eyeprolog 1.3.71 → 1.3.73

package/README.md

@@ -151,7 +151,9 @@ top level includes pending `dif/2` goals in residual answers. See
 
 `library(atts)` exposes Scryer-style attributed-variable operations on the same
 persistent `Env` machinery used by `dif/2`: `put_atts/2`, `get_atts/2`,
-`put_attr/3`, `get_attr/3`, `del_attr/2`, and `term_attributed_variables/2`.
+`put_attr/3`, `get_attr/3`, `del_attr/2`, `term_attributed_variables/2`, and
+`call_residue_vars/2`. The latter reports variables whose residual attributes or
+constraints were created or modified by a goal, including native `dif/2` residues.
 `:- attribute ...` declarations are accepted, `verify_attributes/3` runs before
 an attributed binding is committed, and the hook's returned goals run after
 that binding. Attribute state follows variable representatives and ordinary
@@ -359,7 +361,8 @@ lambda syntax also changes the active operator table.
 Outside `--iso-strict`, an otherwise undefined unqualified call may autoload a
 predicate only when the interop profile has one canonical EyeProlog provider.
 For example, `member/2` autoloads from `library(lists)`, `call_nth/2` from
-`library(iso_ext)`, and `between/3` from EyeProlog's internal
+`library(iso_ext)`, `call_residue_vars/2` from `library(atts)`, and `between/3`
+from EyeProlog's internal
 `library(prologue)` implementation. Use `--no-autoload` to disable this
 convenience. Strict ISO mode never autoloads library predicates.
 

package/examples/dif-constraints.pl

@@ -11,8 +11,8 @@ allowed_pair(X, Y) :-
     X = left,
     Y = right.
 
-% The structural constraint remains pending after X=Y. Binding both to 1
-% then proves X-Y and 1-2 different, so the constraint is discharged.
+% X=Y already proves X-Y and 1-2 different: X-X cannot unify with 1-2,
+% so the dif/2 constraint is discharged before the final specialization Y=1.
 specialization(X, Y) :-
     dif(X-Y, 1-2),
     X = Y,

package/package.json

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

package/src/atts.js

