eyeling 1.18.0 → 1.18.2

package/HANDBOOK.md

@@ -1767,7 +1767,41 @@ For fully stream-oriented RDF/JS consumers there is also `reasonRdfJs(...)`, whi
 
 Eyeling exposes itself in three layers.
 
-### 14.1 The bundled CLI (`eyeling.js`)
+### 14.1 Install and first run
+
+Eyeling targets modern JavaScript runtimes. For the npm package and CLI workflow, use **Node.js 18 or newer**.
+
+Install from npm:
+
+```bash
+npm i eyeling
+```
+
+Run a file:
+
+```bash
+npx eyeling examples/socrates.n3
+```
+
+Show the available options:
+
+```bash
+npx eyeling --help
+```
+
+A few practical defaults are worth remembering:
+
+- In normal mode, Eyeling prints **newly derived forward facts**.
+- If the input contains top-level `log:query` directives, Eyeling prints the **query-selected conclusion triples** instead.
+- If the final closure contains any `log:outputString` triples, Eyeling renders those strings instead of emitting the default N3 result set.
+
+Custom builtins can be loaded explicitly from the CLI:
+
+```bash
+npx eyeling --builtin lib/builtin-sudoku.js examples/sudoku.n3
+```
+
+### 14.2 The bundled CLI (`eyeling.js`)
 
 The bundle contains the whole engine. The CLI path is the “canonical behavior”:
 
@@ -1777,7 +1811,7 @@ The bundle contains the whole engine. The CLI path is the “canonical behavior
 - optional proof comments
 - optional streaming
 
-#### 14.1.1 CLI options at a glance
+#### 14.2.1 CLI options at a glance
 
 The current CLI supports a small set of flags (see `lib/cli.js`):
 
@@ -1790,7 +1824,7 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 - `-v`, `--version` — print version and exit.
 - `-h`, `--help` — show usage.
 
-### 14.2 `lib/entry.js`: bundler-friendly exports
+### 14.3 `lib/entry.js`: bundler-friendly exports
 
 `lib/entry.js` exports:
 
@@ -1799,7 +1833,14 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 
 `rdfjs` is a small built-in RDF/JS `DataFactory`, so browser / worker code can construct quads without pulling in another package first.
 
-### 14.3 `index.js`: the npm API wrapper
+### 14.4 JavaScript API
+
+Eyeling exposes two JavaScript entry styles:
+
+- `reason(...)` from `index.js` when you want the same text output as the CLI
+- `reasonStream(...)` / `reasonRdfJs(...)` from the bundle entry when you want in-process reasoning and structured RDF/JS results
+
+#### 14.4.1 npm helper: `reason(...)`
 
 The npm `reason(...)` function does something intentionally simple and robust:
 
@@ -1810,19 +1851,141 @@ The npm `reason(...)` function does something intentionally simple and robust:
 
 This keeps the observable output identical to the CLI while still allowing richer JS-side inputs.
 
