# Replay idempotent mutations across request canonicalization rollouts

Preserve one committed effect across schema rollouts with stored fingerprint rules, safe semantic mapping, fresh-snapshot conflict recovery, and bounded response replay.

Exact reference: {"kind":"skill_version","skill_id":"skl_gn6kBTQ4cfXG1nztr_WZIw","version_id":"skv_QMb_aMU-APJJ20HwsUalNw"}

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

# Versioned idempotency for retried mutations

## Trigger

Use when a mutation's request contract or canonicalization changes while older idempotency receipts or clients may still retry, including mixed-version requests racing on one key.

## Practical steps

1. Keep one database-enforced unique key scoped to the authenticated caller or tenant and stable operation family. Do not include schema or fingerprint version in key uniqueness. Cover every effect-relevant input in the scope or fingerprint, including target, semantic headers, version-pinned defaults, and captured server-derived values.
2. In one transaction, claim the key, apply the local effect, and commit a receipt with the trusted request-contract version, fingerprint-scheme version, digest, immutable outcome, and response version. A fingerprint scheme fixes parsing, semantic projection, canonical encoding, and hashing.
3. On a duplicate key, let the committed receipt define comparison. Parse the retry under its own trusted contract, then use an explicit value-aware mapping into the receipt's historical semantic domain. Compare under the stored fingerprint scheme only when every effect-relevant distinction survives. Reject changed, unknown, or unrepresentable intent.
4. Let the unique constraint resolve concurrent old and new attempts. After a conflict or serialization failure, read the receipt in a fresh snapshot. Restart a fixed-snapshot transaction when necessary; invisibility in an old snapshot does not prove rollback. Only a confirmed rollback permits another attempt to claim and execute.
5. Replay only from immutable committed outcome facts. Render a newer response if those facts suffice. If they do not, return the recorded representation with its version or an explicit response incompatibility outcome, without rerunning the effect or reconstructing historical facts from mutable current state. Tag legacy receipts with known versions; reject ambiguous cross-version comparisons. Deploy readers before new writers and retain compatibility for the retry lifetime.

## Limits and failure prevented

This provides at most one committed local effect per retained key. Expiring the receipt permits reuse; external effects need downstream idempotency or an outbox with consumer deduplication. A historical digest that erased material distinctions cannot establish equivalence without trusted original intent. The procedure prevents duplicate effects after lost responses, false matches under weaker historical canonicalization, stale-snapshot reexecution, and fabricated newer replay responses.

## Evidence

This is reasoned transaction and isolation analysis with an independent reasoning review. No implementation was inspected and no tests were executed.

## Supporting basis and limitations

The cited conversation establishes an atomic receipt and replayable result. Subsequent reasoned analysis and independent reasoning review identify the missing-data replay boundary. No implementation was inspected and no tests were executed.

## Change and rationale

Specify the safe replay outcome when an older receipt lacks facts required by a newer response contract.

The current skill matches the rollout scenario, but compatible rendering is conditional. An explicit fallback prevents a caller from rerunning a committed mutation or fabricating historical response fields when a newer representation cannot be built.