alkstore/tasks/review-wave-5.md

---
id: review-wave-5
name: Wave 5 review gate — the suite as compatibility instrument
status: completed
depends_on: [suite-queue-depth-rows, suite-scheduler-rows, suite-tx-commit-atomicity-rows, suite-stream-rows, suite-lock-rows, suite-wake-rows, suite-opts-backoff-rows, sqlite-commit-error-arm, pg-suite-infra-hardening]
scope: broad
risk: low
impact: project
level: review
tags: [wave-5, review-gate]
---

## Description

The wave-5 review gate (docs/plans/implementation.md §Review gates):
"the suite as compatibility instrument — every backlog row present,
version-stamped, green on both engines; this is the gate that flips
the engine specs to `stable`."

Primary lenses:

1. **Backlog audit — every row present.** Walk
   core-contract.md §Verification backlog item by item against the
   suite (and the engine-side pins for the SQLite-scoped rows) and
   record the discharge map. The decomposition's audit (below) is the
   starting point — verify each "discharged" claim by reading the
   pinning row/test, not by trusting the map.
2. **Version stamps.** Every row's `Contract stamp:` items cite ADR §
   per `version_stamp.rs`'s convention; stamps accumulate on
   amendment (the extended `enqueue_opts_resolution` row is the
   amendment case to check); greppable via `STAMP_MARKER`. Cross-check
   against ADR-017 §2's no-silent-change discipline: every stamp's
   cited ADR § actually pins the behavior tested.
3. **Green on both engines.** The SQLite column green server-less;
   the pg column green against the harness server (twice, the
   wave-4 gate's posture). Workspace gates green
   (build/test/clippy/fmt).
4. **Dispositions audited.** The decomposition parked several
   judgment calls in task Notes — verify each was made and recorded:
   the M-1 retention-failure pin's location (suite row vs engine-side),
   the beyond-64 skip-forward leg's location, the backoff cap leg's
   location, the scheduler fire-wake parity call, the lock-row
   divergence call (if any), the SQLite reconnect-success test
   taken/not-taken.
5. **Conformance spot-checks.** The rows assert what the ADR text
   pins (no weaker, no stronger — a row pinning beyond the ADR text
   is a suite defect: it would fail a correct engine); the
   determinism posture holds (tolerance-bounded state assertions
   only, no timing-value asserts, no two-task races) including the
   scheduler rows' documented posture extension; no duplication
   between rows' legs.
6. **Flip the engine specs to `stable`** — `engine-sqlite.md` and
   `engine-postgres.md` frontmatter `status: draft` → `status:
   stable`, with dated `last_updated` annotations citing this gate.
   Update `docs/plans/implementation.md`: the wave table's wave-5
   status, a review-rounds entry for this gate.

## Acceptance Criteria

- [x] Backlog discharge map recorded (every §Verification backlog item
      → its pinning row/test or an explicit gap with a disposition)
- [x] Every row version-stamped per convention; amendment stamps
      accumulated; stamps verified against the cited ADR text
- [x] Suite green on both engines (SQLite server-less; pg vs harness,
      two consecutive full runs); workspace gates green
- [x] All parked dispositions from the wave-5 tasks audited and
      recorded
- [x] Engine specs flipped to `stable` with dated annotations;
      implementation.md updated (wave table + review rounds)
- [x] Findings recorded; the next decomposition may proceed
      (release readiness at gate time — since renumbered to wave 7
      when the mem engine inserted at wave 6, ADR-024; wave 8 since
      the fuzzing wave's renumber, 2026-10-10)

## References

- docs/plans/implementation.md §Review gates (wave 5), §The waves
- docs/architecture/core-contract.md §Verification backlog
- docs/architecture/decisions/017-contract-versioning.md §4.2
- docs/architecture/decisions/022-contract-suite-layout.md
- alkstore-contract-suite/src/version_stamp.rs (the stamp convention)

## Notes

> Audit of record for the gate (2026-10-10). Every claim below was
> verified by reading the pinning row/test, not by trusting the
> appendix map or the implementing tasks' self-reports.

**1. Backlog audit — the discharge map, verified.** All 25 mechanism
rows per engine column were read in full
(`alkstore-contract-suite/src/properties.rs`, 3344 lines) against the
backlog text in `core-contract.md` §Verification backlog. Findings:

- Every row of the appendix's first table is genuinely discharged by
  the named row: name validation + `schedule()` queue argument + the
  keyed `publish_with_key_tx` empty-`Some` rule (exemplar covers all
  three, tx twins included and `with_tx`-driven); numeric domains
  (`extent_clamp_semantics` + `duration_refusal_on_non_positive_ttl`);
  `encode_payload` typed failure + round-trip; the `PayloadTooLarge`
  asymmetry (both engine-scoped rows, the pg one reading the limit
  from the produced variant); drop = rollback no-ghosts;
  read-your-own-writes; receiver arms + monotone save composition.
- The combined-coverage claim for `save_offset_tx` exactly-once
  (in-tx-ryow's own-save visibility + drop-rollback's save-never-lands)
  holds: together they pin (a) the save is visible inside the tx,
  (b) the saved checkpoint survives commit semantics exactly when the
  business tx commits, (c) rollback deletes it. No gap.
- The engine-side pins the map claims exist and are real:
  `uri_shaped_open_path_is_a_literal_filename` and
  `poll_interval_flows_to_the_watcher_config`
  (`alkstore-sqlite/src/store/open_tests.rs`);
  `sweep_rolls_back_the_retention_half_with_the_move`
  (SQLite substrate trigger seam — M-1's live pin) and the pg twin's
  structural guarantee confirmed by code-read of
  `alkstore-postgres/src/queue.rs::sweep_expired` (move + retention
  DELETE inside one `in_tx` `BEGIN…COMMIT/ROLLBACK` frame — a
  retention-DELETE failure rolls the move back via the frame's error
  arm);
  `receiver_stays_open_across_reconnects_closes_at_shutdown` (pg
  notify tests) + `subscriber_survives_reconnect_and_heals_gap_by_redrain`
  (pg stream tests) — the reconnect-stays-open pin the receiver-arms
  row cross-references; and the pg receiver error/close arms it pins
  inside the shared row body.
- Every row of the second table (wave-5 tasks) is present and stamped:
  the three queue-depth rows, three scheduler rows, three tx-seam rows
  (N-5's panic probe included), two stream rows, two lock rows (the
  SQLite busy-path open question answered in-row: losers get the clean
  `None` value — no divergence), `wake_receiver_shapes`,
  `backoff_curve_equivalence`, and the two extended
  `enqueue_opts_resolution` clock legs. The two engine-side hardening
  deliverables landed (`failed_commit_replenishes_the_writer_slot` —
  replay-proofed per its task; `reconnect_success_resumes_wake_delivery`;
  the pg `must_recv_event` parked-recv re-shape with the
  self-diagnosing deadline panic).

**2. Stamp audit — verified against the cited ADR text.** `grep
"Contract stamp:"` yields exactly 25 markers for 25 rows (one per
row; multi-stamp rows cite several ADRs on one marker). Every cited §
exists in its ADR and pins the behavior the row tests — verified
against the ADR bodies for the load-bearing citations: ADR-008 §3
(wake type + recv forms, `Ok(None)` idle arm), §5 (error taxonomy /
value-not-error), §7 (locks guarantee row), §8 (explicit saves only);
ADR-009 §1/§3/§4/§6 (runner shape, boundary fires, the 64-cap,
`LeadershipLost`); ADR-010 §1 (delete-on-ack, per-id `ack_batch`
predicate — pinned in ADR-021-era §1 annotation), §2 (validity
predicate, reclaim-eats-attempt), §3/§3a, §4 (strings, get_job-sees-dead,
retention default), §5 (no-stranded-rows, retention); ADR-014 §1 (60/5/5
derived stamp set); ADR-015 §1–§5 (key semantics, tx seam, `StreamEvent`
shape, ordering row, `trim_to` — the row texts quote the ADR's
"silent-loss / resume-at-horizon / no-dedicated-wake" semantics
verbatim); ADR-016 §5; ADR-020 §1/§2/§3/§4; ADR-021 §1/§3/§4/§5;
ADR-023 §1/§2 (the domain-rule table); ADR-012 §2 (one-owner
arithmetic, suite-pinned identical); ADR-019 §1/§3/§4/§6; ADR-007;
ADR-006. The amendment case checks: `enqueue_opts_resolution`'s stamp
list accumulated ADR-023 §2 when the wave-5 clock legs landed, on top
of its ADR-020 stamps — the deferral note replaced by the completion
statement, per the convention. No stamp cites an ADR § that doesn't
pin the tested behavior; no tested behavior lacks a stamp.

**3. Green on both engines — verified this session.** Workspace gates
green: `cargo build`, `cargo test` (12 binaries — core 25; suite
harness 3; pg 121 lib + 25 suite + 9 schema against the harness
server; SQLite 191 lib + 25 suite), `cargo clippy --all-targets --
-D warnings`, `cargo fmt --check`. Dedicated suite runs: pg column
vs the harness server three full runs (two consecutive + one concurrent
with the SQLite column, the wave-4 gate's posture plus), 25/25 each;
SQLite column green server-less twice (isolated + concurrent), 25/25.
Focused stress: 6 consecutive `--test-threads=6` runs of
`row_trim_to_semantics` + `row_lock_ttl` on pg — green throughout.

**4. Parked dispositions audited — all six made and recorded.**

| Disposition | Where recorded | Audit verdict |
|---|---|---|
| M-1 retention-failure pin's location | `suite-queue-depth-rows` Notes | Engine-side (SQLite trigger seam; pg by frame structure) — sound; the pg leg rests on code-read, accepted with the row's doc text recording it |
| Beyond-64 skip-forward leg | `suite-scheduler-rows` Notes | Engine-side twins exist on both engines (`catch_up_replays_up_to_the_cap_then_skips_forward`); suite pins the ≤64 in-band leg; row doc states it |
| Backoff cap leg | `suite-opts-backoff-rows` Notes | Engine-side pins verified present (both engines' unit tests); row doc records the disposition |
| Scheduler fire-wake parity | `suite-scheduler-rows` Notes | Not demanded by the row shapes (claim-polling observation only); the recorded gap stands for a later task; accepted as-is — **closed post-gate** (2026-10-10) by `pg-fix-scheduler-fire-wake` (the tick's commit-atomic fire wake; the row's Notes and `review-wave-4-fixes` carry the retirement pointers) |
| Lock-row divergence call | `suite-lock-rows` Notes | No divergence found — the row pins the convergence; nothing to fix |
| SQLite reconnect-success test | `sqlite-commit-error-arm` Notes | Taken — `reconnect_success_resumes_wake_delivery` exists and pins the success arm's re-baseline + restored delivery |

**5. Conformance spot-checks — clean.** No row pins beyond ADR text
(a row that would fail a correct engine was not found); the
determinism posture holds throughout — state-outcome assertions,
bounded waits, tolerance bands on stamps (`abs_diff <= 5`, ±10 s
informational `created_at`, one-second straddle on the curve upper
bounds), sleeps bounded well past second-resolution stamps; the two
documented posture extensions (runner-driving rows; the N-5 panic
probe) are admitted in the module doc as ADR-017 §2 class-4
suite-side posture notes and are implemented as described; no leg
duplication — cross-references instead (duration guards →
`duration_refusal_on_non_positive_ttl`; close arms →
`receiver_close_and_save_arms`; byte-exactness →
`payload_round_trip_stores_exact_encoding`; negative-horizon →
`extent_clamp_semantics`).

**6. Flaky-test ledger — the two unreproducible pg failures.** Two
single-occurrence failures were recorded honestly during development:
`row_trim_to_semantics` (stream-rows, 1/14 under the concurrent
SQLite+pg condition) and `row_lock_ttl_expiry_and_reacquisition`
(lock-rows, first cold pg run, message lost to truncation). Bounded
review investigation this session: three full pg suite runs (one under
the replayed concurrent SQLite+pg condition), six focused
`--test-threads=6` runs of both rows, and the workspace's own full pg
runs — all green; no divergence, no repro. Both rows' windows assert
state outcomes only (delivered events / post-sleep lock state), so a
timing-value failure mode is not available; the lock row's lapse
assertions are post-sleep states that a slower clock can only delay,
never un-lapse. One residual observation recorded for the future: the
trim row's pg-side failure shape would have been an event delivered to
the subscriber beyond its checkpoint in the post-trim absence window —
under pg's cross-database LISTEN the wakes are mechanism-named, and
the row's re-drain safety argument (own-schema storage yields nothing)
is the by-construction defense; if either row fails again, it should
get a dedicated investigative session (instrumentation + focused
repro loop) *before* any postulate-and-fix — per the user's ledger
the pattern (a prior unreproducible flake hinting at a real engine
issue) deserves that attention. Not blocking this gate: 13+ subsequent
clean pg runs across both rows since the failures, all conditions
covered. **Flagged for watch in the next wave window** (release
readiness at gate time — since renumbered to wave 7, ADR-024; wave 8
since the fuzzing wave's renumber, 2026-10-10).

*Ledger update (2026-10-10, from the `pg-fix-scheduler-fire-wake`
session):* `row_lock_ttl_expiry_and_reacquisition` failed once more —
a single occurrence in one full pg suite run (`cargo test
-p alkstore-postgres`, sequential, against the harness; the row's
failure message was lost to the run's output filtering), then green on
two subsequent full runs and six consecutive focused `row_lock_ttl`
runs. Unrelated mechanism to that task's change (scheduler fire wake;
locks untouched). Per this ledger's own prescription the row now
meets the "fails again" trigger — a dedicated investigative session
(instrumentation + focused repro loop) is owed by the wave-7 watch
carriage (the release-readiness watch — wave 8 since the fuzzing
wave's renumber) before any postulate-and-fix. Recorded here for the ledger's
honesty; not blocking the fire-wake task.

*Ledger update (2026-10-11, from the `release-flake-investigation`
session):* the lock row's trigger has been **investigated and
resolved** — `tasks/release-flake-investigation.md` carries the full
record (the capture procedure of record, the conditions matrix, the
read-back of the delay-only argument, the mechanism probes, the
natural repro). The disposition: **harness-model, not the engine** —
the pre-fix row's contention leg asserted a live-TTL state over a
`ttl = 1` hold whose guaranteed window second-precision stamps
(`now_unix`, `as_secs`) collapse below one second, so any ≳1 s
scheduling stall between the holder's and the contender's
acquisitions lapses the holder with the engine acting entirely per
ADR-008 §7. Natural repro captured (2/30 loaded solo runs, the exact
message at the exact assert site); fixed test-side that session (the
row's two-leg shape: long-TTL exclusion leg, short-TTL lapse leg);
30/30 loaded verification runs green under the exact repro condition.
The lock row's watch flag **retires**. Two observations carry to the
`review-wave-8` gate's flake outcome: the trim row stays
watch-flagged (no repro in 10 focused + 7 loaded full-suite rounds
this session), and a **new** single occurrence of
`row_stream_ordering_equivalence` under 8-CPU-burner load is
watch-flagged (message captured: `left: [1]` vs the six stored
offsets at the attach-drain compare, `properties.rs:3052` — the row's
recv-once-then-try_recv drain window raced the pg bridge's
not-yet-complete channel fill; no ordering violation, no delivery
failure — scheduling-lottery class, same as the lock row's contention
leg); no ride-along fix (instrumentation-first discipline).

**7. Findings.** No code, suite-row, or stamp defects requiring change
were found at gate time; all changes this gate made are doc-side
(engine specs `draft` → `stable` with dated gate annotations;
`docs/plans/implementation.md` wave table + review-rounds entry) and
task-file hygiene (`suite-opts-backoff-rows` had the placeholder
"To be filled" lines left in its Notes/Summary headers above real
content — removed the placeholders). Wave 6 decomposition may proceed.

## Summary

> Filled by the review agent (2026-10-10):

The wave-5 review gate passed. The suite is the compatibility
instrument the plan called for: **all 25 mechanism rows per engine
column present, version-stamped per `version_stamp.rs`'s convention
(greppable via `STAMP_MARKER`), green on both engines.** Verified by
direct read of every row and both engines' wiring, cross-checked
against `core-contract.md` §Verification backlog item by item (the
verified discharge map is in Notes §1), every `Contract stamp:` against
its cited ADR § text (Notes §2; the `enqueue_opts_resolution`
amendment accumulation checked), all six parked dispositions
audited (Notes §4, table), and the determinism/conformance postures
spot-checked (Notes §5). Suite green on both engines with the gate
posture exceeded (three full pg runs against the harness, one
concurrent with the SQLite column; SQLite green server-less twice),
plus focused stress on the two development-time flake rows; workspace
build/test/clippy/fmt green. Engine specs flipped to `stable`
(`docs/architecture/engine-sqlite.md`, `docs/architecture/engine-postgres.md`,
dated annotations citing this gate); `docs/plans/implementation.md`
wave table and review-rounds updated. The two unreproducible pg
failures from development are recorded with the bounded investigation
and a watch flag (Notes §6) — if either reproduces, a dedicated
session follows. Wave 6 (release readiness) decomposition may proceed.

## Appendix — the decomposition's backlog audit (verify, don't trust)

Discharged by existing rows (waves 1/3/4 — verify each):

| Backlog item | Discharged by |
|---|---|
| Name validation at every entry point (ADR-008 §4) | `name_validation_rejects_empty_and_reserved` (exemplar) |
| `schedule()` queue-argument validation (ADR-021 §3) | same exemplar row |
| Numeric-domain semantics (ADR-023 §2) | `extent_clamp_semantics` + `duration_refusal_on_non_positive_ttl` |
| `encode_payload` typed failure + round-trip (ADR-023 §1, ADR-020 §4) | `payload_round_trip_stores_exact_encoding` |
| `PayloadTooLarge` occurrence asymmetry (ADR-016 §5) | `payload_too_large_never_produced_on_sqlite` + `payload_too_large_produced_on_pg` |
| Drop = rollback no-ghosts (ADR-021 §4) | `drop_rollback_leaves_no_ghosts` |
| In-tx read-your-own-writes (ADR-021 §1) | `in_tx_reads_see_own_writes` |
| `save_offset_tx` exactly-once-within-a-business-tx shape | discharged across `in_tx_reads_see_own_writes` (own-save visibility) + `drop_rollback_leaves_no_ghosts` (the save never lands on rollback) — verify the combination genuinely covers the backlog row's claim |
| Receiver error/close arms + save-offset monotone composition (ADR-021 §5, ADR-019 §6) | `receiver_close_and_save_arms` (both columns; the pg reconnect-stays-open leg pins engine-side — verify that pin exists) |
| Plain-path SQLite open (ADR-023 §3) | engine-side: `uri_shaped_open_path_is_a_literal_filename` (`open_tests.rs`) — SQLite-scoped backlog row per the sqlite-engine-integration task |
| Watcher cadence default + knob (ADR-023 §4) | engine-side: `poll_interval_flows_to_the_watcher_config` (`open_tests.rs`) — same scoping |

Added by wave-5 tasks (verify presence + stamps):

| Backlog item | Wave-5 task |
|---|---|
| Job-handle validity predicate (ADR-010 §2) | `suite-queue-depth-rows` |
| ADR-010 depth: reclaim-eats-attempt, dead-letter, no-stranded-rows sweep + M-1 retention pin | `suite-queue-depth-rows` |
| Scheduler boundary/catch-up/leadership (ADR-009) | `suite-scheduler-rows` |
| `outbox_enqueue_tx` commit-atomicity (ADR-014) | `suite-tx-commit-atomicity-rows` |
| `publish_with_key_tx` commit-atomicity (ADR-015 §2) | `suite-tx-commit-atomicity-rows` |
| `with_tx` panic disposition (N-5) | `suite-tx-commit-atomicity-rows` |
| Cross-engine stream ordering equivalence (ADR-015 §3/§4) | `suite-stream-rows` |
| `trim_to` full semantics (ADR-015 §5) | `suite-stream-rows` |
| Lock TTL/expiry re-acquisition + concurrent loser (ADR-008 §7) | `suite-lock-rows` |
| Wake semantics under `WakeReceiver` shapes (ADR-008 §3) | `suite-wake-rows` |
| Backoff-curve equivalence (ADR-010 §3) + deferred opts clock legs (ADR-020) | `suite-opts-backoff-rows` |

Engine-side hardening riding the wave-5 window:

| Item | Task |
|---|---|
| SQLite commit-error-arm coverage (wave-3 review deferral) | `sqlite-commit-error-arm` |
| F-1 defense-in-depth (pg test-infra; not load-bearing) | `pg-suite-infra-hardening` |