eyeprolog 1.4.6 → 1.4.7

package/examples/deck/README.md

@@ -2,7 +2,7 @@
 
 Wide-audience companion explanations for selected runnable examples.
 
-- [Introduction to EyeProlog](https://eyereasoner.github.io/eyeprolog/examples/deck/introduction-to-eyeprolog) — a short slide deck introducing facts, rules, answers, proofs, ISO conformance, JavaScript embedding, and RDF roundtrips.
+- [Introduction to EyeProlog](https://eyereasoner.github.io/eyeprolog/examples/deck/introduction-to-eyeprolog) — a guided slide deck introducing facts, rules, answers, proofs, CLP(Z), CLP(B), ISO conformance, JavaScript embedding, RDF roundtrips, and a categorized path through the example corpus.
 - [Cross-organization data sharing](https://eyereasoner.github.io/eyeprolog/examples/deck/cross-organization-data-sharing) — ODRL/DPV sharing decisions with permit, deny, review, safeguards, and obligations.
 - [Explainable EV-depot configuration](https://eyereasoner.github.io/eyeprolog/examples/deck/explainable-ev-depot-configuration) — reversible configuration rules that select a charger, explain blockers, and derive required changes.
 - [ODRL policy reasoning](https://eyereasoner.github.io/eyeprolog/examples/deck/odrl-policy-reasoning) — permissions, prohibitions, duties, conflicts, and defaults.

package/examples/deck/introduction-to-eyeprolog.md

@@ -1,26 +1,24 @@
 ---
 marp: true
 title: Introduction to EyeProlog
-description: A short presentation introducing EyeProlog as a portable, inspectable ISO Prolog engine for answers, proofs, and RDF-backed reasoning.
+description: A short presentation introducing EyeProlog as a portable, inspectable ISO Prolog engine for answers, proofs, constraints, and RDF-backed reasoning.
 ---
 
 # Introduction to EyeProlog
 
-Portable Prolog reasoning for answers, proofs, and knowledge graphs
+Portable Prolog reasoning for answers, proofs, constraints, and knowledge graphs
+
+EyeProlog is meant to be approachable from two directions at once: it is small enough to embed in JavaScript applications, yet explicit enough that a conclusion can be explained as ordinary facts and rules.
 
 ---
 
 ## What is EyeProlog?
 
-EyeProlog is a small ISO Prolog implementation for JavaScript.
+EyeProlog is an ISO-oriented Prolog implementation for JavaScript.
 
-It turns explicit facts and rules into:
+It turns explicit facts and rules into answers, variable bindings, checked example output, optional proof traces, and embeddable reasoning in Node.js or browsers.
 
-- answers;
-- variable bindings;
-- checked example output;
-- optional proof traces;
-- embeddable reasoning in Node.js and browsers.
+The project’s emphasis is not only “can this query run?” but also “can we inspect what happened, test it again, and explain why the answer follows?” That makes EyeProlog useful for demos, documentation, knowledge-graph workflows, and applications that need a small transparent reasoning layer.
 
 ---
 
@@ -42,6 +40,8 @@ Then you ask questions:
    true.
 ```
 
+The same rule can answer a yes/no question, enumerate solutions, or participate in a larger proof. That reuse is one of the reasons Prolog remains attractive for rule-heavy software.
+
 ---
 
 ## The core idea
@@ -56,7 +56,9 @@ facts + rules + query
 answers with reasons
 ```
 
-The same rule can answer a yes/no question, enumerate solutions, or participate in a larger proof.
+A query is not just a function call. It is a logical request: “find values that make this relation true.” EyeProlog searches by unifying terms, trying clauses, and backtracking over alternatives.
+
+Because the input remains ordinary Prolog text, the boundary between data, rules, and answers stays inspectable.
 
 ---
 
@@ -78,6 +80,8 @@ Try a list query:
 ;  X = logic.
 ```
 
+The semicolon asks for another answer. This small interaction already shows the Prolog execution model: a relation can produce more than one solution.
+
 ---
 
 ## Programs are ordinary text
@@ -97,6 +101,8 @@ Run it:
 eyeprolog examples/socrates.pl
 ```
 
+The examples directory uses this same pattern at larger scale. Each runnable example has checked output, so examples are not just illustrative snippets; they are part of the release gate.
+
 ---
 
 ## Proofs are first-class
@@ -107,12 +113,9 @@ EyeProlog can show not only *what* was concluded, but *why*.
 eyeprolog --proof examples/socrates.pl
 ```
 
-Proof output is useful for:
+Proof output is useful for debugging rules, explaining decisions, preserving audit trails, and keeping documentation honest. If a proof-producing example changes, the checked proof output changes too.
 
-- debugging rules;
-- explaining decisions;
-- regression tests;
-- audit trails.
+This is especially helpful when rules encode policies, risk decisions, or derived knowledge where the explanation matters as much as the final answer.
 
 ---
 
@@ -120,23 +123,44 @@ Proof output is useful for:
 
 EyeProlog starts from ISO/IEC 13211-1 Prolog.
 
-That matters because facts, rules, terms, control, errors, streams, arithmetic, and meta-calls have an external reference point.
+That matters because facts, rules, terms, control, errors, streams, arithmetic, and meta-calls have an external reference point. Strict ISO mode keeps that standardized core separate and testable.
+
+Normal mode adds practical libraries and embedding features. The design goal is to keep extensions visible rather than hiding them inside an undocumented dialect.
+
+---
+
+## Constraints over integers: CLP(Z)
 
-Normal mode adds practical libraries and embedding features. Strict ISO mode keeps the standardized core separate and testable.
+`library(clpz)` lets programs state relations over integers instead of manually enumerating arithmetic cases.
+
+```prolog
+:- use_module(library(clpz)).
+
+?- X #>= 1, X #=< 4, Y #= X*X, labeling([X]).
+   X = 1, Y = 1
+;  X = 2, Y = 4
+;  X = 3, Y = 9
+;  X = 4, Y = 16.
+```
+
+This style is useful when you know the constraints before you know the values: scheduling, allocation, Sudoku, finite-domain puzzles, resource planning, and arithmetic search.
 
 ---
 
-## Why JavaScript?
+## Constraints over Booleans: CLP(B)
 
-EyeProlog runs where modern applications already run:
+`library(clpb)` provides Boolean constraints with satisfiability, cardinality, counting, and optimization predicates.
+
+```prolog
+:- use_module(library(clpb)).
+
+?- sat(card([2], [A,B,C,D]) * (A =< C) * (B # D)),
+   labeling([A,B,C,D]).
+```
 
-- command-line tools;
-- npm packages;
-- browser playgrounds;
-- web workers;
-- JavaScript APIs.
+The recent CLP(B) examples show several practical shapes: circuit verification, quorum constraints, feature-model counting, and weighted release planning.
 
-The aim is not to replace every Prolog system. It is to make portable Prolog reasoning easy to embed and inspect.
+Boolean constraints are compact when the domain is “on/off”, “selected/not selected”, “permitted/denied”, or “feature enabled/disabled”.
 
 ---
 
@@ -154,56 +178,79 @@ RDF dataset
 
 RDF remains the interchange layer. Prolog remains the transparent reasoning layer.
 
+This is useful when a knowledge graph needs explicit derivation rules, but the data should still move in and out as RDF rather than as a private in-memory structure.
+
 ---
 
-## What this enables
+## Categorized examples: start here
 
-The example suite uses the same pattern for:
+The example corpus is intentionally broad. A practical path through it is:
 
-- policy decisions;
-- incident response;
-- software supply-chain risk;
-- scientific evidence assessment;
-- EV-depot configuration;
-- symbiotic human/AI/knowledge-graph workflows.
+- **First steps:** `socrates.pl`, `ancestor.pl`, `list-collection.pl`.
+- **Algorithms:** graph reachability, Dijkstra, parser, FFT, SAT/DPLL.
+- **Integer constraints:** CLP(Z) queens, Sudoku, resource allocation.
+- **Boolean constraints:** CLP(B) circuits, cardinality, feature models, planning.
+- **Policies and decisions:** access control, ODRL, GDPR, trust flow.
+- **RDF roundtrips:** symbiotic knowledge graph and domain-specific RDF scenarios.
+- **Proofs:** examples with checked `--proof` output.
 
-Each scenario keeps data, rules, answers, and materialized results as separate inspectable artifacts.
+Use the [playground](https://eyereasoner.github.io/eyeprolog/playground) for quick exploration, or browse the [examples source tree](https://github.com/eyereasoner/eyeprolog/tree/main/examples) when you want to inspect the program and golden output side by side.
 
 ---
 
-## Testing and conformance
+## Example path: constraints
+
+For constraint reasoning, start with the small examples and move outward:
+
+- `clpz-n-queens.pl` shows finite-domain search.
+- `clpz-sudoku-9x9.pl` shows a familiar grid problem.
+- `clpz-resource-allocation.pl` shows planning under resource limits.
+- `clpb-boolean-circuit.pl` shows Boolean verification.
+- `clpb-cardinality.pl` shows exact-count selection.
+- `clpb-feature-model.pl` and `clpb-weighted-planning.pl` show product/release decisions.
+
+Together these examples show that Prolog can describe a problem declaratively while constraint libraries do the propagation and search work.
+
+---
+
+## Example path: knowledge graphs
+
+For RDF-backed reasoning, start with [Symbiotic Knowledge Graphs](https://eyereasoner.github.io/eyeprolog/examples/deck/symbiotic-knowledge-graphs).
 
-EyeProlog’s release gate includes:
+Then explore the scenario decks:
 
-- file-based conformance cases;
-- strict ISO tests;
-- WG17 syntax cases;
-- regression tests;
-- runnable examples;
-- proof examples;
-- documentation synchronization checks.
+- [Cross-organization data sharing](https://eyereasoner.github.io/eyeprolog/examples/deck/cross-organization-data-sharing)
+- [Explainable EV-depot configuration](https://eyereasoner.github.io/eyeprolog/examples/deck/explainable-ev-depot-configuration)
+- [Operational incident response](https://eyereasoner.github.io/eyeprolog/examples/deck/operational-incident-response)
+- [SBOM vulnerability response](https://eyereasoner.github.io/eyeprolog/examples/deck/sbom-vulnerability-response)
+- [Scientific evidence graph](https://eyereasoner.github.io/eyeprolog/examples/deck/scientific-evidence-graph)
+
+Each scenario keeps source RDF, Prolog rules, generated Prolog, and output RDF as separate artifacts.
+
+---
+
+## Testing and conformance
+
+EyeProlog’s release gate includes conformance cases, strict ISO tests, WG17 syntax cases, regression tests, runnable examples, proof examples, and documentation synchronization checks.
 
 The point is simple: behavior should be reproducible, not anecdotal.
 
+The examples are also linted for avoidable singleton-variable warnings. This keeps example code clean for users who run examples through stricter tooling or compare with other Prolog systems.
+
 ---
 
 ## When EyeProlog fits
 
-EyeProlog is a good fit when a project needs:
+EyeProlog is a good fit when a project needs explicit rules, inspectable conclusions, portable Prolog syntax, an embeddable JavaScript runtime, checked examples and proofs, and a clean boundary between data, rules, and results.
 
-- explicit rules;
-- inspectable conclusions;
-- portable Prolog syntax;
-- embeddable JavaScript runtime;
-- checked examples and proofs;
-- a clean boundary between data, rules, and results.
+It is not trying to replace high-performance native Prolog systems. Its niche is transparent reasoning that can live close to JavaScript applications, documentation, and web-accessible demos.
 
 ---
 
 ## Where to go next
 
 - Read [project README](https://github.com/eyereasoner/eyeprolog#readme) for setup and links.
-- Read [Why EyeProlog?](https://eyereasoner.github.io/eyeprolog/why-eyeprolog) for the design motivation.
 - Open [EyeProlog playground](https://eyereasoner.github.io/eyeprolog/playground) to run examples in a browser.
-- Explore [runnable examples](https://github.com/eyereasoner/eyeprolog/tree/main/examples) for runnable programs.
+- Browse [runnable examples](https://github.com/eyereasoner/eyeprolog/tree/main/examples) by category or filename.
+- Read [Why EyeProlog?](https://eyereasoner.github.io/eyeprolog/why-eyeprolog) for the design motivation.
 - Read [The Art of EyeProlog](https://eyereasoner.github.io/eyeprolog/the-art-of-eyeprolog) for the full reference.

package/package.json

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

package/test/run-regression.mjs

@@ -4647,8 +4647,65 @@ child.stdin.write(\`consult(${consultedAtom}).\\n\`);
 }
 
 
+
+function topLevelRunnableExampleFiles() {
+  const examplesDir = path.join(packageRoot, 'examples');
+  return fs.readdirSync(examplesDir)
+    .filter((name) => name.endsWith('.pl'))
+    .sort()
+    .map((name) => path.join(examplesDir, name));
+}
+
+function visitTermVariables(term, counts, seen = new Set()) {
+  if (term == null) return;
+  if (term.type === 'var') {
+    // The parser preserves identity for repeated source variables. Count every
+    // occurrence so only variables that occur once syntactically are flagged.
+    counts.set(term.name, (counts.get(term.name) ?? 0) + 1);
+    return;
+  }
+  if (seen.has(term)) return;
+  seen.add(term);
+  if (term.type === 'compound') {
+    for (const arg of term.args) visitTermVariables(arg, counts, seen);
+  }
+}
+
+function singletonVariableWarningsForClause(clause) {
+  const counts = new Map();
+  visitTermVariables(clause.head, counts);
+  for (const goal of clause.body ?? []) visitTermVariables(goal, counts);
+  return [...counts]
+    .filter(([name, count]) => count === 1 && !String(name).startsWith('_'))
+    .map(([name]) => name);
+}
+
+function singletonVariableWarningsForRunnableExamples() {
+  const warnings = [];
+  for (const filename of topLevelRunnableExampleFiles()) {
+    const text = fs.readFileSync(filename, 'utf8');
+    const program = Program.parseSources([{ text, filename }], { sourceMetadata: true });
+    for (const clause of program.clauses) {
+      if (path.resolve(clause.source?.filename ?? '') !== path.resolve(filename)) continue;
+      for (const name of singletonVariableWarningsForClause(clause)) {
+        warnings.push(`singleton: ${name}, near ${path.relative(packageRoot, filename)}:${clause.source?.line ?? '?'}`);
+      }
+    }
+  }
+  return warnings;
+}
+
 function documentationSyncCases() {
   return [
+    {
+      name: 'runnable examples are free of singleton-variable warnings',
+      run: () => {
+        const warnings = singletonVariableWarningsForRunnableExamples();
+        if (warnings.length !== 0) {
+          throw new Error(`example singleton-variable warnings\n${warnings.join('\n')}`);
+        }
+      },
+    },
     {
       name: 'WG17 syntax status matches its executable-coverage manifest',
       run: () => {