#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 #include #include #include #include #include #include #include #include #include // M10.5 bounded snapshot replication with spatial interest (ADR-0093). Transport-neutral and // single-owner on both sides. // // Server: every tick, each session's snapshot is a delta against the newest snapshot the // client acknowledged (kept at most `max_baseline_age` ticks, at most `max_baselines` per // session, always including the acknowledged one) or a fresh baseline. Records are whole entities: // upserts and removals. Interest is a client focus (one Z slice, centre, radius) clamped by the // server; organisms also pass a perception predicate, so concealed state is never encoded. Changed // entities are sent nearest first within the per-tick byte budget; distant ones (beyond // `near_radius`) refresh every `far_interval` ticks; anything deferred keeps the value the client // 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. namespace evo::network { struct ReplicationLimits { std::uint16_t max_radius{7}; // 15 x 15 cells <= the 256-cell presentation limit. std::uint16_t near_radius{3}; // Updated every tick. std::uint64_t far_interval{4}; // Ticks between updates beyond near_radius. std::size_t max_baselines{4}; // Per session (ADR-0089). std::uint64_t max_baseline_age{40}; // Ticks (2 s, ADR-0089). std::size_t tick_budget_bytes{16384}; // Per session per tick (ADR-0089). std::size_t max_sessions{32}; }; // The authority's state around one interest, as the host can see it: environment cells // and organisms of one Z slice (already copied out of the region; no store handles). struct ReplicationSource { world::WorldIdentity identity; std::uint64_t field_revision{}, organism_revision{}; std::uint32_t mask{}; std::vector environment; std::vector organisms; // Probe markers of the region (all of them; filtered per session) and their area. std::vector markers; std::optional 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. using Perceives = std::function; struct ReplicationStats { std::uint64_t snapshots{}, chunks{}, bytes{}, records{}, deferred{}, fresh_baselines{}; std::size_t retained_entities{}; // Entity states held in all sessions' baselines. }; enum class ReplicationError : std::uint8_t { invalid_config, unknown_session, full }; class ReplicationServer { public: [[nodiscard]] static std::expected create(ReplicationLimits limits); [[nodiscard]] std::expected open(std::uint64_t session, std::uint64_t epoch); void close(std::uint64_t session); // Clamped to max_radius. A new interest drops the session's baselines (fresh baseline). [[nodiscard]] std::expected set_interest(std::uint64_t session, SessionInterest interest); [[nodiscard]] std::optional interest(std::uint64_t session) const; // The client completely applied snapshot `tick` (older or unknown acks are ignored). void acknowledge(std::uint64_t session, const SnapshotAck& ack); // Builds every interested session's snapshot for `tick`. `source` is called once per // distinct interest. `payload` is the largest whole message per datagram. [[nodiscard]] std::vector>> tick(std::uint64_t tick, const std::function& source, const Perceives& perceives, std::size_t payload = session_datagram_bytes); // The same with each session's own largest datagram (its path's current limit). [[nodiscard]] std::vector>> tick(std::uint64_t tick, const std::function& source, const Perceives& perceives, const std::function& payload); [[nodiscard]] ReplicationStats stats() const; private: // (kind, x | id, y, z): environment by voxel, organisms by id. using Key = std::tuple; struct Entry { std::vector record; // Encoded upsert record. std::uint64_t updated{}; // Tick this value was sent. bool operator==(const Entry&) const = default; }; struct Snapshot { std::uint64_t tick{}; std::map state; }; struct Session { std::uint64_t id{}, epoch{}, acked{}; std::optional interest; std::deque baselines; }; explicit ReplicationServer(ReplicationLimits limits) : limits_{limits} {} ReplicationLimits limits_; std::vector sessions_; 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{}; bool ghost{}; // v4: a probe being handed to this region, read-only (ADR-0096). 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{}; std::uint32_t mask{}; std::int64_t slice_z{}; std::vector environment; // Sorted by voxel. std::vector organisms; // Sorted by id. std::vector markers; // Sorted by id; at most one own. }; enum class AssemblyError : std::uint8_t { malformed, invalid_view }; class SnapshotAssembler { public: explicit SnapshotAssembler(world::WorldIdentity identity, std::uint64_t epoch) : identity_{identity}, epoch_{epoch} {} // A complete snapshot yields its acknowledgement. Stale, foreign-epoch or // unassemblable chunks are ignored; malformed records or views are errors. [[nodiscard]] std::expected, AssemblyError> accept(const SnapshotChunk& chunk); [[nodiscard]] const ReplicatedView* latest() const noexcept { return applied_.empty() ? nullptr : &applied_.back(); } [[nodiscard]] std::expected environment() const; [[nodiscard]] std::expected organisms() const; [[nodiscard]] std::size_t partial() const noexcept { return partial_.size(); } private: struct Partial { SnapshotChunk first; // Header fields of the snapshot. std::vector>> chunks; }; world::WorldIdentity identity_; std::uint64_t epoch_; std::deque applied_; // At most 2 (ADR-0089). std::map partial_; // At most 4 snapshots in assembly. }; // Record codec, exposed for tests: one record per entity. enum class RecordKind : std::uint8_t { environment_upsert = 1, environment_remove, organism_upsert, organism_remove, marker_upsert, // v3 (ADR-0094). marker_remove }; [[nodiscard]] std::vector encode_record(const client::EnvironmentCell& cell); [[nodiscard]] std::vector encode_record(const client::OrganismCell& cell); // The own marker also carries its applied sequence and area. [[nodiscard]] std::vector encode_record(const motion::Marker& marker, std::int64_t z, const motion::Area* own_area); } // namespace evo::network