Files
aevolution/docs/biology/GENOME_MODEL.md
T
dingoandClaude Opus 5 5497f4d74c Propose mutations without proposing a best build
M3.4 adds the candidate-generation experiment GENOME_MODEL describes: a
static catalog of four effects over the seven capabilities, drawn from a
recorded context with an explicit stream.

The named risk is a hidden best build or offerings biased toward what
would help, so the defence is structural rather than asserted. Nothing is
ranked: candidates are drawn without replacement by rejection sampling,
making every eligible operator exactly as likely as any other, and the
result is returned sorted by operator ID. No score exists in the record,
position carries no meaning, and nothing about an organism's situation
makes a helpful mutation more likely to be offered.

Eligibility is not a second rulebook. An operator is eligible when the
genome it would produce passes the M3.1 validation unchanged, so
prerequisites, required capabilities, ranges and the acyclic development
graph are enforced once, where they were defined. Shedding a capability
another declares as a prerequisite fails that check with no rule written
here to catch it. Range boundaries are refused rather than clamped, since
a clamp would make two operators agree and offer a no-op as a choice.

The draw reads the parent digest and the context and nothing else, so the
same context always returns the same candidates and a retry cannot
reroll; a new event index is what earns a new draw. select_mutation
regenerates the offer and refuses unless it still matches, so a changed
context is rejected rather than answered with a different mutation.

Cost is not invented: a candidate reports the successor's own maintenance
and mass under ADR-0032, and reserves nothing.

The eligible set is pinned by hand from the schema rather than observed,
and the uniformity check is confirmed to fail against a draw that takes
the first eligible operators. The rejection sampling that removes modulo
bias is correct by construction, not test-verified: at this scale the
bias is one part in 10^18. That is recorded rather than claimed.

No organism mutates and no fixture calls any of this. Candidate count,
mutation cost as a game rule, inherited versus acquired expression, NPC
mutation and recombination all remain open, as GENOME_MODEL requires.

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:27:21 -04:00

14 KiB

Genome, development and phenotype

Status: locked separation and evolutionary intent; recommended schema; mutation and morphology are experiments. No biology is implemented in the M0 proof.

flowchart LR
  G[Immutable developmental genome] --> D[Versioned development]
  E[Environment / resources / growth history] --> D
  D --> P[Phenotype revision]
  P --> C[Physical and biological components]
  C --> S[Simulation]
  S --> H[Reproduction / survival / history]

Genomes encode evolvable developmental capabilities, not literal DNA or an Animal/Plant/Fungus inheritance hierarchy. Classification is derived. Capability is distinct from realized structure: permitted armor still requires material and energy. Reconstructible phenotype caches require retained developmental inputs, including growth and damage history. Fitness is an outcome, not a power score.

Proposed genome field Invariant
genome_id Immutable world-scoped identity, distinct from runtime entity ID
schema and development-rule versions Explicit interpretation and migration boundaries
parents Zero only for documented founder; one initially; possible multiple parents later
origin_event_id Explains founder, mutation or reproduction origin
capabilities and parameters Canonical typed records with units, ranges and prerequisites
content_digest Integrity/deduplication aid; never merges distinct historical origins

Founder admission is a world event with inventory debited from a documented environmental or external genesis budget. Genome v0.1 covers energy conversion, membrane, movement, ingestion, reproduction, target size and tolerances only.

Contract Required behavior
ValidateGenome Reject unknown required capability, invalid range/dependency and cyclic development
PlanDevelopment Return bounded construction plan and resource requirements from genome/growth/environment
ApplyDevelopment Reserve resources; commit phenotype revision and matching transfers, or make no change
DerivePhenotype Produce dimensioned mass, geometry, maintenance and enabled component descriptions
GenerateMutationCandidates Genome + bounded recorded context + explicit stream/version → canonical candidates
SelectMutation Revalidate candidate, organism/genome revision and current context before immutable successor

A displayed candidate does not reserve resources. Changed context must reject or revalidate; never silently substitute a different mutation. Thicker membrane first changes thickness/composition; development derives construction mass, permeability/protection, movement and thermal consequences. Omitted physics is a documented model limitation, not an unrelated percentage modifier.

Candidate-generation experiment

