@nanobpm/nano-workforce 0.116.0 → 0.118.0

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/e2e/delivery-graph-start.e2e.ts

@@ -0,0 +1,145 @@
+// End-to-end proof of the S5 DISPATCH DOOR (ADR 0005 Decision 7) driven through its REAL ingress — the
+// `startDeliveryGraph` OpenAPI operation (`POST /app/api/actions/start/delivery-graph`), the one
+// contract all three ingress paths (agent POST, raw REST, UI JSON-paste) share. Hermetic: deterministic
+// virtual clock, no network. It proves the acceptance the slice hinges on:
+//
+//   • APPROVAL GATE: a side-effecting graph submitted WITHOUT approval is refused + PARKED (400,
+//     awaiting-approval, no engine instance, no agent job fired) — and is VISIBLE in the cockpit's
+//     `delivery_graph_runs` aggregate so an operator can see it waiting.
+//   • DISPATCH: re-submitting the same graph WITH its content-addressed approval token dispatches — the
+//     graph deploys + runs engine-natively (the agent side effect fires), and the run's derived phase
+//     shows WHERE it is parked ("Parked on human node: …") via the same `pollDeliveryGraphPhase`
+//     projection the cockpit reads.
+//   • IDEMPOTENCY: a duplicate submit short-circuits (`alreadyRunning`) — the agent side effect fires
+//     exactly ONCE, never twice.
+//   • COMPLETION: when the instance ends, the poller reconciles the run to `done` (instanceTracking's
+//     onTerminated reconciles only TERMINATED, so this poller owns COMPLETED→done).
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { after, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { deliveryGraphRuns } from "../app/deliveryGraphRun.ts";
+import { pollDeliveryGraphPhase } from "../app/service.ts";
+import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+const GITHUB_ENV: Record<string, string> = { NANO_PR_GITHUB_TRANSPORT: "token", GITHUB_TOKEN: "" };
+
+interface StartResult {
+  ok: boolean;
+  status: string;
+  runKey: string;
+  digest: string;
+  sideEffecting: boolean;
+  alreadyRunning?: boolean;
+  processInstanceKey?: string;
+  approvalToken?: string;
+}
+
+// A side-effecting graph: an `agent` side effect gated ahead of a `human` stop. Approval is required
+// (the agent + the human-facing merge/publish class of graphs Decision 7 protects).
+const GRAPH: DeliveryGraph = {
+  name: "release runbook e2e",
+  nodes: [
+    { id: "open", kind: "agent", agent: { jobType: "senior:demo", prompt: "open + prep" } },
+    { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish" } },
+  ],
+  edges: [{ from: "open", to: "publish" }],
+};
+
+describe("startDeliveryGraph dispatch door — submit → approve → dispatch, idempotent (S5)", () => {
+  const dirs: string[] = [];
+  const apps: TestApp[] = [];
+  after(async () => {
+    for (const app of apps) await app.stop?.();
+    for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  });
+  const boot = async (): Promise<TestApp> => {
+    const d = mkdtempSync(join(tmpdir(), "nwf-delivery-start-e2e-"));
+    dirs.push(d);
+    const app = await bootTestApp(APP_ROOT, { env: { ...GITHUB_ENV, NANO_APP_DB_URL: `file:${join(d, "app.db")}` } });
+    apps.push(app);
+    return app;
+  };
+
+  test("a side-effecting graph is parked at approval, then dispatches once approved; a duplicate never double-launches", async () => {
+    const app = await boot();
+    assert.ok(app.api, "app declares an `api` binding");
+    const api = app.api;
+
+    let agentFired = 0;
+    await app.engine.registerWorker("senior:demo", async () => {
+      agentFired++;
+      return {};
+    });
+
+    // ── Approval gate: submit WITHOUT approval → refused + parked, nothing launched ────────────────
+    const parked = await api.call<StartResult>("startDeliveryGraph", { body: { graph: GRAPH } });
+    assert.equal(parked.status, 400, "an unapproved side-effecting graph is refused");
+    assert.equal(parked.body.status, "awaiting-approval");
+    assert.equal(parked.body.sideEffecting, true);
+    assert.ok(parked.body.approvalToken, "the response hands back the approval token to re-submit with");
+    await app.settle();
+    assert.equal(agentFired, 0, "a parked graph never dispatched its side effect");
+
+    // The parked run is durable + visible in the cockpit aggregate.
+    const runKey = parked.body.runKey;
+    const parkedRow = await deliveryGraphRuns(app.db).get(runKey);
+    assert.ok(parkedRow, "a delivery_graph_runs row exists for the parked graph");
+    assert.equal(parkedRow?.status, "awaiting-approval");
+    assert.equal(parkedRow?.process_key, null, "no engine instance while parked");
+
+    // ── Dispatch: re-submit WITH the token → deploys + runs engine-natively ───────────────────────
+    const token = parked.body.approvalToken;
+    const dispatched = await api.call<StartResult>("startDeliveryGraph", { body: { graph: GRAPH, approvalToken: token } });
+    assert.equal(dispatched.status, 202, "an approved graph dispatches");
+    assert.equal(dispatched.body.status, "running");
+    assert.equal(dispatched.body.alreadyRunning, false);
+    assert.ok(dispatched.body.processInstanceKey, "the run carries the started engine instance key");
+    await app.settle();
+    assert.equal(agentFired, 1, "the agent side effect fired exactly once");
+
+    // The run transitioned parked → running IN PLACE (one row, not a duplicate), carrying its instance.
+    const runningRows = await deliveryGraphRuns(app.db).find({ status: "running" });
+    assert.equal(runningRows.length, 1, "exactly one running run");
+    assert.equal(runningRows[0]?.run_key, runKey, "the SAME run row was approved, not a new one");
+    assert.equal(runningRows[0]?.process_key, dispatched.body.processInstanceKey);
+
+    // ── Cockpit phase: the poller derives WHERE the run is parked (the human node) ─────────────────
+    await pollDeliveryGraphPhase(app.db, app.engine);
+    const phased = await deliveryGraphRuns(app.db).get(runKey);
+    assert.equal(phased?.status, "running");
+    assert.match(String(phased?.phase), /^Parked on human node:/, `phase shows the parked human node, got ${phased?.phase}`);
+
+    // ── Idempotency: a duplicate submit short-circuits — the side effect never fires twice ────────
+    const dup = await api.call<StartResult>("startDeliveryGraph", { body: { graph: GRAPH, approvalToken: token } });
+    assert.equal(dup.status, 202);
+    assert.equal(dup.body.alreadyRunning, true, "the re-submit short-circuited the already-running run");
+    await app.settle();
+    assert.equal(agentFired, 1, "the agent side effect STILL fired only once (no double-launch)");
+
+    // ── Completion: complete the human stop → the instance ends → the poller reconciles to done ───
+    const open = await app.engine.searchUserTasks({ state: "CREATED" });
+    const human = open.find((t) => t.elementId?.startsWith("delivery-human-task__") && !t.elementId?.endsWith("__esc"));
+    assert.ok(human, `a human user task is open, got ${JSON.stringify(open.map((t) => t.elementId))}`);
+    await app.engine.completeUserTask(human.userTaskKey, { humanOutcome: "completed" });
+    await app.settle();
+    await pollDeliveryGraphPhase(app.db, app.engine);
+    const done = await deliveryGraphRuns(app.db).get(runKey);
+    assert.equal(done?.status, "done", "the completed instance reconciled the run to done");
+    assert.equal(done?.phase, "Completed");
+  });
+
+  test("a non-side-effecting (human-only) graph dispatches with NO approval", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const graph: DeliveryGraph = { name: "manual gate", nodes: [{ id: "ack", kind: "human", human: { prompt: "click done" } }] };
+    const res = await app.api.call<StartResult>("startDeliveryGraph", { body: { graph } });
+    assert.equal(res.status, 202, "a graph with no side effects needs no approval");
+    assert.equal(res.body.status, "running");
+    assert.equal(res.body.sideEffecting, false);
+    assert.ok(res.body.processInstanceKey);
+  });
+});

package/nano.app.json

@@ -81,6 +81,20 @@
         }
       },
       "pollMs": 5000
