eyeling 1.16.2 → 1.16.3

package/lib/engine.js

@@ -30,7 +30,7 @@ const {
 // In N3/Turtle, rdf:nil is the canonical IRI for the empty RDF list.
 // Eyeling represents list literals with ListTerm; ensure rdf:nil unifies with ().
 const RDF_NIL_IRI = RDF_NS + 'nil';
-const __EMPTY_LIST = new ListTerm([]);
+const EMPTY_LIST_TERM = new ListTerm([]);
 
 const { lex, N3SyntaxError } = require('./lexer');
 const { Parser } = require('./parser');
@@ -72,13 +72,13 @@ let version = 'dev';
 try {
   // Node: keep package.json version if available
   if (typeof require === 'function') version = require('./package.json').version || version;
-} catch (_) {}
+} catch {}
 
 let nodeCrypto = null;
 try {
   // Node: crypto available
   if (typeof require === 'function') nodeCrypto = require('crypto');
-} catch (_) {}
+} catch {}
 // For a single reasoning run, this maps a canonical representation
 // of the subject term in log:skolem to a Skolem IRI.
 const skolemCache = new Map();
@@ -90,10 +90,10 @@ const skolemCache = new Map();
 //   - Across reasoning runs (default): same subject -> different Skolem IRI.
 //   - Optional legacy mode: stable across runs (CLI: --deterministic-skolem).
 let deterministicSkolemAcrossRuns = false;
-let __skolemRunDepth = 0;
-let __skolemRunSalt = null;
+let skolemRunDepth = 0;
+let skolemRunSalt = null;
 
-function __makeSkolemRunSalt() {
+function makeSkolemRunSalt() {
   // Prefer WebCrypto if present (browser/worker)
   try {
     const g = typeof globalThis !== 'undefined' ? globalThis : null;
@@ -107,7 +107,7 @@ function __makeSkolemRunSalt() {
           .join('');
       }
     }
-  } catch (_) {}
+  } catch {}
 
   // Node.js crypto
   try {
@@ -115,7 +115,7 @@ function __makeSkolemRunSalt() {
       if (typeof nodeCrypto.randomUUID === 'function') return nodeCrypto.randomUUID();
       if (typeof nodeCrypto.randomBytes === 'function') return nodeCrypto.randomBytes(16).toString('hex');
     }
-  } catch (_) {}
+  } catch {}
 
   // Last-resort fallback (not cryptographically strong)
   return (
@@ -123,30 +123,30 @@ function __makeSkolemRunSalt() {
   );
 }
 
