Clone a verified committed head into an isolated world and database (ADR-0067): world re-identification with a proven byte round trip, a schema v7 clone genesis naming the source commit and digest with digested inherited outcomes, a read-only source session, an owner-only atomic target transaction and the evo-world-clone tool. audit_region_history re-verifies every retained link. Real-process tests cover trajectory equality after the cut, source isolation, killed clones and retention. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
322 lines
14 KiB
C++
322 lines
14 KiB
C++
#include "evo/persistence/region_checkpoint.hpp"
|
|
#include <algorithm>
|
|
#include <ranges>
|
|
|
|
namespace evo::persistence {
|
|
namespace {
|
|
constexpr std::uint64_t manifest_magic = 0x314D43524F564541ULL; // "AEVORCM1"
|
|
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 {
|
|
// An unknown profile is unsupported, not malformed: bound it by the largest cap.
|
|
const auto cap = max_payload_bytes(m.profile);
|
|
const auto limit = cap == 0 ? max_lineage_payload_bytes : cap;
|
|
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 > limit || zero(m.payload_sha256))
|
|
return false;
|
|
const auto& b = m.batch;
|
|
if (m.manifest_version != 1 && m.manifest_version != 2)
|
|
return false;
|
|
const bool no_batch = b == BatchDigests{};
|
|
if (m.sequence == 0) {
|
|
const bool genesis = zero(m.holder) && m.epoch == 0 && m.begin_tick == m.end_tick &&
|
|
b.trace_bytes == 0 && zero(b.trace_sha256);
|
|
if (zero(m.predecessor_commit) && zero(m.predecessor_digest))
|
|
return genesis && m.end_tick == 0 && no_batch;
|
|
// Clone genesis (ADR-0067, v2 only): the origin is the source commit and
|
|
// manifest digest; the block digests inherited permanent outcomes.
|
|
return genesis && m.manifest_version == 2 && !zero(m.predecessor_commit) &&
|
|
!zero(m.predecessor_digest) && m.predecessor_commit != m.commit &&
|
|
b.decision_count <= max_batch_decisions &&
|
|
(b.decision_count == 0) == zero(b.decisions_sha256);
|
|
}
|
|
const bool link = !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;
|
|
if (m.manifest_version == 1)
|
|
return link && no_batch;
|
|
// v2: the trace has exactly one step per tick; decisions are bounded.
|
|
return link && b.trace_bytes == trace_bytes_for(m.end_tick - m.begin_tick) &&
|
|
!zero(b.trace_sha256) && b.decision_count <= max_batch_decisions &&
|
|
(b.decision_count == 0) == zero(b.decisions_sha256);
|
|
}
|
|
} // namespace
|
|
|
|
bool supported(const CheckpointManifest& m) noexcept {
|
|
const bool profile =
|
|
(m.profile == CheckpointProfile::environmental_v1 && m.history_profile == 0) ||
|
|
(m.profile == CheckpointProfile::environmental_lineage_v1 &&
|
|
m.history_profile == lineage_history_profile);
|
|
return profile && m.versions == environmental_v1_versions && m.rng_streams == 0 &&
|
|
m.durability == DurabilityPolicy::single_volume_development;
|
|
}
|
|
|
|
std::expected<std::vector<std::uint8_t>, CheckpointError>
|
|
encode_manifest(const CheckpointManifest& m) {
|
|
if (!structural(m) || m.manifest_version != 2)
|
|
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(m.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);
|
|
w.u(m.batch.trace_bytes, 8);
|
|
w.bytes(m.batch.trace_sha256);
|
|
w.u(m.batch.decision_count, 4);
|
|
w.u(0, 4);
|
|
w.bytes(m.batch.decisions_sha256);
|
|
return out;
|
|
}
|
|
|
|
std::expected<CheckpointManifest, CheckpointError>
|
|
decode_manifest(std::span<const std::uint8_t> bytes) {
|
|
if (bytes.size() < 12)
|
|
return std::unexpected{CheckpointError::format};
|
|
Reader r{bytes};
|
|
if (r.u(8) != manifest_magic)
|
|
return std::unexpected{CheckpointError::format};
|
|
CheckpointManifest m;
|
|
m.manifest_version = static_cast<std::uint32_t>(r.u(4));
|
|
if (m.manifest_version != 1 && m.manifest_version != 2)
|
|
return std::unexpected{CheckpointError::unsupported};
|
|
if (bytes.size() !=
|
|
(m.manifest_version == 1 ? checkpoint_manifest_v1_bytes : checkpoint_manifest_bytes))
|
|
return std::unexpected{CheckpointError::format};
|
|
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 (m.manifest_version == 2) {
|
|
m.batch.trace_bytes = r.u(8);
|
|
m.batch.trace_sha256 = r.bytes<32>();
|
|
m.batch.decision_count = static_cast<std::uint32_t>(r.u(4));
|
|
if (r.u(4) != 0)
|
|
return std::unexpected{CheckpointError::format}; // Reserved.
|
|
m.batch.decisions_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, CheckpointProfile profile) {
|
|
CheckpointManifest m;
|
|
m.profile = profile;
|
|
m.history_profile =
|
|
profile == CheckpointProfile::environmental_lineage_v1 ? lineage_history_profile : 0;
|
|
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>
|
|
clone_manifest(const CheckpointManifest& source, const Sha256Digest& source_digest,
|
|
RegionKey target, Uuid commit, std::uint64_t payload_bytes,
|
|
const Sha256Digest& payload_sha256, const BatchDigests& inherited) {
|
|
if (!supported(source))
|
|
return std::unexpected{CheckpointError::unsupported};
|
|
if (!structural(source) || target.world == source.key.world || commit == source.commit ||
|
|
inherited.trace_bytes != 0 || !zero(inherited.trace_sha256))
|
|
return std::unexpected{CheckpointError::chain};
|
|
CheckpointManifest m = source;
|
|
m.manifest_version = 2;
|
|
m.key = target;
|
|
m.commit = commit;
|
|
m.sequence = 0;
|
|
m.predecessor_commit = source.commit;
|
|
m.predecessor_digest = source_digest;
|
|
m.begin_tick = source.end_tick;
|
|
m.holder = {};
|
|
m.epoch = 0;
|
|
m.payload_bytes = payload_bytes;
|
|
m.payload_sha256 = payload_sha256;
|
|
m.batch = inherited;
|
|
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,
|
|
const BatchDigests& batch) {
|
|
// 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.manifest_version = 2;
|
|
m.batch = batch;
|
|
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) || m.profile != CheckpointProfile::environmental_v1)
|
|
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);
|
|
}
|
|
|
|
std::expected<std::unique_ptr<processes::LineageRegion>, CheckpointError>
|
|
restore_lineage_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) || m.profile != CheckpointProfile::environmental_lineage_v1)
|
|
return std::unexpected{CheckpointError::unsupported};
|
|
// Container header (56 bytes) and the nested envelope's magic and format.
|
|
if (payload.size() != m.payload_bytes || payload.size() < 72)
|
|
return std::unexpected{CheckpointError::payload};
|
|
Reader container{payload.subspan(8)};
|
|
Reader nested{payload.subspan(64)};
|
|
if (container.u(4) != processes::lineage_region_format || nested.u(8) != m.versions.envelope)
|
|
return std::unexpected{CheckpointError::unsupported};
|
|
auto restored = processes::LineageRegion::restore(payload, {m.key.world, m.frame}, budget);
|
|
if (!restored)
|
|
return std::unexpected{restored.error() == processes::LineageRegionError::version
|
|
? CheckpointError::unsupported
|
|
: CheckpointError::payload};
|
|
const auto& community = (*restored)->community();
|
|
if (community.progress().tick != m.end_tick ||
|
|
community.tick_microseconds() != m.tick_microseconds)
|
|
return std::unexpected{CheckpointError::payload};
|
|
return std::move(*restored);
|
|
}
|
|
} // namespace evo::persistence
|