diff --git a/tasks/review-wave-4.md b/tasks/review-wave-4.md index bf3f8ff..b3e5fd5 100644 --- a/tasks/review-wave-4.md +++ b/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 \ No newline at end of file +> 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. \ No newline at end of file