Versioned idempotency across canonicalization rollouts

Trigger

Use when a retryable mutation changes its request schema, defaults, or canonicalization while old clients or receipts remain live.

Practical steps

1. Keep one unique database key for authenticated caller, stable operation family, and client idempotency key across all versions. Never include the fingerprint version in that uniqueness key.
2. Choose the incoming contract from a trusted route or negotiated protocol version and reject unknown fields. A version label in the body must not select a weaker parser.
3. In the same transaction as the business effect, claim the key and record the request contract, fingerprint scheme, digest, outcome version, and immutable replay facts. Each scheme fixes parsing, defaults, effect-relevant projection, canonical encoding, and hash domain.
4. Tag legacy receipts with their known generating scheme before new writes. Verify that a legacy digest committed to every field that could affect the original mutation. If its scheme or complete original intent cannot be established from trusted durable facts, refuse cross-version replay for that receipt.
5. On conflict, wait for the claiming transaction to commit or roll back. Decode under the incoming contract, then compare against the winner's stored scheme through an explicit, lossless semantic mapping. Reject any changed effect-relevant value, ambiguous default, unrepresentable field, or different digest. Never accept whichever of several hashes happens to match.
6. Replay the committed outcome from immutable facts using a compatible renderer for the requesting client. If no safe rendering exists, return a compatibility error without repeating the effect or reconstructing the historical response from mutable state.
7. Deploy readers, comparators, and renderers for both versions to every serving instance before new-version writes. Retain them through the retry, retention, and rollback horizon.

Limits and failure prevented

Versioning cannot repair a legacy fingerprint that omitted an effect-relevant field. For example, if a transfer digest covered amount and currency but not destination, a changed destination could falsely match; recover the original destination from trustworthy durable facts or reject. A new authorize-only request must not match an old immediate-capture request merely because an old parser ignored the new field.

A shared uniqueness constraint serializes overlapping old and new clients: whichever transaction commits first sets the comparison scheme, and the other replays only after proving equivalent intent. This prevents duplicate committed effects and false same-key matches after a lost reply. External effects still require an outbox and downstream deduplication or an equivalent guarantee.

Evidence

This is reasoned transaction and rollout analysis, including an independent conceptual check. No implementation was inspected and no tests were executed.