eyeprolog 1.5.2 → 1.5.4

package/README.md

@@ -31,8 +31,6 @@ Run EyeProlog without installing it globally:
 
 ```sh
 npx --yes eyeprolog
-?- use_module(library(lists)).
-   true.
 ?- member(X, [prolog, logic]).
    X = prolog
 ;  X = logic.
@@ -59,11 +57,13 @@ 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
-extension. See [*The Art of EyeProlog*](the-art-of-eyeprolog.md) for the full semantics.
+`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.
 
 ## Links
 

package/package.json

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

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/test/conformance/ISO-IMPLEMENTATION-DEFINED.md

@@ -121,7 +121,7 @@ families; `--iso-strict` is intended to remove their Part 1 interpretation.
 | 5.5.6 Side effects | Normal mode adds `statistics/0-2`, cleanup/library state, and optional proof/statistics host instrumentation. | The strict registry excludes Prolog-visible statistics/cleanup/library adapters; ordinary Part 1 I/O/database/flag/operator side effects remain. Host proof/statistics collection observes execution through the embedding API rather than adding a strict Prolog goal effect. **covered** — strict registry/execution regression. |
 | 5.5.7 Control constructs | `tnot/1` and normal-profile execution optimizations | `tnot/1` and the normal-profile explicit `table` declaration are absent. |
 | 5.5.8 Flags | `occurs_check` | Absent in strict mode. |
-| 5.5.9 Built-in predicates | EyeProlog libraries, CLP(Z), statistics, Part 3 `phrase/2-3`, and interop autoloaded predicates | Strict registry contains only the Part 1 + Corrigenda core registry. |
+| 5.5.9 Built-in predicates | EyeProlog libraries, CLP(Z), statistics, Part 3 `phrase/2-3`, and bundled-library autoloaded predicates | Strict registry contains only the Part 1 + Corrigenda core registry. |
 | 5.5.10 Evaluable functors | Normal mode additionally accepts the EyeProlog evaluable atom `e`; the remaining arithmetic functors accepted by strict mode are the Part 1 + Corrigenda set. | Strict mode rejects `e/0` as non-evaluable and retains the Corrigendum arithmetic additions. **covered** — strict extension-boundary regression plus `src/iso-arithmetic.js`. |
 | 5.5.11 Reserved atoms | None | None. |
 | Cor.3 5.5.12 Options | Extra library/host options may exist outside core option lists | Normal mode additionally accepts the EyeProlog `write_term/2-3` options `double_quotes(true|false)` and `spacing(true|false)`. `spacing(false)` emits only lexically required separators; `spacing(true)` adds conventional layout around operators. Strict core excludes these implementation-specific extensions and accepts only the Part 1 plus Corrigendum 3 write-option surface; unknown extension options raise `domain_error(write_option,...)`. |

package/test/run-regression.mjs

@@ -4784,6 +4784,35 @@ function documentationSyncCases() {
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'reference docs match explicit tabling and current runtime extensions',
+      run: () => {
+        const readme = fs.readFileSync(path.join(packageRoot, 'README.md'), 'utf8');
+        const book = fs.readFileSync(path.join(packageRoot, 'the-art-of-eyeprolog.md'), 'utf8');
+        const profile = fs.readFileSync(path.join(packageRoot, 'why-eyeprolog.md'), 'utf8');
+        const combined = `${readme}
+${book}
+${profile}`;
+        for (const stale of [
+          'Automatic tabling',
+          'Automatic hybrid reasoning',
+          'eligible positive recursive groups are tabled automatically',
+          '--no-auto-table',
+          'conservative interop autoloading',
+        ]) assertNotIncludes(combined, stale, `stale documentation phrase ${stale}`);
+        assertIncludes(book, 'including recursive calls, use depth-first resolution unless the source', 'ordinary recursion is depth-first');
+        assertIncludes(book, 'explicitly declares `:- table p/n.`', 'tabling is explicit');
+        assertIncludes(book, 'The autoload index covers every', 'generic bundled-library autoload');
+        assertIncludes(book, 'interactive top-level query therefore autoloads its canonical', 'REPL autoload');
+        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,', 'README autoload summary');
+      },
+    },
     {
       name: 'WG17 syntax status matches its executable-coverage manifest',
       run: () => {
@@ -5442,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: () => {
@@ -6260,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');
@@ -6272,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

@@ -30,7 +30,7 @@ program with EyeProlog means learning to move comfortably between these views.
 
 EyeProlog implements a broad ISO Prolog profile with facts, clauses, terms, lists,
 control, arithmetic, dynamic predicates, operators, streams, and standard
-built-ins. Automatic
+built-ins. Explicit
 tabling, explicit integrity checks, and proof output are implementation
 capabilities around that standards-based foundation. EyeProlog does not attempt to
 claim formal certification of every ISO processor edge case.
@@ -175,7 +175,8 @@ Approach each example through the same six moves:
 This rhythm deliberately joins declarative reading, operational reading, and
 program construction. Readers new to logic programming can follow Parts I–III
 in order. Experienced Prolog programmers can begin with Chapters 3, 13, and
-17 to see where EyeProlog's hybrid execution and proof-oriented design differ.
+17 to see how EyeProlog combines ordinary depth-first Prolog with explicit
+tabling, native forward rules, and inspectable proofs.
 Chapter 41 gives further routes through the material.
 
 ### When a run surprises you
@@ -1680,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
@@ -5685,10 +5686,11 @@ so `edge/2` and `edge/3` are different predicates.
 
 Execution is goal-directed rather than complete bottom-up saturation. Goals in
 a body normally run from left to right; the solver may select a ready
-deterministic built-in early as a pure filter. Ordinary user-defined calls use
-depth-first resolution, while eligible positive recursive groups are tabled
-automatically. `\+/1` is stratified negation as failure, not classical
-negation.
+deterministic built-in early as a pure filter. Ordinary user-defined calls,
+including recursive calls, use depth-first resolution unless the source
+explicitly declares `:- table p/n.`. `\+/1` is negation as failure, not
+classical negation; the separate `tnot/1` extension provides well-founded
+semantics for eligible finite Datalog components.
 
 EyeProlog supports cut, operator declarations, dynamic database updates, grouped
 solutions, exceptions, flags, initialization and inclusion directives, and
@@ -5840,21 +5842,27 @@ time. Source facts are not echoed as new conclusions, and duplicate answers
 are suppressed. Answers are not asserted back into the running program.
 Supported output syntax is designed to be readable as Prolog input accepted by EyeProlog.
 
-#### Automatic hybrid reasoning
+#### Explicit tabling and recursion planning
 
-The program loader detects predicate-dependency cycles, including dependencies
-inside conjunction, `\+/1`, `once/1`, and aggregate goals.
-Positive recursive components—including directly queried recursive
-relations—are tabled to an answer fixed point before answers are replayed.
-Components with a negative dependency retain guarded ordinary resolution,
-because positive least-fixed-point tabling does not define unstratified
-negation. Nonrecursive groups use indexed, depth-first resolution.
+The program loader analyzes predicate dependencies and recursion so the solver
+can choose semantics-preserving indexes and fast paths. That analysis does
+**not** decide whether a predicate is tabled. Ordinary predicates—including
+recursive ones—use indexed, depth-first Prolog resolution unless their source
+explicitly declares `:- table p/n.`.
 
-For calls with ground structural input, tabled answers can be reused within a
-solver run. The engine infers common structurally decreasing inputs from
-recursive heads. Fully open calls and calls whose inferred structural input is
-not ground may remain under ordinary resolution rather than forcing a possibly
-infinite relation into a table. This changes control, not declarative meaning.
+An explicitly tabled positive recursive predicate is coordinated through an
+answer table: recurring calls consume answers already found, new answers are
+recorded, and evaluation continues toward a fixed point. For eligible large,
+finite, function-free Datalog components, EyeProlog may represent that declared
+table as one shared most-general relation or an indexed least model. For other
+declared tables the engine may infer structurally bound input positions to
+improve table reuse. These are implementation choices inside an explicit table
+declaration; they never opt an undeclared predicate into tabling.
+
+Ordinary `\+/1` remains ISO-style negation as failure. The separate `tnot/1`
+extension explicitly requests well-founded evaluation for eligible finite,
+range-restricted Datalog dependencies. Strict ISO mode exposes neither `table`
+nor `tnot/1`.
 
 #### Query execution
 
@@ -5872,8 +5880,8 @@ answers. The host:
 7. prints each answer and, only when requested, its `why/2` explanation.
 
 Goal selection affects host execution rather than the program's logical meaning.
-One goal's answers are not asserted for later goals, although internal
-tables may be reused during the solver run. For stable output, queries for
+One goal's answers are not asserted for later goals, although explicitly
+declared tables may be reused during the solver run. For stable output, queries for
 known predicates are grouped by the source order in which their predicate
 groups first appear; goals within one group retain their supplied order.
 Queries for predicates with no group follow the known groups.
@@ -6270,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
@@ -6288,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`,
@@ -6360,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 |
@@ -7475,7 +7484,7 @@ recursion as one technique.
 | [Deep taxonomy: 10](https://github.com/eyereasoner/eyeprolog/blob/main/examples/deep-taxonomy-10.pl) | A small generated hierarchy is readable by hand and establishes the benchmark shape. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/deep-taxonomy-10.pl) |
 | [Deep Taxonomy 100](https://github.com/eyereasoner/eyeprolog/blob/main/examples/deep-taxonomy-100.pl) | A 100-step taxonomy chain that exercises deep recursive closure and side-label derivation. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/deep-taxonomy-100.pl) |
 | [Deep taxonomy: 1,000](https://github.com/eyereasoner/eyeprolog/blob/main/examples/deep-taxonomy-1000.pl) | The same logical theory tests indexing and recursive closure at a realistic depth. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/deep-taxonomy-1000.pl) |
-| [Deep Taxonomy 10000](https://github.com/eyereasoner/eyeprolog/blob/main/examples/deep-taxonomy-10000.pl) | A 10,000-step taxonomy chain used as a large-depth tabling and closure stress test. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/deep-taxonomy-10000.pl) |
+| [Deep Taxonomy 10000](https://github.com/eyereasoner/eyeprolog/blob/main/examples/deep-taxonomy-10000.pl) | A 10,000-step taxonomy chain used as a large-depth ordinary-recursion and closure stress test. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/deep-taxonomy-10000.pl) |
 | [Deep taxonomy: 100,000](https://github.com/eyereasoner/eyeprolog/blob/main/examples/deep-taxonomy-100000.pl) | A stress case separates semantic simplicity from implementation scale. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/deep-taxonomy-100000.pl) |
 | [Family cousins](https://github.com/eyereasoner/eyeprolog/blob/main/examples/family-cousins.pl) | Several relational joins derive kinship beyond a simple transitive closure. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/family-cousins.pl) |
 | [Graph reachability](https://github.com/eyereasoner/eyeprolog/blob/main/examples/graph-reachability.pl) | A visited list bounds cyclic traversal and makes explicit negative test cases finite. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/graph-reachability.pl) · [proof](https://github.com/eyereasoner/eyeprolog/blob/main/examples/proof/graph-reachability.pl) |

package/why-eyeprolog.md

@@ -143,12 +143,21 @@ 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)`.
 
+Library convenience is explicit at the profile boundary too. Outside strict ISO
+mode, an unresolved unqualified predicate may autoload its unique provider from
+the bundled `src/lib/` modules after program definitions, standard built-ins,
+and explicit imports have had precedence. `--no-autoload` disables this
+convenience, and strict ISO mode disables it unconditionally. Autoloading happens
+after parsing, so libraries that introduce operators still require an explicit
+`use_module/1-2` before that syntax is read.
+
 Definite clause grammars follow the ISO Part 3 difference-list model. Internal
 fast paths make deep finite sequence processing economical while preserving
 relational modes. The checked