Add funded cellular mutation proposal
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (checks) (push) Failing after 43s
Foundation / checks (ecs) (push) Successful in 1m57s
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 (postgres) (push) Canceled after 53s
Foundation / checks (client) (push) Canceled after 2m59s
Foundation / checks (network) (push) Canceled after 2m19s

This commit is contained in:
dingo
2026-10-11 02:42:53 -04:00
parent b7f3d73980
commit 84efa4bf14
6 changed files with 264 additions and 3 deletions
@@ -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.
+51
View File
@@ -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.
+19 -2
View File
@@ -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.
+23 -1
View File
@@ -45,13 +45,27 @@ struct MutationOffer {
std::vector<MutationCandidate> 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<Genome, MutationError>
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<MutationTransition, MutationError>
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
+68
View File
@@ -217,4 +217,72 @@ select_mutation(const Genome& genome, const MutationContext& context, const Muta
}
return *successor;
}
std::expected<MutationTransition, MutationError>
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<std::uint64_t>::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<std::uint64_t>::max() / whole) ||
(remainder != 0 && per_thousand > std::numeric_limits<std::uint64_t>::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<std::uint64_t>::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<std::uint64_t>::max() - (available - required)) {
return std::unexpected{MutationError::development};
}
transition.reserve.matter[channel].value = available - required + returned;
}
return transition;
}
} // namespace evo::biology
+49
View File
@@ -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 (...) {