From 44732967e7ccafa85015989ca652fe214ed485d9 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 21:16:54 -0400 Subject: [PATCH] Add bounded cellular resource perception --- docs/adr/0103-cellular-perception-trial.md | 49 ++++++++++++++++++++++ docs/adr/README.md | 1 + docs/engineering/M11_3_DELIVERY_PLAN.md | 3 ++ docs/engineering/VALIDATION.md | 17 ++++++++ include/evo/biology/cellular_habitat.hpp | 12 ++++++ src/biology/cellular_habitat.cpp | 28 +++++++++++++ tests/cellular_habitat_tests.cpp | 26 +++++++++++- 7 files changed, 135 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0103-cellular-perception-trial.md diff --git a/docs/adr/0103-cellular-perception-trial.md b/docs/adr/0103-cellular-perception-trial.md new file mode 100644 index 0000000..ce41d3e --- /dev/null +++ b/docs/adr/0103-cellular-perception-trial.md @@ -0,0 +1,49 @@ +# ADR-0103: Cellular resource perception trial + +## Status + +Accepted direction for the M11.3 exploratory slice (2026-10-10). Range and +disclosure are versioned trial rules and may be revisited after hands-on use. + +## Context + +ADR-0101 adds sparse, finite food patches at a 1,000 μm pitch. ADR-0102 makes +the server authoritative for position and contact. A client needs enough local +information to choose where to steer, while unseen map stock and patch-opening +provenance must stay outside its view. The founder's starting movement capacity +is 200 μm/s; perception should show several nearby patches without revealing +the whole finite region. + +## Decision + +- The M11.3 trial uses a fixed 5,000 μm perception radius, measured as the + shortest Euclidean gap between the organism's square footprint and each + patch's square footprint. A patch exactly 5,000 μm away is visible. +- The server view may disclose the address and current exact energy and + matter inventory of provisioned patches within range, including an empty + provisioned patch. It never discloses source/provenance identifiers or + patches outside range. Unprovisioned patches are absent from the view. +- Clients cannot choose or enlarge this range. The biological owner derives + the footprint and position from authoritative state and returns a canonical + address-ordered projection. A footprint outside the habitat is rejected. +- The range is about 25 seconds of full-speed travel for the starting founder. + This is a trial affordance for steering and feeding choices, not a general + sensory law or a claim about the eventual world. + +## Alternatives considered + +- **Expose the full habitat:** rejected because finite stock outside the + perception boundary would become client knowledge. +- **Hide exact quantities:** deferred; exact nearby quantities make the first + agency and feeding-choice probe interpretable. A later revision can test a + coarser signal. +- **Let clients request their range:** rejected because it turns a view + boundary into a client-controlled information leak. + +## Consequences + +The pure habitat API can project visible patch records without exposing their +provenance. The live server still needs to bind this projection to the +authenticated life and authoritative position before the exploratory probe. +Changing range or disclosure after the probe requires an explicit trial-rule +revision and a checkpoint/profile version decision before persisted play. diff --git a/docs/adr/README.md b/docs/adr/README.md index 7fdcacb..4d9e388 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -3,6 +3,7 @@ - [ADR-0100: Primitive lives and persistent control](0100-primitive-lives-and-persistent-control.md) - accepted M11.2 direction: finite spawn pools, equal full-grown founders, new cellular checkpoint and atomic life publication. 11.2a adds in-memory funded creation; durability/integration follow. - [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-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 680b9df..98e1259 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -114,6 +114,9 @@ scoped change before starting the next segment. - 11.3c-1: pure channel-limited uptake proposal is implemented and locally tested. A finite patch map and canonical habitat-only codec are implemented; atomic update of patch, life reserve and durable action outcome remains open. +- 11.3a-2: ADR-0103 and the habitat's pure perception projection implement the + 5 mm footprint-gap trial radius and exact in-range stock view. Live authenticated + server replication and the complete cellular checkpoint remain open. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 3c34475..409de8b 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -5870,3 +5870,20 @@ dry-run; clang-tidy 19.1.5 against the generated compile database; and `git diff --check`. Linux GCC, ASan+UBSan and cellular server/PostgreSQL process qualification remain pending CI. This habitat codec does not replace or alter profile 3 and is not yet included in a live region checkpoint. + +## 2026-10-10 — M11.3a-2 cellular perception projection (CI pending) + +ADR-0103 fixes the exploratory sensor radius at 5,000 μm from the organism's +square footprint to a patch square. The pure habitat query rejects invalid +footprints and returns only canonical, in-range provisioned patch addresses and +exact available inventories; source provenance and out-of-range stock are not +part of the projection. The range is about 25 seconds of starting-founder +full-speed travel and is a trial value, not a final sensory rule. + +Executed locally: warning-as-error MSVC 19.44 Debug compile/run and Release +`NDEBUG` compile/run of the focused habitat tests (both passed); focused CTest +for cellular motion, uptake and habitat (3/3 passed); clang-format 19.1.5 +dry-run; clang-tidy 19.1.5 using the MSVC `/std:c++latest` argument; and +`git diff --check`. Linux GCC, ASan+UBSan, authenticated server visibility and +the full CI suite remain pending CI. This projection is not yet wired into live +replication or a persistent cellular checkpoint. diff --git a/include/evo/biology/cellular_habitat.hpp b/include/evo/biology/cellular_habitat.hpp index 74ce2b8..e7442a5 100644 --- a/include/evo/biology/cellular_habitat.hpp +++ b/include/evo/biology/cellular_habitat.hpp @@ -15,6 +15,7 @@ namespace evo::biology { inline constexpr std::uint32_t cellular_patch_pitch_um = 1'000; +inline constexpr std::uint32_t cellular_trial_perception_radius_um = 5'000; inline constexpr std::size_t max_cellular_patches = 4'096; inline constexpr std::uint32_t cellular_habitat_format = 1; inline constexpr std::size_t cellular_habitat_header_bytes = 72; @@ -43,6 +44,12 @@ struct CellularPatchUptakeProposal { CellularUptakeProposal transfer; auto operator<=>(const CellularPatchUptakeProposal&) const = default; }; +// Client-safe view of an in-range patch. Provenance remains server-owned. +struct CellularPatchPerception { + CellularPatchAddress address; + accounting::Inventory available; + auto operator<=>(const CellularPatchPerception&) const = default; +}; enum class CellularHabitatError : std::uint8_t { invalid_config, invalid_patch, @@ -50,6 +57,7 @@ enum class CellularHabitatError : std::uint8_t { overflow, missing_patch, uptake, + outside_area, format, version, checksum, @@ -73,6 +81,10 @@ class CellularHabitat { [[nodiscard]] std::span patches() const noexcept; [[nodiscard]] accounting::Inventory totals() const noexcept; [[nodiscard]] std::optional find(CellularPatchAddress address) const noexcept; + // Returns patch stock only within the fixed M11.3 sensor radius. Patches + // are visible when the organism-to-patch-square gap is within that radius. + [[nodiscard]] std::expected, CellularHabitatError> + perceive(CellularPosition position, std::uint32_t extent_um) const; [[nodiscard]] std::expected propose_uptake(CellularPatchAddress address, accounting::Inventory reserve, const MetabolicBudget& budget) const noexcept; diff --git a/src/biology/cellular_habitat.cpp b/src/biology/cellular_habitat.cpp index 34ce294..c1dc01b 100644 --- a/src/biology/cellular_habitat.cpp +++ b/src/biology/cellular_habitat.cpp @@ -123,6 +123,34 @@ std::optional CellularHabitat::find(CellularPatchAddress address) c return static_cast(found - config_.patches.begin()); } +std::expected, CellularHabitatError> +CellularHabitat::perceive(CellularPosition position, std::uint32_t extent_um) const { + 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}; + + std::vector visible; + for (const auto& patch : config_.patches) { + const auto axis_gap = [](std::uint64_t body_start, std::uint32_t body_extent, + std::uint32_t patch_start) { + const auto body_end = body_start + body_extent; + const auto patch_end = std::uint64_t{patch_start} + cellular_patch_pitch_um; + if (body_end < patch_start) + return std::uint64_t{patch_start} - body_end; + if (patch_end < body_start) + return body_start - patch_end; + return std::uint64_t{}; + }; + const auto dx = axis_gap(position.x_um, extent_um, patch.address.x_um); + const auto dy = axis_gap(position.y_um, extent_um, patch.address.y_um); + const auto radius = std::uint64_t{cellular_trial_perception_radius_um}; + if (dx * dx + dy * dy <= radius * radius) + visible.push_back({patch.address, patch.stock}); + } + return visible; +} + std::expected CellularHabitat::propose_uptake(CellularPatchAddress address, accounting::Inventory reserve, const MetabolicBudget& budget) const noexcept { diff --git a/tests/cellular_habitat_tests.cpp b/tests/cellular_habitat_tests.cpp index 435a82b..ef5930b 100644 --- a/tests/cellular_habitat_tests.cpp +++ b/tests/cellular_habitat_tests.cpp @@ -78,6 +78,29 @@ void canonical_snapshot_round_trip() { CHECK(!CellularHabitat::restore(oversized, 7, 9, 11)); } +void perception_is_bounded_by_body_to_patch_distance() { + CellularHabitatConfig opening{7, + 9, + 11, + 10'000, + 10'000, + {{{0, 0}, 51, {{1'000}, {}}}, + {{4'000, 4'000}, 52, {{2'000}, {}}}, + {{5'000, 5'000}, 53, {{3'000}, {}}}, + {{6'000, 0}, 54, {{4'000}, {}}}}}; + const auto made = CellularHabitat::create(std::move(opening)); + CHECK(made); + + const auto visible = (*made)->perceive({0, 0}, 1'000); + CHECK(visible); + CHECK(visible->size() == 3); + CHECK((*visible)[0] == CellularPatchPerception{{0, 0}, {{1'000}, {}}}); + CHECK((*visible)[1] == CellularPatchPerception{{4'000, 4'000}, {{2'000}, {}}}); + CHECK((*visible)[2] == CellularPatchPerception{{6'000, 0}, {{4'000}, {}}}); + CHECK(!(*made)->perceive({9'001, 0}, 1'000)); + CHECK(!(*made)->perceive({0, 0}, 0)); +} + void invalid_openings_refuse() { auto invalid = config(); invalid.width_um = 3'001; @@ -118,8 +141,9 @@ int main() { try { create_query_and_propose(); canonical_snapshot_round_trip(); + perception_is_bounded_by_body_to_patch_distance(); invalid_openings_refuse(); - std::puts("PASS cellular habitat: finite patch opening, lookup and canonical recovery"); + std::puts("PASS cellular habitat: finite patches, perception and canonical recovery"); } catch (const std::exception& error) { std::fprintf(stderr, "%s\n", error.what()); return 1;