Add M9.8f dev session route design, disabled with fail-closed policy

ADR-0087 records the maintainer's route (void.aeternalisgames.com:7400 via a
dedicated internal MetalLB VIP to the evolution-dev region pod, TLS end to end,
CIDR-limited) and operator-opened windows enforced by evo-server. The route is a
kustomize component included nowhere; the policy check encodes its shape and
refuses enabling until VIP/CIDR, the dev quota and --session-window exist, with a
20-case self-test in the CI deploy stage. The base listener stays loopback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-02 17:34:12 -04:00
co-authored by Claude Opus 5.5
parent 2a2d6fbbfe
commit 9f622cf6b3
18 changed files with 504 additions and 24 deletions
+2 -1
View File
@@ -458,7 +458,8 @@ terrain meshing or procedural creature animation is required.
M9.8b adds bounded UI state, protected external input capture and bounded session
event delivery. M9.8c integrates the launcher, legend, labelled inspector, click
selection and session panel. M9.8d adds rebindable controls (ADR-0085). M9.8e
packages a local Windows x64 ZIP (ADR-0086). ADR-0084 records the toolkit scopes.
packages a local Windows x64 ZIP (ADR-0086). M9.8f designs the dev session route,
committed disabled (ADR-0087). ADR-0084 records the toolkit scopes.
**M9.8 planning (2026-10-02):** user-confirmed Windows ZIP, temporary Gitea Actions
artifacts, labelled engineering UI/launcher and control rebinding. See the
+5 -2
View File
@@ -10,10 +10,13 @@ bounded errors, Retry/Cancel), legend, labelled inspector, click selection, sess
panel with the intention outcome record, and visible notifications/dialog. M9.8d
adds rebindable controls (ADR-0085) with conflict checks and a validated file. M9.8e
builds a static-runtime Windows x64 ZIP locally with notices, identity, checksums and
credential guards (ADR-0086); Actions publication needs a Windows runner. Tests,
credential guards (ADR-0086); Actions publication needs a Windows runner. M9.8f
designs the dev session route (ADR-0087), committed disabled with fail-closed policy
tests; nothing was applied to the cluster. Tests,
visual review and limits are recorded in engineering/VALIDATION.md.
Next: M9.8f dev TCP route design, then M9.8g qualification on the low-spec VM.
Next: server-enforced session windows and the route inputs (VIP, CIDR, DNS) to enable
ADR-0087, and M9.8g qualification on the low-spec VM.
Windows packages will be built locally until a Windows runner exists. Testing is internal; 172.10.1.160 is the
RKE2 control-plane address. VM qualification and the cluster restart drill remain
outstanding, as agreed. See engineering/M9_8_DELIVERY_PLAN.md.
+2
View File
@@ -1,6 +1,8 @@
# ADR-0069: Environment isolation and World0 protection
## Status
ADR-0087 allows exactly one LoadBalancer Service, in evolution-dev only, for the dev
session route once enabled; node ports stay forbidden and stage/World0 are unchanged.
Accepted for M8.2, 2026-09-29. It builds on the M8.1 inventory
(infrastructure/INVENTORY.md), ADR-0020 (delivery), and OPERATIONS.md (World0
protection). Nothing here deploys a world; World0 launch stays gated by M8.8.
+2
View File
@@ -1,6 +1,8 @@
# ADR-0083: Dev region sessions, no-effect intentions and the session drill
## Status
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
confirmed with the maintainer on 2026-10-01: durable no-effect intentions, an
explicitly empty organism presentation, local real-process evidence plus a dev
+89
View File
@@ -0,0 +1,89 @@
# ADR-0087: Dev session route and operator-opened session windows
## Status
Accepted for M9.8f as design (2026-10-02), evolution-dev only. The route is committed
**disabled**; nothing was applied to the cluster. Enabling it is blocked by policy until
the inputs and server-side window enforcement below exist. Narrowly supersedes
ADR-0083 (loopback-only listener, never a Service) and ADR-0069 (no LoadBalancer
Services) for evolution-dev, and only once enabled.
## Context
Internal testers need the native client (M9.8e ZIP) to reach the dev region without
`kubectl port-forward`. The cluster inventory (INVENTORY.md, 2026-09-29) shows RKE2's
ingress-nginx 1.12.1 DaemonSet serving 80/443 on all four node addresses (public sites
included), MetalLB 0.15.2 in FRR mode with one LoadBalancer (Gitea SSH), and an existing
HTTP Ingress for void.aeternalisgames.com in namespace `void`. The session protocol is
TLS 1.3 over raw TCP (ADR-0082), not HTTP. Sessions need synthetic carrier inputs, which
ADR-0073 keeps drill-time only so dev history does not grow continuously.
## Decision (maintainer, 2026-10-02)
**Route.** `void.aeternalisgames.com:7400` resolves, in internal DNS, to a dedicated
internal MetalLB VIP (never automatically the control-plane address 172.10.1.160) that
fronts one LoadBalancer Service `evo-region-session` in evolution-dev, which forwards to
the region pod's port 7400. TLS 1.3 terminates in the region pod; its dev-CA server
certificate carries `void.aeternalisgames.com`, which the client verifies. No HTTP
Ingress, no TLS termination at nginx, no PROXY-protocol prefix. The Service uses
`externalTrafficPolicy: Local` (client addresses preserved), no node ports, a pinned
`metallb.io/loadBalancerIPs` annotation and `loadBalancerSourceRanges`. New connections
reach only a ready pod; after a replacement, clients reconnect with a fresh grant and
baseline (ADR-0083).
**Access.** Development workstation/test subnet only, in three layers: the edge
firewall, the Service source ranges and a NetworkPolicy admitting TCP 7400 to the region
pod from exactly those CIDRs. TLS with the dev CA and single-use, short-lived grants stay
mandatory; grants remain bearer tokens.
**Listener.** The base keeps the opt-in listener on loopback through
`REGION_SESSION_LISTEN=127.0.0.1:7400`. Only the route component
(`deploy/kubernetes/region/dev-session-route`) binds the pod interface and names the
session port. The listener still starts only when sessions are enabled.
**Windows.** Sessions and synthetic inputs run only during an operator-opened test window
with automatic expiry (default 30 minutes); always-on simulation waits for an explicit
disposable-world lifecycle and retention. The endpoint (DNS, MetalLB Service) may stay
configured permanently. A small dev-only GitOps configuration holds an activation id,
the exact world/region identity and an absolute UTC expiry. Operations, via a manually
triggered Gitea workflow: Open (default 30 min), Extend (new explicit expiry), Close
(stop accepting sessions, close existing connections, stop synthetic inputs, drain
pending commits) and Status (window, expiry, active sessions, committed tick).
Expiry is enforced **inside evo-server**, not by a delayed cleanup job:
- a restart keeps the original absolute deadline, never a fresh duration;
- an expired configuration cannot reopen the listener;
- expiry stops synthetic generation as well as connections;
- a failed workflow cannot leave simulation running; cleanup may later restore the
closed Git configuration. Grant expiry alone does not stop the generator.
## Enabling (all required; `tools/ci/deploy-policy-check.py` refuses otherwise)
1. The VIP (private, from the MetalLB pool) and permitted client CIDR(s) (private, no
wider than /16) replace the REPLACE markers; Service ranges equal the policy's.
2. `deploy/kubernetes/platform/dev` raises `services.loadbalancers` to exactly 1;
node ports stay 0; stage and World0 stay 0.
3. evo-server implements the session window (`--session-window`) as above, with tests
and an amendment to this ADR, and the base deployment passes it.
4. Only `region/dev` includes the component. Then: internal DNS for void to the VIP, the
edge firewall rule, and a server-side dry-run (quota accounting of the Local health
check port is to be confirmed there), a new dev server certificate for
void.aeternalisgames.com, and live connectivity recorded separately in VALIDATION.md.
## Open points for the maintainer
- **Argo delivery.** The aevolution-dev Application has no automated sync, and the
policy forbids auto-sync outside the platform app (ADR-0069). A workflow commit alone
will not deploy; either a manual sync per window or a scoped dev exception must be
decided before implementing the workflow. CI holds no cluster credentials (ADR-0020),
so Status can report Git state; live fields need a defined read path.
- **void namespace.** void.aeternalisgames.com already has an HTTP Ingress (namespace
`void`). Pointing internal DNS at the VIP changes what internal clients reach for that
name; confirm or retire the existing route.
- Window limits: maximum window length and clock-skew tolerance.
## Alternatives considered
- ingress-nginx tcp-services or SNI passthrough on 443: couples game sessions to the
shared web ingress (443 likely internet-facing) and needs controller changes.
- Port-forward only (ADR-0083): no tester-friendly endpoint.
- NodePort: opens a port on every node; forbidden by ADR-0069.
- Always-on sessions in dev: continuous synthetic history; rejected for now.
## Consequences
One reviewed exception to "no LoadBalancer" for evolution-dev. The policy check and its
fail-closed self-test (`tools/ci/deploy-policy-selftest.py`) encode the route's shape and
the enabling preconditions. World0 and stage are untouched.
+1
View File
@@ -97,5 +97,6 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0083: Dev region sessions](0083-dev-region-sessions.md) - session server in evo-server, durable no-effect intentions on synthetic carriers, empty organism presentation, reconnect with fresh baselines, loopback-only drill-time dev deployment.
- [ADR-0084: Engineering UI toolkit](0084-engineering-ui-toolkit.md) - Dear ImGui 1.92.9b pinned (M9.8a) and integrated as the engineering client overlay with toolkit-first input routing (M9.8c).
- [ADR-0087: Dev session route](0087-dev-session-route.md) - evolution-dev only: void.aeternalisgames.com:7400 via a dedicated internal MetalLB VIP to the region pod, TLS end to end, CIDR-limited, operator-opened windows enforced by evo-server; committed disabled with fail-closed policy tests.
- [ADR-0086: Windows client package](0086-windows-client-package.md) - static-runtime Windows x64 ZIP with explicit allowlist, licence texts, build identity, SHA256 manifest, credential guards and deterministic layout; local packaging until a Windows runner exists.
- [ADR-0085: Rebindable engineering controls](0085-rebindable-engineering-controls.md) - SDL-free action/HID-key bindings, conflict validation, versioned all-or-nothing controls file, binding capture before toolkit/world.
+7 -4
View File
@@ -4,7 +4,9 @@ Status: M9.8a probe, M9.8b owned state/capture/event bounds, M9.8c launcher,
legend, labelled inspector and click selection, and M9.8d rebindable controls
complete, 2026-10-02. M9.8e local Windows ZIP complete (ADR-0086); its Gitea
Actions publication waits for a Windows runner and its clean-VM run for M9.8g.
Remaining segments planned.
M9.8f route design, disabled manifests and fail-closed policy tests complete
(ADR-0087); enabling waits for the VIP, client CIDR, DNS, dev quota and server-enforced
session windows. M9.8g remains.
No application UI or deployment completion is claimed. See ADR-0084 for the toolkit boundary.
## Confirmed scope
@@ -64,9 +66,10 @@ All selected biological data remains a read-only presentation copy.
- No Windows runner exists yet (confirmed 2026-10-02). Local builds are the initial path. Do not silently route a Windows
package job to the existing Linux runner or assume an untested cross-compile.
The packaging script can run on the existing Windows development host meanwhile.
- Confirmed control plane: 172.10.1.160. Still needed for direct service routing:
nginx implementation/configuration, exposed TCP port,
source restrictions and certificate name. The protocol is TLS/TCP, not HTTP;
- Confirmed control plane: 172.10.1.160. Direct routing decided in ADR-0087: dedicated
internal MetalLB VIP, TCP 7400, void.aeternalisgames.com, CIDR-limited. Still needed:
the VIP from the MetalLB pool, the permitted client CIDR, internal DNS, and decisions
on Argo delivery of session windows and the existing void HTTP Ingress. The protocol is TLS/TCP, not HTTP;
a standard HTTP Ingress rule does not implement it. Port-forward remains supported.
- VM specification and whether graphics acceleration is available. Hardware-specific
performance acceptance cannot be declared before these are known.
+34
View File
@@ -3896,3 +3896,37 @@ Executed on the Windows development host (MSVC 19.44.35217, CMake 3.31.6):
Not done: Gitea Actions publication (no Windows runner), a run on a clean Windows
VM (M9.8g), code signing, hardware/DPI qualification, legal review of notices.
## 2026-10-02 — M9.8f dev session route design (ADR-0087)
Maintainer decisions: dedicated internal MetalLB VIP, TCP 7400,
void.aeternalisgames.com, TLS ending in the region pod, development/test CIDR only
(firewall + Service source ranges + NetworkPolicy), no Ingress/nginx TLS/PROXY
protocol; operator-opened windows with server-enforced absolute expiry; scope limited
to design, manifests and policy tests. Nothing was applied to the cluster.
Implemented: `REGION_SESSION_LISTEN` (base stays 127.0.0.1:7400); the disabled
component `deploy/kubernetes/region/dev-session-route` (LoadBalancer Service with
Local policy, no node ports, pinned VIP annotation and source ranges; CIDR-only
ingress policy on TCP 7400; listener patch to the pod interface) carrying REPLACE
markers; policy rules for the route's exact shape, LoadBalancer/NodePort and
session-port exclusivity, no session Ingress, evolution-dev-only placement, quota
limits, and enabling preconditions (no markers, dev quota of exactly one
LoadBalancer, server `--session-window`); patch files are now recognized generally.
`tools/ci/deploy-policy-selftest.py` copies the manifests and applies 20 unsafe changes.
Executed (WSL Ubuntu, Python 3 with PyYAML 6.0.1): deploy policy check on the
repository, 70 objects in 68 files, 0 failures; self-test 20/20 refused, baseline
copy passes; ops-lib and ci-path fixtures pass; session-drill usage unchanged.
kustomize v5.4.3 (official release, SHA-256 checked against its checksums.txt, in a
scratch directory, not a project dependency) rendered region/dev as committed (listener
127.0.0.1:7400, no session Service) and a temporary enabled copy with example private
values (LoadBalancer evo-region-session and the CIDR policy in evolution-dev, listener
0.0.0.0:7400, session container port merged).
Not run: the ci-deploy Docker stage (no Docker in this WSL distribution; its commands
were run directly), any cluster/server dry-run, MetalLB allocation, DNS, firewall or live
connectivity. Server-enforced session windows and the Gitea window workflow are not
implemented; Argo delivery for windows and the existing void HTTP Ingress are open
maintainer decisions recorded in ADR-0087.
@@ -82,3 +82,12 @@ exposed through a Service, NodePort or Ingress. A grant bundle lasts at most one
and each connection consumes one grant. WASD sends intentions; the small chip under
the intention dot turns white (admitted), green (durable, no effect) or red/grey
(rejected or outcome unknown). Console lines report every session event.
## 6. Planned direct route (M9.8f, disabled)
ADR-0087 designs `void.aeternalisgames.com:7400` through a dedicated internal MetalLB
VIP to the region pod (TLS end to end, development/test CIDR only), opened only in
operator windows that evo-server itself expires. The manifests are in
`deploy/kubernetes/region/dev-session-route` and are not included anywhere; the policy
check refuses to enable them until the VIP, client CIDR, dev quota and the server-side
`--session-window` exist. Until then use the port-forward procedures above.