eyeprolog 1.5.21 → 1.5.23

package/conformance-report.md

@@ -8,9 +8,9 @@ when this report is generated; it is not inferred from fixture counts.
 
 | Gate | Passed | Total | Status |
 |---|---:|---:|---|
-| WG17 syntax | 372 | 372 | pass |
+| WG17 syntax | 366 | 366 | pass |
 
-The WG17 syntax row executes the vendored 372-case conformity-testing matrix
+The WG17 syntax row executes the vendored 366-case conformity-testing matrix
 against EyeProlog's strict ISO reader/writer. A behavior fix such as operator-token
 spelling therefore changes this report even when no corpus file is added or removed.
 

package/index.d.ts

@@ -12,6 +12,8 @@ export interface EyePrologRunOptions {
   /** Host-supplied goals, executed in order. */
   goals?: Array<string | EyePrologTerm>;
   proof?: boolean;
+  /** Proof detail: abstract keeps library predicates as trusted leaves; expanded opens bundled Prolog library clauses. */
+  proofDetail?: 'abstract' | 'expanded';
   why?: boolean;
   explain?: boolean;
   maxDepth?: number;
@@ -310,9 +312,54 @@ export function hasForwardRules(program: Program): boolean;
 /** Execute EyeProlog `:+/2` rules to closure using an existing solver. */
 export function executeForwardRules(program: Program, solver: Solver, options?: EyePrologForwardRunOptions): EyePrologForwardRunResult;
 export function runQuads(source: string | Program, options?: EyePrologQuadRunOptions): EyePrologQuadRunResult;
-export function whyProof(program: Program, goal: EyePrologTerm, options?: EyePrologRunOptions): { ok: boolean; text: string };
+export interface EyePrologProofMethod {
+  type: 'source' | 'builtin' | 'library' | 'conjunction';
+  kind?: 'fact' | 'rule';
+  filename?: string;
+  clause?: number;
+  name?: string;
+  arity?: number;
+}
+
+export interface EyePrologProofNode {
+  goal: string;
+  method: EyePrologProofMethod;
+  bindings: Array<{ name: string; value: string }>;
+  children: EyePrologProofNode[];
+}
+
+export interface EyePrologProofCertificate {
+  version: 1;
+  detail: 'abstract' | 'expanded';
+  answer: string;
+  proof: EyePrologProofNode;
+}
+
+export interface EyePrologProofResult {
+  ok: boolean;
+  certificate: EyePrologProofCertificate | null;
+  text: string;
+}
+
+export interface EyePrologProofTrustBoundary {
+  type: 'builtin' | 'library';
+  name: string;
+  arity: number;
+  goal: string;
+}
+
+export interface EyePrologProofVerification {
+  ok: boolean;
+  error: string | null;
+  trusted: EyePrologProofTrustBoundary[];
+}
+
+export function proofCertificate(program: Program, goal: EyePrologTerm, options?: EyePrologRunOptions): EyePrologProofResult;
+export function proofCertificatesFromText(text: string, program: Program): EyePrologProofCertificate[];
+export function verifyProof(program: Program, certificate: EyePrologProofCertificate | EyePrologProofResult, options?: EyePrologRunOptions): EyePrologProofVerification;
+export function whyProof(program: Program, goal: EyePrologTerm, options?: EyePrologRunOptions): EyePrologProofResult;
 export function whyNoProof(goal: EyePrologTerm): string;
-export function explainProof(program: Program, goal: EyePrologTerm, options?: EyePrologRunOptions): { ok: boolean; text: string };
+export function explainProof(program: Program, goal: EyePrologTerm, options?: EyePrologRunOptions): EyePrologProofResult;
 
 declare const eyeprolog: {
   VAR: typeof VAR;
@@ -386,6 +433,9 @@ declare const eyeprolog: {
   hasForwardRules: typeof hasForwardRules;
   executeForwardRules: typeof executeForwardRules;
   runQuads: typeof runQuads;
+  proofCertificate: typeof proofCertificate;
+  proofCertificatesFromText: typeof proofCertificatesFromText;
+  verifyProof: typeof verifyProof;
   whyProof: typeof whyProof;
   whyNoProof: typeof whyNoProof;
   explainProof: typeof explainProof;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.5.21",
+  "version": "1.5.23",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",

package/src/ARCHITECTURE.md

@@ -21,6 +21,12 @@ higher-level frontends.
 5. **Frontends/tools** — `execute.js`, `repl.js`, `cli.js`, `quads.js`,
    `explain.js`, and the playground worker.
 
+`explain.js` owns both proof construction and proof-certificate verification.
+Verification walks the supplied certificate and checks source-clause steps against
+the parsed `Program`; it does not call the solver to rediscover the proof.
+Built-in and abstract library nodes are explicit trust boundaries, while expanded
+proofs expose bundled Prolog-library clauses as ordinary source steps.
+
 `iso.js` and `program.js` remain facade modules for their existing exports, so
 this refactor does not change the public JavaScript API.
 

package/src/cli.js

@@ -25,6 +25,8 @@ export async function main(argv) {
   const options = {
     files: [],
     proof: false,
+    proofDetail: 'abstract',
+    verifyProof: null,
     quads: false,
     stats: false,
     isoStrict: false,
@@ -47,6 +49,15 @@ export async function main(argv) {
       return;
     } else if (!endOptions && (arg === '--proof' || arg === '-p')) {
       options.proof = true;
+    } else if (!endOptions && arg === '--proof-detail') {
+      const detail = argv[++i];
+      if (detail !== 'abstract' && detail !== 'expanded') throw new Error('--proof-detail requires abstract or expanded');
+      options.proof = true;
+      options.proofDetail = detail;
+    } else if (!endOptions && arg === '--verify-proof') {
+      const file = argv[++i];
+      if (file == null) throw new Error('--verify-proof requires a file');
+      options.verifyProof = file;
     } else if (!endOptions && (arg === '--quads' || arg === '-q')) {
       options.quads = true;
     } else if (!endOptions && (arg === '--stats' || arg === '-s')) {
@@ -94,9 +105,18 @@ export async function main(argv) {
   if (options.isoStrict && options.quads) {
     throw new Error('--iso-strict cannot be combined with --quads');
   }
+  if (options.verifyProof != null && options.quads) {
+    throw new Error('--verify-proof cannot be combined with --quads');
+  }
+  if (options.verifyProof != null && options.proof) {
+    throw new Error('--verify-proof cannot be combined with --proof or --proof-detail');
+  }
+  if (options.verifyProof != null && options.goals.length > 0) {
+    throw new Error('--verify-proof cannot be combined with --goal');
+  }
 
   if (options.isoStrict && options.files.length === 0 && options.goals.length === 0 &&
-      !options.proof && !options.stats && !options.warnings) {
+      options.verifyProof == null && !options.proof && !options.stats && !options.warnings) {
     const engine = await loadEngine();
     const { runRepl } = await import('./repl.js');
     const exitCode = await runRepl(engine, {
@@ -134,7 +154,7 @@ export async function main(argv) {
     }
   }
 
-  if (options.goals.length === 0 && !options.quads) {
+  if (options.goals.length === 0 && !options.quads && options.verifyProof == null) {
     for (const source of sourceParts) options.goals.push(...goalsFromSource(source.text));
   }
 
@@ -150,7 +170,7 @@ export async function main(argv) {
 
   const engine = await loadEngine();
   let program = engine.Program.parseSources(sourceParts, {
-    sourceMetadata: options.proof || options.isoStrict,
+    sourceMetadata: options.proof || options.verifyProof != null || options.isoStrict,
     isoStrict: options.isoStrict,
     autoload: options.autoload,
     autoloadGoals: options.goals,
@@ -164,6 +184,20 @@ export async function main(argv) {
     return;
   }
 
+  if (options.verifyProof != null) {
+    const explanation = await loadExplanation();
+    const proofText = await fs.readFile(options.verifyProof, 'utf8');
+    const certificates = explanation.proofCertificatesFromText(proofText, program);
+    if (certificates.length === 0) throw new Error(`no why/2 proof certificate found in ${options.verifyProof}`);
+    const registry = options.isoStrict ? engine.getStrictIsoRegistry() : engine.getEyePrologRegistry();
+    for (let i = 0; i < certificates.length; i++) {
+      const checked = explanation.verifyProof(program, certificates[i], { registry });
+      if (!checked.ok) throw new Error(`proof certificate ${i + 1} failed verification: ${checked.error}`);
+    }
+    process.stdout.write(`verified ${certificates.length} proof certificate${certificates.length === 1 ? '' : 's'}.\n`);
+    return;
+  }
+
   if (!options.quads || options.goals.length > 0) {
     if (options.goals.length === 0 && !options.isoStrict && engine.hasForwardRules(program)) {
       await runForwardDefault(engine, program, options);
@@ -244,7 +278,7 @@ async function runDefault(engine, program, options) {
     const { haltCode } = engine.executeGoals(program, solver, goals, {
       onAnswer: (line, resolved) => {
         process.stdout.write(line);
-        if (options.proof) writeExplanation(explanation, program, resolved, registry);
+        if (options.proof) writeExplanation(explanation, program, resolved, registry, options);
       },
     });
     if (haltCode != null) process.exitCode = haltCode;
@@ -253,8 +287,8 @@ async function runDefault(engine, program, options) {
   }
 }
 
-function writeExplanation(explanation, program, resolved, registry) {
-  const proof = explanation.whyProof(program, resolved, { registry });
+function writeExplanation(explanation, program, resolved, registry, options = {}) {
+  const proof = explanation.whyProof(program, resolved, { registry, proofDetail: options?.proofDetail ?? 'abstract' });
   process.stdout.write(proof.text);
   if (!proof.ok) process.stdout.write(explanation.whyNoProof(resolved));
 }
@@ -276,6 +310,8 @@ Input:
 Options:
   -h, --help            Show this help text and exit.
   -p, --proof           Enable proof explanations.
+  --proof-detail mode   Use abstract or expanded proof detail (implies --proof).
+  --verify-proof file   Verify why/2 proof certificates against the input program.
   -q, --quads           Run embedded quad tests and fail if any do not hold.
   -s, --stats           Print solver and memory statistics to stderr after execution.
   --iso-strict          Use ISO/IEC 13211-1 core + Corrigenda 1-3 only;

package/src/explain.js

@@ -2,19 +2,34 @@
 // The explanation printer replays a successful goal against the program and emits
 // ordinary EyeProlog facts with nested proof terms.  Explanations are therefore both
 // human-readable and machine-readable.
-import { ATOM, COMPOUND, Env, Term, VAR, deref, flattenConjunction, freshTerm, termToString, unify, variantTerms } from './term.js';
+import { ATOM, COMPOUND, Env, Term, VAR, deref, flattenConjunction, freshTerm, properListItems, termToString, unify, variantTerms } from './term.js';
 import { selectClauseCandidates } from './program.js';
+import { parseGoalText, parseProgramText } from './parser.js';
 import { getEyePrologRegistry } from './standard-library.js';
 import { Solver, nextFreshId } from './solver.js';
 
-export function whyProof(program, goal, options = {}) {
+let verifyFreshCounter = 0;
+
+export function proofCertificate(program, goal, options = {}) {
   const maxDepth = options.maxDepth ?? 256;
   const registry = options.registry ?? getEyePrologRegistry();
   const env = options.env ?? new Env();
-  for (const proof of proveGoalAll(program, goal, env, 0, maxDepth, registry, [])) {
-    return { ok: true, text: renderWhyFacts(goal, proof.node, proof.env) };
+  const detail = normalizeProofDetail(options.proofDetail ?? 'abstract');
+  for (const proof of proveGoalAll(program, goal, env, 0, maxDepth, registry, [], detail)) {
+    const answer = resolveForProof(goal, proof.env);
+    const certificate = {
+      version: 1,
+      detail,
+      answer: termToString(answer, new Env(), true),
+      proof: certificateNode(proof.node),
+    };
+    return { ok: true, certificate, text: renderWhyFacts(goal, proof.node, proof.env) };
   }
-  return { ok: false, text: '' };
+  return { ok: false, certificate: null, text: '' };
+}
+
+export function whyProof(program, goal, options = {}) {
+  return proofCertificate(program, goal, options);
 }
 
 export function whyNoProof(goal) {
@@ -26,11 +41,11 @@ export function explainProof(program, goal, options = {}) {
   return whyProof(program, goal, options);
 }
 
-function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active) {
+function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active, detail) {
   if (depth > maxDepth) return;
 
   if (goal.type === COMPOUND && goal.name === ',' && goal.arity === 2) {
-    for (const proved of proveGoalsAll(program, flattenConjunction(goal), env, depth + 1, maxDepth, registry, active)) {
+    for (const proved of proveGoalsAll(program, flattenConjunction(goal), env, depth + 1, maxDepth, registry, active, detail)) {
       yield {
         env: proved.env,
         node: {
@@ -58,7 +73,7 @@ function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active) {
           sourceHead: resolveForProof(goal, proofEnv),
           sourceBody: [],
           bindings: [],
-          children: builtinChildren(program, goal, proofEnv, depth + 1, maxDepth, registry, active),
+          children: builtinChildren(program, goal, proofEnv, depth + 1, maxDepth, registry, active, detail),
         },
       };
     }
@@ -74,7 +89,7 @@ function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active) {
   // a standard Prolog module. The implementation remains
   // ordinary clauses, but explanations collapse its private helper expansion
   // behind an explicit library(Name, Arity) boundary.
-  if (group.module !== 'user' && program.modules.get(group.module)?.filename?.startsWith('src/lib/')) {
+  if (detail !== 'expanded' && group.module !== 'user' && program.modules.get(group.module)?.filename?.startsWith('src/lib/')) {
     const solver = new Solver(program, { registry });
     for (const next of solver.solve([goal], env.clone(), 0)) {
       const proofEnv = next.clone ? next.clone() : next;
@@ -128,7 +143,7 @@ function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active) {
       let activePushed = true;
       active.push({ goal, env });
       try {
-        for (const proved of proveGoalsAll(program, freshBody, next, depth + 1, maxDepth, registry, active)) {
+        for (const proved of proveGoalsAll(program, freshBody, next, depth + 1, maxDepth, registry, active, detail)) {
           active.pop();
           activePushed = false;
           yield {
@@ -160,7 +175,7 @@ function clauseCandidateAt(candidate, index) {
   return Array.isArray(candidate) ? candidate[index] : index === 0 ? candidate : undefined;
 }
 
-function* proveGoalsAll(program, goals, env, depth, maxDepth, registry, active) {
+function* proveGoalsAll(program, goals, env, depth, maxDepth, registry, active, detail) {
   if (goals.length === 0) {
     yield { env: env.clone(), children: [] };
     return;
@@ -170,8 +185,8 @@ function* proveGoalsAll(program, goals, env, depth, maxDepth, registry, active)
   const goal = goals[selectedIndex];
   const rest = selectedIndex === 0 ? goals.slice(1) : [...goals.slice(0, selectedIndex), ...goals.slice(selectedIndex + 1)];
 
-  for (const proved of proveGoalAll(program, goal, env, depth, maxDepth, registry, active)) {
-    for (const tail of proveGoalsAll(program, rest, proved.env, depth, maxDepth, registry, active)) {
+  for (const proved of proveGoalAll(program, goal, env, depth, maxDepth, registry, active, detail)) {
+    for (const tail of proveGoalsAll(program, rest, proved.env, depth, maxDepth, registry, active, detail)) {
       const children = tail.children.slice();
       children.splice(selectedIndex, 0, proved.node);
       yield { env: tail.env, children };
@@ -212,10 +227,10 @@ function selectReadyDeterministicBuiltin(goals, env, registry) {
   return 0;
 }
 
-function builtinChildren(program, goal, env, depth, maxDepth, registry, active) {
+function builtinChildren(program, goal, env, depth, maxDepth, registry, active, detail) {
   if (goal.type !== COMPOUND) return [];
   if (goal.name === 'once' && goal.arity === 1) {
-    for (const proved of proveGoalAll(program, goal.args[0], env.clone(), depth, maxDepth, registry, active)) return [proved.node];
+    for (const proved of proveGoalAll(program, goal.args[0], env.clone(), depth, maxDepth, registry, active, detail)) return [proved.node];
   }
   return [];
 }
@@ -250,6 +265,291 @@ function libraryMethod(goal) {
   };
 }
 
+function normalizeProofDetail(value) {
+  if (value === 'abstract' || value === 'expanded') return value;
+  throw new Error(`unknown proof detail: ${value}`);
+}
+
+function certificateNode(node) {
+  return {
+    goal: termToString(node.goal, new Env(), true),
+    method: certificateMethod(node.method),
+    bindings: node.bindings.map((binding) => ({
+      name: String(binding.name),
+      value: termToString(binding.value, new Env(), true),
+    })),
+    children: node.children.map(certificateNode),
+  };
+}
+
+function certificateMethod(method) {
+  if (typeof method === 'string') return { type: method };
+  if (!method || typeof method !== 'object') return { type: String(method) };
+  return { ...method };
+}
+
+export function proofCertificatesFromText(text, program) {
+  const clauses = parseProgramText(String(text), {
+    doubleQuotes: program.doubleQuotes ?? 'chars',
+    sourceMetadata: false,
+  });
+  const certificates = [];
+  for (const clause of clauses) {
+    if (!clause?.head || clause.body?.length !== 0 || clause.head.type !== COMPOUND ||
+        clause.head.name !== 'why' || clause.head.arity !== 2) continue;
+    const proof = certificateNodeFromTerm(clause.head.args[1]);
+    if (!proof) continue;
+    certificates.push({
+      version: 1,
+      detail: containsExpandedLibrarySource(proof) ? 'expanded' : 'abstract',
+      answer: termToString(clause.head.args[0], new Env(), true),
+      proof,
+    });
+  }
+  return certificates;
+}
+
+function certificateNodeFromTerm(term) {
+  if (term.type !== COMPOUND || term.name !== 'proof') return null;
+  const fields = term.args;
+  if (fields.length < 2) return null;
+  const goalField = fields[0];
+  const byField = fields[1];
+  if (goalField.type !== COMPOUND || goalField.name !== 'goal' || goalField.arity !== 1) return null;
+  if (byField.type !== COMPOUND || byField.name !== 'by' || byField.arity !== 1) return null;
+  const node = {
+    goal: termToString(goalField.args[0], new Env(), true),
+    method: certificateMethodFromTerm(byField.args[0]),
+    bindings: [],
+    children: [],
+  };
+  if (!node.method) return null;
+  for (let i = 2; i < fields.length; i++) {
+    const field = fields[i];
+    if (field.type !== COMPOUND) return null;
+    if (field.name === 'bindings' && field.arity === 1) {
+      const items = properListItems(field.args[0], new Env());
+      if (items == null) return null;
+      node.bindings = items.map((item) => {
+        if (item.type !== COMPOUND || item.name !== 'binding' || item.arity !== 2) throw new Error('malformed certificate binding');
+        return { name: certificateText(item.args[0]), value: termToString(item.args[1], new Env(), true) };
+      });
+    } else if (field.name === 'uses' && field.arity === 1) {
+      const items = properListItems(field.args[0], new Env());
+      if (items == null) return null;
+      node.children = items.map(certificateNodeFromTerm);
+      if (node.children.some((child) => child == null)) return null;
+    } else {
+      return null;
+    }
+  }
+  return node;
+}
+
+function certificateMethodFromTerm(term) {
+  if (term.type === ATOM && term.name === 'conjunction') return { type: 'conjunction' };
+  if (term.type !== COMPOUND) return null;
+  if ((term.name === 'fact' || term.name === 'rule') && term.arity === 2) {
+    const clause = term.args[1];
+    if (clause.type !== COMPOUND || clause.name !== 'clause' || clause.arity !== 1) return null;
+    return { type: 'source', kind: term.name, filename: certificateText(term.args[0]), clause: Number(clause.args[0].name) };
+  }
+  if ((term.name === 'builtin' || term.name === 'library') && term.arity === 2) {
+    return { type: term.name, name: String(term.args[0].name), arity: Number(term.args[1].name) };
+  }
+  return null;
+}
+
+function certificateText(term) {
+  if (term.type === ATOM || term.type === 'string') return String(term.name);
+  const items = properListItems(term, new Env());
+  if (items != null && items.every((item) => item.type === ATOM && String(item.name).length === 1)) {
+    return items.map((item) => String(item.name)).join('');
+  }
+  if (items != null && items.every((item) => item.type === 'number' && /^\d+$/.test(String(item.name)))) {
+    const codes = items.map((item) => Number(item.name));
+    if (codes.every((code) => Number.isInteger(code) && code >= 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff))) {
+      return String.fromCodePoint(...codes);
+    }
+  }
+  throw new Error('expected certificate text');
+}
+
+function containsLibraryBoundary(node) {
+  if (node.method?.type === 'library') return true;
+  return node.children.some(containsLibraryBoundary);
+}
+
+function containsExpandedLibrarySource(node) {
+  if (node.method?.type === 'source' && String(node.method.filename ?? '').startsWith('src/lib/')) return true;
+  return node.children.some(containsExpandedLibrarySource);
+}
+
+export function verifyProof(program, input, options = {}) {
+  const certificate = input?.certificate ?? input;
+  try {
+    if (!certificate || certificate.version !== 1 || typeof certificate.answer !== 'string' || !certificate.proof ||
+        (certificate.detail !== 'abstract' && certificate.detail !== 'expanded')) {
+      throw new Error('invalid proof certificate');
+    }
+    if (certificate.detail === 'abstract' && containsExpandedLibrarySource(certificate.proof)) {
+      throw new Error('abstract proof certificate contains expanded library source');
+    }
+    if (certificate.detail === 'expanded' && containsLibraryBoundary(certificate.proof)) {
+      throw new Error('expanded proof certificate contains an abstract library boundary');
+    }
+    const registry = options.registry ?? getEyePrologRegistry();
+    const answer = parseCertificateTerm(certificate.answer, program);
+    const rootGoal = parseCertificateTerm(certificate.proof.goal, program);
+    const answerEnv = new Env();
+    if (!unify(answer, rootGoal, answerEnv)) throw new Error('certificate answer does not match root goal');
+    verifyCertificateNode(program, certificate.proof, rootGoal, registry, options, new Env());
+    return { ok: true, error: null, trusted: collectTrustedBoundaries(certificate.proof) };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error), trusted: [] };
+  }
+}
+
+function collectTrustedBoundaries(node, out = []) {
+  if (node.method?.type === 'builtin' || node.method?.type === 'library') {
+    out.push({
+      type: node.method.type,
+      name: String(node.method.name),
+      arity: Number(node.method.arity),
+      goal: String(node.goal),
+    });
+  }
+  for (const child of node.children) collectTrustedBoundaries(child, out);
+  return out;
+}
+
+function parseCertificateTerm(text, program) {
+  return parseGoalText(String(text), { doubleQuotes: program.doubleQuotes ?? 'chars' });
+}
+
+function verifyCertificateNode(program, node, expectedGoal, registry, options, inheritedEnv) {
+  if (!node || typeof node.goal !== 'string' || !node.method || !Array.isArray(node.children) || !Array.isArray(node.bindings)) {
+    throw new Error('malformed proof node');
+  }
+  const nodeGoal = parseCertificateTerm(node.goal, program);
+  if (!unify(expectedGoal, nodeGoal, inheritedEnv)) throw new Error(`proof goal mismatch: ${node.goal}`);
+  const method = node.method;
+
+  if (method.type === 'conjunction') {
+    if (nodeGoal.type !== COMPOUND || nodeGoal.name !== ',' || nodeGoal.arity !== 2) throw new Error('invalid conjunction proof');
+    const goals = flattenConjunction(nodeGoal);
+    if (goals.length !== node.children.length) throw new Error('conjunction child count mismatch');
+    for (let i = 0; i < goals.length; i++) {
+      const childGoal = parseCertificateTerm(node.children[i].goal, program);
+      if (!unify(goals[i], childGoal, inheritedEnv)) throw new Error(`conjunction child ${i + 1} does not match`);
+      verifyCertificateNode(program, node.children[i], childGoal, registry, options, new Env());
+    }
+    if (node.bindings.length !== 0) throw new Error('conjunction proof must not carry clause bindings');
+    return;
+  }
+
+  if (method.type === 'builtin') {
+    const name = nodeGoal.type === COMPOUND || nodeGoal.type === ATOM ? nodeGoal.name : null;
+    const arity = nodeGoal.type === COMPOUND ? nodeGoal.arity : 0;
+    if (method.name !== name || method.arity !== arity || registry.get(name, arity) == null) {
+      throw new Error(`untrusted builtin boundary: ${method.name}/${method.arity}`);
+    }
+    if (node.bindings.length !== 0) throw new Error('builtin proof must not carry clause bindings');
+    if (name === 'once' && arity === 1) {
+      if (node.children.length !== 1) throw new Error('once/1 proof requires exactly one child');
+      const childGoal = parseCertificateTerm(node.children[0].goal, program);
+      const innerEnv = new Env();
+      if (!unify(nodeGoal.args[0], childGoal, innerEnv)) throw new Error('once/1 child does not match called goal');
+      verifyCertificateNode(program, node.children[0], childGoal, registry, options, new Env());
+    } else if (node.children.length !== 0) {
+      throw new Error(`unexpected children for builtin ${name}/${arity}`);
+    }
+    return;
+  }
+
+  if (method.type === 'library') {
+    const name = nodeGoal.type === COMPOUND || nodeGoal.type === ATOM ? nodeGoal.name : null;
+    const arity = nodeGoal.type === COMPOUND ? nodeGoal.arity : 0;
+    if (method.name !== name || method.arity !== arity) throw new Error('library boundary does not match goal');
+    const group = findLibraryGroup(program, name, arity);
+    if (!group) throw new Error(`untrusted library boundary: ${name}/${arity}`);
+    if (node.children.length !== 0 || node.bindings.length !== 0) throw new Error('abstract library proof must be a leaf');
+    return;
+  }
+
+  if (method.type === 'source') {
+    verifySourceNode(program, node, nodeGoal, registry, options);
+    return;
+  }
+
+  throw new Error(`unknown proof method: ${method.type}`);
+}
+
+function findLibraryGroup(program, name, arity) {
+  for (const group of program.groups.values()) {
+    if (group.name !== name || group.arity !== arity || group.module === 'user') continue;
+    if (program.modules.get(group.module)?.filename?.startsWith('src/lib/')) return group;
+  }
+  return null;
+}
+
+function verifySourceNode(program, node, nodeGoal, registry, options) {
+  const method = node.method;
+  const candidates = program.clauses.filter((clause) => {
+    const source = clause.source ?? {};
+    const filename = source.filename ?? '<input>';
+    const clauseNumber = source.clause ?? ((clause.index ?? 0) + 1);
+    return filename === method.filename && clauseNumber === method.clause;
+  });
+  if (candidates.length === 0) throw new Error(`source clause not found: ${method.filename}:${method.clause}`);
+
+  for (const clause of candidates) {
+    const kind = clause.body.length === 0 ? 'fact' : 'rule';
+    if (method.kind !== kind) continue;
+    const id = `verify${++verifyFreshCounter}`;
+    const variables = new Map();
+    const head = freshTerm(clause.head, id, variables);
+    const body = clause.body.map((term) => freshTerm(term, id, variables));
+    const env = new Env();
+    if (!unify(head, nodeGoal, env)) continue;
+    if (body.length !== node.children.length) continue;
+
+    let valid = true;
+    for (let i = 0; i < body.length; i++) {
+      try {
+        const childGoal = parseCertificateTerm(node.children[i].goal, program);
+        if (!unify(body[i], childGoal, env)) { valid = false; break; }
+        verifyCertificateNode(program, node.children[i], childGoal, registry, options, new Env());
+      } catch {
+        valid = false;
+        break;
+      }
+    }
+    if (!valid) continue;
+    if (!verifyBindings(node.bindings, variables, env, program)) continue;
+    return;
+  }
+  throw new Error(`source proof does not validate: ${node.goal}`);
+}
+
+function verifyBindings(bindings, variables, env, program) {
+  const expected = new Map();
+  for (const [name, fresh] of variables.entries()) {
+    const resolved = deref(fresh, env);
+    if (resolved.type !== VAR) expected.set(name, resolved);
+  }
+  if (bindings.length !== expected.size) return false;
+  for (const binding of bindings) {
+    if (!binding || typeof binding.name !== 'string' || typeof binding.value !== 'string') return false;
+    const resolved = expected.get(binding.name);
+    if (!resolved) return false;
+    const value = parseCertificateTerm(binding.value, program);
+    const check = new Env();
+    if (!unify(resolveForProof(resolved, env), value, check)) return false;
+  }
+  return true;
+}
+
 function renderMethodTerm(method) {
   if (method && method.type === 'source') return `${method.kind}(${quoteString(method.filename)}, clause(${method.clause}))`;
   if (method && method.type === 'builtin') return `builtin(${quoteAtomText(method.name)}, ${method.arity})`;

package/src/index.js

@@ -79,7 +79,7 @@ export function run(source, options = {}) {
     ({ haltCode } = executeForwardRules(program, solver, {
       onAnswer: (line, resolved) => {
         output.push(line);
-        if (includeWhy) appendExplanation(output, program, resolved, runOptions.registry);
+        if (includeWhy) appendExplanation(output, program, resolved, runOptions.registry, options.proofDetail);
       },
       onFuse: (line) => output.push(line),
       onDiagnostic: (line) => {
@@ -91,15 +91,15 @@ export function run(source, options = {}) {
     ({ haltCode } = executeGoals(program, solver, goals, {
       onAnswer: (line, resolved) => {
         output.push(line);
-        if (includeWhy) appendExplanation(output, program, resolved, runOptions.registry);
+        if (includeWhy) appendExplanation(output, program, resolved, runOptions.registry, options.proofDetail);
       },
     }));
   }
   return { stdout: output.join(''), stats: solver.stats, haltCode };
 }
 
-function appendExplanation(output, program, resolved, registry) {
-  const proof = whyProof(program, resolved, { registry });
+function appendExplanation(output, program, resolved, registry, proofDetail = 'abstract') {
+  const proof = whyProof(program, resolved, { registry, proofDetail });
   output.push(proof.text);
   if (!proof.ok) output.push(whyNoProof(resolved));
 }