Files
aevolution/docs/biology/GENOME_MODEL.md
T
dingoandClaude Opus 5.5 17fe23e5f0
Foundation / checks (deploy) (push) Successful in 3m32s
Foundation / checks (ecs) (push) Successful in 1m56s
Foundation / checks (client) (push) Successful in 12m56s
Foundation / checks (network) (push) Successful in 13m46s
Foundation / checks (tsan) (push) Successful in 7m59s
Foundation / checks (checks) (push) Successful in 33m36s
Foundation / checks (postgres) (push) Successful in 45m30s
Foundation / postgres-tools (push) Successful in 20s
Foundation / server-image (push) Successful in 25s
Foundation / image (push) Successful in 2m36s
M11.1: genome schema 2 with per-second rates (ADR-0099, segment 2)
Movement and ingestion are stored per second in schema 2 (ranges x20). Schema 1 records
stay valid, are never rewritten, and read as exactly x20 via Genome::per_second; drafts
default to schema 1 so existing literals keep their meaning. Development version 1
converts genome rates at its own 50 ms quantum (round down), so phenotypes are
unchanged. Mutation keeps the parent's schema and step; the lineage archive header names
exactly the highest schema held (all-schema-1 archives keep their bytes); the
development-v1 opening names schema 1. No golden changed; two tests that used 2 as an
unknown schema now use the next one. Refresh the dev session window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-09 13:16:55 -04:00

304 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
```mermaid
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](../adr/0030-immutable-genome-record.md) 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](../../schemas/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.
### Schema 2 (M11.1, ADR-0099)
Schema 2 states the movement and ingestion rates per second (×20 ranges), so biology
is no longer tied to the 50 ms tick. Schema 1 records stay valid and are never
rewritten. They read as exactly ×20 through `Genome::per_second`. Drafts default to
schema 1. Mutation keeps a lineage's schema. Development version 1 converts rates
back to its own 50 ms quantum, so nothing behaves differently.
See [genome-v2.md](../../schemas/genome-v2.md).
## Implemented M3.2 development and phenotype
[ADR-0031](../adr/0031-development-and-phenotype.md) 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](../adr/0032-metabolic-budgets-from-genome.md) 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](../adr/0033-seeded-mutation-candidates.md) 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, and no fixture calls any of this.
## Implemented M3.5 lineage retention
[ADR-0034](../adr/0034-lineage-archive.md) keeps what M3.4 produces. `LineageArchive`
has no removal operation: not a guarded one, not a private one. Retention is a
property of the interface rather than a rule anyone has to remember, which is the
only form of "keep extinct genomes indefinitely" that a later change cannot quietly
undo.
A genome is admitted only if its parent is already present, so ancestry never
dangles and the parent graph is acyclic by construction: a cycle would need one of
its members admitted before itself. Duplicate identities are refused rather than
overwritten, because overwriting is deletion wearing another name.
Organism identity and genome identity stay separate. Many organisms may carry one
genome; a birth names both, a death names only the organism, and death is terminal
for that organism and touches nothing about the genome. Ancestry, descendants and
divergence all resolve after every carrier has died.
The archive reports a lineage as living or absent, and has no third answer.
Absence means no organism now carries it, which the archive can establish about
itself. Terminal extinction is a policy judgement over a reconciled watermark
covering suspended members, eggs, spores and in-flight transfers, none of which
exist yet and none of which this type can see, so the word does not appear in the
API. Absence is also reversible: a lineage with no carrier can gain one again.
Capacity is bounded and admission fails loudly at the limit. Refusing to record is
not deleting; a silent drop would be. Durable storage, retention tiers and
cross-version migration are M7 and M8 work. M7.4b (ADR-0062) serializes the
whole archive canonically for history-capable region checkpoints. NPC
mutation stays undecided, because the archive records an origin event and never an
actor.
## What a genome decides, end to end
A genome now determines behaviour all the way into an ecosystem. `strategy_for`
turns a genome, a growth state and an environment into the same `StrategyConfig`
the episode driver already took, with intake, assimilation and reproduction
investment all read from the metabolic budget. A strategy is therefore what the
genome already implies, not a second description of the same organism, and a
parent reproduces once it holds what it would invest rather than clearing an
invented margin.
Where an environment acts is narrower than it first appears. Temperature enters
the derivation, through the phenotype's thermal shortfall. Resource level does
not enter it at all: an organism derived fully grown has an empty construction
transition, so the per-channel `available` inventory has nothing to bound, and
intake, assimilation and investment are unchanged by how much material surrounds
it. The resource level acts only on the ecology, as the nutrient pool bounding
what producers can build.
Reproduction is expensive in a specific, structural way. Intake scales with
surface area and investment with body mass, so the time to fund a birth by
feeding falls only as the cube root of mass and rises with the investment
fraction. Across the sizes the schema permits, a birth can be earned within a
plausible lifespan only near the schema's floor of one per thousand. That is a
property of the development and metabolism rules, not of any fixture, and whether
it is intended is an open question rather than a settled model.
Nothing in this path mutates an organism. Variants are diverged before a run and
compared as a fixed set, because an organism diverging on its own would settle NPC
mutation, which remains open.