ruvnet-brain 4.3.8 → 4.3.10

package/scripts/publication-receipt.mjs

@@ -7,7 +7,6 @@ import os from 'node:os';
 import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
-import readline from 'node:readline';
 import { spawn, spawnSync } from 'node:child_process';
 // ONE doctor rule and ONE mode vocabulary, shared with the staged-side check in
 // scripts/staged-host-verifier.mjs. This file kept its own copies, spelled claudeOnly/
@@ -16,11 +15,12 @@ import { spawn, spawnSync } from 'node:child_process';
 // post-publication proofs below (payload assertions, MCP wiring, SOURCE.json, rpcSearch)
 // stay here — they are this side's job, not duplication.
 import { HOST_MODES, RECEIPT_MODE_NAMES, MODE_FROM_RECEIPT_NAME, classifyDoctor, VARIANTS } from './host-install-matrix.mjs';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { evaluateCandidateReceipt, evaluatePublicationReceipt } from './release-proof.mjs';
 import { verifyPayload } from './release-payload.mjs';
-import { digest, sha256File } from './coverage-integrity.mjs';
-import { parseCitations } from '../kb/verify-citation.mjs';
+import { resolveInstalledCanaryCitation } from './retrieval-canary.mjs';
+import { runNightlyTwoRunProof, validateNightlyProofReceipt } from './nightly-two-run-proof.mjs';
+import { parseRetrievalResult } from '../kb/retrieval-result.mjs';
 
 const REPO = 'stuinfla/ruvnet-brain';
 const PACKAGE = 'ruvnet-brain';
@@ -29,30 +29,95 @@ const DEADLINE_MS = 30_000;
 const sha256 = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
 const receiptDigest = (candidate) => String(candidate?.artifact?.sha256 || '').replace(/^sha256:/, '');
-
+export function commandInvocation(name, args, { platform = process.platform, env = process.env } = {}) {
+  if (platform === 'win32' && /^(?:npm|npx)$/i.test(name)) return {
+    executable: env.ComSpec || 'cmd.exe', args: ['/d', '/c', `${name}.cmd`, ...args],
+  };
+  return { executable: name, args };
+}
+export function tarExtractionInvocation(artifactPath, destination, { platform = process.platform } = {}) {
+  const paths = platform === 'win32' ? path.win32 : path;
+  const archive = paths.resolve(artifactPath);
+  // A relative archive argument avoids GNU tar's drive-letter remote-host syntax and also
+  // works with Windows BSD tar, which does not support GNU's --force-local option.
+  return { args: ['-xzf', `./${paths.basename(archive)}`, '-C', paths.resolve(destination)],
+    cwd: paths.dirname(archive) };
+}
 function command(name, args, options = {}) {
-  const result = spawnSync(name, args, { encoding: 'utf8', ...options });
+  const { platform = process.platform, ...spawnOptions } = options;
+  const invocation = commandInvocation(name, args, { platform, env: spawnOptions.env || process.env });
+  const result = spawnSync(invocation.executable, invocation.args, { encoding: 'utf8', ...spawnOptions });
   if (result.error || result.status !== 0) {
     const detail = String(result.stderr || result.stdout || result.error?.message || '').trim();
     throw new Error(`${name} ${args.join(' ')} failed: ${detail || `exit ${result.status}`}`);
   }
   return String(result.stdout || '').trim();
 }
-
-function locate(name) {
-  try { return command('which', [name]); } catch { return null; }
+export function validateCandidateSource(root, { sha, version }) {
+  const candidateRoot = fs.realpathSync(root);
+  const options = { cwd: candidateRoot };
+  const top = command('git', ['rev-parse', '--show-toplevel'], options);
+  const head = command('git', ['rev-parse', 'HEAD'], options);
+  // Git and Node can spell the same Windows directory with different casing/separators.
+  // Compare actual directory identity, never case-fold distinct source paths.
+  const candidateDirectory = fs.statSync(candidateRoot, { bigint: true });
+  const topDirectory = fs.statSync(top, { bigint: true });
+  if (!candidateDirectory.isDirectory() || !topDirectory.isDirectory()
+    || candidateDirectory.ino <= 0n || topDirectory.ino <= 0n
+    || candidateDirectory.dev !== topDirectory.dev || candidateDirectory.ino !== topDirectory.ino
+    || !/^[a-f0-9]{40}$/.test(String(sha)) || head !== sha) {
+    throw new Error(`candidate checkout ${head} does not match candidate ${sha}`);
+  }
+  if (command('git', ['status', '--porcelain', '--untracked-files=no'], options)) {
+    throw new Error('candidate checkout has tracked changes');
+  }
+  const manifest = path.join(candidateRoot, 'package.json');
+  const stat = fs.lstatSync(manifest);
+  if (!stat.isFile() || stat.isSymbolicLink() || !version || readJson(manifest).version !== version) {
+    throw new Error('candidate checkout package version differs from the released candidate');
+  }
+  return candidateRoot;
 }
-
-function isolatedPath(mode, temp) {
+function locate(name, { platform = process.platform } = {}) {
+  const query = platform === 'win32' ? (name === 'node' ? 'node.exe' : `${name}.cmd`) : name;
+  try {
+    return command(platform === 'win32' ? 'where.exe' : 'which', [query], { platform })
+      .split(/\r?\n/).find(Boolean) || null;
+  } catch { return null; }
+}
+export function createIsolatedPath(mode, temp, { platform = process.platform, env = process.env,
+  resolve = (name) => locate(name, { platform }) } = {}) {
   const bin = path.join(temp, `bin-${mode}`);
   fs.mkdirSync(bin);
   const hosts = mode === 'claudeOnly' ? ['claude'] : mode === 'codexOnly' ? ['codex'] : ['claude', 'codex'];
-  for (const name of ['node', 'npm', ...hosts]) {
-    const target = locate(name);
+  const names = platform === 'win32' ? ['npm', ...hosts] : ['node', 'npm', ...hosts];
+  for (const name of names) {
+    const target = resolve(name);
     if (!target) throw new Error(`${name} CLI unavailable for ${mode} public host fixture`);
-    fs.symlinkSync(target, path.join(bin, name));
+    if (platform === 'win32') {
+      fs.writeFileSync(path.join(bin, `${name}.cmd`), `@call "${target}" %*\r\n`, { flag: 'wx' });
+    } else {
+      fs.symlinkSync(target, path.join(bin, name));
+    }
   }
-  return `${bin}:/usr/bin:/bin`;
+  if (platform !== 'win32') return `${bin}:/usr/bin:/bin`;
+  const node = resolve('node');
+  if (!node) throw new Error(`node CLI unavailable for ${mode} public host fixture`);
+  return [bin, path.dirname(node), path.join(env.SystemRoot || 'C:\\Windows', 'System32'),
+    path.join(env.ProgramFiles || 'C:\\Program Files', 'Git', 'usr', 'bin')].join(path.win32.delimiter);
+}
+export function stageVerifiedBundle({ bundlePath, bundleSha256, packageRoot }) {
+  const source = path.resolve(bundlePath || '');
+  let stat;
+  try { stat = fs.lstatSync(source); } catch { throw new Error('verified public bundle is missing'); }
+  if (!stat.isFile() || stat.isSymbolicLink() || sha256(source) !== bundleSha256) {
+    throw new Error('verified bundle digest mismatch before installation');
+  }
+  const destination = path.join(packageRoot, 'dist', 'ruvnet-brain.zip');
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination, fs.constants.COPYFILE_EXCL);
+  if (sha256(destination) !== bundleSha256) throw new Error('staged verified bundle digest mismatch');
+  return destination;
 }
 
 async function download(url, destination, headers = {}) {
@@ -134,17 +199,32 @@ export function assertInstalledPayload(sourceRoot, installedRoot) {
   return checked;
 }
 
-function rpcSearch(server, env, query, timeoutMs = DEADLINE_MS) {
+export function rpcSearch(server, env, query, k = 5, timeoutMs = DEADLINE_MS, {
+  requiredRepo = 'ruvnet-brain',
+} = {}) {
+  if (!Number.isSafeInteger(k) || k < 1 || k > 50) throw new Error(`invalid search result count: ${k}`);
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [server], { env, stdio: ['pipe', 'pipe', 'pipe'] });
     let stdout = '';
     let stderr = '';
     let timer;
+    let killTimer;
+    let closeTimer;
+    let outcome;
     const pending = new Map();
     const finish = (error, value) => {
+      if (outcome) return;
+      outcome = { error, value };
       clearTimeout(timer);
+      pending.clear();
+      // Do not let the next doctor/search probe contend with this process while it exits.
+      // A child that ignores graceful shutdown must not leave the verifier hanging either.
+      killTimer = setTimeout(() => {
+        outcome.error = new Error('installed Brain did not shut down within 5000ms');
+        child.kill('SIGKILL');
+        closeTimer = setTimeout(() => reject(new Error('installed Brain process did not close after SIGKILL')), 1000);
+      }, 5000);
       child.kill('SIGTERM');
-      error ? reject(error) : resolve(value);
     };
     timer = setTimeout(() => finish(new Error(`installed Brain exceeded ${timeoutMs}ms deadline`)), timeoutMs);
     child.stderr.on('data', (chunk) => { stderr += chunk; });
@@ -162,8 +242,12 @@ function rpcSearch(server, env, query, timeoutMs = DEADLINE_MS) {
       }
     });
     child.on('error', (error) => finish(error));
-    child.on('exit', (code) => {
-      if (pending.size) finish(new Error(`installed Brain exited ${code}: ${stderr.slice(0, 400)}`));
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      clearTimeout(killTimer);
+      clearTimeout(closeTimer);
+      const result = outcome || { error: new Error(`installed Brain exited ${code}: ${stderr.slice(0, 400)}`) };
+      result.error ? reject(result.error) : resolve(result.value);
     });
     const call = (id, method, params = {}) => new Promise((done) => {
       pending.set(id, done);
@@ -175,17 +259,21 @@ function rpcSearch(server, env, query, timeoutMs = DEADLINE_MS) {
       const listed = await call(2, 'tools/list');
       if (!listed.result?.tools?.some((tool) => tool.name === 'search_ruvnet')) throw new Error('installed MCP does not advertise search_ruvnet');
       const started = performance.now();
-      const searched = await call(3, 'tools/call', { name: 'search_ruvnet', arguments: { query, k: 5 } });
+      const searched = await call(3, 'tools/call', { name: 'search_ruvnet', arguments: { query, k } });
       const broadMs = Math.round(performance.now() - started);
       const text = (searched.result?.content || []).map((item) => item.text || '').join('\n');
       if (searched.error || searched.result?.isError || /search_ruvnet error:/i.test(text)) throw new Error(`installed Brain search failed: ${text.slice(0, 400)}`);
-      if (!/repo=ruvnet-brain/i.test(text) || !/path\s*:/i.test(text)) throw new Error('installed Brain search returned no ruvnet-brain source citation');
-      finish(null, { broadMs, text });
+      if (!/repo=/i.test(text) || !/path\s*:/i.test(text)) throw new Error('installed Brain search returned no source citation');
+      const repos = [...text.matchAll(/repo=([\w.-]+)/gi)].map((match) => match[1].toLowerCase());
+      if (requiredRepo && !repos.includes(String(requiredRepo).toLowerCase())) {
+        throw new Error(`installed Brain search returned no ${requiredRepo} source citation`);
+      }
+      finish(null, { broadMs, text, mcpResult: searched.result });
     })().catch((error) => finish(error));
   });
 }
 
