@nanobpm/nano-workforce 0.107.1 → 0.107.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,6 +5,12 @@ on:
5
5
  branches: [main]
6
6
  push:
7
7
  branches: [main]
8
+ # Merge-skew guard (issue #366): also run the required gates against the merge queue's
9
+ # PROSPECTIVE merged commit (GitHub Actions `merge_group` event). Several gates assert a whole-repo invariant (migration prefixes,
10
+ # BPMN DI freshness, committed generated artifacts) that two PRs can each satisfy in isolation yet
11
+ # violate once BOTH land on `main`. Validating the speculative merge commit the queue builds — not
12
+ # the stale PR head — blocks such a merge categorically instead of letting it poison the next PR.
13
+ merge_group:
8
14
 
9
15
  permissions:
10
16
  contents: read
@@ -77,3 +83,30 @@ jobs:
77
83
  - name: E2E (urban-testkit)
78
84
  run: npm run e2e
79
85
 
86
+ # FINAL regression guard for epic nano-ide#314 (S6, #321): the compounding oracle that keeps the
87
+ # code-first (`defineFlow`) and model-first (`.bpmn`) representations of the nano-workforce corpus
88
+ # in lockstep. For every model it DERIVES the BPMN from its defineFlow port, structurally DIFFS it
89
+ # against the checked-in golden via the S0 harness (@nanobpm/workflow/test-support), and DEPLOYS
90
+ # the derived model to the in-process @nanobpm/engine-wasm engine — failing on any structural drift
91
+ # OR deploy rejection. Parked models (awaiting an upstream construct) must each carry a documented
92
+ # blocker, and a self-proving canary asserts the oracle's red path genuinely fires so the gate can
93
+ # never rot into a vacuous green while the corpus is parked. Hermetic (in-process wasm engine, no
94
+ # sockets), so it runs on every PR/push as its own job.
95
+ derivation-parity:
96
+ name: derivation parity (nwf corpus regression guard)
97
+ runs-on: ubuntu-latest
98
+ steps:
99
+ - name: Checkout
100
+ uses: actions/checkout@v4
101
+
102
+ - name: Setup Node.js
103
+ uses: actions/setup-node@v4
104
+ with:
105
+ node-version: "24"
106
+
107
+ - name: Install dependencies
108
+ run: npm ci
109
+
110
+ - name: Derive + diff + deploy the full nwf corpus
111
+ run: npm run check:derivation-parity
112
+
@@ -0,0 +1,72 @@
1
+ name: Whole-repo invariants (merge-skew guard)
2
+
3
+ # Closes the merge-skew failure class (issue #366).
4
+ #
5
+ # Several gates assert a GLOBAL invariant / checked-in DERIVED artifact — `derived == f(sources)` —
6
+ # but the main CI only ever verifies them against a PR's OWN head. Two PRs can each pass in isolation
7
+ # and still break the invariant once BOTH squash-merge, because `main`'s `derived` is then
8
+ # `f(sources_A ∪ sources_B)`, which neither branch's green CI ever saw (the 052 migration collision,
9
+ # #359; the stale `retro.bpmn` DI, #365). Nothing re-checked `main`, so the breakage landed silently
10
+ # and poisoned the next unrelated PR to touch the same job.
11
+ #
12
+ # This lean workflow re-asserts those whole-repo invariants where the merge actually happens:
13
+ # - `merge_group` — the queue's PROSPECTIVE merged commit, so a skew is blocked BEFORE it lands.
14
+ # - `push: [main]` — a fast backstop that fails a `main`-scoped build within minutes if something
15
+ # slipped through, instead of first surfacing on an unrelated open PR.
16
+ # - `schedule` — a daily catch-all for any skew introduced by a merge that bypassed the queue.
17
+ on:
18
+ merge_group:
19
+ push:
20
+ branches: [main]
21
+ schedule:
22
+ # 06:00 UTC daily — cheap catch-all backstop.
23
+ - cron: "0 6 * * *"
24
+ workflow_dispatch:
25
+
26
+ permissions:
27
+ contents: read
28
+
29
+ jobs:
30
+ invariants:
31
+ name: whole-repo invariants
32
+ runs-on: ubuntu-latest
33
+ steps:
34
+ - name: Checkout
35
+ uses: actions/checkout@v4
36
+ with:
37
+ # Full history: the migration immutability gate diffs against the merge-base with
38
+ # origin/main, and the layout gate needs the whole tree — neither works on a shallow clone.
39
+ fetch-depth: 0
40
+
41
+ - name: Setup Node.js
42
+ uses: actions/setup-node@v4
43
+ with:
44
+ node-version: "24"
45
+
46
+ - name: Install dependencies
47
+ run: npm ci
48
+
49
+ # Prefix-collision (+ immutability): two branches that each took "the next" free migration
50
+ # prefix collide once merged. Re-run on the merged/`main` tree so the collision can't hide.
51
+ - name: Check migration prefixes (no collisions)
52
+ run: npm run check:migrations
53
+
54
+ # BPMN DI freshness: a merged semantic model can carry flows whose DI was regenerated on neither
55
+ # branch. Regenerate the DI over the merged model and fail if any committed diagram is stale.
56
+ - name: Check BPMN diagram freshness (layout)
57
+ run: npm run layout:check
58
+
59
+ # Generated-artifact freshness (`urban gen --check`): landscape.gen.html, JSON Schemas / OpenAPI,
60
+ # the processos grammar (ir.gbnf) and friends are `derived == f(sources)` — re-derive over the
61
+ # merged sources and fail if a committed artifact drifted.
62
+ - name: Check generated artifacts (urban gen --check)
63
+ run: npm run gen:check
64
+
65
+ # Navigation index is another checked-in derived artifact; re-assert it on the merged tree too.
66
+ - name: Check navigation index freshness
67
+ run: npm run sync:nav:check
68
+
69
+ # Backstop: catch ANY other committed generated file that the merged sources render stale, even
70
+ # one without its own `--check` script above. A clean tree is the whole-repo invariant.
71
+ - name: No stale committed artifacts on the merged tree
72
+ run: git diff --exit-code
package/AGENTS.md CHANGED
@@ -272,7 +272,13 @@ Migrations live in `db/migrations/*.sql` and are **auto-applied on boot** from
272
272
  Check `origin/main`, not your branch point — a fan-out epic branch forks at one
