Files
aevolution/schemas/network/session-v1.md
T
dingoandClaude Opus 5.5 d917e8443d
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 5s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 5s
Foundation / checks (deploy) (push) Successful in 3m16s
Foundation / postgres-tools (push) Successful in 5s
Foundation / server-image (push) Successful in 5s
Foundation / image (push) Successful in 6s
Route the dev session as QUIC over UDP 7400
The deployed M10 listener is QUIC (UDP) but the ADR-0087 route admitted only TCP
7400, so nothing reached it through the VIP. The route container port, Service and
NetworkPolicy now carry UDP 7400 only (no TCP: nothing needs it). The policy check
requires exactly UDP 7400 for the route and counts any protocol on 7400 as session
exposure elsewhere; six new self-test cases. ADR-0087 amended (edge firewall and
internal DNS as separate reviewed steps, end-to-end probe as acceptance);
session protocol v1 recorded as frozen now that it is deployed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 17:04:31 -04:00

5.0 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 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.