diff --git a/docs/adr/0030-immutable-genome-record.md b/docs/adr/0030-immutable-genome-record.md index 03686d3..e75be44 100644 --- a/docs/adr/0030-immutable-genome-record.md +++ b/docs/adr/0030-immutable-genome-record.md @@ -27,6 +27,13 @@ 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 @@ -104,6 +111,12 @@ 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, diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index f1aed45..7ef1f13 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -400,6 +400,31 @@ closure, which is tested. A later schema that mandates a capability without requiring it would exercise the remaining branch; this is recorded rather than covered by a test that could not fail. +Review of `8584eb1` found two defects (2026-09-22). First, `Genome` had implicit +move operations, so moving one emptied the source's capabilities while leaving +its identity, origin and digest intact: a record that still reported ID 7 but +whose encoded bytes no longer decoded. That contradicted the documented invariant +directly. The type is now copy-only, which suppresses the implicit moves so a +move decays to a copy, and the invariant holds for every operation. The new move +tests were confirmed to fail without the fix: the Debug and ASan builds exit 1 at +runtime, and the Release build does not compile at all, because MSVC proves the +moved-from comparison always throws and rejects the unreachable code under +warnings-as-errors. clang-tidy then flagged the deliberate decaying moves in the +tests as `performance-move-const-arg`; those two lines carry a NOLINT explaining +that the decay is the contract under test. + +Second, 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. Every structural byte was verified by hand against +schemas/genome-v1.md before being frozen: magic, both versions, ID 7, origin 1, +zero parents, three records, kinds 0/1/5 with parameters 400/120/5000, and the +`56 + 9N` length. The digest `9b2cdedef16ac87f` and the trailing checksum are +computed values frozen alongside them. The fixture is asserted in both +directions: the encoder must still produce those bytes, and the decoder must +still read them into the expected record. It is a golden and must not be edited +to make a test pass. + No genome affects any simulation, and nothing links the new library except its own tests. The M2 process fixtures still duplicate founder strategies and do not read the record. Development, phenotype derivation, mutation, recombination, diff --git a/include/evo/biology/genome.hpp b/include/evo/biology/genome.hpp index a75f38d..e73fa93 100644 --- a/include/evo/biology/genome.hpp +++ b/include/evo/biology/genome.hpp @@ -93,6 +93,13 @@ class Genome { [[nodiscard]] static std::expected create(const GenomeDraft& draft); [[nodiscard]] static std::expected decode(std::span bytes); + // Copy-only on purpose. A moved-from record would keep its identity, origin + // and digest while losing its capabilities, which is precisely the invalid + // genome 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 that is cheap. + Genome(const Genome&) = default; + Genome& operator=(const Genome&) = default; [[nodiscard]] std::vector encode() const; [[nodiscard]] std::uint64_t id() const noexcept { return id_; diff --git a/tests/genome_tests.cpp b/tests/genome_tests.cpp index 442ca3a..cfbbb13 100644 --- a/tests/genome_tests.cpp +++ b/tests/genome_tests.cpp @@ -5,6 +5,8 @@ #include #include #include +#include +#include #include namespace { @@ -270,6 +272,74 @@ void encoded_record_rules() { const auto overfull = Genome::decode(crowded); CHECK(!overfull && overfull.error() == GenomeError::invalid_ancestry); } +// A frozen schema 1 record for the founder above, verified by hand against +// schemas/genome-v1.md. Changing these bytes changes the meaning of every +// existing v1 record: it needs a schema version and a migration, not an edit. +const std::vector& frozen_founder() { + static const std::vector bytes{ + 0x41, 0x45, 0x56, 0x4f, 0x47, 0x45, 0x4e, 0x31, // magic AEVOGEN1 + 0x01, 0x00, 0x00, 0x00, // schema version 1 + 0x01, 0x00, 0x00, 0x00, // development version 1 + 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // genome ID 7 + 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // origin event 1 + 0x00, 0x00, 0x00, 0x00, // no parents: a founder + 0x03, 0x00, 0x00, 0x00, // three capabilities + 0x00, 0x90, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // conversion 400 + 0x01, 0x78, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // membrane 120 + 0x05, 0x88, 0x13, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // target size 5000 + 0x7f, 0xc8, 0x6a, 0xf1, 0xde, 0xde, 0x2c, 0x9b, // content digest + 0x0b, 0xb0, 0xaa, 0xf8, 0x3c, 0x76, 0x83, 0xec}; // checksum + return bytes; +} + +void frozen_record_compatibility() { + const auto genome = Genome::create(founder()); + CHECK(genome); + // The encoder must still produce the bytes a v1 record was written with. + CHECK(genome->encode() == frozen_founder()); + CHECK(frozen_founder().size() == 56 + 9 * 3); + CHECK(genome->content_digest() == 0x9b2cdedef16ac87fULL); + // The decoder must still read them, independently of what the encoder does. + const auto restored = Genome::decode(frozen_founder()); + CHECK(restored); + CHECK(restored->id() == 7 && restored->origin_event() == 1); + CHECK(restored->schema_version() == 1 && restored->development_version() == 1); + CHECK(restored->parents().empty()); + CHECK(restored->capabilities().size() == 3); + CHECK(restored->capabilities()[0] == (CapabilityRecord{Capability::energy_conversion, 400, 0})); + CHECK(restored->capabilities()[1] == (CapabilityRecord{Capability::membrane, 120, 0})); + CHECK(restored->capabilities()[2] == (CapabilityRecord{Capability::target_size, 5'000, 0})); + CHECK(restored->content_digest() == 0x9b2cdedef16ac87fULL); + CHECK(*restored == *genome); +} + +void moves_preserve_validity() { + const auto original = Genome::create(founder()); + const auto other = Genome::create(descendant()); + CHECK(original && other); + // Moves decay to copies, so a moved-from record is still a whole genome + // rather than an identity with no capabilities. + auto source = *original; + // The decay to a copy is the contract under test, so tidy is right that no + // move happens here and wrong that it is a mistake. + // NOLINTNEXTLINE(performance-move-const-arg) + const auto moved = std::move(source); + CHECK(moved == *original); + // NOLINTNEXTLINE(bugprone-use-after-move): the point of the check. + CHECK(source == *original); + CHECK(source.capabilities().size() == 3 && source.id() == 7); + CHECK(Genome::decode(source.encode())); + auto target = *original; + auto donor = *other; + // NOLINTNEXTLINE(performance-move-const-arg) + target = std::move(donor); + CHECK(target == *other); + // NOLINTNEXTLINE(bugprone-use-after-move): the point of the check. + CHECK(donor == *other); + CHECK(Genome::decode(donor.encode())); + static_assert(std::is_copy_constructible_v); + static_assert(std::is_copy_assignable_v); +} } // namespace int main() try { founders_and_ancestry(); @@ -278,6 +348,8 @@ int main() try { development_graph_rules(); canonical_encoding(); encoded_record_rules(); + frozen_record_compatibility(); + moves_preserve_validity(); std::cout << "PASS genome schema, ancestry, development graph and canonical encoding\n"; return 0; } catch (...) {