Files
aevolution/docs/architecture/NETWORK_ARCHITECTURE.md
T
dingoandClaude Opus 5.5 7956143cd8
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 3m13s
Foundation / checks (client) (push) Successful in 12m12s
Foundation / checks (network) (push) Successful in 8m56s
Foundation / checks (tsan) (push) Successful in 7m42s
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 19m14s
Foundation / checks (checks) (push) Canceled after 31m28s
Add M10.3b session login over QUIC
Session protocol v1 session messages (Hello with grant, Welcome, Refresh,
RefreshResult, Close with reasons) on the QUIC reliable stream. RegionSessions
verifies grants with the issuer public keys and admits them through SessionControl:
a newer grant closes the account's old connection as superseded, expiry and epoch
advances close sessions, every close is announced and flushed. RegionSessionClient
logs in, refreshes in place and reports why a session ended. ADR-0091.

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

92 lines
5.5 KiB
Markdown

# Authoritative network architecture
Status: locked server authority and untrusted clients; transport/reliability are
proposals for M10. M10 timing and workload budgets: ADR-0089 and
[m10-budgets-v1](../../schemas/network/m10-budgets-v1.md). M10 transport: QUIC via msquic
with OpenSSL (ADR-0090): bounded DATAGRAM and reliable-stream channels with exact CA
pinning (`evo_network_quic`, M10.2b); loss/head-of-line measurements (M10.2c,
[M10_TRANSPORT_MEASUREMENTS](../networking/M10_TRANSPORT_MEASUREMENTS.md)) confirm
superseding state on DATAGRAMs and reliable actions on the ordered stream. Session
identity and control (ADR-0091, M10.3): ECDSA-signed account-scoped grants
([session-grant-v1](../../schemas/network/session-grant-v1.md)), newest grant wins; login over
QUIC per [session-v1](../../schemas/network/session-v1.md). The scoped M9 dev session (TLS 1.3, protocol v1, dev-only grants)
is specified in [DEV_SESSION_PROTOCOL](../networking/DEV_SESSION_PROTOCOL.md) and
ADR-0082. M0 has no networking. Steam distribution follows later through
an identity-provider adapter; core account IDs are independent of Steam IDs.
```mermaid
flowchart LR
S[Steam identity provider] --> A[Identity adapter / backend]
C[Custom desktop client] <-->|HTTPS identity / world / history| A
A -->|short-lived region-scoped session grant| C
C -->|authenticated bounded intentions| R[Region network host]
R -->|ordered commands| W[Simulation owner]
W -->|views / outcomes| R
R -->|perceived deltas / ACKs / durable events| C
```
## Channel contracts
| Channel | Information | Delivery contract |
|---|---|---|
| Realtime | Movement/orientation intentions and superseding snapshots | Prefer datagrams; sequence/drop obsolete state; bounded loss recovery |
| Reliable gameplay | Mutation choice, reproduction, death, region transfer | Idempotent action/event IDs; retry; outcome ACK after durable commit |
| Backend | Identity, world selection, friends, lineage/history/admin | HTTPS or justified gRPC; provider validation and least-privilege API scopes |
InputFrame includes protocol/session/region epoch, sequence, intended tick,
bounded movement/orientation, action flags and validated interaction reference.
Clients cannot author position, damage, energy, resources, genome, reproduction
or death. Validate lengths, numeric ranges/non-finite values, sequence window,
target relevance, session ownership, action prerequisites, rates and expiry
before admitting bounded commands. Reject unsupported required protocol versions.
Do not deserialize directly into trusted native structs.
Snapshot includes region/epoch, server tick, acknowledged simulated input sequence,
baseline ID, perception-filtered state and events. Recovery also exposes the
durable commit watermark. Receipt ACK means bytes accepted; simulated ACK means
input applied; final biological outcome means durable. These are not aliases.
## Prediction and interest boundaries
Client predicts only approved local motion using shared versioned rules. It keeps
bounded unacknowledged intentions. On authoritative snapshot, restore local state
at ACK, discard acknowledged inputs, replay remaining ones, and visually smooth
correction. Remote entities interpolate buffered snapshots with bounded
extrapolation; loss requests a fresh baseline. Death/mutation/reproduction remain
server decisions. Bound retained baselines, input buffers and packet work.
Proposed interface: `PerceptionView(observer, tick)` → perceptible entity/field
facts; `InterestPolicy(session, view, budget)` → replication set and granularity.
Do spatial coarse filtering before biological perception. Poor vision cannot
receive hidden exact transforms; scent may expose a directional field, echolocation
a derived acoustic result. Rendering receives no arbitrary player/NPC/level labels.
Social friend identification is a separate authorized policy. Implement simple
spatial interest first; M0 does not implement sensory networking.
## Reliability and security experiments
Compare established authenticated datagram/reliable transports (including a
library-backed UDP security channel and QUIC options) against an owned selective
reliability layer. Measure loss/reorder/duplication, head-of-line delay, MTU/
fragmentation, congestion, NAT routing, CPU, bandwidth and platform support.
Do not choose raw unauthenticated UDP or invent cryptography. The final protocol
ADR must name the maintained implementation, exact version, license, cipher
configuration and threat review. Custom replication/game protocol does not
require custom TLS, encryption, key exchange or random nonces.
Use short-lived world/region/account-scoped grants, authenticated key establishment,
replay windows, rate/byte/work caps, server input scheduling windows and timeouts.
Reconnect cannot duplicate control grants. Secrets never enter logs or gameplay
snapshots. Network identities map to current ownership epoch; stale region
responses/handoff tickets fail. Administrative APIs and storage credentials are
separate from client sessions. Game workers have only region-scoped operations;
a compromised process remains a threat requiring isolation and audit, not merely
client validation.
Required tests before M10 acceptance: fabricated/oversized/truncated packets,
NaN/overflow, replayed actions, sequence wrap/old baselines, duplicate/reordered
reliable messages, speed/mutation/resource cheats, flooded sessions, dropped ACKs,
lease/handoff races, reconnect uniqueness, sensory information leaks and bounded
queue overload. Demonstrate 20+ simulated clients, then measure higher load with
latency/loss and authoritative-state divergence reports.