Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m58s
Foundation / checks (client) (push) Failing after 9m57s
Foundation / checks (network) (push) Successful in 11m17s
Foundation / checks (tsan) (push) Successful in 7m49s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 25m43s
Foundation / checks (postgres) (push) Canceled after 15m44s
Session protocol v2 adds Interest, SnapshotChunk and SnapshotAck (v1 is refused). ReplicationServer filters by a server-capped client focus and a perception predicate, sends per-tick entity deltas against the acknowledged baseline (kept up to 40 ticks), nearest first within 16 KiB with a slower distant tier, as self-contained datagram chunks. SnapshotAssembler applies complete snapshots to one of two baselines and validates them as presentations. ADR-0093. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
79 lines
5.1 KiB
Markdown
79 lines
5.1 KiB
Markdown
# M10 session protocol, version 1
|
|
|
|
**Superseded by [version 2](session-v2.md) (ADR-0093, 2026-10-06).** Kept as the record of
|
|
what was deployed in evolution-dev from 2026-10-05; servers built since refuse version 1.
|
|
|
|
Login, session control, intentions and actions over QUIC (ADR-0090 transport, ADR-0091
|
|
identity, ADR-0092 intentions and actions). Implemented by `encode_session`/`decode_session`
|
|
(include/evo/network/session_protocol.hpp), `RegionSessions` (server) and
|
|
`RegionSessionClient` (client). Stream messages are one framed QUIC reliable message
|
|
each; types 6-8 travel as one QUIC DATAGRAM each, and only after Welcome.
|
|
Integers little-endian. Every message has a fixed length for its type; any other length,
|
|
magic, version, nonzero flags, unknown type or out-of-range value is refused, and the
|
|
server then sends Close (`unsupported_version` for another version, otherwise
|
|
`protocol`) and closes the connection. v1 was amended in place once, before deployment, by
|
|
M10.4 (types 6-12, Welcome server_tick). **Frozen since 2026-10-05**: v1 is deployed in
|
|
evolution-dev (ADR-0087 route); any change to a message, value or rule needs a new
|
|
version.
|
|
|
|
## Header (8 bytes)
|
|
| Offset | Size | Field | Rule |
|
|
|---|---|---|---|
|
|
| 0 | 4 | magic | bytes `EVSN` |
|
|
| 4 | 2 | version | 1 |
|
|
| 6 | 1 | type | 1..12 below |
|
|
| 7 | 1 | flags | 0 |
|
|
|
|
## Messages
|
|
| Type | Direction | Payload | Size |
|
|
|---|---|---|---|
|
|
| 1 Hello | client -> server | required_features u32 (0), grant (session-grant-v1, 160 bytes) | 164 |
|
|
| 2 Welcome | server -> client | session, epoch, world, frame, region, expires_at, server_seconds, server_tick (u64 each; session and epoch nonzero) | 64 |
|
|
| 3 Refresh | client -> server | newer grant for the same account (160 bytes) | 160 |
|
|
| 4 RefreshResult | server -> client | status u8 (0 accepted, else a close reason value), expires_at u64 | 9 |
|
|
| 5 Close | either | reason u8 | 1 |
|
|
| 6 Intention | client -> server, datagram | session, epoch, sequence, tick (u64), move_x, move_y (i16) | 36 |
|
|
| 7 IntentionReceipt | server -> client, datagram | sequence u64, status u8, server_tick u64 | 17 |
|
|
| 8 SimulatedThrough | server -> client, datagram | epoch, sequence, tick (u64) | 24 |
|
|
| 9 Action | client -> server | session, epoch, action_id (u64), kind u16, tick u64 | 34 |
|
|
| 10 ActionReceipt | server -> client | action_id u64, status u8, server_tick u64, tick u64 | 25 |
|
|
| 11 ActionOutcome | server -> client | action_id u64, result u8 (1..4), tick u64, commit_sequence u64 | 25 |
|
|
| 12 ActionQuery | client -> server | action_id u64 | 8 |
|
|
|
|
Admission status (wire 0..10): 0 admitted, 1 unknown_session, 2 stale_epoch,
|
|
3 outside_window, 4 rate_limited, 5 replayed, 6 invalid_vector, 7 too_many_unresolved,
|
|
8 invalid_action, 9 duplicate, 10 not_ready. Action kinds: 1 probe (no effect). Action
|
|
results: 1 committed_no_effect, 2 not_committed (both final), 3 pending, 4 unknown (query
|
|
answers only). Intentions carry no state claims; their vector ranges and every action
|
|
field are checked by admission, which answers with a status rather than closing.
|
|
|
|
Close reasons (wire 1..13): 1 client_closed, 2 superseded, 3 expired, 4 stale_epoch,
|
|
5 unauthenticated, 6 wrong_scope, 7 stale_grant, 8 rate_limited, 9 capacity,
|
|
10 protocol, 11 timeout, 12 unsupported_version, 13 shutdown. Value 255
|
|
(`connection_lost`) is local only and never sent.
|
|
|
|
## Sequence and rules
|
|
- The client sends Hello first, as soon as the pinned QUIC connection is up. The server
|
|
closes with `timeout` if no Hello arrives within 5 s of connecting, and refuses any
|
|
other first message with `protocol`.
|
|
- Region-wide attempts are counted before the signature is checked (`rate_limited`).
|
|
The grant must verify with one of the region's issuer keys (`unauthenticated`) for the
|
|
region's environment (`wrong_scope`), then pass session control: world/region scope,
|
|
lifetime, expiry, serial (`stale_grant`), per-account attempts and capacity.
|
|
- Welcome confirms the session; `expires_at` is the grant's expiry. A newer grant for an
|
|
account with an open session closes that session's connection with `superseded`.
|
|
- Refresh renews the open session with a newer grant; a refusal leaves the session and
|
|
its expiry unchanged. The server closes a session with `expired` when its expiry
|
|
passes, and every session with `stale_epoch` when the region's ownership epoch advances.
|
|
- Close is followed by closing the connection (the server waits up to 1 s for delivery).
|
|
A client that closes its connection without Close is treated as `client_closed`.
|
|
- Reconnecting needs a new connection and a newer grant (ADR-0089).
|
|
- Intentions (ADR-0092): one per tick, ticks and sequences increasing, tick within
|
|
server_tick + 1 ..= + 8. A receipt only says admitted or refused; `SimulatedThrough`
|
|
says which admitted intentions' ticks have run (cumulative, sent every simulated tick, sequence 0 before the first; it is also the
|
|
client's clock for the server tick).
|
|
Any datagram other than an Intention, or before Welcome, closes with `protocol`.
|
|
- Actions (ADR-0092): ids unique per account and never admitted twice. A receipt only
|
|
says scheduled or refused; `ActionOutcome` is sent once the action is final, again
|
|
after a duplicate of a final action, and in answer to `ActionQuery`.
|