# 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.