Record M9.8 decisions and scoped client delivery plan

This commit is contained in:
dingo
2026-10-02 07:37:13 -04:00
parent 7ac587743c
commit 4d6a2b6d83
5 changed files with 152 additions and 0 deletions
+6
View File
@@ -454,6 +454,12 @@ terrain meshing or procedural creature animation is required.
| 9.7 Connect to one authoritative dev region | src/client/session, src/server/session adapter | 9.6, M8-dev/stage | Real desktop-to-server connection, snapshot display and minimal admitted intent; reconnect requests fresh baseline; final outcomes reflect durable server ACK | Disconnect/reconnect, stale epoch, server pod restart, rejected intention and duplicate session tests | Client state or reconnect becomes authority |
| 9.8 Validate presentation and package the client | tools/client packaging, tests/client, docs/engineering | 9.1-9.7 | Reproducible native artifact, bounded snapshot/render queues, frame/memory report and documented manual visual checks | Install/run on supported dev platforms; long session, resolution/DPI matrix, headless regression suite | Declaring FUN or multiplayer scalability from a viewer |
**M9.8 planning (2026-10-02):** user-confirmed Windows ZIP, temporary Gitea Actions
artifacts, labelled engineering UI/launcher and control rebinding. See the
[delivery segments](engineering/M9_8_DELIVERY_PLAN.md) and proposed ADR-0084.
Low-spec VM qualification and live cluster evidence remain outstanding; neither
is implied by packaging completion.
**Exit:** a packaged native client opens, renders an authoritative cellular development
scene, submits a bounded test intention and recovers its view after the server restarts.
The prototype session respects server authority and ownership epochs. M10 owns the
+68
View File
@@ -0,0 +1,68 @@
# ADR-0084: Engineering UI toolkit and ownership boundary
## Status
Proposed, 2026-10-02. User authorized evaluating/adopting a maintained framework.
Preferred candidate: Dear ImGui for the engineering client only. Adoption requires
an exact source pin, licence inventory and Windows/Linux compatibility probe in
M9.8a. No dependency has been added by this ADR. Final player UI remains undecided.
## Context
M9.4/M9.5 intentionally used rectangles and unlabelled gauges. M9.8 now requires
readable text, a launcher, dialogs, dismissible notifications, click selection and
control rebinding. The existing client uses SDL3 and SDL_Renderer. The headless
libraries and immutable biological views must remain toolkit-independent.
## Decision proposed
Use Dear ImGui's upstream SDL3 platform and SDL_Renderer3 rendering adapters behind
the private native client boundary. Implement owned application state for toasts,
selection, dialogs and action bindings; do not equate toolkit widget state with
simulation or session authority. Reuse toolkit text, input, layout and widgets
instead of implementing those primitives. Disable unnecessary multi-window features.
Keep public biological/render snapshot contracts free of ImGui and SDL types.
Toolkit initialization follows the window/renderer; shutdown precedes their teardown.
UI capture is resolved before generating world intentions. Document and test event
ordering, focus loss, modal capture and binding changes together with API changes.
Before merge of integration: choose a reviewed release supported by its actual
source history (not an assumed latest version), record source commit/archive hash,
retain MIT licence and embedded font/third-party notices, build only needed sources,
measure incremental artifact size and idle/frame cost, and verify lifecycle on both
supported toolchains. Normal configure must not download dependencies. Use explicit
preparation and pinned sources as in ADR-0077; no new general package manager.
## Alternatives considered
| Option | Assessment |
|---|---|
| Dear ImGui | C++ widget API and upstream SDL3/SDL_Renderer adapters fit the current engineering client. Low integration surface; immediate-mode work and accessibility limitations need measurement/review. Preferred. |
| RmlUi | Retained documents and styling could suit final game interfaces. Integration adds document/assets/font and render-interface work; no demonstrated M9 benefit over the existing renderer path. Keep as a later product-UI candidate. |
| Custom text/widgets | Avoids a toolkit dependency but requires fonts, editing, focus, layout and popup behavior to be built and maintained; rejects the user's preference for an established framework. |
These are integration assessments, not measured performance or binary-size rankings.
## Benefits
Readable engineering tools, reusable interaction primitives and narrow dependencies.
The simulation stays independent and the final game UI is not prematurely selected.
## Costs
New pinned source and licence obligations, text/atlas resource lifetime, input capture
integration and Windows/Linux visual validation. Toast/binding policies remain ours.
## Risks
Toolkit input capture can leak movement or selection if handled after world input.
Immediate-mode UI is not a hard frame-time guarantee. Font/DPI/accessibility behavior
requires real review. Dependency versions and notices must be checked in the pinning
segment, not inferred from this high-level comparison.
## Consequences
Revisits ADR-0081's scoped decision to defer ImGui once labelled engineering UI is
needed. M9.8a must change this status to accepted only with the pin and probe evidence.
M9.8 delivery is tracked in ../engineering/M9_8_DELIVERY_PLAN.md.
## Primary-source evidence reviewed 2026-10-02
- https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md — upstream SDL3 and SDL_Renderer3 adapters; platform/render separation.
- https://github.com/ocornut/imgui/blob/master/LICENSE.txt — MIT licence; pin-time notice audit still required.
- https://github.com/ocornut/imgui/blob/master/docs/FAQ.md — input capture guidance and integration responsibilities.
- https://github.com/ocornut/imgui/releases — release/maintenance evidence; no version selected here.
- https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html — context and rendering integration requirements for the alternative.
+2
View File
@@ -95,3 +95,5 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0081: Organism presentation](0081-organism-presentation.md) - biology-only organism cells without controller labels, budgeted rendering with explicit truncation and an engineering gauge inspector; ImGui deferred.
- [ADR-0082: Dev session transport](0082-dev-session-transport.md) - TLS 1.3-only Mbed TLS 4.1.1 LTS (pinned, compiled-down), dev-only HMAC grants, versioned bounded protocol v1 and session admission for M9.
- [ADR-0083: Dev region sessions](0083-dev-region-sessions.md) - session server in evo-server, durable no-effect intentions on synthetic carriers, empty organism presentation, reconnect with fresh baselines, loopback-only drill-time dev deployment.
- [ADR-0084: Engineering UI toolkit](0084-engineering-ui-toolkit.md) - proposed Dear ImGui boundary; adoption waits for the exact pin and compatibility probe.
+68
View File
@@ -0,0 +1,68 @@
# M9.8 delivery plan
Status: planned; user choices recorded 2026-10-02. No implementation or deployment
is claimed by this document. See ADR-0084 for the proposed UI toolkit boundary.
## Confirmed scope
- Native Windows x64 ZIP is the primary tester artifact. Linux remains a build/test
target; no browser client or Steam integration.
- Gitea Actions artifacts are the temporary download location. Later publication
uses a CDN backed by rebuilt Ceph/MinIO storage. Packaging must be independent of
its eventual hosting provider. No auto-updater in this gate.
- Readable field names, units, legends, connection state and inspector values;
shared dialogs, dismissible toasts, click selection and rebindable controls.
- Startup panel offers Local fixture and Connect to dev, with endpoint and
credential-file selection. Fixture mode is clearly labelled. Remote mode shows
the server's empty organism layer honestly until placed organisms exist.
- User will provide a low-spec VM. Measure first; minimum hardware and performance
claims remain unqualified until CPU/RAM/GPU/OS/DPI are recorded and tested.
- Live cluster restart evidence is explicitly deferred by the user. Local packaging
qualification can complete independently; M9's live-deployment evidence remains open.
- Cluster uses MetalLB and nginx. User reports 172.10.1.160 reachable from the
development machine, with deployment through existing Gitea/GitOps machinery.
Whether this address belongs to a node or the ingress service is unconfirmed.
- Available DNS names: sys, void, srs, cloud, assets under aeternalisgames.com.
No assignment or route is implemented. Proposed dev session name: void; proposed
future download name: assets. DNS existence is not evidence of service reachability.
## Reviewable implementation segments
Commit and push each completed, validated segment. These rows extend M9.8; they
must not be interpreted as implemented merely because a design exists.
| Segment | Objective / affected modules | Dependencies | Completion and tests | Principal risk |
|---|---|---|---|---|
| 9.8a | Pin and integrate scoped UI toolkit: ADR, third_party, tools, cmake, private client adapter | ADR-0084 proposal | Verify exact version/license/hash; opt-in preparation; Windows/Linux text/widget probe; clean teardown; headless configure unchanged | UI types leak into simulation or renderer-independent contracts |
| 9.8b | Owned UI state, dialogs, bounded dismissible notifications: src/client/ui, application adapter, tests | a | Explicit modal focus, notification expiry/dismissal/overflow; bounded event draining; tests under event bursts and reconnect | Toasts conceal durable outcomes or queues grow indefinitely |
| 9.8c | Launcher, resource legend, labelled inspector, click selection: apps/evo-client, UI, tests | a-b | Fixture/live distinction, invalid credentials give bounded errors, cancel/retry, selected organism disappearance clears selection, zero/missing/stale remain distinct; visual review | Displaying fictional state or logging credentials |
| 9.8d | Rebindable controls: input contracts, platform adapter, configuration, tests | b-c | Actions separated from physical keys; conflict validation; reset defaults; UI capture/key release/focus loss cannot cause movement; malformed config rejected | Stuck actions and click-through while interacting with UI |
| 9.8e | Reproducible Windows ZIP: tools/client, CMake, Gitea workflow | c-d, runner availability | Stage explicit runtime files, licences, build identity and checksum manifest; no credentials; extract/run on clean Windows; publish Actions artifact | Missing DLLs/runtime prerequisites or secrets packaged accidentally |
| 9.8f | Dev TCP route design and optional deployment: ADR, dev overlay, policy tests | Confirm endpoint/controller/port and access policy | Reconcile loopback-only ADR-0083 with deliberate dev-only exposure; TLS passthrough, verified server name, scoped grants, fail-closed policy tests; actual connectivity recorded separately | Exposing development identity or widening World0 access |
| 9.8g | Qualification report: tools, tests, engineering docs | b-e, test VM | Record frame-time percentiles, memory after warm-up, queue high-water, prolonged run, DPI/resolution/input matrix, headless regression; publish actual limits | Calling an unaccelerated VM result a universal hardware requirement |
## UI and input invariants
Toolkit events are processed on the application thread. Dialogs and binding capture
consume relevant input before world intentions or selection are generated. Opening
UI/focus loss releases active world actions; closing it does not synthesize held
keys. A click that dismisses a toast or operates a widget must not select through it.
A transient toast is not the authoritative record of an intention outcome. Keep a
bounded, inspectable session status/outcome model even if notifications expire.
No credentials, grant payloads, or private keys in notifications, logs, config or ZIPs.
Use bounded path inputs; retain file references rather than persisting grant bytes.
All selected biological data remains a read-only presentation copy.
## Infrastructure and packaging decisions still needed
- Windows runner label/toolchain availability. Do not silently route a Windows
package job to the existing Linux runner or assume an untested cross-compile.
The packaging script can run on the existing Windows development host meanwhile.
- Exact role of 172.10.1.160, nginx implementation/configuration, exposed TCP port,
source restrictions and certificate name. The protocol is TLS/TCP, not HTTP;
a standard HTTP Ingress rule does not implement it. Port-forward remains supported.
- VM specification and whether graphics acceleration is available. Hardware-specific
performance acceptance cannot be declared before these are known.
- CDN origin/access/retention decisions wait for the storage rebuild. They do not
block local ZIPs or temporary Actions artifact downloads.
+8
View File
@@ -3594,3 +3594,11 @@ Not rerun: Docker/Gitea, full PostgreSQL process suite, fuzzing, TSan, or live c
operations. No deployment performed. The text ledger detects malformed framing,
not syntactically valid corruption or deletion of entire records; ADR-0083 now states
that integrity limit explicitly. Client event-list bounds remain M9.8 work.
## 2026-10-02 — M9.8 decision capture and delivery segmentation
Recorded confirmed platform/distribution/UI choices and deferred VM/cluster evidence
in M9_8_DELIVERY_PLAN.md. ADR-0084 proposes the UI boundary and comparison; no library
version or dependency was adopted. Reviewed upstream toolkit documentation, checked
repository-relative links and git diff --check. Documentation only: no code tests,
package build, runner execution, endpoint verification or deployment performed.