eyeprolog 1.5.3 → 1.5.5

package/README.md

@@ -57,10 +57,10 @@ printf 'human(socrates).\nmortal(X) :- human(X).\n' |
 ```
 
 ## Native forward rules (`:+`)
-
 Normal mode executes top-level `Conclusion :+ Premise` rules natively when no explicit
 `-g/--goal` is supplied. `true :+ Goal` prints answers and `false :+ Goal` emits a
-`fuse/1`; JavaScript `run()` follows the same rule. Strict ISO mode disables this
+`fuse/1`; JavaScript `run()` follows the same rule. The bundled `library(eyelet)`
+exports the `:+` operator, `stable/1`, and `becomes/2`. Strict ISO mode disables this
 extension. Bundled `src/lib/` predicates autoload in files, CLI/API goals, and the REPL;
 use `--no-autoload` to require explicit imports, and explicitly import libraries that introduce
 operators before using their syntax. See [*The Art of EyeProlog*](the-art-of-eyeprolog.md) for the full semantics.

package/package.json

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

package/src/datalog-common.js

@@ -0,0 +1,56 @@
+// Shared plumbing for the finite positive-Datalog and WFS evaluators.
+//
+// Keep evaluator-specific relation storage and fixpoint algorithms in their
+// own modules; this file only contains representation/traversal helpers whose
+// semantics are common to both execution paths.
+
+import { ATOM, COMPOUND, VAR } from './term.js';
+
+export const EMPTY_ARRAY = Object.freeze([]);
+
+export function predicateKey(module, name, arity) {
+  return `${module ?? 'user'}:${name}/${arity}`;
+}
+
+export function directLiteral(goal, module) {
+  if (goal?.type !== COMPOUND && goal?.type !== ATOM) return null;
+  return {
+    key: predicateKey(goal.module ?? module, goal.name, goal.arity),
+    name: goal.name,
+    arity: goal.arity,
+    module: goal.module ?? module,
+    args: goal.args ?? EMPTY_ARRAY,
+  };
+}
+
+export function dependencyCone(program, rootGroup, literalForGoal = directLiteral) {
+  const groups = [];
+  const seen = new Set();
+  const stack = [rootGroup];
+  while (stack.length > 0) {
+    const group = stack.pop();
+    const key = predicateKey(group.module, group.name, group.arity);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    groups.push(group);
+    for (const clause of group.clauses) {
+      for (const goal of clause.body) {
+        const literal = literalForGoal(goal, group.module);
+        if (!literal) continue;
+        const target = program.findGroup(literal.name, literal.arity, literal.module);
+        if (target) stack.push(target);
+      }
+    }
+  }
+  return groups;
+}
+
+export function resolvePatternTerm(term, bindings) {
+  if (term.type === VAR) return bindings.get(term.name) ?? null;
+  return term;
+}
+
+export function estimateLiteral(literal, relation, bindings) {
+  const candidates = relation.candidateIndexes(literal.args, bindings);
+  return candidates == null ? relation.rows.length : candidates.length;
+}

package/src/datalog.js

@@ -5,14 +5,16 @@
 // newly-added row fires only the rule occurrences that mention its predicate.
 // This avoids replaying the whole recursive program on every table round.
 
-import { ATOM, COMPOUND, VAR } from './term.js';
+import { VAR } from './term.js';
 import { numberValueKey } from './number-value.js';
-
-const EMPTY_ARRAY = Object.freeze([]);
-
-function predicateKey(module, name, arity) {
-  return `${module ?? 'user'}:${name}/${arity}`;
-}
+import {
+  EMPTY_ARRAY,
+  dependencyCone,
+  directLiteral,
+  estimateLiteral,
+  predicateKey,
+  resolvePatternTerm,
+} from './datalog-common.js';
 
 const scalarKeyCache = new WeakMap();
 
@@ -30,11 +32,6 @@ function sameScalar(left, right) {
   return scalarKey(left) === scalarKey(right);
 }
 
-function tupleKey(tuple) {
-  if (tuple.length === 1) return scalarKey(tuple[0]);
-  return tuple.map(scalarKey).join('\u0001');
-}
-
 export class DatalogRelation {
   constructor(arity) {
     this.arity = arity;
@@ -117,50 +114,16 @@ export class DatalogRelation {
   }
 }
 
-function directLiteral(goal, module) {
-  if (goal?.type !== COMPOUND && goal?.type !== ATOM) return null;
-  return {
-    key: predicateKey(goal.module ?? module, goal.name, goal.arity),
-    name: goal.name,
-    arity: goal.arity,
-    module: goal.module ?? module,
-    args: goal.args ?? EMPTY_ARRAY,
-  };
-}
-
-function dependencyCone(program, rootGroup) {
-  const groups = [];
-  const seen = new Set();
-  const stack = [rootGroup];
-  while (stack.length > 0) {
-    const group = stack.pop();
-    const key = predicateKey(group.module, group.name, group.arity);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    groups.push(group);
-    for (const clause of group.clauses) {
-      for (const goal of clause.body) {
-        const literal = directLiteral(goal, group.module);
-        if (!literal) continue;
-        const target = program.findGroup(literal.name, literal.arity, literal.module);
-        if (target) stack.push(target);
-      }
-    }
-  }
-  return groups;
-}
 
 function compileProgram(program, rootGroup) {
   const groups = dependencyCone(program, rootGroup);
   const relations = new Map();
-  const groupByKey = new Map();
   const rules = [];
   const triggers = new Map();
 
   for (const group of groups) {
     const key = predicateKey(group.module, group.name, group.arity);
     relations.set(key, new DatalogRelation(group.arity));
-    groupByKey.set(key, group);
   }
 
   for (const group of groups) {
@@ -181,13 +144,9 @@ function compileProgram(program, rootGroup) {
     }
   }
 
-  return { groups, groupByKey, relations, rules, triggers };
+  return { groups, relations, rules, triggers };
 }
 
-function resolvePatternTerm(term, bindings) {
-  if (term.type === VAR) return bindings.get(term.name) ?? null;
-  return term;
-}
 
 function matchTupleMutable(args, tuple, bindings) {
   const added = [];
@@ -218,10 +177,6 @@ function undoBindings(bindings, added) {
   for (let i = added.length - 1; i >= 0; i--) bindings.delete(added[i]);
 }
 
-function estimateLiteral(literal, relation, bindings) {
-  const candidates = relation.candidateIndexes(literal.args, bindings);
-  return candidates == null ? relation.rows.length : candidates.length;
-}
 
 function forEachBinding(body, relations, callback, bindings, remaining) {
   if (remaining.length === 0) {
@@ -271,16 +226,6 @@ function forEachBinding(body, relations, callback, bindings, remaining) {
   }
 }
 
-function instantiateTuple(args, bindings) {
-  const tuple = new Array(args.length);
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    const value = arg.type === VAR ? bindings.get(arg.name) : arg;
-    if (value == null || value.type === VAR) return null;
-    tuple[i] = value;
-  }
-  return tuple;
-}
 
 export function evaluatePositiveDatalog(program, rootGroup) {
   const compiled = compileProgram(program, rootGroup);

package/src/execute.js

@@ -82,8 +82,6 @@ export function executeForwardRules(program, solver, {
   predeclareForwardTerms(program, solver, group);
   setSingletonFact(program, 'closure', [numberTerm(0)]);
   setSingletonFact(program, 'limit', [numberTerm(-1)]);
-  setSingletonFact(program, 'count', [atom('fm'), numberTerm(0)], true);
-  setSingletonFact(program, 'count', [atom('mf'), numberTerm(0)], true);
 
   const seenAnswers = new Set();
   let rounds = 0;
@@ -188,11 +186,6 @@ export function executeForwardRules(program, solver, {
     break;
   }
 
-  for (const name of ['fm', 'mf']) {
-    const count = keyedCount(program, name);
-    if (count !== 0) onDiagnostic(`*** ${name}=${count}\n`);
-  }
-
   return { haltCode, rounds, derived };
 }
 
@@ -370,12 +363,4 @@ function singletonInteger(program, name, fallback) {
   return fallback;
 }
 
-function keyedCount(program, key) {
-  const group = program.findGroup('count', 2, 'user');
-  if (group == null) return 0;
-  for (let i = group.clauses.length - 1; i >= 0; i--) {
-    const args = group.clauses[i].head?.args;
-    if (args?.[0]?.type === ATOM && args[0].name === key && args[1]?.type === NUMBER) return Number(args[1].name);
-  }
-  return 0;
-}
+

package/src/lib/eyelet.pl

@@ -0,0 +1,43 @@
+% Eyelet forward-reasoning support for EyeProlog.
+%
+% The :+/2 closure itself is executed natively by EyeProlog.  This module owns
+% the two state helpers used by Eyelet programs and exports the :+ operator so
+% source files can opt into the complete surface with one use_module/1.
+
+:- module(eyelet, [op(1200, xfx, :+), stable/1, becomes/2]).
+
+:- use_module(library(iso_ext), [forall/2]).
+:- use_module(library(lists), [member/2]).
+
+:- meta_predicate(becomes(0, 0)).
+
+% stable(+Level)
+% Fail until the native forward-rule driver has reached the requested closure
+% level.  Asking for a higher level extends the driver's target limit.
+stable(Level) :-
+    call(user:limit(Limit)),
+    (   Limit < Level
+    ->  user:retract(limit(Limit)),
+        user:assertz(limit(Level))
+    ;   true
+    ),
+    call(user:closure(Closure)),
+    Level =< Closure.
+
+% becomes(:From, :To)
+% Linear implication over dynamic state: prove and retract every conjunct in
+% From, then assert every conjunct in To.
+becomes(From, To) :-
+    catch(call(user:From), _, fail),
+    conj_list(From, Old),
+    forall(member(Clause, Old), user:retract(Clause)),
+    conj_list(To, New),
+    forall(member(Clause, New), user:assertz(Clause)).
+
+conj_list(true, []).
+conj_list(Goal, [Goal]) :-
+    Goal \= (_, _),
+    Goal \= false,
+    !.
+conj_list((A, B), [A|Rest]) :-
+    conj_list(B, Rest).

package/src/library-autoload-index.js

@@ -69,6 +69,7 @@ export const eyePrologLibraryAutoload = Object.freeze({
   "bb_get/2": "debug",
   "bb_global_get/2": "debug",
   "bb_put/2": "debug",
+  "becomes/2": "eyelet",
   "between/3": "between",
   "call_nth/2": "iso_ext",
   "call_residue_vars/2": "atts",
@@ -264,6 +265,7 @@ export const eyePrologLibraryAutoload = Object.freeze({
   "slice/4": "lists",
   "smallest_divisor_from/3": "primes",
   "split/3": "strings",
+  "stable/1": "eyelet",
   "start_tabling/2": "tabling",
   "string_concat/3": "strings",
   "substring/4": "strings",
@@ -322,6 +324,7 @@ export const eyePrologLibraryAutoloadModules = Object.freeze([
   "debug",
   "dif",
   "error",
+  "eyelet",
   "format",
   "freeze",
   "gensym",

package/src/program.js

@@ -1131,6 +1131,14 @@ function bundledLibraryModule(program, module) {
 function groupDependencies(group) {
   const dependencies = [];
   for (const clause of group.clauses) {
+    // Native forward rules store their executable premise in the :+/2 head
+    // rather than in the ordinary clause body.  Treat that premise as a goal
+    // dependency so bundled predicates such as stable/1 and becomes/2 can be
+    // autoloaded exactly like calls in ordinary rules.  Derived :+ rules may
+    // themselves occur in a conclusion, so recurse through that shape too.
+    if (group.name === ':+') {
+      dependencies.push(...forwardRuleDependencies(clause.head));
+    }
     if (isCompactBinaryClause(clause)) {
       if (clause.bodyName != null) {
         dependencies.push({
@@ -1149,6 +1157,103 @@ function groupDependencies(group) {
   return dependencies;
 }
 
+function forwardRuleDependencies(term, out = []) {
+  if (term?.type !== COMPOUND) return out;
+  if (term.name === ':+' && term.arity === 2) {
+    out.push(...collectGoalDependencies(term.args[1], false, true));
+    forwardRuleDependencies(term.args[0], out);
+    return out;
+  }
+  if (term.name === ',' && term.arity === 2) {
+    forwardRuleDependencies(term.args[0], out);
+    forwardRuleDependencies(term.args[1], out);
+  }
+  return out;
+}
+
+// Autoloading needs a slightly richer dependency walk than recursion analysis.
+// Meta-predicates such as forall/2 and setof/3 are themselves callable
+// procedures while also containing executable goals.  The recursion graph
+// intentionally looks through those wrappers; the autoloader must see both the
+// wrapper and any statically visible nested calls so a bundled library can be
+// loaded before execution reaches it.
+function collectAutoloadGoalDependencies(goal, out = []) {
+  if (goal?.type === ATOM) {
+    out.push({ key: `${goal.name}/0`, name: goal.name, arity: 0, module: goal.module });
+    return out;
+  }
+  if (goal?.type !== COMPOUND) return out;
+  if (goal.name === ',' && goal.arity === 2) {
+    collectAutoloadGoalDependencies(goal.args[0], out);
+    collectAutoloadGoalDependencies(goal.args[1], out);
+    return out;
+  }
+  if ((goal.name === ';' || goal.name === '->') && goal.arity === 2) {
+    collectAutoloadGoalDependencies(goal.args[0], out);
+    collectAutoloadGoalDependencies(goal.args[1], out);
+    return out;
+  }
+  if ((goal.name === '\\+' || goal.name === 'not' || goal.name === 'tnot' || goal.name === 'once') && goal.arity === 1) {
+    collectAutoloadGoalDependencies(goal.args[0], out);
+    return out;
+  }
+
+  out.push({ key: `${goal.name}/${goal.arity}`, name: goal.name, arity: goal.arity, module: goal.module });
+
+  if (goal.name === 'forall' && goal.arity === 2) {
+    collectAutoloadGoalDependencies(goal.args[0], out);
+    collectAutoloadGoalDependencies(goal.args[1], out);
+  } else if ((goal.name === 'findall' || goal.name === 'bagof' || goal.name === 'setof' || goal.name === 'sumall') && goal.arity === 3) {
+    collectAutoloadGoalDependencies(goal.args[1], out);
+  } else if (goal.name === 'countall' && goal.arity === 2) {
+    collectAutoloadGoalDependencies(goal.args[0], out);
+  } else if ((goal.name === 'aggregate_min' || goal.name === 'aggregate_max') && goal.arity === 5) {
+    collectAutoloadGoalDependencies(goal.args[2], out);
+  } else if (goal.name === 'catch' && goal.arity === 3) {
+    collectAutoloadGoalDependencies(goal.args[0], out);
+    collectAutoloadGoalDependencies(goal.args[2], out);
+  } else if ((goal.name === 'call_cleanup' || goal.name === 'setup_call_cleanup') && (goal.arity === 2 || goal.arity === 3)) {
+    for (const arg of goal.args) collectAutoloadGoalDependencies(arg, out);
+  } else if (goal.name === 'call' && goal.arity === 1) {
+    collectAutoloadGoalDependencies(goal.args[0], out);
+  }
+  return out;
+}
+
+function forwardRuleAutoloadDependencies(term, out = []) {
+  if (term?.type !== COMPOUND) return out;
+  if (term.name === ':+' && term.arity === 2) {
+    collectAutoloadGoalDependencies(term.args[1], out);
+    forwardRuleAutoloadDependencies(term.args[0], out);
+    return out;
+  }
+  if (term.name === ',' && term.arity === 2) {
+    forwardRuleAutoloadDependencies(term.args[0], out);
+    forwardRuleAutoloadDependencies(term.args[1], out);
+  }
+  return out;
+}
+
+function groupAutoloadDependencies(group) {
+  const dependencies = [];
+  for (const clause of group.clauses) {
+    if (group.name === ':+') dependencies.push(...forwardRuleAutoloadDependencies(clause.head));
+    if (isCompactBinaryClause(clause)) {
+      if (clause.bodyName != null) {
+        dependencies.push({
+          key: `${clause.bodyName}/2`,
+          name: clause.bodyName,
+          arity: 2,
+          module: clause.module ?? group.module,
+        });
+      }
+      continue;
+    }
+    for (const goal of clause.body) collectAutoloadGoalDependencies(goal, dependencies);
+  }
+  return dependencies;
+}
+
 function parseInteropGoalInputs(inputs, options, program) {
   if (inputs == null) return [];
   const values = Array.isArray(inputs) ? inputs : [inputs];
@@ -1164,7 +1269,7 @@ function parseInteropGoalInputs(inputs, options, program) {
 
 function extraGoalDependencies(goals) {
   const dependencies = [];
-  for (const goal of goals) dependencies.push(...collectGoalDependencies(goal, false, true));
+  for (const goal of goals) collectAutoloadGoalDependencies(goal, dependencies);
   return dependencies;
 }
 
@@ -1190,7 +1295,7 @@ 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)) {
+    for (const dependency of groupAutoloadDependencies(group)) {
       const targetModule = dependency.module ?? group.module;
       if (procedureResolvedBeforeAutoload(program, dependency, targetModule)) continue;
       const library = autoloadLibraryFor(dependency);
@@ -1206,7 +1311,7 @@ function libraryAutoloadRequests(program, extraGoals = []) {
     }
   }
   for (const goal of program.initializations) {
-    for (const dependency of collectGoalDependencies(goal, false, true)) {
+    for (const dependency of collectAutoloadGoalDependencies(goal)) {
       const targetModule = dependency.module ?? 'user';
       if (procedureResolvedBeforeAutoload(program, dependency, targetModule)) continue;
       const library = autoloadLibraryFor(dependency);

package/src/standard-library.js

@@ -28,6 +28,7 @@ const moduleFiles = Object.freeze({
   debug: 'debug.pl',
   dif: 'dif.pl',
   error: 'error.pl',
+  eyelet: 'eyelet.pl',
   format: 'format.pl',
   freeze: 'freeze.pl',
   gensym: 'gensym.pl',
@@ -102,6 +103,7 @@ export const eyePrologPortableLibraryIndicators = Object.freeze([
   'sat/1', 'taut/2', 'labeling/1', 'sat_count/2', 'random_labeling/2', 'weighted_maximum/3',
   'lt/2', 'gt/2', 'le/2', 'ge/2',
   'difference/3',
+  'stable/1', 'becomes/2',
   'seq/3', 'seqq/3',
   'debug/1', 'debug/3', 'nodebug/1', 'bb_get/2', 'bb_put/2', 'bb_b_put/2', 'bb_global_get/2',
   '*/1', '$/1', '$-/1',

package/src/wfs.js

@@ -12,10 +12,14 @@
 
 import { ATOM, COMPOUND, VAR } from './term.js';
 import { numberValueKey } from './number-value.js';
-
-function predicateKey(module, name, arity) {
-  return `${module ?? 'user'}:${name}/${arity}`;
-}
+import {
+  EMPTY_ARRAY,
+  dependencyCone,
+  directLiteral,
+  estimateLiteral,
+  predicateKey,
+  resolvePatternTerm,
+} from './datalog-common.js';
 
 function scalarKey(term) {
   if (term.type === 'number') return `number\u0000${numberValueKey(term.name)}`;
@@ -73,8 +77,6 @@ class Relation {
   }
 }
 
-const EMPTY_ARRAY = Object.freeze([]);
-
 function emptyRelations(groups) {
   const relations = new Map();
   for (const group of groups) {
@@ -93,48 +95,18 @@ function copyBaseRelations(base, groups) {
   return relations;
 }
 
-function directLiteral(goal, module) {
-  if (goal?.type !== COMPOUND && goal?.type !== ATOM) return null;
-  return {
-    key: predicateKey(goal.module ?? module, goal.name, goal.arity),
-    name: goal.name,
-    arity: goal.arity,
-    module: goal.module ?? module,
-    args: goal.args ?? EMPTY_ARRAY,
-  };
-}
 
 function negativeLiteral(goal, module) {
   if (goal?.type !== COMPOUND || goal.name !== 'tnot' || goal.arity !== 1) return null;
   return directLiteral(goal.args[0], module);
 }
 
-function dependencyCone(program, rootGroup) {
-  const groups = [];
-  const seen = new Set();
-  const stack = [rootGroup];
-  while (stack.length > 0) {
-    const group = stack.pop();
-    const key = predicateKey(group.module, group.name, group.arity);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    groups.push(group);
-
-    for (const clause of group.clauses) {
-      for (const goal of clause.body) {
-        const neg = negativeLiteral(goal, group.module);
-        const literal = neg ?? directLiteral(goal, group.module);
-        if (!literal) continue;
-        const target = program.findGroup(literal.name, literal.arity, literal.module);
-        if (target) stack.push(target);
-      }
-    }
-  }
-  return groups;
+function dependencyLiteral(goal, module) {
+  return negativeLiteral(goal, module) ?? directLiteral(goal, module);
 }
 
 function compileProgram(program, rootGroup) {
-  const groups = dependencyCone(program, rootGroup);
+  const groups = dependencyCone(program, rootGroup, dependencyLiteral);
   const base = emptyRelations(groups);
   const rules = [];
 
@@ -175,10 +147,6 @@ function compileProgram(program, rootGroup) {
   return { groups, base, rules };
 }
 
-function resolvePatternTerm(term, bindings) {
-  if (term.type === VAR) return bindings.get(term.name) ?? null;
-  return term;
-}
 
 function matchTuple(args, tuple, bindings) {
   let next = null;
@@ -199,10 +167,6 @@ function matchTuple(args, tuple, bindings) {
   return next ?? bindings;
 }
 
-function estimateLiteral(literal, relation, bindings) {
-  const candidates = relation.candidateIndexes(literal.args, bindings);
-  return candidates == null ? relation.rows.length : candidates.length;
-}
 
 function forEachPositiveBinding(positives, relations, callback, bindings = new Map(), remaining = null) {
   if (remaining == null) remaining = positives.map((_, index) => index);

package/test/run-regression.mjs

@@ -4807,8 +4807,10 @@ ${profile}`;
         assertIncludes(book, 'Autoloading therefore supplies', 'autoload syntax boundary');
         assertIncludes(book, 'Residual constraints are part of the displayed answer even when', 'top-level hidden residuals');
         assertIncludes(book, 'EyeProlog normal mode also accepts `:+`', 'native forward-rule extension');
+        assertIncludes(book, '`library(eyelet)`', 'Eyelet library surface');
+        assertIncludes(readme, '`library(eyelet)`', 'README Eyelet library surface');
         assertIncludes(profile, 'an unresolved unqualified predicate may autoload its unique provider', 'Why EyeProlog autoload policy');
-        assertIncludes(readme, 'Bundled `src/lib/` predicates autoload in files, CLI/API goals, and the REPL', 'README autoload summary');
+        assertIncludes(readme, 'Bundled `src/lib/` predicates autoload in files, CLI/API goals,', 'README autoload summary');
       },
     },
     {
@@ -5469,6 +5471,20 @@ function apiCases() {
         assertEqual(result.haltCode, null, 'forward halt code');
       },
     },
+    {
+      name: 'native forward rules autoload library(eyelet) helpers from :+ premises',
+      run: () => {
+        const result = run(`
+:- dynamic(state/1).
+state(a).
+changed :+ becomes(state(a), state(b)).
+seed :+ state(b).
+ready :+ seed, stable(1).
+true :+ ready.
+`);
+        assertEqual(result.stdout, 'ready.\n', 'forward helper stdout');
+      },
+    },
     {
       name: 'run exposes false/0 as an always-failing built-in',
       run: () => {
@@ -6287,7 +6303,7 @@ answer(ok) :-
         assertEqual(registry.get('setup_call_cleanup', 3), null, 'setup_call_cleanup/3 is absent from the ISO registry');
         assertEqual(Boolean(library.get('setup_call_cleanup', 3)), true, 'setup_call_cleanup/3 is an EyeProlog cleanup control');
         assertEqual(registeredNativeEyePrologLibraryNames().length, 58, 'public host-supported EyeProlog library count');
-        assertEqual(eyePrologPortableLibraryIndicators.length, 241, 'portable Prolog library count');
+        assertEqual(eyePrologPortableLibraryIndicators.length, 243, 'portable Prolog library count');
         assertEqual(eyePrologInteropLibraryIndicators.length, 189, 'cross-implementation interop profile count');
         assertEqual(eyePrologInteropLibraryModules.length, 23, 'common explicit library module profile count');
         assertEqual(eyePrologInteropAutoload['member/2'], 'lists', 'member/2 canonical autoload');
@@ -6299,11 +6315,13 @@ answer(ok) :-
         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(eyePrologLibraryAutoload['stable/1'], 'eyelet', 'complete library autoload includes Eyelet stable/1');
+        assertEqual(eyePrologLibraryAutoload['becomes/2'], 'eyelet', 'complete library autoload includes Eyelet becomes/2');
+        assertEqual(eyePrologLibraryAutoloadModules.length, 36, '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');
-        assertEqual(eyePrologLibraryIndicators.length, 299, 'complete non-ISO EyeProlog library surface');
+        assertEqual(eyePrologLibraryIndicators.length, 301, 'complete non-ISO 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(Boolean(library.get('eyeprolog__call_residue_vars', 2)), true, 'private call_residue_vars adapter is registered for EyeProlog');

package/the-art-of-eyeprolog.md

@@ -1681,16 +1681,16 @@ is a forward rule. When a loaded program contains such rules and no explicit
 top-level goal overrides them, the engine runs a native closure driver rather
 than a Prolog meta-interpreter. It repeatedly solves premises against the
 current program, asserts novel conjuncts from successful conclusions, and
-continues until no new conclusion is added. This is the execution path used by
-the Eyelet adapter.
+continues until no new conclusion is added. This is the execution path used when
+Eyelet sources are run directly by EyeProlog.
 
 Two conclusions have control meaning. `true :+ Goal` is a query and prints each
 distinct successful instance of `Goal`. `false :+ Goal` is an integrity fuse:
 on success EyeProlog prints `fuse(Goal)` and returns halt status 2. Variables
 that occur only in an ordinary derived conclusion are existential and become
 `sk_0`, `sk_1`, and so on; a derived conclusion that is itself a `:+` rule keeps
-its variables universal. Eyelet's `stable/1` and `becomes/2` remain library-level
-compatibility helpers, while closure selection and assertion are native.
+its variables universal. The bundled `library(eyelet)` exports the `:+` operator together with
+`stable/1` and `becomes/2`, while closure selection and assertion are native.
 
 The JavaScript convenience `run()` function selects this forward mode when no
 explicit `goal` or `goals` option is supplied. Advanced embedders can inspect a
@@ -6278,12 +6278,12 @@ so side effects occur in Prolog execution order.
 
 ### The EyeProlog library
 
-EyeProlog exposes **299 distinct non-ISO library and normal-extension predicate
+EyeProlog exposes **301 distinct non-ISO library and normal-extension predicate
 indicators** in addition to the 129 indicators in its isolated ISO profile.
-**241 are defined entirely as ordinary Prolog clauses** in focused modules under
+**243 are defined entirely as ordinary Prolog clauses** in focused modules under
 `src/lib/`; **58 use host support** for control, attributed variables,
 constraints, or observability. The ISO and library catalogs therefore cover
-**428 distinct predicate indicators**. Normal-mode controls and observability
+**430 distinct predicate indicators**. Normal-mode controls and observability
 relations that do not belong to a library, such as `call_cleanup/2`,
 `setup_call_cleanup/3`, `statistics/0,2`, and `tnot/1`, are documented in their
 own sections rather than counted as library predicates. `time/1` is additionally
@@ -6296,7 +6296,7 @@ The sources are `src/lib/aggregate.pl`, `src/lib/arithmetic.pl`,
 `src/lib/charsio.pl`, `src/lib/clpb.pl`, `src/lib/clpz.pl`,
 `src/lib/comparison.pl`, `src/lib/dates.pl`, `src/lib/dcgs.pl`,
 `src/lib/debug.pl`, `src/lib/dif.pl`, `src/lib/error.pl`,
-`src/lib/format.pl`, `src/lib/freeze.pl`, `src/lib/gensym.pl`,
+`src/lib/eyelet.pl`, `src/lib/format.pl`, `src/lib/freeze.pl`, `src/lib/gensym.pl`,
 `src/lib/iso_ext.pl`, `src/lib/lambda.pl`, `src/lib/lists.pl`,
 `src/lib/ordsets.pl`, `src/lib/pairs.pl`, `src/lib/pio.pl`,
 `src/lib/primes.pl`, `src/lib/prologue.pl`, `src/lib/random.pl`,
@@ -6368,6 +6368,7 @@ bindings make one aligned subterm pair sufficient. For example:
 | `library(debug)` | `*/1`, `$/1`, `$-/1`, `debug/1`, `debug/3`, `nodebug/1`, `bb_get/2`, `bb_put/2`, `bb_b_put/2`, `bb_global_get/2` | Declarative debug operators and constraint-library blackboards |
 | `library(dif)` | `dif/2` | Common module facade over native delayed disequality |
 | `library(error)` | `must_be/2`, `can_be/2`, `instantiation_error/0`, `instantiation_error/1`, `domain_error/2`, `domain_error/3`, `type_error/2`, `type_error/3`, `representation_error/1`, `resource_error/1`, `call_with_error_context/2` | Error checking and construction |
+| `library(eyelet)` | `stable/1`, `becomes/2` | Eyelet forward-reasoning state helpers; the `:+` operator is exported by the module and executed natively by EyeProlog |
 | `library(format)` | `format_/4`, `format/2`, `format/3`, `listing/1`, `portray_clause_/3`, `portray_clause/1`, `portray_clause/2` | Formatted DCG text and output; `format_/4` and `portray_clause_/3` are the expanded nonterminals |
 | `library(freeze)` | `freeze/2` | Delayed goals |
 | `library(gensym)` | `gensym/2`, `reset_gensym/1` | Process-local generated atoms |

package/why-eyeprolog.md

@@ -143,8 +143,9 @@ This avoids a heuristic silently changing answer multiplicity, termination, or
 resource behavior for an otherwise ordinary recursive predicate.
 
 Forward chaining is explicit too. Normal mode recognizes `Conclusion :+ Premise`
-and executes those rules with a native fixed-point driver, including Eyelet's
-`true :+ Goal` query and `false :+ Goal` fuse conventions. Strict ISO mode
+and executes those rules with a native fixed-point driver. The bundled
+`library(eyelet)` exports the `:+` operator, `stable/1`, and `becomes/2`, including
+Eyelet's `true :+ Goal` query and `false :+ Goal` fuse conventions. Strict ISO mode
 removes the operator. Because resource exhaustion is not logical failure, normal
 execution has no hidden depth cutoff; an explicitly requested depth limit raises
 `resource_error(depth_limit)`.