--- id: pg-fix-tx-wake name: Fix tx enqueue/publish paths issuing no pg_notify wake (review 002 Finding 2 — F-1's root cause) status: completed depends_on: [] scope: narrow risk: low impact: component level: implementation tags: [wave-4-fixes, postgres-engine, tx, wake] --- ## Description Fix the HIGH finding from the wave-4 general review (`docs/reviews/002-wave-4-general-review.md` §Finding 2, live-proven): none of the tx-side enqueue/publish paths run `pg_notify` in the caller's transaction. Sites: `alkstore-postgres/src/tx.rs:290-329` (`publish_tx`/`publish_with_key_tx`), `tx.rs:272-288` (`enqueue_tx`), `tx.rs:545-562` (`outbox_enqueue_tx`). `notify_tx` proves `pg_notify` inside a tx is native commit-atomic (delivers at the caller's commit) — the exact mechanism these paths have available and don't use. A *committed* `publish_tx`/`enqueue_tx` never wakes a registered listener (deterministic silence, live-proven), while the auto-commit `publish`/`Queue::enqueue` wake immediately. **This is F-1's root cause, engine-side** — `tasks/review-wave-4.md` F-1's "root cause unresolved" and the gate's "the tx INSERT's commit *is* the NOTIFY carrier" conclusion were both wrong. Mechanism: the subscriber bridge attach-read + drain race the commit; when both beat the commit the bridge drains empty and parks on `wait_wake` — and no wake ever comes from a tx-committed publish, so the 15 s deadline exhausts (~2% under the 8-thread suite). **Conformance angle**: engine-postgres.md's mapping names `pg_notify` as the streams wake trigger; core-contract.md pins "events never require polling to become visible" and the tx/no-ghosts rows pin rollback dropping the event row *with its wake*. SQLite's watcher fires on any committed write, so its tx path wakes — the asymmetry would also have failed wave 5's cross-engine equivalence rows. **Fix shape** (the review's): - `publish_with_key_tx`: after the INSERT, one `SELECT pg_notify($1, '')` inside the caller's tx — the channel is the stream name (the mechanism-name-is-the-channel realization, already pinned in `stream.rs`'s docs). Empty payload: the wake carries `Wake { channel }` only, never payloads (ADR-008 §3). This is the **contract obligation** — the load-bearing fix. - `enqueue_tx` and `outbox_enqueue_tx`: add the same wake (channel = queue name; the outbox's derived `__alkstore_outbox:{name}`) for **posture parity** with SQLite's watcher — a weaker obligation (the queues row's pinned re-poll safety net covers correctness; the wake is latency posture), but the asymmetry is free to close and the review recommends it. - `run_once` is a pull op, consumer-driven — no wake needed there (do not add one). **Record updates**: this fix retires F-1's engine arm. Update `tasks/review-wave-4.md`'s F-1 note (engine arm retired by this fix; the wave-5 suite-hardening candidates — parked-recv deadline, lag diagnostics — remain valid as defense-in-depth but are no longer load-bearing for this flake) and `docs/plans/implementation.md`'s review-rounds line for the general review. ## Acceptance Criteria - [ ] `publish_with_key_tx` issues the `pg_notify` wake commit-atomically (channel = stream name, empty payload) — pinned by test: a registered listener receives the wake at/after the caller's commit, deterministically - [ ] The no-ghosts arm pinned: a *rolled-back* `publish_tx` produces no wake (the wake is commit-atomic, not statement-atomic) - [ ] `enqueue_tx` and `outbox_enqueue_tx` issue their wakes (channel = queue name / derived backing queue) — pinned by test - [ ] `tx_publishes_compose_with_the_handle` is deterministic: repeated solo runs (≥ 20) green with zero deadline misses - [ ] Auto-commit `publish`/`enqueue` behavior unchanged (still wake; no double-wake regression pinned where the suite observes it) - [ ] `tasks/review-wave-4.md` F-1 note + `docs/plans/implementation.md` review-rounds line updated to record the retirement - [ ] `cargo test -p alkstore-postgres` (harness server), clippy `-D warnings`, fmt clean; gates green server-less ## References - docs/reviews/002-wave-4-general-review.md §Finding 2 (the finding, the probe, the fix shape, the F-1 mechanism) - docs/architecture/engine-postgres.md (pg_notify as the streams wake trigger) - docs/architecture/core-contract.md (streams visibility; tx/no-ghosts rows) - docs/architecture/decisions/008-contract-v1-pinning.md §3 (Wake carries channel only) - tasks/review-wave-4.md (F-1's record — updated by this task) - alkstore-postgres/src/tx.rs (`notify_tx` — the proven commit-atomic mechanics these paths adopt) ## Notes Fix-shape decisions of record (what the description left open): - **One-owner wake statement**: all three producer paths call a shared `tx::wake_tx(client, channel)` — `SELECT pg_notify($1, '')` (empty payload, `Wake { channel }` only per ADR-008 §3) issued on the caller's tx client after the INSERT. Channel = the stream name (`publish_tx` rides `publish_with_key_tx`, so one site), the queue name (`enqueue_tx`), and the outbox's derived `__alkstore_outbox:{name}` (`outbox_enqueue_tx`). - **Wake error posture**: best-effort log-and-swallow (the engine-wide stance — a wake must never fail a write), matching the auto-commit publish/enqueue twins. Documented hazard: a failed statement aborts the pg tx server-side, so a swallowed wake failure still surfaces typed at COMMIT — no silent half-state; a rolled-back tx's queued notifies are discarded server-side with the row (the no-ghosts arm is native). - **No double-wake**: the wake is applied at the tx call sites, NOT inside the shared `enqueue_row`/INSERT — the auto-commit `Queue::enqueue` and the scheduler's fire-wake keep their own single statements on their pool connections, untouched. - **`run_once` untouched** (pull op, consumer-driven — no wake, per the task). - **Test shape**: one harness test in `tx_tests.rs` (`tx_producer_wakes_are_commit_atomic_and_rollback_discards_them`) pins all four arms — pre-commit silence (commit-atomic, not statement-atomic: 300 ms statement window + 100 ms listen, then commit), deterministic wake delivery at commit on all three registered channels, rollback silence, committed row-count truth. Uses `forwarder().register` + the raw fanout (`listener_hears`); `register` does no name validation, so the reserved derived outbox channel registers directly. - **Record updates went slightly beyond the strict line**: besides the review-rounds line, `docs/plans/implementation.md`'s frontmatter `last_updated` and the wave-4 gate bullet's "root cause unresolved" text got dated supersede/correction pointers (the stale-reference discipline — those conclusions were factually wrong, not just unresolved). ## Summary **Landed**: the tx producer paths' commit-atomic `pg_notify` wakes (`tx.rs`: `wake_tx` helper + the three call sites + the "The tx wakes" module-doc section pinning the semantics) — `publish_with_key_tx`/ `publish_tx` (the contract obligation: streams never require polling; rollback drops the row with its wake) and the posture-parity `enqueue_tx`/`outbox_enqueue_tx` twins (channel = queue name / derived backing queue); the new pinned tx-wake test; the F-1 retirement recorded in `tasks/review-wave-4.md` (including the correction that the gate's "the tx INSERT's commit *is* the NOTIFY carrier" conclusion was wrong) and `docs/plans/implementation.md`. **Verified**: full pg lib suite 116/116 green against the harness server (two consecutive full runs, ~70 s each); the new wake test green; `tx_publishes_compose_with_the_handle` deterministic — 20 consecutive solo runs green with zero deadline misses; workspace `cargo test` server-less green (harness tests skip cleanly); `cargo clippy --all-targets -- -D warnings` clean; `cargo fmt --check` clean. Auto-commit publish/enqueue unchanged (their wake tests ride the suite untouched).