bmweb-cli 0.1.0

package/runtime/core/webshim/framing.js

@@ -0,0 +1,331 @@
+/**
+ * @file Concept-aware framing: which checksum, which length rule and which
+ * port settings each EDIABAS concept uses.
+ *
+ * The SGBD's telegram EXCLUDES its trailing checksum -- appending it is the
+ * interface's job (learned the hard way: a request one byte short is silently
+ * discarded by a real ECU). Framing per concept, from each job's xsetpar
+ * CommParameter {concept, baud, timeout}, verified against data/sim-captures:
+ *
+ *   1/5/6   DS2 family   9600 8E1   XOR checksum   answer[1] = total length
+ *   0x10D   KWP2000*     9600 8E1   sum8           answer[3] + 5 = total
+ *   0x10F   BMW-FAST   115200 8N1   sum8           header short/long form
+ *   0x110   D-CAN      115200 8N1   sum8           (CAN cable, BMW-FAST serial)
+ *   0x10C   ISO 9141   10400 8N1   sum8           after a 5-baud slow init
+ *
+ * The wire is described by the SGBD's set_communication_pars and nothing
+ * else. A telegram with no CommParameter behind it has no baud, no checksum
+ * rule and no length rule -- EDIABAS refuses it (IFH-0056), so do we, rather
+ * than assume BMW-FAST and sign a DS2 request with the wrong checksum.
+ */
+/* exported KDCAN, UTILITY_NOMINAL_MV, KLINE_DEFAULT_BAUD, conceptOf, isDs2, isIso9141, isKline, isBmwFast, assertReachable, ISO9141_INIT_ADDR, ISO9141_BAUD, ifhError, withChecksum, frameTotal, verifyChecksum, portConfig */
+
+/**
+ * The wire parameters an SGBD declares with xsetpar (Best2Vm.decodeCommParams),
+ * carried beside every telegram so the transport can frame, sign and pace it.
+ * @typedef {object} CommParams
+ * @property {number} concept - EDIABAS concept: 1/5/6 DS2, 0x10C ISO 9141,
+ *   0x10D KWP2000*, 0x10F BMW-FAST, 0x110 D-CAN.
+ * @property {number} [baud] - The rate the SGBD names (CommParameter[1]).
+ * @property {number|null} [timeout] - ParTimeoutStd: ms the ECU may take to
+ *   START answering.
+ * @property {number|null} [regen] - ParRegenTime: ms of quiet the ECU needs
+ *   after its answer before the next request.
+ * @property {number|null} [telEnd] - ParTimeoutTelEnd (inter-byte silence).
+ * @property {number|null} [timeoutNr78] - ParTimeoutNr78: ms the ECU may say
+ *   "busy" (7F xx 78) between polls.
+ * @property {number[]} [answerLen] - The DS2 xawlen rule: [offset|length, add].
+ * @property {number} [waitMs] - A `wait` the SGBD issued before this telegram.
+ * @property {number[]} [params] - The raw CommParameter words.
+ */
+
+/**
+ * Web Serial / native port settings.
+ * @typedef {object} PortConfig
+ * @property {number} baudRate - Bits per second.
+ * @property {number} dataBits - Always 8 here.
+ * @property {number} stopBits - Always 1 here.
+ * @property {'none'|'even'} parity - 8N1 for BMW-FAST/ISO 9141, 8E1 on the K line.
+ * @property {boolean} [dtr] - The IDLE level of DTR for this concept: high on
+ *   BMW-FAST/D-CAN, low on every K-line concept (see portConfig).
+ */
+
+/**
+ * K+DCAN over Web Serial. Default until a job's SGBD declares its own via
+ * xsetpar: BMW-FAST 115200 8N1 (the USB cable's default concept), DTR high.
+ * @type {PortConfig}
+ */
+const KDCAN = {
+  baudRate: 115200,
+  dataBits: 8,
+  stopBits: 1,
+  parity: 'none',
+  dtr: true,
+};
+/**
+ * UTILITY.PRG's own number, read out of its BEST/2 bytecode: UTILITY /
+ * INTERFACE substitutes 12000 mV when the interface cannot measure at all,
+ * and STATUS_UBATT / STATUS_ZUENDUNG both compare the adapter's sense reading
+ * against 10000 mV (`comp L0, 10000` / `jae`), so the nominal value reads as
+ * "on".
+ */
+const UTILITY_NOMINAL_MV = 12000;
+/** The K-line rate EDIABAS falls back to when an SGBD names none (8E1). */
+const KLINE_DEFAULT_BAUD = 9600;
+
+/**
+ * The concept a telegram rides on, or IFH-0056 when the SGBD never set one.
+ * @param {CommParams|null|undefined} comm - The telegram's wire parameters.
+ * @returns {number} The concept id.
+ * @throws {Error} IFH-0056 when no CommParameter precedes the telegram.
+ */
+const conceptOf = (comm) => {
+  if (!(comm && comm.concept)) {
+    throw ifhError('IFH-0056', 'no CommParameter set before the telegram');
+  }
+  return comm.concept;
+};
+/**
+ * Is this a DS2-family concept (1, 5, 6)?
+ * @param {number} c - The concept id.
+ * @returns {boolean}
+ */
+const isDs2 = (c) => c === 1 || c === 5 || c === 6;
+/**
+ * ISO 9141-2: the module sleeps until a 5-baud address byte wakes it.
+ * @param {number} c - The concept id.
+ * @returns {boolean}
+ */
+const isIso9141 = (c) => c === 0x10c;
+/**
+ * Concepts that ride the K line and therefore need DTR as transmit enable.
+ * DS2 and KWP2000* are K-line; BMW-FAST/D-CAN (0x10F/0x110) are not.
+ * @param {number} c - The concept id.
+ * @returns {boolean}
+ */
+const isKline = (c) => isDs2(c) || c === 0x10d;
+/**
+ * BMW-FAST (0x10F) and D-CAN (0x110): the two concepts on which the reference
+ * interface holds DTR HIGH for the whole session on a plain FTDI/COM cable
+ * (`stateDtr = HasAdapterEcho`, set in exactly these two cases and nowhere
+ * else). Every other concept idles with DTR low.
+ * @param {number} c - The concept id.
+ * @returns {boolean}
+ */
+const isBmwFast = (c) => c === 0x10f || c === 0x110;
+/**
+ * Concepts that only the old BMW ADS interface can drive: concept 1, concept
+ * 2 (ISO 9141 / KWP1281 5-baud) and concept 3. They need the L line on OBD
+ * pin 20 and ADS-style line control; the reference interface refuses all
+ * three on any echoing adapter ("only with ADS adapter", IFH-0006), and a
+ * K+DCAN cable is one. The 76 SGBDs that declare them are the early E31,
+ * E34, E36, E38 and E39 modules (Motronic 1.7 to 5.2.1, DDE 2.1, ZF EGS,
+ * the first ABS and IHKA). Refusing here, with the reason, beats signing a
+ * request the cable can never deliver and reporting "no answer".
+ */
+const ADS_ONLY_CONCEPTS = new Set([1, 2, 3]);
+/**
+ * Refuse a concept this cable cannot physically reach, before anything is
+ * configured or written.
+ * @param {CommParams|null|undefined} comm - The telegram's wire parameters.
+ * @throws {Error} IFH-0006 for an ADS-only concept.
+ */
+function assertReachable(comm) {
+  const c = conceptOf(comm);
+  if (ADS_ONLY_CONCEPTS.has(c)) {
+    throw ifhError(
+      'IFH-0006',
+      `concept ${c} needs the ADS interface (L line, OBD pin 20); ` +
+        'a K+DCAN cable cannot reach this module'
+    );
+  }
+}
+/**
+ * Verified on a real E46 (M54 / MS45): the DME answers the ISO 9141 generic
+ * tester address at 10400 baud, NOT its own KWP address at 9600. Sending a
+ * job to an unwoken module gets silence, which surfaced as IFH-0009 "no
+ * response" and looked for all the world like a wiring fault.
+ */
+const ISO9141_INIT_ADDR = 0x33;
+/**
+ * The rate an E46 K-line module actually answers on after the slow or fast
+ * init -- 9600 (either parity) stays silent even after a successful wake.
+ */
+const ISO9141_BAUD = 10400;
+
+/**
+ * Build an interface failure carrying its EDIABAS IFH identity, so
+ * explainError and a user comparing to real INPA see the same code (IFH-0009
+ * no answer, -0003 line/echo, -0019 truncated). SGBD-level ERROR_ECU_* stay
+ * the jobs' business.
+ * @param {string} code - The IFH code, e.g. 'IFH-0009'.
+ * @param {string} message - What went wrong, in plain words.
+ * @returns {Error & {ifh: string}} The error, tagged with `ifh`.
+ */
+function ifhError(code, message) {
+  const e = new Error(`${code}: ${message}`);
+  e.ifh = code;
+  return e;
+}
+
+/**
+ * Which EDIABAS transmit function a concept runs, and therefore its checksum
+ * and its answer-length rule (the reference interface's `switch (concept)`
+ * that sets ParTransmitFunc):
+ *   1, 5, 6            TransDs2         XOR    length from xawlen (TelLengthDs2)
+ *   0x10D KWP2000*     TransKwp2000S    XOR    byte[3] + 4      (TelLengthKwp2000S)
+ *   0x10B/0x10C/0x10F  TransKwp2000Bmw/ sum    TelLengthBmwFast
+ *   0x110 D-CAN        TransBmwFast
+ * Nothing here looks at the first byte of a frame to decide -- 0xB8 is just
+ * the tester address KWP2000* and BMW-FAST both use.
+ */
+const XOR_CONCEPTS = new Set([1, 5, 6, 0x10d]);
+/**
+ * The reference interface's per-concept CommAnswerLen seed, used when an
+ * SGBD never issues xawlen: [-o, k] = byte at offset o plus k.
+ * @type {Record<number, [number, number]>}
+ */
+const DS_ANSWER_LEN_DEFAULT = { 1: [-2, 0], 5: [-1, 0], 6: [-1, 0] };
+/** Concepts whose checksum is the 8-bit sum (see XOR_CONCEPTS). */
+const SUM_CONCEPTS = new Set([0x10b, 0x10c, 0x10f, 0x110]);
+
+/**
+ * The checksum a concept puts after its telegram.
+ * @param {ArrayLike<number>} bytes - The telegram without its checksum.
+ * @param {number} c - The concept id.
+ * @returns {number} XOR or sum8 of the bytes.
+ * @throws {Error} IFH-0018 for a concept this interface cannot sign.
+ */
+function checksumOf(bytes, c) {
+  let sum = 0;
+  if (XOR_CONCEPTS.has(c)) {
+    for (const b of bytes) sum ^= b;
+    return sum;
+  }
+  if (SUM_CONCEPTS.has(c)) {
+    for (const b of bytes) sum = (sum + b) & 0xff;
+    return sum;
+  }
+  throw ifhError(
+    'IFH-0018',
+    `concept 0x${c.toString(16)} is not supported on this interface`
+  );
+}
+
+/**
+ * Append the concept's checksum to an outgoing telegram.
+ * @param {ArrayLike<number>} out - The request as the SGBD built it.
+ * @param {CommParams} comm - Its wire parameters.
+ * @returns {number[]} The framed request, ready for the wire.
+ */
+function withChecksum(out, comm) {
+  return [...out, checksumOf(out, conceptOf(comm))];
+}
+
+/**
+ * Total frame length INCLUDING the checksum byte, or null while too few
+ * bytes are in to know. Each rule is its EDIABAS TelLength* + 1.
+ * @param {number[]} buf - The bytes received so far.
+ * @param {CommParams} comm - The wire parameters of the request.
+ * @returns {number|null} The frame length, or null while undecidable.
+ * @throws {Error} IFH-0018 for an unsupported concept or a DS2 job with no
+ *   answer-length rule at all.
+ */
+function frameTotal(buf, comm) {
+  const c = conceptOf(comm);
+  if (XOR_CONCEPTS.has(c) && c !== 0x10d) {
+    // DS2: the rule the SGBD declared with xawlen (TelLengthDs2), or, when it
+    // never did, EDIABAS's own default for the concept -- every xsetpar seeds
+    // CommAnswerLen per concept (DS1/DS2 = [-1, 0] "byte 1 is the total
+    // length", concept 1 = [-2, 0]) and xawlen only overrides it. The E46
+    // steering-angle group d_0057 is 99 ops and never calls xawlen; refusing
+    // its exchange here made the resolver log "bus-silent" for a sensor that
+    // answers every time, and the scan printed "not installed".
+    let al = comm && comm.answerLen;
+    if (!al || !al.length) al = DS_ANSWER_LEN_DEFAULT[c];
+    if (!al) {
+      throw ifhError(
+        'IFH-0018',
+        'DS2 answer length not set by the SGBD (xawlen)'
+      );
+    }
+    if (al[0] > 0) return al[0];
+    const off = -al[0];
+    return buf.length > off ? buf[off] + (al[1] || 0) : null;
+  }
+  // KWP2000* (0x10d): these answers always carry the B8 F1 12 address header,
+  // so byte 0 (0xB8) is NOT a BMW-FAST length byte -- the length is byte 3,
+  // and the frame is byte3 + 4 header + 1 checksum. Verified against a real
+  // MS45 EDIABAS trace: byte3 0x1F -> 36 bytes, 0x41 -> 70, 0xFF -> 260. (Do
+  // NOT apply TelLengthBmwFast's byte0-&-0x3F rule here: 0xB8 & 0x3F = 56
+  // would force every answer to 60 bytes.)
+  if (c === 0x10d) return buf.length >= 4 ? buf[3] + 4 + 1 : null;
+  if (SUM_CONCEPTS.has(c)) {
+    // TelLengthBmwFast -- length in the low 6 bits of byte 0, with byte 3 (or
+    // bytes 4-5) as the long-form fallback.
+    if (!buf.length) return null;
+    const short = buf[0] & 0x3f;
+    if (short) return short + 3 + 1;
+    if (buf.length < 4) return null;
+    if (buf[3] === 0)
+      return buf.length >= 6 ? (buf[4] << 8) + buf[5] + 6 + 1 : null;
+    return buf[3] + 4 + 1;
+  }
+  throw ifhError(
+    'IFH-0018',
+    `concept 0x${c.toString(16)} is not supported on this interface`
+  );
+}
+
+/**
+ * Check a complete frame's trailing checksum against its concept's rule.
+ * @param {number[]} frame - The whole answer including its checksum byte.
+ * @param {CommParams} comm - The wire parameters of the request.
+ * @throws {Error} IFH-0019 on a mismatch.
+ */
+function verifyChecksum(frame, comm) {
+  const want = checksumOf(frame.slice(0, -1), conceptOf(comm));
+  if (want !== frame[frame.length - 1]) {
+    throw ifhError('IFH-0019', 'answer checksum mismatch');
+  }
+}
+
+/**
+ * The port settings a concept's telegrams travel on.
+ * @param {CommParams} comm - The telegram's wire parameters.
+ * @returns {PortConfig} Baud, bits and parity for the port.
+ */
+function portConfig(comm) {
+  const c = conceptOf(comm);
+  if (isIso9141(c)) {
+    // 8N1 after the handshake -- the init itself is bit-banged, not framed.
+    // DTR idles low: the reference raises the idle level for BMW-FAST and
+    // D-CAN only, never for 0x10C.
+    return {
+      baudRate: (comm && comm.baud) || ISO9141_BAUD,
+      dataBits: 8,
+      stopBits: 1,
+      parity: 'none',
+      dtr: false,
+    };
+  }
+  if (isKline(c)) {
+    // DS2 and KWP2000* are 8E1 at the rate the SGBD names (concept 6 in the
+    // reference interface: parity = Even, baudRate = CommParameter[1]). An
+    // earlier 10400 8N1 override here came from an ISO 9141 experiment and
+    // does not belong on these concepts. DTR idles LOW: held high it keeps
+    // the cable transmitting and the answer is lost (real E46, MS45).
+    return {
+      baudRate: (comm && comm.baud) || KLINE_DEFAULT_BAUD,
+      dataBits: 8,
+      stopBits: 1,
+      parity: 'even',
+      dtr: false,
+    };
+  }
+  // BMW-FAST / D-CAN: 115200 8N1 with DTR held HIGH for the session, the way
+  // the reference drives a plain cable (stateDtr = HasAdapterEcho). Dropping
+  // it after a K-line probe and leaving it there is the one thing this
+  // transport did differently from the reference on an E60/E65/E90 bus.
+  return { ...KDCAN, dtr: isBmwFast(c) };
+}

