@nanobpm/nano-workforce 0.54.0 → 0.56.0

package/app/agentic/cockpit/supply-render.test.ts

@@ -0,0 +1,112 @@
+// Unit tests for the SUPPLY cockpit DOM renderer (H5 / #148), on the in-memory fake DOM.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { FakeDocument, FakeElement } from "../../../test/agentic-cockpit-doubles.ts";
+import { renderSupply } from "./supply-render.ts";
+import { type SupplyReport, supplyView } from "./supply-view.ts";
+
+const doc = new FakeDocument();
+
+const sample: SupplyReport = {
+  count: 2,
+  workers: [
+    { instance: "wk-a", identity: "leaf-1", stream: "wk-a", family: "senior", host: "h1", jobKeys: ["job-1"], live: true, staleMs: 0 },
+    { instance: "wk-b", identity: "leaf-1", stream: "wk-b", family: "junior", host: "h2", jobKeys: [], live: false, staleMs: 0 },
+  ],
+  leaves: [
+    {
+      token: "leaf-1",
+      workers: [
+        { instance: "wk-a", identity: "leaf-1", stream: "wk-a", family: "senior", host: "h1", jobKeys: ["job-1"], live: true, staleMs: 0 },
+        { instance: "wk-b", identity: "leaf-1", stream: "wk-b", family: "junior", host: "h2", jobKeys: [], live: false, staleMs: 0 },
+      ],
+    },
+  ],
+};
+
+test("renders one leaf section with a worker row per worker (family, host, jobs, liveness)", () => {
+  const host = new FakeElement("body");
+  renderSupply(host, doc, supplyView(sample));
+
+  assert.equal(host.byData("leaf", "leaf-1").length, 1);
+  const rows = host.byClass("cockpit-supply-worker");
+  assert.equal(rows.length, 2);
+
+  const rowA = host.byData("worker", "wk-a")[0];
+  assert.equal(rowA?.getAttribute("data-liveness"), "live");
+  assert.equal(rowA?.byClass("cockpit-supply-family")[0]?.text(), "senior");
+  assert.equal(rowA?.byClass("cockpit-supply-host")[0]?.text(), "h1");
+  assert.equal(rowA?.byClass("cockpit-supply-jobs")[0]?.text(), "job-1");
+
+  const rowB = host.byData("worker", "wk-b")[0];
+  assert.equal(rowB?.getAttribute("data-liveness"), "down");
+  assert.equal(rowB?.byClass("cockpit-supply-jobs")[0]?.text(), "—");
+});
+
+test("worker buttons carry the drill stream and fire onDrill on click", () => {
+  const host = new FakeElement("body");
+  const drilled: string[] = [];
+  renderSupply(host, doc, supplyView(sample), { onDrill: (stream) => drilled.push(stream) });
+
+  const button = host.byClass("cockpit-worker").find((b) => b.getAttribute("data-stream") === "wk-a");
+  assert.ok(button, "the worker button was rendered with its stream id");
+  button?.dispatch("click");
+  assert.deepEqual(drilled, ["wk-a"]);
+});
+
+test("does NOT render any demand matrix, missing-agent reds, or diversity light", () => {
+  const host = new FakeElement("body");
+  renderSupply(host, doc, supplyView(sample));
+  // Those widgets belong to the packaged demand renderer / enrolment epic #152 — never here.
+  assert.equal(host.byClass("cockpit-matrix").length, 0);
+  assert.equal(host.byClass("cockpit-network").length, 0);
+  assert.equal(host.byClass("cockpit-missing").length, 0);
+  assert.equal(
+    host.byClass("cockpit-light").filter((l) => l.getAttribute("data-light-id") === "diversity").length,
+    0,
+  );
+});
+
+test("renders an empty state when no workers are connected", () => {
+  const host = new FakeElement("body");
+  renderSupply(host, doc, supplyView({ count: 0, workers: [], leaves: [] }));
+  assert.equal(host.byData("empty", "true").length, 1);
+  assert.equal(host.byClass("cockpit-supply-worker").length, 0);
+});
+
+test("H6: renders a process/plan cell that drills into the job's stream", () => {
+  const host = new FakeElement("body");
+  const drilled: string[] = [];
+  const correlated: SupplyReport = {
+    count: 1,
+    workers: [{ instance: "wk-a", identity: "leaf-1", stream: "job:6494", family: "senior", host: "h1", jobKeys: ["6494"], live: true, staleMs: 0 }],
+    leaves: [
+      {
+        token: "leaf-1",
+        workers: [{ instance: "wk-a", identity: "leaf-1", stream: "job:6494", family: "senior", host: "h1", jobKeys: ["6494"], live: true, staleMs: 0 }],
+      },
+    ],
+    correlations: [{ jobKey: "6494", stream: "job:6494", bpmnProcessId: "plan-fanout", processInstanceKey: "4612", planKey: "o/r#142" }],
+  };
+  renderSupply(host, doc, supplyView(correlated), { onDrill: (stream) => drilled.push(stream) });
+
+  const cell = host.byData("worker", "wk-a")[0]?.byClass("cockpit-supply-process")[0];
+  assert.ok(cell);
+  assert.equal(cell?.getAttribute("data-correlations"), "1");
+  const link = host.byClass("cockpit-correlation")[0];
+  assert.ok(link, "the correlation drill button was rendered");
+  assert.equal(link?.getAttribute("data-job-key"), "6494");
+  assert.equal(link?.getAttribute("data-stream"), "job:6494");
+  assert.equal(link?.text(), "plan-fanout · inst 4612 · o/r#142");
+  link?.dispatch("click");
+  assert.deepEqual(drilled, ["job:6494"], "drilling the process/plan cell opens the live job's stream");
+});
+
+test("H6: a worker with no correlation renders an em-dash process cell", () => {
+  const host = new FakeElement("body");
+  renderSupply(host, doc, supplyView(sample));
+  const cell = host.byData("worker", "wk-b")[0]?.byClass("cockpit-supply-process")[0];
+  assert.equal(cell?.text(), "—");
+  assert.equal(cell?.getAttribute("data-correlations"), "0");
+});

package/app/agentic/cockpit/supply-render.ts

@@ -0,0 +1,165 @@
+// The SUPPLY-only cockpit DOM renderer (ADR 0056, H5 / #148).
+//
+// Renders a {@link SupplyView} into a host element: the live worker list grouped by leaf token, each
+// worker showing family, host, current jobs, and a liveness dot. Clicking a worker calls
+// {@link RenderOptions.onDrill} with that worker's relay stream id, which the boot layer turns into a
+// live terminal. This renders only the *volatile* part of the page (re-rendered each poll pass); the
+// drill-in terminal is owned by {@link ../supply-boot.ts} in a persistent region so it survives a
+// refresh.
+//
+// It draws a supply-only projection ON PURPOSE — NOT the packaged `renderCockpit`, which draws the
+// demand×supply matrix, the missing-agent-type reds, and the diversity-SLO light. Those are deferred
+// to enrolment epic #152 (see `./supply-view.ts`). The genuinely reusable, correctness-critical parts
+// of the cockpit — the relay client and the resume-from-offset terminal session — ARE reused from
+// `@nanobpm/agentic/cockpit` by the boot layer; only this supply projection, which the package does
+// not provide, is authored here.
+//
+// Like the packaged renderer it builds against the structural {@link ElementLike} / {@link DocumentLike}
+// subset (reused from `@nanobpm/agentic/cockpit`) rather than the global `document`, so the real DOM
+// satisfies it at runtime AND a plain in-memory fake satisfies it for DOM-free Node tests (no `as`).
+import type { DocumentLike, ElementLike } from "@nanobpm/agentic/cockpit";
+import type { Liveness, SupplyLeafView, SupplyView, SupplyWorkerView } from "./supply-view.ts";
+
+export interface RenderSupplyOptions {
+  /** Called with a worker's relay stream id when the operator drills into it. */
+  readonly onDrill?: (stream: string) => void;
+}
+
+/** Handles into the rendered tree the caller may need. */
+export interface SupplyDom {
+  /** The freshly built root the view was rendered into. */
+  readonly root: ElementLike;
+}
+
+function el(doc: DocumentLike, tag: string, className?: string, text?: string): ElementLike {
+  const node = doc.createElement(tag);
+  if (className !== undefined) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function dot(doc: DocumentLike, liveness: Liveness): ElementLike {
+  const node = el(doc, "span", "cockpit-dot");
+  node.setAttribute("data-liveness", liveness);
+  return node;
+}
+
+function workerRow(doc: DocumentLike, worker: SupplyWorkerView, options: RenderSupplyOptions): ElementLike {
+  const row = el(doc, "tr", "cockpit-supply-worker");
+  row.setAttribute("data-worker", worker.instance);
+  row.setAttribute("data-liveness", worker.liveness);
+  row.setAttribute("data-stream", worker.stream);
+
+  const nameCell = el(doc, "td", "cockpit-td cockpit-supply-name");
+  nameCell.appendChild(dot(doc, worker.liveness));
+  const button = el(doc, "button", "cockpit-worker", worker.instance);
+  button.setAttribute("type", "button");
+  button.setAttribute("data-stream", worker.stream);
+  const onDrill = options.onDrill;
+  if (onDrill !== undefined) {
+    button.addEventListener("click", () => onDrill(worker.stream));
+  }
+  nameCell.appendChild(button);
+  row.appendChild(nameCell);
+
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-supply-family", worker.family));
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-supply-host", worker.host));
+
+  const jobsCell = el(doc, "td", "cockpit-td cockpit-supply-jobs", worker.jobs === 0 ? "—" : worker.jobKeys.join(", "));
+  jobsCell.setAttribute("data-jobs", String(worker.jobs));
+  row.appendChild(jobsCell);
+
+  // The process instance / plan each current job belongs to (H6). Each correlation is a drill button
+  // onto its jobKey-scoped relay stream, so the operator opens the LIVE job's terminal — not just the
+  // worker's default stream. Empty → "—" so the cell always renders something stable.
+  const processCell = el(doc, "td", "cockpit-td cockpit-supply-process");
+  processCell.setAttribute("data-correlations", String(worker.correlations.length));
+  if (worker.correlations.length === 0) {
+    processCell.textContent = "—";
+  } else {
+    for (const correlation of worker.correlations) {
+      const link = el(doc, "button", "cockpit-correlation", correlation.label);
+      link.setAttribute("type", "button");
+      link.setAttribute("data-job-key", correlation.jobKey);
+      link.setAttribute("data-stream", correlation.stream);
+      if (onDrill !== undefined) {
+        link.addEventListener("click", () => onDrill(correlation.stream));
+      }
+      processCell.appendChild(link);
+    }
+  }
+  row.appendChild(processCell);
+
+  const livenessCell = el(doc, "td", "cockpit-td cockpit-supply-liveness", worker.liveness);
+  livenessCell.setAttribute("data-liveness", worker.liveness);
+  row.appendChild(livenessCell);
+
+  return row;
+}
+
+function leafSection(doc: DocumentLike, leaf: SupplyLeafView, options: RenderSupplyOptions): ElementLike {
+  const section = el(doc, "section", "cockpit-leaf");
+  section.setAttribute("data-leaf", leaf.token);
+
+  const header = el(doc, "div", "cockpit-leaf-head");
+  header.appendChild(el(doc, "span", "cockpit-leaf-name", leaf.token));
+  header.appendChild(el(doc, "span", "cockpit-leaf-count", `${leaf.liveCount}/${leaf.total} live`));
+  section.appendChild(header);
+
+  const table = el(doc, "table", "cockpit-supply-table");
+  const thead = el(doc, "thead", "cockpit-supply-thead");
+  const head = el(doc, "tr", "cockpit-supply-head");
+  for (const label of ["worker", "family", "host", "jobs", "process / plan", "liveness"]) {
+    head.appendChild(el(doc, "th", "cockpit-th", label));
+  }
+  thead.appendChild(head);
+  table.appendChild(thead);
+
+  const tbody = el(doc, "tbody", "cockpit-supply-tbody");
+  for (const worker of leaf.workers) {
+    tbody.appendChild(workerRow(doc, worker, options));
+  }
+  table.appendChild(tbody);
+  section.appendChild(table);
+  return section;
+}
+
+/**
+ * Render `view` into `host`, replacing whatever was there. Idempotent: call it again on every refresh
+ * to reflect the latest supply snapshot.
+ */
+export function renderSupply(
+  host: ElementLike,
+  doc: DocumentLike,
+  view: SupplyView,
+  options: RenderSupplyOptions = {},
+): SupplyDom {
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit-supply");
+  root.setAttribute("data-worker-count", String(view.count));
+  root.setAttribute("data-live-count", String(view.live));
+
+  const header = el(doc, "header", "cockpit-header");
+  header.appendChild(el(doc, "h1", "cockpit-title", "Workers — supply"));
+  const summary = el(doc, "span", "cockpit-supply-summary", `${view.live}/${view.count} live`);
+  summary.setAttribute("data-summary", "supply");
+  header.appendChild(summary);
+  root.appendChild(header);
+
+  if (view.count === 0) {
+    const empty = el(doc, "div", "cockpit-supply-empty", "No workers connected.");
+    empty.setAttribute("data-empty", "true");
+    root.appendChild(empty);
+    host.appendChild(root);
+    return { root };
+  }
+
+  const list = el(doc, "div", "cockpit-supply-list");
+  for (const leaf of view.leaves) {
+    list.appendChild(leafSection(doc, leaf, options));
+  }
+  root.appendChild(list);
+
+  host.appendChild(root);
+  return { root };
+}

package/app/agentic/cockpit/supply-view.test.ts

@@ -0,0 +1,116 @@
+// Unit tests for the SUPPLY cockpit view-model projection (H5 / #148).
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { type SupplyReport, supplyView } from "./supply-view.ts";
+
+function report(over: Partial<SupplyReport> = {}): SupplyReport {
+  const workers = over.workers ?? [];
+  return {
+    workers,
+    leaves: over.leaves ?? [],
+    count: over.count ?? workers.length,
+    generatedAt: over.generatedAt,
+    correlations: over.correlations,
+  };
+}
+
+test("grades liveness: down when disconnected, stale past the threshold, else live", () => {
+  const view = supplyView(
+    report({
+      workers: [
+        { instance: "a", identity: "t", stream: "a", jobKeys: [], live: false, staleMs: 0 },
+        { instance: "b", identity: "t", stream: "b", jobKeys: [], live: true, staleMs: 20_000 },
+        { instance: "c", identity: "t", stream: "c", jobKeys: [], live: true, staleMs: 100 },
+      ],
+    }),
+    { staleAfterMs: 15_000 },
+  );
+  assert.equal(view.workers.find((w) => w.instance === "a")?.liveness, "down");
+  assert.equal(view.workers.find((w) => w.instance === "b")?.liveness, "stale");
+  assert.equal(view.workers.find((w) => w.instance === "c")?.liveness, "live");
+  assert.equal(view.count, 3);
+  assert.equal(view.live, 1);
+});
+
+test("defaults absent family/host to a stable dash and counts + sorts jobKeys", () => {
+  const view = supplyView(
+    report({
+      workers: [{ instance: "a", identity: "t", stream: "a", jobKeys: ["z", "a"], live: true, staleMs: 0 }],
+    }),
+  );
+  const w = view.workers[0];
+  assert.equal(w?.family, "—");
+  assert.equal(w?.host, "—");
+  assert.deepEqual(w?.jobKeys, ["a", "z"]);
+  assert.equal(w?.jobs, 2);
+});
+
+test("sorts leaves by token and workers by instance, with per-leaf live counts", () => {
+  const view = supplyView(
+    report({
+      leaves: [
+        {
+          token: "leaf-b",
+          workers: [
+            { instance: "b2", identity: "leaf-b", stream: "b2", jobKeys: [], live: true, staleMs: 0 },
+            { instance: "b1", identity: "leaf-b", stream: "b1", jobKeys: [], live: false, staleMs: 0 },
+          ],
+        },
+        {
+          token: "leaf-a",
+          workers: [{ instance: "a1", identity: "leaf-a", stream: "a1", jobKeys: [], live: true, staleMs: 0 }],
+        },
+      ],
+    }),
+  );
+  assert.deepEqual(
+    view.leaves.map((l) => l.token),
+    ["leaf-a", "leaf-b"],
+  );
+  assert.deepEqual(
+    view.leaves[1]?.workers.map((w) => w.instance),
+    ["b1", "b2"],
+  );
+  assert.equal(view.leaves[1]?.liveCount, 1);
+  assert.equal(view.leaves[1]?.total, 2);
+});
+
+test("H6: resolves each worker's jobKeys into correlation views with a human label", () => {
+  const view = supplyView(
+    report({
+      workers: [{ instance: "wk-a", identity: "leaf-a", stream: "job:6494", jobKeys: ["6494"], live: true, staleMs: 0 }],
+      correlations: [
+        { jobKey: "6494", stream: "job:6494", processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" },
+      ],
+    }),
+  );
+  const w = view.workers[0];
+  assert.equal(w?.correlations.length, 1);
+  const c = w?.correlations[0];
+  assert.equal(c?.jobKey, "6494");
+  assert.equal(c?.stream, "job:6494");
+  assert.equal(c?.processInstanceKey, "4612");
+  assert.equal(c?.planKey, "o/r#142");
+  assert.equal(c?.label, "plan-fanout · implement-task · inst 4612 · o/r#142");
+});
+
+test("H6: a worker with no matching correlation renders an empty correlation list", () => {
+  const view = supplyView(
+    report({
+      workers: [{ instance: "wk-a", identity: "leaf-a", stream: "wk-a", jobKeys: ["nope"], live: true, staleMs: 0 }],
+      correlations: [{ jobKey: "other", stream: "job:other" }],
+    }),
+  );
+  assert.deepEqual(view.workers[0]?.correlations, []);
+});
+
+test("H6: a correlation with no engine context falls back to a job-key label", () => {
+  const view = supplyView(
+    report({
+      workers: [{ instance: "wk-a", identity: "leaf-a", stream: "job:6494", jobKeys: ["6494"], live: true, staleMs: 0 }],
+      correlations: [{ jobKey: "6494", stream: "job:6494" }],
+    }),
+  );
+  assert.equal(view.workers[0]?.correlations[0]?.label, "job 6494");
+});

package/app/agentic/cockpit/supply-view.ts

@@ -0,0 +1,243 @@
+// The SUPPLY-only cockpit view-model (ADR 0056, H5 / #148).
+//
+// A pure, deterministic projection of the app's SUPPLY report — the live worker registry (H1 #144)
+// carried over the agentic channel — onto the shape the supply cockpit renders: a per-leaf-token
+// list of connected workers with family, host, current jobs, and liveness.
+//
+// This is DELIBERATELY the supply half only. The DEMAND×supply matrix, the missing-agent-type reds,
+// and the diversity-SLO lights (the packaged `@nanobpm/agentic/cockpit` view/render draws those from
+// a `DemandSupplyReport`) are OUT OF SCOPE for this epic (#142) — they depend on the vocab /
+// capability→SERVE / diversity-SLO machinery deferred to the paired enrolment epic #152. So this
+// module models a supply-only report and never fabricates demand data.
+//
+// Like the packaged `cockpit/view.ts` it is framework-free and side-effect-free: the same report
+// always yields the same {@link SupplyView}, so it is safe to snapshot in a test and to render
+// identically whether the page is embedded in the console (App View, ADR 0057) or served standalone.
+
+/** A worker's coarse liveness grade, rendered as a coloured dot. */
+export type Liveness = "live" | "stale" | "down";
+
+/** One connected worker as the app's supply feed reports it (mirrors the H1 registry snapshot row). */
+export interface SupplyWorkerReport {
+  /** The worker instance id. */
+  readonly instance: string;
+  /** The authenticated ADR 0028 principal — the leaf token this worker registered under. */
+  readonly identity: string;
+  /**
+   * The relay stream to drill into for this worker's live terminal. The supply endpoint defaults it
+   * to the worker instance; the correlation slice (H6 #149) may repoint it at a jobKey-keyed stream.
+   */
+  readonly stream: string;
+  /** Declared family (enrolment attribute), if any. */
+  readonly family?: string;
+  /** Declared host (where the worker runs), if any. */
+  readonly host?: string;
+  /** The jobKeys the worker is currently processing (empty until H6 wires the resolver). */
+  readonly jobKeys: readonly string[];
+  /** Whether the worker's channel connection is still open. */
+  readonly live: boolean;
+  /** How long since the worker's last liveness refresh, in ms. */
+  readonly staleMs: number;
+}
+
+/** The supply registered under one leaf token. */
+export interface SupplyLeafReport {
+  readonly token: string;
+  readonly workers: readonly SupplyWorkerReport[];
+}
+
+/**
+ * One current job's engine context (H6 #149) — the process instance / plan a worker's terminal is
+ * lined up against. Mirrors the supply endpoint's `AgenticJobCorrelation`.
+ */
+export interface SupplyCorrelationReport {
+  /** The Camunda-8 job key. */
+  readonly jobKey: string;
+  /** The relay stream the job's terminal is on (`job:<jobKey>`). */
+  readonly stream: string;
+  /** The owning process instance key, if known. */
+  readonly processInstanceKey?: string;
+  /** The BPMN process id, if known. */
+  readonly bpmnProcessId?: string;
+  /** The BPMN element id, if known. */
+  readonly elementId?: string;
+  /** The plan / epic key, if known. */
+  readonly planKey?: string;
+}
+
+/** The supply-only report the cockpit polls (no demand fields — those are enrolment epic #152). */
+export interface SupplyReport {
+  /** Supply grouped by leaf token. */
+  readonly leaves: readonly SupplyLeafReport[];
+  /** Every connected worker, flat. */
+  readonly workers: readonly SupplyWorkerReport[];
+  /** The number of connected workers. */
+  readonly count: number;
+  /** When the snapshot was taken, ISO-8601 (optional). */
+  readonly generatedAt?: string;
+  /** The engine context for every currently-processing job (H6), keyed by jobKey. */
+  readonly correlations?: readonly SupplyCorrelationReport[];
+}
+
+/** One current job's context as the cockpit renders it in a worker row (H6). */
+export interface JobCorrelationView {
+  /** The Camunda-8 job key. */
+  readonly jobKey: string;
+  /** The relay stream the job's terminal is on. */
+  readonly stream: string;
+  /** A single human label for the process instance / plan, e.g. `plan-fanout · inst 4612 · owner/repo#142`. */
+  readonly label: string;
+  /** The owning process instance key, if known. */
+  readonly processInstanceKey?: string;
+  /** The BPMN process id, if known. */
+  readonly bpmnProcessId?: string;
+  /** The BPMN element id, if known. */
+  readonly elementId?: string;
+  /** The plan / epic key, if known. */
+  readonly planKey?: string;
+}
+
+/** One worker row in the renderable supply view. */
+export interface SupplyWorkerView {
+  readonly instance: string;
+  readonly identity: string;
+  /** The relay stream to open when the operator drills into this worker. */
+  readonly stream: string;
+  /** Declared family, or `"—"` when absent (so the cell always renders something stable). */
+  readonly family: string;
+  /** Declared host, or `"—"` when absent. */
+  readonly host: string;
+  /** The worker's current jobKeys, sorted. */
+  readonly jobKeys: readonly string[];
+  /** The number of current jobs. */
+  readonly jobs: number;
+  /**
+   * The engine context for each of this worker's current jobs (H6), sorted by jobKey — so the operator
+   * sees which process instance / plan the terminal belongs to. Empty when nothing correlates.
+   */
+  readonly correlations: readonly JobCorrelationView[];
+  /** The coarse liveness grade for the status dot. */
+  readonly liveness: Liveness;
+  /** How long since the last liveness refresh, in ms. */
+  readonly staleMs: number;
+}
+
+/** One leaf-token section in the renderable supply view. */
+export interface SupplyLeafView {
+  readonly token: string;
+  readonly workers: readonly SupplyWorkerView[];
+  /** Workers under this leaf currently graded `live`. */
+  readonly liveCount: number;
+  /** Total workers under this leaf. */
+  readonly total: number;
+}
+
+/** The full renderable supply view. */
+export interface SupplyView {
+  /** Supply grouped by leaf token, sorted by token. */
+  readonly leaves: readonly SupplyLeafView[];
+  /** Every worker, flat, sorted by instance. */
+  readonly workers: readonly SupplyWorkerView[];
+  /** The number of workers. */
+  readonly count: number;
+  /** The number of workers graded `live`. */
+  readonly live: number;
+}
+
+/** Options for {@link supplyView}. */
+export interface SupplyViewOptions {
+  /**
+   * A live worker whose last refresh is older than this (ms) is graded `stale` rather than `live`.
+   * A disconnected worker is always `down`. Default 15000.
+   */
+  readonly staleAfterMs?: number;
+}
+
+const DEFAULT_STALE_AFTER_MS = 15_000;
+
+function liveness(worker: SupplyWorkerReport, staleAfterMs: number): Liveness {
+  if (!worker.live) return "down";
+  return worker.staleMs >= staleAfterMs ? "stale" : "live";
+}
+
+/** A single stable human label for a job's process instance / plan (empty parts are dropped). */
+function correlationLabel(c: SupplyCorrelationReport): string {
+  const parts: string[] = [];
+  if (c.bpmnProcessId !== undefined) parts.push(c.bpmnProcessId);
+  if (c.elementId !== undefined) parts.push(c.elementId);
+  if (c.processInstanceKey !== undefined) parts.push(`inst ${c.processInstanceKey}`);
+  if (c.planKey !== undefined) parts.push(c.planKey);
+  return parts.length > 0 ? parts.join(" · ") : `job ${c.jobKey}`;
+}
+
+function correlationView(c: SupplyCorrelationReport): JobCorrelationView {
+  return {
+    jobKey: c.jobKey,
+    stream: c.stream,
+    label: correlationLabel(c),
+    ...(c.processInstanceKey !== undefined ? { processInstanceKey: c.processInstanceKey } : {}),
+    ...(c.bpmnProcessId !== undefined ? { bpmnProcessId: c.bpmnProcessId } : {}),
+    ...(c.elementId !== undefined ? { elementId: c.elementId } : {}),
+    ...(c.planKey !== undefined ? { planKey: c.planKey } : {}),
+  };
+}
+
+function workerView(
+  worker: SupplyWorkerReport,
+  staleAfterMs: number,
+  byJobKey: ReadonlyMap<string, SupplyCorrelationReport>,
+): SupplyWorkerView {
+  const jobKeys = [...worker.jobKeys].sort((a, b) => a.localeCompare(b));
+  const correlations = jobKeys
+    .map((jobKey) => byJobKey.get(jobKey))
+    .filter((c): c is SupplyCorrelationReport => c !== undefined)
+    .map(correlationView);
+  return {
+    instance: worker.instance,
+    identity: worker.identity,
+    stream: worker.stream,
+    family: worker.family ?? "—",
+    host: worker.host ?? "—",
+    jobKeys,
+    jobs: jobKeys.length,
+    correlations,
+    liveness: liveness(worker, staleAfterMs),
+    staleMs: worker.staleMs,
+  };
+}
+
+const byInstance = (a: SupplyWorkerView, b: SupplyWorkerView) => a.instance.localeCompare(b.instance);
+
+/**
+ * Derive the renderable supply view from the app's supply-only report.
+ *
+ * Pure and total: it re-sorts leaves by token and workers by instance so the derived view is stable
+ * and diff-friendly regardless of the report's incoming order; no input mutates and no I/O happens.
+ */
+export function supplyView(report: SupplyReport, options: SupplyViewOptions = {}): SupplyView {
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+
+  const byJobKey = new Map<string, SupplyCorrelationReport>();
+  for (const c of report.correlations ?? []) byJobKey.set(c.jobKey, c);
+
+  const leaves: SupplyLeafView[] = report.leaves
+    .map((leaf) => {
+      const workers = leaf.workers.map((w) => workerView(w, staleAfterMs, byJobKey)).sort(byInstance);
+      return {
+        token: leaf.token,
+        workers,
+        liveCount: workers.filter((w) => w.liveness === "live").length,
+        total: workers.length,
+      };
+    })
+    .sort((a, b) => a.token.localeCompare(b.token));
+
+  const workers = report.workers.map((w) => workerView(w, staleAfterMs, byJobKey)).sort(byInstance);
+
+  return {
+    leaves,
+    workers,
+    count: workers.length,
+    live: workers.filter((w) => w.liveness === "live").length,
+  };
+}