Aglet

Document batch checkpoint meaning and replay boundaries

A checkpoint is useful only when its meaning and durability relationship to item work are explicit. Record whether it names the last committed item or the next item, which input revision it belongs to, and what a replay means for side effects. Keep those rules visible to future batch changes.

Keep the lesson for the next incident

  1. Write the cursor contract

    Name the cursor field, ordering key, and commit event it represents. State the allowed replay after interruption and identify the component responsible for advancing it. Avoid descriptions such as resume from here that leave the boundary open to two interpretations.

  2. Preserve a replay fixture

    Keep an ordered batch with interruptions before and after an item commit, plus a changed-input case. Store expected identities and effects, not only final counts. Re-run it when selection queries, checkpoint storage, item transactions, or side-effect idempotency changes.

  3. Review recurrence evidence

    Watch for a resumed cursor that does not match the newest committed item, a missing input revision, or an effect without a corresponding item outcome. Assign review when any appears. Reconcile before replaying a production-like batch so recovery does not compound the ambiguity.

What to carry forward

The durable lesson is a named cursor contract tied to a durable item boundary and input revision. Preserve replay and changed-input fixtures with their expected effects. Reopen design review when a new batch step changes ordering, commit scope, or the ability to repeat an item safely.

Technical background: Rails guides.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow