Files
aevolution/include/evo/persistence/region_checkpoint.hpp
T
dingoandClaude Opus 5.5 b73ccbae9a
Foundation / checks (ecs) (push) Successful in 2m19s
Foundation / checks (deploy) (push) Successful in 4m47s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 16m48s
Foundation / checks (network) (push) Canceled after 16m46s
Foundation / checks (postgres) (push) Canceled after 16m47s
Foundation / checks (client) (push) Canceled after 16m53s
Foundation / checks (tsan) (push) Canceled after 14m33s
feat(ecology): make photosynthesis regions playable on DEV
ADR-0176 and schema 57 admit raw cellular bundle 13 (rules 11 on owner
format 9) through parser-local normalization to bundle 12, and a fenced
no-tick 12 -> 13 upgrade that declares the region's light; recovery reads
the light from the target and re-derives the whole target from the source.
The resumable cellular-v8 opening provisions a cellular-v7 genesis, one
empty tick and the durable upgrades to bundle 13.

Session v12 adds the owner's captured light and the producers it can see
to its perception, and lets offers name photosynthesis; older sessions keep
their layouts and never receive photosynthesis candidates. The client
draws chloroplasts by efficiency, shows sunlight in the HUD and offers
photosynthesis cards. DEV now provisions and serves region 9 with the
trial light; region 8 stays stored but unserved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 23:04:34 -04:00

318 lines
21 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_environment.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.
cellular_environment_v1 = 6, // ADR-0174: cells with their environment; bundle 10 or 11.
};
// Profiles whose manifests carry a CellularVersionBundle.
[[nodiscard]] constexpr bool cellular_profile(CheckpointProfile profile) noexcept {
return profile == CheckpointProfile::cellular_lives_v1 ||
profile == CheckpointProfile::cellular_population_v1 ||
profile == CheckpointProfile::cellular_environment_v1;
}
// 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;
// ADR-0174: joint envelope 1 nesting population envelope 2 and its lineage archive.
inline constexpr std::uint32_t environment_history_profile = 6;
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};
// ADR-0167: portable raw-only retained plans. SQL/publication admission is separate.
inline constexpr CellularVersionBundle cellular_v12_versions{10, 8, 2, 1, 1, 4, 3, 2, 1};
// ADR-0175/0176: rules 11 on owner format 9 (declared light), development 5, founder 4.
inline constexpr CellularVersionBundle cellular_v13_versions{11, 9, 2, 1, 1, 5, 4, 2, 1};
// Raw-only retained-plan bundles, which use trace 4 and their own SQL admission.
[[nodiscard]] constexpr bool cellular_plan_bundle(const CellularVersionBundle& b) noexcept {
return b == cellular_v12_versions || b == cellular_v13_versions;
}
// 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;
}
// Legacy revision bundles using history profile 4 and format-3 traces.
// Bundle 12 is intentionally excluded: it requires separate trace-4 admission.
[[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;
}
// Exact raw trace version for admitted cellular tuples; bundle 12 has its own semantics.
[[nodiscard]] constexpr std::uint32_t
cellular_checkpoint_trace_format(const CellularVersionBundle& b) noexcept {
return cellular_plan_bundle(b) ? server::cellular_batch_inheritance_format
: cellular_revision_bundle(b) ? server::cellular_batch_format
: server::cellular_batch_v2_format;
}
// 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
: profile == CheckpointProfile::cellular_environment_v1
? server::max_cellular_environment_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);
// ADR-0167: explicit raw-only bundle 11 -> 12 retained-plan candidate, no tick.
// Caller verifies SHA-256 source/target bindings and durable authority separately.
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
cellular_inheritance_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_inheritance_upgrade_payload(std::span<const std::uint8_t> payload,
const CheckpointManifest& predecessor);
// ADR-0176: explicit raw-only bundle 12 -> 13 upgrade declaring the region's light. The
// light is an input; recovery reads it from the target and re-derives everything else.
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
cellular_photosynthesis_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_photosynthesis_upgrade_payload(std::span<const std::uint8_t> payload,
const CheckpointManifest& predecessor,
const server::CellularLight& light);
// ADR-0174: explicit one-way, no-tick profile 5 -> 6 transition. The payload wraps the
// identical population with its declared environment; bundle and policy are unchanged.
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
environment_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);
// Joint interval or whole-group conversion; a conversion keeps the tick with a trace.
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError> environment_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);
[[nodiscard]] std::expected<std::unique_ptr<server::CellularEnvironment>, CheckpointError>
restore_environment_payload(std::span<const std::uint8_t> payload,
const CheckpointManifest& manifest);
// 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