Files
aevolution/docs/architecture/CLIENT_ARCHITECTURE.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

80 lines
4.7 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 client boundary (M9.2–M9.5)
Implemented scope: desktop lifecycle and primitive presentation, not gameplay.
ADR-0077 selects SDL; ADR-0078 defines its ownership and view boundary.
```mermaid
flowchart LR
App[evo-client main thread] --> Platform[Application / private SDL adapter]
App --> Frame[Owned immutable render Frame]
Platform --> Render[Private SDL renderer]
Frame --> Render
World[M6.3 EnvironmentView] -- copied once --> Views[EnvironmentPresentation / Layer]
Views --> Env[build_environment + Camera]
Env -- bounded rectangles --> Frame
Bio[M3 Phenotype] -- derive_phenotype --> Orgs[OrganismPresentation / Layer]
Orgs --> OrgRender[append_organisms + inspector]
OrgRender -- budgeted rectangles --> Frame
```
`include/evo/client/application.hpp` and `include/evo/render/frame.hpp` contain
no SDL, world-store, network or database types. The application owns one SDL
runtime, window and renderer on the process main thread; concurrent application
instances are rejected. Destruction releases renderer, window, then SDL. Partial
initialization releases everything acquired. No application object may outlive
main or be used/destroyed on another thread.
`Frame::create` validates and copies at most 4096 rectangles. Its const span is
valid until frame destruction/assignment. `Application::step(const Frame&)`
borrows it for the call only; there is no queue, stored pointer or simulation
mutation. Coordinates are logical window units, top-left origin, +Y down. They
are presentation units, never world millimetres. M9.3 implements world-screen mapping;
M9.4 projects environment samples. In particular, do not retain M6 validation
tokens/store pointers in a renderer or serialize them as a client protocol.
Window state records logical size, drawable pixel size and display content scale
separately. Resizes/display changes query SDL rather than trust event payloads.
Drawing scales independently by pixel/logical width and height; content scale is
for future UI sizing, not a second pixel multiplier. Hidden/minimized/zero-area
windows skip rendering. Focus loss disables the future input admission flag;
M9.3 clears all held intentions on admission loss. Close is terminal.
Each step consumes at most 256 events, filters window-specific events and renders
one frame. Target reset needs only redraw (no cached textures). Device reset
recreates the renderer from CPU frame data. Device loss, recreation/query/draw
failure latch an error until destruction; no silent backend substitution or busy
recovery loop. Typed errors reach the process boundary. The host paces frames
outside the renderer and catches allocation/standard-library exceptions.
M9.3 also exposes separate `poll_events()` and `present(frame)` calls so camera
mapping uses current resize/input state. SDL-free camera and input contracts are
specified in [CAMERA_INPUT.md](../engineering/CAMERA_INPUT.md) and ADR-0079.
UI capture and event-backlog handling suppress held world input; sequence/tick
intentions do not confer server authority. M9.6 owns session binding.
M9.4 ([ENVIRONMENT_RENDERING.md](../engineering/ENVIRONMENT_RENDERING.md),
ADR-0080) adds SDL-free `client/environment_view.hpp` and
`render/environment.hpp`. A presentation copies at most 256 cells of one Z slice
from a view and retains no store, token or native handle. `EnvironmentLayer`
holds one presentation, rejects foreign or regressed revisions and reports
none/current/stale against observed authority watermarks. The projection emits
at most 2313 clipped rectangles with explicit missing, unrequested, present-zero,
undefined and stale encodings. The client libraries link the headless world
library read-only; no world or simulation target links client code.
M9.5 ([ORGANISM_RENDERING.md](../engineering/ORGANISM_RENDERING.md), ADR-0081)
adds `client/organism_view.hpp`, `render/organism.hpp` and the engineering
`client/organism_inspector.hpp`. Organism cells carry phenotype, growth, position
and alive/dead only; no controller, owner or level field exists, so players and
NPCs share one presentation. Rendering takes an explicit rectangle budget and
reports truncation; the inspector draws biology gauges only. ImGui is not adopted.
M9.7 (ADR-0083): in remote mode the layers are owned by `network::SessionClient`,
filled only from server views; on loss they stay visible but stale, and every new
session resets them to the server's fresh baseline. The client never predicts.
Failure tests inject actual SDL events, including foreign window IDs, with no
test-only production hooks. Real device failures and physical DPI/input require
manual hardware qualification at M9.8. The native client is opt-in and never
enters a server container. Headless configuration does not prepare/load SDL.