eyeprolog 1.6.28 → 1.6.30

package/index.d.ts

@@ -214,6 +214,7 @@ export type BuiltinHandler =
 export class BuiltinRegistry {
   constructor();
   defs: Map<string, BuiltinDefinition>;
+  byName: Map<string, Map<number, BuiltinDefinition>>;
   eyePrologLibrary?: boolean;
   add(name: string, arity: number, handler: BuiltinHandler, options?: Partial<BuiltinDefinition>): this;
   get(name: string, arity: number): BuiltinDefinition | null;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.6.28",
+  "version": "1.6.30",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",

package/src/ARCHITECTURE.md

@@ -39,6 +39,10 @@ Verification walks the supplied certificate and checks source-clause steps again
 the parsed `Program`; it does not call the solver to rediscover the proof.
 Built-in and abstract library nodes are explicit trust boundaries, while expanded
 proofs expose bundled Prolog-library clauses as ordinary source steps.
+Proof nodes share the runtime terms they resolve. Runtime terms are structurally
+immutable, so a ground subtree already is the snapshot a proof needs, and
+`resolveForProof` copies only the ancestors of an argument that variable
+resolution actually changed. Nothing anywhere may rewrite a term in place.
 
 `iso.js` and `program.js` remain facade modules for their existing exports, so
 this refactor does not change the public JavaScript API.
@@ -116,6 +120,16 @@ construct native propagation/search plans while their Prolog modules retain
 validation, residual constraints, and portable fallbacks. A cleaner file layout
 is not worth a runtime regression, so such splits must retain benchmark parity.
 
+Hot paths follow one allocation discipline: the state a walk or a comparison
+needs only for its hard case -- a cycle guard, a traversal stack, a variable
+pairing -- is allocated when that case actually appears rather than on entry.
+`deref`, `variantTerms`, and `goalHeadTermsCannotMatch` therefore decide the
+shallow, acyclic, scalar-argument case, which is the overwhelming majority of
+their calls, without allocating anything. A key a table or an index derives
+from a term is built once into one fragment array for the whole term: a key
+composed from a key per subterm makes recording one answer quadratic in that
+answer's own size.
+
 Performance claims use `npm test`'s own elapsed time across the full corpus,
 not predicate, inference, or host-call counts as a substitute for elapsed
 time, and not a separate wall-clock benchmark harness.

package/src/explain.js

@@ -131,12 +131,15 @@ function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active, de
       const id = nextFreshId();
       const freshVariables = new Map();
       const freshHead = freshTerm(clause.head, id, freshVariables);
-      const freshBody = clause.body.map((term) => freshTerm(term, id, freshVariables));
       const next = env.clone();
       if (!unify(goal, freshHead, next)) continue;
 
+      // Rename the body only once the head has matched. The shared variable
+      // map carries the head's renamings, so a body renamed now is the same
+      // body renaming as before -- a clause rejected on its head simply no
+      // longer pays for one.
+      const freshBody = clause.body.map((term) => freshTerm(term, id, freshVariables));
       const substitutions = collectClauseSubstitutions(clause, freshHead, freshBody);
-      const bindings = resolvedSubstitutions(substitutions, next);
 
       if (freshBody.length === 0) {
         yield {
@@ -146,7 +149,10 @@ function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active, de
             method: sourceMethod(clause, 'fact'),
             sourceHead: clause.head,
             sourceBody: [],
-            bindings,
+            // A fact binds everything it is going to bind at head unification.
+            // A rule's substitutions are only final once its body is proved,
+            // so that branch resolves them against the proving environment.
+            bindings: resolvedSubstitutions(substitutions, next),
             children: [],
           },
         };
@@ -254,7 +260,17 @@ function builtinChildren(program, goal, env, depth, maxDepth, registry, active,
 }
 
 function activeVariant(goal, env, active) {
-  return active.some((entry) => variantTerms(goal, env, entry.goal, entry.env));
+  // Only a goal for the same predicate can be a variant of this one, so reject
+  // the rest on their functor instead of on a structural comparison. Scan from
+  // the innermost entry outwards: a replay that is about to cycle repeats its
+  // nearest ancestor, not the goal the whole replay started from.
+  for (let index = active.length - 1; index >= 0; index--) {
+    const entry = active[index];
+    const candidate = entry.goal;
+    if (candidate.type !== goal.type || candidate.name !== goal.name || candidate.arity !== goal.arity) continue;
+    if (variantTerms(goal, env, candidate, entry.env)) return true;
+  }
+  return false;
 }
 
 function sourceMethod(clause, kind) {

package/src/iso.js

@@ -3302,10 +3302,15 @@ import { isBuiltin, arithmeticComparison } from './iso-arithmetic.js';
 export class BuiltinRegistry {
   constructor() {
     this.defs = new Map();
+    // `defs` stays keyed by the printable predicate indicator because callers
+    // enumerate the catalog from it. Lookups, though, happen at least once per
+    // goal on the solver's hot path, so they go through a name/arity index
+    // rather than formatting -- and allocating -- an indicator string each time.
+    this.byName = new Map();
   }
 
   add(name, arity, handler, options = {}) {
-    this.defs.set(`${name}/${arity}`, {
+    const def = {
       name,
       arity,
       handler,
@@ -3317,16 +3322,25 @@ export class BuiltinRegistry {
       fallbackWhenNotReady: options.fallbackWhenNotReady ?? false,
       shouldUse: options.shouldUse ?? null,
       eyePrologLibrary: options.eyePrologLibrary ?? false,
-    });
+    };
+    this.defs.set(`${name}/${arity}`, def);
+    let byArity = this.byName.get(name);
+    if (byArity == null) this.byName.set(name, byArity = new Map());
+    byArity.set(arity, def);
     return this;
   }
 
   get(name, arity) {
-    return this.defs.get(`${name}/${arity}`) ?? null;
+    return this.byName.get(name)?.get(arity) ?? null;
   }
 
   remove(name, arity) {
     this.defs.delete(`${name}/${arity}`);
+    const byArity = this.byName.get(name);
+    if (byArity != null) {
+      byArity.delete(arity);
+      if (byArity.size === 0) this.byName.delete(name);
+    }
     return this;
   }
 }

package/src/solver.js

@@ -3223,13 +3223,13 @@ function rememberGroundChainSuccess(solver, seen) {
 
 function rememberMemoAnswer(entry, goal, env) {
   const variables = new Map();
-  const answerKeys = [];
-  const answerArgs = goal.args.map((arg) => {
-    const answer = copyResolvedWithKey(arg, env, variables);
-    answerKeys.push(answer.key);
-    return answer.term;
-  });
-  const key = answerKeys.join('\x1f');
+  const keyParts = [];
+  const answerArgs = new Array(goal.args.length);
+  for (let position = 0; position < goal.args.length; position++) {
+    if (position > 0) keyParts.push('\x1f');
+    answerArgs[position] = copyResolvedWithKey(goal.args[position], env, variables, keyParts);
+  }
+  const key = keyParts.join('');
   if (entry.answerKeys.has(key)) return;
   entry.answerKeys.add(key);
   const answerIndex = entry.answers.length;
@@ -3373,7 +3373,13 @@ function canonicalTermKey(term, env, variables) {
   return key.join('');
 }
 
-function copyResolvedWithKey(term, env, variables) {
+// Copies one answer argument and appends its variant key to `keyParts`.
+// Writing fragments into one shared array keeps a tabled answer linear in its
+// own size: returning a key per subterm instead made every enclosing term
+// rebuild the key of everything below it, so a predicate tabling long lists --
+// a Collatz trajectory, a transitive closure path -- paid quadratic string
+// building for each answer it recorded.
+function copyResolvedWithKey(term, env, variables, keyParts) {
   const value = derefForLocal(term, env);
   if (value.type === 'var') {
     let id = variables.get(value.name);
@@ -3381,19 +3387,24 @@ function copyResolvedWithKey(term, env, variables) {
       id = variables.size;
       variables.set(value.name, id);
     }
-    return { term: termModuleCache.variable(value.name), key: `var:${id}` };
+    keyParts.push('var:', id);
+    return termModuleCache.variable(value.name);
   }
   if (!value.args?.length) {
     // Atomic terms are immutable in the solver.  Share them across table
     // answers instead of allocating a fresh host object for every cell of a
     // large closure such as tc/2.
-    return { term: value, key: `${value.type}:${value.name}` };
+    keyParts.push(value.type, ':', value.name);
+    return value;
   }
-  const children = value.args.map((arg) => copyResolvedWithKey(arg, env, variables));
-  return {
-    term: termModuleCache.compound(value.name, children.map((child) => child.term)),
-    key: `${value.type}:${value.name}(${children.map((child) => child.key).join(',')})`,
-  };
+  keyParts.push(value.type, ':', value.name, '(');
+  const children = new Array(value.args.length);
+  for (let index = 0; index < value.args.length; index++) {
+    if (index > 0) keyParts.push(',');
+    children[index] = copyResolvedWithKey(value.args[index], env, variables, keyParts);
+  }
+  keyParts.push(')');
+  return termModuleCache.compound(value.name, children);
 }
 
 // Avoid circular import surprises in older Node loaders.

package/src/term.js

@@ -19,6 +19,10 @@ const ATTRIBUTED_ENV_FLATTEN_DEPTH = 256;
 // binding is just as safe to cache as a present one. Negative lookups are
 // especially common while tabling and constraint code probes fresh variables.
 const ENV_UNBOUND = Symbol('environment-unbound');
+// Dereferencing walks a binding chain. Chains are one or two hops in practice
+// and cyclic only when a term was built incorrectly, so the cycle guard starts
+// recording visited names only after a chain is long enough to be suspect.
+const DEREF_CYCLE_GUARD_HOPS = 16;
 // Runtime terms are structurally immutable: environments hold bindings beside
 // them rather than rewriting their argument arrays. Cache only the syntactic
 // variable names; binding reachability is still checked against each Env.
@@ -885,20 +889,34 @@ class SolverEnv extends Env {
 }
 
 export function deref(term, env) {
-  // Follow variable bindings until a non-variable term is reached. The seen set
-  // protects readback from accidental cycles in partially constructed terms.
+  // Follow variable bindings until a non-variable term is reached. This is the
+  // most frequently executed function in the runtime, so nothing it needs only
+  // occasionally may be paid for on every call: most terms are not variables
+  // at all, most environments declare no DCG locals, and almost every chain is
+  // one or two hops long.
+  if (term?.type !== VAR || env == null) return term;
+  // A live compiler-proven DCG local is the current unbound representative.
+  // No older Env layer can contain a binding for it. Both Env representations
+  // answer that question from this one set, so read it once per call instead
+  // of dispatching a method call per hop.
+  const locals = env._localVariables;
   let current = term;
   let seen = null;
-  while (current?.type === VAR) {
-    // A live compiler-proven DCG local is the current unbound representative.
-    // No older Env layer can contain a binding for it.
-    if (env?.isLocalVariable?.(current.name) === true) break;
-    const next = env?.get(current.name);
+  let hops = 0;
+  do {
+    if (locals != null && locals.has(current.name)) break;
+    const next = env.get(current.name);
     if (next === undefined) break;
-    if (seen?.has(current.name)) break;
-    (seen ??= new Set()).add(current.name);
+    // The seen set protects readback from accidental cycles in partially
+    // constructed terms. A cycle still terminates the walk once the guard
+    // starts recording, so ordinary chains never allocate it.
+    if (++hops > DEREF_CYCLE_GUARD_HOPS) {
+      if (seen == null) seen = new Set();
+      if (seen.has(current.name)) break;
+      seen.add(current.name);
+    }
     current = next;
-  }
+  } while (current?.type === VAR);
   return current;
 }
 
@@ -1519,40 +1537,65 @@ export function termSignature(term) {
   return term?.type === COMPOUND ? `${term.name}/${term.arity}` : null;
 }
 
-export function variantTerms(left, leftEnv, right, rightEnv, pairs = new Map(), reverse = new Map()) {
-  // Variant checks sit on the recursive-call hot path. Use an explicit work
-  // stack so long lists do not consume the JavaScript call stack.
-  const pending = [[left, right]];
-  const seen = new WeakMap();
-  while (pending.length > 0) {
-    [left, right] = pending.pop();
-    left = deref(left, leftEnv);
-    right = deref(right, rightEnv);
-    if (left.type === VAR || right.type === VAR) {
-      if (left.type !== VAR || right.type !== VAR) return false;
-      if (pairs.has(left.name) || reverse.has(right.name)) {
-        if (pairs.get(left.name) !== right.name || reverse.get(right.name) !== left.name) return false;
-        continue;
+export function variantTerms(left, leftEnv, right, rightEnv, pairs = null, reverse = null) {
+  // Variant checks sit on the recursive-call hot path, where the usual answer
+  // is "not a variant" and the usual reason is one mismatched scalar argument.
+  // Settle scalar and variable arguments as they are derefed and defer only
+  // compound ones to an explicit work stack, which long lists still need so
+  // they do not consume the JavaScript call stack. The stack, the variable
+  // pairing, and the cycle guard are therefore allocated only once something
+  // actually needs them, which a rejected comparison usually never does.
+  let leftStack = null;
+  let rightStack = null;
+  let seen = null;
+  let current = deref(left, leftEnv);
+  let other = deref(right, rightEnv);
+  for (;;) {
+    if (current.type === VAR || other.type === VAR) {
+      if (current.type !== VAR || other.type !== VAR) return false;
+      pairs ??= new Map();
+      reverse ??= new Map();
+      const forward = pairs.get(current.name);
+      const backward = reverse.get(other.name);
+      if (forward !== undefined || backward !== undefined) {
+        if (forward !== other.name || backward !== current.name) return false;
+      } else {
+        pairs.set(current.name, other.name);
+        reverse.set(other.name, current.name);
+      }
+    } else if (current.type !== other.type || current.arity !== other.arity) {
+      return false;
+    } else if (current.type === NUMBER ? !sameNumberValue(current.name, other.name) : current.name !== other.name) {
+      return false;
+    } else if (current.type === COMPOUND && seen?.get(current)?.has(other) !== true) {
+      let recorded = false;
+      for (let i = 0; i < current.arity; i++) {
+        const leftArg = deref(current.args[i], leftEnv);
+        const rightArg = deref(other.args[i], rightEnv);
+        if (leftArg.type !== COMPOUND && rightArg.type !== COMPOUND
+          && leftArg.type !== VAR && rightArg.type !== VAR) {
+          if (leftArg.type !== rightArg.type) return false;
+          if (leftArg.type === NUMBER
+            ? !sameNumberValue(leftArg.name, rightArg.name)
+            : leftArg.name !== rightArg.name) return false;
+          continue;
+        }
+        if (!recorded) {
+          recorded = true;
+          let rights = (seen ??= new WeakMap()).get(current);
+          if (rights == null) seen.set(current, rights = new WeakSet());
+          rights.add(other);
+          leftStack ??= [];
+          rightStack ??= [];
+        }
+        leftStack.push(leftArg);
+        rightStack.push(rightArg);
       }
-      pairs.set(left.name, right.name);
-      reverse.set(right.name, left.name);
-      continue;
-    }
-
-    if (left.type !== right.type || left.arity !== right.arity) return false;
-    if (left.type === NUMBER ? !sameNumberValue(left.name, right.name) : left.name !== right.name) return false;
-    if (left.type !== COMPOUND) continue;
-
-    let rights = seen.get(left);
-    if (rights?.has(right)) continue;
-    if (rights == null) {
-      rights = new WeakSet();
-      seen.set(left, rights);
     }
-    rights.add(right);
-    for (let i = left.arity - 1; i >= 0; i--) pending.push([left.args[i], right.args[i]]);
+    if (leftStack == null || leftStack.length === 0) return true;
+    current = leftStack.pop();
+    other = rightStack.pop();
   }
-  return true;
 }
 
 

package/test/parallel-tasks.mjs

@@ -0,0 +1,113 @@
+// A small ordered worker pool for the suites that do the same work once per
+// file: run every example, prove every example, check every packaged proof.
+//
+// Results are reported in task order however the workers finish, so a parallel
+// suite numbers its tests exactly as the sequential one did and a failure still
+// stops the run at the same test. Each suite compares inside its worker, so
+// only a name, an elapsed time, an optional failure, and a small plain-data
+// value cross the thread boundary.
+import os from 'node:os';
+import { Worker } from 'node:worker_threads';
+
+export async function runTasksInParallel({
+  names,
+  workerUrl,
+  workerData,
+  message = {},
+  maxWorkers,
+  runLocally,
+  onResult,
+}) {
+  if (names.length === 0) return;
+  const parallelism = os.availableParallelism?.() ?? os.cpus().length;
+  const workerCount = Math.min(names.length, Math.max(1, Math.min(maxWorkers, parallelism - 1)));
+  if (workerCount === 1) {
+    for (const name of names) {
+      const startedAt = performance.now();
+      try {
+        const value = runLocally(name) ?? null;
+        onResult(name, { ms: Math.round(performance.now() - startedAt), value });
+      } catch (error) {
+        onResult(name, { ms: Math.round(performance.now() - startedAt), error });
+      }
+    }
+    return;
+  }
+
+  const completedResults = new Map();
+  let nextTask = 0;
+  let nextReport = 0;
+  let completed = 0;
+  let settled = false;
+
+  await new Promise((resolve, reject) => {
+    const workers = Array.from({ length: workerCount }, () => new Worker(workerUrl, { workerData }));
+
+    const stopWorkers = () => Promise.all(workers.map((worker) => worker.terminate()));
+
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      stopWorkers().finally(() => reject(error));
+    };
+
+    const finish = () => {
+      if (settled || completed !== names.length || nextReport !== names.length) return;
+      settled = true;
+      stopWorkers().then(() => resolve(), reject);
+    };
+
+    const reportReady = () => {
+      try {
+        while (completedResults.has(nextReport)) {
+          const result = completedResults.get(nextReport);
+          completedResults.delete(nextReport);
+          onResult(names[nextReport], result);
+          nextReport++;
+        }
+      } catch (error) {
+        fail(error);
+      }
+    };
+
+    const assign = (worker) => {
+      if (nextTask >= names.length || settled) return;
+      worker.postMessage({ ...message, id: nextTask, name: names[nextTask++] });
+    };
+
+    for (const worker of workers) {
+      worker.on('message', ({ id, ms, error, value }) => {
+        if (settled) return;
+        completedResults.set(id, {
+          ms,
+          value: value ?? null,
+          error: error == null ? null : Object.assign(new Error(error.message), { stack: error.stack }),
+        });
+        completed++;
+        reportReady();
+        assign(worker);
+        finish();
+      });
+      worker.on('error', fail);
+      assign(worker);
+    }
+  });
+}
+
+// The worker side of the same protocol. `runTask` receives the posted message
+// and may return a plain-data value for the pool to hand back with the result.
+export function serveTasks(parentPort, runTask) {
+  parentPort.on('message', (task) => {
+    const startedAt = performance.now();
+    try {
+      const value = runTask(task) ?? null;
+      parentPort.postMessage({ id: task.id, ms: Math.round(performance.now() - startedAt), error: null, value });
+    } catch (error) {
+      parentPort.postMessage({
+        id: task.id,
+        ms: Math.round(performance.now() - startedAt),
+        error: { message: error?.message ?? String(error), stack: error?.stack ?? String(error) },
+      });
+    }
+  });
+}

package/test/regression/cases-white-box.mjs

@@ -6,7 +6,7 @@ import { spawnSync } from 'node:child_process';
 import * as publicApi from '../../src/index.js';
 import { Env, Program, atom, compound, copyResolved, flattenConjunction, listFromItems, numberTerm, parseProgramText, properListItems, stringTerm, termIsGround, termToString, unify, variable, variantTerms } from '../../src/index.js';
 import { ISO_OPERATOR_DEFINITIONS, parseGoalText, parseNumberTokenText } from '../../src/parser.js';
-import { compareTerms } from '../../src/term.js';
+import { compareTerms, deref } from '../../src/term.js';
 import { checkProofDocument, verdict } from '../../src/check-proof.js';
 import { formatTermForWrite } from '../../src/write.js';
 import { selectClauseCandidates } from '../../src/program.js';
@@ -1065,5 +1065,66 @@ path(X, Z) :- edge(X, Y), path(Y, Z).
         assertIncludes(result.stdout, 'collatzTrajectory(1, [1]).\n', 'stdout');
       },
     },
+    {
+      // The hot paths below settle the ordinary case without allocating the
+      // traversal state the hard case needs. These cases pin the hard cases:
+      // the state has to appear exactly when the comparison stops being
+      // shallow, acyclic, and decidable on a scalar.
+      name: 'variantTerms separates renaming from sharing and still rejects on scalars',
+      run: () => {
+        const goal = parseGoalText('step(1, X, point(Y, X))');
+        const renamed = parseGoalText('step(1, A, point(B, A))');
+        const shared = parseGoalText('step(1, A, point(B, B))');
+        const otherScalar = parseGoalText('step(2, A, point(B, A))');
+        assertEqual(variantTerms(goal, new Env(), renamed, new Env()), true, 'a consistent renaming is a variant');
+        assertEqual(variantTerms(goal, new Env(), shared, new Env()), false, 'sharing a variable is not a renaming');
+        assertEqual(variantTerms(goal, new Env(), otherScalar, new Env()), false, 'a differing scalar argument rejects');
+        assertEqual(
+          variantTerms(parseGoalText('step(1.0, A)'), new Env(), parseGoalText('step(1, A)'), new Env()),
+          false,
+          'a float and an integer argument stay distinct',
+        );
+      },
+    },
+    {
+      name: 'variantTerms and deref terminate on cyclic bindings',
+      run: () => {
+        const leftEnv = new Env();
+        leftEnv.bind('X', compound('f', [variable('X')]));
+        const rightEnv = new Env();
+        rightEnv.bind('Y', compound('f', [variable('Y')]));
+        assertEqual(variantTerms(variable('X'), leftEnv, variable('Y'), rightEnv), true, 'cyclic terms of one shape are variants');
+
+        const chain = new Env();
+        for (let index = 0; index < 40; index++) chain.bind(`V${index}`, variable(`V${index + 1}`));
+        chain.bind('V40', atom('done'));
+        assertEqual(deref(variable('V0'), chain).name, 'done', 'a forty-hop chain resolves to its value');
+
+        const cyclicChain = new Env();
+        cyclicChain.bind('A', variable('B'));
+        cyclicChain.bind('B', variable('A'));
+        assertEqual(deref(variable('A'), cyclicChain).type, 'var', 'a cyclic chain stops at a variable');
+      },
+    },
+    {
+      name: 'tabled answers separate on a deep list element and still merge on a repeated derivation',
+      run: () => {
+        const program = Program.parse(`
+:- table suffixed/2.
+:- table duplicated/1.
+mark(a).
+mark(b).
+chain(0, [E], E).
+chain(N, [x|T], E) :- N > 0, M is N - 1, chain(M, T, E).
+suffixed(E, L) :- mark(E), chain(40, L, E).
+duplicated(L) :- chain(40, L, a).
+duplicated(L) :- chain(40, L, a).
+`);
+        const distinct = run(program, { goal: 'suffixed(E, L)' });
+        assertEqual(distinct.stdout.trim().split('\n').length, 2, 'answers differing only past forty cells stay distinct');
+        const merged = run(program, { goal: 'duplicated(L)' });
+        assertEqual(merged.stdout.trim().split('\n').length, 1, 'one answer derived twice is tabled once');
+      },
+    },
   ];
 }

package/test/run-all.mjs

@@ -35,6 +35,6 @@ await runStandalone(async (reporter) => {
   await runRegression(reporter);
   await runPlayground(reporter);
   await runExamples(reporter);
-  runProofChecking(reporter);
+  await runProofChecking(reporter);
   runBookExamples(reporter);
 });

package/test/run-examples.mjs

@@ -2,13 +2,13 @@
 // Example-output test runner.
 // It compares examples byte-for-byte against golden output so answer and proof changes cannot silently alter results.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';
+import { isMainThread, parentPort, workerData } from 'node:worker_threads';
 import { Program, run } from '../src/index.js';
 import { fileURLToPath } from 'node:url';
 import { TestReporter, isMainModule, runStandalone } from './test-style.mjs';
+import { runTasksInParallel, serveTasks } from './parallel-tasks.mjs';
 import { goalsInProgramOrder } from './goal-metadata.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
@@ -31,107 +31,39 @@ export async function runExamples(reporter = new TestReporter()) {
     .sort();
 
   reporter.section('Examples');
-  await runExampleTasks(files, (name, result) => reporter.testResult(name, result), 3);
+  await runExampleTasks(files, 'output', reporter);
   reporter.sectionTotal('examples');
 
+  // Proving an example costs several times what running it does, so this is
+  // the longer of the two passes over the same corpus. It is the same work per
+  // program and the same isolation, so it goes through the same worker pool.
   reporter.section('Proof examples');
-  for (const name of proofExamples) reporter.test(name, () => runProofExample(name));
+  await runExampleTasks(proofExamples, 'proof', reporter);
   reporter.sectionTotal('proof examples');
 }
 
-
-async function runExampleTasks(tasks, onResult, maxWorkers) {
-  if (tasks.length === 0) return;
-  const parallelism = os.availableParallelism?.() ?? os.cpus().length;
-  const workerCount = Math.min(tasks.length, Math.max(1, Math.min(maxWorkers, parallelism - 1)));
-  if (workerCount === 1) {
-    for (const name of tasks) {
-      const startedAt = performance.now();
-      try {
-        runExample(name);
-        onResult(name, { ms: Math.round(performance.now() - startedAt) });
-      } catch (error) {
-        onResult(name, { ms: Math.round(performance.now() - startedAt), error });
-      }
-    }
-    return;
-  }
-
-  const completedResults = new Map();
-  let nextTask = 0;
-  let nextReport = 0;
-  let completed = 0;
-  let settled = false;
-
-  await new Promise((resolve, reject) => {
-    const workers = Array.from({ length: workerCount }, () => new Worker(new URL(import.meta.url), {
-      workerData: { exampleWorker: true },
-    }));
-
-    const stopWorkers = () => Promise.all(workers.map((worker) => worker.terminate()));
-
-    const fail = (error) => {
-      if (settled) return;
-      settled = true;
-      stopWorkers().finally(() => reject(error));
-    };
-
-    const finish = () => {
-      if (settled || completed !== tasks.length || nextReport !== tasks.length) return;
-      settled = true;
-      stopWorkers().then(() => resolve(), reject);
-    };
-
-    const reportReady = () => {
-      try {
-        while (completedResults.has(nextReport)) {
-          const result = completedResults.get(nextReport);
-          completedResults.delete(nextReport);
-          onResult(tasks[nextReport], result);
-          nextReport++;
-        }
-      } catch (error) {
-        fail(error);
-      }
-    };
-
-    const assign = (worker) => {
-      if (nextTask >= tasks.length || settled) return;
-      worker.postMessage({ id: nextTask, name: tasks[nextTask++] });
-    };
-
-    for (const worker of workers) {
-      worker.on('message', ({ id, ms, error }) => {
-        if (settled) return;
-        completedResults.set(id, {
-          ms,
-          error: error == null ? null : Object.assign(new Error(error.message), { stack: error.stack }),
-        });
-        completed++;
-        reportReady();
-        assign(worker);
-        finish();
-      });
-      worker.on('error', fail);
-      assign(worker);
-    }
+// What a worker is asked to do with one example. Results are compared inside
+// the worker, so only a name, an elapsed time, and a failure cross the thread.
+const exampleTaskKinds = {
+  output: runExample,
+  proof: runProofExample,
+};
+
+
+function runExampleTasks(names, kind, reporter) {
+  return runTasksInParallel({
+    names,
+    workerUrl: new URL(import.meta.url),
+    workerData: { exampleWorker: true },
+    message: { kind },
+    maxWorkers: 3,
+    runLocally: (name) => exampleTaskKinds[kind](name),
+    onResult: (name, result) => reporter.testResult(name, result),
   });
 }
 
 function runExampleWorker() {
-  parentPort.on('message', ({ id, name }) => {
-    const startedAt = performance.now();
-    try {
-      runExample(name);
-      parentPort.postMessage({ id, ms: Math.round(performance.now() - startedAt), error: null });
-    } catch (error) {
-      parentPort.postMessage({
-        id,
-        ms: Math.round(performance.now() - startedAt),
-        error: { message: error?.message ?? String(error), stack: error?.stack ?? String(error) },
-      });
-    }
-  });
+  serveTasks(parentPort, ({ kind, name }) => exampleTaskKinds[kind](name));
 }
 
 

package/test/run-proof-checking.mjs

@@ -9,11 +9,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isMainThread, parentPort, workerData } from 'node:worker_threads';
 
 import { Program } from '../src/index.js';
 import { checkProofDocument, checkReportTerms, verdict } from '../src/check-proof.js';
 import { TestReporter, assertEqual, isMainModule, runStandalone } from './test-style.mjs';
 import { proofExamples } from './run-examples.mjs';
+import { runTasksInParallel, serveTasks } from './parallel-tasks.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const examplesDir = path.join(root, 'examples');
@@ -43,17 +45,24 @@ const KNOWN_GAPS = new Map([
 // checked here. The list is read from the directory rather than written out,
 // so a proof cannot be added without being checked.
 
-const totals = { steps: 0, verified: 0, redecided: 0, trusted: 0 };
-
-export function runProofChecking(reporter = new TestReporter()) {
+export async function runProofChecking(reporter = new TestReporter()) {
   reporter.section('Proof checking');
-  totals.steps = 0;
-  totals.verified = 0;
-  totals.redecided = 0;
-  totals.trusted = 0;
-  for (const name of [...proofExamples].sort()) {
-    reporter.test(name, () => checkPackagedProof(name));
-  }
+  // Each document is checked on its own against its own program, so the corpus
+  // is checked in parallel and the counts it establishes are summed as the
+  // results come back, in task order, rather than accumulated in a shared
+  // tally a worker could not reach.
+  const totals = { steps: 0, verified: 0, redecided: 0, trusted: 0 };
+  await runTasksInParallel({
+    names: [...proofExamples].sort(),
+    workerUrl: new URL(import.meta.url),
+    workerData: { proofCheckingWorker: true },
+    maxWorkers: 3,
+    runLocally: (name) => checkPackagedProof(name),
+    onResult: (name, result) => {
+      for (const field of Object.keys(totals)) totals[field] += result.value?.[field] ?? 0;
+      reporter.testResult(name, result);
+    },
+  });
   reporter.sectionTotal('proof checking');
   // What the corpus establishes, in the terms the conditions use: a verified
   // step was re-performed against its source clause, a recomputed one was run
@@ -83,19 +92,27 @@ function checkPackagedProof(name) {
   if (expected !== actual) {
     throw new Error(`check report mismatch for ${name}\nexpected:\n${expected}\nactual:\n${actual}`);
   }
-  totals.steps += report.steps;
-  totals.verified += report.verified;
-  totals.redecided += report.redecided;
-  totals.trusted += report.trusted.length;
+  // What this document contributes to the corpus totals, returned rather than
+  // added to a module-level tally so the same function is correct whether it
+  // runs here or in a worker.
+  const contribution = {
+    steps: report.steps,
+    verified: report.verified,
+    redecided: report.redecided,
+    trusted: report.trusted.length,
+  };
   const gap = KNOWN_GAPS.get(name);
   if (gap) {
     assertEqual(report.valid, false, `${name} now checks; remove it from KNOWN_GAPS (${gap})`);
-    return;
+    return contribution;
   }
   const detail = report.failures.slice(0, 3).map((failure) => `[${failure.condition}] ${failure.conclusion} -- ${failure.detail}`).join('; ');
   assertEqual(report.valid, true, `${name}: ${verdict(report)}${detail ? ` -- ${detail}` : ''}`);
+  return contribution;
 }
 
-if (isMainModule(import.meta.url)) {
+if (!isMainThread && workerData?.proofCheckingWorker) {
+  serveTasks(parentPort, ({ name }) => checkPackagedProof(name));
+} else if (isMainModule(import.meta.url)) {
   await runStandalone(runProofChecking);
 }