Concurrency and Idempotency

Version coordination exists to protect one invariant. Naming the conflicting operations, the invalid combined result, the expected winner, and the caller-visible response states which invariant that is. An implementation without that document cannot tell a conflict it has to reject from contention it has to absorb.

Reviewed forWhich conflicting-write use cases lack conflicts, invalid state, winner behavior, or caller response? Look at the use case pages.

Marked guidance: a reviewer answers this question.

Every stored aggregate already carries a baseline version that the store compares at commit, so the version itself needs no document. Requiring the caller to supply a version adds a rejection path the caller has to handle: a missing or stale caller version refuses an otherwise valid write. The conflicting-write document stays the gate for that caller burden: no case, no caller-version requirement.

Reviewed forWhich caller-version requirements lack a documented conflicting-write case? Look at the versioned operations beside the conflicting-write documents.

Marked guidance: a reviewer answers this question.

The caller-supplied version marks which write the caller saw, and the stored version marks what the database holds. Comparing the two in the same transaction as the change detects a competing accepted write against the same state, through the selected persistence model. A comparison outside the transaction races the commit it claims to guard.

Reviewed forWhich caller-version comparisons run outside the transaction carrying their change? Look at the conflicting-write paths.

Marked guidance: a reviewer answers this question.

A caller that loses a version race retries: re-read, re-apply, re-send. Status 409 with a stable Problem Details code names the loss as a conflict, distinct from validation and authorization failures. Without the stable code, the caller guesses which failure it met.

Reviewed forWhich failed expected versions miss the 409 Problem Details response or its stable code? Look at the conflict responses.

Marked guidance: a reviewer answers this question.

A conflicting write that silently replaces the accepted change destroys work another caller committed. The losing caller never learns its change is gone. Rejecting the conflict instead hands the caller the facts it needs to reconcile.

Reviewed forWhich conflicting accepted writes silently replace the winner? Look at the conflict outcomes.

Marked guidance: a reviewer answers this question.

The caller reads the current state with its strong persistence-derived ETag and sends it back in If-Match on the write. The server compares what the caller saw with what is stored. The round trip carries the version through HTTP headers instead of a second contract field.

A current ETag permits the write; a changed entity version rejects it.

Reviewed forWhich versioned HTTP operations miss a strong persistence-derived ETag or an If-Match requirement on writes? Look at the versioned endpoints.

Marked guidance: a reviewer answers this question.

A missing If-Match and a stale version are different caller mistakes with different fixes: send the version, or re-read and retry. Status 428 precondition_required names the omission and 409 version_conflict names the stale version. One code for both would leave the caller guessing which fix applies.

Reviewed forWhich versioned operations return a wrong status or code for a missing If-Match or a stale version? Look at the precondition responses.

Marked guidance: a reviewer answers this question.

The ETag is the one contract field that carries the persistence version. A provider-specific version leaked into another field gives callers a second version to depend on. Hiding it keeps the coordination behind one boundary the project can change.

Reviewed forWhich transport models expose a provider-specific version value outside the ETag? Look at the public transport models.

Marked guidance: a reviewer answers this question.

Authorization and validation run first, so a denied or invalid attempt neither consumes a client key nor replays a stored result. The handler runs after, so a replayed key returns the stored response without executing the handler again. Any other order either spends keys on attempts the pipeline would refuse or executes work the store already accepted.

Reviewed forWhich idempotent operations run idempotency outside a pipeline stage after authorization and validation, before the handler? Look at the pipeline stage order.

Marked guidance: a reviewer answers this question.

A client key alone proves nothing about who sent it: two callers can pick the same key. Scoping the key to tenant, authenticated actor, and operation stops one caller's key from replaying another caller's operation. A project without the tenancy extension uses one fixed tenant value.

Reviewed forWhich idempotent operations scope their client key to less than tenant, authenticated actor, and operation? Look at the keyed operations.

Marked guidance: a reviewer answers this question.

The fingerprint, state, response status, response body, and expiry describe the accepted change, so they commit with it in one provider transaction. One transaction leaves neither a completed record without its change nor a change without its replay record. A retry then replays exactly what the first attempt accepted.

Reviewed forWhich idempotent operations store fingerprint, state, response, or expiry outside the business transaction? Look at the keyed write paths.

Marked guidance: a reviewer answers this question.

A key reused with a different request fingerprint names two different intents under one key. Accepting both would replay the first intent's result for the second intent's request. Rejecting the reuse keeps one key bound to one intent.

Reviewed forWhich reused keys with a changed fingerprint miss the documented rejection? Look at the key-reuse paths.

Marked guidance: a reviewer answers this question.

Two concurrent requests can arrive with the same key before either commits. The unique constraint on tenant, actor, operation, and client key admits one winner and rejects the other at the store. Application code alone cannot order two requests that arrive together. A project without the tenancy extension uses one fixed tenant value.

Reviewed forWhich idempotency stores lack the unique constraint on tenant, actor, operation, and client key? Look at the idempotency store schema.

Marked guidance: a reviewer answers this question.

