Minimal durable idempotency for ambiguous mutation outcomes

The problem is to reason about a client retrying the same logical mutation after losing the first response, when the server may already have committed. The desired design should identify the minimum durable record, uniqueness constraint, transaction boundary, replay behavior, and handling of mismatched request reuse. A concrete failure sequence should demonstrate why the effect occurs at most once while the client can safely recover the result. No implementation or execution evidence is available; this is a standalone design analysis.

Reasoned resolution: the minimal robust design is a completed-operation ledger keyed by authenticated caller scope, operation namespace, and a client-generated idempotency key. A unique constraint serializes claimants. The server verifies a semantic request fingerprint, performs the business mutation, and stores an immutable replay outcome in the same database transaction. If the transaction rolls back, neither ledger nor effect remains and a retry may execute; if it commits, both remain and every retry replays the stored outcome. A concurrent claimant waits for the unique-key winner to commit or roll back. Reusing the key for different semantics must be rejected. Ledger retention must cover the full retry window. Effects outside the atomic datastore require an idempotent downstream service or a transactional outbox plus downstream deduplication. This conclusion is supported by failure-case reasoning only; no executable tests were run.

Extended reasoned resolution: keep one unchanged unique identity over caller, operation, and key; fingerprint version must never enter that identity. Each committed record stores the request contract version, canonicalization and fingerprint version, digest, result schema version, and immutable replay data. A retry first finds the existing key, then parses its own contract and converts it into the stored record's semantic domain through an explicit lossless adapter. It is accepted only when all effect-relevant distinctions are preserved and the digest computed with the stored rules matches. New-only fields may map to an old record only when they are provably non-semantic or equal the old contract's unique default; otherwise reject key reuse. In an overlapping old and new race, the unique constraint selects one winner. If the old request wins, the new loser compares under old semantics without discarding new distinctions. If the new request wins, the old loser compares under new semantics only when old values determine every new semantic field. The stored winner's immutable outcome is then rendered compatibly for the retrying client's response contract without rerunning the mutation. Accepting any hash version, rewriting an old digest from retry data, or placing version in the unique key would be unsafe. Rollout requires dual readers and adapters before new writes and retention of old comparison and replay code through the retry window. This is failure-case reasoning only; no tests were executed.