Add M10.5a session protocol v2 and snapshot replication core
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

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>
This commit is contained in:
dingo
2026-10-06 10:22:11 -04:00
co-authored by Claude Opus 5.5
parent ca0939dda5
commit e640b6d3a3
17 changed files with 1342 additions and 9 deletions
+393
View File
@@ -0,0 +1,393 @@
// M10.5 replication tests (ADR-0093): session protocol v2 snapshot messages, server-side
// interest, deltas, budgets, baselines and concealment; client-side assembly.
#include "evo/biology/genome.hpp"
#include "evo/network/replication.hpp"
#include "network_test.hpp"
#include <algorithm>
#include <cstdio>
#include <map>
#include <set>
#include <vector>
namespace evo::network_test {
namespace {
using namespace evo::network;
constexpr world::WorldIdentity identity{11, 12};
constexpr std::uint32_t mask = (1U << 0) | (1U << 1) | (1U << 7);
constexpr std::int64_t slice = -7;
client::EnvironmentCell cell(std::int64_t x, std::int64_t y, std::uint64_t quantity = 30) {
client::EnvironmentCell c;
c.voxel = {x, y, slice};
c.chunk_revision = 40;
c.habitat = {{100}, {200}, {0}, {1000}, {500}, {10}};
c.volume = {1000ULL * 500 * 10};
c.substrate = {1};
c.terrain_material = {2};
c.terrain_fill = 1000;
c.presence[0] = client::FieldPresence::present;
c.quantity[0] = quantity;
c.presence[1] = client::FieldPresence::missing;
c.presence[7] = client::FieldPresence::present;
c.quantity[7] = 0xFFFF'FFFF'FFFF'0000ULL;
c.moisture_status = world::MoistureStatus::available;
c.moisture = {3, 50};
return c;
}
client::OrganismCell organism(std::uint64_t id, std::int64_t x, std::int64_t y) {
using biology::Capability;
const auto genome = biology::Genome::create({7,
1,
1,
{},
{{Capability::energy_conversion, 400, 0},
{Capability::membrane, 10, 0},
{Capability::movement, 50, 0},
{Capability::target_size, 8'000'000, 0}}});
CHECK(genome);
const biology::EnvironmentState temperate{
293'150, {{1'000'000'000}, {accounting::Femtograms{1'000'000'000}, {}, {}, {}}}};
auto c = client::present_organism(id, {x, y, slice}, {100}, {200}, *genome, {500, 0}, temperate,
client::OrganismState::alive);
CHECK(c);
return *c;
}
// A 21 x 21 slice centred on the origin, plus organisms.
struct World {
std::map<std::pair<std::int64_t, std::int64_t>, std::uint64_t> quantity;
std::vector<client::OrganismCell> organisms;
std::uint64_t revision{1};
World() {
for (std::int64_t x = -10; x <= 10; ++x)
for (std::int64_t y = -10; y <= 10; ++y)
quantity[{x, y}] = 30;
}
ReplicationSource source() const {
ReplicationSource s;
s.identity = identity;
s.field_revision = revision;
s.organism_revision = revision;
s.mask = mask;
for (const auto& [xy, q] : quantity)
s.environment.push_back(cell(xy.first, xy.second, q));
s.organisms = organisms;
return s;
}
};
ReplicationLimits limits() {
return ReplicationLimits{};
}
// Delivers chunks (optionally dropping some) and returns the acknowledgements.
std::vector<SnapshotAck> deliver(SnapshotAssembler& client,
const std::vector<SnapshotChunk>& chunks,
const std::set<std::size_t>& drop = {}) {
std::vector<SnapshotAck> acks;
for (std::size_t i = 0; i < chunks.size(); ++i) {
if (drop.contains(i))
continue;
// Every chunk crosses the real codec as one datagram.
const auto bytes = encode_session(chunks[i]);
CHECK(bytes.size() <= session_datagram_bytes);
const auto decoded = decode_session(bytes);
CHECK(decoded && std::get<SnapshotChunk>(*decoded) == chunks[i]);
const auto accepted = client.accept(std::get<SnapshotChunk>(*decoded));
CHECK(accepted);
const auto complete = accepted.value_or(std::nullopt);
if (complete)
acks.push_back(*complete);
}
return acks;
}
std::size_t bytes_of(const std::vector<SnapshotChunk>& chunks) {
std::size_t n = 0;
for (const auto& c : chunks)
n += encode_session(c).size();
return n;
}
const std::vector<SnapshotChunk>&
for_session(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;
}
void codec_v2() {
const SessionInterest interest{-3, 4, -7, 7};
const auto i = decode_session(encode_session(interest));
CHECK(i && std::get<SessionInterest>(*i) == interest);
const SnapshotAck ack{5, 9};
CHECK(std::get<SnapshotAck>(*decode_session(encode_session(ack))) == ack);
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));
// 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, {}},
SnapshotChunk{5, 9, 0, 3, 4, mask, -7, 0, 17, {}},
SnapshotChunk{5, 9, 0, 3, 4, mask, -7, 0, 0, {}},
SnapshotChunk{0, 9, 0, 3, 4, mask, -7, 0, 1, {}},
SnapshotChunk{5, 0, 0, 3, 4, mask, -7, 0, 1, {}}})
CHECK(refused(decode_session(encode_session(bad)), SessionCodecError::invalid_value));
chunk.records.assign(max_snapshot_records_bytes, 0);
CHECK(encode_session(chunk).size() == session_datagram_bytes &&
decode_session(encode_session(chunk)));
chunk.records.push_back(0); // One byte more than a datagram.
CHECK(refused(decode_session(encode_session(chunk)), SessionCodecError::wrong_length));
const auto empty = encode_session(SnapshotChunk{5, 9, 0, 3, 4, mask, -7, 0, 1, {}});
for (std::size_t n = 0; n < empty.size(); ++n) // Every truncation of the header.
CHECK(!decode_session(std::span{empty}.first(n)));
}
void convergence_and_deltas() {
auto server = *ReplicationServer::create(limits());
World world;
CHECK(server.open(1, 5));
const auto clamped = server.set_interest(1, {0, 0, slice, 30});
CHECK(clamped && clamped->radius == 7); // 15 x 15 = 225 cells at most.
SnapshotAssembler client{identity, 5};
const auto source = [&](const SessionInterest&) { return world.source(); };
// A fresh 225-cell baseline exceeds 16 KiB: it arrives nearest first over a few ticks.
std::uint64_t tick = 1;
std::size_t first_size = 0;
for (; tick <= 6; ++tick) {
const auto out = server.tick(tick, source, {});
const auto& chunks = for_session(out, 1);
CHECK(bytes_of(chunks) <= 16384 && chunks.size() <= 16);
CHECK(chunks.front().baseline == (tick == 1 ? 0 : tick - 1));
for (const auto& a : deliver(client, chunks))
server.acknowledge(1, a);
if (tick == 1)
first_size = client.latest()->environment.size();
if (client.latest()->environment.size() == 225)
break;
}
CHECK(first_size > 50 && first_size < 225 && tick <= 4);
// Nearest first: the first snapshot holds the cells closest to the focus.
// Leak assertion: nothing outside the interest square ever arrives.
const auto env = client.environment();
CHECK(env && env->cells().size() == 225);
CHECK(std::ranges::all_of(env->cells(), [](const auto& c) {
return c.voxel.x >= -7 && c.voxel.x <= 7 && c.voxel.y >= -7 && c.voxel.y <= 7;
}));
// Converged and unchanged: one empty chunk per tick keeps the cadence.
++tick;
auto out = server.tick(tick, source, {});
CHECK(for_session(out, 1).size() == 1 && for_session(out, 1)[0].records.empty());
for (const auto& a : deliver(client, for_session(out, 1)))
server.acknowledge(1, a);
const auto find = [&](std::int64_t x, std::int64_t y) {
return std::ranges::find_if(client.latest()->environment, [&](const auto& c) {
return c.voxel.x == x && c.voxel.y == y;
});
};
const auto step = [&] {
out = server.tick(++tick, source, {});
for (const auto& a : deliver(client, for_session(out, 1)))
server.acknowledge(1, a);
};
for (int i = 0; i < 4; ++i)
step(); // Every cell was last sent at least 4 ticks ago.
// Changes are sent when due: near every tick, far (radius > 3) every 4 ticks.
world.quantity[{1, 1}] = 99;
world.quantity[{6, 6}] = 77;
step(); // Both were last sent long ago: both due.
CHECK(find(1, 1)->quantity[0] == 99 && find(6, 6)->quantity[0] == 77);
world.quantity[{1, 1}] = 100;
world.quantity[{6, 6}] = 78;
step(); // Near again at once; the far cell was updated a tick ago and waits.
CHECK(for_session(out, 1)[0].records == encode_record(cell(1, 1, 100)));
CHECK(find(1, 1)->quantity[0] == 100 && find(6, 6)->quantity[0] == 77);
int waited = 1;
while (find(6, 6)->quantity[0] != 78 && waited < 8) {
step();
++waited;
}
CHECK(find(6, 6)->quantity[0] == 78 && waited == 4);
// Removal: a cell that disappears is removed from the client's view.
world.quantity.erase(std::pair<std::int64_t, std::int64_t>{0, 0});
++tick;
for (const auto& a : deliver(client, for_session(server.tick(tick, source, {}), 1)))
server.acknowledge(1, a);
CHECK(find(0, 0) == client.latest()->environment.end() &&
client.latest()->environment.size() == 224);
// Loss: a dropped chunk leaves the snapshot incomplete (no ack); the next delta is
// against the older acknowledged snapshot and the client still converges.
for (std::int64_t x = -7; x <= 7; ++x)
world.quantity[{x, 2}] = 500; // Enough changes for several chunks.
++tick;
out = server.tick(tick, source, {});
CHECK(for_session(out, 1).size() > 1);
CHECK(deliver(client, for_session(out, 1), {0}).empty());
const auto acked_before = client.latest()->tick;
++tick;
out = server.tick(tick, source, {});
CHECK(for_session(out, 1).front().baseline == acked_before);
for (const auto& a : deliver(client, for_session(out, 1)))
server.acknowledge(1, a);
CHECK(client.latest()->tick == tick && find(3, 2)->quantity[0] == 500);
// Without acks for more than 40 ticks the server falls back to a fresh baseline.
const auto fresh_before = server.stats().fresh_baselines;
for (int i = 0; i < 40; ++i) // The acknowledged baseline survives 40 ticks...
CHECK(for_session(server.tick(++tick, source, {}), 1).front().baseline != 0);
out = server.tick(++tick, source, {});
CHECK(for_session(out, 1).front().baseline == 0 &&
server.stats().fresh_baselines == fresh_before + 1);
// Baselines are bounded: an ack for an evicted snapshot is ignored (still fresh).
server.acknowledge(1, {5, tick - 30});
out = server.tick(++tick, source, {});
CHECK(for_session(out, 1).front().baseline == 0);
server.acknowledge(1, {4, tick}); // Another epoch: ignored.
out = server.tick(++tick, source, {});
CHECK(for_session(out, 1).front().baseline == 0);
// A new interest starts from a fresh baseline; the client's view follows it.
server.acknowledge(1, {5, tick});
CHECK(server.set_interest(1, {5, 5, slice, 2}));
out = server.tick(++tick, source, {});
CHECK(for_session(out, 1).front().baseline == 0);
SnapshotAssembler moved{identity, 5};
for (const auto& a : deliver(moved, for_session(out, 1)))
server.acknowledge(1, a);
const auto small = moved.environment();
CHECK(small && small->cells().size() == 25 &&
std::ranges::all_of(small->cells(), [](const auto& c) {
return c.voxel.x >= 3 && c.voxel.x <= 7 && c.voxel.y >= 3 && c.voxel.y <= 7;
}));
}
void concealment() {
auto server = *ReplicationServer::create(limits());
World world;
world.organisms = {organism(1, 0, 0), organism(2, 1, 1), organism(3, 9, 9)};
CHECK(server.open(1, 5) && server.open(2, 5));
CHECK(server.set_interest(1, {0, 0, slice, 3}) && server.set_interest(2, {0, 0, slice, 3}));
// Session 1 cannot perceive organism 2 (e.g. concealed); session 2 can.
const Perceives perceives = [](std::uint64_t session, const client::OrganismCell& o) {
return !(session == 1 && o.id == 2);
};
const auto out =
server.tick(1, [&](const SessionInterest&) { return world.source(); }, perceives);
std::vector<std::uint8_t> one, two;
for (const auto& c : for_session(out, 1))
one.insert(one.end(), c.records.begin(), c.records.end());
for (const auto& c : for_session(out, 2))
two.insert(two.end(), c.records.begin(), c.records.end());
const auto contains = [](const std::vector<std::uint8_t>& hay,
const std::vector<std::uint8_t>& needle) {
return std::search(hay.begin(), hay.end(), needle.begin(), needle.end()) != hay.end();
};
// Leak assertions on the encoded bytes: concealed and out-of-interest organisms are absent.
CHECK(contains(one, encode_record(world.organisms[0])) &&
!contains(one, encode_record(world.organisms[1])));
CHECK(contains(two, encode_record(world.organisms[1])));
CHECK(!contains(one, encode_record(world.organisms[2])) &&
!contains(two, encode_record(world.organisms[2])));
SnapshotAssembler client{identity, 5};
(void)deliver(client, for_session(out, 1));
const auto seen = client.organisms();
CHECK(seen && seen->cells().size() == 1 && seen->cells()[0].id == 1);
}
void client_robustness() {
SnapshotAssembler client{identity, 5};
const auto record = encode_record(cell(0, 0));
SnapshotChunk c{5, 3, 0, 1, 1, mask, slice, 0, 1, record};
CHECK(client.accept(c) && client.latest() && client.latest()->tick == 3);
// Stale and foreign-epoch chunks are ignored.
c.tick = 2;
CHECK(client.accept(c) && client.latest()->tick == 3);
c.tick = 4;
c.epoch = 6;
CHECK(client.accept(c) && client.latest()->tick == 3);
c.epoch = 5;
// Malformed records: truncated, unknown kind, another slice, an invalid enumerator.
auto truncated = c;
truncated.records.pop_back();
CHECK(refused(client.accept(truncated), AssemblyError::malformed));
auto unknown = c;
unknown.tick = 5;
unknown.records = {9};
CHECK(refused(client.accept(unknown), AssemblyError::malformed));
auto other = c;
other.tick = 6;
other.records = encode_record([] {
auto x = cell(0, 0);
x.voxel.z = slice + 1;
return x;
}());
CHECK(refused(client.accept(other), AssemblyError::malformed));
// Parts of one snapshot must agree; a delta against an unknown baseline is dropped.
SnapshotChunk part{5, 10, 0, 1, 1, mask, slice, 0, 2, record};
CHECK(client.accept(part));
auto disagree = part;
disagree.index = 1;
disagree.mask = 1;
CHECK(refused(client.accept(disagree), AssemblyError::malformed));
SnapshotChunk orphan{5, 11, 7, 1, 1, mask, slice, 0, 1, {}};
CHECK(client.accept(orphan) && client.latest()->tick == 3);
// At most four snapshots in assembly.
for (std::uint64_t t = 20; t < 30; ++t)
CHECK(client.accept(SnapshotChunk{5, t, 0, 1, 1, mask, slice, 0, 2, record}));
CHECK(client.partial() <= 4);
}
// Dense interest: 32 sessions with different foci over a 41 x 41 slice; every snapshot within
// the per-tick budget; a bandwidth and memory report for the record.
void dense_report() {
auto server = *ReplicationServer::create(limits());
World world;
world.quantity.clear();
for (std::int64_t x = -20; x <= 20; ++x)
for (std::int64_t y = -20; y <= 20; ++y)
world.quantity[{x, y}] = 30;
std::vector<SnapshotAssembler> clients;
for (std::uint64_t s = 1; s <= 32; ++s) {
CHECK(server.open(s, 5));
// Centres within +-13, so every 15 x 15 interest lies inside the 41 x 41 slice.
CHECK(server.set_interest(s, {static_cast<std::int64_t>(s % 8) * 3 - 10,
static_cast<std::int64_t>(s / 8) * 5 - 10, slice, 7}));
clients.emplace_back(identity, 5);
}
CHECK(refused(server.open(33, 5), ReplicationError::full));
std::size_t max_bytes = 0, total = 0;
for (std::uint64_t tick = 1; tick <= 40; ++tick) {
for (std::int64_t x = -20; x <= 20; ++x) // Every tick, a changing row.
world.quantity[{x, static_cast<std::int64_t>(tick % 41) - 20}] = 100 + tick;
const auto out =
server.tick(tick, [&](const SessionInterest&) { return world.source(); }, {});
CHECK(out.size() == 32);
for (const auto& [session, chunks] : out) {
const auto n = bytes_of(chunks);
max_bytes = std::max(max_bytes, n);
total += n;
for (const auto& a : deliver(clients[session - 1], chunks))
server.acknowledge(session, a);
}
}
CHECK(max_bytes <= 16384);
CHECK(std::ranges::all_of(clients, [](const auto& c) {
return c.latest() && c.latest()->environment.size() == 225;
}));
const auto stats = server.stats();
CHECK(stats.retained_entities <= std::size_t{32} * 4 * 225);
std::printf(
"replication_report sessions=32 ticks=40 max_bytes_per_tick=%zu mean_bytes_per_tick=%zu "
"chunks=%llu records=%llu deferred=%llu retained_entities=%zu\n",
max_bytes, total / (std::size_t{32} * 40), static_cast<unsigned long long>(stats.chunks),
static_cast<unsigned long long>(stats.records),
static_cast<unsigned long long>(stats.deferred), stats.retained_entities);
}
} // namespace
void replication_tests() {
codec_v2();
convergence_and_deltas();
concealment();
client_robustness();
dense_report();
}
} // namespace evo::network_test