Files
aevolution/include/evo/persistence/region_lease.hpp
T
dingoandClaude Opus 5.5 5d4f59f901 Implement M7.4a checkpoint publication and verified recovery
ADR-0061 publishes environmental-v1 full checkpoints. Manifest v1 is a
fixed 280-byte record (identity, chain, lease, versions, build, zero
RNG/history declarations, durability policy, payload length/SHA-256)
that PostgreSQL parses and digests itself. Schema v3 adds region_commits
with a digest CHECK and a composite head FK, owner-managed retained
builds, fenced publish/load functions and owner-only genesis; it drops
the bare v2 head kernel and fails closed while v2 heads exist.

Linux evo::region_store adds OpenSSL SHA-256, an immutable
content-addressed filesystem object store (temp+fsync+link, no
overwrite/delete, O_NOFOLLOW exact-length verified reads), and
publication (validate -> upload -> read back -> fenced transaction ->
receipt check) and recovery (re-digest, allowlist, verify, full restore).
Portable evo::region_checkpoint holds the codec and payload validation.

Validated: Windows CTest 56/56; WSL Release, clang-tidy and ASan/UBSan
private-PostgreSQL suites; four SQL and one host mutation each caught.
M7.4 stays open for 7.4b (lineage archive codec and history binding).
No Docker/Gitea CI, remote store, process kill or deployment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 15:25:27 -04:00

103 lines
4.4 KiB
C++

#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{};
friend bool operator==(const RegionKey&, const RegionKey&) = default;
};
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); every other
// term positive and below the duration (checked before any arithmetic); 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. A
// request above 60s cannot have applied; a non-positive request fences.
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