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
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>
257 lines
16 KiB
C++
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
|