eyeleng 1.1.1 → 1.2.0

package/README.md

@@ -3,15 +3,49 @@
 [![npm version](https://img.shields.io/npm/v/eyeleng.svg)](https://www.npmjs.com/package/eyeleng)
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20342577-blue.svg)](https://doi.org/10.5281/zenodo.20342577)
 
-`eyeleng` stands for **EYE Logic Engine**. It is a compact JavaScript implementation of SHACL 1.2 Rules with two rule front-ends:
+The `leng` in `eyeleng` stands for **Logic Engine Next Generation**. Eyeleng's main purpose is **automatic hybrid reasoning**: it combines forward materialization with tabled backward proving and automatically chooses how rules should be evaluated.
+
+Eyeleng is a compact JavaScript implementation of SHACL 1.2 Rules with two rule front-ends:
 
 - **SRL** — the Shape Rules Language syntax used by the SHACL 1.2 Rules draft.
 - **RDF Rules** — a Turtle/RDF syntax for rule sets.
 
-Eyeleng is a forward-chaining reasoner over RDF-style triples. It is deliberately small, dependency-free at runtime, readable as ordinary JavaScript, and usable from the CLI, Node.js, and the browser playground.
+Eyeleng is a compact automatic hybrid reasoner over RDF-style triples. It uses forward chaining for ordinary finite materialization while its default execution mode applies conservative hybrid planning: selected function-like predicates can be proved just in time by a tabled backward prover when they are demanded by a query or another rule body. It is deliberately small, dependency-free at runtime, readable as ordinary JavaScript, and usable from the CLI, Node.js, and the browser playground.
 
 Eyeleng implements the rules/reasoning surface. It is **not** a SHACL validation engine and does not emit SHACL validation reports.
 
+## Why Eyeleng?
+
+Eyeleng is a next-generation path for rule-based RDF reasoning: it combines a language being developed on the W3C standards track with an execution model that automatically uses both forward and backward reasoning.
+
+The central choice is **SHACL 1.2 Rules instead of N3 as the native rule language**. SHACL 1.2 Rules is being developed by the W3C Data Shapes Working Group as a W3C Working Draft on the Recommendation track. It defines both an RDF representation of rule sets and the concise Shape Rules Language (SRL), together with `infer` and `query` operations. By contrast, the current N3 specification is a W3C Community Group Report. Community Group Reports are useful specifications, but they are not on the W3C standards track and are not W3C-endorsed standards.
+
+That standards position does not require giving up the kinds of programs traditionally written in N3. The N3 examples translated to SRL or RDF Rules and tested with Eyeleng so far have retained their intended reasoning behavior. This is practical evidence that existing N3 rule programs can migrate to the SHACL Rules model, although Eyeleng does not parse N3 syntax directly and this is not yet a claim that every possible N3 extension has a translation.
+
+Eyeleng also removes a choice that N3 engines commonly expose to the rule author. In EYE, Eyeling, and Eyeron, `=>` and `<=` explicitly select forward and backward rules. In Eyeleng, rules describe the logical relationship while the engine analyzes dependencies and demand. It materializes ordinary consequences forward and can prove safe, function-like predicates backward with tabling only when they are needed. This avoids exposing internal helper triples merely because they were required during a computation, while preserving forward closure where materialization is appropriate.
+
+The related engines therefore mark stages and implementation choices rather than hard limits on what Eyeleng may replace:
+
+| Project | Native language and runtime | Main reason to choose it |
+| --- | --- | --- |
+| **EYE** | N3 on SWI-Prolog | The mature, extensive N3 implementation and ecosystem |
+| **Eyeling** | N3 implemented in JavaScript | Direct JavaScript and RDF-JS integration with explicit forward and backward N3 rules |
+| **Eyeron** | N3 implemented in Rust, with native and WebAssembly APIs | Rust-native or WebAssembly deployment with N3 proofs and built-ins |
+| **Eyeleng** | SHACL 1.2 SRL and RDF Rules implemented in JavaScript | A W3C Recommendation-track language plus automatic hybrid reasoning |
+
+Choose Eyeleng when you want to:
+
+- build new rule systems on SHACL 1.2 Rules rather than a Community Group language;
+- migrate N3 reasoning workloads to SRL or RDF Rules;
+- let the engine choose between materialization and goal-directed evaluation;
+- use tabling for recursive, function-like computations without publishing their intermediate facts;
+- combine stratified negation, dependency analysis, RDF 1.2 syntax, and rule execution in one compact engine;
+- run the same dependency-free implementation from a CLI, Node.js, or a browser.
+
+In short: **Eyeleng aims to carry the practical reasoning power demonstrated by the EYE family into SHACL 1.2 Rules, with automatic hybrid execution as the default rather than explicit reasoning direction as a language-level choice.**
+
+Standards references: [SHACL 1.2 Rules](https://www.w3.org/TR/shacl12-rules/), [Notation3 Community Group](https://www.w3.org/groups/cg/n3-dev/), and [W3C document types](https://www.w3.org/standards/types/).
+
 ## Quick start
 
 ```sh
@@ -43,7 +77,7 @@ It derives:
 
 Open the [Playground](https://eyereasoner.github.io/eyeleng/playground) for a self-contained browser UI with URL loading, autosave, share links, diagnostics, queries, and SRL/RDF Rules syntax selection.
 
-## How the reasoner works
+## How automatic hybrid reasoning works
 
 Eyeleng computes the closure of a rule set:
 
@@ -76,6 +110,10 @@ then the body matches with `?parent = :alice` and `?child = :bob`, and the head
 
 Negation is handled by stratified evaluation: rules are grouped into dependency layers, and recursion through negation is rejected so the result stays deterministic.
 
+By default, run mode uses **auto-hybrid reasoning**. Ordinary rules are still materialized forward into the closure. Rules that behave like internal functions can instead be proved backward with tabling when their predicates occur as demanded body goals. For example, a Fibonacci helper predicate can be computed just in time for the public `:fib` results, without printing all intermediate helper triples. Use `--no-hybrid` or `{ hybrid: false }` to force pure forward materialization, and use `--hybrid` or `{ hybrid: true }` to force more aggressive backward orientation.
+
+For explicit `--query` / `--query-file` use, the query body is the top-level goal. Each triple pattern in that body is then a sub-goal that may be answered by the backward prover. If pure backward proving is not safe for the demanded predicates, query mode can run a hybrid plan and finally fall back to ordinary forward closure.
+
 Recursive rules that create new terms through `SET`/`BIND` or head blank nodes run in relaxed mode by default. Relaxed mode can derive useful finite closures, but termination is not guaranteed; use `--max-iterations` as a safety valve. `--strict` rejects these recursive term-generating cycles at analysis time. Head blank nodes are deterministically skolemized per rule and solution mapping, so the same firing reuses the same witness node instead of creating a fresh one each pass.
 
 ## Language surface
@@ -153,7 +191,6 @@ npm run w3c:rules:earl
 npm run w3c:rdf
 npm run w3c:rdf:json
 npm run w3c:rdf:earl
-npm run w3c:all
 ```
 
 `npm test` includes the W3C harnesses. When W3C URLs are reachable, progress is printed test by test. In offline environments, remote W3C checks are reported as unreachable unless `EYELENG_W3C_REQUIRED=1` is set. The `*:earl` scripts also print test progress, but write the EARL Turtle only to `reports/` instead of printing the report to the terminal.
@@ -186,15 +223,23 @@ The replay data includes message streams, envelopes, offsets, next-envelope link
 
 ## CLI
 
+```text
+Usage: eyeleng [options] [file-or-url.n3|- ...]
+```
+
+With no input arguments, Eyeleng prints help. Pass `-` to read from standard input; local files and HTTP(S) URLs can be combined as positional inputs.
+
 Common commands:
 
 ```sh
 ./eyeleng.js examples/family.srl
 ./eyeleng.js --all examples/family.srl
 ./eyeleng.js --check --deps examples/stratified-negation.srl
-./eyeleng.js --json --trace --stats examples/if-then.srl
+./eyeleng.js --json --prove --stats examples/if-then.srl
 ./eyeleng.js --query-file examples/query-body.txt examples/query.srl
 ./eyeleng.js --syntax rdf examples/w3c-rule-set-snippet.ttl
+cat examples/family.srl | ./eyeleng.js -
+./eyeleng.js https://example.org/rules.n3
 ```
 
 Important options:
@@ -202,7 +247,7 @@ Important options:
 ```text
 --all                 print the full closure, including input facts
 --json                print JSON instead of compact triples/bindings
---trace               print derivation trace to stderr, or include it in JSON
+--prove               print proof explanations
 --stats               print iteration and triple counts to stderr
 --check               parse and analyze only; do not run rules
 --strict              treat static warnings as errors, including recursive term generation
@@ -238,28 +283,30 @@ RULE { ?x a :Mortal } WHERE { ?x a :Man }
 console.log(formatTriples(result.inferred, result.prefixes));
 ```
 
-Query mode:
+Hybrid and query mode:
 
 ```js
-const { runQuery, formatBindings } = require('./src/index.js');
+const { run, runQuery, formatBindings } = require('./src/index.js');
 
+// Normal run mode defaults to conservative auto-hybrid reasoning.
+// Ordinary output rules still materialize forward, while selected
+// function-like helper predicates can be proved backward on demand.
+const resultWithAutoHybrid = run(source);
+
+// Force pure forward closure if you want every derivable helper fact materialized.
+const pureForward = run(source, { hybrid: false });
+
+// For explicit queries, the whole raw body is the top-level goal.
+// Each triple pattern in that body is a sub-goal for the planner.
 const result = runQuery(source, '?x :ancestorOf ?y');
 console.log(formatBindings(result.query.bindings, result.prefixes));
 
-// Query mode defaults to auto. Supported query/rule shapes are proved
-// backward with tabling. If full backward proving is not safe but the
-// ruleset contains function-like derived predicates, auto mode uses a
-// hybrid plan before falling back to plain forward closure.
-const justInTime = runQuery(source, ':alice :computedValue ?value', { queryMode: 'backward' });
-
-// Run mode uses conservative auto-hybrid planning by default. It keeps
-// ordinary rules materialized, but can prove demanded function-like predicates
-// backward with tabling. Pass { hybrid: false } to force pure forward closure,
-// or { hybrid: true } to force aggressive hybrid orientation.
-const resultWithAutoHybrid = run(source);
+// queryMode defaults to auto: try tabled backward proving for demanded
+// predicates, then hybrid execution, then ordinary forward closure.
+const justInTime = runQuery(source, ':alice :computedValue ?value');
 
-// The backward planner is demand-driven: irrelevant unsupported rules do not
-// prevent a query from using tabled backward proving.
+// Force the tabled backward prover for supported query shapes.
+const backwardOnly = runQuery(source, ':alice :computedValue ?value', { queryMode: 'backward' });
 ```
 
 Imports:
@@ -326,6 +373,7 @@ Examples live in [examples/](./examples/):
 - `property-paths.srl` — path matching in bodies
 - `basic-ruleset.ttl` — RDF Rules syntax
 - `rdf-messages.srl` / `rdf-messages.trig` — RDF Message Log replay
+- `fibonacci.srl` — fast-doubling Fibonacci using just-in-time backward helper predicates
 - `deep-taxonomy-*.srl` — generated benchmark programs
 
 ## Known boundaries

package/dist/browser/eyeleng.browser.js

@@ -15,7 +15,7 @@
       const { parseRdfMessageLog, looksLikeRdfMessageLog } = require('./rdfMessages.js');
       const { evaluate } = require('./engine.js');
       const { analyze } = require('./analyze.js');
-      const { formatTriples, sortTriples, toJSON, formatTrace, formatBindings } = require('./format.js');
+      const { formatTriples, sortTriples, toJSON, formatTrace, formatProof, formatBindings } = require('./format.js');
       const { runQuery, queryResult, queryProgram, queryRunOptions, shouldUseHybridForQuery } = require('./query.js');
       const { resultTriples } = require('./output.js');
       
@@ -138,6 +138,7 @@
         sortTriples,
         toJSON,
         formatTrace,
+        formatProof,
         resultTriples,
       };
       
@@ -441,7 +442,7 @@
         }
       
         parseTripleStatement(options = {}) {
-          const subjectNode = this.parseGraphNode(options);
+          const subjectNode = this.parseGraphNode({ ...options, position: 'subject' });
           const triples = [...subjectNode.triples];
           triples.push(...this.parsePropertyListForSubject(subjectNode.term, options));
           return triples;
@@ -455,7 +456,7 @@
             if (terminators.some((value) => this.checkValue(value)) || this.checkValue('.')) break;
             const predicate = options.allowPath ? this.parseVerbPathOrSimple(options) : this.parseVerbTerm(options);
             do {
-              const objectNode = this.parseGraphNode(options);
+              const objectNode = this.parseGraphNode({ ...options, position: 'object' });
               triples.push(...objectNode.triples);
               const baseTriple = { s: subject, p: predicate, o: objectNode.term };
               triples.push(baseTriple);
@@ -522,6 +523,7 @@
               currentReifier = this.parseOptionalReifier(options);
               triples.push({ s: currentReifier, p: iri(RDF_REIFIES), o: reified });
             } else if (this.matchValue('{|')) {
+              if (this.checkValue('|}')) throw this.error('Annotation blocks may not be empty');
               const annotationSubject = currentReifier || this.freshGraphNode(options);
               triples.push({ s: annotationSubject, p: iri(RDF_REIFIES), o: reified });
               triples.push(...this.parsePropertyListForSubject(annotationSubject, options, ['|}']));
@@ -571,7 +573,7 @@
         }
       
         parseVerbTerm(options = {}) {
-          const term = this.parseTerm(options);
+          const term = this.parseTerm({ ...options, position: 'predicate' });
           if (term.type !== 'iri' && term.type !== 'var') throw this.error('Expected IRI or variable as predicate');
           return term;
         }
@@ -694,7 +696,10 @@
           if (token.value === '<<(') return this.parseTripleTermAfterOpen(options);
           if (token.value === '<<') throw this.error('Use << s p o >> as a graph node reifier; use <<( s p o )>> for a triple term', token);
           if (token.type === 'word') {
-            if (token.value === 'a') return iri(RDF_TYPE);
+            if (token.value === 'a') {
+              if (options.position !== 'predicate') throw this.error('a is only allowed as a predicate', token);
+              return iri(RDF_TYPE);
+            }
             if (token.value === 'true') return literal(true, XSD_BOOLEAN);
             if (token.value === 'false') return literal(false, XSD_BOOLEAN);
             if (token.value.startsWith('_:')) return blankNode(token.value.slice(2));
@@ -728,7 +733,13 @@
             return literal(coerceLexicalLiteral(token.value, datatype), datatype, null);
           }
           if (this.checkType('word') && /^@[A-Za-z]+(?:-[A-Za-z0-9]+)*(?:--[A-Za-z]+)?$/.test(this.peek().value)) {
-            const tag = this.advance().value.slice(1).toLowerCase();
+            const tagToken = this.advance();
+            const rawTag = tagToken.value.slice(1);
+            const direction = rawTag.includes('--') ? rawTag.slice(rawTag.lastIndexOf('--') + 2) : null;
+            if (direction && direction !== 'ltr' && direction !== 'rtl') {
+              throw this.error(`Invalid base direction --${direction}; expected --ltr or --rtl`, tagToken);
+            }
+            const tag = rawTag.toLowerCase();
             const [lang, langDir = null] = tag.split('--');
             return literal(token.value, null, lang, langDir);
           }
@@ -2507,6 +2518,7 @@
         const syntaxProfile = String(options.profile || options.profileId || '').toLowerCase();
         const rdf12Surface = syntaxProfile === 'turtle' || syntaxProfile === 'trig';
         const implicitStatementNodes = new Set();
+        function implicitStatementNodeKey(term) { return `${term.kind}:${term.value}`; }
       
         function freshBlank() { bnodeCounter += 1; return blank(`b${bnodeCounter}`); }
         function peek(offset = 0) { return tokens[i + offset]; }
@@ -2657,7 +2669,7 @@
           expect('>>');
           const node = reifier || freshBlank();
           out.push(triple(node, iri(RDF_REIFIES), tripleTerm(s, p, o), graph));
-          if (node.kind === 'blank') implicitStatementNodes.add(node.value);
+          implicitStatementNodes.add(implicitStatementNodeKey(node));
           return node;
         }
       
