#pragma once #include "evo/persistence/region_batch.hpp" #include "evo/persistence/region_lease.hpp" #include "evo/processes/environmental_community.hpp" #include "evo/processes/lineage_region.hpp" #include "evo/server/lifecycle/cellular_batch.hpp" #include "evo/server/lifecycle/cellular_environment.hpp" #include "evo/server/lifecycle/cellular_lives.hpp" #include "evo/server/lifecycle/cellular_population_batch.hpp" #include "evo/server/lifecycle/primitive_batch.hpp" #include #include #include #include #include #include // Region checkpoint manifest v1 and payload validation for environmental-v1 // (ADR-0061) and environmental-lineage-v1 (ADR-0062), schemas/region-commit.md. Portable and // storage-free: digests are computed and objects are stored by the Linux adapters; this only // encodes and validates. namespace evo::persistence { // Encoded as u32 on the wire; values above 255 decode as unknown (0), never truncated. enum class CheckpointProfile : std::uint8_t { unknown = 0, 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 or 4. cellular_population_v1 = 5, // Exact populations; cellular bundle 9, 10 or 11. cellular_environment_v1 = 6, // ADR-0174: cells with their environment; bundle 10 or 11. }; // Profiles whose manifests carry a CellularVersionBundle. [[nodiscard]] constexpr bool cellular_profile(CheckpointProfile profile) noexcept { return profile == CheckpointProfile::cellular_lives_v1 || profile == CheckpointProfile::cellular_population_v1 || profile == CheckpointProfile::cellular_environment_v1; } // 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; inline constexpr std::uint32_t population_history_profile = 5; // ADR-0174: joint envelope 1 nesting population envelope 2 and its lineage archive. inline constexpr std::uint32_t environment_history_profile = 6; inline constexpr std::uint32_t cellular_revision_history_profile = 4; // Declared durability, verified at deployment. Development: one volume, no host-loss claim. enum class DurabilityPolicy : std::uint8_t { unknown = 0, single_volume_development = 1 }; // Exact versions of every nested format/rule the payload depends on. The interval // adapter carries no payload state but its version is still pinned. struct VersionBundle { std::uint32_t rules{2}, envelope{2}, resources{1}, fields{1}, terrain{1}, coordinate{1}, generator{1}, material{1}, interval_adapter{1}; friend bool operator==(const VersionBundle&, const VersionBundle&) = default; }; 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}, mutation_state{}; friend bool operator==(const CellularVersionBundle&, const CellularVersionBundle&) = default; }; inline constexpr CellularVersionBundle cellular_v1_versions{}; inline constexpr CellularVersionBundle cellular_v2_versions{2, 2, 1, 1, 1, 2, 1, 1, 1}; inline constexpr CellularVersionBundle cellular_v3_versions{2, 3, 1, 1, 1, 2, 1, 2, 1}; // ADR-0124: rules 3 (engulfment, detritus) and owner envelope 4 (corpse causes). inline constexpr CellularVersionBundle cellular_v4_versions{3, 4, 1, 1, 1, 2, 1, 2, 1}; // ADR-0125: rules 4 (budding wildlife) and owner envelope 5 (bud sequence, parents). inline constexpr CellularVersionBundle cellular_v5_versions{4, 5, 1, 1, 1, 2, 1, 2, 1}; // ADR-0128: rules 5 (offline freeze and resume) and owner envelope 6 (presence). inline constexpr CellularVersionBundle cellular_v6_versions{5, 6, 1, 1, 1, 2, 1, 2, 1}; // 2026-10-15 balance: rules 6 on owner envelope 6, with development 3 and founder 2. inline constexpr CellularVersionBundle cellular_v7_versions{6, 6, 1, 1, 1, 3, 2, 2, 1}; // ADR-0137: rules 7 on owner envelope 6, with development 4 and founder 3. inline constexpr CellularVersionBundle cellular_v8_versions{7, 6, 1, 1, 1, 4, 3, 2, 1}; // ADR-0136 step A: rules 8 on owner envelope 6 with habitat 2 (pools and bubbles). inline constexpr CellularVersionBundle cellular_v9_versions{8, 6, 2, 1, 1, 4, 3, 2, 1}; // ADR-0145: portable boundary accounting, unchanged rules 8 on owner envelope 7. // Database publication requires its own explicit schema admission. 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}; // ADR-0175/0176: rules 11 on owner format 9 (declared light), development 5, founder 4. inline constexpr CellularVersionBundle cellular_v13_versions{11, 9, 2, 1, 1, 5, 4, 2, 1}; // Rules 12 on owner format 10 (liquid region), development 6, founder 5 (ADR-0177). inline constexpr CellularVersionBundle cellular_v14_versions{12, 10, 2, 1, 1, 6, 5, 2, 1}; // Rules 13 on owner format 11 (the cellular revamp), development 7, founder 6 (ADR-0179). inline constexpr CellularVersionBundle cellular_v15_versions{13, 11, 2, 1, 1, 7, 6, 2, 1}; // Raw-only retained-plan bundles, which use trace 4 and their own SQL admission. [[nodiscard]] constexpr bool cellular_plan_bundle(const CellularVersionBundle& b) noexcept { return b == cellular_v12_versions || b == cellular_v13_versions || b == cellular_v14_versions || b == cellular_v15_versions; } // Zero means this bundle has no population representation. [[nodiscard]] constexpr std::uint32_t population_envelope_version(const CellularVersionBundle& b) noexcept { return b == cellular_v9_versions ? 1 : (b == cellular_v10_versions || b == cellular_v11_versions) ? 2 : 0; } // 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 || b == cellular_v9_versions || b == cellular_v10_versions || b == cellular_v11_versions; } // Exact raw trace version for admitted cellular tuples; bundle 12 has its own semantics. [[nodiscard]] constexpr std::uint32_t cellular_checkpoint_trace_format(const CellularVersionBundle& b) noexcept { return cellular_plan_bundle(b) ? server::cellular_batch_inheritance_format : cellular_revision_bundle(b) ? server::cellular_batch_format : server::cellular_batch_v2_format; } // ADR-0182: a bundle-15 commit may carry admin commands in trace 5; every other format is // exactly the bundle's. [[nodiscard]] constexpr bool cellular_checkpoint_trace_admits(const CellularVersionBundle& b, std::uint32_t format) noexcept { return format == cellular_checkpoint_trace_format(b) || (format == server::cellular_batch_admin_format && b == cellular_v15_versions); } // Batch evidence bound by manifest v2 (ADR-0063); all zero at genesis. struct BatchDigests { std::uint64_t trace_bytes{}; Sha256Digest trace_sha256{}; std::uint32_t decision_count{}; Sha256Digest decisions_sha256{}; // Zero exactly when there are no decisions. friend bool operator==(const BatchDigests&, const BatchDigests&) = default; }; struct CheckpointManifest { // 2 is the only version written; 1 (M7.4, no batch evidence) still decodes. std::uint32_t manifest_version{2}; CheckpointProfile profile{CheckpointProfile::environmental_v1}; RegionKey key{}; std::uint64_t frame{}; Uuid commit{}; std::uint64_t sequence{}; // Zero at provisioned genesis. At a clone genesis (sequence 0, ADR-0067) they // name the source commit and the SHA-256 of its manifest bytes. Uuid predecessor_commit{}; Sha256Digest predecessor_digest{}; // SHA-256 of the predecessor manifest bytes. std::uint64_t begin_tick{}, end_tick{}; Uuid holder{}; // Zero only at genesis (provisioning, not a lease). 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. DurabilityPolicy durability{DurabilityPolicy::single_volume_development}; std::uint64_t payload_bytes{}; Sha256Digest payload_sha256{}; BatchDigests batch{}; friend bool operator==(const CheckpointManifest&, const CheckpointManifest&) = default; }; inline constexpr std::size_t checkpoint_manifest_v1_bytes = 280; inline constexpr std::size_t checkpoint_manifest_bytes = 360; inline constexpr std::size_t max_environmental_payload_bytes = std::size_t{1024} * 1024; inline constexpr std::size_t max_lineage_payload_bytes = processes::max_lineage_region_bytes; // Payload cap by profile; zero for an unknown profile. [[nodiscard]] constexpr std::size_t max_payload_bytes(CheckpointProfile profile) noexcept { 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 : profile == CheckpointProfile::cellular_population_v1 ? server::max_cellular_population_bytes : profile == CheckpointProfile::cellular_environment_v1 ? server::max_cellular_environment_bytes : 0; } inline constexpr std::uint64_t max_checkpoint_ticks = 64; enum class CheckpointError : std::uint8_t { format, // Malformed or internally inconsistent manifest. unsupported, // Unknown profile, version, RNG/history or durability declaration. chain, // Not a valid successor of the committed predecessor. payload, // Payload bytes fail full envelope validation or identity/tick checks. }; // Structural validation of every field; versions/profile are checked separately // so recovery can distinguish corruption from an unsupported (retained) format. [[nodiscard]] std::expected, CheckpointError> encode_manifest(const CheckpointManifest& manifest); [[nodiscard]] std::expected decode_manifest(std::span bytes); // Portable reader support: history, exact versions, zero RNG and durability. // This does not grant admission to a database schema or a publication operation. [[nodiscard]] bool supported(const CheckpointManifest& manifest) noexcept; // Genesis for operator provisioning only; recovery never creates one. [[nodiscard]] std::expected genesis_manifest(RegionKey key, std::uint64_t frame, Uuid commit, std::uint64_t tick_microseconds, const Sha256Digest& build, std::uint64_t payload_bytes, const Sha256Digest& payload_sha256, CheckpointProfile profile = CheckpointProfile::environmental_v1); // Clone genesis (ADR-0067): sequence 0 of `target` in another world, at the source's // end tick, whose predecessor fields name the source commit and manifest digest. // Profile, versions, quantum, frame and build are inherited; `inherited` digests the // source's permanent outcomes (no trace). The payload must be re-identified bytes. [[nodiscard]] std::expected clone_manifest(const CheckpointManifest& source, const Sha256Digest& source_digest, RegionKey target, Uuid commit, std::uint64_t payload_bytes, const Sha256Digest& payload_sha256, const BatchDigests& inherited); // Next link from the committed predecessor and its manifest digest under a lease. // Profile, versions and quantum are inherited: a region never changes them. [[nodiscard]] std::expected successor_manifest(const CheckpointManifest& predecessor, const Sha256Digest& predecessor_digest, Uuid commit, const LeaseGrant& lease, std::uint64_t end_tick, const Sha256Digest& build, std::uint64_t payload_bytes, const Sha256Digest& payload_sha256, const BatchDigests& batch); // Leased, no-tick cellular representation migration. SQL publication independently // verifies the exact adjacent profile transition. [[nodiscard]] std::expected cellular_profile_migration_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); // Fully restores payload bytes (envelope checksum, bounds and replay audit), then // requires manifest identity, end tick, tick quantum, envelope format 2 and a // byte-identical canonical re-encoding. The caller verifies length and SHA-256. [[nodiscard]] std::expected, CheckpointError> restore_environmental_payload(std::span payload, const CheckpointManifest& manifest, std::size_t budget); // environmental-lineage-v1: restores the container (envelope replay audit, archive // replay through its invariants, closure) with the same identity/tick/quantum, // nested envelope format 2 and canonical checks. [[nodiscard]] std::expected, CheckpointError> restore_lineage_payload(std::span payload, const CheckpointManifest& manifest, std::size_t budget); // Creation-only profile: canonical funded closure, all births <= manifest tick, // no organisms at genesis. Manifest owns the checkpoint clock; no biology steps. // Length and SHA-256 must be verified by the object-store caller as above. [[nodiscard]] std::expected, CheckpointError> restore_primitive_payload(std::span payload, const CheckpointManifest& manifest); [[nodiscard]] std::expected, CheckpointError> restore_cellular_payload(std::span payload, const CheckpointManifest& manifest); [[nodiscard]] std::expected, CheckpointError> restore_population_payload(std::span payload, const CheckpointManifest& manifest); // Dedicated profile 4 <-> profile 5 transition, preserving bundle 9, 10 or 11 exactly. [[nodiscard]] std::expected population_profile_transition_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); // Explicit portable bundle 9 -> 10 upgrade, preserving profile 4/5 and history. // No tick, representation conversion, new genesis or downgrade. The caller must // independently verify the predecessor manifest/payload SHA-256 bindings; neither // these candidate bytes nor supported() confer publication authority. [[nodiscard]] std::expected cellular_boundary_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); // Restores the complete bundle-9 source and derives an exact no-tick owner-7 // candidate; population policy, membership and conversion sequence are retained. [[nodiscard]] std::expected, CheckpointError> cellular_boundary_upgrade_payload(std::span payload, const CheckpointManifest& predecessor); // ADR-0158: exact same-profile, no-tick bundle 10 -> 11 maturation upgrade. // The caller independently binds source SHA-256 and fenced publication authority. [[nodiscard]] std::expected cellular_maturation_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_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); // ADR-0176: explicit raw-only bundle 12 -> 13 upgrade declaring the region's light. The // light is an input; recovery reads it from the target and re-derives everything else. [[nodiscard]] std::expected cellular_photosynthesis_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_photosynthesis_upgrade_payload(std::span payload, const CheckpointManifest& predecessor, const server::CellularLight& light); // Rules 12: explicit raw-only bundle 13 -> 14 upgrade declaring the region's liquid rules. As // with light, the rules are the only input; recovery reads them from the target. [[nodiscard]] std::expected cellular_liquid_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_liquid_upgrade_payload(std::span payload, const CheckpointManifest& predecessor, const server::CellularLiquidRules& rules); // Rules 13 (ADR-0179): explicit raw-only bundle 14 -> 15 upgrade declaring the revamp rules // from the Git tuning file. ADR-0180 also admits an explicit empty-opening fixture; // recovery reads its count/first identity from the target and re-derives every byte. [[nodiscard]] std::expected cellular_revamp_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_revamp_upgrade_payload(std::span payload, const CheckpointManifest& predecessor, const server::CellularRevampRules& rules, std::uint32_t playtest_wildlife_count = 0, std::uint64_t playtest_first_identity = 0); // ADR-0174: explicit one-way, no-tick profile 5 -> 6 transition. The payload wraps the // identical population with its declared environment; bundle and policy are unchanged. [[nodiscard]] std::expected environment_profile_transition_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); // Joint interval or whole-group conversion; a conversion keeps the tick with a trace. [[nodiscard]] std::expected environment_successor_manifest( const CheckpointManifest& predecessor, const Sha256Digest& predecessor_digest, Uuid commit, const LeaseGrant& lease, std::uint64_t end_tick, const Sha256Digest& build, std::uint64_t payload_bytes, const Sha256Digest& payload_sha256, const BatchDigests& batch); [[nodiscard]] std::expected, CheckpointError> restore_environment_payload(std::span payload, const CheckpointManifest& manifest); // 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, const LeaseGrant& lease, std::uint64_t end_tick, const Sha256Digest& build, std::uint64_t payload_bytes, const Sha256Digest& payload_sha256, const BatchDigests& batch); } // namespace evo::persistence