eyeprolog 1.2.41 → 1.2.43

package/package.json

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

package/src/cli.js

@@ -4,6 +4,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
 import { goalsFromSource } from './goal-metadata.js';
+import { memoryStatistics } from './platform.js';
 
 let engineModule = null;
 let explanationModule = null;
@@ -230,9 +231,9 @@ async function runDefault(engine, program, options) {
   } catch (error) {
     if (error?.name !== 'HaltSignal') throw error;
     process.exitCode = error.code;
+  } finally {
+    if (options.stats) printStats(solver.stats);
   }
-
-  if (options.stats) printStats(solver.stats);
 }
 
 function writeExplanation(explanation, program, resolved, registry) {
@@ -259,7 +260,7 @@ Options:
   -h, --help            Show this help text and exit.
   -p, --proof           Enable proof explanations.
   -q, --quads           Run embedded quad tests and fail if any do not hold.
-  -s, --stats           Print solver statistics to stderr after execution.
+  -s, --stats           Print solver and memory statistics to stderr after execution.
   --iso-strict          Use ISO/IEC 13211-1 core + Corrigenda 1-3 only;
                         reject EyeProlog language extensions and disable automatic tabling.
   -v, --version         Show the package version and exit.
@@ -294,7 +295,7 @@ function printWarnings(program) {
 
 function printStats(stats) {
   process.stderr.write('eyeprolog stats:\n');
-  for (const [key, value] of Object.entries(stats)) {
+  for (const [key, value] of Object.entries({ ...stats, ...memoryStatistics() })) {
     process.stderr.write(`  ${key}: ${value}\n`);
   }
 }

package/src/iso.js

@@ -1715,21 +1715,22 @@ function numberListBuiltin(kind) {
     const list = deref(goal.args[1], env);
     if (value.type === VAR && list.type === VAR) throw new PrologError('instantiation_error');
     const text = numberListText(list, env, kind, value.type === NUMBER);
-    const next = env.clone();
     if (value.type === NUMBER) {
       if (text != null) {
         const parsed = parseIsoNumber(text);
         if (parsed == null) throw numberSyntaxError;
-        if (sameNumber(value, parsed)) yield next;
+        if (sameNumber(value, parsed)) yield env.clone();
         return;
       }
       const items = characters(canonicalNumberText(value)).map((ch) =>
         kind === 'chars' ? atom(ch) : numberTerm(ch.codePointAt(0)));
+      const next = env.clone();
       if (unify(goal.args[1], listFromItems(items), next)) yield next;
       return;
     }
     const parsed = parseIsoNumber(text);
     if (parsed == null) throw numberSyntaxError;
+    const next = env.clone();
     if (unify(goal.args[0], parsed, next)) yield next;
   };
 }
@@ -1979,36 +1980,59 @@ function* phraseBuiltin({ solver, goal, env }) {
     solver.absorbStatsFrom(child);
   }
 }
-export function formalErrorTerm(error) {
-  const context = error.contextTerm ?? atom('eyeprolog');
-  if (error.formalTerm != null) return compound('error', [error.formalTerm, context]);
-  const parse = (text) => {
-    const open = text.indexOf('(');
-    if (open === -1) return atom(text);
-    const name = text.slice(0, open);
-    const inner = text.slice(open + 1, -1);
-    const args = [];
-    let start = 0;
-    let depth = 0;
-    for (let i = 0; i <= inner.length; i++) {
-      const ch = inner[i];
-      if (ch === '(') depth++;
-      else if (ch === ')') depth--;
-      else if ((ch === ',' || i === inner.length) && depth === 0) {
-        args.push(parse(inner.slice(start, i).trim()));
-        start = i + 1;
-      }
+const defaultErrorContext = atom('eyeprolog');
+
+function parseFormalErrorTerm(text) {
+  const open = text.indexOf('(');
+  if (open === -1) return atom(text);
+  const name = text.slice(0, open);
+  const inner = text.slice(open + 1, -1);
+  const args = [];
+  let start = 0;
+  let depth = 0;
+  for (let i = 0; i <= inner.length; i++) {
+    const ch = inner[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    else if ((ch === ',' || i === inner.length) && depth === 0) {
+      args.push(parseFormalErrorTerm(inner.slice(start, i).trim()));
+      start = i + 1;
     }
-    return compound(name, args);
-  };
-  let formal = parse(error.formal);
+  }
+  return compound(name, args);
+}
+
+function hasDefaultGroundErrorShape(error) {
+  return error.formalTerm == null && error.culprit == null && error.contextTerm == null;
+}
+
+export function formalErrorTerm(error) {
+  // Reused processor errors can occur hundreds of thousands of times in a
+  // caught failure loop. Cache their immutable ground error/2 term on the
+  // error object itself instead of rebuilding the same tree on every catch.
+  if (hasDefaultGroundErrorShape(error) && error._groundErrorTerm != null) {
+    return error._groundErrorTerm;
+  }
+
+  const context = error.contextTerm ?? defaultErrorContext;
+  let formal = error.formalTerm ?? parseFormalErrorTerm(error.formal);
   if (error.culprit != null) {
     if (formal.type === COMPOUND) formal = compound(formal.name, [...formal.args, error.culprit]);
     else if (formal.type === ATOM && formal.name === 'uninstantiation_error') {
       formal = compound(formal.name, [error.culprit]);
     }
   }
-  return compound('error', [formal, context]);
+  const term = compound('error', [formal, context]);
+  if (hasDefaultGroundErrorShape(error)) error._groundErrorTerm = term;
+  return term;
+}
+
+function prologErrorBall(error) {
+  const term = formalErrorTerm(error);
+  // Ground terms are immutable from unification's perspective: bindings are
+  // recorded only in the catcher Env, so copying them is unnecessary.
+  if (hasDefaultGroundErrorShape(error) || termIsGround(term)) return term;
+  return freshCopy(term, new Env());
 }
 function* catchBuiltin({ solver, goal, env }) {
   const child = solver.cloneForInnerGoal();
@@ -2020,7 +2044,7 @@ function* catchBuiltin({ solver, goal, env }) {
     const ball = error instanceof ThrownTerm
       ? error.term
       : error instanceof PrologError
-        ? freshCopy(formalErrorTerm(error), new Env())
+        ? prologErrorBall(error)
         : null;
     if (ball == null) throw error;
     const recovered = env.clone();

package/src/platform.js

@@ -23,6 +23,13 @@ export function currentWorkingDirectory() {
   return isNode && typeof process.cwd === 'function' ? process.cwd() : '/';
 }
 
+function oldGenerationUsedSize() {
+  if (!isNode || typeof v8?.getHeapSpaceStatistics !== 'function') return null;
+  return v8.getHeapSpaceStatistics()
+    .filter(({ space_name: name }) => name !== 'read_only_space' && !name.startsWith('new_'))
+    .reduce((total, { space_used_size: size }) => total + size, 0);
+}
+
 export function usedHeapSize() {
   if (isNode && typeof process.memoryUsage === 'function') {
     // --max-old-space-size constrains V8's old generation, not the complete
@@ -30,11 +37,9 @@ export function usedHeapSize() {
     // with total heap use makes bursts of collectible new-space objects look
     // like retained memory. Measure the corresponding non-young spaces when
     // an old-space limit was supplied.
-    if (configuredOldSpaceLimit != null && typeof v8?.getHeapSpaceStatistics === 'function') {
-      const spaces = v8.getHeapSpaceStatistics();
-      return spaces
-        .filter(({ space_name: name }) => name !== 'read_only_space' && !name.startsWith('new_'))
-        .reduce((total, { space_used_size: size }) => total + size, 0);
+    if (configuredOldSpaceLimit != null) {
+      const oldGeneration = oldGenerationUsedSize();
+      if (oldGeneration != null) return oldGeneration;
     }
     return process.memoryUsage().heapUsed;
   }
@@ -42,6 +47,31 @@ export function usedHeapSize() {
   return Number.isFinite(memory?.usedJSHeapSize) ? memory.usedJSHeapSize : null;
 }
 
+export function memoryStatistics() {
+  const stats = {};
+  if (isNode && typeof process.memoryUsage === 'function') {
+    const memory = process.memoryUsage();
+    stats.memory_heap_used_bytes = memory.heapUsed;
+    const oldGeneration = oldGenerationUsedSize();
+    if (oldGeneration != null) stats.memory_old_generation_used_bytes = oldGeneration;
+    stats.memory_guard_used_bytes = configuredOldSpaceLimit != null && oldGeneration != null
+      ? oldGeneration
+      : memory.heapUsed;
+    stats.memory_rss_bytes = memory.rss;
+  } else {
+    const memory = globalThis.performance?.memory;
+    if (Number.isFinite(memory?.usedJSHeapSize)) {
+      stats.memory_heap_used_bytes = memory.usedJSHeapSize;
+      stats.memory_guard_used_bytes = memory.usedJSHeapSize;
+    }
+  }
+  const softLimit = softHeapLimit();
+  const hardLimit = hardHeapLimit();
+  if (Number.isFinite(softLimit)) stats.memory_soft_limit_bytes = softLimit;
+  if (Number.isFinite(hardLimit)) stats.memory_hard_limit_bytes = hardLimit;
+  return stats;
+}
+
 export function softHeapLimit() {
   const limit = hardHeapLimit();
   // Leave ample room for the generator stack to unwind and for the top level

package/src/standard-library.js

@@ -2,9 +2,10 @@
 // The sources are registered here so library(Name) works in Node and browsers;
 // unlike the former autoloader, no clauses are added unless use_module/1 or
 // use_module/2 requests their module.
-import { createDefaultRegistry, eyePrologLibraryBuiltins } from './iso.js';
+import { PrologError, createDefaultRegistry, eyePrologLibraryBuiltins } from './iso.js';
 import { clpzBuiltins } from './clpz.js';
-import { fs, isNode } from './platform.js';
+import { fs, isNode, memoryStatistics } from './platform.js';
+import { ATOM, VAR, atom, deref, numberTerm, unify } from './term.js';
 
 const moduleFiles = Object.freeze({
   aggregate: 'aggregate.pl',
@@ -73,8 +74,44 @@ export const eyePrologLibraryIndicators = Object.freeze([
   ...eyePrologNativeLibraryIndicators,
 ]);
 
+function runtimeStatistics(solver) {
+  return { ...solver.stats, ...memoryStatistics() };
+}
+
+function* statisticsBuiltin({ solver, env }) {
+  const stream = solver.io.resolve(solver.io.currentOutput);
+  if (stream?.type !== 'text') throw new PrologError('permission_error(output, binary_stream)');
+  solver.io.writeUnit(stream, 'eyeprolog stats:\n');
+  for (const [key, value] of Object.entries(runtimeStatistics(solver))) {
+    solver.io.writeUnit(stream, `  ${key}: ${value}\n`);
+  }
+  yield env;
+}
+
+function* statisticsValueBuiltin({ solver, goal, env }) {
+  const snapshot = runtimeStatistics(solver);
+  const key = deref(goal.args[0], env);
+  const entries = key.type === VAR
+    ? Object.entries(snapshot)
+    : key.type === ATOM && Object.hasOwn(snapshot, key.name)
+      ? [[key.name, snapshot[key.name]]]
+      : null;
+
+  if (entries == null) {
+    if (key.type !== ATOM) throw new PrologError('type_error(atom)', key);
+    return;
+  }
+
+  for (const [name, value] of entries) {
+    const next = env.clone();
+    if (unify(goal.args[0], atom(name), next) && unify(goal.args[1], numberTerm(value), next)) yield next;
+  }
+}
+
 export function createEyePrologRegistry() {
   const registry = createDefaultRegistry();
+  registry.add('statistics', 0, statisticsBuiltin, { deterministic: true });
+  registry.add('statistics', 2, statisticsValueBuiltin);
   eyePrologLibraryBuiltins.register(registry);
   clpzBuiltins.register(registry);
   registry.eyePrologLibrary = true;

package/test/run-regression.mjs

@@ -39,6 +39,7 @@ import {
   parseProgramText,
 } from '../src/index.js';
 import { ISO_OPERATOR_DEFINITIONS, parseGoalText, parseNumberTokenText } from '../src/parser.js';
+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';
@@ -1939,13 +1940,29 @@ c4 ?- call((!;1)).
 
 
     {
-      name: '--stats prints solver statistics to stderr',
+      name: '--stats prints solver and memory statistics to stderr',
       run: () => {
         const result = runCli(['--stats', '-'], { input: '%% goal: q(X, Y)\np(a, b).\nq(X, Y) :- p(X, Y).\n' });
         assertEqual(result.status, 0, 'exit status');
         assertEqual(result.stdout, 'q(a, b).\n', 'stdout');
         assertIncludes(result.stderr, 'eyeprolog stats:\n', 'stderr');
         assertIncludes(result.stderr, '  solve_goals_calls:', 'stderr');
+        assertIncludes(result.stderr, '  memory_heap_used_bytes:', 'stderr');
+        assertIncludes(result.stderr, '  memory_old_generation_used_bytes:', 'stderr');
+        assertIncludes(result.stderr, '  memory_guard_used_bytes:', 'stderr');
+        assertIncludes(result.stderr, '  memory_rss_bytes:', 'stderr');
+        assertIncludes(result.stderr, '  memory_soft_limit_bytes:', 'stderr');
+        assertIncludes(result.stderr, '  memory_hard_limit_bytes:', 'stderr');
+      },
+    },
+    {
+      name: '--stats is still printed when a query raises an error',
+      run: () => {
+        const result = runCli(['--stats', '-'], { input: "%% goal: number_chars(N, ['x'])\n" });
+        assertEqual(result.status, 1, 'exit status');
+        assertIncludes(result.stderr, 'eyeprolog stats:\n', 'stderr');
+        assertIncludes(result.stderr, '  memory_heap_used_bytes:', 'stderr');
+        assertIncludes(result.stderr, 'eyeprolog: error(syntax_error(number))', 'stderr');
       },
     },
     {
@@ -1958,6 +1975,36 @@ c4 ?- call((!;1)).
         assertIncludes(result.stderr, '  solve_goals_calls:', 'stderr');
       },
     },
+    {
+      name: 'statistics/0 prints snapshots during execution',
+      run: () => {
+        const input = '%% goal: live\nlive :- statistics, statistics.\n';
+        const result = runCli(['-'], { input });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual((result.stdout.match(/eyeprolog stats:/g) ?? []).length, 2, 'in-run snapshot count');
+        assertIncludes(result.stdout, '  memory_guard_used_bytes:', 'stdout');
+        assertIncludes(result.stdout, 'live.\n', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'statistics/2 exposes current counters and memory values',
+      run: () => {
+        const input = '%% goal: live(Used)\nlive(Used) :- statistics(memory_guard_used_bytes, Used).\n';
+        const result = runCli(['-'], { input });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(/^live\(\d+\)\.\n$/.test(result.stdout), true, 'numeric memory statistic');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'statistics predicates are excluded from strict ISO mode',
+      run: () => {
+        const result = runCli(['--iso-strict', '-'], { input: '%% goal: statistics\n' });
+        assertEqual(result.status, 1, 'exit status');
+        assertIncludes(result.stderr, 'existence_error(procedure)', 'stderr');
+      },
+    },
     {
       name: '--warnings prints unstratified negation diagnostics without failing',
       run: () => {
@@ -2959,6 +3006,15 @@ open(X) :- candidate(X), \\+ closed(X).
         assertEqual(result.stdout, '300000', 'fresh-variable answer count');
       },
     },
+    {
+      name: 'ground Prolog error terms are reused across catches',
+      run: () => {
+        const error = new PrologError('syntax_error(number)');
+        const first = formalErrorTerm(error);
+        const second = formalErrorTerm(error);
+        assertEqual(first === second, true, 'reused ground error term');
+      },
+    },
     {
       name: 'caught number syntax errors do not exhaust memory on distinct inputs',
       run: () => {
@@ -2979,22 +3035,22 @@ open(X) :- candidate(X), \\+ closed(X).
           const goal = parseGoalText('trial(Chars)');
           let count = 0;
           for (const _ of solver.solve([goal], new Env(), 0)) {
-            if (++count === 50000) break;
+            if (++count === 250000) break;
           }
-          if (count !== 50000) throw new Error('unexpected answer count: ' + count);
+          if (count !== 250000) throw new Error('unexpected answer count: ' + count);
           process.stdout.write(String(count));
         `;
         const result = spawnSync(process.execPath, [
-          // A smaller heap preserves the original false-exhaustion signal
-          // without requiring half a million transient conversion attempts.
+          // Run well past the roughly 126,000-answer failure reported in #28
+          // while keeping the host heap deliberately constrained.
           '--max-old-space-size=32',
           '--input-type=module',
           '--eval',
           script,
-        ], { cwd: packageRoot, encoding: 'utf8', timeout: 10000 });
+        ], { cwd: packageRoot, encoding: 'utf8', timeout: 30000 });
         if (result.error) throw result.error;
         assertEqual(result.status, 0, `bounded-heap child status; stderr=${result.stderr}`);
-        assertEqual(result.stdout, '50000', 'distinct number syntax attempts');
+        assertEqual(result.stdout, '250000', 'distinct number syntax attempts');
       },
     },
     {
@@ -3179,9 +3235,13 @@ open(X) :- candidate(X), \\+ closed(X).
         assertEqual(Boolean(registry.get('is', 2)), true, 'ISO is/2 exists');
         assertEqual(Boolean(registry.get('append', 3)), false, 'append/3 is not ISO core');
         assertEqual(library.eyePrologLibrary, true, 'complete registry marker');
-        assertEqual(library.defs.size, 153, 'EyeProlog registry contains ISO definitions and private library adapters');
+        assertEqual(library.defs.size, 155, 'EyeProlog registry contains ISO definitions, observability extensions, and private library adapters');
         assertEqual(Boolean(registry.get('phrase', 2)), true, 'Part 3 phrase/2 exists');
         assertEqual(Boolean(registry.get('phrase', 3)), true, 'Part 3 phrase/3 exists');
+        assertEqual(registry.get('statistics', 0), null, 'statistics/0 is absent from the ISO registry');
+        assertEqual(registry.get('statistics', 2), null, 'statistics/2 is absent from the ISO registry');
+        assertEqual(Boolean(library.get('statistics', 0)), true, 'statistics/0 is an EyeProlog observability extension');
+        assertEqual(Boolean(library.get('statistics', 2)), true, 'statistics/2 is an EyeProlog observability extension');
         assertEqual(registeredNativeEyePrologLibraryNames().length, 40, 'public native EyeProlog builtin count');
         assertEqual(eyePrologPortableLibraryIndicators.length, 59, 'portable Prolog library count');
         assertEqual(eyePrologNativeLibraryIndicators.length, 40, 'native host library count');

package/the-art-of-eyeprolog.md

@@ -4633,7 +4633,22 @@ testing is a powerful guard during program transformation.
 `--stats` reports work, not meaning. A high solution count may be necessary or
 may indicate a generator that should be constrained. Many table hits may show
 effective reuse; many distinct table entries may reveal an argument that
-prevents calls from sharing.
+prevents calls from sharing. On the Node CLI it also reports current heap use,
+non-young/old-generation use, the amount currently compared with the memory
+guard, resident-set size, and the soft and hard memory ceilings in bytes. These
+memory figures are printed even when execution ends by raising a Prolog error.
+
+`--stats` is an end-of-run summary. For a deliberately non-terminating or very
+long computation, call the EyeProlog extension `statistics/0` at the points
+where a live snapshot is useful. For example, a long-running loop can include
+`statistics` as one of its goals, as in `loop :- work, statistics, loop.`
+
+`statistics/0` writes the current solver counters and memory figures
+immediately to the current output stream. `statistics/2` makes an individual
+value available to the program, for example
+`statistics(memory_guard_used_bytes, Used)`. With an unbound first argument it
+enumerates the available statistic keys and values. These predicates are
+EyeProlog observability extensions and are not available under `--iso-strict`.
 
 Compare statistics only between runs with the same query, data, and observable
 answer contract. A faster program that silently loses answers is not an
@@ -6406,7 +6421,7 @@ make the observed question explicit.
 | `-p`, `--proof` | Print `why/2` explanations |
 | `-q`, `--quads` | Run embedded quad tests and fail if any do not hold |
 | `--iso-strict` | Restrict parsing and execution to ISO/IEC 13211-1:1995 + Corrigenda 1–3; reject EyeProlog language extensions and disable automatic tabling |
-| `-s`, `--stats` | Print solver counters to stderr |
+| `-s`, `--stats` | Print final solver and memory statistics to stderr after execution |
 | `-v`, `--version` | Print the package version |
 | `-w`, `--warnings` | Print non-fatal portability warnings |
 | `-g`, `--goal Goal` | Solve a callable goal; may be repeated; overrides `%% goal:` comments |