eyeprolog 1.3.85 → 1.3.87

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.3.85",
+  "version": "1.3.87",
   "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 }) {
@@ -1738,15 +1756,6 @@ function writeOptionBoolean(value, env, option) {
   return value.name === 'true';
 }
 
-function writeOptionSpacing(value, env, option) {
-  value = deref(value, env);
-  if (value.type === VAR) throw new PrologError('instantiation_error');
-  if (value.type !== ATOM || !['minimal', 'standard'].includes(value.name)) {
-    throw new PrologError('domain_error(write_option)', copyResolved(option, env));
-  }
-  return value.name;
-}
-
 function writeVariableNames(value, env, option) {
   value = deref(value, env);
   if (value.type === VAR) throw new PrologError('instantiation_error');
@@ -1788,7 +1797,7 @@ function termWriteOptionsFromItems(options, env, mode = 'write_term', solver = n
     else if (option.name === 'double_quotes' && !solver?.isoStrict) {
       result.doubleQuotes = writeOptionBoolean(option.args[0], env, option);
     } else if (option.name === 'spacing' && !solver?.isoStrict) {
-      result.minimalOperatorSpacing = writeOptionSpacing(option.args[0], env, option) === 'minimal';
+      result.minimalOperatorSpacing = !writeOptionBoolean(option.args[0], env, option);
     } else {
       throw new PrologError('domain_error(write_option)', copyResolved(option, env));
     }
@@ -2413,6 +2422,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 +2452,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 +2467,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 +2476,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 +2533,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 +2548,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 +2564,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 +2594,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 +2692,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 +2715,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 +2781,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 +2846,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 +2868,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 +2891,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 +3000,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 +3031,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/conformance/ISO-IMPLEMENTATION-DEFINED.md

@@ -124,7 +124,7 @@ families; `--iso-strict` is intended to remove their Part 1 interpretation.
 | 5.5.9 Built-in predicates | EyeProlog libraries, CLP(Z), statistics, Part 3 `phrase/2-3`, and interop autoloaded predicates | Strict registry contains only the Part 1 + Corrigenda core registry. |
 | 5.5.10 Evaluable functors | Normal mode additionally accepts the EyeProlog evaluable atom `e`; the remaining arithmetic functors accepted by strict mode are the Part 1 + Corrigenda set. | Strict mode rejects `e/0` as non-evaluable and retains the Corrigendum arithmetic additions. **covered** — strict extension-boundary regression plus `src/iso-arithmetic.js`. |
 | 5.5.11 Reserved atoms | None | None. |
-| Cor.3 5.5.12 Options | Extra library/host options may exist outside core option lists | Normal mode additionally accepts the EyeProlog `write_term/2-3` options `double_quotes(true|false)` and `spacing(minimal|standard)`. `minimal` emits only lexically required separators; `standard` adds conventional layout around operators. Strict core excludes these implementation-specific extensions and accepts only the Part 1 plus Corrigendum 3 write-option surface; unknown extension options raise `domain_error(write_option,...)`. |
+| Cor.3 5.5.12 Options | Extra library/host options may exist outside core option lists | Normal mode additionally accepts the EyeProlog `write_term/2-3` options `double_quotes(true|false)` and `spacing(true|false)`. `spacing(false)` emits only lexically required separators; `spacing(true)` adds conventional layout around operators. Strict core excludes these implementation-specific extensions and accepts only the Part 1 plus Corrigendum 3 write-option surface; unknown extension options raise `domain_error(write_option,...)`. |
 
 Normal mode provides documented module and DCG compatibility profiles whose
 features overlap standardized Part 2 and Part 3 facilities. They are extensions

package/test/run-iso-strict.mjs

@@ -285,13 +285,13 @@ export function runIsoStrict(reporter = new TestReporter()) {
 
     const strictSpacingError = capture(() => run('', {
       isoStrict: true,
-      goal: 'write_term(1+1,[spacing(minimal)])',
+      goal: 'write_term(1+1,[spacing(false)])',
     }));
     equal(strictSpacingError.formal, 'domain_error(write_option)', 'strict spacing extension rejection');
 
     const normal = run('', { goal: 'write_term("ab",[double_quotes(true)])' });
     includes(normal.stdout, '"ab"', 'normal-profile extension remains available');
-    includes(run('', { goal: 'write_term(1+1,[spacing(standard)])' }).stdout,
+    includes(run('', { goal: 'write_term(1+1,[spacing(true)])' }).stdout,
       '1 + 1', 'normal-profile spacing extension remains available');
   });
 

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');
       },
     },
     {
@@ -4032,8 +4078,8 @@ child.stdin.write(\`consult(${consultedAtom}).\\n\`);
       run: () => {
         const source = [
           'emit :-',
-          '  write_term(1+1, [spacing(minimal)]), put_char(\'|\'),',
-          '  write_term(1+1, [spacing(standard)]).',
+          '  write_term(1+1, [spacing(false)]), put_char(\'|\'),',
+          '  write_term(1+1, [spacing(true)]).',
           '',
         ].join('\n');
         assertEqual(run(source, { goal: 'emit' }).stdout, '1+1|1 + 1emit.\n',
@@ -4058,7 +4104,7 @@ child.stdin.write(\`consult(${consultedAtom}).\\n\`);
         }
         assertEqual(variableError?.formal, 'instantiation_error', 'variable spacing value');
 
-        for (const value of ['true', 'false', '1', '0']) {
+        for (const value of ['minimal', 'standard', '1', '0']) {
           let domainError = null;
           try {
             run('', { goal: `write_term(1+1,[spacing(${value})])` });
@@ -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.">
@@ -5430,11 +5439,11 @@ still retained where adjacent graphic tokens would otherwise merge, as in
 `double_quotes(true|false)`: `true` lets eligible character/code lists use the
 current `double_quotes` representation, while strict ISO mode rejects this
 implementation-specific write option. Normal mode also accepts the
-implementation-specific `spacing(minimal|standard)` option: `minimal` emits
-only separators required to avoid lexical ambiguity, while `standard` adds
+implementation-specific boolean `spacing(true|false)` option: `false` emits
+only separators required to avoid lexical ambiguity, while `true` adds
 conventional layout around operators. For example,
-`write_term(1+1,[spacing(minimal)])` emits `1+1` and
-`write_term(1+1,[spacing(standard)])` emits `1 + 1`. The REPL always follows
+`write_term(1+1,[spacing(false)])` emits `1+1` and
+`write_term(1+1,[spacing(true)])` emits `1 + 1`. The REPL always follows
 the minimal-separator rule, so `X=1*1` is displayed as `X = 1*1`, while a
 separator is retained in `X = a+ -b` because the adjacent graphic tokens would
 otherwise merge. Strict ISO mode rejects both extension options.
@@ -6130,7 +6139,7 @@ the beginning. A peek does not mark the stream as past-end.
 | `write(+Term)`, `write(+Stream,+Term)` | Writes readable operator notation without quoting atoms merely because quoting would be required for reparsing. Number variables are enabled. |
 | `writeq(+Term)`, `writeq(+Stream,+Term)` | Like `write`, but quotes atoms when required for unambiguous input syntax. |
 | `write_canonical(+Term)`, `write_canonical(+Stream,+Term)` | Writes quoted canonical functor notation while ignoring operators and without interpreting *$VAR/1*. |
-| `write_term(+Term,+Options)`, `write_term(+Stream,+Term,+Options)` | Writes with *quoted(true or false)*, *ignore_ops(true or false)*, *numbervars(true or false)*, and *variable_names([Name=Variable,...])*. Normal mode also supports *double_quotes(true or false)* and *spacing(minimal or standard)*. |
+| `write_term(+Term,+Options)`, `write_term(+Stream,+Term,+Options)` | Writes with *quoted(true or false)*, *ignore_ops(true or false)*, *numbervars(true or false)*, and *variable_names([Name=Variable,...])*. Normal mode also supports *double_quotes(true or false)* and *spacing(true or false)*. |
 
 Term input uses the program's current operator table and the same ISO quoted-character
 syntax as source text, including backslash-terminated octal and hexadecimal
@@ -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
@@ -7783,7 +7796,7 @@ Notable implementation boundaries are:
 - `write_term/2-3` implements the Part 1 plus Corrigendum 3 `quoted/1`,
   `ignore_ops/1`, `numbervars/1`, and `variable_names/1` option surface,
   including option validation and traversal rules; normal mode also offers
-  `double_quotes(true|false)` and `spacing(minimal|standard)` as explicitly
+  `double_quotes(true|false)` and `spacing(true|false)` as explicitly
   implementation-specific extensions, which strict mode rejects;
 - unification consistently performs an occurs check, rejecting rational-tree
   bindings accepted as extensions by some systems.
@@ -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