feat(out)!: commit-lane consumer gaps — readable commit position, lane-aware fence

[bodymindarts]

Closes both consumer-side gaps that blocked lana's DW relay from adopting Ordering::Commit against the released 0.11.1 crate. Working from obix-dev/handoff-commit-lane-consumer-gaps.md, rev 1 (2026-09-16).

Base: rebased onto origin/main @ 365e6d1 (0.11.2-dev). PR #154 has landed — it is in 0.11.1 (6a0b2dd), so the OutboxPayload/as_event trait bound is already the shipped shape here; nothing in this PR touches it.

---

FOR THE LANA CONSUMER — the API you adopt against

This is the whole Rust-side surface. Note the fence differs from §10 as written (see CORRECTION below) — a consumer following the original spec text builds the wrong thing.

Reading your commit position (Gap A — this did not exist at all before):

// registration — unchanged from the prior handoff
OutboxEventJobConfig::new(DW_OUTBOX_RELAY_JOB).ordering(Ordering::Commit)

// in handle_persistent — read BEFORE resolving the ctx (the verbs consume it)
let (commit_sequence, is_boundary) = ctx.commit_position().expect("commit lane");
ctx.collect(LanaDwRow { commit_sequence: i64::from(commit_sequence), .. })

// in flush — the position the batch actually landed at
let watermark = op.commit_position();   // Option<CommitSequence>

FlushOp::commit_position() is the last fully handled event's position, not max over the collected rows. Those differ whenever a group's trailing members were skipped, and the batch one is the correct watermark — use it rather than folding over your own rows. Both accessors are None on the insert lane.

Fencing (Gap B / §10):

lana_relay_fence.await_caught_up(Duration::from_secs(60)).await?;   // signature UNCHANGED

await_caught_up picks the right fence from stored state — no new parameter, nothing to pass. This is what verify_party_pii_erased.rs:78 already calls; it keeps working and is now actually sound on the commit lane (before this PR, moving the relay to Ordering::Commit silently converted that GDPR-erasure check into a race).

What StreamPosition requires you to match on — this is the breaking part:

pub enum StreamPosition { Insert(EventSequence), Commit(CommitSequence) }

API	before	after
SubscriptionSnapshot::checkpoint()	EventSequence	StreamPosition
SubscriptionSnapshot::frontier()	EventSequence	StreamPosition
SubscriptionError::CaughtUpTimeout { checkpoint, target }	EventSequence	StreamPosition
SubscriptionSnapshot::ordering()	—	new: Ordering, if you only need the lane
lag(), is_caught_up(), stream_status()		unchanged signatures
await_caught_up(), await_sequence()		unchanged signatures

Call sites break only where they compare or assert on a raw position; the fix is to wrap (StreamPosition::Insert(seq)) or match. StreamPosition derives Ord, so checkpoint() >= StreamPosition::Insert(target) works — but comparing across variants is meaningless, so only compare positions read from the same subscription. The in-repo migration of tests/registered_handler.rs + tests/keyed_subscriber.rs in this PR is a worked example of the full downstream change.

await_sequence(target: EventSequence, ..) keeps its signature and stays insert-lane: it compares state.sequence, which is not monotone under commit ordering. A commit-lane subscription fences with await_caught_up.

---

Gap A — the commit position was unreachable

It lived on CommitOrderedEnvelope, which only the raw listen_commit_ordered listener yields; singleton.rs unwrapped it into LaneItem and kept it. handle_persistent gets &Arc<PersistentOutboxEvent<P>>, which carries no lane position by design, and EventCtx/FlushOp exposed nothing. The relay's entire job is to write that number into the warehouse, so it could not be written. The runner already held commit in scope at the ctx construction site; this carries it through.

