feat(cellular): rules 13 feeding, matter as energy, spent pool and predation
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m29s
Foundation / postgres-tools (push) Successful in 31s
Foundation / server-image (push) Successful in 4m24s
Foundation / image (push) Successful in 5m3s

Phase 2 of the cellular revamp build plan (ADR-0179), server half.

- Matter as energy: when an energy cost exceeds the reserve's energy, reserve
  matter stands in for the rest at each channel's burn rate (pJ per 1,000 fg,
  scaled by the genome's burn efficiency), largest channel first. Upkeep may
  burn any channel; thrust only channels the player has not excluded. Burned
  matter adds no heat; it goes to the region's spent pool. A cell dies only when
  nothing can pay its upkeep.
- Collection: per-channel limits scaled by the genome's collection indices, a
  shared limit on all matter, a tunable cost per membrane point, and only the
  genome's kept share (energy conversion) of bubble energy reaching the reserve.
- Predation: engulf mass carries a tunable share of reserve matter, the
  predator's engulf capacity scales its side and the prey's membrane (now in
  nanometres) its own; kill absorption scales the predator's intake; the kill's
  remainder is split between bubbles at the prey and the spent pool, and a full
  habitat sends overflow to the pool.
- The spent pool is owner format 11 state, counted in conservation, and drips
  back as seeded random bubbles every interval tick.
- Reserve matter is carried as load: slower thrust and turning, costlier thrust.
- Channel exclusions are a 4-bit step intent field, trace byte 14; only owned
  lives under rules 13 may send them.

