Add cellular checkpoint manifest profile
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (checks) (push) Failing after 40s
Foundation / checks (ecs) (push) Successful in 1m49s
Foundation / checks (postgres) (push) Failing after 51s
Foundation / checks (tsan) (push) Failing after 32s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (client) (push) Canceled after 3m42s
Foundation / checks (network) (push) Canceled after 3m4s

This commit is contained in:
dingo
2026-10-10 22:45:29 -04:00
parent 181b9aeec2
commit 3931fcfbe6
7 changed files with 163 additions and 19 deletions
+4 -3
View File
@@ -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
+5
View File
@@ -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
+17
View File
@@ -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.
@@ -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 <cstddef>
#include <cstdint>
@@ -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<const std::uint8_t> payload, const CheckpointM
[[nodiscard]] std::expected<std::unique_ptr<server::PrimitiveLives>, CheckpointError>
restore_primitive_payload(std::span<const std::uint8_t> payload,
const CheckpointManifest& manifest);
[[nodiscard]] std::expected<std::unique_ptr<server::CellularLives>, CheckpointError>
restore_cellular_payload(std::span<const std::uint8_t> payload,
const CheckpointManifest& manifest);
} // namespace evo::persistence
+14 -7
View File
@@ -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
+60 -9
View File
@@ -1,5 +1,6 @@
#include "evo/persistence/region_checkpoint.hpp"
#include <algorithm>
#include <array>
#include <ranges>
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<const std::uint8_t> 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<std::uint32_t>(r.u(4));
std::array<std::uint32_t, 9> versions{};
for (auto& v : versions)
v = static_cast<std::uint32_t>(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<std::uint32_t>(r.u(4));
m.history_profile = static_cast<std::uint32_t>(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<CheckpointManifest, CheckpointError>
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<const std::uint8_t> payload, const Checkpoin
return std::unexpected{CheckpointError::payload};
return std::move(*restored);
}
std::expected<std::unique_ptr<server::CellularLives>, CheckpointError>
restore_cellular_payload(std::span<const std::uint8_t> 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
+49
View File
@@ -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) {