From 4d6a2b6d8380dcf4290441cb42ebdd472b848bfe Mon Sep 17 00:00:00 2001 From: dingo Date: Fri, 2 Oct 2026 07:37:13 -0400 Subject: [PATCH] Record M9.8 decisions and scoped client delivery plan --- docs/ROADMAP.md | 6 +++ docs/adr/0084-engineering-ui-toolkit.md | 68 +++++++++++++++++++++++++ docs/adr/README.md | 2 + docs/engineering/M9_8_DELIVERY_PLAN.md | 68 +++++++++++++++++++++++++ docs/engineering/VALIDATION.md | 8 +++ 5 files changed, 152 insertions(+) create mode 100644 docs/adr/0084-engineering-ui-toolkit.md create mode 100644 docs/engineering/M9_8_DELIVERY_PLAN.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 853dce1..ce45cb0 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -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 diff --git a/docs/adr/0084-engineering-ui-toolkit.md b/docs/adr/0084-engineering-ui-toolkit.md new file mode 100644 index 0000000..881a721 --- /dev/null +++ b/docs/adr/0084-engineering-ui-toolkit.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index 71f8ff5..310658f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. diff --git a/docs/engineering/M9_8_DELIVERY_PLAN.md b/docs/engineering/M9_8_DELIVERY_PLAN.md new file mode 100644 index 0000000..9aad587 --- /dev/null +++ b/docs/engineering/M9_8_DELIVERY_PLAN.md @@ -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. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index a0d23b3..ca6fcd8 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -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.