Resolve cellular patch contention per tick
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m55s
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 (network) (push) Canceled after 1m26s
Foundation / checks (client) (push) Canceled after 3m33s
Foundation / checks (checks) (push) Canceled after 3m38s

This commit is contained in:
dingo
2026-10-10 21:51:38 -04:00
parent 747b063c65
commit b5e831f385
11 changed files with 343 additions and 11 deletions
+7 -1
View File
@@ -70,7 +70,8 @@ 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_habitat.cpp src/biology/cellular_step.cpp)
src/biology/cellular_habitat.cpp src/biology/cellular_step.cpp
src/biology/cellular_region_step.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)
@@ -445,6 +446,11 @@ if(BUILD_TESTING)
evo_owned_target(evo-cellular-step-tests)
add_test(NAME cellular-step-contracts COMMAND evo-cellular-step-tests)
set_tests_properties(cellular-step-contracts PROPERTIES TIMEOUT 60)
add_executable(evo-cellular-region-step-tests tests/cellular_region_step_tests.cpp)
target_link_libraries(evo-cellular-region-step-tests PRIVATE evo::biology)
evo_owned_target(evo-cellular-region-step-tests)
add_test(NAME cellular-region-step-contracts COMMAND evo-cellular-region-step-tests)
set_tests_properties(cellular-region-step-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)
@@ -53,7 +53,8 @@ shared candidate habitat before invoking or replacing this single-life helper.
## Consequences
The pure biology resolver composes rate conversion, movement affordability,
heat transfer and one contact-gated patch intake into a detached value. It is
not yet connected to life ownership, shared-stock contention, the cellular
checkpoint, network intentions or durable outcomes. Those integrations are
required before the exploratory hands-on probe.
heat transfer and one contact-gated patch intake into a detached value.
ADR-0106 adds shared-stock arbitration around this single-life proposal. Neither
helper is yet connected to life ownership, the cellular checkpoint, network
intentions or durable outcomes. Those integrations are required before the
exploratory hands-on probe.
@@ -0,0 +1,45 @@
# ADR-0106: Cellular contested patch arbitration trial
## Status
Accepted for the M11.3 exploratory slice (2026-10-10). The arbitration order
is explicit and reviewable with the 11.3e playtest evidence; it is not a claim
of long-term balance.
## Context
ADR-0101 makes each cellular patch finite. ADR-0104 orders one life's maintenance,
movement and intake, but a shared patch can receive claims from multiple lives in
the same tick. Resolving each life against the original patch would duplicate
stock. Network arrival order is nondeterministic and cannot decide the biological
result.
## Decision
- Resolve a region's life proposals in ascending stable world life identity,
independent of input, session and connection order.
- Each valid claimant receives its per-channel intake limit from the patch stock
remaining after earlier identities. An exhausted channel transfers zero; other
channels remain independent.
- Produce one detached region candidate with the final patch stocks and every
life result. If any life cannot produce its tick candidate, refuse the entire
result; the caller publishes no partial tick.
- This trial does not define death/corpse closure, cell-to-cell contact, engulfment
or durable publication. Those remain later 11.3c/11.3d work.
## Alternatives considered
- **Connection or arrival order:** rejected because it is nondeterministic and
gives transport timing biological effect.
- **Proportional allocation:** deferred; it changes the meaning of the existing
per-life intake cap and needs a different conservation/fairness trial.
- **Seeded rotation:** deferred until playtest evidence shows fixed identity order
causes a meaningful fairness problem. It would add state or a new deterministic
arbitration rule.
## Consequences
The first implementation provides a bounded deterministic shared-patch candidate
and verifies channel conservation. Ascending identity can favour older lives under
repeated scarcity; 11.3e records whether that is understandable and acceptable.
Changing the order requires updating this decision and deterministic replay evidence.
+3 -2
View File
@@ -4,8 +4,9 @@
- [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-0104: Cellular single-life tick order trial](0104-cellular-single-life-tick-order.md) - accepted M11.3 order for maintenance, funded movement and one contact-gated intake proposal; shared-stock contention and durable publication remain open.
- [ADR-0105: Cellular session intention protocol v6](0105-cellular-session-intention-v6.md) - accepted M11.3 wire direction for movement plus an optional food-patch target; v1-v5 remain frozen and v6 server admission is still to be implemented.
- [ADR-0104: Cellular single-life tick order trial](0104-cellular-single-life-tick-order.md) - accepted M11.3 order for maintenance, funded movement and one contact-gated intake proposal; life ownership and durable publication remain open.
- [ADR-0105: Cellular session intention protocol v6](0105-cellular-session-intention-v6.md) - accepted M11.3 wire direction for movement plus an optional food-patch target; v1-v5 remain frozen and v6 has an opt-in admission path.
- [ADR-0106: Cellular contested patch arbitration trial](0106-cellular-contested-patch-arbitration.md) - accepted M11.3 trial resolves same-tick finite-stock claims by stable life identity, independent of connection order.
- [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows.
+4
View File
@@ -138,6 +138,10 @@ scoped change before starting the next segment.
exposes the scheduled input to the host; the session client can send v6 movement
and a requested patch address. V6 currently has no M10 probe view. Biology
ownership, durable publication and perceived cell views remain open.
- 11.3c-4: ADR-0106 defines stable life-identity arbitration for same-tick patch
contention. A detached multi-life candidate resolves all claims against each
patch's remaining per-channel stock; starvation still refuses the candidate
pending same-tick death/corpse closure.
## Exit boundary
+17
View File
@@ -5986,3 +5986,20 @@ on changed ranges; clang-tidy 19.1.5 on all three changed C++ files using
idled without launching a compiler, so the changed objects and test executable
were built directly in the existing `build/quic` tree. Linux CI qualification
and the full application build remain pending.
## 2026-10-10 — M11.3c-4 deterministic shared-patch candidate (CI pending)
Added ADR-0106's trial arbitration: same-tick claims resolve by ascending stable
life identity and use the patch's remaining per-channel stock. The pure batch
candidate returns all life results and final patch stocks together; if a life
cannot produce its one-tick proposal, it refuses the whole candidate. It does
not close starvation into a corpse or publish state.
Executed locally: warning-as-error MSVC 19.44 Debug and Release/NDEBUG direct
compile/run of the focused region-step regression; Debug direct compile/run of
the existing habitat and single-life step regressions; clang-format 19.1.5 on
the new/changed C++ ranges; clang-tidy 19.1.5 with `-std=c++23` on the changed
implementation and test; and `git diff --check`. The tests confirm input-order
independent arbitration, per-channel conservation, no mutation of the source
habitat and no partial result for duplicate identities or starvation. CTest and
Linux sanitizer/CI qualification remain pending.
+7
View File
@@ -89,6 +89,13 @@ class CellularHabitat {
[[nodiscard]] std::expected<CellularPatchUptakeProposal, CellularHabitatError>
propose_uptake(CellularPatchAddress address, CellularPosition position, std::uint32_t extent_um,
accounting::Inventory reserve, const MetabolicBudget& budget) const noexcept;
// Same authoritative map/contact checks with stock supplied by a detached shared-tick
// candidate after earlier life claims have been resolved.
[[nodiscard]] std::expected<CellularPatchUptakeProposal, CellularHabitatError>
propose_uptake_from_stock(CellularPatchAddress address, CellularPosition position,
std::uint32_t extent_um, accounting::Inventory patch_stock,
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;
@@ -0,0 +1,58 @@
#pragma once
#include "evo/biology/cellular_step.hpp"
#include <compare>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <span>
#include <vector>
namespace evo::biology {
inline constexpr std::size_t max_cellular_tick_lives = 256;
struct CellularLifeStepInput {
std::uint64_t life_id{}; // Stable world identity; arbitrates same-tick patch contention.
CellularPosition position;
std::uint32_t extent_um{};
CellularStepIntent intent;
accounting::Inventory reserve;
accounting::Inventory heat;
MetabolicBudget budget;
auto operator<=>(const CellularLifeStepInput&) const = default;
};
struct CellularLifeStepResult {
std::uint64_t life_id{};
CellularStepCandidate candidate;
auto operator<=>(const CellularLifeStepResult&) const = default;
};
struct CellularPatchStockUpdate {
CellularPatchAddress address;
accounting::Inventory stock;
auto operator<=>(const CellularPatchStockUpdate&) const = default;
};
struct CellularRegionStepCandidate {
std::uint64_t begin_tick{}, end_tick{};
// Sorted by stable life_id, independent of connection or input order.
std::vector<CellularLifeStepResult> lives;
std::vector<CellularPatchStockUpdate> patches;
auto operator<=>(const CellularRegionStepCandidate&) const = default;
};
enum class CellularRegionStepError : std::uint8_t {
invalid_tick,
too_many_lives,
invalid_life_id,
duplicate_life_id,
life_step,
habitat
};
// Detached shared-habitat candidate. Same-tick claims resolve by ascending stable life id;
// the first valid claimant spends from each patch's remaining per-channel stock. Any refused
// life step rejects the complete candidate; the caller publishes nothing.
[[nodiscard]] std::expected<CellularRegionStepCandidate, CellularRegionStepError>
propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area,
std::span<const CellularLifeStepInput> lives,
const CellularHabitat& habitat);
} // namespace evo::biology
+20 -4
View File
@@ -162,14 +162,30 @@ CellularHabitat::propose_uptake(CellularPatchAddress address, CellularPosition p
const auto index = find(address);
if (!index)
return std::unexpected{CellularHabitatError::missing_patch};
const auto& patch = config_.patches[*index];
if (!cellular_footprints_contact(position, extent_um, {patch.address.x_um, patch.address.y_um},
return propose_uptake_from_stock(address, position, extent_um, config_.patches[*index].stock,
reserve, budget);
}
std::expected<CellularPatchUptakeProposal, CellularHabitatError>
CellularHabitat::propose_uptake_from_stock(CellularPatchAddress address, CellularPosition position,
std::uint32_t extent_um,
accounting::Inventory patch_stock,
accounting::Inventory reserve,
const MetabolicBudget& budget) const noexcept {
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};
const auto index = find(address);
if (!index)
return std::unexpected{CellularHabitatError::missing_patch};
if (!cellular_footprints_contact(position, extent_um, {address.x_um, address.y_um},
cellular_patch_pitch_um))
return std::unexpected{CellularHabitatError::not_in_contact};
const auto uptake = propose_cellular_uptake(patch.stock, reserve, budget);
const auto uptake = propose_cellular_uptake(patch_stock, reserve, budget);
if (!uptake)
return std::unexpected{CellularHabitatError::uptake};
return CellularPatchUptakeProposal{address, *uptake};
return CellularPatchUptakeProposal{config_.patches[*index].address, *uptake};
}
std::vector<std::uint8_t> CellularHabitat::snapshot() const {
+76
View File
@@ -0,0 +1,76 @@
#include "evo/biology/cellular_region_step.hpp"
#include <algorithm>
#include <limits>
#include <utility>
namespace evo::biology {
std::expected<CellularRegionStepCandidate, CellularRegionStepError>
propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area,
std::span<const CellularLifeStepInput> lives,
const CellularHabitat& habitat) {
if (begin_tick == std::numeric_limits<std::uint64_t>::max())
return std::unexpected{CellularRegionStepError::invalid_tick};
if (lives.size() > max_cellular_tick_lives)
return std::unexpected{CellularRegionStepError::too_many_lives};
std::vector<const CellularLifeStepInput*> ordered;
ordered.reserve(lives.size());
for (const auto& life : lives) {
if (life.life_id == 0)
return std::unexpected{CellularRegionStepError::invalid_life_id};
ordered.push_back(&life);
}
std::ranges::sort(ordered, {}, [](const auto* life) { return life->life_id; });
for (std::size_t i = 1; i < ordered.size(); ++i)
if (ordered[i - 1]->life_id == ordered[i]->life_id)
return std::unexpected{CellularRegionStepError::duplicate_life_id};
CellularRegionStepCandidate candidate{begin_tick, begin_tick + 1, {}, {}};
candidate.lives.reserve(ordered.size());
std::vector<accounting::Inventory> patch_stock;
patch_stock.reserve(habitat.patches().size());
for (const auto& patch : habitat.patches())
patch_stock.push_back(patch.stock);
for (const auto* life : ordered) {
auto intent = life->intent;
const auto target = intent.intake_target;
intent.intake_target.reset();
const auto step =
propose_cellular_step(begin_tick, area, life->position, life->extent_um, intent,
life->reserve, life->heat, life->budget, habitat);
if (!step)
return std::unexpected{CellularRegionStepError::life_step};
auto result = *step;
if (target) {
const auto index = habitat.find(*target);
if (!index) {
result.intake_status = CellularIntakeStatus::missing;
} else {
const auto intake = habitat.propose_uptake_from_stock(
*target, result.position, life->extent_um, patch_stock[*index],
result.reserve_after, life->budget);
if (!intake) {
if (intake.error() == CellularHabitatError::not_in_contact) {
result.intake_status = CellularIntakeStatus::out_of_contact;
} else {
return std::unexpected{CellularRegionStepError::habitat};
}
} else {
patch_stock[*index] = intake->transfer.patch_after;
result.reserve_after = intake->transfer.reserve_after;
result.intake_status = CellularIntakeStatus::acquired;
result.intake = *intake;
}
}
}
candidate.lives.push_back({life->life_id, result});
}
for (std::size_t i = 0; i < patch_stock.size(); ++i)
if (patch_stock[i] != habitat.patches()[i].stock)
candidate.patches.push_back({habitat.patches()[i].address, patch_stock[i]});
return candidate;
}
} // namespace evo::biology
+101
View File
@@ -0,0 +1,101 @@
#include "evo/biology/cellular_region_step.hpp"
#include <array>
#include <cstdio>
#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 region step line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
MetabolicBudget budget() {
MetabolicBudget value{};
value.rate_microseconds = 1'000'000;
value.intake_limit = {{1'000}, {{{1'000}, {1'000}, {1'000}, {1'000}}}};
return value;
}
std::unique_ptr<CellularHabitat> habitat() {
CellularHabitatConfig opening{7, 9, 11,
3'000, 2'000, {{{0, 0}, 51, {{5}, {{{2}, {2}, {2}, {2}}}}}}};
auto made = CellularHabitat::create(std::move(opening));
CHECK(made);
return std::move(*made);
}
void shared_patch_claims_are_identity_ordered_and_conserved() {
const auto map = habitat();
const CellularLifeStepInput later{
20, {0, 0}, 20, {{0, 0}, CellularPatchAddress{0, 0}}, {{100}, {}}, {}, budget()};
const CellularLifeStepInput earlier{
10, {0, 0}, 20, {{0, 0}, CellularPatchAddress{0, 0}}, {{100}, {}}, {}, budget()};
const std::array input{later, earlier}; // Deliberately opposite the arbitration order.
const auto candidate = propose_cellular_region_step(4, {3'000, 2'000}, input, *map);
CHECK(candidate);
CHECK(candidate->begin_tick == 4 && candidate->end_tick == 5);
CHECK(candidate->lives.size() == 2);
CHECK(candidate->lives[0].life_id == 10 && candidate->lives[1].life_id == 20);
CHECK(candidate->lives[0].candidate.intake_status == CellularIntakeStatus::acquired);
const auto first_intake =
candidate->lives[0].candidate.intake.value_or(CellularPatchUptakeProposal{});
CHECK(candidate->lives[0].candidate.intake.has_value());
CHECK(first_intake.transfer.acquired == Inventory{{5}, {{{2}, {2}, {2}, {2}}}});
CHECK(candidate->lives[1].candidate.intake_status == CellularIntakeStatus::acquired);
const auto second_intake =
candidate->lives[1].candidate.intake.value_or(CellularPatchUptakeProposal{});
CHECK(candidate->lives[1].candidate.intake.has_value());
CHECK(second_intake.transfer.acquired == Inventory{});
CHECK(candidate->patches.size() == 1);
CHECK(candidate->patches[0] == CellularPatchStockUpdate{{0, 0}, {}});
CHECK(map->patches()[0].stock == Inventory{{5}, {{{2}, {2}, {2}, {2}}}});
Inventory matter{};
for (const auto& life : candidate->lives)
for (std::size_t channel = 0; channel < matter.matter.size(); ++channel)
matter.matter[channel].value += life.candidate.reserve_after.matter[channel].value;
for (std::size_t channel = 0; channel < matter.matter.size(); ++channel)
CHECK(matter.matter[channel].value + candidate->patches[0].stock.matter[channel].value ==
map->patches()[0].stock.matter[channel].value);
CHECK(candidate->lives[0].candidate.reserve_after.energy.value +
candidate->lives[1].candidate.reserve_after.energy.value +
candidate->patches[0].stock.energy.value ==
100 + 100 + map->patches()[0].stock.energy.value);
}
void refusal_never_returns_partial_tick_state() {
const auto map = habitat();
const std::array duplicate{CellularLifeStepInput{1, {0, 0}, 20, {}, {{100}, {}}, {}, budget()},
CellularLifeStepInput{1, {0, 0}, 20, {}, {{100}, {}}, {}, budget()}};
const auto repeated = propose_cellular_region_step(4, {3'000, 2'000}, duplicate, *map);
CHECK(!repeated && repeated.error() == CellularRegionStepError::duplicate_life_id);
auto starved_life = CellularLifeStepInput{2, {0, 0}, 20, {}, {{0}, {}}, {}, budget()};
auto starved_budget = budget();
starved_budget.maintenance = {1'000};
starved_life.budget = starved_budget;
const std::array starved{starved_life};
const auto refused = propose_cellular_region_step(4, {3'000, 2'000}, starved, *map);
CHECK(!refused && refused.error() == CellularRegionStepError::life_step);
CHECK(map->patches()[0].stock == Inventory{{5}, {{{2}, {2}, {2}, {2}}}});
}
} // namespace
int main() {
try {
shared_patch_claims_are_identity_ordered_and_conserved();
refusal_never_returns_partial_tick_state();
std::puts("PASS cellular region step: deterministic shared-stock candidate");
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;
}
}