--- id: review-wave-8 name: Review gate — wave 8 (release readiness) status: completed depends_on: [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] scope: broad risk: low impact: project level: review tags: [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 `.crate`s — 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 - [x] Docs honesty audit recorded (README traces, matrix rows, crate docs, env boundary) - [x] Contract-window closure audited; the class-1 termination record landed; no undisposed class-1 candidate remains - [x] N-1 + Findings 2–3 dispositions audited as decisions of record - [x] Flake-watch outcome audited; any follow-up task's blocking status stated explicitly - [x] Publish-prep audit recorded (package evidence + exclusion re-run + checklist complete) - [x] Frontmatter parse sweep + renumber-sweep spot-check green - [x] All gates re-run green this session (incl. fuzz replay + wasm + doc gates) - [x] 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.