eyeprolog 1.1.10 → 1.1.12

package/README.md

@@ -21,11 +21,22 @@ examples, proofs, conformance, and implementation.
 
 ## Quick start
 
-EyeProlog requires Node.js 18 or newer.
+EyeProlog requires Node.js 18 or newer. Check the active runtime before
+installing:
 
 ```sh
-npm install --global eyeprolog
-eyeprolog
+node --version
+```
+
+If it reports an older release, upgrade through a Node version manager or the
+[official Node.js download](https://nodejs.org/en/download) and check again.
+Distribution packages can provide an older Node.js even on a current operating
+system.
+
+Run EyeProlog without a global installation:
+
+```sh
+npx --yes eyeprolog
 ?- use_module(library(lists)).
    true.
 ?- member(X, [prolog, logic]).
@@ -34,11 +45,25 @@ eyeprolog
 ?- halt.
 ```
 
+For a persistent `eyeprolog` command without administrator access, install it
+under a user-owned prefix and put that prefix's `bin` directory on `PATH`:
+
+```sh
+npm install --global --prefix "$HOME/.local" eyeprolog
+export PATH="$HOME/.local/bin:$PATH"
+eyeprolog
+```
+
+Add the `PATH` export to your shell startup file to keep it across sessions.
+Do not use `sudo npm install`; npm's
+[EACCES guidance](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/)
+also recommends a Node version manager or a user-owned npm prefix.
+
 For a non-interactive run:
 
 ```sh
 printf 'human(socrates).\nmortal(X) :- human(X).\n' |
-  eyeprolog --proof --goal 'mortal(socrates)' -
+  npx --yes eyeprolog --proof --goal 'mortal(socrates)' -
 ```
 
 Programs may declare their default queries with `%% goal:` comments.
@@ -66,12 +91,14 @@ noun --> [world] | [prolog].
 %% goal: phrase(sentence, Words)
 ```
 
-EyeProlog also adds 46 public library predicates to its 129-entry ISO registry.
-**All 46 are ordinary Prolog clauses** in `src/lib/eyeprolog.pl`,
-`src/lib/lists.pl`, and `src/lib/prologue.pl`. They are ISO/IEC 13211-2 modules,
+EyeProlog also adds 57 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.
+They are ISO/IEC 13211-2 modules,
 loaded explicitly with `use_module(library(eyeprolog))`,
-`use_module(library(lists))`, or `use_module(library(prologue))`. None requires
-host support. Portable text predicates use ISO atoms or character lists.
+`use_module(library(lists))`, or `use_module(library(prologue))`. Portable text
+predicates use ISO atoms or character lists.
 
 ## Development
 

package/package.json

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

package/src/iso.js

@@ -164,6 +164,15 @@ 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.
+export const eyePrologLibraryBuiltins = {
+  register(registry) {
+    registry.add('eyeprolog__call_nth', 2, callNthBuiltin, { eyePrologLibrary: true });
+  },
+};
+
 function* unification({ goal, env }) {
   const next = env.clone();
   if (unify(goal.args[0], goal.args[1], next)) yield next;
@@ -1564,6 +1573,36 @@ function* callClosureBuiltin({ solver, goal, env }) {
   }
 }
 
+function* callNthBuiltin({ solver, goal, env }) {
+  const requestedTerm = deref(goal.args[1], env);
+  // Zero is the one Nth value that fails before Goal is inspected.
+  if (requestedTerm.type === NUMBER && isDecimalInteger(requestedTerm.name) && BigInt(requestedTerm.name) === 0n) return;
+
+  const invoked = callable(goal.args[0], env);
+  let requested = null;
+  if (requestedTerm.type !== VAR) {
+    if (requestedTerm.type !== NUMBER || !isDecimalInteger(requestedTerm.name)) {
+      throw new PrologError('type_error(integer)', requestedTerm);
+    }
+    requested = BigInt(requestedTerm.name);
+    if (requested < 0n) throw new PrologError('domain_error(not_less_than_zero)', requestedTerm);
+  }
+
+  const child = solver.cloneForInnerGoal();
+  let nth = 0n;
+  try {
+    for (const answerEnv of child.solve([invoked], env, 0)) {
+      nth++;
+      if (requested != null && nth < requested) continue;
+      const next = answerEnv.clone();
+      if (unify(goal.args[1], numberTerm(nth.toString()), next)) yield next;
+      if (requested != null) return;
+    }
+  } finally {
+    solver.absorbStatsFrom(child);
+  }
+}
+
 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

@@ -7,10 +7,36 @@
     between/3,
     select/3,
     succ/2,
-    maplist/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
 ]).
 
 :- meta_predicate(maplist(1, '?')).
+:- meta_predicate(maplist(2, '?', '?')).
+:- meta_predicate(maplist(3, '?', '?', '?')).
+:- meta_predicate(maplist(4, '?', '?', '?', '?')).
+:- meta_predicate(maplist(5, '?', '?', '?', '?', '?')).
+:- meta_predicate(maplist(6, '?', '?', '?', '?', '?', '?')).
+:- meta_predicate(maplist(7, '?', '?', '?', '?', '?', '?', '?')).
+:- meta_predicate(call_nth(0, '?')).
+:- meta_predicate(foldl(3, '?', '?', '?')).
+:- meta_predicate(foldl(4, '?', '?', '?', '?')).
+:- meta_predicate(foldl(5, '?', '?', '?', '?', '?')).
+:- meta_predicate(countall(0, '?')).
 
 member(X, [X|_]).
 member(X, [_|Xs]) :- member(X, Xs).
@@ -74,6 +100,84 @@ maplist(Closure, [X|Xs]) :-
     call(Closure, X),
     maplist(Closure, Xs).
 
+maplist(_, [], []).
+maplist(Closure, [A|As], [B|Bs]) :-
+    call(Closure, A, B),
+    maplist(Closure, As, Bs).
+
+maplist(_, [], [], []).
+maplist(Closure, [A|As], [B|Bs], [C|Cs]) :-
+    call(Closure, A, B, C),
+    maplist(Closure, As, Bs, Cs).
+
+maplist(_, [], [], [], []).
+maplist(Closure, [A|As], [B|Bs], [C|Cs], [D|Ds]) :-
+    call(Closure, A, B, C, D),
+    maplist(Closure, As, Bs, Cs, Ds).
+
+maplist(_, [], [], [], [], []).
+maplist(Closure, [A|As], [B|Bs], [C|Cs], [D|Ds], [E|Es]) :-
+    call(Closure, A, B, C, D, E),
+    maplist(Closure, As, Bs, Cs, Ds, Es).
+
+maplist(_, [], [], [], [], [], []).
+maplist(Closure, [A|As], [B|Bs], [C|Cs], [D|Ds], [E|Es], [F|Fs]) :-
+    call(Closure, A, B, C, D, E, F),
+    maplist(Closure, As, Bs, Cs, Ds, Es, Fs).
+
+maplist(_, [], [], [], [], [], [], []).
+maplist(Closure, [A|As], [B|Bs], [C|Cs], [D|Ds], [E|Es], [F|Fs], [G|Gs]) :-
+    call(Closure, A, B, C, D, E, F, G),
+    maplist(Closure, As, Bs, Cs, Ds, Es, Fs, Gs).
+
+nth0(N, List, Elem) :- nth0(N, List, Elem, _).
+
+nth0(N, List, Elem, Rest) :-
+    prologue__integer_or_variable(N),
+    ( var(N) -> prologue__nth0(N, List, Elem, Rest)
+    ; prologue__not_less_than_zero(N),
+      prologue__nth0(N, List, Elem, Rest)
+    ).
+
+prologue__nth0(0, [Elem|Rest], Elem, Rest).
+prologue__nth0(N, [X|Xs], Elem, [X|Rest]) :-
+    var(N),
+    prologue__nth0(N0, Xs, Elem, Rest),
+    N is N0 + 1.
+prologue__nth0(N, [X|Xs], Elem, [X|Rest]) :-
+    nonvar(N),
+    N > 0,
+    N0 is N - 1,
+    prologue__nth0(N0, Xs, Elem, Rest).
+
+nth1(N, List, Elem) :- nth1(N, List, Elem, _).
+
+nth1(N, List, Elem, Rest) :-
+    N \== 0,
+    nth0(N, [_|List], Elem, [_|Rest]),
+    N \== 0.
+
+call_nth(Goal, Nth) :- eyeprolog__call_nth(Goal, Nth).
+
+foldl(_, [], Acc, Acc).
+foldl(Closure, [A|As], Acc0, Acc) :-
+    call(Closure, A, Acc0, Acc1),
+    foldl(Closure, As, Acc1, Acc).
+
+foldl(_, [], [], Acc, Acc).
+foldl(Closure, [A|As], [B|Bs], Acc0, Acc) :-
+    call(Closure, A, B, Acc0, Acc1),
+    foldl(Closure, As, Bs, Acc1, Acc).
+
+foldl(_, [], [], [], Acc, Acc).
+foldl(Closure, [A|As], [B|Bs], [C|Cs], Acc0, Acc) :-
+    call(Closure, A, B, C, Acc0, Acc1),
+    foldl(Closure, As, Bs, Cs, Acc1, Acc).
+
+countall(Goal, Count) :-
+    findall(1, Goal, Ones),
+    length(Ones, Count).
+
 prologue__integer_or_variable(X) :- var(X), !.
 prologue__integer_or_variable(X) :- prologue__integer(X).
 

package/src/standard-library.js

@@ -2,7 +2,7 @@
 // The sources are registered here so library(Name) works in Node and browsers;
 // unlike the former autoloader, no clauses are added unless use_module/1 or
 // use_module/2 requests their module.
-import { createDefaultRegistry } from './iso.js';
+import { createDefaultRegistry, eyePrologLibraryBuiltins } from './iso.js';
 import { fs, isNode } from './platform.js';
 
 const moduleFiles = Object.freeze({
@@ -35,21 +35,27 @@ function libraryUrl(filename) {
   return url;
 }
 
-export const eyePrologNativeLibraryIndicators = Object.freeze([]);
+export const eyePrologNativeLibraryIndicators = Object.freeze(['call_nth/2']);
 export const eyePrologPortableLibraryIndicators = Object.freeze([
-  'uuid/3', 'difference/3', 'maplist/2', 'maplist/3', 'lt/2', 'gt/2', 'le/2', 'ge/2',
+  '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',
   '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', 'append/3', 'string_concat/3', 'contains/2',
   'matches/2', 'join/3', 'substring/4', 'member/2', 'select/3', 'last/2',
-  'nth0/3', 'nth1/3', 'set_nth0/4', 'take/3', 'drop/3', 'slice/4', 'reverse/2',
+  'nth0/3', 'nth0/4', 'nth1/3', 'nth1/4', 'set_nth0/4', 'take/3', 'drop/3', 'slice/4', 'reverse/2',
   'length/2', 'sum_list/2', 'min_list/2', 'max_list/2', 'list_to_set/2',
-  'countall/2', 'succ/2', 'sumall/3', 'aggregate_min/5', 'aggregate_max/5',
+  'countall/2', 'succ/2', 'foldl/4', 'foldl/5', 'foldl/6',
+  'sumall/3', 'aggregate_min/5', 'aggregate_max/5',
+]);
+export const eyePrologLibraryIndicators = Object.freeze([
+  ...eyePrologPortableLibraryIndicators,
+  ...eyePrologNativeLibraryIndicators,
 ]);
-export const eyePrologLibraryIndicators = Object.freeze([...eyePrologPortableLibraryIndicators]);
 
 export function createEyePrologRegistry() {
   const registry = createDefaultRegistry();
+  eyePrologLibraryBuiltins.register(registry);
   registry.eyePrologLibrary = true;
   return registry;
 }

package/test/fixtures/prologue_call_nth_quad.pl

@@ -0,0 +1,32 @@
+?- call_nth(true, Nth).
+   Nth = 1.
+?- call_nth(false, Nth).
+   false.
+?- call_nth(repeat, Nth).
+   Nth = 1
+;  Nth = 2
+;  Nth = 3
+;  Nth = 4
+;  Nth = 5
+;  ... .
+?- call_nth(( N = 1 ; N = 2 ), Nth).
+   N = 1, Nth = 1
+;  N = 2, Nth = 2.
+?- call_nth(true, non_integer).
+   type_error(integer,non_integer).
+?- call_nth(true, 1.0).
+   type_error(integer,1.0).
+?- call_nth(true, 0).
+   false.
+?- call_nth(repeat, 0).
+   false.
+?- call_nth(repeat, -1).
+   domain_error(not_less_than_zero,-1).
+?- call_nth(length(L,N), 3).
+   L = [_A,_B], N = 2.
+?- call_nth(inex, 0).
+   false.
+?- call_nth(1, 0).
+   false.
+?- call_nth(V, 0).
+   false.

package/test/fixtures/prologue_call_nth_quad_runner.pl

@@ -0,0 +1,2 @@
+:- use_module(library(prologue)).
+:- include('prologue_call_nth_quad.pl').

package/test/fixtures/prologue_extended_quad.pl

@@ -0,0 +1,87 @@
+% Finite examples and arity coverage for Prologue p.p.7 through p.p.11.
+
+?- maplist(same2, [a], [a]).
+   true.
+?- maplist(same3, [a], [a], [a]).
+   true.
+?- maplist(same4, [a], [a], [a], [a]).
+   true.
+?- maplist(same5, [a], [a], [a], [a], [a]).
+   true.
+?- maplist(same6, [a], [a], [a], [a], [a], [a]).
+   true.
+?- maplist(same7, [a], [a], [a], [a], [a], [a], [a]).
+   true.
+
+?- nth0(1, [a,b,c], E).
+   E = b.
+?- nth0(N, [a,b,c], E).
+   N = 0, E = a
+;  N = 1, E = b
+;  N = 2, E = c.
+?- nth0(0, [A,B|non_list], E).
+   A = E.
+?- nth0(2, Es, E).
+   Es = [_A,_B,E|_C].
+?- nth0(N, Es, E).
+   N = 0, Es = [E|_A]
+;  N = 1, Es = [_A,E|_B]
+;  N = 2, Es = [_A,_B,E|_C]
+;  N = 3, Es = [_A,_B,_C,E|_D]
+;  ... .
+?- nth0(non_integer, Es, E).
+   type_error(integer, non_integer).
+?- nth0(-1, Es, E).
+   domain_error(not_less_than_zero, -1).
+?- nth0(N, [[]|Es], Es).
+   N = 0, Es = []
+;  sto, loops.
+?- nth0(1, [a,b,c], E, Es).
+   E = b, Es = [a,c].
+?- nth1(0, Es, E).
+   false.
+?- nth1(2, [a,b,c], E, Es).
+   E = b, Es = [a,c].
+
+?- call_nth(N = 1, N).
+   N = 1.
+?- call_nth(N = -1, N).
+   false.
+?- call_nth(repeat, 1+1).
+   type_error(integer, 1+1).
+?- call_nth(inex, 0).
+   existence_error(procedure, _), unexpected.
+?- call_nth(G, non_integer).
+   instantiation_error.
+?- call_nth(1, -1).
+   type_error(callable, 1).
+
+?- foldl(append, [[1,2],[3],[4,5]], [], Xs).
+   Xs = [4,5,3,1,2].
+?- foldl(add2, [1,2], [10,20], 0, S).
+   S = 33.
+?- foldl(add3, [1,2], [10,20], [100,200], 0, S).
+   S = 333.
+
+?- countall((X=1;X=2), N).
+   N = 2.
+?- countall((true;true), N).
+   N = 2.
+?- countall(G, N).
+   instantiation_error.
+?- countall((length(L,5),nth0(_,L,_),nth0(_,L,_)), N).
+   N = 25.
+?- countall(N=1, N).
+   N = 1.
+?- countall(N=non_integer, N).
+   N = 1.
+?- countall(false, 1).
+   false.
+?- countall(false, -1).
+   domain_error(not_less_than_zero, -1).
+?- countall(false, non_integer).
+   type_error(integer, non_integer).
+?- countall(G, -1).
+   instantiation_error.
+?- countall(1, -1).
+   type_error(callable, 1).

package/test/fixtures/prologue_extended_quad_runner.pl

@@ -0,0 +1,13 @@
+:- use_module(library(prologue)).
+
+same2(X, X).
+same3(X, X, X).
+same4(X, X, X, X).
+same5(X, X, X, X, X).
+same6(X, X, X, X, X, X).
+same7(X, X, X, X, X, X, X).
+
+add2(X, Y, S0, S) :- S is S0 + X + Y.
+add3(X, Y, Z, S0, S) :- S is S0 + X + Y + Z.
+
+:- include('prologue_extended_quad.pl').

package/test/run-regression.mjs

@@ -50,7 +50,7 @@ const bin = path.join(packageRoot, 'bin', 'eyeprolog.js');
 const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
 let tmp = null;
 let tmpCounter = 0;
-const libraryCall = /\b(?:uuid|difference|maplist|lt|gt|le|ge|between|smallest_divisor_from|random|matches|split|replace|lowercase|uppercase|trim|number_string|atom_string|term_string|append|string_concat|contains|join|substring|member|select|last|nth0|nth1|set_nth0|take|drop|slice|reverse|length|sum_list|min_list|max_list|list_to_set|countall|sumall|aggregate_min|aggregate_max)\s*\(/;
+const libraryCall = /\b(?:uuid|difference|maplist|foldl|call_nth|lt|gt|le|ge|between|smallest_divisor_from|random|matches|split|replace|lowercase|uppercase|trim|number_string|atom_string|term_string|append|string_concat|contains|join|substring|member|select|last|nth0|nth1|set_nth0|take|drop|slice|reverse|length|sum_list|min_list|max_list|list_to_set|countall|sumall|aggregate_min|aggregate_max)\s*\(/;
 
 function withStandardModules(source) {
   if (!libraryCall.test(source) || source.includes('use_module(library(') || source.includes(':- module(')) return source;
@@ -337,6 +337,36 @@ c4 ?- call((!;1)).
         assertEqual(result.stdout, 'quads: 33 run, 33 passed, 0 failed.\n', 'quad report');
       },
     },
+    {
+      name: 'runQuads passes the authoritative Prologue call_nth quad corpus',
+      run: () => {
+        const filename = path.join(testRoot, 'fixtures', 'prologue_call_nth_quad_runner.pl');
+        const source = fs.readFileSync(filename, 'utf8');
+        const result = publicApi.runQuads(Program.parseSources([{
+          text: source,
+          filename,
+          baseDir: path.dirname(filename),
+        }]));
+        assertEqual(result.total, 13, 'quad total');
+        assertEqual(result.passed, 13, 'quad passed');
+        assertEqual(result.stdout, 'quads: 13 run, 13 passed, 0 failed.\n', 'quad report');
+      },
+    },
+    {
+      name: 'runQuads covers the remaining finite Prologue examples and arities',
+      run: () => {
+        const filename = path.join(testRoot, 'fixtures', 'prologue_extended_quad_runner.pl');
+        const source = fs.readFileSync(filename, 'utf8');
+        const result = publicApi.runQuads(Program.parseSources([{
+          text: source,
+          filename,
+          baseDir: path.dirname(filename),
+        }]));
+        assertEqual(result.total, 37, 'quad total');
+        assertEqual(result.passed, 37, 'quad passed');
+        assertEqual(result.stdout, 'quads: 37 run, 37 passed, 0 failed.\n', 'quad report');
+      },
+    },
     {
       name: 'runQuads rejects malformed answer substitutions',
       run: () => {
@@ -516,6 +546,27 @@ c4 ?- call((!;1)).
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'npm can install the CLI under a user-owned prefix',
+      run: () => {
+        const prefix = path.join(tmp, `npm-prefix-${++tmpCounter}`);
+        const installed = spawnSync('npm', [
+          'install', '--global', '--prefix', prefix, '--loglevel=silent', '--no-audit', '--no-fund', '.',
+        ], {
+          cwd: packageRoot,
+          encoding: 'utf8',
+          env: { ...process.env, npm_config_update_notifier: 'false' },
+        });
+        assertEqual(installed.status, 0, 'install exit status');
+        const executable = process.platform === 'win32'
+          ? path.join(prefix, 'eyeprolog.cmd')
+          : path.join(prefix, 'bin', 'eyeprolog');
+        const result = spawnSync(executable, ['--version'], { encoding: 'utf8' });
+        assertEqual(result.status, 0, 'installed CLI exit status');
+        assertEqual(result.stdout, `eyeprolog ${pkg.version}\n`, 'installed CLI stdout');
+        assertEqual(result.stderr, '', 'installed CLI stderr');
+      },
+    },
     {
       name: 'stdin input is accepted',
       run: () => {
@@ -979,6 +1030,22 @@ function documentationSyncCases() {
         assertArrayEqual(misleadingDependencyInstallDocs(), [], 'misleading dependency install docs');
       },
     },
+    {
+      name: 'installation docs avoid unsupported Node and global npm permission traps',
+      run: () => {
+        assertEqual(pkg.engines?.node, '>=18', 'supported Node range');
+        for (const filename of ['README.md', 'the-art-of-eyeprolog.md']) {
+          const text = fs.readFileSync(path.join(packageRoot, filename), 'utf8');
+          assertIncludes(text, 'node --version', `${filename} checks Node version`);
+          assertIncludes(text, 'npx --yes eyeprolog', `${filename} offers a non-global launch`);
+          assertIncludes(text, 'npm install --global --prefix "$HOME/.local" eyeprolog', `${filename} uses a user prefix`);
+          assertIncludes(text, 'https://nodejs.org/en/download', `${filename} links Node upgrades`);
+          assertIncludes(text, 'https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/', `${filename} links npm EACCES guidance`);
+          assertEqual(text.includes('sudo npm install'), true, `${filename} explicitly warns against sudo npm`);
+          assertEqual(/^\s*sudo npm install/m.test(text), false, `${filename} never recommends sudo npm`);
+        }
+      },
+    },
   ];
 }
 
@@ -1311,14 +1378,17 @@ 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, 129, 'EyeProlog registry contains only ISO host definitions');
+        assertEqual(library.defs.size, 130, 'EyeProlog registry contains ISO definitions and one private library adapter');
         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, 0, 'public native EyeProlog builtin count');
-        assertEqual(eyePrologPortableLibraryIndicators.length, 46, 'portable Prolog library count');
-        assertEqual(eyePrologNativeLibraryIndicators.length, 0, 'native host library count');
-        assertEqual(eyePrologNativeLibraryIndicators.join(','), '', 'no EyeProlog library predicate requires host support');
-        assertEqual(eyePrologLibraryIndicators.length, 46, 'complete EyeProlog library surface');
+        assertEqual(registeredNativeEyePrologLibraryNames().length, 1, '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(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(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

@@ -79,6 +79,30 @@ Then ask for the derivations:
 node bin/eyeprolog.js --proof examples/socrates.pl
 ```
 
+To use the published package, first verify that `node --version` reports Node.js
+18 or newer. Upgrade an older runtime through a Node version manager or the
+[official Node.js download](https://nodejs.org/en/download). A current Linux
+distribution can still expose an older Node.js package.
+
+The package can be launched without a global installation:
+
+```sh
+npx --yes eyeprolog
+```
+
+For a persistent command without administrator access, install into a
+user-owned prefix:
+
+```sh
+npm install --global --prefix "$HOME/.local" eyeprolog
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+Persist the `PATH` export in the appropriate shell startup file. Do not use
+`sudo npm install`; npm's
+[EACCES guidance](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/)
+recommends a Node version manager or a user-owned npm prefix.
+
 Readers who do not want to install anything can begin in the
 [browser playground](https://eyereasoner.github.io/eyeprolog/playground). Paste
 the source of `examples/socrates.pl` into the editor and run it. The playground
@@ -5737,22 +5761,25 @@ so side effects occur in Prolog execution order.
 
 ### The EyeProlog library
 
-EyeProlog exposes **46 library predicate indicators** in addition to the 129
-indicators in its isolated ISO profile. **All 46 are ordinary Prolog clauses**
-across `src/lib/eyeprolog.pl`, `src/lib/lists.pl`, and `src/lib/prologue.pl`; none
-is a native host predicate. The resulting
-normal EyeProlog language surface is therefore **175 public predicate
-indicators**. Internally, the runtime registry contains only the 129 ISO
-definitions; the EyeProlog relations are module source clauses.
+EyeProlog exposes **57 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;
+the remaining EyeProlog relations are module source clauses.
 
 The three Prolog files declare `eyeprolog`, `lists`, and `prologue` with
 `module/2`. A program loads them explicitly with
 `use_module(library(eyeprolog))`, `use_module(library(lists))`, or
 `use_module(library(prologue))`; `use_module/2` can select a smaller import
-list. The last module implements the predicates exercised by the working-draft
-Prologue quad corpus.
-`src/standard-library.js` only registers the module sources for Node and browser
-resolution and never adds clauses implicitly.
+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
+control adapter for Node and browser resolution, and never adds clauses
+implicitly.
 The isolated ISO-only registry remains
 available through `createDefaultRegistry()` and `getDefaultRegistry()` for
 conformance work and advanced embedders. Module-local predicate identity keeps
@@ -5764,7 +5791,7 @@ private helpers and same-named predicates in different modules separate.
 | --- | --- |
 | `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` |
+| `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` |
 
 <!-- eyeprolog-library-catalog:end -->
 
@@ -5891,7 +5918,7 @@ eyeprolog --goal 'answer(Kind, Value)' program.pl
 The portable text API uses **ISO atoms or proper lists of one-character atoms**.
 A generated text result defaults to an atom. Double-quoted source text uses the
 ISO representation selected by `double_quotes`; with the default `chars`, it is
-already a proper character list accepted by this API. The 46-predicate portable
+already a proper character list accepted by this API. The 56-predicate portable
 library itself has no STRING or JavaScript dependency.
 
 | Predicate and principal mode | Behavior |