eyeprolog 1.3.11 → 1.3.12

package/README.md

@@ -107,6 +107,17 @@ keeps both long-running filters such as `\+ phrase((..., Pattern), Sequence)`
 and repeated same-input probes bounded without turning memory safety into a
 per-call cache-eviction cost.
 
+Finite-tree unification also recognizes a conservative first-use case inspired
+by the local-variable optimization used by WAM-family systems. In a freshly
+renamed clause, a singleton head variable or a variable that first appears once
+in a direct `=/2` goal cannot already occur in the value it is about to receive,
+so that one binding can skip an otherwise redundant occurs traversal. Repeated
+variables, variables seen earlier in the clause, and ordinary public unification
+remain fully occurs-checked. This is a source-level proof, not a WAM-style
+local/global variable stack. `phrase/2` likewise supplies its fixed `[]`
+remainder directly to the grammar; `phrase/3` retains its delayed final output
+unification for steadfastness.
+
 Recursion through negation is explicit. EyeProlog provides `tnot/1` for
 well-founded negation over finite, range-restricted, function-free Datalog
 components. Ordinary `\+/1` remains negation-as-failure and is not silently

package/package.json

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

package/src/iso.js

@@ -181,7 +181,8 @@ export const eyePrologLibraryBuiltins = {
 
 function* unification({ goal, env }) {
   const next = env.clone();
-  if (unify(goal.args[0], goal.args[1], next)) yield next;
+  const localFreshVariables = goal._localFreshVariables ?? null;
+  if (unify(goal.args[0], goal.args[1], next, { localFreshVariables })) yield next;
 }
 function* unificationWithOccursCheck({ goal, env }) {
   const next = env.clone();
@@ -2033,14 +2034,17 @@ function* phraseBuiltin({ solver, goal, env }) {
     throw new PrologError('type_error(list)', deref(requestedOutput, env));
   }
 
-  // Delay the final output unification to keep phrase/3 steadfast in its
-  // third argument, as required by the Part 3 execution model.
-  const finalOutput = variable(`\u0000phrase:${++isoFresh}`);
+  // phrase/2 fixes the remainder to [] from the outset. phrase/3 keeps a
+  // private output variable and delays the final unification so its third
+  // argument remains steadfast as required by the Part 3 execution model.
+  const finalOutput = goal.arity === 2
+    ? requestedOutput
+    : variable(`\u0000phrase:${++isoFresh}`);
   const expanded = expandDcgBody(grammarBody, input, finalOutput, {
     env,
     module: goal.module ?? grammarBody.module ?? 'user',
   });
-  const finish = compound('=', [finalOutput, requestedOutput]);
+  const finish = goal.arity === 2 ? null : compound('=', [finalOutput, requestedOutput]);
   // Recursive DCGs are automatically tabled in normal mode. Keep tables in a
   // phrase-local scope keyed by the whole invocation. Repeatedly testing the
   // same grammar/input (issue #48) reuses its completed table, while switching
@@ -2064,7 +2068,7 @@ function* phraseBuiltin({ solver, goal, env }) {
     skipListTailTabling: !repeatedInvocation,
   });
   try {
-    yield* child.solve([expanded, finish], env, 0);
+    yield* child.solve(finish == null ? [expanded] : [expanded, finish], env, 0);
   } finally {
     solver.absorbStatsFrom(child);
     solver.trimInnerTableScope('phrase');

package/src/solver.js

@@ -799,9 +799,12 @@ export class Solver {
         const freshVariables = new Map();
         const freshHead = freshTerm(clause.head, id, freshVariables);
         const freshBody = clause.body.map((term) => freshTerm(term, id, freshVariables));
+        const localFreshPlan = clauseLocalFreshPlan(clause);
+        const headLocalFresh = freshVariableSet(localFreshPlan.head, freshVariables);
+        attachBodyLocalFreshVariables(freshBody, localFreshPlan.body, freshVariables);
         const next = env.clone();
         this.stats.unify_calls++;
-        if (!unify(goal, freshHead, next)) continue;
+        if (!unify(goal, freshHead, next, { localFreshVariables: headLocalFresh })) continue;
         if (freshBody.length === 0) {
           yield* this.solve(rest, next, depth + 1);
         } else if (!groupNeedsActiveFrame(group)) {
@@ -1013,9 +1016,12 @@ function pushUserGoalUncachedFrames(stack, solver, group, goal, rest, env, depth
       const freshVariables = new Map();
       const freshHead = freshTerm(clause.head, id, freshVariables);
       const freshBody = clause.body.map((term) => freshTerm(term, id, freshVariables));
+      const localFreshPlan = clauseLocalFreshPlan(clause);
+      const headLocalFresh = freshVariableSet(localFreshPlan.head, freshVariables);
+      attachBodyLocalFreshVariables(freshBody, localFreshPlan.body, freshVariables);
       const next = env.clone();
       solver.stats.unify_calls++;
-      if (!unify(goal, freshHead, next)) continue;
+      if (!unify(goal, freshHead, next, { localFreshVariables: headLocalFresh })) continue;
       if (freshBody.length === 0) {
         frames.push({
           kind: 'goals',
@@ -1038,6 +1044,53 @@ function pushUserGoalUncachedFrames(stack, solver, group, goal, rest, env, depth
   for (let i = frames.length - 1; i >= 0; i--) stack.push(frames[i]);
 }
 
+function clauseLocalFreshPlan(clause) {
+  if (clause._localFreshPlan != null) return clause._localFreshPlan;
+  const seen = new Set();
+  const planForTerm = (term) => {
+    const counts = new Map();
+    const stack = [term];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (current?.type === VAR) {
+        counts.set(current.name, (counts.get(current.name) ?? 0) + 1);
+        continue;
+      }
+      if (current?.type !== COMPOUND) continue;
+      for (let index = 0; index < current.arity; index++) stack.push(current.args[index]);
+    }
+    const local = [];
+    for (const [name, count] of counts) {
+      if (!seen.has(name) && count === 1) local.push(name);
+      seen.add(name);
+    }
+    return local;
+  };
+  const head = planForTerm(clause.head);
+  const body = clause.body.map(planForTerm);
+  return clause._localFreshPlan = { head, body };
+}
+
+function freshVariableSet(names, freshVariables) {
+  if (names.length === 0) return null;
+  const fresh = new Set();
+  for (const name of names) {
+    const term = freshVariables.get(name);
+    if (term != null) fresh.add(term.name);
+  }
+  return fresh.size === 0 ? null : fresh;
+}
+
+function attachBodyLocalFreshVariables(freshBody, plan, freshVariables) {
+  for (let index = 0; index < freshBody.length; index++) {
+    const localFreshVariables = freshVariableSet(plan[index] ?? [], freshVariables);
+    if (localFreshVariables != null && freshBody[index]?.type === COMPOUND &&
+        freshBody[index].name === '=' && freshBody[index].arity === 2) {
+      freshBody[index]._localFreshVariables = localFreshVariables;
+    }
+  }
+}
+
 function groupNeedsActiveFrame(group) {
   // A direct recursive call that consumes the tail of a matched list cannot
   // revisit an earlier finite-tree call. It needs neither a cycle guard nor an
@@ -1900,10 +1953,14 @@ function compactIndexBucket(index, type, name) {
 
 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;
+  // This fast path only accepts scalar arguments. Dereference those arguments
+  // directly instead of deep-copying the whole goal before discovering that a
+  // list/compound argument is ineligible. Besides avoiding wasted work, this
+  // keeps deep DCG state lists away from recursive copyResolved().
+  const first = derefForLocal(goal.args[0], env);
+  const second = derefForLocal(goal.args[1], env);
+  let secondType = second?.type;
+  let secondName = second?.name;
   if (!isScalarTerm(first) || !['atom', 'string', 'number'].includes(secondType)) return false;
 
   const index = group.argIndexes[1];
@@ -2014,10 +2071,17 @@ function tryPushGroundChainFrames(stack, solver, group, goal, rest, env, depth,
   // 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;
+  // The chain matcher below only propagates variables bound to flat scalar
+  // head arguments (or literal scalars). Keep this optimization on that flat
+  // domain instead of recursively copying an arbitrary ground compound just
+  // to discover later that a rule shape is unsupported. Deep list arguments
+  // such as DCG state therefore fall straight through to normal resolution.
+  const resolvedArgs = goal.args.map((arg) => derefForLocal(arg, env));
+  if (!resolvedArgs.every(isScalarTerm)) return false;
 
   const baseEnv = env;
   let currentGroup = group;
-  let currentGoal = copyResolved(goal, env);
+  let currentGoal = compound(goal.name, resolvedArgs);
   let currentDepth = depth;
   const currentEnv = new Env();
   const seen = new Set();
@@ -2328,6 +2392,10 @@ 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;
+    // A first-use proof is derived from source goal order. Do not move a later
+    // deterministic builtin across that equality: doing so could touch one of
+    // its proven-fresh variables before the checked binding executes.
+    if (goal?._localFreshVariables != null) 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;

package/src/term.js

@@ -271,6 +271,10 @@ export function unify(left, right, env, options = {}) {
   // unification: a variable cannot be bound to a term containing itself.
   // Bindings are written into the supplied Env.
   const occursCheckHandler = options.occursCheck === 'fail' ? null : env?._occursCheckHandler;
+  // A solver-proven first-use singleton variable cannot already occur in the
+  // term it is about to receive.  This internal proof lets that one binding
+  // skip the occurs traversal without weakening ordinary unification.
+  const localFreshVariables = options.localFreshVariables ?? null;
   const stack = [[left, right]];
   while (stack.length) {
     let [a, b] = stack.pop();
@@ -286,7 +290,7 @@ export function unify(left, right, env, options = {}) {
       continue;
     }
     if (a.type === VAR) {
-      if (occurs(a.name, b, env)) {
+      if (!localFreshVariables?.has(a.name) && occurs(a.name, b, env)) {
         occursCheckHandler?.(a, b, env);
         return false;
       }
@@ -295,7 +299,7 @@ export function unify(left, right, env, options = {}) {
       continue;
     }
     if (b.type === VAR) {
-      if (occurs(b.name, a, env)) {
+      if (!localFreshVariables?.has(b.name) && occurs(b.name, a, env)) {
         occursCheckHandler?.(b, a, env);
         return false;
       }

package/test/run-regression.mjs

@@ -1317,6 +1317,68 @@ c4 ?- call((!;1)).
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'first-use local equality shortcut preserves finite-tree occurs checking',
+      run: () => {
+        const program = Program.parse(`
+          first_use_cycle :- X = f(Y), Y = g(X).
+          repeated_cycle :- X = f(X).
+          first_use_ok(T) :- X = f(Y), Y = a, T = X.
+        `);
+        const solver = new Solver(program);
+        const solveCount = (text) => {
+          const goal = parseGoalText(text, {
+            doubleQuotes: 'chars',
+            operatorDefinitions: [...program.operators.values()],
+          });
+          let count = 0;
+          for (const _ of solver.solve([goal], new Env(), 0)) count++;
+          return count;
+        };
+        assertEqual(solveCount('first_use_cycle'), 0, 'cycle across later first-use binding');
+        assertEqual(solveCount('repeated_cycle'), 0, 'same-goal repeated variable still checks occurs');
+        assertEqual(solveCount('first_use_ok(f(a))'), 1, 'acyclic first-use bindings still succeed');
+      },
+    },
+    {
+      name: 'phrase/2 fixes the final remainder before running the grammar',
+      run: () => {
+        const program = Program.parse('probe(_, Out) :- var(Out).\n');
+        const solver = new Solver(program);
+        const goal = parseGoalText('phrase(probe, [])', {
+          doubleQuotes: 'chars',
+          operatorDefinitions: [...program.operators.values()],
+        });
+        let count = 0;
+        for (const _ of solver.solve([goal], new Env(), 0)) count++;
+        assertEqual(count, 0, 'phrase/2 exposes [] rather than a temporary output variable');
+      },
+    },
+    {
+      name: 'deep tail-consuming DCG avoids quadratic occurs scans and recursive ground-goal copying',
+      run: () => {
+        const engineUrl = new URL('../src/index.js', import.meta.url).href;
+        const script = `
+          import { Program, Solver, Env, atom, compound, listFromItems } from ${JSON.stringify(engineUrl)};
+          const program = Program.parse(${JSON.stringify('s --> [].\ns --> [x], s.\n')});
+          const input = listFromItems(Array.from({ length: 2500 }, () => atom('x')));
+          const solver = new Solver(program, { solutionLimit: 1, maxMemoryBytes: Infinity });
+          const goal = compound('phrase', [atom('s'), input]);
+          let count = 0;
+          for (const _ of solver.solve([goal], new Env(), 0)) { count++; break; }
+          if (count !== 1) throw new Error('deep DCG did not succeed');
+          process.stdout.write('ok');
+        `;
+        const result = spawnSync(process.execPath, [
+          '--input-type=module',
+          '--eval',
+          script,
+        ], { cwd: packageRoot, encoding: 'utf8', timeout: 10000 });
+        if (result.error) throw result.error;
+        assertEqual(result.status, 0, `deep DCG child status; stderr=${result.stderr}`);
+        assertEqual(result.stdout, 'ok', 'deep DCG result');
+      },
+    },
     {
       name: 'REPL enumerates and stops answers like the Scryer top level',
       run: () => {

package/the-art-of-eyeprolog.md

@@ -1905,10 +1905,30 @@ bundled path binds each fresh generated spine directly instead of re-running an
 occurs-check over the whole growing list. It also reserves recovery headroom
 proportional to the retained spine, so a finite heap limit is raised inside the
 `length/2` search as a catchable `resource_error(memory)` rather than allowing
-an outer solver frame to encounter the limit first. The ordinary clauses remain
-the authoritative module definition and are used unchanged by the ISO-only
-registry and whenever delays or finite-domain constraints require their normal
-wake-up points.
+an outer solver frame to encounter the limit first.
+
+The same principle now has a conservative general form for freshly renamed
+clauses. A singleton variable in the clause head, or a variable that has not
+appeared in the head or any earlier body goal and occurs exactly once in a
+direct `=/2` goal, cannot already be a subterm of the value it is about to
+receive. EyeProlog marks only that binding as locally fresh and skips its occurs
+traversal. A repeated variable such as the `X` in `X = f(X)`, a variable already
+seen earlier in the clause, and `unify_with_occurs_check/2` all keep the normal
+finite-tree check. The solver also treats such a first-use equality as a
+source-order barrier for its deterministic-goal scheduling, so the freshness
+proof cannot be invalidated by moving a later goal ahead of it. This recovers
+much of the classic WAM-family "local variable" optimization for DCG tail
+variables without introducing a WAM local/global stack distinction into the
+JavaScript term model.
+
+For grammar execution, `phrase/2` passes its fixed final remainder `[]` directly
+into the expanded grammar. Besides matching the two-argument contract, this
+avoids repeatedly trying an empty production against a temporary output
+variable. `phrase/3` still uses a private final-output variable and delays its
+last unification, preserving the existing steadfast treatment of its explicit
+third argument. The ordinary `length/2` clauses remain the authoritative module
+definition and are used unchanged by the ISO-only registry and whenever delays
+or finite-domain constraints require their normal wake-up points.
 
 ### Implementation boundary