Files
aevolution/docs/architecture/NETWORK_ARCHITECTURE.md
T
dingoandClaude Opus 5.5 ca762bff75
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m47s
Foundation / checks (network) (push) Successful in 8m11s
Foundation / checks (client) (push) Successful in 12m20s
Foundation / checks (tsan) (push) Successful in 7m44s
Foundation / checks (checks) (push) Successful in 31m12s
Foundation / checks (postgres) (push) Successful in 33m27s
Foundation / image (push) Successful in 2m14s
Foundation / postgres-tools (push) Successful in 6m24s
Foundation / server-image (push) Successful in 18m6s
Add M10.2b bounded QUIC channels with exact CA pinning
evo_network_quic wraps msquic in a single-owner Endpoint: newest-wins datagram
channel and one length-framed reliable stream, both bounded, with explicit close
causes. The client pins exactly one CA and name with an owned Mbed TLS check that
is the sole authority (OpenSSL's verdict advisory), callbacks never call msquic
under the lock, and MinimumMtu starts at 1280 so 1,200-byte datagrams fit minimum
paths. An owned seeded UDP impairment relay drives loss, duplication, reordering,
corruption, MTU and outage tests, passing on MSVC, GCC and Clang ASan/UBSan.

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

5.2 KiB

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. 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 follow in M10.2c. The scoped M9 dev session (TLS 1.3, protocol v1, dev-only grants) is specified in DEV_SESSION_PROTOCOL and ADR-0082. M0 has no networking. Steam distribution follows later through an identity-provider adapter; core account IDs are independent of Steam IDs.

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.