# Versioned Idempotency Across Canonicalization Rollouts

Preserve mutation idempotency when request contracts, defaults, derived inputs, or canonicalization change while old records and mixed-version clients remain retryable.

Exact reference: {"kind":"skill_version","skill_id":"skl_MrDa3St8lIhwmH-3ddyMIA","version_id":"skv_ZbHEBKkJONeZTMC5pM2E3Q"}

Applicability: []

# Versioned Idempotency Across Canonicalization Rollouts

## Trigger

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

## Practical steps

1. Keep one durable unique identity across versions, scoped by a stable authenticated principal or tenant, stable operation, and client idempotency key. Never include request or fingerprint version in this identity.
2. Select the request contract through a trusted protocol discriminator. Define each fingerprint version as the exact semantic domain plus parsing, defaults, normalization, canonical encoding, hash domain, and digest algorithm. Capture any resolved server-derived values or immutable configuration reference needed to reproduce the original intent.
3. For a new key, strictly parse the request under its declared contract, claim the key, apply the business mutation, and store the fingerprint contract, digest, immutable replay outcome, and result version in one transaction. No effect may occur before a request wins the claim.
4. For a duplicate key, wait for the competing transaction, read the committed winner, and let the winner's stored contract select comparison rules. A loser must discard any precomputed current-version comparison and recover without speculative effects.
5. Parse the retry under its own contract, then use an explicit directional, value-aware adapter into the stored semantic domain. Accept only when every effect-relevant distinction is preserved and the historical fingerprint matches. An adapter may be partial: reject unknown, ambiguous, or unrepresentable values.
6. Validate both old-to-new and new-to-old paths. A new field may map to old semantics only when it is non-semantic or equals the uniquely implied historical behavior. An old request may map to new semantics only when old values determine every new semantic field. Never try several fingerprint versions and accept any match.
7. Replay from immutable stored outcome data after identity matches. Ensure the snapshot contains every value required by each supported response renderer. If a response version cannot be rendered without mutable state, replay the original representation or return a compatibility error; never rerun the mutation.
8. Deploy readers, adapters, and renderers before writers across the entire serving fleet. Drain or route around incompatible binaries, prevent unsafe rollback, and retain old records and implementations through the retry and rollback horizon.

## Limits

A digest supplies collision-resistant evidence, not literal equality. Retain canonical bytes as well when exact equality is required.

If a legacy fingerprint erased an effect-relevant distinction and trusted stored intent is unavailable, equivalence cannot be recovered; reject rather than infer it. Unknown versions, mutable historical defaults, or incomplete result snapshots also require rejection or explicitly degraded replay.

External effects require downstream idempotency or a transactional outbox with durable consumer deduplication. Removing a record or verifier before its advertised retry lifetime ends reopens duplicate-effect risk.

## Failure prevented

This prevents a lost response from causing a duplicate committed effect, prevents version changes from creating separate claim domains, and prevents a changed request from matching an old key because historical parsing or canonicalization ignored newer meaning.

## Evidence

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

## Supporting basis and limitations

The cited conversation reasoned through ambiguous commits, versioned fingerprints, mixed old-client and new-client races, lossy mappings, compatible replay, and rollout safety, followed by one independent reasoning review. Support is reasoned analysis only; no code, database, concurrency, or integration tests were executed.

## Change and rationale

Adds captured server-derived semantics, value-aware directional adapters, clean loser recovery, digest evidence limits, and replay-snapshot completeness to the existing mixed-version rollout guidance.

The current skill exactly matches the problem, so an update is preferable to duplicate guidance. The corrected analysis and independent review identified concrete invariants not yet explicit in the current version.