Files
aevolution/include/evo/persistence/region_clone.hpp
T
dingoandClaude Opus 5.5 703f67834f Complete M7.9a region clones and retained-history audit
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>
2026-09-29 06:47:45 -04:00

105 lines
5.3 KiB
C++

#pragma once
#include "evo/persistence/checkpoint_store.hpp"
#include <chrono>
#include <cstdint>
#include <expected>
#include <functional>
#include <span>
// M7.9 region clones and history audit (ADR-0067). Linux only.
//
// A clone is a consistent cut: the verified committed head of a source region,
// re-identified into another world and provisioned there as a clone genesis whose
// manifest names the source commit and digest. The source session is made
// read-only before anything is read; nothing is ever written to the source. Order:
// full source recovery (payload, tail, outcomes) -> re-identify and prove the byte
// round trip -> verified target upload -> one owner transaction in the target
// database. A failure before that transaction leaves at most target orphans; the
// target is never partially provisioned. Rules, formats, quantum and build are
// inherited unchanged: a clone never converts versions.
namespace evo::persistence {
enum class CloneError : std::uint8_t {
identity, // Target is in the source world or has a zero ID; nothing read.
session, // The source session could not be made read-only; nothing read.
source, // Source head failed full recovery verification (see recovery).
candidate, // Re-identified payload, outcomes or manifest failed validation.
upload, // Target object write failed; nothing provisioned.
verify, // Target object read-back differs; nothing provisioned.
rejected, // Target database refused (see store); uploads are orphans.
unknown, // Target outcome unknown: load the target head before retrying.
receipt, // Target head disagrees with the clone manifest: fail closed.
};
struct CloneFailure {
CloneError kind{};
RecoveryFailure recovery{}; // Meaningful for source.
LeaseStoreFailure store{}; // Meaningful for session/rejected/unknown.
ObjectError object{}; // Meaningful for upload/verify.
};
struct CloneOrigin {
RegionKey source{};
std::uint64_t sequence{}, tick{};
Uuid commit{};
Sha256Digest digest{}; // SHA-256 of the source manifest bytes.
friend bool operator==(const CloneOrigin&, const CloneOrigin&) = default;
};
struct ClonedRegion {
CommittedCheckpoint genesis;
CloneOrigin origin;
std::size_t inherited_outcomes{};
};
// Test/fault-injection seam, called after the verified target upload and
// immediately before the target transaction. Production callers pass nothing.
struct CloneHooks {
std::function<void()> before_transaction;
};
// `source` is any connection that may read the region (it is switched to read-only
// transactions for the rest of its life); `target_owner` must be a different
// connection with the target database's owner role. The target store is opened for
// target_key. Both profiles are supported; the profile is read from the source head.
[[nodiscard]] std::expected<ClonedRegion, CloneFailure>
clone_region(Postgres& source, const FilesystemObjectStore& source_objects, RegionKey source_key,
Postgres& target_owner, const FilesystemObjectStore& target_objects,
RegionKey target_key, Uuid commit, std::span<const Sha256Digest> retained_builds,
std::size_t restore_budget, std::chrono::milliseconds timeout,
const CloneHooks& hooks = {});
enum class AuditError : std::uint8_t {
store, // Database unavailable/failed (see store).
not_provisioned, // No such region.
bounds, // More commits than the caller allowed; nothing concluded.
manifest, // A link's bytes disagree with its digest or position.
chain, // Links do not form one contiguous chain from genesis.
unsupported, // Profile/versions/build outside the retained allowlist.
missing_payload, // A referenced payload object is gone.
corrupt_payload, // A payload object has the wrong length or digest.
payload, // Verified bytes fail full state validation.
tail, // A link's trace is missing, corrupt or does not reproduce it.
history, // Durable outcomes disagree with a link or the head state.
};
struct AuditFailure {
AuditError kind{};
std::uint64_t sequence{}; // The first link that failed.
LeaseStoreFailure store{};
};
struct HistoryAudit {
std::uint64_t commits{}, end_tick{}, outcomes{};
CheckpointProfile profile{};
// A clone genesis names its origin commit and manifest digest; the source
// world/region is recorded only in the target database (region_origins).
bool clone{};
Uuid origin_commit{};
Sha256Digest origin_digest{};
};
// Retention evidence: verifies every committed link from genesis to the head, as
// recovery verifies the head alone. Each manifest matches its digest and chain
// position, each payload is present and restores, each trace replays its
// predecessor's payload to exactly its own, and each link's durable outcomes are
// exactly those derived; the head state agrees with all of them. At most
// `max_commits` links are examined. Read-only; no lease is needed.
[[nodiscard]] std::expected<HistoryAudit, AuditFailure>
audit_region_history(Postgres& db, const FilesystemObjectStore& objects, RegionKey key,
std::span<const Sha256Digest> retained_builds, std::size_t restore_budget,
std::uint64_t max_commits, std::chrono::milliseconds timeout);
} // namespace evo::persistence