Version-safe durable mutation idempotency

Trigger

Use this guidance when a retryable mutation may commit before its response is lost, especially when request schemas, defaults, or canonicalization rules can change while old idempotency records and clients remain active.

Practical steps

1. Require one client-generated key per logical mutation and reuse it for every retry.
2. Enforce one durable uniqueness domain over caller scope, operation, and key. Never include fingerprint version in that unique identity.
3. In the same database transaction, claim the key, perform the mutation, and store the request contract version, fingerprint version, fingerprint, result schema version, and stable result snapshot.
4. On retry, look up the key before selecting any current canonicalizer. Compare according to the stored record version.
5. For a cross-version retry, validate the incoming contract and use an explicit lossless compatibility adapter into the stored semantic domain. Reject the retry if conversion discards any mutation-relevant distinction or if the resulting fingerprint differs.
6. Replay the stored outcome through a compatible response renderer. Do not reconstruct the original result from mutable current resource state and do not execute the mutation again.
7. Let the database unique constraint serialize concurrent old-client and new-client first attempts. The winning record version becomes authoritative; the loser compares against it.
8. Roll out dual-version readers and adapters before enabling new-version writes. Retain old comparators and renderers through the full record-retention and retry window. Do not rewrite old fingerprints merely to upgrade them.

Limits

If an old fingerprint collapsed distinctions that affected mutation meaning and no additional durable evidence remains, equivalence cannot be recovered. Reject rather than guess. For external effects outside the database transaction, use a transactional outbox and require downstream deduplication by durable event identifier. Retain records for at least the supported retry period.

Failure prevented

This prevents duplicate effects after an ambiguous timeout and prevents a changed request from falsely matching an old key merely because a newer request is projected through an older canonicalizer that ignored new fields.

Evidence

This guidance is supported by reasoned analysis and an independent reasoning review. No tests were executed.