AutoForge/docs/synthetic-diagnostics-v1.md

175 lines
8.7 KiB
Markdown

# Synthetic diagnostics protocol v1
## Purpose and limitations
Protocol v1 is a small, explicit JSON request/reply contract used only between
the provider-neutral diagnostic protocol client and the in-process synthetic
simulation transport. The frames are UTF-8 JSON. They are not CAN, ISO-TP, UDS,
OBD-II, a manufacturer protocol, or a claim of vehicle compatibility. No
physical transport or vehicle operation is implemented.
V1 is intentionally static. Its `SYNTHETIC_STATIC` signals retain request-start
logical-tick semantics and are not the Step-04 dynamics path. The separate
[`SYNTHETIC_DYNAMIC` protocol-v2 extension](synthetic-diagnostics-v2.md) binds
computed telemetry to an exact dynamics configuration and run; the static v1
provider and strict v1 parsing behavior are unchanged.
The actual capability path is:
1. `SyntheticDiagnosticProtocolClient` builds and encodes a request.
2. The encoded bytes cross `IDiagnosticTransport.SendAsync`.
3. The simulation transport decodes the request, checks its bound session and
profile/configuration, selects a configured virtual endpoint by address and
service, and creates a response or explicit transport outcome.
4. The protocol client validates the response envelope/correlation and decodes
service data into typed results. Identity is compared with the exact selected
profile snapshot.
5. The exchange is added to that session's bounded trace with copied payloads
and logical timing.
The application and UI never read the simulation module objects directly.
## Request
The request contains protocol version, session/profile/configuration identity,
correlation identifier, target address, service identifier, logical start tick
and logical timeout:
```json
{
"version": 1,
"sessionIdentifier": "diagnostic-session-000001",
"profileIdentifier": "autoforge.synthetic.test-truck",
"profileRevision": 1,
"configurationIdentifier": "profile:autoforge.synthetic.test-truck@revision:1",
"correlationIdentifier": "diagnostic-session-000001-000001",
"targetAddress": "10",
"service": "probe",
"logicalTimeTicks": 0,
"timeoutTicks": 5
}
```
All ten top-level fields shown are required on the wire. Protocol fields use
exact camelCase spelling; names are case-sensitive. The decoder rejects a
missing field rather than filling it from a C# initializer or primitive
default. An explicitly supplied `logicalTimeTicks: 0` is valid. Unknown fields,
case variants and duplicate properties are rejected recursively before session
binding, endpoint selection or service dispatch. A malformed request receives
the transport's explicit no-response outcome; it does not dispatch a service,
and no response correlation is fabricated from ambiguous input. A complete
request with explicit version `2` remains distinguishable and receives the
typed `UNSUPPORTED_VERSION` negative response.
The address is a one-to-four digit hexadecimal text value. Module IDs are
separate diagnostic context and are never inferred from an address alone. The
current service identifiers are `probe`, `read.identity`, `read.dtcs`,
`clear.dtcs` and `read.signals`. These are AutoForge's synthetic service names,
not standardized vehicle commands.
## Reply and failures
Every received reply includes version, session/configuration, correlation,
target address, service, a success flag, optional error code/message and data.
A positive example:
```json
{
"version": 1,
"sessionIdentifier": "diagnostic-session-000001",
"configurationIdentifier": "profile:autoforge.synthetic.test-truck@revision:1",
"correlationIdentifier": "diagnostic-session-000001-000001",
"targetAddress": "10",
"service": "probe",
"success": true,
"errorCode": null,
"error": null,
"data": {
"moduleIdentifier": "module.engine.primary",
"implementedServices": ["probe", "read.identity", "read.dtcs", "clear.dtcs", "read.signals"]
}
}
```
A negative service reply uses `success: false`, a typed error code/message and
`data: null`; an unsupported operation is never represented as a successful
empty collection. Wrong version, session/configuration, correlation, address or
service is rejected. Malformed JSON or required fields produce
`ProtocolError`. A valid DTC reply with an empty `codes` array is distinct from
all failures.
Discovery records the validated probe and identity exchange as separate
results. A positive probe retains its validated module ID and immutable
advertised service list even if identity is later unavailable, negative,
malformed, mismatched, timed out or cancelled. If `read.identity` was not
advertised, the client does not send that unsupported request and records an
explicit not-attempted reason. A failed probe has no advertised services and
identity remains not attempted. The result exposes expected endpoint count,
validated positive probe count and profile-verified identity count separately.
Profile metadata never fills an absent runtime identity or grants permission.
The UI shows partial probe evidence, but identity-dependent read/clear actions
remain disabled until identity is validated against the selected profile.
The receiver requires every envelope field shown, exact camelCase spelling,
unique properties at every object level and no unknown fields. Positive replies
must carry an object `data` and null `errorCode`/`error`; negative replies must
carry nonblank `errorCode`/`error` and null `data`. Each interpreted service
object has its own exact required-field set. Identifiers/text must be nonblank
and trimmed; DTC codes, advertised services and signal identifiers are unique.
Probe replies must name the requested module and advertise only known, unique
v1 service tokens, including `probe`. Identity is compared with the selected
profile snapshot. Static-signal source/module and quality are validated; the
snapshot logical tick must equal the request start tick. Any invalid or
ambiguous response produces `ProtocolError` with no partial result value.
Signal `value` remains an explicit arbitrary JSON value, including `null` for
unknown; protocol envelope/service objects themselves reject unknown members.
No-response, timeout and cancellation are transport outcomes, not fabricated
JSON replies. Their trace record has the immutable request bytes and no response
payload. A configured no-response endpoint is not counted as a validated probe;
an earlier successful probe remains positive in its own trace record even when
the subsequent identity exchange fails.
An accepted `clear.dtcs` positive response is only an acknowledgement. The
Application clear-and-verify use case performs a fresh `read.dtcs` request and
reports verified success only when that valid response contains an empty code
set. A nonempty readback is retained as observed data and reported as a
verification failure; any failed/uncertain readback is not a verified clear.
This result describes in-memory Simulation state only; it is not a physical
write.
## Logical timing and concurrency
The logical clock is injected per diagnostic session. Successful transport
delivery advances it by deterministic configured response ticks; no
wall-clock-based fault choice or random delay is used. A request includes a
logical timeout of five ticks. A virtual latency greater than the deadline
returns Timeout without a response. The protocol client serializes exchanges
per session so correlation sequence, logical time and retained trace order stay
consistent.
`HoldUntilCancelled` is a deterministic blocking fault released only by
cancellation or session close. No `Thread.Sleep` is used. The logical clock is
for diagnostics only; it is not the Step-04 dynamics/scenario clock.
## Trace
Each session keeps at most 200 in-memory records. Every record contains session
identity (including exact target/profile/revision/configuration), module/address,
correlation, service, start/end logical ticks, copied request bytes, optional
copied response bytes, typed outcome, decoded summary and explicit error text.
The oldest entry is dropped at capacity and `DroppedRecordCount` increases.
The response is validated completely before positive result and trace commitment;
semantic probe failures therefore have one `ProtocolError` record with the
actual raw reply instead of a positive record followed by a contradictory
discovery result.
The trace is session-local, not persistent logging, telemetry recording or
replay. Closing the session releases the trace with its transport state.
Cancellation after a successful probe retains that phase's probe/service facts
and records cancellation only for the pending identity exchange; closing the
session suppresses stale UI updates and releases the active session results.
The UI renders decoded summaries and lets the user inspect raw UTF-8 request and
response JSON. It labels synthetic operation results and never describes them
as live vehicle capture.