424 lines
24 KiB
Markdown
424 lines
24 KiB
Markdown
# Step-03 - Virtual modules and simulated diagnostic communication
|
|
|
|
## STEP IDENTIFIER
|
|
|
|
Step-03. Step-02 and its correction Step-02A were accepted on 2026-10-28.
|
|
This is the sole active implementation assignment.
|
|
|
|
## STEP TITLE
|
|
|
|
Connect an explicitly selected synthetic vehicle through a real simulated
|
|
transport; discover virtual modules, inspect identity/DTC/static telemetry and
|
|
communication traces, and verify deterministic failures.
|
|
|
|
## OBJECTIVE
|
|
|
|
Deliver one complete simulated-diagnostics vertical slice in the existing native
|
|
Client. Application features and UI must use provider-neutral diagnostic services
|
|
that encode requests, traverse the simulated transport, reach virtual modules,
|
|
decode responses and produce truthful results/traces.
|
|
|
|
This is not the vehicle-dynamics milestone. Telemetry is an explicitly labeled
|
|
static synthetic module-state snapshot, not fabricated live physics or a real
|
|
vehicle capture. No physical adapter, programming, AI, backend or extra executable.
|
|
|
|
You are the WORKER. Execute only this assignment, verify it, write
|
|
`prompts/Step-03-Report.md`, and STOP for manual orchestrator review.
|
|
|
|
## ARCHITECTURAL CONTEXT
|
|
|
|
Read [ROADMAP.md](ROADMAP.md), [STATE.md](STATE.md), the accepted
|
|
[profile assignment](Step-02.md), [correction](Step-02A.md) and their reports,
|
|
the [architecture](../docs/architecture.md) and
|
|
[schema guide](../docs/vehicle-profile-schema-v1.md).
|
|
|
|
Keep the .NET 10 modular monolith and application Vertical Slice Architecture.
|
|
Client is the only application executable; UI owns routes/feature presentation;
|
|
Components owns generic reusable controls. Application coordinates domain and
|
|
capability libraries, not UI/hardware implementations. No mediator or generic
|
|
repository/manager layer is needed.
|
|
|
|
All source/projects/tests belong under `src`, tests under `src/tests`. Root project
|
|
directories remain exactly `docs`, `src`, `prompts`, preserving protected
|
|
infrastructure. Handoffs remain manual; no agent automation, watchers or polling.
|
|
|
|
## CURRENT IMPLEMENTATION STATE
|
|
|
|
The solution currently contains seven projects:
|
|
|
|
- Core: explicit execution-target metadata and immutable vehicle/profile/module/
|
|
capability/provenance models.
|
|
- Application: `Features/ExecutionTargets/SelectExecutionTarget` and
|
|
`Features/Vehicles/Profiles`, with validated DI, schema-v1 import/export,
|
|
process-local catalog and exact profile/revision selection.
|
|
- Components: reusable StatusNotice.
|
|
- UI: `/`, `/execution-targets`, `/vehicle-profiles`, layout/navigation and
|
|
not-found handling; scoped presentation state invokes actual application services.
|
|
- Client: Windows MAUI Blazor Hybrid, native lifecycle/BlazorWebView/composition.
|
|
- UnitTests and IntegrationTests: portable Core/Application/RCL/graph tests.
|
|
|
|
Client -> UI/Application; UI -> Components/Application; Application -> Core.
|
|
Components has no AutoForge project reference. No cycle or separate backend.
|
|
|
|
Accepted correction requires complete date/time/seconds and explicit timestamp
|
|
offset, preserves fractional precision, and treats null optional module evidence
|
|
identities as absent constraints while validating supplied values. Preserve it.
|
|
|
|
Worker evidence records a complete seven-project Release build with zero warnings/
|
|
errors, 103 unit + 37 integration cases passed (140 total, zero failed/skipped),
|
|
and native profile/error/original-fixture smoke. These are previous worker
|
|
results, not an orchestrator runtime rerun.
|
|
|
|
Current target-provider registration is intentionally empty: resolving metadata
|
|
does not connect. No diagnostic/provider session, protocol, transport, virtual
|
|
module or physics engine exists yet.
|
|
|
|
Verified worker platform: SDK 10.0.402, runtime 10.0.13, Windows TFM
|
|
`net10.0-windows10.0.26100.0`/win-x64, MAUI Windows manifest 10.0.110,
|
|
WebView2 155.0.4283.62. Inspect prerequisites read-only if needed. No workload
|
|
restore/install/update/repair/rollback or other major environment change is
|
|
authorized. Ordinary package restore is distinct.
|
|
|
|
Recheck Git/instructions and preserve pre-existing dirty implementation and all
|
|
historical assignments/reports. Do not assume a clean worktree.
|
|
|
|
## REQUIRED IMPLEMENTATION
|
|
|
|
### 1. Establish the two actual capability boundaries
|
|
|
|
Add these purposeful `net10.0` class libraries to the existing solution:
|
|
|
|
| Project | Responsibility | Allowed project references |
|
|
|---|---|---|
|
|
| `src/AutoForge.Diagnostics` | Provider/session/transport contracts, diagnostic messages, explicitly synthetic protocol client/codec, decoded identity/DTC/signal results and communication trace | Core |
|
|
| `src/AutoForge.Simulation` | Data-driven virtual modules, isolated state, simulated transport/provider, deterministic fault behavior | Core, Diagnostics |
|
|
|
|
Application may reference Diagnostics but must not reference Simulation.
|
|
Client composes the actual Simulation provider through diagnostic interfaces;
|
|
it may reference Simulation for composition only. UI calls Application/appropriate
|
|
contracts and must not reference Simulation or native adapters. Core, Diagnostics
|
|
and Simulation must not depend on UI, Client or their coordinating application
|
|
slices. Preserve Components independence and production/test separation.
|
|
|
|
Expected solution total: nine projects, still one application executable and the
|
|
same two test projects. Update the existing project-graph assertions deliberately.
|
|
Do not create empty Calibration/Telemetry/AI projects or a new clock/ports assembly.
|
|
|
|
### 2. Add explicit provider and session selection
|
|
|
|
Build the smallest provider-neutral connection/session path:
|
|
|
|
- User selects an exact saved profile/revision and an explicit provider ID/kind.
|
|
Reuse the existing target descriptor/resolver invariants; do not create a
|
|
competing identity/default-selection scheme.
|
|
- A real Simulation provider implements the diagnostic factory/transport path.
|
|
Register its descriptor and implementation consistently from one source of
|
|
registration data. Duplicate/mismatched IDs or kinds fail explicitly.
|
|
- Metadata resolution remains metadata-only. Opening a simulated session is a
|
|
separate explicit action, clearly labeled Simulation in UI/results/trace.
|
|
- Unknown profile/revision, unregistered provider, mismatched kind or missing
|
|
simulation definition fail without choosing a latest/first/demo alternative.
|
|
- RecordedReplay and PhysicalHardware remain unavailable for operational
|
|
connections; do not substitute Simulation or create fake connected providers.
|
|
- Session identity binds the selected profile snapshot, target and configuration.
|
|
No mutable global active vehicle/target. Different sessions have isolated
|
|
virtual state, traces and cancellation/disposal.
|
|
- Closing/resetting a session has explicit lifecycle semantics and releases its
|
|
resources; it does not modify the source profile or another session.
|
|
|
|
Use ordinary DI and async/cancellation where communication requires it.
|
|
Do not introduce a plugin framework, hidden server or service locator.
|
|
|
|
### 3. Define synthetic module behavior as data, not manufacturer assumptions
|
|
|
|
Create a clearly synthetic diagnostic example with at least three module
|
|
instances, including a non-powertrain module. Bind virtual endpoints, identities,
|
|
implemented services, initial DTC state and static signal definitions/values to
|
|
validated profile/module IDs.
|
|
|
|
- Use open module roles/instance IDs; do not special-case the engine/TCU list in
|
|
application features. Demonstrate another inventory/configuration in tests.
|
|
- Validate duplicate addresses/IDs, missing mappings, incompatible profile/revision
|
|
and invalid service/signal definitions explicitly.
|
|
- Preserve schema-v1 profiles and original fixtures. Put endpoint/service/state
|
|
configuration in a separate validated simulation definition rather than adding
|
|
silently ignored fields to the strict profile document.
|
|
- Profile capability/provenance declarations are metadata, not proof of an
|
|
implemented service or authorization. Definition/provider/session availability
|
|
must be distinguished from supplied claims and unknown/inaccessible/restricted/
|
|
unsupported states. Do not silently relabel them.
|
|
- Do not infer implemented service support merely from a role or generic
|
|
`diagnostic.read` declaration. The actual virtual service must exist.
|
|
- Provide an explicit, documented way to load the synthetic example. A user action
|
|
may import its profile; do not auto-import/select a vehicle or silently replace
|
|
the user's existing selection when a page opens.
|
|
- Source-controlled synthetic definitions belong under `src`; avoid duplicated
|
|
fixture copies and no private VIN/calibration/firmware assets.
|
|
|
|
Store deterministic initial state and allow reset to it. Expose runtime state
|
|
only through diagnostics to normal application/UI consumers. Tests may use an
|
|
isolated internal/friend test oracle for independent state assertions; do not
|
|
publish a general ground-truth interface to Application/UI or future AI tools.
|
|
Client needs composition types, not unrestricted runtime state access.
|
|
|
|
### 4. Implement an actual diagnostic request/response path
|
|
|
|
Separate addressing/transport, protocol/service encoding, response validation/
|
|
decoding and application commands. In-process simulated delivery is sufficient,
|
|
but requests must traverse that path rather than directly reading module objects.
|
|
|
|
Implement a small documented **synthetic protocol version 1** unless a verified
|
|
standard is genuinely necessary. Preserve raw immutable request/response payloads
|
|
and define framing, target address, correlation, service and negative outcomes.
|
|
Do not invent CAN/ISO-TP/UDS/OBD/manufacturer semantics and call them authentic.
|
|
|
|
Required operations:
|
|
|
|
1. Discover/probe virtual module endpoints and report actual responders versus
|
|
expected/inaccessible/no-response entries. Returning the profile inventory
|
|
alone is not discovery.
|
|
2. Read module identity through the transport. Validate response address,
|
|
correlation and identity against the selected session/definition; wrong
|
|
identity must be an explicit failure, not silently mapped to the expected one.
|
|
3. Retrieve synthetic diagnostic trouble codes with module/source metadata.
|
|
4. Explicitly clear supported **virtual** DTC state and verify by re-reading and
|
|
an independent test oracle. Do not clear another module/session or unrelated
|
|
data. Unsupported/restricted operations return clear failures.
|
|
5. Read a small static telemetry snapshot appropriate to the configured modules.
|
|
Preserve signal ID, source module, value/type, unit, data quality, logical time
|
|
and simulated/synthetic origin. Unknown values stay unknown.
|
|
|
|
Virtual DTC clearing is not calibration/firmware programming. It must remain
|
|
Simulation-only; no physical command/write path is introduced.
|
|
No dynamic engine/transmission/road-load model, scenario engine or live random
|
|
sensor generation belongs here. Label static responses honestly; do not claim
|
|
fuel economy/physics predictions or actual sensor capture.
|
|
|
|
Malformed payloads, wrong target/correlation, unsupported versions/services and
|
|
negative responses must not produce success-shaped empty data. Distinguish a
|
|
valid empty DTC result from a failed/incomplete request.
|
|
|
|
### 5. Deterministic delays, faults and trace
|
|
|
|
Provide explicit reproducible fault configuration for at least:
|
|
|
|
- Unsupported service/negative response.
|
|
- Inaccessible or non-responding endpoint and request timeout.
|
|
- Malformed response and unexpected module identity/correlation.
|
|
- Interrupted/cancelled request or session closure while work is pending.
|
|
|
|
Use an injected controllable logical diagnostic clock/scheduler or appropriate
|
|
verified .NET time abstraction. No Thread.Sleep-based tests or random/wall-clock
|
|
fault selection. This is diagnostic timing, not permission to build the complete
|
|
Step-04 simulation clock/dynamics engine. Separate optional capture-wall-time
|
|
metadata from logical time and documented reproducibility assertions.
|
|
|
|
Trace must contain ordered immutable request/response/error records with session/
|
|
target/profile/module/address/correlation/service, logical timing, raw payload,
|
|
decoded summary and explicit positive/negative/timeout/cancelled outcome as
|
|
applicable. Do not fabricate a response when none arrived. Preserve enough detail
|
|
to diagnose malformed and mismatched messages.
|
|
|
|
Avoid an unbounded UI/process log. A documented bounded in-memory trace with an
|
|
explicit dropped-record count is sufficient; it is not telemetry recording/
|
|
replay or persistent audit storage. Trace acquisition must not depend on which
|
|
panel is currently visible.
|
|
|
|
### 6. Application feature slices and real UI
|
|
|
|
Implement cohesive features for opening/closing a simulated session, discovering
|
|
modules, reading identity/DTC/signals and explicitly clearing virtual DTCs.
|
|
Group real operations under Vehicles/Diagnostics as useful, with small direct
|
|
handlers/services and explicit results; no class per trivial method or mandatory
|
|
request/handler boilerplate.
|
|
|
|
Application/UI must use the diagnostic interfaces, not Simulation internals.
|
|
Add a feature page/workflow in the existing UI that:
|
|
|
|
- Requires explicit saved profile/revision/provider selection and explicit open/
|
|
close; clearly shows the Simulation target and selected session identity.
|
|
- Displays discovered modules, identity, DTCs and static signals with units/source.
|
|
- Offers only supported logical read/virtual-clear actions and visible errors.
|
|
- Displays inspectable raw/decoded communication trace and loss indication.
|
|
- Handles pending/cancelled/closed states without stale-success presentation.
|
|
- Leaves profile JSON/import/export, exact revision semantics and target metadata
|
|
resolution unchanged and separate from connection.
|
|
|
|
Wire the actual Simulation provider into Client. Review every tightly coupled
|
|
status surface: the old target-selection view model hardcodes an empty registry,
|
|
and home/docs currently say diagnostics are absent. Update these truthful states
|
|
for an available simulated provider, while preserving the distinction between
|
|
metadata selection and session connection. Do not leave an inaccurate
|
|
"no provider registered" notice after registering the real Simulation provider.
|
|
Map intentional UI-text changes in tests; do not delete the underlying safety/
|
|
error/no-fallback assertions.
|
|
|
|
Keep Client thin. No new host, backend, native automotive driver or future
|
|
dashboard/gauge framework is required. Reuse existing generic components.
|
|
|
|
## FILES OR PROJECTS EXPECTED TO CHANGE
|
|
|
|
- Add Diagnostics and Simulation projects, source/definitions and solution entries.
|
|
- Extend Application feature slices and required diagnostic project reference.
|
|
- Add UI feature presentation, routing/navigation and composition/status changes.
|
|
- Add Client composition reference/registration only; no business feature code.
|
|
- Extend existing unit/integration suites and project-graph assertions; no new
|
|
test project. Preserve synthetic profile fixtures and timestamp/evidence fixes.
|
|
- Update root README and actual technical/protocol/simulation/test documentation.
|
|
- Add only `prompts/Step-03-Report.md` under `prompts`.
|
|
|
|
Do not modify assignments/ROADMAP/STATE, historical reports or protected Copilot
|
|
instructions, or create override instructions. Do not stage, commit, push,
|
|
initialize/reset Git or discard unrelated dirty work.
|
|
|
|
## INTERFACE AND DEPENDENCY REQUIREMENTS
|
|
|
|
Preserve typed failures, immutable/snapshotted input/output, explicit selection,
|
|
profile/schema compatibility and metadata-versus-operation boundaries.
|
|
Cancellation/timeout/protocol failure must be distinguishable from success.
|
|
Do not catch broadly or silently select another target/profile/provider.
|
|
|
|
Diagnostics ports and logical use cases must be reusable by a future physical
|
|
adapter, but there is no physical implementation or approval in this step.
|
|
Never route physical/replay selection into a simulated transport. No arbitrary
|
|
hardware frames, memory offsets, programming, backup or AI execution.
|
|
|
|
Use existing maintained SDK/test/package conventions. Add a dependency only for
|
|
an actual required capability after verifying compatibility; do not add tooling/
|
|
containers/services speculatively or change system workloads.
|
|
|
|
## TESTING REQUIREMENTS
|
|
|
|
### Unit and protocol/module tests
|
|
|
|
Exercise actual codec/framing/service logic and virtual state, including:
|
|
|
|
- Valid request/reply shapes and raw payload snapshots; caller mutation cannot
|
|
change already validated messages/trace.
|
|
- Duplicate/missing endpoint/definition validation and more than one inventory.
|
|
- Discovery/identity, DTC retrieval and static telemetry with exact source/units/
|
|
quality; no application bypass of transport.
|
|
- Virtual clear/readback and independent oracle assertions; unrelated module/
|
|
session/profile data preserved; reset restores known initial state.
|
|
- Unsupported/invalid request, wrong version/address/correlation/identity,
|
|
malformed payload and negative outcome handling.
|
|
- Deterministic deadline/latency/fault vectors and cancellation/close, without
|
|
sleeps or arbitrary elapsed-time thresholds.
|
|
- Trace order/content/outcomes and bounded-buffer dropped-record accounting.
|
|
|
|
### Real integration and UI tests
|
|
|
|
Compose actual profile, target, diagnostic protocol and Simulation implementations:
|
|
|
|
1. Explicitly load/select a synthetic profile and Simulation provider, open a
|
|
session, discover modules and read identity/DTC/signals through actual frames.
|
|
2. Clear virtual DTCs and verify fresh diagnostic readback plus the independent
|
|
test oracle. Open another session and prove state isolation.
|
|
3. Inject deterministic errors through the actual wire/transport path; assert
|
|
explicit failure/trace and no false positive results.
|
|
4. Reject unknown profile/revision/provider, wrong kind, missing definition,
|
|
replay/physical operation attempts and any fallback.
|
|
5. Render the real UI with actual application DI: positive module/signal/trace
|
|
views, unsupported/timeout/cancelled states and truthful provider metadata
|
|
notices. Do not mock the feature/component under test.
|
|
6. Preserve profile round-trip/timestamp/optional-applicability behavior, target
|
|
metadata-only resolution, no physical operations and correct dependency graph.
|
|
|
|
Graph assertions must cover all nine projects and allowed references, no reverse
|
|
edges/cycles, one production executable and oracle isolation. Source-policy tests
|
|
supplement actual behavioral integration; no always-passing/DI-only placeholders.
|
|
|
|
### Execution and native evidence
|
|
|
|
Preserve the accepted 140-case baseline invariants (103 unit/37 integration).
|
|
Document any intentional presentation assertion updates caused by the new real
|
|
Simulation provider; do not remove checks or skip acceptance cases.
|
|
|
|
Run focused tests during implementation, then sequentially restore as necessary,
|
|
build the complete solution Release and run both suites:
|
|
|
|
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
|
|
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
|
|
|
|
The full build must include the actual Windows Client and both new libraries,
|
|
not a filtered headless subset reported as complete. Use direct native build if
|
|
needed for target verification; do not override portable projects with Windows
|
|
TFM flags. Record exact commands/exit outcomes, versions/targets, warnings and
|
|
per-project discovered/passed/failed/skipped counts.
|
|
|
|
Launch the actual native Client. Explicitly load/select the synthetic example
|
|
and Simulation provider, open a session, discover modules, inspect identity/DTC/
|
|
signals, clear supported virtual DTCs and re-read them, inspect raw trace and at
|
|
least one visible failure, and close/reset as documented. Verify existing profile,
|
|
target-metadata and not-found routes still work. Record observations separately
|
|
from headless tests; a running process is not proof of UI/service integration.
|
|
Report missing prerequisites honestly without installing workloads or substituting
|
|
another host.
|
|
|
|
## DOCUMENTATION REQUIREMENTS
|
|
|
|
Update README/index/architecture/build guide and add only useful actual documents:
|
|
|
|
- Diagnostics/Simulation responsibilities and project/reference graph.
|
|
- Synthetic protocol version, request/reply/negative/error/correlation rules,
|
|
raw trace shape and explicit non-authentic limitations.
|
|
- Data-driven module/profile binding, service availability versus claims,
|
|
initial/reset state, static signal definitions and test-oracle boundary.
|
|
- Provider/session lifecycle, logical timing/fault reproducibility, cancellation,
|
|
trace capacity/loss and source classification.
|
|
- Actual feature/UI/native usage, synthetic example loading, tests and limitations.
|
|
- A focused ADR for the real capability boundaries/protocol decision.
|
|
|
|
Align lifecycle text with Step-02/Step-02A acceptance and distinguish Step-03
|
|
worker completion from pending orchestrator acceptance. Preserve historical
|
|
reports and the schema-v1 contract. Do not present static simulated readings as
|
|
vehicle dynamics, real diagnostic compatibility or physical programming support.
|
|
|
|
## ACCEPTANCE CRITERIA
|
|
|
|
| ID | Criterion | Required evidence |
|
|
|---|---|---|
|
|
| AC-01 | Nine-project one-shell modular monolith with Diagnostics/Simulation boundaries, no forbidden references/cycles and isolated oracle | Actual solution/reference/source graph, architecture tests and composition paths |
|
|
| AC-02 | Explicit profile/revision/provider/session selection and lifecycle with no metadata-to-connect shortcut, unsupported target or missing-definition fallback | Real positive/negative session tests and native selection observations |
|
|
| AC-03 | Discovery and identity traverse encoded requests, simulated transport and decoded responses, not profile/direct-state reads | Raw frame assertions, actual responders versus expectations and mismatch tests |
|
|
| AC-04 | Synthetic DTC read/virtual-clear/readback/reset and static telemetry work with exact source/units/quality and isolated state | Behavioral tests, independent oracle, multiple sessions/inventories and original-profile preservation |
|
|
| AC-05 | Invalid/unsupported/negative/malformed/timeout/interrupted/cancelled cases are deterministic and never successful empty data | Controlled clock/fault integration vectors with exact failure and lifecycle assertions |
|
|
| AC-06 | Raw/decoded trace preserves correlation, context, logical time and real outcomes, with explicit bounded loss | Trace content/order/immutability/capacity tests and native inspection |
|
|
| AC-07 | Real application slices/UI consume ports, actual Simulation provider is composed, and all old absence/status wording is truthful | Source paths, rendered integration, provider/metadata/session separation and native workflow |
|
|
| AC-08 | Full Release solution/native build, both suites and required native smoke succeed; baseline invariants retained and new real tests added | Exact commands/targets/results, warnings, counts and native observations |
|
|
| AC-09 | README, index, architecture/protocol/simulation/testing docs and ADR match actual scope and limitations | Changed document list and implemented/planned/source-fidelity summary |
|
|
| AC-10 | Historical work/protected files/manual workflow preserved; complete report saved and worker stops | Preservation/Git/scope review and `prompts/Step-03-Report.md` |
|
|
|
|
Map every criterion to PASSED, FAILED, NOT EXECUTED or BLOCKED with concrete
|
|
evidence. COMPLETE requires required build/test/native checks. Incomplete
|
|
communication, verification or missing prerequisites cannot be reported as success.
|
|
|
|
## OUT-OF-SCOPE WORK
|
|
|
|
Full vehicle dynamics/clock/scenario engine, live physics-driven gauges, telemetry
|
|
recording/replay/comparison, calibration values/editing/programming/backups,
|
|
physical adapters/drivers or real vehicle access, AI/research/knowledge services,
|
|
databases, cloud/container infrastructure, extra executables/platforms, automatic
|
|
handoffs and unrelated refactoring. No emissions defeat, anti-theft bypass,
|
|
mileage falsification or safety disabling functionality.
|
|
|
|
## REPORTING REQUIREMENTS
|
|
|
|
Create `prompts/Step-03-Report.md` entirely inside exactly one plain triple-backtick
|
|
code fence, without language tag or outside content. Use no nested fences.
|
|
Use the same copy-window format for the final chat report.
|
|
|
|
Include step/title and COMPLETE/INCOMPLETE/BLOCKED status; implemented functions;
|
|
files/projects created/modified; actual reference graph and interfaces; provider/
|
|
session and synthetic wire contract; virtual state/static-signal/fault/trace
|
|
semantics; unit/integration tests and baseline/intentional UI assertion mapping;
|
|
exact restore/build/test commands/results with per-project counts; native
|
|
workflow/trace observations; AC-01 through AC-10 evidence; documentation and
|
|
README updates; limitations/outstanding issues; deviations/recommendations; and
|
|
protected/scope/Git preservation review.
|
|
|
|
No unexecuted test may be marked passed. No synthetic data implies hardware
|
|
compatibility/authority. Save the report and STOP. Do not change assignments/
|
|
roadmap/state, create or begin Step-04, invoke agents, automate handoff, stage,
|
|
commit or push.
|