-In particular, the npm API now accepts:
+CommonJS:
+
+```js
+const { reason } = require('eyeling');
+
+const input = `
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
+@prefix : <http://example.org/socrates#>.
+
+:Socrates a :Human.
+:Human rdfs:subClassOf :Mortal.
+
+{ ?s a ?A. ?A rdfs:subClassOf ?B. } => { ?s a ?B. }.
+`;
+
+console.log(reason({ proofComments: false }, input));
+```
+
+ESM:
+
+```js
+import eyeling from 'eyeling';
+
+const input = `
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
+@prefix : <http://example.org/socrates#>.
+
+:Socrates a :Human.
+:Human rdfs:subClassOf :Mortal.
+
+{ ?s a ?A. ?A rdfs:subClassOf ?B. } => { ?s a ?B. }.
+`;
+
+console.log(eyeling.reason({ proofComments: false }, input));
+```
+
+Notes:
+
+- `reason()` returns the same textual output you would get from the CLI for the same input and options.
+- By default, the npm helper keeps output machine-friendly (`proofComments: false`).
+- Use this path when you want CLI-equivalent behavior inside JavaScript.
+
+#### 14.4.2 RDF-JS and Eyeling rule-object interoperability
+
+The JavaScript APIs accept three input styles:
+
+1. plain N3 text
+2. RDF/JS fact input (`quads`, `facts`, or `dataset`)
+3. Eyeling rule objects or full AST bundles
+
+If you want to use N3 source text, pass the whole input as a plain string.
+
+For RDF/JS facts, the graph must be the default graph. Named-graph quads are rejected.
+
+If you already have rules in structured form, Eyeling rule objects can be passed directly in the API:
+
+```js
+const { reason, rdfjs } = require('eyeling');
+
+const ex = 'http://example.org/';
+
+const rule = {
+  _type: 'Rule',
+  premise: [
+    {
+      _type: 'Triple',
+      s: { _type: 'Var', name: 'x' },
+      p: { _type: 'Iri', value: ex + 'parent' },
+      o: { _type: 'Var', name: 'y' },
+    },
+  ],
+  conclusion: [
+    {
+      _type: 'Triple',
+      s: { _type: 'Var', name: 'x' },
+      p: { _type: 'Iri', value: ex + 'ancestor' },
+      o: { _type: 'Var', name: 'y' },
+    },
+  ],
+  isForward: true,
+  isFuse: false,
+  headBlankLabels: [],
+};
+
+const out = reason(
+  { proofComments: false },
+  {
+    quads: [rdfjs.quad(rdfjs.namedNode(ex + 'alice'), rdfjs.namedNode(ex + 'parent'), rdfjs.namedNode(ex + 'bob'))],
+    rules: [rule],
+  },
+);
+
+console.log(out);
+```
+
+You can also pass a full AST bundle directly, for example `[prefixes, triples, forwardRules, backwardRules]`.
+
+#### 14.4.3 In-process bundle API: `reasonStream(...)` and `reasonRdfJs(...)`
+
+Use the bundle entry if you want structured results while the engine is running instead of final CLI text after the fact.
+
+`reasonStream(...)` can emit RDF/JS quads while reasoning runs:
+
+```js
+import eyeling from './eyeling.js';
+
+const result = eyeling.reasonStream(input, {
+  proof: false,
+  onDerived: ({ quad }) => {
+    if (quad) console.log(quad);
+  },
+});
+```
+
+That same path also lets derived results be consumed as an async stream of RDF/JS quads:
+
+```js
+for await (const quad of eyeling.reasonRdfJs(input)) {
+  console.log(quad);
+}
+```
 
-- raw N3 strings
-- RDF/JS fact inputs (`quads`, `facts`, or `dataset`)
-- Eyeling rule objects or full AST bundles like `[prefixes, triples, frules, brules]`
+Use these entry points when you need one or more of the following:
 
-For structured JavaScript input, rules are supplied as current Eyeling `Rule` / `Triple` object graphs or as JSON-serialized `--ast` output with `_type` markers.
+- RDF/JS quads as fact input
+- Eyeling rule objects passed directly from JavaScript
+- derived results consumed as RDF/JS quads
+- streaming derived RDF/JS quads during reasoning
 
-If you want to use N3 source text, pass the whole input as a plain N3 string.
+### 14.5 Choosing the right entry point
 
-One practical implication remains:
+A practical rule of thumb:
 
-- if you want _in-process_ access to the engine objects (facts arrays, derived proof objects), use `reasonStream` / `reasonRdfJs` from the bundle entry rather than the subprocess-based API.
+- if you want the same final text output as the CLI, use `reason(...)`
+- if you want in-process access to structured facts, quads, or streaming derivations, use `reasonStream(...)` / `reasonRdfJs(...)`
 
 ---
 

package/README.md

@@ -4,218 +4,16 @@
 
 A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 
