192 lines
10 KiB
Markdown
192 lines
10 KiB
Markdown
---
|
||
id: release-crate-docs
|
||
name: Crate docs final pass — rustdoc across the four published crates
|
||
status: completed
|
||
depends_on: []
|
||
scope: moderate
|
||
risk: low
|
||
impact: component
|
||
level: implementation
|
||
tags: [wave-8, docs, rustdoc]
|
||
---
|
||
|
||
## Description
|
||
|
||
The plan's wave-8 "crate docs" item: the public-API rustdoc of the
|
||
four published crates (`alkstore`, `alkstore-sqlite`,
|
||
`alkstore-postgres`, `alkstore-mem`) gets its release pass. The crate
|
||
docs are load-bearing — core's doc text is part of the contract
|
||
artifact (ADR-001 §1; AGENTS.md: "core's docs are part of the
|
||
contract") and the engine crates' lib docs carry the ADR-016 honesty
|
||
postures — so this is an accuracy-and-completeness pass, not prose
|
||
polish.
|
||
|
||
1. **Build clean**: `cargo doc --no-deps` (workspace) zero warnings —
|
||
broken intra-doc links, ambiguous links, missing docs. Also
|
||
`RUSTDOCFLAGS="-D warnings" cargo doc --no-deps` as the recorded
|
||
gate posture.
|
||
2. **Missing-docs audit**: every public item (traits, trait methods,
|
||
types, variants, fields, functions — including the `#[doc(hidden)]`
|
||
re-exports the fuzz wave added at the three engine roots, which
|
||
must stay documented as fuzz/test-only surfaces) carries doc text;
|
||
gaps filled. Consider whether `#![deny(missing_docs)]` (or
|
||
`warn`) is warranted per crate — decide and record; adding it is
|
||
the enforcement posture, skipping it needs a reason.
|
||
3. **Accuracy spot-check against the specs**: core's trait/type doc
|
||
text read against `core-contract.md` (the docs are contract text —
|
||
a drift is a defect); each engine's lib-doc posture claims
|
||
(writer-parking, connection budget, honest-ephemeral, wasm subset)
|
||
read against `deployment.md` and the engine specs. The wave-6
|
||
gate's inline doc fixes are the precedent for the honesty standard.
|
||
4. **Crate-level `//!` docs**: each published crate's root module doc
|
||
names its posture, its ADR charter, and (for engines) its
|
||
deployment boundary — verify all four do, fill what's missing.
|
||
5. **Examples**: core's public surface has no doctest examples; decide
|
||
whether a minimal compile-checked example (a `MemStore` open +
|
||
one mechanism round-trip) belongs in the core or mem crate docs —
|
||
the honest-ephemeral engine is the zero-config one, so it is the
|
||
natural example carrier. Either land it or record the not-taken
|
||
call.
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [x] `cargo doc --no-deps` (workspace) zero warnings; the
|
||
`-D warnings` doc gate posture recorded
|
||
- [x] Missing-docs audit recorded (public items × 4 crates); gaps
|
||
filled; the `#![deny(missing_docs)]` decision made and recorded
|
||
- [x] Core doc text spot-checked against core-contract.md; engine
|
||
lib-doc posture claims spot-checked against deployment.md —
|
||
drifts fixed or recorded
|
||
- [x] The doc-hidden fuzz re-exports documented as fuzz/test-only at
|
||
all three engine roots
|
||
- [x] The example decision made (landed or recorded not-taken)
|
||
- [x] Workspace gates green (`cargo build`, `cargo test`, clippy
|
||
`-D warnings`, fmt)
|
||
|
||
## References
|
||
|
||
- docs/plans/implementation.md §Wave 8
|
||
- docs/architecture/core-contract.md (the contract the core docs must
|
||
match)
|
||
- docs/architecture/deployment.md (the matrix the engine posture docs
|
||
must match)
|
||
- docs/architecture/decisions/016-deployment-honesty.md (the honesty
|
||
carriers)
|
||
- docs/architecture/decisions/024-mem-engine.md §5 (the wasm identity
|
||
the mem crate docs carry)
|
||
|
||
## Notes
|
||
|
||
- **`#![deny(missing_docs)]` decision**: **`#![warn(missing_docs)]`**
|
||
adopted at the four published crate roots instead of deny — with
|
||
rationale: the standing merge gate (`cargo clippy --all-targets --
|
||
-D warnings`) promotes rustc lints to errors anyway, so the lint is
|
||
*enforced* while plain `cargo build`/`cargo test` remain unblocked
|
||
mid-task (a deny attribute fails every build the moment a pub item
|
||
lacks text, punishing incremental work). Recorded as the standing
|
||
posture in AGENTS.md's Verification Commands section alongside the
|
||
doc-gate line.
|
||
- **Doc gate posture recorded**: `RUSTDOCFLAGS="-D warnings" cargo
|
||
doc --no-deps` — zero warnings, added to AGENTS.md's Verification
|
||
Commands block as the doc gate.
|
||
- **Missing-docs audit results** (full-surface probe via
|
||
`RUSTFLAGS='-Wmissing_docs' RUSTDOCFLAGS='-Wmissing_docs' cargo doc
|
||
--no-deps`, probe reports 0 after fixes): every public item across
|
||
the four crates carries doc text. Gaps found and filled: the
|
||
`Error` enum's own doc + its four struct-variant fields
|
||
(`alkstore/src/error.rs`); the sqlite substrate's two fuzz-surface
|
||
functions (`substrate/queue_ops.rs` — their source-side docs had
|
||
never been written; the pg/mem scheduler twins already had them).
|
||
- **Core doc fixes against core-contract.md** (drifts fixed): (1)
|
||
`StreamHandle::trim_to`'s flat "trim emits no wake" corrected to the
|
||
contract's exact row — no *dedicated wake and no notify*, with the
|
||
SQLite `data_version` spurious-hint nuance (a trim commit does wake
|
||
the watcher, contract-legal); (2) the ADR-023 §2 numeric-domain
|
||
rules were missing from every affected method's doc text — added the
|
||
extent rules (`claim_batch`/`read_since`/`read_from_consumer` and
|
||
their tx twins: `n/limit <= 0` → empty value), duration rules
|
||
(`try_lock`/`renew`: `ttl <= 0` rejects, opaque `Err`), the
|
||
boundary-totality rule for `trim_to`'s horizon, and the shared
|
||
domain-rule paragraph (store.rs module doc, per ADR-023 §2's own
|
||
amendment text); (3) the `QueueOpts` "trusted as given" gloss drew
|
||
the wrong criterion (opts-struct constants it names *are*
|
||
trait-surface arguments) — reworded to the domain table's real
|
||
boundary (enumeration by call-site kind); (4) store.rs's
|
||
constructor prose gained the ADR-024 §4 `MemStore::new()` exception
|
||
clause (amended into the contract 2026-10-10).
|
||
- **Engine doc fixes**: (1) "all eleven `*_tx` methods" was an
|
||
off-by-one — the trait carries ten `*_tx` ops plus `commit`;
|
||
reworded in both `alkstore-sqlite/src/tx.rs` and
|
||
`alkstore-postgres/src/tx.rs` module docs; (2) the SQLite
|
||
`spawn_blocking` rationale misstated the driver property (rusqlite
|
||
`Connection` *is* `Send`; the honest reason is that the substrate is
|
||
sync machinery — std threads, blocking iterators) — reworded in
|
||
`alkstore-sqlite/src/lib.rs` + `store.rs` per engine-sqlite.md; (3)
|
||
the SQLite lib doc gained the missing third element of ADR-016 §3's
|
||
mandated single-host prose — one-host cross-process *supported*
|
||
(`data_version` is cross-process by nature), matching deployment.md;
|
||
(4) cosmetic: a malformed doc-comment indent line on `PgOpts::max_size`.
|
||
- **Spec-side alignments** (code docs + ADR win, spec aligned to
|
||
match): `docs/architecture/engine-postgres.md` now lists `locks` in
|
||
the schema-family enumeration and rewords "advisory-lock-semantics
|
||
TTL locks" to the ADR-008 §7 row-backed realization;
|
||
`docs/architecture/engine-mem.md` gained the one-clock-accessor line
|
||
(no server clock to defer to) that the mem lib doc's wasm identity
|
||
and `clock.rs` already cited — the claim now has its spec home.
|
||
- **Recorded, not fixed — two boundary-wording drifts for
|
||
`release-contract-window-close`** (the task that owns the class-1
|
||
window's last dispositions): (1) `EventReceiver::try_recv`'s error
|
||
arms (`Database` or `Closed`) are claimed in core doc text but not
|
||
yet pinned in contract text — that task's §2 already decides
|
||
`Err(Closed)` mirroring `WakeReceiver::try_recv` (mem-test-pinned),
|
||
so the doc text is a forward-claim of the decided disposition, left
|
||
as-is; (2) the notify payload boundary: ADR-004/core-contract say
|
||
"≤ 8000 bytes" loosely, but the engine (POC + test-pinned against a
|
||
live server) rejects a serialization of exactly 8000 bytes — the
|
||
server's NUL-inclusive budget — so acceptance is ≤ 7999; the pg
|
||
engine's docs state the truthful predicate; a normative-spec
|
||
wording amendment is the window task's call.
|
||
- **Example decision: landed** — the honest-ephemeral engine is the
|
||
zero-config one, so `alkstore-mem`'s crate docs now carry the
|
||
contract round-trip example (a compile-checked doctest:
|
||
`MemStore::new()` → `queue` → `enqueue` → `claim_one` →
|
||
`job().id`/`JobState` asserts), with a pointer that the other
|
||
engines' round-trip is identical via their `open` form. The mem
|
||
lib's architecture paragraph dropped its `crate::state`/`crate::wakes`
|
||
intra-doc links (private modules — the private-intra-doc-link
|
||
warning class) in favor of plain code spans.
|
||
- **Fuzz re-exports (AC 4)**: verified all six `#[doc(hidden)]`
|
||
re-exports at the three engine roots carry the four-part
|
||
fuzz/test-only disclosure, name the correct module of origin, and
|
||
match the re-exported function's semantics — no changes needed.
|
||
|
||
- Status of record: 2026-10-11, gates green (`cargo build`, `cargo
|
||
test` incl. the new doctest, `cargo clippy --all-targets -- -D
|
||
warnings`, `cargo fmt --check`, `RUSTDOCFLAGS="-D warnings" cargo
|
||
doc --no-deps`, missing-docs probe 0).
|
||
|
||
## Summary
|
||
|
||
The release doc pass over the four published crates: `RUSTDOCFLAGS="-D
|
||
warnings" cargo doc --no-deps` is now the standing doc gate (recorded
|
||
in AGENTS.md) and the workspace builds docs with zero warnings (8
|
||
baseline rustdoc-warning classes fixed: broken `Error::*` links,
|
||
redundant explicit links, bracket-escape escapes, and a
|
||
private-intra-doc link). The `#![warn(missing_docs)]` enforcement
|
||
posture landed on all four crate roots (clippy gate enforces);
|
||
audit-probe reports zero undocumented public items after filling the
|
||
`Error` enum/field docs and the sqlite substrate's fuzz-surface fn
|
||
docs. Accuracy spot-checks ran core docs against core-contract.md and
|
||
engine lib-doc posture claims against deployment.md/ADR-016/ADR-024:
|
||
eight drifts fixed (trim_to wake nuance, the full ADR-023 §2
|
||
numeric-domain doc text + shared paragraph, the QueueOpts gloss, the
|
||
`MemStore::new()` constructor exception, the eleven-vs-ten tx-method
|
||
count, the SQLite `Send`-misstatement rationale, the missing
|
||
one-host-cross-process honesty element, a cosmetic indent), two
|
||
spec-side alignments made (pg locks table family + row-backed
|
||
wording; mem clock-accessor spec home), and two boundary-wording
|
||
dispositions recorded for `release-contract-window-close`
|
||
(`try_recv` arm pinning; the 8000-byte boundary's "≤" reading). The
|
||
example decision landed: alkstore-mem's crate docs carry the
|
||
zero-config queue round-trip doctest (green in the workspace test
|
||
run). All workspace gates re-verified green. |