From 84efa4bf14ed42913ba122ac722c385f3984492b Mon Sep 17 00:00:00 2001 From: dingo Date: Sun, 11 Oct 2026 02:42:53 -0400 Subject: [PATCH] Add funded cellular mutation proposal --- ...118-funded-cellular-mutation-transition.md | 54 +++++++++++++++ docs/engineering/M11_4_DELIVERY_PLAN.md | 51 ++++++++++++++ docs/engineering/VALIDATION.md | 21 +++++- include/evo/biology/mutation.hpp | 24 ++++++- src/biology/mutation.cpp | 68 +++++++++++++++++++ tests/mutation_tests.cpp | 49 +++++++++++++ 6 files changed, 264 insertions(+), 3 deletions(-) create mode 100644 docs/adr/0118-funded-cellular-mutation-transition.md create mode 100644 docs/engineering/M11_4_DELIVERY_PLAN.md diff --git a/docs/adr/0118-funded-cellular-mutation-transition.md b/docs/adr/0118-funded-cellular-mutation-transition.md new file mode 100644 index 0000000..25487f5 --- /dev/null +++ b/docs/adr/0118-funded-cellular-mutation-transition.md @@ -0,0 +1,54 @@ +# ADR-0118: Funded cellular mutation transitions + +## Status + +Accepted for the first M11 mutation implementation (2026-10-11). This is a +versioned trial contract, not a balance sign-off. Mutation eligibility, offer +timing and any tunable thresholds remain open for the 11.3 probe and 11.9 +repeated-life review. + +## Context + +ADR-0098 selects in-life mutation from seeded M3.4 offers and requires each +selection to be funded through development. `select_mutation` already returns an +immutable successor, while `metabolic_budget` derives the exact body inventory +from a genome and growth state. The missing pure step is the atomic inventory +proposal that joins them. A total-mass comparison is insufficient because one +channel cannot pay for another. + +## Decision + +For a selected candidate, keep the organism's current growth state and derive +both the current and successor body inventories under the same recorded +environment. For each matter channel independently: + +- A larger successor compartment is intake from the organism's reserve. +- A smaller successor compartment is released back to that reserve. +- A release in one channel cannot fund an intake in another channel. + +Construction energy is the current development version's construction rate +applied to the sum of the matter-channel intakes. It is charged from retained +reserve. The transition is refused unless every matter channel and energy can be +funded. No partial debit, growth change, or genome change is returned on refusal. +On success, the caller receives a detached successor genome, exact successor +body, exact new reserve, and the intake/release audit inventories. Only the +authoritative owner may commit it. + +This computes a trial cost from existing development and composition rules; it +does not add a mutation-specific price or multiplier. The existing M3 catalog, +seed, stream and event-index rules continue to determine the offer. Eligibility +and event cadence are separate contracts and are not inferred from this cost +proposal. + +## Consequences + +Candidate generation and selection remain pure. The funder can be tested for +channel conservation and refusal atomicity before session or persistence code is +involved. A successor that costs more than its current reserve cannot be chosen +until the organism has retained enough of every required resource. A future +balance change requires a versioned development-rule review; no old genome is +silently reinterpreted. + +The transition does not yet create or persist player-facing offers, award +eligibility, publish a genome revision, or define candidate UI. Those belong to +later M11.4 segments. diff --git a/docs/engineering/M11_4_DELIVERY_PLAN.md b/docs/engineering/M11_4_DELIVERY_PLAN.md new file mode 100644 index 0000000..6fa263d --- /dev/null +++ b/docs/engineering/M11_4_DELIVERY_PLAN.md @@ -0,0 +1,51 @@ +# M11.4: Apply earned mutation choices through development + +M11.4 connects the accepted M3 seeded candidate generator and immutable lineage +archive to a living player organism. The game rule authority is ADR-0098; the +first funded transition is ADR-0118. Candidate counts, event cadence, eligibility +thresholds and resource targets remain trial values until informed by the 11.3 +probe and later repeated-life tests. No class tree, candidate ranking or automatic +wildlife mutation is introduced. + +## Boundaries + +Read PROJECT_VISION, ENGINEERING_CONSTITUTION, GENOME_MODEL, +ADR-0030 through ADR-0034, ADR-0098, ADR-0108 through +ADR-0110 and the cellular checkpoint schema before changing the owner. Preserve +the M3 pure generator's seed/context rules and genome v1/v2 compatibility. The +headless biology library must not acquire transport, UI, database or Kubernetes +dependencies. Every accepted choice must be one durable action whose outcome, +successor genome, body transfer and life revision recover together. + +The 11.3 hands-on probe is now executable in the engineering client. Its human +notes remain the design input for tuning mutation timing and eligibility. The +maintainer has explicitly authorized continuing M11 work while those notes are +pending; no gameplay balance is treated as final by this plan. + +## Segments + +| Segment | Affected modules | Acceptance evidence | +|---|---|---| +| 11.4a: funded transition proposal | Biology mutation/development public API and implementation; mutation tests; ADR-0118 | Deterministic selection revalidation; exact per-channel body/reserve closure; construction energy charge; insufficient-channel refusal with no partial result; `NDEBUG` tests | +| 11.4b: earned eligibility and offer identity | Cellular life state, tick intake accounting, offer context, profile-4 codec/schema | Offers require retained fed surplus; exact retry returns the same offer; changed genome/context/tick refuses stale selection; no free rerolls; checkpoint restore preserves eligibility and action identity | +| 11.4c: durable mutation publication | Cellular host/session, SQL migration/action parser, replay, crash tests | One action atomically publishes debit, genome successor, organism revision, archive and result; duplicate retry is exact; uncertain commit and process restart have one outcome | +| 11.4d: player choice and review | Engineering client trial UI, replication, playtest notes | Owner sees unranked candidates and actual tradeoffs; choice/refusal/recovery is readable; playtest verifies the choice follows useful feeding rather than appearing at spawn | + +## Required checks + +- All current M3 mutation and archive tests remain unchanged and pass. +- Test equal inputs and retry after process restore, wrong/stale offers, + unaffordable candidates in each individual channel, overflow, and exact body + + reserve conservation. +- Exercise two candidates that trade construction, maintenance, movement, + ingestion and membrane defense without rendering a ranked score. +- Profile-4 PostgreSQL publication, crash/restart and Linux CI evidence are + required before claiming a live mutation path. +- Record the exploratory 11.3 probe feedback and revisit tuning before widening + candidate options or setting an event cadence. + +## Progress + +- 11.4a implementation is in progress: `fund_mutation` returns a detached, + channel-conserving transition under ADR-0118. Session offers, eligibility, + durable publication and UI remain open. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 327c4bd..d82d6d8 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -6661,5 +6661,22 @@ The live-region human probe remains the only open 11.3 gate. The local environment cannot query the operator's running region: `kubectl` reports that no current context is set and its default `localhost:8080` API is refused; no `evo-region` or `evo-server` process is running locally. The -maintainer must run the human probe against the operator's region and provide -the exploratory feedback before 11.4. +maintainer reports that the region is up and the client connects. The detailed +11.3 cellular-loop probe notes have not yet been recorded. Mutation work has +started at the maintainer's direction while those notes are pending; eligibility +and balance remain explicitly open. + +## 2026-10-11 — M11.4a funded mutation proposal + +The new `fund_mutation` biology proposal revalidates the exact seeded offer, +derives the successor body at the same growth state, and returns channel-specific +reserve intake/release plus construction energy. It refuses underfunding without +returning a partial transition. The mutation contract tests passed after a fresh +MSVC 19.44 `/W4 /WX /DNDEBUG` compile of the modified mutation, genome, +development, metabolism and rates sources with `tests/mutation_tests.cpp`. +Visual Studio LLVM `clang-format --dry-run --Werror` and `git diff --check` +passed. + +`cmake --build build/debug --target evo-mutation-tests` regenerated successfully +but stalled before target compilation, at the same Ninja glob recheck seen above. +The direct focused MSVC executable is local evidence only; full CI is pending. diff --git a/include/evo/biology/mutation.hpp b/include/evo/biology/mutation.hpp index 0da21c6..6583e6c 100644 --- a/include/evo/biology/mutation.hpp +++ b/include/evo/biology/mutation.hpp @@ -45,13 +45,27 @@ struct MutationOffer { std::vector candidates; auto operator<=>(const MutationOffer&) const = default; }; +// A fully funded genome change, detached from the organism until its owner +// commits it. Body matter is recomputed from the successor; reserve includes +// channel-specific material releases and pays all deficits plus construction +// energy. A refusal never spends anything. +struct MutationTransition { + Genome successor; + accounting::Inventory body; + accounting::Inventory reserve; + accounting::Inventory intake; + accounting::Inventory release; + auto operator<=>(const MutationTransition&) const = default; +}; enum class MutationError : std::uint8_t { invalid_context, no_candidates, unknown_candidate, context_changed, altered_offer, - invalid_successor + invalid_successor, + insufficient_funding, + development }; inline constexpr std::size_t max_candidates = 8; @@ -66,4 +80,12 @@ mutation_candidates(const Genome& genome, const MutationContext& context); [[nodiscard]] std::expected select_mutation(const Genome& genome, const MutationContext& context, const MutationOffer& offered, std::uint16_t chosen, std::uint64_t successor_id, std::uint64_t origin_event); +// Revalidates the offer, derives both bodies at the offer's recorded growth and +// environment, and funds the exact channel transition from retained reserve. +// Added matter in each channel incurs construction energy at that genome's +// versioned construction rate. No state is changed by this proposal. +[[nodiscard]] std::expected +fund_mutation(const Genome& genome, const MutationContext& context, const MutationOffer& offered, + std::uint16_t chosen, std::uint64_t successor_id, std::uint64_t origin_event, + const accounting::Inventory& reserve); } // namespace evo::biology diff --git a/src/biology/mutation.cpp b/src/biology/mutation.cpp index c8c922e..a059fea 100644 --- a/src/biology/mutation.cpp +++ b/src/biology/mutation.cpp @@ -217,4 +217,72 @@ select_mutation(const Genome& genome, const MutationContext& context, const Muta } return *successor; } + +std::expected +fund_mutation(const Genome& genome, const MutationContext& context, const MutationOffer& offered, + std::uint16_t chosen, std::uint64_t successor_id, std::uint64_t origin_event, + const accounting::Inventory& reserve) { + const auto successor = + select_mutation(genome, context, offered, chosen, successor_id, origin_event); + if (!successor) { + return std::unexpected{successor.error()}; + } + const auto before = metabolic_budget(genome, context.growth, context.environment); + const auto after = metabolic_budget(*successor, context.growth, context.environment); + const auto rules = rules_for(genome.development_version()); + if (!before || !after || !rules) { + return std::unexpected{MutationError::development}; + } + + MutationTransition transition{*successor, after->body, reserve, {}, {}}; + std::uint64_t added_matter = 0; + for (std::size_t channel = 0; channel < transition.body.matter.size(); ++channel) { + const auto old_mass = before->body.matter[channel].value; + const auto new_mass = after->body.matter[channel].value; + if (new_mass > old_mass) { + const auto amount = new_mass - old_mass; + if (amount > std::numeric_limits::max() - added_matter) { + return std::unexpected{MutationError::development}; + } + added_matter += amount; + transition.intake.matter[channel].value = amount; + } else { + transition.release.matter[channel].value = old_mass - new_mass; + } + } + + // Construction energy is charged for each channel's added material. The + // release from another channel cannot pay for construction or hide a missing + // nutrient; this matches channel-specific affordability in M3.3. + const auto per_thousand = rules->construction_per_kilogram; + const auto whole = added_matter / 1000; + const auto remainder = added_matter % 1000; + if ((whole != 0 && per_thousand > std::numeric_limits::max() / whole) || + (remainder != 0 && per_thousand > std::numeric_limits::max() / remainder)) { + return std::unexpected{MutationError::development}; + } + const auto whole_energy = whole * per_thousand; + const auto remainder_energy = remainder * per_thousand / 1000; + if (remainder_energy > std::numeric_limits::max() - whole_energy) { + return std::unexpected{MutationError::development}; + } + transition.intake.energy.value = whole_energy + remainder_energy; + if (reserve.energy.value < transition.intake.energy.value) { + return std::unexpected{MutationError::insufficient_funding}; + } + transition.reserve.energy.value -= transition.intake.energy.value; + for (std::size_t channel = 0; channel < transition.body.matter.size(); ++channel) { + const auto available = reserve.matter[channel].value; + const auto required = transition.intake.matter[channel].value; + const auto returned = transition.release.matter[channel].value; + if (available < required) { + return std::unexpected{MutationError::insufficient_funding}; + } + if (returned > std::numeric_limits::max() - (available - required)) { + return std::unexpected{MutationError::development}; + } + transition.reserve.matter[channel].value = available - required + returned; + } + return transition; +} } // namespace evo::biology diff --git a/tests/mutation_tests.cpp b/tests/mutation_tests.cpp index bb50131..4f82814 100644 --- a/tests/mutation_tests.cpp +++ b/tests/mutation_tests.cpp @@ -352,6 +352,54 @@ void successors_keep_their_parents_schema() { } } +void mutation_funding_is_exact_and_atomic() { + const auto parent = build(draft()); + const auto context_value = context(33, 8); + const auto offered = mutation_candidates(parent, context_value); + CHECK(offered); + constexpr Inventory reserve = pooled(1'000'000'000); + for (const auto& candidate : offered->candidates) { + const auto transition = + fund_mutation(parent, context_value, *offered, candidate.operator_id, 99, 42, reserve); + CHECK(transition); + const auto before = + metabolic_budget(parent, context_value.growth, context_value.environment); + CHECK(before); + for (std::size_t channel = 0; channel < reserve.matter.size(); ++channel) { + CHECK(before->body.matter[channel].value + reserve.matter[channel].value == + transition->body.matter[channel].value + + transition->reserve.matter[channel].value); + } + CHECK(reserve.energy.value - transition->reserve.energy.value == + transition->intake.energy.value); + CHECK(transition->successor.parents().size() == 1 && + transition->successor.parents().front() == parent.id()); + } + + // Acquiring a larger target-size capability needs construction matter and + // energy. Empty reserves refuse the proposal and leave the caller's balance + // unchanged. + bool checked_unfunded = false; + for (std::uint64_t seed = 1; seed <= 200 && !checked_unfunded; ++seed) { + const auto offer = mutation_candidates(parent, context(seed, 8)); + CHECK(offer); + for (const auto& candidate : offer->candidates) { + if (candidate.target != Capability::target_size || + candidate.effect != MutationEffect::adjust_up) { + continue; + } + constexpr Inventory empty{}; + const auto result = fund_mutation(parent, context(seed, 8), *offer, + candidate.operator_id, 99, 42, empty); + CHECK(!result && result.error() == MutationError::insufficient_funding); + CHECK(empty == Inventory{}); + checked_unfunded = true; + break; + } + } + CHECK(checked_unfunded); +} + int main() try { the_same_context_always_offers_the_same_candidates(); offers_are_canonical_and_unranked(); @@ -363,6 +411,7 @@ int main() try { invalid_contexts_are_refused(); every_eligible_operator_is_offered_and_none_is_favoured(); successors_keep_their_parents_schema(); + mutation_funding_is_exact_and_atomic(); std::cout << "PASS mutation catalog, uniform seeded offers and guarded selection\n"; return 0; } catch (...) {