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
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:
+3
-1
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user