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
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:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user