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