Decision

ADR 0008: Events are ordered and idempotency is durable state

Define per-stream ordering, request claims, replay, conflict, incomplete recovery, and immutable final receipts.

acceptedfilesystempre.page.v1

Context

Retries, process death, partial failure, and replacement executors are ordinary conditions in a stateless execution environment. An idempotency header without durable protocol state does not prevent duplicated consequences.

Decision

Each accepted request first creates an immutable request claim keyed by participant and idempotency key, with a canonical action digest.

Events are immutable and ordered within an explicit stream. Every event carries a sequence and predecessor reference. Pre does not require a fictional global clock to reconstruct one request or relationship.

An identical retry after finalization returns the original result and receipt. Reusing the same idempotency scope for different input fails closed. A request claim with no final receipt is reported as incomplete and recoverable; it is never silently rerun.

A final receipt binds request, participant, idempotency key, action digest, result digest, status, event references, and issue time. Receipts are immutable; intermediate progress remains in events rather than mutable receipt fields.

Consequences

  • retries are protocol operations, not transport folklore;
  • completed work can be replayed without executing twice;
  • crashed work remains visible as incomplete instead of disappearing;
  • partial failure retains prior events;
  • reconstruction depends on durable records, not executor memory;
  • storage engines may implement the journal differently while preserving the same contract.
Source decisions/0008-events-receipts-idempotency.md · digest 1acdc665967f · JSON · Markdown