Propose a constrained catalog of mutation operators over capability/parameter records. Filter by prerequisites, sort stable operator IDs, then sample bounded integer weights from recorded genome/context. This is an internal rule catalog, not a visible linear progression tree. Environment-conditioned offerings are a game-design proposal, not a claim that biological mutation anticipates needs.

Record seed, organism, eligible event index, context digest, rules and stream ID. Unrelated entity additions cannot change candidates. No wall clock, std::hash or implementation-defined distribution enters sampling. Store bounded context statistics; retries cannot obtain free rerolls. Candidate count, context window, costs, inherited/acquired expression, NPC mutation and recombination remain open before M3 mutation acceptance. No implementation silently settles these rules.

Later morphology and history

Evaluate typed body graphs with tissue/segment/organ nodes and distinct attachment, joint, vascular, neural and developmental edges. Independent consumers derive meshes, collisions, mass, maintenance and locomotion. Validate work/graph bounds, structural connectivity and resource feasibility. Development dependencies are acyclic or explicitly bounded; vascular cycles can be valid. Mesh validity alone does not prove biological viability. Intelligence remains one costly strategy.

Keep extinct genomes and ancestry indefinitely. Rule migrations preserve original records/provenance and are tested on cloned worlds. Unknown required capabilities fail closed. Tests cover canonical round trips, prerequisites, resource-limited development, deterministic candidates, stream independence, retry stability, bounded graph expansion, ancestry-preserving migration and material tradeoffs.

Implemented M3.1 genome record

ADR-0030 implements the record this document proposes, and nothing that reads it. evo::biology::Genome is validated once at construction and exposes no mutator, so an invalid genome cannot exist at runtime and callers never revalidate. GenomeDraft carries unvalidated input; create and decode apply identical semantic checks, so a decoded record is never less validated than a constructed one.

Schema 1 fixes the seven v0.1 capability kinds. Each has a unit, an inclusive parameter range, whether every genome must carry it, and the capabilities it mandates, all held as schema facts rather than record data, so no genome can contradict its own units. Energy conversion, membrane and target size are required. A capability record adds one u32 parameter and a bitmask of declared developmental edges; the union of declared and mandated edges must be acyclic.

Identity is a nonzero world-scoped genome ID distinct from every runtime identity, a nonzero origin event, and zero or one parent. Zero parents identifies a documented founder. The format reserves room for a second parent so recombination needs a schema version rather than a layout change. The byte layout, validation rules and digest semantics are in genome-v1.md.

Contract Status after M3.1
ValidateGenome Implemented for schema 1, at construction and at decode
PlanDevelopment Not started; M3.2
ApplyDevelopment Not started; M3.2
DerivePhenotype Not started; M3.2
GenerateMutationCandidates Not started; M3.4
SelectMutation Not started; M3.4

No genome affects any simulation. The M2 process fixtures still duplicate founder strategies verbatim and do not read this record; M3.3 connects capability to energetic cost. Nothing here decides mutation operators, inherited versus acquired expression, NPC divergence or recombination. A parameter within range is not a viable organism: validation proves neither developmental feasibility nor biological plausibility, and the schema ranges are expressible bounds rather than balance. Fitness remains an outcome, not a score held in the record.

Implemented M3.2 development and phenotype

ADR-0031 adds derive_phenotype and plan_development as pure functions over the M3.1 record. Nothing is stored: a phenotype is recomputed from retained inputs rather than cached, so a cached copy can always be checked against a recomputation.

GrowthState holds what an organism has built and what it has lost, in thousandths. EnvironmentState holds ambient temperature and the material a plan may draw on. Neither is written to the genome, and no function takes a mutable genome: damage changes the phenotype and leaves the content digest untouched, so heredity cannot carry acquired condition.

The genome's development version selects the rule set, and an unknown version fails closed. Version 1 declares every constant the derivation uses. The shape model is explicit: the body is a cube of uniform declared density, so extent is the exact integer cube root of volume and surface is six extents squared. Membrane mass is surface times the genome's thickness times membrane density. Maintenance is proportional to total mass plus a membrane upkeep term, so a thicker membrane costs more to hold. Uptake scales with surface against a declared reference, so size trades uptake against maintenance. A capability the genome does not carry yields zero for its component.

