Implement M9.1 scoped SDL3 native client dependency probe
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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,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`).
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user