@nanobpm/nano-workforce 0.113.0 → 0.114.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.114.0](https://github.com/nanobpm/nano-workforce/compare/v0.113.0...v0.114.0) (2026-08-20)
+
+
+### Features
+
+* **delivery-graphs:** integration runner deploys a compiled delivery graph as an engine-native process ([#397](https://github.com/nanobpm/nano-workforce/issues/397)) ([4ae2394](https://github.com/nanobpm/nano-workforce/commit/4ae239412194bfd346cde3213b15d17fad487bbc)), closes [#379](https://github.com/nanobpm/nano-workforce/issues/379)
+
 # [0.113.0](https://github.com/nanobpm/nano-workforce/compare/v0.112.0...v0.113.0) (2026-08-20)
 
 

package/app/agentCompletion.ts

@@ -23,7 +23,7 @@
 import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } 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";
 
 const now = () => new Date().toISOString();
 
@@ -320,12 +320,24 @@ async function resolveEscalationTask(
   const open = await engine.openUserTasks();
   const match = open.find((t) => t.userTaskKey === userTaskKey);
   if (!match) return { ok: false, reason: "no open completable task" };
-  if (!match.elementId || !allowed.has(match.elementId)) {
+  if (!match.elementId || !isCompletableElement(match.elementId, allowed)) {
     return { ok: false, reason: "not a completable task" };
   }
   return { ok: true, elementId: match.elementId };
 }
 
+/** Whether an open task's `elementId` is completable through the given `allowed` surface. Exact-set
+ *  membership PLUS the delivery-human convention: any surface that admits the bare `DELIVERY_HUMAN_ELEMENT`
+ *  (both `ESCALATION_TASK_ELEMENTS` and `HUMAN_COMPLETABLE_ELEMENTS` do) also admits the per-node inlined
+ *  human tasks and their bounded-timeout escalation twins (`delivery-human-task__<el>[__esc]`) the S4
+ *  compiler emits — matched through the single-source-of-truth `isDeliveryHumanElement` predicate so the
+ *  routing can never drift from the compiler's id form (a human node is answerable by a human OR an
+ *  agent, ADR 0046). */
+function isCompletableElement(elementId: string, allowed: ReadonlySet<string>): boolean {
+  if (allowed.has(elementId)) return true;
+  return allowed.has(DELIVERY_HUMAN_ELEMENT) && isDeliveryHumanElement(elementId);
+}
+
 /** Complete an escalation user task AS AN AGENT (ADR 0046). Resolves the parked task by its key,
  *  refuses anything that is not one of the migrated escalation tasks, and routes the typed form
  *  variables through the shared attributed completer with the agent's identity. Reuses the exact

package/app/deliveryConnector.test.ts

@@ -0,0 +1,215 @@
+// Unit coverage for the delivery-graph `connector` node's idempotency envelope (ADR 0005 slice S4,
+// Decision 7). The connector is the epic's one side-effecting node kind, so it MUST fire its outbound
+// action AT-MOST-ONCE per dedupe key even though the engine delivers a job AT-LEAST-ONCE. These tests
+// exercise the durable-fence ledger + claim→act envelope directly against an in-memory app data layer,
+// no engine:
+//   • a first dispatch DELIVERS (performs the action, records the claim),
+//   • a redelivery on the same key DEDUPES (never re-acts, reports the original detail),
+//   • distinct keys each deliver once,
+//   • the graph-derived key falls back to `<processInstanceKey>:<elementId>` when no author key is set.
+import { test } from "node:test";
+import { assert, assertEquals, assertRejects } from "#test-assert";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import type { DataLayer } from "@nanobpm/urban";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import {
+  connectorDedupeKey,
+  type DeliveryConnectorDispatchRow,
+  deliveryConnectorDispatches,
+  dispatchConnector,
+} from "./deliveryConnector.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+/** A minimal in-memory ledger that deterministically drives the concurrent-race fence-LOSER path.
+ * The winning claim `seed` is already present, so the caller's INSERT hits the UNIQUE fence; `missFirstFindOne`
+ * makes the caller's PRE-insert `findOne` miss it (the classic findOne→insert race window), so `dispatchConnector`
+ * falls into its catch branch and rediscovers the winning row there. Returns the live `rows` for assertions. */
+function racingLedgerData(
+  seed: DeliveryConnectorDispatchRow,
+  opts: { missFirstFindOne: boolean },
+): { data: DataLayer; rows: DeliveryConnectorDispatchRow[] } {
+  const rows: DeliveryConnectorDispatchRow[] = [{ ...seed, id: 1 }];
+  let nextId = 2;
+  let firstFindOne = opts.missFirstFindOne;
+  const table = {
+    async findOne(where: Record<string, unknown> = {}) {
+      if (firstFindOne) {
+        firstFindOne = false;
+        return undefined;
+      }
+      return rows.find((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+    },
+    async insert(row: DeliveryConnectorDispatchRow) {
+      if (rows.some((r) => r.dedupe_key === row.dedupe_key)) {
+        throw new Error("UNIQUE constraint failed: delivery_connector_dispatches.dedupe_key");
+      }
+      const id = nextId++;
+      rows.push({ ...row, id });
+      return id;
+    },
+    async update(id: number, patch: Partial<DeliveryConnectorDispatchRow>) {
+      const r = rows.find((x) => x.id === id);
+      if (r) Object.assign(r, patch);
+    },
+    async find(where: Record<string, unknown> = {}) {
+      return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+    },
+  };
+  return { data: { table: () => table } as any as DataLayer, rows };
+}
+
+/** Boot an app purely for its provisioned data layer (migration 055 applied), run `fn`, tear down. */
+async function withApp(fn: (app: TestApp) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-connector-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    await fn(app);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("connectorDedupeKey: author key wins; else derives <processInstanceKey>:<elementId>; else null", () => {
+  assertEquals(connectorDedupeKey({ dedupeKey: "author-1" }), "author-1");
+  assertEquals(connectorDedupeKey({ dedupeKey: "  spaced  " }), "spaced");
+  assertEquals(connectorDedupeKey({ processInstanceKey: "pi9", elementId: "n3" }), "pi9:n3");
+  assertEquals(connectorDedupeKey({ dedupeKey: "  ", processInstanceKey: "pi9", elementId: "n3" }), "pi9:n3");
+  assertEquals(connectorDedupeKey({ dedupeKey: null }), null);
+  assertEquals(connectorDedupeKey({ processInstanceKey: "pi9" }), null);
+  // The engine can return a NUMERIC processInstanceKey — it must still derive a key, not fail closed.
+  assertEquals(connectorDedupeKey({ processInstanceKey: 12345, elementId: "n3" }), "12345:n3");
+});
+
+test("first dispatch delivers exactly once; a redelivery on the same key dedupes and never re-acts", async () => {
+  await withApp(async (app) => {
+    const at = "2025-01-01T00:00:00.000Z";
+    const first = await dispatchConnector(app.db, { dedupeKey: "k1", target: "slack" }, at);
+    assertEquals(first.connectorOutcome, "delivered");
+    assert(first.connectorDetail.length > 0, "delivered dispatch carries an action detail");
+
+    // A redelivery (at-least-once) of the SAME job — same key — must NOT perform the action again.
+    const replay = await dispatchConnector(app.db, { dedupeKey: "k1", target: "slack" }, "2025-01-01T01:00:00.000Z");
+    assertEquals(replay.connectorOutcome, "deduped");
+    assertEquals(replay.connectorDetail, first.connectorDetail);
+
+    // Exactly one durable ledger row exists for the key — the side effect fired at most once.
+    const rows = await deliveryConnectorDispatches(app.db).find({ dedupe_key: "k1" });
+    assertEquals(rows.length, 1);
+    assertEquals(rows[0].outcome, "delivered");
+  });
+});
+
+test("a redelivery of a CLAIMED-but-not-delivered row RESUMES the action (never wedges on a permanent dedupe)", async () => {
+  await withApp(async (app) => {
+    const ledger = deliveryConnectorDispatches(app.db);
+    // Simulate a worker that crashed AFTER claiming the key but BEFORE recording delivery: a lone
+    // `claimed` row whose action never fired.
+    await ledger.insert({ dedupe_key: "wedged-1", target: "slack", outcome: "claimed", detail: null, dispatched_at: "2025-01-01T00:00:00.000Z" });
+
+    // A redelivery must RESUME (perform the action + record delivery), not report `deduped` forever.
+    const resumed = await dispatchConnector(app.db, { dedupeKey: "wedged-1", target: "slack" }, "2025-01-01T01:00:00.000Z");
+    assertEquals(resumed.connectorOutcome, "delivered");
+    assert(resumed.connectorDetail.length > 0, "the resumed dispatch carries an action detail");
+
+    const rows = await ledger.find({ dedupe_key: "wedged-1" });
+    assertEquals(rows.length, 1, "resume records on the existing row — no duplicate ledger entry");
+    assertEquals(rows[0].outcome, "delivered");
+
+    // And a subsequent redelivery of the now-DELIVERED row terminally dedupes.
+    const replay = await dispatchConnector(app.db, { dedupeKey: "wedged-1", target: "slack" }, "2025-01-01T02:00:00.000Z");
+    assertEquals(replay.connectorOutcome, "deduped");
+    assertEquals(replay.connectorDetail, resumed.connectorDetail);
+  });
+});
+
+test("the concurrent-race fence LOSER RESUMES a still-CLAIMED winning row (never dedupes on an un-acted claim)", async () => {
+  // The winner CLAIMED the key (row present) but has NOT yet recorded delivery. The loser races: its
+  // pre-insert lookup misses (the findOne→insert window), its INSERT hits the UNIQUE fence, and in the
+  // catch it rediscovers the winner's STILL-`claimed` row. If the loser deduped and completed the job
+  // here, the engine — having taken the loser's ack — would never redeliver, so a winner that then
+  // crashed would strand the side effect FOREVER. The loser must RESUME the claimed row instead.
+  const { data, rows } = racingLedgerData(
+    { dedupe_key: "race", target: "slack", outcome: "claimed", detail: null, dispatched_at: "2025-01-01T00:00:00.000Z" },
+    { missFirstFindOne: true },
+  );
+  const out = await dispatchConnector(data, { dedupeKey: "race", target: "slack" }, "2025-01-01T01:00:00.000Z");
+  assertEquals(out.connectorOutcome, "delivered");
+  assert(out.connectorDetail.length > 0, "the resumed dispatch carries an action detail");
+  const settled = rows.filter((r) => r.dedupe_key === "race");
+  assertEquals(settled.length, 1, "resume records on the winning row — no duplicate ledger entry");
+  assertEquals(settled[0].outcome, "delivered");
+});
+
+test("the fence LOSER still DEDUPES a DELIVERED winning row (reports its detail, never re-acts)", async () => {
+  const { data, rows } = racingLedgerData(
+    { dedupe_key: "race2", target: "slack", outcome: "delivered", detail: "winner-detail", dispatched_at: "2025-01-01T00:00:00.000Z" },
+    { missFirstFindOne: true },
+  );
+  const out = await dispatchConnector(data, { dedupeKey: "race2", target: "slack" }, "2025-01-01T01:00:00.000Z");
+  assertEquals(out.connectorOutcome, "deduped");
+  assertEquals(out.connectorDetail, "winner-detail");
+  assertEquals(rows.filter((r) => r.dedupe_key === "race2").length, 1, "no re-act, no duplicate row");
+  assertEquals(rows.find((r) => r.dedupe_key === "race2")?.outcome, "delivered");
+});
+
+test("the fence LOSER fails closed when the winning row carries a DIFFERENT target", async () => {
+  const { data, rows } = racingLedgerData(
+    { dedupe_key: "race3", target: "slack", outcome: "claimed", detail: null, dispatched_at: "2025-01-01T00:00:00.000Z" },
+    { missFirstFindOne: true },
+  );
+  await assertRejects(
+    () => dispatchConnector(data, { dedupeKey: "race3", target: "pagerduty" }, "2025-01-01T01:00:00.000Z"),
+    Error,
+    "different target",
+  );
+  // The mismatch must not have mutated the winning row (still an un-acted claim on its original target).
+  const row = rows.find((r) => r.dedupe_key === "race3");
+  assertEquals(row?.target, "slack");
+  assertEquals(row?.outcome, "claimed");
+});
+
+test("distinct dedupe keys each deliver once", async () => {
+  await withApp(async (app) => {
+    const a = await dispatchConnector(app.db, { dedupeKey: "a", target: "t" }, "2025-01-01T00:00:00.000Z");
+    const b = await dispatchConnector(app.db, { dedupeKey: "b", target: "t" }, "2025-01-01T00:00:00.000Z");
+    assertEquals(a.connectorOutcome, "delivered");
+    assertEquals(b.connectorOutcome, "delivered");
+    const rows = await deliveryConnectorDispatches(app.db).find({});
+    assertEquals(rows.length, 2);
+  });
+});
+
+test("a dedupe key reused with a DIFFERENT target fails closed (never delivers/reports against the wrong destination)", async () => {
+  await withApp(async (app) => {
+    const ledger = deliveryConnectorDispatches(app.db);
+    // A DELIVERED row would otherwise short-circuit to `deduped` and report the ORIGINAL target's detail.
+    const first = await dispatchConnector(app.db, { dedupeKey: "reused", target: "slack" }, "2025-01-01T00:00:00.000Z");
+    assertEquals(first.connectorOutcome, "delivered");
+    await assertRejects(
+      () => dispatchConnector(app.db, { dedupeKey: "reused", target: "pagerduty" }, "2025-01-01T01:00:00.000Z"),
+      Error,
+      "different target",
+    );
+
+    // A still-CLAIMED (crashed mid-flight) row would otherwise RESUME — against the wrong target.
+    await ledger.insert({ dedupe_key: "claimed-reused", target: "slack", outcome: "claimed", detail: null, dispatched_at: "2025-01-01T00:00:00.000Z" });
+    await assertRejects(
+      () => dispatchConnector(app.db, { dedupeKey: "claimed-reused", target: "pagerduty" }, "2025-01-01T01:00:00.000Z"),
+      Error,
+      "different target",
+    );
+
+    // The mismatch must not have mutated either ledger row.
+    const slackRows = await ledger.find({ target: "slack" });
+    assertEquals(slackRows.length, 2, "both original-target rows are intact — no wrong-target write");
+
+    // Re-dispatching each with its ORIGINAL target still dedupes/resumes normally.
+    const replay = await dispatchConnector(app.db, { dedupeKey: "reused", target: "slack" }, "2025-01-01T02:00:00.000Z");
+    assertEquals(replay.connectorOutcome, "deduped");
+    assertEquals(replay.connectorDetail, first.connectorDetail);
+  });
+});

package/app/deliveryConnector.ts

@@ -0,0 +1,210 @@
+// nano-workforce — the delivery-graph `connector` node's execution body (ADR 0005 Decision 6/7, slice
+// S4). A `connector` is the epic's one SIDE-EFFECTING node kind — it drives an outbound action against
+// the connector I/O surface. That surface is FORWARD-DECLARED here (the concrete connector scheme and
+// payload land in a later slice, per the ADR non-goals): `performConnectorAction` is a deliberate STUB.
+// But the node is REAL — it is deployed, scheduled engine-natively, and, crucially, IDEMPOTENT, so the
+// dedupe contract every side-effecting node inherits is exercised end-to-end today rather than
+// retrofitted onto a live integration later.
+//
+// Idempotency (Decision 7). 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 the dispatch is claimed in a
+// durable ledger (`delivery_connector_dispatches`, migration 055) BEFORE the action fires; a redelivery
+// that finds the key already `delivered` short-circuits to the recorded outcome (`deduped`) and never
+// re-performs the side effect, while one that finds a still-`claimed` (crashed mid-flight) row RESUMES
+// it. The UNIQUE fence on `dedupe_key` makes the claim atomic even under a concurrent race — the loser
+// is classified by the ONE canonical `isUniqueConstraintFence` (app/dbFence.ts) as a fence collision,
+// not a spurious failure, then dedupes-or-resumes the winning row exactly as a sequential redelivery
+// would (the durable-fence idiom, no drift).
+import type { DataLayer } from "@nanobpm/urban";
+import { isUniqueConstraintFence } from "./dbFence.ts";
+
+/** The engine `taskType` a compiled `connector` node's inlined subProcess delegates to. The canonical
+ * source the compiler's delegation map (`DELEGATE_TASK_TYPE.connector` imports and uses this constant),
+ * so the compiled BPMN's task type is DERIVED here, not re-typed. The worker registration
+ * (`nano.app.json`) and the compiler tests pin the same literal by value — a manifest is JSON and a
+ * value assertion cannot import a TS const — so they read as verification of this constant, not a
+ * parallel source of truth. */
+export const DELIVERY_CONNECTOR_TASK_TYPE = "pr.delivery-connector";
+
+/** The connector ledger's two-step claim lifecycle. `claimed` — the row was fenced but the action has
+ * not yet been recorded as done (an in-flight or crashed attempt, which `dispatchConnector` RESUMES);
+ * `delivered` — the action completed and the row is terminally deduped. Named constants so the claim,
+ * the resume check, and the delivered short-circuit can never drift on a bare string. */
+export const OUTCOME_CLAIMED = "claimed";
+export const OUTCOME_DELIVERED = "delivered";
+
+/** One durable dispatch-claim row — the at-most-once ledger entry a connector writes before it acts. */
+export interface DeliveryConnectorDispatchRow extends Record<string, unknown> {
+  id?: number;
+  dedupe_key: string;
+  target: string;
+  outcome: string;
+  detail: string | null;
+  dispatched_at: string;
+}
+
+/** The `delivery_connector_dispatches` ledger accessor (migration 055). Access goes through the RAD
+ * `Table<T>` gateway (`data.table`), never hand-written SQL — matching every other data path in the app. */
+export const deliveryConnectorDispatches = (data: DataLayer) =>
+  data.table<DeliveryConnectorDispatchRow>("delivery_connector_dispatches", "id");
+
+/** A late-bound upstream fact threaded into a consuming node (the `boundFacts` list the compiler emits). */
+export interface BoundFact {
+  from: string;
+  name: string;
+  value: unknown;
+}
+
+/** The effective dedupe key for a connector dispatch: the author-supplied `connector.dedupeKey` when
+ * present, else a graph-derived `<processInstanceKey>:<elementId>` — both STABLE across a re-activation
+ * of the same node instance (the engine re-delivers the same job with the same identity), so an
+ * at-least-once redelivery collapses onto the same ledger row. The single derivation site so the runner
+ * (which may pre-seed an author key) and the worker agree on the key shape. Returns `null` only when no
+ * key can be formed at all (no author key AND no engine identity) — the caller treats that as
+ * un-dedupable and MUST NOT perform the side effect (fail closed rather than double-fire). */
+export function connectorDedupeKey(input: {
+  dedupeKey?: string | null;
+  processInstanceKey?: string | number | null;
+  elementId?: string | null;
+}): string | null {
+  const authored = typeof input.dedupeKey === "string" ? input.dedupeKey.trim() : "";
+  if (authored) return authored;
+  // The engine can hand back a NUMERIC processInstanceKey — coerce (codebase-wide `String(...)` pattern)
+  // so a connector node without an authored dedupeKey stays dedupable instead of failing closed.
+  const pik = input.processInstanceKey == null ? "" : String(input.processInstanceKey).trim();
+  const el = typeof input.elementId === "string" ? input.elementId.trim() : "";
+  if (pik && el) return `${pik}:${el}`;
+  return null;
+}
+
+/** The forward-declared connector I/O surface (ADR non-goal — the concrete scheme is deferred). A STUB
+ * that "performs" the action by returning a deterministic acknowledgement; a later slice replaces the
+ * body with the real transport without touching the idempotency envelope around it. */
+function performConnectorAction(_input: {
+  target: string;
+  payload: Record<string, unknown> | null;
+  boundFacts: readonly BoundFact[];
+}): { detail: string } {
+  return { detail: "connector stub — I/O surface forward-declared (ADR 0005 non-goal)" };
+}
+
+/** The result of one connector dispatch attempt. `delivered` — the claim was won and the action fired
+ * exactly once; `deduped` — the key was already claimed (an at-least-once redelivery), so the recorded
+ * outcome is returned and NO side effect re-fired. */
+export interface ConnectorDispatchResult extends Record<string, unknown> {
+  connectorOutcome: "delivered" | "deduped";
+  connectorDedupeKey: string;
+  connectorDetail: string;
+}
+
+/** Decide the outcome for a ledger row that ALREADY claims `dedupeKey`: DEDUPE it when it is terminally
+ * `delivered` (report the recorded detail, never re-act), or RESUME it when it is still `claimed` (its
+ * action never recorded delivery — perform the idempotent action now and record delivery on THIS row).
+ * The ONE place that decides resume-vs-dedupe for a rediscovered row, so the sequential-redelivery path
+ * and the concurrent-race fence-loser path can never drift on whether a still-`claimed` winner is
+ * resumed (AGENTS.md: "no drift surfaces"). */
+async function resumeOrDedupe(
+  ledger: ReturnType<typeof deliveryConnectorDispatches>,
+  row: DeliveryConnectorDispatchRow,
+  input: { dedupeKey: string; target: string; payload?: Record<string, unknown> | null; boundFacts?: readonly BoundFact[] | null },
+): Promise<ConnectorDispatchResult> {
+  if (row.outcome === OUTCOME_DELIVERED) {
+    return { connectorOutcome: "deduped", connectorDedupeKey: input.dedupeKey, connectorDetail: row.detail ?? "" };
+  }
+  // Still `claimed` — a prior attempt (sequential or the concurrent-race winner) claimed the key but
+  // never recorded delivery. Resume on the existing row rather than dedupe forever on an un-acted claim.
+  const { detail } = performConnectorAction({
+    target: input.target,
+    payload: input.payload ?? null,
+    boundFacts: input.boundFacts ?? [],
+  });
+  if (row.id !== undefined) await ledger.update(row.id, { outcome: OUTCOME_DELIVERED, detail });
+  return { connectorOutcome: "delivered", connectorDedupeKey: input.dedupeKey, connectorDetail: detail };
+}
+
+/** Dispatch a connector action AT-MOST-ONCE against its dedupe key. CLAIMS the ledger row FIRST (the
+ * UNIQUE fence is the atomic gate that elects exactly one winner), and ONLY the claim winner performs
+ * the forward-declared action — so an at-least-once redelivery, or a concurrent racer, can never
+ * double-fire a SETTLED side effect. A redelivery whose key is already recorded `delivered` returns
+ * `deduped` WITHOUT acting, reporting the ORIGINAL detail.
+ *
+ * Resumability (the crash window). A claim is a two-step `claimed`→act→`delivered`. If a worker dies
+ * AFTER claiming but BEFORE recording delivery, the action never completed — so ANY dispatch that
+ * rediscovers a still-`claimed` (not yet `delivered`) row must RESUME it: perform the action and record
+ * delivery, rather than treating the un-acted claim as `deduped` and wedging the node on a side effect
+ * that never fires. Only a `delivered` row is terminally deduped. This rule is uniform across BOTH ways
+ * a row is rediscovered — the sequential `findOne` redelivery AND the concurrent-race fence LOSER below
+ * — routed through the ONE `resumeOrDedupe` decision so they can never drift. The fence loser MUST NOT
+ * dedupe a still-`claimed` winner: it would complete the job on the loser's ack, and the engine — having
+ * taken that ack — would never redeliver, so a winner that then crashed would strand the side effect
+ * forever (no later redelivery can recover it). Resuming instead may re-perform an action the winner is
+ * still delivering, but the STUB action is idempotent so a concurrent double-resume is free — exactly as
+ * the sequential resume already is; a real transport later slots a resumable `applied` reconcile in — as
+ * the world-store ledger does — to make the resume itself at-most-once, without changing this contract.
+ *
+ * Target drift (fail closed). The ledger keys only by `dedupeKey`; a key reused with a DIFFERENT
+ * `target` than its recorded row is a contract violation (a legitimate redelivery always repeats the
+ * same target), so this throws rather than deliver/resume/report against the wrong destination. */
+export async function dispatchConnector(
+  data: DataLayer,
+  input: { dedupeKey: string; target: string; payload?: Record<string, unknown> | null; boundFacts?: readonly BoundFact[] | null },
+  at: string,
+): Promise<ConnectorDispatchResult> {
+  const ledger = deliveryConnectorDispatches(data);
+  const existing = await ledger.findOne({ dedupe_key: input.dedupeKey });
+  if (existing && existing.target !== input.target) {
+    // FAIL CLOSED on target drift. The ledger keys only by `dedupeKey`; if the same key is ever reused
+    // (accidentally or maliciously) with a DIFFERENT target, both the `delivered` short-circuit and the
+    // `claimed` resume below would act on / report the recorded row — delivering to, or attributing the
+    // outcome of, the WRONG destination and leaving the persisted `target` describing neither action.
+    // Refuse rather than corrupt the at-most-once ledger; a legitimate redelivery always carries the
+    // same target for a given key.
+    throw new Error(
+      `connector dedupe key "${input.dedupeKey}" reused with a different target ` +
+        `(ledger="${existing.target}", input="${input.target}") — refusing to dispatch`,
+    );
+  }
+  if (existing) {
+    // A prior attempt recorded (`delivered`) or claimed-but-crashed (`claimed`) this key. Dedupe or
+    // resume it on the existing row — the ONE decision shared with the fence-loser path below.
+    return resumeOrDedupe(ledger, existing, input);
+  }
+  let claimId: number | bigint;
+  try {
+    claimId = await ledger.insert({
+      dedupe_key: input.dedupeKey,
+      target: input.target,
+      outcome: OUTCOME_CLAIMED,
+      detail: null,
+      dispatched_at: at,
+    });
+  } catch (err) {
+    // A concurrent redelivery won the claim between our `findOne` and `insert`. The UNIQUE fence on
+    // `dedupe_key` rejects our loser — tolerate ONLY that collision as the same idempotent `deduped`
+    // outcome, and NEVER perform the action (the winner is the one that acts).
+    if (!isUniqueConstraintFence(err)) throw err;
+    const won = await ledger.findOne({ dedupe_key: input.dedupeKey });
+    if (won && won.target !== input.target) {
+      // Same target-drift anomaly as above, surfaced via a concurrent racer that won the claim with a
+      // different target — fail closed rather than report the wrong destination's outcome as ours.
+      throw new Error(
+        `connector dedupe key "${input.dedupeKey}" reused with a different target ` +
+          `(ledger="${won.target}", input="${input.target}") — refusing to dispatch`,
+      );
+    }
+    // Dedupe (winner `delivered`) OR resume (winner still `claimed`) the winning row — the SAME decision
+    // as the sequential path. Deduping a still-`claimed` winner here would complete the job on our ack,
+    // so a winner that then crashed would strand the side effect forever (the engine won't redeliver an
+    // acked job); resuming closes that gap and is safe because the action is idempotent.
+    if (won) return resumeOrDedupe(ledger, won, input);
+    return { connectorOutcome: "deduped", connectorDedupeKey: input.dedupeKey, connectorDetail: "" };
+  }
+  // We alone won the claim — perform the side effect exactly once and record its outcome on our row.
+  const { detail } = performConnectorAction({
+    target: input.target,
+    payload: input.payload ?? null,
+    boundFacts: input.boundFacts ?? [],
+  });
+  await ledger.update(claimId, { outcome: OUTCOME_DELIVERED, detail });
+  return { connectorOutcome: "delivered", connectorDedupeKey: input.dedupeKey, connectorDetail: detail };
+}

package/app/deliveryGraphCompiler.test.ts

@@ -6,8 +6,9 @@
 //   • DETERMINISM (same JSON → byte-identical bpmn/diagram/resolved — the core trust property),
 //   • rejection of every malformed class (unknown-kind / dangling / bad-from / cycle) as ok:false
 //     with path-qualified errors forwarded verbatim from the validator,
-//   • the trust bound — only allowlisted kinds are instantiated (callActivity/userTask, allowlisted
-//     calledElement targets; a non-allowlisted kind never reaches compilation),
+//   • the trust bound — every node inlines an embedded subProcess whose inner body delegates to an
+//     allowlisted engine-native worker (serviceTask `type`) or user task (human); no scriptTask/
+//     callActivity ever appears (call activities are a no-op on the pinned WASM engine, ADR 0005 S4),
 //   • fan-in / fan-out / multi-root / multi-leaf → explicit parallel gateways,
 //   • humanNodes[] and sideEffects[] extraction.
 import { test } from "node:test";
@@ -82,16 +83,35 @@ test("determinism: the same JSON always yields byte-identical bpmn/diagram/resol
   assertEquals(c.diagram, a.diagram);
 });
 
-test("trust bound: only allowlisted kinds are instantiated — no other BPMN activity type appears", () => {
+test("trust bound: every node inlines an embedded subProcess delegating to an allowlisted body — no other activity type", () => {
   const r = compileOk(RELEASE_RUNBOOK);
-  // Every node compiles to a callActivity (agent/wait/connector) or a userTask (human) — nothing else.
-  assertEquals((r.bpmn.match(/<bpmn:callActivity /g) ?? []).length, 3);
-  assertEquals((r.bpmn.match(/<bpmn:userTask /g) ?? []).length, 1);
+  // Each of the 4 nodes compiles to an EMBEDDED subProcess (call activities are a no-op on the pinned
+  // WASM engine, so delegation is an inlined subProcess sharing the parent scope — never a callActivity).
+  assertEquals((r.bpmn.match(/<bpmn:callActivity/g) ?? []).length, 0);
+  assertEquals((r.bpmn.match(/<bpmn:subProcess /g) ?? []).length, 4);
   assert(!r.bpmn.includes("<bpmn:scriptTask"), "no script task is ever emitted");
-  assert(!r.bpmn.includes("<bpmn:serviceTask"), "no bespoke service task is ever emitted");
-  // Every call activity delegates to an allowlisted engine-native body.
-  const called = [...r.bpmn.matchAll(/processId="([^"]+)"/g)].map((m) => m[1]);
-  assertEquals(new Set(called), new Set(["delivery-node-agent", "readiness-gate", "delivery-node-connector"]));
+  // Each node's inner body delegates to an allowlisted engine-native body: a `serviceTask` typed to a
+  // worker (agent → its `senior:*` job; wait → `pr.readiness-probe`; connector → `pr.delivery-connector`)
+  // or a `userTask` (human). Collect the service delegation targets.
+  const types = new Set([...r.bpmn.matchAll(/<zeebe:taskDefinition type="([^"]+)"/g)].map((m) => m[1]));
+  assert(types.has("senior:feature"), "agent delegates to its named job type");
+  assert(types.has("pr.readiness-probe"), "wait delegates to the readiness-probe gate");
+  assert(types.has("pr.delivery-connector"), "connector delegates to the connector worker");
+  // The human node inlines the S3 user-task body under the per-node convention id, and the bounded
+  // service nodes inline a human-completable escalation userTask under the same convention.
+  assert(/<bpmn:userTask id="delivery-human-task__n\d+"/.test(r.bpmn), "human node inlines its per-node user task");
+  assert(/<bpmn:userTask id="delivery-human-task__n\d+__esc"/.test(r.bpmn), "a bounded node inlines an escalation user task");
+});
+
+test("late-binding: a fact-qualified edge threads a boundFacts input into the consumer subProcess", () => {
+  const r = compileOk(RELEASE_RUNBOOK);
+  // `publish.resolvedArtifact -> consume`: the connector subProcess receives the human's emitted fact as
+  // a boundFacts list entry, read from the flat `<producerElement>_<fact>` variable the producer publishes.
+  // FEEL string literals must use single-quote XML-attribute delimiters (the engine deploy path drops
+  // `&quot;`-encoded quotes silently), so the boundFacts source is single-quoted with literal quotes.
+  assert(r.bpmn.includes("target=\"boundFacts\""), "the consumer receives a boundFacts input");
+  const boundInput = /<zeebe:input source='=\[\{from: "publish"[^']*\}\]' target="boundFacts"/.test(r.bpmn);
+  assert(boundInput, `boundFacts is a single-quoted FEEL list literal, got: ${r.bpmn.match(/source='[^']*' target="boundFacts"/)?.[0] ?? r.bpmn.match(/source="[^"]*" target="boundFacts"/)?.[0]}`);
 });
 
 test("rejects unknown kind (by construction) with a path-qualified error, nothing compiled", () => {
@@ -223,10 +243,12 @@ test("resolved edges carry the resolved fromNode and the referenced fact", () =>
   assertEquals(plainEdge?.fromFact, undefined);
 });
 
-test("BPMN is structurally coherent: one start, one end, every flow endpoint declared", () => {
+test("BPMN is structurally coherent: one process start, one process end, every flow endpoint declared", () => {
   const r = compileOk(RELEASE_RUNBOOK);
-  assertEquals((r.bpmn.match(/<bpmn:startEvent /g) ?? []).length, 1);
-  assertEquals((r.bpmn.match(/<bpmn:endEvent /g) ?? []).length, 1);
+  // The TOP-LEVEL process has exactly one Start and one End (each inlined subProcess has its OWN
+  // start/end events, so a raw `<bpmn:startEvent>` count is not the process boundary — the fixed ids are).
+  assertEquals((r.bpmn.match(/ id="Start"/g) ?? []).length, 1);
+  assertEquals((r.bpmn.match(/ id="End"/g) ?? []).length, 1);
   // Every sequenceFlow source/target id is declared as an element id in the document.
   const declaredIds = new Set([...r.bpmn.matchAll(/ id="([^"]+)"/g)].map((m) => m[1]));
   for (const m of r.bpmn.matchAll(/sourceRef="([^"]+)" targetRef="([^"]+)"/g)) {