alkstore/tasks/release-crate-docs.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
release-crate-docs	Crate docs final pass — rustdoc across the four published crates	completed		moderate	low	component	implementation	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

• cargo doc --no-deps (workspace) zero warnings; the -D warnings doc gate posture recorded
• Missing-docs audit recorded (public items × 4 crates); gaps filled; the #![deny(missing_docs)] decision made and recorded
• Core doc text spot-checked against core-contract.md; engine lib-doc posture claims spot-checked against deployment.md — drifts fixed or recorded
• The doc-hidden fuzz re-exports documented as fuzz/test-only at all three engine roots
• The example decision made (landed or recorded not-taken)
• 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.