@starci/hfs 4.7.32 → 4.7.34

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

@@ -0,0 +1,206 @@
+// 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/runtime-package-selection.mjs

@@ -0,0 +1,27 @@
+// 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

@@ -0,0 +1,254 @@
+#!/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';
+
+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 });
+    const text = `${JSON.stringify(summary, null, 2)}\n`;
+    if (opts.out) { fs.mkdirSync(path.dirname(path.resolve(opts.out)), { recursive: true }); fs.writeFileSync(path.resolve(opts.out), text); }
+    process.stdout.write(text);
+    process.exitCode = summary.exit;
+  } catch (error) {
+    process.stderr.write(`test-world-run: ${error.message}\n`);
+    process.exitCode = 2;
+  }
+}