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

100 lines
5.2 KiB
Markdown

# 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.