eyeling 1.23.1 → 1.23.3

package/HANDBOOK.md

@@ -1874,7 +1874,7 @@ echo '@prefix : <http://example.org/> .
 { ?x a :Man } => { ?x a :Mortal } .' | npx eyeling
 ```
 
-You can also pass one or more file paths/URLs, or `-` to read explicitly from stdin. When multiple inputs are given, Eyeling parses each source separately, merges the parsed ASTs, and then runs one reasoning pass over the combined facts and rules. This avoids constructing one giant N3 source string.
+You can also pass one or more file paths/URLs, or `-` to read explicitly from stdin. When multiple inputs are given, Eyeling parses each source separately, merges the parsed ASTs, and then runs one reasoning pass over the combined facts and rules. This avoids constructing one giant N3 source string. During the merge path, parse-only artifacts such as source text and token arrays are discarded after the AST has been built, except while formatting syntax errors or when an internal caller explicitly asks to keep those artifacts for debugging.
 
 Show the available options:
 
@@ -1891,9 +1891,17 @@ A few practical defaults are worth remembering:
 Custom builtins can be loaded explicitly from the CLI:
 
 ```bash
-npx eyeling --builtin lib/builtin-sudoku.js examples/sudoku.n3
+npx eyeling --builtin examples/builtin/sudoku.js examples/sudoku.n3
 ```
 
+Example-specific builtins live under `examples/builtin/`. When the examples test runner sees `examples/builtin/<stem>.js` next to `examples/<stem>.n3`, it auto-loads that builtin for the matching example by running the same command shape a user would run manually:
+
+```bash
+node eyeling.js --builtin examples/builtin/queens.js examples/queens.n3
+```
+
+Examples that do not need a custom builtin should not add a matching file under `examples/builtin/`. Examples that do need one should ship it there and let the examples test runner load it uniformly. For example, `examples/sudoku.n3` is paired with `examples/builtin/sudoku.js`, and `examples/queens.n3` is paired with `examples/builtin/queens.js`.
+
 ### 14.2 The bundled Node CLI/runtime (`eyeling.js`)
 
 The bundle contains the whole engine. The CLI path is the “canonical behavior”:
@@ -2057,6 +2065,8 @@ console.log(out);
 
 In a source list, each source is parsed with its own blank-node scope and optional base IRI. That means the same explicit blank label, such as `_:x`, in two different sources does not accidentally become the same blank node after merging. Prefix declarations are merged mainly for readable output; IRI expansion has already happened while each source was parsed.
 
+For large inputs, the source-list path is also the preferred memory shape: each source is lexed and parsed independently, then Eyeling keeps the merged facts/rules rather than retaining the original source strings and token arrays. The parser still needs one JavaScript string per source, so source splitting is not a streaming parser, but it avoids both a single giant concatenated N3 string and long-lived token arrays after parsing.
+
 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:
@@ -2374,14 +2384,16 @@ That API keeps the extension boundary explicit: custom builtins get the operatio
 
 ### 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`).
+The repository ships a Sudoku example program (`examples/sudoku.n3`) together with its example-specific builtin module (`examples/builtin/sudoku.js`).
 
-So this works out of the box:
+Run it explicitly like this:
 
 ```bash
-eyeling sudoku.n3
+eyeling --builtin examples/builtin/sudoku.js examples/sudoku.n3
 ```
 
+`npm run test:examples` uses the same convention automatically: when it sees `examples/builtin/sudoku.js` next to `examples/sudoku.n3`, it loads that module for the Sudoku example.
+
 That example is useful for two reasons:
 
 - it shows a realistic domain-specific builtin implemented outside the core builtin switchboard
@@ -2565,10 +2577,10 @@ It also supports **custom builtin modules**.
 - 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:
+A concrete shipped example is the Sudoku builtin paired with `examples/sudoku.n3`:
 
 ```bash
-eyeling sudoku.n3
+eyeling --builtin examples/builtin/sudoku.js examples/sudoku.n3
 ```
 
 References: