alkblobs/tasks/review-wave-12.md

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

id	name	status	depends_on	scope	risk	impact	level
review-wave-12	Wave 12 review — the pre-release gate	completed	unicode-hygiene docs-consistency-review crate-docs feature-graph-verification changelog-and-readme publish-prep	moderate	low	project	review

Description

The wave-12 review gate — the plan's pre-release gate, the last gate before the crate is publishable. Reads the wave's diffs against the plan's wave-12 charter and the family precedent, and flips the release-facing lifecycle.

The gate's checks (per docs/plans/implementation.md wave 12):

• Docs honesty audit — README, CHANGELOG, and the crate-level docs claim only what's shipped; the quick-start examples compile; the feature/engine tables match ADR-013 §4 and the constructor surface; the facade docs read as contract text.
• Feature-graph verification re-run — the matrix recorded by feature-graph-verification re-run (or spot-verified with the full block) and green.
• All gates green — the full AGENTS verification block: cargo test, cargo test --all-features, both clippy variants, cargo fmt --check, cargo doc --no-deps, and the fuzz corpus-replay gate (cargo test --manifest-path fuzz/shared/Cargo.toml).
• Publish readiness — cargo publish --dry-run --allow-dirty green; the packaged file list clean.
• The lifecycle flip — release-facing specs move draft → stable ("stable when implementation verifies against it" — the lifecycle line in docs/architecture/README.md; eleven waves of implementation is that verification). The specs: overview, requirements, hashing-and-keys, store-api, backends-and-dispatch, gc-and-namespaces, ops-surface. Externally-owned OQ-07/OQ-08 gate nothing by definition. The architecture README's table and last_updated move with them; open-questions.md stays draft-status as a living tracker unless the sweep says otherwise.
• The plan stamp — wave 12 marked completed in docs/plans/implementation.md (wave table + the wave-12 record).

Acceptance Criteria

• Docs honesty audit passed (README/CHANGELOG/crate docs vs shipped reality; examples compile)
• Feature-graph matrix green (re-run or verified from the recorded results plus the full block)
• Full verification block green, including the fuzz corpus-replay gate
• cargo publish --dry-run --allow-dirty green
• Release-facing specs flipped stable with dated notes; the architecture README table updated
• docs/plans/implementation.md wave 12 stamped completed
• Any residue named (post-release observations get a home, not a shrug)

References

• docs/plans/implementation.md (wave 12 charter; review gates section)
• docs/architecture/README.md (the Lifecycle section — the flip's rule)
• AGENTS.md (the verification block)

Notes

Diff read across the wave's six commits (0fb451f, 0592d8a, 157f10f, bc2f4f1, 825b0e3, 81c7273): all six are within their charters — unicode sweep verifiably complete (git grep -nP '[\x{2013}\x{00D7}\x{2228}]' over tracked files: empty), the crate docs and the no-kv-feature build fix land as described, the consistency pass's residue has its named home (tasks/n-cleanup-residue.md), and the manifest audit matches the packaged reality.

Two inline findings, both fixed in this session:

1. The recorded feature matrix was invalidated by a later wave-12 commit (review's matrix re-run caught it): tests/readme_examples.rs landed in changelog-and-readme (825b0e3) after feature-graph-verification (157f10f) recorded its matrix, and the test file used Store::mem_only / Store::dual_tier_sqlite_local unconditionally — breaking, with E0599, every no-sqlite/no-mem matrix row (pg-pure, pg-lo, postgres+pg-lo, mem-only, local-only, mem+ops on the sqlite-only constructor). Exactly the co-occurrence class the feature-graph pass exists to catch, arriving after the pass. Fix: each fence in tests/readme_examples.rs is now feature-gated to the constructor it exercises (mem, sqlite, postgres), with per-function imports — the same gate the constructor carries, so the file compiles on every matrix build. All six broken rows re-run green.

2. The README pg quick-start row failed instead of skipping server-less (surfaced during the row re-runs): it defaulted ALKBLOBS_PG_HOST to localhost:5432 and connected rather than skipping — diverging from the conformance columns' harness convention (AGENTS.md's skip-cleanly posture; the operator's note that server-less runs "skip cleanly... or were and should"). Fix: the row now gates on ALKBLOBS_PG_HOST set and non-empty (skip note to stderr, same shape as the conformance columns') and defaults port/user/password/db to the harness values (15432/postgres/poc/ blobs — the 5432 default was also wrong for the container).

One drift miss caught from the docs-consistency pass: AGENTS.md's Architecture Context bullet still read "Phase 1 in progress: specs draft, ADRs 001-006 accepted" (the pass updated the top status line but missed this one). Fixed inline.

Residue: none new. The pre-existing named remainder lives in tasks/n-cleanup-residue.md; everything the gate found it could fix inline, it fixed inline.

Summary

Completed 2026-10-16. The gate is green and the lifecycle flipped.

• Docs honesty audit — pass. README/CHANGELOG/crate docs claim only what's shipped; the README's feature table matches ADR-013 §4 (mem default-on amendment included) and the manifest's feature graph; the engine table matches backends-and-dispatch/ADR-013; the quick-start fences compile and run via tests/readme_examples.rs (2 default / 3 with postgres, against the live harness).
• Feature matrix re-run — pass. All six no-default matrix rows re-run green after the readme_examples fix above (rows 5-10 of the recorded 12-row matrix); the full block below re-proves rows 1-4.
• Full verification block (live pglo-poc harness, env per AGENTS.md): cargo test green (149 lib + 54 conformance + 4 git-interop + 2 README examples); cargo test --all-features green (328 + 125 + 4 + 3 — the pg columns ran, not skipped); both clippy configs clean under -D warnings; cargo fmt --check clean; cargo doc --no-deps zero warnings in both feature configs; the fuzz corpus-replay gate green (7/7).
• Publish readiness — cargo publish --dry-run --allow-dirty green (92 files, 2.4MiB, matching the publish-prep record). Not publishing: the first consumer's review pass comes first, by operator decision.
• The lifecycle flip — the seven release-facing specs (overview, requirements, hashing-and-keys, store-api, backends-and-dispatch, gc-and-namespaces, ops-surface) flipped stable with the dated gate note in each frontmatter (last_updated, preserved notes kept); open-questions.md stays draft as the living tracker. docs/architecture/README.md: table updated, Current State + frontmatter moved to wave-12-completed, and the Lifecycle section's closing line updated ("in draft pending the first architecture review cycle" → the 2026-10-16 stable flip, eleven waves of implementation being that verification).
• The plan stamp — wave 12 marked completed in the implementation plan's wave table; AGENTS.md's status moved to "Phase 1 complete — release-ready, pre-publish" (including the stale Architecture Context bullet above).