docs(review): the wave-4 review gate — every gate check green

tasks/review-wave-4.md

@@ -1,7 +1,7 @@
 ---
 id: review-wave-4
 name: Wave 4 review gate — the postgres engine vs the contract
-status: pending
+status: completed
 depends_on: [suite-column-postgres]
 scope: narrow
 risk: low
@@ -85,14 +85,14 @@ completion is what unblocks wave 5's decomposition.
 
 ## Acceptance Criteria
 
-- [ ] Every gate check above read and verified against the cited ADR
+- [x] Every gate check above read and verified against the cited ADR
       text (not from memory of it)
-- [ ] Named design points each decided, recorded, and consistent with
+- [x] Named design points each decided, recorded, and consistent with
       the specs
-- [ ] Findings fixed inline or recorded as wave-5 amendments with
+- [x] Findings fixed inline or recorded as wave-5 amendments with
       owners
-- [ ] All gates re-run green after any fixes
-- [ ] Wave 5 decomposition unblocked (recorded in this task's Summary)
+- [x] All gates re-run green after any fixes
+- [x] Wave 5 decomposition unblocked (recorded in this task's Summary)
 
 ## References
 
@@ -107,8 +107,105 @@ completion is what unblocks wave 5's decomposition.
 
 ## Notes
 
-> To be filled by the review agent
+> Gate completed 2026-10-12, the wave-1/2/3 method: every gate check
+> read against the pinned text (ADR-007 §4/§5/§6, ADR-010 §2,
+> ADR-012 §3/§4/§5, ADR-013 §2/§4, store-api.md, the seam trait in
+> src/gc.rs), then verified against the landed diff (1efc46f…0fb05fc)
+> and re-run gates. Findings fixed inline:
+>
+> - **PG-1 — in-instance sweep-lease reaping after session loss
+>   (fixed, ADR-013 §2).** `sweep_lock_acquire` answered `Ok(false)`
+>   from the mutex even when the held lease's session had died —
+>   blocking re-acquisition on the same backend until an explicit
+>   release, against the holdership rule ("holdership ends at …
+>   engine-session loss"). Fixed: the acquisition answers against a
+>   live session only (dead checkouts are reaped in-instance); new
+>   test `sweep_lock_in_instance_session_loss_reaps_the_lease`
+>   (terminates the lease's own held backend via
+>   `pg_terminate_backend` and re-acquires without a release). The
+>   foreign-session reaping test (the wave-4 test) is unchanged.
+> - **PG-2 — the `PgJointTx` mid-flight-drop hazard (doc fix +
+>   amendment A1 below).** deadpool's `Fast` recycle never resets
+>   transaction state, so a `PgJointTx` dropped between
+>   `begin_joint_tx` and `pin_commit` returns a pooled *dirty*
+>   session to the pool. The clause bodies' own failure paths all
+>   ROLLBACK before surfacing (wave-4 contract holds — the zero-
+>   residue atomicity test proves it); the hazard is the store core's
+>   future use, where Rust `?` propagation between the two calls is
+>   the natural error shape. Not fixable inline without async-drop or
+>   a seam reshape — recorded on [`PgJointTx`]'s doc and as amendment
+>   A1 for wave 6.
+> - **PG-3 — engine-level pg tests leaked per-test schemas on the
+>   shared harness db (fixed).** 380 `abt_*` schemas had accumulated
+>   (the suite column's `alkblobs_suite_*` teardown was verifiably
+>   clean — 0 residue — the leak was src/postgres.rs's + src/store.rs
+>   construction tests' per-test schemas). Added crate-internal
+>   `test_support::SchemaJanitor` (a drop-guard running
+>   `DROP SCHEMA IF EXISTS … CASCADE` synchronously over a std
+>   thread + a one-shot current-thread runtime — no async-drop
+>   exists), the `Harness` deref-guard wrapper for the engine tests',
+>   and `fresh_opts` carrying a janitor in the construction tests. A
+>   one-time manual cleanup dropped the legacy residue (the 16
+>   hostile-name stragglers dropped via `quote_ident` — incidentally
+>   exercising the boundary). Post-fix: **0 schemas residue** after
+>   full `--features postgres` and `--all-features` runs.
+>
+> Amendments for the next waves (owners recorded here, no spec text
+> changed this gate):
+>
+> - **A1 (wave 6, owner: the fleet-GC mechanism task)** — the joint-tx
+>   drop discipline: the store core's joint-tx driver owes `pin_commit`
+>   on **every** path from `begin_joint_tx` onward (PG-2). Design it
+>   catch-propagate-terminate, or grow an explicit abort verb via a new
+>   ADR (the seam shape is pinned; `pin_commit`'s terminal-consume
+>   reading stays).
+> - **A2 (wave 5, owner: the pg-lo engine task)** — pg-lo's engine
+>   tests share the `pglo-poc` cluster: adopt `SchemaJanitor` (or the
+>   column's own teardown pattern) from the start — the wave-4 lesson
+>   is not to re-learn it.
+>
+> Minor observations, no action: `sweep_lock_acquire`'s mutex check is
+> not atomic with its checkout (two racing acquires both check out;
+> the advisory lock itself arbitrates and exactly one stores its
+> checkout) — sound by server arbitration. `list` rides the collected
+> query rather than `query_raw` — the recorded design point; the
+> bounded-memory claim holds for the keys-only materialization.
+>
+> Verification (post-fixes, all live unless noted): `cargo test`
+> 69/19/3 ok; `cargo test --features mem` 124/54/4 ok; `cargo test
+> --features postgres` 103/36/3 ok against the pglo-poc server, 51
+> clean skip notes server-less; `cargo test --all-features` 158/71/4
+> ok against the server; `cargo test --no-default-features
+> --features postgres` (pg-pure) 76/19/3 ok; clippy `-D warnings`
+> green (default / --features postgres / --all-features / pg-pure);
+> `cargo fmt --check` green; `cargo doc --no-deps` clean; shared-db
+> schema residue 0.
 
 ## Summary
 
-> To be filled on completion
+> Completed 2026-10-12 (wave 4). The engine-wave gate read the landed
+> postgres engine against the contract line by line and found it
+> conformant: the suite column green against the harness server (36
+> conformance rows live; server-less runs skip cleanly — a skip never
+> substituted), every clause family of ADR-012 §5's postgres row
+> contract-tested (both-tables schema + never-the-embedders,
+> stage-idempotence/take-atomicity/the `<=` boundary, joint-tx
+> atomicity with zero residue, `pin_renew` never-resurrect,
+> two-variant `pin_check`, the folded `FOR UPDATE` arbitrate, the
+> advisory lease's ADR-013 §2 semantics), the B5 deltas carried as
+> requirements (the per-connection `synchronous_commit` knob tested,
+> per-connection `prepare_cached`, fillfactor 90 stamped and
+> reloption-asserted, autovacuum/40× overhead stated in the module
+> doc), the `list` MVCC-snapshot cursor + the batch-delete helper
+> exact-count-gated vs server, the schema-less virgin-store split,
+> the size metadata-only EXPLAIN gate, and the non-fleet/posture
+> recordings verbatim where wave 6 needs them. All 11 named design
+> points audited as decided and recorded in the wave-4 task Notes.
+> Three findings fixed inline (in-instance lease reaping — new test;
+> the `PgJointTx` mid-flight-drop hazard — doc + amendment A1; the
+> engine-test schema janitor — 380 leaked schemas → 0), two
+> amendments recorded for waves 5/6 with owners (A1 the joint-tx
+> drop discipline; A2 pg-lo adopts the janitor). All gates re-run
+> green after the fixes (the verification block is in Notes). Wave 5
+> (pg-lo large engine) decomposition is unblocked; its review gate is
+> the engine-wave shape again.