Complete M7.3 fenced region ownership

ADR-0060 and schema v2 add database-time region leases and a fenced head
advance. Acquire/renew/release/advance lock the lease row, check holder,
epoch and expiry with clock_timestamp() after the lock wait, and the
advance compares the exact predecessor. Holders are DB-generated tokens;
epochs never wrap or repeat. The runtime group role gets EXECUTE on five
SECURITY DEFINER functions only - no table, provisioning or CREATE rights.
Migration history admits clean->v2, v1->v2 and a v2 no-op, and refuses
privileged runtime roles.

Host side: portable LeaseAuthority fences from send-time deadlines on
CLOCK_BOOTTIME, keeps the earlier deadline on unknown renewal and stays
fenced until a newer epoch. Selected timings: 20s lease, 5s renew, 2s
margin, 2s renew and 5s commit deadlines. Linux evo::postgres wraps the
functions with typed LeaseStoreError results.

Validated: Windows CTest 55/55; WSL Release, clang-tidy and ASan/UBSan
private-PostgreSQL suites (contenders, expiry, paused/queued stale
writers, unknown renewal, exhaustion, bypass denial, upgrade path).
Three SQL mutations were each caught. Docker/Gitea CI, remote TLS and
cluster runs were not executed. No director, host or deployment added.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-09-28 11:14:32 -04:00
co-authored by Claude Opus 5.5
parent 598b3938e6
commit 2496649a9b
22 changed files with 1501 additions and 29 deletions
+99
View File
@@ -0,0 +1,99 @@
#pragma once
#include <array>
#include <chrono>
#include <cstdint>
#include <optional>
// Portable host-side region authority contract (ADR-0060). No database types:
// PostgreSQL arbitrates ownership; this only decides when a holder must stop.
namespace evo::persistence {
using Uuid = std::array<std::uint8_t, 16>;
using Sha256Digest = std::array<std::uint8_t, 32>;
struct RegionKey {
std::uint64_t world{};
std::uint64_t region{};
};
struct RegionHead {
std::uint64_t frame{};
std::uint64_t sequence{};
Uuid commit{};
Sha256Digest digest{};
std::uint64_t end_tick{};
friend bool operator==(const RegionHead&, const RegionHead&) = default;
};
// Holder is a database-generated per-acquisition token, not a Pod identity.
struct LeaseGrant {
Uuid holder{};
std::uint64_t epoch{};
std::uint64_t frame{};
std::chrono::milliseconds duration{};
};
// Selected M7.3 timings. Validity: duration 1..60s (database bound); margin at
// least 10% of duration (clock-rate and check-to-effect allowance); two complete
// renewal attempts fit before local fencing; I/O deadlines within adapter limits.
struct LeasePolicy {
std::chrono::milliseconds duration{20000};
std::chrono::milliseconds renew_interval{5000};
std::chrono::milliseconds safety_margin{2000};
std::chrono::milliseconds renew_timeout{2000};
std::chrono::milliseconds commit_timeout{5000};
};
[[nodiscard]] bool valid(const LeasePolicy& policy) noexcept;
// Monotonic clock that keeps advancing while the process or machine is suspended
// (Linux CLOCK_BOOTTIME). A paused worker must observe that time passed.
struct LeaseClock {
using duration = std::chrono::nanoseconds;
using rep = duration::rep;
using period = duration::period;
using time_point = std::chrono::time_point<LeaseClock>;
static constexpr bool is_steady = true;
[[nodiscard]] static time_point now() noexcept;
};
enum class LeaseState : std::uint8_t { absent, active, renew_due, fenced };
// Single-owner local view of one region lease. Every time point is a LeaseClock
// reading supplied by the host. The local deadline is request-send time plus the
// granted duration minus the safety margin: the database set its expiry no earlier
// than that send, so the holder stops before any successor can acquire. Fencing is
// sticky until a strictly newer epoch is acquired; renewal never revives it.
class LeaseAuthority {
public:
explicit LeaseAuthority(const LeasePolicy& policy) noexcept : policy_(policy) {}
[[nodiscard]] const LeasePolicy& policy() const noexcept {
return policy_;
}
[[nodiscard]] const std::optional<LeaseGrant>& grant() const noexcept {
return grant_;
}
// Returns false (and fences) for an invalid policy, reused/older epoch or late reply.
[[nodiscard]] bool acquired(const LeaseGrant& grant, LeaseClock::time_point sent,
LeaseClock::time_point received) noexcept;
[[nodiscard]] bool renewed(std::uint64_t epoch, std::chrono::milliseconds granted,
LeaseClock::time_point sent,
LeaseClock::time_point received) noexcept;
// Ambiguous renewal: the database may have applied a shorter expiry, so keep
// the earlier of the old deadline and the one the attempt could have set.
void renewal_unknown(std::chrono::milliseconds requested, LeaseClock::time_point sent) noexcept;
void fence() noexcept;
[[nodiscard]] LeaseState state(LeaseClock::time_point now) const noexcept;
// Admission, simulation and final output require an unfenced lease.
[[nodiscard]] bool may_originate(LeaseClock::time_point now) const noexcept;
// Liveness guard: begin a commit only if its deadline ends before local fencing.
[[nodiscard]] bool may_begin_commit(LeaseClock::time_point now) const noexcept;
[[nodiscard]] LeaseClock::time_point deadline() const noexcept {
return deadline_;
}
private:
LeasePolicy policy_;
std::optional<LeaseGrant> grant_;
std::uint64_t highest_epoch_{};
LeaseClock::time_point last_sent_{};
LeaseClock::time_point deadline_{};
bool fenced_{};
};
} // namespace evo::persistence
@@ -0,0 +1,50 @@
#pragma once
#include "evo/persistence/postgres.hpp"
#include "evo/persistence/region_lease.hpp"
#include <chrono>
#include <cstdint>
#include <expected>
// 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.
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{};
};
struct HeadAdvance {
Uuid commit{};
Sha256Digest digest{};
std::uint64_t end_tick{};
};
[[nodiscard]] std::expected<LeaseGrant, LeaseStoreFailure>
acquire_region_lease(Postgres& db, RegionKey key, 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);
// Locks the lease then the head; requires unexpired holder/epoch and the exact
// expected predecessor. head_mismatch after unknown: load the head and compare.
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
advance_region_head(Postgres& db, RegionKey key, const LeaseGrant& lease,
const RegionHead& expected, const HeadAdvance& next,
std::chrono::milliseconds timeout);
} // namespace evo::persistence