Files
aevolution/docs/engineering/CLIENT.md
T
dingoandClaude Opus 5.5 8e319322f4 Implement M9.7 dev region sessions with durable no-effect intentions
Run a non-blocking TLS 1.3 session server inside evo-server's loop:
environment views come from the region's own field/terrain stores with an
explicitly empty organism presentation; admitted intentions ride the next
synthetic input (content unchanged) and return a durable no-effect outcome
from the host's final acknowledgement, or not_committed when dropped.
Sessions are bound to their connection, epochs close stale sessions, and
connections have bounded output, input rate and deadlines.

SessionClient and evo-client --connect consume one single-use grant per
Hello (refusals before admission keep it), reset to a fresh baseline on
every session, keep stale views visible and report in-flight intentions as
unknown after loss. evo-dev-session generates dev credentials, grant
bundles and runs a restart probe. The dev deployment gains a drill-time,
loopback-only listener with an optional Secret, enforced by the policy
check, and tools/ops/session-drill.sh. Protocol v1 gains IntentOutcome and
the capacity close reason before any deployment. ADR-0083 records the
maintainer-confirmed decisions; M8-dev/stage remains not passed and no
cluster change was made.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 20:12:18 -04:00

79 lines
4.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Native engineering client (M9.2–M9.7)
This opens a resizable native window showing camera-controlled environment habitats
and biology-derived organisms (M9.5) from a local in-memory fixture authority.
It does not run an ecosystem,
connect to a server or implement cellular gameplay.
Contract: [client architecture](../architecture/CLIENT_ARCHITECTURE.md), ADR-0078.
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.
`--connect HOST:PORT --server-name NAME --ca FILE --grants FILE` (preset
`client-network`) replaces the local fixture with a dev session: views come from the
region, WASD sends intentions, and chips at y=72 show the connection (green/amber/red)
and the last intention (white admitted, green durable, red rejected, grey unknown).
## Build and run
After [explicit SDL preparation](CLIENT_DEPENDENCIES.md), in a compiler shell:
```sh
cmake --preset client
cmake --build --preset client --parallel 4
ctest --preset client --no-tests=error
./build/client/evo-client
```
Windows: `tools/windows-check.ps1 -Preset client -Action check` configures the
MSVC environment. Use `.exe` for executable paths. Linux requires the X11 or
Wayland development packages described in the dependency guide; the Docker
`ci-client` stage supplies the tested X11 subset.
Close the window to exit. `--renderer software` or `--renderer vulkan` requests
one explicit backend, without fallback. `--frames N` exits after N bounded steps
(including paused steps), maximum 100000; `--hidden` opens without showing the
window and pauses drawing. These options permit unattended smoke checks.
`--layer NAME` selects the displayed field or `moisture`; `--refresh-every N`
(1..1000 fixture authority ticks) delays view refresh so the stale state is visible.
`--inspect` shows biology gauges for the organism under the pointer.
Usage errors exit 2, lifecycle/fixture failures exit 1, orderly exit returns 0.
Engineering controls: arrow keys pan, mouse wheel zooms around the pointer, WASD
updates the small intention indicator without moving the world fixture. Tab
toggles UI capture: the top-left bar turns orange and navigation/movement input
is suppressed. Leaving capture/focus loss requires fresh presses. This is a
focus exercise, not the final player UI. The host's input tick is a local fixture
counter and is never interpreted as authoritative server time. The top-right
chips show environment then organism freshness (green current, amber stale, red
none; magenta marker: organisms truncated); the bottom-left legend shows the ramp.
The organism cluster is near (410 mm, 480 mm); zoom in with the wheel to see it.
For native X11 regression on a CI host:
```sh
xvfb-run -a env SDL_VIDEO_DRIVER=x11 ./build/client/evo-client-lifecycle-tests
```
CTest uses the dummy driver. `client-environment` is an SDL-free suite for
presentation validation, ordering/freshness, encodings, seams and bounds; it
prints an `environment_profile` line (rectangles, bytes, microseconds per build).
`client-organisms` covers phenotype derivation, controller parity, death/removal,
dense scenes and truncation, ordering, picking and the inspector. The lifecycle suite runs 32 open/destroy rounds,
resize/scale queries, non-unit drawable-scale pixel checks, minimize/restore,
show/hide, focus/foreign events, reset/loss and close. Separate process checks
exercise initialization failure. Tests stay active under NDEBUG. Synthetic
events and software rendering do not qualify physical DPI, keyboard, GPU loss
or compositor behavior; those remain a hardware matrix at M9.8.
Analysis/sanitizers use the existing options, for example configure `--preset
asan -B build/client-asan -DEVO_BUILD_CLIENT=ON` with Clang 19. This instruments
owned frame/platform/app/test code, not SDL/system libraries. Linux X11 builds
link X11 directly (`SDL_X11_SHARED=OFF`) to preserve library lifetime across SDL
cycles. No preload or leak suppression is required. The diagnosed M9.1 dynamic
unload behavior and qualification evidence are documented in VALIDATION.md.
Headless defaults keep both `EVO_BUILD_CLIENT` and `EVO_BUILD_CLIENT_PROBE` OFF.
No prepared SDL sources, display or client runtime are needed for `evo-sim` or
server tests. No Kubernetes deployment change belongs to this desktop gate.