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>
This commit is contained in:
dingo
2026-09-28 15:25:27 -04:00
co-authored by Claude Opus 5.5
parent 07116446c6
commit 5d4f59f901
32 changed files with 2253 additions and 145 deletions
+220
View File
@@ -0,0 +1,220 @@
#include "evo/persistence/region_checkpoint.hpp"
#include <algorithm>
#include <ranges>
namespace evo::persistence {
namespace {
constexpr std::uint64_t manifest_magic = 0x314D43524F564541ULL; // "AEVORCM1"
constexpr std::uint32_t manifest_version = 1;
constexpr std::uint64_t maximum = ~std::uint64_t{0};
template <std::size_t N> bool zero(const std::array<std::uint8_t, N>& bytes) {
return std::ranges::all_of(bytes, [](std::uint8_t b) { return b == 0; });
}
class Writer {
public:
explicit Writer(std::vector<std::uint8_t>& out) : out_(out) {}
void u(std::uint64_t value, unsigned width) {
for (unsigned i = 0; i < width; ++i) {
out_.push_back(static_cast<std::uint8_t>(value & 0xFFU));
value >>= 8U;
}
}
template <std::size_t N> void bytes(const std::array<std::uint8_t, N>& value) {
out_.insert(out_.end(), value.begin(), value.end());
}
private:
std::vector<std::uint8_t>& out_;
};
class Reader {
public:
explicit Reader(std::span<const std::uint8_t> in) : in_(in) {}
std::uint64_t u(unsigned width) {
std::uint64_t value{};
for (unsigned i = 0; i < width; ++i)
value |= static_cast<std::uint64_t>(in_[at_ + i]) << (8U * i);
at_ += width;
return value;
}
template <std::size_t N> std::array<std::uint8_t, N> bytes() {
std::array<std::uint8_t, N> value{};
std::copy_n(in_.begin() + static_cast<std::ptrdiff_t>(at_), N, value.begin());
at_ += N;
return value;
}
private:
std::span<const std::uint8_t> in_;
std::size_t at_{};
};
// Every field, independent of which versions this build supports.
bool structural(const CheckpointManifest& m) noexcept {
if (m.key.world == 0 || m.key.region == 0 || m.frame == 0 || zero(m.commit) ||
m.tick_microseconds == 0 || zero(m.build) || m.payload_bytes == 0 ||
m.payload_bytes > max_environmental_payload_bytes || zero(m.payload_sha256))
return false;
if (m.sequence == 0)
return zero(m.predecessor_commit) && zero(m.predecessor_digest) && m.begin_tick == 0 &&
m.end_tick == 0 && zero(m.holder) && m.epoch == 0;
return !zero(m.predecessor_commit) && m.predecessor_commit != m.commit &&
!zero(m.predecessor_digest) && !zero(m.holder) && m.epoch != 0 &&
m.end_tick > m.begin_tick && m.end_tick - m.begin_tick <= max_checkpoint_ticks;
}
} // namespace
bool supported(const CheckpointManifest& m) noexcept {
return m.profile == CheckpointProfile::environmental_v1 &&
m.versions == environmental_v1_versions && m.rng_streams == 0 &&
m.history_profile == 0 && m.durability == DurabilityPolicy::single_volume_development;
}
std::expected<std::vector<std::uint8_t>, CheckpointError>
encode_manifest(const CheckpointManifest& m) {
if (!structural(m))
return std::unexpected{CheckpointError::format};
std::vector<std::uint8_t> out;
out.reserve(checkpoint_manifest_bytes);
Writer w{out};
w.u(manifest_magic, 8);
w.u(manifest_version, 4);
w.u(static_cast<std::uint8_t>(m.profile), 4);
w.u(m.key.world, 8);
w.u(m.key.region, 8);
w.u(m.frame, 8);
w.bytes(m.commit);
w.u(m.sequence, 8);
w.bytes(m.predecessor_commit);
w.bytes(m.predecessor_digest);
w.u(m.begin_tick, 8);
w.u(m.end_tick, 8);
w.bytes(m.holder);
w.u(m.epoch, 8);
w.u(m.tick_microseconds, 8);
for (const auto v : {m.versions.rules, m.versions.envelope, m.versions.resources,
m.versions.fields, m.versions.terrain, m.versions.coordinate,
m.versions.generator, m.versions.material, m.versions.interval_adapter})
w.u(v, 4);
w.bytes(m.build);
w.u(m.rng_streams, 4);
w.u(m.history_profile, 4);
w.u(static_cast<std::uint8_t>(m.durability), 4);
w.u(m.payload_bytes, 8);
w.bytes(m.payload_sha256);
return out;
}
std::expected<CheckpointManifest, CheckpointError>
decode_manifest(std::span<const std::uint8_t> bytes) {
if (bytes.size() != checkpoint_manifest_bytes)
return std::unexpected{CheckpointError::format};
Reader r{bytes};
if (r.u(8) != manifest_magic)
return std::unexpected{CheckpointError::format};
if (r.u(4) != manifest_version)
return std::unexpected{CheckpointError::unsupported};
CheckpointManifest m;
const auto profile = r.u(4);
m.profile =
profile <= 0xFFU ? static_cast<CheckpointProfile>(profile) : CheckpointProfile::unknown;
m.key.world = r.u(8);
m.key.region = r.u(8);
m.frame = r.u(8);
m.commit = r.bytes<16>();
m.sequence = r.u(8);
m.predecessor_commit = r.bytes<16>();
m.predecessor_digest = r.bytes<32>();
m.begin_tick = r.u(8);
m.end_tick = r.u(8);
m.holder = r.bytes<16>();
m.epoch = r.u(8);
m.tick_microseconds = r.u(8);
for (auto* v : {&m.versions.rules, &m.versions.envelope, &m.versions.resources,
&m.versions.fields, &m.versions.terrain, &m.versions.coordinate,
&m.versions.generator, &m.versions.material, &m.versions.interval_adapter})
*v = static_cast<std::uint32_t>(r.u(4));
m.build = r.bytes<32>();
m.rng_streams = static_cast<std::uint32_t>(r.u(4));
m.history_profile = static_cast<std::uint32_t>(r.u(4));
const auto durability = r.u(4);
m.durability =
durability <= 0xFFU ? static_cast<DurabilityPolicy>(durability) : DurabilityPolicy::unknown;
m.payload_bytes = r.u(8);
m.payload_sha256 = r.bytes<32>();
if (!structural(m))
return std::unexpected{CheckpointError::format};
return m;
}
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) {
CheckpointManifest m;
m.key = key;
m.frame = frame;
m.commit = commit;
m.tick_microseconds = tick_microseconds;
m.build = build;
m.payload_bytes = payload_bytes;
m.payload_sha256 = payload_sha256;
if (!structural(m))
return std::unexpected{CheckpointError::format};
return m;
}
std::expected<CheckpointManifest, CheckpointError>
successor_manifest(const CheckpointManifest& p, 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) {
// This build writes only its own versions; a change requires a migration (M7.9).
if (!supported(p))
return std::unexpected{CheckpointError::unsupported};
if (!structural(p) || p.sequence == maximum || lease.frame != p.frame ||
end_tick <= p.end_tick || end_tick - p.end_tick > max_checkpoint_ticks)
return std::unexpected{CheckpointError::chain};
CheckpointManifest m = p;
m.commit = commit;
m.sequence = p.sequence + 1;
m.predecessor_commit = p.commit;
m.predecessor_digest = predecessor_digest;
m.begin_tick = p.end_tick;
m.end_tick = end_tick;
m.holder = lease.holder;
m.epoch = lease.epoch;
m.build = build;
m.payload_bytes = payload_bytes;
m.payload_sha256 = payload_sha256;
if (!structural(m))
return std::unexpected{CheckpointError::format};
return m;
}
std::expected<std::unique_ptr<processes::EnvironmentalCommunity>, CheckpointError>
restore_environmental_payload(std::span<const std::uint8_t> payload, const CheckpointManifest& m,
std::size_t budget) {
if (!structural(m))
return std::unexpected{CheckpointError::format};
if (!supported(m))
return std::unexpected{CheckpointError::unsupported};
if (payload.size() != m.payload_bytes || payload.size() < 16)
return std::unexpected{CheckpointError::payload};
Reader header{payload};
header.u(8); // Envelope magic is checked by the envelope decoder itself.
if (header.u(8) != m.versions.envelope)
return std::unexpected{CheckpointError::unsupported};
auto restored =
processes::EnvironmentalCommunity::restore(payload, {m.key.world, m.frame}, budget);
if (!restored)
return std::unexpected{CheckpointError::payload};
const auto& state = **restored;
if (state.progress().tick != m.end_tick || state.tick_microseconds() != m.tick_microseconds)
return std::unexpected{CheckpointError::payload};
// Canonical: the restored state re-encodes to exactly the committed bytes.
const auto again = state.snapshot();
if (!again || !std::ranges::equal(*again, payload))
return std::unexpected{CheckpointError::payload};
return std::move(*restored);
}
} // namespace evo::persistence