@nanobpm/nano-workforce 0.117.0 → 0.118.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.118.0](https://github.com/nanobpm/nano-workforce/compare/v0.117.0...v0.118.0) (2026-08-21)
+
+
+### Features
+
+* **delivery-graphs:** human-facing Delivery Graphs UI surface ([#386](https://github.com/nanobpm/nano-workforce/issues/386)) ([#418](https://github.com/nanobpm/nano-workforce/issues/418)) ([3e5877d](https://github.com/nanobpm/nano-workforce/commit/3e5877d2e9f7dc4c7d7934b556e4eefd93685f0f)), closes [#405](https://github.com/nanobpm/nano-workforce/issues/405) [#397](https://github.com/nanobpm/nano-workforce/issues/397) [#374](https://github.com/nanobpm/nano-workforce/issues/374)
+
 # [0.117.0](https://github.com/nanobpm/nano-workforce/compare/v0.116.0...v0.117.0) (2026-08-21)
 
 

package/README.md

@@ -246,6 +246,27 @@ active epic already targets the same custom base. See
 
 ---
 
+## Delivery graphs
+
+Beyond a single PR (review convergence) and an epic (plan → fan-out), Nano Workforce can
+run an **arbitrary, heterogeneous, cross-repo, partly-human delivery graph** — e.g.
+*merge PR #A → un-draft+merge PR #B → a human runs a manual OTP publish → PR #C consumes
+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).
+
+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
+agent at that URL to author, compile, and submit a graph unaided. See
+[ADR 0005](docs/adr/0005-agent-authored-delivery-graphs.md) for the design and rationale.
+
+---
+
 ## Configuration
 
 | env | default | purpose |

package/app/deliveryGraphText.ts

@@ -0,0 +1,41 @@
+// app/deliveryGraphText.ts — the shared PARSE step for the human-facing UI JSON-paste ingress
+// (issue #386, ADR 0005). The Delivery Graphs page (`pages/delivery-graphs.page.json`) submits the
+// operator's pasted delivery-graph as a raw JSON STRING (`graphJson`) — the page's text field cannot
+// submit a structured object — so the preview/dispatch ingress operations parse it here before handing
+// the resulting object to the SAME pure `compileDeliveryGraph` compiler / gated `startDeliveryGraph`
+// door the agent-facing paths use. This is a UI text adapter, NOT a parallel compile/dispatch path.
+//
+// PURE and I/O-free so it unit-tests in isolation. A blank field, non-JSON text, or a non-object JSON
+// value maps to a clean `{ ok:false, error }` the ingress surfaces as a 400 with a human banner —
+// never a 500.
+
+/** The result of parsing a UI JSON-paste body: the parsed graph (still `unknown` — the compiler/door
+ * run the real shape + semantic validation), or a human-readable parse error. */
+export type ParseDeliveryGraphTextResult =
+  | { ok: true; graph: unknown }
+  | { ok: false; error: string };
+
+/** Parse a UI JSON-paste request body (`{ graphJson: string, … }`) into a candidate delivery graph.
+ * Guards the three ways the paste can be unusable BEFORE any compile/dispatch runs: a missing/blank
+ * `graphJson`, text that is not valid JSON, and JSON that is not an object (e.g. a bare array or
+ * scalar). The returned `graph` is deliberately `unknown` — `compileDeliveryGraph` /
+ * `validateDeliveryGraph` own the real validation. */
+export function parseDeliveryGraphText(body: unknown): ParseDeliveryGraphTextResult {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return { ok: false, error: "request body must carry a `graphJson` string" };
+  }
+  const graphJson = "graphJson" in body ? body.graphJson : undefined;
+  if (typeof graphJson !== "string" || graphJson.trim() === "") {
+    return { ok: false, error: "paste a delivery-graph JSON into the field" };
+  }
+  let graph: unknown;
+  try {
+    graph = JSON.parse(graphJson);
+  } catch (err) {
+    return { ok: false, error: `not valid JSON: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (!graph || typeof graph !== "object" || Array.isArray(graph)) {
+    return { ok: false, error: "the pasted JSON must be a delivery-graph object" };
+  }
+  return { ok: true, graph };
+}

package/docs/agent-guide.md

@@ -394,3 +394,176 @@ When you find a genuine bug or a missing capability in the orchestration itself
 When describing the bug, include the concrete evidence you gathered here: the
 `prKey`, the engine `processKey`, the parked element / incident message (§5), and the
 BPMN/prompt file you believe is responsible (§6).
+
+---
+
+## 9. Author and run a delivery graph (ADR 0005)
+
+The two workflows above (§1 convergence-loop, §2 plan-fanout) are each specialised to
+**one** node shape ("an agent implements a slice → opens a PR"). Real delivery is often a
+**heterogeneous, cross-repo, partly-human graph** — e.g. *merge PR #101 → un-draft+merge
+PR #202 → a human does a manual OTP publish → PR #303 consumes the just-published version*. A
+**delivery graph** ([ADR 0005](https://github.com/nanobpm/nano-workforce/blob/main/docs/adr/0005-agent-authored-delivery-graphs.md))
+lets you compose exactly that as **data** and hand it to a generic runner.
+
+You author the graph as **JSON — never BPMN or code** (Decision 1: the agent must never
+author the executable artifact; the closed node vocabulary is the trust boundary). Two
+doors take that JSON: a **pure `compile`** door you hammer while drafting, and a **gated
+`start`** door that dispatches it.
+
+### 9.1 The `DeliveryGraph` shape
+
+A `DeliveryGraph` is a JSON **DAG**: `{ name?, nodes[], edges[] }`.
+
+- **`nodes[]`** — each node has a unique `id`, a `kind` from the **closed allowlist**
+  (`agent` | `wait` | `human` | `connector`), the matching per-kind config, and an
+  optional typed `emits[]` declaration (the facts it hands forward).
+- **`edges[]`** — each edge is `{ from, to }` meaning *"`to` proceeds once fact `from` is
+  observable"* (Decision 3 — edges are **discovered facts**, not declared values). `from`
+  is either a bare **`<nodeId>`** (the degenerate "wait for the upstream node's
+  completion" fact) or a **qualified `<nodeId>.<fact>`** referencing one of that node's
+  declared `emits`. The whole edge set must be a DAG. Omit / `[]` for independent roots.
+
+**The four node kinds** (each delegates to an existing engine-native body — the graph
+layer schedules, it does not re-implement execution):
+
+| kind | config | what it does | may `emits`? |
+|---|---|---|---|
+| `agent` | `agent: { jobType, prompt? }` | a worker runs an agent job type (the fan-out body). **Side-effecting.** | yes |
+| `wait` | `wait: <ReadinessProbe>` | a durable, bounded readiness probe — kind ∈ `http`, `command`, `npm`, `github-check`, `capability`, `pr`. Read-only. | yes (binds observed facts) |
+| `human` | `human?: { formKey?, prompt? }` | a scheduled user task + form (the Tasks inbox, §3). Blocks dependents, SLA-bounded, answerable by a human **or** an agent. | yes |
+| `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). *(payload is a forward-declared stub.)* | yes |
+
+A **`wait` node's `wait` is a `ReadinessProbe` verbatim** (the same shape feature-run
+intake uses): `{ kind, target, onTimeout?, match?, poll? }`. The **`pr` kind** watches an
+in-flight PR — `target: "owner/repo#123"`, `match.prState ∈ ready|merged|mergeable|checks-green`
+(default `merged`) — and on a merged match binds `mergedSha` as an output fact.
+
+A **typed fact** (`emits[]` entry) is `{ name, type, description? }` where
+`type ∈ string|number|boolean|artifact|version|url` (`artifact` = a `pkg@version` handle,
+`version` = a bare version). `name` matches `^[A-Za-z_][A-Za-z0-9_]*$` and is referenced
+downstream as `<nodeId>.<name>`. A "click done" human node or a pass-through node declares
+no facts.
+
+### 9.2 The agent loop: draft → compile → fix → approve → start
+
+```
+GET __BASE__/agent           # ← you are reading it; learn the vocabulary + endpoints
+   └─ draft a DeliveryGraph JSON
+        └─ POST __BASE__/actions/compile-delivery-graph   # PURE — validate + preview, repeat freely
+             ├─ 400 { ok:false, errors:[{path,message}] } → fix the exact offending input, recompile
+             └─ 200 { ok:true, diagram, bpmn, resolved, humanNodes, sideEffects } → review the preview
+                  └─ POST __BASE__/actions/start/delivery-graph   # GATED dispatch
+                       ├─ 400 awaiting-approval (has side effects) → re-POST with approvalToken
+                       └─ 202 running → track it like a plan (§5)
+```
+
+**Compile (pure preview — never deploys).** The fast inner loop. It runs the semantic
+validator and the deterministic compiler and returns a preview with **zero side effects**,
+so call it as often as you like:
+
+```bash
+curl -sS -X POST __BASE__/actions/compile-delivery-graph \
+  -H 'content-type: application/json' \
+  -d @graph.json | jq
+```
+
+- `200 { ok:true, diagram, bpmn, resolved, humanNodes, sideEffects }` — `diagram` is a
+  mermaid `flowchart` of the resolved graph; `bpmn` is the compiled one-shot definition
+  (deterministic — same JSON → byte-identical XML, **not** deployed here); `resolved` is
+  the normalised graph; `humanNodes[]` are the stop-points where it waits for a person;
+  `sideEffects[]` are the `agent`/`connector` actions it **will** perform (what a human
+  approves).
+- `400 { ok:false, errors:[{ path, message }] }` — every error path-qualified
+  (`nodes[2].kind`, `edges[1].from`, …) for unknown kind, dangling edge, a cycle, or an
+  unresolvable `from` fact. Fix and recompile.
+
+**Start (gated dispatch — the OUTER action).** `compile` and `start` are **separate**
+operations — there is deliberately **no `dryRun` flag** on start (Decision 5/7). The door
+re-validates, re-compiles, then launches the runner:
+
+```bash
+# First submit — a graph with side effects is refused and PARKED for approval:
+curl -sS -X POST __BASE__/actions/start/delivery-graph \
+  -H 'content-type: application/json' \
+  -d '{ "graph": { … } }' | jq
+# → 400 { ok:false, status:"awaiting-approval", runKey, digest, sideEffecting:true,
+#          approvalToken:"<digest>", message:"graph has N side-effecting node(s); re-submit with approvalToken" }
+
+# Approve by re-submitting with the token (== the digest) you were handed:
+curl -sS -X POST __BASE__/actions/start/delivery-graph \
+  -H 'content-type: application/json' \
+  -d '{ "graph": { … }, "approvalToken": "<digest>" }' | jq
+# → 202 { ok:true, status:"running", runKey, digest, sideEffecting:true,
+#          alreadyRunning:false, processInstanceKey, processDefinitionId:"delivery-graph-<digest>" }
+```
+
+The request body is `{ graph, approvalToken?, idempotencyKey? }`:
+
+| field | type | meaning |
+|---|---|---|
+| `graph` | `DeliveryGraph` | the JSON graph. Required. |
+| `approvalToken` | string | the approval **of the rendered preview** (Decision 7). A graph with any **side-effecting** (`agent`/`connector`) node — one that merges PRs / publishes — dispatches **only** when you present its content-addressed token (the `digest`, returned on the first unapproved submit). A graph with **only** `wait`/`human` nodes needs none and dispatches straight away. |
+| `idempotencyKey` | string | optional. A re-POST with the same key (or, when omitted, the same graph — the default key is the content digest) does **not** double-launch: an in-flight run short-circuits with `alreadyRunning: true`. |
+
+The running graph registers as a run aggregate, so its current phase / parked node shows
+in the cockpit's **Active Delivery Graphs** grid (e.g. *"parked on human node: manual OTP
+publish"*). Track it like a plan (§5) via its `processInstanceKey`. A `human` node parks
+on the **Tasks** inbox and is answered exactly as an escalation is (§3) — its completion
+emits any declared facts, which downstream edges bind.
+
+### 9.3 Worked example — the cross-repo human-in-the-loop release
+
+*Merge PR #101 (repo 1) → un-draft+merge PR #202 (repo 2) → a **human** runs the manual OTP
+publish and records the version → open+merge PR #303 (repo 3) consuming that version.* The
+`human` node **emits** a typed `version` fact, and the downstream `from:
+"manual-publish.publishedVersion"` edge binds it into the PR-#303 path:
+
+```json
+{
+  "name": "cross-repo release: merge #101 → un-draft+merge #202 → manual OTP publish → consume in #303",
+  "nodes": [
+    { "id": "merge-a", "kind": "wait",
+      "wait": { "kind": "pr", "target": "acme/repo-1#101", "match": { "prState": "merged" }, "onTimeout": "escalate" } },
+    { "id": "undraft-merge-b", "kind": "agent",
+      "agent": { "jobType": "senior:merge", "prompt": "Take draft PR acme/repo-2#202 out of draft and merge it once its required checks are green." } },
+    { "id": "manual-publish", "kind": "human",
+      "human": { "prompt": "Run the manual OTP-authenticated `npm publish` for @acme/widget and set up OIDC trusted publishing. Record the exact published version." },
+      "emits": [ { "name": "publishedVersion", "type": "version", "description": "The version just published to npm." } ] },
+    { "id": "open-pr-c", "kind": "agent",
+      "agent": { "jobType": "senior:feature", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open PR #303." } },
+    { "id": "merge-c", "kind": "wait",
+      "wait": { "kind": "pr", "target": "acme/repo-3#303", "match": { "prState": "merged" }, "onTimeout": "escalate" } }
+  ],
+  "edges": [
+    { "from": "merge-a", "to": "undraft-merge-b" },
+    { "from": "undraft-merge-b", "to": "manual-publish" },
+    { "from": "manual-publish.publishedVersion", "to": "open-pr-c" },
+    { "from": "open-pr-c", "to": "merge-c" }
+  ]
+}
+```
+
+`compile` returns this preview (abridged):
+
+```
+diagram (mermaid flowchart):
+  n4["agent: undraft-merge-b"] --> n0["human: manual-publish"]
+  n0 -- "publishedVersion" --> n3["agent: open-pr-c"]
+  n1["wait: merge-a"] --> n4
+  n3 --> n2["wait: merge-c"]
+
+humanNodes: [ { nodeId: "manual-publish", emits: [ { name: "publishedVersion", type: "version" } ], … } ]
+sideEffects: [ { nodeId: "open-pr-c", kind: "agent", … }, { nodeId: "undraft-merge-b", kind: "agent", … } ]
+```
+
+Two side-effecting `agent` nodes ⇒ `start` **requires approval**: the first submit returns
+`awaiting-approval` with an `approvalToken`; re-submit carrying it to dispatch. The graph
+then runs to `manual-publish`, parks it on the Tasks inbox (`now do X`), and — once a human
+(or agent) completes it with the `publishedVersion` — binds that fact into `open-pr-c` and
+carries on to `merge-c`.
+
+To swap the manual PR-#303 path for a **capability** edge instead of a raw `pr` watch, make
+the consumer a `wait` node with `kind: "capability"` (resolving *which published
+`pkg@version` first carries the change*) fed by the same `manual-publish.publishedVersion`
+fact — the fact-edge syntax is identical.

package/openapi.yaml

@@ -1515,6 +1515,107 @@ components:
         message:
           type: string
           description: Human-actionable description of the failure.
+    DeliveryGraphTextSubmit:
+      description: >-
+        The human-facing UI JSON-paste PREVIEW request (issue #386). The Delivery Graphs page's text
+        field cannot submit a structured object, so the operator's pasted delivery-graph is carried as
+        a raw JSON STRING (`graphJson`), parsed server-side and handed to the SAME pure
+        `compileDeliveryGraph` compiler the agent-facing door uses. No parallel compile path.
+      type: object
+      additionalProperties: false
+      required:
+        - graphJson
+      properties:
+        graphJson:
+          type: string
+          description: The pasted delivery-graph JSON (a serialised `DeliveryGraph`), parsed server-side.
+    DeliveryGraphTextDispatch:
+      description: >-
+        The human-facing UI JSON-paste DISPATCH request (issue #386). Carries the pasted delivery-graph
+        as a raw JSON STRING plus the operator's explicit `approve` flag and optional idempotency key;
+        parsed server-side and delegated to the ONE gated, idempotent `startDeliveryGraph` contract —
+        there is NO parallel dispatch path.
+      type: object
+      additionalProperties: false
+      required:
+        - graphJson
+      properties:
+        graphJson:
+          type: string
+          description: The pasted delivery-graph JSON (a serialised `DeliveryGraph`), parsed server-side.
+        approve:
+          type: boolean
+          description: >-
+            The operator's approval OF the previewed graph. When true, the door derives the graph's
+            content digest and presents it as the `approvalToken`, so a side-effecting graph the
+            operator reviewed dispatches; when false/absent a side-effecting graph is parked at approval.
+        idempotencyKey:
+          type: string
+          maxLength: 255
+          description: OPTIONAL idempotency key forwarded to `startDeliveryGraph`. Blank/whitespace is treated as absent.
+    DeliveryGraphTextResult:
+      description: >-
+        The UI JSON-paste ingress outcome (issue #386) — a single shape covering the PREVIEW summary,
+        the DISPATCH outcome, and any parse/validation error. `ok` discriminates success; a failure
+        carries a human `error` (and, for a compile failure, path-qualified `errors`).
+      type: object
+      additionalProperties: false
+      required:
+        - ok
+      properties:
+        ok:
+          type: boolean
+          description: True on a successful preview/dispatch; false on a parse/validation failure or an approval park.
+        error:
+          type: string
+          description: A human-readable failure message (surfaced by the page's action banner).
+        errors:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryCompileError"
+          description: Path-qualified validation/compile failures, when the pasted graph was malformed.
+        status:
+          type: string
+          description: The dispatch run's lifecycle position (`running` / `awaiting-approval`), when dispatched.
+        runKey:
+          type: string
+          description: The dispatch run's idempotency key, when dispatched.
+        digest:
+          type: string
+          description: The graph's content digest — the approval token to dispatch a side-effecting graph.
+        sideEffecting:
+          type: boolean
+          description: Whether the graph has any side-effecting (`agent`/`connector`) node.
+        alreadyRunning:
+          type: boolean
+          description: True when a dispatch short-circuited onto an already-running run.
+        processInstanceKey:
+          type: string
+          description: The started engine instance key, when dispatched.
+        processDefinitionId:
+          type: string
+          description: The started process definition id, when dispatched.
+        approvalToken:
+          type: string
+          description: The approval token to re-submit with, when a side-effecting graph was parked pending approval.
+        message:
+          type: string
+          description: Additional detail from the dispatch door (e.g. the approval-park explanation).
+        title:
+          type: string
+          description: The graph's human-readable name, echoed on a successful preview.
+        nodeCount:
+          type: integer
+          description: The compiled graph's node count (preview).
+        humanNodeCount:
+          type: integer
+          description: The compiled graph's human stop-point count (preview).
+        sideEffectCount:
+          type: integer
+          description: The compiled graph's side-effecting node count (preview).
+        diagram:
+          type: string
+          description: The mermaid flowchart of the compiled graph (preview).
     ResolvedDeliveryNode:
       description: >-
         A normalised node in the compiled graph (ADR 0005 slice S1) — its `id`, `kind`, the
@@ -2615,6 +2716,71 @@ paths:
                 oneOf:
                   - $ref: "#/components/schemas/CompileDeliveryGraphErrors"
                   - $ref: "#/components/schemas/StartDeliveryGraphResult"
+  /actions/delivery-graph/preview:
+    post:
+      operationId: previewDeliveryGraph
+      summary: UI JSON-paste PREVIEW — parse a pasted delivery-graph JSON string and compile it (PURE). (ADR 0005 S1 / #386)
+      description: >-
+        The human-facing UI JSON-paste PREVIEW ingress (issue #386). The Delivery Graphs page's
+        "Preview" action posts the operator's pasted JSON as a STRING; this door parses it and runs the
+        SAME pure `compileDeliveryGraph` compiler the agent-facing door uses, returning a compact
+        summary (the content `digest` = the approval token, node/human/side-effect counts, the mermaid
+        `diagram`). It is PURE and side-effect-free — nothing is deployed or dispatched. A blank/invalid
+        JSON string, or a graph that fails validation, is a 400 carrying a human `error` (and
+        path-qualified `errors` for a compile failure).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeliveryGraphTextSubmit"
+      responses:
+        "200":
+          description: The pasted graph parsed, validated and compiled — the pure preview summary.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphTextResult"
+        "400":
+          description: The pasted text was not valid JSON, or the graph failed validation/compilation.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphTextResult"
+  /actions/delivery-graph/dispatch:
+    post:
+      operationId: dispatchDeliveryGraph
+      summary: UI JSON-paste DISPATCH — parse a pasted delivery-graph JSON string and dispatch it via startDeliveryGraph (gated, idempotent). (ADR 0005 S5 / #386)
+      description: >-
+        The human-facing UI JSON-paste DISPATCH ingress (issue #386). The Delivery Graphs page's
+        "Dispatch" action posts the operator's pasted JSON as a STRING plus an explicit `approve` flag;
+        this door parses it and delegates to the SAME gated, idempotent `startDeliveryGraph` contract —
+        there is NO parallel dispatch path. When `approve` is true the door derives the graph's content
+        digest and presents it as the approval token, so a side-effecting graph the operator reviewed in
+        the preview dispatches; without `approve` a side-effecting graph is PARKED at approval (visible
+        in the in-flight grid) and a non-side-effecting graph dispatches straight away. Idempotent on
+        `idempotencyKey` (else the content digest).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeliveryGraphTextDispatch"
+      responses:
+        "202":
+          description: The graph dispatched (or a re-submit short-circuited an already-running run).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphTextResult"
+        "400":
+          description: >-
+            The pasted text was not valid JSON, the graph failed validation, or a side-effecting graph
+            was parked pending approval (the body carries the `approvalToken` / `error` to act on).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphTextResult"
   /actions/start/feature:
     post:
       operationId: startFeature

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);
+});