Implement M9.1 scoped SDL3 native client dependency probe

This commit is contained in:
dingo
2026-10-01 11:18:46 -04:00
parent 26056b7c9f
commit d487d86ea3
20 changed files with 429 additions and 5 deletions
+5
View File
@@ -389,6 +389,11 @@ JetStream is adopted only for a demonstrated delivery workload, not as lease aut
## M9 - Custom 2D engineering client
**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.
**Goal:** a native desktop cellular viewer/controller with input, camera, renderer,
readable organism/environment views and a real development-server connection.
It is an engineering client, not the M11 playable game or the M13 3D engine.
+14
View File
@@ -1,5 +1,19 @@
# Project status and next steps
## 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.
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.
The sections below retain earlier milestone delivery history.
Updated 2026-09-27. The repository contains an engineering foundation and a
deterministic headless proof. It does not yet contain cellular gameplay or a
persistent simulation server. The founding vision remains unchanged.
+2 -1
View File
@@ -2,7 +2,8 @@
## Status
Dependency-free proof adopted; vcpkg manifest proposed at first dependency gate.
Dependency-free proof adopted; general package-manager comparison remains open.
ADR-0077 accepts a scoped explicit-source SDL dependency for M9 only.
## Context
@@ -0,0 +1,74 @@
# ADR-0077: Scoped native 2D client dependencies
## Status
Accepted for M9.1's isolated probe and M9 engineering client. No final 3D renderer,
audio, UI toolkit, physics engine or transport is selected here.
## Context
M9 needs a native Windows/Linux window, input events and simple 2D primitives.
The headless libraries must configure, build and run without graphical dependencies.
M6 views already expose immutable value data; no SDL types belong in those APIs.
## Decision
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.
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,
Direct3D11 or software without silently substituting another backend. Disable
unused audio, camera, joystick, haptic, sensor and SDL_GPU subsystems. Keyboard and
mouse events remain. Audio and final UI are explicitly deferred.
This is a scoped amendment to ADR-0003, following the explicit-source approach
already used for PostgreSQL: do not require adoption of a general package manager
for one self-contained client dependency. vcpkg/Conan measured comparison remains
open before a broader dependency graph. No claim is made that either was benchmarked.
Archive preparation can use an existing verified download for offline rebuilds.
## Alternatives considered
| Option | Value | Cost / disposition |
|---|---|---|
| SDL3 + direct Vulkan | Explicit resource/synchronization control and future compute | Swapchain, shaders, pipeline and allocator work exceeds this 2D gate; defer to measured need / M13 |
| SDL3 + SDL_GPU | Portable explicit GPU API with shader pipelines | Shader build/distribution and more resource lifetime work; useful later, not required for basic views |
| SDL3 + SDL_Renderer | Window/events plus accelerated primitives and textures from one dependency | Less pipeline control; selected for scoped 2D client, not a permanent engine-wide abstraction |
| GLFW + Vulkan | Narrow window/input layer | Still needs the renderer work above and another dependency choice; no demonstrated M9 advantage |
| vcpkg manifest | Baselines/features and strong CMake/MSVC integration | Broader tool bootstrap/registry governance for one archive; remains a candidate |
| Conan lockfile | Profiles, binary packages and revision locks | Python/recipe/tool bootstrap and profile governance; remains a candidate |
These are scope/maintenance comparisons, not measured performance rankings.
The probe records actual backend, SDL version and execution result; size/build
measurements and platform limits belong in the M9.1 validation record.
## Benefits
One established C API with explicit return checks, uncomplicated RAII adapters and
small review surface for generated C++. No engine dependency and no changes to
simulation rules, formats or public headers. Software rendering permits CI pixel
checks without pretending to test a GPU driver.
## Costs
Shared-library packaging and license retention; platform-specific SDL build options
and system video libraries. Main-thread event/render calls. A later renderer may
replace the private adapter rather than inherit an unsuitable 2D abstraction.
## Risks
Backend-dependent pixels/performance, driver availability, DPI/event differences,
untrusted asset decoders and dependency updates. Synthetic event injection proves
queue plumbing only; actual keyboard/focus/DPI acceptance stays in M9.2/M9.3.
No user assets are decoded by this probe. Retain upstream third-party notices
alongside the SDL license for distribution; audit the enabled build at packaging.
## Consequences and evidence
Preparation is explicit; missing sources fail with instructions. An ordinary
headless configure never evaluates SDL. Upgrades change version and hash together,
rerun platform probes and review upstream changes. Client rendering is approximate
presentation, never authoritative biological state.
Primary sources checked 2026-10-01:
- [SDL 3.4.16 release](https://github.com/libsdl-org/SDL/releases/tag/release-3.4.16): stable bugfix release, active release maintenance.
- [SDL 2D API](https://wiki.libsdl.org/SDL3/CategoryRender): primitives/textures and main-thread requirement.
- [SDL GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU): alternative explicit pipeline API.
- License/build/platform documentation is retained in the pinned source archive
(`LICENSE.txt`, `docs/README-cmake.md`, `docs/README-platforms.md`).
+2
View File
@@ -87,3 +87,5 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0074: World backup bundles and verified restore](0074-world-backup-and-restore.md) - accepted for M8.7 snapshot-consistent online bundles (dump + immutable objects + manifest), fail-closed audited restore on independent storage, isolated rebuild through clones; destination, encryption, schedule and WAL archiving pending.
- [ADR-0075: World0 acknowledgment gate, host-loss recovery and promotion](0075-world0-acknowledgment-gate.md) - accepted for M8.8 ratified dev/stage RPO/RTO, World0 launch blocked (policy-enforced) until acknowledgements survive host loss in an independent failure domain, explicit-rewind in-place restore, barrier-based fencing of a superseded database, promotion only of stage-pinned digests.
- [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.
+69
View File
@@ -0,0 +1,69 @@
# M9.1 native client dependency probe
Decision: [ADR-0077](../adr/0077-scoped-native-client-dependencies.md). This is an
isolated dependency evaluation, not `evo-client`, gameplay or the M9.2 renderer.
SDL 3.4.16 provides window/events and a thin 2D renderer. Direct Vulkan and SDL_GPU
remain alternatives if measured workloads outgrow it. Audio and player UI are deferred.
## Reproduce
In a C++23 developer shell with CMake 3.28+ and Ninja:
```sh
cmake -P tools/prepare-sdl3.cmake
cmake --preset client-probe
cmake --build --preset client-probe --parallel 4
ctest --preset client-probe --no-tests=error
./build/client-probe/evo-client-probe
./build/client-probe/evo-client-probe --renderer vulkan
```
Windows executables have `.exe`. CTest uses SDL's dummy window driver and software
renderer for deterministic rectangle/background pixel checks. The standalone run
uses the native video driver and reports the actual renderer. The window is hidden
and the process exits after one checked frame; no persistent desktop window is left.
An explicitly requested missing renderer must fail, not silently fall back.
Synthetic keyboard injection proves event plumbing, not physical input/focus behavior.
Linux desktop builds require SDL's documented X11/Wayland development packages.
The `ci-client` Docker stage installs the X11 subset and runs a window probe under
Xvfb, in addition to dummy-driver CTests. It does not require a GPU or cluster.
For a CI host without these, explicitly add `-DSDL_UNIX_CONSOLE_BUILD=ON
-DSDL_X11=OFF -DSDL_WAYLAND=OFF`. That configuration proves software/offscreen
behavior only. Do not use it to claim Linux desktop-window qualification.
Offline preparation from a previously downloaded archive:
```sh
cmake -DSDL_ARCHIVE=/absolute/path/SDL3-3.4.16.tar.gz -P tools/prepare-sdl3.cmake
```
The script checks the archive before extraction. Sources go under ignored
`build/external/sdl3/`; configuration consumes only prepared sources and refuses
a missing/mismatched preparation marker. Treat that directory as an immutable
local dependency checkout; edits there invalidate qualification. Delete/reprepare
it explicitly for a clean rebuild. No network access occurs during configuration.
## Ownership, licensing and updates
- Machine-readable release URL/version/hash: `tools/sdl3-pin.cmake`.
- Owner: client/platform engineering. Upgrade by reviewing upstream release and
security changes, updating version/hash, preparing fresh sources and rerunning
Windows/Linux probes, analysis and package measurements.
- SDL's zlib notice is retained in `third_party/SDL3/LICENSE.txt`; the complete
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
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.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.
+54
View File
@@ -3133,3 +3133,57 @@ as proof of rollback.
layers deep and only the outer layer is tested.
- Not run: a real network partition around COMMIT. The lost acknowledgement is an
injected test mode (`EVO_RESTORE_TEST_INSTALL_ACK`).
## M9.1 scoped native dependency probe — 2026-10-01
Decision: ADR-0077. SDL 3.4.16 shared window/events/2D renderer, explicitly
prepared from the official archive with SHA-256 validation. No simulation API,
world format, server image or deployed workload changed.
Executed:
- Windows x64 MSVC 19.44: fresh `client-probe` configure/build and 2/2 labeled
CTests passed. Native standalone probes reported `video=windows` with both
`renderer=direct3d11` (automatic) and explicitly requested `renderer=vulkan`;
synthetic key delivery and rectangle/background pixel readback passed.
Developer environment required explicit compiler and Windows SDK tool paths.
- WSL Ubuntu, GCC 14 Release: configured the same preset in
`build/client-probe-linux` with `SDL_X11=ON`, `SDL_WAYLAND=OFF`; build and 2/2
client CTests passed. `xvfb-run -a env SDL_VIDEO_DRIVER=x11
./build/client-probe-linux/evo-client-probe --renderer software` passed.
X11 development dependencies are reproduced in Docker's `ci-client` stage.
- clang-tidy 19 standalone against `experiments/client/main.cpp`, C++23 and the
prepared SDL include directory: no owned-code diagnostics. Initial use of the
GCC compilation database failed on GCC module options; rerun used explicit
Clang arguments. Repository `format-check` passed.
- Clang 19 ASan/UBSan build of the owned probe, linked to the Release SDL shared
library: dummy video/software renderer passed. SDL itself was not instrumented.
**Additional X11 sanitizer run failed LeakSanitizer:** 50,016 bytes in 912
allocations remained at exit; resolved SDL call sites included
`X11_InitKeyboard` and `X11_GetGlobalContentScale`, with underlying unloaded
library frames unresolved. This is not a proven application leak or a clean
native sanitizer result. Do not suppress or declare it fixed. M9.2 must reproduce
with symbolized native libraries and establish repeated window-lifecycle memory
behavior before desktop qualification.
Diagnostic rerun with `LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libX11.so.6`
passed with leak detection enabled. Keeping libX11 loaded changes the result,
suggesting library unload/static allocation reachability; it does not establish
that repeated native lifecycles are leak-free. No suppression was added.
- Headless Release, client disabled: configured/built `evo-sim`; seed 123456,
eight entities, 1,000 ticks and `--verify-replay` passed, hash `d61ad5bf0c928c76`.
- Offline cached archive preparation passed; deliberately invalid archive was
rejected with checksum mismatch before extraction. CI selector regression:
all 12 fixtures passed, including an SDL pin change selecting the client gate.
- Artifact sizes (not comparable performance measurements): Windows executable
14,336 bytes + SDL3.dll 1,998,848; Linux X11 executable 17,624 bytes + shared SDL
3,304,808. Build configurations/backend sets differ. No throughput or cold-build
benchmark claim is made.
Limits: synthetic keyboard events only; hidden Windows window and virtual Linux
X11 display. No human visual inspection, real input/focus/DPI, Wayland or Linux
GPU qualification. A Linux offscreen GLES attempt failed because the environment
could not initialize OpenGL/GLES. No full headless CTest rerun, TSan, Docker build,
remote Gitea run or Kubernetes action was performed for this gate. The new client
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.