diff --git a/CMakeLists.txt b/CMakeLists.txt index 8e917db..38fd540 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -70,7 +70,8 @@ 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_step.cpp) + src/biology/cellular_habitat.cpp src/biology/cellular_step.cpp + src/biology/cellular_region_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) @@ -445,6 +446,11 @@ if(BUILD_TESTING) 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-cellular-region-step-tests tests/cellular_region_step_tests.cpp) + target_link_libraries(evo-cellular-region-step-tests PRIVATE evo::biology) + evo_owned_target(evo-cellular-region-step-tests) + add_test(NAME cellular-region-step-contracts COMMAND evo-cellular-region-step-tests) + set_tests_properties(cellular-region-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 index d9688b3..e30b983 100644 --- a/docs/adr/0104-cellular-single-life-tick-order.md +++ b/docs/adr/0104-cellular-single-life-tick-order.md @@ -53,7 +53,8 @@ shared candidate habitat before invoking or replacing this single-life helper. ## 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. +heat transfer and one contact-gated patch intake into a detached value. +ADR-0106 adds shared-stock arbitration around this single-life proposal. Neither +helper is yet connected to life ownership, the cellular checkpoint, network +intentions or durable outcomes. Those integrations are required before the +exploratory hands-on probe. diff --git a/docs/adr/0106-cellular-contested-patch-arbitration.md b/docs/adr/0106-cellular-contested-patch-arbitration.md new file mode 100644 index 0000000..34dbccf --- /dev/null +++ b/docs/adr/0106-cellular-contested-patch-arbitration.md @@ -0,0 +1,45 @@ +# ADR-0106: Cellular contested patch arbitration trial + +## Status + +Accepted for the M11.3 exploratory slice (2026-10-10). The arbitration order +is explicit and reviewable with the 11.3e playtest evidence; it is not a claim +of long-term balance. + +## Context + +ADR-0101 makes each cellular patch finite. ADR-0104 orders one life's maintenance, +movement and intake, but a shared patch can receive claims from multiple lives in +the same tick. Resolving each life against the original patch would duplicate +stock. Network arrival order is nondeterministic and cannot decide the biological +result. + +## Decision + +- Resolve a region's life proposals in ascending stable world life identity, + independent of input, session and connection order. +- Each valid claimant receives its per-channel intake limit from the patch stock + remaining after earlier identities. An exhausted channel transfers zero; other + channels remain independent. +- Produce one detached region candidate with the final patch stocks and every + life result. If any life cannot produce its tick candidate, refuse the entire + result; the caller publishes no partial tick. +- This trial does not define death/corpse closure, cell-to-cell contact, engulfment + or durable publication. Those remain later 11.3c/11.3d work. + +## Alternatives considered + +- **Connection or arrival order:** rejected because it is nondeterministic and + gives transport timing biological effect. +- **Proportional allocation:** deferred; it changes the meaning of the existing + per-life intake cap and needs a different conservation/fairness trial. +- **Seeded rotation:** deferred until playtest evidence shows fixed identity order + causes a meaningful fairness problem. It would add state or a new deterministic + arbitration rule. + +## Consequences + +The first implementation provides a bounded deterministic shared-patch candidate +and verifies channel conservation. Ascending identity can favour older lives under +repeated scarcity; 11.3e records whether that is understandable and acceptable. +Changing the order requires updating this decision and deterministic replay evidence. diff --git a/docs/adr/README.md b/docs/adr/README.md index 8561e1c..6ae0db5 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -4,8 +4,9 @@ - [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-0105: Cellular session intention protocol v6](0105-cellular-session-intention-v6.md) - accepted M11.3 wire direction for movement plus an optional food-patch target; v1-v5 remain frozen and v6 server admission is still to be implemented. +- [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; life ownership and durable publication remain open. +- [ADR-0105: Cellular session intention protocol v6](0105-cellular-session-intention-v6.md) - accepted M11.3 wire direction for movement plus an optional food-patch target; v1-v5 remain frozen and v6 has an opt-in admission path. +- [ADR-0106: Cellular contested patch arbitration trial](0106-cellular-contested-patch-arbitration.md) - accepted M11.3 trial resolves same-tick finite-stock claims by stable life identity, independent of connection order. - [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 28de517..745166f 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -138,6 +138,10 @@ scoped change before starting the next segment. exposes the scheduled input to the host; the session client can send v6 movement and a requested patch address. V6 currently has no M10 probe view. Biology ownership, durable publication and perceived cell views remain open. +- 11.3c-4: ADR-0106 defines stable life-identity arbitration for same-tick patch + contention. A detached multi-life candidate resolves all claims against each + patch's remaining per-channel stock; starvation still refuses the candidate + pending same-tick death/corpse closure. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index b6bbce6..e973515 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -5986,3 +5986,20 @@ on changed ranges; clang-tidy 19.1.5 on all three changed C++ files using idled without launching a compiler, so the changed objects and test executable were built directly in the existing `build/quic` tree. Linux CI qualification and the full application build remain pending. + +## 2026-10-10 — M11.3c-4 deterministic shared-patch candidate (CI pending) + +Added ADR-0106's trial arbitration: same-tick claims resolve by ascending stable +life identity and use the patch's remaining per-channel stock. The pure batch +candidate returns all life results and final patch stocks together; if a life +cannot produce its one-tick proposal, it refuses the whole candidate. It does +not close starvation into a corpse or publish state. + +Executed locally: warning-as-error MSVC 19.44 Debug and Release/NDEBUG direct +compile/run of the focused region-step regression; Debug direct compile/run of +the existing habitat and single-life step regressions; clang-format 19.1.5 on +the new/changed C++ ranges; clang-tidy 19.1.5 with `-std=c++23` on the changed +implementation and test; and `git diff --check`. The tests confirm input-order +independent arbitration, per-channel conservation, no mutation of the source +habitat and no partial result for duplicate identities or starvation. CTest and +Linux sanitizer/CI qualification remain pending. diff --git a/include/evo/biology/cellular_habitat.hpp b/include/evo/biology/cellular_habitat.hpp index 3410b2c..502edef 100644 --- a/include/evo/biology/cellular_habitat.hpp +++ b/include/evo/biology/cellular_habitat.hpp @@ -89,6 +89,13 @@ class CellularHabitat { [[nodiscard]] std::expected propose_uptake(CellularPatchAddress address, CellularPosition position, std::uint32_t extent_um, accounting::Inventory reserve, const MetabolicBudget& budget) const noexcept; + // Same authoritative map/contact checks with stock supplied by a detached shared-tick + // candidate after earlier life claims have been resolved. + [[nodiscard]] std::expected + propose_uptake_from_stock(CellularPatchAddress address, CellularPosition position, + std::uint32_t extent_um, accounting::Inventory patch_stock, + accounting::Inventory reserve, + const MetabolicBudget& budget) const noexcept; // Canonical little-endian envelope, FNV-1a64 checksum for corruption checks only. [[nodiscard]] std::vector snapshot() const; diff --git a/include/evo/biology/cellular_region_step.hpp b/include/evo/biology/cellular_region_step.hpp new file mode 100644 index 0000000..9d6c7de --- /dev/null +++ b/include/evo/biology/cellular_region_step.hpp @@ -0,0 +1,58 @@ +#pragma once + +#include "evo/biology/cellular_step.hpp" + +#include +#include +#include +#include +#include +#include + +namespace evo::biology { +inline constexpr std::size_t max_cellular_tick_lives = 256; + +struct CellularLifeStepInput { + std::uint64_t life_id{}; // Stable world identity; arbitrates same-tick patch contention. + CellularPosition position; + std::uint32_t extent_um{}; + CellularStepIntent intent; + accounting::Inventory reserve; + accounting::Inventory heat; + MetabolicBudget budget; + auto operator<=>(const CellularLifeStepInput&) const = default; +}; +struct CellularLifeStepResult { + std::uint64_t life_id{}; + CellularStepCandidate candidate; + auto operator<=>(const CellularLifeStepResult&) const = default; +}; +struct CellularPatchStockUpdate { + CellularPatchAddress address; + accounting::Inventory stock; + auto operator<=>(const CellularPatchStockUpdate&) const = default; +}; +struct CellularRegionStepCandidate { + std::uint64_t begin_tick{}, end_tick{}; + // Sorted by stable life_id, independent of connection or input order. + std::vector lives; + std::vector patches; + auto operator<=>(const CellularRegionStepCandidate&) const = default; +}; +enum class CellularRegionStepError : std::uint8_t { + invalid_tick, + too_many_lives, + invalid_life_id, + duplicate_life_id, + life_step, + habitat +}; + +// Detached shared-habitat candidate. Same-tick claims resolve by ascending stable life id; +// the first valid claimant spends from each patch's remaining per-channel stock. Any refused +// life step rejects the complete candidate; the caller publishes nothing. +[[nodiscard]] std::expected +propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area, + std::span lives, + const CellularHabitat& habitat); +} // namespace evo::biology diff --git a/src/biology/cellular_habitat.cpp b/src/biology/cellular_habitat.cpp index 4327d16..2bf00d8 100644 --- a/src/biology/cellular_habitat.cpp +++ b/src/biology/cellular_habitat.cpp @@ -162,14 +162,30 @@ CellularHabitat::propose_uptake(CellularPatchAddress address, CellularPosition p const auto index = find(address); if (!index) return std::unexpected{CellularHabitatError::missing_patch}; - const auto& patch = config_.patches[*index]; - if (!cellular_footprints_contact(position, extent_um, {patch.address.x_um, patch.address.y_um}, + return propose_uptake_from_stock(address, position, extent_um, config_.patches[*index].stock, + reserve, budget); +} + +std::expected +CellularHabitat::propose_uptake_from_stock(CellularPatchAddress address, CellularPosition position, + std::uint32_t extent_um, + accounting::Inventory patch_stock, + accounting::Inventory reserve, + const MetabolicBudget& budget) const noexcept { + if (extent_um == 0 || extent_um > config_.width_um || extent_um > config_.height_um || + position.x_um > config_.width_um - extent_um || + position.y_um > config_.height_um - extent_um) + return std::unexpected{CellularHabitatError::outside_area}; + const auto index = find(address); + if (!index) + return std::unexpected{CellularHabitatError::missing_patch}; + if (!cellular_footprints_contact(position, extent_um, {address.x_um, address.y_um}, cellular_patch_pitch_um)) return std::unexpected{CellularHabitatError::not_in_contact}; - const auto uptake = propose_cellular_uptake(patch.stock, reserve, budget); + const auto uptake = propose_cellular_uptake(patch_stock, reserve, budget); if (!uptake) return std::unexpected{CellularHabitatError::uptake}; - return CellularPatchUptakeProposal{address, *uptake}; + return CellularPatchUptakeProposal{config_.patches[*index].address, *uptake}; } std::vector CellularHabitat::snapshot() const { diff --git a/src/biology/cellular_region_step.cpp b/src/biology/cellular_region_step.cpp new file mode 100644 index 0000000..69d165f --- /dev/null +++ b/src/biology/cellular_region_step.cpp @@ -0,0 +1,76 @@ +#include "evo/biology/cellular_region_step.hpp" + +#include +#include +#include + +namespace evo::biology { +std::expected +propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area, + std::span lives, + const CellularHabitat& habitat) { + if (begin_tick == std::numeric_limits::max()) + return std::unexpected{CellularRegionStepError::invalid_tick}; + if (lives.size() > max_cellular_tick_lives) + return std::unexpected{CellularRegionStepError::too_many_lives}; + + std::vector ordered; + ordered.reserve(lives.size()); + for (const auto& life : lives) { + if (life.life_id == 0) + return std::unexpected{CellularRegionStepError::invalid_life_id}; + ordered.push_back(&life); + } + std::ranges::sort(ordered, {}, [](const auto* life) { return life->life_id; }); + for (std::size_t i = 1; i < ordered.size(); ++i) + if (ordered[i - 1]->life_id == ordered[i]->life_id) + return std::unexpected{CellularRegionStepError::duplicate_life_id}; + + CellularRegionStepCandidate candidate{begin_tick, begin_tick + 1, {}, {}}; + candidate.lives.reserve(ordered.size()); + std::vector patch_stock; + patch_stock.reserve(habitat.patches().size()); + for (const auto& patch : habitat.patches()) + patch_stock.push_back(patch.stock); + + for (const auto* life : ordered) { + auto intent = life->intent; + const auto target = intent.intake_target; + intent.intake_target.reset(); + const auto step = + propose_cellular_step(begin_tick, area, life->position, life->extent_um, intent, + life->reserve, life->heat, life->budget, habitat); + if (!step) + return std::unexpected{CellularRegionStepError::life_step}; + auto result = *step; + if (target) { + const auto index = habitat.find(*target); + if (!index) { + result.intake_status = CellularIntakeStatus::missing; + } else { + const auto intake = habitat.propose_uptake_from_stock( + *target, result.position, life->extent_um, patch_stock[*index], + result.reserve_after, life->budget); + if (!intake) { + if (intake.error() == CellularHabitatError::not_in_contact) { + result.intake_status = CellularIntakeStatus::out_of_contact; + } else { + return std::unexpected{CellularRegionStepError::habitat}; + } + } else { + patch_stock[*index] = intake->transfer.patch_after; + result.reserve_after = intake->transfer.reserve_after; + result.intake_status = CellularIntakeStatus::acquired; + result.intake = *intake; + } + } + } + candidate.lives.push_back({life->life_id, result}); + } + + for (std::size_t i = 0; i < patch_stock.size(); ++i) + if (patch_stock[i] != habitat.patches()[i].stock) + candidate.patches.push_back({habitat.patches()[i].address, patch_stock[i]}); + return candidate; +} +} // namespace evo::biology diff --git a/tests/cellular_region_step_tests.cpp b/tests/cellular_region_step_tests.cpp new file mode 100644 index 0000000..c9fdf10 --- /dev/null +++ b/tests/cellular_region_step_tests.cpp @@ -0,0 +1,101 @@ +#include "evo/biology/cellular_region_step.hpp" + +#include +#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 region step line " + std::to_string(at.line())); +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) + +MetabolicBudget budget() { + MetabolicBudget value{}; + value.rate_microseconds = 1'000'000; + value.intake_limit = {{1'000}, {{{1'000}, {1'000}, {1'000}, {1'000}}}}; + return value; +} + +std::unique_ptr habitat() { + CellularHabitatConfig opening{7, 9, 11, + 3'000, 2'000, {{{0, 0}, 51, {{5}, {{{2}, {2}, {2}, {2}}}}}}}; + auto made = CellularHabitat::create(std::move(opening)); + CHECK(made); + return std::move(*made); +} + +void shared_patch_claims_are_identity_ordered_and_conserved() { + const auto map = habitat(); + const CellularLifeStepInput later{ + 20, {0, 0}, 20, {{0, 0}, CellularPatchAddress{0, 0}}, {{100}, {}}, {}, budget()}; + const CellularLifeStepInput earlier{ + 10, {0, 0}, 20, {{0, 0}, CellularPatchAddress{0, 0}}, {{100}, {}}, {}, budget()}; + const std::array input{later, earlier}; // Deliberately opposite the arbitration order. + const auto candidate = propose_cellular_region_step(4, {3'000, 2'000}, input, *map); + CHECK(candidate); + CHECK(candidate->begin_tick == 4 && candidate->end_tick == 5); + CHECK(candidate->lives.size() == 2); + CHECK(candidate->lives[0].life_id == 10 && candidate->lives[1].life_id == 20); + CHECK(candidate->lives[0].candidate.intake_status == CellularIntakeStatus::acquired); + const auto first_intake = + candidate->lives[0].candidate.intake.value_or(CellularPatchUptakeProposal{}); + CHECK(candidate->lives[0].candidate.intake.has_value()); + CHECK(first_intake.transfer.acquired == Inventory{{5}, {{{2}, {2}, {2}, {2}}}}); + CHECK(candidate->lives[1].candidate.intake_status == CellularIntakeStatus::acquired); + const auto second_intake = + candidate->lives[1].candidate.intake.value_or(CellularPatchUptakeProposal{}); + CHECK(candidate->lives[1].candidate.intake.has_value()); + CHECK(second_intake.transfer.acquired == Inventory{}); + CHECK(candidate->patches.size() == 1); + CHECK(candidate->patches[0] == CellularPatchStockUpdate{{0, 0}, {}}); + CHECK(map->patches()[0].stock == Inventory{{5}, {{{2}, {2}, {2}, {2}}}}); + + Inventory matter{}; + for (const auto& life : candidate->lives) + for (std::size_t channel = 0; channel < matter.matter.size(); ++channel) + matter.matter[channel].value += life.candidate.reserve_after.matter[channel].value; + for (std::size_t channel = 0; channel < matter.matter.size(); ++channel) + CHECK(matter.matter[channel].value + candidate->patches[0].stock.matter[channel].value == + map->patches()[0].stock.matter[channel].value); + CHECK(candidate->lives[0].candidate.reserve_after.energy.value + + candidate->lives[1].candidate.reserve_after.energy.value + + candidate->patches[0].stock.energy.value == + 100 + 100 + map->patches()[0].stock.energy.value); +} + +void refusal_never_returns_partial_tick_state() { + const auto map = habitat(); + const std::array duplicate{CellularLifeStepInput{1, {0, 0}, 20, {}, {{100}, {}}, {}, budget()}, + CellularLifeStepInput{1, {0, 0}, 20, {}, {{100}, {}}, {}, budget()}}; + const auto repeated = propose_cellular_region_step(4, {3'000, 2'000}, duplicate, *map); + CHECK(!repeated && repeated.error() == CellularRegionStepError::duplicate_life_id); + + auto starved_life = CellularLifeStepInput{2, {0, 0}, 20, {}, {{0}, {}}, {}, budget()}; + auto starved_budget = budget(); + starved_budget.maintenance = {1'000}; + starved_life.budget = starved_budget; + const std::array starved{starved_life}; + const auto refused = propose_cellular_region_step(4, {3'000, 2'000}, starved, *map); + CHECK(!refused && refused.error() == CellularRegionStepError::life_step); + CHECK(map->patches()[0].stock == Inventory{{5}, {{{2}, {2}, {2}, {2}}}}); +} +} // namespace + +int main() { + try { + shared_patch_claims_are_identity_ordered_and_conserved(); + refusal_never_returns_partial_tick_state(); + std::puts("PASS cellular region step: deterministic shared-stock candidate"); + } catch (const std::exception& error) { + std::fprintf(stderr, "%s\n", error.what()); + return 1; + } +}