Six state machines govern the protocol's runtime behaviour. Each is documented with its states, its transitions, the invariants that hold across them, and the failure modes that the current shape exists to prevent.
| Document | Governs |
|---|---|
| Delivery and acknowledgements | What happens to an inbound frame, and when a receiver acknowledges |
| Outbox and retries | What happens to an outbound message from send to terminal state |
| Session lifecycle | 1:1 MLS session establishment, confirmation, desync, and heal |
| Group message lifecycle | A group message from send through fan-out, buffering, and drain |
| Transport lifecycle | Transport availability, scoring, switching, and escalation |
| Document replication | A document from edit to durable record, a space from offer to convergence, an attachment fetch to one of six ends |
Each document states its invariants first. The invariants are the part that survives refactoring; the state names are not.
Where a transition exists to prevent a specific failure, the failure is named. Several of these shapes look over-engineered until you know which bug they close, and the surrounding prose is there so a future change does not undo one by accident.
Custody of an undelivered message stays with the sender until a receiver positively confirms it.
Every acknowledgement decision, every buffering decision, and every deduplication decision in these documents is downstream of that. When a receiver cannot yet deliver a frame, the correct move is to withhold the acknowledgement and let the sender keep custody, not to acknowledge and hope.
The corollary matters to application teams: because acknowledgements are withheld on recoverable failures and re-sent on recovery, a missing acknowledgement is not proof of non-delivery.
Document replication inherits it rather than restating it: a sync frame is an ordinary message on the same ladder, which is why that layer needed no delivery machinery of its own.