@@ -69,7 +69,8 @@ function* getAttsBuiltin({ goal, env }) {
   if (pattern.type === VAR) {
     if (attributes.length === 0) return;
     const next = env.clone();
-    if (unify(goal.args[1], listFromItems(attributes), next)) yield next;
+    if (unify(goal.args[1], listFromItems(attributes), next,
+      { knownNonoccurringVariables: goal._firstUseVariables })) yield next;
     return;
   }
 
@@ -89,7 +90,10 @@ function* getAttsBuiltin({ goal, env }) {
   }
   if (stored == null) return;
   const next = env.clone();
-  if (unify(inner, stored, next, { skipVariableConstraints: true })) yield next;
+  if (unify(inner, stored, next, {
+    skipVariableConstraints: true,
+    knownNonoccurringVariables: goal._firstUseVariables,
+  })) yield next;
 }
 
 function attributeName(term, env) {
@@ -117,7 +121,10 @@ function* getAttrBuiltin({ goal, env }) {
   const stored = env.getPrologAttribute(variableTerm.name, owner, name, 1);
   if (stored == null) return;
   const next = env.clone();
-  if (unify(goal.args[2], stored.args[0], next, { skipVariableConstraints: true })) yield next;
+  if (unify(goal.args[2], stored.args[0], next, {
+    skipVariableConstraints: true,
+    knownNonoccurringVariables: goal._firstUseVariables,
+  })) yield next;
 }
 
 function* delAttrBuiltin({ goal, env }) {
@@ -163,7 +170,8 @@ function* getAttrListBuiltin({ goal, env }) {
   if (entries.length === 0) return;
   const encoded = entries.map(({ module, attribute }) => compound(':', [atom(module), attribute]));
   const next = env.clone();
-  if (unify(goal.args[1], listFromItems(encoded), next)) yield next;
+  if (unify(goal.args[1], listFromItems(encoded), next,
+    { knownNonoccurringVariables: goal._firstUseVariables })) yield next;
 }
 
 function* getFromAttrListBuiltin({ goal, env }) {
@@ -179,7 +187,10 @@ function* getFromAttrListBuiltin({ goal, env }) {
   const stored = env.getPrologAttribute(variableTerm.name, moduleTerm.name, signature.name, signature.arity);
   if (stored == null) return;
   const next = env.clone();
-  if (unify(pattern, stored, next, { skipVariableConstraints: true })) yield next;
+  if (unify(pattern, stored, next, {
+    skipVariableConstraints: true,
+    knownNonoccurringVariables: goal._firstUseVariables,
+  })) yield next;
 }
 
 function* putToAttrListBuiltin({ goal, env }) {

package/src/iso.js

@@ -165,6 +165,7 @@ export const isoBuiltins = {
 export const eyePrologLibraryBuiltins = {
   register(registry) {
     registry.add('eyeprolog__call_nth', 2, callNthBuiltin, { eyePrologLibrary: true });
+    registry.add('eyeprolog__call_residue_vars', 2, callResidueVarsBuiltin, { eyePrologLibrary: true });
     registry.add('eyeprolog__countall', 2, countAllBuiltin, { eyePrologLibrary: true });
     registry.add('eyeprolog__freeze', 2, freezeBuiltin, { eyePrologLibrary: true });
     registry.add('dif', 2, difBuiltin, { deterministic: true, eyePrologLibrary: true });
@@ -2497,6 +2498,79 @@ function* callNthBuiltin({ solver, goal, env }) {
   }
 }
 
+function residueSnapshot(env) {
+  const attributes = new Map();
+  for (const name of env.attributedVariableNames?.() ?? []) {
+    attributes.set(name, env.prologAttributes(name));
+  }
+  const delays = new Map();
+  for (const name of env.delayedVariableNames?.() ?? []) {
+    delays.set(name, env.delayedGoals(name));
+  }
+  const constraints = new Map();
+  for (const constraint of env.variableConstraints?.() ?? []) {
+    constraints.set(constraint, [...constraint.variables(env)]);
+  }
+  return { attributes, delays, constraints };
+}
+
+function sameAttributeEntries(before, after) {
+  if (before == null || before.length !== after.length) return false;
+  for (let i = 0; i < after.length; i++) {
+    if (before[i].module !== after[i].module || before[i].attribute !== after[i].attribute) return false;
+  }
+  return true;
+}
+
+function sameDelayEntries(before, after) {
+  if (before == null || before.length !== after.length) return false;
+  for (let i = 0; i < after.length; i++) if (before[i] !== after[i]) return false;
+  return true;
+}
+
+function residueVariablesSince(snapshot, env) {
+  const names = [];
+  const seen = new Set();
+  const add = (name) => {
+    const root = deref(variable(name), env);
+    if (root.type !== VAR || seen.has(root.name)) return;
+    seen.add(root.name);
+    names.push(root);
+  };
+
+  for (const name of env.attributedVariableNames?.() ?? []) {
+    const after = env.prologAttributes(name);
+    if (!sameAttributeEntries(snapshot.attributes.get(name), after)) add(name);
+  }
+  for (const name of env.delayedVariableNames?.() ?? []) {
+    const after = env.delayedGoals(name);
+    if (!sameDelayEntries(snapshot.delays.get(name), after)) add(name);
+  }
+  for (const constraint of env.variableConstraints?.() ?? []) {
+    const after = [...constraint.variables(env)];
+    const before = snapshot.constraints.get(constraint);
+    const unchanged = before != null && before.length === after.length && before.every((name, index) => name === after[index]);
+    if (unchanged) continue;
+    for (const name of after) add(name);
+  }
+  return names;
+}
+
+function* callResidueVarsBuiltin({ solver, goal, env }) {
+  const invoked = callable(goal.args[0], env);
+  if (invoked.module == null) invoked.module = goal.module ?? 'user';
+  const snapshot = residueSnapshot(env);
+  const child = solver.cloneForInnerGoal();
+  try {
+    for (const answerEnv of child.solve([invoked], env, 0)) {
+      const next = answerEnv.clone();
+      if (unify(goal.args[1], listFromItems(residueVariablesSince(snapshot, answerEnv)), next)) yield next;
+    }
+  } finally {
+    solver.absorbStatsFrom(child);
+  }
+}
+
 function* freezeBuiltin({ solver, goal, env }) {
   const watched = deref(goal.args[0], env);
   if (watched.type !== VAR) {

package/src/lib/atts.pl

@@ -12,9 +12,14 @@
     put_attr/3,
     get_attr/3,
     del_attr/2,
-    term_attributed_variables/2
+    term_attributed_variables/2,
+    call_residue_vars/2
 ]).
 :- op(1199, fx, attribute).
+:- meta_predicate(call_residue_vars(0, '?')).
 
 term_attributed_variables(Term, Variables) :-
     '$term_attributed_variables'(Term, Variables).
+
+call_residue_vars(Goal, Variables) :-
+    eyeprolog__call_residue_vars(Goal, Variables).

package/src/program.js

@@ -34,6 +34,28 @@ import {
 const DEFER_PROGRAM_BUILD = Symbol('deferProgramBuild');
 const FAST_PARSE_ABORT = Symbol('fastParseAbort');
 const PROGRAM_BUILD_BATCH_SIZE = 16384;
+const preparedBundledLibraryCache = new Map();
+
+function preparedBundledLibraryCacheKey(program, options) {
+  const filename = String(options.filename ?? '');
+  if (filename !== standardLibrarySources.get('clpz')?.filename) return null;
+  // A user hook deliberately defined before use_module/1 is allowed to
+  // transform bundled source. Such a program needs its own ordinary expansion.
+  if (program.groups.has(modulePredicateKey('user', 'term_expansion', 2)) ||
+      program.groups.has(modulePredicateKey('user', 'goal_expansion', 2))) return null;
+  return `${filename}\u0000${options.sourceMetadata === false ? 'compact' : 'metadata'}`;
+}
+
+function cachedClauseCopy(clause) {
+  const copy = { ...clause };
+  if (Array.isArray(clause.body)) copy.body = [...clause.body];
+  if (clause.source != null) copy.source = { ...clause.source };
+  delete copy.index;
+  delete copy.groundHead;
+  delete copy.scalarHead;
+  delete copy._localFreshPlan;
+  return copy;
+}
 
 function termContainsStringExtension(term, seen = new Set()) {
   if (term == null || typeof term !== 'object' || seen.has(term)) return false;
@@ -1074,6 +1096,8 @@ function sourcePath(options) {
 function loadSourceIntoBuilder(builder, source, options, ensured, loadedModules, fast, context) {
   const batch = [];
   const deferredGoalExpansions = [];
+  const preparedCacheKey = preparedBundledLibraryCacheKey(builder.program, options);
+  const preparedForCache = preparedCacheKey == null ? null : [];
   const flush = () => {
     if (batch.length === 0) return;
     builder.addClauses(batch);
@@ -1106,41 +1130,12 @@ function loadSourceIntoBuilder(builder, source, options, ensured, loadedModules,
     processPreparedClause(clause);
   };
 
-  const processPreparedClause = (inputClause) => {
-    let clause = inputClause;
-    const lexicalModule = context.module;
-
-    // Grammar-rule expansion belongs to ISO/IEC TS 13211-3 rather than the
-    // Part 1 strict-core language.  In strict core mode -->/2 remains the
-    // ordinary predefined operator term from Table 7 and is not rewritten.
-    const grammarClause = builder.program.strictIso ? null : expandDcgRuleClause(clause, lexicalModule);
-    if (grammarClause) clause = grammarClause;
-
-    // A source module qualifier on a clause head selects the procedure owner,
-    // while unqualified calls in the body retain the lexical module of the
-    // source text. This distinction is essential for conventional hooks such
-    // as user:term_expansion/2 defined from library modules.
-    clause = normalizeQualifiedClauseHead(clause, lexicalModule);
-
-    if (!builder.program.strictIso && !isDirectiveClause(clause)) {
-      try {
-        expandClauseGoals(builder.program, clause, lexicalModule, {
-          module: lexicalModule,
-          filename: options.filename ?? '<input>',
-        });
-      } catch (error) {
-        // Scryer-compatible goal-expansion hooks may refer to helper predicates
-        // that occur later in the same source file. Keep loading so those
-        // helpers become visible, then retry this clause at end-of-source.
-        // A still-missing helper (or any other expansion error) is reported on
-        // the final retry rather than being silently ignored.
-        if (!(error instanceof PrologError) || error.formal !== 'existence_error(procedure)') throw error;
-        clause.module ??= lexicalModule;
-        clause.textUnit ??= context.textUnit;
-        deferredGoalExpansions.push({ clause, lexicalModule });
-        return;
+  const acceptPreparedClause = (clause, lexicalModule, record = true) => {
+    const remember = () => {
+      if (record && preparedForCache != null) {
+        preparedForCache.push({ clause: cachedClauseCopy(clause), lexicalModule });
       }
-    }
+    };
 
     const moduleDeclaration = moduleDirective(clause);
     if (moduleDeclaration) {
@@ -1148,6 +1143,7 @@ function loadSourceIntoBuilder(builder, source, options, ensured, loadedModules,
       clause.module = moduleDeclaration.name;
       clause.textUnit = context.textUnit;
       clause.moduleFilename = options.filename ?? '<input>';
+      remember();
       builder.addClauses([clause]);
       context.module = moduleDeclaration.name;
       loadedModules.add(moduleDeclaration.name);
@@ -1158,6 +1154,7 @@ function loadSourceIntoBuilder(builder, source, options, ensured, loadedModules,
       flush();
       clause.module = context.module;
       clause.textUnit = context.textUnit;
+      remember();
       builder.addClauses([clause]);
       const libraryName = libraryDesignationName(use.designation);
       if (libraryName != null) {
@@ -1185,6 +1182,7 @@ function loadSourceIntoBuilder(builder, source, options, ensured, loadedModules,
         const bodyModule = clause.lexicalModule ?? lexicalModule;
         for (const goal of clause.body) annotateGoalModule(goal, bodyModule);
       }
+      remember();
       const isExpansionHook = !isDirectiveClause(clause) &&
         clause.head?.arity === 2 && ['term_expansion', 'goal_expansion'].includes(clause.head?.name);
       if (isExpansionHook) {
@@ -1199,6 +1197,7 @@ function loadSourceIntoBuilder(builder, source, options, ensured, loadedModules,
       return;
     }
     flush();
+    remember();
     if (builder.program.strictIso && include.name === 'ensure_loaded') {
       builder.lastPredicateByText.set(context.textUnit ?? '<input>', '@directive');
     }
@@ -1212,6 +1211,54 @@ function loadSourceIntoBuilder(builder, source, options, ensured, loadedModules,
     }
   };
 
+  const processPreparedClause = (inputClause) => {
+    let clause = inputClause;
+    const lexicalModule = context.module;
+
+    // Grammar-rule expansion belongs to ISO/IEC TS 13211-3 rather than the
+    // Part 1 strict-core language.  In strict core mode -->/2 remains the
+    // ordinary predefined operator term from Table 7 and is not rewritten.
+    const grammarClause = builder.program.strictIso ? null : expandDcgRuleClause(clause, lexicalModule);
+    if (grammarClause) clause = grammarClause;
+
+    // A source module qualifier on a clause head selects the procedure owner,
+    // while unqualified calls in the body retain the lexical module of the
+    // source text. This distinction is essential for conventional hooks such
+    // as user:term_expansion/2 defined from library modules.
+    clause = normalizeQualifiedClauseHead(clause, lexicalModule);
+
+    if (!builder.program.strictIso && !isDirectiveClause(clause)) {
+      try {
+        expandClauseGoals(builder.program, clause, lexicalModule, {
+          module: lexicalModule,
+          filename: options.filename ?? '<input>',
+        });
+      } catch (error) {
+        // Scryer-compatible goal-expansion hooks may refer to helper predicates
+        // that occur later in the same source file. Keep loading so those
+        // helpers become visible, then retry this clause at end-of-source.
+        // A still-missing helper (or any other expansion error) is reported on
+        // the final retry rather than being silently ignored.
+        if (!(error instanceof PrologError) || error.formal !== 'existence_error(procedure)') throw error;
+        clause.module ??= lexicalModule;
+        clause.textUnit ??= context.textUnit;
+        deferredGoalExpansions.push({ clause, lexicalModule });
+        return;
+      }
+    }
+
+    acceptPreparedClause(clause, lexicalModule);
+  };
+
+  const cachedEntry = preparedCacheKey == null ? null : preparedBundledLibraryCache.get(preparedCacheKey);
+  if (cachedEntry?.source === source) {
+    for (const item of cachedEntry.clauses) {
+      acceptPreparedClause(cachedClauseCopy(item.clause), item.lexicalModule, false);
+    }
+    flush();
+    return true;
+  }
+
   if (fast) {
     const acceptBinary = (headName, head0Type, head0Name, head1Type, head1Name,
         bodyName, body0Type, body0Name, body1Type, body1Name) => {
@@ -1235,9 +1282,12 @@ function loadSourceIntoBuilder(builder, source, options, ensured, loadedModules,
         module: lexicalModule,
         filename: options.filename ?? '<input>',
       });
-      for (const goal of clause.body) annotateGoalModule(goal, clause.lexicalModule ?? lexicalModule);
-      builder.addClauses([clause]);
+      acceptPreparedClause(clause, lexicalModule);
     }
+    flush();
+  }
+  if (preparedCacheKey != null) {
+    preparedBundledLibraryCache.set(preparedCacheKey, { source, clauses: preparedForCache });
   }
   return true;
 }

package/src/repl.js

@@ -672,18 +672,18 @@ async function solveQuery(engine, state, goal, reader, output) {
 }
 
 function pullSolution(solver, solutions, reader) {
-  const stream = solver.io.resolve('user_output');
-  const originalWrite = stream?.write;
-  let captured = '';
-  if (stream) stream.write = (text) => { captured += String(text); };
+  // Prolog output is an observable side effect of execution, so never hold it
+  // until the search reaches its next leaf. In particular an infinite search
+  // that periodically writes progress must remain observable at the terminal.
+  // Completed queries keep the same byte order because user_output writes are
+  // synchronous and occur before solutions.next() returns its answer.
   const suspended = reader.suspendForComputation();
   try {
-    return { result: solutions.next(), output: captured };
+    return { result: solutions.next(), output: '' };
   } catch (error) {
-    return { error, output: captured };
+    return { error, output: '' };
   } finally {
     reader.resumeAfterComputation(suspended);
-    if (stream) stream.write = originalWrite;
   }
 }
 

package/src/solver.js

@@ -1269,22 +1269,80 @@ function clauseLocalFreshPlan(clause) {
 
 function freshVariableSet(names, freshVariables) {
   if (names.length === 0) return null;
-  const fresh = new Set();
+  const fresh = [];
   for (const name of names) {
     const term = freshVariables.get(name);
-    if (term != null) fresh.add(term.name);
+    if (term != null) fresh.push(term.name);
   }
-  return fresh.size === 0 ? null : fresh;
+  if (fresh.length === 0) return null;
+  // Most clauses introduce only one or two first-use variables. A tiny linear
+  // membership object avoids allocating and populating an OrderedHashSet on
+  // every invocation; use the native Set once linear lookup would lose.
+  return fresh.length <= 4 ? new SmallFreshVariableSet(fresh) : new Set(fresh);
+}
+
+class SmallFreshVariableSet {
+  constructor(values) {
+    this.values = values;
+  }
+
+  has(value) {
+    for (let index = 0; index < this.values.length; index++) {
+      if (this.values[index] === value) return true;
+    }
+    return false;
+  }
+}
+
+function goalUsesFirstUseProof(term) {
+  if (term?.type !== COMPOUND) return false;
+  if ((term.name === '=' && term.arity === 2)
+    || (term.name === 'get_atts' && term.arity === 2)
+    || (term.name === 'get_attr' && term.arity === 3)
+    || (term.name === '$get_attr_list' && term.arity === 2)
+    || (term.name === '$get_from_attr_list' && term.arity === 3)) return true;
+  if ((term.name === ',' || term.name === ';' || term.name === '->') && term.arity === 2) {
+    return goalUsesFirstUseProof(term.args[0]) || goalUsesFirstUseProof(term.args[1]);
+  }
+  if (term.name === '\\+' && term.arity === 1) return goalUsesFirstUseProof(term.args[0]);
+  if (term.name === ':' && term.arity === 2) return goalUsesFirstUseProof(term.args[1]);
+  return false;
 }
 
 function attachBodyLocalFreshVariables(freshBody, plan, freshVariables) {
+  const attach = (term, knownNonoccurringVariables) => {
+    if (term?.type !== COMPOUND) return;
+    if (term.name === '=' && term.arity === 2) {
+      term._knownNonoccurringVariables = knownNonoccurringVariables;
+    } else if ((term.name === 'get_atts' && term.arity === 2)
+      || (term.name === 'get_attr' && term.arity === 3)
+      || (term.name === '$get_attr_list' && term.arity === 2)
+      || (term.name === '$get_from_attr_list' && term.arity === 3)) {
+      term._firstUseVariables = knownNonoccurringVariables;
+    }
+    // Goal expansion commonly wraps a primitive in a conjunction or
+    // if-then-else. Preserve the proof on the executable child; attaching it
+    // only to the outer control term leaves get_atts/2 unable to use it.
+    if ((term.name === ',' || term.name === ';' || term.name === '->') && term.arity === 2) {
+      attach(term.args[0], knownNonoccurringVariables);
+      attach(term.args[1], knownNonoccurringVariables);
+    } else if (term.name === '\\+' && term.arity === 1) {
+      attach(term.args[0], knownNonoccurringVariables);
+    } else if (term.name === ':' && term.arity === 2) {
+      attach(term.args[1], knownNonoccurringVariables);
+    }
+  };
   for (let index = 0; index < freshBody.length; index++) {
     const goal = freshBody[index];
+    if (!goalUsesFirstUseProof(goal)) continue;
     const knownNonoccurringVariables = freshVariableSet(plan[index] ?? [], freshVariables);
     if (knownNonoccurringVariables == null || goal?.type !== COMPOUND) continue;
-    if (goal.name === '=' && goal.arity === 2) {
-      goal._knownNonoccurringVariables = knownNonoccurringVariables;
-    }
+    // Host builtins that only unify an output with already-existing logical
+    // data can use the same first-use proof without treating the variable as a
+    // WAM-style local across the whole call. This is especially important for
+    // get_atts/2: CLP(Z) attributes are large trees that would otherwise be
+    // traversed once per freshly introduced pattern variable.
+    attach(goal, knownNonoccurringVariables);
   }
 }
 
@@ -2376,10 +2434,14 @@ function tryPushGroundScalarRuleFrame(stack, solver, group, goal, rest, env, dep
   // A fully-ground call to a single flat rule can be checked without freshening
   // the rule or allocating an Env for every body literal.  This is especially
   // valuable for data-validation joins such as rb(A,B,C,D,E) in ORB Join2.
-  if (!termIsGround(goal, env) || group.clauses.length !== 1) return false;
+  // Reject ineligible rule shapes before recursively resolving the goal. Most
+  // library predicates have several clauses, and CLP(Z) calls are commonly
+  // large non-ground structures for which that groundness walk is pure cost.
+  if (group.clauses.length !== 1) return false;
   const clause = group.clauses[0];
   if (clause?.compactBinary === true || clause.body.length < 2 || clause.head.type !== COMPOUND) return false;
   if (clause.head.name !== goal.name || clause.head.arity !== goal.arity) return false;
+  if (!termIsGround(goal, env)) return false;
 
   const bindings = new Map();
   const resolvedGoal = copyResolved(goal, env);
@@ -2438,14 +2500,17 @@ function tryPushGroundChainFrames(stack, solver, group, goal, rest, env, depth,
   // 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;
   // 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;
+  // domain. Resolving the top-level arguments first proves groundness when all
+  // of them are scalars and avoids recursively walking arbitrary CLP(Z) terms
+  // only to reject them immediately afterward.
+  const resolvedArgs = new Array(goal.arity);
+  for (let index = 0; index < goal.arity; index++) {
+    const resolved = derefForLocal(goal.args[index], env);
+    if (!isScalarTerm(resolved)) return false;
+    resolvedArgs[index] = resolved;
+  }
 
   const baseEnv = env;
   let currentGroup = group;

package/src/standard-library.js

@@ -63,7 +63,7 @@ function libraryUrl(filename) {
 
 export const eyePrologNativeLibraryIndicators = Object.freeze([
   'call_nth/2', 'freeze/2', 'dif/2', 'countall/2', 'time/1',
-  'put_atts/2', 'get_atts/2', 'put_attr/3', 'get_attr/3', 'del_attr/2', 'term_attributed_variables/2',
+  'put_atts/2', 'get_atts/2', 'put_attr/3', 'get_attr/3', 'del_attr/2', 'term_attributed_variables/2', 'call_residue_vars/2',
   '#>/2', '#</2', '#>=/2', '#=</2', '#=/2', '#\\=/2', '#\\/1',
   '#<==>/2', '#==>/2', '#<==/2', '#\\//2', '#\\/2', '#/\\/2',
   'in/2', 'ins/2', 'all_different/1', 'all_distinct/1', 'nvalue/2', 'sum/3',
@@ -133,6 +133,9 @@ export const eyePrologInteropAutoload = Object.freeze({
   // it from library(iso_ext), matching the explicit Scryer import while still
   // allowing Trealla-style unqualified source to use the same autoload entry.
   'call_nth/2': 'iso_ext',
+  // Scryer exposes call_residue_vars/2 from library(atts); autoload it for
+  // constraint-test source that uses the predicate without an explicit import.
+  'call_residue_vars/2': 'atts',
   // Trealla exposes time/1 as a meta timing predicate and library(iso_ext)
   // supplies ... //0. Autoload both so UWN's DCG hand-off benchmark runs
   // unchanged while their implementations remain outside the ISO core.

package/src/term.js

@@ -8,7 +8,17 @@ export const STRING = 'string';
 export const NUMBER = 'number';
 export const COMPOUND = 'compound';
 const EMPTY_ARGS = Object.freeze([]);
-const ENV_FLATTEN_DEPTH = 1024;
+// Deep persistent binding chains make the many negative variable lookups in
+// constraint propagation linear in the complete history. Periodically fold
+// the chain into its indexed Map before that lookup cost dominates. Ordinary
+// execution keeps the memory-friendly 512-layer threshold; attributed-variable
+// propagation uses 256 because its repeated negative lookups dominate sooner.
+const ENV_FLATTEN_DEPTH = 512;
+const ATTRIBUTED_ENV_FLATTEN_DEPTH = 256;
+// 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.
+const structuralVariableCache = new WeakMap();
 
 export class Term {
   constructor(type, name, args = []) {
@@ -227,7 +237,10 @@ export class Env {
     return undefined;
   }
   bind(name, term) {
-    if (this._state.depth >= ENV_FLATTEN_DEPTH) {
+    const flattenDepth = this._prologAttributes == null
+      ? ENV_FLATTEN_DEPTH
+      : ATTRIBUTED_ENV_FLATTEN_DEPTH;
+    if (this._state.depth >= flattenDepth) {
       const flattened = new Map();
       for (let state = this._state; state != null; state = state.parent) {
         if (state.bindingName != null && !flattened.has(state.bindingName)) {
@@ -268,6 +281,28 @@ export class Env {
     delays.set(name, [...(delays.get(name) ?? []), { goal, module }]);
     this._delays = delays;
   }
+  delayedVariableNames() {
+    if (this._delays == null || this._delays.size === 0) return [];
+    const names = [];
+    const seen = new Set();
+    for (const name of this._delays.keys()) {
+      const root = deref(variable(name), this);
+      if (root.type !== VAR || seen.has(root.name)) continue;
+      seen.add(root.name);
+      names.push(root.name);
+    }
+    return names;
+  }
+  delayedGoals(name) {
+    const root = deref(variable(name), this);
+    if (root.type !== VAR || this._delays == null) return [];
+    const result = [];
+    for (const [source, goals] of this._delays) {
+      const current = deref(variable(source), this);
+      if (current.type === VAR && current.name === root.name) result.push(...goals);
+    }
+    return result;
+  }
   takeReadyDelays() {
     if (this._delays == null || this._delays.size === 0) return [];
     const ready = [];
@@ -509,7 +544,35 @@ export function isConjunction(term) {
   return term?.type === COMPOUND && term.name === ',' && term.arity === 2;
 }
 
-function occurs(variableName, term, env) {
+function structuralVariableNames(term) {
+  if (isScalar(term)) return EMPTY_ARGS;
+  if (term?.type === VAR) return [term.name];
+  if (term?.type !== COMPOUND) return EMPTY_ARGS;
+
+  const cached = structuralVariableCache.get(term);
+  if (cached !== undefined) return cached;
+
+  const names = new Set();
+  const stack = [term];
+  const seenTerms = new Set();
+  while (stack.length) {
+    const current = stack.pop();
+    if (current?.type === VAR) {
+      names.add(current.name);
+      continue;
+    }
+    if (isCompactList(current)) return null;
+    if (current?.type !== COMPOUND || seenTerms.has(current)) continue;
+    seenTerms.add(current);
+    for (let i = 0; i < current.arity; i++) stack.push(current.args[i]);
+  }
+
+  const result = names.size === 0 ? EMPTY_ARGS : [...names];
+  structuralVariableCache.set(term, result);
+  return result;
+}
+
+function occursUncached(variableName, term, env) {
   // Walk bindings and compound arguments iteratively so the occurs check also
   // remains safe for very deep terms. The visited sets make this defensive
   // against cycles introduced through the public Env API.
@@ -537,6 +600,50 @@ function occurs(variableName, term, env) {
   return false;
 }
 
+function occurs(variableName, term, env) {
+  if (isScalar(term)) return false;
+  const initial = structuralVariableNames(term);
+  if (initial == null) return occursUncached(variableName, term, env);
+  if (initial.length === 0) return false;
+
+  // Lists, wrappers, and arithmetic expressions commonly contain one logical
+  // variable. Follow that unary binding chain without allocating a work queue
+  // and hash set for every occurs check. Fall back to the general graph walk
+  // as soon as a binding fans out.
+  if (initial.length === 1) {
+    let name = initial[0];
+    const seen = [];
+    while (true) {
+      if (name === variableName) return true;
+      for (let index = 0; index < seen.length; index++) {
+        if (seen[index] === name) return false;
+      }
+      seen.push(name);
+      const binding = env?.get(name);
+      if (binding === undefined) return false;
+      const names = structuralVariableNames(binding);
+      if (names == null || names.length > 1) return occursUncached(variableName, term, env);
+      if (names.length === 0) return false;
+      name = names[0];
+    }
+  }
+
+  const pending = initial.slice();
+  const seenVariables = new Set();
+  for (let index = 0; index < pending.length; index++) {
+    const name = pending[index];
+    if (name === variableName) return true;
+    if (seenVariables.has(name)) continue;
+    seenVariables.add(name);
+    const binding = env?.get(name);
+    if (binding === undefined) continue;
+    const names = structuralVariableNames(binding);
+    if (names == null) return occursUncached(variableName, term, env);
+    for (const child of names) pending.push(child);
+  }
+  return false;
+}
+
 export function unify(left, right, env, options = {}) {
   // Iterative unification avoids deep JavaScript recursion on long lists or
   // deeply nested compounds. The occurs check gives EyeProlog finite-tree
@@ -664,9 +771,16 @@ export function freshTerm(term, suffix, variables = new Map()) {
     }
     return fresh;
   }
-  const fresh = term.type === COMPOUND && term.arity === 0
-    ? atom(term.name)
-    : new Term(term.type, term.name, term.args.map((arg) => freshTerm(arg, suffix, variables)));
+  let fresh;
+  if (term.type === COMPOUND && term.arity === 0) {
+    fresh = atom(term.name);
+  } else {
+    const args = new Array(term.args.length);
+    for (let index = 0; index < args.length; index++) {
+      args[index] = freshTerm(term.args[index], suffix, variables);
+    }
+    fresh = new Term(term.type, term.name, args);
+  }
   if (term.module != null) fresh.module = term.module;
   return fresh;
 }

package/test/run-regression.mjs

@@ -132,7 +132,7 @@ function regressionCases() {
     {
       name: 'library(atts) provides Scryer-style attributed-variable hooks',
       run: () => {
-        const source = `:- module(attr_probe, [check_get/0, check_alias/0, check_ok/0, check_bad/0, check_conflict/0, check_backtrack/0, check_term_vars/0]).
+        const source = `:- module(attr_probe, [check_get/0, check_alias/0, check_ok/0, check_bad/0, check_conflict/0, check_backtrack/0, check_term_vars/0, check_residue_new/0, check_residue_unchanged/0, check_residue_modified/0, check_residue_dif/0]).
 :- use_module(library(atts)).
 :- attribute mark/1.
 attach(X, V) :- put_atts(X, mark(V)).
@@ -151,6 +151,10 @@ check_bad :- attach(X, 3), X = 4.
 check_conflict :- attach(X, a), attach(Y, b), X = Y.
 check_backtrack :- (attach(X, a), fail ; true), \\+ get_atts(X, mark(_)).
 check_term_vars :- attach(X, a), term_attributed_variables(pair(X,Y), [X]), var(Y), X = a.
+check_residue_new :- call_residue_vars(attach(X, a), Vs), Vs = [X].
+check_residue_unchanged :- attach(X, a), call_residue_vars(true, Vs), Vs = [], X = a.
+check_residue_modified :- attach(X, a), call_residue_vars(put_atts(X, mark(b)), Vs), Vs = [X], X = b.
+check_residue_dif :- call_residue_vars(dif(X,Y), Vs), Vs = [X,Y].
 `;
         assertIncludes(run(source, { goal: 'attr_probe:check_get' }).stdout, 'attr_probe:check_get.', 'get_atts/2');
         assertIncludes(run(source, { goal: 'attr_probe:check_alias' }).stdout, 'attr_probe:check_alias.', 'attribute transfer on aliasing');
@@ -159,6 +163,20 @@ check_term_vars :- attach(X, a), term_attributed_variables(pair(X,Y), [X]), var(
         assertEqual(run(source, { goal: 'attr_probe:check_conflict' }).stdout, '', 'same-module attributes are verified before aliasing');
         assertIncludes(run(source, { goal: 'attr_probe:check_backtrack' }).stdout, 'attr_probe:check_backtrack.', 'attributes backtrack with Env branches');
         assertIncludes(run(source, { goal: 'attr_probe:check_term_vars' }).stdout, 'attr_probe:check_term_vars.', 'term_attributed_variables/2');
+        assertIncludes(run(source, { goal: 'attr_probe:check_residue_new' }).stdout, 'attr_probe:check_residue_new.', 'call_residue_vars/2 reports newly attributed variables');
+        assertIncludes(run(source, { goal: 'attr_probe:check_residue_unchanged' }).stdout, 'attr_probe:check_residue_unchanged.', 'call_residue_vars/2 ignores unchanged pre-existing attributes');
+        assertIncludes(run(source, { goal: 'attr_probe:check_residue_modified' }).stdout, 'attr_probe:check_residue_modified.', 'call_residue_vars/2 reports modified attributes');
+        assertIncludes(run(source, { goal: 'attr_probe:check_residue_dif' }).stdout, 'attr_probe:check_residue_dif.', 'call_residue_vars/2 includes native dif/2 residual variables');
+        const freezeResidue = `:- use_module(library(atts)).
+:- use_module(library(prologue), [freeze/2]).
+check :- call_residue_vars(freeze(X,true), Vs), Vs = [X].
+`;
+        assertIncludes(run(freezeResidue, { goal: 'check' }).stdout, 'check.', 'call_residue_vars/2 includes delayed freeze/2 variables');
+        const clpzResidue = `:- use_module(library(atts)).
+:- use_module(library(clpz)).
+check :- call_residue_vars(X in 1..3, Vs), Vs = [X].
+`;
+        assertIncludes(run(clpzResidue, { goal: 'check' }).stdout, 'check.', 'call_residue_vars/2 includes CLP(Z) attributed variables');
 
         const residualFile = path.join(tmp, `atts-residual-${++tmpCounter}.pl`);
         fs.writeFileSync(residualFile, `:- use_module(library(atts)).
@@ -2090,6 +2108,53 @@ c4 ?- call((!;1)).
         assertEqual(advanced.stderr, '', 'advanced stderr');
       },
     },
+    {
+      name: 'REPL exposes output side effects while search is still running (issue #72)',
+      run: () => {
+        const helper = `
+          import { spawn } from 'node:child_process';
+
+          const child = spawn(${JSON.stringify(process.execPath)}, [${JSON.stringify(bin)}], {
+            cwd: ${JSON.stringify(packageRoot)},
+            stdio: ['pipe', 'pipe', 'pipe'],
+          });
+          child.stdout.setEncoding('utf8');
+          child.stderr.setEncoding('utf8');
+          let stdout = '';
+          let stderr = '';
+          child.stdout.on('data', (text) => { stdout += text; });
+          child.stderr.on('data', (text) => { stderr += text; });
+
+          async function waitFor(predicate, label) {
+            const deadline = Date.now() + 5000;
+            while (!predicate()) {
+              if (Date.now() >= deadline) {
+                child.kill('SIGKILL');
+                throw new Error(label + ' timeout; stdout=' + JSON.stringify(stdout) + '; stderr=' + JSON.stringify(stderr));
+              }
+              await new Promise((resolve) => setTimeout(resolve, 10));
+            }
+          }
+
+          child.stdin.write('use_module(library(iso_ext)).\\n');
+          await waitFor(() => stdout.includes('   true.\\n?- '), 'module import');
+          child.stdin.write('call_nth(repeat,Nth), (Nth mod 2=:=0->writeq(r(Nth)),nl;true),Nth<0.\\n');
+          await waitFor(() => stdout.includes('r(2)\\nr(4)\\n'), 'progress output');
+          if (stdout.includes('false.')) throw new Error('infinite search unexpectedly reached a leaf');
+          child.kill('SIGKILL');
+          await new Promise((resolve) => child.once('exit', resolve));
+          process.stdout.write('progress-visible');
+        `;
+        const result = spawnSync(process.execPath, [
+          '--input-type=module',
+          '--eval',
+          helper,
+        ], { cwd: packageRoot, encoding: 'utf8', timeout: 10000 });
+        if (result.error) throw result.error;
+        assertEqual(result.status, 0, `progress helper status; stderr=${result.stderr}`);
+        assertEqual(result.stdout, 'progress-visible', 'newline-terminated progress is visible before a leaf answer');
+      },
+    },
     {
       name: 'REPL bindings use argument syntax for operator atoms',
       run: () => {
@@ -4939,7 +5004,7 @@ answer(ok) :-
         assertEqual(Boolean(registry.get('is', 2)), true, 'ISO is/2 exists');
         assertEqual(Boolean(registry.get('append', 3)), false, 'append/3 is not ISO core');
         assertEqual(library.eyePrologLibrary, true, 'complete registry marker');
-        assertEqual(library.defs.size, 154, 'EyeProlog registry contains ISO definitions, cleanup controls, observability extensions, WFS tnot/1, and generic library adapters');
+        assertEqual(library.defs.size, 155, 'EyeProlog registry contains ISO definitions, cleanup controls, observability extensions, WFS tnot/1, and generic library adapters');
         assertEqual(Boolean(registry.get('phrase', 2)), true, 'Part 3 phrase/2 exists');
         assertEqual(Boolean(registry.get('phrase', 3)), true, 'Part 3 phrase/3 exists');
         assertEqual(registry.get('statistics', 0), null, 'statistics/0 is absent from the ISO registry');
@@ -4956,21 +5021,23 @@ answer(ok) :-
         assertEqual(Boolean(library.get('call_cleanup', 2)), true, 'call_cleanup/2 is an EyeProlog cleanup control');
         assertEqual(registry.get('setup_call_cleanup', 3), null, 'setup_call_cleanup/3 is absent from the ISO registry');
         assertEqual(Boolean(library.get('setup_call_cleanup', 3)), true, 'setup_call_cleanup/3 is an EyeProlog cleanup control');
-        assertEqual(registeredNativeEyePrologLibraryNames().length, 48, 'public native EyeProlog builtin count');
+        assertEqual(registeredNativeEyePrologLibraryNames().length, 49, 'public native EyeProlog builtin count');
         assertEqual(eyePrologPortableLibraryIndicators.length, 87, 'portable Prolog library count');
-        assertEqual(eyePrologInteropLibraryIndicators.length, 29, 'cross-implementation interop profile count');
+        assertEqual(eyePrologInteropLibraryIndicators.length, 30, 'cross-implementation interop profile count');
         assertEqual(eyePrologInteropLibraryModules.join(','), 'lists,iso_ext,lambda,atts', 'common explicit library module profile');
         assertEqual(eyePrologInteropAutoload['member/2'], 'lists', 'member/2 canonical autoload');
         assertEqual(eyePrologInteropAutoload['between/3'], 'prologue', 'between/3 canonical internal autoload');
         assertEqual(eyePrologInteropAutoload['call_nth/2'], 'iso_ext', 'call_nth/2 canonical interop autoload');
+        assertEqual(eyePrologInteropAutoload['call_residue_vars/2'], 'atts', 'call_residue_vars/2 canonical interop autoload');
         assertEqual(eyePrologInteropAutoload['time/1'], 'iso_ext', 'time/1 canonical interop autoload');
         assertEqual(eyePrologInteropAutoload['.../2'], 'iso_ext', '.../2 canonical interop autoload');
         assertEqual(eyePrologInteropAutoload['set_nth0/4'] ?? null, null, 'EyeProlog-only set_nth0/4 is not autoloadable');
-        assertEqual(eyePrologNativeLibraryIndicators.length, 48, 'native host library count');
+        assertEqual(eyePrologNativeLibraryIndicators.length, 49, 'native host library count');
         assertEqual(eyePrologNativeLibraryIndicators.slice(0, 3).join(','), 'call_nth/2,freeze/2,dif/2', 'control and constraint predicates requiring host support');
-        assertEqual(eyePrologLibraryIndicators.length, 135, 'complete EyeProlog library surface');
+        assertEqual(eyePrologLibraryIndicators.length, 136, 'complete EyeProlog library surface');
         assertEqual(registry.get('eyeprolog__call_nth', 2), null, 'private call_nth adapter is absent from ISO registry');
         assertEqual(Boolean(library.get('eyeprolog__call_nth', 2)), true, 'private call_nth adapter is registered for EyeProlog');
+        assertEqual(Boolean(library.get('eyeprolog__call_residue_vars', 2)), true, 'private call_residue_vars adapter is registered for EyeProlog');
         assertEqual(library.get('eyeprolog__call_nth', 2)?.eyePrologLibrary, true, 'private adapter is marked as library support');
         assertEqual(registry.get('eyeprolog__freeze', 2), null, 'private freeze adapter is absent from ISO registry');
         assertEqual(Boolean(library.get('eyeprolog__freeze', 2)), true, 'private freeze adapter is registered for EyeProlog');

package/the-art-of-eyeprolog.md

@@ -6253,7 +6253,7 @@ between solution branches.
 | Module | Exported predicate indicators |
 | --- | --- |
 | `library(aggregate)` | `sumall/3`, `aggregate_min/5`, `aggregate_max/5` |
-| `library(atts)` | `put_atts/2`, `get_atts/2`, `put_attr/3`, `get_attr/3`, `del_attr/2`, `term_attributed_variables/2` |
+| `library(atts)` | `put_atts/2`, `get_atts/2`, `put_attr/3`, `get_attr/3`, `del_attr/2`, `term_attributed_variables/2`, `call_residue_vars/2` |
 | `library(clpz)` | `#>/2`, `#</2`, `#>=/2`, `#=</2`, `#=/2`, `#\=/2`, `#\/1`, `#<==>/2`, `#==>/2`, `#<==/2`, `#\//2`, `#\/2`, `#/\/2`, `in/2`, `ins/2`, `all_different/1`, `all_distinct/1`, `nvalue/2`, `sum/3`, `scalar_product/4`, `tuples_in/2`, `labeling/2`, `label/1`, `indomain/1`, `lex_chain/1`, `serialized/2`, `global_cardinality/2`, `global_cardinality/3`, `circuit/1`, `chain/2`, `element/3`, `zcompare/3`, `fd_var/1`, `fd_inf/2`, `fd_sup/2`, `fd_size/2`, `fd_dom/2` |
 | `library(comparison)` | `lt/2`, `gt/2`, `le/2`, `ge/2` |
 | `library(dates)` | `difference/3` |