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>
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::admittedis 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.