#pragma once #include "evo/persistence/life_reservation_store.hpp" #include "evo/persistence/object_store.hpp" #include "evo/persistence/region_batch.hpp" #include "evo/persistence/region_checkpoint.hpp" #include "evo/persistence/region_lease_store.hpp" #include "evo/server/lifecycle/cellular_batch.hpp" #include #include #include #include #include #include // Linux publication and recovery of region checkpoints (ADR-0061/0062/0063). // Batch order: replay the recorded trace from the committed predecessor payload // and require the candidate bytes -> derive decisions -> immutable payload and // trace uploads with verified read-back -> one fenced transaction recording // checkpoint, decisions and outbox. Nothing before the transaction has authority: // a failure there leaves the previous head and at most unreferenced orphan objects. // Permanent outcomes are final only when a receipt (publish or resolve) confirms them. namespace evo::persistence { enum class PublicationError : std::uint8_t { candidate, // State, batch or manifest is not a valid successor; nothing uploaded. predecessor, // Committed predecessor payload missing/corrupt/invalid: quarantine. digest, // Digest provider failure; nothing uploaded. upload, // Object write failed; no manifest was sent. verify, // Read-back differs from the candidate; no manifest was sent. rejected, // Database refused (see store); uploads are orphans. unknown, // Outcome unknown (see store): stay paused; resolve `prepared`. receipt, // Committed receipt disagrees with the local manifest: fail closed. }; // The exact bytes sent to the database. After `unknown`, resolve or retry only these. struct PreparedCommit { RegionKey key{}; Uuid commit{}; std::vector manifest; std::vector decisions; std::vector actions; // Schema v11 block; empty: published without actions. }; struct PublicationFailure { PublicationError kind{}; LeaseStoreFailure store{}; // Meaningful for rejected/unknown. ObjectError object{}; // Meaningful for upload/verify/predecessor. PreparedCommit prepared; // Present for rejected/unknown. }; // Durably confirmed batch: its decisions are now final and may be acknowledged. // Test/fault-injection seam: called after verified uploads, immediately before the // fenced transaction is sent. Production callers pass nothing. struct PublishHooks { std::function before_transaction; }; struct PublishedBatch { CommittedCheckpoint committed; std::vector decisions; }; enum class RecoveryError : std::uint8_t { store, // Database unavailable/failed (see store). not_provisioned, // No genesis: recovery never creates one. manifest, // Manifest bytes disagree with the committed digest/head. unsupported, // Profile/versions/build not in this host's retained allowlist. missing_payload, // Referenced object absent: quarantine, no older head. corrupt_payload, // Length/digest mismatch: quarantine, no older head. payload, // Verified bytes fail full state validation: quarantine. history, // Durable decisions disagree with the restored lifecycle: quarantine. tail, // Head batch evidence missing, corrupt or not reproducible: quarantine. }; struct RecoveryFailure { RecoveryError kind{}; LeaseStoreFailure store{}; }; struct RecoveredCheckpoint { CommittedCheckpoint committed; CheckpointManifest manifest; std::unique_ptr state; std::vector decisions; }; struct RecoveredLineageCheckpoint { CommittedCheckpoint committed; CheckpointManifest manifest; std::unique_ptr state; std::vector decisions; }; struct PrimitivePreparedCommit { RegionKey key{}; Uuid commit{}; std::vector manifest, trace; }; struct PrimitivePublicationFailure { PublicationError kind{}; LeaseStoreFailure store{}; ObjectError object{}; PrimitivePreparedCommit prepared; }; struct PublishedPrimitiveBatch { CommittedCheckpoint committed; }; struct RecoveredPrimitiveCheckpoint { CommittedCheckpoint committed; CheckpointManifest manifest; std::unique_ptr state; std::vector bindings; }; struct CellularPreparedCommit { RegionKey key{}; Uuid commit{}; std::vector manifest, trace, actions; // ADR-0121: the canonical mutation block and one result byte per record; both empty // when the trace carries no selections. std::vector mutations, results; }; struct CellularPublicationFailure { PublicationError kind{}; LeaseStoreFailure store{}; ObjectError object{}; CellularPreparedCommit prepared; }; struct CellularProfileMigrationPrepared { RegionKey key{}; Uuid commit{}; std::vector manifest; }; struct CellularProfileMigrationFailure { PublicationError kind{}; LeaseStoreFailure store{}; ObjectError object{}; CellularProfileMigrationPrepared prepared; }; struct PublishedCellularBatch { CommittedCheckpoint committed; // Each published mutation action's final result, in action-block order. std::vector mutation_results; }; struct RecoveredCellularCheckpoint { CommittedCheckpoint committed; CheckpointManifest manifest; std::unique_ptr state; std::vector actions; std::vector mutation_actions; std::vector mutation_results; }; // Owner/operator connection only: uploads a tick-0 state and records genesis. [[nodiscard]] std::expected provision_environmental_region( Postgres& owner, const FilesystemObjectStore& objects, RegionKey key, std::uint64_t frame, const processes::EnvironmentalCommunity& opening, Uuid commit, const Sha256Digest& build, std::size_t restore_budget, std::chrono::milliseconds timeout); // Publishes a sealed batch that began at `predecessor`, under `lease` (which the // caller has checked with LeaseAuthority::may_begin_commit). On success call // batch.confirm(end_tick); only then are its decisions final. [[nodiscard]] std::expected publish_environmental_batch(Postgres& db, const FilesystemObjectStore& objects, const LeaseGrant& lease, const CommittedCheckpoint& predecessor, const RegionBatch& batch, Uuid commit, const Sha256Digest& build, std::size_t restore_budget, std::chrono::milliseconds timeout, const PublishHooks& hooks = {}, std::span actions = {}); // Loads and fully verifies the committed head before any readiness (ADR-0065): // manifest digest and chain fields, retained build, payload length/SHA-256 and full // restore; then the head's tail: its trace object binds to the committed // predecessor, replaying it from the predecessor's verified payload reproduces the // head bytes, and its derived decisions equal the durable ones; finally every // durable decision agrees with the restored lifecycle. Any failure quarantines; // nothing older or empty is ever substituted. Readiness also requires a fresh // valid lease acquired before this call. [[nodiscard]] std::expected recover_environmental_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key, std::span retained_builds, std::size_t restore_budget, std::chrono::milliseconds timeout); // environmental-lineage-v1 (ADR-0062): the same order and guarantees, with the // LineageRegion container as payload. A region's profile never changes; each call // refuses a predecessor/committed head of the other profile. [[nodiscard]] std::expected provision_lineage_region(Postgres& owner, const FilesystemObjectStore& objects, RegionKey key, std::uint64_t frame, const processes::LineageRegion& opening, Uuid commit, const Sha256Digest& build, std::size_t restore_budget, std::chrono::milliseconds timeout); [[nodiscard]] std::expected publish_lineage_batch(Postgres& db, const FilesystemObjectStore& objects, const LeaseGrant& lease, const CommittedCheckpoint& predecessor, const RegionBatch& batch, Uuid commit, const Sha256Digest& build, std::size_t restore_budget, std::chrono::milliseconds timeout, const PublishHooks& hooks = {}, std::span actions = {}); [[nodiscard]] std::expected recover_lineage_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key, std::span retained_builds, std::size_t restore_budget, std::chrono::milliseconds timeout); // Primitive-life profile 3 stores a complete creation-only payload. Publication // replays the canonical birth trace from the verified predecessor before upload, // then uses schema v16's atomic reservation/control/checkpoint transaction. [[nodiscard]] std::expected provision_primitive_region(Postgres& owner, const FilesystemObjectStore& objects, RegionKey key, std::uint64_t frame, const server::PrimitiveLives& opening, Uuid commit, const Sha256Digest& build, std::chrono::milliseconds timeout); [[nodiscard]] std::expected publish_primitive_batch(Postgres& db, const FilesystemObjectStore& objects, const LeaseGrant& lease, const CommittedCheckpoint& predecessor, const server::PrimitiveBatch& batch, const server::PrimitiveLives& candidate, Uuid commit, const Sha256Digest& build, std::chrono::milliseconds timeout, const PublishHooks& hooks = {}); // Retry after an ambiguous response with these exact immutable bytes. The SQL // function converges exact retries and rejects changed bytes or stale authority. [[nodiscard]] std::expected retry_primitive_prepared(Postgres& db, const PrimitivePreparedCommit& prepared, std::chrono::milliseconds timeout); // Read-only recovery adapter. The caller must acquire a fresh region lease before // using the recovered state or declaring the host ready. [[nodiscard]] std::expected recover_primitive_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key, std::span retained_builds, std::chrono::milliseconds timeout); // Profile 4 publication replays the bounded cellular trace from the verified // predecessor and requires exact candidate bytes and action-to-life agreement. // Owner-only genesis provisioning accepts an empty profile-4 state. Player births // are durable runtime operations and cannot be smuggled into genesis. [[nodiscard]] std::expected provision_cellular_region(Postgres& owner, const FilesystemObjectStore& objects, RegionKey key, std::uint64_t frame, const server::CellularLives& opening, Uuid commit, const Sha256Digest& build, std::chrono::milliseconds timeout); [[nodiscard]] std::expected publish_cellular_batch(Postgres& db, const FilesystemObjectStore& objects, const LeaseGrant& lease, const CommittedCheckpoint& predecessor, const server::CellularBatch& batch, const server::CellularLives& candidate, Uuid commit, const Sha256Digest& build, std::chrono::milliseconds timeout, const PublishHooks& hooks = {}, std::span actions = {}, std::span mutation_actions = {}); [[nodiscard]] std::expected retry_cellular_prepared(Postgres& db, const CellularPreparedCommit& prepared, std::chrono::milliseconds timeout); [[nodiscard]] std::expected resolve_cellular_prepared(Postgres& db, const CellularPreparedCommit& prepared, std::chrono::milliseconds timeout); [[nodiscard]] std::expected recover_cellular_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key, const LeaseGrant& lease, std::span retained_builds, std::chrono::milliseconds timeout); // Read-only historical recovery with the SAME full replay/evidence validation. // Never select this state as a live head, resume an old owner or infer authority. [[nodiscard]] std::expected recover_cellular_commit(Postgres&, const FilesystemObjectStore&, RegionKey, std::uint64_t sequence, const LeaseGrant&, std::span retained_builds, std::chrono::milliseconds timeout); // Leased, no-tick representation migration. The v1 payload is restored and // converted in memory before one immutable v1-to-v2 migration commit is written. [[nodiscard]] std::expected migrate_cellular_profile_to_v2(Postgres& db, const FilesystemObjectStore& objects, const LeaseGrant& lease, const CommittedCheckpoint& predecessor, Uuid commit, const Sha256Digest& build, std::chrono::milliseconds timeout); [[nodiscard]] std::expected migrate_cellular_profile_to_v3(Postgres& db, const FilesystemObjectStore& objects, const LeaseGrant& lease, const CommittedCheckpoint& predecessor, Uuid commit, const Sha256Digest& build, std::chrono::milliseconds timeout); [[nodiscard]] std::expected retry_cellular_profile_migration(Postgres& db, const CellularProfileMigrationPrepared& prepared, std::chrono::milliseconds timeout); // Explicit same-profile bundle-9 -> 10 upgrade. No worker selects it implicitly. // Uses the immutable version-upgrade journal, including for population profile 5. [[nodiscard]] std::expected migrate_cellular_boundary_profile(Postgres&, const FilesystemObjectStore&, const LeaseGrant&, const CommittedCheckpoint&, Uuid commit, const Sha256Digest& build, std::chrono::milliseconds timeout, const PublishHooks& hooks = {}); // ADR-0158: explicit bundle 10 -> 11 maturation, same journal and exact retry contract. [[nodiscard]] std::expected migrate_cellular_maturation_profile(Postgres&, const FilesystemObjectStore&, const LeaseGrant&, const CommittedCheckpoint&, Uuid commit, const Sha256Digest& build, std::chrono::milliseconds timeout, const PublishHooks& hooks = {}); // Verify the recorded no-tick operation under current authority, replaying its // entire source/target payload. Version upgrades and profile transitions retain // separate evidence; neither is inferred solely from the target tuple. [[nodiscard]] std::expected verify_cellular_no_tick_checkpoint(Postgres&, const FilesystemObjectStore&, const LeaseGrant&, const CommittedCheckpoint&, const CheckpointManifest&, std::span payload, std::chrono::milliseconds timeout); // After an `unknown` publication: resolve exactly the prepared bytes. A committed // result yields the final batch; absent may be retried with the same prepared bytes // only while the lease is still valid; conflict fails closed. [[nodiscard]] std::expected resolve_prepared(Postgres& db, const PreparedCommit& prepared, std::chrono::milliseconds timeout); [[nodiscard]] std::expected retry_prepared(Postgres& db, const PreparedCommit& prepared, std::chrono::milliseconds timeout); } // namespace evo::persistence