From c6df1f4e30900b43cd8dde9f24d389c1fdbbe90d Mon Sep 17 00:00:00 2001 From: dingo Date: Fri, 9 Oct 2026 22:00:49 -0400 Subject: [PATCH] Add typed primitive life reservation adapter and reconciliation tests --- CMakeLists.txt | 1 + docs/engineering/M11_2_DELIVERY_PLAN.md | 2 + docs/engineering/VALIDATION.md | 15 +++ .../persistence/life_reservation_store.hpp | 48 +++++++ schemas/life-reservations-v1.md | 8 ++ src/persistence/region_lease_store.cpp | 84 ++++++++++++ tests/life_reservation_store_tests.cpp | 121 ++++++++++++++++++ tests/postgres_tests.cpp | 12 +- tools/ci/postgres-check.sh | 1 + 9 files changed, 291 insertions(+), 1 deletion(-) create mode 100644 include/evo/persistence/life_reservation_store.hpp create mode 100644 tests/life_reservation_store_tests.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index c2345b0..f53badc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -262,6 +262,7 @@ if(EVO_BUILD_POSTGRES) # Contention tests use one thread and one connection per contender. add_executable(evo-postgres-tests tests/postgres_tests.cpp tests/region_lease_store_tests.cpp tests/account_control_store_tests.cpp tests/probe_handoff_store_tests.cpp + tests/life_reservation_store_tests.cpp tests/region_action_tests.cpp tests/region_checkpoint_store_tests.cpp tests/region_host_tests.cpp tests/region_server_process_tests.cpp tests/region_recovery_tests.cpp diff --git a/docs/engineering/M11_2_DELIVERY_PLAN.md b/docs/engineering/M11_2_DELIVERY_PLAN.md index bbc12f5..a034cfc 100644 --- a/docs/engineering/M11_2_DELIVERY_PLAN.md +++ b/docs/engineering/M11_2_DELIVERY_PLAN.md @@ -70,6 +70,8 @@ Local checks do not close ADR-0097's reference-worker qualification. - 11.2c-1: schema v15 reservations/identity allocation and durable refusals. These spend nothing and do not publish an organism. Focused PostgreSQL tests and the full migration/process, backup/restore, upgrade and privilege regressions pass. +- 11.2c-1 adapter: typed C++ reserve/refuse API, full unsigned identity range and + uncertain-response reconciliation validated in Release and ASan+UBSan. - 11.2c-2 and 11.2d remain: atomic funded checkpoint publication, reconciliation, host/session integration and crash-boundary qualification. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index ab6d1db..3923f9b 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -5543,3 +5543,18 @@ the proper Clang database completed cleanly. No sanitizer rerun is claimed for t SQL subsection; prior lifecycle sanitizer results remain recorded above. No wire type changed. All database work used disposable local clusters; no world deployment, reset or provisioning occurred. + +## 2026-10-09 — M11.2c-1 reservation adapter + +Added the Linux C++ reserve/refuse API and real-database tests for unsigned IDs +above INT64_MAX, UINT64_MAX request IDs, exact reconnect retries, stable refusals, +missing provisioning, invalid inputs, exhaustion, stale control and takeover +routing. A deliberate allocator lock wait produces an unknown mutation response; +reconnecting with the same request reconciles exactly one allocation. + +Executed: GCC 14 Release build and focused PostgreSQL adapter/SQL/concurrency +tests; Clang 19 ASan+UBSan build and the same focused tests; clang-tidy on the +adapter and both affected test files; full format-check, shell syntax and diff +checks. All passed. The full PostgreSQL/process suite above belongs to the schema +subsection; it was not repeated for these adapter-only changes. No wire format, +deployed world or SQL migration changed in this subsection. diff --git a/include/evo/persistence/life_reservation_store.hpp b/include/evo/persistence/life_reservation_store.hpp new file mode 100644 index 0000000..e8493e6 --- /dev/null +++ b/include/evo/persistence/life_reservation_store.hpp @@ -0,0 +1,48 @@ +#pragma once +#include "evo/persistence/postgres.hpp" +#include "evo/persistence/region_lease.hpp" +#include +#include +#include + +namespace evo::persistence { +// Schema v15, ADR-0100. These operations allocate identity, never a biological +// body. Each call is one statement on the caller's connection, without retries. +enum class LifeReservationError : std::uint8_t { + existing_life, + fenced, + not_available, // Missing allocator/reservation, or reservation belongs elsewhere. + exhausted, + invalid, + store, + unknown // May have committed. Reconnect and retry the SAME request to reconcile. +}; +struct LifeReservationFailure { + LifeReservationError kind{}; + PgFailure cause{}; +}; +enum class LifeRefusal : std::uint8_t { + none = 0, // Reserved only; NOT successful spawn. + insufficient_funding = 1, + no_placement = 2, + cancelled = 3 +}; +struct LifeReservation { + std::uint64_t identity{}, region{}; + LifeRefusal refusal{}; + friend bool operator==(const LifeReservation&, const LifeReservation&) = default; +}; +// Exact retry returns the original identity/owning region/refusal, even after +// account control moves. The result grants no authority in the returned region. +// request_id is in the new-life namespace, separate from M10 probe action IDs. +[[nodiscard]] std::expected +reserve_primitive_life(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account, + std::uint64_t generation, std::uint64_t request_id, std::uint32_t rules, + std::chrono::milliseconds timeout); +// Requires control in the reservation's owning region. First refusal is final; +// repeats return it. Passing none or an unknown enum value is invalid. +[[nodiscard]] std::expected +reject_primitive_life(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account, + std::uint64_t generation, std::uint64_t request_id, LifeRefusal reason, + std::chrono::milliseconds timeout); +} // namespace evo::persistence diff --git a/schemas/life-reservations-v1.md b/schemas/life-reservations-v1.md index 8909a65..5549477 100644 --- a/schemas/life-reservations-v1.md +++ b/schemas/life-reservations-v1.md @@ -54,3 +54,11 @@ Final spawn success, checkpoint publication and reconciliation are 11.2c-2/d. Validation: `tools/ci/postgres-check.sh --life-reservations-only` starts a fresh local socket-only PostgreSQL test cluster. The full postgres-check also executes these tests, alongside migration, backup, restore and existing process checks. +Pass a built `evo-postgres-tests` as the second argument to include the typed +adapter tests in the focused run. + +The Linux adapter in `evo/persistence/life_reservation_store.hpp` returns the +allocated identity, owning region and a typed refusal. It preserves the entire +unsigned 64-bit range and performs no automatic retries. A timeout or malformed +mutation reply is `unknown`: reconnect and retry the same request to reconcile. +Callers must never reinterpret a reservation as final spawn success. diff --git a/src/persistence/region_lease_store.cpp b/src/persistence/region_lease_store.cpp index ad6a779..238dca7 100644 --- a/src/persistence/region_lease_store.cpp +++ b/src/persistence/region_lease_store.cpp @@ -1,5 +1,6 @@ #include "evo/persistence/region_lease_store.hpp" #include "evo/persistence/account_control_store.hpp" +#include "evo/persistence/life_reservation_store.hpp" #include "evo/persistence/probe_store.hpp" #include #include @@ -577,6 +578,89 @@ release_account_control(Postgres& db, RegionKey key, const LeaseGrant& lease, co return text == "true"; } +namespace { +LifeReservationFailure life_failure(const PgFailure& f) { + const std::string_view state(f.sqlstate.data(), 5); + auto kind = LifeReservationError::store; + if (f.kind == PgError::unknown) + kind = LifeReservationError::unknown; + else if (f.kind == PgError::config || f.kind == PgError::bounds || state == "22023") + kind = LifeReservationError::invalid; + else if (state == "EVL16") + kind = LifeReservationError::existing_life; + else if (state == "EVL02" || state == "EVL06") + kind = LifeReservationError::fenced; + else if (state == "EVL04") + kind = LifeReservationError::not_available; + else if (state == "EVL05") + kind = LifeReservationError::exhausted; + return {kind, f}; +} +} // namespace + +std::expected +reserve_primitive_life(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account, + std::uint64_t generation, std::uint64_t request_id, std::uint32_t rules, + milliseconds timeout) { + // Avoid a PostgreSQL integer cast failure for arbitrary unsigned rule versions. + if (rules != 1) + return std::unexpected{LifeReservationFailure{LifeReservationError::invalid, {}}}; + const auto base = control_parameters(key, lease, account, generation); + const std::array p{base[0], + base[1], + base[2], + base[3], + base[4], + base[5], + std::to_string(request_id), + std::to_string(rules)}; + auto rows = db.query("SELECT * FROM evolution.reserve_primitive_life($1::evolution.u64, " + "$2::evolution.u64, $3::uuid, $4::evolution.u64, $5::uuid, " + "$6::evolution.u64, $7::evolution.u64, $8::integer)", + p, timeout); + if (!rows) + return std::unexpected{life_failure(rows.error())}; + const auto unknown = LifeReservationFailure{LifeReservationError::unknown, {}}; + if (rows->size() != 1 || (*rows)[0].size() != 3) + return std::unexpected{unknown}; + const auto identity = parse_integer((*rows)[0][0]); + const auto region = parse_integer((*rows)[0][1]); + const auto refusal = parse_integer((*rows)[0][2]); + if (!identity || *identity == 0 || !region || *region == 0 || !refusal || *refusal > 3) + return std::unexpected{unknown}; + return LifeReservation{*identity, *region, static_cast(*refusal)}; +} + +std::expected +reject_primitive_life(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account, + std::uint64_t generation, std::uint64_t request_id, LifeRefusal reason, + milliseconds timeout) { + const auto value = static_cast(reason); + if (value < 1 || value > 3) + return std::unexpected{LifeReservationFailure{LifeReservationError::invalid, {}}}; + const auto base = control_parameters(key, lease, account, generation); + const std::array p{base[0], + base[1], + base[2], + base[3], + base[4], + base[5], + std::to_string(request_id), + std::to_string(value)}; + auto rows = db.query("SELECT evolution.reject_primitive_life($1::evolution.u64, " + "$2::evolution.u64, $3::uuid, $4::evolution.u64, $5::uuid, " + "$6::evolution.u64, $7::evolution.u64, $8::smallint)", + p, timeout); + if (!rows) + return std::unexpected{life_failure(rows.error())}; + const auto refusal = rows->size() == 1 && (*rows)[0].size() == 1 + ? parse_integer((*rows)[0][0]) + : std::nullopt; + if (!refusal || *refusal < 1 || *refusal > 3) + return std::unexpected{LifeReservationFailure{LifeReservationError::unknown, {}}}; + return static_cast(*refusal); +} + // Schema v12 probe records and handoff (ADR-0096). Shares this file's parsing rules. namespace { ProbeStoreFailure probe_failure(const PgFailure& f) { diff --git a/tests/life_reservation_store_tests.cpp b/tests/life_reservation_store_tests.cpp new file mode 100644 index 0000000..a64a5ba --- /dev/null +++ b/tests/life_reservation_store_tests.cpp @@ -0,0 +1,121 @@ +// Real PostgreSQL schema v15 adapter checks, isolated world 9752. +#include "evo/persistence/account_control_store.hpp" +#include "evo/persistence/life_reservation_store.hpp" +#include "evo/persistence/region_lease_store.hpp" +#include +#include +#include +#include +#include + +void run_life_reservation_store_tests(); + +namespace { +using namespace evo::persistence; +using namespace std::chrono_literals; +void check(bool value, std::source_location at = std::source_location::current()) { + if (!value) + throw std::runtime_error("life reservation store test line " + std::to_string(at.line())); +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) +std::string env(const char* name) { + const auto* value = std::getenv(name); + if (!value) + throw std::runtime_error("missing PostgreSQL test environment"); + return value; +} +std::unique_ptr connect_as(const std::string& user) { + auto db = + Postgres::connect({env("PGHOST"), {}, env("PGPORT"), env("PGDATABASE"), user, {}, {}}, 5s); + CHECK(db); + return std::move(*db); +} +bool failed(const auto& result, LifeReservationError kind) { + return !result && result.error().kind == kind; +} +} // namespace + +void run_life_reservation_store_tests() { + auto admin = connect_as(env("PGUSER")); + auto db = connect_as(env("EVO_PG_RUNTIME_USER")); + CHECK(admin->query("INSERT INTO evolution.retained_builds(build_identity) VALUES " + "(decode(repeat('d6',32),'hex')) ON CONFLICT DO NOTHING", + {}, 5s)); + CHECK(admin->query("INSERT INTO evolution.region_leases(world_id,region_id,frame_id) " + "VALUES (9752,1,1),(9752,2,1)", + {}, 5s)); + Sha256Digest build{}; + build.fill(0xD6); + const RegionKey a{9752, 1}, b{9752, 2}; + const auto lease_a = acquire_region_lease(*db, a, build, 20000ms, 5s); + const auto lease_b = acquire_region_lease(*db, b, build, 20000ms, 5s); + CHECK(lease_a && lease_b); + Uuid alice{}; + alice.fill(0x61); + const auto control = claim_account_control(*db, a, *lease_a, alice, 1, 1, 20000ms, 5s); + CHECK(control); + const auto request = std::numeric_limits::max(); + auto reserve = [&](std::uint64_t action, std::uint32_t rules = 1) { + return reserve_primitive_life(*db, a, *lease_a, alice, control->generation, action, rules, + 5s); + }; + CHECK(failed(reserve(request), LifeReservationError::not_available)); + CHECK(admin->query("INSERT INTO evolution.life_allocators VALUES " + "(9752,9223372036854775808)", + {}, 5s)); + CHECK(failed(reserve(0), LifeReservationError::invalid)); + CHECK(failed(reserve(request, 0), LifeReservationError::invalid)); + CHECK(failed(reserve(request, std::numeric_limits::max()), + LifeReservationError::invalid)); + const auto first = reserve(request); + CHECK(first && first->identity == 9223372036854775808ULL && first->region == 1 && + first->refusal == LifeRefusal::none); + db = connect_as(env("EVO_PG_RUNTIME_USER")); + CHECK(reserve(request) == *first); + CHECK(failed(reserve(2), LifeReservationError::existing_life)); + CHECK(failed(reserve_primitive_life(*db, a, *lease_a, alice, 2, request, 1, 5s), + LifeReservationError::fenced)); + CHECK(failed(reject_primitive_life(*db, a, *lease_a, alice, 1, request, LifeRefusal::none, 5s), + LifeReservationError::invalid)); + CHECK(reject_primitive_life(*db, a, *lease_a, alice, 1, request, + LifeRefusal::insufficient_funding, + 5s) == LifeRefusal::insufficient_funding); + CHECK(reject_primitive_life(*db, a, *lease_a, alice, 1, request, LifeRefusal::cancelled, 5s) == + LifeRefusal::insufficient_funding); + const auto refused = reserve(request); + CHECK(refused && refused->identity == first->identity && + refused->refusal == LifeRefusal::insufficient_funding); + + // Force an uncertain mutation response. Reconcile with the same request on + // a new connection, whether the interrupted statement committed or not. + CHECK(admin->query("BEGIN", {}, 5s)); + CHECK(admin->query("SELECT * FROM evolution.life_allocators WHERE world_id=9752 FOR UPDATE", {}, + 5s)); + CHECK(failed(reserve_primitive_life(*db, a, *lease_a, alice, 1, 2, 1, 20ms), + LifeReservationError::unknown)); + CHECK(admin->query("COMMIT", {}, 5s)); + db = connect_as(env("EVO_PG_RUNTIME_USER")); + const auto reconciled = reserve(2); + CHECK(reconciled && reconciled->identity == first->identity + 1); + CHECK(reserve(2) == *reconciled); + const auto counter = admin->query( + "SELECT next_identity FROM evolution.life_allocators WHERE world_id=9752", {}, 5s); + CHECK(counter && (*counter)[0][0] == "9223372036854775810"); + CHECK(reject_primitive_life(*db, a, *lease_a, alice, 1, 2, LifeRefusal::no_placement, 5s) == + LifeRefusal::no_placement); + CHECK(admin->query("UPDATE evolution.life_allocators SET next_identity=18446744073709551615 " + "WHERE world_id=9752", + {}, 5s)); + CHECK(failed(reserve(3), LifeReservationError::exhausted)); + + const auto moved = claim_account_control(*db, b, *lease_b, alice, 2, 2, 20000ms, 5s); + CHECK(moved); + CHECK(reserve_primitive_life(*db, b, *lease_b, alice, moved->generation, request, 1, 5s) == + *refused); + CHECK(failed(reject_primitive_life(*db, b, *lease_b, alice, moved->generation, request, + LifeRefusal::cancelled, 5s), + LifeReservationError::not_available)); + CHECK(failed(reserve(request), LifeReservationError::fenced)); + CHECK(release_region_lease(*db, a, *lease_a, 5s)); + CHECK(release_region_lease(*db, b, *lease_b, 5s)); +} diff --git a/tests/postgres_tests.cpp b/tests/postgres_tests.cpp index 3b6e4d2..a12e03e 100644 --- a/tests/postgres_tests.cpp +++ b/tests/postgres_tests.cpp @@ -3,8 +3,10 @@ #include #include #include +#include void run_region_lease_store_tests(); void run_account_control_store_tests(); +void run_life_reservation_store_tests(); void run_probe_handoff_store_tests(); void run_region_action_tests(); void run_region_checkpoint_store_tests(); @@ -118,12 +120,20 @@ void run() { CHECK(!Postgres::connect(options, 1s)); } } // namespace -int main() { +int main(int argc, char** argv) { try { + if (argc == 2 && std::string_view(argv[1]) == "--life-reservations-only") { + run_life_reservation_store_tests(); + std::puts("life reservation adapter integration passed"); + return 0; + } + if (argc != 1) + return 2; run(); std::puts("postgres adapter integration passed"); run_region_lease_store_tests(); run_account_control_store_tests(); + run_life_reservation_store_tests(); run_probe_handoff_store_tests(); run_region_action_tests(); std::puts("region lease fencing integration passed"); diff --git a/tools/ci/postgres-check.sh b/tools/ci/postgres-check.sh index c3a6c4c..f91a442 100644 --- a/tools/ci/postgres-check.sh +++ b/tools/ci/postgres-check.sh @@ -18,6 +18,7 @@ export EVO_PG_RUNTIME_ROLE=evo_runtime_test EVO_PG_RUNTIME_USER=evo_runtime_logi bash "$root/tools/migrate-postgres.sh" bash "$root/tools/migrate-postgres.sh" # exact supported upgrade/restart is a no-op if [ "${1:-}" = --life-reservations-only ]; then + if [ "$#" = 2 ]; then "$2" --life-reservations-only; fi psql -X -v ON_ERROR_STOP=1 -f "$root/tools/ci/life-reservations-check.sql" > /dev/null bash "$root/tools/ci/life-reservations-concurrency.sh" exit 0