Files
aevolution/schemas/network/session-v1.md
T
dingoandClaude Opus 5.5 0bf9901c7f
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m46s
Foundation / checks (postgres) (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 0s
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 3m44s
Foundation / checks (client) (push) Canceled after 3m49s
Foundation / checks (network) (push) Canceled after 1m59s
Add M10.4c evo-server QUIC listener and headless session client
evo-server gains an opt-in M10 listener (--m10-*, QUIC builds only): RegionSessions
with the PostgreSQL control and action ledgers on their own connection under the
host's lease, carried actions submitted to the host and its acknowledgements and
drops turned into outcomes. evo-session-probe is a dev-only headless client. Real
process tests cover intentions, durable action outcomes, SIGKILL before and after
an action's commit, duplicate retries and the probe. The simulated watermark now
reaches every session every tick, so clients always know the server tick.
ADR-0092.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 09:20:55 -04:00

4.9 KiB

M10 session protocol, 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 has not been deployed; it was amended in place by M10.4 (types 6-12, Welcome server_tick). After its first deployment, changes need 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.