128 lines
7.1 KiB
Markdown
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.
|