From 1ccc0ce47695de614adbe7a9c7ac67db0447561f Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 21:24:39 -0400 Subject: [PATCH] Compose single-life cellular tick proposals --- CMakeLists.txt | 7 +- .../0104-cellular-single-life-tick-order.md | 59 +++++++++ docs/adr/README.md | 1 + docs/engineering/M11_3_DELIVERY_PLAN.md | 4 + docs/engineering/VALIDATION.md | 17 +++ include/evo/biology/cellular_step.hpp | 43 ++++++ src/biology/cellular_step.cpp | 81 ++++++++++++ tests/cellular_step_tests.cpp | 122 ++++++++++++++++++ 8 files changed, 333 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0104-cellular-single-life-tick-order.md create mode 100644 include/evo/biology/cellular_step.hpp create mode 100644 src/biology/cellular_step.cpp create mode 100644 tests/cellular_step_tests.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 656b224..8e917db 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -70,7 +70,7 @@ add_library(evo_biology STATIC src/biology/genome.cpp src/biology/development.cpp src/biology/metabolism.cpp src/biology/mutation.cpp src/biology/lineage.cpp src/biology/founder.cpp src/biology/cellular_motion.cpp src/biology/cellular_uptake.cpp - src/biology/cellular_habitat.cpp) + src/biology/cellular_habitat.cpp src/biology/cellular_step.cpp) add_library(evo::biology ALIAS evo_biology) target_include_directories(evo_biology PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") target_link_libraries(evo_biology PUBLIC evo::accounting) @@ -440,6 +440,11 @@ if(BUILD_TESTING) evo_owned_target(evo-cellular-habitat-tests) add_test(NAME cellular-habitat-contracts COMMAND evo-cellular-habitat-tests) set_tests_properties(cellular-habitat-contracts PROPERTIES TIMEOUT 60) + add_executable(evo-cellular-step-tests tests/cellular_step_tests.cpp) + target_link_libraries(evo-cellular-step-tests PRIVATE evo::biology) + evo_owned_target(evo-cellular-step-tests) + add_test(NAME cellular-step-contracts COMMAND evo-cellular-step-tests) + set_tests_properties(cellular-step-contracts PROPERTIES TIMEOUT 60) add_executable(evo-primitive-lives-tests tests/primitive_lives_tests.cpp) target_link_libraries(evo-primitive-lives-tests PRIVATE evo::lifecycle) evo_owned_target(evo-primitive-lives-tests) diff --git a/docs/adr/0104-cellular-single-life-tick-order.md b/docs/adr/0104-cellular-single-life-tick-order.md new file mode 100644 index 0000000..d9688b3 --- /dev/null +++ b/docs/adr/0104-cellular-single-life-tick-order.md @@ -0,0 +1,59 @@ +# ADR-0104: Cellular single-life tick order trial + +## Status + +Accepted direction for the M11.3 exploratory slice (2026-10-10). This orders a +single-life proposal only; the region transaction must resolve shared patch +claims and durable actions before the rule is used for multiple organisms. + +## Context + +ADR-0098 selects phenotype-derived maintenance, movement and intake with +movement and engulf intentions. ADR-0099 defines rate conversion at the fixed +50 ms tick boundary. ADR-0101 and ADR-0102 supply finite resources, bounded +movement and footprint contact. These independent proposals need an explicit +order so energy acquired during a tick cannot retroactively fund actions earlier +in that tick. + +## Decision + +For the first one-life cellular trial step, the authoritative resolver produces +one detached candidate in this order: + +1. Charge one tick of maintenance from the starting reserve to heat, rounded up. + If it cannot be paid, return `insufficient_maintenance`; the later life/death + owner must resolve starvation in this same tick before publication. +2. Resolve bounded movement from the post-maintenance reserve. If the move is + unaffordable, the organism remains in place and the tick continues; it cannot + spend resources it will acquire later in the tick. Paid movement energy goes + to heat. +3. If an intake target was supplied, validate its patch exists and the resulting + footprint contacts it. A missing or out-of-contact target is reported without + intake, while the already-proposed maintenance and movement remain in the + candidate. A valid target receives the one-tick channel-limited transfer. +4. Publish position, reserve, heat, patch stock and tick together. Every resource + channel is conserved. This resolver does not grow the body, replenish patches, + resolve a second life's claim, or commit state itself. + +An intake in this trial addresses one provisioned patch per life per tick. The +perception projection is the only intended way for a client to learn target +addresses; the server still validates range at view creation and contact at +resolution. Later multi-life resolution must arbitrate all claims against one +shared candidate habitat before invoking or replacing this single-life helper. + +## Alternatives considered + +- **Intake before movement:** rejected because newly absorbed energy could fund + movement in the same tick, making costs depend on action ordering. +- **Refuse the whole tick when movement is underfunded:** rejected because a + cell may still maintain itself and feed while stationary. +- **Silently skip unaffordable maintenance:** rejected because it would allow a + nonviable cell to remain active without paying upkeep. + +## Consequences + +The pure biology resolver composes rate conversion, movement affordability, +heat transfer and one contact-gated patch intake into a detached value. It is +not yet connected to life ownership, shared-stock contention, the cellular +checkpoint, network intentions or durable outcomes. Those integrations are +required before the exploratory hands-on probe. diff --git a/docs/adr/README.md b/docs/adr/README.md index 4d9e388..e7885d3 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -4,6 +4,7 @@ - [ADR-0101: Cellular microhabitat resource sites](0101-cellular-microhabitat-resources.md) - accepted M11.3 direction for finite, conserved sub-voxel food patches; 1 mm pitch is a versioned exploratory tunable, with no meter-scale coupling yet. - [ADR-0102: Bounded cellular space and locomotion trial](0102-cellular-spatial-trial.md) - accepted M11.3 trial direction for finite 2D region bounds, phenotype-limited movement and organism contact; tunable arena dimensions are not world geometry. - [ADR-0103: Cellular resource perception trial](0103-cellular-perception-trial.md) - accepted M11.3 exploratory direction for a 5 mm footprint-based sensor range and exact nearby patch stock; provenance and out-of-range stock remain hidden. +- [ADR-0104: Cellular single-life tick order trial](0104-cellular-single-life-tick-order.md) - accepted M11.3 order for maintenance, funded movement and one contact-gated intake proposal; shared-stock contention and durable publication remain open. - [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows. diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index 2f59448..3fe84cb 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -123,6 +123,10 @@ scoped change before starting the next segment. - 11.3b-2: funded motion now returns one detached position/reserve/heat candidate and refuses underfunded or overflowing movement without partial debit. Live intent admission, tick publication and recovery remain open. +- 11.3c-3: ADR-0104 and a single-life tick resolver compose maintenance, + affordable movement and one targeted contact intake into a detached candidate. + Shared-stock contention, starvation/death closure, owner commit and checkpoint + recovery remain open; this helper is not yet a multi-life tick. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 2adb698..9da037c 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -5888,6 +5888,23 @@ dry-run; clang-tidy 19.1.5 using the MSVC `/std:c++latest` argument; and the full CI suite remain pending CI. This projection is not yet wired into live replication or a persistent cellular checkpoint. +## 2026-10-10 — M11.3c-3 single-life cellular tick (CI pending) + +Added ADR-0104 and a pure one-life tick candidate. It debits per-tick +maintenance first, attempts movement only from the remaining starting reserve, +and applies one explicitly targeted intake only after movement and contact +validation. An unaffordable move leaves the cell still while maintenance and +valid intake remain in the candidate; unaffordable maintenance refuses the +candidate for same-tick starvation resolution by the later life owner. The +returned balances conserve energy and each matter channel. No owner, shared-stock +arbitration, death closure or durable publication has been integrated. + +Executed locally: warning-as-error MSVC 19.44 Debug and Release `NDEBUG` +compile/run; focused CTest for motion, uptake, habitat and the composed tick +(4/4 passed); clang-format 19.1.5 dry-run; clang-tidy 19.1.5 using MSVC +`/std:c++latest`; and `git diff --check`. Linux sanitizers, shared-life +contention and server/checkpoint integration remain pending CI and later gates. + ## 2026-10-10 — M11.3c-2 contact-gated patch uptake (CI pending) The habitat uptake proposal now validates the cell footprint against the finite diff --git a/include/evo/biology/cellular_step.hpp b/include/evo/biology/cellular_step.hpp new file mode 100644 index 0000000..74b6414 --- /dev/null +++ b/include/evo/biology/cellular_step.hpp @@ -0,0 +1,43 @@ +#pragma once + +#include "evo/biology/cellular_habitat.hpp" + +#include +#include + +namespace evo::biology { +struct CellularStepIntent { + CellularIntent movement{}; + std::optional intake_target; + auto operator<=>(const CellularStepIntent&) const = default; +}; + +enum class CellularStepError : std::uint8_t { + invalid_tick, + unsupported_rate_period, + insufficient_maintenance, + overflow, + motion +}; +enum class CellularIntakeStatus : std::uint8_t { not_requested, acquired, missing, out_of_contact }; + +// Complete detached candidate for one 50 ms life tick. Maintenance is charged +// first; unaffordable motion leaves the cell stationary, then one targeted patch +// may be absorbed at the resulting position. Publication owns the final swap. +struct CellularStepCandidate { + std::uint64_t begin_tick{}, end_tick{}; + CellularPosition position; + accounting::Inventory reserve_after; + accounting::Inventory heat_after; + accounting::Picojoules maintenance_cost{}, movement_cost{}; + CellularIntakeStatus intake_status{CellularIntakeStatus::not_requested}; + std::optional intake; + auto operator<=>(const CellularStepCandidate&) const = default; +}; + +[[nodiscard]] std::expected +propose_cellular_step(std::uint64_t begin_tick, CellularArea area, CellularPosition position, + std::uint32_t extent_um, CellularStepIntent intent, + accounting::Inventory reserve, accounting::Inventory heat, + const MetabolicBudget& budget, const CellularHabitat& habitat) noexcept; +} // namespace evo::biology diff --git a/src/biology/cellular_step.cpp b/src/biology/cellular_step.cpp new file mode 100644 index 0000000..68e955b --- /dev/null +++ b/src/biology/cellular_step.cpp @@ -0,0 +1,81 @@ +#include "evo/biology/cellular_step.hpp" + +#include "evo/accounting/rates.hpp" +#include "evo/biology/cellular_motion.hpp" + +#include + +namespace evo::biology { +namespace { +constexpr std::uint64_t rate_period_microseconds = 1'000'000; + +bool credit_heat(accounting::Inventory& heat, std::uint64_t amount) noexcept { + if (heat.energy.value > std::numeric_limits::max() - amount) + return false; + heat.energy.value += amount; + return true; +} +} // namespace + +std::expected +propose_cellular_step(std::uint64_t begin_tick, CellularArea area, CellularPosition position, + std::uint32_t extent_um, CellularStepIntent intent, + accounting::Inventory reserve, accounting::Inventory heat, + const MetabolicBudget& budget, const CellularHabitat& habitat) noexcept { + if (begin_tick == std::numeric_limits::max()) + return std::unexpected{CellularStepError::invalid_tick}; + if (budget.rate_microseconds != rate_period_microseconds) + return std::unexpected{CellularStepError::unsupported_rate_period}; + if (area.width_um != habitat.config().width_um || area.height_um != habitat.config().height_um) + return std::unexpected{CellularStepError::motion}; + + const auto maintenance = accounting::per_tick( + budget.maintenance.value, cellular_motion_tick_microseconds, accounting::Rounding::up); + if (!maintenance) + return std::unexpected{CellularStepError::overflow}; + if (reserve.energy.value < *maintenance) + return std::unexpected{CellularStepError::insufficient_maintenance}; + if (!credit_heat(heat, *maintenance)) + return std::unexpected{CellularStepError::overflow}; + reserve.energy.value -= *maintenance; + + const auto movement = propose_funded_cellular_motion(area, position, extent_um, intent.movement, + budget, reserve, heat); + if (!movement && movement.error() != CellularMotionError::insufficient_reserve) + return std::unexpected{CellularStepError::motion}; + if (movement) { + position = movement->position; + reserve = movement->reserve_after; + heat = movement->heat_after; + } + + CellularStepCandidate candidate{ + begin_tick, begin_tick + 1, position, reserve, + heat, {*maintenance}, {}, CellularIntakeStatus::not_requested, + {}}; + if (movement) + candidate.movement_cost = movement->movement_cost; + if (!intent.intake_target) + return candidate; + + const auto intake = + habitat.propose_uptake(*intent.intake_target, position, extent_um, reserve, budget); + if (!intake) { + if (intake.error() == CellularHabitatError::missing_patch) { + candidate.intake_status = CellularIntakeStatus::missing; + return candidate; + } + if (intake.error() == CellularHabitatError::not_in_contact) { + candidate.intake_status = CellularIntakeStatus::out_of_contact; + return candidate; + } + return std::unexpected{intake.error() == CellularHabitatError::uptake + ? CellularStepError::overflow + : CellularStepError::motion}; + } + candidate.reserve_after = intake->transfer.reserve_after; + candidate.intake_status = CellularIntakeStatus::acquired; + candidate.intake = *intake; + return candidate; +} +} // namespace evo::biology diff --git a/tests/cellular_step_tests.cpp b/tests/cellular_step_tests.cpp new file mode 100644 index 0000000..6c2443e --- /dev/null +++ b/tests/cellular_step_tests.cpp @@ -0,0 +1,122 @@ +#include "evo/biology/cellular_step.hpp" + +#include +#include +#include +#include +#include + +namespace { +using namespace evo::biology; +using evo::accounting::Inventory; +void check(bool value, std::source_location at = std::source_location::current()) { + if (!value) + throw std::runtime_error("cellular step line " + std::to_string(at.line())); +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) + +MetabolicBudget budget() { + MetabolicBudget result{}; + result.phenotype.movement_speed = 200; + result.maintenance = {100}; + result.movement = {1'000}; + result.intake_limit = {{1'000}, {{{100}, {50}, {25}, {10}}}}; + result.rate_microseconds = 1'000'000; + return result; +} + +std::unique_ptr habitat() { + CellularHabitatConfig opening{ + 7, 9, 11, 3'000, 2'000, {{{0, 0}, 51, {{1'000}, {{{20}, {10}, {5}, {2}}}}}}}; + auto made = CellularHabitat::create(std::move(opening)); + CHECK(made); + return std::move(*made); +} + +void maintenance_motion_and_intake_conserve_one_tick() { + const Inventory reserve{{200}, {}}; + const Inventory heat{}; + const auto map = habitat(); + const auto step = propose_cellular_step(12, {3'000, 2'000}, {0, 0}, 20, + {{1'000, 0}, CellularPatchAddress{0, 0}}, reserve, heat, + budget(), *map); + if (!step) + throw std::runtime_error("cellular step failed"); + CHECK(step->begin_tick == 12 && step->end_tick == 13); + CHECK(step->position == CellularPosition{10, 0}); + CHECK(step->maintenance_cost.value == 5 && step->movement_cost.value == 50); + CHECK(step->heat_after.energy.value == 55); + CHECK(step->reserve_after == Inventory{{195}, {{{5}, {2}, {1}, {0}}}}); + if (step->intake_status != CellularIntakeStatus::acquired || !step->intake) + throw std::runtime_error("cellular step intake missing"); + const auto& intake = *step->intake; + CHECK(intake.transfer.patch_after == Inventory{{950}, {{{15}, {8}, {4}, {2}}}}); + CHECK(reserve.energy.value == 200 && heat.energy.value == 0); + CHECK(map->patches()[0].stock == Inventory{{1'000}, {{{20}, {10}, {5}, {2}}}}); + + const auto& acquired = intake.transfer.acquired; + CHECK(step->reserve_after.energy.value + step->heat_after.energy.value + + intake.transfer.patch_after.energy.value == + reserve.energy.value + heat.energy.value + map->patches()[0].stock.energy.value); + for (std::size_t channel = 0; channel < acquired.matter.size(); ++channel) + CHECK(step->reserve_after.matter[channel].value + + intake.transfer.patch_after.matter[channel].value == + reserve.matter[channel].value + map->patches()[0].stock.matter[channel].value); +} + +void maintenance_precedes_motion_and_intake() { + const auto map = habitat(); + Inventory low_reserve{{54}, {}}; + const auto step = propose_cellular_step(1, {3'000, 2'000}, {0, 0}, 20, + {{1'000, 0}, CellularPatchAddress{0, 0}}, low_reserve, + {}, budget(), *map); + CHECK(step); + CHECK(step->position == CellularPosition{0, 0}); + CHECK(step->movement_cost.value == 0); + CHECK(step->maintenance_cost.value == 5 && step->heat_after.energy.value == 5); + CHECK(step->intake_status == CellularIntakeStatus::acquired); + CHECK(step->reserve_after.energy.value == 99); // Intake cannot fund this tick's move. + + low_reserve.energy.value = 4; + const auto starved = + propose_cellular_step(1, {3'000, 2'000}, {0, 0}, 20, {{}, CellularPatchAddress{0, 0}}, + low_reserve, {}, budget(), *map); + CHECK(!starved && starved.error() == CellularStepError::insufficient_maintenance); +} + +void refusals_and_noncontact_are_explicit() { + const auto map = habitat(); + const auto missed = + propose_cellular_step(4, {3'000, 2'000}, {1'500, 0}, 20, {{}, CellularPatchAddress{0, 0}}, + {{100}, {}}, {}, budget(), *map); + CHECK(missed && missed->intake_status == CellularIntakeStatus::out_of_contact); + CHECK(missed->position == CellularPosition{1'500, 0}); + CHECK(missed->reserve_after.energy.value == 95); + CHECK(!missed->intake); + + const auto absent = + propose_cellular_step(4, {3'000, 2'000}, {0, 0}, 20, {{}, CellularPatchAddress{1'000, 0}}, + {{100}, {}}, {}, budget(), *map); + CHECK(absent && absent->intake_status == CellularIntakeStatus::missing); + CHECK(!propose_cellular_step(std::numeric_limits::max(), {3'000, 2'000}, {0, 0}, + 20, {}, {{100}, {}}, {}, budget(), *map)); + CHECK( + !propose_cellular_step(0, {2'000, 2'000}, {0, 0}, 20, {}, {{100}, {}}, {}, budget(), *map)); + + auto full_heat = Inventory{{std::numeric_limits::max()}, {}}; + CHECK(!propose_cellular_step(0, {3'000, 2'000}, {0, 0}, 20, {}, {{100}, {}}, full_heat, + budget(), *map)); +} +} // namespace + +int main() { + try { + maintenance_motion_and_intake_conserve_one_tick(); + maintenance_precedes_motion_and_intake(); + refusals_and_noncontact_are_explicit(); + std::puts("PASS cellular step: tick order, funded motion and bounded feeding"); + } catch (const std::exception& error) { + std::fprintf(stderr, "%s\n", error.what()); + return 1; + } +}