Atomic idempotency for ambiguous mutation retries

A useful design should identify the smallest persistent state, uniqueness boundary, and transaction boundary needed to turn at least once request delivery into a single committed business effect. The core hypothesis is that a caller scoped key, request fingerprint, durable unique constraint, and atomic commit of the receipt with the database mutation close the ambiguity window. Remaining questions are how concurrent retries observe completion and where the guarantee ends when an external system cannot join the transaction.

Reasoned resolution: the minimal guarantee for effects contained in one transactional datastore is a client generated key reused for the same logical attempt, a durable unique constraint scoped by caller and operation, an intent fingerprint, and an immutable result receipt committed atomically with the business mutation. A retry that races the first attempt must lose or wait on the same uniqueness boundary, then compare its intent with the committed fingerprint and replay the stored outcome. A crash before commit leaves neither receipt nor effect; a crash after commit leaves both, so there is no state in which the effect exists without its deduplication evidence. If an external effect cannot join the transaction, this construction alone is insufficient; use a transactional outbox plus idempotent downstream handling, or accept that duplicate freedom is impossible across the external acceptance and local acknowledgement gap. This is reasoned analysis only; no tests were executed.

Extended reasoned resolution for canonicalization rollouts: keep the durable uniqueness identity invariant across schema and fingerprint versions. Each winning receipt records the request contract version, fingerprint semantics version, digest, result schema version, and immutable result snapshot. A retry first loads the receipt, then strictly decodes its declared input contract and compares using the stored fingerprint semantics. Cross-version comparison is allowed only through an explicit lossless mapping that preserves every effect-relevant distinction; a newer field may map to an old intent only when its value is exactly the behavior the old contract implied. If mapping would drop a meaningful distinction, reject rather than treating the key as a match. Concurrent old and new first attempts race on the same unique key: the winner fixes the authoritative semantic version, and the loser waits, maps into that version, then either replays or conflicts. Replay uses the stored result version and a compatible renderer; inability to render must never cause re-execution. Deploy dual-version readers and adapters before new-version writes, and retain them for the receipt lifetime. No tests were executed.