eyeleng 1.0.13 → 1.1.1

package/eyeleng.js

@@ -14,6 +14,8 @@
         evaluate,
         parseQuery,
         queryResult,
+        queryProgram,
+        queryRunOptions,
         formatTriples,
         formatTrace,
         formatBindings,
@@ -40,7 +42,7 @@
       const VERSION = readPackageVersion();
       
       function help() {
-        return `eyeleng ${VERSION}\n\nA dependency-free JavaScript implementation experiment for the SHACL 1.2 Rules draft, including SRL and RDF Rules syntax front-ends.\n\nUsage:\n  eyeleng [options] [file ...]\n\nOptions:\n  --all                 Print the full closure, including input facts\n  --json                Print JSON instead of compact triples/bindings\n  --trace               Print derivation trace to stderr, or include it in JSON\n  --stats               Print iteration and triple counts to stderr\n  --check               Parse and analyze only; do not run rules\n  --strict              Treat static warnings as errors, including recursive term generation\n  --deps                Print rule dependency edges during --check\n  --query TEXT          Run a raw SRL body pattern over the closure\n  --query-file FILE     Read a raw SRL body pattern from a file\n  --max-iterations N    Stop after N fixpoint iterations within a recursive layer\n  --no-imports          Parse IMPORTS/owl:imports but do not load imported rule sets\n  --rdf-messages        Parse input as an RDF Message Log\n  --stream-messages     Replay RDF Message Log envelopes\n  --include-message-facts Include payload facts while parsing RDF Message Logs\n  --syntax MODE         Use srl, rdf, or auto syntax detection (default auto)\n  --ruleset TERM        In RDF syntax, run only the selected srl:RuleSet\n  --version             Print version\n  -h, --help            Print this help\n\nWith no file arguments, eyeleng reads from stdin.\n`;
+        return `eyeleng ${VERSION}\n\nA dependency-free JavaScript implementation experiment for the SHACL 1.2 Rules draft, including SRL and RDF Rules syntax front-ends.\n\nUsage:\n  eyeleng [options] [file ...]\n\nOptions:\n  --all                 Print the full closure, including input facts\n  --json                Print JSON instead of compact triples/bindings\n  --trace               Print derivation trace to stderr, or include it in JSON\n  --stats               Print iteration and triple counts to stderr\n  --check               Parse and analyze only; do not run rules\n  --strict              Treat static warnings as errors, including recursive term generation\n  --deps                Print rule dependency edges during --check\n  --query TEXT          Run a raw SRL body pattern over the closure or backward planner\n  --query-file FILE     Read a raw SRL body pattern from a file\n  --query-mode MODE     Use auto, forward, or backward query planning (default auto)\n  --hybrid              Force aggressive hybrid orientation for function-like rules\n  --no-hybrid           Disable automatic hybrid forward/backward execution\n  --max-iterations N    Stop after N fixpoint iterations within a recursive layer\n  --no-imports          Parse IMPORTS/owl:imports but do not load imported rule sets\n  --rdf-messages        Parse input as an RDF Message Log\n  --include-message-facts Include payload facts while parsing RDF Message Logs\n  --syntax MODE         Use srl, rdf, or auto syntax detection (default auto)\n  --ruleset TERM        In RDF syntax, run only the selected srl:RuleSet\n  --version             Print version\n  -h, --help            Print this help\n\nWith no file arguments, eyeleng reads from stdin.\n`;
       }
       
       function parseArgs(argv) {
@@ -54,6 +56,8 @@
           deps: false,
           query: null,
           queryFile: null,
+          queryMode: 'auto',
+          hybrid: 'auto',
           maxIterations: 10000,
           imports: true,
           syntax: 'auto',
@@ -72,7 +76,9 @@
           else if (arg === '--strict') options.strict = true;
           else if (arg === '--deps') options.deps = true;
           else if (arg === '--no-imports') options.imports = false;
-          else if (arg === '--rdf-messages' || arg === '--stream-messages') options.rdfMessages = true;
+          else if (arg === '--hybrid') options.hybrid = true;
+          else if (arg === '--no-hybrid') options.hybrid = false;
+          else if (arg === '--rdf-messages') options.rdfMessages = true;
           else if (arg === '--include-message-facts') options.includeMessageFacts = true;
           else if (arg === '--syntax') {
             i += 1;
@@ -83,8 +89,12 @@
             i += 1;
             if (i >= argv.length) throw new Error('--ruleset requires an RDF term');
             options.ruleSet = argv[i];
-          }
-          else if (arg === '--query') {
+          } else if (arg === '--query-mode') {
+            i += 1;
+            if (i >= argv.length) throw new Error('--query-mode requires auto, forward, or backward');
+            options.queryMode = argv[i];
+            if (!['auto', 'forward', 'backward'].includes(options.queryMode)) throw new Error('--query-mode requires auto, forward, or backward');
+          } else if (arg === '--query') {
             i += 1;
             if (i >= argv.length) throw new Error('--query requires a value');
             options.query = argv[i];
@@ -197,15 +207,42 @@
           }
           if (fatal) return 1;
       
-          const result = evaluate(compiled.program, { ...options, analysis: compiled.analysis });
-          result.diagnostics = compiled.diagnostics;
-          result.analysis = compiled.analysis;
-      
           const queryText = options.queryFile ? fs.readFileSync(options.queryFile, 'utf8') : options.query;
           const querySpec = queryText
             ? parseQuery(queryText, { filename: options.queryFile || '<query>', prefixes: compiled.program.prefixes, baseIRI: compiled.program.baseIRI })
             : null;
-          if (querySpec) result.query = queryResult(result, querySpec, options);
+      
+          let result;
+          if (querySpec) {
+            const directQuery = queryProgram(compiled.program, querySpec, options);
+            if (directQuery) {
+              result = {
+                baseIRI: compiled.program.baseIRI,
+                prefixes: compiled.program.prefixes,
+                input: compiled.program.data.slice(),
+                inferred: [],
+                closure: compiled.program.data.slice(),
+                iterations: 0,
+                layers: [],
+                ruleApplications: 0,
+                perRule: [],
+                trace: [],
+                diagnostics: compiled.diagnostics,
+                analysis: compiled.analysis,
+                query: directQuery,
+              };
+            }
+          }
+      
+          if (!result) {
+            const runOptions = querySpec
+              ? queryRunOptions(compiled.program, querySpec, options)
+              : { ...options, hybrid: options.hybrid };
+            result = evaluate(compiled.program, { ...runOptions, analysis: compiled.analysis });
+            result.diagnostics = compiled.diagnostics;
+            result.analysis = compiled.analysis;
+            if (querySpec) result.query = queryResult(result, querySpec, runOptions);
+          }
       
           if (options.json) {
             io.stdout.write(`${JSON.stringify(toJSON(result, { all: options.all, trace: options.trace, analysis: options.deps }), null, 2)}\n`);
@@ -220,7 +257,9 @@
           }
       
           if (options.stats) {
-            io.stderr.write(`eyeleng: iterations=${result.iterations} layers=${result.layers.length} input=${result.input.length} inferred=${result.inferred.length} closure=${result.closure.length} ruleApplications=${result.ruleApplications}\n`);
+            io.stderr.write(`eyeleng: iterations=${result.iterations} layers=${result.layers.length} input=${result.input.length} inferred=${result.inferred.length} closure=${result.closure.length} ruleApplications=${result.ruleApplications}${result.query && result.query.mode ? ` queryMode=${result.query.mode}` : ''}\n`);
+            if (result.query && result.query.stats) io.stderr.write(`eyeleng: backward goals=${result.query.stats.goals} facts=${result.query.stats.facts} rules=${result.query.stats.rules} memoHits=${result.query.stats.memoHits} memoStores=${result.query.stats.memoStores}\n`);
+            if (result.hybridStats) io.stderr.write(`eyeleng: hybridBackward goals=${result.hybridStats.goals} facts=${result.hybridStats.facts} rules=${result.hybridStats.rules} memoHits=${result.hybridStats.memoHits} memoStores=${result.hybridStats.memoStores}\n`);
             for (const rule of result.perRule) {
               if (rule.applications > 0 || rule.added > 0) io.stderr.write(`eyeleng: rule ${rule.name}: applications=${rule.applications} added=${rule.added}${rule.runOnce ? ' runOnce=true' : ''}\n`);
             }
@@ -246,7 +285,7 @@
       const { evaluate } = require('./engine.js');
       const { analyze } = require('./analyze.js');
       const { formatTriples, sortTriples, toJSON, formatTrace, formatBindings } = require('./format.js');
-      const { runQuery, queryResult } = require('./query.js');
+      const { runQuery, queryResult, queryProgram, queryRunOptions, shouldUseHybridForQuery } = require('./query.js');
       const { resultTriples } = require('./output.js');
       
       function parseInput(source, options = {}) {
@@ -360,6 +399,9 @@
         runToString,
         runQuery,
         queryResult,
+        queryProgram,
+        queryRunOptions,
+        shouldUseHybridForQuery,
         formatTriples,
         formatBindings,
         sortTriples,
@@ -4278,10 +4320,11 @@
     "src/engine.js": function (require, module, exports) {
       '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;
@@ -4297,6 +4340,7 @@
           applications: 0,
           added: 0,
           runOnce: !!rule.runOnce,
+          backward: false,
         }));
       
         const analysis = options.analysis || analyze(program, options);
@@ -4313,6 +4357,18 @@
         const relaxedRecursiveRunOnce = options.relaxedRecursion === false
           ? new Set()
           : recursiveTermGenerationRuleIndexes(analysis);
+        const useHybrid = options.hybrid !== false && !options.shacl12Conformance;
+        const hybridBackwardPredicates = useHybrid || 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,
@@ -4324,12 +4380,16 @@
           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;
@@ -4362,6 +4422,7 @@
           ruleApplications,
           perRule,
           trace,
+          hybridStats,
         };
       }
       
