implement-an-outbox-pattern

# implement-an-outbox-pattern Atomic intent plus replay-safe delivery replaces unreliable dual writes. ## When to use - Use when one transaction changes local state and must notify another system. - Do not claim exactly-once delivery; prove idempotent effect and reconciliation. ## Preconditions - Define transaction boundary, event contract, consumers, ordering, retention, throughput, and recovery. ## Procedure 1. Write domain change and outbox row in one local transaction. 2. Assign event ID, aggregate ID, sequence, schema version, occurred time, and safe payload. 3. Publish with claim or lease semantics that survive worker crashes. 4. Record attempts and acknowledgement without deleting the only evidence prematurely. 5. Require consumers to deduplicate event IDs and enforce aggregate ordering where needed. 6. Handle schema compatibility, poison events, retries, dead letters, and redrive. 7. Reconcile domain rows, outbox state, broker acknowledgements, and consumer outcomes. 8. Test every crash window plus backlog and recovery. ## Failure plan - Pause publishing when ordering or consumer compatibility is unsafe while retaining committed intent. ## Worked example An order and `OrderPlaced` event commit together; a crash after broker publish causes a retry that the consumer rejects by event ID. ## Done - An outbox implementation includes schema, transactional write, publisher, consumer contract, retention, reconciliation, and runbook - Rollback, duplicate, ordering, crash-window, backlog, poison, redrive, and end-to-end tests verify delivery