eyeling 1.15.13 → 1.16.0

package/HANDBOOK.md

@@ -1747,6 +1747,13 @@ The engine’s `reasonStream` API can accept an `onDerived` callback. Each time
 
 This is especially useful in interactive demos (and is the basis of the playground streaming tab).
 
+The same API can now also emit RDF/JS output. When `rdfjs: true` is passed, every `onDerived(...)` payload includes both:
+
+- `triple` — Eyeling’s N3 string form
+- `quad` — the same fact as an RDF/JS default-graph quad
+
+For fully stream-oriented RDF/JS consumers there is also `reasonRdfJs(...)`, which exposes the derived facts as an async iterable of RDF/JS quads.
+
 ---
 
 <a id="ch14"></a>
@@ -1783,22 +1790,35 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 
 `lib/entry.js` exports:
 
-- public APIs: `reasonStream`, `main`, `version`
+- public APIs: `reasonStream`, `reasonRdfJs`, `rdfjs`, `main`, `version`
 - plus a curated set of internals used by the demo (`lex`, `Parser`, `forwardChain`, etc.)
 
+`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
 
 The npm `reason(...)` function does something intentionally simple and robust:
 
-- write your N3 input to a temp file
+- normalize the JavaScript input into N3 text
+- write that N3 input to a temp file
 - spawn the bundled CLI (`node eyeling.js ... input.n3`)
 - return stdout (and forward stderr)
 
-This ensures the API matches the CLI perfectly and keeps the public surface small.
+This keeps the observable output identical to the CLI while still allowing richer JS-side inputs.
+
+In particular, the npm API now accepts:
+
+- raw N3 strings
+- RDF/JS fact inputs (`quads`, `facts`, or `dataset`)
+- Eyeling rule objects or full AST bundles like `[prefixes, triples, frules, brules]`
+
+For structured JavaScript input, rules are supplied as current Eyeling `Rule` / `Triple` object graphs or as JSON-serialized `--ast` output with `_type` markers.
+
+If you want to use N3 source text, pass the whole input as a plain N3 string.
 
-One practical implication:
+One practical implication remains:
 
-- if you want _in-process_ access to the engine objects (facts arrays, derived proof objects), use `reasonStream` from the bundle entry rather than the subprocess-based API.
+- 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

@@ -15,7 +15,7 @@ A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 - **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)
-- **Follows From:** [https://eyereasoner.github.io/eyeling/follows-from/](https://eyereasoner.github.io/eyeling/follows-from/)
+- **ARCtifacts:** [https://eyereasoner.github.io/eyeling/arctifacts/](https://eyereasoner.github.io/eyeling/arctifacts/)
 
 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.
 
@@ -99,6 +99,64 @@ Notes:
 - 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`):
