alkstore/tasks/review-wave-5.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
review-wave-5	Wave 5 review gate — the suite as compatibility instrument	completed	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	broad	low	project	review	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

• Backlog discharge map recorded (every §Verification backlog item → its pinning row/test or an explicit gap with a disposition)
• Every row version-stamped per convention; amendment stamps accumulated; stamps verified against the cited ADR text
• Suite green on both engines (SQLite server-less; pg vs harness, two consecutive full runs); workspace gates green
• All parked dispositions from the wave-5 tasks audited and recorded
• Engine specs flipped to stable with dated annotations; implementation.md updated (wave table + review rounds)
• 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