docs(HT-127): state the event contract's no-ordering consequence - #203

Events emitted in one transaction share an occurredAt exactly (now() is
transaction start time), so conversation.message_received can reach a
consumer before the conversation.created it belongs to. substrate-v1 §4
already granted no cross-event ordering guarantee; it never said what an
integrator has to do about it.

§4 now names the concrete case and the requirement that follows: treat any
event as possibly the first seen for its conversationId, upsert rather than
insert, read state from the API rather than from arrival order. Sorting by
occurredAt does not recover an order — the ties are exact. §8's guarantee
table carries "no ordering" on the emission row too, so it cannot be read
as "the outbox is ordered, delivery is not".

No tiebreak column is added. event_id is a random v4 uuid and created_at is
the same now(), so a tiebreak would take a new sequence — and drainEventOutbox
fans each event to one queue_jobs row per endpoint, each retrying
independently, so claim order does not survive to the consumer regardless. A
deterministic drain would hold in development and break under production
retry, which is worse than no guarantee at all.

claimBatch's interface doc records the same reasoning, and a test pins the
premise the spec text rests on: two events appended in one transaction give
count(DISTINCT occurred_at) = 1.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The claimBatch re-sort compares Date.getTime(), which cannot hold the
column's microseconds, so events under a millisecond apart tie there too —
not only events sharing a transaction. The interface doc named one tie class
and implied it was the only one.

Documented rather than made exact. The sort is best-effort by construction:
spec §4 grants no cross-event ordering guarantee, and per-endpoint retries
reorder deliveries downstream regardless, so a microsecond-exact claim order
would be precision no consumer can observe.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

claimBatch's drain order previously left occurred_at ties (same-
transaction events, or any two events under a millisecond apart)
unordered by design, since no order reaches the consumer regardless.
That left replay non-reproducible for debugging and testing.

(occurred_at, event_id) is a stable total order without adding a
column: event_id is the primary key, so it never ties. This is a
fixed-but-arbitrary tiebreak, not a meaningful one — event_id is a
random v4 UUID uncorrelated with write time. Both the claiming SQL
and the RETURNING re-sort now use it, matching the interface doc
(maintainer decision, 2026-08-08).

A sequence column was considered and declined (maintainer decision,
2026-08-08): the published contract already grants no cross-event
ordering (substrate-v1.md §4), and drain order cannot reach a
consumer regardless — SKIP LOCKED under concurrent drainers, queue
claiming ordered only by run_after with no tiebreak, an UPDATE...
RETURNING with no result-order guarantee, and independent per-
endpoint backoff rescheduling all destroy it downstream.

The interface doc claimed the drain is "reproducible: the same rows
come out in the same order every time" without qualifying that this
only holds for repeated calls against a fixed eligible set. Under
concurrent drainers, SKIP LOCKED partitions eligible rows between
them unpredictably, so no single global order exists across
overlapping calls. The safety property (no double-claim) already
held; only the reproducibility wording overclaimed.