+    },
+    {
+      "table": "delivery_graph_runs",
+      "keyField": "process_key",
+      "statusField": "status",
+      "activeStatuses": [
+        "running"
+      ],
+      "onTerminated": {
+        "set": {
+          "status": "failed"
+        }
+      },
+      "pollMs": 5000
     }
   ],
   "workers": [

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
@@ -1713,6 +1814,85 @@ components:
           items:
             $ref: "#/components/schemas/DeliveryCompileError"
           description: The path-qualified validation/compile failures (at least one).
+    DeliveryGraphStart:
+      description: >-
+        The `startDeliveryGraph` request body (ADR 0005 slice S5) — the ONE gated dispatch door that
+        turns an agent-authored `DeliveryGraph` into a RUNNING engine-native process. This is the OUTER
+        action, distinct from S1's pure `compileDeliveryGraph`: there is deliberately no `dryRun` flag
+        (Decision 5/7) — compile and start are separate operations. The door re-validates (S0), compiles
+        (S1), and launches the S4 runner. Three ingress paths — an agent-ergonomic POST, a raw REST call,
+        and a UI JSON-paste — all hit this ONE contract.
+      type: object
+      additionalProperties: false
+      required:
+        - graph
+      properties:
+        graph:
+          $ref: "#/components/schemas/DeliveryGraph"
+        approvalToken:
+          type: string
+          description: >-
+            The approval OF the rendered preview (Decision 7). Because a delivery graph merges PRs and
+            publishes packages, a graph with any SIDE-EFFECTING node (`agent`/`connector`) dispatches
+            ONLY when the caller presents the graph's content-addressed approval token (returned as
+            `approvalToken` on a prior unapproved submit's `awaiting-approval` response). A graph with
+            no side effects (only `wait`/`human` nodes) needs none and dispatches straight away.
+        idempotencyKey:
+          type: string
+          maxLength: 255
+          description: >-
+            OPTIONAL caller-supplied idempotency key. A re-POST with the SAME key (or, when omitted, the
+            SAME graph — the default key is the graph's content digest) does NOT double-launch: an
+            in-flight run short-circuits with `alreadyRunning: true`. Blank/whitespace is treated as
+            absent.
+    StartDeliveryGraphResult:
+      description: >-
+        The `startDeliveryGraph` outcome. `status` is the run's lifecycle position: `running` (the graph
+        dispatched — or was already running, see `alreadyRunning`) or `awaiting-approval` (a
+        side-effecting graph was submitted without a valid `approvalToken` — it is PARKED, visible in the
+        cockpit, and refused pending approval; re-POST with the returned `approvalToken` to dispatch).
+      type: object
+      additionalProperties: false
+      required:
+        - ok
+        - status
+        - runKey
+        - digest
+        - sideEffecting
+      properties:
+        ok:
+          type: boolean
+          description: True when the graph dispatched (or was already running); false when parked at approval.
+        status:
+          type: string
+          enum: [running, awaiting-approval]
+          description: The run's lifecycle position after this call.
+        runKey:
+          type: string
+          description: The idempotency key the run is stored under (the caller key, else the content digest).
+        digest:
+          type: string
+          description: The graph's content digest — the content-address of the compiled definition.
+        sideEffecting:
+          type: boolean
+          description: Whether the graph has any side-effecting (`agent`/`connector`) node — i.e. whether approval is required.
+        alreadyRunning:
+          type: boolean
+          description: True when a re-submit short-circuited onto an already-running run (no second launch).
+        processInstanceKey:
+          type: string
+          description: The started engine instance key. Present when `status` is `running`; absent while parked at approval.
+        processDefinitionId:
+          type: string
+          description: The content-addressed deployed process id (`delivery-graph-<digest>`). Present when dispatched.
+        approvalToken:
+          type: string
+          description: >-
+            The token to present as `approvalToken` on a re-POST to dispatch this exact graph. Present
+            when `status` is `awaiting-approval` (equals `digest`).
+        message:
+          type: string
+          description: A human-readable summary of the outcome (e.g. the approval-required reason).
     FeatureStart:
       description: The start-feature request body — a SINGLE-issue feature run. Names the target issue
         by EXACTLY ONE of `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a
@@ -2495,6 +2675,112 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/CompileDeliveryGraphErrors"
+  /actions/start/delivery-graph:
+    post:
+      operationId: startDeliveryGraph
+      summary: Validate + compile + DISPATCH a delivery graph as a running engine-native process (gated, idempotent). (ADR 0005 slice S5)
+      description: >-
+        The delivery-graph DISPATCH door (ADR 0005 Decision 7) — the single gated OUTER action that
+        turns an agent-authored `DeliveryGraph` into a RUNNING engine-native process. Distinct from S1's
+        pure `compileDeliveryGraph`: compile and start are SEPARATE operations (Decision 5/7), so there
+        is deliberately no `dryRun` flag. The door re-validates the graph (`validateDeliveryGraph`, S0),
+        compiles it (`compileDeliveryGraph`, S1), and LAUNCHES the S4 runner (`runDeliveryGraph`).
+        Because these graphs merge PRs and publish packages, dispatch is GATED: a graph with any
+        side-effecting (`agent`/`connector`) node must present the content-addressed `approvalToken` of
+        its rendered preview, else it is PARKED at approval (a 400 carrying the token, plus a visible
+        `awaiting-approval` run in the cockpit) rather than dispatched. Idempotent: a re-POST of the same
+        graph (or the same `idempotencyKey`) short-circuits an already-running run instead of
+        double-launching. Three ingress paths — an agent-ergonomic POST, a raw REST call, and a UI
+        JSON-paste — all hit this ONE contract.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeliveryGraphStart"
+      responses:
+        "202":
+          description: The graph dispatched (or a re-submit short-circuited an already-running run).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StartDeliveryGraphResult"
+        "400":
+          description: >-
+            The graph failed validation/compilation (path-qualified errors), OR a side-effecting graph
+            was submitted without a valid approval token — it is refused and PARKED at approval (the
+            body carries the `approvalToken` to re-submit with).
+          content:
+            application/json:
+              schema:
+                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