AutoForge/docs/synthetic-diagnostics-v1.md

8.3 KiB

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.

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:

{
  "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:

{
  "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.