eyeprolog 1.2.18 → 1.2.19

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.19",
   "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/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

@@ -2324,6 +2324,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.