-- Single self-contained bundle (`eyeling.js`), no external runtime dependencies
-- Forward (`=>`) and backward (`<=`) chaining over Horn-style rules
-- **CLI / npm `reason()` output is mode-dependent by default**: it prints **newly derived forward facts** in normal mode, or (when top-level `{ ... } log:query { ... }.` directives are present) the **unique instantiated conclusion triples** of those queries, optionally with compact proof comments
-- Works in Node.js and fully client-side (browser/worker)
-
-## Links
-
-- **Handbook:** [https://eyereasoner.github.io/eyeling/HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK)
-- **Semantics:** [https://eyereasoner.github.io/eyeling/SEMANTICS](https://eyereasoner.github.io/eyeling/SEMANTICS)
-- **Playground:** [https://eyereasoner.github.io/eyeling/demo](https://eyereasoner.github.io/eyeling/demo)
-- **Conformance report:** [https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md](https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md)
-
-Eyeling is regularly checked against the community Notation3 test suite. If you want implementation details (parser, unifier, proof search, skolemization, scoped closure, builtins), start with the handbook.
-
 ## Quick start
 
-### Requirements
-
-- Node.js >= 18
-
-### Install
-
 ```bash
 npm i eyeling
-```
-
-## CLI usage
-
-Run on a file:
-
-```bash
 npx eyeling examples/socrates.n3
 ```
 
-Show all options:
-
-```bash
-npx eyeling --help
-```
-
-Useful flags include `--proof-comments`, `--stream`, and `--enforce-https`. If the final closure contains any `log:outputString` triples, Eyeling now renders those strings automatically instead of printing N3 output.
-
-## What gets printed?
-
-### Normal mode (default)
-
-Without top-level `log:query` directives, Eyeling prints **newly derived forward facts** by default.
-
-### `log:query` mode (output selection)
-
-If the input contains one or more **top-level** directives of the form:
-
-```n3
-{ ?x a :Human. } log:query { ?x a :Mortal. }.
-```
-
-Eyeling still computes the saturated forward closure, but it **prints only** the **unique instantiated conclusion triples** of those `log:query` directives (instead of all newly derived forward facts).
-
-## JavaScript API
-
-### npm helper: `reason()`
-
-CommonJS:
-
-```js
-const { reason } = require('eyeling');
-
-const input = `
-@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
-@prefix : <http://example.org/socrates#>.
-
-:Socrates a :Human.
-:Human rdfs:subClassOf :Mortal.
-
-{ ?s a ?A. ?A rdfs:subClassOf ?B. } => { ?s a ?B. }.
-`;
-
-console.log(reason({ proofComments: false }, input));
-```
-
-ESM:
-
-```js
-import eyeling from 'eyeling';
-
-console.log(eyeling.reason({ proofComments: false }, input));
-```
-
-Notes:
-
-- `reason()` returns the same textual output you would get from the CLI for the same input/options.
-- By default, the npm helper keeps output machine-friendly (`proofComments: false`).
-- The npm helper shells out to the bundled `eyeling.js` CLI for simplicity and robustness.
-
-### RDF/JS and Eyeling rule-object interop
-
-The JavaScript APIs now accept three input styles:
-
-1. plain N3 text
-2. RDF/JS facts (`quads`, `facts`, or `dataset`)
-3. Eyeling rule objects / AST bundles (the same shapes you get from `eyeling --ast`)
-
-If you want to use N3 source text, pass the whole input as a plain N3 string.
-
-For RDF/JS facts, the graph must be the default graph. Named-graph quads are rejected.
-
-For structured inputs, `rules` is supplied as current Eyeling rule objects:
-
-```js
-const { reason, rdfjs } = require('eyeling');
-
-const ex = 'http://example.org/';
-
-const rule = {
-  _type: 'Rule',
-  premise: [
-    {
-      _type: 'Triple',
-      s: { _type: 'Var', name: 'x' },
-      p: { _type: 'Iri', value: ex + 'parent' },
-      o: { _type: 'Var', name: 'y' },
-    },
-  ],
-  conclusion: [
-    {
-      _type: 'Triple',
-      s: { _type: 'Var', name: 'x' },
-      p: { _type: 'Iri', value: ex + 'ancestor' },
-      o: { _type: 'Var', name: 'y' },
-    },
-  ],
-  isForward: true,
-  isFuse: false,
-  headBlankLabels: [],
-};
-
-const out = reason(
-  { proofComments: false },
-  {
-    quads: [rdfjs.quad(rdfjs.namedNode(ex + 'alice'), rdfjs.namedNode(ex + 'parent'), rdfjs.namedNode(ex + 'bob'))],
-    rules: [rule],
-  },
-);
-```
-
-You can also pass a full AST bundle directly:
-
-```js
-const ast = [prefixes, triples, forwardRules, backwardRules];
-const out2 = reason({ proofComments: false }, ast);
-```
-
-### Direct bundle / browser-worker API: `reasonStream()`
-
-For in-process reasoning (browser, worker, or direct use of `eyeling.js`):
-
-```js
-const result = eyeling.reasonStream(input, {
-  proof: false,
-  onDerived: ({ triple }) => console.log(triple),
-  // includeInputFactsInClosure: false,
-});
-
-console.log(result.closureN3);
-```
-
-`eyeling.js` now also exposes `eyeling.rdfjs` and `eyeling.reasonRdfJs(...)` for RDF/JS workflows.
-
-#### `reasonStream()` output behavior
-
-`closureN3` is also mode-dependent:
-
-- **Normal mode:** by default, `closureN3` is the closure (**input facts + derived facts**)
-- **`log:query` mode:** `closureN3` is the **query-selected triples**
-
-To exclude input facts from the normal-mode closure, pass:
-
-```js
-includeInputFactsInClosure: false;
-```
-
-When `rdfjs: true` is passed, `onDerived` also receives a `quad` field and the result may include `closureQuads` / `queryQuads`.
-
-The returned object also includes `queryMode`, `queryTriples`, and `queryDerived` (and in normal mode, `onDerived` fires for newly derived facts; in `log:query` mode it fires for the query-selected derived triples).
-
-### `reasonRdfJs()`
-
-`reasonRdfJs(input, opts)` exposes derived results as an async iterable of RDF/JS quads as they are produced:
-
-```js
-const { reasonRdfJs, rdfjs } = require('eyeling');
-
-for await (const quad of reasonRdfJs({
-  quads: [rdfjs.quad(rdfjs.namedNode(ex + 'alice'), rdfjs.namedNode(ex + 'parent'), rdfjs.namedNode(ex + 'bob'))],
-  rules: [rule],
-})) {
-  console.log(quad.subject.value, quad.predicate.value, quad.object.value);
-}
-```
-
-## Builtins
-
-Builtins are defined in [eyeling-builtins.ttl](https://github.com/eyereasoner/eyeling/blob/main/eyeling-builtins.ttl) and described in the [Handbook (Chapter 11)](https://eyereasoner.github.io/eyeling/HANDBOOK#ch11).
-
-## Development and testing (repo checkout)
-
-```bash
-npm test
-```
-
-You can also inspect the `examples/` directory for many small and large N3 programs.
-
-## License
+## Read more
 
-MIT — see [LICENSE.md](https://github.com/eyereasoner/eyeling/blob/main/LICENSE.md).
+- **Handbook:** [eyereasoner.github.io/eyeling/HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK)
+- **Playground:** [eyereasoner.github.io/eyeling/demo](https://eyereasoner.github.io/eyeling/demo)
+- **Semantics:** [eyereasoner.github.io/eyeling/SEMANTICS](https://eyereasoner.github.io/eyeling/SEMANTICS)
+- **Conformance report:** [codeberg.org/phochste/notation3tests/.../report.md](https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md)

package/examples/sudoku.n3

@@ -115,7 +115,7 @@
                      log:outputString "\n" ;
                      log:outputString "Completed grid\n" ;
                      log:outputString ?solutionText ;
-                     log:outputString "\n" .
+                     log:outputString "\n\n" .
          :02-reason log:outputString "=== Reason Why ===\n" ;
                     log:outputString ?reasonText ;
                     log:outputString "\n\n" .

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.18.0",
+  "version": "1.18.2",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [