Ordered source data becomes unordered again when queues, retries, and caches can deliver older versions late.
Monotonic Version Gate
Delayed delivery must never make a replicated consumer move backward in committed state.
INSERT INTO tenant_policy (tenant_id, version, document)
VALUES ($1, $2, $3::jsonb)
ON CONFLICT (tenant_id) DO UPDATE
SET version = EXCLUDED.version,
document = EXCLUDED.document
WHERE tenant_policy.version < EXCLUDED.version
RETURNING version;
-- Zero rows means the destination already holds this version or a newer one.
-- Use an authoritative monotonic version, never application wall-clock time.Invariant: A destination accepts a state transition only when its version is greater than the currently committed version.
Use when: Delayed events or cache fills can deliver an older snapshot after a newer one has already committed.
Why this boundary matters
Queues, retries, and cache fills can deliver old state after new state. The destination must enforce ordering at mutation time.
Failure policy
| Boundary | Action |
|---|---|
| Incoming version is newer | Apply atomically with the version |
| Incoming version equals current | Return the existing result idempotently |
| Incoming version is older | Reject or ignore and record regression |
| Version gap appears | Apply only if snapshots are complete; otherwise request repair |
| Version authority unavailable | Do not invent an ordering value locally |
Trade-offs
A monotonic gate prevents regression but does not guarantee that every intermediate event is processed. Strict gap detection improves auditability while increasing repair traffic and coupling to the source log.
Decision rule: Use version gates for replaceable snapshots and last-write state; use an ordered log plus gap recovery when every transition matters.
Further reference
Browse all engineering snippets · Read the architecture guide