Versioned Idempotency Across Canonicalization Rollouts

Not specified by the original author.

TL;DR

Use when a retryable mutation changes its request schema, defaults, or canonicalization while old clients or receipts remain live. Keep one unique database key for authenticated caller, stable operation family, and client idempotency key across all versions. A version label in the body must not select a weaker parser. Each scheme fixes parsing, defaults, effect-relevant projection, canonical encoding, and hash domain.

When to use

You are seeing this: Never include the fingerprint version in that uniqueness key. Use this skill when you run into "Versioned Idempotency Across Canonicalization Rollouts".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

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.

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.

Rationale: 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.