@nanobpm/nano-workforce 0.113.0 → 0.114.0

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

package/app/deliveryRunner.ts

@@ -0,0 +1,169 @@
+// nano-workforce — the delivery-graph RUNNER (ADR 0005 slice S4). The integration step that turns the
+// PURE compiled preview (S1's `compileDeliveryGraph`) into a RUNNING, engine-native process: it deploys
+// the compile-to-native one-shot definition and starts an instance, seeding each node's config so the
+// inlined subProcess bodies (agent/wait/human/connector) delegate to their existing worker / user-task
+// bodies. It builds NO execution machinery of its own (Decision 2 — the graph SCHEDULES; the engine
+// runs it); its whole job is deploy + seed + start.
+//
+// Definition lifecycle (the ADR open question, resolved here): the deployed process id is
+// CONTENT-ADDRESSED — `delivery-graph-<sha256(bpmn)[:12]>`. Identical graphs compile byte-identically
+// (S1 determinism) → identical id → an idempotent redeploy (the engine versions the same id, never a
+// duplicate definition per run); different graphs get different ids and never collide; and because the
+// id ENCODES its content, a stale one-shot definition is GC-identifiable by a later sweeper (out of
+// scope to implement the sweeper — the naming is what enables it). The base id the compiler emits
+// (`DELIVERY_GRAPH_PROCESS_ID`) is the single substitution target, so the runner never hardcodes it.
+
+import { createHash, randomUUID } from "node:crypto";
+import type { EngineClient } from "@nanobpm/urban";
+import type { DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
+import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
+
+/** The bounded-timeout / SLA envelope every node inherits (Decision: bounded → escalate). ISO-8601
+ * durations. Defaults are conservative; a caller (the S5 door) may tighten them per run. */
+export interface DeliveryRunTimeouts {
+  /** `agent`/`connector` service-node bounded timeout before it escalates onto a human-completable task. */
+  nodeTimeout?: string;
+  /** `wait` gate poll budget before it escalates (the engine bound; the probe itself is read-only). */
+  probeTimeout?: string;
+  /** `human` node SLA before it records an `escalated` outcome and settles. */
+  escalationSlaTimeout?: string;
+  /** Optional explicit assignee for `human` nodes + escalation tasks (else candidate-group routed). */
+  escalationAssignee?: string | null;
+}
+
+export interface DeliveryRunOptions extends DeliveryRunTimeouts {
+  /** A per-run token that scopes each `wait` node's gate key (`<runKey>:<element>`) so two concurrent
+   * runs of the same graph never share a gate correlation. Defaults to a fresh random per-run token
+   * (`randomUUID()`) — NOT the graph digest, which every run of an identical graph would share and so
+   * cross-correlate. Pass an explicit `runKey` only when you need a reproducible/externally-owned gate
+   * scope. */
+  runKey?: string;
+}
+
+const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
+  nodeTimeout: "PT30M",
+  probeTimeout: "PT30M",
+  escalationSlaTimeout: "P1D",
+};
+
+/** The per-node config the compiled subProcess ioMappings read from `nodeInputs.<element>`. A closed
+ * union mirrored by the compiler's `ioMappingLines` — the two must agree on field names (a drift here
+ * silently seeds `null` into a node body), so both derive from the same node kinds. */
+type NodeInput =
+  | { jobType: string; appendPrompt: string; timeout: string }
+  | { gateKey: string; probe: unknown; probeTimeout: string }
+  | { escalationSlaTimeout: string; escalationAssignee: string | null }
+  | { target: string; dedupeKey: string | null; payload: Record<string, unknown> | null; timeout: string };
+
+/** The result of compiling + preparing a graph for deployment: the content-addressed process id, the
+ * deployable BPMN (base id rewritten), and the seeded `nodeInputs` map — everything `runDeliveryGraph`
+ * needs, exposed separately so a caller can deploy/inspect without starting an instance. */
+export interface PreparedDeliveryGraph {
+  processDefinitionId: string;
+  bpmn: string;
+  nodeInputs: Record<string, NodeInput>;
+}
+
+export type PrepareDeliveryResult =
+  | { ok: true; prepared: PreparedDeliveryGraph }
+  | { ok: false; errors: { path: string; message: string }[] };
+
+/** A live delivery-graph run: the deployed definition + the started instance + the seed it ran with. */
+export interface DeliveryRunHandle extends PreparedDeliveryGraph {
+  processInstanceKey: string;
+}
+
+export type RunDeliveryResult =
+  | { ok: true; handle: DeliveryRunHandle }
+  | { ok: false; errors: { path: string; message: string }[] };
+
+/** Compile a graph and prepare it for deployment WITHOUT touching the engine: content-address its id,
+ * rewrite the base process id, and build the `nodeInputs` seed. The deployable DEFINITION (the
+ * content-addressed `processDefinitionId` and the `bpmn`) is deterministic — the same graph yields the
+ * same id, which is what makes redeploy idempotent — because the gate scope lives in `nodeInputs`
+ * (runtime instance variables), not in the BPMN. The default `runKey` is a fresh random per-run token,
+ * so each call's `wait` `gateKey`s differ (two concurrent runs of the same graph never cross-correlate);
+ * pass an explicit `runKey` for a reproducible seed. Returns the S1 compile errors verbatim for a
+ * malformed graph. */
+export function prepareDeliveryGraph(graph: DeliveryGraph, options: DeliveryRunOptions = {}): PrepareDeliveryResult {
+  const compiled = compileDeliveryGraph(graph);
+  if (!compiled.ok) return { ok: false, errors: compiled.errors };
+
+  const digest = createHash("sha256").update(compiled.bpmn).digest("hex").slice(0, 12);
+  const processDefinitionId = `${DELIVERY_GRAPH_PROCESS_ID}-${digest}`;
+  const bpmn = rewriteProcessId(compiled.bpmn, processDefinitionId);
+
+  const runKey = options.runKey?.trim() || randomUUID();
+  const timeouts = {
+    nodeTimeout: options.nodeTimeout ?? DEFAULTS.nodeTimeout,
+    probeTimeout: options.probeTimeout ?? DEFAULTS.probeTimeout,
+    escalationSlaTimeout: options.escalationSlaTimeout ?? DEFAULTS.escalationSlaTimeout,
+    escalationAssignee: options.escalationAssignee ?? null,
+  };
+  const elementByNodeId = new Map(compiled.resolved.nodes.map((n) => [n.id, n.element]));
+  const nodeInputs: Record<string, NodeInput> = {};
+  for (const node of graph.nodes) {
+    const element = elementByNodeId.get(node.id);
+    if (element === undefined) continue; // unreachable — resolved covers every node — but keep total.
+    nodeInputs[element] = buildNodeInput(node, { runKey, element, ...timeouts });
+  }
+  return { ok: true, prepared: { processDefinitionId, bpmn, nodeInputs } };
+}
+
+/** Deploy + start a compiled graph as a running engine-native instance. Idempotent at the DEFINITION
+ * level (content-addressed id — redeploying the same graph re-uses the definition); each call still
+ * starts a fresh INSTANCE (a distinct run of that definition). Returns the run handle, or the compile
+ * errors for a malformed graph (the engine is never touched in that case). */
+export async function runDeliveryGraph(
+  engine: Pick<EngineClient, "deployResources" | "createInstance">,
+  graph: DeliveryGraph,
+  options: DeliveryRunOptions = {},
+): Promise<RunDeliveryResult> {
+  const prep = prepareDeliveryGraph(graph, options);
+  if (!prep.ok) return prep;
+  const { processDefinitionId, bpmn, nodeInputs } = prep.prepared;
+
+  await engine.deployResources([{ name: `${processDefinitionId}.bpmn`, content: bpmn, contentType: "application/xml" }]);
+  const { processInstanceKey } = await engine.createInstance({
+    processDefinitionId,
+    variables: { nodeInputs },
+  });
+  // The engine can yield a numeric key; `DeliveryRunHandle.processInstanceKey` is typed `string` and
+  // downstream consumers expect a string — coerce (codebase-wide `String(...)` pattern, e.g. app/plan.ts).
+  return {
+    ok: true,
+    handle: { processDefinitionId, bpmn, nodeInputs, processInstanceKey: String(processInstanceKey) },
+  };
+}
+
+/** Rewrite the compiled BPMN's base `bpmn:process` id to the content-addressed deploy id. The base id
+ * appears exactly once — as the process element's `id` attribute (element ids are `n<i>`/`gw*`/`Start`/
+ * `End`, never the process id) — so a single targeted replacement is unambiguous. */
+function rewriteProcessId(bpmn: string, processDefinitionId: string): string {
+  return bpmn.replace(`id="${DELIVERY_GRAPH_PROCESS_ID}"`, `id="${processDefinitionId}"`);
+}
+
+/** Build the `nodeInputs.<element>` seed for one node, per its kind — the exact fields the compiled
+ * subProcess ioMapping pulls. Total over the closed kind set. */
+function buildNodeInput(
+  node: DeliveryNode,
+  ctx: { runKey: string; element: string; nodeTimeout: string; probeTimeout: string; escalationSlaTimeout: string; escalationAssignee: string | null },
+): NodeInput {
+  switch (node.kind) {
+    case "agent":
+      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: ctx.nodeTimeout };
+    case "wait":
+      return { gateKey: `${ctx.runKey}:${ctx.element}`, probe: node.wait, probeTimeout: ctx.probeTimeout };
+    case "human":
+      return { escalationSlaTimeout: ctx.escalationSlaTimeout, escalationAssignee: ctx.escalationAssignee };
+    case "connector":
+      return {
+        target: node.connector.target,
+        dedupeKey: node.connector.dedupeKey ?? null,
+        payload: node.connector.payload ?? null,
+        timeout: ctx.nodeTimeout,
+      };
+    default:
+      return assertNever(node, "buildNodeInput");
+  }
+}

