Files
aevolution/include/evo/persistence/checkpoint_store.hpp
T
dingoandClaude Opus 5.5 5d4f59f901 Implement M7.4a checkpoint publication and verified recovery
ADR-0061 publishes environmental-v1 full checkpoints. Manifest v1 is a
fixed 280-byte record (identity, chain, lease, versions, build, zero
RNG/history declarations, durability policy, payload length/SHA-256)
that PostgreSQL parses and digests itself. Schema v3 adds region_commits
with a digest CHECK and a composite head FK, owner-managed retained
builds, fenced publish/load functions and owner-only genesis; it drops
the bare v2 head kernel and fails closed while v2 heads exist.

Linux evo::region_store adds OpenSSL SHA-256, an immutable
content-addressed filesystem object store (temp+fsync+link, no
overwrite/delete, O_NOFOLLOW exact-length verified reads), and
publication (validate -> upload -> read back -> fenced transaction ->
receipt check) and recovery (re-digest, allowlist, verify, full restore).
Portable evo::region_checkpoint holds the codec and payload validation.

Validated: Windows CTest 56/56; WSL Release, clang-tidy and ASan/UBSan
private-PostgreSQL suites; four SQL and one host mutation each caught.
M7.4 stays open for 7.4b (lineage archive codec and history binding).
No Docker/Gitea CI, remote store, process kill or deployment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 15:25:27 -04:00

69 lines
3.7 KiB
C++

#pragma once
#include "evo/persistence/object_store.hpp"
#include "evo/persistence/region_checkpoint.hpp"
#include "evo/persistence/region_lease_store.hpp"
#include <chrono>
#include <expected>
#include <memory>
#include <span>
// Linux publication and recovery of environmental-v1 checkpoints (ADR-0061).
// Order: validate candidate -> immutable upload -> verified read-back -> fenced
// manifest transaction. Nothing before the transaction has authority; a failure
// there leaves the previous head and at most an unreferenced orphan object.
namespace evo::persistence {
enum class PublicationError : std::uint8_t {
candidate, // State/manifest not a valid successor; nothing uploaded.
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); the upload is an orphan.
unknown, // Outcome unknown (see store); stay paused and reconcile the head.
receipt, // Committed receipt disagrees with the local manifest: fail closed.
};
struct PublicationFailure {
PublicationError kind{};
LeaseStoreFailure store{}; // Meaningful for rejected/unknown.
ObjectError object{}; // Meaningful for upload/verify.
};
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.
};
struct RecoveryFailure {
RecoveryError kind{};
LeaseStoreFailure store{};
};
struct RecoveredCheckpoint {
CommittedCheckpoint committed;
CheckpointManifest manifest;
std::unique_ptr<processes::EnvironmentalCommunity> state;
};
// 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 `state` as the successor of `predecessor` under `lease`. The caller
// must hold the committed predecessor it simulated from and a lease that may
// begin a commit (LeaseAuthority::may_begin_commit).
[[nodiscard]] std::expected<CommittedCheckpoint, PublicationFailure>
publish_environmental_checkpoint(Postgres& db, const FilesystemObjectStore& objects,
const LeaseGrant& lease, const CommittedCheckpoint& predecessor,
const processes::EnvironmentalCommunity& state, Uuid commit,
const Sha256Digest& build, std::size_t restore_budget,
std::chrono::milliseconds timeout);
// Loads and fully verifies the committed head. Readiness additionally requires a
// fresh valid lease acquired before this call (M7.7); this does not grant one.
[[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);
} // namespace evo::persistence