Normative specification · SPEC-014
Dispatcher routing and failure behavior
This specification defines how an accepted event is assigned to one queue, how quickly the gateway must return, and what implementations must prove before conformance.
Scope
This specification begins after the gateway accepts and validates POST /events. It ends when the dispatcher writes the event to ingest-a or ingest-b, or records a bounded shed result.
Authentication, payload schema, warehouse writes, batch ingestion, and global ordering are outside this specification.
Definitions
- Accepted event
- An event whose caller, envelope, and required fields passed gateway validation.
- Partition
hash(event.id) mod 2; even routes to A and odd routes to B.- Shed
- A bounded refusal to enqueue on an unavailable selected queue, recorded for retry.
- Healthy path
- The selected queue and consumer group are available and below their alert thresholds.
Normative requirements
REQ-001
Exactly one destination. The dispatcher MUST assign every accepted event to exactly one queue.
REQ-002
Deterministic partition. Assignment MUST be a function of event ID alone and MUST remain stable across retries.
REQ-003
Bounded gateway wait. A selected queue failure MUST NOT hold the gateway request longer than 200 ms.
REQ-004
No payload persistence. The dispatcher MUST NOT inspect domain fields or persist event bodies.
REQ-005
Observable outcome. Every enqueue or shed MUST increment the matching partition counter and retain the request ID.
REQ-006
Independent health. Failure of one queue MUST NOT prevent writes to the other queue.
Worked examples
routingevent.id = "evt_01"
hash(event.id) mod 2 = 0
destination = ingest-a
result = enqueuedevt_01 resolves to the same queue.failureevent.id = "evt_02"
destination = ingest-b
ingest-b = unavailable
gateway wait = 187 ms
result = INGEST_SHEDCompliance matrix
| Requirement | Evidence | Gate |
|---|---|---|
| REQ-001–002 | Fixed-vector unit test across 10,000 IDs and retries | All assignments stable |
| REQ-003 | Selected queue unavailable during load test | p99 gateway wait below 200 ms |
| REQ-004 | Code review and storage inventory | No body access or dispatcher store |
| REQ-005 | Dashboard and trace fixture | Every outcome correlated |
| REQ-006 | One-queue-down chaos test | Healthy path continues accepting |