All values come from the revamp tuning file. Rules up to 12 are unchanged. Tests
cover payments and their conservation over 400 seeds, the rules-13 region step
(collection, membrane, kept energy, burning, engulfment and kill splits with
closure), the drip, load, exclusions, a 700-tick run with closure and exact
restore, and trace replay with exclusions. Session v14 and the client follow
the server phases (build plan). Refreshes the DEV session window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-22 18:35:31 -04:00
co-authored by Claude Opus 5.5
parent c7b4846901
commit 76d21b4815
21 changed files with 1307 additions and 72 deletions
+52
View File
@@ -0,0 +1,52 @@
#pragma once
#include "evo/accounting/ledger.hpp"
#include <array>
#include <compare>
#include <cstdint>
#include <optional>
// Matter as energy (rules 13, ADR-0179; Cellular_feeding_energy_plan.md section 3). When an
// energy cost is larger than the reserve's energy, reserve matter stands in for the rest at
// each channel's burn rate. The matter is not converted: it leaves the cell as spent matter,
// which the region owner keeps in its spent pool. No energy is created, so a cost paid with
// matter adds no heat.
namespace evo::biology {
inline constexpr std::size_t cellular_matter_channels = 4; // C, N, P, other.
struct CellularBurn {
// Picojoules 1,000 fg of each matter channel stands in for, after the cell's burn
// efficiency. Zero means the channel cannot be burned.
std::array<std::uint64_t, cellular_matter_channels> pj_per_kfg{};
// Bit c set: the player keeps channel c (C = bit 0). Upkeep may override it.
std::uint8_t excluded{};
auto operator<=>(const CellularBurn&) const = default;
};
// The burn rates of a cell: each base rate times its burn efficiency index over 100.
[[nodiscard]] CellularBurn
cellular_burn(const std::array<std::uint64_t, cellular_matter_channels>& base_pj_per_kfg,
const std::array<std::uint16_t, cellular_matter_channels>& efficiency,
std::uint8_t excluded) noexcept;
// Energy the reserve could pay: its energy plus what its burnable matter stands in for.
// `override_exclusions` also counts excluded channels (upkeep).
[[nodiscard]] std::uint64_t cellular_payable_energy(const accounting::Inventory& reserve,
const CellularBurn& burn,
bool override_exclusions) noexcept;
// Pays `cost` from `reserve`: its energy first, then matter from the largest burnable channel
// (ties C, N, P, O), the next largest when that runs out. Returns the energy paid and the
// matter spent, and leaves `reserve` debited; nothing changes when the whole cost cannot be
// paid. A channel pays whole femtograms, so matter may cover slightly more than the cost.
struct CellularPayment {
std::uint64_t energy{};
accounting::Inventory spent{}; // Matter only.
auto operator<=>(const CellularPayment&) const = default;
};
[[nodiscard]] std::optional<CellularPayment> cellular_pay(accounting::Inventory& reserve,
std::uint64_t cost,
const CellularBurn& burn,
bool override_exclusions) noexcept;
} // namespace evo::biology
@@ -2,10 +2,12 @@
#include "evo/biology/cellular_step.hpp"
#include <array>
#include <compare>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <optional>
#include <span>
#include <vector>
@@ -16,6 +18,30 @@ inline constexpr std::size_t max_cellular_tick_lives = 256;
// ratio in thousandths per micrometre of prey membrane (tunable; 1.5 for 1 um).
inline constexpr std::uint64_t cellular_engulf_ratio_milli_per_membrane_um = 1'500;
// Rules 13 (ADR-0179; feeding and energy, predation and defense plans): region-declared
// feeding, energy and predation values. All trial values from the revamp tuning file.
struct CellularRevampStepRules {
// Collection changes by this many per mille per membrane point away from the founder's 100
// (thicker collects slower), bounded to 10%-200%.
std::uint32_t membrane_collection_per_mille_per_point{};
// A predator needs engulf mass x capacity / 100 >= prey engulf mass x ratio / 1000 x prey
// membrane points / 100.
std::uint32_t engulf_ratio_milli{1'500};
// Share of reserve matter that counts toward engulf mass, per cent.
std::uint32_t engulf_reserve_percent{100};
// Share of a kill's remainder left as bubbles at the prey; the rest goes to the spent pool.
std::uint32_t kill_bubble_per_thousand{500};
auto operator<=>(const CellularRevampStepRules&) const = default;
};
// Rules 13: one life's heritable feeding, energy and predation values, from its genome.
struct CellularRevampLifeInput {
CellularBurn burn{};
std::array<std::uint16_t, 5> collection{100, 100, 100, 100, 100}; // E, C, N, P, O.
std::uint32_t energy_kept_per_thousand{1'000}; // Of each energy bubble; the rest is heat.
std::uint32_t membrane_nm{1'000};
std::uint16_t engulf_capacity{100}, kill_absorption{100};
auto operator<=>(const CellularRevampLifeInput&) const = default;
};
struct CellularRegionRules {
// Rules 3: engulfment, and every corpse's inventory deposited as patch detritus.
// Rules 2 (false) is the original trial: engulf intents are ignored and starvation
@@ -25,6 +51,8 @@ struct CellularRegionRules {
// its intake rate, with no intake target; pools yield at most a quarter of that rate.
// A dead life's detritus becomes one bubble per non-empty channel.
bool contact_feeding{};
// Rules 13: present exactly when every life carries its revamp input.
std::optional<CellularRevampStepRules> revamp{};
auto operator<=>(const CellularRegionRules&) const = default;
};
@@ -42,6 +70,8 @@ struct CellularLifeStepInput {
// Rules 12: liquid motion, required exactly when the habitat is format 3. The movement
// intent becomes the propulsion command.
std::optional<CellularLiquidInput> liquid{};
// Rules 13 (ADR-0179), required exactly when the region rules declare revamp.
std::optional<CellularRevampLifeInput> revamp{};
auto operator<=>(const CellularLifeStepInput&) const = default;
};
enum class CellularEngulfStatus : std::uint8_t {
@@ -88,6 +118,9 @@ struct CellularRegionStepCandidate {
// Rules 3 detritus patches created at empty cells, sorted by address.
std::vector<CellularPatch> new_patches;
accounting::Picojoules heat_released{};
// Rules 13: everything for the region's spent pool this tick: matter every life burned in
// place of energy (also in its own step candidate) and the spent share of kill remainders.
accounting::Inventory spent{};
auto operator<=>(const CellularRegionStepCandidate&) const = default;
};
enum class CellularRegionStepError : std::uint8_t {
@@ -21,6 +21,18 @@ struct CellularRevampTuning {
std::int64_t version{};
// Body: the share of upkeep no upkeep-efficiency trait reduces.
std::int64_t body_essential_upkeep_per_mille{};
// Body: share of reserve matter carried as load on handling and thrust costs.
std::int64_t body_reserve_load_per_mille{};
// Energy: picojoules 1,000 fg of each matter channel stand in for (burn efficiency 100).
std::int64_t energy_burn_carbon_pj_per_kfg{}, energy_burn_nitrogen_pj_per_kfg{},
energy_burn_phosphorus_pj_per_kfg{}, energy_burn_other_pj_per_kfg{};
// Feeding: per mille of collection lost per membrane point above the founder's 100.
std::int64_t feeding_membrane_collection_per_mille_per_point{};
// Predation.
std::int64_t predation_engulf_ratio_milli{}, predation_engulf_reserve_percent{},
predation_kill_bubble_per_mille{};
// The spent pool's drip back into the region.
std::int64_t spent_drip_interval_ticks{}, spent_drip_bubble_pj{}, spent_drip_bubble_fg{};
auto operator<=>(const CellularRevampTuning&) const = default;
};
+11 -2
View File
@@ -1,5 +1,6 @@
#pragma once
#include "evo/biology/cellular_burn.hpp"
#include "evo/biology/cellular_habitat.hpp"
#include "evo/biology/cellular_kinematics.hpp"
@@ -21,6 +22,9 @@ struct CellularStepIntent {
bool frozen{};
// Rules 12: oppose relative velocity instead of following `movement`.
bool brake{};
// Rules 13 (ADR-0179): matter channels the player keeps from being burned for anything but
// upkeep, bit 0 carbon to bit 3 other matter. Wildlife keeps nothing.
std::uint8_t exclude{};
auto operator<=>(const CellularStepIntent&) const = default;
};
@@ -54,6 +58,9 @@ struct CellularStepCandidate {
// Rules 12 (liquid motion): the motion state after the tick and the path travelled.
CellularMotionState motion{};
std::uint64_t path_um{};
// Rules 13 (ADR-0179): reserve matter burned in place of energy, for the region's spent
// pool. Costs paid this way add no heat.
accounting::Inventory spent{};
auto operator<=>(const CellularStepCandidate&) const = default;
};
// Rules 12: liquid-relative motion inputs for one life (Cellular_Region_Movement_Plan.md).
@@ -72,10 +79,12 @@ propose_cellular_step(std::uint64_t begin_tick, CellularArea area, CellularPosit
const MetabolicBudget& budget, const CellularHabitat& habitat) noexcept;
// Rules 12: maintenance first, then one kinematic tick funded from what is left; thrust it
// cannot fund is not applied and the cell coasts with the flow. No targeted intake: liquid
// regions feed by contact in the region step.
// regions feed by contact in the region step. Rules 13 pass `burn`: reserve matter stands in
// for missing energy, any channel for maintenance and only unexcluded ones for thrust.
[[nodiscard]] std::expected<CellularStepCandidate, CellularStepError>
propose_liquid_cellular_step(std::uint64_t begin_tick, CellularArea area, CellularPosition position,
std::uint32_t extent_um, CellularIntent movement,
const CellularLiquidInput& liquid, accounting::Inventory reserve,
accounting::Inventory heat, const MetabolicBudget& budget) noexcept;
accounting::Inventory heat, const MetabolicBudget& budget,
const CellularBurn* burn = nullptr) noexcept;
} // namespace evo::biology
@@ -1,9 +1,13 @@
#pragma once
#include "evo/biology/cellular_habitat.hpp"
#include "evo/biology/cellular_region_step.hpp"
#include "evo/biology/cellular_revamp_tuning.hpp"
#include "evo/biology/development.hpp"
#include <array>
#include <compare>
#include <cstdint>
// Rules 13 (ADR-0179, Cellular_Revamp_Build_Plan.md): what a cellular owner declares when it
// upgrades to owner format 11. Taken from the Git tuning file when the region opens and
@@ -12,10 +16,36 @@
namespace evo::server {
struct CellularRevampRules {
biology::BodyTuning body{};
// Picojoules 1,000 fg of C, N, P and other matter stand in for at burn efficiency 100.
std::array<std::uint64_t, 4> burn_pj_per_kfg{};
biology::CellularRevampStepRules step{};
// The spent pool drips back as bubbles every `drip_interval_ticks` ticks (0: never), one
// bubble per non-empty channel of at most these amounts, at seeded random spots.
std::uint32_t drip_interval_ticks{};
std::uint64_t drip_bubble_pj{}, drip_bubble_fg{};
// Share of reserve matter carried as load, per mille: it slows thrust and turning and makes
// thrust costlier, in proportion to the body's mass. Upkeep stays on the body.
std::uint32_t reserve_load_per_thousand{};
auto operator<=>(const CellularRevampRules&) const = default;
};
[[nodiscard]] bool cellular_revamp_valid(const CellularRevampRules& rules) noexcept;
// The spent pool's drip for the tick ending at `tick`: on every `drip_interval_ticks`-th tick,
// one bubble per non-empty channel of at most the declared size, taken from `spent`, at a
// seeded random spot (nudged east past taken addresses) with the next deposit id and `source`.
// A habitat at its deposit limit keeps the rest waiting. False only on identity overflow, with
// `config` and `spent` then unusable.
[[nodiscard]] bool cellular_drip_spent(biology::CellularHabitatConfig& config,
accounting::Inventory& spent,
const CellularRevampRules& rules, std::uint64_t world,
std::uint64_t region, std::uint64_t tick,
std::uint64_t source);
// A body's handling carrying reserve matter: thrust, reverse thrust and turning scale by
// body / (body + load), full-output costs by (body + load) / body, where load is the declared
// share of `carried` matter. Drag is unchanged. No load leaves the handling as it is.
[[nodiscard]] biology::CellularHandling
cellular_loaded_handling(const biology::CellularHandling& handling, std::uint64_t body_mass,
std::uint64_t carried, const CellularRevampRules& rules) noexcept;
// Rules from the revamp tuning file.
[[nodiscard]] CellularRevampRules
cellular_revamp_rules(const biology::CellularRevampTuning& tuning);