@nanobpm/nano-workforce 0.107.1 → 0.108.0

package/.github/workflows/ci.yml

@@ -5,6 +5,12 @@ on:
     branches: [main]
   push:
     branches: [main]
+  # Merge-skew guard (issue #366): also run the required gates against the merge queue's
+  # PROSPECTIVE merged commit (GitHub Actions `merge_group` event). Several gates assert a whole-repo invariant (migration prefixes,
+  # BPMN DI freshness, committed generated artifacts) that two PRs can each satisfy in isolation yet
+  # violate once BOTH land on `main`. Validating the speculative merge commit the queue builds — not
+  # the stale PR head — blocks such a merge categorically instead of letting it poison the next PR.
+  merge_group:
 
 permissions:
   contents: read
@@ -77,3 +83,30 @@ jobs:
       - name: E2E (urban-testkit)
         run: npm run e2e
 
+  # FINAL regression guard for epic nano-ide#314 (S6, #321): the compounding oracle that keeps the
+  # code-first (`defineFlow`) and model-first (`.bpmn`) representations of the nano-workforce corpus
+  # in lockstep. For every model it DERIVES the BPMN from its defineFlow port, structurally DIFFS it
+  # against the checked-in golden via the S0 harness (@nanobpm/workflow/test-support), and DEPLOYS
+  # the derived model to the in-process @nanobpm/engine-wasm engine — failing on any structural drift
+  # OR deploy rejection. Parked models (awaiting an upstream construct) must each carry a documented
+  # blocker, and a self-proving canary asserts the oracle's red path genuinely fires so the gate can
+  # never rot into a vacuous green while the corpus is parked. Hermetic (in-process wasm engine, no
+  # sockets), so it runs on every PR/push as its own job.
+  derivation-parity:
+    name: derivation parity (nwf corpus regression guard)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Derive + diff + deploy the full nwf corpus
+        run: npm run check:derivation-parity
+

package/.github/workflows/invariants.yml

@@ -0,0 +1,72 @@
+name: Whole-repo invariants (merge-skew guard)
+
+# Closes the merge-skew failure class (issue #366).
+#
+# Several gates assert a GLOBAL invariant / checked-in DERIVED artifact — `derived == f(sources)` —
+# but the main CI only ever verifies them against a PR's OWN head. Two PRs can each pass in isolation
+# and still break the invariant once BOTH squash-merge, because `main`'s `derived` is then
+# `f(sources_A ∪ sources_B)`, which neither branch's green CI ever saw (the 052 migration collision,
+# #359; the stale `retro.bpmn` DI, #365). Nothing re-checked `main`, so the breakage landed silently
+# and poisoned the next unrelated PR to touch the same job.
+#
+# This lean workflow re-asserts those whole-repo invariants where the merge actually happens:
+#   - `merge_group`  — the queue's PROSPECTIVE merged commit, so a skew is blocked BEFORE it lands.
+#   - `push: [main]` — a fast backstop that fails a `main`-scoped build within minutes if something
+#                      slipped through, instead of first surfacing on an unrelated open PR.
+#   - `schedule`     — a daily catch-all for any skew introduced by a merge that bypassed the queue.
+on:
+  merge_group:
+  push:
+    branches: [main]
+  schedule:
+    # 06:00 UTC daily — cheap catch-all backstop.
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  invariants:
+    name: whole-repo invariants
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history: the migration immutability gate diffs against the merge-base with
+          # origin/main, and the layout gate needs the whole tree — neither works on a shallow clone.
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Prefix-collision (+ immutability): two branches that each took "the next" free migration
+      # prefix collide once merged. Re-run on the merged/`main` tree so the collision can't hide.
+      - name: Check migration prefixes (no collisions)
+        run: npm run check:migrations
+
+      # BPMN DI freshness: a merged semantic model can carry flows whose DI was regenerated on neither
+      # branch. Regenerate the DI over the merged model and fail if any committed diagram is stale.
+      - name: Check BPMN diagram freshness (layout)
+        run: npm run layout:check
+
+      # Generated-artifact freshness (`urban gen --check`): landscape.gen.html, JSON Schemas / OpenAPI,
+      # the processos grammar (ir.gbnf) and friends are `derived == f(sources)` — re-derive over the
+      # merged sources and fail if a committed artifact drifted.
+      - name: Check generated artifacts (urban gen --check)
+        run: npm run gen:check
+
+      # Navigation index is another checked-in derived artifact; re-assert it on the merged tree too.
+      - name: Check navigation index freshness
+        run: npm run sync:nav:check
+
+      # Backstop: catch ANY other committed generated file that the merged sources render stale, even
+      # one without its own `--check` script above. A clean tree is the whole-repo invariant.
+      - name: No stale committed artifacts on the merged tree
+        run: git diff --exit-code

