eyeprolog 1.2.18 → 1.2.20

package/index.d.ts

@@ -12,6 +12,8 @@ export interface EyePrologRunOptions {
   explain?: boolean;
   maxDepth?: number;
   maxInferences?: number;
+  /** Soft JavaScript heap ceiling in bytes; exhaustion raises resource_error(memory). */
+  maxMemoryBytes?: number;
   solutionLimit?: number;
   registry?: BuiltinRegistry;
   sourceMetadata?: boolean;
@@ -171,6 +173,7 @@ export class Solver {
   maxInferences: number;
   inferences: number;
   inferenceLimitExceeded: boolean;
+  maxMemoryBytes: number;
   solutionLimit: number;
   solutionsSeen: number;
   active: unknown[];

package/package.json

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

package/src/platform.js

@@ -6,10 +6,12 @@ const isNode = typeof process !== 'undefined' && Boolean(process.versions?.node)
 let fs = null;
 let path = null;
 let BufferCtor = null;
+let v8 = null;
 
 if (isNode) {
   ({ default: fs } = await import('node:fs'));
   ({ default: path } = await import('node:path'));
+  ({ default: v8 } = await import('node:v8'));
   BufferCtor = globalThis.Buffer ?? null;
 }
 
@@ -18,3 +20,43 @@ export { fs, path, BufferCtor, isNode };
 export function currentWorkingDirectory() {
   return isNode && typeof process.cwd === 'function' ? process.cwd() : '/';
 }
+
+export function usedHeapSize() {
+  if (isNode && typeof process.memoryUsage === 'function') {
+    return process.memoryUsage().heapUsed;
+  }
+  const memory = globalThis.performance?.memory;
+  return Number.isFinite(memory?.usedJSHeapSize) ? memory.usedJSHeapSize : null;
+}
+
+export function softHeapLimit() {
+  let limit = null;
+  if (isNode) {
+    limit = v8?.getHeapStatistics?.().heap_size_limit ?? null;
+    const configuredOldSpace = configuredOldSpaceBytes();
+    if (configuredOldSpace != null) limit = Math.min(limit ?? Infinity, configuredOldSpace);
+  } else {
+    const memory = globalThis.performance?.memory;
+    if (Number.isFinite(memory?.jsHeapSizeLimit)) limit = memory.jsHeapSizeLimit;
+  }
+  // Leave ample room for the generator stack to unwind and for the top level
+  // to construct and print resource_error(memory). Fatal V8 OOMs cannot be
+  // caught after the heap limit itself has been reached.
+  return Number.isFinite(limit) && limit > 0 ? Math.floor(limit * 0.75) : Infinity;
+}
+
+function configuredOldSpaceBytes() {
+  if (!isNode) return null;
+  const argumentsText = [
+    ...(process.execArgv ?? []),
+    ...(String(process.env?.NODE_OPTIONS ?? '').match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []),
+  ];
+  for (let index = 0; index < argumentsText.length; index++) {
+    const argument = argumentsText[index];
+    const match = /^--max[-_]old[-_]space[-_]size(?:=(\d+))?$/.exec(argument);
+    if (!match) continue;
+    const megabytes = match[1] ?? argumentsText[index + 1];
+    if (/^\d+$/.test(megabytes ?? '')) return Number(megabytes) * 1024 * 1024;
+  }
+  return null;
+}

package/src/repl.js

@@ -488,8 +488,15 @@ async function solveQuery(engine, state, goal, reader, output) {
   let automatic = 0;
   let answersShown = 0;
   let firstAnswer = true;
+  let formattingAfterAdvance = false;
   while (!current.result.done) {
     const next = pullSolution(solver, solutions, reader);
+    // The control prompt has no trailing space while it waits for input. The
+    // first space appears as soon as the user requests another solution and
+    // remains visible while pullSolution() computes; the second appears only
+    // when the requested leaf answer is ready to format.
+    if (formattingAfterAdvance) output.write(' ');
+    formattingAfterAdvance = false;
     output.write(current.output);
     output.write(`${firstAnswer ? '   ' : ''}${formatAnswer(engine, state, variables, current.result.value)}`);
     answersShown++;
@@ -501,14 +508,15 @@ async function solveQuery(engine, state, goal, reader, output) {
 
     if (automatic > 0 || automatic === Infinity) {
       if (automatic !== Infinity) automatic--;
-      output.write('\n;  ');
+      output.write('\n; ');
+      formattingAfterAdvance = true;
     } else {
       while (true) {
-        const controlLine = await reader.readControl('\n;  ');
+        const controlLine = await reader.readControl('\n;');
         if (controlLine == null || controlLine === '' || controlLine === '\r' || controlLine === '\n' ||
             controlLine.trimStart().startsWith('.')) {
           if (typeof solutions.return === 'function') solutions.return();
-          output.write('... .\n');
+          output.write('  ... .\n');
           return null;
         }
         const control = controlLine === ' ' ? ' ' : controlLine.trimStart()[0];
@@ -527,18 +535,22 @@ async function solveQuery(engine, state, goal, reader, output) {
           break;
         }
         if (control === 'w' || control === 'p') {
-          output.write(`${formatAnswer(engine, state, variables, current.result.value)}`);
+          output.write(`  ${formatAnswer(engine, state, variables, current.result.value)}`);
           continue;
         }
         if (control === 'h') {
           output.write(ANSWER_HELP);
           continue;
         }
-        output.write('Action? ');
+        output.write(' Action? ');
       }
+      output.write(' ');
+      formattingAfterAdvance = true;
     }
 
     if (next.error) {
+      if (formattingAfterAdvance) output.write(' ');
+      formattingAfterAdvance = false;
       output.write(next.output);
       if (next.error?.name === 'HaltSignal') return { halted: true, code: next.error.code };
       throw next.error;

package/src/solver.js

@@ -9,6 +9,7 @@ import { getEyePrologRegistry } from './standard-library.js';
 import { selectClauseCandidates, selectClauseCandidatesForValues, selectGroundClauseCandidates } from './program.js';
 import { StreamManager } from './io.js';
 import { clpzStateConsistent } from './clpz.js';
+import { softHeapLimit, usedHeapSize } from './platform.js';
 
 let freshCounter = 0;
 
@@ -47,6 +48,8 @@ export class Solver {
     this.maxInferences = options.maxInferences ?? Infinity;
     this.inferences = 0;
     this.inferenceLimitExceeded = false;
+    this.maxMemoryBytes = options.maxMemoryBytes ?? softHeapLimit();
+    this.nextMemoryCheck = 0;
     // Do not impose an implicit answer cap. Infinite and very large searches are
     // part of normal Prolog semantics; callers that need a resource bound can
     // still supply solutionLimit explicitly.
@@ -115,6 +118,7 @@ export class Solver {
       registry: this.registry,
       maxDepth: this.maxDepth,
       maxInferences: this.maxInferences,
+      maxMemoryBytes: this.maxMemoryBytes,
       solutionLimit,
       isoStrict: this.isoStrict,
       prologFlags: this.prologFlags,
@@ -177,6 +181,7 @@ export class Solver {
       this.solveStacks.push(stack);
       while (stack.length) {
       this.inferences++;
+      this.checkMemoryLimit();
       if (this.inferences > this.maxInferences) {
         this.inferenceLimitExceeded = true;
         break;
@@ -228,6 +233,7 @@ export class Solver {
 
       while (true) {
         this.inferences++;
+        this.checkMemoryLimit();
         if (this.inferences > this.maxInferences) {
           this.inferenceLimitExceeded = true;
           stack.length = 0;
@@ -411,6 +417,16 @@ export class Solver {
     return activeVariantIn(goal, env, this.active);
   }
 
+  checkMemoryLimit() {
+    if (this.inferences < this.nextMemoryCheck) return;
+    this.nextMemoryCheck = this.inferences + 256;
+    if (!Number.isFinite(this.maxMemoryBytes)) return;
+    const used = usedHeapSize();
+    if (used != null && used >= this.maxMemoryBytes) {
+      throw new PrologError('resource_error(memory)');
+    }
+  }
+
   *solveUserGoal(goal, rest, env, depth) {
     this.stats.solve_one_goal_calls++;
     if (depth > this.maxDepth) {

package/test/run-regression.mjs

@@ -790,6 +790,61 @@ c4 ?- call((!;1)).
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'REPL answer prompt distinguishes waiting from computation',
+      run: () => {
+        const helper = `
+          import { spawn } from 'node:child_process';
+
+          const child = spawn(${JSON.stringify(process.execPath)}, [${JSON.stringify(bin)}], {
+            cwd: ${JSON.stringify(packageRoot)},
+            stdio: ['pipe', 'pipe', 'pipe'],
+          });
+          child.stdout.setEncoding('utf8');
+          child.stderr.setEncoding('utf8');
+          let stdout = '';
+          let stderr = '';
+          let sawComputingPrompt = false;
+          child.stdout.on('data', (text) => {
+            stdout += text;
+            if (stdout.endsWith('\\n; ')) sawComputingPrompt = true;
+          });
+          child.stderr.on('data', (text) => { stderr += text; });
+
+          async function waitFor(predicate, label) {
+            const deadline = Date.now() + 5000;
+            while (!predicate()) {
+              if (Date.now() >= deadline) {
+                throw new Error(label + ' timeout; stdout=' + JSON.stringify(stdout) + '; stderr=' + JSON.stringify(stderr));
+              }
+              await new Promise((resolve) => setTimeout(resolve, 10));
+            }
+          }
+
+          child.stdin.write('use_module(library(prologue)).\\n');
+          await waitFor(() => stdout.includes('   true.\\n?- '), 'module import');
+          child.stdin.write('(N = 0; N = 1; (call_nth(repeat, 100000), N = 2)).\\n');
+          await waitFor(() => stdout.endsWith('   N = 0\\n;'), 'waiting prompt');
+          child.stdin.write(';\\n');
+          await waitFor(() => sawComputingPrompt, 'computing prompt');
+          await waitFor(() => stdout.endsWith(';  N = 1\\n;'), 'formatted answer');
+          child.stdin.write('\\n');
+          await waitFor(() => stdout.endsWith('  ... .\\n?- '), 'stopped enumeration');
+          child.stdin.write('halt.\\n');
+          const status = await new Promise((resolve) => child.once('exit', resolve));
+          if (status !== 0) throw new Error('child status ' + status + '; stderr=' + stderr);
+          process.stdout.write('waiting;computing;formatting');
+        `;
+        const result = spawnSync(process.execPath, [
+          '--input-type=module',
+          '--eval',
+          helper,
+        ], { cwd: packageRoot, encoding: 'utf8', timeout: 10000 });
+        if (result.error) throw result.error;
+        assertEqual(result.status, 0, `prompt helper status; stderr=${result.stderr}`);
+        assertEqual(result.stdout, 'waiting;computing;formatting', 'prompt state sequence');
+      },
+    },
     {
       name: 'REPL f stops at five-answer boundaries instead of adding five answers',
       run: () => {
@@ -2324,6 +2379,35 @@ open(X) :- candidate(X), \\+ closed(X).
         }
       },
     },
+    {
+      name: 'list allocation heap pressure becomes resource_error(memory)',
+      run: () => {
+        const engineUrl = new URL('../src/index.js', import.meta.url).href;
+        const programText = ':- use_module(library(prologue)).\n';
+        const goalText = 'length(_, I), I > 9, N is 2^I, \\+ \\+ length(_, N)';
+        const script = `
+          import { Program, Solver, Env, parseGoalText, getEyePrologRegistry } from ${JSON.stringify(engineUrl)};
+          const program = Program.parse(${JSON.stringify(programText)});
+          const solver = new Solver(program, { registry: getEyePrologRegistry() });
+          const goal = parseGoalText(${JSON.stringify(goalText)}, {
+            operatorDefinitions: [...program.operators.values()],
+          });
+          let caught = null;
+          try { [...solver.solve([goal], new Env(), 0)]; } catch (error) { caught = error; }
+          if (caught?.formal !== 'resource_error(memory)') throw caught ?? new Error('no resource error');
+          process.stdout.write(caught.formal);
+        `;
+        const result = spawnSync(process.execPath, [
+          '--max-old-space-size=64',
+          '--input-type=module',
+          '--eval',
+          script,
+        ], { 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, 'resource_error(memory)', 'heap pressure resource error');
+      },
+    },
     {
       name: 'solver honors solution limits',
       run: () => {

package/the-art-of-eyeprolog.md

@@ -1725,6 +1725,8 @@ const result = run(reasoningSource(record), {
   goal: `thermal_alert(${record.sensor})`,
   proof: true,
   maxDepth: 10_000,
+  maxInferences: 100_000,
+  maxMemoryBytes: 256 * 1024 * 1024,
   solutionLimit: 10
 });
 
@@ -1774,10 +1776,10 @@ prints numeric work counters; those counters describe this run rather than an
 additional logical answer.
 
 `run/2` accepts source text or an already parsed `Program`. Its options include
-`proof` (with `why` and `explain` as aliases), `maxDepth`, `solutionLimit`, a
-custom `registry`, and `strictNegation` or `analyzeNegation`. It returns
-`stdout`, the solver's numeric `stats`, and a nullable `haltCode`; it does not
-write to the process streams.
+`proof` (with `why` and `explain` as aliases), `maxDepth`, `maxInferences`,
+`maxMemoryBytes`, `solutionLimit`, a custom `registry`, and `strictNegation` or
+`analyzeNegation`. It returns `stdout`, the solver's numeric `stats`, and a
+nullable `haltCode`; it does not write to the process streams.
 
 For applications that inspect or prepare a theory before running it, use
 `Program` directly:
@@ -1800,18 +1802,24 @@ console.log(path?.recursive, path?.tabled, path?.tableInputPositions);
 
 const solver = new Solver(program, {
   maxDepth: 50_000,
+  maxInferences: 1_000_000,
+  maxMemoryBytes: 256 * 1024 * 1024,
   solutionLimit: 100_000
 });
 ```
 
-The limits are safety ceilings, not logical declarations. Reaching one may
-truncate search; it does not prove that no further answer exists. At the `Solver`
-API boundary, `solutionLimit` is opt-in: if it is omitted, ordinary solving and
-child searches that inherit the solver limit do not stop after a fixed number of
-solutions. This matters for re-executable goals such as `repeat/0` and for
-library relations such as `call_nth/2`; an implementation safety threshold must
-not turn a still re-executable search into logical failure. Embedders that need
-a finite answer budget should pass `solutionLimit` explicitly.
+The limits are safety ceilings, not logical declarations. Reaching the depth,
+inference, or solution ceiling may truncate search; it does not prove that no
+further answer exists. Reaching `maxMemoryBytes` instead raises
+`resource_error(memory)`, because continuing until the JavaScript engine's hard
+heap limit would let the host abort before Prolog could report an exception. At
+the `Solver` API boundary, `solutionLimit` is opt-in: if it is omitted, ordinary
+solving and child searches that inherit the solver limit do not stop after a
+fixed number of solutions. This matters for re-executable goals such as
+`repeat/0` and for library relations such as `call_nth/2`; an implementation
+safety threshold must not turn a still re-executable search into logical
+failure. Embedders that need a finite answer budget should pass `solutionLimit`
+explicitly.
 
 Variable term order is deliberately scoped rather than stored as a permanent
 property of a variable. ISO 13211-1 section 7.2.1 leaves the order of two
@@ -1822,10 +1830,15 @@ sorting step of `setof/3` share one ranking for the duration of that single
 sorted-list operation. No process-global variable registry or creation ordinal
 is retained or exposed through later comparisons.
 
-Host capacity failures that V8 reports as `Map maximum size exceeded` or `Set`
-`maximum size exceeded` are normalized at the solver boundary to
-`resource_error(memory)` instead of leaking a JavaScript `RangeError`. ISO
-13211-1 leaves the resource atom implementation dependent. EyeProlog uses
+EyeProlog periodically checks detectable JavaScript heap use and keeps a quarter
+of the host heap ceiling in reserve so the solver can unwind and report
+`resource_error(memory)` before a fatal host out-of-memory abort. Embedders may
+replace that automatically derived soft ceiling with `maxMemoryBytes`; setting
+it to `Infinity` disables the proactive check. Environments that do not expose
+heap use cannot provide the proactive check. Host capacity failures that V8
+reports as `Map maximum size exceeded` or `Set maximum size exceeded` are also
+normalized at the solver boundary instead of leaking a JavaScript `RangeError`.
+ISO 13211-1 leaves the resource atom implementation dependent. EyeProlog uses
 `memory` for a finite host allocation/capacity ceiling and reserves the
 `finite_memory` spelling for the distinct convention where no finite amount of
 memory could complete the computation.
@@ -6271,7 +6284,9 @@ When another answer exists in an interactive terminal, press `;`, Space, or
 enumeration, `a` enumerates all remaining answers, and `f` advances to the
 next five-answer boundary (5, 10, 15, ... displayed leaf answers), regardless
 of how many answers were stepped through individually beforehand. `h` displays
-the answer-control help. While a query is actively
+the answer-control help. The answer prompt is `;` with no trailing space while
+it waits for input; after an advance command, one space marks active search and
+a second marks an answer ready for formatting. While a query is actively
 computing, EyeProlog releases readline's terminal signal handling: `Ctrl-C`
 therefore terminates the current EyeProlog process immediately, and on POSIX
 terminals `Ctrl-Z` suspends it in the usual shell-managed way. This remains a