alkblobs/tasks/crate-docs.md

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

id	name	status	depends_on	scope	risk	impact	level
crate-docs	Crate-root docs and the public-API rustdoc pass	completed	unicode-hygiene	moderate	low	component	implementation

Description

The crate-root //! docs, deferred here by wave 8 ("release readiness owns crate docs"), plus the public-API rustdoc pass. src/lib.rs currently opens directly with pub mod lines — no crate-level doc exists.

Write the crate-level doc as contract text (the plan's words: "the facade's docs are contract text"): what the crate is (content-addressed blob storage; the canonical hash is the git-family derivation per ADR-002), the layer map (the Store facade over the kv/large tiers; engine modules behind features; the ops feature riding alkcall), the substrate-agnostic posture (convention 4 — the store never knows where bytes came from), the constructor modes, and the pointer to docs/architecture/ as the spec/ADR record. Keep it honest and lean — an orientation, not a second README.

Then the public-API pass:

• cargo doc --no-deps and cargo doc --no-deps --all-features warning-free (currently clean — keep it that way; the new crate doc and any doc-comment touch-ups must not introduce warnings).
• Intra-doc links resolve (the crate doc linking modules/types is the natural place to verify).
• Spot-audit the public surface for contract-grade docs: the facade types (Store, StoreMode, EntryMeta, Pin/Batch, SweepReport, GcAbortCause, PinState), Digest/Key/Algorithm, the error enum, the feature-gated modules' public items (mem, pg_lo, postgres, sqlite, ops re-exports). Gaps found get filled; the facade's existing docs are the bar, not a rewrite.
• The #[doc(hidden)] fuzz surface keeps its honest not-contract wording (lib.rs lines 42-49) — verify it still reads correctly.

No API changes, no behavior changes — docs only.

Acceptance Criteria

• src/lib.rs carries crate-level docs (purpose, layer map, feature graph, constructor modes, architecture-docs pointer)
• cargo doc --no-deps and cargo doc --no-deps --all-features warning-free
• Intra-doc links in the new crate doc resolve (no broken-link warnings)
• Public-surface spot-audit done; gaps filled; facade docs read as contract text
• Full verification block green (docs-only diff, but the block is the block)

References

• docs/plans/implementation.md wave 8 ("The crate-root //! docs stay wave 12's") and wave 12 ("Crate docs … the facade's docs are contract text")
• docs/architecture/store-api.md, overview.md (the contract text the crate doc orients against)
• src/lib.rs (the current state), src/store/mod.rs (the facade's existing doc standard)

Notes

Filled by implementation agent (2026-10-16).

The "currently clean" premise was stale in one place: at HEAD, cargo doc --no-deps --all-features emitted 33 warnings - pre-existing intra-doc links from public docs to crate-private items (across pg_lo, postgres, pg_common). Making the doc pass warning-free is this task's own acceptance criterion and docs-only, so those were fixed in the same pass: public-doc links to private items reified to plain backticks (pg_lo/mod.rs, pg_lo/windows.rs, pg_lo/staging.rs, postgres/mod.rs, postgres/cas.rs, pg_common.rs). Doc content in those files otherwise untouched (link syntax only). The default-build doc pass was clean and stayed clean.

The missing_docs lint under RUSTFLAGS flags exactly one gap: the crate itself. All public items already carry module/type/verb docs, and the spot-audit found them contract-grade (sampled: Store/StoreMode/ EntryMeta/Blob/Pin/Batch/SweepReport/GcAbortCause/PinState, Digest/Key/Algorithm, the Error enum's one-enum-both-altitudes notes, the mem/sqlite/local/ops module docs, the ops re-export types and wire-error constants) - no gaps filled beyond the crate doc. The #[doc(hidden)] fuzz surface's honesty wording (now lib.rs:104-111 after the crate doc insert) verified unchanged and correct.

Summary

Filled on completion.

Crate-root //! docs written in src/lib.rs as contract text: what the crate is (content-addressed blob storage, the canonical hash is the git-family derivation per ADR-002), the layer map (Store facade, engine modules with their features, ops riding alkcall, the types' homes), the substrate-agnostic posture, the named-constructor model (no new), and the architecture-docs pointer with the specs-win rule. Intra-doc links resolve in both doc configurations (feature-gated modules deliberately backticked, not hyper-linked, so the default-build pass stays link-clean).

Verification: cargo doc --no-deps and --all-features warning-free (33 pre-existing private-item link warnings fixed), cargo test (207 pass), cargo test --all-features (457 pass, pg columns skip clean), both clippy gates, fuzz corpus-replay gate (7 pass), cargo fmt --check

• all green. Docs-only diff: src/lib.rs plus the six files listed above.