ADR-0063: manifest v2 (360 bytes) binds a per-tick validation trace object and a canonical decision block by SHA-256. Publication replays the trace from the committed predecessor's verified payload and requires every report and the candidate bytes, derives deaths deterministically, uploads payload and trace with verified read-back, then sends manifest and decisions to one fenced statement. RegionBatch seals at a terminal transition or 64 ticks and refuses ticks until durable confirmation. Schema v5 records the checkpoint, its decisions and outbox rows atomically; a unique index keeps one terminal outcome per actor (EVL08), triggers make commits/decisions immutable (EVL09), an exact retry of a committed ID returns the original receipt, changed bytes conflict, and read-only resolve_region_commit answers committed/absent/ conflict. Outbox pending/acknowledge give idempotent at-least-once delivery. Recovery reconciles durable deaths with restored lifecycle (and archive deaths for the lineage profile). Validated: Windows CTest 58/58; Linux GCC Debug/Release, clang-tidy and ASan/UBSan CTest 58/58 each; PostgreSQL suites Release, analysis, ASan (lost response, committed-after-timeout, terminated orphan retry, changed bytes, repeated/partial/reordered decisions, gap, outbox redelivery, history quarantine); five mutations each caught. No Docker/Gitea CI, process kill, broker or deployment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
123 lines
6.9 KiB
C++
123 lines
6.9 KiB
C++
#pragma once
|
|
#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 <chrono>
|
|
#include <expected>
|
|
#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;
|
|
};
|
|
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.
|
|
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.
|
|
};
|
|
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;
|
|
};
|
|
|
|
// 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);
|
|
// Loads and fully verifies the committed head and reconciles durable decisions.
|
|
// Readiness additionally 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);
|
|
[[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);
|
|
|
|
// 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
|