@@ -4431,9 +4492,10 @@
         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) {
@@ -4466,9 +4528,36 @@
           }
         }
       
+        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;
@@ -4577,9 +4666,20 @@
       
         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;
         }
       
@@ -4625,6 +4725,12 @@
         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;
@@ -4657,6 +4763,7 @@
           this.byPredicate = new Map();
           this.byPredicateSubject = new Map();
           this.byPredicateObject = new Map();
+          this.version = 0;
           for (const triple of triples) this.add(triple);
         }
       
@@ -4671,6 +4778,7 @@
           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;
         }
       
@@ -5652,6 +5760,544 @@
         canPossiblyGenerate,
       };
       
+    },
+    "src/backward.js": function (require, module, exports) {
+      'use strict';
+      
+      const { TripleStore, bindingKey } = require('./store.js');
+      const { tripleKey, termKey, termEquals } = require('./term.js');
+      const { evalExpression, booleanValue, asTerm } = require('./builtins.js');
+      
+      function backwardQuery(program, querySpec, options = {}) {
+        const planner = planBackwardQuery(program, querySpec, options);
+        if (!planner.ok) return { ok: false, reason: planner.reason };
+        const prover = new BackwardProver(program, { ...options, allowedRuleIndexes: planner.ruleIndexes });
+        const bindings = uniqueBindings(Array.from(prover.solveBody(querySpec.body, {})));
+        return { ok: true, bindings, stats: prover.stats, plan: planner };
+      }
+      
+      function planBackwardQuery(program, querySpec, options = {}) {
+        const clauses = querySpec && Array.isArray(querySpec.body) ? querySpec.body : [];
+        if (!bodySupported(clauses, options)) return { ok: false, reason: 'query body contains clauses not supported by the backward prover yet' };
+      
+        const reachable = reachableBackwardRuleIndexes(program, clauses, options);
+        for (const ruleIndex of reachable.ruleIndexes) {
+          const rule = (program.rules || [])[ruleIndex];
+          if (!ruleSupported(rule, options)) return { ok: false, reason: `reachable rule ${rule.name || '<anonymous>'} is not supported by the backward prover yet` };
+        }
+        return { ok: true, ruleIndexes: reachable.ruleIndexes, predicates: reachable.predicates };
+      }
+      
+      function bodySupported(clauses, options = {}) {
+        for (const clause of clauses || []) {
+          if (clause.type === 'triple' || clause.type === 'filter' || clause.type === 'set' || clause.type === 'bind') continue;
+          if (clause.type === 'not') {
+            if (options.backwardNegation === false) return false;
+            if (!bodySupported(clause.body, options)) return false;
+            continue;
+          }
+          return false;
+        }
+        return true;
+      }
+      
+      function ruleSupported(rule, options = {}) {
+        if (!Array.isArray(rule.head) || rule.head.length === 0) return false;
+        for (const head of rule.head) {
+          if (!head || !head.p || head.p.type !== 'iri') return false;
+          if (containsBlank(head.s) || containsBlank(head.p) || containsBlank(head.o)) return false;
+        }
+        return bodySupported(rule.body || [], options);
+      }
+      
+      class BackwardProver {
+        constructor(program, options = {}) {
+          this.program = program;
+          this.options = options;
+          this.store = options.store || new TripleStore(program.data || []);
+          this.maxDepth = options.backwardMaxDepth || options.maxDepth || 10000;
+          this.solutionLimit = options.backwardSolutionLimit || options.solutionLimit || 1000000;
+          this.allowedPredicates = normalizePredicateSet(options.allowedPredicates || options.backwardPredicates || null);
+          this.allowedRuleIndexes = normalizeRuleIndexSet(options.allowedRuleIndexes || null);
+          this.ruleHeads = indexRuleHeads(program.rules || [], { allowedPredicates: this.allowedPredicates, allowedRuleIndexes: this.allowedRuleIndexes });
+          this.memo = new Map();
+          this.active = new Set();
+          this.freshCounter = 0;
+          this.solutionCount = 0;
+          this.stats = {
+            mode: 'backward',
+            goals: 0,
+            facts: 0,
+            rules: 0,
+            memoHits: 0,
+            memoStores: 0,
+            maxDepth: 0,
+          };
+        }
+      
+        *solveBody(clauses, binding = {}, depth = 0, index = 0) {
+          if (depth > this.maxDepth) throw new Error(`Reached backwardMaxDepth=${this.maxDepth}; backward query may not terminate`);
+          this.stats.maxDepth = Math.max(this.stats.maxDepth, depth);
+          if (this.solutionCount >= this.solutionLimit) return;
+          if (index >= clauses.length) {
+            this.solutionCount += 1;
+            yield resolveBinding(binding);
+            return;
+          }
+      
+          const clause = clauses[index];
+          if (clause.type === 'triple') {
+            for (const matched of this.solveTriple(clause.triple, binding, depth + 1)) {
+              yield* this.solveBody(clauses, matched, depth + 1, index + 1);
+            }
+            return;
+          }
+      
+          if (clause.type === 'filter') {
+            try {
+              if (booleanValue(evalExpression(clause.expr, resolveBinding(binding), this.options))) {
+                yield* this.solveBody(clauses, binding, depth + 1, index + 1);
+              }
+            } catch (_) {
+              // SPARQL-style FILTER errors reject the current solution.
+            }
+            return;
+          }
+      
+          if (clause.type === 'set' || clause.type === 'bind') {
+            try {
+              const resolved = resolveBinding(binding);
+              const value = asTerm(evalExpression(clause.expr, resolved, this.options));
+              const next = unifyTerms({ type: 'var', value: clause.variable }, value, binding);
+              if (next) yield* this.solveBody(clauses, next, depth + 1, index + 1);
+            } catch (_) {
+              // Assignment errors drop the current solution.
+            }
+            return;
+          }
+      
+          if (clause.type === 'not') {
+            let found = false;
+            for (const _ of this.solveBody(clause.body, { ...binding }, depth + 1, 0)) { found = true; break; }
+            if (!found) yield* this.solveBody(clauses, binding, depth + 1, index + 1);
+            return;
+          }
+      
+          throw new Error(`Unsupported backward body clause ${clause.type}`);
+        }
+      
+        *solveTriple(pattern, binding = {}, depth = 0) {
+          if (depth > this.maxDepth) throw new Error(`Reached backwardMaxDepth=${this.maxDepth}; backward query may not terminate`);
+          this.stats.goals += 1;
+          const resolvedPattern = resolvePattern(pattern, binding);
+          const key = `${goalKey(resolvedPattern)}@store:${this.store.version || 0}`;
+          const entry = this.memo.get(key);
+          if (entry && entry.complete) {
+            this.stats.memoHits += 1;
+            yield* this.replayAnswers(pattern, binding, entry.answers);
+            return;
+          }
+          if (this.active.has(key)) return;
+      
+          const answers = [];
+          const answerKeys = new Set();
+          this.active.add(key);
+          try {
+            for (const fact of this.factCandidates(resolvedPattern, binding)) {
+              const next = unifyTriples(pattern, fact, binding);
+              if (!next) continue;
+              rememberAnswer(answers, answerKeys, pattern, next);
+              this.stats.facts += 1;
+            }
+      
+            for (const item of this.ruleCandidates(resolvedPattern)) {
+              const suffix = `__b${++this.freshCounter}_${item.ruleIndex}`;
+              const freshHead = freshTriple(item.head, suffix);
+              const next = unifyTriples(pattern, freshHead, binding);
+              if (!next) continue;
+              const freshBody = (item.rule.body || []).map((clause) => freshClause(clause, suffix));
+              for (const solved of this.solveBody(freshBody, next, depth + 1, 0)) {
+                rememberAnswer(answers, answerKeys, pattern, solved);
+                this.stats.rules += 1;
+              }
+            }
+          } finally {
+            this.active.delete(key);
+          }
+      
+          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) {
+          return this.store.candidates(pattern, binding);
+        }
+      
+        ruleCandidates(pattern) {
+          const predicate = pattern.p && pattern.p.type === 'iri' ? pattern.p.value : null;
+          if (predicate) return this.ruleHeads.byPredicate.get(predicate) || [];
+          return this.ruleHeads.all;
+        }
+      }
+      
+      function indexRuleHeads(rules, options = {}) {
+        const allowedPredicates = options.allowedPredicates || null;
+        const allowedRuleIndexes = options.allowedRuleIndexes || null;
+        const byPredicate = new Map();
+        const all = [];
+        for (let ruleIndex = 0; ruleIndex < rules.length; ruleIndex += 1) {
+          if (allowedRuleIndexes && !allowedRuleIndexes.has(ruleIndex)) continue;
+          const rule = rules[ruleIndex];
+          for (let headIndex = 0; headIndex < (rule.head || []).length; headIndex += 1) {
+            const head = rule.head[headIndex];
+            if (!head || !head.p || head.p.type !== 'iri') continue;
+            if (allowedPredicates && !allowedPredicates.has(head.p.value)) continue;
+            const item = { ruleIndex, headIndex, rule, head };
+            all.push(item);
+            const bucket = byPredicate.get(head.p.value);
+            if (bucket) bucket.push(item);
+            else byPredicate.set(head.p.value, [item]);
+          }
+        }
+        return { byPredicate, all };
+      }
+      
+      function freshClause(clause, suffix) {
+        if (clause.type === 'triple') return { ...clause, triple: freshTriple(clause.triple, suffix) };
+        if (clause.type === 'filter') return { ...clause, expr: freshExpr(clause.expr, suffix) };
+        if (clause.type === 'set' || clause.type === 'bind') return { ...clause, variable: freshVarName(clause.variable, suffix), expr: freshExpr(clause.expr, suffix) };
+        if (clause.type === 'not') return { ...clause, body: clause.body.map((item) => freshClause(item, suffix)) };
+        return clause;
+      }
+      
+      function freshTriple(triple, suffix) {
+        return { s: freshTerm(triple.s, suffix), p: freshTerm(triple.p, suffix), o: freshTerm(triple.o, suffix) };
+      }
+      
+      function freshTerm(term, suffix) {
+        if (!term) return term;
+        if (term.type === 'var') return { type: 'var', value: freshVarName(term.value, suffix) };
+        if (term.type === 'triple') return { type: 'triple', s: freshTerm(term.s, suffix), p: freshTerm(term.p, suffix), o: freshTerm(term.o, suffix) };
+        return term;
+      }
+      
+      function freshExpr(expr, suffix) {
+        if (!expr) return expr;
+        if (expr.type === 'var') return { ...expr, name: freshVarName(expr.name, suffix) };
+        if (expr.type === 'term') return { ...expr, value: freshTerm(expr.value, suffix) };
+        if (expr.type === 'unary') return { ...expr, expr: freshExpr(expr.expr, suffix) };
+        if (expr.type === 'binary') return { ...expr, left: freshExpr(expr.left, suffix), right: freshExpr(expr.right, suffix) };
+        if (expr.type === 'call') return { ...expr, args: expr.args.map((arg) => freshExpr(arg, suffix)) };
+        if (expr.type === 'list') return { ...expr, items: expr.items.map((item) => freshExpr(item, suffix)) };
+        return expr;
+      }
+      
+      function freshVarName(name, suffix) {
+        return `${name}${suffix}`;
+      }
+      
+      function resolvePattern(pattern, binding) {
+        return { s: resolveTerm(pattern.s, binding, false), p: resolveTerm(pattern.p, binding, false), o: resolveTerm(pattern.o, binding, false) };
+      }
+      
+      function resolveBinding(binding) {
+        const out = {};
+        for (const name of Object.keys(binding)) out[name] = resolveTerm(binding[name], binding, false);
+        return out;
+      }
+      
+      function resolveTerm(term, binding, preserveUnbound = true, seen = new Set()) {
+        if (!term) return term;
+        if (term.type === 'var') {
+          const name = term.value;
+          if (seen.has(name)) return preserveUnbound ? term : { type: 'var', value: name };
+          if (!Object.prototype.hasOwnProperty.call(binding, name)) return preserveUnbound ? term : { type: 'var', value: name };
+          seen.add(name);
+          return resolveTerm(binding[name], binding, preserveUnbound, seen);
+        }
+        if (term.type === 'triple') {
+          return {
+            type: 'triple',
+            s: resolveTerm(term.s, binding, preserveUnbound, new Set(seen)),
+            p: resolveTerm(term.p, binding, preserveUnbound, new Set(seen)),
+            o: resolveTerm(term.o, binding, preserveUnbound, new Set(seen)),
+          };
+        }
+        return term;
+      }
+      
+      function unifyTriples(left, right, binding) {
+        let next = unifyTerms(left.s, right.s, binding);
+        if (!next) return null;
+        next = unifyTerms(left.p, right.p, next);
+        if (!next) return null;
+        return unifyTerms(left.o, right.o, next);
+      }
+      
+      function unifyTerms(left, right, binding) {
+        const a = resolveTerm(left, binding);
+        const b = resolveTerm(right, binding);
+        if (a.type === 'var' && b.type === 'var' && a.value === b.value) return binding;
+        if (a.type === 'var') return bindVariable(a.value, b, binding);
+        if (b.type === 'var') return bindVariable(b.value, a, binding);
+        if (a.type === 'triple' || b.type === 'triple') {
+          if (a.type !== 'triple' || b.type !== 'triple') return null;
+          let next = unifyTerms(a.s, b.s, binding);
+          if (!next) return null;
+          next = unifyTerms(a.p, b.p, next);
+          if (!next) return null;
+          return unifyTerms(a.o, b.o, next);
+        }
+        return termEquals(a, b) ? binding : null;
+      }
+      
+      function bindVariable(name, term, binding) {
+        const existing = binding[name];
+        if (existing) return unifyTerms(existing, term, binding);
+        if (term.type === 'var' && term.value === name) return binding;
+        return { ...binding, [name]: term };
+      }
+      
+      function rememberAnswer(answers, answerKeys, pattern, binding) {
+        const triple = {
+          s: resolveTerm(pattern.s, binding),
+          p: resolveTerm(pattern.p, binding),
+          o: resolveTerm(pattern.o, binding),
+        };
+        if (triple.s.type === 'var' || triple.p.type === 'var' || triple.o.type === 'var') return;
+        const key = tripleKey(triple);
+        if (answerKeys.has(key)) return;
+        answerKeys.add(key);
+        answers.push(triple);
+      }
+      
+      function goalKey(pattern) {
+        return `${safeTermKey(pattern.s)} ${safeTermKey(pattern.p)} ${safeTermKey(pattern.o)}`;
+      }
+      
+      function safeTermKey(term) {
+        return term && term.type === 'var' ? '_' : termKey(term);
+      }
+      
+      function uniqueBindings(bindings) {
+        const seen = new Set();
+        const out = [];
+        for (const binding of bindings) {
+          const resolved = resolveBinding(binding);
+          const key = bindingKey(resolved);
+          if (seen.has(key)) continue;
+          seen.add(key);
+          out.push(resolved);
+        }
+        return out;
+      }
+      
+      function containsBlank(term) {
+        if (!term) return false;
+        if (term.type === 'blank') return true;
+        if (term.type === 'triple') return containsBlank(term.s) || containsBlank(term.p) || containsBlank(term.o);
+        return false;
+      }
+      
+      
+      
+      function reachableBackwardRuleIndexes(program, rootClauses, options = {}) {
+        const rules = program.rules || [];
+        const headIndex = new Map();
+        const allHeadPredicates = new Set();
+        const allRuleIndexes = new Set();
+        for (let ruleIndex = 0; ruleIndex < rules.length; ruleIndex += 1) {
+          const rule = rules[ruleIndex];
+          for (const head of rule.head || []) {
+            if (!head || !head.p || head.p.type !== 'iri') continue;
+            allRuleIndexes.add(ruleIndex);
+            allHeadPredicates.add(head.p.value);
+            if (!headIndex.has(head.p.value)) headIndex.set(head.p.value, new Set());
+            headIndex.get(head.p.value).add(ruleIndex);
+          }
+        }
+      
+        const predicates = new Set();
+        const ruleIndexes = new Set();
+        const work = [];
+        const enqueue = (predicate) => {
+          if (!predicate) {
+            for (const item of allHeadPredicates) enqueue(item);
+            return;
+          }
+          if (predicates.has(predicate)) return;
+          predicates.add(predicate);
+          work.push(predicate);
+        };
+      
+        for (const predicate of bodyPredicateDemands(rootClauses || [])) enqueue(predicate);
+      
+        while (work.length > 0) {
+          const predicate = work.shift();
+          const indexes = headIndex.get(predicate);
+          if (!indexes) continue;
+          for (const ruleIndex of indexes) {
+            if (ruleIndexes.has(ruleIndex)) continue;
+            ruleIndexes.add(ruleIndex);
+            const rule = rules[ruleIndex];
+            for (const needed of bodyPredicateDemands(rule.body || [])) enqueue(needed);
+          }
+        }
+      
+        return { ruleIndexes, predicates };
+      }
+      
+      function bodyPredicateDemands(clauses) {
+        const out = [];
+        for (const clause of clauses || []) {
+          if (clause.type === 'triple') {
+            out.push(predicateDemand(clause.triple.p));
+            continue;
+          }
+          if (clause.type === 'not') {
+            out.push(...bodyPredicateDemands(clause.body || []));
+          }
+        }
+        return out;
+      }
+      
+      function predicateDemand(term) {
+        return term && term.type === 'iri' ? term.value : null;
+      }
+      
+      function normalizePredicateSet(value) {
+        if (!value) return null;
+        if (value instanceof Set) return value;
+        if (Array.isArray(value)) return new Set(value);
+        return new Set(String(value).split(',').map((item) => item.trim()).filter(Boolean));
+      }
+      
+      function normalizeRuleIndexSet(value) {
+        if (!value) return null;
+        if (value instanceof Set) return value;
+        if (Array.isArray(value)) return new Set(value);
+        return null;
+      }
+      
+      function supportedBackwardPredicates(program, options = {}) {
+        const explicit = normalizePredicateSet(options.backwardPredicates || options.hybridPredicates || null);
+        const byPredicate = new Map();
+        for (const rule of program.rules || []) {
+          const predicates = new Set();
+          for (const head of rule.head || []) {
+            if (head && head.p && head.p.type === 'iri') predicates.add(head.p.value);
+          }
+          for (const predicate of predicates) {
+            if (!byPredicate.has(predicate)) byPredicate.set(predicate, []);
+            byPredicate.get(predicate).push(rule);
+          }
+        }
+      
+        const supported = new Set();
+        for (const [predicate, rules] of byPredicate) {
+          if (explicit && !explicit.has(predicate)) continue;
+          if (rules.length > 0 && rules.every((rule) => ruleSupported(rule, options))) supported.add(predicate);
+        }
+        return supported;
+      }
+      
+      function preferredBackwardPredicates(program, options = {}) {
+        const explicit = normalizePredicateSet(options.hybridPredicates || null);
+        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)) 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');
+      }
+      
+      function ruleHeadPredicates(rule) {
+        const predicates = new Set();
+        for (const head of rule.head || []) {
+          if (!head || !head.p || head.p.type !== 'iri') return null;
+          predicates.add(head.p.value);
+        }
+        return predicates;
+      }
+      
+      function ruleIsBackwardOriented(rule, predicates) {
+        if (!predicates || predicates.size === 0) return false;
+        const heads = ruleHeadPredicates(rule);
+        if (!heads || heads.size === 0) return false;
+        for (const predicate of heads) if (!predicates.has(predicate)) return false;
+        return true;
+      }
+      
+      module.exports = {
+        BackwardProver,
+        backwardQuery,
+        planBackwardQuery,
+        supportedBackwardPredicates,
+        preferredBackwardPredicates,
+        reachableBackwardRuleIndexes,
+        ruleIsBackwardOriented,
+        ruleSupported,
+        resolveBinding,
+      };
+      
     },
     "src/format.js": function (require, module, exports) {
       'use strict';
@@ -5745,6 +6391,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 || []);
@@ -5755,28 +6402,92 @@
           prefixes: result.prefixes,
           select,
           bindings: projectBindings(bindings, select),
+          mode: result.hybridStats ? '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 = {}) {
+        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 === false) return false;
+        if (options.hybrid === true) 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) {
@@ -5794,7 +6505,7 @@
         return out;
       }
       
-      module.exports = { runQuery, queryResult, parseQuery, normalizeSelect, projectBindings };
+      module.exports = { runQuery, queryResult, queryProgram, queryRunOptions, shouldUseHybridForQuery, parseQuery, normalizeSelect, projectBindings };
       
     },
     "src/output.js": function (require, module, exports) {
@@ -5808,7 +6519,7 @@
       
     },
   };
-  const __mappings = {"src/tokenizer.js":{},"src/assignments.js":{},"src/term.js":{},"src/rdfSyntax.js":{"./tokenizer.js":"src/tokenizer.js","./assignments.js":"src/assignments.js","./term.js":"src/term.js"},"src/builtins.js":{"./term.js":"src/term.js"},"src/parser.js":{"./tokenizer.js":"src/tokenizer.js","./rdfSyntax.js":"src/rdfSyntax.js","./builtins.js":"src/builtins.js","./assignments.js":"src/assignments.js","./term.js":"src/term.js"},"src/rdfMessages.js":{"./rdfSyntax.js":"src/rdfSyntax.js","./term.js":"src/term.js"},"src/store.js":{"./term.js":"src/term.js"},"src/analyze.js":{"./term.js":"src/term.js","./assignments.js":"src/assignments.js"},"src/engine.js":{"./store.js":"src/store.js","./term.js":"src/term.js","./builtins.js":"src/builtins.js","./analyze.js":"src/analyze.js"},"src/format.js":{"./term.js":"src/term.js"},"src/query.js":{"./parser.js":"src/parser.js","./store.js":"src/store.js","./engine.js":"src/engine.js","./api.js":"src/api.js"},"src/output.js":{},"src/api.js":{"./parser.js":"src/parser.js","./rdfSyntax.js":"src/rdfSyntax.js","./rdfMessages.js":"src/rdfMessages.js","./engine.js":"src/engine.js","./analyze.js":"src/analyze.js","./format.js":"src/format.js","./query.js":"src/query.js","./output.js":"src/output.js"},"src/cli.js":{"./api.js":"src/api.js","./term.js":"src/term.js"}};
+  const __mappings = {"src/tokenizer.js":{},"src/assignments.js":{},"src/term.js":{},"src/rdfSyntax.js":{"./tokenizer.js":"src/tokenizer.js","./assignments.js":"src/assignments.js","./term.js":"src/term.js"},"src/builtins.js":{"./term.js":"src/term.js"},"src/parser.js":{"./tokenizer.js":"src/tokenizer.js","./rdfSyntax.js":"src/rdfSyntax.js","./builtins.js":"src/builtins.js","./assignments.js":"src/assignments.js","./term.js":"src/term.js"},"src/rdfMessages.js":{"./rdfSyntax.js":"src/rdfSyntax.js","./term.js":"src/term.js"},"src/store.js":{"./term.js":"src/term.js"},"src/analyze.js":{"./term.js":"src/term.js","./assignments.js":"src/assignments.js"},"src/backward.js":{"./store.js":"src/store.js","./term.js":"src/term.js","./builtins.js":"src/builtins.js"},"src/engine.js":{"./store.js":"src/store.js","./term.js":"src/term.js","./builtins.js":"src/builtins.js","./analyze.js":"src/analyze.js","./backward.js":"src/backward.js"},"src/format.js":{"./term.js":"src/term.js"},"src/query.js":{"./parser.js":"src/parser.js","./store.js":"src/store.js","./engine.js":"src/engine.js","./backward.js":"src/backward.js","./api.js":"src/api.js"},"src/output.js":{},"src/api.js":{"./parser.js":"src/parser.js","./rdfSyntax.js":"src/rdfSyntax.js","./rdfMessages.js":"src/rdfMessages.js","./engine.js":"src/engine.js","./analyze.js":"src/analyze.js","./format.js":"src/format.js","./query.js":"src/query.js","./output.js":"src/output.js"},"src/cli.js":{"./api.js":"src/api.js","./term.js":"src/term.js"}};
   const __cache = {};
   function __require(id) {
     if (!id.startsWith("src/")) return __nativeRequire(id);