Files
aevolution/docs/adr/0030-immutable-genome-record.md
T
2026-10-08 12:08:53 -04:00

128 lines
7.1 KiB
Markdown

[Reviewed]
# ADR-0030: Immutable genome v1 record and canonical encoding
## Status
Adopted for M3.1. Development, phenotype derivation, mutation candidates,
heredity operations and any coupling to the M2 process fixtures are out of scope
and remain M3.2 through M3.5. No gameplay balance is selected.
## Context
M2 closed with founder strategies duplicated verbatim from parent to child, so
nothing heritable exists and lineages differ only by their founder. Before
development or mutation can be written, the record they read must exist: a
versioned, validated, immutable description of developmental capability, with
ancestry that outlives its organisms and an encoding that is canonical enough to
compare across platforms and reject malformed input.
GENOME_MODEL fixes the shape of that record and the two failure modes to avoid:
literal DNA, and an Animal/Plant/Fungus style inheritance hierarchy. It also
leaves mutation, recombination, NPC divergence and multi-parent heredity open.
## Decision
Add an `evo::biology` library holding one value type, `Genome`, constructed only
through validation and exposing no mutator. A `GenomeDraft` carries unvalidated
input; `Genome::create` either returns a validated record or an error, and
`decode` applies the identical semantic checks to bytes. There is no way to hold
an invalid `Genome`, so callers never revalidate.
That claim requires the type to be copy-only. An implicit move would empty the
source's capabilities while leaving its identity, origin and digest intact, which
is exactly the invalid record this type exists to make unrepresentable. Declaring
the copy operations suppresses the implicit moves, so a move decays to a copy.
The record is at most seven capabilities and one parent, so the copy is cheap and
the invariant holds for every operation rather than all but two.
Genome v1 fixes seven capability kinds, matching the v0.1 list in GENOME_MODEL:
energy conversion, membrane, movement, ingestion, reproduction, target size and
thermal tolerance. These are capabilities, not genes, organs or species. A static
schema table gives each kind its unit, inclusive parameter range, whether every
genome must carry it, and the capabilities it mandates being present. The unit is
a schema fact and is never encoded, so no record can contradict its own units.
Energy conversion, membrane and target size are required in every v1 genome.
A capability record is a kind, one u32 parameter and a u32 bitmask of declared
prerequisites. Declared prerequisites are developmental ordering the genome
asserts; mandated prerequisites are schema facts. Validation rejects an unknown
capability bit or kind, a duplicate kind, a parameter outside its declared range,
a prerequisite naming a capability the genome does not carry, a missing required
or mandated capability, and any cycle in the union of declared and mandated
edges. Seven nodes make that closure exact and bounded.
Ancestry is immutable and separate from every runtime identity. A genome carries
a nonzero world-scoped ID distinct from the process and entity IDs of earlier
increments, a nonzero origin event explaining founder, mutation or reproduction
origin, and zero or one parent. The format reserves room for two so later
recombination needs a schema version rather than a layout change; v1 rejects more
than one. A parent may be neither zero, nor the genome itself, nor repeated.
The encoding follows ADR-0008: explicit little endian, an `AEVOGEN1` magic, fixed
u32 schema and development versions, the identity and ancestry fields, then
capability records sorted strictly ascending by kind, a content digest and a
trailing FNV-1a checksum. Strict ascending order makes the encoding canonical and
rejects duplicates in the same comparison. Sizes and counts are validated against
`max_genome_bytes` before any allocation, and an exact length match is required,
so trailing bytes are rejected rather than ignored.
The content digest covers the whole body, identity and ancestry included, so two
genomes with identical capabilities but different origins never share a digest.
It is an integrity and deduplication aid, never a content-identity key across
origins. It is stored and also recomputed on decode, and a mismatch is rejected:
the digest and the checksum answer different questions, record consistency and
accidental corruption, and neither is an authenticity claim.
Unknown schema versions fail closed. A genome is never migrated in place.
## Alternatives Considered
Literal nucleotide sequences would need an expression model no contract defines
and would make every range check meaningless. A capability class hierarchy would
bake the taxonomy GENOME_MODEL forbids into the type system. Deriving the digest
on demand instead of storing it would lose the record-consistency check that
catches a hand-edited or partially migrated record. Typed accounting units in the
parameters would couple the genome to the ledger before M3.3 has decided how
capability maps to energetic cost. A general graph with arbitrary node counts
would make cycle detection unbounded for no v1 benefit.
## Benefits
An invalid genome cannot exist at runtime. Capability, range and dependency
errors are caught once, at the boundary, with a named reason. Ancestry survives
encoding and is independent of every runtime identity. The bytes are canonical,
bounded and comparable across platforms, so later development and mutation work
starts from a record whose validity is already established.
## Costs
Seven fixed kinds and one u32 parameter each cannot express a capability with
several dimensions; that needs a schema version. The required set and the ranges
are chosen constants. Storing the digest costs eight bytes and one consistency
rule. Multi-parent heredity is reserved but not implemented.
## Risks
Do not read capability parameters as balance, stats or a power score: fitness is
an outcome. A parameter within range is not a viable organism, and validation
proves neither developmental feasibility nor biological plausibility. The schema
ranges must not become gameplay tuning by having been written down. Nothing here
decides mutation operators, inherited versus acquired expression, NPC divergence
or recombination, and no genome yet affects any simulation.
## Consequences
A frozen fixture holds the exact bytes of one schema 1 record, verified by hand
against the documented layout. Round trips alone compare the current encoder with
the current decoder, so a coordinated change to layout or digest would pass every
such test while invalidating existing records. The fixture is a golden: changing
it needs a schema version and a migration, not an edit.
Test canonical round trips, byte-exact encoding stability, strict ordering,
truncation, trailing bytes, corrupted checksums, digest mismatch, unsupported and
zero versions, unknown capability kinds and prerequisite bits, duplicates,
every range boundary, missing required and mandated capabilities, self and mutual
and longer prerequisite cycles, and every ancestry rule. No snapshot format,
process fixture, database, renderer or deployment changes. The M1 particle codec
does not serialize genomes, and M3.2 development must not mutate this record.