eyeling 1.25.5 → 1.26.1

package/index.d.ts

@@ -151,6 +151,7 @@ declare module 'eyeling' {
   }
 
   export interface ReasonOptions {
+    proof?: boolean;
     proofComments?: boolean;
     noProofComments?: boolean;
     args?: string[];

package/index.js

@@ -19,21 +19,24 @@ function reason(opt = {}, input = '') {
 
   const args = [];
 
-  // default: proof comments OFF for API output (machine-friendly)
-  // set { proofComments: true } to keep them
-  const proofCommentsSpecified = typeof opt.proofComments === 'boolean' || typeof opt.noProofComments === 'boolean';
-
-  const proofComments =
-    typeof opt.proofComments === 'boolean'
-      ? opt.proofComments
-      : typeof opt.noProofComments === 'boolean'
-        ? !opt.noProofComments
-        : false;
+  // default: proof output OFF for API output (machine-friendly)
+  // set { proof: true } to include N3 proof explanations.
+  // proofComments/noProofComments are accepted as legacy aliases.
+  const proofSpecified =
+    typeof opt.proof === 'boolean' || typeof opt.proofComments === 'boolean' || typeof opt.noProofComments === 'boolean';
+
+  const proof =
+    typeof opt.proof === 'boolean'
+      ? opt.proof
+      : typeof opt.proofComments === 'boolean'
+        ? opt.proofComments
+        : typeof opt.noProofComments === 'boolean'
+          ? !opt.noProofComments
+          : false;
 
   // Only pass a flag when the caller explicitly asked.
-  // (CLI default is now: no proof comments.)
-  if (proofCommentsSpecified) {
-    if (proofComments) args.push('--proof-comments');
+  if (proofSpecified) {
+    if (proof) args.push('--proof');
     else args.push('--no-proof-comments');
   }
 

package/lib/cli.js

@@ -106,7 +106,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` +
@@ -161,8 +161,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);
   }
 
@@ -212,6 +212,7 @@ function main() {
           label: sourceLabel,
           collectUsedPrefixes: streamMode,
           keepSourceArtifacts: false,
+          sourceLocations: engine.getProofCommentsEnabled(),
           rdf: rdfMode,
         }),
       );
@@ -301,7 +302,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);
 
@@ -366,6 +367,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');

package/lib/engine.js

@@ -25,6 +25,7 @@ const {
   Triple,
   Rule,
   DerivedFact,
+  varsInRule,
   internIri,
   collectBlankLabelsInTriples,
   copyQuotedGraphMetadata,
@@ -42,7 +43,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,
@@ -780,9 +781,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) {
@@ -3154,6 +3157,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
 // ===========================================================================
@@ -3839,7 +3956,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;
 
@@ -3875,11 +3992,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);
@@ -3947,11 +4075,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,
@@ -3995,7 +4131,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,
@@ -4078,6 +4214,7 @@ module.exports = {
   collectLogQueryConclusions,
   forwardChainAndCollectLogQueryConclusions,
   collectOutputStringsFromFacts,
+  renderProofDocument,
   main,
   version,
   N3SyntaxError,

package/lib/entry.js

@@ -32,6 +32,7 @@ module.exports = {
   materializeRdfLists: engine.materializeRdfLists,
   isGroundTriple: engine.isGroundTriple,
   printExplanation: engine.printExplanation,
+  renderProofDocument: engine.renderProofDocument,
   tripleToN3: engine.tripleToN3,
   collectOutputStringsFromFacts: engine.collectOutputStringsFromFacts,
   prettyPrintQueryTriples: engine.prettyPrintQueryTriples,

package/lib/explain.js

@@ -6,7 +6,7 @@
  */
 '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');
@@ -14,6 +14,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('# ----------------------------------------------------------------------');
@@ -111,6 +113,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
   // ===========================================================================
@@ -217,7 +514,7 @@ function makeExplain(deps) {
     return addMarkdownHardBreaks(pairs.map((p) => p.text).join(''));
   }
 
-  return { printExplanation, collectOutputStringsFromFacts };
+  return { printExplanation, renderProofDocument, collectOutputStringsFromFacts };
 }
 
 module.exports = { makeExplain };