feat(persistence): define retained-plan checkpoint upgrade candidates
Foundation / checks (ecs) (push) Successful in 2m51s
Foundation / checks (deploy) (push) Successful in 5m18s
Foundation / checks (network) (push) Successful in 25m49s
Foundation / checks (client) (push) Successful in 26m34s
Foundation / checks (tsan) (push) Successful in 37m12s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 47m59s
Foundation / checks (postgres) (push) Canceled after 47m53s

This commit is contained in:
dingo
2026-10-19 14:17:41 -04:00
parent c0c66fa11a
commit 39509ecd40
17 changed files with 629 additions and 11 deletions
+10
View File
@@ -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=$<TARGET_FILE:evo-cellular-inheritance-checkpoint-tests>"
"-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)
+6
View File
@@ -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).
@@ -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.
+16
View File
@@ -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
@@ -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.
+2
View File
@@ -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.
@@ -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
+3 -1
View File
@@ -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.
+3 -1
View File
@@ -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.
+53
View File
@@ -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
+15 -1
View File
@@ -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<std::vector<std::uint8_t>, CheckpointError>
cellular_maturation_upgrade_payload(std::span<const std::uint8_t> 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<CheckpointManifest, CheckpointError>
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<std::vector<std::uint8_t>, CheckpointError>
cellular_inheritance_upgrade_payload(std::span<const std::uint8_t> payload,
const CheckpointManifest& predecessor);
// Population manual conversion may publish at the same tick with a nonempty trace.
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError> population_successor_manifest(
const CheckpointManifest& predecessor, const Sha256Digest& predecessor_digest, Uuid commit,
+45
View File
@@ -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.
+3 -1
View File
@@ -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.
+2 -1
View File
@@ -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.
+26
View File
@@ -171,4 +171,30 @@ cellular_maturation_upgrade_payload(std::span<const std::uint8_t> payload,
const CheckpointManifest& previous) {
return upgrade_payload(payload, previous, true);
}
std::expected<CheckpointManifest, CheckpointError>
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<std::vector<std::uint8_t>, CheckpointError>
cellular_inheritance_upgrade_payload(std::span<const std::uint8_t> 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
+10 -5
View File
@@ -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;
}
@@ -0,0 +1,350 @@
#include "evo/persistence/region_checkpoint.hpp"
#include "fixtures/cellular_ecology.hpp"
#include <fstream>
#include <iterator>
namespace {
using namespace evo;
using namespace evo::server;
using namespace evo::persistence;
using namespace evo::fixture;
template <std::size_t N> std::array<std::uint8_t, N> filled(std::uint8_t value) {
std::array<std::uint8_t, N> result{};
result.fill(value);
return result;
}
std::vector<CellularLifeIntent> idle(const CellularLives& state, bool bud = false,
bool frozen = false) {
std::vector<CellularLifeIntent> 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<std::uint8_t> payload;
};
Upgraded upgrade(std::span<const std::uint8_t> 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<std::uint8_t>((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<const std::uint8_t> bytes) {
std::ofstream file(path, std::ios::binary | std::ios::trunc);
file.write(reinterpret_cast<const char*>(bytes.data()),
static_cast<std::streamsize>(bytes.size()));
require(file.good(), "checkpoint fixture write");
}
std::vector<std::uint8_t> read(const std::string& path, std::size_t bound) {
std::ifstream file(path, std::ios::binary);
require(file.good(), "checkpoint fixture read");
std::vector<std::uint8_t> bytes{std::istreambuf_iterator<char>{file}, {}};
require(bytes.size() <= bound, "checkpoint fixture bound");
return bytes;
}
std::vector<std::uint8_t> 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;
}