# 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](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](STATE.md), [architecture](../docs/architecture.md), [protocol v1](../docs/synthetic-diagnostics-v1.md) and [v2](../docs/synthetic-diagnostics-v2.md). 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 `/diagnostics` and `/simulation` workflows 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](../src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs) 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.md` under `prompts`. 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-restore` - `dotnet 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.