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
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:
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 (...) {
|
||||
|
||||
Reference in New Issue
Block a user