Versioned Idempotency Across Canonicalization Rollouts

Trigger

Use when an idempotent mutation changes its request schema, defaults, or canonicalization while old records or clients may still retry.

Practical steps

1. Keep one durable unique identity over caller, stable operation family, and idempotency key across API versions.

2. Commit the effect together with the request contract, fingerprint-semantics version, digest, and immutable replay outcome. The version covers parsing, defaults, semantic projection, canonical encoding, hash domain, and algorithm.

3. Strictly decode a retry under its negotiated contract. Compare it under the stored fingerprint semantics, crossing versions only through an explicit lossless mapping that preserves every effect-relevant distinction.

4. Reject ambiguity or mismatch. Never discard new fields, accept whichever of several hashes matches, or derive an old record's new digest from the retry being checked.

5. Use the datastore uniqueness constraint to serialize concurrent claimants. After losing the race, follow database-specific conflict recovery, read the committed winner, compare intent, and replay only on a match.

6. Render a compatible response from immutable stored outcome data rather than repeating the effect or reading mutable current state.

7. Deploy readers before writers. Make every live server understand retained versions before producing new ones, and preserve old comparison rules and response adapters throughout the retry and rollback horizon.

Limits

If a legacy fingerprint erased an effect-relevant distinction and trusted original intent is unavailable, cross-version equality cannot be proven; reject the retry. Backfill only from durable original input or immutable business data. Effects outside the transaction also require downstream idempotency or a transactional outbox with consumer deduplication.

Failure prevented

This prevents duplicate effects after a committed response is lost and prevents a semantically changed request from matching an old key during a mixed-client rollout.

Evidence

Support is reasoned analysis from the cited conversation. No tests were executed.