AutoForge/docs/adr-0004-synthetic-diagnost...

90 lines
4.9 KiB
Markdown

# 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.Diagnostics` owns provider-neutral transport/session/operation
contracts, typed results, a synthetic protocol-v1 codec/client and bounded
trace.
- `AutoForge.Simulation` owns 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.