cool-workflow 0.2.5 → 0.2.6

package/scripts/gen-manifests.js

@@ -110,82 +110,47 @@ function _resolveTemplate(template, src, pluginRootVar) {
 
 function build(src) {
   const { targets, vendors } = src;
-  // Backward compat: if no `vendors` key, build from legacy targets
-  if (!vendors || typeof vendors !== "object" || Object.keys(vendors).length === 0) {
-    return buildLegacy(src);
-  }
+  validateVendorRegistry(vendors);
   const outputs = [];
   for (const [vendorId, vendorDef] of Object.entries(vendors)) {
     const targetConfig = targets && targets[vendorId] ? targets[vendorId] : {};
     const pluginRootVar = targetConfig.pluginRootVar || "./";
-    const vendorOutputs = vendorDef.outputs || [];
+    const vendorOutputs = vendorDef.outputs;
     for (const output of vendorOutputs) {
       const resolved = _resolveTemplate(output, src, pluginRootVar);
+      if (!isPlainObject(resolved) || typeof resolved.path !== "string" || !resolved.path.trim()) {
+        throw new Error(`vendor ${vendorId} has an output without a path`);
+      }
+      if (!isPlainObject(resolved.json)) {
+        throw new Error(`vendor ${vendorId} output ${resolved.path} has no JSON object`);
+      }
       outputs.push({
-        path: typeof resolved.path === "string" ? resolved.path : `vendor-${vendorId}-${outputs.length}`,
-        json: resolved.json || {}
+        path: resolved.path,
+        json: resolved.json
       });
     }
   }
   return outputs;
 }
 
-/** Legacy path: build from hardcoded shapes (backward compat if no `vendors` key). */
-function buildLegacy(src) {
-  const { identity, descriptions, interface: ui, layout, mcp, targets } = src;
-  const outputs = [];
-
-  if (targets && targets.claude) {
-    outputs.push({
-      path: targets.claude.marketplace,
-      json: { name: identity.name, owner: identity.author, metadata: { description: descriptions.standard, version: identity.version }, plugins: [{ name: identity.name, source: layout.pluginPathFromRepoRoot, description: descriptions.standard, category: ui.category.toLowerCase() }] }
-    });
-    outputs.push({
-      path: targets.claude.plugin,
-      json: { name: identity.name, description: descriptions.standard, version: identity.version, author: identity.author, homepage: identity.homepage, license: identity.license, keywords: identity.keywords }
-    });
-    outputs.push({
-      path: targets.claude.mcp,
-      json: legacyMcpConfig(mcp, layout, targets.claude.pluginRootVar)
-    });
-  }
-  if (targets && targets.codex) {
-    outputs.push({
-      path: targets.codex.marketplace,
-      json: { name: identity.name, interface: { displayName: ui.displayName }, plugins: [{ name: identity.name, source: { source: "local", path: layout.pluginPathFromRepoRoot }, policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" }, category: ui.category }] }
-    });
-    outputs.push({
-      path: targets.codex.plugin,
-      json: { name: identity.name, version: identity.version, description: descriptions.standard, author: identity.author, keywords: identity.keywords, skills: layout.skillsDir, mcpServers: "./.codex-plugin/mcp.json", interface: { displayName: ui.displayName, shortDescription: descriptions.short, longDescription: descriptions.long, developerName: identity.author.name, category: ui.category, capabilities: ui.capabilities, brandColor: ui.brandColor, defaultPrompt: ui.defaultPrompt } }
-    });
-    outputs.push({
-      path: targets.codex.mcp,
-      json: legacyMcpConfig(mcp, layout, targets.codex.pluginRootVar)
-    });
-  }
-  if (targets && targets.agents) {
-    outputs.push({
-      path: targets.agents.plugin,
-      json: { name: identity.name, description: descriptions.standard, version: identity.version, author: identity.author, homepage: identity.homepage, license: identity.license, keywords: identity.keywords, skills: layout.skillsDir, mcpServers: "./.codex-plugin/mcp.json", interface: { displayName: ui.displayName, shortDescription: descriptions.short, longDescription: descriptions.long, developerName: identity.author.name, category: ui.category, capabilities: ui.capabilities, brandColor: ui.brandColor, defaultPrompt: ui.defaultPrompt } }
-    });
-    outputs.push({
-      path: targets.agents.mcp,
-      json: legacyMcpConfig(mcp, layout, targets.agents.pluginRootVar)
-    });
-  }
-
-  return outputs;
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
-function legacyMcpConfig(mcp, layout, pluginRootVar) {
-  return {
-    mcpServers: {
-      [mcp.serverName]: {
-        command: mcp.command,
-        args: [`${pluginRootVar}${layout.mcpServerScript}`]
-      }
+/** The vendor table is required. A broken source must stop before the write
+ *  loop; an old hard-coded shape is not a safe second source of truth. */
+function validateVendorRegistry(vendors) {
+  if (!isPlainObject(vendors) || Object.keys(vendors).length === 0) {
+    throw new Error("manifest source needs a non-empty vendors object");
+  }
+  for (const [vendorId, vendorDef] of Object.entries(vendors)) {
+    if (!isPlainObject(vendorDef) || !Array.isArray(vendorDef.outputs) || vendorDef.outputs.length === 0) {
+      throw new Error(`vendor ${vendorId} needs a non-empty outputs array`);
+    }
+    for (const output of vendorDef.outputs) {
+      if (!isPlainObject(output)) throw new Error(`vendor ${vendorId} has an invalid output`);
     }
-  };
+  }
 }
 
 function serialize(json) {
@@ -229,4 +194,10 @@ function main() {
   }
 }
 
-main();
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`gen-manifests: ${message}\n`);
+  process.exitCode = 1;
+}

package/scripts/golden-path.js

@@ -33,7 +33,7 @@ function main() {
     const appValidation = runJson(["app", "validate", "end-to-end-golden-path"], pluginRoot);
     assert.equal(appValidation.valid, true);
     assert.equal(appValidation.summary.id, "end-to-end-golden-path");
-    assert.equal(appValidation.summary.version, "0.2.5");
+    assert.equal(appValidation.summary.version, "0.2.6");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.2.5 end-to-end golden path."
+        "Prove the deterministic v0.2.6 end-to-end golden path."
       ],
       pluginRoot
     );
@@ -52,7 +52,7 @@ function main() {
 
     let state = readJson(plan.statePath);
     assert.equal(state.workflow.app.id, "end-to-end-golden-path");
-    assert.equal(state.workflow.app.version, "0.2.5");
+    assert.equal(state.workflow.app.version, "0.2.6");
     assert.equal(state.loopStage, "interpret");
 
     const dispatch = runJson(["dispatch", plan.runId, "--limit", "1", "--sandbox", "readonly"], tmp);
@@ -195,7 +195,7 @@ function main() {
     assert.equal(reportPath, plan.reportPath);
     assert.ok(fs.existsSync(reportPath));
     const report = fs.readFileSync(reportPath, "utf8");
-    assert.match(report, /Workflow App: end-to-end-golden-path@0\.2\.5/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.2\.6/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);

package/scripts/parity-check.js

@@ -8,9 +8,9 @@
 //
 // FAIL CLOSED ON DRIFT (BSD discipline, same shape as gen-manifests --check):
 //   1. STATIC parity — the declared capability registry must exactly match the
-//      live MCP tool list (tools/list) and the CLI dispatch tokens parsed from
-//      the built CLI dispatch surface. A tool or command on one surface but not
-//      the other, or not declared in src/capability-registry.ts, is release-blocking.
+//      live MCP tool list (tools/list), every declared CLI path must resolve
+//      through the live dispatcher, and real `cw help` must match the declared
+//      help surface. Any gap is release-blocking.
 //   2. PAYLOAD parity — for every capability declared `payloadIdentical`, the
 //      `cw <cmd> --json` payload must equal the `cw_<tool>` MCP result on a real
 //      bootstrap run (whitespace + generation-moment ISO timestamps aside).
@@ -38,7 +38,6 @@ const node = process.execPath;
 const cli = path.join(pluginRoot, "dist", "cli.js");
 const mcpServer = path.join(pluginRoot, "dist", "mcp-server.js");
 const registry = require(path.join(pluginRoot, "dist", "core", "capability-table.js"));
-const { formatHelp } = require(path.join(pluginRoot, "dist", "core", "format", "help.js"));
 const { loadRunFromCwd, saveCheckpoint } = require(path.join(pluginRoot, "dist", "shell", "run-store.js"));
 const { appendRunNode, createStateNode } = require(path.join(pluginRoot, "dist", "core", "state", "state-node.js"));
 
@@ -71,15 +70,6 @@ function liveMcpTools() {
   return JSON.parse(line).result.tools.map((tool) => tool.name);
 }
 
-function cliDispatchTokens() {
-  // v2 dispatch is table-driven (findCapabilityByCliPath over REGISTRY), not a
-  // switch, so the token set is the union of every CLI capability's accepted
-  // first tokens (cli.caseTokens where an alias set is declared, else cli.path).
-  // The reachability check below then proves each declared path resolves through
-  // the live dispatcher — replacing the old `case "x":` dist source-grep.
-  return [...new Set(registry.cliCapabilities().flatMap((cap) => cap.cli.caseTokens ?? cap.cli.path))];
-}
-
 // Old-build top-level verbs kept in the frozen help "More commands" index line
 // but folded in v2 into subcommands / the shell layer: init->app.init,
 // search->run.search (declaredCliHelpTokens collapses both to app/run), and
@@ -87,8 +77,8 @@ function cliDispatchTokens() {
 // discovery text, not dispatch-parity tokens — exclude them.
 const HELP_INDEX_ONLY_TOKENS = new Set(["init", "search", "update"]);
 
-function cliHelpTokens() {
-  const lines = formatHelp().split(/\r?\n/);
+function cliHelpTokens(helpText) {
+  const lines = helpText.split(/\r?\n/);
   const tokens = new Set();
   for (const line of lines) {
     // Command lines start with exactly 2 spaces; examples are 4-space.
@@ -104,6 +94,29 @@ function cliHelpTokens() {
   return [...tokens].sort();
 }
 
+function liveCliHelpTokens() {
+  const helpText = execFileSync(node, [cli, "help", "--no-color"], {
+    cwd: pluginRoot,
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1" }
+  });
+  return cliHelpTokens(helpText);
+}
+
+/** The CLI dispatcher calls this same lookup. Keep the probe outside the
+ * registry report so the live gate does not compare a token list made from the
+ * registry with another list made from the same registry. */
+function cliReachabilityIssues(table) {
+  const issues = [];
+  for (const cap of table.cliCapabilities()) {
+    const resolved = table.findCapabilityByCliPath(cap.cli.path);
+    if (!resolved || !resolved.cli || typeof resolved.cli.handler !== "function") {
+      issues.push(`${cap.capability}: CLI path ${cap.cli.path.join(" ")} does not resolve through the dispatcher`);
+    }
+  }
+  return issues;
+}
+
 // ---- 2. payload identity ---------------------------------------------------
 // Generation-moment ISO timestamps are presentation metadata, not capability
 // data: the same field carries the wall-clock instant of the render. Neutralize
@@ -907,9 +920,11 @@ async function payloadParity() {
 async function main() {
   const check = process.argv.includes("--check");
   const tools = liveMcpTools();
-  const tokens = cliDispatchTokens();
-  const helpTokens = cliHelpTokens();
-  const report = registry.buildParityReport({ mcpTools: tools, cliTokens: tokens, helpTokens });
+  const helpTokens = liveCliHelpTokens();
+  const report = registry.buildParityReport({ mcpTools: tools, helpTokens });
+  const reachabilityIssues = cliReachabilityIssues(registry);
+  report.registryLint.push(...reachabilityIssues);
+  report.ok = report.ok && reachabilityIssues.length === 0;
   const payload = await payloadParity();
 
   const ok = report.ok && payload.mismatches.length === 0;
@@ -940,13 +955,17 @@ async function main() {
     if (report.payloadProbeInvalidClassifications.length) lines.push(`  - payload probe classifications for invalid capabilities: ${report.payloadProbeInvalidClassifications.join(", ")}`);
     if (report.registryLint.length) lines.push(`  - registry lint: ${report.registryLint.join("; ")}`);
     if (payload.mismatches.length) lines.push(`  - cw --json != cw_<tool> payload for: ${payload.mismatches.join(", ")}`);
-    lines.push("Reconcile src/capability-registry.ts, cli.ts, and mcp-server.ts so both surfaces render one data source.\n");
+    lines.push("Reconcile src/wiring/capability-table, src/cli, and src/mcp so both surfaces render one data source.\n");
     process.stderr.write(lines.join("\n"));
     process.exitCode = 1;
   }
 }
 
-main().catch((error) => {
-  process.stderr.write(`parity-check: ${error instanceof Error ? error.message : String(error)}\n`);
-  process.exitCode = 1;
-});
+module.exports = { cliHelpTokens, cliReachabilityIssues };
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`parity-check: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/purity-baseline.json

@@ -1,8 +1,5 @@
 {
   "builtinViolations": {
-    "core/state/run-paths.ts": [
-      "node:fs"
-    ],
     "core/trust/telemetry-attestation.ts": [
       "node:fs"
     ]

package/scripts/release-flow.js

@@ -229,12 +229,12 @@ function buildReviewerInput(resultPath) {
     "  <one concrete sentence: the user-visible capability this ships>",
     "or:",
     "  REJECTED",
-    "  <numbered gate failures with file:line references>",
+    "  kind: semantic-review",
+    "  1. <a semantic code finding with repo-relative file:line evidence>",
     "",
-    "If your host wrapper asks for Markdown, JSON, or a fenced result block, still put",
-    "the exact APPROVED/REJECTED verdict line above as a standalone line outside any",
-    "prose or code fence. The release tool extracts only strict standalone verdict",
-    "lines; prose such as 'Verdict: APPROVED' is not trusted.",
+    "The control plane already ran the deterministic gate. Do not run it again",
+    "or reject with an unsupported claim that it failed. A rejection without the",
+    "semantic-review form above is invalid reviewer output and remains fail closed.",
     ""
   ].join("\n");
 }
@@ -271,7 +271,7 @@ function extractVerdictFromStdout(stdout, resultPath) {
   const rejectedLine = lines.find((line) => isRejectedLine(line));
   if (rejectedLine) {
     process.stderr.write(`reviewer REJECTED via stdout — full output:\n${stdout.trim()}\n`);
-    return rejectedLine.trim();
+    return lines.slice(lines.indexOf(rejectedLine)).join("\n").trim();
   }
   const approvedLine = lines.find((line) => /^APPROVED\s+\S+/.test(line.trim()));
   if (approvedLine) {
@@ -432,14 +432,19 @@ function verifyVerdict(resultPath) {
   const text = fs.readFileSync(resultPath, "utf8");
   const lines = text.split(/\r?\n/);
   const firstLine = lines[0] || "";
+  if (isRejectedLine(firstLine)) {
+    const rejection = validateSemanticRejection(lines);
+    if (!rejection.ok) {
+      die(`invalid reviewer output — ${rejection.reason}. Release remains blocked; this is not a verified code rejection.`, text.trim());
+    }
+    die("reviewer rejected the release with semantic evidence.", text.trim());
+  }
   if (firstLine !== `APPROVED ${HEAD}`) {
-    if (!isRejectedLine(firstLine)) {
-      const normalized = extractVerdictFromStdout(text, resultPath);
-      if (normalized && normalized.split(/\r?\n/)[0] === `APPROVED ${HEAD}`) {
-        fs.writeFileSync(resultPath, `${normalized}\n`);
-        const normalizedLines = normalized.split(/\r?\n/);
-        return (normalizedLines[1] || "").trim();
-      }
+    const normalized = extractVerdictFromStdout(text, resultPath);
+    if (normalized && normalized.split(/\r?\n/)[0] === `APPROVED ${HEAD}`) {
+      fs.writeFileSync(resultPath, `${normalized}\n`);
+      const normalizedLines = normalized.split(/\r?\n/);
+      return (normalizedLines[1] || "").trim();
     }
     die(`verdict first line must be exactly "APPROVED ${HEAD}" — release blocked.`, text.trim());
   }
@@ -447,6 +452,31 @@ function verifyVerdict(resultPath) {
   return cap;
 }
 
+function validateSemanticRejection(lines) {
+  if (lines[0] !== "REJECTED") {
+    return { ok: false, reason: 'a rejection must start with exact "REJECTED"' };
+  }
+  if (lines[1] !== "kind: semantic-review") {
+    return { ok: false, reason: 'a rejection must declare exact "kind: semantic-review"' };
+  }
+  const findings = lines.slice(2).filter((line) => /^\d+\.\s+/.test(line));
+  if (!findings.length) return { ok: false, reason: "a semantic rejection needs a numbered finding" };
+  for (const finding of findings) {
+    const match = finding.match(/^\d+\.\s+.*?\b([A-Za-z0-9][A-Za-z0-9_./-]*):(\d+)\b/);
+    if (!match) return { ok: false, reason: "each semantic finding needs a repo-relative file:line locator" };
+    const rel = match[1];
+    const line = Number(match[2]);
+    if (rel.startsWith("/") || rel.split("/").includes("..") || !Number.isSafeInteger(line) || line < 1) {
+      return { ok: false, reason: "a semantic finding has an unsafe file:line locator" };
+    }
+    const target = path.join(repoRoot, rel);
+    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+      return { ok: false, reason: `semantic evidence path does not exist: ${rel}` };
+    }
+  }
+  return { ok: true };
+}
+
 // ---- verdict signing (optional, opt-in — see the header comment) -----------
 function resolveVerdictPrivateKey(value) {
   const trimmed = String(value).trim();

package/scripts/release-gate.js

@@ -67,23 +67,47 @@ if (!PREV_TAG) {
 const MARKER_DIR = path.join(REPO_ROOT, ".cw-release");
 fs.mkdirSync(MARKER_DIR, { recursive: true });
 
+const MAX_CHILD_DIAGNOSTIC_BYTES = 16 * 1024;
+
+function boundedDiagnostic(text) {
+  const value = String(text || "").trim();
+  if (value.length <= MAX_CHILD_DIAGNOSTIC_BYTES) return value;
+  return `…${value.slice(-MAX_CHILD_DIAGNOSTIC_BYTES)}`;
+}
+
+function reportNpmFailure(label, result) {
+  // Failure facts are local diagnostics, never stdout data and never a saved
+  // release record. Keep the tail so a large smoke run cannot flood a terminal.
+  const out = boundedDiagnostic(result.stdout);
+  const err = boundedDiagnostic(result.stderr);
+  process.stderr.write(`release-gate: ${label} failed (exit ${result.status ?? "unknown"})\n`);
+  if (err) process.stderr.write(`[stderr]\n${err}\n`);
+  if (out) process.stderr.write(`[stdout]\n${out}\n`);
+}
+
 function runNpm(args, extraEnv) {
-  // stdio ignored on purpose (the old script sent both streams to /dev/null):
-  // the gate's verdict is the exit code; a red step is re-run by hand for detail.
   const r = spawnSync("npm", args, {
     cwd: REPO_ROOT,
-    stdio: "ignore",
+    encoding: "utf8",
     env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
   });
-  return !r.error && r.status === 0;
+  return r;
 }
 
 // --- 1. Build & tests (run, don't trust pasted output) -----------------
 say("[1/6] build");
-if (!runNpm(["run", "--prefix", "plugins/cool-workflow", "build"])) fail("build failed");
+const build = runNpm(["run", "--prefix", "plugins/cool-workflow", "build"]);
+if (build.error || build.status !== 0) {
+  fail("build failed");
+  reportNpmFailure("build", build);
+}
 
 say("[2/6] tests");
-if (!runNpm(["run", "test:gate", "--prefix", "plugins/cool-workflow"], { CW_TEST_CONCURRENCY: "1" })) fail("tests failed");
+const tests = runNpm(["run", "test:gate", "--prefix", "plugins/cool-workflow"], { CW_TEST_CONCURRENCY: "1" });
+if (tests.error || tests.status !== 0) {
+  fail("tests failed");
+  reportNpmFailure("tests", tests);
+}
 
 if (PREV_TAG) {
   const RANGE = `${PREV_TAG}..HEAD`;

package/scripts/schema-version-inventory.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "domains": [
+    { "domain": "agent-config", "constant": "AGENT_CONFIG_SCHEMA_VERSION", "source": "shell/agent-config.ts" },
+    { "domain": "blackboard", "constant": "BLACKBOARD_SCHEMA_VERSION", "source": "core/multi-agent/coordinator.ts" },
+    { "domain": "candidate", "constant": "CANDIDATE_SCHEMA_VERSION", "source": "core/multi-agent/candidate-scoring.ts" },
+    { "domain": "collaboration", "constant": "COLLABORATION_SCHEMA_VERSION", "source": "core/multi-agent/collaboration.ts" },
+    { "domain": "contract-migration", "constant": "CONTRACT_MIGRATION_SCHEMA_VERSION", "source": "core/state/contract-migration.ts" },
+    { "domain": "current-run-state", "constant": "CURRENT_RUN_STATE_SCHEMA_VERSION", "source": "core/version.ts" },
+    { "domain": "drive", "constant": "DRIVE_SCHEMA_VERSION", "source": "core/pipeline/drive-decide.ts" },
+    { "domain": "error-feedback", "constant": "ERROR_FEEDBACK_SCHEMA_VERSION", "source": "core/pipeline/error-feedback.ts" },
+    { "domain": "evidence-reasoning", "constant": "EVIDENCE_REASONING_SCHEMA_VERSION", "source": "shell/evidence-reasoning.ts" },
+    { "domain": "execution-backend", "constant": "EXECUTION_BACKEND_SCHEMA_VERSION", "source": "shell/execution-backend/registry.ts" },
+    { "domain": "legacy-run-state", "constant": "LEGACY_RUN_STATE_SCHEMA_VERSION", "source": "core/version.ts" },
+    { "domain": "metrics", "constant": "METRICS_SCHEMA_VERSION", "source": "shell/observability.ts" },
+    { "domain": "minimum-run-state", "constant": "MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION", "source": "core/version.ts" },
+    { "domain": "multi-agent", "constant": "MULTI_AGENT_SCHEMA_VERSION", "source": "core/multi-agent/runtime.ts" },
+    { "domain": "node-snapshot", "constant": "NODE_SNAPSHOT_SCHEMA_VERSION", "source": "core/state/node-snapshot.ts" },
+    { "domain": "pipeline-contract", "constant": "PIPELINE_CONTRACT_SCHEMA_VERSION", "source": "core/state/state-node.ts" },
+    { "domain": "run-registry", "constant": "RUN_REGISTRY_SCHEMA_VERSION", "source": "shell/run-registry-io.ts" },
+    { "domain": "sandbox-profile", "constant": "SANDBOX_PROFILE_SCHEMA_VERSION", "source": "shell/sandbox-profile.ts" },
+    { "domain": "scheduling", "constant": "SCHEDULING_SCHEMA_VERSION", "source": "shell/scheduling-io.ts" },
+    { "domain": "state-explosion", "constant": "STATE_EXPLOSION_SCHEMA_VERSION", "source": "core/state/state-explosion/size.ts" },
+    { "domain": "state-node", "constant": "STATE_NODE_SCHEMA_VERSION", "source": "core/state/state-node.ts" },
+    { "domain": "telemetry-ledger", "constant": "TELEMETRY_LEDGER_SCHEMA_VERSION", "source": "core/trust/telemetry-ledger.ts" },
+    { "domain": "topology", "constant": "TOPOLOGY_SCHEMA_VERSION", "source": "core/multi-agent/topology.ts" },
+    { "domain": "trust-audit", "constant": "TRUST_AUDIT_SCHEMA_VERSION", "source": "shell/trust-audit.ts" },
+    { "domain": "worker-isolation", "constant": "WORKER_ISOLATION_SCHEMA_VERSION", "source": "shell/worker-isolation.ts" },
+    { "domain": "workflow-app", "constant": "WORKFLOW_APP_SCHEMA_VERSION", "source": "core/version.ts" }
+  ]
+}

package/scripts/validate-run-state-schema.js

@@ -19,6 +19,8 @@ const path = require("node:path");
 const PLUGIN_ROOT = path.resolve(__dirname, "..");
 const TYPES_FILE = path.join(PLUGIN_ROOT, "src", "core", "state", "types.ts");
 const SCHEMA_MODULE = path.join(PLUGIN_ROOT, "dist", "core", "state", "schema.js");
+const SOURCE_ROOT = path.join(PLUGIN_ROOT, "src");
+const VERSION_INVENTORY_FILE = path.join(__dirname, "schema-version-inventory.json");
 
 function main() {
   const errors = [];
@@ -43,6 +45,15 @@ function main() {
   const requiredKeys = new Set(schema.REQUIRED_TOP_LEVEL_KEYS || []);
   const optionalKeys = new Set(schema.OPTIONAL_TOP_LEVEL_KEYS || []);
 
+  let versionInventory;
+  try {
+    versionInventory = JSON.parse(fs.readFileSync(VERSION_INVENTORY_FILE, "utf8"));
+  } catch (error) {
+    console.error(`validate-run-state-schema: FATAL — cannot load ${VERSION_INVENTORY_FILE}.`);
+    process.exit(1);
+  }
+  errors.push(...validateSchemaVersionInventory(versionInventory, readTypeScriptSources(SOURCE_ROOT)));
+
   // ---- 3. Cross-check: every type key must be either required or optional ----
   for (const key of runKeys) {
     if (requiredKeys.has(key)) continue;
@@ -70,9 +81,8 @@ function main() {
     console.error("validate-run-state-schema: FAIL CLOSED — schema drift detected.");
     for (const e of errors) console.error(`  ${e}`);
     console.error(
-      `\nFix: update REQUIRED_TOP_LEVEL_KEYS and/or OPTIONAL_TOP_LEVEL_KEYS in ` +
-      `src/run-state-schema.ts, then update normalizeRunState() and validateMigratedRunState() ` +
-      `in src/state-migrations.ts to handle any new required fields.`
+      `\nFix: update the run-state key lists or schema-version-inventory.json and its canonical source. ` +
+      `Keep each schema domain separate.`
     );
     process.exit(1);
   }
@@ -82,6 +92,85 @@ function main() {
     `validate-run-state-schema: ok — ${runKeys.size} WorkflowRun keys accounted for ` +
     `(${requiredKeys.size} required + ${optionalKeys.size} optional = ${total})`
   );
+  console.error(
+    `validate-run-state-schema: ok — ${versionInventory.domains.length} schema version domains have one definition each`
+  );
+}
+
+function readTypeScriptSources(root, base = root) {
+  const files = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const absolute = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...readTypeScriptSources(absolute, base));
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith(".ts")) continue;
+    files.push({
+      path: path.relative(base, absolute).split(path.sep).join("/"),
+      source: fs.readFileSync(absolute, "utf8"),
+    });
+  }
+  return files;
+}
+
+function validateSchemaVersionInventory(inventory, sourceFiles) {
+  const errors = [];
+  if (!inventory || inventory.schemaVersion !== 1 || !Array.isArray(inventory.domains)) {
+    return ["Schema version inventory must have schemaVersion 1 and a domains array."];
+  }
+
+  const entriesByConstant = new Map();
+  const domains = new Set();
+  for (const entry of inventory.domains) {
+    if (!entry || typeof entry.domain !== "string" || typeof entry.constant !== "string" || typeof entry.source !== "string") {
+      errors.push("Schema version inventory entries need domain, constant, and source strings.");
+      continue;
+    }
+    if (domains.has(entry.domain)) errors.push(`Schema version domain "${entry.domain}" is listed more than once.`);
+    domains.add(entry.domain);
+    if (entriesByConstant.has(entry.constant)) {
+      errors.push(`Schema version constant "${entry.constant}" is listed more than once.`);
+    } else {
+      entriesByConstant.set(entry.constant, entry);
+    }
+  }
+
+  const definitions = new Map();
+  const pattern = /^\s*(?:export\s+)?const\s+([A-Z][A-Z0-9_]*_SCHEMA_VERSION)\s*(?::[^=;]+)?=/gm;
+  for (const file of sourceFiles) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(file.source)) !== null) {
+      const found = definitions.get(match[1]) || [];
+      found.push(file.path);
+      definitions.set(match[1], found);
+    }
+  }
+
+  for (const [constant, sources] of definitions) {
+    const entry = entriesByConstant.get(constant);
+    if (!entry) {
+      errors.push(`Unknown schema version domain: "${constant}" has a definition in ${sources.join(", ")}.`);
+      continue;
+    }
+    if (sources.length > 1) {
+      errors.push(`Schema version constant "${constant}" has more than one definition: ${sources.join(", ")}.`);
+    }
+    for (const source of sources) {
+      if (source !== entry.source) {
+        errors.push(`Schema version constant "${constant}" must be defined in ${entry.source}, not ${source}.`);
+      }
+    }
+  }
+
+  for (const [constant, entry] of entriesByConstant) {
+    if (!definitions.has(constant)) {
+      errors.push(`Schema version inventory entry "${entry.domain}" has no definition for ${constant}.`);
+    }
+  }
+
+  return errors;
 }
 
 /**
@@ -123,4 +212,6 @@ function extractInterfaceKeys(source, interfaceName) {
   return keys;
 }
 
-main();
+if (require.main === module) main();
+
+module.exports = { extractInterfaceKeys, validateSchemaVersionInventory };