Files
aevolution/include/evo/persistence/region_lease_store.hpp
T
dingo 627411983f
Foundation / checks (ecs) (push) Successful in 2m41s
Foundation / checks (tsan) (push) Failing after 18m12s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (network) (push) Canceled after 20m41s
Foundation / checks (postgres) (push) Canceled after 20m43s
Foundation / checks (checks) (push) Canceled after 20m49s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (client) (push) Failing after 17m4s
Foundation / postgres-tools (push) Canceled after 0s
M12.3: publish and recover durable exact populations
2026-10-17 17:10:17 -04:00

240 lines
14 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);
[[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);
} // namespace evo::persistence