-function __enterReasoningRun() {
-  __skolemRunDepth += 1;
-  if (__skolemRunDepth === 1) {
+function enterReasoningRun() {
+  skolemRunDepth += 1;
+  if (skolemRunDepth === 1) {
     skolemCache.clear();
-    __skolemRunSalt = deterministicSkolemAcrossRuns ? '' : __makeSkolemRunSalt();
+    skolemRunSalt = deterministicSkolemAcrossRuns ? '' : makeSkolemRunSalt();
   }
 }
 
-function __exitReasoningRun() {
-  if (__skolemRunDepth > 0) __skolemRunDepth -= 1;
-  if (__skolemRunDepth === 0) {
+function exitReasoningRun() {
+  if (skolemRunDepth > 0) skolemRunDepth -= 1;
+  if (skolemRunDepth === 0) {
     // Clear the salt so a future top-level run gets a fresh one (default mode).
-    __skolemRunSalt = null;
+    skolemRunSalt = null;
   }
 }
 
-function __skolemIdForKey(key) {
+function skolemIdForKey(key) {
   if (deterministicSkolemAcrossRuns) return deterministicSkolemIdFromKey(key);
   // Ensure we have a run salt even if log:skolem is invoked outside forwardChain().
-  if (__skolemRunSalt === null) {
+  if (skolemRunSalt === null) {
     skolemCache.clear();
-    __skolemRunSalt = __makeSkolemRunSalt();
+    skolemRunSalt = makeSkolemRunSalt();
   }
-  return deterministicSkolemIdFromKey(__skolemRunSalt + '|' + key);
+  return deterministicSkolemIdFromKey(skolemRunSalt + '|' + key);
 }
 
 function getDeterministicSkolemEnabled() {
@@ -156,8 +156,8 @@ function getDeterministicSkolemEnabled() {
 function setDeterministicSkolemEnabled(v) {
   deterministicSkolemAcrossRuns = !!v;
   // Reset per-run state so the new mode takes effect immediately for the next run.
-  if (__skolemRunDepth === 0) {
-    __skolemRunSalt = null;
+  if (skolemRunDepth === 0) {
+    skolemRunSalt = null;
     skolemCache.clear();
   }
 }
@@ -243,6 +243,7 @@ function __computeHeadIsStrictGround(r) {
   if (r.isFuse) return false;
   // Dynamic heads depend on runtime bindings; treat as non-ground.
   if (r.__dynamicConclusionTerm) return false;
+  if (r.__fromRulePromotion) return false;
   if (r.headBlankLabels && r.headBlankLabels.size) return false;
   for (const tr of r.conclusion) if (!__isStrictGroundTriple(tr)) return false;
   return true;
@@ -1118,10 +1119,13 @@ function candidateFacts(facts, goal) {
     else if (wildPO) wild = wildPO;
     else wild = facts.__wildPred.length ? facts.__wildPred : null;
 
-    if (exact && wild) return exact.concat(wild);
-    if (exact) return exact;
-    if (wild) return wild;
-    return [];
+    return {
+      exact: exact || null,
+      wild: wild || null,
+      exactLen: exact ? exact.length : 0,
+      wildLen: wild ? wild.length : 0,
+      totalLen: (exact ? exact.length : 0) + (wild ? wild.length : 0),
+    };
   }
 
   return null;
@@ -1164,6 +1168,11 @@ function pushFactIndexed(facts, tr) {
   indexFact(facts, tr, idx);
 }
 
+function makeDerivedRecord(fact, rule, premises, subst, captureExplanations) {
+  if (captureExplanations === false) return { fact };
+  return new DerivedFact(fact, rule, premises.slice(), { ...subst });
+}
+
 function ensureBackRuleIndexes(backRules) {
   if (backRules.__byHeadPred && backRules.__wildHeadPred) return;
 
@@ -1197,6 +1206,164 @@ function indexBackRule(backRules, r) {
   }
 }
 
+function isSinglePremiseAgendaRuleSafe(r, backRules) {
+  if (!r || r.isFuse || !Array.isArray(r.premise) || r.premise.length !== 1) return false;
+
+  // Keep agenda firing restricted to rules whose observable output order is
+  // already stable in the legacy engine. Dynamic heads and head-blank
+  // skolemization are deliberately left on the old path so example outputs keep
+  // the same derived blank labels and rule-promotion behavior.
+  if (r.__dynamicConclusionTerm) return false;
+  if (r.__fromRulePromotion) return false;
+  if (r.headBlankLabels && r.headBlankLabels.size) return false;
+
+  const goal = r.premise[0];
+
+  // Builtin-only bodies need the normal proveGoals path because they can
+  // succeed without matching an extensional fact and may depend on scoped state.
+  if (isBuiltinPred(goal.p)) return false;
+
+  // Safe only when the sole premise cannot be satisfied via backward rules.
+  // Otherwise matching just against newly-seen facts would be incomplete.
+  ensureBackRuleIndexes(backRules);
+  if (goal.p instanceof Iri) {
+    if ((backRules.__byHeadPred.get(goal.p.__tid) || []).length) return false;
+    if (backRules.__wildHeadPred.length) return false;
+    return true;
+  }
+
+  return backRules.__wildHeadPred.length === 0;
+}
+
+function mergeSinglePremiseAgendaBuckets() {
+  let out = null;
+  let seen = null;
+
+  for (let i = 0; i < arguments.length; i++) {
+    const bucket = arguments[i];
+    if (!bucket || bucket.length === 0) continue;
+
+    if (out === null) {
+      out = bucket.length === 1 ? [bucket[0]] : bucket.slice();
+      if (bucket.length > 1) seen = new Set(out);
+      continue;
+    }
+
+    if (!seen) seen = new Set(out);
+    for (let j = 0; j < bucket.length; j++) {
+      const entry = bucket[j];
+      if (seen.has(entry)) continue;
+      seen.add(entry);
+      out.push(entry);
+    }
+  }
+
+  return out;
+}
+
+function makeSinglePremiseAgendaIndex(forwardRules, backRules) {
+  const index = {
+    byPred: new Map(),
+    byPS: new Map(),
+    byPO: new Map(),
+    wildPred: [],
+    wildPS: new Map(),
+    wildPO: new Map(),
+    indexed: new Set(),
+    size: 0,
+  };
+
+  function addToMapArray(m, k, v) {
+    let bucket = m.get(k);
+    if (!bucket) {
+      bucket = [];
+      m.set(k, bucket);
+    }
+    bucket.push(v);
+  }
+
+  for (let i = 0; i < forwardRules.length; i++) {
+    const r = forwardRules[i];
+    if (!isSinglePremiseAgendaRuleSafe(r, backRules)) continue;
+
+    const goal = r.premise[0];
+    const entry = {
+      rule: r,
+      ruleIndex: i,
+      goal,
+      goalPredTid: goal.p instanceof Iri ? goal.p.__tid : null,
+      goalSKey: termFastKey(goal.s),
+      goalOKey: termFastKey(goal.o),
+    };
+
+    index.indexed.add(r);
+    index.size += 1;
+
+    if (entry.goalPredTid !== null) {
+      if (entry.goalSKey === null && entry.goalOKey === null) addToMapArray(index.byPred, entry.goalPredTid, entry);
+      if (entry.goalSKey !== null) {
+        let ps = index.byPS.get(entry.goalPredTid);
+        if (!ps) {
+          ps = new Map();
+          index.byPS.set(entry.goalPredTid, ps);
+        }
+        addToMapArray(ps, entry.goalSKey, entry);
+      }
+      if (entry.goalOKey !== null) {
+        let po = index.byPO.get(entry.goalPredTid);
+        if (!po) {
+          po = new Map();
+          index.byPO.set(entry.goalPredTid, po);
+        }
+        addToMapArray(po, entry.goalOKey, entry);
+      }
+    } else {
+      if (entry.goalSKey === null && entry.goalOKey === null) index.wildPred.push(entry);
+      if (entry.goalSKey !== null) addToMapArray(index.wildPS, entry.goalSKey, entry);
+      if (entry.goalOKey !== null) addToMapArray(index.wildPO, entry.goalOKey, entry);
+    }
+  }
+
+  return index;
+}
+
+function getSinglePremiseAgendaCandidates(index, fact) {
+  if (!index || index.size === 0) return null;
+
+  const sk = termFastKey(fact.s);
+  const ok = termFastKey(fact.o);
+
+  let exact = null;
+  if (fact.p instanceof Iri) {
+    const pk = fact.p.__tid;
+    const byPred = index.byPred.get(pk) || null;
+    let byPS = null;
+    if (sk !== null) {
+      const ps = index.byPS.get(pk);
+      if (ps) byPS = ps.get(sk) || null;
+    }
+    let byPO = null;
+    if (ok !== null) {
+      const po = index.byPO.get(pk);
+      if (po) byPO = po.get(ok) || null;
+    }
+
+    exact = mergeSinglePremiseAgendaBuckets(byPred, byPS, byPO);
+  }
+
+  const wildPred = index.wildPred.length ? index.wildPred : null;
+  let wildPS = null;
+  if (sk !== null) wildPS = index.wildPS.get(sk) || null;
+
+  let wildPO = null;
+  if (ok !== null) wildPO = index.wildPO.get(ok) || null;
+
+  const wild = mergeSinglePremiseAgendaBuckets(wildPred, wildPS, wildPO);
+
+  if (!exact && !wild) return null;
+  return { exact, wild, exactLen: exact ? exact.length : 0, wildLen: wild ? wild.length : 0 };
+}
+
 // ===========================================================================
 // Special predicate helpers
 // ===========================================================================
@@ -1222,7 +1389,7 @@ function isLogImpliedBy(p) {
 // So this improves reuse across repeated backward proofs without changing the
 // semantics of recursive goals.
 
-function __goalTableScopeVersion(facts, backRules) {
+function goalTableScopeVersion(facts, backRules) {
   const factCount = Array.isArray(facts) ? facts.length : 0;
   const backRuleCount = Array.isArray(backRules) ? backRules.length : 0;
   const scopedLevel = facts && typeof facts.__scopedClosureLevel === 'number' ? facts.__scopedClosureLevel : 0;
@@ -1239,26 +1406,26 @@ function __makeGoalTable() {
 
 function __attachGoalTable(scopeCarrier, goalTable) {
   if (!scopeCarrier) return goalTable;
-  if (!hasOwn.call(scopeCarrier, '__goalTable')) {
-    Object.defineProperty(scopeCarrier, '__goalTable', {
+  if (!hasOwn.call(scopeCarrier, 'goalTable')) {
+    Object.defineProperty(scopeCarrier, 'goalTable', {
       value: goalTable,
       enumerable: false,
       writable: true,
       configurable: true,
     });
   } else {
-    scopeCarrier.__goalTable = goalTable;
+    scopeCarrier.goalTable = goalTable;
   }
   return goalTable;
 }
 
 function __ensureGoalTable(facts, backRules) {
-  let table = (facts && facts.__goalTable) || (backRules && backRules.__goalTable) || null;
+  let table = (facts && facts.goalTable) || (backRules && backRules.goalTable) || null;
   if (!table) table = __makeGoalTable();
   __attachGoalTable(facts, table);
   __attachGoalTable(backRules, table);
 
-  const version = __goalTableScopeVersion(facts, backRules);
+  const version = goalTableScopeVersion(facts, backRules);
   if (table.scopeVersion !== version) {
     table.scopeVersion = version;
     table.entries.clear();
@@ -1304,6 +1471,7 @@ function __canStoreGoalMemo(visited, maxResults) {
 // ===========================================================================
 
 function containsVarTerm(t, v) {
+  if (t instanceof Iri || t instanceof Literal || t instanceof Blank) return false;
   if (t instanceof Var) return t.name === v;
   if (t instanceof ListTerm) return t.elems.some((e) => containsVarTerm(e, v));
   if (t instanceof OpenListTerm) return t.prefix.some((e) => containsVarTerm(e, v)) || t.tailVar === v;
@@ -1327,6 +1495,7 @@ function isGroundTripleInGraph(tr) {
 }
 
 function isGroundTerm(t) {
+  if (t instanceof Iri || t instanceof Literal || t instanceof Blank) return true;
   if (t instanceof Var) return false;
   if (t instanceof ListTerm) return t.elems.every((e) => isGroundTerm(e));
   if (t instanceof OpenListTerm) return false;
@@ -1360,7 +1529,7 @@ function skolemIriFromGroundTerm(t) {
   const key = skolemKeyFromTerm(t);
   let iri = skolemCache.get(key);
   if (!iri) {
-    const id = __skolemIdForKey(key);
+    const id = skolemIdForKey(key);
     iri = internIri(SKOLEM_NS + id);
     skolemCache.set(key, iri);
   }
@@ -1368,6 +1537,9 @@ function skolemIriFromGroundTerm(t) {
 }
 
 function applySubstTerm(t, s) {
+  // Hot fast path: most terms are already-ground atomic terms.
+  if (t instanceof Iri || t instanceof Literal || t instanceof Blank) return t;
+
   // Common case: variable
   if (t instanceof Var) {
     const first = s[t.name];
@@ -1562,8 +1734,8 @@ function unifyTermWithOptions(a, b, subst, opts) {
 
   // Normalize rdf:nil IRI to the empty list term, so it unifies with () and
   // list builtins treat it consistently.
-  if (a instanceof Iri && a.value === RDF_NIL_IRI) a = __EMPTY_LIST;
-  if (b instanceof Iri && b.value === RDF_NIL_IRI) b = __EMPTY_LIST;
+  if (a instanceof Iri && a.value === RDF_NIL_IRI) a = EMPTY_LIST_TERM;
+  if (b instanceof Iri && b.value === RDF_NIL_IRI) b = EMPTY_LIST_TERM;
 
   // Variable binding
   if (a instanceof Var) {
@@ -1793,10 +1965,10 @@ function __builtinIsSatisfiableWhenFullyUnbound(pIriVal) {
 }
 
 function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxResults, opts) {
-  const __goalTable = __canLookupGoalMemo(visited) ? __ensureGoalTable(facts, backRules) : null;
-  const __goalMemoKeyNow = __goalTable ? __goalMemoKey(goals, subst, facts, opts) : null;
-  if (__goalTable && __goalTable.entries.has(__goalMemoKeyNow)) {
-    const cached = __goalTable.entries.get(__goalMemoKeyNow) || [];
+  const goalTable = __canLookupGoalMemo(visited) ? __ensureGoalTable(facts, backRules) : null;
+  const goalMemoKeyNow = goalTable ? __goalMemoKey(goals, subst, facts, opts) : null;
+  if (goalTable && goalTable.entries.has(goalMemoKeyNow)) {
+    const cached = goalTable.entries.get(goalMemoKeyNow) || [];
     const cloned = __cloneGoalSolutions(cached);
     if (typeof maxResults === 'number' && maxResults > 0 && cloned.length > maxResults)
       return cloned.slice(0, maxResults);
@@ -1815,7 +1987,7 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
 
   // IMPORTANT: Goal reordering / deferral is only enabled when explicitly
   // requested by the caller (used for forward rules).
-  const __allowDeferBuiltins = !!(opts && opts.deferBuiltins);
+  const allowDeferredBuiltins = !!(opts && opts.deferBuiltins);
 
   const initialGoals = Array.isArray(goals) ? goals.slice() : [];
   const substMut = subst ? { ...subst } : {};
@@ -1830,8 +2002,8 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
 
   if (!initialGoals.length) {
     results.push(gcCompactForGoals(substMut, [], answerVars));
-    if (__goalTable && __canStoreGoalMemo(visited, maxResults)) {
-      __goalTable.entries.set(__goalMemoKeyNow, __cloneGoalSolutions(results));
+    if (goalTable && __canStoreGoalMemo(visited, maxResults)) {
+      goalTable.entries.set(goalMemoKeyNow, __cloneGoalSolutions(results));
     }
     return results;
   }
@@ -1871,14 +2043,14 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
   const visitedCounts = new Map(); // key -> count
   const visitedTrail = []; // stack of keys in insertion order
 
-  const __termKeyCache = typeof WeakMap === 'function' ? new WeakMap() : null;
+  const termKeyCache = typeof WeakMap === 'function' ? new WeakMap() : null;
 
-  function __termKeyForVisited(t) {
+  function termKeyForVisited(t) {
     if (t instanceof Iri && t.value === RDF_NIL_IRI) return '()';
     if (t instanceof ListTerm && t.elems.length === 0) return '()';
 
-    if (__termKeyCache && t && typeof t === 'object') {
-      const cached = __termKeyCache.get(t);
+    if (termKeyCache && t && typeof t === 'object') {
+      const cached = termKeyCache.get(t);
       if (cached) return cached;
     }
 
@@ -1909,14 +2081,14 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
       // Iri / Blank and other atomic interned terms
       out = 'T' + t.__tid;
     } else if (t instanceof ListTerm) {
-      out = '[' + t.elems.map(__termKeyForVisited).join(',') + ']';
+      out = '[' + t.elems.map(termKeyForVisited).join(',') + ']';
     } else if (t instanceof OpenListTerm) {
-      out = '[open:' + t.prefix.map(__termKeyForVisited).join(',') + '|tail:' + t.tailVar + ']';
+      out = '[open:' + t.prefix.map(termKeyForVisited).join(',') + '|tail:' + t.tailVar + ']';
     } else if (t instanceof GraphTerm) {
       out =
         '{' +
         t.triples
-          .map((tr) => __termKeyForVisited(tr.s) + ' ' + __termKeyForVisited(tr.p) + ' ' + __termKeyForVisited(tr.o))
+          .map((tr) => termKeyForVisited(tr.s) + ' ' + termKeyForVisited(tr.p) + ' ' + termKeyForVisited(tr.o))
           .join(';') +
         '}';
     } else {
@@ -1924,20 +2096,20 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
       out = skolemKeyFromTerm(t);
     }
 
-    if (__termKeyCache && t && typeof t === 'object') __termKeyCache.set(t, out);
+    if (termKeyCache && t && typeof t === 'object') termKeyCache.set(t, out);
     return out;
   }
 
-  function __tripleKeyForVisited(tr) {
-    return __termKeyForVisited(tr.s) + '\t' + __termKeyForVisited(tr.p) + '\t' + __termKeyForVisited(tr.o);
+  function tripleKeyForVisited(tr) {
+    return termKeyForVisited(tr.s) + '\t' + termKeyForVisited(tr.p) + '\t' + termKeyForVisited(tr.o);
   }
 
-  function __pushVisited(key) {
+  function pushVisitedKey(key) {
     visitedTrail.push(key);
     visitedCounts.set(key, (visitedCounts.get(key) || 0) + 1);
   }
 
-  function __undoVisitedTo(mark) {
+  function undoVisitedKeysTo(mark) {
     for (let i = visitedTrail.length - 1; i >= mark; i--) {
       const k = visitedTrail[i];
       const c = visitedCounts.get(k);
@@ -1947,7 +2119,7 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
     visitedTrail.length = mark;
   }
 
-  for (const tr of initialVisited) __pushVisited(__tripleKeyForVisited(tr));
+  for (const tr of initialVisited) pushVisitedKey(tripleKeyForVisited(tr));
 
   // ---------------------------------------------------------------------------
   // In-place unification into the mutable substitution + trail.
@@ -1979,8 +2151,10 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
 
     // Normalize rdf:nil IRI to the empty list term, so it unifies with () and
     // list builtins treat it consistently.
-    if (a instanceof Iri && a.value === RDF_NIL_IRI) a = __EMPTY_LIST;
-    if (b instanceof Iri && b.value === RDF_NIL_IRI) b = __EMPTY_LIST;
+    if (a instanceof Iri && a.value === RDF_NIL_IRI) a = EMPTY_LIST_TERM;
+    if (b instanceof Iri && b.value === RDF_NIL_IRI) b = EMPTY_LIST_TERM;
+
+    if (a === b) return true;
 
     // Variable binding
     if (a instanceof Var) return bindVarTrail(a.name, b);
@@ -2099,7 +2273,7 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
     kind: 'node',
     goalsNow: initialGoals,
     curDepth: depth || 0,
-    canDeferBuiltins: __allowDeferBuiltins,
+    canDeferBuiltins: allowDeferredBuiltins,
     deferCount: 0,
   });
 
@@ -2108,7 +2282,7 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
 
     if (frame.kind === 'undo') {
       undoTo(frame.substMark);
-      __undoVisitedTo(frame.visitedMark);
+      undoVisitedKeysTo(frame.visitedMark);
       continue;
     }
 
@@ -2167,15 +2341,15 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
         // still preventing trivial non-termination in mutually recursive rule
         // cycles.
         if (frame.goalWasVisited && rStd.premise && rStd.premise.length) {
-          let __cycle = false;
+          let hasCycle = false;
           for (let i = 0; i < rStd.premise.length; i++) {
-            const premKey = __tripleKeyForVisited(applySubstTriple(rStd.premise[i], substMut));
+            const premKey = tripleKeyForVisited(applySubstTriple(rStd.premise[i], substMut));
             if (visitedCounts.has(premKey)) {
-              __cycle = true;
+              hasCycle = true;
               break;
             }
           }
-          if (__cycle) {
+          if (hasCycle) {
             undoTo(mark);
             continue;
           }
@@ -2184,7 +2358,7 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
         const newGoals = rStd.premise.concat(frame.restGoals);
 
         const vMark = visitedTrail.length;
-        __pushVisited(frame.goalKey);
+        pushVisitedKey(frame.goalKey);
 
         // Explore the rule body; then undo; then resume trying further rules.
         stack.push(frame);
@@ -2206,8 +2380,15 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
       const candidates = frame.candidates;
       const isIndexed = !!candidates;
 
-      while (frame.idx < (isIndexed ? candidates.length : factsList.length) && results.length < max) {
-        const f = isIndexed ? factsList[candidates[frame.idx++]] : factsList[frame.idx++];
+      while (frame.idx < (isIndexed ? candidates.totalLen : factsList.length) && results.length < max) {
+        let f;
+        if (isIndexed) {
+          const idxNow = frame.idx++;
+          if (idxNow < candidates.exactLen) f = factsList[candidates.exact[idxNow]];
+          else f = factsList[candidates.wild[idxNow - candidates.exactLen]];
+        } else {
+          f = factsList[frame.idx++];
+        }
 
         const mark = trail.length;
         if (!unifyTripleTrail(frame.goal0, f)) {
@@ -2250,13 +2431,13 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
     const goal0 = applySubstTriple(rawGoal, substMut);
 
     // 1) Builtins
-    const __pv0 = goal0.p instanceof Iri ? goal0.p.value : null;
-    const __rdfFirstOrRest = __pv0 === RDF_NS + 'first' || __pv0 === RDF_NS + 'rest';
-    const __treatBuiltin =
+    const goalPredicateIri = goal0.p instanceof Iri ? goal0.p.value : null;
+    const isRdfFirstOrRest = goalPredicateIri === RDF_NS + 'first' || goalPredicateIri === RDF_NS + 'rest';
+    const shouldTreatAsBuiltin =
       isBuiltinPred(goal0.p) &&
-      !(__rdfFirstOrRest && !(goal0.s instanceof ListTerm || goal0.s instanceof OpenListTerm));
+      !(isRdfFirstOrRest && !(goal0.s instanceof ListTerm || goal0.s instanceof OpenListTerm));
 
-    if (__treatBuiltin) {
+    if (shouldTreatAsBuiltin) {
       const remaining = max - results.length;
       if (remaining <= 0) continue;
       const builtinMax = Number.isFinite(remaining) && !restGoals.length ? remaining : undefined;
@@ -2264,11 +2445,11 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
       let deltas = evalBuiltin(goal0, {}, facts, backRules, frame.curDepth, varGen, builtinMax);
 
       const dc = typeof frame.deferCount === 'number' ? frame.deferCount : 0;
-      const __vacuous = deltas.length > 0 && deltas.every((d) => Object.keys(d).length === 0);
+      const builtinDeltasAreVacuous = deltas.length > 0 && deltas.every((d) => Object.keys(d).length === 0);
 
       if (
         frame.canDeferBuiltins &&
-        (!deltas.length || __vacuous) &&
+        (!deltas.length || builtinDeltasAreVacuous) &&
         restGoals.length &&
         __tripleHasVarOrBlank(goal0) &&
         dc < goalsNow.length
@@ -2284,14 +2465,14 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
         continue;
       }
 
-      const __fullyUnboundSO =
+      const subjectAndObjectAreFullyUnbound =
         (goal0.s instanceof Var || goal0.s instanceof Blank) && (goal0.o instanceof Var || goal0.o instanceof Blank);
 
       if (
         frame.canDeferBuiltins &&
         !deltas.length &&
-        __builtinIsSatisfiableWhenFullyUnbound(__pv0) &&
-        __fullyUnboundSO &&
+        __builtinIsSatisfiableWhenFullyUnbound(goalPredicateIri) &&
+        subjectAndObjectAreFullyUnbound &&
         (!restGoals.length || dc >= goalsNow.length)
       ) {
         deltas = [{}];
@@ -2326,7 +2507,7 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
     // We therefore *allow* re-entering a visited goal, but when a goal is
     // already visited we avoid applying backward rules whose premises would
     // immediately re-enter any visited goal again (a cheap cycle guard).
-    const goalKey = __tripleKeyForVisited(goal0);
+    const goalKey = tripleKeyForVisited(goal0);
     const goalWasVisited = visitedCounts.has(goalKey);
 
     // 3) Backward rules (indexed by head predicate) — explored first
@@ -2376,8 +2557,8 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
     }
   }
 
-  if (__goalTable && __canStoreGoalMemo(visited, maxResults)) {
-    __goalTable.entries.set(__goalMemoKeyNow, __cloneGoalSolutions(results));
+  if (goalTable && __canStoreGoalMemo(visited, maxResults)) {
+    goalTable.entries.set(goalMemoKeyNow, __cloneGoalSolutions(results));
   }
 
   return results;
@@ -2387,8 +2568,8 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
 // Forward chaining to fixpoint
 // ===========================================================================
 
-function forwardChain(facts, forwardRules, backRules, onDerived /* optional */) {
-  __enterReasoningRun();
+function forwardChain(facts, forwardRules, backRules, onDerived /* optional */, opts = {}) {
+  enterReasoningRun();
   try {
     ensureFactIndexes(facts);
     ensureBackRuleIndexes(backRules);
@@ -2397,7 +2578,7 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */)
     __attachGoalTable(facts, goalTable);
     __attachGoalTable(backRules, goalTable);
 
-    const factList = facts.slice();
+    const captureExplanations = !(opts && opts.captureExplanations === false);
     const derivedForward = [];
     const varGen = [0];
     const skCounter = [0];
@@ -2473,46 +2654,216 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */)
       return snap;
     }
 
+    function __skipForwardRuleNow(r) {
+      // Skip forward rules that are guaranteed to "delay" due to scoped
+      // builtins (log:collectAllIn / log:forAllIn / log:includes / log:notIncludes)
+      // until a snapshot exists (and a certain closure level is reached).
+      // This prevents expensive proofs that will definitely fail in Phase A
+      // and in early closure levels.
+      const info = r.__scopedSkipInfo;
+      if (info && info.needsSnap) {
+        const snapHere = facts.__scopedSnapshot || null;
+        const lvlHere = (facts && typeof facts.__scopedClosureLevel === 'number' && facts.__scopedClosureLevel) || 0;
+        if (!snapHere) return true;
+        if (lvlHere < info.requiredLevel) return true;
+      }
+
+      // Optimization: if the rule head is **structurally ground** (no vars anywhere, even inside
+      // quoted formulas) and has no head blanks, then the head does not depend on which body
+      // solution we pick. In that case, we only need *one* proof of the body, and once all head
+      // triples are already known we can skip proving the body entirely.
+      const headIsStrictGround = r.__headIsStrictGround;
+      if (headIsStrictGround) {
+        let allKnown = true;
+        for (const tr of r.conclusion) {
+          if (!hasFactIndexed(facts, tr)) {
+            allKnown = false;
+            break;
+          }
+        }
+        if (allKnown) return true;
+      }
+
+      return false;
+    }
+
+    function __emitForwardRuleSolution(r, ruleIndex, s) {
+      let changedHere = false;
+      let rulesChanged = false;
+
+      // IMPORTANT: one skolem map per *rule firing*
+      const skMap = {};
+      const instantiatedPremises = r.premise.map((b) => applySubstTriple(b, s));
+      const fireKey = __firingKey(ruleIndex, instantiatedPremises);
+
+      // Support "dynamic" rule heads where the consequent is a term that
+      // (after substitution) evaluates to a quoted formula.
+      // Example: { :a :b ?C } => ?C.
+      let dynamicHeadTriples = null;
+      let headBlankLabelsHere = r.headBlankLabels;
+      if (r.__dynamicConclusionTerm) {
+        const dynTerm = applySubstTerm(r.__dynamicConclusionTerm, s);
+
+        // Allow dynamic fuses: ... => ?X. where ?X becomes false
+        if (dynTerm instanceof Literal && dynTerm.value === 'false') {
+          console.log('# Inference fuse triggered: dynamic head resolved to false.');
+          process.exit(2);
+        }
+
+        const dynTriples = __graphTriplesOrTrue(dynTerm);
+        dynamicHeadTriples = dynTriples !== null ? dynTriples : [];
+
+        // If the dynamic head contains explicit blank nodes, treat them as
+        // head blanks for skolemization.
+        const dynHeadBlankLabels =
+          dynamicHeadTriples && dynamicHeadTriples.length ? collectBlankLabelsInTriples(dynamicHeadTriples) : null;
+        if (dynHeadBlankLabels && dynHeadBlankLabels.size) {
+          headBlankLabelsHere = new Set([...headBlankLabelsHere, ...dynHeadBlankLabels]);
+        }
+      }
+
+      const headPatterns =
+        dynamicHeadTriples && dynamicHeadTriples.length ? r.conclusion.concat(dynamicHeadTriples) : r.conclusion;
+
+      for (const cpat of headPatterns) {
+        const instantiated = applySubstTriple(cpat, s);
+
+        const subj = instantiated.s;
+        const obj = instantiated.o;
+
+        const subjIsGraph = subj instanceof GraphTerm;
+        const objIsGraph = obj instanceof GraphTerm;
+        const subjIsTrue = subj instanceof Literal && subj.value === 'true';
+        const objIsTrue = obj instanceof Literal && obj.value === 'true';
+
+        const isFwRuleTriple =
+          isLogImplies(instantiated.p) &&
+          ((subjIsGraph && objIsGraph) || (subjIsTrue && objIsGraph) || (subjIsGraph && objIsTrue));
+
+        const isBwRuleTriple =
+          isLogImpliedBy(instantiated.p) &&
+          ((subjIsGraph && objIsGraph) || (subjIsGraph && objIsTrue) || (subjIsTrue && objIsGraph));
+
+        if (isFwRuleTriple || isBwRuleTriple) {
+          if (!hasFactIndexed(facts, instantiated)) {
+            pushFactIndexed(facts, instantiated);
+            const df = makeDerivedRecord(instantiated, r, instantiatedPremises, s, captureExplanations);
+            derivedForward.push(df);
+            if (typeof onDerived === 'function') onDerived(df);
+            changedHere = true;
+          }
+
+          // Promote rule-producing triples to live rules, treating literal true as {}.
+          const left = __graphTriplesOrTrue(subj);
+          const right = __graphTriplesOrTrue(obj);
+
+          if (left !== null && right !== null) {
+            if (isFwRuleTriple) {
+              const [premise, conclusion] = liftBlankRuleVars(left, right);
+              const headBlankLabels = collectBlankLabelsInTriples(conclusion);
+              const newRule = new Rule(premise, conclusion, true, false, headBlankLabels);
+              __prepareForwardRule(newRule);
+
+              const key = __ruleKey(
+                newRule.isForward,
+                newRule.isFuse,
+                newRule.premise,
+                newRule.conclusion,
+                newRule.__dynamicConclusionTerm || null,
+              );
+              if (!forwardRules.__ruleKeySet.has(key)) {
+                forwardRules.__ruleKeySet.add(key);
+                forwardRules.push(newRule);
+                rulesChanged = true;
+              }
+            } else if (isBwRuleTriple) {
+              const [premise, conclusion] = liftBlankRuleVars(right, left);
+              const headBlankLabels = collectBlankLabelsInTriples(conclusion);
+              const newRule = new Rule(premise, conclusion, false, false, headBlankLabels);
+
+              const key = __ruleKey(
+                newRule.isForward,
+                newRule.isFuse,
+                newRule.premise,
+                newRule.conclusion,
+                newRule.__dynamicConclusionTerm || null,
+              );
+              if (!backRules.__ruleKeySet.has(key)) {
+                backRules.__ruleKeySet.add(key);
+                backRules.push(newRule);
+                indexBackRule(backRules, newRule);
+                rulesChanged = true;
+              }
+            }
+          }
+
+          continue; // skip normal fact handling
+        }
+
+        // Only skolemize blank nodes that occur explicitly in the rule head
+        const inst = skolemizeTripleForHeadBlanks(
+          instantiated,
+          headBlankLabelsHere,
+          skMap,
+          skCounter,
+          fireKey,
+          headSkolemCache,
+        );
+
+        if (!isGroundTriple(inst)) continue;
+        if (hasFactIndexed(facts, inst)) continue;
+
+        pushFactIndexed(facts, inst);
+        const df = makeDerivedRecord(inst, r, instantiatedPremises, s, captureExplanations);
+        derivedForward.push(df);
+        if (typeof onDerived === 'function') onDerived(df);
+
+        changedHere = true;
+      }
+
+      return { changedHere, rulesChanged };
+    }
+
     function runFixpoint() {
       let anyChange = false;
+      let agendaIndex = makeSinglePremiseAgendaIndex(forwardRules, backRules);
+      let agendaCursor = 0;
 
       while (true) {
         let changed = false;
 
-        for (let i = 0; i < forwardRules.length; i++) {
-          const r = forwardRules[i];
+        while (agendaCursor < facts.length && agendaIndex.size) {
+          const fact = facts[agendaCursor++];
+          const candidates = getSinglePremiseAgendaCandidates(agendaIndex, fact);
+          if (!candidates) continue;
 
-          // Skip forward rules that are guaranteed to "delay" due to scoped
-          // builtins (log:collectAllIn / log:forAllIn / log:includes / log:notIncludes)
-          // until a snapshot exists (and a certain closure level is reached).
-          // This prevents expensive proofs that will definitely fail in Phase A
-          // and in early closure levels.
-          const info = r.__scopedSkipInfo;
-          if (info && info.needsSnap) {
-            const snapHere = facts.__scopedSnapshot || null;
-            const lvlHere =
-              (facts && typeof facts.__scopedClosureLevel === 'number' && facts.__scopedClosureLevel) || 0;
-            if (!snapHere) continue;
-            if (lvlHere < info.requiredLevel) continue;
-          }
+          const total = candidates.exactLen + candidates.wildLen;
+          for (let ci = 0; ci < total; ci++) {
+            const entry = ci < candidates.exactLen ? candidates.exact[ci] : candidates.wild[ci - candidates.exactLen];
+            const r = entry.rule;
+            if (__skipForwardRuleNow(r)) continue;
 
-          // Optimization: if the rule head is **structurally ground** (no vars anywhere, even inside
-          // quoted formulas) and has no head blanks, then the head does not depend on which body
-          // solution we pick. In that case, we only need *one* proof of the body, and once all head
-          // triples are already known we can skip proving the body entirely.
-          const headIsStrictGround = r.__headIsStrictGround;
+            const s = unifyTriple(entry.goal, fact, {});
+            if (s === null) continue;
 
-          if (headIsStrictGround) {
-            let allKnown = true;
-            for (const tr of r.conclusion) {
-              if (!hasFactIndexed(facts, tr)) {
-                allKnown = false;
-                break;
-              }
+            const outcome = __emitForwardRuleSolution(r, entry.ruleIndex, s);
+            if (outcome.rulesChanged) {
+              agendaIndex = makeSinglePremiseAgendaIndex(forwardRules, backRules);
+              agendaCursor = 0;
+            }
+            if (outcome.changedHere) {
+              changed = true;
+              anyChange = true;
             }
-            if (allKnown) continue;
           }
+        }
 
+        for (let i = 0; i < forwardRules.length; i++) {
+          const r = forwardRules[i];
+          if (agendaIndex.indexed.has(r)) continue;
+          if (__skipForwardRuleNow(r)) continue;
+
+          const headIsStrictGround = r.__headIsStrictGround;
           const maxSols = r.isFuse || headIsStrictGround ? 1 : undefined;
           // Enable builtin deferral / goal reordering for forward rules only.
           // This keeps forward-chaining conjunctions order-insensitive while
@@ -2529,145 +2880,22 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */)
           }
 
           for (const s of sols) {
-            // IMPORTANT: one skolem map per *rule firing*
-            const skMap = {};
-            const instantiatedPremises = r.premise.map((b) => applySubstTriple(b, s));
-            const fireKey = __firingKey(i, instantiatedPremises);
-
-            // Support "dynamic" rule heads where the consequent is a term that
-            // (after substitution) evaluates to a quoted formula.
-            // Example: { :a :b ?C } => ?C.
-            let dynamicHeadTriples = null;
-            let headBlankLabelsHere = r.headBlankLabels;
-            if (r.__dynamicConclusionTerm) {
-              const dynTerm = applySubstTerm(r.__dynamicConclusionTerm, s);
-
-              // Allow dynamic fuses: ... => ?X. where ?X becomes false
-              if (dynTerm instanceof Literal && dynTerm.value === 'false') {
-                console.log('# Inference fuse triggered: dynamic head resolved to false.');
-                process.exit(2);
-              }
-
-              const dynTriples = __graphTriplesOrTrue(dynTerm);
-              dynamicHeadTriples = dynTriples !== null ? dynTriples : [];
-
-              // If the dynamic head contains explicit blank nodes, treat them as
-              // head blanks for skolemization.
-              const dynHeadBlankLabels =
-                dynamicHeadTriples && dynamicHeadTriples.length
-                  ? collectBlankLabelsInTriples(dynamicHeadTriples)
-                  : null;
-              if (dynHeadBlankLabels && dynHeadBlankLabels.size) {
-                headBlankLabelsHere = new Set([...headBlankLabelsHere, ...dynHeadBlankLabels]);
-              }
+            const outcome = __emitForwardRuleSolution(r, i, s);
+            if (outcome.rulesChanged) {
+              agendaIndex = makeSinglePremiseAgendaIndex(forwardRules, backRules);
+              agendaCursor = 0;
             }
-
-            const headPatterns =
-              dynamicHeadTriples && dynamicHeadTriples.length ? r.conclusion.concat(dynamicHeadTriples) : r.conclusion;
-
-            for (const cpat of headPatterns) {
-              const instantiated = applySubstTriple(cpat, s);
-
-              const subj = instantiated.s;
-              const obj = instantiated.o;
-
-              const subjIsGraph = subj instanceof GraphTerm;
-              const objIsGraph = obj instanceof GraphTerm;
-              const subjIsTrue = subj instanceof Literal && subj.value === 'true';
-              const objIsTrue = obj instanceof Literal && obj.value === 'true';
-
-              const isFwRuleTriple =
-                isLogImplies(instantiated.p) &&
-                ((subjIsGraph && objIsGraph) || (subjIsTrue && objIsGraph) || (subjIsGraph && objIsTrue));
-
-              const isBwRuleTriple =
-                isLogImpliedBy(instantiated.p) &&
-                ((subjIsGraph && objIsGraph) || (subjIsGraph && objIsTrue) || (subjIsTrue && objIsGraph));
-
-              if (isFwRuleTriple || isBwRuleTriple) {
-                if (!hasFactIndexed(facts, instantiated)) {
-                  factList.push(instantiated);
-                  pushFactIndexed(facts, instantiated);
-                  const df = new DerivedFact(instantiated, r, instantiatedPremises.slice(), { ...s });
-                  derivedForward.push(df);
-                  if (typeof onDerived === 'function') onDerived(df);
-
-                  changed = true;
-                }
-
-                // Promote rule-producing triples to live rules, treating literal true as {}.
-                const left = __graphTriplesOrTrue(subj);
-                const right = __graphTriplesOrTrue(obj);
-
-                if (left !== null && right !== null) {
-                  if (isFwRuleTriple) {
-                    const [premise, conclusion] = liftBlankRuleVars(left, right);
-                    const headBlankLabels = collectBlankLabelsInTriples(conclusion);
-                    const newRule = new Rule(premise, conclusion, true, false, headBlankLabels);
-                    __prepareForwardRule(newRule);
-
-                    const key = __ruleKey(
-                      newRule.isForward,
-                      newRule.isFuse,
-                      newRule.premise,
-                      newRule.conclusion,
-                      newRule.__dynamicConclusionTerm || null,
-                    );
-                    if (!forwardRules.__ruleKeySet.has(key)) {
-                      forwardRules.__ruleKeySet.add(key);
-                      forwardRules.push(newRule);
-                    }
-                  } else if (isBwRuleTriple) {
-                    const [premise, conclusion] = liftBlankRuleVars(right, left);
-                    const headBlankLabels = collectBlankLabelsInTriples(conclusion);
-                    const newRule = new Rule(premise, conclusion, false, false, headBlankLabels);
-
-                    const key = __ruleKey(
-                      newRule.isForward,
-                      newRule.isFuse,
-                      newRule.premise,
-                      newRule.conclusion,
-                      newRule.__dynamicConclusionTerm || null,
-                    );
-                    if (!backRules.__ruleKeySet.has(key)) {
-                      backRules.__ruleKeySet.add(key);
-                      backRules.push(newRule);
-                      indexBackRule(backRules, newRule);
-                    }
-                  }
-                }
-
-                continue; // skip normal fact handling
-              }
-
-              // Only skolemize blank nodes that occur explicitly in the rule head
-              const inst = skolemizeTripleForHeadBlanks(
-                instantiated,
-                headBlankLabelsHere,
-                skMap,
-                skCounter,
-                fireKey,
-                headSkolemCache,
-              );
-
-              if (!isGroundTriple(inst)) continue;
-              if (hasFactIndexed(facts, inst)) continue;
-
-              factList.push(inst);
-              pushFactIndexed(facts, inst);
-              const df = new DerivedFact(inst, r, instantiatedPremises.slice(), {
-                ...s,
-              });
-              derivedForward.push(df);
-              if (typeof onDerived === 'function') onDerived(df);
-
+            if (outcome.changedHere) {
               changed = true;
+              anyChange = true;
             }
           }
         }
 
-        if (!changed) break;
-        anyChange = true;
+        if (!changed) {
+          if (agendaCursor < facts.length && agendaIndex.size) continue;
+          break;
+        }
       }
 
       return anyChange;
@@ -2711,7 +2939,7 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */)
 
     return derivedForward;
   } finally {
-    __exitReasoningRun();
+    exitReasoningRun();
   }
 }
 
@@ -2783,7 +3011,7 @@ function __withScopedSnapshotForQueries(facts, fn) {
   }
 }
 
-function collectLogQueryConclusions(logQueryRules, facts, backRules) {
+function collectLogQueryConclusions(logQueryRules, facts, backRules, opts = {}) {
   const queryTriples = [];
   const queryDerived = [];
   const seen = new Set();
@@ -2799,6 +3027,8 @@ function collectLogQueryConclusions(logQueryRules, facts, backRules) {
   __attachGoalTable(facts, goalTable);
   __attachGoalTable(backRules, goalTable);
 
+  const captureExplanations = !(opts && opts.captureExplanations === false);
+
   // Shared state across all query firings (mirrors forwardChain()).
   const varGen = [0];
   const skCounter = [0];
@@ -2850,7 +3080,7 @@ function collectLogQueryConclusions(logQueryRules, facts, backRules) {
           if (seen.has(k)) continue;
           seen.add(k);
           queryTriples.push(inst);
-          queryDerived.push(new DerivedFact(inst, r, instantiatedPremises.slice(), { ...s }));
+          queryDerived.push(makeDerivedRecord(inst, r, instantiatedPremises, s, captureExplanations));
         }
       }
     }
@@ -2859,16 +3089,23 @@ function collectLogQueryConclusions(logQueryRules, facts, backRules) {
   });
 }
 
-function forwardChainAndCollectLogQueryConclusions(facts, forwardRules, backRules, logQueryRules, onDerived) {
-  __enterReasoningRun();
+function forwardChainAndCollectLogQueryConclusions(
+  facts,
+  forwardRules,
+  backRules,
+  logQueryRules,
+  onDerived,
+  opts = {},
+) {
+  enterReasoningRun();
   try {
     // Forward chain first (saturates `facts`).
-    const derived = forwardChain(facts, forwardRules, backRules, onDerived);
+    const derived = forwardChain(facts, forwardRules, backRules, onDerived, opts);
     // Then collect query conclusions against the saturated closure.
-    const { queryTriples, queryDerived } = collectLogQueryConclusions(logQueryRules, facts, backRules);
+    const { queryTriples, queryDerived } = collectLogQueryConclusions(logQueryRules, facts, backRules, opts);
     return { derived, queryTriples, queryDerived };
   } finally {
-    __exitReasoningRun();
+    exitReasoningRun();
   }
 }