eyeprolog 1.5.4 → 1.5.6

package/README.md

@@ -56,14 +56,10 @@ printf 'human(socrates).\nmortal(X) :- human(X).\n' |
   npx --yes eyeprolog --proof --goal 'mortal(socrates)' -
 ```
 
-## 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. 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.
+## Eyelet forward rules (`:+`)
+Normal mode executes top-level `Conclusion :+ Premise` rules through the bundled Prolog `library(eyelet)` driver when no explicit `-g/--goal` is supplied. `true :+ Goal` prints answers and `false :+ Goal` emits a `fuse/1`; JavaScript `run()` follows the same rule. The module exports `:+`, `stable/1`, and `becomes/2`, and implements rule selection, fixed-point rounds, skolemization, state replacement, and duplicate suppression in Prolog. JavaScript only loads the driver and provides private mutability/output adapters. 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.4",
+  "version": "1.5.6",
   "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

@@ -1,9 +1,9 @@
 // Shared goal preparation and execution for the CLI and embedding API.
-import { ATOM, COMPOUND, NUMBER, VAR, Env, atom, compound, copyResolved, flattenConjunction, numberTerm, termIsGround, variable } from './term.js';
+import { ATOM, COMPOUND, NUMBER, VAR, Env, compound, copyResolved, termIsGround, variable } from './term.js';
 import { parseGoalText } from './parser.js';
 import { HaltSignal, PrologError } from './iso.js';
 import { formatTermForWrite } from './write.js';
-import { modulePredicateKey } from './program-indexing.js';
+import { loadBundledProgramLibrary } from './program.js';
 
 export function normalizeGoals(requestedGoals, solver) {
   return requestedGoals.map((requestedGoal) => {
@@ -57,14 +57,11 @@ function currentWriteOptions(program, solver) {
 }
 
 
-// Native EyeProlog forward-rule extension.
+// Eyelet forward-rule bootstrap.
 //
-// Source terms `Conclusion :+ Premise` remain ordinary :+/2 clauses so they
-// can be inspected and even derived by Prolog code.  The closure driver below
-// replaces Eyelet's Prolog-level meta-interpreter: it asks the solver directly
-// for (: +)/2 rule instances whose premises hold, materializes novel
-// conclusions, and repeats to a fixed point.  Query and fuse rules retain the
-// Eyelet conventions `true :+ Goal` and `false :+ Goal`.
+// The :+/2 fixed-point semantics live in library(eyelet).  This JavaScript
+// adapter only ensures that library is loaded, invokes its Prolog driver, and
+// converts the driver's recorded answer/fuse events to the public callbacks.
 export function hasForwardRules(program) {
   return program.findGroup(':+', 2) != null;
 }
@@ -74,293 +71,65 @@ export function executeForwardRules(program, solver, {
   onFuse = () => {},
   onDiagnostic = () => {},
 } = {}) {
-  const group = program.findGroup(':+', 2);
-  if (group == null) return { haltCode: null, rounds: 0, derived: 0 };
+  if (!hasForwardRules(program)) return { haltCode: null, rounds: 0, derived: 0 };
 
+  // Load the Prolog driver without importing a bootstrap-only predicate into
+  // user or widening library(eyelet)'s public API.
+  loadBundledProgramLibrary(program, 'eyelet');
   solver.runInitializations();
-  makeGroupDynamic(program, group);
-  predeclareForwardTerms(program, solver, group);
-  setSingletonFact(program, 'closure', [numberTerm(0)]);
-  setSingletonFact(program, 'limit', [numberTerm(-1)]);
 
-  const seenAnswers = new Set();
-  let rounds = 0;
-  let derived = 0;
-  let haltCode = null;
-
-  // Query-only Eyelet files are common and should be as cheap as ordinary
-  // EyeProlog -g goals.  Avoid routing their premises through a variable
-  // call/1 and :+/2 clause-selection meta path.  This is especially important
-  // for deep deterministic workloads such as Ackermann and the evolutionary
-  // example.
-  if (forwardGroupIsPlainQueries(group)) {
-    for (const clause of group.clauses) {
-      const conclusion = clause.head.args[0];
-      const premise = clause.head.args[1];
-      const child = solver.cloneForInnerGoal(Infinity);
-      try {
-        for (const env of child.solve([premise], new Env(), 0)) {
-          const resolvedPremise = copyResolved(premise, env);
-          if (isAtomNamed(conclusion, 'false')) {
-            const fuse = compound('fuse', [resolvedPremise]);
-            onFuse(forwardLine(fuse, program, solver), fuse);
-            haltCode = 2;
-            break;
-          }
-          const line = forwardLine(resolvedPremise, program, solver);
-          if (!seenAnswers.has(line)) {
-            seenAnswers.add(line);
-            onAnswer(line, resolvedPremise);
-          }
-        }
-      } finally {
-        solver.absorbStatsFrom(child);
-      }
-      if (haltCode != null) break;
+  const roundsVar = variable('\u0000eyeletRounds');
+  const derivedVar = variable('\u0000eyeletDerived');
+  const statusVar = variable('\u0000eyeletStatus');
+  const driver = compound('eyelet_run', [roundsVar, derivedVar, statusVar]);
+  driver.module = 'eyelet';
+
+  let resultEnv = null;
+  const previousEventHandler = solver.eyeletEventHandler;
+  solver.eyeletEventHandler = (kind, term) => {
+    if (kind === 'answer') {
+      onAnswer(forwardLine(term, program, solver), term);
+    } else if (kind === 'fuse') {
+      const fuse = compound('fuse', [term]);
+      onFuse(forwardLine(fuse, program, solver), fuse);
     }
-    return { haltCode, rounds: 1, derived: 0 };
+  };
+  const iterator = solver.solve([driver], new Env(), 0);
+  try {
+    const result = iterator.next();
+    if (!result.done) resultEnv = result.value;
+  } finally {
+    try { iterator.return?.(); } catch (_) { /* best effort */ }
+    solver.eyeletEventHandler = previousEventHandler;
   }
+  if (resultEnv == null) return { haltCode: null, rounds: 0, derived: 0 };
 
-  while (true) {
-    rounds++;
-    const conc = variable(`\u0000forwardConc${rounds}`);
-    const prem = variable(`\u0000forwardPrem${rounds}`);
-    const selector = compound(':+', [conc, prem]);
-    const invocation = compound('call', [prem]);
-    let changed = false;
-
-    const child = solver.cloneForInnerGoal(Infinity);
-    try {
-      for (const env of child.solve([selector, invocation], new Env(), 0)) {
-        const resolvedPremise = copyResolved(prem, env);
-        let resolvedConclusion = copyResolved(conc, env);
-
-        if (isAtomNamed(resolvedConclusion, 'true')) {
-          const line = forwardLine(resolvedPremise, program, solver);
-          if (!seenAnswers.has(line)) {
-            seenAnswers.add(line);
-            onAnswer(line, resolvedPremise);
-          }
-          continue;
-        }
-
-        if (isAtomNamed(resolvedConclusion, 'false')) {
-          const fuse = compound('fuse', [resolvedPremise]);
-          const line = forwardLine(fuse, program, solver);
-          onFuse(line, fuse);
-          haltCode = 2;
-          break;
-        }
-
-        // A derived rule keeps its variables universally quantified.  Ordinary
-        // derived facts use Eyelet's historical existential convention: any
-        // conclusion-only variables become sk_0, sk_1, ... before assertion.
-        if (!isForwardRuleTerm(resolvedConclusion)) {
-          resolvedConclusion = skolemizeForwardConclusion(resolvedConclusion);
-        }
-
-        for (const fact of forwardConjuncts(resolvedConclusion)) {
-          if (isAtomNamed(fact, 'true') || isAtomNamed(fact, 'false')) continue;
-          makePredicateDynamic(program, fact);
-          if (!goalHasSolution(solver, fact)) {
-            insertForwardFact(program, fact);
-            derived++;
-            changed = true;
-          }
-        }
-      }
-    } finally {
-      solver.absorbStatsFrom(child);
-    }
-
-    if (haltCode != null) break;
-
-    if (changed) continue;
-
-    const closure = singletonInteger(program, 'closure', 0);
-    const limit = singletonInteger(program, 'limit', -1);
-    if (closure < limit) {
-      setSingletonFact(program, 'closure', [numberTerm(closure + 1)]);
-      continue;
-    }
-    break;
-  }
+  const rounds = resolvedInteger(roundsVar, resultEnv, 0);
+  const derived = resolvedInteger(derivedVar, resultEnv, 0);
+  const status = copyResolved(statusVar, resultEnv);
+  const haltCode = status?.type === ATOM && status.name === 'fuse' ? 2 : null;
 
+  // Kept for source compatibility with the existing callback shape. The
+  // Prolog driver currently has no diagnostic event kind.
+  void onDiagnostic;
   return { haltCode, rounds, derived };
 }
 
-
-function forwardGroupIsPlainQueries(group) {
-  return group.clauses.length > 0 && group.clauses.every((clause) => {
-    if ((clause.body?.length ?? 0) !== 0) return false;
-    const head = clause.head;
-    if (head?.type !== COMPOUND || head.name !== ':+' || head.arity !== 2) return false;
-    return isAtomNamed(head.args[0], 'true') || isAtomNamed(head.args[0], 'false');
-  });
+function resolvedInteger(term, env, fallback) {
+  const value = copyResolved(term, env);
+  return value?.type === NUMBER && /^-?\d+$/.test(value.name) ? Number(value.name) : fallback;
 }
 
 function forwardLine(term, program, solver) {
   return `${formatTermForWrite(term, new Env(), {
-    // Eyelet historically used portray_clause/2.  Keep character lists as
-    // list syntax here rather than collapsing them to strings according to
-    // the ambient double_quotes flag.
+    // Eyelet historically used portray_clause/2. Keep character lists as list
+    // syntax rather than collapsing them according to double_quotes.
     doubleQuotes: null,
     operators: [...program.operators.values()],
     quoted: true,
     compact: true,
     minimalOperatorSpacing: true,
-    // Match portray_clause/2 more closely for Eyelet compatibility: current
-    // operator atoms are legal unquoted arguments/list elements, and anonymous
-    // source variables should be rendered with stable generated names rather
-    // than their internal parser identifiers.
     operatorAtomsAsArgs: true,
     generateVariableNames: true,
   })}.\n`;
 }
-
-function isAtomNamed(term, name) {
-  return term?.type === ATOM && term.name === name;
-}
-
-function isForwardRuleTerm(term) {
-  return term?.type === COMPOUND && term.name === ':+' && term.arity === 2;
-}
-
-function forwardConjuncts(term) {
-  if (isAtomNamed(term, 'true') || isAtomNamed(term, 'false')) return [];
-  return flattenConjunction(term);
-}
-
-function skolemizeForwardConclusion(term) {
-  const variables = new Map();
-  const copy = (current) => {
-    if (current.type === VAR) {
-      let skolem = variables.get(current.name);
-      if (skolem == null) {
-        skolem = atom(`sk_${variables.size}`);
-        variables.set(current.name, skolem);
-      }
-      return skolem;
-    }
-    if (current.type !== COMPOUND) return current;
-    const result = compound(current.name, current.args.map(copy));
-    if (current.module != null) result.module = current.module;
-    return result;
-  };
-  return copy(term);
-}
-
-function makeGroupDynamic(program, group) {
-  group.dynamic = true;
-  program.dynamicPredicates.add(modulePredicateKey(group.module ?? 'user', group.name, group.arity));
-  program.mutable = true;
-}
-
-function makePredicateDynamic(program, term) {
-  if (term?.type !== ATOM && term?.type !== COMPOUND) return;
-  if (term.type === COMPOUND && term.name === ',' && term.arity === 2) {
-    makePredicateDynamic(program, term.args[0]);
-    makePredicateDynamic(program, term.args[1]);
-    return;
-  }
-  if (isForwardRuleTerm(term)) {
-    const group = program.findGroup(':+', 2, term.module ?? 'user') ?? program.ensureDynamicGroup(':+', 2, term.module ?? 'user');
-    makeGroupDynamic(program, group);
-    makePredicateDynamic(program, term.args[0]);
-    return;
-  }
-  if (['true', 'false', '!'].includes(term.name)) return;
-  const module = term.module ?? 'user';
-  const group = program.findGroup(term.name, term.arity, module) ?? program.ensureDynamicGroup(term.name, term.arity, module);
-  makeGroupDynamic(program, group);
-}
-
-function predeclareForwardTerms(program, solver, group) {
-  for (const clause of group.clauses) {
-    const head = clause.head;
-    if (head?.type !== COMPOUND || head.name !== ':+' || head.arity !== 2) continue;
-    // Conclusions may later be asserted, while premise-only predicates need an
-    // empty procedure so a not-yet-derived relation fails rather than raising
-    // existence_error(procedure), matching Eyelet's former dynify/1 step.
-    predeclareConclusionTerm(program, solver, head.args[0]);
-    predeclareUnknownTerm(program, solver, head.args[1]);
-    for (const bodyGoal of clause.body ?? []) predeclareUnknownTerm(program, solver, bodyGoal);
-  }
-}
-
-function predeclareConclusionTerm(program, solver, term) {
-  if (term?.type === COMPOUND && term.name === ',' && term.arity === 2) {
-    predeclareConclusionTerm(program, solver, term.args[0]);
-    predeclareConclusionTerm(program, solver, term.args[1]);
-    return;
-  }
-  if (isForwardRuleTerm(term)) {
-    makePredicateDynamic(program, term);
-    predeclareConclusionTerm(program, solver, term.args[0]);
-    predeclareUnknownTerm(program, solver, term.args[1]);
-    return;
-  }
-  if (term?.type === ATOM || term?.type === COMPOUND) makePredicateDynamic(program, term);
-}
-
-function predeclareUnknownTerm(program, solver, term) {
-  if (term?.type !== ATOM && term?.type !== COMPOUND) return;
-  if (term.type === COMPOUND) {
-    for (const arg of term.args) predeclareUnknownTerm(program, solver, arg);
-  }
-  if (['true', 'false', '!'].includes(term.name)) return;
-  if (solver.registry.get(term.name, term.arity) != null) return;
-  if (program.findGroup(term.name, term.arity, term.module ?? 'user') != null) return;
-  const group = program.ensureDynamicGroup(term.name, term.arity, term.module ?? 'user');
-  makeGroupDynamic(program, group);
-}
-
-function goalHasSolution(solver, goal) {
-  const child = solver.cloneForInnerGoal(1);
-  const iterator = child.solve([goal], new Env(), 0);
-  try {
-    const result = iterator.next();
-    return !result.done;
-  } finally {
-    try { iterator.return?.(); } catch (_) { /* best effort */ }
-    solver.absorbStatsFrom(child);
-  }
-}
-
-function insertForwardFact(program, fact) {
-  makePredicateDynamic(program, fact);
-  program.insertDynamicClause({
-    head: fact,
-    module: fact.module ?? 'user',
-    body: [],
-  }, false);
-}
-
-function setSingletonFact(program, name, args, keyed = false) {
-  const module = 'user';
-  let group = program.findGroup(name, args.length, module);
-  if (group == null) group = program.ensureDynamicGroup(name, args.length, module);
-  makeGroupDynamic(program, group);
-
-  if (keyed && args.length > 0) {
-    const key = args[0]?.name;
-    for (const clause of [...group.clauses]) {
-      if (clause.head?.args?.[0]?.name === key) program.removeDynamicClause(group, clause);
-    }
-  } else {
-    for (const clause of [...group.clauses]) program.removeDynamicClause(group, clause);
-  }
-  program.insertDynamicClause({ head: compound(name, args), module, body: [] }, false);
-}
-
-function singletonInteger(program, name, fallback) {
-  const group = program.findGroup(name, 1, 'user');
-  if (group == null) return fallback;
-  for (let i = group.clauses.length - 1; i >= 0; i--) {
-    const arg = group.clauses[i].head?.args?.[0];
-    if (arg?.type === NUMBER && /^-?\d+$/.test(arg.name)) return Number(arg.name);
-  }
-  return fallback;
-}
-
-

package/src/lib/eyelet.pl

@@ -1,43 +1,292 @@
-% Eyelet forward-reasoning support for EyeProlog.
+% Eyelet forward reasoning 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.
+% The fixed-point driver lives here in Prolog. JavaScript only bootstraps this
+% module and adapts the recorded answer/fuse events to the embedding callbacks.
 
-:- module(eyelet, [op(1200, xfx, :+), stable/1, becomes/2]).
+:- module(eyelet, [
+    op(1200, xfx, :+),
+    stable/1,
+    becomes/2
+]).
 
-:- use_module(library(iso_ext), [forall/2]).
-:- use_module(library(lists), [member/2]).
+:- use_module(library(iso_ext), [variant/2]).
 
 :- meta_predicate(becomes(0, 0)).
 
+:- dynamic(eyelet_reported/1).
+:- dynamic(eyelet_changed/0).
+:- dynamic(eyelet_fused/0).
+:- dynamic(eyelet_derived/1).
+
+% eyelet_run(-Rounds, -Derived, -Status)
+% Run the user module's :+/2 rules to a fixed point. Status is ok or fuse.
+% Answer/fuse terms are emitted through a tiny host callback adapter.
+eyelet_run(Rounds, Derived, Status) :-
+    eyelet_setup,
+    (   plain_query_program
+    ->  run_plain_queries,
+        Rounds = 1
+    ;   eyelet_loop(0, Rounds)
+    ),
+    ( eyelet_fused -> Status = fuse ; Status = ok ),
+    eyelet_derived(Derived).
+
+% Preparation is structural: inspect clauses instead of executing their bodies.
+% dynify/1 also makes existing user predicates mutable, which is required by
+% conclusions and becomes/2, while leaving imported and builtin predicates alone.
+eyelet_setup :-
+    retractall(eyelet_reported(_)),
+    retractall(eyelet_changed),
+    retractall(eyelet_fused),
+    retractall(eyelet_derived(_)),
+    assertz(eyelet_derived(0)),
+    user:eyeprolog__dynify((:+)/2),
+    user:eyeprolog__dynify(closure/1),
+    user:eyeprolog__dynify(limit/1),
+    user:retractall(closure(_)),
+    user:retractall(limit(_)),
+    user:assertz(closure(0)),
+    user:assertz(limit(-1)),
+    prepare_rules.
+
+prepare_rules :-
+    (   user:clause((Conc :+ Prem), Body),
+        dynify_goal(Conc),
+        dynify_goal(Prem),
+        dynify_goal(Body),
+        fail
+    ;   true
+    ).
+
+% Query-only Eyelet files are common. Detect them from clause heads and execute
+% their premises once instead of entering the fixed-point loop.
+plain_query_program :-
+    \+ ( user:clause((Conc :+ _), _), Conc \== true, Conc \== false ).
+
+run_plain_queries :-
+    (   user:(Conc :+ Prem),
+        user:Prem,
+        process_control_conclusion(Conc, Prem, 1),
+        ( eyelet_fused -> ! ; fail )
+    ;   true
+    ).
+
+% Iterate until a round adds no new conclusion. stable/1 can request additional
+% closure levels; each requested level advances only after a quiescent round.
+eyelet_loop(Round0, Round) :-
+    Round1 is Round0 + 1,
+    retractall(eyelet_changed),
+    run_round(Round1),
+    (   eyelet_fused
+    ->  Round = Round1
+    ;   eyelet_changed
+    ->  eyelet_loop(Round1, Round)
+    ;   advance_closure
+    ->  eyelet_loop(Round1, Round)
+    ;   Round = Round1
+    ).
+
+run_round(Round) :-
+    (   user:(Conc :+ Prem),
+        user:Prem,
+        process_conclusion(Conc, Prem, Round),
+        ( eyelet_fused -> ! ; fail )
+    ;   true
+    ).
+
+process_conclusion(Conc, Prem, Round) :-
+    (   Conc == true
+    ->  report_answer(Prem)
+    ;   Conc == false
+    ->  report_fuse(Prem),
+        mark_fused
+    ;   prepare_conclusion(Conc, Prepared),
+        assert_conj(Prepared)
+    ).
+
+process_control_conclusion(Conc, Prem, _) :-
+    (   Conc == true
+    ->  report_answer(Prem)
+    ;   Conc == false
+    ->  report_fuse(Prem),
+        mark_fused
+    ;   true
+    ).
+
+report_answer(Prem) :-
+    (   already_reported(Prem)
+    ->  true
+    ;   copy_term(Prem, Copy),
+        assertz(eyelet_reported(Copy)),
+        user:eyeprolog__eyelet_emit(answer, Prem)
+    ).
+
+% Ground answers use the dynamic predicate's ground index. Only residual-variable
+% answers need the more expensive variant scan.
+already_reported(Prem) :-
+    term_variables(Prem, Vars),
+    (   Vars == []
+    ->  eyelet_reported(Prem)
+    ;   eyelet_reported(Seen),
+        variant(Prem, Seen)
+    ),
+    !.
+
+report_fuse(Prem) :-
+    user:eyeprolog__eyelet_emit(fuse, Prem).
+
+mark_fused :-
+    ( eyelet_fused -> true ; assertz(eyelet_fused) ).
+
+prepare_conclusion(Conc, Conc) :-
+    is_forward_rule(Conc),
+    !.
+prepare_conclusion(Conc, Conc) :-
+    skolemize(Conc, 0, _).
+
+is_forward_rule(Term) :-
+    nonvar(Term),
+    Term = (_ :+ _).
+
+% Assert each new conjunct. Ordinary conclusions are considered already known
+% when they are provable; a derived :+/2 rule is considered known only when an
+% identical fact-clause already exists, so guarded source rules are not confused
+% with a newly derived unconditional rule.
+assert_conj(true) :- !.
+assert_conj(false) :- !.
+assert_conj((A, B)) :-
+    !,
+    assert_conj(A),
+    assert_conj(B).
+assert_conj(Goal) :-
+    dynify_goal(Goal),
+    (   known_conclusion(Goal)
+    ->  true
+    ;   user:assertz(Goal),
+        mark_changed
+    ).
+
+known_conclusion(Goal) :-
+    is_forward_rule(Goal),
+    !,
+    user:clause(Goal, true).
+known_conclusion(Goal) :-
+    user:Goal.
+
+mark_changed :-
+    ( eyelet_changed -> true ; assertz(eyelet_changed) ),
+    retract(eyelet_derived(N)),
+    N1 is N + 1,
+    assertz(eyelet_derived(N1)).
+
+advance_closure :-
+    user:closure(Closure),
+    user:limit(Limit),
+    Closure < Limit,
+    NewClosure is Closure + 1,
+    user:retract(closure(Closure)),
+    user:assertz(closure(NewClosure)).
+
+% skolemize(+Term, +N0, -N)
+% Replace remaining conclusion variables with sk_0, sk_1, ... . Derived :+/2
+% rules skip this step so their variables remain universally quantified.
+skolemize(Term, N0, N) :-
+    term_variables(Term, Vars),
+    skolemize_vars(Vars, N0, N).
+
+skolemize_vars([], N, N).
+skolemize_vars([Sk|Vars], N0, N) :-
+    number_chars(N0, Digits),
+    atom_chars(Number, Digits),
+    atom_concat(sk_, Number, Sk),
+    N1 is N0 + 1,
+    skolemize_vars(Vars, N1, N).
+
 % 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.
+% Fail until the requested closure level has been reached. Asking for a higher
+% level raises the target; the driver advances it only at a quiescent round.
 stable(Level) :-
-    call(user:limit(Limit)),
+    user:limit(Limit),
     (   Limit < Level
     ->  user:retract(limit(Limit)),
         user:assertz(limit(Level))
     ;   true
     ),
-    call(user:closure(Closure)),
+    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.
+% Linear implication over dynamic state. dynify/1 first makes existing source
+% predicates mutable, so callers no longer need a separate dynamic/1 directive.
 becomes(From, To) :-
-    catch(call(user:From), _, fail),
+    dynify_goal(From),
+    dynify_goal(To),
+    catch(user:From, _, fail),
     conj_list(From, Old),
-    forall(member(Clause, Old), user:retract(Clause)),
+    retract_conj(Old),
     conj_list(To, New),
-    forall(member(Clause, New), user:assertz(Clause)).
+    assert_conj_list(New).
 
-conj_list(true, []).
-conj_list(Goal, [Goal]) :-
-    Goal \= (_, _),
-    Goal \= false,
+retract_conj([]).
+retract_conj([Clause|Clauses]) :-
+    user:retract(Clause),
+    retract_conj(Clauses).
+
+assert_conj_list([]).
+assert_conj_list([Clause|Clauses]) :-
+    user:assertz(Clause),
+    assert_conj_list(Clauses).
+
+% Flatten conjunctions in either association direction without append/3.
+conj_list(Goal, List) :-
+    conj_list(Goal, List, []).
+
+conj_list(true, Tail, Tail) :- !.
+conj_list(false, _, _) :- !, fail.
+conj_list((A, B), List, Tail) :-
+    !,
+    conj_list(A, List, Rest),
+    conj_list(B, Rest, Tail).
+conj_list(Goal, [Goal|Tail], Tail).
+
+% Prepare a callable goal and recursively inspect compound arguments. Atomic
+% arguments are data, but an atom in callable position denotes a 0-arity
+% predicate and therefore needs an empty dynamic procedure when it is unknown.
+dynify_goal(Term) :-
+    var(Term),
+    !.
+dynify_goal(Term) :-
+    atom(Term),
+    !,
+    user:eyeprolog__dynify(Term/0).
+dynify_goal(Term) :-
+    atomic(Term),
     !.
-conj_list((A, B), [A|Rest]) :-
-    conj_list(B, Rest).
+dynify_goal(Term) :-
+    dynify_term(Term).
+
+% Recursively prepare callable shapes embedded in compound arguments. The
+% private host primitive only mutates direct user procedures; imports, builtins,
+% and control constructs are left untouched.
+dynify_term(Term) :-
+    var(Term),
+    !.
+dynify_term(Term) :-
+    atomic(Term),
+    !.
+dynify_term([]) :-
+    !.
+dynify_term([Head|Tail]) :-
+    !,
+    dynify_term(Head),
+    dynify_term(Tail).
+dynify_term(Term) :-
+    functor(Term, Name, Arity),
+    user:eyeprolog__dynify(Name/Arity),
+    Term =.. [_|Args],
+    dynify_list(Args).
+
+dynify_list([]).
+dynify_list([Term|Terms]) :-
+    dynify_term(Term),
+    dynify_list(Terms).

package/src/parser.js

@@ -159,7 +159,7 @@ export const ISO_OPERATOR_DEFINITIONS = [
 export const PART3_OPERATOR_DEFINITIONS = [
   [1105, 'xfy', '|'],
   // EyeProlog forward-rule extension.  A top-level Conclusion :+ Premise is
-  // executed by the native closure driver when no explicit CLI goal is given.
+  // executed by library(eyelet)'s Prolog closure driver when no explicit CLI goal is given.
   [1200, 'xfx', ':+'],
   // Tabling is explicit in the normal EyeProlog profile. Make the common
   // `:- table p/n.` declaration available without requiring a library import.

package/src/program.js

@@ -1030,6 +1030,43 @@ function hybridFastSource(source, options) {
 // that phase, so extend the existing instance with the same canonical interop
 // imports before solving those goals. Keeping this here lets both paths share
 // the dependency analysis and module-loading rules.
+// Load one bundled library module into an already-built Program without
+// importing its public predicates into user. This is useful for host bootstraps
+// that call a module-private Prolog entry point while keeping the user-facing
+// module export list unchanged.
+export function loadBundledProgramLibrary(program, name, options = {}) {
+  if (program.modules.has(name)) return program;
+  const operatorState = createParserOperatorState(
+    [...program.operators.values()],
+    false,
+    { isoStrict: program.strictIso },
+  );
+  const parserFlagState = {
+    doubleQuotes: program.doubleQuotes ?? options.doubleQuotes ?? 'chars',
+    charConversion: 'on',
+    charConversions: new Map(),
+  };
+  const builder = new ProgramBuilder({ ...options, isoStrict: program.strictIso }, program);
+  const loadedModules = new Set([...program.modules.keys()].filter((module) => module !== 'user'));
+  const ensured = new Set();
+  const designation = compound('library', [atom(name)]);
+  const loaded = readModuleSource(designation, {
+    ...options,
+    isoStrict: program.strictIso,
+    operatorState,
+    parserFlagState,
+  });
+  const childContext = { module: loaded.name };
+  if (!loadSourceIntoBuilder(
+    builder, loaded.text, loaded.options, ensured, loadedModules, false, childContext,
+  )) {
+    throw new Error(`could not load library(${name})`);
+  }
+  program.noteMutation(false);
+  builder.finish();
+  return program;
+}
+
 export function autoloadProgramGoals(program, inputs, options = {}) {
   if (inputs == null || (Array.isArray(inputs) && inputs.length === 0)) return program;
   const operatorState = createParserOperatorState(
@@ -1131,7 +1168,7 @@ 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
+    // Eyelet 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

package/src/scryer-compat.js

@@ -4,9 +4,77 @@
 // backtrackable blackboard lives in Env so ordinary Prolog choice points undo
 // writes automatically.
 
-import { ATOM, COMPOUND, NUMBER, STRING, VAR, atom, compound, deref, listFromItems, numberTerm, numberTextFromDouble, unify } from './term.js';
+import { ATOM, COMPOUND, NUMBER, STRING, VAR, atom, compound, copyResolved, deref, listFromItems, numberTerm, numberTextFromDouble, unify } from './term.js';
 import { PrologError } from './errors.js';
 import { formatTermForWrite } from './write.js';
+import { modulePredicateKey, rebuildGroupIndexes } from './program-indexing.js';
+
+
+const NON_PROCEDURE_CONTROL = new Set([',/2', ';/2', '->/2', ':/2', '!/0', 'true/0', 'false/0', 'fail/0']);
+
+function dynifyIndicator(term, env) {
+  const indicator = deref(term, env);
+  if (indicator.type === VAR) throw new PrologError('instantiation_error');
+  if (indicator.type !== COMPOUND || indicator.name !== '/' || indicator.arity !== 2) {
+    throw new PrologError('type_error(predicate_indicator)', indicator);
+  }
+  const name = deref(indicator.args[0], env);
+  const arity = deref(indicator.args[1], env);
+  if (name.type === VAR || arity.type === VAR) throw new PrologError('instantiation_error');
+  if (name.type !== ATOM || arity.type !== NUMBER || !/^\d+$/.test(arity.name)) {
+    throw new PrologError('type_error(predicate_indicator)', indicator);
+  }
+  const value = BigInt(arity.name);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new PrologError('representation_error(max_arity)');
+  return { name: name.name, arity: Number(value), indicator };
+}
+
+// Private support for declarative libraries that need to prepare user predicates
+// for database updates. Unlike assertz/retract probes, this can make an existing
+// source predicate dynamic without changing its clauses, and it leaves imported
+// or builtin procedures alone instead of accidentally shadowing them.
+function* dynifyBuiltin({ solver, goal, env }) {
+  const target = dynifyIndicator(goal.args[0], env);
+  const module = goal.module ?? 'user';
+  const indicatorKey = `${target.name}/${target.arity}`;
+  if (NON_PROCEDURE_CONTROL.has(indicatorKey)) {
+    yield env;
+    return;
+  }
+
+  const directKey = modulePredicateKey(module, target.name, target.arity);
+  let group = solver.program.groups.get(directKey) ?? null;
+  if (group != null) {
+    if (!group.dynamic) {
+      group.dynamic = true;
+      solver.program.dynamicPredicates.add(directKey);
+      solver.program.mutable = true;
+      rebuildGroupIndexes(group);
+      solver.program.noteMutation(group.clauses.some((clause) => (clause.body?.length ?? 0) > 0));
+    }
+    yield env;
+    return;
+  }
+
+  if (solver.registry.get(target.name, target.arity) != null ||
+      solver.program.moduleImports.get(module)?.has(indicatorKey) === true) {
+    yield env;
+    return;
+  }
+
+  group = solver.program.ensureDynamicGroup(target.name, target.arity, module);
+  group.dynamic = true;
+  yield env;
+}
+
+function* eyeletEmitBuiltin({ solver, goal, env }) {
+  const kind = deref(goal.args[0], env);
+  if (kind.type === VAR) throw new PrologError('instantiation_error');
+  if (kind.type !== ATOM) throw new PrologError('type_error(atom)', kind);
+  const term = copyResolved(goal.args[1], env);
+  solver.eyeletEventHandler?.(kind.name, term);
+  yield env;
+}
 
 function blackboardKey(term, env) {
   const value = deref(term, env);
@@ -255,6 +323,8 @@ function* portrayClauseBuiltin({ solver, goal, env }) {
 
 export const scryerCompatibilityBuiltins = {
   register(registry) {
+    registry.add('eyeprolog__dynify', 1, dynifyBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('eyeprolog__eyelet_emit', 2, eyeletEmitBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__bb_get', 2, bbGetBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__bb_b_put', 2, bbPutBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__bb_global_get', 2, bbGlobalGetBuiltin, { deterministic: true, eyePrologLibrary: true });

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

@@ -4806,7 +4806,7 @@ ${profile}`;
         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, 'EyeProlog normal mode also accepts `:+`', 'Eyelet 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');
