Complete M7.4b lineage checkpoint profile; M7.4 done
ADR-0062 adds a canonical LineageArchive codec (parents before children, organisms by id, FNV) that decodes by replaying admit/record_birth/ record_death and requires byte-identical re-encoding; it never overwrites an existing archive. LineageRegion binds the environmental producer and consumer accounts to archived organisms with identity high-waters, enforces closure (lifecycle vs deaths, exact living set, tick bounds) and records deaths in the tick that causes them. Checkpoint profile 2 (environmental-lineage-v1, history profile 1) publishes that container; schema v4 admits it with a 4,268,144-byte cap and requires each commit to keep its predecessor's profile, RNG, history and durability declarations. Linux adds provision/publish/recover for the profile on the shared publication path. Qualification found WSL2 stepping CLOCK_REALTIME back ~0.5 s every ~32 s, which made two 1 s-lease tests flaky under ASan. Tests now wait on database-time expiry; ADR-0060 records the slewed-clock requirement. Validated: Windows CTest 57/57; Linux GCC Debug/Release, clang-tidy and ASan/UBSan CTest 57/57 each; PostgreSQL suites 2x Release, 2x analysis, 5x ASan; SQL and C++ mutations each caught. 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:
@@ -29,6 +29,21 @@ enum class HistoryError : std::uint8_t {
|
||||
};
|
||||
inline constexpr std::size_t max_archived_genomes = 4'096;
|
||||
inline constexpr std::size_t max_archived_organisms = 65'536;
|
||||
// Whole-archive codec v1 (schemas/lineage-archive-v1.md, ADR-0062).
|
||||
enum class ArchiveCodecError : std::uint8_t {
|
||||
format, // Magic, lengths or field forms.
|
||||
version, // Unknown archive format or genome schema.
|
||||
checksum, // Trailing FNV-1a64 mismatch (corruption, not forgery).
|
||||
bounds, // Counts or bytes above the archive caps; checked before allocation.
|
||||
genome, // A record fails Genome v1 validation.
|
||||
history, // Admission/birth/death invariants refuse the record sequence.
|
||||
noncanonical, // Valid content in a non-canonical order or form.
|
||||
};
|
||||
inline constexpr std::uint32_t lineage_archive_format = 1;
|
||||
inline constexpr std::size_t archived_organism_bytes = 33;
|
||||
inline constexpr std::size_t max_archive_bytes =
|
||||
32 + (max_archived_genomes * (2 + max_genome_bytes)) +
|
||||
(max_archived_organisms * archived_organism_bytes) + 8;
|
||||
|
||||
// Retains genomes and the organisms that carried them. There is no removal
|
||||
// operation: not a guarded one, not a private one. Retention is a property of
|
||||
@@ -78,6 +93,22 @@ class LineageArchive {
|
||||
[[nodiscard]] std::size_t recorded() const noexcept {
|
||||
return organisms_.size();
|
||||
}
|
||||
// Ascending identities of organisms not yet recorded dead.
|
||||
[[nodiscard]] std::vector<std::uint64_t> living_organisms() const;
|
||||
// Largest recorded identities, zero when none: allocator high-water checks.
|
||||
[[nodiscard]] std::uint64_t highest_genome() const noexcept;
|
||||
[[nodiscard]] std::uint64_t highest_organism() const noexcept;
|
||||
|
||||
// Canonical bytes: genomes by (ancestry depth, id), so parents precede children,
|
||||
// then organisms by id. Equal archives encode identically whatever order their
|
||||
// records were admitted in.
|
||||
[[nodiscard]] std::vector<std::uint8_t> encode() const;
|
||||
// Constructs a new archive by replaying admit/record_birth/record_death, so
|
||||
// every retention invariant is re-established, then requires a byte-identical
|
||||
// re-encoding. It never overwrites an existing archive; refusing stale older
|
||||
// copies is the durable commit chain's job (ADR-0061/0062).
|
||||
[[nodiscard]] static std::expected<LineageArchive, ArchiveCodecError>
|
||||
decode(std::span<const std::uint8_t> bytes);
|
||||
|
||||
private:
|
||||
struct ArchivedOrganism {
|
||||
|
||||
@@ -44,6 +44,11 @@ struct RecoveredCheckpoint {
|
||||
CheckpointManifest manifest;
|
||||
std::unique_ptr<processes::EnvironmentalCommunity> state;
|
||||
};
|
||||
struct RecoveredLineageCheckpoint {
|
||||
CommittedCheckpoint committed;
|
||||
CheckpointManifest manifest;
|
||||
std::unique_ptr<processes::LineageRegion> state;
|
||||
};
|
||||
|
||||
// Owner/operator connection only: uploads a tick-0 state and records genesis.
|
||||
[[nodiscard]] std::expected<CommittedCheckpoint, PublicationFailure> provision_environmental_region(
|
||||
@@ -65,4 +70,21 @@ publish_environmental_checkpoint(Postgres& db, const FilesystemObjectStore& obje
|
||||
recover_environmental_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key,
|
||||
std::span<const Sha256Digest> retained_builds,
|
||||
std::size_t restore_budget, std::chrono::milliseconds timeout);
|
||||
|
||||
// environmental-lineage-v1 (ADR-0062): the same order and guarantees, with the
|
||||
// LineageRegion container as payload. A region's profile never changes; each call
|
||||
// refuses a predecessor/committed head of the other profile.
|
||||
[[nodiscard]] std::expected<CommittedCheckpoint, PublicationFailure>
|
||||
provision_lineage_region(Postgres& owner, const FilesystemObjectStore& objects, RegionKey key,
|
||||
std::uint64_t frame, const processes::LineageRegion& opening, Uuid commit,
|
||||
const Sha256Digest& build, std::size_t restore_budget,
|
||||
std::chrono::milliseconds timeout);
|
||||
[[nodiscard]] std::expected<CommittedCheckpoint, PublicationFailure> publish_lineage_checkpoint(
|
||||
Postgres& db, const FilesystemObjectStore& objects, const LeaseGrant& lease,
|
||||
const CommittedCheckpoint& predecessor, const processes::LineageRegion& state, Uuid commit,
|
||||
const Sha256Digest& build, std::size_t restore_budget, std::chrono::milliseconds timeout);
|
||||
[[nodiscard]] std::expected<RecoveredLineageCheckpoint, RecoveryFailure>
|
||||
recover_lineage_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key,
|
||||
std::span<const Sha256Digest> retained_builds,
|
||||
std::size_t restore_budget, std::chrono::milliseconds timeout);
|
||||
} // namespace evo::persistence
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
#pragma once
|
||||
#include "evo/persistence/region_lease.hpp"
|
||||
#include "evo/processes/environmental_community.hpp"
|
||||
#include "evo/processes/lineage_region.hpp"
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
@@ -8,12 +9,19 @@
|
||||
#include <span>
|
||||
#include <vector>
|
||||
|
||||
// Region checkpoint manifest v1 and environmental-v1 payload validation (ADR-0061,
|
||||
// schemas/region-commit.md). Portable and storage-free: digests are computed and
|
||||
// objects are stored by the Linux adapters; this only encodes and validates.
|
||||
// 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 };
|
||||
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.
|
||||
};
|
||||
// history_profile 1: lineage archive format 1 with genome schema 1.
|
||||
inline constexpr std::uint32_t lineage_history_profile = 1;
|
||||
// Declared durability, verified at deployment. Development: one volume, no host-loss claim.
|
||||
enum class DurabilityPolicy : std::uint8_t { unknown = 0, single_volume_development = 1 };
|
||||
|
||||
@@ -40,8 +48,8 @@ struct CheckpointManifest {
|
||||
std::uint64_t tick_microseconds{};
|
||||
VersionBundle versions{};
|
||||
Sha256Digest build{}; // Retained immutable build artifact identity.
|
||||
std::uint32_t rng_streams{}; // environmental-v1 rules use no randomness: 0.
|
||||
std::uint32_t history_profile{}; // No lineage/genome state in environmental-v1: 0.
|
||||
std::uint32_t rng_streams{}; // These rules use no randomness: 0.
|
||||
std::uint32_t history_profile{}; // 0 environmental-v1; 1 environmental-lineage-v1.
|
||||
DurabilityPolicy durability{DurabilityPolicy::single_volume_development};
|
||||
std::uint64_t payload_bytes{};
|
||||
Sha256Digest payload_sha256{};
|
||||
@@ -50,6 +58,13 @@ struct CheckpointManifest {
|
||||
|
||||
inline constexpr std::size_t checkpoint_manifest_bytes = 280;
|
||||
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
|
||||
: 0;
|
||||
}
|
||||
inline constexpr std::uint64_t max_checkpoint_ticks = 64;
|
||||
|
||||
enum class CheckpointError : std::uint8_t {
|
||||
@@ -65,15 +80,17 @@ enum class CheckpointError : std::uint8_t {
|
||||
encode_manifest(const CheckpointManifest& manifest);
|
||||
[[nodiscard]] std::expected<CheckpointManifest, CheckpointError>
|
||||
decode_manifest(std::span<const std::uint8_t> bytes);
|
||||
// Profile, exact versions, zero RNG/history declarations and durability policy.
|
||||
// Profile with its history profile, exact versions, zero RNG and durability policy.
|
||||
[[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);
|
||||
const Sha256Digest& payload_sha256,
|
||||
CheckpointProfile profile = CheckpointProfile::environmental_v1);
|
||||
// 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,
|
||||
@@ -86,4 +103,10 @@ successor_manifest(const CheckpointManifest& predecessor, const Sha256Digest& pr
|
||||
[[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);
|
||||
} // namespace evo::persistence
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
#pragma once
|
||||
#include "evo/biology/lineage.hpp"
|
||||
#include "evo/processes/environmental_community.hpp"
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
#include <memory>
|
||||
#include <span>
|
||||
|
||||
// History-capable environmental region (ADR-0062, schemas/environmental-lineage-v1.md):
|
||||
// the environmental community, the lineage archive that retains its organisms'
|
||||
// genomes and deaths, the binding of its two accounts to archived organisms, and
|
||||
// identity high-waters. One owner; every advance keeps archive deaths in the same
|
||||
// tick as the community's terminal transitions, so a checkpoint cannot split them.
|
||||
namespace evo::processes {
|
||||
struct LineageBinding {
|
||||
std::uint64_t producer{}, consumer{}; // Archived organism identities.
|
||||
std::uint64_t next_organism{}, next_genome{}; // Never reissue below these.
|
||||
auto operator<=>(const LineageBinding&) const = default;
|
||||
};
|
||||
enum class LineageRegionError : std::uint8_t {
|
||||
community, // The community refused the tick or its envelope; nothing changed.
|
||||
closure, // Binding, lifecycle, living set or high-waters disagree.
|
||||
archive, // Archive bytes refused (see ArchiveCodecError via restore).
|
||||
format, // Container framing, lengths or reserved fields.
|
||||
version, // Unknown container format.
|
||||
checksum, // Container FNV-1a64 mismatch.
|
||||
poisoned, // A prior advance failed after committing the community tick.
|
||||
};
|
||||
inline constexpr std::uint32_t lineage_region_format = 1;
|
||||
inline constexpr std::size_t max_lineage_region_bytes =
|
||||
72 + EnvironmentalCommunity::max_snapshot_bytes + biology::max_archive_bytes;
|
||||
|
||||
class LineageRegion {
|
||||
public:
|
||||
// Validates closure: both bound organisms recorded; terminal flags equal the
|
||||
// archive's death records; the archive's living organisms are exactly the
|
||||
// bound, non-terminal ones; births/deaths not after the current tick; and both
|
||||
// high-waters above every recorded identity.
|
||||
[[nodiscard]] static std::expected<std::unique_ptr<LineageRegion>, LineageRegionError>
|
||||
create(std::unique_ptr<EnvironmentalCommunity> community,
|
||||
const biology::LineageArchive& archive, LineageBinding binding);
|
||||
LineageRegion(const LineageRegion&) = delete;
|
||||
LineageRegion& operator=(const LineageRegion&) = delete;
|
||||
LineageRegion(LineageRegion&&) = delete;
|
||||
LineageRegion& operator=(LineageRegion&&) = delete;
|
||||
~LineageRegion() = default;
|
||||
|
||||
// Advances the community one tick and records each terminal transition as an
|
||||
// archive death at that tick.
|
||||
[[nodiscard]] std::expected<EnvironmentalReport, LineageRegionError>
|
||||
advance(std::uint64_t tick, const EnvironmentalInput& input);
|
||||
[[nodiscard]] std::expected<world::WorldBytes, LineageRegionError> snapshot() const;
|
||||
// Restores the envelope (full replay audit) and the archive, validates closure
|
||||
// and requires a byte-identical canonical re-encoding. The budget is charged to
|
||||
// the community; archive memory is bounded by the archive's fixed caps.
|
||||
[[nodiscard]] static std::expected<std::unique_ptr<LineageRegion>, LineageRegionError>
|
||||
restore(std::span<const std::uint8_t> bytes, world::WorldIdentity identity, std::size_t budget);
|
||||
|
||||
[[nodiscard]] const EnvironmentalCommunity& community() const noexcept {
|
||||
return *community_;
|
||||
}
|
||||
[[nodiscard]] const biology::LineageArchive& archive() const noexcept {
|
||||
return archive_;
|
||||
}
|
||||
[[nodiscard]] const LineageBinding& binding() const noexcept {
|
||||
return binding_;
|
||||
}
|
||||
|
||||
private:
|
||||
LineageRegion(std::unique_ptr<EnvironmentalCommunity> community,
|
||||
const biology::LineageArchive& archive, LineageBinding binding);
|
||||
[[nodiscard]] bool closed() const;
|
||||
std::unique_ptr<EnvironmentalCommunity> community_;
|
||||
biology::LineageArchive archive_;
|
||||
LineageBinding binding_;
|
||||
bool poisoned_{};
|
||||
};
|
||||
} // namespace evo::processes
|
||||
Reference in New Issue
Block a user