@nanobpm/nano-workforce 0.112.0 → 0.114.0

package/app/deliveryHuman.ts

@@ -0,0 +1,384 @@
+// nano-workforce — the `human` delivery-graph node (ADR 0005, slice S3). A `human` node promotes
+// ADR 0002's user-task+form machinery from an *exception* (something broke) to a *scheduled node* (a
+// planned "now do X" stop that BLOCKS its dependents, is answerable by a human OR an agent — ADR 0046
+// — is SLA-bounded so it nags and cannot silently wedge the graph, and can EMIT a typed fact its form
+// captures which late-binds downstream). It is the emit-side of #263's emit-vs-poll dual: a *human*
+// emitter is the same shape as an automated one (the `capability`/`pr` probe's `resolvedArtifact`
+// bind), which is what unifies human and automated steps in one graph.
+//
+// This module owns the PURE, side-effect-free machinery the compiler (S1, author-time) and the
+// runner (S4, runtime) reuse — it never itself creates a user task or completes one. Execution stays
+// engine-native (Decision 2): the human node's body is the deployed `delivery-human` `bpmn:userTask`
+// (`resources/processes/delivery-human.bpmn`, an SLA-bounded scheduled user task), completion routes
+// through the ONE canonical completer (`completeEscalationAsAgent`/`completeEscalationAsHuman`,
+// `app/agentCompletion.ts`) because `DELIVERY_HUMAN_ELEMENT` is registered in
+// `ESCALATION_TASK_ELEMENTS`, and the emitted fact threads downstream via the #289 brief-appender /
+// bound-output pattern (`renderResolvedDepsBrief` / the `caps-resolved` → `appendPrompt` recipe).
+//
+// The three pure concerns:
+//   1. FORM RESOLUTION — specific-else-generic (Decision 4): an explicit `human.formKey` on the node,
+//      else a form SELECTED by node category (derived from the node's typed emits), else a GENERIC
+//      fallback form that STILL captures a typed emitted fact — so every human node can emit even with
+//      no bespoke form. A runtime agent-form-router is a GATED exception: it fires ONLY when a node
+//      activates with no statically resolvable form (multiple heterogeneous emits, no explicit/bespoke
+//      form), never in the common path — the same "deterministic default, agent judgment as the escape
+//      hatch" grain as the capability probe's empirical verifier.
+//   2. TYPED EMIT — validate + coerce the completed form output against the node's declared `emits[]`
+//      (Decision 3/4 — binds are validated, not stringly), producing the typed facts the node hands
+//      forward. A "click done" node declares no emits — the degenerate no-emit case.
+//   3. LATE-BINDING — render the emitted facts into a downstream node's brief (`renderHumanEmitBrief`,
+//      mirroring `renderResolvedDepsBrief`) and into a qualified bind map keyed `<nodeId>.<fact>`
+//      (`humanEmitBind`, mirroring the probe `bind`) so a downstream `capability`/`npm`/`pr` edge
+//      binds and pins exactly the value the human handed forward.
+import type { DeliveryFact, DeliveryNodeHuman } from "../nano-generated/api-io.d.ts";
+import { DELIVERY_FACT_TYPES, type DeliveryFactType, FACT_NAME_MAX_LENGTH, FACT_NAME_PATTERN } from "./deliveryGraph.ts";
+
+/** The single BPMN `bpmn:userTask` element id every `human` delivery-graph node schedules its work
+ *  as (`resources/processes/delivery-human.bpmn`). One reusable engine-native body, instantiated once
+ *  per human node (mirroring the one `readiness-gate` process instantiated per `wait` node). It is
+ *  registered in `ESCALATION_TASK_ELEMENTS` (`app/agentCompletion.ts`) so a human OR an agent
+ *  (ADR 0046) can complete it through the ONE canonical `complete-user-task` / `agent-complete` door,
+ *  and in `USER_TASK_KIND_LABELS` (`app/userTasks.ts`) so it surfaces on the Tasks inbox. */
+export const DELIVERY_HUMAN_ELEMENT = "delivery-human-task";
+
+/** True for any user-task element id a delivery-graph `human` node schedules. The S3 static body
+ *  (`delivery-human.bpmn`) uses the bare `delivery-human-task` id, but the S4 compiler INLINES the
+ *  human body once per node into the one-shot process (embedded sub-processes — call activities are a
+ *  no-op on the pinned WASM engine, so a single shared static instance is not reusable), giving each a
+ *  UNIQUE convention id `delivery-human-task__<element>` (and its bounded-timeout escalation twin
+ *  `delivery-human-task__<element>__esc`). Exact-membership routing on the bare id would drop these, so
+ *  every surface that recognises a delivery human task (completion routing in `agentCompletion.ts`, the
+ *  Tasks-inbox label in `userTasks.ts`) matches through THIS one predicate — the single source of truth
+ *  for the id convention, so the compiler's id form and the routers can never drift apart. */
+export function isDeliveryHumanElement(elementId: string): boolean {
+  return elementId === DELIVERY_HUMAN_ELEMENT || elementId.startsWith(`${DELIVERY_HUMAN_ELEMENT}__`);
+}
+
+/** The GENERIC fallback form (Decision 4, step 3): captures ONE typed value into the node's single
+ *  declared emitted fact, so a human node with no explicit/category form can STILL emit downstream. */
+export const GENERIC_HUMAN_FORM = "delivery-human-generic";
+
+/** The "click done" category form: a degenerate no-emit acknowledgement ("now do X" → done). */
+export const HUMAN_ACK_FORM = "delivery-human-ack";
+
+/** The manual-publish category form: captures a `resolvedArtifact` (`pkg@version`) — the motivating
+ *  case where a human hands a just-published version forward to a downstream `capability`/`npm`/`pr`
+ *  edge. */
+export const HUMAN_PUBLISH_FORM = "delivery-human-publish";
+
+/** A human node's derived CATEGORY — a coarse classification of what the node emits, used to SELECT a
+ *  bespoke form (Decision 4, step 2) without the author naming one. Derived from the node's typed
+ *  `emits[]` so the same typed-fact declaration that drives late-binding also drives form selection —
+ *  one source of truth, no second author-facing knob (the frozen S0 `human` config carries only
+ *  `formKey`/`prompt`). `null` ⇒ no bespoke category form applies (fall through to generic/router). */
+export type HumanNodeCategory = "ack" | "publish";
+
+/** Category → its bespoke form. Kept as the single source of truth for "which form a category selects"
+ *  so {@link resolveHumanForm} and any preview/compile step agree. */
+export const HUMAN_CATEGORY_FORMS: Readonly<Record<HumanNodeCategory, string>> = {
+  ack: HUMAN_ACK_FORM,
+  publish: HUMAN_PUBLISH_FORM,
+};
+
+/** How a human node's form was resolved. `explicit` — the node named a `human.formKey`; `category` —
+ *  a form was selected by the node's derived category; `generic` — the typed-emit-capturing fallback;
+ *  `agent-router` — NOTHING statically resolved, so a runtime agent must pick/assemble one (the gated
+ *  exception). */
+export type HumanFormSource = "explicit" | "category" | "generic" | "agent-router";
+
+/** The resolved form for a human node (Decision 4). `formKey` is the `.form` to attach — `null` ONLY
+ *  for `agent-router`, where the runtime supplies it. `category` records the derived category when one
+ *  applied. `reason` is a human-readable one-liner for the compiled preview. */
+export interface HumanFormResolution {
+  readonly source: HumanFormSource;
+  readonly formKey: string | null;
+  readonly category: HumanNodeCategory | null;
+  readonly emits: readonly DeliveryFact[];
+  readonly reason: string;
+}
+
+/** A typed fact a completed human node hands forward — its declared `name`/`type` plus the validated,
+ *  canonically-serialised `value` (a string, like the probe `bind`, so it threads uniformly into
+ *  prompts, messages, and qualified bind maps). */
+export interface BoundFact {
+  readonly name: string;
+  readonly type: DeliveryFactType;
+  readonly value: string;
+}
+
+/** The outcome of binding a completed form's output to a node's declared emits: the typed `facts` in
+ *  declaration order plus any path-qualified `errors` (a missing/ill-typed declared fact). An empty
+ *  `emits` yields `{ facts: [], errors: [] }` — the degenerate no-emit "click done" case. */
+export interface HumanEmitResult {
+  readonly facts: readonly BoundFact[];
+  readonly errors: readonly string[];
+}
+
+/** Narrow an untyped value to a plain object so its fields can be read defensively. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** True when `value` is one of the closed set of delivery fact types (a type guard, so the pure
+ *  form/emit logic narrows without an `as` assertion). */
+function isDeliveryFactType(value: unknown): value is DeliveryFactType {
+  return typeof value === "string" && DELIVERY_FACT_TYPES.some((t) => t === value);
+}
+
+/** Normalise a human node's `emits[]` to the well-formed, typed declarations, dropping anything the
+ *  S0 validator would already have rejected (a non-record entry, a blank name, a name that is not a
+ *  dot-free identifier within the 128-char cap, a duplicate name, or an unknown type) so the pure
+ *  form/emit logic never trips on a malformed declaration — the graph is validated upstream by
+ *  `validateDeliveryGraph`, this is defence in depth. Fact-name pattern/length are the SAME canonical
+ *  constants the validator enforces (`FACT_NAME_PATTERN`/`FACT_NAME_MAX_LENGTH`), so a dotted /
+ *  over-long / duplicate name can't slip through here and make `<nodeId>.<fact>` binding ambiguous. */
+export function normalizeEmits(node: Pick<DeliveryNodeHuman, "emits">): DeliveryFact[] {
+  const raw = node.emits;
+  if (!Array.isArray(raw)) return [];
+  const facts: DeliveryFact[] = [];
+  const seen = new Set<string>();
+  for (const entry of raw) {
+    if (!isRecord(entry)) continue;
+    const name = entry.name;
+    const type = entry.type;
+    if (typeof name !== "string" || name.length === 0) continue;
+    if (name.length > FACT_NAME_MAX_LENGTH || !FACT_NAME_PATTERN.test(name)) continue;
+    if (seen.has(name)) continue;
+    if (!isDeliveryFactType(type)) continue;
+    seen.add(name);
+    facts.push({ name, type, ...(typeof entry.description === "string" ? { description: entry.description } : {}) });
+  }
+  return facts;
+}
+
+/** Derive a human node's CATEGORY from its typed emits (Decision 4, step 2), or `null` when no bespoke
+ *  category form applies:
+ *   - `ack` — the node emits NOTHING (a "click done" acknowledgement).
+ *   - `publish` — the node emits EXACTLY ONE `artifact` fact (a `pkg@version` handle — the manual-
+ *     publish-hands-a-version-forward case), which the bespoke publish form captures as a
+ *     `resolvedArtifact`. A lone `version` (a BARE version, e.g. `1.4.0`) does NOT map here: the
+ *     publish form captures a `pkg@version` into `resolvedArtifact`, which fails `version` coercion in
+ *     {@link bindHumanEmits} — so a single `version` falls through to the generic single-value form
+ *     (which captures a bare `value`, validated against the `version` type).
+ *   - `null` — a single non-artifact scalar/url/version fact (the generic fallback captures it), OR
+ *     two-or-more facts (no bespoke or generic single-value form can hold them → the agent-router
+ *     territory).
+ *  Kept coarse ON PURPOSE: bespoke category forms are a deterministic convenience, not an open
+ *  taxonomy; anything they don't cover falls through to the generic fallback or the gated router. */
+export function deriveHumanCategory(emits: readonly DeliveryFact[]): HumanNodeCategory | null {
+  if (emits.length === 0) return "ack";
+  if (emits.length === 1 && emits[0].type === "artifact") return "publish";
+  return null;
+}
+
+/** Resolve which form a human node uses, specific-else-generic (ADR 0005 Decision 4). Preference:
+ *    1. `explicit`     — the node carries a non-blank `human.formKey`.
+ *    2. `category`     — the node's derived category selects a bespoke form ({@link deriveHumanCategory}).
+ *    3. `generic`      — the node emits ≤1 fact, captured by the generic typed-emit fallback form.
+ *    4. `agent-router` — NOTHING statically resolved (≥2 heterogeneous emits, no explicit/bespoke
+ *                        form): a runtime agent must pick/assemble a form. This is the GATED escape
+ *                        hatch — it fires ONLY here, never in the common path.
+ *  Pure and total (never throws): the graph is shape/semantic-validated upstream, and malformed emits
+ *  are normalised away, so this always returns a resolution. Author-time callers (the S1 compiler)
+ *  attach `formKey` deterministically so the resolved form is visible in the preview; only the
+ *  `agent-router` case defers to runtime. */
+export function resolveHumanForm(node: Pick<DeliveryNodeHuman, "emits" | "human">): HumanFormResolution {
+  const emits = normalizeEmits(node);
+  const explicit = node.human?.formKey;
+  if (typeof explicit === "string" && explicit.trim().length > 0) {
+    return {
+      source: "explicit",
+      formKey: explicit.trim(),
+      category: null,
+      emits,
+      reason: `explicit form "${explicit.trim()}" attached on the node`,
+    };
+  }
+  const category = deriveHumanCategory(emits);
+  if (category !== null) {
+    return {
+      source: "category",
+      formKey: HUMAN_CATEGORY_FORMS[category],
+      category,
+      emits,
+      reason:
+        category === "ack"
+          ? "no emitted fact — the generic acknowledgement (click-done) form"
+          : `emits a single ${emits[0].type} fact — the manual-publish form (captures a resolvedArtifact)`,
+    };
+  }
+  if (emits.length <= 1) {
+    return {
+      source: "generic",
+      formKey: GENERIC_HUMAN_FORM,
+      category: null,
+      reason: `emits a single ${emits[0].type} fact — the generic typed-emit fallback form`,
+      emits,
+    };
+  }
+  return {
+    source: "agent-router",
+    formKey: null,
+    category: null,
+    emits,
+    reason:
+      `emits ${emits.length} typed facts and carries no explicit/bespoke form — no static form can ` +
+      "capture them, so a runtime agent-form-router must assemble one (the gated exception)",
+  };
+}
+
+/** True when a human node resolves to the gated runtime agent-form-router — i.e. nothing statically
+ *  resolved. A thin predicate over {@link resolveHumanForm} so callers can branch without re-deriving. */
+export function needsAgentFormRouter(node: Pick<DeliveryNodeHuman, "emits" | "human">): boolean {
+  return resolveHumanForm(node).source === "agent-router";
+}
+
+/** The canonical form-field keys a bespoke/generic form captures its single typed value under, tried
+ *  (in addition to the fact's own name) when binding a single-fact node's output. The generic form
+ *  captures `value`; the publish form captures `resolvedArtifact`. */
+const CANONICAL_VALUE_KEYS = ["resolvedArtifact", "value"] as const;
+
+/** The ONE accepted shape of a bare version string (an optional `v` then a digit-led `[\w.+-]` run,
+ *  e.g. `1.4.0`, `v2.0.0-rc.1`). The single source of truth shared by the `version` fact type AND the
+ *  version segment of an `artifact` handle — so a `pkg@version` artifact validates its version the
+ *  same way a bare `version` does, with no second notion of "valid version" to drift. */
+const VERSION_PATTERN = /^v?\d[\w.+-]*$/;
+
+/** Coerce + validate one raw form value against a declared fact type, returning the canonical string
+ *  serialisation or an error message. Typed so a bind is validated, not stringly (Decision 3/4): an
+ *  `artifact` must be `pkg@version` (with a well-formed version segment), a `version` a bare version, a
+ *  `url` a parseable location, a `number` finite, a `boolean` a real boolean. */
+function coerceFactValue(type: DeliveryFactType, raw: unknown): { value: string } | { error: string } {
+  switch (type) {
+    case "string": {
+      if (typeof raw !== "string" || raw.trim() === "") return { error: "expected a non-empty string" };
+      // Return the trimmed value, mirroring the other string-like types (version/artifact/url) so the
+      // canonical serialisation does not depend on incidental surrounding whitespace.
+      return { value: raw.trim() };
+    }
+    case "number": {
+      const n = typeof raw === "number" ? raw : typeof raw === "string" && raw.trim() !== "" ? Number(raw) : Number.NaN;
+      if (!Number.isFinite(n)) return { error: "expected a finite number" };
+      return { value: String(n) };
+    }
+    case "boolean": {
+      if (typeof raw === "boolean") return { value: String(raw) };
+      // Trim before validating, mirroring the other string-like types (version/artifact/url) so a
+      // boolean captured via the generic textfield (e.g. " true ") is not needlessly brittle.
+      const trimmed = typeof raw === "string" ? raw.trim() : raw;
+      if (trimmed === "true" || trimmed === "false") return { value: trimmed };
+      return { error: "expected a boolean (true/false)" };
+    }
+    case "version": {
+      if (typeof raw !== "string" || !VERSION_PATTERN.test(raw.trim())) {
+        return { error: "expected a version string (e.g. 1.4.0)" };
+      }
+      return { value: raw.trim() };
+    }
+    case "artifact": {
+      if (typeof raw !== "string") return { error: "expected a pkg@version artifact handle" };
+      const at = raw.trim().lastIndexOf("@");
+      const name = raw.trim().slice(0, at);
+      const version = raw.trim().slice(at + 1);
+      if (at <= 0 || name.length === 0 || version.length === 0 || !VERSION_PATTERN.test(version)) {
+        return { error: "expected a pkg@version artifact handle (e.g. @nanobpm/urban@0.54.0)" };
+      }
+      return { value: raw.trim() };
+    }
+    case "url": {
+      if (typeof raw !== "string" || raw.trim() === "") return { error: "expected a URL" };
+      try {
+        new URL(raw.trim());
+      } catch {
+        return { error: "expected a valid URL (with a scheme)" };
+      }
+      return { value: raw.trim() };
+    }
+    default:
+      return { error: `unknown fact type "${type}"` };
+  }
+}
+
+/** Bind a completed human node's form `output` to its declared `emits[]` (Decision 3/4). For each
+ *  declared fact, read its value from the output — preferring the fact's own `name` key, then, for a
+ *  single-fact node, the canonical capture keys the generic/publish forms use (`resolvedArtifact` /
+ *  `value`) — and validate/coerce it against the fact's type. Returns the typed facts in declaration
+ *  order plus one error per missing/ill-typed declared fact. A node with no declared emits yields no
+ *  facts and no errors (the degenerate "click done" case) regardless of what the form captured.
+ *
+ *  This is the typed-emit contract the runner (S4) enforces on completion before threading the facts
+ *  downstream via {@link humanEmitBind} / {@link renderHumanEmitBrief} — the emit-side of #263. */
+export function bindHumanEmits(
+  emits: readonly DeliveryFact[],
+  output: Record<string, unknown> | null | undefined,
+): HumanEmitResult {
+  const out = isRecord(output) ? output : {};
+  const facts: BoundFact[] = [];
+  const errors: string[] = [];
+  const single = emits.length === 1;
+  for (const fact of emits) {
+    let raw = out[fact.name];
+    if (raw === undefined && single) {
+      for (const key of CANONICAL_VALUE_KEYS) {
+        if (out[key] !== undefined) {
+          raw = out[key];
+          break;
+        }
+      }
+    }
+    if (raw === undefined || raw === null) {
+      errors.push(`emits.${fact.name}: no value captured for the declared ${fact.type} fact`);
+      continue;
+    }
+    const coerced = coerceFactValue(fact.type, raw);
+    if ("error" in coerced) {
+      errors.push(`emits.${fact.name}: ${coerced.error}`);
+      continue;
+    }
+    facts.push({ name: fact.name, type: fact.type, value: coerced.value });
+  }
+  return { facts, errors };
+}
+
+/** Build the qualified bind map a human node's emitted facts publish downstream, keyed exactly as a
+ *  delivery edge references them — `<nodeId>.<fact>` (mirroring the probe `bind: Record<string,string>`
+ *  and the `capability` kind's `resolvedArtifact`). A downstream edge `from: "<nodeId>.<fact>"` binds
+ *  and PINS the human-handed value from this map. Empty for a no-emit node. */
+export function humanEmitBind(nodeId: string, facts: readonly BoundFact[]): Record<string, string> {
+  const bind: Record<string, string> = {};
+  for (const fact of facts) bind[`${nodeId}.${fact.name}`] = fact.value;
+  return bind;
+}
+
+/** Neutralise a human-submitted value before it is embedded in a Markdown inline-code span in the
+ *  brief. A raw backtick would terminate the span (corrupting the brief and letting free-form form
+ *  text inject unintended prompt content into the downstream agent's prompt), and a newline would
+ *  break the span; collapse both. Display-only — the authoritative value published downstream via
+ *  {@link humanEmitBind} is untouched, so the pinned contract is unaffected. */
+function inlineCodeSafe(value: string): string {
+  return value.replace(/`/g, "'").replace(/\r?\n/g, " ");
+}
+
+/** Render the "human-emitted facts" brief appended to a downstream node's prompt once a human node
+ *  completes and hands its typed facts forward (#289 §3), mirroring `renderResolvedDepsBrief`. It pins
+ *  each `name → value` the human declared + captured so a downstream agent/edge consumes EXACTLY that
+ *  value — no re-derivation, no human re-entry. Returns "" for a no-emit node so callers concatenate
+ *  unconditionally (the same `if X = null then "" else X` FEEL convention as the other briefs). */
+export function renderHumanEmitBrief(facts: readonly BoundFact[]): string {
+  if (facts.length === 0) return "";
+  const lines = [
+    "",
+    "",
+    "---",
+    "",
+    "**Human-emitted facts (authoritative — a scheduled human step handed these forward):**",
+    "",
+    "A `human` node upstream captured and emitted the typed values below. Consume/pin exactly these —",
+    "do NOT re-derive, float, or re-request them:",
+    "",
+  ];
+  for (const fact of facts) lines.push(`- \`${fact.name}\` (${fact.type}) → \`${inlineCodeSafe(fact.value)}\``);
+  lines.push("");
+  lines.push("These are the contract the human handed forward; a different value is a different run.");
+  return lines.join("\n");
+}

