6.5 KiB
[Reviewed]
ADR-0033: Seeded mutation candidates over a bounded operator catalog
Status
Adopted for M3.4 as the candidate-generation experiment GENOME_MODEL describes. It settles none of the rules that document leaves open: candidate count, context window, mutation costs as a game rule, inherited versus acquired expression, NPC mutation and recombination all remain undecided. Heredity history is M3.5.
Context
M3.3 gave capability a cost, but every genome is still authored by hand. Before
lineages can diverge, something has to propose a successor, and GENOME_MODEL is
specific about how: a constrained catalog of operators over capability records,
filtered by prerequisites, sorted by stable operator ID, sampled from a recorded
genome and context with an explicit stream, with no wall clock, no std::hash
and no implementation-defined distribution.
The named risk is a hidden deterministic best build, or offerings biased toward what would help. Either would turn mutation into a progression tree wearing a biological costume.
Decision
Add evo::biology::mutation_candidates and select_mutation over a static
catalog. Each operator has a stable ID and one of four effects on one capability:
adjust its parameter up or down, acquire a capability the genome lacks, or shed
one it carries. The adjustment step is one rule rather than a constant per
capability: a hundredth of that capability's declared range, at least one.
Eligibility is not a second rulebook. An operator is eligible when its own precondition holds and the genome it would produce passes the M3.1 validation unchanged. Prerequisites, required capabilities, ranges and the acyclic development graph are therefore enforced exactly once, where they were defined. Shedding a capability another one declares as a prerequisite fails that check by itself, with no rule written here to catch it.
Nothing is ranked. Candidates are drawn without replacement from the eligible set by rejection sampling on a SplitMix64 stream, so each eligible operator is exactly equally likely, and the result is returned sorted by operator ID. Position carries no meaning, there is no score anywhere in the record, and nothing about an organism's situation makes a helpful mutation more likely to be offered. Whether offerings should ever be environment-conditioned is a game-design question GENOME_MODEL leaves open, and this implementation does not open it.
The draw is seeded from the recorded context alone: the parent's content digest, an explicit seed and stream, the eligible event index, the organism's growth and environment, and the requested count. Two calls with the same context return identical candidates, so a retry cannot reroll; a new event index is what earns a new draw. Because the functions read nothing but the genome and that context, events elsewhere in a world cannot move a candidate set.
A candidate reports what the successor would be and what it would cost, and reserves nothing. Cost is not invented here: it is the successor's own maintenance and mass under ADR-0032, derived from the same rules as the parent's, so a candidate carries a consequence rather than a price this ADR made up.
An offer therefore records what produced it: the parent's identity and digest, and
the context itself. select_mutation compares those against the current ones
first, and only then regenerates the list. A candidate list cannot stand in for
that comparison, because a small catalog yields few distinct lists and two
different contexts draw the same one often; comparing lists alone would accept a
stale offer. A changed context is rejected outright rather than silently answered
with a different mutation. Because the context and parent then determine the draw,
a list that still differs means the offer itself was altered, which is reported as
its own error rather than as a context having moved. Only then is the immutable
successor built, with a caller-allocated identity, the parent recorded, and M3.1
validating it once more.
Alternatives Considered
Scoring or ordering candidates by any derived quantity would be the best-build failure directly, however it was labelled. Conditioning the draw on what an organism needs would make mutation anticipate its environment, which GENOME_MODEL explicitly refuses to claim. Re-implementing prerequisite checks in the catalog would let the two rulebooks drift. Clamping an adjustment at a range boundary would make two operators produce one result and offer no-ops as real choices. Plain modulo on the stream would bias the draw very slightly toward low operator IDs, which is exactly the accusation this increment must be able to refute. Letting selection substitute a still-valid candidate when the context moved would mean an organism mutating into something nobody was shown.
Benefits
Divergence becomes possible without a progression tree. Every offer is legitimate by the same validation that defines legitimacy, uniformity is exact rather than asymptotic, retries are stable, and a changed context fails loudly. The cost shown is the cost the rest of the system would charge.
Costs
Four effects over seven capabilities is a small catalog, and the shared range-fraction step means a capability's granularity follows its range rather than any biology. Eligibility runs validation once per operator per call, which is cheap here but is a full genome construction each time. Regenerating the whole list to select is deliberate duplicated work.
Risks
Do not read a candidate's reported maintenance or mass as a recommendation, a score or a price; it is what ADR-0032 would charge either way. Uniform offering is not a claim about real mutation rates, and the catalog is not a claim about which mutations are possible in biology. Nothing here decides whether NPCs mutate, whether acquired state is ever inherited, what a mutation should cost a player, or how often events occur. No organism mutates yet, and no fixture calls any of this.
Consequences
Test that the same context always yields the same candidates and a new event index yields a new draw, that offers are uniform across the eligible set over many seeds and cover it completely, that the returned order is always canonical, that every offered candidate produces a genome M3.1 accepts, that ineligible operators are never offered, that shedding a declared prerequisite is refused, that boundary adjustments are refused rather than clamped, that selection rejects an unknown candidate and any changed context, and that a successor records its parent and survives encoding. No genome schema, ledger, fixture, renderer or deployment changes.