alkstore/tasks/review-wave-8.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
review-wave-8	Review gate — wave 8 (release readiness)	completed	docs-frontmatter-cleanup release-renumber-sweep release-crate-docs release-contract-window-close release-n1-growth-posture release-findings-2-3-disposition release-flake-investigation release-deployment-matrix release-readme release-publish-prep	broad	low	project	review	wave-8 review-gate

Description

The wave-8 review gate (the plan's §Review gates pattern; the pre-release gate). Audit the release-readiness pass as landed:

1. Docs honesty audit: the README's claims traced to specs (the readme task's trace list re-verified by spot-read); the deployment matrix's rows read true as implemented across the three engines; the crate docs' posture claims consistent with the matrix; the env-boundary sentence present and the grep result current.
2. Contract-window closure audit: every wave-6 recorded observation disposed (wake-ordering decision landed per the user's call; the ADR-023 §2 classifications; the try_recv shape; the get_job prose; the mem-arithmetic disposition); every landed amendment dated + cited; the class-1 window's termination recorded — ADR-017 §2's "terminates permanently at the core crate's first release" becomes a fact at this gate: the record states the window closes with the first publish, and no undisposed class-1 candidate remains.
3. N-1 + Findings 2–3 dispositions audited: the growth-posture acceptance is a decision of record (not a shrug); the findings' landed-vs-parked dispositions recorded so the inventory is closed.
4. Flake-watch outcome audited: the investigation's conditions matrix + disposition read; if a follow-up fix task was created, its status is visible (a live engine bug blocks the release blessing — the gate says so explicitly rather than publishing over it).
5. Publish-prep audit: cargo package evidence per crate; the exclusion verification re-run this session (file lists of the built .crates — no fuzz/sidecar/suite leakage); the publish checklist of record complete and mechanical.
6. Frontmatter + records hygiene: the parse sweep re-run (zero invalid frontmatters under docs/); the renumber sweep's disposition list spot-checked (stale wave-7 references gone or annotated; genuine fuzz-wave references intact).
7. All gates re-run green this session: cargo build, cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check, the fuzz corpus-replay gate, the wasm32 check, and the doc gate (cargo doc --no-deps warning-free).
8. Spec flips + records: the remaining draft architecture docs (core-contract.md, overview.md, queues.md, deployment.md, the architecture README) flip to stable with dated gate annotations — the release-facing spec set is stable at the gate, mirroring the wave-5/6 engine-spec flips; docs/architecture/README.md's Current State refreshed (waves 6–8); implementation.md's wave-8 row updated + a review-rounds entry; task files audited (all wave-8 dependencies completed, Notes/Summary filled).

Acceptance Criteria

• Docs honesty audit recorded (README traces, matrix rows, crate docs, env boundary)
• Contract-window closure audited; the class-1 termination record landed; no undisposed class-1 candidate remains
• N-1 + Findings 2–3 dispositions audited as decisions of record
• Flake-watch outcome audited; any follow-up task's blocking status stated explicitly
• Publish-prep audit recorded (package evidence + exclusion re-run + checklist complete)
• Frontmatter parse sweep + renumber-sweep spot-check green
• All gates re-run green this session (incl. fuzz replay + wasm + doc gates)
• Spec flips + records landed; implementation.md updated; task files audited

References

• docs/plans/implementation.md §Wave 8, §Review gates
• docs/architecture/decisions/017-contract-versioning.md §2 (the window termination this gate records)
• tasks/review-wave-5.md §Notes 6 (the flake ledger)
• tasks/review-wave-6.md §Recorded findings (the dispositions this gate audits)
• tasks/review-wave-7.md (the parked exclusion verification)
• tasks/review-wave-5.md / tasks/review-wave-6.md (the gate pattern)

Notes

Gate verdict: passed. One finding found and fixed at the gate (a pg engine divergence from the close-out pass's ADR-023 §2 annotation); no blocker, no major live defect. Every audit item was re-verified by this session's own runs/reads, not by trusting the implementing tasks' self-reports.

1. Docs honesty audit — recorded

• README: the trace list (release-readme §Notes) spot-read — the seven-mechanism list against core-contract.md §Mechanism contracts, the engine posture lines against deployment.md §Host semantics + §TLS posture, mem's wasm/ephemeral lines against ADR-024 §2/§5, the license note against the workspace license field + ADR-018. Every claim has a spec source; the usage sketch was compile-checked and executed from a scratch crate with path deps (the mem round-trip mirrors the lib-doc doctest cargo test re-verifies — green in this session's run). No aspirational or unshipped claims found.
• Deployment matrix: rows read true as implemented across the three engines (the full text of release-deployment-matrix's five corrections — the consumer-side FULL claim false-as-implemented, the three-guard list, the NFS re-citation, the unsourced mem latency number replaced — present in the final text; the env-boundary §Configuration boundary sentence present; no internal task/wave pointers remain in the release-facing text — re-read this session). Spot-checks against code: synchronous = NORMAL at bootstrap, poll_interval 1 ms default, NoTls on every pg path, max_size 0 rejected — all match the text.
• Crate docs: the four published crates' lib-doc posture claims read against deployment.md/the engine specs — the sqlite single-host/one-host-cross-process, pg's max_size + 1 budget + NoTls v1, mem's honest-ephemeral/wasm identity all consistent with the matrix. Doc gate green (RUSTDOCFLAGS="-D warnings" cargo doc --no-deps, zero warnings this session).
• Env boundary: the grep re-run this session — 40 env::var reads, all inside the pg test modules' DSN plumbing; production paths env-free. The matrix's "grep re-verified across the workspace at release" sentence is current.

2. Contract-window closure audit — recorded

• All five wave-6 recorded observations verified disposed with dated in-place citations: the publish→wake ordering tolerance (core-contract.md streams tolerance paragraph + the delivery-guarantee obligations bullet + ADR-015 §4's companion annotation; the user declined the enforced-guarantee amendment — the documented-tolerance posture was the user's call, recorded in the task's Notes); the ADR-023 §2 heartbeat(extend)/save_offset classifications (boundary/offset row annotated, core-contract numeric-domain paragraph mirrored); the EventReceiver::try_recv closed shape (ADR-021 §5 dated annotation); the get_job prose (core-contract + queues.md now say the uniform id-global / tx-filtered split); the mem-arithmetic no-action disposition (task Notes, explicit).
• The registered suite-duty follow-up — audited, and landed at the gate (the close-out pass deferred it to "the review-wave-8 gate owns the audit"): no suite leg pinned the two new classifications. In the audit read of pg's implementation, a real divergence surfaced: pg's negative-seed clamp contradicted the ADR-023 §2 annotation — pg's offsets-table CHECK ("offset" >= 0) + the GREATEST($3, 0) upsert clamped a fresh consumer's negative save_offset to 0, where SQLite and mem store the raw negative and the annotation pins "a negative is stored as the checkpoint" (get_offset observable: −5 vs 0, the only read that distinguishes; below-checkpoint saves, monotone no-ops, and reads-resume-forward were uniform). Per AGENTS.md's ADR-wins discipline, the pg code was fixed: raw seed, CHECK dropped, doc comments updated (the window is open until first publish — legal; no published consumer exists). Suite legs then landed: the negative-heartbeat(extend) leg in job_handle_validity_predicate (heartbeat lands true while unexpired; the voided claim refuses ack through the validity predicate; the row survives as processing) and the negative-save_offset seed leg in receiver_close_and_save_arms (fresh-consumer seed stored raw; read_from_consumer resumes forward from the anchor) — both stamped with the ADR-023 §2 (annotated 2026-10-11) accumulation per version_stamp.rs convention; green on all three columns against the live pg server (and core-contract.md's numeric-domain backlog row updated to name the landed legs). The close-out task's "code read verified the uniform shapes" claim was right on acceptance/monotonicity and wrong on the stored seed value through pg's clamp — corrected here.
• The class-1 termination record landed: ADR-017 §2's class-1 bullet now carries the dated termination-of-record annotation (2026-10-11, the wave-8 gate): the close-out pass landed every recorded disposition, the gate audited no undisposed class-1 candidate remains (grep across docs/tasks for parked window candidates — none; the surviving "class-1 window open/open at time of writing" phrases are historical ADR texts), and the class terminates permanently at the core crate's first cargo publish — the 0.1.0 release this gate blesses (§1's 2026-10-11 amendment; contract changes thereafter are classes 2–4 only).

3. N-1 + Findings 2–3 dispositions — audited as decisions of record

• N-1: the conscious acceptance is a decision of record with a per-engine, per-path rationale table (deployment.md §Growth postures), made against the implemented engines' code (the task's re-read verified each path: sweep-on-call-only retention, the at-attach-only prune, consumer-invoked trim_to; mem's process-lifetime-bounded postures recorded structurally). The notify prune-cadence note landed in engine-sqlite.md §Notifications-table hygiene, anchored and linked from the matrix. Not a shrug; recorded and folded.
• Findings 2–3: 2(a) and 3 landed as seam tests (the pg generation-top LISTEN-pause arm with the exactly-one-wake differentiator, replay-proofed both ways; the SQLite rollback-fault two-drop-arm test via the rollback_fault seam), and 2(b) + the defensive arms' parked dispositions are recorded with current line refs, reach reasons, and the tested-elsewhere coverage each overlaps — the inventory reads closed, not re-derivable. Gates green per the task's record; both engines' suites green this session.

4. Flake-watch outcome — audited

• The fired lock-row trigger was investigated per the ledger's prescription (instrumentation first — the tee-before-filter capture procedure demonstrated on a deliberately-failing probe; the conditions matrix run, 48+ rounds; the second-precision arithmetic read against lock.rs/resolution.rs with the delay-only argument confirmed for the lapse legs and corrected for the contention leg; mechanism probes + natural repro captured, 2/30 loaded solo runs, exact message at the exact site). Disposition: reproduced; root cause harness-model — the row's contention leg wrote ttl = 1 into a live-TTL assertion second-precision stamps collapse below a second; the engine acted per ADR-008 §7 at every step. Fixed test-side in-session (the two-leg row: long-TTL exclusion leg, short-TTL lapse leg); 30/30 loaded verification green; the three columns green. No live engine bug — nothing blocks the release blessing.
• Post-investigation watch posture: the lock row's flag retires; the trim row stays watch-flagged (no repro in this session's rounds) and one new single-occurrence observation (row_stream_ordering_equivalence under 8-CPU-burner synthetic load — a drain-window scheduling lottery, message captured, no ordering violation) is recorded in the ledger dated 2026-10-11. Their stated status: watch continues, no ride-along fix, instrumentation first; neither reproduces under dev/gate conditions. Recorded; not blocking.

5. Publish-prep audit — recorded

• Package evidence, fresh this session: cargo package -p alkstore — packaged 30 files + verification build green; the .crate inspection shows LICENSE-MIT/LICENSE-APACHE at the tarball root, README, normalized manifest, no stray paths. The engines' registry-side verification remains correctly blocked pre-core-publish (re-captured this session with --allow-dirty: no matching package named 'alkstore' found … searched: crates.io index); their evidence stands on the reconstructed exact-list trees of record (all green, the publish-shaped manifests).
• Exclusion verification re-run this session: fresh cargo package --list for all four crates — alkstore 30 files, sqlite 36, postgres 31, mem 23; zero fuzz//sidecar/corpora paths or alkstore-fuzz-shared references in any list; the engine packages' src/fuzz_surface_tests.rs + tests/contract_suite.rs riders are the documented crate-internal probe tests and dev-dep suite target, not sidecar leakage; the suite appears in no [dependencies]; the workspace exclude = ["fuzz"] holds.
• Substrate packaging: src/substrate/PROVENANCE.md + src/substrate/LICENSE confirmed in the alkstore-sqlite list; the crate README documents the carriers.
• Path-dep bounds + metadata: alkstore = { version = "0.1", path = … } verified on all three engines + the suite dep; descriptions/readmes wired per crate; keywords/categories landed; homepage/documentation omitted per family precedent; ADR-017 §1's 0.1.0 amendment dated + cited. The manual publish checklist of record is complete (release-publish-prep §Notes — core first, then engines, gates → package → eyeball → publish, tag v0.1.0); publishing is the user's post-gate action. The one mechanical note: run the checklist from the committed, clean tree (cargo package refuses dirty trees).

6. Frontmatter + records hygiene — re-run green

• The PyYAML parse sweep re-run exactly as recorded (docs-frontmatter-cleanup's command, both globs): 0 failures across docs/**/*.md + tasks/*.md.
• The renumber sweep spot-check: re-grepped wave 7|wave-7 across docs/reviews/ + tasks/ — every non-fuzz hit carries its wave-8 annotation (001 header, 002 security bullet, 003 echo + trail, review-wave-5's three sites, review-wave-6's three, review-wave-4's gate record, pg-fix-scheduler-fire-wake's ledger note); genuine fuzz-wave/review-7 references intact; taskgraph validate green (79 tasks).

7. All gates re-run green this session

• cargo build — clean.
• cargo test --workspace — all green server-less (core 25 + 1 lib-test target, suite harness 3, mem 102 lib + 25 suite + 1 doctest, sqlite 193 + 25, pg 127 lib (SKIP posture) + 25 + 9).
• Live pg column against the harness server (pglo-poc): 127 + 25 + 9, all green (this session, post-fix — the run that verified the pg seed-divergence fix and the new suite legs).
• cargo clippy --all-targets -- -D warnings — clean.
• cargo fmt --check — clean.
• Fuzz corpus replay (cargo test --manifest-path fuzz/shared/Cargo.toml) — 6/6 green.
• cargo check --target wasm32-unknown-unknown -p alkstore-mem — clean.
• Doc gate (RUSTDOCFLAGS="-D warnings" cargo doc --no-deps) — zero warnings.

8. Spec flips + records — landed this gate

• Flipped stable with dated gate annotations: core-contract.md, overview.md, queues.md, deployment.md (already stable from the matrix pass — annotation current), the architecture README. The engine specs' engine-mem.md row in the README's doc table corrected (it still read draft; the wave-6 gate flipped the spec). open-questions.md stays draft deliberately — it is the OQ tracker, whose lifecycle is separate from the spec set (noted in the README table's row); the doc set this gate freezes is the release-facing spec set.
• docs/architecture/README.md: Current State refreshed (waves 1–8, the pre-release gate passed, the window's termination stated).
• implementation.md: wave-8 row → implemented + reviewed (2026-10-11); frontmatter annotation updated; the review-rounds entry appended.
• Task files audited: all ten wave-8 dependencies completed with Notes/Summary filled; two of their AC checklists (release-contract-window-close, release-readme) were left unticked despite the work + records being complete — ticked at this gate; no placeholder residue remains in the wave-8 task set.

Findings summary

#	Severity	Finding	Disposition
1	LOW (contract-observable)	pg's negative-seed clamp (GREATEST(offset, 0) + the offsets CHECK) diverged from ADR-023 §2's 2026-10-11 "a negative is stored as the checkpoint" annotation on get_offset	Fixed engine-side at the gate (raw seed, CHECK dropped; window open until first publish); suite legs landed uniformly (three columns green); backlog row updated
2	INFO	The close-out pass's "uniform shapes" verification missed the clamp (acceptance was verified; the stored seed value was not)	Corrected by the fix above; recorded here for the record's honesty
3	INFO	The 2026-10-11 row_stream_ordering_equivalence load observation (from release-flake-investigation §F6)	Watch-flagged in the ledger, carries post-release; no ride-along fix, instrumentation first; single occurrence under synthetic load beyond dev/gate conditions — not blocking

Summary

Gate passed 2026-10-11. The pre-release pass audited clean on every axis and one contract-observable divergence surfaced and was fixed: pg's negative-seed clamp contradicted the ADR-023 §2 close-out annotation, resolved engine-side (raw seed, no CHECK), with the registered suite-duty follow-up discharged — the negative-heartbeat(extend) and negative-save_offset legs landed, stamped, and green on all three columns (pg verified against the live harness server). The class-1 termination of record landed in ADR-017 §2: every recorded disposition is dated + cited, no undisposed candidate remains, and the window terminates permanently at the core crate's first cargo publish — the 0.1.0 this gate blesses. N-1's acceptance and Findings 2–3's dispositions are decisions of record; the flake investigation's outcome is a harness-model root cause, test-side fixed, watch retired, with the remaining watch items recorded and non-blocking. Publish prep verified fresh (package evidence, exclusion re-run clean, the manual checklist of record standing); the frontmatter and renumber hygiene sweeps re-ran green; all gates re-run green this session (build, workspace tests, live-pg suite, clippy, fmt, fuzz replay, wasm32, doc gate). The release-facing spec set — core-contract.md, overview.md, queues.md, deployment.md, the architecture README — is flipped stable; engine-mem.md's README-table row corrected to match its wave-6 flip; implementation.md's records updated; open-questions.md stays the draft tracker by intent. Implementation is complete; the release itself is the user's manual publish session.