AutoForge/README.md

232 lines
12 KiB
Markdown

# AutoForge
## Product vision
The following describes the product vision, not implemented capabilities:
AI-assisted automotive diagnostics and programming platform. Read and back up
vehicle data or build AI-researched vehicle profiles. Simulate control modules
and driving scenarios, replay telemetry, and test calibration changes before
real-world programming. Diagnose faults, read/clear trouble codes, and program
supported vehicle modules.
## Implementation status
### Implemented
- Step-01 platform-neutral Core/Application foundation and regression coverage.
- Step-01A single Windows-first .NET 10 MAUI Blazor Hybrid Client, UI and generic
Components RCLs. Step-01A was accepted by the orchestrator on 2026-10-28.
- Step-02 validated vehicle/profile/module metadata, strict schema-v1 JSON
interchange, an in-memory revision catalog, and a synthetic profile UI.
Step-02A corrected strict timestamp parsing and optional evidence applicability.
Step-02 and Step-02A were accepted by the orchestrator on 2026-10-28.
- Step-03 adds a provider-neutral diagnostic protocol/session path and a
data-driven synthetic virtual-module provider. The native UI explicitly loads
and selects a saved profile revision/provider, opens a separate simulation
session, probes endpoints, reads module identity/DTC/static signal snapshots,
clears only supported virtual DTC state after fresh empty readback verification,
and exposes a bounded raw/decoded trace. Step-03A corrects strict wire presence/
ambiguity checks, complete reply validation and truthful trace outcomes.
Step-03B preserves successful probe/service evidence separately from optional
profile-verified identity and keeps expected/probed/identified counts distinct.
Read/clear actions remain gated on verified identity. Step-03 with its
corrections was accepted by the orchestrator.
- Step-04 adds immutable versioned dynamics configurations, a fixed-step
coupled synthetic engine/transmission/longitudinal model, an explicit
`autoforge.simulation.dynamics` provider using protocol v2, configuration
import/export, lifecycle/scenario controls, and source/unit/model-time-aware
telemetry at `/simulation`. Step-04A corrects typed reference-validation
failures, drivetrain/rev-limit consistency, monotonic phase/overall progress,
terminal-failure telemetry/UI behavior, and single-owner cancellable pacing.
Step-04B corrects side-effect-free Start/Resume rejection during owner cleanup.
The static provider and protocol v1 remain separate. Step-04/04A/04B are
accepted by the orchestrator.
- Step-05 adds one configurable numeric/bar dashboard panel to both static
diagnostics and dynamics workflows. It reads only identity-verified signals
from the explicitly opened session, exposes source/quality/range/sample
context, and keeps acquisition session-owned while gauges are hidden or
removed. Step-05 with Step-05A/Step-05B was accepted by the orchestrator.
- Step-06 adds a shared, persisted display preference with an Imperial (US) /
Road first-use default and Metric/Imperial (US) plus Road/Engineering choices.
Supported readouts convert only at presentation; SI source values, model
calculations, configuration fingerprints and canonical dashboard definitions
remain unchanged. See [display units](docs/live-dashboard.md#display-units).
Step-06 implementation and worker verification are complete; manual
orchestrator review remains pending.
- UI routes: `/` foundation, `/execution-targets` explicit metadata selection,
`/vehicle-profiles` explicit profile import/revision selection/inspection/export,
`/diagnostics` static synthetic diagnostics, `/simulation` dynamics, and a
visible not-found route.
- Capability declarations distinguish Supported, Unsupported, Unknown,
Inaccessible and Restricted. Missing declarations are explicitly Unknown.
Provenance and all profile facts are supplied metadata, not independently
verified truth or permission.
- Profile import is atomic and unknowns remain explicit. A selected profile is
immutable, process-local metadata; it is not connected to a vehicle.
- Publication/retrieval timestamps require a complete date/time with seconds and
an explicit `Z` or signed `HH:mm` offset; partial dates/times and local-time
defaults are rejected. A null optional module identity in evidence is no
constraint; supplied values must match a known module identity and never fill
unknown module data. See the schema guide for exact grammar and limits.
### In progress
Step-06 is complete on worker execution evidence and is awaiting manual
orchestrator review. The Step-04 and Step-05 acceptances include their listed
corrections.
### Planned
Telemetry recording/replay, calibration values/editing/backups, AI and real
hardware operations require later approved assignments. Dynamics estimates are
synthetic, not manufacturer prediction, vehicle compatibility, physical access,
safe tuning advice or authorization. No capability is implemented merely
because it appears in the product vision or roadmap.
## Architecture
One Windows-first **AutoForge.Client** .NET 10 MAUI Blazor Hybrid executable hosts
the application UI via `BlazorWebView`. **AutoForge.UI** owns all routes,
navigation, layouts and feature presentation. **AutoForge.Components** owns
vehicle-independent reusable controls. Application features run in-process in a
modular monolith, and Core remains platform-neutral. There is no backend,
browser-hosted WASM shell, Blazor Server host or second application executable.
The application slices provide explicit target metadata resolution,
vehicle-profile metadata import/list/select/export, dynamics configuration
catalog/import/export, simulation-only diagnostic sessions, and a shared
display-unit preference with a native local-preference adapter. The Client
composes separate static and dynamics synthetic providers through
provider-neutral factory contracts and a session-lifetime in-memory profile/
configuration catalog. Import never opens a session; metadata resolution never
opens a session or starts a run.
```mermaid
flowchart TD
Client[MAUI Blazor Hybrid Client] --> UI[UI RCL]
Client --> Simulation[Simulation provider]
UI --> Components[Reusable Components RCL]
UI --> App[Application feature slices]
Client --> App
App --> Diagnostics[Provider-neutral Diagnostics contracts and protocol]
App --> Core[Platform-neutral Core models]
Diagnostics --> Core
Simulation --> Diagnostics
Simulation --> Core
UnitTests[Headless unit tests] --> Core
UnitTests --> App
UnitTests --> Diagnostics
UnitTests --> Simulation
IntegrationTests[Headless integration and rendered UI tests] --> UI
IntegrationTests --> App
IntegrationTests --> Core
IntegrationTests --> Diagnostics
IntegrationTests --> Simulation
```
Core and Application own their behaviors under feature-focused source folders:
- `AutoForge.Application/Features/ExecutionTargets/SelectExecutionTarget`
- `AutoForge.Application/Features/Vehicles/Profiles`
- `AutoForge.Application/Features/Vehicles/Diagnostics`
- `AutoForge.Application/Features/Vehicles/Simulation`
- `AutoForge.Diagnostics` (provider-neutral protocol, transport/session contracts)
- `AutoForge.Simulation` (data-driven virtual modules, fixed-step engine and transports)
- `AutoForge.UI/Features/Vehicles/Profiles`
- `AutoForge.UI/Features/Vehicles/Diagnostics`
- `AutoForge.UI/Features/Vehicles/Simulation`
No mediator, generic repository layer, database, or empty future feature is
required. See the [schema-v1 profile guide](docs/vehicle-profile-schema-v1.md)
for stable identifiers/revisions, unknown values, capabilities, provenance and
the strict JSON contract.
## Repository layout
Only `docs`, `src` and `prompts` are top-level project directories. Tests and
synthetic fixtures remain under `src/tests`. No nested repository or root test
project is used.
```text
AutoForge/
docs/ Technical docs, schemas and ADRs
prompts/ Manual assignments, state and worker reports
src/
AutoForge.slnx
AutoForge.Client/ Sole Windows MAUI Hybrid executable
AutoForge.UI/ Application routes and feature presentation
AutoForge.Components/ Generic reusable UI components
AutoForge.Core/ Platform-neutral domain invariants
AutoForge.Application/ In-process application feature slices
AutoForge.Diagnostics/ Provider-neutral diagnostic protocol/contracts
AutoForge.Simulation/ Static modules, dynamics engine and transports
tests/
AutoForge.UnitTests/
AutoForge.IntegrationTests/
Fixtures/ Clearly synthetic schema-v1 JSON only
```
## Build, test and run
Verified Windows prerequisites: .NET SDK **10.0.402**, runtime **10.0.13**,
Windows SDK target **10.0.26100.0**, `maui-windows` workload manifest **10.0.110**
and WebView2 Runtime **155.0.4283.62**. The Client targets
`net10.0-windows10.0.26100.0`/`win-x64`; the other projects target portable
`net10.0`. No automotive driver, actual vehicle, AI model, database, backend or
cloud account is needed.
From the repository root in PowerShell:
```powershell
dotnet restore .\src\AutoForge.slnx
dotnet build .\src\AutoForge.slnx --configuration Release --no-restore
dotnet test .\src\AutoForge.slnx --configuration Release --no-build
dotnet run --project .\src\AutoForge.Client\AutoForge.Client.csproj --configuration Release --framework net10.0-windows10.0.26100.0
```
Step-02A worker verification includes a seven-project Release build with zero
warnings/errors, 103 unit and 37 integration tests passed (140 total, zero
failed/skipped), and native Client checks for strict timestamp failures, partial
evidence import/export and conflicting-identity atomicity. The original Step-02
report records its historical 59 unit/34 integration cases; those runs did not
include the Step-02A corrections. Step-03 extends those suites and records its
actual full-build/test and native-smoke evidence in the
[Step-03 worker report](prompts/Step-03-Report.md). Step-03A's stricter
request/reply validation, trace consistency and clear-verification behavior,
tests, final 111-unit/64-integration Release results, and worker evidence are
recorded in the
[Step-03A corrective report](prompts/Step-03A-Report.md). Manual Step-03
acceptance remains the orchestrator's responsibility.
## Documentation and handoff
- [Documentation index](docs/README.md)
- [Architecture and project graph](docs/architecture.md)
- [Synthetic diagnostics protocol v1](docs/synthetic-diagnostics-v1.md)
- [Synthetic diagnostics protocol v2](docs/synthetic-diagnostics-v2.md)
- [Simulation definitions and state](docs/simulation.md)
- [Live dashboard usage and contracts](docs/live-dashboard.md)
- [Vehicle-profile schema v1 and usage](docs/vehicle-profile-schema-v1.md)
- [Build, tests and native smoke guide](docs/build-and-test.md)
- [ADR-0001: historical .NET foundation](docs/adr-0001-headless-foundation.md)
- [ADR-0002: one native shell and feature slices](docs/adr-0002-single-shell-vsa.md)
- [ADR-0003: strict profile interchange v1](docs/adr-0003-profile-interchange-v1.md)
- [ADR-0004: synthetic diagnostics boundaries](docs/adr-0004-synthetic-diagnostics.md)
- [Step-01 historical report](prompts/Step-01-Report.md)
- [Accepted Step-01A report](prompts/Step-01A-Report.md)
- [Step-02 worker report](prompts/Step-02-Report.md)
- [Step-02A corrective worker report](prompts/Step-02A-Report.md)
- [Step-03 worker report](prompts/Step-03-Report.md)
- [Step-03A corrective worker report](prompts/Step-03A-Report.md)
- [Step-03B corrective worker report](prompts/Step-03B-Report.md)
- [Step-04 worker report](prompts/Step-04-Report.md)
- [Step-04A corrective worker report](prompts/Step-04A-Report.md)
- [Step-04B corrective worker report](prompts/Step-04B-Report.md)
- [Step-05A corrective worker report](prompts/Step-05A-Report.md)
- [Orchestrator-owned roadmap](prompts/ROADMAP.md) and
[orchestration state](prompts/STATE.md)
Handoffs are manual. Worker completion does not mean orchestrator acceptance or
authorize subsequent work.