Files
aevolution/docs/adr/0078-native-client-lifecycle.md
T
2026-10-08 12:08:53 -04:00

52 lines
2.7 KiB
Markdown

[Reviewed]
# 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.