Files
aevolution/include/evo/persistence/region_checkpoint.hpp
T
dingoandClaude Opus 5.5 dd7e8028b0 Complete M7.5 durable batch outcomes and commit resolution
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>
2026-09-28 17:30:30 -04:00

127 lines
6.8 KiB
C++

#pragma once
#include "evo/persistence/region_batch.hpp"
#include "evo/persistence/region_lease.hpp"
#include "evo/processes/environmental_community.hpp"
#include "evo/processes/lineage_region.hpp"
#include <cstddef>
#include <cstdint>
#include <expected>
#include <memory>
#include <span>
#include <vector>
// Region checkpoint manifest v1 and payload validation for environmental-v1
// (ADR-0061) and environmental-lineage-v1 (ADR-0062), schemas/region-commit.md. Portable and
// storage-free: digests are computed and objects are stored by the Linux adapters; this only
// encodes and validates.
namespace evo::persistence {
// Encoded as u32 on the wire; values above 255 decode as unknown (0), never truncated.
enum class CheckpointProfile : std::uint8_t {
unknown = 0,
environmental_v1 = 1, // Environmental envelope only; history_profile 0.
environmental_lineage_v1 = 2, // LineageRegion container; history_profile 1.
};
// history_profile 1: lineage archive format 1 with genome schema 1.
inline constexpr std::uint32_t lineage_history_profile = 1;
// Declared durability, verified at deployment. Development: one volume, no host-loss claim.
enum class DurabilityPolicy : std::uint8_t { unknown = 0, single_volume_development = 1 };
// Exact versions of every nested format/rule the payload depends on. The interval
// adapter carries no payload state but its version is still pinned.
struct VersionBundle {
std::uint32_t rules{2}, envelope{2}, resources{1}, fields{1}, terrain{1}, coordinate{1},
generator{1}, material{1}, interval_adapter{1};
friend bool operator==(const VersionBundle&, const VersionBundle&) = default;
};
inline constexpr VersionBundle environmental_v1_versions{};
// Batch evidence bound by manifest v2 (ADR-0063); all zero at genesis.
struct BatchDigests {
std::uint64_t trace_bytes{};
Sha256Digest trace_sha256{};
std::uint32_t decision_count{};
Sha256Digest decisions_sha256{}; // Zero exactly when there are no decisions.
friend bool operator==(const BatchDigests&, const BatchDigests&) = default;
};
struct CheckpointManifest {
// 2 is the only version written; 1 (M7.4, no batch evidence) still decodes.
std::uint32_t manifest_version{2};
CheckpointProfile profile{CheckpointProfile::environmental_v1};
RegionKey key{};
std::uint64_t frame{};
Uuid commit{};
std::uint64_t sequence{};
Uuid predecessor_commit{}; // Zero only at genesis.
Sha256Digest predecessor_digest{}; // SHA-256 of the predecessor manifest bytes.
std::uint64_t begin_tick{}, end_tick{};
Uuid holder{}; // Zero only at genesis (provisioning, not a lease).
std::uint64_t epoch{};
std::uint64_t tick_microseconds{};
VersionBundle versions{};
Sha256Digest build{}; // Retained immutable build artifact identity.
std::uint32_t rng_streams{}; // These rules use no randomness: 0.
std::uint32_t history_profile{}; // 0 environmental-v1; 1 environmental-lineage-v1.
DurabilityPolicy durability{DurabilityPolicy::single_volume_development};
std::uint64_t payload_bytes{};
Sha256Digest payload_sha256{};
BatchDigests batch{};
friend bool operator==(const CheckpointManifest&, const CheckpointManifest&) = default;
};
inline constexpr std::size_t checkpoint_manifest_v1_bytes = 280;
inline constexpr std::size_t checkpoint_manifest_bytes = 360;
inline constexpr std::size_t max_environmental_payload_bytes = std::size_t{1024} * 1024;
inline constexpr std::size_t max_lineage_payload_bytes = processes::max_lineage_region_bytes;
// Payload cap by profile; zero for an unknown profile.
[[nodiscard]] constexpr std::size_t max_payload_bytes(CheckpointProfile profile) noexcept {
return profile == CheckpointProfile::environmental_v1 ? max_environmental_payload_bytes
: profile == CheckpointProfile::environmental_lineage_v1 ? max_lineage_payload_bytes
: 0;
}
inline constexpr std::uint64_t max_checkpoint_ticks = 64;
enum class CheckpointError : std::uint8_t {
format, // Malformed or internally inconsistent manifest.
unsupported, // Unknown profile, version, RNG/history or durability declaration.
chain, // Not a valid successor of the committed predecessor.
payload, // Payload bytes fail full envelope validation or identity/tick checks.
};
// Structural validation of every field; versions/profile are checked separately
// so recovery can distinguish corruption from an unsupported (retained) format.
[[nodiscard]] std::expected<std::vector<std::uint8_t>, CheckpointError>
encode_manifest(const CheckpointManifest& manifest);
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
decode_manifest(std::span<const std::uint8_t> bytes);
// Profile with its history profile, exact versions, zero RNG and durability policy.
[[nodiscard]] bool supported(const CheckpointManifest& manifest) noexcept;
// Genesis for operator provisioning only; recovery never creates one.
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
genesis_manifest(RegionKey key, std::uint64_t frame, Uuid commit, std::uint64_t tick_microseconds,
const Sha256Digest& build, std::uint64_t payload_bytes,
const Sha256Digest& payload_sha256,
CheckpointProfile profile = CheckpointProfile::environmental_v1);
// Next link from the committed predecessor and its manifest digest under a lease.
// Profile, versions and quantum are inherited: a region never changes them.
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
successor_manifest(const CheckpointManifest& predecessor, const Sha256Digest& predecessor_digest,
Uuid commit, const LeaseGrant& lease, std::uint64_t end_tick,
const Sha256Digest& build, std::uint64_t payload_bytes,
const Sha256Digest& payload_sha256, const BatchDigests& batch);
// Fully restores payload bytes (envelope checksum, bounds and replay audit), then
// requires manifest identity, end tick, tick quantum, envelope format 2 and a
// byte-identical canonical re-encoding. The caller verifies length and SHA-256.
[[nodiscard]] std::expected<std::unique_ptr<processes::EnvironmentalCommunity>, CheckpointError>
restore_environmental_payload(std::span<const std::uint8_t> payload,
const CheckpointManifest& manifest, std::size_t budget);
// environmental-lineage-v1: restores the container (envelope replay audit, archive
// replay through its invariants, closure) with the same identity/tick/quantum,
// nested envelope format 2 and canonical checks.
[[nodiscard]] std::expected<std::unique_ptr<processes::LineageRegion>, CheckpointError>
restore_lineage_payload(std::span<const std::uint8_t> payload, const CheckpointManifest& manifest,
std::size_t budget);
} // namespace evo::persistence