PAT-PA-002 / SOURCE CONTROLLED
Idempotent shared-mailbox intake pattern
Use this pattern when one email or intake event must produce one authoritative business record even if delivery or execution occurs more than once.
Scope and assumptions
- The trigger can deliver the same logical item more than once.
- The workflow can fail after an external side effect has succeeded.
- Operators may need a controlled replay path.
- The destination can enforce a unique key or accept an atomic reservation.
- The business can nominate the authoritative outcome when historical duplicates exist.
Processing contract
| STATE | MEANING | ALLOWED NEXT STEP |
|---|---|---|
| Received | Unique intake key reserved | Begin controlled processing |
| In progress | One worker owns the active attempt | Record each side effect |
| Complete | Required acceptance evidence exists | Return existing result on replay |
| Duplicate | Key already resolved to a business record | Do not recreate; return reference |
| Reconcile | External outcome is unknown or contradictory | Business-led investigation |
Key selection
- Prefer an upstream business request identifier.
- Otherwise use the Internet Message ID with a source/mailbox namespace.
- If neither is reliable, generate an intake ID before side effects and persist it at the source boundary.
- Retain connector item IDs and a human-readable fingerprint as evidence. Enforce uniqueness through the atomic ledger or destination key.
- Enforce uniqueness atomically in the ledger or destination.
Ordered implementation
- Capture the source key and minimal evidence.
- Attempt the unique ledger reservation.
- On conflict, return the existing ledger/business record state.
- Create or update the business record with the same key.
- Record external identifiers immediately after each side effect.
- Mark complete only when acceptance checks pass.
- Move or archive the message only after completion. The unique key and ledger remain the duplicate controls.
Replay and reconciliation
Replay only from ledger rows whose state and completed effects are known. The replay request must identify the original intake key, current business record, completed effects, proposed repeated effects and approving owner. Treat timeout as unknown outcome until the destination is checked. Never use mailbox forwarding as the recovery mechanism.
Acceptance tests
- Simultaneous duplicate deliveries resolve to one record.
- An action retry after a successful write does not duplicate the write.
- A manual replay returns the existing result or resumes from the recorded state.
- Two legitimate same-subject messages remain distinct.
- Destination throttling leaves visible pending work.
- A second operator can reconcile and replay from this document.
Limits and review
Concurrency control serialises executions. Idempotency also requires an atomic unique key and replay tests that return the existing business record. A pre-create lookup without atomic uniqueness can race. Connector message IDs can change with mailbox operations. Review the key choice, destination constraint, queue capacity, retry behaviour and replay evidence quarterly and after connector/platform changes.