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