package/runtime/core/webshim/install.js

@@ -0,0 +1,30 @@
+/**
+ * @file The shim's composition root: lock the bus, publish the public
+ * surface on window, and install the fetch shim. Loads last, after every
+ * other core/webshim/ piece.
+ */
+
+/**
+ * Forget everything known about the car on the other end of the cable:
+ * the EDIABAS sessions (without ENDE -- the wire is already going away) and
+ * the resolved variants. Run before the bus disconnects.
+ */
+function forgetCar() {
+  forgetSessions();
+  forgetResolvedVariants();
+}
+
+lockBus(webBus, forgetCar);
+
+if (typeof window !== 'undefined') {
+  window.webBus = webBus;
+  window.installWebShim = installWebShim;
+  // group -> variant resolution, for the sweep screen: which SGBD answers
+  // at this diagnostic address? (lowercased SGBD name, or null)
+  window.webResolveVariant = webResolveVariant;
+  window.webResolveVariantLast = webResolveVariantLast;
+  // The explicitly-confirmed coding write path (the UI's "code this module"
+  // action). Gated on opts.confirmed and its own re-read proof; see coding.js.
+  window.webWriteCoding = webWriteCoding;
+  installWebShim();
+}

package/runtime/core/webshim/job-runner.js

@@ -0,0 +1,319 @@
+/**
+ * @file EDIABAS's session model and the job runner: run a job the way the
+ * server's /run endpoint did, but in the VM, over the live bus.
+ */
+/* exported sessionFor, switchSession, forgetSessions, newTally, driveJobOverBus, webRunJob */
+
+/**
+ * How many telegram exchanges a single job may need before it is declared
+ * stuck (one VM replay pass per exchange).
+ */
+const MAX_JOB_PASSES = 64;
+
+/**
+ * The VM's send callback: synchronous, returns a memoised answer or throws
+ * the needAnswer sentinel to unwind the pass.
+ * @callback SendFn
+ * @param {ArrayLike<number>} out - The request without its checksum.
+ * @param {CommParams} comm - Its wire parameters.
+ * @returns {number[]} The answer bytes.
+ */
+
+/**
+ * One SGBD's session state.
+ * @typedef {object} Session
+ * @property {Map<string, any>} shared - shmset data carried across jobs.
+ * @property {boolean} inited - Has INITIALISIERUNG run.
+ * @property {CommParams|null} comm - The wire parameters xsetpar left behind.
+ */
+
+/**
+ * What a VM job produced once every telegram it needed had been exchanged.
+ * @typedef {object} DriveResult
+ * @property {object[]} sets - The result sets.
+ * @property {Best2Vm} vm - The VM instance that completed the job.
+ */
+
+/**
+ * How the wire answered a job's telegrams, kept OUTSIDE the drive so the
+ * counts survive a pass that throws (the resolver reports them beside the
+ * error).
+ * @typedef {object} AnswerTally
+ * @property {number} empty - Telegrams the wire could not answer.
+ * @property {number} real - Telegrams that came back with bytes.
+ */
+
+/**
+ * A fresh, zeroed answer tally.
+ * @returns {AnswerTally}
+ */
+function newTally() {
+  return { empty: 0, real: 0 };
+}
+
+/**
+ * EDIABAS's session model, which a fresh-VM-per-job does not have:
+ * INITIALISIERUNG runs ONCE when an SGBD is loaded, shared data (shmset)
+ * persists across that SGBD's jobs, and ENDE runs when it is unloaded.
+ * MS450 hands its AIF block from init to later jobs exactly this way.
+ * The session also carries COMM: xsetpar lives in INITIALISIERUNG, so a
+ * later job's fresh VM never executes it -- without the carry, every
+ * ordinary job transmitted with default BMW-FAST framing and every K-line
+ * module got 115200 8N1 line noise.
+ * Keyed by SGBD; switching ECUs ends the previous session.
+ * @type {Map<string, Session>}
+ */
+const sessions = new Map();
+
+/**
+ * The session for an SGBD, created empty on first sight.
+ * @param {string} sgbd - The SGBD name (any case).
+ * @returns {Session}
+ */
+function sessionFor(sgbd) {
+  const key = String(sgbd).toLowerCase();
+  let s = sessions.get(key);
+  if (!s) {
+    s = { shared: new Map(), inited: false, comm: null };
+    sessions.set(key, s);
+  }
+  return s;
+}
+
+/**
+ * Run ENDE for a session being dropped. Fire-and-forget: the answer does
+ * not matter, but the ECU is entitled to the notification.
+ * @param {string} sgbd - The SGBD whose session ends.
+ */
+async function endSession(sgbd) {
+  const key = String(sgbd).toLowerCase();
+  const s = sessions.get(key);
+  if (!s || !s.inited) {
+    sessions.delete(key);
+    return;
+  }
+  sessions.delete(key);
+  try {
+    const code = await webFetchJson(`data/job-code/${key}.json`);
+    if (code && code.jobs && code.jobs.ENDE !== undefined) {
+      await webRunJob(sgbd, 'ENDE', null, {
+        noInit: true,
+        shared: s.shared,
+        comm: s.comm,
+      });
+    }
+  } catch {
+    /* the session is over either way */
+  }
+}
+
+/**
+ * The currently-loaded SGBD (lowercased). EDIABAS holds one at a time;
+ * switching ends the old session so its ENDE runs while the bus is still up.
+ * @type {string|null}
+ */
+let loadedSgbd = null;
+
+/**
+ * Make `sgbd` the loaded SGBD, ending the previous one's session first.
+ *
+ * NOTE this must NOT run between an SGBD's session init and its jobs: those
+ * are the same session. Clearing there let the job's BMW-FAST concept
+ * become the session concept, the port reopened at 115200, and the wake
+ * performed at 10400 was undone before the telegram went out.
+ * @param {string} sgbd - The SGBD about to run.
+ */
+async function switchSession(sgbd) {
+  const key = String(sgbd).toLowerCase();
+  if (loadedSgbd === key) return;
+  const prev = loadedSgbd;
+  loadedSgbd = key;
+  // Only a REAL switch clears the wire state. The early return above already
+  // skipped the no-op case, so reaching here means a different ECU -- which
+  // may live on a different wire, so the remembered concept and the wake
+  // that went with it do not carry over.
+  if (prev) {
+    await endSession(prev);
+    webBus.sessionConcept = null;
+    webBus.inited = null;
+  }
+}
+
+/**
+ * Forget every session and the loaded SGBD, without running ENDE. Called
+ * when the cable goes away: the wire is already gone.
+ */
+function forgetSessions() {
+  sessions.clear();
+  loadedSgbd = null;
+}
+
+/**
+ * The sentinel a send() throws to unwind a VM pass whose answer is not yet
+ * known. bestvm's INITIALISIERUNG handling rethrows it instead of swallowing
+ * it -- an init whose telegrams were never fetched used to "succeed" having
+ * sent nothing.
+ * @returns {Error & {needAnswer: true}}
+ */
+function needAnswerError() {
+  const need = new Error('__need_answer__');
+  need.needAnswer = true;
+  return need;
+}
+
+/**
+ * Did this wire error mean the telegram got nothing usable -- silence or a
+ * bad echo -- as opposed to a lying wire?
+ *
+ * A SILENT ECU IS AN ANSWER OF ZERO BYTES, NOT A DEAD JOB. The VM sets
+ * f.zero from the answer's length and the bytecode branches on it. Tracing
+ * EDIABAS proved the SGBD relies on exactly that: ms450ds0's INITIALISIERUNG
+ * holds two telegrams as constants, sends "82 12 F1 1A 80", gets IFH-0009 --
+ * and carries on to send "B8 12 F1 02 1A 80", which the ECU answers. Throwing
+ * here killed the job on the first telegram, so the second was never tried
+ * and a perfectly reachable DME looked silent.
+ *
+ * IFH-0009 (silence) and IFH-0003 (the echo did not come back cleanly) both
+ * mean THIS TELEGRAM GOT NOTHING USABLE. The SGBD's fallback branches on the
+ * answer's length via `slen`, so both must arrive as an empty answer or the
+ * bytecode never reaches its second telegram. A half-duplex K line genuinely
+ * produces both: an ECU that ignores a framing answers with silence, and the
+ * stray leftover byte that follows makes the NEXT echo compare fail.
+ * Treating only the timeout as "no answer" left the app dying on whichever
+ * of the two happened to occur first.
+ *
+ * Only those two are swallowed. A damaged frame, a checksum failure or a
+ * bus-level fault still throws: those mean the wire is lying, and continuing
+ * would decode garbage.
+ * @param {any} err - What webBus.exchange threw.
+ * @returns {boolean} True for IFH-0009 / IFH-0003.
+ */
+function isNoUsableAnswer(err) {
+  return !!(err && (err.ifh === 'IFH-0009' || err.ifh === 'IFH-0003'));
+}
+
+/**
+ * Drive one VM job over the bus in passes.
+ *
+ * send() is synchronous but the wire is async, so the VM runs in passes:
+ * each pass runs until a send whose answer we lack, which we fetch, memoise,
+ * then retry from the top (the VM is deterministic, so replay is safe). The
+ * memo is keyed by request bytes AND occurrence index: a job that sends the
+ * same telegram twice (clear-then-verify) must get the second answer, not a
+ * replay. One clock serves all passes -- a time that ticked between passes
+ * would change the request bytes, miss the memo, and re-transmit an
+ * already-sent telegram.
+ *
+ * REMEMBER THAT THE WIRE FAILED. The empty answer is what the SGBD's
+ * fallback needs, but a job whose telegrams ALL came back empty has not read
+ * the car -- it has read nothing. The tally lets the caller say so: without
+ * it the fault screen rendered "No stored faults / clean fault memory" for a
+ * DME holding nine real faults, which is the worst thing a diagnostic tool
+ * can say.
+ * @param {(send: SendFn, now: Date) => Best2Vm} buildVm - Builds a fresh VM
+ *   for one pass around the given send callback and clock.
+ * @param {string} job - The job name.
+ * @param {string} arg - The job's argument string.
+ * @param {AnswerTally} tally - Updated in place as telegrams are answered.
+ * @returns {Promise<DriveResult>} The result sets and the finished VM.
+ * @throws {Error} A VM error from the job itself, a wire error that is not
+ *   silence, or 'did not settle' after MAX_JOB_PASSES exchanges.
+ */
+async function driveJobOverBus(buildVm, job, arg, tally) {
+  const answers = new Map();
+  const jobNow = new Date();
+  for (let attempt = 0; attempt < MAX_JOB_PASSES; attempt++) {
+    let missing = null;
+    let sendSeq = 0;
+    const send = (out, comm) => {
+      const key = `${sendSeq++}:${Array.from(out)}`;
+      if (answers.has(key)) return answers.get(key);
+      // Carry the wire parameters along with the request: the exchange
+      // below needs the concept to frame, checksum and pace it. Unwind this
+      // pass: nothing sensible to return, and continuing would decode
+      // garbage.
+      missing = { key, out: Array.from(out), comm };
+      throw needAnswerError();
+    };
+    const vm = buildVm(send, jobNow);
+    try {
+      const sets = vm.run(job, arg);
+      return { sets, vm };
+    } catch (e) {
+      // Only the needAnswer sentinel may turn into a wire exchange. A real
+      // VM error thrown in the same pass must surface as itself, not be
+      // recycled into "did not settle".
+      if (!missing || !e.needAnswer) throw e;
+      let answer;
+      try {
+        answer = await webBus.exchange(missing.out, missing.comm);
+      } catch (err) {
+        if (!isNoUsableAnswer(err)) throw err;
+        answer = [];
+        tally.empty++;
+      }
+      if (answer && answer.length) tally.real++;
+      answers.set(missing.key, answer);
+    }
+  }
+  throw new Error(
+    `job did not settle after ${MAX_JOB_PASSES} telegram exchanges`
+  );
+}
+
+/**
+ * Run a job on an SGBD over the live bus, inside its EDIABAS session.
+ * @param {string} sgbd - The SGBD name.
+ * @param {string} job - The job name.
+ * @param {string|null} arg - The argument string (null for none).
+ * @param {{shared?: Map<string, any>, comm?: CommParams|null, noInit?: boolean}} [opts] -
+ *   A detached session to run in (endSession's ENDE uses this).
+ * @returns {Promise<{sets: object[]}>} The job's result sets.
+ * @throws {Error} When no job code is shipped, when the ECU answered nothing
+ *   at all (IFH-0009), or whatever the job or wire threw.
+ */
+async function webRunJob(sgbd, job, arg, opts = {}) {
+  const code = await webFetchJson(`data/job-code/${sgbd.toLowerCase()}.json`);
+  if (!code) throw new Error(`no job code shipped for ${sgbd}`);
+  const sharedTables = await loadSharedTables();
+  const tables =
+    (await webFetchJson(`data/sgbd-tables/${sgbd.toLowerCase()}.json`)) || {};
+  const session = opts.shared
+    ? { shared: opts.shared, inited: true, comm: opts.comm || null }
+    : sessionFor(sgbd);
+  const argText = arg == null ? '' : String(arg);
+  const tally = newTally();
+
+  const { sets, vm } = await driveJobOverBus(
+    (send, now) =>
+      new Best2Vm(code, {
+        tables,
+        extTables: sharedTables,
+        args: argText,
+        // Writes permitted -- see the note on Best2Vm.allowWrites. This is
+        // the main job runner, so it is what lets an actuator test reach the
+        // wire.
+        allowWrites: true,
+        shared: session.shared,
+        inited: session.inited,
+        comm: session.comm,
+        now,
+        send,
+      }),
+    job,
+    argText,
+    tally
+  );
+  session.inited = true;
+  session.comm = vm.comm || session.comm;
+  // A job that transmitted and was answered by NOTHING did not read the
+  // car. Saying so is the only honest outcome: the alternative is a
+  // "clean fault memory" that is really a dead wire.
+  if (tally.empty && !tally.real) {
+    throw ifhError(
+      'IFH-0009',
+      'the ECU did not answer any telegram in this job'
+    );
+  }
+  return { sets };
+}