eyeleng 1.0.13 → 1.1.0

package/src/engine.js

@@ -1,9 +1,10 @@
 'use strict';
 
-const { TripleStore, bindingKey } = require('./store.js');
+const { TripleStore, bindingKey, instantiateTerm } = require('./store.js');
 const { tripleKey, termKey, termEquals, blankNode, tripleTerm } = require('./term.js');
 const { evalExpression, booleanValue, asTerm } = require('./builtins.js');
 const { analyze } = require('./analyze.js');
+const { BackwardProver, preferredBackwardPredicates, ruleIsBackwardOriented } = require('./backward.js');
 
 function evaluate(program, options = {}) {
   const maxIterations = options.maxIterations ?? 10000;
@@ -19,6 +20,7 @@ function evaluate(program, options = {}) {
     applications: 0,
     added: 0,
     runOnce: !!rule.runOnce,
+    backward: false,
   }));
 
   const analysis = options.analysis || analyze(program, options);
@@ -35,6 +37,17 @@ function evaluate(program, options = {}) {
   const relaxedRecursiveRunOnce = options.relaxedRecursion === false
     ? new Set()
     : recursiveTermGenerationRuleIndexes(analysis);
+  const hybridBackwardPredicates = options.hybrid || options.backwardBodyCalls
+    ? preferredBackwardPredicates(program, options)
+    : new Set();
+  const hybridBackwardRules = new Set();
+  if (hybridBackwardPredicates.size > 0) {
+    for (let ruleIndex = 0; ruleIndex < program.rules.length; ruleIndex += 1) {
+      if (ruleIsBackwardOriented(program.rules[ruleIndex], hybridBackwardPredicates)) hybridBackwardRules.add(ruleIndex);
+    }
+  }
+  const hybridStats = hybridBackwardPredicates.size > 0 ? emptyBackwardStats() : null;
+  for (const ruleIndex of hybridBackwardRules) perRule[ruleIndex].backward = true;
   const baseContext = {
     ...evalOptions,
     maxIterations,
@@ -46,12 +59,16 @@ function evaluate(program, options = {}) {
     iteration: 0,
     startingIterations: 0,
     recursiveLayer: false,
+    hybridBackwardPredicates,
+    hybridBackwardRules,
+    hybridStats,
   };
 
   for (let layerIndex = 0; layerIndex < layerIndexes.length; layerIndex += 1) {
     const layer = layerIndexes[layerIndex];
-    const ordinary = layer.filter((ruleIndex) => !program.rules[ruleIndex].runOnce || relaxedRecursiveRunOnce.has(ruleIndex));
-    const runOnce = layer.filter((ruleIndex) => program.rules[ruleIndex].runOnce && !relaxedRecursiveRunOnce.has(ruleIndex));
+    const forwardLayer = hybridBackwardRules.size > 0 ? layer.filter((ruleIndex) => !hybridBackwardRules.has(ruleIndex)) : layer;
+    const ordinary = forwardLayer.filter((ruleIndex) => !program.rules[ruleIndex].runOnce || relaxedRecursiveRunOnce.has(ruleIndex));
+    const runOnce = forwardLayer.filter((ruleIndex) => program.rules[ruleIndex].runOnce && !relaxedRecursiveRunOnce.has(ruleIndex));
 
     if (runOnce.length > 0) {
       iterations += 1;
@@ -84,6 +101,7 @@ function evaluate(program, options = {}) {
     ruleApplications,
     perRule,
     trace,
+    hybridStats,
   };
 }
 
@@ -153,9 +171,10 @@ function applyRuleOnce(program, store, ruleIndex, context) {
   const seenBindings = dedupeBindings ? new Set() : null;
   const headBlankLabels = collectHeadBlankLabels(rule.head);
 
-  const bodyBindings = rule.body.length === 1 && rule.body[0].type === 'triple'
+  const bodyContext = prepareBodyContext(program, store, context);
+  const bodyBindings = rule.body.length === 1 && rule.body[0].type === 'triple' && !shouldUseBackwardForTriple(rule.body[0].triple, {}, bodyContext)
     ? store.match(rule.body[0].triple, {})
-    : evaluateBodyStream(rule.body, store, {}, context);
+    : evaluateBodyStream(rule.body, store, {}, bodyContext);
 
   for (const binding of bodyBindings) {
     if (seenBindings) {
@@ -188,9 +207,36 @@ function applyRuleOnce(program, store, ruleIndex, context) {
     }
   }
 
+  if (bodyContext.backwardProver && context.hybridStats) mergeBackwardStats(context.hybridStats, bodyContext.backwardProver.stats);
   return { applications, added };
 }
 
+function prepareBodyContext(program, store, context) {
+  if (!context.hybridBackwardPredicates || context.hybridBackwardPredicates.size === 0) return context;
+  return {
+    ...context,
+    backwardProver: new BackwardProver(program, {
+      ...context,
+      store,
+      allowedPredicates: context.hybridBackwardPredicates,
+    }),
+  };
+}
+
+function emptyBackwardStats() {
+  return { mode: 'hybrid', goals: 0, facts: 0, rules: 0, memoHits: 0, memoStores: 0, maxDepth: 0 };
+}
+
+function mergeBackwardStats(total, item) {
+  if (!total || !item) return;
+  total.goals += item.goals || 0;
+  total.facts += item.facts || 0;
+  total.rules += item.rules || 0;
+  total.memoHits += item.memoHits || 0;
+  total.memoStores += item.memoStores || 0;
+  total.maxDepth = Math.max(total.maxDepth || 0, item.maxDepth || 0);
+}
+
 function recursiveTermGenerationRuleIndexes(analysis) {
   const out = new Set();
   if (!analysis || !analysis.dependency || !analysis.diagnostics) return out;
@@ -299,9 +345,20 @@ function* evaluateBodyStream(clauses, store, initialBinding = {}, options = {},
 
   const clause = clauses[index];
   if (clause.type === 'triple') {
+    const seen = new Set();
     for (const matched of store.match(clause.triple, initialBinding)) {
+      const key = bindingKey(matched);
+      seen.add(key);
       yield* evaluateBodyStream(clauses, store, matched, options, index + 1);
     }
+    if (shouldUseBackwardForTriple(clause.triple, initialBinding, options)) {
+      for (const matched of options.backwardProver.solveTriple(clause.triple, initialBinding)) {
+        const key = bindingKey(matched);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        yield* evaluateBodyStream(clauses, store, matched, options, index + 1);
+      }
+    }
     return;
   }
 
@@ -347,6 +404,12 @@ function* evaluateBodyStream(clauses, store, initialBinding = {}, options = {},
   throw new Error(`Unsupported body clause ${clause.type}`);
 }
 
+function shouldUseBackwardForTriple(pattern, binding, options = {}) {
+  if (!options.backwardProver || !options.hybridBackwardPredicates || options.hybridBackwardPredicates.size === 0) return false;
+  const predicate = instantiateTerm(pattern.p, binding);
+  return !!(predicate && predicate.type === 'iri' && options.hybridBackwardPredicates.has(predicate.value));
+}
+
 function bodyHasAny(clauses, store, initialBinding, options) {
   for (const _ of evaluateBodyStream(clauses, store, initialBinding, options)) return true;
   return false;

package/src/query.js

@@ -3,6 +3,7 @@
 const { parseQuery } = require('./parser.js');
 const { TripleStore, bindingKey } = require('./store.js');
 const { evaluateBody } = require('./engine.js');
+const { backwardQuery, planBackwardQuery, preferredBackwardPredicates } = require('./backward.js');
 
 function queryResult(result, querySpec, options = {}) {
   const store = new TripleStore(result.closure || []);
@@ -13,28 +14,89 @@ function queryResult(result, querySpec, options = {}) {
     prefixes: result.prefixes,
     select,
     bindings: projectBindings(bindings, select),
+    mode: options.queryMode === 'hybrid' || options.hybrid ? 'hybrid' : 'forward',
   };
 }
 
+function queryProgram(program, querySpec, options = {}) {
+  const mode = options.queryMode || 'auto';
+  if (mode !== 'forward' && mode !== 'hybrid') {
+    const planned = planBackwardQuery(program, querySpec, options);
+    if (planned.ok) {
+      const result = backwardQuery(program, querySpec, options);
+      if (result.ok) {
+        const select = normalizeSelect(querySpec.select, result.bindings);
+        return {
+          baseIRI: program.baseIRI,
+          prefixes: program.prefixes,
+          select,
+          bindings: projectBindings(result.bindings, select),
+          mode: 'backward',
+          stats: result.stats,
+        };
+      }
+      if (mode === 'backward') throw new Error(result.reason || 'Backward query failed');
+    } else if (mode === 'backward') {
+      throw new Error(`Backward query is not supported for this ruleset: ${planned.reason}`);
+    }
+  }
+  return null;
+}
+
 function runQuery(source, querySource = null, options = {}) {
   const { run, compile } = require('./api.js');
-  const { program, diagnostics } = compile(source, options);
-  const result = run(program, options);
-  result.diagnostics = diagnostics;
+  const { program, diagnostics, analysis } = compile(source, options);
 
   let querySpec;
   if (querySource) querySpec = parseQuery(querySource, { ...options, prefixes: program.prefixes, baseIRI: program.baseIRI });
   else throw new Error('No query supplied. Use --query or --query-file with a raw body pattern.');
 
-  const query = queryResult(result, querySpec, options);
-  return { ...result, query };
+  const direct = queryProgram(program, querySpec, options);
+  if (direct) {
+    return {
+      baseIRI: program.baseIRI,
+      version: program.version || null,
+      imports: program.imports || [],
+      prefixes: program.prefixes,
+      input: program.data.slice(),
+      inferred: [],
+      closure: program.data.slice(),
+      iterations: 0,
+      layers: [],
+      ruleApplications: 0,
+      perRule: [],
+      trace: [],
+      diagnostics,
+      analysis,
+      query: direct,
+    };
+  }
+
+  const runOptions = queryRunOptions(program, querySpec, options);
+  const result = run(program, runOptions);
+  result.diagnostics = diagnostics;
+  result.query = queryResult(result, querySpec, runOptions);
+  return result;
+}
+
+function queryRunOptions(program, querySpec, options = {}) {
+  if (shouldUseHybridForQuery(program, querySpec, options)) return { ...options, hybrid: true };
+  return options;
+}
+
+function shouldUseHybridForQuery(program, querySpec, options = {}) {
+  const mode = options.queryMode || 'auto';
+  if (options.hybrid || mode === 'hybrid') return true;
+  if (mode !== 'auto') return false;
+  if (!querySpec) return false;
+  return preferredBackwardPredicates(program, options).size > 0;
 }
 
 function normalizeSelect(select, bindings) {
   if (select && select.length > 0) return select.slice();
   const vars = new Set();
   for (const binding of bindings) for (const key of Object.keys(binding)) vars.add(key);
-  return Array.from(vars).sort();
+  return Array.from(vars).sort().filter((name) => !name.includes('__b'));
 }
 
 function projectBindings(bindings, select) {
@@ -52,4 +114,4 @@ function projectBindings(bindings, select) {
   return out;
 }
 
-module.exports = { runQuery, queryResult, parseQuery, normalizeSelect, projectBindings };
+module.exports = { runQuery, queryResult, queryProgram, queryRunOptions, shouldUseHybridForQuery, parseQuery, normalizeSelect, projectBindings };

package/src/store.js

@@ -8,6 +8,7 @@ class TripleStore {
     this.byPredicate = new Map();
     this.byPredicateSubject = new Map();
     this.byPredicateObject = new Map();
+    this.version = 0;
     for (const triple of triples) this.add(triple);
   }
 
@@ -22,6 +23,7 @@ class TripleStore {
     addIndex(this.byPredicate, predicate, key, normalized);
     addNestedIndex(this.byPredicateSubject, predicate, subject, key, normalized);
     addNestedIndex(this.byPredicateObject, predicate, object, key, normalized);
+    this.version += 1;
     return true;
   }
 

package/test/api.test.js

@@ -2,7 +2,7 @@
 
 const { test, main } = require('./harness.js').createHarness('API');
 const assert = require('node:assert/strict');
-const { parse, compile, run, runToString } = require('../src/index.js');
+const { parse, compile, run, runToString, runQuery } = require('../src/index.js');
 const { tripleKey } = require('../src/term.js');
 
 test('parse reads prefixes, data, and rules', () => {
@@ -159,6 +159,114 @@ RULE { ?x :ancestorOf ?z } WHERE { ?x :parentOf ?y . ?y :ancestorOf ?z }
   assert.match(output, /\?d = :carol/);
 });
 
+
+
+test('backward query mode proves recursive derived predicates with tabling', () => {
+  const { runQuery, formatBindings } = require('../src/index.js');
+  const result = runQuery(`
+PREFIX : <http://example/>
+DATA { :alice :parentOf :bob . :bob :parentOf :carol . }
+RULE { ?x :ancestorOf ?y } WHERE { ?x :parentOf ?y }
+RULE { ?x :ancestorOf ?z } WHERE { ?x :parentOf ?y . ?y :ancestorOf ?z }
+`, ':alice :ancestorOf ?d', { queryMode: 'backward' });
+  assert.equal(result.iterations, 0);
+  assert.equal(result.query.mode, 'backward');
+  assert.ok(result.query.stats.memoStores > 0);
+  const output = formatBindings(result.query.bindings, result.prefixes, result.query.select);
+  assert.match(output, /\?d = :bob/);
+  assert.match(output, /\?d = :carol/);
+});
+
+test('backward query mode computes function-like rules just in time', () => {
+  const { runQuery, formatBindings } = require('../src/index.js');
+  const result = runQuery(`
+PREFIX : <http://example/>
+DATA { :alice :score 41 . :bob :score 2 . }
+RULE { ?x :nextScore ?m } WHERE { ?x :score ?n . SET(?m := ?n + 1) }
+`, '?who :nextScore ?score', { queryMode: 'backward' });
+  assert.equal(result.iterations, 0);
+  const output = formatBindings(result.query.bindings, result.prefixes, result.query.select);
+  assert.match(output, /\?score = 42; \?who = :alice/);
+  assert.match(output, /\?score = 3; \?who = :bob/);
+});
+
+test('auto query mode uses backward planning for supported rules', () => {
+  const { runQuery } = require('../src/index.js');
+  const result = runQuery(`
+PREFIX : <http://example/>
+DATA { :a :p :b . }
+RULE { ?x :q ?y } WHERE { ?x :p ?y }
+`, ':a :q ?y');
+  assert.equal(result.query.mode, 'backward');
+  assert.equal(result.iterations, 0);
+});
+
+
+
+test('hybrid execution proves function-like body predicates backward without materializing them', () => {
+  const result = run(`
+PREFIX : <http://example/>
+DATA { :alice :score 41 . :bob :score 2 . }
+RULE { ?x :nextScore ?m } WHERE { ?x :score ?n . SET(?m := ?n + 1) }
+RULE { ?x :ready true } WHERE { ?x :nextScore 42 }
+`, { hybrid: true });
+  const keys = result.closure.map(tripleKey).join('\n');
+  assert.match(keys, /ready/);
+  assert.doesNotMatch(keys, /nextScore/);
+  assert.equal(result.perRule[0].applications, 0);
+  assert.equal(result.perRule[0].backward, true);
+  assert.ok(result.hybridStats.goals > 0);
+  assert.ok(result.hybridStats.rules > 0);
+});
+
+test('hybrid query mode runs forward rules with backward body calls', () => {
+  const { runQuery, formatBindings } = require('../src/index.js');
+  const result = runQuery(`
+PREFIX : <http://example/>
+DATA { :alice :score 41 . :bob :score 2 . }
+RULE { ?x :nextScore ?m } WHERE { ?x :score ?n . SET(?m := ?n + 1) }
+RULE { ?x :ready ?score } WHERE { ?x :nextScore ?score . FILTER(?score = 42) }
+`, '?who :ready ?score', { queryMode: 'hybrid' });
+  assert.equal(result.query.mode, 'hybrid');
+  assert.ok(result.hybridStats.goals > 0);
+  const output = formatBindings(result.query.bindings, result.prefixes, result.query.select);
+  assert.match(output, /\?score = 42; \?who = :alice/);
+  assert.doesNotMatch(output, /bob/);
+});
+
+test('auto query mode uses pure backward planning when unsupported rules are irrelevant', () => {
+  const { runQuery, formatBindings } = require('../src/index.js');
+  const result = runQuery(`
+PREFIX : <http://example/>
+DATA { :alice :score 41 . :bob :score 2 . :seed :seen :x . }
+RULE { ?x :nextScore ?m } WHERE { ?x :score ?n . SET(?m := ?n + 1) }
+RULE { ?x :ready ?score } WHERE { ?x :nextScore ?score . FILTER(?score = 42) }
+RULE { [] :unrelated :x } WHERE { :seed :seen :x }
+`, '?who :ready ?score');
+  assert.equal(result.query.mode, 'backward');
+  assert.ok(result.query.stats.goals > 0);
+  const output = formatBindings(result.query.bindings, result.prefixes, result.query.select);
+  assert.match(output, /\?score = 42; \?who = :alice/);
+  assert.doesNotMatch(output, /bob/);
+});
+
+test('auto query mode falls back to hybrid when a demanded predicate has unsupported rules', () => {
+  const { runQuery, formatBindings } = require('../src/index.js');
+  const result = runQuery(`
+PREFIX : <http://example/>
+DATA { :alice :score 41 . :bob :score 2 . :seed :seen :x . }
+RULE { ?x :nextScore ?m } WHERE { ?x :score ?n . SET(?m := ?n + 1) }
+RULE { ?x :ready ?score } WHERE { ?x :nextScore ?score . FILTER(?score = 42) }
+RULE { [] :ready 999 } WHERE { :seed :seen :x }
+`, '?who :ready ?score');
+  assert.equal(result.query.mode, 'hybrid');
+  assert.ok(result.hybridStats.goals > 0);
+  assert.equal(result.perRule[0].backward, true);
+  assert.doesNotMatch(result.closure.map(tripleKey).join('\n'), /nextScore/);
+  const output = formatBindings(result.query.bindings, result.prefixes, result.query.select);
+  assert.match(output, /\?score = 42; \?who = :alice/);
+});
+
 test('parseQuery accepts raw body text and rejects non-SRL QUERY/SELECT syntax', () => {
   const { parseQuery } = require('../src/index.js');
   const raw = parseQuery('?x :p ?y', { prefixes: { '': 'http://example/' } });
@@ -599,4 +707,22 @@ RULE { ?x :p ?v1 } WHERE { ?x :p ?v . SET(?v1 := ?v + 1) }
 `, { shacl12Conformance: true, strict: true }), /creates terms in a recursive dependency cycle/);
 });
 
+
+test('auto backward query ignores unsupported rules outside the demanded slice', () => {
+  const source = `
+PREFIX : <http://example/>
+DATA { :alice :parent :bob . :bob :parent :carol . :a :q :b . :b :q :c . }
+RULE { ?x :ancestor ?y } WHERE { ?x :parent ?y }
+RULE { ?x :ancestor ?z } WHERE { ?x :parent ?y . ?y :ancestor ?z }
+RULE { ?x :twoStep ?y } WHERE { ?x :q/:q ?y }
+`;
+  const result = runQuery(source, ':alice :ancestor ?who');
+  assert.equal(result.query.mode, 'backward');
+  assert.ok(result.query.stats.goals > 0);
+  assert.deepEqual(
+    result.query.bindings.map((binding) => binding.who.value).sort(),
+    ['http://example/bob', 'http://example/carol'],
+  );
+});
+
 main();

package/test/cli.test.js

@@ -22,7 +22,7 @@ function readmeCliOptions() {
 test('CLI help documents RDF Message Log flags', () => {
   const text = help();
   assert.match(text, /--rdf-messages\s+Parse input as an RDF Message Log/);
-  assert.match(text, /--stream-messages\s+Replay RDF Message Log envelopes/);
+  assert.doesNotMatch(text, /--stream-messages/);
   assert.match(text, /--include-message-facts\s+Include payload facts while parsing RDF Message Logs/);
 });
 
@@ -34,8 +34,17 @@ test('README CLI options stay in sync with --help', () => {
 
 test('RDF Message Log flags are accepted by parseArgs', () => {
   assert.equal(parseArgs(['--rdf-messages']).options.rdfMessages, true);
-  assert.equal(parseArgs(['--stream-messages']).options.rdfMessages, true);
   assert.equal(parseArgs(['--include-message-facts']).options.includeMessageFacts, true);
 });
 
+test('query mode flag is accepted by parseArgs', () => {
+  assert.equal(parseArgs(['--query-mode', 'auto']).options.queryMode, 'auto');
+  assert.equal(parseArgs(['--query-mode', 'forward']).options.queryMode, 'forward');
+  assert.equal(parseArgs(['--query-mode', 'backward']).options.queryMode, 'backward');
+  assert.equal(parseArgs(['--hybrid']).options.hybrid, true);
+  assert.throws(() => parseArgs(['--query-mode', 'hybrid']), /--query-mode requires auto, forward, or backward/);
+  assert.throws(() => parseArgs(['--query-mode', 'sideways']), /--query-mode requires auto, forward, or backward/);
+  assert.throws(() => parseArgs(['--stream-messages']), /Unknown option --stream-messages/);
+});
+
 main();