@nanobpm/nano-workforce 0.116.0 → 0.118.0

package/operations/startDeliveryGraph.integration.test.ts

@@ -0,0 +1,316 @@
+// Integration coverage for the S5 DISPATCH door (ADR 0005 Decision 7) driven through the operation
+// EDGE — `startDeliveryGraph` composing S0 validate → S1 compile → approval gate → S4 launch. The unit
+// tests in app/deliveryGraphRun.test.ts prove the pure decision helpers in isolation; this file proves
+// the COMPOSED behaviour at the door: each path maps to the correct HTTP status and the correct
+// durable-run / launch effect. It runs the real delegate against an in-memory app/data/engine — no
+// network, deterministic on a single run.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import startDeliveryGraph from "./startDeliveryGraph.ts";
+
+// ── in-memory app (data + engine) ────────────────────────────────────────────
+// A generic table over an array (the DataLayer surface the run aggregate uses: get/find/insert/update)
+// plus a fake engine recording each deploy + start so an accept path can assert exactly-once launch.
+function makeApp(opts: { failCreate?: boolean } = {}) {
+  const tables = new Map<string, Record<string, unknown>[]>();
+  const started: { processDefinitionId: string; variables?: Record<string, unknown> }[] = [];
+  const deployed: unknown[][] = [];
+  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>) => {
+        // Faithful to the durable table's PRIMARY KEY: a duplicate-key insert is rejected with the
+        // SQLite fence message `isUniqueConstraintFence` classifies, so the door's claim-before-launch
+        // fence is exercised the same way it is against the real store.
+        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,
+      // Faithful model of the guarded raw UPDATEs the door issues via the DataSource gateway, BOTH of
+      // which fence on `WHERE "run_key" = ? AND "status" <> 'running'`: the launch-claim compare-and-swap
+      // (`SET status=?,updated_at=?`) and the approval-park write (`SET process_key=?,…,updated_at=?`).
+      // Columns are parsed from the SQL so either statement is applied faithfully. Deferred to a microtask
+      // to model the real async DataSource — the guard-and-write is NOT visible synchronously at call
+      // time, so a concurrently-scheduled delegate can still read the row pre-flip and reach its OWN
+      // claim/park (the exact interleave that made the unfenced writes double-launch / clobber a claim).
+      // The single `status <> 'running'` guard then lets only the first writer win: a launched `running`
+      // row is never flipped back, and a losing claim matches zero rows (`changed: 0`).
+      open: () => ({
+        exec: (sql: string, params: unknown[]) =>
+          Promise.resolve().then(() => {
+            // `"col" = ?` matches every SET assignment plus the WHERE `"run_key" = ?` (the `<> 'running'`
+            // guard uses `<>`, not `=`, so it is excluded); the last param is therefore the run_key.
+            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: (res: unknown[]) => {
+        deployed.push(res);
+        return Promise.resolve([]);
+      },
+      createInstance: (req: { processDefinitionId: string; variables?: Record<string, unknown> }) => {
+        started.push(req);
+        if (opts.failCreate) return Promise.reject(new Error("engine unavailable"));
+        return Promise.resolve({ processInstanceKey: "PI-1" });
+      },
+    },
+    log: noopLog(),
+  } as unknown as AppApi;
+  return { app, started, deployed, runs: () => tables.get("delivery_graph_runs") ?? [] };
+}
+
+function input(body: unknown) {
+  return {
+    req: { method: "POST", path: "/", query: new URLSearchParams(), headers: new Headers(), text: async () => "" } as never,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+// A SIDE-EFFECTING graph (an `agent` node → approval required) and a NON-side-effecting one
+// (`human`-only → dispatches without approval).
+const SIDE_EFFECTING = {
+  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 = {
+  name: "manual gate",
+  nodes: [{ id: "ack", kind: "human", human: { prompt: "click done when the release is out" } }],
+};
+
+test("missing graph → 400, nothing launched", async () => {
+  const { app, started } = makeApp();
+  const res = (await startDeliveryGraph(input({}), app)) as { status: number; body: { ok: boolean } };
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  assertEquals(started.length, 0);
+});
+
+test("a malformed graph fails S0 validation → 400, nothing compiled or launched", async () => {
+  const { app, started } = makeApp();
+  // Duplicate node ids — a semantic error `validateDeliveryGraph` catches (shape alone is fine).
+  const dup = { nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }, { id: "a", kind: "agent", agent: { jobType: "j" } }] };
+  const res = (await startDeliveryGraph(input({ graph: dup }), app)) as { status: number; body: { ok: boolean; errors?: unknown[] } };
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  assertEquals(Array.isArray(res.body.errors), true);
+  assertEquals(started.length, 0);
+});
+
+test("a side-effecting graph WITHOUT approval is refused + PARKED at approval (400, awaiting-approval row, no launch)", async () => {
+  const { app, started, runs } = makeApp();
+  const res = (await startDeliveryGraph(input({ graph: SIDE_EFFECTING }), app)) as {
+    status: number;
+    body: { ok: boolean; status: string; approvalToken: string; sideEffecting: boolean };
+  };
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  assertEquals(res.body.status, "awaiting-approval");
+  assertEquals(res.body.sideEffecting, true);
+  assertEquals(typeof res.body.approvalToken, "string");
+  assertEquals(started.length, 0); // parked, never launched
+  // The parked run is durable + visible (cockpit reads this table).
+  assertEquals(runs().length, 1);
+  assertEquals(runs()[0]?.["status"], "awaiting-approval");
+});
+
+test("re-submitting the SAME side-effecting graph WITH its approval token dispatches (202, running, launched once)", async () => {
+  const { app, started, runs } = makeApp();
+  // First submit parks + hands back the token.
+  const parked = (await startDeliveryGraph(input({ graph: SIDE_EFFECTING }), app)) as { body: { approvalToken: string } };
+  const token = parked.body.approvalToken;
+  // Second submit approves → dispatch. The SAME run row transitions parked → running (not a new row).
+  const res = (await startDeliveryGraph(input({ graph: SIDE_EFFECTING, approvalToken: token }), app)) as {
+    status: number;
+    body: { ok: boolean; status: string; processInstanceKey?: string };
+  };
+  assertEquals(res.status, 202);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.status, "running");
+  assertEquals(res.body.processInstanceKey, "PI-1");
+  assertEquals(started.length, 1);
+  assertEquals(runs().length, 1); // still ONE row — approval updated it, did not duplicate
+  assertEquals(runs()[0]?.["status"], "running");
+});
+
+test("a non-side-effecting (human-only) graph dispatches WITHOUT approval (202, running)", async () => {
+  const { app, started } = makeApp();
+  const res = (await startDeliveryGraph(input({ graph: HUMAN_ONLY }), app)) as {
+    status: number;
+    body: { ok: boolean; status: string; sideEffecting: boolean };
+  };
+  assertEquals(res.status, 202);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.status, "running");
+  assertEquals(res.body.sideEffecting, false);
+  assertEquals(started.length, 1);
+});
+
+test("a duplicate submit of an already-running graph short-circuits — no second launch", async () => {
+  const { app, started } = makeApp();
+  await startDeliveryGraph(input({ graph: HUMAN_ONLY }), app); // launch #1
+  const res = (await startDeliveryGraph(input({ graph: HUMAN_ONLY }), app)) as {
+    status: number;
+    body: { alreadyRunning: boolean; status: string };
+  };
+  assertEquals(res.status, 202);
+  assertEquals(res.body.alreadyRunning, true);
+  assertEquals(res.body.status, "running");
+  assertEquals(started.length, 1); // still ONE launch — the re-POST did not double-launch
+});
+
+test("a caller idempotencyKey scopes the run — the same key short-circuits, a different key launches again", async () => {
+  const { app, started } = makeApp();
+  await startDeliveryGraph(input({ graph: HUMAN_ONLY, idempotencyKey: "run-1" }), app);
+  const same = (await startDeliveryGraph(input({ graph: HUMAN_ONLY, idempotencyKey: "run-1" }), app)) as { body: { alreadyRunning: boolean } };
+  assertEquals(same.body.alreadyRunning, true);
+  assertEquals(started.length, 1);
+  const other = (await startDeliveryGraph(input({ graph: HUMAN_ONLY, idempotencyKey: "run-2" }), app)) as { body: { status: string; runKey: string } };
+  assertEquals(other.body.status, "running");
+  assertEquals(other.body.runKey, "run-2");
+  assertEquals(started.length, 2); // a distinct key is a distinct run
+});
+
+test("two SIMULTANEOUS submits of the same graph launch it exactly ONCE — the loser hits the run_key fence and short-circuits, no double side effect", async () => {
+  const { app, started, runs } = makeApp();
+  // Fire both before awaiting either: both read `existing === null`, then race to claim the run_key.
+  // The claim-before-launch fence means the loser's insert collides on the PK and it NEVER launches.
+  const [a, b] = (await Promise.all([
+    startDeliveryGraph(input({ graph: HUMAN_ONLY }), app),
+    startDeliveryGraph(input({ graph: HUMAN_ONLY }), app),
+  ])) as { status: number; body: { ok: boolean; status: string; alreadyRunning: boolean } }[];
+  assertEquals(a.status, 202);
+  assertEquals(b.status, 202);
+  assertEquals(a.body.ok, true);
+  assertEquals(b.body.ok, true);
+  // Exactly ONE launch and ONE durable row — no double-dispatch of side effects, no duplicate row.
+  assertEquals(started.length, 1);
+  assertEquals(runs().length, 1);
+  assertEquals(runs()[0]?.["status"], "running");
+  // Exactly one racer is the short-circuited loser (alreadyRunning); the other is the fresh winner.
+  assertEquals([a, b].filter((r) => r.body.alreadyRunning === true).length, 1);
+});
+
+test("two SIMULTANEOUS APPROVED re-submits of an already-PARKED graph launch it exactly ONCE — the parked→running claim is a compare-and-swap, not an unfenced update", async () => {
+  const { app, started, runs } = makeApp();
+  // Park the side-effecting graph first (unapproved), then grab its approval token.
+  const parked = (await startDeliveryGraph(input({ graph: SIDE_EFFECTING }), app)) as { body: { approvalToken: string } };
+  const token = parked.body.approvalToken;
+  assertEquals(runs()[0]?.["status"], "awaiting-approval");
+  // Fire two APPROVED submits before awaiting either: both read `existing` as the SAME parked row.
+  // Without a fence on the parked→running transition both would `update` then both launch. The
+  // compare-and-swap (`WHERE status <> 'running'`) lets exactly one flip the row and launch.
+  const [a, b] = (await Promise.all([
+    startDeliveryGraph(input({ graph: SIDE_EFFECTING, approvalToken: token }), app),
+    startDeliveryGraph(input({ graph: SIDE_EFFECTING, approvalToken: token }), app),
+  ])) as { status: number; body: { ok: boolean; status: string; alreadyRunning: boolean } }[];
+  assertEquals(a.status, 202);
+  assertEquals(b.status, 202);
+  // Exactly ONE launch of the side-effecting graph and still ONE durable row (no double-dispatch).
+  assertEquals(started.length, 1);
+  assertEquals(runs().length, 1);
+  assertEquals(runs()[0]?.["status"], "running");
+  // Exactly one racer is the short-circuited loser (alreadyRunning); the other is the fresh winner.
+  assertEquals([a, b].filter((r) => r.body.alreadyRunning === true).length, 1);
+});
+
+test("an APPROVED launch racing a concurrent UNAPPROVED re-submit of an already-PARKED graph is NOT clobbered — the park write is fenced `WHERE status <> 'running'`, so the launched claim (and its process_key) survives", async () => {
+  const { app, started, runs } = makeApp();
+  // Park the side-effecting graph first (unapproved) + grab its token — both racers read THIS row.
+  const parked = (await startDeliveryGraph(input({ graph: SIDE_EFFECTING }), app)) as { body: { approvalToken: string } };
+  const token = parked.body.approvalToken;
+  assertEquals(runs()[0]?.["status"], "awaiting-approval");
+  // Fire an APPROVED submit (which claims → running → launches) SIMULTANEOUSLY with another UNAPPROVED
+  // submit (which re-parks). Both read `existing` as the parked row. A blind park `update` would flip
+  // the launched `running` claim back to `awaiting-approval` and null its process_key — breaking the
+  // at-most-once fence. The guarded park write refuses to touch a `running` row instead.
+  const [approved, unapproved] = (await Promise.all([
+    startDeliveryGraph(input({ graph: SIDE_EFFECTING, approvalToken: token }), app),
+    startDeliveryGraph(input({ graph: SIDE_EFFECTING }), app),
+  ])) as { status: number; body: { status: string } }[];
+  assertEquals(approved.status, 202);
+  assertEquals(approved.body.status, "running"); // the approved submit dispatched
+  assertEquals(unapproved.status, 400); // the unapproved submit is refused (needs approval)
+  // Exactly ONE launch and ONE durable row, still `running` with its instance key — NOT clobbered.
+  assertEquals(started.length, 1);
+  assertEquals(runs().length, 1);
+  assertEquals(runs()[0]?.["status"], "running");
+  assertEquals(runs()[0]?.["process_key"], "PI-1");
+});
+
+test("a launch failure rolls the claimed run to `failed` — no stranded null-process_key `running` row", async () => {
+  const { app, started, runs } = makeApp({ failCreate: true });
+  let threw = false;
+  try {
+    await startDeliveryGraph(input({ graph: HUMAN_ONLY }), app);
+  } catch {
+    threw = true; // a thrown engine error propagates (framework maps it to a 500) — but only after rollback
+  }
+  assertEquals(threw, true);
+  assertEquals(started.length, 1); // the launch was attempted once
+  // The claim was written, then rolled back to a TERMINAL `failed` — the reconciler/poller skip null-
+  // key rows, so leaving it `running` would strand it forever; `failed` lets it drop out cleanly.
+  assertEquals(runs().length, 1);
+  assertEquals(runs()[0]?.["status"], "failed");
+  assertEquals(runs()[0]?.["process_key"], null);
+});
+
+test("a reused idempotencyKey short-circuits with the RUNNING run's persisted digest/sideEffecting — not the new submission's", async () => {
+  const { app, started } = makeApp();
+  // Launch a human-only (non-side-effecting) run under an explicit key.
+  const first = (await startDeliveryGraph(input({ graph: HUMAN_ONLY, idempotencyKey: "shared" }), app)) as {
+    body: { digest: string; sideEffecting: boolean };
+  };
+  assertEquals(first.body.sideEffecting, false);
+  // Re-POST the SAME key with a DIFFERENT (side-effecting) graph. The response must describe the run
+  // that is actually running — the human-only one — not this mismatched submission.
+  const second = (await startDeliveryGraph(input({ graph: SIDE_EFFECTING, idempotencyKey: "shared" }), app)) as {
+    status: number;
+    body: { alreadyRunning: boolean; digest: string; sideEffecting: boolean };
+  };
+  assertEquals(second.status, 202);
+  assertEquals(second.body.alreadyRunning, true);
+  assertEquals(second.body.sideEffecting, false); // the RUNNING run's value, not the side-effecting resubmit's
+  assertEquals(second.body.digest, first.body.digest);
+  assertEquals(started.length, 1); // still one launch
+});

package/operations/startDeliveryGraph.ts

@@ -0,0 +1,222 @@
+// POST /app/api/actions/start/delivery-graph → operationId `startDeliveryGraph` (ADR 0005 slice S5,
+// Decision 7). The ONE gated dispatch door for a delivery graph: it turns an agent-authored
+// `DeliveryGraph` into a RUNNING engine-native process. Three ingress paths — an agent-ergonomic POST,
+// a raw REST call, and a UI JSON-paste — all hit this ONE contract.
+//
+// This is the OUTER action, deliberately distinct from S1's pure `compileDeliveryGraph`: compile and
+// start are SEPARATE operations (Decision 5/7), so there is NO `dryRun` flag here. The door composes
+// the already-merged slices — it re-validates via S0 (`validateDeliveryGraph`), compiles via S1
+// (`compileDeliveryGraph`), and launches via S4 (`runDeliveryGraph`) — and adds the two properties a
+// DISPATCH (unlike a pure compile) must have:
+//
+//   • APPROVAL (Decision 7). Because these graphs merge PRs and publish packages, a graph with any
+//     side-effecting node (`agent`/`connector`) dispatches ONLY when the caller presents the graph's
+//     content-addressed `approvalToken` (== the compiled `digest`) — an approval OF the rendered
+//     preview. A side-effecting graph submitted without it is REFUSED (400) and PARKED as an
+//     `awaiting-approval` run (visible in the cockpit), the response carrying the token to re-submit
+//     with. A graph with no side effects (only `wait`/`human`) needs no approval and dispatches.
+//   • IDEMPOTENCY. A run is keyed by `runKey` (a caller `idempotencyKey`, else the content `digest`);
+//     a re-POST of the same graph short-circuits an already-running run instead of double-launching —
+//     mirroring `startPlan`'s `alreadyRunning`.
+
+import { validateDeliveryGraph } from "../app/deliveryGraph.ts";
+import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
+import {
+  buildDeliveryGraphRunRow,
+  buildHumanLabels,
+  claimRunForLaunch,
+  computeRunKey,
+  DELIVERY_PHASE,
+  deliveryGraphRuns,
+  isDeliveryGraphApproved,
+  parkRunFencedAgainstLaunch,
+} from "../app/deliveryGraphRun.ts";
+import { deliveryGraphDigest, runDeliveryGraph } from "../app/deliveryRunner.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+export default defineOperation("startDeliveryGraph", async ({ body }, app) => {
+  // The runtime validates a well-formed body against openapi.yaml, but a directly-invoked delegate (or
+  // a missing body) leaves `body` undefined — guard so that becomes a 400, not a 500.
+  if (!body || typeof body !== "object" || !("graph" in body) || body.graph === null || typeof body.graph !== "object") {
+    app.log.warn("start-delivery-graph rejected: missing graph");
+    return { status: 400, body: { ok: false, errors: [{ path: "graph", message: "request body must carry a `graph`" }] } };
+  }
+  const graph = body.graph;
+  const approvalToken = "approvalToken" in body && typeof body.approvalToken === "string" ? body.approvalToken : null;
+  const idempotencyKey = "idempotencyKey" in body && typeof body.idempotencyKey === "string" ? body.idempotencyKey : null;
+
+  // 1) Re-validate via S0 (`validateDeliveryGraph`) for a clean 400 BEFORE compiling — the door
+  //    re-checks even though the compiler validates internally, so a malformed graph is refused at the
+  //    edge with path-qualified errors and nothing is compiled or launched.
+  const validationErrors = validateDeliveryGraph(graph);
+  if (validationErrors.length > 0) {
+    app.log.warn("start-delivery-graph rejected: validation", { count: validationErrors.length });
+    return { status: 400, body: { ok: false, errors: validationErrors } };
+  }
+
+  // 2) Compile via S1. This yields the deterministic BPMN (→ the content digest / approval token) plus
+  //    the graph's shape: its side effects (whether approval is required), human stops, and node count.
+  const compiled = compileDeliveryGraph(graph);
+  if (!compiled.ok) {
+    app.log.warn("start-delivery-graph rejected: compile", { count: compiled.errors.length });
+    return { status: 400, body: { ok: false, errors: compiled.errors } };
+  }
+
+  const digest = deliveryGraphDigest(compiled.bpmn);
+  const runKey = computeRunKey(idempotencyKey, digest);
+  const sideEffecting = compiled.sideEffects.length > 0;
+  const title = typeof graph.name === "string" && graph.name.trim() !== "" ? graph.name.trim() : runKey;
+  const runs = deliveryGraphRuns(app.data);
+
+  // 3) Idempotency short-circuit — a re-POST onto a run that is still in flight does NOT double-launch.
+  //    Only a `running` run short-circuits (`running` is neither terminal nor a parked-gate status): it
+  //    returns `alreadyRunning`. A terminal (`done`/`failed`/`abandoned`) run may re-run, and an
+  //    `awaiting-approval` run falls through to the approval gate below (this POST may now carry the
+  //    token). Mirrors `startPlan`.
+  const existing = await runs.get(runKey);
+  if (existing && existing.status === "running") {
+    app.log.info("start-delivery-graph short-circuit: already running", { runKey });
+    // Report the ACTUALLY-running run's persisted metadata, not this request's. If a caller reused the
+    // same `idempotencyKey` for a different graph, `digest`/`sideEffecting` derived from THIS submission
+    // would mislabel the run that is really in flight — echo the winner row instead.
+    return {
+      status: 202,
+      body: {
+        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,
+  };
+
+  // 4) Approval gate (Decision 7) — a side-effecting graph without a valid approval token is REFUSED
+  //    (400) and PARKED as an `awaiting-approval` run so it is visible in the cockpit; the response
+  //    carries the token to re-submit with. A non-side-effecting graph passes straight through.
+  if (!isDeliveryGraphApproved(sideEffecting, approvalToken, digest)) {
+    // Park through the launch fence — never overwrite a concurrently-launched `running` claim (a
+    // racing approved submit) back to `awaiting-approval`, which would break at-most-once dispatch.
+    await parkRunFencedAgainstLaunch(
+      app.data,
+      Boolean(existing),
+      buildDeliveryGraphRunRow({ ...rowBase, status: "awaiting-approval", phase: DELIVERY_PHASE.AWAITING_APPROVAL, processKey: null }),
+    );
+    app.log.info("start-delivery-graph parked: awaiting approval", { runKey, sideEffects: compiled.sideEffects.length });
+    return {
+      status: 400,
+      body: {
+        ok: false,
+        status: "awaiting-approval",
+        runKey,
+        digest,
+        sideEffecting,
+        approvalToken: digest,
+        message: `graph has ${compiled.sideEffects.length} side-effecting node(s); re-submit with approvalToken to dispatch`,
+      },
+    };
+  }
+
+  // 5) Claim the run durably BEFORE the side effect — mirrors `startPlan`, which writes the `plans`
+  //    row before `engine.createInstance`. `claimRunForLaunch` makes the launch AT-MOST-ONCE under
+  //    concurrent submits from EITHER starting state: a first launch is fenced by the `run_key` PK
+  //    (a racing insert loses the unique constraint), and a relaunch off a persisted row (an approved
+  //    parked row, or a re-run terminal row) is fenced by an atomic compare-and-swap that flips the
+  //    row to `running` only if it is not already `running`. The loser never reaches `runDeliveryGraph`
+  //    — it re-reads the winner's row and short-circuits as `alreadyRunning` instead of double-launching
+  //    a graph's side effects. The claimed row carries no `process_key` yet — like a freshly-inserted
+  //    `planning` plan it is a transient active row that `pollDeliveryGraphPhase` and the instanceTracking
+  //    reconciler skip until the instance key lands (both ignore null-key rows).
+  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("start-delivery-graph short-circuit: launch claim raced a concurrent submit", { runKey });
+    // Echo the winner row's persisted metadata (falling back to this request's only if the row
+    // somehow can't be re-read) so a reused idempotencyKey never reports the wrong run's digest.
+    return {
+      status: 202,
+      body: {
+        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,
+      },
+    };
+  }
+  // Won the claim. For a relaunch off a persisted row the guarded CAS flipped only `status`; write the
+  // run's full metadata now — we are the sole caller past the fence, so this update cannot race.
+  if (existing) {
+    const { run_key, created_at, ...patch } = claim;
+    await runs.update(runKey, patch);
+  }
+
+  // 6) Launch — deploy + start the compiled definition via the S4 runner. `runKey` scopes the run's
+  //    wait-gate keys so two runs of the same graph never cross-correlate. On ANY launch failure (a
+  //    thrown engine error OR the runner's `ok:false`) flip the claimed row to `failed` so no null-
+  //    process_key `running` row is ever stranded — the reconciler and poller both skip null-key rows,
+  //    so a stranded claim would otherwise never terminate — then surface the error.
+  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, graph, { runKey });
+  } catch (err) {
+    await markClaimFailed();
+    app.log.error("start-delivery-graph launch threw", { runKey });
+    throw err;
+  }
+  if (!launched.ok) {
+    await markClaimFailed();
+    app.log.error("start-delivery-graph launch failed", { runKey, count: launched.errors.length });
+    return { status: 400, body: { ok: false, errors: launched.errors } };
+  }
+  // 7) 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 {
+    status: 202,
+    body: {
+      ok: true,
+      status: "running",
+      runKey,
+      digest,
+      sideEffecting,
+      alreadyRunning: false,
+      processInstanceKey: launched.handle.processInstanceKey,
+      processDefinitionId: launched.handle.processDefinitionId,
+    },
+  };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.116.0",
+  "version": "0.118.0",
   "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",