feat(ecology): record and replay joint environment intervals

ADR-0173 adds joint batch AEVOEBT1: the unchanged population batch plus
each tick's recorded infall import and radiated heat. Unattended recording
applies each tick's exchange before the shared wildlife controller chooses,
so a recorded interval equals the same live joint ticks; replay applies the
same exchange and the recorded intentions and must re-derive every flow.
Forged flows or boundaries, missing ticks, wrong cuts, truncated input and
future formats are refused. Whole-group conversion replays exactly and
cohort intervals record identical biology and flows. A full habitat counts
infall bubbles skipped and imports nothing for them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-19 16:22:05 -04:00
co-authored by Claude Opus 5.5
parent 4c70257883
commit fc6d26d7d6
12 changed files with 555 additions and 4 deletions
@@ -1,6 +1,7 @@
#include "evo/server/lifecycle/cellular_environment.hpp"
#include "evo/core/random.hpp"
#include "evo/server/lifecycle/wildlife_controller.hpp"
#include <algorithm>
#include <limits>
@@ -309,6 +310,62 @@ CellularEnvironment::advance_tick(std::span<const CellularLifeIntent> controlled
return std::move(exchange->report);
}
std::expected<CellularEnvironmentFlow, CellularEnvironmentError>
CellularEnvironment::advance_unattended(std::vector<CellularLifeIntent>& intents, bool record) {
if (tick() == std::numeric_limits<std::uint64_t>::max())
return std::unexpected(CellularEnvironmentError::overflow);
auto exchange = plan_exchange(tick() + 1);
if (!exchange)
return std::unexpected(exchange.error());
auto& lives = *population_->state_;
auto savepoint = lives.exchange_boundary(exchange->deposits, exchange->heat_export);
if (!savepoint)
return std::unexpected(savepoint.error() == CellularLivesError::habitat
? CellularEnvironmentError::habitat
: CellularEnvironmentError::conservation);
biology::CellularStepIntent frozen;
frozen.frozen = true;
if (record) {
auto chosen = wildlife_intents(lives, lives.tick() + 1);
if (!chosen)
return std::unexpected(CellularEnvironmentError::biology);
for (const auto& life : lives.lives())
if (life.account != LifeAccount{})
chosen->push_back({life.identity.life, frozen});
std::ranges::sort(*chosen, {}, &CellularLifeIntent::life_id);
intents = std::move(*chosen);
}
for (const auto& life : lives.lives()) {
if (life.account == LifeAccount{})
continue;
const auto found =
std::ranges::find(intents, life.identity.life, &CellularLifeIntent::life_id);
if (life.presence != CellularPresence::suspended || found == intents.end() ||
found->intent != frozen)
return std::unexpected(CellularEnvironmentError::unsupported);
}
if (!lives.advance_tick(intents))
return std::unexpected(CellularEnvironmentError::biology);
auto& members = population_->members_;
std::erase_if(members, [&lives](const auto& member) {
return std::ranges::find(lives.lives(), member.life, [](const auto& life) {
return life.identity.life;
}) == lives.lives().end();
});
// The persisted policy's exact result; no random materialization or resampling.
if (population_->policy_.automatic) {
if (population_->conversion_sequence_ == std::numeric_limits<std::uint64_t>::max())
return std::unexpected(CellularEnvironmentError::overflow);
population_->apply_policy();
}
progress_ = std::move(exchange->progress);
exported_.value += exchange->heat_export.value;
return CellularEnvironmentFlow{exchange->report.imported, exchange->heat_export};
}
CellularPopulationBoundary CellularEnvironment::population_boundary() const {
return {population_->conversion_sequence_, population_->members_};
}
std::expected<std::size_t, CellularEnvironmentError>
CellularEnvironment::collapse(std::uint64_t genome) {
const auto converted = population_->collapse(genome);
@@ -0,0 +1,190 @@
#include "evo/server/lifecycle/cellular_environment.hpp"
#include <algorithm>
#include <utility>
namespace evo::server {
namespace {
constexpr std::uint64_t magic = 0x315442454F564541ULL; // "AEVOEBT1"
void put(std::vector<std::uint8_t>& out, std::uint64_t value, unsigned width = 8) {
for (unsigned i = 0; i < width; ++i) {
out.push_back(static_cast<std::uint8_t>(value & 255U));
value >>= 8U;
}
}
std::uint64_t get(std::span<const std::uint8_t> bytes, std::size_t at, unsigned width) {
std::uint64_t value = 0;
for (unsigned i = 0; i < width; ++i)
value |= std::uint64_t{bytes[at + i]} << (8U * i);
return value;
}
// The nested population batch must already be canonical for its own format.
bool shape(const CellularEnvironmentBatch& batch) {
const auto& population = batch.population;
if (population.format_version != 2 &&
population.format_version != cellular_population_inheritance_format)
return false;
const auto ticks = population.conversion ? std::size_t{0} : population.biology.ticks.size();
return batch.flows.size() == ticks && encode_population_batch(population).has_value();
}
} // namespace
std::expected<std::unique_ptr<CellularEnvironment>, CellularEnvironmentError>
execute_environment_batch(const CellularEnvironment& base, CellularEnvironmentBatch& batch,
bool record) {
auto& population = batch.population;
const auto& state = base.state();
if (population.format_version != base.population().format_version())
return std::unexpected(CellularEnvironmentError::unsupported);
const auto& h = population.header;
if (h.world != state.world() || h.region != state.region() || h.frame != state.frame() ||
h.begin_tick != state.tick())
return std::unexpected(CellularEnvironmentError::identity);
if (!record && !shape(batch))
return std::unexpected(CellularEnvironmentError::format);
if (!population.conversion && !population_interval_safe(state))
return std::unexpected(CellularEnvironmentError::unsupported);
auto candidate = CellularEnvironment::restore(base.snapshot(), state.world(), state.region(),
state.frame(), state.tick());
if (!candidate)
return std::unexpected(candidate.error());
auto& joint = **candidate;
if (record) {
population.boundaries.clear();
batch.flows.clear();
}
const auto boundary = [&](std::size_t index) {
auto actual = joint.population_boundary();
if (record) {
population.boundaries.push_back(std::move(actual));
return true;
}
return population.boundaries[index] == actual;
};
if (population.conversion) {
const auto converted = population.conversion->to_cohort
? joint.collapse(population.conversion->genome)
: joint.materialize(population.conversion->genome);
if (!converted || !boundary(0))
return std::unexpected(CellularEnvironmentError::biology);
} else {
const auto count = record ? h.end_tick - h.begin_tick : population.biology.ticks.size();
if (record) {
population.biology.header = h;
population.biology.ticks.clear();
population.biology.format_version =
state.rules_version() == cellular_lives_inheritance_rules
? cellular_batch_inheritance_format
: cellular_batch_format;
}
for (std::size_t index = 0; index < count; ++index) {
std::vector<CellularLifeIntent> intents;
if (!record)
intents = population.biology.ticks[index].lives;
const auto flow = joint.advance_unattended(intents, record);
if (!flow)
return std::unexpected(flow.error());
if (record) {
population.biology.ticks.push_back({std::move(intents), {}, {}});
batch.flows.push_back(*flow);
} else if (batch.flows[index] != *flow) {
return std::unexpected(CellularEnvironmentError::conservation);
}
if (!boundary(index))
return std::unexpected(CellularEnvironmentError::biology);
}
}
if (record && !shape(batch))
return std::unexpected(CellularEnvironmentError::format);
return candidate;
}
std::expected<CellularEnvironmentExecution, CellularEnvironmentError>
prepare_environment_interval(const CellularEnvironment& base, const CellularBatchHeader& header) {
if (header.end_tick <= header.begin_tick ||
header.end_tick - header.begin_tick > max_cellular_batch_ticks)
return std::unexpected(CellularEnvironmentError::identity);
CellularEnvironmentBatch batch;
batch.population.header = header;
batch.population.format_version = base.population().format_version();
auto state = execute_environment_batch(base, batch, true);
if (!state)
return std::unexpected(state.error());
return CellularEnvironmentExecution{std::move(batch), std::move(*state)};
}
std::expected<CellularEnvironmentExecution, CellularEnvironmentError>
prepare_environment_conversion(const CellularEnvironment& base, CellularBatchHeader header,
CellularPopulationConversion conversion) {
CellularEnvironmentBatch batch;
batch.population = {header, {}, conversion, {}};
batch.population.format_version = base.population().format_version();
auto state = execute_environment_batch(base, batch, true);
if (!state)
return std::unexpected(state.error());
return CellularEnvironmentExecution{std::move(batch), std::move(*state)};
}
std::expected<std::unique_ptr<CellularEnvironment>, CellularEnvironmentError>
replay_environment_batch(const CellularEnvironment& base, const CellularEnvironmentBatch& batch) {
auto copy = batch;
return execute_environment_batch(base, copy, false);
}
std::expected<std::vector<std::uint8_t>, CellularEnvironmentError>
encode_environment_batch(const CellularEnvironmentBatch& batch) {
if (!shape(batch))
return std::unexpected(CellularEnvironmentError::format);
const auto nested = encode_population_batch(batch.population);
if (!nested)
return std::unexpected(CellularEnvironmentError::format);
std::vector<std::uint8_t> out;
put(out, magic);
put(out, cellular_environment_batch_format, 4);
put(out, batch.population.conversion ? 1 : 0, 4);
put(out, nested->size());
put(out, batch.flows.size(), 4);
put(out, 0, 4);
out.insert(out.end(), nested->begin(), nested->end());
for (const auto& flow : batch.flows) {
put(out, flow.imported.energy.value);
for (const auto& channel : flow.imported.matter)
put(out, channel.value);
put(out, flow.exported.value);
}
return out;
}
std::expected<CellularEnvironmentBatch, CellularEnvironmentError>
decode_environment_batch(std::span<const std::uint8_t> bytes) {
if (bytes.size() < environment_batch_header_bytes || bytes.size() > max_environment_batch_bytes)
return std::unexpected(CellularEnvironmentError::format);
if (get(bytes, 0, 8) != magic)
return std::unexpected(CellularEnvironmentError::format);
if (get(bytes, 8, 4) != cellular_environment_batch_format)
return std::unexpected(CellularEnvironmentError::unsupported);
const auto kind = get(bytes, 12, 4), nested = get(bytes, 16, 8), flows = get(bytes, 24, 4);
if (kind > 1 || get(bytes, 28, 4) != 0 || nested > max_population_batch_bytes ||
flows > max_cellular_batch_ticks ||
bytes.size() != environment_batch_header_bytes + nested + flows * environment_flow_bytes)
return std::unexpected(CellularEnvironmentError::format);
auto population = decode_population_batch(
bytes.subspan(environment_batch_header_bytes, static_cast<std::size_t>(nested)));
if (!population || population->conversion.has_value() != (kind == 1))
return std::unexpected(CellularEnvironmentError::format);
CellularEnvironmentBatch batch{std::move(*population), {}};
auto at = environment_batch_header_bytes + static_cast<std::size_t>(nested);
for (std::uint64_t index = 0; index < flows; ++index) {
CellularEnvironmentFlow flow;
flow.imported.energy.value = get(bytes, at, 8);
for (std::size_t channel = 0; channel < flow.imported.matter.size(); ++channel)
flow.imported.matter[channel].value = get(bytes, at + 8 + 8 * channel, 8);
flow.exported.value = get(bytes, at + 40, 8);
at += environment_flow_bytes;
batch.flows.push_back(flow);
}
const auto canonical = encode_environment_batch(batch);
if (!canonical || !std::ranges::equal(*canonical, bytes))
return std::unexpected(CellularEnvironmentError::format);
return batch;
}
} // namespace evo::server