Typed routine result contracts

run_routine differs from the read commands in one respect: two different ABS pump-cycle tests can complete with the same UDS success code and mean different things — cycles completed as expected, cycles short of expected, or a marginal deviation the operator should track. The transport layer cannot see this; the guidance encodes it at the payload layer as a per-routine result schema plus a verdict.

Per-routine result schema

Each remotely invocable routine has an entry in a schema registry that declares:

• A version number, for wire-compatible evolution.

• A fields list — the flat set of primitives (scalars, or 1-level arrays of scalars) the routine’s result dict is required to contain, each with a name, type, unit, and short description.

• A verdict function — a pure function that maps a valid result dict to one of in_spec, marginal, or out_of_spec. Missing fields default to in_spec (a defensive default, not a crash path).

• A renderer hint — advisory metadata the operator UI uses to select a rendering surface (table, key-value grid, list). Not enforcement; the operator UI is free to render more richly.

The schemas are colocated with the routine catalog so a routine cannot ship a schema without a catalog entry; an import-time guard fails the build if the two disagree.

Verdict on the wire

A successful run_routine response carries a typed result and the verdict computed from it:

{
  "correlation_id": "…",
  "status": "SUCCEEDED",
  "routine_id": "evap_leak_test",
  "result": {
    "system_pressure_kpa": 3.4,
    "leak_rate_ccm": 0.8
  },
  "verdict": "marginal",
  "latency_ms": 5200
}

The verdict is computed by the sidecar (or the sim producer, in the deterministic testing path) and written into the payload before publish. The operator UI reads response.verdict directly and does not recompute — recomputation on the client is explicitly disallowed, because the verdict is a safety-shaped output and the wire value is the audit record.

Verdict bands and renderer patterns are stable across routines: in_spec renders green, marginal renders amber, out_of_spec renders red, and the underlying result values render alongside the verdict so an operator can see why the classification was made rather than only what it was.

Pilot routines

The v1 pilot covers six routines chosen to exercise five distinct rendering patterns and both ICE and EV powertrain surfaces:

routine_id	Renderer hint	What is measured
lamp_self_check	list	Per-lamp verdict array (ok / dim / flicker / open_circuit / short) plus ambient light reading.
o2_heater_check	kv_grid	Bank-1 upstream O2 sensor heater response time vs manufacturer threshold.
evap_leak_test	kv_grid	EVAP system pressure and measured fuel-vapour leak rate.
abs_pump_cycle	kv_grid	Observed vs expected ABS pump cycle count.
pack_isolation_test	kv_grid	HV traction-battery isolation resistance vs manufacturer minimum.
cell_balance_check	table	Per-cell voltage array plus derived maximum inter-cell delta.

Each routine registers its own schema entry. A routine without a registered schema falls back to a raw-JSON renderer with no verdict banner, so it degrades legibly rather than crashing the operator surface.