eyeprolog 1.6.27 → 1.6.29

package/index.d.ts

@@ -214,6 +214,7 @@ export type BuiltinHandler =
 export class BuiltinRegistry {
   constructor();
   defs: Map<string, BuiltinDefinition>;
+  byName: Map<string, Map<number, BuiltinDefinition>>;
   eyePrologLibrary?: boolean;
   add(name: string, arity: number, handler: BuiltinHandler, options?: Partial<BuiltinDefinition>): this;
   get(name: string, arity: number): BuiltinDefinition | null;

package/package.json

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

package/src/ARCHITECTURE.md

@@ -21,7 +21,10 @@ higher-level frontends.
    `datalog-common.js` owns what the two Datalog evaluators share: scalar row
    keying and the per-argument candidate-bucket narrowing both index their
    relations with. Their fixpoint algorithms and relation storage stay in their
-   own modules.
+   own modules. Positive Datalog compiles clause variables to numeric slots
+   and joins through array bindings; WFS retains its persistent Map bindings.
+   Candidate selection has a direct entry point for each binding representation
+   so their inner loops do not dispatch through a binding-store abstraction.
    `cleanup.js` owns lifecycle-aware disposal of protected builtin
    iterators and registers the normal-profile cleanup controls without making
    `solver.js` depend back on the language registry.
@@ -36,6 +39,10 @@ Verification walks the supplied certificate and checks source-clause steps again
 the parsed `Program`; it does not call the solver to rediscover the proof.
 Built-in and abstract library nodes are explicit trust boundaries, while expanded
 proofs expose bundled Prolog-library clauses as ordinary source steps.
+Proof nodes share the runtime terms they resolve. Runtime terms are structurally
+immutable, so a ground subtree already is the snapshot a proof needs, and
+`resolveForProof` copies only the ancestors of an argument that variable
+resolution actually changed. Nothing anywhere may rewrite a term in place.
 
 `iso.js` and `program.js` remain facade modules for their existing exports, so
 this refactor does not change the public JavaScript API.
@@ -113,6 +120,16 @@ construct native propagation/search plans while their Prolog modules retain
 validation, residual constraints, and portable fallbacks. A cleaner file layout
 is not worth a runtime regression, so such splits must retain benchmark parity.
 
+Hot paths follow one allocation discipline: the state a walk or a comparison
+needs only for its hard case -- a cycle guard, a traversal stack, a variable
+pairing -- is allocated when that case actually appears rather than on entry.
+`deref`, `variantTerms`, and `goalHeadTermsCannotMatch` therefore decide the
+shallow, acyclic, scalar-argument case, which is the overwhelming majority of
+their calls, without allocating anything. A key a table or an index derives
+from a term is built once into one fragment array for the whole term: a key
+composed from a key per subterm makes recording one answer quadratic in that
+answer's own size.
+
 Performance claims use `npm test`'s own elapsed time across the full corpus,
 not predicate, inference, or host-call counts as a substitute for elapsed
 time, and not a separate wall-clock benchmark harness.

package/src/datalog-common.js

@@ -91,3 +91,17 @@ export function selectCandidateIndexes(indexes, args, bindings) {
   }
   return selected;
 }
+
+// Positive Datalog compiles clause variables to numeric slots. Keep its hot
+// path direct rather than introducing a binding-store dispatch in each lookup.
+export function selectCandidateIndexesForSlots(indexes, args, bindings) {
+  let selected = null;
+  for (let i = 0; i < args.length; i++) {
+    const value = args[i].type === VAR ? bindings[args[i].slot] : args[i];
+    if (value == null) continue;
+    const bucket = indexes[i].get(scalarKey(value)) ?? EMPTY_ARRAY;
+    if (selected == null || bucket.length < selected.length) selected = bucket;
+    if (selected.length === 0) break;
+  }
+  return selected;
+}

package/src/datalog.js

