Files
aevolution/include/evo/persistence/checkpoint_store.hpp
T
dingo ff121c3ed1
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m27s
Foundation / postgres-tools (push) Successful in 30s
Foundation / server-image (push) Successful in 4m16s
Foundation / image (push) Successful in 4m54s
feat(cellular): seed dev wildlife and tune budding playtests
2026-10-26 12:01:57 -04:00

320 lines
19 KiB
C++

#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 <chrono>
#include <expected>
#include <functional>
#include <memory>
#include <span>
#include <vector>
// 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<std::uint8_t> manifest;
std::vector<std::uint8_t> decisions;
std::vector<std::uint8_t> 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<void()> before_transaction;
};
struct PublishedBatch {
CommittedCheckpoint committed;
std::vector<BatchDecision> 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<processes::EnvironmentalCommunity> state;
std::vector<CommittedDecision> decisions;
};
struct RecoveredLineageCheckpoint {
CommittedCheckpoint committed;
CheckpointManifest manifest;
std::unique_ptr<processes::LineageRegion> state;
std::vector<CommittedDecision> decisions;
};
struct PrimitivePreparedCommit {
RegionKey key{};
Uuid commit{};
std::vector<std::uint8_t> 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<server::PrimitiveLives> state;
std::vector<PrimitiveLifeBinding> bindings;
};
struct CellularPreparedCommit {
RegionKey key{};
Uuid commit{};
std::vector<std::uint8_t> 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<std::uint8_t> mutations, results;
};
struct CellularPublicationFailure {
PublicationError kind{};
LeaseStoreFailure store{};
ObjectError object{};
CellularPreparedCommit prepared;
};
struct CellularProfileMigrationPrepared {
RegionKey key{};
Uuid commit{};
std::vector<std::uint8_t> 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<server::CellularMutationResult> mutation_results;
};
struct RecoveredCellularCheckpoint {
CommittedCheckpoint committed;
CheckpointManifest manifest;
std::unique_ptr<server::CellularLives> state;
std::vector<server::CellularActionRecord> actions;
std::vector<server::CellularMutationActionRecord> mutation_actions;
std::vector<server::CellularMutationResult> mutation_results;
};
// Owner/operator connection only: uploads a tick-0 state and records genesis.
[[nodiscard]] std::expected<CommittedCheckpoint, PublicationFailure> 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<PublishedBatch, PublicationFailure>
publish_environmental_batch(Postgres& db, const FilesystemObjectStore& objects,
const LeaseGrant& lease, const CommittedCheckpoint& predecessor,
const RegionBatch<processes::EnvironmentalCommunity>& batch,
Uuid commit, const Sha256Digest& build, std::size_t restore_budget,
std::chrono::milliseconds timeout, const PublishHooks& hooks = {},
std::span<const ActionRecord> 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<RecoveredCheckpoint, RecoveryFailure>
recover_environmental_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key,
std::span<const Sha256Digest> 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<CommittedCheckpoint, PublicationFailure>
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<PublishedBatch, PublicationFailure>
publish_lineage_batch(Postgres& db, const FilesystemObjectStore& objects, const LeaseGrant& lease,
const CommittedCheckpoint& predecessor,
const RegionBatch<processes::LineageRegion>& batch, Uuid commit,
const Sha256Digest& build, std::size_t restore_budget,
std::chrono::milliseconds timeout, const PublishHooks& hooks = {},
std::span<const ActionRecord> actions = {});
[[nodiscard]] std::expected<RecoveredLineageCheckpoint, RecoveryFailure>
recover_lineage_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key,
std::span<const Sha256Digest> 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<CommittedCheckpoint, PrimitivePublicationFailure>
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<PublishedPrimitiveBatch, PrimitivePublicationFailure>
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<CommittedCheckpoint, PrimitivePublicationFailure>
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<RecoveredPrimitiveCheckpoint, RecoveryFailure>
recover_primitive_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key,
std::span<const Sha256Digest> 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<CommittedCheckpoint, CellularPublicationFailure>
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<PublishedCellularBatch, CellularPublicationFailure>
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<const server::CellularActionRecord> actions = {},
std::span<const server::CellularMutationActionRecord> mutation_actions = {});
[[nodiscard]] std::expected<CommittedCheckpoint, CellularPublicationFailure>
retry_cellular_prepared(Postgres& db, const CellularPreparedCommit& prepared,
std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<ResolvedCommit, LeaseStoreFailure>
resolve_cellular_prepared(Postgres& db, const CellularPreparedCommit& prepared,
std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<RecoveredCellularCheckpoint, RecoveryFailure>
recover_cellular_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key,
const LeaseGrant& lease, std::span<const Sha256Digest> 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<RecoveredCellularCheckpoint, RecoveryFailure>
recover_cellular_commit(Postgres&, const FilesystemObjectStore&, RegionKey, std::uint64_t sequence,
const LeaseGrant&, std::span<const Sha256Digest> 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<CommittedCheckpoint, CellularProfileMigrationFailure>
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<CommittedCheckpoint, CellularProfileMigrationFailure>
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<CommittedCheckpoint, CellularProfileMigrationFailure>
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<CommittedCheckpoint, CellularProfileMigrationFailure>
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<CommittedCheckpoint, CellularProfileMigrationFailure>
migrate_cellular_maturation_profile(Postgres&, const FilesystemObjectStore&, const LeaseGrant&,
const CommittedCheckpoint&, Uuid commit,
const Sha256Digest& build, std::chrono::milliseconds timeout,
const PublishHooks& hooks = {});
// ADR-0168: explicit raw-only bundle 11 -> 12, retaining complete source evidence.
[[nodiscard]] std::expected<CommittedCheckpoint, CellularProfileMigrationFailure>
migrate_cellular_inheritance_profile(Postgres&, const FilesystemObjectStore&, const LeaseGrant&,
const CommittedCheckpoint&, Uuid commit,
const Sha256Digest& build, std::chrono::milliseconds timeout,
const PublishHooks& hooks = {});
// ADR-0176: explicit raw-only bundle 12 -> 13, declaring the region's light.
[[nodiscard]] std::expected<CommittedCheckpoint, CellularProfileMigrationFailure>
migrate_cellular_photosynthesis_profile(Postgres&, const FilesystemObjectStore&, const LeaseGrant&,
const CommittedCheckpoint&, Uuid commit,
const Sha256Digest& build, server::CellularLight light,
std::chrono::milliseconds timeout,
const PublishHooks& hooks = {});
// Rules 12: explicit raw-only bundle 13 -> 14, declaring the region's liquid rules.
[[nodiscard]] std::expected<CommittedCheckpoint, CellularProfileMigrationFailure>
migrate_cellular_liquid_profile(Postgres&, const FilesystemObjectStore&, const LeaseGrant&,
const CommittedCheckpoint&, Uuid commit, const Sha256Digest& build,
const server::CellularLiquidRules& rules,
std::chrono::milliseconds timeout, const PublishHooks& hooks = {});
// Rules 13: explicit raw-only bundle 14 -> 15, declaring the region's revamp rules.
[[nodiscard]] std::expected<CommittedCheckpoint, CellularProfileMigrationFailure>
migrate_cellular_revamp_profile(Postgres&, const FilesystemObjectStore&, const LeaseGrant&,
const CommittedCheckpoint&, Uuid commit, const Sha256Digest& build,
const server::CellularRevampRules& rules,
std::chrono::milliseconds timeout, const PublishHooks& hooks = {},
std::uint32_t playtest_wildlife_count = 0,
std::uint64_t playtest_first_identity = 0);
// 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<void, RecoveryFailure>
verify_cellular_no_tick_checkpoint(Postgres&, const FilesystemObjectStore&, const LeaseGrant&,
const CommittedCheckpoint&, const CheckpointManifest&,
std::span<const std::uint8_t> 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<ResolvedCommit, LeaseStoreFailure>
resolve_prepared(Postgres& db, const PreparedCommit& prepared, std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
retry_prepared(Postgres& db, const PreparedCommit& prepared, std::chrono::milliseconds timeout);
} // namespace evo::persistence