Versioned idempotency across canonicalization rollouts

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

Versioned idempotency across canonicalization rollouts

Trigger

Use when a retryable mutation changes its request schema or canonicalization while older clients or idempotency records remain live.

Practical steps

1. Keep one unique database key for caller, stable operation, and client idempotency key across all versions. Do not include fingerprint version in that key. Commit the receipt, business effect, and immutable result facts in one transaction.
2. Define request identity before comparing retries. Include every accepted field whose change must invalidate the key, even if it does not change the database effect. State whether identity is exact body equality or a documented normalized form. A fingerprint scheme fixes its parser, defaults, identity fields, canonical encoding, and hash domain.
3. Store the generating request contract, fingerprint scheme version, digest, result version, and replay facts. Label legacy receipts with a known generating scheme; never reinterpret their digests as a newer scheme.
4. On a unique-key conflict, wait for the first transaction to commit or roll back. The committed receipt chooses the comparison scheme. Parse the retry under a trusted incoming contract and compare through a mapping that preserves every identity field. Reject changed values, unknown fields, ambiguous defaults, or information the recorded scheme cannot represent. If the first transaction rolls back, a retry may claim the key.
5. Render the committed result for the retrying client from immutable facts. If safe rendering is unavailable, return a compatibility error without repeating the mutation.
6. Before new-version writes, deploy readers and comparators to every serving instance. An older instance must reject a receipt version it cannot understand. Retain both schemes through the retry and rollback horizon.

Limits and failure prevented

A legacy digest that omitted a field required by request identity cannot prove equality. Recover that field from trustworthy durable facts or reject the unverifiable retry. For example, a new client annotation can make a request different even when amount and recipient are unchanged. If literal body equality is required, a legacy receipt needs the original body or an equally complete representation; semantic equivalence alone is insufficient. Retain receipts for the promised retry window. External effects also need downstream deduplication or an equivalent coordinated guarantee.

Shared uniqueness prevents old and new clients from committing the same mutation twice. Complete versioned identity comparison prevents a changed request from falsely matching an old key after a lost response.

Evidence

This is reasoned transaction and rollout analysis with an independent conceptual check. No implementation was inspected and no tests were executed.

The cited conversation contains reasoned transaction and mixed-version retry analysis. An independent conceptual review identified the changed-request-field counterexample and the need for older instances to fail closed. No repository or implementation was inspected, and no tests were executed.

Rationale: The current skill exactly covers schema and canonicalization rollouts, but its effect-relevant comparison can accept a changed non-effect request field. This update makes the comparison policy explicit and preserves the existing transaction, replay, and rollout guidance.