eyeprolog 1.5.1 → 1.5.2

package/index.d.ts

@@ -289,6 +289,9 @@ export const eyePrologLibraryIndicators: readonly string[];
 export const eyePrologNativeLibraryIndicators: readonly string[];
 export const eyePrologPortableLibraryIndicators: readonly string[];
 export const eyePrologInteropAutoload: Readonly<Record<string, string>>;
+export const eyePrologLibraryAutoload: Readonly<Record<string, string>>;
+export const eyePrologAmbiguousLibraryAutoload: Readonly<Record<string, readonly string[]>>;
+export const eyePrologLibraryAutoloadModules: readonly string[];
 export const eyePrologInteropLibraryIndicators: readonly string[];
 export const eyePrologInteropLibraryModules: readonly string[];
 export class PrologError extends Error {
@@ -374,6 +377,9 @@ declare const eyeprolog: {
   eyePrologNativeLibraryIndicators: typeof eyePrologNativeLibraryIndicators;
   eyePrologPortableLibraryIndicators: typeof eyePrologPortableLibraryIndicators;
   eyePrologInteropAutoload: typeof eyePrologInteropAutoload;
+  eyePrologLibraryAutoload: typeof eyePrologLibraryAutoload;
+  eyePrologAmbiguousLibraryAutoload: typeof eyePrologAmbiguousLibraryAutoload;
+  eyePrologLibraryAutoloadModules: typeof eyePrologLibraryAutoloadModules;
   eyePrologInteropLibraryIndicators: typeof eyePrologInteropLibraryIndicators;
   eyePrologInteropLibraryModules: typeof eyePrologInteropLibraryModules;
   run: typeof run;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",
@@ -46,7 +46,8 @@
   },
   "scripts": {
     "test": "node test/run-all.mjs",
-    "generate": "node tools/extract-book-examples.mjs",
+    "generate": "node tools/generate-library-autoload-index.mjs && node tools/extract-book-examples.mjs",
+    "generate:autoload": "node tools/generate-library-autoload-index.mjs",
     "test:eyeprolog": "node test/run-all.mjs",
     "test:conformance": "node test/run-conformance.mjs",
     "test:iso-strict": "node test/run-iso-strict.mjs",

package/src/cli.js

@@ -281,7 +281,7 @@ Options:
   --iso-strict          Use ISO/IEC 13211-1 core + Corrigenda 1-3 only;
                         reject EyeProlog language extensions.
   --portable            Enforce the EyeProlog/Trealla/Scryer interop profile.
-  --no-autoload         Disable conservative interop predicate autoloading.
+  --no-autoload         Disable bundled library predicate autoloading.
   -v, --version         Show the package version and exit.
   -w, --warnings        Print non-fatal portability warnings to stderr.
   -g, --goal goal       Solve goal and print its ground answers; may be repeated.

package/src/index.js

@@ -21,6 +21,9 @@ export {
   eyePrologNativeLibraryIndicators,
   eyePrologPortableLibraryIndicators,
   eyePrologInteropAutoload,
+  eyePrologLibraryAutoload,
+  eyePrologAmbiguousLibraryAutoload,
+  eyePrologLibraryAutoloadModules,
   eyePrologInteropLibraryIndicators,
   eyePrologInteropLibraryModules,
 } from './standard-library.js';

package/src/library-autoload-index.js

@@ -0,0 +1,346 @@
+// Generated by tools/generate-library-autoload-index.mjs.
+// Do not edit by hand; module/2 export lists under src/lib/ are the source of truth.
+
+export const eyePrologLibraryAutoload = Object.freeze({
+  ",/3": "reif",
+  ";/3": "reif",
+  ".../2": "iso_ext",
+  "*/1": "debug",
+  "\\/1": "lambda",
+  "\\/2": "lambda",
+  "\\/3": "lambda",
+  "\\/4": "lambda",
+  "\\/5": "lambda",
+  "\\/6": "lambda",
+  "\\/7": "lambda",
+  "\\/8": "lambda",
+  "#/\\/2": "clpz",
+  "#\\//2": "clpz",
+  "#\\/1": "clpz",
+  "#\\/2": "clpz",
+  "#\\=/2": "clpz",
+  "#</2": "clpz",
+  "#</3": "clpz",
+  "#<==/2": "clpz",
+  "#<==>/2": "clpz",
+  "#=/2": "clpz",
+  "#=/3": "clpz",
+  "#=</2": "clpz",
+  "#==>/2": "clpz",
+  "#>/2": "clpz",
+  "#>=/2": "clpz",
+  "^/10": "lambda",
+  "^/3": "lambda",
+  "^/4": "lambda",
+  "^/5": "lambda",
+  "^/6": "lambda",
+  "^/7": "lambda",
+  "^/8": "lambda",
+  "^/9": "lambda",
+  "+\\/2": "lambda",
+  "+\\/3": "lambda",
+  "+\\/4": "lambda",
+  "+\\/5": "lambda",
+  "+\\/6": "lambda",
+  "+\\/7": "lambda",
+  "+\\/8": "lambda",
+  "+\\/9": "lambda",
+  "=/3": "reif",
+  "$-/1": "debug",
+  "$/1": "debug",
+  "abolish_all_tables/0": "tabling",
+  "add_edges/3": "ugraphs",
+  "add_vertices/3": "ugraphs",
+  "aggregate_max/5": "aggregate",
+  "aggregate_min/5": "aggregate",
+  "all_different/1": "clpz",
+  "all_distinct/1": "clpz",
+  "append/2": "lists",
+  "append/3": "lists",
+  "assoc_to_keys/2": "assoc",
+  "assoc_to_list/2": "assoc",
+  "assoc_to_values/2": "assoc",
+  "atom_si/1": "si",
+  "atom_string/2": "strings",
+  "atomic_si/1": "si",
+  "automaton/3": "clpz",
+  "automaton/8": "clpz",
+  "bb_b_put/2": "debug",
+  "bb_get/2": "debug",
+  "bb_global_get/2": "debug",
+  "bb_put/2": "debug",
+  "between/3": "between",
+  "call_nth/2": "iso_ext",
+  "call_residue_vars/2": "atts",
+  "call_with_error_context/2": "error",
+  "can_be/2": "error",
+  "cfor/3": "iso_ext",
+  "chain/2": "clpz",
+  "char_type/2": "charsio",
+  "character_si/1": "si",
+  "chars_si/1": "si",
+  "circuit/1": "clpz",
+  "clpz_t/2": "clpz",
+  "complement/2": "ugraphs",
+  "compose/3": "ugraphs",
+  "cond_t/3": "reif",
+  "connect_ugraph/3": "ugraphs",
+  "contains/2": "strings",
+  "copy_term_nat/2": "terms",
+  "countall/2": "iso_ext",
+  "cumulative/1": "clpz",
+  "cumulative/2": "clpz",
+  "current_time/1": "time",
+  "debug/1": "debug",
+  "debug/3": "debug",
+  "del_assoc/4": "assoc",
+  "del_attr/2": "atts",
+  "del_edges/3": "ugraphs",
+  "del_max_assoc/4": "assoc",
+  "del_min_assoc/4": "assoc",
+  "del_vertices/3": "ugraphs",
+  "dif_si/2": "si",
+  "dif/2": "dif",
+  "dif/3": "reif",
+  "difference/3": "dates",
+  "disjoint2/1": "clpz",
+  "domain_error/2": "error",
+  "domain_error/3": "error",
+  "drop/3": "lists",
+  "edges/2": "ugraphs",
+  "element/3": "clpz",
+  "empty_assoc/1": "assoc",
+  "fd_dom/2": "clpz",
+  "fd_inf/2": "clpz",
+  "fd_size/2": "clpz",
+  "fd_sup/2": "clpz",
+  "fd_var/1": "clpz",
+  "findall/4": "iso_ext",
+  "foldl/4": "lists",
+  "foldl/5": "lists",
+  "foldl/6": "lists",
+  "forall/2": "iso_ext",
+  "format_/4": "format",
+  "format_time/4": "time",
+  "format/2": "format",
+  "format/3": "format",
+  "freeze/2": "freeze",
+  "ge/2": "comparison",
+  "gen_assoc/3": "assoc",
+  "gen_int/1": "between",
+  "gen_nat/1": "between",
+  "gensym/2": "gensym",
+  "get_assoc/3": "assoc",
+  "get_assoc/5": "assoc",
+  "get_attr/3": "atts",
+  "get_atts/2": "atts",
+  "get_line_to_chars/3": "charsio",
+  "get_n_chars/3": "charsio",
+  "get_single_char/1": "charsio",
+  "global_cardinality/2": "clpz",
+  "global_cardinality/3": "clpz",
+  "group_pairs_by_key/2": "pairs",
+  "gt/2": "comparison",
+  "if_/3": "reif",
+  "in/2": "clpz",
+  "indomain/1": "clpz",
+  "ins/2": "clpz",
+  "instantiation_error/0": "error",
+  "instantiation_error/1": "error",
+  "integer_si/1": "si",
+  "is_assoc/1": "assoc",
+  "is_ordset/1": "ordsets",
+  "join/3": "strings",
+  "label/1": "clpz",
+  "labeling/1": "clpb",
+  "labeling/2": "clpz",
+  "last/2": "lists",
+  "le/2": "comparison",
+  "length/2": "lists",
+  "lex_chain/1": "clpz",
+  "list_max/2": "lists",
+  "list_min/2": "lists",
+  "list_si/1": "si",
+  "list_to_assoc/2": "assoc",
+  "list_to_ord_set/2": "ordsets",
+  "list_to_set/2": "lists",
+  "listing/1": "format",
+  "lowercase/2": "strings",
+  "lsb/2": "arithmetic",
+  "lt/2": "comparison",
+  "map_assoc/2": "assoc",
+  "map_assoc/3": "assoc",
+  "map_list_to_pairs/3": "pairs",
+  "maplist/2": "lists",
+  "maplist/3": "lists",
+  "maplist/4": "lists",
+  "maplist/5": "lists",
+  "maplist/6": "lists",
+  "maplist/7": "lists",
+  "maplist/8": "lists",
+  "matches/2": "strings",
+  "matches/3": "strings",
+  "max_assoc/3": "assoc",
+  "max_list/2": "lists",
+  "maybe/0": "random",
+  "member/2": "lists",
+  "memberchk/2": "lists",
+  "memberd_t/3": "reif",
+  "min_assoc/3": "assoc",
+  "min_list/2": "lists",
+  "msb/2": "arithmetic",
+  "must_be/2": "error",
+  "neighbors/3": "ugraphs",
+  "neighbours/3": "ugraphs",
+  "nodebug/1": "debug",
+  "not_si/1": "si",
+  "nth0/3": "lists",
+  "nth0/4": "lists",
+  "nth1/3": "lists",
+  "nth1/4": "lists",
+  "number_string/2": "strings",
+  "numbervars/3": "terms",
+  "numlist/2": "between",
+  "numlist/3": "between",
+  "nvalue/2": "clpz",
+  "ord_add_element/3": "ordsets",
+  "ord_del_element/3": "ordsets",
+  "ord_disjoint/2": "ordsets",
+  "ord_empty/1": "ordsets",
+  "ord_intersect/2": "ordsets",
+  "ord_intersect/3": "ordsets",
+  "ord_intersection/2": "ordsets",
+  "ord_intersection/3": "ordsets",
+  "ord_intersection/4": "ordsets",
+  "ord_list_to_assoc/2": "assoc",
+  "ord_memberchk/2": "ordsets",
+  "ord_selectchk/3": "ordsets",
+  "ord_seteq/2": "ordsets",
+  "ord_subset/2": "ordsets",
+  "ord_subtract/3": "ordsets",
+  "ord_symdiff/3": "ordsets",
+  "ord_union/2": "ordsets",
+  "ord_union/3": "ordsets",
+  "ord_union/4": "ordsets",
+  "pairs_keys_values/3": "pairs",
+  "pairs_keys/2": "pairs",
+  "pairs_values/2": "pairs",
+  "permutation/2": "lists",
+  "phrase_from_file/2": "pio",
+  "phrase_from_file/3": "pio",
+  "phrase_to_file/2": "pio",
+  "phrase_to_file/3": "pio",
+  "phrase_to_stream/2": "pio",
+  "phrase/2": "dcgs",
+  "phrase/3": "dcgs",
+  "popcount/2": "arithmetic",
+  "portray_clause_/3": "format",
+  "portray_clause/1": "format",
+  "portray_clause/2": "format",
+  "put_assoc/4": "assoc",
+  "put_attr/3": "atts",
+  "put_atts/2": "atts",
+  "random_integer/3": "random",
+  "random_labeling/2": "clpb",
+  "random/1": "random",
+  "random/3": "random",
+  "reachable/3": "ugraphs",
+  "repeat/1": "between",
+  "replace/4": "strings",
+  "representation_error/1": "error",
+  "reset_gensym/1": "gensym",
+  "resource_error/1": "error",
+  "reverse/2": "lists",
+  "same_length/2": "lists",
+  "sat_count/2": "clpb",
+  "sat/1": "clpb",
+  "scalar_product/4": "clpz",
+  "select/3": "lists",
+  "seq/3": "dcgs",
+  "seqq/3": "dcgs",
+  "serialized/2": "clpz",
+  "set_nth0/4": "lists",
+  "set_random/1": "random",
+  "slice/4": "lists",
+  "smallest_divisor_from/3": "primes",
+  "split/3": "strings",
+  "start_tabling/2": "tabling",
+  "string_concat/3": "strings",
+  "substring/4": "strings",
+  "succ/2": "iso_ext",
+  "sum_list/2": "lists",
+  "sum/3": "clpz",
+  "sumall/3": "aggregate",
+  "take/3": "lists",
+  "taut/2": "clpb",
+  "term_attributed_variables/2": "atts",
+  "term_si/1": "si",
+  "term_string/2": "strings",
+  "tfilter/3": "reif",
+  "time/1": "iso_ext",
+  "tmember_t/3": "reif",
+  "tmember/2": "reif",
+  "top_sort/2": "ugraphs",
+  "top_sort/3": "ugraphs",
+  "tpartition/4": "reif",
+  "transitive_closure/2": "ugraphs",
+  "transpose_ugraph/2": "ugraphs",
+  "transpose/2": "lists",
+  "trim/2": "strings",
+  "tuples_in/2": "clpz",
+  "type_error/2": "error",
+  "type_error/3": "error",
+  "ugraph_union/3": "ugraphs",
+  "uppercase/2": "strings",
+  "uuid_string/2": "uuid",
+  "uuid/3": "uuid",
+  "uuidv4_string/1": "uuid",
+  "uuidv4/1": "uuid",
+  "variant/2": "iso_ext",
+  "vertices_edges_to_ugraph/3": "ugraphs",
+  "vertices/2": "ugraphs",
+  "weighted_maximum/3": "clpb",
+  "when_si/2": "si",
+  "when/2": "when",
+  "zcompare/3": "clpz"
+});
+
+export const eyePrologAmbiguousLibraryAutoload = Object.freeze({});
+
+export const eyePrologLibraryAutoloadModules = Object.freeze([
+  "aggregate",
+  "arithmetic",
+  "assoc",
+  "atts",
+  "between",
+  "charsio",
+  "clpb",
+  "clpz",
+  "comparison",
+  "dates",
+  "dcgs",
+  "debug",
+  "dif",
+  "error",
+  "format",
+  "freeze",
+  "gensym",
+  "iso_ext",
+  "lambda",
+  "lists",
+  "ordsets",
+  "pairs",
+  "pio",
+  "primes",
+  "prologue",
+  "random",
+  "reif",
+  "si",
+  "strings",
+  "tabling",
+  "terms",
+  "time",
+  "ugraphs",
+  "uuid",
+  "when"
+]);

package/src/program.js

@@ -12,11 +12,12 @@ import {
   parseGoalText,
   tryParseClausesFastInto,
 } from './parser.js';
-import { PrologError, convertClauseBodyTerm, getStrictIsoRegistry } from './iso.js';
+import { PrologError, convertClauseBodyTerm, getDefaultRegistry, getStrictIsoRegistry } from './iso.js';
 import { currentWorkingDirectory, fs, path } from './platform.js';
 import {
   standardLibrarySources,
-  eyePrologInteropAutoload,
+  eyePrologAmbiguousLibraryAutoload,
+  eyePrologLibraryAutoload,
   eyePrologInteropLibraryIndicators,
   eyePrologInteropLibraryModules,
 } from './standard-library.js';
@@ -255,7 +256,10 @@ export class Program {
       }
     }
     this.initializations = [];
-    this._initializationsExecuted = false;
+    // Track how many initialization/1 directives have run so a REPL can
+    // autoload a library after startup and execute only that library's newly
+    // appended initializations without repeating earlier side effects.
+    this._initializationsExecutedCount = 0;
     this.quads = [];
     this.prologFlagDirectives = [];
     this.charConversionDirectives = [];
@@ -1045,7 +1049,7 @@ export function autoloadProgramGoals(program, inputs, options = {}) {
     const builder = new ProgramBuilder({ ...options, isoStrict: false }, program);
     const loadedModules = new Set([...program.modules.keys()].filter((name) => name !== 'user'));
     const autoloadCount = program.autoloadedPredicates.length;
-    autoloadInteropDependencies(builder, {
+    autoloadLibraryDependencies(builder, {
       ...options,
       isoStrict: false,
       operatorState,
@@ -1094,7 +1098,7 @@ function loadSourcesIntoBuilder(builder, sources, options, fast) {
       parserFlagState,
     }, builder.program);
     if (options.isoStrict !== true && options.autoload !== false) {
-      autoloadInteropDependencies(builder, {
+      autoloadLibraryDependencies(builder, {
         ...options,
         operatorState,
         parserFlagState,
@@ -1164,14 +1168,32 @@ function extraGoalDependencies(goals) {
   return dependencies;
 }
 
-function interopAutoloadRequests(program, extraGoals = []) {
+function procedureResolvedBeforeAutoload(program, dependency, targetModule) {
+  if (program.findGroup(dependency.name, dependency.arity, targetModule)) return true;
+  return program.moduleImports.get(targetModule)?.has(dependency.key) === true;
+}
+
+function autoloadLibraryFor(dependency) {
+  // ISO built-ins always take precedence over optional library autoloading.
+  if (getDefaultRegistry().get(dependency.name, dependency.arity) != null) return null;
+  const ambiguous = eyePrologAmbiguousLibraryAutoload[dependency.key];
+  if (ambiguous != null) {
+    throw new PrologError(
+      'permission_error(import, procedure)',
+      compound('/', [atom(dependency.name), numberTerm(dependency.arity)]),
+    );
+  }
+  return eyePrologLibraryAutoload[dependency.key] ?? null;
+}
+
+function libraryAutoloadRequests(program, extraGoals = []) {
   const requests = new Map();
   for (const group of program.groups.values()) {
     if (bundledLibraryModule(program, group.module)) continue;
     for (const dependency of groupDependencies(group)) {
       const targetModule = dependency.module ?? group.module;
-      if (program.findGroup(dependency.name, dependency.arity, targetModule)) continue;
-      const library = eyePrologInteropAutoload[dependency.key];
+      if (procedureResolvedBeforeAutoload(program, dependency, targetModule)) continue;
+      const library = autoloadLibraryFor(dependency);
       if (library == null) continue;
       const requestKey = `${targetModule}\u0000${dependency.key}`;
       requests.set(requestKey, {
@@ -1186,8 +1208,8 @@ function interopAutoloadRequests(program, extraGoals = []) {
   for (const goal of program.initializations) {
     for (const dependency of collectGoalDependencies(goal, false, true)) {
       const targetModule = dependency.module ?? 'user';
-      if (program.findGroup(dependency.name, dependency.arity, targetModule)) continue;
-      const library = eyePrologInteropAutoload[dependency.key];
+      if (procedureResolvedBeforeAutoload(program, dependency, targetModule)) continue;
+      const library = autoloadLibraryFor(dependency);
       if (library == null) continue;
       const requestKey = `${targetModule}\u0000${dependency.key}`;
       requests.set(requestKey, {
@@ -1201,8 +1223,8 @@ function interopAutoloadRequests(program, extraGoals = []) {
   }
   for (const dependency of extraGoalDependencies(extraGoals)) {
     const targetModule = dependency.module ?? 'user';
-    if (program.findGroup(dependency.name, dependency.arity, targetModule)) continue;
-    const library = eyePrologInteropAutoload[dependency.key];
+    if (procedureResolvedBeforeAutoload(program, dependency, targetModule)) continue;
+    const library = autoloadLibraryFor(dependency);
     if (library == null) continue;
     const requestKey = `${targetModule}\u0000${dependency.key}`;
     requests.set(requestKey, {
@@ -1216,14 +1238,14 @@ function interopAutoloadRequests(program, extraGoals = []) {
   return [...requests.values()];
 }
 
-function autoloadInteropDependencies(builder, options, ensured, loadedModules, extraGoals = []) {
+function autoloadLibraryDependencies(builder, options, ensured, loadedModules, extraGoals = []) {
   const program = builder.program;
   while (true) {
-    const requests = interopAutoloadRequests(program, extraGoals);
+    const requests = libraryAutoloadRequests(program, extraGoals);
     if (requests.length === 0) return;
     let changed = false;
     for (const request of requests) {
-      if (program.findGroup(request.name, request.arity, request.targetModule)) continue;
+      if (procedureResolvedBeforeAutoload(program, request, request.targetModule)) continue;
       if (!loadedModules.has(request.library)) {
         const designation = compound('library', [atom(request.library)]);
         const loaded = readModuleSource(designation, options);

package/src/repl.js

@@ -4,6 +4,7 @@ import { readSync } from 'node:fs';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { formalErrorTerm } from './iso.js';
+import { autoloadProgramGoals } from './program.js';
 import {
   characterCodeConstantEnd, continuesGraphicToken, isTerminatingFullStop, quotedEscapeEnd,
 } from './syntax-scan.js';
@@ -67,6 +68,19 @@ export async function runRepl(engine, options = {}) {
           continue;
         }
 
+        // Queries entered after the initial Program was prepared need the same
+        // bundled-library autoload resolution as file and -g execution.  This
+        // is intentionally after parsing: predicate autoloading cannot provide
+        // syntax operators retroactively (libraries such as clpz must still be
+        // imported explicitly before their operators are used).
+        if (!state.strictIso && options.autoload !== false) {
+          autoloadProgramGoals(state.program, [goal], {
+            autoload: true,
+            doubleQuotes: state.solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
+          });
+          runWithTerminalSignals(reader, () => state.solver.runInitializations());
+        }
+
         const flagsBefore = snapshotFlagValues(state.solver);
         try {
           await prepareInteractiveTermInput(state, goal, reader);
@@ -284,7 +298,11 @@ function runWithTerminalSignals(reader, operation) {
 
 function makeState(engine, sources, output, options = {}, previousState = null, reader = null) {
   const strictIso = options.isoStrict === true;
-  const program = engine.Program.parseSources(sources, { strictIso, sourceMetadata: strictIso });
+  const program = engine.Program.parseSources(sources, {
+    isoStrict: strictIso,
+    sourceMetadata: strictIso,
+    autoload: !strictIso && options.autoload !== false,
+  });
   const solver = new engine.Solver(program, {
     registry: strictIso ? engine.getStrictIsoRegistry() : engine.getEyePrologRegistry(),
     isoStrict: strictIso,
@@ -756,12 +774,29 @@ function formatAnswer(engine, state, variables, env) {
     collectUnboundVariables(engine, residual, env, names, () => `_${letterName(generated++)}`);
     bindings.push(engine.formatTermForWrite(residual, env, answerWriteOptions));
   }
+  // Residual attributes are part of the answer even when the attributed
+  // variable was created inside a called predicate and is not itself a query
+  // variable (issue #87).  First retain visible query names for attributed
+  // roots, then project every remaining live attributed root with a generated
+  // top-level variable name.  This also makes call_residue_vars/2 useful at the
+  // top level: variables returned through its list share the same name with the
+  // projected constraint instead of appearing unconstrained.
   const projectedAttributeRoots = new Set();
+  const attributeRoots = [];
   for (const variable of variables) {
     const root = engine.deref(variable, env);
-    if (root.type !== 'var' || projectedAttributeRoots.has(root.name) || !env.hasPrologAttributes?.(root.name)) continue;
-    projectedAttributeRoots.add(root.name);
+    if (root.type !== 'var' || !env.hasPrologAttributes?.(root.name)) continue;
     names.set(root.name, variable.name);
+    attributeRoots.push(root);
+  }
+  for (const name of env.attributedVariableNames?.() ?? []) {
+    const root = engine.deref(engine.variable(name), env);
+    if (root.type === 'var') attributeRoots.push(root);
+  }
+  for (const root of attributeRoots) {
+    if (projectedAttributeRoots.has(root.name) || !env.hasPrologAttributes?.(root.name)) continue;
+    projectedAttributeRoots.add(root.name);
+    if (!names.has(root.name)) names.set(root.name, `_${letterName(generated++)}`);
     for (const residual of state.solver.attributeResidualGoals(root, env)) {
       collectUnboundVariables(engine, residual, env, names, () => `_${letterName(generated++)}`);
       bindings.push(engine.formatTermForWrite(residual, env, answerWriteOptions));

package/src/solver.js

@@ -375,18 +375,19 @@ export class Solver {
   }
 
   runInitializations() {
-    if (this.program._initializationsExecuted) return;
-    for (const goal of this.program.initializations ?? []) {
+    const goals = this.program.initializations ?? [];
+    let index = this.program._initializationsExecutedCount ?? 0;
+    for (; index < goals.length; index++) {
       let succeeded = false;
-      for (const _ of this.solve([goal], new Env(), 0)) {
+      for (const _ of this.solve([goals[index]], new Env(), 0)) {
         succeeded = true;
         break;
       }
       if (!succeeded) throw new PrologError('initialization_error');
+      // Mark each successful initialization immediately. If a later one fails,
+      // retrying does not repeat already completed initialization side effects.
+      this.program._initializationsExecutedCount = index + 1;
     }
-    // 7.4.2.6 attaches initialization to preparation of the Prolog text, not
-    // to each later Solver instance created for the same prepared Program.
-    this.program._initializationsExecuted = true;
   }
 
   *solve(goals, env = new Env(), depth = 0) {

package/src/standard-library.js

@@ -1,7 +1,7 @@
 // Prolog library modules shipped with EyeProlog and loaded through its documented module compatibility surface.
 // The sources are registered here so library(Name) works in Node and browsers.
-// Modules are loaded on demand by explicit use_module/1-2 or by the conservative
-// source-level interop autoloader declared below.
+// Modules are loaded on demand by explicit use_module/1-2 or by the generic
+// source-level autoloader generated from every bundled module/2 export list.
 import { PrologError, createDefaultRegistry, eyePrologLibraryBuiltins } from './iso.js';
 import { attsBuiltins } from './atts.js';
 import { expansionBuiltins } from './expansion-builtins.js';
@@ -9,6 +9,9 @@ import { scryerCompatibilityBuiltins } from './scryer-compat.js';
 import { registerCleanupBuiltins } from './cleanup.js';
 import { fs, isNode, memoryStatistics } from './platform.js';
 import { ATOM, VAR, atom, deref, numberTerm, unify } from './term.js';
+import { eyePrologAmbiguousLibraryAutoload, eyePrologLibraryAutoload, eyePrologLibraryAutoloadModules } from './library-autoload-index.js';
+
+export { eyePrologAmbiguousLibraryAutoload, eyePrologLibraryAutoload, eyePrologLibraryAutoloadModules };
 
 const moduleFiles = Object.freeze({
   aggregate: 'aggregate.pl',
@@ -152,10 +155,12 @@ export const eyePrologLibraryIndicators = Object.freeze([
 ]);
 
 
-// Conservative cross-implementation profile.  These predicate indicators are
-// intentionally limited to interfaces that EyeProlog wants to keep source-
-// compatible with the Trealla/Scryer ecosystem.  The value is the canonical
-// EyeProlog library used when an otherwise undefined call is autoloaded.
+// Conservative cross-implementation profile metadata. These predicate indicators
+// are intentionally limited to interfaces that EyeProlog wants to keep source-
+// compatible with the Trealla/Scryer ecosystem. The complete runtime autoload
+// index is generated separately from every bundled module/2 export; this smaller
+// map is retained as the canonical interoperability subset used by diagnostics
+// and public metadata.
 //
 // This is deliberately separate from eyePrologPortableLibraryIndicators:
 // "portable" there means implemented in Prolog rather than as a host builtin;

package/test/run-regression.mjs

@@ -26,6 +26,9 @@ import {
   eyePrologNativeLibraryIndicators,
   eyePrologPortableLibraryIndicators,
   eyePrologInteropAutoload,
+  eyePrologLibraryAutoload,
+  eyePrologAmbiguousLibraryAutoload,
+  eyePrologLibraryAutoloadModules,
   eyePrologInteropLibraryIndicators,
   eyePrologInteropLibraryModules,
   atom,
@@ -519,6 +522,24 @@ attribute_goals(X) --> { get_atts(X, required(V)) }, [required(X,V)].
         assertIncludes(repl.stdout, 'dif(Y, c), freeze:freeze(Y, a).',
           'freeze/2 and dif/2 residuals share the query variable (issue #73)');
 
+        const hiddenResidualFile = path.join(tmp, `atts-hidden-residual-${++tmpCounter}.pl`);
+        fs.writeFileSync(hiddenResidualFile, 'ffalse :- freeze(_, false).\n');
+        const hiddenResidual = runCli([], {
+          input:
+            `[${sourceAtom(hiddenResidualFile)}].\n` +
+            'ffalse.\n' +
+            'call_residue_vars(ffalse, Vs).\n' +
+            'freeze(V,false).\n' +
+            'halt.\n',
+        });
+        assertEqual(hiddenResidual.status, 0, 'hidden attribute residual REPL status');
+        assertIncludes(hiddenResidual.stdout, 'freeze:freeze(_A, false).',
+          'top level projects hidden attributed variables (issue #87)');
+        assertIncludes(hiddenResidual.stdout, 'Vs = [_A], freeze:freeze(_A, false).',
+          'call_residue_vars/2 shares its returned variable with the projected residue (issue #87)');
+        assertIncludes(hiddenResidual.stdout, 'freeze:freeze(V, false).',
+          'direct top-level freeze/2 keeps the visible query variable name');
+
         const scryerShape = Program.parse(`:- module(scryer_shape, [op(700, xfx, #=), probe/0]).
 :- op(700, xfx, #=).
 :- use_module(library(atts)).
@@ -2850,7 +2871,7 @@ c4 ?- call((!;1)).
       },
     },
     {
-      name: 'REPL applies conservative autoloading to interactive time/1 and consulted ... //0',
+      name: 'REPL applies bundled-library autoloading to interactive time/1 and consulted ... //0',
       run: () => {
         const filename = path.join(tmp, `issue49-handoff-${tmpCounter++}.pl`);
         fs.writeFileSync(filename, 'a --> ..., epsilon.\nepsilon --> [].\n');
@@ -3632,14 +3653,14 @@ child.stdin.write(\`consult(${consultedAtom}).\\n\`);
       },
     },
     {
-      name: 'REPL use_module imports Part 2 library predicates',
+      name: 'REPL autoload and explicit use_module coexist for Part 2 library predicates',
       run: () => {
         const result = runCli([], {
           input: 'append(X, Y, [1, 2, 3, 4]).\nuse_module(library(lists)).\nappend(X, Y, [1, 2, 3, 4]).\n\nhalt.\n',
         });
         assertEqual(result.status, 0, 'exit status');
         assertEqual(result.stdout,
-          '?-    error(existence_error(procedure, append / 3), eyeprolog).\n' +
+          '?-    X = [], Y = [1, 2, 3, 4].\n' +
           '?-    true.\n' +
           '?-    X = [], Y = [1, 2, 3, 4]\n;  ... .\n?- ',
           'stdout');
@@ -3946,6 +3967,50 @@ child.stdin.write(\`consult(${consultedAtom}).\\n\`);
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'interactive top level autoloads unresolved bundled predicates',
+      run: () => {
+        const result = runCli([], {
+          input: 'append(X,Y,[1,2]).\n;\nhalt.\n',
+        });
+        assertEqual(result.status, 0, 'exit status');
+        assertIncludes(result.stdout, 'X = [], Y = [1, 2]', 'first append/3 answer');
+        assertIncludes(result.stdout, 'X = [1], Y = [2].', 'second append/3 answer');
+        assertNotIncludes(result.stdout, 'existence_error(procedure, append / 3)', 'autoload failure');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'all bundled library exports participate in generic autoloading',
+      run: () => {
+        const input = [
+          '%% goal: pair_answer(K,V)',
+          '%% goal: string_answer(X)',
+          '%% goal: prime_answer(X)',
+          'pair_answer(K,V) :- pairs_keys_values([a-1,b-2], K, V).',
+          'string_answer(X) :- uppercase("hello", X).',
+          'prime_answer(X) :- smallest_divisor_from(91, 2, X).',
+          '',
+        ].join('\n');
+        const result = runCli(['-'], { input });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout,
+          'pair_answer("ab", [1, 2]).\nstring_answer(\'HELLO\').\nprime_answer(7).\n', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'generic autoload index is generated from every bundled library module',
+      run: () => {
+        assertEqual(eyePrologLibraryAutoload['member/2'], 'lists', 'facade duplicate resolves to defining lists module');
+        assertEqual(eyePrologLibraryAutoload['pairs_keys_values/3'], 'pairs', 'pairs export is autoloadable');
+        assertEqual(eyePrologLibraryAutoload['uppercase/2'], 'strings', 'strings export is autoloadable');
+        assertEqual(eyePrologLibraryAutoload['smallest_divisor_from/3'], 'primes', 'primes export is autoloadable');
+        assertEqual(Object.keys(eyePrologAmbiguousLibraryAutoload).length, 0, 'current bundled surface has no unresolved export ambiguities');
+        assertEqual(eyePrologLibraryAutoloadModules.length, standardLibrarySources.size, 'every registered bundled module is indexed');
+        assertEqual([...standardLibrarySources.keys()].sort().join(','), [...eyePrologLibraryAutoloadModules].sort().join(','), 'autoload module index matches bundled sources');
+      },
+    },
     {
       name: 'between/3 generated values avoid recursive environment chains (issue #52)',
       run: () => {
@@ -3994,7 +4059,7 @@ child.stdin.write(\`consult(${consultedAtom}).\\n\`);
       },
     },
     {
-      name: 'strict ISO mode disables interop autoloading',
+      name: 'strict ISO mode disables bundled-library autoloading',
       run: () => {
         const input = '%% goal: answer(X)\nanswer(X) :- member(X, [a,b]).\n';
         const result = runCli(['--iso-strict', '-'], { input });
@@ -4004,7 +4069,7 @@ child.stdin.write(\`consult(${consultedAtom}).\\n\`);
       },
     },
     {
-      name: 'CLI top-level goals participate in interop autoloading',
+      name: 'CLI top-level goals participate in bundled-library autoloading',
       run: () => {
         const result = runCli(['-g', 'member(X,[a,b])', '-'], { input: '' });
         assertEqual(result.status, 0, 'exit status');
@@ -4707,6 +4772,18 @@ answer(Result) :- countdown(2048, Result), Result = 2048.
 
 function documentationSyncCases() {
   return [
+    {
+      name: 'generated bundled-library autoload index matches src/lib module exports',
+      run: () => {
+        const result = spawnSync(process.execPath, [path.join(packageRoot, 'tools', 'generate-library-autoload-index.mjs'), '--check'], {
+          cwd: packageRoot,
+          encoding: 'utf8',
+        });
+        assertEqual(result.status, 0, 'exit status');
+        assertIncludes(result.stdout, 'library-autoload-index.js is up to date', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
     {
       name: 'WG17 syntax status matches its executable-coverage manifest',
       run: () => {
@@ -5678,7 +5755,7 @@ answer(ok) :-
       },
     },
     {
-      name: 'autoload metadata records canonical interop imports',
+      name: 'autoload metadata records canonical bundled-library imports',
       run: () => {
         const program = Program.parse('answer(X) :- member(X, [a]), between(1, 1, _).\n');
         assertEqual(program.autoloadedPredicates.length, 2, 'autoloaded predicate count');
@@ -5688,7 +5765,7 @@ answer(ok) :-
       },
     },
     {
-      name: 'JavaScript run top-level goals participate in interop autoloading',
+      name: 'JavaScript run top-level goals participate in bundled-library autoloading',
       run: () => {
         const result = runEyeProlog('', { goal: 'member(X,[a,b])' });
         assertEqual(result.stdout, 'member(a, "ab").\nmember(b, "ab").\n', 'stdout');
@@ -6192,7 +6269,10 @@ answer(ok) :-
         assertEqual(eyePrologInteropAutoload['call_residue_vars/2'], 'atts', 'call_residue_vars/2 canonical interop autoload');
         assertEqual(eyePrologInteropAutoload['time/1'], 'iso_ext', 'time/1 canonical interop autoload');
         assertEqual(eyePrologInteropAutoload['.../2'], 'iso_ext', '.../2 canonical interop autoload');
-        assertEqual(eyePrologInteropAutoload['set_nth0/4'] ?? null, null, 'EyeProlog-only set_nth0/4 is not autoloadable');
+        assertEqual(eyePrologInteropAutoload['set_nth0/4'] ?? null, null, 'set_nth0/4 is outside the conservative interop subset');
+        assertEqual(eyePrologLibraryAutoload['set_nth0/4'], 'lists', 'complete library autoload includes EyeProlog-only exports');
+        assertEqual(eyePrologLibraryAutoload['pairs_keys_values/3'], 'pairs', 'complete library autoload includes library(pairs)');
+        assertEqual(eyePrologLibraryAutoloadModules.length, 35, 'all bundled src/lib modules are indexed for autoload');
         assertEqual(eyePrologNativeLibraryIndicators.length, 58, 'host-supported library count');
         assertEqual(eyePrologNativeLibraryIndicators.slice(0, 3).join(','), 'call_nth/2,freeze/2,dif/2', 'control and constraint predicates requiring host support');
         assertEqual(eyePrologNativeLibraryIndicators.includes('random/1'), true, 'stateful random/1 is classified as host-supported');

package/the-art-of-eyeprolog.md

@@ -1860,10 +1860,11 @@ additional logical answer.
 `analyzeNegation`. It returns `stdout`, the solver's numeric `stats`, and a
 nullable `haltCode`; it does not write to the process streams.
 
-When `run` receives an already parsed `Program`, canonical interop imports
+When `run` receives an already parsed `Program`, bundled-library imports
 needed only by its host-supplied goals are added to that Program before solving,
-just as they are while source text is parsed. Pass `autoload: false` when the
-Program must retain only explicitly imported predicates.
+just as they are while source text is parsed. The autoload index covers every
+exported predicate in the bundled `src/lib/` modules. Pass `autoload: false`
+when the Program must retain only explicitly imported predicates.
 
 For applications that inspect or prepare a theory before running it, use
 `Program` directly:
@@ -6303,8 +6304,9 @@ as a compatibility facade over the canonical `lists`, `between`, `iso_ext`,
 and `freeze` modules. The published Prologue, `call_nth/2`, and `length/2`
 quads are retained as offline regressions. `src/standard-library.js` registers the module sources and private control and
 constraint adapters for Node and browser resolution. Explicit `use_module/1-2`
-loads remain supported; outside strict ISO mode, the conservative interop
-autoloader may also load a module for one uniquely mapped common predicate.
+loads remain supported; outside strict ISO mode, the bundled-library autoloader
+may also load the canonical owner of any exported `src/lib/` predicate. The
+autoload index is generated from the libraries' `module/2` declarations.
 The core registry remains available through `createDefaultRegistry()` and
 `getDefaultRegistry()` for low-level embedding. The stricter Part 1 +
 Corrigenda registry is exposed as `createStrictIsoRegistry()` and
@@ -6382,7 +6384,7 @@ bindings make one aligned subterm pair sufficient. For example:
 
 <!-- eyeprolog-library-catalog:end -->
 
-#### Interoperability profile and conservative autoloading
+#### Interoperability profile and bundled-library autoloading
 
 EyeProlog keeps four related concepts separate:
 
@@ -6391,7 +6393,7 @@ EyeProlog keeps four related concepts separate:
 | **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. |
+| **Autoload index** | A generated index of every predicate exported by the bundled `src/lib/` modules, with one canonical provider per unambiguous predicate. |
 
 These layers answer different questions. A predicate may be implemented entirely
 as ordinary Prolog and still be outside the cross-processor interoperability
@@ -6452,9 +6454,9 @@ EyeProlog API belongs to the shared profile. `call_nth/2`, `time/1`, and
 prints elapsed time, EyeProlog inference count, and MLips in Trealla-style form,
 for example `% Time elapsed 0.832s, 65551 Inferences, 0.079 MLips`; `... //0`
 describes an arbitrary number of input elements. Together they let the
-Trealla/Scryer DCG hand-off benchmark run in EyeProlog without source changes
-(assuming the usual list library is already imported in an interactive
-session). The focused modules have one canonical implementation owner per
+Trealla/Scryer DCG hand-off benchmark run in EyeProlog without source changes;
+the interactive top level uses the same bundled-predicate autoloader as file and
+CLI/API goal execution. The focused modules have one canonical implementation owner per
 predicate. `library(prologue)` re-exports those same owners, so legacy code can
 combine the facade with `library(lists)`, `library(iso_ext)`, and
 `library(freeze)` in either import order without an accidental collision.
@@ -6488,25 +6490,41 @@ 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. When a source program
-or an explicit CLI/API goal is built, an otherwise undefined **unqualified**
-predicate may be autoloaded only when the interop table assigns it one canonical
-provider. The interactive top level keeps ordinary library imports explicit;
-`time/1` is available there because it is also a normal EyeProlog runtime
-extension. For example, the canonical build-time providers are:
+Autoloading is a convenience layered on top of the module system and is
+independent of the smaller interoperability profile. At build time EyeProlog
+uses a generated index derived from every bundled `src/lib/*.pl` `module/2`
+export list. An otherwise unresolved predicate in source, initialization code, an explicit
+CLI/API goal, or an interactive top-level query therefore autoloads its canonical
+bundled provider.
+For example:
 
 | Predicate | Canonical autoload provider |
 | --- | --- |
 | `member/2` | `library(lists)` |
-| `call_nth/2` | `library(iso_ext)` |
-| `time/1` | `library(iso_ext)` |
-| `.../2` | `library(iso_ext)` |
+| `pairs_keys_values/3` | `library(pairs)` |
+| `uppercase/2` | `library(strings)` |
+| `smallest_divisor_from/3` | `library(primes)` |
 | `between/3` | `library(between)` |
 
-Predicates outside that table require an explicit import even when EyeProlog
-provides them. Explicit imports therefore remain the clearest way to state
-library dependencies:
+The resolution order is deliberately conservative with respect to Prolog
+semantics: a predicate already defined by the program wins; ISO/standard
+built-ins are not replaced by an autoloaded library; an explicit module import
+wins over autoloading; only then is the bundled autoload index consulted.
+Facade modules such as `library(prologue)` may re-export predicates from focused
+modules; the generated index chooses the unique module that actually defines
+the predicate. If more than one bundled module genuinely defines the same
+export, EyeProlog reports an import ambiguity and requires explicit
+`use_module/1-2` rather than guessing. The interactive top level applies this
+same resolution after a query has been parsed. Autoloading therefore supplies
+predicates, not retroactive syntax: a library that introduces operators (for
+example `library(clpz)` and `ins`) must still be explicitly imported before a
+query or source term uses those operators.
+
+The index is generated by `npm run generate:autoload` into
+`src/library-autoload-index.js`, and the documentation regression suite checks
+that it is synchronized with the current `src/lib/` sources. Explicit imports
+remain the clearest way to state dependencies when portability or module intent
+should be visible in the source:
 
 ```text
 :- use_module(library(lists)).
@@ -6515,7 +6533,8 @@ library dependencies:
 
 Use `--no-autoload`, or the JavaScript option `autoload: false`, when every
 library dependency should be explicit. `--iso-strict` always disables EyeProlog
-library autoloading.
+library autoloading, so strict ISO execution never gains procedures from this
+implementation convenience.
 
 `-w` / `--warnings` reports explicit dependencies on non-profile libraries and
 calls to non-profile predicates from otherwise common modules. `--portable`
@@ -6927,9 +6946,17 @@ 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
 host top-level convention rather than an ISO/IEC 13211-1 language feature. A
-period-terminated query with no solutions prints `false.`; a solution without
-visible variable bindings prints `true.`. Answer substitutions are rendered as
-valid Prolog syntax under the current operator table: when a bound value would
+period-terminated query with no solutions prints `false.`. A solution without
+visible variable bindings prints `true.` only when it also has no pending
+residual goals. Residual constraints are part of the displayed answer even when
+the attributed variable was created inside a called predicate and is not a
+visible query variable; the top level assigns such variables generated names
+like `_A`. For example, if `ffalse :- freeze(_, false).`, the query `ffalse.`
+displays `freeze:freeze(_A, false).`, and
+`call_residue_vars(ffalse, Vs).` displays
+`Vs = [_A], freeze:freeze(_A, false).` rather than implying that the returned
+variable is unconstrained. Answer substitutions are rendered as valid Prolog
+syntax under the current operator table: when a bound value would
 not be a valid right operand of the displayed `=/2`, EyeProlog adds parentheses,
 for example `T = (a = b).` rather than the invalid `T = a = b.`. When an answer
 ends in a graphic token, the top level inserts layout before its terminating
@@ -6994,9 +7021,9 @@ make the observed question explicit.
 | `-h`, `--help` | Show usage |
 | `-p`, `--proof` | Print `why/2` explanations |
 | `-q`, `--quads` | Run embedded quad tests and fail if any do not hold |
-| `--iso-strict` | Restrict parsing and execution to ISO/IEC 13211-1:1995 + Corrigenda 1–3; reject EyeProlog language extensions (including `table` and `:+`) and disable interop autoloading |
+| `--iso-strict` | Restrict parsing and execution to ISO/IEC 13211-1:1995 + Corrigenda 1–3; reject EyeProlog language extensions (including `table` and `:+`) and disable bundled-library autoloading |
 | `--portable` | Enforce the conservative EyeProlog/Trealla/Scryer interoperability profile |
-| `--no-autoload` | Disable conservative interop predicate autoloading |
+| `--no-autoload` | Disable bundled-library predicate autoloading |
 | `-s`, `--stats` | Print final solver and memory statistics to stderr after execution |
 | `-v`, `--version` | Print the package version |
 | `-w`, `--warnings` | Print non-fatal portability warnings |
@@ -7011,8 +7038,8 @@ retains the Part 1 prefix `(?-)/1` operator and treats `-->/2` as ordinary Part
 `phrase/2-3`. Part 2 module directives and EyeProlog libraries are rejected,
 the implementation-specific `occurs_check` flag is absent, and the normal-profile
 `table` declaration is unavailable. Normal mode continues to support Parts
-2–3 and EyeProlog extensions, plus conservative interop autoloading for the
-profile documented above.
+2–3 and EyeProlog extensions, plus generated autoloading across the bundled
+`src/lib/` library exports documented above.
 
 Inputs may be local files, HTTP(S) URLs, or one `-` for stdin. The bare command
 `eyeprolog` starts the normal REPL; `eyeprolog --iso-strict` starts the strict

package/tools/generate-library-autoload-index.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseClauses } from '../src/parser.js';
+import { ATOM, COMPOUND, NUMBER, Env, properListItems } from '../src/term.js';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const libDir = path.join(root, 'src', 'lib');
+const outputFile = path.join(root, 'src', 'library-autoload-index.js');
+
+function predicateIndicator(nameTerm, arityTerm, extraArity = 0) {
+  if (nameTerm?.type !== ATOM || arityTerm?.type !== NUMBER || !/^\d+$/.test(arityTerm.name)) return null;
+  const arity = Number(arityTerm.name) + extraArity;
+  return { name: nameTerm.name, arity, key: `${nameTerm.name}/${arity}` };
+}
+
+function moduleExports(term) {
+  const items = properListItems(term, new Env());
+  if (items == null) throw new Error('module export list is not a proper list');
+  const exports = [];
+  for (const item of items) {
+    if (item?.type === COMPOUND && item.name === 'op' && item.arity === 3) continue;
+    if (item?.type !== COMPOUND || !['/', '//'].includes(item.name) || item.arity !== 2) {
+      throw new Error(`unsupported module export: ${item?.name ?? '<unknown>'}`);
+    }
+    const indicator = predicateIndicator(item.args[0], item.args[1], item.name === '//' ? 2 : 0);
+    if (indicator == null) throw new Error('invalid predicate indicator in module export');
+    exports.push(indicator);
+  }
+  return exports;
+}
+
+function localDefinitionKey(clause) {
+  const head = clause?.head;
+  if (head == null) return null;
+  if (head.type === COMPOUND && head.name === ':-' && head.arity === 1) return null;
+  if (head.type === COMPOUND && head.name === '-->' && head.arity === 2) {
+    const nt = head.args[0];
+    if (nt?.type !== ATOM && nt?.type !== COMPOUND) return null;
+    return `${nt.name}/${nt.arity + 2}`;
+  }
+  if (head.type !== ATOM && head.type !== COMPOUND) return null;
+  return `${head.name}/${head.arity}`;
+}
+
+const candidates = new Map();
+const modules = [];
+for (const filename of fs.readdirSync(libDir).filter((name) => name.endsWith('.pl')).sort()) {
+  const source = fs.readFileSync(path.join(libDir, filename), 'utf8');
+  const clauses = parseClauses(source, { filename: `src/lib/${filename}`, sourceMetadata: false });
+  const definitions = new Set(clauses.map(localDefinitionKey).filter(Boolean));
+  let moduleName = null;
+  let exports = null;
+  for (const clause of clauses) {
+    const directive = clause?.head?.type === COMPOUND && clause.head.name === ':-' && clause.head.arity === 1
+      ? clause.head.args[0]
+      : null;
+    if (directive?.type !== COMPOUND || directive.name !== 'module' || directive.arity !== 2) continue;
+    if (directive.args[0]?.type !== ATOM) throw new Error(`${filename}: invalid module name`);
+    moduleName = directive.args[0].name;
+    exports = moduleExports(directive.args[1]);
+    break;
+  }
+  if (moduleName == null || exports == null) throw new Error(`${filename}: missing module/2 declaration`);
+  modules.push(moduleName);
+  for (const indicator of exports) {
+    const list = candidates.get(indicator.key) ?? [];
+    list.push({ library: moduleName, local: definitions.has(indicator.key) });
+    candidates.set(indicator.key, list);
+  }
+}
+
+const providers = {};
+const ambiguous = {};
+for (const [key, list] of [...candidates.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+  if (list.length === 1) {
+    providers[key] = list[0].library;
+    continue;
+  }
+  const local = list.filter((entry) => entry.local);
+  if (local.length === 1) {
+    providers[key] = local[0].library;
+    continue;
+  }
+  ambiguous[key] = list.map((entry) => entry.library).sort();
+}
+
+const renderObject = (value) => JSON.stringify(value, null, 2)
+  .replace(/^\{/m, 'Object.freeze({')
+  .replace(/\}$/m, '})');
+const text = `// Generated by tools/generate-library-autoload-index.mjs.\n` +
+  `// Do not edit by hand; module/2 export lists under src/lib/ are the source of truth.\n\n` +
+  `export const eyePrologLibraryAutoload = ${renderObject(providers)};\n\n` +
+  `export const eyePrologAmbiguousLibraryAutoload = ${renderObject(ambiguous)};\n\n` +
+  `export const eyePrologLibraryAutoloadModules = Object.freeze(${JSON.stringify(modules.sort(), null, 2)});\n`;
+if (process.argv.includes('--check')) {
+  const current = fs.existsSync(outputFile) ? fs.readFileSync(outputFile, 'utf8') : '';
+  if (current !== text) {
+    console.error(`${path.relative(root, outputFile)} is stale; run npm run generate:autoload`);
+    process.exit(1);
+  }
+  console.log(`${path.relative(root, outputFile)} is up to date`);
+} else {
+  fs.writeFileSync(outputFile, text);
+  console.log(`wrote ${path.relative(root, outputFile)} (${Object.keys(providers).length} predicates, ${Object.keys(ambiguous).length} ambiguous)`);
+}