@nanobpm/nano-workforce 0.123.1 → 0.124.0

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+# [0.124.0](https://github.com/nanobpm/nano-workforce/compare/v0.123.2...v0.124.0) (2026-08-23)
+
+
+### Bug Fixes
+
+* **cockpit:** anchor supply/transcript endpoints to import.meta.url so the shell finds the API ([#468](https://github.com/nanobpm/nano-workforce/issues/468)) ([4ff4b99](https://github.com/nanobpm/nano-workforce/commit/4ff4b99767b915902be19cdecd5973c1ce6efc4c)), closes [279/#280](https://github.com/nanobpm/nano-workforce/issues/280) [#467](https://github.com/nanobpm/nano-workforce/issues/467)
+* **migrations:** grandfather prefix 075 collision to unblock main + releases ([#471](https://github.com/nanobpm/nano-workforce/issues/471)) ([508194e](https://github.com/nanobpm/nano-workforce/commit/508194e7be0f58ba3f12d2b67d4d6212d243c609)), closes [#458](https://github.com/nanobpm/nano-workforce/issues/458) [460/#463](https://github.com/nanobpm/nano-workforce/issues/463) [#357](https://github.com/nanobpm/nano-workforce/issues/357) [#470](https://github.com/nanobpm/nano-workforce/issues/470)
+
+
+### Features
+
+* **delivery-graph:** make dispatch operator-only ([#460](https://github.com/nanobpm/nano-workforce/issues/460)) ([#463](https://github.com/nanobpm/nano-workforce/issues/463)) ([cd6d2b8](https://github.com/nanobpm/nano-workforce/commit/cd6d2b819b32c5c7daf047dbb6e077a26d4b09e6))
+
+## [0.123.2](https://github.com/nanobpm/nano-workforce/compare/v0.123.1...v0.123.2) (2026-08-22)
+
+
+### Bug Fixes
+
+* **merge:** make draft PRs a first-class not-landable verdict ([#454](https://github.com/nanobpm/nano-workforce/issues/454)) ([#455](https://github.com/nanobpm/nano-workforce/issues/455)) ([d684086](https://github.com/nanobpm/nano-workforce/commit/d684086748c840fe6a77fd7d86c5cdecbf8bfe2a))
+* **read-model:** derive feature attention badge from open user tasks, not sticky status ([#458](https://github.com/nanobpm/nano-workforce/issues/458)) ([496971d](https://github.com/nanobpm/nano-workforce/commit/496971dba95f19857d659e5a9d7fa56085d932fa)), closes [#439](https://github.com/nanobpm/nano-workforce/issues/439) [#448](https://github.com/nanobpm/nano-workforce/issues/448) [#422](https://github.com/nanobpm/nano-workforce/issues/422) [#422](https://github.com/nanobpm/nano-workforce/issues/422)
+* **tasks:** scan running delivery-graph runs in the typed-seam fallback so human gates surface without raw-REST ([#457](https://github.com/nanobpm/nano-workforce/issues/457)) ([9e82d37](https://github.com/nanobpm/nano-workforce/commit/9e82d37a101d532de447c6ca0bf64bd3d9a3bee7)), closes [#443](https://github.com/nanobpm/nano-workforce/issues/443) [#442](https://github.com/nanobpm/nano-workforce/issues/442)
+
 ## [0.123.1](https://github.com/nanobpm/nano-workforce/compare/v0.123.0...v0.123.1) (2026-08-22)
 
 

package/README.md

@@ -254,11 +254,15 @@ run an **arbitrary, heterogeneous, cross-repo, partly-human delivery graph** —
 the just-published version*. You author the graph as **JSON over a closed node vocabulary**
 (`agent` | `wait` | `human` | `connector`) — never BPMN or code — whose edges are
 **discovered facts** (`from: "<node>.<fact>"`). A deterministic compiler turns it into an
-engine-native process; a human approves the rendered preview before any side effect runs.
-
-Two doors: a **pure** `POST /app/api/actions/compile-delivery-graph` (validate + preview,
-side-effect-free — hammer it while drafting) and a **gated, idempotent**
-`POST /app/api/actions/start/delivery-graph` (approve → dispatch).
+engine-native process; a human previews the staged proposal and dispatches it from the
+cockpit before any side effect runs.
+
+Two doors — and the second is **operator-only** (issue #460): a
+`POST /app/api/actions/compile-delivery-graph` on the agent surface that validates + previews
+the graph and **stages** it as a proposal (the agent surface ends there — no run key or token
+comes back), and a `POST /app/api/actions/delivery-graph/dispatch` the **cockpit** uses to
+dispatch a staged proposal by its content `digest` (idempotent, at-most-once). There is no
+agent `start` door to replay — the human clicking Dispatch in the cockpit is the approval.
 
 The agent guide served at `GET /app/api/agent` documents the full vocabulary, both
 operation contracts, and a complete worked example — see §9 there, or point your coding

package/app/deliveryGraphDeploy.test.ts

@@ -0,0 +1,209 @@
+// End-to-end coverage that the delivery-graph compiler (ADR 0005) emits BPMN that is BOTH
+// EXECUTABLE and RENDERABLE — the two disjoint validity axes of the one BPMN in this system that is
+// generated at RUNTIME by raw string concatenation rather than authored (issue #451).
+//
+// The pure compiler tests (`deliveryGraphCompiler.test.ts`) assert only on the XML STRING SHAPE
+// (`includes(...)`, regex counts). A string-shape assert proves the text LOOKS right; it does NOT
+// prove it DEPLOYS — a mis-wired boundary event, a flow to a dropped element, a bad `ioMapping`, or a
+// `jobType` typo yields BPMN that passes every `includes()` and still fails `engine.deploy(xml)` with
+// a misleading "unknown target element" at the flow (the AGENTS.md "it parsed but didn't execute"
+// drift class). So here we DEPLOY the compiled graph through the real in-process WASM engine
+// (`@nanobpm/urban-testkit`) via the SAME S4 path the runner uses (`runDeliveryGraph`) and ADVANCE a
+// live instance to a terminal state — the exact deploy → instance → user-tasks → complete → terminal
+// path that otherwise only gets hand-verified against a live node.
+//
+// Renderability and executability are DISJOINT (a graph can lay out perfectly and still fail deploy,
+// and vice-versa), so `di coverage` guards the visual axis independently: every emitted flow node
+// carries a `bpmndi:BPMNShape` and every sequence flow a `bpmndi:BPMNEdge`, so a future node kind
+// cannot silently ship without a diagram (AGENTS.md: "BPMN Models need DI for rendering").
+import { test } from "node:test";
+import { createWasmEngineClient } from "@nanobpm/urban-testkit";
+import { assert, assertEquals } from "#test-assert";
+import { DELIVERY_CONNECTOR_TASK_TYPE } from "./deliveryConnector.ts";
+import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
+import { runDeliveryGraph } from "./deliveryRunner.ts";
+import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+
+/** A graph exercising the full node-kind matrix: `agent` (a named `senior:*` job), `wait` (the
+ *  `pr.readiness-probe` poll gate), `human` (a user task), and `connector` (the delivery-connector
+ *  delegate). This is the ADR's motivating release runbook. */
+const MATRIX_GRAPH: DeliveryGraph = {
+  name: "release runbook",
+  nodes: [
+    { id: "impl", kind: "agent", agent: { jobType: "senior:feature", prompt: "un-draft + merge #B" } },
+    { id: "watch", kind: "wait", wait: { kind: "pr", target: "owner/repo#42", match: { prState: "merged" } }, emits: [{ name: "mergedSha", type: "string" }] },
+    { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish" }, emits: [{ name: "resolvedArtifact", type: "artifact" }] },
+    { id: "consume", kind: "connector", connector: { target: "npm:install", dedupeKey: "consume-1" } },
+  ],
+  edges: [
+    { from: "impl", to: "watch" },
+    { from: "watch.mergedSha", to: "publish" },
+    { from: "publish.resolvedArtifact", to: "consume" },
+  ],
+};
+
+/** The generic completion payload for a delivery user task. Satisfies BOTH the `human` node's output
+ *  ioMapping (`value` → `humanEmitValue`, `resolvedArtifact` → `humanEmitArtifact`, `note` →
+ *  `humanNote`) and the escalation task's generic form (`value` required, `note`). */
+const HUMAN_PAYLOAD = { value: "done", note: "ok", resolvedArtifact: "@nanobpm/demo@1.0.0" };
+
+/** Upper bound on drive rounds — a terminal graph settles in a handful; the cap turns a wiring bug
+ *  (a node that never advances) into a loud failure instead of a hang. */
+const MAX_ROUNDS = 16;
+
+test("deploy+advance: a well-formed graph deploys through the real engine and every node kind advances to a COMPLETED instance", async () => {
+  const engine = await createWasmEngineClient();
+  try {
+    // Serve every service node's job so each node completes NORMALLY (no boundary timeout fires): the
+    // agent job, the readiness probe (return `ready: true` so the poll loop exits on its first pass),
+    // and the connector delegate.
+    await engine.registerWorker("senior:feature", async () => ({}));
+    await engine.registerWorker("pr.readiness-probe", async () => ({ ready: true, mergedSha: "deadbeefcafe" }));
+    await engine.registerWorker(DELIVERY_CONNECTOR_TASK_TYPE, async () => ({}));
+
+    const run = await runDeliveryGraph(engine, MATRIX_GRAPH);
+    assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
+    const key = run.handle.processInstanceKey;
+
+    // Drive to terminal: serve jobs (drain), then complete any parked human user task, repeat. No
+    // virtual-clock advance — the happy path stalls ONLY on the human node, never on a timer.
+    const humanTasks: string[] = [];
+    let state = "?";
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+      await engine.drain();
+      const [pi] = await engine.searchProcessInstances({ processInstanceKeys: [key] });
+      assert(pi, `no process instance snapshot for ${key} — searchProcessInstances returned empty`);
+      state = pi.state ?? "?";
+      if (state === "COMPLETED" || state === "TERMINATED") break;
+      const open = await engine.searchUserTasks({ processInstanceKey: key, state: "CREATED" });
+      assert(open.length > 0, `instance is ${state} with no open user task — a service node never advanced`);
+      for (const t of open) {
+        humanTasks.push(t.elementId ?? "?");
+        await engine.completeUserTask(t.userTaskKey, HUMAN_PAYLOAD);
+      }
+    }
+
+    assertEquals(state, "COMPLETED", "the deployed delivery graph must run to a COMPLETED instance");
+    // The ONE stop on the happy path is the `publish` human node; its compiled user-task element id is
+    // `delivery-human-task__<element>`. Assert we actually surfaced (and completed) it — proof the
+    // human node's user task deployed and is completable, not just that the instance ended.
+    assertEquals(humanTasks.length, 1, `expected exactly one human user task, saw ${JSON.stringify(humanTasks)}`);
+    assert(
+      humanTasks[0].startsWith("delivery-human-task__") && !humanTasks[0].endsWith("__esc"),
+      `expected a human node task, saw ${humanTasks[0]}`,
+    );
+  } finally {
+    await engine.close();
+  }
+});
+
+test("deploy+advance: a stalled service node escalates on its node-timeout boundary onto a human-completable task that advances the instance to COMPLETED", async () => {
+  const engine = await createWasmEngineClient();
+  try {
+    // A minimal agent → human graph. We deliberately register NO `senior:feature` worker, so the agent
+    // node stalls and MUST escalate on its `=nodeTimeout` boundary timer — the exact path a stuck node
+    // takes on a live fleet (and the one hand-verified against merlin).
+    const graph: DeliveryGraph = {
+      name: "escalation graph",
+      nodes: [
+        { id: "impl", kind: "agent", agent: { jobType: "senior:feature", prompt: "do it" } },
+        { id: "signoff", kind: "human", human: { prompt: "sign off" } },
+      ],
+      edges: [{ from: "impl", to: "signoff" }],
+    };
+    // Short node timeout so the boundary fires within one virtual-clock advance; a long SLA so the
+    // human node's own escalation boundary never fires during the drive.
+    const run = await runDeliveryGraph(engine, graph, { nodeTimeout: "PT1M", escalationSlaTimeout: "PT1H" });
+    assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
+    const key = run.handle.processInstanceKey;
+
+    // The stalled agent has NOT escalated yet: no user task before the timeout.
+    await engine.drain();
+    let open = await engine.searchUserTasks({ processInstanceKey: key, state: "CREATED" });
+    assertEquals(open.length, 0, "the stalled agent must not surface a task before its node timeout");
+
+    // Fire the PT1M node-timeout boundary → the agent node escalates onto its `__esc` user task.
+    await engine.advanceTime(60_000);
+    open = await engine.searchUserTasks({ processInstanceKey: key, state: "CREATED" });
+    assertEquals(open.length, 1, "the node timeout must surface exactly one escalation user task");
+    assert(open[0].elementId?.endsWith("__esc"), `expected an __esc escalation task, saw ${open[0].elementId}`);
+
+    // Complete the escalation task → the agent node ends → the flow reaches the human node → complete
+    // that → terminal.
+    const completed: string[] = [];
+    let state = "?";
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+      await engine.drain();
+      const [pi] = await engine.searchProcessInstances({ processInstanceKeys: [key] });
+      assert(pi, `no process instance snapshot for ${key} — searchProcessInstances returned empty`);
+      state = pi.state ?? "?";
+      if (state === "COMPLETED" || state === "TERMINATED") break;
+      const tasks = await engine.searchUserTasks({ processInstanceKey: key, state: "CREATED" });
+      assert(tasks.length > 0, `instance is ${state} with no open task after escalation — a node never advanced`);
+      for (const t of tasks) {
+        completed.push(t.elementId ?? "?");
+        await engine.completeUserTask(t.userTaskKey, HUMAN_PAYLOAD);
+      }
+    }
+
+    assertEquals(state, "COMPLETED", "completing the escalation + human task must run the graph to COMPLETED");
+    assert(
+      completed.some((id) => id.endsWith("__esc")),
+      `the escalation task must have been driven, saw ${JSON.stringify(completed)}`,
+    );
+    assert(
+      completed.some((id) => id.startsWith("delivery-human-task__") && !id.endsWith("__esc")),
+      `the downstream human task must have been driven, saw ${JSON.stringify(completed)}`,
+    );
+  } finally {
+    await engine.close();
+  }
+});
+
+/** Every BPMN flow-node tag that must carry a `bpmndi:BPMNShape` to be rendered by human tooling. */
+const FLOW_NODE_TAGS = [
+  "startEvent",
+  "endEvent",
+  "task",
+  "serviceTask",
+  "userTask",
+  "subProcess",
+  "exclusiveGateway",
+  "parallelGateway",
+  "inclusiveGateway",
+  "boundaryEvent",
+  "intermediateCatchEvent",
+  "intermediateThrowEvent",
+  "callActivity",
+].join("|");
+
+/** Extract every `id="…"` for the given opening-tag alternation from the BPMN source. */
+function idsForTags(bpmn: string, tagAlternation: string): string[] {
+  const re = new RegExp(`<bpmn:(?:${tagAlternation})\\b[^>]*\\bid="([^"]+)"`, "g");
+  return [...bpmn.matchAll(re)].map((m) => m[1]);
+}
+
+test("di coverage: every compiled flow node carries a BPMNShape and every sequence flow a BPMNEdge", async () => {
+  const r = await compileDeliveryGraph(MATRIX_GRAPH);
+  assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
+  const bpmn = r.bpmn;
+
+  const flowNodeIds = idsForTags(bpmn, FLOW_NODE_TAGS);
+  assert(flowNodeIds.length > 0, "expected the compiled graph to contain flow nodes");
+  const shapeless = flowNodeIds.filter(
+    (id) => !new RegExp(`<bpmndi:BPMNShape[^>]*bpmnElement="${escapeRe(id)}"`).test(bpmn),
+  );
+  assertEquals(shapeless, [], `every flow node must have a BPMNShape; missing: ${JSON.stringify(shapeless)}`);
+
+  const sequenceFlowIds = idsForTags(bpmn, "sequenceFlow");
+  assert(sequenceFlowIds.length > 0, "expected the compiled graph to contain sequence flows");
+  const edgeless = sequenceFlowIds.filter(
+    (id) => !new RegExp(`<bpmndi:BPMNEdge[^>]*bpmnElement="${escapeRe(id)}"`).test(bpmn),
+  );
+  assertEquals(edgeless, [], `every sequence flow must have a BPMNEdge; missing: ${JSON.stringify(edgeless)}`);
+});
+
+/** Escape a BPMN element id for embedding in a RegExp (ids can contain `.` from fact-qualified names). */
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/app/deliveryGraphDispatch.test.ts

@@ -0,0 +1,143 @@
+// Unit coverage for `dispatchDeliveryGraphRun` (app/deliveryGraphDispatch.ts) — the retained
+// delivery-graph DISPATCH core extracted out of the removed agent `start` door (ADR 0005 Decision 7,
+// issue #460). It has NO approval gate: the authorization lives in the fact that only the cockpit
+// dispatch seam reaches this code (never the agent surface). What it DOES keep is the durable
+// at-most-once launch fence + idempotency short-circuit, so a double-dispatch never double-launches a
+// graph's side effects. These tests drive it against an in-memory app/data/engine faithful to the run
+// aggregate's PRIMARY KEY fence and the guarded raw UPDATE the claim issues.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { dispatchDeliveryGraphRun } from "./deliveryGraphDispatch.ts";
+import { noopLog } from "../test/log.ts";
+
+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))),
+      all: () => Promise.resolve([...rows]),
+      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") ?? [] };
+}
+
+const HUMAN_ONLY = {
+  name: "manual gate",
+  nodes: [{ id: "ack", kind: "human", human: { prompt: "click done" } }],
+};
+const SIDE_EFFECTING = {
+  name: "release runbook",
+  nodes: [
+    { id: "open-b", kind: "agent", agent: { jobType: "senior:demo", prompt: "merge #B" } },
+    { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish" } },
+  ],
+  edges: [{ from: "open-b", to: "publish" }],
+};
+
+test("dispatchDeliveryGraphRun: a human-only graph launches straight away (running), one engine instance", async () => {
+  const { app, started, runs } = makeApp();
+  const res = await dispatchDeliveryGraphRun(app, HUMAN_ONLY);
+  assertEquals(res.ok, true);
+  if (!res.ok) return;
+  assertEquals(res.status, "running");
+  assertEquals(res.alreadyRunning, false);
+  assertEquals(res.sideEffecting, false);
+  assertEquals(started.length, 1);
+  assertEquals(runs()[0].status, "running");
+});
+
+test("dispatchDeliveryGraphRun: a side-effecting graph dispatches with NO approval token — the operator seam IS the approval", async () => {
+  const { app, started, runs } = makeApp();
+  const res = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING);
+  assertEquals(res.ok, true);
+  if (!res.ok) return;
+  assertEquals(res.status, "running");
+  assertEquals(res.sideEffecting, true);
+  assertEquals(started.length, 1);
+  assertEquals(runs()[0].status, "running");
+});
+
+test("dispatchDeliveryGraphRun: a re-dispatch of a still-running run short-circuits (alreadyRunning) — the side effect launches at most once", async () => {
+  const { app, started } = makeApp();
+  const first = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING);
+  assert(first.ok);
+  const second = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING);
+  assertEquals(second.ok, true);
+  if (!second.ok) return;
+  assertEquals(second.alreadyRunning, true);
+  assertEquals(started.length, 1); // never a second launch
+});
+
+test("dispatchDeliveryGraphRun: an explicit idempotency key forces a distinct run row", async () => {
+  const { app, started } = makeApp();
+  await dispatchDeliveryGraphRun(app, HUMAN_ONLY);
+  await dispatchDeliveryGraphRun(app, HUMAN_ONLY, { runKey: "second-run" });
+  assertEquals(started.length, 2);
+});
+
+test("dispatchDeliveryGraphRun: a malformed graph → ok:false with path-qualified errors, nothing launched", async () => {
+  const { app, started } = makeApp();
+  const res = await dispatchDeliveryGraphRun(app, { name: "empty", nodes: [] });
+  assertEquals(res.ok, false);
+  if (res.ok) return;
+  assert(Array.isArray(res.errors) && res.errors.length > 0);
+  for (const e of res.errors) {
+    assert(typeof e.path === "string" && typeof e.message === "string");
+  }
+  assertEquals(started.length, 0);
+});

package/app/deliveryGraphDispatch.ts

@@ -0,0 +1,168 @@
+// app/deliveryGraphDispatch.ts — the delivery-graph DISPATCH core (ADR 0005 Decision 7, issue #460).
+// This is the retained run-launch logic (compile → content-address → idempotent at-most-once claim →
+// deploy+start the S4 runner → stamp the instance) extracted out of the removed agent `start` door so
+// it is invoked ONLY from the cockpit dispatch action — never an agent-callable operation.
+//
+// The old `start` door gated dispatch on a REPLAYABLE `approvalToken` (the content digest handed back
+// to the same caller), which let any holder of the API credential self-approve. Under issue #460 the
+// human clicking Dispatch in the cockpit IS the approval — so there is NO approval gate here; the
+// authorization lives in the fact that only the cockpit dispatch seam reaches this code, not the agent
+// surface. What IS retained is the durable at-most-once launch fence (`claimRunForLaunch`) and the
+// idempotency short-circuit, so a double-click or a re-dispatch never double-launches a graph's side
+// effects.
+
+import type { AppApi } from "@nanobpm/urban";
+import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+import { validateDeliveryGraph } from "./deliveryGraph.ts";
+import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
+import {
+  buildDeliveryGraphRunRow,
+  buildHumanLabels,
+  claimRunForLaunch,
+  computeRunKey,
+  DELIVERY_PHASE,
+  deliveryGraphRuns,
+} from "./deliveryGraphRun.ts";
+import { deliveryGraphDigest, runDeliveryGraph } from "./deliveryRunner.ts";
+
+/** The outcome of a dispatch attempt — mirrors the retained run lifecycle. `ok:false` carries the
+ * path-qualified compile/validation errors (a staged graph should always recompile, but a corrupt
+ * stored graph is refused cleanly rather than throwing). */
+export type DispatchDeliveryGraphResult =
+  | {
+      ok: true;
+      status: "running";
+      runKey: string;
+      digest: string;
+      sideEffecting: boolean;
+      alreadyRunning: boolean;
+      processInstanceKey?: string;
+      processDefinitionId?: string;
+    }
+  | { ok: false; errors: { path: string; message: string }[] };
+
+/** Dispatch a delivery graph as a running engine-native process — the operator action. Re-validates
+ * and re-compiles the (already-staged) graph to derive its content digest + run-row shape, then
+ * launches it through the durable at-most-once fence. Idempotent: a re-dispatch of an already-running
+ * run short-circuits with `alreadyRunning` instead of double-launching. */
+export async function dispatchDeliveryGraphRun(
+  app: Pick<AppApi, "data" | "engine" | "log">,
+  graph: unknown,
+  options: { runKey?: string | null; title?: string | null } = {},
+): Promise<DispatchDeliveryGraphResult> {
+  const validationErrors = validateDeliveryGraph(graph);
+  if (validationErrors.length > 0) {
+    return { ok: false, errors: validationErrors };
+  }
+  // The graph passed the semantic validator above, so it is safe to narrow to the typed contract.
+  // biome-ignore lint/plugin: validated external body narrowed to its contract after validateDeliveryGraph
+  const typedGraph = graph as DeliveryGraph;
+  const compiled = await compileDeliveryGraph(typedGraph);
+  if (!compiled.ok) {
+    return { ok: false, errors: compiled.errors };
+  }
+
+  const digest = deliveryGraphDigest(compiled.bpmn);
+  const runKey = computeRunKey(options.runKey, digest);
+  const sideEffecting = compiled.sideEffects.length > 0;
+  const explicitTitle = typeof options.title === "string" && options.title.trim() !== "" ? options.title.trim() : "";
+  const graphName = typeof typedGraph.name === "string" && typedGraph.name.trim() !== "" ? typedGraph.name.trim() : "";
+  const title = explicitTitle || graphName || runKey;
+  const runs = deliveryGraphRuns(app.data);
+
+  // Idempotency short-circuit — a re-dispatch onto a still-running run does NOT double-launch.
+  const existing = await runs.get(runKey);
+  if (existing && existing.status === "running") {
+    app.log.info("dispatch-delivery-graph short-circuit: already running", { runKey });
+    return {
+      ok: true,
+      status: "running",
+      runKey,
+      digest: existing.digest,
+      sideEffecting: existing.side_effecting === 1,
+      alreadyRunning: true,
+      processInstanceKey: existing.process_key ?? undefined,
+      processDefinitionId: existing.process_definition_id ?? undefined,
+    };
+  }
+
+  const rowBase = {
+    runKey,
+    digest,
+    sideEffecting,
+    nodeCount: compiled.resolved.nodes.length,
+    humanNodeCount: compiled.humanNodes.length,
+    sideEffectCount: compiled.sideEffects.length,
+    title,
+    humanLabels: buildHumanLabels(compiled),
+    createdAt: existing?.created_at,
+  };
+
+  // Claim the run durably BEFORE the side effect (the at-most-once dispatch fence). A losing racer
+  // never reaches `runDeliveryGraph` — it re-reads the winner's row and short-circuits.
+  const claim = buildDeliveryGraphRunRow({ ...rowBase, status: "running", phase: DELIVERY_PHASE.RUNNING, processKey: null });
+  const wonClaim = await claimRunForLaunch(app.data, Boolean(existing), claim);
+  if (!wonClaim) {
+    const won = await runs.get(runKey);
+    app.log.info("dispatch-delivery-graph short-circuit: launch claim raced a concurrent dispatch", { runKey });
+    return {
+      ok: true,
+      status: "running",
+      runKey,
+      digest: won?.digest ?? digest,
+      sideEffecting: won ? won.side_effecting === 1 : sideEffecting,
+      alreadyRunning: true,
+      processInstanceKey: won?.process_key ?? undefined,
+      processDefinitionId: won?.process_definition_id ?? undefined,
+    };
+  }
+  if (existing) {
+    const { run_key, created_at, ...patch } = claim;
+    await runs.update(runKey, patch);
+  }
+
+  // Launch — deploy + start the compiled definition. On ANY launch failure flip the claimed row to
+  // `failed` so no null-process_key `running` row is ever stranded.
+  const markClaimFailed = async () => {
+    const failed = buildDeliveryGraphRunRow({ ...rowBase, status: "failed", phase: DELIVERY_PHASE.FAILED, processKey: null });
+    const { run_key, created_at, ...patch } = failed;
+    await runs.update(runKey, patch);
+  };
+  let launched: Awaited<ReturnType<typeof runDeliveryGraph>>;
+  try {
+    launched = await runDeliveryGraph(app.engine, typedGraph, { runKey });
+  } catch (err) {
+    await markClaimFailed();
+    app.log.error("dispatch-delivery-graph launch threw", { runKey });
+    throw err;
+  }
+  if (!launched.ok) {
+    await markClaimFailed();
+    app.log.error("dispatch-delivery-graph launch failed", { runKey, count: launched.errors.length });
+    return { ok: false, errors: launched.errors };
+  }
+
+  // Stamp the started instance key onto the claimed row.
+  {
+    const running = buildDeliveryGraphRunRow({
+      ...rowBase,
+      status: "running",
+      phase: DELIVERY_PHASE.RUNNING,
+      processKey: launched.handle.processInstanceKey,
+      processDefinitionId: launched.handle.processDefinitionId,
+    });
+    const { run_key, created_at, ...patch } = running;
+    await runs.update(runKey, patch);
+  }
+  app.log.info("delivery graph dispatched", { runKey, processInstanceKey: launched.handle.processInstanceKey });
+  return {
+    ok: true,
+    status: "running",
+    runKey,
+    digest,
+    sideEffecting,
+    alreadyRunning: false,
+    processInstanceKey: launched.handle.processInstanceKey,
+    processDefinitionId: launched.handle.processDefinitionId,
+  };
+}