eyeprolog 0.5.11 → 0.5.12

package/README.md

@@ -32,9 +32,9 @@ Programs may declare their default queries with `%% goal:` comments.
 ## Portable library
 
 EyeProlog adds 50 public library predicates to its 115-predicate ISO profile.
-**48 of the 50 are ordinary Prolog clauses** in `src/eyeprolog-library.pl` and
-are autoloaded in Node and the browser. Only `uuid/1` and `local_time/1` require
-host support. Portable text predicates use ISO atoms or character lists; the
+**All 50 are ordinary Prolog clauses** in `src/eyeprolog-library.pl` and are
+autoloaded in Node and the browser. None requires host support. Portable text
+predicates use ISO atoms or character lists; the
 RDF tools emit lexical values as ISO atoms as well.
 
 ## RDF 1.2

package/examples/age.pl

@@ -1,8 +1,7 @@
 % Age checker adapted from Eyeling.
-% The example combines date literals, ISO-8601 duration values, local_time/1,
-% difference/3, and duration comparison.  It deliberately uses the current
-% local date so the derived ageAbove/2 fact remains an executable temporal
-% check rather than a precomputed constant.
+% The example combines date literals, ISO-8601 duration values, an explicit
+% local_time/1 fact, difference/3, and duration comparison. Declaring the date
+% as scenario data keeps the result reproducible across hosts and runs.
 
 %% goal: birthDay(X0, X1)
 
@@ -15,9 +14,10 @@
 
 birthDay(patH, '1944-08-21').
 duration(check, 'P80Y').
+local_time('2026-05-30').
 
-% A person is above a duration if the local date minus the birthday is greater
-% than that duration.
+% A person is above a duration if the declared local date minus the birthday
+% is greater than that duration.
 ageAbove(S, A) :-
   birthDay(S, B),
   duration(check, A),

package/examples/proof/age.pl

@@ -3,7 +3,7 @@ why(
   ageAbove(patH, 'P80Y'),
   proof(
     goal(ageAbove(patH, 'P80Y')),
-    by(rule("age.pl", clause(3))),
+    by(rule("age.pl", clause(4))),
     bindings([binding("S", patH), binding("A", 'P80Y'), binding("B", '1944-08-21'), binding("D", '2026-05-30'), binding("F", 'P81Y9M9D')]),
     uses([
       proof(
@@ -16,7 +16,7 @@ why(
       ),
       proof(
         goal(local_time('2026-05-30')),
-        by(builtin(local_time, 1))
+        by(fact("age.pl", clause(3)))
       ),
       proof(
         goal(difference('2026-05-30', '1944-08-21', 'P81Y9M9D')),
@@ -35,12 +35,12 @@ why(
   holds_result(test, true),
   proof(
     goal(holds_result(test, true)),
-    by(rule("age.pl", clause(4))),
+    by(rule("age.pl", clause(5))),
     bindings([binding("S", patH)]),
     uses([
       proof(
         goal(ageAbove(patH, 'P80Y')),
-        by(rule("age.pl", clause(3))),
+        by(rule("age.pl", clause(4))),
         bindings([binding("S", patH), binding("A", 'P80Y'), binding("B", '1944-08-21'), binding("D", '2026-05-30'), binding("F", 'P81Y9M9D')]),
         uses([
           proof(
@@ -53,7 +53,7 @@ why(
           ),
           proof(
             goal(local_time('2026-05-30')),
-            by(builtin(local_time, 1))
+            by(fact("age.pl", clause(3)))
           ),
           proof(
             goal(difference('2026-05-30', '1944-08-21', 'P81Y9M9D')),

package/examples/proof/iso-dynamic-database.pl

@@ -12,7 +12,7 @@ why(
         uses([
           proof(
             goal(task(check_power, urgent)),
-            by(fact("<input>", clause(275)))
+            by(fact("<input>", clause(299)))
           )
         ])
       )

package/examples/uuid.pl

@@ -1,12 +1,12 @@
-% uuid/1 creates exactly one fresh version 4 UUID atom.
+% uuid/3 creates a version 4 UUID atom from explicit random state.
 %
-% The UUID itself varies between runs, so this example checks its type and
-% canonical shape while returning a stable, reviewable answer.
+% The same initial seed reproduces the same UUID across runs. Threading the
+% returned seed into another call produces the next UUID in the sequence.
 
 %% goal: uuid_example(Result)
 
 uuid_example(true) :-
-  uuid(UUID),
+  uuid(20260807, UUID, _),
   atom(UUID),
   atom_length(UUID, 36),
   sub_atom(UUID, 8, 1, 27, '-'),

package/package.json

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

package/playground.html

@@ -681,7 +681,6 @@
             "le",
             "length",
             "list_to_set",
-            "local_time",
             "log",
             "lowercase",
             "lt",
@@ -699,6 +698,7 @@
             "number_string",
             "once",
             "pow",
+            "random",
             "replace",
             "reverse",
             "rounded",

package/src/cli.js

@@ -115,7 +115,7 @@ async function loadEngine() {
       import('./program.js'),
       import('./solver.js'),
       import('./iso.js'),
-      import('./library.js'),
+      import('./eyeprolog-library.js'),
     ]);
     engineModule = { ...term, ...parser, ...program, ...solver, ...iso, ...library };
   }

package/src/explain.js

@@ -4,7 +4,7 @@
 // human-readable and machine-readable.
 import { ATOM, COMPOUND, Env, Term, VAR, deref, flattenConjunction, freshTerm, termToString, unify, variantTerms } from './term.js';
 import { selectClauseCandidates } from './program.js';
-import { getEyePrologRegistry } from './library.js';
+import { getEyePrologRegistry } from './eyeprolog-library.js';
 import { Solver, nextFreshId } from './solver.js';
 
 export function whyProof(program, goal, options = {}) {

package/src/eyeprolog-library.js

@@ -0,0 +1,118 @@
+// Load and autoload the pure-Prolog EyeProlog library in Node and the browser.
+import { createDefaultRegistry } from './iso.js';
+import { parseClauses } from './parser.js';
+import { fs, isNode } from './platform.js';
+
+export const eyePrologNativeLibraryIndicators = Object.freeze([]);
+
+export const eyePrologPortableLibraryIndicators = Object.freeze([
+  'uuid/3',
+  'difference/3',
+  'call/3',
+  'maplist/3',
+  'tan/2',
+  'asin/2',
+  'acos/2',
+  'atan2/3',
+  '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',
+  'length/2',
+  'sum_list/2',
+  'min_list/2',
+  'max_list/2',
+  'list_to_set/2',
+  'sort/2',
+  'countall/2',
+  'sumall/3',
+  'aggregate_min/5',
+  'aggregate_max/5',
+]);
+
+export const eyePrologLibraryIndicators = Object.freeze([
+  ...eyePrologNativeLibraryIndicators,
+  ...eyePrologPortableLibraryIndicators,
+]);
+
+const autoloadedPrograms = new WeakSet();
+const libraryUrl = new URL('./eyeprolog-library.pl', import.meta.url);
+const librarySource = await loadLibrarySource(libraryUrl);
+const portableClauseTemplates = parseClauses(librarySource, {
+  filename: 'src/eyeprolog-library.pl',
+  sourceMetadata: true,
+});
+
+async function loadLibrarySource(url) {
+  if (isNode) return fs.readFileSync(url, 'utf8');
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`could not load EyeProlog library: ${response.status}`);
+  return response.text();
+}
+
+export function ensureEyePrologLibrary(program) {
+  if (autoloadedPrograms.has(program)) return program;
+
+  // User clauses already present in the Program stay first in clause order;
+  // the autoloaded library clauses are appended as defaults. This preserves
+  // useful source specializations such as length(numbers,N) while still making
+  // the relational length(List,N) library clauses available inside them.
+  let added = 0;
+  for (const template of portableClauseTemplates) {
+    // Clause terms are immutable; clone only the mutable indexing shell so the
+    // cached parse can be safely shared across independent Program instances.
+    const clause = {
+      ...template,
+      body: template.body.slice(),
+      index: program.clauses.length,
+      eyePrologLibraryPortable: true,
+    };
+    program.clauses.push(clause);
+    program.indexClause(clause);
+    added++;
+  }
+  if (added > 0) program.markRecursivePredicates();
+  autoloadedPrograms.add(program);
+  return program;
+}
+
+export function createEyePrologRegistry() {
+  const registry = createDefaultRegistry();
+  registry.eyePrologLibrary = true;
+  return registry;
+}
+
+let eyePrologRegistry = null;
+
+export function getEyePrologRegistry() {
+  if (eyePrologRegistry == null) eyePrologRegistry = createEyePrologRegistry();
+  return eyePrologRegistry;
+}

package/src/eyeprolog-library.pl

@@ -3,8 +3,8 @@
 % This file is autoloaded for the EyeProlog runtime and is intentionally
 % written against the project's ISO compatibility profile.  Text-facing
 % predicates accept ISO atoms or proper lists of one-character atoms; newly
-% produced text defaults to atoms.  Only uuid/1 and local_time/1 remain native
-% host built-ins because ISO Prolog has no entropy or wall-clock primitive.
+% produced text defaults to atoms. Every public predicate in this file uses
+% only the project's ISO Prolog profile; none requires host support.
 
 % ---------- text representation helpers ----------
 
@@ -140,6 +140,72 @@ eyeprolog__between(Low, High, Value) :-
     !,
     eyeprolog__between(Next, High, Value).
 
+% A Park-Miller generator with explicit state. Threading Seed into the next
+% call makes a sequence reproducible without mutable runtime state. Schrage's
+% method keeps every intermediate integer within the exact 32-bit range.
+random(Seed0, Value, Seed) :-
+    integer(Seed0),
+    eyeprolog__random_normalize_seed(Seed0, Normalized),
+    High is Normalized // 44488,
+    Low is Normalized mod 44488,
+    Candidate is 48271 * Low - 3399 * High,
+    eyeprolog__random_wrap(Candidate, Seed),
+    Value is (Seed - 1) / 2147483646.
+
+eyeprolog__random_normalize_seed(Seed, 1) :-
+    0 is Seed mod 2147483647,
+    !.
+eyeprolog__random_normalize_seed(Seed, Normalized) :-
+    Normalized is Seed mod 2147483647.
+
+eyeprolog__random_wrap(Candidate, Candidate) :- Candidate > 0, !.
+eyeprolog__random_wrap(Candidate, Seed) :- Seed is Candidate + 2147483647.
+
+% Seed-threaded UUID version 4 generation. The version and variant nibbles are
+% fixed by RFC 9562; all other nibbles come from random/3. Reusing Seed0
+% reproduces the same UUID, while threading Seed produces a deterministic
+% sequence of different UUIDs.
+uuid(Seed0, UUID, Seed) :-
+    eyeprolog__uuid_hex(8, Seed0, Group1, Seed1),
+    eyeprolog__uuid_hex(4, Seed1, Group2, Seed2),
+    eyeprolog__uuid_hex(3, Seed2, Group3, Seed3),
+    random(Seed3, _, Seed4),
+    VariantValue is 8 + Seed4 mod 4,
+    eyeprolog__hex_digit(VariantValue, Variant),
+    eyeprolog__uuid_hex(3, Seed4, Group4, Seed5),
+    eyeprolog__uuid_hex(12, Seed5, Group5, Seed),
+    append(Group1, ['-'|Tail1], Chars),
+    append(Group2, ['-','4'|Tail2], Tail1),
+    append(Group3, ['-',Variant|Tail3], Tail2),
+    append(Group4, ['-'|Group5], Tail3),
+    atom_chars(UUID, Chars).
+
+eyeprolog__uuid_hex(0, Seed, [], Seed).
+eyeprolog__uuid_hex(Count, Seed0, [Digit|Digits], Seed) :-
+    Count > 0,
+    random(Seed0, _, Seed1),
+    Value is Seed1 mod 16,
+    eyeprolog__hex_digit(Value, Digit),
+    NextCount is Count - 1,
+    eyeprolog__uuid_hex(NextCount, Seed1, Digits, Seed).
+
+eyeprolog__hex_digit(0, '0').
+eyeprolog__hex_digit(1, '1').
+eyeprolog__hex_digit(2, '2').
+eyeprolog__hex_digit(3, '3').
+eyeprolog__hex_digit(4, '4').
+eyeprolog__hex_digit(5, '5').
+eyeprolog__hex_digit(6, '6').
+eyeprolog__hex_digit(7, '7').
+eyeprolog__hex_digit(8, '8').
+eyeprolog__hex_digit(9, '9').
+eyeprolog__hex_digit(10, a).
+eyeprolog__hex_digit(11, b).
+eyeprolog__hex_digit(12, c).
+eyeprolog__hex_digit(13, d).
+eyeprolog__hex_digit(14, e).
+eyeprolog__hex_digit(15, f).
+
 smallest_divisor_from(N, Start, Divisor) :-
     N >= 0,
     Start > 0,

package/src/index.js

@@ -18,7 +18,7 @@ export {
   eyePrologLibraryIndicators,
   eyePrologNativeLibraryIndicators,
   eyePrologPortableLibraryIndicators,
-} from './library.js';
+} from './eyeprolog-library.js';
 export { StreamManager } from './io.js';
 
 import { ATOM, COMPOUND, VAR, Env, copyResolved, termIsGround, termToString } from './term.js';
@@ -26,7 +26,7 @@ import { Program } from './program.js';
 import { Solver } from './solver.js';
 import { whyNoProof, whyProof } from './explain.js';
 import { HaltSignal, PrologError } from './iso.js';
-import { getEyePrologRegistry } from './library.js';
+import { getEyePrologRegistry } from './eyeprolog-library.js';
 import { parseGoalText } from './parser.js';
 
 export function run(source, options = {}) {

package/src/playground-worker.js

@@ -2,7 +2,7 @@
 // Keep this module free of Node-only imports: it is fetched directly by the
 // browser and is also exercised by test/run-playground.mjs.
 import { run } from './index.js?playground=20260803c';
-import { createEyePrologRegistry } from './library.js?playground=20260803c';
+import { createEyePrologRegistry } from './eyeprolog-library.js?playground=20260803c';
 
 const registry = createEyePrologRegistry();
 

package/src/solver.js

@@ -5,7 +5,7 @@ import {
   numberTerm, numberTextFromDouble, termIsGround, termToString, unify, variantTerms,
 } from './term.js';
 import { PrologError } from './iso.js';
-import { ensureEyePrologLibrary, getEyePrologRegistry } from './library.js';
+import { ensureEyePrologLibrary, getEyePrologRegistry } from './eyeprolog-library.js';
 import { selectClauseCandidates, selectClauseCandidatesForValues, selectGroundClauseCandidates } from './program.js';
 import { StreamManager } from './io.js';
 

package/test/conformance/cases/builtins/extra_uuid_v4.pl

@@ -1,6 +1,6 @@
-% uuid/1 is deterministic and creates a canonical version 4 UUID atom.
+% uuid/3 deterministically creates a canonical version 4 UUID atom from a seed.
 answer(uuid_v4, true) :-
-  uuid(UUID),
+  uuid(1, UUID, _),
   atom(UUID),
   atom_length(UUID, 36),
   sub_atom(UUID, 8, 1, 27, '-'),

package/test/run-examples.mjs

@@ -14,7 +14,6 @@ const packageRoot = path.resolve(root, '..');
 const examplesDir = path.join(packageRoot, 'examples');
 const expectedDir = path.join(examplesDir, 'output');
 const expectedProofDir = path.join(examplesDir, 'proof');
-const fixedExampleDate = '2026-05-30';
 
 export const proofExamples = [
   'access-control-policy.pl',
@@ -124,25 +123,18 @@ function runProofExample(name) {
 }
 
 function runProgramExample(programFile, filename, options) {
-  const oldLocalTime = process.env.EYEPROLOG_LOCAL_TIME;
-  process.env.EYEPROLOG_LOCAL_TIME = fixedExampleDate;
+  const text = fs.readFileSync(programFile, 'utf8');
+  const expectedExit = text.match(/^%\s*expect-exit:\s*(\d+)\s*$/m);
+  const program = Program.parseSources([{ text, filename }], {
+    sourceMetadata: options.proof,
+  });
   try {
-    const text = fs.readFileSync(programFile, 'utf8');
-    const expectedExit = text.match(/^%\s*expect-exit:\s*(\d+)\s*$/m);
-    const program = Program.parseSources([{ text, filename }], {
-      sourceMetadata: options.proof,
-    });
-    try {
-      const result = run(program, { ...options, goals: goalsInProgramOrder(program, text) });
-      if (expectedExit) throw new Error(`${filename} expected exit ${expectedExit[1]}, but reasoning succeeded`);
-      return result.stdout;
-    } catch (error) {
-      if (expectedExit && error?.code === Number(expectedExit[1])) return error.stdout ?? '';
-      throw error;
-    }
-  } finally {
-    if (oldLocalTime == null) delete process.env.EYEPROLOG_LOCAL_TIME;
-    else process.env.EYEPROLOG_LOCAL_TIME = oldLocalTime;
+    const result = run(program, { ...options, goals: goalsInProgramOrder(program, text) });
+    if (expectedExit) throw new Error(`${filename} expected exit ${expectedExit[1]}, but reasoning succeeded`);
+    return result.stdout;
+  } catch (error) {
+    if (expectedExit && error?.code === Number(expectedExit[1])) return error.stdout ?? '';
+    throw error;
   }
 }
 

package/test/run-playground.mjs

@@ -94,7 +94,7 @@ export async function runPlayground(reporter = new TestReporter()) {
     await withStaticServer(async (baseUrl) => {
       const modules = await crawlModuleGraph(new URL('src/playground-worker.js?playground=test', baseUrl));
       assert(modules.size >= 10, `expected a substantial worker module graph, got ${modules.size}`);
-      assert([...modules].some((url) => url.includes('/src/library.js')), 'EyeProlog library missing from worker graph');
+      assert([...modules].some((url) => url.includes('/src/eyeprolog-library.js')), 'EyeProlog library missing from worker graph');
       assert([...modules].some((url) => url.includes('/src/solver.js')), 'solver missing from worker graph');
     });
   });

package/test/run-regression.mjs

@@ -177,15 +177,23 @@ why(
       },
     },
     {
-      name: 'EYEPROLOG_LOCAL_TIME fixes local_time builtin',
+      name: 'seeded random/3 sequence is reproducible',
       run: () => {
-        const result = runCli(['--goal', 'local_time_answer(D)', '-'], {
-          input: 'local_time_answer(D) :- local_time(D).\n',
-          env: { EYEPROLOG_LOCAL_TIME: '2024-01-02' },
-        });
-        assertEqual(result.status, 0, 'exit status');
-        assertEqual(result.stdout, "local_time_answer('2024-01-02').\n", 'stdout');
-        assertEqual(result.stderr, '', 'stderr');
+        const result = run(
+          'seeded(A, B, C, Seeds) :- random(1, A, S1), random(S1, B, S2), random(1, C, S3), Seeds = [S1, S2, S3].\n',
+          { goal: 'seeded(A, B, C, Seeds)' },
+        );
+        assertEqual(result.stdout, 'seeded(0.00002247747035927835, 0.085032448717423201, 0.00002247747035927835, [48271, 182605794, 48271]).\n', 'stdout');
+      },
+    },
+    {
+      name: 'seeded uuid/3 sequence is reproducible',
+      run: () => {
+        const result = run(
+          'seeded_uuid(U1, U2, true) :- uuid(1, U1, S1), uuid(1, U1, _), uuid(S1, U2, _), U1 \\= U2.\n',
+          { goal: 'seeded_uuid(U1, U2, Same)' },
+        );
+        assertEqual(result.stdout, "seeded_uuid('f26d1319-3f3f-4bd9-b92f-f414794a43b5', '4be874d3-166b-4107-b0dc-9c53074b3de1', true).\n", 'stdout');
       },
     },
     {
@@ -576,7 +584,7 @@ function documentationSyncCases() {
           '[Book — *The Art of EyeProlog*](https://eyereasoner.github.io/eyeprolog/the-art-of-eyeprolog)',
           'README links to the book',
         );
-        for (const filename of ['src/iso.js', 'src/library.js', 'src/playground-worker.js']) {
+        for (const filename of ['src/iso.js', 'src/eyeprolog-library.js', 'src/playground-worker.js']) {
           assertEqual(fs.existsSync(path.join(packageRoot, filename)), true, `${filename} exists`);
           assertIncludes(book, filename, `book documents ${filename}`);
         }
@@ -1007,19 +1015,21 @@ 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, 117, 'ISO plus host registry size');
-        assertEqual(registeredNativeEyePrologLibraryNames().length, 2, 'public native EyeProlog builtin count');
-        assertEqual(eyePrologPortableLibraryIndicators.length, 48, 'portable Prolog library count');
-        assertEqual(eyePrologNativeLibraryIndicators.length, 2, 'native host library count');
-        assertEqual(eyePrologNativeLibraryIndicators.join(','), 'uuid/1,local_time/1', 'native host library stays minimal');
+        assertEqual(library.defs.size, 115, 'EyeProlog registry contains only ISO host definitions');
+        assertEqual(registeredNativeEyePrologLibraryNames().length, 0, 'public native EyeProlog builtin count');
+        assertEqual(eyePrologPortableLibraryIndicators.length, 50, '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, 50, 'complete EyeProlog library surface');
         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');
+        assertEqual(library.get('local_time', 1), null, 'local_time/1 is not a host builtin');
         assertEqual(library.get('eyeprolog__string_atom', 2), null, 'private string adapter is absent');
         assertEqual(library.get('append', 3), null, 'append/3 moved to portable Prolog');
         assertEqual(library.get('maplist', 3), null, 'maplist/3 moved to portable Prolog');
         assertEqual(library.get('matches', 3), null, 'matches/3 moved to portable Prolog');
-        assertEqual(library.get('uuid', 1)?.deterministic, true, 'uuid/1 deterministic metadata');
+        assertEqual(library.get('uuid', 3), null, 'uuid/3 remains portable Prolog');
         for (const [name, arity] of [['not_member', 2], ['head', 2], ['rest', 2], ['min', 3], ['max', 3]]) {
           assertEqual(library.get(name, arity), null, `${name}/${arity} removed from library`);
         }
@@ -1037,9 +1047,11 @@ open(X) :- candidate(X), \\+ closed(X).
         assertEqual(betweenGenerator.cutRecursive, true, 'portable between generator has deterministic recursive control');
         assertEqual(betweenGenerator.tabled, false, 'portable between generator avoids suffix answer tables');
         assertEqual(fs.existsSync(path.join(packageRoot, 'src', 'eyeprolog-library.pl')), true, 'portable Prolog source exists');
-        assertEqual(fs.existsSync(path.join(packageRoot, 'src', 'library-source.js')), true, 'portable source loader exists');
+        assertEqual(fs.existsSync(path.join(packageRoot, 'src', 'eyeprolog-library.js')), true, 'portable source loader exists');
+        assertEqual(fs.existsSync(path.join(packageRoot, 'src', 'library-source.js')), false, 'duplicate source loader is absent');
         assertEqual(fs.existsSync(path.join(packageRoot, 'src', 'portable-library.js')), false, 'obsolete duplicate module remains absent');
         assertEqual(run(program, { goal: 'answer(X)' }).stdout, 'answer([a, b]).\n', 'autoloaded append execution');
+        assertEqual(Boolean(program.findGroup('random', 3)), true, 'random/3 is autoloaded as a clause group');
       },
     },
     {
@@ -1053,8 +1065,9 @@ portable_check(A, B, C) :- lowercase('HELLO', A), replace('banana', 'na', 'NA',
         const goal = parseGoalText('portable_check(A, B, C)');
         const answers = [...solver.solve([goal], new Env(), 0)].map((env) => termToString(goal, env, true));
         assertEqual(answers.join('\n'), "portable_check(hello, baNANA, [x, y])", 'ISO-only portable execution');
-        assertEqual(program.findGroup('uuid', 1), null, 'uuid/1 remains outside portable file');
-        assertEqual(program.findGroup('local_time', 1), null, 'local_time/1 remains outside portable file');
+        assertEqual(Boolean(program.findGroup('uuid', 3)), true, 'uuid/3 is implemented in the portable file');
+        assertEqual(program.findGroup('uuid', 1), null, 'obsolete uuid/1 is absent');
+        assertEqual(program.findGroup('local_time', 1), null, 'local_time/1 is absent from the library');
       },
     },
     {
@@ -1699,7 +1712,7 @@ function playgroundStaticIssues() {
   if (!html.includes("new URL('./src/playground-worker.js?playground=")) issues.push('playground must cache-bust its dedicated module worker');
   if (!html.includes("new Worker(workerUrl, { type: 'module' })")) issues.push('playground must launch the dedicated module worker');
   const workerText = fs.readFileSync(path.join(packageRoot, 'src', 'playground-worker.js'), 'utf8');
-  if (!workerText.includes("from './library.js?playground=") ||
+  if (!workerText.includes("from './eyeprolog-library.js?playground=") ||
       !workerText.includes('createEyePrologRegistry') ||
       !workerText.includes('executePlaygroundRequest')) {
     issues.push('playground worker must install the EyeProlog library registry');

package/the-art-of-eyeprolog.md

@@ -1710,10 +1710,10 @@ truncate search; it does not prove that no further answer exists.
 
 The source layout mirrors the language boundary. `src/iso.js` contains the
 isolated ISO processor predicates and registry. `src/eyeprolog-library.pl` is
-the portable EyeProlog library: 48 public predicates written as ordinary
-Prolog clauses against that ISO profile. `src/library-source.js` loads the same
-file in Node and the browser, while `src/library.js` owns autoload integration
-and the two unavoidable public host predicates, `uuid/1` and `local_time/1`.
+the portable EyeProlog library: 50 public predicates written as ordinary
+Prolog clauses against that ISO profile. Its paired
+`src/eyeprolog-library.js` module loads the Prolog file in Node and the browser
+and owns the small autoload integration layer.
 The RDF tools emit IRI and literal lexical values as ISO atoms, matching the
 portable text API without a host representation adapter.
 
@@ -5253,17 +5253,15 @@ so side effects occur in Prolog execution order.
 ### The EyeProlog library
 
 EyeProlog exposes **50 library predicate indicators** in addition to the 115
-indicators in its isolated ISO profile. Of those 50, **48 are ordinary Prolog
-clauses** in `src/eyeprolog-library.pl`; only **`uuid/1` and `local_time/1` are
-native host predicates** because ISO Prolog provides neither entropy nor a wall
-clock. The resulting normal EyeProlog language surface is therefore **165
-public predicate indicators**. Internally, the runtime registry has 117
-definitions: 115 ISO predicates and the 2 public host predicates.
+indicators in its isolated ISO profile. **All 50 are ordinary Prolog clauses**
+in `src/eyeprolog-library.pl`; none is a native host predicate. The resulting
+normal EyeProlog language surface is therefore **165 public predicate
+indicators**. Internally, the runtime registry contains only the 115 ISO
+definitions; the EyeProlog relations are autoloaded source clauses.
 
 The portable file is autoloaded once into every `Program` used with the
-EyeProlog registry. `src/library-source.js` loads it from the package in Node or
-through `fetch()` in the browser; `src/library.js` performs the autoload and
-registers the two host predicates.
+EyeProlog registry. `src/eyeprolog-library.js` loads it from the package in Node
+or through `fetch()` in the browser and performs the autoload.
 The isolated ISO-only registry remains
 available through `createDefaultRegistry()` and `getDefaultRegistry()` for
 conformance work and advanced embedders. Source clauses sharing a portable
@@ -5283,11 +5281,11 @@ standard fallback relation.
 | `join/3`, `substring/4` |
 | `countall/2`, `sumall/3` |
 | `aggregate_min/5`, `aggregate_max/5` |
-| `between/3`, `smallest_divisor_from/3` |
+| `between/3`, `smallest_divisor_from/3`, `random/3` |
 | `maplist/3` |
 | `acos/2`, `asin/2`, `atan2/3`, `tan/2` |
 | `lt/2`, `le/2`, `gt/2`, `ge/2` |
-| `uuid/1`, `local_time/1`, `difference/3` |
+| `uuid/3`, `difference/3` |
 | `matches/3` |
 | `call/3` |
 | `split/3`, `replace/4` |
@@ -5296,10 +5294,11 @@ standard fallback relation.
 
 <!-- eyeprolog-library-catalog:end -->
 
-`uuid/1` creates one fresh version 4 UUID atom. It is deterministic in
-the Prolog sense: each call has exactly one solution, although the generated atom
-is intentionally different between calls. The implementation uses the Web Crypto API where available and remains
-portable across Node and the browser playground.
+`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, the EyeProlog library is already present:
 
@@ -5335,13 +5334,14 @@ the corresponding predicate.
 | --- | --- |
 | `tan/2`, `asin/2`, `acos/2`, `atan2/3` | Floating-point functions not supplied as evaluable functions by ISO/IEC 13211-1. |
 | `lt(+A,+B)`, `le(+A,+B)`, `gt(+A,+B)`, `ge(+A,+B)` | Compare integers exactly, finite numeric text numerically, `PnYnMnD` duration text component-wise, and other lexical values by string order. These differ from ISO arithmetic comparison and standard term order. |
-| `local_time(-Date)` | The one host relation in this group. Produces the host-local calendar date as atom `'YYYY-MM-DD'`. Tests and reproducible hosts may set `EYEPROLOG_LOCAL_TIME`. |
+| `random(+Seed0,-Value,-Seed)` | Portable Park-Miller generator with explicit state. `Value` is in `[0,1)`; pass the returned integer `Seed` to the next call. The same initial integer seed always reproduces the same sequence. |
 | `difference(+End,+Start,-Duration)` | Portable Prolog. Computes a nonnegative calendar difference between ISO date atoms/character lists and returns atom `'PnYnMnD'`. Invalid dates or an end before the start fail. |
 
 ```eyeprolog
 answer(square, S) :- (S is 12 * 12).
 answer(day_count, N) :- between(3, 5, N).
 answer(age, D) :- difference('2026-07-28', '2020-05-20', D).
+answer(random_pair, [A,B]) :- random(42, A, S), random(S, B, _).
 eyeprolog --goal 'answer(Kind, Value)' program.pl
 ```
 
@@ -5778,7 +5778,7 @@ studies.
 | [Socket Age](https://github.com/eyereasoner/eyeprolog/blob/main/examples/socket-age.pl) | Socket and plug declarations for an age-reasoning module with registry, policy, and clock providers. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/socket-age.pl) · [proof](https://github.com/eyereasoner/eyeprolog/blob/main/examples/proof/socket-age.pl) |
 | [Socket Family](https://github.com/eyereasoner/eyeprolog/blob/main/examples/socket-family.pl) | Socket and plug declarations for a family-reasoning module that expects a `parent/2` provider. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/socket-family.pl) · [proof](https://github.com/eyereasoner/eyeprolog/blob/main/examples/proof/socket-family.pl) |
 | [Socrates](https://github.com/eyereasoner/eyeprolog/blob/main/examples/socrates.pl) | A fact and one rule turn the classical syllogism into a ground derivation. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/socrates.pl) · [proof](https://github.com/eyereasoner/eyeprolog/blob/main/examples/proof/socrates.pl) |
-| [UUID](https://github.com/eyereasoner/eyeprolog/blob/main/examples/uuid.pl) | `uuid/1` creates one version 4 UUID atom; the example validates its shape while keeping the checked answer stable. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/uuid.pl) |
+| [UUID](https://github.com/eyereasoner/eyeprolog/blob/main/examples/uuid.pl) | `uuid/3` reproducibly creates one version 4 UUID atom from explicit random state; the example validates its canonical shape. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/uuid.pl) |
 | [Witch](https://github.com/eyereasoner/eyeprolog/blob/main/examples/witch.pl) | Burn the witch, adapted from Eyeling's examples/witch.n3. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/witch.pl) · [proof](https://github.com/eyereasoner/eyeprolog/blob/main/examples/proof/witch.pl) |
 
 Suggested path: Socrates → Age → Ancestor → Derived rule → Reusable built-ins.

package/src/library-source.js

@@ -1,18 +0,0 @@
-// Load the portable EyeProlog Prolog-library source from the package assets.
-// eyeprolog-library.pl is the source of truth for all 48 portable public
-// library predicates.
-import { fs, isNode } from './platform.js';
-
-const portableLibraryUrl = new URL('./eyeprolog-library.pl', import.meta.url);
-
-async function loadSource(url, label) {
-  if (isNode) return fs.readFileSync(url, 'utf8');
-  const response = await fetch(url);
-  if (!response.ok) throw new Error(`could not load ${label}: ${response.status}`);
-  return response.text();
-}
-
-export const eyePrologPortableLibrarySource = await loadSource(
-  portableLibraryUrl,
-  'EyeProlog portable library',
-);

package/src/library.js

@@ -1,171 +0,0 @@
-// EyeProlog library integration.
-//
-// 48 of the 50 public library predicates are implemented in plain Prolog in
-// eyeprolog-library.pl and autoloaded into every Solver that uses the EyeProlog
-// registry.  Only uuid/1 and local_time/1 remain native because ISO Prolog has
-// no standard entropy or wall-clock primitive.
-import {
-  atom,
-  unify,
-} from './term.js';
-import {
-  BuiltinRegistry,
-  isoBuiltins,
-} from './iso.js';
-import { parseClauses } from './parser.js';
-import { eyePrologPortableLibrarySource } from './library-source.js';
-
-export const eyePrologNativeLibraryIndicators = Object.freeze([
-  'uuid/1',
-  'local_time/1',
-]);
-
-export const eyePrologPortableLibraryIndicators = Object.freeze([
-  'difference/3',
-  'call/3',
-  'maplist/3',
-  'tan/2',
-  'asin/2',
-  'acos/2',
-  'atan2/3',
-  'lt/2',
-  'gt/2',
-  'le/2',
-  'ge/2',
-  'between/3',
-  'smallest_divisor_from/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',
-  'length/2',
-  'sum_list/2',
-  'min_list/2',
-  'max_list/2',
-  'list_to_set/2',
-  'sort/2',
-  'countall/2',
-  'sumall/3',
-  'aggregate_min/5',
-  'aggregate_max/5',
-]);
-
-export const eyePrologLibraryIndicators = Object.freeze([
-  ...eyePrologNativeLibraryIndicators,
-  ...eyePrologPortableLibraryIndicators,
-]);
-
-const portableIndicatorSet = new Set(eyePrologPortableLibraryIndicators);
-const autoloadedPrograms = new WeakSet();
-const portableClauseTemplates = parseClauses(eyePrologPortableLibrarySource, {
-  filename: 'src/eyeprolog-library.pl',
-  sourceMetadata: true,
-});
-
-
-export function ensureEyePrologLibrary(program) {
-  if (autoloadedPrograms.has(program)) return program;
-
-  // User clauses already present in the Program stay first in clause order;
-  // the autoloaded library clauses are appended as defaults. This preserves
-  // useful source specializations such as length(numbers,N) while still making
-  // the relational length(List,N) library clauses available inside them.
-  let added = 0;
-  for (const template of portableClauseTemplates) {
-    // Clause terms are immutable; clone only the mutable indexing shell so the
-    // cached parse can be safely shared across independent Program instances.
-    const clause = {
-      ...template,
-      body: template.body.slice(),
-      index: program.clauses.length,
-      eyePrologLibraryPortable: true,
-    };
-    program.clauses.push(clause);
-    program.indexClause(clause);
-    added++;
-  }
-  if (added > 0) program.markRecursivePredicates();
-  autoloadedPrograms.add(program);
-  return program;
-}
-
-export function createEyePrologRegistry() {
-  const registry = new BuiltinRegistry();
-  registry.eyePrologLibrary = true;
-
-  registry.add('uuid', 1, uuidBuiltin, {
-    deterministic: true,
-    eyePrologLibrary: true,
-  });
-  registry.add('local_time', 1, localTimeBuiltin, {
-    deterministic: true,
-    eyePrologLibrary: true,
-  });
-  // ISO definitions take precedence where names overlap and remain identifiable
-  // as ISO rather than EyeProlog-library predicates.
-  isoBuiltins.register(registry);
-  return registry;
-}
-
-let eyePrologRegistry = null;
-
-export function getEyePrologRegistry() {
-  if (eyePrologRegistry == null) eyePrologRegistry = createEyePrologRegistry();
-  return eyePrologRegistry;
-}
-
-function* uuidBuiltin({ goal, env }) {
-  const next = env.clone();
-  if (unify(goal.args[0], atom(randomUuidV4()), next)) yield next;
-}
-
-function* localTimeBuiltin({ goal, env }) {
-  const next = env.clone();
-  if (unify(goal.args[0], atom(localDateText()), next)) yield next;
-}
-
-function randomUuidV4() {
-  const cryptoApi = globalThis.crypto;
-  if (typeof cryptoApi?.randomUUID === 'function') return cryptoApi.randomUUID();
-  const bytes = new Uint8Array(16);
-  if (typeof cryptoApi?.getRandomValues === 'function') {
-    cryptoApi.getRandomValues(bytes);
-  } else {
-    for (let index = 0; index < bytes.length; index++) bytes[index] = Math.floor(Math.random() * 256);
-  }
-  bytes[6] = (bytes[6] & 0x0f) | 0x40;
-  bytes[8] = (bytes[8] & 0x3f) | 0x80;
-  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0'));
-  return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex.slice(6, 8).join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10).join('')}`;
-}
-
-function localDateText() {
-  const fixed = typeof process !== 'undefined' ? process.env?.EYEPROLOG_LOCAL_TIME : null;
-  if (fixed) return fixed;
-  const now = new Date();
-  const yyyy = now.getFullYear();
-  const mm = String(now.getMonth() + 1).padStart(2, '0');
-  const dd = String(now.getDate()).padStart(2, '0');
-  return `${yyyy}-${mm}-${dd}`;
-}