eyeprolog 1.3.37 → 1.3.38

package/README.md

@@ -149,6 +149,24 @@ statistics(wfs_undefined_answers, UndefinedObservations).
 Both automatic tabling and `tnot/1` are EyeProlog extensions. Strict ISO mode
 disables automatic tabling and does not provide `tnot/1`.
 
+## Cleanup-aware control
+
+Normal mode provides `call_cleanup/2` and `setup_call_cleanup/3` for resource
+lifetimes that follow Prolog search. Cleanup runs exactly once when the protected
+goal completes deterministically, is exhausted, is cut or otherwise pruned, the
+top level stops answer enumeration, or an exception unwinds the search.
+`setup_call_cleanup/3` runs Setup once and installs Cleanup only after Setup
+succeeds. On ordinary pruning Cleanup sees the current goal bindings; during
+exception unwinding bindings made by the protected goal have already been
+unwound. Cleanup failure is ignored, and an exception already being propagated
+takes precedence over a cleanup exception. Nested cleanups run inside-out.
+
+These predicates are EyeProlog normal-mode extensions and are absent from
+`--iso-strict`. Their implementation is lifecycle-aware: the interactive top
+level can report a remaining choicepoint without speculatively requesting the
+next solution, while abandoning that choicepoint still closes protected
+resources.
+
 ## OpenRuleBench portable profile
 
 The `openrulebench/` directory contains a deterministic four-engine adaptation
@@ -176,9 +194,10 @@ eyeprolog --iso-strict --goal 'p(X)' program.pl
 
 The equivalent JavaScript option is `isoStrict: true`. Strict mode rejects
 EyeProlog language extensions, Part 2 module directives, and Part 3 grammar-rule
-expansion/`phrase/2-3`; it also removes the EyeProlog `occurs_check` flag and
-disables automatic tabling. Normal mode is unchanged and continues to support
-modules, DCGs, quads, libraries, proofs, and the other documented extensions.
+expansion/`phrase/2-3`; it also removes the EyeProlog `occurs_check` flag,
+`call_cleanup/2`, and `setup_call_cleanup/3`, and disables automatic tabling.
+Normal mode is unchanged and continues to support modules, DCGs, quads,
+libraries, proofs, cleanup-aware control, and the other documented extensions.
 
 The auditable processor-requirement checklist lives in
 [`test/conformance/ISO-COMPLIANCE.md`](test/conformance/ISO-COMPLIANCE.md).

package/examples/book/chapter-37/01-write_event.pl

@@ -1,7 +1,10 @@
 % From The Art of EyeProlog, Chapter 37.
 write_event(Path, Event) :-
-  open(Path, write, Stream, [type(text)]),
-  write_canonical(Stream, Event),
-  put_char(Stream, '.'),
-  nl(Stream),
-  close(Stream).
+  setup_call_cleanup(
+    open(Path, write, Stream, [type(text)]),
+    ( write_canonical(Stream, Event),
+      put_char(Stream, '.'),
+      nl(Stream)
+    ),
+    close(Stream)
+  ).

package/package.json

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

package/src/ARCHITECTURE.md

@@ -11,7 +11,10 @@ higher-level frontends.
    `program-indexing.js`. Static recursion/Datalog/WFS classification lives in
    `program-analysis.js`; compact clauses and candidate indexes live in
    `program-indexing.js`.
-3. **Execution** — `solver.js`, `io.js`, `datalog.js`, `wfs.js`, `clpz.js`.
+3. **Execution** — `solver.js`, `cleanup.js`, `io.js`, `datalog.js`, `wfs.js`,
+   `clpz.js`. `cleanup.js` owns lifecycle-aware disposal of protected builtin
+   iterators and registers the normal-profile cleanup controls without making
+   `solver.js` depend back on the language registry.
 4. **Language services** — `iso.js`, `iso-arithmetic.js`, `dcg.js`,
    `standard-library.js`, and `src/lib/`.
 5. **Frontends/tools** — `execute.js`, `repl.js`, `cli.js`, `quads.js`,
@@ -30,7 +33,9 @@ report processor errors without importing `iso.js` and creating an
 
 The JavaScript runtime stays flat directly under `src/`; the existing `src/lib/`
 contains Prolog library sources rather than JavaScript runtime modules. The architecture
-test rejects JavaScript import cycles under `src/`.
+test rejects JavaScript import cycles under `src/`. Cleanup lifecycle hooks are
+installed from the public API and CLI entry paths; `standard-library.js` only
+registers the predicates, so the execution layer remains acyclic.
 
 ## Performance rule
 

package/src/cleanup.js

@@ -0,0 +1,339 @@
+// call_cleanup/2 and setup_call_cleanup/3 plus solver lifecycle support.
+//
+// EyeProlog's solver is demand-driven: a yielded builtin remains represented by
+// a resumeBuiltin frame until its next answer is requested. Cleanup predicates
+// therefore need two pieces of host support:
+//   * discarded resumeBuiltin iterators must be closed when search is pruned;
+//   * a cleanup iterator can report that its protected goal has no alternatives,
+//     so the REPL does not need speculative look-ahead to suppress a choicepoint.
+import { PrologError } from './errors.js';
+import { deref } from './term.js';
+
+const cleanupLifecycleInstalled = Symbol('eyeprolog.cleanupLifecycleInstalled');
+const cleanupLifecycleState = Symbol('eyeprolog.cleanupLifecycleState');
+const searchStackPatched = Symbol('eyeprolog.cleanupSearchStackPatched');
+
+export function installCleanupLifecycle(Solver) {
+  const prototype = Solver.prototype;
+  if (prototype[cleanupLifecycleInstalled]) return;
+  Object.defineProperty(prototype, cleanupLifecycleInstalled, { value: true });
+
+  const originalSolve = prototype.solve;
+  prototype.solve = function* cleanupAwareSolve(...args) {
+    const state = ensureLifecycleState(this);
+    const owner = {};
+    const iterator = originalSolve.apply(this, args);
+    let completed = false;
+    let thrown = null;
+
+    try {
+      while (true) {
+        const result = withOwner(state, owner, () => iterator.next());
+        if (result.done) {
+          completed = true;
+          return result.value;
+        }
+        yield result.value;
+      }
+    } catch (error) {
+      thrown = error;
+      throw error;
+    } finally {
+      // If the consumer prunes this solve() while it is suspended at an answer,
+      // close pending builtin iterators before the original solver removes its
+      // explicit search stack. Cleanup exceptions are observable on an ordinary
+      // cut/return, but never replace an exception already propagating outward.
+      if (!completed) {
+        let closeError = null;
+        try {
+          closeOwnedSearchStacks(this, state, owner, thrown != null);
+        } catch (error) {
+          closeError = error;
+        }
+        try {
+          withOwner(state, owner, () => iterator.return?.());
+        } catch (error) {
+          if (closeError == null) closeError = error;
+        }
+        if (thrown == null && closeError != null) throw closeError;
+      }
+    }
+  };
+
+  prototype.hasPendingAlternatives = function cleanupAwarePendingAlternatives() {
+    return this.solveStacks.some((stack) => stack.some(frameHasPendingAlternative));
+  };
+}
+
+export function registerCleanupBuiltins(registry) {
+  registry.add('call_cleanup', 2, callCleanupBuiltin);
+  registry.add('setup_call_cleanup', 3, setupCallCleanupBuiltin);
+}
+
+function ensureLifecycleState(solver) {
+  if (solver[cleanupLifecycleState] != null) return solver[cleanupLifecycleState];
+  const state = {
+    owner: null,
+    stackOwners: new WeakMap(),
+  };
+  Object.defineProperty(solver, cleanupLifecycleState, { value: state });
+
+  const solveStacks = solver.solveStacks;
+  const originalPush = solveStacks.push;
+  const originalSplice = solveStacks.splice;
+
+  solveStacks.push = function cleanupAwarePush(...stacks) {
+    for (const stack of stacks) {
+      state.stackOwners.set(stack, state.owner);
+      patchSearchStack(stack);
+    }
+    return originalPush.apply(this, stacks);
+  };
+
+  solveStacks.splice = function cleanupAwareSplice(start, deleteCount, ...items) {
+    const removed = originalSplice.call(this, start, deleteCount, ...items);
+    // This path is used by Solver.solve()'s finally block. If the solve is
+    // unwinding an exception, a cleanup exception must not replace it. Normal
+    // consumer pruning closes frames earlier in cleanupAwareSolve(), where
+    // cleanup errors are allowed to propagate.
+    for (let index = removed.length - 1; index >= 0; index--) {
+      closeSearchStack(removed[index], true);
+    }
+    return removed;
+  };
+
+  return state;
+}
+
+function withOwner(state, owner, operation) {
+  const previous = state.owner;
+  state.owner = owner;
+  try {
+    return operation();
+  } finally {
+    state.owner = previous;
+  }
+}
+
+function patchSearchStack(stack) {
+  if (stack[searchStackPatched]) return;
+  Object.defineProperty(stack, searchStackPatched, { value: true });
+  const originalSplice = stack.splice;
+  stack.splice = function cleanupAwareSearchSplice(start, deleteCount, ...items) {
+    const removed = originalSplice.call(this, start, deleteCount, ...items);
+    // A cut prunes explicit search frames synchronously. Closing a discarded
+    // builtin iterator here gives call_cleanup/2 its required cut semantics and
+    // also lets existing builtin finally blocks release their child solvers.
+    closeFrames(removed, false);
+    return removed;
+  };
+}
+
+function closeOwnedSearchStacks(solver, state, owner, suppressErrors) {
+  const stacks = solver.solveStacks
+    .filter((stack) => state.stackOwners.get(stack) === owner)
+    .slice()
+    .reverse();
+  let firstError = null;
+  for (const stack of stacks) {
+    try {
+      closeSearchStack(stack, suppressErrors);
+    } catch (error) {
+      if (firstError == null) firstError = error;
+    }
+  }
+  if (!suppressErrors && firstError != null) throw firstError;
+}
+
+function closeSearchStack(stack, suppressErrors) {
+  if (stack == null || stack.length === 0) return;
+  // Use Array.prototype directly: calling the patched splice would always use
+  // cut semantics (propagating errors) even while an exception is unwinding.
+  const removed = Array.prototype.splice.call(stack, 0, stack.length);
+  closeFrames(removed, suppressErrors);
+}
+
+function closeFrames(frames, suppressErrors) {
+  let firstError = null;
+  for (let index = frames.length - 1; index >= 0; index--) {
+    const frame = frames[index];
+    if (frame?.kind !== 'resumeBuiltin' || typeof frame.iterator?.return !== 'function') continue;
+    try {
+      frame.iterator.prepareClose?.({ unwinding: suppressErrors });
+      frame.iterator.return();
+    } catch (error) {
+      if (firstError == null) firstError = error;
+    }
+  }
+  if (!suppressErrors && firstError != null) throw firstError;
+}
+
+function frameHasPendingAlternative(frame) {
+  if (frame?.kind !== 'resumeBuiltin') return true;
+  const predicate = frame.iterator?.hasPendingAlternatives;
+  if (typeof predicate !== 'function') return true;
+  return predicate.call(frame.iterator);
+}
+
+function callableTerm(term, env) {
+  const value = deref(term, env);
+  if (value.type === 'var') throw new PrologError('instantiation_error');
+  if (value.type !== 'atom' && value.type !== 'compound') {
+    throw new PrologError('type_error(callable)', value);
+  }
+  return value;
+}
+
+function firstSetupSolution(solver, setup, env) {
+  const child = solver.cloneForInnerGoal(1);
+  const iterator = child.solve([callableTerm(setup, env)], env.clone(), 0);
+  try {
+    const result = iterator.next();
+    return result.done ? null : result.value;
+  } finally {
+    try {
+      iterator.return?.();
+    } finally {
+      solver.absorbStatsFrom(child);
+    }
+  }
+}
+
+function callCleanupBuiltin({ solver, goal, env }) {
+  const cleanup = callableTerm(goal.args[1], env);
+  return cleanupProtectedIterator(solver, goal.args[0], cleanup, env);
+}
+
+function setupCallCleanupBuiltin({ solver, goal, env }) {
+  let protectedIterator = null;
+  let pending = true;
+  const iterator = (function* setupThenProtected() {
+    const setupEnv = firstSetupSolution(solver, goal.args[0], env);
+    if (setupEnv == null) {
+      pending = false;
+      return;
+    }
+    // The cleanup is validated after Setup succeeds and before Goal starts, as
+    // in the WG17 cleanup proposal. A variable bound by Setup may therefore be
+    // used as Cleanup.
+    const cleanup = callableTerm(goal.args[2], setupEnv);
+    protectedIterator = cleanupProtectedIterator(solver, goal.args[1], cleanup, setupEnv);
+    try {
+      while (true) {
+        const result = protectedIterator.next();
+        pending = protectedIterator.hasPendingAlternatives();
+        if (result.done) {
+          pending = false;
+          return;
+        }
+        yield result.value;
+        if (!pending) return;
+      }
+    } finally {
+      protectedIterator.return?.();
+    }
+  })();
+  iterator.hasPendingAlternatives = () => pending;
+  iterator.prepareClose = (reason) => protectedIterator?.prepareClose?.(reason);
+  return iterator;
+}
+
+function cleanupProtectedIterator(solver, protectedGoal, cleanup, initialEnv) {
+  const child = solver.cloneForInnerGoal();
+  let childIterator = null;
+  let cleanupEnv = initialEnv;
+  let pending = true;
+  let cleaned = false;
+  let bodyError = null;
+  let unwindToSetupBindings = false;
+
+  const performCleanup = () => {
+    if (cleaned) return;
+    // Mark first so a throwing Cleanup is still considered executed exactly once.
+    cleaned = true;
+    runCleanupOnce(solver, cleanup, cleanupEnv);
+  };
+
+  const iterator = (function* protectedWithCleanup() {
+    try {
+      childIterator = child.solve([callableTerm(protectedGoal, initialEnv)], initialEnv.clone(), 0);
+      while (true) {
+        const result = childIterator.next();
+        if (result.done) {
+          pending = false;
+          // At the latest cleanup moment, Goal bindings have been undone.
+          cleanupEnv = initialEnv;
+          return;
+        }
+
+        cleanupEnv = result.value;
+        pending = child.hasPendingAlternatives();
+        if (!pending) {
+          // A deterministic final answer is known from the solver's explicit
+          // pending-frame state. Finalize the protected iterator and cleanup now,
+          // before yielding the answer, without computing a speculative answer.
+          childIterator.return?.();
+          childIterator = null;
+          performCleanup();
+        }
+
+        yield result.value;
+        if (!pending) return;
+      }
+    } catch (error) {
+      bodyError = error;
+      // Exceptions from Goal unwind its bindings before Cleanup is called.
+      cleanupEnv = initialEnv;
+      throw error;
+    } finally {
+      let childCloseError = null;
+      if (childIterator != null) {
+        try {
+          childIterator.return?.();
+        } catch (error) {
+          childCloseError = error;
+        }
+        childIterator = null;
+      }
+      solver.absorbStatsFrom(child);
+
+      if (unwindToSetupBindings) cleanupEnv = initialEnv;
+      if (!cleaned) {
+        try {
+          performCleanup();
+        } catch (cleanupError) {
+          // When the protected goal (or an inner cleanup) already raised, it has
+          // priority over this cleanup exception. An exception from an outer
+          // continuation is preserved by cleanup-aware stack teardown too.
+          if (bodyError == null && childCloseError == null) throw cleanupError;
+        }
+      }
+      if (bodyError == null && childCloseError != null) throw childCloseError;
+    }
+  })();
+
+  iterator.hasPendingAlternatives = () => pending;
+  iterator.prepareClose = ({ unwinding } = {}) => {
+    unwindToSetupBindings = unwinding === true;
+  };
+  return iterator;
+}
+
+function runCleanupOnce(solver, cleanup, env) {
+  const child = solver.cloneForInnerGoal(1);
+  const iterator = child.solve([cleanup], env.clone(), 0);
+  let result;
+  try {
+    result = iterator.next();
+  } finally {
+    try {
+      iterator.return?.();
+    } finally {
+      solver.absorbStatsFrom(child);
+    }
+  }
+  // Cleanup is semidet only as a control operation: failure is ignored, and
+  // bindings made solely by Cleanup are intentionally not added to an answer
+  // already produced by Goal.
+  return !result.done;
+}

package/src/cli.js

@@ -174,7 +174,7 @@ export async function main(argv) {
 
 async function loadEngine() {
   if (engineModule == null) {
-    const [term, parser, program, solver, iso, library, write, quads, execute] = await Promise.all([
+    const [term, parser, program, solver, iso, library, write, quads, execute, cleanup] = await Promise.all([
       import('./term.js'),
       import('./parser.js'),
       import('./program.js'),
@@ -184,7 +184,11 @@ async function loadEngine() {
       import('./write.js'),
       import('./quads.js'),
       import('./execute.js'),
+      import('./cleanup.js'),
     ]);
+    // CLI loading is an entry-point layer above solver.js and the standard
+    // registry, so lifecycle installation stays acyclic.
+    cleanup.installCleanupLifecycle(solver.Solver);
     engineModule = { ...term, ...parser, ...program, ...solver, ...iso, ...library, ...write, ...quads, ...execute };
   }
   return engineModule;

package/src/index.js

@@ -27,6 +27,7 @@ export {
 export { StreamManager } from './io.js';
 export { runQuads } from './quads.js';
 
+import { installCleanupLifecycle } from './cleanup.js';
 import { Program, autoloadProgramGoals } from './program.js';
 import { Solver } from './solver.js';
 import { whyNoProof, whyProof } from './explain.js';
@@ -34,6 +35,10 @@ import { getStrictIsoRegistry } from './iso.js';
 import { getEyePrologRegistry } from './standard-library.js';
 import { executeGoals, normalizeGoals } from './execute.js';
 
+// The public API is an entry point above the solver/registry layers, so it can
+// install pruning-aware iterator disposal without introducing an import cycle.
+installCleanupLifecycle(Solver);
+
 export function run(source, options = {}) {
   const includeWhy = options.proof === true || options.why === true || options.explain === true;
   const requestedStrictIso = options.isoStrict === true;

package/src/standard-library.js

@@ -4,6 +4,7 @@
 // source-level interop autoloader declared below.
 import { PrologError, createDefaultRegistry, eyePrologLibraryBuiltins } from './iso.js';
 import { clpzBuiltins } from './clpz.js';
+import { registerCleanupBuiltins } from './cleanup.js';
 import { fs, isNode, memoryStatistics } from './platform.js';
 import { ATOM, VAR, atom, deref, numberTerm, unify } from './term.js';
 
@@ -181,6 +182,7 @@ export function createEyePrologRegistry() {
   registry.add('statistics', 0, statisticsBuiltin, { deterministic: true });
   registry.add('statistics', 2, statisticsValueBuiltin);
   registry.add('tnot', 1, tabledNegationBuiltin, { deterministic: true });
+  registerCleanupBuiltins(registry);
   eyePrologLibraryBuiltins.register(registry);
   clpzBuiltins.register(registry);
   registry.eyePrologLibrary = true;

package/test/run-all.mjs

@@ -12,6 +12,7 @@ import { runBookExamples } from './run-book-examples.mjs';
 import { runWg17 } from './run-wg17.mjs';
 import { runOpenRuleBenchChecks } from './run-openrulebench.mjs';
 import { runArchitecture } from './run-architecture.mjs';
+import { runCleanup } from './run-cleanup.mjs';
 
 await runStandalone(async (reporter) => {
   runConformance(reporter);
@@ -19,6 +20,7 @@ await runStandalone(async (reporter) => {
   runWg17(reporter);
   runOpenRuleBenchChecks(reporter);
   runArchitecture(reporter);
+  runCleanup(reporter);
   runRegression(reporter);
   await runPlayground(reporter);
   runExamples(reporter);

package/test/run-cleanup.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// Regression coverage for call_cleanup/2 and setup_call_cleanup/3.
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  assertEqual,
+  assertIncludes,
+  assertNotIncludes,
+  isMainModule,
+  runStandalone,
+} from './test-style.mjs';
+
+const testRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+const packageRoot = path.resolve(testRoot, '..');
+const bin = path.join(packageRoot, 'bin', 'eyeprolog.js');
+
+export function runCleanup(reporter) {
+  reporter.section('Cleanup control');
+
+  reporter.test('call_cleanup/2 deterministic success has no leftover choicepoint', () => {
+    const result = runRepl('call_cleanup(true,true).\nhalt.\n');
+    assertEqual(result.status, 0, 'status');
+    assertIncludes(result.stdout, 'true.', 'stdout');
+    assertNotIncludes(result.stdout, '\n;', 'stdout');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.test('call_cleanup/2 runs cleanup when the user stops enumeration', () => {
+    const result = runRepl('call_cleanup((X=one;X=two),write(issue48_cleanup)).\n.\nhalt.\n');
+    assertEqual(result.status, 0, 'status');
+    assertIncludes(result.stdout, 'X = one', 'first answer');
+    assertIncludes(result.stdout, 'issue48_cleanup', 'cleanup output');
+    assertNotIncludes(result.stdout, 'X = two', 'unrequested answer');
+    assertEqual(count(result.stdout, 'issue48_cleanup'), 1, 'cleanup count');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.test('call_cleanup/2 runs before continuation after cut and sees current bindings', () => {
+    const result = runRepl(
+      'call_cleanup((X=one;X=two),assertz(issue48_saved(X))),!,issue48_saved(Y).\nhalt.\n',
+    );
+    assertEqual(result.status, 0, 'status');
+    assertIncludes(result.stdout, 'X = one, Y = one.', 'cut cleanup answer');
+    assertNotIncludes(result.stdout, 'false.', 'stdout');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.test('call_cleanup/2 preserves protected exception over cleanup exception', () => {
+    const result = runRepl('catch(call_cleanup(throw(original),throw(cleanup)),E,true).\nhalt.\n');
+    assertEqual(result.status, 0, 'status');
+    assertIncludes(result.stdout, 'E = original.', 'caught exception');
+    assertNotIncludes(result.stdout, 'E = cleanup', 'exception priority');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.test('exception unwind removes Goal bindings before Cleanup', () => {
+    const result = runRepl(
+      'catch((setup_call_cleanup(true,(G=bound;G=other),(var(G)->write(cleanup_unbound);write(cleanup_bound))),throw(cont)),E,true).\nhalt.\n',
+    );
+    assertEqual(result.status, 0, 'status');
+    assertIncludes(result.stdout, 'cleanup_unbound', 'cleanup binding state');
+    assertNotIncludes(result.stdout, 'cleanup_bound', 'unwound Goal binding');
+    assertIncludes(result.stdout, 'E = cont.', 'continuation exception');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.test('nested call_cleanup/2 cleanups run inside-out on cut', () => {
+    const result = runRepl(
+      'call_cleanup(call_cleanup((X=one;X=two),write(inner_cleanup)),write(outer_cleanup)),!,true.\nhalt.\n',
+    );
+    assertEqual(result.status, 0, 'status');
+    const inner = result.stdout.indexOf('inner_cleanup');
+    const outer = result.stdout.indexOf('outer_cleanup');
+    if (inner < 0 || outer < 0 || inner >= outer) {
+      throw new Error(`cleanup order mismatch\nstdout: ${JSON.stringify(result.stdout)}`);
+    }
+    assertEqual(count(result.stdout, 'inner_cleanup'), 1, 'inner cleanup count');
+    assertEqual(count(result.stdout, 'outer_cleanup'), 1, 'outer cleanup count');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.test('setup_call_cleanup/3 calls Setup once and ignores cleanup failure', () => {
+    const result = runRepl('setup_call_cleanup((X=one;X=two),true,fail).\nhalt.\n');
+    assertEqual(result.status, 0, 'status');
+    assertIncludes(result.stdout, 'X = one.', 'setup result');
+    assertNotIncludes(result.stdout, 'X = two', 'second setup solution');
+    assertNotIncludes(result.stdout, '\n;', 'leftover choicepoint');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.test('setup_call_cleanup/3 does not install cleanup when Setup fails', () => {
+    const result = runRepl('setup_call_cleanup(fail,true,write(should_not_run)).\nhalt.\n');
+    assertEqual(result.status, 0, 'status');
+    assertIncludes(result.stdout, 'false.', 'failed setup');
+    assertNotIncludes(result.stdout, 'should_not_run', 'cleanup output');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.test('setup_call_cleanup/3 validates Cleanup after successful Setup', () => {
+    const result = runRepl('catch(setup_call_cleanup(true,true,_),E,true).\nhalt.\n');
+    assertEqual(result.status, 0, 'status');
+    assertIncludes(result.stdout, 'instantiation_error', 'cleanup validation error');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.test('cleanup predicates remain outside strict ISO core', () => {
+    const result = runRepl('catch(call_cleanup(true,true),E,true).\nhalt.\n', ['--iso-strict']);
+    assertEqual(result.status, 0, 'status');
+    assertIncludes(result.stdout, 'existence_error(procedure', 'strict ISO error');
+    assertIncludes(result.stdout, 'call_cleanup', 'strict ISO predicate');
+    assertEqual(result.stderr, '', 'stderr');
+  });
+
+  reporter.sectionTotal('cleanup');
+}
+
+function runRepl(input, args = []) {
+  const result = spawnSync(process.execPath, [bin, ...args], {
+    cwd: packageRoot,
+    input,
+    encoding: 'utf8',
+    timeout: 10000,
+  });
+  if (result.error) throw result.error;
+  return result;
+}
+
+function count(text, needle) {
+  return String(text).split(needle).length - 1;
+}
+
+if (isMainModule(import.meta.url)) {
+  await runStandalone((reporter) => runCleanup(reporter));
+}

package/test/run-regression.mjs

@@ -4471,7 +4471,7 @@ answer(ok) :-
         assertEqual(Boolean(registry.get('is', 2)), true, 'ISO is/2 exists');
         assertEqual(Boolean(registry.get('append', 3)), false, 'append/3 is not ISO core');
         assertEqual(library.eyePrologLibrary, true, 'complete registry marker');
-        assertEqual(library.defs.size, 158, 'EyeProlog registry contains ISO definitions, observability extensions, WFS tnot/1, and private library adapters');
+        assertEqual(library.defs.size, 160, 'EyeProlog registry contains ISO definitions, cleanup controls, observability extensions, WFS tnot/1, and private library adapters');
         assertEqual(Boolean(registry.get('phrase', 2)), true, 'Part 3 phrase/2 exists');
         assertEqual(Boolean(registry.get('phrase', 3)), true, 'Part 3 phrase/3 exists');
         assertEqual(registry.get('statistics', 0), null, 'statistics/0 is absent from the ISO registry');
@@ -4482,6 +4482,10 @@ answer(ok) :-
         assertEqual(Boolean(library.get('tnot', 1)), true, 'tnot/1 is an EyeProlog WFS extension');
         assertEqual(registry.get('time', 1), null, 'time/1 is absent from the ISO registry');
         assertEqual(Boolean(library.get('time', 1)), true, 'time/1 is an EyeProlog timing extension');
+        assertEqual(registry.get('call_cleanup', 2), null, 'call_cleanup/2 is absent from the ISO registry');
+        assertEqual(Boolean(library.get('call_cleanup', 2)), true, 'call_cleanup/2 is an EyeProlog cleanup control');
+        assertEqual(registry.get('setup_call_cleanup', 3), null, 'setup_call_cleanup/3 is absent from the ISO registry');
+        assertEqual(Boolean(library.get('setup_call_cleanup', 3)), true, 'setup_call_cleanup/3 is an EyeProlog cleanup control');
         assertEqual(registeredNativeEyePrologLibraryNames().length, 41, 'public native EyeProlog builtin count');
         assertEqual(eyePrologPortableLibraryIndicators.length, 87, 'portable Prolog library count');
         assertEqual(eyePrologInteropLibraryIndicators.length, 29, 'cross-implementation interop profile count');

package/the-art-of-eyeprolog.md

@@ -1947,6 +1947,13 @@ implements the shared ISO Part 3 grammar-rule and dynamic-body expansion
 without depending back on the ISO registry. This keeps the low-level syntax and
 error layers acyclic while preserving the existing `src/iso.js` exports.
 
+`src/cleanup.js` is an execution-layer sibling of the solver. It installs
+lifecycle-aware closing of protected builtin iterators from the supported API
+and CLI entry paths and registers `call_cleanup/2` and
+`setup_call_cleanup/3` for the normal EyeProlog profile. The standard-library
+layer does not import the solver back through this module, preserving the
+acyclic source graph.
+
 Program preparation follows the same pattern. `src/program.js` remains the
 `Program` facade and source/module loader. Static recursion, Datalog, WFS, and
 negation-stratification analysis is isolated in `src/program-analysis.js`,
@@ -5167,6 +5174,18 @@ for example malformed input or an unavailable required resource. ISO
 instantiation, type, domain, permission, representation, and evaluation errors
 follow this same exception path.
 
+Normal EyeProlog also provides `call_cleanup(Goal, Cleanup)` and
+`setup_call_cleanup(Setup, Goal, Cleanup)`. Cleanup is run exactly once when the
+protected search completes deterministically, is exhausted, is cut or otherwise
+pruned, top-level answer enumeration is abandoned, or an exception unwinds the
+search. `setup_call_cleanup/3` runs Setup once and installs Cleanup only after
+Setup succeeds. On cut or ordinary pruning Cleanup sees the current Goal
+bindings; on exception unwind the Goal bindings have been removed and Cleanup
+sees the Setup environment. Cleanup failure is ignored, and an exception already
+being propagated takes precedence over a cleanup exception. Nested cleanups run
+inside-out. These two controls are EyeProlog extensions and are absent from
+`--iso-strict`.
+
 Collection also makes search boundaries explicit. `findall/3` returns one list
 and existentially closes variables that occur only in its goal. `bagof/3`
 instead creates a group for each binding of a free variable and fails when
@@ -5372,13 +5391,21 @@ application code.
 
 ```eyeprolog
 write_event(Path, Event) :-
-  open(Path, write, Stream, [type(text)]),
-  write_canonical(Stream, Event),
-  put_char(Stream, '.'),
-  nl(Stream),
-  close(Stream).
+  setup_call_cleanup(
+    open(Path, write, Stream, [type(text)]),
+    ( write_canonical(Stream, Event),
+      put_char(Stream, '.'),
+      nl(Stream)
+    ),
+    close(Stream)
+  ).
 ```
 
+In normal mode, `setup_call_cleanup/3` is the preferred lifecycle boundary for
+resources such as streams: `close(Stream)` still runs if the protected work
+fails, throws, is cut, or its remaining alternatives are abandoned. Strict ISO
+mode does not provide this EyeProlog extension.
+
 The period is essential when another Prolog processor will read the result as
 a term. `write/1-2` uses readable conventional syntax, `writeq/1-2` quotes
 where needed, and `write_canonical/1-2` exposes canonical structure. Dotted
@@ -5586,8 +5613,10 @@ negation.
 
 EyeProlog supports cut, operator declarations, dynamic database updates, grouped
 solutions, exceptions, flags, initialization and inclusion directives, and
-standard stream and term I/O. ISO Part 2 modules and Part 3 definite clause
-grammars complement this Part 1 core.
+standard stream and term I/O. Normal mode additionally provides lifecycle-aware
+`call_cleanup/2` and `setup_call_cleanup/3`; these cleanup controls are
+EyeProlog extensions and are excluded by `--iso-strict`. ISO Part 2 modules and
+Part 3 definite clause grammars complement this Part 1 core.
 
 ### ISO Part 2 modules
 
@@ -5838,8 +5867,7 @@ collision because other Prolog systems commonly reject it while loading.
 `;/2` recognizes an `->/2` term on its left and implements the ISO
 if-then-else commitment described above. Cuts and committed conditions are
 operational controls; use ordinary relations when all alternatives should
-remain observable.
-
+remain observable. 
 ### Definite clause grammar processing
 
 | Predicate and principal call | Behavior |
@@ -6142,6 +6170,10 @@ The JavaScript `ioOptions.input` and `ioOptions.write` hooks connect standard
 streams to an embedder. File-backed streams use synchronous lifecycle semantics
 so side effects occur in Prolog execution order.
 
+### Normal-mode cleanup controls
+
+`call_cleanup/2` and `setup_call_cleanup/3` are normal EyeProlog runtime extensions rather than members of the isolated ISO builtin registry. They protect a goal across deterministic completion, exhaustion, cut, top-level abandonment, and exception unwinding, running Cleanup exactly once. `setup_call_cleanup/3` runs Setup once and installs Cleanup only after Setup succeeds. Nested cleanups run inside-out, and strict ISO mode does not provide either predicate.
+
 ### The EyeProlog library
 
 EyeProlog exposes **128 library predicate indicators** in addition to the 129
@@ -6665,8 +6697,10 @@ 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
+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
 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
@@ -7510,7 +7544,8 @@ Corrigenda 1–3. Corrigendum 2 additions—including `subsumes_term/2`,
 `acyclic_term/1`, `sort/2`, `keysort/2`, `term_variables/2`, `retractall/1`,
 and `call/2-8`—remain part of that strict baseline. Part 2 modules, Part 3 DCG
 expansion/`phrase/2-3`, quads, EyeProlog libraries, the `occurs_check` flag,
-and automatic tabling are outside that Part 1 strict surface.
+automatic tabling, `call_cleanup/2`, and `setup_call_cleanup/3` are outside
+that Part 1 strict surface.
 
 This release establishes the strict-mode mechanism required for the ongoing
 conformance audit; it does **not** yet claim that every processor requirement
@@ -7739,6 +7774,14 @@ 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.
+
+**Cleanup.** A protected finalization goal installed by normal-mode
+`call_cleanup/2` or `setup_call_cleanup/3`. It runs exactly once when the
+protected search ends, is pruned or abandoned, or unwinds through an exception.
+
 **Closed-world assumption.** The decision to treat failure to derive a
 sufficiently scoped claim as evidence for its absence. EyeProlog's `\+/1` performs
 negation as failure; the modeler is responsible for justifying the scope.

package/why-eyeprolog.md

@@ -36,6 +36,7 @@ keeps a narrow architecture:
 - the ISO built-in registry;
 - lean portable ISO Part 2 library modules;
 - ISO Part 3 definite clause grammars and `phrase/2-3`;
+- lifecycle-aware `call_cleanup/2` and `setup_call_cleanup/3` in normal mode;
 - optional proof explanations; and
 - the same implementation in Node.js and the browser.
 
@@ -48,11 +49,13 @@ their ISO definitions directly.
 The implementation follows the same compactness rule. JavaScript runtime
 modules stay flat under `src/`: `program.js` and `iso.js` remain stable facade
 modules, while static program analysis, clause indexing, arithmetic evaluation,
-and processor error types are factored into focused sibling files. The
-execution fast paths remain direct code in `solver.js`; source cleanup is not
-allowed to add dispatch or abstraction overhead merely to make that file
-smaller. `src/ARCHITECTURE.md` records these boundaries and an automated test
-rejects JavaScript import cycles.
+processor error types, and cleanup lifecycle handling are factored into focused
+sibling files. `cleanup.js` closes protected builtin iterators when search is
+committed, abandoned, or unwound without making `solver.js` depend on the
+language registry. The execution fast paths remain direct code in `solver.js`;
+source cleanup is not allowed to add dispatch or abstraction overhead merely to
+make that file smaller. `src/ARCHITECTURE.md` records these boundaries and an
+automated test rejects JavaScript import cycles.
 
 
 ## Why keep well-founded negation explicit?
@@ -77,6 +80,16 @@ checked `examples/dcg-expression-language.pl` program shows the declarative side
 of that design: one grammar builds precedence-aware syntax trees and another
 generates minimally parenthesized token sequences back from them.
 
+## Why cleanup follows search lifecycle?
+
+A Prolog resource lifetime is tied to search, not just to ordinary function
+return. A protected goal can finish, fail, be cut, be abandoned at the top
+level while alternatives remain, or unwind through an exception. Normal-mode
+`call_cleanup/2` and `setup_call_cleanup/3` make those exits explicit and run
+Cleanup exactly once. This also preserves demand-driven answer interaction: the
+top level need not execute a successor merely to decide whether a choicepoint
+exists. Strict ISO mode leaves these predicates out.
+
 ## Why proofs?
 
 An answer says that a goal succeeded. A proof records one successful route