Preserve versioned intent across idempotency rollouts

Trigger

Use when a retryable mutation changes request schemas, defaults, or canonicalization while old clients and idempotency receipts may still retry.

Practical steps

1. Keep one database uniqueness key for authenticated caller, stable operation, and client idempotency key across every request version. Do not put a fingerprint version in that key.
2. Select the incoming contract from a trusted route or negotiated version. Strictly parse it into an explicit effect intent using that contract's pinned defaults and captured effect-relevant derived values. Use this same intent for both fingerprinting and the business mutation. Never execute an old request using a new contract's defaults.
3. Store the request contract, fingerprint scheme, digest, immutable outcome, and result version with the receipt. A scheme fixes parsing, normalization, canonical encoding, and hash domain. Give legacy receipts one trustworthy original interpretation; do not recalculate their digests with new rules.
4. For a new key, claim the shared unique key, apply the explicit intent, save the receipt and outcome, and commit in one database transaction. A lookup before the unique claim does not control a race.
5. For a concurrent or later retry, wait for the claim to commit or roll back. After commit, parse the retry under its own contract and map its explicit intent into the winner's stored fingerprint scheme. Permit replay only when this directional mapping preserves every effect-relevant distinction and the digest matches. Support both directions when either client version can win. Reject changed, unknown, or unrepresentable intent.
6. Replay from the immutable outcome through a compatible response renderer. If rendering cannot be done safely, return a compatibility error without rerunning the mutation. Deploy old and new parsers, intent normalizers, comparators, and renderers across the fleet before enabling new-version writes; retain them for the receipt lifetime.

Limits

If a legacy digest omitted a meaningful input and trusted original intent is unavailable, cross-version equivalence cannot be proved; reject the retry. An effect outside the database transaction needs downstream idempotency or a transactional outbox with durable consumer deduplication.

Failure prevented

A request under an old contract may imply USD when currency is omitted, while new business logic defaults omission to EUR. Fingerprinting that request as USD but executing it as EUR produces the wrong effect and makes an equivalent new-client USD retry conflict. Versioned explicit intent keeps execution and comparison aligned while the shared unique key prevents duplicate committed effects.

Evidence

This is reasoned failure-sequence analysis with an independent conceptual review. No implementation was inspected and no tests were executed.