eyeprolog 1.3.38 → 1.3.40

package/README.md

@@ -84,7 +84,18 @@ use any normal Prolog term syntax; EyeProlog only requires it to be ground when
 the quad is checked. A non-ground label is a quad failure, not a source syntax
 error, and later quads still run. When a query has multiple indented answer
 descriptions, each description is checked and counted independently, so one
-failed expectation does not prevent the later ones from running.
+failed expectation does not prevent the later ones from running. Following the
+Trealla quad convention, `sto` declares that the query is subject to occurs-check.
+EyeProlog now uses an occurs-check event observed during the query's ordinary
+execution as positive STO evidence, and rejects `sto` when a finite execution
+completes without such an event (for example `?- true. sto.`). If execution is
+cut short by a search/resource boundary, the STO claim remains conservatively
+unverified rather than being guessed.
+For nontermination expectations, `loops` is kept distinct from resource
+exhaustion: structural loop evidence may satisfy `loops`, while a bounded
+search that cannot establish the requested answer sequence is reported as
+`UNDECIDED`. In CLI quad mode, failures use exit status `1`; if there are no
+failures but at least one undecided quad, the exit status is `2`.
 
 ## Tabling and well-founded negation
 

package/examples/book/README.md

@@ -248,3 +248,4 @@ npm run generate
 ## Chapter 40: Running EyeProlog: command line and corpus
 
 - [01-color.pl](chapter-40/01-color.pl) — Embedded quad tests
+- [02-program.pl](chapter-40/02-program.pl)

package/examples/book/chapter-40/02-program.pl

@@ -0,0 +1,5 @@
+% From The Art of EyeProlog, Chapter 40.
+inf :- inf, inf.
+
+?- inf.
+   loops.

package/package.json

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

package/src/quads.js

