---
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.