@@ -2686,7 +2698,7 @@
           if (accept(']')) return node;
           parsePredicateObjectList(node, out, graph);
           expect(']');
-          if (node.kind === 'blank') implicitStatementNodes.add(node.value);
+          if (node.kind === 'blank') implicitStatementNodes.add(implicitStatementNodeKey(node));
           return node;
         }
       
@@ -2764,9 +2776,8 @@
             if (options3.requireDot) expect('.'); else accept('.');
             return;
           }
-          if (peek()?.type === '<<' && peek(1)?.type === '(') throw new Error('Triple term cannot be used as a subject');
-          const subject = parseTerm(out, graph, { noLiteral: true, noA: true });
-          if ((peek()?.type === '.' || peek()?.type === '}' || peek()?.type === undefined) && subject.kind === 'blank' && implicitStatementNodes.has(subject.value)) {
+          const subject = parseTerm(out, graph, { noLiteral: !rdf12Surface, noA: true });
+          if ((peek()?.type === '.' || peek()?.type === '}' || peek()?.type === undefined) && implicitStatementNodes.has(implicitStatementNodeKey(subject))) {
             if (options3.requireDot) expect('.'); else accept('.');
             return;
           }
@@ -4253,6 +4264,7 @@
                   rule: rule.name || `rule#${ruleIndex + 1}`,
                   triple,
                   binding,
+                  uses: proofUses(rule.body, binding),
                 });
               }
             }
