eyeling 1.12.15 → 1.13.0

package/HANDBOOK.md

@@ -761,6 +761,8 @@ A predicate is treated as builtin if:
 
 Super restricted mode exists to let you treat all other predicates as ordinary facts/rules without any built-in evaluation.
 
+**Note on `log:query`:** Eyeling also recognizes a special _top-level_ directive of the form `{...} log:query {...}.` to **select which results to print**. This is **not** a builtin predicate (it is not evaluated as part of goal solving); it is handled by the parser/CLI/output layer. See §11.3.5 below and Chapter 13 for details.
+
 ### 11.2 Built-ins return multiple solutions
 
 Every builtin returns a list of substitution _deltas_.
@@ -1353,6 +1355,47 @@ As _builtins_, `log:implies` and `log:impliedBy` let you **inspect the currently
 
 Each enumerated rule is standardized apart (fresh variable names) before unification so you can safely query over it.
 
+### Top-level directive: `log:query` (output selection)
+
+**Shape (top level only):**
+
+```n3
+{ ...premise... } log:query { ...conclusion... }.
+```
+
+`log:query` is best understood as an **output projection**, not as a rule and not as a normal builtin:
+
+- Eyeling still computes the saturated forward closure (facts + rules, including backward-rule proofs where needed).
+- It then proves the **premise formula** as a goal (as if it were fed to `log:includes` in the global scope).
+- For every solution, it instantiates the **conclusion formula** and collects the resulting triples.
+- The final output is the **set of unique ground triples** from those instantiated conclusions.
+
+This is “forward-rule-like” in spirit (premise ⇒ conclusion), but the instantiated conclusion triples are **not added back into the fact store**; they are just what Eyeling prints.
+
+**Important details:**
+
+- Only **top-level** `{...} log:query {...}.` directives are recognized. Inside quoted formulas (or inside rule bodies/heads) it is just an ordinary triple.
+- Query-mode output depends on the saturated closure, so it cannot be streamed; `--stream` has no effect when any `log:query` directives are present.
+- If you want _logical_ querying inside a rule/proof, use `log:includes` (and optionally `log:conclusion`) instead.
+
+**Example (project a result set):**
+
+```n3
+@prefix : <urn:ex:>.
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+
+{ :a :p ?x } => { :a :q ?x }.
+:a :p :b.
+
+{ :a :q ?x } log:query { :result :x ?x }.
+```
+
+Output (only):
+
+```n3
+:result :x :b .
+```
+
 ### Scoped proof inside formulas: `log:includes` and friends
 
 #### `log:includes`
