Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m47s
Foundation / checks (network) (push) Successful in 9m30s
Foundation / checks (client) (push) Successful in 12m19s
Foundation / checks (tsan) (push) Successful in 7m43s
Foundation / checks (checks) (push) Successful in 31m29s
Foundation / checks (postgres) (push) Successful in 36m39s
Foundation / postgres-tools (push) Successful in 19s
Foundation / image (push) Successful in 2m15s
Foundation / server-image (push) Successful in 20m37s
Each batch's actions are recorded in the same statement as its checkpoint: one region_actions row per (world, account, action id) and the block in an append-only table, compared on exact retries and resolution. The region host attaches actions to the ticks they ride and reports acknowledgements and drops, keeping unknown-outcome batches unresolved. Outcomes come from the durable record via ActionLedger, so crashes before or after a commit, unknown publications and cross-region moves all resolve to one answer; a repeated id keeps its first record instead of stalling a region. ADR-0092. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
127 lines
7.2 KiB
C++
127 lines
7.2 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;
|
|
};
|
|
|
|
// 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);
|
|
|
|
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);
|
|
// 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 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);
|
|
} // namespace evo::persistence
|