Contract Status after M3.2
ValidateGenome Implemented for schema 1, at construction and at decode
PlanDevelopment Implemented: bounded step, exact largest affordable, reserves nothing
ApplyDevelopment Half: a plan carries the growth state it would produce, but no transfer exists until M3.3
DerivePhenotype Implemented for rule version 1
GenerateMutationCandidates Not started; M3.4
SelectMutation Not started; M3.4

Omitted physics is a documented model limitation. Extent, maintenance and uptake are derived quantities, not balance, stats or a power score, and the constants must not become tuning by having been written down. Thermal shortfall is reported as a quantity; it is not a mortality, penalty or damage rule. A derived phenotype is not a viability claim. Repair is not modelled: a plan advances growth and never reduces damage. Nothing is spent or reserved, and no organism yet develops.

Implemented M3.3 metabolic budgets

ADR-0032 turns a phenotype into the budgets a ledger can hold: body composition, maintenance, movement, the next construction step, the per-tick intake limit and the reproduction investment. metabolism is the single place the genome's description of capability becomes accounting quantities; the record itself stays free of those types.

Each budget is derived from a different phenotype quantity on purpose. Maintenance follows total mass plus a membrane upkeep term, movement follows mass and speed, intake follows surface, construction follows the mass a growth step adds, and investment divides the body a parent already has. One genome parameter therefore moves some budgets and not others, by different amounts: a thicker membrane costs more matter to build, more energy to hold and more energy to haul, while changing neither uptake nor speed. Nothing here is a multiplier applied to a total, which is the capability-as-percentage-modifier failure this increment was scoped against.

Composition is declared per compartment, and membrane is the more carbon-rich one, so a thicker membrane changes what a body is made of and not only how much. A split assigns the first three channels by share and gives the remainder to the last, so parts always sum back to the whole and a derived body can be spent through the ledger without a rounding leak.

processes::consumer_for is the first path from a genome into the M2 fixtures. Opening inventory stays the caller's: a genome describes what an organism can do, never the resources it holds, and a derived config that invented an opening balance would create matter. No existing fixture reads genomes; that is M3.6.

The rule constants are chosen so budgets are of comparable magnitude, because budgets differing by orders of magnitude make every tradeoff invisible. That is a legibility choice for tests, not tuning, and must be re-derived before balancing. A budget is a derived quantity, not a rule: nothing here decides starvation, death or repair, and no organism spends any of it yet.

Implemented M3.4 mutation candidates

ADR-0033 implements the candidate-generation experiment this document describes, and only that. Four effects over the seven capabilities give a static catalog with stable IDs: adjust a parameter up or down by a hundredth of its declared range, acquire a capability the genome lacks, or shed one it carries.

Eligibility is not a second rulebook. An operator is eligible when the genome it would produce passes the M3.1 validation unchanged, so prerequisites, required capabilities, ranges and the acyclic graph are enforced once, where they were defined. Shedding a capability another declares as a prerequisite fails that check without a rule written for it.

Nothing is ranked. Candidates are drawn without replacement by rejection sampling on an explicit SplitMix64 stream, so every eligible operator is exactly as likely as any other, and the result is returned sorted by operator ID. No score exists in the record, position carries no meaning, and nothing about an organism's situation makes a helpful mutation more likely to be offered.

The draw reads the parent's content digest, a seed, a stream, an eligible event index, growth, environment and the requested count, and nothing else. The same context always returns the same candidates, so a retry cannot reroll; a new event index is what earns a new draw. select_mutation regenerates the offer and refuses unless it still matches exactly, so a changed context is rejected rather than answered with a different mutation. A candidate reports the successor's own maintenance and mass under ADR-0032 and reserves nothing.

Contract Status after M3.4
ValidateGenome Implemented for schema 1, and reused as the eligibility filter
PlanDevelopment Implemented: a proposal, narrowed by the composition layer
ApplyDevelopment Half: the transfer still does not exist
DerivePhenotype Implemented for rule version 1
GenerateMutationCandidates Implemented: uniform, canonical, context-recorded
SelectMutation Implemented: revalidates and refuses a changed context

Uniform offering is not a claim about real mutation rates, and the catalog is not a claim about which mutations are possible in biology. Candidate count, context window, mutation cost as a game rule, inherited versus acquired expression, NPC mutation and recombination all remain open, exactly as stated above. No organism mutates, no fixture calls any of this, and heredity history is M3.5.