Files
dingoandClaude Opus 5.5 51991ac7ff
Foundation / checks (ecs) (push) Successful in 2m24s
Foundation / checks (deploy) (push) Successful in 4m51s
Foundation / checks (network) (push) Successful in 20m42s
Foundation / checks (client) (push) Successful in 21m53s
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 40m19s
Foundation / checks (postgres) (push) Canceled after 40m9s
Foundation / checks (tsan) (push) Canceled after 37m53s
feat(persistence): admit durable cellular environment profile
ADR-0174 and schema 56 add checkpoint profile 6, which stores the joint
cell/environment envelope nesting population envelope 2 (bundles 10 and
11). Entry from a committed population head is explicit, one-way and
no-tick, with the source commit, manifest and payload digests bound in
immutable evidence. Joint intervals use schema 45's owned admission and
settlement; conversions cannot overtake a pending interval. The fenced
publisher validates the joint trace structurally, including the complete
nested population batch, and records per-commit imported and radiated
totals. Recovery replays the head's link and requires the payload
exactly, refusing a forged but structurally valid trace. A trigger
refuses profile-6 commits from every other publisher; profile 4/5 bytes,
parsers and rules are unchanged.

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

257 lines
16 KiB
C++

#pragma once
#include "evo/persistence/postgres.hpp"
#include "evo/persistence/region_batch.hpp"
#include "evo/persistence/region_lease.hpp"
#include <chrono>
#include <cstdint>
#include <expected>
#include <optional>
#include <span>
#include <vector>
// Linux-only calls to the fenced database functions of migration v2 (ADR-0060).
// Each call is one statement on a caller-owned connection; outside an explicit
// transaction it commits by itself. No retries. Rejections are ordinary results.
namespace evo::persistence {
enum class LeaseStoreError : std::uint8_t {
busy, // Another holder's lease is unexpired in database time.
fenced, // Holder/epoch superseded, released or expired: stop originating.
head_mismatch, // Expected predecessor is not the committed head.
not_provisioned, // No genesis; runtime can never create one.
exhausted, // Epoch or commit sequence would wrap: fail closed.
unsupported, // Profile/version/build not admitted, or rules/quantum changed.
commit_conflict, // Commit ID already holds other bytes: never retry it.
outcome_final, // A decision repeats an already committed permanent outcome.
immutable, // Attempted rewrite of committed history (owner paths only).
invalid, // Rejected arguments; nothing changed.
store, // Other SQL/configuration failure; nothing committed.
unknown, // May have executed; reconnect and reconcile before reuse.
};
struct LeaseStoreFailure {
LeaseStoreError kind{};
PgFailure cause{};
};
// Committed head and the exact manifest bytes its digest covers.
struct CommittedCheckpoint {
RegionHead head{};
std::vector<std::uint8_t> manifest;
};
struct CellularProfileMigrationRecord {
std::uint64_t source_sequence{};
Uuid source_commit{};
Sha256Digest source_manifest_sha256{}, source_payload_sha256{};
std::vector<std::uint8_t> source_versions;
std::uint64_t target_sequence{};
Uuid target_commit{};
Sha256Digest target_manifest_sha256{}, target_payload_sha256{};
std::vector<std::uint8_t> target_versions;
friend bool operator==(const CellularProfileMigrationRecord&,
const CellularProfileMigrationRecord&) = default;
};
// Schema v8 (ADR-0068): authority is granted only to a retained, unretired build;
// a retired or unknown build is unsupported and must not keep retrying.
[[nodiscard]] std::expected<LeaseGrant, LeaseStoreFailure>
acquire_region_lease(Postgres& db, RegionKey key, const Sha256Digest& build,
std::chrono::milliseconds duration, std::chrono::milliseconds timeout);
// Returns the granted duration; the caller measures it from its request send time.
[[nodiscard]] std::expected<std::chrono::milliseconds, LeaseStoreFailure>
renew_region_lease(Postgres& db, RegionKey key, const LeaseGrant& lease,
std::chrono::milliseconds duration, std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<void, LeaseStoreFailure>
release_region_lease(Postgres& db, RegionKey key, const LeaseGrant& lease,
std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
load_region_head(Postgres& db, RegionKey key, std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<CommittedCheckpoint, LeaseStoreFailure>
load_region_checkpoint(Postgres& db, RegionKey key, std::chrono::milliseconds timeout);
// Any committed link by sequence (schema v6): its identity, digest, end tick and
// exact manifest bytes. not_provisioned when the region has no such commit.
[[nodiscard]] std::expected<CommittedCheckpoint, LeaseStoreFailure>
load_region_commit(Postgres& db, RegionKey key, std::uint64_t sequence,
std::chrono::milliseconds timeout);
// Canonical manifest v2 bytes plus the decision block they digest (ADR-0063). The
// database parses identity, lease and chain, locks the lease then the head, requires
// the exact committed predecessor and records decisions and outbox rows in the same
// statement. An exact retry of a committed ID returns its original receipt; changed
// bytes are commit_conflict. The payload and trace must already be verified objects.
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
publish_region_checkpoint(Postgres& db, std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> decisions,
std::chrono::milliseconds timeout);
// Schema v11: the same publication with the batch's action block (encode_actions), recorded
// in the same statement. The block is part of the commit identity. An action id already on
// record in the world keeps its first record (find_region_action is the authority).
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
publish_region_checkpoint(Postgres& db, std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> decisions,
std::span<const std::uint8_t> actions, std::chrono::milliseconds timeout);
// Schema v20, ADR-0112: profile-4 checkpoints use a distinct publisher so the
// canonical cellular action block is bound to the checkpoint and durable result rows.
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
publish_cellular_checkpoint(Postgres& db, std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> decisions,
std::span<const std::uint8_t> actions,
std::span<const std::uint8_t> trace, std::chrono::milliseconds timeout);
// Explicit version upgrades: retained raw v1->v2/v2->v3, or same-profile
// bundle 9->10 for raw/population owners. Immutable journal and lease/head fence.
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
publish_cellular_profile_migration(Postgres& db, std::span<const std::uint8_t> manifest,
std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<std::optional<CellularProfileMigrationRecord>, LeaseStoreFailure>
load_cellular_profile_migration(Postgres& db, RegionKey key, const LeaseGrant& lease,
const Uuid& commit, std::chrono::milliseconds timeout);
enum class Resolution : std::uint8_t {
committed, // Exact bytes are durable; receipt holds the head. Grants no authority.
absent, // Not committed now; proves nothing about a request still in flight.
conflict, // The ID holds other bytes or belongs to another region: fail closed.
};
struct ResolvedCommit {
Resolution status{};
RegionHead receipt{}; // Only for committed.
};
[[nodiscard]] std::expected<ResolvedCommit, LeaseStoreFailure>
resolve_region_commit(Postgres& db, RegionKey key, const Uuid& commit,
std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> decisions, std::chrono::milliseconds timeout);
// Schema v11 resolution, comparing the action block too.
[[nodiscard]] std::expected<ResolvedCommit, LeaseStoreFailure>
resolve_region_commit(Postgres& db, RegionKey key, const Uuid& commit,
std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> decisions,
std::span<const std::uint8_t> actions, std::chrono::milliseconds timeout);
// Schema v20 resolution also compares the immutable profile-4 cellular action block.
[[nodiscard]] std::expected<ResolvedCommit, LeaseStoreFailure> resolve_cellular_region_commit(
Postgres& db, RegionKey key, const Uuid& commit, std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> decisions, std::span<const std::uint8_t> actions,
std::span<const std::uint8_t> trace, std::chrono::milliseconds timeout);
// Load the immutable action block for a committed profile-4 link under the current lease.
// Empty means this commit has no cellular publication row; a missing row for a progressing
// profile-4 commit is a database error and fails closed.
[[nodiscard]] std::expected<std::optional<std::vector<std::uint8_t>>, LeaseStoreFailure>
load_cellular_publication_actions(Postgres& db, RegionKey key, const LeaseGrant& lease,
const Uuid& commit, std::chrono::milliseconds timeout);
struct CellularBirthBinding {
Uuid account{}, commit{};
std::uint64_t request{}, identity{}, born{}, commit_sequence{};
friend bool operator==(const CellularBirthBinding&, const CellularBirthBinding&) = default;
};
[[nodiscard]] std::expected<std::vector<CellularBirthBinding>, LeaseStoreFailure>
load_cellular_publication_births(Postgres& db, RegionKey key, const LeaseGrant& lease,
const Uuid& commit, std::chrono::milliseconds timeout);
// Schema v35 (ADR-0121): a checkpoint whose trace carries mutation selections publishes
// with its canonical mutation block (64-byte records) and one result byte per record.
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure> publish_cellular_mutation_checkpoint(
Postgres& db, std::span<const std::uint8_t> manifest, std::span<const std::uint8_t> decisions,
std::span<const std::uint8_t> actions, std::span<const std::uint8_t> trace,
std::span<const std::uint8_t> mutations, std::span<const std::uint8_t> results,
std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<ResolvedCommit, LeaseStoreFailure> resolve_cellular_mutation_commit(
Postgres& db, RegionKey key, const Uuid& commit, std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> decisions, std::span<const std::uint8_t> actions,
std::span<const std::uint8_t> trace, std::span<const std::uint8_t> mutations,
std::span<const std::uint8_t> results, std::chrono::milliseconds timeout);
// The mutation choices bound to one commit, ordered (tick, account, action): the 16-byte
// account, action id, 34-byte reserved input and final result.
struct CellularMutationPublication {
std::array<std::uint8_t, 16> account{};
std::uint64_t action_id{};
std::array<std::uint8_t, 34> input{};
std::uint8_t result{};
friend bool operator==(const CellularMutationPublication&,
const CellularMutationPublication&) = default;
};
[[nodiscard]] std::expected<std::vector<CellularMutationPublication>, LeaseStoreFailure>
load_cellular_mutation_publications(Postgres& db, RegionKey key, const LeaseGrant& lease,
const Uuid& commit, std::chrono::milliseconds timeout);
// The committed record of an account's action in the lease's world (schema v11), under the
// caller's exact lease. Nothing when the action was never committed.
struct CommittedAction {
std::uint64_t region{}, tick{}, commit_sequence{};
friend bool operator==(const CommittedAction&, const CommittedAction&) = default;
};
[[nodiscard]] std::expected<std::optional<CommittedAction>, LeaseStoreFailure>
find_region_action(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account,
std::uint64_t action_id, std::chrono::milliseconds timeout);
struct CommittedActionRecord {
CommittedAction action;
std::uint16_t kind{};
std::uint8_t result{};
std::optional<std::vector<std::uint8_t>> cellular_input;
friend bool operator==(const CommittedActionRecord&, const CommittedActionRecord&) = default;
};
[[nodiscard]] std::expected<std::optional<CommittedActionRecord>, LeaseStoreFailure>
find_region_action_record(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account,
std::uint64_t action_id, std::chrono::milliseconds timeout);
// The same for several (account, action) pairs in one statement, answered in order
// (M10.9d, ADR-0097). Empty asks nothing.
struct ActionRef {
Uuid account{};
std::uint64_t action_id{};
};
[[nodiscard]] std::expected<std::vector<std::optional<CommittedAction>>, LeaseStoreFailure>
find_region_actions(Postgres& db, RegionKey key, const LeaseGrant& lease,
std::span<const ActionRef> actions, std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<std::vector<std::optional<CommittedActionRecord>>, LeaseStoreFailure>
find_region_action_records(Postgres& db, RegionKey key, const LeaseGrant& lease,
std::span<const ActionRef> actions, std::chrono::milliseconds timeout);
struct CommittedDecision {
std::uint64_t commit_sequence{};
BatchDecision decision{};
friend bool operator==(const CommittedDecision&, const CommittedDecision&) = default;
};
// Every committed permanent outcome of the region, ordered by (tick, actor).
[[nodiscard]] std::expected<std::vector<CommittedDecision>, LeaseStoreFailure>
load_region_decisions(Postgres& db, RegionKey key, std::chrono::milliseconds timeout);
// Undelivered outbox rows (1..64), ordered by (commit, tick, actor). Delivery is
// at-least-once; consumers deduplicate by (region, outcome, actor, tick).
[[nodiscard]] std::expected<std::vector<CommittedDecision>, LeaseStoreFailure>
pending_region_outbox(Postgres& db, RegionKey key, std::uint32_t limit,
std::chrono::milliseconds timeout);
// True on first acknowledgement, false when already delivered.
[[nodiscard]] std::expected<bool, LeaseStoreFailure>
acknowledge_region_outbox(Postgres& db, RegionKey key, const BatchDecision& decision,
std::chrono::milliseconds timeout);
struct PopulationEvidence {
std::vector<std::uint8_t> trace;
std::optional<Uuid> source_commit;
Sha256Digest source_manifest_sha256{}, source_payload_sha256{};
};
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
publish_population_checkpoint(Postgres&, std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> trace,
std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
publish_population_profile_transition(Postgres&, std::span<const std::uint8_t> manifest,
std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<ResolvedCommit, LeaseStoreFailure>
resolve_population_commit(Postgres&, RegionKey, const Uuid& commit,
std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> trace, std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<std::optional<PopulationEvidence>, LeaseStoreFailure>
load_population_evidence(Postgres&, RegionKey, const LeaseGrant&, const Uuid& commit,
std::chrono::milliseconds timeout);
// ADR-0174 / schema 56: the joint profile's fenced publishers and immutable evidence.
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
publish_environment_checkpoint(Postgres&, std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> trace,
std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
publish_environment_profile_transition(Postgres&, std::span<const std::uint8_t> manifest,
std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<ResolvedCommit, LeaseStoreFailure>
resolve_environment_commit(Postgres&, RegionKey, const Uuid& commit,
std::span<const std::uint8_t> manifest,
std::span<const std::uint8_t> trace, std::chrono::milliseconds timeout);
[[nodiscard]] std::expected<std::optional<PopulationEvidence>, LeaseStoreFailure>
load_environment_evidence(Postgres&, RegionKey, const LeaseGrant&, const Uuid& commit,
std::chrono::milliseconds timeout);
} // namespace evo::persistence