274 lines
17 KiB
Markdown
274 lines
17 KiB
Markdown
# Step-06 - Imperial-default metric/imperial display units
|
|
|
|
## STEP IDENTIFIER
|
|
|
|
Step-06. Corrected Step-05/05A/05B was accepted on 2026-10-29.
|
|
This is the sole active implementation assignment. Recording/replay is Step-07
|
|
and remains blocked until this work is accepted.
|
|
|
|
## STEP TITLE
|
|
|
|
Use one shared metric/Imperial (US) presentation preference, defaulting to imperial,
|
|
while preserving SI calculations and exact raw/source data.
|
|
|
|
## OBJECTIVE
|
|
|
|
One user outcome: current human-facing measurements use the selected unit system
|
|
consistently, without changing the vehicle model, source or physical gauge range.
|
|
One primary new contract: a shared locally remembered display preference and
|
|
pure, validated presentation conversion boundary.
|
|
|
|
Read [STATE.md](STATE.md), the dated owner decision in [ROADMAP.md](ROADMAP.md),
|
|
[live dashboard contracts](../docs/live-dashboard.md) and
|
|
[WORKER-QUALITY-GATE.md](WORKER-QUALITY-GATE.md). Build the frozen case matrix
|
|
before coding, self-review after the first green run, write
|
|
`prompts/Step-06-Report.md`, and STOP.
|
|
|
|
## ARCHITECTURAL CONTEXT
|
|
|
|
Keep the nine-project .NET 10 modular monolith and sole MAUI Client. Components
|
|
remains generic with no AutoForge project reference. Application may own a small
|
|
display-unit feature/pure conversion and preference port; UI owns presentation/
|
|
interaction, and Client supplies real local MAUI preference storage/composition.
|
|
An equally simple existing-boundary arrangement is acceptable without duplicated
|
|
conversion logic. No new project, package, host or units/settings framework.
|
|
|
|
Use existing MAUI storage primitives, not new dependencies. Portable tests use
|
|
an explicitly isolated store behind the same port; the native host must not
|
|
silently fall back to an in-memory implementation. All source/tests stay under
|
|
`src`, tests under `src/tests`.
|
|
|
|
## CURRENT IMPLEMENTATION STATE
|
|
|
|
Accepted dashboard behavior includes real static-v1/dynamic-v2 signal reads,
|
|
zero-to-eight immutable definitions with exact source-unit binding, one session
|
|
acquisition owner, independent quality/range and explicit stale/error states.
|
|
The worker reports a clean nine-project Release build, 134 unit + 91 integration
|
|
passes (225 total, zero failed/skipped) and native baseline recheck.
|
|
The orchestrator did not run those commands.
|
|
|
|
Relevant existing surfaces:
|
|
|
|
- [MainLayout](../src/AutoForge.UI/Layout/MainLayout.razor): shared shell/navigation.
|
|
- [DiagnosticsPage](../src/AutoForge.UI/Features/Vehicles/Diagnostics/DiagnosticsPage.razor):
|
|
human-readable signals and separate raw trace.
|
|
- [SimulationPage](../src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPage.razor):
|
|
scenario target summaries, decoded telemetry and raw configuration JSON.
|
|
- [LiveDashboardPanel](../src/AutoForge.UI/Features/Vehicles/Telemetry/LiveDashboard/LiveDashboardPanel.razor):
|
|
values, editor bounds and source/sample context.
|
|
- [LiveDashboardAcquisition](../src/AutoForge.Application/Features/Vehicles/Telemetry/LiveDashboard/LiveDashboardAcquisition.cs):
|
|
canonical definitions/source values/states; not a new physics or conversion owner.
|
|
- [MauiProgram](../src/AutoForge.Client/MauiProgram.cs): native DI/composition.
|
|
|
|
There is no shared unit preference/conversion implementation yet. Reinspect Git,
|
|
existing tests/helpers and real source-unit metadata before editing; preserve
|
|
dirty work, accepted behavior and all historical reports.
|
|
|
|
## REQUIRED IMPLEMENTATION
|
|
|
|
### Frozen contract matrix
|
|
|
|
| ID | Input/precondition | Required result |
|
|
|---|---|---|
|
|
| C-01 | No saved preference; any route/culture | Imperial (US), Road-speed presentation by default; shared accessible control is visible before a session opens. No ambient region chooses the default. |
|
|
| C-02 | Known source units and representative conversion vectors below | Correct finite forward/inverse result within 1e-9 absolute target units for these vectors; consistent value/unit text. RPM/V/ratio/count/gear/boolean remain unchanged. |
|
|
| C-03 | Actual speed 20.1168 m/s, source bounds 0..40.2336 m/s | Imperial Road: 45 mph, bounds 0..90; Imperial Engineering: 66 ft/s, 0..132; Metric Road: 72.42048 km/h, 0..144.84096; Metric Engineering: source m/s. All retain 50% geometry and identical source bounds/state/context. |
|
|
| C-04 | At least 20 system/speed-mode toggles and rerenders on a bound paused session | Canonical definitions/source snapshots/configuration/time/step/request counts and owner stay unchanged; no drift or extra wire request/physics action. |
|
|
| C-05 | Gauge range editor in display units; valid/invalid saves; unedited Save | Convert edited bounds once to source units and validate atomically. 32..212 degF becomes 0..100 degC. Unedited saves/toggles retain original canonical bounds exactly. Invalid/overflowing bounds preserve prior definitions/feed/source. |
|
|
| C-06 | Active unsaved editor draft while global units change | Draft keeps its captured input unit and numbers, visibly labeled until Save/Cancel; Save uses that unit. Other readouts update; new/reset editor uses current selection. Never reinterpret typed numbers under a new label. |
|
|
| C-07 | Pending/Unknown/Uncertain/Stale/Error/Stopped, low/high or missing values | Preserve source quality/range/freshness/reason/time; missing stays `--`, never zero. Conversion cannot turn stale/uncertain data Good or clamp the numeric value. |
|
|
| C-08 | Known unchanged units, unsupported units, invalid preference/value or non-finite conversion | Pass-through units stay exact. Unsupported units remain explicitly unconverted with source unit/notice, never relabeled. Invalid input/overflow yields a handled visible error/unavailable result, not fabricated data or invalid geometry. |
|
|
| C-09 | Valid stored selection; navigation/restart; corrupt/unreadable store; failed write | Valid choice restores across routes/restarts. Missing is documented default. Invalid/read failure is visible with clearly labeled Imperial/Road default, not claimed restored or silently overwritten. Failed selection save preserves previous active preference and shows error. |
|
|
| C-10 | Human readouts versus raw/config/source inspectors | Assigned readouts convert consistently; original payloads, source-unit values, JSON/import/export/fingerprint and raw context remain byte/value-identical and labeled source/SI. |
|
|
| C-11 | Numeric source 0.4 m/s with display precision 0 | Convert NumericValue before formatting: Imperial Road displays 1 mph, not 0 from parsing the feed's already-rounded text. Never chain conversions through formatted display values. |
|
|
| C-12 | Actual static/dynamic Application/UI/Client paths | Real ports, preference adapter, shared selector and generic gauge path operate together; native toggling/restart/close and original routes work without an oracle or parallel host. |
|
|
|
|
### A. Shared display preference and exact supported mappings
|
|
|
|
Expose Metric / Imperial (US) and Road / Engineering speed presentation through
|
|
one application-wide control, preferably in the existing shared shell.
|
|
Defaults are Imperial (US) + Road; ordinary vehicle speed therefore shows mph.
|
|
Engineering is the explicit ft/s option, not a second poller or per-gauge layout
|
|
system. Switching unit system keeps the selected speed style.
|
|
|
|
Use one immutable validated selection shared across routes and mounted panels.
|
|
Persist only this small local preference through existing platform primitives.
|
|
Missing data means first-use default. Invalid/unreadable saved state shows an
|
|
explicit preference error and clearly identified default; do not overwrite it
|
|
silently. A successful explicit selection can recover. Persist a proposed
|
|
selection before publishing it; save failure leaves the prior active selection.
|
|
Undefined enum/options must reject before any state/store mutation.
|
|
Do not silently substitute an in-memory native store.
|
|
|
|
Current required source-to-display mappings:
|
|
|
|
| Exact source unit | Metric display | Imperial (US) display |
|
|
|---|---|---|
|
|
| m/s | km/h for Road; m/s for Engineering | mph for Road; ft/s for Engineering |
|
|
| m | m | ft |
|
|
| kg | kg | lb |
|
|
| kg/s | kg/s | lb/h |
|
|
| N*m | N*m | lbf*ft |
|
|
| degC | degC | degF |
|
|
| m/s^2 | m/s^2 | ft/s^2 |
|
|
| rpm, V, ratio, count, gear, boolean | Same source unit | Same source unit |
|
|
|
|
Use exact definitions: 1 ft = 0.3048 m; 1 mile = 1609.344 m;
|
|
1 lb = 0.45359237 kg; 1 lbf = 4.4482216152605 N; 1 hour = 3600 s;
|
|
degF = degC * 9/5 + 32. Do not introduce UK gallons or fuel-volume/economy
|
|
conversion without sourced density. No additional unit families are assigned.
|
|
|
|
Representative independent vectors: 20.1168 m/s -> 45 mph -> 66 ft/s;
|
|
0.3048 m -> 1 ft; 0.45359237 kg -> 1 lb;
|
|
(0.45359237 / 3600) kg/s -> 1 lb/h;
|
|
1.3558179483314004 N*m -> 1 lbf*ft;
|
|
0/100/-40 degC -> 32/212/-40 degF;
|
|
0.3048 m/s^2 -> 1 ft/s^2. Test inverse mappings too.
|
|
|
|
Map actual exact source units, not labels, module roles or guessed signal aliases.
|
|
Unknown units are not errors in the original source: retain their source value/
|
|
unit with an explicit unconverted notice. Preserve source quality independently.
|
|
Reject non-finite input/output and overflow through a typed handled result/error;
|
|
never return a success-shaped zero.
|
|
|
|
### B. Canonical data stays unchanged; conversion is presentation only
|
|
|
|
Keep raw diagnostic values, DiagnosticSignal.Unit, configuration/export/import,
|
|
fingerprints, physics inputs/results and time in their existing source/SI units.
|
|
Keep DashboardGaugeDefinition.Unit and bounds as exact source-unit contracts.
|
|
Do not weaken source-unit matching to make an imperial display work.
|
|
|
|
Project a separate display value/unit/bounds from original finite numeric data,
|
|
then apply the existing 0..3 decimal precision once. Never parse DisplayValue,
|
|
mutate a signal/definition, convert a prior display result again or change
|
|
acquisition rate/ownership/model control in response to a preference.
|
|
|
|
Reuse source-computed range/quality and bar percentage unchanged. Temperature
|
|
offset conversion must preserve physical boundaries, not merely change the
|
|
value label. Bounds are converted for editor display and converted back only
|
|
for actual edits; preserve original canonical numbers on an unedited Save.
|
|
Validate finite ordered source span as well as display input before committing.
|
|
Display precision must not quantize canonical editor bounds.
|
|
|
|
Pin an active editor draft's unit when its binding/edit begins and label that
|
|
unit explicitly. Global changes must not reinterpret its text. Save parses in
|
|
the captured unit; Cancel/Reset/new draft adopts the current preference.
|
|
Changing binding starts a clearly labeled draft for the new actual source.
|
|
|
|
Missing/failed/unknown/stale/stopped values retain their established states,
|
|
reason and actual source/sample time. Preserve independent Uncertain low/high
|
|
status and actual out-of-range readings; only bar geometry stays clamped.
|
|
Subscribe/unsubscribe presentation notifications safely on the renderer
|
|
dispatcher; view disposal must not stop session acquisition.
|
|
|
|
### C. Wire all current relevant surfaces, not just gauges
|
|
|
|
Use the shared conversion path in dashboard numeric/bar values and range labels/
|
|
editor, diagnostics human-readable signal readings, simulation decoded-telemetry
|
|
rows and scenario target-speed summaries. Keep timing/percent/count fields
|
|
unchanged. Retain accessible unit/state/value descriptions and safe text.
|
|
|
|
Source metadata/inspectors must still expose the exact original value and unit.
|
|
Raw trace/payloads, protocol fields, profile facts and configuration JSON remain
|
|
source data, explicitly labeled as unaffected by display preference. Do not
|
|
attempt to convert arbitrary text/profile metadata or rewrite historical docs/
|
|
reports. The global control and any load/save error are visible without a session.
|
|
|
|
## FILES OR PROJECTS EXPECTED TO CHANGE
|
|
|
|
Focused Application/UI presentation/preference/conversion code, shared layout
|
|
and current host/panel wiring, a small real Client preference adapter/DI, unit/
|
|
integration tests and directly related docs/README.
|
|
Components remains generic; Core/Diagnostics/Simulation implementation/schema/
|
|
physics changes are not expected or authorized by this display-only work.
|
|
Only `prompts/Step-06-Report.md` under `prompts`.
|
|
|
|
## INTERFACE AND DEPENDENCY REQUIREMENTS
|
|
|
|
Keep all nine projects, current references and one Client. No new dependency,
|
|
host, global active-session registry or generic settings framework. Tests may
|
|
use an explicit isolated preference store, not mock away conversion/feed/session.
|
|
Client must use actual MAUI preference primitives through the portable boundary.
|
|
|
|
Preserve static v1/dynamic v2, strict wire/profile/config contracts, source/
|
|
run identity, partial discovery/verified clear and one acquisition/physics owner.
|
|
No new oracle, hardware capability, silent fallback or broad exception mask.
|
|
No workload/system restore/install/update/repair/rollback is authorized.
|
|
Preserve existing dirty work and protected/history files; no stage/commit/push
|
|
or destructive Git action.
|
|
|
|
## TESTING REQUIREMENTS
|
|
|
|
Map C-01..C-12 to meaningful named tests before handoff:
|
|
|
|
- Pure forward/inverse vectors with independently specified expected values,
|
|
temperature offset, true zero/negative boundaries, finite/overflow checks,
|
|
exact pass-through/unknown units and conversion-before-rounding.
|
|
- First-use versus restored/error preferences using the real shared service and
|
|
isolated store seam. Verify failed writes/invalid options are atomic; do not
|
|
treat an always-working mock store as persistence failure coverage.
|
|
- Controlled real-provider/rendered static and dynamic routes/panel: all speed
|
|
modes, values/bounds/accessibility, 20 toggles, canonical equality, preserved
|
|
quality/range/time, editor draft pinning/invalid saves and zero added reads/
|
|
unchanged paused model state. Count at the real wire boundary.
|
|
- Raw source/config export/fingerprint/trace values and bytes remain unchanged.
|
|
Keep meaningful existing 225-case regressions; map necessary presentation-only
|
|
assertion updates without deleting source/safety/error checks.
|
|
|
|
Run focused cases, then sequential full checks:
|
|
|
|
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
|
|
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
|
|
|
|
The complete build includes all nine projects and the real Windows Client.
|
|
No dependency install/restore absent a real missing-dependency failure.
|
|
|
|
Native smoke on the rebuilt Client: observe initial/default or restored selection
|
|
honestly; configure real static/dynamic gauges; toggle systems/speed styles and
|
|
compare source versus display; edit a range and switch with a draft open; check
|
|
scenario/telemetry readouts and raw SI JSON; pause and prove toggles do not step;
|
|
restart to verify the chosen preference; reset/close and check old routes.
|
|
Do not wipe shared preferences or unrelated user data. Preserve/restore only
|
|
exact task-owned preference values when needed for smoke cleanup. Distinguish
|
|
native observations from controlled storage-error/invalid-data proof.
|
|
|
|
## DOCUMENTATION REQUIREMENTS
|
|
|
|
Update README/index/architecture/build guide and live-dashboard/simulation usage:
|
|
Imperial (US) first use, Metric and Road/Engineering options, persistence/error
|
|
behavior, mappings/limits, source versus display, canonical editor/draft policy
|
|
and actual validation evidence. Mark Step-05/05A/05B accepted; Step-06 remains
|
|
pending orchestrator review. Recording/replay is Step-07 and not implemented.
|
|
|
|
## ACCEPTANCE CRITERIA
|
|
|
|
| ID | Criterion | Evidence |
|
|
|---|---|---|
|
|
| AC-01 | C-01/C-09 shared Imperial/Road default, persistence/restoration and explicit atomic failure behavior | Service/store/DI tests plus actual native adapter/restart evidence |
|
|
| AC-02 | C-02/C-03/C-08/C-11 exact supported conversions, safe unknown/invalid inputs and convert-before-rounding | Independent numeric vectors, inverse/finite checks and exact rendered units/values |
|
|
| AC-03 | C-04..C-07 stable canonical bounds, pinned drafts and unchanged acquisition/model/source states | Controlled real-provider/wire-count/source-equality and editor/render tests |
|
|
| AC-04 | C-10/C-12 all assigned current UI surfaces use the shared path; raw/source/config contracts unchanged | Real routes/panel/Client integration, raw bytes and accessible native smoke |
|
|
| AC-05 | 225 baseline cases preserved, meaningful new coverage, complete Release/native build and required smoke pass | Exact commands/exits/warnings/per-project counts; native versus controlled evidence |
|
|
| AC-06 | Frozen matrix/self-review/docs/README accurately describe implemented behavior and limitations | Case/test mapping, own source-path review after first green and documentation summary |
|
|
| AC-07 | Protected files/history/dependencies/manual workflow preserved; report saved and worker stops | Preservation review and `prompts/Step-06-Report.md` |
|
|
|
|
## OUT-OF-SCOPE WORK
|
|
|
|
Recording/replay, charts/layouts/dashboard persistence/schema, additional unit
|
|
families/fuel-volume/MPG, new clock/model/protocol/physics, calibration/AI/hardware,
|
|
new project/package/host and unrelated cleanup. No future assignment, agents,
|
|
automatic handoff, orchestration/shared-gate edit, stage, commit or push.
|
|
|
|
## REPORTING REQUIREMENTS
|
|
|
|
Create `prompts/Step-06-Report.md` entirely inside exactly one plain triple-backtick
|
|
fence, no language tag/outside text/nested fences. Include identifier/title/status,
|
|
implemented functions/files/interfaces, C-01..C-12/AC-01..AC-07 evidence with
|
|
named executed tests and exact vectors/tolerances, commands/exits/warnings/
|
|
per-project counts, native versus controlled coverage, docs/README, own source-
|
|
path self-review after the first green run, limitations/deviations/blockers and
|
|
preservation review. COMPLETE requires all assigned checks; otherwise report
|
|
INCOMPLETE/BLOCKED and the precise unmet criterion.
|
|
|
|
Save and STOP for manual orchestrator review. Do not begin Step-07.
|