eyeling 1.22.16 → 1.23.0

package/HANDBOOK.md

@@ -27,7 +27,7 @@
 - [Epilogue](#epilogue)
 - [Appendix A — Eyeling user notes](#app-a)
 - [Appendix B — Notation3: when facts can carry their own logic](#app-b)
-- [Appendix C — N3 beyond Prolog: logic that survives the open web](#app-c)
+- [Appendix C — Why N3 fits the Eyeling examples](#app-c)
 - [Appendix D — LLM + Eyeling: A Repeatable Logic Toolchain](#app-d)
 - [Appendix E — How Eyeling reaches 100% on `notation3tests`](#app-e)
 - [Appendix F — The ARC approach: Answer • Reason Why • Check](#app-f)
@@ -1871,7 +1871,7 @@ echo '@prefix : <http://example.org/> .
 { ?x a :Man } => { ?x a :Mortal } .' | npx eyeling
 ```
 
-You can also pass a file path, or `-` to read explicitly from stdin.
+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.
 
 Show the available options:
 
@@ -1895,7 +1895,7 @@ npx eyeling --builtin lib/builtin-sudoku.js examples/sudoku.n3
 
 The bundle contains the whole engine. The CLI path is the “canonical behavior”:
 
-- parse input file
+- parse one or more input sources; with multiple sources, parse each source independently and merge the ASTs
 - reason to closure
 - print derived triples, or render `log:outputString` strings when present
 - optional proof comments
@@ -1916,6 +1916,7 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 - `-h`, `--help` — show usage.
 - With no positional argument, Eyeling reads from stdin when input is piped.
 - Use `-` as the input path to read explicitly from stdin.
+- Multiple positional inputs are allowed, for example `eyeling facts.n3 rules.n3`; rules from any input can match facts from any other input after the merge.
 
 ### 14.3 Package entrypoint split for Node, browser, and CLI
 
@@ -2024,13 +2025,34 @@ Notes:
 
 #### 14.4.2 RDF-JS and Eyeling rule-object interoperability
 
-The JavaScript APIs accept three input styles:
+The JavaScript APIs accept four input styles:
 
 1. plain N3 text
-2. RDF/JS fact input (`quads`, `facts`, or `dataset`)
-3. Eyeling rule objects or full AST bundles
+2. a multi-source N3 object (`{ sources: [...] }`)
+3. RDF/JS fact input (`quads`, `facts`, or `dataset`)
+4. Eyeling rule objects or full AST bundles
 
-If you want to use N3 source text, pass the whole input as a plain string.
+If you want to use one N3 source text, pass the whole input as a plain string. If you want to avoid concatenating several N3 sources into one large string, pass them as a source list instead.
+
+For example:
+
+```js
+const { reason } = require('eyeling');
+
+const out = reason(
+  { proofComments: false },
+  {
+    sources: [
+      '@prefix : <http://example.org/> .\n:Socrates a :Man .\n',
+      '@prefix : <http://example.org/> .\n{ ?x a :Man } => { ?x a :Mortal } .\n',
+    ],
+  },
+);
+
+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 RDF/JS facts, the graph must be the default graph. Named-graph quads are rejected.
 
@@ -2467,6 +2489,12 @@ The authoritative list is always:
 eyeling --help
 ```
 
+Usage:
+
+```bash
+eyeling [options] [file-or-url.n3|- ...]
+```
+
 Options:
 
 ```
@@ -2481,6 +2509,8 @@ Options:
   -v, --version                Print version and exit.
 ```
 
+Input note: with multiple positional inputs, Eyeling reads and parses each source separately, then merges facts, forward rules, backward rules, and `log:query` directives before reasoning. Blank node labels are scoped per input document.
+
 Note: when `log:query` directives are present, or when the program may produce `log:outputString` facts, Eyeling cannot stream its final user-facing output from partial derivations, so `--stream` has no effect in those cases. In the latter case Eyeling saturates first and then renders the collected output strings.
 
 See also:
@@ -2631,23 +2661,69 @@ In that sense, N3 is less a bid to make the web “smarter” than a bid to make
 
 <a id="app-c"></a>
 
-## Appendix C — N3 beyond Prolog: logic that survives the open web
+## Appendix C — Why N3 fits the Eyeling examples
+
+The Eyeling examples combine several things at once. They contain facts about a situation, rules that derive new facts, checks that make the result testable, and an answer that can be shown to a human. That combination matters. It means that Eyeling is not only a data exercise and not only a logic exercise. It needs a notation in which data and rules can remain together.
+
+This raises a practical question: which language fits these examples best?
+
+SQL is a natural candidate when the main task is storing data and querying it. Prolog is a natural candidate when the main task is writing rules and deriving consequences from facts. N3 is interesting because it tries to keep those two sides together. The point of this appendix is not to rank SQL, Prolog, and N3 in general. The point is to explain why N3 works especially well for Eyeling-style examples.
+
+### What the examples need
+
+A typical Eyeling example is not just a small dataset. It is also not just a set of inference rules. It is a compact artifact in which several layers belong together.
+
+There is usually a description of a situation: products, airports, organisms, policies, signatures, dates, or other entities. There are rules that derive new facts from those inputs. There are explicit checks that say whether the intended conclusions hold. And there is often a final answer or explanation that is part of the example itself.
+
+This is the real design problem. If the language handles only one of these layers well, then the example has to be split up. The data ends up in one notation, the rules in another, the checks somewhere else, and the final answer in yet another place. Once that happens, the example becomes harder to read and harder to maintain.
+
+### What SQL contributes
+
+SQL is strong when the main task is structured data and queries over that data. It is excellent for tables, filtering, aggregation, joins, and efficient execution. When an Eyeling example is translated into DuckDB, SQL can do a surprising amount. Recursive queries can express route search. Views can express derived facts. Checks can be written as boolean queries. Output can be assembled from query results.
+
+That is useful, and it shows that the examples can be operationalized in a relational setting.
+
+However, SQL is not the original shape of these examples. To get there, the graph-like source has to be mapped into tables, and the rule logic has to be reconstructed with joins, common table expressions, macros, and views. The result can work well, but the conceptual structure becomes more indirect. Data and reasoning are still connected, but they are no longer expressed in the same native form.
+
+In other words, SQL is a good execution target, but it is not always the clearest authoring language for this kind of material.
+
+### What Prolog contributes
+
+Prolog is strong when the main task is expressing facts and rules directly. An Eyeling example often looks much closer to Prolog than to SQL once the focus shifts to derivation. Facts become predicates. Rules become clauses. Recursive reasoning becomes natural. This makes Prolog a very good target when the aim is to express the logical behavior of an example clearly.
+
+That is why Prolog translations of Eyeling examples often feel much cleaner than SQL translations. The rule layer fits naturally.
+
+However, Prolog is not primarily a graph data notation. Eyeling examples often use a linked-data style in which named entities and relations remain visible as part of the knowledge representation. In Prolog this can certainly be modeled, but it is usually represented as application-specific predicates rather than as a graph-native notation. That means the rule side is natural, while the original data style becomes less central.
+
+So Prolog captures the inference well, but it does not preserve the same linked-data feel as naturally as N3 does.
+
+### Why N3 fits these examples well
+
+N3 fits Eyeling well because it keeps the data model and the rule model close together.
+
+The facts remain graph-shaped. Entities and relations can be written directly. Rules can be added in the same notation. Checks can be expressed next to the derivations they depend on. Even the final answer can remain part of the same artifact. This allows an example to stay compact from beginning to end.
+
+That compactness is important. It means the reader can inspect one example and see the situation, the derivation, the checks, and the answer without mentally switching between several different layers of representation.
+
+This is the main reason N3 feels like a sweet spot in Eyeling. Compared with SQL, it avoids the split between graph-shaped knowledge and relational encoding. Compared with Prolog, it avoids the split between logic programming and linked-data representation. It keeps both sides close enough that the whole example can stay in one place.
+
+### Where this matters in practice
 
-Notation3 and Prolog resemble each other at first glance. Both use variables, unification, and implication-shaped rules. Both can be used to derive consequences from a set of premises. But they were shaped for different native environments. Prolog was designed around executing logic programs. N3 was designed around expressing logic in the same world as RDF: a world of IRIs, triples, graphs, linked documents, and shared vocabularies. That difference in native setting gives N3 a wider built-in reach for web-scale knowledge work.
+This matters most in examples where the structure of the knowledge is part of the point.
 
-The first difference is the data model. In Prolog, the basic units are terms and clauses. In N3, the basic units are RDF-style triples and graphs, extended with variables, lists, graph terms, and logical implication. N3 is explicitly defined as an extension of RDF, not as a separate programming language that merely happens to manipulate graphs. That means identifiers, data, and inferred results all live in one interoperable form. A rule consumes graph patterns and produces graph patterns, so the output of reasoning can be published, merged, quoted, exchanged, and reasoned over again without changing representation.
+In the path-discovery example, the facts describe airports and routes, and the rule describes how a connection can be found through a bounded number of stopovers. In SQL, this becomes a recursive query over tables. In Prolog, it becomes a recursive predicate over facts. In N3, the graph and the rule remain in one notation.
 
-The second difference is more profound: N3 can treat graphs as first-class terms. A graph term is a quoted graph. It can appear in subject, predicate, or object position, and it does not automatically assert its contents as true. It is a resource in its own right. This makes it natural to represent claims, reports, beliefs, policies, source snapshots, and provenance. One can say not only “this is true,” but also “this document says this,” “this authority concludes that,” or “this rule applies to that quoted context.” In other words, N3 can reason about statements as statements, not only about the world those statements describe.
+In the barley-seed-becoming example, the facts describe stages, transitions, and constraints, and the rules determine what can and cannot become something else. In SQL and Prolog, this can be translated, but N3 preserves the original structure more directly.
 
-That leads directly to a third advantage: scope is part of the logic. In N3, implicit universal quantification is global, while implicit existential quantification is local to the graph in which it occurs. Once graphs can be nested and quoted, that distinction matters. It allows a reasoner to keep track of what is asserted here, what is asserted inside a quoted subgraph, and what variables belong to which level. This gives N3 a native way to express context-sensitive reasoning that would feel external or encoded-by-convention in classic Prolog.
+In the delfour example, the same pattern becomes even clearer. The example combines facts about products and household needs, rules about authorization and recommendation, checks over the derived conclusions, and a final human-readable answer. That kind of example is exactly where a language that keeps data, rules, checks, and answers together becomes valuable.
 
-A fourth difference is that N3 connects logic to the web inside the language itself. The N3 vocabulary includes `log:semantics` and `log:conclusion` for retrieving and reasoning over local or online sources. It also includes scoped operators such as `log:forAllIn` and `log:notIncludes`, which support scoped universal reasoning and scoped negation-as-failure over a chosen graph or document. So web retrieval, source-bounded reasoning, and reasoning over quoted content are not afterthoughts. They are part of the logic vocabulary. This is one of the clearest senses in which N3 has greater inherent potential: it is not only a language for deriving consequences from facts, but a language for locating, quoting, constraining, and comparing the sources of those facts.
+### Conclusion
 
-By contrast, classic Prolog is centered on a proof procedure over definite clauses. In the usual operational reading, Prolog applies a restricted form of SLD-resolution, chooses the leftmost goal, tries clauses top-to-bottom, and searches depth-first. Traditional negation is negation-as-failure, described in the SWI-Prolog glossary as a weak negation. This makes Prolog extremely effective as an executable logic language, but it also means that much of its practical power comes from the operational behavior of the engine, not from a web-native knowledge model.
+N3 is not the best language for every task. SQL is stronger as a database query language. Prolog is stronger as a pure rule language. But the Eyeling examples are not only database exercises and not only rule exercises.
 
-This does not make Prolog inferior. Modern Prolog systems add important capabilities beyond the classic core, including tabling, which improves termination behavior and can make Prolog behave more like a bottom-up theorem prover for some classes of problems. But that actually sharpens the comparison: when Prolog needs to work more comfortably in graph-heavy or knowledge-integration settings, it typically gains that power through extensions, libraries, or host-environment choices. N3 starts there. Graphs, quoted formulas, scoped reasoning, and web-connected semantics are part of its native conceptual center.
+They are compact knowledge artifacts in which facts, rules, checks, and answers belong together.
 
-So the strongest claim is not that N3 replaces Prolog in every domain. The stronger and more precise claim is this: Prolog is a very strong language for executing logic programs, while N3 has greater inherent potential as a language for publishable, linkable, inspectable, and source-aware logic on the open web. It lets facts, rules, quoted claims, retrieved documents, and derived conclusions all live in one semantic space. For a system like Eyeling, that is not a cosmetic difference. It is the reason the language can scale from local inference to web-shaped reasoning without changing its basic form.
+That is why N3 fits them so well. It is not because N3 wins an abstract language competition. It is because these examples need a form in which data and reasoning can remain unified. For Eyeling, that is exactly what N3 provides.
 
 ---
 
@@ -3686,7 +3762,7 @@ Taken together, these positions support a straightforward attitude toward Eyelin
 
 ## Appendix K — Whitehead-inspired becoming examples
 
-A small family of examples in the repository explores a common idea: that logic can describe not only what **is** the case, but what a thing, system, lineage, or device can **become**. The inspiration is Whiteheadian in a broad sense. The examples do not attempt to formalize Whitehead’s metaphysics as scholarship. Instead, they borrow one guiding intuition from it: reality is often better understood as a structured passage from one state to another than as a mere inventory of static objects.
+A small family of examples in the repository (`examples/*-becoming.n3`) explores a common idea: that logic can describe not only what **is** the case, but what a thing, system, lineage, or device can **become**. The inspiration is Whiteheadian in a broad sense. The examples do not attempt to formalize Whitehead’s metaphysics as scholarship. Instead, they borrow one guiding intuition from it: reality is often better understood as a structured passage from one state to another than as a mere inventory of static objects.
 
 In N3 terms, this means the examples are written so that rules describe **state-transition potential**. Earlier examples in the handbook often use predicates such as `:can`, `:cannot`, `:supports`, or `:requires`. The becoming family shifts the emphasis toward predicates such as `:canBecome` and `:cannotBecome`, along with intermediate states such as protected dormancy, germination, negative differential response, or adaptive persistence. This is still ordinary Horn-style reasoning. The novelty is not in the engine, but in the modeling style.
 

package/dist/browser/eyeling.browser.js

@@ -4935,6 +4935,7 @@
     const engine = require('./engine');
     const deref = require('./deref');
     const { PrefixEnv } = require('./prelude');
+    const { parseN3Text, mergeParsedDocuments } = require('./multisource');
 
     function offsetToLineCol(text, offset) {
       const chars = Array.from(text);
@@ -5018,8 +5019,9 @@
 
       function printHelp(toStderr = false) {
         const msg =
-          `Usage: ${prog} [options] [file.n3|-]\n\n` +
-          `When no file is given and stdin is piped, read N3 from stdin.\n\n` +
+          `Usage: ${prog} [options] [file-or-url.n3|- ...]\n\n` +
+          `When no file is given and stdin is piped, read N3 from stdin.\n` +
+          `When multiple inputs are given, parse each source separately, merge ASTs, then reason once.\n\n` +
           `Options:\n` +
           `  -a, --ast                    Print parsed AST as JSON and exit.\n` +
           `      --builtin <module.js>    Load a custom builtin module (repeatable).\n` +
@@ -5063,7 +5065,7 @@
           builtinModules.push(a.slice('--builtin='.length));
           continue;
         }
-        if (!a.startsWith('-')) positional.push(a);
+        if (a === '-' || !a.startsWith('-')) positional.push(a);
       }
 
       const showAst = argv.includes('--ast') || argv.includes('-a');
@@ -5089,17 +5091,12 @@
         if (typeof engine.setSuperRestrictedMode === 'function') engine.setSuperRestrictedMode(true);
       }
 
-      // Positional args (the N3 file)
+      // Positional args (one or more N3 sources).
       const useImplicitStdin = positional.length === 0 && !process.stdin.isTTY;
       if (positional.length === 0 && !useImplicitStdin) {
         printHelp(false);
         process.exit(0);
       }
-      if (positional.length > 1) {
-        console.error('Error: expected at most one input [file.n3|-].');
-        printHelp(true);
-        process.exit(1);
-      }
 
       for (const spec of builtinModules) {
         try {
@@ -5113,35 +5110,47 @@
         }
       }
 
-      const sourceLabel = useImplicitStdin || positional[0] === '-' ? '<stdin>' : positional[0];
-      const baseIri = __sourceLabelToBaseIri(sourceLabel);
-
-      let text;
-      try {
-        text = __readInputSourceSync(sourceLabel);
-      } catch (e) {
-        if (sourceLabel === '<stdin>') console.error(`Error reading stdin: ${e.message}`);
-        else console.error(`Error reading file ${JSON.stringify(sourceLabel)}: ${e.message}`);
+      const sourceLabels = useImplicitStdin ? ['<stdin>'] : positional.map((item) => (item === '-' ? '<stdin>' : item));
+      if (sourceLabels.filter((item) => item === '<stdin>').length > 1) {
+        console.error('Error: stdin can only be used once.');
         process.exit(1);
       }
 
-      let toks;
-      let prefixes, triples, frules, brules, qrules;
-      try {
-        toks = engine.lex(text);
-        const parser = new engine.Parser(toks);
-        if (baseIri) parser.prefixes.setBase(baseIri);
-        [prefixes, triples, frules, brules, qrules] = parser.parseDocument();
-        // Make the parsed prefixes available to log:trace output (CLI path)
-        engine.setTracePrefixes(prefixes);
-      } catch (e) {
-        if (e && e.name === 'N3SyntaxError') {
-          console.error(formatN3SyntaxError(e, text, sourceLabel));
+      const parsedSources = [];
+      for (const sourceLabel of sourceLabels) {
+        let text;
+        try {
+          text = __readInputSourceSync(sourceLabel);
+        } catch (e) {
+          if (sourceLabel === '<stdin>') console.error(`Error reading stdin: ${e.message}`);
+          else console.error(`Error reading source ${JSON.stringify(sourceLabel)}: ${e.message}`);
           process.exit(1);
         }
-        throw e;
+
+        try {
+          parsedSources.push(
+            parseN3Text(text, {
+              baseIri: __sourceLabelToBaseIri(sourceLabel),
+              label: sourceLabel,
+            }),
+          );
+        } catch (e) {
+          if (e && e.name === 'N3SyntaxError') {
+            console.error(formatN3SyntaxError(e, text, sourceLabel));
+            process.exit(1);
+          }
+          throw e;
+        }
       }
 
+      const mergedDocument = mergeParsedDocuments(parsedSources);
+      const prefixes = mergedDocument.prefixes;
+      const triples = mergedDocument.triples;
+      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);
@@ -5285,7 +5294,10 @@
       const mayAutoRenderOutputStrings = programMayProduceOutputStrings(triples, frules, qrules);
 
       if (streamMode && !hasQueries && !mayAutoRenderOutputStrings) {
-        const usedInInput = prefixesUsedInInputTokens(toks, prefixes);
+        const usedInInput = new Set();
+        for (const source of tokenSets) {
+          for (const pfx of prefixesUsedInInputTokens(source.tokens, source.prefixes)) usedInInput.add(pfx);
+        }
         const outPrefixes = restrictPrefixEnv(prefixes, usedInInput);
 
         // Ensure log:trace uses the same compact prefix set as the output.
@@ -5879,6 +5891,7 @@
     const { lex, N3SyntaxError } = require('./lexer');
     const { Parser } = require('./parser');
     const { liftBlankRuleVars } = require('./rules');
+    const { parseN3SourceList } = require('./multisource');
 
     const {
       makeBuiltins,
@@ -9228,7 +9241,8 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
         builtinModules = null,
       } = opts;
 
-      const parsedInput = normalizeParsedReasonerInputSync(input);
+      const parsedSourceList = parseN3SourceList(input, { baseIri });
+      const parsedInput = parsedSourceList || normalizeParsedReasonerInputSync(input);
       const rdfFactory = rdfjs ? getDataFactory(dataFactory) : null;
 
       const __oldEnforceHttps = deref.getEnforceHttpsEnabled();
@@ -9371,7 +9385,7 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
 
       Promise.resolve().then(async () => {
         try {
-          const normalizedInput = await normalizeReasonerInputAsync(input);
+          const normalizedInput = parseN3SourceList(input, restOpts) || (await normalizeReasonerInputAsync(input));
           reasonStream(normalizedInput, {
             ...restOpts,
             rdfjs: false,
@@ -10566,6 +10580,206 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
 
     module.exports = { Token, N3SyntaxError, lex, decodeN3StringEscapes };
   };
+  __modules['lib/multisource.js'] = function (require, module, exports) {
+    /**
+     * Eyeling Reasoner — multi-source parsing helpers
+     *
+     * These helpers let the CLI/API parse several N3 documents independently and
+     * merge their parsed ASTs before reasoning. This avoids building one giant N3
+     * string while preserving the existing lexer/parser/engine pipeline.
+     */
+
+    'use strict';
+
+    const { lex } = require('./lexer');
+    const { Parser } = require('./parser');
+    const {
+      Blank,
+      ListTerm,
+      OpenListTerm,
+      GraphTerm,
+      Triple,
+      Rule,
+      PrefixEnv,
+      annotateQuotedGraphTerm,
+    } = require('./prelude');
+
+    function emptyParsedDocument() {
+      return {
+        prefixes: PrefixEnv.newDefault(),
+        triples: [],
+        frules: [],
+        brules: [],
+        logQueryRules: [],
+      };
+    }
+
+    function parseN3Text(text, opts = {}) {
+      const { baseIri = '', label = '<input>' } = 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 };
+    }
+
+    function sourceBlankPrefix(sourceIndex) {
+      return `_:src${sourceIndex}_`;
+    }
+
+    function scopedBlankLabel(label, sourceIndex, mapping) {
+      const key = String(label || '');
+      let out = mapping.get(key);
+      if (out) return out;
+
+      const bare = key.startsWith('_:') ? key.slice(2) : key;
+      out = sourceBlankPrefix(sourceIndex) + bare;
+      mapping.set(key, out);
+      return out;
+    }
+
+    function scopeBlankNodesInDocument(doc, sourceIndex) {
+      const mapping = new Map();
+
+      function cloneTerm(term) {
+        if (term instanceof Blank) return new Blank(scopedBlankLabel(term.label, sourceIndex, mapping));
+        if (term instanceof ListTerm) return new ListTerm(term.elems.map(cloneTerm));
+        if (term instanceof OpenListTerm) return new OpenListTerm(term.prefix.map(cloneTerm), term.tailVar);
+        if (term instanceof GraphTerm) return annotateQuotedGraphTerm(new GraphTerm(term.triples.map(cloneTriple)));
+        return term;
+      }
+
+      function cloneTriple(triple) {
+        return new Triple(cloneTerm(triple.s), cloneTerm(triple.p), cloneTerm(triple.o));
+      }
+
+      function cloneRule(rule) {
+        const headBlankLabels = new Set();
+        if (rule && rule.headBlankLabels instanceof Set) {
+          for (const label of rule.headBlankLabels) headBlankLabels.add(scopedBlankLabel(label, sourceIndex, mapping));
+        }
+
+        const out = new Rule(
+          (rule.premise || []).map(cloneTriple),
+          (rule.conclusion || []).map(cloneTriple),
+          rule.isForward,
+          rule.isFuse,
+          headBlankLabels,
+        );
+
+        if (rule && Object.prototype.hasOwnProperty.call(rule, '__dynamicConclusionTerm')) {
+          Object.defineProperty(out, '__dynamicConclusionTerm', {
+            value: cloneTerm(rule.__dynamicConclusionTerm),
+            enumerable: false,
+            writable: false,
+            configurable: true,
+          });
+        }
+
+        return out;
+      }
+
+      return {
+        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,
+      };
+    }
+
+    function mergePrefixEnvs(target, source) {
+      if (!source) return target;
+      const map = source.map || {};
+      for (const [prefix, iri] of Object.entries(map)) {
+        // Every parser starts with an empty default namespace. Do not let a later
+        // source that never declared ':' erase a useful default namespace from an
+        // earlier source; prefix merging is for output readability only.
+        if (iri || !Object.prototype.hasOwnProperty.call(target.map, prefix)) target.set(prefix, iri);
+      }
+      if (source.baseIri) target.setBase(source.baseIri);
+      return target;
+    }
+
+    function mergeParsedDocuments(docs, opts = {}) {
+      const documents = Array.isArray(docs) ? docs : [];
+      const scopeBlankNodes = typeof opts.scopeBlankNodes === 'boolean' ? opts.scopeBlankNodes : documents.length > 1;
+
+      const merged = emptyParsedDocument();
+      const mergedSources = [];
+
+      for (let i = 0; i < documents.length; i++) {
+        const originalDoc = documents[i] || emptyParsedDocument();
+        const doc = scopeBlankNodes ? scopeBlankNodesInDocument(originalDoc, i + 1) : originalDoc;
+
+        mergePrefixEnvs(merged.prefixes, doc.prefixes);
+        merged.triples.push(...(doc.triples || []));
+        merged.frules.push(...(doc.frules || []));
+        merged.brules.push(...(doc.brules || []));
+        merged.logQueryRules.push(...(doc.logQueryRules || []));
+        mergedSources.push(doc);
+      }
+
+      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));
+    }
+
+    function normalizeN3SourceItem(source, index) {
+      const sourceNumber = index + 1;
+      if (typeof source === 'string') {
+        return { text: source, label: `<source ${sourceNumber}>`, baseIri: '' };
+      }
+      if (!source || typeof source !== 'object' || Array.isArray(source)) {
+        throw new TypeError('Each N3 source must be a string or an object with an n3/text field');
+      }
+
+      const text = typeof source.n3 === 'string' ? source.n3 : typeof source.text === 'string' ? source.text : null;
+      if (text === null) throw new TypeError('Each N3 source object must provide an n3 or text string');
+
+      return {
+        text,
+        label: typeof source.label === 'string' && source.label ? source.label : `<source ${sourceNumber}>`,
+        baseIri: typeof source.baseIri === 'string' ? source.baseIri : '',
+      };
+    }
+
+    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) =>
+        parseN3Text(source.text, {
+          label: source.label,
+          baseIri: source.baseIri || (sources.length === 1 ? defaultBaseIri : ''),
+        }),
+      );
+      return mergeParsedDocuments(parsed, {
+        scopeBlankNodes: typeof input.scopeBlankNodes === 'boolean' ? input.scopeBlankNodes : parsed.length > 1,
+      });
+    }
+
+    module.exports = {
+      emptyParsedDocument,
+      parseN3Text,
+      mergeParsedDocuments,
+      scopeBlankNodesInDocument,
+      isN3SourceListInput,
+      parseN3SourceList,
+    };
+  };
   __modules['lib/parser.js'] = function (require, module, exports) {
     /**
      * Eyeling Reasoner — parser