@@ -4263,6 +4275,17 @@
         return { applications, added };
       }
       
+      function proofUses(body, binding) {
+        return body
+          .filter((clause) => clause.type === 'triple')
+          .map((clause) => ({
+            s: instantiateTerm(clause.triple.s, binding),
+            p: instantiateTerm(clause.triple.p, binding),
+            o: instantiateTerm(clause.triple.o, binding),
+          }))
+          .filter((triple) => ![triple.s, triple.p, triple.o].some((term) => term && term.type === 'var'));
+      }
+      
       function prepareBodyContext(program, store, context) {
         if (!context.hybridBackwardPredicates || context.hybridBackwardPredicates.size === 0) return context;
         return {
@@ -6053,6 +6076,35 @@
         return trace.map((entry) => `#${entry.iteration} ${entry.rule} => ${formatTriple(entry.triple, prefixes)}`).join('\n');
       }
       
+      function formatProof(trace, prefixes = {}) {
+        if (!trace.length) return '';
+        const lines = ['@prefix pe: <https://eyereasoner.github.io/pe#> .', ''];
+        for (const entry of trace) {
+          const conclusion = formatTriple(entry.triple, prefixes);
+          lines.push(`{ ${conclusion} } pe:why {`);
+          lines.push(`  { ${conclusion} }`);
+          lines.push(`    pe:by [ pe:rule ${quoteString(entry.rule)} ]${proofDetails(entry, prefixes)} .`);
+          lines.push('}.', '');
+        }
+        return lines.join('\n').trimEnd();
+      }
+      
+      function proofDetails(entry, prefixes) {
+        const details = [];
+        const bindings = Object.entries(entry.binding || {}).sort(([a], [b]) => a.localeCompare(b));
+        if (bindings.length > 0) {
+          details.push(`\n    pe:binding ${bindings.map(([name, value]) => `[ pe:var ${quoteString(name)}; pe:value ${formatTerm(value, prefixes)} ]`).join(', ')}`);
+        }
+        if (entry.uses && entry.uses.length > 0) {
+          details.push(`\n    pe:uses ${entry.uses.map((triple) => `{ ${formatTriple(triple, prefixes)} }`).join(', ')}`);
+        }
+        return details.length ? `;${details.join(';')}` : '';
+      }
+      
+      function quoteString(value) {
+        return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
+      }
+      
       function formatBindings(bindings, prefixes = {}, select = null) {
         const columns = select && select.length > 0 ? select : inferColumns(bindings);
         return bindings
@@ -6084,7 +6136,7 @@
           prefixes: result.prefixes,
           diagnostics: result.diagnostics || [],
           triples: sortTriples(triples, result.prefixes).map(jsonSafeTriple),
-          trace: options.trace ? result.trace : undefined,
+          proof: options.proof ? result.trace : undefined,
         };
         if (result.query) json.query = jsonSafeValue(result.query);
         if (result.analysis && options.analysis) json.analysis = result.analysis;
@@ -6113,7 +6165,7 @@
         return value;
       }
       
-      module.exports = { sortTriples, formatTriples, formatTrace, formatBindings, formatBinding, toJSON };
+      module.exports = { sortTriples, formatTriples, formatTrace, formatProof, formatBindings, formatBinding, toJSON };
       
     },
     "src/query.js": function (require, module, exports) {

package/examples/README.md

@@ -1,5 +1,7 @@
 # W3C SHACL 1.2 Rules draft examples
 
+Eyeleng—where `leng` stands for **Logic Engine Next Generation**—is built for automatic hybrid reasoning, combining forward materialization with tabled backward proving.
+
 This directory contains runnable examples, including files mirrored from the SHACL 1.2 Rules draft.
 It also includes SRL adaptations of selected eyeling N3 examples.