Concurrency and Idempotency

The specification identifies the invariant that version coordination protects.

Does the use case name conflicts, invalid state, winner behavior, and caller response?

Marked guidance: a reviewer answers this question.

Unneeded version checks create rejection behavior without a protected business outcome.

ConcurrencyVersionTests link every version check to a documented conflicting-write case.

Marked checkable: the tool named here checks it.

The persistence version detects a competing accepted write against the same aggregate state.

ConcurrencyVersionTests race conflicting aggregate writes with expected versions.

Marked checkable: the tool named here checks it.

A stable response lets callers distinguish a concurrency conflict from validation or authorization failure.

ConcurrencyVersionTests assert a failed expected version returns 409 Problem Details with its stable code.

Marked checkable: the tool named here checks it.

Silent replacement can violate the invariant named by the use-case specification.

ConcurrencyVersionTests assert conflicting accepted writes preserve the winner without silent replacement.

Marked checkable: the tool named here checks it.

HTTP preconditions let a caller send the version that it read.

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

ConcurrencyVersionTests require and validate a strong persistence-derived ETag.

Marked checkable: the tool named here checks it.

Distinct outcomes show whether a caller omitted or supplied an obsolete version. This extends the outcome table of litespec/backend/api#use-consistent-status-codes.

ConcurrencyVersionTests return 428 for a missing If-Match and 409 for a stale version.

Marked checkable: the tool named here checks it.

The ETag is the contract boundary for persistence-version coordination.

ConcurrencyVersionTests assert public transport models expose no provider-specific version field.

Marked checkable: the tool named here checks it.

Tenant, actor, and operation scope prevents one caller's key from replaying another operation. A project without the tenancy extension uses one fixed tenant value.

IdempotencyKeyTests assert keys from different tenants, actors, or operations do not replay each other.

Marked checkable: the tool named here checks it.

One transaction connects the accepted change to the result that later calls replay. It leaves no completed record without its change and no change without its replay record.

IdempotencyKeyTests commit fingerprint, state, response, and expiry with the accepted business change.

Marked checkable: the tool named here checks it.

One client key can represent only one accepted request intent.

IdempotencyKeyTests assert reused keys with changed input return the documented rejection.

Marked checkable: the tool named here checks it.

The constraint selects one accepted winner when concurrent requests use the same key. A project without the tenancy extension uses one fixed tenant value.

IdempotencyKeyTests assert concurrent inserts prove the tenant-actor-operation-key uniqueness constraint.

Marked checkable: the tool named here checks it.

Equivalent requests produce one comparison value without embedding authentication material.

The actor identifier is in the fingerprint. The credential that proved it is not in the fingerprint. Two actors can present the same client key. A fingerprint without the actor lets one actor's replay return another actor's stored response. A bearer token, a cookie, and a signature are the credential, and each one changes between two requests the rule has to treat as equal.

IdempotencyKeyTests assert equivalent mapped requests produce one fingerprint without credentials or client key.

Marked checkable: the tool named here checks it.

A hash preserves comparison behavior while reducing retained sensitive data.

Is sensitive fingerprint source data hashed wherever support needs no original content?

Marked guidance: a reviewer answers this question.

A retry receives the accepted result rather than repeating its state change.

IdempotencyReplayTests return the original accepted status and body.

Marked checkable: the tool named here checks it.

Callers need one documented result while an identical request is still active.

IdempotencyReplayTests prove the documented wait, in-progress, or conflict behavior.

Marked checkable: the tool named here checks it.

The unique-key winner provides the accepted result for all matching retries.

IdempotencyReplayTests reload and replay the matching winner record.

Marked checkable: the tool named here checks it.

A later retry can safely perform the uncommitted operation.

IdempotencyReplayTests leave no business change or completed replay state.

Marked checkable: the tool named here checks it.

An uncommitted operation cannot safely claim an irreversible external effect.

Does every irreversible provider call run only after its business transaction commits?

Marked guidance: a reviewer answers this question.

Durable routing or provider replay protection aligns external effects with retries.

Does each required effect use the outbox or a documented provider idempotency contract?

Marked guidance: a reviewer answers this question.

Retention lasts through the period in which callers can safely retry.

Does the Limit record cover the caller retry window and the business risk?

Marked guidance: a reviewer answers this question.

Bounded maintenance prevents cleanup from overwhelming normal application work.

IdempotencyRetentionTests show bounded deletion of expired idempotency records.

Marked checkable: the tool named here checks it.

Early expiration can turn a retry into duplicate business work.

IdempotencyRetentionTests reject expiration before the documented safe retry time.

Marked checkable: the tool named here checks it.

The list defines the transport result that a completed retry can reproduce.

IdempotencyOutcomeTests match replayed statuses and headers against the declared list.

Marked checkable: the tool named here checks it.

Replay data needs enough information for callers without retaining unnecessary sensitive content.

Does each stored replay field serve the accepted result callers reproduce?

Marked guidance: a reviewer answers this question.

These values are unsafe, transient, or unrelated to the accepted operation result. 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. The replayed response computes its own.

IdempotencyOutcomeTests exclude authentication, transient failures, cookies, hop-by-hop headers, tokens, and secrets.

Marked checkable: the tool named here checks it.