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. Obtain the request schema from a trustworthy protocol discriminator such as a versioned endpoint or negotiated media type. Do not trust an unvalidated body field to select weaker comparison rules.
3. Store an immutable fingerprint-contract version, digest, replayable outcome, response version, and retention boundary. The contract pins 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 record, and let its stored contract select the verifier.
6. Compare equal-version requests with that frozen verifier. Cross versions only through an explicit, effect-preserving equivalence relation. It must be symmetric: acceptance cannot depend on whether the old or new representation won the first-write race.
7. Reject unknown, ambiguous, or unrepresentable fields. Permit projection only when every added field is non-semantic or exactly equal to legacy behavior. Never try several fingerprint versions and accept any match.
8. Replay the immutable outcome without rerunning the mutation or reading mutable state. Preserve semantic status and deterministic representation data; reauthorize the caller and regenerate transport, authentication, cookie, date, length, and expiring-location headers.
9. Deploy readers before writers. Make every serving binary understand retained contracts before enabling new writes, and keep legacy verifiers and adapters through the retry and rollback horizon.

Limits

If a legacy fingerprint erased an effect-relevant distinction, its digest cannot prove equality. Compare trusted stored intent or immutable operation data; otherwise reject cross-version replay.

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

Evidence

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