eyeleng 1.1.0 → 1.1.2

package/README.md

@@ -8,7 +8,7 @@
 - **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 reasoner over RDF-style triples. It still uses forward chaining for ordinary finite materialization, but the default execution mode now includes conservative auto-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 by 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.
 
@@ -76,6 +76,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 +157,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.
@@ -210,7 +213,8 @@ Important options:
 --query TEXT          run a raw SRL body pattern over the closure or backward planner
 --query-file FILE     read a raw SRL body pattern from a file
 --query-mode MODE     use auto, forward, or backward query planning (default auto)
---hybrid              orient function-like rules backward during forward execution and queries
+--hybrid              force aggressive hybrid orientation for function-like rules
+--no-hybrid           disable automatic hybrid forward/backward execution
 --max-iterations N    stop after N fixpoint iterations within a recursive layer
 --no-imports          parse IMPORTS/owl:imports but do not load imported rule sets
 --rdf-messages        parse input as an RDF Message Log
@@ -237,27 +241,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' });
-
-// Explicit hybrid mode keeps forward materialization for ordinary rules, but
-// orients function-like derived predicates backward and proves them only when
-// a forward rule body or query asks for them.
-const hybrid = run(source, { hybrid: true });
+// 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:
@@ -324,6 +331,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

@@ -441,7 +441,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 +455,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 +522,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 +572,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 +695,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 +732,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 +2517,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 +2668,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 +2697,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 +2775,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;
           }
@@ -4088,7 +4098,8 @@
         const relaxedRecursiveRunOnce = options.relaxedRecursion === false
           ? new Set()
           : recursiveTermGenerationRuleIndexes(analysis);
-        const hybridBackwardPredicates = options.hybrid || options.backwardBodyCalls
+        const useHybrid = options.hybrid !== false && !options.shacl12Conformance;
+        const hybridBackwardPredicates = useHybrid || options.backwardBodyCalls
           ? preferredBackwardPredicates(program, options)
           : new Set();
         const hybridBackwardRules = new Set();
@@ -5624,10 +5635,7 @@
           const entry = this.memo.get(key);
           if (entry && entry.complete) {
             this.stats.memoHits += 1;
-            for (const answer of entry.answers) {
-              const next = unifyTriples(pattern, answer, binding);
-              if (next) yield next;
-            }
+            yield* this.replayAnswers(pattern, binding, entry.answers);
             return;
           }
           if (this.active.has(key)) return;
@@ -5641,7 +5649,6 @@
               if (!next) continue;
               rememberAnswer(answers, answerKeys, pattern, next);
               this.stats.facts += 1;
-              yield next;
             }
       
             for (const item of this.ruleCandidates(resolvedPattern)) {
@@ -5653,7 +5660,6 @@
               for (const solved of this.solveBody(freshBody, next, depth + 1, 0)) {
                 rememberAnswer(answers, answerKeys, pattern, solved);
                 this.stats.rules += 1;
-                yield solved;
               }
             }
           } finally {
@@ -5662,6 +5668,14 @@
       
           this.memo.set(key, { complete: true, answers });
           this.stats.memoStores += 1;
+          yield* this.replayAnswers(pattern, binding, answers);
+        }
+      
+        *replayAnswers(pattern, binding, answers) {
+          for (const answer of answers) {
+            const next = unifyTriples(pattern, answer, binding);
+            if (next) yield next;
+          }
         }
       
         factCandidates(pattern, binding) {
@@ -5941,15 +5955,57 @@
         if (explicit) return supportedBackwardPredicates(program, { ...options, hybridPredicates: explicit });
         const supported = supportedBackwardPredicates(program, options);
         const preferred = new Set();
+        const force = options.hybrid === true || options.hybridMode === 'force';
+        const demanded = force ? null : demandedBodyPredicates(program);
         for (const rule of program.rules || []) {
           if (!ruleIsFunctionLike(rule)) continue;
+          if (!force && ruleCreatesHeadTerms(rule)) continue;
           for (const head of rule.head || []) {
-            if (head && head.p && head.p.type === 'iri' && supported.has(head.p.value)) preferred.add(head.p.value);
+            if (!head || !head.p || head.p.type !== 'iri' || !supported.has(head.p.value)) continue;
+            if (force || demanded.has(head.p.value)) preferred.add(head.p.value);
           }
         }
         return preferred;
       }
       
+      function demandedBodyPredicates(program) {
+        const out = new Set();
+        for (const rule of program.rules || []) {
+          for (const predicate of bodyPredicateDemands(rule.body || [])) if (predicate) out.add(predicate);
+        }
+        return out;
+      }
+      
+      
+      function ruleCreatesHeadTerms(rule) {
+        const headVars = new Set();
+        for (const triple of rule.head || []) {
+          for (const term of [triple.s, triple.p, triple.o]) {
+            if (!term) continue;
+            if (term.type === 'blank') return true;
+            if (term.type === 'var') headVars.add(term.value);
+          }
+        }
+        if (headVars.size === 0) return false;
+        for (const clause of rule.body || []) {
+          if ((clause.type === 'set' || clause.type === 'bind') && headVars.has(clause.variable) && expressionCreatesTerm(clause.expr)) return true;
+        }
+        return false;
+      }
+      
+      function expressionCreatesTerm(expr) {
+        if (!expr) return false;
+        if (expr.type === 'call') {
+          const name = String(expr.name || '').toUpperCase();
+          if (name === 'BNODE' || name === 'IRI' || name === 'URI' || name === 'TRIPLE' || name === 'UUID' || name === 'STRUUID') return true;
+          return (expr.args || []).some(expressionCreatesTerm);
+        }
+        if (expr.type === 'binary') return expressionCreatesTerm(expr.left) || expressionCreatesTerm(expr.right);
+        if (expr.type === 'unary') return expressionCreatesTerm(expr.expr);
+        if (expr.type === 'in') return expressionCreatesTerm(expr.left) || (expr.values || []).some(expressionCreatesTerm);
+        return false;
+      }
+      
       function ruleIsFunctionLike(rule) {
         return (rule.body || []).some((clause) => clause.type === 'set' || clause.type === 'bind');
       }
@@ -6087,7 +6143,7 @@
           prefixes: result.prefixes,
           select,
           bindings: projectBindings(bindings, select),
-          mode: options.queryMode === 'hybrid' || options.hybrid ? 'hybrid' : 'forward',
+          mode: result.hybridStats ? 'hybrid' : 'forward',
         };
       }
       
@@ -6153,13 +6209,16 @@
       }
       
       function queryRunOptions(program, querySpec, options = {}) {
-        if (shouldUseHybridForQuery(program, querySpec, options)) return { ...options, hybrid: true };
+        const mode = options.queryMode || 'auto';
+        if (mode === 'forward') return { ...options, hybrid: false };
+        if (shouldUseHybridForQuery(program, querySpec, options)) return { ...options, hybrid: options.hybrid ?? 'auto' };
         return options;
       }
       
       function shouldUseHybridForQuery(program, querySpec, options = {}) {
         const mode = options.queryMode || 'auto';
-        if (options.hybrid || mode === 'hybrid') return true;
+        if (options.hybrid === false) return false;
+        if (options.hybrid === true) return true;
         if (mode !== 'auto') return false;
         if (!querySpec) return false;
         return preferredBackwardPredicates(program, options).size > 0;