Files
aevolution/docs/networking/DEV_SESSION_PROTOCOL.md
T
dingoandClaude Opus 5.5 8e319322f4 Implement M9.7 dev region sessions with durable no-effect intentions
Run a non-blocking TLS 1.3 session server inside evo-server's loop:
environment views come from the region's own field/terrain stores with an
explicitly empty organism presentation; admitted intentions ride the next
synthetic input (content unchanged) and return a durable no-effect outcome
from the host's final acknowledgement, or not_committed when dropped.
Sessions are bound to their connection, epochs close stale sessions, and
connections have bounded output, input rate and deadlines.

SessionClient and evo-client --connect consume one single-use grant per
Hello (refusals before admission keep it), reset to a fresh baseline on
every session, keep stale views visible and report in-flight intentions as
unknown after loss. evo-dev-session generates dev credentials, grant
bundles and runs a restart probe. The dev deployment gains a drill-time,
loopback-only listener with an optional Secret, enforced by the policy
check, and tools/ops/session-drill.sh. Protocol v1 gains IntentOutcome and
the capacity close reason before any deployment. ADR-0083 records the
maintainer-confirmed decisions; M8-dev/stage remains not passed and no
cluster change was made.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 20:12:18 -04:00

5.2 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-fuzz is the libFuzzer target (EVO_BUILD_FUZZER, Linux Clang). Results: engineering/VALIDATION.md.