Add M10.5a session protocol v2 and snapshot replication core
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m58s
Foundation / checks (client) (push) Failing after 9m57s
Foundation / checks (network) (push) Successful in 11m17s
Foundation / checks (tsan) (push) Successful in 7m49s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 25m43s
Foundation / checks (postgres) (push) Canceled after 15m44s

Session protocol v2 adds Interest, SnapshotChunk and SnapshotAck (v1 is refused).
ReplicationServer filters by a server-capped client focus and a perception
predicate, sends per-tick entity deltas against the acknowledged baseline (kept
up to 40 ticks), nearest first within 16 KiB with a slower distant tier, as
self-contained datagram chunks. SnapshotAssembler applies complete snapshots to
one of two baselines and validates them as presentations. ADR-0093.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-06 10:22:11 -04:00
co-authored by Claude Opus 5.5
parent ca0939dda5
commit e640b6d3a3
17 changed files with 1342 additions and 9 deletions
+3 -1
View File
@@ -525,7 +525,9 @@ session control done; 10.3b QUIC session login (schemas/network/session-v1.md) d
10.4a intention/action protocol and admission done; 10.4b durable action records
(schema v11, same transaction as the checkpoint) done; 10.4c evo-server QUIC listener and
headless client with process kill tests done. The engineering GUI client still uses the
M9 dev path. 10.5-10.9 planned.
M9 dev path. 10.5 split (ADR-0093): 10.5a session protocol v2 and the replication core
done; 10.5b wiring and process evidence and 10.5c the GUI client switch follow.
10.6-10.9 planned.
**Entry:** M9 client/session evidence and M7/M8 dev/stage durability. Read
NETWORK_ARCHITECTURE, PERSISTENCE_ARCHITECTURE and ADR-0017. The M9 transport is
+5
View File
@@ -42,6 +42,11 @@ behind the ADR-0087 route; session protocol v1 is therefore frozen. The route ad
only TCP 7400 while QUIC is UDP, so it is changed to UDP 7400 (ADR-0087 amendment). The
route is not yet verified end to end: the edge firewall rule (UDP 7400 from
172.10.1.0/24), internal DNS to 172.10.1.202 and a probe run through the VIP remain.
M10.5a (ADR-0093) adds session protocol v2 (interest, snapshot chunks, snapshot acks; v1 is
refused) and the replication core: server-capped interest with a perception boundary,
entity deltas against the acknowledged baseline, nearest first within 16 KiB per tick with
a slower distant tier, datagram chunks and client assembly. Next: 10.5b wiring, then the
GUI client switch (10.5c).
## Previous gate - 2026-10-02
@@ -0,0 +1,60 @@
# ADR-0093: M10 snapshots, spatial interest and session protocol v2
## Status
Accepted for M10.5 (2026-10-06). Decisions confirmed with the maintainer on 2026-10-06:
interest is a client-declared focus capped by the server; snapshots travel as datagram
chunks with acknowledgements; 10.5 replicates environment cells plus the organism entity
class (currently empty) with a perception boundary; the GUI engineering client moves to
M10 sessions within 10.5. Delivery: 10.5a protocol v2 and the replication core (this text),
10.5b server/client wiring, probe and process evidence, 10.5c the GUI client switch
(msquic.dll in the package, dev grant files). Each segment amends this ADR.
## Context
ADR-0089 fixed per-tick snapshots for entities in interest, a fresh baseline on join, epoch
change and loss, at most 4 server baselines of at most 40 ticks per session and 2 on the
client, and at most 16 KiB of replication per session per tick; ADR-0090 put superseding
state on 1,200-byte QUIC DATAGRAMs. The M9 dev session sent the whole environment view of
one slice every tick over TCP (up to 256 cells of about 170 bytes). Session protocol v1 is
deployed in evolution-dev and frozen (ADR-0087 amendment). The region has no placed
organisms yet; its organism presentation is empty.
## Decision (10.5a)
**Session protocol v2** (schemas/network/session-v2.md) is v1 plus `Interest` (stream),
`SnapshotChunk` (datagram) and `SnapshotAck` (datagram). v1 is no longer accepted: its only
deployed client was the development probe.
**Interest.** A session declares one Z slice, a centre and a radius. The server clamps the
radius to 7 (15 x 15 cells, within the 256-cell presentation limit) and filters
authoritatively: an entity outside the square or the slice is never encoded. Organisms then
pass a perception predicate (the extension boundary for concealment and, later, the
controlled organism's senses). Records carry the presentation fields only: no controller,
owner, account or player/NPC label exists in them. Interest changes restart from a fresh
baseline.
**Snapshots.** Every tick, each interested session gets snapshot `tick`: entity-level
upserts and removals against the newest snapshot the client acknowledged, or against
nothing (a fresh baseline). The server keeps the acknowledged snapshot plus the newest
others, at most 4, none older than 40 ticks; an ack for an evicted or another epoch's
snapshot is ignored. Changed entities are sent nearest first (Chebyshev distance from the
focus). Distant ones (beyond radius 3) refresh at most every 4 ticks (the lower-rate tier);
anything not sent keeps the value the client already holds, so the snapshot's state is
exactly what the client will have. A snapshot never exceeds 16 KiB: a fresh 225-cell
baseline arrives over about two ticks, nearest first. Unchanged ticks send one empty chunk
(the per-tick cadence).
**Chunks.** A snapshot is split into at most 16 self-contained chunks of whole records,
each one datagram of at most 1,200 bytes including headers. The client assembles a snapshot
when all chunks arrived, applies it to its baseline (one of its 2 newest applied snapshots),
validates the result through the presentation constructors and acknowledges it. A lost
chunk leaves the snapshot incomplete; the next delta is against the older acknowledged
snapshot. At most 4 snapshots are in assembly. Stale, foreign-epoch and unassemblable chunks
are ignored; malformed records, a slice mismatch or disagreeing chunk headers are errors.
## Consequences and limits
- Development-reference figures (32 sessions, 40 ticks, a changing row every tick, record
size about 114 bytes): at most 16,320 bytes per session per tick, mean 1,404 bytes, 28,800
retained entity states (about 3.5 MB) across all baselines.
- Entity-level deltas: a changed cell is resent whole. Field-level deltas or quantization
are not needed at this size and are left for measurement (10.9).
- Wiring into RegionSessions, evo-server and the clients is 10.5b; until then v2 messages
exist but no server sends snapshots.
+1
View File
@@ -98,6 +98,7 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0084: Engineering UI toolkit](0084-engineering-ui-toolkit.md) - Dear ImGui 1.92.9b pinned (M9.8a) and integrated as the engineering client overlay with toolkit-first input routing (M9.8c).
- [ADR-0090: M10 QUIC transport](0090-m10-quic-transport.md) - msquic 2.6.2 with OpenSSL 3.5.9 LTS (TLS 1.3 only) from pinned sources on Windows and Linux; DATAGRAM frames for superseding state, streams for reliable actions; M9 TLS/TCP kept as dev fallback; owned impairment relay; exact CA pinning due in 10.2b.
- [ADR-0093: M10 snapshots and interest](0093-m10-snapshots-and-interest.md) - session protocol v2: client-declared, server-capped interest (radius <= 7) with a perception boundary; per-tick snapshot chunks as datagrams, entity deltas against the acknowledged baseline (<= 4, <= 40 ticks), nearest first within 16 KiB, distant tier every 4 ticks; client assembly with 2 baselines.
- [ADR-0092: M10 intentions and durable outcomes](0092-m10-intentions-and-durable-outcomes.md) - realtime intentions (datagram receipts and a cumulative simulated watermark) and account-scoped actions with stable ids, receipts and final outcomes (committed_no_effect / not_committed); no biological effect until organisms exist; durable action records in the commit transaction (10.4b).
- [ADR-0091: M10 session identity and control](0091-m10-session-identity-and-control.md) - provider-independent 128-bit AccountIds, ECDSA P-256 session grants (regions hold public keys only, signed environment byte), per-account serials where the newest grant wins, takeover of an existing session, in-session refresh, bounded attempt rates; identity adapter and issuer as a library; durable control lease follows (10.3c).
- [ADR-0089: M10 timing and budgets](0089-m10-timing-and-budgets.md) - ratified 50 ms tick, 1 s flush with final outcomes p95 <= 1.5 s, responsiveness LAN p95 <= 150 ms / 100 ms RTT <= 250 ms, reference hardware; derived scheduling, sequence, baseline, queue/byte/work budgets and exact/tolerant determinism; biological rates will be time-based with deterministic tick conversion and versioned migration in M11.1.
+33
View File
@@ -4347,3 +4347,36 @@ Probe changes: host names are resolved (IPv4) and printed (`resolved HOST ADDRES
`closed` lines name the QUIC transport cause (`RegionSessionClient::transport_cause`).
Executed: Windows MSVC preset `quic` build; Linux GCC preset `quic` CTest 4/4; clang-tidy 19
on the client, probe and evo-server sources.
## 2026-10-06 — M10.5a session protocol v2 and replication core (ADR-0093)
Implemented session protocol v2 (`Interest`, `SnapshotChunk`, `SnapshotAck`; version 1
refused), `ReplicationServer` and `SnapshotAssembler` (`include/evo/network/replication.hpp`)
and `tests/network_replication.cpp` (part of `evo-network-tests`).
Tests: v2 codec round trips, version 1 refused, chunk header rules (baseline >= tick, index
>= count, count 0 or > 16, zero epoch or tick), exactly one datagram of records accepted and
one byte more refused, every header truncation refused; radius clamped to 7; a fresh
225-cell baseline arriving nearest first within 16 KiB per tick over two ticks; nothing
outside the interest square ever received; converged ticks sending one empty chunk; a near
change sent at once and a far change deferred exactly 4 ticks; removal; a dropped chunk
leaving the snapshot unacknowledged and the next delta against the older baseline; the
acknowledged baseline kept 40 ticks and a fresh baseline after that; acks for evicted or
another epoch's snapshots ignored; a new interest restarting from a fresh baseline with only
the new square; concealment (an organism one session may not perceive and organisms outside
interest absent from the encoded bytes); client rejection of truncated, unknown-kind and
other-slice records and disagreeing chunk headers, stale and foreign-epoch chunks ignored,
deltas against unknown baselines dropped, at most 4 assemblies; 32 dense sessions for 40
ticks with a changing row (report: max 16,320 bytes per session per tick, mean 1,404,
28,800 retained entity states).
Found and fixed during development: eviction of the acknowledged baseline when acks lag
four or more ticks (normal at 100 ms RTT) would have forced fresh baselines (it is now always
kept); a dangling reference to an erased assembly entry; enum values cast before validation
in the record reader; MSVC narrowing in tuple keys and an ambiguous map erase.
Executed: Linux GCC 14 preset `quic` CTest 4/4; session tests 10/10 repeated; Clang 19
ASan/UBSan session and network tests; clang-tidy 19 on the new and changed sources and
tests; format check (only unrelated uncommitted files of the maintainer fail it); Windows
MSVC 19.44 preset `quic` build and CTest 4/4 (binaries rebuilt, timestamps checked).
Not done: wiring into RegionSessions, evo-server and the clients (10.5b); the GUI client
(10.5c).