eyeling 1.25.5 → 1.26.1

package/dist/browser/eyeling.browser.js

@@ -4721,7 +4721,7 @@ function main() {
       `  -d, --deterministic-skolem   Make log:skolem stable across reasoning runs.\n` +
       `  -e, --enforce-https          Rewrite http:// IRIs to https:// for log dereferencing builtins.\n` +
       `  -h, --help                   Show this help and exit.\n` +
-      `  -p, --proof-comments         Enable proof explanations.\n` +
+      `  -p, --proof                  Enable proof explanations.\n` +
       `  -r, --rdf                    Enable RDF/TriG input/output compatibility.\n` +
       `  -s, --super-restricted       Disable all builtins except => and <=.\n` +
       `  -t, --stream                 Stream derived triples as soon as they are derived.\n` +
@@ -4776,8 +4776,8 @@ function main() {
     if (typeof engine.setDeterministicSkolemEnabled === 'function') engine.setDeterministicSkolemEnabled(true);
   }
 
-  // --proof-comments / -p: enable proof explanations
-  if (argv.includes('--proof-comments') || argv.includes('-p')) {
+  // --proof / -p: enable proof explanations as N3 proof graphs
+  if (argv.includes('--proof') || argv.includes('--proof-comments') || argv.includes('-p')) {
     engine.setProofCommentsEnabled(true);
   }
 
@@ -4827,6 +4827,7 @@ function main() {
           label: sourceLabel,
           collectUsedPrefixes: streamMode,
           keepSourceArtifacts: false,
+          sourceLocations: engine.getProofCommentsEnabled(),
           rdf: rdfMode,
         }),
       );
