eyeprolog 1.5.95 → 1.5.97

package/README.md

@@ -96,8 +96,7 @@ npm test
 The npm command list is deliberately small:
 
 - `npm test` (or `npm run test`): run the release gate, including live upstream conformity checks (WG17 syntax among them).
-- `npm run generate`: rebuild generated library and book files.
 
-Use `npm test -- --offline` for a network-free local pass (this also skips the live-discovered WG17 syntax check, since it has no offline snapshot). Focused checks remain available directly, for example `node test/run-regression.mjs docs`; see [test runners](test/README.md). The automatic version hooks still run the release gate, refresh and stage conformance reports, and push the release. Detailed upstream report maintenance is documented in the [conformance guide](test/conformance/README.md).
+Use `npm test -- --offline` for a network-free local pass (this also skips the live-discovered WG17 syntax check, since it has no offline snapshot). Focused checks remain available directly, for example `node test/run-regression.mjs docs`; see [test runners](test/README.md). The automatic version hooks rebuild generated library and book files, run the release gate, refresh and stage conformance reports, and push the release. Detailed upstream report maintenance is documented in the [conformance guide](test/conformance/README.md).
 
 EyeProlog is released under the [MIT License](LICENSE.md).

package/examples/book/README.md

@@ -8,9 +8,11 @@ not extracted.
 Regenerate them from the repository root with:
 
 ```sh
-npm run generate
+node tools/extract-book-examples.mjs
 ```
 
+`npm version` regenerates this directory automatically as part of its release checks.
+
 ## Chapter 1: A program is a little theory
 
 - [01-parent.pl](chapter-01/01-parent.pl)

package/examples/declarative-fault-localization.pl

@@ -0,0 +1,36 @@
+% Declarative fault localization: when a predicate returns a wrong answer,
+% test it again on a strictly smaller sub-goal that a correct version would
+% still have to get right. Each step either still shows the wrong answer
+% (the fault is at or before this depth -- keep shrinking) or the sub-goal
+% is fine (the fault must be in what combines that correct sub-result with
+% the rest). No stack trace or print statement is needed: only whether each
+% successively smaller call is itself correct.
+%
+% buggy_list_max/2 has its comparison branches swapped in the recursive
+% clause (a classic off-by-one-style slip), so it sometimes reports the
+% smaller of two candidates as the maximum.
+buggy_list_max([X], X).
+buggy_list_max([X|Xs], Max) :-
+    buggy_list_max(Xs, Max0),
+    ( X > Max0 -> Max = Max0 ; Max = X ).
+
+fixed_list_max([X], X).
+fixed_list_max([X|Xs], Max) :-
+    fixed_list_max(Xs, Max0),
+    ( X > Max0 -> Max = X ; Max = Max0 ).
+
+%% goal: answer(X0, X1, X2, X3)
+
+answer(WholeListWrongAnswer, TwoElementSublistAlreadyWrong, BaseCaseIsCorrect, FixedAnswer) :-
+    % The full query already gives the wrong maximum...
+    buggy_list_max([1, 5, 3], WholeListWrongAnswer),
+    % ...and so, it turns out, does the very first recursive step alone:
+    % this two-element call is already wrong on its own, which localizes
+    % the fault to the recursive clause itself, not to how its result
+    % later combines with the outer 1.
+    buggy_list_max([5, 3], TwoElementSublistAlreadyWrong),
+    % Shrinking one step further reaches the base case, which is correct
+    % (trivially): the fault cannot be shrunk past this depth.
+    buggy_list_max([3], BaseCaseIsCorrect),
+    % Swapping the branches back gives the right answer throughout.
+    fixed_list_max([1, 5, 3], FixedAnswer).

package/examples/knights-tour-warnsdorff.pl

