7.6 KiB
[Reviewed]
ADR-0094: M10 probe-motion experiment, prediction and reconciliation
Status
Accepted for M10.6 (2026-10-06). Decisions confirmed with the maintainer on 2026-10-06: intentions move a per-session probe marker (not an organism); markers are ephemeral (region memory only); the shared rule is a fixed-speed integer kinematic; evidence is loopback traces through the owned impairment relay plus real-process and GUI checks. Delivery: 10.6a rule, markers, protocol v3 records and the client predictor (this text); 10.6b session, evo-server, probe and GUI wiring; 10.6c impaired traces and the report. Each segment amends this ADR.
EXPERIMENT. Nothing here is a game movement rule. M11.1 decides organism movement (rates per unit time, ADR-0089 amendment), and the marker is retired when controllable organisms exist.
Context
The roadmap's 10.6 needs local motion that the client can predict with shared versioned rules and reconcile with the authority (NETWORK_ARCHITECTURE "Prediction and interest boundaries"). No controllable organism or movement rule exists (ADR-0092: intentions change nothing), and the project vision forbids engineering fixtures from silently becoming game rules. Session protocol v2 was deployed to evolution-dev on 2026-10-06 and is frozen.
Decision (10.6a)
- Probe marker. One per session, opened with the session, at the area's spawn, closed with it. It has a position and a held movement vector only: no energy, contact, perception, biology, persistence or effect on any store. A restart, epoch change or reconnect starts a fresh marker at the spawn. The host sets the area (an inclusive micrometre rectangle in one cell slice) and the spawn.
- probe-motion-v1 (
include/evo/network/probe_motion.hpp, shared by server and client): each tick, position += vector x 100,000 / 1,000 um per axis (integer, truncating toward zero; 100 mm per tick, 2 m/s at 50 ms), clamped to the area. An admitted intention for tick T sets the held vector from T's step onward; per tick the newest sequence wins. The server applies at most 16 scheduled intentions per marker and steps at most 64 ticks per advance (a longer gap applies the held vectors without the motion it can no longer attribute). - Session protocol v3 (schemas/network/session-v3.md): v2 plus marker records in snapshot chunks. A session's own marker is always sent, first (distance 0) and every tick it changed, with its newest applied intention sequence and its area; other markers pass the spatial filter and carry neither. v1 and v2 are refused.
- Client prediction (
include/evo/client/motion_prediction.hpp): at most 32 sent, unacknowledged inputs (a full list stops sending); on each authoritative marker state (after tick T) restore it, drop inputs applied (sequence <= applied) or past (tick <= T), replay the rest with the shared rule up to the presented tick (at most 32 ticks ahead). A refused intention is removed; reset on a new session or epoch. The jump a rebase makes to the presented position is a correction; the error per authoritative state (predicted versus authoritative position for that tick) is measured. Presentation smoothing is separate: a visual offset halves every 60 ms and snaps beyond 2 m. The input lead (ticks ahead of the newest known server tick) starts at 2, grows on eachoutside_windowrefusal and shrinks after 20 admitted inputs with more than two ticks to spare, within 2..7 (below the 8-tick admission window). - Prediction covers only the own marker's motion. Nothing biological is predicted, and other markers are shown as replicated (interpolation is 10.7).
Alternatives considered
- A placed test organism: biology (locomotion, maintenance) before M11.1 ratifies it.
- Checkpointed markers: a simulation-version and format change for a throwaway entity.
- Collision with habitat cells, inertia: more shared state and more of a design decision; the fixed-speed rule exercises replay and reconciliation fully.
- Extending v2 in place: v2 is deployed; an unknown record kind would close deployed v2 clients mid-session instead of refusing them at login.
Consequences
- Deployed v2 servers refuse v3 clients (
unsupported_version) until redeployed. - Exact prediction needs the inputs to arrive in time: a too-small lead shows as refusals and corrections until the lead adapts; a lost input datagram shows as a correction (the client resends after 10.6b's rules).
- Markers add at most 32 x 78 bytes per snapshot; their state is not durable and not part of any checkpoint or simulation version.
M10.6b wiring (2026-10-06)
-
RegionSessions owns
ProbeMarkers. Once the host callsset_motion_area:- every established session gets a marker (also those open at that moment);
- an admitted intention schedules its marker;
- each poll advances markers to the simulated tick (while ready) before admitting;
- close and loss remove the marker;
- a new epoch clears all markers;
replicateadds the markers and area to every source.
-
evo-server sets the area with the default interest: the bounding cells of the region's habitat sites in that slice, spawning at the centre of the first site. It prints
m10 motion area. -
Probe: one
marker TICK X Y APPLIEDline per snapshot holding its own marker. -
Engineering client:
- inputs are scheduled with the adaptive lead and recorded with the predictor;
- each snapshot's own marker rebases the prediction;
- a refusal removes the input, and
outside_windowraises the lead; - an intention is sent again when the authority holds another vector and nothing is in flight (after a loss or refusal);
- the predicted marker is presented at server tick + lead, with corrections smoothed.
While following, the camera and the interest follow the predicted own marker, until the user pans or zooms. Markers are drawn as squares: own amber, others blue. The Session panel shows the marker position, pending inputs, lead, corrections, maximum error and snaps. There is no sub-tick interpolation: the marker steps at 20 Hz.
-
Evidence:
client-remote-session: the marker at the spawn, followed by camera and interest; an intention moves the predicted marker and the authority confirms it with zero error.- The real-process test: the probe's marker moved +x with its intention applied, and evo-server reported the motion area.
M10.6c traces and close (2026-10-06)
evo-motion-tracedrives the client's own session code through the impairment relay against a real-time 50 ms loopback region; the figures are in M10_PREDICTION_TRACES.- Prediction is exact without loss.
- With 2-5 % loss and 60-200 ms RTT, 94-99 % of samples are exact. Errors stay within the motion of the lost or late inputs (at most about 1.4 m) and are corrected by the resend.
- All profiles converge on the authority when stopped.
- A restart resyncs in about 2-3 s (the reconnect pause).
- The CTest
motion-trace-smoke(labels client, quic-session) runs 6 s of rtt60-loss2 plus a restart. It fails unless both converge, the input list stays within its bound and most predictions are exact. - The owned UDP relay now lets a new sender take over once the current client has been silent for 1 s, so a reconnecting client (new source port) can be traced. Concurrent senders are still dropped.
- The client now counts refusal receipts (
refused) separately from inputs the predictor removed; the unusedPredictionStats::refused_inputsfield is gone. - M10.6 is complete. Sub-tick presentation and remote-marker interpolation belong to 10.7.