package/AGENTS.md

@@ -272,7 +272,13 @@ Migrations live in `db/migrations/*.sql` and are **auto-applied on boot** from
   Check `origin/main`, not your branch point — a fan-out epic branch forks at one
   prefix while `main` keeps advancing, so the branch-local "next" number collides
   on merge. Two files must never share a prefix; `npm run check:migrations`
-  (a CI gate) enforces this and fails the build on any new duplicate.
+  (a CI gate) enforces this and fails the build on any new duplicate. Because a
+  prefix collision only exists in the *union* of two branches, this gate — like
+  `layout:check` and the generated-artifact `--check`s — is also re-run on the
+  merge queue's **prospective merged commit** and on **push to `main`** by
+  `.github/workflows/invariants.yml` (issue #366), so a merge-skew collision is
+  blocked at merge time or fails a `main`-scoped build within minutes rather than
+  first surfacing on an unrelated open PR.
 - **A merged migration is IMMUTABLE — never rename, delete, or edit it.** The
   runtime keys the `_urban_migrations` ledger by *filename*, so a renamed file is
   a *new* migration to the runner: it re-runs its DDL against an already-migrated

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.108.0](https://github.com/nanobpm/nano-workforce/compare/v0.107.2...v0.108.0) (2026-08-20)
+
+
+### Features
+
+* **derivation-parity:** un-park retro to full whole-model parity ([#372](https://github.com/nanobpm/nano-workforce/issues/372)) ([1320838](https://github.com/nanobpm/nano-workforce/commit/1320838251646258ec2151a547ed2b5573ce1168)), closes [nano-ide#405](https://github.com/nano-ide/issues/405) [355/#356](https://github.com/nanobpm/nano-workforce/issues/356) [#371](https://github.com/nanobpm/nano-workforce/issues/371)
+
+## [0.107.2](https://github.com/nanobpm/nano-workforce/compare/v0.107.1...v0.107.2) (2026-08-20)
+
+
+### Bug Fixes
+
+* **ci:** close the merge-skew failure class — re-check whole-repo invariants on the post-merge state ([#367](https://github.com/nanobpm/nano-workforce/issues/367)) ([62f5214](https://github.com/nanobpm/nano-workforce/commit/62f5214961cdb82a708d7cc08acecbf5eecf25ed)), closes [#359](https://github.com/nanobpm/nano-workforce/issues/359) [#365](https://github.com/nanobpm/nano-workforce/issues/365) [#366](https://github.com/nanobpm/nano-workforce/issues/366)
+
 ## [0.107.1](https://github.com/nanobpm/nano-workforce/compare/v0.107.0...v0.107.1) (2026-08-20)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.107.1",
+  "version": "0.108.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",
@@ -41,6 +41,8 @@
     "heal:migrations": "node --experimental-strip-types scripts/heal-migration-ledger.ts",
     "check:contracts": "node --experimental-strip-types scripts/check-contracts.ts",
     "reconcile:contracts": "node --experimental-strip-types scripts/reconcile-contracts.ts",
+    "precheck:derivation-parity": "urban gen",
+    "check:derivation-parity": "node --experimental-strip-types scripts/check-derivation-parity.ts",
     "gen": "urban gen",
     "gen:check": "urban gen --check",
     "layout": "node --experimental-strip-types scripts/layout-bpmn.ts",
@@ -62,7 +64,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
     "@nanobpm/urban-testkit": "^0.5.0",
-    "@nanobpm/workflow": "^0.12.0",
+    "@nanobpm/workflow": "^0.13.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/npm": "^13.1.5",

package/scripts/check-derivation-parity.ts

@@ -0,0 +1,214 @@
+// check-derivation-parity — the FINAL regression guard for epic nanobpm/nano-ide#314 (S6, #321).
+//
+// This is the compounding oracle that keeps the code-first (`defineFlow`) and model-first (`.bpmn`)
+// representations of the nano-workforce corpus in lockstep. For EVERY golden under
+// `resources/processes/*.bpmn` it runs the full derive → diff → deploy loop:
+//
+//   (a) DERIVE  — take the golden's `defineFlow` port (test/derivation-parity/flows.ts) and derive
+//                 its BPMN with `@nanobpm/workflow`.
+//   (b) DIFF    — structurally compare the derived model against the checked-in golden using the S0
+//                 parity harness (`@nanobpm/workflow/test-support`'s `normalize` / `assertDerivation-
+//                 Parity`). The normalization/diff is NEVER reimplemented here — this gate only calls
+//                 the shared harness, so the code-first check can't drift from the unit suite's.
+//   (c) DEPLOY  — deploy the derived model to the in-process `@nanobpm/engine-wasm` engine (via
+//                 `@nanobpm/urban-testkit`) and assert the engine ACCEPTS it.
+//
+// Any structural drift (b) OR deploy rejection (c) fails the build.
+//
+// PARKED MODELS ARE ACCOUNTED FOR, NOT IGNORED. `retro` is a green whole-model parity port; the
+// remaining corpus is parked behind upstream `@nanobpm/workflow` constructs (see
+// test/derivation-parity/flows.ts for the two blocker classes). Each parked model must carry a
+// documented `blockedReason`; a model that is neither ported nor documented fails this gate, so the
+// corpus can never silently lose coverage. As each parked model flips to a real `flow` upstream, it
+// is automatically pulled into the full derive → diff → deploy loop here with NO change to this
+// script.
+//
+// SELF-PROVING CANARY. To keep the gate honest even while most of the corpus is parked, a gate that
+// merely iterated it could be a near-vacuous green — it could rot without anyone noticing. So before
+// touching the corpus we run a CANARY that proves the oracle's RED path genuinely fires: a faithful
+// derived flow deploys green and diffs green, a drifted derivation is CAUGHT by the diff, and a
+// corrupted model is REJECTED by the engine. If any red path fails to fire (the diff misses drift,
+// or the engine accepts garbage), the gate fails — the oracle must be able to say no.
+
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createWasmEngineClient } from "@nanobpm/urban-testkit";
+import type { DeclarativeFlow } from "@nanobpm/workflow";
+import { declarativeToBpmn, defineFlow, toDeployableBpmn } from "@nanobpm/workflow";
+import { assertDerivationParity } from "@nanobpm/workflow/test-support";
+import { PORTS } from "../test/derivation-parity/flows.ts";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const PROCESSES_DIR = join(REPO_ROOT, "resources", "processes");
+const goldenPath = (model: string): string => join(PROCESSES_DIR, `${model}.bpmn`);
+
+type WasmEngine = Awaited<ReturnType<typeof createWasmEngineClient>>;
+
+const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+/** Deploy a derived flow's *deployable* BPMN (semantic model + auto-layout DI) to the wasm engine
+ *  and assert acceptance. Throws when the engine rejects the model or reports nothing deployed. */
+async function deployDerived(engine: WasmEngine, id: string, flow: DeclarativeFlow): Promise<void> {
+  const xml = await toDeployableBpmn(flow);
+  const result = await engine.deployResources([{ name: `${id}.bpmn`, content: xml, contentType: "application/xml" }]);
+  if (!result || result.deployed < 1) {
+    throw new Error(`engine did not accept derived "${id}" (deployed=${result?.deployed ?? 0})`);
+  }
+}
+
+/** Prove the derive → diff → deploy oracle can actually say NO, so an all-parked corpus can't let
+ *  this gate rot into a vacuous green. Pushes a line onto `errors` for any red path that fails to
+ *  fire. */
+async function proveOracleFiresRed(engine: WasmEngine, errors: string[]): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-parity-canary-"));
+  try {
+    const canary = defineFlow("parity-canary", (w) => {
+      w.task("step-a", { jobType: "senior:noop" });
+    });
+    const golden = join(dir, "parity-canary.bpmn");
+    writeFileSync(golden, declarativeToBpmn(canary), "utf8");
+
+    // DIFF, green: a faithful derivation matches its own golden.
+    try {
+      assertDerivationParity(canary, golden);
+    } catch (e) {
+      errors.push(`  canary: a faithful derivation was reported as drift — the diff is broken (${errMsg(e)})`);
+    }
+
+    // DIFF, red: a structurally different derivation MUST be caught.
+    const drifted = defineFlow("parity-canary", (w) => {
+      w.task("step-a", { jobType: "senior:noop" });
+      w.task("step-b", { jobType: "senior:noop" });
+    });
+    let structuralFired = false;
+    try {
+      assertDerivationParity(drifted, golden);
+    } catch {
+      structuralFired = true;
+    }
+    if (!structuralFired) {
+      errors.push("  canary: the structural-drift oracle did NOT fire (an added node slipped past the diff)");
+    }
+
+    // DEPLOY, green: a valid derived model is accepted by the engine.
+    try {
+      await deployDerived(engine, "parity-canary", canary);
+    } catch (e) {
+      errors.push(`  canary: the engine rejected a VALID derived model — the deploy oracle is broken (${errMsg(e)})`);
+    }
+
+    // DEPLOY, red: a corrupted model MUST be rejected.
+    let deployFired = false;
+    try {
+      await engine.deployResources([{ name: "corrupt.bpmn", content: "<not-bpmn/>", contentType: "application/xml" }]);
+    } catch {
+      deployFired = true;
+    }
+    if (!deployFired) {
+      errors.push("  canary: the deploy-rejection oracle did NOT fire (the engine accepted invalid BPMN)");
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Assert PORTS covers EXACTLY the checked-in goldens under
+ *  `resources/processes/*.bpmn`. Without this the guard's "full corpus" claim is
+ *  unproven: a newly-added golden with no PORTS entry would be silently skipped
+ *  (eroding coverage while still reporting OK), and a stale PORTS entry for a
+ *  deleted golden would iterate a model that no longer exists. Both directions
+ *  fail the gate. */
+function assertPortsCoverGoldens(errors: string[]): void {
+  const goldens = readdirSync(PROCESSES_DIR)
+    .filter((f) => f.endsWith(".bpmn"))
+    .map((f) => f.slice(0, -".bpmn".length));
+  const ported = PORTS.map((p) => p.model);
+
+  const missing = goldens.filter((g) => !ported.includes(g)).sort();
+  if (missing.length > 0) {
+    errors.push(
+      `  PORTS is missing ${missing.length} checked-in golden(s) under resources/processes ` +
+        `(${missing.join(", ")}) — add a derived flow or a documented blockedReason so the ` +
+        `"full corpus" guard can't silently skip them.`,
+    );
+  }
+
+  const orphaned = ported.filter((m) => !goldens.includes(m)).sort();
+  if (orphaned.length > 0) {
+    errors.push(
+      `  PORTS references ${orphaned.length} model(s) with no golden under resources/processes ` +
+        `(${orphaned.join(", ")}) — remove the stale entry or restore its golden.`,
+    );
+  }
+
+  const seen = new Set<string>();
+  const duplicated = new Set<string>();
+  for (const m of ported) {
+    if (seen.has(m)) duplicated.add(m);
+    seen.add(m);
+  }
+  if (duplicated.size > 0) {
+    errors.push(
+      `  PORTS has duplicate entries for ${duplicated.size} model(s) (${[...duplicated].sort().join(", ")}) — ` +
+        `each golden must appear exactly once.`,
+    );
+  }
+}
+
+async function main(): Promise<void> {
+  const errors: string[] = [];
+  const engine = await createWasmEngineClient();
+
+  let ported = 0;
+  let deployed = 0;
+  let parked = 0;
+
+  try {
+    assertPortsCoverGoldens(errors);
+    await proveOracleFiresRed(engine, errors);
+
+    for (const port of PORTS) {
+      if (port.flow) {
+        ported++;
+        const golden = goldenPath(port.model);
+        try {
+          assertDerivationParity(port.flow, golden);
+        } catch (e) {
+          errors.push(`  ${port.model}: STRUCTURAL DRIFT vs golden — ${errMsg(e)}`);
+          continue; // a model that doesn't derive its golden can't be trusted to deploy meaningfully
+        }
+        try {
+          await deployDerived(engine, port.model, port.flow);
+          deployed++;
+        } catch (e) {
+          errors.push(`  ${port.model}: DEPLOY REJECTED by wasm engine — ${errMsg(e)}`);
+        }
+      } else {
+        parked++;
+        if (!port.blockedReason || port.blockedReason.trim().length === 0) {
+          errors.push(
+            `  ${port.model}: neither ported (no flow) nor documented (no blockedReason) — every ` +
+              `corpus model must derive its golden or carry a precise blocker.`,
+          );
+        }
+      }
+    }
+  } finally {
+    // Release the underlying WASM engine resources so repeated runs (local / CI matrix) don't leak.
+    await engine.close();
+  }
+
+  if (errors.length > 0) {
+    console.error(`check-derivation-parity: the nano-workforce corpus failed its derivation-parity guard:\n${errors.join("\n")}`);
+    process.exit(1);
+  }
+
+  console.log(
+    `check-derivation-parity: OK (${PORTS.length} corpus models — ${ported} ported ` +
+      `[${deployed} deploy-accepted by the wasm engine], ${parked} documented-parked; oracle red paths verified).`,
+  );
+}
+
+if (import.meta.main) main();

package/scripts/check-migrations.test.ts

@@ -6,7 +6,7 @@
 // with origin/main; here we drive its diff classifier directly with representative
 // `git diff --find-renames --name-status` output so each violation shape is pinned.
 import test from "node:test";
-import { immutabilityErrorsFromDiff } from "./check-migrations.ts";
+import { collisionErrorsFromFiles, immutabilityErrorsFromDiff } from "./check-migrations.ts";
 import { assert, assertEquals } from "#test-assert";
 
 test("a rename of a merged migration is a violation", () => {
@@ -56,3 +56,41 @@ test("mixed changes report every violation but ignore the addition", () => {
   assert(errors.some((e) => /DELETED/.test(e)));
   assert(errors.some((e) => /RENAMED/.test(e)));
 });
+
+// Merge-skew regression coverage (issue #366).
+//
+// The failure class this pins: two PRs each pass `check:migrations` on their OWN head, but their
+// COMBINATION on `main` after both squash-merge violates the prefix-collision invariant — because
+// neither branch's green CI ever saw the other's file. The 052 collision (#351 + #355, hotfixed in
+// #359) was exactly this. Driving the pure collision detector with each branch's tree AND their union
+// demonstrates that only the post-merge state trips the gate, which is why the gate must re-run on
+// the prospective merged commit (merge_group) / on push to `main`, not just PR heads.
+test("merge skew: two individually-clean branches whose union collides IS caught", () => {
+  const mainTree = ["050_capability_gates.sql", "051_merges_per_day.sql"];
+  // Each branch independently picks the same "next free" prefix (060) without seeing its sibling.
+  const branchA = [...mainTree, "060_plan_conformance.sql"];
+  const branchB = [...mainTree, "060_worker_durable_resume.sql"];
+
+  // On its own head, each branch is clean — this is why both PRs go green in isolation.
+  assertEquals(collisionErrorsFromFiles(branchA), [], "branch A alone has no colliding prefix");
+  assertEquals(collisionErrorsFromFiles(branchB), [], "branch B alone has no colliding prefix");
+
+  // The post-merge tree on `main` (git merges both files cleanly — the names don't textually
+  // conflict) now shares slot 060. The gate, re-run on that merged state, catches it.
+  const mergedOnMain = [...new Set([...branchA, ...branchB])].sort();
+  const errors = collisionErrorsFromFiles(mergedOnMain);
+  assertEquals(errors.length, 1, "the merged tree has exactly one colliding prefix");
+  assert(/prefix 060/.test(errors[0]));
+  assert(/060_plan_conformance.sql/.test(errors[0]));
+  assert(/060_worker_durable_resume.sql/.test(errors[0]));
+});
+
+test("collision detector flags a non-NNN shape and grandfathers historical dupes", () => {
+  assert(collisionErrorsFromFiles(["nope.sql"]).some((e) => /required NNN_name.sql shape/.test(e)));
+  // Grandfathered historical collisions (already applied forward-only) must stay exempt.
+  assertEquals(
+    collisionErrorsFromFiles(["052_plan_conformance.sql", "052_worker_durable_resume.sql"]),
+    [],
+    "grandfathered prefix 052 is not a new violation",
+  );
+});

package/scripts/check-migrations.ts

@@ -150,11 +150,13 @@ function checkImmutability(errors: string[]): boolean {
   return true;
 }
 
-function main(): void {
-  const files = readdirSync(MIGRATIONS_DIR)
-    .filter((f) => f.endsWith(".sql"))
-    .sort();
-
+/** Classify a migration file listing into shape + prefix-collision errors. Pure over the file list
+ *  so the MERGE-SKEW scenario can be pinned in a test: two individually-clean branches each pass this
+ *  over their OWN tree, but the gate must fail over the UNION that lands on `main` after both merge
+ *  (issue #366). This is exactly why the gate has to re-run on the post-merge state — neither branch's
+ *  green CI ever saw the other's prefix. Grandfathered historical collisions stay exempt. Exported
+ *  for unit coverage. */
+export function collisionErrorsFromFiles(files: readonly string[]): string[] {
   const errors: string[] = [];
   const byPrefix = new Map<string, string[]>();
 
@@ -175,13 +177,23 @@ function main(): void {
   for (const [prefix, group] of byPrefix) {
     if (group.length > 1 && !GRANDFATHERED_DUPES.has(prefix)) {
       errors.push(
-        `  prefix ${prefix} is used by ${group.length} files: ${group.join(", ")} — ` +
+        `  prefix ${prefix} is used by ${group.length} files: ${[...group].sort().join(", ")} — ` +
           `two migrations cannot share an apply-order slot. Renumber the newer one to the next ` +
           `free prefix (check origin/main, not your branch point).`,
       );
     }
   }
 
+  return errors;
+}
+
+function main(): void {
+  const files = readdirSync(MIGRATIONS_DIR)
+    .filter((f) => f.endsWith(".sql"))
+    .sort();
+
+  const errors: string[] = collisionErrorsFromFiles(files);
+
   const immutabilityChecked = checkImmutability(errors);
 
   if (errors.length > 0) {

package/test/derivation-parity/README.md

@@ -26,7 +26,7 @@ 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) |
+| `retro`            | 1 / 1               | ✅ green — whole-model parity |
 | `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) |
@@ -34,13 +34,17 @@ behind an upstream construct, and do **not** relax to node-surface parity_:
 | `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).
+`retro` is a green whole-model parity port — a single-start/single-end agent
+pipeline (gather → conformance → record-conformance) with a `deviations?`
+conformance-escalation subgraph (#355/#356) and a shared synthesize → record
+tail. Its `record-conformance-ack` service task carries a general
+`<zeebe:ioMapping>` that the stock `task` builder could not emit until
+`@nanobpm/workflow@0.13.0` landed the general service-task `io` construct
+(nano-ide#405); every other element was always expressible (`w.task`+prompt,
+`w.branch`, `w.human`, envelopes). The remaining six goldens are parked across
+**two** distinct blocker classes, each awaiting an upstream `@nanobpm/workflow`
+(nano-ide) construct + re-release (never a golden edit, never relaxed
+acceptance).
 
 ## The blockers
 
@@ -83,24 +87,6 @@ pinned by a diagnostic in `derivation-parity.test.ts`:
 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
@@ -108,8 +94,11 @@ The follow-up upstream slices (opened in **nanobpm/nano-ide** per decision path
 
 - 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).
+  `convergence-loop`).
+
+(The class-3 general service-task `io` mapping has already landed —
+`@nanobpm/workflow@0.13.0`, nano-ide#405 — unparking `retro` to whole-model
+parity.)
 
 Then, on a resumed run here:
 
@@ -121,3 +110,28 @@ Then, on a resumed run here:
 
 No golden `.bpmn` file may be edited to force a match — the derivation must
 reproduce the checked-in golden.
+
+## CI regression guard (S6, nano-ide#321)
+
+The unit suite above (run under `npm test`) does the DERIVE + structural DIFF for
+every ported model. The **final regression guard** adds the third leg — DEPLOY —
+and wires the whole corpus into CI as its own job:
+
+    npm run check:derivation-parity        # scripts/check-derivation-parity.ts
+
+For every model it derives the BPMN from its `defineFlow` port, structurally
+diffs it against the checked-in golden via the **same** S0 harness
+(`normalize` / `assertDerivationParity` — never reimplemented), and **deploys the
+derived model to the in-process `@nanobpm/engine-wasm` engine**
+(`@nanobpm/urban-testkit`), asserting the engine accepts it. Any structural drift
+**or** deploy rejection fails the build. Parked models must each carry a
+documented `blockedReason`, so the corpus can never silently lose coverage; a
+parked model flips into the full derive → diff → deploy loop automatically the
+moment its `flow` lands — no change to the gate.
+
+Because most of the corpus is (currently) parked, the gate runs a **self-proving
+canary** first: it proves a faithful derivation deploys and diffs green, a
+drifted derivation is caught by the diff, and a corrupted model is rejected by
+the engine — so the oracle's red path can never rot into a vacuous green. The
+guard runs on every PR/push as the `derivation-parity` job in
+`.github/workflows/ci.yml`.

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

@@ -85,8 +85,8 @@ test("class-1 blocked goldens genuinely have multiple top-level start/end events
   }
 
   // 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.
+  // class 1; retro is a GREEN whole-model parity port (it runs through
+  // `assertDerivationParity` above), convergence-loop is class-2 blocked (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`);
@@ -94,37 +94,6 @@ test("class-1 blocked goldens genuinely have multiple top-level start/end events
   }
 });
 
-// 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.

package/test/derivation-parity/flows.ts

@@ -9,12 +9,13 @@
 // 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:
+//   • `retro` is a GREEN whole-model parity port (see below). The remaining six
+//     goldens are `blockedReason`-parked, in TWO 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
+//         merge-loop, plan-fanout). `@nanobpm/workflow` 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
@@ -34,23 +35,10 @@
 //         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.
+// upstream construct lands and `@nanobpm/workflow` is bumped to carry it.
 
-import type { DeclarativeFlow } from "@nanobpm/workflow";
+import { type DeclarativeFlow, defineFlow, envelope } 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
@@ -72,38 +60,87 @@ export type PortEntry =
       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
+// ── retro (GREEN — whole-model parity) ───────────────────────────────────────
+// retro is a single-start/single-end model: a linear gather → conformance →
+// record-conformance agent pipeline, a `deviations?` exclusive gateway guarding a
+// conformance-escalation subgraph (nano-workforce #355/#356), then a shared
+// synthesize → record tail. Every element ports with the stock builder:
+// `w.task`+envelopes for the data-envelope service tasks, `w.task`+prompt for the
+// two agent tasks (`senior:conformance`, `senior:retro`), `w.branch` for the
+// `deviations?` gateway, `w.human` for the `conformance-escalation` userTask, and
+// — since @nanobpm/workflow@0.13.0 landed the general service-task `io` construct
+// (nano-ide#405) — `w.task`+`io` for `record-conformance-ack`'s 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.
+// `=if (is defined(note)) then note else null`→note).
+
+/** The typed data envelopes retro's non-agent service tasks lift into the model
+ *  (`nano:shape` + `io.nanobpm.dataEnvelope.in`), matching the golden's shapes. */
+const RetroGatherIn = envelope("RetroGatherIn", { planKey: "string" });
+const RetroRecordIn = envelope("RetroRecordIn", {
+  planKey: "string",
+  retroLearnings: { type: "integer", optional: true },
+  status: { type: "string", optional: true },
+  pr: { type: "string", optional: true },
+  summary: { type: "string", optional: true },
+});
+const ConformanceRecordIn = envelope("ConformanceRecordIn", {
+  planKey: "string",
+  status: { type: "string", optional: true },
+  commentUrl: { type: "string", optional: true },
+  slicesMet: { type: "integer", optional: true },
+  slicesReduced: { type: "integer", optional: true },
+  slicesNotVerified: { type: "integer", optional: true },
+  deviationsRaised: { type: "integer", optional: true },
+  deviationsUnraised: { type: "integer", optional: true },
+  hasDeviations: { type: "boolean", optional: true },
+  summary: { type: "string", optional: true },
+});
 
-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 code-first port of `resources/processes/retro.bpmn`. */
+const retroFlow: DeclarativeFlow = defineFlow(
+  "retro",
+  {
+    gather: { in: RetroGatherIn },
+    "record-conformance": { in: ConformanceRecordIn },
+    record: { in: RetroRecordIn },
+  },
+  (w) => {
+    w.task("gather", { jobType: "pr.retro-gather" });
+    w.task("conformance", {
+      jobType: "senior:conformance",
+      prompt: { resourceId: "conformance.md", bindingType: "latest", append: "=conformanceDigest" },
+    });
+    w.task("record-conformance", { jobType: "pr.conformance-record" });
+    w.branch("hasDeviations = true", {
+      then: (b) => {
+        b.human("conformance-escalation", {
+          form: "conformance-escalation",
+          candidateGroups: "operators",
+        });
+        b.task("record-conformance-ack", {
+          jobType: "pr.conformance-ack",
+          io: {
+            input: [
+              { source: "=planKey", target: "planKey" },
+              { source: "=if (is defined(note)) then note else null", target: "note" },
+            ],
+          },
+        });
+      },
+    });
+    w.task("synthesize", {
+      jobType: "senior:retro",
+      prompt: { resourceId: "retro.md", bindingType: "latest", append: "=retroDigest" },
+    });
+    w.task("record", { jobType: "pr.retro-record" });
+  },
+);
 
 /** 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 " +
+  "blocked: the published @nanobpm/workflow compiler 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) " +
@@ -111,7 +148,7 @@ const MULTI_START_END_BLOCK =
 
 /** 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: "retro", flow: retroFlow },
   {
     model: "spine-demo",
     blockedReason: `${MULTI_START_END_BLOCK} (spine-demo: 1 start, 2 ends)`,
@@ -128,7 +165,7 @@ export const PORTS: readonly PortEntry[] = [
     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 " +
+      "its topology is not expressible with the published @nanobpm/workflow'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 " +