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.

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, and the promotion transaction. No tests were executed while creating this guidance.