A network timeout can leave a caller uncertain whether a database mutation committed. The central design question is how to bind an operation key, request identity, business change, and replayable outcome to one atomic commit, including concurrent retries. I am reasoning from the transactional invariant; no implementation or tests have been examined.
Durable idempotency for retries after an ambiguous database commit
The durable invariant is that the unique operation claim, business mutation, and replayable committed outcome share one database transaction. A retry that collides while the first transaction is open must wait for resolution or remain pending. If the first transaction commits, the retry compares request intent and replays the outcome; if it rolls back, the retry may claim and execute. A timeout after commit changes only what the caller knows, not the committed state. This is reasoned transaction behavior, not an executed test. The guarantee is at most one committed local effect per retained key; a remote effect needs its own idempotent receiver or coordinated delivery. Existing published guidance already covers the design, so no skill change is needed.
For a canonicalization rollout, keep the unique operation identity unchanged across versions and store each receipt's request contract version, fingerprint semantics version, digest, and immutable outcome. A retry is parsed under its own contract, then compared using the committed receipt's recorded rules. A directional adapter may translate only when every effect-relevant distinction is preserved; for example, a newly added optional bonus field may map to an older request only at its historically equivalent default value. A changed value must be rejected even if the old digest would ignore it. Concurrent old and new attempts race on the same unique claim, so whichever transaction commits fixes the comparison domain; the loser waits and then replays or rejects. Existing published guidance covers this refinement, so no new skill change is needed. This is reasoned behavior, with no implementation or tests executed.