Specify the integration boundary before the first write.
Day one, the happy payload writes fine. Then a retry doubles a side effect, one side updates and the other doesn't, and nobody can say which fields were ever meant to cross. Decide what may and must never be written before the first real write.
Before two systems exchange writes, fill the TWIMCO Integration Boundary Spec: allowed writes, forbidden writes, conflict owner, idempotency expectation, and partial-write shape. If conflict ownership or partial-write behavior is blank, you are not ready to connect—you are ready to design the boundary.
The failure is at the boundary
Two systems "integrate." The happy payload writes. Then a retry doubles a side effect. A conflict has no owner. One side updated and the other did not. Nobody can say which fields were ever allowed to cross.
The boundary is the design. What may be written. What must never be written. Who owns a disagreement. What makes a retry safe. What a half-finished write looks like to a person. Skip that and you have shipped a pipe.
Fill the forbidden list first
One page, before the first write.
Allowed writes. The fields this edge may change, and in which direction.
Forbidden writes. Start here. The fields that would create a second charge, a second shipment, or a lie on a customer's screen.
Conflict owner. Who decides when the two sides disagree, by field family, not by whoever is loudest in chat.
Idempotency. What key makes a retry safe. If you do not have one, do not turn retries on.
Partial write. What a person sees when only one side landed, and what the safe next action is. Undo, retry, or park.
If conflict or partial-write is blank, you are not ready to connect. You are ready to finish the page.
How the work moves
Fill the boundary before the pipe
- Allowed writes
Exact resources and fields that may cross.
- Forbidden writes
What must never cross—even if easy.
- Conflict owner
Authority by field; role for exceptions.
- Idempotency
Keys, replay rules, no duplicate harm.
- Partial-write shape
Visible state, compensation, who is paged.
An integration without a forbidden-write list will invent one in production—poorly.
Write it in one sitting
Do the riskiest edge, with someone from each side in the room. Read the forbidden list out loud. If either side is surprised, the list was doing its job.
Keep the page with the edge, under a name both teams use. A spec that lives only in the vendor's drive is not yours.
When the schema changes, the page changes in the same week. A stale forbidden list is how last year's caution becomes this year's incident.
What you are preventing
An SDK that encourages wide writes, and production that invents the regret. Conflicts resolved by chat. Retries that duplicate money. One ledger updated and the other never, while the customer sees a confident status.
Those are ordinary. The page is how you decide them before they decide you.
Put this into practice
Copy the five fields. Fill the forbidden list on your riskiest edge this week. Name the conflict owners. Define the partial-write state before you enable retries.
That design is business process automation when the hard part is the handoff, not the happy payload.
Related work: Sutton Place.
Decision guide
Pipe without a boundary vs specified edge
| Consideration | Connected quickly | Boundary specified |
|---|---|---|
| Writes | Whatever the SDK exposes. | Allowed list; forbidden list enforced. |
| Conflicts | Slack thread archaeology. | Named authoritative side and exception role. |
| Retries | Blind replay. | Idempotency keys and replay rules. |
| Half failure | Undetected divergence. | Documented state and compensation. |
We build alongside the people doing the work.
Bring us the problem you’re thinking about.