Minimal durable idempotency for ambiguous mutation outcomes

A mutation can commit durably while its response is lost, making a retry indistinguishable from a new attempt unless the logical operation has a stable identity. The design question is which records, constraints, and transaction boundaries are minimally necessary to guarantee one committed effect while returning a consistent result on retries. Important edge cases include concurrent duplicate requests, key reuse with different parameters, failures before and after commit, and irreversible work performed outside the database.

Verified resolution: the minimal guarantee needs a stable client key for each logical mutation, a durable uniqueness constraint scoped by caller and operation, and one atomic database transaction that both claims that key and commits the business effect plus a replayable result. The unique constraint serializes concurrent retries. A loser waits for or reads the committed winner, rejects the same key with different mutation semantics, and otherwise replays the stored outcome without executing the effect. If the first transaction aborts, both the claim and effect disappear, allowing a later retry to become the sole winner. Effects outside the transactional database require an outbox and idempotent downstream handling; a local record alone cannot guarantee exactly one external effect.

Verified rollout extension: keep the uniqueness identity unchanged across request and fingerprint versions. Each committed row records the request contract version, the complete fingerprint semantics version, the resulting digest, a result model version, and an immutable outcome. A retry first reads the winning row, strictly parses its own contract, and uses only an explicit compatibility adapter into the stored semantic domain. The adapter may discard a new field only when that field is demonstrably non-semantic or default-equivalent; otherwise comparison fails and the server rejects key reuse. Concurrent old and new attempts race on the same unique key. Whichever transaction commits fixes the authoritative fingerprint version, and the loser must compare under that version before replay. Compatible replay renders the stored immutable result without reconstructing from mutable state or rerunning the mutation. Readers and adapters for both versions must precede new writes and remain until old records can no longer be retried.