# M9 dev session protocol Decision: [ADR-0082](../adr/0082-dev-session-transport.md). Wire layout: [dev-session-v1](../../schemas/view/dev-session-v1.md). Architecture: [NETWORK_ARCHITECTURE](../architecture/NETWORK_ARCHITECTURE.md). Scope: one engineering client and one authoritative **dev** region. Not the M10 multiplayer transport, not production identity, not a gameplay protocol. ```mermaid sequenceDiagram participant C as evo-client participant T as TLS 1.3 (Mbed TLS) participant A as SessionAdmission participant R as Region host (M9.7) C->>T: handshake, verify pinned dev CA + server name C->>A: Hello{dev grant} A->>A: HMAC verify, world/region, lifetime, single use, one subject A-->>C: Welcome{session, epoch, server tick, commit watermark, limits} R-->>C: EnvironmentView / OrganismView{session, epoch, tick, watermark, baseline} C->>A: Intent{session, epoch, sequence, tick, vector} A-->>C: IntentResult{admitted | rejected reason} A->>R: admitted intention for scheduling (server decides outcome) ``` ## Layers and modules | Layer | Module | Depends on | |---|---|---| | Wire codec, FrameReader | `evo_network_protocol` (`protocol.hpp`) | client presentation values only | | Session admission | `evo_network_protocol` (`admission.hpp`) | codec, world identity | | Dev grants (HMAC-SHA256) | `evo_network_tls` (`dev_grant.hpp`) | PSA crypto (Mbed TLS) | | TLS 1.3 channel | `evo_network_tls` (`tls_channel.hpp`) | Mbed TLS, caller `ByteTransport` | | Non-blocking TCP | `evo_network_session` (`tcp.hpp`) | Winsock/POSIX | | Session server and client | `evo_network_session` (`session_server.hpp`, `session_client.hpp`) | all of the above | | Region integration | `apps/evo-server/session_bridge.hpp` | region host (read-only) | M9.7 ([ADR-0083](../adr/0083-dev-region-sessions.md)) runs the session server in `evo-server`'s loop: views from the region's real field/terrain stores (empty organism presentation), admitted intentions riding synthetic inputs with durable no-effect outcomes, client reconnect with fresh baselines. Operations: [DEV_SESSION_OPERATIONS](DEV_SESSION_OPERATIONS.md). Nothing links into `evo_simulation`. `EVO_BUILD_NETWORK` is opt-in and requires `cmake -P tools/prepare-mbedtls.cmake`. ## Trust and authority - The client authors only Hello (an opaque grant) and Intent (sequence, tick and a signed vector of norm <= 1000). It cannot author position, energy, resources, genome, reproduction, death or presentation values. - Views travel server -> client and are rebuilt through the presentation validators; a client never sends them. - Every view and Welcome carries epoch and the durable commit watermark. Receipt of bytes, admission for scheduling, simulation and durable outcome are distinct: `IntentResult::admitted` is only the second. - Session ids are server-assigned counters. They identify, they do not authenticate; M9.7 binds each session to its TLS connection. ## Admission rules `SessionAdmission` is single-owner (the host serializes calls) and bounded: at most 256 sessions and 65536 remembered grant ids by configuration limits. Open: verified grant -> world/frame and region must match; lifetime <= configured maximum; not issued beyond clock skew in the future; not expired; grant id not seen before (remembered until its expiry; when the table is full, new grants are refused rather than forgetting live ones); the subject has no active session; capacity available. Reconnect = close + new grant. Intent (status, first failing rule wins): unknown session; rate (every attempt by a known session in the current `window_ticks` counts, accepted or not); epoch (message and session must match the current ownership epoch; `advance_epoch` makes all existing sessions stale); grant expiry; vector bound; sequence strictly greater than the last admitted; tick in `[server_tick, server_tick + window]`. Rejected messages never advance the sequence. ## Dev-only enforcement `DevGrantKey::import` refuses `stage` and `world0`. The grant carries the marker `EVO-DEV-ONLY` and a dev environment byte under the HMAC. The key is a 32-byte secret from dev provisioning (M9.7: a dev-namespace Secret), never logged, never in images. A leaked dev key compromises dev sessions only; rotation is a redeploy. ## Failure behaviour Decoding errors (`ProtocolError`) mean the peer is malformed: close with `malformed`/`unsupported_version` and drop the connection. TLS errors latch per channel; `peer_verification` means the server certificate did not chain to the pinned CA or name. No error path retries automatically or falls back to plaintext. ## Evidence `evo-network-tests` (label `network`): round trips and an explicit little-endian golden; header/payload rejection cases; byte-by-byte FrameReader reassembly and early oversized rejection; 30,000-round seeded mutation fuzzing with canonical re-encoding; dev grant environment refusal, bit-flip tag failures and key misuse; admission scope/lifetime/reuse/duplicate/capacity rules and every intent status; TLS 1.3 loopback with suite/version checks, 100 kB transfer, close_notify, untrusted CA, wrong name, mismatched key, record tampering, transport failure and plaintext rejection. `evo-dev-session-fuzz` is the libFuzzer target (`EVO_BUILD_FUZZER`, Linux Clang). Results: engineering/VALIDATION.md.