eyeprolog 1.3.36 → 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).
@@ -312,4 +331,10 @@ The GitHub test workflow runs the complete suite and an npm package dry-run on
 both the minimum supported Node.js 18 release line and Node.js 24. Publishing
 repeats those release checks before uploading the package.
 
+The runtime JavaScript modules stay flat under `src/`; the existing `src/lib/`
+directory contains the portable Prolog library modules. See
+[`src/ARCHITECTURE.md`](src/ARCHITECTURE.md) for the source-layer boundaries,
+facade modules, dependency rule, and the requirement that architectural cleanup
+must preserve the existing solver hot paths and benchmark performance.
+
 EyeProlog is released under the [MIT License](LICENSE.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.36",
+  "version": "1.3.38",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",
@@ -64,6 +64,7 @@
     "report:wg17": "node tools/report-wg17-syntax-coverage.mjs",
     "report:wg17-syntax": "node tools/report-wg17-syntax-coverage.mjs",
     "preversion": "npm test && node test/run-conformance-report.mjs conformance-report.md",
-    "postversion": "git push origin HEAD --follow-tags"
+    "postversion": "git push origin HEAD --follow-tags",
+    "test:architecture": "node test/run-architecture.mjs"
   }
 }

package/src/ARCHITECTURE.md

@@ -0,0 +1,49 @@
+# EyeProlog source architecture
+
+The runtime is intentionally layered so semantic modules do not depend back on
+higher-level frontends.
+
+## Layers
+
+1. **Kernel representation and syntax** — `term.js`, `number-value.js`,
+   `syntax-scan.js`, `parser.js`, `write.js`, `errors.js`.
+2. **Program preparation** — `program.js` plus `program-analysis.js` and
+   `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`, `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`,
+   `explain.js`, and the playground worker.
+
+`iso.js` and `program.js` remain facade modules for their existing exports, so
+this refactor does not change the public JavaScript API.
+
+## Dependency rule
+
+Dependencies should point down or sideways within a layer, never back from a
+kernel component into the ISO registry or a frontend.  In particular,
+`errors.js` owns `PrologError` and `HaltSignal`; DCG expansion can therefore
+report processor errors without importing `iso.js` and creating an
+`iso.js <-> dcg.js` cycle.
+
+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/`. 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
+
+Architecture changes must not add runtime strategy objects, callbacks, or
+extra dispatch in solver hot paths.  Existing scalar/indexed solver paths stay
+as direct function calls.  Candidate indexing is separated physically but
+retains the same data structures and selection functions.
+
+Large solver fast paths deliberately remain co-located in `solver.js` until a
+split can demonstrate benchmark parity.  A cleaner file layout is not worth a
+runtime regression.

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/dcg.js

@@ -5,7 +5,7 @@ import {
   ATOM, COMPOUND, VAR, Env, atom, compactListLength, compound, deref, emptyList,
   flattenConjunction, variable,
 } from './term.js';
-import { PrologError } from './iso.js';
+import { PrologError } from './errors.js';
 
 let dcgFresh = 0;
 

package/src/errors.js

@@ -0,0 +1,23 @@
+// Runtime control and ISO processor error types shared across subsystems.
+// Keep these independent of the ISO builtin registry so syntax, DCG, program,
+// and solver layers can report Prolog errors without importing the whole ISO
+// implementation (and without creating semantic-layer import cycles).
+import { termToString } from './term.js';
+
+export class PrologError extends Error {
+  constructor(formal, culprit = null) {
+    const detail = culprit == null ? formal : `${formal}, ${termToString(culprit)}`;
+    super(`error(${detail})`);
+    this.name = 'PrologError';
+    this.formal = formal;
+    this.culprit = culprit;
+  }
+}
+
+export class HaltSignal extends Error {
+  constructor(code = 0) {
+    super(`halt(${code})`);
+    this.name = 'HaltSignal';
+    this.code = code;
+  }
+}

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;