AutoForge/prompts/Step-03.md

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.