Implement M9.2 native client lifecycle and immutable render boundary

This commit is contained in:
dingo
2026-10-01 16:58:46 -04:00
parent d487d86ea3
commit 04c7715646
24 changed files with 827 additions and 34 deletions
+2 -1
View File
@@ -25,6 +25,7 @@ option(EVO_BUILD_FUZZER "Build the Clang libFuzzer snapshot target" OFF)
option(EVO_BUILD_ECS_EXPERIMENT "Build the isolated EnTT comparison (explicit preparation required)" OFF)
option(EVO_BUILD_POSTGRES "Build the isolated Linux PostgreSQL persistence adapter" OFF)
option(EVO_BUILD_CLIENT_PROBE "Build the isolated M9.1 SDL dependency probe" OFF)
option(EVO_BUILD_CLIENT "Build the native M9 engineering client" OFF)
set(EVO_SANITIZER "none" CACHE STRING "none, address (ASan/UBSan), or thread")
set_property(CACHE EVO_SANITIZER PROPERTY STRINGS none address thread)
include(cmake/ProjectOptions.cmake)
@@ -91,7 +92,7 @@ target_link_libraries(evo_region_checkpoint PUBLIC evo::region_lease evo::proces
evo_owned_target(evo_region_checkpoint)
include(CTest)
if(EVO_BUILD_CLIENT_PROBE)
if(EVO_BUILD_CLIENT_PROBE OR EVO_BUILD_CLIENT)
include(cmake/ClientProbe.cmake)
endif()
if(EVO_BUILD_POSTGRES)
+3
View File
@@ -8,6 +8,7 @@
{"name": "analysis", "inherits": "debug", "cacheVariables": {"EVO_ENABLE_TIDY": "ON"}},
{"name": "asan", "inherits": "debug", "cacheVariables": {"EVO_SANITIZER": "address"}},
{"name": "tsan", "inherits": "debug", "cacheVariables": {"EVO_SANITIZER": "thread"}},
{"name": "client", "inherits": "release", "cacheVariables": {"EVO_BUILD_CLIENT": "ON"}},
{"name": "client-probe", "inherits": "release", "cacheVariables": {"EVO_BUILD_CLIENT_PROBE": "ON"}}
],
"buildPresets": [
@@ -16,6 +17,7 @@
{"name": "analysis", "configurePreset": "analysis"},
{"name": "asan", "configurePreset": "asan"},
{"name": "tsan", "configurePreset": "tsan"},
{"name": "client", "configurePreset": "client", "targets": ["evo-client", "evo-client-lifecycle-tests"]},
{"name": "client-probe", "configurePreset": "client-probe", "targets": ["evo-client-probe"]}
],
"testPresets": [
@@ -24,6 +26,7 @@
{"name": "analysis", "configurePreset": "analysis", "output": {"outputOnFailure": true}},
{"name": "asan", "configurePreset": "asan", "output": {"outputOnFailure": true}},
{"name": "tsan", "configurePreset": "tsan", "output": {"outputOnFailure": true}},
{"name": "client", "configurePreset": "client", "filter": {"include": {"label": "client"}}, "output": {"outputOnFailure": true}},
{"name": "client-probe", "configurePreset": "client-probe", "filter": {"include": {"label": "client"}}, "output": {"outputOnFailure": true}}
]
}
+2 -1
View File
@@ -168,4 +168,5 @@ The default simulation build does not require PostgreSQL.
The optional SDL3 probe is separate from the headless targets. See
[client dependency preparation and checks](docs/engineering/CLIENT_DEPENDENCIES.md).
M9.2 will build the actual client platform/render boundary.
M9.2 supplies the [native engineering client](docs/engineering/CLIENT.md), with
an immutable frame boundary and tested window/resource lifecycle.
+61
View File
@@ -0,0 +1,61 @@
#include "evo/client/application.hpp"
#include <array>
#include <charconv>
#include <chrono>
#include <cstdio>
#include <exception>
#include <string_view>
#include <thread>
int main(int argc, char** argv) try {
evo::client::Config config;
unsigned frames = 0;
for (int i = 1; i < argc; ++i) {
const std::string_view arg{argv[i]};
if (arg == "--hidden")
config.hidden = true;
else if (arg == "--renderer" && i + 1 < argc)
config.renderer = argv[++i];
else if (arg == "--frames" && i + 1 < argc) {
const std::string_view value{argv[++i]};
const auto [end, error] =
std::from_chars(value.data(), value.data() + value.size(), frames);
if (error != std::errc{} || end != value.data() + value.size() || frames == 0 ||
frames > 100000)
return 2;
} else {
std::fputs("usage: evo-client [--renderer NAME] [--hidden] [--frames 1..100000]\n",
stderr);
return 2;
}
}
auto app = evo::client::Application::open(config);
if (!app) {
std::fprintf(stderr, "client initialization error=%d\n", static_cast<int>(app.error()));
return 1;
}
// Presentation fixture only. No simulated organisms or world state.
const std::array<evo::render::Rectangle, 1> boxes{{{24, 24, 160, 96, {64, 180, 140, 255}}}};
const auto frame = evo::render::Frame::create(boxes, {16, 20, 28, 255});
if (!frame)
return 1;
unsigned count = 0;
while (frames == 0 || count < frames) {
const auto result = (*app)->step(*frame);
if (!result) {
std::fprintf(stderr, "client frame error=%d\n", static_cast<int>(result.error()));
return 1;
}
if (*result == evo::client::Step::closed)
break;
++count;
std::this_thread::sleep_for(std::chrono::milliseconds{16});
}
return 0;
} catch (const std::exception& e) {
std::fprintf(stderr, "client exception: %.200s\n", e.what());
return 1;
} catch (...) {
std::fputs("client exception\n", stderr);
return 1;
}
+52 -14
View File
@@ -14,23 +14,61 @@ set(SDL_TEST_LIBRARY OFF CACHE BOOL "" FORCE)
set(SDL_TESTS OFF CACHE BOOL "" FORCE)
set(SDL_EXAMPLES OFF CACHE BOOL "" FORCE)
set(SDL_INSTALL OFF CACHE BOOL "" FORCE)
if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
# Keep Xlib process-lifetime caches reachable across SDL init/quit cycles.
# Dynamic unloading leaked in the repeated M9.2 lifecycle test (ADR-0078).
set(SDL_X11_SHARED OFF CACHE BOOL "Link X11 directly for the native client" FORCE)
endif()
foreach(feature AUDIO CAMERA JOYSTICK HAPTIC SENSOR GPU)
set(SDL_${feature} OFF CACHE BOOL "M9.1 scoped subset" FORCE)
endforeach()
add_subdirectory("${sdl_source}" "${PROJECT_BINARY_DIR}/sdl3" EXCLUDE_FROM_ALL SYSTEM)
add_executable(evo-client-probe experiments/client/main.cpp)
target_link_libraries(evo-client-probe PRIVATE SDL3::SDL3)
evo_owned_target(evo-client-probe)
if(WIN32)
add_custom_command(TARGET evo-client-probe POST_BUILD
COMMAND "${CMAKE_COMMAND}" -E copy_if_different
"$<TARGET_FILE:SDL3::SDL3>" "$<TARGET_FILE_DIR:evo-client-probe>" VERBATIM)
function(evo_client_runtime target)
if(WIN32)
add_custom_command(TARGET ${target} POST_BUILD
COMMAND "${CMAKE_COMMAND}" -E copy_if_different
"$<TARGET_FILE:SDL3::SDL3>" "$<TARGET_FILE_DIR:${target}>" VERBATIM)
endif()
endfunction()
if(EVO_BUILD_CLIENT_PROBE)
add_executable(evo-client-probe experiments/client/main.cpp)
target_link_libraries(evo-client-probe PRIVATE SDL3::SDL3)
evo_owned_target(evo-client-probe)
evo_client_runtime(evo-client-probe)
if(BUILD_TESTING)
add_test(NAME client-probe-software COMMAND evo-client-probe --renderer software)
set_tests_properties(client-probe-software PROPERTIES
ENVIRONMENT "SDL_VIDEO_DRIVER=dummy" TIMEOUT 20 LABELS "client")
add_test(NAME client-probe-invalid-driver COMMAND evo-client-probe --renderer evo-invalid)
set_tests_properties(client-probe-invalid-driver PROPERTIES
ENVIRONMENT "SDL_VIDEO_DRIVER=dummy" WILL_FAIL TRUE TIMEOUT 20 LABELS "client")
endif()
endif()
if(BUILD_TESTING)
add_test(NAME client-probe-software COMMAND evo-client-probe --renderer software)
set_tests_properties(client-probe-software PROPERTIES
ENVIRONMENT "SDL_VIDEO_DRIVER=dummy" TIMEOUT 20 LABELS "client")
add_test(NAME client-probe-invalid-driver COMMAND evo-client-probe --renderer evo-invalid)
set_tests_properties(client-probe-invalid-driver PROPERTIES
ENVIRONMENT "SDL_VIDEO_DRIVER=dummy" WILL_FAIL TRUE TIMEOUT 20 LABELS "client")
if(EVO_BUILD_CLIENT)
add_library(evo_render_frame STATIC src/render/frame.cpp)
target_include_directories(evo_render_frame PUBLIC "${PROJECT_SOURCE_DIR}/include")
evo_owned_target(evo_render_frame)
add_library(evo_client_platform STATIC src/client/platform/application.cpp src/render/sdl_renderer.cpp)
target_include_directories(evo_client_platform PRIVATE "${PROJECT_SOURCE_DIR}/src")
target_link_libraries(evo_client_platform PUBLIC evo_render_frame PRIVATE SDL3::SDL3)
evo_owned_target(evo_client_platform)
add_executable(evo-client apps/evo-client/main.cpp)
target_link_libraries(evo-client PRIVATE evo_client_platform)
evo_owned_target(evo-client)
evo_client_runtime(evo-client)
if(BUILD_TESTING)
add_executable(evo-client-lifecycle-tests tests/client_lifecycle.cpp)
target_include_directories(evo-client-lifecycle-tests PRIVATE "${PROJECT_SOURCE_DIR}/src")
target_link_libraries(evo-client-lifecycle-tests PRIVATE evo_client_platform SDL3::SDL3)
evo_owned_target(evo-client-lifecycle-tests)
evo_client_runtime(evo-client-lifecycle-tests)
add_test(NAME client-lifecycle COMMAND evo-client-lifecycle-tests)
add_test(NAME client-smoke COMMAND evo-client --renderer software --frames 3)
add_test(NAME client-init-failure COMMAND evo-client --frames 1)
set_tests_properties(client-lifecycle client-smoke PROPERTIES
ENVIRONMENT "SDL_VIDEO_DRIVER=dummy" TIMEOUT 30 LABELS "client")
set_tests_properties(client-init-failure PROPERTIES
ENVIRONMENT "SDL_VIDEO_DRIVER=evo-invalid" WILL_FAIL TRUE TIMEOUT 20 LABELS "client")
endif()
endif()
+8 -3
View File
@@ -40,10 +40,15 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
&& rm -rf /var/lib/apt/lists/*
RUN cmake -P tools/prepare-sdl3.cmake \
&& cmake --preset client-probe -DCMAKE_CXX_COMPILER=clang++-19 \
-DEVO_ENABLE_TIDY=ON -DSDL_X11=ON -DSDL_WAYLAND=OFF \
&& cmake --build --preset client-probe --parallel 2 \
-DEVO_BUILD_CLIENT=ON -DEVO_ENABLE_TIDY=ON -DSDL_X11=ON -DSDL_WAYLAND=OFF \
&& cmake --build build/client-probe --target evo-client-probe evo-client evo-client-lifecycle-tests --parallel 2 \
&& ctest --preset client-probe --no-tests=error \
&& xvfb-run -a env SDL_VIDEO_DRIVER=x11 ./build/client-probe/evo-client-probe --renderer software
&& xvfb-run -a env SDL_VIDEO_DRIVER=x11 ./build/client-probe/evo-client-probe --renderer software \
&& xvfb-run -a env SDL_VIDEO_DRIVER=x11 ./build/client-probe/evo-client-lifecycle-tests \
&& cmake --preset client-probe -DEVO_BUILD_CLIENT=ON -DEVO_SANITIZER=address -DEVO_ENABLE_TIDY=OFF \
&& cmake --build build/client-probe --target evo-client evo-client-lifecycle-tests --parallel 2 \
&& ctest --preset client-probe --no-tests=error \
&& xvfb-run -a env SDL_VIDEO_DRIVER=x11 ./build/client-probe/evo-client-lifecycle-tests
FROM ci-source AS ci-ecs
# Explicit experiment preparation; normal configure/runtime remains dependency-free.
+7 -1
View File
@@ -392,7 +392,13 @@ JetStream is adopted only for a demonstrated delivery workload, not as lease aut
**M9.1 status (2026-10-01):** implemented and locally validated; scoped SDL3
decision in ADR-0077, explicit pinned preparation, Windows native and Linux X11
software probes. Evidence and platform limits are in engineering/VALIDATION.md.
The added Gitea client job awaits remote execution. Next gate: M9.2.
The added Gitea client job awaits remote verification.
**M9.2 status (2026-10-01):** native application, immutable frame boundary and
surface/resource lifecycle implemented under ADR-0078; Windows/Linux tests,
analysis, ASan/UBSan and headless replay evidence in engineering/VALIDATION.md.
Physical DPI/input and real GPU loss remain hardware qualification, not claims
from injected events. Next gate: M9.3.
**Goal:** a native desktop cellular viewer/controller with input, camera, renderer,
readable organism/environment views and a real development-server connection.
+10 -8
View File
@@ -2,15 +2,17 @@
## Current gate — 2026-10-01
M9.1 supplies the opt-in native dependency probe and scoped SDL3 decision in
[ADR-0077](adr/0077-scoped-native-client-dependencies.md). SDL 3.4.16 is pinned by
archive hash; the headless build remains independent. Windows native backends and
Linux software/X11 validation are recorded in [VALIDATION.md](engineering/VALIDATION.md).
The new isolated Gitea client gate has not yet run remotely.
M9.2 adds an opt-in native `evo-client`, immutable presentation frame contract and
RAII platform/renderer lifecycle ([ADR-0078](adr/0078-native-client-lifecycle.md)).
Resize/pixel scale, focus, minimized/hidden windows, reset/loss and orderly close
are covered by Windows/Linux tests. Direct X11 linking resolves the observed
M9.1 unload allocation issue in repeated sanitizer checks. See
[CLIENT.md](engineering/CLIENT.md) and [VALIDATION.md](engineering/VALIDATION.md).
Updated remote Gitea client execution remains unverified locally.
Next: **M9.2**, the real native application lifecycle and immutable-view renderer
boundary, including resize/DPI/focus and failure handling. The probe is not a
playable client. No deployment or persistent-world state changed in M9.1.
Next: **M9.3**, camera and bounded input intentions. The window displays a static
presentation fixture, not organisms or a connected world. No deployment,
simulation rules, persistent formats or world state changed in M9.2.
The sections below retain earlier milestone delivery history.
@@ -14,7 +14,8 @@ Use SDL **3.4.16**, zlib licensed, for window/events and `SDL_Renderer`. Build a
shared library from an explicitly prepared SHA-256-pinned upstream source archive.
`tools/sdl3-pin.cmake` is the machine-readable pin. Normal CMake configuration
never downloads it. The dependency and `evo-client-probe` are opt-in; only the
probe links SDL. M9.2 will introduce the actual platform/render boundary.
probe links SDL at M9.1. ADR-0078 extends this to the M9.2 platform adapter and
its native tests, with direct X11 linking on Linux for lifecycle correctness.
Select SDL's small 2D abstraction rather than direct Vulkan for this scope. Retain
its platform renderer selection and allow the probe to explicitly request Vulkan,
+50
View File
@@ -0,0 +1,50 @@
# ADR-0078: Native client lifecycle and immutable presentation frames
## Status
Accepted for M9.2 engineering client; no gameplay or protocol decision.
## Context
SDL requires main-thread window/render ownership. A renderer must not retain
mutable simulation stores, and DPI changes must not reinterpret world units.
## Decision
Use one RAII application with a private SDL implementation, typed expected errors,
and a synchronous bounded immutable frame of copied presentation primitives.
Separate logical/drawable dimensions and content scale. Suspend rendering for
hidden/minimized surfaces. Recreate on recoverable device reset; fail closed on
device loss or adapter errors. Document the single-main-thread precondition.
The executable owns pacing and exception handling. See CLIENT_ARCHITECTURE.md.
Linux X11 builds set SDL's supported `SDL_X11_SHARED=OFF`: link X11 libraries
directly rather than repeatedly dlopen/dlclose them with SDL. Repeated init/quit
with dynamic loading left 1,700,544 bytes reported by LeakSanitizer over this
fixture (32 repeated lifecycles, a hidden window and failed renderer initialization). Preloading
libX11 avoided the report; direct linking makes library lifetime explicit without
a preload requirement or sanitizer suppression. This adds system X11 runtime
dependencies when that backend is enabled; headless targets remain unaffected.
## Alternatives considered
- Public SDL handles: simple but leaks backend lifetime into callers; rejected.
- Render thread / queued scene graph: unnecessary synchronization and lifetime
complexity for this gate; defer until profiling justifies it.
- Renderer directly reads world stores: violates the immutable view boundary.
- Retry every failed frame: risks busy loops and hides fatal failures; rejected.
## Benefits
Bounded memory and work, release-active failure tests, no graphical dependencies
in headless targets. SDL can be replaced behind private source files.
## Costs
Frame copy (bounded), one window, simple rectangles only. Native library/global
state precludes embedding another SDL owner in the same process for this scope.
## Risks
Synthetic events do not prove a real GPU reset or physical multi-monitor DPI.
System driver allocations remain outside owned-code instrumentation. Direct
linking addresses the observed unload/lifecycle case, not every platform library
leak or arbitrary GPU driver. Re-run repeated native lifecycle checks on upgrades.
## Consequences
M9.3 adds camera and input intentions; M9.4/5 add biology-derived projections.
No current simulation interfaces, rules or formats change. Desktop packaging,
hardware matrix and native driver recovery remain explicit qualification work.
+1
View File
@@ -89,3 +89,4 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0076: Upgrade rehearsal on clones, version barrier in dev/stage, and node growth](0076-upgrade-and-growth.md) - accepted for M8.9 accelerated clone runs compared state-for-state before a build change, failed-migration recovery, guarded in-cluster barrier, stores/compute node labels with policy-checked placement.
- [ADR-0077: Scoped native client dependencies](0077-scoped-native-client-dependencies.md) - SDL 3.4.16 window/events and 2D renderer for the opt-in M9.1 probe; no simulation dependency.
- [ADR-0078: Native client lifecycle](0078-native-client-lifecycle.md) - main-thread RAII application, immutable presentation frames and explicit surface/device failure handling.
+47
View File
@@ -0,0 +1,47 @@
# Native client boundary (M9.2)
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
Future[Later M9.4 view projection] -. copied presentation values .-> 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 owns 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;
there are no held gameplay inputs in M9.2. 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.
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.
+4
View File
@@ -43,6 +43,10 @@ headers expose values and bounded commands, not third-party ECS/storage types.
No Steam ID, socket, Kubernetes API, logger clock or storage handle belongs in
the simulation state. Durable account references live in orchestration mapping.
M9.2 implements the opt-in [native client boundary](CLIENT_ARCHITECTURE.md):
copied immutable presentation frames and one main-thread platform owner. It does
not yet project biological views or connect to a region server.
| Boundary | Owns | Must not own |
|---|---|---|
| core | Value types, deterministic algorithms, explicit version constants | Global state, threads, I/O |
+51
View File
@@ -0,0 +1,51 @@
# Native engineering client (M9.2)
This opens a resizable native window containing a static presentation fixture.
It does not simulate a world, connect to a server or implement cellular gameplay.
Contract: [client architecture](../architecture/CLIENT_ARCHITECTURE.md), ADR-0078.
## 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.
Usage errors exit 2, lifecycle failures exit 1, orderly exit returns 0.
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. 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.
+6 -4
View File
@@ -54,16 +54,18 @@ it explicitly for a clean rebuild. No network access occurs during configuration
upstream archive retains bundled component notices. No claim is made that SDL
license review licenses the game itself. Binary release packaging must retain
applicable third-party notices and audit enabled backend/system dependencies.
- Shared SDL is linked only by `evo-client-probe`; no SDL includes/link dependencies
enter `include/evo`, simulation, world, biology or server targets. It is disabled
- Shared SDL is linked only by the opt-in probe/client platform and native tests;
no SDL includes enter public headers or simulation, world, biology or server
targets. It is disabled
by default. Windows copies SDL3.dll beside the probe; Linux uses the build RPATH.
- Size reports are build artifacts, not performance rankings. No representative
creature/terrain workload exists yet, so no renderer throughput claim is made.
## Follow-up boundary
M9.2 owns the real application lifecycle, immutable-view renderer interface,
resize/DPI/focus/device failures and resource limits. M9.3 owns camera/intentions.
M9.2 implements the real application lifecycle, immutable-view renderer interface,
resize/DPI/focus/device failures and resource limits. See
[client operation and validation](CLIENT.md). M9.3 owns camera/intentions.
M9.8 owns distributable packaging. Xvfb verifies the Linux X11 window path; real
desktop input, focus, DPI, Wayland and GPU qualification remain later gate work.
See VALIDATION.md for executed measurements and limitations.
+53
View File
@@ -3187,3 +3187,56 @@ remote Gitea run or Kubernetes action was performed for this gate. The new clien
CI job performs analysis, dummy pixel/error tests and an Xvfb window probe;
remote execution remains pending. M9.1 selects a scoped dependency, not a
production-ready renderer or packaged client.
## M9.2 native application and renderer boundary — 2026-10-01
Implemented ADR-0078, opt-in `evo-client`, bounded immutable presentation frames,
private main-thread SDL ownership, logical/drawable size separation, focus and
visibility/minimize handling, recoverable reset and terminal device-loss policy.
No camera, gameplay, protocol, simulation-state or deployment changes.
Executed:
- Fresh Windows Release: `tools/windows-check.ps1 -Preset client -Action check`
configured and built with MSVC 19.44; **3/3 client CTests passed** under NDEBUG.
Also ran `build/client/evo-client-lifecycle-tests.exe` with native Windows video,
then `evo-client.exe --frames 3` (default renderer) and `--renderer vulkan
--frames 3`; all returned success. Earlier combined probe/client configuration
passed 5/5 labeled tests.
- Linux GCC 14 Release in `build/client-probe-linux`: **5/5 combined probe/client
CTests passed**, as did native X11 lifecycle checks under Xvfb. The new suite executes 32
window/app destroy/recreate rounds, plus partial renderer initialization failure
and hidden-window/quit behavior. It covers copied-frame independence, finite
geometry/primitive limits, foreign events, focus, resize/scale queries,
non-unit anisotropic scale pixel readback, hide/minimize/resume, renderer
reset/loss and terminal close/error behavior.
- Clang 19 Debug ASan/UBSan: `cmake --preset asan -B build/client-asan
-DEVO_BUILD_CLIENT=ON -DCMAKE_CXX_COMPILER=clang++-19
-DCMAKE_C_COMPILER=clang-19 -DSDL_X11=ON -DSDL_WAYLAND=OFF`, built application
and lifecycle tests, **3/3 CTests passed**. Xvfb/X11 lifecycle executable also
passed with default leak detection, **no LD_PRELOAD or suppressions** after
adopting direct X11 linkage. Owned libraries, app and tests are instrumented;
SDL and system libraries are not comprehensively sanitizer-instrumented.
- Investigated M9.1's X11 unload issue: dynamically loaded X11 configuration left
1,700,544 bytes / 31,008 allocations reported at process exit in the repeated
fixture. Preloading libX11 avoided the report. SDL's supported
`SDL_X11_SHARED=OFF` fixes the observed repeated-lifecycle case by retaining the
linked system libraries for process lifetime. `ldd` confirms libX11 and libXext
dependencies; normal X11 sanitizer run passes. This is an adopted Linux build
constraint, not a claim to have repaired upstream Xlib or all native drivers.
- `clang-tidy-19 -p build/client-asan` on all five new C++ translation units:
passed with warnings-as-errors. Initial enum-size and multi-level pointer
conversion diagnostics were corrected. Repository `format-check` passed.
- Headless Release configured with **both client options OFF**, built `evo-sim`
and replayed seed 123456, eight entities, 1000 ticks: unchanged hash
`d61ad5bf0c928c76`, `replay_verified=true`. No SDL acquisition is part of this
configure/build path.
CI's isolated client stage now builds the actual app, runs static analysis and
labeled checks, exercises X11 lifecycles, then instruments owned code and repeats
software/X11 checks. No Docker build or remote Gitea execution was verified here.
No full headless suite rerun or TSan run: headless source did not change, and this
boundary requires single-main-thread use. Tests do not establish physical
multi-monitor DPI, real keyboard/focus behavior, Wayland, hardware GPU loss or
human visual acceptance. Those remain M9.3/M9.8 qualification work. No cluster
operation was performed.
+50
View File
@@ -0,0 +1,50 @@
#pragma once
#include "evo/render/frame.hpp"
#include <cstdint>
#include <expected>
#include <memory>
#include <string>
namespace evo::client {
enum class Error : std::uint8_t {
invalid_config,
already_open,
initialization,
window,
renderer,
surface,
draw,
device_lost
};
enum class Step : std::uint8_t { rendered, paused, closed };
struct Config {
int width{960}, height{640};
bool hidden{false};
std::string renderer; // Empty selects SDL's supported default; explicit names must succeed.
};
struct WindowState {
int logical_width{}, logical_height{}, pixel_width{}, pixel_height{};
float content_scale{1};
bool focused{}, minimized{}, hidden{}, closed{}, failed{};
[[nodiscard]] bool accepts_input() const noexcept {
return focused && !minimized && !hidden && !closed && !failed;
}
};
// One owner, process main thread only (including destruction). No SDL owner may coexist.
class Application {
public:
[[nodiscard]] static std::expected<std::unique_ptr<Application>, Error>
open(const Config& config);
~Application();
Application(const Application&) = delete;
Application& operator=(const Application&) = delete;
[[nodiscard]] WindowState state() const noexcept;
// Borrows the immutable frame for this call only. Errors latch until destruction.
[[nodiscard]] std::expected<Step, Error> step(const render::Frame& frame);
private:
struct Impl;
explicit Application(std::unique_ptr<Impl> impl);
std::unique_ptr<Impl> impl_;
};
} // namespace evo::client
+36
View File
@@ -0,0 +1,36 @@
#pragma once
#include <cstddef>
#include <cstdint>
#include <expected>
#include <span>
#include <vector>
namespace evo::render {
inline constexpr std::size_t max_rectangles = 4096;
struct Color {
std::uint8_t red{}, green{}, blue{}, alpha{255};
};
struct Rectangle {
float x{}, y{}, width{}, height{};
Color color;
};
enum class FrameError : std::uint8_t { too_many_primitives, invalid_geometry };
// Owns copied logical-window coordinates; never stores simulation/native handles.
class Frame {
public:
[[nodiscard]] static std::expected<Frame, FrameError>
create(std::span<const Rectangle> rectangles, Color background = {});
[[nodiscard]] std::span<const Rectangle> rectangles() const noexcept {
return rectangles_;
}
[[nodiscard]] Color background() const noexcept {
return background_;
}
private:
Frame(std::span<const Rectangle> rectangles, Color background)
: rectangles_(rectangles.begin(), rectangles.end()), background_{background} {}
std::vector<Rectangle> rectangles_;
Color background_;
};
} // namespace evo::render
+160
View File
@@ -0,0 +1,160 @@
#include "evo/client/application.hpp"
#include "render/sdl_renderer.hpp"
#define SDL_MAIN_HANDLED
#include <SDL3/SDL_main.h>
#include <cmath>
#include <optional>
#include <utility>
namespace evo::client {
namespace {
bool runtime_owned = false; // Process main-thread-only contract; no hidden threads.
struct Runtime {
bool acquired{false};
~Runtime() {
if (acquired) {
SDL_Quit();
runtime_owned = false;
}
}
};
} // namespace
struct Application::Impl {
Runtime runtime;
std::unique_ptr<SDL_Window, decltype(&SDL_DestroyWindow)> window{nullptr, SDL_DestroyWindow};
detail::Renderer renderer{nullptr, SDL_DestroyRenderer};
std::string renderer_name;
WindowState state;
std::optional<Error> failure;
std::expected<void, Error> refresh() {
if (!SDL_GetWindowSize(window.get(), &state.logical_width, &state.logical_height) ||
!SDL_GetWindowSizeInPixels(window.get(), &state.pixel_width, &state.pixel_height))
return std::unexpected(Error::surface);
state.content_scale = SDL_GetWindowDisplayScale(window.get());
if (!std::isfinite(state.content_scale) || state.content_scale <= 0 ||
state.logical_width < 0 || state.logical_height < 0 || state.pixel_width < 0 ||
state.pixel_height < 0 || state.logical_width > 32768 || state.logical_height > 32768 ||
state.pixel_width > 32768 || state.pixel_height > 32768)
return std::unexpected(Error::surface);
return {};
}
};
Application::Application(std::unique_ptr<Impl> impl) : impl_{std::move(impl)} {}
Application::~Application() = default;
WindowState Application::state() const noexcept {
auto result = impl_->state;
result.failed = impl_->failure.has_value();
return result;
}
std::expected<std::unique_ptr<Application>, Error> Application::open(const Config& config) {
if (config.width <= 0 || config.height <= 0 || config.width > 32768 || config.height > 32768 ||
config.renderer.size() > 64 || config.renderer.find('\0') != std::string::npos)
return std::unexpected(Error::invalid_config);
if (runtime_owned || SDL_WasInit(0) != 0)
return std::unexpected(Error::already_open);
auto impl = std::make_unique<Impl>();
SDL_SetMainReady();
impl->runtime.acquired = true;
runtime_owned = true;
if (!SDL_Init(SDL_INIT_VIDEO))
return std::unexpected(Error::initialization);
const auto flags = SDL_WINDOW_RESIZABLE | SDL_WINDOW_HIGH_PIXEL_DENSITY |
(config.hidden ? SDL_WINDOW_HIDDEN : 0);
impl->window.reset(SDL_CreateWindow("Aeternalis Evolution - engineering client", config.width,
config.height, flags));
if (!impl->window)
return std::unexpected(Error::window);
impl->renderer_name = config.renderer;
auto renderer = detail::make_renderer(impl->window.get(), impl->renderer_name);
if (!renderer)
return std::unexpected(renderer.error());
impl->renderer = std::move(*renderer);
const auto window_flags = SDL_GetWindowFlags(impl->window.get());
impl->state.focused = (window_flags & SDL_WINDOW_INPUT_FOCUS) != 0;
impl->state.minimized = (window_flags & SDL_WINDOW_MINIMIZED) != 0;
impl->state.hidden = (window_flags & SDL_WINDOW_HIDDEN) != 0;
if (auto result = impl->refresh(); !result)
return std::unexpected(result.error());
return std::unique_ptr<Application>{new Application{std::move(impl)}};
}
std::expected<Step, Error> Application::step(const render::Frame& frame) {
auto& p = *impl_;
if (p.failure)
return std::unexpected(*p.failure);
if (p.state.closed)
return Step::closed;
const auto id = SDL_GetWindowID(p.window.get());
bool reset = false;
SDL_Event event{};
for (int count = 0; count < 256 && SDL_PollEvent(&event); ++count) {
if (event.type == SDL_EVENT_QUIT)
p.state.closed = true;
if (event.type >= SDL_EVENT_WINDOW_FIRST && event.type <= SDL_EVENT_WINDOW_LAST &&
event.window.windowID == id) {
switch (event.type) {
case SDL_EVENT_WINDOW_CLOSE_REQUESTED:
p.state.closed = true;
break;
case SDL_EVENT_WINDOW_FOCUS_GAINED:
p.state.focused = true;
break;
case SDL_EVENT_WINDOW_FOCUS_LOST:
p.state.focused = false;
break;
case SDL_EVENT_WINDOW_MINIMIZED:
p.state.minimized = true;
break;
case SDL_EVENT_WINDOW_RESTORED:
case SDL_EVENT_WINDOW_MAXIMIZED:
p.state.minimized = false;
break;
case SDL_EVENT_WINDOW_HIDDEN:
p.state.hidden = true;
break;
case SDL_EVENT_WINDOW_SHOWN:
p.state.hidden = false;
break;
default:
break;
}
}
if (event.type >= SDL_EVENT_RENDER_TARGETS_RESET &&
event.type <= SDL_EVENT_RENDER_DEVICE_LOST && event.render.windowID == id) {
if (event.type == SDL_EVENT_RENDER_DEVICE_LOST)
p.failure = Error::device_lost;
else if (event.type == SDL_EVENT_RENDER_DEVICE_RESET)
reset = true;
}
}
if (p.failure)
return std::unexpected(*p.failure);
if (p.state.closed)
return Step::closed;
if (reset) {
p.renderer.reset();
auto renderer = detail::make_renderer(p.window.get(), p.renderer_name);
if (!renderer) {
p.failure = renderer.error();
return std::unexpected(*p.failure);
}
p.renderer = std::move(*renderer);
}
if (auto result = p.refresh(); !result) {
p.failure = result.error();
return std::unexpected(*p.failure);
}
if (p.state.hidden || p.state.minimized || p.state.logical_width == 0 ||
p.state.logical_height == 0 || p.state.pixel_width == 0 || p.state.pixel_height == 0)
return Step::paused;
if (auto result = detail::draw(p.renderer.get(), frame, p.state); !result) {
p.failure = result.error();
return std::unexpected(*p.failure);
}
if (!SDL_RenderPresent(p.renderer.get())) {
p.failure = Error::draw;
return std::unexpected(*p.failure);
}
return Step::rendered;
}
} // namespace evo::client
+17
View File
@@ -0,0 +1,17 @@
#include "evo/render/frame.hpp"
#include <cmath>
namespace evo::render {
std::expected<Frame, FrameError> Frame::create(std::span<const Rectangle> rectangles,
Color background) {
if (rectangles.size() > max_rectangles)
return std::unexpected(FrameError::too_many_primitives);
for (const auto& r : rectangles) {
if (!std::isfinite(r.x) || !std::isfinite(r.y) || !std::isfinite(r.width) ||
!std::isfinite(r.height) || std::abs(r.x) > 32768 || std::abs(r.y) > 32768 ||
r.width < 0 || r.height < 0 || r.width > 32768 || r.height > 32768)
return std::unexpected(FrameError::invalid_geometry);
}
return Frame{rectangles, background};
}
} // namespace evo::render
+32
View File
@@ -0,0 +1,32 @@
#include "sdl_renderer.hpp"
namespace evo::client::detail {
std::expected<Renderer, Error> make_renderer(SDL_Window* window, const std::string& name) {
Renderer result{SDL_CreateRenderer(window, name.empty() ? nullptr : name.c_str()),
SDL_DestroyRenderer};
if (!result)
return std::unexpected(Error::renderer);
if (!SDL_SetRenderDrawBlendMode(result.get(), SDL_BLENDMODE_BLEND))
return std::unexpected(Error::renderer);
return result;
}
std::expected<void, Error> draw(SDL_Renderer* renderer, const render::Frame& frame,
const WindowState& state) {
const auto bg = frame.background();
if (!SDL_SetRenderScale(
renderer,
static_cast<float>(state.pixel_width) / static_cast<float>(state.logical_width),
static_cast<float>(state.pixel_height) / static_cast<float>(state.logical_height)) ||
!SDL_SetRenderDrawColor(renderer, bg.red, bg.green, bg.blue, bg.alpha) ||
!SDL_RenderClear(renderer))
return std::unexpected(Error::draw);
for (const auto& r : frame.rectangles()) {
const SDL_FRect box{r.x, r.y, r.width, r.height};
if (!SDL_SetRenderDrawColor(renderer, r.color.red, r.color.green, r.color.blue,
r.color.alpha) ||
!SDL_RenderFillRect(renderer, &box))
return std::unexpected(Error::draw);
}
return {};
}
} // namespace evo::client::detail
+12
View File
@@ -0,0 +1,12 @@
#pragma once
#include "evo/client/application.hpp"
#include <SDL3/SDL.h>
#include <memory>
namespace evo::client::detail {
using Renderer = std::unique_ptr<SDL_Renderer, decltype(&SDL_DestroyRenderer)>;
[[nodiscard]] std::expected<Renderer, Error> make_renderer(SDL_Window* window,
const std::string& name);
[[nodiscard]] std::expected<void, Error> draw(SDL_Renderer* renderer, const render::Frame& frame,
const WindowState& state);
} // namespace evo::client::detail
+160
View File
@@ -0,0 +1,160 @@
#include "evo/client/application.hpp"
#include "render/sdl_renderer.hpp"
#include <SDL3/SDL.h>
#include <array>
#include <cmath>
#include <cstdio>
#include <limits>
#include <source_location>
#include <stdexcept>
#include <string>
#include <vector>
namespace {
using namespace evo::client;
void check(bool ok, std::source_location at = std::source_location::current()) {
if (!ok)
throw std::runtime_error("client lifecycle line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
template <typename T, typename E> bool refused(const std::expected<T, E>& result, E error) {
return !result && result.error() == error;
}
evo::render::Frame fixture() {
const std::array<evo::render::Rectangle, 1> rectangles{{{0, 0, 32, 32, {255, 0, 0, 255}}}};
auto result = evo::render::Frame::create(rectangles);
CHECK(result);
return std::move(result.value());
}
SDL_Window* window() {
int count{};
SDL_Window** windows = SDL_GetWindows(&count);
SDL_Window* result = count == 1 ? windows[0] : nullptr;
SDL_free(static_cast<void*>(windows));
CHECK(result);
return result;
}
void send(SDL_EventType type, SDL_WindowID id) {
SDL_Event event{};
event.type = type;
if (type >= SDL_EVENT_RENDER_TARGETS_RESET && type <= SDL_EVENT_RENDER_DEVICE_LOST)
event.render.windowID = id;
else
event.window.windowID = id;
CHECK(SDL_PushEvent(&event));
}
void frame_contract() {
using namespace evo::render;
std::array<Rectangle, 1> r{{{1, 2, 3, 4, {5, 6, 7, 255}}}};
const auto frame = Frame::create(r);
CHECK(frame);
r[0].x = 100;
CHECK(frame->rectangles()[0].x == 1); // Owns copy; caller mutation cannot alter it.
r[0].x = std::numeric_limits<float>::quiet_NaN();
CHECK(refused(Frame::create(r), FrameError::invalid_geometry));
r[0].x = 0;
r[0].width = -1;
CHECK(refused(Frame::create(r), FrameError::invalid_geometry));
r[0].width = std::numeric_limits<float>::infinity();
CHECK(refused(Frame::create(r), FrameError::invalid_geometry));
std::vector<Rectangle> full(max_rectangles);
CHECK(Frame::create(full));
full.emplace_back();
CHECK(refused(Frame::create(full), FrameError::too_many_primitives));
}
void pixels(SDL_Window* native, const evo::render::Frame& frame, WindowState state) {
auto* renderer = SDL_GetRenderer(native);
CHECK(renderer);
// Exercise non-unit, anisotropic drawable scaling without requiring a HiDPI monitor.
state.logical_width = state.pixel_width / 2;
state.logical_height = state.pixel_height;
CHECK(detail::draw(renderer, frame, state));
const std::unique_ptr<SDL_Surface, decltype(&SDL_DestroySurface)> surface{
SDL_RenderReadPixels(renderer, nullptr), SDL_DestroySurface};
CHECK(surface);
Uint8 r{}, g{}, b{}, a{};
CHECK(SDL_ReadSurfacePixel(surface.get(), 48, 8, &r, &g, &b, &a));
CHECK(r == 255 && g == 0 && b == 0 && a == 255);
CHECK(SDL_ReadSurfacePixel(surface.get(), 80, 8, &r, &g, &b, &a));
CHECK(r == 0 && g == 0 && b == 0 && a == 255);
CHECK(SDL_ReadSurfacePixel(surface.get(), 8, 48, &r, &g, &b, &a));
CHECK(r == 0 && g == 0 && b == 0 && a == 255);
}
void lifecycle() {
const auto frame = fixture();
CHECK(refused(Application::open({0, 64, false, "software"}), Error::invalid_config));
CHECK(refused(Application::open({64, 64, false, "evo-invalid"}), Error::renderer));
CHECK(SDL_WasInit(0) == 0); // Failed partial initialization released SDL.
for (int round = 0; round < 32; ++round) {
auto result = Application::open({160, 120, false, "software"});
CHECK(result);
auto app = std::move(result.value());
CHECK(refused(Application::open({}), Error::already_open));
CHECK(app->step(frame) == Step::rendered);
auto* native = window();
pixels(native, frame, app->state());
const auto id = SDL_GetWindowID(native);
// Foreign close/reset must not affect the one owned window.
send(SDL_EVENT_WINDOW_CLOSE_REQUESTED, id + 1);
send(SDL_EVENT_RENDER_DEVICE_LOST, id + 1);
send(SDL_EVENT_WINDOW_FOCUS_GAINED, id);
CHECK(app->step(frame) == Step::rendered);
CHECK(app->state().accepts_input());
send(SDL_EVENT_WINDOW_FOCUS_LOST, id);
CHECK(app->step(frame) == Step::rendered);
CHECK(!app->state().accepts_input());
send(SDL_EVENT_WINDOW_MINIMIZED, id);
CHECK(app->step(frame) == Step::paused);
send(SDL_EVENT_WINDOW_RESTORED, id);
CHECK(app->step(frame) == Step::rendered);
CHECK(SDL_SetWindowSize(native, 240, 180));
send(SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED, id);
send(SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED, id);
CHECK(app->step(frame) == Step::rendered);
int lw{}, lh{}, pw{}, ph{};
CHECK(SDL_GetWindowSize(native, &lw, &lh));
CHECK(SDL_GetWindowSizeInPixels(native, &pw, &ph));
const auto state = app->state();
CHECK(state.logical_width == lw && state.logical_height == lh);
CHECK(state.pixel_width == pw && state.pixel_height == ph);
CHECK(std::isfinite(state.content_scale) && state.content_scale > 0);
send(SDL_EVENT_RENDER_TARGETS_RESET, id);
CHECK(app->step(frame) == Step::rendered);
send(SDL_EVENT_RENDER_DEVICE_RESET, id);
CHECK(app->step(frame) == Step::rendered);
CHECK(SDL_HideWindow(native));
send(SDL_EVENT_WINDOW_HIDDEN, id);
CHECK(app->step(frame) == Step::paused);
CHECK(SDL_ShowWindow(native));
send(SDL_EVENT_WINDOW_SHOWN, id);
CHECK(app->step(frame) == Step::rendered);
if (round % 2 == 0) {
send(SDL_EVENT_RENDER_DEVICE_LOST, id);
CHECK(refused(app->step(frame), Error::device_lost));
CHECK(refused(app->step(frame), Error::device_lost));
CHECK(app->state().failed && !app->state().accepts_input());
} else {
send(SDL_EVENT_WINDOW_CLOSE_REQUESTED, id);
CHECK(app->step(frame) == Step::closed);
CHECK(app->step(frame) == Step::closed);
}
app.reset();
CHECK(SDL_WasInit(0) == 0);
}
auto hidden = Application::open({64, 64, true, "software"});
CHECK(hidden);
CHECK((*hidden)->step(frame) == Step::paused);
send(SDL_EVENT_QUIT, 0);
CHECK((*hidden)->step(frame) == Step::closed);
}
} // namespace
int main() try {
frame_contract();
lifecycle();
return 0;
} catch (const std::exception& e) {
std::fprintf(stderr, "%s: %s\n", e.what(), SDL_GetError());
return 1;
} catch (...) {
return 1;
}
+1 -1
View File
@@ -1,5 +1,5 @@
param(
[ValidateSet('debug', 'release', 'analysis', 'asan', 'tsan')]
[ValidateSet('debug', 'release', 'analysis', 'asan', 'tsan', 'client', 'client-probe')]
[string]$Preset = 'debug',
[ValidateSet('configure', 'build', 'test', 'format', 'check')]
[string]$Action = 'check'