Files
aevolution/docs/adr/README.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

2.0 KiB
Raw Blame History

Architecture decision records

Locked requirements outrank these records. Review architecture, ADRs, public contracts, tests, then implementation. Stop expanding implementation on conflict.

Adopted for proof applies only to the bounded initial headless slice. Proposed recommends without adopting a dependency. Deferred requires a named experiment. Later Accepted and Superseded preserve rationale. Proof choices do not silently settle gameplay or production infrastructure.

Records 0001–0015 cover language, build, dependencies, tests/benchmarks, ECS, ticks, randomness, serialization, units, errors, threads, logging, PostgreSQL, messaging and metrics. 0016–0019 cover durability/ownership, networking/security, infrastructure and voxels. 0020 scopes Gitea delivery and the stateless dev Job. Each record has the eight required sections. 0021 authorizes the opt-in ECS comparison only, not a production dependency. 0022 adopts the bounded sequential lifecycle-command scheduler for the proof. 0023 defines local periodic neighborhood queries and a measured linear baseline. 0024 adopts finite, typed energy/matter inventory transfers for M2.1. 0025 scopes finite capture, growth recipes and residual accounting for M2.2. 0026 adds shared community ownership and bounded synthetic feeding for M2.3. 0027 adds terminal inventory ownership and budgeted nutrient return for M2.4. 0028 adopts funded reproduction, bounded slot capacity and retained lineage IDs. 0029 scopes the deterministic ecosystem driver and bounded measured episodes. 0030 adopts the immutable genome v1 record, validation and canonical encoding.

Every dependency adoption records exact version/commit and integrity hash, transitive license obligations, maintenance/security review, owner and removal boundary. Candidate performance and binary-size comparisons are hypotheses until benchmarked. Primary sources were reviewed during the initial September 2026 design. No unadopted candidate is a link dependency of the proof.