Add bounded cellular resource perception
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (network) (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (client) (push) Canceled after 1m8s
Foundation / checks (checks) (push) Canceled after 1m13s
Foundation / checks (ecs) (push) Canceled after 1m4s

This commit is contained in:
dingo
2026-10-10 21:16:54 -04:00
parent 1787718383
commit 44732967e7
7 changed files with 135 additions and 1 deletions
@@ -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.
+1
View File
@@ -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.
+3
View File
@@ -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
+17
View File
@@ -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.
+12
View File
@@ -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<const CellularPatch> patches() const noexcept;
[[nodiscard]] accounting::Inventory totals() const noexcept;
[[nodiscard]] std::optional<std::size_t> 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<std::vector<CellularPatchPerception>, CellularHabitatError>
perceive(CellularPosition position, std::uint32_t extent_um) const;
[[nodiscard]] std::expected<CellularPatchUptakeProposal, CellularHabitatError>
propose_uptake(CellularPatchAddress address, accounting::Inventory reserve,
const MetabolicBudget& budget) const noexcept;
+28
View File
@@ -123,6 +123,34 @@ std::optional<std::size_t> CellularHabitat::find(CellularPatchAddress address) c
return static_cast<std::size_t>(found - config_.patches.begin());
}
std::expected<std::vector<CellularPatchPerception>, 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<CellularPatchPerception> 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<CellularPatchUptakeProposal, CellularHabitatError>
CellularHabitat::propose_uptake(CellularPatchAddress address, accounting::Inventory reserve,
const MetabolicBudget& budget) const noexcept {
+25 -1
View File
@@ -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;