EXPERIMENT (ADR-0094), not an organism movement rule: one non-biological marker per session, moved by admitted intentions with a shared integer rule (probe-motion-v1, 100 mm per tick, clamped to the area), held in region memory only. - ProbeMarkers: spawn, area, bounded per-marker schedule, catch-up bound - session protocol v3: marker records in snapshot chunks; the own marker is always sent with its applied sequence and area; v1 and v2 are refused - MotionPredictor (bounded replay from the authoritative marker, corrections, error samples), CorrectionSmoother and InputLead - tests: exact prediction with enough lead, refusal and lead adaptation, lost inputs, bounds, marker records through the codec Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.0 KiB
M10 session protocol, version 2
Login, session control, intentions, actions and snapshots over QUIC (ADR-0090 transport,
ADR-0091 identity, ADR-0092 intentions and actions, ADR-0093 snapshots and interest).
Version 2 is version 1 plus types 13-15; types 1-12 are unchanged. 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, 14 and 15 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. Version 1 messages are refused
(unsupported_version). Once v2 is deployed it is frozen like v1.
Superseded by version 3 (ADR-0094): v2 was deployed to evolution-dev on 2026-10-06 and is frozen; v3 servers and clients refuse it.
Header (8 bytes)
| Offset | Size | Field | Rule |
|---|---|---|---|
| 0 | 4 | magic | bytes EVSN |
| 4 | 2 | version | 2 |
| 6 | 1 | type | 1..15 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 |
| 13 Interest | client -> server | x, y, z (i64), radius u16 | 26 |
| 14 SnapshotChunk | server -> client, datagram | epoch, tick, baseline, field_revision, organism_revision (u64), mask u32, slice_z i64, index u8, count u8, records | 54 + records, at most 1,200 in all |
| 15 SnapshotAck | client -> server, datagram | epoch, tick (u64) | 16 |
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
timeoutif no Hello arrives within 5 s of connecting, and refuses any other first message withprotocol. -
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_atis the grant's expiry. A newer grant for an account with an open session closes that session's connection withsuperseded. -
Refresh renews the open session with a newer grant; a refusal leaves the session and its expiry unchanged. The server closes a session with
expiredwhen its expiry passes, and every session withstale_epochwhen 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;
SimulatedThroughsays 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 withprotocol. -
Actions (ADR-0092): ids unique per account and never admitted twice. A receipt only says scheduled or refused;
ActionOutcomeis sent once the action is final, again after a duplicate of a final action, and in answer toActionQuery. -
Interest (ADR-0093): the server clamps the radius to 7 and sends only entities in that square of the slice that the session may perceive. A new interest restarts from a fresh baseline. Until a client sends one, the server may apply a default interest (evo-server: the region's first habitat site, radius 7); snapshots then start right after Welcome.
-
SnapshotChunk: epoch and tick nonzero; baseline 0 (fresh) or an earlier tick; 1 <= count <= 16; index < count. Records are whole entities, concatenated:
Kind Body 1 environment upsert x, y, z (i64), chunk_revision u64, habitat x, y, z, width, height, depth (u32 um), volume u64, substrate, terrain_material, terrain_fill (u16), then per field (10): presence u8 (0 not requested, 1 missing, 2 present) and quantity u64 when present, moisture_status u8 (0..3) and numerator, denominator u64 when available (3) 2 environment remove x, y, z (i64) 3 organism upsert id u64, x, y, z (i64), offset x, y (u32 um), structural_mass, membrane_mass, total_mass (u64), extent u32, surface, maintenance (u64), movement_speed u32, ingestion_rate u64, conversion_per_thousand, thermal_shortfall, realized_per_thousand, damage_per_thousand (u32), state u8 (0 alive, 1 dead) 4 organism remove id u64 Every record's z equals slice_z. The client applies a complete snapshot to its baseline and validates the result as presentations; a malformed record or disagreeing chunk headers are errors.
-
SnapshotAck names the newest snapshot applied completely; the server sends later deltas against it while it is at most 40 ticks old.