Projection Delivery Guarantees -- Milestones

Date: 2026-07-27 Supplements: 2026-07-27-projection-delivery-guarantees-design.md

Five milestones, sequenced so each one leaves the library in a coherent state and strictly safer than the one before. The design document is the authority on what is built; this document covers ordering, exit criteria, and what remains broken at each boundary.

The honest framing of the sequence: M2 is where duplicate application stops. M1 builds the parts, M3 closes the remaining window and makes the guarantee structural, M4 stops the amplification loop, M5 proves all of it. If work has to pause, M2 is the first safe stopping point and M4 is the second.


M1 -- Primitives and honesty

Goal: Build the pieces the guarantee needs, change no behavior, and stop the documentation from lying in the meantime.

Changes

Exit criteria

Still broken after M1: everything. Duplicate application, silent loss under continue_on_error, and the amplification loop are all untouched.

Risk: low. Additive, with an inert-behavior exit criterion that is easy to verify.


M2 -- Exactly-once application for `DatabaseProjection`

Goal: Duplicate application stops. This is the milestone that discharges requirement 2 and unblocks the downstream consumer.

Changes

Exit criteria

Still broken after M2: the subscription cursor (save_position) still advances outside the transaction at EVERY_BATCH granularity, so mid-batch crashes still redeliver -- but the ledger now absorbs those redeliveries, so they no longer duplicate. The amplification loop persists: terminal failures still re-raise without advancing, and continue_on_error still drops events silently.

Risk: medium. Touches the core delivery path. The EXACTLY_ONCE default means every existing DatabaseProjection test exercises the new path, which is good for coverage and will surface fixture wiring that assumed an in-memory checkpoint repo.


M3 -- Inverted transaction ownership

Goal: The resume cursor commits with the handler's writes. Discharges requirement 1.

Changes

Exit criteria

Still broken after M3: the amplification loop and continue_on_error loss.

Risk: medium-high. Genuine control-flow inversion in the runner, and the throughput cost lands here. Highest chance of needing design revision mid-flight of any milestone.


M4 -- Failure handling

Goal: No event is lost, and no event is retried forever.

Changes

Exit criteria

Still broken after M4: nothing in scope. Remaining gaps are the documented exclusions -- non-transactional subscribers and out-of-transaction side effects.

Risk: medium. New dependency on CatchUpRunner, and the poison-pill transaction is a second write path that must stay consistent with the primary one.


M5 -- Verification and documentation

Goal: The guarantees are pinned by tests a future refactor cannot quietly break, and stated where users will find them.

Changes

Exit criteria

Risk: low, with one caveat -- crash-injection tests are the likeliest source of flakiness. If they prove unstable, the fix is a more deterministic seam, not a retry decorator on the test.


Sequencing notes