#pragma once // Private to src/persistence: payload codecs, verified uploads, receipt checks, tail // verification and full recovery shared by publication (checkpoint_store.cpp) and // clone/audit (region_clone.cpp). Not an installed header. #include "evo/persistence/checkpoint_store.hpp" #include "evo/persistence/sha256.hpp" #include #include #include namespace evo::persistence::detail { using std::chrono::milliseconds; struct Organisms { std::uint64_t producer{}, consumer{}; }; // Lifecycle agreement shared by both profiles: exactly one durable death per // terminal actor, none for an active one, never after the committed tick. inline bool lifecycle_agrees(const processes::EnvironmentalProgress& progress, Organisms organisms, std::span decisions, const RegionHead& head) { for (const auto actor : {Actor::producer, Actor::consumer}) { const auto terminal = actor == Actor::producer ? progress.producer_terminal : progress.consumer_terminal; const auto count = std::ranges::count_if( decisions, [&](const CommittedDecision& d) { return d.decision.actor == actor; }); if (count > 1 || (terminal == 1) != (count == 1)) return false; } return std::ranges::all_of(decisions, [&](const CommittedDecision& d) { const auto organism = d.decision.actor == Actor::producer ? organisms.producer : organisms.consumer; return d.decision.tick >= 1 && d.decision.tick <= head.end_tick && d.commit_sequence <= head.sequence && d.decision.organism == organism; }); } // Per-profile payload operations; publication and recovery paths are shared. struct EnvironmentalCodec { using State = processes::EnvironmentalCommunity; using Recovered = RecoveredCheckpoint; static constexpr auto profile = CheckpointProfile::environmental_v1; static auto snapshot(const State& s) { return s.snapshot(); } static std::uint64_t tick(const State& s) { return s.progress().tick; } static std::uint64_t quantum(const State& s) { return s.tick_microseconds(); } static Organisms organisms(const State&) { return {}; } static auto restore(std::span payload, const CheckpointManifest& m, std::size_t budget) { return restore_environmental_payload(payload, m, budget); } static bool reconcile(const State& s, std::span d, const RegionHead& head) { return lifecycle_agrees(s.progress(), organisms(s), d, head); } }; struct LineageCodec { using State = processes::LineageRegion; using Recovered = RecoveredLineageCheckpoint; static constexpr auto profile = CheckpointProfile::environmental_lineage_v1; static auto snapshot(const State& s) { return s.snapshot(); } static std::uint64_t tick(const State& s) { return s.community().progress().tick; } static std::uint64_t quantum(const State& s) { return s.community().tick_microseconds(); } static Organisms organisms(const State& s) { return {s.binding().producer, s.binding().consumer}; } static auto restore(std::span payload, const CheckpointManifest& m, std::size_t budget) { return restore_lineage_payload(payload, m, budget); } // Plus: each durable death is the archive's death, at the same tick. static bool reconcile(const State& s, std::span d, const RegionHead& head) { if (!lifecycle_agrees(s.community().progress(), organisms(s), d, head)) return false; return std::ranges::all_of(d, [&](const CommittedDecision& x) { const auto record = s.archive().organism(x.decision.organism); return record && !record->alive && record->died.value == x.decision.tick; }); } }; inline PublicationFailure fail(PublicationError kind, ObjectError object = {}) { return {kind, {}, object, {}}; } inline std::string hex_parameter(std::span bytes) { constexpr char digits[] = "0123456789abcdef"; std::string out = "\\x"; for (const auto b : bytes) { out.push_back(digits[b >> 4U]); out.push_back(digits[b & 0x0FU]); } return out; } inline std::expected put_verified(const FilesystemObjectStore& objects, const std::vector& bytes, const VerifiedObject& expected) { auto stored = objects.put(bytes); if (!stored) return std::unexpected{fail(PublicationError::upload, stored.error())}; auto back = objects.get(*stored); if (!back || *stored != expected || !std::ranges::equal(*back, bytes)) return std::unexpected{ fail(PublicationError::verify, back ? ObjectError::corrupt : back.error())}; return {}; } // The receipt must agree with the local manifest the database digested. inline std::expected confirm(const std::expected& published, std::vector manifest_bytes, const CheckpointManifest& manifest, PreparedCommit prepared) { if (!published) { const auto kind = published.error().kind == LeaseStoreError::unknown ? PublicationError::unknown : PublicationError::rejected; return std::unexpected{ PublicationFailure{kind, published.error(), {}, std::move(prepared)}}; } const auto digest = sha256(manifest_bytes); if (!digest || published->digest != *digest || published->sequence != manifest.sequence || published->commit != manifest.commit || published->end_tick != manifest.end_tick || published->frame != manifest.frame) return std::unexpected{fail(PublicationError::receipt)}; return CommittedCheckpoint{*published, std::move(manifest_bytes)}; } // Replays the head's recorded batch from its committed predecessor (ADR-0065). template std::expected verify_tail(Postgres& db, const FilesystemObjectStore& objects, RegionKey key, const CheckpointManifest& m, std::span head_payload, const typename Codec::State& head_state, std::span durable, std::size_t budget, milliseconds timeout) { const auto fail_with = [](RecoveryError kind) { return std::unexpected{RecoveryFailure{kind, {}}}; }; if (m.sequence == 0) { // Genesis has no batch. A clone genesis digests the outcomes it inherited // (ADR-0067); a provisioned genesis has none. std::vector inherited; for (const auto& d : durable) if (d.commit_sequence == 0) inherited.push_back(d.decision); bool agree = false; if (const auto block = encode_decisions(inherited, 0, m.end_tick); block) { const auto digest = sha256(*block); agree = inherited.empty() ? m.batch.decisions_sha256 == Sha256Digest{} : digest && *digest == m.batch.decisions_sha256; } if (!agree || inherited.size() != m.batch.decision_count) return fail_with(RecoveryError::history); return {}; } if (m.manifest_version != 2) return fail_with(RecoveryError::unsupported); auto trace_bytes = objects.get({m.batch.trace_sha256, m.batch.trace_bytes}); if (!trace_bytes) return fail_with(trace_bytes.error() == ObjectError::io ? RecoveryError::store : RecoveryError::tail); auto trace = decode_trace(*trace_bytes); const TraceHeader expected{static_cast(Codec::profile), key, m.predecessor_commit, m.predecessor_digest, m.begin_tick, m.end_tick}; if (!trace || trace->header != expected) return fail_with(RecoveryError::tail); auto predecessor = load_region_commit(db, key, m.sequence - 1, timeout); if (!predecessor) return predecessor.error().kind == LeaseStoreError::not_provisioned ? fail_with(RecoveryError::tail) : std::unexpected{RecoveryFailure{RecoveryError::store, predecessor.error()}}; const auto digest = sha256(predecessor->manifest); auto previous = decode_manifest(predecessor->manifest); if (!digest || *digest != predecessor->head.digest || predecessor->head.digest != m.predecessor_digest || predecessor->head.commit != m.predecessor_commit || !previous || previous->end_tick != m.begin_tick) return fail_with(RecoveryError::tail); auto base = objects.get({previous->payload_sha256, previous->payload_bytes}); if (!base) return fail_with(base.error() == ObjectError::io ? RecoveryError::store : RecoveryError::tail); auto replay = Codec::restore(*base, *previous, budget); if (!replay) return fail_with(RecoveryError::tail); for (const auto& step : trace->steps) { auto report = (*replay)->advance(step.report.tick, step.input); if (!report || *report != step.report) return fail_with(RecoveryError::tail); } const auto replayed = Codec::snapshot(**replay); if (!replayed || !std::ranges::equal(*replayed, head_payload)) return fail_with(RecoveryError::tail); // The head's durable outcomes are exactly those its trace derives. const auto organisms = Codec::organisms(head_state); const auto derived = derive_decisions(trace->steps, organisms.producer, organisms.consumer); std::vector recorded; for (const auto& d : durable) if (d.commit_sequence == m.sequence) recorded.push_back(d.decision); if (derived != recorded || derived.size() != m.batch.decision_count) return fail_with(RecoveryError::history); return {}; } template std::expected recover(Postgres& db, const FilesystemObjectStore& objects, RegionKey key, std::span retained_builds, std::size_t budget, milliseconds timeout) { const auto store_failure = [](const LeaseStoreFailure& f) { return std::unexpected{RecoveryFailure{f.kind == LeaseStoreError::not_provisioned ? RecoveryError::not_provisioned : RecoveryError::store, f}}; }; auto committed = load_region_checkpoint(db, key, timeout); if (!committed) return store_failure(committed.error()); const auto fail_with = [](RecoveryError kind) { return std::unexpected{RecoveryFailure{kind, {}}}; }; const auto digest = sha256(committed->manifest); auto manifest = decode_manifest(committed->manifest); const auto& head = committed->head; if (!digest || *digest != head.digest) return fail_with(RecoveryError::manifest); if (!manifest) return fail_with(manifest.error() == CheckpointError::unsupported ? RecoveryError::unsupported : RecoveryError::manifest); if (manifest->key != key || manifest->frame != head.frame || manifest->sequence != head.sequence || manifest->commit != head.commit || manifest->end_tick != head.end_tick) return fail_with(RecoveryError::manifest); if (!supported(*manifest) || manifest->profile != Codec::profile || std::ranges::find(retained_builds, manifest->build) == retained_builds.end()) return fail_with(RecoveryError::unsupported); auto payload = objects.get({manifest->payload_sha256, manifest->payload_bytes}); if (!payload) return fail_with(payload.error() == ObjectError::missing ? RecoveryError::missing_payload : payload.error() == ObjectError::corrupt ? RecoveryError::corrupt_payload : RecoveryError::store); auto state = Codec::restore(*payload, *manifest, budget); if (!state) return fail_with(RecoveryError::payload); // Durable permanent outcomes must agree with the restored state they finalized. auto decisions = load_region_decisions(db, key, timeout); if (!decisions) return store_failure(decisions.error()); // Outcomes of a link committed after the head was read (possible only when the // reader holds no lease, e.g. a clone) belong to that newer, separately verified // link. Every other durable outcome must agree with this head. std::erase_if(*decisions, [&](const CommittedDecision& d) { return d.commit_sequence > head.sequence; }); if (!Codec::reconcile(**state, *decisions, head)) return fail_with(RecoveryError::history); if (auto tail = verify_tail(db, objects, key, *manifest, *payload, **state, *decisions, budget, timeout); !tail) return std::unexpected{tail.error()}; return typename Codec::Recovered{std::move(*committed), *manifest, std::move(*state), std::move(*decisions)}; } } // namespace evo::persistence::detail