diff --git a/CMakeLists.txt b/CMakeLists.txt index 6139075..8b16da0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -66,7 +66,10 @@ target_include_directories(evo_accounting PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/in target_compile_features(evo_accounting PUBLIC cxx_std_23) evo_owned_target(evo_accounting) -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) +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) 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) @@ -421,6 +424,11 @@ if(BUILD_TESTING) add_test(NAME development-contracts COMMAND evo-development-tests) set_tests_properties(development-contracts PROPERTIES TIMEOUT 60) add_executable(evo-metabolism-tests tests/metabolism_tests.cpp) + add_executable(evo-cellular-motion-tests tests/cellular_motion_tests.cpp) + target_link_libraries(evo-cellular-motion-tests PRIVATE evo::biology) + evo_owned_target(evo-cellular-motion-tests) + add_test(NAME cellular-motion-contracts COMMAND evo-cellular-motion-tests) + set_tests_properties(cellular-motion-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/0102-cellular-spatial-trial.md b/docs/adr/0102-cellular-spatial-trial.md index dbf7acb..86f93e0 100644 --- a/docs/adr/0102-cellular-spatial-trial.md +++ b/docs/adr/0102-cellular-spatial-trial.md @@ -21,8 +21,9 @@ patches without client authority over speed or position. - A cellular trial domain is a finite, axis-aligned 2D rectangle in one region/frame, expressed in integer micrometres. Its width and height are positive multiples of ADR-0101's patch pitch; the provisioned extent is - explicit and bounded. There is no wraparound. A body cannot leave the - rectangle; a movement step that reaches an edge is clamped there. + explicit and bounded to 1,000,000 μm per axis in this trial. There is no + wraparound. A body cannot leave the rectangle; a movement step that reaches + an edge is clamped there. - An organism's position is the lower-left corner of its square footprint, matching the existing primitive spawn-site overlap convention. Current phenotype extent determines that square. Spawn/restore rejects positions @@ -37,8 +38,9 @@ patches without client authority over speed or position. speed capacity. Invalid or stale intentions do not alter state. - Movement energy is derived from `MetabolicBudget::movement`, proportional to actual displacement relative to the full-speed tick distance and rounded up: - `ceil(full_speed_tick_cost * floor_sqrt(dx²+dy²) / per_tick_speed)`. Checked - quotient/remainder arithmetic is required; overflow refuses the whole step. + `ceil(full_speed_tick_cost * ceil_sqrt(dx²+dy²) / per_tick_speed)`. The + distance rounds up so the discrete approximation cannot undercharge motion. + Checked quotient/remainder arithmetic is required; overflow refuses the whole step. A zero per-tick speed or zero displacement costs zero. The movement resolver reports a proposed cost; the state owner applies the move only if the reserve can fund that cost. This resolver does not also spend maintenance, which diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index dac40b7..cc9bdc5 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -5818,3 +5818,23 @@ The Linux/PostgreSQL process suite now includes an isolated profile-3 lifecycle: owner-provision genesis, authenticate over v5, publish a founder, gracefully restart, and query the same immutable identity/commit receipt after recovery. This regression was added but cannot run locally on this Windows host; its CI evidence remains pending. + +## 2026-10-10 — M11.3b-1 phenotype-derived motion proposal (CI pending) + +Added the pure cellular motion proposal and square-footprint contact helper under +`evo::biology`. It uses the v2 per-second founder budget and 50 ms tick, clamps the +20 μm-class body inside a bounded trial area, reports movement energy without +spending it, and rejects invalid vectors, positions and rate periods. Focused tests +cover cardinal/diagonal movement, directional rounding, energy cost, boundaries, +unsupported rates and edge contact. No network, persistence, feeding or server +integration is included yet. + +Executed locally: MSVC 19.44 warning-as-error Debug compile/link and focused CTest +(1/1 passed); direct MSVC Release/NDEBUG compile/run (passed); clang-format 19.1.5 +dry-run; clang-tidy 19.1.5 against the generated compile database; and +`git diff --check`. The CMake configure completed with Visual Studio CMake 3.31.6 +and module scanning disabled (the project does not use C++ modules), but the Ninja +build target idled at 0 CPU and was stopped; the test executable was compiled +directly and then run by CTest. Linux GCC, ASan+UBSan and server/PostgreSQL process +qualification remain pending CI. This small resolver does not make 11.3 or a +playtest-ready cellular stage complete. diff --git a/include/evo/biology/cellular_motion.hpp b/include/evo/biology/cellular_motion.hpp new file mode 100644 index 0000000..fe2d616 --- /dev/null +++ b/include/evo/biology/cellular_motion.hpp @@ -0,0 +1,54 @@ +#pragma once + +#include "evo/biology/metabolism.hpp" + +#include +#include +#include + +namespace evo::biology { +inline constexpr std::uint64_t cellular_motion_tick_microseconds = 50'000; +inline constexpr std::uint64_t cellular_motion_axis_limit_um = 1'000'000; +inline constexpr std::int32_t cellular_intent_component_limit = 1'000; + +struct CellularArea { + std::uint64_t width_um{}, height_um{}; + auto operator<=>(const CellularArea&) const = default; +}; +// Lower-left corner of the cell's square footprint, in micrometres. +struct CellularPosition { + std::uint64_t x_um{}, y_um{}; + auto operator<=>(const CellularPosition&) const = default; +}; +// Bounded movement direction/magnitude, not a position or speed claim. +struct CellularIntent { + std::int16_t x{}, y{}; + auto operator<=>(const CellularIntent&) const = default; +}; +struct CellularMotionProposal { + CellularPosition position; + std::uint64_t distance_um{}; // Conservative integer upper bound on actual travel. + accounting::Picojoules movement_cost{}; + auto operator<=>(const CellularMotionProposal&) const = default; +}; +enum class CellularMotionError : std::uint8_t { + invalid_area, + invalid_extent, + outside_area, + invalid_intent, + unsupported_rate_period, + overflow +}; + +// Pure M11.3 proposal for one 50 ms tick. Costs are reported, not spent; the +// authoritative state owner must apply the proposal only when its reserve can +// fund the movement_cost. Only per-second development-v2 budgets are accepted. +[[nodiscard]] std::expected +propose_cellular_motion(CellularArea area, CellularPosition position, std::uint32_t extent_um, + CellularIntent intent, const MetabolicBudget& budget) noexcept; + +// Axis-aligned square footprints touching at an edge count as in contact. +[[nodiscard]] bool cellular_footprints_contact(CellularPosition a, std::uint32_t extent_a_um, + CellularPosition b, + std::uint32_t extent_b_um) noexcept; +} // namespace evo::biology diff --git a/src/biology/cellular_motion.cpp b/src/biology/cellular_motion.cpp new file mode 100644 index 0000000..b0457fb --- /dev/null +++ b/src/biology/cellular_motion.cpp @@ -0,0 +1,128 @@ +#include "evo/biology/cellular_motion.hpp" + +#include "evo/accounting/rates.hpp" + +#include + +namespace evo::biology { +namespace { +constexpr std::uint64_t rate_period_microseconds = 1'000'000; + +std::uint64_t integer_sqrt(std::uint64_t value) noexcept { + std::uint64_t result{}, bit = std::uint64_t{1} << 62U; + while (bit > value) + bit >>= 2U; + while (bit != 0) { + if (value >= result + bit) { + value -= result + bit; + result = (result >> 1U) + bit; + } else { + result >>= 1U; + } + bit >>= 2U; + } + return result; +} + +std::uint64_t integer_sqrt_ceil(std::uint64_t value) noexcept { + const auto floor = integer_sqrt(value); + return floor * floor == value ? floor : floor + 1; +} + +bool valid(CellularIntent intent) noexcept { + if (intent.x < -cellular_intent_component_limit || intent.x > cellular_intent_component_limit || + intent.y < -cellular_intent_component_limit || intent.y > cellular_intent_component_limit) + return false; + const auto x = static_cast(intent.x); + const auto y = static_cast(intent.y); + return x * x + y * y <= + std::int64_t{cellular_intent_component_limit} * cellular_intent_component_limit; +} + +std::expected +movement_cost(std::uint64_t full_cost, std::uint64_t distance, + std::uint64_t full_distance) noexcept { + if (distance == 0 || full_cost == 0) + return std::uint64_t{}; + if (full_distance == 0 || distance > full_distance) + return std::unexpected{CellularMotionError::overflow}; + const auto whole = full_cost / full_distance; + const auto remainder = full_cost % full_distance; + const auto base = whole * distance; // <= full_cost by construction. + const auto product = remainder * distance; // Both are bounded by uint32 speed per tick. + const auto fractional = product / full_distance + (product % full_distance != 0 ? 1 : 0); + if (fractional > std::numeric_limits::max() - base) + return std::unexpected{CellularMotionError::overflow}; + return base + fractional; +} + +} // namespace + +std::expected +propose_cellular_motion(CellularArea area, CellularPosition position, std::uint32_t extent_um, + CellularIntent intent, const MetabolicBudget& budget) noexcept { + if (area.width_um == 0 || area.height_um == 0 || + area.width_um > cellular_motion_axis_limit_um || + area.height_um > cellular_motion_axis_limit_um) + return std::unexpected{CellularMotionError::invalid_area}; + if (extent_um == 0 || extent_um > area.width_um || extent_um > area.height_um) + return std::unexpected{CellularMotionError::invalid_extent}; + if (position.x_um > area.width_um - extent_um || position.y_um > area.height_um - extent_um) + return std::unexpected{CellularMotionError::outside_area}; + if (!valid(intent)) + return std::unexpected{CellularMotionError::invalid_intent}; + if (budget.rate_microseconds != rate_period_microseconds) + return std::unexpected{CellularMotionError::unsupported_rate_period}; + + const auto max_step = + accounting::per_tick(budget.phenotype.movement_speed, cellular_motion_tick_microseconds, + accounting::Rounding::down); + const auto full_cost = accounting::per_tick( + budget.movement.value, cellular_motion_tick_microseconds, accounting::Rounding::up); + if (!max_step || !full_cost) + return std::unexpected{CellularMotionError::overflow}; + if (*max_step > static_cast(std::numeric_limits::max()) / + cellular_intent_component_limit) + return std::unexpected{CellularMotionError::overflow}; + + const auto dx = static_cast(intent.x) * static_cast(*max_step) / + cellular_intent_component_limit; + const auto dy = static_cast(intent.y) * static_cast(*max_step) / + cellular_intent_component_limit; + const auto max_x = area.width_um - extent_um; + const auto max_y = area.height_um - extent_um; + const auto next_x = + static_cast(dx < 0 ? (static_cast(-dx) > position.x_um + ? 0 + : static_cast(position.x_um) + dx) + : (dx > static_cast(max_x - position.x_um) + ? max_x + : static_cast(position.x_um) + dx)); + const auto next_y = + static_cast(dy < 0 ? (static_cast(-dy) > position.y_um + ? 0 + : static_cast(position.y_um) + dy) + : (dy > static_cast(max_y - position.y_um) + ? max_y + : static_cast(position.y_um) + dy)); + const auto moved_x = next_x >= position.x_um ? next_x - position.x_um : position.x_um - next_x; + const auto moved_y = next_y >= position.y_um ? next_y - position.y_um : position.y_um - next_y; + const auto distance = integer_sqrt_ceil(moved_x * moved_x + moved_y * moved_y); + const auto cost = movement_cost(*full_cost, distance, *max_step); + if (!cost) + return std::unexpected{cost.error()}; + return CellularMotionProposal{{next_x, next_y}, distance, {*cost}}; +} + +bool cellular_footprints_contact(CellularPosition a, std::uint32_t extent_a_um, CellularPosition b, + std::uint32_t extent_b_um) noexcept { + if (extent_a_um == 0 || extent_b_um == 0) + return false; + const auto axis_touches = [](std::uint64_t a_start, std::uint32_t a_extent, + std::uint64_t b_start, std::uint32_t b_extent) { + return a_start <= b_start ? b_start - a_start <= a_extent : a_start - b_start <= b_extent; + }; + return axis_touches(a.x_um, extent_a_um, b.x_um, extent_b_um) && + axis_touches(a.y_um, extent_a_um, b.y_um, extent_b_um); +} +} // namespace evo::biology diff --git a/tests/cellular_motion_tests.cpp b/tests/cellular_motion_tests.cpp new file mode 100644 index 0000000..2ac974a --- /dev/null +++ b/tests/cellular_motion_tests.cpp @@ -0,0 +1,97 @@ +#include "evo/biology/cellular_motion.hpp" + +#include +#include +#include +#include + +namespace { +using namespace evo::biology; +void check(bool value, std::source_location at = std::source_location::current()) { + if (!value) + throw std::runtime_error("cellular motion line " + std::to_string(at.line())); +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) + +MetabolicBudget budget(std::uint32_t speed_um_per_second = 200, + std::uint64_t movement_pj_per_second = 1'000) { + MetabolicBudget result{}; + result.phenotype.movement_speed = speed_um_per_second; + result.movement = {movement_pj_per_second}; + result.rate_microseconds = 1'000'000; + return result; +} + +void movement_proposals() { + const CellularArea area{400, 300}; + const CellularPosition start{100, 100}; + const auto east = propose_cellular_motion(area, start, 20, {1000, 0}, budget()); + CHECK(east && east->position == CellularPosition{110, 100}); + CHECK(east->distance_um == 10 && east->movement_cost.value == 50); + + const auto partial = propose_cellular_motion(area, start, 20, {500, 0}, budget()); + CHECK(partial && partial->position == CellularPosition{105, 100}); + CHECK(partial->distance_um == 5 && partial->movement_cost.value == 25); + + const auto diagonal = propose_cellular_motion(area, start, 20, {707, 707}, budget()); + CHECK(diagonal && diagonal->position == CellularPosition{107, 107}); + CHECK(diagonal->distance_um == 10 && diagonal->movement_cost.value == 50); + + const auto west = propose_cellular_motion(area, start, 20, {-1000, 0}, budget()); + CHECK(west && west->position == CellularPosition{90, 100}); + CHECK(west->movement_cost.value == 50); + + const auto stopped = propose_cellular_motion(area, start, 20, {0, 0}, budget()); + CHECK(stopped && stopped->position == start && stopped->distance_um == 0 && + stopped->movement_cost.value == 0); +} + +void edges_and_invalid_state() { + const auto east_edge = propose_cellular_motion({400, 300}, {370, 100}, 20, {1000, 0}, budget()); + CHECK(east_edge && east_edge->position == CellularPosition{380, 100}); + CHECK(east_edge->distance_um == 10 && east_edge->movement_cost.value == 50); + const auto pinned = propose_cellular_motion({400, 300}, {380, 100}, 20, {1000, 0}, budget()); + CHECK(pinned && pinned->position == CellularPosition{380, 100}); + CHECK(pinned->distance_um == 0 && pinned->movement_cost.value == 0); + const auto south_edge = propose_cellular_motion({400, 300}, {100, 1}, 20, {0, -1000}, budget()); + CHECK(south_edge && south_edge->position == CellularPosition{100, 0}); + CHECK(south_edge->distance_um == 1 && south_edge->movement_cost.value == 5); + + CHECK(!propose_cellular_motion({0, 300}, {0, 0}, 20, {}, budget())); + CHECK(!propose_cellular_motion({cellular_motion_axis_limit_um + 1, 300}, {0, 0}, 20, {}, + budget())); + CHECK(!propose_cellular_motion({400, 300}, {0, 0}, 0, {}, budget())); + CHECK(!propose_cellular_motion({400, 300}, {390, 0}, 20, {}, budget())); + CHECK(!propose_cellular_motion({400, 300}, {0, 0}, 401, {}, budget())); + CHECK(!propose_cellular_motion({400, 300}, {100, 100}, 20, {1000, 1000}, budget())); + auto wrong_rate_period = budget(); + wrong_rate_period.rate_microseconds = 50'000; + CHECK(!propose_cellular_motion({400, 300}, {100, 100}, 20, {}, wrong_rate_period)); + + // The per-tick speed rounds down by ADR-0099; no phantom sub-micrometre step. + const auto quantized = + propose_cellular_motion({400, 300}, {100, 100}, 20, {1000, 0}, budget(19)); + CHECK(quantized && quantized->position == CellularPosition{100, 100}); + CHECK(quantized->movement_cost.value == 0); +} + +void contact_geometry() { + CHECK(cellular_footprints_contact({0, 0}, 20, {20, 0}, 20)); // Exact edge touch. + CHECK(cellular_footprints_contact({0, 0}, 20, {19, 19}, 20)); + CHECK(!cellular_footprints_contact({0, 0}, 20, {21, 0}, 20)); + CHECK(!cellular_footprints_contact({0, 0}, 0, {0, 0}, 20)); + CHECK(cellular_footprints_contact({1'000'000, 1'000'000}, 20, {1'000'020, 1'000'020}, 20)); +} +} // namespace + +int main() { + try { + movement_proposals(); + edges_and_invalid_state(); + contact_geometry(); + std::puts("PASS cellular motion: phenotype speed, energy cost, bounds and contact"); + } catch (const std::exception& error) { + std::fprintf(stderr, "%s\n", error.what()); + return 1; + } +}