#pragma once #include "evo/persistence/postgres.hpp" #include "evo/persistence/region_lease.hpp" #include #include #include #include #include // Linux-only calls to the probe record and handoff functions of schema v12 (ADR-0096, // migrations/0012_probe_handoff.sql). EXPERIMENT: probes are non-biological engineering // entities (ADR-0094). Each call is one statement under the caller's region lease: a fenced // or expired lease refuses everything. No retries; every transfer call can be retried with // the same transfer id and returns the recorded outcome. namespace evo::persistence { enum class ProbeStoreError : std::uint8_t { fenced, // Lease, ownership, generation or frozen state no longer allows it. unknown_transfer, // No transfer with this id in the world. not_staged, // Commit before the caller's current epoch staged the transfer. exhausted, // Generations would wrap: fail closed. invalid, // Rejected arguments (or an unprovisioned region); nothing changed. store, // Other SQL/configuration failure; nothing committed. unknown, // May have executed; reconnect and reconcile (retry the same id). }; struct ProbeStoreFailure { ProbeStoreError kind{}; PgFailure cause{}; }; struct ProbeRecord { std::uint64_t region{}, generation{}; // Owning region; generation of this ownership. std::int64_t x{}, y{}, z{}; // Micrometres; z is the cell slice. std::uint64_t inventory{}; // EXPERIMENT conserved test inventory. std::optional transfer; // Frozen under this open transfer. }; enum class TransferState : std::uint8_t { prepared, staged, committed, aborted }; struct ProbeTransfer { TransferState state{}; Uuid account{}; std::uint64_t generation{}, source{}, destination{}; std::int64_t x{}, y{}, z{}; std::uint64_t inventory{}; friend bool operator==(const ProbeTransfer&, const ProbeTransfer&) = default; }; // The account's probe, created owned by the caller's region (at the position, with the // inventory) when the world has none. The caller acts for it only if it owns it and it is // not frozen. [[nodiscard]] std::expected open_probe(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account, std::int64_t x, std::int64_t y, std::int64_t z, std::uint64_t inventory, std::chrono::milliseconds timeout); // Records the active, owned probe's position (fenced otherwise). [[nodiscard]] std::expected save_probe(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account, std::uint64_t generation, std::int64_t x, std::int64_t y, std::int64_t z, std::chrono::milliseconds timeout); // Source: freezes the probe at its final position under `transfer` for `destination`. [[nodiscard]] std::expected prepare_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account, std::uint64_t generation, const Uuid& transfer, std::uint64_t destination, std::int64_t x, std::int64_t y, std::int64_t z, std::chrono::milliseconds timeout); // Destination: durably accepts it under its current epoch. [[nodiscard]] std::expected stage_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& transfer, std::chrono::milliseconds timeout); // Destination: the authority switch (staged by this epoch only). [[nodiscard]] std::expected commit_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& transfer, std::chrono::milliseconds timeout); // Source or destination: abandons it before its commit; the source resumes. [[nodiscard]] std::expected abort_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& transfer, std::chrono::milliseconds timeout); // Any region of the world: the transfer as recorded, or nothing. [[nodiscard]] std::expected, ProbeStoreFailure> find_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& transfer, std::chrono::milliseconds timeout); // Schema v13: the open (prepared or staged) transfers addressed to the caller's region, for // read-only ghosts (at most 256, oldest first). struct IncomingTransfer { Uuid transfer{}, account{}; std::uint64_t source{}; std::int64_t x{}, y{}, z{}; friend bool operator==(const IncomingTransfer&, const IncomingTransfer&) = default; }; [[nodiscard]] std::expected, ProbeStoreFailure> incoming_probe_transfers(Postgres& db, RegionKey key, const LeaseGrant& lease, std::chrono::milliseconds timeout); // Schema v14: the caller's open outgoing transfers prepared more than `age` (1 s .. 1 day) // ago by the database clock, for recovery aborts after a restart (at most 256, oldest first). [[nodiscard]] std::expected, ProbeStoreFailure> overdue_probe_transfers(Postgres& db, RegionKey key, const LeaseGrant& lease, std::chrono::seconds age, std::chrono::milliseconds timeout); } // namespace evo::persistence