4.9 KiB
ADR-0004: Provider-neutral synthetic diagnostics boundary
- Status: Step-03A corrective implementation and verification complete; manual orchestrator acceptance of Step-03 remains pending.
- Date: 2026-10-29.
Context
The accepted profile slice provides explicit immutable metadata and capability claims, not actual module services, communication or vehicle access. Step-03 requires proving that diagnostics requests traverse a transport, that failures remain truthful, and that deterministic virtual state can be inspected without claiming a real automotive standard or adding a physical adapter.
Decision
Add exactly two portable capability libraries:
AutoForge.Diagnosticsowns provider-neutral transport/session/operation contracts, typed results, a synthetic protocol-v1 codec/client and bounded trace.AutoForge.Simulationowns data-driven virtual module definitions, isolated per-session state, and an in-process transport implementing the diagnostics factory/transport ports.
Application coordinates exact profile/revision/provider/kind selection and
session lifecycle using Diagnostics interfaces only. The native Client composes
the Simulation provider from a single factory/descriptor registration source.
UI owns /diagnostics, requires explicit import/selection/open, and consumes
Application/Diagnostics APIs. Metadata resolution remains separate from session
opening. Simulation is never a fallback for replay or physical kinds.
Synthetic protocol v1 uses UTF-8 JSON with explicit version/session/profile/ configuration/correlation/address/service/logical-time/deadline fields and positive or negative replies. Actual frames cross the transport port. Malformed, mismatched, unsupported, no-response, timeout and cancellation results remain typed failures. Static synthetic signals and virtual DTCs are data, not dynamics, vehicle capture or physical writes. A session owns deterministic state and a bounded 200-entry trace; reset closes/reopens exact selected configuration. Only integration tests can access the internal state oracle.
The Step-03A correction requires every request/envelope/service property with exact camelCase spelling, rejects unknown and duplicate properties before dispatch or interpretation, and validates all service payload semantics before returning a positive value or trace outcome. A complete unsupported protocol version remains an explicit version failure. Malformed requests do not dispatch or mutate state. Probe identity/service claims and trace outcomes are validated in the protocol exchange path.
An acknowledged virtual DTC clear is not a verified state change. Application coordinates the clear and a fresh DTC read; only a valid empty readback is verified success. Nonempty data is retained as observed with verification failure, while failed/uncertain readback is not reported as success. The operation remains Simulation-only and performs no physical write.
Consequences
- The application has a real, testable diagnostics path without a hardware driver, backend, generic plugin framework or extra executable.
- Services are declared in simulation data and discovered by real protocol probes; profile capability claims do not grant them.
- Discovery keeps expected endpoints, validated positive probes and identities verified against the selected profile as distinct facts. Probe services survive later identity failures; profile metadata never fills runtime identity, and read/clear actions remain identity-gated.
- Each wire phase keeps its own immutable raw/decoded trace outcome, including cancellation or failure after a positive probe.
- Invalid frames cannot select state-changing services through missing defaults or duplicate fields, and semantic response errors cannot appear as successful values or contradictory positive trace records.
- The new protocol is intentionally non-authentic and cannot be used as evidence of standards compatibility. There is still no physical or replay provider, vehicle dynamics, telemetry capture/replay, programming or calibration write.
- Future providers may implement the provider-neutral Diagnostics ports only through a separately approved assignment and operation-specific safeguards.
Alternatives considered
- Treat profile capability claims as implemented services: rejected because metadata is not executable behavior or authorization.
- Read virtual state directly from Application/UI: rejected because it would bypass request/transport/response validation and conceal communication faults.
- Reuse Simulation for physical/replay selections: rejected because it creates false connection semantics and unsafe fallback behavior.
- Adopt a real automotive standard: rejected because this milestone has no validated hardware/standard transport, and calling synthetic frames authentic would be misleading.
- Add a general protocol/plugin/clock assembly or full dynamics engine: rejected as unnecessary to this bounded vertical slice.