eyeprolog 1.1.13 → 1.1.14

package/README.md

@@ -91,10 +91,10 @@ noun --> [world] | [prolog].
 %% goal: phrase(sentence, Words)
 ```
 
-EyeProlog also adds 57 public library predicate indicators to its 129-entry ISO
+EyeProlog also adds 58 public library predicate indicators to its 129-entry ISO
 profile. **56 are implemented entirely as ordinary Prolog clauses** in
-`src/lib/eyeprolog.pl`, `src/lib/lists.pl`, and `src/lib/prologue.pl`; the
-`call_nth/2` module clause uses one private host adapter to number solutions.
+`src/lib/eyeprolog.pl`, `src/lib/lists.pl`, and `src/lib/prologue.pl`;
+`call_nth/2` and `freeze/2` use private host adapters for their control behavior.
 They are ISO/IEC 13211-2 modules,
 loaded explicitly with `use_module(library(eyeprolog))`,
 `use_module(library(lists))`, or `use_module(library(prologue))`. Portable text

package/index.d.ts

@@ -11,6 +11,7 @@ export interface EyePrologRunOptions {
   why?: boolean;
   explain?: boolean;
   maxDepth?: number;
+  maxInferences?: number;
   solutionLimit?: number;
   registry?: BuiltinRegistry;
   sourceMetadata?: boolean;
@@ -161,6 +162,10 @@ export class Solver {
   program: Program;
   registry: BuiltinRegistry;
   maxDepth: number;
+  depthLimitExceeded: boolean;
+  maxInferences: number;
+  inferences: number;
+  inferenceLimitExceeded: boolean;
   solutionLimit: number;
   solutionsSeen: number;
   active: unknown[];

package/package.json

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

package/src/cli.js

@@ -110,6 +110,16 @@ export async function main(argv) {
     for (const source of sourceParts) options.goals.push(...goalsFromSource(source.text));
   }
 
+  // The ISO Prolog working-example quad files assume the Prologue predicates
+  // are available as system predicates and therefore contain no use_module/1
+  // directive. Import their portable EyeProlog counterparts in quad mode.
+  if (options.quads) {
+    sourceParts.unshift({
+      text: ':- use_module(library(prologue)).\n',
+      filename: '<quad-prelude>',
+    });
+  }
+
   const engine = await loadEngine();
   let program = engine.Program.parseSources(sourceParts, { sourceMetadata: options.proof });
 

package/src/iso.js

@@ -164,12 +164,13 @@ export const isoBuiltins = {
   }
 };
 
-// call_nth/2 is a Prologue library predicate with control behavior that cannot
-// be expressed portably as ordinary Prolog clauses.  Keep the public wrapper
-// in library(prologue) and expose only this private adapter to the host registry.
+// These Prologue library predicates have control behavior that cannot be
+// expressed portably as ordinary Prolog clauses. Keep their public wrappers in
+// library(prologue) and expose only private adapters to the host registry.
 export const eyePrologLibraryBuiltins = {
   register(registry) {
     registry.add('eyeprolog__call_nth', 2, callNthBuiltin, { eyePrologLibrary: true });
+    registry.add('eyeprolog__freeze', 2, freezeBuiltin, { eyePrologLibrary: true });
   },
 };
 
@@ -1727,6 +1728,22 @@ function* callNthBuiltin({ solver, goal, env }) {
   }
 }
 
+function* freezeBuiltin({ solver, goal, env }) {
+  const watched = deref(goal.args[0], env);
+  if (watched.type !== VAR) {
+    const child = solver.cloneForInnerGoal();
+    try {
+      yield* child.solve([callable(goal.args[1], env)], env, 0);
+    } finally {
+      solver.absorbStatsFrom(child);
+    }
+    return;
+  }
+  const next = env.clone();
+  next.delay(watched.name, goal.args[1], goal.module ?? 'user');
+  yield next;
+}
+
 function* phraseBuiltin({ solver, goal, env }) {
   const grammarBody = deref(goal.args[0], env);
   if (grammarBody.type === VAR) throw new PrologError('instantiation_error');

package/src/lib/prologue.pl

@@ -19,6 +19,7 @@
     nth1/3,
     nth1/4,
     call_nth/2,
+    freeze/2,
     foldl/4,
     foldl/5,
     foldl/6,
@@ -33,6 +34,7 @@
 :- meta_predicate(maplist(6, '?', '?', '?', '?', '?', '?')).
 :- meta_predicate(maplist(7, '?', '?', '?', '?', '?', '?', '?')).
 :- meta_predicate(call_nth(0, '?')).
+:- meta_predicate(freeze('?', 0)).
 :- meta_predicate(foldl(3, '?', '?', '?')).
 :- meta_predicate(foldl(4, '?', '?', '?', '?')).
 :- meta_predicate(foldl(5, '?', '?', '?', '?', '?')).
@@ -159,6 +161,8 @@ nth1(N, List, Elem, Rest) :-
 
 call_nth(Goal, Nth) :- eyeprolog__call_nth(Goal, Nth).
 
+freeze(Var, Goal) :- eyeprolog__freeze(Var, Goal).
+
 foldl(_, [], Acc, Acc).
 foldl(Closure, [A|As], Acc0, Acc) :-
     call(Closure, A, Acc0, Acc1),

package/src/quads.js

@@ -56,12 +56,16 @@ function checkQuad(program, quad, options) {
 
 function checkDescription(program, quad, description, options) {
   const alternatives = splitOperator(description, '|');
-  for (const alternative of alternatives) {
+  // Probe an explicitly accepted nontermination outcome before alternatives
+  // that would run the same query without a bound.
+  const ordered = [...alternatives].sort((left, right) =>
+    Number(alternativeDescribesLoop(right)) - Number(alternativeDescribesLoop(left)));
+  for (const alternative of ordered) {
     const malformed = malformedAlternative(quad.query, alternative);
     if (malformed != null) return { ok: false, kind: 'malformed', expected: malformed };
   }
   let unsupported = null;
-  for (const alternative of alternatives) {
+  for (const alternative of ordered) {
     const checked = checkAlternative(program, quad, alternative, options);
     if (checked.ok) return checked;
     if (checked.kind === 'unsupported') unsupported ??= checked;
@@ -86,7 +90,10 @@ function checkAlternative(program, quad, alternative, options) {
   const maxSolutions = inputSpecs.length > 0
     ? 1
     : moreAt < 0 ? describedCount + 1 : Math.max(describedCount, 1);
-  const actual = executeQuery(program, quad.query, input, maxSolutions, options);
+  const actual = executeQuery(program, quad.query, input, maxSolutions, {
+    ...options,
+    detectLoops: leaves.some((leaf) => leaf.loops),
+  });
 
   if (inputSpecs.length > 0) {
     const leaf = leaves[0];
@@ -137,6 +144,7 @@ function describeLeaf(term) {
     sto: false,
     false: false,
     truth: false,
+    loops: false,
     error: null,
     input: null,
     output: null,
@@ -149,7 +157,8 @@ function describeLeaf(term) {
       if (item.name === 'unexpected' || item.name === 'inattendue') leaf.unexpected = true;
       else if (item.name === '...' || item.name === 'ad_infinitum') leaf.more = true;
       else if (item.name === 'sto') leaf.sto = true;
-      else if (item.name === 'loops' || item.name === 'waits' || item.name === 'other_answer_sequence') {
+      else if (item.name === 'loops') leaf.loops = true;
+      else if (item.name === 'waits' || item.name === 'other_answer_sequence') {
         leaf.unsupported ??= item;
       } else if (item.name === 'false') leaf.false = true;
       else if (item.name === 'true') leaf.truth = true;
@@ -181,7 +190,7 @@ function describeLeaf(term) {
     if (isErrorDescription(item)) leaf.error = item;
     else leaf.malformed ??= item;
   }
-  leaf.hasExpectation = leaf.bindings.length > 0 || leaf.truth || leaf.false || leaf.error != null || leaf.output != null;
+  leaf.hasExpectation = leaf.bindings.length > 0 || leaf.truth || leaf.false || leaf.loops || leaf.error != null || leaf.output != null;
   if (!leaf.hasExpectation && !leaf.more && !leaf.sto && leaf.unsupported == null) leaf.malformed ??= term;
   if ([leaf.false, leaf.truth, leaf.error != null].filter(Boolean).length > 1) leaf.malformed ??= term;
   return leaf;
@@ -192,6 +201,8 @@ function executeQuery(program, query, input, maxSolutions, options) {
   const solver = new Solver(program, {
     ...options,
     registry: options.registry ?? getEyePrologRegistry(),
+    maxDepth: options.detectLoops ? (options.loopMaxDepth ?? 1000) : options.maxDepth,
+    maxInferences: options.detectLoops ? (options.loopMaxInferences ?? 10000) : options.maxInferences,
     // The solver's counter also observes completed nested searches (for
     // example each arm of a DCG disjunction).  Bound the public iterator here
     // instead of letting those internal completions consume the quad's answer
@@ -225,10 +236,17 @@ function executeQuery(program, query, input, maxSolutions, options) {
     error = { term: errorTerm(caught), output: pendingOutput };
   }
   const inputPosition = solver.io.resolve('user_input')?.position ?? 0;
-  return { solutions, error, tailOutput, inputPosition };
+  return {
+    solutions,
+    error,
+    tailOutput,
+    inputPosition,
+    loops: solver.depthLimitExceeded || solver.inferenceLimitExceeded,
+  };
 }
 
 function matchLeaf(query, leaf, actual, position) {
+  if (leaf.loops) return actual.loops;
   if (leaf.false) {
     return position >= actual.solutions.length && actual.error == null && outputMatches(leaf.output, actual.tailOutput);
   }
@@ -241,6 +259,10 @@ function matchLeaf(query, leaf, actual, position) {
   return substitutionMatches(query, leaf.bindings, solution.env);
 }
 
+function alternativeDescribesLoop(alternative) {
+  return splitOperator(alternative, ';').some((term) => describeLeaf(term).loops);
+}
+
 function substitutionMatches(query, bindings, actualEnv) {
   const queryVariables = namedVariables(query);
   const queryNames = new Set(queryVariables.map((variable) => variable.name));

package/src/solver.js

@@ -29,6 +29,10 @@ export class Solver {
     this.mutableProgram = program.mutable === true;
     this.programRevision = this.program.revision ?? 0;
     this.maxDepth = options.maxDepth ?? 100000;
+    this.depthLimitExceeded = false;
+    this.maxInferences = options.maxInferences ?? Infinity;
+    this.inferences = 0;
+    this.inferenceLimitExceeded = false;
     this.solutionLimit = options.solutionLimit ?? 10000000;
     this.solutionsSeen = 0;
     this.prologFlags = options.prologFlags ?? defaultPrologFlags(this.registry?.eyePrologLibrary ? 'fail' : 'error');
@@ -83,6 +87,7 @@ export class Solver {
     const solver = new Solver(this.program, {
       registry: this.registry,
       maxDepth: this.maxDepth,
+      maxInferences: this.maxInferences,
       solutionLimit,
       prologFlags: this.prologFlags,
       charConversions: this.charConversions,
@@ -110,6 +115,8 @@ export class Solver {
 
   absorbStatsFrom(child) {
     if (!child || child === this || !child.stats) return;
+    this.depthLimitExceeded ||= child.depthLimitExceeded;
+    this.inferenceLimitExceeded ||= child.inferenceLimitExceeded;
     for (const [key, value] of Object.entries(child.stats)) {
       if (key === 'max_depth' || key === 'max_goal_count') {
         this.stats[key] = Math.max(this.stats[key] ?? 0, value ?? 0);
@@ -140,6 +147,11 @@ export class Solver {
       registeredStack = stack;
       this.solveStacks.push(stack);
       while (stack.length) {
+      this.inferences++;
+      if (this.inferences > this.maxInferences) {
+        this.inferenceLimitExceeded = true;
+        break;
+      }
       const frame = stack.pop();
       this.syncProgramRevision();
       if (frame.kind === 'resumeBuiltin') {
@@ -185,11 +197,31 @@ export class Solver {
       let active = frame.active;
 
       while (true) {
+        this.inferences++;
+        if (this.inferences > this.maxInferences) {
+          this.inferenceLimitExceeded = true;
+          stack.length = 0;
+          break;
+        }
         this.syncProgramRevision();
         this.stats.solve_goals_calls++;
         this.stats.max_depth = Math.max(this.stats.max_depth, depth);
         this.stats.max_goal_count = Math.max(this.stats.max_goal_count, goals.length);
-        if (depth > this.maxDepth || this.solutionsSeen >= this.solutionLimit) break;
+        if (depth > this.maxDepth) {
+          this.depthLimitExceeded = true;
+          break;
+        }
+        if (this.solutionsSeen >= this.solutionLimit) break;
+
+        const readyDelays = env.takeReadyDelays();
+        if (readyDelays.length > 0) {
+          const awakened = readyDelays.map(({ goal, module }) => {
+            const delayed = copyResolved(goal, env);
+            qualifyTerm(delayed, module);
+            return delayed;
+          });
+          goals = [...awakened, ...goals];
+        }
 
         if (goals.length === 0) {
           this.solutionsSeen++;
@@ -348,7 +380,11 @@ export class Solver {
 
   *solveUserGoal(goal, rest, env, depth) {
     this.stats.solve_one_goal_calls++;
-    if (depth > this.maxDepth || this.solutionsSeen >= this.solutionLimit) return;
+    if (depth > this.maxDepth) {
+      this.depthLimitExceeded = true;
+      return;
+    }
+    if (this.solutionsSeen >= this.solutionLimit) return;
     if (goal.type !== COMPOUND && goal.type !== 'atom') return;
     const group = this.program.findGroup(goal.name, goal.arity, goal.module ?? 'user');
     if (!group) return;

package/src/standard-library.js

@@ -35,7 +35,7 @@ function libraryUrl(filename) {
   return url;
 }
 
-export const eyePrologNativeLibraryIndicators = Object.freeze(['call_nth/2']);
+export const eyePrologNativeLibraryIndicators = Object.freeze(['call_nth/2', 'freeze/2']);
 export const eyePrologPortableLibraryIndicators = Object.freeze([
   'uuid/3', 'difference/3', 'maplist/2', 'maplist/3', 'maplist/4', 'maplist/5',
   'maplist/6', 'maplist/7', 'maplist/8', 'lt/2', 'gt/2', 'le/2', 'ge/2',

package/src/term.js

@@ -45,6 +45,7 @@ export class Env {
       cacheValue: undefined,
       cache: null,
     };
+    this._delays = null;
   }
   clone() {
     // Most speculative environments are either rejected without a binding or
@@ -54,6 +55,7 @@ export class Env {
     // occasionally flattened.
     const clone = Object.create(Env.prototype);
     clone._state = this._state;
+    clone._delays = this._delays;
     return clone;
   }
   has(name) {
@@ -125,6 +127,24 @@ export class Env {
       cache: null,
     };
   }
+  delay(name, goal, module = 'user') {
+    const delays = new Map(this._delays ?? []);
+    delays.set(name, [...(delays.get(name) ?? []), { goal, module }]);
+    this._delays = delays;
+  }
+  takeReadyDelays() {
+    if (this._delays == null || this._delays.size === 0) return [];
+    const ready = [];
+    let remaining = this._delays;
+    for (const [name, delays] of this._delays) {
+      if (deref(variable(name), this).type === VAR) continue;
+      if (remaining === this._delays) remaining = new Map(this._delays);
+      remaining.delete(name);
+      ready.push(...delays);
+    }
+    if (ready.length > 0) this._delays = remaining;
+    return ready;
+  }
 }
 
 export function deref(term, env) {

package/test/fixtures/length_quad.pl

@@ -0,0 +1,94 @@
+% ids refer to http://www.complang.tuwien.ac.at/ulrich/iso-prolog/length#1
+
+a1 ?- atom_length(A,N).
+      instantiation_error.
+a2 ?- atom_length(a,a).
+      type_error(integer,a).
+a3 ?- atom_length(a,1.1).
+      type_error(integer,1.1).
+a4 ?- atom_length(a,-1).
+      domain_error(not_less_than_zero,-1).
+a5 ?- atom_length(1,N).
+       type_error(atom,1).
+1  ?- length(L,N).
+      L = [], N = 0
+   ;  L = [_A], N = 1
+   ;  L = [_A,_B], N = 2
+   ;  ... .
+2  ?- length(L,0).
+      L = [].
+3  ?- length([_|L],0).
+      false.
+4  ?- length(2,0).
+      false.
+5  ?- length([_|2],0).
+      false.
+6  ?- length([_|2],N).
+      false.
+7  ?- length([_|2],2).
+      false.
+8  ?- length(L,-1).
+      domain_error(not_less_than_zero,-1).
+9  ?- length([],-1).
+      domain_error(not_less_than_zero,-1).
+10 ?- length(a,-1).
+      domain_error(not_less_than_zero,-1).
+11 ?- length([],-0.1).
+      type_error(integer,-0.1).
+12 ?- length(L,-0.1).
+      type_error(integer,-0.1).
+13 ?- length([a],1.0).
+      type_error(integer,1.0).
+14 ?- length(L,1.0).
+      type_error(integer,1.0).
+15 ?- length(L,1.1).
+      type_error(integer,1.1).
+16 ?- length(L,1.0e99).
+      type_error(integer,1.0e99).
+17 ?- N is 2^52, length([], N).
+      false.
+18 ?- length([],0+0).
+      type_error(integer,0+0).
+19 ?- length([],-_).
+      type_error(integer,-_).
+20 ?- length([a],-_).
+      type_error(integer,-_).
+21 ?- length([a,b|X],X).
+      resource_error(finite_memory)
+   |  resource_error(...)
+   |  loops.
+22 ?- length(L,L).
+      resource_error(finite_memory)
+   |  resource_error(...)
+   |  loops.
+23 ?- L = [_|_], length(L,L).
+      type_error(integer,[_|_]).
+24 ?- L = [_], length(L,L).
+      type_error(integer,[_]).
+25 ?- L = [1], length(L,L).
+      type_error(integer,[1]).
+26 ?- L = [a|L], length(L,N).
+      sto, false % current_prolog_flag(occurs_check, true)
+   |  sto, resource_error(finite_memory)
+   |  sto, resource_error(...)
+   |  sto, loops
+   |  sto, L = [a,a], N = 2
+   ;  L = [a,a,_A], N = 3
+   ;  ... . % dag representation, literal substitution, Tau
+27 ?- L = [a|L], length(L,0).
+      sto, false.
+28 ?- L = [a|L], length(L,7).
+      sto, false
+   |  sto, L = [a,a,_A,_B,_C,_D,_E]. % tau
+29 ?- freeze(L,L=[]), length(L,L).
+      false.
+30 ?- freeze(L,L=[_|L]), length(L,N).
+      sto, loops
+   |  sto, resource_error(...).
+31 ?- freeze(L,L=[_|L]), N is 2^64, length(L,N).
+      sto, false.
+32 ?- length([a,b|L], N).
+      L = [], N = 2
+   ;  L = [_A], N = 3
+   ;  L = [_A,_B], N = 4
+   ;  ... .

package/test/run-regression.mjs

@@ -366,6 +366,28 @@ c4 ?- call((!;1)).
         assertEqual(result.stdout, 'quads: 13 run, 13 passed, 0 failed.\n', 'quad report');
       },
     },
+    {
+      name: 'CLI passes the complete authoritative length quad corpus',
+      run: () => {
+        const filename = path.join(testRoot, 'fixtures', 'length_quad.pl');
+        const source = fs.readFileSync(filename, 'utf8');
+        assertEqual(Program.parse(source).quads.length, 37, 'vendored quad total');
+        const result = runCli(['-q', filename]);
+        assertEqual(result.status, 0, 'quad exit status');
+        assertEqual(result.stdout, 'quads: 37 run, 37 passed, 0 failed.\n', 'quad report');
+        assertEqual(result.stderr, '', 'quad stderr');
+      },
+    },
+    {
+      name: 'Prologue freeze wakes delayed goals with their bindings',
+      run: () => {
+        const result = runEyeProlog(
+          ':- use_module(library(prologue)).\nwake(X, Y) :- freeze(X, Y = awake), X = ready.\n',
+          { goal: 'wake(X, Y)' },
+        );
+        assertEqual(result.stdout, 'wake(ready, awake).\n', 'freeze answer');
+      },
+    },
     {
       name: 'runQuads covers the remaining finite Prologue examples and arities',
       run: () => {
@@ -392,11 +414,11 @@ c4 ?- call((!;1)).
       },
     },
     {
-      name: 'runQuads reports annotations that cannot be checked safely',
+      name: 'runQuads recognizes bounded nontermination descriptions',
       run: () => {
         const result = publicApi.runQuads(`?- repeat, fail.\n   loops.\n`);
-        assertEqual(result.results[0].kind, 'unsupported', 'quad result');
-        assertIncludes(result.stdout, 'quads: UNSUPPORTED <input>:1', 'unsupported report');
+        assertEqual(result.passed, 1, 'quad passed');
+        assertEqual(result.stdout, 'quads: 1 run, 1 passed, 0 failed.\n', 'quad report');
       },
     },
     {
@@ -1392,17 +1414,19 @@ 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, 130, 'EyeProlog registry contains ISO definitions and one private library adapter');
+        assertEqual(library.defs.size, 131, 'EyeProlog registry contains ISO definitions and two 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(registeredNativeEyePrologLibraryNames().length, 1, 'public native EyeProlog builtin count');
+        assertEqual(registeredNativeEyePrologLibraryNames().length, 2, 'public native EyeProlog builtin count');
         assertEqual(eyePrologPortableLibraryIndicators.length, 56, 'portable Prolog library count');
-        assertEqual(eyePrologNativeLibraryIndicators.length, 1, 'native host library count');
-        assertEqual(eyePrologNativeLibraryIndicators.join(','), 'call_nth/2', 'control predicate requiring host support');
-        assertEqual(eyePrologLibraryIndicators.length, 57, 'complete EyeProlog library surface');
+        assertEqual(eyePrologNativeLibraryIndicators.length, 2, 'native host library count');
+        assertEqual(eyePrologNativeLibraryIndicators.join(','), 'call_nth/2,freeze/2', 'control predicates requiring host support');
+        assertEqual(eyePrologLibraryIndicators.length, 58, 'complete EyeProlog library surface');
         assertEqual(registry.get('eyeprolog__call_nth', 2), null, 'private call_nth adapter is absent from ISO registry');
         assertEqual(Boolean(library.get('eyeprolog__call_nth', 2)), true, 'private call_nth adapter is registered for EyeProlog');
         assertEqual(library.get('eyeprolog__call_nth', 2)?.eyePrologLibrary, true, 'private adapter is marked as library support');
+        assertEqual(registry.get('eyeprolog__freeze', 2), null, 'private freeze adapter is absent from ISO registry');
+        assertEqual(Boolean(library.get('eyeprolog__freeze', 2)), true, 'private freeze adapter is registered for EyeProlog');
         assertEqual(library.get('between', 3), null, 'between/3 remains portable Prolog');
         assertEqual(library.get('smallest_divisor_from', 3), null, 'smallest_divisor_from/3 remains portable Prolog');
         assertEqual(library.get('random', 3), null, 'random/3 remains portable Prolog');

package/the-art-of-eyeprolog.md

@@ -5761,13 +5761,13 @@ so side effects occur in Prolog execution order.
 
 ### The EyeProlog library
 
-EyeProlog exposes **57 library predicate indicators** in addition to the 129
+EyeProlog exposes **58 library predicate indicators** in addition to the 129
 indicators in its isolated ISO profile. **56 are implemented entirely as
 ordinary Prolog clauses** across `src/lib/eyeprolog.pl`, `src/lib/lists.pl`, and
-`src/lib/prologue.pl`. The Prologue `call_nth/2` clause delegates its solution
-numbering to one private host adapter. The resulting normal EyeProlog language
-surface is therefore **186 public predicate indicators**. Internally, the
-runtime registry contains the 129 ISO definitions plus that private adapter;
+`src/lib/prologue.pl`. The Prologue `call_nth/2` and `freeze/2` clauses delegate
+their control behavior to private host adapters. The resulting normal EyeProlog
+language surface is therefore **187 public predicate indicators**. Internally, the
+runtime registry contains the 129 ISO definitions plus those two private adapters;
 the remaining EyeProlog relations are module source clauses.
 
 The three Prolog files declare `eyeprolog`, `lists`, and `prologue` with
@@ -5776,8 +5776,8 @@ The three Prolog files declare `eyeprolog`, `lists`, and `prologue` with
 `use_module(library(prologue))`; `use_module/2` can select a smaller import
 list. The last module implements p.p.1 through p.p.11 of the
 [working-draft Prologue](https://www.complang.tuwien.ac.at/ulrich/iso-prolog/prologue),
-with the published `call_nth/2` quads and finite examples retained as offline
-regressions. `src/standard-library.js` registers the module sources and private
+with the published Prologue, `call_nth/2`, and `length/2` quads retained as
+offline regressions. `src/standard-library.js` registers the module sources and private
 control adapter for Node and browser resolution, and never adds clauses
 implicitly.
 The isolated ISO-only registry remains
@@ -5785,13 +5785,18 @@ available through `createDefaultRegistry()` and `getDefaultRegistry()` for
 conformance work and advanced embedders. Module-local predicate identity keeps
 private helpers and same-named predicates in different modules separate.
 
+`freeze(?Term,:Goal)` runs `Goal` immediately when `Term` is already nonvariable;
+otherwise it delays the goal until `Term` becomes nonvariable. Suspensions are
+kept in the logical environment, so bindings and backtracking remain isolated
+between solution branches.
+
 <!-- eyeprolog-library-catalog:start -->
 
 | Module | Exported predicate indicators |
 | --- | --- |
 | `library(lists)` | `maplist/3`, `append/3`, `member/2`, `select/3`, `last/2`, `nth0/3`, `nth1/3`, `reverse/2`, `length/2`, `sum_list/2`, `min_list/2`, `max_list/2`, `list_to_set/2`, `countall/2` |
 | `library(eyeprolog)` | `uuid/3`, `difference/3`, `lt/2`, `le/2`, `gt/2`, `ge/2`, `between/3`, `smallest_divisor_from/3`, `random/3`, `matches/3`, `split/3`, `replace/4`, `lowercase/2`, `uppercase/2`, `trim/2`, `number_string/2`, `atom_string/2`, `term_string/2`, `string_concat/3`, `contains/2`, `matches/2`, `join/3`, `substring/4`, `set_nth0/4`, `take/3`, `drop/3`, `slice/4`, `sumall/3`, `aggregate_min/5`, `aggregate_max/5` |
-| `library(prologue)` | `member/2`, `append/3`, `length/2`, `between/3`, `select/3`, `succ/2`, `maplist/2`, `maplist/3`, `maplist/4`, `maplist/5`, `maplist/6`, `maplist/7`, `maplist/8`, `nth0/3`, `nth0/4`, `nth1/3`, `nth1/4`, `call_nth/2`, `foldl/4`, `foldl/5`, `foldl/6`, `countall/2` |
+| `library(prologue)` | `member/2`, `append/3`, `length/2`, `between/3`, `select/3`, `succ/2`, `maplist/2`, `maplist/3`, `maplist/4`, `maplist/5`, `maplist/6`, `maplist/7`, `maplist/8`, `nth0/3`, `nth0/4`, `nth1/3`, `nth1/4`, `call_nth/2`, `freeze/2`, `foldl/4`, `foldl/5`, `foldl/6`, `countall/2` |
 
 <!-- eyeprolog-library-catalog:end -->
 
@@ -6169,7 +6174,9 @@ Run all quads in a file with `eyeprolog --quads file.pl` or `eyeprolog -q
 file.pl`. A label such as `colors` is optional. Loading the file normally only
 records its quads; it does not execute them or add their queries and answers as
 program clauses. A quad run prints a summary and exits with status `1` when any
-description fails.
+description fails. Quad mode imports `library(prologue)` as a compatibility
+prelude because the ISO Prolog working-example files use those predicates as
+system predicates without an explicit module directive.
 
 Unless the source explicitly selects another `unknown` flag, quad execution
 uses `unknown=error`, so an undefined predicate is reported rather than being
@@ -6181,10 +6188,10 @@ and the `unexpected` annotation for an answer that must not occur (`inattendue`
 is its synonym). `...` and `ad_infinitum` accept further answers. Multiple
 indented descriptions after one query must all hold. `inputs/1` supplies and
 checks consumed characters; `outputs/1` checks emitted characters. `sto` marks
-an answer description that this finite-tree implementation skips. The
-nontermination and advanced stream annotations `loops`, `peeks/1`, and `waits`,
-and the unordered `other_answer_sequence` annotation, are not executed by the
-current runner.
+an answer description that this finite-tree implementation skips. `loops` is
+checked with a deterministic solver-depth budget. The advanced stream
+annotations `peeks/1` and `waits`, and the unordered `other_answer_sequence`
+annotation, are not executed by the current runner.
 
 The JavaScript API exposes the same operation without process I/O: