Versioned Idempotency Across Canonicalization Rollouts

Trigger

Use when a mutation changes request parsing, schema, defaults, or canonicalization while old idempotency records remain retryable, especially when old and new clients may race on one key.

Failure prevented

This prevents a lost response from causing a duplicate committed effect. It also prevents a changed request from matching an old key because a historical verifier ignored newer meaning.

Practical steps

1. Keep one durable unique key across versions, scoped by authenticated principal or tenant, stable operation, and client idempotency key.
2. Select the request schema through a trustworthy protocol discriminator, such as a versioned endpoint or negotiated media type. Do not let an unvalidated body field select weaker rules.
3. Store an immutable fingerprint-contract version, digest, replayable outcome, response version, and retention boundary. Retain the exact historical verifier implementation covering parsing, defaults, semantic projection, canonical encoding, and hashing.
4. For a new key, create the record, apply the business mutation, and save the outcome in one database transaction.
5. For a duplicate key, wait for any competing transaction, read the committed winner, and let its stored contract select the verifier.
6. Compare across versions only through an explicit effect-preserving equivalence relation. Validate both directions so acceptance does not depend on which representation won the first-write race.
7. Reject unknown, ambiguous, or unrepresentable meaning. Drop a new field only when it is non-semantic or exactly equal to historical behavior. Never try several fingerprints and accept any match.
8. Replay immutable outcome data without rerunning the mutation or reading mutable state. Render a compatible response only after identity matches.
9. Deploy readers before writers across the entire serving fleet. Before enabling new contracts, ensure every reachable instance can read them, prevent rollback to incompatible binaries or route by contract, and retain old verifiers and adapters through the retry and rollback horizon.

Limits

If a legacy fingerprint erased an effect-relevant distinction and trusted stored intent is unavailable, cross-version equality cannot be proven; reject the retry.

External effects require a transactional outbox plus downstream deduplication, or equivalent idempotency at the external provider. Removing a record or verifier before its retry horizon ends reopens duplicate-effect risk.

Evidence

Support is reasoned failure-sequence analysis from the cited conversation. No code, database, concurrency, or integration tests were executed.