@nanobpm/agentic 0.1.0

package/src/cockpit/view.ts

@@ -0,0 +1,140 @@
+/**
+ * The cockpit view-model — S8.
+ *
+ * A pure, deterministic projection of the S4 {@link DemandSupplyReport} onto the
+ * shape the cockpit renders: a per-network demand×supply matrix, a red light per
+ * *missing agent type*, and the diversity-SLO state (from S3, carried through S4).
+ *
+ * It is deliberately framework-free and side-effect-free: the same report always
+ * yields the same {@link CockpitView}, so it is safe to diff frame-to-frame, to
+ * snapshot in a test, and to render identically whether the page is embedded in
+ * the console (App View) or served standalone — the view is the single source of
+ * truth both render paths consume.
+ */
+import type { DemandSupplyReport, NetworkDemand, SloStatus, TokenDemand } from "../demand/index.ts";
+import type { DiversityReport } from "../vocab/index.ts";
+
+export type { SloStatus } from "../demand/index.ts";
+
+/** A three-state status light rendered as a coloured dot + label. */
+export interface CockpitLight {
+  /** Stable id for the DOM node / keyed diff. */
+  readonly id: string;
+  /** Human label shown next to the dot. */
+  readonly label: string;
+  /** The grade the dot colours to. */
+  readonly status: SloStatus;
+  /** Optional one-line detail (tooltip / secondary text). */
+  readonly detail?: string;
+}
+
+/** One demanded routing token as a matrix cell. */
+export interface CockpitTokenRow {
+  /** The demanded routing token. */
+  readonly token: string;
+  /** How many registered workers currently serve it. */
+  readonly supply: number;
+  /** The serving worker instances (provenance for the drill-in), sorted. */
+  readonly instances: readonly string[];
+  /** False when no worker serves it — a missing agent type. */
+  readonly satisfied: boolean;
+  /** GREEN when served, RED when missing. */
+  readonly status: SloStatus;
+}
+
+/** One network prefix as a matrix row. */
+export interface CockpitNetworkRow {
+  /** The network prefix bucket. */
+  readonly network: string;
+  /** Every demanded token in the bucket, sorted by token. */
+  readonly tokens: readonly CockpitTokenRow[];
+  /** The demanded tokens in this bucket with zero supply, sorted. */
+  readonly missing: readonly string[];
+  /** RED when the row has any missing agent type, else GREEN. */
+  readonly status: SloStatus;
+}
+
+/** The full renderable cockpit view. */
+export interface CockpitView {
+  /** The overall SLO state: worst of missing-agent and diversity. */
+  readonly status: SloStatus;
+  /** The demand×supply matrix, one row per network, sorted by network. */
+  readonly networks: readonly CockpitNetworkRow[];
+  /** Every missing agent type across all networks, sorted and de-duplicated. */
+  readonly missing: readonly string[];
+  /** One RED light per missing agent type (empty when nothing is missing). */
+  readonly missingLights: readonly CockpitLight[];
+  /** The S3 diversity report, carried through unchanged for detail rendering. */
+  readonly diversity: DiversityReport;
+  /** A single light summarising the diversity SLO. */
+  readonly diversityLight: CockpitLight;
+  /**
+   * Deployed task types that are not valid routing tokens (ordinary,
+   * non-agentic C8 jobs) — surfaced so an operator can spot a mistyped token,
+   * excluded from the agentic accounting.
+   */
+  readonly nonAgentic: readonly string[];
+}
+
+function tokenRow(token: TokenDemand): CockpitTokenRow {
+  return {
+    token: token.token,
+    supply: token.supply,
+    instances: token.instances,
+    satisfied: token.satisfied,
+    status: token.satisfied ? "green" : "red",
+  };
+}
+
+function networkRow(network: NetworkDemand): CockpitNetworkRow {
+  return {
+    network: network.network,
+    tokens: network.tokens.map(tokenRow),
+    missing: network.missing,
+    status: network.missing.length > 0 ? "red" : "green",
+  };
+}
+
+function missingLight(token: string): CockpitLight {
+  return {
+    id: `missing:${token}`,
+    label: token,
+    status: "red",
+    detail: "missing agent type — no registered worker serves this token",
+  };
+}
+
+function diversityDetail(diversity: DiversityReport): string {
+  const offenders = diversity.roles.filter((role) => role.status !== "green");
+  if (offenders.length === 0) return "family(#red) ≠ family(#blue) holds for every role";
+  return offenders
+    .map((role) => `${role.token}: ${role.collidingFamilies.join(", ")} (${role.status})`)
+    .join("; ");
+}
+
+function diversityLight(diversity: DiversityReport): CockpitLight {
+  return {
+    id: "diversity",
+    label: "diversity SLO",
+    status: diversity.status,
+    detail: diversityDetail(diversity),
+  };
+}
+
+/**
+ * Derive the renderable cockpit view from an S4 demand×supply report.
+ *
+ * Pure and total: every list is already sorted by S4, so the derived view is
+ * stable and diff-friendly; no input mutates and no I/O happens.
+ */
+export function cockpitView(report: DemandSupplyReport): CockpitView {
+  return {
+    status: report.status,
+    networks: report.networks.map(networkRow),
+    missing: report.missing,
+    missingLights: report.missing.map(missingLight),
+    diversity: report.diversity,
+    diversityLight: diversityLight(report.diversity),
+    nonAgentic: report.nonAgentic,
+  };
+}