@@ -14,7 +14,7 @@ import {
   predicateKey,
   sameScalar,
   scalarKey,
-  selectCandidateIndexes,
+  selectCandidateIndexesForSlots,
 } from './datalog-common.js';
 
 class DatalogRelation {
@@ -61,7 +61,7 @@ class DatalogRelation {
     const tuple = new Array(args.length);
     const parts = new Array(args.length);
     for (let i = 0; i < args.length; i++) {
-      const value = args[i].type === VAR ? bindings.get(args[i].name) : args[i];
+      const value = args[i].type === VAR ? bindings[args[i].slot] : args[i];
       if (value == null || value.type === VAR) return null;
       tuple[i] = value;
       parts[i] = scalarKey(value);
@@ -87,7 +87,7 @@ class DatalogRelation {
   }
 
   candidateIndexes(args, bindings) {
-    return selectCandidateIndexes(this.indexes, args, bindings);
+    return selectCandidateIndexesForSlots(this.indexes, args, bindings);
   }
 }
 
@@ -106,11 +106,21 @@ function compileProgram(program, rootGroup) {
   for (const group of groups) {
     const headKey = predicateKey(group.module, group.name, group.arity);
     for (const clause of group.clauses) {
-      const headArgs = clause.head.args ?? EMPTY_ARRAY;
       if (clause.body.length === 0) continue;
       const body = clause.body.map((goal) => directLiteral(goal, group.module));
       if (body.some((literal) => literal == null)) continue;
-      const rule = { headKey, headArgs, body };
+      // Variable names matter only within this source clause. Compile them to
+      // array slots once so each join can bind and undo without Map lookups.
+      const variables = new Map();
+      const compileArgument = (arg) => {
+        if (arg.type !== VAR) return arg;
+        let slot = variables.get(arg.name);
+        if (slot == null) variables.set(arg.name, slot = variables.size);
+        return { type: VAR, slot };
+      };
+      const headArgs = (clause.head.args ?? EMPTY_ARRAY).map(compileArgument);
+      for (const literal of body) literal.args = literal.args.map(compileArgument);
+      const rule = { headKey, headArgs, body, variableCount: variables.size };
       rules.push(rule);
       for (let index = 0; index < body.length; index++) {
         const key = body[index].key;
@@ -130,20 +140,20 @@ function matchTupleMutable(args, tuple, bindings) {
   for (let i = 0; i < args.length; i++) {
     const pattern = args[i];
     if (pattern.type === VAR) {
-      const current = bindings.get(pattern.name);
+      const current = bindings[pattern.slot];
       if (current != null) {
         if (!sameScalar(current, tuple[i])) {
-          for (let j = added.length - 1; j >= 0; j--) bindings.delete(added[j]);
+          undoBindings(bindings, added);
           return null;
         }
       } else {
-        bindings.set(pattern.name, tuple[i]);
-        added.push(pattern.name);
+        bindings[pattern.slot] = tuple[i];
+        added.push(pattern.slot);
       }
       continue;
     }
     if (!sameScalar(pattern, tuple[i])) {
-      for (let j = added.length - 1; j >= 0; j--) bindings.delete(added[j]);
+      undoBindings(bindings, added);
       return null;
     }
   }
@@ -151,7 +161,7 @@ function matchTupleMutable(args, tuple, bindings) {
 }
 
 function undoBindings(bindings, added) {
-  for (let i = added.length - 1; i >= 0; i--) bindings.delete(added[i]);
+  for (let i = added.length - 1; i >= 0; i--) bindings[added[i]] = undefined;
 }
 
 
@@ -234,7 +244,7 @@ export function evaluatePositiveDatalog(program, rootGroup) {
     const triggerEntries = compiled.triggers.get(event.key) ?? EMPTY_ARRAY;
     for (const { rule, literalIndex } of triggerEntries) {
       const fixed = rule.body[literalIndex];
-      const bindings = new Map();
+      const bindings = new Array(rule.variableCount);
       if (!matchTupleMutable(fixed.args, event.tuple, bindings)) continue;
       const remaining = [];
       for (let i = 0; i < rule.body.length; i++) if (i !== literalIndex) remaining.push(i);

package/src/explain.js

@@ -131,12 +131,15 @@ function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active, de
       const id = nextFreshId();
       const freshVariables = new Map();
       const freshHead = freshTerm(clause.head, id, freshVariables);
-      const freshBody = clause.body.map((term) => freshTerm(term, id, freshVariables));
       const next = env.clone();
       if (!unify(goal, freshHead, next)) continue;
 
+      // Rename the body only once the head has matched. The shared variable
+      // map carries the head's renamings, so a body renamed now is the same
+      // body renaming as before -- a clause rejected on its head simply no
+      // longer pays for one.
+      const freshBody = clause.body.map((term) => freshTerm(term, id, freshVariables));
       const substitutions = collectClauseSubstitutions(clause, freshHead, freshBody);
-      const bindings = resolvedSubstitutions(substitutions, next);
 
       if (freshBody.length === 0) {
         yield {
@@ -146,7 +149,10 @@ function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active, de
             method: sourceMethod(clause, 'fact'),
             sourceHead: clause.head,
             sourceBody: [],
-            bindings,
+            // A fact binds everything it is going to bind at head unification.
+            // A rule's substitutions are only final once its body is proved,
+            // so that branch resolves them against the proving environment.
+            bindings: resolvedSubstitutions(substitutions, next),
             children: [],
           },
         };
@@ -254,7 +260,17 @@ function builtinChildren(program, goal, env, depth, maxDepth, registry, active,
 }
 
 function activeVariant(goal, env, active) {
-  return active.some((entry) => variantTerms(goal, env, entry.goal, entry.env));
+  // Only a goal for the same predicate can be a variant of this one, so reject
+  // the rest on their functor instead of on a structural comparison. Scan from
+  // the innermost entry outwards: a replay that is about to cycle repeats its
+  // nearest ancestor, not the goal the whole replay started from.
+  for (let index = active.length - 1; index >= 0; index--) {
+    const entry = active[index];
+    const candidate = entry.goal;
+    if (candidate.type !== goal.type || candidate.name !== goal.name || candidate.arity !== goal.arity) continue;
+    if (variantTerms(goal, env, candidate, entry.env)) return true;
+  }
+  return false;
 }
 
 function sourceMethod(clause, kind) {

package/src/iso.js

@@ -3302,10 +3302,15 @@ import { isBuiltin, arithmeticComparison } from './iso-arithmetic.js';
 export class BuiltinRegistry {
   constructor() {
     this.defs = new Map();
+    // `defs` stays keyed by the printable predicate indicator because callers
+    // enumerate the catalog from it. Lookups, though, happen at least once per
+    // goal on the solver's hot path, so they go through a name/arity index
+    // rather than formatting -- and allocating -- an indicator string each time.
+    this.byName = new Map();
   }
 
   add(name, arity, handler, options = {}) {
-    this.defs.set(`${name}/${arity}`, {
+    const def = {
       name,
       arity,
       handler,
@@ -3317,16 +3322,25 @@ export class BuiltinRegistry {
       fallbackWhenNotReady: options.fallbackWhenNotReady ?? false,
       shouldUse: options.shouldUse ?? null,
       eyePrologLibrary: options.eyePrologLibrary ?? false,
-    });
+    };
+    this.defs.set(`${name}/${arity}`, def);
+    let byArity = this.byName.get(name);
+    if (byArity == null) this.byName.set(name, byArity = new Map());
+    byArity.set(arity, def);
     return this;
   }
 
   get(name, arity) {
-    return this.defs.get(`${name}/${arity}`) ?? null;
+    return this.byName.get(name)?.get(arity) ?? null;
   }
 
   remove(name, arity) {
     this.defs.delete(`${name}/${arity}`);
+    const byArity = this.byName.get(name);
+    if (byArity != null) {
+      byArity.delete(arity);
+      if (byArity.size === 0) this.byName.delete(name);
+    }
     return this;
   }
 }

package/src/solver.js

@@ -3223,13 +3223,13 @@ function rememberGroundChainSuccess(solver, seen) {
 
 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');
+  const keyParts = [];
+  const answerArgs = new Array(goal.args.length);
+  for (let position = 0; position < goal.args.length; position++) {
+    if (position > 0) keyParts.push('\x1f');
+    answerArgs[position] = copyResolvedWithKey(goal.args[position], env, variables, keyParts);
+  }
+  const key = keyParts.join('');
   if (entry.answerKeys.has(key)) return;
   entry.answerKeys.add(key);
   const answerIndex = entry.answers.length;
@@ -3373,7 +3373,13 @@ function canonicalTermKey(term, env, variables) {
   return key.join('');
 }
 
-function copyResolvedWithKey(term, env, variables) {
+// Copies one answer argument and appends its variant key to `keyParts`.
+// Writing fragments into one shared array keeps a tabled answer linear in its
+// own size: returning a key per subterm instead made every enclosing term
+// rebuild the key of everything below it, so a predicate tabling long lists --
+// a Collatz trajectory, a transitive closure path -- paid quadratic string
+// building for each answer it recorded.
+function copyResolvedWithKey(term, env, variables, keyParts) {
   const value = derefForLocal(term, env);
   if (value.type === 'var') {
     let id = variables.get(value.name);
@@ -3381,19 +3387,24 @@ function copyResolvedWithKey(term, env, variables) {
       id = variables.size;
       variables.set(value.name, id);
     }
-    return { term: termModuleCache.variable(value.name), key: `var:${id}` };
+    keyParts.push('var:', id);
+    return termModuleCache.variable(value.name);
   }
   if (!value.args?.length) {
     // Atomic terms are immutable in the solver.  Share them across table
     // answers instead of allocating a fresh host object for every cell of a
     // large closure such as tc/2.
-    return { term: value, key: `${value.type}:${value.name}` };
+    keyParts.push(value.type, ':', value.name);
+    return value;
   }
-  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(',')})`,
-  };
+  keyParts.push(value.type, ':', value.name, '(');
+  const children = new Array(value.args.length);
+  for (let index = 0; index < value.args.length; index++) {
+    if (index > 0) keyParts.push(',');
+    children[index] = copyResolvedWithKey(value.args[index], env, variables, keyParts);
+  }
+  keyParts.push(')');
+  return termModuleCache.compound(value.name, children);
 }
 
 // Avoid circular import surprises in older Node loaders.

package/src/term.js

@@ -19,6 +19,10 @@ const ATTRIBUTED_ENV_FLATTEN_DEPTH = 256;
 // binding is just as safe to cache as a present one. Negative lookups are
 // especially common while tabling and constraint code probes fresh variables.
 const ENV_UNBOUND = Symbol('environment-unbound');
+// Dereferencing walks a binding chain. Chains are one or two hops in practice
+// and cyclic only when a term was built incorrectly, so the cycle guard starts
+// recording visited names only after a chain is long enough to be suspect.
+const DEREF_CYCLE_GUARD_HOPS = 16;
 // Runtime terms are structurally immutable: environments hold bindings beside
 // them rather than rewriting their argument arrays. Cache only the syntactic
 // variable names; binding reachability is still checked against each Env.
@@ -885,20 +889,34 @@ class SolverEnv extends Env {
 }
 
 export function deref(term, env) {
-  // Follow variable bindings until a non-variable term is reached. The seen set
-  // protects readback from accidental cycles in partially constructed terms.
+  // Follow variable bindings until a non-variable term is reached. This is the
+  // most frequently executed function in the runtime, so nothing it needs only
+  // occasionally may be paid for on every call: most terms are not variables
+  // at all, most environments declare no DCG locals, and almost every chain is
+  // one or two hops long.
+  if (term?.type !== VAR || env == null) return term;
+  // A live compiler-proven DCG local is the current unbound representative.
+  // No older Env layer can contain a binding for it. Both Env representations
+  // answer that question from this one set, so read it once per call instead
+  // of dispatching a method call per hop.
+  const locals = env._localVariables;
   let current = term;
   let seen = null;
-  while (current?.type === VAR) {
-    // A live compiler-proven DCG local is the current unbound representative.
-    // No older Env layer can contain a binding for it.
-    if (env?.isLocalVariable?.(current.name) === true) break;
-    const next = env?.get(current.name);
+  let hops = 0;
+  do {
+    if (locals != null && locals.has(current.name)) break;
+    const next = env.get(current.name);
     if (next === undefined) break;
-    if (seen?.has(current.name)) break;
-    (seen ??= new Set()).add(current.name);
+    // The seen set protects readback from accidental cycles in partially
+    // constructed terms. A cycle still terminates the walk once the guard
+    // starts recording, so ordinary chains never allocate it.
+    if (++hops > DEREF_CYCLE_GUARD_HOPS) {
+      if (seen == null) seen = new Set();
+      if (seen.has(current.name)) break;
+      seen.add(current.name);
+    }
     current = next;
-  }
+  } while (current?.type === VAR);
   return current;
 }
 
@@ -1519,40 +1537,65 @@ export function termSignature(term) {
   return term?.type === COMPOUND ? `${term.name}/${term.arity}` : null;
 }
 
-export function variantTerms(left, leftEnv, right, rightEnv, pairs = new Map(), reverse = new Map()) {
-  // Variant checks sit on the recursive-call hot path. Use an explicit work
-  // stack so long lists do not consume the JavaScript call stack.
-  const pending = [[left, right]];
-  const seen = new WeakMap();
-  while (pending.length > 0) {
-    [left, right] = pending.pop();
-    left = deref(left, leftEnv);
-    right = deref(right, rightEnv);
-    if (left.type === VAR || right.type === VAR) {
-      if (left.type !== VAR || right.type !== VAR) return false;
-      if (pairs.has(left.name) || reverse.has(right.name)) {
-        if (pairs.get(left.name) !== right.name || reverse.get(right.name) !== left.name) return false;
-        continue;
+export function variantTerms(left, leftEnv, right, rightEnv, pairs = null, reverse = null) {
+  // Variant checks sit on the recursive-call hot path, where the usual answer
+  // is "not a variant" and the usual reason is one mismatched scalar argument.
+  // Settle scalar and variable arguments as they are derefed and defer only
+  // compound ones to an explicit work stack, which long lists still need so
+  // they do not consume the JavaScript call stack. The stack, the variable
+  // pairing, and the cycle guard are therefore allocated only once something
+  // actually needs them, which a rejected comparison usually never does.
+  let leftStack = null;
+  let rightStack = null;
+  let seen = null;
+  let current = deref(left, leftEnv);
+  let other = deref(right, rightEnv);
+  for (;;) {
+    if (current.type === VAR || other.type === VAR) {
+      if (current.type !== VAR || other.type !== VAR) return false;
+      pairs ??= new Map();
+      reverse ??= new Map();
+      const forward = pairs.get(current.name);
+      const backward = reverse.get(other.name);
+      if (forward !== undefined || backward !== undefined) {
+        if (forward !== other.name || backward !== current.name) return false;
+      } else {
+        pairs.set(current.name, other.name);
+        reverse.set(other.name, current.name);
+      }
+    } else if (current.type !== other.type || current.arity !== other.arity) {
+      return false;
+    } else if (current.type === NUMBER ? !sameNumberValue(current.name, other.name) : current.name !== other.name) {
+      return false;
+    } else if (current.type === COMPOUND && seen?.get(current)?.has(other) !== true) {
+      let recorded = false;
+      for (let i = 0; i < current.arity; i++) {
+        const leftArg = deref(current.args[i], leftEnv);
+        const rightArg = deref(other.args[i], rightEnv);
+        if (leftArg.type !== COMPOUND && rightArg.type !== COMPOUND
+          && leftArg.type !== VAR && rightArg.type !== VAR) {
+          if (leftArg.type !== rightArg.type) return false;
+          if (leftArg.type === NUMBER
+            ? !sameNumberValue(leftArg.name, rightArg.name)
+            : leftArg.name !== rightArg.name) return false;
+          continue;
+        }
+        if (!recorded) {
+          recorded = true;
+          let rights = (seen ??= new WeakMap()).get(current);
+          if (rights == null) seen.set(current, rights = new WeakSet());
+          rights.add(other);
+          leftStack ??= [];
+          rightStack ??= [];
+        }
+        leftStack.push(leftArg);
+        rightStack.push(rightArg);
       }
-      pairs.set(left.name, right.name);
-      reverse.set(right.name, left.name);
-      continue;
-    }
-
-    if (left.type !== right.type || left.arity !== right.arity) return false;
-    if (left.type === NUMBER ? !sameNumberValue(left.name, right.name) : left.name !== right.name) return false;
-    if (left.type !== COMPOUND) continue;
-
-    let rights = seen.get(left);
-    if (rights?.has(right)) continue;
-    if (rights == null) {
-      rights = new WeakSet();
-      seen.set(left, rights);
     }
-    rights.add(right);
-    for (let i = left.arity - 1; i >= 0; i--) pending.push([left.args[i], right.args[i]]);
+    if (leftStack == null || leftStack.length === 0) return true;
+    current = leftStack.pop();
+    other = rightStack.pop();
   }
-  return true;
 }
 
 

package/test/regression/cases-white-box.mjs

@@ -6,10 +6,11 @@ import { spawnSync } from 'node:child_process';
 import * as publicApi from '../../src/index.js';
 import { Env, Program, atom, compound, copyResolved, flattenConjunction, listFromItems, numberTerm, parseProgramText, properListItems, stringTerm, termIsGround, termToString, unify, variable, variantTerms } from '../../src/index.js';
 import { ISO_OPERATOR_DEFINITIONS, parseGoalText, parseNumberTokenText } from '../../src/parser.js';
-import { compareTerms } from '../../src/term.js';
+import { compareTerms, deref } from '../../src/term.js';
 import { checkProofDocument, verdict } from '../../src/check-proof.js';
 import { formatTermForWrite } from '../../src/write.js';
 import { selectClauseCandidates } from '../../src/program.js';
+import { evaluatePositiveDatalog, relationForDatalogGroup } from '../../src/datalog.js';
 import { assertEqual, assertIncludes, assertNotIncludes } from '../test-style.mjs';
 import { goalsFromSource } from '../goal-metadata.mjs';
 import {
@@ -770,6 +771,44 @@ export function whiteBoxCases() {
         assertEqual(ground.stats.datalog_evaluations, 0, 'ground query keeps the ordinary indexed chain path');
       },
     },
+    {
+      name: 'Datalog joins preserve clause-local variables and repeated arguments',
+      run: () => {
+        const program = Program.parse(`
+link(a,b,red).
+link(b,c,red).
+link(c,d,red).
+link(x,x,red).
+link(a,b,blue).
+link(c,c,blue).
+link(a,c,blue).
+reach(X,Y,C) :- link(X,Y,C).
+reach(X,Y,C) :- link(X,Z,C), reach(Z,Y,C).
+back(Y,X) :- reach(X,Y,red).
+back(X,Y) :- reach(X,Y,blue).
+diagonal(X) :- reach(X,X,C).
+marked(tag,X) :- reach(X,X,red).
+wide(X,marker,Y) :- reach(X,Y,red).
+ready :- diagonal(x).
+summary :- ready, back(X,Y), marked(tag,Z), wide(X,marker,Y).
+`);
+        const model = evaluatePositiveDatalog(program, program.findGroup('summary', 0));
+        const checkRows = (name, arity, expected) => {
+          const relation = relationForDatalogGroup(model, program.findGroup(name, arity));
+          const actual = relation.rows.map((row) => row.map((value) => value.name).join(':')).sort();
+          assertEqual(actual.join('|'), expected.sort().join('|'), `${name}/${arity} rows`);
+        };
+        checkRows('back', 2, ['b:a', 'c:b', 'd:c', 'x:x', 'c:a', 'd:a', 'd:b', 'a:b', 'c:c', 'a:c']);
+        checkRows('diagonal', 1, ['c', 'x']);
+        checkRows('marked', 2, ['tag:x']);
+        checkRows('wide', 3, [
+          'a:marker:b', 'b:marker:c', 'c:marker:d', 'x:marker:x',
+          'a:marker:c', 'a:marker:d', 'b:marker:d',
+        ]);
+        checkRows('ready', 0, ['']);
+        checkRows('summary', 0, ['']);
+      },
+    },
     {
       name: 'compact finite Datalog planning preserves lazy clause terms',
       run: () => {
@@ -1026,5 +1065,66 @@ path(X, Z) :- edge(X, Y), path(Y, Z).
         assertIncludes(result.stdout, 'collatzTrajectory(1, [1]).\n', 'stdout');
       },
     },
+    {
+      // The hot paths below settle the ordinary case without allocating the
+      // traversal state the hard case needs. These cases pin the hard cases:
+      // the state has to appear exactly when the comparison stops being
+      // shallow, acyclic, and decidable on a scalar.
+      name: 'variantTerms separates renaming from sharing and still rejects on scalars',
+      run: () => {
+        const goal = parseGoalText('step(1, X, point(Y, X))');
+        const renamed = parseGoalText('step(1, A, point(B, A))');
+        const shared = parseGoalText('step(1, A, point(B, B))');
+        const otherScalar = parseGoalText('step(2, A, point(B, A))');
+        assertEqual(variantTerms(goal, new Env(), renamed, new Env()), true, 'a consistent renaming is a variant');
+        assertEqual(variantTerms(goal, new Env(), shared, new Env()), false, 'sharing a variable is not a renaming');
+        assertEqual(variantTerms(goal, new Env(), otherScalar, new Env()), false, 'a differing scalar argument rejects');
+        assertEqual(
+          variantTerms(parseGoalText('step(1.0, A)'), new Env(), parseGoalText('step(1, A)'), new Env()),
+          false,
+          'a float and an integer argument stay distinct',
+        );
+      },
+    },
+    {
+      name: 'variantTerms and deref terminate on cyclic bindings',
+      run: () => {
+        const leftEnv = new Env();
+        leftEnv.bind('X', compound('f', [variable('X')]));
+        const rightEnv = new Env();
+        rightEnv.bind('Y', compound('f', [variable('Y')]));
+        assertEqual(variantTerms(variable('X'), leftEnv, variable('Y'), rightEnv), true, 'cyclic terms of one shape are variants');
+
+        const chain = new Env();
+        for (let index = 0; index < 40; index++) chain.bind(`V${index}`, variable(`V${index + 1}`));
+        chain.bind('V40', atom('done'));
+        assertEqual(deref(variable('V0'), chain).name, 'done', 'a forty-hop chain resolves to its value');
+
+        const cyclicChain = new Env();
+        cyclicChain.bind('A', variable('B'));
+        cyclicChain.bind('B', variable('A'));
+        assertEqual(deref(variable('A'), cyclicChain).type, 'var', 'a cyclic chain stops at a variable');
+      },
+    },
+    {
+      name: 'tabled answers separate on a deep list element and still merge on a repeated derivation',
+      run: () => {
+        const program = Program.parse(`
+:- table suffixed/2.
+:- table duplicated/1.
+mark(a).
+mark(b).
+chain(0, [E], E).
+chain(N, [x|T], E) :- N > 0, M is N - 1, chain(M, T, E).
+suffixed(E, L) :- mark(E), chain(40, L, E).
+duplicated(L) :- chain(40, L, a).
+duplicated(L) :- chain(40, L, a).
+`);
+        const distinct = run(program, { goal: 'suffixed(E, L)' });
+        assertEqual(distinct.stdout.trim().split('\n').length, 2, 'answers differing only past forty cells stay distinct');
+        const merged = run(program, { goal: 'duplicated(L)' });
+        assertEqual(merged.stdout.trim().split('\n').length, 1, 'one answer derived twice is tabled once');
+      },
+    },
   ];
 }