@@ -4916,7 +4917,7 @@ function main() {
   const hasQueries = Array.isArray(qrules) && qrules.length;
   const mayAutoRenderOutputStrings = programMayProduceOutputStrings(triples, frules, qrules);
 
-  if (streamMode && !hasQueries && !mayAutoRenderOutputStrings) {
+  if (streamMode && !hasQueries && !mayAutoRenderOutputStrings && !engine.getProofCommentsEnabled()) {
     const usedInInput = mergedDocument.usedPrefixes instanceof Set ? new Set(mergedDocument.usedPrefixes) : new Set();
     const outPrefixes = restrictPrefixEnv(prefixes, usedInInput);
 
@@ -4981,6 +4982,11 @@ function main() {
     return;
   }
 
+  if (engine.getProofCommentsEnabled()) {
+    process.stdout.write(engine.renderProofDocument(outDerived, derived.concat(outDerived || []), triples, prefixes, brules));
+    return;
+  }
+
   let bodyText = '';
   if (rdfMode && !engine.getProofCommentsEnabled()) {
     bodyText = outTriples.map((tr) => engine.tripleToRdfCompatible(tr, prefixes)).join('\n');
@@ -5514,6 +5520,7 @@ const {
   Triple,
   Rule,
   DerivedFact,
+  varsInRule,
   internIri,
   collectBlankLabelsInTriples,
   copyQuotedGraphMetadata,
@@ -5531,7 +5538,7 @@ const EMPTY_LIST_TERM = new ListTerm([]);
 const { lex, N3SyntaxError } = require('./lexer');
 const { Parser } = require('./parser');
 const { liftBlankRuleVars } = require('./rules');
-const { parseN3SourceList } = require('./multisource');
+const { parseN3Text, parseN3SourceList } = require('./multisource');
 
 const {
   makeBuiltins,
@@ -6269,9 +6276,11 @@ const { evalBuiltin, isBuiltinPred } = makeBuiltins({
 });
 
 // Initialize proof/output helpers (implemented in lib/explain.js).
-const { printExplanation, collectOutputStringsFromFacts } = makeExplain({
+const { printExplanation, renderProofDocument, collectOutputStringsFromFacts } = makeExplain({
   applySubstTerm,
   skolemKeyFromTerm,
+  isBuiltinPred,
+  findBackwardProofForGoal,
 });
 
 function skolemizeTermForHeadBlanks(t, headBlankLabels, mapping, skCounter, firingKey, globalMap) {
@@ -8643,6 +8652,120 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
   return results;
 }
 
+
+// Reconstruct one backward proof for N3 proof output. This is intentionally
+// called only by renderProofDocument(), so normal reasoning does not pay for it.
+function __proofTripleKey(tr) {
+  if (!tr) return '';
+  return `${skolemKeyFromTerm(tr.s)}\t${skolemKeyFromTerm(tr.p)}\t${skolemKeyFromTerm(tr.o)}`;
+}
+
+function __copyProofSource(from, to) {
+  if (from && to && Object.prototype.hasOwnProperty.call(from, '__source')) {
+    Object.defineProperty(to, '__source', {
+      value: from.__source,
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  }
+  return to;
+}
+
+function __annotateProofVarSourceNames(rule) {
+  if (!rule) return rule;
+  const sourceNames = Object.create(null);
+  for (const name of varsInRule(rule)) {
+    const m = /^(.*)__\d+$/.exec(name);
+    sourceNames[name] = m ? m[1] : name;
+  }
+  Object.defineProperty(rule, '__proofVarSourceNames', {
+    value: sourceNames,
+    enumerable: false,
+    writable: false,
+    configurable: true,
+  });
+  return rule;
+}
+
+function findBackwardProofForGoal(goal, facts, backRules, opts = {}) {
+  const maxDepth = Number.isInteger(opts.maxDepth) && opts.maxDepth >= 0 ? opts.maxDepth : 64;
+  const varGen = Array.isArray(opts.varGen) ? opts.varGen : [1];
+  const visited = opts.visited instanceof Set ? opts.visited : new Set();
+  const factList = Array.isArray(facts) ? facts : [];
+  const ruleList = Array.isArray(backRules) ? backRules : [];
+
+  function matchingBaseFact(g) {
+    const candidates = g && g.p instanceof Iri ? candidateFacts(factList, g) : null;
+    const total = candidates ? candidates.totalLen : factList.length;
+    for (let i = 0; i < total; i++) {
+      let f;
+      if (candidates) {
+        if (i < candidates.exactLen) f = factList[candidates.exact[i]];
+        else f = factList[candidates.wild[i - candidates.exactLen]];
+      } else {
+        f = factList[i];
+      }
+      if (unifyTriple(g, f, __emptySubst()) !== null) return f;
+    }
+    return null;
+  }
+
+  function builtinProof(g) {
+    if (!(g && isBuiltinPred(g.p))) return null;
+    return { kind: 'builtin', fact: g, builtin: g.p };
+  }
+
+  function solve(g, depth) {
+    if (!g || depth > maxDepth) return null;
+
+    const base = matchingBaseFact(g);
+    if (base) return { kind: 'fact', fact: base, source: base.__source };
+
+    const builtin = builtinProof(g);
+    if (builtin) return builtin;
+
+    if (!(g.p instanceof Iri)) return null;
+    const gKey = __proofTripleKey(g);
+    if (visited.has(gKey)) return null;
+    visited.add(gKey);
+
+    try {
+      ensureBackRuleIndexes(ruleList);
+      const candRules = (ruleList.__byHeadPred.get(g.p.__tid) || []).concat(ruleList.__wildHeadPred);
+      for (const r of candRules) {
+        if (!r || !Array.isArray(r.conclusion) || r.conclusion.length !== 1) continue;
+        const rawHead = r.conclusion[0];
+        if (rawHead.p instanceof Iri && rawHead.p.__tid !== g.p.__tid) continue;
+
+        const rStd = __annotateProofVarSourceNames(__copyProofSource(r, standardizeRule(r, varGen)));
+        const head = rStd.conclusion[0];
+        const s0 = unifyTriple(head, g, __emptySubst());
+        if (s0 === null) continue;
+
+        const solutions = proveGoals(rStd.premise, s0, factList, ruleList, depth + 1, [], varGen, 1, {
+          keepVars: varsInRule(rStd),
+          deferBuiltins: true,
+        });
+        if (!solutions.length) continue;
+
+        const subst = solutions[0];
+        const fact = applySubstTriple(head, subst);
+        const premises = rStd.premise.map((prem) => applySubstTriple(prem, subst));
+        const df = new DerivedFact(fact, rStd, premises, __cloneSubst(subst));
+        const children = premises.map((prem) => builtinProof(prem) || solve(prem, depth + 1));
+        return { kind: 'rule', df, children };
+      }
+    } finally {
+      visited.delete(gKey);
+    }
+
+    return null;
+  }
+
+  return solve(goal, 0);
+}
+
 // ===========================================================================
 // Forward chaining to fixpoint
 // ===========================================================================
@@ -9328,7 +9451,7 @@ function reasonStream(input, opts = {}) {
 
   const useRdfCompatibility = !!rdf;
 
-  const parsedSourceList = parseN3SourceList(input, { baseIri, rdf: useRdfCompatibility });
+  const parsedSourceList = parseN3SourceList(input, { baseIri, rdf: useRdfCompatibility, sourceLocations: proof });
   const parsedInput = parsedSourceList || normalizeParsedReasonerInputSync(input);
   const rdfFactory = rdfjs ? getDataFactory(dataFactory) : null;
 
@@ -9364,11 +9487,22 @@ function reasonStream(input, opts = {}) {
     if (baseIri) prefixes.setBase(baseIri);
   } else {
     const n3Text = normalizeReasonerInputSync(input);
-    const toks = lex(n3Text, { rdf: useRdfCompatibility });
-    const parser = new Parser(toks);
-    if (baseIri) parser.prefixes.setBase(baseIri);
+    if (proof) {
+      const parsed = parseN3Text(n3Text, {
+        label: 'input.n3',
+        baseIri: baseIri || '',
+        keepSourceArtifacts: false,
+        sourceLocations: true,
+        rdf: useRdfCompatibility,
+      });
+      ({ prefixes, triples, frules, brules, logQueryRules } = parsed);
+    } else {
+      const toks = lex(n3Text, { rdf: useRdfCompatibility });
+      const parser = new Parser(toks);
+      if (baseIri) parser.prefixes.setBase(baseIri);
 
-    [prefixes, triples, frules, brules, logQueryRules] = parser.parseDocument();
+      [prefixes, triples, frules, brules, logQueryRules] = parser.parseDocument();
+    }
   }
   // Make the parsed prefixes available to log:trace output
   trace.setTracePrefixes(prefixes);
@@ -9436,11 +9570,19 @@ function reasonStream(input, opts = {}) {
         ? facts
         : derived.map((d) => d.fact);
 
-  const closureN3 = useRdfCompatibility
-    ? closureTriples.map((t) => tripleToRdfCompatible(t, prefixes)).join('\n')
-    : Array.isArray(logQueryRules) && logQueryRules.length && !proof
-      ? prettyPrintQueryTriples(closureTriples, prefixes)
-      : closureTriples.map((t) => tripleToN3(t, prefixes)).join('\n');
+  const closureN3 = proof
+    ? renderProofDocument(
+        Array.isArray(logQueryRules) && logQueryRules.length ? queryDerived : derived,
+        derived.concat(queryDerived || []),
+        triples,
+        prefixes,
+        brules,
+      ).replace(/\n$/g, '')
+    : useRdfCompatibility
+      ? closureTriples.map((t) => tripleToRdfCompatible(t, prefixes)).join('\n')
+      : Array.isArray(logQueryRules) && logQueryRules.length
+        ? prettyPrintQueryTriples(closureTriples, prefixes)
+        : closureTriples.map((t) => tripleToN3(t, prefixes)).join('\n');
 
   const __out = {
     prefixes,
@@ -9484,7 +9626,7 @@ function reasonRdfJs(input, opts = {}) {
 
   Promise.resolve().then(async () => {
     try {
-      const normalizedInput = parseN3SourceList(input, restOpts) || (await normalizeReasonerInputAsync(input));
+      const normalizedInput = parseN3SourceList(input, { ...restOpts, sourceLocations: !!(restOpts.proof || restOpts.proofComments) }) || (await normalizeReasonerInputAsync(input));
       reasonStream(normalizedInput, {
         ...restOpts,
         rdfjs: false,
@@ -9567,6 +9709,7 @@ module.exports = {
   collectLogQueryConclusions,
   forwardChainAndCollectLogQueryConclusions,
   collectOutputStringsFromFacts,
+  renderProofDocument,
   main,
   version,
   N3SyntaxError,
@@ -9636,6 +9779,7 @@ module.exports = {
   materializeRdfLists: engine.materializeRdfLists,
   isGroundTriple: engine.isGroundTriple,
   printExplanation: engine.printExplanation,
+  renderProofDocument: engine.renderProofDocument,
   tripleToN3: engine.tripleToN3,
   collectOutputStringsFromFacts: engine.collectOutputStringsFromFacts,
   prettyPrintQueryTriples: engine.prettyPrintQueryTriples,
@@ -9662,7 +9806,7 @@ module.exports = {
  */
 'use strict';
 
-const { LOG_NS, Literal, Iri, Blank, Var, varsInRule, literalParts } = require('./prelude');
+const { LOG_NS, Literal, Iri, Blank, Var, GraphTerm, varsInRule, literalParts, PrefixEnv } = require('./prelude');
 
 const { termToN3, tripleToN3 } = require('./printing');
 const { parseNumericLiteralInfo, termToJsString } = require('./builtins');
@@ -9670,6 +9814,8 @@ const { parseNumericLiteralInfo, termToJsString } = require('./builtins');
 function makeExplain(deps) {
   const applySubstTerm = deps.applySubstTerm;
   const skolemKeyFromTerm = deps.skolemKeyFromTerm;
+  const isBuiltinPred = typeof deps.isBuiltinPred === 'function' ? deps.isBuiltinPred : () => false;
+  const findBackwardProofForGoal = typeof deps.findBackwardProofForGoal === 'function' ? deps.findBackwardProofForGoal : null;
 
   function printExplanation(df, prefixes) {
     console.log('# ----------------------------------------------------------------------');
@@ -9767,6 +9913,301 @@ function makeExplain(deps) {
     console.log('# ----------------------------------------------------------------------\n');
   }
 
+
+  const PE_NS = 'https://eyereasoner.github.io/pe#';
+
+  function n3String(value) {
+    return JSON.stringify(String(value));
+  }
+
+  function lineIndent(text, prefix) {
+    return String(text)
+      .split(/\r?\n/)
+      .map((line) => (line.length ? prefix + line : line))
+      .join('\n');
+  }
+
+  function graphForTriple(tr, prefixes) {
+    const body = tripleToN3(tr, prefixes).trimEnd();
+    if (!body.includes('\n')) return `{ ${body} }`;
+    return `{
+${lineIndent(body, '    ')}
+}`;
+  }
+
+  function clonePrefixEnvWithProofVocabulary(prefixes) {
+    const map = { ...(prefixes && prefixes.map ? prefixes.map : {}) };
+    if (!map.pe) map.pe = PE_NS;
+    return new PrefixEnv(map, (prefixes && prefixes.baseIri) || '');
+  }
+
+  function proofTripleKey(tr) {
+    if (!tr) return '';
+    return `${skolemKeyFromTerm(tr.s)}\t${skolemKeyFromTerm(tr.p)}\t${skolemKeyFromTerm(tr.o)}`;
+  }
+
+  function sourceLabelForProof(source) {
+    if (!source || typeof source.label !== 'string' || !source.label) return '<unknown>';
+    // Keep proof output stable when the CLI is invoked with paths such as examples/foo.n3.
+    return source.label.replace(/\\/g, '/').split('/').pop() || source.label;
+  }
+
+  function sourceKeyForProof(source) {
+    if (!source) return '<unknown>';
+    return `${sourceLabelForProof(source)}:${Number.isInteger(source.line) ? source.line : ''}`;
+  }
+
+  function byBlankNode(kind, source) {
+    const src = source || {};
+    const props = [`pe:${kind} ${n3String(sourceLabelForProof(src))}`];
+    if (Number.isInteger(src.line) && src.line > 0) props.push(`pe:line ${src.line}`);
+    return `[ ${props.join('; ')} ]`;
+  }
+
+  function renderBindingItems(df, prefixes) {
+    if (!df || !df.rule || !df.subst) return [];
+    const ruleVars = varsInRule(df.rule);
+    const visibleNames = Object.keys(df.subst)
+      .filter((name) => ruleVars.has(name))
+      .sort();
+    if (!visibleNames.length) return [];
+    const sourceNames = (df.rule && df.rule.__proofVarSourceNames) || null;
+    return visibleNames.map((name) => {
+      const value = applySubstTerm(new Var(name), df.subst);
+      const displayName = sourceNames && sourceNames[name] ? sourceNames[name] : name;
+      return `[ pe:var ${n3String(displayName)}; pe:value ${termToN3(value, prefixes)} ]`;
+    });
+  }
+
+  function withLastLineSuffix(text, suffix) {
+    const lines = String(text).split(/\r?\n/);
+    lines[lines.length - 1] += suffix;
+    return lines.join('\n');
+  }
+
+  function renderPredicateObjects(predicate, objects, isLast) {
+    const values = (objects || []).filter((value) => value);
+    if (!values.length) return [];
+    const end = isLast ? '.' : ';';
+    if (values.length === 1 && !values[0].includes('\n')) {
+      return [`    ${predicate} ${values[0]}${end}`];
+    }
+    const out = [`    ${predicate}`];
+    for (let i = 0; i < values.length; i++) {
+      const suffix = i === values.length - 1 ? end : ',';
+      out.push(lineIndent(withLastLineSuffix(values[i], suffix), '      '));
+    }
+    return out;
+  }
+
+  function proofEntryKey(entry) {
+    if (!entry) return '';
+    if (entry.kind === 'rule') {
+      const df = entry.df;
+      const source = df && df.rule && df.rule.__source;
+      const premiseKey = (df && df.premises ? df.premises : []).map(proofTripleKey).join('|');
+      return `rule:${proofTripleKey(df && df.fact)}:${sourceKeyForProof(source)}:${premiseKey}`;
+    }
+    if (entry.kind === 'builtin') return `builtin:${proofTripleKey(entry.fact)}`;
+    return `fact:${proofTripleKey(entry.fact)}:${sourceKeyForProof(entry.source)}`;
+  }
+
+  function collectProofEntries(rootDf, derivedByKey, baseFactByKey, resolveBackwardProof) {
+    const entries = [];
+    const seen = new Set();
+
+    function remember(entry) {
+      const key = proofEntryKey(entry);
+      if (!key || seen.has(key)) return false;
+      seen.add(key);
+      entries.push(entry);
+      return true;
+    }
+
+    function derivedCandidatesForKey(key) {
+      const found = derivedByKey.get(key);
+      if (!found) return [];
+      return Array.isArray(found) ? found : [found];
+    }
+
+    function visitProofNode(proof, fallbackTriple, parentDf) {
+      if (!proof) {
+        visitFactTriple(fallbackTriple, parentDf);
+        return;
+      }
+      if (proof.kind === 'rule' && proof.df) {
+        visitDerivedFact(proof.df, proof.children || null);
+        return;
+      }
+      if (proof.kind === 'builtin') {
+        remember({ kind: 'builtin', fact: proof.fact || fallbackTriple, builtin: proof.builtin || (proof.fact && proof.fact.p) });
+        return;
+      }
+      remember({ kind: 'fact', fact: proof.fact || fallbackTriple, source: proof.source });
+    }
+
+    function visitFactTriple(tr, parentDf) {
+      const key = proofTripleKey(tr);
+      const base = baseFactByKey.get(key) || null;
+      if (base) {
+        remember({ kind: 'fact', fact: base, source: base.__source });
+        return;
+      }
+
+      const candidates = derivedCandidatesForKey(key);
+      const df = candidates.find((candidate) => candidate !== parentDf) || null;
+      if (df) {
+        visitDerivedFact(df);
+        return;
+      }
+
+      if (tr && isBuiltinPred(tr.p)) {
+        remember({ kind: 'builtin', fact: tr, builtin: tr.p });
+        return;
+      }
+
+      if (resolveBackwardProof) {
+        const proof = resolveBackwardProof(tr);
+        if (proof) {
+          visitProofNode(proof, tr, parentDf);
+          return;
+        }
+      }
+
+      remember({ kind: 'fact', fact: tr, source: null });
+    }
+
+    function visitDerivedFact(df, children) {
+      if (!df || !df.fact) return;
+      const entry = { kind: 'rule', df };
+      if (!remember(entry)) return;
+
+      if (Array.isArray(children) && children.length) {
+        for (const child of children) visitProofNode(child, null, df);
+        return;
+      }
+      for (const prem of df.premises || []) visitFactTriple(prem, df);
+    }
+
+    visitDerivedFact(rootDf);
+    return entries;
+  }
+
+  function collectProofOutputTriples(outputDerived) {
+    const out = [];
+    const seen = new Set();
+    for (const df of outputDerived || []) {
+      if (!df || !df.fact) continue;
+      const key = proofTripleKey(df.fact);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(df.fact);
+    }
+    return out;
+  }
+
+  function renderProofEntry(entry, prefixes) {
+    if (!entry) return '';
+    if (entry.kind === 'fact') {
+      return `  ${graphForTriple(entry.fact, prefixes)}\n    pe:by ${byBlankNode('fact', entry.source)}.`;
+    }
+    if (entry.kind === 'builtin') {
+      return `  ${graphForTriple(entry.fact, prefixes)}\n    pe:by [ pe:builtin ${termToN3(entry.builtin, prefixes)} ].`;
+    }
+
+    const df = entry.df;
+    const bindingItems = renderBindingItems(df, prefixes);
+    const useItems = (df.premises || []).map((prem) => graphForTriple(prem, prefixes));
+    const propertyGroups = [
+      { predicate: 'pe:by', objects: [byBlankNode('rule', df.rule && df.rule.__source)] },
+      { predicate: 'pe:binding', objects: bindingItems },
+      { predicate: 'pe:uses', objects: useItems },
+    ].filter((group) => group.objects.length);
+
+    let out = `  ${graphForTriple(df.fact, prefixes)}\n`;
+    for (let i = 0; i < propertyGroups.length; i++) {
+      const group = propertyGroups[i];
+      out += renderPredicateObjects(group.predicate, group.objects, i === propertyGroups.length - 1).join('\n') + '\n';
+    }
+    return out.trimEnd();
+  }
+
+  function renderProofBlock(rootDf, derivedByKey, baseFactByKey, prefixes, resolveBackwardProof) {
+    const entries = collectProofEntries(rootDf, derivedByKey, baseFactByKey, resolveBackwardProof);
+    const rootGraph = graphForTriple(rootDf.fact, prefixes);
+    const proofBody = entries.map((entry) => renderProofEntry(entry, prefixes)).join('\n\n');
+    const proofGraph = proofBody ? `{
+${proofBody}
+}` : '{}';
+    return `${rootGraph} pe:why ${proofGraph}.`;
+  }
+
+  function renderProofDocument(outputDerived, allDerived, baseFacts, prefixes, backRules) {
+    const selectedDerived = Array.isArray(outputDerived) ? outputDerived.filter((df) => df && df.fact) : [];
+    if (!selectedDerived.length) return '';
+
+    const proofPrefixes = clonePrefixEnvWithProofVocabulary(prefixes);
+    const derivedByKey = new Map();
+    function addDerived(df) {
+      if (!df || !df.fact) return;
+      const key = proofTripleKey(df.fact);
+      let bucket = derivedByKey.get(key);
+      if (!bucket) {
+        bucket = [];
+        derivedByKey.set(key, bucket);
+      }
+      if (!bucket.includes(df)) bucket.push(df);
+    }
+    for (const df of allDerived || []) addDerived(df);
+    for (const df of selectedDerived) addDerived(df);
+
+    const baseFactByKey = new Map();
+    for (const tr of baseFacts || []) {
+      if (!tr) continue;
+      const key = proofTripleKey(tr);
+      if (!baseFactByKey.has(key)) baseFactByKey.set(key, tr);
+    }
+
+    const resolveBackwardProof = findBackwardProofForGoal
+      ? (tr) => findBackwardProofForGoal(tr, baseFacts || [], backRules || [], { maxDepth: 64 })
+      : null;
+
+    const outputTriples = collectProofOutputTriples(selectedDerived);
+    const proofRelationTriples = [];
+    for (const df of selectedDerived) {
+      proofRelationTriples.push({ s: new GraphTerm([df.fact]), p: new Iri(PE_NS + 'why'), o: new GraphTerm([]) });
+      for (const entry of collectProofEntries(df, derivedByKey, baseFactByKey, resolveBackwardProof)) {
+        const fact = entry.kind === 'rule' ? entry.df.fact : entry.fact;
+        const byObject = entry.kind === 'builtin' && entry.builtin ? entry.builtin : new Iri(PE_NS + 'source');
+        proofRelationTriples.push({ s: new GraphTerm([fact]), p: new Iri(PE_NS + 'by'), o: byObject });
+        if (entry.kind === 'rule') {
+          for (const prem of entry.df.premises || []) proofRelationTriples.push({ s: new GraphTerm([fact]), p: new Iri(PE_NS + 'uses'), o: new GraphTerm([prem]) });
+        }
+      }
+    }
+
+    const usedPrefixes = proofPrefixes.prefixesUsedForOutput(outputTriples.concat(proofRelationTriples));
+    if (!usedPrefixes.some(([pfx]) => pfx === 'pe')) usedPrefixes.push(['pe', PE_NS]);
+    usedPrefixes.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+
+    const parts = [];
+    for (const [pfx, base] of usedPrefixes) {
+      if (!base) continue;
+      if (pfx === '') parts.push(`@prefix : <${base}> .`);
+      else parts.push(`@prefix ${pfx}: <${base}> .`);
+    }
+    if (parts.length) parts.push('');
+
+    parts.push(...outputTriples.map((tr) => tripleToN3(tr, proofPrefixes)));
+    parts.push('');
+    for (let i = 0; i < selectedDerived.length; i++) {
+      if (i > 0) parts.push('');
+      parts.push(renderProofBlock(selectedDerived[i], derivedByKey, baseFactByKey, proofPrefixes, resolveBackwardProof));
+    }
+
+    return parts.join('\n').replace(/[ \t]+$/gm, '').replace(/\s*$/g, '') + '\n';
+  }
+
   // ===========================================================================
   // CLI entry point
   // ===========================================================================
@@ -9873,7 +10314,7 @@ function makeExplain(deps) {
     return addMarkdownHardBreaks(pairs.map((p) => p.text).join(''));
   }
 
-  return { printExplanation, collectOutputStringsFromFacts };
+  return { printExplanation, renderProofDocument, collectOutputStringsFromFacts };
 }
 
 module.exports = { makeExplain };
@@ -11665,6 +12106,67 @@ function emptyParsedDocument() {
   };
 }
 
+function lineStartsForText(text) {
+  const starts = [0];
+  const str = String(text);
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    if (c === '\n') starts.push(i + 1);
+    else if (c === '\r') {
+      starts.push(i + 1 < str.length && str[i + 1] === '\n' ? i + 2 : i + 1);
+      if (i + 1 < str.length && str[i + 1] === '\n') i++;
+    }
+  }
+  return starts;
+}
+
+function offsetToLine(lineStarts, offset) {
+  if (typeof offset !== 'number') return null;
+  let lo = 0;
+  let hi = lineStarts.length;
+  while (lo + 1 < hi) {
+    const mid = (lo + hi) >> 1;
+    if (lineStarts[mid] <= offset) lo = mid;
+    else hi = mid;
+  }
+  return lo + 1;
+}
+
+function annotateSourceLocation(obj, lineStarts, label) {
+  if (!obj || typeof obj.__sourceOffset !== 'number') return obj;
+  const line = offsetToLine(lineStarts, obj.__sourceOffset);
+  Object.defineProperty(obj, '__source', {
+    value: { label, line },
+    enumerable: false,
+    writable: false,
+    configurable: true,
+  });
+  return obj;
+}
+
+function annotateParsedSourceLocations(doc, text, label) {
+  const lineStarts = lineStartsForText(text);
+  for (const tr of doc.triples || []) annotateSourceLocation(tr, lineStarts, label);
+  for (const r of doc.frules || []) annotateSourceLocation(r, lineStarts, label);
+  for (const r of doc.brules || []) annotateSourceLocation(r, lineStarts, label);
+  for (const r of doc.logQueryRules || []) annotateSourceLocation(r, lineStarts, label);
+}
+
+function copySourceMetadata(from, to) {
+  if (!from || !to) return to;
+  for (const key of ['__sourceOffset', '__source']) {
+    if (Object.prototype.hasOwnProperty.call(from, key)) {
+      Object.defineProperty(to, key, {
+        value: from[key],
+        enumerable: false,
+        writable: false,
+        configurable: true,
+      });
+    }
+  }
+  return to;
+}
+
 function prefixesUsedInTokens(tokens, prefEnv) {
   const used = new Set();
   const toks = Array.isArray(tokens) ? tokens : [];
@@ -11742,6 +12244,7 @@ function parseN3Text(text, opts = {}) {
     label = '<input>',
     keepSourceArtifacts = true,
     collectUsedPrefixes = false,
+    sourceLocations = false,
     rdf = false,
   } = opts || {};
   const tokens = lex(text, { rdf });
@@ -11750,6 +12253,7 @@ function parseN3Text(text, opts = {}) {
   const [prefixes, triples, frules, brules, logQueryRules] = parser.parseDocument();
 
   const doc = { prefixes, triples, frules, brules, logQueryRules, label };
+  if (sourceLocations) annotateParsedSourceLocations(doc, text, label);
 
   if (collectUsedPrefixes) {
     Object.defineProperty(doc, 'usedPrefixes', {
@@ -11795,7 +12299,7 @@ function scopeBlankNodesInDocument(doc, sourceIndex) {
   }
 
   function cloneTriple(triple) {
-    return new Triple(cloneTerm(triple.s), cloneTerm(triple.p), cloneTerm(triple.o));
+    return copySourceMetadata(triple, new Triple(cloneTerm(triple.s), cloneTerm(triple.p), cloneTerm(triple.o)));
   }
 
   function cloneRule(rule) {
@@ -11804,12 +12308,15 @@ function scopeBlankNodesInDocument(doc, sourceIndex) {
       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,
+    const out = copySourceMetadata(
+      rule,
+      new Rule(
+        (rule.premise || []).map(cloneTriple),
+        (rule.conclusion || []).map(cloneTriple),
+        rule.isForward,
+        rule.isFuse,
+        headBlankLabels,
+      ),
     );
 
     if (rule && Object.prototype.hasOwnProperty.call(rule, '__dynamicConclusionTerm')) {
@@ -11938,6 +12445,7 @@ function parseN3SourceList(input, opts = {}) {
       baseIri: source.baseIri || (sources.length === 1 ? defaultBaseIri : ''),
       collectUsedPrefixes: true,
       keepSourceArtifacts: !!opts.keepSourceArtifacts,
+      sourceLocations: !!opts.sourceLocations,
       rdf: !!opts.rdf,
     }),
   );
@@ -12003,6 +12511,17 @@ function failInvalidKeywordLikeIdent(fail, tok, name) {
   fail(`invalid_keyword(${name})`, tok);
 }
 
+function annotateSourceOffset(obj, offset) {
+  if (!obj || typeof offset !== 'number') return obj;
+  Object.defineProperty(obj, '__sourceOffset', {
+    value: offset,
+    enumerable: false,
+    writable: false,
+    configurable: true,
+  });
+  return obj;
+}
+
 class Parser {
   constructor(tokens) {
     this.toks = tokens;
@@ -12127,17 +12646,19 @@ class Parser {
         continue;
       }
 
+      const statementToken = this.peek();
+      const statementOffset = statementToken && typeof statementToken.offset === 'number' ? statementToken.offset : null;
       const first = this.parseTerm();
       if (this.peek().typ === 'OpImplies') {
         this.next();
         const second = this.parseTerm();
         this.expectDot();
-        forwardRules.push(this.makeRule(first, second, true));
+        forwardRules.push(annotateSourceOffset(this.makeRule(first, second, true), statementOffset));
       } else if (this.peek().typ === 'OpImpliedBy') {
         this.next();
         const second = this.parseTerm();
         this.expectDot();
-        backwardRules.push(this.makeRule(first, second, false));
+        backwardRules.push(annotateSourceOffset(this.makeRule(first, second, false), statementOffset));
       } else {
         let more;
 
@@ -12155,16 +12676,17 @@ class Parser {
         }
 
         // normalize explicit log:implies / log:impliedBy at top-level
-        for (const tr of more) {
+        for (const tr0 of more) {
+          const tr = annotateSourceOffset(tr0, statementOffset);
           if (isLogImplies(tr.p) && tr.s instanceof GraphTerm && tr.o instanceof GraphTerm) {
-            forwardRules.push(this.makeRule(tr.s, tr.o, true));
+            forwardRules.push(annotateSourceOffset(this.makeRule(tr.s, tr.o, true), statementOffset));
           } else if (isLogImpliedBy(tr.p) && tr.s instanceof GraphTerm && tr.o instanceof GraphTerm) {
-            backwardRules.push(this.makeRule(tr.s, tr.o, false));
+            backwardRules.push(annotateSourceOffset(this.makeRule(tr.s, tr.o, false), statementOffset));
           } 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));
+            logQueries.push(annotateSourceOffset(this.makeRule(tr.s, tr.o, true), statementOffset));
           } else {
             triples.push(tr);
           }
@@ -15105,6 +15627,7 @@ module.exports = {
       if (typeof __entry.materializeRdfLists === "function") __outerSelf.materializeRdfLists = __entry.materializeRdfLists;
       if (typeof __entry.isGroundTriple === "function") __outerSelf.isGroundTriple = __entry.isGroundTriple;
       if (typeof __entry.printExplanation === "function") __outerSelf.printExplanation = __entry.printExplanation;
+      if (typeof __entry.renderProofDocument === "function") __outerSelf.renderProofDocument = __entry.renderProofDocument;
       if (typeof __entry.tripleToN3 === "function") __outerSelf.tripleToN3 = __entry.tripleToN3;
       if (typeof __entry.collectOutputStringsFromFacts === "function") __outerSelf.collectOutputStringsFromFacts = __entry.collectOutputStringsFromFacts;
       if (typeof __entry.prettyPrintQueryTriples === "function") __outerSelf.prettyPrintQueryTriples = __entry.prettyPrintQueryTriples;