Add finite cellular habitat snapshot
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m56s
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 (checks) (push) Canceled after 2m39s
Foundation / checks (client) (push) Canceled after 2m38s
Foundation / checks (network) (push) Canceled after 36s

This commit is contained in:
dingo
2026-10-10 21:13:51 -04:00
parent c552eb3250
commit 1787718383
8 changed files with 526 additions and 2 deletions
+7 -1
View File
@@ -69,7 +69,8 @@ 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
src/biology/cellular_motion.cpp src/biology/cellular_uptake.cpp)
src/biology/cellular_motion.cpp src/biology/cellular_uptake.cpp
src/biology/cellular_habitat.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)
@@ -434,6 +435,11 @@ if(BUILD_TESTING)
evo_owned_target(evo-cellular-uptake-tests)
add_test(NAME cellular-uptake-contracts COMMAND evo-cellular-uptake-tests)
set_tests_properties(cellular-uptake-contracts PROPERTIES TIMEOUT 60)
add_executable(evo-cellular-habitat-tests tests/cellular_habitat_tests.cpp)
target_link_libraries(evo-cellular-habitat-tests PRIVATE evo::biology)
evo_owned_target(evo-cellular-habitat-tests)
add_test(NAME cellular-habitat-contracts COMMAND evo-cellular-habitat-tests)
set_tests_properties(cellular-habitat-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)
@@ -87,4 +87,6 @@ available until its conservation transaction is designed and tested.
M11.3 adds a pure cellular habitat/resource owner and server adapter rather than
expanding `FieldStore` or `EnvironmentalTransfers`. Required evidence and the
remaining spatial, persistence and server work are tracked in the
[M11.3 delivery plan](../engineering/M11_3_DELIVERY_PLAN.md).
[M11.3 delivery plan](../engineering/M11_3_DELIVERY_PLAN.md). The habitat-only
codec is specified in [cellular-habitat-v1.md](../../schemas/cellular-habitat-v1.md);
it is not yet an admitted region checkpoint profile.
+13
View File
@@ -102,6 +102,19 @@ scoped change before starting the next segment.
feeding choices, cost legibility and reasons to continue. One session is
exploratory feedback, not evidence that the product is fun.
## Progress
- 11.3a contract direction: ADR-0101 selects finite 1 mm cellular food patches;
ADR-0102 defines bounded non-wrapping movement and footprint contact. The
complete living-set checkpoint, perception contract and server profile remain
open.
- 11.3b-1: pure phenotype-derived movement proposal and square-footprint contact
helper are implemented and locally tested. Session inputs, server state,
replication and durable movement publication remain open.
- 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.
## Exit boundary
11.3 closes only when all five segments have evidence and the player-facing
+16
View File
@@ -5854,3 +5854,19 @@ dry-run; clang-tidy 19.1.5 against the generated compile database; and
`git diff --check`. Linux GCC and sanitizer runs are unavailable locally; the full
cellular-owner conservation, contention, durable publication and PostgreSQL process
checks remain pending CI. This helper does not yet close the server-side transfer.
## 2026-10-10 — M11.3a-1 finite cellular habitat map (CI pending)
Added the region/frame-scoped cellular habitat owner: explicit 1 mm patch
coordinates, per-patch provenance and finite C/N/P/other/energy openings; strict
area, ordering, count and total-inventory bounds; and a canonical versioned
snapshot/restore codec. It refuses absent patches rather than supplying stock.
Read-only uptake proposals combine the patch stock with the previous rate-limited
proposal, leaving publication to the later cellular host.
Executed locally: MSVC 19.44 warning-as-error Debug compile/link and focused CTest
(1/1 passed); direct 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`. 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.
+92
View File
@@ -0,0 +1,92 @@
#pragma once
#include "evo/biology/cellular_motion.hpp"
#include "evo/biology/cellular_uptake.hpp"
#include <compare>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <memory>
#include <optional>
#include <span>
#include <utility>
#include <vector>
namespace evo::biology {
inline constexpr std::uint32_t cellular_patch_pitch_um = 1'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;
inline constexpr std::size_t cellular_patch_record_bytes = 56;
inline constexpr std::size_t max_cellular_habitat_bytes =
cellular_habitat_header_bytes + cellular_patch_record_bytes * max_cellular_patches + 8;
struct CellularPatchAddress {
std::uint32_t x_um{}, y_um{};
auto operator<=>(const CellularPatchAddress&) const = default;
};
struct CellularPatch {
CellularPatchAddress address;
std::uint64_t source{}; // Explicit region-opening provenance.
accounting::Inventory stock{};
auto operator<=>(const CellularPatch&) const = default;
};
struct CellularHabitatConfig {
std::uint64_t world{}, region{}, frame{};
std::uint32_t width_um{}, height_um{};
std::vector<CellularPatch> patches; // Strictly ordered by (x_um, y_um).
auto operator<=>(const CellularHabitatConfig&) const = default;
};
struct CellularPatchUptakeProposal {
CellularPatchAddress patch;
CellularUptakeProposal transfer;
auto operator<=>(const CellularPatchUptakeProposal&) const = default;
};
enum class CellularHabitatError : std::uint8_t {
invalid_config,
invalid_patch,
duplicate_patch,
overflow,
missing_patch,
uptake,
format,
version,
checksum,
identity
};
// Region-local finite food stock for the cellular trial. Empty/unlisted patches
// contain no stock. This is a read/proposal owner; the caller commits its patch
// and organism candidate together through the durable cellular state owner.
class CellularHabitat {
public:
[[nodiscard]] static std::expected<std::unique_ptr<CellularHabitat>, CellularHabitatError>
create(CellularHabitatConfig config);
CellularHabitat(const CellularHabitat&) = delete;
CellularHabitat& operator=(const CellularHabitat&) = delete;
CellularHabitat(CellularHabitat&&) = delete;
CellularHabitat& operator=(CellularHabitat&&) = delete;
~CellularHabitat();
[[nodiscard]] const CellularHabitatConfig& config() const noexcept;
[[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;
[[nodiscard]] std::expected<CellularPatchUptakeProposal, CellularHabitatError>
propose_uptake(CellularPatchAddress address, accounting::Inventory reserve,
const MetabolicBudget& budget) const noexcept;
// Canonical little-endian envelope, FNV-1a64 checksum for corruption checks only.
[[nodiscard]] std::vector<std::uint8_t> snapshot() const;
[[nodiscard]] static std::expected<std::unique_ptr<CellularHabitat>, CellularHabitatError>
restore(std::span<const std::uint8_t> bytes, std::uint64_t world, std::uint64_t region,
std::uint64_t frame);
private:
CellularHabitat(CellularHabitatConfig config, accounting::Inventory totals)
: config_{std::move(config)}, totals_{totals} {}
CellularHabitatConfig config_;
accounting::Inventory totals_{};
};
} // namespace evo::biology
+56
View File
@@ -0,0 +1,56 @@
# Cellular habitat snapshot v1
This bounded snapshot is implemented by `biology::CellularHabitat` under
ADR-0101. It describes a region-local finite food opening and its current stock;
it is not yet an admitted PostgreSQL checkpoint profile. A containing cellular
checkpoint must bind its exact world, region and frame identity.
All integers are unsigned little-endian unless stated. Records are packed by
the codec, not by native C++ layout.
## Envelope
| Offset | Width | Field | Contract |
|---:|---:|---|---|
| 0 | 8 | magic | ASCII `EVOPATK1` |
| 8 | 4 | format | 1 |
| 12 | 4 | habitat rules | 1 |
| 16 | 8 | world | Nonzero identity |
| 24 | 8 | region | Nonzero identity |
| 32 | 8 | frame | Nonzero identity |
| 40 | 4 | width_um | Positive, <=1,000,000, multiple of 1,000 |
| 44 | 4 | height_um | Positive, <=1,000,000, multiple of 1,000 |
| 48 | 4 | patch_pitch_um | 1,000 |
| 52 | 4 | patch_count | 0..4,096 |
| 56 | 8 | reserved | Zero |
| 64 | 8 | reserved | Zero |
| 72 | 56*n | patch records | Ordered by ascending (x_um,y_um) |
| 72+56*n | 8 | checksum | FNV-1a64 over all preceding bytes |
Exact length is `80 + 56 * patch_count`. The checksum detects accidental
corruption; it is not an authentication mechanism.
## Patch record (56 bytes)
| Offset | Width | Field | Contract |
|---:|---:|---|---|
| 0 | 4 | x_um | Patch lower-left coordinate; 1,000 μm aligned and in bounds |
| 4 | 4 | y_um | Patch lower-left coordinate; 1,000 μm aligned and in bounds |
| 8 | 8 | source | Nonzero opening-provenance identity |
| 16 | 8 | energy_pj | Finite usable chemical energy |
| 24 | 8 | carbon_fg | Finite organic carbon |
| 32 | 8 | nitrogen_fg | Finite organic nitrogen |
| 40 | 8 | phosphorus_fg | Finite organic phosphorus |
| 48 | 8 | other_fg | Finite organic other matter |
Unlisted patches contain no stock. Each conserved channel's sum across the
opening must fit `u64`; overflow rejects creation. Records must be strictly
ordered and unique. There is no automatic refill or default opening.
## Restore validation
Before allocating patch storage, the decoder checks the minimum/maximum byte
length, checksum, magic, versions, count cap and exact length. It then validates
identity, dimensions, patch pitch, zero reserved fields, patch alignment, source
ids, strict ordering and per-channel totals. Restore rebuilds through the same
creation validator and accepts only bytes identical to a canonical re-encoding.
+212
View File
@@ -0,0 +1,212 @@
#include "evo/biology/cellular_habitat.hpp"
#include <algorithm>
#include <array>
#include <limits>
namespace evo::biology {
namespace {
constexpr std::uint64_t habitat_magic = 0x314B5441504F5645ULL; // EVOPATK1
constexpr std::uint32_t habitat_rules = 1;
bool add(std::uint64_t value, std::uint64_t& total) noexcept {
if (value > std::numeric_limits<std::uint64_t>::max() - total)
return false;
total += value;
return true;
}
bool add(accounting::Inventory value, accounting::Inventory& total) noexcept {
if (!add(value.energy.value, total.energy.value))
return false;
for (std::size_t channel = 0; channel < value.matter.size(); ++channel)
if (!add(value.matter[channel].value, total.matter[channel].value))
return false;
return true;
}
std::uint64_t checksum(std::span<const std::uint8_t> bytes) noexcept {
std::uint64_t value = 14695981039346656037ULL;
for (const auto byte : bytes)
value = (value ^ byte) * 1099511628211ULL;
return value;
}
class Writer {
public:
explicit Writer(std::vector<std::uint8_t>& bytes) : bytes_{bytes} {}
void put(std::uint64_t value, unsigned width = 8) {
for (unsigned i = 0; i < width; ++i, value >>= 8U)
bytes_.push_back(static_cast<std::uint8_t>(value & 255U));
}
void inventory(accounting::Inventory value) {
put(value.energy.value);
for (const auto matter : value.matter)
put(matter.value);
}
private:
std::vector<std::uint8_t>& bytes_;
};
class Reader {
public:
explicit Reader(std::span<const std::uint8_t> bytes) : bytes_{bytes} {}
std::uint64_t get(unsigned width = 8) {
std::uint64_t value{};
for (unsigned i = 0; i < width; ++i)
value |= std::uint64_t{bytes_[at_++]} << (8U * i);
return value;
}
accounting::Inventory inventory() {
accounting::Inventory value{};
value.energy.value = get();
for (auto& matter : value.matter)
matter.value = get();
return value;
}
private:
std::span<const std::uint8_t> bytes_;
std::size_t at_{};
};
} // namespace
CellularHabitat::~CellularHabitat() = default;
std::expected<std::unique_ptr<CellularHabitat>, CellularHabitatError>
CellularHabitat::create(CellularHabitatConfig config) {
if (config.world == 0 || config.region == 0 || config.frame == 0 || config.width_um == 0 ||
config.height_um == 0 || config.width_um > cellular_motion_axis_limit_um ||
config.height_um > cellular_motion_axis_limit_um ||
config.width_um % cellular_patch_pitch_um != 0 ||
config.height_um % cellular_patch_pitch_um != 0 ||
config.patches.size() > max_cellular_patches)
return std::unexpected{CellularHabitatError::invalid_config};
accounting::Inventory totals{};
for (std::size_t index = 0; index < config.patches.size(); ++index) {
const auto& patch = config.patches[index];
if (patch.source == 0 || patch.address.x_um >= config.width_um ||
patch.address.y_um >= config.height_um ||
patch.address.x_um % cellular_patch_pitch_um != 0 ||
patch.address.y_um % cellular_patch_pitch_um != 0)
return std::unexpected{CellularHabitatError::invalid_patch};
if (index != 0 && !(config.patches[index - 1].address < patch.address))
return std::unexpected{config.patches[index - 1].address == patch.address
? CellularHabitatError::duplicate_patch
: CellularHabitatError::invalid_patch};
if (!add(patch.stock, totals))
return std::unexpected{CellularHabitatError::overflow};
}
return std::unique_ptr<CellularHabitat>{new CellularHabitat{std::move(config), totals}};
}
const CellularHabitatConfig& CellularHabitat::config() const noexcept {
return config_;
}
std::span<const CellularPatch> CellularHabitat::patches() const noexcept {
return config_.patches;
}
accounting::Inventory CellularHabitat::totals() const noexcept {
return totals_;
}
std::optional<std::size_t> CellularHabitat::find(CellularPatchAddress address) const noexcept {
const auto found = std::lower_bound(
config_.patches.begin(), config_.patches.end(), address,
[](const CellularPatch& patch, CellularPatchAddress key) { return patch.address < key; });
if (found == config_.patches.end() || found->address != address)
return std::nullopt;
return static_cast<std::size_t>(found - config_.patches.begin());
}
std::expected<CellularPatchUptakeProposal, CellularHabitatError>
CellularHabitat::propose_uptake(CellularPatchAddress address, accounting::Inventory reserve,
const MetabolicBudget& budget) const noexcept {
const auto index = find(address);
if (!index)
return std::unexpected{CellularHabitatError::missing_patch};
const auto& patch = config_.patches[*index];
const auto uptake = propose_cellular_uptake(patch.stock, reserve, budget);
if (!uptake)
return std::unexpected{CellularHabitatError::uptake};
return CellularPatchUptakeProposal{address, *uptake};
}
std::vector<std::uint8_t> CellularHabitat::snapshot() const {
std::vector<std::uint8_t> bytes;
bytes.reserve(cellular_habitat_header_bytes +
cellular_patch_record_bytes * config_.patches.size() + 8);
Writer out{bytes};
out.put(habitat_magic);
out.put(cellular_habitat_format, 4);
out.put(habitat_rules, 4);
out.put(config_.world);
out.put(config_.region);
out.put(config_.frame);
out.put(config_.width_um, 4);
out.put(config_.height_um, 4);
out.put(cellular_patch_pitch_um, 4);
out.put(config_.patches.size(), 4);
out.put(0); // Reserved.
out.put(0); // Reserved.
for (const auto& patch : config_.patches) {
out.put(patch.address.x_um, 4);
out.put(patch.address.y_um, 4);
out.put(patch.source);
out.inventory(patch.stock);
}
out.put(checksum(bytes));
return bytes;
}
std::expected<std::unique_ptr<CellularHabitat>, CellularHabitatError>
CellularHabitat::restore(std::span<const std::uint8_t> bytes, std::uint64_t world,
std::uint64_t region, std::uint64_t frame) {
if (bytes.size() < cellular_habitat_header_bytes + 8 ||
bytes.size() > max_cellular_habitat_bytes)
return std::unexpected{CellularHabitatError::format};
Reader tail{bytes.last(8)};
if (checksum(bytes.first(bytes.size() - 8)) != tail.get())
return std::unexpected{CellularHabitatError::checksum};
Reader in{bytes};
if (in.get() != habitat_magic)
return std::unexpected{CellularHabitatError::format};
if (in.get(4) != cellular_habitat_format || in.get(4) != habitat_rules)
return std::unexpected{CellularHabitatError::version};
CellularHabitatConfig config;
config.world = in.get();
config.region = in.get();
config.frame = in.get();
if (config.world != world || config.region != region || config.frame != frame)
return std::unexpected{CellularHabitatError::identity};
config.width_um = static_cast<std::uint32_t>(in.get(4));
config.height_um = static_cast<std::uint32_t>(in.get(4));
if (in.get(4) != cellular_patch_pitch_um)
return std::unexpected{CellularHabitatError::version};
const auto count = in.get(4);
if (in.get() != 0 || in.get() != 0 || count > max_cellular_patches ||
bytes.size() != cellular_habitat_header_bytes + cellular_patch_record_bytes * count + 8)
return std::unexpected{CellularHabitatError::format};
config.patches.reserve(static_cast<std::size_t>(count));
for (std::uint64_t index = 0; index < count; ++index) {
CellularPatch patch{};
patch.address.x_um = static_cast<std::uint32_t>(in.get(4));
patch.address.y_um = static_cast<std::uint32_t>(in.get(4));
patch.source = in.get();
patch.stock = in.inventory();
config.patches.push_back(patch);
}
auto restored = create(std::move(config));
if (!restored)
return std::unexpected{restored.error()};
const auto canonical = (*restored)->snapshot();
if (canonical.size() != bytes.size() ||
!std::equal(canonical.begin(), canonical.end(), bytes.begin()))
return std::unexpected{CellularHabitatError::format};
return std::move(*restored);
}
} // namespace evo::biology
+127
View File
@@ -0,0 +1,127 @@
#include "evo/biology/cellular_habitat.hpp"
#include <cstdio>
#include <limits>
#include <source_location>
#include <stdexcept>
#include <string>
#include <utility>
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 habitat line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
CellularHabitatConfig config() {
return {7,
9,
11,
3'000,
2'000,
{{{0, 0}, 51, {{1'000}, {{{20}, {10}, {5}, {2}}}}},
{{0, 1'000}, 51, {{0}, {{{0}, {0}, {0}, {0}}}}},
{{1'000, 0}, 52, {{2'000}, {{{30}, {15}, {7}, {3}}}}}}};
}
MetabolicBudget uptake_budget() {
MetabolicBudget result{};
result.rate_microseconds = 1'000'000;
result.intake_limit = {{1'000}, {{{100}, {50}, {25}, {10}}}};
return result;
}
void create_query_and_propose() {
const auto opening = config();
const auto made = CellularHabitat::create(opening);
CHECK(made);
CHECK((*made)->config() == opening);
CHECK((*made)->patches().size() == 3);
CHECK((*made)->find({1'000, 0}) == 2);
CHECK(!(*made)->find({2'000, 1'000}));
CHECK((*made)->totals() == Inventory{{3'000}, {{{50}, {25}, {12}, {5}}}});
const auto plan = (*made)->propose_uptake({0, 0}, {}, uptake_budget());
CHECK(plan && plan->patch == CellularPatchAddress{0, 0});
CHECK(plan->transfer.acquired == Inventory{{50}, {{{5}, {2}, {1}, {0}}}});
CHECK(plan->transfer.patch_after == Inventory{{950}, {{{15}, {8}, {4}, {2}}}});
CHECK(plan->transfer.reserve_after == plan->transfer.acquired);
CHECK((*made)->patches()[0].stock == Inventory{{1'000}, {{{20}, {10}, {5}, {2}}}});
CHECK(!(*made)->propose_uptake({2'000, 0}, {}, uptake_budget()));
}
void canonical_snapshot_round_trip() {
const auto made = CellularHabitat::create(config());
CHECK(made);
const auto bytes = (*made)->snapshot();
CHECK(bytes.size() == cellular_habitat_header_bytes +
cellular_patch_record_bytes * (*made)->patches().size() + 8);
const auto restored = CellularHabitat::restore(bytes, 7, 9, 11);
CHECK(restored);
CHECK((*restored)->config() == (*made)->config());
CHECK((*restored)->totals() == (*made)->totals());
CHECK((*restored)->snapshot() == bytes);
CHECK(!CellularHabitat::restore(bytes, 8, 9, 11));
CHECK(!CellularHabitat::restore(bytes, 7, 9, 12));
auto corrupt = bytes;
corrupt[20] ^= 1;
const auto refused = CellularHabitat::restore(corrupt, 7, 9, 11);
CHECK(!refused && refused.error() == CellularHabitatError::checksum);
CHECK(
!CellularHabitat::restore(std::span{bytes}.first(cellular_habitat_header_bytes), 7, 9, 11));
auto oversized = bytes;
oversized.resize(max_cellular_habitat_bytes + 1);
CHECK(!CellularHabitat::restore(oversized, 7, 9, 11));
}
void invalid_openings_refuse() {
auto invalid = config();
invalid.width_um = 3'001;
CHECK(!CellularHabitat::create(invalid));
invalid = config();
invalid.patches[1].address.x_um = 500;
CHECK(!CellularHabitat::create(invalid));
invalid = config();
invalid.patches[1].source = 0;
CHECK(!CellularHabitat::create(invalid));
invalid = config();
std::swap(invalid.patches[0], invalid.patches[1]);
CHECK(!CellularHabitat::create(invalid));
invalid = config();
invalid.patches[1].address = invalid.patches[0].address;
CHECK(!CellularHabitat::create(invalid));
invalid = {7,
9,
11,
2'000,
1'000,
{{{0, 0}, 1, {{std::numeric_limits<std::uint64_t>::max()}, {}}},
{{1'000, 0}, 2, {{1}, {}}}}};
const auto overflow = CellularHabitat::create(invalid);
CHECK(!overflow && overflow.error() == CellularHabitatError::overflow);
invalid = {7, 9, 11, 1'000'000, 1'000'000, {}};
for (std::uint32_t y = 0; y < 64'000; y += cellular_patch_pitch_um)
for (std::uint32_t x = 0; x < 65'000; x += cellular_patch_pitch_um)
invalid.patches.push_back({{x, y}, 1, {}});
CHECK(invalid.patches.size() > max_cellular_patches);
CHECK(!CellularHabitat::create(std::move(invalid)));
}
} // namespace
int main() {
try {
create_query_and_propose();
canonical_snapshot_round_trip();
invalid_openings_refuse();
std::puts("PASS cellular habitat: finite patch opening, lookup and canonical recovery");
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;
}
}