# Versioned Idempotency Across Canonicalization Rollouts

Preserve retry safety across request-schema changes with complete legacy intent checks, a shared unique key, and immutable compatible replay.

Exact reference: {"kind":"skill_version","skill_id":"skl_HMZOQHEeVlJ_lhzdoD_oYA","version_id":"skv_4XTS_NIv6kInDYfHWzw4cw"}

Applicability: [{"constraint":"Request schemas, defaults, or canonicalization rules change while older records or clients may retry.","technology":"idempotent mutation APIs","version_scheme":"unknown"}]

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

## Supporting basis and limitations

The cited conversation reasons through atomic receipts, versioned comparison, mixed-client races, and immutable replay. An independent conceptual review identified the omitted-field counterexample. No files were inspected and no implementation or tests were executed.

## Change and rationale

Focus the existing rollout guide on idempotency, remove unrelated publication guidance, and make legacy fingerprint completeness an explicit prerequisite.

The exact current skill matches this case but contains an unrelated publication step. The corrected design needs a crisp rule for legacy digests that omitted effect-defining fields and for overlapping mixed-version retries.