Add M10.8a probe handoff schema v12 and store
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m53s
Foundation / checks (client) (push) Successful in 12m32s
Foundation / checks (network) (push) Successful in 12m17s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 2m2s
Foundation / checks (postgres) (push) Canceled after 3m48s
Foundation / checks (checks) (push) Canceled after 16m29s

ADR-0096, the persistence handoff ADR (EXPERIMENT probes, ADR-0094). Durable
probe records hold one owning region per account, so ownership is unique and
the test inventory is conserved by construction. A fenced transfer state
machine (prepared, staged, committed, aborted) under each caller's exact
region lease returns the recorded outcome on every retry; a commit requires
staging by the destination's current epoch; aborts are durable and only
before commit. handoff_account_control moves account control on a committed
transfer.

A PostgreSQL fault matrix covers restarts at each transition, stale epochs,
failed destinations, partitions and commit/abort races, checking one owner and
the conserved inventory after every scenario.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-06 18:15:49 -04:00
co-authored by Claude Opus 5.5
parent 5728e7682e
commit 6a645ef7e4
18 changed files with 1355 additions and 16 deletions
@@ -39,6 +39,13 @@ claim_account_control(Postgres& db, RegionKey key, const LeaseGrant& lease, cons
renew_account_control(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account,
std::uint64_t generation, std::chrono::milliseconds duration,
std::chrono::milliseconds timeout);
// M10.8 (ADR-0096, schema v12): takes control of `account` for `session` on the strength of
// probe transfer `transfer` committed to the caller's region (no serial: a handoff ticket
// has none). Fenced unless that transfer is committed to this region for this account.
[[nodiscard]] std::expected<AccountControlClaim, ControlStoreFailure>
handoff_account_control(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account,
const Uuid& transfer, std::uint64_t session,
std::chrono::milliseconds duration, std::chrono::milliseconds timeout);
// True when released, false when control had already moved on.
[[nodiscard]] std::expected<bool, ControlStoreFailure>
release_account_control(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account,
+78
View File
@@ -0,0 +1,78 @@
#pragma once
#include "evo/persistence/postgres.hpp"
#include "evo/persistence/region_lease.hpp"
#include <chrono>
#include <cstdint>
#include <expected>
#include <optional>
// 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<Uuid> 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<ProbeRecord, ProbeStoreFailure>
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<void, ProbeStoreFailure>
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<ProbeTransfer, ProbeStoreFailure>
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<ProbeTransfer, ProbeStoreFailure>
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<ProbeTransfer, ProbeStoreFailure>
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<ProbeTransfer, ProbeStoreFailure>
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<std::optional<ProbeTransfer>, ProbeStoreFailure>
find_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& transfer,
std::chrono::milliseconds timeout);
} // namespace evo::persistence