CORE GUIDE
Idempotency boundary
Repeated attempts should represent the same business intent instead of silently creating a new side effect each time.
Mental model
A stable operation identity distinguishes a retry of the same intent from a genuinely new intent.
Why it matters
Networks retry, workers restart and agents re-plan. Without an idempotency boundary, the same user intent can create duplicate orders, messages, charges or refunds. The protection has to live at the side-effect boundary rather than in optimistic model reasoning.
01
Give business intent a stable identity
The caller assigns an idempotency key or operation ID when one side-effecting intent is created. The receiver records the result for that identity and returns the same outcome for repeated attempts. That identity must survive network retries, process restarts and agent re-planning.
02
Example: one click, two HTTP attempts
A user clicks Buy once. The first request times out, so the client retries. If both attempts carry the same order-intent ID, the server can return the original order instead of creating a second one.
Common failure modes
- Creating a new idempotency key for every retry.
- Scoping the key only to an HTTP attempt rather than the business intent.
- Using compensation as a substitute for preventing avoidable duplicates.
Engineering heuristics
- Place the identity at the business side-effect boundary.
- Persist the operation identity wherever retries can originate.
- Test timeout, restart and partial-success paths explicitly.
Takeaways
- 01Identity should be stable before retry timing is considered.
- 02One intent should have one operation identity.
- 03Idempotency and reconciliation work together for ambiguous outcomes.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.