eyeprolog 1.3.85 → 1.3.86

package/package.json

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

package/src/iso.js

@@ -137,8 +137,10 @@ export const isoBuiltins = {
     registry.add('number_chars', 2, numberCharsBuiltin, { deterministic: true });
     registry.add('number_codes', 2, numberCodesBuiltin, { deterministic: true });
 
-    registry.add('call', 1, callBuiltin);
-    for (let arity = 2; arity <= 8; arity++) registry.add('call', arity, callClosureBuiltin);
+    registry.add('call', 1, callBuiltin, { expandGoal: expandCallGoal });
+    for (let arity = 2; arity <= 8; arity++) {
+      registry.add('call', arity, callClosureBuiltin, { expandGoal: expandCallClosureGoal });
+    }
     registry.add('catch', 3, catchBuiltin);
     registry.add('throw', 1, throwBuiltin, { deterministic: true });
     registry.add('\\+', 1, negationBuiltin, { deterministic: true });
@@ -166,7 +168,7 @@ 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__countall', 2, countAllBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__freeze', 2, freezeBuiltin, { eyePrologLibrary: true });
     registry.add('dif', 2, difBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('time', 1, timeBuiltin, { eyePrologLibrary: true });
@@ -712,27 +714,43 @@ function assertBuiltin(atStart) {
   };
 }
 
-function* retractBuiltin({ solver, goal, env }) {
+function retractBuiltin(context) {
+  const state = { pending: true };
+  const iterator = retractSolutions(context, state);
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
+}
+
+function* retractSolutions({ solver, goal, env }, state) {
   const parts = clauseParts(goal.args[0], env);
   requireClauseHead(parts.head);
   const group = solver.program.findGroup(parts.head.name, parts.head.arity, parts.head.module ?? goal.module ?? 'user');
   if (isProcessorStaticProcedure(solver, parts.head) || (group && !group.dynamic)) {
     throw new PrologError('permission_error(modify, static_procedure)', procedureIndicator(parts.head));
   }
-  if (!group) return;
+  if (!group) {
+    state.pending = false;
+    return;
+  }
   // ISO logical update view: this call keeps the clauses that were visible
   // when it began. A later retract/1 may erase one of those clauses from the
   // live procedure, but must not invalidate this call's pending alternatives.
-  const candidates = [...group.clauses];
-  for (const clause of candidates) {
+  const matches = [];
+  for (const clause of [...group.clauses]) {
     const copied = freshCopy(compound('$clause', [clause.head, clauseBodyTerm(clause.body)]), new Env());
     const next = env.clone();
     if (!unify(parts.head, copied.args[0], next)) continue;
     if (parts.rule && !unify(parts.body, copied.args[1], next)) continue;
     if (!parts.rule && !(copied.args[1].type === ATOM && copied.args[1].name === 'true')) continue;
+    matches.push({ clause, next });
+  }
+  for (let index = 0; index < matches.length; index++) {
+    const { clause, next } = matches[index];
     solver.program.removeDynamicClause(group, clause);
+    state.pending = index + 1 < matches.length;
     yield next;
   }
+  state.pending = false;
 }
 
 function* retractAllBuiltin({ solver, goal, env }) {
@@ -2413,6 +2431,11 @@ function callable(term, env) {
   validateControlCallable(term, term, env);
   return term;
 }
+
+function withPendingState(iterator, state) {
+  iterator.hasPendingAlternatives = () => state.pending;
+  return iterator;
+}
 function validateControlCallable(term, culprit, env) {
   // Only control constructs need their nested goals validated at meta-call
   // entry. Walk them iteratively and dereference each nested goal lazily so
@@ -2438,9 +2461,14 @@ function validateControlCallable(term, culprit, env) {
     }
   }
 }
-function* callBuiltin({ solver, goal, env }) {
+function expandCallGoal({ goal, env }) {
   const invoked = callable(goal.args[0], env);
   if (invoked.module == null) invoked.module = goal.module ?? 'user';
+  return invoked;
+}
+function* callBuiltin(context) {
+  const { solver, env } = context;
+  const invoked = expandCallGoal(context);
   const child = solver.cloneForInnerGoal();
   try {
     yield* child.solve([invoked], env, 0);
@@ -2448,7 +2476,7 @@ function* callBuiltin({ solver, goal, env }) {
     solver.absorbStatsFrom(child);
   }
 }
-function* callClosureBuiltin({ solver, goal, env }) {
+function expandCallClosureGoal({ goal, env }) {
   const closure = callable(goal.args[0], env);
   const existing = closure.type === COMPOUND ? closure.args : [];
   const extra = goal.args.slice(1);
@@ -2457,6 +2485,11 @@ function* callClosureBuiltin({ solver, goal, env }) {
   }
   const invoked = compound(closure.name, [...existing, ...extra]);
   invoked.module = closure.module ?? goal.module ?? 'user';
+  return invoked;
+}
+function* callClosureBuiltin(context) {
+  const { solver, env } = context;
+  const invoked = expandCallClosureGoal(context);
   const child = solver.cloneForInnerGoal();
   try {
     yield* child.solve([invoked], env, 0);
@@ -2509,7 +2542,12 @@ function writeElapsedTime(solver, startedAt, inferences) {
   );
 }
 
-function* timeBuiltin({ solver, goal, env }) {
+function timeBuiltin(context) {
+  const state = { pending: true };
+  return withPendingState(timeSolutions(context, state), state);
+}
+
+function* timeSolutions({ solver, goal, env }, state) {
   const invoked = callable(goal.args[0], env);
   const child = solver.cloneForInnerGoal();
   let startedAt = monotonicMilliseconds();
@@ -2519,12 +2557,15 @@ function* timeBuiltin({ solver, goal, env }) {
     for (const answerEnv of child.solve([invoked], env, 0)) {
       writeElapsedTime(solver, startedAt, child.inferenceObservation.value - startedInferences);
       yieldedAny = true;
+      state.pending = child.hasPendingAlternatives();
       yield answerEnv;
+      if (!state.pending) return;
       // A resumed time/1 measures only the work required to reach the next
       // answer, so nondeterministic calls get one timing line per solution.
       startedAt = monotonicMilliseconds();
       startedInferences = child.inferenceObservation.value;
     }
+    state.pending = false;
     // A call that fails without producing an answer still reports the work.
     if (!yieldedAny) writeElapsedTime(solver, startedAt, child.inferenceObservation.value - startedInferences);
   } finally {
@@ -2532,10 +2573,18 @@ function* timeBuiltin({ solver, goal, env }) {
   }
 }
 
-function* callNthBuiltin({ solver, goal, env }) {
+function callNthBuiltin(context) {
+  const state = { pending: true };
+  return withPendingState(callNthSolutions(context, state), state);
+}
+
+function* callNthSolutions({ solver, goal, env }, state) {
   const requestedTerm = deref(goal.args[1], env);
   // Zero is the one Nth value that fails before Goal is inspected.
-  if (requestedTerm.type === NUMBER && isDecimalInteger(requestedTerm.name) && BigInt(requestedTerm.name) === 0n) return;
+  if (requestedTerm.type === NUMBER && isDecimalInteger(requestedTerm.name) && BigInt(requestedTerm.name) === 0n) {
+    state.pending = false;
+    return;
+  }
 
   const invoked = callable(goal.args[0], env);
   let requested = null;
@@ -2554,9 +2603,13 @@ function* callNthBuiltin({ solver, goal, env }) {
       nth++;
       if (requested != null && nth < requested) continue;
       const next = answerEnv.clone();
-      if (unify(goal.args[1], numberTerm(nth.toString()), next)) yield next;
-      if (requested != null) return;
+      if (unify(goal.args[1], numberTerm(nth.toString()), next)) {
+        state.pending = requested == null && child.hasPendingAlternatives();
+        yield next;
+        if (requested != null || !state.pending) return;
+      }
     }
+    state.pending = false;
   } finally {
     solver.absorbStatsFrom(child);
   }
@@ -2648,12 +2701,22 @@ function callResidueVarsBuiltin({ solver, goal, env }) {
   return iterator;
 }
 
-function* freezeBuiltin({ solver, goal, env }) {
+function freezeBuiltin(context) {
+  const state = { pending: true };
+  return withPendingState(freezeSolutions(context, state), state);
+}
+
+function* freezeSolutions({ solver, goal, env }, state) {
   const watched = deref(goal.args[0], env);
   if (watched.type !== VAR) {
     const child = solver.cloneForInnerGoal();
     try {
-      yield* child.solve([callable(goal.args[1], env)], env, 0);
+      for (const answerEnv of child.solve([callable(goal.args[1], env)], env, 0)) {
+        state.pending = child.hasPendingAlternatives();
+        yield answerEnv;
+        if (!state.pending) return;
+      }
+      state.pending = false;
     } finally {
       solver.absorbStatsFrom(child);
     }
@@ -2661,10 +2724,16 @@ function* freezeBuiltin({ solver, goal, env }) {
   }
   const next = env.clone();
   next.delay(watched.name, goal.args[1], goal.module ?? 'user');
+  state.pending = false;
   yield next;
 }
 
-function* phraseBuiltin({ solver, goal, env }) {
+function phraseBuiltin(context) {
+  const state = { pending: true };
+  return withPendingState(phraseSolutions(context, state), state);
+}
+
+function* phraseSolutions({ solver, goal, env }, state) {
   const grammarBody0 = deref(goal.args[0], env);
   if (grammarBody0.type === VAR) throw new PrologError('instantiation_error');
   if (grammarBody0.type !== ATOM && grammarBody0.type !== COMPOUND) {
@@ -2721,7 +2790,12 @@ function* phraseBuiltin({ solver, goal, env }) {
     skipListTailTabling: !repeatedInvocation,
   });
   try {
-    yield* child.solve(finish == null ? [expanded] : [expanded, finish], env, 0);
+    for (const answerEnv of child.solve(finish == null ? [expanded] : [expanded, finish], env, 0)) {
+      state.pending = child.hasPendingAlternatives();
+      yield answerEnv;
+      if (!state.pending) return;
+    }
+    state.pending = false;
   } finally {
     solver.absorbStatsFrom(child);
     solver.trimInnerTableScope('phrase');
@@ -2781,7 +2855,12 @@ function prologErrorBall(error) {
   if (hasDefaultGroundErrorShape(error) || termIsGround(term)) return term;
   return freshCopy(term, new Env());
 }
-function* catchBuiltin({ solver, goal, env }) {
+function catchBuiltin(context) {
+  const state = { pending: true };
+  return withPendingState(catchSolutions(context, state), state);
+}
+
+function* catchSolutions({ solver, goal, env }, state) {
   let child = null;
   try {
     // Corrigendum 2 removed catch/3's own callability errors so that errors
@@ -2798,12 +2877,19 @@ function* catchBuiltin({ solver, goal, env }) {
       if (result.done) solver.stats.deterministic_builtin_failures++;
       else {
         solver.stats.deterministic_builtin_successes++;
+        state.pending = false;
         yield result.value;
       }
+      state.pending = false;
       return;
     }
     child = solver.cloneForInnerGoal();
-    yield* child.solve([invoked], env.clone(), 0);
+    for (const answerEnv of child.solve([invoked], env.clone(), 0)) {
+      state.pending = child.hasPendingAlternatives();
+      yield answerEnv;
+      if (!state.pending) return;
+    }
+    state.pending = false;
   } catch (error) {
     const ball = error instanceof ThrownTerm
       ? error.term
@@ -2814,12 +2900,18 @@ function* catchBuiltin({ solver, goal, env }) {
     const recovered = env.clone();
     if (!unify(goal.args[1], ball, recovered)) throw error;
     const recovery = callable(goal.args[2], recovered);
-    if (recovery.type === ATOM && (recovery.name === 'false' || recovery.name === 'fail')) return;
+    if (recovery.type === ATOM && (recovery.name === 'false' || recovery.name === 'fail')) {
+      state.pending = false;
+      return;
+    }
     if (recovery.type === ATOM && recovery.name === 'true') {
+      state.pending = false;
       yield recovered;
       return;
     }
-    yield* solver.solve([recovery], recovered, 0);
+    yield* solveControlBranch(solver, recovery, recovered,
+      (pending) => { state.pending = pending; });
+    state.pending = false;
   } finally {
     if (child != null) solver.absorbStatsFrom(child);
   }
@@ -2917,11 +3009,19 @@ function* disjunctionSolutions({ solver, goal, env }, state) {
     (pending) => { state.pending = pending; });
   state.pending = false;
 }
-function* ifThenBuiltin({ solver, goal, env }) {
+function ifThenBuiltin(context) {
+  const state = { pending: true };
+  return withPendingState(ifThenSolutions(context, state), state);
+}
+
+function* ifThenSolutions({ solver, goal, env }, state) {
   for (const conditionEnv of solver.cloneForInnerGoal(1).solve([callable(goal.args[0], env)], env.clone(), 0)) {
-    yield* solveControlBranch(solver, goal.args[1], conditionEnv);
+    yield* solveControlBranch(solver, goal.args[1], conditionEnv,
+      (pending) => { state.pending = pending; });
+    state.pending = false;
     return;
   }
+  state.pending = false;
 }
 
 export { arithmeticValueTerm, evaluateArithmetic, compareArithmeticValues } from './iso-arithmetic.js';
@@ -2940,6 +3040,7 @@ export class BuiltinRegistry {
       handler,
       deterministic: options.deterministic ?? false,
       deterministicWhen: options.deterministicWhen ?? null,
+      expandGoal: options.expandGoal ?? null,
       ready: options.ready ?? null,
       fallbackWhenNotReady: options.fallbackWhenNotReady ?? false,
       shouldUse: options.shouldUse ?? null,

package/src/scryer-compat.js

@@ -207,9 +207,9 @@ function* termCharsBuiltin({ solver, goal, env }) {
 
 export const scryerCompatibilityBuiltins = {
   register(registry) {
-    registry.add('eyeprolog__bb_get', 2, bbGetBuiltin, { eyePrologLibrary: true });
+    registry.add('eyeprolog__bb_get', 2, bbGetBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__bb_b_put', 2, bbPutBuiltin, { deterministic: true, eyePrologLibrary: true });
-    registry.add('eyeprolog__bb_global_get', 2, bbGlobalGetBuiltin, { eyePrologLibrary: true });
+    registry.add('eyeprolog__bb_global_get', 2, bbGlobalGetBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__bb_global_put', 2, bbGlobalPutBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__char_type', 2, charTypeBuiltin, { eyePrologLibrary: true });
     registry.add('eyeprolog__current_time', 1, currentTimeBuiltin, { deterministic: true, eyePrologLibrary: true });

package/src/solver.js

@@ -614,7 +614,21 @@ export class Solver {
 
         const def = callable ? this.registry.get(goal.name, goal.arity) : null;
         this.active = active;
-        if (def && builtinIsReadyOrAuthoritative(def, this, goal, env)) {
+        const builtinReady = def && builtinIsReadyOrAuthoritative(def, this, goal, env);
+        if (builtinReady && typeof def.expandGoal === 'function') {
+          // Meta-calls execute in this continuation instead of hiding their
+          // search behind a host-generator frame. Their real clause, control,
+          // and builtin frames therefore determine whether another answer is
+          // pending exactly as they do for a direct call. A fresh active marker
+          // keeps cut opaque at the call/N boundary.
+          const expanded = def.expandGoal({ solver: this, goal, env });
+          const invocation = { goal, env };
+          active = [...active, invocation];
+          goals = [expanded, { kind: 'releaseActive' }, ...rest];
+          depth++;
+          continue;
+        }
+        if (builtinReady) {
           const deterministic = def.deterministic ||
             def.deterministicWhen?.({ solver: this, goal, env }) === true;
           const iterator = def.handler({ solver: this, goal, env });
@@ -1414,10 +1428,7 @@ 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.
-  const state = { pending: true };
-  const iterator = bundledBetweenSolutions(solver, goal, env, state);
-  iterator.hasPendingAlternatives = () => state.pending;
-  return iterator;
+  return bundledBetweenSolutions(solver, goal, env);
 }
 
 function requireBetweenInteger(term, env) {
@@ -1429,7 +1440,7 @@ function requireBetweenInteger(term, env) {
   return BigInt(value.name);
 }
 
-function* bundledBetweenSolutions(solver, goal, env, state) {
+function* bundledBetweenSolutions(solver, goal, env) {
   const lower = requireBetweenInteger(goal.args[0], env);
   const upper = requireBetweenInteger(goal.args[1], env);
   const requested = deref(goal.args[2], env);
@@ -1439,23 +1450,15 @@ function* bundledBetweenSolutions(solver, goal, env, state) {
       throw new PrologError('type_error(integer)', requested);
     }
     const value = BigInt(requested.name);
-    if (value >= lower && value <= upper) {
-      state.pending = false;
-      yield env;
-    }
-    state.pending = false;
+    if (value >= lower && value <= upper) yield env;
     return;
   }
 
   for (let value = lower; value <= upper; value++) {
     const next = env.clone();
     solver.stats.unify_calls++;
-    if (unify(goal.args[2], numberTerm(value), next)) {
-      state.pending = value < upper;
-      yield next;
-    }
+    if (unify(goal.args[2], numberTerm(value), next)) yield next;
   }
-  state.pending = false;
 }
 
 function bundledMemberIterator(solver, group, goal, env) {
@@ -1472,50 +1475,18 @@ function bundledMemberIterator(solver, group, goal, env) {
   let cursor = deref(goal.args[1], env);
   while (isCons(cursor)) cursor = deref(cursor.args[1], env);
   if (!isEmptyList(cursor)) return null;
-  const state = { pending: true };
-  const iterator = bundledMemberSolutions(solver, goal, env, state);
-  iterator.hasPendingAlternatives = () => state.pending;
-  return iterator;
+  return bundledMemberSolutions(solver, goal, env);
 }
 
-function* bundledMemberSolutions(solver, goal, env, state) {
+function* bundledMemberSolutions(solver, goal, env) {
   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)) {
-      state.pending = bundledMemberMayMatch(goal.args[0], cursor, env);
-      yield next;
-    }
-  }
-  state.pending = false;
-}
-
-function bundledMemberMayMatch(target, cursor, env) {
-  while (isCons(cursor)) {
-    if (!termsCannotUnify(target, cursor.args[0], env)) return true;
-    cursor = deref(cursor.args[1], env);
-  }
-  return false;
-}
-
-function termsCannotUnify(left, right, env) {
-  const pending = [[left, right]];
-  while (pending.length > 0) {
-    const [leftItem, rightItem] = pending.pop();
-    const actualLeft = derefForLocal(leftItem, env);
-    const actualRight = derefForLocal(rightItem, env);
-    if (actualLeft.type === VAR || actualRight.type === VAR) continue;
-    if (actualLeft.type !== actualRight.type || actualLeft.name !== actualRight.name ||
-        actualLeft.arity !== actualRight.arity) return true;
-    if (actualLeft.type !== COMPOUND) continue;
-    for (let index = 0; index < actualLeft.arity; index++) {
-      pending.push([actualLeft.args[index], actualRight.args[index]]);
-    }
+    if (unify(goal.args[0], item, next)) yield next;
   }
-  return false;
 }
 
 function bundledEllipsisPlan(solver, group, goal, rest, env) {
@@ -1630,13 +1601,7 @@ function bundledLengthIterator(solver, group, goal, env) {
       if (length.type === VAR && cursor.name === length.name) return null;
     }
   }
-  const iterator = bundledLengthSolutions(solver, goal, env);
-  // A supplied length selects at most one list, and a closed supplied list has
-  // exactly one length. Only an open list paired with an output variable can
-  // produce another answer after the first one.
-  const hasOpenTail = cursor.type === VAR;
-  iterator.hasPendingAlternatives = () => length.type === VAR && hasOpenTail;
-  return iterator;
+  return bundledLengthSolutions(solver, goal, env);
 }
 
 function* bundledLengthSolutions(solver, goal, env) {
@@ -2210,13 +2175,7 @@ function pushStreamingScalarFactRun(stack, solver, runGoals, groups, rest, env,
   const iterator = scalarFactRunSolutions(solver, runGoals, groups, env, depth, active);
   const first = iterator.next();
   if (first.done) return;
-  stack.push({
-    kind: 'resumeBuiltin',
-    iterator,
-    goals: rest,
-    depth: depth + runGoals.length,
-    active,
-  });
+  pushResumeBuiltinFrame(stack, iterator, rest, depth + runGoals.length, active);
   stack.push({
     kind: 'goals',
     goals: rest,
@@ -2854,10 +2813,64 @@ function builtinIsReadyOrAuthoritative(def, solver, goal, env) {
 
 function iteratorMayHavePendingAlternatives(iterator) {
   const predicate = iterator?.hasPendingAlternatives;
-  return typeof predicate !== 'function' || predicate.call(iterator) !== false;
+  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);
 }
 
 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/test/run-regression.mjs

@@ -1999,11 +1999,13 @@ c4 ?- call((!;1)).
       },
     },
     {
-      name: 'predicates discard exhausted choicepoints before the REPL observes them (issue #74)',
+      name: 'direct and meta-called predicates discard exhausted choicepoints (issue #74 comment 5427164365)',
       run: () => {
         const result = runCli([], {
           input:
             'X=1;X=2.\n;\n' +
+            'call(X=1).\n' +
+            'call(=(X),1).\n' +
             'setof(X,true,Xs).\n' +
             'findall(t,false,Xs).\n' +
             'use_module(library(lists)).\n' +
@@ -2015,6 +2017,8 @@ c4 ?- call((!;1)).
         assertEqual(result.stdout,
           '?-    X = 1\n' +
           ';  X = 2.\n' +
+          '?-    X = 1.\n' +
+          '?-    X = 1.\n' +
           '?-    Xs = [_A].\n' +
           '?-    Xs = [].\n' +
           '?-    true.\n' +
@@ -2044,6 +2048,16 @@ c4 ?- call((!;1)).
         };
 
         finalAnswerHasNoFrames('', 'X=1;X=2', 2);
+        finalAnswerHasNoFrames('', 'call(X=1)', 1);
+        finalAnswerHasNoFrames('', 'call(=(X),1)', 1);
+        finalAnswerHasNoFrames('', 'atom_concat(a,X,ab)', 1);
+        finalAnswerHasNoFrames('', 'sub_atom(ab,0,2,0,S)', 1);
+        finalAnswerHasNoFrames('', 'current_prolog_flag(double_quotes,_Value)', 1);
+        finalAnswerHasNoFrames('', "current_op(700,xfx,'=')", 1);
+        finalAnswerHasNoFrames(':- dynamic(p/1).\np(a).', 'clause(p(X),true)', 1);
+        finalAnswerHasNoFrames(':- dynamic(p/1).\np(a).', 'retract(p(X))', 1);
+        finalAnswerHasNoFrames('', 'catch(true,_,fail)', 1);
+        finalAnswerHasNoFrames('', 'phrase([],[])', 1);
         finalAnswerHasNoFrames('', 'setof(X,true,Xs)', 1);
         finalAnswerHasNoFrames('', 'findall(t,false,Xs)', 1);
         finalAnswerHasNoFrames(':- use_module(library(lists)).', 'member(a,"ba")', 1, 'lists');
@@ -2056,6 +2070,38 @@ c4 ?- call((!;1)).
         assertEqual(groupedSolutions.next().done, false, 'first grouped setof/3 answer');
         assertEqual(grouped.hasPendingAlternatives(), true, 'genuine grouped setof/3 choicepoint');
         groupedSolutions.return();
+
+        const called = new Solver(Program.parse(''), { registry: getEyePrologRegistry() });
+        const calledSolutions = called.solve([parseGoalText('call((X=1;X=2))')], new Env(), 0);
+        assertEqual(calledSolutions.next().done, false, 'called disjunction first answer');
+        assertEqual(called.hasPendingAlternatives(), true, 'called disjunction retains its real alternative');
+        assertEqual(calledSolutions.next().done, false, 'called disjunction second answer');
+        assertEqual(called.hasPendingAlternatives(), false, 'called disjunction removes its exhausted alternative');
+        calledSolutions.return();
+
+        const customRegistry = new BuiltinRegistry();
+        customRegistry.add('single', 1, function* ({ goal, env }) {
+          const next = env.clone();
+          if (unify(goal.args[0], atom('only'), next)) yield next;
+        });
+        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');
+        customSolutions.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');
+        assertEqual(dynamicSolver.hasPendingAlternatives(), true,
+          'stateful protected iterator retains its real second retraction');
+        dynamicSolutions.return();
+        assertEqual(dynamicProgram.findGroup('p', 1).clauses.length, 1,
+          'closing stateful iterator leaves the unrequested clause intact');
       },
     },
     {
@@ -5373,21 +5419,13 @@ answer(ok) :-
           import { Program, Solver, Env, deref, variable, parseGoalText, getEyePrologRegistry } from ${JSON.stringify(engineUrl)};
           import { usedHeapSize } from ${JSON.stringify(platformUrl)};
           const program = Program.parse(${JSON.stringify(programText)}, { sourceMetadata: false });
-          // Exercise EyeProlog's recovery window at a stable threshold instead
-          // of relying on V8's version-dependent old-generation promotion.
-          const solver = new Solver(program, {
-            registry: getEyePrologRegistry(),
-            maxMemoryBytes: usedHeapSize() + 20 * 1024 * 1024,
-          });
-          const execute = (text) => {
-            const goal = parseGoalText(text, { operatorDefinitions: [...program.operators.values()] });
-            return [...solver.solve([goal], new Env(), 0)];
-          };
+          const registry = getEyePrologRegistry();
           const reported = parseGoalText(${JSON.stringify(reportedGoal)}, {
             operatorDefinitions: [...program.operators.values()],
           });
+          const reportedSolver = new Solver(program, { registry, maxMemoryBytes: Infinity });
           let reportedAnswers = 0;
-          for (const answer of solver.solve([reported], new Env(), 0)) {
+          for (const answer of reportedSolver.solve([reported], new Env(), 0)) {
             reportedAnswers++;
             if (reportedAnswers !== 14) continue;
             if (deref(variable('I'), answer).name !== '13' || deref(variable('N'), answer).name !== '8192') {
@@ -5396,6 +5434,18 @@ answer(ok) :-
             break;
           }
           if (reportedAnswers !== 14) throw new Error('reported query produced too few answers');
+
+          // Exercise EyeProlog's recovery window at a stable threshold relative
+          // to the heap after the preliminary reproduction. Keeping that probe
+          // unlimited prevents host GC timing from exhausting the test early.
+          const solver = new Solver(program, {
+            registry,
+            maxMemoryBytes: usedHeapSize() + 8 * 1024 * 1024,
+          });
+          const execute = (text) => {
+            const goal = parseGoalText(text, { operatorDefinitions: [...program.operators.values()] });
+            return [...solver.solve([goal], new Env(), 0)];
+          };
           let caught = null;
           try { execute('length(L,32768),l(L)'); } catch (error) { caught = error; }
           if (caught?.formal !== 'resource_error(memory)') throw caught ?? new Error('no resource error');

package/the-art-of-eyeprolog.md

@@ -2017,7 +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. A mode-sensitive extension can additionally provide `ready`,
+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
+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.
 
@@ -5136,8 +5141,12 @@ at a named boundary.
 ## 34. Control, exceptions, and grouped solutions
 
 The control predicates accept goals as arguments. `call/1` invokes a callable
-term, `once/1` keeps its first solution, and `!/0` commits within the clause
-that contains it. If-then-else commits to the first successful condition:
+term, and `call/2-8` appends arguments to a callable closure. The expanded goal
+runs in the current search continuation, so a direct goal and its meta-called
+form expose the same remaining alternatives; the meta-call still establishes
+its own cut boundary. `once/1` keeps its first solution, and `!/0` commits
+within the clause that contains it. If-then-else commits to the first successful
+condition:
 
 <figure>
   <img src="book-assets/iso-control-board.svg" alt="A goal passes through choice and exception recovery before finite solutions enter findall, bagof, and setof collectors.">
@@ -6831,11 +6840,15 @@ When another answer exists in an interactive terminal, press `;`, Space, or
 enumeration, `a` enumerates all remaining answers, and `f` advances to the
 next five-answer boundary (5, 10, 15, ... displayed leaf answers), regardless
 of how many answers were stepped through individually beforehand. `h` displays
-the answer-control help. Enumeration is demand-driven: after an answer is
-found, the top level does not pull a successor merely to discover whether the
-current answer is the last one. Search for a later answer, including any side
-effects reached on that path, starts only after an answer-control command asks
-to continue. Stopping enumeration closes any active `call_cleanup/2` or
+the answer-control help. Enumeration of goal continuations is demand-driven:
+after an answer is found, the top level does not execute a later program branch
+or side effect merely to discover whether the current answer is the last one.
+The solver's uniform choicepoint protocol uses explicit clause and control
+frames, permits a one-answer buffer only for effect-free host relations, and
+requires stateful or meta-control iterators to report their pending state
+directly. Search that can perform an effect starts only after an answer-control
+command asks to continue. Stopping enumeration closes any active
+`call_cleanup/2` or
 `setup_call_cleanup/3` protection exactly once; detecting that a choicepoint
 remains does not execute that next branch. If an unresolved alternative
 ultimately has no solution, asking for it may therefore finish with `false.`. In scripted non-TTY input, a new
@@ -7995,8 +8008,11 @@ decidable by structural equality.
 **Clause.** A fact or rule terminated by a period.
 
 **Choicepoint.** A remaining search alternative that may produce another
-answer if the caller asks the solver to continue. EyeProlog's top level reports
-choicepoint availability without speculatively executing the next alternative.
+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.
 
 **Cleanup.** A protected finalization goal installed by normal-mode
 `call_cleanup/2` or `setup_call_cleanup/3`. It runs exactly once when the