package/src/demand/c8-rest.test.ts

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { httpC8RestReader, readDeployedTaskDefinitions, readDeployedTaskTypes, type FetchLike } from "./c8-rest.ts";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function xmlFor(taskType: string): string {
+  return `<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0">
+    <bpmn:process id="proc-${taskType}">
+      <bpmn:serviceTask id="t"><zeebe:taskDefinition type="${taskType}" /></bpmn:serviceTask>
+    </bpmn:process>
+  </bpmn:definitions>`;
+}
+
+function jsonResponse(body: unknown): Awaited<ReturnType<FetchLike>> {
+  return {
+    ok: true,
+    status: 200,
+    statusText: "OK",
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  };
+}
+
+function textResponse(text: string): Awaited<ReturnType<FetchLike>> {
+  return {
+    ok: true,
+    status: 200,
+    statusText: "OK",
+    json: async () => JSON.parse(text),
+    text: async () => text,
+  };
+}
+
+test("reads deployed taskDefinition leaves over the C8 v2 REST API", async () => {
+  const calls: string[] = [];
+  const fetch: FetchLike = async (input, init) => {
+    calls.push(`${init?.method ?? "GET"} ${input}`);
+    if (input.endsWith("/process-definitions/search")) {
+      return jsonResponse({ items: [{ processDefinitionKey: "111" }, { processDefinitionKey: 222 }] });
+    }
+    if (input.endsWith("/process-definitions/111/xml")) return textResponse(xmlFor("planning.planner"));
+    if (input.endsWith("/process-definitions/222/xml")) return textResponse(xmlFor("qa.tester"));
+    throw new Error(`unexpected call ${input}`);
+  };
+
+  const reader = httpC8RestReader({ restAddress: "http://engine:8080/v2/", fetch });
+  const leaves = await readDeployedTaskDefinitions(reader);
+
+  assert.deepEqual(
+    leaves.map((l) => l.taskType),
+    ["planning.planner", "qa.tester"],
+  );
+  // Trailing slash on restAddress is normalised (no double slash).
+  assert.ok(calls.includes("POST http://engine:8080/v2/process-definitions/search"));
+  // Numeric keys are coerced to strings for the XML path.
+  assert.ok(calls.includes("GET http://engine:8080/v2/process-definitions/222/xml"));
+});
+
+test("pages the definition search until a short page drains it", async () => {
+  const pageOf = (from: number, limit: number): { processDefinitionKey: string }[] =>
+    Array.from({ length: Math.max(0, Math.min(limit, 250 - from)) }, (_u, i) => ({
+      processDefinitionKey: String(from + i),
+    }));
+
+  const seenPages: number[] = [];
+  const fetch: FetchLike = async (input, init) => {
+    if (input.endsWith("/process-definitions/search")) {
+      const body: unknown = JSON.parse(init?.body ?? "{}");
+      const page = isRecord(body) ? body.page : undefined;
+      const from = isRecord(page) && typeof page.from === "number" ? page.from : 0;
+      const limit = isRecord(page) && typeof page.limit === "number" ? page.limit : 100;
+      seenPages.push(from);
+      return jsonResponse({ items: pageOf(from, limit) });
+    }
+    return textResponse(xmlFor("ci.runner"));
+  };
+
+  const reader = httpC8RestReader({ restAddress: "http://engine:8080/v2", fetch, pageSize: 100 });
+  const keys = await reader.searchProcessDefinitionKeys();
+
+  assert.equal(keys.length, 250);
+  assert.deepEqual(seenPages, [0, 100, 200]);
+});
+
+test("readDeployedTaskTypes returns the distinct demand set", async () => {
+  const fetch: FetchLike = async (input) => {
+    if (input.endsWith("/process-definitions/search")) {
+      return jsonResponse({ items: [{ processDefinitionKey: "1" }, { processDefinitionKey: "2" }] });
+    }
+    return textResponse(xmlFor("planning.planner"));
+  };
+  const reader = httpC8RestReader({ restAddress: "http://x/v2", fetch });
+  assert.deepEqual(await readDeployedTaskTypes(reader), ["planning.planner"]);
+});
+
+test("sends the bearer token when configured", async () => {
+  let authHeader: string | undefined;
+  const fetch: FetchLike = async (input, init) => {
+    authHeader = init?.headers?.authorization;
+    if (input.endsWith("/search")) return jsonResponse({ items: [] });
+    return textResponse("");
+  };
+  const reader = httpC8RestReader({ restAddress: "http://x/v2", fetch, token: "secret" });
+  await reader.searchProcessDefinitionKeys();
+  assert.equal(authHeader, "Bearer secret");
+});
+
+test("a non-2xx search fails loudly rather than reporting zero demand", async () => {
+  const fetch: FetchLike = async () => ({
+    ok: false,
+    status: 503,
+    statusText: "Service Unavailable",
+    json: async () => ({}),
+    text: async () => "",
+  });
+  const reader = httpC8RestReader({ restAddress: "http://x/v2", fetch });
+  await assert.rejects(() => reader.searchProcessDefinitionKeys(), /503 Service Unavailable/);
+});
+
+test("a non-2xx xml fetch fails loudly", async () => {
+  const fetch: FetchLike = async (input) => {
+    if (input.endsWith("/search")) return jsonResponse({ items: [{ processDefinitionKey: "1" }] });
+    return { ok: false, status: 404, statusText: "Not Found", json: async () => ({}), text: async () => "" };
+  };
+  const reader = httpC8RestReader({ restAddress: "http://x/v2", fetch });
+  await assert.rejects(() => readDeployedTaskDefinitions(reader), /404 Not Found/);
+});
+
+test("rejects a non-positive-integer pageSize instead of spinning forever", () => {
+  const fetch: FetchLike = async () => jsonResponse({ items: [] });
+  // pageSize is the loop's termination condition (items.length < pageSize); a
+  // zero/negative/NaN/fractional value could never break, so reject it up front.
+  for (const bad of [0, -1, Number.NaN, Number.POSITIVE_INFINITY, 1.5]) {
+    assert.throws(() => httpC8RestReader({ restAddress: "http://x/v2", fetch, pageSize: bad }), /pageSize must be a positive integer/);
+  }
+});

package/src/demand/c8-rest.ts

@@ -0,0 +1,167 @@
+/**
+ * Read deployed models' `taskDefinition` leaves from the engine's C8 REST API.
+ *
+ * S4 is a read-only mirror: it reads what the *engine* already has deployed and
+ * diffs it against live supply — it never places work. The Camunda-8 engine stays
+ * frozen (design invariant 2): we speak the ordinary C8 v2 REST API over the
+ * app's own HTTP client, on a connection entirely separate from the agentic
+ * channel and from the worker's C8 job protocol. Nothing here rides the engine's
+ * transport or mutates engine state.
+ *
+ * The concrete reader ({@link httpC8RestReader}) is a thin fetch adapter over two
+ * C8 v2 endpoints:
+ *
+ *  - `POST {rest}/process-definitions/search` → the deployed definition keys.
+ *  - `GET  {rest}/process-definitions/{key}/xml` → each definition's BPMN XML.
+ *
+ * It is expressed against a small structural {@link C8RestReader} seam so the
+ * model can be driven by an in-memory reader in tests without a live engine.
+ */
+import { distinctTaskTypes, scanTaskDefinitions, type TaskDefinitionLeaf } from "./taskdef.ts";
+
+/**
+ * The minimal C8 REST surface the demand reader needs: enumerate deployed
+ * process-definition keys and fetch each one's BPMN XML. Structural so tests can
+ * supply an in-memory implementation.
+ */
+export interface C8RestReader {
+  /** Every deployed process-definition key currently known to the engine. */
+  searchProcessDefinitionKeys(): Promise<string[]>;
+  /** The BPMN XML of one process definition. */
+  getProcessDefinitionXml(processDefinitionKey: string): Promise<string>;
+}
+
+/** A `fetch`-shaped function, so the HTTP reader is testable without the global. */
+export type FetchLike = (
+  input: string,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  statusText: string;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}>;
+
+/** Options for {@link httpC8RestReader}. */
+export interface HttpC8RestReaderOptions {
+  /** The C8 REST base address, e.g. `http://localhost:8080/v2`. */
+  readonly restAddress: string;
+  /** Optional bearer token for the C8 REST API. */
+  readonly token?: string;
+  /** Injected `fetch` (defaults to the global). */
+  readonly fetch?: FetchLike;
+  /** Search page size (C8 caps the result set; the reader pages until drained). Must be a positive integer. */
+  readonly pageSize?: number;
+}
+
+function trimSlash(address: string): string {
+  return address.endsWith("/") ? address.slice(0, -1) : address;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asKey(item: unknown): string | undefined {
+  if (!isRecord(item)) return undefined;
+  const key = item.processDefinitionKey;
+  if (typeof key === "string") return key;
+  if (typeof key === "number") return String(key);
+  return undefined;
+}
+
+function itemsOf(body: unknown): unknown[] {
+  if (!isRecord(body)) return [];
+  return Array.isArray(body.items) ? body.items : [];
+}
+
+/**
+ * Build a {@link C8RestReader} backed by the live C8 v2 REST API.
+ *
+ * `searchProcessDefinitionKeys` pages `POST /process-definitions/search` until the
+ * engine returns fewer than a full page, de-duplicating keys. `getProcessDefinitionXml`
+ * reads `GET /process-definitions/{key}/xml`. Both raise on a non-2xx response so a
+ * misconfigured endpoint fails loudly rather than reporting phantom zero demand.
+ */
+export function httpC8RestReader(options: HttpC8RestReaderOptions): C8RestReader {
+  const base = trimSlash(options.restAddress);
+  const doFetch: FetchLike = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const pageSize = options.pageSize ?? 100;
+  if (!Number.isInteger(pageSize) || pageSize <= 0) {
+    throw new Error(`httpC8RestReader: pageSize must be a positive integer, got ${pageSize}`);
+  }
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (options.token !== undefined) headers.authorization = `Bearer ${options.token}`;
+
+  return {
+    async searchProcessDefinitionKeys(): Promise<string[]> {
+      const keys: string[] = [];
+      const seen = new Set<string>();
+      let from = 0;
+      for (;;) {
+        const response = await doFetch(`${base}/process-definitions/search`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ page: { from, limit: pageSize } }),
+        });
+        if (!response.ok) {
+          throw new Error(`C8 REST process-definitions/search failed: ${response.status} ${response.statusText}`);
+        }
+        const items = itemsOf(await response.json());
+        for (const item of items) {
+          const key = asKey(item);
+          if (key !== undefined && !seen.has(key)) {
+            seen.add(key);
+            keys.push(key);
+          }
+        }
+        if (items.length < pageSize) break;
+        from += items.length;
+      }
+      return keys;
+    },
+    async getProcessDefinitionXml(processDefinitionKey: string): Promise<string> {
+      const response = await doFetch(`${base}/process-definitions/${encodeURIComponent(processDefinitionKey)}/xml`, {
+        method: "GET",
+        headers,
+      });
+      if (!response.ok) {
+        throw new Error(
+          `C8 REST process-definitions/${processDefinitionKey}/xml failed: ${response.status} ${response.statusText}`,
+        );
+      }
+      return response.text();
+    },
+  };
+}
+
+/**
+ * Read every deployed model's `taskDefinition` leaves through a {@link C8RestReader}.
+ *
+ * Enumerates the deployed definitions, fetches each one's BPMN XML, and scans out
+ * its service-task task-definition leaves. The result is the raw demand corpus the
+ * {@link ./model.ts} model buckets and diffs against supply.
+ */
+export async function readDeployedTaskDefinitions(reader: C8RestReader): Promise<TaskDefinitionLeaf[]> {
+  const keys = await reader.searchProcessDefinitionKeys();
+  const leaves: TaskDefinitionLeaf[] = [];
+  for (const key of keys) {
+    const xml = await reader.getProcessDefinitionXml(key);
+    leaves.push(...scanTaskDefinitions(xml));
+  }
+  return leaves;
+}
+
+/**
+ * Read the distinct demanded job types (routing tokens) from the engine — the
+ * convenience path for callers that only need the demand token set, not element
+ * provenance.
+ */
+export async function readDeployedTaskTypes(reader: C8RestReader): Promise<string[]> {
+  return distinctTaskTypes(await readDeployedTaskDefinitions(reader));
+}

package/src/demand/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @nanobpm/agentic-demand — the demand×supply model for the Nano agentic
+ * protocol (ADR 0056, slice S4).
+ *
+ * A **read-only mirror + enrolment gate**: it reads the deployed models'
+ * `taskDefinition` leaves from the engine's C8 REST API ({@link httpC8RestReader},
+ * {@link readDeployedTaskDefinitions}), buckets them by network prefix, and diffs
+ * that demand against the live supply — the S2 presence registry resolved through
+ * the S3 vocabulary ({@link computeDemandSupply}) — to surface, per network, the
+ * *missing agent types* (`demand ∖ supply`) and the SLO state (missing-agent RED
+ * folded together with the S3 diversity SLO).
+ *
+ * It does NOT match-make: it never places work on a worker or holds a seat's job.
+ * Active placement is explicitly out of scope for v1. Nothing here rides the
+ * Camunda-8 engine or its transport — the C8 REST read is an ordinary read over a
+ * separate connection; the engine and the C8 job protocol stay frozen.
+ *
+ * The wire contract (routing-token grammar, `demand` payload) lives in
+ * `@nanobpm/agentic-protocol`; the registry rows and vocab resolver come from
+ * `@nanobpm/agentic-vocab`. This package builds on both and never redefines them.
+ */
+
+export { scanTaskDefinitions, distinctTaskTypes, type TaskDefinitionLeaf } from "./taskdef.ts";
+
+export {
+  httpC8RestReader,
+  readDeployedTaskDefinitions,
+  readDeployedTaskTypes,
+  type C8RestReader,
+  type FetchLike,
+  type HttpC8RestReaderOptions,
+} from "./c8-rest.ts";
+
+export {
+  computeDemandSupply,
+  toDemandPayloads,
+  type DemandSupplyInput,
+  type DemandSupplyReport,
+  type NetworkDemand,
+  type TokenDemand,
+  type SloStatus,
+} from "./model.ts";

package/src/demand/model.test.ts

@@ -0,0 +1,197 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { CORE_VOCAB, VocabResolver, type RegisteredWorker } from "../vocab/index.ts";
+import type { VocabDocument } from "../protocol/index.ts";
+
+import { computeDemandSupply, toDemandPayloads } from "./model.ts";
+import type { TaskDefinitionLeaf } from "./taskdef.ts";
+
+const resolver = new VocabResolver(CORE_VOCAB);
+
+// A minimal vocab with a single warn-default, multi-seat role and NO strict
+// (`seatsDistinctFamily`) role — so a same-family collision grades AMBER, not RED.
+// The core vocab can't express this (every multi-seat cognition also carries a
+// strict `reviewer` role), so the diversity-fold cases use this instead.
+const AMBER_VOCAB: VocabDocument = {
+  version: 1,
+  networks: {
+    build: {
+      roles: {
+        worker: { requires: ["cognition=build"], seats: 2 },
+      },
+    },
+  },
+};
+const amberResolver = new VocabResolver(AMBER_VOCAB);
+
+function leaf(taskType: string, process = "p", elementId = "e"): TaskDefinitionLeaf {
+  return { taskType, process, elementId };
+}
+
+function worker(instance: string, cognition: string, family: string, weight?: number): RegisteredWorker {
+  return { instance, capability: { cognition, family, ...(weight === undefined ? {} : { weight }) } };
+}
+
+test("reports demand×supply per network and flags a missing agent type", () => {
+  // Deployed model demands three tokens across two networks.
+  const taskDefinitions = [leaf("planning.planner"), leaf("qa.tester"), leaf("ci.runner")];
+  // Live registry supplies planning + qa, but nobody serves ci.
+  const workers = [worker("w-plan", "planning", "gpt"), worker("w-qa", "qa", "claude")];
+
+  const report = computeDemandSupply({ taskDefinitions, workers, resolver });
+
+  assert.deepEqual(
+    report.networks.map((n) => n.network),
+    ["ci", "planning", "qa"],
+  );
+
+  const ci = report.networks.find((n) => n.network === "ci");
+  assert.ok(ci);
+  assert.deepEqual(ci.missing, ["ci.runner"]);
+  assert.equal(ci.tokens[0].supply, 0);
+  assert.equal(ci.tokens[0].satisfied, false);
+
+  const planning = report.networks.find((n) => n.network === "planning");
+  assert.ok(planning);
+  assert.deepEqual(planning.missing, []);
+  assert.equal(planning.tokens[0].token, "planning.planner");
+  assert.equal(planning.tokens[0].satisfied, true);
+  assert.deepEqual(planning.tokens[0].instances, ["w-plan"]);
+
+  // The missing agent type is surfaced at the top level and drives the SLO red.
+  assert.deepEqual(report.missing, ["ci.runner"]);
+  assert.equal(report.status, "red");
+});
+
+test("all demand satisfied → SLO green when diversity is also green", () => {
+  const taskDefinitions = [leaf("planning.planner"), leaf("ci.runner")];
+  const workers = [worker("w-plan", "planning", "gpt"), worker("w-ci", "ci", "claude")];
+
+  const report = computeDemandSupply({ taskDefinitions, workers, resolver });
+
+  assert.deepEqual(report.missing, []);
+  assert.equal(report.diversity.status, "green");
+  assert.equal(report.status, "green");
+});
+
+test("supply counts every registered worker that serves a token", () => {
+  const taskDefinitions = [leaf("implementation.junior")];
+  const workers = [
+    worker("w-a", "implementation", "gpt"),
+    worker("w-b", "implementation", "claude"),
+    worker("w-c", "qa", "gpt"),
+  ];
+
+  const report = computeDemandSupply({ taskDefinitions, workers, resolver });
+  const token = report.networks[0].tokens[0];
+  assert.equal(token.token, "implementation.junior");
+  // Both implementation workers serve implementation.junior; the qa worker does not.
+  assert.equal(token.supply, 2);
+  assert.deepEqual(token.instances, ["w-a", "w-b"]);
+});
+
+test("a requires-gated token is missing when no worker clears the gate", () => {
+  // implementation.senior requires weight>=4; the only implementation worker is weight 2.
+  const taskDefinitions = [leaf("implementation.senior")];
+  const workers = [worker("w-jr", "implementation", "gpt", 2)];
+
+  const report = computeDemandSupply({ taskDefinitions, workers, resolver });
+  assert.deepEqual(report.missing, ["implementation.senior"]);
+
+  // Raise the worker's weight and the same token becomes supplied.
+  const stronger = computeDemandSupply({
+    taskDefinitions,
+    workers: [worker("w-sr", "implementation", "gpt", 5)],
+    resolver,
+  });
+  assert.deepEqual(stronger.missing, []);
+});
+
+test("the diversity SLO folds into the overall status (amber warn-default)", () => {
+  // Two workers of the SAME family fill the two `build.worker` seats: a
+  // warn-default collision → AMBER. Demand is fully supplied, so missing is green.
+  const taskDefinitions = [leaf("build.worker")];
+  const workers = [worker("w-a", "build", "gpt"), worker("w-b", "build", "gpt")];
+
+  const report = computeDemandSupply({ taskDefinitions, workers, resolver: amberResolver });
+  assert.deepEqual(report.missing, []);
+  assert.equal(report.diversity.status, "amber");
+  assert.equal(report.status, "amber");
+});
+
+test("a missing agent type is RED even if diversity is only amber", () => {
+  const taskDefinitions = [leaf("build.worker"), leaf("ci.runner")];
+  const workers = [worker("w-a", "build", "gpt"), worker("w-b", "build", "gpt")];
+
+  const report = computeDemandSupply({ taskDefinitions, workers, resolver: amberResolver });
+  assert.deepEqual(report.missing, ["ci.runner"]);
+  assert.equal(report.diversity.status, "amber");
+  assert.equal(report.status, "red");
+});
+
+test("buckets a bare (network-less) token under its own name", () => {
+  const report = computeDemandSupply({
+    taskDefinitions: [leaf("decide")],
+    workers: [],
+    resolver,
+  });
+  assert.deepEqual(
+    report.networks.map((n) => n.network),
+    ["decide"],
+  );
+  assert.deepEqual(report.networks[0].missing, ["decide"]);
+});
+
+test("distinct demand: a token demanded by many elements is one entry", () => {
+  const report = computeDemandSupply({
+    taskDefinitions: [leaf("qa.tester", "p1", "e1"), leaf("qa.tester", "p2", "e2")],
+    workers: [worker("w", "qa", "gpt")],
+    resolver,
+  });
+  const qa = report.networks.find((n) => n.network === "qa");
+  assert.ok(qa);
+  assert.equal(qa.tokens.length, 1);
+  assert.equal(qa.tokens[0].supply, 1);
+});
+
+test("non-routing-token task types are surfaced but excluded from accounting", () => {
+  const report = computeDemandSupply({
+    taskDefinitions: [leaf("planning.planner"), leaf("legacy:job#bad#token")],
+    workers: [worker("w", "planning", "gpt")],
+    resolver,
+  });
+  assert.deepEqual(report.nonAgentic, ["legacy:job#bad#token"]);
+  assert.deepEqual(
+    report.networks.map((n) => n.network),
+    ["planning"],
+  );
+  assert.deepEqual(report.missing, []);
+});
+
+test("the report is deterministic: lists sorted regardless of input order", () => {
+  const a = computeDemandSupply({
+    taskDefinitions: [leaf("qa.tester"), leaf("ci.runner"), leaf("planning.planner")],
+    workers: [worker("z", "qa", "gpt"), worker("a", "qa", "claude")],
+    resolver,
+  });
+  const b = computeDemandSupply({
+    taskDefinitions: [leaf("planning.planner"), leaf("qa.tester"), leaf("ci.runner")],
+    workers: [worker("a", "qa", "claude"), worker("z", "qa", "gpt")],
+    resolver,
+  });
+  assert.deepEqual(a, b);
+});
+
+test("toDemandPayloads projects one demand payload per network", () => {
+  const report = computeDemandSupply({
+    taskDefinitions: [leaf("planning.planner"), leaf("ci.runner")],
+    workers: [worker("w-plan", "planning", "gpt")],
+    resolver,
+  });
+  const payloads = toDemandPayloads(report);
+  assert.deepEqual(payloads, [
+    { network: "ci", missing: ["ci.runner"] },
+    { network: "planning", missing: [] },
+  ]);
+});