eyeprolog 1.3.11 → 1.3.13

package/README.md

@@ -107,6 +107,18 @@ keeps both long-running filters such as `\+ phrase((..., Pattern), Sequence)`
 and repeated same-input probes bounded without turning memory safety into a
 per-call cache-eviction cost.
 
+Finite-tree unification also accepts an internal proven-nonoccurrence hint: when
+the solver can prove that a variable cannot occur in the value it is about to
+receive, that binding skips an otherwise redundant occurs traversal. The main
+source-level case is conservative first use in a freshly renamed clause, inspired
+by the local-variable optimization used by WAM-family systems; native construction
+paths such as relational `length/2` reuse the same unifier mechanism. Repeated
+variables, variables seen earlier in the clause, and ordinary public unification
+remain fully occurs-checked. This is a proof local to one binding, not a WAM-style
+local/global variable stack. `phrase/2` likewise supplies its fixed `[]`
+remainder directly to the grammar; `phrase/3` retains its delayed final output
+unification for steadfastness.
+
 Recursion through negation is explicit. EyeProlog provides `tnot/1` for
 well-founded negation over finite, range-restricted, function-free Datalog
 components. Ordinary `\+/1` remains negation-as-failure and is not silently

package/package.json

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

package/src/iso.js

@@ -181,7 +181,8 @@ export const eyePrologLibraryBuiltins = {
 
 function* unification({ goal, env }) {
   const next = env.clone();
-  if (unify(goal.args[0], goal.args[1], next)) yield next;
+  const knownNonoccurringVariables = goal._knownNonoccurringVariables ?? null;
+  if (unify(goal.args[0], goal.args[1], next, { knownNonoccurringVariables })) yield next;
 }
 function* unificationWithOccursCheck({ goal, env }) {
   const next = env.clone();
@@ -2033,14 +2034,17 @@ function* phraseBuiltin({ solver, goal, env }) {
     throw new PrologError('type_error(list)', deref(requestedOutput, env));
   }
 
-  // Delay the final output unification to keep phrase/3 steadfast in its
-  // third argument, as required by the Part 3 execution model.
-  const finalOutput = variable(`\u0000phrase:${++isoFresh}`);
+  // phrase/2 fixes the remainder to [] from the outset. phrase/3 keeps a
+  // private output variable and delays the final unification so its third
+  // argument remains steadfast as required by the Part 3 execution model.
+  const finalOutput = goal.arity === 2
+    ? requestedOutput
+    : variable(`\u0000phrase:${++isoFresh}`);
   const expanded = expandDcgBody(grammarBody, input, finalOutput, {
     env,
     module: goal.module ?? grammarBody.module ?? 'user',
   });
-  const finish = compound('=', [finalOutput, requestedOutput]);
+  const finish = goal.arity === 2 ? null : compound('=', [finalOutput, requestedOutput]);
   // Recursive DCGs are automatically tabled in normal mode. Keep tables in a
   // phrase-local scope keyed by the whole invocation. Repeatedly testing the
   // same grammar/input (issue #48) reuses its completed table, while switching
@@ -2064,7 +2068,7 @@ function* phraseBuiltin({ solver, goal, env }) {
     skipListTailTabling: !repeatedInvocation,
   });
   try {
-    yield* child.solve([expanded, finish], env, 0);
+    yield* child.solve(finish == null ? [expanded] : [expanded, finish], env, 0);
   } finally {
     solver.absorbStatsFrom(child);
     solver.trimInnerTableScope('phrase');

package/src/solver.js

@@ -799,9 +799,12 @@ export class Solver {
         const freshVariables = new Map();
         const freshHead = freshTerm(clause.head, id, freshVariables);
         const freshBody = clause.body.map((term) => freshTerm(term, id, freshVariables));
+        const localFreshPlan = clauseLocalFreshPlan(clause);
+        const headLocalFresh = freshVariableSet(localFreshPlan.head, freshVariables);
+        attachBodyLocalFreshVariables(freshBody, localFreshPlan.body, freshVariables);
         const next = env.clone();
         this.stats.unify_calls++;
-        if (!unify(goal, freshHead, next)) continue;
+        if (!unify(goal, freshHead, next, { knownNonoccurringVariables: headLocalFresh })) continue;
         if (freshBody.length === 0) {
           yield* this.solve(rest, next, depth + 1);
         } else if (!groupNeedsActiveFrame(group)) {
@@ -1013,9 +1016,12 @@ function pushUserGoalUncachedFrames(stack, solver, group, goal, rest, env, depth
       const freshVariables = new Map();
       const freshHead = freshTerm(clause.head, id, freshVariables);
       const freshBody = clause.body.map((term) => freshTerm(term, id, freshVariables));
+      const localFreshPlan = clauseLocalFreshPlan(clause);
+      const headLocalFresh = freshVariableSet(localFreshPlan.head, freshVariables);
+      attachBodyLocalFreshVariables(freshBody, localFreshPlan.body, freshVariables);
       const next = env.clone();
       solver.stats.unify_calls++;
-      if (!unify(goal, freshHead, next)) continue;
+      if (!unify(goal, freshHead, next, { knownNonoccurringVariables: headLocalFresh })) continue;
       if (freshBody.length === 0) {
         frames.push({
           kind: 'goals',
@@ -1038,6 +1044,53 @@ function pushUserGoalUncachedFrames(stack, solver, group, goal, rest, env, depth
   for (let i = frames.length - 1; i >= 0; i--) stack.push(frames[i]);
 }
 
+function clauseLocalFreshPlan(clause) {
+  if (clause._localFreshPlan != null) return clause._localFreshPlan;
+  const seen = new Set();
+  const planForTerm = (term) => {
+    const counts = new Map();
+    const stack = [term];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (current?.type === VAR) {
+        counts.set(current.name, (counts.get(current.name) ?? 0) + 1);
+        continue;
+      }
+      if (current?.type !== COMPOUND) continue;
+      for (let index = 0; index < current.arity; index++) stack.push(current.args[index]);
+    }
+    const local = [];
+    for (const [name, count] of counts) {
+      if (!seen.has(name) && count === 1) local.push(name);
+      seen.add(name);
+    }
+    return local;
+  };
+  const head = planForTerm(clause.head);
+  const body = clause.body.map(planForTerm);
+  return clause._localFreshPlan = { head, body };
+}
+
+function freshVariableSet(names, freshVariables) {
+  if (names.length === 0) return null;
+  const fresh = new Set();
+  for (const name of names) {
+    const term = freshVariables.get(name);
+    if (term != null) fresh.add(term.name);
+  }
+  return fresh.size === 0 ? null : fresh;
+}
+
+function attachBodyLocalFreshVariables(freshBody, plan, freshVariables) {
+  for (let index = 0; index < freshBody.length; index++) {
+    const knownNonoccurringVariables = freshVariableSet(plan[index] ?? [], freshVariables);
+    if (knownNonoccurringVariables != null && freshBody[index]?.type === COMPOUND &&
+        freshBody[index].name === '=' && freshBody[index].arity === 2) {
+      freshBody[index]._knownNonoccurringVariables = knownNonoccurringVariables;
+    }
+  }
+}
+
 function groupNeedsActiveFrame(group) {
   // A direct recursive call that consumes the tail of a matched list cannot
   // revisit an earlier finite-tree call. It needs neither a cycle guard nor an
@@ -1204,12 +1257,11 @@ function* fixedLengthSolutions(solver, list, length, env) {
   const suffix = compactVariableList(remaining, `__length${id}_`);
   const next = env.clone();
   solver.stats.unify_calls++;
-  // cursor is dereferenced and the compact skeleton contains only freshly
-  // generated variables, so this binding cannot create a cycle. Binding it
-  // directly avoids traversing and expanding the new skeleton for an occurs
-  // check whose result is known by construction.
-  next.bind(cursor.name, suffix);
-  yield next;
+  // The compact skeleton contains only freshly generated variables, so the
+  // dereferenced tail variable is known not to occur in it. Reuse the same
+  // proven-nonoccurrence path as source-level first-use unification.
+  const knownNonoccurringVariables = new Set([cursor.name]);
+  if (unify(cursor, suffix, next, { knownNonoccurringVariables })) yield next;
 }
 
 function* generatedLengthSolutions(solver, list, length, env) {
@@ -1243,15 +1295,13 @@ function* generatedLengthSolutions(solver, list, length, env) {
 
   const id = nextFreshId();
   let suffix = emptyList();
+  // Every generated suffix is built from fresh variables and therefore cannot
+  // contain the caller's dereferenced tail variable. Share the general
+  // proven-nonoccurrence unification path instead of bypassing unify() here.
+  const knownNonoccurringVariables = new Set([cursor.name]);
   for (let extra = 0n; ; extra++) {
     const next = env.clone();
-    // cursor is a dereferenced plain variable and suffix is made only from
-    // freshly generated variables, so this binding cannot create a cycle.
-    // Binding directly avoids an O(extra) occurs-check over the complete
-    // growing suffix for every answer; without this, unbounded length/2
-    // generation becomes quadratic and can spend hours before reaching the
-    // normal memory resource guard (issue #49).
-    next.bind(cursor.name, suffix);
+    if (!unify(cursor, suffix, next, { knownNonoccurringVariables })) return;
     const answer = bindGeneratedLength(solver, length, count + extra, next);
     if (answer != null) yield answer;
     suffix = cons(variable(`__length${id}_${extra}`), suffix);
@@ -1900,10 +1950,14 @@ function compactIndexBucket(index, type, name) {
 
 function tryPushCompactBinaryChainFrames(stack, solver, group, goal, rest, env, depth, active) {
   if (active.length !== 0 || goal.type !== COMPOUND || goal.arity !== 2) return false;
-  const resolved = copyResolved(goal, env);
-  const first = resolved.args[0];
-  let secondType = resolved.args[1]?.type;
-  let secondName = resolved.args[1]?.name;
+  // This fast path only accepts scalar arguments. Dereference those arguments
+  // directly instead of deep-copying the whole goal before discovering that a
+  // list/compound argument is ineligible. Besides avoiding wasted work, this
+  // keeps deep DCG state lists away from recursive copyResolved().
+  const first = derefForLocal(goal.args[0], env);
+  const second = derefForLocal(goal.args[1], env);
+  let secondType = second?.type;
+  let secondName = second?.name;
   if (!isScalarTerm(first) || !['atom', 'string', 'number'].includes(secondType)) return false;
 
   const index = group.argIndexes[1];
@@ -2014,10 +2068,17 @@ function tryPushGroundChainFrames(stack, solver, group, goal, rest, env, depth,
   // has exactly one matching clause and a single ground body goal; otherwise the
   // normal clause path below remains authoritative.
   if (!termIsGround(goal, env)) return false;
+  // The chain matcher below only propagates variables bound to flat scalar
+  // head arguments (or literal scalars). Keep this optimization on that flat
+  // domain instead of recursively copying an arbitrary ground compound just
+  // to discover later that a rule shape is unsupported. Deep list arguments
+  // such as DCG state therefore fall straight through to normal resolution.
+  const resolvedArgs = goal.args.map((arg) => derefForLocal(arg, env));
+  if (!resolvedArgs.every(isScalarTerm)) return false;
 
   const baseEnv = env;
   let currentGroup = group;
-  let currentGoal = copyResolved(goal, env);
+  let currentGoal = compound(goal.name, resolvedArgs);
   let currentDepth = depth;
   const currentEnv = new Env();
   const seen = new Set();
@@ -2328,6 +2389,10 @@ function selectReadyDeterministicBuiltin(goals, env, registry) {
   for (let i = 0; i < goals.length; i++) {
     const goal = goals[i];
     if (goal?.kind === 'releaseActive' || goal?.kind === 'memoStore') return 0;
+    // A first-use proof is derived from source goal order. Do not move a later
+    // deterministic builtin across that equality: doing so could touch one of
+    // its proven-fresh variables before the checked binding executes.
+    if (goal?._knownNonoccurringVariables != null) return 0;
     if (goal.type !== COMPOUND && goal.type !== 'atom') continue;
     const def = registry.get(goal.name, goal.arity);
     if (!def?.deterministic || typeof def.ready !== 'function') continue;

package/src/term.js

@@ -271,6 +271,11 @@ export function unify(left, right, env, options = {}) {
   // unification: a variable cannot be bound to a term containing itself.
   // Bindings are written into the supplied Env.
   const occursCheckHandler = options.occursCheck === 'fail' ? null : env?._occursCheckHandler;
+  // Callers may provide a proof that selected variables cannot occur in the
+  // term they are about to receive.  Source-level first-use analysis and a few
+  // construction fast paths share this internal proof; ordinary unification
+  // remains fully occurs-checked.
+  const knownNonoccurringVariables = options.knownNonoccurringVariables ?? null;
   const stack = [[left, right]];
   while (stack.length) {
     let [a, b] = stack.pop();
@@ -286,7 +291,7 @@ export function unify(left, right, env, options = {}) {
       continue;
     }
     if (a.type === VAR) {
-      if (occurs(a.name, b, env)) {
+      if (!knownNonoccurringVariables?.has(a.name) && occurs(a.name, b, env)) {
         occursCheckHandler?.(a, b, env);
         return false;
       }
@@ -295,7 +300,7 @@ export function unify(left, right, env, options = {}) {
       continue;
     }
     if (b.type === VAR) {
-      if (occurs(b.name, a, env)) {
+      if (!knownNonoccurringVariables?.has(b.name) && occurs(b.name, a, env)) {
         occursCheckHandler?.(b, a, env);
         return false;
       }

package/test/run-regression.mjs

@@ -1317,6 +1317,68 @@ c4 ?- call((!;1)).
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'proven-nonoccurrence first-use shortcut preserves finite-tree occurs checking',
+      run: () => {
+        const program = Program.parse(`
+          first_use_cycle :- X = f(Y), Y = g(X).
+          repeated_cycle :- X = f(X).
+          first_use_ok(T) :- X = f(Y), Y = a, T = X.
+        `);
+        const solver = new Solver(program);
+        const solveCount = (text) => {
+          const goal = parseGoalText(text, {
+            doubleQuotes: 'chars',
+            operatorDefinitions: [...program.operators.values()],
+          });
+          let count = 0;
+          for (const _ of solver.solve([goal], new Env(), 0)) count++;
+          return count;
+        };
+        assertEqual(solveCount('first_use_cycle'), 0, 'cycle across later first-use binding');
+        assertEqual(solveCount('repeated_cycle'), 0, 'same-goal repeated variable still checks occurs');
+        assertEqual(solveCount('first_use_ok(f(a))'), 1, 'acyclic first-use bindings still succeed');
+      },
+    },
+    {
+      name: 'phrase/2 fixes the final remainder before running the grammar',
+      run: () => {
+        const program = Program.parse('probe(_, Out) :- var(Out).\n');
+        const solver = new Solver(program);
+        const goal = parseGoalText('phrase(probe, [])', {
+          doubleQuotes: 'chars',
+          operatorDefinitions: [...program.operators.values()],
+        });
+        let count = 0;
+        for (const _ of solver.solve([goal], new Env(), 0)) count++;
+        assertEqual(count, 0, 'phrase/2 exposes [] rather than a temporary output variable');
+      },
+    },
+    {
+      name: 'deep tail-consuming DCG avoids quadratic occurs scans and recursive ground-goal copying',
+      run: () => {
+        const engineUrl = new URL('../src/index.js', import.meta.url).href;
+        const script = `
+          import { Program, Solver, Env, atom, compound, listFromItems } from ${JSON.stringify(engineUrl)};
+          const program = Program.parse(${JSON.stringify('s --> [].\ns --> [x], s.\n')});
+          const input = listFromItems(Array.from({ length: 2500 }, () => atom('x')));
+          const solver = new Solver(program, { solutionLimit: 1, maxMemoryBytes: Infinity });
+          const goal = compound('phrase', [atom('s'), input]);
+          let count = 0;
+          for (const _ of solver.solve([goal], new Env(), 0)) { count++; break; }
+          if (count !== 1) throw new Error('deep DCG did not succeed');
+          process.stdout.write('ok');
+        `;
+        const result = spawnSync(process.execPath, [
+          '--input-type=module',
+          '--eval',
+          script,
+        ], { cwd: packageRoot, encoding: 'utf8', timeout: 10000 });
+        if (result.error) throw result.error;
+        assertEqual(result.status, 0, `deep DCG child status; stderr=${result.stderr}`);
+        assertEqual(result.stdout, 'ok', 'deep DCG result');
+      },
+    },
     {
       name: 'REPL enumerates and stops answers like the Scryer top level',
       run: () => {

package/the-art-of-eyeprolog.md

@@ -1900,15 +1900,37 @@ unification, another list predicate, or answer readback inspects it. This is a
 storage optimization, not a distinct Prolog term or list semantics. Embedders
 that inspect the JavaScript term model can recognize this representation with
 `CompactListTerm`, `isCompactList`, and `compactListLength`, or construct one
-with `compactVariableList`. For open-ended `length(List, N)` generation, the
-bundled path binds each fresh generated spine directly instead of re-running an
-occurs-check over the whole growing list. It also reserves recovery headroom
-proportional to the retained spine, so a finite heap limit is raised inside the
-`length/2` search as a catchable `resource_error(memory)` rather than allowing
-an outer solver frame to encounter the limit first. The ordinary clauses remain
-the authoritative module definition and are used unchanged by the ISO-only
-registry and whenever delays or finite-domain constraints require their normal
-wake-up points.
+with `compactVariableList`. For open-ended `length(List, N)` generation, each generated spine is known not
+to contain the caller's dereferenced tail variable. The bundled path passes that
+proof through the normal unifier, sharing the same proven-nonoccurrence mechanism
+as first-use clause variables instead of maintaining a predicate-specific raw
+binding shortcut. It still reserves recovery headroom proportional to the
+retained spine, so a finite heap limit is raised inside the `length/2` search as
+a catchable `resource_error(memory)` rather than allowing an outer solver frame
+to encounter the limit first.
+
+The same proven-nonoccurrence mechanism has a conservative source-level form for freshly renamed
+clauses. A singleton variable in the clause head, or a variable that has not
+appeared in the head or any earlier body goal and occurs exactly once in a
+direct `=/2` goal, cannot already be a subterm of the value it is about to
+receive. EyeProlog marks only that binding as locally fresh and skips its occurs
+traversal. A repeated variable such as the `X` in `X = f(X)`, a variable already
+seen earlier in the clause, and `unify_with_occurs_check/2` all keep the normal
+finite-tree check. The solver also treats such a first-use equality as a
+source-order barrier for its deterministic-goal scheduling, so the freshness
+proof cannot be invalidated by moving a later goal ahead of it. This recovers
+much of the classic WAM-family "local variable" optimization for DCG tail
+variables without introducing a WAM local/global stack distinction into the
+JavaScript term model.
+
+For grammar execution, `phrase/2` passes its fixed final remainder `[]` directly
+into the expanded grammar. Besides matching the two-argument contract, this
+avoids repeatedly trying an empty production against a temporary output
+variable. `phrase/3` still uses a private final-output variable and delays its
+last unification, preserving the existing steadfast treatment of its explicit
+third argument. The ordinary `length/2` clauses remain the authoritative module
+definition and are used unchanged by the ISO-only registry and whenever delays
+or finite-domain constraints require their normal wake-up points.
 
 ### Implementation boundary
 
@@ -6101,47 +6123,74 @@ between solution branches.
 
 #### Interoperability profile and conservative autoloading
 
-The full EyeProlog library is larger than the deliberately conservative
-EyeProlog/Trealla/Scryer source-interoperability profile. The two concepts are
-kept separate: a predicate can be implemented as ordinary portable Prolog and
-still have an API that is not shared by the other systems.
-
-`library(lists)` is the first aligned common module. Its interop surface includes
-`member/2`, `memberchk/2`, `select/3`, `append/2-3`, `last/2`,
-`same_length/2`, `nth0/3-4`, `nth1/3-4`, `reverse/2`, `length/2`,
-`maplist/2-8`, `foldl/4-6`, `sum_list/2`, and `list_to_set/2`. Its `length/2`
-is fully relational: when both arguments are variables, `length(Xs, N)`
-enumerates `Xs = [], N = 0`, then one-element lists with `N = 1`, and so on.
-This generator mode is important for portable stress and enumeration programs.
-EyeProlog-only helpers such as `set_nth0/4`, `take/3`, `drop/3`, and `slice/4`
-remain available for compatibility but are outside this profile.
-
-`library(iso_ext)` is also recognized as a common interop module name.
-EyeProlog exports `call_nth/2` there, matching Scryer's explicit import
-organization while still permitting unqualified autoloaded source. The aligned
-`library(lists)` and `library(iso_ext)` export sets are intentionally disjoint,
-so a source file may import both without an accidental predicate collision.
-`library(prologue)` is retained as an EyeProlog compatibility umbrella and may
-overlap these modules; use selective imports when legacy code combines it with
-the aligned libraries.
-
-`library(lambda)` is an explicitly imported Scryer-aligned module for
-higher-order programming. Its implementation is adapted from Ulrich Neumerkel's
-`library(lambda)` as distributed by Scryer Prolog, retaining the upstream
-copyright and redistribution notice. The public syntax is:
+EyeProlog keeps four related concepts separate:
+
+| Layer | Meaning |
+| --- | --- |
+| **ISO core** | The documented ISO predicate profile built into the processor. No EyeProlog library import is involved. |
+| **EyeProlog library surface** | Every module and exported predicate listed in the catalog above. Programs normally access these with `use_module/1-2`. |
+| **Interoperability profile** | A deliberately smaller set of library names and predicate interfaces that EyeProlog intends to keep source-compatible with Trealla and Scryer where practical. |
+| **Autoload map** | An even smaller convenience table that gives selected unqualified predicates one canonical EyeProlog provider. |
+
+These layers answer different questions. A predicate may be implemented entirely
+as ordinary Prolog and still be outside the cross-processor interoperability
+profile; conversely, an interoperable predicate may be backed by a private host
+adapter. In this section, **portable** refers to source portability between
+Prolog systems, not merely to the language in which a predicate happens to be
+implemented.
+
+The current interoperability profile recognizes these library roles:
+
+| Library | Role in the interoperability profile |
+| --- | --- |
+| `library(lists)` | Common list module. A conservative subset of its exports is in the shared predicate profile. |
+| `library(iso_ext)` | Common extension-module name. `call_nth/2` is currently its autoloaded cross-engine predicate. |
+| `library(lambda)` | Scryer-aligned higher-order notation. It is imported explicitly because loading it also installs the `+\` operator. |
+| `library(prologue)` | EyeProlog compatibility module, not a common interop library name. `between/3` is nevertheless autoloaded from it so portable source need not name this EyeProlog-specific provider. |
+
+Other modules from the catalog, including `library(clpz)`, `library(strings)`,
+`library(random)`, and `library(uuid)`, remain normal EyeProlog libraries. They
+can be imported explicitly, but their module names and full APIs are not thereby
+claimed as part of the current conservative Trealla/Scryer profile.
+
+For `library(lists)`, the current interop predicate set is `member/2`,
+`memberchk/2`, `select/3`, `append/2-3`, `last/2`, `same_length/2`,
+`nth0/3-4`, `nth1/3-4`, `reverse/2`, `length/2`, `maplist/2-8`,
+`foldl/4-6`, `sum_list/2`, and `list_to_set/2`. Other exports from the same
+module, such as `min_list/2`, `max_list/2`, `set_nth0/4`, `take/3`, `drop/3`,
+and `slice/4`, remain available to EyeProlog programs but lie outside this
+conservative cross-engine subset.
+
+`length/2` remains fully relational. With both arguments variable,
+`length(Xs, N)` enumerates `Xs = [], N = 0`, then one-element lists with
+`N = 1`, and so on. Open-ended generation uses the normal memory guard with
+recovery headroom so finite-heap exhaustion remains a catchable
+`resource_error(memory)`.
+
+`library(iso_ext)` is a common interop module name, but only part of its
+EyeProlog API belongs to the shared profile. `call_nth/2` is mapped there to
+match Scryer's explicit import organization while also permitting portable
+unqualified source to autoload it. The interop exports of `library(lists)` and
+`library(iso_ext)` are kept disjoint, so both modules can be imported together
+without an accidental collision. `library(prologue)` remains a compatibility
+umbrella and overlaps them; use selective imports when legacy code combines it
+with the aligned modules.
+
+`library(lambda)` follows Scryer's higher-order notation, adapted from Ulrich
+Neumerkel's permissively licensed implementation. Its public syntax is:
 
 ```text
 \X1^X2^...^XN^Goal
 Free+\X1^X2^...^XN^Goal
 ```
 
-The first form has no explicitly shared free variables. Before each invocation
-EyeProlog copies the closure term, so local variables are fresh on successive
+The first form has no explicitly shared free variables. Before each invocation,
+EyeProlog copies the closure term so local variables are fresh on successive
 `maplist/2-8`, `foldl/4-6`, or direct `call/N` uses. In the second form, the
-variables contained in `Free` remain shared with the surrounding goal. Importing
-the library installs `+\` as a priority-201 `xfx` operator; `\` and `^` use
-their existing ISO operator definitions. Parenthesize lower-priority goal
-operators after `^`, for example `\X^(X > 3)`.
+variables contained in `Free` remain shared with the surrounding goal.
+Importing the library installs `+\` as a priority-201 `xfx` operator; `\` and
+`^` use their existing ISO operator definitions. Parenthesize lower-priority
+goal operators after `^`, for example `\X^(X > 3)`.
 
 A continuation lambda may leave arguments for a later call:
 
@@ -6151,56 +6200,78 @@ f(x, y).
 answer(A, B) :- call(\X^f(X), A, B).
 ```
 
-This is equivalent to supplying both arguments directly. A lambda that is
-called with too few parameters raises `existence_error(lambda_parameter, ...)`,
-matching the diagnostic intent of the Scryer library. EyeProlog uses its ISO
-`copy_term/2` implementation for the fresh-copy step; in EyeProlog this gives
-the natural-copy behavior needed by the library without requiring a separate
-`copy_term_nat/2` predicate.
-
-Normal EyeProlog execution can autoload an otherwise undefined unqualified call
-only when the interop table assigns it one canonical provider. Thus `member/2`
-autoloads from `library(lists)`, `call_nth/2` from `library(iso_ext)`, and
-`between/3` from the internal `library(prologue)` implementation. Autoloading is
-disabled by `--no-autoload`, by the JavaScript option `autoload: false`, and
-always by `--iso-strict`.
-
-`-w` / `--warnings` reports explicit non-profile library dependencies and calls
-to non-profile predicates from common libraries. `--portable` turns those
-portability diagnostics into a failing command, making the profile suitable for
-continuous integration. `npm run test:interop` executes the same Sudoku source
-under EyeProlog, Trealla, and Scryer when those commands are installed; the
-repository's interoperability workflow installs them and runs that check.
-
-`library(clpz)` follows the Trealla and Scryer convention for constraint logic
-programming over integers. Its first implementation step provides finite
+This is equivalent to supplying both arguments directly. A lambda called with
+too few parameters raises `existence_error(lambda_parameter, ...)`. EyeProlog
+uses its ISO `copy_term/2` implementation for the fresh-copy step and does not
+require a separate `copy_term_nat/2` predicate.
+
+Autoloading is a convenience layered on top of the interoperability profile; it
+is not a general search through all EyeProlog libraries. During normal
+execution, an otherwise undefined **unqualified** predicate may be autoloaded
+only when the interop table assigns it one canonical provider. For example:
+
+| Predicate | Canonical autoload provider |
+| --- | --- |
+| `member/2` | `library(lists)` |
+| `call_nth/2` | `library(iso_ext)` |
+| `between/3` | `library(prologue)` |
+
+Predicates outside that table require an explicit import even when EyeProlog
+provides them. Explicit imports therefore remain the clearest way to state
+library dependencies:
+
+```text
+:- use_module(library(lists)).
+:- use_module(library(iso_ext), [call_nth/2]).
+```
+
+Use `--no-autoload`, or the JavaScript option `autoload: false`, when every
+library dependency should be explicit. `--iso-strict` always disables EyeProlog
+library autoloading.
+
+`-w` / `--warnings` reports explicit dependencies on non-profile libraries and
+calls to non-profile predicates from otherwise common modules. `--portable`
+turns those diagnostics into a failing run, making the conservative profile
+suitable for continuous integration. `npm run test:interop` executes the same
+portable Sudoku source under EyeProlog, Trealla, and Scryer when those commands
+are installed; the repository interoperability workflow installs them and runs
+that check.
+
+#### Library notes beyond the interoperability profile
+
+The catalog above is authoritative for the complete EyeProlog library surface.
+The following notes describe useful parts of that surface without extending the
+cross-engine claims made above.
+
+`library(clpz)` follows the familiar Trealla and Scryer convention for
+constraint logic programming over integers. EyeProlog currently provides finite
 interval and union domains, arithmetic and reified constraints, backtrackable
-labeling with `ff`, `up`, and `down`, global distinctness, linear sums and
-scalar products, chains, elements, value counting, extensional tuple tables,
+labeling with `ff`, `up`, and `down`, global distinctness, linear sums and scalar
+products, chains, elements, value counting, extensional tuple tables,
 lexicographic chains, serialized schedules, global cardinality with costs,
 Hamiltonian circuits, three-way comparison, and domain reflection. Constraints
 are kept in the logical environment, so failed alternatives cannot leak domains
-into later branches. The full Trealla library also contains automata,
-cumulative and two-dimensional scheduling constraints, and unbounded-domain
-propagation that are not yet exported here.
-
-`library(iso_ext)` collects extensions commonly found in mature Prolog
-systems. `call_nth/2` exposes the ordinal number of each solution and supports
-the explicit import used by Scryer-style source; `forall/2` checks an action for
-every solution of a condition; `cfor/3` enumerates an inclusive evaluated
-integer range; `succ/2` relates adjacent nonnegative integers; `findall/4`
-collects into a difference list; and `variant/2` recognizes terms equal up to
-variable renaming. Its portable `countall/2` counts solutions without exposing
-a template. `countall/2` is not exported by `library(lists)`, avoiding a
-full-module import collision between the two libraries.
-
-`uuid(+Seed0,-UUID,-Seed)` creates a version 4 UUID atom using `random/3`.
-Passing the returned seed to the next call produces the next UUID; restarting
-with the same integer seed reproduces the same sequence exactly. This explicit
-state replaces hidden host entropy and behaves identically in Node and the
-browser playground.
-
-On the command line, a program imports the modules it uses:
+into later branches. Trealla's larger library also contains facilities such as
+automata, cumulative and two-dimensional scheduling constraints, and
+unbounded-domain propagation that EyeProlog does not currently export.
+
+Beyond its interop entry for `call_nth/2`, `library(iso_ext)` also exports
+EyeProlog's extension relations `countall/2`, `forall/2`, `succ/2`, `cfor/3`,
+`findall/4`, and `variant/2`. `forall/2` checks an action for every solution of a
+condition; `cfor/3` enumerates an inclusive evaluated integer range; `succ/2`
+relates adjacent nonnegative integers; `findall/4` collects into a difference
+list; and `variant/2` recognizes terms equal up to variable renaming.
+`countall/2` counts solutions without exposing a template. These exports do not
+all belong to the conservative interop subset merely because they share the
+`iso_ext` module.
+
+`uuid(+Seed0,-UUID,-Seed)` from `library(uuid)` creates a version 4 UUID atom
+using `random/3`. Passing the returned seed to the next call produces the next
+UUID; restarting with the same integer seed reproduces the same sequence. This
+explicit state replaces hidden host entropy and behaves identically in Node and
+the browser playground.
+
+On the command line, a program can state its library dependencies explicitly:
 
 ```sh
 printf '%s\n' ':- use_module(library(lists)).' 'answer(X) :- member(X, [ready]).' > program.pl
@@ -6208,12 +6279,13 @@ eyeprolog --goal 'answer(X)' program.pl
 eyeprolog -p program.pl        # add proof output
 ```
 
-JavaScript uses the same registry by default:
+JavaScript uses the same normal EyeProlog library registry by default:
 
 ```js
 import { run } from 'eyeprolog';
 
 const source = `
+:- use_module(library(lists)).
 answer(Whole) :- append([red, green], [blue], Whole).
 `;
 
@@ -6221,7 +6293,7 @@ const result = run(source, { goal: 'answer(X)' });
 console.log(result.stdout);
 ```
 
-The mode notation below is descriptive:
+The mode notation used in the reference tables below is descriptive:
 
 - `+` means the argument must already have the required input shape;
 - `-` means the predicate produces that argument;
@@ -6230,9 +6302,9 @@ The mode notation below is descriptive:
 Most EyeProlog library predicates are projections or filters. When an input is
 unbound, malformed, outside its domain, or incompatible with the requested
 output, they normally **fail** rather than raising the ISO errors described in
-the errors section above. They do not invent open-ended domains. Bind arithmetic operands, source
-text, proper lists, indexes, dates, and aggregate generators before calling
-the corresponding predicate.
+the errors section above. They do not invent open-ended domains. Bind arithmetic
+operands, source text, proper lists, indexes, dates, and aggregate generators
+before calling the corresponding predicate.
 
 #### Portable numeric, comparison, and date relations