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,6 @@
#pragma once
#include "evo/server/lifecycle/cellular_population.hpp"
#include "evo/server/lifecycle/cellular_population_batch.hpp"
#include "evo/world/coordinates.hpp"
#include "evo/world/environment_units.hpp"
@@ -87,6 +87,14 @@ enum class CellularEnvironmentError : std::uint8_t {
checksum
};
// ADR-0173: one tick's recorded environmental crossing. Replay re-derives it from
// configuration, tick and seed and must reproduce it exactly; it is evidence, not input.
struct CellularEnvironmentFlow {
accounting::Inventory imported{};
accounting::Picojoules exported{};
bool operator==(const CellularEnvironmentFlow&) const = default;
};
struct CellularEnvironmentBatch;
class CellularEnvironment {
public:
// Consumes the population on success or failure.
@@ -128,14 +136,54 @@ class CellularEnvironment {
std::uint64_t frame, std::uint64_t tick);
private:
friend std::expected<std::unique_ptr<CellularEnvironment>, CellularEnvironmentError>
execute_environment_batch(const CellularEnvironment&, CellularEnvironmentBatch&, bool record);
struct Exchange;
CellularEnvironment(std::unique_ptr<CellularPopulation> population,
CellularEnvironmentConfig config);
[[nodiscard]] std::expected<Exchange, CellularEnvironmentError>
plan_exchange(std::uint64_t tick) const;
// One unattended joint tick on a detached candidate: the exchange, then frozen
// controlled intentions with either the recorded wildlife intentions (replay) or
// the shared controller's choice on the exchanged state (recording, `intents` empty).
[[nodiscard]] std::expected<CellularEnvironmentFlow, CellularEnvironmentError>
advance_unattended(std::vector<CellularLifeIntent>& intents, bool record);
[[nodiscard]] CellularPopulationBoundary population_boundary() const;
std::unique_ptr<CellularPopulation> population_;
CellularEnvironmentConfig config_;
std::vector<CellularInfallProgress> progress_; // Source order.
accounting::Picojoules exported_{};
};
// Joint batch 1: the unchanged population batch (interval or whole-group conversion)
// plus one flow per biological tick. Conversions carry no flows.
struct CellularEnvironmentBatch {
CellularPopulationBatch population;
std::vector<CellularEnvironmentFlow> flows;
bool operator==(const CellularEnvironmentBatch&) const = default;
};
inline constexpr std::uint32_t cellular_environment_batch_format = 1;
inline constexpr std::size_t environment_batch_header_bytes = 32;
inline constexpr std::size_t environment_flow_bytes = 48;
inline constexpr std::size_t max_environment_batch_bytes =
environment_batch_header_bytes + max_population_batch_bytes +
environment_flow_bytes * max_cellular_batch_ticks;
struct CellularEnvironmentExecution {
CellularEnvironmentBatch batch;
std::unique_ptr<CellularEnvironment> state;
};
// An unattended interval: every controlled cell must be fully suspended. Each tick
// applies its exchange, then the unchanged wildlife controller chooses on that state;
// the recorded intentions replay without rerunning the controller.
[[nodiscard]] std::expected<CellularEnvironmentExecution, CellularEnvironmentError>
prepare_environment_interval(const CellularEnvironment& base, const CellularBatchHeader& header);
[[nodiscard]] std::expected<CellularEnvironmentExecution, CellularEnvironmentError>
prepare_environment_conversion(const CellularEnvironment& base, CellularBatchHeader header,
CellularPopulationConversion conversion);
[[nodiscard]] std::expected<std::unique_ptr<CellularEnvironment>, CellularEnvironmentError>
replay_environment_batch(const CellularEnvironment& base, const CellularEnvironmentBatch& batch);
[[nodiscard]] std::expected<std::vector<std::uint8_t>, CellularEnvironmentError>
encode_environment_batch(const CellularEnvironmentBatch& batch);
[[nodiscard]] std::expected<CellularEnvironmentBatch, CellularEnvironmentError>
decode_environment_batch(std::span<const std::uint8_t> bytes);
} // namespace evo::server