A reused key with a different payload replays the first result: store a fingerprint

[AlexeyShalaev]

Measured on 0.2.0 with the Redis repository. After a charge of 1999 was recorded under key order-42, the same key came back with a different amount:

--- the same key again, with a different amount ---
requested amount 5, got back: charge_id='ch_1' amount=1999

Rule 1 on the agents page says the arguments are not part of the identity, so this is documented, and for a well-behaved client it never happens. It happens with a client that reuses keys by mistake (a key derived from the order id, then a second, different operation on the same order), and today the library answers such a request with a result for a different request and no signal that anything is off. Stripe rejects this with a 422 ("keys are for identical requests"), and I think that is the right shape.

Proposal: an optional fingerprint on the record. coordinate() takes fingerprint: str | None = None; the decorator takes a way to derive one from the call (a callable over the bound arguments, or a tuple of parameter names whose values are hashed after model_dump(mode="json") for Pydantic models). The fingerprint is stored on IdempotencyRecord (fingerprint: str | None, so existing records stay readable) and compared on a hit; a hit with a different fingerprint raises a new IdempotencyKeyReuseError carrying both fingerprints. That one must propagate through the coordinator rather than be swallowed: it is a caller error, not storage trouble, and rule 6 is about storage. No fingerprint supplied means today's behaviour, key only.

Script: measure.py in https://github.com/bedrock-python/bedrock-python.github.io/tree/docs/production-python-series/docs/blog/lab/2026-09-07-idempotency-keys. Related: the in-flight reservation issue filed alongside this one.

[AlexeyShalaev]

Reproduced on master with your script: requested amount 5, got back: charge_id='ch_1' amount=1999. The plan, built on top of #28 since both touch the coordinator and the record.

The record gets fingerprint: str | None = None, stored beside the result, so records already in Redis stay readable and mean "no fingerprint". coordinate() takes it as a keyword-only argument, idempotency_fingerprint: str | None = None, declared after *args so it stays out of the action's **kwargs. That name rather than fingerprint because everything keyword-shaped in coordinate() is forwarded to the action, so the name is one the action can never have again — and fingerprint is a plausible parameter in the auth-shaped services this is used in (a device fingerprint), where idempotency_fingerprint mirrors idempotency_key and is not. On a hit, or on a pending record from #28, the stored fingerprint is compared with the caller's: different means IdempotencyKeyReuseError, which carries operation, key, stored_fingerprint and fingerprint and propagates out of coordinate() and the decorator — a caller error, not storage trouble, so rule 6 keeps its meaning and the HTTP layer maps it to 422 as Stripe does. Comparing against the pending record matters: a waiter with a different payload is refused at once instead of waiting for someone else's result. Either side missing means no comparison: a record without a fingerprint never raises, and a caller without one gets today's key-only behaviour, so nothing changes for anyone who does not opt in. In in_flight="run" mode the check happens on the read before the action; the collision path after the action only logs a mismatch and returns the caller's own result, because raising after the side effect would make the caller retry a completed operation.

The decorator gets fingerprint_params: tuple[str, ...] | None = None, naming the parameters whose bound values make the fingerprint, in the same shape as key_param and infra_param. It binds the call against the signature with defaults applied, so an argument passed explicitly at its default value and one omitted fingerprint the same; turns the values into JSON-able Python with pydantic's to_jsonable_python, which covers Pydantic models, dataclasses, UUIDs, datetimes and Decimals without a special case per type; serialises with sorted keys and no whitespace so two equal dicts built in different orders agree; and takes the SHA-256 hex, a 64-character string that no payload size can bloat the record with. A name not in the signature, or a signature inspect cannot describe, raises TypeError at decoration time — a programming error should fail at import. A caller who wants some other notion of "same request" computes a string and passes it to coordinate() directly; I am not adding a callable form to the decorator alongside the tuple, since the tuple covers the case in the issue and one shape is easier to hold in the head than two.

I considered hashing every argument by default, which would close this class of mistake for everyone without asking, and rejected it: a request often carries something that legitimately differs between identical retries (a timestamp, a trace id, self), and a default that rejects honest retries as key reuse is worse than the documented status quo. Opt-in per operation, with the parameters named, is the version that does not surprise anyone. Rule 1 on the agents page stays true — the key is the identity — and gains the fingerprint as the guard against the identity being wrong; the errors table, the record, the decorator signature and the user guide follow, and the PR will show your script with a fingerprint passed on the reused-key run raising IdempotencyKeyReuseError.

[AlexeyShalaev]

#30 is up, rebased onto master now that #28 is in. A copy of your script with fingerprint_of(amount=...) passed on each call, against that branch:

--- the same key again, with a different amount ---
requested amount 5, got: IdempotencyKeyReuseError: Idempotency key 'order-42' for operation 'payment.charge' was used for a different request: stored fingerprint '52e7a9b6...', got '7e84cbf0...'
charges made by the provider: 1 -> ['ch_1']

It is the plan as posted: fingerprint on the record, idempotency_fingerprint= as the one keyword coordinate() keeps for itself, fingerprint_params=("dto",) on the decorator, and fingerprint_of(**values) exported so both paths hash the same way. The comparison is on the read, pending record included, so a retry with another payload is refused before the action and before any waiting; either side without a fingerprint means no comparison, so your unmodified script still gets the 1999 charge back on the reused key — key-only, as rule 1 always said — and nothing already in Redis needs touching.

On your side: name the parameters that identify the request on each decorated operation, and map IdempotencyKeyReuseError to 422 next to the 409 for IdempotencyInProgressError. Leave timestamps and trace ids out of fingerprint_params, or every honest retry becomes a reuse; rule 23 on the agents page says the same.