Switch the engineering client to M10 sessions (M10.5c)
Foundation / checks (checks) (push) Successful in 32m47s
Foundation / checks (client) (push) Failing after 10m1s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m53s
Foundation / checks (network) (push) Successful in 11m18s
Foundation / checks (postgres) (push) Successful in 40m20s
Foundation / checks (tsan) (push) Successful in 7m46s
Foundation / postgres-tools (push) Skipped
Foundation / image (push) Skipped
Foundation / server-image (push) Skipped

evo-client's remote mode now runs over RegionSessionClient (QUIC, session
v2): snapshot-fed environment and organism views, the camera following the
server's view until the user moves it and then driving the interest, intention
records with a simulated state, and reconnects with the next grant of a bundle.
The launcher reads 160-byte M10 grants and defaults to the dev route.

- quic::resolve_ipv4 shared by the client and evo-session-probe
- evo-session-probe grants: owner-only bundles of 1-64 grants
- evo-server --m10-max-grant-lifetime (dev only, 60..3600 s)
- presets client-network/client-package build QUIC; msquic links the CRT
  fully static; msquic.dll and msquic/OpenSSL licences in the Windows package
- client-remote-session test against a loopback region
- ADR-0093/0091/0086 amendments, M10_CLIENT_SESSIONS guide, validation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-06 11:57:07 -04:00
co-authored by Claude Opus 5.5
parent 33e91458e7
commit 1819ebc0ab
35 changed files with 1119 additions and 270 deletions
+4 -4
View File
@@ -524,10 +524,10 @@ session control done; 10.3b QUIC session login (schemas/network/session-v1.md) d
10.3c durable per-world account control (schema v10) done. 10.4 split (ADR-0092):
10.4a intention/action protocol and admission done; 10.4b durable action records
(schema v11, same transaction as the checkpoint) done; 10.4c evo-server QUIC listener and
headless client with process kill tests done. The engineering GUI client still uses the
M9 dev path. 10.5 split (ADR-0093): 10.5a session protocol v2 and the replication core
done; 10.5b wiring (sessions, evo-server, client, probe) with process evidence done; 10.5c
the GUI client switch follows.
headless client with process kill tests done. 10.5 split (ADR-0093): 10.5a session
protocol v2 and the replication core done; 10.5b wiring (sessions, evo-server, client,
probe) with process evidence done; 10.5c engineering client switched to M10 sessions
(snapshot views, camera interest, grant bundles, msquic.dll in the Windows package) done.
10.6-10.9 planned.
**Entry:** M9 client/session evidence and M7/M8 dev/stage durability. Read
+6 -3
View File
@@ -35,8 +35,7 @@ from the durable record after crashes before or after a commit, unknown publicat
cross-region moves. M10.4c adds the opt-in
evo-server QUIC listener (session control and action records under the host's lease) and
the headless `evo-session-probe`, with real-process tests including SIGKILL before and after
an action's commit. M10.4 is complete; the GUI client still uses the M9 dev path. Next:
M10.5 bounded snapshots and spatial interest.
an action's commit. M10.4 is complete. Next: M10.5 bounded snapshots and spatial interest.
Deployment (2026-10-05): the maintainer deployed the M10 QUIC listener to evolution-dev
behind the ADR-0087 route; session protocol v1 is therefore frozen. The route admitted
only TCP 7400 while QUIC is UDP, so it is changed to UDP 7400 (ADR-0087 amendment). The
@@ -48,7 +47,11 @@ entity deltas against the acknowledged baseline, nearest first within 16 KiB per
a slower distant tier, datagram chunks and client assembly. M10.5b wires it end to end:
evo-server replicates the region's environment for each session's interest (default: the
first habitat site), the client assembles and acknowledges snapshots, and the probe prints
them. Next: the GUI client switch (10.5c).
them. M10.5c switches the engineering client to M10 sessions: snapshot-fed views, the camera
driving the interest after the user moves it, grant bundles (`evo-session-probe grants`,
evo-server `--m10-max-grant-lifetime` for dev), and `msquic.dll` in the Windows package.
M10.5 is complete. Deploying the v2 server to evolution-dev (the dev server still runs v1)
is a maintainer step. Next: M10.6 movement prediction and reconciliation.
## Previous gate - 2026-10-02
+2
View File
@@ -1,6 +1,8 @@
# ADR-0083: Dev region sessions, no-effect intentions and the session drill
## Status
The engineering client's remote mode moved to M10 sessions in M10.5c (ADR-0093); this
ADR's server path and `evo-dev-session` remain for their own tests.
Listener/Service rule narrowly superseded for evolution-dev by ADR-0087 (dev session
route), effective only when that route is enabled; until then this ADR applies as is.
Accepted for M9.7 (engineering client to one authoritative **dev** region). Decisions
+13
View File
@@ -51,3 +51,16 @@ Static runtime: each image has its own CRT state; SDL's C API passes no CRT obje
across the DLL boundary. Package and verification scripts change with the file
list. Clean-machine/VM runs and minimum hardware remain M9.8g qualification.
The notice inventory is an engineering record, not a legal review.
## Amendment (M10.5c, 2026-10-06): msquic.dll
- The package adds `msquic.dll` (msquic 2.6.2, MIT, with OpenSSL 3.5.9 built static inside,
Apache-2.0; pins and sources as in ADR-0090) and `LICENSES/msquic.txt` and
`LICENSES/OpenSSL.txt`, copied from the verified sources. BUILD-INFO lists both pins.
- msquic links the whole C runtime statically (`QUIC_STATIC_LINK_PARTIAL_CRT=OFF`; its
default imported the UCRT forwarders). Allowed imports add `msquic.dll` and the system
DLLs it needs: `crypt32`, `iphlpapi`, `ncrypt`, `ntdll`. All three images are checked.
- Determinism: OpenSSL is built by msquic with nmake, outside CMake's `/Brepro`; the package
script sets `CL=/Brepro` (cl.exe reads options from it) and `SOURCE_DATE_EPOCH` (the
commit time, used by OpenSSL's build-date string) for the build.
- The package CTest run adds the label `quic-session` (QUIC session and client remote
session tests).
@@ -133,3 +133,18 @@ only through `claim_account_control`, `renew_account_control` and
by a later migration when organisms arrive, under the same row and fencing.
- Not yet wired into evo-server or the engineering client (both keep the M9 dev path);
that integration comes with 10.4, so nothing deploys M10 sessions yet.
## Amendment (M10.5c, 2026-10-06): grant bundles and a dev grant lifetime
- **Bundles.** `evo-session-probe grants` signs 1-64 grants for one account in one file
(concatenated 160-byte grants, created new, owner-only), all issued now with consecutive
serials. Without `--serial` the first serial is 64 x the issue time in seconds, so a later
bundle for the account supersedes an earlier one without bookkeeping. The issuer key stays
with the operator; testers receive only the bundle and the dev CA. Grants cannot be dated
ahead (clock skew 30 s), so a bundle expires as a whole.
- **Lifetime.** The 300 s maximum would make a bundle unusable after five minutes. The
evo-server flag `--m10-max-grant-lifetime 60..3600` raises the region's maximum, refused
at startup outside `dev`; without it the 300 s default stands. A session ends when its
grant expires; the client then reconnects with the next grant of the bundle, which
succeeds only while that grant is still valid.
- Not changed: World0/stage issuance (no production identity provider yet), refresh within
a session, durable serial rules.
@@ -81,3 +81,32 @@ are ignored; malformed records, a slice mismatch or disagreeing chunk headers ar
- Evidence: the test region's default interest holds one habitat site, so the process test
shows a one-cell view refreshed every tick (40 chunks, 8,888 bytes in 40 ticks); the
225-cell and 32-session figures come from synthetic sources.
## M10.5c engineering client switch (2026-10-06)
- **Remote mode is M10 only.** `evo-client` builds its remote mode with `EVO_BUILD_QUIC`
(presets `client-network` and `client-package` now enable it) over `RegionSessionClient`;
the M9.7 TCP session path is no longer used by the GUI (`evo-dev-session` and the M9
server path keep their own tests). The launcher reads 160-byte M10 grants and defaults to
the dev route `void.aeternalisgames.com:7400` (ADR-0087); the endpoint is looked up once
(IPv4) when Connect is pressed.
- **One connection per grant.** A lost or closed session reconnects with the bundle's next
grant after a pause that grows from 2 s to 30 s and resets on Welcome (inside the
per-account attempt limit). Shutdown or capacity: retry. Refusals before any Welcome
(scope, signature, stale or expired grant) fail the launcher; `superseded` (another client
opened a session with a newer grant for the account) fails it at once instead of fighting
back; no grant left fails it as exhausted. A new epoch resets the views.
- **Views.** The newest applied snapshot feeds the environment and organism layers; a lost
session marks them stale. The camera follows the server's default view (re-centred on
its square while it fills in, nearest cells first) until the user pans or zooms; from then
on the camera centre's voxel, radius 7, in the snapshot's slice is the interest, sent at
most every 250 ms and again after each reconnect.
- **Intentions.** Sent as datagrams for server tick + 2 when the movement vector changes,
at most once per server tick. The Session panel's record shows sent, admitted, rejected,
**simulated** (the watermark covered it: final, never durable, ADR-0092) and unknown
(the session ended first). Entries are numbered by the client, since session sequences
restart with each session. The panel also shows the simulated watermark, the snapshot
(tick, cells, organisms), the interest and snapshot bytes.
- Evidence: `client-remote-session` drives `apps/evo-client/remote_session.hpp` against a
loopback region (launcher flow, 225-cell default view, following and the camera interest,
admitted then simulated intentions, epoch change with unknown outcomes and reconnect with
the next grant, superseded, wrong region, exhausted bundle, unresolvable endpoint).
+7 -6
View File
@@ -8,21 +8,22 @@ Contract: [client architecture](../architecture/CLIENT_ARCHITECTURE.md), ADR-007
Camera/input: [contracts and limits](CAMERA_INPUT.md), ADR-0079.
Environment: [presentation and encodings](ENVIRONMENT_RENDERING.md), ADR-0080.
Organisms/inspector: [encodings and budget](ORGANISM_RENDERING.md), ADR-0081.
Remote dev region: [operations](../networking/DEV_SESSION_OPERATIONS.md), ADR-0083.
Remote dev region: [M10 client sessions](../networking/M10_CLIENT_SESSIONS.md), ADR-0093
(the M9.7 path, ADR-0083, is no longer used by the client).
Engineering panels and launcher: [UI state](CLIENT_UI_STATE.md), ADR-0084.
Without arguments a launcher opens. **Local fixture** is labelled as an in-memory
stand-in, never as a server or ecosystem. **Connect** (preset `client-network`)
reads the endpoint, server name, dev CA file and grant bundle file when pressed;
stand-in, never as a server or ecosystem. **Connect** (preset `client-network`, with QUIC)
reads the endpoint, server name, dev CA file and M10 grant bundle file when pressed;
nothing is saved and no path, certificate or grant byte is shown or logged. Errors
use fixed wording. A connection with no Welcome after three failed attempts
(refused, TLS failure or timeout) or a refused grant fails with Retry/Cancel.
`--fixture` or `--connect HOST:PORT --server-name NAME --ca FILE --grants FILE`
skip the launcher (an unreadable file then exits 1). While running, a banner names
the mode (LOCAL FIXTURE or DEV REGION with its phase); Disconnect asks for
confirmation. The Session panel shows session/epoch, server tick, durable
watermark, grants left and the last ten intentions with their outcome (sent,
admitted, rejected, durable, not committed, unknown). That list is the record;
confirmation. The Session panel shows session/epoch, server tick, simulated
watermark, grants left, the snapshot, interest and snapshot bytes, and the last ten
intentions with their outcome (sent, admitted, rejected, simulated, unknown; M10.5c). That list is the record;
short notifications expire and can be dismissed.
## Build and run
+9 -7
View File
@@ -1,9 +1,10 @@
# Windows client package (M9.8e)
Decision: [ADR-0086](../adr/0086-windows-client-package.md). Windows development host
only; requires Visual Studio 2022 C++ tools and prepared SDL, Dear ImGui and Mbed TLS
sources (`cmake -P tools/prepare-sdl3.cmake`, `prepare-imgui.cmake`,
`prepare-mbedtls.cmake`).
only; requires Visual Studio 2022 C++ tools and prepared SDL, Dear ImGui, Mbed TLS and
msquic sources (`cmake -P tools/prepare-sdl3.cmake`, `prepare-imgui.cmake`,
`prepare-mbedtls.cmake`, `prepare-msquic.cmake`), plus Strawberry Perl and NASM for
msquic's OpenSSL build (ADR-0090).
## Build a package
@@ -13,15 +14,15 @@ powershell -NoProfile -ExecutionPolicy Bypass -File tools\client\package-windows
It refuses uncommitted tracked changes (`-AllowDirty` packages them with a `-dirty`
identity), configures `client-package` with `EVO_BUILD_IDENTITY=g<12 hex>`, builds,
runs the client/network CTest suite, stages the allowlisted files and writes
runs the client/network/quic-session CTest suite, stages the allowlisted files and writes
`build/packages/evo-client-windows-x64-<identity>.zip` and `.zip.sha256`. The staged
folder stays next to the ZIP. `-Clean` deletes `build/client-package` first; the
build log is `build/client-package.log` (+ `.err`).
Package content (exact): `evo-client.exe`, `SDL3.dll`, `README.txt`,
Package content (exact): `evo-client.exe`, `SDL3.dll`, `msquic.dll`, `README.txt`,
`BUILD-INFO.txt`, `THIRD-PARTY-NOTICES.txt`, `SHA256SUMS.txt` and `LICENSES/`
(SDL3, its HIDAPI, yuv2rgb, stb_image and Khronos notices, Apache-2.0, Mbed TLS,
Dear ImGui with fonts and stb notices). The tester README template is
Dear ImGui with fonts and stb notices, msquic, OpenSSL). The tester README template is
`tools/client/README-package.txt`; the notice index is
`tools/client/THIRD-PARTY-NOTICES.txt`. No credentials, grant bundles, CA files or
settings are ever packaged; dev CA and grants are issued to testers separately.
@@ -34,7 +35,8 @@ powershell -NoProfile -ExecutionPolicy Bypass -File tools\client\package-selftes
```
Verification works without Visual Studio (copy `tools/client` with the ZIP): digest,
exact content and SHA256SUMS, PE imports limited to system DLLs plus `SDL3.dll`,
exact content and SHA256SUMS, PE imports of all three images limited to system DLLs plus
`SDL3.dll` and `msquic.dll` (no C runtime DLLs),
credential and profile-path scan, then the extracted client runs with only the
Windows system directories on PATH. `-Interactive` opens a real window for 3 s.
The self-test proves each guard refuses its defect.
+73
View File
@@ -4406,3 +4406,76 @@ tests; clang-tidy 19 on sessions, client, replication, bridge, probe and tests;
checked). The repository format check fails only on `include/evo/server/session_window.hpp`
(already on main, not part of this change).
Not done: the GUI client (10.5c); deployment of v2 (the dev server still runs v1).
## 2026-10-06 — M10.5c engineering client on M10 sessions (ADR-0093, ADR-0091, ADR-0086)
Implemented the client's remote mode over `RegionSessionClient`
(`apps/evo-client/remote_session.hpp`):
- snapshot-fed views;
- the camera follows the default view, then drives the interest;
- intention record states, including `simulated`;
- reconnect with the bundle's next grant, with a growing pause.
Supporting changes:
- the launcher reads 160-byte grants, takes `authority_path`, and defaults to the dev route;
- `quic::resolve_ipv4`;
- `evo-session-probe grants`;
- evo-server `--m10-max-grant-lifetime` (dev only);
- presets `client-network` and `client-package` with QUIC;
- msquic with a fully static CRT;
- `msquic.dll` and the msquic and OpenSSL licences in the Windows package;
- `CL=/Brepro` and `SOURCE_DATE_EPOCH` for the package's OpenSSL build.
New test `client-remote-session` (labels client and quic-session) runs against a loopback
region:
- launcher flow and the 225-cell default view;
- following, then the camera interest (144 cells clipped);
- admitted then simulated intentions;
- an epoch change: unknown outcomes, stale views, reconnect with the next grant and the
views restored;
- client-side numbering across sessions;
- superseded, wrong region, an exhausted bundle, and an unresolvable endpoint.
The process test now runs evo-server with `--m10-max-grant-lifetime 900` and the probe with
a 900 s grant.
Found during development:
- test cells requesting water without moisture (the client refused the snapshot and closed);
- a budget-cut first snapshot skewed a one-time recentre, so the camera now follows until
the user moves it;
- session sequences collided in the outcome record, so the record now numbers entries
itself;
- msquic's default partial-static CRT imported the UCRT forwarders;
- a clang-tidy optional-access finding.
Executed:
- **Linux GCC 14**
- preset `client-network` (with QUIC): CTest 14/14; `client-remote-session` passed 5 times
in a row;
- preset `quic`: 4/4;
- `postgres-check.sh` with EVO_BUILD_QUIC: 20 suites, including the region m10 session
integration.
- **Linux Clang 19:** clang-tidy 19 on the client app, remote test, host lookup, probe,
launcher and UI-model test; clang-format 19 on the changed files.
- **Windows MSVC 19.44** (binaries rebuilt, timestamps checked):
- preset `client-network`: 12/12;
- preset `quic`: 4/4.
- **Windows package:**
- `package-windows.ps1`: client-package CTest 12/12;
- `verify-windows-package.ps1` passed;
- `package-selftest.ps1`: 10 refusals, including the missing `msquic.dll` and the
dynamic-runtime image;
- `msquic.dll` imports only advapi32, bcrypt, crypt32, iphlpapi, kernel32, ncrypt, ntdll,
user32, winmm and ws2_32;
- two `-Clean` builds gave identical ZIPs (sha256 `aaabc228…312cb2`, identity
`g33e91458e7ee-dirty`), the same as the earlier incremental build.
- `evo-session-probe grants`, checked by hand:
- 8 grants, 1280 bytes, mode 0600;
- refuses an existing file, a lifetime under 60 s, a count over 64 and connect flags;
- `--serial` respected.
Not done:
- a GUI run against evolution-dev (the dev server still runs session v1 and the flag is
not in the dev manifest);
- ASan of the client remote test (msquic under sanitizers is still open);
- a clean-VM package run.
+39
View File
@@ -0,0 +1,39 @@
# Engineering client over M10 sessions (M10.5c)
Decisions: ADR-0091 (grants, bundles, grant lifetime), ADR-0092 (intentions), ADR-0093
(snapshots, interest, client behaviour), ADR-0087 (dev route). **evolution-dev only.**
## Operator: issue a grant bundle
On a machine that holds the dev issuer key (never give the key to testers):
```sh
evo-session-probe grants --issuer-key issuer.key --world 100 --frame 9 --region 1 \
--account <32 hex digits, one per tester> --count 16 --lifetime 3600 --out tester.grants
```
The file is created new and owner-only; it holds 16 single-use grants, valid together for
the lifetime. A lifetime above 300 s needs the region to run with
`--m10-max-grant-lifetime` at least that long (dev only); otherwise every grant is refused.
Issue a new bundle (same account; newer serials are automatic) when one runs out or
expires. Give the tester the bundle and the public dev CA (`dev-ca.pem`).
## Tester: connect
Run `evo-client`, choose **Connect to a dev region** and fill in the endpoint (default
`void.aeternalisgames.com:7400`, UDP; reachable only from 172.10.1.0/24), the server name
on the dev certificate, `dev-ca.pem` and the bundle. Or:
```sh
evo-client --connect void.aeternalisgames.com:7400 --server-name NAME --ca dev-ca.pem \
--grants tester.grants
```
- The view follows the region's default view until you pan or zoom; then the 15 x 15
cells around the camera centre are replicated (radius 7).
- W A S D send movement intentions; the Session panel lists each as sent, admitted,
rejected, simulated (final; intentions are never durable) or unknown.
- Each reconnect uses the next grant. A second client with a bundle for the same account
takes the session over; the first stops (do not share bundles).
- A server still on session protocol v1 refuses the client (`unsupported_version`):
deploy the v2 server first.