@nanobpm/nano-workforce 0.106.2 → 0.107.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Bug Fixes
+
+* **models:** regenerate stale retro.bpmn DI ([#365](https://github.com/nanobpm/nano-workforce/issues/365)) ([5619ee5](https://github.com/nanobpm/nano-workforce/commit/5619ee5805fb788ae5deebeb75bb0aa11f9c478d)), closes [355/#356](https://github.com/nanobpm/nano-workforce/issues/356)
+
 ## [0.106.2](https://github.com/nanobpm/nano-workforce/compare/v0.106.1...v0.106.2) (2026-08-20)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.106.2",
+  "version": "0.107.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",
@@ -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/resources/processes/retro.bpmn

@@ -146,27 +146,27 @@
         <dc:Bounds x="616" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-deviations" bpmnElement="gw-deviations" isMarkerVisible="true">
-        <dc:Bounds x="776" y="95" width="50" height="50" />
+        <dc:Bounds x="816" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="770" y="65" width="62" height="14" />
+          <dc:Bounds x="801" y="76" width="81" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_conformance-escalation" bpmnElement="conformance-escalation">
-        <dc:Bounds x="751" y="240" width="100" height="80" />
+        <dc:Bounds x="966" y="240" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record-conformance-ack" bpmnElement="record-conformance-ack">
-        <dc:Bounds x="911" y="240" width="100" height="80" />
+        <dc:Bounds x="1166" y="240" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_synthesize" bpmnElement="synthesize">
-        <dc:Bounds x="1056" y="80" width="100" height="80" />
+        <dc:Bounds x="1366" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record" bpmnElement="record">
-        <dc:Bounds x="1256" y="80" width="100" height="80" />
+        <dc:Bounds x="1566" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_End" bpmnElement="End">
-        <dc:Bounds x="1456" y="102" width="36" height="36" />
+        <dc:Bounds x="1766" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1434" y="143" width="80" height="14" />
+          <dc:Bounds x="1744" y="143" width="80" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNEdge id="BPMNEdge_f_start" bpmnElement="f_start">
@@ -183,32 +183,36 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toDeviationsGw" bpmnElement="f_toDeviationsGw">
         <di:waypoint x="716" y="120" />
-        <di:waypoint x="776" y="120" />
+        <di:waypoint x="816" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_noDeviations" bpmnElement="f_noDeviations">
-        <di:waypoint x="826" y="120" />
-        <di:waypoint x="1056" y="120" />
+        <di:waypoint x="866" y="120" />
+        <di:waypoint x="1366" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toRecord" bpmnElement="f_toRecord">
+        <di:waypoint x="1466" y="120" />
+        <di:waypoint x="1566" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toEnd" bpmnElement="f_toEnd">
+        <di:waypoint x="1666" y="120" />
+        <di:waypoint x="1766" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_deviations" bpmnElement="f_deviations">
-        <di:waypoint x="801" y="145" />
-        <di:waypoint x="801" y="240" />
+        <di:waypoint x="841" y="145" />
+        <di:waypoint x="841" y="280" />
+        <di:waypoint x="966" y="280" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="846" y="206" width="74" height="14" />
+        </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toConformanceAck" bpmnElement="f_toConformanceAck">
-        <di:waypoint x="851" y="280" />
-        <di:waypoint x="911" y="280" />
+        <di:waypoint x="1066" y="280" />
+        <di:waypoint x="1166" y="280" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ackToSynthesize" bpmnElement="f_ackToSynthesize">
-        <di:waypoint x="1011" y="280" />
-        <di:waypoint x="1106" y="280" />
-        <di:waypoint x="1106" y="160" />
-      </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toRecord" bpmnElement="f_toRecord">
-        <di:waypoint x="1156" y="120" />
-        <di:waypoint x="1256" y="120" />
-      </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toEnd" bpmnElement="f_toEnd">
-        <di:waypoint x="1356" y="120" />
-        <di:waypoint x="1456" y="120" />
+        <di:waypoint x="1266" y="280" />
+        <di:waypoint x="1416" y="280" />
+        <di:waypoint x="1416" y="160" />
       </bpmndi:BPMNEdge>
     </bpmndi:BPMNPlane>
   </bpmndi:BPMNDiagram>

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)`,
+  },
+];