package/app/deliveryRunner.test.ts

@@ -0,0 +1,111 @@
+// Unit coverage for the delivery-graph RUNNER's PURE prepare step (ADR 0005 slice S4). `prepareDeliveryGraph`
+// compiles a graph, content-addresses its deploy id, rewrites the base process id, and builds the
+// `nodeInputs` seed — all without touching the engine. These tests pin, directly:
+//   • the content-addressed id (`delivery-graph-<sha12>`), and that it is DETERMINISTIC (same graph → same
+//     id) but CONTENT-SENSITIVE (a different graph → a different id) — the property that makes redeploy
+//     idempotent and stale definitions GC-identifiable (the ADR definition-lifecycle open question),
+//   • the base process id is rewritten to the content-addressed id in the deployable BPMN,
+//   • each node kind seeds the exact `nodeInputs` fields its compiled subProcess ioMapping reads,
+//   • a malformed graph returns the S1 compile errors and prepares nothing.
+// The engine-native EXECUTION of a prepared graph (deploy + run + gate + fan-in + late-bind + dedupe) is
+// proven end-to-end in `e2e/delivery-graph.e2e.ts`.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { prepareDeliveryGraph, runDeliveryGraph } from "./deliveryRunner.ts";
+import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+
+const GRAPH: DeliveryGraph = {
+  name: "release runbook",
+  nodes: [
+    { id: "open-b", kind: "agent", agent: { jobType: "senior:feature", prompt: "un-draft + merge #B" } },
+    { id: "watch-b", kind: "wait", wait: { kind: "pr", target: "owner/repo#42", match: { prState: "merged" } }, emits: [{ name: "mergedSha", type: "string" }] },
+    { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish" }, emits: [{ name: "resolvedArtifact", type: "artifact" }] },
+    { id: "consume", kind: "connector", connector: { target: "npm:install", dedupeKey: "consume-1" } },
+  ],
+  edges: [
+    { from: "open-b", to: "watch-b" },
+    { from: "watch-b.mergedSha", to: "publish" },
+    { from: "publish.resolvedArtifact", to: "consume" },
+  ],
+};
+
+function prepareOk(graph: DeliveryGraph, options = {}) {
+  const r = prepareDeliveryGraph(graph, options);
+  assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
+  return r.prepared;
+}
+
+test("content-addressed id: deterministic for the same graph, content-sensitive across graphs", () => {
+  const a = prepareOk(GRAPH);
+  const b = prepareOk(GRAPH);
+  assert(/^delivery-graph-[0-9a-f]{12}$/.test(a.processDefinitionId), `id is content-addressed, got ${a.processDefinitionId}`);
+  assertEquals(a.processDefinitionId, b.processDefinitionId);
+
+  // A structurally different graph gets a DIFFERENT id (no collision / no accidental redeploy-as-same).
+  const other = prepareOk({ ...GRAPH, nodes: [...GRAPH.nodes, { id: "extra", kind: "agent", agent: { jobType: "senior:feature" } }], edges: [...GRAPH.edges, { from: "consume", to: "extra" }] });
+  assert(other.processDefinitionId !== a.processDefinitionId, "a different graph yields a different id");
+});
+
+test("the deployable BPMN rewrites the base process id to the content-addressed deploy id", () => {
+  const p = prepareOk(GRAPH);
+  assert(p.bpmn.includes(`<bpmn:process id="${p.processDefinitionId}"`), "process id is the content-addressed id");
+  assert(!p.bpmn.includes('<bpmn:process id="delivery-graph"'), "the base id no longer appears as the process id");
+});
+
+test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMapping reads", () => {
+  const p = prepareOk(GRAPH, { nodeTimeout: "PT10M", probeTimeout: "PT20M", escalationSlaTimeout: "PT2H", escalationAssignee: "alice", runKey: "run-7" });
+  // Element ids are positional by sorted node id: consume, open-b, publish, watch-b → n0..n3.
+  const inputs = p.nodeInputs;
+  const byField = (pred: (v: Record<string, unknown>) => boolean) => Object.values(inputs).find((v) => pred(v as Record<string, unknown>)) as Record<string, unknown> | undefined;
+
+  const agent = byField((v) => v.jobType === "senior:feature");
+  assertEquals(agent, { jobType: "senior:feature", appendPrompt: "un-draft + merge #B", timeout: "PT10M" });
+
+  const wait = byField((v) => "gateKey" in v);
+  assertEquals(wait?.gateKey, "run-7:n3");
+  assertEquals(wait?.probeTimeout, "PT20M");
+  assert(wait?.probe && typeof wait.probe === "object", "the wait node carries its ReadinessProbe descriptor");
+
+  const human = byField((v) => "escalationSlaTimeout" in v);
+  assertEquals(human, { escalationSlaTimeout: "PT2H", escalationAssignee: "alice" });
+
+  const connector = byField((v) => v.target === "npm:install");
+  assertEquals(connector, { target: "npm:install", dedupeKey: "consume-1", payload: null, timeout: "PT10M" });
+});
+
+test("wait gateKeys default to a fresh per-run token so concurrent runs of one graph never cross-correlate", () => {
+  const gateKeyOf = (p: ReturnType<typeof prepareOk>) =>
+    (Object.values(p.nodeInputs).find((v) => "gateKey" in v) as { gateKey?: string } | undefined)?.gateKey;
+
+  const a = prepareOk(GRAPH);
+  const b = prepareOk(GRAPH);
+  assert(gateKeyOf(a) && gateKeyOf(b), "each run seeds a wait gateKey");
+  assert(gateKeyOf(a) !== gateKeyOf(b), "two runs of the same graph get DISTINCT default gate scopes");
+  // The gate key must NOT be derived from the (shared) content digest — that is the bug this guards.
+  assert(!gateKeyOf(a)?.startsWith(a.processDefinitionId.slice(-12)), "default gateKey is not the graph digest");
+  // The deployable definition (id + bpmn) stays deterministic regardless of the per-run gate scope.
+  assertEquals(a.processDefinitionId, b.processDefinitionId);
+  assertEquals(a.bpmn, b.bpmn);
+
+  // An explicit runKey is honoured verbatim (reproducible seed).
+  const seeded = prepareOk(GRAPH, { runKey: "run-7" });
+  assertEquals(gateKeyOf(seeded), "run-7:n3");
+});
+
+test("a malformed graph returns the S1 compile errors and prepares nothing", () => {
+  const r = prepareDeliveryGraph({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }], edges: [{ from: "a", to: "ghost" }] } as unknown as DeliveryGraph);
+  assert(!r.ok, "a dangling edge fails to prepare");
+  assert(r.errors.some((e) => e.path === "edges[0].to"), `expected a dangling-edge error, got ${JSON.stringify(r.errors)}`);
+});
+
+test("runDeliveryGraph coerces a numeric engine processInstanceKey to a string handle", async () => {
+  // The engine can yield a NUMERIC key; the handle is typed `string` and downstream expects a string.
+  const engine = {
+    deployResources: async () => [],
+    createInstance: async () => ({ processInstanceKey: 987654321 as unknown as string }),
+  };
+  const r = await runDeliveryGraph(engine, GRAPH);
+  assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
+  assertEquals(r.handle.processInstanceKey, "987654321");
+  assertEquals(typeof r.handle.processInstanceKey, "string");
+});