eyeling 1.5.14 → 1.5.16

package/README.md

@@ -4,12 +4,13 @@ A minimal [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 
 `eyeling` is:
 
-- a single self-contained file (`eyeling.js`, no external deps),
-- intentionally tiny and close in spirit to EYE,
-- a practical N3/Turtle superset (enough for lots of real rulesets),
-- supports forward (`=>`) + backward (`<=`) chaining over Horn-style rules,
-- prints only newly derived forward facts, optionally preceded by compact proof comments,
-- we never want to leak raw data, hence pass-only-new and backward rules for functions that work with raw data, and of course we also keep all reasoning in the browser.
+- a single self-contained file (`eyeling.js`, no external deps)
+- intentionally tiny and close in spirit to EYE
+- a practical N3/Turtle superset (enough for lots of real rulesets)
+- supports forward (`=>`) + backward (`<=`) chaining over Horn-style rules
+- prints only newly derived forward facts, optionally preceded by compact proof comments
+- we never want to leak raw data, hence pass-only-new and backward rules for functions that work with raw data
+- and of course we also keep all reasoning in the browser
 
 ## Playground (in your browser)
 
@@ -18,21 +19,22 @@ Try it here:
 - [Eyeling playground](https://eyereasoner.github.io/eyeling/demo)
 
 The playground runs `eyeling` client-side. You can:
-- edit an N3 program directly,
-- load an N3 program from a URL,
-- share a link with the program encoded in the URL fragment (`#...`).  
+
+- edit an N3 program directly
+- load an N3 program from a URL
+- share a link with the program encoded in the URL fragment (`#...`)
 
 ### Example (Socrates)
 
 This link preloads a small “Socrates is Mortal” ruleset:
 
-[Socrates example](https://eyereasoner.github.io/eyeling/demo#%23%20------------------%0A%23%20Socrates%20inference%0A%23%20------------------%0A%0A%40prefix%20rdfs%3A%20%3Chttp%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23%3E.%0A%40prefix%20%3A%20%3Chttp%3A%2F%2Fexample.org%2Fsocrates%23%3E.%0A%0A%23%20facts%0A%3ASocrates%20a%20%3AHuman.%0A%3AHuman%20rdfs%3AsubClassOf%20%3AMortal.%0A%0A%23%20subclass%20rule%0A%7B%0A%20%20%20%20%3FS%20a%20%3FA.%0A%20%20%20%20%3FA%20rdfs%3AsubClassOf%20%3FB.%0A%7D%20%3D%3E%20%7B%0A%20%20%20%20%3FS%20a%20%3FB.%0A%7D%2E%0A)
+- [Socrates example](https://eyereasoner.github.io/eyeling/demo#%23%20------------------%0A%23%20Socrates%20inference%0A%23%20------------------%0A%0A%40prefix%20rdfs%3A%20%3Chttp%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23%3E.%0A%40prefix%20%3A%20%3Chttp%3A%2F%2Fexample.org%2Fsocrates%23%3E.%0A%0A%23%20facts%0A%3ASocrates%20a%20%3AHuman.%0A%3AHuman%20rdfs%3AsubClassOf%20%3AMortal.%0A%0A%23%20subclass%20rule%0A%7B%0A%20%20%20%20%3FS%20a%20%3FA.%0A%20%20%20%20%3FA%20rdfs%3AsubClassOf%20%3FB.%0A%7D%20%3D%3E%20%7B%0A%20%20%20%20%3FS%20a%20%3FB.%0A%7D%2E%0A)
 
 ## Quick start (Node.js)
 
 ### Requirements
 
-- A reasonably recent Node.js (anything modern with `BigInt` support is fine).
+- Node.js >= 18 (anything modern with `BigInt` support is fine)
 
 ### Install (npm)
 
@@ -53,7 +55,7 @@ npx eyeling examples/socrates.n3
 ### JavaScript API (Node)
 
 ```js
-const { reason } = require('eyeling');
+const { reason } = require("eyeling");
 
 const input = `
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@@ -72,7 +74,7 @@ console.log(output);
 ESM:
 
 ```js
-import eyeling from 'eyeling';
+import eyeling from "eyeling";
 
 const output = eyeling.reason({ proofComments: false }, input);
 console.log(output);
@@ -80,6 +82,28 @@ console.log(output);
 
 Note: the API currently shells out to the bundled `eyeling.js` CLI under the hood (simple + robust).
 
+### Testing
+
+From a repo checkout:
+
+```bash
+npm test
+```
+
+Or run individual suites:
+
+```bash
+npm run test:api
+npm run test:examples
+npm run test:package
+npm run test:packlist
+```
+
+- `test:api` runs an independent JS API test suite (does not rely on `examples/`).
+- `test:examples` runs the `examples/test` runner and compares against the golden outputs in `examples/output`.
+- `test:package` does a “real consumer” smoke test: `npm pack` → install tarball into a temp project → run API + CLI + examples.
+- `test:packlist` sanity-checks what will be published in the npm tarball (and the CLI shebang/bin wiring).
+
 ### Run a single file
 
 From the repo root:
@@ -94,10 +118,10 @@ node eyeling.js examples/socrates.n3
 
 By default, `eyeling`:
 
-1. parses the input (facts + rules),
-2. runs **forward chaining to a fixpoint**,
-3. prints only **newly derived forward facts** (not the original input facts),
-4. prints a compact per-triple explanation as `#` comments (can be disabled).
+1. parses the input (facts + rules)
+2. runs **forward chaining to a fixpoint**
+3. prints only **newly derived forward facts** (not the original input facts)
+4. prints a compact per-triple explanation as `#` comments (can be disabled)
 
 ### Options
 
@@ -116,7 +140,8 @@ node eyeling.js -n examples/socrates.n3
 npm run test:examples
 ```
 
-This runs `eyeling.js` over each example and compares against the golden outputs in `examples/output`.
+This runs `eyeling.js` over each example and compares against the golden outputs in `examples/output`
+(works both in a git checkout and in an npm-installed package).
 
 ## What output do I get?
 
@@ -131,14 +156,14 @@ The proof comments are compact “local justifications” per derived triple (no
 
 ### Forward + backward chaining
 
-* **Forward chaining to fixpoint** for forward rules written as `{ P } => { C } .`
-* **Backward chaining (SLD-style)** for backward rules written as `{ H } <= { B } .` and for built-ins.
+- **Forward chaining to fixpoint** for forward rules written as `{ P } => { C } .`
+- **Backward chaining (SLD-style)** for backward rules written as `{ H } <= { B } .` and for built-ins.
 
 Forward rule premises are proved using:
 
-* ground facts (input + derived),
-* backward rules,
-* built-ins.
+- ground facts (input + derived)
+- backward rules
+- built-ins
 
 The CLI prints only newly derived forward facts.
 
@@ -146,63 +171,59 @@ The CLI prints only newly derived forward facts.
 
 `eyeling` stays tiny, but includes a few key performance mechanisms:
 
-* facts are indexed for matching:
-
-  * by predicate, and (when possible) by **(predicate, object)** (important for type-heavy workloads),
-* duplicate detection uses a fast key path when a triple is fully IRI/Literal-shaped,
-* backward rules are indexed by head predicate,
-* the backward prover is **iterative** (explicit stack), so deep chains won’t blow the JS call stack,
-* for very deep backward chains, substitutions may be compactified (semantics-preserving) to avoid quadratic “copy a growing substitution object” behavior.
+- facts are indexed for matching:
+  - by predicate, and (when possible) by **(predicate, object)** (important for type-heavy workloads)
+- duplicate detection uses a fast key path when a triple is fully IRI/Literal-shaped
+- backward rules are indexed by head predicate
+- the backward prover is **iterative** (explicit stack), so deep chains won’t blow the JS call stack
+- for very deep backward chains, substitutions may be compactified (semantics-preserving) to avoid quadratic “copy a growing substitution object” behavior
 
 ## Parsing: practical N3 subset
 
 Supported:
 
-* `@prefix` / `@base`
-* triples with `;` and `,`
-* variables `?x`
-* blank nodes:
-
-  * anonymous `[]`
-  * property lists `[ :p :o; :q :r ]`
-  * collections `( ... )`
-* quoted formulas `{ ... }`
-* implications:
-
-  * forward rules `{ P } => { C } .`
-  * backward rules `{ H } <= { B } .`
-* datatyped literals with `^^`
-* `#` line comments
+- `@prefix` / `@base`
+- triples with `;` and `,`
+- variables `?x`
+- blank nodes:
+  - anonymous `[]`
+  - property lists `[ :p :o; :q :r ]`
+- collections `( ... )`
+- quoted formulas `{ ... }`
+- implications:
+  - forward rules `{ P } => { C } .`
+  - backward rules `{ H } <= { B } .`
+- datatyped literals with `^^`
+- `#` line comments
 
 Non-goals / current limits:
 
-* not a full W3C N3 grammar (some edge cases for identifiers, quantifiers, advanced syntax),
-* quoted formulas are matched as whole formulas (no pattern matching inside formulas yet),
-* proof output is local per derived triple (not a global exported proof tree).
+- not a full W3C N3 grammar (some edge cases for identifiers, quantifiers, advanced syntax)
+- quoted formulas are matched as whole formulas (no pattern matching inside formulas yet)
+- proof output is local per derived triple (not a global exported proof tree)
 
 ## Blank nodes and quantification (pragmatic N3/EYE-style)
 
 `eyeling` follows the usual N3 intuition:
 
-1. blank nodes in facts are normal RDF blanks (`_:b1`, `_:b2`, … within a run),
-2. blank nodes in rule premises behave like rule-scoped universals (similar to variables),
-3. blank nodes only in rule conclusions behave like existentials:
-   each rule firing generates fresh Skolem blanks (`_:sk_0`, `_:sk_1`, …).
+1. blank nodes in facts are normal RDF blanks (`_:b1`, `_:b2`, … within a run)
+2. blank nodes in rule premises behave like rule-scoped universals (similar to variables)
+3. blank nodes only in rule conclusions behave like existentials: each rule firing generates fresh Skolem blanks (`_:sk_0`, `_:sk_1`, …)
 
 Equal facts up to renaming of Skolem IDs are treated as duplicates and are not re-added.
 
 ## Rule-producing rules (meta-rules)
 
-`eyeling` understands the `log:implies` / `log:impliedBy` idiom:
+`eyeling` understands the `log:implies` / `log:impliedBy` idiom.
 
 Top level:
 
-* `{ P } log:implies { C } .` becomes a forward rule `{ P } => { C } .`
-* `{ H } log:impliedBy { B } .` becomes a backward rule `{ H } <= { B } .`
+- `{ P } log:implies { C } .` becomes a forward rule `{ P } => { C } .`
+- `{ H } log:impliedBy { B } .` becomes a backward rule `{ H } <= { B } .`
 
 During reasoning:
 
-* any **derived** `log:implies` / `log:impliedBy` triple with formula subject/object is turned into a new live forward/backward rule.
+- any **derived** `log:implies` / `log:impliedBy` triple with formula subject/object is turned into a new live forward/backward rule.
 
 ## Inference fuse — `{ ... } => false.`
 
@@ -211,6 +232,7 @@ Rules whose conclusion is `false` are treated as hard failures:
 ```n3
 :stone :color :black .
 :stone :color :white .
+
 { ?X :color :black . ?X :color :white . } => false.
 ```
 
@@ -220,13 +242,12 @@ As soon as the premise is provable, `eyeling` exits with status code `2`.
 
 `eyeling` implements a pragmatic subset of common N3 builtin families and evaluates them during backward goal proving:
 
-* **crypto**: `crypto:md5` `crypto:sha` `crypto:sha256` `crypto:sha512`
-* **list**: `list:append` `list:first` `list:firstRest` `list:in` `list:iterate` `list:last` `list:length` `list:map` `list:member` `list:memberAt` `list:notMember` `list:remove` `list:reverse` `list:sort`
-* **log**: `log:collectAllIn` `log:equalTo` `log:forAllIn` `log:impliedBy` `log:implies` `log:notEqualTo` `log:notIncludes` `log:skolem` `log:uri`
-* **math**: `math:absoluteValue` `math:acos` `math:asin` `math:atan` `math:cos` `math:cosh` `math:degrees` `math:difference` `math:equalTo` `math:exponentiation` `math:greaterThan` `math:lessThan` `math:negation` `math:notEqualTo` `math:notGreaterThan` `math:notLessThan` `math:product` `math:quotient` `math:remainder` `math:rounded` `math:sin` `math:sinh` `math:sum` `math:tan` `math:tanh`
-* **string**: `string:concatenation` `string:contains` `string:containsIgnoringCase` `string:endsWith` `string:equalIgnoringCase` `string:format` `string:greaterThan` `string:lessThan` `string:matches` `string:notEqualIgnoringCase` `string:notGreaterThan` `string:notLessThan` `string:notMatches` `string:replace` `string:scrape` `string:startsWith`
-* **time**: `time:localTime`
-
+- **crypto**: `crypto:md5` `crypto:sha` `crypto:sha256` `crypto:sha512`
+- **list**: `list:append` `list:first` `list:firstRest` `list:in` `list:iterate` `list:last` `list:length` `list:map` `list:member` `list:memberAt` `list:notMember` `list:remove` `list:reverse` `list:sort`
+- **log**: `log:collectAllIn` `log:equalTo` `log:forAllIn` `log:impliedBy` `log:implies` `log:notEqualTo` `log:notIncludes` `log:skolem` `log:uri`
+- **math**: `math:absoluteValue` `math:acos` `math:asin` `math:atan` `math:cos` `math:cosh` `math:degrees` `math:difference` `math:equalTo` `math:exponentiation` `math:greaterThan` `math:lessThan` `math:negation` `math:notEqualTo` `math:notGreaterThan` `math:notLessThan` `math:product` `math:quotient` `math:remainder` `math:rounded` `math:sin` `math:sinh` `math:sum` `math:tan` `math:tanh`
+- **string**: `string:concatenation` `string:contains` `string:containsIgnoringCase` `string:endsWith` `string:equalIgnoringCase` `string:format` `string:greaterThan` `string:lessThan` `string:matches` `string:notEqualIgnoringCase` `string:notGreaterThan` `string:notLessThan` `string:notMatches` `string:replace` `string:scrape` `string:startsWith`
+- **time**: `time:localTime`
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.5.14",
+  "version": "1.5.16",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [
@@ -29,9 +29,10 @@
     "node": ">=18"
   },
   "scripts": {
+    "test:packlist": "node test/packlist.test.js",
     "test:api": "node test/api.test.js",
     "test:examples": "bash -lc 'cd examples && ./test'",
     "test:package": "bash test/package-smoke.sh",
-    "test": "npm run test:api && npm run test:examples"
+    "test": "npm run test:packlist && npm run test:api && npm run test:examples"
   }
 }

package/test/api.test.js

@@ -1,22 +1,613 @@
 'use strict';
 
 const assert = require('node:assert/strict');
-const { reason } = require('..'); // gebruikt package main: ./index.js
+const { reason } = require('..');
 
-const input = `
-{ <http://example.org/s> <http://example.org/p> <http://example.org/o>. }
-  => { <http://example.org/s> <http://example.org/q> <http://example.org/o>. }.
+const TTY = process.stdout.isTTY;
+const C = TTY
+  ? { g: '\x1b[32m', r: '\x1b[31m', y: '\x1b[33m', dim: '\x1b[2m', n: '\x1b[0m' }
+  : { g: '', r: '', y: '', dim: '', n: '' };
 
-<http://example.org/s> <http://example.org/p> <http://example.org/o>.
+function ok(msg)   { console.log(`${C.g}OK${C.n}  ${msg}`); }
+function info(msg) { console.log(`${C.y}==${C.n} ${msg}`); }
+function fail(msg) { console.error(`${C.r}FAIL${C.n} ${msg}`); }
+
+function msNow() {
+  return Date.now();
+}
+
+function mustMatch(output, re, label) {
+  assert.match(output, re, label || `Expected output to match ${re}`);
+}
+
+function mustNotMatch(output, re, label) {
+  assert.ok(!re.test(output), label || `Expected output NOT to match ${re}`);
+}
+
+const EX = 'http://example.org/';
+
+// Helper to build a URI quickly
+const U = (path) => `<${EX}${path}>`;
+
+function parentChainN3(n) {
+  // n links => n+1 nodes: n0->n1->...->nN
+  let s = '';
+  for (let i = 0; i < n; i++) {
+    s += `${U(`n${i}`)} ${U('parent')} ${U(`n${i + 1}`)}.\n`;
+  }
+  s += `
+{ ?x ${U('parent')} ?y } => { ?x ${U('ancestor')} ?y }.
+{ ?x ${U('parent')} ?y. ?y ${U('ancestor')} ?z } => { ?x ${U('ancestor')} ?z }.
+`;
+  return s;
+}
+
+function subclassChainN3(n) {
+  // C0 sub C1 ... Cn sub C(n+1)
+  let s = '';
+  for (let i = 0; i <= n; i++) {
+    s += `${U(`C${i}`)} ${U('sub')} ${U(`C${i + 1}`)}.\n`;
+  }
+  s += `${U('x')} ${U('type')} ${U('C0')}.\n`;
+  s += `{ ?s ${U('type')} ?a. ?a ${U('sub')} ?b } => { ?s ${U('type')} ?b }.\n`;
+  return s;
+}
+
+function ruleChainN3(n) {
+  // p0 -> p1 -> ... -> pn, starting from (s p0 o)
+  let s = '';
+  for (let i = 0; i < n; i++) {
+    s += `{ ${U('s')} ${U(`p${i}`)} ${U('o')}. } => { ${U('s')} ${U(`p${i + 1}`)} ${U('o')}. }.\n`;
+  }
+  s += `${U('s')} ${U('p0')} ${U('o')}.\n`;
+  return s;
+}
+
+function binaryTreeParentN3(depth) {
+  // breadth-first numbering: node i has children 2i+1 and 2i+2
+  // depth=0 -> 1 node; depth=1 -> 3 nodes; depth=4 -> 31 nodes
+  const maxNode = (1 << (depth + 1)) - 2; // last index at given depth
+  let s = '';
+
+  for (let i = 0; i <= maxNode; i++) {
+    const left = 2 * i + 1;
+    const right = 2 * i + 2;
+    if (left <= maxNode) s += `${U(`t${i}`)} ${U('parent')} ${U(`t${left}`)}.\n`;
+    if (right <= maxNode) s += `${U(`t${i}`)} ${U('parent')} ${U(`t${right}`)}.\n`;
+  }
+
+  s += `
+{ ?x ${U('parent')} ?y } => { ?x ${U('ancestor')} ?y }.
+{ ?x ${U('parent')} ?y. ?y ${U('ancestor')} ?z } => { ?x ${U('ancestor')} ?z }.
+`;
+  return s;
+}
+
+function transitiveClosureN3(pred) {
+  return `
+{ ?a ${U(pred)} ?b. ?b ${U(pred)} ?c } => { ?a ${U(pred)} ?c }.
+`;
+}
+
+function reachabilityGraphN3(n) {
+  // chain plus a few extra edges for branching
+  let s = '';
+  for (let i = 0; i < n; i++) {
+    s += `${U(`g${i}`)} ${U('edge')} ${U(`g${i + 1}`)}.\n`;
+  }
+  // add some shortcuts/branches
+  if (n >= 6) {
+    s += `${U('g0')} ${U('edge')} ${U('g3')}.\n`;
+    s += `${U('g2')} ${U('edge')} ${U('g5')}.\n`;
+    s += `${U('g1')} ${U('edge')} ${U('g4')}.\n`;
+  }
+  s += `
+{ ?a ${U('edge')} ?b } => { ?a ${U('reach')} ?b }.
+{ ?a ${U('edge')} ?b. ?b ${U('reach')} ?c } => { ?a ${U('reach')} ?c }.
 `;
+  return s;
+}
+
+function diamondSubclassN3() {
+  return `
+${U('A')} ${U('sub')} ${U('B')}.
+${U('A')} ${U('sub')} ${U('C')}.
+${U('B')} ${U('sub')} ${U('D')}.
+${U('C')} ${U('sub')} ${U('D')}.
+${U('x')} ${U('type')} ${U('A')}.
+
+{ ?s ${U('type')} ?a. ?a ${U('sub')} ?b } => { ?s ${U('type')} ?b }.
+`;
+}
+
+function join3HopN3(k) {
+  // a0 --p--> a1 --p--> a2 --p--> ... ; rule derives hop3 edges
+  let s = '';
+  for (let i = 0; i < k; i++) {
+    s += `${U(`j${i}`)} ${U('p')} ${U(`j${i + 1}`)}.\n`;
+  }
+  s += `
+{ ?x ${U('p')} ?y. ?y ${U('p')} ?z. ?z ${U('p')} ?w } => { ?x ${U('p3')} ?w }.
+`;
+  return s;
+}
+
+function sameAsN3() {
+  return `
+${U('a')} ${U('sameAs')} ${U('b')}.
+${U('a')} ${U('p')} ${U('o')}.
+
+{ ?x ${U('sameAs')} ?y } => { ?y ${U('sameAs')} ?x }.
+{ ?x ${U('sameAs')} ?y. ?x ?p ?o } => { ?y ?p ?o }.
+`;
+}
+
+function ruleBranchJoinN3() {
+  return `
+${U('s')} ${U('p')} ${U('o')}.
+
+{ ${U('s')} ${U('p')} ${U('o')}. } => { ${U('s')} ${U('q')} ${U('o')}. }.
+{ ${U('s')} ${U('p')} ${U('o')}. } => { ${U('s')} ${U('r')} ${U('o')}. }.
+{ ${U('s')} ${U('q')} ${U('o')}. ${U('s')} ${U('r')} ${U('o')}. } => { ${U('s')} ${U('qr')} ${U('o')}. }.
+`;
+}
+
+function bigFactsN3(n) {
+  let s = '';
+  for (let i = 0; i < n; i++) {
+    s += `${U('x')} ${U('p')} ${U(`o${i}`)}.\n`;
+  }
+  s += `{ ?s ${U('p')} ?o } => { ?s ${U('q')} ?o }.\n`;
+  return s;
+}
+
+function negativeEntailmentBatchN3(n) {
+  // if any forbidden fact exists, derive false
+  let s = '';
+  for (let i = 0; i < n; i++) {
+    s += `${U('x')} ${U('ok')} ${U(`v${i}`)}.\n`;
+  }
+  s += `${U('x')} ${U('forbidden')} ${U('boom')}.\n`;
+  s += `{ ?s ${U('forbidden')} ?o. } => false.\n`;
+  return s;
+}
+
+function symmetricTransitiveN3() {
+  // friend is symmetric; reachFriend is transitive closure over friend edges
+  return `
+${U('a')} ${U('friend')} ${U('b')}.
+${U('b')} ${U('friend')} ${U('c')}.
+${U('c')} ${U('friend')} ${U('d')}.
+
+{ ?x ${U('friend')} ?y } => { ?y ${U('friend')} ?x }.
+{ ?a ${U('friend')} ?b } => { ?a ${U('reachFriend')} ?b }.
+{ ?a ${U('friend')} ?b. ?b ${U('reachFriend')} ?c } => { ?a ${U('reachFriend')} ?c }.
+`;
+}
+
+function mkChainRewriteCase(i, steps) {
+  const input = ruleChainN3(steps); // already defined earlier
+  return {
+    name: `${String(i).padStart(2, '0')} chain rewrite: ${steps} steps`,
+    opt: { proofComments: false },
+    input,
+    expect: [new RegExp(`${EX}s>\\s+<${EX}p${steps}>\\s+<${EX}o>\\s*\\.`)],
+  };
+}
+
+function mkSubclassChainCase(i, steps) {
+  const input = subclassChainN3(steps); // already defined earlier
+  return {
+    name: `${String(i).padStart(2, '0')} subclass chain: ${steps} steps`,
+    opt: { proofComments: false },
+    input,
+    expect: [new RegExp(`${EX}x>\\s+<${EX}type>\\s+<${EX}C${steps + 1}>\\s*\\.`)],
+  };
+}
+
+function mkParentChainCase(i, links) {
+  const input = parentChainN3(links); // already defined earlier
+  return {
+    name: `${String(i).padStart(2, '0')} ancestor chain: ${links} links`,
+    opt: { proofComments: false },
+    input,
+    expect: [new RegExp(`${EX}n0>\\s+<${EX}ancestor>\\s+<${EX}n${links}>\\s*\\.`)],
+  };
+}
+
+function mkJoinCase(i, len) {
+  const input = join3HopN3(len); // already defined earlier
+  // Check a couple of hop-3 inferences that always exist for len>=6
+  return {
+    name: `${String(i).padStart(2, '0')} 3-hop join over chain len ${len}`,
+    opt: { proofComments: false },
+    input,
+    expect: [
+      new RegExp(`${EX}j0>\\s+<${EX}p3>\\s+<${EX}j3>\\s*\\.`),
+      new RegExp(`${EX}j2>\\s+<${EX}p3>\\s+<${EX}j5>\\s*\\.`),
+    ],
+  };
+}
+
+function mkBranchReachCase(i, n) {
+  const input = reachabilityGraphN3(n); // already defined earlier
+  return {
+    name: `${String(i).padStart(2, '0')} reachability: n=${n}`,
+    opt: { proofComments: false },
+    input,
+    expect: [
+      new RegExp(`${EX}g0>\\s+<${EX}reach>\\s+<${EX}g${n}>\\s*\\.`),
+    ],
+  };
+}
+
+const cases = [
+  {
+    name: '01 forward rule: p -> q',
+    opt: { proofComments: false },
+    input: `
+{ ${U('s')} ${U('p')} ${U('o')}. } => { ${U('s')} ${U('q')} ${U('o')}. }.
+${U('s')} ${U('p')} ${U('o')}.
+`,
+    expect: [
+      new RegExp(`${EX}s>\\s+<${EX}q>\\s+<${EX}o>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '02 two-step: p -> q -> r',
+    opt: { proofComments: false },
+    input: `
+{ ${U('s')} ${U('p')} ${U('o')}. } => { ${U('s')} ${U('q')} ${U('o')}. }.
+{ ${U('s')} ${U('q')} ${U('o')}. } => { ${U('s')} ${U('r')} ${U('o')}. }.
+${U('s')} ${U('p')} ${U('o')}.
+`,
+    expect: [
+      new RegExp(`${EX}s>\\s+<${EX}r>\\s+<${EX}o>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '03 join antecedents: (x p y & y p z) -> (x p2 z)',
+    opt: { proofComments: false },
+    input: `
+{ ?x ${U('p')} ?y. ?y ${U('p')} ?z. } => { ?x ${U('p2')} ?z. }.
+${U('a')} ${U('p')} ${U('b')}.
+${U('b')} ${U('p')} ${U('c')}.
+`,
+    expect: [
+      new RegExp(`${EX}a>\\s+<${EX}p2>\\s+<${EX}c>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '04 inverse relation: (x p y) -> (y invp x)',
+    opt: { proofComments: false },
+    input: `
+{ ?x ${U('p')} ?y. } => { ?y ${U('invp')} ?x. }.
+${U('alice')} ${U('p')} ${U('bob')}.
+`,
+    expect: [
+      new RegExp(`${EX}bob>\\s+<${EX}invp>\\s+<${EX}alice>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '05 subclass rule: type + sub -> inferred type (two-level chain)',
+    opt: { proofComments: false },
+    input: `
+${U('Human')} ${U('sub')} ${U('Mortal')}.
+${U('Mortal')} ${U('sub')} ${U('Being')}.
+${U('Socrates')} ${U('type')} ${U('Human')}.
+
+{ ?s ${U('type')} ?a. ?a ${U('sub')} ?b } => { ?s ${U('type')} ?b }.
+`,
+    expect: [
+      new RegExp(`${EX}Socrates>\\s+<${EX}type>\\s+<${EX}Mortal>\\s*\\.`),
+      new RegExp(`${EX}Socrates>\\s+<${EX}type>\\s+<${EX}Being>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '06 transitive closure: sub is transitive',
+    opt: { proofComments: false },
+    input: `
+${U('A')} ${U('sub')} ${U('B')}.
+${U('B')} ${U('sub')} ${U('C')}.
+
+{ ?a ${U('sub')} ?b. ?b ${U('sub')} ?c } => { ?a ${U('sub')} ?c }.
+`,
+    expect: [
+      new RegExp(`${EX}A>\\s+<${EX}sub>\\s+<${EX}C>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '07 symmetric: knows is symmetric',
+    opt: { proofComments: false },
+    input: `
+{ ?x ${U('knows')} ?y } => { ?y ${U('knows')} ?x }.
+${U('a')} ${U('knows')} ${U('b')}.
+`,
+    expect: [
+      new RegExp(`${EX}b>\\s+<${EX}knows>\\s+<${EX}a>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '08 recursion: ancestor from parent (2 steps)',
+    opt: { proofComments: false },
+    input: `
+${U('a')} ${U('parent')} ${U('b')}.
+${U('b')} ${U('parent')} ${U('c')}.
+
+{ ?x ${U('parent')} ?y } => { ?x ${U('ancestor')} ?y }.
+{ ?x ${U('parent')} ?y. ?y ${U('ancestor')} ?z } => { ?x ${U('ancestor')} ?z }.
+`,
+    expect: [
+      new RegExp(`${EX}a>\\s+<${EX}ancestor>\\s+<${EX}c>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '09 literals preserved: age -> hasAge',
+    opt: { proofComments: false },
+    input: `
+{ ?s ${U('age')} ?n } => { ?s ${U('hasAge')} ?n }.
+${U('x')} ${U('age')} "42".
+`,
+    expect: [
+      new RegExp(`${EX}x>\\s+<${EX}hasAge>\\s+"42"\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '10 API option: opt can be an args array',
+    opt: ['--no-proof-comments'],
+    input: `
+{ ${U('s')} ${U('p')} ${U('o')}. } => { ${U('s')} ${U('q')} ${U('o')}. }.
+${U('s')} ${U('p')} ${U('o')}.
+`,
+    expect: [
+      new RegExp(`${EX}s>\\s+<${EX}q>\\s+<${EX}o>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '11 negative entailment: rule derives false (expect exit 2 => throws)',
+    opt: { proofComments: false },
+    input: `
+{ ${U('a')} ${U('p')} ${U('b')}. } => false.
+${U('a')} ${U('p')} ${U('b')}.
+`,
+    expectErrorCode: 2,
+  },
+
+  {
+    name: '12 invalid syntax should throw (non-zero exit)',
+    opt: { proofComments: false },
+    input: `
+@prefix : <http://example.org/>   # missing dot on purpose
+: s :p :o .
+`,
+    expectError: true,
+  },
+  {
+    name: '13 heavier recursion: ancestor closure over 15 links',
+    opt: { proofComments: false, maxBuffer: 200 * 1024 * 1024 },
+    input: parentChainN3(15),
+    expect: [
+      new RegExp(`${EX}n0>\\s+<${EX}ancestor>\\s+<${EX}n15>\\s*\\.`),
+      new RegExp(`${EX}n3>\\s+<${EX}ancestor>\\s+<${EX}n12>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '14 heavier taxonomy: 60-step subclass chain',
+    opt: { proofComments: false, maxBuffer: 200 * 1024 * 1024 },
+    input: subclassChainN3(60),
+    expect: [
+      new RegExp(`${EX}x>\\s+<${EX}type>\\s+<${EX}C61>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '15 heavier chaining: 40-step predicate rewrite chain',
+    opt: { proofComments: false, maxBuffer: 200 * 1024 * 1024 },
+    input: ruleChainN3(40),
+    expect: [
+      new RegExp(`${EX}s>\\s+<${EX}p40>\\s+<${EX}o>\\s*\\.`),
+    ],
+  },
+  {
+    name: '16 heavier recursion: binary tree ancestor closure (depth 4)',
+    opt: { proofComments: false, maxBuffer: 200 * 1024 * 1024 },
+    input: binaryTreeParentN3(4), // 31 nodes
+    expect: [
+      new RegExp(`${EX}t0>\\s+<${EX}ancestor>\\s+<${EX}t30>\\s*\\.`), // root reaches last node
+      new RegExp(`${EX}t1>\\s+<${EX}ancestor>\\s+<${EX}t22>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '17 heavier reachability: branching graph reach closure',
+    opt: { proofComments: false, maxBuffer: 200 * 1024 * 1024 },
+    input: reachabilityGraphN3(12),
+    expect: [
+      new RegExp(`${EX}g0>\\s+<${EX}reach>\\s+<${EX}g12>\\s*\\.`),
+      new RegExp(`${EX}g2>\\s+<${EX}reach>\\s+<${EX}g10>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '18 heavier taxonomy: diamond subclass inference',
+    opt: { proofComments: false },
+    input: diamondSubclassN3(),
+    expect: [
+      new RegExp(`${EX}x>\\s+<${EX}type>\\s+<${EX}D>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '19 heavier join: 3-hop path rule over a chain of 25 edges',
+    opt: { proofComments: false, maxBuffer: 200 * 1024 * 1024 },
+    input: join3HopN3(25),
+    expect: [
+      new RegExp(`${EX}j0>\\s+<${EX}p3>\\s+<${EX}j3>\\s*\\.`),
+      new RegExp(`${EX}j10>\\s+<${EX}p3>\\s+<${EX}j13>\\s*\\.`),
+      new RegExp(`${EX}j20>\\s+<${EX}p3>\\s+<${EX}j23>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '20 heavier branching: p produces q and r, then q+r produces qr',
+    opt: { proofComments: false },
+    input: ruleBranchJoinN3(),
+    expect: [
+      new RegExp(`${EX}s>\\s+<${EX}qr>\\s+<${EX}o>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '21 heavier equivalence: sameAs propagation (with symmetric sameAs)',
+    opt: { proofComments: false },
+    input: sameAsN3(),
+    expect: [
+      new RegExp(`${EX}b>\\s+<${EX}p>\\s+<${EX}o>\\s*\\.`), // b inherits a's triple
+      new RegExp(`${EX}b>\\s+<${EX}sameAs>\\s+<${EX}a>\\s*\\.`), // symmetric sameAs inferred
+    ],
+  },
+
+  {
+    name: '22 heavier closure: transitive property via generic rule',
+    opt: { proofComments: false },
+    input: `
+${U('a')} ${U('sub')} ${U('b')}.
+${U('b')} ${U('sub')} ${U('c')}.
+${U('c')} ${U('sub')} ${U('d')}.
+${U('d')} ${U('sub')} ${U('e')}.
+${transitiveClosureN3('sub')}
+`,
+    expect: [
+      new RegExp(`${EX}a>\\s+<${EX}sub>\\s+<${EX}e>\\s*\\.`),
+      new RegExp(`${EX}b>\\s+<${EX}sub>\\s+<${EX}d>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '23 heavier social: symmetric + reachFriend closure',
+    opt: { proofComments: false, maxBuffer: 200 * 1024 * 1024 },
+    input: symmetricTransitiveN3(),
+    expect: [
+      new RegExp(`${EX}a>\\s+<${EX}reachFriend>\\s+<${EX}d>\\s*\\.`),
+      new RegExp(`${EX}d>\\s+<${EX}reachFriend>\\s+<${EX}a>\\s*\\.`), // due to symmetry + closure
+    ],
+  },
+
+  {
+    name: '24 heavier volume: 400 facts, simple rewrite rule p -> q',
+    opt: { proofComments: false, maxBuffer: 200 * 1024 * 1024 },
+    input: bigFactsN3(400),
+    expect: [
+      new RegExp(`${EX}x>\\s+<${EX}q>\\s+<${EX}o0>\\s*\\.`),
+      new RegExp(`${EX}x>\\s+<${EX}q>\\s+<${EX}o399>\\s*\\.`),
+    ],
+  },
+
+  {
+    name: '25 heavier negative entailment: batch + forbidden => false (expect exit 2)',
+    opt: { proofComments: false, maxBuffer: 200 * 1024 * 1024 },
+    input: negativeEntailmentBatchN3(200),
+    expectErrorCode: 2,
+  },
+];
+
+// ---- Generated “many more” tests (keep them fast & deterministic) ----
+const generated = [];
+
+// 10 rewrite-chain tests
+for (const steps of [1, 2, 3, 5, 8, 10, 12, 15, 20, 25]) {
+  generated.push(mkChainRewriteCase(100 + generated.length + 1, steps));
+}
+
+// 8 subclass-chain tests
+for (const steps of [1, 2, 3, 5, 8, 10, 15, 25]) {
+  generated.push(mkSubclassChainCase(100 + generated.length + 1, steps));
+}
+
+// 6 ancestor-chain tests
+for (const links of [2, 3, 5, 8, 10, 15]) {
+  generated.push(mkParentChainCase(100 + generated.length + 1, links));
+}
+
+// 3 join tests
+for (const len of [8, 12, 20]) {
+  generated.push(mkJoinCase(100 + generated.length + 1, len));
+}
+
+// 3 reachability tests
+for (const n of [6, 10, 14]) {
+  generated.push(mkBranchReachCase(100 + generated.length + 1, n));
+}
+
+cases.push(...generated);
+
+let passed = 0;
+let failed = 0;
+
+(async function main() {
+  info(`Running ${cases.length} API tests (independent of examples/)`);
+
+  for (const tc of cases) {
+    const start = msNow();
+    try {
+      const out = reason(tc.opt, tc.input);
+
+      if (tc.expectErrorCode != null || tc.expectError) {
+        throw new Error(`Expected an error, but reason() returned output:\n${out}`);
+      }
+
+      for (const re of (tc.expect || [])) mustMatch(out, re, `${tc.name}: missing expected pattern ${re}`);
+      for (const re of (tc.notExpect || [])) mustNotMatch(out, re, `${tc.name}: unexpected pattern ${re}`);
+
+      const dur = msNow() - start;
+      ok(`${tc.name} ${C.dim}(${dur} ms)${C.n}`);
+      passed++;
+    } catch (e) {
+      const dur = msNow() - start;
+
+      // Expected error handling
+      if (tc.expectErrorCode != null) {
+        if (e && typeof e === 'object' && 'code' in e && e.code === tc.expectErrorCode) {
+          ok(`${tc.name} ${C.dim}(expected exit ${tc.expectErrorCode}, ${dur} ms)${C.n}`);
+          passed++;
+          continue;
+        }
+        fail(`${tc.name} ${C.dim}(${dur} ms)${C.n}`);
+        fail(`Expected exit code ${tc.expectErrorCode}, got: ${e && e.code != null ? e.code : 'unknown'}\n${e && e.stderr ? e.stderr : (e && e.stack ? e.stack : String(e))}`);
+        failed++;
+        continue;
+      }
 
-const out = reason({ proofComments: false }, input);
+      if (tc.expectError) {
+        ok(`${tc.name} ${C.dim}(expected error, ${dur} ms)${C.n}`);
+        passed++;
+        continue;
+      }
 
-// Verwacht dat de afgeleide triple aanwezig is (tolerant voor formatting)
-assert.match(
-  out,
-  /<http:\/\/example\.org\/s>\s+<http:\/\/example\.org\/q>\s+<http:\/\/example\.org\/o>\s*\./
-);
+      fail(`${tc.name} ${C.dim}(${dur} ms)${C.n}`);
+      fail(e && e.stack ? e.stack : String(e));
+      failed++;
+    }
+  }
 
-console.log('OK: reason() inferred expected triple');
+  console.log('');
+  if (failed === 0) {
+    ok(`All API tests passed (${passed}/${cases.length})`);
+    process.exit(0);
+  } else {
+    fail(`Some API tests failed (${passed}/${cases.length})`);
+    process.exit(1);
+  }
+})();
 

package/test/package-smoke.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\e[31m'; GREEN=$'\e[32m'; YELLOW=$'\e[33m'; NORMAL=$'\e[0m'
+else
+  RED=""; GREEN=""; YELLOW=""; NORMAL=""
+fi
+
+say() { echo -e "${YELLOW}== $* ==${NORMAL}"; }
+ok()  { echo -e "${GREEN}OK${NORMAL} $*"; }
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP="$(mktemp -d)"
+cleanup() { rm -rf "$TMP"; }
+trap cleanup EXIT
+
+cd "$ROOT"
+
+say "Building tarball"
+TGZ="$(npm pack --silent)"
+mv "$TGZ" "$TMP/"
+cd "$TMP"
+
+say "Installing tarball into temp project"
+npm init -y >/dev/null 2>&1
+npm install "./$TGZ" >/dev/null 2>&1
+
+say "API smoke test"
+node - <<'NODE'
+const { reason } = require('eyeling');
+const input = `
+{ <http://example.org/s> <http://example.org/p> <http://example.org/o>. }
+  => { <http://example.org/s> <http://example.org/q> <http://example.org/o>. }.
+
+<http://example.org/s> <http://example.org/p> <http://example.org/o>.
+`;
+const out = reason({ proofComments: false }, input);
+if (!/<http:\/\/example\.org\/s>\s+<http:\/\/example\.org\/q>\s+<http:\/\/example\.org\/o>\s*\./.test(out)) {
+  console.error("Unexpected output:\n" + out);
+  process.exit(1);
+}
+NODE
+ok "API works"
+
+say "CLI smoke test"
+./node_modules/.bin/eyeling -v
+ok "CLI works"
+
+say "Examples test (installed package)"
+cd node_modules/eyeling/examples
+./test
+
+ok "packaged install smoke test passed"
+

package/test/packlist.test.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const cp = require('node:child_process');
+const fs = require('node:fs');
+
+const TTY = process.stdout.isTTY;
+const C = TTY
+  ? { g: '\x1b[32m', r: '\x1b[31m', y: '\x1b[33m', n: '\x1b[0m' }
+  : { g: '', r: '', y: '', n: '' };
+
+function ok(msg) { console.log(`${C.g}OK${C.n} ${msg}`); }
+function info(msg) { console.log(`${C.y}${msg}${C.n}`); }
+function fail(msg) { console.error(`${C.r}FAIL${C.n} ${msg}`); }
+
+try {
+  info('Checking packlist + metadata…');
+
+  const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+
+  assert.ok(pkg.name, 'package.json: name missing');
+  assert.ok(pkg.version, 'package.json: version missing');
+  assert.equal(pkg.main, './index.js', 'package.json: main should be ./index.js');
+  assert.ok(pkg.bin && pkg.bin.eyeling, 'package.json: bin.eyeling missing');
+
+  assert.ok(fs.existsSync('eyeling.js'), 'eyeling.js missing');
+  assert.ok(fs.existsSync('index.js'), 'index.js missing');
+
+  const firstLine = fs.readFileSync('eyeling.js', 'utf8').split(/\r?\n/, 1)[0];
+  assert.match(firstLine, /^#!\/usr\/bin\/env node\b/, 'eyeling.js should start with "#!/usr/bin/env node"');
+
+  let packJson;
+  try {
+    packJson = cp.execSync('npm pack --dry-run --json', { encoding: 'utf8' });
+  } catch (e) {
+    throw new Error('npm pack --dry-run --json failed\n' + (e.stderr || e.message));
+  }
+
+  const pack = JSON.parse(packJson)[0];
+  const paths = new Set(pack.files.map(f => f.path));
+
+  const mustHave = [
+    'package.json',
+    'README.md',
+    'LICENSE.md',
+    'eyeling.js',
+    'index.js',
+    'examples/test',
+  ];
+
+  for (const p of mustHave) assert.ok(paths.has(p), `missing from npm pack: ${p}`);
+
+  assert.ok(
+    [...paths].some(p => p.startsWith('examples/output/')),
+    'missing from npm pack: examples/output/*'
+  );
+
+  ok('packlist + metadata sanity checks passed');
+} catch (e) {
+  fail(e && e.stack ? e.stack : String(e));
+  process.exit(1);
+}
+