eyeling 1.23.0 → 1.23.2

package/HANDBOOK.md

@@ -358,7 +358,9 @@ That distinction matters because quoted formulas still play **two different role
 
 The practical rule is:
 
-> **Eyeling lifts blanks inside quoted formulas only when the quoted formula appears directly in a premise triple position. Nested quoted formulas remain scoped data unless a query-like builtin interprets them as patterns.**
+> **Eyeling lifts blanks inside quoted formulas only when the quoted formula appears directly in an ordinary premise triple position.**
+>
+> For `log:includes` and `log:notIncludes`, quoted formula operands keep their own blank-node scope. The builtin may treat blanks in the goal formula existentially while proving it, but blanks in an explicit scope graph remain formula-local blanks and may be returned as blank nodes rather than synthetic variables such as `?_b1`.
 
 This keeps `log:conjunction` and formula printing honest, while still allowing direct quoted-formula premise patterns such as `{ _:X :B :C } a :Statement.` to match interoperably.
 
@@ -1526,6 +1528,7 @@ Eyeling has **two modes**:
 1. **Explicit scope graph**: if `Scope` is a formula `{...}`
    - Eyeling reasons _only inside that formula_ (its triples are the fact store).
    - External rules are not used.
+   - Blank nodes inside the explicit scope graph are preserved as graph-local blanks; if a goal variable matches one, the binding is a blank node, not a lifted rule variable.
 
 2. **Priority-gated global scope**: otherwise
    - Eyeling uses a _frozen snapshot_ of the current global closure.
@@ -1871,7 +1874,7 @@ echo '@prefix : <http://example.org/> .
 { ?x a :Man } => { ?x a :Mortal } .' | npx eyeling
 ```
 
-You can also pass one or more file paths/URLs, or `-` to read explicitly from stdin. When multiple inputs are given, Eyeling parses each source separately, merges the parsed ASTs, and then runs one reasoning pass over the combined facts and rules. This avoids constructing one giant N3 source string.
+You can also pass one or more file paths/URLs, or `-` to read explicitly from stdin. When multiple inputs are given, Eyeling parses each source separately, merges the parsed ASTs, and then runs one reasoning pass over the combined facts and rules. This avoids constructing one giant N3 source string. During the merge path, parse-only artifacts such as source text and token arrays are discarded after the AST has been built, except while formatting syntax errors or when an internal caller explicitly asks to keep those artifacts for debugging.
 
 Show the available options:
 
@@ -2054,6 +2057,8 @@ console.log(out);
 
 In a source list, each source is parsed with its own blank-node scope and optional base IRI. That means the same explicit blank label, such as `_:x`, in two different sources does not accidentally become the same blank node after merging. Prefix declarations are merged mainly for readable output; IRI expansion has already happened while each source was parsed.
 
+For large inputs, the source-list path is also the preferred memory shape: each source is lexed and parsed independently, then Eyeling keeps the merged facts/rules rather than retaining the original source strings and token arrays. The parser still needs one JavaScript string per source, so source splitting is not a streaming parser, but it avoids both a single giant concatenated N3 string and long-lived token arrays after parsing.
+
 For RDF/JS facts, the graph must be the default graph. Named-graph quads are rejected.
 
 If you already have rules in structured form, Eyeling rule objects can be passed directly in the API:

package/dist/browser/eyeling.browser.js

@@ -5132,6 +5132,8 @@
             parseN3Text(text, {
               baseIri: __sourceLabelToBaseIri(sourceLabel),
               label: sourceLabel,
+              collectUsedPrefixes: true,
+              keepSourceArtifacts: false,
             }),
           );
         } catch (e) {
@@ -5149,8 +5151,6 @@
       const frules = mergedDocument.frules;
       const brules = mergedDocument.brules;
       const qrules = mergedDocument.logQueryRules;
-      const tokenSets = parsedSources.map((source) => ({ tokens: source.tokens, prefixes: source.prefixes }));
-
       if (showAst) {
         function astReplacer(unusedJsonKey, value) {
           if (value instanceof Set) return Array.from(value);
@@ -5208,75 +5208,6 @@
       // In --stream mode we print prefixes *before* any derivations happen.
       // To keep the header small and stable, emit only prefixes that are actually
       // used (as QNames) in the *input* N3 program.
-      function prefixesUsedInInputTokens(toks2, prefEnv) {
-        const used = new Set();
-
-        function maybeAddFromQName(name) {
-          if (typeof name !== 'string') return;
-          if (!name.includes(':')) return;
-          if (name.startsWith('_:')) return; // blank node
-
-          // Split only on the first ':'
-          const idx = name.indexOf(':');
-          const p = name.slice(0, idx); // may be '' for ":foo"
-
-          // Ignore things like "http://..." unless that prefix is actually defined.
-          if (!Object.prototype.hasOwnProperty.call(prefEnv.map, p)) return;
-
-          used.add(p);
-        }
-
-        for (let i = 0; i < toks2.length; i++) {
-          const t = toks2[i];
-
-          // Skip @prefix ... .
-          if (t.typ === 'AtPrefix') {
-            while (i < toks2.length && toks2[i].typ !== 'Dot' && toks2[i].typ !== 'EOF') i++;
-            continue;
-          }
-          // Skip @base ... .
-          if (t.typ === 'AtBase') {
-            while (i < toks2.length && toks2[i].typ !== 'Dot' && toks2[i].typ !== 'EOF') i++;
-            continue;
-          }
-
-          // Skip SPARQL/Turtle PREFIX pfx: <iri>
-          if (
-            t.typ === 'Ident' &&
-            typeof t.value === 'string' &&
-            t.value.toLowerCase() === 'prefix' &&
-            toks2[i + 1] &&
-            toks2[i + 1].typ === 'Ident' &&
-            typeof toks2[i + 1].value === 'string' &&
-            toks2[i + 1].value.endsWith(':') &&
-            toks2[i + 2] &&
-            (toks2[i + 2].typ === 'IriRef' || toks2[i + 2].typ === 'Ident')
-          ) {
-            i += 2;
-            continue;
-          }
-
-          // Skip SPARQL BASE <iri>
-          if (
-            t.typ === 'Ident' &&
-            typeof t.value === 'string' &&
-            t.value.toLowerCase() === 'base' &&
-            toks2[i + 1] &&
-            toks2[i + 1].typ === 'IriRef'
-          ) {
-            i += 1;
-            continue;
-          }
-
-          // Count QNames in identifiers (including datatypes like xsd:integer).
-          if (t.typ === 'Ident') {
-            maybeAddFromQName(t.value);
-          }
-        }
-
-        return used;
-      }
-
       function restrictPrefixEnv(prefEnv, usedSet) {
         const m = {};
         for (const p of usedSet) {
@@ -5294,10 +5225,8 @@
       const mayAutoRenderOutputStrings = programMayProduceOutputStrings(triples, frules, qrules);
 
       if (streamMode && !hasQueries && !mayAutoRenderOutputStrings) {
-        const usedInInput = new Set();
-        for (const source of tokenSets) {
-          for (const pfx of prefixesUsedInInputTokens(source.tokens, source.prefixes)) usedInInput.add(pfx);
-        }
+        const usedInInput =
+          mergedDocument.usedPrefixes instanceof Set ? new Set(mergedDocument.usedPrefixes) : new Set();
         const outPrefixes = restrictPrefixEnv(prefixes, usedInInput);
 
         // Ensure log:trace uses the same compact prefix set as the output.
@@ -10614,13 +10543,101 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
       };
     }
 
+    function prefixesUsedInTokens(tokens, prefEnv) {
+      const used = new Set();
+      const toks = Array.isArray(tokens) ? tokens : [];
+      const prefixes = prefEnv && prefEnv.map ? prefEnv.map : {};
+
+      function maybeAddFromQName(name) {
+        if (typeof name !== 'string') return;
+        if (!name.includes(':')) return;
+        if (name.startsWith('_:')) return; // blank node
+
+        // Split only on the first ':'; the empty prefix is valid for ":foo".
+        const idx = name.indexOf(':');
+        const p = name.slice(0, idx);
+
+        // Ignore strings like "http://..." unless that prefix is actually defined.
+        if (!Object.prototype.hasOwnProperty.call(prefixes, p)) return;
+
+        used.add(p);
+      }
+
+      for (let i = 0; i < toks.length; i++) {
+        const t = toks[i];
+        if (!t) continue;
+
+        // Skip @prefix ... .
+        if (t.typ === 'AtPrefix') {
+          while (i < toks.length && toks[i].typ !== 'Dot' && toks[i].typ !== 'EOF') i++;
+          continue;
+        }
+
+        // Skip @base ... .
+        if (t.typ === 'AtBase') {
+          while (i < toks.length && toks[i].typ !== 'Dot' && toks[i].typ !== 'EOF') i++;
+          continue;
+        }
+
+        // Skip SPARQL/Turtle PREFIX pfx: <iri>
+        if (
+          t.typ === 'Ident' &&
+          typeof t.value === 'string' &&
+          t.value.toLowerCase() === 'prefix' &&
+          toks[i + 1] &&
+          toks[i + 1].typ === 'Ident' &&
+          typeof toks[i + 1].value === 'string' &&
+          toks[i + 1].value.endsWith(':') &&
+          toks[i + 2] &&
+          (toks[i + 2].typ === 'IriRef' || toks[i + 2].typ === 'Ident')
+        ) {
+          i += 2;
+          continue;
+        }
+
+        // Skip SPARQL BASE <iri>
+        if (
+          t.typ === 'Ident' &&
+          typeof t.value === 'string' &&
+          t.value.toLowerCase() === 'base' &&
+          toks[i + 1] &&
+          toks[i + 1].typ === 'IriRef'
+        ) {
+          i += 1;
+          continue;
+        }
+
+        // Count QNames in identifiers, including datatypes like xsd:integer.
+        if (t.typ === 'Ident') maybeAddFromQName(t.value);
+      }
+
+      return used;
+    }
+
     function parseN3Text(text, opts = {}) {
-      const { baseIri = '', label = '<input>' } = opts || {};
+      const { baseIri = '', label = '<input>', keepSourceArtifacts = true, collectUsedPrefixes = false } = opts || {};
       const tokens = lex(text);
       const parser = new Parser(tokens);
       if (baseIri) parser.prefixes.setBase(baseIri);
       const [prefixes, triples, frules, brules, logQueryRules] = parser.parseDocument();
-      return { prefixes, triples, frules, brules, logQueryRules, tokens, text, label };
+
+      const doc = { prefixes, triples, frules, brules, logQueryRules, label };
+
+      if (collectUsedPrefixes) {
+        Object.defineProperty(doc, 'usedPrefixes', {
+          value: prefixesUsedInTokens(tokens, prefixes),
+          enumerable: false,
+          writable: false,
+          configurable: true,
+        });
+      }
+
+      if (keepSourceArtifacts) {
+        doc.tokens = tokens;
+        doc.text = text;
+      }
+
+      return doc;
     }
 
     function sourceBlankPrefix(sourceIndex) {
@@ -10679,16 +10696,27 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
         return out;
       }
 
-      return {
+      const out = {
         prefixes: doc.prefixes,
         triples: (doc.triples || []).map(cloneTriple),
         frules: (doc.frules || []).map(cloneRule),
         brules: (doc.brules || []).map(cloneRule),
         logQueryRules: (doc.logQueryRules || []).map(cloneRule),
-        tokens: doc.tokens,
-        text: doc.text,
         label: doc.label,
       };
+
+      if (doc.usedPrefixes instanceof Set) {
+        Object.defineProperty(out, 'usedPrefixes', {
+          value: new Set(doc.usedPrefixes),
+          enumerable: false,
+          writable: false,
+          configurable: true,
+        });
+      }
+      if (Object.prototype.hasOwnProperty.call(doc, 'tokens')) out.tokens = doc.tokens;
+      if (Object.prototype.hasOwnProperty.call(doc, 'text')) out.text = doc.text;
+
+      return out;
     }
 
     function mergePrefixEnvs(target, source) {
@@ -10707,9 +10735,10 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
     function mergeParsedDocuments(docs, opts = {}) {
       const documents = Array.isArray(docs) ? docs : [];
       const scopeBlankNodes = typeof opts.scopeBlankNodes === 'boolean' ? opts.scopeBlankNodes : documents.length > 1;
+      const keepSources = !!opts.keepSources || !!opts.keepSourceArtifacts;
 
       const merged = emptyParsedDocument();
-      const mergedSources = [];
+      const mergedSources = keepSources ? [] : null;
 
       for (let i = 0; i < documents.length; i++) {
         const originalDoc = documents[i] || emptyParsedDocument();
@@ -10720,15 +10749,30 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
         merged.frules.push(...(doc.frules || []));
         merged.brules.push(...(doc.brules || []));
         merged.logQueryRules.push(...(doc.logQueryRules || []));
-        mergedSources.push(doc);
+
+        if (doc.usedPrefixes instanceof Set) {
+          if (!(merged.usedPrefixes instanceof Set)) {
+            Object.defineProperty(merged, 'usedPrefixes', {
+              value: new Set(),
+              enumerable: false,
+              writable: false,
+              configurable: true,
+            });
+          }
+          for (const pfx of doc.usedPrefixes) merged.usedPrefixes.add(pfx);
+        }
+
+        if (keepSources) mergedSources.push(doc);
       }
 
-      Object.defineProperty(merged, 'sources', {
-        value: mergedSources,
-        enumerable: false,
-        writable: false,
-        configurable: true,
-      });
+      if (keepSources) {
+        Object.defineProperty(merged, 'sources', {
+          value: mergedSources,
+          enumerable: false,
+          writable: false,
+          configurable: true,
+        });
+      }
 
       return merged;
     }
@@ -10760,14 +10804,17 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
       if (!isN3SourceListInput(input)) return null;
       const sources = input.sources.map(normalizeN3SourceItem);
       const defaultBaseIri = typeof opts.baseIri === 'string' ? opts.baseIri : '';
-      const parsed = sources.map((source, index) =>
+      const parsed = sources.map((source) =>
         parseN3Text(source.text, {
           label: source.label,
           baseIri: source.baseIri || (sources.length === 1 ? defaultBaseIri : ''),
+          collectUsedPrefixes: true,
+          keepSourceArtifacts: !!opts.keepSourceArtifacts,
         }),
       );
       return mergeParsedDocuments(parsed, {
         scopeBlankNodes: typeof input.scopeBlankNodes === 'boolean' ? input.scopeBlankNodes : parsed.length > 1,
+        keepSources: !!opts.keepSourceArtifacts,
       });
     }
 
@@ -10776,6 +10823,7 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
       parseN3Text,
       mergeParsedDocuments,
       scopeBlankNodesInDocument,
+      prefixesUsedInTokens,
       isN3SourceListInput,
       parseN3SourceList,
     };
@@ -13272,9 +13320,23 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
 
     'use strict';
 
-    const { Var, Blank, ListTerm, OpenListTerm, GraphTerm, Triple, copyQuotedGraphMetadata } = require('./prelude');
+    const {
+      LOG_NS,
+      Iri,
+      Var,
+      Blank,
+      ListTerm,
+      OpenListTerm,
+      GraphTerm,
+      Triple,
+      copyQuotedGraphMetadata,
+    } = require('./prelude');
 
     function liftBlankRuleVars(premise, conclusion) {
+      function isLogIncludesLikePredicate(p) {
+        return p instanceof Iri && (p.value === LOG_NS + 'includes' || p.value === LOG_NS + 'notIncludes');
+      }
+
       // Map blank labels to stable rule-local variable names.
       // This runs at rule construction time; keep it simple and allocation-light.
       const mapping = Object.create(null);
@@ -13335,9 +13397,19 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
         return t;
       }
 
-      const newPremise = premise.map(
-        (tr) => new Triple(convertTerm(tr.s, true), convertTerm(tr.p, true), convertTerm(tr.o, true)),
-      );
+      const newPremise = premise.map((tr) => {
+        // In log:includes / log:notIncludes, quoted formula operands are formulas
+        // consumed by the builtin rather than ordinary triple patterns. Keep their
+        // local blank nodes as Blank terms so the builtin can treat them as local
+        // existentials, and bindings returned from an explicit scope are blank nodes
+        // instead of synthetic rule variables such as ?_b1.
+        const keepFormulaBlanks = isLogIncludesLikePredicate(tr.p);
+        return new Triple(
+          keepFormulaBlanks && tr.s instanceof GraphTerm ? copyQuotedTerm(tr.s) : convertTerm(tr.s, true),
+          convertTerm(tr.p, true),
+          keepFormulaBlanks && tr.o instanceof GraphTerm ? copyQuotedTerm(tr.o) : convertTerm(tr.o, true),
+        );
+      });
       return [newPremise, conclusion];
     }
 

package/eyeling.js

@@ -5116,6 +5116,8 @@ function main() {
         parseN3Text(text, {
           baseIri: __sourceLabelToBaseIri(sourceLabel),
           label: sourceLabel,
+          collectUsedPrefixes: true,
+          keepSourceArtifacts: false,
         }),
       );
     } catch (e) {
@@ -5133,8 +5135,6 @@ function main() {
   const frules = mergedDocument.frules;
   const brules = mergedDocument.brules;
   const qrules = mergedDocument.logQueryRules;
-  const tokenSets = parsedSources.map((source) => ({ tokens: source.tokens, prefixes: source.prefixes }));
-
   if (showAst) {
     function astReplacer(unusedJsonKey, value) {
       if (value instanceof Set) return Array.from(value);
@@ -5190,75 +5190,6 @@ function main() {
   // In --stream mode we print prefixes *before* any derivations happen.
   // To keep the header small and stable, emit only prefixes that are actually
   // used (as QNames) in the *input* N3 program.
-  function prefixesUsedInInputTokens(toks2, prefEnv) {
-    const used = new Set();
-
-    function maybeAddFromQName(name) {
-      if (typeof name !== 'string') return;
-      if (!name.includes(':')) return;
-      if (name.startsWith('_:')) return; // blank node
-
-      // Split only on the first ':'
-      const idx = name.indexOf(':');
-      const p = name.slice(0, idx); // may be '' for ":foo"
-
-      // Ignore things like "http://..." unless that prefix is actually defined.
-      if (!Object.prototype.hasOwnProperty.call(prefEnv.map, p)) return;
-
-      used.add(p);
-    }
-
-    for (let i = 0; i < toks2.length; i++) {
-      const t = toks2[i];
-
-      // Skip @prefix ... .
-      if (t.typ === 'AtPrefix') {
-        while (i < toks2.length && toks2[i].typ !== 'Dot' && toks2[i].typ !== 'EOF') i++;
-        continue;
-      }
-      // Skip @base ... .
-      if (t.typ === 'AtBase') {
-        while (i < toks2.length && toks2[i].typ !== 'Dot' && toks2[i].typ !== 'EOF') i++;
-        continue;
-      }
-
-      // Skip SPARQL/Turtle PREFIX pfx: <iri>
-      if (
-        t.typ === 'Ident' &&
-        typeof t.value === 'string' &&
-        t.value.toLowerCase() === 'prefix' &&
-        toks2[i + 1] &&
-        toks2[i + 1].typ === 'Ident' &&
-        typeof toks2[i + 1].value === 'string' &&
-        toks2[i + 1].value.endsWith(':') &&
-        toks2[i + 2] &&
-        (toks2[i + 2].typ === 'IriRef' || toks2[i + 2].typ === 'Ident')
-      ) {
-        i += 2;
-        continue;
-      }
-
-      // Skip SPARQL BASE <iri>
-      if (
-        t.typ === 'Ident' &&
-        typeof t.value === 'string' &&
-        t.value.toLowerCase() === 'base' &&
-        toks2[i + 1] &&
-        toks2[i + 1].typ === 'IriRef'
-      ) {
-        i += 1;
-        continue;
-      }
-
-      // Count QNames in identifiers (including datatypes like xsd:integer).
-      if (t.typ === 'Ident') {
-        maybeAddFromQName(t.value);
-      }
-    }
-
-    return used;
-  }
-
   function restrictPrefixEnv(prefEnv, usedSet) {
     const m = {};
     for (const p of usedSet) {
@@ -5276,10 +5207,7 @@ function main() {
   const mayAutoRenderOutputStrings = programMayProduceOutputStrings(triples, frules, qrules);
 
   if (streamMode && !hasQueries && !mayAutoRenderOutputStrings) {
-    const usedInInput = new Set();
-    for (const source of tokenSets) {
-      for (const pfx of prefixesUsedInInputTokens(source.tokens, source.prefixes)) usedInInput.add(pfx);
-    }
+    const usedInInput = mergedDocument.usedPrefixes instanceof Set ? new Set(mergedDocument.usedPrefixes) : new Set();
     const outPrefixes = restrictPrefixEnv(prefixes, usedInInput);
 
     // Ensure log:trace uses the same compact prefix set as the output.
@@ -10581,13 +10509,101 @@ function emptyParsedDocument() {
   };
 }
 
+function prefixesUsedInTokens(tokens, prefEnv) {
+  const used = new Set();
+  const toks = Array.isArray(tokens) ? tokens : [];
+  const prefixes = prefEnv && prefEnv.map ? prefEnv.map : {};
+
+  function maybeAddFromQName(name) {
+    if (typeof name !== 'string') return;
+    if (!name.includes(':')) return;
+    if (name.startsWith('_:')) return; // blank node
+
+    // Split only on the first ':'; the empty prefix is valid for ":foo".
+    const idx = name.indexOf(':');
+    const p = name.slice(0, idx);
+
+    // Ignore strings like "http://..." unless that prefix is actually defined.
+    if (!Object.prototype.hasOwnProperty.call(prefixes, p)) return;
+
+    used.add(p);
+  }
+
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    if (!t) continue;
+
+    // Skip @prefix ... .
+    if (t.typ === 'AtPrefix') {
+      while (i < toks.length && toks[i].typ !== 'Dot' && toks[i].typ !== 'EOF') i++;
+      continue;
+    }
+
+    // Skip @base ... .
+    if (t.typ === 'AtBase') {
+      while (i < toks.length && toks[i].typ !== 'Dot' && toks[i].typ !== 'EOF') i++;
+      continue;
+    }
+
+    // Skip SPARQL/Turtle PREFIX pfx: <iri>
+    if (
+      t.typ === 'Ident' &&
+      typeof t.value === 'string' &&
+      t.value.toLowerCase() === 'prefix' &&
+      toks[i + 1] &&
+      toks[i + 1].typ === 'Ident' &&
+      typeof toks[i + 1].value === 'string' &&
+      toks[i + 1].value.endsWith(':') &&
+      toks[i + 2] &&
+      (toks[i + 2].typ === 'IriRef' || toks[i + 2].typ === 'Ident')
+    ) {
+      i += 2;
+      continue;
+    }
+
+    // Skip SPARQL BASE <iri>
+    if (
+      t.typ === 'Ident' &&
+      typeof t.value === 'string' &&
+      t.value.toLowerCase() === 'base' &&
+      toks[i + 1] &&
+      toks[i + 1].typ === 'IriRef'
+    ) {
+      i += 1;
+      continue;
+    }
+
+    // Count QNames in identifiers, including datatypes like xsd:integer.
+    if (t.typ === 'Ident') maybeAddFromQName(t.value);
+  }
+
+  return used;
+}
+
 function parseN3Text(text, opts = {}) {
-  const { baseIri = '', label = '<input>' } = opts || {};
+  const { baseIri = '', label = '<input>', keepSourceArtifacts = true, collectUsedPrefixes = false } = opts || {};
   const tokens = lex(text);
   const parser = new Parser(tokens);
   if (baseIri) parser.prefixes.setBase(baseIri);
   const [prefixes, triples, frules, brules, logQueryRules] = parser.parseDocument();
-  return { prefixes, triples, frules, brules, logQueryRules, tokens, text, label };
+
+  const doc = { prefixes, triples, frules, brules, logQueryRules, label };
+
+  if (collectUsedPrefixes) {
+    Object.defineProperty(doc, 'usedPrefixes', {
+      value: prefixesUsedInTokens(tokens, prefixes),
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  }
+
+  if (keepSourceArtifacts) {
+    doc.tokens = tokens;
+    doc.text = text;
+  }
+
+  return doc;
 }
 
 function sourceBlankPrefix(sourceIndex) {
@@ -10646,16 +10662,27 @@ function scopeBlankNodesInDocument(doc, sourceIndex) {
     return out;
   }
 
-  return {
+  const out = {
     prefixes: doc.prefixes,
     triples: (doc.triples || []).map(cloneTriple),
     frules: (doc.frules || []).map(cloneRule),
     brules: (doc.brules || []).map(cloneRule),
     logQueryRules: (doc.logQueryRules || []).map(cloneRule),
-    tokens: doc.tokens,
-    text: doc.text,
     label: doc.label,
   };
+
+  if (doc.usedPrefixes instanceof Set) {
+    Object.defineProperty(out, 'usedPrefixes', {
+      value: new Set(doc.usedPrefixes),
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  }
+  if (Object.prototype.hasOwnProperty.call(doc, 'tokens')) out.tokens = doc.tokens;
+  if (Object.prototype.hasOwnProperty.call(doc, 'text')) out.text = doc.text;
+
+  return out;
 }
 
 function mergePrefixEnvs(target, source) {
@@ -10673,11 +10700,11 @@ function mergePrefixEnvs(target, source) {
 
 function mergeParsedDocuments(docs, opts = {}) {
   const documents = Array.isArray(docs) ? docs : [];
-  const scopeBlankNodes =
-    typeof opts.scopeBlankNodes === 'boolean' ? opts.scopeBlankNodes : documents.length > 1;
+  const scopeBlankNodes = typeof opts.scopeBlankNodes === 'boolean' ? opts.scopeBlankNodes : documents.length > 1;
+  const keepSources = !!opts.keepSources || !!opts.keepSourceArtifacts;
 
   const merged = emptyParsedDocument();
-  const mergedSources = [];
+  const mergedSources = keepSources ? [] : null;
 
   for (let i = 0; i < documents.length; i++) {
     const originalDoc = documents[i] || emptyParsedDocument();
@@ -10688,26 +10715,36 @@ function mergeParsedDocuments(docs, opts = {}) {
     merged.frules.push(...(doc.frules || []));
     merged.brules.push(...(doc.brules || []));
     merged.logQueryRules.push(...(doc.logQueryRules || []));
-    mergedSources.push(doc);
+
+    if (doc.usedPrefixes instanceof Set) {
+      if (!(merged.usedPrefixes instanceof Set)) {
+        Object.defineProperty(merged, 'usedPrefixes', {
+          value: new Set(),
+          enumerable: false,
+          writable: false,
+          configurable: true,
+        });
+      }
+      for (const pfx of doc.usedPrefixes) merged.usedPrefixes.add(pfx);
+    }
+
+    if (keepSources) mergedSources.push(doc);
   }
 
-  Object.defineProperty(merged, 'sources', {
-    value: mergedSources,
-    enumerable: false,
-    writable: false,
-    configurable: true,
-  });
+  if (keepSources) {
+    Object.defineProperty(merged, 'sources', {
+      value: mergedSources,
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  }
 
   return merged;
 }
 
 function isN3SourceListInput(input) {
-  return !!(
-    input &&
-    typeof input === 'object' &&
-    !Array.isArray(input) &&
-    Array.isArray(input.sources)
-  );
+  return !!(input && typeof input === 'object' && !Array.isArray(input) && Array.isArray(input.sources));
 }
 
 function normalizeN3SourceItem(source, index) {
@@ -10733,14 +10770,17 @@ function parseN3SourceList(input, opts = {}) {
   if (!isN3SourceListInput(input)) return null;
   const sources = input.sources.map(normalizeN3SourceItem);
   const defaultBaseIri = typeof opts.baseIri === 'string' ? opts.baseIri : '';
-  const parsed = sources.map((source, index) =>
+  const parsed = sources.map(source =>
     parseN3Text(source.text, {
       label: source.label,
       baseIri: source.baseIri || (sources.length === 1 ? defaultBaseIri : ''),
+      collectUsedPrefixes: true,
+      keepSourceArtifacts: !!opts.keepSourceArtifacts,
     }),
   );
   return mergeParsedDocuments(parsed, {
     scopeBlankNodes: typeof input.scopeBlankNodes === 'boolean' ? input.scopeBlankNodes : parsed.length > 1,
+    keepSources: !!opts.keepSourceArtifacts,
   });
 }
 
@@ -10749,6 +10789,7 @@ module.exports = {
   parseN3Text,
   mergeParsedDocuments,
   scopeBlankNodesInDocument,
+  prefixesUsedInTokens,
   isN3SourceListInput,
   parseN3SourceList,
 };
@@ -13237,9 +13278,23 @@ module.exports = {
 
 'use strict';
 
-const { Var, Blank, ListTerm, OpenListTerm, GraphTerm, Triple, copyQuotedGraphMetadata } = require('./prelude');
+const {
+  LOG_NS,
+  Iri,
+  Var,
+  Blank,
+  ListTerm,
+  OpenListTerm,
+  GraphTerm,
+  Triple,
+  copyQuotedGraphMetadata,
+} = require('./prelude');
 
 function liftBlankRuleVars(premise, conclusion) {
+  function isLogIncludesLikePredicate(p) {
+    return p instanceof Iri && (p.value === LOG_NS + 'includes' || p.value === LOG_NS + 'notIncludes');
+  }
+
   // Map blank labels to stable rule-local variable names.
   // This runs at rule construction time; keep it simple and allocation-light.
   const mapping = Object.create(null);
@@ -13296,9 +13351,19 @@ function liftBlankRuleVars(premise, conclusion) {
     return t;
   }
 
-  const newPremise = premise.map(
-    (tr) => new Triple(convertTerm(tr.s, true), convertTerm(tr.p, true), convertTerm(tr.o, true)),
-  );
+  const newPremise = premise.map((tr) => {
+    // In log:includes / log:notIncludes, quoted formula operands are formulas
+    // consumed by the builtin rather than ordinary triple patterns. Keep their
+    // local blank nodes as Blank terms so the builtin can treat them as local
+    // existentials, and bindings returned from an explicit scope are blank nodes
+    // instead of synthetic rule variables such as ?_b1.
+    const keepFormulaBlanks = isLogIncludesLikePredicate(tr.p);
+    return new Triple(
+      keepFormulaBlanks && tr.s instanceof GraphTerm ? copyQuotedTerm(tr.s) : convertTerm(tr.s, true),
+      convertTerm(tr.p, true),
+      keepFormulaBlanks && tr.o instanceof GraphTerm ? copyQuotedTerm(tr.o) : convertTerm(tr.o, true),
+    );
+  });
   return [newPremise, conclusion];
 }
 

package/lib/cli.js

@@ -208,6 +208,8 @@ function main() {
         parseN3Text(text, {
           baseIri: __sourceLabelToBaseIri(sourceLabel),
           label: sourceLabel,
+          collectUsedPrefixes: true,
+          keepSourceArtifacts: false,
         }),
       );
     } catch (e) {
@@ -225,8 +227,6 @@ function main() {
   const frules = mergedDocument.frules;
   const brules = mergedDocument.brules;
   const qrules = mergedDocument.logQueryRules;
-  const tokenSets = parsedSources.map((source) => ({ tokens: source.tokens, prefixes: source.prefixes }));
-
   if (showAst) {
     function astReplacer(unusedJsonKey, value) {
       if (value instanceof Set) return Array.from(value);
@@ -282,75 +282,6 @@ function main() {
   // In --stream mode we print prefixes *before* any derivations happen.
   // To keep the header small and stable, emit only prefixes that are actually
   // used (as QNames) in the *input* N3 program.
-  function prefixesUsedInInputTokens(toks2, prefEnv) {
-    const used = new Set();
-
-    function maybeAddFromQName(name) {
-      if (typeof name !== 'string') return;
-      if (!name.includes(':')) return;
-      if (name.startsWith('_:')) return; // blank node
-
-      // Split only on the first ':'
-      const idx = name.indexOf(':');
-      const p = name.slice(0, idx); // may be '' for ":foo"
-
-      // Ignore things like "http://..." unless that prefix is actually defined.
-      if (!Object.prototype.hasOwnProperty.call(prefEnv.map, p)) return;
-
-      used.add(p);
-    }
-
-    for (let i = 0; i < toks2.length; i++) {
-      const t = toks2[i];
-
-      // Skip @prefix ... .
-      if (t.typ === 'AtPrefix') {
-        while (i < toks2.length && toks2[i].typ !== 'Dot' && toks2[i].typ !== 'EOF') i++;
-        continue;
-      }
-      // Skip @base ... .
-      if (t.typ === 'AtBase') {
-        while (i < toks2.length && toks2[i].typ !== 'Dot' && toks2[i].typ !== 'EOF') i++;
-        continue;
-      }
-
-      // Skip SPARQL/Turtle PREFIX pfx: <iri>
-      if (
-        t.typ === 'Ident' &&
-        typeof t.value === 'string' &&
-        t.value.toLowerCase() === 'prefix' &&
-        toks2[i + 1] &&
-        toks2[i + 1].typ === 'Ident' &&
-        typeof toks2[i + 1].value === 'string' &&
-        toks2[i + 1].value.endsWith(':') &&
-        toks2[i + 2] &&
-        (toks2[i + 2].typ === 'IriRef' || toks2[i + 2].typ === 'Ident')
-      ) {
-        i += 2;
-        continue;
-      }
-
-      // Skip SPARQL BASE <iri>
-      if (
-        t.typ === 'Ident' &&
-        typeof t.value === 'string' &&
-        t.value.toLowerCase() === 'base' &&
-        toks2[i + 1] &&
-        toks2[i + 1].typ === 'IriRef'
-      ) {
-        i += 1;
-        continue;
-      }
-
-      // Count QNames in identifiers (including datatypes like xsd:integer).
-      if (t.typ === 'Ident') {
-        maybeAddFromQName(t.value);
-      }
-    }
-
-    return used;
-  }
-
   function restrictPrefixEnv(prefEnv, usedSet) {
     const m = {};
     for (const p of usedSet) {
@@ -368,10 +299,7 @@ function main() {
   const mayAutoRenderOutputStrings = programMayProduceOutputStrings(triples, frules, qrules);
 
   if (streamMode && !hasQueries && !mayAutoRenderOutputStrings) {
-    const usedInInput = new Set();
-    for (const source of tokenSets) {
-      for (const pfx of prefixesUsedInInputTokens(source.tokens, source.prefixes)) usedInInput.add(pfx);
-    }
+    const usedInInput = mergedDocument.usedPrefixes instanceof Set ? new Set(mergedDocument.usedPrefixes) : new Set();
     const outPrefixes = restrictPrefixEnv(prefixes, usedInInput);
 
     // Ensure log:trace uses the same compact prefix set as the output.

package/lib/multisource.js

@@ -31,13 +31,101 @@ function emptyParsedDocument() {
   };
 }
 
+function prefixesUsedInTokens(tokens, prefEnv) {
+  const used = new Set();
+  const toks = Array.isArray(tokens) ? tokens : [];
+  const prefixes = prefEnv && prefEnv.map ? prefEnv.map : {};
+
+  function maybeAddFromQName(name) {
+    if (typeof name !== 'string') return;
+    if (!name.includes(':')) return;
+    if (name.startsWith('_:')) return; // blank node
+
+    // Split only on the first ':'; the empty prefix is valid for ":foo".
+    const idx = name.indexOf(':');
+    const p = name.slice(0, idx);
+
+    // Ignore strings like "http://..." unless that prefix is actually defined.
+    if (!Object.prototype.hasOwnProperty.call(prefixes, p)) return;
+
+    used.add(p);
+  }
+
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    if (!t) continue;
+
+    // Skip @prefix ... .
+    if (t.typ === 'AtPrefix') {
+      while (i < toks.length && toks[i].typ !== 'Dot' && toks[i].typ !== 'EOF') i++;
+      continue;
+    }
+
+    // Skip @base ... .
+    if (t.typ === 'AtBase') {
+      while (i < toks.length && toks[i].typ !== 'Dot' && toks[i].typ !== 'EOF') i++;
+      continue;
+    }
+
+    // Skip SPARQL/Turtle PREFIX pfx: <iri>
+    if (
+      t.typ === 'Ident' &&
+      typeof t.value === 'string' &&
+      t.value.toLowerCase() === 'prefix' &&
+      toks[i + 1] &&
+      toks[i + 1].typ === 'Ident' &&
+      typeof toks[i + 1].value === 'string' &&
+      toks[i + 1].value.endsWith(':') &&
+      toks[i + 2] &&
+      (toks[i + 2].typ === 'IriRef' || toks[i + 2].typ === 'Ident')
+    ) {
+      i += 2;
+      continue;
+    }
+
+    // Skip SPARQL BASE <iri>
+    if (
+      t.typ === 'Ident' &&
+      typeof t.value === 'string' &&
+      t.value.toLowerCase() === 'base' &&
+      toks[i + 1] &&
+      toks[i + 1].typ === 'IriRef'
+    ) {
+      i += 1;
+      continue;
+    }
+
+    // Count QNames in identifiers, including datatypes like xsd:integer.
+    if (t.typ === 'Ident') maybeAddFromQName(t.value);
+  }
+
+  return used;
+}
+
 function parseN3Text(text, opts = {}) {
-  const { baseIri = '', label = '<input>' } = opts || {};
+  const { baseIri = '', label = '<input>', keepSourceArtifacts = true, collectUsedPrefixes = false } = opts || {};
   const tokens = lex(text);
   const parser = new Parser(tokens);
   if (baseIri) parser.prefixes.setBase(baseIri);
   const [prefixes, triples, frules, brules, logQueryRules] = parser.parseDocument();
-  return { prefixes, triples, frules, brules, logQueryRules, tokens, text, label };
+
+  const doc = { prefixes, triples, frules, brules, logQueryRules, label };
+
+  if (collectUsedPrefixes) {
+    Object.defineProperty(doc, 'usedPrefixes', {
+      value: prefixesUsedInTokens(tokens, prefixes),
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  }
+
+  if (keepSourceArtifacts) {
+    doc.tokens = tokens;
+    doc.text = text;
+  }
+
+  return doc;
 }
 
 function sourceBlankPrefix(sourceIndex) {
@@ -96,16 +184,27 @@ function scopeBlankNodesInDocument(doc, sourceIndex) {
     return out;
   }
 
-  return {
+  const out = {
     prefixes: doc.prefixes,
     triples: (doc.triples || []).map(cloneTriple),
     frules: (doc.frules || []).map(cloneRule),
     brules: (doc.brules || []).map(cloneRule),
     logQueryRules: (doc.logQueryRules || []).map(cloneRule),
-    tokens: doc.tokens,
-    text: doc.text,
     label: doc.label,
   };
+
+  if (doc.usedPrefixes instanceof Set) {
+    Object.defineProperty(out, 'usedPrefixes', {
+      value: new Set(doc.usedPrefixes),
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  }
+  if (Object.prototype.hasOwnProperty.call(doc, 'tokens')) out.tokens = doc.tokens;
+  if (Object.prototype.hasOwnProperty.call(doc, 'text')) out.text = doc.text;
+
+  return out;
 }
 
 function mergePrefixEnvs(target, source) {
@@ -124,9 +223,10 @@ function mergePrefixEnvs(target, source) {
 function mergeParsedDocuments(docs, opts = {}) {
   const documents = Array.isArray(docs) ? docs : [];
   const scopeBlankNodes = typeof opts.scopeBlankNodes === 'boolean' ? opts.scopeBlankNodes : documents.length > 1;
+  const keepSources = !!opts.keepSources || !!opts.keepSourceArtifacts;
 
   const merged = emptyParsedDocument();
-  const mergedSources = [];
+  const mergedSources = keepSources ? [] : null;
 
   for (let i = 0; i < documents.length; i++) {
     const originalDoc = documents[i] || emptyParsedDocument();
@@ -137,15 +237,30 @@ function mergeParsedDocuments(docs, opts = {}) {
     merged.frules.push(...(doc.frules || []));
     merged.brules.push(...(doc.brules || []));
     merged.logQueryRules.push(...(doc.logQueryRules || []));
-    mergedSources.push(doc);
+
+    if (doc.usedPrefixes instanceof Set) {
+      if (!(merged.usedPrefixes instanceof Set)) {
+        Object.defineProperty(merged, 'usedPrefixes', {
+          value: new Set(),
+          enumerable: false,
+          writable: false,
+          configurable: true,
+        });
+      }
+      for (const pfx of doc.usedPrefixes) merged.usedPrefixes.add(pfx);
+    }
+
+    if (keepSources) mergedSources.push(doc);
   }
 
-  Object.defineProperty(merged, 'sources', {
-    value: mergedSources,
-    enumerable: false,
-    writable: false,
-    configurable: true,
-  });
+  if (keepSources) {
+    Object.defineProperty(merged, 'sources', {
+      value: mergedSources,
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  }
 
   return merged;
 }
@@ -177,14 +292,17 @@ function parseN3SourceList(input, opts = {}) {
   if (!isN3SourceListInput(input)) return null;
   const sources = input.sources.map(normalizeN3SourceItem);
   const defaultBaseIri = typeof opts.baseIri === 'string' ? opts.baseIri : '';
-  const parsed = sources.map((source, index) =>
+  const parsed = sources.map((source) =>
     parseN3Text(source.text, {
       label: source.label,
       baseIri: source.baseIri || (sources.length === 1 ? defaultBaseIri : ''),
+      collectUsedPrefixes: true,
+      keepSourceArtifacts: !!opts.keepSourceArtifacts,
     }),
   );
   return mergeParsedDocuments(parsed, {
     scopeBlankNodes: typeof input.scopeBlankNodes === 'boolean' ? input.scopeBlankNodes : parsed.length > 1,
+    keepSources: !!opts.keepSourceArtifacts,
   });
 }
 
@@ -193,6 +311,7 @@ module.exports = {
   parseN3Text,
   mergeParsedDocuments,
   scopeBlankNodesInDocument,
+  prefixesUsedInTokens,
   isN3SourceListInput,
   parseN3SourceList,
 };

package/lib/rules.js

@@ -7,9 +7,23 @@
 
 'use strict';
 
-const { Var, Blank, ListTerm, OpenListTerm, GraphTerm, Triple, copyQuotedGraphMetadata } = require('./prelude');
+const {
+  LOG_NS,
+  Iri,
+  Var,
+  Blank,
+  ListTerm,
+  OpenListTerm,
+  GraphTerm,
+  Triple,
+  copyQuotedGraphMetadata,
+} = require('./prelude');
 
 function liftBlankRuleVars(premise, conclusion) {
+  function isLogIncludesLikePredicate(p) {
+    return p instanceof Iri && (p.value === LOG_NS + 'includes' || p.value === LOG_NS + 'notIncludes');
+  }
+
   // Map blank labels to stable rule-local variable names.
   // This runs at rule construction time; keep it simple and allocation-light.
   const mapping = Object.create(null);
@@ -66,9 +80,19 @@ function liftBlankRuleVars(premise, conclusion) {
     return t;
   }
 
-  const newPremise = premise.map(
-    (tr) => new Triple(convertTerm(tr.s, true), convertTerm(tr.p, true), convertTerm(tr.o, true)),
-  );
+  const newPremise = premise.map((tr) => {
+    // In log:includes / log:notIncludes, quoted formula operands are formulas
+    // consumed by the builtin rather than ordinary triple patterns. Keep their
+    // local blank nodes as Blank terms so the builtin can treat them as local
+    // existentials, and bindings returned from an explicit scope are blank nodes
+    // instead of synthetic rule variables such as ?_b1.
+    const keepFormulaBlanks = isLogIncludesLikePredicate(tr.p);
+    return new Triple(
+      keepFormulaBlanks && tr.s instanceof GraphTerm ? copyQuotedTerm(tr.s) : convertTerm(tr.s, true),
+      convertTerm(tr.p, true),
+      keepFormulaBlanks && tr.o instanceof GraphTerm ? copyQuotedTerm(tr.o) : convertTerm(tr.o, true),
+    );
+  });
   return [newPremise, conclusion];
 }
 

package/package.json

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

package/test/api.test.js

@@ -1643,6 +1643,30 @@ _:x :hates { _:foo :making :mess }.
     expect: [/:(?:test)\s+:(?:contains)\s+:(?:success-literal-3)\s*\./, /:(?:test)\s+:(?:is)\s+true\s*\./],
   },
 
+  {
+    name: '60a regression: log:includes explicit-scope blank node is returned as blank, not synthetic variable',
+    opt: { proofComments: false },
+    input: `@prefix : <http://example.org/ns#> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+
+{
+  {
+    _:b1 a :Mortal .
+  } log:includes {
+    ?CS ?CP ?CO .
+  } .
+}
+=>
+{
+  _:b2 :conclusion {
+    ?CS ?CP ?CO .
+  } .
+} .
+`,
+    expect: [/_:sk_\d+\s+:(?:conclusion)\s+\{\s*_:b\d+\s+a\s+:(?:Mortal)\s*\.\s*\}\s*\./s],
+    notExpect: [/\?_b\d+\s+a\s+:(?:Mortal)/],
+  },
+
   {
     name: '61 RDF/JS input + rule objects: reason() accepts quads with rules',
     run() {