273
273
  prefix while `main` keeps advancing, so the branch-local "next" number collides
274
274
  on merge. Two files must never share a prefix; `npm run check:migrations`
275
- (a CI gate) enforces this and fails the build on any new duplicate.
275
+ (a CI gate) enforces this and fails the build on any new duplicate. Because a
276
+ prefix collision only exists in the *union* of two branches, this gate — like
277
+ `layout:check` and the generated-artifact `--check`s — is also re-run on the
278
+ merge queue's **prospective merged commit** and on **push to `main`** by
279
+ `.github/workflows/invariants.yml` (issue #366), so a merge-skew collision is
280
+ blocked at merge time or fails a `main`-scoped build within minutes rather than
281
+ first surfacing on an unrelated open PR.
276
282
  - **A merged migration is IMMUTABLE — never rename, delete, or edit it.** The
277
283
  runtime keys the `_urban_migrations` ledger by *filename*, so a renamed file is
278
284
  a *new* migration to the runner: it re-runs its DDL against an already-migrated
package/CHANGELOG.md CHANGED
@@ -1,3 +1,10 @@
1
+ ## [0.107.2](https://github.com/nanobpm/nano-workforce/compare/v0.107.1...v0.107.2) (2026-08-20)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * **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)
7
+
1
8
  ## [0.107.1](https://github.com/nanobpm/nano-workforce/compare/v0.107.0...v0.107.1) (2026-08-20)
2
9
 
3
10
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nanobpm/nano-workforce",
3
- "version": "0.107.1",
3
+ "version": "0.107.2",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "main": "main.ts",
@@ -41,6 +41,8 @@
41
41
  "heal:migrations": "node --experimental-strip-types scripts/heal-migration-ledger.ts",
42
42
  "check:contracts": "node --experimental-strip-types scripts/check-contracts.ts",
43
43
  "reconcile:contracts": "node --experimental-strip-types scripts/reconcile-contracts.ts",
44
+ "precheck:derivation-parity": "urban gen",
45
+ "check:derivation-parity": "node --experimental-strip-types scripts/check-derivation-parity.ts",
44
46
  "gen": "urban gen",
45
47
  "gen:check": "urban gen --check",
46
48
  "layout": "node --experimental-strip-types scripts/layout-bpmn.ts",
@@ -0,0 +1,213 @@
1
+ // check-derivation-parity — the FINAL regression guard for epic nanobpm/nano-ide#314 (S6, #321).
2
+ //
3
+ // This is the compounding oracle that keeps the code-first (`defineFlow`) and model-first (`.bpmn`)
4
+ // representations of the nano-workforce corpus in lockstep. For EVERY golden under
5
+ // `resources/processes/*.bpmn` it runs the full derive → diff → deploy loop:
6
+ //
7
+ // (a) DERIVE — take the golden's `defineFlow` port (test/derivation-parity/flows.ts) and derive
8
+ // its BPMN with `@nanobpm/workflow`.
9
+ // (b) DIFF — structurally compare the derived model against the checked-in golden using the S0
10
+ // parity harness (`@nanobpm/workflow/test-support`'s `normalize` / `assertDerivation-
11
+ // Parity`). The normalization/diff is NEVER reimplemented here — this gate only calls
12
+ // the shared harness, so the code-first check can't drift from the unit suite's.
13
+ // (c) DEPLOY — deploy the derived model to the in-process `@nanobpm/engine-wasm` engine (via
14
+ // `@nanobpm/urban-testkit`) and assert the engine ACCEPTS it.
15
+ //
16
+ // Any structural drift (b) OR deploy rejection (c) fails the build.
17
+ //
18
+ // PARKED MODELS ARE ACCOUNTED FOR, NOT IGNORED. The corpus is currently fully parked behind
19
+ // upstream `@nanobpm/workflow` constructs (see test/derivation-parity/flows.ts for the three blocker
20
+ // classes). Each parked model must carry a documented `blockedReason`; a model that is neither
21
+ // ported nor documented fails this gate, so the corpus can never silently lose coverage. As each
22
+ // parked model flips to a real `flow` upstream, it is automatically pulled into the full
23
+ // derive → diff → deploy loop here with NO change to this script.
24
+ //
25
+ // SELF-PROVING CANARY. Because the corpus is (today) all-parked, a gate that merely iterated it
26
+ // would be a vacuous green — it could rot without anyone noticing. So before touching the corpus we
27
+ // run a CANARY that proves the oracle's RED path genuinely fires: a faithful derived flow deploys
28
+ // green and diffs green, a drifted derivation is CAUGHT by the diff, and a corrupted model is
29
+ // REJECTED by the engine. If any red path fails to fire (the diff misses drift, or the engine
30
+ // accepts garbage), the gate fails — the oracle must be able to say no.
31
+
32
+ import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
33
+ import { tmpdir } from "node:os";
34
+ import { dirname, join } from "node:path";
35
+ import { fileURLToPath } from "node:url";
36
+ import { createWasmEngineClient } from "@nanobpm/urban-testkit";
37
+ import type { DeclarativeFlow } from "@nanobpm/workflow";
38
+ import { declarativeToBpmn, defineFlow, toDeployableBpmn } from "@nanobpm/workflow";
39
+ import { assertDerivationParity } from "@nanobpm/workflow/test-support";
40
+ import { PORTS } from "../test/derivation-parity/flows.ts";
41
+
42
+ const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
43
+ const PROCESSES_DIR = join(REPO_ROOT, "resources", "processes");
44
+ const goldenPath = (model: string): string => join(PROCESSES_DIR, `${model}.bpmn`);
45
+
46
+ type WasmEngine = Awaited<ReturnType<typeof createWasmEngineClient>>;
47
+
48
+ const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
49
+
50
+ /** Deploy a derived flow's *deployable* BPMN (semantic model + auto-layout DI) to the wasm engine
51
+ * and assert acceptance. Throws when the engine rejects the model or reports nothing deployed. */
52
+ async function deployDerived(engine: WasmEngine, id: string, flow: DeclarativeFlow): Promise<void> {
53
+ const xml = await toDeployableBpmn(flow);
54
+ const result = await engine.deployResources([{ name: `${id}.bpmn`, content: xml, contentType: "application/xml" }]);
55
+ if (!result || result.deployed < 1) {
56
+ throw new Error(`engine did not accept derived "${id}" (deployed=${result?.deployed ?? 0})`);
57
+ }
58
+ }
59
+
60
+ /** Prove the derive → diff → deploy oracle can actually say NO, so an all-parked corpus can't let
61
+ * this gate rot into a vacuous green. Pushes a line onto `errors` for any red path that fails to
62
+ * fire. */
63
+ async function proveOracleFiresRed(engine: WasmEngine, errors: string[]): Promise<void> {
64
+ const dir = mkdtempSync(join(tmpdir(), "nwf-parity-canary-"));
65
+ try {
66
+ const canary = defineFlow("parity-canary", (w) => {
67
+ w.task("step-a", { jobType: "senior:noop" });
68
+ });
69
+ const golden = join(dir, "parity-canary.bpmn");
70
+ writeFileSync(golden, declarativeToBpmn(canary), "utf8");
71
+
72
+ // DIFF, green: a faithful derivation matches its own golden.
73
+ try {
74
+ assertDerivationParity(canary, golden);
75
+ } catch (e) {
76
+ errors.push(` canary: a faithful derivation was reported as drift — the diff is broken (${errMsg(e)})`);
77
+ }
78
+
79
+ // DIFF, red: a structurally different derivation MUST be caught.
80
+ const drifted = defineFlow("parity-canary", (w) => {
81
+ w.task("step-a", { jobType: "senior:noop" });
82
+ w.task("step-b", { jobType: "senior:noop" });
83
+ });
84
+ let structuralFired = false;
85
+ try {
86
+ assertDerivationParity(drifted, golden);
87
+ } catch {
88
+ structuralFired = true;
89
+ }
90
+ if (!structuralFired) {
91
+ errors.push(" canary: the structural-drift oracle did NOT fire (an added node slipped past the diff)");
92
+ }
93
+
94
+ // DEPLOY, green: a valid derived model is accepted by the engine.
95
+ try {
96
+ await deployDerived(engine, "parity-canary", canary);
97
+ } catch (e) {
98
+ errors.push(` canary: the engine rejected a VALID derived model — the deploy oracle is broken (${errMsg(e)})`);
99
+ }
100
+
101
+ // DEPLOY, red: a corrupted model MUST be rejected.
102
+ let deployFired = false;
103
+ try {
104
+ await engine.deployResources([{ name: "corrupt.bpmn", content: "<not-bpmn/>", contentType: "application/xml" }]);
105
+ } catch {
106
+ deployFired = true;
107
+ }
108
+ if (!deployFired) {
109
+ errors.push(" canary: the deploy-rejection oracle did NOT fire (the engine accepted invalid BPMN)");
110
+ }
111
+ } finally {
112
+ rmSync(dir, { recursive: true, force: true });
113
+ }
114
+ }
115
+
116
+ /** Assert PORTS covers EXACTLY the checked-in goldens under
117
+ * `resources/processes/*.bpmn`. Without this the guard's "full corpus" claim is
118
+ * unproven: a newly-added golden with no PORTS entry would be silently skipped
119
+ * (eroding coverage while still reporting OK), and a stale PORTS entry for a
120
+ * deleted golden would iterate a model that no longer exists. Both directions
121
+ * fail the gate. */
122
+ function assertPortsCoverGoldens(errors: string[]): void {
123
+ const goldens = readdirSync(PROCESSES_DIR)
124
+ .filter((f) => f.endsWith(".bpmn"))
125
+ .map((f) => f.slice(0, -".bpmn".length));
126
+ const ported = PORTS.map((p) => p.model);
127
+
128
+ const missing = goldens.filter((g) => !ported.includes(g)).sort();
129
+ if (missing.length > 0) {
130
+ errors.push(
131
+ ` PORTS is missing ${missing.length} checked-in golden(s) under resources/processes ` +
132
+ `(${missing.join(", ")}) — add a derived flow or a documented blockedReason so the ` +
133
+ `"full corpus" guard can't silently skip them.`,
134
+ );
135
+ }
136
+
137
+ const orphaned = ported.filter((m) => !goldens.includes(m)).sort();
138
+ if (orphaned.length > 0) {
139
+ errors.push(
140
+ ` PORTS references ${orphaned.length} model(s) with no golden under resources/processes ` +
141
+ `(${orphaned.join(", ")}) — remove the stale entry or restore its golden.`,
142
+ );
143
+ }
144
+
145
+ const seen = new Set<string>();
146
+ const duplicated = new Set<string>();
147
+ for (const m of ported) {
148
+ if (seen.has(m)) duplicated.add(m);
149
+ seen.add(m);
150
+ }
151
+ if (duplicated.size > 0) {
152
+ errors.push(
153
+ ` PORTS has duplicate entries for ${duplicated.size} model(s) (${[...duplicated].sort().join(", ")}) — ` +
154
+ `each golden must appear exactly once.`,
155
+ );
156
+ }
157
+ }
158
+
159
+ async function main(): Promise<void> {
160
+ const errors: string[] = [];
161
+ const engine = await createWasmEngineClient();
162
+
163
+ let ported = 0;
164
+ let deployed = 0;
165
+ let parked = 0;
166
+
167
+ try {
168
+ assertPortsCoverGoldens(errors);
169
+ await proveOracleFiresRed(engine, errors);
170
+
171
+ for (const port of PORTS) {
172
+ if (port.flow) {
173
+ ported++;
174
+ const golden = goldenPath(port.model);
175
+ try {
176
+ assertDerivationParity(port.flow, golden);
177
+ } catch (e) {
178
+ errors.push(` ${port.model}: STRUCTURAL DRIFT vs golden — ${errMsg(e)}`);
179
+ continue; // a model that doesn't derive its golden can't be trusted to deploy meaningfully
180
+ }
181
+ try {
182
+ await deployDerived(engine, port.model, port.flow);
183
+ deployed++;
184
+ } catch (e) {
185
+ errors.push(` ${port.model}: DEPLOY REJECTED by wasm engine — ${errMsg(e)}`);
186
+ }
187
+ } else {
188
+ parked++;
189
+ if (!port.blockedReason || port.blockedReason.trim().length === 0) {
190
+ errors.push(
191
+ ` ${port.model}: neither ported (no flow) nor documented (no blockedReason) — every ` +
192
+ `corpus model must derive its golden or carry a precise blocker.`,
193
+ );
194
+ }
195
+ }
196
+ }
197
+ } finally {
198
+ // Release the underlying WASM engine resources so repeated runs (local / CI matrix) don't leak.
199
+ await engine.close();
200
+ }
201
+
202
+ if (errors.length > 0) {
203
+ console.error(`check-derivation-parity: the nano-workforce corpus failed its derivation-parity guard:\n${errors.join("\n")}`);
204
+ process.exit(1);
205
+ }
206
+
207
+ console.log(
208
+ `check-derivation-parity: OK (${PORTS.length} corpus models — ${ported} ported ` +
209
+ `[${deployed} deploy-accepted by the wasm engine], ${parked} documented-parked; oracle red paths verified).`,
210
+ );
211
+ }
212
+
213
+ if (import.meta.main) main();
@@ -6,7 +6,7 @@
6
6
  // with origin/main; here we drive its diff classifier directly with representative
7
7
  // `git diff --find-renames --name-status` output so each violation shape is pinned.
8
8
  import test from "node:test";
9
- import { immutabilityErrorsFromDiff } from "./check-migrations.ts";
9
+ import { collisionErrorsFromFiles, immutabilityErrorsFromDiff } from "./check-migrations.ts";
10
10
  import { assert, assertEquals } from "#test-assert";
11
11
 
12
12
  test("a rename of a merged migration is a violation", () => {
@@ -56,3 +56,41 @@ test("mixed changes report every violation but ignore the addition", () => {
56
56
  assert(errors.some((e) => /DELETED/.test(e)));
57
57
  assert(errors.some((e) => /RENAMED/.test(e)));
58
58
  });
59
+
60
+ // Merge-skew regression coverage (issue #366).
61
+ //
62
+ // The failure class this pins: two PRs each pass `check:migrations` on their OWN head, but their
63
+ // COMBINATION on `main` after both squash-merge violates the prefix-collision invariant — because
64
+ // neither branch's green CI ever saw the other's file. The 052 collision (#351 + #355, hotfixed in
65
+ // #359) was exactly this. Driving the pure collision detector with each branch's tree AND their union
66
+ // demonstrates that only the post-merge state trips the gate, which is why the gate must re-run on
67
+ // the prospective merged commit (merge_group) / on push to `main`, not just PR heads.
68
+ test("merge skew: two individually-clean branches whose union collides IS caught", () => {
69
+ const mainTree = ["050_capability_gates.sql", "051_merges_per_day.sql"];
70
+ // Each branch independently picks the same "next free" prefix (060) without seeing its sibling.
71
+ const branchA = [...mainTree, "060_plan_conformance.sql"];
72
+ const branchB = [...mainTree, "060_worker_durable_resume.sql"];
73
+
74
+ // On its own head, each branch is clean — this is why both PRs go green in isolation.
75
+ assertEquals(collisionErrorsFromFiles(branchA), [], "branch A alone has no colliding prefix");
76
+ assertEquals(collisionErrorsFromFiles(branchB), [], "branch B alone has no colliding prefix");
77
+
78
+ // The post-merge tree on `main` (git merges both files cleanly — the names don't textually
79
+ // conflict) now shares slot 060. The gate, re-run on that merged state, catches it.
80
+ const mergedOnMain = [...new Set([...branchA, ...branchB])].sort();
81
+ const errors = collisionErrorsFromFiles(mergedOnMain);
82
+ assertEquals(errors.length, 1, "the merged tree has exactly one colliding prefix");
83
+ assert(/prefix 060/.test(errors[0]));
84
+ assert(/060_plan_conformance.sql/.test(errors[0]));
85
+ assert(/060_worker_durable_resume.sql/.test(errors[0]));
86
+ });
87
+
88
+ test("collision detector flags a non-NNN shape and grandfathers historical dupes", () => {
89
+ assert(collisionErrorsFromFiles(["nope.sql"]).some((e) => /required NNN_name.sql shape/.test(e)));
90
+ // Grandfathered historical collisions (already applied forward-only) must stay exempt.
91
+ assertEquals(
92
+ collisionErrorsFromFiles(["052_plan_conformance.sql", "052_worker_durable_resume.sql"]),
93
+ [],
94
+ "grandfathered prefix 052 is not a new violation",
95
+ );
96
+ });
@@ -150,11 +150,13 @@ function checkImmutability(errors: string[]): boolean {
150
150
  return true;
151
151
  }
152
152
 
153
- function main(): void {
154
- const files = readdirSync(MIGRATIONS_DIR)
155
- .filter((f) => f.endsWith(".sql"))
156
- .sort();
157
-
153
+ /** Classify a migration file listing into shape + prefix-collision errors. Pure over the file list
154
+ * so the MERGE-SKEW scenario can be pinned in a test: two individually-clean branches each pass this
155
+ * over their OWN tree, but the gate must fail over the UNION that lands on `main` after both merge
156
+ * (issue #366). This is exactly why the gate has to re-run on the post-merge state — neither branch's
157
+ * green CI ever saw the other's prefix. Grandfathered historical collisions stay exempt. Exported
158
+ * for unit coverage. */
159
+ export function collisionErrorsFromFiles(files: readonly string[]): string[] {
158
160
  const errors: string[] = [];
159
161
  const byPrefix = new Map<string, string[]>();
160
162
 
@@ -175,13 +177,23 @@ function main(): void {
175
177
  for (const [prefix, group] of byPrefix) {
176
178
  if (group.length > 1 && !GRANDFATHERED_DUPES.has(prefix)) {
177
179
  errors.push(
178
- ` prefix ${prefix} is used by ${group.length} files: ${group.join(", ")} — ` +
180
+ ` prefix ${prefix} is used by ${group.length} files: ${[...group].sort().join(", ")} — ` +
179
181
  `two migrations cannot share an apply-order slot. Renumber the newer one to the next ` +
180
182
  `free prefix (check origin/main, not your branch point).`,
181
183
  );
182
184
  }
183
185
  }
184
186
 
187
+ return errors;
188
+ }
189
+
190
+ function main(): void {
191
+ const files = readdirSync(MIGRATIONS_DIR)
192
+ .filter((f) => f.endsWith(".sql"))
193
+ .sort();
194
+
195
+ const errors: string[] = collisionErrorsFromFiles(files);
196
+
185
197
  const immutabilityChecked = checkImmutability(errors);
186
198
 
187
199
  if (errors.length > 0) {
@@ -121,3 +121,28 @@ Then, on a resumed run here:
121
121
 
122
122
  No golden `.bpmn` file may be edited to force a match — the derivation must
123
123
  reproduce the checked-in golden.
124
+
125
+ ## CI regression guard (S6, nano-ide#321)
126
+
127
+ The unit suite above (run under `npm test`) does the DERIVE + structural DIFF for
128
+ every ported model. The **final regression guard** adds the third leg — DEPLOY —
129
+ and wires the whole corpus into CI as its own job:
130
+
131
+ npm run check:derivation-parity # scripts/check-derivation-parity.ts
132
+
133
+ For every model it derives the BPMN from its `defineFlow` port, structurally
134
+ diffs it against the checked-in golden via the **same** S0 harness
135
+ (`normalize` / `assertDerivationParity` — never reimplemented), and **deploys the
136
+ derived model to the in-process `@nanobpm/engine-wasm` engine**
137
+ (`@nanobpm/urban-testkit`), asserting the engine accepts it. Any structural drift
138
+ **or** deploy rejection fails the build. Parked models must each carry a
139
+ documented `blockedReason`, so the corpus can never silently lose coverage; a
140
+ parked model flips into the full derive → diff → deploy loop automatically the
141
+ moment its `flow` lands — no change to the gate.
142
+
143
+ Because the corpus is (currently) fully parked, the gate runs a **self-proving
144
+ canary** first: it proves a faithful derivation deploys and diffs green, a
145
+ drifted derivation is caught by the diff, and a corrupted model is rejected by
146
+ the engine — so the oracle's red path can never rot into a vacuous green. The
147
+ guard runs on every PR/push as the `derivation-parity` job in
148
+ `.github/workflows/ci.yml`.