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