From 5d4f59f9018871d0738222c60f7786ae3f08f3bd Mon Sep 17 00:00:00 2001 From: dingo Date: Mon, 28 Sep 2026 15:25:27 -0400 Subject: [PATCH] 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 --- CMakeLists.txt | 23 +- .../postgres-migration/job.yaml.example | 2 +- docs/ROADMAP.md | 14 + docs/STATUS.md | 19 + docs/adr/0003-dependencies.md | 4 +- docs/adr/0060-fenced-region-ownership.md | 2 + docs/adr/0061-checkpoint-publication.md | 112 ++++++ docs/adr/README.md | 1 + docs/architecture/REGION_DURABILITY.md | 14 + docs/engineering/VALIDATION.md | 55 +++ docs/infrastructure/POSTGRESQL.md | 45 ++- include/evo/persistence/checkpoint_store.hpp | 68 ++++ include/evo/persistence/object_store.hpp | 57 +++ include/evo/persistence/region_checkpoint.hpp | 89 +++++ include/evo/persistence/region_lease.hpp | 1 + .../evo/persistence/region_lease_store.hpp | 25 +- include/evo/persistence/sha256.hpp | 13 + migrations/0003_region_checkpoints.sql | 236 ++++++++++++ migrations/apply.sql | 15 +- schemas/region-commit.md | 39 +- src/persistence/checkpoint_store.cpp | 154 ++++++++ src/persistence/object_store.cpp | 200 ++++++++++ src/persistence/region_checkpoint.cpp | 220 +++++++++++ src/persistence/region_lease_store.cpp | 68 ++-- src/persistence/sha256.cpp | 13 + tests/fixtures/environmental_region.hpp | 84 +++++ tests/postgres_tests.cpp | 3 + tests/region_checkpoint_store_tests.cpp | 357 ++++++++++++++++++ tests/region_checkpoint_tests.cpp | 199 ++++++++++ tests/region_lease_store_tests.cpp | 237 +++++++----- tools/ci/postgres-check.sh | 24 +- tools/migrate-postgres.sh | 5 +- 32 files changed, 2253 insertions(+), 145 deletions(-) create mode 100644 docs/adr/0061-checkpoint-publication.md create mode 100644 include/evo/persistence/checkpoint_store.hpp create mode 100644 include/evo/persistence/object_store.hpp create mode 100644 include/evo/persistence/region_checkpoint.hpp create mode 100644 include/evo/persistence/sha256.hpp create mode 100644 migrations/0003_region_checkpoints.sql create mode 100644 src/persistence/checkpoint_store.cpp create mode 100644 src/persistence/object_store.cpp create mode 100644 src/persistence/region_checkpoint.cpp create mode 100644 src/persistence/sha256.cpp create mode 100644 tests/fixtures/environmental_region.hpp create mode 100644 tests/region_checkpoint_store_tests.cpp create mode 100644 tests/region_checkpoint_tests.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 91e09d0..e6419fb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -77,6 +77,11 @@ add_library(evo::region_lease ALIAS evo_region_lease) target_include_directories(evo_region_lease PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") target_compile_features(evo_region_lease PUBLIC cxx_std_23) evo_owned_target(evo_region_lease) +# Portable checkpoint manifest codec and environmental-v1 payload validation. +add_library(evo_region_checkpoint STATIC src/persistence/region_checkpoint.cpp) +add_library(evo::region_checkpoint ALIAS evo_region_checkpoint) +target_link_libraries(evo_region_checkpoint PUBLIC evo::region_lease evo::processes) +evo_owned_target(evo_region_checkpoint) include(CTest) if(EVO_BUILD_POSTGRES) @@ -90,10 +95,19 @@ if(EVO_BUILD_POSTGRES) target_include_directories(evo_postgres PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") target_link_libraries(evo_postgres PUBLIC evo::region_lease PRIVATE PostgreSQL::PostgreSQL) evo_owned_target(evo_postgres) + # SHA-256 via system OpenSSL libcrypto (already required by libpq TLS; ADR-0061). + find_package(OpenSSL 3 REQUIRED COMPONENTS Crypto) + add_library(evo_region_store STATIC src/persistence/sha256.cpp src/persistence/object_store.cpp + src/persistence/checkpoint_store.cpp) + add_library(evo::region_store ALIAS evo_region_store) + target_link_libraries(evo_region_store PUBLIC evo::postgres evo::region_checkpoint + PRIVATE OpenSSL::Crypto) + evo_owned_target(evo_region_store) if(BUILD_TESTING) # 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) - target_link_libraries(evo-postgres-tests PRIVATE evo::postgres Threads::Threads) + add_executable(evo-postgres-tests tests/postgres_tests.cpp tests/region_lease_store_tests.cpp + tests/region_checkpoint_store_tests.cpp) + target_link_libraries(evo-postgres-tests PRIVATE evo::region_store Threads::Threads) evo_owned_target(evo-postgres-tests) # Intentionally not an ordinary CTest: tools/ci/postgres-check.sh owns its private DB. endif() @@ -104,6 +118,11 @@ if(BUILD_TESTING) evo_owned_target(evo-region-lease-tests) add_test(NAME region-lease-contracts COMMAND evo-region-lease-tests) set_tests_properties(region-lease-contracts PROPERTIES TIMEOUT 60) + add_executable(evo-region-checkpoint-tests tests/region_checkpoint_tests.cpp) + target_link_libraries(evo-region-checkpoint-tests PRIVATE evo::region_checkpoint) + evo_owned_target(evo-region-checkpoint-tests) + add_test(NAME region-checkpoint-contracts COMMAND evo-region-checkpoint-tests) + set_tests_properties(region-checkpoint-contracts PROPERTIES TIMEOUT 60) add_executable(evo-environmental-qualification tests/environmental_qualification.cpp) target_link_libraries(evo-environmental-qualification PRIVATE evo::processes) evo_owned_target(evo-environmental-qualification) diff --git a/deploy/kubernetes/postgres-migration/job.yaml.example b/deploy/kubernetes/postgres-migration/job.yaml.example index b643314..94a3aad 100644 --- a/deploy/kubernetes/postgres-migration/job.yaml.example +++ b/deploy/kubernetes/postgres-migration/job.yaml.example @@ -3,7 +3,7 @@ apiVersion: batch/v1 kind: Job metadata: - name: evolution-db-migrate-v2 + name: evolution-db-migrate-v3 namespace: evolution-dev spec: backoffLimit: 0 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 64cbca3..3074c2b 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -515,3 +515,17 @@ Real-PostgreSQL tests cover the scenarios the roadmap row requires: Timings were selected and measured locally. The director is intentionally deferred because it has no authority and would be a placeholder. Next: M7.4 checkpoint codecs/publication. It must also revoke runtime EXECUTE on the bare head kernel. + +M7.4 split into 7.4a (environmental-v1 publication) and 7.4b (lineage archive +codec and history-capable binding). M7.4a is implemented and locally qualified +(2026-09-28) under ADR-0061: +- Manifest v1 is 280 bytes and is parsed by the database itself. +- Schema v3 adds a commit chain with digest and head constraints, retained + builds, and fenced publication. The bare v2 kernel is dropped. +- SHA-256 comes from OpenSSL, and payloads go to an immutable filesystem store. +- Publication validates, uploads, verifies, then commits. Recovery re-digests and + verifies. +- Missing or corrupt objects, upload and manifest failures, orphans, size caps, + retained-build allowlists and restored-trajectory equality are covered. + +Next: M7.4b. M7.4 stays open until it passes. diff --git a/docs/STATUS.md b/docs/STATUS.md index eaf69d0..c7020f0 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -769,3 +769,22 @@ lease check, a disabled busy check) were each detected by a failing test. Windows ran 55/55; Linux Release, clang-tidy and ASan/UBSan PostgreSQL suites passed in WSL. No director, host, gateway, payload publication or deployment exists yet. The v2 head must not carry real world state before M7.4. Next: M7.4. + +## M7.4a checkpoint publication (2026-09-28) + +ADR-0061 and schema v3 publish environmental-v1 checkpoints. A fixed 280-byte +manifest is parsed and digested by PostgreSQL. Payloads live in an immutable, +content-addressed filesystem store and are hashed with OpenSSL SHA-256. The +database enforces the commit chain, retained builds and fixed versions/quantum, +and refuses to migrate while v2 heads exist. + +Recovery re-digests the manifest, checks the build allowlist and fully restores the +payload. A restored state continues identically to the uninterrupted original. +Missing, corrupt or tampered data quarantines the region. Four SQL mutations and +one host mutation were each caught by a test. + +Local fixture payloads are 23-37 KiB and publish in about 3.5-10.6 ms across +builds. Windows ran 56/56; Linux Release, clang-tidy and ASan/UBSan PostgreSQL +suites passed in WSL. M7.4 stays open for M7.4b (lineage archive codec and +history-capable binding). No real world was provisioned; there is no deployment, +host or process-kill test yet. diff --git a/docs/adr/0003-dependencies.md b/docs/adr/0003-dependencies.md index bf3da8d..60e259d 100644 --- a/docs/adr/0003-dependencies.md +++ b/docs/adr/0003-dependencies.md @@ -35,4 +35,6 @@ Record revision/hash, owner, license, build options and removal boundary; mirror M7.2's [ADR-0059](0059-postgresql-bootstrap.md) accepts a scoped checksum-pinned source build for the paired PostgreSQL server/client. The general cross-platform -package-manager comparison remains open. +package-manager comparison remains open. M7.4's [ADR-0061](0061-checkpoint-publication.md) +links system OpenSSL 3 libcrypto (already required by libpq TLS) for SHA-256 in the +Linux persistence adapter only. diff --git a/docs/adr/0060-fenced-region-ownership.md b/docs/adr/0060-fenced-region-ownership.md index 72dc728..6ff526d 100644 --- a/docs/adr/0060-fenced-region-ownership.md +++ b/docs/adr/0060-fenced-region-ownership.md @@ -97,6 +97,8 @@ binds it to verified payloads, so v2 must not host real world state. Custom SQLSTATEs are project conventions; they are not PostgreSQL-reserved. ## Consequences +Done in M7.4a (ADR-0061): schema v3 drops the bare kernel and publishes through a +manifest-parsing function under the same lock order. The M7.4 migration must add the manifest/payload publication function that calls the kernel, and revoke runtime EXECUTE on `advance_region_head`. M7.5 adds commit-ID resolution. Until then, "head equals my commit ID" is only the primitive diff --git a/docs/adr/0061-checkpoint-publication.md b/docs/adr/0061-checkpoint-publication.md new file mode 100644 index 0000000..7611ec9 --- /dev/null +++ b/docs/adr/0061-checkpoint-publication.md @@ -0,0 +1,112 @@ +# ADR-0061: Checkpoint publication and verified recovery + +## Status +Accepted for M7.4a, 2026-09-28. Covers the `environmental-v1` profile only. The +lineage archive codec and history-capable profile binding are M7.4b; M7.4 is not +complete until both parts pass. Decisions, outbox and commit resolution remain M7.5. + +## Context +ADR-0058 selects full checkpoint batches: payload bytes go to an immutable object, +then a fenced database transaction makes them the committed head. ADR-0060 fences +the head, but its v2 kernel accepts any 32-byte digest with no payload behind it. +ADR-0059 deferred the SHA-256 provider. No object-store dependency has been selected. +The M6 environmental envelope is complete for its profile and already validates +itself fully on restore. + +## Decision +**Manifest v1** is a fixed 280-byte little-endian record (schemas/region-commit.md) +holding: +- identity, commit ID and sequence, predecessor ID and digest, and the tick range; +- the lease holder and epoch, and the tick quantum; +- nine pinned versions and the retained build identity; +- explicit declarations that there are zero RNG streams, no history profile, and a + single-volume development durability policy; +- the payload length and SHA-256. + +The commit digest is SHA-256 of these bytes. The database parses the same bytes +itself, so no separately supplied field can disagree with the digested record. + +**Schema v3** makes the following changes: +- It adds `region_commits`. A CHECK constraint ties each commit digest to its + manifest, and a composite foreign key requires the head to name an existing + commit with the same ID and digest. +- It adds owner-managed `retained_builds`. +- It adds `publish_region_checkpoint(manifest)`, in the same order as the v2 kernel: + lease row lock, database-time lease check, then head lock. It requires the + exact successor of the committed head, with unchanged versions and tick quantum, + a retained build, and a unique commit ID. +- It adds `load_region_checkpoint` and owner-only `provision_region_checkpoint` + for genesis. +- It drops the v2 kernel and v2 provisioning functions. +- It refuses to migrate a database that still has v2 heads, because those have no + payload binding. Such regions must be re-provisioned. + +The runtime role can execute exactly six functions. + +**SHA-256** comes from the system OpenSSL 3 libcrypto EVP interface. It is linked +only into the Linux `evo::region_store` adapter. libpq TLS already requires that +library in the same images. Locally observed: Ubuntu `libssl3t64`/`libssl-dev` +3.0.13-0ubuntu3.15, Apache-2.0. PostgreSQL's built-in `sha256()` independently +computes commit digests, and the host checks that the receipt matches. + +**Object store**: a filesystem store on a trusted mounted volume (Linux only). +- Each region has its own `w/r` directory with mode 0700. Objects + are named by the hex SHA-256 of their content. +- Upload writes a private temporary file, fsyncs it, `link()`s it to the key (a + link never replaces an existing name), and then fsyncs the directory. +- Existing identical content is reused. Differing content already under a key is + reported as corrupt and never overwritten. +- Reads use `O_NOFOLLOW`, check an exact-length regular file before allocating, + and verify the digest. +- There is no delete or GC operation: unreferenced uploads are orphans. + +**Publication order**: +1. Validate the candidate the way recovery would: full envelope restore, + identity, tick and quantum checks, and a byte-identical re-encode. +2. Upload the payload. +3. Read it back and verify it. +4. Run the fenced transaction. +5. Compare the receipt with the local manifest digest. + +Only step 4 has authority. **Recovery** loads the head and manifest, re-digests +the manifest, requires the head fields to match and the build to be in the host's +retained allowlist, fetches and verifies the object, and fully restores it. It +never creates genesis or selects an older head. A missing or corrupt payload +quarantines the region. + +## Alternatives Considered +- **S3/MinIO clients** add a large network dependency before any measured need. + The interface boundary allows one later, with a separate ADR. +- **Payload bytes in PostgreSQL** was deferred by ADR-0058 until measured. +- **Host-supplied manifest fields as SQL parameters** could disagree with the + digested bytes. +- **A project-written SHA-256** is forbidden by the constitution. +- **rename()** can silently replace an existing object. + +## Benefits +The committed head is always backed by a verified, immutable payload whose +identity, chain, lease and versions the database has checked. Tampering is +blocked by constraints and detected again on recovery. Crashes before the +transaction leave the previous head. + +## Costs +- A full payload is written per batch. The local fixture's payload is about 23-37 + KiB, and publication took about 3.5-6.6 ms in non-sanitizer builds. +- Orphans accumulate. +- The existing v2 regions must be re-provisioned. +- Recovery fetches whole payloads. + +## Risks +- A single volume is not host-loss durability (M8). +- `fsync` semantics depend on the filesystem and mount options. The local test + volume does not prove power-loss behavior. +- The database cannot validate payload contents: a compromised worker holding a + valid lease can publish a self-consistent but illegitimate state (ADR-0058). +- The read-back verification path is not exercised by any fault injection. + +## Consequences +M7.4b adds the lineage archive codec, organism-to-genome binding and a separately +versioned history-capable profile. M7.5 adds decisions, outbox and commit-ID +resolution to the same transaction. Operators insert each promoted image digest +into `retained_builds` before hosts publish with it, and hosts restore only builds +in their own allowlist. diff --git a/docs/adr/README.md b/docs/adr/README.md index e5865f7..8beba09 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -71,3 +71,4 @@ design. No unadopted candidate is a link dependency of the proof. - [ADR-0059: PostgreSQL bootstrap](0059-postgresql-bootstrap.md) - accepted for M7.2 optional adapter, pinned server/client, migrations and Secret boundary. - [ADR-0060: Fenced region ownership](0060-fenced-region-ownership.md) - accepted for M7.3 database-time leases, guarded head advance, runtime grants and selected timings. +- [ADR-0061: Checkpoint publication](0061-checkpoint-publication.md) - accepted for M7.4a manifest v1, immutable filesystem objects, OpenSSL SHA-256 and verified recovery. diff --git a/docs/architecture/REGION_DURABILITY.md b/docs/architecture/REGION_DURABILITY.md index 9d8b14b..7e2c01f 100644 --- a/docs/architecture/REGION_DURABILITY.md +++ b/docs/architecture/REGION_DURABILITY.md @@ -168,3 +168,17 @@ rejected, and the head is unchanged. A paused stale worker resuming past its lea is fenced both locally and by the database. A writer queued on the lease lock past expiry is also rejected. These are in-process pauses, not killed pods or network partitions. The 7.6 parts of those rows remain open. + +M7.4a (ADR-0061) executed its rows for environmental-v1 against real PostgreSQL and +a local filesystem object store: +- A partial upload leaves only an unresolvable temporary name. +- A failed upload sends no manifest. +- A verified upload whose transaction is rejected stays an unreferenced orphan, + and recovery returns the previous head. +- Missing, corrupt, symlinked or resized payloads quarantine the region. +- Unsupported builds are refused by both the database and recovery. +- Recovery never creates genesis or picks an older head. + +Two parts remain open. M7.4b adds the lineage archive codec and a history-capable +profile; until then the history rows of this audit stay open. No process-kill +test was run yet (7.7). diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 84a7045..f6a4379 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -2103,3 +2103,58 @@ Only clean-to-v1 and exact-v1 restart are supported migration paths at this gate overflow (`9223372036854775807 + 2000`). - Reran Windows CTest 55/55, the repository format check, and GCC14 Release, clang-tidy analysis and ASan/UBSan private-PostgreSQL suites: all passed. + +## M7.4a checkpoint publication - 2026-09-28 + +- Windows MSVC Release configure/build/CTest passed 56/56, including the new + portable `region-checkpoint-contracts`. It covers: + - golden byte offsets and round trips; + - malformed and unsupported manifests, including u32 values above 255 that + must not truncate onto supported enums; + - chain rules; + - payload identity, tick, quantum, corruption and budget checks; + - 24-tick continuation equality after restore. + The repository clang-format 19 check passed. +- WSL Ubuntu, with GCC 14.2.0, clang 19.1.1, PostgreSQL/libpq 18.6 and OpenSSL + 3.0.13-0ubuntu3.15, running as uid 1000 so permission faults were really + exercised. GCC14 Release, clang19 analysis (clang-tidy warnings-as-errors) and + clang19 ASan/UBSan each passed `tools/ci/postgres-check.sh`. +- Analysis initially flagged `performance-enum-size` on the u32-based + profile/durability enums. They are now u8 with explicit decoding of values + above 255 as unknown. All three configurations were rerun. +- New real-database/filesystem coverage: + - SHA-256 vectors (NIST "", "abc" and the 448-bit message) and agreement with + PostgreSQL `sha256()`. + - Object store: rejects root symlinks, creates 0700 namespaces, puts are + idempotent, never overwrites differing content, ignores temporary leftovers, + and detects byte flips, symlinks, truncation and growth. Size bounds and + write-permission failure are also covered. + - Genesis provisioning and duplicate refusal; three batches (16/64/16 ticks); + a 65-tick batch refused before upload. + - Recovery from a new store handle is byte-identical and continues 44 ticks + identically to an uninterrupted reference. + - The build allowlist is enforced by the host and by the database. + - Upload failure leaves the head unchanged. A fenced publication leaves a + verified orphan, and recovery ignores it. + - Missing and corrupt payloads quarantine; restoring the object recovers. + - Owner edits to a manifest (23514) and head repointing (23503) are refused. + With the constraint dropped, recovery still detects the edit, and the + constraint is restored afterwards. + - Unknown regions are never created. +- Lease tests were ported to manifest publication. They additionally cover + malformed manifests, a quantum change, an unretained build, a future rules + version and a globally reused commit ID. +- Migrations: clean→v3, repeated no-op, v1→v3. v2 with existing heads fails + closed and stays at v2. The audit rejects EXECUTE on provisioning and SELECT on + commits. Tampered v2/v3 checksums and an unknown v4 are refused. +- Mutations, run on scratch copies with the source restored afterwards: removing + the predecessor-digest check, the lease check, the version/quantum continuity + check or the retained-build check in SQL, or the host manifest re-digest, each + failed at the expected assertion. +- Local fixture measurements: payloads of 22775 and 37367 bytes. + - Release publication took 3.6-4.8 ms per batch; analysis 5.5-6.7 ms; ASan + about 10.5 ms. + - Manifest publish p50 was about 0.74-0.91 ms. + These are local socket and local disk only. +- Not executed: Docker/Gitea CI, a remote object store or PVC, power-loss fsync + semantics, read-back verification fault injection, process kill, and TSan. diff --git a/docs/infrastructure/POSTGRESQL.md b/docs/infrastructure/POSTGRESQL.md index d19fc98..a699c99 100644 --- a/docs/infrastructure/POSTGRESQL.md +++ b/docs/infrastructure/POSTGRESQL.md @@ -68,7 +68,7 @@ every role transitively in it, and rolls back on any violation: `pg_write_all_data`); - any table privilege in `evolution`, including via PUBLIC; - CREATE on the schema, the database or `public`; -- EXECUTE outside the five fenced functions. +- EXECUTE outside the six fenced functions (schema v3). Attribute checks alone are not enough: a login with `pg_write_all_data` can update lease rows directly. Rerun the migrate Job after adding or changing runtime logins or grants; it is the audit. Grants made later without a rerun are not detected. Bootstrap revokes PUBLIC access to the schema, tables and @@ -77,20 +77,41 @@ never creates logins or passwords, and never grants superuser. ## Fenced region ownership (schema v2, ADR-0060) -The runtime role has schema USAGE and EXECUTE on five SECURITY DEFINER functions: -`acquire_region_lease`, `renew_region_lease`, `release_region_lease`, -`load_region_head` and `advance_region_head`. It cannot read or write tables, create -objects, call `check_region_lease` or provision regions. Each mutation locks the lease row +In schema v3 the runtime role has schema USAGE and EXECUTE on six SECURITY DEFINER +functions: `acquire_region_lease`, `renew_region_lease`, `release_region_lease`, +`load_region_head`, `publish_region_checkpoint` and `load_region_checkpoint`. It +cannot read or write tables, create objects, call internal check/parse functions or +provision regions. (Schema v2's `advance_region_head` is dropped in v3.) Each mutation locks the lease row and checks holder, epoch and expiry with `clock_timestamp()` after the lock wait. Clients never send times. Rejections: EVL01 busy, EVL02 fenced, EVL03 head mismatch, -EVL04 not provisioned, EVL05 epoch/sequence exhausted, 22023 invalid arguments. -`evo::postgres` maps them to `LeaseStoreError`; a timeout or broken connection is -`unknown`. +EVL04 not provisioned, EVL05 epoch/sequence exhausted, EVL06 unsupported +profile/version/build or a changed rules/quantum, EVL07 reused commit ID, and 22023 +malformed arguments or manifest. `evo::postgres` maps them to `LeaseStoreError`; a +timeout or broken connection is `unknown`. -Genesis is operator-only (owner login), never done by recovery or runtime: -`SELECT evolution.provision_region(world, region, frame, genesis_commit_uuid, -'\x<64 hex digest>');`. In schema v2 the head is an identity/digest pointer with no -payload binding. Do not provision real world state before M7.4 publication. +## Checkpoint publication (schema v3, ADR-0061) + +Each commit row stores the exact 280-byte manifest, and a constraint ties the +commit digest to `sha256(manifest)`. The head has a composite foreign key to its +commit, so even the owner cannot silently repoint or edit it. + +Payloads are immutable files under a trusted object root: +`/w/r/`, mode 0700 directories and 0600 files. +Mount a dedicated volume that only the region host's user can write. Nothing is +ever deleted; orphans from failed transactions are expected. + +Operator steps: +1. Record each promoted build (image digest, 32 bytes) before a host uses it: + `INSERT INTO evolution.retained_builds(build_identity) VALUES ('\x<64 hex>');` +2. Provision genesis only through `provision_environmental_region` on an owner + connection. It uploads and verifies the tick-0 payload, then calls the + owner-only `provision_region_checkpoint(manifest)`. + +There is no operator CLI for provisioning yet, and no real world has been +provisioned. Migrating v2→v3 fails closed if any v2 head exists, because v2 heads +have no payload. + +## Host lease discipline Hosts use `LeaseAuthority` with `LeasePolicy` defaults: 20 s lease, 5 s renewal interval, 2 s safety margin, 2 s renewal deadline and 5 s commit deadline. The diff --git a/include/evo/persistence/checkpoint_store.hpp b/include/evo/persistence/checkpoint_store.hpp new file mode 100644 index 0000000..d552592 --- /dev/null +++ b/include/evo/persistence/checkpoint_store.hpp @@ -0,0 +1,68 @@ +#pragma once +#include "evo/persistence/object_store.hpp" +#include "evo/persistence/region_checkpoint.hpp" +#include "evo/persistence/region_lease_store.hpp" +#include +#include +#include +#include + +// Linux publication and recovery of environmental-v1 checkpoints (ADR-0061). +// Order: validate candidate -> immutable upload -> verified read-back -> fenced +// manifest transaction. Nothing before the transaction has authority; a failure +// there leaves the previous head and at most an unreferenced orphan object. +namespace evo::persistence { +enum class PublicationError : std::uint8_t { + candidate, // State/manifest not a valid successor; nothing uploaded. + digest, // Digest provider failure; nothing uploaded. + upload, // Object write failed; no manifest was sent. + verify, // Read-back differs from the candidate; no manifest was sent. + rejected, // Database refused (see store); the upload is an orphan. + unknown, // Outcome unknown (see store); stay paused and reconcile the head. + receipt, // Committed receipt disagrees with the local manifest: fail closed. +}; +struct PublicationFailure { + PublicationError kind{}; + LeaseStoreFailure store{}; // Meaningful for rejected/unknown. + ObjectError object{}; // Meaningful for upload/verify. +}; +enum class RecoveryError : std::uint8_t { + store, // Database unavailable/failed (see store). + not_provisioned, // No genesis: recovery never creates one. + manifest, // Manifest bytes disagree with the committed digest/head. + unsupported, // Profile/versions/build not in this host's retained allowlist. + missing_payload, // Referenced object absent: quarantine, no older head. + corrupt_payload, // Length/digest mismatch: quarantine, no older head. + payload, // Verified bytes fail full state validation: quarantine. +}; +struct RecoveryFailure { + RecoveryError kind{}; + LeaseStoreFailure store{}; +}; +struct RecoveredCheckpoint { + CommittedCheckpoint committed; + CheckpointManifest manifest; + std::unique_ptr state; +}; + +// Owner/operator connection only: uploads a tick-0 state and records genesis. +[[nodiscard]] std::expected provision_environmental_region( + Postgres& owner, const FilesystemObjectStore& objects, RegionKey key, std::uint64_t frame, + const processes::EnvironmentalCommunity& opening, Uuid commit, const Sha256Digest& build, + std::size_t restore_budget, std::chrono::milliseconds timeout); +// Publishes `state` as the successor of `predecessor` under `lease`. The caller +// must hold the committed predecessor it simulated from and a lease that may +// begin a commit (LeaseAuthority::may_begin_commit). +[[nodiscard]] std::expected +publish_environmental_checkpoint(Postgres& db, const FilesystemObjectStore& objects, + const LeaseGrant& lease, const CommittedCheckpoint& predecessor, + const processes::EnvironmentalCommunity& state, Uuid commit, + const Sha256Digest& build, std::size_t restore_budget, + std::chrono::milliseconds timeout); +// Loads and fully verifies the committed head. Readiness additionally requires a +// fresh valid lease acquired before this call (M7.7); this does not grant one. +[[nodiscard]] std::expected +recover_environmental_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key, + std::span retained_builds, + std::size_t restore_budget, std::chrono::milliseconds timeout); +} // namespace evo::persistence diff --git a/include/evo/persistence/object_store.hpp b/include/evo/persistence/object_store.hpp new file mode 100644 index 0000000..ea0d321 --- /dev/null +++ b/include/evo/persistence/object_store.hpp @@ -0,0 +1,57 @@ +#pragma once +#include "evo/persistence/region_lease.hpp" +#include +#include +#include +#include +#include +#include +#include + +// Immutable content-addressed payload store on a trusted local/mounted volume +// (ADR-0061). Linux only. One namespace directory per world/region; the object +// key is the lowercase hex SHA-256 of its bytes. There is no delete or overwrite: +// unreferenced uploads are orphans and remain until a reachability-proven GC exists. +namespace evo::persistence { +enum class ObjectError : std::uint8_t { + invalid, // Bad root, namespace or object reference; nothing done. + missing, // No object with that key. + corrupt, // Length or digest mismatch, or not a regular file: quarantine. + bounds, // Larger than the configured maximum; rejected before allocation. + io, // Write/sync/link failure; the object is absent or unverified. +}; +struct VerifiedObject { + Sha256Digest sha256{}; + std::uint64_t bytes{}; + friend bool operator==(const VerifiedObject&, const VerifiedObject&) = default; +}; +class FilesystemObjectStore { + public: + // trusted_root must be an existing real directory (not a symlink). Namespace + // directories w/r are created 0700 and their parents synced. + [[nodiscard]] static std::expected, ObjectError> + open(const std::filesystem::path& trusted_root, RegionKey key, std::size_t max_object_bytes); + FilesystemObjectStore(const FilesystemObjectStore&) = delete; + FilesystemObjectStore& operator=(const FilesystemObjectStore&) = delete; + FilesystemObjectStore(FilesystemObjectStore&&) = delete; + FilesystemObjectStore& operator=(FilesystemObjectStore&&) = delete; + ~FilesystemObjectStore(); + // Writes a private temporary file, fsyncs it, links it to its key without + // replacing anything, then fsyncs the directory. Identical bytes already stored + // are verified and reused; a differing existing object is corrupt, never replaced. + [[nodiscard]] std::expected + put(std::span bytes) const; + // Reads only an exact-length regular file and verifies its SHA-256. + [[nodiscard]] std::expected, ObjectError> + get(const VerifiedObject& object) const; + [[nodiscard]] const std::filesystem::path& directory() const noexcept { + return directory_; + } + + private: + FilesystemObjectStore(std::filesystem::path directory, int descriptor, std::size_t maximum); + std::filesystem::path directory_; + int descriptor_; + std::size_t maximum_; +}; +} // namespace evo::persistence diff --git a/include/evo/persistence/region_checkpoint.hpp b/include/evo/persistence/region_checkpoint.hpp new file mode 100644 index 0000000..c02c8c7 --- /dev/null +++ b/include/evo/persistence/region_checkpoint.hpp @@ -0,0 +1,89 @@ +#pragma once +#include "evo/persistence/region_lease.hpp" +#include "evo/processes/environmental_community.hpp" +#include +#include +#include +#include +#include +#include + +// Region checkpoint manifest v1 and environmental-v1 payload validation (ADR-0061, +// schemas/region-commit.md). Portable and storage-free: digests are computed and +// objects are stored by the Linux adapters; this only encodes and validates. +namespace evo::persistence { +// Encoded as u32 on the wire; values above 255 decode as unknown (0), never truncated. +enum class CheckpointProfile : std::uint8_t { unknown = 0, environmental_v1 = 1 }; +// Declared durability, verified at deployment. Development: one volume, no host-loss claim. +enum class DurabilityPolicy : std::uint8_t { unknown = 0, single_volume_development = 1 }; + +// Exact versions of every nested format/rule the payload depends on. The interval +// adapter carries no payload state but its version is still pinned. +struct VersionBundle { + std::uint32_t rules{2}, envelope{2}, resources{1}, fields{1}, terrain{1}, coordinate{1}, + generator{1}, material{1}, interval_adapter{1}; + friend bool operator==(const VersionBundle&, const VersionBundle&) = default; +}; +inline constexpr VersionBundle environmental_v1_versions{}; + +struct CheckpointManifest { + CheckpointProfile profile{CheckpointProfile::environmental_v1}; + RegionKey key{}; + std::uint64_t frame{}; + Uuid commit{}; + std::uint64_t sequence{}; + Uuid predecessor_commit{}; // Zero only at genesis. + Sha256Digest predecessor_digest{}; // SHA-256 of the predecessor manifest bytes. + std::uint64_t begin_tick{}, end_tick{}; + Uuid holder{}; // Zero only at genesis (provisioning, not a lease). + std::uint64_t epoch{}; + std::uint64_t tick_microseconds{}; + VersionBundle versions{}; + Sha256Digest build{}; // Retained immutable build artifact identity. + std::uint32_t rng_streams{}; // environmental-v1 rules use no randomness: 0. + std::uint32_t history_profile{}; // No lineage/genome state in environmental-v1: 0. + DurabilityPolicy durability{DurabilityPolicy::single_volume_development}; + std::uint64_t payload_bytes{}; + Sha256Digest payload_sha256{}; + friend bool operator==(const CheckpointManifest&, const CheckpointManifest&) = default; +}; + +inline constexpr std::size_t checkpoint_manifest_bytes = 280; +inline constexpr std::size_t max_environmental_payload_bytes = std::size_t{1024} * 1024; +inline constexpr std::uint64_t max_checkpoint_ticks = 64; + +enum class CheckpointError : std::uint8_t { + format, // Malformed or internally inconsistent manifest. + unsupported, // Unknown profile, version, RNG/history or durability declaration. + chain, // Not a valid successor of the committed predecessor. + payload, // Payload bytes fail full envelope validation or identity/tick checks. +}; + +// Structural validation of every field; versions/profile are checked separately +// so recovery can distinguish corruption from an unsupported (retained) format. +[[nodiscard]] std::expected, CheckpointError> +encode_manifest(const CheckpointManifest& manifest); +[[nodiscard]] std::expected +decode_manifest(std::span bytes); +// Profile, exact versions, zero RNG/history declarations and durability policy. +[[nodiscard]] bool supported(const CheckpointManifest& manifest) noexcept; + +// Genesis for operator provisioning only; recovery never creates one. +[[nodiscard]] std::expected +genesis_manifest(RegionKey key, std::uint64_t frame, Uuid commit, std::uint64_t tick_microseconds, + const Sha256Digest& build, std::uint64_t payload_bytes, + const Sha256Digest& payload_sha256); +// Next link from the committed predecessor and its manifest digest under a lease. +[[nodiscard]] std::expected +successor_manifest(const CheckpointManifest& predecessor, const Sha256Digest& predecessor_digest, + Uuid commit, const LeaseGrant& lease, std::uint64_t end_tick, + const Sha256Digest& build, std::uint64_t payload_bytes, + const Sha256Digest& payload_sha256); + +// Fully restores payload bytes (envelope checksum, bounds and replay audit), then +// requires manifest identity, end tick, tick quantum, envelope format 2 and a +// byte-identical canonical re-encoding. The caller verifies length and SHA-256. +[[nodiscard]] std::expected, CheckpointError> +restore_environmental_payload(std::span payload, + const CheckpointManifest& manifest, std::size_t budget); +} // namespace evo::persistence diff --git a/include/evo/persistence/region_lease.hpp b/include/evo/persistence/region_lease.hpp index 209ab0c..3efa018 100644 --- a/include/evo/persistence/region_lease.hpp +++ b/include/evo/persistence/region_lease.hpp @@ -13,6 +13,7 @@ using Sha256Digest = std::array; struct RegionKey { std::uint64_t world{}; std::uint64_t region{}; + friend bool operator==(const RegionKey&, const RegionKey&) = default; }; struct RegionHead { std::uint64_t frame{}; diff --git a/include/evo/persistence/region_lease_store.hpp b/include/evo/persistence/region_lease_store.hpp index 5be84dc..65e7057 100644 --- a/include/evo/persistence/region_lease_store.hpp +++ b/include/evo/persistence/region_lease_store.hpp @@ -4,6 +4,8 @@ #include #include #include +#include +#include // 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 @@ -15,6 +17,8 @@ enum class LeaseStoreError : std::uint8_t { 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. + unsupported, // Profile/version/build not admitted, or rules/quantum changed. + commit_conflict, // Commit ID already used by another manifest (resolve at M7.5). invalid, // Rejected arguments; nothing changed. store, // Other SQL/configuration failure; nothing committed. unknown, // May have executed; reconnect and reconcile before reuse. @@ -23,10 +27,10 @@ struct LeaseStoreFailure { LeaseStoreError kind{}; PgFailure cause{}; }; -struct HeadAdvance { - Uuid commit{}; - Sha256Digest digest{}; - std::uint64_t end_tick{}; +// Committed head and the exact manifest bytes its digest covers. +struct CommittedCheckpoint { + RegionHead head{}; + std::vector manifest; }; [[nodiscard]] std::expected @@ -41,10 +45,13 @@ release_region_lease(Postgres& db, RegionKey key, const LeaseGrant& lease, std::chrono::milliseconds timeout); [[nodiscard]] std::expected 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 +load_region_checkpoint(Postgres& db, RegionKey key, std::chrono::milliseconds timeout); +// Canonical manifest v1 bytes; the database parses identity, lease and chain from +// them, locks the lease then the head and requires the exact committed predecessor. +// The payload must already be verified in the object store. head_mismatch after +// unknown: load the head and compare its commit ID (full resolution is M7.5). [[nodiscard]] std::expected -advance_region_head(Postgres& db, RegionKey key, const LeaseGrant& lease, - const RegionHead& expected, const HeadAdvance& next, - std::chrono::milliseconds timeout); +publish_region_checkpoint(Postgres& db, std::span manifest, + std::chrono::milliseconds timeout); } // namespace evo::persistence diff --git a/include/evo/persistence/sha256.hpp b/include/evo/persistence/sha256.hpp new file mode 100644 index 0000000..deb58a8 --- /dev/null +++ b/include/evo/persistence/sha256.hpp @@ -0,0 +1,13 @@ +#pragma once +#include "evo/persistence/region_lease.hpp" +#include +#include + +// SHA-256 from the system OpenSSL libcrypto EVP interface (ADR-0061). Linux +// persistence adapters only; no project cryptography. Content identity, not +// authentication. +namespace evo::persistence { +enum class DigestError : std::uint8_t { provider }; +[[nodiscard]] std::expected +sha256(std::span bytes) noexcept; +} // namespace evo::persistence diff --git a/migrations/0003_region_checkpoints.sql b/migrations/0003_region_checkpoints.sql new file mode 100644 index 0000000..fe30c4e --- /dev/null +++ b/migrations/0003_region_checkpoints.sql @@ -0,0 +1,236 @@ +-- M7.4 committed checkpoint publication (ADR-0061). The database parses the +-- canonical manifest v1 bytes itself, so no separately supplied field can disagree +-- with the digested record. Payload bytes live in the object store; the database +-- records their length and SHA-256 and never parses them. +DO $$ +BEGIN + -- Schema v2 heads carry no payload binding and cannot be migrated into a chain. + IF EXISTS (SELECT 1 FROM evolution.region_heads) THEN + RAISE EXCEPTION 'v2 region heads have no checkpoint payload; re-provision under v3'; + END IF; +END $$; +DROP FUNCTION evolution.advance_region_head(evolution.u64, evolution.u64, uuid, evolution.u64, + evolution.u64, uuid, bytea, uuid, bytea, evolution.u64); +DROP FUNCTION evolution.provision_region(evolution.u64, evolution.u64, evolution.u64, uuid, bytea); + +-- Immutable build artifacts retained for recovery; owner-managed on promotion. +CREATE TABLE evolution.retained_builds ( + build_identity bytea PRIMARY KEY CHECK (octet_length(build_identity) = 32), + retained_at timestamptz NOT NULL DEFAULT clock_timestamp() +); +CREATE TABLE evolution.region_commits ( + world_id evolution.u64 NOT NULL, + region_id evolution.u64 NOT NULL, + commit_sequence evolution.u64 NOT NULL, + commit_id uuid NOT NULL UNIQUE, + commit_digest bytea NOT NULL CHECK (octet_length(commit_digest) = 32), + manifest bytea NOT NULL CHECK (octet_length(manifest) = 280), + begin_tick evolution.u64 NOT NULL, + end_tick evolution.u64 NOT NULL, + published_epoch evolution.u64 NOT NULL, + tick_microseconds evolution.u64 NOT NULL, + versions bytea NOT NULL CHECK (octet_length(versions) = 36), + build_identity bytea NOT NULL REFERENCES evolution.retained_builds, + payload_bytes evolution.u64 NOT NULL, + payload_sha256 bytea NOT NULL CHECK (octet_length(payload_sha256) = 32), + committed_at timestamptz NOT NULL DEFAULT clock_timestamp(), + PRIMARY KEY (world_id, region_id, commit_sequence), + UNIQUE (world_id, region_id, commit_sequence, commit_id, commit_digest), + FOREIGN KEY (world_id, region_id) REFERENCES evolution.region_leases, + CONSTRAINT region_commits_manifest_digest CHECK (commit_digest = sha256(manifest)) +); +-- The head can only name an existing commit with the same identity and digest. +ALTER TABLE evolution.region_heads + ADD FOREIGN KEY (world_id, region_id, commit_sequence, commit_id, digest) + REFERENCES evolution.region_commits (world_id, region_id, commit_sequence, commit_id, + commit_digest); +REVOKE ALL ON evolution.retained_builds, evolution.region_commits FROM PUBLIC; + +CREATE TYPE evolution.checkpoint_manifest AS ( + world_id evolution.u64, region_id evolution.u64, frame_id evolution.u64, commit_id uuid, + commit_sequence evolution.u64, predecessor_commit uuid, predecessor_digest bytea, + begin_tick evolution.u64, end_tick evolution.u64, holder uuid, epoch evolution.u64, + tick_microseconds evolution.u64, versions bytea, build_identity bytea, + payload_bytes evolution.u64, payload_sha256 bytea +); + +CREATE FUNCTION evolution.manifest_uint(m bytea, off integer, width integer) +RETURNS numeric LANGUAGE plpgsql IMMUTABLE STRICT SET search_path = pg_catalog, pg_temp AS $$ +DECLARE + v numeric := 0; +BEGIN + FOR i IN REVERSE width - 1 .. 0 LOOP + v := v * 256 + get_byte(m, off + i); + END LOOP; + RETURN v; +END $$; + +-- Mirrors decode_manifest + supported() in src/persistence/region_checkpoint.cpp. +-- 22023: malformed; EVL06: parsable but unsupported by this schema. +CREATE FUNCTION evolution.parse_checkpoint_manifest(m bytea) +RETURNS evolution.checkpoint_manifest LANGUAGE plpgsql IMMUTABLE +SET search_path = pg_catalog, pg_temp AS $$ +DECLARE + r evolution.checkpoint_manifest; + zero16 constant bytea := '\x00000000000000000000000000000000'; + zero32 constant bytea := decode(repeat('00', 32), 'hex'); +BEGIN + IF m IS NULL OR octet_length(m) <> 280 OR substring(m FROM 1 FOR 8) <> '\x4145564f52434d31' THEN + RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023'; + END IF; + IF evolution.manifest_uint(m, 8, 4) <> 1 OR evolution.manifest_uint(m, 12, 4) <> 1 + OR substring(m FROM 161 FOR 36) <> '\x020000000200000001000000010000000100000001000000010000000100000001000000' + OR evolution.manifest_uint(m, 228, 4) <> 0 OR evolution.manifest_uint(m, 232, 4) <> 0 + OR evolution.manifest_uint(m, 236, 4) <> 1 THEN + RAISE EXCEPTION 'unsupported checkpoint manifest' USING ERRCODE = 'EVL06'; + END IF; + r.world_id := evolution.manifest_uint(m, 16, 8); + r.region_id := evolution.manifest_uint(m, 24, 8); + r.frame_id := evolution.manifest_uint(m, 32, 8); + r.commit_id := encode(substring(m FROM 41 FOR 16), 'hex')::uuid; + r.commit_sequence := evolution.manifest_uint(m, 56, 8); + r.predecessor_commit := encode(substring(m FROM 65 FOR 16), 'hex')::uuid; + r.predecessor_digest := substring(m FROM 81 FOR 32); + r.begin_tick := evolution.manifest_uint(m, 112, 8); + r.end_tick := evolution.manifest_uint(m, 120, 8); + r.holder := encode(substring(m FROM 129 FOR 16), 'hex')::uuid; + r.epoch := evolution.manifest_uint(m, 144, 8); + r.tick_microseconds := evolution.manifest_uint(m, 152, 8); + r.versions := substring(m FROM 161 FOR 36); + r.build_identity := substring(m FROM 197 FOR 32); + r.payload_bytes := evolution.manifest_uint(m, 240, 8); + r.payload_sha256 := substring(m FROM 249 FOR 32); + IF r.world_id = 0 OR r.region_id = 0 OR r.frame_id = 0 + OR substring(m FROM 41 FOR 16) = zero16 OR r.tick_microseconds = 0 + OR r.build_identity = zero32 OR r.payload_bytes NOT BETWEEN 1 AND 1048576 + OR r.payload_sha256 = zero32 THEN + RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023'; + END IF; + IF r.commit_sequence = 0 THEN + IF substring(m FROM 65 FOR 16) <> zero16 OR r.predecessor_digest <> zero32 + OR r.begin_tick <> 0 OR r.end_tick <> 0 OR substring(m FROM 129 FOR 16) <> zero16 + OR r.epoch <> 0 THEN + RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023'; + END IF; + r.predecessor_commit := NULL; + r.holder := NULL; + ELSIF substring(m FROM 65 FOR 16) = zero16 OR r.predecessor_commit = r.commit_id + OR r.predecessor_digest = zero32 OR substring(m FROM 129 FOR 16) = zero16 + OR r.epoch = 0 OR r.end_tick <= r.begin_tick OR r.end_tick - r.begin_tick > 64 THEN + RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023'; + END IF; + RETURN r; +END $$; + +-- Owner-only: genesis is an explicit authorized opening payload, never recovery. +CREATE FUNCTION evolution.provision_region_checkpoint(p_manifest bytea) +RETURNS void LANGUAGE plpgsql SECURITY INVOKER SET search_path = pg_catalog, pg_temp AS $$ +DECLARE + g evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest); + d bytea := sha256(p_manifest); +BEGIN + IF g.commit_sequence <> 0 THEN + RAISE EXCEPTION 'genesis manifest required' USING ERRCODE = '22023'; + END IF; + INSERT INTO evolution.region_leases(world_id, region_id, frame_id) + VALUES (g.world_id, g.region_id, g.frame_id); + INSERT INTO evolution.region_commits(world_id, region_id, commit_sequence, commit_id, + commit_digest, manifest, begin_tick, end_tick, published_epoch, tick_microseconds, + versions, build_identity, payload_bytes, payload_sha256) + VALUES (g.world_id, g.region_id, 0, g.commit_id, d, p_manifest, 0, 0, 0, + g.tick_microseconds, g.versions, g.build_identity, g.payload_bytes, + g.payload_sha256); + INSERT INTO evolution.region_heads(world_id, region_id, commit_sequence, commit_id, digest, + end_tick, published_epoch) + VALUES (g.world_id, g.region_id, 0, g.commit_id, d, 0, 0); +END $$; + +-- Fenced publication: lease row lock and database-time check, then the head lock; +-- the manifest must be the exact successor of the committed head. One statement: +-- a rejection inserts nothing. A verified orphan payload stays unreferenced. +CREATE FUNCTION evolution.publish_region_checkpoint(p_manifest bytea) +RETURNS TABLE (region_frame evolution.u64, head_sequence evolution.u64, head_commit uuid, + head_digest text, head_tick evolution.u64) +LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ +DECLARE + c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest); + h evolution.region_heads%ROWTYPE; + p evolution.region_commits%ROWTYPE; + frame evolution.u64; + d bytea := sha256(p_manifest); +BEGIN + IF c.commit_sequence = 0 THEN + RAISE EXCEPTION 'genesis is provisioned, not published' USING ERRCODE = '22023'; + END IF; + PERFORM evolution.check_region_lease(c.world_id, c.region_id, c.holder, c.epoch); + SELECT * INTO h FROM evolution.region_heads r + WHERE r.world_id = c.world_id AND r.region_id = c.region_id FOR UPDATE; + IF NOT FOUND THEN + RAISE EXCEPTION 'region not provisioned' USING ERRCODE = 'EVL04'; + END IF; + IF h.commit_sequence = 18446744073709551615 THEN + RAISE EXCEPTION 'commit sequences exhausted' USING ERRCODE = 'EVL05'; + END IF; + IF c.commit_sequence <> h.commit_sequence + 1 OR c.predecessor_commit <> h.commit_id + OR c.predecessor_digest <> h.digest OR c.begin_tick <> h.end_tick THEN + RAISE EXCEPTION 'region head moved' USING ERRCODE = 'EVL03'; + END IF; + SELECT l.frame_id INTO frame FROM evolution.region_leases l + WHERE l.world_id = c.world_id AND l.region_id = c.region_id; + IF c.frame_id <> frame THEN + RAISE EXCEPTION 'foreign frame' USING ERRCODE = '22023'; + END IF; + SELECT * INTO p FROM evolution.region_commits r + WHERE r.world_id = c.world_id AND r.region_id = c.region_id + AND r.commit_sequence = h.commit_sequence; + -- Rules, formats and quantum are fixed for a region; changing them is a migration. + IF c.versions <> p.versions OR c.tick_microseconds <> p.tick_microseconds + OR NOT EXISTS (SELECT 1 FROM evolution.retained_builds b + WHERE b.build_identity = c.build_identity) THEN + RAISE EXCEPTION 'unsupported checkpoint' USING ERRCODE = 'EVL06'; + END IF; + IF EXISTS (SELECT 1 FROM evolution.region_commits r WHERE r.commit_id = c.commit_id) THEN + RAISE EXCEPTION 'commit identity reused' USING ERRCODE = 'EVL07'; + END IF; + INSERT INTO evolution.region_commits(world_id, region_id, commit_sequence, commit_id, + commit_digest, manifest, begin_tick, end_tick, published_epoch, tick_microseconds, + versions, build_identity, payload_bytes, payload_sha256) + VALUES (c.world_id, c.region_id, c.commit_sequence, c.commit_id, d, p_manifest, + c.begin_tick, c.end_tick, c.epoch, c.tick_microseconds, c.versions, + c.build_identity, c.payload_bytes, c.payload_sha256); + UPDATE evolution.region_heads r + SET commit_sequence = c.commit_sequence, commit_id = c.commit_id, digest = d, + end_tick = c.end_tick, published_epoch = c.epoch + WHERE r.world_id = c.world_id AND r.region_id = c.region_id; + RETURN QUERY SELECT frame, c.commit_sequence, c.commit_id, encode(d, 'hex'), c.end_tick; +END $$; + +-- Committed head plus its exact manifest bytes, for recovery verification. +CREATE FUNCTION evolution.load_region_checkpoint(p_world evolution.u64, p_region evolution.u64) +RETURNS TABLE (region_frame evolution.u64, head_sequence evolution.u64, head_commit uuid, + head_digest text, head_tick evolution.u64, head_manifest text) +LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ +BEGIN + RETURN QUERY SELECT l.frame_id, h.commit_sequence, h.commit_id, encode(h.digest, 'hex'), + h.end_tick, encode(c.manifest, 'hex') + FROM evolution.region_heads h + JOIN evolution.region_leases l USING (world_id, region_id) + JOIN evolution.region_commits c USING (world_id, region_id, commit_sequence) + WHERE h.world_id = p_world AND h.region_id = p_region; + IF NOT FOUND THEN + RAISE EXCEPTION 'region not provisioned' USING ERRCODE = 'EVL04'; + END IF; +END $$; + +REVOKE ALL ON FUNCTION + evolution.manifest_uint(bytea, integer, integer), + evolution.parse_checkpoint_manifest(bytea), + evolution.provision_region_checkpoint(bytea), + evolution.publish_region_checkpoint(bytea), + evolution.load_region_checkpoint(evolution.u64, evolution.u64) + FROM PUBLIC; +GRANT EXECUTE ON FUNCTION + evolution.publish_region_checkpoint(bytea), + evolution.load_region_checkpoint(evolution.u64, evolution.u64) + TO :"runtime_role"; +INSERT INTO evolution.schema_migrations(version, sha256) VALUES (3, :'migration_sha_3'); diff --git a/migrations/apply.sql b/migrations/apply.sql index dc33912..b5bb35d 100644 --- a/migrations/apply.sql +++ b/migrations/apply.sql @@ -17,10 +17,15 @@ SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname='evolution') SELECT coalesce(string_agg(version || ':' || sha256, ',' ORDER BY version), '') AS history FROM evolution.schema_migrations \gset SELECT :'history' = '1:' || :'migration_sha' AS at_v1, - :'history' = '1:' || :'migration_sha' || ',2:' || :'migration_sha_2' AS at_v2 \gset - \if :at_v2 + :'history' = '1:' || :'migration_sha' || ',2:' || :'migration_sha_2' AS at_v2, + :'history' = '1:' || :'migration_sha' || ',2:' || :'migration_sha_2' + || ',3:' || :'migration_sha_3' AS at_v3 \gset + \if :at_v3 + \elif :at_v2 + \ir 0003_region_checkpoints.sql \elif :at_v1 \ir 0002_region_fencing.sql + \ir 0003_region_checkpoints.sql \else \echo 'Unknown or changed migration history' DO $$ BEGIN RAISE EXCEPTION 'unknown or changed migration history'; END $$; @@ -28,6 +33,7 @@ SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname='evolution') \else \ir 0001_region_bootstrap.sql \ir 0002_region_fencing.sql + \ir 0003_region_checkpoints.sql \endif -- Effective-privilege audit on every run, including no-ops (ADR-0060). Attributes -- alone are insufficient: predefined roles such as pg_write_all_data, PUBLIC @@ -52,7 +58,8 @@ BEGIN ('evolution.renew_region_lease(evolution.u64,evolution.u64,uuid,evolution.u64,integer)'::regprocedure::oid), ('evolution.release_region_lease(evolution.u64,evolution.u64,uuid,evolution.u64)'::regprocedure::oid), ('evolution.load_region_head(evolution.u64,evolution.u64)'::regprocedure::oid), - ('evolution.advance_region_head(evolution.u64,evolution.u64,uuid,evolution.u64,evolution.u64,uuid,bytea,uuid,bytea,evolution.u64)'::regprocedure::oid) + ('evolution.publish_region_checkpoint(bytea)'::regprocedure::oid), + ('evolution.load_region_checkpoint(evolution.u64,evolution.u64)'::regprocedure::oid) ), violations(role_oid, reason) AS ( SELECT r.oid, 'privileged attribute or owner identity' FROM pg_catalog.pg_roles r JOIN closure c ON c.oid = r.oid @@ -76,7 +83,7 @@ BEGIN OR EXISTS (SELECT 1 FROM pg_catalog.pg_namespace n WHERE n.nspname = 'public' AND pg_catalog.has_schema_privilege(c.oid, n.oid, 'CREATE')) UNION ALL - -- Only the five guarded functions are executable; provisioning/internal are not. + -- Only the six guarded functions are executable; provisioning/internal are not. SELECT c.oid, 'EXECUTE outside the fenced function set' FROM closure c CROSS JOIN pg_catalog.pg_proc p WHERE p.pronamespace = 'evolution'::regnamespace diff --git a/schemas/region-commit.md b/schemas/region-commit.md index 387515b..be85575 100644 --- a/schemas/region-commit.md +++ b/schemas/region-commit.md @@ -1,4 +1,41 @@ -# Region commit manifest contract v1 (M7.1 design) +# Region commit manifest contract v1 (M7.1 design, M7.4a encoding) + +## Canonical manifest encoding v1 (ADR-0061) + +The encoder, decoder and `supported()` check live in +`src/persistence/region_checkpoint.cpp`; `evolution.parse_checkpoint_manifest` +mirrors them in SQL. The record is exactly 280 bytes, all integers little-endian, +with no padding or trailing checksum. The commit digest is SHA-256 of the whole +record, and each commit row stores it. + +| Offset | Size | Field | +|---|---|---| +| 0 | 8 | magic `AEVORCM1` | +| 8 | 4 | manifest_version = 1 (other values are unsupported) | +| 12 | 4 | profile: 1 = environmental-v1 | +| 16 | 24 | world, region, frame (nonzero u64 each) | +| 40 | 16 | commit_id (nonzero; globally unique in the database) | +| 56 | 8 | commit_sequence | +| 64 | 16 | predecessor_commit_id (zero only at genesis; never equal to commit_id) | +| 80 | 32 | predecessor manifest SHA-256 (zero only at genesis) | +| 112 | 16 | begin_tick, end_tick (genesis 0/0; otherwise 1..64 tick delta) | +| 128 | 16 | lease holder (zero only at genesis) | +| 144 | 8 | lease epoch (0 only at genesis) | +| 152 | 8 | tick_microseconds (nonzero; fixed for the region) | +| 160 | 36 | nine u32 versions: rules 2, envelope 2, resources/fields/terrain/coordinate/generator/material/interval-adapter 1 | +| 196 | 32 | retained build identity (nonzero; `retained_builds` row required) | +| 228 | 4 | rng_streams = 0 (these rules use no randomness) | +| 232 | 4 | history_profile = 0 (no genome/lineage state) | +| 236 | 4 | durability_policy = 1 (single-volume development) | +| 240 | 8 | payload_bytes (1..1 MiB) | +| 248 | 32 | payload SHA-256 (nonzero) | + +A structurally invalid record is malformed (SQL 22023). A record that parses but +has an unsupported version, profile, RNG, history or durability declaration is +unsupported (EVL06). Values above 255 are never truncated onto a supported enum. +The payload is the exact environmental envelope format 2; its object key is the +hex payload SHA-256 in the region's namespace. Decisions, trace and outbox are not +encoded here: M7.5 adds them under a new manifest version. Authority: ADR-0058 and docs/architecture/REGION_DURABILITY.md. Logical schema, not an implemented wire codec, SQL migration or permission to serialize structs. diff --git a/src/persistence/checkpoint_store.cpp b/src/persistence/checkpoint_store.cpp new file mode 100644 index 0000000..adee2ad --- /dev/null +++ b/src/persistence/checkpoint_store.cpp @@ -0,0 +1,154 @@ +#include "evo/persistence/checkpoint_store.hpp" +#include "evo/persistence/sha256.hpp" +#include +#include +#include + +namespace evo::persistence { +namespace { +using std::chrono::milliseconds; +PublicationFailure fail(PublicationError kind) { + return {kind, {}, {}}; +} +// Encodes the candidate, validates the exact payload bytes as recovery would, +// uploads and reads back. Returns the manifest bytes ready for the database. +std::expected, PublicationFailure> +stage(const FilesystemObjectStore& objects, const std::vector& payload, + const CheckpointManifest& manifest, std::size_t budget) { + auto bytes = encode_manifest(manifest); + if (!bytes || !restore_environmental_payload(payload, manifest, budget)) + return std::unexpected{fail(PublicationError::candidate)}; + auto stored = objects.put(payload); + if (!stored) + return std::unexpected{PublicationFailure{PublicationError::upload, {}, stored.error()}}; + auto back = objects.get(*stored); + if (!back || *stored != VerifiedObject{manifest.payload_sha256, manifest.payload_bytes} || + !std::ranges::equal(*back, payload)) + return std::unexpected{PublicationFailure{ + PublicationError::verify, {}, back ? ObjectError::corrupt : back.error()}}; + return std::move(*bytes); +} +std::expected +confirm(const std::expected& published, + std::vector manifest_bytes, const CheckpointManifest& manifest) { + if (!published) { + const auto kind = published.error().kind == LeaseStoreError::unknown + ? PublicationError::unknown + : PublicationError::rejected; + return std::unexpected{PublicationFailure{kind, published.error(), {}}}; + } + // The database digested the bytes independently; the receipt must agree. + const auto digest = sha256(manifest_bytes); + if (!digest || published->digest != *digest || published->sequence != manifest.sequence || + published->commit != manifest.commit || published->end_tick != manifest.end_tick || + published->frame != manifest.frame) + return std::unexpected{fail(PublicationError::receipt)}; + return CommittedCheckpoint{*published, std::move(manifest_bytes)}; +} +} // namespace + +std::expected provision_environmental_region( + Postgres& owner, const FilesystemObjectStore& objects, RegionKey key, std::uint64_t frame, + const processes::EnvironmentalCommunity& opening, Uuid commit, const Sha256Digest& build, + std::size_t restore_budget, milliseconds timeout) { + auto payload = opening.snapshot(); + if (!payload || opening.progress().tick != 0) + return std::unexpected{fail(PublicationError::candidate)}; + const auto digest = sha256(*payload); + if (!digest) + return std::unexpected{fail(PublicationError::digest)}; + auto manifest = genesis_manifest(key, frame, commit, opening.tick_microseconds(), build, + payload->size(), *digest); + if (!manifest) + return std::unexpected{fail(PublicationError::candidate)}; + auto bytes = stage(objects, *payload, *manifest, restore_budget); + if (!bytes) + return std::unexpected{bytes.error()}; + constexpr char digits[] = "0123456789abcdef"; + std::string parameter = "\\x"; + for (const auto b : *bytes) { + parameter.push_back(digits[b >> 4U]); + parameter.push_back(digits[b & 0x0FU]); + } + const std::array p{parameter}; + auto done = owner.query("SELECT evolution.provision_region_checkpoint($1::bytea)", p, timeout); + if (!done) { + const auto kind = done.error().kind == PgError::unknown ? PublicationError::unknown + : PublicationError::rejected; + return std::unexpected{ + PublicationFailure{kind, + {done.error().kind == PgError::unknown ? LeaseStoreError::unknown + : LeaseStoreError::store, + done.error()}, + {}}}; + } + auto committed = load_region_checkpoint(owner, key, timeout); + if (!committed) + return std::unexpected{ + PublicationFailure{PublicationError::unknown, committed.error(), {}}}; + return confirm(committed->head, std::move(*bytes), *manifest); +} + +std::expected publish_environmental_checkpoint( + Postgres& db, const FilesystemObjectStore& objects, const LeaseGrant& lease, + const CommittedCheckpoint& predecessor, const processes::EnvironmentalCommunity& state, + Uuid commit, const Sha256Digest& build, std::size_t restore_budget, milliseconds timeout) { + const auto previous = decode_manifest(predecessor.manifest); + auto payload = state.snapshot(); + if (!previous || !payload) + return std::unexpected{fail(PublicationError::candidate)}; + const auto digest = sha256(*payload); + if (!digest) + return std::unexpected{fail(PublicationError::digest)}; + auto manifest = successor_manifest(*previous, predecessor.head.digest, commit, lease, + state.progress().tick, build, payload->size(), *digest); + if (!manifest) + return std::unexpected{fail(PublicationError::candidate)}; + auto bytes = stage(objects, *payload, *manifest, restore_budget); + if (!bytes) + return std::unexpected{bytes.error()}; + auto published = publish_region_checkpoint(db, *bytes, timeout); + return confirm(published, std::move(*bytes), *manifest); +} + +std::expected +recover_environmental_checkpoint(Postgres& db, const FilesystemObjectStore& objects, RegionKey key, + std::span retained_builds, + std::size_t restore_budget, milliseconds timeout) { + auto committed = load_region_checkpoint(db, key, timeout); + if (!committed) + return std::unexpected{ + RecoveryFailure{committed.error().kind == LeaseStoreError::not_provisioned + ? RecoveryError::not_provisioned + : RecoveryError::store, + committed.error()}}; + const auto fail_with = [](RecoveryError kind) { + return std::unexpected{RecoveryFailure{kind, {}}}; + }; + const auto digest = sha256(committed->manifest); + auto manifest = decode_manifest(committed->manifest); + const auto& head = committed->head; + if (!digest || *digest != head.digest) + return fail_with(RecoveryError::manifest); + if (!manifest) + return fail_with(manifest.error() == CheckpointError::unsupported + ? RecoveryError::unsupported + : RecoveryError::manifest); + if (manifest->key != key || manifest->frame != head.frame || + manifest->sequence != head.sequence || manifest->commit != head.commit || + manifest->end_tick != head.end_tick) + return fail_with(RecoveryError::manifest); + if (!supported(*manifest) || + std::ranges::find(retained_builds, manifest->build) == retained_builds.end()) + return fail_with(RecoveryError::unsupported); + auto payload = objects.get({manifest->payload_sha256, manifest->payload_bytes}); + if (!payload) + return fail_with(payload.error() == ObjectError::missing ? RecoveryError::missing_payload + : payload.error() == ObjectError::corrupt ? RecoveryError::corrupt_payload + : RecoveryError::store); + auto state = restore_environmental_payload(*payload, *manifest, restore_budget); + if (!state) + return fail_with(RecoveryError::payload); + return RecoveredCheckpoint{std::move(*committed), *manifest, std::move(*state)}; +} +} // namespace evo::persistence diff --git a/src/persistence/object_store.cpp b/src/persistence/object_store.cpp new file mode 100644 index 0000000..c645dcb --- /dev/null +++ b/src/persistence/object_store.cpp @@ -0,0 +1,200 @@ +#include "evo/persistence/object_store.hpp" +#include "evo/persistence/sha256.hpp" +#include +#include +#include +#include +#include +#include + +namespace evo::persistence { +namespace { +constexpr std::size_t maximum_object_limit = std::size_t{64} * 1024 * 1024; +std::atomic temporary_counter{0}; + +class Descriptor { + public: + explicit Descriptor(int fd) noexcept : fd_(fd) {} + Descriptor(const Descriptor&) = delete; + Descriptor& operator=(const Descriptor&) = delete; + ~Descriptor() { + if (fd_ >= 0) + static_cast(::close(fd_)); + } + [[nodiscard]] int get() const noexcept { + return fd_; + } + [[nodiscard]] int release() noexcept { + const int fd = fd_; + fd_ = -1; + return fd; + } + // Explicit close so a deferred write error is observed. + [[nodiscard]] bool close() noexcept { + const int fd = release(); + return fd < 0 || ::close(fd) == 0; + } + + private: + int fd_; +}; +std::string key_name(const Sha256Digest& d) { + constexpr char digits[] = "0123456789abcdef"; + std::string out; + out.reserve(64); + for (const auto b : d) { + out.push_back(digits[b >> 4U]); + out.push_back(digits[b & 0x0FU]); + } + return out; +} +// Opens or creates a private subdirectory without following symlinks. +int subdirectory(int parent, const std::string& name) { + bool created = false; + if (::mkdirat(parent, name.c_str(), 0700) == 0) + created = true; + else if (errno != EEXIST) + return -1; + const int fd = ::openat(parent, name.c_str(), O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC); + if (fd >= 0 && created && ::fsync(parent) != 0) { + static_cast(::close(fd)); + return -1; + } + return fd; +} +bool write_all(int fd, std::span bytes) { + while (!bytes.empty()) { + const auto n = ::write(fd, bytes.data(), bytes.size()); + if (n < 0 && errno == EINTR) + continue; + if (n <= 0) + return false; + bytes = bytes.subspan(static_cast(n)); + } + return true; +} +// Exact-length regular file whose content has the expected digest. +std::expected, ObjectError> read_verified(int directory, + const VerifiedObject& object) { + const auto name = key_name(object.sha256); + const Descriptor fd{::openat(directory, name.c_str(), O_RDONLY | O_NOFOLLOW | O_CLOEXEC)}; + if (fd.get() < 0) + return std::unexpected{errno == ENOENT ? ObjectError::missing + : errno == ELOOP ? ObjectError::corrupt + : ObjectError::io}; + struct stat info{}; + if (::fstat(fd.get(), &info) != 0) + return std::unexpected{ObjectError::io}; + // Size is checked before any allocation. + if (!S_ISREG(info.st_mode) || info.st_size < 0 || + static_cast(info.st_size) != object.bytes) + return std::unexpected{ObjectError::corrupt}; + std::vector bytes(static_cast(object.bytes)); + std::size_t done = 0; + while (done < bytes.size()) { + const auto n = ::read(fd.get(), bytes.data() + done, bytes.size() - done); + if (n < 0 && errno == EINTR) + continue; + if (n < 0) + return std::unexpected{ObjectError::io}; + if (n == 0) + return std::unexpected{ObjectError::corrupt}; // Shrunk after fstat. + done += static_cast(n); + } + std::uint8_t extra{}; + if (::read(fd.get(), &extra, 1) != 0) + return std::unexpected{ObjectError::corrupt}; // Grew after fstat. + const auto digest = sha256(bytes); + if (!digest) + return std::unexpected{ObjectError::io}; + if (*digest != object.sha256) + return std::unexpected{ObjectError::corrupt}; + return bytes; +} +} // namespace + +FilesystemObjectStore::FilesystemObjectStore(std::filesystem::path directory, int descriptor, + std::size_t maximum) + : directory_(std::move(directory)), descriptor_(descriptor), maximum_(maximum) {} + +FilesystemObjectStore::~FilesystemObjectStore() { + static_cast(::close(descriptor_)); +} + +std::expected, ObjectError> +FilesystemObjectStore::open(const std::filesystem::path& trusted_root, RegionKey key, + std::size_t max_object_bytes) { + if (key.world == 0 || key.region == 0 || max_object_bytes == 0 || + max_object_bytes > maximum_object_limit || trusted_root.empty()) + return std::unexpected{ObjectError::invalid}; + const Descriptor root{ + ::open(trusted_root.c_str(), O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC)}; + if (root.get() < 0) + return std::unexpected{ObjectError::invalid}; + const auto world = "w" + std::to_string(key.world); + const auto region = "r" + std::to_string(key.region); + const Descriptor world_fd{subdirectory(root.get(), world)}; + if (world_fd.get() < 0) + return std::unexpected{ObjectError::io}; + Descriptor region_fd{subdirectory(world_fd.get(), region)}; + if (region_fd.get() < 0) + return std::unexpected{ObjectError::io}; + return std::unique_ptr(new FilesystemObjectStore( + trusted_root / world / region, region_fd.release(), max_object_bytes)); +} + +std::expected +FilesystemObjectStore::put(std::span bytes) const { + if (bytes.empty()) + return std::unexpected{ObjectError::invalid}; + if (bytes.size() > maximum_) + return std::unexpected{ObjectError::bounds}; + const auto digest = sha256(bytes); + if (!digest) + return std::unexpected{ObjectError::io}; + const VerifiedObject object{*digest, bytes.size()}; + const auto existing = [&]() -> std::expected { + auto stored = read_verified(descriptor_, object); + if (!stored) + return std::unexpected{stored.error()}; + return object; + }; + // Immutable: identical content is reused; anything else under the key is corrupt. + if (auto found = existing(); found || found.error() != ObjectError::missing) + return found; + + const auto name = key_name(*digest); + const auto temporary = ".tmp-" + name + "-" + std::to_string(::getpid()) + "-" + + std::to_string(temporary_counter.fetch_add(1)); + Descriptor fd{::openat(descriptor_, temporary.c_str(), + O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW | O_CLOEXEC, 0600)}; + if (fd.get() < 0) + return std::unexpected{ObjectError::io}; + const auto discard = [&] { static_cast(::unlinkat(descriptor_, temporary.c_str(), 0)); }; + if (!write_all(fd.get(), bytes) || ::fsync(fd.get()) != 0 || !fd.close()) { + discard(); + return std::unexpected{ObjectError::io}; + } + // link() never replaces an existing name, unlike rename(). + if (::linkat(descriptor_, temporary.c_str(), descriptor_, name.c_str(), 0) != 0) { + const bool raced = errno == EEXIST; + discard(); + if (raced) + return existing(); + return std::unexpected{ObjectError::io}; + } + discard(); + if (::fsync(descriptor_) != 0) + return std::unexpected{ObjectError::io}; + return object; +} + +std::expected, ObjectError> +FilesystemObjectStore::get(const VerifiedObject& object) const { + if (object.bytes == 0) + return std::unexpected{ObjectError::invalid}; + if (object.bytes > maximum_) + return std::unexpected{ObjectError::bounds}; + return read_verified(descriptor_, object); +} +} // namespace evo::persistence diff --git a/src/persistence/region_checkpoint.cpp b/src/persistence/region_checkpoint.cpp new file mode 100644 index 0000000..d8bf4c8 --- /dev/null +++ b/src/persistence/region_checkpoint.cpp @@ -0,0 +1,220 @@ +#include "evo/persistence/region_checkpoint.hpp" +#include +#include + +namespace evo::persistence { +namespace { +constexpr std::uint64_t manifest_magic = 0x314D43524F564541ULL; // "AEVORCM1" +constexpr std::uint32_t manifest_version = 1; +constexpr std::uint64_t maximum = ~std::uint64_t{0}; + +template bool zero(const std::array& bytes) { + return std::ranges::all_of(bytes, [](std::uint8_t b) { return b == 0; }); +} +class Writer { + public: + explicit Writer(std::vector& out) : out_(out) {} + void u(std::uint64_t value, unsigned width) { + for (unsigned i = 0; i < width; ++i) { + out_.push_back(static_cast(value & 0xFFU)); + value >>= 8U; + } + } + template void bytes(const std::array& value) { + out_.insert(out_.end(), value.begin(), value.end()); + } + + private: + std::vector& out_; +}; +class Reader { + public: + explicit Reader(std::span in) : in_(in) {} + std::uint64_t u(unsigned width) { + std::uint64_t value{}; + for (unsigned i = 0; i < width; ++i) + value |= static_cast(in_[at_ + i]) << (8U * i); + at_ += width; + return value; + } + template std::array bytes() { + std::array value{}; + std::copy_n(in_.begin() + static_cast(at_), N, value.begin()); + at_ += N; + return value; + } + + private: + std::span in_; + std::size_t at_{}; +}; + +// Every field, independent of which versions this build supports. +bool structural(const CheckpointManifest& m) noexcept { + if (m.key.world == 0 || m.key.region == 0 || m.frame == 0 || zero(m.commit) || + m.tick_microseconds == 0 || zero(m.build) || m.payload_bytes == 0 || + m.payload_bytes > max_environmental_payload_bytes || zero(m.payload_sha256)) + return false; + if (m.sequence == 0) + return zero(m.predecessor_commit) && zero(m.predecessor_digest) && m.begin_tick == 0 && + m.end_tick == 0 && zero(m.holder) && m.epoch == 0; + return !zero(m.predecessor_commit) && m.predecessor_commit != m.commit && + !zero(m.predecessor_digest) && !zero(m.holder) && m.epoch != 0 && + m.end_tick > m.begin_tick && m.end_tick - m.begin_tick <= max_checkpoint_ticks; +} +} // namespace + +bool supported(const CheckpointManifest& m) noexcept { + return m.profile == CheckpointProfile::environmental_v1 && + m.versions == environmental_v1_versions && m.rng_streams == 0 && + m.history_profile == 0 && m.durability == DurabilityPolicy::single_volume_development; +} + +std::expected, CheckpointError> +encode_manifest(const CheckpointManifest& m) { + if (!structural(m)) + return std::unexpected{CheckpointError::format}; + std::vector out; + out.reserve(checkpoint_manifest_bytes); + Writer w{out}; + w.u(manifest_magic, 8); + w.u(manifest_version, 4); + w.u(static_cast(m.profile), 4); + w.u(m.key.world, 8); + w.u(m.key.region, 8); + w.u(m.frame, 8); + w.bytes(m.commit); + w.u(m.sequence, 8); + w.bytes(m.predecessor_commit); + w.bytes(m.predecessor_digest); + w.u(m.begin_tick, 8); + w.u(m.end_tick, 8); + w.bytes(m.holder); + w.u(m.epoch, 8); + w.u(m.tick_microseconds, 8); + for (const auto v : {m.versions.rules, m.versions.envelope, m.versions.resources, + m.versions.fields, m.versions.terrain, m.versions.coordinate, + m.versions.generator, m.versions.material, m.versions.interval_adapter}) + w.u(v, 4); + w.bytes(m.build); + w.u(m.rng_streams, 4); + w.u(m.history_profile, 4); + w.u(static_cast(m.durability), 4); + w.u(m.payload_bytes, 8); + w.bytes(m.payload_sha256); + return out; +} + +std::expected +decode_manifest(std::span bytes) { + if (bytes.size() != checkpoint_manifest_bytes) + return std::unexpected{CheckpointError::format}; + Reader r{bytes}; + if (r.u(8) != manifest_magic) + return std::unexpected{CheckpointError::format}; + if (r.u(4) != manifest_version) + return std::unexpected{CheckpointError::unsupported}; + CheckpointManifest m; + const auto profile = r.u(4); + m.profile = + profile <= 0xFFU ? static_cast(profile) : CheckpointProfile::unknown; + m.key.world = r.u(8); + m.key.region = r.u(8); + m.frame = r.u(8); + m.commit = r.bytes<16>(); + m.sequence = r.u(8); + m.predecessor_commit = r.bytes<16>(); + m.predecessor_digest = r.bytes<32>(); + m.begin_tick = r.u(8); + m.end_tick = r.u(8); + m.holder = r.bytes<16>(); + m.epoch = r.u(8); + m.tick_microseconds = r.u(8); + for (auto* v : {&m.versions.rules, &m.versions.envelope, &m.versions.resources, + &m.versions.fields, &m.versions.terrain, &m.versions.coordinate, + &m.versions.generator, &m.versions.material, &m.versions.interval_adapter}) + *v = static_cast(r.u(4)); + m.build = r.bytes<32>(); + m.rng_streams = static_cast(r.u(4)); + m.history_profile = static_cast(r.u(4)); + const auto durability = r.u(4); + m.durability = + durability <= 0xFFU ? static_cast(durability) : DurabilityPolicy::unknown; + m.payload_bytes = r.u(8); + m.payload_sha256 = r.bytes<32>(); + if (!structural(m)) + return std::unexpected{CheckpointError::format}; + return m; +} + +std::expected +genesis_manifest(RegionKey key, std::uint64_t frame, Uuid commit, std::uint64_t tick_microseconds, + const Sha256Digest& build, std::uint64_t payload_bytes, + const Sha256Digest& payload_sha256) { + CheckpointManifest m; + m.key = key; + m.frame = frame; + m.commit = commit; + m.tick_microseconds = tick_microseconds; + m.build = build; + m.payload_bytes = payload_bytes; + m.payload_sha256 = payload_sha256; + if (!structural(m)) + return std::unexpected{CheckpointError::format}; + return m; +} + +std::expected +successor_manifest(const CheckpointManifest& p, const Sha256Digest& predecessor_digest, Uuid commit, + const LeaseGrant& lease, std::uint64_t end_tick, const Sha256Digest& build, + std::uint64_t payload_bytes, const Sha256Digest& payload_sha256) { + // This build writes only its own versions; a change requires a migration (M7.9). + if (!supported(p)) + return std::unexpected{CheckpointError::unsupported}; + if (!structural(p) || p.sequence == maximum || lease.frame != p.frame || + end_tick <= p.end_tick || end_tick - p.end_tick > max_checkpoint_ticks) + return std::unexpected{CheckpointError::chain}; + CheckpointManifest m = p; + m.commit = commit; + m.sequence = p.sequence + 1; + m.predecessor_commit = p.commit; + m.predecessor_digest = predecessor_digest; + m.begin_tick = p.end_tick; + m.end_tick = end_tick; + m.holder = lease.holder; + m.epoch = lease.epoch; + m.build = build; + m.payload_bytes = payload_bytes; + m.payload_sha256 = payload_sha256; + if (!structural(m)) + return std::unexpected{CheckpointError::format}; + return m; +} + +std::expected, CheckpointError> +restore_environmental_payload(std::span payload, const CheckpointManifest& m, + std::size_t budget) { + if (!structural(m)) + return std::unexpected{CheckpointError::format}; + if (!supported(m)) + return std::unexpected{CheckpointError::unsupported}; + if (payload.size() != m.payload_bytes || payload.size() < 16) + return std::unexpected{CheckpointError::payload}; + Reader header{payload}; + header.u(8); // Envelope magic is checked by the envelope decoder itself. + if (header.u(8) != m.versions.envelope) + return std::unexpected{CheckpointError::unsupported}; + auto restored = + processes::EnvironmentalCommunity::restore(payload, {m.key.world, m.frame}, budget); + if (!restored) + return std::unexpected{CheckpointError::payload}; + const auto& state = **restored; + if (state.progress().tick != m.end_tick || state.tick_microseconds() != m.tick_microseconds) + return std::unexpected{CheckpointError::payload}; + // Canonical: the restored state re-encodes to exactly the committed bytes. + const auto again = state.snapshot(); + if (!again || !std::ranges::equal(*again, payload)) + return std::unexpected{CheckpointError::payload}; + return std::move(*restored); +} +} // namespace evo::persistence diff --git a/src/persistence/region_lease_store.cpp b/src/persistence/region_lease_store.cpp index 369b2e1..4c2f3de 100644 --- a/src/persistence/region_lease_store.cpp +++ b/src/persistence/region_lease_store.cpp @@ -2,6 +2,7 @@ #include #include #include +#include #include #include @@ -27,15 +28,19 @@ LeaseStoreFailure classify(const PgFailure& f) { kind = LeaseStoreError::not_provisioned; else if (state == "EVL05") kind = LeaseStoreError::exhausted; + else if (state == "EVL06") + kind = LeaseStoreError::unsupported; + else if (state == "EVL07") + kind = LeaseStoreError::commit_conflict; return {kind, f}; } LeaseStoreFailure malformed(bool mutation) { // A mutation whose reply cannot be parsed may still have committed. return {mutation ? LeaseStoreError::unknown : LeaseStoreError::store, {}}; } -template std::string hex(const std::array& bytes) { +std::string hex(std::span bytes) { std::string out; - out.reserve(N * 2); + out.reserve(bytes.size() * 2); for (const auto b : bytes) { out.push_back(digits[static_cast(b >> 4U)]); out.push_back(digits[static_cast(b & 0x0FU)]); @@ -61,6 +66,19 @@ template std::optional> unhex(std::s } return out; } +std::optional> unhex_bytes(std::string_view s) { + if (s.size() % 2 != 0) + return std::nullopt; + std::vector out(s.size() / 2); + for (std::size_t i = 0; i < out.size(); ++i) { + const auto high = nibble(s[i * 2]); + const auto low = nibble(s[(i * 2) + 1]); + if (!high || !low) + return std::nullopt; + out[i] = static_cast((*high << 4U) | *low); + } + return out; +} std::string uuid_text(const Uuid& id) { const auto h = hex(id); return h.substr(0, 8) + '-' + h.substr(8, 4) + '-' + h.substr(12, 4) + '-' + h.substr(16, 4) + @@ -89,11 +107,12 @@ template std::optional parse_integer(const std::optional b) { + return "\\x" + hex(b); } -std::optional parse_head(const PgRows& rows) { - if (rows.size() != 1 || rows[0].size() != 5) +// Head columns: frame, sequence, commit, digest hex, end tick (+ optional extras). +std::optional parse_head(const PgRows& rows, std::size_t columns = 5) { + if (rows.size() != 1 || rows[0].size() != columns) return std::nullopt; const auto& r = rows[0]; const auto frame = parse_integer(r[0]); @@ -177,23 +196,28 @@ std::expected load_region_head(Postgres& db, Regi return *head; } +std::expected +load_region_checkpoint(Postgres& db, RegionKey key, milliseconds timeout) { + const std::array p{std::to_string(key.world), std::to_string(key.region)}; + auto rows = db.query( + "SELECT * FROM evolution.load_region_checkpoint($1::evolution.u64, $2::evolution.u64)", p, + timeout); + if (!rows) + return std::unexpected{classify(rows.error())}; + auto head = parse_head(*rows, 6); + const auto& manifest_text = head ? (*rows)[0][5] : std::optional{}; + auto manifest = manifest_text ? unhex_bytes(*manifest_text) : std::nullopt; + if (!head || !manifest) + return std::unexpected{malformed(false)}; + return CommittedCheckpoint{*head, std::move(*manifest)}; +} + std::expected -advance_region_head(Postgres& db, RegionKey key, const LeaseGrant& lease, - const RegionHead& expected, const HeadAdvance& next, milliseconds timeout) { - const std::array p{std::to_string(key.world), - std::to_string(key.region), - uuid_text(lease.holder), - std::to_string(lease.epoch), - std::to_string(expected.sequence), - uuid_text(expected.commit), - bytea(expected.digest), - uuid_text(next.commit), - bytea(next.digest), - std::to_string(next.end_tick)}; - auto rows = db.query("SELECT * FROM evolution.advance_region_head($1::evolution.u64, " - "$2::evolution.u64, $3::uuid, $4::evolution.u64, $5::evolution.u64, " - "$6::uuid, $7::bytea, $8::uuid, $9::bytea, $10::evolution.u64)", - p, timeout); +publish_region_checkpoint(Postgres& db, std::span manifest, + milliseconds timeout) { + const std::array p{bytea(manifest)}; + auto rows = + db.query("SELECT * FROM evolution.publish_region_checkpoint($1::bytea)", p, timeout); if (!rows) return std::unexpected{classify(rows.error())}; auto head = parse_head(*rows); diff --git a/src/persistence/sha256.cpp b/src/persistence/sha256.cpp new file mode 100644 index 0000000..c1736f1 --- /dev/null +++ b/src/persistence/sha256.cpp @@ -0,0 +1,13 @@ +#include "evo/persistence/sha256.hpp" +#include + +namespace evo::persistence { +std::expected sha256(std::span bytes) noexcept { + Sha256Digest out{}; + unsigned int length = 0; + if (EVP_Digest(bytes.data(), bytes.size(), out.data(), &length, EVP_sha256(), nullptr) != 1 || + length != out.size()) + return std::unexpected{DigestError::provider}; + return out; +} +} // namespace evo::persistence diff --git a/tests/fixtures/environmental_region.hpp b/tests/fixtures/environmental_region.hpp new file mode 100644 index 0000000..5d03af6 --- /dev/null +++ b/tests/fixtures/environmental_region.hpp @@ -0,0 +1,84 @@ +#pragma once +// Rules-2 environmental community used by region checkpoint tests (M7.4). +#include "evo/processes/environmental_community.hpp" +#include +#include +#include +#include + +namespace evo::test { +inline constexpr world::WorldIdentity region_identity{7, 9}; + +inline void require(bool ok, const char* what) { + if (!ok) + throw std::runtime_error(what); +} +inline processes::EnvironmentalConfig region_config() { + processes::EnvironmentalConfig c; + c.rules = 2; + c.world = region_identity.world; + c.frame = region_identity.frame; + c.producer = 1; + c.consumer = 2; + c.source = 3; + c.tick_microseconds = 50000; + c.area_um2 = 1; + c.irradiance_numerator = 11; + c.irradiance_denominator = 3; + c.efficiency = 600; + c.growth_numerator = 3; + c.growth_denominator = 2; + c.growth_cost = 1; + c.recipe = {1, 2, 1, 1, 1}; + c.intake.fill(100); + c.assimilation = 1000; + c.producer_min_mK = c.consumer_min_mK = 270000; + c.producer_max_mK = c.consumer_max_mK = 310000; + c.decay.fill(1); + return c; +} +inline std::unique_ptr region_community() { + using namespace world; + constexpr auto maximum = std::numeric_limits::max(); + std::array environment{200, 6, 6, 400, 0, 0, 200, 0, 2000, 0}; + const FieldSite site{{0, 0, -16000}, {{0}, {0}, {0}, {10}, {20}, {3}}, {1}}; + std::array opening{}; + for (std::size_t k = 0; k < 10; ++k) + opening[k] = {static_cast(k), {&environment[k], 1}}; + const FieldDefaults defaults{ + {accounting::Femtograms{0}, accounting::Femtograms{maximum}, accounting::Femtograms{0}}}; + auto f = FieldStore::create(region_identity, 1, defaults, {&site, 1}, opening, 2000000); + require(f.has_value(), "field store"); + auto t = ChunkStore::create({}, 1, 2000000, {{VolumeUnits{100}, VolumeUnits{100}}}); + require(t.has_value(), "chunk store"); + require((*t)->load({0, 0, -1000}).has_value(), "chunk load"); + std::array accounts{}; + accounts[0].id = {1}; + accounts[1].id = {2}; + accounts[0].capacities.fill(100000000); + accounts[1].capacities.fill(100000000); + auto r = EnvironmentalTransfers::create(region_identity, std::move(*f), std::move(*t), accounts, + 4000000); + require(r.has_value(), "transfers"); + auto o = processes::EnvironmentalCommunity::create(region_config(), std::move(*r), 8000000); + require(o.has_value(), "community"); + return std::move(*o); +} +// Deterministic input for tick t; the consumer dies at tick 20 when requested. +inline processes::EnvironmentalInput region_input(std::uint64_t tick, bool consumer_dies = false) { + processes::EnvironmentalInput in; + in.temperature_mK = 290000; + in.source_enabled = tick % 7 == 0 ? 0 : 1; + if (tick == 16) + in.bite = {2, 2, 2, 2, 1}; + if (consumer_dies && tick == 20) + in.terminal[1] = 1; + return in; +} +inline void advance_region(processes::EnvironmentalCommunity& o, std::uint64_t ticks) { + for (std::uint64_t i = 0; i < ticks; ++i) { + const auto tick = o.progress().tick + 1; + require(o.advance(tick, region_input(tick)).has_value(), "advance"); + } +} +} // namespace evo::test diff --git a/tests/postgres_tests.cpp b/tests/postgres_tests.cpp index b63f7fb..f3d2bf9 100644 --- a/tests/postgres_tests.cpp +++ b/tests/postgres_tests.cpp @@ -4,6 +4,7 @@ #include #include void run_region_lease_store_tests(); +void run_region_checkpoint_store_tests(); namespace { using namespace evo::persistence; using namespace std::chrono_literals; @@ -72,6 +73,8 @@ int main() { std::puts("postgres adapter integration passed"); run_region_lease_store_tests(); std::puts("region lease fencing integration passed"); + run_region_checkpoint_store_tests(); + std::puts("region checkpoint publication integration passed"); return 0; } catch (const std::exception& e) { std::fprintf(stderr, "%s\n", e.what()); diff --git a/tests/region_checkpoint_store_tests.cpp b/tests/region_checkpoint_store_tests.cpp new file mode 100644 index 0000000..57a1ba9 --- /dev/null +++ b/tests/region_checkpoint_store_tests.cpp @@ -0,0 +1,357 @@ +// Real PostgreSQL + filesystem M7.4 checkpoint publication/recovery (ADR-0061). +#include "evo/persistence/checkpoint_store.hpp" +#include "evo/persistence/sha256.hpp" +#include "fixtures/environmental_region.hpp" +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +void run_region_checkpoint_store_tests(); + +namespace { +using namespace evo::persistence; +using namespace std::chrono_literals; +namespace fs = std::filesystem; +void check(bool value, std::source_location at = std::source_location::current()) { + if (!value) + throw std::runtime_error("region checkpoint store test line " + std::to_string(at.line())); +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) +std::string env(const char* key) { + const auto* value = std::getenv(key); + if (!value) + throw std::runtime_error("missing test environment"); + return value; +} +std::unique_ptr connect_as(const std::string& user) { + PgOptions options{env("PGHOST"), {}, env("PGPORT"), env("PGDATABASE"), user, {}, {}}; + auto made = Postgres::connect(options, 5s); + CHECK(made); + return std::move(*made); +} +template std::array filled(std::uint8_t value) { + std::array out{}; + out.fill(value); + return out; +} +std::string hex(std::span bytes) { + constexpr char digits[] = "0123456789abcdef"; + std::string out; + for (const auto b : bytes) { + out.push_back(digits[b >> 4U]); + out.push_back(digits[b & 0x0FU]); + } + return out; +} +std::vector bytes_of(std::string_view s) { + return {s.begin(), s.end()}; +} +// Private scratch root; the CI script runs each binary under its own /tmp dir. +fs::path scratch(const char* name) { + const auto root = fs::path(env("PGHOST")) / name; + fs::remove_all(root); + fs::create_directory(root); + fs::permissions(root, fs::perms::owner_all, fs::perm_options::replace); + return root; +} +const Sha256Digest build = filled<32>(0xB1); +constexpr std::size_t budget = 8000000; + +void sha256_vectors_and_database_agreement() { + // FIPS 180-2 / NIST example vectors. + CHECK(hex(*sha256({})) == "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"); + CHECK(hex(*sha256(bytes_of("abc"))) == + "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"); + CHECK(hex(*sha256(bytes_of("abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"))) == + "248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1"); + // Independent implementation: PostgreSQL computes the commit digest. + auto db = connect_as(env("PGUSER")); + std::vector data(2000); // Hex parameter stays within the 4KiB adapter bound. + for (std::size_t i = 0; i < data.size(); ++i) + data[i] = static_cast((i * 131U) ^ (i >> 3U)); + const std::array p{"\\x" + hex(data)}; + auto rows = db->query("SELECT encode(sha256($1::bytea), 'hex')", p, 5s); + CHECK(rows && (*rows)[0][0] == hex(*sha256(data))); +} + +void object_store_is_immutable_and_verified() { + const auto root = scratch("objects"); + CHECK(!FilesystemObjectStore::open(root / "absent", {1, 1}, 1024)); + CHECK(!FilesystemObjectStore::open(root, {0, 1}, 1024)); + fs::create_directory_symlink(root, root.parent_path() / "objects-link"); + CHECK(!FilesystemObjectStore::open(root.parent_path() / "objects-link", {1, 1}, 1024)); + fs::remove(root.parent_path() / "objects-link"); + auto store = FilesystemObjectStore::open(root, {1, 2}, 1024); + CHECK(store); + const auto dir = (*store)->directory(); + CHECK(dir == root / "w1" / "r2"); + CHECK((fs::status(dir).permissions() & fs::perms::all) == fs::perms::owner_all); + + const auto payload = bytes_of("immutable payload bytes"); + auto put = (*store)->put(payload); + CHECK(put && put->bytes == payload.size() && put->sha256 == *sha256(payload)); + auto again = (*store)->put(payload); // Idempotent for identical bytes. + CHECK(again && *again == *put); + auto got = (*store)->get(*put); + CHECK(got && *got == payload); + const auto file = dir / hex(put->sha256); + CHECK((fs::status(file).permissions() & fs::perms::all) == fs::perms::owner_read || + (fs::status(file).permissions() & fs::perms::all) == + (fs::perms::owner_read | fs::perms::owner_write)); + + CHECK((*store)->put({}).error() == ObjectError::invalid); + CHECK((*store)->put(std::vector(1025)).error() == ObjectError::bounds); + CHECK((*store)->get({put->sha256, 1025}).error() == ObjectError::bounds); + CHECK((*store)->get({filled<32>(7), 5}).error() == ObjectError::missing); + CHECK((*store)->get({put->sha256, put->bytes - 1}).error() == ObjectError::corrupt); + + // A crash mid-upload leaves only a temporary name no key can resolve. + std::ofstream(dir / (".tmp-" + hex(filled<32>(9)) + "-1-0")) << "partial"; + CHECK((*store)->get({filled<32>(9), 7}).error() == ObjectError::missing); + + // Corruption is detected, and never repaired by overwriting. + { + std::fstream f(file, std::ios::in | std::ios::out | std::ios::binary); + f.seekp(3); + f.put('X'); + } + CHECK((*store)->get(*put).error() == ObjectError::corrupt); + CHECK((*store)->put(payload).error() == ObjectError::corrupt); + fs::remove(file); + fs::create_symlink(dir / "elsewhere", file); + CHECK((*store)->get(*put).error() == ObjectError::corrupt); + fs::remove(file); + CHECK((*store)->put(payload) && (*store)->get(*put)); + fs::resize_file(file, payload.size() + 1); + CHECK((*store)->get(*put).error() == ObjectError::corrupt); + fs::remove(file); + + if (::geteuid() != 0) { // Permission faults cannot be simulated as root. + fs::permissions(dir, fs::perms::owner_read | fs::perms::owner_exec, + fs::perm_options::replace); + CHECK((*store)->put(payload).error() == ObjectError::io); + fs::permissions(dir, fs::perms::owner_all, fs::perm_options::replace); + } +} + +struct Region { + RegionKey key{7, 3}; + std::unique_ptr owner, runtime; + std::unique_ptr objects; +}; +Region provisioned(const char* name, std::uint64_t region, std::uint8_t genesis_seed) { + Region r; + r.key.region = region; + r.owner = connect_as(env("PGUSER")); + r.runtime = connect_as(env("EVO_PG_RUNTIME_USER")); + auto objects = + FilesystemObjectStore::open(scratch(name), r.key, max_environmental_payload_bytes); + CHECK(objects); + r.objects = std::move(*objects); + CHECK(r.owner->query("INSERT INTO evolution.retained_builds(build_identity) VALUES " + "(decode(repeat('b1', 32), 'hex')) ON CONFLICT DO NOTHING", + {}, 5s)); + auto opening = evo::test::region_community(); + auto genesis = provision_environmental_region(*r.owner, *r.objects, r.key, + evo::test::region_identity.frame, *opening, + filled<16>(genesis_seed), build, budget, 5s); + CHECK(genesis && genesis->head.sequence == 0); + return r; +} +std::size_t count_objects(const fs::path& dir) { + std::size_t n = 0; + for (const auto& entry : fs::directory_iterator(dir)) + n += entry.path().filename().string().starts_with(".tmp-") ? 0 : 1; + return n; +} + +void publish_recover_and_continue() { + auto r = provisioned("publish", 3, 0xC0); + const std::array retained{build}; + auto lease = acquire_region_lease(*r.runtime, r.key, 20000ms, 5s); + CHECK(lease); + // Genesis recovers to the exact opening state. + auto recovered = + recover_environmental_checkpoint(*r.runtime, *r.objects, r.key, retained, budget, 5s); + CHECK(recovered && recovered->state->progress().tick == 0); + auto head = recovered->committed; + + // Genesis cannot be re-provisioned or published over. + auto opening = evo::test::region_community(); + CHECK(!provision_environmental_region(*r.owner, *r.objects, r.key, 9, *opening, + filled<16>(0xC9), build, budget, 5s)); + + auto original = evo::test::region_community(); + std::uint8_t seed = 0xC1; + for (int batch = 0; batch < 3; ++batch) { + evo::test::advance_region(*original, batch == 1 ? 64 : 16); + const auto started = std::chrono::steady_clock::now(); + auto published = publish_environmental_checkpoint( + *r.runtime, *r.objects, *lease, head, *original, filled<16>(seed++), build, budget, 5s); + const auto us = std::chrono::duration_cast( + std::chrono::steady_clock::now() - started) + .count(); + CHECK(published && published->head.sequence == head.head.sequence + 1); + CHECK(published->head.end_tick == original->progress().tick); + std::printf( + "checkpoint_publish_us batch=%d ticks=%llu payload_bytes=%llu us=%lld\n", batch, + static_cast(published->head.end_tick - head.head.end_tick), + static_cast(decode_manifest(published->manifest)->payload_bytes), + static_cast(us)); + head = std::move(*published); + } + // 65 ticks is more than one batch: refused before upload. + const auto before = count_objects(r.objects->directory()); + evo::test::advance_region(*original, 65); + auto oversized = publish_environmental_checkpoint( + *r.runtime, *r.objects, *lease, head, *original, filled<16>(0xCA), build, budget, 5s); + CHECK(!oversized && oversized.error().kind == PublicationError::candidate); + CHECK(count_objects(r.objects->directory()) == before); + + // A new process recovers the committed head; its trajectory matches the original's. + auto second = FilesystemObjectStore::open(r.objects->directory().parent_path().parent_path(), + r.key, max_environmental_payload_bytes); + CHECK(second); + auto restored = + recover_environmental_checkpoint(*r.runtime, **second, r.key, retained, budget, 5s); + CHECK(restored && restored->committed.head == head.head); + CHECK(restored->state->progress().tick == 96); + auto reference = evo::test::region_community(); + evo::test::advance_region(*reference, 96); + CHECK(reference->snapshot() == restored->state->snapshot()); + for (std::uint64_t tick = 97; tick <= 140; ++tick) { + auto a = reference->advance(tick, evo::test::region_input(tick, true)); + auto b = restored->state->advance(tick, evo::test::region_input(tick, true)); + CHECK(a && b && *a == *b); + } + CHECK(reference->snapshot() == restored->state->snapshot()); + + // Retained-build allowlist: a host without this build cannot restore it. + const std::array other{filled<32>(0xB2)}; + auto foreign = + recover_environmental_checkpoint(*r.runtime, *r.objects, r.key, other, budget, 5s); + CHECK(!foreign && foreign.error().kind == RecoveryError::unsupported); + // Unretained build is refused by the database; the upload stays an orphan. + auto next = evo::test::region_community(); + evo::test::advance_region(*next, 100); + auto refused = publish_environmental_checkpoint(*r.runtime, *r.objects, *lease, head, *next, + filled<16>(0xCB), filled<32>(0xB2), budget, 5s); + CHECK(!refused && refused.error().kind == PublicationError::rejected && + refused.error().store.kind == LeaseStoreError::unsupported); + CHECK(release_region_lease(*r.runtime, r.key, *lease, 5s)); +} + +void failures_leave_the_previous_head() { + auto r = provisioned("failures", 4, 0xD0); + const std::array retained{build}; + auto lease = acquire_region_lease(*r.runtime, r.key, 20000ms, 5s); + CHECK(lease); + auto head = load_region_checkpoint(*r.runtime, r.key, 5s); + CHECK(head); + auto state = evo::test::region_community(); + evo::test::advance_region(*state, 8); + auto first = publish_environmental_checkpoint(*r.runtime, *r.objects, *lease, *head, *state, + filled<16>(0xD1), build, budget, 5s); + CHECK(first); + const auto manifest = *decode_manifest(first->manifest); + const auto object = r.objects->directory() / hex(manifest.payload_sha256); + + // Upload failure: no manifest is sent; the head does not move. + evo::test::advance_region(*state, 8); + if (::geteuid() != 0) { + fs::permissions(r.objects->directory(), fs::perms::owner_read | fs::perms::owner_exec, + fs::perm_options::replace); + auto upload = publish_environmental_checkpoint(*r.runtime, *r.objects, *lease, *first, + *state, filled<16>(0xD2), build, budget, 5s); + fs::permissions(r.objects->directory(), fs::perms::owner_all, fs::perm_options::replace); + CHECK(!upload && upload.error().kind == PublicationError::upload); + CHECK(load_region_head(*r.runtime, r.key, 5s)->sequence == 1); + } + + // Manifest transaction failure after a verified upload: fenced writer, orphan retained. + auto stale = *lease; + stale.holder[0] ^= 1U; + auto fenced = publish_environmental_checkpoint(*r.runtime, *r.objects, stale, *first, *state, + filled<16>(0xD3), build, budget, 5s); + CHECK(!fenced && fenced.error().kind == PublicationError::rejected && + fenced.error().store.kind == LeaseStoreError::fenced); + auto orphan_bytes = state->snapshot(); + auto orphan = r.objects->get({*sha256(*orphan_bytes), orphan_bytes->size()}); + CHECK(orphan && *orphan == *orphan_bytes); // Uploaded, verified, unreferenced. + auto recovered = + recover_environmental_checkpoint(*r.runtime, *r.objects, r.key, retained, budget, 5s); + CHECK(recovered && recovered->state->progress().tick == 8); // Never the orphan. + + // Missing and corrupt committed payloads quarantine; no older head is selected. + const auto saved = r.objects->get({manifest.payload_sha256, manifest.payload_bytes}); + CHECK(saved); + fs::remove(object); + auto missing = + recover_environmental_checkpoint(*r.runtime, *r.objects, r.key, retained, budget, 5s); + CHECK(!missing && missing.error().kind == RecoveryError::missing_payload); + CHECK(r.objects->put(*saved)); + fs::permissions(object, fs::perms::owner_all, fs::perm_options::replace); + { + std::fstream f(object, std::ios::in | std::ios::out | std::ios::binary); + f.seekp(100); + f.put(static_cast((*saved)[100] ^ 1U)); + } + auto corrupt = + recover_environmental_checkpoint(*r.runtime, *r.objects, r.key, retained, budget, 5s); + CHECK(!corrupt && corrupt.error().kind == RecoveryError::corrupt_payload); + fs::remove(object); + CHECK(r.objects->put(*saved)); + CHECK(recover_environmental_checkpoint(*r.runtime, *r.objects, r.key, retained, budget, 5s)); + + // The database refuses tampering with committed manifests even by the owner. + auto tamper = r.owner->query("UPDATE evolution.region_commits SET manifest = " + "overlay(manifest placing '\\x02'::bytea from 121 for 1) " + "WHERE world_id = 7 AND region_id = 4 AND commit_sequence = 1", + {}, 5s); + CHECK(!tamper && std::string(tamper.error().sqlstate.data()) == "23514"); + auto repoint = r.owner->query("UPDATE evolution.region_heads SET digest = sha256('\\x00') " + "WHERE world_id = 7 AND region_id = 4", + {}, 5s); + CHECK(!repoint && std::string(repoint.error().sqlstate.data()) == "23503"); + // Defense in depth: even if that constraint were lost, recovery re-digests the + // manifest and quarantines. Restores the constraint before continuing. + CHECK(r.owner->query("ALTER TABLE evolution.region_commits DROP CONSTRAINT " + "region_commits_manifest_digest", + {}, 5s)); + // Flip a payload-digest byte: only the manifest digest check can notice it. + CHECK(r.owner->query("UPDATE evolution.region_commits SET manifest = " + "set_byte(manifest, 248, get_byte(manifest, 248) # 1) " + "WHERE world_id = 7 AND region_id = 4 AND commit_sequence = 1", + {}, 5s)); + auto tampered = + recover_environmental_checkpoint(*r.runtime, *r.objects, r.key, retained, budget, 5s); + CHECK(!tampered && tampered.error().kind == RecoveryError::manifest); + const std::array original{"\\x" + hex(first->manifest)}; + CHECK(r.owner->query("UPDATE evolution.region_commits SET manifest = $1::bytea " + "WHERE world_id = 7 AND region_id = 4 AND commit_sequence = 1", + original, 5s)); + CHECK(r.owner->query("ALTER TABLE evolution.region_commits ADD CONSTRAINT " + "region_commits_manifest_digest CHECK (commit_digest = sha256(manifest))", + {}, 5s)); + CHECK(recover_environmental_checkpoint(*r.runtime, *r.objects, r.key, retained, budget, 5s)); + + // Recovery does not create genesis for an unknown region. + auto none = + recover_environmental_checkpoint(*r.runtime, *r.objects, {7, 99}, retained, budget, 5s); + CHECK(!none && none.error().kind == RecoveryError::not_provisioned); +} +} // namespace + +void run_region_checkpoint_store_tests() { + sha256_vectors_and_database_agreement(); + object_store_is_immutable_and_verified(); + publish_recover_and_continue(); + failures_leave_the_previous_head(); +} diff --git a/tests/region_checkpoint_tests.cpp b/tests/region_checkpoint_tests.cpp new file mode 100644 index 0000000..c24d5cc --- /dev/null +++ b/tests/region_checkpoint_tests.cpp @@ -0,0 +1,199 @@ +#include "evo/persistence/region_checkpoint.hpp" +#include "fixtures/environmental_region.hpp" + +#include +#include +#include +#include +#include + +namespace { +using namespace evo::persistence; +using evo::test::advance_region; +using evo::test::region_community; +using evo::test::region_input; +void check(bool ok, std::source_location at = std::source_location::current()) { + if (!ok) + throw std::runtime_error("region checkpoint line " + std::to_string(at.line())); +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) +template std::array filled(std::uint8_t value) { + std::array out{}; + out.fill(value); + return out; +} +constexpr RegionKey key{7, 3}; +const auto build = filled<32>(0xB1); +LeaseGrant lease() { + return {filled<16>(0x11), 4, 9, std::chrono::milliseconds{20000}}; +} +CheckpointManifest genesis(std::uint64_t payload_bytes = 100) { + auto g = + genesis_manifest(key, 9, filled<16>(0x01), 50000, build, payload_bytes, filled<32>(0xA0)); + CHECK(g); + return *g; +} +CheckpointManifest next(std::uint64_t end_tick = 16) { + auto n = successor_manifest(genesis(), filled<32>(0xD0), filled<16>(0x02), lease(), end_tick, + build, 200, filled<32>(0xA1)); + CHECK(n); + return *n; +} +std::uint64_t at(const std::vector& b, std::size_t offset, unsigned width) { + std::uint64_t value{}; + for (unsigned i = 0; i < width; ++i) + value |= static_cast(b[offset + i]) << (8U * i); + return value; +} + +void layout_and_round_trip() { + const auto m = next(); + auto bytes = encode_manifest(m); + CHECK(bytes && bytes->size() == checkpoint_manifest_bytes); + // Golden offsets from schemas/region-commit.md. + CHECK(std::string_view(reinterpret_cast(bytes->data()), 8) == "AEVORCM1"); + CHECK(at(*bytes, 8, 4) == 1 && at(*bytes, 12, 4) == 1); + CHECK(at(*bytes, 16, 8) == 7 && at(*bytes, 24, 8) == 3 && at(*bytes, 32, 8) == 9); + CHECK((*bytes)[40] == 0x02 && at(*bytes, 56, 8) == 1 && (*bytes)[64] == 0x01); + CHECK((*bytes)[80] == 0xD0 && at(*bytes, 112, 8) == 0 && at(*bytes, 120, 8) == 16); + CHECK((*bytes)[128] == 0x11 && at(*bytes, 144, 8) == 4 && at(*bytes, 152, 8) == 50000); + CHECK(at(*bytes, 160, 4) == 2 && at(*bytes, 164, 4) == 2 && at(*bytes, 192, 4) == 1); + CHECK((*bytes)[196] == 0xB1 && at(*bytes, 228, 4) == 0 && at(*bytes, 232, 4) == 0); + CHECK(at(*bytes, 236, 4) == 1 && at(*bytes, 240, 8) == 200 && (*bytes)[248] == 0xA1); + auto decoded = decode_manifest(*bytes); + CHECK(decoded && *decoded == m && supported(*decoded)); + auto g = encode_manifest(genesis()); + CHECK(g && decode_manifest(*g) == genesis()); +} + +void malformed_and_unsupported() { + auto bytes = *encode_manifest(next()); + CHECK(decode_manifest(std::span{bytes}.first(279)).error() == CheckpointError::format); + auto grown = bytes; + grown.push_back(0); + CHECK(decode_manifest(grown).error() == CheckpointError::format); + auto magic = bytes; + magic[0] ^= 1U; + CHECK(decode_manifest(magic).error() == CheckpointError::format); + auto version = bytes; + version[8] = 2; + CHECK(decode_manifest(version).error() == CheckpointError::unsupported); + // Structurally invalid: zero world, 65-tick batch, oversized payload, zero digest. + for (const auto& [offset, value] : + {std::pair{16, 0}, std::pair{120, 65}, std::pair{242, 0x11}, std::pair{144, 0}}) { + auto b = bytes; + b[static_cast(offset)] = static_cast(value); + if (offset == 144) + std::fill_n(b.begin() + 144, 8, std::uint8_t{0}); // Epoch zero off genesis. + CHECK(decode_manifest(b).error() == CheckpointError::format); + } + auto sha = bytes; + std::fill_n(sha.begin() + 248, 32, std::uint8_t{0}); + CHECK(decode_manifest(sha).error() == CheckpointError::format); + // Parsable but not admitted by this build: decode succeeds, supported() refuses. + // 13/237 make profile/durability 257: never truncated onto a supported value. + for (const std::size_t offset : {12U, 13U, 160U, 164U, 192U, 228U, 232U, 236U, 237U}) { + auto b = bytes; + b[offset] = static_cast(b[offset] + 1); + auto d = decode_manifest(b); + CHECK(d && !supported(*d)); + } + auto g = genesis(); + g.holder = filled<16>(1); + CHECK(encode_manifest(g).error() == CheckpointError::format); + g = genesis(); + g.end_tick = 1; + CHECK(encode_manifest(g).error() == CheckpointError::format); + CHECK( + !genesis_manifest(key, 9, filled<16>(1), 50000, build, 1024 * 1024 + 1, filled<32>(0xA0))); + CHECK(!genesis_manifest(key, 0, filled<16>(1), 50000, build, 1, filled<32>(0xA0))); +} + +void successor_chain() { + const auto g = genesis(); + const auto d = filled<32>(0xD0); + const auto payload = filled<32>(0xA1); + CHECK(successor_manifest(g, d, filled<16>(2), lease(), 0, build, 1, payload).error() == + CheckpointError::chain); + CHECK(successor_manifest(g, d, filled<16>(2), lease(), 65, build, 1, payload).error() == + CheckpointError::chain); + auto foreign = lease(); + foreign.frame = 8; + CHECK(successor_manifest(g, d, filled<16>(2), foreign, 1, build, 1, payload).error() == + CheckpointError::chain); + CHECK(successor_manifest(g, d, g.commit, lease(), 1, build, 1, payload).error() == + CheckpointError::format); // Reused commit identity. + auto old = g; + old.versions.rules = 1; + CHECK(successor_manifest(old, d, filled<16>(2), lease(), 1, build, 1, payload).error() == + CheckpointError::unsupported); + auto last = next(); + last.sequence = ~std::uint64_t{0}; + CHECK(successor_manifest(last, d, filled<16>(3), lease(), 17, build, 1, payload).error() == + CheckpointError::chain); + const auto n = next(64); + CHECK(n.sequence == 1 && n.predecessor_commit == g.commit && n.predecessor_digest == d); + CHECK(n.begin_tick == 0 && n.holder == lease().holder && n.epoch == 4 && n.frame == 9); +} + +void payload_validation_and_restored_trajectory() { + const RegionKey region{evo::test::region_identity.world, 3}; + auto original = region_community(); + auto opening = original->snapshot(); + CHECK(opening); + auto g = genesis_manifest(region, evo::test::region_identity.frame, filled<16>(1), 50000, build, + opening->size(), filled<32>(0xA0)); + CHECK(g && restore_environmental_payload(*opening, *g, 8000000)); + + advance_region(*original, 16); + auto payload = original->snapshot(); + CHECK(payload); + auto lease_at_frame = lease(); + lease_at_frame.frame = evo::test::region_identity.frame; + auto m = successor_manifest(*g, filled<32>(0xD0), filled<16>(2), lease_at_frame, 16, build, + payload->size(), filled<32>(0xA1)); + CHECK(m); + auto restored = restore_environmental_payload(*payload, *m, 8000000); + CHECK(restored); + // The restored checkpoint continues exactly like the uninterrupted original. + for (std::uint64_t tick = 17; tick <= 40; ++tick) { + auto a = original->advance(tick, region_input(tick, true)); + auto b = (*restored)->advance(tick, region_input(tick, true)); + CHECK(a && b && *a == *b); + } + CHECK(original->snapshot() == (*restored)->snapshot()); + + const auto refused = [&](auto change, CheckpointError error) { + auto bytes = *payload; + auto manifest = *m; + change(bytes, manifest); + auto r = restore_environmental_payload(bytes, manifest, 8000000); + return !r && r.error() == error; + }; + CHECK(refused([](auto&, auto& x) { x.end_tick = 15; }, CheckpointError::payload)); + CHECK(refused([](auto&, auto& x) { x.key.world = 8; }, CheckpointError::payload)); + CHECK(refused([](auto&, auto& x) { x.frame = 10; }, CheckpointError::payload)); + CHECK(refused([](auto&, auto& x) { x.tick_microseconds = 25000; }, CheckpointError::payload)); + CHECK(refused([](auto&, auto& x) { --x.payload_bytes; }, CheckpointError::payload)); + CHECK(refused([](auto& b, auto&) { b[b.size() / 2] ^= 1U; }, CheckpointError::payload)); + CHECK(refused([](auto&, auto& x) { x.versions.rules = 1; }, CheckpointError::unsupported)); + CHECK(refused([](auto&, auto& x) { x.rng_streams = 1; }, CheckpointError::unsupported)); + CHECK(refused([](auto&, auto& x) { x.history_profile = 1; }, CheckpointError::unsupported)); + CHECK(refused([](auto& b, auto&) { b[8] = 1; }, CheckpointError::unsupported)); + CHECK(!restore_environmental_payload(*payload, *m, 1000)); // Budget still charged. +} +} // namespace + +int main() { + try { + layout_and_round_trip(); + malformed_and_unsupported(); + successor_chain(); + payload_validation_and_restored_trajectory(); + std::puts("region checkpoint contracts passed"); + return 0; + } catch (const std::exception& e) { + std::fprintf(stderr, "%s\n", e.what()); + return 1; + } +} diff --git a/tests/region_lease_store_tests.cpp b/tests/region_lease_store_tests.cpp index 17a1be2..e698e02 100644 --- a/tests/region_lease_store_tests.cpp +++ b/tests/region_lease_store_tests.cpp @@ -1,4 +1,6 @@ -// Real PostgreSQL M7.3 fencing checks (ADR-0060). Run by tools/ci/postgres-check.sh. +// Real PostgreSQL M7.3 fencing checks (ADR-0060), publishing M7.4 manifests +// (ADR-0061) with synthetic payload digests. Run by tools/ci/postgres-check.sh. +#include "evo/persistence/region_checkpoint.hpp" #include "evo/persistence/region_lease_store.hpp" #include #include @@ -8,6 +10,7 @@ #include #include #include +#include #include #include #include @@ -52,29 +55,76 @@ Sha256Digest digest(std::uint8_t seed) { out.fill(seed); return out; } -std::string hex_text(std::uint8_t seed, std::size_t bytes) { +const Sha256Digest build = digest(0xB1); +void retain_build(Postgres& db) { + CHECK(db.query("INSERT INTO evolution.retained_builds(build_identity) VALUES " + "(decode(repeat('b1', 32), 'hex')) ON CONFLICT DO NOTHING", + {}, 5s)); +} +std::string bytea(std::span bytes) { constexpr char digits[] = "0123456789abcdef"; - std::string out; - for (std::size_t i = 0; i < bytes; ++i) { - out.push_back(digits[seed >> 4U]); - out.push_back(digits[seed & 0x0FU]); + std::string out = "\\x"; + for (const auto b : bytes) { + out.push_back(digits[b >> 4U]); + out.push_back(digits[b & 0x0FU]); } return out; } -std::string uuid_literal(std::uint8_t seed) { - const auto h = hex_text(seed, 16); - return h.substr(0, 8) + '-' + h.substr(8, 4) + '-' + h.substr(12, 4) + '-' + h.substr(16, 4) + - '-' + h.substr(20); -} -// Genesis commit/digest bytes are the region number; frame is 7. +// Genesis commit ID bytes are the region number; frame is 7. Payload digests are +// synthetic: the database records them and never reads the object store. RegionKey provision(Postgres& db, std::uint64_t region) { - const auto seed = static_cast(region); - const std::array p{std::to_string(region), uuid_literal(seed), - "\\x" + hex_text(seed, 32), "7"}; - CHECK(db.query("SELECT evolution.provision_region(1, $1::evolution.u64, $4::evolution.u64, " - "$2::uuid, $3::bytea)", - p, 5s)); - return {1, region}; + retain_build(db); + const RegionKey key{1, region}; + auto g = genesis_manifest(key, 7, id(static_cast(region)), 50000, build, 100, + digest(0xA0)); + CHECK(g); + auto bytes = encode_manifest(*g); + CHECK(bytes); + const std::array p{bytea(*bytes)}; + CHECK(db.query("SELECT evolution.provision_region_checkpoint($1::bytea)", p, 5s)); + return key; +} +CommittedCheckpoint committed(Postgres& db, RegionKey key) { + auto c = load_region_checkpoint(db, key, 5s); + CHECK(c); + return std::move(*c); +} +// Successor fields set directly, so tests can send links the local builder refuses. +CheckpointManifest link(const CommittedCheckpoint& from, const LeaseGrant& lease, + std::uint8_t commit, std::uint64_t end_tick) { + auto m = decode_manifest(from.manifest); + CHECK(m); + m->commit = id(commit); + m->sequence = from.head.sequence + 1; + m->predecessor_commit = from.head.commit; + m->predecessor_digest = from.head.digest; + m->begin_tick = from.head.end_tick; + m->end_tick = end_tick; + m->holder = lease.holder; + m->epoch = lease.epoch; + m->payload_sha256 = digest(0xA1); + return *m; +} +std::expected publish(Postgres& db, + std::vector bytes) { + auto head = publish_region_checkpoint(db, bytes, 5s); + if (!head) + return std::unexpected{head.error()}; + return CommittedCheckpoint{*head, std::move(bytes)}; +} +std::expected publish(Postgres& db, + const CheckpointManifest& m) { + auto bytes = encode_manifest(m); + CHECK(bytes); + return publish(db, std::move(*bytes)); +} +// Encodes a valid link, then overwrites raw bytes the encoder would refuse. +std::vector patched(const CheckpointManifest& m, std::size_t offset, + std::span value) { + auto bytes = encode_manifest(m); + CHECK(bytes); + std::ranges::copy(value, bytes->begin() + static_cast(offset)); + return std::move(*bytes); } bool failed(const auto& result, LeaseStoreError kind) { return !result && result.error().kind == kind; @@ -94,7 +144,10 @@ void runtime_cannot_bypass_the_guard() { "INSERT INTO evolution.region_leases(world_id,region_id,frame_id) VALUES (9,9,9)", "SELECT * FROM evolution.region_leases", "SELECT * FROM evolution.region_heads", - "SELECT evolution.provision_region(1, 11, 7, gen_random_uuid(), '\\x00')", + "SELECT evolution.provision_region_checkpoint('\\x00')", + "SELECT * FROM evolution.region_commits", + "INSERT INTO evolution.retained_builds VALUES ('\\x00')", + "SELECT evolution.parse_checkpoint_manifest('\\x00')", "SELECT evolution.check_region_lease(1, 10, gen_random_uuid(), 1)", "CREATE FUNCTION evolution.bypass() RETURNS int LANGUAGE sql AS 'SELECT 1'", "CREATE TABLE evolution.bypass(x int)", @@ -110,7 +163,7 @@ void runtime_cannot_bypass_the_guard() { CHECK(release_region_lease(*db, key, *lease, 5s)); } -void acquire_renew_release_and_advance() { +void acquire_renew_release_and_publish() { auto admin = owner(); const auto key = provision(*admin, 20); auto db = runtime(); @@ -130,39 +183,50 @@ void acquire_renew_release_and_advance() { stale_epoch.epoch = 2; CHECK(failed(renew_region_lease(*db, key, stale_epoch, 20000ms, 5s), LeaseStoreError::fenced)); - auto genesis = load_region_head(*db, key, 5s); - CHECK(genesis && genesis->sequence == 0 && genesis->end_tick == 0 && genesis->frame == 7); - CHECK(genesis->commit == id(20) && genesis->digest == digest(20)); - CHECK(failed(advance_region_head(*db, key, *lease, *genesis, {id(21), digest(21), 65}, 5s), + const auto genesis = committed(*db, key); + CHECK(genesis.head.sequence == 0 && genesis.head.end_tick == 0 && genesis.head.frame == 7); + CHECK(genesis.head.commit == id(20) && genesis.head.digest != Sha256Digest{}); + const std::array tick65{65}; + CHECK(failed(publish(*db, patched(link(genesis, *lease, 21, 64), 120, tick65)), LeaseStoreError::invalid)); - CHECK(failed(advance_region_head(*db, key, *lease, *genesis, {id(20), digest(21), 1}, 5s), + const auto reused = id(20); + CHECK(failed(publish(*db, patched(link(genesis, *lease, 21, 1), 40, reused)), LeaseStoreError::invalid)); - const HeadAdvance first{id(21), digest(21), 64}; - auto head = advance_region_head(*db, key, *lease, *genesis, first, 5s); - CHECK(head && head->sequence == 1 && head->end_tick == 64 && head->commit == id(21)); - CHECK(failed(advance_region_head(*db, key, forged, *head, {id(22), digest(22), 65}, 5s), - LeaseStoreError::fenced)); - // Exact retry after an applied advance: mismatch, then the head proves it committed. - CHECK(failed(advance_region_head(*db, key, *lease, *genesis, first, 5s), - LeaseStoreError::head_mismatch)); - auto current = load_region_head(*db, key, 5s); - CHECK(current && *current == *head); - auto changed = *head; - changed.digest[31] ^= 1U; - CHECK(failed(advance_region_head(*db, key, *lease, changed, {id(22), digest(22), 65}, 5s), - LeaseStoreError::head_mismatch)); - CHECK(failed(advance_region_head(*db, key, *lease, *head, {id(22), digest(22), 64}, 5s), + const auto first = link(genesis, *lease, 21, 64); + auto head = publish(*db, first); + CHECK(head && head->head.sequence == 1 && head->head.end_tick == 64 && + head->head.commit == id(21)); + CHECK(failed(publish(*db, link(*head, forged, 22, 65)), LeaseStoreError::fenced)); + // Exact retry after an applied publication: mismatch, then the head proves it. + CHECK(failed(publish(*db, first), LeaseStoreError::head_mismatch)); + auto current = committed(*db, key); + CHECK(current.head == head->head && current.manifest == head->manifest); + auto changed = link(*head, *lease, 22, 65); + changed.predecessor_digest[31] ^= 1U; + CHECK(failed(publish(*db, changed), LeaseStoreError::head_mismatch)); + const std::array tick64{64}; + CHECK(failed(publish(*db, patched(link(*head, *lease, 22, 65), 120, tick64)), LeaseStoreError::invalid)); + auto other_quantum = link(*head, *lease, 22, 65); + other_quantum.tick_microseconds = 25000; // Fixed per region; changing it is a migration. + CHECK(failed(publish(*db, other_quantum), LeaseStoreError::unsupported)); + auto unretained = link(*head, *lease, 22, 65); + unretained.build = digest(0xB2); + CHECK(failed(publish(*db, unretained), LeaseStoreError::unsupported)); + auto future = link(*head, *lease, 22, 65); + future.versions.rules = 3; + CHECK(failed(publish(*db, future), LeaseStoreError::unsupported)); + // Commit IDs are globally unique: region 10's genesis ID cannot be reused here. + CHECK(failed(publish(*db, link(*head, *lease, 10, 65)), LeaseStoreError::commit_conflict)); CHECK(release_region_lease(*db, key, *lease, 5s)); CHECK(failed(release_region_lease(*db, key, *lease, 5s), LeaseStoreError::fenced)); CHECK(failed(renew_region_lease(*db, key, *lease, 20000ms, 5s), LeaseStoreError::fenced)); - CHECK(failed(advance_region_head(*db, key, *lease, *head, {id(22), digest(22), 65}, 5s), - LeaseStoreError::fenced)); + CHECK(failed(publish(*db, link(*head, *lease, 22, 65)), LeaseStoreError::fenced)); auto next = acquire_region_lease(*db, key, 20000ms, 5s); CHECK(next && next->epoch == 2 && next->holder != lease->holder); - auto final_head = advance_region_head(*db, key, *next, *head, {id(22), digest(22), 65}, 5s); - CHECK(final_head && final_head->sequence == 2); + auto final_head = publish(*db, link(*head, *next, 22, 65)); + CHECK(final_head && final_head->head.sequence == 2); } void database_time_expiry_and_paused_writer() { @@ -176,29 +240,23 @@ void database_time_expiry_and_paused_writer() { auto lease_a = acquire_region_lease(*worker_a, key, fast.duration, 5s); CHECK(lease_a && a.acquired(*lease_a, sent, LeaseClock::now())); CHECK(failed(acquire_region_lease(*worker_b, key, 20000ms, 5s), LeaseStoreError::busy)); - auto genesis = load_region_head(*worker_a, key, 5s); - CHECK(genesis); + const auto genesis = committed(*worker_a, key); std::this_thread::sleep_for(1200ms); // Worker A is paused past its lease. CHECK(a.state(LeaseClock::now()) == LeaseState::fenced); // Expiry is decided by database time; the successor acquires a newer epoch. auto lease_b = acquire_region_lease(*worker_b, key, 20000ms, 5s); CHECK(lease_b && lease_b->epoch == lease_a->epoch + 1); - auto head_b = - advance_region_head(*worker_b, key, *lease_b, *genesis, {id(31), digest(31), 3}, 5s); + auto head_b = publish(*worker_b, link(genesis, *lease_b, 31, 3)); CHECK(head_b); // A resumes and ignores its local fence: every database path rejects it. CHECK(failed(renew_region_lease(*worker_a, key, *lease_a, fast.duration, 5s), LeaseStoreError::fenced)); - CHECK( - failed(advance_region_head(*worker_a, key, *lease_a, *genesis, {id(32), digest(32), 1}, 5s), - LeaseStoreError::fenced)); - CHECK( - failed(advance_region_head(*worker_a, key, *lease_a, *head_b, {id(32), digest(32), 4}, 5s), - LeaseStoreError::fenced)); + CHECK(failed(publish(*worker_a, link(genesis, *lease_a, 32, 1)), LeaseStoreError::fenced)); + CHECK(failed(publish(*worker_a, link(*head_b, *lease_a, 32, 4)), LeaseStoreError::fenced)); CHECK(failed(release_region_lease(*worker_a, key, *lease_a, 5s), LeaseStoreError::fenced)); auto head = load_region_head(*worker_a, key, 5s); - CHECK(head && *head == *head_b); + CHECK(head && *head == head_b->head); // Expired renewal cannot revive a lease even without a successor. CHECK(release_region_lease(*worker_b, key, *lease_b, 5s)); @@ -216,24 +274,23 @@ void queued_writer_uses_post_lock_database_time() { const auto key = provision(*admin, 40); auto worker = runtime(); auto lease = acquire_region_lease(*worker, key, 1000ms, 5s); - auto genesis = load_region_head(*worker, key, 5s); - CHECK(lease && genesis); + CHECK(lease); + const auto genesis = committed(*worker, key); auto blocker = owner(); const std::array region{"40"}; CHECK(blocker->query("BEGIN", {}, 5s)); CHECK(blocker->query("SELECT 1 FROM evolution.region_leases WHERE world_id = 1 AND " "region_id = $1::evolution.u64 FOR UPDATE", region, 5s)); - std::expected queued = std::unexpected{LeaseStoreFailure{}}; - std::thread writer([&] { - queued = advance_region_head(*worker, key, *lease, *genesis, {id(41), digest(41), 1}, 5s); - }); + std::expected queued = + std::unexpected{LeaseStoreFailure{}}; + std::thread writer([&] { queued = publish(*worker, link(genesis, *lease, 41, 1)); }); std::this_thread::sleep_for(1300ms); CHECK(blocker->query("ROLLBACK", {}, 5s)); writer.join(); CHECK(failed(queued, LeaseStoreError::fenced)); auto head = load_region_head(*worker, key, 5s); - CHECK(head && *head == *genesis); + CHECK(head && *head == genesis.head); } // Partition: the renewal's outcome is unknown and the connection is gone. The @@ -300,10 +357,9 @@ void contenders_serialize_on_the_database() { // The same holder racing two commits from the same predecessor: exactly one wins. auto lease = acquire_region_lease(*workers[0], key, 20000ms, 5s); CHECK(lease); - auto head = load_region_head(*workers[0], key, 5s); - CHECK(head); + auto head = committed(*workers[0], key); for (std::uint8_t round = 0; round < 32; ++round) { - std::array, 2> results{ + std::array, 2> results{ std::unexpected{LeaseStoreFailure{}}, std::unexpected{LeaseStoreFailure{}}}; std::latch start{2}; std::vector threads; @@ -312,18 +368,17 @@ void contenders_serialize_on_the_database() { threads.emplace_back([&, i] { const auto seed = static_cast(100 + (round * 2) + i); start.arrive_and_wait(); - results[i] = advance_region_head(*workers[i], key, *lease, *head, - {id(seed), digest(seed), head->end_tick + 1}, 5s); + results[i] = publish(*workers[i], link(head, *lease, seed, head.head.end_tick + 1)); }); for (auto& t : threads) t.join(); const std::size_t w = results[0] ? 0 : 1; CHECK(results[w] && failed(results[1 - w], LeaseStoreError::head_mismatch)); - CHECK(results[w]->sequence == head->sequence + 1); + CHECK(results[w]->head.sequence == head.head.sequence + 1); head = *results[w]; } - auto committed = load_region_head(*workers[1], key, 5s); - CHECK(committed && *committed == *head && committed->sequence == 32); + auto last = load_region_head(*workers[1], key, 5s); + CHECK(last && *last == head.head && last->sequence == 32); } void exhaustion_fails_closed() { @@ -337,13 +392,24 @@ void exhaustion_fails_closed() { const auto other = provision(*admin, 71); auto lease = acquire_region_lease(*db, other, 20000ms, 5s); CHECK(lease); + // Owner-only fixture: a chain link at the last sequence (the head FK requires it). + CHECK(admin->query( + "INSERT INTO evolution.region_commits(world_id, region_id, commit_sequence, commit_id, " + "commit_digest, manifest, begin_tick, end_tick, published_epoch, tick_microseconds, " + "versions, build_identity, payload_bytes, payload_sha256) SELECT world_id, region_id, " + "18446744073709551615, '000000ff-0000-0000-0000-000000000000', commit_digest, manifest, 0, " + "5, 1, tick_microseconds, versions, build_identity, payload_bytes, payload_sha256 FROM " + "evolution.region_commits WHERE world_id = 1 AND region_id = 71", + {}, 5s)); CHECK(admin->query("UPDATE evolution.region_heads SET commit_sequence = 18446744073709551615, " - "end_tick = 5, published_epoch = 1 WHERE world_id = 1 AND region_id = 71", + "commit_id = '000000ff-0000-0000-0000-000000000000', end_tick = 5, " + "published_epoch = 1 WHERE world_id = 1 AND region_id = 71", {}, 5s)); - auto head = load_region_head(*db, other, 5s); - CHECK(head && head->sequence == 18446744073709551615ULL); - CHECK(failed(advance_region_head(*db, other, *lease, *head, {id(72), digest(72), 6}, 5s), - LeaseStoreError::exhausted)); + const auto last = committed(*db, other); + CHECK(last.head.sequence == 18446744073709551615ULL); + auto beyond = link(last, *lease, 72, 6); + beyond.sequence = 18446744073709551615ULL; // Any value: exhaustion is checked first. + CHECK(failed(publish(*db, beyond), LeaseStoreError::exhausted)); } struct Summary { @@ -372,8 +438,7 @@ void measure_round_trips() { auto db = runtime(); constexpr int n = 200; Summary acquire, renew, advance, release; - auto head = load_region_head(*db, key, 5s); - CHECK(head); + auto head = committed(*db, key); for (int i = 0; i < n; ++i) { std::expected lease = std::unexpected{LeaseStoreFailure{}}; acquire.samples.push_back( @@ -381,29 +446,27 @@ void measure_round_trips() { CHECK(lease); renew.samples.push_back( timed([&] { CHECK(renew_region_lease(*db, key, *lease, 20000ms, 5s)); })); - const auto seed = static_cast(i); - Uuid commit = id(seed); - commit[0] = 0xAA; // Distinct from genesis 0x50 bytes. - commit[1] = static_cast(i >> 8); + auto m = link(head, *lease, 0, head.head.end_tick + 64); + m.commit[0] = 0xAA; // Unique across all tests: 0xAA, index, zeros. + m.commit[1] = static_cast(i); advance.samples.push_back(timed([&] { - auto next = advance_region_head(*db, key, *lease, *head, - {commit, digest(seed), head->end_tick + 64}, 5s); + auto next = publish(*db, m); CHECK(next); - head = *next; + head = std::move(*next); })); release.samples.push_back( timed([&] { CHECK(release_region_lease(*db, key, *lease, 5s)); })); } acquire.print("acquire"); renew.print("renew"); - advance.print("advance_head"); + advance.print("publish_manifest"); release.print("release"); } } // namespace void run_region_lease_store_tests() { runtime_cannot_bypass_the_guard(); - acquire_renew_release_and_advance(); + acquire_renew_release_and_publish(); database_time_expiry_and_paused_writer(); queued_writer_uses_post_lock_database_time(); partitioned_renewal_fences_locally(); diff --git a/tools/ci/postgres-check.sh b/tools/ci/postgres-check.sh index 7a81d7e..4a8c7e0 100644 --- a/tools/ci/postgres-check.sh +++ b/tools/ci/postgres-check.sh @@ -37,13 +37,23 @@ if (export PGDATABASE=migration_rollback EVO_PG_RUNTIME_ROLE=no_such_evo_role; \ echo 'Expected missing runtime role rejection' >&2; exit 1 fi test "$(PGDATABASE=migration_rollback psql -XAtc "SELECT count(*) FROM pg_namespace WHERE nspname='evolution'")" = 0 -# Supported upgrade path: an existing exact v1 database migrates to v2. +# Supported upgrade path: an existing exact v1 database migrates to the latest. createdb upgrade_path PGDATABASE=upgrade_path psql -X -v ON_ERROR_STOP=1 -1 -v "migration_sha=$v1_sha" \ -f "$root/migrations/0001_region_bootstrap.sql" > /dev/null test "$(PGDATABASE=upgrade_path psql -XAtc "SELECT string_agg(version::text, ',') FROM evolution.schema_migrations")" = 1 PGDATABASE=upgrade_path bash "$root/tools/migrate-postgres.sh" -test "$(PGDATABASE=upgrade_path psql -XAtc "SELECT string_agg(version::text, ',' ORDER BY version) FROM evolution.schema_migrations")" = 1,2 +test "$(PGDATABASE=upgrade_path psql -XAtc "SELECT string_agg(version::text, ',' ORDER BY version) FROM evolution.schema_migrations")" = 1,2,3 +# v2 heads have no payload binding: v2->v3 fails closed and leaves history at v2. +v2_sha="$(sha256sum "$root/migrations/0002_region_fencing.sql")" +v2_sha="${v2_sha%% *}" +createdb v2_heads +PGDATABASE=v2_heads psql -X -v ON_ERROR_STOP=1 -1 -v "migration_sha=$v1_sha" -v "migration_sha_2=$v2_sha" -v runtime_role=evo_runtime_test -f "$root/migrations/0001_region_bootstrap.sql" -f "$root/migrations/0002_region_fencing.sql" > /dev/null +PGDATABASE=v2_heads psql -X -v ON_ERROR_STOP=1 -c "SELECT evolution.provision_region(1, 1, 1, gen_random_uuid(), decode(repeat('00', 32), 'hex'))" > /dev/null +if PGDATABASE=v2_heads bash "$root/tools/migrate-postgres.sh"; then + echo 'Expected v2 heads to block v3' >&2; exit 1 +fi +test "$(PGDATABASE=v2_heads psql -XAtc "SELECT string_agg(version::text, ',' ORDER BY version) FROM evolution.schema_migrations")" = 1,2 # Inherited privileges bypass fencing, so every migrate run audits effective rights. psql -X -v ON_ERROR_STOP=1 -c 'CREATE ROLE evo_bad_runtime NOLOGIN IN ROLE pg_write_all_data' if (export PGDATABASE=migration_rollback EVO_PG_RUNTIME_ROLE=evo_bad_runtime; \ @@ -72,13 +82,17 @@ expect_audit_failure 'GRANT UPDATE ON evolution.region_heads TO PUBLIC' \ expect_audit_failure 'GRANT EXECUTE ON FUNCTION evolution.check_region_lease(evolution.u64, evolution.u64, uuid, evolution.u64) TO evo_runtime_test' \ 'REVOKE EXECUTE ON FUNCTION evolution.check_region_lease(evolution.u64, evolution.u64, uuid, evolution.u64) FROM evo_runtime_test' expect_audit_failure 'ALTER ROLE evo_runtime_login CREATEDB' 'ALTER ROLE evo_runtime_login NOCREATEDB' +expect_audit_failure 'GRANT EXECUTE ON FUNCTION evolution.provision_region_checkpoint(bytea) TO evo_runtime_test' 'REVOKE EXECUTE ON FUNCTION evolution.provision_region_checkpoint(bytea) FROM evo_runtime_test' +expect_audit_failure 'GRANT SELECT ON evolution.region_commits TO evo_runtime_test' 'REVOKE SELECT ON evolution.region_commits FROM evo_runtime_test' bash "$root/tools/migrate-postgres.sh" # Restored configuration passes the audit again. # Unknown future versions and checksum drift must not be repaired silently. -psql -X -v ON_ERROR_STOP=1 -c 'UPDATE evolution.schema_migrations SET version=3 WHERE version=2' +psql -X -v ON_ERROR_STOP=1 -c 'UPDATE evolution.schema_migrations SET version=4 WHERE version=3' +if bash "$root/tools/migrate-postgres.sh"; then exit 1; fi +psql -X -v ON_ERROR_STOP=1 -c "UPDATE evolution.schema_migrations SET version=3 WHERE version=4" +psql -X -v ON_ERROR_STOP=1 -c "UPDATE evolution.schema_migrations SET sha256=repeat('0',64) WHERE version=3" if bash "$root/tools/migrate-postgres.sh"; then exit 1; fi -psql -X -v ON_ERROR_STOP=1 -c "UPDATE evolution.schema_migrations SET version=2 WHERE version=3" psql -X -v ON_ERROR_STOP=1 -c "UPDATE evolution.schema_migrations SET sha256=repeat('0',64) WHERE version=2" if bash "$root/tools/migrate-postgres.sh"; then exit 1; fi psql -X -v ON_ERROR_STOP=1 -c "UPDATE evolution.schema_migrations SET sha256=repeat('0',64)" if bash "$root/tools/migrate-postgres.sh"; then exit 1; fi -echo 'postgres migrations, rollback, constraints, permissions and fencing passed' +echo 'postgres migrations, rollback, constraints, permissions, fencing and checkpoints passed' diff --git a/tools/migrate-postgres.sh b/tools/migrate-postgres.sh index 964e101..585594a 100644 --- a/tools/migrate-postgres.sh +++ b/tools/migrate-postgres.sh @@ -16,6 +16,9 @@ digest="$(sha256sum "$root/migrations/0001_region_bootstrap.sql")" digest="${digest%% *}" digest_2="$(sha256sum "$root/migrations/0002_region_fencing.sql")" digest_2="${digest_2%% *}" +digest_3="$(sha256sum "$root/migrations/0003_region_checkpoints.sql")" +digest_3="${digest_3%% *}" psql -X --no-password --set=ON_ERROR_STOP=1 --set="migration_sha=$digest" \ - --set="migration_sha_2=$digest_2" --set="runtime_role=$runtime_role" \ + --set="migration_sha_2=$digest_2" --set="migration_sha_3=$digest_3" \ + --set="runtime_role=$runtime_role" \ --file="$root/migrations/apply.sql"