Files
aevolution/schemas/genome-v1.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

3.3 KiB

Genome record, schema version 1

Scope: the immutable developmental record defined by ADR-0030 and shaped by GENOME_MODEL.md. Its encoder/decoder is src/biology/genome.cpp.

Not a network protocol, authenticated archive, event journal, production world format or durable storage implementation. It is not literal DNA, not a taxonomy and not a balance table. A future schema must preserve or explicitly migrate supported historical versions; unknown versions fail closed and no record is migrated in place.

Layout

All integers are little endian. Offsets assume P parents and N capability records. P is 0 or 1 in schema 1, with room reserved for 2. N is 1 to 7.

Offset Size Field
0 8 magic AEVOGEN1
8 4 schema version, 1
12 4 development rule version, nonzero and opaque to this schema
16 8 genome ID, nonzero and distinct from every runtime identity
24 8 origin event ID, nonzero
32 4 parent count P
36 8·P parent genome IDs
36+8P 4 capability record count N
40+8P 9·N capability records, strictly ascending by kind
40+8P+9N 8 content digest
48+8P+9N 8 FNV-1a checksum over every preceding byte

Each capability record is a u8 kind, a u32 parameter and a u32 prerequisite bitmask, in that order. Total size is 56 + 8P + 9N bytes: 83 for a founder carrying the three required capabilities, 135 at the maximum, and never more than max_genome_bytes (256).

Capabilities

Kinds are ordered 0 to 6: energy conversion, membrane, movement, ingestion, reproduction, target size, thermal tolerance. The unit, inclusive range, whether every genome must carry the kind, and the capabilities it mandates are schema facts held in capability_schema and are never encoded, so no record can contradict its own units. Energy conversion, membrane and target size are required in schema 1. A prerequisite bit outside the known kinds is rejected.

Validation

Decoding applies the same semantic checks as construction, so a decoded record is never less validated than a constructed one. Sizes and counts are bounded before any allocation, and the length must match exactly, so trailing bytes are rejected rather than ignored.

Rejected: unknown schema version, unknown capability kind or prerequisite bit, a missing required capability, duplicate or non-ascending kinds, a parameter outside its range, a prerequisite naming an absent capability, any cycle in the union of declared and mandated developmental edges, a zero identity or origin, a zero development version, more than one parent, and a parent that is zero, repeated or the genome itself.

Digest and checksum

The digest covers the whole body, identity and ancestry included, so two genomes with identical capabilities but different origins never share one. It is an integrity and deduplication aid, never a content-identity key across origins. It is stored and recomputed on decode, and a mismatch is rejected, which catches a record edited in place or partially migrated.

The trailing checksum detects accidental corruption only. Neither value is a cryptographic or authenticity claim, and neither substitutes for the other: they answer record consistency and transport corruption respectively.