Files
aevolution/docs/adr/0033-seeded-mutation-candidates.md
T
dingoandClaude Opus 5 badd28fe9b Check the context an offer records, not the list it produced
Selection established that a context was unchanged by regenerating the
candidate list and comparing it. That cannot establish it. Four of nine
operators is only 126 distinct lists, so different contexts draw the same
one routinely, and an offer from event 1 was accepted under event 239.

An offer now records what produced it: the parent's identity and digest,
and the context itself. Selection compares those directly, before
anything else. Because the context and parent then determine the draw, a
list that still differs means the offer itself was altered, which is now
reported as its own error rather than as a context having moved.

The regression searches for a context whose draw collides with the
offer's and asserts that such a collision exists rather than assuming
one, then requires selection to reject it. It was confirmed to fail
against the previous implementation.

One expectation of mine was wrong and is now stated correctly: rewriting
an offer's recorded context to name the colliding one is accepted, and
should be. Those candidates genuinely are what that context draws, so the
result is a legitimate offer for it rather than a forgery. The check is
that the recorded context matches the current one, not provenance.
Editing a candidate remains caught, as an altered offer.

Native Release, clang-tidy analysis, ASan and format checks pass 20/20.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-23 15:37:13 -04:00

118 lines
6.5 KiB
Markdown

# 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.