#pragma once #include "evo/server/lifecycle/cellular_population_batch.hpp" #include "evo/world/coordinates.hpp" #include "evo/world/environment_units.hpp" #include #include #include #include #include #include #include #include namespace evo::server { // ADR-0172: one owner of a region's cells and their local environment. inline constexpr std::uint32_t cellular_environment_format = 1; inline constexpr std::uint32_t cellular_environment_rules = 1; inline constexpr std::size_t max_cellular_infall_sources = 4; // Trial values (ADR-0136 step B): two simulated minutes between events on average, // 12-24 bubbles per event, dropped within a 1 mm disc. inline constexpr std::uint64_t cellular_infall_trial_interval_ticks = 2'400; inline constexpr std::uint32_t cellular_infall_trial_bubbles_min = 12; inline constexpr std::uint32_t cellular_infall_trial_bubbles_max = 24; inline constexpr std::uint32_t cellular_infall_clump_radius_um = 500; inline constexpr std::uint32_t max_cellular_infall_bubbles = 64; inline constexpr std::size_t cellular_environment_header_bytes = 176; inline constexpr std::size_t cellular_infall_source_bytes = 208; inline constexpr std::size_t max_cellular_environment_bytes = cellular_environment_header_bytes + cellular_infall_source_bytes * max_cellular_infall_sources + max_cellular_population_bytes + 8; // One axis-aligned habitat inside one environmental voxel. Its width and height // equal the cellular area; depth only defines a sampling volume, never stock. struct CellularEnvironmentGeometry { world::VoxelAddress voxel{}; world::HabitatBox box{}; }; // Tagged, inedible compartments. No rules-1 process converts them. struct CellularWaterColumn { accounting::Femtograms water{}, dissolved_nitrogen{}, dissolved_phosphorus{}; auto operator<=>(const CellularWaterColumn&) const = default; }; // An audited external import over a declared rectangle and half-open tick interval. // The entitlement is finite; what remains is entitlement minus imported. struct CellularInfallSource { std::uint64_t id{}; std::uint32_t x_um{}, y_um{}, width_um{}, height_um{}; std::uint64_t start_tick{}, end_tick{}; std::uint64_t mean_interval_ticks{cellular_infall_trial_interval_ticks}; std::uint32_t bubbles_min{cellular_infall_trial_bubbles_min}; std::uint32_t bubbles_max{cellular_infall_trial_bubbles_max}; accounting::Inventory per_bubble{}; // Single-channel bubbles cycle stocked channels. accounting::Inventory entitlement{}; // Cumulative import limit, per channel. auto operator<=>(const CellularInfallSource&) const = default; }; struct CellularInfallProgress { accounting::Inventory imported{}; std::uint64_t events{}, credited_bubbles{}, skipped_bubbles{}, exhausted_events{}; auto operator<=>(const CellularInfallProgress&) const = default; }; struct CellularEnvironmentConfig { CellularEnvironmentGeometry geometry{}; CellularWaterColumn water{}; std::vector sources; // Sorted unique ids, disjoint rectangles. accounting::Picojoules radiation_cap{}; // Heat exported per tick; zero is closed. std::uint32_t atmosphere_species{}; // Any declared species is unsupported. }; struct CellularEnvironmentTickReport { std::uint64_t tick{}; accounting::Inventory imported{}; // Infall only; a rules-11 owner books its own light. accounting::Picojoules exported{}; std::uint64_t events{}, credited_bubbles{}, skipped_bubbles{}; CellularTickExecution biology; }; enum class CellularEnvironmentError : std::uint8_t { unsupported, invalid_geometry, invalid_source, identity, habitat, biology, overflow, conservation, format, 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. [[nodiscard]] static std::expected, CellularEnvironmentError> create(std::unique_ptr population, CellularEnvironmentConfig config); CellularEnvironment(const CellularEnvironment&) = delete; CellularEnvironment& operator=(const CellularEnvironment&) = delete; ~CellularEnvironment(); // Read-only views; they confer no separate spending rights. [[nodiscard]] const CellularPopulation& population() const noexcept; [[nodiscard]] const CellularLives& state() const noexcept; [[nodiscard]] const CellularEnvironmentGeometry& geometry() const noexcept; [[nodiscard]] world::HabitatMeasure measure() const noexcept; [[nodiscard]] const CellularWaterColumn& water() const noexcept; [[nodiscard]] std::span sources() const noexcept; [[nodiscard]] std::span infall() const noexcept; [[nodiscard]] accounting::Picojoules radiation_cap() const noexcept; [[nodiscard]] accounting::Inventory imported() const noexcept; // Infall, cumulative. [[nodiscard]] accounting::Picojoules exported() const noexcept; [[nodiscard]] std::uint64_t tick() const noexcept; // One joint 50 ms tick: the environmental exchange, then the unchanged population // tick. Any refusal leaves the whole owner byte-for-byte unchanged. [[nodiscard]] std::expected advance_tick(std::span controlled, std::span selections = {}); // Explicit representation changes of the nested population; no tick advances. [[nodiscard]] std::expected collapse(std::uint64_t genome); [[nodiscard]] std::expected materialize(std::uint64_t genome); [[nodiscard]] std::vector snapshot() const; [[nodiscard]] static std::expected, CellularEnvironmentError> restore(std::span bytes, std::uint64_t world, std::uint64_t region, std::uint64_t frame, std::uint64_t tick); private: friend std::expected, CellularEnvironmentError> execute_environment_batch(const CellularEnvironment&, CellularEnvironmentBatch&, bool record); struct Exchange; struct Step { CellularEnvironmentTickReport report; }; enum class StepMode : std::uint8_t { live, record, replay }; [[nodiscard]] std::expected joint_step(std::vector& intents, std::span selections, StepMode mode); CellularEnvironment(std::unique_ptr population, CellularEnvironmentConfig config); [[nodiscard]] std::expected 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 advance_unattended(std::vector& intents, bool record); [[nodiscard]] CellularPopulationBoundary population_boundary() const; std::unique_ptr population_; CellularEnvironmentConfig config_; std::vector 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 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 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 prepare_environment_interval(const CellularEnvironment& base, const CellularBatchHeader& header); [[nodiscard]] std::expected prepare_environment_conversion(const CellularEnvironment& base, CellularBatchHeader header, CellularPopulationConversion conversion); [[nodiscard]] std::expected, CellularEnvironmentError> replay_environment_batch(const CellularEnvironment& base, const CellularEnvironmentBatch& batch); [[nodiscard]] std::expected, CellularEnvironmentError> encode_environment_batch(const CellularEnvironmentBatch& batch); [[nodiscard]] std::expected decode_environment_batch(std::span bytes); } // namespace evo::server