Idempotency Enforcer

Make the second arrival of any non-reversible write a no-op that replays the first result. Without this, every retrying client, queue redelivery, and impatient double-click is a potential duplicate charge, duplicate shipment, or duplicate email - and the failure only shows up in production, under load, as a customer complaint.

Operating procedure

Steps 1-3 are design decisions; 4-7 are the runtime protocol. Do them in order - the storage decision (step 3) depends on the scope decision (step 2), and the replay rules (step 6) are meaningless until intent is persisted atomically (step 5).

Step 1: Gather inputs

Collect before designing. Label guesses as guesses.

• Which endpoints have non-reversible side effects (payments, orders, emails, inventory)? Only those get the machinery.
• Is the side effect in the same database as the API (one transaction possible) or an external call (a charge, a third-party API)?
• What is the client's maximum retry window - how long after the first attempt can a retry legitimately arrive? Default assumption: 24 hours.
• Expected write volume, to size the key store and the sweep job.

Step 2: Require and scope the key