@@ -113,6 +171,8 @@ const result = eyeling.reasonStream(input, {
 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:
@@ -126,8 +186,25 @@ To exclude input facts from the normal-mode closure, pass:
 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).

package/arctifacts/README.md

@@ -0,0 +1,57 @@
+# ARCtifacts
+
+ARCtifacts are trustworthy programs telling a concise story in three parts. First comes the **Answer** to a specific question. This is followed by the **Reason Why** that answer is correct, articulated in everyday language and supported by the relevant identities, rules, or ideas. Finally, every case includes a **Check**—a concrete test designed to fail loudly if an assumption doesn't hold or an edge case bites. The result is a computation with a complete, auditable trail: you can see precisely what was done, why it was valid, and how the page verifies its own work.
+
+## Science
+
+- [**Body Mass Index**](https://eyereasoner.github.io/eyeling/arctifacts/bmi.html) — Compute BMI categories with explainable thresholds and sanity checks.
+- [**Earthquake Epicenter**](https://eyereasoner.github.io/eyeling/arctifacts/earthquake-epicenter.html) — Infer an earthquake’s epicenter from P- and S-wave arrivals and verify with distance and timing checks.
+- [**Exoplanet Transit**](https://eyereasoner.github.io/eyeling/arctifacts/exoplanet-transit.html) — Infer a planet’s size and orbit from a transit light curve, with explainable formulas and consistency checks.
+- [**Grass Seed Germination**](https://eyereasoner.github.io/eyeling/arctifacts/grass-molecular.html) — Model germination states and transitions with rule checks.
+- [**Leg Length Discrepancy Measurement**](https://eyereasoner.github.io/eyeling/arctifacts/lldm.html) — Leg Length Discrepancy Measurement from four landmarks.
+
+## Technology
+
+- [**Auroracare**](https://eyereasoner.github.io/eyeling/arctifacts/auroracare.html) — Purpose-based Medical Data Exchange.
+- [**Clinical Care Planning**](https://eyereasoner.github.io/eyeling/arctifacts/clinical-care.html) — Derive care plans from observations, guidelines, and policy constraints.
+- [**Delfour**](https://eyereasoner.github.io/eyeling/arctifacts/delfour.html) — Ruben Verborgh's "Inside the Insight Economy" case.
+- [**GPS Clinical Bench**](https://eyereasoner.github.io/eyeling/arctifacts/gps-clinical-bench.html) — Benchmark clinical decisions with transparent rules and audit trails.
+- [**Graph of French Cities**](https://eyereasoner.github.io/eyeling/arctifacts/graph-french.html) — Shortest paths and connectivity over a city graph with proofs.
+- [**Health Information Processing**](https://eyereasoner.github.io/eyeling/arctifacts/health-info.html) — Transform clinical payloads with typed rules and validation.
+- [**Linked Lists**](https://eyereasoner.github.io/eyeling/arctifacts/linked-lists.html) — Term logic example proved using Resolution.
+- [**REST-Path**](https://eyereasoner.github.io/eyeling/arctifacts/rest-path.html) — Explain link-following over REST resources; verify pre/post conditions.
+- [**Turing Machine**](https://eyereasoner.github.io/eyeling/arctifacts/turing.html) — Run tapes with explicit transitions; verify halting and tape contents.
+
+## Engineering
+
+- [**Bike Trip Planning**](https://eyereasoner.github.io/eyeling/arctifacts/bike-trip.html) — Route priorities from hazards, preferences, and declarative JSON rules.
+- [**Building Performance**](https://eyereasoner.github.io/eyeling/arctifacts/building-performance.html) — Reason about energy/comfort metrics and verify rule-based outcomes.
+- [**Control System**](https://eyereasoner.github.io/eyeling/arctifacts/control-system.html) — Model simple feedback loops and verify stability/response conditions.
+- [**Eco-Route**](https://eyereasoner.github.io/eyeling/arctifacts/eco-route.html) — Pick lower-emission routes by fusing traffic, grade, and policy goals.
+- [**GPS Bike**](https://eyereasoner.github.io/eyeling/arctifacts/gps-bike.html) — GPS for bike trip Gent → Maasmechelen.
+- [**Lee**](https://eyereasoner.github.io/eyeling/arctifacts/lee.html) — Maze routing with Lee’s algorithm; trace optimal wavefront paths.
+- [**Wind-Turbine Maintenance**](https://eyereasoner.github.io/eyeling/arctifacts/wind-turbines.html) — Plan maintenance from telemetry and policies with auditable outcomes.
+
+## Mathematics
+
+- [**Ackermann**](https://eyereasoner.github.io/eyeling/arctifacts/ackermann.html) — Compute A₂ with exact hyper-ops; print small, expand huge safely.
+- [**Binomial Theorem**](https://eyereasoner.github.io/eyeling/arctifacts/binomial-theorem.html) — Sum of all binomial coefficients.
+- [**Collatz**](https://eyereasoner.github.io/eyeling/arctifacts/collatz.html) — Generate trajectories and check invariants for the Collatz map.
+- [**Complex Identities**](https://eyereasoner.github.io/eyeling/arctifacts/complex.html) — Symbolic steps for complex-number equalities with auditable reasoning.
+- [**Euclid’s Infinitude of Primes**](https://eyereasoner.github.io/eyeling/arctifacts/euclid-infinitude.html) — Restate the theorem, explain Euclid’s one-line proof, and run computational checks.
+- [**Euler’s Identity**](https://eyereasoner.github.io/eyeling/arctifacts/euler-identity.html) — The most beautiful equation in mathematics.
+- [**Faltings' Theorem**](https://eyereasoner.github.io/eyeling/arctifacts/faltings-theorem.html) — Explore genus 0, 1, and 2 curves, and see why genus ≥ 2 leads to only finitely many rational points.
+- [**Fibonacci**](https://eyereasoner.github.io/eyeling/arctifacts/fibonacci.html) — Compute big Fₙ with fast-doubling recurrences and proof-style checks.
+- [**Fundamental Theorem of Arithmetic**](https://eyereasoner.github.io/eyeling/arctifacts/fundamental-theorem-arithmetic.html) — Every integer factors as a product of primes.
+- [**Gödel Numbering**](https://eyereasoner.github.io/eyeling/arctifacts/godel-numbering.html) — A classic Gödel numbering demonstrator.
+- [**Group Theory**](https://eyereasoner.github.io/eyeling/arctifacts/group-theory.html) — Verify closure, identity, inverses, and associativity on examples.
+- [**Kaprekar’s Constant**](https://eyereasoner.github.io/eyeling/arctifacts/kaprekar-constant.html) — Exhaustive sweep of every 4-digit state in Kaprekar’s routine.
+- [**Matrix Basics**](https://eyereasoner.github.io/eyeling/arctifacts/matrix.html) — Add/multiply/invert with dimension/property checks.
+- [**Matrix Multiplication**](https://eyereasoner.github.io/eyeling/arctifacts/matrix-multiplication.html) — Not commutative (AB ≠ BA).
+- [**Newton–Raphson**](https://eyereasoner.github.io/eyeling/arctifacts/newton-raphson.html) — Newton–Raphson method for root-finding.
+- [**Peano Factorial**](https://eyereasoner.github.io/eyeling/arctifacts/peano-factorial.html) — 5! = 120 proved via Resolution.
+- [**Pi**](https://eyereasoner.github.io/eyeling/arctifacts/pi.html) — High-precision π via Chudnovsky series with error-bound checks.
+- [**Polynomial Roots**](https://eyereasoner.github.io/eyeling/arctifacts/polynomial.html) — Find all roots simultaneously; prove convergence on typical cases.
+- [**Primes**](https://eyereasoner.github.io/eyeling/arctifacts/prime.html) — Generate/test primes; log certs (trial factors or proofs) as checks.
+- [**Pythagorean Theorem**](https://eyereasoner.github.io/eyeling/arctifacts/pythagorean-theorem.html) — Compute legs/hypotenuse and confirm with algebraic or area proofs.
+- [**Roots of Unity**](https://eyereasoner.github.io/eyeling/arctifacts/roots-of-unity.html) — Place complex n-th roots on the unit circle; check spacing and sums/products.