# Dev session operations (M9.7) Decision: [ADR-0083](../adr/0083-dev-region-sessions.md); protocol: [DEV_SESSION_PROTOCOL](DEV_SESSION_PROTOCOL.md). **evolution-dev only.** Stage and World0 have no session Secret, and `evo-server` refuses any environment but `dev`. ## 1. Build the tools ```sh cmake -P tools/prepare-mbedtls.cmake cmake --preset network && cmake --build --preset network # evo-dev-session # Desktop client with remote mode (also needs SDL prepared): cmake --preset client-network && cmake --build --preset client-network ``` The server image (`deploy/docker/Dockerfile`, `server-runtime`) is built with `EVO_BUILD_NETWORK=ON`; a new image digest must be pinned in the dev overlay as usual (ADR-0071) before the session flags exist in the cluster. ## 2. Create credentials on the operator machine (once) ```sh evo-dev-session credentials --environment dev \ --server-name dev-region.evolution.test --out ~/aevolution-dev-session ``` Writes `dev-ca.pem` (public; give to dev clients), `server.pem` (public), `server.key` and `grant.key` (secrets, owner-only, never overwritten). Keep the directory private. Never commit these files; the policy check rejects Secrets in Git. ## 3. Provision the Secret (cluster administrator, out of band) ```sh kubectl -n evolution-dev create secret generic evolution-dev-session \ --from-file=server.pem=$HOME/aevolution-dev-session/server.pem \ --from-file=server.key=$HOME/aevolution-dev-session/server.key \ --from-file=grant.key=$HOME/aevolution-dev-session/grant.key ``` The Deployment mounts it optionally (0440). Consumed grants are recorded in `/objects/dev-session-grants.v1` on the region's persistent volume (fsynced before each Welcome), so a restarted pod refuses grants its predecessor used. Corrupt or unwritable ledgers fail closed (`error session-grant-ledger`, or sessions refused). A sibling `.lock` file enforces one ledger owner across startup and compaction. Do not delete or replace this lock file while a server might be running; its presence does not mean a stale lock. Process exit releases the OS lock automatically. A competing startup fails before modifying the ledger. Incomplete final records and oversized lines are refused without rewriting; investigate the storage failure rather than deleting grant history to force startup. Rotation: create new credentials, replace the Secret, restart evo-region and redistribute `dev-ca.pem`. Old grants stop verifying with the new key. ## 4. Session drill (enables sessions temporarily, then restores Git values) ```sh EVO_DEV_SESSION=./build/network/evo-dev-session \ tools/ops/session-drill.sh ~/aevolution-dev-session [--context ] ``` Expected: `probe durable ...` before and after the forced pod deletion, a second `probe welcome` with a higher epoch, `PASS session drill`. Record the output in engineering/VALIDATION.md. Exit 1 on any missing observation; Git values are restored on every exit path. ## 5. Interactive engineering session While a drill-style override is active (`REGION_INPUTS=development-v1`, `REGION_SESSION=dev`; revert afterwards: `kubectl -n evolution-dev set env deployment/evo-region REGION_INPUTS= REGION_SESSION=`): ```sh evo-dev-session grants --environment dev --key ~/aevolution-dev-session/grant.key \ --world 100 --frame 9 --region 1 --subject 7 --count 16 --out grants.bin kubectl -n evolution-dev port-forward deploy/evo-region 17400:7400 & evo-client --connect 127.0.0.1:17400 --server-name dev-region.evolution.test \ --ca ~/aevolution-dev-session/dev-ca.pem --grants grants.bin ``` The listener binds the pod's loopback, so only port-forward reaches it; nothing is exposed through a Service, NodePort or Ingress. A grant bundle lasts at most one hour 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.