diff --git a/CMakeLists.txt b/CMakeLists.txt index c31cdd6..4e4766f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -715,6 +715,16 @@ if(BUILD_TESTING) "-DTEST_DIR=${CMAKE_CURRENT_BINARY_DIR}/inheritance-replay-restart" -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/cellular_population_restart.cmake") set_tests_properties(cellular-inherited-replay-process-restart PROPERTIES TIMEOUT ${evo_cohort_timeout}) + add_executable(evo-cellular-inheritance-checkpoint-tests tests/cellular_inheritance_checkpoint_tests.cpp) + target_link_libraries(evo-cellular-inheritance-checkpoint-tests PRIVATE evo::region_checkpoint) + evo_owned_target(evo-cellular-inheritance-checkpoint-tests) + add_test(NAME cellular-inherited-checkpoint-upgrade COMMAND evo-cellular-inheritance-checkpoint-tests) + set_tests_properties(cellular-inherited-checkpoint-upgrade PROPERTIES TIMEOUT ${evo_cohort_timeout}) + add_test(NAME cellular-inherited-upgrade-process-restart COMMAND "${CMAKE_COMMAND}" + "-DPOPULATION_TEST=$" + "-DTEST_DIR=${CMAKE_CURRENT_BINARY_DIR}/inheritance-upgrade-restart" + -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/cellular_population_restart.cmake") + set_tests_properties(cellular-inherited-upgrade-process-restart PROPERTIES TIMEOUT ${evo_cohort_timeout}) add_executable(evo-cellular-maturation-tests tests/cellular_maturation_tests.cpp) target_link_libraries(evo-cellular-maturation-tests PRIVATE evo::lifecycle) evo_owned_target(evo-cellular-maturation-tests) diff --git a/README.md b/README.md index 2974ada..518b2d9 100644 --- a/README.md +++ b/README.md @@ -218,6 +218,12 @@ trace 4 with owner 8/rules 10; old defaults remain trace 3. Build results with direct execution, including same-tick selection/birth. This is a portable prerequisite for durable admission. +The [portable inheritance checkpoint upgrade](schemas/cellular-inheritance-upgrade.md) +defines raw bundle 12 and an exact no-tick transformation from bundle 11. Build +`evo-cellular-inheritance-checkpoint-tests`; CTest covers the manifest/payload +contract and its separate-process reproduction. SQL publication and population +support remain subsequent work. + M5.1 local voxel/address API and scope: [local voxel contract](docs/world/LOCAL_VOXEL_CONTRACT.md). M5.8 process restart proof and measured costs: [world proof](docs/engineering/WORLD_PROOF.md). diff --git a/deploy/kubernetes/region/dev-session-route/listener.yaml b/deploy/kubernetes/region/dev-session-route/listener.yaml index db5be1e..4df2fb0 100644 --- a/deploy/kubernetes/region/dev-session-route/listener.yaml +++ b/deploy/kubernetes/region/dev-session-route/listener.yaml @@ -12,7 +12,7 @@ spec: env: - {name: REGION_SESSION, value: "dev"} - {name: REGION_SESSION_LISTEN, value: "0.0.0.0:7400"} - - {name: REGION_SESSION_WINDOW, value: "dev-20261019T180417-2aacb0ba:1792447457"} + - {name: REGION_SESSION_WINDOW, value: "dev-20261019T181708-5ae9e40b:1792448228"} - {name: REGION_M10_MAX_GRANT_LIFETIME, value: "14400"} ports: # QUIC (ADR-0090): UDP only; nothing listens on TCP 7400. diff --git a/docs/STATUS.md b/docs/STATUS.md index caf659b..f4a4882 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,5 +1,21 @@ # Project status and next steps +## Portable retained-plan checkpoint upgrade - 2026-10-19 + +[ADR-0167](adr/0167-retained-plan-checkpoint-upgrade.md) defines raw-only bundle +12 and an explicit no-tick upgrade from bundle 11. It restores the complete +source, preserves expressed mutations, funded descendants, inventories, presence +and archive history, and initializes each offspring plan from its expressed +genome. The checkpoint restores and continues through raw trace 4. No genesis, +skipped prerequisites, repeats or population conversion are admitted. + +Full MSVC/GCC Release suites pass **89/89**. Analysis, formatting and focused +ASan/UBSan pass; separate-process upgrade proof bytes agree across compilers. +[Validation](engineering/VALIDATION.md) records exact evidence and limitations. +This is portable reader/upgrade support. SQL and fenced durable publication, +population/census/migration admission, control succession, retained NPC behavior +and choice UI remain open; M12 is still in progress. + ## Portable inherited-plan replay - 2026-10-19 [ADR-0166](adr/0166-retained-plan-replay-traces.md) adds raw trace 4 exclusively diff --git a/docs/adr/0167-retained-plan-checkpoint-upgrade.md b/docs/adr/0167-retained-plan-checkpoint-upgrade.md new file mode 100644 index 0000000..21824e8 --- /dev/null +++ b/docs/adr/0167-retained-plan-checkpoint-upgrade.md @@ -0,0 +1,77 @@ +# ADR-0167: Explicit retained-plan checkpoint upgrade + +## Status and scope + +Accepted portable checkpoint prerequisite for ADR-0163/0165/0166, 2026-10-19. +No SQL admission, automatic upgrade, provisioning mode, population support, +control handoff, NPC behavior policy or live deployment. + +## Context + +Owner 8/rules 10 and raw trace 4 now have qualified portable codecs and replay. +Bundle 11 still names owner 7/rules 9. Labeling the new state with that tuple or +creating a new opening would lose the meaning of retained biology and ancestry. +An explicit checkpoint contract is required before fenced durable admission. +Population/census/migration semantics for viable unexpressed plans remain open. + +## Decision + +Define raw-only cellular bundle 12 as `(10,8,2,1,1,4,3,2,1)`: rules, owner, +habitat, coordinates, genome, development, founder, archive and mutation state. +The raw profile remains 4, history profile 4, quantum 50 ms and manifest layout +360 bytes. Owner 8 contains the new plan references/history; archive 2 retains +its expressed-body meaning. Mutation offer layout is unchanged. Continuation +uses raw trace 4. Old tuples, trace defaults and successful bytes stay unchanged. + +The sole upgrade is an explicit raw bundle 11 -> 12 no-tick candidate. Require +a supported, structurally valid raw predecessor at positive tick/sequence, +nonzero predecessor digest, distinct result commit, next sequence without wrap, +same-frame nonzero lease, build and bounded payload binding. Preserve identity, +profile, history, quantum and tick. Empty batch evidence marks this boundary; +an ordinary successor inherits its existing tuple and cannot perform an upgrade. +No genesis, skipped prerequisite, repeated upgrade, downgrade or profile change. + +Restore the entire bundle-11 source and invoke ADR-0165's exact detached owner +upgrade. Preserve all expressed genomes, stocks, boundary flows, presence, +positions, growth/damage, mutation offers and archives. Initialize each local +living/corpse plan to its current expressed genome; invent no past selections. +The full candidate must restore canonically under the target manifest, and +future recorded biology must remain raw bundle 12 with trace 4. + +Portable `supported()` means reader support, not database or publication +authority. The caller must independently verify manifest/payload SHA-256 +bindings and current durable head/lease. These pure functions perform no I/O, +hashing, allocation reservation or publication. Existing SQL entry points and +their version allowlists are unchanged; no durable upgrade adapter is added. +The eventual durable segment must retain both exact manifests/objects, derive +the same complete target on recovery, reject pending intervals/handoffs, fence +the atomic evidence/result/head operation and qualify retries and crashes. + +Bundle 12 has no population envelope mapping. Profile conversion, population +successors, migration and census must continue to refuse it. No terminal +extinction may be inferred from missing projection support. Legacy revision +bundle helpers remain the trace-3 admission set; the new raw reader handles +bundle 12 explicitly so existing durable consumers do not silently opt in. + +## Alternatives, consequences and risks + +Reusing bundle 11 changes retained save meaning; new genesis loses opening stock +history; upgrading a population before plan viability semantics are defined would +silently change census and migration. A separate raw tuple permits a bounded +reviewable prerequisite while preserving those boundaries. + +Risks are mistaken publication authority, cross-version payload confusion and +lost legacy expression/offer history. Exact pair checks, full source restore and +canonical target comparison address the portable risks. Durable faults and +unexpressed-plan viability require subsequent integration; this closes no M12 +product or persistence gate by itself. + +## Qualification + +Require real retained organisms, legacy expressed revisions and funded offspring, +unchanged source bytes, exact target equality with the owner upgrade, canonical +manifest/payload restore and trace-4 continuation. Refuse malformed bindings, +wrong profiles/tuples, sequence exhaustion, genesis, repeats and old/new payload +mislabeling. A fresh process must derive identical complete manifest/payload +proof bytes from the retained source. Run Release/NDEBUG, analysis, formatting +and relevant ASan/UBSan; do not replace existing goldens. diff --git a/docs/adr/README.md b/docs/adr/README.md index 17f69d3..f471369 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -1,5 +1,7 @@ # Architecture decision records +- [ADR-0167: Explicit retained-plan checkpoint upgrade](0167-retained-plan-checkpoint-upgrade.md) - portable raw-only bundle 12 and exact no-tick bundle-11 source transformation; SQL/durable admission and population support remain separate. + - [ADR-0166: Retained-plan replay traces](0166-retained-plan-replay-traces.md) - explicit raw trace 4 for owner 8/rules 10, inherited-offer action matching and complete-result replay; durable admission remains separate. - [ADR-0165: Retained cellular offspring plans](0165-retained-cellular-offspring-plans.md) - portable owner format 8/rules 10 keeps expressed bodies separate from earned inherited plans, repeated births and selection history; durable/control/UI integration pending. diff --git a/docs/architecture/PERSISTENCE_ARCHITECTURE.md b/docs/architecture/PERSISTENCE_ARCHITECTURE.md index 2e7f1ad..2a17992 100644 --- a/docs/architecture/PERSISTENCE_ARCHITECTURE.md +++ b/docs/architecture/PERSISTENCE_ARCHITECTURE.md @@ -1,5 +1,12 @@ # Persistence and region authority +[ADR-0167](../adr/0167-retained-plan-checkpoint-upgrade.md) defines portable +raw-only bundle 12 and the explicit no-tick bundle-11 -> 12 checkpoint candidate. +Full source restore preserves expressed biology/history while initializing +retained offspring plans. Reader support is separate from SQL publication; +there is no population mapping, automatic upgrade or new durable entry point. +See [the portable upgrade contract](../../schemas/cellular-inheritance-upgrade.md). + [ADR-0166](../adr/0166-retained-plan-replay-traces.md) adds portable raw trace 4 exclusively for the retained-plan owner 8/rules 10. Replay and action matching preserve expressed/inherited meanings and return outcomes only after the entire diff --git a/docs/biology/REPRODUCTION_MODEL.md b/docs/biology/REPRODUCTION_MODEL.md index f5f6f4b..b5bb6ef 100644 --- a/docs/biology/REPRODUCTION_MODEL.md +++ b/docs/biology/REPRODUCTION_MODEL.md @@ -52,7 +52,9 @@ needs to distinguish traits that can also change during an existing life. Existi durable bundles, census, population and migration refuse the new owner until their plan semantics are qualified. [Trace 4](../../schemas/cellular-region-batch-v4.md) supplies portable replay and inherited-offer action matching; old traces refuse -this owner. The birth-time control choice, +this owner. [Bundle 12](../../schemas/cellular-inheritance-upgrade.md) supplies +its portable raw checkpoint and exact retained-source upgrade; SQL publication +is still separate. The birth-time control choice, persistent NPC behavior and UI remain unimplemented; default/DEV rules do not opt into this owner. diff --git a/docs/engineering/M12_REMAINING_GATES.md b/docs/engineering/M12_REMAINING_GATES.md index 084fc0e..98186bf 100644 --- a/docs/engineering/M12_REMAINING_GATES.md +++ b/docs/engineering/M12_REMAINING_GATES.md @@ -19,7 +19,9 @@ closure. [ADR-0165](../adr/0165-retained-cellular-offspring-plans.md) adds porta retained plans and earned selections, unchanged expressed parents and repeated funded births. [ADR-0166](../adr/0166-retained-plan-replay-traces.md) adds portable raw trace-4 replay, action matching and exact process restart. Existing same-genome -behavior remains. Durable plan/trace/bundle, +behavior remains. [ADR-0167](../adr/0167-retained-plan-checkpoint-upgrade.md) defines +the portable raw checkpoint tuple and exact retained-source upgrade. Durable +plan/trace/bundle admission, population/migration/census admission, the in-life expression catalog, authority handoff and NPC/UI integration are still required. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 8dc14ca..04320e5 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -1,5 +1,58 @@ # Validation report +## 2026-10-19 - Portable retained-plan checkpoint upgrade + +[ADR-0167](../adr/0167-retained-plan-checkpoint-upgrade.md) adds raw-only bundle +12 and the exact bundle-11 -> 12 manifest/payload candidate. The new tuple has +portable reader support, no genesis or population mapping, and no SQL admission. +Legacy revision/trace admission helpers remain unchanged. The payload operation +restores the whole source before invoking the detached owner upgrade; an ordinary +successor preserves bundle 12 and biological continuation requires trace 4. + +Executed locally: + +- MSVC 19.44 Release full CTest **89/89 passed, 22.32 s**, with NDEBUG. +- GCC 14.2 Release full CTest **89/89 passed, 17.33 s**, with NDEBUG. +- Clang 19.1 Debug new checkpoint/actual process-restart tests **2/2 passed, + 2.28 s**, built with clang-tidy 19 enabled. Both changed implementations and + the test compiled under analysis; repository clang-format 19 and diff checks + pass. No golden or existing biological rule was changed. +- Clang 19.1 ASan/UBSan region checkpoints, inherited checkpoint upgrade, upgrade + process restart and population checkpoints **4/4 passed, 26.86 s**, without + reports. +- Optional GCC persistence and session consumers rebuilt; the session adapter + test passed **1/1, 0.14 s**. No new durable admission was enabled. + +The finite-food fixture acquires an actual legacy expressed mutation, produces +funded offspring and suspends its parent before the upgrade. It checks unchanged +source bytes/manifests, equality with the full owner-upgrade oracle, retained +archive/stock/identities/presence and initial plans matching current expressed +genomes rather than immutable birth genomes. Continuation resumes the parent, +earns/consumes a real plan offer, compares direct execution to trace-4 replay, +and restores each resulting bundle-12 checkpoint. No state is replenished. + +Tests refuse skipped/repeated upgrades, unknown history, sequence exhaustion, +zero/reused commit or digest/build bindings, invalid holder/epoch/frame, payload +bounds, corrupt/truncated source bytes, genesis, population admission and old/new +payload mislabeling. Manifest fields and the complete target re-encode exactly. +The process test saves a source owner and manifest, then a fresh process derives +the complete target manifest plus payload. MSVC and GCC proof bytes share SHA-256 +`ee8fdf41a4fc132581cea2c74788f6517414a9444bb36efeda763beccafb1f11`. +That concatenation is a test comparison artifact, not a new production codec. + +These tests use opaque nonzero digest inputs to exercise the storage-free API. +They do not verify cryptographic source binding, a committed database chain or +publication authority. The caller must independently hash/verify both immutable +manifests/objects and enforce the current head/lease. SQL schema, durable upgrade +and publication adapters are unchanged. No private database fault suite, live +deployment, target-host, TSan, actual-days, client/UI or M12 completion evidence +is claimed. Fenced admission/recovery and plan viability remain subsequent work. + +The refreshed DEV window expires **2026-10-19 22:17:08 UTC**. Rendered deployment +policy passes: 75 objects in 74 files, 138 rendered objects in 17 overlays, zero +failures. The unchanged policy self-test matrix was not repeated. No deployment +or World0 operation occurred; unrelated untracked work was preserved. + ## 2026-10-19 - Portable retained-plan trace replay [ADR-0166](../adr/0166-retained-plan-replay-traces.md) adds explicit raw trace 4 diff --git a/include/evo/persistence/region_checkpoint.hpp b/include/evo/persistence/region_checkpoint.hpp index d8be0b3..aaa974c 100644 --- a/include/evo/persistence/region_checkpoint.hpp +++ b/include/evo/persistence/region_checkpoint.hpp @@ -73,6 +73,8 @@ inline constexpr CellularVersionBundle cellular_v9_versions{8, 6, 2, 1, 1, 4, 3, inline constexpr CellularVersionBundle cellular_v10_versions{8, 7, 2, 1, 1, 4, 3, 2, 1}; // ADR-0158: explicit funded maturation, retaining owner 7 and population envelope 2. inline constexpr CellularVersionBundle cellular_v11_versions{9, 7, 2, 1, 1, 4, 3, 2, 1}; +// ADR-0167: portable raw-only retained plans. SQL/publication admission is separate. +inline constexpr CellularVersionBundle cellular_v12_versions{10, 8, 2, 1, 1, 4, 3, 2, 1}; // Zero means this bundle has no population representation. [[nodiscard]] constexpr std::uint32_t population_envelope_version(const CellularVersionBundle& b) noexcept { @@ -80,7 +82,8 @@ population_envelope_version(const CellularVersionBundle& b) noexcept { : (b == cellular_v10_versions || b == cellular_v11_versions) ? 2 : 0; } -// Bundles with genome revisions: the revision history profile and format-3 traces. +// Legacy revision bundles using history profile 4 and format-3 traces. +// Bundle 12 is intentionally excluded: it requires separate trace-4 admission. [[nodiscard]] constexpr bool cellular_revision_bundle(const CellularVersionBundle& b) noexcept { return b == cellular_v3_versions || b == cellular_v4_versions || b == cellular_v5_versions || b == cellular_v6_versions || b == cellular_v7_versions || b == cellular_v8_versions || @@ -242,6 +245,17 @@ cellular_maturation_upgrade_manifest(const CheckpointManifest& predecessor, [[nodiscard]] std::expected, CheckpointError> cellular_maturation_upgrade_payload(std::span payload, const CheckpointManifest& predecessor); +// ADR-0167: explicit raw-only bundle 11 -> 12 retained-plan candidate, no tick. +// Caller verifies SHA-256 source/target bindings and durable authority separately. +[[nodiscard]] std::expected +cellular_inheritance_upgrade_manifest(const CheckpointManifest& predecessor, + const Sha256Digest& predecessor_digest, Uuid commit, + const LeaseGrant& lease, const Sha256Digest& build, + std::uint64_t payload_bytes, + const Sha256Digest& payload_sha256); +[[nodiscard]] std::expected, CheckpointError> +cellular_inheritance_upgrade_payload(std::span payload, + const CheckpointManifest& predecessor); // Population manual conversion may publish at the same tick with a nonempty trace. [[nodiscard]] std::expected population_successor_manifest( const CheckpointManifest& predecessor, const Sha256Digest& predecessor_digest, Uuid commit, diff --git a/schemas/cellular-inheritance-upgrade.md b/schemas/cellular-inheritance-upgrade.md new file mode 100644 index 0000000..51a2482 --- /dev/null +++ b/schemas/cellular-inheritance-upgrade.md @@ -0,0 +1,45 @@ +# Portable retained-plan checkpoint upgrade + +Authority: [ADR-0167](../docs/adr/0167-retained-plan-checkpoint-upgrade.md). +Bundle 12 is exactly +`{rules=10,envelope=8,habitat=2,coordinate=1,genome=1,development=4,founder=3,archive=2,mutation_state=1}`. +It is raw profile 4/history 4 only, with the unchanged 360-byte manifest and +50,000-microsecond quantum. [Owner 8](cellular-lives-v8.md) stores the additional +plan references/history; [raw trace 4](cellular-region-batch-v4.md) records its +subsequent biological steps. Legacy trace defaults and version tuples remain. + +Only a supported, structurally valid, non-genesis raw bundle-11 predecessor at +positive tick may derive a bundle-12 candidate. Require nonzero predecessor +digest, a distinct nonzero commit, next sequence without wrap, a same-frame +nonzero holder/epoch and valid build/payload bindings. The result preserves +world, region, frame, profile, history, quantum and biological tick. Its exact +predecessor reference is retained and batch evidence is empty. No skipped +prerequisite, downgrade, repeated upgrade or bundle-12 genesis exists. + +The payload operation fully restores the source under its declared manifest and +uses the detached owner-7/rules-9 -> owner-8/rules-10 upgrade. Preserve all +expressed bodies/genomes, inventories, growth/damage, position, habitat, heat, +nursery, source provenance, archive revisions/births/deaths, boundary flows, +presence and standing offers. Initialize local living/corpse offspring plans to +their current expressed genome and retain no invented plan selections. The +complete target must restore canonically under the result tuple. Ordinary +successors retain bundle 12; biological continuation requires trace 4. + +These functions are portable and storage-free. They validate structure, owner +identity/tick and canonical biology, but do not compute or verify SHA-256 values, +contact a database, reserve identities or grant authority. The I/O caller must +independently verify both manifest and object digest bindings before relying on +the result. `supported()` describes reader support only. Legacy revision-bundle +helpers remain the trace-3 admission set and exclude bundle 12. + +No population envelope maps to bundle 12. Profile transitions, population +successors/restore, census and migration remain unsupported for this owner. +Missing or unsupported projections cannot establish zero life or extinction. +SQL schema and C++ durable upgrade/publication adapters are unchanged; neither +portable candidate function is a new durable entry point. + +The next durable segment must admit this exact pair through fenced atomic +evidence/result/head publication, retain both complete manifests and payloads, +rederive the target on recovery, refuse pending intervals/handoffs and qualify +exact retries, stale writers, ambiguous outcomes and process/storage failures. +No worker or DEV/default opening selects bundle 12 automatically. diff --git a/schemas/cellular-lives-v8.md b/schemas/cellular-lives-v8.md index 46c4420..d30877e 100644 --- a/schemas/cellular-lives-v8.md +++ b/schemas/cellular-lives-v8.md @@ -2,7 +2,9 @@ Authority: [ADR-0165](../docs/adr/0165-retained-cellular-offspring-plans.md). Portable opt-in format 8/rules 10 only. [Raw trace 4](cellular-region-batch-v4.md) -now supplies portable replay. No existing durable bundle, population envelope, +supplies portable replay; [bundle 12](cellular-inheritance-upgrade.md) supplies +the portable raw checkpoint tuple and retained-source upgrade. No existing SQL +admission, population envelope, migration or census adapter admits this version. Earlier canonical formats and their meanings are unchanged. diff --git a/schemas/cellular-region-batch-v4.md b/schemas/cellular-region-batch-v4.md index b48321f..70da267 100644 --- a/schemas/cellular-region-batch-v4.md +++ b/schemas/cellular-region-batch-v4.md @@ -2,7 +2,8 @@ Authority: [ADR-0166](../docs/adr/0166-retained-plan-replay-traces.md). This is a portable raw-owner trace, paired exclusively with owner format 8/rules 10. -Existing durable bundles and population traces do not admit it. The default +[Portable bundle 12](cellular-inheritance-upgrade.md) names this raw checkpoint; +existing SQL bundles and population traces do not admit it. The default cellular trace remains format 3. Formats 1-3 keep their successful canonical bytes and earlier biological meanings. diff --git a/src/persistence/population_checkpoint.cpp b/src/persistence/population_checkpoint.cpp index 3603271..32314a8 100644 --- a/src/persistence/population_checkpoint.cpp +++ b/src/persistence/population_checkpoint.cpp @@ -171,4 +171,30 @@ cellular_maturation_upgrade_payload(std::span payload, const CheckpointManifest& previous) { return upgrade_payload(payload, previous, true); } +std::expected +cellular_inheritance_upgrade_manifest(const CheckpointManifest& previous, + const Sha256Digest& previous_digest, Uuid commit, + const LeaseGrant& lease, const Sha256Digest& build, + std::uint64_t bytes, const Sha256Digest& digest) { + if (previous.profile != CheckpointProfile::cellular_lives_v1) + return std::unexpected(CheckpointError::unsupported); + return upgrade_manifest(previous, previous_digest, commit, lease, build, bytes, digest, + cellular_v11_versions, cellular_v12_versions); +} +std::expected, CheckpointError> +cellular_inheritance_upgrade_payload(std::span payload, + const CheckpointManifest& previous) { + if (!supported(previous) || previous.profile != CheckpointProfile::cellular_lives_v1 || + previous.cellular_versions != cellular_v11_versions) + return std::unexpected(CheckpointError::unsupported); + if (!encode_manifest(previous) || previous.sequence == 0 || previous.end_tick == 0) + return std::unexpected(CheckpointError::chain); + auto state = restore_cellular_payload(payload, previous); + if (!state) + return std::unexpected(state.error()); + auto upgraded = (*state)->inheritance_upgrade_candidate(); + if (!upgraded) + return std::unexpected(CheckpointError::payload); + return (*upgraded)->snapshot(); +} } // namespace evo::persistence diff --git a/src/persistence/region_checkpoint.cpp b/src/persistence/region_checkpoint.cpp index 73eb91f..8f1db82 100644 --- a/src/persistence/region_checkpoint.cpp +++ b/src/persistence/region_checkpoint.cpp @@ -67,7 +67,8 @@ bool structural(const CheckpointManifest& m) noexcept { m.cellular_versions == cellular_v3_versions || m.cellular_versions == cellular_v9_versions || m.cellular_versions == cellular_v10_versions || - m.cellular_versions == cellular_v11_versions) && + m.cellular_versions == cellular_v11_versions || + m.cellular_versions == cellular_v12_versions) && m.begin_tick == m.end_tick && m.end_tick > 0 && b == BatchDigests{}; const bool population_conversion = population && m.begin_tick == m.end_tick && m.end_tick > 0 && @@ -87,7 +88,8 @@ bool structural(const CheckpointManifest& m) noexcept { m.cellular_versions != cellular_v8_versions && m.cellular_versions != cellular_v9_versions && m.cellular_versions != cellular_v10_versions && - m.cellular_versions != cellular_v11_versions) || + m.cellular_versions != cellular_v11_versions && + m.cellular_versions != cellular_v12_versions) || (cellular && m.versions != environmental_v1_versions)) return false; if (primitive && (m.manifest_version != 2 || m.tick_microseconds != 50000 || @@ -102,7 +104,8 @@ bool structural(const CheckpointManifest& m) noexcept { // Boundary accounting is admitted only by an explicit retained-source // upgrade. Provisioning cannot skip its original opening-stock history. if (cellular && (m.cellular_versions == cellular_v10_versions || - m.cellular_versions == cellular_v11_versions)) + m.cellular_versions == cellular_v11_versions || + m.cellular_versions == cellular_v12_versions)) return false; const bool genesis = zero(m.holder) && m.epoch == 0 && m.begin_tick == m.end_tick && b.trace_bytes == 0 && zero(b.trace_sha256); @@ -185,7 +188,8 @@ bool supported(const CheckpointManifest& m) noexcept { 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) { - const bool revision = cellular_revision_bundle(m.cellular_versions); + const bool revision = cellular_revision_bundle(m.cellular_versions) || + m.cellular_versions == cellular_v12_versions; const bool history_matches = (!revision && m.history_profile == cellular_history_profile) || (revision && m.history_profile == cellular_revision_history_profile); @@ -200,7 +204,8 @@ bool supported(const CheckpointManifest& m) noexcept { m.cellular_versions == cellular_v8_versions || m.cellular_versions == cellular_v9_versions || m.cellular_versions == cellular_v10_versions || - m.cellular_versions == cellular_v11_versions) && + m.cellular_versions == cellular_v11_versions || + m.cellular_versions == cellular_v12_versions) && m.versions == environmental_v1_versions && m.tick_microseconds == 50000 && m.rng_streams == 0 && m.durability == DurabilityPolicy::single_volume_development; } diff --git a/tests/cellular_inheritance_checkpoint_tests.cpp b/tests/cellular_inheritance_checkpoint_tests.cpp new file mode 100644 index 0000000..1a2726d --- /dev/null +++ b/tests/cellular_inheritance_checkpoint_tests.cpp @@ -0,0 +1,350 @@ +#include "evo/persistence/region_checkpoint.hpp" +#include "fixtures/cellular_ecology.hpp" + +#include +#include + +namespace { +using namespace evo; +using namespace evo::server; +using namespace evo::persistence; +using namespace evo::fixture; +template std::array filled(std::uint8_t value) { + std::array result{}; + result.fill(value); + return result; +} +std::vector idle(const CellularLives& state, bool bud = false, + bool frozen = false) { + std::vector result; + for (const auto& life : state.lives()) { + CellularLifeIntent input{life.identity.life, {}}; + if (life.account != LifeAccount{}) { + input.intent.frozen = frozen; + input.intent.bud = bud && !frozen; + } + result.push_back(input); + } + return result; +} +const CellularOwnedLife& parent(const CellularLives& state) { + const auto found = + std::ranges::find(state.lives(), 100, [](const auto& life) { return life.identity.life; }); + require(found != state.lives().end(), "checkpoint parent missing"); + return *found; +} +Owner source_owner() { + auto state = opening(7, true, 1); + state = checked(state->migration_upgrade_candidate(), "checkpoint boundary source"); + state = checked(state->maturation_upgrade_candidate(), "checkpoint maturation source"); + for (unsigned tick = 0; tick < 60'000 && parent(*state).identity.genome == 100; ++tick) { + const auto cell = parent(*state); + if (cell.mutation.offer) { + const CellularMutationSelection choice{ + 100, cell.mutation.event_index, cell.mutation.offer_tick, 500'000, + cell.mutation.offer->candidates.front().operator_id}; + checked(state->advance_tick_with_mutations(idle(*state), std::span{&choice, 1}), + "legacy expressed source mutation"); + } else + checked(state->advance_tick_with_mutations(idle(*state), {}), "source earned offer"); + } + require(parent(*state).identity.genome == 500'000 && !state->archive().revisions().empty(), + "source has no legacy expressed revision"); + bool born = false; + for (unsigned tick = 0; tick < 30'000 && !born; ++tick) { + const auto result = checked(state->advance_tick_with_mutations(idle(*state, true), {}), + "fund source offspring"); + born = std::ranges::any_of( + result.buds, [](const auto& bud) { return bud.result == CellularBudResult::budded; }); + } + require(born, "source did not produce funded offspring"); + for (unsigned tick = 0; tick < 205; ++tick) + checked(state->advance_tick_with_mutations(idle(*state, false, true), {}), + "suspend source parent"); + require(parent(*state).presence == CellularPresence::suspended && state->lives().size() > 1, + "source lost its suspended parent or funded offspring"); + return state; +} +// Opaque digest inputs exercise this storage-free API; the I/O caller must verify SHA-256. +CheckpointManifest source_manifest(const CellularLives& source) { + CheckpointManifest m; + m.profile = CheckpointProfile::cellular_lives_v1; + m.key = {source.world(), source.region()}; + m.frame = source.frame(); + m.commit = filled<16>(3); + m.sequence = 8; + m.predecessor_commit = filled<16>(2); + m.predecessor_digest = filled<32>(4); + m.begin_tick = source.tick() - 1; + m.end_tick = source.tick(); + m.holder = filled<16>(5); + m.epoch = 4; + m.tick_microseconds = biology::cellular_motion_tick_microseconds; + m.cellular_versions = cellular_v11_versions; + m.build = filled<32>(6); + m.history_profile = cellular_revision_history_profile; + m.payload_bytes = source.snapshot().size(); + m.payload_sha256 = filled<32>(7); + m.batch.trace_bytes = cellular_batch_header_bytes + cellular_batch_tick_header_bytes + + source.lives().size() * cellular_batch_intent_bytes; + m.batch.trace_sha256 = filled<32>(8); + require(supported(m) && encode_manifest(m).has_value(), "invalid source manifest fixture"); + return m; +} +LeaseGrant lease_for(const CheckpointManifest& m) { + return {filled<16>(9), 5, m.frame}; +} +struct Upgraded { + CheckpointManifest manifest; + std::vector payload; +}; +Upgraded upgrade(std::span bytes, const CheckpointManifest& source) { + auto payload = checked(cellular_inheritance_upgrade_payload(bytes, source), "upgrade payload"); + auto manifest = checked(cellular_inheritance_upgrade_manifest( + source, filled<32>(10), filled<16>(11), lease_for(source), + filled<32>(12), payload.size(), filled<32>(13)), + "upgrade manifest"); + return {manifest, std::move(payload)}; +} +void continuation(const Upgraded& target) { + auto state = checked(restore_cellular_payload(target.payload, target.manifest), + "upgraded continuation source"); + auto head = target.manifest; + for (unsigned tick = 0; tick < 60'000; ++tick) { + const auto cell = parent(*state); + const bool selecting = + cell.mutation.offer.has_value() && cell.presence == CellularPresence::active; + CellularBatch batch; + batch.format_version = cellular_batch_inheritance_format; + batch.header = {state->world(), state->region(), state->frame(), {}, {}, + state->tick(), state->tick() + 1}; + batch.header.predecessor.fill(14); + batch.header.predecessor_digest.fill(15); + batch.ticks.push_back({idle(*state), {}, {}}); + if (selecting) { + const auto offer = cell.mutation.offer; + if (!offer) + throw std::runtime_error("continuation offer missing"); + batch.ticks.front().mutations.push_back({100, cell.mutation.event_index, + cell.mutation.offer_tick, 600'000, + offer->candidates.front().operator_id}); + } + const auto before = restore(*state); + const auto result = checked(state->advance_tick_with_mutations( + batch.ticks.front().lives, batch.ticks.front().mutations), + "inherited continuation tick"); + const auto recorded = checked(encode_cellular_batch(batch), "continuation trace"); + require(checked(replay_cellular_batch(*before, checked(decode_cellular_batch(recorded), + "continuation trace decode")), + "continuation replay") + ->snapshot() == state->snapshot(), + "continued trace differs from direct owner"); + auto commit = filled<16>(21); + for (unsigned offset = 0; offset < 8; ++offset) + commit[offset] = static_cast((head.sequence + 1) >> (offset * 8U)); + head = checked(successor_manifest(head, filled<32>(20), commit, lease_for(head), + state->tick(), head.build, state->snapshot().size(), + filled<32>(22), {recorded.size(), filled<32>(23), 0, {}}), + "inherited successor manifest"); + require(head.cellular_versions == cellular_v12_versions && + checked(restore_cellular_payload(state->snapshot(), head), + "continued checkpoint restore") + ->snapshot() == state->snapshot(), + "ordinary successor lost retained-plan tuple or biology"); + if (selecting) { + require(result.mutations.size() == 1 && + result.mutations.front().result == + CellularMutationResult::offspring_plan_applied && + parent(*state).identity.genome == 500'000 && + parent(*state).offspring_genome == 600'000, + "continuation rebuilt expressed body or lost selected plan"); + return; + } + } + throw std::runtime_error("continued upgraded owner did not earn an offer"); +} +void contracts() { + auto source = source_owner(); + const auto original = source->snapshot(); + const auto manifest = source_manifest(*source); + const auto manifest_bytes = checked(encode_manifest(manifest), "source manifest bytes"); + const auto target = upgrade(original, manifest); + const auto restored = + checked(restore_cellular_payload(target.payload, target.manifest), "target full restore"); + require(source->snapshot() == original && + checked(encode_manifest(manifest), "unchanged source manifest") == manifest_bytes && + restored->snapshot() == + checked(source->inheritance_upgrade_candidate(), "owner oracle")->snapshot() && + restored->archive().encode() == source->archive().encode() && + restored->current_total() == source->current_total() && + parent(*restored).identity == parent(*source).identity && + parent(*restored).offspring_genome == 500'000 && + parent(*restored).presence == CellularPresence::suspended && + restored->offspring_revisions().empty(), + "checkpoint upgrade changed source or retained biology"); + for (const auto& life : restored->lives()) + require(life.offspring_genome == life.identity.genome, "initial inherited plan mismatch"); + const auto& m = target.manifest; + require(supported(m) && m.cellular_versions == cellular_v12_versions && + m.profile == manifest.profile && m.history_profile == manifest.history_profile && + m.key == manifest.key && m.frame == manifest.frame && + m.sequence == manifest.sequence + 1 && m.predecessor_commit == manifest.commit && + m.predecessor_digest == filled<32>(10) && m.commit == filled<16>(11) && + m.begin_tick == source->tick() && m.end_tick == source->tick() && + m.tick_microseconds == manifest.tick_microseconds && m.batch == BatchDigests{} && + m.holder == lease_for(manifest).holder && m.epoch == lease_for(manifest).epoch && + m.build == filled<32>(12) && m.payload_bytes == target.payload.size() && + m.payload_sha256 == filled<32>(13) && + checked(decode_manifest(checked(encode_manifest(m), "target encode")), + "target decode") == m, + "upgrade manifest lost its exact bindings"); + require(!cellular_inheritance_upgrade_payload(target.payload, m) && + !cellular_inheritance_upgrade_manifest(m, filled<32>(1), filled<16>(2), + lease_for(m), m.build, m.payload_bytes, + m.payload_sha256), + "repeated inheritance upgrade admitted"); + auto mislabeled = manifest; + mislabeled.cellular_versions = cellular_v12_versions; + require(!restore_cellular_payload(original, mislabeled), "old bytes admitted as bundle 12"); + mislabeled = m; + mislabeled.cellular_versions = cellular_v11_versions; + require(!restore_cellular_payload(target.payload, mislabeled), + "new bytes admitted as bundle 11"); + auto corrupt = original; + corrupt.back() ^= 1; + require(!cellular_inheritance_upgrade_payload(corrupt, manifest) && + !cellular_inheritance_upgrade_payload(std::span{original}.first(16), manifest), + "bad source payload upgraded"); + auto genesis = m; + genesis.sequence = 0; + genesis.begin_tick = genesis.end_tick = 0; + genesis.predecessor_commit = {}; + genesis.predecessor_digest = {}; + genesis.holder = {}; + genesis.epoch = 0; + require(!encode_manifest(genesis), "retained-plan genesis bypassed upgrade"); + require(population_envelope_version(cellular_v12_versions) == 0 && + !cellular_revision_bundle(cellular_v12_versions) && + !population_profile_transition_manifest(m, filled<32>(1), filled<16>(2), + lease_for(m), m.build, m.payload_bytes, + m.payload_sha256), + "legacy population/trace admission included retained plans"); + auto population = manifest; + population.profile = CheckpointProfile::cellular_population_v1; + population.history_profile = population_history_profile; + require(!cellular_inheritance_upgrade_payload(original, population) && + !cellular_inheritance_upgrade_manifest(population, filled<32>(1), filled<16>(2), + lease_for(population), population.build, + m.payload_bytes, m.payload_sha256), + "population inheritance upgrade admitted"); + population.cellular_versions = cellular_v12_versions; + require(!supported(population) && !encode_manifest(population), + "bundle 12 population admitted"); + for (unsigned fault = 0; fault < 15; ++fault) { + auto bad = manifest; + auto lease = lease_for(bad); + auto reference = filled<32>(10); + auto commit = filled<16>(11); + auto build = filled<32>(12); + auto digest = filled<32>(13); + auto bytes = m.payload_bytes; + switch (fault) { + case 0: + bad.sequence = ~std::uint64_t{0}; + break; + case 1: + bad.sequence = 0; + break; + case 2: + bad.cellular_versions = cellular_v10_versions; + break; + case 3: + bad.cellular_versions = cellular_v9_versions; + break; + case 4: + ++lease.frame; + break; + case 5: + lease.epoch = 0; + break; + case 6: + lease.holder = {}; + break; + case 7: + reference = {}; + break; + case 8: + commit = manifest.commit; + break; + case 9: + commit = {}; + break; + case 10: + build = {}; + break; + case 11: + digest = {}; + break; + case 12: + bytes = 0; + break; + case 13: + bytes = max_cellular_lives_bytes + 1; + break; + case 14: + bad.history_profile = cellular_history_profile; + break; + default: + throw std::runtime_error("unknown checkpoint fault"); + } + require(!cellular_inheritance_upgrade_manifest(bad, reference, commit, lease, build, bytes, + digest), + "invalid upgrade binding admitted"); + } + continuation(target); +} +void save(const std::string& path, std::span bytes) { + std::ofstream file(path, std::ios::binary | std::ios::trunc); + file.write(reinterpret_cast(bytes.data()), + static_cast(bytes.size())); + require(file.good(), "checkpoint fixture write"); +} +std::vector read(const std::string& path, std::size_t bound) { + std::ifstream file(path, std::ios::binary); + require(file.good(), "checkpoint fixture read"); + std::vector bytes{std::istreambuf_iterator{file}, {}}; + require(bytes.size() <= bound, "checkpoint fixture bound"); + return bytes; +} +std::vector proof(const Upgraded& candidate) { + checked(restore_cellular_payload(candidate.payload, candidate.manifest), "process target"); + auto bytes = checked(encode_manifest(candidate.manifest), "proof manifest"); + bytes.insert(bytes.end(), candidate.payload.begin(), candidate.payload.end()); + return bytes; // Test-only complete manifest + payload comparison, not a storage codec. +} +} // namespace +int main(int argc, char** argv) try { + if (argc == 4 && std::string_view{argv[1]} == "--checkpoint") { + const auto source = source_owner(); + const auto bytes = source->snapshot(); + const auto manifest = source_manifest(*source); + save(argv[2], bytes); + save(std::string{argv[2]} + ".manifest", checked(encode_manifest(manifest), "save source")); + save(argv[3], proof(upgrade(bytes, manifest))); + return 0; + } + if (argc == 4 && std::string_view{argv[1]} == "--resume") { + const auto source = read(argv[2], max_cellular_lives_bytes); + const auto manifest = checked( + decode_manifest(read(std::string{argv[2]} + ".manifest", checkpoint_manifest_bytes)), + "new process source manifest"); + save(argv[3], proof(upgrade(source, manifest))); + return 0; + } + require(argc == 1, "unknown inheritance checkpoint arguments"); + contracts(); + return 0; +} catch (const std::exception& error) { + std::cerr << error.what() << '\n'; + return 1; +}