Add M10.7a tick clock and remote-marker interpolation
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m59s
Foundation / checks (client) (push) Successful in 12m44s
Foundation / checks (network) (push) Successful in 12m45s
Foundation / checks (tsan) (push) Successful in 8m5s
Foundation / checks (checks) (push) Successful in 32m4s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 21m38s

ADR-0095 (presentation only): a drift-corrected monotonic tick clock that
never runs more than one tick past the newest observation; remote probe
markers shown 2-6 ticks behind (adaptive to snapshot gaps), interpolated,
extrapolated for at most 2 ticks and then marked stale; appearance and
removal at their snapshot ticks; organisms never extrapolated; sub-tick
own-marker prediction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-06 17:16:20 -04:00
co-authored by Claude Opus 5.5
parent 61d899de3c
commit 90cdb61e30
12 changed files with 539 additions and 5 deletions
@@ -0,0 +1,57 @@
# ADR-0095: M10 tick clock, remote interpolation and session loss
## Status
Accepted for M10.7 (2026-10-06). Decisions confirmed with the maintainer on 2026-10-06:
- an adaptive interpolation delay of 2-6 ticks;
- remote markers extrapolate at most 2 ticks, and organisms never;
- on session loss the last view stays frozen, dimmed and labelled stale, and a reconnect
starts from a fresh baseline;
- a drift-corrected client tick clock, with sub-tick presentation.
Delivery: 10.7a the headless clock, interpolator and fractional prediction (this text);
10.7b engineering client wiring, the loss view and a two-client trace. Each segment amends
this ADR. Presentation only: none of it is authority, and no outcome is invented.
## Context
NETWORK_ARCHITECTURE requires remote entities to interpolate buffered snapshots with
bounded extrapolation, loss to request a fresh baseline, and death, mutation and
reproduction to remain server decisions. M10.6 (ADR-0094) predicts the own probe marker at
whole ticks. Other markers are drawn as last replicated, so they step at 20 Hz and jump
when a snapshot is lost. No controllable organism moves yet.
## Decision (10.7a)
- **Tick clock** (`include/evo/client/interpolation.hpp`). Each observed server tick
(watermark or snapshot) slews a local estimate by 10 % of the error. An error beyond 4
ticks snaps forward. The estimate is monotonic between resets and never more than one
tick beyond the newest observation, so a silent or paused server freezes it rather than
inventing time. Assumes 50 ms ticks; drift of ±4 % stays within 1.5 ticks in tests.
- **Remote markers** are presented at `clock - delay`, interpolated linearly between the
buffered snapshots around that tick (at most 16 snapshots).
- A marker appears at the tick of the snapshot that adds it.
- It is shown unmoved until the tick of the snapshot that removes it: never moved toward
a removal.
- Snapshots more than 8 ticks apart are not interpolated across.
- Reordered or duplicate snapshots are ignored.
- Beyond the newest snapshot the replicated held vector continues for at most 2 ticks;
then the marker freezes there and is marked stale.
- **Adaptive delay.** The target is the 90th-percentile gap between received snapshots
(last 40) plus one tick, within 2-6. The delay rises toward it at 2 ticks/s and falls at
0.5 ticks/s.
- **Organisms** are never extrapolated or interpolated: they are shown as replicated (newest
snapshot, ADR-0093). A dead or removed organism is therefore never shown moving or as
present after its removal.
- **Own marker between ticks.** `MotionPredictor::predict_between(tick, fraction)`
interpolates the prediction between two whole ticks for presentation. Error measurement
still records whole ticks.
## Alternatives considered
- A fixed 2- or 3-tick delay: simpler, but either stutters on lossy links or adds latency
on good ones.
- No extrapolation: visible stalls on every lost snapshot.
- Longer extrapolation (4 ticks): larger errors when a remote changes direction.
- Clock from the local timer only: drifts without bound against the server's pacing.
## Consequences
- Remote markers are shown 100-300 ms in the past, the own marker in the predicted
present. That is the usual split; interactions that need both are later work.
- Extrapolated or stale markers are flagged so the client can draw them differently.