Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 2m24s
Foundation / checks (network) (push) Successful in 20m40s
Foundation / checks (client) (push) Successful in 21m57s
Foundation / checks (tsan) (push) Successful in 26m32s
Foundation / checks (postgres) (push) Successful in 1h3m17s
Foundation / checks (checks) (push) Successful in 1h14m29s
Foundation / postgres-tools (push) Successful in 34s
Foundation / server-image (push) Successful in 4m6s
Foundation / image (push) Successful in 4m52s
251 lines
16 KiB
C++
251 lines
16 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 "evo/server/lifecycle/cellular_batch.hpp"
|
|
#include "evo/server/lifecycle/cellular_lives.hpp"
|
|
#include "evo/server/lifecycle/cellular_population_batch.hpp"
|
|
#include "evo/server/lifecycle/primitive_batch.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.
|
|
primitive_lives_v1 = 3, // Funded creation state; history_profile 2.
|
|
cellular_lives_v1 = 4, // Complete cellular state; history_profile 3 or 4.
|
|
cellular_population_v1 = 5, // Exact populations; cellular bundle 9, 10 or 11.
|
|
};
|
|
// history_profile 1: lineage archive format 1 with genome schema 1.
|
|
inline constexpr std::uint32_t lineage_history_profile = 1;
|
|
// Archive format 1, genome schema 2, development 2, founder-life rules 1.
|
|
inline constexpr std::uint32_t primitive_history_profile = 2;
|
|
inline constexpr std::uint32_t cellular_history_profile = 3;
|
|
inline constexpr std::uint32_t population_history_profile = 5;
|
|
inline constexpr std::uint32_t cellular_revision_history_profile = 4;
|
|
// 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{};
|
|
// No field or terrain state in this explicitly provisioned nursery profile.
|
|
inline constexpr VersionBundle primitive_v1_versions{1, 1, 1, 0, 0, 1, 1, 1, 1};
|
|
struct CellularVersionBundle {
|
|
std::uint32_t rules{1}, envelope{1}, habitat{1}, coordinate{1}, genome{1}, development{2},
|
|
founder{1}, archive{1}, mutation_state{};
|
|
friend bool operator==(const CellularVersionBundle&, const CellularVersionBundle&) = default;
|
|
};
|
|
inline constexpr CellularVersionBundle cellular_v1_versions{};
|
|
inline constexpr CellularVersionBundle cellular_v2_versions{2, 2, 1, 1, 1, 2, 1, 1, 1};
|
|
inline constexpr CellularVersionBundle cellular_v3_versions{2, 3, 1, 1, 1, 2, 1, 2, 1};
|
|
// ADR-0124: rules 3 (engulfment, detritus) and owner envelope 4 (corpse causes).
|
|
inline constexpr CellularVersionBundle cellular_v4_versions{3, 4, 1, 1, 1, 2, 1, 2, 1};
|
|
// ADR-0125: rules 4 (budding wildlife) and owner envelope 5 (bud sequence, parents).
|
|
inline constexpr CellularVersionBundle cellular_v5_versions{4, 5, 1, 1, 1, 2, 1, 2, 1};
|
|
// ADR-0128: rules 5 (offline freeze and resume) and owner envelope 6 (presence).
|
|
inline constexpr CellularVersionBundle cellular_v6_versions{5, 6, 1, 1, 1, 2, 1, 2, 1};
|
|
// 2026-10-15 balance: rules 6 on owner envelope 6, with development 3 and founder 2.
|
|
inline constexpr CellularVersionBundle cellular_v7_versions{6, 6, 1, 1, 1, 3, 2, 2, 1};
|
|
// ADR-0137: rules 7 on owner envelope 6, with development 4 and founder 3.
|
|
inline constexpr CellularVersionBundle cellular_v8_versions{7, 6, 1, 1, 1, 4, 3, 2, 1};
|
|
// ADR-0136 step A: rules 8 on owner envelope 6 with habitat 2 (pools and bubbles).
|
|
inline constexpr CellularVersionBundle cellular_v9_versions{8, 6, 2, 1, 1, 4, 3, 2, 1};
|
|
// ADR-0145: portable boundary accounting, unchanged rules 8 on owner envelope 7.
|
|
// Database publication requires its own explicit schema admission.
|
|
inline constexpr CellularVersionBundle cellular_v10_versions{8, 7, 2, 1, 1, 4, 3, 2, 1};
|
|
// ADR-0158: explicit funded maturation, retaining owner 7 and population envelope 2.
|
|
inline constexpr CellularVersionBundle cellular_v11_versions{9, 7, 2, 1, 1, 4, 3, 2, 1};
|
|
// Zero means this bundle has no population representation.
|
|
[[nodiscard]] constexpr std::uint32_t
|
|
population_envelope_version(const CellularVersionBundle& b) noexcept {
|
|
return b == cellular_v9_versions ? 1
|
|
: (b == cellular_v10_versions || b == cellular_v11_versions) ? 2
|
|
: 0;
|
|
}
|
|
// Bundles with genome revisions: the revision history profile and format-3 traces.
|
|
[[nodiscard]] constexpr bool cellular_revision_bundle(const CellularVersionBundle& b) noexcept {
|
|
return b == cellular_v3_versions || b == cellular_v4_versions || b == cellular_v5_versions ||
|
|
b == cellular_v6_versions || b == cellular_v7_versions || b == cellular_v8_versions ||
|
|
b == cellular_v9_versions || b == cellular_v10_versions || b == cellular_v11_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{};
|
|
// Zero at provisioned genesis. At a clone genesis (sequence 0, ADR-0067) they
|
|
// name the source commit and the SHA-256 of its manifest bytes.
|
|
Uuid predecessor_commit{};
|
|
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{};
|
|
CellularVersionBundle cellular_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; 1 lineage; 2 primitive lives.
|
|
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
|
|
: profile == CheckpointProfile::primitive_lives_v1 ? server::max_primitive_lives_bytes
|
|
: profile == CheckpointProfile::cellular_lives_v1 ? server::max_cellular_lives_bytes
|
|
: profile == CheckpointProfile::cellular_population_v1
|
|
? server::max_cellular_population_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);
|
|
// Portable reader support: history, exact versions, zero RNG and durability.
|
|
// This does not grant admission to a database schema or a publication operation.
|
|
[[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);
|
|
// Clone genesis (ADR-0067): sequence 0 of `target` in another world, at the source's
|
|
// end tick, whose predecessor fields name the source commit and manifest digest.
|
|
// Profile, versions, quantum, frame and build are inherited; `inherited` digests the
|
|
// source's permanent outcomes (no trace). The payload must be re-identified bytes.
|
|
[[nodiscard]] 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);
|
|
// 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);
|
|
// Leased, no-tick cellular representation migration. SQL publication independently
|
|
// verifies the exact adjacent profile transition.
|
|
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
|
|
cellular_profile_migration_manifest(const CheckpointManifest& predecessor,
|
|
const Sha256Digest& predecessor_digest, Uuid commit,
|
|
const LeaseGrant& lease, const Sha256Digest& build,
|
|
std::uint64_t payload_bytes,
|
|
const Sha256Digest& payload_sha256);
|
|
|
|
// 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);
|
|
// Creation-only profile: canonical funded closure, all births <= manifest tick,
|
|
// no organisms at genesis. Manifest owns the checkpoint clock; no biology steps.
|
|
// Length and SHA-256 must be verified by the object-store caller as above.
|
|
[[nodiscard]] std::expected<std::unique_ptr<server::PrimitiveLives>, CheckpointError>
|
|
restore_primitive_payload(std::span<const std::uint8_t> payload,
|
|
const CheckpointManifest& manifest);
|
|
[[nodiscard]] std::expected<std::unique_ptr<server::CellularLives>, CheckpointError>
|
|
restore_cellular_payload(std::span<const std::uint8_t> payload, const CheckpointManifest& manifest);
|
|
[[nodiscard]] std::expected<std::unique_ptr<server::CellularPopulation>, CheckpointError>
|
|
restore_population_payload(std::span<const std::uint8_t> payload,
|
|
const CheckpointManifest& manifest);
|
|
// Dedicated profile 4 <-> profile 5 transition, preserving bundle 9, 10 or 11 exactly.
|
|
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
|
|
population_profile_transition_manifest(const CheckpointManifest& predecessor,
|
|
const Sha256Digest& predecessor_digest, Uuid commit,
|
|
const LeaseGrant& lease, const Sha256Digest& build,
|
|
std::uint64_t payload_bytes,
|
|
const Sha256Digest& payload_sha256);
|
|
// Explicit portable bundle 9 -> 10 upgrade, preserving profile 4/5 and history.
|
|
// No tick, representation conversion, new genesis or downgrade. The caller must
|
|
// independently verify the predecessor manifest/payload SHA-256 bindings; neither
|
|
// these candidate bytes nor supported() confer publication authority.
|
|
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
|
|
cellular_boundary_upgrade_manifest(const CheckpointManifest& predecessor,
|
|
const Sha256Digest& predecessor_digest, Uuid commit,
|
|
const LeaseGrant& lease, const Sha256Digest& build,
|
|
std::uint64_t payload_bytes, const Sha256Digest& payload_sha256);
|
|
// Restores the complete bundle-9 source and derives an exact no-tick owner-7
|
|
// candidate; population policy, membership and conversion sequence are retained.
|
|
[[nodiscard]] std::expected<std::vector<std::uint8_t>, CheckpointError>
|
|
cellular_boundary_upgrade_payload(std::span<const std::uint8_t> payload,
|
|
const CheckpointManifest& predecessor);
|
|
// ADR-0158: exact same-profile, no-tick bundle 10 -> 11 maturation upgrade.
|
|
// The caller independently binds source SHA-256 and fenced publication authority.
|
|
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
|
|
cellular_maturation_upgrade_manifest(const CheckpointManifest& predecessor,
|
|
const Sha256Digest& predecessor_digest, Uuid commit,
|
|
const LeaseGrant& lease, const Sha256Digest& build,
|
|
std::uint64_t payload_bytes,
|
|
const Sha256Digest& payload_sha256);
|
|
[[nodiscard]] std::expected<std::vector<std::uint8_t>, CheckpointError>
|
|
cellular_maturation_upgrade_payload(std::span<const std::uint8_t> payload,
|
|
const CheckpointManifest& predecessor);
|
|
// Population manual conversion may publish at the same tick with a nonempty trace.
|
|
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError> population_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);
|
|
} // namespace evo::persistence
|