@@ -0,0 +1,46 @@
+% Knight's tour via Warnsdorff's rule: at each step, move to the reachable
+% unvisited square with the fewest onward moves of its own. Preferring the
+% most constrained square first empties the "hard" corners early, while
+% plenty of freedom remains to reach them -- so a full tour is usually found
+% without ever needing to backtrack. keysort/2 on Degree-Square pairs picks
+% the least-constrained-first candidate; the cut in tour_/4's base case
+% commits to the tour once every square is visited.
+:- use_module(library(lists)).
+
+board_size(5).
+
+knight_move(p(X0, Y0), p(X, Y)) :-
+    member(d(DX, DY), [
+        d(1, 2), d(2, 1), d(-1, 2), d(-2, 1),
+        d(1, -2), d(2, -1), d(-1, -2), d(-2, -1)
+    ]),
+    X is X0 + DX, Y is Y0 + DY,
+    board_size(N),
+    X >= 1, X =< N, Y >= 1, Y =< N.
+
+degree(Square, Visited, Degree) :-
+    findall(Next, (knight_move(Square, Next), \+ member(Next, Visited)), Nexts),
+    length(Nexts, Degree).
+
+tour_(_, Visited, SquareCount, Visited) :- length(Visited, SquareCount), !.
+tour_(Current, Visited, SquareCount, Tour) :-
+    findall(Degree-Next, (
+        knight_move(Current, Next),
+        \+ member(Next, Visited),
+        degree(Next, Visited, Degree)
+    ), Candidates),
+    Candidates \= [],
+    keysort(Candidates, [_-Best | _]),
+    tour_(Best, [Best | Visited], SquareCount, Tour).
+
+knights_tour(Start, Tour) :-
+    board_size(N),
+    SquareCount is N * N,
+    tour_(Start, [Start], SquareCount, ReverseTour),
+    reverse(ReverseTour, Tour).
+
+%% goal: answer(X0, X1)
+
+answer(SquareCount, Tour) :-
+    knights_tour(p(1, 1), Tour),
+    length(Tour, SquareCount).

package/examples/output/declarative-fault-localization.pl

@@ -0,0 +1 @@
+answer(1, 3, 3, 5).

package/examples/output/knights-tour-warnsdorff.pl

@@ -0,0 +1 @@
+answer(25, [p(1, 1), p(2, 3), p(1, 5), p(3, 4), p(5, 5), p(4, 3), p(5, 1), p(3, 2), p(4, 4), p(2, 5), p(1, 3), p(2, 1), p(4, 2), p(5, 4), p(3, 5), p(1, 4), p(2, 2), p(4, 1), p(5, 3), p(4, 5), p(2, 4), p(1, 2), p(3, 3), p(5, 2), p(3, 1)]).

package/examples/output/reified-conditionals.pl

@@ -0,0 +1 @@
+answer([2, 4, 6, 8], [1, 3, 5, 7], even, odd).

package/examples/output/universal-vs-existential-termination.pl

@@ -0,0 +1 @@
+answer([[] - "abc", "a" - "bc", "ab" - "c", "abc" - []], 4, true).

package/examples/output/vanilla-meta-interpreter.pl

@@ -0,0 +1 @@
+answer([ann, pat], [jim]).

package/examples/reified-conditionals.pl

@@ -0,0 +1,20 @@
+% Reified conditionals: a "reified" predicate turns a condition into an
+% ordinary term (true or false) that a caller receives as data, instead of
+% committing to one branch itself the way (->)/2 does. if_/3 then dispatches
+% on that term. The payoff is that reusable control predicates like
+% tfilter/3 and tpartition/4 can be built once, on top of if_/3, and applied
+% to any reified condition -- filtering and partitioning are not each
+% reimplemented per predicate the way they would be with hand-written
+% (->)/2 chains.
+:- use_module(library(reif)).
+
+even_t(N, true) :- 0 is N mod 2, !.
+even_t(_, false).
+
+%% goal: answer(X0, X1, X2, X3)
+
+answer(Evens, Odds, First, Second) :-
+    tfilter(even_t, [1, 2, 3, 4, 5, 6, 7, 8], Evens),
+    tpartition(even_t, [1, 2, 3, 4, 5, 6, 7, 8], _, Odds),
+    if_(even_t(4), First = even, First = odd),
+    if_(even_t(7), Second = even, Second = odd).

package/examples/universal-vs-existential-termination.pl

@@ -0,0 +1,29 @@
+% Universal vs. existential termination: a query terminates *existentially*
+% if finding one answer (or failing outright) takes finite time; it
+% terminates *universally* only if exhausting every answer does. The two
+% can come apart for the very same predicate, depending only on how it is
+% called -- append/3 is the classic case.
+%
+% append(X, Y, [a,b,c]) has exactly as many solutions as there are ways to
+% split a 3-element list, so asking for all of them (findall/3) terminates:
+% this call terminates universally.
+%
+% append(X, Y, Z) with Z left unbound has infinitely many solutions (Z can
+% be a list of any length), so the first one is still found immediately
+% (existential termination holds), but findall/3 over it would never
+% return: this call terminates existentially but not universally. once/1
+% below deliberately stops after that first solution so this file's own
+% checked output stays finite -- do not replace it with findall/3.
+
+%% goal: answer(X0, X1, X2)
+
+answer(AllSplitsOfBoundList, SplitCount, FoundFirstSplitOfUnboundList) :-
+    findall(X - Y, append(X, Y, [a, b, c]), AllSplitsOfBoundList),
+    length(AllSplitsOfBoundList, SplitCount),
+    % X2 comes out ground ([]), but Y2 and Z2 stay unbound (merely aliased
+    % to each other) -- append/3's first solution names no particular
+    % list at all, only that Y and Z must coincide. Reporting that
+    % once/1 succeeded is itself the point: existential termination only
+    % promises a first answer exists, not that it pins everything down.
+    once((append(X2, _Y2, _Z2), X2 == [])),
+    FoundFirstSplitOfUnboundList = true.

package/examples/vanilla-meta-interpreter.pl

@@ -0,0 +1,30 @@
+% A vanilla meta-interpreter: solve/1 mirrors the ordinary Prolog resolution
+% rule at the object level, using clause/2 to fetch a matching clause and
+% conjunction to solve its body. It shows that "how Prolog executes a goal"
+% is itself expressible as an ordinary Prolog relation, not a hidden
+% mechanism -- the classic starting point for building custom reasoners
+% (tracers, proof recorders, alternative search strategies) on top of plain
+% Prolog. clause/2 only inspects dynamic procedures, hence the declarations.
+:- dynamic(parent/2).
+:- dynamic(grandparent/2).
+:- dynamic(great_grandparent/2).
+
+solve(true) :- !.
+solve((A, B)) :- !, solve(A), solve(B).
+solve(Goal) :-
+    clause(Goal, Body),
+    solve(Body).
+
+parent(tom, bob).
+parent(bob, ann).
+parent(bob, pat).
+parent(pat, jim).
+
+grandparent(X, Z) :- parent(X, Y), parent(Y, Z).
+great_grandparent(X, Z) :- parent(X, Y), grandparent(Y, Z).
+
+%% goal: answer(X0, X1)
+
+answer(Grandchildren, GreatGrandchildren) :-
+    findall(X, solve(grandparent(tom, X)), Grandchildren),
+    findall(X, solve(great_grandparent(tom, X)), GreatGrandchildren).

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.5.95",
+  "version": "1.5.97",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",
@@ -46,8 +46,7 @@
   },
   "scripts": {
     "test": "node test/run-all.mjs",
-    "generate": "node tools/generate-library-autoload-index.mjs && node tools/generate-predicate-reference.mjs && node tools/extract-book-examples.mjs",
-    "preversion": "npm test && node test/run-neumerkel.mjs --cached --update-report && node test/run-conformance-report.mjs conformance-report.md && git add test/conformance/NEUMERKEL-LATEST.md conformance-report.md",
+    "preversion": "node tools/generate-library-autoload-index.mjs && node tools/generate-predicate-reference.mjs && node tools/extract-book-examples.mjs && npm test && node test/run-neumerkel.mjs --cached --update-report && node test/run-conformance-report.mjs conformance-report.md && git add src/library-autoload-index.js the-art-of-eyeprolog.md examples/book test/conformance/NEUMERKEL-LATEST.md conformance-report.md",
     "postversion": "git push origin HEAD --follow-tags"
   }
 }

