# Dev session protocol v1 (wire schema) Decision: [ADR-0082](../../docs/adr/0082-dev-session-transport.md). Implementation: `include/evo/network/protocol.hpp`, `src/network/protocol/codec.cpp`. Carried inside TLS 1.3 only. All integers are little-endian, fixed width, with no padding or alignment; `i` types are two's complement. Encodings are canonical: a decoded message re-encodes to identical bytes (fuzz-tested). ## Frame | Offset | Field | Type | Rule | |---|---|---|---| | 0 | magic | u32 | `0x53445645` (bytes `E V D S`) | | 4 | version | u16 | exactly 1, otherwise `unsupported_version` | | 6 | type | u8 | 1..9, otherwise `unknown_type` | | 7 | flags | u8 | 0, otherwise `reserved_flags` | | 8 | length | u32 | payload bytes, <= 262144 (`oversized`) | | 12 | payload | bytes | exactly `length`; short `truncated`, extra `trailing_bytes` | Payload decoders also reject truncation, trailing bytes, out-of-range enum bytes (`invalid_value`) and values failing the presentation contracts (`invalid_value`). ## Messages | Type | Name | Direction | Payload | |---|---|---|---| | 1 | Hello | C->S | required_features u32 (must be 0: `unsupported_feature`), grant_length u16 (1..512), grant bytes | | 2 | Welcome | S->C | session, world, frame, region, epoch, server_tick, commit_watermark, grant_expires_at (u64 each); intent_window, window_ticks, max_intents_per_window (u32 each; session, window_ticks and max nonzero) | | 3 | Intent | C->S | session, epoch, sequence, tick (u64); move_x, move_y (i16) — 36 bytes | | 4 | IntentResult | S->C | sequence u64, status u8 (0..7), server_tick u64 | | 5 | EnvironmentView | S->C | view header, environment presentation | | 6 | OrganismView | S->C | view header, organism presentation | | 7 | Close | both | reason u8 (0..10) | | 8 | IntentOutcome | S->C | sequence u64, finality u8 (0 committed_no_effect, 1 not_committed), tick u64, commit_sequence u64; committed requires commit_sequence != 0, not_committed requires tick = commit_sequence = 0 | | 9 | Heartbeat | both | empty (length 0); sent after 1 s without other output; 5 s of silence closes with `timeout` | IntentStatus: 0 admitted, 1 unknown_session, 2 stale_epoch, 3 expired, 4 invalid_vector, 5 replayed, 6 outside_window, 7 rate_limited. CloseReason: 0 normal, 1 unsupported_version, 2 malformed, 3 unauthenticated, 4 expired, 5 duplicate_session, 6 stale_epoch, 7 rate_limited, 8 server_shutdown, 9 capacity, 10 timeout. Types 8-9 and reasons 9-10 were added in M9.7 before any v1 peer was deployed (ADR-0083); later changes require a new version. View header (40 bytes): session, epoch, server_tick, commit_watermark, baseline (u64). Environment presentation: world, frame, tick, field_revision (u64); mask u32; slice_z i64; count u16 (<= 256); then per cell: x, y (i64; z = slice_z); chunk_revision u64; habitat x, y, z, width, height, depth (u32 micrometres); volume u64; substrate, terrain_material, terrain_fill (u16); for each of the ten fields a presence u8 (0 not_requested, 1 missing, 2 present) followed by a u64 quantity only when present; moisture status u8 (0 not_requested, 1 missing_water, 2 zero_capacity, 3 available) followed by numerator, denominator (u64) only when available. The cells are then validated by `EnvironmentPresentation::create`. Organism presentation: world, frame, tick, revision (u64); slice_z i64; count u16 (<= 1024); then per cell: id u64; x, y (i64); offset x, y (u32 um); structural, membrane, total mass (u64); extent u32; surface, maintenance (u64); movement speed u32; ingestion rate u64; conversion, thermal shortfall (u32); realized, damage (u32 per thousand); state u8 (0 alive, 1 dead). Validated by `OrganismPresentation::create`. There is no controller, owner or label field. Maximum payload sizes: Hello 518 bytes, environment view about 42 KiB at 256 cells, organism view about 105 KiB at 1024 cells; all within one frame. ## Dev grant (opaque in Hello; 108 bytes) | Offset | Field | Type | |---|---|---| | 0 | marker | `EVO-DEV-ONLY` + 4 zero bytes | | 16 | version | u16 = 1 | | 18 | environment | u8 = 1 (dev) | | 19 | reserved | u8 = 0 | | 20 | grant_id, subject, world, frame, region, issued_at, expires_at | u64 each | | 76 | tag | HMAC-SHA256 over bytes 0..75 | The tag is verified before any other field is interpreted. ## Compatibility v1 has no optional extensions: `required_features` and `flags` must be zero, and a peer receiving another version closes with `unsupported_version`. Any field change is a new version with an explicit compatibility decision; nothing is negotiated silently. These messages are transient and never persisted.