AutoForge/docs/synthetic-diagnostics-v2.md

91 lines
5.0 KiB
Markdown

# Synthetic diagnostics protocol v2: dynamics telemetry
## Compatibility boundary
Protocol v2 is an explicit UTF-8 JSON extension for the separate
`autoforge.simulation.dynamics` provider. It does not reinterpret or weaken
[protocol v1](synthetic-diagnostics-v1.md): `autoforge.simulation.synthetic`
continues to require v1 static semantics, including origin
`SYNTHETIC_STATIC` and the request-start logical tick. A static session cannot
acquire dynamics controls, and a dynamics session must be opened with a
validated immutable format-v1/model-v1 `DynamicsConfiguration`. This protocol
is synthetic in-process JSON, not CAN/ISO-TP/UDS/OBD-II or a manufacturer
protocol.
The request envelope has the same required top-level fields as v1, but its
`version` is exactly `2` and its `configurationIdentifier` binds the selected
profile revision and stable dynamics fingerprint. `sessionIdentifier` and the
separate dynamics run identifier provide operational isolation. The request's
`logicalTimeTicks` is the diagnostic capture/request clock; it is not model
time.
## Dynamic `read.signals` payload
All v2 response envelopes retain the strict v1 envelope/correlation fields,
with `version: 2`. The `read.signals` data object has exactly these required
fields:
| Field | Meaning |
|---|---|
| `moduleIdentifier` | Exact requested engine or transmission module |
| `configurationIdentifier` | Stable `sha256:v1:<hex>` configuration fingerprint |
| `runIdentifier` | Operational dynamics-run ID bound to this session |
| `modelStepIndex` | Nonnegative integer fixed-step count |
| `modelTimeSeconds` | Virtual model time, equal to step index times configured step seconds |
| `origin` | Exactly `SYNTHETIC_DYNAMIC` |
| `captureLogicalTimeTicks` | Diagnostic logical start tick, exactly matching the request |
| `signals` | Exact source module signal list, with identifier, JSON value, unit and quality |
Signal identifiers and units are validated exactly. Engine signals are
`engine.running` (boolean), `engine.speed` (rpm), `vehicle.speed` (m/s),
`engine.throttle` (ratio), `engine.load` (ratio), `engine.torque` (N*m),
`engine.fuel-rate` (kg/s), `engine.fuel-consumed` (kg),
`engine.temperature` (degC), `vehicle.distance` (m),
`vehicle.acceleration` (m/s^2), and `driver.brake` (ratio). Transmission
signals are `transmission.gear` (gear), `transmission.shift-count` (count),
`transmission.coupling-slip` (ratio), `vehicle.speed` (m/s), and
`engine.speed` (rpm). Numeric dynamic values must be finite JSON numbers;
identifiers, source module, units, quality, origin and model/run/configuration
identity are retained in the typed snapshot.
The receiver rejects duplicate/unknown/missing fields, unsupported versions,
invalid correlation/envelope identity, wrong module, unexpected dynamic signal
or unit, non-finite numeric telemetry, wrong capture tick, invalid model step/
time, and configuration/run mismatch as `ProtocolError` with no partial value.
The configured step size is used to validate
`modelTimeSeconds = modelStepIndex * stepSeconds`. Positive replies preserve
the transport's elapsed diagnostic ticks in bounded trace timing; those ticks
remain independent from model step/time.
Every request samples the engine once under its state lock and serializes that
snapshot. A paused or explicitly stepped run therefore returns the same
step/time from engine and transmission reads until a control step occurs. While
the asynchronous scenario pacer is running, separate requests can capture
different steps; each response reports its actual step/time and does not imply
simultaneous capture. Reads themselves never advance the engine.
A faulted run never serializes a positive dynamic snapshot: `read.signals`
returns a correlated v2 negative response with failure code
`DYNAMICS_RUN_FAULTED` and the retained lifecycle reason. It does not replace a
failed computation with zero-valued or empty `Good` signals. The UI preserves
that terminal failure and clears any previously displayed rows so older
successful values cannot be mistaken for current post-fault telemetry.
Probe, identity, DTC and clear service names retain their v1 service-level
shapes inside a v2 envelope. Dynamics module services are still checked against
their explicit endpoint advertisement; provider selection never falls back to
the static provider. Static protocol clients and static provider response
versions remain v1. The actual strict client and provider implementation is in
`AutoForge.Diagnostics` and `AutoForge.Simulation`; Application/UI telemetry
still traverses encoded diagnostic frames rather than a model-state oracle.
## Limitations
The origin means generated by this AutoForge synthetic model only. Quality
`Good` means the deterministic synthetic computation completed, not sensor
quality or real vehicle truth. The model omits detailed engine combustion,
torque-converter dynamics, tire/road conditions, gearshift transient mechanics,
thermal circuits, emissions, manufacturer calibration and uncertainty
quantification. Protocol v2 is not evidence of compatibility, prediction
accuracy, safe tuning or physical authorization.