eyeprolog 1.3.29 → 1.3.31

package/README.md

@@ -291,8 +291,11 @@ and Scryer (`scryer-prolog`) installed, run:
 npm run test:interop
 ```
 
-The GitHub interoperability workflow builds both implementations and runs the
-same portable Towers of Hanoi source under EyeProlog, Trealla, and Scryer.
+This optional check runs the same portable Towers of Hanoi source under
+EyeProlog, Trealla, and Scryer. The default `npm test` does not require external
+Prolog implementations; it does validate all four generated OpenRuleBench
+source trees and their engine-specific tabling and WFS adaptations. Run those
+fast structural checks separately with `npm run test:openrulebench`.
 
 ## Development
 
@@ -303,4 +306,8 @@ npm install
 npm test
 ```
 
+The GitHub test workflow runs the complete suite and an npm package dry-run on
+both the minimum supported Node.js 18 release line and Node.js 24. Publishing
+repeats those release checks before uploading the package.
+
 EyeProlog is released under the [MIT License](LICENSE.md).

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.3.29",
+  "version": "1.3.31",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",
@@ -51,9 +51,14 @@
     "test:conformance": "node test/run-conformance.mjs",
     "test:iso-strict": "node test/run-iso-strict.mjs",
     "test:interop": "node test/run-interop.mjs",
+    "test:openrulebench": "node test/run-openrulebench.mjs",
     "test:wg17": "node test/run-wg17.mjs",
     "test:examples": "node test/run-examples.mjs",
     "test:regression": "node test/run-regression.mjs",
+    "test:regression:api": "node test/run-regression.mjs api",
+    "test:regression:core": "node test/run-regression.mjs regression",
+    "test:regression:docs": "node test/run-regression.mjs docs",
+    "test:regression:white-box": "node test/run-regression.mjs white-box",
     "test:playground": "node test/run-playground.mjs",
     "wg17:upgrade": "node tools/upgrade-wg17.mjs",
     "report:wg17": "node tools/report-wg17-syntax-coverage.mjs",

package/src/cli.js