Gap B — the fence was not lane-aware (§10, deferred at #151)

singleton.rs assigns state.sequence = event.sequence on the commit lane too. Commit order is a permutation of insert order, so that field goes down as well as up. await_sequence polled checkpoint >= target, so a single delivery whose insert sequence happened to reach the sampled frontier satisfied the barrier while events at lower insert sequences were still undelivered — it returned early, violating the documented semantics-1 guarantee rather than merely reporting a confusing number.

Now: StreamPosition, lane-aware snapshot accessors, commit-lane frontier from commit_log_state().last_commit_seq, and a commit-lane fence.

CORRECTION — §10's step 2 as written would HANG

The spec fences on commit_log_state().logged_through_sequence >= H. That is true of what the watermark means but not of how it moves: it is written only by append_commit_group, and Sequencer::fold returns early — touching no row — for a placeholder, a logged_ahead seed, or a member of an already-seen group. It is an append watermark, not the fold's stream position, so an aborted transaction at the head (exactly what inflates H, which counts allocations including aborted ones) parks it below H forever. Quiet periods have the same shape. A hang is the worst failure shape to debug, because the logs say nothing.

Implemented option 1 of §4, as recommended: the sequencer publishes its insert-lane fold position on an AtomicU64 alongside the commit head, advanced for every delivery it examines — placeholders included — and the fence waits on that. No extra writes, no schema change. Per-process is acceptable and already implied: §10 documents that this fence requires a live sequencer, and one is guaranteed while the subscription's own job is alive. The wait is bounded by the sequencer listener's own gap-fill grace, the same wait the insert-lane fence implies today.

Recorded in obix-dev/handoff-commit-ordered-delivery.md as CORRECTION 3, fixed at both points the defective recipe appeared (§10's prose and Appendix B's "Fence" pseudo-code), re-fetched and verified afterwards — the phrase survives only inside the correction blocks that quote it to explain why it is wrong.

---

Deliberate decisions NOT touched

• Decision 3 (rev 3) — groups placed at first sight, by group MIN. Untouched. The only change in sequencer.rs is publishing the fold position; the placement algorithm and append_commit_group are byte-identical in behaviour.
• SubscriptionDef::wake_keys stays a plain reference — not touched.
• Subscribers still receive &Arc<..> — not touched.
• Publication delivery stays singleton-only — §15 (keyed on the commit lane) remains out of scope, per the handoff's own non-goals.

Regulatory note (FFIEC-051)

This changes no delivery granularity, ordering, checkpoint timing, or at-least-once/at-most-once property of either lane. Gap A is a pure read of a value the runner already tracked. Gap B makes a barrier that could return early wait correctly — strictly more conservative, in the direction of not letting a consumer act on a half-applied prefix. The insert lane is behaviourally untouched.

Migration / deployment

No migration. No schema change, no job_setup.sql change, no checksum change — so no make clean-deps and no consumer hand-copy of SQL is needed. The ! is for the Rust API break only (StreamPosition), which is a compile error downstream, not a silent one.

Verification (run separately, as stated)

• nix run .#nextest — 156/156 passed, stable across three consecutive runs. This is what runs the tests; nix flake check does not.
• nix flake check components — cargo fmt --check clean, cargo clippy --all-targets --all-features -- -D warnings clean.
• cargo doc --no-deps --all-features — fails with exactly the 3 pre-existing broken intra-doc links on src/config.rs, src/out/ctx.rs, src/out/partition/mod.rs, all three confirmed byte-identical to origin/main (those files are either untouched or unchanged in that region). One new warning I introduced (a doc link to a private method) was found this way and fixed, so the count is back to the baseline 3.

Revert-to-red

Every test proving a mechanism was confirmed RED against unfixed code, deterministically and for the right reason:

Probe	Result
EventCtx::commit_position() returns None (the pre-change state: runner keeps commit to itself)	test 1 + test 3 FAIL — commit lane must report a position
await_caught_up restored to its lane-blind form (insert frontier vs insert cursor)	test 4 FAILS — await_caught_up returned while commit positions 3 and 4 were still undelivered; test 5 FAILS — wedged, checkpoint insert:2 behind target insert:3
fence step 2 restored to logged_through_sequence >= H (the defective §10 text)	test 5 FAILS — CaughtUpTimeout: checkpoint insert:1 behind target insert:3 after 15.0s, i.e. the hang, reproduced

Two tests were vacuous when first written and were fixed, not accepted. Both are worth recording, because the same trap will catch the lana adoption:

1. Insert sequences are allocated in PersistEvents::pre_commit, not at publish time. So an interleaving built by holding ops open and publishing into them produces no interleaving at all (each transaction's sequences come out contiguous), and a dropped op burns no sequence at all. The tests now seed rows directly — the technique tests/commit_ordered.rs already uses and documents for exactly this reason — and burn the aborted tail with a raw INSERT that is rolled back. Explicit-sequence inserts do not move the generator, so the seeds also setval it; without that the frontier reads 0 and anything fencing on it passes trivially.
2. The commit-lane fence is only taken once a commit cursor has been persisted, and a handler blocked inside handle_persistent can never persist one. The fence test now commits one event in its own op first, and asserts its preconditions (ordering() == Commit, commit cursor 2 of 4, insert frontier == the insert cursor) before fencing — the last of those being precisely the state an insert-cursor fence wrongly accepts as caught up.

No sleep-based synchronisation: conditions are polled, and the "must not return" assertion uses a bounded timeout window that resolves the instant the barrier completes. Neither fragile test was touched or re-thresholded — tests/keyed_subscriber.rs:1974 and slow_consumer_does_not_inflate_the_rows_read both pass, and this change adds no new reader of persistent_outbox_events (the fence reads the sequence generator and the commit-log state table).

Comment diff

src/ gains exactly one new inline comment — an INVARIANT: note on the fold-position store, matching the form already in singleton.rs, guarding the one thing a later reader could silently regress (it must advance on placeholders too, or the fence wedges). One pre-existing comment moved with the poll loop into the extracted helper. Everything else is rustdoc on new public API. Rationale lives here and in the commit message.

---

Note

Medium Risk
Breaking public API (StreamPosition) and changes commit-lane await_caught_up semantics in the outbox consumer path; incorrect fencing would let callers act on partially applied streams, though the change is strictly more conservative than the prior commit-lane behavior.

Overview
Closes commit-lane adoption blockers by exposing commit positions to handlers and making subscription fencing lane-aware, with a breaking StreamPosition type for checkpoints and frontiers.

Gap A: EventCtx::commit_position() and FlushOp::commit_position() surface commit-lane sequence and boundary info (both None on the insert lane). Batch flush passes the runner’s commit checkpoint into FlushOp so warehouse-style subscribers can persist watermarks without using the raw commit listener.

Gap B: SubscriptionSnapshot and CaughtUpTimeout now use StreamPosition (Insert vs Commit) instead of bare EventSequence. await_caught_up branches on lane: insert behavior is unchanged; commit-lane subscriptions use a two-step fence that first waits on the local sequencer’s fold_position (insert sequences the fold has examined, including placeholders), then polls the commit cursor—fixing early return when insert cursor hits the frontier before all commit deliveries, and hangs when fencing on logged_through_sequence behind an aborted tail.

The sequencer publishes SequencerPositions into resident Subscription handles; singleton registration wires this from Outbox::sequencer_positions().

^{Reviewed by Cursor Bugbot for commit fadcc9b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit fadcc9b. Configure here.}

[cursor]

Fence can return before append

High Severity

The commit-lane await_caught_up fence treats fold_position as proof that every group up to the call-time insert head is in the commit log, but fold publishes that atomic at the start of each delivery — before append returns. On a single-event transaction at the head (the usual publish-then-fence case), and especially while append is retrying, the fence can sample a stale last_commit_seq and return while that event is still unlogged and undelivered. That reopens the early-return race this change is meant to close.

Additional Locations (1)

• src/out/subscription/mod.rs#L640-L656

 

^{Reviewed by Cursor Bugbot for commit fadcc9b. Configure here.}

[cursor]

Fresh commit lane uses insert fence

Medium Severity

await_caught_up infers the lane only from a persisted commit_sequence. A commit-lane subscription that has not checkpointed yet is classified as insert and waits on state.sequence, which is not monotone under commit order. Until the first flush or consume, the same permutation that this PR fixes can still satisfy the insert-cursor fence while later groups are undelivered.

Additional Locations (1)

• src/out/subscription/mod.rs#L600-L607

 

^{Reviewed by Cursor Bugbot for commit fadcc9b. Configure here.}

[bodymindarts]

Superseded by a lane-typed redesign (handoff-lane-typed-delivery.md). The EventCtx::commit_position() shape here is withdrawn by design decision: a position is a property of a delivery on a lane, not of the ctx or the event row. The replacement makes the lane a type parameter (Delivery<L, T>, SingletonSubscriber<P, L>, FlushOp<'_, L>, Subscription<P, Tables, L>) so one handler API serves both lanes.

The Gap B fence correction and the regression tests from this PR are carried into the replacement, which is implemented from origin/main.