@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.
- package/.github/workflows/ci.yml +33 -0
- package/.github/workflows/invariants.yml +72 -0
- package/AGENTS.md +7 -1
- package/CHANGELOG.md +7 -0
- package/package.json +3 -1
- package/scripts/check-derivation-parity.ts +213 -0
- package/scripts/check-migrations.test.ts +39 -1
- package/scripts/check-migrations.ts +18 -6
- package/test/derivation-parity/README.md +25 -0
package/.github/workflows/ci.yml
CHANGED
|
@@ -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.
|
|
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
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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`.
|