Durable idempotency for retrying mutations after uncertain outcomes

A timeout can conceal a successful commit, so client-side retry discipline alone cannot prevent duplicate effects. The design question is how to bind a stable request identity, payload identity, mutation, and replayable outcome into one atomic durable decision. Need reason through concurrency, rollback, response loss, and effects outside the transaction.

Reasoned resolution: give each logical mutation a stable high-entropy key scoped to the authenticated actor and operation, and store a canonical intent fingerprint plus replayable outcome under a unique constraint. In one database transaction, claim the key, apply the database mutation, store the outcome, and commit. A concurrent retry waits for the conflicting claim to resolve; after commit it compares intent and replays the outcome, while after rollback it may become the claimant. A crash before commit leaves neither receipt nor effect; loss of the reply after commit leaves both, so retry does not repeat the effect. Retention must cover the retry horizon. External effects require a transactional outbox plus downstream idempotency or an equivalent receiver guarantee. This is transaction reasoning only; no implementation or tests were executed. Existing guidance already covers this pattern, so no new skill or update is warranted.

Extension resolved by reasoning: retain one unique operation-key namespace across client versions. Store the trusted request-contract version, fingerprint scheme and digest, outcome version, and immutable replay facts with the effect. A fingerprint scheme freezes parsing, defaults, effect-relevant projection, canonical encoding and hash domain. Tag known legacy rows with their original scheme; if its identity or intent cannot be established, reject cross-version matching. Decode an incoming request under its trusted protocol contract, then compare using the committed row's scheme only through an explicit lossless mapping of effect-relevant intent. For example an old amount-in-minor-units request implies immediate capture, and a new nested-money request with capture true can be equivalent; capture false cannot be represented as the old intent and must conflict. In either overlapping arrival order, the common unique constraint lets one transaction win; after commit the other may replay only if equivalence is proven, otherwise it rejects. Render the requesting client's response from immutable committed result facts, or return a compatibility error without rerunning the mutation. Keep old comparators and response adapters for the retry and rollback horizon. This is conceptual reasoning with no executed tests. Existing versioned-rollout guidance already covers the solution, so there is no warranted skill change.