eyeprolog 1.2.42 → 1.2.43

package/package.json

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

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

@@ -1975,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: () => {
@@ -3205,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

@@ -4635,9 +4635,20 @@ 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. 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, which makes `--stats` useful when reproducing bounded
-memory failures such as long-running conversion stress tests.
+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
@@ -6410,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 |