252 lines
15 KiB
Markdown
252 lines
15 KiB
Markdown
# 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.
|