@nanobpm/nano-workforce 0.117.0 → 0.118.1

package/app/agentic/families/relay.family.ts

@@ -33,7 +33,9 @@ import {
   type TranscriptStream,
 } from "@nanobpm/agentic/transcript";
 import type { Logger } from "@nanobpm/urban";
+import { currentCorrelation, type JobContext, jobKeyOfStream } from "../correlation.ts";
 import type { AgenticContext, AgenticFamily } from "../registry.ts";
+import { currentPresenceRegistry } from "./presence.family.ts";
 
 /** The stable family name this slice registers under the seam (distinct from the wire family key). */
 export const RELAY_FAMILY_NAME = "relay";
@@ -81,6 +83,22 @@ interface StreamState {
   producer?: string;
   /** Set once an ephemeral stream has been flushed & completed (so it is not re-completed). */
   completed: boolean;
+  /**
+   * Set once a `job:<jobKey>` stream has been linked into the correlation registry (H6, #149), so
+   * the link is attempted at most once per stream. It stays `false` while the producer's presence
+   * instance is not yet resolvable (a register/produce race), so a later `produce` frame retries.
+   */
+  linked: boolean;
+}
+
+/**
+ * The minimal correlation write-side the relay slice drives (H6, #149): link a producing worker
+ * instance to the jobKey it is relaying, and release it when the job's stream ends. Structural so
+ * the service depends on a shape, not the whole {@link CorrelationRegistry}.
+ */
+export interface CorrelationLink {
+  link(instance: string, jobKey: string, context?: JobContext): void;
+  releaseJob(jobKey: string): void;
 }
 
 export interface RelayTranscriptServiceOptions {
@@ -104,6 +122,21 @@ export interface RelayTranscriptServiceOptions {
    * against a bare source too (and is harmless when the migration already ran).
    */
   readonly ensureSchema?: boolean;
+  /**
+   * The correlation write-side seam (H6, #149). When present, a first `produce` frame for a
+   * `job:<jobKey>` stream links the producing worker instance → jobKey here, and the stream's
+   * completion / producer disconnect releases it. Defaults to the process-wide correlation registry
+   * ({@link currentCorrelation}); absent (`() => undefined`) → no linking (advisory, never an error).
+   */
+  readonly correlation?: () => CorrelationLink | undefined;
+  /**
+   * Resolve the presence instance that owns a connection — the connection → instance join the
+   * correlation write-side needs to attribute a `produce` frame's jobKey. When omitted,
+   * `RelayTranscriptService` defaults it to `() => undefined` (no linking); the family factory
+   * {@link createRelayFamily} is what wires it to the mounted presence registry's resolver
+   * ({@link currentPresenceRegistry}). A resolver returning undefined → no linking (advisory).
+   */
+  readonly instanceForConnection?: (connectionId: string) => string | undefined;
 }
 
 /** The minimal per-connection surface the relay handler receives from the hub (a {@link RelayHub} `RelayConnection`). */
@@ -128,10 +161,16 @@ export class RelayTranscriptService {
   readonly #registry: ConnectionRegistry;
   readonly #log: Logger;
   readonly #streams = new Map<string, StreamState>();
+  /** The correlation write-side accessor (H6, #149) — resolved per call so a late family mount wins. */
+  readonly #correlation: () => CorrelationLink | undefined;
+  /** The connection → producing-instance resolver (H6, #149). */
+  readonly #instanceForConnection: (connectionId: string) => string | undefined;
 
   constructor(options: RelayTranscriptServiceOptions) {
     this.#registry = options.registry;
     this.#log = options.log;
+    this.#correlation = options.correlation ?? currentCorrelation;
+    this.#instanceForConnection = options.instanceForConnection ?? (() => undefined);
     // Persistence is advisory: a store that can't be constructed or whose schema can't be applied
     // (locked/permission-denied/unavailable SQLite) must NOT fail the family mount — fall back to
     // running the relay unpersisted rather than tearing down the whole agentic channel.
@@ -191,23 +230,31 @@ export class RelayTranscriptService {
    * re-completing already-persisted offsets is a no-op. Returns the number of newly-persisted chunks.
    */
   completeStream(stream: string): number {
-    if (!this.store) return 0;
     const state = this.#stateFor(stream);
     const source = this.relay.ring(stream) ?? EMPTY_SOURCE;
-    let flushed: number;
-    try {
-      flushed = this.store.flush(stream, source, state.lifecycle);
-    } catch (err) {
-      // Persistence is advisory: a flush failure must not bubble into the hub's frame handler and
-      // take down unrelated streams. Log and leave the stream uncompleted so a later pass retries.
-      this.#log.warn("agentic relay stream flush failed — leaving stream uncompleted", {
-        stream,
-        lifecycle: state.lifecycle,
-        err: String(err),
-      });
-      return 0;
+    let flushed = 0;
+    // Persistence is advisory: with no store there is nothing to flush, but the in-memory lifecycle
+    // must still transition (mark completed, unlink correlation, drop producer) so an unpersisted
+    // ephemeral stream completes exactly once and #reconcile does not keep retrying it every frame.
+    if (this.store) {
+      try {
+        flushed = this.store.flush(stream, source, state.lifecycle);
+      } catch (err) {
+        // A flush failure must not bubble into the hub's frame handler and take down unrelated
+        // streams. Log and leave the stream uncompleted so a later pass retries.
+        this.#log.warn("agentic relay stream flush failed — leaving stream uncompleted", {
+          stream,
+          lifecycle: state.lifecycle,
+          err: String(err),
+        });
+        return 0;
+      }
+    }
+    if (state.lifecycle === "ephemeral") {
+      state.completed = true;
+      // Job end: release the jobKey ⇄ instance correlation so the worker's supply row clears it.
+      this.#unlink(stream, state);
     }
-    if (state.lifecycle === "ephemeral") state.completed = true;
     // Drop producer ownership so a later reconcile does not re-flush a completed stream.
     state.producer = undefined;
     this.#log.info("agentic relay stream flushed", {
@@ -283,19 +330,83 @@ export class RelayTranscriptService {
     if (readProp(frame.payload, "op") !== "produce") return;
     const stream = readProp(frame.payload, "stream");
     if (typeof stream !== "string" || stream === "") return;
-    this.#stateFor(stream).producer = conn.id;
+    const state = this.#stateFor(stream);
+    // A completed stream is terminal: a late `produce` frame (e.g. arriving after job-end
+    // completion released the correlation) must not re-own or re-link it — doing so would
+    // resurrect a jobKey after it was released. Ignore ownership updates once completed.
+    if (state.completed) return;
+    state.producer = conn.id;
+    this.#link(stream, conn.id, state);
+  }
+
+  /**
+   * H6 write-side (#149): on the first `produce` for a `job:<jobKey>` stream, link the producing
+   * worker instance → jobKey in the correlation registry, from data already crossing the wire (the
+   * jobKey is decoded from the stream id; the instance is resolved from the producing connection).
+   * That lights up the worker's `jobKeys` in the supply feed and repoints its drill stream at the
+   * jobKey-scoped relay stream. Idempotent per stream; retries on a later frame while the producer's
+   * presence instance is not yet resolvable (a register/produce race). Advisory — never throws into
+   * the frame handler.
+   */
+  #link(stream: string, connectionId: string, state: StreamState): void {
+    if (state.linked) return;
+    const jobKey = jobKeyOfStream(stream);
+    if (jobKey === undefined) return;
+    const instance = this.#instanceForConnection(connectionId);
+    if (instance === undefined || instance === "") return;
+    const correlation = this.#correlation();
+    if (!correlation) return;
+    try {
+      correlation.link(instance, jobKey);
+      state.linked = true;
+    } catch (err) {
+      // Advisory — never throws into the frame handler. Swallow a throwing injectable correlation and
+      // leave the stream UNLINKED so a later `produce` retries the link.
+      this.#log.warn("agentic relay correlation link failed — leaving stream unlinked", {
+        stream,
+        jobKey,
+        err: String(err),
+      });
+    }
+  }
+
+  /** H6 write-side (#149): release a `job:<jobKey>` stream's correlation on completion / disconnect. */
+  #unlink(stream: string, state: StreamState): void {
+    if (!state.linked) return;
+    const jobKey = jobKeyOfStream(stream);
+    if (jobKey === undefined) return;
+    try {
+      this.#correlation()?.releaseJob(jobKey);
+      state.linked = false;
+    } catch (err) {
+      // Advisory — never throws into the frame handler. Swallow a throwing injectable correlation and
+      // leave `state.linked` true so the flag honestly records that the release did NOT happen (rather
+      // than falsely clearing it). Note there is no automatic retry once the stream completes:
+      // `completeStream` sets `state.completed` and clears `state.producer`, so `#reconcile` no longer
+      // revisits it and `teardown` skips already-completed streams. A retry only occurs on the
+      // dead-producer path, where `#reconcile` re-invokes `#unlink` on a still-uncompleted stream.
+      this.#log.warn("agentic relay correlation release failed — leaving stream linked", {
+        stream,
+        jobKey,
+        err: String(err),
+      });
+    }
   }
 
   /**
    * Flush + complete every ephemeral stream whose producer connection is no longer live (the S1
-   * registry dropped it on close or liveness timeout). Lazy, like the relay hub's own dead-subscriber
-   * prune: it runs on each inbound frame, and shutdown covers the quiescent tail via {@link teardown}.
+   * registry dropped it on close or liveness timeout), and release its job correlation (H6, #149).
+   * Lazy, like the relay hub's own dead-subscriber prune: it runs on each inbound frame, and shutdown
+   * covers the quiescent tail via {@link teardown}. The correlation release is store-independent (it
+   * runs even for an unpersisted relay), so a dropped worker's `jobKeys` always clear.
    */
   #reconcile(): void {
     for (const [stream, state] of this.#streams) {
-      if (state.completed || state.lifecycle !== "ephemeral") continue;
       if (state.producer !== undefined && !this.#registry.has(state.producer)) {
-        this.completeStream(stream);
+        // Producer connection gone → the job it was relaying ended: release its correlation.
+        this.#unlink(stream, state);
+        // ...and flush+complete an ephemeral, not-yet-completed transcript exactly as before.
+        if (!state.completed && state.lifecycle === "ephemeral") this.completeStream(stream);
       }
     }
   }
@@ -303,7 +414,7 @@ export class RelayTranscriptService {
   #stateFor(stream: string): StreamState {
     let state = this.#streams.get(stream);
     if (state === undefined) {
-      state = { lifecycle: "ephemeral", completed: false };
+      state = { lifecycle: "ephemeral", completed: false, linked: false };
       this.#streams.set(stream, state);
     }
     return state;
@@ -344,6 +455,12 @@ export function createRelayFamily(options: {
         relay: options.relay,
         transcript: options.transcript,
         ensureSchema: options.ensureSchema,
+        // H6 write-side (#149): resolve the producing connection's presence instance from the live
+        // presence registry, and link/release against the process-wide correlation registry. Both
+        // are read per call, so this works regardless of family mount order (relay may mount before
+        // presence/correlation). Absent registries → no linking, still advisory-correct.
+        instanceForConnection: (connectionId) => currentPresenceRegistry()?.instanceForConnection(connectionId),
+        correlation: currentCorrelation,
       });
       setCurrentRelayTranscriptService(service);
 

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