diff --git a/docs/adr/0108-cellular-checkpoint-profile.md b/docs/adr/0108-cellular-checkpoint-profile.md index 61213bc..7a1cc83 100644 --- a/docs/adr/0108-cellular-checkpoint-profile.md +++ b/docs/adr/0108-cellular-checkpoint-profile.md @@ -3,9 +3,10 @@ ## Status Accepted M11.3 engineering direction (2026-10-10). This is an additive format -contract; it does not change gameplay constants selected by ADR-0098. Snapshot -and restore implementation is in progress; SQL validation, durable tick -publication and recovery fault tests remain incomplete. +contract; it does not change gameplay constants selected by ADR-0098. The +in-memory snapshot/restore codec and portable profile-4 manifest allowlist are +implemented; SQL validation, durable tick publication and recovery fault tests +remain incomplete. ## Context diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index 7dc9a8c..a52c2d4 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -162,6 +162,11 @@ scoped change before starting the next segment. and inventory invariants, and rejects malformed, wrong-identity, wrong-tick, corrupt, unsupported and noncanonical state. Durable profile admission, publication and recovery remain open. +- 11.3d-2: portable manifest v2 now assigns profile 4, pins the cellular rule, + envelope, habitat, coordinate, genome, development, founder and archive + versions, applies the 16 MiB cap, restores through the owner codec, and + refuses profile-4 cloning. PostgreSQL admission and durable publication + remain open. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index dee5759..a70afce 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -6064,3 +6064,20 @@ compile/run; Debug CTest `cellular-lives-owner` (1/1 passed); and `git diff --check`. `clang-format` and `clang-tidy` are unavailable on the Windows PATH. PostgreSQL profile admission, publication/recovery tests, Linux sanitizers and CI remain pending; the codec is not yet durably playable. + +## 2026-10-10 — M11.3d-2 portable profile-4 manifest (CI pending) + +Manifest v2 now recognizes cellular-lives-v1 as profile 4, applies its 16 MiB +payload cap, pins cellular rules/envelope/habitat/coordinate/genome/development/ +founder/archive versions in dedicated in-memory fields, and restores payloads +through the profile-4 owner validator. Profile-4 clone genesis is refused; +profile-3 behavior and bytes remain unchanged. The focused test covers profile-4 +genesis encode/decode, payload restore, version refusal, identity/length +rejection, clone refusal and a progressing successor manifest. + +Executed locally: warning-as-error MSVC 19.44 Debug and Release/NDEBUG compile +and run, Debug CTest `region-checkpoint-contracts` (1/1 passed), and +`git diff --check`. CMake/Ninja again idled without starting compilation, so the +focused target was compiled and linked directly with the available build +artifacts. `clang-format` and `clang-tidy` are not available on PATH. PostgreSQL +admission, durable publication/recovery, sanitizer and CI checks remain pending. diff --git a/include/evo/persistence/region_checkpoint.hpp b/include/evo/persistence/region_checkpoint.hpp index 81fd6d1..c6f4a44 100644 --- a/include/evo/persistence/region_checkpoint.hpp +++ b/include/evo/persistence/region_checkpoint.hpp @@ -3,6 +3,7 @@ #include "evo/persistence/region_lease.hpp" #include "evo/processes/environmental_community.hpp" #include "evo/processes/lineage_region.hpp" +#include "evo/server/lifecycle/cellular_lives.hpp" #include "evo/server/lifecycle/primitive_batch.hpp" #include #include @@ -22,11 +23,13 @@ enum class CheckpointProfile : std::uint8_t { environmental_v1 = 1, // Environmental envelope only; history_profile 0. environmental_lineage_v1 = 2, // LineageRegion container; history_profile 1. primitive_lives_v1 = 3, // Funded creation state; history_profile 2. + cellular_lives_v1 = 4, // Complete cellular state; history_profile 3. }; // history_profile 1: lineage archive format 1 with genome schema 1. inline constexpr std::uint32_t lineage_history_profile = 1; // Archive format 1, genome schema 2, development 2, founder-life rules 1. inline constexpr std::uint32_t primitive_history_profile = 2; +inline constexpr std::uint32_t cellular_history_profile = 3; // Declared durability, verified at deployment. Development: one volume, no host-loss claim. enum class DurabilityPolicy : std::uint8_t { unknown = 0, single_volume_development = 1 }; @@ -40,6 +43,12 @@ struct VersionBundle { inline constexpr VersionBundle environmental_v1_versions{}; // No field or terrain state in this explicitly provisioned nursery profile. inline constexpr VersionBundle primitive_v1_versions{1, 1, 1, 0, 0, 1, 1, 1, 1}; +struct CellularVersionBundle { + std::uint32_t rules{1}, envelope{1}, habitat{1}, coordinate{1}, genome{1}, development{2}, + founder{1}, archive{1}; + friend bool operator==(const CellularVersionBundle&, const CellularVersionBundle&) = default; +}; +inline constexpr CellularVersionBundle cellular_v1_versions{}; // Batch evidence bound by manifest v2 (ADR-0063); all zero at genesis. struct BatchDigests { @@ -67,6 +76,7 @@ struct CheckpointManifest { std::uint64_t epoch{}; std::uint64_t tick_microseconds{}; VersionBundle versions{}; + CellularVersionBundle cellular_versions{}; Sha256Digest build{}; // Retained immutable build artifact identity. std::uint32_t rng_streams{}; // These rules use no randomness: 0. std::uint32_t history_profile{}; // 0 environmental; 1 lineage; 2 primitive lives. @@ -86,6 +96,7 @@ inline constexpr std::size_t max_lineage_payload_bytes = processes::max_lineage_ return profile == CheckpointProfile::environmental_v1 ? max_environmental_payload_bytes : profile == CheckpointProfile::environmental_lineage_v1 ? max_lineage_payload_bytes : profile == CheckpointProfile::primitive_lives_v1 ? server::max_primitive_lives_bytes + : profile == CheckpointProfile::cellular_lives_v1 ? server::max_cellular_lives_bytes : 0; } inline constexpr std::uint64_t max_checkpoint_ticks = 64; @@ -146,4 +157,7 @@ restore_lineage_payload(std::span payload, const CheckpointM [[nodiscard]] std::expected, CheckpointError> restore_primitive_payload(std::span payload, const CheckpointManifest& manifest); +[[nodiscard]] std::expected, CheckpointError> +restore_cellular_payload(std::span payload, + const CheckpointManifest& manifest); } // namespace evo::persistence diff --git a/schemas/region-commit.md b/schemas/region-commit.md index 12079cc..ef3dcb5 100644 --- a/schemas/region-commit.md +++ b/schemas/region-commit.md @@ -1,9 +1,10 @@ # Region commit manifest contract v1 (M7.1 design, M7.4a encoding) M11.2 adds the portable [primitive creation profile 3](primitive-checkpoint-v1.md) -using manifest v2. Its history, versions, payload and trace rules differ from the -environmental profiles below. Schema v15 does not yet admit profile 3; guarded -atomic publication is a separate migration requirement. +using manifest v2. M11.3 adds profile 4, the +[cellular lives profile](cellular-lives-v1.md), with its own version bundle, +payload bound and restore validator. These formats do not change profiles 1–3. +PostgreSQL admission and atomic publication are separate migration requirements. ## Canonical manifest encoding v1/v2 (ADR-0061, ADR-0063) @@ -17,7 +18,7 @@ record, and each commit row stores it. |---|---|---| | 0 | 8 | magic `AEVORCM1` | | 8 | 4 | manifest_version = 1 (other values are unsupported) | -| 12 | 4 | profile: 1 = environmental-v1, 2 = environmental-lineage-v1 (ADR-0062) | +| 12 | 4 | profile: 1 = environmental-v1, 2 = environmental-lineage-v1, 3 = primitive-lives-v1, 4 = cellular-lives-v1 | | 16 | 24 | world, region, frame (nonzero u64 each) | | 40 | 16 | commit_id (nonzero; globally unique in the database) | | 56 | 8 | commit_sequence | @@ -27,12 +28,12 @@ record, and each commit row stores it. | 128 | 16 | lease holder (zero only at genesis) | | 144 | 8 | lease epoch (0 only at genesis) | | 152 | 8 | tick_microseconds (nonzero; fixed for the region) | -| 160 | 36 | nine u32 versions: rules 2, envelope 2, resources/fields/terrain/coordinate/generator/material/interval-adapter 1 | +| 160 | 36 | nine u32 versions: environmental/primitive bundles as below; profile 4 has cellular rules, envelope, habitat, coordinate, genome, development, founder, archive, then reserved zero | | 196 | 32 | retained build identity (nonzero; `retained_builds` row required) | | 228 | 4 | rng_streams = 0 (these rules use no randomness) | -| 232 | 4 | history_profile: 0 with profile 1; 1 (lineage archive 1 + genome schema 1) with profile 2 | +| 232 | 4 | history_profile: 0 with profile 1; 1 with profile 2; 2 with profile 3; 3 with profile 4 | | 236 | 4 | durability_policy = 1 (single-volume development) | -| 240 | 8 | payload_bytes: profile 1 is 1..1 MiB; profile 2 is 1..4,268,144 | +| 240 | 8 | payload_bytes: profile 1 is 1..1 MiB; profile 2 is 1..4,268,144; profile 3 is 1..3,266,800; profile 4 is 1..16 MiB | | 248 | 32 | payload SHA-256 (nonzero) | | 280 | 8 | v2: trace bytes, exactly 96 + 304·(end_tick − begin_tick); 0 at genesis | | 288 | 32 | v2: trace SHA-256 (nonzero except at genesis) | @@ -43,6 +44,12 @@ record, and each commit row stores it. A structurally invalid record is malformed (SQL 22023). A record that parses but has an unsupported version, profile, RNG, history or durability declaration is unsupported (EVL06). Values above 255 are never truncated onto a supported enum. +Profile 4 pins cellular rules/envelope/habitat/coordinate/genome/development/ +founder/archive as eight u32s, with the ninth version word zero. Its tick +quantum is 50,000 μs; its v2 trace retains the standard 96 + 304·tick encoding, +and its decision block is transactionally bound like other progressing profiles. +Profile 4 clone genesis is unsupported until cellular identity remapping is +specified. Profile 3 retains its creation-only trace and zero-decision rules. Profile 2 payloads are schemas/environmental-lineage-v1.md containers. A region never changes profile, history, RNG or durability declarations; schema v4 enforces this against the predecessor. For profile 1, the payload is the exact diff --git a/src/persistence/region_checkpoint.cpp b/src/persistence/region_checkpoint.cpp index 9574741..c6f13dd 100644 --- a/src/persistence/region_checkpoint.cpp +++ b/src/persistence/region_checkpoint.cpp @@ -1,5 +1,6 @@ #include "evo/persistence/region_checkpoint.hpp" #include +#include #include namespace evo::persistence { @@ -59,9 +60,15 @@ bool structural(const CheckpointManifest& m) noexcept { return false; const auto& b = m.batch; const bool primitive = m.profile == CheckpointProfile::primitive_lives_v1; + const bool cellular = m.profile == CheckpointProfile::cellular_lives_v1; + if ((!cellular && m.cellular_versions != cellular_v1_versions) || + (cellular && m.versions != environmental_v1_versions)) + return false; if (primitive && (m.manifest_version != 2 || m.tick_microseconds != 50000 || b.decision_count != 0 || !zero(b.decisions_sha256))) return false; + if (cellular && (m.manifest_version != 2 || m.tick_microseconds != 50000)) + return false; if (m.manifest_version != 1 && m.manifest_version != 2) return false; const bool no_batch = b == BatchDigests{}; @@ -70,8 +77,8 @@ bool structural(const CheckpointManifest& m) noexcept { b.trace_bytes == 0 && zero(b.trace_sha256); if (zero(m.predecessor_commit) && zero(m.predecessor_digest)) return genesis && m.end_tick == 0 && no_batch; - // Primitive cloning needs explicit life-binding remapping; not admitted yet. - if (primitive) + // Primitive and cellular cloning need explicit identity remapping; not admitted yet. + if (primitive || cellular) return false; // Clone genesis (ADR-0067, v2 only): the origin is the source commit and // manifest digest; the block digests inherited permanent outcomes. @@ -104,6 +111,11 @@ bool supported(const CheckpointManifest& m) noexcept { return m.manifest_version == 2 && m.history_profile == primitive_history_profile && m.versions == primitive_v1_versions && m.tick_microseconds == 50000 && m.rng_streams == 0 && m.durability == DurabilityPolicy::single_volume_development; + if (m.profile == CheckpointProfile::cellular_lives_v1) + return m.manifest_version == 2 && m.history_profile == cellular_history_profile && + m.cellular_versions == cellular_v1_versions && + m.versions == environmental_v1_versions && m.tick_microseconds == 50000 && + m.rng_streams == 0 && m.durability == DurabilityPolicy::single_volume_development; const bool profile = (m.profile == CheckpointProfile::environmental_v1 && m.history_profile == 0) || (m.profile == CheckpointProfile::environmental_lineage_v1 && @@ -134,9 +146,16 @@ encode_manifest(const CheckpointManifest& m) { w.bytes(m.holder); w.u(m.epoch, 8); w.u(m.tick_microseconds, 8); - for (const auto v : {m.versions.rules, m.versions.envelope, m.versions.resources, + const auto versions = + m.profile == CheckpointProfile::cellular_lives_v1 + ? std::array{m.cellular_versions.rules, m.cellular_versions.envelope, + m.cellular_versions.habitat, m.cellular_versions.coordinate, + m.cellular_versions.genome, m.cellular_versions.development, + m.cellular_versions.founder, m.cellular_versions.archive, 0U} + : std::array{m.versions.rules, m.versions.envelope, m.versions.resources, m.versions.fields, m.versions.terrain, m.versions.coordinate, - m.versions.generator, m.versions.material, m.versions.interval_adapter}) + m.versions.generator, m.versions.material, m.versions.interval_adapter}; + for (const auto v : versions) w.u(v, 4); w.bytes(m.build); w.u(m.rng_streams, 4); @@ -181,10 +200,18 @@ decode_manifest(std::span bytes) { m.holder = r.bytes<16>(); m.epoch = r.u(8); m.tick_microseconds = r.u(8); - for (auto* v : {&m.versions.rules, &m.versions.envelope, &m.versions.resources, - &m.versions.fields, &m.versions.terrain, &m.versions.coordinate, - &m.versions.generator, &m.versions.material, &m.versions.interval_adapter}) - *v = static_cast(r.u(4)); + std::array versions{}; + for (auto& v : versions) + v = static_cast(r.u(4)); + if (m.profile == CheckpointProfile::cellular_lives_v1) { + m.cellular_versions = {versions[0], versions[1], versions[2], versions[3], versions[4], + versions[5], versions[6], versions[7]}; + if (versions[8] != 0) + return std::unexpected{CheckpointError::format}; + } else { + m.versions = {versions[0], versions[1], versions[2], versions[3], versions[4], + versions[5], versions[6], versions[7], versions[8]}; + } m.build = r.bytes<32>(); m.rng_streams = static_cast(r.u(4)); m.history_profile = static_cast(r.u(4)); @@ -218,6 +245,10 @@ genesis_manifest(RegionKey key, std::uint64_t frame, Uuid commit, std::uint64_t m.history_profile = primitive_history_profile; m.versions = primitive_v1_versions; } + if (profile == CheckpointProfile::cellular_lives_v1) { + m.history_profile = cellular_history_profile; + m.cellular_versions = cellular_v1_versions; + } m.key = key; m.frame = frame; m.commit = commit; @@ -234,7 +265,8 @@ std::expected clone_manifest(const CheckpointManifest& source, const Sha256Digest& source_digest, RegionKey target, Uuid commit, std::uint64_t payload_bytes, const Sha256Digest& payload_sha256, const BatchDigests& inherited) { - if (!supported(source) || source.profile == CheckpointProfile::primitive_lives_v1) + if (!supported(source) || source.profile == CheckpointProfile::primitive_lives_v1 || + source.profile == CheckpointProfile::cellular_lives_v1) return std::unexpected{CheckpointError::unsupported}; if (!structural(source) || target.world == source.key.world || commit == source.commit || inherited.trace_bytes != 0 || !zero(inherited.trace_sha256)) @@ -362,4 +394,23 @@ restore_primitive_payload(std::span payload, const Checkpoin return std::unexpected{CheckpointError::payload}; return std::move(*restored); } + +std::expected, CheckpointError> +restore_cellular_payload(std::span payload, const CheckpointManifest& m) { + if (!structural(m)) + return std::unexpected{CheckpointError::format}; + if (!supported(m) || m.profile != CheckpointProfile::cellular_lives_v1) + return std::unexpected{CheckpointError::unsupported}; + if (payload.size() != m.payload_bytes) + return std::unexpected{CheckpointError::payload}; + auto restored = server::CellularLives::restore(payload, m.key.world, m.key.region, m.frame, + m.end_tick); + if (!restored) + return std::unexpected{restored.error() == server::CellularLivesError::version + ? CheckpointError::unsupported + : CheckpointError::payload}; + if (m.sequence == 0 && (!(*restored)->lives().empty() || !(*restored)->corpses().empty())) + return std::unexpected{CheckpointError::payload}; + return std::move(*restored); +} } // namespace evo::persistence diff --git a/tests/region_checkpoint_tests.cpp b/tests/region_checkpoint_tests.cpp index bdc425b..e2b77e6 100644 --- a/tests/region_checkpoint_tests.cpp +++ b/tests/region_checkpoint_tests.cpp @@ -399,6 +399,54 @@ void primitive_profile() { CHECK(mismatched_ids && (*mismatched_ids)->spawn(r, {12, 13, 14, 15, {5}})); CHECK(!restore_primitive_payload((*mismatched_ids)->snapshot(), *n)); } + +void cellular_profile() { + using namespace evo::biology; + using namespace evo::server; + auto endowment = primitive_endowment(); + CHECK(endowment); + auto funding = endowment->body; + funding.energy.value = endowment->reserve.energy.value + endowment->construction.value; + auto primitive = PrimitiveLives::create({7, 3, 9, 17, funding, {{0, 0}}}); + CHECK(primitive); + auto habitat = CellularHabitat::create({7, 3, 9, 1'000, 1'000, {}}); + CHECK(habitat); + auto owner = CellularLives::create(**primitive, std::move(*habitat), {{1'000, 1'000}, 0, 293'150}); + CHECK(owner && (*owner)->lives().empty() && (*owner)->tick() == 0); + + const auto payload = (*owner)->snapshot(); + auto manifest = genesis_manifest(key, 9, filled<16>(0x02), 50000, build, payload.size(), + filled<32>(0xA2), CheckpointProfile::cellular_lives_v1); + CHECK(manifest && supported(*manifest) && manifest->history_profile == cellular_history_profile && + manifest->cellular_versions == cellular_v1_versions && + max_payload_bytes(CheckpointProfile::cellular_lives_v1) == max_cellular_lives_bytes); + const auto encoded = encode_manifest(*manifest); + CHECK(encoded && decode_manifest(*encoded) == *manifest); + const auto restored = restore_cellular_payload(payload, *manifest); + CHECK(restored && (*restored)->snapshot() == payload); + CHECK(!restore_primitive_payload(payload, *manifest)); + const auto successor = successor_manifest(*manifest, filled<32>(0xA5), filled<16>(0x04), + lease(), 1, build, payload.size(), + filled<32>(0xA6), batch_for(1, 1)); + CHECK(successor && supported(*successor) && + successor->cellular_versions == cellular_v1_versions); + const auto clone = clone_manifest(*manifest, filled<32>(0xA3), {8, 3}, filled<16>(0x03), + payload.size(), filled<32>(0xA4), {}); + CHECK(!clone && clone.error() == CheckpointError::unsupported); + + auto bad_versions = *manifest; + ++bad_versions.cellular_versions.archive; + CHECK(!supported(bad_versions)); + CHECK(!restore_cellular_payload(payload, bad_versions)); + auto bad_identity = *manifest; + bad_identity.key.region = 4; + const auto wrong_identity = restore_cellular_payload(payload, bad_identity); + CHECK(!wrong_identity && wrong_identity.error() == CheckpointError::payload); + auto wrong_length = *manifest; + ++wrong_length.payload_bytes; + const auto length_result = restore_cellular_payload(payload, wrong_length); + CHECK(!length_result && length_result.error() == CheckpointError::payload); +} } // namespace int main() { @@ -410,6 +458,7 @@ int main() { lineage_profile(); clone_genesis(); primitive_profile(); + cellular_profile(); std::puts("region checkpoint contracts passed"); return 0; } catch (const std::exception& e) {