From ba97c41ad01184fa0101bce80306257168af0c4b Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 23:12:27 -0400 Subject: [PATCH] Add cellular checkpoint persistence calls --- docs/engineering/M11_3_DELIVERY_PLAN.md | 6 +++ docs/engineering/VALIDATION.md | 13 ++++++ .../evo/persistence/region_lease_store.hpp | 16 +++++++ src/persistence/region_lease_store.cpp | 45 +++++++++++++++++++ tests/region_lease_store_tests.cpp | 11 +++++ 5 files changed, 91 insertions(+) diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index 671d00c..774e59c 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -216,6 +216,12 @@ scoped change before starting the next segment. Migration-chain, privilege-audit, and parser tests are added. PostgreSQL CI is pending; the C++ writer, full process recovery, and RegionSessions v7 enablement remain open. +- 11.3d-6b: the persistence API now has separately named cellular publish and + ambiguous-commit resolution calls. Both pass canonical action bytes to the + profile-4 SQL wrappers and validate the returned receipt/status using the + existing store error contract. Focused PostgreSQL adapter tests cover malformed + calls; CI execution is pending. Payload preparation, replay validation, and a + cellular region host remain open. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index a0783f8..0505025 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -6214,3 +6214,16 @@ PostgreSQL migration and integration tests were not run locally because `psql` i not installed in this Windows environment; Linux/PostgreSQL CI qualification remains pending. The C++ writer, replay verification, crash/restart process tests, and RegionSessions v7 enablement remain open. +## 2026-10-10 — M11.3d-6b cellular PostgreSQL adapter (CI pending) + +Added `publish_cellular_checkpoint` and `resolve_cellular_region_commit` to the +region persistence interface. They call only the profile-4 SQL wrappers, preserve +their exact manifest/decision/action bytes, classify SQL failures through the +existing lease-store contract, and parse the normal durable receipt or resolution +status. The PostgreSQL adapter integration test now verifies malformed calls are +rejected as invalid requests. + +`git diff --check` passes. The adapter and PostgreSQL integration tests have not +run locally; this Windows environment lacks the PostgreSQL build/runtime needed +for `EVO_BUILD_POSTGRES`, so CI is required. No cellular host calls these methods +yet. diff --git a/include/evo/persistence/region_lease_store.hpp b/include/evo/persistence/region_lease_store.hpp index fa4bd4c..2e32aee 100644 --- a/include/evo/persistence/region_lease_store.hpp +++ b/include/evo/persistence/region_lease_store.hpp @@ -76,6 +76,14 @@ publish_region_checkpoint(Postgres& db, std::span manifest, std::span decisions, std::span actions, std::chrono::milliseconds timeout); +// Schema v20, ADR-0112: profile-4 checkpoints use a distinct publisher so the +// canonical cellular action block is bound to the checkpoint and durable result rows. +[[nodiscard]] std::expected +publish_cellular_checkpoint(Postgres& db, std::span manifest, + std::span decisions, + std::span actions, + std::chrono::milliseconds timeout); + enum class Resolution : std::uint8_t { committed, // Exact bytes are durable; receipt holds the head. Grants no authority. absent, // Not committed now; proves nothing about a request still in flight. @@ -96,6 +104,14 @@ resolve_region_commit(Postgres& db, RegionKey key, const Uuid& commit, std::span manifest, std::span decisions, std::span actions, std::chrono::milliseconds timeout); + +// Schema v20 resolution also compares the immutable profile-4 cellular action block. +[[nodiscard]] std::expected +resolve_cellular_region_commit(Postgres& db, RegionKey key, const Uuid& commit, + std::span manifest, + std::span decisions, + std::span actions, + std::chrono::milliseconds timeout); // The committed record of an account's action in the lease's world (schema v11), under the // caller's exact lease. Nothing when the action was never committed. struct CommittedAction { diff --git a/src/persistence/region_lease_store.cpp b/src/persistence/region_lease_store.cpp index ece734e..5093442 100644 --- a/src/persistence/region_lease_store.cpp +++ b/src/persistence/region_lease_store.cpp @@ -336,6 +336,22 @@ publish_region_checkpoint(Postgres& db, std::span manifest, return *head; } +std::expected +publish_cellular_checkpoint(Postgres& db, std::span manifest, + std::span decisions, + std::span actions, milliseconds timeout) { + const std::array p{bytea(manifest), bytea(decisions), bytea(actions)}; + auto rows = db.query( + "SELECT * FROM evolution.publish_cellular_checkpoint($1::bytea, $2::bytea, $3::bytea)", + p, timeout); + if (!rows) + return std::unexpected{classify(rows.error())}; + auto head = parse_head(*rows); + if (!head) + return std::unexpected{malformed(true)}; + return *head; +} + std::expected resolve_region_commit(Postgres& db, RegionKey key, const Uuid& commit, std::span manifest, @@ -367,6 +383,35 @@ resolve_region_commit(Postgres& db, RegionKey key, const Uuid& commit, return ResolvedCommit{Resolution::committed, *head}; } +std::expected +resolve_cellular_region_commit(Postgres& db, RegionKey key, const Uuid& commit, + std::span manifest, + std::span decisions, + std::span actions, milliseconds timeout) { + const std::array p{std::to_string(key.world), std::to_string(key.region), + uuid_text(commit), bytea(manifest), + bytea(decisions), bytea(actions)}; + auto rows = db.query( + "SELECT * FROM evolution.resolve_cellular_region_commit($1::evolution.u64, " + "$2::evolution.u64, $3::uuid, $4::bytea, $5::bytea, $6::bytea)", + p, timeout); + if (!rows) + return std::unexpected{classify(rows.error())}; + if (rows->size() != 1 || (*rows)[0].size() != 6 || !(*rows)[0][0]) + return std::unexpected{malformed(false)}; + const auto& status = *(*rows)[0][0]; + if (status == "absent") + return ResolvedCommit{Resolution::absent, {}}; + if (status == "conflict") + return ResolvedCommit{Resolution::conflict, {}}; + const PgRows receipt{ + std::vector>((*rows)[0].begin() + 1, (*rows)[0].end())}; + auto head = status == "committed" ? parse_head(receipt) : std::nullopt; + if (!head) + return std::unexpected{malformed(false)}; + return ResolvedCommit{Resolution::committed, *head}; +} + std::expected, LeaseStoreFailure> find_region_action(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& account, std::uint64_t action_id, milliseconds timeout) { diff --git a/tests/region_lease_store_tests.cpp b/tests/region_lease_store_tests.cpp index d6c843c..5a5de5c 100644 --- a/tests/region_lease_store_tests.cpp +++ b/tests/region_lease_store_tests.cpp @@ -183,6 +183,16 @@ void runtime_cannot_bypass_the_guard() { CHECK(release_region_lease(*db, key, *lease, 5s)); } +void cellular_publisher_adapter_rejects_malformed_requests() { + auto db = runtime(); + const std::vector empty; + auto published = publish_cellular_checkpoint(*db, empty, empty, empty, 5s); + CHECK(failed(published, LeaseStoreError::invalid)); + auto resolved = resolve_cellular_region_commit(*db, {1, 999}, id(0xC1), empty, empty, empty, + 5s); + CHECK(failed(resolved, LeaseStoreError::invalid)); +} + void acquire_renew_release_and_publish() { auto admin = owner(); const auto key = provision(*admin, 20); @@ -517,6 +527,7 @@ void measure_round_trips() { void run_region_lease_store_tests() { runtime_cannot_bypass_the_guard(); + cellular_publisher_adapter_rejects_malformed_requests(); acquire_renew_release_and_publish(); database_time_expiry_and_paused_writer(); queued_writer_uses_post_lock_database_time();