@aria-framework/ai 0.26.0 → 0.26.1

package/lmxVerify.js

@@ -1,402 +1,402 @@
-/**
- * Does this supervisor actually work? — the four questions, asked in the only order they can be.
- *
- * WHY THIS EXISTS. A supervisor was saved correctly twice and looked identical both times, while the
- * engines key sat in the status token's field. The listener answered 401, and the only place that
- * surfaced was an HTTP code behind a button — a number that names neither credential. Saving
- * something and finding out later whether it works is the shape of that whole failure.
- *
- * THE ORDER IS FORCED, and each step's failure means something the next cannot tell you:
- *
- *   1. reachable      — nothing below it means anything if the machine does not answer
- *   2. certificate    — fails BEFORE any credential leaves this process, which is why its message
- *                       says so: a pin mismatch is the whole story, and the tokens are not suspect
- *   3. status token   — FREE. Reading the document is exactly what this credential authorises, so
- *                       whether it works is learned as a side effect of asking
- *   4. engines key    — authorises INFERENCE, and no amount of status reading exercises it
- *
- * CHECK 4 SPENDS NOTHING. The obvious way to test an inference credential is to run an inference;
- * asking the engine's own `/models` instead authenticates against the same route with the same
- * bearer and costs no tokens at all. An operator should never have to weigh "is my key right?"
- * against what the answer costs.
- *
- * NOTHING HERE READS A DATABASE OR A KEYSTORE. Every credential arrives as an argument, which is
- * what lets the same function serve an admin screen, a boot check and a test with a stub fetch.
- * Where the values come from is the consuming app's business.
- *
- * WHAT IS NEVER DONE: a check is never reported as passed because it probably would have. When the
- * engine list does not arrive, the engines key reads `not checked` rather than a tick — it is the
- * credential whose failure stays invisible until a job runs, so a tick meaning "probably" is worse
- * there than no tick at all.
- */
-
-'use strict';
-
-const crypto = require('crypto');
-
-const DEFAULT_TIMEOUT_MS = 6000;
-
-/** How long a verification stays on the page before it is stale enough to be misleading. */
-const REPORT_TTL_MS = 10 * 60 * 1000;
-
-/** Certificates inside this window are called out — an expired pin takes the stack out silently. */
-const EXPIRY_WARN_DAYS = 30;
-
-/**
- * The last verification per instance, so the report survives the redirect that follows a save.
- *
- * NOT A FLASH. The flash partial escapes to a single line, and a per-check report is exactly the
- * kind of result the partial's own notes warn about losing — "the only place that output appears,
- * and a message that erases itself after three seconds would lose it with no way back". Keeping it
- * here means it stays readable until something supersedes it, which is also what makes it useful
- * outside the moment of saving.
- */
-const _reports = new Map();
-
-function remember(instance, report) {
-  _reports.set(String(instance), report);
-  return report;
-}
-
-/** The last report for an instance, or null once it is old enough to mislead. */
-function lastFor(instance) {
-  const r = _reports.get(String(instance));
-  if (!r) return null;
-  if (Date.now() - new Date(r.at).getTime() > REPORT_TTL_MS) {
-    _reports.delete(String(instance));
-    return null;
-  }
-  return r;
-}
-
-function forget(instance) { _reports.delete(String(instance)); }
-
-/** Only for tests — the cache is process-wide and would otherwise leak between them. */
-function _reset() { _reports.clear(); }
-
-// ── classifying what went wrong ────────────────────────────────────────────────────────────────
-//
-// fetch() reports every transport failure as the same "fetch failed", with the real reason on
-// `cause`. Collapsing those into one message would put a certificate mismatch and an unplugged
-// network cable behind identical words, which is the confusion this whole module exists to end.
-
-const TLS_CODES = new Set([
-  'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'SELF_SIGNED_CERT_IN_CHAIN', 'DEPTH_ZERO_SELF_SIGNED_CERT',
-  'CERT_HAS_EXPIRED', 'CERT_NOT_YET_VALID', 'ERR_TLS_CERT_ALTNAME_INVALID',
-  'CERT_SIGNATURE_FAILURE', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'ERR_SSL_WRONG_VERSION_NUMBER'
-]);
-
-function causeOf(err) {
-  let e = err;
-  for (let i = 0; i < 5 && e && e.cause; i += 1) e = e.cause;
-  return e || err;
-}
-
-function classify(err) {
-  const c = causeOf(err);
-  const code = (c && c.code) || '';
-  if (err && err.name === 'TimeoutError') return { kind: 'unreachable', code: 'ETIMEDOUT' };
-  if (TLS_CODES.has(code)) return { kind: 'tls', code };
-  if (/certificate|self.signed|SSL/i.test(String(c && c.message))) return { kind: 'tls', code: code || 'TLS' };
-  return { kind: 'unreachable', code: code || 'unknown' };
-}
-
-// ── the pinned certificate, read locally ───────────────────────────────────────────────────────
-
-/**
- * What we are pinning, without asking anybody. The fingerprint and expiry are properties of the PEM
- * in front of us, so they are known even when the stack is off — which is when an operator most
- * needs to be told the pin expires in a fortnight.
- */
-function readPin(pem) {
-  if (!pem || !String(pem).trim()) return { present: false };
-  try {
-    const x = new crypto.X509Certificate(String(pem));
-    const expires = new Date(x.validTo);
-    const days = Math.floor((expires.getTime() - Date.now()) / 86400000);
-    return {
-      present: true,
-      valid: true,
-      // Short form, because the whole digest is unreadable and nobody compares 32 bytes by eye.
-      fingerprint: shortPrint(x.fingerprint256),
-      expires,
-      expiresDays: days,
-      expired: days < 0,
-      expiringSoon: days >= 0 && days <= EXPIRY_WARN_DAYS
-    };
-  } catch (e) {
-    return { present: true, valid: false, error: e.message };
-  }
-}
-
-function shortPrint(fp) {
-  const parts = String(fp || '').split(':');
-  if (parts.length < 4) return String(fp || '');
-  return `${parts.slice(0, 2).join(':')}…${parts[parts.length - 1]}`;
-}
-
-function fmtDate(d) {
-  return d instanceof Date && !isNaN(d) ? d.toISOString().slice(0, 10) : 'unknown';
-}
-
-// ── the checks ─────────────────────────────────────────────────────────────────────────────────
-
-const pass = (key, text) => ({ key, status: 'pass', text });
-const fail = (key, text) => ({ key, status: 'fail', text });
-const skip = (key, text) => ({ key, status: 'skip', text });
-
-/**
- * Run the four (occasionally five) checks against a supervisor.
- *
- * @param {object} o
- *   instance     the id this stack must report as itself
- *   statusUrl    the status listener
- *   statusToken  bearer for the status document
- *   caCert       the certificate to pin, PEM
- *   enginesKey   bearer for inference — checked only when there is an engine to check it against
- *   engineName   an adopted engine to authenticate against; omitted, the first healthy one is used
- *   engineId     its stable id, when the row has one — matched instead of the name (renames)
- *   fetchImpl    test seam; the pinned transport is used when absent
- */
-async function verify(o = {}) {
-  const instance = String(o.instance || '');
-  const statusUrl = String(o.statusUrl || '');
-  const timeoutMs = Number(o.timeoutMs) || DEFAULT_TIMEOUT_MS;
-  const checks = [];
-  const at = new Date().toISOString();
-
-  const pin = readPin(o.caCert);
-  const host = hostOf(statusUrl);
-
-  // ── 1 + 2 + 3: one request answers all three, because they fail at different layers of it ──
-  let doc = null;
-  let found = null;   // the engine list, when the document arrived
-  try {
-    const started = Date.now();
-    const res = await statusFetch(o, statusUrl, timeoutMs);
-    const ms = Date.now() - started;
-
-    checks.push(pass('reachable', `reached ${host} in ${ms} ms`));
-    checks.push(certCheck(pin, true));
-
-    if (res.status === 401 || res.status === 403) {
-      checks.push(fail('status_token',
-        `status token rejected — the listener answered ${res.status}`));
-      checks.push(skip('engines_key', 'engines key not checked — needs the engine list'));
-      return finish(instance, at, checks, null, found);
-    }
-    if (!res.ok) {
-      checks.push(fail('status_token', `the listener answered ${res.status}`));
-      checks.push(skip('engines_key', 'engines key not checked — needs the engine list'));
-      return finish(instance, at, checks, null, found);
-    }
-
-    try {
-      doc = await res.json();
-    } catch (e) {
-      checks.push(fail('status_token', 'the listener answered, but not with a status document'));
-      checks.push(skip('engines_key', 'engines key not checked — needs the engine list'));
-      return finish(instance, at, checks, null, found);
-    }
-
-    const engines = Array.isArray(doc && doc.engines) ? doc.engines : [];
-    checks.push(pass('status_token',
-      `status token accepted · ${engines.length} engine${engines.length === 1 ? '' : 's'} reported`));
-
-    // THE DOCUMENT COMES BACK WITH THE VERDICT. Verifying already costs a status read, and that read
-    // is the same one the engine picker used to make on demand — so carrying the list here lets the
-    // panel render its engines from what we just fetched instead of asking again from the browser.
-    // It is also what removes the "Discover engines" button: a list you have to press for is a list
-    // that is stale by definition, and pressing it was where the 401 used to hide.
-    found = engines;
-
-    // IDENTITY, not connectivity. Engine names collide across deployments — `analysis` exists on
-    // every stack — so a status URL pointed at the wrong machine answers plausibly and sends work
-    // somewhere else. Only raised when it is actually wrong; a matching id needs no line.
-    if (doc && doc.instance && String(doc.instance) !== instance) {
-      checks.push(fail('instance',
-        `this stack reports itself as “${doc.instance}”, not “${instance}” — the address points at a different deployment`));
-      // AND ITS ENGINES ARE NOT HANDED BACK (0.25.0). The apps' scheduled refresh feeds
-      // report.engines to rekeyPlan; returning another deployment's list wrote THAT stack's engine
-      // ids onto this stack's rows — irreversibly, since a row with an id is never re-pointed.
-      // `null` is "no document for this stack", which every consumer treats as "write nothing".
-      found = null;
-    }
-
-    checks.push(await enginesKeyCheck(o, engines, timeoutMs));
-    return finish(instance, at, checks, null, found);
-  } catch (err) {
-    const { kind, code } = classify(err);
-    if (kind === 'tls') {
-      // NOTHING WAS SENT. The handshake failed, so neither credential left this process — worth
-      // saying, because it means the tokens are not what to go and look at.
-      checks.push(pass('reachable', `reached ${host}`));
-      checks.push(fail('certificate', certFailText(pin, code)));
-      checks.push(skip('status_token', 'status token not sent — the connection was refused first'));
-      checks.push(skip('engines_key', 'engines key not sent'));
-      return finish(instance, at, checks, null, found);
-    }
-    checks.push(fail('reachable', `no answer from ${host} (${code})`));
-    checks.push(skip('certificate', 'certificate not checked'));
-    checks.push(skip('status_token', 'status token not checked'));
-    checks.push(skip('engines_key', 'engines key not checked'));
-    return finish(instance, at, checks, pin, found);
-  }
-}
-
-function hostOf(url) {
-  try { const u = new URL(url); return u.host; } catch (e) { return url || 'the listener'; }
-}
-
-/** The status read, over the pinned transport unless a test supplies its own fetch. */
-async function statusFetch(o, statusUrl, timeoutMs) {
-  const headers = { Accept: 'application/json' };
-  if (o.statusToken) headers.Authorization = `Bearer ${o.statusToken}`;
-  return send(o, statusUrl, headers, timeoutMs);
-}
-
-/**
- * One request, over the pinned transport.
- *
- * THE DISPATCHER IS HALF THE TRANSPORT. `lmxTransport(ca)` returns `{ fetch, dispatcher }` and the
- * certificate lives on the DISPATCHER — taking only `.fetch` and calling it leaves the pin behind,
- * and the request goes out against the system trust store instead. Against a self-signed stack that
- * surfaces as DEPTH_ZERO_SELF_SIGNED_CERT, which reads exactly like a genuine certificate mismatch:
- * a verifier that reported "the certificate did not match" for a perfectly good certificate, which
- * is a worse failure than the one it was written to catch.
- */
-async function send(o, url, headers, timeoutMs) {
-  const opts = { headers, signal: AbortSignal.timeout(timeoutMs) };
-  if (o.fetchImpl) return o.fetchImpl(url, opts);
-  const { lmxTransport } = require('./providers/lmxTransport');
-  const t = lmxTransport(o.caCert || null);
-  if (t.dispatcher) opts.dispatcher = t.dispatcher;
-  return t.fetch(url, opts);
-}
-
-function certCheck(pin, handshakeOk) {
-  if (!pin.present) {
-    // Not a failure: a stack on loopback, or one behind a certificate the system already trusts,
-    // needs no pin. Saying "none pinned" is the true statement; a tick would claim a check ran.
-    return skip('certificate', 'no certificate pinned — the system trust store was used');
-  }
-  if (!pin.valid) return fail('certificate', `the pinned certificate could not be read (${pin.error})`);
-  if (pin.expired) {
-    return fail('certificate',
-      `the pinned certificate EXPIRED on ${fmtDate(pin.expires)} — every call fails at the handshake`);
-  }
-  const base = `certificate matched the pin · ${pin.fingerprint} · expires ${fmtDate(pin.expires)}`;
-  if (pin.expiringSoon) {
-    return { key: 'certificate', status: 'warn', text: `${base} — ${pin.expiresDays} days left` };
-  }
-  return handshakeOk ? pass('certificate', base) : skip('certificate', base);
-}
-
-function certFailText(pin, code) {
-  if (pin.present && pin.expired) {
-    return `the pinned certificate expired on ${fmtDate(pin.expires)} (${code})`;
-  }
-  if (code === 'CERT_HAS_EXPIRED') return 'the stack is presenting an expired certificate';
-  if (code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
-    return 'the certificate is not valid for this address — check the hostname';
-  }
-  if (!pin.present) {
-    return 'the stack presented a certificate this machine does not trust, and none is pinned here';
-  }
-  return `the stack presented a different certificate from the one pinned here (${code})`;
-}
-
-/**
- * Check 4 — WITHOUT SPENDING ANYTHING.
- *
- * The engines key is a bearer on the engine's own OpenAI-compatible API, so asking that API to list
- * its models authenticates against exactly the route inference uses. A completion would prove the
- * same thing and bill for the privilege.
- */
-async function enginesKeyCheck(o, engines, timeoutMs) {
-  if (!o.enginesKey) {
-    return skip('engines_key', 'no engines key set — engines are being called unauthenticated');
-  }
-  const { findEngine } = require('./providers/lmxDiscovery');
-  const wanted = (o.engineId || o.engineName)
-    ? findEngine(engines, { id: o.engineId || null, name: o.engineName })
-    : engines.find((e) => e && e.state === 'healthy' && e.url);
-  if (!wanted || !wanted.url) {
-    return skip('engines_key',
-      o.engineName
-        ? `engines key not checked — “${o.engineName}” is not currently healthy`
-        : 'engines key not checked — no healthy engine to authenticate against');
-  }
-  try {
-    const url = `${String(wanted.url).replace(/\/+$/, '')}/models`;
-    const res = await send(o, url,
-      { Accept: 'application/json', Authorization: `Bearer ${o.enginesKey}` }, timeoutMs);
-    if (res.status === 401 || res.status === 403) {
-      return fail('engines_key',
-        `engines key rejected by ${wanted.name} — inference calls will fail with ${res.status}`);
-    }
-    if (!res.ok) {
-      return skip('engines_key', `engines key not confirmed — ${wanted.name} answered ${res.status}`);
-    }
-    return pass('engines_key', `engines key accepted · checked against ${wanted.name}`);
-  } catch (err) {
-    const { code } = classify(err);
-    return skip('engines_key', `engines key not checked — ${wanted.name} did not answer (${code})`);
-  }
-}
-
-// ── the verdict ────────────────────────────────────────────────────────────────────────────────
-
-function finish(instance, at, checks, pinForOffline, engines) {
-  // A certificate that expires soon is worth saying even when nothing could be reached, because it
-  // is knowable from the PEM alone and is exactly the failure nobody sees coming.
-  if (pinForOffline && pinForOffline.present && pinForOffline.valid
-      && (pinForOffline.expired || pinForOffline.expiringSoon)) {
-    const i = checks.findIndex((c) => c.key === 'certificate');
-    if (i > -1) checks[i] = certCheck(pinForOffline, false);
-  }
-
-  const failed = checks.filter((c) => c.status === 'fail');
-  const warned = checks.filter((c) => c.status === 'warn');
-  const ok = failed.length === 0;
-
-  return {
-    ok,
-    level: failed.length ? (failed.some((c) => c.key === 'certificate') ? 'bad' : 'warn')
-      : (warned.length ? 'warn' : 'ok'),
-    headline: headlineFor(failed, warned),
-    at,
-    instance,
-    checks,
-    // Null means "we never got a document", which is NOT the same as a stack with no engines — the
-    // panel must be able to say "not checked" rather than "no engines", because those send an
-    // operator to entirely different places.
-    engines: engines || null
-  };
-}
-
-/**
- * ONE SENTENCE NAMING THE CAUSE, for the flash. "Saved, but the status token is being rejected"
- * is a different instruction from "saved, but the stack did not answer" — the first sends somebody
- * to a credential, the second to a machine, and "401" sent them to neither.
- */
-function headlineFor(failed, warned) {
-  if (!failed.length) {
-    return warned.length ? warned[0].text : 'connected, certificate pinned, both credentials accepted';
-  }
-  const first = failed[0];
-  switch (first.key) {
-    case 'reachable': return 'the stack did not answer — its settings are stored and will be used when it is back';
-    case 'certificate': return 'the certificate did not match — nothing was sent';
-    case 'status_token': return 'the status token is being rejected — engines cannot be listed until it is corrected';
-    case 'instance': return 'this address points at a different deployment';
-    case 'engines_key': return 'the engines key is being rejected — inference calls will fail';
-    default: return first.text;
-  }
-}
-
-module.exports = {
-  verify, remember, lastFor, forget, readPin,
-  DEFAULT_TIMEOUT_MS, EXPIRY_WARN_DAYS, REPORT_TTL_MS,
-  _reset, _classify: classify, _shortPrint: shortPrint
-};
+/**
+ * Does this supervisor actually work? — the four questions, asked in the only order they can be.
+ *
+ * WHY THIS EXISTS. A supervisor was saved correctly twice and looked identical both times, while the
+ * engines key sat in the status token's field. The listener answered 401, and the only place that
+ * surfaced was an HTTP code behind a button — a number that names neither credential. Saving
+ * something and finding out later whether it works is the shape of that whole failure.
+ *
+ * THE ORDER IS FORCED, and each step's failure means something the next cannot tell you:
+ *
+ *   1. reachable      — nothing below it means anything if the machine does not answer
+ *   2. certificate    — fails BEFORE any credential leaves this process, which is why its message
+ *                       says so: a pin mismatch is the whole story, and the tokens are not suspect
+ *   3. status token   — FREE. Reading the document is exactly what this credential authorises, so
+ *                       whether it works is learned as a side effect of asking
+ *   4. engines key    — authorises INFERENCE, and no amount of status reading exercises it
+ *
+ * CHECK 4 SPENDS NOTHING. The obvious way to test an inference credential is to run an inference;
+ * asking the engine's own `/models` instead authenticates against the same route with the same
+ * bearer and costs no tokens at all. An operator should never have to weigh "is my key right?"
+ * against what the answer costs.
+ *
+ * NOTHING HERE READS A DATABASE OR A KEYSTORE. Every credential arrives as an argument, which is
+ * what lets the same function serve an admin screen, a boot check and a test with a stub fetch.
+ * Where the values come from is the consuming app's business.
+ *
+ * WHAT IS NEVER DONE: a check is never reported as passed because it probably would have. When the
+ * engine list does not arrive, the engines key reads `not checked` rather than a tick — it is the
+ * credential whose failure stays invisible until a job runs, so a tick meaning "probably" is worse
+ * there than no tick at all.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+const DEFAULT_TIMEOUT_MS = 6000;
+
+/** How long a verification stays on the page before it is stale enough to be misleading. */
+const REPORT_TTL_MS = 10 * 60 * 1000;
+
+/** Certificates inside this window are called out — an expired pin takes the stack out silently. */
+const EXPIRY_WARN_DAYS = 30;
+
+/**
+ * The last verification per instance, so the report survives the redirect that follows a save.
+ *
+ * NOT A FLASH. The flash partial escapes to a single line, and a per-check report is exactly the
+ * kind of result the partial's own notes warn about losing — "the only place that output appears,
+ * and a message that erases itself after three seconds would lose it with no way back". Keeping it
+ * here means it stays readable until something supersedes it, which is also what makes it useful
+ * outside the moment of saving.
+ */
+const _reports = new Map();
+
+function remember(instance, report) {
+  _reports.set(String(instance), report);
+  return report;
+}
+
+/** The last report for an instance, or null once it is old enough to mislead. */
+function lastFor(instance) {
+  const r = _reports.get(String(instance));
+  if (!r) return null;
+  if (Date.now() - new Date(r.at).getTime() > REPORT_TTL_MS) {
+    _reports.delete(String(instance));
+    return null;
+  }
+  return r;
+}
+
+function forget(instance) { _reports.delete(String(instance)); }
+
+/** Only for tests — the cache is process-wide and would otherwise leak between them. */
+function _reset() { _reports.clear(); }
+
+// ── classifying what went wrong ────────────────────────────────────────────────────────────────
+//
+// fetch() reports every transport failure as the same "fetch failed", with the real reason on
+// `cause`. Collapsing those into one message would put a certificate mismatch and an unplugged
+// network cable behind identical words, which is the confusion this whole module exists to end.
+
+const TLS_CODES = new Set([
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'SELF_SIGNED_CERT_IN_CHAIN', 'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'CERT_HAS_EXPIRED', 'CERT_NOT_YET_VALID', 'ERR_TLS_CERT_ALTNAME_INVALID',
+  'CERT_SIGNATURE_FAILURE', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'ERR_SSL_WRONG_VERSION_NUMBER'
+]);
+
+function causeOf(err) {
+  let e = err;
+  for (let i = 0; i < 5 && e && e.cause; i += 1) e = e.cause;
+  return e || err;
+}
+
+function classify(err) {
+  const c = causeOf(err);
+  const code = (c && c.code) || '';
+  if (err && err.name === 'TimeoutError') return { kind: 'unreachable', code: 'ETIMEDOUT' };
+  if (TLS_CODES.has(code)) return { kind: 'tls', code };
+  if (/certificate|self.signed|SSL/i.test(String(c && c.message))) return { kind: 'tls', code: code || 'TLS' };
+  return { kind: 'unreachable', code: code || 'unknown' };
+}
+
+// ── the pinned certificate, read locally ───────────────────────────────────────────────────────
+
+/**
+ * What we are pinning, without asking anybody. The fingerprint and expiry are properties of the PEM
+ * in front of us, so they are known even when the stack is off — which is when an operator most
+ * needs to be told the pin expires in a fortnight.
+ */
+function readPin(pem) {
+  if (!pem || !String(pem).trim()) return { present: false };
+  try {
+    const x = new crypto.X509Certificate(String(pem));
+    const expires = new Date(x.validTo);
+    const days = Math.floor((expires.getTime() - Date.now()) / 86400000);
+    return {
+      present: true,
+      valid: true,
+      // Short form, because the whole digest is unreadable and nobody compares 32 bytes by eye.
+      fingerprint: shortPrint(x.fingerprint256),
+      expires,
+      expiresDays: days,
+      expired: days < 0,
+      expiringSoon: days >= 0 && days <= EXPIRY_WARN_DAYS
+    };
+  } catch (e) {
+    return { present: true, valid: false, error: e.message };
+  }
+}
+
+function shortPrint(fp) {
+  const parts = String(fp || '').split(':');
+  if (parts.length < 4) return String(fp || '');
+  return `${parts.slice(0, 2).join(':')}…${parts[parts.length - 1]}`;
+}
+
+function fmtDate(d) {
+  return d instanceof Date && !isNaN(d) ? d.toISOString().slice(0, 10) : 'unknown';
+}
+
+// ── the checks ─────────────────────────────────────────────────────────────────────────────────
+
+const pass = (key, text) => ({ key, status: 'pass', text });
+const fail = (key, text) => ({ key, status: 'fail', text });
+const skip = (key, text) => ({ key, status: 'skip', text });
+
+/**
+ * Run the four (occasionally five) checks against a supervisor.
+ *
+ * @param {object} o
+ *   instance     the id this stack must report as itself
+ *   statusUrl    the status listener
+ *   statusToken  bearer for the status document
+ *   caCert       the certificate to pin, PEM
+ *   enginesKey   bearer for inference — checked only when there is an engine to check it against
+ *   engineName   an adopted engine to authenticate against; omitted, the first healthy one is used
+ *   engineId     its stable id, when the row has one — matched instead of the name (renames)
+ *   fetchImpl    test seam; the pinned transport is used when absent
+ */
+async function verify(o = {}) {
+  const instance = String(o.instance || '');
+  const statusUrl = String(o.statusUrl || '');
+  const timeoutMs = Number(o.timeoutMs) || DEFAULT_TIMEOUT_MS;
+  const checks = [];
+  const at = new Date().toISOString();
+
+  const pin = readPin(o.caCert);
+  const host = hostOf(statusUrl);
+
+  // ── 1 + 2 + 3: one request answers all three, because they fail at different layers of it ──
+  let doc = null;
+  let found = null;   // the engine list, when the document arrived
+  try {
+    const started = Date.now();
+    const res = await statusFetch(o, statusUrl, timeoutMs);
+    const ms = Date.now() - started;
+
+    checks.push(pass('reachable', `reached ${host} in ${ms} ms`));
+    checks.push(certCheck(pin, true));
+
+    if (res.status === 401 || res.status === 403) {
+      checks.push(fail('status_token',
+        `status token rejected — the listener answered ${res.status}`));
+      checks.push(skip('engines_key', 'engines key not checked — needs the engine list'));
+      return finish(instance, at, checks, null, found);
+    }
+    if (!res.ok) {
+      checks.push(fail('status_token', `the listener answered ${res.status}`));
+      checks.push(skip('engines_key', 'engines key not checked — needs the engine list'));
+      return finish(instance, at, checks, null, found);
+    }
+
+    try {
+      doc = await res.json();
+    } catch (e) {
+      checks.push(fail('status_token', 'the listener answered, but not with a status document'));
+      checks.push(skip('engines_key', 'engines key not checked — needs the engine list'));
+      return finish(instance, at, checks, null, found);
+    }
+
+    const engines = Array.isArray(doc && doc.engines) ? doc.engines : [];
+    checks.push(pass('status_token',
+      `status token accepted · ${engines.length} engine${engines.length === 1 ? '' : 's'} reported`));
+
+    // THE DOCUMENT COMES BACK WITH THE VERDICT. Verifying already costs a status read, and that read
+    // is the same one the engine picker used to make on demand — so carrying the list here lets the
+    // panel render its engines from what we just fetched instead of asking again from the browser.
+    // It is also what removes the "Discover engines" button: a list you have to press for is a list
+    // that is stale by definition, and pressing it was where the 401 used to hide.
+    found = engines;
+
+    // IDENTITY, not connectivity. Engine names collide across deployments — `analysis` exists on
+    // every stack — so a status URL pointed at the wrong machine answers plausibly and sends work
+    // somewhere else. Only raised when it is actually wrong; a matching id needs no line.
+    if (doc && doc.instance && String(doc.instance) !== instance) {
+      checks.push(fail('instance',
+        `this stack reports itself as “${doc.instance}”, not “${instance}” — the address points at a different deployment`));
+      // AND ITS ENGINES ARE NOT HANDED BACK (0.25.0). The apps' scheduled refresh feeds
+      // report.engines to rekeyPlan; returning another deployment's list wrote THAT stack's engine
+      // ids onto this stack's rows — irreversibly, since a row with an id is never re-pointed.
+      // `null` is "no document for this stack", which every consumer treats as "write nothing".
+      found = null;
+    }
+
+    checks.push(await enginesKeyCheck(o, engines, timeoutMs));
+    return finish(instance, at, checks, null, found);
+  } catch (err) {
+    const { kind, code } = classify(err);
+    if (kind === 'tls') {
+      // NOTHING WAS SENT. The handshake failed, so neither credential left this process — worth
+      // saying, because it means the tokens are not what to go and look at.
+      checks.push(pass('reachable', `reached ${host}`));
+      checks.push(fail('certificate', certFailText(pin, code)));
+      checks.push(skip('status_token', 'status token not sent — the connection was refused first'));
+      checks.push(skip('engines_key', 'engines key not sent'));
+      return finish(instance, at, checks, null, found);
+    }
+    checks.push(fail('reachable', `no answer from ${host} (${code})`));
+    checks.push(skip('certificate', 'certificate not checked'));
+    checks.push(skip('status_token', 'status token not checked'));
+    checks.push(skip('engines_key', 'engines key not checked'));
+    return finish(instance, at, checks, pin, found);
+  }
+}
+
+function hostOf(url) {
+  try { const u = new URL(url); return u.host; } catch (e) { return url || 'the listener'; }
+}
+
+/** The status read, over the pinned transport unless a test supplies its own fetch. */
+async function statusFetch(o, statusUrl, timeoutMs) {
+  const headers = { Accept: 'application/json' };
+  if (o.statusToken) headers.Authorization = `Bearer ${o.statusToken}`;
+  return send(o, statusUrl, headers, timeoutMs);
+}
+
+/**
+ * One request, over the pinned transport.
+ *
+ * THE DISPATCHER IS HALF THE TRANSPORT. `lmxTransport(ca)` returns `{ fetch, dispatcher }` and the
+ * certificate lives on the DISPATCHER — taking only `.fetch` and calling it leaves the pin behind,
+ * and the request goes out against the system trust store instead. Against a self-signed stack that
+ * surfaces as DEPTH_ZERO_SELF_SIGNED_CERT, which reads exactly like a genuine certificate mismatch:
+ * a verifier that reported "the certificate did not match" for a perfectly good certificate, which
+ * is a worse failure than the one it was written to catch.
+ */
+async function send(o, url, headers, timeoutMs) {
+  const opts = { headers, signal: AbortSignal.timeout(timeoutMs) };
+  if (o.fetchImpl) return o.fetchImpl(url, opts);
+  const { lmxTransport } = require('./providers/lmxTransport');
+  const t = lmxTransport(o.caCert || null);
+  if (t.dispatcher) opts.dispatcher = t.dispatcher;
+  return t.fetch(url, opts);
+}
+
+function certCheck(pin, handshakeOk) {
+  if (!pin.present) {
+    // Not a failure: a stack on loopback, or one behind a certificate the system already trusts,
+    // needs no pin. Saying "none pinned" is the true statement; a tick would claim a check ran.
+    return skip('certificate', 'no certificate pinned — the system trust store was used');
+  }
+  if (!pin.valid) return fail('certificate', `the pinned certificate could not be read (${pin.error})`);
+  if (pin.expired) {
+    return fail('certificate',
+      `the pinned certificate EXPIRED on ${fmtDate(pin.expires)} — every call fails at the handshake`);
+  }
+  const base = `certificate matched the pin · ${pin.fingerprint} · expires ${fmtDate(pin.expires)}`;
+  if (pin.expiringSoon) {
+    return { key: 'certificate', status: 'warn', text: `${base} — ${pin.expiresDays} days left` };
+  }
+  return handshakeOk ? pass('certificate', base) : skip('certificate', base);
+}
+
+function certFailText(pin, code) {
+  if (pin.present && pin.expired) {
+    return `the pinned certificate expired on ${fmtDate(pin.expires)} (${code})`;
+  }
+  if (code === 'CERT_HAS_EXPIRED') return 'the stack is presenting an expired certificate';
+  if (code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
+    return 'the certificate is not valid for this address — check the hostname';
+  }
+  if (!pin.present) {
+    return 'the stack presented a certificate this machine does not trust, and none is pinned here';
+  }
+  return `the stack presented a different certificate from the one pinned here (${code})`;
+}
+
+/**
+ * Check 4 — WITHOUT SPENDING ANYTHING.
+ *
+ * The engines key is a bearer on the engine's own OpenAI-compatible API, so asking that API to list
+ * its models authenticates against exactly the route inference uses. A completion would prove the
+ * same thing and bill for the privilege.
+ */
+async function enginesKeyCheck(o, engines, timeoutMs) {
+  if (!o.enginesKey) {
+    return skip('engines_key', 'no engines key set — engines are being called unauthenticated');
+  }
+  const { findEngine } = require('./providers/lmxDiscovery');
+  const wanted = (o.engineId || o.engineName)
+    ? findEngine(engines, { id: o.engineId || null, name: o.engineName })
+    : engines.find((e) => e && e.state === 'healthy' && e.url);
+  if (!wanted || !wanted.url) {
+    return skip('engines_key',
+      o.engineName
+        ? `engines key not checked — “${o.engineName}” is not currently healthy`
+        : 'engines key not checked — no healthy engine to authenticate against');
+  }
+  try {
+    const url = `${String(wanted.url).replace(/\/+$/, '')}/models`;
+    const res = await send(o, url,
+      { Accept: 'application/json', Authorization: `Bearer ${o.enginesKey}` }, timeoutMs);
+    if (res.status === 401 || res.status === 403) {
+      return fail('engines_key',
+        `engines key rejected by ${wanted.name} — inference calls will fail with ${res.status}`);
+    }
+    if (!res.ok) {
+      return skip('engines_key', `engines key not confirmed — ${wanted.name} answered ${res.status}`);
+    }
+    return pass('engines_key', `engines key accepted · checked against ${wanted.name}`);
+  } catch (err) {
+    const { code } = classify(err);
+    return skip('engines_key', `engines key not checked — ${wanted.name} did not answer (${code})`);
+  }
+}
+
+// ── the verdict ────────────────────────────────────────────────────────────────────────────────
+
+function finish(instance, at, checks, pinForOffline, engines) {
+  // A certificate that expires soon is worth saying even when nothing could be reached, because it
+  // is knowable from the PEM alone and is exactly the failure nobody sees coming.
+  if (pinForOffline && pinForOffline.present && pinForOffline.valid
+      && (pinForOffline.expired || pinForOffline.expiringSoon)) {
+    const i = checks.findIndex((c) => c.key === 'certificate');
+    if (i > -1) checks[i] = certCheck(pinForOffline, false);
+  }
+
+  const failed = checks.filter((c) => c.status === 'fail');
+  const warned = checks.filter((c) => c.status === 'warn');
+  const ok = failed.length === 0;
+
+  return {
+    ok,
+    level: failed.length ? (failed.some((c) => c.key === 'certificate') ? 'bad' : 'warn')
+      : (warned.length ? 'warn' : 'ok'),
+    headline: headlineFor(failed, warned),
+    at,
+    instance,
+    checks,
+    // Null means "we never got a document", which is NOT the same as a stack with no engines — the
+    // panel must be able to say "not checked" rather than "no engines", because those send an
+    // operator to entirely different places.
+    engines: engines || null
+  };
+}
+
+/**
+ * ONE SENTENCE NAMING THE CAUSE, for the flash. "Saved, but the status token is being rejected"
+ * is a different instruction from "saved, but the stack did not answer" — the first sends somebody
+ * to a credential, the second to a machine, and "401" sent them to neither.
+ */
+function headlineFor(failed, warned) {
+  if (!failed.length) {
+    return warned.length ? warned[0].text : 'connected, certificate pinned, both credentials accepted';
+  }
+  const first = failed[0];
+  switch (first.key) {
+    case 'reachable': return 'the stack did not answer — its settings are stored and will be used when it is back';
+    case 'certificate': return 'the certificate did not match — nothing was sent';
+    case 'status_token': return 'the status token is being rejected — engines cannot be listed until it is corrected';
+    case 'instance': return 'this address points at a different deployment';
+    case 'engines_key': return 'the engines key is being rejected — inference calls will fail';
+    default: return first.text;
+  }
+}
+
+module.exports = {
+  verify, remember, lastFor, forget, readPin,
+  DEFAULT_TIMEOUT_MS, EXPIRY_WARN_DAYS, REPORT_TTL_MS,
+  _reset, _classify: classify, _shortPrint: shortPrint
+};