354 lines
19 KiB
Markdown
354 lines
19 KiB
Markdown
---
|
||
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. |