-export function livePublicationAdapter({ root = process.cwd() } = {}) {
+export function livePublicationAdapter({ root = process.cwd(), candidateRoot = root } = {}) {
   const installContexts = new Map();
   const passageFileDigests = new Map();
   let installTemp = null;
@@ -213,14 +301,46 @@ export function livePublicationAdapter({ root = process.cwd() } = {}) {
       return { path: destination, tag: release.tag_name, sha: tagCommit(root, tag) };
     },
 
-    async installHosts({ artifactPath, artifactSha256, version }) {
-      const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-public-install-'));
+    async runNativeNightly({ identity, workflowRunId }) {
+      const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-public-nightly-'));
+      let completed = false;
+      try {
+        const npm = await this.downloadNpm({ version: identity.version,
+          destination: path.join(temp, 'package.tgz') });
+        const bundle = await this.downloadGithub({ tag: identity.tag, assetName: 'ruvnet-brain.zip',
+          destination: path.join(temp, 'ruvnet-brain.zip') });
+        const signature = await this.downloadGithub({ tag: identity.tag, assetName: 'ruvnet-brain.zip.sig',
+          destination: path.join(temp, 'ruvnet-brain.zip.sig') });
+        if (sha256(npm.path) !== identity.packageSha256 || sha256(bundle.path) !== identity.bundleSha256
+          || npm.version !== identity.version || bundle.sha !== identity.candidateSha
+          || signature.sha !== identity.candidateSha) throw new Error('nightly public artifact identity mismatch');
+        const proof = await runNightlyTwoRunProof({ packagePath: npm.path, bundlePath: bundle.path,
+          signaturePath: signature.path, sourceSha: identity.candidateSha, workflowRunId,
+          out: path.join(temp, 'nightly-proof.json') });
+        const validation = validateNightlyProofReceipt(proof, { platform: process.platform, version: identity.version,
+          packageSha256: identity.packageSha256, bundleSha256: identity.bundleSha256,
+          sourceSha: identity.candidateSha, workflowRunId });
+        if (!validation.ok) throw new Error(`public nightly proof failed: ${validation.failures.join('; ')}`);
+        completed = true;
+        return proof;
+      } finally {
+        if (completed) fs.rmSync(temp, { recursive: true, force: true });
+        else console.error(`Native public artifact diagnostics retained at ${temp}`);
+      }
+    },
+
+    async installHosts({ artifactPath, artifactSha256, bundlePath, bundleSha256, version }) {
+      const temp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-public-install-')));
       installTemp = temp;
       const packageRoot = path.join(temp, 'package');
-      command('tar', ['-xzf', artifactPath, '-C', temp]);
+      const extraction = tarExtractionInvocation(artifactPath, temp);
+      command('tar', extraction.args, { cwd: extraction.cwd });
+      stageVerifiedBundle({ bundlePath, bundleSha256, packageRoot });
       const sealedPlugin = path.join(packageRoot, 'plugin');
       const results = {};
       let bundle = null;
+      const sharedModelCache = path.join(temp, 'models-cache');
+      fs.mkdirSync(sharedModelCache, { recursive: true });
       // Derived from HOST_MODES, so a fourth host shape is added in ONE place and this loop
       // cannot fall behind the staged-side check the way it did.
       for (const mode of HOST_MODES.map((m) => RECEIPT_MODE_NAMES[m])) {
@@ -233,26 +353,27 @@ export function livePublicationAdapter({ root = process.cwd() } = {}) {
         const env = {
           ...process.env,
           HOME: home,
+          ...(process.platform === 'win32' ? { USERPROFILE: home } : {}),
           CODEX_HOME: codexHome,
           RUVNET_BRAIN_HOME: brainHome,
           RUVNET_BRAIN_KB: kb,
+          KB_MODEL_CACHE: sharedModelCache,
           // Env comes from the ONE variant table (host-install-matrix VARIANTS.published), not a
           // second hand-written copy — this file's own header promises "ONE doctor rule and ONE mode
           // vocabulary, shared with the staged-side check", and the copy had already drifted: it
           // omitted the Codex hook-trust bypass the staged side carries, which failed the seal on
           // every release.
           ...VARIANTS.published.env({ packageRoot }),
+          RUVNET_STRICT_INSTALL: '0',
           CI: 'true',
-          PATH: isolatedPath(mode, temp),
+          PATH: createIsolatedPath(mode, temp),
         };
         const installer = path.join(packageRoot, 'bin', 'install.mjs');
         command(process.execPath, [
           installer, '--yes', '--force', '--version', `v${version}`,
           '--no-nightly-prompt', '--no-telemetry', '--no-stack', '--no-enhance', '--no-statusline',
+          '--no-selfcheck', '--no-verify',
         ], { env, cwd: packageRoot, timeout: 1_200_000, maxBuffer: 32 * 1024 * 1024 });
-        command(process.execPath, [installer, '--doctor', '--hooks'], {
-          env, cwd: packageRoot, timeout: 300_000, maxBuffer: 32 * 1024 * 1024,
-        });
 
         const verified = {};
         if (mode !== 'codexOnly') {
@@ -270,7 +391,11 @@ export function livePublicationAdapter({ root = process.cwd() } = {}) {
           throw new Error(`${mode} installed public Brain bundle version mismatch`);
         }
         bundle ||= { brainVersion: source.brainVersion, releaseTag: source.releaseTag };
-        const searched = await rpcSearch(findMcpServer(home), env, 'How does RuvNet Brain prove a public release artifact?', DEADLINE_MS);
+        const searched = await rpcSearch(findMcpServer(home), env,
+          'How does RuvNet Brain prove a public release artifact?', 5, DEADLINE_MS);
+        command(process.execPath, [installer, '--doctor', '--hooks'], {
+          env, cwd: packageRoot, timeout: 300_000, maxBuffer: 32 * 1024 * 1024,
+        });
         results[mode] = {
           status: 'PASS', doctorExit: 0, version, artifactSha256,
           functionalSearch: true, searchMs: searched.broadMs, hostsOnPath: mode,
@@ -291,55 +416,36 @@ export function livePublicationAdapter({ root = process.cwd() } = {}) {
       if (rvfs.length === 0) throw new Error('installed public Brain has no ruvnet-brain self RVF');
       const server = path.join(installContext.home, '.claude', 'ruvnet-brain', 'mcp', 'server.mjs');
       if (!fs.existsSync(server)) throw new Error('installed persistent MCP server is missing');
-      const result = await rpcSearch(server, installContext.env, 'How does RuvNet Brain prove a public release artifact?', DEADLINE_MS);
+      const result = await rpcSearch(server, installContext.env,
+        'How does RuvNet Brain prove a public release artifact?', 5, DEADLINE_MS);
       const readiness = readJson(path.join(installContext.brainHome, 'mcp-readiness.json'));
       if (readiness.state !== 'ready') throw new Error(`installed Brain readiness is ${readiness.state || 'missing'}`);
       return { status: 'PASS', selfStore: true, broadMs: result.broadMs, deadlineMs: DEADLINE_MS };
     },
 
-    async searchInstalled({ mode, query }) {
+    async searchInstalled({ mode, query, k }) {
       const context = installContexts.get(mode);
       if (!context) throw new Error(`${mode} public host is not installed`);
-      const result = await rpcSearch(findMcpServer(context.home), context.env, query, DEADLINE_MS);
-      return parseCitations(result.text).map((citation) => ({
-        repo: citation.repo.toLowerCase(),
-        path: citation.docPath,
-      }));
+      // Each canary's exact expected repository/path/passage is checked by the canary validator.
+      const result = await rpcSearch(findMcpServer(context.home), context.env, query, k, DEADLINE_MS,
+        { requiredRepo: null });
+      return parseRetrievalResult(result.mcpResult, { query, k });
     },
 
     async resolveInstalledCitation({ mode, matched, expected }) {
       const context = installContexts.get(mode);
       if (!context) throw new Error(`${mode} public host is not installed`);
-      if (String(matched?.repo || '').toLowerCase() !== expected.repo || matched?.path !== expected.path) {
-        return { resolved: false };
-      }
-      const files = [
-        path.join(context.kb, `${expected.repo}.passages.jsonl`),
-        path.join(context.kb, `${expected.repo}.big.passages.jsonl`),
-      ].filter((file) => fs.existsSync(file));
-      for (const file of files) {
-        const rows = readline.createInterface({ input: fs.createReadStream(file), crlfDelay: Infinity });
-        try {
-          for await (const line of rows) {
-            let record;
-            try { record = JSON.parse(line); } catch { continue; }
-            if (record?.path !== expected.path) continue;
-            const passageSha256 = digest(record);
-            if (passageSha256 !== expected.passageSha256) return { resolved: false };
-            if (!passageFileDigests.has(file)) passageFileDigests.set(file, sha256File(file));
-            return { resolved: true, evidence: { passageSha256, passageFileSha256: passageFileDigests.get(file) } };
-          }
-        } finally { rows.close(); }
-      }
-      return { resolved: false };
+      return resolveInstalledCanaryCitation({ kbDir: context.kb, matched, expected, passageFileDigests });
     },
 
-    async probePublishedSurface({ sha }) {
-      const head = command('git', ['rev-parse', 'HEAD'], { cwd: root });
-      if (head !== sha) throw new Error(`published-surface probe checkout ${head} does not match candidate ${sha}`);
-      const result = spawnSync(process.execPath, ['scripts/published-surface-probe.mjs', '--json'], {
-        cwd: root, env: process.env, encoding: 'utf8', timeout: 600_000,
+    async probePublishedSurface({ sha, version }) {
+      const source = validateCandidateSource(candidateRoot, { sha, version });
+      // The verifier supplies executable checks; the candidate supplies only the released source.
+      const script = fileURLToPath(new URL('./published-surface-probe.mjs', import.meta.url));
+      const result = spawnSync(process.execPath, [script, '--json'], {
+        cwd: source, env: process.env, encoding: 'utf8', timeout: 600_000,
       });
+      validateCandidateSource(candidateRoot, { sha, version });
       let parsed;
       try { parsed = JSON.parse(String(result.stdout || '')); } catch { throw new Error(`published-surface-probe emitted invalid JSON: ${String(result.stderr || '').slice(0, 300)}`); }
       if (result.status !== 0 || parsed.verdict !== 'PASS') throw new Error(`published-surface-probe is ${parsed.verdict || `exit ${result.status}`}`);
@@ -400,7 +506,8 @@ export async function generatePublicationReceipt({
     if (npm.version !== candidate.version || (npm.sha && npm.sha !== candidate.sha)) throw new Error('npm public identity mismatch');
     if (github.tag !== candidate.tag || github.sha !== candidate.sha) throw new Error('GitHub public identity mismatch');
 
-    const installed = await adapter.installHosts({ artifactPath: npm.path, artifactSha256: digest, version: candidate.version });
+    const installed = await adapter.installHosts({ artifactPath: npm.path, artifactSha256: digest,
+      bundlePath: githubBundle.path, bundleSha256: githubBundleDigest, version: candidate.version });
     const brain = await adapter.probeBrain({ sha: candidate.sha, artifactSha256: digest, version: candidate.version });
     const surface = await adapter.probePublishedSurface({ sha: candidate.sha, artifactSha256: digest, version: candidate.version });
     const publication = {

package/scripts/published-surface-probe.mjs

@@ -52,6 +52,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 export const EXIT = Object.freeze({ PASS: 0, FAIL: 1, UNKNOWN: 4 });
 
@@ -127,6 +128,12 @@ async function probeRegistry() {
 }
 
 // ── B. EXECUTE the published package, from the registry ────────────────────────────────────────
+export function npxInvocation(args, { platform = process.platform, env = process.env } = {}) {
+  if (platform === 'win32') return {
+    executable: env.ComSpec || 'cmd.exe', args: ['/d', '/c', 'npx.cmd', ...args],
+  };
+  return { executable: 'npx', args };
+}
 function probeExec() {
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-brain-probe-'));
   try {
@@ -134,7 +141,8 @@ function probeExec() {
     // (npm resolve → download → unpack → bin mapping → node parses every module it imports) while
     // touching NOTHING on the machine. `--doctor`/`--plan` reach the network and the brain dir; this
     // probe must never be the reason a surface changes.
-    const r = spawnSync('npx', ['-y', `${PKG}@latest`, '--help'], {
+    const invocation = npxInvocation(['-y', `${PKG}@latest`, '--help']);
+    const r = spawnSync(invocation.executable, invocation.args, {
       encoding: 'utf8',
       timeout: 300_000,
       cwd: home,
@@ -237,5 +245,5 @@ export async function main() {
   return EXIT[verdict];
 }
 
-const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (invokedDirectly) process.exit(await main());

package/scripts/qa-contract.mjs

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+
+export function verdictOf(results) {
+  if (results.some(({ status }) => ['FAIL', 'TIMEOUT', 'BLOCKED'].includes(status))) return 'FAIL';
+  return results.length && results.every(({ status }) => status === 'PASS') ? 'PASS' : 'UNKNOWN';
+}
+
+// A source digest includes dirty tracked files and untracked source, never ignored build outputs.
+export function sourceIdentity(root) {
+  const git = (args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  let sha = null;
+  try { sha = git(['rev-parse', 'HEAD']).trim(); } catch { /* unborn repository */ }
+  const files = [...new Set(git(['ls-files', '-z', '--cached', '--others', '--exclude-standard']).split('\0').filter(Boolean))].sort();
+  const hash = createHash('sha256');
+  for (const relative of files) {
+    const file = path.join(root, relative);
+    let bytes = Buffer.from('deleted');
+    try {
+      const stat = fs.lstatSync(file);
+      bytes = stat.isSymbolicLink() ? Buffer.from(`symlink:${fs.readlinkSync(file)}`)
+        : stat.isFile() ? Buffer.concat([Buffer.from(`${stat.mode & 0o777}:`), fs.readFileSync(file)]) : Buffer.from('directory');
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    hash.update(JSON.stringify([relative, createHash('sha256').update(bytes).digest('hex')]));
+  }
+  return { sha, dirty: Boolean(git(['status', '--porcelain']).trim()), digest: hash.digest('hex'), files: files.length, recipe: 'git-source-bytes-v1' };
+}
+
+export async function runLanes(lanes, execute, concurrency = 2) {
+  if (!Number.isInteger(concurrency) || concurrency < 1) throw new Error('invalid QA concurrency');
+  const names = new Set(lanes.map(({ name }) => name));
+  if (names.size !== lanes.length || lanes.some((lane) => (lane.dependsOn || []).some((name) => !names.has(name)))) throw new Error('invalid QA dependency');
+  const pending = [...lanes], completed = new Map();
+  while (pending.length) {
+    const resources = new Set(), batch = [];
+    for (const lane of pending) {
+      if (!(lane.dependsOn || []).every((name) => completed.has(name))) continue;
+      if ((lane.dependsOn || []).some((name) => completed.get(name).status !== 'PASS')) {
+        completed.set(lane.name, { name: lane.name, status: 'BLOCKED', reason: 'required prerequisite did not pass' });
+        continue;
+      }
+      if (batch.length >= concurrency || (lane.resource && resources.has(lane.resource))) continue;
+      batch.push(lane); resources.add(lane.resource);
+    }
+    if (!batch.length && !pending.some(({ name }) => completed.has(name))) throw new Error('QA dependency cycle');
+    await Promise.all(batch.map(async (lane) => {
+      let result;
+      try { result = await execute(lane); }
+      catch (error) { result = { name: lane.name, status: 'FAIL', reason: error.message }; }
+      completed.set(lane.name, result);
+    }));
+    for (let index = pending.length - 1; index >= 0; index--) if (completed.has(pending[index].name)) pending.splice(index, 1);
+  }
+  return lanes.map(({ name }) => completed.get(name));
+}

package/scripts/qa-lanes.mjs

@@ -0,0 +1,40 @@
+// Shared producers for local diagnostics, CI, and candidate qualification.
+export function selectLanes(lanes, requested) {
+  if (!requested.length) return lanes;
+  const selected = new Set();
+  const visit = (name) => {
+    const lane = lanes.find((entry) => entry.name === name);
+    if (!lane) throw new Error(`unknown QA lane: ${name}`);
+    if (selected.has(name)) return;
+    selected.add(name);
+    for (const dependency of lane.dependsOn || []) visit(dependency);
+  };
+  requested.forEach(visit);
+  return lanes.filter(({ name }) => selected.has(name));
+}
+
+export function qaLanes({ release = false, base = null, runtimeCensusArgs = [] } = {}) {
+  const node = (name, script, args = [], extra = {}) => ({ name, command: process.execPath, args: [script, ...args], resource: 'static', ...extra });
+  const test = (name, args) => node(name, 'node_modules/vitest/vitest.mjs', ['run', ...args], { resource: 'tests' });
+  return [
+    node('version', 'scripts/sync-version.mjs', ['--check']),
+    node('convergence', 'scripts/convergence-manifest.mjs'),
+    node('execution-policy', 'scripts/execution-policy.mjs', ['{"action":"delegate","description":"architecture audit","nativeHosts":["codex"]}']),
+    node('architecture', 'scripts/product-integrity-contract.mjs', ['--check-source']),
+    node('docs', 'scripts/doc-currency.mjs', ['--check', ...(base ? ['--changed', base] : ['--warn-drift'])]),
+    node('wiring', 'scripts/wired-check.mjs', ['--check']),
+    node('substitution', 'scripts/no-silent-substitution.mjs'),
+    node('catalog', 'scripts/verify-model-catalog.mjs'),
+    test('coverage', ['tests/unit', '--coverage']),
+    node('claims-source', 'scripts/claims-verify.mjs', ['--strict', '--scope', 'source'], { dependsOn: ['coverage'], report: 'claims' }),
+    test('mesh', ['tests/mesh']),
+    node('plugin', 'plugin/test/run-tests.mjs', [], { resource: 'tests' }),
+    ...(release ? [
+      test('mutation', ['tests/mutation']),
+      test('regression', ['tests/regression']),
+      test('integration', ['tests/integration']),
+      test('continuity', ['tests/acceptance/cross-host-project-resume.test.mjs']),
+      node('claims-runtime', 'scripts/claims-verify.mjs', ['--strict', '--scope', 'runtime', ...runtimeCensusArgs], { report: 'claims' }),
+    ] : []),
+  ];
+}