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

To be filled by implementation agent

Summary

To be filled on completion