A generic mutation can commit before its response reaches the caller. The design question is how to bind a caller-supplied operation key, request identity, effect, and saved outcome to one durable transaction so retries can resolve the ambiguity. Need account for concurrent attempts, changed payloads, retention, and effects outside the transactional store. No code or system-specific evidence is involved.
Minimal durable idempotency for ambiguous mutation retries
Reasoned resolution, without executed tests: A caller must reuse one high-entropy operation key for one logical mutation. A server enforces uniqueness on authenticated scope, operation, and key, and stores a fingerprint of effect-defining inputs plus a replayable committed result. The key claim, business database effect, and saved result commit in one transaction. A concurrent duplicate waits for the unique-key winner to commit or roll back; after commit it compares fingerprints and replays the saved result, while after rollback it may claim and execute. If commit succeeds but the response is lost, a retry sees the receipt and cannot repeat the effect. If a crash precedes commit, both receipt and effect roll back. This guarantee applies only when the effect shares the transaction boundary; an external side effect requires downstream idempotency or an equivalent coordinated pattern. Receipt retention bounds the retry guarantee. Existing published guidance already covers this pattern, so no new skill is needed.
Extended reasoned resolution for a request-canonicalization rollout; no files or tests were involved. Keep the unique idempotency identity invariant across versions. Each receipt records its request contract, fingerprint-semantics version, digest, and immutable result version; legacy rows need a deterministic original-version interpretation. A retry is parsed under its declared contract, then compared using the committed receipt's version through an explicit directional adapter. Such an adapter may map a new field to an old receipt only when its value equals the old contract's actual implied behavior; it must reject changed or unrepresentable values instead of dropping them before hashing. New receipts can use the new fingerprint semantics even for old-client requests, provided old inputs are normalized with pinned defaults. Overlapping old and new requests contend on the same unique key: the winner commits the effect and versioned receipt together, while the loser waits, rereads, and either replays a compatible stored result or reports a request conflict. Response rendering must use immutable outcome data and remain compatible across client versions; inability to render must never rerun the effect. Deploy readers and adapters across the serving fleet before new-version writes. If the legacy digest omitted a meaningful distinction and no trusted original intent remains, equivalence cannot be proved and cross-version replay must be rejected. Exact existing published guidance covers this extension, so no new skill is proposed.