#pragma once #include "evo/persistence/checkpoint_store.hpp" #include #include #include #include #include // M7.9 region clones and history audit (ADR-0067). Linux only. // // A clone is a consistent cut: the verified committed head of a source region, // re-identified into another world and provisioned there as a clone genesis whose // manifest names the source commit and digest. The source session is made // read-only before anything is read; nothing is ever written to the source. Order: // full source recovery (payload, tail, outcomes) -> re-identify and prove the byte // round trip -> verified target upload -> one owner transaction in the target // database. A failure before that transaction leaves at most target orphans; the // target is never partially provisioned. Rules, formats, quantum and build are // inherited unchanged: a clone never converts versions. namespace evo::persistence { enum class CloneError : std::uint8_t { identity, // Target is in the source world or has a zero ID; nothing read. session, // The source session could not be made read-only; nothing read. source, // Source head failed full recovery verification (see recovery). candidate, // Re-identified payload, outcomes or manifest failed validation. upload, // Target object write failed; nothing provisioned. verify, // Target object read-back differs; nothing provisioned. rejected, // Target database refused (see store); uploads are orphans. unknown, // Target outcome unknown: load the target head before retrying. receipt, // Target head disagrees with the clone manifest: fail closed. }; struct CloneFailure { CloneError kind{}; RecoveryFailure recovery{}; // Meaningful for source. LeaseStoreFailure store{}; // Meaningful for session/rejected/unknown. ObjectError object{}; // Meaningful for upload/verify. }; struct CloneOrigin { RegionKey source{}; std::uint64_t sequence{}, tick{}; Uuid commit{}; Sha256Digest digest{}; // SHA-256 of the source manifest bytes. friend bool operator==(const CloneOrigin&, const CloneOrigin&) = default; }; struct ClonedRegion { CommittedCheckpoint genesis; CloneOrigin origin; std::size_t inherited_outcomes{}; }; // Test/fault-injection seam, called after the verified target upload and // immediately before the target transaction. Production callers pass nothing. struct CloneHooks { std::function before_transaction; }; // `source` is any connection that may read the region (it is switched to read-only // transactions for the rest of its life); `target_owner` must be a different // connection with the target database's owner role. The target store is opened for // target_key. Both profiles are supported; the profile is read from the source head. [[nodiscard]] std::expected clone_region(Postgres& source, const FilesystemObjectStore& source_objects, RegionKey source_key, Postgres& target_owner, const FilesystemObjectStore& target_objects, RegionKey target_key, Uuid commit, std::span retained_builds, std::size_t restore_budget, std::chrono::milliseconds timeout, const CloneHooks& hooks = {}); enum class AuditError : std::uint8_t { store, // Database unavailable/failed (see store). not_provisioned, // No such region. bounds, // More commits than the caller allowed; nothing concluded. manifest, // A link's bytes disagree with its digest or position. chain, // Links do not form one contiguous chain from genesis. unsupported, // Profile/versions/build outside the retained allowlist. missing_payload, // A referenced payload object is gone. corrupt_payload, // A payload object has the wrong length or digest. payload, // Verified bytes fail full state validation. tail, // A link's trace is missing, corrupt or does not reproduce it. history, // Durable outcomes disagree with a link or the head state. }; struct AuditFailure { AuditError kind{}; std::uint64_t sequence{}; // The first link that failed. LeaseStoreFailure store{}; }; struct HistoryAudit { std::uint64_t commits{}, end_tick{}, outcomes{}; CheckpointProfile profile{}; // A clone genesis names its origin commit and manifest digest; the source // world/region is recorded only in the target database (region_origins). bool clone{}; Uuid origin_commit{}; Sha256Digest origin_digest{}; }; // Retention evidence: verifies every committed link from genesis to the head, as // recovery verifies the head alone. Each manifest matches its digest and chain // position, each payload is present and restores, each trace replays its // predecessor's payload to exactly its own, and each link's durable outcomes are // exactly those derived; the head state agrees with all of them. At most // `max_commits` links are examined. Read-only; no lease is needed. [[nodiscard]] std::expected audit_region_history(Postgres& db, const FilesystemObjectStore& objects, RegionKey key, std::span retained_builds, std::size_t restore_budget, std::uint64_t max_commits, std::chrono::milliseconds timeout); // M8.9 upgrade comparison (ADR-0076). Before a build replaces another at a barrier, // both run the same inputs on clones of one cut (accelerated), and their histories // must be the same world: equal head tick, frame, quantum, versions and profile; // identical head states once B is rebound to A's world; identical durable outcomes // (tick, actor, outcome, organism), including those inherited at clone genesis. // Builds may differ; nothing else may. Both histories are fully audited first. // Read-only. A rules or format change cannot pass (no converter exists, ADR-0068). enum class CompareError : std::uint8_t { identity, // Same key, a zero ID, or different region IDs (only worlds rebind). audit, // Either history failed its audit (see audit and side). ticks, // Heads at different ticks: nothing compared. versions, // Frame, quantum, versions or profile differ. state, // Head states differ after rebinding B to A's world. outcomes, // Durable outcome histories differ. }; struct CompareFailure { CompareError kind{}; AuditFailure audit{}; // Meaningful for audit. char side{}; // 'a' or 'b' for audit. }; struct HistoryComparison { std::uint64_t tick{}, outcomes{}, commits_a{}, commits_b{}; Sha256Digest state{}; // SHA-256 of the identical head state, in A's world. }; [[nodiscard]] std::expected compare_region_histories(Postgres& db_a, const FilesystemObjectStore& objects_a, RegionKey a, Postgres& db_b, const FilesystemObjectStore& objects_b, RegionKey b, std::span retained_builds, std::size_t restore_budget, std::uint64_t max_commits, std::chrono::milliseconds timeout); } // namespace evo::persistence