#include "evo/persistence/region_checkpoint.hpp" #include #include namespace evo::persistence { namespace { constexpr std::uint64_t manifest_magic = 0x314D43524F564541ULL; // "AEVORCM1" constexpr std::uint64_t maximum = ~std::uint64_t{0}; template bool zero(const std::array& bytes) { return std::ranges::all_of(bytes, [](std::uint8_t b) { return b == 0; }); } class Writer { public: explicit Writer(std::vector& out) : out_(out) {} void u(std::uint64_t value, unsigned width) { for (unsigned i = 0; i < width; ++i) { out_.push_back(static_cast(value & 0xFFU)); value >>= 8U; } } template void bytes(const std::array& value) { out_.insert(out_.end(), value.begin(), value.end()); } private: std::vector& out_; }; class Reader { public: explicit Reader(std::span in) : in_(in) {} std::uint64_t u(unsigned width) { std::uint64_t value{}; for (unsigned i = 0; i < width; ++i) value |= static_cast(in_[at_ + i]) << (8U * i); at_ += width; return value; } template std::array bytes() { std::array value{}; std::copy_n(in_.begin() + static_cast(at_), N, value.begin()); at_ += N; return value; } private: std::span in_; std::size_t at_{}; }; // Every field, independent of which versions this build supports. bool structural(const CheckpointManifest& m) noexcept { // An unknown profile is unsupported, not malformed: bound it by the largest cap. const auto cap = max_payload_bytes(m.profile); const auto limit = cap == 0 ? max_lineage_payload_bytes : cap; if (m.key.world == 0 || m.key.region == 0 || m.frame == 0 || zero(m.commit) || m.tick_microseconds == 0 || zero(m.build) || m.payload_bytes == 0 || m.payload_bytes > limit || zero(m.payload_sha256)) return false; const auto& b = m.batch; if (m.manifest_version != 1 && m.manifest_version != 2) return false; const bool no_batch = b == BatchDigests{}; if (m.sequence == 0) { const bool genesis = zero(m.holder) && m.epoch == 0 && m.begin_tick == m.end_tick && 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; // Clone genesis (ADR-0067, v2 only): the origin is the source commit and // manifest digest; the block digests inherited permanent outcomes. return genesis && m.manifest_version == 2 && !zero(m.predecessor_commit) && !zero(m.predecessor_digest) && m.predecessor_commit != m.commit && b.decision_count <= max_batch_decisions && (b.decision_count == 0) == zero(b.decisions_sha256); } const bool link = !zero(m.predecessor_commit) && m.predecessor_commit != m.commit && !zero(m.predecessor_digest) && !zero(m.holder) && m.epoch != 0 && m.end_tick > m.begin_tick && m.end_tick - m.begin_tick <= max_checkpoint_ticks; if (m.manifest_version == 1) return link && no_batch; // v2: the trace has exactly one step per tick; decisions are bounded. return link && b.trace_bytes == trace_bytes_for(m.end_tick - m.begin_tick) && !zero(b.trace_sha256) && b.decision_count <= max_batch_decisions && (b.decision_count == 0) == zero(b.decisions_sha256); } } // namespace bool supported(const CheckpointManifest& m) noexcept { const bool profile = (m.profile == CheckpointProfile::environmental_v1 && m.history_profile == 0) || (m.profile == CheckpointProfile::environmental_lineage_v1 && m.history_profile == lineage_history_profile); return profile && m.versions == environmental_v1_versions && m.rng_streams == 0 && m.durability == DurabilityPolicy::single_volume_development; } std::expected, CheckpointError> encode_manifest(const CheckpointManifest& m) { if (!structural(m) || m.manifest_version != 2) return std::unexpected{CheckpointError::format}; std::vector out; out.reserve(checkpoint_manifest_bytes); Writer w{out}; w.u(manifest_magic, 8); w.u(m.manifest_version, 4); w.u(static_cast(m.profile), 4); w.u(m.key.world, 8); w.u(m.key.region, 8); w.u(m.frame, 8); w.bytes(m.commit); w.u(m.sequence, 8); w.bytes(m.predecessor_commit); w.bytes(m.predecessor_digest); w.u(m.begin_tick, 8); w.u(m.end_tick, 8); 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, m.versions.fields, m.versions.terrain, m.versions.coordinate, m.versions.generator, m.versions.material, m.versions.interval_adapter}) w.u(v, 4); w.bytes(m.build); w.u(m.rng_streams, 4); w.u(m.history_profile, 4); w.u(static_cast(m.durability), 4); w.u(m.payload_bytes, 8); w.bytes(m.payload_sha256); w.u(m.batch.trace_bytes, 8); w.bytes(m.batch.trace_sha256); w.u(m.batch.decision_count, 4); w.u(0, 4); w.bytes(m.batch.decisions_sha256); return out; } std::expected decode_manifest(std::span bytes) { if (bytes.size() < 12) return std::unexpected{CheckpointError::format}; Reader r{bytes}; if (r.u(8) != manifest_magic) return std::unexpected{CheckpointError::format}; CheckpointManifest m; m.manifest_version = static_cast(r.u(4)); if (m.manifest_version != 1 && m.manifest_version != 2) return std::unexpected{CheckpointError::unsupported}; if (bytes.size() != (m.manifest_version == 1 ? checkpoint_manifest_v1_bytes : checkpoint_manifest_bytes)) return std::unexpected{CheckpointError::format}; const auto profile = r.u(4); m.profile = profile <= 0xFFU ? static_cast(profile) : CheckpointProfile::unknown; m.key.world = r.u(8); m.key.region = r.u(8); m.frame = r.u(8); m.commit = r.bytes<16>(); m.sequence = r.u(8); m.predecessor_commit = r.bytes<16>(); m.predecessor_digest = r.bytes<32>(); m.begin_tick = r.u(8); m.end_tick = r.u(8); 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(r.u(4)); m.build = r.bytes<32>(); m.rng_streams = static_cast(r.u(4)); m.history_profile = static_cast(r.u(4)); const auto durability = r.u(4); m.durability = durability <= 0xFFU ? static_cast(durability) : DurabilityPolicy::unknown; m.payload_bytes = r.u(8); m.payload_sha256 = r.bytes<32>(); if (m.manifest_version == 2) { m.batch.trace_bytes = r.u(8); m.batch.trace_sha256 = r.bytes<32>(); m.batch.decision_count = static_cast(r.u(4)); if (r.u(4) != 0) return std::unexpected{CheckpointError::format}; // Reserved. m.batch.decisions_sha256 = r.bytes<32>(); } if (!structural(m)) return std::unexpected{CheckpointError::format}; return m; } 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) { CheckpointManifest m; m.profile = profile; m.history_profile = profile == CheckpointProfile::environmental_lineage_v1 ? lineage_history_profile : 0; m.key = key; m.frame = frame; m.commit = commit; m.tick_microseconds = tick_microseconds; m.build = build; m.payload_bytes = payload_bytes; m.payload_sha256 = payload_sha256; if (!structural(m)) return std::unexpected{CheckpointError::format}; return m; } 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) { if (!supported(source)) return std::unexpected{CheckpointError::unsupported}; if (!structural(source) || target.world == source.key.world || commit == source.commit || inherited.trace_bytes != 0 || !zero(inherited.trace_sha256)) return std::unexpected{CheckpointError::chain}; CheckpointManifest m = source; m.manifest_version = 2; m.key = target; m.commit = commit; m.sequence = 0; m.predecessor_commit = source.commit; m.predecessor_digest = source_digest; m.begin_tick = source.end_tick; m.holder = {}; m.epoch = 0; m.payload_bytes = payload_bytes; m.payload_sha256 = payload_sha256; m.batch = inherited; if (!structural(m)) return std::unexpected{CheckpointError::format}; return m; } std::expected successor_manifest(const CheckpointManifest& p, 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) { // This build writes only its own versions; a change requires a migration (M7.9). if (!supported(p)) return std::unexpected{CheckpointError::unsupported}; if (!structural(p) || p.sequence == maximum || lease.frame != p.frame || end_tick <= p.end_tick || end_tick - p.end_tick > max_checkpoint_ticks) return std::unexpected{CheckpointError::chain}; CheckpointManifest m = p; m.manifest_version = 2; m.batch = batch; m.commit = commit; m.sequence = p.sequence + 1; m.predecessor_commit = p.commit; m.predecessor_digest = predecessor_digest; m.begin_tick = p.end_tick; m.end_tick = end_tick; m.holder = lease.holder; m.epoch = lease.epoch; m.build = build; m.payload_bytes = payload_bytes; m.payload_sha256 = payload_sha256; if (!structural(m)) return std::unexpected{CheckpointError::format}; return m; } std::expected, CheckpointError> restore_environmental_payload(std::span payload, const CheckpointManifest& m, std::size_t budget) { if (!structural(m)) return std::unexpected{CheckpointError::format}; if (!supported(m) || m.profile != CheckpointProfile::environmental_v1) return std::unexpected{CheckpointError::unsupported}; if (payload.size() != m.payload_bytes || payload.size() < 16) return std::unexpected{CheckpointError::payload}; Reader header{payload}; header.u(8); // Envelope magic is checked by the envelope decoder itself. if (header.u(8) != m.versions.envelope) return std::unexpected{CheckpointError::unsupported}; auto restored = processes::EnvironmentalCommunity::restore(payload, {m.key.world, m.frame}, budget); if (!restored) return std::unexpected{CheckpointError::payload}; const auto& state = **restored; if (state.progress().tick != m.end_tick || state.tick_microseconds() != m.tick_microseconds) return std::unexpected{CheckpointError::payload}; // Canonical: the restored state re-encodes to exactly the committed bytes. const auto again = state.snapshot(); if (!again || !std::ranges::equal(*again, payload)) return std::unexpected{CheckpointError::payload}; return std::move(*restored); } std::expected, CheckpointError> restore_lineage_payload(std::span payload, const CheckpointManifest& m, std::size_t budget) { if (!structural(m)) return std::unexpected{CheckpointError::format}; if (!supported(m) || m.profile != CheckpointProfile::environmental_lineage_v1) return std::unexpected{CheckpointError::unsupported}; // Container header (56 bytes) and the nested envelope's magic and format. if (payload.size() != m.payload_bytes || payload.size() < 72) return std::unexpected{CheckpointError::payload}; Reader container{payload.subspan(8)}; Reader nested{payload.subspan(64)}; if (container.u(4) != processes::lineage_region_format || nested.u(8) != m.versions.envelope) return std::unexpected{CheckpointError::unsupported}; auto restored = processes::LineageRegion::restore(payload, {m.key.world, m.frame}, budget); if (!restored) return std::unexpected{restored.error() == processes::LineageRegionError::version ? CheckpointError::unsupported : CheckpointError::payload}; const auto& community = (*restored)->community(); if (community.progress().tick != m.end_tick || community.tick_microseconds() != m.tick_microseconds) return std::unexpected{CheckpointError::payload}; return std::move(*restored); } } // namespace evo::persistence