@@ -1809,6 +1852,14 @@ See also: [Chapter 14 — Entry points: CLI, bundle exports, and npm API](#ch14)
 
 By default, Eyeling prints **newly derived forward facts** (the heads of fired `=>` rules), serialized as N3. It does **not** reprint your input facts.
 
+If the input contains one or more **top-level** `log:query` directives:
+
+```n3
+{ ...premise... } log:query { ...conclusion... }.
+```
+
+Eyeling still computes the saturated forward closure, but it prints only the **unique instantiated conclusion triples** of those `log:query` directives (instead of all newly derived facts). This is useful when you want a forward-rule-like projection of results.
+
 For proof/explanation output and output modes, see:
 
 - [Chapter 13 — Printing, proofs, and the user-facing output](#ch13)
@@ -1835,6 +1886,8 @@ Options:
   -v, --version                Print version and exit.
 ```
 
+Note: when `log:query` directives are present, Eyeling cannot stream output (the selected results depend on the saturated closure), so `--stream` has no effect in that mode.
+
 See also:
 
 - [Chapter 13 — Printing, proofs, and the user-facing output](#ch13)
@@ -2031,7 +2084,7 @@ If you don’t want “stop the world”, derive a `:Violation` fact instead, an
 The most robust way to keep LLM-generated logic plausible is to make it live under tests:
 
 - Keep tiny **fixtures** (facts) alongside the rules.
-- Run Eyeling to produce the **derived closure** (Eyeling can emit only newly derived forward facts, and can optionally include compact proof comments).
+- Run Eyeling to produce the **derived closure** (Eyeling emits only newly derived forward facts by default, can optionally include compact proof comments, and can also use `log:query` directives to project a specific result set).
 - Compare against an expected output (“golden file”) in CI.
 
 This turns rule edits into a normal change-management loop: diffs are explicit, reviewable, and reproducible.

package/README.md

@@ -4,7 +4,8 @@ A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 
 - Single self-contained bundle (`eyeling.js`), no external runtime deps
 - Forward (`=>`) + backward (`<=`) chaining over Horn-style rules
-- Outputs only **newly derived** forward facts (optionally with compact proof comments)
+- Outputs only **newly derived** forward facts by default (optionally with compact proof comments)
+- If the input contains one or more top-level `{ ... } log:query { ... }.` directives, the output becomes the **unique instantiated conclusion triples** of those queries (a forward-rule-like projection)
 - Works in Node.js and fully client-side (browser/worker)
 
 ## Links
@@ -45,6 +46,16 @@ See all options:
 npx eyeling --help
 ```
 
+### log:query output selection
+
+If your input contains one or more **top-level** directives of the form:
+
+```n3
+{ ?x a :Human. } log:query { ?x a :Mortal. }.
+```
+
+Eyeling will still compute the saturated forward closure, but it will **print only** the **unique instantiated conclusion triples** of those `log:query` directives (instead of printing all newly derived forward facts).
+
 ### JavaScript API
 
 CommonJS:
@@ -79,6 +90,9 @@ const { closureN3 } = eyeling.reasonStream(input, {
   proof: false,
   onDerived: ({ triple }) => console.log(triple),
 });
+
+// With log:query directives present, closureN3 contains the query-selected triples.
+// The return value also includes `queryMode`, `queryTriples`, and `queryDerived`.
 ```
 
 > Note: the npm `reason()` helper shells out to the bundled `eyeling.js` CLI for simplicity and robustness.

package/examples/odrl-dpv-risk-ranked.n3

@@ -1,5 +1,5 @@
 # ===========================================================================================
-# ODRL + DPV/DPV-RISK risk assessment with ranked, explainable output.
+# ODRL + DPV risk assessment with ranked, explainable output.
 #
 # What this file does
 # - Models an agreement as an ODRL policy (odrl:Policy) containing permissions,

package/examples/output/socrates.n3

@@ -1,3 +1,4 @@
 @prefix : <http://example.org/socrates#> .
 
+:Socrates a :Human .
 :Socrates a :Mortal .

package/examples/socrates.n3

@@ -3,6 +3,7 @@
 # ==================
 
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
 @prefix : <http://example.org/socrates#>.
 
 # facts
@@ -17,3 +18,5 @@
     ?S a ?B.
 }.
 
+# query
+{ ?S a ?C } log:query { ?S a ?C }.

package/eyeling-builtins.ttl

@@ -256,6 +256,9 @@ log:implies a ex:Builtin ; ex:kind ex:Relation ;
 log:impliedBy a ex:Builtin ; ex:kind ex:Relation ;
   rdfs:comment "Rule/formula relation used for <=." .
 
+log:query a ex:Builtin ; ex:kind ex:Meta ;
+  rdfs:comment "Output-selection directive: a top-level triple {premise} log:query {conclusion}. does not add facts, but selects the unique instantiated conclusion triples as Eyeling's output." .
+
 log:includes a ex:Builtin ; ex:kind ex:Generator ;
   rdfs:comment "Proves the object formula in the (possibly scoped) facts/rules; returns the set of proof substitutions (may bind variables)." .
 

package/eyeling.js

@@ -3798,11 +3798,11 @@ function main() {
   }
 
   let toks;
-  let prefixes, triples, frules, brules;
+  let prefixes, triples, frules, brules, qrules;
   try {
     toks = engine.lex(text);
     const parser = new engine.Parser(toks);
-    [prefixes, triples, frules, brules] = parser.parseDocument();
+    [prefixes, triples, frules, brules, qrules] = parser.parseDocument();
     // Make the parsed prefixes available to log:trace output (CLI path)
     engine.setTracePrefixes(prefixes);
   } catch (e) {
@@ -3822,13 +3822,17 @@ function main() {
       }
       return value;
     }
+    // For backwards compatibility, --ast prints exactly four top-level elements:
+    //   [prefixes, triples, forwardRules, backwardRules]
+    // log:query directives are output-selection statements and are not included
+    // in the legacy AST contract expected by test suites and downstream tools.
     console.log(JSON.stringify([prefixes, triples, frules, brules], astReplacer, 2));
     process.exit(0);
   }
 
   // Materialize anonymous rdf:first/rdf:rest collections into list terms.
   // Named list nodes keep identity; list:* builtins can traverse them.
-  engine.materializeRdfLists(triples, frules, brules);
+  engine.materializeRdfLists(triples, frules.concat(qrules || []), brules);
 
   const facts = triples.filter((tr) => engine.isGroundTriple(tr));
 
@@ -3924,7 +3928,9 @@ function main() {
   }
 
   // Streaming mode: print (input) prefixes first, then print derived triples as soon as they are found.
-  if (streamMode) {
+  // Note: when log:query directives are present, we cannot stream output because
+  // the selected results depend on the saturated closure.
+  if (streamMode && !(Array.isArray(qrules) && qrules.length)) {
     const usedInInput = prefixesUsedInInputTokens(toks, prefixes);
     const outPrefixes = restrictPrefixEnv(prefixes, usedInInput);
 
@@ -3953,18 +3959,36 @@ function main() {
     return;
   }
 
-  // Default (non-streaming): derive everything first, then print only the newly derived facts.
-  const derived = engine.forwardChain(facts, frules, brules);
-  const derivedTriples = derived.map((df) => df.fact);
-  const usedPrefixes = prefixes.prefixesUsedForOutput(derivedTriples);
+  const hasQueries = Array.isArray(qrules) && qrules.length;
+
+  // Default (non-streaming):
+  // - without log:query: derive everything first, then print only newly derived facts
+  // - with log:query: derive everything first, then print only unique instantiated
+  //   conclusion triples from the log:query directives.
+  let derived = [];
+  let outTriples = [];
+  let outDerived = [];
+
+  if (hasQueries) {
+    const res = engine.forwardChainAndCollectLogQueryConclusions(facts, frules, brules, qrules);
+    derived = res.derived;
+    outTriples = res.queryTriples;
+    outDerived = res.queryDerived;
+  } else {
+    derived = engine.forwardChain(facts, frules, brules);
+    outDerived = derived;
+    outTriples = derived.map((df) => df.fact);
+  }
+
+  const usedPrefixes = prefixes.prefixesUsedForOutput(outTriples);
 
   for (const [pfx, base] of usedPrefixes) {
     if (pfx === '') console.log(`@prefix : <${base}> .`);
     else console.log(`@prefix ${pfx}: <${base}> .`);
   }
-  if (derived.length && usedPrefixes.length) console.log();
+  if (outTriples.length && usedPrefixes.length) console.log();
 
-  for (const df of derived) {
+  for (const df of outDerived) {
     if (engine.getProofCommentsEnabled()) {
       engine.printExplanation(df, prefixes);
       console.log(engine.tripleToN3(df.fact, prefixes));
@@ -6820,6 +6844,159 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */)
   }
 }
 
+// ---------------------------------------------------------------------------
+// log:query output selection
+// ---------------------------------------------------------------------------
+// A top-level directive of the form:
+//   { premise } log:query { conclusion }.
+// does not add facts to the closure. Instead, when one or more such directives
+// are present in the input, eyeling outputs only the **unique instantiated**
+// conclusion triples for each solution of the premise (similar to a forward
+// rule head projection).
+
+function __tripleKeyForOutput(tr) {
+  // Use a canonical structural encoding (covers lists and quoted graphs).
+  // Note: this is used only for de-duplication of output triples.
+  return skolemKeyFromTerm(tr.s) + '\t' + skolemKeyFromTerm(tr.p) + '\t' + skolemKeyFromTerm(tr.o);
+}
+
+function __withScopedSnapshotForQueries(facts, fn) {
+  // Some scoped log:* builtins "delay" unless a frozen snapshot exists.
+  // After forwardChain completes, we create a snapshot of the saturated
+  // closure so query premises can use scoped builtins reliably.
+  const oldSnap = hasOwn.call(facts, '__scopedSnapshot') ? facts.__scopedSnapshot : undefined;
+  const oldLvl = hasOwn.call(facts, '__scopedClosureLevel') ? facts.__scopedClosureLevel : undefined;
+
+  // Create a frozen snapshot of the saturated closure.
+  const snap = facts.slice();
+  ensureFactIndexes(snap);
+  Object.defineProperty(snap, '__scopedSnapshot', {
+    value: snap,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(snap, '__scopedClosureLevel', {
+    value: Number.MAX_SAFE_INTEGER,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+
+  // Ensure the live facts array exposes the snapshot/level for builtins.
+  if (!hasOwn.call(facts, '__scopedSnapshot')) {
+    Object.defineProperty(facts, '__scopedSnapshot', {
+      value: null,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+  if (!hasOwn.call(facts, '__scopedClosureLevel')) {
+    Object.defineProperty(facts, '__scopedClosureLevel', {
+      value: 0,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+
+  facts.__scopedSnapshot = snap;
+  facts.__scopedClosureLevel = Number.MAX_SAFE_INTEGER;
+
+  try {
+    return fn();
+  } finally {
+    facts.__scopedSnapshot = oldSnap === undefined ? null : oldSnap;
+    facts.__scopedClosureLevel = oldLvl === undefined ? 0 : oldLvl;
+  }
+}
+
+function collectLogQueryConclusions(logQueryRules, facts, backRules) {
+  const queryTriples = [];
+  const queryDerived = [];
+  const seen = new Set();
+
+  if (!Array.isArray(logQueryRules) || logQueryRules.length === 0) {
+    return { queryTriples, queryDerived };
+  }
+
+  ensureFactIndexes(facts);
+  ensureBackRuleIndexes(backRules);
+
+  // Shared state across all query firings (mirrors forwardChain()).
+  const varGen = [0];
+  const skCounter = [0];
+  const headSkolemCache = new Map();
+
+  return __withScopedSnapshotForQueries(facts, () => {
+    for (let qi = 0; qi < logQueryRules.length; qi++) {
+      const r = logQueryRules[qi];
+      if (!r || !Array.isArray(r.premise) || !Array.isArray(r.conclusion)) continue;
+
+      const sols = proveGoals(r.premise, null, facts, backRules, 0, null, varGen, undefined, {
+        deferBuiltins: true,
+      });
+
+      for (const s of sols) {
+        const skMap = {};
+        const instantiatedPremises = r.premise.map((b) => applySubstTriple(b, s));
+        const fireKey = __firingKey(1000000 + qi, instantiatedPremises);
+
+        // Support dynamic heads (same semantics as forwardChain).
+        let dynamicHeadTriples = null;
+        let headBlankLabelsHere = r.headBlankLabels;
+        if (r.__dynamicConclusionTerm) {
+          const dynTerm = applySubstTerm(r.__dynamicConclusionTerm, s);
+          const dynTriples = __graphTriplesOrTrue(dynTerm);
+          dynamicHeadTriples = dynTriples !== null ? dynTriples : [];
+          const dynHeadBlankLabels =
+            dynamicHeadTriples && dynamicHeadTriples.length ? collectBlankLabelsInTriples(dynamicHeadTriples) : null;
+          if (dynHeadBlankLabels && dynHeadBlankLabels.size) {
+            headBlankLabelsHere = new Set([...headBlankLabelsHere, ...dynHeadBlankLabels]);
+          }
+        }
+
+        const headPatterns =
+          dynamicHeadTriples && dynamicHeadTriples.length ? r.conclusion.concat(dynamicHeadTriples) : r.conclusion;
+
+        for (const cpat of headPatterns) {
+          const instantiated = applySubstTriple(cpat, s);
+          const inst = skolemizeTripleForHeadBlanks(
+            instantiated,
+            headBlankLabelsHere,
+            skMap,
+            skCounter,
+            fireKey,
+            headSkolemCache,
+          );
+          if (!isGroundTriple(inst)) continue;
+          const k = __tripleKeyForOutput(inst);
+          if (seen.has(k)) continue;
+          seen.add(k);
+          queryTriples.push(inst);
+          queryDerived.push(new DerivedFact(inst, r, instantiatedPremises.slice(), { ...s }));
+        }
+      }
+    }
+
+    return { queryTriples, queryDerived };
+  });
+}
+
+function forwardChainAndCollectLogQueryConclusions(facts, forwardRules, backRules, logQueryRules, onDerived) {
+  __enterReasoningRun();
+  try {
+    // Forward chain first (saturates `facts`).
+    const derived = forwardChain(facts, forwardRules, backRules, onDerived);
+    // Then collect query conclusions against the saturated closure.
+    const { queryTriples, queryDerived } = collectLogQueryConclusions(logQueryRules, facts, backRules);
+    return { derived, queryTriples, queryDerived };
+  } finally {
+    __exitReasoningRun();
+  }
+}
+
 // (proof printing + log:outputString moved to lib/explain.js)
 
 function reasonStream(n3Text, opts = {}) {
@@ -6839,32 +7016,62 @@ function reasonStream(n3Text, opts = {}) {
   const parser = new Parser(toks);
   if (baseIri) parser.prefixes.setBase(baseIri);
 
-  const [prefixes, triples, frules, brules] = parser.parseDocument();
+  const [prefixes, triples, frules, brules, logQueryRules] = parser.parseDocument();
   // Make the parsed prefixes available to log:trace output
   trace.setTracePrefixes(prefixes);
 
   // Materialize anonymous rdf:first/rdf:rest collections into list terms.
   // Named list nodes keep identity; list:* builtins can traverse them.
-  materializeRdfLists(triples, frules, brules);
+  materializeRdfLists(triples, frules.concat(logQueryRules || []), brules);
 
   // facts becomes the saturated closure because pushFactIndexed(...) appends into it
   const facts = triples.filter((tr) => isGroundTriple(tr));
 
-  const derived = forwardChain(facts, frules, brules, (df) => {
+  let derived = [];
+  let queryTriples = [];
+  let queryDerived = [];
+
+  if (Array.isArray(logQueryRules) && logQueryRules.length) {
+    // Query-selection mode: derive full closure, then output only the unique
+    // instantiated conclusion triples of the log:query directives.
+    const res = forwardChainAndCollectLogQueryConclusions(facts, frules, brules, logQueryRules);
+    derived = res.derived;
+    queryTriples = res.queryTriples;
+    queryDerived = res.queryDerived;
+
+    // For compatibility with the streaming callback signature, we emit the
+    // query-selected triples (not all derived facts).
     if (typeof onDerived === 'function') {
-      onDerived({
-        triple: tripleToN3(df.fact, prefixes),
-        df,
-      });
+      for (const qdf of queryDerived) {
+        onDerived({ triple: tripleToN3(qdf.fact, prefixes), df: qdf });
+      }
     }
-  });
+  } else {
+    // Default mode: output only newly derived forward facts.
+    derived = forwardChain(facts, frules, brules, (df) => {
+      if (typeof onDerived === 'function') {
+        onDerived({
+          triple: tripleToN3(df.fact, prefixes),
+          df,
+        });
+      }
+    });
+  }
 
-  const closureTriples = includeInputFactsInClosure ? facts : derived.map((d) => d.fact);
+  const closureTriples =
+    Array.isArray(logQueryRules) && logQueryRules.length
+      ? queryTriples
+      : includeInputFactsInClosure
+        ? facts
+        : derived.map((d) => d.fact);
 
   const __out = {
     prefixes,
     facts, // saturated closure (Triple[])
     derived, // DerivedFact[]
+    queryMode: Array.isArray(logQueryRules) && logQueryRules.length ? true : false,
+    queryTriples,
+    queryDerived,
     closureN3: closureTriples.map((t) => tripleToN3(t, prefixes)).join('\n'),
   };
   deref.setEnforceHttpsEnabled(__oldEnforceHttps);
@@ -6917,6 +7124,8 @@ function setTracePrefixes(v) {
 
 module.exports = {
   reasonStream,
+  collectLogQueryConclusions,
+  forwardChainAndCollectLogQueryConclusions,
   collectOutputStringsFromFacts,
   main,
   version,
@@ -6969,6 +7178,8 @@ module.exports = {
   lex: engine.lex,
   Parser: engine.Parser,
   forwardChain: engine.forwardChain,
+  collectLogQueryConclusions: engine.collectLogQueryConclusions,
+  forwardChainAndCollectLogQueryConclusions: engine.forwardChainAndCollectLogQueryConclusions,
   materializeRdfLists: engine.materializeRdfLists,
   isGroundTriple: engine.isGroundTriple,
   printExplanation: engine.printExplanation,
@@ -7879,6 +8090,7 @@ const {
   collectBlankLabelsInTriples,
   isLogImplies,
   isLogImpliedBy,
+  isLogQuery,
 } = require('./prelude');
 
 const { N3SyntaxError } = require('./lexer');
@@ -7927,6 +8139,7 @@ class Parser {
     const triples = [];
     const forwardRules = [];
     const backwardRules = [];
+    const logQueries = [];
 
     while (this.peek().typ !== 'EOF') {
       if (this.peek().typ === 'AtPrefix') {
@@ -8001,6 +8214,11 @@ class Parser {
               forwardRules.push(this.makeRule(tr.s, tr.o, true));
             } else if (isLogImpliedBy(tr.p) && tr.s instanceof GraphTerm && tr.o instanceof GraphTerm) {
               backwardRules.push(this.makeRule(tr.s, tr.o, false));
+            } else if (isLogQuery(tr.p) && tr.s instanceof GraphTerm && tr.o instanceof GraphTerm) {
+              // Output-selection directive: { premise } log:query { conclusion }.
+              // When present at top-level, eyeling prints only the instantiated conclusion
+              // triples (unique) instead of all newly derived facts.
+              logQueries.push(this.makeRule(tr.s, tr.o, true));
             } else {
               triples.push(tr);
             }
@@ -8009,7 +8227,7 @@ class Parser {
       }
     }
 
-    return [this.prefixes, triples, forwardRules, backwardRules];
+    return [this.prefixes, triples, forwardRules, backwardRules, logQueries];
   }
 
   parsePrefixDirective() {
@@ -8950,6 +9168,10 @@ function isLogImpliedBy(p) {
   return p instanceof Iri && p.value === LOG_NS + 'impliedBy';
 }
 
+function isLogQuery(p) {
+  return p instanceof Iri && p.value === LOG_NS + 'query';
+}
+
 // ===========================================================================
 // PREFIX ENVIRONMENT
 // ===========================================================================
@@ -9161,6 +9383,7 @@ module.exports = {
   isOwlSameAsPred,
   isLogImplies,
   isLogImpliedBy,
+  isLogQuery,
   PrefixEnv,
   collectIrisInTerm,
   varsInRule,

package/lib/cli.js

@@ -137,11 +137,11 @@ function main() {
   }
 
   let toks;
-  let prefixes, triples, frules, brules;
+  let prefixes, triples, frules, brules, qrules;
   try {
     toks = engine.lex(text);
     const parser = new engine.Parser(toks);
-    [prefixes, triples, frules, brules] = parser.parseDocument();
+    [prefixes, triples, frules, brules, qrules] = parser.parseDocument();
     // Make the parsed prefixes available to log:trace output (CLI path)
     engine.setTracePrefixes(prefixes);
   } catch (e) {
@@ -161,13 +161,17 @@ function main() {
       }
       return value;
     }
+    // For backwards compatibility, --ast prints exactly four top-level elements:
+    //   [prefixes, triples, forwardRules, backwardRules]
+    // log:query directives are output-selection statements and are not included
+    // in the legacy AST contract expected by test suites and downstream tools.
     console.log(JSON.stringify([prefixes, triples, frules, brules], astReplacer, 2));
     process.exit(0);
   }
 
   // Materialize anonymous rdf:first/rdf:rest collections into list terms.
   // Named list nodes keep identity; list:* builtins can traverse them.
-  engine.materializeRdfLists(triples, frules, brules);
+  engine.materializeRdfLists(triples, frules.concat(qrules || []), brules);
 
   const facts = triples.filter((tr) => engine.isGroundTriple(tr));
 
@@ -263,7 +267,9 @@ function main() {
   }
 
   // Streaming mode: print (input) prefixes first, then print derived triples as soon as they are found.
-  if (streamMode) {
+  // Note: when log:query directives are present, we cannot stream output because
+  // the selected results depend on the saturated closure.
+  if (streamMode && !(Array.isArray(qrules) && qrules.length)) {
     const usedInInput = prefixesUsedInInputTokens(toks, prefixes);
     const outPrefixes = restrictPrefixEnv(prefixes, usedInInput);
 
@@ -292,18 +298,36 @@ function main() {
     return;
   }
 
-  // Default (non-streaming): derive everything first, then print only the newly derived facts.
-  const derived = engine.forwardChain(facts, frules, brules);
-  const derivedTriples = derived.map((df) => df.fact);
-  const usedPrefixes = prefixes.prefixesUsedForOutput(derivedTriples);
+  const hasQueries = Array.isArray(qrules) && qrules.length;
+
+  // Default (non-streaming):
+  // - without log:query: derive everything first, then print only newly derived facts
+  // - with log:query: derive everything first, then print only unique instantiated
+  //   conclusion triples from the log:query directives.
+  let derived = [];
+  let outTriples = [];
+  let outDerived = [];
+
+  if (hasQueries) {
+    const res = engine.forwardChainAndCollectLogQueryConclusions(facts, frules, brules, qrules);
+    derived = res.derived;
+    outTriples = res.queryTriples;
+    outDerived = res.queryDerived;
+  } else {
+    derived = engine.forwardChain(facts, frules, brules);
+    outDerived = derived;
+    outTriples = derived.map((df) => df.fact);
+  }
+
+  const usedPrefixes = prefixes.prefixesUsedForOutput(outTriples);
 
   for (const [pfx, base] of usedPrefixes) {
     if (pfx === '') console.log(`@prefix : <${base}> .`);
     else console.log(`@prefix ${pfx}: <${base}> .`);
   }
-  if (derived.length && usedPrefixes.length) console.log();
+  if (outTriples.length && usedPrefixes.length) console.log();
 
-  for (const df of derived) {
+  for (const df of outDerived) {
     if (engine.getProofCommentsEnabled()) {
       engine.printExplanation(df, prefixes);
       console.log(engine.tripleToN3(df.fact, prefixes));

package/lib/engine.js

@@ -2378,6 +2378,159 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */)
   }
 }
 
+// ---------------------------------------------------------------------------
+// log:query output selection
+// ---------------------------------------------------------------------------
+// A top-level directive of the form:
+//   { premise } log:query { conclusion }.
+// does not add facts to the closure. Instead, when one or more such directives
+// are present in the input, eyeling outputs only the **unique instantiated**
+// conclusion triples for each solution of the premise (similar to a forward
+// rule head projection).
+
+function __tripleKeyForOutput(tr) {
+  // Use a canonical structural encoding (covers lists and quoted graphs).
+  // Note: this is used only for de-duplication of output triples.
+  return skolemKeyFromTerm(tr.s) + '\t' + skolemKeyFromTerm(tr.p) + '\t' + skolemKeyFromTerm(tr.o);
+}
+
+function __withScopedSnapshotForQueries(facts, fn) {
+  // Some scoped log:* builtins "delay" unless a frozen snapshot exists.
+  // After forwardChain completes, we create a snapshot of the saturated
+  // closure so query premises can use scoped builtins reliably.
+  const oldSnap = hasOwn.call(facts, '__scopedSnapshot') ? facts.__scopedSnapshot : undefined;
+  const oldLvl = hasOwn.call(facts, '__scopedClosureLevel') ? facts.__scopedClosureLevel : undefined;
+
+  // Create a frozen snapshot of the saturated closure.
+  const snap = facts.slice();
+  ensureFactIndexes(snap);
+  Object.defineProperty(snap, '__scopedSnapshot', {
+    value: snap,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(snap, '__scopedClosureLevel', {
+    value: Number.MAX_SAFE_INTEGER,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+
+  // Ensure the live facts array exposes the snapshot/level for builtins.
+  if (!hasOwn.call(facts, '__scopedSnapshot')) {
+    Object.defineProperty(facts, '__scopedSnapshot', {
+      value: null,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+  if (!hasOwn.call(facts, '__scopedClosureLevel')) {
+    Object.defineProperty(facts, '__scopedClosureLevel', {
+      value: 0,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+
+  facts.__scopedSnapshot = snap;
+  facts.__scopedClosureLevel = Number.MAX_SAFE_INTEGER;
+
+  try {
+    return fn();
+  } finally {
+    facts.__scopedSnapshot = oldSnap === undefined ? null : oldSnap;
+    facts.__scopedClosureLevel = oldLvl === undefined ? 0 : oldLvl;
+  }
+}
+
+function collectLogQueryConclusions(logQueryRules, facts, backRules) {
+  const queryTriples = [];
+  const queryDerived = [];
+  const seen = new Set();
+
+  if (!Array.isArray(logQueryRules) || logQueryRules.length === 0) {
+    return { queryTriples, queryDerived };
+  }
+
+  ensureFactIndexes(facts);
+  ensureBackRuleIndexes(backRules);
+
+  // Shared state across all query firings (mirrors forwardChain()).
+  const varGen = [0];
+  const skCounter = [0];
+  const headSkolemCache = new Map();
+
+  return __withScopedSnapshotForQueries(facts, () => {
+    for (let qi = 0; qi < logQueryRules.length; qi++) {
+      const r = logQueryRules[qi];
+      if (!r || !Array.isArray(r.premise) || !Array.isArray(r.conclusion)) continue;
+
+      const sols = proveGoals(r.premise, null, facts, backRules, 0, null, varGen, undefined, {
+        deferBuiltins: true,
+      });
+
+      for (const s of sols) {
+        const skMap = {};
+        const instantiatedPremises = r.premise.map((b) => applySubstTriple(b, s));
+        const fireKey = __firingKey(1000000 + qi, instantiatedPremises);
+
+        // Support dynamic heads (same semantics as forwardChain).
+        let dynamicHeadTriples = null;
+        let headBlankLabelsHere = r.headBlankLabels;
+        if (r.__dynamicConclusionTerm) {
+          const dynTerm = applySubstTerm(r.__dynamicConclusionTerm, s);
+          const dynTriples = __graphTriplesOrTrue(dynTerm);
+          dynamicHeadTriples = dynTriples !== null ? dynTriples : [];
+          const dynHeadBlankLabels =
+            dynamicHeadTriples && dynamicHeadTriples.length ? collectBlankLabelsInTriples(dynamicHeadTriples) : null;
+          if (dynHeadBlankLabels && dynHeadBlankLabels.size) {
+            headBlankLabelsHere = new Set([...headBlankLabelsHere, ...dynHeadBlankLabels]);
+          }
+        }
+
+        const headPatterns =
+          dynamicHeadTriples && dynamicHeadTriples.length ? r.conclusion.concat(dynamicHeadTriples) : r.conclusion;
+
+        for (const cpat of headPatterns) {
+          const instantiated = applySubstTriple(cpat, s);
+          const inst = skolemizeTripleForHeadBlanks(
+            instantiated,
+            headBlankLabelsHere,
+            skMap,
+            skCounter,
+            fireKey,
+            headSkolemCache,
+          );
+          if (!isGroundTriple(inst)) continue;
+          const k = __tripleKeyForOutput(inst);
+          if (seen.has(k)) continue;
+          seen.add(k);
+          queryTriples.push(inst);
+          queryDerived.push(new DerivedFact(inst, r, instantiatedPremises.slice(), { ...s }));
+        }
+      }
+    }
+
+    return { queryTriples, queryDerived };
+  });
+}
+
+function forwardChainAndCollectLogQueryConclusions(facts, forwardRules, backRules, logQueryRules, onDerived) {
+  __enterReasoningRun();
+  try {
+    // Forward chain first (saturates `facts`).
+    const derived = forwardChain(facts, forwardRules, backRules, onDerived);
+    // Then collect query conclusions against the saturated closure.
+    const { queryTriples, queryDerived } = collectLogQueryConclusions(logQueryRules, facts, backRules);
+    return { derived, queryTriples, queryDerived };
+  } finally {
+    __exitReasoningRun();
+  }
+}
+
 // (proof printing + log:outputString moved to lib/explain.js)
 
 function reasonStream(n3Text, opts = {}) {
@@ -2397,32 +2550,62 @@ function reasonStream(n3Text, opts = {}) {
   const parser = new Parser(toks);
   if (baseIri) parser.prefixes.setBase(baseIri);
 
-  const [prefixes, triples, frules, brules] = parser.parseDocument();
+  const [prefixes, triples, frules, brules, logQueryRules] = parser.parseDocument();
   // Make the parsed prefixes available to log:trace output
   trace.setTracePrefixes(prefixes);
 
   // Materialize anonymous rdf:first/rdf:rest collections into list terms.
   // Named list nodes keep identity; list:* builtins can traverse them.
-  materializeRdfLists(triples, frules, brules);
+  materializeRdfLists(triples, frules.concat(logQueryRules || []), brules);
 
   // facts becomes the saturated closure because pushFactIndexed(...) appends into it
   const facts = triples.filter((tr) => isGroundTriple(tr));
 
-  const derived = forwardChain(facts, frules, brules, (df) => {
+  let derived = [];
+  let queryTriples = [];
+  let queryDerived = [];
+
+  if (Array.isArray(logQueryRules) && logQueryRules.length) {
+    // Query-selection mode: derive full closure, then output only the unique
+    // instantiated conclusion triples of the log:query directives.
+    const res = forwardChainAndCollectLogQueryConclusions(facts, frules, brules, logQueryRules);
+    derived = res.derived;
+    queryTriples = res.queryTriples;
+    queryDerived = res.queryDerived;
+
+    // For compatibility with the streaming callback signature, we emit the
+    // query-selected triples (not all derived facts).
     if (typeof onDerived === 'function') {
-      onDerived({
-        triple: tripleToN3(df.fact, prefixes),
-        df,
-      });
+      for (const qdf of queryDerived) {
+        onDerived({ triple: tripleToN3(qdf.fact, prefixes), df: qdf });
+      }
     }
-  });
+  } else {
+    // Default mode: output only newly derived forward facts.
+    derived = forwardChain(facts, frules, brules, (df) => {
+      if (typeof onDerived === 'function') {
+        onDerived({
+          triple: tripleToN3(df.fact, prefixes),
+          df,
+        });
+      }
+    });
+  }
 
-  const closureTriples = includeInputFactsInClosure ? facts : derived.map((d) => d.fact);
+  const closureTriples =
+    Array.isArray(logQueryRules) && logQueryRules.length
+      ? queryTriples
+      : includeInputFactsInClosure
+        ? facts
+        : derived.map((d) => d.fact);
 
   const __out = {
     prefixes,
     facts, // saturated closure (Triple[])
     derived, // DerivedFact[]
+    queryMode: Array.isArray(logQueryRules) && logQueryRules.length ? true : false,
+    queryTriples,
+    queryDerived,
     closureN3: closureTriples.map((t) => tripleToN3(t, prefixes)).join('\n'),
   };
   deref.setEnforceHttpsEnabled(__oldEnforceHttps);
@@ -2475,6 +2658,8 @@ function setTracePrefixes(v) {
 
 module.exports = {
   reasonStream,
+  collectLogQueryConclusions,
+  forwardChainAndCollectLogQueryConclusions,
   collectOutputStringsFromFacts,
   main,
   version,

package/lib/entry.js

@@ -23,6 +23,8 @@ module.exports = {
   lex: engine.lex,
   Parser: engine.Parser,
   forwardChain: engine.forwardChain,
+  collectLogQueryConclusions: engine.collectLogQueryConclusions,
+  forwardChainAndCollectLogQueryConclusions: engine.forwardChainAndCollectLogQueryConclusions,
   materializeRdfLists: engine.materializeRdfLists,
   isGroundTriple: engine.isGroundTriple,
   printExplanation: engine.printExplanation,

package/lib/parser.js

@@ -25,6 +25,7 @@ const {
   collectBlankLabelsInTriples,
   isLogImplies,
   isLogImpliedBy,
+  isLogQuery,
 } = require('./prelude');
 
 const { N3SyntaxError } = require('./lexer');
@@ -73,6 +74,7 @@ class Parser {
     const triples = [];
     const forwardRules = [];
     const backwardRules = [];
+    const logQueries = [];
 
     while (this.peek().typ !== 'EOF') {
       if (this.peek().typ === 'AtPrefix') {
@@ -147,6 +149,11 @@ class Parser {
               forwardRules.push(this.makeRule(tr.s, tr.o, true));
             } else if (isLogImpliedBy(tr.p) && tr.s instanceof GraphTerm && tr.o instanceof GraphTerm) {
               backwardRules.push(this.makeRule(tr.s, tr.o, false));
+            } else if (isLogQuery(tr.p) && tr.s instanceof GraphTerm && tr.o instanceof GraphTerm) {
+              // Output-selection directive: { premise } log:query { conclusion }.
+              // When present at top-level, eyeling prints only the instantiated conclusion
+              // triples (unique) instead of all newly derived facts.
+              logQueries.push(this.makeRule(tr.s, tr.o, true));
             } else {
               triples.push(tr);
             }
@@ -155,7 +162,7 @@ class Parser {
       }
     }
 
-    return [this.prefixes, triples, forwardRules, backwardRules];
+    return [this.prefixes, triples, forwardRules, backwardRules, logQueries];
   }
 
   parsePrefixDirective() {

package/lib/prelude.js

@@ -317,6 +317,10 @@ function isLogImpliedBy(p) {
   return p instanceof Iri && p.value === LOG_NS + 'impliedBy';
 }
 
+function isLogQuery(p) {
+  return p instanceof Iri && p.value === LOG_NS + 'query';
+}
+
 // ===========================================================================
 // PREFIX ENVIRONMENT
 // ===========================================================================
@@ -528,6 +532,7 @@ module.exports = {
   isOwlSameAsPred,
   isLogImplies,
   isLogImpliedBy,
+  isLogQuery,
   PrefixEnv,
   collectIrisInTerm,
   varsInRule,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.12.15",
+  "version": "1.13.0",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [

package/tools/n3gen.js

@@ -101,7 +101,6 @@ const log = {
   nameOf: `${LOG_NS}nameOf`,
 };
 
-
 // ---------------------------------------------------------------------------
 // Minimal Turtle/N3 model + lexer + parser
 // ---------------------------------------------------------------------------
@@ -2001,7 +2000,10 @@ function writeN3LogNameOf({ datasetQuads, prefixes }) {
   const prunedPrefixes = pruneUnusedPrefixes(prefixes, pseudoTriplesForUse);
   const skolemMap = buildSkolemMapForBnodesThatCrossScopes(pseudoTriplesForUse);
   const outPrefixes = ensureRdfPrefixIfUsed(
-    ensureXsdPrefixIfUsed(ensureLogPrefixIfUsed(ensureSkolemPrefix(prunedPrefixes, skolemMap), pseudoTriplesForUse), pseudoTriplesForUse),
+    ensureXsdPrefixIfUsed(
+      ensureLogPrefixIfUsed(ensureSkolemPrefix(prunedPrefixes, skolemMap), pseudoTriplesForUse),
+      pseudoTriplesForUse,
+    ),
     pseudoTriplesForUse,
   );
   const pro = renderPrefixPrologue(outPrefixes).trim();
@@ -2059,7 +2061,10 @@ function writeN3Triples({ triples, prefixes }) {
   const prunedPrefixes = pruneUnusedPrefixes(prefixes, foldedTriples);
   const skolemMap = buildSkolemMapForBnodesThatCrossScopes(foldedTriples);
   const outPrefixes = ensureRdfPrefixIfUsed(
-    ensureXsdPrefixIfUsed(ensureLogPrefixIfUsed(ensureSkolemPrefix(prunedPrefixes, skolemMap), foldedTriples), foldedTriples),
+    ensureXsdPrefixIfUsed(
+      ensureLogPrefixIfUsed(ensureSkolemPrefix(prunedPrefixes, skolemMap), foldedTriples),
+      foldedTriples,
+    ),
     foldedTriples,
   );
   const blocks = [];