Files
aevolution/docs/biology/GENOME_MODEL.md
T
dingoandClaude Opus 5 8584eb1f6f Add the immutable genome v1 record and its canonical encoding
Open M3 with the record that development and mutation will read, in a new
evo::biology library that nothing else links yet. A genome is validated
once at construction and exposes no mutator, so an invalid one cannot
exist at runtime and callers never revalidate. A draft 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 range, whether every genome must carry it, and the capabilities
it mandates, all held as schema facts rather than record data, so no
record can contradict its own units. A capability adds one parameter and
a bitmask of declared developmental edges; the union of declared and
mandated edges must be acyclic, which seven nodes make exact and bounded.

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 so
recombination needs a schema version rather than a layout change.

The encoding follows ADR-0008: explicit little endian, bounded before any
allocation, an exact length match so trailing bytes are rejected, records
strictly ascending by kind so the bytes are canonical and duplicates fall
out of the same comparison, a stored digest recomputed on decode, and a
trailing checksum. The digest covers identity and ancestry, so identical
capabilities from different origins never share one. Neither value is an
authenticity claim. Unknown schema versions fail closed.

Tests cover ancestry rules, every declared range boundary from both
sides, self, mutual and three-node cycles, a cycle closed by a mandated
edge, truncation at every length, trailing and oversized buffers, every
single-byte corruption, and three resealed edits that reach the digest,
version and ordering checks rather than stopping at the checksum. One
branch is recorded as uncovered rather than given a test that cannot
fail: in schema 1 every mandated capability is also required.

No genome affects any simulation. Native Release, clang-tidy analysis,
ASan and format checks pass 17/17; golden d61ad5bf0c928c76 and ecosystem
fingerprint 2cd4a15f9fbe9949 are unchanged. Linux CI has not run yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-22 20:53:23 -04:00

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