eyeling 1.18.0 → 1.18.1

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,7 @@ 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 `index.js`: the npm API wrapper
 
 The npm `reason(...)` function does something intentionally simple and robust:
 
@@ -1820,6 +1854,106 @@ For structured JavaScript input, rules are supplied as current Eyeling `Rule` /
 
 If you want to use N3 source text, pass the whole input as a plain N3 string.
 
+#### 14.4.1 RDF/JS quads as fact input
+
+Eyeling can take RDF/JS quads directly as its fact input. At the npm API boundary, the input object may provide any of:
+
+- `quads`
+- `facts`
+- `dataset`
+
+Each is treated as an iterable of RDF/JS **default-graph** quads and converted into Eyeling’s internal triple form before reasoning starts.
+
+```js
+const { reason, rdfjs } = require('eyeling');
+
+const input = {
+  quads: [
+    rdfjs.quad(
+      rdfjs.namedNode('http://example.org/Socrates'),
+      rdfjs.namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+      rdfjs.namedNode('http://example.org/Human'),
+    ),
+  ],
+  n3: `
+    @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
+    @prefix : <http://example.org/>.
+    :Human rdfs:subClassOf :Mortal.
+    { ?x a ?c. ?c rdfs:subClassOf ?d. } => { ?x a ?d. }.
+  `,
+};
+
+const out = reason(input);
+```
+
+The important point is architectural: RDF/JS quads can be used as the **fact channel**, while rules may still come from N3 text or Eyeling rule objects. Named-graph quads are intentionally rejected here; Eyeling’s input model is triple-oriented and expects the default graph only.
+
+#### 14.4.2 Passing Eyeling rule objects directly
+
+The JS API also accepts Eyeling rule objects directly, so you do not have to serialize everything back into N3 first.
+
+That means an input such as this is valid:
+
+```js
+const { reason } = require('eyeling');
+
+const input = {
+  triples: [
+    /* Eyeling Triple objects */
+  ],
+  forwardRules: [
+    /* Eyeling Rule objects */
+  ],
+  backwardRules: [
+    /* optional Eyeling Rule objects */
+  ],
+};
+
+const out = reason(input);
+```
+
+The accepted shapes are intentionally flexible:
+
+- `triples`
+- `forwardRules` or `frules`
+- `backwardRules` or `brules`
+- `queryRules`, `logQueryRules`, or `qrules`
+- a full AST bundle like `[prefixes, triples, frules, brules, queryRules]`
+
+So Eyeling rule objects can be passed directly in the API, either as separate arrays or bundled into the same object graph the parser itself uses.
+
+#### 14.4.3 Consuming derived RDF/JS results
+
+There are two main ways to consume derived results in RDF/JS form.
+
+First, `reasonStream(...)` can emit RDF/JS quads **while reasoning runs**. Pass `rdfjs: true` and an `onDerived(...)` callback:
+
+```js
+const { reasonStream } = require('eyeling/lib/entry');
+
+reasonStream(input, {
+  rdfjs: true,
+  onDerived({ triple, quad }) {
+    // triple = Eyeling's N3 string form
+    // quad   = RDF/JS Quad for the same derived fact
+  },
+});
+```
+
+This is the “push” interface: each newly derived forward fact is reported as soon as it is produced.
+
+Second, `reasonRdfJs(...)` exposes the same derived results as an **async stream of RDF/JS quads**:
+
+```js
+const { reasonRdfJs } = require('eyeling/lib/entry');
+
+for await (const quad of reasonRdfJs(input)) {
+  // consume RDF/JS quads incrementally
+}
+```
+
+This is the “pull” interface: the consumer iterates an async iterable of quads instead of registering a callback.
+
 One practical implication remains:
 
 - 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.

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)
+- **Semantics:** [eyereasoner.github.io/eyeling/SEMANTICS](https://eyereasoner.github.io/eyeling/SEMANTICS)
+- **Playground:** [eyereasoner.github.io/eyeling/demo](https://eyereasoner.github.io/eyeling/demo)
+- **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.1",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [