A customer presses Confirm. The order succeeds. The response disappears somewhere between the service and the browser. The customer tries again and receives a second order.
The implementation request sounds small: make retries safe. The organizational problem is larger. Who defines a duplicate? How long should the system remember a request? Which team owns the checkout client’s behavior? Who can accept the operational cost of retaining the result?
This chapter follows one change across the book. Northstar, its people, artifacts, incidents, and measurements are fictional. All numbers are illustrative design choices, not research findings or a production recipe. The case is deliberately incomplete as a payments implementation: it models order creation in a sandbox, with no external charge side effects. A real payment workflow also needs provider reconciliation and recovery across systems.
- ORD-42 → ADR-17Define the outcome; agree on retry semantics.
- CTX-42 + CHANGE-42Resolve source authority and Checkout's response.
- Sandbox implementationSequential tests pass. Independent concurrency check fails.
- Reject → correct → recheckEnforce atomic order creation; test crash behavior.
- Review and bounded trialKeep production access outside the agent's authority.
The boundary
Northstar has a Checkout team, an Orders team, and a small Platform team. Mara owns Orders. Luis owns the checkout client. Priya reviews reliability. Those are responsibilities in this case, not a recommended organization chart.
Support has three reproducible reports of duplicate sandbox orders following a simulated lost response. The team does not know the production incidence. It refuses to turn three reports into a percentage of customers affected.
Mara opens ORD-42 with the outcome: a retry of the same authorized request must not create another order within the agreed retention window. She records an alternative: disable retries and ask customers to inspect order history. That option costs less to implement but leaves the failure confusing. The team chooses server-side deduplication for a bounded pilot, not a new orchestration platform.
Agree on meaning before splitting work
The teams accept ADR-17:
- A client supplies a stable key for one intended order and reuses it when retrying that request.
- The server scopes that key to the authenticated account and endpoint. It rechecks authorization before replaying a stored response.
- Matching key and payload return the recorded outcome. A changed payload with the same key is rejected as a conflict.
- Concurrent matching requests must not create two orders. The order and deduplication result commit within one database transaction in this simplified case.
- The illustrative retention window is 24 hours. After expiry, reuse can create a new order; clients must not silently retry an old intent indefinitely.
These decisions are not details for two independent agents to guess. They are the shared interface.
The executable ticket records acceptance cases. The decision record preserves why this boundary was chosen. Neither artifact authorizes a production release.
Supply context without supplying the company
The execution run receives bundle CTX-42: the approved task revision, ADR-17, Orders ownership, the sandbox schema, authentication rules, and the release policy. Each source has a revision and owner. The raw customer reports are replaced with synthetic reproductions.
A search result also contains an abandoned proposal to deduplicate by email address. That document remains useful historical evidence, but is explicitly superseded. It cannot override the accepted account boundary.
The hierarchy answers which rules govern. The dependency graph identifies Checkout as a consumer. The bundle is the specific selection given to this run. The knowledge chapters explain why those are different objects.
A communication contract with an actual recipient
Mara publishes CHANGE-42, a proposal routed to Luis and Priya. It names the client change, payload semantics, proposed pilot, and evidence required from each team. Acknowledgement means the owner has received the request. It does not mean agreement or completion.
Luis objects to an early proposal that generated a fresh key on every retry. The contract stays blocked while that behavior is corrected. Had he missed the response deadline, Mara would have escalated the dependency instead of interpreting silence as consent.
The record is small. Its value is that the next action is unambiguous.
Execute inside the sandbox
An implementation agent works in an isolated checkout with synthetic data and no production credentials. It may edit the Orders handler, repository layer, and relevant tests. It may propose the schema change but cannot apply a production migration. A second task prepares client contract cases after ADR-17 is accepted.
The coordinator runs integration checks against the combined revision. Passing both branches separately would not establish that client and server agree.
The first implementation passes sequential retry tests. An independently prepared concurrency case fails: both workers read a missing key before either writes the order. The team rejects the patch. It does not rename the failing test as an unrealistic edge case.
The correction uses a database-enforced uniqueness boundary and a transactional result path. Crash cases test failure before commit and after commit but before the response. These checks establish evidence about the chosen database and test environment. They do not prove every deployment behavior.
Review the result and the authority
The review packet identifies the exact code revision, context revisions, commands, observed results, known limitations, and rollback plan. Priya checks the race correction. Luis verifies that retries retain the key. Mara owns the decision that the remaining limitations are acceptable for a sandbox trial.
One attractive shortcut is rejected: adding production credentials so the agent can “verify everything.” The team can improve the test environment without expanding the agent’s authority.
The evaluation chapter explains the evidence layers. Human in the Loop explains who may act on that evidence.
Release is not a Git revert
Before any real rollout, the owner would need an approved migration, representative load testing, observable conflict and replay behavior, and a verified recovery procedure. Northstar’s fictional pilot starts with synthetic traffic. Its gate is zero duplicate order side effects in the prescribed concurrency and crash cases, not a claim of zero possible defects.
If a later pilot reveals unexpected conflicts, the owner pauses expansion and disables admission to the new path. Existing retained keys still need to be honored. Deleting the deduplication table would make retries unsafe; reverting application code does not erase that obligation. Orders already created require reconciliation, not wishful rollback.
This is why reversibility belongs in the specification, before the patch exists.
What the organization retains
The concurrency failure produces EVAL-42, a regression case owned by Orders. The team adds a short note to its repository guidance: concurrent claims require an atomic boundary. It does not promote a service-specific SQL pattern into company-wide policy.
The rejected client behavior updates the cross-team contract example. A narrated review becomes a consented learning exercise with synthetic inputs. The next retrospective checks whether another engineer can identify the race without being told where it is.
The change is technically complete when the agreed evidence supports the accepted scope. The learning work is complete only when the retained correction changes a later decision or check.
The artifact trail
| Artifact | Accountable owner | Question it answers |
|---|---|---|
| ORD-42 | Mara | What outcome are we asking for, and what is excluded? |
| ADR-17 | Mara, with Luis and Priya consulted | Which semantics were accepted, and why? |
| CTX-42 | Run coordinator | Which source revisions informed this attempt? |
| CHANGE-42 | Mara; recipient actions owned separately | Who must respond or change something? |
| EVAL-42 | Orders reliability owner | Which failure must future changes continue to detect? |
| Release record | Named release owner | What was authorized, observed, paused, or rolled back? |
These can be sections of an issue and a pull request. Six identifiers do not require six tools. A small team can keep the same meaning with far less administration.
To adapt the case, choose one recent change and reconstruct this trail. Where evidence is missing, record the gap. Do not rewrite the past to make the model look successful.