eyeprolog 1.3.34 → 1.3.36

package/index.d.ts

@@ -77,8 +77,9 @@ export interface EyePrologQuad {
 
 export interface EyePrologQuadResult {
   ok: boolean;
-  kind?: 'failed' | 'malformed' | 'bad_identifier' | 'unsupported';
+  kind?: 'failed' | 'malformed' | 'bad_identifier' | 'unsupported' | 'undecided';
   expected?: EyePrologTerm;
+  reason?: string;
 }
 
 export interface EyePrologQuadRunResult {
@@ -86,9 +87,20 @@ export interface EyePrologQuadRunResult {
   total: number;
   passed: number;
   failed: number;
+  undecided: number;
   results: EyePrologQuadResult[];
 }
 
+export interface EyePrologQuadRunOptions extends EyePrologRunOptions {
+  initialize?: boolean;
+  /** Search budget for ordinary quad descriptions before reporting an undecided result. */
+  quadMaxInferences?: number;
+  /** Depth bound used when a quad explicitly expects loops. */
+  loopMaxDepth?: number;
+  /** Inference bound used when a quad explicitly expects loops. */
+  loopMaxInferences?: number;
+}
+
 export interface EyePrologPredicateGroup {
   name: string;
   arity: number;
@@ -271,7 +283,7 @@ export class HaltSignal extends Error {
   constructor(code?: number);
 }
 export function run(source: string | Program, options?: EyePrologRunOptions): EyePrologRunResult;
-export function runQuads(source: string | Program, options?: EyePrologRunOptions & { initialize?: boolean }): EyePrologQuadRunResult;
+export function runQuads(source: string | Program, options?: EyePrologQuadRunOptions): EyePrologQuadRunResult;
 export function whyProof(program: Program, goal: EyePrologTerm, options?: EyePrologRunOptions): { ok: boolean; text: string };
 export function whyNoProof(goal: EyePrologTerm): string;
 export function explainProof(program: Program, goal: EyePrologTerm, options?: EyePrologRunOptions): { ok: boolean; text: string };

package/package.json

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

package/src/cli.js

@@ -168,6 +168,7 @@ export async function main(argv) {
     const result = engine.runQuads(program, { initialize: options.goals.length === 0 });
     process.stdout.write(result.stdout);
     if (result.failed > 0) process.exitCode = 1;
+    else if (result.undecided > 0) process.exitCode = 2;
   }
 }
 

package/src/quads.js

@@ -3,7 +3,7 @@
 // used by Trealla and the ISO Prolog working examples linked from issue #1.
 import {
   ATOM, COMPOUND, VAR, Env, atom, compound, copyResolved, deref,
-  flattenConjunction, properListItems, termIsGround,
+  flattenConjunction, listFromItems, properListItems, termIsGround,
   unify, variable,
 } from './term.js';
 import { parseGoalText } from './parser.js';
@@ -12,13 +12,16 @@ import { Solver } from './solver.js';
 import { getEyePrologRegistry } from './standard-library.js';
 import { formatTermForWrite } from './write.js';
 
+const DEFAULT_QUAD_MAX_INFERENCES = 100000;
+const DEFAULT_LOOP_MAX_INFERENCES = 10000;
+
 export function runQuads(source, options = {}) {
   const program = source instanceof Program
     ? source
     : Program.parse(source, { ...options, sourceMetadata: true });
   const quads = program.quads ?? [];
   if (quads.length === 0) {
-    return { stdout: 'quads: nothing to run.\n', total: 0, passed: 0, failed: 0, results: [] };
+    return { stdout: 'quads: nothing to run.\n', total: 0, passed: 0, failed: 0, undecided: 0, results: [] };
   }
 
   if (options.initialize !== false) {
@@ -43,9 +46,11 @@ export function runQuads(source, options = {}) {
     }
   }
   const passed = results.filter((result) => result.ok).length;
-  const failed = results.length - passed;
-  lines.push(`quads: ${results.length} run, ${passed} passed, ${failed} failed.\n`);
-  return { stdout: lines.join(''), total: results.length, passed, failed, results };
+  const undecided = results.filter((result) => result.kind === 'undecided').length;
+  const failed = results.length - passed - undecided;
+  const undecidedSummary = undecided === 0 ? '' : `, ${undecided} undecided`;
+  lines.push(`quads: ${results.length} run, ${passed} passed, ${failed} failed${undecidedSummary}.\n`);
+  return { stdout: lines.join(''), total: results.length, passed, failed, undecided, results };
 }
 
 function checkQuadDescription(program, quad, description, options) {
@@ -66,12 +71,14 @@ function checkDescription(program, quad, description, options) {
     if (malformed != null) return { ok: false, kind: 'malformed', expected: malformed };
   }
   let unsupported = null;
+  let undecided = null;
   for (const alternative of ordered) {
     const checked = checkAlternative(program, quad, alternative, options);
     if (checked.ok) return checked;
     if (checked.kind === 'unsupported') unsupported ??= checked;
+    if (checked.kind === 'undecided') undecided ??= checked;
   }
-  return unsupported ?? { ok: false, kind: 'failed', expected: description };
+  return unsupported ?? undecided ?? { ok: false, kind: 'failed', expected: description };
 }
 
 function checkAlternative(program, quad, alternative, options) {
@@ -98,15 +105,21 @@ function checkAlternative(program, quad, alternative, options) {
 
   if (inputSpecs.length > 0) {
     const leaf = leaves[0];
-    const matches = actual.inputPosition === input.length && matchLeaf(quad.query, leaf, actual, 0);
+    const matches = actual.inputPosition === input.length && matchLeaf(program, quad.query, leaf, actual, 0);
+    if (actual.undecided && !matches) return undecidedResult(actual, alternative);
     return { ok: leaf.unexpected ? !matches : matches };
   }
 
   let position = 0;
   for (const leaf of leaves) {
     if (leaf.more && !leaf.hasExpectation) return { ok: true };
-    const matches = matchLeaf(quad.query, leaf, actual, position);
-    if (leaf.unexpected ? matches : !matches) return { ok: false };
+    const matches = matchLeaf(program, quad.query, leaf, actual, position);
+    if (leaf.unexpected ? matches : !matches) {
+      if (actual.undecided && leafNeedsMoreSearch(leaf, actual, position)) {
+        return undecidedResult(actual, alternative);
+      }
+      return { ok: false };
+    }
     // An unexpected error description is a negative assertion about that
     // particular error pattern.  A different exception may be present and is
     // checked by other descriptions; do not make the final 'no error' test
@@ -114,12 +127,16 @@ function checkAlternative(program, quad, alternative, options) {
     if (leaf.unexpected && leaf.error != null) return { ok: true };
     if (leaf.more) return { ok: true };
     if (!leaf.unexpected && (leaf.false || leaf.error != null)) {
+      if (actual.undecided) return undecidedResult(actual, alternative);
       return { ok: position === leaves.length - 1 };
     }
     position++;
   }
 
-  const ended = position >= actual.solutions.length && actual.error == null;
+  const ended = position >= actual.solutions.length && actual.error == null && !actual.undecided;
+  if (!ended && actual.undecided && position >= actual.solutions.length && actual.error == null) {
+    return undecidedResult(actual, alternative);
+  }
   return { ok: ended };
 }
 
@@ -184,9 +201,8 @@ function describeLeaf(term) {
       continue;
     }
     if (item.type === COMPOUND && item.name === 'outputs' && item.arity === 1) {
-      const text = characterText(item.args[0]);
-      if (text == null || leaf.output != null) leaf.malformed ??= item;
-      else leaf.output = text;
+      if (leaf.output != null) leaf.malformed ??= item;
+      else leaf.output = item.args[0];
       continue;
     }
     if (item.type === COMPOUND && item.name === 'peeks' && item.arity === 1) {
@@ -208,7 +224,9 @@ function executeQuery(program, query, input, maxSolutions, options) {
     ...options,
     registry: options.registry ?? getEyePrologRegistry(),
     maxDepth: options.detectLoops ? (options.loopMaxDepth ?? 1000) : options.maxDepth,
-    maxInferences: options.detectLoops ? (options.loopMaxInferences ?? 10000) : options.maxInferences,
+    maxInferences: options.detectLoops
+      ? (options.loopMaxInferences ?? DEFAULT_LOOP_MAX_INFERENCES)
+      : (options.quadMaxInferences ?? options.maxInferences ?? DEFAULT_QUAD_MAX_INFERENCES),
     // The solver's counter also observes completed nested searches (for
     // example each arm of a DCG disjunction).  Bound the public iterator here
     // instead of letting those internal completions consume the quad's answer
@@ -242,29 +260,37 @@ function executeQuery(program, query, input, maxSolutions, options) {
     error = { term: errorTerm(caught), output: pendingOutput };
   }
   const inputPosition = solver.io.resolve('user_input')?.position ?? 0;
+  const bounded = solver.depthLimitExceeded || solver.inferenceLimitExceeded;
+  const undecided = !options.detectLoops && (solver.recursionCycleDetected || bounded);
   return {
     solutions,
     error,
     tailOutput,
     inputPosition,
-    // Accept direct structural evidence from EyeProlog's recursion guard as
-    // well as bounded-search evidence. A detected active-variant cycle is
-    // stronger evidence than merely reaching a timeout/inference ceiling.
-    loops: solver.recursionCycleDetected || solver.depthLimitExceeded || solver.inferenceLimitExceeded,
+    // A loops expectation explicitly asks for bounded nontermination evidence.
+    // Other descriptions treat the same exhausted search budget as undecided:
+    // a timeout cannot establish finite failure or an exact answer sequence.
+    loops: options.detectLoops && (solver.recursionCycleDetected || bounded),
+    undecided,
+    undecidedReason: solver.inferenceLimitExceeded ? 'inference limit reached'
+      : solver.depthLimitExceeded ? 'depth limit reached'
+        : solver.recursionCycleDetected ? 'recursion cycle encountered'
+          : null,
   };
 }
 
-function matchLeaf(query, leaf, actual, position) {
+function matchLeaf(program, query, leaf, actual, position) {
   if (leaf.loops) return actual.loops;
   if (leaf.false) {
-    return position >= actual.solutions.length && actual.error == null && outputMatches(leaf.output, actual.tailOutput);
+    return position >= actual.solutions.length && actual.error == null && !actual.undecided &&
+      outputMatches(program, leaf.output, actual.tailOutput);
   }
   if (leaf.error != null) {
     return position === actual.solutions.length && actual.error != null &&
-      errorMatches(query, leaf.error, actual.error.term) && outputMatches(leaf.output, actual.error.output);
+      errorMatches(query, leaf.error, actual.error.term) && outputMatches(program, leaf.output, actual.error.output);
   }
   const solution = actual.solutions[position];
-  if (!solution || !outputMatches(leaf.output, solution.output)) return false;
+  if (!solution || !outputMatches(program, leaf.output, solution.output)) return false;
   return substitutionMatches(query, leaf.bindings, solution.env);
 }
 
@@ -391,10 +417,162 @@ function characterText(term) {
   return text;
 }
 
-function outputMatches(expected, actual) {
-  return expected == null || expected === actual;
+function outputMatches(program, expected, actual) {
+  if (expected == null) return true;
+
+  // Preserve the original exact character-list/code-list shorthand first.
+  const exactText = characterText(expected);
+  if (exactText != null && exactText === actual) return true;
+
+  // Trealla's portable quad convention also permits the captured character
+  // sequence to unify directly with outputs/1's argument before trying it as a
+  // DCG body. This makes outputs(Cs) and partially instantiated character lists
+  // useful without weakening the DCG interpretation.
+  const actualList = listFromItems(Array.from(actual, (character) => atom(character)));
+  if (unify(expected, actualList, new Env())) return true;
+
+  return outputDcgMatches(program, expected, actual);
+}
+
+function outputDcgMatches(program, body, actual) {
+  const characters = Array.from(actual);
+  for (const state of matchOutputDcg(program, body, characters, 0, new Env())) {
+    if (state.position === characters.length) return true;
+  }
+  return false;
 }
 
+function* matchOutputDcg(program, body, characters, position, env) {
+  body = deref(body, env);
+
+  if (body.type === ATOM && (body.name === '...' || body.name === 'ad_infinitum')) {
+    for (let next = position; next <= characters.length; next++) {
+      yield { position: next, env: env.clone() };
+    }
+    return;
+  }
+
+  if (body.type === ATOM && body.name === '[]') {
+    yield { position, env };
+    return;
+  }
+
+  if (body.type === COMPOUND && body.name === '.' && body.arity === 2) {
+    const items = properListItems(body, env);
+    if (items == null) return;
+    let states = [{ position, env }];
+    for (const item of items) {
+      const nextStates = [];
+      for (const state of states) {
+        if (state.position >= characters.length) continue;
+        const expected = outputTerminalTerm(item, state.env);
+        if (expected == null) continue;
+        const nextEnv = state.env.clone();
+        if (unify(expected, atom(characters[state.position]), nextEnv)) {
+          nextStates.push({ position: state.position + 1, env: nextEnv });
+        }
+      }
+      states = nextStates;
+      if (states.length === 0) return;
+    }
+    yield* states;
+    return;
+  }
+
+  if (body.type === COMPOUND && body.name === ',' && body.arity === 2) {
+    for (const left of matchOutputDcg(program, body.args[0], characters, position, env)) {
+      yield* matchOutputDcg(program, body.args[1], characters, left.position, left.env);
+    }
+    return;
+  }
+
+  if (body.type === COMPOUND && [';', '|'].includes(body.name) && body.arity === 2) {
+    yield* matchOutputDcg(program, body.args[0], characters, position, env.clone());
+    yield* matchOutputDcg(program, body.args[1], characters, position, env.clone());
+    return;
+  }
+
+  if ((body.type === ATOM && ['!', '{}'].includes(body.name)) ||
+      (body.type === COMPOUND && body.name === '{}' && body.arity === 1 &&
+       body.args[0].type === ATOM && body.args[0].name === 'true')) {
+    yield { position, env };
+    return;
+  }
+
+  if (body.type === COMPOUND && body.name === '{}' && body.arity === 1 &&
+      body.args[0].type === ATOM && body.args[0].name === 'fail') return;
+
+  // A nonterminal in an outputs/1 DCG body is interpreted against the same
+  // program as the query. Ask its expanded /2 relation how much of the
+  // remaining captured character list it consumes. This covers user-defined
+  // DCGs while the structural cases above handle terminals and ... without
+  // requiring a harness-only library import.
+  if (body.type === ATOM || body.type === COMPOUND) {
+    yield* matchOutputNonterminal(program, body, characters, position, env);
+  }
+}
+
+let outputDcgFresh = 0;
+function* matchOutputNonterminal(program, body, characters, position, env) {
+  const input = listFromItems(characters.slice(position).map((character) => atom(character)));
+  const output = variable(`\u0000quad-output:${++outputDcgFresh}`);
+  let goal;
+  if (body.type === ATOM) goal = compound(body.name, [input, output]);
+  else goal = compound(body.name, [...body.args, input, output]);
+  goal.module = body.module ?? 'user';
+
+  const solver = new Solver(program, {
+    registry: getEyePrologRegistry(),
+    maxInferences: DEFAULT_QUAD_MAX_INFERENCES,
+    solutionLimit: characters.length + 2,
+    ioOptions: { write: () => {} },
+  });
+  try {
+    for (const solutionEnv of solver.solve([goal], env.clone(), 0)) {
+      const tail = characterText(deref(output, solutionEnv));
+      if (tail == null) continue;
+      const remaining = characters.slice(position).join('');
+      if (!remaining.endsWith(tail)) continue;
+      yield {
+        position: characters.length - Array.from(tail).length,
+        env: solutionEnv,
+      };
+    }
+  } catch (_) {
+    // A DCG body that raises while being used as an output matcher simply does
+    // not match, mirroring catch(phrase(Expected, Cs), _, fail).
+  }
+}
+
+function outputTerminalTerm(term, env) {
+  term = deref(term, env);
+  if (term.type === 'number' && /^\d+$/.test(term.name)) {
+    const code = Number(term.name);
+    if (!Number.isSafeInteger(code) || code < 0 || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) {
+      return null;
+    }
+    return atom(String.fromCodePoint(code));
+  }
+  return term;
+}
+
+function leafNeedsMoreSearch(leaf, actual, position) {
+  if (!actual.undecided) return false;
+  if (leaf.false) return true;
+  if (leaf.error != null) return actual.error == null && position >= actual.solutions.length;
+  return position >= actual.solutions.length;
+}
+
+function undecidedResult(actual, expected) {
+  return {
+    ok: false,
+    kind: 'undecided',
+    expected,
+    reason: actual.undecidedReason ?? 'search budget exhausted',
+  };
+}
+
+
 function splitOperator(term, name) {
   if (term.type === COMPOUND && term.name === name && term.arity === 2) {
     return [term.args[0], ...splitOperator(term.args[1], name)];
@@ -408,11 +586,14 @@ function formatFailure(program, quad, result, description = quad.answers[0]) {
   const reason = result.kind === 'malformed' ? 'MALFORMED'
     : result.kind === 'bad_identifier' ? 'BAD_ID'
       : result.kind === 'unsupported' ? 'UNSUPPORTED'
-        : 'FAILED';
+        : result.kind === 'undecided' ? 'UNDECIDED'
+          : 'FAILED';
   const expected = result.expected ?? description;
+  const detail = result.kind === 'undecided'
+    ? `   undecided: ${result.reason}.\n`
+    : `   expected: ${formatQuadTerm(program, expected)}.\n`;
   return `quads: ${reason} ${label}${source.filename}:${source.line}\n` +
-    `   ?- ${formatQuadTerm(program, quad.query)}.\n` +
-    `   expected: ${formatQuadTerm(program, expected)}.\n`;
+    `   ?- ${formatQuadTerm(program, quad.query)}.\n` + detail;
 }
 
 function formatQuadTerm(program, term) {

package/src/repl.js

@@ -18,6 +18,8 @@ RETURN or ".": stop enumeration
 "p": print terms with depth limit
 `;
 
+const SCRIPTED_NEXT_QUERY = Symbol('scripted-next-query');
+
 export async function runRepl(engine, options = {}) {
   const input = options.input ?? process.stdin;
   const output = options.output ?? process.stdout;
@@ -102,6 +104,7 @@ class LineReader {
     this.output = output;
     this.terminal = Boolean(input.isTTY && output.isTTY && typeof input.setRawMode === 'function');
     this.history = [];
+    this.pendingLines = [];
     this.currentPrompt = '?- ';
     this.open();
   }
@@ -119,16 +122,30 @@ class LineReader {
     this.lines = this.readline[Symbol.asyncIterator]();
   }
 
+  async nextLine() {
+    if (this.pendingLines.length > 0) return { done: false, value: this.pendingLines.shift() };
+    return this.lines.next();
+  }
+
   async read(prompt) {
     this.currentPrompt = prompt;
     this.readline.setPrompt(prompt);
     this.output.write(prompt);
-    const result = await this.lines.next();
+    const result = await this.nextLine();
     return result.done ? null : result.value;
   }
 
   async readControl(prompt) {
-    if (!this.terminal) return this.read(prompt);
+    if (!this.terminal) {
+      const result = await this.nextLine();
+      if (result.done) return null;
+      if (!isScriptedAnswerControl(result.value)) {
+        this.pendingLines.unshift(result.value);
+        return SCRIPTED_NEXT_QUERY;
+      }
+      this.output.write(prompt);
+      return result.value;
+    }
     this.output.write(prompt);
     this.history = [...this.readline.history];
     this.currentPrompt = '?- ';
@@ -250,6 +267,12 @@ class LineReader {
   }
 }
 
+function isScriptedAnswerControl(line) {
+  if (line == null || line === '' || line === '\r' || line === '\n' || line === ' ') return true;
+  const control = line.trim();
+  return control.startsWith('.') || [';', 'n', 'a', 'f', 'w', 'p', 'h'].includes(control);
+}
+
 function runWithTerminalSignals(reader, operation) {
   const suspended = reader.suspendForComputation();
   try {
@@ -541,7 +564,6 @@ async function readSource(designation) {
 async function solveQuery(engine, state, goal, reader, output) {
   const variables = queryVariables(goal);
   const solver = state.solver;
-  const demandDriven = containsTimedGoal(goal);
   solver.solutionsSeen = 0;
   const solutions = solver.solve([goal], new engine.Env(), 0);
   let current = pullSolution(solver, solutions, reader);
@@ -560,12 +582,11 @@ async function solveQuery(engine, state, goal, reader, output) {
   let firstAnswer = true;
   let formattingAfterAdvance = false;
   while (!current.result.done) {
-    // Ordinary queries keep the existing eager look-ahead so deterministic
-    // answers can end with a full stop without showing an unnecessary answer
-    // prompt. `time/1` is different: running a future solution changes what is
-    // being measured and can retain a very large current substitution. Timed
-    // queries therefore advance only after the user asks for another answer.
-    const next = demandDriven ? null : pullSolution(solver, solutions, reader);
+    // Enumeration is demand-driven: never execute search for a future answer
+    // merely to decide how to punctuate the current one. That search may have
+    // side effects, and it belongs only to an explicit request for another
+    // answer. A scripted non-TTY session may start its next query directly;
+    // LineReader treats that as an implicit stop without consuming the query.
     if (formattingAfterAdvance) output.write(' ');
     formattingAfterAdvance = false;
     output.write(current.output);
@@ -574,7 +595,11 @@ async function solveQuery(engine, state, goal, reader, output) {
     answersShown++;
     firstAnswer = false;
 
-    if (demandDriven ? !solver.hasPendingAlternatives() : (!next.error && next.result.done)) {
+    if (!solver.hasPendingAlternatives()) {
+      // The solver is suspended at the yielded answer even though no work is
+      // left. Close the generator to run its cleanup/finally blocks without
+      // advancing search or executing future side effects.
+      if (typeof solutions.return === 'function') solutions.return();
       output.write(`${continuesGraphicToken(answer, answer.length) ? ' ' : ''}.\n`);
       return null;
     }
@@ -586,6 +611,11 @@ async function solveQuery(engine, state, goal, reader, output) {
     } else {
       while (true) {
         const controlLine = await reader.readControl('\n;');
+        if (controlLine === SCRIPTED_NEXT_QUERY) {
+          if (typeof solutions.return === 'function') solutions.return();
+          output.write(`${continuesGraphicToken(answer, answer.length) ? ' ' : ''}.\n`);
+          return null;
+        }
         if (controlLine == null || controlLine === '' || controlLine === '\r' || controlLine === '\n' ||
             controlLine.trimStart().startsWith('.')) {
           if (typeof solutions.return === 'function') solutions.return();
@@ -618,52 +648,29 @@ async function solveQuery(engine, state, goal, reader, output) {
       formattingAfterAdvance = true;
     }
 
-    if (demandDriven) {
-      // The displayed timed answer is no longer needed. Drop it before
-      // resuming search so a large list substitution does not remain live only
-      // because the top level is looking for its successor.
-      current = null;
-      const requested = pullSolution(solver, solutions, reader);
-      if (requested.error) {
-        if (formattingAfterAdvance) output.write(' ');
-        formattingAfterAdvance = false;
-        output.write(requested.output);
-        if (requested.error?.name === 'HaltSignal') return { halted: true, code: requested.error.code };
-        throw requested.error;
-      }
-      if (requested.result.done) {
-        if (formattingAfterAdvance) output.write(' ');
-        formattingAfterAdvance = false;
-        output.write(`${requested.output}false.\n`);
-        return null;
-      }
-      current = requested;
-      continue;
+    // Drop the displayed substitution before resuming search. The next search
+    // step, including any side effects, happens only after the user asked for
+    // another answer (or selected automatic enumeration).
+    current = null;
+    const requested = pullSolution(solver, solutions, reader);
+    if (requested.error) {
+      if (formattingAfterAdvance) output.write(' ');
+      formattingAfterAdvance = false;
+      output.write(requested.output);
+      if (requested.error?.name === 'HaltSignal') return { halted: true, code: requested.error.code };
+      throw requested.error;
     }
-
-    if (next.error) {
+    if (requested.result.done) {
       if (formattingAfterAdvance) output.write(' ');
       formattingAfterAdvance = false;
-      output.write(next.output);
-      if (next.error?.name === 'HaltSignal') return { halted: true, code: next.error.code };
-      throw next.error;
+      output.write(`${requested.output}false.\n`);
+      return null;
     }
-    current = next;
+    current = requested;
   }
   return null;
 }
 
-function containsTimedGoal(goal) {
-  const stack = [goal];
-  while (stack.length !== 0) {
-    const term = stack.pop();
-    if (term?.type !== 'compound') continue;
-    if (term.name === 'time' && term.arity === 1) return true;
-    for (let index = term.args.length - 1; index >= 0; index--) stack.push(term.args[index]);
-  }
-  return false;
-}
-
 function pullSolution(solver, solutions, reader) {
   const stream = solver.io.resolve('user_output');
   const originalWrite = stream?.write;

package/src/solver.js

@@ -679,7 +679,7 @@ export class Solver {
 
   hasPendingAlternatives() {
     // When solve() is suspended at an answer, active solve stacks contain only
-    // unexplored work. The timed REPL path uses this without speculatively
+    // unexplored work. The demand-driven REPL uses this without speculatively
     // pulling the next answer.
     return this.solveStacks.some((stack) => stack.length !== 0);
   }

package/test/run-regression.mjs

@@ -1333,6 +1333,53 @@ c4 ?- call((!;1)).
         assertEqual(result.stdout, 'quads: 1 run, 1 passed, 0 failed.\n', 'quad report');
       },
     },
+    {
+      name: 'quad search-budget exhaustion is undecided rather than loops or failure (issue #58)',
+      run: () => {
+        const result = runCli(['--quads', '-'], {
+          input:
+            '24,passes/too_expensive\n' +
+            '?- N is 10^9, between(1,N,I), I = 1.\n' +
+            '   N = ..., I = 1\n' +
+            ';  false.\n',
+          timeout: 5000,
+        });
+        if (result.error) throw result.error;
+        assertEqual(result.status, 2, 'undecided exit status');
+        assertIncludes(result.stdout,
+          'quads: UNDECIDED 24, passes / too_expensive, <stdin>:1',
+          'undecided diagnostic');
+        assertIncludes(result.stdout, 'undecided: inference limit reached.', 'undecided reason');
+        assertIncludes(result.stdout,
+          'quads: 1 run, 0 passed, 0 failed, 1 undecided.',
+          'undecided summary');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'outputs/1 accepts DCG bodies over captured characters (issue #59)',
+      run: () => {
+        const source = [
+          'pair --> "_", "A".',
+          '22',
+          "?- write('_A').",
+          '   outputs("_A").',
+          '   outputs("_"), unexpected.',
+          '   outputs(("_","A")).',
+          '   outputs(("_",...,"A")).',
+          '   outputs(("_",...,"B")), unexpected.',
+          '   outputs(("_",[_],[_])), unexpected.',
+          '   outputs(pair).',
+          '',
+        ].join('\n');
+        const result = publicApi.runQuads(source);
+        assertEqual(result.total, 7, 'quad total');
+        assertEqual(result.passed, 7, 'quad passed');
+        assertEqual(result.failed, 0, 'quad failed');
+        assertEqual(result.undecided, 0, 'quad undecided');
+        assertEqual(result.stdout, 'quads: 7 run, 7 passed, 0 failed.\n', 'quad report');
+      },
+    },
     {
       name: '--quads runs embedded tests and reports failures through exit status',
       run: () => {
@@ -1675,6 +1722,52 @@ c4 ?- call((!;1)).
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'REPL does not precompute an unrequested future alternative (issue #48)',
+      run: () => {
+        const result = runCli([], {
+          input: '(X = first; (repeat, fail)).\nhalt.\n',
+          timeout: 2000,
+        });
+        if (result.error) throw result.error;
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, '?-    X = first.\n?- ', 'first answer is immediate');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'REPL executes future side effects only after another answer is requested (issue #48)',
+      run: () => {
+        const stopped = runCli([], {
+          input:
+            '(X = first; (assertz(issue48_seen), X = second)).\n' +
+            'current_predicate(issue48_seen/0).\n' +
+            'halt.\n',
+        });
+        assertEqual(stopped.status, 0, 'stopped status');
+        assertEqual(
+          stopped.stdout,
+          '?-    X = first.\n?-    false.\n?- ',
+          'unrequested branch has no side effect',
+        );
+
+        const advanced = runCli([], {
+          input:
+            '(X = first; (assertz(issue48_seen), X = second)).\n' +
+            ';\n' +
+            'current_predicate(issue48_seen/0).\n' +
+            'halt.\n',
+        });
+        assertEqual(advanced.status, 0, 'advanced status');
+        assertEqual(
+          advanced.stdout,
+          '?-    X = first\n;  X = second.\n?-    true.\n?- ',
+          'requested branch performs its side effect',
+        );
+        assertEqual(stopped.stderr, '', 'stopped stderr');
+        assertEqual(advanced.stderr, '', 'advanced stderr');
+      },
+    },
     {
       name: 'REPL bindings use argument syntax for operator atoms',
       run: () => {
@@ -1707,7 +1800,7 @@ c4 ?- call((!;1)).
           child.stdout.on('data', (text) => {
             stdout += text;
             if (stdout.endsWith('?-   ')) sawQueryComputingPrompt = true;
-            if (stdout.endsWith('\\n; ')) sawComputingPrompt = true;
+            if (stdout.includes('\\n; ')) sawComputingPrompt = true;
           });
           child.stderr.on('data', (text) => { stderr += text; });
 
@@ -1728,10 +1821,10 @@ c4 ?- call((!;1)).
           await waitFor(() => sawQueryComputingPrompt, 'query computing prompt');
           await waitFor(() => stdout.endsWith('   false.\\n?- '), 'query result');
           child.stdin.write('(N = 0; N = 1; (call_nth(repeat, 100000), N = 2)).\\n');
-          await waitFor(() => stdout.endsWith('   N = 0\\n;'), 'waiting prompt');
+          await waitFor(() => stdout.endsWith('   N = 0'), 'first answer');
           child.stdin.write(';\\n');
           await waitFor(() => sawComputingPrompt, 'computing prompt');
-          await waitFor(() => stdout.endsWith(';  N = 1\\n;'), 'formatted answer');
+          await waitFor(() => stdout.endsWith(';  N = 1'), 'formatted answer');
           child.stdin.write('\\n');
           await waitFor(() => stdout.endsWith('  ... .\\n?- '), 'stopped enumeration');
           child.stdin.write('halt.\\n');

package/the-art-of-eyeprolog.md

@@ -6645,8 +6645,16 @@ 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. Once the top-level reader has accepted a complete
-query, the following line begins with two spaces to mark active execution; a
+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. If an unresolved alternative ultimately has no solution, asking
+for it may therefore finish with `false.`. In scripted non-TTY input, a new
+query line implicitly stops the preceding answer enumeration without consuming
+the new query; explicit `;`, `n`, Space, `a`, or `f` still requests more
+answers. Once the top-level reader has accepted a complete query, the following
+line begins with two spaces to mark active execution; a
 third space appears when its result is ready for formatting. The answer prompt
 is `;` with no trailing space while it waits for input; after an advance
 command, one space marks active search and a second marks an answer ready for
@@ -6812,9 +6820,11 @@ requires that argument to be ground; a non-ground label is reported as a quad
 failure rather than aborting source parsing. Loading the file normally only
 records its quads; it does not execute them or add their queries and answers as
 program clauses. A quad run prints a summary and exits with status `1` when any
-description fails. Quad mode imports `library(prologue)` as a compatibility
-prelude because the ISO Prolog working-example files use those predicates as
-system predicates without an explicit module directive.
+description fails. If no description fails but a bounded search cannot decide
+an exact answer sequence, the case is reported separately as `UNDECIDED` and
+the CLI exits with status `2`. Quad mode imports `library(prologue)` as a
+compatibility prelude because the ISO Prolog working-example files use those
+predicates as system predicates without an explicit module directive.
 
 Unless the source explicitly selects another `unknown` flag, quad execution
 uses `unknown=error`, so an undefined predicate is reported rather than being
@@ -6831,12 +6841,19 @@ variable in the renamed exception term. `...` and `ad_infinitum` accept further
 indented descriptions after one query are independent checks: each re-runs the
 query, each is counted in the `quads:` summary, and a failing description does
 not suppress later descriptions for that query. `inputs/1` supplies and checks
-consumed characters; `outputs/1` checks characters emitted while reaching
-the described answer or error, including output produced before a later
-exception. `sto` marks an answer description that this finite-tree
-implementation skips. `loops` accepts direct active-variant cycle evidence from
-EyeProlog's normal recursion guard, with bounded depth/inference exhaustion as a
-fallback for loops that have no such structural witness. The advanced stream
+consumed characters. `outputs/1` checks characters emitted while reaching the
+described answer or error, including output produced before a later exception.
+Its argument may be an exact character list/string or a DCG body: terminal
+sequences, conjunction/disjunction, `...`/`ad_infinitum` sequence wildcards,
+and user-defined DCG nonterminals are matched against the captured characters.
+`sto` marks an answer description that this finite-tree implementation skips.
+`loops` explicitly asks for bounded nontermination evidence and accepts direct
+active-variant cycle evidence from EyeProlog's normal recursion guard, with the
+loop depth/inference bounds as a fallback. Ordinary quad descriptions also have
+a finite inference budget (100000 by default); exhausting it does **not** mean
+`loops` or `false`, but produces an `UNDECIDED` result. The JavaScript API may
+override this with `quadMaxInferences`, while `loopMaxDepth` and
+`loopMaxInferences` control the explicit `loops` probe. The advanced stream
 annotations `peeks/1` and `waits`, and the unordered `other_answer_sequence`
 annotation, are not executed by the current runner.
 
@@ -6847,7 +6864,7 @@ import { Program, runQuads } from 'eyeprolog';
 
 const program = Program.parse(source);
 const report = runQuads(program);
-console.log(report.passed, report.failed, report.stdout);
+console.log(report.passed, report.failed, report.undecided, report.stdout);
 ```
 
 The syntax follows the “queries using answer descriptions” convention used by