The fingerprint decides whether two requests under one key carry the same intent. Canonical mapped command input, route identity, and the authenticated actor identifier make equivalent requests produce one value. The actor identifier is in the fingerprint because two actors can present the same client key, and a fingerprint without it would replay one actor's stored response to another. The credential that proved the actor stays out: a cookie and a signature each change between two requests the rule treats as equal.

Reviewed forWhich fingerprints miss canonical input, route identity, or actor identifier, or include credentials or the client key? Look at the fingerprint derivation.

Marked guidance: a reviewer answers this question.

The fingerprint needs to compare requests, not to show what they contained. A cryptographic hash preserves the comparison while the original sensitive content stays out of the store. Support keeps original content only where it needs the original to help.

Reviewed forWhich idempotency stores keep original sensitive request content that support never needs? Look at the fingerprint store.

Marked guidance: a reviewer answers this question.

The first attempt performed the state change, and the retry performs it no second time. Returning the original response status and body gives the retry the accepted result. The caller sees one execution no matter how many times the network retried.

Reviewed forWhich completed idempotent retries return other than the original response status and body? Look at the replay paths.

Marked guidance: a reviewer answers this question.

An identical request can arrive while the first is still running. The use case states whether the concurrent request waits, learns the work is in progress, or receives a stable conflict. Without one documented result, each implementation invents its own and callers handle all of them.

Reviewed forWhich idempotent use cases leave concurrent-request behavior undefined? Look at the idempotent use case pages.

Marked guidance: a reviewer answers this question.

The unique constraint admits one winner among concurrent same-key requests. A losing request whose fingerprint matches reloads the winning record and replays its result. The loser then returns the accepted outcome instead of an error for work that succeeded.

Reviewed forWhich losing concurrent requests with a matching fingerprint miss the reload and replay of the winner? Look at the concurrent retry paths.

Marked guidance: a reviewer answers this question.

A request that fails before commit changed nothing, so it leaves neither the business change nor a completed replay record. A leftover completed record would replay success for work that never happened. Clean state lets a later retry perform the operation for the first time.

Reviewed forWhich failed pre-commit requests leave a business change or a completed replay record? Look at the failure paths.

Marked guidance: a reviewer answers this question.

A provider call that cannot be undone follows the commit. A call made before commit fires even when the transaction then rolls back. The business change would vanish while its external effect stands.

Reviewed forWhich irreversible provider calls run before their business transaction commits? Look at the idempotent operation paths.

Marked guidance: a reviewer answers this question.

A required external effect has to survive retries without duplicating. The outbox extension delivers it durably after commit, or a documented provider idempotency contract lets the provider absorb the replay. An effect with neither path fires once per retry.

Reviewed forWhich required external effects use neither the outbox nor a documented provider idempotency contract? Look at the idempotent operation paths.

Marked guidance: a reviewer answers this question.

A key that expires too early turns a legitimate retry into duplicate business work. Retention therefore spans the caller retry window plus the business risk of a late duplicate. The setting record states that span where reviewers and operators read it.

Reviewed forWhich key retentions miss the caller retry window or the business risk? Look at the setting record beside the idempotent use case.

Marked guidance: a reviewer answers this question.

Expired keys accumulate without cleanup, and cleanup without bounds steals capacity from live work. A bounded maintenance process removes expired records within fixed limits on rate and batch. The store stays small without starving the application.

Reviewed forWhich expired-record cleanup runs outside a bounded maintenance process? Look at the cleanup jobs.

Marked guidance: a reviewer answers this question.

Callers retry inside a documented window after an uncertain response. A key expired inside that window is gone when the retry arrives, so the retry executes as new work. Retention covers the whole window the project promises.

Reviewed forWhich keys expire before the documented safe retry time? Look at the retention settings beside the idempotent use cases.

Marked guidance: a reviewer answers this question.

A completed retry reproduces the stored statuses and headers instead of the live ones. The declared list states which statuses and headers the store holds. A reviewer reads the list to learn exactly what a retry can return.

Reviewed forWhich idempotent use cases list no stored statuses and headers for replay? Look at the idempotent use case pages.

Marked guidance: a reviewer answers this question.

The store holds what a retry needs to reproduce the accepted result and nothing more. Each extra field widens the sensitive data held under the key's retention. A field that serves no replay need stays out.

Reviewed forWhich stored replay fields serve no accepted result callers reproduce? Look at the replay store.

Marked guidance: a reviewer answers this question.

Authentication failures and transient server failures describe one exchange rather than the accepted result, so replaying them answers a new request with an old failure. Tokens, secrets, cookies, and hop-by-hop headers each belong to the exchange that produced them. The caching headers are computed for the response that produced them: replaying them hands a later caller freshness instructions from an earlier moment. RFC 9111 makes each one a property of the exchange rather than of the result, so the replayed response computes its own.

Reviewed forWhich replays return authentication failures, transient failures, cookies, hop-by-hop headers, tokens, or secrets? Look at the replayed responses.

Marked guidance: a reviewer answers this question.