15 KiB
Step-05 - First configurable numeric/bar live dashboard
STEP IDENTIFIER
Step-05. Corrected Step-04/04A/04B were accepted on 2026-10-28. This is the sole active implementation assignment.
STEP TITLE
Display configurable numeric and bar gauges from one session-owned diagnostic acquisition feed, with explicit missing/stale/uncertain/range states.
OBJECTIVE
One user outcome: configure and observe a small live dashboard on an existing explicitly opened static or dynamics diagnostic session. One primary new behavioral contract: a shared session-bound acquisition owner, independent of gauge visibility. Gauge configuration is validated in-memory data, not a new persisted format or another application subsystem.
Read WORKER-QUALITY-GATE.md, apply the frozen matrix
below before coding, self-review after the first green run, write
prompts/Step-05-Report.md, and STOP for manual review.
ARCHITECTURAL CONTEXT
Read STATE.md, architecture, protocol v1 and v2.
Keep all nine projects and one native MAUI Client. Components owns generic pure UI controls and has no AutoForge project reference. Application owns feed/ configuration use cases using Diagnostics ports. UI owns composition/editor/ interaction. Client is DI/lifecycle only. No new host, project, package or Application/UI dependency on Simulation implementation.
All source/tests remain under src, tests under src/tests. Root project
directories remain docs, src, prompts. Manual handoff/protected/history
rules in the shared gate remain mandatory.
CURRENT IMPLEMENTATION STATE
Accepted features already provide:
- Exact profile/configuration/provider/session selection; static v1 and dynamics v2 providers; validated identity/service discovery and actual encoded reads.
- DiagnosticSignal/SignalSnapshot values, units, quality, synthetic origin, request time and v2 model/config/run context.
- Existing
/diagnosticsand/simulationworkflows with owned ActiveSession, explicit close/reset, actual telemetry reads and current-generation guards. - StatusNotice and headless HtmlRenderer/real-DI integration tests.
Worker-reported baseline: clean complete nine-project Release build; 126 unit + 81 integration passes (207 total, zero failed/skipped), numerical gates and native baseline smoke. No chart/dashboard acquisition service exists yet. The orchestrator did not rerun those checks.
Reuse DiagnosticSession and current host feature view models. Do not duplicate profile/provider opening, physics, protocol/version or virtual-clock behavior. Inspect actual code/Git before editing and preserve existing dirty work and historical reports.
REQUIRED IMPLEMENTATION
Frozen contract matrix
These are the acceptance outcomes, not examples to replace with weaker proxies.
| ID | Input/precondition | Required result |
|---|---|---|
| C-01 | Good finite 850 rpm; display 0..1000, decimals 0 | Numeric displays 850 with rpm; bar projects 85%; actual source/context retained. Legitimate numeric zero displays zero, not missing. |
| C-02 | Finite value below/above display range, e.g. -10 or 1100 | Preserve actual numeric value; clamp bar geometry only to 0/100%, with explicit low/high indication. No fabricated in-range reading. |
| C-03 | Null/missing/non-numeric value or Unknown quality; finite Uncertain quality | Unknown/unavailable shows -- and reason, not zero/current bar. Uncertain finite data may display only with an explicit warning state, never Good. |
| C-04 | Invalid definition/range/precision/binding/unit/count | Typed visible rejection before mutation; previous valid definitions/source/feed stay intact. Include finite-span overflow as well as NaN/infinity/min>=max. |
| C-05 | Repeated Start on same running feed; Start while Stop drains; retry after Stop | First is idempotent with one owner; draining Start rejects before mutation; Stop cancels/awaits cleanup; retry starts one owner. |
| C-06 | Source close/reset/replacement or late reply from old generation | Old owner/resources stop; old values do not appear in the new context. Pending new data is explicit; no global active-source fallback or stale publication. |
| C-07 | Gauges hidden/removed/re-rendered/disposed while source monitoring remains open | Acquisition continues independently. Widget disposal only removes its subscription; explicit monitoring stop/source close/owning scope disposal ends acquisition. |
| C-08 | Last good value followed by read failure; no previous value; later recovery/stop | Retain a value only as clearly last-known Stale with failure/source time. With no valid prior value show Error/--. Recovery restores correct state. Stopped data is not labeled live. |
| C-09 | Multiple gauges bind signals on the same module; controlled polling; paused dynamics | One read.signals per eligible module per dashboard poll, not per gauge/render. Polling does not advance physics; v1 static and v2 dynamic source/time semantics are preserved. |
| C-10 | Real host UI configure/edit/hide/stop/reset/close and current error cases | Same actual Application feed/validated definitions/pure components are used. No mock live data, oracle read, shell restructuring or hidden owner. |
A. Small validated in-memory dashboard
Support zero to eight gauges using numeric or horizontal-bar type, a stable unique gauge ID, label, explicit module/signal binding, exact reported unit, finite minimum/maximum with finite positive span, and integer decimal precision 0..3. Copy definitions; reject duplicate IDs/undefined kinds/invalid fields. Use documented identifier comparison rules consistent with signal/module IDs.
Bindings are selected explicitly from actually read, identity-verified session signal metadata, not role names or guessed RPM aliases. Reject unknown module/ signal or requested-unit mismatch during configuration. Runtime loss/change of a previously valid signal becomes an explicit data state, not a silent rebind. No unit conversion is assigned; display the exact source unit.
Editing/rejecting/removing a gauge cannot mutate model inputs, run state, source selection or other valid definitions. Empty dashboards are valid and do not stop an explicitly running acquisition owner.
B. One real session-owned acquisition feed
Add a focused Application feature under Telemetry/LiveDashboard or equally clear ownership. Bind to the existing explicit DiagnosticSession and immutable context: session/target/profile plus available config/run identity. No global current vehicle/provider registry or competing open workflow.
Use one owned loop per bound dashboard/session. Repeated acquisition of that same owner must share it or reject duplicate ownership before mutation; repeated Start on the owner is idempotent as C-05 states. Do not create a poll loop per component.
On explicit monitoring Start, obtain verified service/endpoint/signal availability through actual discovery/read ports, then publish an initial snapshot. Subsequent cycles wait 250 ms after the preceding completed cycle; no overlapping polls. Use a small injectable scheduler/time seam for deterministic tests, not the physics pacer or a new clock project. This interval is not a real-time guarantee and is not a new user-configurable rate in this slice.
Group reads by eligible module. Acquire independently of current widget count/ visibility and publish immutable latest snapshots only; no unbounded history, recording, interpolation or replay. Preserve per-response source/quality/request time and model step/time; do not claim simultaneous capture for running modules.
Freshness here is cycle-based, not a new wall-age SLA: initial/pending reads, last completed data, failed-cycle Stale/Error and Stopped are explicit. Show source/sample context and refresh state. No silent zeros or invented timestamps.
Tie ownership to source/feature lifetime, not the Razor widget. Coordinate actual close/reset/disposal so the worker and any pending read are cancelled/drained; source lifetime integration may be added narrowly if needed. Prevent old generations from publishing after stop/restart/rebind. Do not wait under a gate needed by cleanup. Monitoring never starts/stops/steps physics.
C. Pure reusable controls and real UI
Add generic numeric/bar renderers in Components. They consume presentation data, not DiagnosticSession, Simulation, native drivers or acquisition services. Use accessible labels/value/state descriptions and safe text rendering. Handle invalid public presentation parameters explicitly, never healthy NaN/ infinite width or an unhandled user-input rendering failure.
Compose a reusable dashboard panel/editor in UI within the existing /diagnostics
and /simulation session workflows. The host/session owns the feed; mounting/
hiding widgets does not own it. Provide explicit Start/Stop monitoring, add/edit/
remove gauge controls and a simple fixed layout. Preserve existing controls/routes.
Label synthetic/static/dynamic origin and selected source clearly. Missing, uncertain, stale/error, out-of-range and stopped states must be visually/textually distinct. Last-known values may remain only with their stale/stopped label and source time; they are not current measurements or real vehicle evidence.
FILES OR PROJECTS EXPECTED TO CHANGE
- Application dashboard definitions/validation/feed use cases and minimal session- lifetime integration necessary for owner cleanup.
- Components numeric/bar renderers and UI dashboard composition/host wiring.
- Client DI only if needed; existing unit/integration tests and related docs.
- Only
prompts/Step-05-Report.mdunderprompts.
No persisted dashboard format, new project/dependency, provider/protocol/model/ clock redesign, extra host or physics change is assigned. Do not edit assignments, ROADMAP, STATE, shared gate or historical reports. No protected-instruction edit, staging/commit/push, destructive Git or unrelated worktree cleanup.
INTERFACE AND DEPENDENCY REQUIREMENTS
Keep the nine-project graph, Components independence, Application/Diagnostics boundary and private simulation oracle. Preserve wire/profile schemas, exact source/config binding, verified clear, partial identities and clock ownership. Only identity-verified endpoints that implement read.signals are polled; unknown/ restricted/unavailable metadata does not fabricate support.
Use typed visible errors and validate-before-mutate. No broad catches, fake data, target fallback, direct engine access, real hardware or workload/system action. Keep the shared quality gate's frozen-criteria and self-review requirements.
TESTING REQUIREMENTS
Implement C-01..C-10 as relevant component, validation, feed, actual DI and rendered tests before handoff. In particular:
- Assert exact 850/85%/unit/precision and true-zero rendering, out-of-range geometry versus actual value, unknown/uncertain/stale/error/stopped state and safe text.
- Prove invalid definitions (including non-finite span) are rejected atomically.
- Drive the real feed with controlled ticks/barriers through duplicate start, pending stop/restart, close/reset/new source and delayed old response.
- Count actual wire reads for shared bindings and hidden/zero widgets. Preserve model step/time while the dynamics source is paused. No sleeps/polling or arbitrary elapsed-time thresholds as correctness proof.
- Exercise both actual static v1 and dynamics v2 sessions; inject data loss/ negative responses below the feature boundary, not a mock dashboard service.
- Render the real panel/editor against actual Application DI and ensure component disposal does not stop source acquisition while explicit close does.
Preserve the 207-case baseline (126 unit, 81 integration); map intentional UI assertion changes without deleting safety/error checks. Run focused tests, then sequential full Release build/test using the existing commands/runner:
dotnet build .\src\AutoForge.slnx --configuration Release --no-restoredotnet test .\src\AutoForge.slnx --configuration Release --no-build
No new dependency/restore is expected absent a real missing-dependency failure. The complete build includes the real Windows Client/all nine projects.
Native smoke: open an actual static session and configure numeric/bar views of its signal; verify live/stop/hide/range behavior. Repeat with a real dynamics session, pause/step/read to observe correct value/time and prove monitoring alone does not step it; test invalid range/binding, stop/reset/close and old routes. Distinguish native observations from controlled fault/lifecycle proof.
DOCUMENTATION REQUIREMENTS
Update README/index/architecture/build guide and concise dashboard usage/contracts: input limits/binding/unit policy, state semantics, cycle-based freshness, one owner/visibility/lifetime rules, v1/v2 sample context and actual evidence. Mark Step-04/04A/04B accepted, Step-05 worker status pending review, and retain historical reports. No dashboard persistence, charts or conversions are claimed.
ACCEPTANCE CRITERIA
| ID | Criterion | Evidence |
|---|---|---|
| AC-01 | C-01..C-04 exact rendering/projection/state and atomic definition rules | Component/validation matrix and actual UI failures |
| AC-02 | C-05..C-08 one-owner, cleanup/generation/visibility and state rules hold | Controlled feed/service/rendered lifecycle tests |
| AC-03 | C-09 actual static/dynamic wire acquisition is grouped and independent of renders/physics | Per-module frame counts, true source/time and paused-step assertions |
| AC-04 | C-10 real host workflow uses pure Components and actual Application feed without scope expansion | Reference/source review and rendered/native evidence |
| AC-05 | Existing 207 cases/invariants, full nine-project Release/native build and required smoke pass | Exact commands, warnings, per-project counts and coverage distinction |
| AC-06 | Contract/evidence matrix, self-review, docs/README and limitations match implementation | Report mapping and documentation summary |
| AC-07 | Protected/history/manual workflow preserved; complete report saved and worker stops | Preservation/Git review and prompts/Step-05-Report.md |
Use PASSED, FAILED, NOT EXECUTED or BLOCKED precisely. COMPLETE requires assigned checks; optional future preferences are not acceptance requirements.
OUT-OF-SCOPE WORK
Dashboard JSON/storage/persistence, charts/time series, analog/SVG clusters, drag/drop/layout designers, new unit conversion/rate/freshness policies, recording/ replay/comparison, model/protocol/physics changes, hardware/calibration/AI, new projects/packages/hosts/platforms and unrelated cleanup.
REPORTING REQUIREMENTS
Create prompts/Step-05-Report.md entirely inside exactly one plain triple-backtick
code fence, without language tag or outside content. Use no nested fences.
Include identifier/title/status, implemented functions, files created/modified,
architecture/interfaces, unit/integration and C-01..C-10/AC-01..AC-07 evidence,
exact build/test results with warnings/exits/per-project counts, native versus
controlled observations, worker self-review, docs/README, limitations/outstanding
issues/deviations/recommendations and preservation review.
Save and STOP. No orchestration/shared-gate edit, Step-06, agents, automatic handoff, stage, commit or push.