Complete M7.3 fenced region ownership

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

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

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-09-28 11:14:32 -04:00
co-authored by Claude Opus 5.5
parent 598b3938e6
commit 2496649a9b
22 changed files with 1501 additions and 29 deletions
+42 -13
View File
@@ -1,4 +1,4 @@
# PostgreSQL M7.2 bootstrap
# PostgreSQL bootstrap (M7.2) and region fencing (M7.3)
ADR-0059 pins server/libpq 18.6. `evo::postgres` is optional, Linux-only and separate
from all simulation targets. Preparation explicitly downloads a verified source
@@ -21,7 +21,9 @@ bash tools/ci/postgres-check.sh "$PWD/build/postgres/evo-postgres-tests"
```
The test script overrides all connection coordinates and creates a new private
0700 /tmp directory, private Unix socket and disposable local cluster. TCP is off;
0700 /tmp directory, private Unix socket and disposable local cluster. It creates
the `evo_runtime_test` group and the `evo_runtime_login` member, then runs fencing
tests as that real runtime login. TCP is off;
local trust applies only inside that private directory. Cluster stops on exit;
logs/data are retained there for diagnosis. It never uses production PG credentials
or deletes a pre-existing database. Do not point this script at a shared server.
@@ -49,18 +51,45 @@ incomplete session. No PostgreSQL diagnostic strings or connection values are lo
## Migrations and privilege boundary
`tools/migrate-postgres.sh` uses psql environment/service files, no URI arguments.
It requires exactly server18.6, serializes migrations with a transaction advisory
lock, hashes the checked-in SQL, and admits clean->v1 or exact v1->v1 only.
Unknown versions/checksum changes/partial foreign schemas fail closed. No down
migration or destructive repair exists. The u64 domain rejects fractional,
negative and above-u64 values without signed truncation.
It requires exactly server 18.6 and serializes migrations with a transaction
advisory lock. It hashes each checked-in SQL file and applies everything in one
transaction. The recorded history must be an exact prefix: clean->v1->v2, v1->v2,
or a v2 no-op. Unknown versions, checksum changes and partial foreign schemas fail
closed. There is no down migration or destructive repair. The u64 domain rejects
fractional, negative and above-u64 values without signed truncation.
Use a dedicated owner/migrator login with CREATE on the database. Runtime login
must be separate, not a member of the owner and without database CREATE or public
schema CREATE. Bootstrap revokes PUBLIC access to its schema/tables and default
function execution. Runtime has no direct mutation rights; M7.3 adds fenced
functions and narrowly scoped EXECUTE. Operators own database/role provisioning;
the migration never creates login passwords or grants superuser.
Use a dedicated owner/migrator login with CREATE on the database. Before
migrating, operators create a NOLOGIN runtime group role and pass its name as
`EVO_PG_RUNTIME_ROLE`. The migration refuses a role that is missing, is the owner,
inherits the owner, or has superuser/CREATEROLE/CREATEDB/replication/BYPASSRLS. The
runtime login is a separate member of that group only, with no database CREATE or
public schema CREATE. Bootstrap revokes PUBLIC access to the schema, tables and
default function execution. Operators own database/role provisioning; the migration
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
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`.
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.
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
local deadline runs from request send time on CLOCK_BOOTTIME. If a renewal outcome
is unknown, keep the earlier deadline and reconnect. Once fenced, stop admission,
simulation and output, then acquire a new epoch and recover. Never resume the old
epoch.
## Kubernetes Secrets