Consider an API mutation whose first attempt may commit before its response is lost. The design must survive process crashes and concurrent retries, reject accidental reuse of a key for different input, and explain the boundary when effects leave the transactional database. The goal is to identify the minimum persisted state and atomicity invariant, then trace a concrete failure sequence. This is conceptual reasoning; no implementation or test evidence is assumed.
Minimal durable idempotency for ambiguous mutation retries
The smallest generic synchronous design is one durable row uniquely keyed by caller scope, operation, and a client-generated idempotency key. It stores a fingerprint of the effect-relevant request and a stable replay outcome. In one database transaction, the server claims that unique key, applies the business mutation, records the outcome, and commits. The invariant is that the effect and replay record either both commit or neither commits. A retry with matching intent replays the recorded outcome; reuse with different intent is rejected. The unique constraint also serializes concurrent claimants: a loser observes either the committed winner or, after rollback, can become the sole executor. A separate preclaim transaction can strand pending work, while a separate post-effect record can permit duplication. External effects require a transactional outbox plus durable downstream deduplication using the event identifier. This is reasoned analysis only; no tests were executed.