#pragma once #include "evo/persistence/postgres.hpp" #include "evo/persistence/region_batch.hpp" #include "evo/persistence/region_lease.hpp" #include #include #include #include #include #include // 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 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 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 renew_region_lease(Postgres& db, RegionKey key, const LeaseGrant& lease, std::chrono::milliseconds duration, std::chrono::milliseconds timeout); [[nodiscard]] std::expected release_region_lease(Postgres& db, RegionKey key, const LeaseGrant& lease, std::chrono::milliseconds timeout); [[nodiscard]] std::expected load_region_head(Postgres& db, RegionKey key, std::chrono::milliseconds timeout); [[nodiscard]] std::expected 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 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 publish_region_checkpoint(Postgres& db, std::span manifest, std::span 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 publish_region_checkpoint(Postgres& db, std::span manifest, std::span decisions, std::span 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 resolve_region_commit(Postgres& db, RegionKey key, const Uuid& commit, std::span manifest, std::span decisions, std::chrono::milliseconds timeout); // Schema v11 resolution, comparing the action block too. [[nodiscard]] std::expected resolve_region_commit(Postgres& db, RegionKey key, const Uuid& commit, std::span manifest, std::span decisions, std::span 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, 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, 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, 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 acknowledge_region_outbox(Postgres& db, RegionKey key, const BatchDecision& decision, std::chrono::milliseconds timeout); } // namespace evo::persistence