package/playground.html

@@ -493,6 +493,7 @@
           "data-negotiation",
           "dcg-command-parser",
           "dcg-expression-language",
+          "declarative-fault-localization",
           "deep-taxonomy-10",
           "deep-taxonomy-100",
           "deep-taxonomy-1000",
@@ -571,6 +572,7 @@
           "job-shop-scheduling",
           "json",
           "knapsack-optimization",
+          "knights-tour-warnsdorff",
           "knowledge-engineering-alignment-flow",
           "knuth-bendix-completion",
           "language",
@@ -627,6 +629,7 @@
           "rdf12-trig-triple-term",
           "rdf12-triple-term",
           "register-allocation",
+          "reified-conditionals",
           "relational-cube-lookup",
           "reusable-builtins",
           "riemann-hypothesis",
@@ -656,7 +659,9 @@
           "truth-maintenance-system",
           "turing",
           "type-inference",
+          "universal-vs-existential-termination",
           "uuid",
+          "vanilla-meta-interpreter",
           "vector-similarity",
           "vulnerability-impact",
           "web-names",

package/test/regression/cases-documentation-sync.mjs

@@ -629,7 +629,7 @@ ${profile}`;
         const publishIndex = publishWorkflow.indexOf('run: npm publish');
         assertEqual(testIndex >= 0 && testIndex < publishIndex, true, 'publish workflow test gate');
         assertEqual(packIndex >= 0 && packIndex < publishIndex, true, 'publish workflow package gate');
-        assertArrayEqual(Object.keys(pkg.scripts).sort(), ['generate', 'postversion', 'preversion', 'test'], 'small npm command surface');
+        assertArrayEqual(Object.keys(pkg.scripts).sort(), ['postversion', 'preversion', 'test'], 'small npm command surface');
         assertEqual(pkg.scripts.test, 'node test/run-all.mjs', 'full release gate');
         const runner = fs.readFileSync(path.join(packageRoot, 'test', 'run-all.mjs'), 'utf8');
         assertIncludes(runner, 'runOpenRuleBenchChecks(reporter)', 'OpenRuleBench remains in release gate');

package/test/run-neumerkel-tests.mjs

@@ -126,12 +126,18 @@ export function runNeumerkelHarnessTests(reporter = new TestReporter()) {
     const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
     const scripts = pkg.scripts ?? {};
     const releaseSteps = String(scripts.preversion ?? '').split(' && ');
-    if (releaseSteps[0] !== 'npm test' || releaseSteps[1] !== 'node test/run-neumerkel.mjs --cached --update-report') {
+    if (releaseSteps[0] !== 'node tools/generate-library-autoload-index.mjs' ||
+        releaseSteps[1] !== 'node tools/generate-predicate-reference.mjs' ||
+        releaseSteps[2] !== 'node tools/extract-book-examples.mjs') {
+      throw new Error('preversion must regenerate the library index, predicate reference, and book examples first');
+    }
+    if (releaseSteps[3] !== 'npm test' || releaseSteps[4] !== 'node test/run-neumerkel.mjs --cached --update-report') {
       throw new Error('preversion must synchronize the tracked report from the successful npm test snapshot');
     }
-    if (releaseSteps[2] !== 'node test/run-conformance-report.mjs conformance-report.md' ||
-        releaseSteps[3] !== 'git add test/conformance/NEUMERKEL-LATEST.md conformance-report.md' || releaseSteps.length !== 4) {
-      throw new Error('preversion must generate and stage both reports without another fetch');
+    if (releaseSteps[5] !== 'node test/run-conformance-report.mjs conformance-report.md' ||
+        releaseSteps[6] !== 'git add src/library-autoload-index.js the-art-of-eyeprolog.md examples/book ' +
+          'test/conformance/NEUMERKEL-LATEST.md conformance-report.md' || releaseSteps.length !== 7) {
+      throw new Error('preversion must generate and stage the library index, book files, and both reports without another fetch');
     }
   });
 

package/the-art-of-eyeprolog.md

@@ -9934,7 +9934,7 @@ Review questions:
 </figure>
 
 The [examples directory](https://github.com/eyereasoner/eyeprolog/tree/main/examples/) is the book's executable companion. The
-top-level directory contains **229 self-contained runnable programs**. Every
+top-level directory contains **234 self-contained runnable programs**. Every
 source program has an exact answer file under
 [examples/output](https://github.com/eyereasoner/eyeprolog/tree/main/examples/output/), and **61 selected programs** have a checked
 explanation under [examples/proof](https://github.com/eyereasoner/eyeprolog/tree/main/examples/proof/). The thematic lists link every top-level program and open the program
@@ -10346,7 +10346,7 @@ hand.
 
 #### Running and extending the corpus
 
-Run all 229 normal answer goldens and the 61 selected proof goldens with:
+Run all 234 normal answer goldens and the 61 selected proof goldens with:
 
 ```sh
 node test/run-examples.mjs
