Two defects from review of 8584eb1.
Genome had implicit move operations, so moving one emptied the source's
capabilities while leaving its identity, origin and digest intact. The
result still reported its ID but no longer encoded to decodable bytes,
which contradicts the documented invariant that an invalid genome cannot
exist. Declaring the copy operations suppresses the implicit moves, so a
move decays to a copy and the invariant holds for every operation. The
record is at most seven capabilities and one parent, so the copy is cheap.
The move tests were confirmed to fail without the fix: Debug and ASan
exit 1 at runtime, and Release does not compile, because MSVC proves the
moved-from comparison always throws and rejects the unreachable code.
clang-tidy then flagged the deliberate decaying moves; those lines carry
a NOLINT explaining that the decay is the contract under test.
The encoding tests compared the current encoder against the current
decoder, so a coordinated change to layout or digest would have passed
while breaking existing v1 records. A frozen 83-byte fixture now holds
one schema 1 founder record, asserted in both directions: the encoder
must still produce those bytes and the decoder must still read them. Every
structural byte was verified by hand against schemas/genome-v1.md before
freezing. It is a golden, not a value to update when a test fails.
Native Release, clang-tidy analysis, ASan and format checks pass 17/17.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
127 lines
7.1 KiB
Markdown
127 lines
7.1 KiB
Markdown
# 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.
|