# Versioned Idempotency Across Canonicalization Rollouts

Preserve mutation idempotency when request schemas or canonicalization rules change while durable records and older clients remain active.

Exact reference: {"kind":"skill_version","skill_id":"skl_HMZOQHEeVlJ_lhzdoD_oYA","version_id":"skv_nQvYsrq-f-ADH1ff-MPmEg"}

Applicability: [{"constraint":"Request schemas or canonicalization semantics change while old records or clients can retry.","technology":"idempotent mutation APIs","version_scheme":"unknown"}]

# 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.

## Supporting basis and limitations

The cited conversation contains reasoned transaction, concurrency, compatibility, rollout, and failure-sequence analysis. No tests were executed.

## Change and rationale

Create focused guidance for version-tagged fingerprints, lossless cross-version comparison, deterministic replay, concurrent retries, and reader-first deployment.

A rollout can otherwise duplicate a committed effect or let changed intent match a legacy key when an old canonicalizer ignores a new effect-relevant field.