eyeprolog 0.5.3

package/src/solver.js

@@ -0,0 +1,1125 @@
+// Depth-first EyeProlog solver with builtin dispatch, memoization, and guarded recursion handling.
+// Most semantic decisions still flow through unification; optimizations only select candidates earlier.
+import {
+  COMPOUND, Env, compound, copyResolved, deref, flattenConjunction, freshTerm,
+  numberTerm, numberTextFromDouble, termIsGround, termToString, unify, variantTerms,
+} from './term.js';
+import { PrologError } from './iso.js';
+import { getEyePrologRegistry } from './library.js';
+import { selectClauseCandidates, selectClauseCandidatesForValues, selectGroundClauseCandidates } from './program.js';
+import { StreamManager } from './io.js';
+
+let freshCounter = 0;
+
+export function nextFreshId() {
+  return ++freshCounter;
+}
+
+export class Solver {
+  constructor(program, options = {}) {
+    this.registry = options.registry ?? getEyePrologRegistry();
+    this.program = program;
+    this.mutableProgram = program.mutable === true;
+    this.programRevision = this.program.revision ?? 0;
+    this.maxDepth = options.maxDepth ?? 100000;
+    this.solutionLimit = options.solutionLimit ?? 10000000;
+    this.solutionsSeen = 0;
+    this.prologFlags = options.prologFlags ?? defaultPrologFlags(this.registry?.eyePrologLibrary ? 'fail' : 'error');
+    this.charConversions = options.charConversions ?? new Map();
+    if (!options.prologFlags) {
+      for (const [flag, value] of program.prologFlagDirectives ?? []) {
+        const definition = this.prologFlags.get(flag.name);
+        if (flag.type === 'atom' && value.type === 'atom' && definition?.changeable && definition.allowed.includes(value.name)) {
+          definition.value = value;
+        }
+      }
+    }
+    if (!options.charConversions) {
+      for (const [input, output] of program.charConversionDirectives ?? []) {
+        if (input.type === 'atom' && output.type === 'atom' &&
+            Array.from(input.name).length === 1 && Array.from(output.name).length === 1) {
+          if (input.name === output.name) this.charConversions.delete(input.name);
+          else this.charConversions.set(input.name, output.name);
+        }
+      }
+    }
+    this.io = options.io ?? new StreamManager(options.ioOptions);
+    this.solveStacks = [];
+    this.active = [];
+    this.memo = new Map();
+    this.tableCoordinator = null;
+    this.groundChainSuccess = new Set();
+    this.compactChainSuccess = new Map();
+    this.stats = {
+      completed_goal_lists: 0,
+      solve_goals_calls: 0,
+      solve_one_goal_calls: 0,
+      unify_calls: 0,
+      max_depth: 0,
+      max_goal_count: 0,
+      deterministic_builtin_successes: 0,
+      deterministic_builtin_failures: 0,
+      table_fixpoint_rounds: 0,
+    };
+  }
+
+  cloneForInnerGoal(solutionLimit = this.solutionLimit) {
+    const solver = new Solver(this.program, {
+      registry: this.registry,
+      maxDepth: this.maxDepth,
+      solutionLimit,
+      prologFlags: this.prologFlags,
+      charConversions: this.charConversions,
+      io: this.io,
+    });
+    solver.memo = this.memo;
+    solver.groundChainSuccess = this.groundChainSuccess;
+    solver.compactChainSuccess = this.compactChainSuccess;
+    return solver;
+  }
+
+  syncProgramRevision() {
+    if (!this.mutableProgram) {
+      if (this.program.mutable !== true) return;
+      this.mutableProgram = true;
+    }
+    const revision = this.program.revision ?? 0;
+    if (revision === this.programRevision) return;
+    this.programRevision = revision;
+    this.memo.clear();
+    this.tableCoordinator = null;
+    this.groundChainSuccess.clear();
+    this.compactChainSuccess.clear();
+  }
+
+  absorbStatsFrom(child) {
+    if (!child || child === this || !child.stats) return;
+    for (const [key, value] of Object.entries(child.stats)) {
+      if (key === 'max_depth' || key === 'max_goal_count') {
+        this.stats[key] = Math.max(this.stats[key] ?? 0, value ?? 0);
+      } else {
+        this.stats[key] = (this.stats[key] ?? 0) + (value ?? 0);
+      }
+    }
+  }
+
+  runInitializations() {
+    for (const goal of this.program.initializations ?? []) {
+      let succeeded = false;
+      for (const _ of this.solve([goal], new Env(), 0)) {
+        succeeded = true;
+        break;
+      }
+      if (!succeeded) throw new PrologError('initialization_error');
+    }
+  }
+
+  *solve(goals, env = new Env(), depth = 0) {
+    if (!Array.isArray(goals)) goals = [goals];
+
+    const savedActive = this.active;
+    let registeredStack = null;
+    try {
+      const stack = [{ kind: 'goals', goals, env, depth, active: savedActive.slice() }];
+      registeredStack = stack;
+      this.solveStacks.push(stack);
+      while (stack.length) {
+      const frame = stack.pop();
+      this.syncProgramRevision();
+      if (frame.kind === 'resumeBuiltin') {
+        if (this.solutionsSeen >= this.solutionLimit) continue;
+        const result = frame.iterator.next();
+        if (result.done) continue;
+        stack.push(frame);
+        stack.push({
+          kind: 'goals',
+          goals: frame.goals,
+          env: result.value,
+          depth: frame.depth,
+          active: frame.active,
+        });
+        continue;
+      }
+      if (frame.kind === 'completeTableFixpointRound') {
+        if (frame.revision !== this.programRevision) continue;
+        frame.entry.computing = false;
+        const answerCount = frame.entry.answers.length;
+        if (this.tableCoordinator?.cycleSeen && answerCount > frame.answerCountBefore) {
+          scheduleTableFixpointRound(stack, this, frame);
+        } else {
+          for (const entry of this.tableCoordinator?.entries ?? [frame.entry]) {
+            entry.computing = false;
+            entry.complete = true;
+          }
+          this.tableCoordinator = null;
+          pushMemoAnswerFrames(stack, frame.entry, frame.goal, frame.rest, frame.env, frame.depth, frame.active, this);
+        }
+        continue;
+      }
+      if (frame.kind === 'completeMemo') {
+        if (frame.revision !== this.programRevision) continue;
+        frame.entry.computing = false;
+        frame.entry.complete = true;
+        continue;
+      }
+
+      goals = frame.goals;
+      env = frame.env;
+      depth = frame.depth;
+      let active = frame.active;
+
+      while (true) {
+        this.syncProgramRevision();
+        this.stats.solve_goals_calls++;
+        this.stats.max_depth = Math.max(this.stats.max_depth, depth);
+        this.stats.max_goal_count = Math.max(this.stats.max_goal_count, goals.length);
+        if (depth > this.maxDepth || this.solutionsSeen >= this.solutionLimit) break;
+
+        if (goals.length === 0) {
+          this.solutionsSeen++;
+          this.stats.completed_goal_lists++;
+          this.active = active;
+          yield env;
+          break;
+        }
+
+        const first = goals[0];
+        if (first?.kind === 'releaseActive') {
+          active = active.slice(0, -1);
+          goals = goals.slice(1);
+          continue;
+        }
+        if (first?.kind === 'memoStore') {
+          if (first.revision === this.programRevision) rememberMemoAnswer(first.entry, first.goal, env);
+          if (goals.length === 1) break;
+          goals = goals.slice(1);
+          continue;
+        }
+
+        // EyeProlog normally solves left-to-right, but ready deterministic builtins can
+        // be run early as pure filters. Stop at internal sentinels so rule-body
+        // active guards are released before the caller's remaining goals are seen.
+        const selectedIndex = selectReadyDeterministicBuiltin(goals, env, this.registry);
+        const goal = goals[selectedIndex];
+        const rest = selectedIndex === 0 ? goals.slice(1) : [...goals.slice(0, selectedIndex), ...goals.slice(selectedIndex + 1)];
+        if (goal.type === 'atom' && goal.name === '!' && goal.arity === 0) {
+          const marker = active[active.length - 1] ?? null;
+          for (const solveStack of this.solveStacks) {
+            for (let i = solveStack.length - 1; i >= 0; i--) {
+              if (marker == null || solveStack[i].active?.includes(marker)) solveStack.splice(i, 1);
+            }
+          }
+          goals = rest;
+          depth++;
+          continue;
+        }
+        if (goal.type === COMPOUND && goal.name === ',' && goal.arity === 2) {
+          goals = [...flattenConjunction(goal), ...rest];
+          depth++;
+          continue;
+        }
+
+        const callable = goal.type === COMPOUND || goal.type === 'atom';
+        const def = callable ? this.registry.get(goal.name, goal.arity) : null;
+        this.active = active;
+        if (def && builtinIsReadyOrAuthoritative(def, this, goal, env)) {
+          const iterator = def.handler({ solver: this, goal, env });
+          const firstResult = iterator.next();
+          if (def.deterministic) {
+            if (!firstResult.done) this.stats.deterministic_builtin_successes++;
+            else this.stats.deterministic_builtin_failures++;
+          }
+          if (firstResult.done) break;
+          if (!def.deterministic) {
+            stack.push({
+              kind: 'resumeBuiltin',
+              iterator,
+              goals: rest,
+              depth: depth + 1,
+              active,
+            });
+          }
+          goals = rest;
+          env = firstResult.value;
+          depth++;
+          continue;
+        }
+
+        this.stats.solve_one_goal_calls++;
+        if (!callable) break;
+        const group = this.program.findGroup(goal.name, goal.arity);
+        if (!group) {
+          if (this.prologFlags.get('unknown')?.value?.name === 'error') {
+            throw new PrologError(
+              'existence_error(procedure)',
+              compound('/', [compound(goal.name, []), numberTerm(goal.arity)]),
+            );
+          }
+          break;
+        }
+
+        if (group.tabled) {
+          const key = memoKey(goal, env, group);
+          if (key.hasBound) {
+            const mapKey = `${goal.name}/${goal.arity}:${key.text}`;
+            let entry = this.memo.get(mapKey);
+            if (!entry) {
+              entry = makeMemoEntry();
+              this.memo.set(mapKey, entry);
+            }
+            if (this.tableCoordinator) this.tableCoordinator.entries.add(entry);
+            if (entry.complete) {
+              pushMemoAnswerFrames(stack, entry, goal, rest, env, depth, active, this);
+              break;
+            }
+            if (!entry.computing) {
+              if (!this.tableCoordinator) {
+                this.tableCoordinator = { entry, cycleSeen: false, entries: new Set([entry]) };
+                scheduleTableFixpointRound(stack, this, { entry, group, goal, rest, env, depth, active });
+              } else {
+                entry.computing = true;
+                stack.push({ kind: 'completeMemo', entry, revision: this.programRevision });
+                pushUserGoalUncachedFrames(stack, this, group, goal, [{ kind: 'memoStore', entry, goal, revision: this.programRevision }, ...rest], env, depth, active);
+              }
+              break;
+            }
+            if (this.tableCoordinator && activeVariantIn(goal, env, active)) {
+              this.tableCoordinator.cycleSeen = true;
+            }
+            pushMemoAnswerFrames(stack, entry, goal, rest, env, depth, active, this);
+            break;
+          }
+        }
+
+        if (!group.tabled && tryPushScalarFactRunFrames(stack, this, [goal, ...rest], env, depth, active)) break;
+        pushUserGoalUncachedFrames(stack, this, group, goal, rest, env, depth, active);
+        break;
+      }
+      }
+    } finally {
+      const stackIndex = this.solveStacks.indexOf(registeredStack);
+      if (stackIndex >= 0) this.solveStacks.splice(stackIndex, 1);
+      this.active = savedActive;
+    }
+  }
+
+  activeVariant(goal, env) {
+    return activeVariantIn(goal, env, this.active);
+  }
+
+  *solveUserGoal(goal, rest, env, depth) {
+    this.stats.solve_one_goal_calls++;
+    if (depth > this.maxDepth || this.solutionsSeen >= this.solutionLimit) return;
+    if (goal.type !== COMPOUND && goal.type !== 'atom') return;
+    const group = this.program.findGroup(goal.name, goal.arity);
+    if (!group) return;
+    if (group.tabled) {
+      yield* this.solveMemoizedGoal(group, goal, rest, env, depth);
+      return;
+    }
+    yield* this.solveUserGoalUncached(group, goal, rest, env, depth);
+  }
+
+  *solveMemoizedGoal(group, goal, rest, env, depth) {
+    yield* this.solve([goal, ...rest], env, depth);
+  }
+
+  *solveUserGoalUncached(group, goal, rest, env, depth) {
+    if (group.recursive && !group.cutRecursive && !group.linearNumeric && this.activeVariant(goal, env)) return;
+    // Program indexes provide candidate clauses, but every candidate is still
+    // freshened and unified below. The index is a performance hint, not a
+    // semantic shortcut.
+    const candidates = selectClauseCandidates(group, goal, env);
+    for (const pass of [candidates.primary, candidates.fallback]) {
+      for (let candidateIndex = 0; candidateIndex < clauseCandidateLength(pass); candidateIndex++) {
+        const clause = clauseCandidateAt(pass, candidateIndex);
+        if (clause.body.length === 0 && clause.scalarHead) {
+          const next = matchScalarFact(goal, clause.head, env);
+          if (!next) continue;
+          this.stats.unify_calls++;
+          yield* this.solve(rest, next, depth + 1);
+          if (this.solutionsSeen >= this.solutionLimit) return;
+          continue;
+        }
+        if (headCannotMatch(goal, clause.head, env)) continue;
+        const id = nextFreshId();
+        const freshHead = freshTerm(clause.head, id);
+        const freshBody = clause.body.map((term) => freshTerm(term, id));
+        const next = env.clone();
+        this.stats.unify_calls++;
+        if (!unify(goal, freshHead, next)) continue;
+        if (freshBody.length === 0) {
+          yield* this.solve(rest, next, depth + 1);
+        } else {
+          yield* this.solveRuleBodyThenRest(goal, env, freshBody, rest, next, depth);
+        }
+        if (this.solutionsSeen >= this.solutionLimit) return;
+      }
+    }
+  }
+  *solveRuleBodyThenRest(goal, goalEnv, body, rest, env, depth) {
+    // Match the C engine's active-call lifetime: the active guard protects
+    // expansion of the current rule body, but it must be released before
+    // the caller's remaining goals are solved. Keeping the goal active
+    // through rest goals over-prunes valid transitive/recursive derivations.
+    this.active.push({ goal, env: goalEnv });
+    for (const bodyEnv of this.solve(body, env, depth + 1)) {
+      if (this.solutionsSeen > 0) this.solutionsSeen--;
+      this.active.pop();
+      yield* this.solve(rest, bodyEnv, depth + 1);
+      this.active.push({ goal, env: goalEnv });
+      if (this.solutionsSeen >= this.solutionLimit) break;
+    }
+    this.active.pop();
+  }
+
+}
+
+function defaultPrologFlags(unknown = 'error') {
+  return new Map([
+    ['bounded', { value: compound('false', []), allowed: ['false'], changeable: false }],
+    ['integer_rounding_function', { value: compound('toward_zero', []), allowed: ['toward_zero'], changeable: false }],
+    ['char_conversion', { value: compound('on', []), allowed: ['on', 'off'], changeable: true }],
+    ['debug', { value: compound('off', []), allowed: ['on', 'off'], changeable: true }],
+    ['max_arity', { value: compound('unbounded', []), allowed: ['unbounded'], changeable: false }],
+    ['unknown', { value: compound(unknown, []), allowed: ['error', 'fail', 'warning'], changeable: true }],
+    ['double_quotes', { value: compound('atom', []), allowed: ['chars', 'codes', 'atom'], changeable: true }],
+  ]);
+}
+
+
+function makeMemoEntry() {
+  return { computing: false, complete: false, answers: [], answerKeys: new Set() };
+}
+
+function scheduleTableFixpointRound(stack, solver, frame) {
+  solver.stats.table_fixpoint_rounds++;
+  solver.tableCoordinator.cycleSeen = false;
+  for (const entry of solver.tableCoordinator.entries) {
+    entry.computing = false;
+    entry.complete = false;
+  }
+  frame.entry.computing = true;
+  const nextFrame = {
+    kind: 'completeTableFixpointRound',
+    revision: solver.programRevision,
+    entry: frame.entry,
+    group: frame.group,
+    goal: frame.goal,
+    rest: frame.rest,
+    env: frame.env,
+    depth: frame.depth,
+    active: frame.active,
+    answerCountBefore: frame.entry.answers.length,
+  };
+  stack.push(nextFrame);
+  pushUserGoalUncachedFrames(
+    stack,
+    solver,
+    frame.group,
+    frame.goal,
+    [{ kind: 'memoStore', entry: frame.entry, goal: frame.goal, revision: solver.programRevision }],
+    frame.env,
+    frame.depth,
+    frame.active,
+  );
+}
+
+
+function pushMemoAnswerFrames(stack, entry, goal, rest, env, depth, active, solver) {
+  for (let answerIndex = entry.answers.length - 1; answerIndex >= 0; answerIndex--) {
+    // Stored table variables belong to the answer template, not to any caller.
+    // Freshen the complete tuple together so sharing within an answer is kept
+    // while separate replays cannot alias otherwise independent call variables.
+    const storedArgs = entry.answers[answerIndex];
+    const answerArgs = storedArgs.every((arg) => termIsGround(arg))
+      ? storedArgs
+      : freshTerm(compound('$memo_answer', storedArgs), nextFreshId()).args;
+    const next = env.clone();
+    let ok = true;
+    for (let i = 0; i < goal.arity; i++) {
+      solver.stats.unify_calls++;
+      if (!unify(goal.args[i], answerArgs[i], next)) { ok = false; break; }
+    }
+    if (ok) stack.push({ kind: 'goals', goals: rest, env: next, depth: depth + 1, active });
+  }
+}
+
+function pushUserGoalUncachedFrames(stack, solver, group, goal, rest, env, depth, active) {
+  if (group.recursive && !group.cutRecursive && !group.linearNumeric && activeVariantIn(goal, env, active)) return;
+  if (group.fastPi && pushFastPiFrames(stack, goal, rest, env, depth, active)) return;
+  if (tryPushGroundChainFrames(stack, solver, group, goal, rest, env, depth, active)) return;
+  const candidates = selectClauseCandidates(group, goal, env);
+  const frames = [];
+  const invocation = { goal, env };
+  const guarded = !group.linearNumeric;
+  const release = guarded ? [{ kind: 'releaseActive' }] : [];
+  const nextActive = guarded ? [...active, invocation] : active;
+  for (const pass of [candidates.primary, candidates.fallback]) {
+    for (let candidateIndex = 0; candidateIndex < clauseCandidateLength(pass); candidateIndex++) {
+      const clause = clauseCandidateAt(pass, candidateIndex);
+      if (clause.body.length === 0 && clause.scalarHead) {
+        const next = matchScalarFact(goal, clause.head, env);
+        if (next) {
+          solver.stats.unify_calls++;
+          frames.push({
+            kind: 'goals',
+            goals: [...release, ...rest],
+            env: next,
+            depth: depth + 1,
+            active: nextActive,
+          });
+        }
+        continue;
+      }
+      if (headCannotMatch(goal, clause.head, env)) continue;
+      const id = nextFreshId();
+      const freshHead = freshTerm(clause.head, id);
+      const freshBody = clause.body.map((term) => freshTerm(term, id));
+      const next = env.clone();
+      solver.stats.unify_calls++;
+      if (!unify(goal, freshHead, next)) continue;
+      if (freshBody.length === 0) {
+        frames.push({
+          kind: 'goals',
+          goals: [...release, ...rest],
+          env: next,
+          depth: depth + 1,
+          active: nextActive,
+        });
+      } else {
+        frames.push({
+          kind: 'goals',
+          goals: [...freshBody, ...release, ...rest],
+          env: next,
+          depth: depth + 1,
+          active: nextActive,
+        });
+      }
+    }
+  }
+  for (let i = frames.length - 1; i >= 0; i--) stack.push(frames[i]);
+}
+
+function pushFastPiFrames(stack, goal, rest, env, depth, active) {
+  const values = goal.args.map((arg) => deref(arg, env));
+  if ([0, 1, 2, 4].some((index) => values[index].type !== 'number')) return false;
+  let a = Number(values[0].name);
+  const b = Number(values[1].name);
+  let sum = Number(values[2].name);
+  let sign = Number(values[4].name);
+  if (![a, b, sum, sign].every(Number.isFinite) || a > b) return true;
+  while (a < b) {
+    sum += sign / (2 * a * (2 * a + 1) * (2 * a + 2));
+    a += 1;
+    sign = -sign;
+  }
+  const next = env.clone();
+  if (!unify(goal.args[3], numberTerm(numberTextFromDouble(sum)), next)) return true;
+  stack.push({ kind: 'goals', goals: rest, env: next, depth: depth + 1, active });
+  return true;
+}
+
+
+
+const SCALAR_FACT_RUN_FRAME_LIMIT = 100000;
+
+function tryPushScalarFactRunFrames(stack, solver, goals, env, depth, active) {
+  // Consecutive lookups into predicates that are entirely scalar ground facts
+  // are common in data-heavy joins. Execute such a prefix as one iterative join
+  // using local binding arrays, so intermediate fact candidates do not allocate
+  // cloned Env maps.
+  let runLength = 0;
+  const groups = [];
+  while (runLength < goals.length) {
+    const goal = goals[runLength];
+    if (!goal || goal.kind === 'releaseActive' || goal.kind === 'memoStore') break;
+    if (goal.type !== COMPOUND) break;
+    const def = solver.registry.get(goal.name, goal.arity);
+    if (def) break;
+    const group = solver.program.findGroup(goal.name, goal.arity);
+    if (!group || group.tabled || !group.scalarFactsOnly) break;
+    groups.push(group);
+    runLength++;
+  }
+  if (runLength < 2) return false;
+
+  const rest = goals.slice(runLength);
+  const localStack = [{ index: 0, names: [], values: [], depth }];
+  const frames = [];
+
+  while (localStack.length) {
+    const state = localStack.pop();
+    solver.stats.max_depth = Math.max(solver.stats.max_depth, state.depth);
+    if (state.index === runLength) {
+      const next = env.clone();
+      for (let i = 0; i < state.names.length; i++) next.bind(state.names[i], state.values[i]);
+      frames.push({ kind: 'goals', goals: rest, env: next, depth: state.depth, active });
+      if (frames.length > SCALAR_FACT_RUN_FRAME_LIMIT) return false;
+      continue;
+    }
+
+    const goal = goals[state.index];
+    if (activeMightContain(goal, active) && activeVariantIn(goal, envWithLocal(env, state.names, state.values), active)) continue;
+    solver.stats.solve_one_goal_calls++;
+    const candidates = selectScalarFactCandidates(groups[state.index], goal, env, state.names, state.values);
+    const nextStates = [];
+    for (const pass of [candidates.primary, candidates.fallback]) {
+      for (let candidateIndex = 0; candidateIndex < clauseCandidateLength(pass); candidateIndex++) {
+        const clause = clauseCandidateAt(pass, candidateIndex);
+        const match = matchScalarFactLocal(goal, clause.head, env, state.names, state.values);
+        if (!match) continue;
+        solver.stats.unify_calls++;
+        nextStates.push({ index: state.index + 1, names: match.names, values: match.values, depth: state.depth + 1 });
+      }
+    }
+    for (let i = nextStates.length - 1; i >= 0; i--) localStack.push(nextStates[i]);
+    if (solver.solutionsSeen >= solver.solutionLimit) break;
+  }
+
+  for (let i = frames.length - 1; i >= 0; i--) stack.push(frames[i]);
+  return true;
+}
+
+
+function activeMightContain(goal, active) {
+  if (active.length === 0 || goal.type !== COMPOUND) return false;
+  for (const entry of active) {
+    const activeGoal = entry.goal;
+    if (activeGoal?.type === COMPOUND && activeGoal.name === goal.name && activeGoal.arity === goal.arity) return true;
+  }
+  return false;
+}
+
+function envWithLocal(env, names, values) {
+  if (names.length === 0) return env;
+  return {
+    has(name) { return names.includes(name) || env.has(name); },
+    get(name) {
+      const index = names.indexOf(name);
+      return index >= 0 ? values[index] : env.get(name);
+    },
+  };
+}
+
+function selectScalarFactCandidates(group, goal, env, names, values) {
+  const positions = [];
+  const boundValues = [];
+  for (let i = 0; i < goal.arity; i++) {
+    const arg = derefScalarMatch(goal.args[i], env, names, values);
+    if (!isScalarTerm(arg)) continue;
+    positions.push(i);
+    boundValues.push(arg);
+  }
+  return selectClauseCandidatesForValues(group, positions, boundValues);
+}
+
+function matchScalarFactLocal(goal, head, env, names, values) {
+  if (goal.type !== COMPOUND || head.type !== COMPOUND) return null;
+  if (goal.name !== head.name || goal.arity !== head.arity) return null;
+
+  let nextNames = names;
+  let nextValues = values;
+  for (let i = 0; i < goal.arity; i++) {
+    const factArg = head.args[i];
+    const arg = derefScalarMatch(goal.args[i], env, nextNames, nextValues);
+    if (arg.type === 'var') {
+      if (nextNames === names) {
+        nextNames = names.slice();
+        nextValues = values.slice();
+      }
+      nextNames.push(arg.name);
+      nextValues.push(factArg);
+      continue;
+    }
+    if (!sameScalarTerm(arg, factArg)) return null;
+  }
+  return { names: nextNames, values: nextValues };
+}
+
+function matchScalarFact(goal, head, env) {
+  // A scalar ground fact has no variables to freshen and no compound structure
+  // to traverse. Match the goal arguments directly and clone only after the
+  // candidate has succeeded.
+  if (goal.type !== COMPOUND || head.type !== COMPOUND) return null;
+  if (goal.name !== head.name || goal.arity !== head.arity) return null;
+
+  const names = [];
+  const values = [];
+  for (let i = 0; i < goal.arity; i++) {
+    const factArg = head.args[i];
+    let arg = derefScalarMatch(goal.args[i], env, names, values);
+    if (arg.type === 'var') {
+      names.push(arg.name);
+      values.push(factArg);
+      continue;
+    }
+    if (!sameScalarTerm(arg, factArg)) return null;
+  }
+
+  const next = env.clone();
+  for (let i = 0; i < names.length; i++) next.bind(names[i], values[i]);
+  return next;
+}
+
+function derefScalarMatch(term, env, names, values) {
+  let current = term;
+  for (let guard = 0; current?.type === 'var' && guard < 128; guard++) {
+    const localIndex = names.indexOf(current.name);
+    if (localIndex >= 0) current = values[localIndex];
+    else if (env.has(current.name)) current = env.get(current.name);
+    else break;
+  }
+  return current;
+}
+
+function scalarSetContainer() {
+  return { atom: new Set(), string: new Set(), number: new Set() };
+}
+
+function compactChainCacheFor(solver, group, first) {
+  let groupCache = solver.compactChainSuccess.get(group);
+  if (!groupCache) {
+    groupCache = { atom: new Map(), string: new Map(), number: new Map() };
+    solver.compactChainSuccess.set(group, groupCache);
+  }
+  const byFirstName = groupCache[first.type];
+  let cache = byFirstName.get(first.name);
+  if (!cache) {
+    cache = scalarSetContainer();
+    byFirstName.set(first.name, cache);
+  }
+  return cache;
+}
+
+function rememberCompactChainSuccess(cache, seen) {
+  for (const type of ['atom', 'string', 'number']) {
+    let index = 0;
+    const values = seen[type];
+    const last = values.size - 1;
+    for (const name of values) {
+      if ((index & 63) === 0 || index === last) cache[type].add(name);
+      index++;
+    }
+  }
+}
+
+function compactIndexBucket(index, type, name) {
+  if (type === 'atom') return index.atomBuckets.get(name) ?? null;
+  if (type === 'string') return index.stringBuckets.get(name) ?? null;
+  if (type === 'number') return index.numberBuckets.get(name) ?? null;
+  return null;
+}
+
+function tryPushCompactBinaryChainFrames(stack, solver, group, goal, rest, env, depth, active) {
+  if (active.length !== 0 || goal.type !== COMPOUND || goal.arity !== 2) return false;
+  const resolved = copyResolved(goal, env);
+  const first = resolved.args[0];
+  let secondType = resolved.args[1]?.type;
+  let secondName = resolved.args[1]?.name;
+  if (!isScalarTerm(first) || !['atom', 'string', 'number'].includes(secondType)) return false;
+
+  const index = group.argIndexes[1];
+  if (!index?.sawScalar || index.fallback.length !== 0) return false;
+  const cache = compactChainCacheFor(solver, group, first);
+  const seen = scalarSetContainer();
+  let currentDepth = depth;
+
+  while (true) {
+    if (solver.solutionsSeen >= solver.solutionLimit) return true;
+    solver.stats.max_depth = Math.max(solver.stats.max_depth, currentDepth);
+    const seenSet = seen[secondType];
+    if (!seenSet || seenSet.has(secondName)) return true;
+    if (cache[secondType].has(secondName)) {
+      rememberCompactChainSuccess(cache, seen);
+      stack.push({ kind: 'goals', goals: rest, env, depth: depth + 1, active });
+      return true;
+    }
+    seenSet.add(secondName);
+
+    const candidates = compactIndexBucket(index, secondType, secondName);
+    if (clauseCandidateLength(candidates) !== 1) return false;
+    const clause = clauseCandidateAt(candidates, 0);
+    if (clause?.compactBinary !== true || clause.headName !== group.name) return false;
+    if (clause.head1Type !== secondType || clause.head1Name !== secondName) return true;
+    if (clause.head0Type !== 'var' &&
+        (clause.head0Type !== first.type || clause.head0Name !== first.name)) return true;
+
+    if (clause.bodyName == null) {
+      rememberCompactChainSuccess(cache, seen);
+      stack.push({ kind: 'goals', goals: rest, env, depth: depth + 1, active });
+      return true;
+    }
+    if (clause.bodyName !== group.name || clause.head0Type !== 'var' ||
+        clause.body0Type !== 'var' || clause.body0Name !== clause.head0Name ||
+        !['atom', 'string', 'number'].includes(clause.body1Type)) return false;
+
+    secondType = clause.body1Type;
+    secondName = clause.body1Name;
+    currentDepth++;
+  }
+}
+
+function tryPushGroundChainFrames(stack, solver, group, goal, rest, env, depth, active) {
+  if (tryPushCompactBinaryChainFrames(stack, solver, group, goal, rest, env, depth, active)) return true;
+  // Compress deterministic ground single-goal chains such as deep taxonomy
+  // proofs: a(ind, n100000) -> a(ind, n99999) -> ... -> a(ind, n0).
+  // This is a search-control optimization only. It fires only while each step
+  // has exactly one matching clause and a single ground body goal; otherwise the
+  // normal clause path below remains authoritative.
+  if (!termIsGround(goal, env)) return false;
+
+  const baseEnv = env;
+  let currentGroup = group;
+  let currentGoal = copyResolved(goal, env);
+  let currentDepth = depth;
+  const currentEnv = new Env();
+  const seen = new Set();
+
+  while (true) {
+    // The compressed path is iterative and protected by `seen`, so it does not
+    // consume JavaScript recursion depth the way the ordinary solver path does.
+    // Keep recording the logical depth for diagnostics, but do not cut off long
+    // finite taxonomy chains with the recursive maxDepth guard.
+    if (solver.solutionsSeen >= solver.solutionLimit) return true;
+    solver.stats.max_depth = Math.max(solver.stats.max_depth, currentDepth);
+    const key = groundChainKey(currentGoal);
+    if (seen.has(key)) return true;
+    if (activeVariantIn(currentGoal, currentEnv, active)) return true;
+    if (solver.groundChainSuccess.has(key)) {
+      rememberGroundChainSuccess(solver, seen);
+      stack.push({ kind: 'goals', goals: rest, env: baseEnv, depth: depth + 1, active });
+      return true;
+    }
+    seen.add(key);
+
+    const candidates = selectGroundClauseCandidates(currentGroup, currentGoal);
+    const matches = [];
+    for (const pass of [candidates]) {
+      for (let candidateIndex = 0; candidateIndex < clauseCandidateLength(pass); candidateIndex++) {
+        const clause = clauseCandidateAt(pass, candidateIndex);
+        if (headCannotMatch(currentGoal, clause.head, currentEnv)) continue;
+        const match = matchGroundClause(currentGoal, clause);
+        if (match === undefined) return false;
+        if (match === null) continue;
+        matches.push(match);
+        if (matches.length > 1) return false;
+      }
+    }
+
+    if (matches.length !== 1) return false;
+    const match = matches[0];
+    if (match.done) {
+      rememberGroundChainSuccess(solver, seen);
+      stack.push({ kind: 'goals', goals: rest, env: baseEnv, depth: depth + 1, active });
+      return true;
+    }
+    const resolvedNextGoal = match.nextGoal;
+    const nextGroup = solver.program.findGroup(resolvedNextGoal.name, resolvedNextGoal.arity);
+    if (!nextGroup) return false;
+
+    currentGoal = resolvedNextGoal;
+    currentGroup = nextGroup;
+    currentDepth++;
+  }
+}
+
+
+
+
+
+function clauseCandidateLength(candidate) {
+  return candidate == null ? 0 : Array.isArray(candidate) ? candidate.length : 1;
+}
+
+function clauseCandidateAt(candidate, index) {
+  return Array.isArray(candidate) ? candidate[index] : index === 0 ? candidate : undefined;
+}
+
+function matchGroundClause(goal, clause) {
+  if (clause.head.type !== COMPOUND || goal.type !== COMPOUND) return undefined;
+  if (clause.head.name !== goal.name || clause.head.arity !== goal.arity) return null;
+  if (goal.arity === 2) return matchGroundBinaryClause(goal, clause);
+
+  const names = [];
+  const values = [];
+  for (let i = 0; i < goal.arity; i++) {
+    const headArg = clause.head.args[i];
+    const goalArg = goal.args[i];
+    if (headArg.type === 'var') {
+      let index = names.indexOf(headArg.name);
+      if (index < 0) {
+        names.push(headArg.name);
+        values.push(goalArg);
+      } else if (!sameGroundTerm(values[index], goalArg)) {
+        return null;
+      }
+    } else if (isScalarTerm(headArg)) {
+      if (!sameGroundTerm(headArg, goalArg)) return null;
+    } else {
+      return undefined;
+    }
+  }
+
+  if (clause.body.length === 0) return { done: true };
+  if (clause.body.length !== 1) return undefined;
+  const bodyGoal = clause.body[0];
+  if (bodyGoal.type !== COMPOUND) return undefined;
+  const args = [];
+  for (const arg of bodyGoal.args) {
+    if (arg.type === 'var') {
+      const index = names.indexOf(arg.name);
+      if (index < 0) return undefined;
+      args.push(values[index]);
+    } else if (isScalarTerm(arg)) {
+      args.push(arg);
+    } else {
+      return undefined;
+    }
+  }
+  return { nextGoal: compound(bodyGoal.name, args) };
+}
+
+function matchGroundBinaryClause(goal, clause) {
+  const headArgs = clause.head.args;
+  const goalArgs = goal.args;
+  for (let i = 0; i < 2; i++) {
+    const headArg = headArgs[i];
+    if (headArg.type === 'var') {
+      for (let j = 0; j < i; j++) {
+        if (headArgs[j].type === 'var' && headArgs[j].name === headArg.name &&
+            !sameGroundTerm(goalArgs[j], goalArgs[i])) return null;
+      }
+    } else if (isScalarTerm(headArg)) {
+      if (!sameGroundTerm(headArg, goalArgs[i])) return null;
+    } else {
+      return undefined;
+    }
+  }
+
+  if (clause.body.length === 0) return { done: true };
+  if (clause.body.length !== 1) return undefined;
+  const bodyGoal = clause.body[0];
+  if (bodyGoal.type !== COMPOUND) return undefined;
+  const bodyArgs = new Array(bodyGoal.arity);
+  for (let i = 0; i < bodyGoal.arity; i++) {
+    const arg = bodyGoal.args[i];
+    if (arg.type === 'var') {
+      let found = false;
+      for (let j = 0; j < 2; j++) {
+        if (headArgs[j].type === 'var' && headArgs[j].name === arg.name) {
+          bodyArgs[i] = goalArgs[j];
+          found = true;
+          break;
+        }
+      }
+      if (!found) return undefined;
+    } else if (isScalarTerm(arg)) {
+      bodyArgs[i] = arg;
+    } else {
+      return undefined;
+    }
+  }
+  return { nextGoal: compound(bodyGoal.name, bodyArgs) };
+}
+
+function isScalarTerm(term) {
+  return term && (term.type === 'atom' || term.type === 'string' || term.type === 'number');
+}
+
+function sameScalarTerm(left, right) {
+  return isScalarTerm(left) && isScalarTerm(right) && left.type === right.type && left.name === right.name;
+}
+
+function sameGroundTerm(left, right) {
+  if (left?.type !== right?.type || left?.name !== right?.name) return false;
+  const arity = left.args?.length ?? 0;
+  if (arity !== (right.args?.length ?? 0)) return false;
+  for (let i = 0; i < arity; i++) if (!sameGroundTerm(left.args[i], right.args[i])) return false;
+  return true;
+}
+
+function groundChainKey(term) {
+  if (term?.type === COMPOUND) {
+    let out = `${term.name}/${term.arity}`;
+    for (let i = 0; i < term.arity; i++) out += `${groundChainKey(term.args[i])}`;
+    return out;
+  }
+  return `${term?.type ?? ''}:${term?.name ?? ''}`;
+}
+
+function rememberGroundChainSuccess(solver, seen) {
+  // Cache a sparse set of checkpoints. This preserves fast reuse of long
+  // deterministic chains without retaining every intermediate goal.
+  let index = 0;
+  const last = seen.size - 1;
+  for (const key of seen) {
+    if ((index & 63) === 0 || index === last) solver.groundChainSuccess.add(key);
+    index++;
+  }
+}
+
+function rememberMemoAnswer(entry, goal, env) {
+  const variables = new Map();
+  const answerKeys = [];
+  const answerArgs = goal.args.map((arg) => {
+    const answer = copyResolvedWithKey(arg, env, variables);
+    answerKeys.push(answer.key);
+    return answer.term;
+  });
+  const key = answerKeys.join('\x1f');
+  if (entry.answerKeys.has(key)) return;
+  entry.answerKeys.add(key);
+  entry.answers.push(answerArgs);
+}
+
+function activeVariantIn(goal, env, active) {
+  if (active.length === 0) return false;
+  let goalShape = null;
+  for (const entry of active) {
+    const candidate = entry.goal;
+    // Variant calls must have the same predicate indicator. Avoid walking
+    // large matrix/list arguments for every unrelated active predicate.
+    if (candidate?.type !== goal.type || candidate?.name !== goal.name ||
+        candidate?.arity !== goal.arity) continue;
+    goalShape ??= variantShape(goal, env);
+    entry.variantShape ??= variantShape(candidate, entry.env);
+    if (goalShape !== entry.variantShape) continue;
+    if (variantTerms(goal, env, candidate, entry.env)) return true;
+  }
+  return false;
+}
+
+function variantShape(term, env) {
+  if (term?.type !== COMPOUND) return '0';
+  return term.args.map((arg) => variantArgumentSize(arg, env)).join(',');
+}
+
+function variantArgumentSize(term, env) {
+  const pending = [term];
+  let size = 0;
+  while (pending.length > 0) {
+    const current = derefForLocal(pending.pop(), env);
+    size++;
+    // This is only a rejection key. Capping keeps pathological cyclic or very
+    // large terms bounded; equal capped sizes still fall through to the exact
+    // variant check.
+    if (size > 4096) return 4097;
+    if (current?.type === COMPOUND) {
+      for (let index = 0; index < current.arity; index++) pending.push(current.args[index]);
+    }
+  }
+  return size;
+}
+
+
+function builtinIsReadyOrAuthoritative(def, solver, goal, env) {
+  if (typeof def.shouldUse === 'function' && !def.shouldUse({ solver, goal, env })) return false;
+  if (typeof def.ready !== 'function') return true;
+  if (def.ready(goal, env)) return true;
+  return !def.fallbackWhenNotReady;
+}
+
+function selectReadyDeterministicBuiltin(goals, env, registry) {
+  for (let i = 0; i < goals.length; i++) {
+    const goal = goals[i];
+    if (goal?.kind === 'releaseActive' || goal?.kind === 'memoStore') return 0;
+    if (goal.type !== COMPOUND && goal.type !== 'atom') continue;
+    const def = registry.get(goal.name, goal.arity);
+    if (!def?.deterministic || typeof def.ready !== 'function') continue;
+    if (typeof def.shouldUse === 'function') continue;
+    if (def.ready(goal, env)) return i;
+  }
+  return 0;
+}
+
+function headCannotMatch(goal, head, env) {
+  if (goal.type !== COMPOUND || head.type !== COMPOUND) return false;
+  if (goal.name !== head.name || goal.arity !== head.arity) return true;
+  for (let i = 0; i < goal.arity; i++) {
+    const a = goal.args[i];
+    const b = head.args[i];
+    // Keep this only as a cheap scalar rejection. unify() remains authoritative.
+    const da = derefForLocal(a, env);
+    if (isScalarTerm(da) && isScalarTerm(b) && !sameScalarTerm(da, b)) return true;
+  }
+  return false;
+}
+
+function derefForLocal(term, env) {
+  let current = term;
+  while (current.type === 'var') {
+    const next = env.get(current.name);
+    if (next === undefined) break;
+    current = next;
+  }
+  return current;
+}
+
+function memoKey(goal, env, group = null) {
+  let hasBound = false;
+  const variables = new Map();
+  const required = group?.tableInputPositions ?? [];
+  const ground = [];
+  const parts = goal.args.map((arg) => {
+    const value = derefForLocal(arg, env);
+    if (value.type === 'var') {
+      ground.push(false);
+      return '_';
+    }
+    const canonical = canonicalTermInfo(value, env, variables);
+    ground.push(canonical.ground);
+    if (canonical.ground) hasBound = true;
+    return canonical.key;
+  });
+  if (required.length > 0) {
+    hasBound = required.some((index) => ground[index]);
+  }
+  return { hasBound, text: parts.join('|') };
+}
+
+function canonicalTermInfo(term, env, variables) {
+  const value = derefForLocal(term, env);
+  if (value.type === 'var') {
+    let id = variables.get(value.name);
+    if (id == null) {
+      id = variables.size;
+      variables.set(value.name, id);
+    }
+    return { key: `var:${id}`, ground: false };
+  }
+  if (!value.args?.length) return { key: `${value.type}:${value.name}`, ground: true };
+  let ground = true;
+  const keys = value.args.map((arg) => {
+    const child = canonicalTermInfo(arg, env, variables);
+    if (!child.ground) ground = false;
+    return child.key;
+  });
+  return { key: `${value.type}:${value.name}(${keys.join(',')})`, ground };
+}
+
+function copyResolvedWithKey(term, env, variables) {
+  const value = derefForLocal(term, env);
+  if (value.type === 'var') {
+    let id = variables.get(value.name);
+    if (id == null) {
+      id = variables.size;
+      variables.set(value.name, id);
+    }
+    return { term: termModuleCache.variable(value.name), key: `var:${id}` };
+  }
+  if (!value.args?.length) {
+    return {
+      term: new termModuleCache.Term(value.type, value.name, value.args),
+      key: `${value.type}:${value.name}`,
+    };
+  }
+  const children = value.args.map((arg) => copyResolvedWithKey(arg, env, variables));
+  return {
+    term: termModuleCache.compound(value.name, children.map((child) => child.term)),
+    key: `${value.type}:${value.name}(${children.map((child) => child.key).join(',')})`,
+  };
+}
+
+// Avoid circular import surprises in older Node loaders.
+import * as termModuleCache from './term.js';