Files
aevolution/docs/networking/DEV_SESSION_PROTOCOL.md
dingoandClaude Opus 5.5 819137c1df
Foundation / checks (deploy) (push) Successful in 1m0s
Foundation / checks (ecs) (push) Successful in 3m34s
Foundation / checks (network) (push) Successful in 8m8s
Foundation / checks (client) (push) Successful in 14m49s
Foundation / checks (tsan) (push) Successful in 7m35s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 16m18s
Foundation / checks (checks) (push) Canceled after 29m27s
Ratify M10.1 timing and workload budgets with session traces
ADR-0089 records the maintainer-ratified 50 ms tick, 1 s flush with final
outcomes p95 <= 1.5 s, responsiveness targets and reference hardware, plus
derived scheduling, sequence, identity, baseline, queue/byte/work budgets and the
exact/tolerant determinism contract (schemas/network/m10-budgets-v1.md). Adds
SessionClient traffic counters, `evo-dev-session trace` and a reproducible trace
script; development-reference results are in M10_TIMING_TRACES. Records that
genome v1 and metabolism rates are per tick, so the quantum fixes biology rates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 12:29:58 -04:00

5.4 KiB

M9 dev session protocol

Decision: ADR-0082. Wire layout: dev-session-v1. Architecture: NETWORK_ARCHITECTURE. Scope: one engineering client and one authoritative dev region. Not the M10 multiplayer transport, not production identity, not a gameplay protocol.

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) 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. 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 trace (M10.1) measures admission and durable round trips, view cadence and bytes against a running region (tools/network/session-trace.sh, M10_TIMING_TRACES). evo-dev-session-fuzz is the libFuzzer target (EVO_BUILD_FUZZER, Linux Clang). Results: engineering/VALIDATION.md.