@@ -36,11 +36,15 @@ export function runQuads(source, options = {}) {
   const results = [];
   const lines = [];
   for (const quad of quads) {
+    // `sto` declares a property of the query, not merely of the leaf in which
+    // the annotation happens to be written. Preserve that context while each
+    // answer description is still checked independently.
+    const context = { declaresSto: quad.answers.some(descriptionDeclaresSto) };
     // Every indented answer description is an independent portable quad test.
     // Re-run the query for each description so a failed expectation does not
     // prevent later expectations for the same query from being checked.
     for (const description of quad.answers) {
-      const result = checkQuadDescription(program, quad, description, options);
+      const result = checkQuadDescription(program, quad, description, options, context);
       results.push(result);
       if (!result.ok) lines.push(formatFailure(program, quad, result, description));
     }
@@ -53,14 +57,14 @@ export function runQuads(source, options = {}) {
   return { stdout: lines.join(''), total: results.length, passed, failed, undecided, results };
 }
 
-function checkQuadDescription(program, quad, description, options) {
+function checkQuadDescription(program, quad, description, options, context) {
   if (quad.id != null && !termIsGround(quad.id, new Env())) {
     return { ok: false, kind: 'bad_identifier', expected: quad.id };
   }
-  return checkDescription(program, quad, description, options);
+  return checkDescription(program, quad, description, options, context);
 }
 
-function checkDescription(program, quad, description, options) {
+function checkDescription(program, quad, description, options, context) {
   const alternatives = splitOperator(description, '|');
   // Probe an explicitly accepted nontermination outcome before alternatives
   // that would run the same query without a bound.
@@ -73,7 +77,7 @@ function checkDescription(program, quad, description, options) {
   let unsupported = null;
   let undecided = null;
   for (const alternative of ordered) {
-    const checked = checkAlternative(program, quad, alternative, options);
+    const checked = checkAlternative(program, quad, alternative, options, context);
     if (checked.ok) return checked;
     if (checked.kind === 'unsupported') unsupported ??= checked;
     if (checked.kind === 'undecided') undecided ??= checked;
@@ -81,9 +85,9 @@ function checkDescription(program, quad, description, options) {
   return unsupported ?? undecided ?? { ok: false, kind: 'failed', expected: description };
 }
 
-function checkAlternative(program, quad, alternative, options) {
+function checkAlternative(program, quad, alternative, options, context) {
   const leaves = splitOperator(alternative, ';').map(describeLeaf);
-  if (leaves.some((leaf) => leaf.sto)) return { ok: true };
+  const requiresSto = leaves.some((leaf) => leaf.sto);
   const unsupported = leaves.find((leaf) => leaf.unsupported != null)?.unsupported;
   if (unsupported != null) {
     return { ok: false, kind: 'unsupported', expected: unsupported };
@@ -103,6 +107,18 @@ function checkAlternative(program, quad, alternative, options) {
     detectLoops: leaves.some((leaf) => leaf.loops),
   });
 
+  if (requiresSto) {
+    // Trealla currently treats the answer part of an `sto`-annotated leaf as
+    // implementation-dependent and skips it. EyeProlog can strengthen that
+    // conservatively: an observed occurs-check event proves the STO claim, and
+    // a naturally completed finite execution without one disproves it. When
+    // execution was cut short by a search/resource boundary, leave the claim
+    // unchecked rather than pretending to have proved NSTO.
+    if (actual.stoObserved) return { ok: true };
+    if (actual.nstoObserved) return { ok: false };
+    return { ok: true };
+  }
+
   if (inputSpecs.length > 0) {
     const leaf = leaves[0];
     const matches = actual.inputPosition === input.length && matchLeaf(program, quad.query, leaf, actual, 0);
@@ -114,7 +130,12 @@ function checkAlternative(program, quad, alternative, options) {
   for (const leaf of leaves) {
     if (leaf.more && !leaf.hasExpectation) return { ok: true };
     const matches = matchLeaf(program, quad.query, leaf, actual, position);
-    if (leaf.unexpected ? matches : !matches) {
+    // Once a quad explicitly declares the query STO and this execution has
+    // observed an occurs-check event, an unannotated `unexpected` leaf cannot
+    // portably outlaw the implementation's chosen STO outcome. This is the
+    // case behind issue #60's `false, unexpected` example.
+    const stoPermitsUnexpected = context.declaresSto && actual.stoObserved && leaf.unexpected && !leaf.sto;
+    if (!stoPermitsUnexpected && (leaf.unexpected ? matches : !matches)) {
       if (actual.undecided && leafNeedsMoreSearch(leaf, actual, position)) {
         return undecidedResult(actual, alternative);
       }
@@ -245,19 +266,28 @@ function executeQuery(program, query, input, maxSolutions, options) {
   const solutions = [];
   let error = null;
   let tailOutput = '';
+  let complete = false;
+  let resourceInterrupted = false;
+  let iterator = null;
   try {
-    const iterator = solver.solve([query], new Env(), 0);
+    iterator = solver.solve([query], new Env(), 0);
     while (solutions.length < maxSolutions) {
       pendingOutput = '';
       const result = iterator.next();
       if (result.done) {
         tailOutput += pendingOutput;
+        complete = true;
         break;
       }
       solutions.push({ env: result.value, output: pendingOutput });
     }
   } catch (caught) {
     error = { term: errorTerm(caught), output: pendingOutput };
+    resourceInterrupted = caught?.name === 'PrologError' &&
+      String(caught.formal ?? '').startsWith('resource_error(');
+    complete = true;
+  } finally {
+    if (!complete) iterator?.return?.();
   }
   const inputPosition = solver.io.resolve('user_input')?.position ?? 0;
   const bounded = solver.depthLimitExceeded || solver.inferenceLimitExceeded;
@@ -267,6 +297,10 @@ function executeQuery(program, query, input, maxSolutions, options) {
     error,
     tailOutput,
     inputPosition,
+    complete,
+    stoObserved: solver.occursCheckObserved,
+    nstoObserved: complete && !solver.occursCheckObserved && !solver.recursionCycleDetected &&
+      !bounded && !resourceInterrupted,
     // 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.
@@ -294,6 +328,11 @@ function matchLeaf(program, query, leaf, actual, position) {
   return substitutionMatches(query, leaf.bindings, solution.env);
 }
 
+function descriptionDeclaresSto(description) {
+  return splitOperator(description, '|').some((alternative) =>
+    splitOperator(alternative, ';').some((term) => describeLeaf(term).sto));
+}
+
 function alternativeDescribesLoop(alternative) {
   return splitOperator(alternative, ';').some((term) => describeLeaf(term).loops);
 }

package/src/solver.js

@@ -88,7 +88,13 @@ export class Solver {
         if (!ISO_CORE_FLAG_NAMES.has(name)) this.prologFlags.delete(name);
       }
     }
+    // Record a concrete occurs-check event even when the configured action is
+    // finite-tree failure rather than an exception. Quad `sto` checks can then
+    // use the query's real execution as evidence without running it a second
+    // time (which could repeat side effects).
+    this.occursCheckObserved = false;
     this.occursCheckHandler = (left, right, env) => {
+      this.occursCheckObserved = true;
       if (this.prologFlags.get('occurs_check')?.value?.name === 'error') {
         raiseOccursCheckError(left, right, env);
       }
@@ -266,6 +272,7 @@ export class Solver {
     this.depthLimitExceeded ||= child.depthLimitExceeded;
     this.inferenceLimitExceeded ||= child.inferenceLimitExceeded;
     this.recursionCycleDetected ||= child.recursionCycleDetected;
+    this.occursCheckObserved ||= child.occursCheckObserved;
     for (const [key, value] of Object.entries(child.stats)) {
       if (key === 'max_depth' || key === 'max_goal_count') {
         this.stats[key] = Math.max(this.stats[key] ?? 0, value ?? 0);

package/test/run-regression.mjs

@@ -1356,6 +1356,33 @@ c4 ?- call((!;1)).
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'quad sto uses observed occurs-check evidence instead of unconditional acceptance (issue #60)',
+      run: () => {
+        const sto = publicApi.runQuads(String.raw`33
+?- X = s(X).
+   X = ..., unexpected.
+   false, unexpected.
+   sto, false
+|  sto, true.
+`);
+        assertEqual(sto.total, 3, 'STO description total');
+        assertEqual(sto.passed, 3, 'STO descriptions passed');
+        assertEqual(sto.failed, 0, 'STO descriptions failed');
+        assertEqual(sto.undecided, 0, 'STO descriptions undecided');
+        assertEqual(sto.stdout, 'quads: 3 run, 3 passed, 0 failed.\n', 'STO report');
+
+        const nsto = publicApi.runQuads(String.raw`34
+?- true.
+   sto.
+`);
+        assertEqual(nsto.total, 1, 'NSTO description total');
+        assertEqual(nsto.passed, 0, 'NSTO description passed');
+        assertEqual(nsto.failed, 1, 'NSTO description failed');
+        assertEqual(nsto.undecided, 0, 'NSTO description undecided');
+        assertIncludes(nsto.stdout, 'quads: FAILED 34, <input>:1', 'NSTO diagnostic');
+      },
+    },
     {
       name: 'outputs/1 accepts DCG bodies over captured characters (issue #59)',
       run: () => {

package/the-art-of-eyeprolog.md

@@ -6896,16 +6896,67 @@ 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.
+The advanced stream annotations `peeks/1` and `waits`, and the unordered
+`other_answer_sequence` annotation, are not executed by the current runner.
+
+#### STO, loops, and undecided quad results
+
+Following Trealla's quad convention, `sto` declares that a query is subject to
+occurs-check. EyeProlog checks this conservatively rather than attempting a
+complete STO/NSTO decision procedure. During the query's ordinary execution,
+the finite-tree unifier records a concrete occurs-check event as positive STO
+evidence; the query is not run a second time merely to probe STO-ness. A finite
+execution that completes naturally without such an event disproves `sto`, while
+a search or resource boundary leaves the declaration conservatively unchecked.
+The answer portion of an `sto`-annotated leaf remains implementation-dependent
+and is therefore not compared.
+
+For example, the cyclic binding in the first query provides positive STO
+evidence, whereas the second query is finite and cannot be STO:
+
+```eyeprolog
+?- X = s(X).
+   X = ..., unexpected.
+   false, unexpected.
+   sto, false
+|  sto, true.
+
+?- true.
+   sto.                  % fails: no STO evidence
+```
+
+When a quad declares STO and the execution observes an occurs-check event, an
+unannotated `unexpected` leaf does not reject the implementation-dependent
+finite-tree outcome. This is partial STO detection only: EyeProlog makes a
+definite statement where execution provides definite evidence and otherwise
+does not guess.
+
+`loops` is kept distinct from merely exhausting the quad runner's resources.
+EyeProlog accepts structural nontermination evidence such as an active-variant
+recursion cycle, with the loop depth/inference bounds as a bounded fallback:
+
+```eyeprolog
+inf :- inf, inf.
+
+?- inf.
+   loops.
+```
+
+Ordinary answer descriptions also have a finite inference budget (100000 by
+default). Exhausting that budget does **not** establish `loops` and does not
+turn an unfinished search into `false`; instead the description is reported as
+`UNDECIDED`, for example:
+
+```text
+quads: UNDECIDED expensive_case, program.pl:12
+   undecided: inference limit reached.
+```
+
+Thus quad execution has three useful outcomes: passed, failed, and undecided.
+When there are no failures but at least one undecided description, the CLI exits
+with status `2`. The JavaScript API may override the ordinary search budget with
+`quadMaxInferences`; `loopMaxDepth` and `loopMaxInferences` control the explicit
+`loops` probe.
 
 The JavaScript API exposes the same operation without process I/O: