diff --git a/CMakeLists.txt b/CMakeLists.txt index d3ff22f..6363535 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -71,7 +71,7 @@ add_library(evo_biology STATIC 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_region_step.cpp) + src/biology/cellular_region_step.cpp src/biology/budding.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) @@ -484,6 +484,11 @@ if(BUILD_TESTING) evo_owned_target(evo-mutation-tests) add_test(NAME mutation-contracts COMMAND evo-mutation-tests) set_tests_properties(mutation-contracts PROPERTIES TIMEOUT 120) + add_executable(evo-budding-tests tests/budding_tests.cpp) + target_link_libraries(evo-budding-tests PRIVATE evo::biology) + evo_owned_target(evo-budding-tests) + add_test(NAME budding-contracts COMMAND evo-budding-tests) + set_tests_properties(budding-contracts PROPERTIES TIMEOUT 120) add_executable(evo-lineage-tests tests/lineage_tests.cpp) target_link_libraries(evo-lineage-tests PRIVATE evo::biology) evo_owned_target(evo-lineage-tests) diff --git a/docs/adr/0125-cellular-budding-and-wildlife-descendants.md b/docs/adr/0125-cellular-budding-and-wildlife-descendants.md new file mode 100644 index 0000000..ade5788 --- /dev/null +++ b/docs/adr/0125-cellular-budding-and-wildlife-descendants.md @@ -0,0 +1,124 @@ +# ADR-0125: Cellular budding and wildlife descendants + +## Status + +Accepted engineering contract for M11.5 (2026-10-13), implementing ADR-0098 +decisions 1 and 3 and the wildlife controller boundary. Every quantity marked +**trial** is a versioned, playtestable value for 11.9 to revise, not a balance rule. + +## Context + +ADR-0098 fixes budding as the one M11 reproductive strategy: the parent survives +and keeps control, pays an explicit matter-and-energy investment, and the bud is +unowned wildlife from its first tick with an exact copy of the parent's current +genome. Reproduction is an action with a stable id and a durable outcome; the +server decides prerequisites, cost, placement and the child's genome. Wildlife +uses a bounded deterministic controller over the same intentions players use, with +no special biological rules. + +The profile-4 cellular owner (rules 3, format 4) already has durable v7+ actions +with a canonical 24-byte input whose byte 12 is a target kind (0 none, 1 patch, +2 engulf, ADR-0124), a life-ordered replay trace with one intention per living +cell, an archive with append-only genome revisions (ADR-0122), and ADR-0032's +`reproduction_investment`: the genome's reproduction fraction of the body's +matter, priced at the parent's own construction rate. + +## Decision + +### Action + +- A bud is target kind **3** of the canonical cellular action input and of the + trace intention, with zero coordinates, carried by v10 sessions only. It is + exclusive with an intake target and with engulfment, like kind 2. It rides the + existing durable action path: stable account-scoped id, receipt, committed + outcome, exact retry. The client supplies only the intention. +- The same kind in a wildlife intention is how the controller buds. There is no + second path. + +### Funding (rules 4) + +A bud is attempted after the tick's mutation phase and before player births, for +lives in stable life-id order, using the state entering that phase: + +- The parent must be alive, carry the reproduction capability, be fully realized + (growth 1000 per thousand) and undamaged. A bud born this tick cannot bud. +- **Investment** is the parent's ADR-0032 `reproduction_investment`: matter per + channel plus construction energy, which goes to region heat (construction + overhead, ADR-0028). +- The bud is born at the largest realized growth (per thousand, at most 1000) + whose developed body fits inside the investment matter on every channel. The + remaining investment matter becomes the bud's reserve matter: nothing is lost. +- **Provision (trial):** the parent also transfers energy for 30 seconds of the + bud's own full demand (maintenance plus full-speed movement) at its birth + growth, the founder's reserve rule (ADR-0100), into the bud's reserve. +- Everything is paid from the parent's **reserve**, never its body. A parent that + cannot pay the whole investment and provision on every channel is refused and + nothing is spent: abundant energy never pays for missing matter. + +### Placement + +- The bud is placed touching the parent, at centre distance parent extent + bud + extent + 1 micrometre, trying eight directions in fixed order (east, then + counter-clockwise in 45-degree steps). The first position inside the habitat + and separated from every living cell is used. +- If none is free the bud is refused for placement and nothing is spent. + Placement never grants a free or reduced bud. + +### Identity and heredity + +- A bud's life, organism and event identity is + `2^63 + region * 2^32 + sequence`, where `sequence` is a per-region counter in + the owner state, starting at 1. It is server-derived, durable in the checkpoint, + never reused, and replay derives it without a database round trip. Regions above + `2^31 - 1` cannot bud. Schema v36 adds a check that the world allocator stays + at or below `2^63`, so allocated and budded identities can never collide. +- The bud carries its parent's current genome (the same genome record, an exact + copy). The archive records the bud organism's birth with that genome and tick; + the owner records the parent life on the bud and keeps it after death. +- Wildlife never accrues mutation eligibility or offers in M11. + +### Wildlife + +- A wildlife life has the zero account. No session, action or perception targets + it; it is otherwise an ordinary cell: it pays maintenance, moves, feeds, can be + engulfed and dies. +- The server's controller is a pure, bounded function of the committed state and + the tick: bud when the parent can fund a bud; else move toward and feed from the + nearest perceived patch holding energy (the same 5 mm perception as players); + else wander in a direction derived from the life id and the tick, changed every + two seconds. It never engulfs in M11.5. Its output is recorded in the trace like + any intention, so replay never runs the controller. +- Descendants survive their parent's death and the parent's logout. Wildlife + progress is bounded by region ticks: the region simulates only while a player + is present (M11.3), so wildlife pauses with it. M11.7 revisits this together + with the offline freeze. + +### Versions + +- Owner format 5, rules 4 (`cellular-v3` opening): format 5 adds the bud sequence + and a parent life per life and corpse; rules 4 enable kind 3, funding, + placement and wildlife. +- Cellular version bundle v5. The replay trace stays format 3: kind 3 is an + intention byte value. Schema v36 admits kind 3 in action inputs, the v5 bundle + for revision-format publication and births, and the allocator bound. + +## Alternatives + +- **Automatic budding when funded:** rejected. ADR-0098 makes reproduction a + player action; only the wildlife controller decides automatically. +- **Allocating bud identities from the world allocator:** rejected for M11.5. + It needs a reservation and publication binding per bud, including wildlife buds + that no account owns. A region namespace is durable, unique and replayable. +- **Paying the investment from the body:** rejected. It would need growth + regression and a second development path; feeding into the reserve is how the + funding analysis (ADR-0098 decision 7) already counts. +- **A bud with no starting energy:** rejected. It would starve on its first tick, + so the investment would buy only a corpse. + +## Consequences + +Players can grow a lineage of wildlife that competes with them for food. Founders +remain the only way a new player life starts; a bud is never playable. Budding +adds a trace intent value, an owner format, a version bundle and a migration, and +no new SQL publication function. Wildlife pausing with an empty region is a known +M11.5 limit. diff --git a/docs/adr/README.md b/docs/adr/README.md index c9e07e3..4f709e0 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -25,6 +25,7 @@ - [ADR-0122: Append-only cellular genome revisions](0122-append-only-cellular-genome-revisions.md) - preserves immutable birth-genome links while adding a versioned revision chain and no-tick cellular-v3 migration. - [ADR-0123: Dev cellular region and life-allocator provisioning](0123-dev-cellular-region-and-life-allocator-provisioning.md) - moves DEV to cellular region 100/2 at schema v33 and has the owner provisioner create a world's life allocator once at an audited start. - [ADR-0124: Cellular engulfment and detritus](0124-cellular-engulfment-and-detritus.md) - resolves engulfment of a sufficiently smaller contacted cell and deposits every corpse's inventory into the patch grid as absorbable detritus, under cellular rules 3. +- [ADR-0125: Cellular budding and wildlife descendants](0125-cellular-budding-and-wildlife-descendants.md) - M11.5: a bud is v10 action kind 3, paid from the parent's reserve (ADR-0032 investment plus a 30 s provision), placed touching the parent, identified in a region namespace above 2^63, carrying the parent's genome; unowned wildlife driven by a pure deterministic controller whose intentions ride the trace. - [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_5_DELIVERY_PLAN.md b/docs/engineering/M11_5_DELIVERY_PLAN.md new file mode 100644 index 0000000..e6d80a7 --- /dev/null +++ b/docs/engineering/M11_5_DELIVERY_PLAN.md @@ -0,0 +1,50 @@ +# M11.5: Reproduce funded autonomous descendants + +M11.5 lets a player cell bud: it pays an explicit investment and leaves an +unowned wildlife descendant with an exact copy of its genome. The game rules are +ADR-0098 decisions 1 and 3; the engineering contract is +[ADR-0125](../adr/0125-cellular-budding-and-wildlife-descendants.md). The client +bud control and descendant presentation are the maintainer's (client UI is +deferred); this plan covers biology, owner, protocol, persistence and server. + +## Boundaries + +Read ADR-0028, ADR-0032, ADR-0098, ADR-0100, ADR-0122, ADR-0124 and ADR-0125 +before changing the owner. The biology library stays free of transport, database +and Kubernetes dependencies. Every bud is part of exactly one tick's replayed +checkpoint: its funding, placement, identity, archive birth and the parent's +debit recover together. No free or reduced offspring, no player ownership of a +descendant, and no special wildlife biology. + +## Segments + +| Segment | Affected modules | Acceptance evidence | +|---|---|---| +| 11.5a: funded bud proposal | Biology reproduction API; tests | Investment from the parent's reserve on every channel; largest fitting birth growth; remainder matter to the bud's reserve; construction energy to heat; 30 s provision; refusal for any short channel, missing capability, partial growth or damage, with nothing spent; exact conservation | +| 11.5b: owner budding and wildlife | Cellular lives owner, region step, snapshot codec (format 5, rules 4) | Kind 3 intention; placement ring and refusal; namespaced identity and sequence; archive birth; parent life on life and corpse; wildlife (zero account) has no offers; descendants survive parent death; restore and replay byte-identical | +| 11.5c: action, trace and publication | Session protocol and client sender, canonical action input, trace intent, version bundle v5, schema v36, provisioner `cellular-v3` | Kind 3 only on v10, exclusive with intake/engulf; SQL admits kind 3 and the v5 bundle; allocator bound; PostgreSQL publication and recovery of a bud | +| 11.5d: wildlife controller and DEV | Server wildlife controller, scheduler, DEV region | Pure deterministic bounded controller; wildlife intents recorded in the trace; a bud from a live session publishes and its descendant feeds and moves; rules-4 DEV region | + +## Required checks + +- Insufficient resources on each channel, a duplicate bud action and its ACK + loss, a bud refused for placement, parent death in the same tick, a bud engulfed + on a later tick, and a restart between bud and next tick. +- Controller determinism and bounds: same state and tick give the same + intentions; no intention is ever unfunded by construction (the owner still + validates). +- Genetic vulnerability comparison: a parent and its bud share one genome, and + the archive reports two living carriers until one dies. +- Linux CI PostgreSQL publication and recovery before claiming a live path. + +## Progress + +- 2026-10-13: ADR-0125 and this plan written. 11.5a is next. +- 11.5a: `fund_bud` (biology/budding) proposes a bud from a fully realized, + undamaged parent with the reproduction capability: the ADR-0032 investment and + a 30 s provision paid from the parent's reserve, the bud at the largest growth + its investment matter builds, leftover matter in the bud's reserve and the + construction energy to heat. `budding-contracts` checks conservation, the + largest-fit growth, the provision, determinism, a refusal for every short + channel (abundant energy never pays for matter), partial growth, damage and a + genome without the capability. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index a7c8c61..a3d2bb6 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -7340,3 +7340,14 @@ offer. Executed locally: MSVC Debug `ctest` 68/68, network 74/74, client-network 88/88; g++-14 `-Werror` and clang-tidy-19 on the protocol, session, host, client, server main and test sources (no new findings); clang-format 19.1.5. + +## 2026-10-13 — M11.5a funded bud proposal (CI pending) + +ADR-0125 and the M11.5 delivery plan define budding and wildlife descendants. +`evo::biology::fund_bud` is the pure proposal; `budding-contracts` covers +conservation on every channel, the largest-fit birth growth, the 30 s +provision, determinism, per-channel refusal with nothing spent, and the +not-grown, damaged and no-capability refusals. + +Executed locally: MSVC Debug `budding-contracts`; g++-14 `-Werror`, +clang-tidy-19 and clang-format 19.1.5 on the new sources. diff --git a/include/evo/biology/budding.hpp b/include/evo/biology/budding.hpp new file mode 100644 index 0000000..bb8cdf1 --- /dev/null +++ b/include/evo/biology/budding.hpp @@ -0,0 +1,36 @@ +#pragma once + +#include "evo/biology/metabolism.hpp" + +#include +#include + +// M11.5 budding (ADR-0098 decision 1, ADR-0125): a funded proposal, detached from any +// owner. The parent pays its ADR-0032 reproduction investment and a starting provision +// from its reserve; nothing is drawn from its body. +namespace evo::biology { +// Seconds of the bud's full demand (maintenance plus full-speed movement) the parent +// provides as starting reserve energy: the founder's reserve rule (ADR-0100). Trial. +inline constexpr std::uint64_t bud_provision_seconds = 30; + +struct BudTransition { + GrowthState growth{}; // the bud's, the largest the investment matter builds + accounting::Inventory body{}; // the bud's developed body + accounting::Inventory reserve; // the bud's: leftover matter and the provision + accounting::Inventory parent_reserve; // the parent's reserve after paying + accounting::Picojoules heat{}; // the investment's construction energy + auto operator<=>(const BudTransition&) const = default; +}; +enum class BuddingError : std::uint8_t { + no_capability, // The genome cannot reproduce. + not_grown, // The parent is not fully realized, or is damaged. + insufficient_funding, // Some channel of investment plus provision is missing. + development // The genome's rules cannot develop it. +}; + +// Pure and deterministic. On every channel the parent's reserve before equals its reserve +// after plus the bud's body and reserve, plus heat in energy. A refusal spends nothing. +[[nodiscard]] std::expected +fund_bud(const Genome& genome, GrowthState parent_growth, + const accounting::Inventory& parent_reserve, std::uint32_t temperature_millikelvin); +} // namespace evo::biology diff --git a/src/biology/budding.cpp b/src/biology/budding.cpp new file mode 100644 index 0000000..19d5daf --- /dev/null +++ b/src/biology/budding.cpp @@ -0,0 +1,76 @@ +#include "evo/biology/budding.hpp" + +#include + +namespace evo::biology { +namespace { +constexpr std::uint64_t maximum = std::numeric_limits::max(); + +bool fits(const accounting::Inventory& part, const accounting::Inventory& whole) noexcept { + for (std::size_t c = 0; c < part.matter.size(); ++c) + if (part.matter[c].value > whole.matter[c].value) + return false; + return part.energy.value <= whole.energy.value; +} +} // namespace + +std::expected fund_bud(const Genome& genome, GrowthState parent_growth, + const accounting::Inventory& parent_reserve, + std::uint32_t temperature_millikelvin) { + if (!genome.carries(Capability::reproduction)) + return std::unexpected{BuddingError::no_capability}; + if (parent_growth.realized_per_thousand != 1000 || parent_growth.damage_per_thousand != 0) + return std::unexpected{BuddingError::not_grown}; + const auto parent = metabolic_budget(genome, parent_growth, {temperature_millikelvin, {}}); + if (!parent) + return std::unexpected{BuddingError::development}; + const auto& investment = parent->reproduction_investment; + std::uint64_t invested_matter = 0; + for (const auto& mass : investment.matter) + invested_matter += mass.value; + if (invested_matter == 0) + return std::unexpected{BuddingError::no_capability}; + + // The largest realized growth whose developed body fits the invested matter on every + // channel. Bodies grow with realized growth, so the scan stops at the first fit. + for (std::uint32_t realized = 1000; realized > 0; --realized) { + const GrowthState growth{realized, 0}; + const auto bud = metabolic_budget(genome, growth, {temperature_millikelvin, {}}); + if (!bud) + return std::unexpected{BuddingError::development}; + accounting::Inventory body_only = bud->body; + body_only.energy = {}; + accounting::Inventory matter_only = investment; + matter_only.energy = {}; + if (!fits(body_only, matter_only)) + continue; + if (bud->rate_microseconds == 0) + return std::unexpected{BuddingError::development}; + const auto periods = bud_provision_seconds * 1'000'000 / bud->rate_microseconds; + if (periods != 0 && bud->demand.value > maximum / periods) + return std::unexpected{BuddingError::development}; + const auto provision = bud->demand.value * periods; + if (provision > maximum - investment.energy.value) + return std::unexpected{BuddingError::insufficient_funding}; + accounting::Inventory cost = investment; + cost.energy.value = investment.energy.value + provision; + if (!fits(cost, parent_reserve)) + return std::unexpected{BuddingError::insufficient_funding}; + + BudTransition transition; + transition.growth = growth; + transition.body = body_only; + transition.heat = investment.energy; + transition.reserve.energy.value = provision; + transition.parent_reserve = parent_reserve; + transition.parent_reserve.energy.value -= cost.energy.value; + for (std::size_t c = 0; c < investment.matter.size(); ++c) { + transition.reserve.matter[c].value = + investment.matter[c].value - body_only.matter[c].value; + transition.parent_reserve.matter[c].value -= investment.matter[c].value; + } + return transition; + } + return std::unexpected{BuddingError::insufficient_funding}; // Too little to build a cell. +} +} // namespace evo::biology diff --git a/tests/budding_tests.cpp b/tests/budding_tests.cpp new file mode 100644 index 0000000..9ef4693 --- /dev/null +++ b/tests/budding_tests.cpp @@ -0,0 +1,128 @@ +// M11.5a (ADR-0125): the funded bud proposal. +#include "evo/biology/budding.hpp" +#include "evo/biology/founder.hpp" + +#include +#include +#include +#include + +namespace { +using namespace evo::biology; +using namespace evo::accounting; +void check(bool condition, std::source_location location = std::source_location::current()) { + if (!condition) + throw std::runtime_error("budding line " + std::to_string(location.line())); +} +#define CHECK(expression) check(static_cast(expression)) +constexpr std::uint32_t temperate = 293'150; + +Genome founder() { + const auto genome = primitive_founder(5, 5); + CHECK(genome); + return *genome; +} +Inventory plenty() { + constexpr std::uint64_t lots = 1'000'000'000'000; + return {{lots}, {Femtograms{lots}, Femtograms{lots}, Femtograms{lots}, Femtograms{lots}}}; +} +// The parent's reserve before equals its reserve after plus the bud's body and reserve, +// plus heat in energy: nothing is created or lost on any channel. +bool conserves(const Inventory& before, const BudTransition& bud) { + for (std::size_t c = 0; c < before.matter.size(); ++c) + if (before.matter[c].value != bud.parent_reserve.matter[c].value + + bud.body.matter[c].value + bud.reserve.matter[c].value) + return false; + return bud.body.energy.value == 0 && before.energy.value == bud.parent_reserve.energy.value + + bud.reserve.energy.value + + bud.heat.value; +} + +void a_grown_parent_funds_the_largest_bud_its_investment_builds() { + const auto genome = founder(); + const auto reserve = plenty(); + const auto bud = fund_bud(genome, {1000, 0}, reserve, temperate); + CHECK(bud); + CHECK(conserves(reserve, *bud)); + const auto parent = metabolic_budget(genome, {1000, 0}, {temperate, {}}); + CHECK(parent); + // The founder invests half its body, so the bud is a partly realized cell. + CHECK(bud->growth.realized_per_thousand > 0 && bud->growth.realized_per_thousand < 1000 && + bud->growth.damage_per_thousand == 0); + CHECK(bud->heat == parent->reproduction_investment.energy); + const auto developed = metabolic_budget(genome, bud->growth, {temperate, {}}); + CHECK(developed); + CHECK(bud->body.matter == developed->body.matter); + // One more step of growth would not fit the investment. + if (bud->growth.realized_per_thousand < 1000) { + const auto larger = + metabolic_budget(genome, {bud->growth.realized_per_thousand + 1, 0}, {temperate, {}}); + CHECK(larger); + bool fits = true; + for (std::size_t c = 0; c < larger->body.matter.size(); ++c) + fits = fits && + larger->body.matter[c].value <= parent->reproduction_investment.matter[c].value; + CHECK(!fits); + } + // The provision is 30 seconds of the bud's own full demand. + CHECK(bud->reserve.energy.value == developed->demand.value * bud_provision_seconds * 1'000'000 / + developed->rate_microseconds); + CHECK(fund_bud(genome, {1000, 0}, reserve, temperate) == bud); // Deterministic. +} + +void every_short_channel_refuses_and_spends_nothing() { + const auto genome = founder(); + const auto exact = fund_bud(genome, {1000, 0}, plenty(), temperate); + CHECK(exact); + // The exact cost: what the parent's reserve lost. + Inventory cost; + for (std::size_t c = 0; c < cost.matter.size(); ++c) + cost.matter[c].value = plenty().matter[c].value - exact->parent_reserve.matter[c].value; + cost.energy.value = plenty().energy.value - exact->parent_reserve.energy.value; + const auto paid = fund_bud(genome, {1000, 0}, cost, temperate); + CHECK(paid && paid->parent_reserve == Inventory{} && conserves(cost, *paid)); + for (std::size_t c = 0; c <= cost.matter.size(); ++c) { + auto short_one = cost; + if (c == cost.matter.size()) { + if (short_one.energy.value == 0) + continue; + --short_one.energy.value; + } else { + if (short_one.matter[c].value == 0) + continue; + --short_one.matter[c].value; + // Abundant energy never pays for missing matter. + short_one.energy.value += 1'000'000'000; + } + CHECK(fund_bud(genome, {1000, 0}, short_one, temperate).error() == + BuddingError::insufficient_funding); + } +} + +void only_a_grown_undamaged_reproducing_parent_buds() { + const auto genome = founder(); + CHECK(fund_bud(genome, {999, 0}, plenty(), temperate).error() == BuddingError::not_grown); + CHECK(fund_bud(genome, {1000, 1}, plenty(), temperate).error() == BuddingError::not_grown); + const auto barren = Genome::create({9, + 1, + 2, + {}, + {{Capability::energy_conversion, 400, 0}, + {Capability::membrane, 1, 0}, + {Capability::target_size, 8'000'000, 0}}}); + CHECK(barren); + CHECK(fund_bud(*barren, {1000, 0}, plenty(), temperate).error() == BuddingError::no_capability); +} +} // namespace + +int main() { + try { + a_grown_parent_funds_the_largest_bud_its_investment_builds(); + every_short_channel_refuses_and_spends_nothing(); + only_a_grown_undamaged_reproducing_parent_buds(); + } catch (const std::exception& error) { + std::cerr << error.what() << '\n'; + return 1; + } + return 0; +}