Files
aevolution/include/evo/persistence/region_lease_store.hpp
T
dingoandClaude Opus 5.5 69f3ad7cf8
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
Add M10.4b durable action records (schema v11)
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>
2026-10-03 22:53:38 -04:00

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