package/app/userTasks.test.ts

@@ -6,6 +6,7 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
+import { DELIVERY_HUMAN_ELEMENT } from "./deliveryHuman.ts";
 import type { PlanReview } from "./plan.ts";
 import type { TrialMergeAuditRow } from "./trialMerge.ts";
 import {
@@ -19,6 +20,7 @@ import {
   type PrEscalationRow,
   reconcileUserTasks,
   TRIAL_MERGE_ELEMENT,
+  userTaskKindLabel,
   type UserTaskRow,
 } from "./userTasks.ts";
 
@@ -91,6 +93,40 @@ test("buildUserTaskRow: an unknown (non-escalation) element yields null — no a
   assertEquals(row, null);
 });
 
+test("userTaskKindLabel/buildUserTaskRow: an INLINED delivery-human element surfaces under one label; a non-matching internal task is dropped (app/userTasks.ts:122)", () => {
+  // The S4 compiler inlines each `human` node (and its bounded-timeout escalation twin) with a
+  // per-node id `delivery-human-task__<el>[__esc]`, which a bare `USER_TASK_KIND_LABELS` lookup would
+  // miss — so the delivery-human convention MUST be recognised through `isDeliveryHumanElement`.
+  const LABEL = "Delivery: human step";
+  // The bare static body id and both inlined conventions resolve to the one delivery-human label…
+  assertEquals(userTaskKindLabel(DELIVERY_HUMAN_ELEMENT), LABEL);
+  assertEquals(userTaskKindLabel(`${DELIVERY_HUMAN_ELEMENT}__ship-it`), LABEL);
+  assertEquals(userTaskKindLabel(`${DELIVERY_HUMAN_ELEMENT}__ship-it__esc`), LABEL);
+  // …while a non-matching internal task (a near-miss that is NOT the delivery-human prefix) is not a
+  // surfaced kind, so it never leaks into the inbox.
+  assertEquals(userTaskKindLabel("delivery-human-taskish"), undefined);
+  assertEquals(userTaskKindLabel("some-internal-task"), undefined);
+
+  // And end-to-end through the row builder: an inlined delivery-human task projects a labelled row…
+  const inlined = buildUserTaskRow(
+    { userTaskKey: "ut-dh", elementId: `${DELIVERY_HUMAN_ELEMENT}__ship-it`, subjectType: "delivery", subjectKey: "graph-1", question: "approve the release?" },
+    AT,
+  );
+  assert(inlined !== null);
+  assertEquals(inlined?.element_id, `${DELIVERY_HUMAN_ELEMENT}__ship-it`);
+  assertEquals(inlined?.kind_label, LABEL);
+  assertEquals(inlined?.subject_type, "delivery");
+  assertEquals(inlined?.question, "approve the release?");
+  // …whereas a non-matching internal task still yields null (the leak guard holds for the near-miss).
+  assertEquals(
+    buildUserTaskRow(
+      { userTaskKey: "ut-dh2", elementId: "delivery-human-taskish", subjectType: "delivery", subjectKey: "graph-1" },
+      AT,
+    ),
+    null,
+  );
+});
+
 test("buildUserTaskRow: a blank userTaskKey yields null; a known kind with a blank subject key still builds (issue #358)", () => {
   // The completable key is load-bearing (the page completes THROUGH it), so a blank one is still null.
   assertEquals(

package/app/userTasks.ts

@@ -19,7 +19,7 @@
 // it open.
 import type { DataLayer } from "@nanobpm/urban";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
-import { DELIVERY_HUMAN_ELEMENT } from "./deliveryHuman.ts";
+import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, type FeatureEscalationRow } from "./feature.ts";
 import type { PlanReview } from "./plan.ts";
 import type { TrialMergeAuditRow } from "./trialMerge.ts";
@@ -80,6 +80,16 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [DELIVERY_HUMAN_ELEMENT]: "Delivery: human step",
 };
 
+/** The Tasks-inbox label for an open user-task `elementId`, or `undefined` when the element is not a
+ *  surfaced kind (so an arbitrary internal user task is never listed). Exact table lookup PLUS the
+ *  delivery-human convention: the S4 compiler inlines each `human` node (and each service node's
+ *  bounded-timeout escalation twin) with a per-node id `delivery-human-task__<el>[__esc]`, which a bare
+ *  table lookup would miss — matched through the single-source-of-truth `isDeliveryHumanElement`
+ *  predicate so every inlined human/escalation task surfaces under the one delivery-human label. */
+export function userTaskKindLabel(elementId: string): string | undefined {
+  return USER_TASK_KIND_LABELS[elementId] ?? (isDeliveryHumanElement(elementId) ? USER_TASK_KIND_LABELS[DELIVERY_HUMAN_ELEMENT] : undefined);
+}
+
 /** The denormalised context the poller has resolved for an open escalation user task. */
 export interface UserTaskContext {
   userTaskKey: string;
@@ -108,7 +118,7 @@ export interface UserTaskContext {
  *  tasks out of the inbox). */
 export function buildUserTaskRow(ctx: UserTaskContext, at: string = now()): UserTaskRow | null {
   const userTaskKey = ctx.userTaskKey.trim();
-  const kindLabel = USER_TASK_KIND_LABELS[ctx.elementId];
+  const kindLabel = userTaskKindLabel(ctx.elementId);
   if (!userTaskKey || !kindLabel) return null;
   const subjectKey = ctx.subjectKey.trim() || (ctx.processKey ?? "").trim() || userTaskKey;
   const question = typeof ctx.question === "string" && ctx.question.trim() ? ctx.question.trim() : null;

package/db/migrations/055_delivery_connector_dedupe.sql

@@ -0,0 +1,26 @@
+-- The delivery-graph `connector` node's idempotency ledger (ADR 0005 Decision 6/7, slice S4). A
+-- `connector` is the epic's one SIDE-EFFECTING node kind (`agent`/`wait`/`human` are read-only or
+-- human-gated): it drives an outbound action against the forward-declared connector I/O surface. The
+-- engine delivers a service-task job AT-LEAST-ONCE — a worker/hub restart, a lost completion ack, or a
+-- graph resume re-activates the same job — so a naive connector would double-fire its side effect on
+-- every redelivery. This ledger makes each dispatch fire AT-MOST-ONCE per dedupe key: the worker
+-- claims the key here BEFORE performing the action, and a redelivery that finds the key already
+-- claimed short-circuits to the recorded outcome instead of re-dispatching.
+--
+-- The UNIQUE fence on `dedupe_key` is the durable at-most-once guarantee (the canonical durable-fence
+-- idiom — cf. `ux_merges_abandon_pr_closed` in 053 and the world-store ledgers in 049): a concurrent
+-- redelivery that races the claim loses the insert and is classified by `app/dbFence.ts`
+-- (`isUniqueConstraintFence`) as the SAME idempotent outcome, never a spurious job failure. The key is
+-- author-supplied (`connector.dedupeKey`) or graph-derived (`<processInstanceKey>:<elementId>`) — both
+-- stable across a re-activation of the same node instance.
+CREATE TABLE IF NOT EXISTS delivery_connector_dispatches (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  dedupe_key TEXT NOT NULL,
+  target TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  detail TEXT,
+  dispatched_at TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS ux_delivery_connector_dedupe
+  ON delivery_connector_dispatches (dedupe_key);

package/e2e/delivery-graph.e2e.ts

@@ -0,0 +1,197 @@
+// End-to-end proof that a COMPILED delivery graph deploys and runs ENGINE-NATIVELY on the WASM engine
+// + virtual clock (ADR 0005 slice S4) — the integration acceptance the whole slice hinges on. Driven
+// via `bootTestApp`, hermetic (deterministic shell-builtin `command` probes, no network, no GitHub;
+// the `pr` kind's merge-state semantics are S2's surface, proven there — S4 proves the wait NODE
+// executes engine-natively and gates, whatever the probe kind):
+//
+//   • RUNS END-TO-END + FAN-IN + LATE-BIND: a graph with `agent`, `wait`, `human` and `connector`
+//     nodes deploys and runs; the agent job fires, the wait gate resolves, the human task completes,
+//     the connector fires — and the graph reaches End only after the wait AND the human both feed the
+//     connector (fan-in). The human's emitted `artifact` fact LATE-BINDS into the connector's input.
+//   • RESUME NEVER DOUBLE-FIRES: after the connector has fired once, an at-least-once redelivery of the
+//     same dispatch (a resume) DEDUPES — the durable ledger still holds exactly one row (Decision 7).
+//   • CONCURRENCY-CORRECTNESS: while a `wait` is parked on a never-green probe, completing an UNRELATED
+//     parallel human node does NOT falsely resolve the wait (the node polls its OWN target — there is no
+//     shared message correlation an unrelated event could trip, inheriting #274/S2); the wait stays
+//     parked until its bounded budget elapses, then escalates (bounded → escalate, never wedged).
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { connectorDedupeKey, deliveryConnectorDispatches, dispatchConnector } from "../app/deliveryConnector.ts";
+import { readConnectorInput } from "../workers/delivery-connector/worker.ts";
+import { runDeliveryGraph } from "../app/deliveryRunner.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 TakenFlow {
+  from: string;
+  to: string;
+}
+function takenFlows(app: TestApp): string[] {
+  const snap = app.snapshot();
+  const flows = Array.isArray(snap.takenSequenceFlows) ? snap.takenSequenceFlows : [];
+  return flows
+    .filter((f): f is TakenFlow => typeof f === "object" && f !== null && "from" in f && "to" in f)
+    .map((f) => `${f.from}->${f.to}`);
+}
+
+/** Boot a fresh app per scenario (the WASM engine's taken-flow snapshot is engine-global cumulative). */
+async function boot(dir: string): Promise<TestApp> {
+  return bootTestApp(APP_ROOT, { env: { ...GITHUB_ENV, NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+}
+
+describe("delivery-graph runner — engine-native execution (S4)", () => {
+  const dirs: string[] = [];
+  const apps: TestApp[] = [];
+  const freshDir = (): string => {
+    const d = mkdtempSync(join(tmpdir(), "nwf-delivery-e2e-"));
+    dirs.push(d);
+    return d;
+  };
+  const track = (app: TestApp): TestApp => {
+    apps.push(app);
+    return app;
+  };
+  after(async () => {
+    for (const app of apps) await app.stop?.();
+    for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  });
+
+  test("runs end-to-end: agent, wait, human execute; edges gate; fan-in works; human fact late-binds into the connector", async () => {
+    const app = track(await boot(freshDir()));
+
+    let agentFired = 0;
+    let connectorBoundFacts: unknown;
+    await app.engine.registerWorker("senior:demo", async () => {
+      agentFired++;
+      return {};
+    });
+    // Wrap the REAL connector job path so we can observe the late-bound facts it received. The worker
+    // itself is registered from the manifest; here we register a same-type observer stub for the e2e.
+    // Mirror the REAL worker's normalization — `readConnectorInput` (trim+require `target`, coerce a
+    // wrong-shaped payload/boundFacts) and `connectorDedupeKey` (derive the effective key from the
+    // author key OR the engine identity `processInstanceKey:elementId`, fail closed if neither) — so
+    // this observer exercises the same fail-closed/derivation behavior the production worker does and
+    // a regression in that surface can't hide behind a `String(... ?? "")` coercion.
+    await app.engine.registerWorker(
+      "pr.delivery-connector",
+      async (job) => {
+        const vars = job.variables as Record<string, unknown>;
+        connectorBoundFacts = vars.boundFacts;
+        const { target, payload, boundFacts } = readConnectorInput(
+          vars as Parameters<typeof readConnectorInput>[0],
+        );
+        const dedupeKey = connectorDedupeKey({
+          dedupeKey: (vars.dedupeKey as string | null | undefined) ?? null,
+          processInstanceKey: job.processInstanceKey ?? null,
+          elementId: job.elementId ?? null,
+        });
+        if (!dedupeKey) {
+          throw new Error("delivery-connector: no dedupe key (author-supplied or graph-derived) available");
+        }
+        return await dispatchConnector(
+          app.db,
+          { dedupeKey, target, payload, boundFacts },
+          new Date().toISOString(),
+        );
+      },
+      { fetchVariables: ["boundFacts", "target", "dedupeKey", "payload"] },
+    );
+
+    const graph: DeliveryGraph = {
+      name: "e2e end-to-end",
+      nodes: [
+        { id: "a", kind: "agent", agent: { jobType: "senior:demo" } },
+        { id: "w", kind: "wait", wait: { kind: "command", target: "true", poll: { everyMs: 5, backoff: "fixed" } } },
+        { id: "h", kind: "human", emits: [{ name: "art", type: "artifact" }] },
+        { id: "c", kind: "connector", connector: { target: "slack", dedupeKey: "c-e2e-1" } },
+      ],
+      edges: [
+        { from: "a", to: "h" },
+        { from: "h.art", to: "c" },
+        { from: "w", to: "c" },
+      ],
+    };
+
+    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S" });
+    assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
+    await app.settle();
+
+    // The agent node executed via its engine-native serviceTask body.
+    assert.equal(agentFired, 1, "the agent node's job fired once");
+
+    // The human node scheduled its per-node user task (the isDeliveryHumanElement convention id).
+    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))}`);
+
+    // Before the human completes, the connector has NOT fired — the fan-in edge from `h` gates it.
+    assert.equal((await deliveryConnectorDispatches(app.db).find({})).length, 0, "connector waits on the human edge");
+
+    // Complete the human with a resolved artifact — its typed emit late-binds downstream.
+    await app.engine.completeUserTask(human.userTaskKey, { resolvedArtifact: "ARTIFACT-1", humanOutcome: "completed" });
+    await app.settle();
+
+    // The connector fired exactly once (fan-in of the wait AND the human both satisfied), and it
+    // received the human's emitted fact as a late-bound input.
+    const rows = await deliveryConnectorDispatches(app.db).find({ dedupe_key: "c-e2e-1" });
+    assert.equal(rows.length, 1, "the connector fired exactly once");
+    assert.equal(rows[0].outcome, "delivered");
+    assert.deepEqual(connectorBoundFacts, [{ from: "h", name: "art", value: "ARTIFACT-1" }], "the human fact late-binds into the connector");
+
+    // The graph reached End — the fan-in join released only after BOTH upstream branches completed.
+    assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the graph reached its End event");
+  });
+
+  test("resume never double-fires: an at-least-once redelivery of the connector dedupes", async () => {
+    const app = track(await boot(freshDir()));
+    // The connector fired once above's-style; here prove the idempotency directly against the ledger a
+    // resumed graph shares. First dispatch delivers; a redelivery of the SAME dispatch (the resume) is
+    // deduped and the durable ledger still holds exactly ONE row — the side effect never re-fires.
+    const first = await dispatchConnector(app.db, { dedupeKey: "resume-1", target: "slack" }, new Date().toISOString());
+    assert.equal(first.connectorOutcome, "delivered");
+    const replay = await dispatchConnector(app.db, { dedupeKey: "resume-1", target: "slack" }, new Date().toISOString());
+    assert.equal(replay.connectorOutcome, "deduped", "a resume redelivery dedupes");
+    assert.equal((await deliveryConnectorDispatches(app.db).find({ dedupe_key: "resume-1" })).length, 1, "exactly one durable dispatch");
+  });
+
+  test("concurrency-correctness: an unrelated human completion does not falsely resolve a parked wait", async () => {
+    const app = track(await boot(freshDir()));
+    // Two independent parallel branches: a NEVER-GREEN wait, and an unrelated human. The wait polls its
+    // own `false` target (never ready) — there is NO shared correlation an unrelated event could trip.
+    const graph: DeliveryGraph = {
+      name: "e2e concurrency",
+      nodes: [
+        { id: "gate", kind: "wait", wait: { kind: "command", target: "false", poll: { everyMs: 5, backoff: "fixed" } } },
+        { id: "side", kind: "human", emits: [{ name: "ok", type: "string" }] },
+      ],
+      edges: [],
+    };
+    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S", escalationSlaTimeout: "PT1H" });
+    assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
+    await app.settle();
+
+    // Complete the UNRELATED human node — an upstream event with no edge to the wait.
+    const open = await app.engine.searchUserTasks({ state: "CREATED" });
+    const side = open.find((t) => t.elementId?.startsWith("delivery-human-task__") && !t.elementId?.endsWith("__esc"));
+    assert.ok(side, "the unrelated human task is open");
+    await app.engine.completeUserTask(side.userTaskKey, { value: "done", humanOutcome: "completed" });
+    await app.settle();
+
+    // The wait polls `false` — it can NEVER resolve as ready, so completing the unrelated human could
+    // not trip it: the graph never reaches End (the wait never released its "ready" branch). Instead the
+    // wait is BOUNDED — its poll budget elapses and it escalates onto a human-completable task, parking
+    // for a human rather than silently wedging or falsely resolving.
+    assert.ok(!takenFlows(app).some((f) => f.endsWith("->End")), "the wait branch never falsely resolves to End");
+    const esc = (await app.engine.searchUserTasks({ state: "CREATED" })).filter((t) => t.elementId?.endsWith("__esc"));
+    assert.ok(
+      esc.length >= 1,
+      `the parked wait escalates (bounded), never falsely resolved by the unrelated event, got ${JSON.stringify((await app.engine.searchUserTasks({ state: "CREATED" })).map((t) => t.elementId))}`,
+    );
+  });
+});

package/nano.app.json

@@ -199,6 +199,10 @@
     {
       "taskType": "pr.readiness-probe",
       "handler": "workers/readiness-probe/worker.ts"
+    },
+    {
+      "taskType": "pr.delivery-connector",
+      "handler": "workers/delivery-connector/worker.ts"
     }
   ],
   "externalTaskTypes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.113.0",
+  "version": "0.114.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",