Add M10.6a probe-motion experiment core and session protocol v3
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 2m1s
Foundation / checks (network) (push) Successful in 12m13s
Foundation / checks (client) (push) Successful in 14m28s
Foundation / checks (tsan) (push) Successful in 7m56s
Foundation / checks (checks) (push) Successful in 32m49s
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 40m58s

EXPERIMENT (ADR-0094), not an organism movement rule: one non-biological
marker per session, moved by admitted intentions with a shared integer rule
(probe-motion-v1, 100 mm per tick, clamped to the area), held in region
memory only.

- ProbeMarkers: spawn, area, bounded per-marker schedule, catch-up bound
- session protocol v3: marker records in snapshot chunks; the own marker is
  always sent with its applied sequence and area; v1 and v2 are refused
- MotionPredictor (bounded replay from the authoritative marker, corrections,
  error samples), CorrectionSmoother and InputLead
- tests: exact prediction with enough lead, refusal and lead adaptation,
  lost inputs, bounds, marker records through the codec

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-06 15:12:13 -04:00
co-authored by Claude Opus 5.5
parent d781492957
commit ab7e26c02e
20 changed files with 1135 additions and 18 deletions
+8 -3
View File
@@ -33,9 +33,13 @@ add_subdirectory("${mbedtls_source}" "${PROJECT_BINARY_DIR}/mbedtls" EXCLUDE_FRO
add_library(evo_network_protocol STATIC src/network/protocol/codec.cpp
src/network/protocol/admission.cpp src/network/protocol/session_control.cpp
src/network/protocol/session_protocol.cpp src/network/protocol/intent_admission.cpp
src/network/protocol/replication.cpp)
src/network/protocol/replication.cpp src/network/protocol/probe_motion.cpp)
target_link_libraries(evo_network_protocol PUBLIC evo_client_views evo_client_controls)
evo_owned_target(evo_network_protocol)
# M10.6 client prediction and reconciliation of the probe marker (ADR-0094).
add_library(evo_client_prediction STATIC src/client/prediction/motion_prediction.cpp)
target_link_libraries(evo_client_prediction PUBLIC evo_network_protocol)
evo_owned_target(evo_client_prediction)
# Mbed TLS adapters: dev grants (HMAC-SHA256 via PSA) and the TLS 1.3 channel.
# M10.3 session grants (ECDSA P-256 via PSA) share the adapter (ADR-0091).
add_library(evo_network_tls STATIC src/network/tls/dev_grant.cpp src/network/tls/channel.cpp
@@ -61,9 +65,10 @@ evo_owned_target(evo-dev-session)
if(BUILD_TESTING)
add_executable(evo-network-tests tests/network_protocol.cpp tests/network_tls.cpp
tests/network_session.cpp tests/network_control.cpp tests/network_replication.cpp
tests/network_main.cpp)
tests/network_motion.cpp tests/network_main.cpp)
# The TLS tests generate throwaway dev certificates with Mbed TLS directly.
target_link_libraries(evo-network-tests PRIVATE evo_network_session evo_identity mbedtls)
target_link_libraries(evo-network-tests PRIVATE evo_network_session evo_identity
evo_client_prediction mbedtls)
evo_owned_target(evo-network-tests)
add_test(NAME network COMMAND evo-network-tests)
set_tests_properties(network PROPERTIES TIMEOUT 120 LABELS "network")
+3
View File
@@ -528,6 +528,9 @@ headless client with process kill tests done. 10.5 split (ADR-0093): 10.5a sessi
protocol v2 and the replication core done; 10.5b wiring (sessions, evo-server, client,
probe) with process evidence done; 10.5c engineering client switched to M10 sessions
(snapshot views, camera interest, grant bundles, msquic.dll in the Windows package) done.
10.6 split (ADR-0094, EXPERIMENT probe marker, not an organism movement rule): 10.6a shared
probe-motion-v1 rule, server markers, session protocol v3 marker records and the client
predictor done; 10.6b wiring and 10.6c impaired traces follow.
10.6-10.9 planned.
**Entry:** M9 client/session evidence and M7/M8 dev/stage durability. Read
+5 -1
View File
@@ -51,7 +51,11 @@ them. M10.5c switches the engineering client to M10 sessions: snapshot-fed views
driving the interest after the user moves it, grant bundles (`evo-session-probe grants`,
evo-server `--m10-max-grant-lifetime` for dev), and `msquic.dll` in the Windows package.
M10.5 is complete. Deploying the v2 server to evolution-dev (the dev server still runs v1)
is a maintainer step. Next: M10.6 movement prediction and reconciliation.
is a maintainer step. M10.6a (ADR-0094) adds the probe-motion experiment: one
non-biological marker per session moved by intentions with a shared integer rule, session
protocol v3 marker records (v2, deployed, is frozen and refused), and the client predictor
(bounded replay from the authoritative marker, corrections, smoothing, adaptive input lead).
Next: 10.6b wiring into sessions, evo-server, the probe and the GUI.
## Previous gate - 2026-10-02
@@ -0,0 +1,68 @@
# 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 each `outside_window`
refusal 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.
+47
View File
@@ -4479,3 +4479,50 @@ Not done:
not in the dev manifest);
- ASan of the client remote test (msquic under sanitizers is still open);
- a clean-VM package run.
## 2026-10-06 — M10.6a probe-motion experiment core (ADR-0094)
Implemented (EXPERIMENT, not a game rule):
- probe-motion-v1, shared and integer-exact (`include/evo/network/probe_motion.hpp`);
- the server's `ProbeMarkers` (spawn, area, bounded schedule, catch-up bound);
- session protocol v3 marker records, kinds 5 and 6:
- the own marker is always sent, with its applied sequence and area;
- other markers pass the spatial filter;
- v1 and v2 are refused;
- the client `MotionPredictor` (bounded inputs, rebase and replay, corrections, error
samples), `CorrectionSmoother` and `InputLead` (`include/evo/client/motion_prediction.hpp`).
Tests (`tests/network_motion.cpp`):
- the rule's arithmetic and clamping;
- the marker rules;
- client/server loops with whole-tick delays:
- with enough lead, every prediction is exact (zero corrections);
- with too little lead, refusals until the lead adapts, then exact;
- lost inputs give corrections;
- predictor bounds, refusal, drop and reset;
- smoothing and snap, and lead adaptation;
- marker records through the real codec: own versus other, the own marker outside the
interest, unchanged markers not resent, removal, and four malformed records.
The tests that used "3" as a future protocol version now use 4.
Executed:
- **Linux GCC 14**
- `evo-network-tests` and `evo-quic-session-tests`;
- preset `quic`: CTest 4/4;
- `client-network`: 14/14;
- `postgres-check.sh` with QUIC: 20 suites, including region m10 session.
- **Linux Clang 19:** build, ASan/UBSan `evo-network-tests`, clang-tidy 19 on the new and
changed sources and tests.
- **Windows MSVC 19.44** (fresh binaries):
- preset `quic`: 4/4;
- preset `client-network`: 12/12.
The repository format check fails only on `include/evo/server/session_window.hpp`, as
before.
Not done:
- wiring into sessions, evo-server, the probe and the GUI (10.6b);
- impaired traces (10.6c).
Deployed v2 servers refuse v3 clients until redeployed.
+137
View File
@@ -0,0 +1,137 @@
#pragma once
#include "evo/network/probe_motion.hpp"
#include <cstddef>
#include <cstdint>
#include <map>
#include <optional>
#include <vector>
// M10.6 client prediction and reconciliation of the probe marker (ADR-0094). Headless,
// single-owner, presentation only: nothing here is authority.
//
// The predictor keeps a bounded list of sent, unacknowledged inputs. On each authoritative
// marker state (from a snapshot: state after tick T, newest applied intention sequence) it
// restores that state, drops inputs that are applied or can no longer apply (tick <= T),
// and replays the rest with the shared rule up to the presented tick. The difference that
// rebasing makes to the presented position is a correction; the smoother hides it over a
// short time (or snaps when it is large). Prediction never outlives its inputs: a refused
// intention is removed, and a reset (new session or epoch) forgets everything.
namespace evo::client {
struct PredictionLimits {
std::size_t max_pending{32}; // Sent, unacknowledged inputs (bounded replay).
std::uint64_t max_replay_ticks{32}; // Ticks predicted beyond the authoritative state.
std::size_t max_history{128}; // Predicted states kept to measure errors.
std::size_t max_errors{4096}; // Error samples awaiting take_errors().
};
struct MotionInput {
std::uint64_t sequence{}, tick{};
network::motion::Vector vector;
};
// The authoritative marker as a snapshot reports it: the state after `tick`.
struct AuthoritativeMarker {
std::uint64_t tick{}, applied_sequence{};
network::motion::State state;
network::motion::Area area;
};
struct PredictionStats {
std::uint64_t authoritative{}, corrections{}, replayed_ticks{}, dropped_inputs{},
rejected_inputs{}, refused_inputs{};
std::uint64_t max_error_um{}, max_pending{};
};
class MotionPredictor {
public:
explicit MotionPredictor(PredictionLimits limits = {}) : limits_{limits} {}
// A new session or epoch: forget the authoritative state, inputs and history.
void reset();
// Records a sent input. False (nothing recorded) when the list is full or the input's
// tick is not after the authoritative state; the caller then does not send it.
[[nodiscard]] bool input(const MotionInput& in);
// The server refused this input: it never takes effect.
void rejected(std::uint64_t sequence);
// A newer authoritative state (older or equal ticks are ignored).
void authoritative(const AuthoritativeMarker& a);
// The predicted state after `tick` (the presented tick: server tick plus input lead);
// nothing before the first authoritative state.
[[nodiscard]] std::optional<network::motion::State> predict(std::uint64_t tick);
// The jump rebasing made to the newest prediction (old minus new), since the last call.
struct Offset {
std::int64_t x{}, y{};
};
[[nodiscard]] Offset take_correction() noexcept;
// Distance in micrometres between what was predicted for a tick and what the authority
// reported for it, one sample per authoritative state that had a prediction.
[[nodiscard]] std::vector<std::uint64_t> take_errors();
[[nodiscard]] std::size_t pending() const noexcept {
return pending_.size();
}
[[nodiscard]] bool full() const noexcept {
return pending_.size() >= limits_.max_pending;
}
[[nodiscard]] const std::optional<AuthoritativeMarker>& authority() const noexcept {
return authority_;
}
[[nodiscard]] const PredictionStats& stats() const noexcept {
return stats_;
}
private:
[[nodiscard]] std::optional<network::motion::State> replay(std::uint64_t tick);
// Re-predicts the newest presented tick after a change and accumulates the jump.
void rebase(const std::optional<network::motion::State>& before);
PredictionLimits limits_;
std::optional<AuthoritativeMarker> authority_;
std::vector<MotionInput> pending_; // Ascending tick, then sequence.
std::map<std::uint64_t, network::motion::State> history_;
std::optional<std::uint64_t> presented_tick_;
Offset correction_;
std::vector<std::uint64_t> errors_;
PredictionStats stats_;
};
// Presentation smoothing, separate from prediction: a visual offset that decays to zero.
class CorrectionSmoother {
public:
explicit CorrectionSmoother(double half_life_ms = 60, std::int64_t snap_um = 2'000'000)
: half_life_ms_{half_life_ms}, snap_um_{snap_um} {}
// Adds a correction (old minus new predicted position). Larger offsets snap.
void add(MotionPredictor::Offset correction);
// Advances by `elapsed_ms` and returns the offset to add to the predicted position.
[[nodiscard]] MotionPredictor::Offset advance(double elapsed_ms);
void reset() noexcept {
x_ = y_ = 0;
}
[[nodiscard]] std::uint64_t snaps() const noexcept {
return snaps_;
}
private:
double half_life_ms_;
std::int64_t snap_um_;
double x_{}, y_{};
std::uint64_t snaps_{};
};
// How many ticks ahead of the client's newest known server tick inputs are scheduled. It
// grows when the server refuses an input as too late (outside_window) and shrinks slowly
// when receipts show spare ticks, within [min, max] (max below the admission window).
class InputLead {
public:
explicit InputLead(std::uint64_t min = 2, std::uint64_t max = 7)
: min_{min}, max_{max}, lead_{min} {}
[[nodiscard]] std::uint64_t lead() const noexcept {
return lead_;
}
void too_late() noexcept;
// An admitted input for `tick` received at the server's `server_tick`.
void admitted(std::uint64_t tick, std::uint64_t server_tick) noexcept;
void reset() noexcept {
lead_ = min_;
spare_ = 0;
}
private:
std::uint64_t min_, max_, lead_;
std::uint32_t spare_{};
};
} // namespace evo::client
+100
View File
@@ -0,0 +1,100 @@
#pragma once
#include <cstddef>
#include <cstdint>
#include <deque>
#include <expected>
#include <optional>
#include <vector>
// M10.6 probe-motion experiment (ADR-0094). EXPERIMENT, not a game rule: one
// non-biological engineering marker per session moves at a fixed speed so that client
// prediction and reconciliation can be proven before M11 decides organism movement. A
// marker has a position only: no energy, contact, perception, biology or durability (it
// lives in the region's memory for its session and is respawned after a restart).
//
// The rule is shared, versioned and integer-exact, so the client replays exactly what the
// server simulated: each tick the held movement vector (norm <= 1000, as admitted) moves
// the marker by vector * speed / 1000 micrometres per axis, clamped to the area's bounds.
// An intention scheduled for tick T sets the held vector from tick T's step onward.
namespace evo::network::motion {
inline constexpr std::uint32_t rule_version = 1; // probe-motion-v1.
inline constexpr std::int64_t speed_um_per_tick = 100'000; // EXPERIMENT: 100 mm per tick.
inline constexpr std::int64_t micrometres_per_cell = 1'000'000; // 1 m cells.
struct Vector {
std::int16_t x{}, y{};
friend bool operator==(const Vector&, const Vector&) = default;
};
// Inclusive bounds in micrometres, within one Z slice of cells.
struct Area {
std::int64_t min_x{}, min_y{}, max_x{}, max_y{};
std::int64_t z{}; // Cell slice the markers live in.
friend bool operator==(const Area&, const Area&) = default;
};
struct State {
std::int64_t x{}, y{}; // Micrometres.
Vector vector; // Held movement vector.
friend bool operator==(const State&, const State&) = default;
};
// Whether a vector is within the admitted bound (norm <= 1000).
[[nodiscard]] bool valid(Vector v) noexcept;
[[nodiscard]] bool valid(const Area& a) noexcept;
// One simulated tick of the held vector, clamped to the area. Pure and integer-exact.
[[nodiscard]] State step(State s, const Area& a) noexcept;
// Server side: the markers of one region's sessions. Single-owner (the session host).
struct Marker {
std::uint64_t id{}, session{};
State state;
std::uint64_t applied_sequence{}; // Newest intention whose vector is in `state`.
};
enum class MarkerError : std::uint8_t { no_area, unknown_session, full, invalid };
class ProbeMarkers {
public:
explicit ProbeMarkers(std::size_t max_markers = 32, std::size_t max_scheduled = 16)
: max_markers_{max_markers}, max_scheduled_{max_scheduled} {}
// Where markers live and spawn (the spawn is clamped into the area). Existing markers
// are clamped into a new area.
[[nodiscard]] bool set_area(const Area& area, std::int64_t spawn_x, std::int64_t spawn_y);
[[nodiscard]] const std::optional<Area>& area() const noexcept {
return area_;
}
// A marker for the session, at the spawn, holding no movement.
[[nodiscard]] std::expected<std::uint64_t, MarkerError> open(std::uint64_t session);
void close(std::uint64_t session);
void clear() noexcept;
// An admitted intention: from its tick on, the marker holds its vector. Intentions
// arrive in sequence order; the newest per tick wins. Bounded per marker.
[[nodiscard]] std::expected<void, MarkerError>
schedule(std::uint64_t session, std::uint64_t sequence, std::uint64_t tick, Vector vector);
// The host simulated every tick up to `tick`: steps each marker once per tick since the
// last advance (at most `max_catch_up` ticks; a longer gap respawns nothing, it only
// skips motion it can no longer attribute).
void advance(std::uint64_t tick);
[[nodiscard]] const std::vector<Marker>& markers() const noexcept {
return markers_;
}
[[nodiscard]] const Marker* of(std::uint64_t session) const noexcept;
[[nodiscard]] std::uint64_t tick() const noexcept {
return tick_;
}
static constexpr std::uint64_t max_catch_up = 64;
private:
struct Scheduled {
std::uint64_t sequence{}, tick{};
Vector vector;
};
struct Entry {
Marker marker;
std::deque<Scheduled> scheduled; // Ascending tick, then sequence.
};
std::size_t max_markers_, max_scheduled_;
std::optional<Area> area_;
std::int64_t spawn_x_{}, spawn_y_{};
std::vector<Marker> markers_; // Mirror of entries_ for readers, in id order.
std::vector<Entry> entries_;
std::uint64_t tick_{}, next_id_{1};
void publish();
};
} // namespace evo::network::motion
+27 -1
View File
@@ -1,6 +1,7 @@
#pragma once
#include "evo/client/environment_view.hpp"
#include "evo/client/organism_view.hpp"
#include "evo/network/probe_motion.hpp"
#include "evo/network/session_protocol.hpp"
#include <cstddef>
#include <cstdint>
@@ -26,6 +27,11 @@
// already holds. A snapshot is split into self-contained chunks of whole records, one datagram
// each.
//
// M10.6 (ADR-0094): probe markers are replicated too. A session's own marker is always
// sent (whatever its interest), first and every tick it changed, with the newest intention
// sequence applied and the area it moves in, so the client can reconcile its prediction;
// other markers pass the spatial filter like any entity and carry neither.
//
// Client: chunks are assembled per snapshot; a complete snapshot is applied to its baseline
// (one of the two newest applied snapshots) and acknowledged; presentations are rebuilt
// through the validated presentation constructors.
@@ -47,6 +53,9 @@ struct ReplicationSource {
std::uint32_t mask{};
std::vector<client::EnvironmentCell> environment;
std::vector<client::OrganismCell> organisms;
// Probe markers of the region (all of them; filtered per session) and their area.
std::vector<motion::Marker> markers;
std::optional<motion::Area> marker_area;
};
// Whether a session may perceive an organism (the perception extension boundary). Spatial
// interest is applied first; this decides concealment. Default: everything in interest.
@@ -104,6 +113,17 @@ class ReplicationServer {
ReplicationStats stats_;
};
// A probe marker as a client receives it. `own` is the receiving session's marker: only it
// carries the applied sequence and the area (zero otherwise).
struct ReplicatedMarker {
std::uint64_t id{};
motion::State state;
std::int64_t z{};
bool own{};
std::uint64_t applied_sequence{};
motion::Area area;
friend bool operator==(const ReplicatedMarker&, const ReplicatedMarker&) = default;
};
// One applied snapshot as the client holds it.
struct ReplicatedView {
std::uint64_t tick{}, field_revision{}, organism_revision{};
@@ -111,6 +131,7 @@ struct ReplicatedView {
std::int64_t slice_z{};
std::vector<client::EnvironmentCell> environment; // Sorted by voxel.
std::vector<client::OrganismCell> organisms; // Sorted by id.
std::vector<ReplicatedMarker> markers; // Sorted by id; at most one own.
};
enum class AssemblyError : std::uint8_t { malformed, invalid_view };
@@ -148,8 +169,13 @@ enum class RecordKind : std::uint8_t {
environment_upsert = 1,
environment_remove,
organism_upsert,
organism_remove
organism_remove,
marker_upsert, // v3 (ADR-0094).
marker_remove
};
[[nodiscard]] std::vector<std::uint8_t> encode_record(const client::EnvironmentCell& cell);
[[nodiscard]] std::vector<std::uint8_t> encode_record(const client::OrganismCell& cell);
// The own marker also carries its applied sequence and area.
[[nodiscard]] std::vector<std::uint8_t> encode_record(const motion::Marker& marker, std::int64_t z,
const motion::Area* own_area);
} // namespace evo::network
+4 -3
View File
@@ -16,9 +16,10 @@
// 160-byte credentials here. Later M10 segments add message types under a new version.
namespace evo::network {
inline constexpr std::uint32_t session_magic = 0x4E535645; // Bytes "EVSN".
// v2 (M10.5, ADR-0093): v1 plus interest, snapshot chunks and snapshot acks. v1 is frozen
// and no longer accepted (it was only ever deployed to evolution-dev, with the probe).
inline constexpr std::uint16_t session_protocol_version = 2;
// v2 (M10.5, ADR-0093): v1 plus interest, snapshot chunks and snapshot acks.
// v3 (M10.6, ADR-0094): v2 plus probe marker records inside snapshot chunks; no new message
// types. v1 and v2 were deployed to evolution-dev and are frozen; only v3 is accepted.
inline constexpr std::uint16_t session_protocol_version = 3;
inline constexpr std::size_t session_datagram_bytes = 1200; // Whole message, ADR-0089.
inline constexpr std::size_t session_header_bytes = 8;
inline constexpr std::size_t session_grant_wire_bytes = 160;
+3
View File
@@ -12,6 +12,9 @@ server then sends Close (`unsupported_version` for another version, otherwise
`protocol`) and closes the connection. Version 1 messages are refused
(`unsupported_version`). Once v2 is deployed it is frozen like v1.
Superseded by [version 3](session-v3.md) (ADR-0094): v2 was deployed to evolution-dev on
2026-10-06 and is frozen; v3 servers and clients refuse it.
## Header (8 bytes)
| Offset | Size | Field | Rule |
|---|---|---|---|
+25
View File
@@ -0,0 +1,25 @@
# M10 session protocol, version 3
Version 3 is [version 2](session-v2.md) with two more snapshot record kinds for the M10.6
probe-motion experiment (ADR-0094). Message types, lengths and rules are those of v2. The
header version is 3. Versions 1 and 2 were deployed to evolution-dev and are frozen; both
are refused (`unsupported_version`). Once v3 is deployed it is frozen like them.
## Snapshot records (in addition to v2 kinds 1-4)
| Kind | Body |
|---|---|
| 5 marker upsert | id u64, x, y (i64 um), z (i64 cell slice), move_x, move_y (i16), own u8 (0 or 1); when own = 1: applied_sequence u64, area min_x, min_y, max_x, max_y (i64 um) |
| 6 marker remove | id u64 |
- A marker is a non-biological engineering marker, one per session (ADR-0094). The
receiving session's own marker has own = 1 and is sent whatever its interest, with the
newest applied intention sequence and the inclusive area (min <= max) it moves in. A
snapshot holds at most one own marker. Other sessions' markers have own = 0, no sequence
or area, and pass the spatial filter (z equals the interest slice, cell within the square).
- id is nonzero; the vector's norm is at most 1000. A marker's z is not bound to slice_z.
Anything else is malformed and closes the session (`protocol`).
- The marker state is the state after the snapshot's tick: the client restores it, drops
inputs with sequence <= applied_sequence or tick <= the snapshot tick, and replays the
rest with probe-motion-v1 (position += vector x 100,000 / 1,000 um per tick per axis,
clamped to the area; an intention for tick T sets the held vector from T's step on).
+161
View File
@@ -0,0 +1,161 @@
#include "evo/client/motion_prediction.hpp"
#include <algorithm>
#include <cmath>
#include <utility>
namespace evo::client {
namespace {
std::uint64_t distance_um(const network::motion::State& a, const network::motion::State& b) {
const auto dx = static_cast<double>(a.x - b.x), dy = static_cast<double>(a.y - b.y);
return static_cast<std::uint64_t>(std::llround(std::sqrt((dx * dx) + (dy * dy))));
}
} // namespace
void MotionPredictor::reset() {
authority_.reset();
pending_.clear();
history_.clear();
presented_tick_.reset();
correction_ = {};
}
bool MotionPredictor::input(const MotionInput& in) {
if (full() || !network::motion::valid(in.vector) ||
(authority_ && in.tick <= authority_->tick) ||
(!pending_.empty() && in.sequence <= pending_.back().sequence))
return false;
// A new input changes the future, not what is shown now: it is not a correction.
const auto at = std::ranges::upper_bound(pending_, in.tick, {}, &MotionInput::tick);
pending_.insert(at, in);
stats_.max_pending = std::max<std::uint64_t>(stats_.max_pending, pending_.size());
return true;
}
void MotionPredictor::rejected(std::uint64_t sequence) {
const auto it = std::ranges::find(pending_, sequence, &MotionInput::sequence);
if (it == pending_.end())
return;
const auto before = presented_tick_ ? replay(*presented_tick_) : std::nullopt;
pending_.erase(it);
++stats_.rejected_inputs;
rebase(before);
}
void MotionPredictor::authoritative(const AuthoritativeMarker& a) {
if (authority_ && a.tick <= authority_->tick)
return;
++stats_.authoritative;
if (const auto predicted = history_.find(a.tick); predicted != history_.end()) {
const auto error = distance_um(predicted->second, a.state);
stats_.max_error_um = std::max(stats_.max_error_um, error);
if (errors_.size() < limits_.max_errors)
errors_.push_back(error);
}
std::erase_if(history_, [&](const auto& e) { return e.first <= a.tick; });
const auto before = presented_tick_ ? replay(*presented_tick_) : std::nullopt;
// Applied inputs are in the state; unapplied ones whose tick has run never will be.
stats_.dropped_inputs +=
static_cast<std::uint64_t>(std::ranges::count_if(pending_, [&](const MotionInput& in) {
return in.sequence > a.applied_sequence && in.tick <= a.tick;
}));
std::erase_if(pending_, [&](const MotionInput& in) {
return in.sequence <= a.applied_sequence || in.tick <= a.tick;
});
authority_ = a;
rebase(before);
}
std::optional<network::motion::State> MotionPredictor::predict(std::uint64_t tick) {
if (!authority_)
return std::nullopt;
const auto authority_tick = authority_->tick;
auto state = replay(tick);
if (!state)
return std::nullopt;
presented_tick_ = tick;
if (tick > authority_tick) {
history_[tick] = *state;
while (history_.size() > limits_.max_history)
history_.erase(history_.begin());
}
return state;
}
std::optional<network::motion::State> MotionPredictor::replay(std::uint64_t tick) {
if (!authority_)
return std::nullopt;
auto state = authority_->state;
if (tick <= authority_->tick)
return state;
const auto last =
authority_->tick + std::min(tick - authority_->tick, limits_.max_replay_ticks);
auto next = pending_.begin();
for (auto t = authority_->tick + 1; t <= last; ++t) {
for (; next != pending_.end() && next->tick <= t; ++next)
state.vector = next->vector;
state = network::motion::step(state, authority_->area);
++stats_.replayed_ticks;
}
return state;
}
void MotionPredictor::rebase(const std::optional<network::motion::State>& before) {
if (!before || !presented_tick_)
return;
const auto after = replay(*presented_tick_);
if (!after)
return;
const auto dx = before->x - after->x, dy = before->y - after->y;
if (dx != 0 || dy != 0) {
++stats_.corrections;
correction_.x += dx;
correction_.y += dy;
}
}
MotionPredictor::Offset MotionPredictor::take_correction() noexcept {
return std::exchange(correction_, Offset{});
}
std::vector<std::uint64_t> MotionPredictor::take_errors() {
return std::exchange(errors_, {});
}
void CorrectionSmoother::add(MotionPredictor::Offset c) {
x_ += static_cast<double>(c.x);
y_ += static_cast<double>(c.y);
if (std::hypot(x_, y_) > static_cast<double>(snap_um_)) {
x_ = y_ = 0; // Too far to glide: show the corrected position at once.
++snaps_;
}
}
MotionPredictor::Offset CorrectionSmoother::advance(double elapsed_ms) {
if (elapsed_ms > 0 && half_life_ms_ > 0) {
const double keep = std::exp2(-elapsed_ms / half_life_ms_);
x_ *= keep;
y_ *= keep;
}
if (std::abs(x_) < 1 && std::abs(y_) < 1)
x_ = y_ = 0;
return {static_cast<std::int64_t>(std::llround(x_)),
static_cast<std::int64_t>(std::llround(y_))};
}
void InputLead::too_late() noexcept {
lead_ = std::min(lead_ + 1, max_);
spare_ = 0;
}
void InputLead::admitted(std::uint64_t tick, std::uint64_t server_tick) noexcept {
// More than two ticks to spare twenty times in a row: one tick less lead.
if (tick > server_tick + 2) {
if (++spare_ >= 20 && lead_ > min_) {
--lead_;
spare_ = 0;
}
} else {
spare_ = 0;
}
}
} // namespace evo::client
+130
View File
@@ -0,0 +1,130 @@
#include "evo/network/probe_motion.hpp"
#include <algorithm>
namespace evo::network::motion {
namespace {
constexpr std::int32_t max_component = 1000;
// Far inside int64: a marker never moves more than one speed step per axis per tick.
constexpr std::int64_t max_coordinate = std::int64_t{1} << 60;
} // namespace
bool valid(Vector v) noexcept {
const std::int32_t x = v.x, y = v.y;
return (x * x) + (y * y) <= max_component * max_component;
}
bool valid(const Area& a) noexcept {
return a.min_x <= a.max_x && a.min_y <= a.max_y && a.min_x >= -max_coordinate &&
a.max_x <= max_coordinate && a.min_y >= -max_coordinate && a.max_y <= max_coordinate;
}
State step(State s, const Area& a) noexcept {
const auto dx = (std::int64_t{s.vector.x} * speed_um_per_tick) / max_component;
const auto dy = (std::int64_t{s.vector.y} * speed_um_per_tick) / max_component;
s.x = std::clamp(s.x + dx, a.min_x, a.max_x);
s.y = std::clamp(s.y + dy, a.min_y, a.max_y);
return s;
}
bool ProbeMarkers::set_area(const Area& area, std::int64_t spawn_x, std::int64_t spawn_y) {
if (!valid(area))
return false;
area_ = area;
spawn_x_ = std::clamp(spawn_x, area.min_x, area.max_x);
spawn_y_ = std::clamp(spawn_y, area.min_y, area.max_y);
for (auto& e : entries_) {
e.marker.state.x = std::clamp(e.marker.state.x, area.min_x, area.max_x);
e.marker.state.y = std::clamp(e.marker.state.y, area.min_y, area.max_y);
}
publish();
return true;
}
std::expected<std::uint64_t, MarkerError> ProbeMarkers::open(std::uint64_t session) {
if (!area_)
return std::unexpected(MarkerError::no_area);
if (session == 0 ||
std::ranges::any_of(entries_, [&](const Entry& e) { return e.marker.session == session; }))
return std::unexpected(MarkerError::invalid);
if (entries_.size() >= max_markers_)
return std::unexpected(MarkerError::full);
Entry e;
e.marker.id = next_id_++;
e.marker.session = session;
e.marker.state = {spawn_x_, spawn_y_, {}};
entries_.push_back(std::move(e));
publish();
return entries_.back().marker.id;
}
void ProbeMarkers::close(std::uint64_t session) {
std::erase_if(entries_, [&](const Entry& e) { return e.marker.session == session; });
publish();
}
void ProbeMarkers::clear() noexcept {
entries_.clear();
markers_.clear();
}
std::expected<void, MarkerError> ProbeMarkers::schedule(std::uint64_t session,
std::uint64_t sequence, std::uint64_t tick,
Vector vector) {
const auto it =
std::ranges::find_if(entries_, [&](const Entry& e) { return e.marker.session == session; });
if (it == entries_.end())
return std::unexpected(MarkerError::unknown_session);
if (!valid(vector) || tick <= tick_ || sequence <= it->marker.applied_sequence ||
(!it->scheduled.empty() && sequence <= it->scheduled.back().sequence))
return std::unexpected(MarkerError::invalid);
if (it->scheduled.size() >= max_scheduled_)
return std::unexpected(MarkerError::full);
// Keep ascending tick order; a later sequence for an earlier tick supersedes nothing
// already scheduled after it (each takes effect at its own tick).
const auto at = std::ranges::upper_bound(it->scheduled, tick, {}, &Scheduled::tick);
it->scheduled.insert(at, Scheduled{sequence, tick, vector});
return {};
}
void ProbeMarkers::advance(std::uint64_t tick) {
if (tick <= tick_)
return;
if (!area_) {
tick_ = tick;
return;
}
const auto first = tick - tick_ > max_catch_up ? tick - max_catch_up + 1 : tick_ + 1;
for (auto& e : entries_) {
auto& m = e.marker;
// Intentions for ticks that can no longer be stepped still set the held vector.
while (!e.scheduled.empty() && e.scheduled.front().tick < first) {
m.state.vector = e.scheduled.front().vector;
m.applied_sequence = std::max(m.applied_sequence, e.scheduled.front().sequence);
e.scheduled.pop_front();
}
for (auto t = first; t <= tick; ++t) {
while (!e.scheduled.empty() && e.scheduled.front().tick == t) {
m.state.vector = e.scheduled.front().vector;
m.applied_sequence = std::max(m.applied_sequence, e.scheduled.front().sequence);
e.scheduled.pop_front();
}
m.state = step(m.state, *area_);
}
}
tick_ = tick;
publish();
}
const Marker* ProbeMarkers::of(std::uint64_t session) const noexcept {
const auto it =
std::ranges::find_if(markers_, [&](const Marker& m) { return m.session == session; });
return it == markers_.end() ? nullptr : &*it;
}
void ProbeMarkers::publish() {
markers_.clear();
for (const auto& e : entries_)
markers_.push_back(e.marker);
std::ranges::sort(markers_, {}, &Marker::id);
}
} // namespace evo::network::motion
+78 -4
View File
@@ -70,6 +70,19 @@ std::vector<std::uint8_t> remove_organism(std::uint64_t id) {
put(out, id, 8);
return out;
}
std::vector<std::uint8_t> remove_marker(std::uint64_t id) {
std::vector<std::uint8_t> out{static_cast<std::uint8_t>(RecordKind::marker_remove)};
put(out, id, 8);
return out;
}
constexpr auto environment_kind = static_cast<std::uint8_t>(RecordKind::environment_upsert);
constexpr auto organism_kind = static_cast<std::uint8_t>(RecordKind::organism_upsert);
constexpr auto marker_kind = static_cast<std::uint8_t>(RecordKind::marker_upsert);
// The cell a marker position (micrometres) lies in.
std::int64_t cell_of(std::int64_t um) {
const auto q = um / motion::micrometres_per_cell;
return (um % motion::micrometres_per_cell != 0 && um < 0) ? q - 1 : q;
}
std::uint64_t distance(std::int64_t x, std::int64_t y, const SessionInterest& i) {
const auto dx =
x > i.x ? static_cast<std::uint64_t>(x - i.x) : static_cast<std::uint64_t>(i.x - x);
@@ -128,6 +141,24 @@ std::vector<std::uint8_t> encode_record(const client::OrganismCell& c) {
return out;
}
std::vector<std::uint8_t> encode_record(const motion::Marker& m, std::int64_t z,
const motion::Area* own_area) {
std::vector<std::uint8_t> out{static_cast<std::uint8_t>(RecordKind::marker_upsert)};
put(out, m.id, 8);
put_signed(out, m.state.x);
put_signed(out, m.state.y);
put_signed(out, z);
put(out, static_cast<std::uint16_t>(m.state.vector.x), 2);
put(out, static_cast<std::uint16_t>(m.state.vector.y), 2);
out.push_back(own_area != nullptr ? 1 : 0);
if (own_area != nullptr) {
put(out, m.applied_sequence, 8);
for (const auto v : {own_area->min_x, own_area->min_y, own_area->max_x, own_area->max_y})
put_signed(out, v);
}
return out;
}
std::expected<ReplicationServer, ReplicationError> ReplicationServer::create(ReplicationLimits l) {
if (l.max_radius == 0 || l.max_radius > 7 || l.near_radius > l.max_radius ||
l.far_interval == 0 || l.max_baselines == 0 || l.max_baselines > 16 ||
@@ -219,13 +250,24 @@ std::vector<std::pair<std::uint64_t, std::vector<SnapshotChunk>>> ReplicationSer
std::map<Key, std::pair<std::vector<std::uint8_t>, std::uint64_t>> truth;
for (const auto& c : src.environment)
if (c.voxel.z == in.z && distance(c.voxel.x, c.voxel.y, in) <= in.radius)
truth[Key{std::uint8_t{1}, c.voxel.x, c.voxel.y, c.voxel.z}] = {
truth[Key{environment_kind, c.voxel.x, c.voxel.y, c.voxel.z}] = {
encode_record(c), distance(c.voxel.x, c.voxel.y, in)};
for (const auto& o : src.organisms)
if (o.voxel.z == in.z && distance(o.voxel.x, o.voxel.y, in) <= in.radius &&
(!perceives || perceives(s.id, o)))
truth[Key{std::uint8_t{3}, static_cast<std::int64_t>(o.id), 0, 0}] = {
truth[Key{organism_kind, static_cast<std::int64_t>(o.id), 0, 0}] = {
encode_record(o), distance(o.voxel.x, o.voxel.y, in)};
// Markers: the own one always; others in the square of the slice. Distance 0 puts
// every marker first and makes it due every tick it changed.
if (src.marker_area)
for (const auto& m : src.markers) {
const bool own = m.session == s.id;
if (!own && (src.marker_area->z != in.z ||
distance(cell_of(m.state.x), cell_of(m.state.y), in) > in.radius))
continue;
truth[Key{marker_kind, static_cast<std::int64_t>(m.id), 0, 0}] = {
encode_record(m, src.marker_area->z, own ? &*src.marker_area : nullptr), 0};
}
// Baselines older than the limit are forgotten; an expired ack means a fresh one.
while (!s.baselines.empty() && tick - s.baselines.front().tick > limits_.max_baseline_age)
s.baselines.pop_front();
@@ -244,9 +286,11 @@ std::vector<std::pair<std::uint64_t, std::vector<SnapshotChunk>>> ReplicationSer
for (const auto& [key, entry] : base_state)
if (!truth.contains(key)) {
removals.push_back(
std::get<0>(key) == 1
std::get<0>(key) == environment_kind
? remove_environment({std::get<1>(key), std::get<2>(key), std::get<3>(key)})
: remove_organism(static_cast<std::uint64_t>(std::get<1>(key))));
: std::get<0>(key) == organism_kind
? remove_organism(static_cast<std::uint64_t>(std::get<1>(key)))
: remove_marker(static_cast<std::uint64_t>(std::get<1>(key))));
removed.push_back(key);
}
std::vector<Candidate> candidates;
@@ -384,11 +428,14 @@ SnapshotAssembler::accept(const SnapshotChunk& chunk) {
}
std::map<std::pair<std::int64_t, std::int64_t>, client::EnvironmentCell> environment;
std::map<std::uint64_t, client::OrganismCell> organisms;
std::map<std::uint64_t, ReplicatedMarker> markers;
if (base) {
for (const auto& c : base->environment)
environment[{c.voxel.x, c.voxel.y}] = c;
for (const auto& o : base->organisms)
organisms[o.id] = o;
for (const auto& m : base->markers)
markers[m.id] = m;
}
for (const auto& records : p.chunks) {
if (!records)
@@ -447,6 +494,29 @@ SnapshotAssembler::accept(const SnapshotChunk& chunk) {
organisms[o.id] = o;
} else if (kind == static_cast<std::uint8_t>(RecordKind::organism_remove)) {
organisms.erase(r.u(8));
} else if (kind == static_cast<std::uint8_t>(RecordKind::marker_upsert)) {
ReplicatedMarker m;
m.id = r.u(8);
m.state.x = r.i64();
m.state.y = r.i64();
m.z = r.i64();
m.state.vector = {static_cast<std::int16_t>(r.u(2)),
static_cast<std::int16_t>(r.u(2))};
const auto own = r.u(1);
if (own > 1)
return std::unexpected(AssemblyError::malformed);
m.own = own == 1;
if (m.own) {
m.applied_sequence = r.u(8);
m.area = {r.i64(), r.i64(), r.i64(), r.i64(), m.z};
if (r.ok() && !motion::valid(m.area))
return std::unexpected(AssemblyError::malformed);
}
if (r.ok() && (m.id == 0 || !motion::valid(m.state.vector)))
return std::unexpected(AssemblyError::malformed);
markers[m.id] = m;
} else if (kind == static_cast<std::uint8_t>(RecordKind::marker_remove)) {
markers.erase(r.u(8));
} else {
return std::unexpected(AssemblyError::malformed);
}
@@ -464,6 +534,10 @@ SnapshotAssembler::accept(const SnapshotChunk& chunk) {
view.environment.push_back(cell);
for (auto& [id, organism] : organisms)
view.organisms.push_back(organism);
for (auto& [id, marker] : markers)
view.markers.push_back(marker);
if (std::ranges::count_if(view.markers, &ReplicatedMarker::own) > 1)
return std::unexpected(AssemblyError::malformed);
// The same validation as any presentation: a snapshot that cannot be shown is refused.
if (!client::EnvironmentPresentation::create({identity_, view.tick, view.field_revision},
view.mask, view.slice_z, view.environment) &&
+1 -1
View File
@@ -362,7 +362,7 @@ void session_codec() {
mutated.at(0) ^= 1;
CHECK(refused(decode_session(mutated), SessionCodecError::bad_magic));
mutated = bytes;
mutated.at(4) = 3;
mutated.at(4) = 4; // A future version.
CHECK(refused(decode_session(mutated), SessionCodecError::unsupported_version));
mutated = bytes;
mutated.at(7) = 1;
+1
View File
@@ -8,6 +8,7 @@ int main() try {
evo::network_test::session_tests();
evo::network_test::control_tests();
evo::network_test::replication_tests();
evo::network_test::motion_tests();
std::puts("network tests passed");
return 0;
} catch (const std::exception& e) {
+329
View File
@@ -0,0 +1,329 @@
// M10.6 probe-motion experiment (ADR-0094): the shared rule, the server's markers, client
// prediction and reconciliation (exact replay, refused and lost inputs, resets, bounds),
// presentation smoothing, the input lead, and marker records in v3 snapshots.
#include "evo/client/motion_prediction.hpp"
#include "evo/network/replication.hpp"
#include "network_test.hpp"
#include <algorithm>
#include <deque>
#include <functional>
#include <set>
#include <vector>
namespace evo::network_test {
namespace {
using namespace evo::network;
using motion::Area;
using motion::ProbeMarkers;
using motion::State;
using motion::Vector;
constexpr Area area{-5'000'000, -5'000'000, 5'000'000, 5'000'000, -7};
void rule() {
CHECK(motion::valid(Vector{1000, 0}) && motion::valid(Vector{707, 707}) &&
motion::valid(Vector{0, -1000}) && !motion::valid(Vector{708, 708}) &&
!motion::valid(Vector{-32768, 0}) && !motion::valid(Vector{1001, 0}));
CHECK(motion::step({0, 0, {1000, 0}}, area) == State{100'000, 0, {1000, 0}});
CHECK(motion::step({0, 0, {707, -707}}, area) == State{70'700, -70'700, {707, -707}});
CHECK(motion::step({0, 0, {-1, 1}}, area) == State{-100, 100, {-1, 1}}); // Exact.
CHECK(motion::step({0, 0, {}}, area) == State{0, 0, {}});
// Clamped to the area, holding the vector.
CHECK(motion::step({4'950'000, -4'990'000, {1000, -1000}}, area) ==
State{5'000'000, -5'000'000, {1000, -1000}});
CHECK(!motion::valid(Area{1, 0, 0, 0, 0}) && motion::valid(Area{0, 0, 0, 0, 0}));
}
void markers() {
ProbeMarkers m{2, 3};
CHECK(refused(m.open(1), motion::MarkerError::no_area));
CHECK(!m.set_area(Area{1, 0, 0, 0, 0}, 0, 0));
CHECK(m.set_area(area, 9'000'000, 0)); // The spawn is clamped into the area.
const auto a = m.open(10), b = m.open(11);
CHECK(a && b && *a == 1 && *b == 2 && refused(m.open(12), motion::MarkerError::full) &&
refused(m.open(10), motion::MarkerError::invalid));
CHECK(m.of(10)->state == State{5'000'000, 0, {}});
m.advance(4);
// From tick 5 on the marker holds the vector; earlier ticks are past.
CHECK(m.schedule(10, 1, 5, {-1000, 0}));
CHECK(refused(m.schedule(10, 2, 4, {}), motion::MarkerError::invalid)); // Past.
CHECK(refused(m.schedule(10, 1, 6, {}), motion::MarkerError::invalid)); // Sequence.
CHECK(refused(m.schedule(10, 2, 6, {2000, 0}), motion::MarkerError::invalid)); // Vector.
CHECK(refused(m.schedule(99, 2, 6, {}), motion::MarkerError::unknown_session));
CHECK(m.schedule(10, 2, 8, {0, 1000}) && m.schedule(10, 3, 9, {}));
CHECK(refused(m.schedule(10, 4, 10, {}), motion::MarkerError::full)); // Bounded.
m.advance(4);
CHECK(m.of(10)->state.x == 5'000'000 && m.of(10)->applied_sequence == 0);
m.advance(5);
CHECK(m.of(10)->state == State{4'900'000, 0, {-1000, 0}} && m.of(10)->applied_sequence == 1);
m.advance(7);
CHECK(m.of(10)->state.x == 4'700'000);
m.advance(9); // Tick 8 moves +y; tick 9 stops.
CHECK(m.of(10)->state == State{4'700'000, 100'000, {}} && m.of(10)->applied_sequence == 3);
CHECK(m.of(11)->state == State{5'000'000, 0, {}});
// A long gap applies what was scheduled but steps at most max_catch_up ticks.
CHECK(m.schedule(10, 4, 10, {1000, 0}));
m.advance(1000);
CHECK(m.of(10)->state.x == 5'000'000 && m.tick() == 1000);
CHECK(m.of(10)->state.vector == Vector{1000, 0});
m.close(10);
CHECK(!m.of(10) && m.markers().size() == 1 && m.open(12) && m.of(12)->id == 3);
}
// One client against the server's markers with whole-tick delays. Inputs reach the server
// `up` ticks after sending, snapshots and receipts reach the client `down` ticks after.
struct Link {
std::uint64_t up{}, down{};
std::set<std::uint64_t> lost; // Input sequences lost on the way.
};
struct Run {
std::vector<std::uint64_t> errors;
std::uint64_t rejected{}, last_rejected_at{}, corrections{}, final_lead{};
std::uint64_t error_ticks_after_warmup{};
};
Run drive(const Link& link, client::InputLead lead, std::uint64_t ticks,
const std::function<Vector(std::uint64_t)>& script) {
ProbeMarkers server;
CHECK(server.set_area(area, 0, 0) && server.open(1));
client::MotionPredictor predictor;
std::deque<std::pair<std::uint64_t, client::MotionInput>> to_server;
std::deque<std::pair<std::uint64_t, client::AuthoritativeMarker>> snapshots;
std::deque<std::pair<std::uint64_t, std::uint64_t>> refusals; // Arrival, sequence.
Run run;
std::uint64_t sequence = 0;
Vector sent{};
for (std::uint64_t t = 1; t <= ticks; ++t) {
// Server: inputs that arrived during tick t-1 are admitted against server tick t-1.
while (!to_server.empty() && to_server.front().first <= t - 1) {
const auto in = to_server.front().second;
to_server.pop_front();
if (in.tick > t - 1 && in.tick - (t - 1) <= 8)
CHECK(server.schedule(1, in.sequence, in.tick, in.vector));
else
refusals.emplace_back(t - 1 + link.down, in.sequence);
}
server.advance(t);
const auto& m = *server.of(1);
snapshots.emplace_back(t + link.down,
client::AuthoritativeMarker{t, m.applied_sequence, m.state, area});
// Client at tick t: it knows the server tick t - down.
while (!snapshots.empty() && snapshots.front().first <= t) {
predictor.authoritative(snapshots.front().second);
snapshots.pop_front();
}
while (!refusals.empty() && refusals.front().first <= t) {
predictor.rejected(refusals.front().second);
lead.too_late();
++run.rejected;
run.last_rejected_at = t;
refusals.pop_front();
}
if (t <= link.down)
continue;
const auto known = t - link.down;
const auto v = script(t);
if (v != sent) {
const client::MotionInput in{++sequence, known + lead.lead(), v};
CHECK(predictor.input(in));
sent = v;
if (!link.lost.contains(in.sequence))
to_server.emplace_back(t + link.up, in);
}
CHECK(predictor.predict(known + lead.lead()));
for (const auto e : predictor.take_errors()) {
run.errors.push_back(e);
if (e != 0 && run.last_rejected_at != 0 && t > run.last_rejected_at + 16)
++run.error_ticks_after_warmup;
}
}
run.corrections = predictor.stats().corrections;
run.final_lead = lead.lead();
return run;
}
Vector zigzag(std::uint64_t t) {
const auto phase = (t / 7) % 4;
return phase == 0 ? Vector{1000, 0}
: phase == 1 ? Vector{0, 1000}
: phase == 2 ? Vector{-707, -707}
: Vector{};
}
void prediction() {
// Enough lead for the round trip: every prediction is exact (shared integer rule).
const auto exact = drive({1, 1, {}}, client::InputLead{4, 7}, 300, zigzag);
CHECK(!exact.errors.empty() && exact.rejected == 0 && exact.corrections == 0 &&
std::ranges::all_of(exact.errors, [](auto e) { return e == 0; }));
// Too little lead: inputs arrive late and are refused; the lead grows until they fit,
// and from then on predictions are exact again.
const auto late = drive({2, 2, {}}, client::InputLead{2, 7}, 400, zigzag);
CHECK(late.rejected > 0 && late.final_lead >= 5 && late.corrections > 0 &&
late.error_ticks_after_warmup == 0);
// A lost input: the authority never applies it; the client reconciles to what ran.
const auto lost = drive({1, 1, {3, 5}}, client::InputLead{4, 7}, 200, zigzag);
CHECK(lost.corrections > 0 && std::ranges::any_of(lost.errors, [](auto e) { return e != 0; }));
}
void predictor_rules() {
client::MotionPredictor p{{4, 8, 16, 16}};
CHECK(!p.predict(5)); // Nothing before the first authoritative state.
CHECK(p.input({1, 3, {1000, 0}}));
p.authoritative({2, 0, {0, 0, {}}, area});
CHECK(p.pending() == 1);
CHECK(must(p.predict(4)) == State{200'000, 0, {1000, 0}}); // Ticks 3 and 4.
// Rejection: the input never takes effect; the shown position jumps back.
p.rejected(1);
CHECK(p.pending() == 0 && must(p.predict(4)) == State{0, 0, {}});
const auto c = p.take_correction();
CHECK(c.x == 200'000 && c.y == 0 && p.take_correction().x == 0);
// Bounded: a full list refuses (the caller does not send); stale ticks are refused.
for (std::uint64_t s = 2; s <= 5; ++s)
CHECK(p.input({s, 2 + s, {0, 1000}}));
CHECK(p.full() && !p.input({6, 9, {}}));
p.authoritative({4, 3, {0, 100'000, {0, 1000}}, area}); // Applied through 3, tick 4.
CHECK(p.pending() == 2 && !p.input({6, 4, {}}) && p.input({6, 9, {}}));
// Replay is bounded in ticks beyond the authority (8 here); ticks 5-8 move, the
// tick-9 input stops the marker.
const auto replayed = p.stats().replayed_ticks;
const auto far = must(p.predict(1000));
CHECK(far.y == 100'000 + (4 * 100'000) && p.stats().replayed_ticks - replayed == 8);
p.authoritative({3, 9, {}, area}); // Older: ignored.
CHECK(must(p.authority()).tick == 4);
// An input that the authority passed without applying is dropped.
p.authoritative({7, 4, {0, 400'000, {0, 1000}}, area});
CHECK(p.pending() == 1 && p.stats().dropped_inputs == 1);
// Reset (new session or epoch) forgets everything.
p.reset();
CHECK(!p.authority() && p.pending() == 0 && !p.predict(8));
}
void smoothing_and_lead() {
client::CorrectionSmoother s{60, 2'000'000};
s.add({1'000'000, -400'000});
const auto half = s.advance(60);
CHECK(half.x == 500'000 && half.y == -200'000);
CHECK(s.advance(600).x < 1'000 && s.snaps() == 0);
s.add({3'000'000, 0}); // Beyond the snap distance: no glide.
CHECK(s.snaps() == 1 && s.advance(0).x == 0);
client::InputLead lead{2, 5};
for (int i = 0; i < 10; ++i)
lead.too_late();
CHECK(lead.lead() == 5);
for (int i = 0; i < 19; ++i)
lead.admitted(100, 90);
CHECK(lead.lead() == 5);
lead.admitted(100, 90);
CHECK(lead.lead() == 4);
lead.admitted(100, 99); // No spare: the count restarts.
for (int i = 0; i < 19; ++i)
lead.admitted(100, 90);
CHECK(lead.lead() == 4);
}
// Markers in v3 snapshots through the real codec.
std::vector<SnapshotAck> deliver(SnapshotAssembler& client,
const std::vector<SnapshotChunk>& chunks) {
std::vector<SnapshotAck> acks;
for (const auto& c : chunks) {
const auto decoded = decode_session(encode_session(c));
CHECK(decoded);
const auto accepted = client.accept(std::get<SnapshotChunk>(*decoded));
CHECK(accepted);
if (const auto ack = accepted.value_or(std::nullopt))
acks.push_back(*ack);
}
return acks;
}
const std::vector<SnapshotChunk>&
chunks_of(const std::vector<std::pair<std::uint64_t, std::vector<SnapshotChunk>>>& out,
std::uint64_t session) {
const auto it = std::ranges::find_if(out, [&](const auto& e) { return e.first == session; });
CHECK(it != out.end());
return it->second;
}
const ReplicatedMarker* marker(const SnapshotAssembler& a, std::uint64_t id) {
const auto& v = *a.latest();
const auto it = std::ranges::find(v.markers, id, &ReplicatedMarker::id);
return it == v.markers.end() ? nullptr : &*it;
}
void replicated_markers() {
constexpr world::WorldIdentity identity{11, 12};
auto made = ReplicationServer::create({});
CHECK(made);
auto server = std::move(*made);
CHECK(server.open(1, 5) && server.open(2, 5));
CHECK(server.set_interest(1, {0, 0, -7, 2}) && server.set_interest(2, {4, 0, -7, 7}));
ProbeMarkers markers;
CHECK(markers.set_area(area, 0, 0) && markers.open(1) && markers.open(2));
// Session 2's marker starts outside session 1's interest square (x cell 4 > radius 2).
CHECK(markers.schedule(2, 1, 1, {1000, 0}));
const auto source = [&](const SessionInterest&) {
ReplicationSource s;
s.identity = identity;
s.markers = markers.markers();
s.marker_area = markers.area();
return s;
};
SnapshotAssembler a{identity, 5}, b{identity, 5};
std::uint64_t tick = 0;
const auto step = [&] {
markers.advance(++tick);
const auto out = server.tick(tick, source, {});
for (const auto& ack : deliver(a, chunks_of(out, 1)))
server.acknowledge(1, ack);
for (const auto& ack : deliver(b, chunks_of(out, 2)))
server.acknowledge(2, ack);
return out;
};
for (int i = 0; i < 30; ++i)
step(); // Marker 2 moves to x = 3 m (cell 3), then 4 m and beyond.
// Session 1 holds its own marker (with sequence and area) and not marker 2 (outside).
const auto* own = marker(a, 1);
CHECK(own && own->own && own->area == area && own->state == State{0, 0, {}} && own->z == -7 &&
!marker(a, 2));
// Session 2 sees marker 1 (in its square), without sequence or area, and its own.
const auto* other = marker(b, 1);
const auto* mine = marker(b, 2);
CHECK(other && !other->own && other->applied_sequence == 0 && other->area == Area{});
CHECK(mine && mine->own && mine->applied_sequence == 1 && mine->state.x == 3'000'000);
// The own marker is sent even when it is outside the session's interest.
CHECK(server.set_interest(2, {-5, -5, -7, 1}));
step();
step();
CHECK(marker(b, 2) && marker(b, 2)->state.x == 3'200'000 && !marker(b, 1));
// An unchanged marker is not resent; a closed session's marker is removed.
const auto before = server.stats().records;
step();
CHECK(server.stats().records - before == 1); // Only marker 2 moved.
markers.close(1);
step();
CHECK(!marker(a, 1) && !marker(b, 1));
// Malformed marker records are refused.
SnapshotAssembler c{identity, 5};
motion::Marker m;
m.id = 1;
auto two_own = encode_record(m, -7, &area);
m.id = 2;
const auto second = encode_record(m, -7, &area);
two_own.insert(two_own.end(), second.begin(), second.end());
auto bad_flag = encode_record(m, -7, nullptr);
bad_flag.back() = 2;
m.state.vector = {2000, 0};
const auto bad_vector = encode_record(m, -7, nullptr);
m = {};
const auto zero_id = encode_record(m, -7, nullptr);
std::uint64_t t = 100;
for (const auto& records : {two_own, bad_flag, bad_vector, zero_id})
CHECK(refused(c.accept(SnapshotChunk{5, ++t, 0, 0, 0, 0, -7, 0, 1, records}),
AssemblyError::malformed));
}
} // namespace
void motion_tests() {
rule();
markers();
prediction();
predictor_rules();
smoothing_and_lead();
replicated_markers();
}
} // namespace evo::network_test
+6 -4
View File
@@ -121,10 +121,12 @@ void codec_v2() {
SnapshotChunk chunk{5, 9, 7, 3, 4, mask, -7, 1, 2, {1, 2, 3}};
auto bytes = encode_session(chunk);
CHECK(std::get<SnapshotChunk>(*decode_session(bytes)) == chunk);
// Version 1 messages are no longer accepted.
auto v1 = encode_session(ack);
v1.at(4) = 1;
CHECK(refused(decode_session(v1), SessionCodecError::unsupported_version));
// Versions 1 and 2 (frozen, deployed) are no longer accepted (v3, ADR-0094).
for (const std::uint8_t old : {std::uint8_t{1}, std::uint8_t{2}}) {
auto previous = encode_session(ack);
previous.at(4) = old;
CHECK(refused(decode_session(previous), SessionCodecError::unsupported_version));
}
// Header rules: fresh baselines are 0 and always older; index < count <= 16; epoch, tick.
for (const auto& bad : {SnapshotChunk{5, 9, 9, 3, 4, mask, -7, 0, 1, {}},
SnapshotChunk{5, 9, 0, 3, 4, mask, -7, 1, 1, {}},
+1
View File
@@ -28,5 +28,6 @@ void tls_tests();
void session_tests();
void control_tests();
void replication_tests();
void motion_tests();
} // namespace evo::network_test
#define CHECK(...) ::evo::network_test::check(static_cast<bool>(__VA_ARGS__))
+1 -1
View File
@@ -307,7 +307,7 @@ void login_rules(const Files& f) {
CHECK(raw_peer(h, std::nullopt) == Reason::timeout);
CHECK(raw_peer(h, std::vector<std::uint8_t>{1, 2, 3}) == Reason::protocol);
auto future = encode_session(SessionHello{0, h.issuer.grant(carol, 2, start + 60)});
future.at(4) = 3;
future.at(4) = 4;
CHECK(raw_peer(h, future) == Reason::unsupported_version);
CHECK(raw_peer(h, encode_session(SessionClose{Reason::client_closed})) == Reason::protocol);
CHECK(raw_peer(h, encode_session(SessionHello{1, h.issuer.grant(carol, 3, start + 60)})) ==