@@ -173,7 +173,7 @@ export async function main(argv) {
 
 async function loadEngine() {
   if (engineModule == null) {
-    const [term, parser, program, solver, iso, library, write, quads] = await Promise.all([
+    const [term, parser, program, solver, iso, library, write, quads, execute] = await Promise.all([
       import('./term.js'),
       import('./parser.js'),
       import('./program.js'),
@@ -182,8 +182,9 @@ async function loadEngine() {
       import('./standard-library.js'),
       import('./write.js'),
       import('./quads.js'),
+      import('./execute.js'),
     ]);
-    engineModule = { ...term, ...parser, ...program, ...solver, ...iso, ...library, ...write, ...quads };
+    engineModule = { ...term, ...parser, ...program, ...solver, ...iso, ...library, ...write, ...quads, ...execute };
   }
   return engineModule;
 }
@@ -201,49 +202,16 @@ async function runDefault(engine, program, options) {
     ioOptions: { write: (text) => process.stdout.write(String(text)) },
   });
   program = solver.program;
-  const goals = options.goals.map((text) => {
-    const goal = engine.parseGoalText(text, {
-      doubleQuotes: solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
-      operatorDefinitions: [...program.operators.values()],
-      isoStrict: options.isoStrict,
-    });
-    if (goal.type === 'var') throw new engine.PrologError('instantiation_error');
-    if (goal.type !== 'atom' && goal.type !== 'compound') throw new engine.PrologError('type_error(callable)', goal);
-    return goal;
-  });
-  const queriedKeys = new Set(goals.map((goal) => `${goal.name}/${goal.arity}`));
-  const writeOptions = {
-    doubleQuotes: solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
-    operators: [...program.operators.values()],
-    quoted: true,
-  };
-  const facts = program.sourceFactLines(queriedKeys, writeOptions);
-  const lines = new Set();
+  const goals = engine.normalizeGoals(options.goals, solver);
   const explanation = options.proof ? await loadExplanation() : null;
   try {
-    solver.runInitializations();
-    for (const goal of goals) {
-      solver.solutionsSeen = 0;
-      for (const env of solver.solve([goal], new engine.Env(), 0)) {
-        if (!engine.termIsGround(goal, env)) continue;
-
-        const currentWriteOptions = {
-          doubleQuotes: solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
-          operators: [...program.operators.values()],
-          quoted: true,
-        };
-        const line = `${engine.formatTermForWrite(goal, env, currentWriteOptions)}.\n`;
-        if (facts.has(line) || lines.has(line)) continue;
-
-        lines.add(line);
-
+    const { haltCode } = engine.executeGoals(program, solver, goals, {
+      onAnswer: (line, resolved) => {
         process.stdout.write(line);
-        if (options.proof) writeExplanation(explanation, program, engine.copyResolved(goal, env), registry);
-      }
-    }
-  } catch (error) {
-    if (error?.name !== 'HaltSignal') throw error;
-    process.exitCode = error.code;
+        if (options.proof) writeExplanation(explanation, program, resolved, registry);
+      },
+    });
+    if (haltCode != null) process.exitCode = haltCode;
   } finally {
     if (options.stats) printStats(solver.stats);
   }

package/src/execute.js

@@ -0,0 +1,56 @@
+// Shared goal preparation and execution for the CLI and embedding API.
+import { ATOM, COMPOUND, VAR, Env, copyResolved, termIsGround } from './term.js';
+import { parseGoalText } from './parser.js';
+import { HaltSignal, PrologError } from './iso.js';
+import { formatTermForWrite } from './write.js';
+
+export function normalizeGoals(requestedGoals, solver) {
+  return requestedGoals.map((requestedGoal) => {
+    const goal = typeof requestedGoal === 'string'
+      ? parseGoalText(requestedGoal, {
+          doubleQuotes: solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
+          operatorDefinitions: [...solver.program.operators.values()],
+          isoStrict: solver.isoStrict,
+        })
+      : requestedGoal;
+    if (goal.type === VAR) throw new PrologError('instantiation_error');
+    if (goal.type !== ATOM && goal.type !== COMPOUND) throw new PrologError('type_error(callable)', goal);
+    return goal;
+  });
+}
+
+export function executeGoals(program, solver, goals, { onAnswer = () => {} } = {}) {
+  const initialWriteOptions = currentWriteOptions(program, solver);
+  const queriedKeys = new Set(goals.map((goal) => `${goal.name}/${goal.arity}`));
+  const facts = program.sourceFactLines(queriedKeys, initialWriteOptions);
+  const seen = new Set();
+  let haltCode = null;
+
+  try {
+    solver.runInitializations();
+    for (const goal of goals) {
+      solver.solutionsSeen = 0;
+      for (const env of solver.solve([goal], new Env(), 0)) {
+        if (!termIsGround(goal, env)) continue;
+        const resolved = copyResolved(goal, env);
+        const line = `${formatTermForWrite(resolved, new Env(), currentWriteOptions(program, solver))}.\n`;
+        if (facts.has(line) || seen.has(line)) continue;
+        seen.add(line);
+        onAnswer(line, resolved);
+      }
+    }
+  } catch (error) {
+    if (!(error instanceof HaltSignal)) throw error;
+    haltCode = error.code;
+  }
+
+  return { haltCode };
+}
+
+function currentWriteOptions(program, solver) {
+  return {
+    doubleQuotes: solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
+    operators: [...program.operators.values()],
+    quoted: true,
+  };
+}

package/src/index.js

@@ -27,14 +27,12 @@ export {
 export { StreamManager } from './io.js';
 export { runQuads } from './quads.js';
 
-import { ATOM, COMPOUND, VAR, Env, copyResolved, termIsGround } from './term.js';
-import { Program } from './program.js';
+import { Program, autoloadProgramGoals } from './program.js';
 import { Solver } from './solver.js';
 import { whyNoProof, whyProof } from './explain.js';
-import { HaltSignal, PrologError, getStrictIsoRegistry } from './iso.js';
+import { getStrictIsoRegistry } from './iso.js';
 import { getEyePrologRegistry } from './standard-library.js';
-import { parseGoalText } from './parser.js';
-import { formatTermForWrite } from './write.js';
+import { executeGoals, normalizeGoals } from './execute.js';
 
 export function run(source, options = {}) {
   const includeWhy = options.proof === true || options.why === true || options.explain === true;
@@ -49,6 +47,7 @@ export function run(source, options = {}) {
     autoloadGoals: requestedGoals,
   };
   let program = source instanceof Program ? source : Program.parse(source, parseOptions);
+  if (source instanceof Program) autoloadProgramGoals(program, requestedGoals, options);
   const strictIso = requestedStrictIso || program.strictIso === true;
   const runOptions = strictIso
     ? { ...options, isoStrict: true, registry: getStrictIsoRegistry() }
@@ -66,56 +65,14 @@ export function run(source, options = {}) {
     },
   });
   program = solver.program;
-  const goals = normalizeGoals(options, solver);
-  const writeOptions = {
-    doubleQuotes: solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
-    operators: [...program.operators.values()],
-    quoted: true,
-  };
-  const queriedKeys = new Set(goals.map((goal) => `${goal.name}/${goal.arity}`));
-  const facts = program.sourceFactLines(queriedKeys, writeOptions);
-  const seen = new Set();
-  let haltCode = null;
-  try {
-    solver.runInitializations();
-    for (const goal of goals) {
-      solver.solutionsSeen = 0;
-      for (const env of solver.solve([goal], new Env(), 0)) {
-        const resolved = copyResolved(goal, env);
-        if (!termIsGround(resolved)) continue;
-        const currentWriteOptions = {
-          doubleQuotes: solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
-          operators: [...program.operators.values()],
-          quoted: true,
-        };
-        const line = `${formatTermForWrite(resolved, new Env(), currentWriteOptions)}.\n`;
-        if (facts.has(line) || seen.has(line)) continue;
-        seen.add(line);
-        output.push(line);
-        if (includeWhy) appendExplanation(output, program, resolved, runOptions.registry);
-      }
-    }
-  } catch (error) {
-    if (!(error instanceof HaltSignal)) throw error;
-    haltCode = error.code;
-  }
-  return { stdout: output.join(''), stats: solver.stats, haltCode };
-}
-
-function normalizeGoals(options, solver) {
-  const requested = options.goals ?? (options.goal == null ? [] : [options.goal]);
-  return requested.map((requestedGoal) => {
-    const goal = typeof requestedGoal === 'string'
-      ? parseGoalText(requestedGoal, {
-          doubleQuotes: solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
-          operatorDefinitions: [...solver.program.operators.values()],
-          isoStrict: solver.isoStrict,
-        })
-      : requestedGoal;
-    if (goal.type === VAR) throw new PrologError('instantiation_error');
-    if (goal.type !== ATOM && goal.type !== COMPOUND) throw new PrologError('type_error(callable)', goal);
-    return goal;
+  const goals = normalizeGoals(requestedGoals, solver);
+  const { haltCode } = executeGoals(program, solver, goals, {
+    onAnswer: (line, resolved) => {
+      output.push(line);
+      if (includeWhy) appendExplanation(output, program, resolved, runOptions.registry);
+    },
   });
+  return { stdout: output.join(''), stats: solver.stats, haltCode };
 }
 
 function appendExplanation(output, program, resolved, registry) {

package/src/program.js

@@ -706,6 +706,48 @@ function buildProgramFromSources(sources, options) {
   return builder.finish();
 }
 
+// Program.parse() can see host-supplied goals through autoloadGoals while it
+// builds the program. A Program passed directly to run() has already completed
+// that phase, so extend the existing instance with the same canonical interop
+// imports before solving those goals. Keeping this here lets both paths share
+// the dependency analysis and module-loading rules.
+export function autoloadProgramGoals(program, inputs, options = {}) {
+  if (inputs == null || (Array.isArray(inputs) && inputs.length === 0)) return program;
+  const operatorState = createParserOperatorState(
+    [...program.operators.values()],
+    false,
+    { isoStrict: program.strictIso },
+  );
+  const parserFlagState = { doubleQuotes: program.doubleQuotes ?? options.doubleQuotes ?? 'chars' };
+  const goals = parseInteropGoalInputs(inputs, {
+    ...options,
+    isoStrict: program.strictIso,
+    operatorState,
+    parserFlagState,
+  }, program);
+
+  if (!program.strictIso && options.autoload !== false) {
+    const builder = new ProgramBuilder({ ...options, isoStrict: false }, program);
+    const loadedModules = new Set([...program.modules.keys()].filter((name) => name !== 'user'));
+    const autoloadCount = program.autoloadedPredicates.length;
+    autoloadInteropDependencies(builder, {
+      ...options,
+      isoStrict: false,
+      operatorState,
+      parserFlagState,
+    }, new Set(), loadedModules, goals);
+    if (program.autoloadedPredicates.length !== autoloadCount) {
+      // Existing Solver instances key their tables by Program revision, and a
+      // previously requested negation analysis is no longer complete once new
+      // library groups become reachable.
+      program.noteMutation(false);
+      builder.finish();
+    }
+  }
+  analyzeInteropPortability(program, goals);
+  return program;
+}
+
 function loadSourcesIntoBuilder(builder, sources, options, fast) {
   const ensured = new Set();
   const loadedModules = new Set();

package/test/run-all.mjs

@@ -2,7 +2,7 @@
 // Unified test runner used by `npm test`.
 // Running all suites in one process keeps the numbering continuous and avoids
 // npm's intermediate script banners between conformance, regression, and examples.
-import { TestReporter } from './test-style.mjs';
+import { runStandalone } from './test-style.mjs';
 import { runConformance } from './run-conformance.mjs';
 import { runRegression } from './run-regression.mjs';
 import { runIsoStrict } from './run-iso-strict.mjs';
@@ -10,19 +10,15 @@ import { runPlayground } from './run-playground.mjs';
 import { runExamples } from './run-examples.mjs';
 import { runBookExamples } from './run-book-examples.mjs';
 import { runWg17 } from './run-wg17.mjs';
+import { runOpenRuleBenchChecks } from './run-openrulebench.mjs';
 
-const reporter = new TestReporter();
-
-try {
+await runStandalone(async (reporter) => {
   runConformance(reporter);
   runIsoStrict(reporter);
   runWg17(reporter);
+  runOpenRuleBenchChecks(reporter);
   runRegression(reporter);
   await runPlayground(reporter);
   runExamples(reporter);
   runBookExamples(reporter);
-  reporter.totalLine();
-  process.exit(0);
-} catch (_) {
-  process.exit(1);
-}
+});

package/test/run-book-examples.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { Program, run } from '../src/index.js';
-import { TestReporter, isMainModule } from './test-style.mjs';
+import { TestReporter, isMainModule, runStandalone } from './test-style.mjs';
 import { goalsFromSource } from './goal-metadata.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -39,11 +39,5 @@ function listPrograms(directory) {
 }
 
 if (isMainModule(import.meta.url)) {
-  const reporter = new TestReporter();
-  try {
-    runBookExamples(reporter);
-    reporter.totalLine();
-  } catch (_) {
-    process.exit(1);
-  }
+  await runStandalone(runBookExamples);
 }

package/test/run-conformance-report.mjs

@@ -5,6 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { listPrologFiles } from './test-support.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
 const packageRoot = path.resolve(root, '..');
@@ -24,7 +25,7 @@ export function buildConformanceReport() {
   for (const { kind, expectedKind, expectedExt, column } of KINDS) {
     const base = path.join(conformanceRoot, kind);
     if (!fs.existsSync(base)) continue;
-    for (const file of listEyePrologFiles(base)) {
+    for (const file of listPrologFiles(base)) {
       const category = categoryOf(file);
       const counts = ensureCategory(categories, category);
       counts[column]++;
@@ -77,19 +78,6 @@ export function formatConformanceReport(report = buildConformanceReport()) {
   return `${lines.join('\n')}\n`;
 }
 
-function listEyePrologFiles(base, dir = base) {
-  const files = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...listEyePrologFiles(base, full));
-    } else if (entry.isFile() && entry.name.endsWith('.pl')) {
-      files.push(path.relative(base, full).split(path.sep).join('/'));
-    }
-  }
-  return files.sort();
-}
-
 function categoryOf(file) {
   const parts = file.split('/');
   return parts.length > 1 ? parts[0] : 'legacy-numbered';

package/test/run-conformance.mjs

@@ -6,27 +6,12 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { Program, createDefaultRegistry, run } from '../src/index.js';
 import { fileURLToPath } from 'node:url';
-import { TestReporter, isMainModule } from './test-style.mjs';
+import { TestReporter, isMainModule, runStandalone } from './test-style.mjs';
 import { goalsFromSource } from './goal-metadata.mjs';
+import { listPrologFiles, withStandardModules } from './test-support.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
 const filterArg = process.argv[2] ?? null;
-const libraryCall = /\b(?:uuid|difference|maplist|lt|gt|le|ge|between|smallest_divisor_from|random|matches|split|replace|lowercase|uppercase|trim|number_string|atom_string|term_string|append|string_concat|contains|join|substring|member|select|last|nth0|nth1|set_nth0|take|drop|slice|reverse|length|sum_list|min_list|max_list|list_to_set|countall|sumall|aggregate_min|aggregate_max)\s*\(/;
-
-function withStandardModules(text) {
-  if (!libraryCall.test(text) || text.includes('use_module(library(')) return text;
-  return `:- use_module(library(aggregate)).
-:- use_module(library(comparison)).
-:- use_module(library(dates)).
-:- use_module(library(iso_ext)).
-:- use_module(library(lists)).
-:- use_module(library(primes)).
-:- use_module(library(prologue), [between/3]).
-:- use_module(library(random)).
-:- use_module(library(strings)).
-:- use_module(library(uuid)).
-${text}`;
-}
 
 export function runConformance(reporter = new TestReporter(), requestedFilter = null) {
   const filter = requestedFilter ?? filterArg;
@@ -42,7 +27,7 @@ export function runConformance(reporter = new TestReporter(), requestedFilter =
 function listCaseFiles(kind, filter = null) {
   const base = path.join(root, 'conformance', kind);
   if (!fs.existsSync(base)) return [];
-  return listEyePrologFiles(base)
+  return listPrologFiles(base)
     .filter((name) => matchesFilter(kind, name, filter))
     .sort();
 }
@@ -58,19 +43,6 @@ function matchesFilter(kind, name, filter) {
     || `${label}/${stem}`.includes(filter);
 }
 
-function listEyePrologFiles(base, dir = base) {
-  const files = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...listEyePrologFiles(base, full));
-    } else if (entry.isFile() && entry.name.endsWith('.pl')) {
-      files.push(path.relative(base, full).split(path.sep).join('/'));
-    }
-  }
-  return files;
-}
-
 function runCaseFile(reporter, file) {
   const name = file.slice(0, -3);
   reporter.test(name, () => runCase(name, file));
@@ -194,11 +166,5 @@ function diffText(expected, actualText) {
 }
 
 if (isMainModule(import.meta.url)) {
-  const reporter = new TestReporter();
-  try {
-    runConformance(reporter);
-    reporter.totalLine();
-  } catch (_) {
-    process.exit(1);
-  }
+  await runStandalone(runConformance);
 }

package/test/run-examples.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { Program, run } from '../src/index.js';
 import { fileURLToPath } from 'node:url';
-import { TestReporter, isMainModule } from './test-style.mjs';
+import { TestReporter, isMainModule, runStandalone } from './test-style.mjs';
 import { goalsInProgramOrder } from './goal-metadata.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
@@ -156,11 +156,5 @@ function diffText(expected, actualText) {
 }
 
 if (isMainModule(import.meta.url)) {
-  const reporter = new TestReporter();
-  try {
-    runExamples(reporter);
-    reporter.totalLine();
-  } catch (_) {
-    process.exit(1);
-  }
+  await runStandalone(runExamples);
 }

package/test/run-iso-strict.mjs

@@ -10,7 +10,7 @@ import {
   parseGoalText,
   run,
 } from '../src/index.js';
-import { TestReporter, isMainModule } from './test-style.mjs';
+import { TestReporter, isMainModule, runStandalone } from './test-style.mjs';
 
 export function runIsoStrict(reporter = new TestReporter()) {
   reporter.section('Strict ISO core');
@@ -103,11 +103,5 @@ function includes(actual, expected, label) {
 }
 
 if (isMainModule(import.meta.url)) {
-  const reporter = new TestReporter();
-  try {
-    runIsoStrict(reporter);
-    reporter.totalLine();
-  } catch (_) {
-    process.exit(1);
-  }
+  await runStandalone(runIsoStrict);
 }

package/test/run-openrulebench.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Fast structural checks for the generated multi-engine OpenRuleBench corpus.
+// Full benchmark execution remains separate because it requires external
+// Prolog implementations and is intentionally performance-oriented.
+import { validateOpenRuleBench } from '../openrulebench/tools/check.mjs';
+import { TestReporter, isMainModule, runStandalone } from './test-style.mjs';
+
+export function runOpenRuleBenchChecks(reporter = new TestReporter()) {
+  let report = null;
+  reporter.section('OpenRuleBench source integrity');
+  reporter.test('generated sources pass lexical checks', () => {
+    report = validateOpenRuleBench();
+    assertNoErrors(report.lexicalErrors);
+  });
+  reporter.test('engine variants preserve table and WFS adaptations', () => {
+    report ??= validateOpenRuleBench();
+    assertNoErrors(report.adaptationErrors);
+  });
+  reporter.sectionTotal('OpenRuleBench source-integrity');
+}
+
+function assertNoErrors(errors) {
+  if (errors.length > 0) throw new Error(errors.join('\n'));
+}
+
+if (isMainModule(import.meta.url)) {
+  await runStandalone(runOpenRuleBenchChecks);
+}

package/test/run-playground.mjs

@@ -10,7 +10,14 @@ import {
   executePlaygroundRequest,
   installPlaygroundWorker,
 } from '../src/playground-worker.js';
-import { TestReporter, isMainModule } from './test-style.mjs';
+import {
+  TestReporter,
+  assertEqual,
+  assertIncludes,
+  assertNotIncludes,
+  isMainModule,
+  runStandalone,
+} from './test-style.mjs';
 
 const testRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
 const packageRoot = path.resolve(testRoot, '..');
@@ -220,30 +227,6 @@ function assert(condition, message) {
   if (!condition) throw new Error(message);
 }
 
-function assertEqual(actual, expected, label) {
-  if (actual !== expected) {
-    throw new Error(`${label} mismatch\nexpected: ${JSON.stringify(expected)}\nactual:   ${JSON.stringify(actual)}`);
-  }
-}
-
-function assertIncludes(actual, expected, label) {
-  if (!String(actual).includes(expected)) {
-    throw new Error(`${label} did not include ${JSON.stringify(expected)}\nactual: ${JSON.stringify(actual)}`);
-  }
-}
-
-function assertNotIncludes(actual, expected, label) {
-  if (String(actual).includes(expected)) {
-    throw new Error(`${label} unexpectedly included ${JSON.stringify(expected)}`);
-  }
-}
-
 if (isMainModule(import.meta.url)) {
-  const reporter = new TestReporter();
-  try {
-    await runPlayground(reporter);
-    reporter.totalLine();
-  } catch (_) {
-    process.exit(1);
-  }
+  await runStandalone(runPlayground);
 }

package/test/run-regression.mjs

@@ -48,13 +48,21 @@ import { PrologError, formalErrorTerm } from '../src/iso.js';
 import { compareTerms } from '../src/term.js';
 import { formatTermForWrite } from '../src/write.js';
 import { selectClauseCandidates } from '../src/program.js';
-import { TestReporter, isMainModule } from './test-style.mjs';
+import {
+  TestReporter,
+  assertEqual,
+  assertIncludes,
+  assertNotIncludes,
+  isMainModule,
+  runStandalone,
+} from './test-style.mjs';
 import { buildConformanceReport, formatConformanceReport } from './run-conformance-report.mjs';
 import { proofExamples } from './run-examples.mjs';
 import { goalsFromSource } from './goal-metadata.mjs';
 import { renderWg17SyntaxStatus } from '../tools/report-wg17-syntax-coverage.mjs';
 import { parseWg17SyntaxTable } from '../tools/upgrade-wg17.mjs';
 import { executeWg17Item, matchesUpstreamExpectation, readWg17SyntaxFixture } from './run-wg17.mjs';
+import { withStandardModules } from './test-support.mjs';
 
 const testRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
 const packageRoot = path.resolve(testRoot, '..');
@@ -62,22 +70,6 @@ const bin = path.join(packageRoot, 'bin', 'eyeprolog.js');
 const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
 let tmp = null;
 let tmpCounter = 0;
-const libraryCall = /\b(?:uuid|difference|maplist|foldl|call_nth|lt|gt|le|ge|between|smallest_divisor_from|random|matches|split|replace|lowercase|uppercase|trim|number_string|atom_string|term_string|append|string_concat|contains|join|substring|member|select|last|nth0|nth1|set_nth0|take|drop|slice|reverse|length|sum_list|min_list|max_list|list_to_set|countall|sumall|aggregate_min|aggregate_max)\s*\(/;
-
-function withStandardModules(source) {
-  if (!libraryCall.test(source) || source.includes('use_module(library(') || source.includes(':- module(')) return source;
-  return `:- use_module(library(aggregate)).
-:- use_module(library(comparison)).
-:- use_module(library(dates)).
-:- use_module(library(iso_ext)).
-:- use_module(library(lists)).
-:- use_module(library(primes)).
-:- use_module(library(prologue), [between/3]).
-:- use_module(library(random)).
-:- use_module(library(strings)).
-:- use_module(library(uuid)).
-${source}`;
-}
 
 function run(source, options = {}) {
   const programSource = Array.isArray(source) ? source.join('\n') : source;
@@ -92,15 +84,24 @@ function sourceAtom(value) {
   return `'${String(value).replaceAll('\\', '\\\\').replaceAll("'", "''")}'`;
 }
 
-export function runRegression(reporter = new TestReporter()) {
+export function runRegression(reporter = new TestReporter(), requestedSection = null) {
+  const sections = [
+    { key: 'regression', name: 'Regression', cases: regressionCases },
+    { key: 'docs', name: 'Documentation sync', cases: documentationSyncCases },
+    { key: 'api', name: 'API', cases: apiCases },
+    { key: 'white-box', name: 'White-box', cases: whiteBoxCases },
+  ];
+  const selected = requestedSection == null
+    ? sections
+    : sections.filter((section) => section.key === requestedSection);
+  if (selected.length === 0) {
+    throw new Error(`unknown regression section: ${requestedSection}; expected ${sections.map(({ key }) => key).join(', ')}`);
+  }
+
   tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'eyeprolog-regression.'));
   tmpCounter = 0;
-
   try {
-    runSection(reporter, 'Regression', regressionCases());
-    runSection(reporter, 'Documentation sync', documentationSyncCases());
-    runSection(reporter, 'API', apiCases());
-    runSection(reporter, 'White-box', whiteBoxCases());
+    for (const section of selected) runSection(reporter, section.name, section.cases());
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });
     tmp = null;
@@ -3407,6 +3408,23 @@ function documentationSyncCases() {
       name: 'documented npm scripts exist in package.json',
       run: () => assertArrayEqual(missingDocumentedPackageScripts(), [], 'missing documented npm scripts'),
     },
+    {
+      name: 'CI verifies the supported Node floor and gates npm publishing',
+      run: () => {
+        const testWorkflow = fs.readFileSync(path.join(packageRoot, '.github', 'workflows', 'test.yml'), 'utf8');
+        assertIncludes(testWorkflow, "node-version: ['18', '24']", 'test workflow Node matrix');
+        assertIncludes(testWorkflow, 'run: npm test', 'test workflow suite');
+        assertIncludes(testWorkflow, 'run: npm pack --dry-run', 'test workflow package check');
+
+        const publishWorkflow = fs.readFileSync(path.join(packageRoot, '.github', 'workflows', 'publish-npm.yml'), 'utf8');
+        const testIndex = publishWorkflow.indexOf('run: npm test');
+        const packIndex = publishWorkflow.indexOf('run: npm pack --dry-run');
+        const publishIndex = publishWorkflow.indexOf('run: npm publish');
+        assertEqual(testIndex >= 0 && testIndex < publishIndex, true, 'publish workflow test gate');
+        assertEqual(packIndex >= 0 && packIndex < publishIndex, true, 'publish workflow package gate');
+        assertEqual(pkg.scripts?.['test:openrulebench'], 'node test/run-openrulebench.mjs', 'OpenRuleBench test script');
+      },
+    },
     {
       name: 'documented conformance totals match the generated report',
       run: () => assertArrayEqual(documentedConformanceMetricIssues(), [], 'documented conformance totals'),
@@ -3856,6 +3874,21 @@ answer(ok) :-
         assertEqual(result.stdout, 'member(a, "ab").\nmember(b, "ab").\n', 'stdout');
       },
     },
+    {
+      name: 'JavaScript run autoloads top-level goals for parsed Program instances',
+      run: () => {
+        const program = Program.parse('');
+        const revision = program.revision;
+        program.stratifiedNegation;
+        const result = runEyeProlog(program, { goal: 'member(X,[a,b])' });
+        assertEqual(result.stdout, 'member(a, "ab").\nmember(b, "ab").\n', 'stdout');
+        assertEqual(program.findGroup('member', 2)?.module, 'lists', 'autoloaded Program predicate');
+        assertEqual(program.autoloadedPredicates.map((entry) => `${entry.indicator}:${entry.library}`).join(','),
+          'member/2:lists', 'autoload metadata');
+        assertEqual(program.revision, revision + 1, 'Program revision after autoload');
+        assertEqual(program.stratifiedNegation, true, 'negation metadata recomputed after autoload');
+      },
+    },
     {
       name: 'JavaScript run can disable top-level goal autoloading',
       run: () => {
@@ -5707,18 +5740,6 @@ function runCli(args, options = {}) {
   });
 }
 
-function assertEqual(actual, expected, label) {
-  if (actual !== expected) throw new Error(`${label} mismatch\nexpected: ${format(expected)}\nactual:   ${format(actual)}`);
-}
-
-function assertIncludes(actual, expected, label) {
-  if (!actual.includes(expected)) throw new Error(`${label} did not include ${format(expected)}\nactual: ${format(actual)}`);
-}
-
-function assertNotIncludes(actual, expected, label) {
-  if (String(actual).includes(expected)) throw new Error(`${label} unexpectedly included ${format(expected)}\nactual: ${format(actual)}`);
-}
-
 function arrayDiffMessages(actual, expected, label) {
   const messages = [];
   const actualSet = new Set(actual);
@@ -5744,11 +5765,5 @@ function format(value) {
 }
 
 if (isMainModule(import.meta.url)) {
-  const reporter = new TestReporter();
-  try {
-    runRegression(reporter);
-    reporter.totalLine();
-  } catch (_) {
-    process.exit(1);
-  }
+  await runStandalone((reporter) => runRegression(reporter, process.argv[2] ?? null));
 }

package/test/run-wg17.mjs

@@ -11,7 +11,7 @@ import {
 } from '../src/index.js';
 import { parseTermText } from '../src/parser.js';
 import { variantTerms } from '../src/term.js';
-import { TestReporter, isMainModule } from './test-style.mjs';
+import { TestReporter, isMainModule, runStandalone } from './test-style.mjs';
 
 const testRoot = path.dirname(fileURLToPath(import.meta.url));
 const fixturePath = path.join(testRoot, 'conformance', 'wg17-syntax-cases.json');
@@ -377,12 +377,5 @@ export function runWg17(reporter = new TestReporter()) {
 }
 
 if (isMainModule(import.meta.url)) {
-  const reporter = new TestReporter();
-  try {
-    runWg17(reporter);
-    reporter.totalLine();
-  } catch (error) {
-    process.stderr.write(`${error?.stack ?? error}\n`);
-    process.exitCode = 1;
-  }
+  await runStandalone(runWg17);
 }

package/test/test-style.mjs

@@ -102,6 +102,43 @@ export function isMainModule(metaUrl) {
   return process.argv[1] != null && path.resolve(process.argv[1]) === fileURLToPath(metaUrl);
 }
 
+export async function runStandalone(runSuite) {
+  const reporter = new TestReporter();
+  try {
+    await runSuite(reporter);
+    reporter.totalLine();
+  } catch (error) {
+    // TestReporter already prints failures raised inside a test. Preserve a
+    // diagnostic for setup/teardown failures that occur outside reporter.test.
+    if (reporter.ok === reporter.total) {
+      reporter.stderr.write(`${error?.stack ?? String(error)}\n`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+export function assertEqual(actual, expected, label) {
+  if (actual !== expected) {
+    throw new Error(`${label} mismatch\nexpected: ${formatValue(expected)}\nactual:   ${formatValue(actual)}`);
+  }
+}
+
+export function assertIncludes(actual, expected, label) {
+  if (!String(actual).includes(expected)) {
+    throw new Error(`${label} did not include ${formatValue(expected)}\nactual: ${formatValue(actual)}`);
+  }
+}
+
+export function assertNotIncludes(actual, expected, label) {
+  if (String(actual).includes(expected)) {
+    throw new Error(`${label} unexpectedly included ${formatValue(expected)}\nactual: ${formatValue(actual)}`);
+  }
+}
+
+function formatValue(value) {
+  return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+
 function defaultSectionLabel(name) {
   return String(name)
     .replace(/^Conformance\s+/, 'conformance ')

package/test/test-support.mjs

@@ -0,0 +1,36 @@
+// Shared fixtures and filesystem helpers used across test suites.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const libraryCall = /\b(?:uuid|difference|maplist|foldl|call_nth|lt|gt|le|ge|between|smallest_divisor_from|random|matches|split|replace|lowercase|uppercase|trim|number_string|atom_string|term_string|append|string_concat|contains|join|substring|member|select|last|nth0|nth1|set_nth0|take|drop|slice|reverse|length|sum_list|min_list|max_list|list_to_set|countall|sumall|aggregate_min|aggregate_max)\s*\(/;
+
+const standardModulePrelude = `:- use_module(library(aggregate)).
+:- use_module(library(comparison)).
+:- use_module(library(dates)).
+:- use_module(library(iso_ext)).
+:- use_module(library(lists)).
+:- use_module(library(primes)).
+:- use_module(library(prologue), [between/3]).
+:- use_module(library(random)).
+:- use_module(library(strings)).
+:- use_module(library(uuid)).
+`;
+
+export function withStandardModules(source) {
+  const text = String(source);
+  if (!libraryCall.test(text) || text.includes('use_module(library(') || text.includes(':- module(')) return text;
+  return `${standardModulePrelude}${text}`;
+}
+
+export function listPrologFiles(base, dir = base) {
+  const files = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listPrologFiles(base, full));
+    } else if (entry.isFile() && entry.name.endsWith('.pl')) {
+      files.push(path.relative(base, full).split(path.sep).join('/'));
+    }
+  }
+  return files.sort();
+}

package/the-art-of-eyeprolog.md

@@ -1819,6 +1819,11 @@ additional logical answer.
 `analyzeNegation`. It returns `stdout`, the solver's numeric `stats`, and a
 nullable `haltCode`; it does not write to the process streams.
 
+When `run` receives an already parsed `Program`, canonical interop imports
+needed only by its host-supplied goals are added to that Program before solving,
+just as they are while source text is parsed. Pass `autoload: false` when the
+Program must retain only explicitly imported predicates.
+
 For applications that inspect or prepare a theory before running it, use
 `Program` directly:
 
@@ -6302,8 +6307,10 @@ calls to non-profile predicates from otherwise common modules. `--portable`
 turns those diagnostics into a failing run, making the conservative profile
 suitable for continuous integration. `npm run test:interop` executes the same
 portable Towers of Hanoi source under EyeProlog, Trealla, and Scryer when those commands
-are installed; the repository interoperability workflow installs them and runs
-that check.
+are installed. Because those are external runtimes, the default `npm test`
+instead validates all four generated OpenRuleBench source trees and their
+engine-specific tabling and WFS adaptations without requiring them. The fast
+structural check is also available directly as `npm run test:openrulebench`.
 
 #### Library notes beyond the interoperability profile