@starci/hfs 4.8.0 → 4.9.1

package/runtime/scripts/gates/grammar-dist.mjs

@@ -1,206 +0,0 @@
-// grammar-dist.mjs - is packages/grammar/dist the build of the source beside it? The judge every grammar dist reader asks
-// (gates, work, the reconciler and land); scripts/checks/check-grammar-dist.mjs is its self-check CLI.
-import fs from 'node:fs';
-import path from 'node:path';
-import { byCodeUnit } from '../lib/list.mjs';
-import {skillRoot} from '../../engine/runtime-root.mjs';
-import {gitDirOf} from '../lib/git-dir.mjs';
-import {readJsonFile as readJson} from '../lib/json.mjs';
-import {slash} from '../lib/path-key.mjs';
-import {DIGEST_ALGORITHM,STAMP_FILE,STAMP_SCHEMA,distDigest,sourceDigest} from '../../packages/grammar/scripts/build-stamp.mjs';
-
-/**
- * A built `packages/grammar/dist` is what products actually get: `file:` consumers link the package
- * directory, and the brand check reads the exported CSS. `dist/` is not tracked, so nothing but a build
- * refreshes it, and a merge that changes the source leaves the previous build in place. This module
- * decides whether a dist is the build of the source beside it, and every reader of grammar dist asks it
- * first and refuses a dist it does not call fresh.
- *
- * Fresh means: `dist/.build-stamp.json` exists, names the manifest's version, was made with this
- * digest algorithm from the current source digest, the built files still hash to the stamp's dist
- * digest, and every `--*` custom property the source CSS declares has the same value in the copied dist
- * CSS. A package that does not carry its source (a registry install) cannot be rebuilt or compared, so
- * it is `unverifiable` and allowed once its stamp binds: the version and dist digest must agree.
- */
-
-export const GRAMMAR_PACKAGE='@starci/grammar';
-export const GRAMMAR_DIST_FIX='run npm run build in packages/grammar';
-const GRAMMAR_DIST_CHECK='starci/grammar-dist-check@1';
-const TOKEN_DIFF_CAP=20;
-const CSS_TOKEN_NAME = '--[A-Za-z0-9_-]+';
-const CSS_TOKEN_SPACE=String.raw`\s*`;
-const CSS_TOKEN_VALUE = '[^;{}]*';
-const CSS_TOKEN_DECLARATION=new RegExp(`(${CSS_TOKEN_NAME})${CSS_TOKEN_SPACE}:(${CSS_TOKEN_VALUE})`,'g');
-
-
-/**
- * The primary worktree of the checkout `dir` belongs to, or null when `dir` is the primary itself or carries no
- * linked-worktree metadata. A linked worktree's `.git` file names `<primary>/.git/worktrees/<name>`, and that
- * directory's `commondir` file names `<primary>/.git` — read from disk, never a git spawn.
- */
-const primaryWorktreeOf=(dir)=>{
-  const gitDir=gitDirOf(dir);
-  if(!gitDir||gitDir===path.join(path.resolve(dir),'.git'))return null;
-  try{
-    const common=path.resolve(gitDir,fs.readFileSync(path.join(gitDir,'commondir'),'utf8').trim());
-    return path.basename(common)==='.git'?path.dirname(common):null;
-  }catch{return null;}
-};
-
-/**
- * The grammar package the runtime at `runtimeRoot` ships: its own packages/grammar while that carries a dist/, or the
- * primary worktree's when this checkout is a linked worktree that never built one — dist/ is untracked, so a land
- * scratch or a lane checkout shares the primary's build (draw-grammar.mjs resolves a lane's grammar the same way).
- * The primary worktree itself, and any standalone checkout, always answer their own: a missing dist on live main
- * stays `missing`.
- */
-function shippedGrammarPackageRoot(runtimeRoot=skillRoot,deps={}){
-  const own=path.join(runtimeRoot,'packages','grammar');
-  if((deps.exists??fs.existsSync)(path.join(own,'dist')))return own;
-  const primary=(deps.primaryOf??primaryWorktreeOf)(runtimeRoot);
-  return primary?path.join(primary,'packages','grammar'):own;
-}
-
-export const defaultGrammarPackageRoot=()=>shippedGrammarPackageRoot(skillRoot);
-
-/** Every `--name: value` declaration outside a comment, in document order, whitespace collapsed. */
-function cssTokenDeclarations(text){
-  const code=String(text).replace(/\/\*[\s\S]*?\*\//g,'');
-  return [...code.matchAll(CSS_TOKEN_DECLARATION)].map(m=>({name:m[1],value:m[2].trim().replace(/\s+/g,' ')}));
-}
-
-/** The families `packages/grammar/scripts/copy-css.mjs` copies: every `src/<family>` that has a `styles.css`. */
-function cssFamilies(packageRoot){
-  const src=path.join(packageRoot,'src');
-  if(!fs.existsSync(src))return [];
-  return fs.readdirSync(src,{withFileTypes:true}).filter(entry=>entry.isDirectory()&&fs.existsSync(path.join(src,entry.name,'styles.css')))
-    .map(entry=>entry.name).sort(byCodeUnit);
-}
-
-/**
- * Compares every family's `--*` token declarations in dist CSS with the source CSS they were copied from.
- * Returns the differing tokens (capped) and how many declarations were compared.
- */
-function compareCssTokens(packageRoot){
-  const differences=[];let compared=0;
-  for(const family of cssFamilies(packageRoot)){
-    const dir=path.join(packageRoot,'src',family);
-    for(const name of fs.readdirSync(dir).filter(file=>file.endsWith('.css')).sort()){
-      const file=`${family}/${name}`;
-      const built=path.join(packageRoot,'dist',family,name);
-      const source=cssTokenDeclarations(fs.readFileSync(path.join(dir,name),'utf8'));
-      if(!fs.existsSync(built)){differences.push({file,token:null,src:`${source.length} declarations`,dist:'file missing'});continue;}
-      const dist=cssTokenDeclarations(fs.readFileSync(built,'utf8'));
-      compared+=source.length;
-      const group=list=>list.reduce((map,{name:token,value})=>map.set(token,[...(map.get(token)??[]),value]),new Map());
-      const [want,have]=[group(source),group(dist)];
-      for(const token of [...new Set([...want.keys(),...have.keys()])].sort(byCodeUnit)){
-        const [a,b]=[want.get(token)??[],have.get(token)??[]];
-        if(a.join('\0')!==b.join('\0'))differences.push({file,token,src:a.join(' | ')||null,dist:b.join(' | ')||null});
-      }
-    }
-  }
-  return {compared,differences:differences.slice(0,TOKEN_DIFF_CAP),differenceCount:differences.length};
-}
-
-/**
- * The nearest package that owns `file` when it is `@starci/grammar`, with whether the file is under its
- * `dist/`. Symlinks are resolved first, so `node_modules/@starci/grammar` of a `file:` consumer lands on
- * the linked package directory.
- */
-function grammarPackageOf(file){
-  let real;
-  try{real=fs.realpathSync(path.resolve(file));}catch{return null;}
-  for(let cursor=path.dirname(real);path.dirname(cursor)!==cursor;cursor=path.dirname(cursor)){
-    const manifest=path.join(cursor,'package.json');
-    if(!fs.existsSync(manifest))continue;
-    if(readJson(manifest)?.name!==GRAMMAR_PACKAGE)return null;
-    const relative=slash(path.relative(cursor,real));
-    return {root:cursor,file:real,inDist:relative==='dist'||relative.startsWith('dist/')};
-  }
-  return null;
-}
-
-/**
- * The freshness of one grammar package's dist. `state` is one of fresh, unverifiable (no source carried,
- * nothing to compare), missing, unstamped, stale, tampered; `ok` is true only for the first two.
- */
-/** The `; <token summary>` tail of a detail string, empty when no token differs. */
-const tokenTail=tokens=>tokens.differenceCount?'; '+tokenSummary(tokens):'';
-
-/** The result for a dist with no valid stamp. */
-const unstampedResult=(result,tokens,evidence,stampFile)=>
-  result('unstamped',`dist/${STAMP_FILE} is ${fs.existsSync(stampFile)?'not a valid build stamp':'missing'}, so this dist was not produced by the current build script${tokenTail(tokens)}`,evidence);
-
-/** The result when the stamp's algorithm or source digest no longer binds the current source, or null. */
-const sourceStaleness=(root,stamp,tokens,evidence,result)=>{
-  if(stamp.algorithm!==DIGEST_ALGORITHM)
-    return result('stale',`the stamp was made with digest ${stamp.algorithm ?? '(none)'}, this check computes ${DIGEST_ALGORITHM}`,evidence);
-  const current=sourceDigest(root);
-  if(stamp.sourceDigest!==current)
-    return result('stale',`dist was built from source ${short(stamp.sourceDigest)} (${stamp.version}, ${stamp.builtAt}) but the source is now ${short(current)}${tokenTail(tokens)}`,{...evidence,sourceDigest:current});
-  return null;
-};
-
-/** The result when the stamp's version/dist digest no longer binds the package, or null. */
-const bindingStaleness=(root,manifest,stamp,tokens,evidence,result)=>{
-  if(stamp.version!==manifest.version)
-    return result('stale',`dist was built as version ${stamp.version} but package.json is ${manifest.version}`,evidence);
-  const built=distDigest(root);
-  if(stamp.distDigest!==built)
-    return result('tampered',`dist files changed after the build (stamp ${short(stamp.distDigest)}, now ${short(built)})${tokenTail(tokens)}`,{...evidence,distDigest:built});
-  if(tokens.differenceCount)return result('tampered',tokenSummary(tokens),evidence);
-  return null;
-};
-
-export function grammarDistStatus(packageRoot=defaultGrammarPackageRoot()){
-  const root=path.resolve(packageRoot);
-  const manifest=readJson(path.join(root,'package.json'));
-  const base={schema:GRAMMAR_DIST_CHECK,root:slash(root),package:manifest?.name??null,version:manifest?.version??null,fix:GRAMMAR_DIST_FIX};
-  const result=(state,detail,extra={})=>({...base,state,ok:state==='fresh'||state==='unverifiable',detail,...extra});
-  if(!manifest)return result('missing',`${slash(root)}/package.json is missing or unreadable`);
-  const hasSource=fs.existsSync(path.join(root,'src'));
-  const distDir=path.join(root,'dist');
-  if(!fs.existsSync(distDir)||!fs.statSync(distDir).isDirectory())
-    return hasSource?result('missing','dist/ does not exist; the package has never been built here'):result('unverifiable','no dist/ and no source: nothing to verify');
-  const stampFile=path.join(distDir,STAMP_FILE);
-  const stamp=readJson(stampFile);
-  const tokens=hasSource?compareCssTokens(root):{compared:0,differences:[],differenceCount:0};
-  const evidence={stamp,tokens};
-  if(!stamp||stamp.schema!==STAMP_SCHEMA)return unstampedResult(result,tokens,evidence,stampFile);
-  if(hasSource){
-    const stale=sourceStaleness(root,stamp,tokens,evidence,result);
-    if(stale)return stale;
-  }
-  const bound=bindingStaleness(root,manifest,stamp,tokens,evidence,result);
-  if(bound)return bound;
-  return hasSource
-    ?result('fresh',`${manifest.name}@${manifest.version} built from source ${short(stamp.sourceDigest)} at ${stamp.builtAt}; ${tokens.compared} token declarations match src`,evidence)
-    :result('unverifiable',`${manifest.name}@${manifest.version} carries no source; its stamp and built files agree`,evidence);
-}
-
-const short=digest=>typeof digest==='string'?digest.replace(/^sha256:/,'').slice(0,12):'(none)';
-const tokenDifferenceText=d=>{
-  if(!d.token)return `${d.file} ${d.dist}`;
-  return `${d.file} ${d.token} src=${d.src??'(absent)'} dist=${d.dist??'(absent)'}`;
-};
-function tokenSummary(tokens){
-  const shown=tokens.differences.slice(0,3).map(tokenDifferenceText);
-  return `${tokens.differenceCount} dist CSS token value(s) differ from src: ${shown.join('; ')}${tokens.differenceCount>3?'; ...':''}`;
-}
-
-/** One line a reader throws or reports when it refuses a dist. Ends with the exact fix. */
-export function grammarDistMessage(status){
-  return `${status.package??GRAMMAR_PACKAGE} dist at ${status.root}/dist is ${status.state}: ${status.detail}. Fix: ${GRAMMAR_DIST_FIX}.`;
-}
-
-/**
- * The refusal for a file a reader is about to read: null when the file is not in a grammar dist or the
- * dist is fresh (or unverifiable), otherwise the status with its message.
- */
-export function grammarDistRefusal(file){
-  const owner=grammarPackageOf(file);
-  if(!owner?.inDist)return null;
-  const status=grammarDistStatus(owner.root);
-  return status.ok?null:{...status,message:grammarDistMessage(status)};
-}

package/runtime/scripts/gates/output.mjs

@@ -1,40 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import {redactBytes} from '../lib/redact.mjs';
-
-/** Print a gate summary, retain an optional scratch copy, and return its measured exit code. */
-export function emitGateSummary(summary, out = null, write = text => process.stdout.write(text)) {
-  const text = `${JSON.stringify(summary, null, 2)}\n`;
-  if (out) {
-    const file = path.resolve(out);
-    fs.mkdirSync(path.dirname(file), {recursive: true});
-    fs.writeFileSync(file, text);
-  }
-  write(text);
-  return summary.exit;
-}
-
-/**
- * Write a check result to scratch, stdout, or the external content-addressed store. A blob is redacted first when its
- * media type is text (scripts/lib/redact.mjs); the printed {sha, redaction} is what a check_runs row cites.
- */
-export async function emitCheckOutput(value, {out = null, blob = false, mediaType = 'application/json',
-  write = text => process.stdout.write(text), put = null} = {}) {
-  if (out && blob) throw new Error('--out and --blob are mutually exclusive');
-  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(String(value));
-  if (out) {
-    const file = path.resolve(out);
-    fs.mkdirSync(path.dirname(file), {recursive: true});
-    fs.writeFileSync(file, bytes);
-    return {out: file};
-  }
-  if (blob) {
-    const putBlob = put ?? (await import('../../engine/db/blob.mjs')).putBlob;
-    const clean = redactBytes(bytes, mediaType);
-    const {sha} = await putBlob(clean.bytes, {mediaType});
-    write(`${JSON.stringify({sha, redaction: clean.redaction})}\n`);
-    return {sha, redaction: clean.redaction};
-  }
-  write(bytes.toString());
-  return {};
-}

package/runtime/scripts/gates/runtime-package-selection.mjs

@@ -1,27 +0,0 @@
-// npm selects the root publish inventory from tracked names and verified generated names, without copying unrelated payload.
-import fs from 'node:fs';
-import path from 'node:path';
-import { containedPath } from '../lib/path-key.mjs';
-import { isLinkLike } from '../api/fs/is-link-like.mjs';
-import { packDryRun } from '../api/npm/pack-dry-run.mjs';
-import { runNpm } from '../api/npm/run-npm.mjs';
-
-/** npm's selected relative names over a fresh placeholder tree; only package/ignore metadata is copied from source. */
-export function packTrackedSelection(root, projection, { tracked, generated = [], env = process.env, run = runNpm } = {}) {
-  fs.mkdirSync(projection);
-  const sourceRoot = path.resolve(root);
-  for (const relative of new Set([...tracked, ...generated])) {
-    const target = containedPath(projection, relative);
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    if (['package.json', 'package-lock.json', 'npm-shrinkwrap.json', '.npmignore', '.gitignore'].includes(path.basename(relative))) {
-      containedPath(sourceRoot, relative);
-      const source = path.resolve(sourceRoot, relative);
-      for (let cursor = source; cursor !== sourceRoot; cursor = path.dirname(cursor)) if (isLinkLike(cursor)) throw new Error(`tracked selection metadata contains a link: ${relative}`);
-      fs.copyFileSync(source, target);
-    } else fs.writeFileSync(target, '');
-  }
-  const listed = packDryRun(projection, { spawn: (args, options) => run(args, { ...options, env }) });
-  if (listed.error || listed.status !== 0) throw new Error('npm could not select the tracked-only root projection');
-  const packed = JSON.parse(listed.stdout);
-  return Array.isArray(packed) && packed.length === 1 && Array.isArray(packed[0].files) ? packed[0].files.map((file) => file.path) : null;
-}

package/runtime/scripts/gates/test-world-run.mjs

@@ -1,252 +0,0 @@
-#!/usr/bin/env node
-// test-world-run.mjs - the test-world run summary (schema starci/test-world-run@1) e2e.verify and integration.verify attach
-// (knowledge/op-gate.yaml proofs.test-world, contract change op-mechanism-proofs).
-//
-//   starci gate test-world --root <app> --project e2e|integration|contract [--tests <path pattern>] [--out <file>]
-//
-// Over the app at --root it records, and `starci kernel settle` re-reads (scripts/kernel/gate-settle.mjs):
-//   harness  the be jest config is @starci/jest-preset's starciJestConfig() (its world projects run on the preset's world
-//            runner: up to min(--maxWorkers, slots) files at once, each in a fresh process on its own data slot) and the world
-//            declaration be/src/tests/world/test-world.config.ts
-//            calls defineTestWorld;
-//   specs    every spec of the project (be/src/tests/{e2e,integration,contract}/**/*.<project>-spec.ts, narrowed by --tests)
-//            takes its world from the library in the layer's form - useTestWorld({ apps }) for e2e, useTestWorld({ modules })
-//            for integration, useSandbox(...) for contract (the real client against the provider's sandbox) - and hand-rolls
-//            none of op-gate.yaml testWorld.forbidden (docker, testcontainers, DataSource, process.env, sleeps); the outage calls
-//            (cut, restore, during, latency) are counted;
-//   run      the managed `npm run test:<project>` with jest's --json report: exit, totals, failed and skipped tests.
-// Our own stack runs real and only third-party SaaS is faked at the network edge: the library owns that, a spec never does.
-// Exit 0 green, 1 a finding or a red run, 2 the summary could not be built.
-import fs from 'node:fs';
-import path from 'node:path';
-import { runNpm } from '../api/npm/run-npm.mjs';
-import { fileURLToPath } from 'node:url';
-import { posixPath } from '../lib/path-key.mjs';
-import { valueFlags } from '../lib/cli-arg.mjs';
-import { isMain } from '../lib/is-main.mjs'; import { walkFiles } from '../lib/walk.mjs';
-import { opGateRules } from '../lib/op-gate.mjs';
-import { makeTempDir } from '../api/fs/make-temp-dir.mjs';
-import { emitGateSummary } from './output.mjs';
-
-export const TEST_WORLD_RUN_SCHEMA = 'starci/test-world-run@1';
-const WORLD_PROJECTS = Object.freeze({
-  e2e: { dir: 'be/src/tests/e2e', suffix: '.e2e-spec.ts', mode: 'apps' },
-  integration: { dir: 'be/src/tests/integration', suffix: '.integration-spec.ts', mode: 'modules' },
-  contract: { dir: 'be/src/tests/contract', suffix: '.contract-spec.ts', mode: 'sandbox' },
-});
-const runtimeRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-const JEST_CONFIGS = ['be/jest.config.js', 'be/jest.config.cjs', 'be/jest.config.ts', 'jest.config.js', 'jest.config.cjs', 'jest.config.ts'];
-const DECLARATION = 'be/src/tests/world/test-world.config.ts';
-const USAGE = 'usage: starci gate test-world --root <app> --project e2e|integration|contract [--tests <path pattern>] [--out <file>]';
-
-/** op-gate.yaml testWorld: {required[], forbidden[], outage[]}. */
-export function testWorldRules(runtime = runtimeRoot) {
-  return opGateRules(runtime, 'testWorld');
-}
-
-/** The harness of the app: {jestConfig, preset, declaration, defineTestWorld}. */
-function harnessOf(root) {
-  const jestConfig = JEST_CONFIGS.find((rel) => fs.existsSync(path.join(root, rel))) ?? null;
-  const text = jestConfig ? fs.readFileSync(path.join(root, jestConfig), 'utf8') : '';
-  const declared = fs.existsSync(path.join(root, DECLARATION)) ? fs.readFileSync(path.join(root, DECLARATION), 'utf8') : null;
-  return { jestConfig, preset: /@starci\/jest-preset/.test(text) && /starciJestConfig\s*\(/.test(text), declaration: declared === null ? null : DECLARATION, defineTestWorld: /defineTestWorld\s*\(/.test(declared ?? '') };
-}
-
-/** The `{ ... }` argument text of each useTestWorld( call, balanced over braces. */
-function useTestWorldArgs(text) {
-  const out = [];
-  const re = /useTestWorld\s*\(/g;
-  let m;
-  while ((m = re.exec(text))) {
-    let depth = 0, i = m.index + m[0].length, start = i;
-    for (; i < text.length; i += 1) {
-      const c = text[i];
-      if (c === '(' || c === '{' || c === '[') depth += 1;
-      else if (c === ')' || c === '}' || c === ']') {
-        if (depth === 0) break;
-        depth -= 1;
-      }
-    }
-    out.push(text.slice(start, i));
-  }
-  return out;
-}
-
-/** One spec judged: {path, useTestWorld, modes[], outage, forbidden[]}; `sandbox` is a mode when the spec calls useSandbox. */
-export function judgeSpec(rel, text, rules) {
-  const args = useTestWorldArgs(text);
-  const modes = [...new Set(args.flatMap((a) => ['apps', 'modules'].filter((k) => new RegExp(String.raw`(^|[{,\s])${k}\s*:`).test(a))))];
-  const sandbox = /useSandbox\s*\(/.test(text);
-  if (sandbox) modes.push('sandbox');
-  // A comment may name a forbidden word to explain its absence; only code counts.
-  const code = text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/[^\n\r\u2028\u2029]*/gm, '$1');
-  return { path: rel, useTestWorld: args.length > 0 || sandbox, modes, outage: rules.outage.reduce((n, needle) => n + code.split(needle).length - 1, 0),
-    forbidden: rules.forbidden.filter((needle) => code.includes(needle)) };
-}
-
-/** The spec files of a world project under the app root (app-relative POSIX paths), narrowed by a --tests pattern. */
-export function specsOf(root, project, tests = null) {
-  const def = WORLD_PROJECTS[project];
-  const dir = path.join(root, def.dir);
-  if (!fs.existsSync(dir)) return [];
-  const narrow = tests ? new RegExp(tests) : null;
-  return walkFiles(dir, { sorted: true, exclude: (name, full, entry) => entry.isDirectory() && name === 'node_modules' })
-    .map((file) => posixPath(path.relative(root, file)))
-    .filter((rel) => rel.endsWith(def.suffix) && (!narrow || narrow.test(rel)));
-}
-
-const RUN_COUNTS = Object.freeze(['total', 'passed', 'failed', 'skipped', 'files', 'failedFiles']);
-const JEST_COUNTS = Object.freeze(['numTotalTests', 'numPassedTests', 'numFailedTests', 'numPendingTests', 'numTodoTests',
-  'numTotalTestSuites', 'numPassedTestSuites', 'numFailedTestSuites', 'numPendingTestSuites', 'numRuntimeErrorTestSuites']);
-
-/** Reject an incomplete or inconsistent required test measurement without coercing reported counters. */
-export function testRunCountsError(run) {
-  if (!run || RUN_COUNTS.some((key) => !Number.isSafeInteger(run[key]) || run[key] < 0)) return 'test counters must be non-negative safe integers';
-  if (run.total !== run.passed + run.failed + run.skipped || run.failedFiles > run.files) return 'test counters do not describe a complete run';
-  return null;
-}
-
-/** The shape checks of the report and its process: an error string or null. */
-const reportShapeError = (report, run) => {
-  if (run?.error || run?.signal || !Number.isSafeInteger(run?.status) || run.status < 0) {
-    const detail = run?.error?.message ?? run?.signal ?? `exit ${run?.status ?? 'unknown'}`;
-    return `jest did not complete: ${detail}`;
-  }
-  if (!report || typeof report !== 'object' || Array.isArray(report) || !Array.isArray(report.testResults)) return 'jest wrote no valid --json report';
-  if (JEST_COUNTS.some((key) => !Number.isSafeInteger(report[key]) || report[key] < 0)) return 'jest counters must be non-negative safe integers';
-  if (typeof report.success !== 'boolean' || typeof report.wasInterrupted !== 'boolean') return 'jest result is missing completion flags';
-  if (report.wasInterrupted || report.runExecError) return 'jest reports an interrupted or incomplete run';
-  if (report.numTotalTestSuites !== report.numPassedTestSuites + report.numFailedTestSuites + report.numPendingTestSuites
-    || report.numRuntimeErrorTestSuites > report.numFailedTestSuites || report.testResults.length !== report.numTotalTestSuites)
-    return 'jest suite counters do not describe a complete run';
-  return null;
-};
-
-/** The assertion and suite tallies of a valid report: {totals, suites}, or {error}. */
-const suiteShapeError = (suite) => !suite || !['passed', 'failed', 'skipped', 'focused'].includes(suite.status) || !Array.isArray(suite.assertionResults)
-  ? 'jest wrote an invalid suite result' : null;
-
-const focusedSuiteError = (suite, report) => suite.status === 'focused'
-  && (report.numPendingTests === 0 || !suite.assertionResults.some(a => ['pending', 'skipped', 'disabled'].includes(a?.status)))
-  ? 'jest focused suite reports no pending assertion' : null;
-
-const tallyAssertion = (assertion, totals) => {
-  if (assertion?.status === 'passed') totals.passed += 1;
-  else if (assertion?.status === 'failed') totals.failed += 1;
-  else if (['pending', 'todo', 'skipped', 'disabled'].includes(assertion?.status)) totals.skipped += 1;
-  else return 'jest wrote an invalid assertion result';
-  return null;
-};
-
-const tallySuites = (report) => {
-  const totals = { passed: 0, failed: 0, skipped: 0 }, suites = { passed: 0, failed: 0, skipped: 0 };
-  for (const suite of report.testResults) {
-    const shapeError = suiteShapeError(suite);
-    if (shapeError) return { error: shapeError };
-    const focusedError = focusedSuiteError(suite, report);
-    if (focusedError) return { error: focusedError };
-    suites[suite.status === 'focused' ? 'passed' : suite.status] += 1;
-    for (const assertion of suite.assertionResults) {
-      const assertionError = tallyAssertion(assertion, totals);
-      if (assertionError) return { error: assertionError };
-    }
-  }
-  return { totals, suites };
-};
-
-/** Validate the Jest JSON and its real process result before any producer can call the measurement clean. */
-export function jestRunError(report, run) {
-  const shapeError = reportShapeError(report, run);
-  if (shapeError) return shapeError;
-  const tally = tallySuites(report);
-  if (tally.error) return tally.error;
-  const { totals, suites } = tally;
-  const countsError = testRunCountsError(reduceJest(report));
-  if (countsError) return countsError;
-  if (suites.passed !== report.numPassedTestSuites || suites.failed !== report.numFailedTestSuites
-    || suites.skipped !== report.numPendingTestSuites) return 'jest suite counters disagree with its results';
-  if (totals.passed !== report.numPassedTests || totals.failed !== report.numFailedTests
-    || totals.skipped !== report.numPendingTests + report.numTodoTests) return 'jest assertion counters disagree with its results';
-  const measuredFailure = report.numFailedTests > 0 || report.numFailedTestSuites > 0;
-  // A normal failed assertion retains its typed finding; a nonzero process with a clean report never passes.
-  if (run.status !== 0 && !measuredFailure) return `jest exited ${run.status} without a reported test failure`;
-  if (!report.success && !measuredFailure) return 'jest reports an unsuccessful run without a reported test failure';
-  if (report.success && measuredFailure) return 'jest success contradicts its failed tests or suites';
-  return null;
-}
-
-/** Jest's totals and executed suite files; testFiles are relative to root when supplied. */
-export function reduceJest(report, root = null) {
-  const suites = Array.isArray(report?.testResults) ? report.testResults : [];
-  const failures = [];
-  for (const file of suites) for (const a of Array.isArray(file?.assertionResults) ? file.assertionResults : []) {
-    if (a.status === 'failed') failures.push({ file: posixPath(String(file.name ?? '')), test: a.fullName ?? a.title, message: String(a.failureMessages?.[0] ?? '').split('\n')[0].slice(0, 300) });
-  }
-  return { total: report?.numTotalTests ?? 0, passed: report?.numPassedTests ?? 0, failed: report?.numFailedTests ?? 0,
-    skipped: (report?.numPendingTests ?? 0) + (report?.numTodoTests ?? 0), files: report?.numTotalTestSuites ?? 0, failedFiles: report?.numFailedTestSuites ?? 0, failures: failures.slice(0, 100),
-    testFiles: suites.filter((suite) => (suite.assertionResults ?? []).some((assertion) => ['passed', 'failed'].includes(assertion.status)))
-      .map((suite) => suite.name ?? suite.testFilePath).filter((file) => typeof file === 'string')
-      .map((file) => posixPath(root ? path.relative(root, path.resolve(root, file)) : file)) };
-}
-
-/** Run the managed `npm run test:<project>` with jest's JSON report; {command, exit, ...reduceJest, error}. */
-function runWorldProject(root, project, tests = null, { npm = runNpm } = {}) {
-  const outDir = makeTempDir('starci-test-world-run-');
-  const outFile = path.join(outDir, 'jest.json');
-  const args = ['run', `test:${project}`, '--', '--json', `--outputFile=${outFile}`, ...(tests ? ['--testPathPattern', tests] : [])];
-  const run = npm(args, { cwd: root, maxBuffer: 512 * 1024 * 1024 });
-  let report = null;
-  try { report = JSON.parse(fs.readFileSync(outFile, 'utf8')); } catch { report = null; }
-  try { fs.rmSync(outFile, { force: true }); fs.rmdirSync(outDir); } catch { /* a temp file of this run */ }
-  return { command: `npm ${args.filter((a) => !a.startsWith('--outputFile=')).join(' ')}`, exit: run.status ?? null,
-    ...(report ? reduceJest(report, root) : { total: 0, passed: 0, failed: 0, skipped: 0, files: 0, failedFiles: 0, failures: [] }),
-    error: jestRunError(report, run) };
-}
-
-/** The findings of a summary (harness, specs and run), each {rule, path, message}. */
-export function testWorldFindings(summary) {
-  const out = [];
-  const h = summary.harness ?? {};
-  if (!h.preset) out.push({ rule: 'preset-missing', path: h.jestConfig, message: 'the be jest config is not @starci/jest-preset starciJestConfig(): its world projects do not run on the world runner' });
-  if (!h.declaration || !h.defineTestWorld) out.push({ rule: 'declaration-missing', path: DECLARATION, message: 'no world declaration calling defineTestWorld' });
-  if (!(summary.specs ?? []).length) out.push({ rule: 'no-specs', path: WORLD_PROJECTS[summary.project]?.dir ?? null, message: `no ${summary.project} spec was selected` });
-  const mode = WORLD_PROJECTS[summary.project]?.mode;
-  for (const spec of summary.specs ?? []) {
-    const form = mode === 'sandbox' ? 'useSandbox(...)' : `useTestWorld({ ${mode} })`;
-    if (!spec.useTestWorld) out.push({ rule: 'use-test-world-missing', path: spec.path, message: 'the spec never calls useTestWorld or useSandbox: its world is hand-rolled' });
-    else if (mode && !spec.modes.includes(mode)) out.push({ rule: 'layer-mode', path: spec.path, message: `a ${summary.project} spec calls ${form}; it uses ${spec.modes.join(', ') || 'neither apps nor modules'}` });
-    for (const needle of spec.forbidden) out.push({ rule: 'hand-rolled', path: spec.path, message: `the spec uses ${needle}: infrastructure belongs to @starci/test-world` });
-  }
-  return out;
-}
-
-function buildTestWorldRun({ root, project, tests = null, rules = testWorldRules(), npm = runNpm, run = true }) {
-  if (!WORLD_PROJECTS[project]) throw new Error(`--project must be one of ${Object.keys(WORLD_PROJECTS).join(', ')}; ${USAGE}`);
-  const abs = path.resolve(root);
-  const specs = specsOf(abs, project, tests).map((rel) => judgeSpec(rel, fs.readFileSync(path.join(abs, rel), 'utf8'), rules));
-  const summary = { schema: TEST_WORLD_RUN_SCHEMA, at: new Date().toISOString(), root: posixPath(abs), project, tests, harness: harnessOf(abs), specs,
-    outageCalls: specs.reduce((n, s) => n + s.outage, 0), run: null, findings: [], exit: 2 };
-  summary.findings = testWorldFindings(summary);
-  summary.run = run ? runWorldProject(abs, project, tests, { npm }) : null;
-  const red = !summary.run || summary.run.error || summary.run.exit !== 0 || summary.run.failed > 0 || summary.run.skipped > 0 || summary.run.total === 0;
-  if (summary.run?.error) summary.exit = 2;
-  else summary.exit = summary.findings.length || red ? 1 : 0;
-  return summary;
-}
-
-function parseTestWorldArgs(argv) {
-  const opts = { root: null, project: null, tests: null, out: null, ...valueFlags(argv, ['--root', '--project', '--tests', '--out'], USAGE) };
-  if (!opts.project) throw new Error(`--project is required; ${USAGE}`);
-  return opts;
-}
-
-if (isMain(import.meta.url)) {
-  try {
-    const opts = parseTestWorldArgs(process.argv.slice(2));
-    const summary = buildTestWorldRun({ root: opts.root ?? process.cwd(), project: opts.project, tests: opts.tests });
-    process.exitCode = emitGateSummary(summary, opts.out);
-  } catch (error) {
-    process.stderr.write(`test-world-run: ${error.message}\n`);
-    process.exitCode = 2;
-  }
-}