eyeprolog 1.5.10 → 1.5.11

package/README.md

@@ -85,6 +85,8 @@ The checked [Symbiotic Knowledge Graphs example](examples/symbiotic-knowledge-gr
 
 The same RDF → Prolog → RDF boundary is exercised by five additional checked scenarios: [cross-organization data sharing](https://eyereasoner.github.io/eyeprolog/examples/deck/cross-organization-data-sharing), [explainable EV-depot configuration](https://eyereasoner.github.io/eyeprolog/examples/deck/explainable-ev-depot-configuration), [operational incident response](https://eyereasoner.github.io/eyeprolog/examples/deck/operational-incident-response), [software supply-chain vulnerability response](https://eyereasoner.github.io/eyeprolog/examples/deck/sbom-vulnerability-response), and a [scientific evidence graph](https://eyereasoner.github.io/eyeprolog/examples/deck/scientific-evidence-graph). Together they cover policy decisions, reversible configuration reasoning, dependency-graph diagnosis, transitive SBOM exposure, and evidence aggregation with explicit disagreement.
 
+## Benchmarks
+EyeProlog has 20 checksum-protected wall-clock benchmarks spanning recursion/indexing, constraints, tabling/WFS, DCGs, Eyelet, search, term I/O, attributes, and rewriting. Short workloads are adaptively batched before timing so millisecond-scale noise is not mistaken for a regression. Run `npm run benchmark`; create a machine-local comparison point with `npm run benchmark:baseline`; use `npm run test:benchmark` for harness checks. Details are in [*The Art of EyeProlog*](the-art-of-eyeprolog.md).
 ## Development
 
 ```sh

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.5.10",
+  "version": "1.5.11",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",
@@ -66,6 +66,9 @@
     "report:wg17-syntax": "node tools/report-wg17-syntax-coverage.mjs",
     "preversion": "npm test && node test/run-conformance-report.mjs conformance-report.md",
     "postversion": "git push origin HEAD --follow-tags",
-    "test:architecture": "node test/run-architecture.mjs"
+    "test:architecture": "node test/run-architecture.mjs",
+    "benchmark": "node test/benchmark.mjs",
+    "benchmark:baseline": "node test/benchmark.mjs --save .benchmarks/baseline.json",
+    "test:benchmark": "node test/run-benchmark-tests.mjs"
   }
 }

package/src/ARCHITECTURE.md

@@ -88,3 +88,10 @@ retains the same data structures and selection functions.
 Large solver fast paths deliberately remain co-located in `solver.js` until a
 split can demonstrate benchmark parity.  A cleaner file layout is not worth a
 runtime regression.
+
+Performance claims use the wall-clock workloads in `test/bench/`, not predicate,
+inference, or host-call counts as a substitute for elapsed time. Each benchmark
+runs in its own Node process, warms the engine before measured parse+execute
+runs, reports the median, and verifies a committed output SHA-256 before its
+timing is accepted. Machine-specific timing baselines live under `.benchmarks/`
+and are intentionally not versioned.

package/test/bench/benchmarks.json

@@ -0,0 +1,184 @@
+[
+  {
+    "name": "deep-taxonomy",
+    "group": "recursion/indexing",
+    "file": "examples/deep-taxonomy-100000.pl",
+    "goals": [
+      "result(report, success)"
+    ],
+    "expectedSha256": "a0aa24fcbc87c394a4da789ac861b8e18cabad5e0d73b25ddc02df5dd4376c1b"
+  },
+  {
+    "name": "clpz-sudoku",
+    "group": "clpz",
+    "file": "examples/clpz-sudoku-9x9.pl",
+    "goals": [
+      "sudoku9_solution(X0)"
+    ],
+    "expectedSha256": "0eed3bcf38498cb514143adb2e475d8e48b0326bcf329fbedb6a3b0e87646731"
+  },
+  {
+    "name": "clpb-weighted-planning",
+    "group": "clpb",
+    "file": "examples/clpb-weighted-planning.pl",
+    "goals": [
+      "best_release_plan(X0, X1)"
+    ],
+    "expectedSha256": "52f2cc7d22873accef7968f89aea3584fb3304b2dceb555428e79477b41f0b5d"
+  },
+  {
+    "name": "clpb-cardinality",
+    "group": "clpb",
+    "file": "examples/clpb-cardinality.pl",
+    "goals": [
+      "review_quorum_count(X0)"
+    ],
+    "expectedSha256": "a643a582baefc95da37b0ccf9609a2241aeb7cfe559e2636bb439c05c50e2177"
+  },
+  {
+    "name": "tabling-cycle",
+    "group": "tabling",
+    "file": "examples/cyclic-path.pl",
+    "goals": [
+      "path(X0, X1)"
+    ],
+    "expectedSha256": "5580a2782c6896ffdf36bd6cc242931e96e1722b154976c1a20e7cad1206566f"
+  },
+  {
+    "name": "tabling-chart-parser",
+    "group": "tabling",
+    "file": "examples/chart-parser.pl",
+    "goals": [
+      "chart_parser_answer(X0, X1)"
+    ],
+    "expectedSha256": "70707d3026aabc65982b82b9617a15d3de6cbb5fa6cdb2ee955bedd4f29f0e5a"
+  },
+  {
+    "name": "wfs-policy",
+    "group": "wfs",
+    "file": "examples/odrl-policy-reasoning.pl",
+    "goals": [
+      "wfsQuestion(X0, X1)"
+    ],
+    "expectedSha256": "b4a153234f3daf1e2ba6c26843349a1bc1919ebd9f9e98559835eb5ef915716b"
+  },
+  {
+    "name": "dcg-command",
+    "group": "dcg",
+    "file": "examples/dcg-command-parser.pl",
+    "goals": [
+      "dcg_example(X0, X1)"
+    ],
+    "expectedSha256": "6f640fb0d327eb9139d3568cf7a86ad55a52afdbb0208ca35a70419be2bf1b9c"
+  },
+  {
+    "name": "dcg-expression",
+    "group": "dcg",
+    "file": "examples/dcg-expression-language.pl",
+    "goals": [
+      "dcg_expression_example(X0, X1)"
+    ],
+    "expectedSha256": "562985450257f1db8c67682c6184102622b4e6946f2cb0abd3ac15bde493f5d5"
+  },
+  {
+    "name": "eyelet-forward",
+    "group": "eyelet",
+    "file": "test/bench/eyelet-forward.pl",
+    "goals": [],
+    "expectedSha256": "127277f2ba5c02d41143b22ac0ae069596a4a7dd4dc71079f3dff1319ca019cc"
+  },
+  {
+    "name": "takeuchi",
+    "group": "recursive-control",
+    "file": "examples/takeuchi.pl",
+    "goals": [
+      "tak([34, 13, 8], X0)"
+    ],
+    "expectedSha256": "a7c33872b86aa7877b9c38ec41c447fc96a328d40f512428993d662f28a097ad"
+  },
+  {
+    "name": "clpz-register-allocation",
+    "group": "clpz",
+    "file": "examples/register-allocation.pl",
+    "goals": [
+      "registerAnswer(X0, X1)"
+    ],
+    "expectedSha256": "1ed0b4a90deff2908463774d0025210d58b89366efb5d82b94ff5b51daca046b"
+  },
+  {
+    "name": "clpb-feature-model",
+    "group": "clpb",
+    "file": "examples/clpb-feature-model.pl",
+    "goals": [
+      "feature_plan(X0)"
+    ],
+    "expectedSha256": "47abfd8a87efb595ffb11c6c8cbda3cb5855e95124bc574e3cae387c12318f33"
+  },
+  {
+    "name": "attributed-variables",
+    "group": "attributes",
+    "file": "examples/attributed-variables.pl",
+    "goals": [
+      "accepts_required_value(X0)",
+      "alias_preserves_attribute(X0)"
+    ],
+    "expectedSha256": "3d60cd3464f2aae44ad01859e838fc2b8754e35916bafe3bba66ca745f77c236"
+  },
+  {
+    "name": "dif-constraints",
+    "group": "constraints",
+    "file": "examples/dif-constraints.pl",
+    "goals": [
+      "allowed_pair(X0, X1)",
+      "specialization(X0, X1)"
+    ],
+    "expectedSha256": "b6268a6653d02f7312f73406612b451d030a3766931e093003c3642cc170009d"
+  },
+  {
+    "name": "dijkstra-findall-sort",
+    "group": "search/collections",
+    "file": "examples/dijkstra-findall-sort.pl",
+    "goals": [
+      "shortestPath(X0, X1)",
+      "cost(X0, X1)"
+    ],
+    "expectedSha256": "1318aaaca44aa19f295f988d87b09165cd0fc279e94ae14c10e2d1f146d544f3"
+  },
+  {
+    "name": "iso-term-io",
+    "group": "term-io",
+    "file": "examples/iso-term-io.pl",
+    "goals": [
+      "report(X0, X1)"
+    ],
+    "expectedSha256": "0719932d697e7587285082b558f4c39c04ec1f2222131073e73e6b6fe37e0320"
+  },
+  {
+    "name": "symbolic-derivative",
+    "group": "term-rewriting",
+    "file": "examples/symbolic-derivative.pl",
+    "goals": [
+      "derivative_result(X0, X1)"
+    ],
+    "expectedSha256": "49f9f33e89e8c8c63ce2eb64ea2639e416869d6ef5db185cab70452d1f77f342"
+  },
+  {
+    "name": "sat-dpll",
+    "group": "search/control",
+    "file": "examples/sat-solver-dpll.pl",
+    "goals": [
+      "satModel(X0)",
+      "satValue(X0, X1)"
+    ],
+    "expectedSha256": "a8c5cdddac5efcb7d5b1031200d3bbc5b78c1668928a45e064377432f05b3c9f"
+  },
+  {
+    "name": "type-inference",
+    "group": "unification",
+    "file": "examples/type-inference.pl",
+    "goals": [
+      "type_answer(X0, X1)"
+    ],
+    "expectedSha256": "acad9ddb995d9ddef091e17cc91659d36ed7f9014d6714fd40100d85a53ae203"
+  }
+]

package/test/bench/eyelet-forward.pl

@@ -0,0 +1,58 @@
+% Synthetic Eyelet fixed-point benchmark.
+% The chain is intentionally moderate: large enough to exercise repeated
+% forward-rule rounds without making the default benchmark suite unwieldy.
+
+reach(0).
+edge(0, 1).
+edge(1, 2).
+edge(2, 3).
+edge(3, 4).
+edge(4, 5).
+edge(5, 6).
+edge(6, 7).
+edge(7, 8).
+edge(8, 9).
+edge(9, 10).
+edge(10, 11).
+edge(11, 12).
+edge(12, 13).
+edge(13, 14).
+edge(14, 15).
+edge(15, 16).
+edge(16, 17).
+edge(17, 18).
+edge(18, 19).
+edge(19, 20).
+edge(20, 21).
+edge(21, 22).
+edge(22, 23).
+edge(23, 24).
+edge(24, 25).
+edge(25, 26).
+edge(26, 27).
+edge(27, 28).
+edge(28, 29).
+edge(29, 30).
+edge(30, 31).
+edge(31, 32).
+edge(32, 33).
+edge(33, 34).
+edge(34, 35).
+edge(35, 36).
+edge(36, 37).
+edge(37, 38).
+edge(38, 39).
+edge(39, 40).
+edge(40, 41).
+edge(41, 42).
+edge(42, 43).
+edge(43, 44).
+edge(44, 45).
+edge(45, 46).
+edge(46, 47).
+edge(47, 48).
+edge(48, 49).
+edge(49, 50).
+
+reach(Y) :+ reach(X), edge(X, Y).
+true :+ reach(50).

package/test/benchmark-core.mjs

@@ -0,0 +1,94 @@
+import crypto from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { run } from '../index.js';
+
+function digest(text) {
+  return crypto.createHash('sha256').update(text).digest('hex');
+}
+
+function nextPowerOfTwo(value) {
+  let power = 1;
+  while (power < value && power < 1024) power *= 2;
+  return power;
+}
+
+export function measureBenchmark(source, goals, { runs = 5, warmup = 1, targetMs = 400 } = {}) {
+  let referenceStdout = null;
+  let referenceDigest = null;
+  let answerLines = null;
+  let outputBytes = null;
+
+  function execute() {
+    return run(source, { goals });
+  }
+
+  function validateResult(result) {
+    if (result.haltCode != null) throw new Error(`benchmark halted with code ${result.haltCode}`);
+    if (referenceStdout == null) {
+      referenceStdout = result.stdout;
+      referenceDigest = digest(result.stdout);
+      answerLines = result.stdout.split('\n').filter((line) => line.length > 0).length;
+      outputBytes = Buffer.byteLength(result.stdout);
+    } else if (result.stdout !== referenceStdout) {
+      throw new Error(`non-deterministic output digest: ${referenceDigest} != ${digest(result.stdout)}`);
+    }
+  }
+
+  function runBatch(batchSize) {
+    const results = new Array(batchSize);
+    const started = performance.now();
+    for (let i = 0; i < batchSize; i++) results[i] = execute();
+    const elapsed = performance.now() - started;
+    for (const result of results) validateResult(result);
+    return elapsed;
+  }
+
+  let batchSize = 1;
+  let calibrationMs = 0;
+  if (targetMs > 0) {
+    runBatch(1); // prime parser/JIT/module state before sizing the measured batch
+    calibrationMs = runBatch(1);
+    if (calibrationMs < targetMs) {
+      batchSize = nextPowerOfTwo(Math.ceil(targetMs / Math.max(calibrationMs, 0.01)));
+      calibrationMs = runBatch(batchSize);
+      while (calibrationMs < targetMs * 0.8 && batchSize < 1024) {
+        batchSize = Math.min(batchSize * 2, 1024);
+        calibrationMs = runBatch(batchSize);
+      }
+      while (calibrationMs > targetMs * 2 && batchSize > 1) {
+        batchSize = Math.max(Math.floor(batchSize / 2), 1);
+        calibrationMs = runBatch(batchSize);
+      }
+    }
+  }
+
+  for (let i = 0; i < warmup; i++) runBatch(batchSize);
+
+  // Warm-up can materially change short-workload cost. Re-check the chosen batch
+  // in the warmed state and grow it until samples are long enough to be useful.
+  if (targetMs > 0) {
+    calibrationMs = runBatch(batchSize);
+    while (calibrationMs < targetMs * 0.8 && batchSize < 1024) {
+      batchSize = Math.min(batchSize * 2, 1024);
+      calibrationMs = runBatch(batchSize);
+    }
+  }
+
+  const samplesMs = [];
+  const batchSamplesMs = [];
+  for (let i = 0; i < runs; i++) {
+    const elapsed = runBatch(batchSize);
+    batchSamplesMs.push(elapsed);
+    samplesMs.push(elapsed / batchSize);
+  }
+
+  return {
+    digest: referenceDigest,
+    answerLines,
+    outputBytes,
+    batchSize,
+    calibrationMs,
+    batchSamplesMs,
+    samplesMs,
+  };
+}

package/test/benchmark-worker.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { measureBenchmark } from './benchmark-core.mjs';
+
+function parseInteger(value, name, minimum) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < minimum) throw new Error(`${name} must be an integer >= ${minimum}`);
+  return number;
+}
+
+function parseNumber(value, name, minimum) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < minimum) throw new Error(`${name} must be a number >= ${minimum}`);
+  return number;
+}
+
+const [fileArg, goalsJson = '[]', runsArg = '5', warmupArg = '1', targetMsArg = '400'] = process.argv.slice(2);
+if (!fileArg) throw new Error('benchmark worker requires a file');
+const goals = JSON.parse(goalsJson);
+if (!Array.isArray(goals) || !goals.every((goal) => typeof goal === 'string')) throw new Error('benchmark worker goals must be a JSON array of strings');
+const source = await fs.readFile(path.resolve(fileArg), 'utf8');
+const result = measureBenchmark(source, goals, {
+  runs: parseInteger(runsArg, 'runs', 1),
+  warmup: parseInteger(warmupArg, 'warmup', 0),
+  targetMs: parseNumber(targetMsArg, 'targetMs', 0),
+});
+process.stdout.write(`${JSON.stringify(result)}\n`);

package/test/benchmark.mjs

@@ -0,0 +1,228 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const manifestPath = path.join(root, 'test', 'bench', 'benchmarks.json');
+const defaultBaselinePath = path.join(root, '.benchmarks', 'baseline.json');
+
+function usage() {
+  process.stdout.write(`EyeProlog benchmark runner\n\nUsage:\n  node test/benchmark.mjs [options]\n\nOptions:\n  --runs N             Measured batches per benchmark (default: 5)\n  --warmup N           Warm-up batches per benchmark (default: 1)\n  --target-ms N        Minimum target for short measured batches (default: 400)\n  --filter TEXT        Run benchmarks whose name or group contains TEXT\n  --baseline FILE      Compare against a saved timing baseline\n  --save FILE          Save current medians as a timing baseline\n  --json               Print machine-readable JSON\n  --list               List benchmark names and exit\n  -h, --help           Show this help\n\nAfter one untimed priming execution, short workloads are automatically repeated\nin independent run() executions until a measured batch lasts about --target-ms. The report divides batch time by the\niteration count, so all results remain milliseconds per workload execution.\nOutput digests are always checked against the committed semantic checksums in\ntest/bench/benchmarks.json.\n`);
+}
+
+function parseInteger(value, name, minimum) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < minimum) {
+    throw new Error(`${name} must be an integer >= ${minimum}`);
+  }
+  return number;
+}
+
+function parseNumber(value, name, minimum) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < minimum) {
+    throw new Error(`${name} must be a number >= ${minimum}`);
+  }
+  return number;
+}
+
+const options = {
+  runs: 5,
+  warmup: 1,
+  targetMs: 400,
+  filter: null,
+  baseline: null,
+  save: null,
+  json: false,
+  list: false,
+};
+
+for (let i = 2; i < process.argv.length; i++) {
+  const arg = process.argv[i];
+  if (arg === '--runs') options.runs = parseInteger(process.argv[++i], '--runs', 1);
+  else if (arg === '--warmup') options.warmup = parseInteger(process.argv[++i], '--warmup', 0);
+  else if (arg === '--target-ms') options.targetMs = parseNumber(process.argv[++i], '--target-ms', 0);
+  else if (arg === '--filter') options.filter = process.argv[++i] ?? '';
+  else if (arg === '--baseline') options.baseline = path.resolve(process.argv[++i] ?? '');
+  else if (arg === '--save') options.save = path.resolve(process.argv[++i] ?? '');
+  else if (arg === '--json') options.json = true;
+  else if (arg === '--list') options.list = true;
+  else if (arg === '--help' || arg === '-h') { usage(); process.exit(0); }
+  else throw new Error(`unknown option: ${arg}`);
+}
+
+const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+if (!Array.isArray(manifest) || manifest.length === 0) throw new Error('benchmark manifest is empty');
+
+const names = new Set();
+for (const item of manifest) {
+  if (!item || typeof item.name !== 'string' || typeof item.group !== 'string' || typeof item.file !== 'string') {
+    throw new Error('invalid benchmark manifest entry');
+  }
+  if (names.has(item.name)) throw new Error(`duplicate benchmark name: ${item.name}`);
+  names.add(item.name);
+  if (!Array.isArray(item.goals) || !item.goals.every((goal) => typeof goal === 'string')) {
+    throw new Error(`invalid goals for benchmark ${item.name}`);
+  }
+  if (!/^[0-9a-f]{64}$/.test(item.expectedSha256)) {
+    throw new Error(`invalid expectedSha256 for benchmark ${item.name}`);
+  }
+}
+
+const selected = manifest.filter((item) => {
+  if (options.filter == null) return true;
+  const needle = options.filter.toLowerCase();
+  return item.name.toLowerCase().includes(needle) || item.group.toLowerCase().includes(needle);
+}).sort((a, b) => a.name.localeCompare(b.name));
+if (selected.length === 0) throw new Error(`no benchmarks match filter: ${options.filter}`);
+
+if (options.list) {
+  for (const item of selected) process.stdout.write(`${item.name}\t${item.group}\t${item.file}\n`);
+  process.exit(0);
+}
+
+let baselinePath = options.baseline;
+if (baselinePath == null) {
+  try {
+    await fs.access(defaultBaselinePath);
+    baselinePath = defaultBaselinePath;
+  } catch (_) {
+    baselinePath = null;
+  }
+}
+
+let baseline = null;
+let baselineWarning = null;
+if (baselinePath != null) {
+  const loaded = JSON.parse(await fs.readFile(baselinePath, 'utf8'));
+  if (loaded.format === 2) baseline = loaded;
+  else {
+    baselineWarning = `Ignoring legacy timing baseline format ${loaded.format ?? 'unknown'}; regenerate it with npm run benchmark:baseline.`;
+    baselinePath = null;
+  }
+}
+
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle];
+}
+
+function formatMs(value) {
+  if (value == null) return '—';
+  return `${value.toFixed(1)} ms`;
+}
+
+function changePercent(medianMs, baselineMs) {
+  if (baselineMs == null || baselineMs === 0) return null;
+  return ((medianMs - baselineMs) / baselineMs) * 100;
+}
+
+function changeText(item) {
+  if (item.changePercent == null) return '—';
+  const change = item.changePercent;
+  const value = `${change >= 0 ? '+' : ''}${change.toFixed(1)}%`;
+  if (Math.abs(change) < 5) return `≈ ${value}`;
+  return `${change < 0 ? '↓' : '↑'} ${value}`;
+}
+
+function runWorker(item) {
+  const child = spawnSync(process.execPath, [
+    path.join(root, 'test', 'benchmark-worker.mjs'),
+    path.join(root, item.file),
+    JSON.stringify(item.goals),
+    String(options.runs),
+    String(options.warmup),
+    String(options.targetMs),
+  ], { cwd: root, encoding: 'utf8', maxBuffer: 10 * 1024 * 1024, timeout: 120_000 });
+  if (child.error) throw new Error(`${item.name} failed: ${child.error.message}`);
+  if (child.status !== 0) {
+    throw new Error(`${item.name} failed${child.stderr ? `: ${child.stderr.trim()}` : ''}`);
+  }
+  try { return JSON.parse(child.stdout); }
+  catch (error) { throw new Error(`${item.name} returned invalid worker output: ${error.message}`); }
+}
+
+const results = [];
+for (const item of selected) {
+  if (!options.json) process.stderr.write(`benchmark ${item.name}...\n`);
+  const worker = runWorker(item);
+  if (worker.digest !== item.expectedSha256) {
+    throw new Error(`${item.name} semantic checksum changed: expected ${item.expectedSha256}, got ${worker.digest}`);
+  }
+  const medianMs = median(worker.samplesMs);
+  const minMs = Math.min(...worker.samplesMs);
+  const maxMs = Math.max(...worker.samplesMs);
+  const baselineItem = baseline?.benchmarks?.[item.name] ?? null;
+  results.push({
+    name: item.name,
+    group: item.group,
+    file: item.file,
+    goals: item.goals,
+    medianMs,
+    minMs,
+    maxMs,
+    batchSize: worker.batchSize,
+    calibrationMs: worker.calibrationMs,
+    batchSamplesMs: worker.batchSamplesMs,
+    samplesMs: worker.samplesMs,
+    answerLines: worker.answerLines,
+    outputBytes: worker.outputBytes,
+    sha256: worker.digest,
+    baselineMs: baselineItem?.medianMs ?? null,
+    changePercent: changePercent(medianMs, baselineItem?.medianMs ?? null),
+  });
+}
+
+if (options.save != null) {
+  await fs.mkdir(path.dirname(options.save), { recursive: true });
+  const saved = {
+    format: 2,
+    generatedAt: new Date().toISOString(),
+    node: process.version,
+    platform: `${process.platform}-${process.arch}`,
+    runs: options.runs,
+    warmup: options.warmup,
+    targetMs: options.targetMs,
+    benchmarks: Object.fromEntries(results.map((item) => [item.name, {
+      medianMs: item.medianMs,
+      batchSize: item.batchSize,
+      sha256: item.sha256,
+    }])),
+  };
+  await fs.writeFile(options.save, `${JSON.stringify(saved, null, 2)}\n`);
+}
+
+if (options.json) {
+  process.stdout.write(`${JSON.stringify({
+    runs: options.runs,
+    warmup: options.warmup,
+    targetMs: options.targetMs,
+    baseline: baselinePath,
+    baselineWarning,
+    results,
+  }, null, 2)}\n`);
+} else {
+  const headers = ['Benchmark', 'Median/op', 'Range/op', 'Batch', 'Baseline', 'Change', 'Answers'];
+  const rows = results.map((item) => [
+    item.name,
+    formatMs(item.medianMs),
+    `${formatMs(item.minMs)}–${formatMs(item.maxMs)}`,
+    String(item.batchSize),
+    formatMs(item.baselineMs),
+    changeText(item),
+    String(item.answerLines),
+  ]);
+  const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index].length)));
+  const printRow = (row) => process.stdout.write(`${row.map((cell, index) => cell.padEnd(widths[index])).join('  ')}\n`);
+  printRow(headers);
+  printRow(widths.map((width) => '-'.repeat(width)));
+  for (const row of rows) printRow(row);
+  process.stdout.write(`\n${results.length} benchmarks; ${options.runs} measured batch${options.runs === 1 ? '' : 'es'} each after ${options.warmup} warm-up batch${options.warmup === 1 ? '' : 'es'}, calibrated after one priming execution toward ${options.targetMs} ms per batch.\n`);
+  if (baselineWarning) process.stdout.write(`${baselineWarning}\n`);
+  if (baselinePath == null && !baselineWarning) process.stdout.write('No timing baseline found; run npm run benchmark:baseline to create .benchmarks/baseline.json.\n');
+  if (options.save != null) process.stdout.write(`Saved timing baseline: ${path.relative(root, options.save)}\n`);
+  process.stdout.write('Change compares the current median/op directly with the saved baseline median/op; the measured range is shown separately.\n');
+}

package/test/run-benchmark-tests.mjs

@@ -0,0 +1,73 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const manifest = JSON.parse(await fs.readFile(path.join(root, 'test', 'bench', 'benchmarks.json'), 'utf8'));
+
+let passed = 0;
+function ok(condition, message) {
+  if (!condition) throw new Error(message);
+  passed++;
+}
+
+function spawnJson(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0) return reject(new Error(stderr || `child exited ${code}`));
+      try { resolve(JSON.parse(stdout)); }
+      catch (error) { reject(new Error(`invalid child JSON: ${error.message}`)); }
+    });
+  });
+}
+
+function runWorker(item) {
+  return spawnJson([
+    path.join(root, 'test', 'benchmark-worker.mjs'),
+    path.join(root, item.file),
+    JSON.stringify(item.goals),
+    '1',
+    '0',
+    '0',
+  ]);
+}
+
+ok(Array.isArray(manifest) && manifest.length === 20, 'benchmark manifest should contain exactly 20 representative workloads');
+ok(new Set(manifest.map((item) => item.name)).size === manifest.length, 'benchmark names should be unique');
+
+for (const item of manifest) {
+  ok(/^[0-9a-f]{64}$/.test(item.expectedSha256), `${item.name} should have a committed semantic checksum`);
+  await fs.access(path.join(root, item.file));
+  passed++;
+
+  const worker = await runWorker(item);
+  ok(worker.digest === item.expectedSha256, `${item.name} should preserve its committed semantic checksum`);
+  ok(worker.batchSize === 1, `${item.name} digest test should use one execution per batch`);
+  ok(Array.isArray(worker.samplesMs) && worker.samplesMs.length === 1, `${item.name} should return one requested sample`);
+  ok(worker.samplesMs[0] >= 0, `${item.name} should return a non-negative wall time`);
+}
+
+const adaptive = await spawnJson([
+  path.join(root, 'test', 'benchmark.mjs'),
+  '--filter', 'dcg-command',
+  '--runs', '1',
+  '--warmup', '0',
+  '--target-ms', '50',
+  '--json',
+]);
+ok(adaptive.results.length === 1, 'adaptive benchmark smoke test should select one workload');
+ok(adaptive.results[0].batchSize > 1, 'adaptive benchmark smoke test should batch a short workload');
+ok(adaptive.results[0].sha256 === manifest.find((item) => item.name === 'dcg-command').expectedSha256,
+  'adaptive batching should preserve the semantic checksum');
+
+process.stdout.write(`Benchmark harness tests: ${passed}/${passed} passed.\n`);

package/the-art-of-eyeprolog.md

@@ -3147,7 +3147,12 @@ Before replacing one definition with another, record:
 
 Then compare both versions. `--stats` can show fewer calls or unifications, but
 performance evidence comes after semantic evidence. A faster program that
-silently drops a mode is a different program.
+silently drops a mode is a different program. Predicate and inference counts are
+also not reliable substitutes for elapsed time: one expensive host call can cost
+more than thousands of cheap Prolog calls. Repository-level performance work
+therefore uses `npm run benchmark`, which measures median wall-clock parse+execute
+time over representative workloads and rejects any run whose answer checksum no
+longer matches the committed result.
 
 **Exercises.**
 
@@ -7858,6 +7863,30 @@ with:
 npm test
 ```
 
+Performance is checked separately so ordinary correctness tests stay deterministic
+and fast:
+
+```sh
+npm run benchmark
+npm run benchmark:baseline
+```
+
+The benchmark suite contains 20 representative workloads and stores their
+semantic output digests in the repository, while wall-clock baselines remain
+machine-local under `.benchmarks/` because absolute timings are machine-specific.
+Each benchmark runs in its own fresh Node worker. Inside that worker, one untimed
+execution primes parser, module, and JIT state; short workloads are then repeated
+with independent `run()` calls until a batch is roughly 400 ms long. After one
+warm-up batch, five measured batches are reported as milliseconds per workload
+execution. Naturally long workloads keep a batch size of one.
+
+The report shows the median, per-operation range, chosen batch size, saved
+baseline median, and the percentage change between the current median and baseline
+median. The range remains visible as context, but it does not suppress or reinterpret
+the median-to-median comparison. Older unbatched baseline files are ignored with a
+request to regenerate them. This keeps the rule simple: unchanged answers first,
+sufficiently long wall-clock samples second, and direct median-versus-median change.
+
 When adding an example:
 
 1. choose a filename that names the mathematical or domain idea;