Idempotent event consumers

The core invariant

Applying the same event twice must have the same externally visible result as applying it once. This is a property of the effect, not merely of a message broker setting.

Processing checklist

1. Validate the envelope and schema version.
2. Look up the stable event ID.
3. Apply the effect and record completion in the same transaction when possible.
4. Commit the consumer offset only after durable success.
5. Bound retries and retain failed events for investigation.

Failure window

If a remote effect succeeds but recording completion fails, retrying may repeat the effect. Use a downstream idempotency key or a durable reconciliation workflow.

See designing for replay.