@nanobpm/nano-workforce 0.106.3 → 0.107.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.107.1](https://github.com/nanobpm/nano-workforce/compare/v0.107.0...v0.107.1) (2026-08-20)
+
+
+### Bug Fixes
+
+* **merge-loop:** converge PRs merged/closed out-of-band at every merge-stage wait ([#370](https://github.com/nanobpm/nano-workforce/issues/370)) ([c673c82](https://github.com/nanobpm/nano-workforce/commit/c673c823b6ed5dde5710c4cb677f7c6f01ae59de)), closes [nanobpm/nano-workforce#368](https://github.com/nanobpm/nano-workforce/issues/368)
+
+# [0.107.0](https://github.com/nanobpm/nano-workforce/compare/v0.106.3...v0.107.0) (2026-08-20)
+
+
+### Features
+
+* port nwf models to defineFlow (S5, [#320](https://github.com/nanobpm/nano-workforce/issues/320)) ([#353](https://github.com/nanobpm/nano-workforce/issues/353)) ([c0b2d9d](https://github.com/nanobpm/nano-workforce/commit/c0b2d9ddea4f5c56159f011ca70203aa3f3c91fe)), closes [nanobpm/nano-ide#314](https://github.com/nanobpm/nano-ide/issues/314) [355/#356](https://github.com/nanobpm/nano-workforce/issues/356) [nano-ide#405](https://github.com/nano-ide/issues/405)
+
 ## [0.106.3](https://github.com/nanobpm/nano-workforce/compare/v0.106.2...v0.106.3) (2026-08-20)
 
 

package/app/mergeOutOfBandTerminal.test.ts

@@ -0,0 +1,178 @@
+// Class regression guard for the out-of-band terminal escape shared by EVERY merge-stage durable
+// wait (issue #368).
+//
+// #368: a PR merged (or closed) OUT-OF-BAND — a maintainer clicks Merge, or a mergify queue lands
+// it — while its merge-loop instance is parked at a durable GitHub wait can silently wedge forever.
+// The `waiting_deps` branch of `pollMerges` only advanced a PR when its *declared dependencies*
+// merged and had NO check on the PR itself already being merged: if those deps never cleared, the
+// instance sat at `wait-deps` forever (ACTIVE, no incident, no timer boundary). `waiting_merge`
+// already guarded this; the fix lifts that guard into ONE shared pre-check
+// (`advanceIfTerminalOutOfBand`) run at the top of all four merge-stage waits — `waiting_deps`,
+// `waiting_merge`, `waiting_lane`, `queued` — so no stage can strand on an out-of-band terminal
+// transition. Each wait subscribes to a DIFFERENT catch, so the pre-check must publish the escape
+// message THAT wait correlates to; this test asserts the class over every (status × merged/closed).
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { pollMerges } from "./service.ts";
+
+// In-memory record gateway (get/find/insert/update/delete), matching app/promotionPoll.test.ts.
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+      async delete(id: any) {
+        for (let i = rows.length - 1; i >= 0; i--) if (rows[i][pk] === id) rows.splice(i, 1);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+// Records every message the poller publishes so a test can assert the exact escape.
+function recordingEngine(): { engine: EngineClient; messages: any[] } {
+  const messages: any[] = [];
+  const engine = {
+    async publishMessage(msg: any) {
+      messages.push(msg);
+    },
+  } as any as EngineClient;
+  return { engine, messages };
+}
+
+// A token-transport GitHub stub. Serves `GET /repos/{repo}/pulls/{n}` from a per-number liveness
+// map so `fetchPrState` (→ `classifyPrLiveness`) reads "merged" / "closed" / "open".
+type Live = "merged" | "closed" | "open";
+function githubFetch(states: Map<number, Live>) {
+  return (url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const json = (obj: unknown, status = 200) =>
+      Promise.resolve(new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } }));
+    const m = u.pathname.match(/\/repos\/[^/]+\/[^/]+\/pulls\/(\d+)$/);
+    if (m) {
+      const n = Number(m[1]);
+      const live = states.get(n) ?? "open";
+      return json({
+        merged: live === "merged",
+        merged_at: live === "merged" ? "2026-08-20T02:35:42Z" : null,
+        state: live === "open" ? "open" : "closed",
+        mergeable_state: live === "open" ? "clean" : "unknown",
+        draft: false,
+        head: { sha: "deadbeef" },
+      });
+    }
+    return Promise.resolve(new Response(`unexpected ${u.pathname}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(states: Map<number, Live>, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = githubFetch(states) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+function prRow(prKey: string, number: number, status: string) {
+  const ts = "2026-08-20T00:00:00Z";
+  return {
+    pr_key: prKey,
+    repo: "o/r",
+    number,
+    url: `https://github.com/o/r/pull/${number}`,
+    title: "t",
+    status,
+    current_round: 0,
+    process_key: null,
+    waiting_since: null,
+    last_review_id: null,
+    outcome: null,
+    created_at: ts,
+    updated_at: ts,
+    converged_at: null,
+    merged_at: null,
+  };
+}
+
+// Every merge-stage durable wait, with the escape message its parked catch subscribes to. The
+// escape differs per wait because each subscribes to a different message — the whole point of the
+// shared pre-check is to publish the RIGHT one so it correlates instead of being dropped.
+const CASES: { status: string; merged: string; closed: string }[] = [
+  // wait-deps subscribes only `deps-cleared` (→ arm-merge → wait-mergeable, where block 2 converges).
+  { status: "waiting_deps", merged: "deps-cleared", closed: "deps-cleared" },
+  // wait-mergeable subscribes `merge-ready` (→ gw-mergeable → attempt-merge terminal short-circuits).
+  { status: "waiting_merge", merged: "merge-ready", closed: "merge-ready" },
+  // waiting_lane is an app hold that leaves the process on wait-mergeable → also `merge-ready`.
+  { status: "waiting_lane", merged: "merge-ready", closed: "merge-ready" },
+  // wait-landed subscribes `merge-landed` (→ mark-merged) and `merge-evicted` (→ arm-merge). A
+  // merged queue PR lands; a closed one can never land, so re-arm and let block 2 abandon it.
+  { status: "queued", merged: "merge-landed", closed: "merge-evicted" },
+];
+
+for (const c of CASES) {
+  for (const live of ["merged", "closed"] as const) {
+    test(`out-of-band ${live} PR at ${c.status} converges via ${live === "merged" ? c.merged : c.closed}`, async () => {
+      const { data, stores } = memData();
+      const { engine, messages } = recordingEngine();
+      stores["pull_requests"] = [prRow("o/r#100", 100, c.status)];
+      // A declared dependency that has NOT merged — the exact condition that wedged `waiting_deps`:
+      // the deps loop would never clear, so ONLY the PR's own terminal state can converge it.
+      stores["pr_dependencies"] = [{ pr_key: "o/r#100", depends_on_key: "o/r#200", created_at: "t" }];
+
+      await withGithub(new Map<number, Live>([[100, live], [200, "open"]]), () =>
+        pollMerges(data, engine, "tok"),
+      );
+
+      assertEquals(messages.length, 1, `expected exactly one escape message for ${c.status}/${live}`);
+      const expected = live === "merged" ? c.merged : c.closed;
+      assertEquals(messages[0].name, expected);
+      assertEquals(messages[0].correlationKey, "o/r#100");
+      if (expected === "merge-ready") assertEquals(messages[0].variables.mergeState, "ready");
+      // Flipped onto the transient `merging` status so a slow pass can't double-signal.
+      assertEquals(stores["pull_requests"][0].status, "merging");
+    });
+  }
+}
+
+// Negative guard: a still-OPEN `waiting_deps` PR whose declared dep is unmerged must NOT be forced
+// terminal by the pre-check — it stays parked (no escape published), proving the pre-check fires
+// only on a real out-of-band terminal transition and never drops a live PR.
+test("still-open waiting_deps PR with an unmerged dep publishes nothing and stays parked", async () => {
+  const { data, stores } = memData();
+  const { engine, messages } = recordingEngine();
+  stores["pull_requests"] = [prRow("o/r#100", 100, "waiting_deps")];
+  stores["pr_dependencies"] = [{ pr_key: "o/r#100", depends_on_key: "o/r#200", created_at: "t" }];
+
+  await withGithub(new Map<number, Live>([[100, "open"], [200, "open"]]), () =>
+    pollMerges(data, engine, "tok"),
+  );
+
+  assertEquals(messages.length, 0);
+  assertEquals(stores["pull_requests"][0].status, "waiting_deps");
+});

package/app/service.ts

@@ -1014,6 +1014,87 @@ async function mirrorTaskStatusForPr(data: DataLayer, prKey: string, status: "op
   }
 }
 
+/** The escape message a merge-stage durable wait must publish when its PR has gone terminal
+ * (merged/closed) OUT-OF-BAND — i.e. someone landed or closed it on GitHub while the process was
+ * parked, so the wait's own declared trigger (deps clearing, a mergeable verdict, a lane release, a
+ * queue landing) may never fire. Each wait subscribes to a DIFFERENT message, so the escape MUST be
+ * the one its parked catch actually correlates to (publishing any other name is dropped by the
+ * engine and re-wedges the PR in the transient `merging` status). All roads lead to the same proven
+ * terminal path — `attempt-merge`'s idempotent already-merged / closed short-circuits (#368):
+ *   • waiting_deps  → parked at `wait-deps`, subscribes ONLY `deps-cleared`. Deps are moot once the
+ *     PR itself landed, so clear them regardless of liveness; `deps-cleared` → `arm-merge` →
+ *     `wait-mergeable`, where block 2 (below) reads the terminal state and drives merged→mark-merged
+ *     / closed→abandon. This is the gap the incident hit — `wait-deps` had NO self-merged escape.
+ *   • waiting_merge / waiting_lane → both parked at `wait-mergeable` (waiting_lane is an app-internal
+ *     hold that leaves the process on `wait-mergeable`), which subscribes `merge-ready`. Route a
+ *     `ready` verdict through `gw-mergeable → attempt-merge`, whose short-circuits complete/abandon.
+ *   • queued → parked at `wait-landed`, subscribes `merge-landed` (→ mark-merged) and `merge-evicted`
+ *     (→ arm-merge). A merged queue PR lands (`merge-landed`); a closed-unmerged one can NEVER land,
+ *     so publishing `merge-landed` would falsely mark it merged — re-arm via `merge-evicted` instead
+ *     and let block 2 abandon it on the next pass. */
+function outOfBandEscapeMessage(
+  status: string,
+  liveness: "merged" | "closed",
+  prKey: string,
+): Parameters<EngineClient["publishMessage"]>[0] {
+  switch (status) {
+    case "waiting_deps":
+      return { name: "deps-cleared", correlationKey: prKey, variables: {} };
+    case "waiting_merge":
+    case "waiting_lane":
+      return {
+        name: "merge-ready",
+        correlationKey: prKey,
+        variables: { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
+      };
+    case "queued":
+      return liveness === "merged"
+        ? { name: "merge-landed", correlationKey: prKey, variables: {} }
+        : { name: "merge-evicted", correlationKey: prKey, variables: {} };
+    default:
+      // Unreachable: only the four merge-stage durable waits call this. Fail loud rather than
+      // mis-route a message the parked catch can't correlate (which would silently re-wedge the PR).
+      throw new Error(`outOfBandEscapeMessage: unexpected merge-stage status ${JSON.stringify(status)}`);
+  }
+}
+
+/** ONE shared out-of-band terminal pre-check for EVERY merge-stage durable wait (#368). A PR parked
+ * at any durable GitHub wait can be merged or closed out-of-band; without a per-branch check on the
+ * PR's OWN state, a wait that keys only off its declared trigger (e.g. `waiting_deps`' declared
+ * deps) strands its instance forever — ACTIVE, no incident, no timer boundary. `waiting_merge`
+ * already guarded this; centralising the check here closes the whole class so no merge stage can
+ * silently wedge on an out-of-band terminal transition.
+ *
+ * Reads the PR's live state (reusing an already-fetched `st` when the caller has one, e.g. block 2)
+ * and, if terminal, publishes the escape message its parked catch subscribes to via
+ * {@link flipToMergingThenPublish} — flipping to the transient `merging` so a slow pass can't
+ * double-signal, reverting on a failed publish. Returns `true` when it advanced the PR (the caller
+ * must `continue`), `false` when the PR is still live / unreadable and the caller should run its
+ * normal per-status logic. Conservative: an unreadable (`null`) or ambiguous (`unknown`/open) state
+ * never resolves terminal, so a false negative only costs a retry while dropping a live PR is
+ * impossible. */
+async function advanceIfTerminalOutOfBand(
+  data: DataLayer,
+  engine: EngineClient,
+  pr: { repo: string; number: number | string; pr_key: string; status: string },
+  token: string,
+  st?: PrState | null,
+): Promise<boolean> {
+  const state = st !== undefined ? st : await fetchPrState(pr.repo, pr.number, token);
+  const liveness = classifyPrLiveness(state);
+  if (liveness !== "merged" && liveness !== "closed") return false;
+  const fromStatus = pr.status; // capture before flip: flipToMergingThenPublish mutates it to `merging`
+  await flipToMergingThenPublish(
+    data,
+    engine,
+    pr.pr_key,
+    fromStatus,
+    outOfBandEscapeMessage(fromStatus, liveness, pr.pr_key),
+  );
+  console.log(`[poller] out-of-band ${liveness} (${fromStatus}) -> ${pr.pr_key}`);
+  return true;
+}
+
 /** Merge-stage poll pass (SPEC §11). Four durable waits, each keyed off the PR's `status`, are
  * advanced by correlating a message — mirroring the review-ready pattern so the process owns
  * the wait and this glue only signals when a GitHub condition is met:
@@ -1023,12 +1104,20 @@ async function mirrorTaskStatusForPr(data: DataLayer, prKey: string, status: "op
  *   • queued        → the queued PR landed → `merge-landed`; or it conflicts (DIRTY) → `merge-evicted`
  * On publish we flip status to the transient `merging` (which no branch scans) so a slow pass
  * can't double-signal, exactly as `pollReviews` flips to `converging`; `flipToMergingThenPublish`
- * reverts the flip if the publish fails so a failed handoff can't wedge the PR. */
-async function pollMerges(data: DataLayer, engine: EngineClient, token: string) {
+ * reverts the flip if the publish fails so a failed handoff can't wedge the PR.
+ *
+ * EVERY branch first runs {@link advanceIfTerminalOutOfBand} — one shared "is this PR already
+ * terminal (merged/closed) out-of-band?" pre-check — so no merge stage can silently strand when a PR
+ * is landed/closed outside the loop (the `waiting_deps` self-merged wedge, #368). */
+export async function pollMerges(data: DataLayer, engine: EngineClient, token: string) {
   // 1) Dependencies merged?
   for (const pr of await prs(data).find({ status: "waiting_deps" })) {
     const prKey = pr.pr_key;
     try {
+      // Out-of-band terminal FIRST: a PR merged/closed outside the loop while parked at `wait-deps`
+      // must converge even if its declared deps never clear (the #368 wedge). `wait-deps` subscribes
+      // only `deps-cleared`, so the shared pre-check publishes exactly that.
+      if (await advanceIfTerminalOutOfBand(data, engine, pr, token)) continue;
       const depRows = await deps(data).find({ pr_key: prKey });
       let allMerged = true;
       for (const d of depRows) {
@@ -1055,38 +1144,12 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
     try {
       const st = await fetchPrState(repo, number, token);
       if (st === null) continue; // no transport → skip this PR (others may still advance)
-      const liveness = classifyPrLiveness(st);
-      if (liveness === "merged") {
-        // Landed out-of-band (a maintainer clicked Merge, a mergify queue merged it, etc.). The
-        // instance is parked at `wait-mergeable`, which subscribes to `merge-ready` — NOT
-        // `merge-landed` (that catch, `wait-landed`, only exists later, after we enqueue). Publishing
-        // `merge-landed` here has no subscription to correlate to, so the engine drops it and the PR
-        // wedges forever in the transient `merging` status (which no poller branch re-scans).
-        // Publish `merge-ready` with a `ready` verdict instead: it routes through `gw-mergeable` to
-        // `attempt-merge`, whose idempotent already-merged check completes the loop (`mark-merged`).
-        await flipToMergingThenPublish(data, engine, prKey, "waiting_merge", {
-          name: "merge-ready",
-          correlationKey: prKey,
-          variables: { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
-        });
-        console.log(`[poller] already merged -> ${prKey}`);
-        continue;
-      }
-      if (liveness === "closed") {
-        // Closed on GitHub WITHOUT merging (e.g. superseded by a newer PR — #350). The PR can never
-        // land, so it must NOT be classified as blocked/conflict and escalated (that orphans the
-        // process on a dead PR, #342). Route it through the same canonical `merge-ready` → `ready` →
-        // `attempt-merge` path as the merged case; the merge worker's closed short-circuit records a
-        // terminal `abandoned` audit row and drives the loop down its terminate/abandon end event.
-        // One canonical abandon implementation lives in the worker — the poller only routes to it.
-        await flipToMergingThenPublish(data, engine, prKey, "waiting_merge", {
-          name: "merge-ready",
-          correlationKey: prKey,
-          variables: { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
-        });
-        console.log(`[poller] closed without merging -> ${prKey}`);
-        continue;
-      }
+      // Out-of-band terminal (merged/closed) → the shared pre-check publishes `merge-ready {ready}`,
+      // routing through `gw-mergeable → attempt-merge` whose idempotent already-merged check completes
+      // the loop (`mark-merged`) and whose closed short-circuit abandons a PR closed without merging
+      // (#342/#350). Reuse the `st` we just read so we don't double-fetch. This is the proven terminal
+      // path the whole class (#368) now shares.
+      if (await advanceIfTerminalOutOfBand(data, engine, pr, token, st)) continue;
       const verdict = classifyMergeability(st);
       if (verdict === "waiting") {
         // Frugal-CI remedy (#43): when the repo publishes a merge protocol that wants a fresh
@@ -1145,6 +1208,10 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
   for (const pr of await prs(data).find({ status: "waiting_lane" })) {
     const prKey = pr.pr_key;
     try {
+      // Out-of-band terminal FIRST: a lane-held PR merged/closed outside the loop must converge even
+      // if its lane predecessor never releases the hold. waiting_lane leaves the process parked at
+      // `wait-mergeable`, so the shared pre-check publishes `merge-ready {ready}` (→ attempt-merge).
+      if (await advanceIfTerminalOutOfBand(data, engine, pr, token)) continue;
       const lane = await mergeLaneDecisionForPr(data, prKey);
       if (lane?.isHeld) continue;
       await prs(data).update(prKey, { status: "waiting_merge", updated_at: now() });
@@ -1172,15 +1239,16 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
     try {
       const st = await fetchPrState(repo, number, token);
       if (st === null) continue; // no transport → skip this PR (others may still advance)
-      const verdict = queuedVerdict(st);
-      if (verdict === "landed") {
-        await flipToMergingThenPublish(data, engine, prKey, "queued", {
-          name: "merge-landed",
-          correlationKey: prKey,
-          variables: {},
-        });
-        console.log(`[poller] queued PR landed -> ${prKey}`);
-      } else if (verdict === "evicted") {
+      // Out-of-band terminal FIRST (reusing `st`): a queued PR merged out-of-band lands
+      // (`merge-landed` → mark-merged); one CLOSED out-of-band without merging can never land, so the
+      // pre-check re-arms it (`merge-evicted` → arm-merge) and block 2 abandons it — a closed queued
+      // PR would otherwise wedge, since `queuedVerdict` calls a non-DIRTY closed PR merely "waiting"
+      // (#368). The DIRTY-while-open eviction below still handles a live-but-conflicted queue drop.
+      if (await advanceIfTerminalOutOfBand(data, engine, pr, token, st)) continue;
+      // Terminal states (merged/closed) are handled by the shared pre-check above; here the PR is
+      // still open, so the only remaining reason to leave `wait-landed` is a live queue DROP — a real
+      // merge CONFLICT (`DIRTY`). `queuedVerdict` stays the canonical classifier for that.
+      if (queuedVerdict(st) === "evicted") {
         await flipToMergingThenPublish(data, engine, prKey, "queued", {
           name: "merge-evicted",
           correlationKey: prKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.106.3",
+  "version": "0.107.1",
   "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",
@@ -62,6 +62,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
     "@nanobpm/urban-testkit": "^0.5.0",
+    "@nanobpm/workflow": "^0.12.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/npm": "^13.1.5",

package/test/derivation-parity/README.md

@@ -0,0 +1,123 @@
+# Derivation-parity suite (`defineFlow` ports of the nwf goldens)
+
+Epic **nanobpm/nano-ide#314**, slice **S5 / #320**: port the seven hand-authored
+nano-workforce BPMN goldens in `resources/processes/*.bpmn` to the code-first
+`@nanobpm/workflow` `defineFlow` surface, and prove each derived model is
+**structurally equal** to its golden with the S0 parity harness
+(`@nanobpm/workflow/test-support` — `normalize` / `assertDerivationParity`).
+
+- `flows.ts` — the code-first ports (one `defineFlow` per model) plus a `PORTS`
+  registry that pairs each model with its port or its documented blocker.
+- `derivation-parity.test.ts` — runs `assertDerivationParity` for every ported
+  model, reports blocked models as skipped with their reason, and proves the
+  blocker against the goldens themselves.
+
+Run it with the repo suite (`npm test`) or directly:
+
+```sh
+node --experimental-strip-types --test test/derivation-parity/derivation-parity.test.ts
+```
+
+## Status
+
+Per the human decision on the **#320 escalation** — _(c)+(a): land the
+structurally-derivable goldens now at full whole-model parity, park the rest
+behind an upstream construct, and do **not** relax to node-surface parity_:
+
+| Model              | Top-level start/end | Status |
+| ------------------ | ------------------- | ------ |
+| `retro`            | 1 / 1               | ⛔ parked — class 3 (general service-task ioMapping) |
+| `convergence-loop` | 1 / 1               | ⛔ parked — class 2 (arbitrary graph) |
+| `spine-demo`       | 1 / 2               | ⛔ parked — class 1 (multi start/end) |
+| `readiness-gate`   | 1 / 5               | ⛔ parked — class 1 (multi start/end) |
+| `feature`          | 2 / 2               | ⛔ parked — class 1 (multi start/end) |
+| `merge-loop`       | 1 / 2               | ⛔ parked — class 1 (multi start/end) |
+| `plan-fanout`      | 3 / 3               | ⛔ parked — class 1 (multi start/end) |
+
+`retro` was a green full-parity port — a linear single-start/single-end agent
+pipeline — until the conformance work (#355/#356) added a conformance-escalation
+subgraph to its golden, which introduced a service task carrying a general
+`<zeebe:ioMapping>` the stock `task` builder cannot emit (class 3). All seven
+goldens are now parked, across **three** distinct blocker classes, each awaiting
+an upstream `@nanobpm/workflow` (nano-ide) construct + re-release (never a golden
+edit, never relaxed acceptance).
+
+## The blockers
+
+### Class 1 — multiple top-level start/end events (5 models)
+
+The published builder surface **`@nanobpm/workflow@0.12.0`** derives **exactly
+one** top-level `<bpmn:startEvent id="Start">` and **exactly one**
+`<bpmn:endEvent id="End">`, converging every top-level dangling branch into that
+single end (`Compiler.compile` in the package's `declarative.ts`). There is no
+terminal / explicit-end construct and no way to author multiple top-level start
+events.
+
+Five goldens have **multiple** top-level start and/or end events, so their
+derived model can never be structurally equal under `normalize` (which
+distinguishes `N` end events each with `in=1` from one end event with `in=N`).
+The suite's `class-1 blocked goldens genuinely have multiple top-level start/end
+events` diagnostic pins this against the goldens themselves.
+
+### Class 2 — arbitrary control-flow graph (`convergence-loop`)
+
+`convergence-loop` has a single start/end (it clears class 1) but its topology is
+**not expressible** with `@nanobpm/workflow@0.12.0`'s structured-only builder
+(`loop` / `switch` / `branch`). Single start/end is _necessary but not
+sufficient_. Three golden features have no structured-builder derivation, each
+pinned by a diagnostic in `derivation-parity.test.ts`:
+
+1. **Task-level back-edge merge.** The loop head `review-round` is a
+   `serviceTask` that merges **three** back-edges directly (`in=3`). But `loop()`
+   always inserts an exclusive-gateway loop head that absorbs the back-edge, so
+   the body task stays `in=1` — empirically demonstrated by the `loop() inserts a
+   gateway head` test.
+2. **Heterogeneous multi-way gateway.** `gw-status` is a single exclusive gateway
+   with **four** heterogeneous-condition out-edges (two `=x = "v"` equalities, one
+   complex boolean, one default). No `switch` (equalities + default) or `branch`
+   (one condition + default) emits that.
+3. **Shared merge+split gateway.** `gw-escalated` is a single exclusive gateway
+   that is at once a **five-way merge and a two-way split**, reached by back-edges
+   from five distinct points.
+
+The fix is an **arbitrary-graph / explicit-join (named-target)** builder upstream
+in `@nanobpm/workflow` — a **superset** of the class-1 gap.
+
+### Class 3 — general service-task ioMapping (`retro`)
+
+`retro` clears classes 1 and 2 (single start/end, structured topology), but its
+golden's `record-conformance-ack` service task carries a **general**
+`<zeebe:ioMapping>` — inputs `=planKey`→`planKey` and
+`=if (is defined(note)) then note else null`→`note`. `@nanobpm/workflow@0.12.0`'s
+`task` builder only emits an ioMapping as a side effect of a `prompt.append` (a
+single `appendPrompt` input); there is no way to declare arbitrary input/output
+mappings on a service task. Every other element of the golden IS expressible
+(`w.task`+prompt, `w.branch` for the `deviations?` gateway, `w.human` for the
+`conformance-escalation` userTask, envelopes) — this one service-task ioMapping
+is the sole gap. The `retro golden needs a general service-task ioMapping the
+stock builder cannot emit` diagnostic pins both halves (the golden needs it; the
+stock builder cannot produce it).
+
+The fix is a general `io: { input?, output? }` on the external `task`/`run`
+builder upstream in `@nanobpm/workflow` (**nano-ide#405**).
+
+## Resuming this slice
+
+The follow-up upstream slices (opened in **nanobpm/nano-ide** per decision path
+(a)) must add:
+
+- a terminal / explicit-end (+ multi-start) construct (unblocks class 1), **and**
+- an arbitrary-graph / explicit-join (named-target) builder (unblocks class 2 —
+  `convergence-loop`), **and**
+- a general service-task `io` mapping (unblocks class 3 — `retro`; nano-ide#405).
+
+Then, on a resumed run here:
+
+1. Bump the `@nanobpm/workflow` dependency to the release that carries the
+   construct(s).
+2. In `flows.ts`, replace each parked entry's `blockedReason` with a real
+   `flow: defineFlow(...)` port (author each model against exactly the features
+   it uses — see the per-model feature map in the #320 brief).
+
+No golden `.bpmn` file may be edited to force a match — the derivation must
+reproduce the checked-in golden.

package/test/derivation-parity/derivation-parity.test.ts

@@ -0,0 +1,177 @@
+// Derivation-parity suite for epic nanobpm/nano-ide#314 (S5, sub-issue #320).
+//
+// For every nano-workforce golden in `resources/processes/*.bpmn`, assert that
+// its code-first `defineFlow` port (see `./flows.ts`) derives a BPMN model that
+// is STRUCTURALLY EQUAL to the checked-in golden, using the S0 parity harness
+// (`@nanobpm/workflow/test-support`). The harness normalizes both models (strips
+// DI, canonicalizes ids/ordering) and diffs their semantic structure — nodes,
+// sequence flows, message subscriptions, timer/boundary definitions, user tasks,
+// and linked resources — with a legible red/green diff on mismatch.
+//
+// Ported models run a real `assertDerivationParity`; parked models (see
+// `./flows.ts`) are reported as skipped WITH their precise reason, in two
+// blocker classes — class 1: multiple top-level start/end events; class 2:
+// arbitrary control-flow graph (`convergence-loop`). Companion diagnostics prove
+// each blocker is real against the goldens themselves. No golden is modified to
+// force a match — the derivation must reproduce the checked-in file.
+
+import { test } from "node:test";
+import { readFileSync } from "node:fs";
+import { assert, assertEquals } from "#test-assert";
+import { assertDerivationParity, normalize } from "@nanobpm/workflow/test-support";
+import { declarativeToBpmn, defineFlow } from "@nanobpm/workflow";
+import { PORTS } from "./flows.ts";
+
+const ROOT = decodeURIComponent(new URL("../../", import.meta.url).pathname);
+const goldenPath = (model: string): string => `${ROOT}resources/processes/${model}.bpmn`;
+
+test("derivation parity — nano-workforce corpus", async (t) => {
+  for (const port of PORTS) {
+    const golden = goldenPath(port.model);
+    const flow = port.flow;
+    if (flow) {
+      await t.test(`${port.model} derives its golden`, () => {
+        assertDerivationParity(flow, golden);
+      });
+    } else {
+      await t.test(`${port.model} (pending port)`, { skip: port.blockedReason ?? "pending" }, () => {});
+    }
+  }
+});
+
+// Every entry either derives its golden or documents why it cannot — so the
+// corpus is fully accounted for and no model is silently dropped.
+test("every corpus model is either ported or has a documented blocker", () => {
+  const expected = [
+    "retro",
+    "spine-demo",
+    "readiness-gate",
+    "feature",
+    "convergence-loop",
+    "merge-loop",
+    "plan-fanout",
+  ];
+  assertEquals(
+    PORTS.map((p) => p.model),
+    expected,
+    "PORTS must cover all seven goldens in the epic's authoring order",
+  );
+  for (const port of PORTS) {
+    assert(
+      port.flow !== undefined || (port.blockedReason && port.blockedReason.length > 0),
+      `${port.model} must either be ported (flow) or carry a blockedReason`,
+    );
+  }
+});
+
+// The blockers are not guesses — prove each against the goldens themselves.
+//
+// CLASS 1 — five goldens have MORE THAN ONE top-level start and/or end event,
+// which the published `@nanobpm/workflow@0.12.0` compiler (a single
+// `<startEvent id="Start">` + single `<endEvent id="End">`) cannot derive.
+test("class-1 blocked goldens genuinely have multiple top-level start/end events", () => {
+  const countTag = (xml: string, tag: string): number =>
+    (xml.match(new RegExp(`<bpmn:${tag}\\b`, "g")) ?? []).length;
+
+  const multiStartEndBlocked = new Set(["spine-demo", "readiness-gate", "feature", "merge-loop", "plan-fanout"]);
+  for (const model of multiStartEndBlocked) {
+    const xml = readFileSync(goldenPath(model), "utf8");
+    const starts = countTag(xml, "startEvent");
+    const ends = countTag(xml, "endEvent");
+    assert(
+      starts > 1 || ends > 1,
+      `${model} is marked compiler-blocked but has ${starts} start(s)/${ends} end(s) — reclassify it`,
+    );
+  }
+
+  // The two single-start/single-end goldens (retro, convergence-loop) clear
+  // class 1; retro is class-3 blocked (a general service-task ioMapping),
+  // convergence-loop is class-2 blocked — both below.
+  for (const model of ["retro", "convergence-loop"]) {
+    const xml = readFileSync(goldenPath(model), "utf8");
+    assertEquals(countTag(xml, "startEvent"), 1, `${model} should have one start event`);
+    assertEquals(countTag(xml, "endEvent"), 1, `${model} should have one end event`);
+  }
+});
+
+// CLASS 3 — retro clears classes 1 & 2 (single start/end, structured topology)
+// but its golden carries a service task with a GENERAL <zeebe:ioMapping> — inputs
+// whose target is NOT `appendPrompt` — which @nanobpm/workflow@0.12.0's `task`
+// builder cannot emit (it only produces an ioMapping via a `prompt.append`, i.e.
+// a lone `appendPrompt` input). Prove both halves: the golden needs it, and the
+// stock builder cannot produce it (awaits nano-ide#405).
+test("retro golden needs a general service-task ioMapping the stock builder cannot emit", () => {
+  const xml = readFileSync(goldenPath("retro"), "utf8");
+  // (a) The golden has a service task carrying an ioMapping input to a non-prompt
+  //     target (`record-conformance-ack`: =planKey→planKey, note→note).
+  assert(
+    /target="planKey"/.test(xml) && /target="note"/.test(xml),
+    "retro golden should carry general ioMapping inputs (planKey, note) on record-conformance-ack",
+  );
+  // (b) The stock `task` builder only ever emits `appendPrompt` as an ioMapping
+  //     target — never a general input like `note` — so the golden is not
+  //     derivable until the upstream `io` construct lands.
+  const probe = defineFlow("io-probe", (w) => {
+    w.task("agent", {
+      jobType: "senior:retro",
+      prompt: { resourceId: "retro.md", bindingType: "latest", append: "=retroDigest" },
+    });
+  });
+  const derived = declarativeToBpmn(probe);
+  assert(/target="appendPrompt"/.test(derived), "prompt.append should emit an appendPrompt ioMapping input");
+  assert(
+    !/target="note"/.test(derived) && !/target="planKey"/.test(derived),
+    "the stock task builder cannot emit a general (non-appendPrompt) ioMapping input",
+  );
+});
+
+// CLASS 2 — convergence-loop has a single start/end (clears class 1) but an
+// ARBITRARY control-flow graph the structured-only builder cannot emit. Prove
+// the three specific features against the golden itself.
+test("convergence-loop golden has arbitrary-graph features the structured builder cannot emit", () => {
+  const xml = readFileSync(goldenPath("convergence-loop"), "utf8");
+  const between = (id: string, closeTag: string, tag: string): number => {
+    // Count <bpmn:<tag>> occurrences inside the element `id`, whose end is its
+    // own </bpmn:<closeTag>> (not the first nested close tag).
+    const open = xml.indexOf(`id="${id}"`);
+    assert(open >= 0, `convergence-loop golden is missing element id="${id}"`);
+    const rest = xml.slice(open);
+    const close = rest.indexOf(`</bpmn:${closeTag}>`);
+    assert(close >= 0, `convergence-loop golden element id="${id}" is missing its closing </bpmn:${closeTag}>`);
+    const body = rest.slice(0, close);
+    return (body.match(new RegExp(`<bpmn:${tag}\\b`, "g")) ?? []).length;
+  };
+  // (a) the loop head is a serviceTask that MERGES three back-edges directly.
+  assertEquals(between("review-round", "serviceTask", "incoming"), 3, "review-round should merge 3 flows on the task itself");
+  // (b) a single exclusive gateway forks FOUR heterogeneous-condition out-edges.
+  assertEquals(between("gw-status", "exclusiveGateway", "outgoing"), 4, "gw-status should be a 4-way exclusive gateway");
+  // (c) a single exclusive gateway is at once a 5-way merge and a 2-way split.
+  assertEquals(between("gw-escalated", "exclusiveGateway", "incoming"), 5, "gw-escalated should merge 5 flows");
+  assertEquals(between("gw-escalated", "exclusiveGateway", "outgoing"), 2, "gw-escalated should also split 2 ways");
+});
+
+// CLASS 2, empirical — demonstrate WHY the structured builder cannot reproduce
+// (a): a `loop()` whose body starts with a task derives an exclusive-gateway
+// loop head that absorbs the back-edge (in>=2), leaving the task itself at
+// in=1. The golden instead merges its back-edges directly into `review-round`
+// (in=3) with no loop-head gateway — a shape the builder cannot express.
+test("loop() inserts a gateway head, so back-edges cannot merge into a task", () => {
+  const probe = defineFlow("loop-head-probe", (w) => {
+    w.loop((b) => {
+      b.task("review-round", { jobType: "senior:pr-review" });
+      b.branch("done", { then: (g) => g.break() });
+    });
+  });
+  const model = normalize(declarativeToBpmn(probe));
+  const inDegree = (n: string): number => Number(/<in=(\d+)/.exec(n)?.[1] ?? "0");
+  const gateways = model.nodes.filter((n) => n.startsWith("exclusiveGateway"));
+  const tasks = model.nodes.filter((n) => n.startsWith("serviceTask"));
+  assert(
+    gateways.some((n) => inDegree(n) >= 2),
+    "loop() should derive an exclusive-gateway head that absorbs the back-edge (in>=2)",
+  );
+  assert(
+    tasks.every((n) => inDegree(n) <= 1),
+    "the loop-body task cannot itself be the back-edge merge (it stays in<=1)",
+  );
+});

package/test/derivation-parity/flows.ts

@@ -0,0 +1,149 @@
+// Code-first (`defineFlow`) ports of the hand-authored nano-workforce BPMN
+// goldens in `resources/processes/*.bpmn`, for epic nanobpm/nano-ide#314 (S5,
+// sub-issue #320). Each port must derive a BPMN model that is STRUCTURALLY equal
+// to its golden under the S0 derivation-parity harness
+// (`@nanobpm/workflow/test-support` — `normalize` / `assertDerivationParity`),
+// proving the code-first and model-first representations agree.
+//
+// STATUS (per the human decision on the nano-ide#320 escalation — (c)+(a): land
+// the structurally-derivable goldens at full whole-model parity, park the rest
+// pending an upstream construct, and do NOT relax to node-surface parity):
+//
+//   • All seven goldens are currently `blockedReason`-parked, in THREE distinct
+//     classes, each awaiting an upstream `@nanobpm/workflow` (nano-ide) construct
+//     + re-release — never a golden edit and never relaxed acceptance:
+//
+//     (1) MULTI top-level start/end (spine-demo, readiness-gate, feature,
+//         merge-loop, plan-fanout). `@nanobpm/workflow@0.12.0` derives EXACTLY
+//         ONE `<bpmn:startEvent id="Start">` + ONE `<bpmn:endEvent id="End">`,
+//         converging every dangler into that single end (see `Compiler.compile`
+//         in the package's `declarative.ts`). Needs a terminal/explicit-end
+//         (+ multi-start) construct.
+//
+//     (2) ARBITRARY control-flow graph (convergence-loop). Single start/end —
+//         so it clears class (1) — but its topology is NOT expressible with the
+//         structured-only builder (`loop`/`switch`/`branch`), empirically proven
+//         (see `derivation-parity.test.ts`): its loop head `review-round` is a
+//         serviceTask that MERGES three back-edges directly (in=3), whereas
+//         `loop()` always inserts an exclusive-gateway loop head (the task stays
+//         in=1); `gw-status` is a single exclusive gateway with FOUR
+//         heterogeneous-condition out-edges (two `=x = "v"`, one complex boolean,
+//         one default) which no `switch`/`branch` emits; and `gw-escalated` is a
+//         single gateway that is simultaneously a five-way merge and a two-way
+//         split. Single start/end is necessary but NOT sufficient. Needs an
+//         arbitrary-graph / explicit-join (named-target) builder — a SUPERSET of
+//         the class-(1) gap.
+//
+//     (3) GENERAL service-task ioMapping (retro). retro WAS a green full-parity
+//         port (a linear gather → synthesize → record agent pipeline) until the
+//         conformance work (nano-workforce #355/#356) added a conformance-
+//         escalation subgraph to its golden. Every new element ports with the
+//         stock builder (`w.branch` for the `deviations?` gateway, `w.human` for
+//         the `conformance-escalation` userTask, `w.task`+prompt/envelopes for
+//         the service tasks) EXCEPT `record-conformance-ack`: a service task with
+//         a general <zeebe:ioMapping> (inputs `=planKey`→planKey and
+//         `=if (is defined(note)) then note else null`→note). @nanobpm/workflow@
+//         0.12.0's `task` builder only emits an ioMapping via a `prompt.append`
+//         (a single `appendPrompt` input), so this task is not derivable. Needs a
+//         general `io` on the task/run builder upstream (nano-ide#405).
+//
+// A resumed run flips any parked model to a real `flow` once the corresponding
+// upstream construct lands and `@nanobpm/workflow` is bumped past 0.12.0.
+
+import type { DeclarativeFlow } from "@nanobpm/workflow";
+
+/** One model's port entry: the golden basename plus EITHER the derived flow
+ *  (when it can be reproduced) OR the reason it is blocked — never both and never
+ *  neither. Modelled as a discriminated union so a partial/contradictory entry
+ *  (both `flow` and `blockedReason`, or neither) fails to compile. */
+export type PortEntry =
+  | {
+      /** The golden model basename under `resources/processes/<model>.bpmn`. */
+      readonly model: string;
+      /** The derived `defineFlow` — a structurally-faithful port exists. */
+      readonly flow: DeclarativeFlow;
+      readonly blockedReason?: never;
+    }
+  | {
+      /** The golden model basename under `resources/processes/<model>.bpmn`. */
+      readonly model: string;
+      readonly flow?: never;
+      /** Why whole-model parity is not yet achievable — precisely. */
+      readonly blockedReason: string;
+    };
+
+// ── retro (PARKED — class 3) ─────────────────────────────────────────────────
+// retro WAS a green full-parity port — a linear gather → synthesize → record
+// agent pipeline. The conformance work (nano-workforce #355/#356) then added a
+// conformance-escalation subgraph to the golden: a `deviations?` exclusive
+// gateway, a `conformance-escalation` userTask, and `senior:conformance` /
+// `pr.conformance-record` / `pr.conformance-ack` service tasks. All of those ARE
+// expressible with the stock builder (`w.branch`, `w.human`, `w.task`+prompt,
+// envelopes) EXCEPT `record-conformance-ack`: it carries a general
+// <zeebe:ioMapping> (inputs `=planKey`→planKey and
+// `=if (is defined(note)) then note else null`→note), which
+// @nanobpm/workflow@0.12.0's `task` builder cannot emit — it only produces an
+// ioMapping via a `prompt.append` (a single `appendPrompt` input). So retro
+// regresses to a parked model pending the upstream construct: a general `io` on
+// the external `task`/`run` builder (nano-ide#405). It flips back to a green
+// port once that lands and @nanobpm/workflow is bumped past 0.12.0.
+
+const RETRO_IO_BLOCK =
+  "blocked (general service-task ioMapping): retro's golden gained a " +
+  "conformance-escalation subgraph whose `record-conformance-ack` service task " +
+  "carries a general <zeebe:ioMapping> (inputs =planKey→planKey and " +
+  "=if (is defined(note)) then note else null→note). @nanobpm/workflow@0.12.0's " +
+  "`task` builder only emits an ioMapping via a `prompt.append` (a single " +
+  "appendPrompt input), so this task is not derivable. Every other element of " +
+  "the golden IS expressible (w.task+prompt, w.branch, w.human, envelopes). " +
+  "Awaits a general `io` on the task/run builder upstream in @nanobpm/workflow " +
+  "(nano-ide#405).";
+
+/** The single-top-level-end/start compiler limitation, reused as the
+ *  `blockedReason` for every golden that has more than one top-level start
+ *  and/or end event. */
+const MULTI_START_END_BLOCK =
+  "blocked: @nanobpm/workflow@0.12.0 derives a single top-level start/end and " +
+  "converges all danglers into one <endEvent id=\"End\">; this golden has " +
+  "multiple top-level start and/or end events, which the published compiler " +
+  "cannot reproduce. Awaits an upstream terminal/explicit-end (+ multi-start) " +
+  "construct in @nanobpm/workflow (nano-ide).";
+
+/** All seven ports, keyed by model, in the epic's stated authoring order. */
+export const PORTS: readonly PortEntry[] = [
+  { model: "retro", blockedReason: RETRO_IO_BLOCK },
+  {
+    model: "spine-demo",
+    blockedReason: `${MULTI_START_END_BLOCK} (spine-demo: 1 start, 2 ends)`,
+  },
+  {
+    model: "readiness-gate",
+    blockedReason: `${MULTI_START_END_BLOCK} (readiness-gate: 1 start, 5 ends)`,
+  },
+  {
+    model: "feature",
+    blockedReason: `${MULTI_START_END_BLOCK} (feature: 2 starts, 2 ends)`,
+  },
+  {
+    model: "convergence-loop",
+    blockedReason:
+      "blocked (arbitrary control-flow graph): single top-level start/end, but " +
+      "its topology is not expressible with @nanobpm/workflow@0.12.0's " +
+      "structured-only builder (loop/switch/branch). Proven in the test suite: " +
+      "the loop head `review-round` is a serviceTask that merges 3 back-edges " +
+      "directly (in=3), but loop() always inserts an exclusive-gateway head " +
+      "(task stays in=1); `gw-status` is one gateway with 4 heterogeneous-" +
+      "condition out-edges (no switch/branch emits that); `gw-escalated` is one " +
+      "gateway that is at once a 5-way merge and a 2-way split. Awaits an " +
+      "arbitrary-graph / explicit-join (named-target) builder upstream in " +
+      "@nanobpm/workflow (nano-ide) — a superset of the multi-start/end gap.",
+  },
+  {
+    model: "merge-loop",
+    blockedReason: `${MULTI_START_END_BLOCK} (merge-loop: 1 start, 2 ends)`,
+  },
+  {
+    model: "plan-fanout",
+    blockedReason: `${MULTI_START_END_BLOCK} (plan-fanout: 3 starts, 3 ends)`,
+  },
+];