---
id: release-crate-docs
name: Crate docs final pass — rustdoc across the four published crates
status: pending
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

- [ ] `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

> To be filled by implementation agent

## Summary

> To be filled on completion