eyeprolog 1.3.91 → 1.3.92

package/index.d.ts

@@ -182,7 +182,12 @@ export interface BuiltinDefinition {
   eyePrologLibrary: boolean;
 }
 
-export type BuiltinHandler = (context: { solver: Solver; goal: EyePrologTerm; env: Env }) => Iterable<Env>;
+export interface BuiltinIterator extends IterableIterator<Env> {
+  hasPendingAlternatives?: () => boolean;
+}
+
+export type BuiltinHandler =
+  (context: { solver: Solver; goal: EyePrologTerm; env: Env }) => BuiltinIterator;
 
 export class BuiltinRegistry {
   constructor();

package/package.json

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

package/src/iso.js

@@ -627,16 +627,30 @@ function validPredicateIndicator(term) {
       (term.args[1].type === NUMBER && isDecimalInteger(term.args[1].name) && BigInt(term.args[1].name) >= 0n));
 }
 
-function* currentPredicateBuiltin({ solver, goal, env }) {
+function currentPredicateBuiltin(context) {
+  const state = { pending: false };
+  return withPendingState(currentPredicateSolutions(context, state), state);
+}
+
+function* currentPredicateSolutions({ solver, goal, env }, state) {
   const indicator = copyResolved(goal.args[0], env);
   if (indicator.type !== VAR && !validPredicateIndicator(indicator)) {
     throw new PrologError('type_error(predicate_indicator)', indicator);
   }
-  for (const group of solver.program.groups.values()) {
+  const groups = [...solver.program.groups.values()].filter((group) =>
+    indicator.type === VAR ||
+    (indicator.args[0].type === VAR || indicator.args[0].name === group.name) &&
+    (indicator.args[1].type === VAR || BigInt(indicator.args[1].name) === BigInt(group.arity)));
+  for (let index = 0; index < groups.length; index++) {
+    const group = groups[index];
     const next = env.clone();
     const candidate = compound('/', [atom(group.name), numberTerm(group.arity)]);
-    if (unify(goal.args[0], candidate, next)) yield next;
+    if (unify(goal.args[0], candidate, next)) {
+      state.pending = index + 1 < groups.length;
+      yield next;
+    }
   }
+  state.pending = false;
 }
 
 function callableOrVariable(term, env) {
@@ -652,7 +666,12 @@ function clauseBodyTerm(body) {
   return result;
 }
 
-function* clauseBuiltin({ solver, goal, env }) {
+function clauseBuiltin(context) {
+  const state = { pending: false };
+  return withPendingState(clauseSolutions(context, state), state);
+}
+
+function* clauseSolutions({ solver, goal, env }, state) {
   const head = deref(goal.args[0], env);
   if (head.type === VAR) throw new PrologError('instantiation_error');
   if (head.type !== ATOM && head.type !== COMPOUND) throw new PrologError('type_error(callable)', head);
@@ -667,12 +686,17 @@ function* clauseBuiltin({ solver, goal, env }) {
   }
   callableOrVariable(goal.args[1], env);
   if (!group) return;
-  for (const clause of group.clauses) {
+  for (let index = 0; index < group.clauses.length; index++) {
+    const clause = group.clauses[index];
     const pair = compound('$clause', [clause.head, clauseBodyTerm(clause.body)]);
     const copied = freshCopy(pair, new Env());
     const next = env.clone();
-    if (unify(goal.args[0], copied.args[0], next) && unify(goal.args[1], copied.args[1], next)) yield next;
+    if (unify(goal.args[0], copied.args[0], next) && unify(goal.args[1], copied.args[1], next)) {
+      state.pending = index + 1 < group.clauses.length;
+      yield next;
+    }
   }
+  state.pending = false;
 }
 
 function clauseParts(term, env) {
@@ -845,21 +869,32 @@ function* abolishBuiltin({ solver, goal, env }) {
   yield env;
 }
 
-function* currentPrologFlagBuiltin({ solver, goal, env }) {
+function currentPrologFlagBuiltin(context) {
+  const state = { pending: false };
+  return withPendingState(currentPrologFlagSolutions(context, state), state);
+}
+
+function* currentPrologFlagSolutions({ solver, goal, env }, state) {
   const flag = deref(goal.args[0], env);
   if (flag.type !== VAR && flag.type !== ATOM) throw new PrologError('type_error(atom)', flag);
   if (flag.type === ATOM && !solver.prologFlags.has(flag.name)) {
     throw new PrologError('domain_error(prolog_flag)', flag);
   }
-  for (const [name, definition] of solver.prologFlags) {
+  const definitions = [...solver.prologFlags]
+    .filter(([name, definition]) => definition.value != null && (flag.type === VAR || flag.name === name));
+  for (let index = 0; index < definitions.length; index++) {
+    const [name, definition] = definitions[index];
     // ISO 7.11.1.1: when bounded=false, max_integer and min_integer have no
     // current value and current_prolog_flag/2 must therefore not enumerate
     // them. The definitions remain registered so attempts to change these
     // non-changeable flags still receive the normal flag error handling.
-    if (definition.value == null) continue;
     const next = env.clone();
-    if (unify(goal.args[0], atom(name), next) && unify(goal.args[1], definition.value, next)) yield next;
+    if (unify(goal.args[0], atom(name), next) && unify(goal.args[1], definition.value, next)) {
+      state.pending = index + 1 < definitions.length;
+      yield next;
+    }
   }
+  state.pending = false;
 }
 
 function* setPrologFlagBuiltin({ solver, goal, env }) {
@@ -946,7 +981,12 @@ function* opBuiltin({ solver, goal, env }) {
   yield env;
 }
 
-function* currentOpBuiltin({ solver, goal, env }) {
+function currentOpBuiltin(context) {
+  const state = { pending: false };
+  return withPendingState(currentOpSolutions(context, state), state);
+}
+
+function* currentOpSolutions({ solver, goal, env }, state) {
   const priority = deref(goal.args[0], env);
   const specifier = deref(goal.args[1], env);
   const name = deref(goal.args[2], env);
@@ -962,12 +1002,21 @@ function* currentOpBuiltin({ solver, goal, env }) {
     throw new PrologError('domain_error(operator_specifier)', specifier);
   }
   if (name.type !== VAR && name.type !== ATOM) throw new PrologError('type_error(atom)', name);
-  for (const definition of solver.program.operators.values()) {
+  const definitions = [...solver.program.operators.values()].filter((definition) =>
+    (priority.type === VAR || BigInt(priority.name) === BigInt(definition.priority)) &&
+    (specifier.type === VAR || specifier.name === definition.specifier) &&
+    (name.type === VAR || name.name === definition.name));
+  for (let index = 0; index < definitions.length; index++) {
+    const definition = definitions[index];
     const next = env.clone();
     if (unify(goal.args[0], numberTerm(definition.priority), next) &&
         unify(goal.args[1], atom(definition.specifier), next) &&
-        unify(goal.args[2], atom(definition.name), next)) yield next;
+        unify(goal.args[2], atom(definition.name), next)) {
+      state.pending = index + 1 < definitions.length;
+      yield next;
+    }
   }
+  state.pending = false;
 }
 
 function conversionCharacter(term, env, current = false, solver = null) {
@@ -998,13 +1047,25 @@ function* charConversionBuiltin({ solver, goal, env }) {
   else solver.charConversions.set(input.name, output.name);
   yield env;
 }
-function* currentCharConversionBuiltin({ solver, goal, env }) {
+function currentCharConversionBuiltin(context) {
+  const state = { pending: false };
+  return withPendingState(currentCharConversionSolutions(context, state), state);
+}
+
+function* currentCharConversionSolutions({ solver, goal, env }, state) {
   const input = conversionCharacter(goal.args[0], env, true, solver);
   const output = conversionCharacter(goal.args[1], env, true, solver);
-  for (const [from, to] of [...solver.charConversions]) {
+  const conversions = [...solver.charConversions].filter(([from, to]) =>
+    (input.type === VAR || input.name === from) && (output.type === VAR || output.name === to));
+  for (let index = 0; index < conversions.length; index++) {
+    const [from, to] = conversions[index];
     const next = env.clone();
-    if (unify(input, atom(from), next) && unify(output, atom(to), next)) yield next;
+    if (unify(input, atom(from), next) && unify(output, atom(to), next)) {
+      state.pending = index + 1 < conversions.length;
+      yield next;
+    }
   }
+  state.pending = false;
 }
 function* haltBuiltin({ goal, env }) {
   const code = goal.arity === 0 ? 0n : requireInteger(goal.args[0], env);
@@ -1293,7 +1354,12 @@ function isStreamPropertyPattern(value) {
   ].includes(value.name);
 }
 
-function* streamPropertyBuiltin({ solver, goal, env }) {
+function streamPropertyBuiltin(context) {
+  const state = { pending: false };
+  return withPendingState(streamPropertySolutions(context, state), state);
+}
+
+function* streamPropertySolutions({ solver, goal, env }, state) {
   const reference = deref(goal.args[0], env);
   const propertyPattern = deref(goal.args[1], env);
   let fixedStreamId = null;
@@ -1311,12 +1377,24 @@ function* streamPropertyBuiltin({ solver, goal, env }) {
   const streams = reference.type === VAR
     ? [...solver.io.streams.values()]
     : [solver.io.resolve(fixedStreamId)].filter(Boolean);
+  const candidates = [];
   for (const stream of streams) {
     for (const property of streamProperties(stream)) {
-      const next = env.clone();
-      if (unify(goal.args[0], streamHandle(stream.id), next) && unify(goal.args[1], property, next)) yield next;
+      if (propertyPattern.type === VAR ||
+          (property.type === propertyPattern.type && property.name === propertyPattern.name)) {
+        candidates.push([stream, property]);
+      }
+    }
+  }
+  for (let index = 0; index < candidates.length; index++) {
+    const [stream, property] = candidates[index];
+    const next = env.clone();
+    if (unify(goal.args[0], streamHandle(stream.id), next) && unify(goal.args[1], property, next)) {
+      state.pending = index + 1 < candidates.length;
+      yield next;
     }
   }
+  state.pending = false;
 }
 
 function inputStreamFor(solver, goal, env) {
@@ -1919,7 +1997,12 @@ function* atomLengthBuiltin({ goal, env }) {
   if (unify(goal.args[1], numberTerm(characters(value.name).length), next)) yield next;
 }
 
-function* atomConcatBuiltin({ goal, env }) {
+function atomConcatBuiltin(context) {
+  const state = { pending: false };
+  return withPendingState(atomConcatSolutions(context, state), state);
+}
+
+function* atomConcatSolutions({ goal, env }, state) {
   const first = deref(goal.args[0], env);
   const second = deref(goal.args[1], env);
   const whole = deref(goal.args[2], env);
@@ -1942,11 +2025,16 @@ function* atomConcatBuiltin({ goal, env }) {
   } else if (second.type === ATOM && whole.type === ATOM && whole.name.endsWith(second.name)) {
     candidates.push([whole.name.slice(0, whole.name.length - second.name.length), second.name, whole.name]);
   }
-  for (const [a, b, c] of candidates) {
+  for (let index = 0; index < candidates.length; index++) {
+    const [a, b, c] = candidates[index];
     const next = env.clone();
     if (unify(goal.args[0], atom(a), next) && unify(goal.args[1], atom(b), next) &&
-        unify(goal.args[2], atom(c), next)) yield next;
+        unify(goal.args[2], atom(c), next)) {
+      state.pending = index + 1 < candidates.length;
+      yield next;
+    }
   }
+  state.pending = false;
 }
 
 function optionalInteger(term, env) {
@@ -1956,7 +2044,12 @@ function optionalInteger(term, env) {
   return BigInt(value.name);
 }
 
-function* subAtomBuiltin({ goal, env }) {
+function subAtomBuiltin(context) {
+  const state = { pending: false };
+  return withPendingState(subAtomSolutions(context, state), state);
+}
+
+function* subAtomSolutions({ goal, env }, state) {
   const source = deref(goal.args[0], env);
   if (source.type === VAR) throw new PrologError('instantiation_error');
   if (source.type !== ATOM) throw new PrologError('type_error(atom)', source);
@@ -1977,11 +2070,34 @@ function* subAtomBuiltin({ goal, env }) {
     throw new PrologError('domain_error(not_less_than_zero)', deref(goal.args[3], env));
   }
   const chars = characters(source.name);
-  for (let start = 0; start <= chars.length; start++) {
-    if (before != null && before !== BigInt(start)) continue;
-    for (let size = 0; size <= chars.length - start; size++) {
+  let starts;
+  if (before != null) {
+    starts = before <= BigInt(chars.length) ? [Number(before)] : [];
+  } else if (length != null && after != null) {
+    const onlyStart = BigInt(chars.length) - length - after;
+    starts = onlyStart >= 0n ? [Number(onlyStart)] : [];
+  } else {
+    const maximumStart = length != null
+      ? BigInt(chars.length) - length
+      : after != null ? BigInt(chars.length) - after : BigInt(chars.length);
+    starts = maximumStart < 0n
+      ? []
+      : Array.from({ length: Number(maximumStart) + 1 }, (_, index) => index);
+  }
+  for (let startIndex = 0; startIndex < starts.length; startIndex++) {
+    const start = starts[startIndex];
+    let sizes;
+    if (length != null) {
+      sizes = length <= BigInt(chars.length - start) ? [Number(length)] : [];
+    } else if (after != null) {
+      const onlySize = BigInt(chars.length - start) - after;
+      sizes = onlySize >= 0n ? [Number(onlySize)] : [];
+    } else {
+      sizes = Array.from({ length: chars.length - start + 1 }, (_, index) => index);
+    }
+    for (let sizeIndex = 0; sizeIndex < sizes.length; sizeIndex++) {
+      const size = sizes[sizeIndex];
       const remaining = chars.length - start - size;
-      if (length != null && length !== BigInt(size)) continue;
       if (after != null && after !== BigInt(remaining)) continue;
       const text = chars.slice(start, start + size).join('');
       if (sub.type === ATOM && sub.name !== text) continue;
@@ -1989,9 +2105,13 @@ function* subAtomBuiltin({ goal, env }) {
       if (unify(goal.args[1], numberTerm(start), next) &&
           unify(goal.args[2], numberTerm(size), next) &&
           unify(goal.args[3], numberTerm(remaining), next) &&
-          unify(goal.args[4], atom(text), next)) yield next;
+          unify(goal.args[4], atom(text), next)) {
+        state.pending = sizeIndex + 1 < sizes.length || startIndex + 1 < starts.length;
+        yield next;
+      }
     }
   }
+  state.pending = false;
 }
 
 function listElements(term, env) {
@@ -2406,42 +2526,52 @@ function sortedUnique(items) {
 }
 
 function allSolutionsBuiltin(asSet) {
-  return function* ({ solver, goal, env }) {
-    // EyeProlog validates the iterated goal before Instances. ISO 7.12 makes
-    // simultaneous-error selection implementation dependent; keep this stable as
-    // a processor choice rather than describing it as mandatory table ordering.
-    const { iterated, quantified } = bagGoalParts(goal.args[1], env);
-    assertListOrPartial(goal.args[2], env);
-    const free = freeVariables(iterated, goal.args[0], quantified, env);
-    const collector = solver.cloneForInnerGoal(10000000);
-    const groups = [];
-    for (const answerEnv of collector.solve([iterated], env.clone(), 0)) {
-      const copied = freshCopy(compound('$bag', [
-        compound('$witness', free),
-        goal.args[0],
-      ]), answerEnv);
-      let group = groups.find((candidate) => sameWitness(candidate.witness, copied.args[0]));
-      if (!group) {
-        group = { witness: copied.args[0], templates: [] };
-        groups.push(group);
-        group.templates.push(copied.args[1]);
-      } else {
-        const alignment = new Env();
-        unify(copied.args[0], group.witness, alignment);
-        group.templates.push(copyResolved(copied.args[1], alignment));
-      }
+  return function allSolutions(context) {
+    const state = { pending: false };
+    return withPendingState(allSolutionsGroups(context, asSet, state), state);
+  };
+}
+
+function* allSolutionsGroups({ solver, goal, env }, asSet, state) {
+  // EyeProlog validates the iterated goal before Instances. ISO 7.12 makes
+  // simultaneous-error selection implementation dependent; keep this stable as
+  // a processor choice rather than describing it as mandatory table ordering.
+  const { iterated, quantified } = bagGoalParts(goal.args[1], env);
+  assertListOrPartial(goal.args[2], env);
+  const free = freeVariables(iterated, goal.args[0], quantified, env);
+  const collector = solver.cloneForInnerGoal(10000000);
+  const groups = [];
+  for (const answerEnv of collector.solve([iterated], env.clone(), 0)) {
+    const copied = freshCopy(compound('$bag', [
+      compound('$witness', free),
+      goal.args[0],
+    ]), answerEnv);
+    let group = groups.find((candidate) => sameWitness(candidate.witness, copied.args[0]));
+    if (!group) {
+      group = { witness: copied.args[0], templates: [] };
+      groups.push(group);
+      group.templates.push(copied.args[1]);
+    } else {
+      const alignment = new Env();
+      unify(copied.args[0], group.witness, alignment);
+      group.templates.push(copyResolved(copied.args[1], alignment));
     }
-    solver.absorbStatsFrom(collector);
-    for (const group of groups) {
-      const next = env.clone();
-      let matches = true;
-      for (let i = 0; i < free.length; i++) {
-        if (!unify(free[i], group.witness.args[i], next)) { matches = false; break; }
-      }
-      const templates = asSet ? sortedUnique(group.templates) : group.templates;
-      if (matches && unify(goal.args[2], listFromItems(templates), next)) yield next;
+  }
+  solver.absorbStatsFrom(collector);
+  for (let index = 0; index < groups.length; index++) {
+    const group = groups[index];
+    const next = env.clone();
+    let matches = true;
+    for (let i = 0; i < free.length; i++) {
+      if (!unify(free[i], group.witness.args[i], next)) { matches = false; break; }
     }
-  };
+    const templates = asSet ? sortedUnique(group.templates) : group.templates;
+    if (matches && unify(goal.args[2], listFromItems(templates), next)) {
+      state.pending = index + 1 < groups.length;
+      yield next;
+    }
+  }
+  state.pending = false;
 }
 const bagofBuiltin = allSolutionsBuiltin(false);
 const setofBuiltin = allSolutionsBuiltin(true);
@@ -2964,8 +3094,12 @@ function* onceBuiltin({ solver, goal, env }) {
   }
   solver.absorbStatsFrom(child);
 }
-function* repeatBuiltin({ env }) {
-  while (true) yield env;
+function repeatBuiltin({ env }) {
+  const iterator = (function* repeatSolutions() {
+    while (true) yield env;
+  })();
+  iterator.hasPendingAlternatives = () => true;
+  return iterator;
 }
 function* negationBuiltin({ solver, goal, env }) {
   const invoked = callable(goal.args[0], env);

package/src/scryer-compat.js

@@ -103,7 +103,14 @@ function validCharType(term) {
     (term.type === COMPOUND && ['lower', 'upper'].includes(term.name) && term.arity === 1);
 }
 
-function* charTypeBuiltin({ goal, env }) {
+function charTypeBuiltin(context) {
+  const state = { pending: false };
+  const iterator = charTypeSolutions(context, state);
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
+}
+
+function* charTypeSolutions({ goal, env }, state) {
   const char = deref(goal.args[0], env);
   const type = deref(goal.args[1], env);
   if (char.type === VAR && type.type === VAR) throw new PrologError('instantiation_error');
@@ -112,20 +119,23 @@ function* charTypeBuiltin({ goal, env }) {
   }
   if (type.type !== VAR && !validCharType(type)) throw new PrologError('domain_error(char_type)', type);
 
-  const chars = char.type === VAR
-    ? (function* unicodeScalars() {
-        for (let code = 0; code <= 0x10ffff; code++) {
-          if (code >= 0xd800 && code <= 0xdfff) continue;
-          yield String.fromCodePoint(code);
-        }
-      })()
-    : [char.name];
-  for (const ch of chars) {
-    for (const candidate of charTypeCandidates(ch)) {
+  const firstCode = char.type === VAR ? 0 : char.name.codePointAt(0);
+  const lastCode = char.type === VAR ? 0x10ffff : firstCode;
+  for (let code = firstCode; code <= lastCode; code++) {
+    if (code >= 0xd800 && code <= 0xdfff) continue;
+    const ch = String.fromCodePoint(code);
+    const candidates = charTypeCandidates(ch).filter((candidate) =>
+      type.type === VAR || (candidate.type === type.type && candidate.name === type.name));
+    for (let index = 0; index < candidates.length; index++) {
+      const candidate = candidates[index];
       const next = env.clone();
-      if (unify(goal.args[0], atom(ch), next) && unify(goal.args[1], candidate, next)) yield next;
+      if (unify(goal.args[0], atom(ch), next) && unify(goal.args[1], candidate, next)) {
+        state.pending = index + 1 < candidates.length || code < lastCode;
+        yield next;
+      }
     }
   }
+  state.pending = false;
 }
 
 const shortMonths = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',

package/src/solver.js

@@ -1371,7 +1371,14 @@ function groupNeedsActiveFrame(group) {
   return group.cutReachable !== false || (group.recursive && !group.linearNumeric);
 }
 
-function* datalogAnswerSolutions(solver, relation, goal, env) {
+function datalogAnswerSolutions(solver, relation, goal, env) {
+  const state = { pending: false };
+  const iterator = datalogAnswerGenerator(solver, relation, goal, env, state);
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
+}
+
+function* datalogAnswerGenerator(solver, relation, goal, env, state) {
   if (!relation) return;
   const candidates = datalogCandidateIndexes(
     relation,
@@ -1380,20 +1387,26 @@ function* datalogAnswerSolutions(solver, relation, goal, env) {
     derefForLocal,
     memoAnswerScalarKey,
   );
-  const visit = function* (rowIndex) {
+  const indexes = candidates == null
+    ? { length: relation.rows.length, at: (index) => index }
+    : { length: candidates.length, at: (index) => candidates[index] };
+  for (let position = 0; position < indexes.length; position++) {
+    const rowIndex = indexes.at(position);
     const row = relation.rows[rowIndex];
     const next = env.clone();
+    let matches = true;
     for (let i = 0; i < goal.arity; i++) {
       solver.stats.unify_calls++;
-      if (!unify(goal.args[i], row[i], next)) return;
+      if (!unify(goal.args[i], row[i], next)) {
+        matches = false;
+        break;
+      }
     }
+    if (!matches) continue;
+    state.pending = position + 1 < indexes.length;
     yield next;
-  };
-  if (candidates == null) {
-    for (let rowIndex = 0; rowIndex < relation.rows.length; rowIndex++) yield* visit(rowIndex);
-    return;
   }
-  for (const rowIndex of candidates) yield* visit(rowIndex);
+  state.pending = false;
 }
 
 function pushWfsAnswerFrames(stack, model, group, goal, rest, env, depth, active, solver) {
@@ -1428,7 +1441,10 @@ function bundledBetweenIterator(solver, group, goal, env) {
   // the generated value in the caller repeatedly revisits all earlier frames.
   // Enumerate the canonical bundled relation directly while leaving user
   // definitions and non-EyeProlog registries on the ordinary Prolog path.
-  return bundledBetweenSolutions(solver, goal, env);
+  const state = { pending: false };
+  const iterator = bundledBetweenSolutions(solver, goal, env, state);
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
 }
 
 function requireBetweenInteger(term, env) {
@@ -1440,7 +1456,7 @@ function requireBetweenInteger(term, env) {
   return BigInt(value.name);
 }
 
-function* bundledBetweenSolutions(solver, goal, env) {
+function* bundledBetweenSolutions(solver, goal, env, state) {
   const lower = requireBetweenInteger(goal.args[0], env);
   const upper = requireBetweenInteger(goal.args[1], env);
   const requested = deref(goal.args[2], env);
@@ -1457,8 +1473,12 @@ function* bundledBetweenSolutions(solver, goal, env) {
   for (let value = lower; value <= upper; value++) {
     const next = env.clone();
     solver.stats.unify_calls++;
-    if (unify(goal.args[2], numberTerm(value), next)) yield next;
+    if (unify(goal.args[2], numberTerm(value), next)) {
+      state.pending = value < upper;
+      yield next;
+    }
   }
+  state.pending = false;
 }
 
 function bundledMemberIterator(solver, group, goal, env) {
@@ -1468,25 +1488,48 @@ function bundledMemberIterator(solver, group, goal, env) {
     return null;
   }
 
-  // Keep the relational/open-list cases in ordinary Prolog.  When the second
-  // argument is already a finite list, however, the canonical two-clause
-  // member/2 definition is exactly a left-to-right scan and can avoid clause
-  // freshening and recursive solver frames for every element.
-  let cursor = deref(goal.args[1], env);
-  while (isCons(cursor)) cursor = deref(cursor.args[1], env);
-  if (!isEmptyList(cursor)) return null;
-  return bundledMemberSolutions(solver, goal, env);
+  // Attributed and delayed list variables retain the ordinary clause path so
+  // their hooks and wake-up boundaries remain source-defined. Plain proper,
+  // partial, and improper lists can all follow the canonical two-clause
+  // relation lazily without first traversing the spine.
+  if (env._prologAttributes != null || env._delays != null) return null;
+  const state = { pending: false };
+  const iterator = bundledMemberSolutions(solver, goal, env, state);
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
 }
 
-function* bundledMemberSolutions(solver, goal, env) {
+function* bundledMemberSolutions(solver, goal, env, state) {
   let cursor = deref(goal.args[1], env);
   while (isCons(cursor)) {
     const item = cursor.args[0];
     cursor = deref(cursor.args[1], env);
     const next = env.clone();
     solver.stats.unify_calls++;
-    if (unify(goal.args[0], item, next)) yield next;
+    if (unify(goal.args[0], item, next)) {
+      // The tail itself is the pending search state. Do not inspect it for a
+      // future successful unification: an untried list position remains a
+      // choicepoint even when resuming it will eventually fail.
+      state.pending = isCons(cursor) || cursor.type === VAR;
+      yield next;
+    }
   }
+  if (cursor.type === VAR) {
+    const openTail = cursor;
+    const id = nextFreshId();
+    let candidate = cons(goal.args[0], variable(`__member${id}_tail`));
+    for (let before = 0n; ; before++) {
+      const next = env.clone();
+      solver.stats.unify_calls++;
+      if (unify(openTail, candidate, next)) {
+        state.pending = true;
+        yield next;
+      }
+      candidate = cons(variable(`__member${id}_head_${before}`), candidate);
+      generatedLengthAllocationCheckpoint(solver, before + 1n);
+    }
+  }
+  state.pending = false;
 }
 
 function bundledEllipsisPlan(solver, group, goal, rest, env) {
@@ -1520,7 +1563,7 @@ function bundledEllipsisPlan(solver, group, goal, rest, env) {
         if (output.type === VAR && continuationInput.type === VAR && output.name === continuationInput.name &&
             output.name.startsWith('\u0000dcg')) {
           return {
-            iterator: bundledEllipsisSolutions(solver, continuation.args[1], input, env),
+            iterator: bundledEllipsisIterator(solver, continuation.args[1], input, env),
             rest: rest.slice(1),
           };
         }
@@ -1528,7 +1571,14 @@ function bundledEllipsisPlan(solver, group, goal, rest, env) {
     }
   }
 
-  return { iterator: bundledEllipsisSolutions(solver, goal.args[1], input, env), rest };
+  return { iterator: bundledEllipsisIterator(solver, goal.args[1], input, env), rest };
+}
+
+function bundledEllipsisIterator(solver, output, input, env) {
+  const state = { pending: false };
+  const iterator = bundledEllipsisSolutions(solver, output, input, env, state);
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
 }
 
 function isBinaryIdentityGroup(group) {
@@ -1548,7 +1598,7 @@ function isBinaryIdentityGroup(group) {
     (a.name === right.name && b.name === left.name);
 }
 
-function* bundledEllipsisSolutions(solver, output, input, env) {
+function* bundledEllipsisSolutions(solver, output, input, env, state) {
   let cursor = input;
   const requestedOutput = deref(output, env);
 
@@ -1568,7 +1618,10 @@ function* bundledEllipsisSolutions(solver, output, input, env) {
   while (true) {
     const next = env.clone();
     solver.stats.unify_calls++;
-    if (unify(output, cursor, next)) yield next;
+    if (unify(output, cursor, next)) {
+      state.pending = isCons(cursor);
+      yield next;
+    }
     if (isEmptyList(cursor)) return;
     if (!isCons(cursor)) return;
     cursor = deref(cursor.args[1], env);
@@ -1601,7 +1654,14 @@ function bundledLengthIterator(solver, group, goal, env) {
       if (length.type === VAR && cursor.name === length.name) return null;
     }
   }
-  return bundledLengthSolutions(solver, goal, env);
+  const state = {
+    // length(OpenList, Length) has an unbounded succession of longer lists.
+    // All other accepted fast-path modes are semidet.
+    pending: length.type === VAR && cursor.type === VAR,
+  };
+  const iterator = bundledLengthSolutions(solver, goal, env);
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
 }
 
 function* bundledLengthSolutions(solver, goal, env) {
@@ -2185,7 +2245,14 @@ function pushStreamingScalarFactRun(stack, solver, runGoals, groups, rest, env,
   });
 }
 
-function* scalarFactRunSolutions(solver, goals, groups, env, depth, active) {
+function scalarFactRunSolutions(solver, goals, groups, env, depth, active) {
+  const state = { pending: false };
+  const iterator = scalarFactRunGenerator(solver, goals, groups, env, depth, active, state);
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
+}
+
+function* scalarFactRunGenerator(solver, goals, groups, env, depth, active, pendingState) {
   const localStack = [{ index: 0, names: [], values: [] }];
   while (localStack.length) {
     const state = localStack.pop();
@@ -2194,6 +2261,7 @@ function* scalarFactRunSolutions(solver, goals, groups, env, depth, active) {
       const next = env.clone();
       for (let i = 0; i < state.names.length; i++) next.bind(state.names[i], state.values[i]);
       if (next._variableConstraints != null && !next.validateVariableConstraints()) continue;
+      pendingState.pending = localStack.length !== 0;
       yield next;
       continue;
     }
@@ -2218,6 +2286,7 @@ function* scalarFactRunSolutions(solver, goals, groups, env, depth, active) {
     for (let i = nextStates.length - 1; i >= 0; i--) localStack.push(nextStates[i]);
     if (solver.solutionsSeen >= solver.solutionLimit) return;
   }
+  pendingState.pending = false;
 }
 
 
@@ -2813,64 +2882,13 @@ function builtinIsReadyOrAuthoritative(def, solver, goal, env) {
 
 function iteratorMayHavePendingAlternatives(iterator) {
   const predicate = iterator?.hasPendingAlternatives;
-  return typeof predicate === 'function' && predicate.call(iterator) !== false;
-}
-
-function lookaheadChoiceIterator(iterator) {
-  let buffered = null;
-  let bufferedReady = false;
-  let closed = false;
-
-  const fill = () => {
-    if (closed || bufferedReady) return;
-    buffered = iterator.next();
-    bufferedReady = true;
-    if (buffered.done) closed = true;
-  };
-
-  return {
-    next() {
-      fill();
-      if (buffered?.done !== false) return buffered ?? { done: true, value: undefined };
-      const result = buffered;
-      buffered = null;
-      bufferedReady = false;
-      // Ordinary relational iterators are advanced by one answer so their
-      // exhausted state is known before this answer reaches the caller.
-      fill();
-      return result;
-    },
-    return(value) {
-      if (!closed) iterator.return?.();
-      closed = true;
-      buffered = { done: true, value };
-      bufferedReady = true;
-      return buffered;
-    },
-    throw(error) {
-      closed = true;
-      if (typeof iterator.throw === 'function') return iterator.throw(error);
-      throw error;
-    },
-    prepareClose(reason) {
-      iterator.prepareClose?.(reason);
-    },
-    hasPendingAlternatives() {
-      fill();
-      return buffered?.done === false;
-    },
-    [Symbol.iterator]() { return this; },
-  };
-}
-
-function choicepointAwareIterator(iterator) {
-  return typeof iterator?.hasPendingAlternatives === 'function'
-    ? iterator
-    : lookaheadChoiceIterator(iterator);
+  // An unannotated suspended iterator is itself an untried continuation.
+  // Advancing it here would speculatively execute Prolog search (and possibly
+  // effects) merely to discover whether a later answer succeeds.
+  return typeof predicate !== 'function' || predicate.call(iterator) !== false;
 }
 
 function pushResumeBuiltinFrame(stack, iterator, goals, depth, active) {
-  iterator = choicepointAwareIterator(iterator);
   if (!iteratorMayHavePendingAlternatives(iterator)) {
     // Finish the suspended generator now so its finally blocks release child
     // solvers, aggregate statistics, and perform predicate-local cleanup.

package/src/standard-library.js

@@ -274,7 +274,14 @@ function* statisticsBuiltin({ solver, env }) {
   yield env;
 }
 
-function* statisticsValueBuiltin({ solver, goal, env }) {
+function statisticsValueBuiltin(context) {
+  const state = { pending: false };
+  const iterator = statisticsValueSolutions(context, state);
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
+}
+
+function* statisticsValueSolutions({ solver, goal, env }, state) {
   const snapshot = runtimeStatistics(solver);
   const key = deref(goal.args[0], env);
   const entries = key.type === VAR
@@ -288,10 +295,15 @@ function* statisticsValueBuiltin({ solver, goal, env }) {
     throw new PrologError('domain_error(statistics_key)', key);
   }
 
-  for (const [name, value] of entries) {
+  for (let index = 0; index < entries.length; index++) {
+    const [name, value] = entries[index];
     const next = env.clone();
-    if (unify(goal.args[0], atom(name), next) && unify(goal.args[1], numberTerm(value), next)) yield next;
+    if (unify(goal.args[0], atom(name), next) && unify(goal.args[1], numberTerm(value), next)) {
+      state.pending = index + 1 < entries.length;
+      yield next;
+    }
   }
+  state.pending = false;
 }
 
 export function createEyePrologRegistry() {

package/src/term.js

@@ -65,7 +65,7 @@ export class CompactListTerm {
     }
     return this._args;
   }
-  mayContainVariable(name) {
+  mayContainVariable(name, env = null) {
     if (String(name).startsWith(this._variablePrefix)) {
       const indexText = String(name).slice(this._variablePrefix.length);
       if (/^\d+$/.test(indexText)) {
@@ -73,9 +73,12 @@ export class CompactListTerm {
         if (index >= this._offset && index < this._offset + this._compactLength) return true;
       }
     }
-    // If no generated head in this suffix has ever participated in a binding,
-    // an unrelated variable cannot occur below it. This remains conservative
-    // across backtracking because the high-water mark is never rolled back.
+    // An Env keeps the exact backtrackable set of cells whose current values
+    // may reach an external variable. Without one, retain the shared
+    // high-water mark as a conservative public-API fallback.
+    if (env?.compactListMayReachExternalVariable != null) {
+      return env.compactListMayReachExternalVariable(this._compactState, this._offset);
+    }
     return this._compactState.maxPossiblyBoundIndex >= this._offset;
   }
 }
@@ -124,6 +127,11 @@ export class Env {
     this._backtrackableBlackboard = null;
     this._occursCheckHandler = null;
     this._localVariables = null;
+    // Origins carried by variables that temporarily represent compact-list
+    // cells. Indexed by logical variable name because callers may reconstruct
+    // an equivalent Term object while environments retain name identity.
+    this._compactVariableOrigins = null;
+    this._compactVariableRisks = null;
   }
   clone() {
     // Most speculative environments are either rejected without a binding or
@@ -142,6 +150,8 @@ export class Env {
     clone._backtrackableBlackboard = this._backtrackableBlackboard;
     clone._occursCheckHandler = this._occursCheckHandler;
     clone._localVariables = this._localVariables;
+    clone._compactVariableOrigins = this._compactVariableOrigins;
+    clone._compactVariableRisks = this._compactVariableRisks;
     return clone;
   }
   setOccursCheckHandler(handler) {
@@ -164,8 +174,80 @@ export class Env {
     // Execution callbacks belong to the Solver driving this Env, not to the
     // logical branch being adopted from an inner attribute-hook call.
     this._localVariables = other._localVariables;
+    this._compactVariableOrigins = other._compactVariableOrigins;
+    this._compactVariableRisks = other._compactVariableRisks;
     return this;
   }
+  compactVariableOrigins(name) {
+    return this._compactVariableOrigins?.get(name) ?? null;
+  }
+  transferCompactVariableOrigins(sourceName, targetName, origins) {
+    const next = new Map(this._compactVariableOrigins ?? []);
+    if (sourceName !== targetName) next.delete(sourceName);
+    next.set(targetName, origins);
+    this._compactVariableOrigins = next.size === 0 ? null : next;
+  }
+  removeCompactVariableOrigins(name) {
+    if (this._compactVariableOrigins?.has(name) !== true) return;
+    const next = new Map(this._compactVariableOrigins);
+    next.delete(name);
+    this._compactVariableOrigins = next.size === 0 ? null : next;
+  }
+  addCompactVariableRisks(origins) {
+    if (origins.length === 0) return;
+    const next = new Map(this._compactVariableRisks ?? []);
+    for (const { state, index } of origins) {
+      const current = next.get(state) ?? null;
+      let top = current?.top ?? null;
+      const removed = current?.removed ?? null;
+      while (top != null && removed?.has(top)) top = top.parent;
+      // Immediate variable-to-variable handoffs carry the same origin. Avoid
+      // stacking duplicate risk entries along that common alias chain.
+      if (top?.index === index) continue;
+      next.set(state, { top: { index, parent: top }, removed });
+    }
+    this._compactVariableRisks = next;
+  }
+  removeCompactVariableRisks(origins) {
+    if (origins.length === 0 || this._compactVariableRisks == null) return;
+    const next = new Map(this._compactVariableRisks);
+    for (const { state, index } of origins) {
+      const current = next.get(state);
+      if (current == null) continue;
+      let top = current.top;
+      let removed = current.removed;
+      while (top != null && removed?.has(top)) top = top.parent;
+      if (top?.index === index) {
+        top = top.parent;
+        while (top != null && removed?.has(top)) top = top.parent;
+      } else {
+        // Out-of-order handoffs are uncommon, but remain exact: tombstone
+        // every active entry for this origin without rewriting the persistent
+        // stack shared by sibling environments.
+        let scan = top;
+        let changed = false;
+        while (scan != null) {
+          if (scan.index === index && removed?.has(scan) !== true) {
+            if (!changed) removed = new Set(removed ?? []);
+            removed.add(scan);
+            changed = true;
+          }
+          scan = scan.parent;
+        }
+      }
+      if (top == null) next.delete(state);
+      else next.set(state, { top, removed });
+    }
+    this._compactVariableRisks = next.size === 0 ? null : next;
+  }
+  compactListMayReachExternalVariable(state, offset) {
+    const current = this._compactVariableRisks?.get(state);
+    if (current == null) return false;
+    for (let entry = current.top; entry != null; entry = entry.parent) {
+      if (current.removed?.has(entry) !== true && entry.index >= offset) return true;
+    }
+    return false;
+  }
   getBacktrackableBlackboard(key) {
     return this._backtrackableBlackboard?.get(key);
   }
@@ -605,7 +687,7 @@ function occursUncached(variableName, term, env) {
       if (binding !== undefined) stack.push(binding);
       continue;
     }
-    if (isCompactList(current) && !current.mayContainVariable(variableName)) continue;
+    if (isCompactList(current) && !current.mayContainVariable(variableName, env)) continue;
     if (current?.type !== COMPOUND || seenTerms.has(current)) continue;
     seenTerms.add(current);
     for (let i = 0; i < current.arity; i++) stack.push(current.args[i]);
@@ -693,11 +775,11 @@ export function unify(left, right, env, options = {}) {
       const aLocalDcg = env?.isLocalVariable(a.name) === true &&
         a.name.startsWith('\u0000dcg') && b.name.startsWith('\u0000dcg');
       if (aLocalDcg) {
-        markCompactVariableBound(b);
+        transferCompactVariableOrigins(b, a, env);
         env?.finalizePrologAttributeAlias?.(b.name, a.name);
         env.bind(b.name, a);
       } else {
-        markCompactVariableBound(a);
+        transferCompactVariableOrigins(a, b, env);
         env?.finalizePrologAttributeAlias?.(a.name, b.name);
         env.bind(a.name, b);
       }
@@ -715,7 +797,7 @@ export function unify(left, right, env, options = {}) {
         b = deref(b, env);
         if (a.type !== VAR) { stack.push([a, b]); continue; }
       }
-      markCompactVariableBound(a);
+      markCompactVariableBound(a, b, env);
       env?.dropPrologAttributes?.(a.name);
       env.bind(a.name, b);
       if (aLocal) env.forgetLocalVariable(a.name);
@@ -733,7 +815,7 @@ export function unify(left, right, env, options = {}) {
         a = deref(a, env);
         if (b.type !== VAR) { stack.push([a, b]); continue; }
       }
-      markCompactVariableBound(b);
+      markCompactVariableBound(b, a, env);
       env?.dropPrologAttributes?.(b.name);
       env.bind(b.name, a);
       if (bLocal) env.forgetLocalVariable(b.name);
@@ -761,10 +843,50 @@ export function unify(left, right, env, options = {}) {
   return true;
 }
 
-function markCompactVariableBound(term) {
-  if (term?._compactState == null || term._compactIndex == null) return;
-  if (term._compactIndex > term._compactState.maxPossiblyBoundIndex) {
-    term._compactState.maxPossiblyBoundIndex = term._compactIndex;
+function compactVariableOrigins(term, env) {
+  const remembered = term?.type === VAR ? env?.compactVariableOrigins(term.name) : null;
+  const origins = remembered == null ? [] : [...remembered];
+  if (term?._compactState != null && term._compactIndex != null &&
+      !origins.some(({ state, index }) => state === term._compactState && index === term._compactIndex)) {
+    origins.push({ state: term._compactState, index: term._compactIndex });
+  }
+  return origins;
+}
+
+function transferCompactVariableOrigins(source, target, env) {
+  const sourceOrigins = compactVariableOrigins(source, env);
+  if (sourceOrigins.length === 0 || target?.type !== VAR) return;
+  const targetOrigins = compactVariableOrigins(target, env);
+  for (const origin of sourceOrigins) {
+    if (!targetOrigins.some(({ state, index }) => state === origin.state && index === origin.index)) {
+      targetOrigins.push(origin);
+    }
+  }
+  env?.addCompactVariableRisks(sourceOrigins);
+  env?.transferCompactVariableOrigins(source.name, target.name, targetOrigins);
+}
+
+function markCompactVariableBound(term, value, env) {
+  const origins = compactVariableOrigins(term, env);
+  if (origins.length === 0) return;
+  // A compact cell commonly passes through a fresh clause variable before it
+  // receives its actual value. Carry the provenance along that alias. Only a
+  // non-scalar value can make an unrelated logical variable reachable from
+  // the compact list, so ground atoms and numbers need not poison the whole
+  // suffix for subsequent finite-tree occurs checks.
+  if (value?.type === VAR) {
+    transferCompactVariableOrigins(term, value, env);
+    return;
+  }
+  if (isScalar(value)) {
+    env?.removeCompactVariableRisks(origins);
+    env?.removeCompactVariableOrigins(term.name);
+    return;
+  }
+  env?.addCompactVariableRisks(origins);
+  env?.removeCompactVariableOrigins(term.name);
+  for (const { state, index } of origins) {
+    if (index > state.maxPossiblyBoundIndex) state.maxPossiblyBoundIndex = index;
   }
 }
 

package/test/run-regression.mjs

@@ -29,6 +29,7 @@ import {
   eyePrologInteropLibraryIndicators,
   eyePrologInteropLibraryModules,
   atom,
+  compactVariableList,
   compound,
   listFromItems,
   numberTerm,
@@ -2302,16 +2303,32 @@ c4 ?- call((!;1)).
         const custom = new Solver(Program.parse(''), { registry: customRegistry });
         const customSolutions = custom.solve([parseGoalText('single(X)')], new Env(), 0);
         assertEqual(customSolutions.next().done, false, 'custom relational iterator answer');
-        assertEqual(custom.hasPendingAlternatives(), false,
-          'unannotated relational iterator uses the universal lookahead protocol');
+        assertEqual(custom.hasPendingAlternatives(), true,
+          'an unannotated suspended iterator remains an untried continuation');
         customSolutions.return();
 
+        const annotatedRegistry = new BuiltinRegistry();
+        annotatedRegistry.add('single', 1, ({ goal, env }) => {
+          const iterator = (function* singleSolution() {
+            const next = env.clone();
+            if (unify(goal.args[0], atom('only'), next)) yield next;
+          })();
+          iterator.hasPendingAlternatives = () => false;
+          return iterator;
+        });
+        const annotated = new Solver(Program.parse(''), { registry: annotatedRegistry });
+        const annotatedSolutions = annotated.solve([parseGoalText('single(X)')], new Env(), 0);
+        assertEqual(annotatedSolutions.next().done, false, 'annotated relational iterator answer');
+        assertEqual(annotated.hasPendingAlternatives(), false,
+          'an iterator may report exact exhaustion without being resumed');
+        annotatedSolutions.return();
+
         const dynamicProgram = Program.parse(':- dynamic(p/1).\np(a).\np(b).\n');
         const dynamicSolver = new Solver(dynamicProgram, { registry: getEyePrologRegistry() });
         const dynamicSolutions = dynamicSolver.solve([parseGoalText('catch(retract(p(X)),_,fail)')], new Env(), 0);
         assertEqual(dynamicSolutions.next().done, false, 'stateful protected iterator first answer');
         assertEqual(dynamicProgram.findGroup('p', 1).clauses.length, 1,
-          'lookahead does not perform the next retraction');
+          'pending-state inspection does not perform the next retraction');
         assertEqual(dynamicSolver.hasPendingAlternatives(), true,
           'stateful protected iterator retains its real second retraction');
         dynamicSolutions.return();
@@ -2320,27 +2337,91 @@ c4 ?- call((!;1)).
       },
     },
     {
-      name: 'bound member tails do not invent predicate choicepoints (issue #74 follow-up)',
+      name: 'member/2 retains untried positions without scanning them (issue #74 comment 5435449600)',
       run: () => {
         const result = runCli([], {
           input:
             'use_module(library(lists)).\n' +
-            'L=[i],append(L,_,[i|L]).\n' +
-            'L=[_],append(L,_,[i|L]).\n' +
-            'L=[i],append(L,_,[i|L]),member(a,[a|L]).\n' +
-            'L=[_],append(L,_,[i|L]),member(a,[a|L]).\n' +
+            'L=[i],append(L,_,[i|L]),' +
+              '(Det=preparing;setup_call_cleanup(true,member(a,[a|L]),Det=yes)).\n' +
+            ';\n' +
+            'setup_call_cleanup(true,member(a,[a]),Det=yes).\n' +
             'halt.\n',
         });
         assertEqual(result.status, 0, 'exit status');
         assertEqual(result.stdout,
           '?-    true.\n' +
-          '?-    L = "i".\n' +
-          '?-    L = "i".\n' +
-          '?-    L = "i".\n' +
-          '?-    L = "i".\n' +
+          '?-    L = "i", Det = preparing\n' +
+          ';  L = "i".\n' +
+          '?-    Det = yes.\n' +
           '?- ',
-          'ground and formerly variable list elements have identical determinism');
+          'cleanup observes the real list-position choicepoint');
         assertEqual(result.stderr, '', 'stderr');
+
+        let speculativeTailRead = false;
+        const unreadTail = {
+          type: 'compound',
+          name: '.',
+          get arity() { return 2; },
+          get args() {
+            speculativeTailRead = true;
+            throw new Error('member/2 inspected an untried tail position');
+          },
+        };
+        const memberGoal = compound('member', [atom('a'), compound('.', [atom('a'), unreadTail])]);
+        memberGoal.module = 'lists';
+        const solver = new Solver(Program.parse(':- use_module(library(lists)).'), {
+          registry: getEyePrologRegistry(),
+        });
+        const solutions = solver.solve([memberGoal], new Env(), 0);
+        assertEqual(solutions.next().done, false, 'member/2 first answer');
+        assertEqual(speculativeTailRead, false, 'first answer does not inspect the tail');
+        assertEqual(solver.hasPendingAlternatives(), true, 'unread tail is a genuine alternative');
+        solutions.return();
+        assertEqual(speculativeTailRead, false, 'discarding the choicepoint does not inspect it');
+
+        const compactAppendTail = compactVariableList(100000n, '__appendTail');
+        const appendGoal = compound('append', [
+          variable('Prefix'),
+          compound('.', [atom('a'), variable('Suffix')]),
+          compound('.', [atom('a'), compactAppendTail]),
+        ]);
+        appendGoal.module = 'lists';
+        const appendSolver = new Solver(Program.parse(':- use_module(library(lists)).'), {
+          registry: getEyePrologRegistry(),
+        });
+        const appendSolutions = appendSolver.solve([appendGoal], new Env(), 0);
+        assertEqual(appendSolutions.next().done, false, 'append/3 first answer');
+        assertEqual(compactAppendTail._args, null, 'append/3 first answer does not expand the tail');
+        assertEqual(appendSolver.hasPendingAlternatives(), true, 'append/3 retains its recursive alternative');
+        appendSolutions.return();
+        assertEqual(compactAppendTail._args, null, 'discarding append/3 alternatives does not expand the tail');
+
+        const compact = compactVariableList(100000n, '__scalarCompact');
+        const firstCell = compact.args[0];
+        const env = new Env();
+        assertEqual(unify(firstCell, variable('ClauseHead'), env), true,
+          'compact cell aliases a clause-head variable');
+        assertEqual(unify(variable('ClauseHead'), atom('i'), env), true,
+          'the clause-head variable receives its scalar value');
+
+        // Recreate the unexpanded view over the same conservative provenance,
+        // as a recursive compact-list tail would provide.
+        compact._args = null;
+        assertEqual(unify(variable('Unrelated'), compact, env), true,
+          'an unrelated variable unifies with the compact list');
+        assertEqual(compact._args, null,
+          'the occurs check proves nonoccurrence without expanding scalar-bound cells');
+
+        const nonGroundCompact = compactVariableList(2n, '__nonGroundCompact');
+        const nonGroundCell = nonGroundCompact.args[0];
+        const cyclicEnv = new Env();
+        assertEqual(unify(nonGroundCell, variable('Intermediate'), cyclicEnv), true,
+          'a second compact cell aliases a clause-head variable');
+        assertEqual(unify(variable('Intermediate'), compound('f', [variable('Cycle')]), cyclicEnv), true,
+          'the aliased cell receives a non-ground value');
+        assertEqual(unify(variable('Cycle'), nonGroundCompact, cyclicEnv), false,
+          'non-ground compact bindings still receive the complete finite-tree occurs check');
       },
     },
     {

package/the-art-of-eyeprolog.md

@@ -2017,11 +2017,12 @@ answer(X) :- host_status(service, X).
 ```
 
 Only mark a built-in deterministic when it can produce at most one environment
-for a call. An unmarked resumable handler is treated as an effect-free relation:
-the solver may buffer one answer to determine its exact pending state. A
-stateful or meta-control handler must instead return an iterator with a
-`hasPendingAlternatives()` method, updated before each yield, so the solver can
-remain demand-driven without advancing it speculatively. A mode-sensitive
+for a call. An unmarked suspended iterator is conservatively an untried
+continuation: the solver never resumes it merely to discover whether a later
+answer will succeed. An iterator that knows its remaining search positions may
+provide `hasPendingAlternatives()`, updated before each yield, to remove its
+resume frame exactly when no position remains. This method reports pending
+search, not the existence of a future successful answer. A mode-sensitive
 extension can additionally provide `ready`,
 `fallbackWhenNotReady`, and `shouldUse` metadata. This metadata affects
 dispatch and safe early filtering, so it belongs to the extension's contract.
@@ -8015,10 +8016,10 @@ decidable by structural equality.
 
 **Choicepoint.** A remaining search alternative that may produce another
 answer if the caller asks the solver to continue. Every resumable engine
-iterator follows the same pending-alternative protocol. Ordinary effect-free
-host relations may buffer one answer to prove exhaustion; stateful and
-meta-control iterators report their state without executing an unrequested
-effect or program branch.
+iterator follows the same pending-alternative protocol. A suspended iterator
+is conservatively a choicepoint unless it reports that no search position
+remains; the engine never executes an unrequested effect or program branch to
+look for a later successful answer.
 
 **Cleanup.** A protected finalization goal installed by normal-mode
 `call_cleanup/2` or `setup_call_cleanup/3`. It runs exactly once when the