Bind each successor cursor to its exact retry response

When to use

Use this procedure when a consumer retries the same opaque input cursor and the provider may return a changed page, a rotated successor token, or both. It supplements ordinary deduplication and checkpoint fencing.

The core invariant is:

A successor cursor may advance the checkpoint only with durable completion evidence for the exact response that issued that successor.

Do not combine events observed in one response with a continuation token taken from another response, even when both were fetched from the same input cursor.

Record a response witness

For every successful fetch, create a durable response witness containing:

• The checkpoint generation and input cursor used for the request.
• A locally generated response-attempt identifier.
• The ordered event witness: stable event identity, source position, and a semantic payload digest when payload mutation matters.
• The exact returned successor cursor, stored as opaque data.
• The provider snapshot or coverage marker, when available.
• A pending, promoted, or abandoned disposition.

Hashing a cursor is useful for comparison and logs, but the consumer must retain the exact opaque successor value if it may later promote it. Protect cursor data according to its sensitivity.

Create the witness before, or transactionally with, the first durable event outcome attributed to that response.

Reconcile a retry

When retrying input cursor C from checkpoint generation G:

1. Fetch C and build a new response witness before adopting its successor.
2. Compare the new response with prior witnesses for C and G.
3. Classify the result:

• Exact replay: ordered event witness and successor cursor are identical. Resume the existing witness.
• Token rotation: the ordered event witness is identical but the successor differs. Treat it as a distinct response. Promote its successor only after every event in that response has a durable terminal outcome and only if the provider contract permits token rotation.
• Shifted page: event contents differ. Verify all overlap against durable receipts, reject conflicting identities or payloads at the same immutable position, and prove that the new response covers the next required portion of the stream.
• Unprovable divergence: the provider supplies neither stable snapshot semantics nor a coverage rule sufficient to exclude a missing event. Stop advancement and recover from a provider-supported stable boundary or fresh snapshot.

1. Process events from the selected response in source order. Existing receipts may satisfy replayed events, but each receipt must match stable identity and any payload digest required by the source contract.
2. Promote only that response's successor. In one compare-and-swap, require that the durable checkpoint still contains C and G, write the selected successor and a greater generation, and mark its witness promoted.
3. Mark other pending witnesses for C and G abandoned after observing the winning checkpoint. Never let a losing retry publish its candidate successor.

Coverage rule for a shifted page

A changed retry response is safe to continue only when the consumer can prove both conditions:

1. Every event at or below the durable applied boundary is either absent under documented exclusive-boundary semantics or matches its durable receipt.
2. The unseen suffix begins at the next required source position, or the provider supplies an equivalent coverage proof such as a stable snapshot boundary.

Monotonic positions alone do not prove completeness. If positions may be sparse and the provider exposes no coverage marker, seeing a larger position cannot prove that an intermediate event was not skipped.

Empty-response promotion boundary

A response containing no events is not complete merely because there are no event outcomes left to record. Its successor may advance only when evidence bound to that exact response proves that no required event lies between the durable applied boundary and the successor. Adequate evidence can be a provider-defined coverage watermark, a stable snapshot boundary, or documented empty-page semantics that preserve completeness. A transient empty page or an undocumented end-of-stream indication is not such proof.

For example, suppose the durable applied boundary is position 700. Retrying input cursor C41 returns no events, successor N9, and a provider-defined coverage marker proving that the same snapshot contains no required event after 700 through the boundary represented by N9. After durably recording that marker in the N9 response witness, the consumer may promote N9 with the usual compare-and-swap.

If the same empty response contains only N9 and no coverage marker or documented completeness rule, the consumer must leave its witness pending and must not advance. A later retry of C41 could still return position 701, so promoting N9 would rely on absence of evidence rather than proof of coverage.

This boundary does not make an unverified terminal flag reliable and cannot manufacture completeness when the provider contract supplies no coverage semantics.

Reasoned example

Checkpoint generation 9 holds input cursor C41. The first response contains positions 501 and 502 with successor N7. Position 501 becomes durable, then the worker crashes.

Retrying C41 returns positions 501, 502, and 503 with successor N8. The consumer creates a second witness, verifies that 501 matches its durable receipt, durably handles 502 and 503, and promotes N8 with a compare-and-swap from C41 at generation 9. It does not promote N7 using completion evidence gathered from the second response.

If the retry instead omits 502 and the provider offers no snapshot or coverage rule proving that 502 is no longer required, the consumer stops rather than advancing either successor.

This is a reasoned example, not an executed test.

Failure prevented

This procedure prevents a mixed-response checkpoint: processing the union of events seen across retries while advancing with a continuation token whose issuing response was never itself reconciled. Such mixing can skip unseen events when retry pages shift or successor tokens encode response-specific server state.

Limits and validation

This procedure cannot manufacture completeness when the provider contract offers no stable ordering, snapshot, or coverage semantics. Per-event idempotency is still required for safe replay, and compare-and-swap fencing is still required for concurrent workers.

Validate an implementation with provider-contract tests and fault injection around witness creation, each event outcome, empty-response coverage evidence, and the promotion transaction. No tests were executed while creating this guidance.