eyeling 1.17.2 → 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.
@@ -1870,28 +2004,162 @@ That’s the whole engine in miniature: unify, compose substitutions, emit head
 
 Eyeling is small, which makes it pleasant to extend — but there are a few invariants worth respecting.
 
-### 16.1 Adding a builtin
+The most important update is architectural: **you no longer need to patch `lib/builtins.js` just to add a project-specific builtin**. The preferred path is now to load a custom builtin module, either programmatically or from the CLI. Core builtins still live in `lib/builtins.js`, but user extensions can stay outside the engine.
+
+### 16.1 The preferred path: custom builtin modules
 
-Most extensions belong in `lib/builtins.js` (inside `evalBuiltin`):
+Eyeling now exposes a small custom-builtin registry.
 
-- Decide if your builtin is:
-  - a test (0/1 solution)
-  - functional (bind output)
-  - generator (many solutions)
-- Return _deltas_ `{ varName: Term }`, not full substitutions.
-- Be cautious with fully-unbound cases: generators can explode the search space.
-- If you add a _new predicate_ (not just a new case inside an existing namespace), make sure it is recognized by `isBuiltinPred(...)`.
+At runtime, builtin predicates can be added with:
 
-A small architectural note: `lib/builtins.js` is initialized by the engine via `makeBuiltins(deps)`. It receives hooks (unification, proving, deref, scoped-closure helpers, …) instead of importing the engine directly, which keeps the module graph acyclic and makes browser bundling easier.
+- `registerBuiltin(iri, handler)`
+- `unregisterBuiltin(iri)`
+- `registerBuiltinModule(moduleExport, origin?)`
+- `loadBuiltinModule(specifier, { resolveFrom? })`
+- `listBuiltinIris()`
+
+That means the extension story is:
+
+- keep the engine’s shipped builtins in `lib/builtins.js`
+- keep your own application or domain builtins in a separate `.js` module
+- load that module with `--builtin` or from JavaScript
+
+This is the safest way to extend Eyeling because it avoids forking the builtin dispatcher and keeps upgrades merge-friendly.
+
+### 16.2 CLI loading: `--builtin`
+
+The CLI accepts a repeatable `--builtin <module.js>` option:
+
+```bash
+eyeling --builtin ./hello-builtin.js rules.n3
+```
+
+You can pass it more than once:
+
+```bash
+eyeling --builtin ./math-extra.js --builtin ./domain-rules.js input.n3
+```
+
+Each module is loaded before reasoning starts. Paths are resolved from the current working directory.
+
+The same capability is available through the npm wrapper:
+
+```js
+const { reason } = require('eyeling');
+const out = reason({ builtinModules: ['./hello-builtin.js'] }, n3Text);
+```
+
+### 16.3 What a builtin module may export
+
+Eyeling accepts three module shapes.
+
+#### A function export
+
+```js
+module.exports = ({ registerBuiltin, internLiteral, unifyTerm, terms }) => {
+  const { Var } = terms;
+
+  registerBuiltin('http://example.org/custom#hello', ({ goal, subst }) => {
+    const lit = internLiteral('"world"');
+    if (goal.o instanceof Var) {
+      return [{ ...subst, [goal.o.name]: lit }];
+    }
+    const s2 = unifyTerm(goal.o, lit, subst);
+    return s2 ? [s2] : [];
+  });
+};
+```
+
+#### An object with `register(api)`
+
+```js
+module.exports = {
+  register(api) {
+    api.registerBuiltin('http://example.org/custom#ping', ({ subst }) => [subst]);
+  },
+};
+```
+
+#### A plain object mapping predicate IRIs to handlers
+
+```js
+module.exports = {
+  'http://example.org/custom#ok': ({ subst }) => [subst],
+};
+```
+
+If none of those shapes match, Eyeling rejects the module with a descriptive error.
+
+### 16.4 The handler contract
+
+Builtin handlers are called with a context object like:
+
+- `iri` — the predicate IRI string
+- `goal` — the current triple goal
+- `subst` — the current substitution
+- `facts`, `backRules`, `depth`, `varGen`, `maxResults`
+- `api` — the same registration/helper API used by modules
+
+A handler returns **an array of substitutions**:
+
+- `[]` means failure / no solutions
+- `[subst2]` means one successful continuation
+- multiple substitutions mean a generator builtin
+
+In practice:
+
+- Decide if your builtin is a test, a functional relation, or a generator.
+- Return substitutions (or substitution deltas merged into the current substitution), not printed output.
+- Be cautious with fully-unbound generators: they can explode the search space.
+- If a builtin needs inputs to be bound first, it is fine to fail early and let forward-rule proving retry later in the conjunction.
+
+Custom builtin failures are wrapped so the predicate IRI appears in the thrown error message, which makes debugging much easier from the CLI.
+
+### 16.5 The helper API exposed to builtin modules
+
+Builtin modules do not need to import internal engine files directly. Eyeling passes a helper API into module registration, including:
+
+- registration helpers: `registerBuiltin`, `unregisterBuiltin`, `listBuiltinIris`
+- term constructors via `terms` (`Literal`, `Iri`, `Var`, `Blank`, `ListTerm`, `GraphTerm`, `Triple`, `Rule`, ...)
+- literal/term helpers such as `internLiteral`, `internIri`, `literalParts`, `termToN3`, `termToJsString`
+- reasoning helpers such as `unifyTerm`, `applySubstTerm`, `applySubstTriple`, `proveGoals`
+- namespace constants via `ns`
+
+That API keeps the extension boundary explicit: custom builtins get the operations they need without reaching into Eyeling’s private module graph.
+
+### 16.6 A shipped example: the Sudoku builtin
+
+The repository now ships a Sudoku builtin module (`lib/builtin-sudoku.js`) and a matching example program (`sudoku.n3`).
+
+So this works out of the box:
+
+```bash
+eyeling sudoku.n3
+```
+
+That example is useful for two reasons:
+
+- it shows a realistic domain-specific builtin implemented outside the core builtin switchboard
+- it demonstrates the intended deployment model for larger custom relations: keep the N3 logic in the `.n3` file, and keep specialized search/verification code in a loadable builtin module
+
+### 16.7 When you should still edit `lib/builtins.js`
+
+Editing `lib/builtins.js` is still reasonable when you are:
+
+- adding or fixing a **core** Eyeling builtin
+- changing builtin behavior that should ship as part of Eyeling itself
+- modifying the builtin helper API that custom modules depend on
+
+But if the builtin is project-specific, experimental, or domain-bound, prefer a custom module first.
+
+A small architectural note: `lib/builtins.js` is still initialized by the engine via `makeBuiltins(deps)`. It receives hooks (unification, proving, deref, scoped-closure helpers, …) instead of importing the engine directly, which keeps the module graph acyclic and makes browser bundling easier.
 
 If your builtin needs a stable view of the scoped closure, follow the scoped-builtin pattern:
 
 - read from `facts.__scopedSnapshot`
 - honor `facts.__scopedClosureLevel` and priority gating
 