@@ -10418,7 +10418,7 @@ accept texts outside the strict grammar, but it may not reinterpret an accepted
 standard case.
 
 The file-based conformance corpus contains 905 cases, including 479 focused ISO cases derived from the success, failure, mode, and error behavior in ISO/IEC 13211-1 clauses 7 and 8, Part 2 modules, and Part 3 grammar rules.
-Separate exact-output suites check 229 normal examples and 61 proof examples; all executable chapter programs are parsed and their declared goals are executed. The nine-case
+Separate exact-output suites check 234 normal examples and 61 proof examples; all executable chapter programs are parsed and their declared goals are executed. The nine-case
 playground contract suite imports the production worker, sends real reasoning
 requests through its message protocol, and crawls the served module graph for
 missing assets, bad MIME types, and static Node-only imports. `conformance-report.md` inventories the file-based conformance corpus and links to the live Neumerkel evidence, which includes the current WG17 syntax result.

package/tools/extract-book-examples.mjs

@@ -86,9 +86,11 @@ const readme = [
   'Regenerate them from the repository root with:',
   '',
   '```sh',
-  'npm run generate',
+  'node tools/extract-book-examples.mjs',
   '```',
   '',
+  '`npm version` regenerates this directory automatically as part of its release checks.',
+  '',
 ];
 
 let total = 0;

package/tools/generate-library-autoload-index.mjs

@@ -97,7 +97,7 @@ const text = `// Generated by tools/generate-library-autoload-index.mjs.\n` +
 if (process.argv.includes('--check')) {
   const current = fs.existsSync(outputFile) ? fs.readFileSync(outputFile, 'utf8') : '';
   if (current !== text) {
-    console.error(`${path.relative(root, outputFile)} is stale; run npm run generate`);
+    console.error(`${path.relative(root, outputFile)} is stale; run node tools/generate-library-autoload-index.mjs (npm version regenerates it automatically)`);
     process.exit(1);
   }
   console.log(`${path.relative(root, outputFile)} is up to date`);

package/tools/generate-predicate-reference.mjs

@@ -209,7 +209,7 @@ const wanted = expectedBook(book, generated);
 
 if (process.argv.includes('--check')) {
   if (wanted !== book) {
-    console.error(`${path.relative(root, bookFile)} predicate reference is stale; run npm run generate`);
+    console.error(`${path.relative(root, bookFile)} predicate reference is stale; run node tools/generate-predicate-reference.mjs (npm version regenerates it automatically)`);
     process.exit(1);
   }
   console.log(`${path.relative(root, bookFile)} predicate reference is up to date (${surface.indicators.length} predicates)`);