@@ -5464,7 +5464,7 @@ function apiCases() {
       },
     },
     {
-      name: 'run executes native forward rules when no explicit goal is supplied',
+      name: 'run executes Prolog Eyelet forward rules when no explicit goal is supplied',
       run: () => {
         const result = run('seed(a).\nseen(X) :+ seed(X).\ntrue :+ seen(X).\n');
         assertEqual(result.stdout, 'seen(a).\n', 'forward stdout');
@@ -5472,10 +5472,9 @@ function apiCases() {
       },
     },
     {
-      name: 'native forward rules autoload library(eyelet) helpers from :+ premises',
+      name: 'Eyelet forward rules autoload library helpers and dynify source state',
       run: () => {
         const result = run(`
-:- dynamic(state/1).
 state(a).
 changed :+ becomes(state(a), state(b)).
 seed :+ state(b).
@@ -5485,6 +5484,21 @@ true :+ ready.
         assertEqual(result.stdout, 'ready.\n', 'forward helper stdout');
       },
     },
+    {
+      name: 'Eyelet false conclusions emit a fuse and halt status 2',
+      run: () => {
+        const result = run('bad(a).\nfalse :+ bad(X).\n');
+        assertEqual(result.stdout, 'fuse(bad(a)).\n', 'fuse stdout');
+        assertEqual(result.haltCode, 2, 'fuse halt code');
+      },
+    },
+    {
+      name: 'Eyelet ordinary conclusions skolemize conclusion-only variables',
+      run: () => {
+        const result = run('seed(a).\npair(X, Y) :+ seed(X).\ntrue :+ pair(X, Y).\n');
+        assertEqual(result.stdout, 'pair(a,sk_0).\n', 'skolemized forward answer');
+      },
+    },
     {
       name: 'run exposes false/0 as an always-failing built-in',
       run: () => {
@@ -6283,7 +6297,11 @@ answer(ok) :-
         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, 163, 'EyeProlog registry contains ISO definitions, cleanup controls, observability extensions, WFS tnot/1, and generic library adapters');
+        assertEqual(library.defs.size, 165, 'EyeProlog registry contains ISO definitions, cleanup controls, observability extensions, WFS tnot/1, and generic library adapters');
+        assertEqual(registry.get('eyeprolog__dynify', 1), null, 'Eyelet dynify adapter is absent from the ISO registry');
+        assertEqual(Boolean(library.get('eyeprolog__dynify', 1)), true, 'Eyelet dynify adapter is an internal EyeProlog library primitive');
+        assertEqual(registry.get('eyeprolog__eyelet_emit', 2), null, 'Eyelet event adapter is absent from the ISO registry');
+        assertEqual(Boolean(library.get('eyeprolog__eyelet_emit', 2)), true, 'Eyelet event adapter is an internal EyeProlog library primitive');
         assertEqual(registry.get('eyeprolog__random_value', 1), null, 'native random helper is absent from the ISO registry');
         assertEqual(Boolean(library.get('eyeprolog__random_value', 1)), true, 'native random helper is an internal EyeProlog library adapter');
         assertEqual(Boolean(registry.get('phrase', 2)), true, 'Part 3 phrase/2 exists');

package/the-art-of-eyeprolog.md

@@ -176,7 +176,7 @@ 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 how EyeProlog combines ordinary depth-first Prolog with explicit
-tabling, native forward rules, and inspectable proofs.
+tabling, Eyelet forward rules, and inspectable proofs.
 Chapter 41 gives further routes through the material.
 
 ### When a run surprises you
@@ -1668,7 +1668,7 @@ list, one by finitely many tabled graph answers, and one that constructs terms
 without bound. State why the first two may terminate and why tabling does not
 repair the third.
 
-### Native forward rules and Eyelet execution
+### Eyelet forward rules and Prolog execution
 
 EyeProlog normal mode also accepts `:+` at priority 1200 as an `xfx` operator.
 A source term
@@ -1678,19 +1678,33 @@ Conclusion :+ Premise.
 ```
 
 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 when
-Eyelet sources are run directly by EyeProlog.
+top-level goal overrides them, the engine loads `library(eyelet)` and invokes its
+Prolog closure driver. The driver inspects `:+/2` clauses structurally, prepares
+state predicates for updates, repeatedly solves premises against the current
+program, asserts novel conjuncts from successful conclusions, and continues until
+no new conclusion is added. Query-only programs take a single-pass fast path
+because they cannot grow the closure. 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. The bundled `library(eyelet)` exports the `:+` operator together with
-`stable/1` and `becomes/2`, while closure selection and assertion are native.
+its variables universal. The driver uses an explicit changed marker to repeat
+only productive rounds. `stable(Level)` raises the requested closure level and
+succeeds once that level has been reached. `becomes(From, To)` performs linear
+state replacement and prepares existing user predicates for mutation, so an
+EyeProlog source does not need a separate `dynamic/1` declaration merely to use
+that state with `becomes/2`.
+
+The `:+` reasoning algorithm is therefore Prolog code in `src/lib/eyelet.pl`, not
+a second JavaScript implementation. The host boundary is intentionally small:
+JavaScript bootstraps the private `eyelet:eyelet_run/3` entry point and supplies
+two private library adapters—one to make an existing user procedure mutable
+without rewriting its clauses, and one to forward answer/fuse terms to the CLI
+or embedding callbacks. Those adapters are not part of the strict ISO registry
+or the public `library(eyelet)` export surface.
 
 The JavaScript convenience `run()` function selects this forward mode when no
 explicit `goal` or `goals` option is supplied. Advanced embedders can inspect a
@@ -6368,7 +6382,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(eyelet)` | `stable/1`, `becomes/2` | Eyelet forward-reasoning driver and state helpers; the `:+` operator is exported by the module and its fixed point is implemented in Prolog |
 | `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,12 +143,14 @@ 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. 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)`.
+and executes those rules with the Prolog fixed-point driver in the bundled
+`library(eyelet)`. That module owns the Eyelet semantics—rule selection,
+fixed-point iteration, skolemization, `stable/1`, `becomes/2`, and the
+`true :+ Goal` / `false :+ Goal` control conventions—rather than duplicating the
+reasoning algorithm in JavaScript. The host layer is limited to private database
+mutability and output-event adapters. 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