Wire M10.8c-1 region handoff: protocol v4, durable probes, crossing, ghosts
Foundation / checks (deploy) (push) Successful in 3m29s
Foundation / checks (ecs) (push) Successful in 2m0s
Foundation / checks (client) (push) Successful in 12m51s
Foundation / checks (network) (push) Successful in 13m0s
Foundation / checks (tsan) (push) Successful in 7m50s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 32m4s
Foundation / checks (postgres) (push) Canceled after 19m13s

ADR-0096. Session protocol v4 (v3 is deployed and frozen) adds HandoffOffer,
SessionRedirect, close reasons handed_off and moved, and ghost marker records.
Sessions use the durable probe record: logins open it where it was saved
(redirected when it lives elsewhere), and session ends save it. A marker
crossing into a neighbour's area is frozen, prepared, its control released
and a signed ticket offered; uncommitted transfers are aborted after the
ticket's lifetime. The destination shows arriving probes as ghosts (schema
v13 incoming_probe_transfers) and opens the marker where it crossed.

Refreshes the dev session window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-06 21:24:42 -04:00
co-authored by Claude Opus 5.5
parent 97a3756e46
commit a7a3d12283
39 changed files with 1315 additions and 68 deletions
+3 -2
View File
@@ -536,8 +536,9 @@ remote-marker interpolation and fractional prediction done; 10.7b client wiring,
view and two-client interpolation traces done. 10.8 split (ADR-0096, the persistence
handoff ADR; EXPERIMENT durable probe records): 10.8a schema v12 probe records and the
transfer state machine with a PostgreSQL fault matrix done; 10.8b signed handoff tickets and
ticket admission (durable stage, commit and control move) done; 10.8c region wiring and 10.8d
two-process kill tests follow. 10.9 planned.
ticket admission (durable stage, commit and control move) done; 10.8c-1 session protocol v4,
durable probes in sessions, edge crossing, ghosts (schema v13) and a two-region loopback test
done; 10.8c-2 client switch and server configuration, 10.8d two-process kill tests follow. 10.9 planned.
**Entry:** M9 client/session evidence and M7/M8 dev/stage durability. Read
NETWORK_ARCHITECTURE, PERSISTENCE_ARCHITECTURE and ADR-0017. The M9 transport is
+9 -1
View File
@@ -76,7 +76,15 @@ Deploying v12 needs a rebuilt migrations image. M10.8b adds signed handoff ticke
region's key signs one transfer for one account and destination; the ticket rides the Hello
grant slot and is verified against the neighbour keys registered here. The destination then
durably stages and commits the transfer and takes the account's control before admitting
the session. Next: 10.8c region wiring (edge crossing, ghost, client switch).
the session. M10.8c-1 wires the regions:
- session protocol v4 (handoff offer, redirect, ghosts; v3 is deployed and frozen);
- sessions use the durable probe: opened where it was saved, redirected when it lives
elsewhere;
- a marker crossing into a neighbour's area is frozen, prepared and offered with a ticket;
- the destination shows arriving probes as ghosts (schema v13) and opens the marker where it
crossed.
Next: 10.8c-2, the client switch and server configuration.
## Previous gate - 2026-10-02
+44
View File
@@ -143,3 +143,47 @@ controllable before M11.
`capacity`.
- Not yet: the source side (freeze at the edge, prepare, release control, offer the ticket),
the client switch, keys in evo-server and the dev tool (10.8c).
## M10.8c-1 region wiring (2026-10-06)
- **Session protocol v4** ([session-v4](../../schemas/network/session-v4.md); v3 was deployed
and is frozen) adds:
- `HandoffOffer` (transfer id, destination address, ticket);
- `SessionRedirect` (where the probe is, before Welcome);
- close reasons `handed_off` and `moved`;
- marker kind 2 (ghost).
- **Durable probes in sessions** (`ProbeLedger`, `include/evo/server/probe_ledger.hpp`).
- A grant login opens the account's probe record after the durable control claim.
- Owned here and active: the marker opens at its saved position, clamped into this
region's area, so a probe left beyond the edge by an aborted handoff does not cross
again at once.
- Owned elsewhere: Redirect (when that region is a known neighbour), then `moved`.
- Frozen: `capacity` (retry once the transfer is decided).
- The position is saved at session end, but not after a handoff.
- **Neighbours.** A region owns its area; markers move within the bounding box of its area
and its neighbours'. Every poll, a marker that left the area into a neighbour's area is
frozen and its transfer prepared. Then the session's control is released, a ticket is
signed (lifetime 30 s; its session expiry is the session's), the HandoffOffer sent, and
the session closed with `handed_off`. Anywhere else, the marker is put back at the edge.
An outgoing transfer not committed within its ticket's lifetime plus 5 s is aborted (the
probe resumes here); undecided aborts retry.
- **Destination.** The ticket admission now returns the probe's state after the switch
(`HandoffAdmission`), and the marker opens there. Every second (configurable) the region
reads the open transfers addressed to it (schema v13 `incoming_probe_transfers`) and shows
them as ghosts: stable ids per transfer, read-only, replicated to sessions whose square
holds them, and gone once decided.
- **Configuration.** Handoffs need probe records, this region's handoff key and neighbours. A
handoff key without probe records is a configuration error.
- **Evidence.** `two_region_handoff` (`tests/quic_sessions.cpp`): two regions with adjacent
areas in one process, over a fake world database with the v12 state machine. It covers:
- a crossing at the border;
- a ghost seen by another client at the destination before the switch;
- the ticket login (owner and generation moved, marker where it crossed);
- the ghost giving way;
- a redirect at the old region;
- a crossing back;
- an abandoned handoff aborted after its deadline, with the probe resumed at the edge and
the late ticket refused as expired.
It passed 3 times in a row on Linux and also passes on Windows.
- Not yet: the engineering client's switch (offer, redirect, multi-region grants),
evo-server and probe configuration (10.8c-2), and real processes on PostgreSQL (10.8d).
+56
View File
@@ -4767,3 +4767,59 @@ Executed:
Not done:
- the source side and the client switch (10.8c);
- two-process kill tests (10.8d).
## 2026-10-06 — M10.8c-1 region handoff wiring (ADR-0096)
Implemented:
- session protocol v4 (HandoffOffer, SessionRedirect, `handed_off` and `moved`, ghost marker
kind; v1-v3 refused);
- the client library keeps offers and redirects;
- `ProbeLedger` (durable open, save, prepare, abort, incoming) and the PostgreSQL version;
- `HandoffAdmission` (state after the switch);
- `RegionSessions`:
- neighbours and the movement area;
- crossing detection, freeze, prepare, control release, a signed ticket, the offer and the
close;
- timed aborts and ghost polling;
- logins placing the durable probe (clamped into the area), with a redirect or `moved`
when it is owned elsewhere;
- saves at session end;
- `ProbeMarkers` `open_at`, `place`, `freeze` and ghosts;
- schema v13 `incoming_probe_transfers` (apply chain, audit, CI checks);
- client ghost drawing.
Found and fixed during development:
- a dangling marker pointer after clamping (two `place` calls);
- the spawn computed from the area instead of the configured one;
- a probe left beyond the edge by an aborted handoff crossing again at login (now clamped).
Tests:
- codec tests for the offer and redirect (round trip, text and padding rules, zero region or
transfer, lengths), with the v4 version, type and reason boundaries;
- ghosts and freezing through replication;
- `two_region_handoff` (two regions in one process over a fake world database):
- a crossing; a ghost at the destination before the switch;
- a ticket login at the crossing position (owner and generation moved); the ghost gone;
- a redirect; a crossing back;
- an abandoned handoff aborted after its deadline, the probe resumed at the edge, and the
late ticket refused;
- PostgreSQL: incoming transfers appear for the destination only while open.
Executed:
- **Linux GCC 14:**
- `postgres-check.sh` with QUIC: 21 suites (migrations to v13; races 8 commits, 16
aborts);
- presets `quic` 4/4 and `client-network` 16/16;
- `evo-quic-session-tests` 3 times in a row.
- **Linux Clang 19:** ASan/UBSan `evo-network-tests`; clang-tidy 19 on the protocol, motion,
replication, interpolation, client, region-sessions, handoff-ledger, store and test sources
(findings fixed); clang-format 19.
- **Windows MSVC 19.44:** presets `quic` 4/4 and `client-network` 14/14.
Not done:
- the engineering client's handling of offers, redirects and multi-region grants, and
evo-server and probe configuration (10.8c-2);
- real processes (10.8d).
Deployed v3 servers refuse v4 clients until redeployed; v12 and v13 need a rebuilt
migrations image.
+4 -2
View File
@@ -216,8 +216,10 @@ returns the recorded outcome. SQLSTATEs:
Lock order: upgrade lock (shared), own region lease row, probe record, transfer;
`handoff_account_control` reads the transfer, then locks the account control row. The
privilege audit covers all eight functions, and the tables are owner-only. Deploying v12
needs a rebuilt migrations (tools) image.
privilege audit covers all eight functions, and the tables are owner-only. Schema v13 adds
`incoming_probe_transfers`, a read-only function under the lease that lists the open
transfers addressed to the caller's region (for ghosts). Deploying v12 and v13 needs a
rebuilt migrations (tools) image.
## Host lease discipline