#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 #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. }; // history_profile 1: lineage archive format 1 with genome schema 1. inline constexpr std::uint32_t lineage_history_profile = 1; // 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{}; // 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{}; 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-v1; 1 environmental-lineage-v1. 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 : 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); // Profile with its history profile, exact versions, zero RNG and durability policy. [[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); // 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); } // namespace evo::persistence