-And if your builtin is “forward-only” (needs inputs bound), it’s fine to **fail early** until inputs are available — forward rule proving enables builtin deferral, so the goal can be retried later in the same conjunction.
-
-### 16.2 Adding new term shapes
+### 16.8 Adding new term shapes
 
 If you add a new Term subclass, you’ll likely need to touch:
 
@@ -1900,7 +2168,7 @@ If you add a new Term subclass, you’ll likely need to touch:
 - variable collection for compaction (`gcCollectVarsInTerm`)
 - groundness checks
 
-### 16.3 Parser extensions
+### 16.9 Parser extensions
 
 If you extend parsing, preserve the Rule invariants:
 
@@ -1983,6 +2251,7 @@ Options:
 
 ```
   -a, --ast                    Print parsed AST as JSON and exit.
+      --builtin <module.js>    Load a custom builtin module (repeatable).
   -d, --deterministic-skolem   Make log:skolem stable across reasoning runs.
   -e, --enforce-https          Rewrite http:// IRIs to https:// for log dereferencing builtins.
   -h, --help                   Show this help and exit.
@@ -2037,10 +2306,23 @@ See also:
 
 Eyeling supports a built-in “standard library” across namespaces like `log:`, `math:`, `string:`, `list:`, `time:`, `crypto:`.
 
+It also supports **custom builtin modules**.
+
+- From the CLI: `eyeling --builtin ./my-builtins.js input.n3`
+- From JavaScript: `reason({ builtinModules: ['./my-builtins.js'] }, input)`
+- Programmatically in-process: `registerBuiltin(...)`, `registerBuiltinModule(...)`, `loadBuiltinModule(...)`
+
+A concrete shipped example is the Sudoku builtin and the root-level `sudoku.n3` program:
+
+```bash
+eyeling sudoku.n3
+```
+
 References:
 
 - W3C N3 Built-ins overview: [https://w3c.github.io/N3/reports/20230703/builtins.html](https://w3c.github.io/N3/reports/20230703/builtins.html)
 - Eyeling implementation details: [Chapter 11 — Built-ins as a standard library](#ch11)
+- Extension API and custom module loading: [Chapter 16 — Extending Eyeling (without breaking it)](#ch16)
 - The shipped builtin catalogue: `eyeling-builtins.ttl` (in this repo)
 
 If you are running untrusted inputs, consider `--super-restricted` to disable all builtins except implication.

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)