@nanobpm/nano-workforce 0.117.0 → 0.118.1

package/operations/dispatchDeliveryGraph.test.ts

@@ -0,0 +1,166 @@
+// Integration coverage for the POST /app/api/actions/delivery-graph/dispatch operation
+// `dispatchDeliveryGraph` (issue #386, ADR 0005 slice S5) — the human-facing UI JSON-paste DISPATCH
+// ingress. It parses the operator's pasted JSON STRING and DELEGATES to the SAME gated, idempotent
+// `startDeliveryGraph` handler (no parallel dispatch path), deriving the approval token from the graph
+// when the operator ticks `approve`. These tests drive the real delegate against an in-memory
+// app/data/engine (mirroring startDeliveryGraph.integration.test.ts) so the composed behaviour — parse
+// → approval-gate → launch — is proven, and assert the parse guards map to a 400 with a human error.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./dispatchDeliveryGraph.ts";
+
+// A compact in-memory app: a generic table over an array (get/find/insert/update/delete) faithful to
+// the run aggregate's PRIMARY KEY fence, plus the guarded raw UPDATE the door issues and a fake engine.
+function makeApp() {
+  const tables = new Map<string, Record<string, unknown>[]>();
+  const started: { processDefinitionId: string }[] = [];
+  const table = (name: string, key: string) => {
+    const rows = tables.get(name) ?? (() => {
+      const fresh: Record<string, unknown>[] = [];
+      tables.set(name, fresh);
+      return fresh;
+    })();
+    return {
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      insert: (r: Record<string, unknown>) => {
+        if (rows.some((existing) => existing[key] === r[key])) {
+          return Promise.reject(new Error(`UNIQUE constraint failed: ${name}.${key}`));
+        }
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    };
+  };
+  const app = {
+    data: {
+      table,
+      open: () => ({
+        exec: (sql: string, params: unknown[]) =>
+          Promise.resolve().then(() => {
+            const cols = [...sql.matchAll(/"(\w+)"\s*=\s*\?/g)].map((m) => m[1]);
+            const runKey = params[params.length - 1];
+            const rows = tables.get("delivery_graph_runs") ?? [];
+            const row = rows.find((r) => r["run_key"] === runKey);
+            if (row && row["status"] !== "running") {
+              for (let i = 0; i < cols.length - 1; i++) row[cols[i]] = params[i];
+              return { changed: 1 };
+            }
+            return { changed: 0 };
+          }),
+      }),
+    },
+    engine: {
+      deployResources: () => Promise.resolve([]),
+      createInstance: (req: { processDefinitionId: string }) => {
+        started.push(req);
+        return Promise.resolve({ processInstanceKey: "PI-1", processDefinitionId: req.processDefinitionId });
+      },
+    },
+    log: noopLog(),
+  } as unknown as AppApi;
+  return { app, started, runs: () => tables.get("delivery_graph_runs") ?? [] };
+}
+
+async function call(app: AppApi, body: unknown) {
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+const SIDE_EFFECTING = JSON.stringify({
+  name: "release runbook",
+  nodes: [
+    { id: "open-b", kind: "agent", agent: { jobType: "senior:feature", prompt: "un-draft + merge #B" } },
+    { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish" } },
+  ],
+  edges: [{ from: "open-b", to: "publish" }],
+});
+const HUMAN_ONLY = JSON.stringify({
+  name: "manual gate",
+  nodes: [{ id: "ack", kind: "human", human: { prompt: "click done when the release is out" } }],
+});
+
+test("dispatch-delivery-graph: a non-JSON paste → 400 with a human error, nothing launched", async () => {
+  const { app, started } = makeApp();
+  const res = await call(app, { graphJson: "{ not json" });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  assert(typeof res.body.error === "string" && res.body.error.includes("not valid JSON"));
+  assertEquals(started.length, 0);
+});
+
+test("dispatch-delivery-graph: a blank paste → 400, never a 500", async () => {
+  const { app } = makeApp();
+  const res = await call(app, { graphJson: "" });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+});
+
+test("dispatch-delivery-graph: a non-side-effecting graph dispatches straight away (202 running)", async () => {
+  const { app, started, runs } = makeApp();
+  const res = await call(app, { graphJson: HUMAN_ONLY });
+  assertEquals(res.status, 202);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.status, "running");
+  assertEquals(started.length, 1);
+  assertEquals(runs()[0].status, "running");
+});
+
+test("dispatch-delivery-graph: a side-effecting graph WITHOUT approve is parked at approval (400), nothing launched", async () => {
+  const { app, started, runs } = makeApp();
+  const res = await call(app, { graphJson: SIDE_EFFECTING });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  assertEquals(res.body.status, "awaiting-approval");
+  // The human banner is populated from the door's park message.
+  assert(typeof res.body.error === "string" && res.body.error.length > 0);
+  assertEquals(started.length, 0);
+  assertEquals(runs()[0].status, "awaiting-approval");
+});
+
+test("dispatch-delivery-graph: a side-effecting graph WITH approve dispatches (202 running), token derived server-side", async () => {
+  const { app, started, runs } = makeApp();
+  const res = await call(app, { graphJson: SIDE_EFFECTING, approve: true });
+  assertEquals(res.status, 202);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.status, "running");
+  assertEquals(res.body.sideEffecting, true);
+  assertEquals(started.length, 1);
+  assertEquals(runs()[0].status, "running");
+});
+
+test("dispatch-delivery-graph: re-dispatch of a running graph short-circuits (alreadyRunning), no second launch", async () => {
+  const { app, started } = makeApp();
+  await call(app, { graphJson: HUMAN_ONLY });
+  const res = await call(app, { graphJson: HUMAN_ONLY });
+  assertEquals(res.status, 202);
+  assertEquals(res.body.alreadyRunning, true);
+  assertEquals(started.length, 1);
+});
+
+test("dispatch-delivery-graph: a graph that fails validation → 400 carries the start door's structured `errors` array, not just a summary banner", async () => {
+  const { app, started } = makeApp();
+  const res = await call(app, { graphJson: JSON.stringify({ name: "empty", nodes: [] }) });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  // The structured, path-qualified errors from startDeliveryGraph must survive the adapter's re-shape.
+  assert(Array.isArray(res.body.errors) && res.body.errors.length > 0);
+  for (const e of res.body.errors) {
+    assert(typeof e.path === "string" && typeof e.message === "string");
+  }
+  // And the human banner is still derived from those errors.
+  assert(typeof res.body.error === "string" && res.body.error.length > 0);
+  assertEquals(started.length, 0);
+});

package/operations/dispatchDeliveryGraph.ts

@@ -0,0 +1,113 @@
+// POST /app/api/actions/delivery-graph/dispatch → operationId `dispatchDeliveryGraph` (issue #386,
+// ADR 0005 slice S5). The human-facing UI JSON-paste DISPATCH ingress: the Delivery Graphs page's
+// "Dispatch" action posts the operator's pasted delivery-graph as a raw JSON STRING plus an explicit
+// `approve` flag; this door parses it (`parseDeliveryGraphText`) and DELEGATES to the SAME gated,
+// idempotent `startDeliveryGraph` handler the agent-facing / REST paths use. There is deliberately NO
+// parallel dispatch path — this is a thin UI text adapter onto the ONE contract (S5's stated "UI
+// JSON-paste" ingress that S5 named but did not build).
+//
+//   • APPROVAL. When the operator ticks `approve` (having reviewed the preview), the door derives the
+//     graph's content digest via the SAME pure compiler `startDeliveryGraph` uses and presents it as
+//     the `approvalToken`, so a side-effecting graph dispatches. Without `approve`, a side-effecting
+//     graph is PARKED at approval by the start door (a 400 whose `awaiting-approval` run shows in the
+//     in-flight grid) and a non-side-effecting graph dispatches straight away.
+//   • The start door owns idempotency, the durable run row, and the at-most-once launch fence — this
+//     adapter adds nothing to that; it only parses the paste and surfaces a human `error` banner.
+
+import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
+import { parseDeliveryGraphText } from "../app/deliveryGraphText.ts";
+import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
+import type { DeliveryCompileError, DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+import startDeliveryGraph from "./startDeliveryGraph.ts";
+
+export default defineOperation("dispatchDeliveryGraph", async (input, app) => {
+  const body = input.body;
+  const parsed = parseDeliveryGraphText(body);
+  if (!parsed.ok) {
+    app.log.warn("dispatch-delivery-graph rejected: parse", { message: parsed.error });
+    return { status: 400, body: { ok: false, error: parsed.error } };
+  }
+  const approve = body?.approve === true;
+  const idemRaw = typeof body?.idempotencyKey === "string" ? body.idempotencyKey.trim() : "";
+  const idempotencyKey = idemRaw !== "" ? idemRaw : undefined;
+
+  // When the operator approves, derive the graph's content digest (the approval token) via the SAME
+  // pure compiler the start door uses, so a side-effecting graph they reviewed in the preview
+  // dispatches. A compile failure here surfaces as a clean 400 rather than reaching the start door.
+  let approvalToken: string | undefined;
+  if (approve) {
+    const compiled = compileDeliveryGraph(parsed.graph);
+    if (!compiled.ok) {
+      app.log.warn("dispatch-delivery-graph rejected: compile", { errors: compiled.errors.length });
+      return {
+        status: 400,
+        body: {
+          ok: false,
+          error: `graph failed validation: ${compiled.errors.length} error(s)`,
+          errors: compiled.errors,
+        },
+      };
+    }
+    approvalToken = deliveryGraphDigest(compiled.bpmn);
+  }
+
+  const startBody: Record<string, unknown> = { graph: parsed.graph };
+  if (approvalToken !== undefined) startBody.approvalToken = approvalToken;
+  if (idempotencyKey !== undefined) startBody.idempotencyKey = idempotencyKey;
+
+  // Delegate to the ONE dispatch contract — the exact `startDeliveryGraph` handler, no re-implementation.
+  // The parsed graph is `unknown` (the paste is runtime-validated inside the door), so the handler's
+  // typed input signature is bridged here; nothing re-implements dispatch.
+  // biome-ignore lint/plugin: bridging the runtime-validated paste onto the start door's typed input; the door owns validation.
+  const delegate = startDeliveryGraph as (
+    i: { req: unknown; params: unknown; query: unknown; body: unknown },
+    a: typeof app,
+  ) => Promise<{ status?: number; body?: Record<string, unknown> } | undefined>;
+  const res = await delegate(
+    { req: input.req, params: input.params, query: input.query, body: startBody },
+    app,
+  );
+  const resBody: Record<string, unknown> = res?.body ?? {};
+  const status = res?.status ?? 202;
+
+  // Re-shape the start door's result onto this ingress contract by narrowing each field — no assertions.
+  const outBody: DeliveryGraphTextResult = { ok: resBody.ok === true };
+  if (typeof resBody.status === "string") outBody.status = resBody.status;
+  if (typeof resBody.runKey === "string") outBody.runKey = resBody.runKey;
+  if (typeof resBody.digest === "string") outBody.digest = resBody.digest;
+  if (typeof resBody.sideEffecting === "boolean") outBody.sideEffecting = resBody.sideEffecting;
+  if (typeof resBody.alreadyRunning === "boolean") outBody.alreadyRunning = resBody.alreadyRunning;
+  if (typeof resBody.processInstanceKey === "string") outBody.processInstanceKey = resBody.processInstanceKey;
+  if (typeof resBody.processDefinitionId === "string") outBody.processDefinitionId = resBody.processDefinitionId;
+  if (typeof resBody.approvalToken === "string") outBody.approvalToken = resBody.approvalToken;
+  if (typeof resBody.message === "string") outBody.message = resBody.message;
+
+  // Carry through the start door's path-qualified validation/compile `errors` so callers/UI keep the
+  // structured detail (not just the summary banner). Narrow each entry to the wire pair — no assertions.
+  if (Array.isArray(resBody.errors)) {
+    const errors: DeliveryCompileError[] = [];
+    for (const e of resBody.errors) {
+      if (
+        typeof e === "object" &&
+        e !== null &&
+        "path" in e &&
+        "message" in e &&
+        typeof e.path === "string" &&
+        typeof e.message === "string"
+      ) {
+        errors.push({ path: e.path, message: e.message });
+      }
+    }
+    if (errors.length > 0) outBody.errors = errors;
+  }
+
+  // Surface a human error banner for the page on a refusal (parked-at-approval / validation).
+  if (status >= 400 && typeof outBody.error !== "string") {
+    if (typeof resBody.error === "string") outBody.error = resBody.error;
+    else if (typeof resBody.message === "string") outBody.error = resBody.message;
+    else if (outBody.errors !== undefined) outBody.error = `graph failed validation: ${outBody.errors.length} error(s)`;
+    else outBody.error = "dispatch was refused";
+  }
+  return { status, body: outBody };
+});

package/operations/getAgentInstructions.test.ts

@@ -50,6 +50,28 @@ test("the guide covers every capability the endpoint promises", async () => {
   assert(md.includes("nanobpm/nano-workforce"), "covers raising issues/PRs against the repo");
 });
 
+test("the guide documents the delivery-graph surface (ADR 0005)", async () => {
+  const md = ((await handler(input(), app)) as any).body.instructions as string;
+  // The two doors, with their exact action paths.
+  assert(md.includes("compile-delivery-graph"), "documents the pure compile door");
+  assert(md.includes("start/delivery-graph"), "documents the gated dispatch door");
+  // The closed node vocabulary: assert the exact config snippet for each of the four kinds,
+  // so the test fails if §9's node-kind table is removed or reworded — not merely if the bare
+  // words "agent"/"wait"/"human"/"connector" appear anywhere else in the guide.
+  assert(md.includes("agent: { jobType, prompt? }"), "documents the agent node config");
+  assert(md.includes("wait: <ReadinessProbe>"), "documents the wait node config");
+  assert(md.includes("human?: { formKey?, prompt? }"), "documents the human node config");
+  assert(md.includes("connector: { target, dedupeKey?, payload? }"), "documents the connector node config");
+  // The fact-edge syntax: an edge is `{ from, to }` and `from` may be a qualified `<nodeId>.<fact>`.
+  assert(md.includes("each edge is `{ from, to }`"), "documents the edge shape");
+  assert(md.includes("qualified `<nodeId>.<fact>`"), "documents the qualified fact-edge syntax");
+  // The approval gate + idempotency of the start door.
+  assert(md.includes("approvalToken"), "documents the approval gate");
+  assert(md.includes("idempotencyKey"), "documents idempotency");
+  // The worked example: a human emit node handing a version to a downstream edge.
+  assert(md.includes("manual-publish.publishedVersion"), "includes the worked example's human-emit fact edge");
+});
+
 test("examples are keyed to the request's control-API base and leave no placeholders", async () => {
   const forwarded = input({ host: "wf.example.com", "x-forwarded-proto": "https" });
   const md = ((await handler(forwarded, app)) as any).body.instructions as string;

package/operations/previewDeliveryGraph.test.ts

@@ -0,0 +1,74 @@
+// Tests for the POST /app/api/actions/delivery-graph/preview operation `previewDeliveryGraph`
+// (issue #386, ADR 0005 slice S1) — the human-facing UI JSON-paste PREVIEW ingress. It parses the
+// operator's pasted JSON STRING and runs the SAME pure `compileDeliveryGraph` compiler the agent door
+// uses, mapping the result onto a compact summary (200) or a human `error` + path-qualified `errors`
+// (400). It is PURE — no data layer, no dispatch — so it mirrors the compile door's test harness.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./previewDeliveryGraph.ts";
+
+const app = { log: noopLog() } as unknown as AppApi;
+
+async function call(body: unknown) {
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+const GOOD = JSON.stringify({
+  name: "runbook",
+  nodes: [
+    { id: "a", kind: "agent", agent: { jobType: "senior:feature" } },
+    { id: "b", kind: "human", human: { prompt: "do X" } },
+  ],
+  edges: [{ from: "a", to: "b" }],
+});
+
+test("preview-delivery-graph: a pasted well-formed graph → 200 summary with digest + counts", async () => {
+  const res = await call({ graphJson: GOOD });
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assert(typeof res.body.digest === "string" && res.body.digest.length > 0);
+  assertEquals(res.body.nodeCount, 2);
+  assertEquals(res.body.humanNodeCount, 1);
+  assertEquals(res.body.sideEffectCount, 1);
+  assertEquals(res.body.sideEffecting, true);
+  assert(typeof res.body.diagram === "string" && res.body.diagram.length > 0);
+  assertEquals(res.body.title, "runbook");
+});
+
+test("preview-delivery-graph: is PURE — repeated previews return the identical digest", async () => {
+  const a = await call({ graphJson: GOOD });
+  const b = await call({ graphJson: GOOD });
+  assertEquals(a.body.digest, b.body.digest);
+});
+
+test("preview-delivery-graph: text that is not valid JSON → 400 with a human error", async () => {
+  const res = await call({ graphJson: "{ not json" });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  assert(typeof res.body.error === "string" && res.body.error.includes("not valid JSON"));
+});
+
+test("preview-delivery-graph: a blank paste → 400, never a 500", async () => {
+  const res = await call({ graphJson: "   " });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  assert(typeof res.body.error === "string" && res.body.error.length > 0);
+});
+
+test("preview-delivery-graph: a valid-JSON but malformed graph → 400 with path-qualified errors", async () => {
+  const res = await call({
+    graphJson: JSON.stringify({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }], edges: [{ from: "a", to: "ghost" }] }),
+  });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  assert(Array.isArray(res.body.errors) && res.body.errors.length > 0);
+  assert(res.body.errors.every((e: { path: string; message: string }) => typeof e.path === "string"));
+});
+
+test("preview-delivery-graph: a pasted JSON array (not an object) → 400", async () => {
+  const res = await call({ graphJson: "[]" });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+});

package/operations/previewDeliveryGraph.ts

@@ -0,0 +1,59 @@
+// POST /app/api/actions/delivery-graph/preview → operationId `previewDeliveryGraph` (issue #386,
+// ADR 0005 slice S1). The human-facing UI JSON-paste PREVIEW ingress: the Delivery Graphs page's
+// "Preview" action posts the operator's pasted delivery-graph as a raw JSON STRING; this door parses
+// it (`parseDeliveryGraphText`) and runs the SAME pure `compileDeliveryGraph` compiler the agent-facing
+// door uses, returning a compact summary — the content `digest` (the approval token to dispatch with),
+// the node / human-stop / side-effect counts, and the mermaid `diagram`.
+//
+// It is PURE and side-effect-free (compile and start are separate doors — Decision 5/7): nothing is
+// deployed or dispatched, so an operator can Preview repeatedly while fixing the JSON. A blank/invalid
+// paste, or a graph that fails validation, is a 400 carrying a human `error` (and, for a compile
+// failure, the path-qualified `errors`). This is a thin UI adapter over the ONE compile contract, not
+// a parallel compile path.
+
+import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
+import { parseDeliveryGraphText } from "../app/deliveryGraphText.ts";
+import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+export default defineOperation("previewDeliveryGraph", async ({ body }, app) => {
+  const parsed = parseDeliveryGraphText(body);
+  if (!parsed.ok) {
+    app.log.warn("preview-delivery-graph rejected: parse", { message: parsed.error });
+    return { status: 400, body: { ok: false, error: parsed.error } };
+  }
+  const compiled = compileDeliveryGraph(parsed.graph);
+  if (!compiled.ok) {
+    app.log.warn("preview-delivery-graph rejected: compile", { errors: compiled.errors.length });
+    return {
+      status: 400,
+      body: {
+        ok: false,
+        error: `graph failed validation: ${compiled.errors.length} error(s)`,
+        errors: compiled.errors,
+      },
+    };
+  }
+  const digest = deliveryGraphDigest(compiled.bpmn);
+  app.log.info("preview-delivery-graph compiled", {
+    nodes: compiled.resolved.nodes.length,
+    humanNodes: compiled.humanNodes.length,
+    sideEffects: compiled.sideEffects.length,
+    digest,
+  });
+  return {
+    status: 200,
+    body: {
+      ok: true,
+      digest,
+      ...(typeof compiled.resolved.name === "string" && compiled.resolved.name !== ""
+        ? { title: compiled.resolved.name }
+        : {}),
+      sideEffecting: compiled.sideEffects.length > 0,
+      nodeCount: compiled.resolved.nodes.length,
+      humanNodeCount: compiled.humanNodes.length,
+      sideEffectCount: compiled.sideEffects.length,
+      diagram: compiled.diagram,
+    },
+  };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.117.0",
+  "version": "0.118.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/_nav.json

@@ -10,6 +10,7 @@
       { "label": "Convergence", "page": "home" },
       { "label": "Epics", "page": "epic" },
       { "label": "Feature", "page": "feature" },
+      { "label": "Delivery Graphs", "page": "delivery-graphs" },
       {
         "label": "Tasks",
         "page": "tasks",

package/pages/board.page.json

@@ -29,6 +29,10 @@
             "label": "Feature",
             "page": "feature"
           },
+          {
+            "label": "Delivery Graphs",
+            "page": "delivery-graphs"
+          },
           {
             "label": "Tasks",
             "page": "tasks",

package/pages/cockpit.page.json

@@ -29,6 +29,10 @@
             "label": "Feature",
             "page": "feature"
           },
+          {
+            "label": "Delivery Graphs",
+            "page": "delivery-graphs"
+          },
           {
             "label": "Tasks",
             "page": "tasks",

package/pages/delivery-graph-detail.page.json

@@ -0,0 +1,114 @@
+{
+  "schemaVersion": "1.0",
+  "title": "Delivery graph",
+  "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "title": "Nano Workforce",
+        "items": [
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Delivery Graphs",
+            "page": "delivery-graphs"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
+          }
+        ],
+        "sticky": true
+      }
+    },
+    {
+      "type": "text",
+      "id": "title",
+      "props": { "text": "Delivery graph {{param}}", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "props": {
+        "text": "This delivery graph's run aggregate \u2014 its lifecycle status, the derived phase (where it is parked, e.g. on a human node), its compiled shape (node / human-stop / side-effect counts), and the content digest that is its approval token. Follow the Status cell into the process explorer to watch the compiled process advance node-by-node and edge-by-edge (the engine owns per-node token state).",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "delivery-graph-run",
+      "props": {
+        "title": "Run",
+        "rowKey": "run_key",
+        "refreshMs": 5000,
+        "empty": "No delivery graph found for this key.",
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "delivery_graph_runs",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "run_key", "eqParam": true }]
+        },
+        "columns": [
+          { "field": "title", "template": "{{title}}", "header": "Graph", "subtitleField": "run_key", "truncate": true, "width": "30%" },
+          { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "phase", "header": "Phase", "truncate": true, "width": "30%" },
+          { "field": "node_count", "header": "Nodes" },
+          { "field": "human_node_count", "header": "Human" },
+          { "field": "side_effect_count", "header": "Side effects" },
+          { "field": "updated_at", "header": "Updated", "width": "9rem", "format": "datetime" }
+        ],
+        "detail": {
+          "fields": [
+            { "field": "process_definition_id", "label": "Process definition" },
+            { "field": "process_key", "label": "Process instance key" },
+            { "field": "digest", "label": "Content digest (approval token)" },
+            { "field": "side_effecting", "label": "Side-effecting (1 = requires approval)" },
+            { "field": "phase_node_id", "label": "Parked human node element" },
+            { "field": "created_at", "label": "Created" }
+          ]
+        }
+      }
+    }
+  ]
+}