Files
aevolution/include/evo/network/replication.hpp
T
dingoandClaude Opus 5.5 e640b6d3a3
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
Add M10.5a session protocol v2 and snapshot replication core
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>
2026-10-06 10:22:11 -04:00

152 lines
7.1 KiB
C++

#pragma once
#include "evo/client/environment_view.hpp"
#include "evo/client/organism_view.hpp"
#include "evo/network/session_protocol.hpp"
#include <cstddef>
#include <cstdint>
#include <deque>
#include <expected>
#include <functional>
#include <map>
#include <optional>
#include <tuple>
#include <utility>
#include <vector>
// 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.
//
// 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<client::EnvironmentCell> environment;
std::vector<client::OrganismCell> organisms;
};
// 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<bool(std::uint64_t session, const client::OrganismCell&)>;
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<ReplicationServer, ReplicationError>
create(ReplicationLimits limits);
[[nodiscard]] std::expected<void, ReplicationError> 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<SessionInterest, ReplicationError>
set_interest(std::uint64_t session, SessionInterest interest);
[[nodiscard]] std::optional<SessionInterest> 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<std::pair<std::uint64_t, std::vector<SnapshotChunk>>>
tick(std::uint64_t tick, const std::function<ReplicationSource(const SessionInterest&)>& source,
const Perceives& perceives, std::size_t payload = session_datagram_bytes);
[[nodiscard]] ReplicationStats stats() const;
private:
// (kind, x | id, y, z): environment by voxel, organisms by id.
using Key = std::tuple<std::uint8_t, std::int64_t, std::int64_t, std::int64_t>;
struct Entry {
std::vector<std::uint8_t> 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<Key, Entry> state;
};
struct Session {
std::uint64_t id{}, epoch{}, acked{};
std::optional<SessionInterest> interest;
std::deque<Snapshot> baselines;
};
explicit ReplicationServer(ReplicationLimits limits) : limits_{limits} {}
ReplicationLimits limits_;
std::vector<Session> sessions_;
ReplicationStats stats_;
};
// 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<client::EnvironmentCell> environment; // Sorted by voxel.
std::vector<client::OrganismCell> organisms; // Sorted by id.
};
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<std::optional<SnapshotAck>, AssemblyError>
accept(const SnapshotChunk& chunk);
[[nodiscard]] const ReplicatedView* latest() const noexcept {
return applied_.empty() ? nullptr : &applied_.back();
}
[[nodiscard]] std::expected<client::EnvironmentPresentation, client::ViewError>
environment() const;
[[nodiscard]] std::expected<client::OrganismPresentation, client::ViewError> organisms() const;
[[nodiscard]] std::size_t partial() const noexcept {
return partial_.size();
}
private:
struct Partial {
SnapshotChunk first; // Header fields of the snapshot.
std::vector<std::optional<std::vector<std::uint8_t>>> chunks;
};
world::WorldIdentity identity_;
std::uint64_t epoch_;
std::deque<ReplicatedView> applied_; // At most 2 (ADR-0089).
std::map<std::uint64_t, Partial> 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
};
[[nodiscard]] std::vector<std::uint8_t> encode_record(const client::EnvironmentCell& cell);
[[nodiscard]] std::vector<std::uint8_t> encode_record(const client::OrganismCell& cell);
} // namespace evo::network