Files
aevolution/include/evo/persistence/checkpoint_store.hpp
T
dingoandClaude Opus 5.5 1bbac48543 Publish mutation choices atomically with their checkpoint
ADR-0121, schema v35. A checkpoint whose trace carries mutation
selections publishes with its canonical mutation block and one result
byte per choice. SQL checks the block's order, matches each record to
one reserved choice of this region and to its trace selection (tick,
life, offer, operator, successor identity), binds it to the commit with
its result, refuses a choice already bound elsewhere and checks exact
retries. The four-argument publisher becomes an internal helper behind
a wrapper that refuses traces with selections.

C++ publication takes the results from its own replay rather than a
caller, prepared commits carry block and results through retry and
resolution, and recovery rebuilds the bound choices and requires the
replay's results to match. A PostgreSQL test feeds a v4 cell to its
first offer, publishes a reserved choice, recovers it and restarts a
host. Host and session admission follow in 11.4c-2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 19:23:39 -04:00

266 lines
15 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);
// 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);
// 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