@factoidal/core 0.12.0 → 0.14.0

package/index.d.ts

@@ -184,7 +184,8 @@ export interface ParseDiagnostic {
    * 'unterminated-string', 'bad-literal', 'bad-blank-node',
    * 'bad-prefixed-name', 'bad-directive', 'bad-graph-name', 'rdf12-syntax',
    * 'unclosed-group', 'nesting-limit', 'unexpected-token', 'internal' or
-   * 'too-many-errors'.
+   * 'too-many-errors'. A warning (`Dataset.warnings`) has the class
+   * 'ill-formed-language-tag'.
    */
   class: string;
 }
@@ -250,6 +251,13 @@ export class Dataset implements Iterable<Quad> {
   readonly prefixes: Record<string, string>;
   /** Diagnostics of a `{lenient:true}` parse; else empty. */
   readonly diagnostics: ParseDiagnostic[];
+  /**
+   * Warnings of the parse of text: one per language tag that is not
+   * well-formed under BCP 47 section 2.2.9 (class 'ill-formed-language-tag',
+   * the position of the tag's first character). The reader keeps the triple
+   * and the writers write the tag unchanged. Empty otherwise.
+   */
+  readonly warnings: ParseDiagnostic[];
   /** The parse format tag, when the data was read from text. */
   readonly format: string | undefined;
   /** True when `format` was inferred because the caller gave none. */
@@ -627,6 +635,159 @@ export function coreRdfsCheck(
   options?: { format?: DataFormat; baseIRI?: string }
 ): Promise<{ ok: boolean; fragment: boolean }>;
 
+/** The evidence bundle and verdict of explain(). */
+export interface ExplainResult {
+  profile: 'rdfs';
+  /** true: the checker accepted `bundle`; the sources RDFS-entail the description. */
+  entailed: boolean;
+  bundle: null | {
+    sources: string;
+    description: string;
+    mapping: Array<{ bnode: string; term: string }>;
+    steps: Array<{ rule: string; conclusion: string; premises: number[] }>;
+    support: number[];
+  };
+  /** Named assumptions that `entailed: false` relies on. */
+  assumptions: string[];
+  rejection:
+    | null
+    | { kind: 'noMatch'; index: number; triple: string }
+    | { kind: 'noJointMapping' }
+    | { kind: 'checkerRefused'; reason: string };
+  entailedMeans: string;
+}
+
+/**
+ * Is `description` (blank nodes shared across its triples) RDFS-entailed by
+ * `sources`? Full engine only; the description is default-graph only. Text
+ * inputs are Turtle unless `format` says otherwise.
+ * https://github.com/danbri/factoidal/issues/1002
+ */
+export function explain(
+  sources: DataInput,
+  description: DataInput,
+  options?: {
+    profile?: 'rdfs';
+    format?: DataFormat;
+    baseIRI?: string;
+    sourcesFormat?: DataFormat;
+    descriptionFormat?: DataFormat;
+  }
+): Promise<ExplainResult>;
+
+/**
+ * One registered stage, as the engine's op stageList reads it from the Lean
+ * registry (L4Factoidal.Dataflow.registry).
+ * https://github.com/danbri/factoidal/issues/1002
+ */
+export interface StageInfo {
+  /** The stage declaration relative to L4Factoidal.Dataflow (or L4Factoidal); the area when there is none. */
+  name: string;
+  /** The full Lean declaration name, or null (status tested or missing). */
+  declaration: string | null;
+  area: string;
+  dir: string;
+  /** The interface type of the declaration (Stage, RdfReader, SoundReasoner, ...), or null. */
+  kind: string | null;
+  wireIn: string;
+  wireOut: string;
+  status: 'proved' | 'tested' | 'assumed' | 'missing';
+  /** The contract declaration (full Lean name), or null. */
+  contract: string | null;
+  theorems: string[];
+  /** The named assumptions of the stage (full Lean names). */
+  assumptions: string[];
+  tests: string[];
+  note: string;
+  /** false exactly when status is 'missing': such a stage does not run. */
+  runnable: boolean;
+  /** true when this package has a function that runs the stage as a node. */
+  bound: boolean;
+}
+
+/** One evidence record: the node that ran and what it produced. */
+export interface EvidenceRecord {
+  stage: string;
+  status: StageInfo['status'];
+  contract: string | null;
+  assumptions: string[];
+  /** true iff `status` is 'proved'. */
+  checked: boolean;
+  /** true on a step that ran under run()'s `unchecked` opt-in and is not checked. */
+  unchecked?: true;
+  /** With `unchecked`: the status and named assumptions, or 'no contract' for a missing stage. */
+  reason?: string;
+  /** The node's own output beside the graph: the explain result, the SHACL report, the written text, ... */
+  artefact: unknown;
+}
+
+/** The value on a wire. */
+export interface Wire<G = unknown> {
+  graph: G;
+  evidence: EvidenceRecord[];
+}
+
+/** A node: a registered stage with its parameters. */
+export interface FactoidalNode {
+  readonly stage: string;
+  readonly kind: string | null;
+  readonly status: StageInfo['status'];
+  readonly contract: string | null;
+  readonly assumptions: readonly string[];
+  readonly wireIn: string;
+  readonly wireOut: string;
+  readonly runnable: boolean;
+  readonly bound: boolean;
+  readonly params: Readonly<Record<string, unknown>>;
+}
+
+/** A pipeline: nodes in order; `assumptions` is the union of theirs. */
+export interface Pipeline {
+  readonly nodes: readonly FactoidalNode[];
+  readonly assumptions: readonly string[];
+}
+
+/** The result of run(): the last graph, one record per node, the assumption union. */
+export interface RunResult<G = unknown> extends Wire<G> {
+  assumptions: string[];
+  /** true iff every evidence record is checked (status 'proved'). */
+  proved: boolean;
+  /** The stage names of the records that are not checked. */
+  uncheckedSteps: string[];
+}
+
+/** Options of run(). */
+export interface RunOptions {
+  /**
+   * Let stages that are not 'proved' run, and 'missing' stages too when the
+   * package has a runner for them. Each such step's record says so, and the
+   * result's `proved` is false. A stage with no runner still rejects (op.unknown).
+   */
+  unchecked?: boolean;
+}
+
+/** The engine's stage list (op stageList, full engine). */
+export function stages(): Promise<StageInfo[]>;
+
+/**
+ * A node for the registered stage `name`. `params` are passed to the
+ * package function that runs it: reader options; `{shapes}` for
+ * shaclValidator; `{query}` for shippedEvaluator; `{description}` for
+ * rdfsExplainGraphStage. An unknown name rejects with a FactoidalError.
+ */
+export function node(name: string, params?: Record<string, unknown>): Promise<FactoidalNode>;
+
+/** Compose nodes and pipelines left to right. */
+export function pipe(...nodes: Array<FactoidalNode | Pipeline>): Pipeline;
+
+/**
+ * Run a node or pipeline on `input` (a Wire, or the graph: text for a
+ * reader, else a Dataset or data input). Rejects before any node runs when
+ * a node's stage has status 'missing' (unless `options.unchecked`) or has
+ * no package function.
+ */
+export function run(pipeline: FactoidalNode | Pipeline, input: unknown, options?: RunOptions): Promise<RunResult>;
+
 /** Literature-name alias for coreRdfsClosure (ρdf). */
 export function rhoDfClosure(
   data: DataInput,
@@ -680,11 +841,18 @@ export function tableauDlInconsistent(
 ): Promise<{ inconsistent: boolean; rlAlone: boolean }>;
 
 /**
- * OWL DL consistency verdict via the clash-detecting tableau
- * (L4Factoidal/OWL/Refute.lean) over the OWL RL closure.
- * Default graph only. `consistent` is three-valued: `false` (a clash on
- * every branch), `true` (a model built), or `null` -- a budget-out, with
- * `reason` naming the fuel cap (never a silent false).
+ * Checked consistency for the original default graph in a restricted
+ * OWL fragment (named subclass/class assertions, Thing/Nothing,
+ * owl:someValuesFrom restrictions as a superclass or a class assertion,
+ * owl:TransitiveProperty, sameAs/differentFrom, declarations, annotations
+ * and annotated axioms).
+ * true requires a checked finite model and has no `reason`; false requires
+ * an accepted refutation certificate; null means unsupported-syntax,
+ * budget-out or incomplete-search. Named graphs do not contribute axioms.
+ * RDF 1.2 terms are refused. Other restrictions, object/data property
+ * axioms, imports and equivalentClass are unsupported. `fuel` bounds the
+ * model search and the certificate checker (default 20000 rounds).
+ * This is not complete OWL DL support.
  */
 export function owlIsConsistent(
   data: DataInput,
@@ -694,8 +862,15 @@ export function owlIsConsistent(
 /**
  * OWL entailment check: does `premise` entail `conclusion`? Two paths: `via: "closure"` (the conclusion is in the OWL-RL
  * closure of the premise) or `via: "refutation"` (the negated
- * conclusion is refuted on every goal). Default graph only. `entailed` is `true`, `false`, or `null`
- * (a refutation budget-out, with `reason` naming the cap).
+ * conclusion is refuted on every goal). Default graph only. The current
+ * implementation returns `true` for those positive results and `null`
+ * when it cannot establish entailment. `reason` distinguishes budget-out,
+ * incomplete-search, unsupported-conclusion and unsupported-punning.
+ * `false` (via `refutation`, reason `countermodel: ...`) requires a checked
+ * finite model of the premise in which the conclusion fails; both graphs
+ * must be in the fragment that `owlIsConsistent` reads.
+ * The punning refusal is limited; full OWL DL recognition and universal
+ * Direct Semantics soundness are not established by this API.
  */
 export function owlEntails(
   premise: DataInput,
@@ -887,6 +1062,42 @@ export class Store {
  */
 export function openStore(source: string | StoreReader, options?: OpenStoreOptions): Promise<Store>;
 
+/** A synchronous reader of the files of one SBM11 generation directory (or
+ * collection root): the engine names every file and checks every answer. */
+export interface Sbm11Reader {
+  readAt(file: string, offset: number, length: number): Uint8Array | null;
+  size(file: string): number | null;
+}
+
+/** The answer of one SBM11 query. */
+export interface Sbm11Answer {
+  /** `path=ids` or `path=reference reason="..." ...` */
+  path: string;
+  rows: number;
+  /** `srj` (SELECT, ASK) or `ntriples` (CONSTRUCT, DESCRIBE) */
+  format: 'srj' | 'ntriples';
+  /** the bytes `l4sbm11 query` writes, as text */
+  readonly result: string;
+  /** the same answer as UTF-8 bytes */
+  readonly bytes: Uint8Array;
+  bytesRead: number;
+  reads: number;
+  /** the parsed SPARQL JSON for SELECT and ASK */
+  readonly json: any;
+}
+
+/** An open SBM11 generation. */
+export interface Sbm11Store {
+  handle: string;
+  /** the generation CURRENT names, or "" when the source is a generation */
+  generation: string;
+  terms: number;
+  query(sparql: string, options?: { base?: string; sparql12?: boolean; reference?: boolean }): Sbm11Answer;
+  close(): void;
+}
+
+
+
 /** One query against a store: open with the query's plan, query, close. */
 export function queryStore(
   source: string | StoreReader,
@@ -1292,6 +1503,8 @@ export function capabilities(): Promise<{
   shacl: boolean;
   shex: boolean;
   owlClosure: boolean;
+  explain: boolean;
+  stages: boolean;
   tableau: boolean;
   rml: boolean;
   csvw: boolean;

package/index.mjs

@@ -66,6 +66,9 @@ export const clearExtensionFunctions = api.clearExtensionFunctions;
 export const registerServiceEndpoint = api.registerServiceEndpoint;
 export const clearServiceEndpoints = api.clearServiceEndpoints;
 
+// SBM11 (openSbm11, registerSbm11Source) is not exported in 0.14.0: the op
+// sbm11Open traps in the wasm build (https://github.com/danbri/factoidal/issues/1009).
+
 // The persisted store
 export const openStore = api.openStore;
 export const queryStore = api.queryStore;
@@ -86,6 +89,11 @@ export const shexValidate = api.shexValidate;
 export const owlClosure = api.owlClosure;
 export const coreRdfsClosure = api.coreRdfsClosure;
 export const coreRdfsCheck = api.coreRdfsCheck;
+export const explain = api.explain;
+export const stages = api.stages;
+export const node = api.node;
+export const pipe = api.pipe;
+export const run = api.run;
 export const rdfsPlusClosure = api.rdfsPlusClosure;
 export const rhoDfClosure = api.rhoDfClosure;
 export const rhoDfFragmentCheck = api.rhoDfFragmentCheck;

package/l4-assets/l4factoidal.js

@@ -37,7 +37,7 @@
 // bytes change.
 
 // Stamped by formal/lean4/Wasm/build-wasm.sh step 9 -- do not hand-edit.
-const WASM_VERSION = "ec99e3524f1a";
+const WASM_VERSION = "2e65b7c2fda1";
 
 import createModule from './l4factoidal.mjs';
 

package/l4-assets/version.json

@@ -2,17 +2,17 @@
   "engine": "lean4",
   "note": "The Lean 4 (L4Factoidal) engine build provenance and claims: the only engine of @factoidal/core since 0.9.0 (issue 713). This committed file is a placeholder. tools/fetch-builds.sh --set web (through tools/stamp-l4-version.mjs) writes the provenance members from the danbri/factoidal-builds release that built the wasm; formal/lean4/Wasm/build-wasm.sh step 9 writes them for a local build. Do not commit a stamped copy.",
   "stamped": true,
-  "release": "danbri/factoidal-builds build-d9cc50253669-web",
-  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/39759947727",
-  "gitSha": "d9cc502536698eaf40ab74f7fb5de194c81f104f",
-  "builtAt": "2026-10-22T10:39:28Z",
+  "release": "danbri/factoidal-builds build-159a7adfbd01-web",
+  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/40192154339",
+  "gitSha": "159a7adfbd0155fc560583bc028a54f4508cd4ee",
+  "builtAt": "2026-10-25T12:48:55Z",
   "leanToolchain": "leanprover/lean4:v4.33.1",
   "emscripten": "6.0.8",
   "abiVersion": "1",
   "engineVersion": "l4factoidal-wasm 0.2.0 (dispatch: RDF parse/serialize, SPARQL query+update, RDFS/OWL-RL closures, RDFC-1.0, CL/IKL)",
   "version": "l4factoidal-wasm 0.2.0 (dispatch: RDF parse/serialize, SPARQL query+update, RDFS/OWL-RL closures, RDFC-1.0, CL/IKL)",
-  "wasmSha256": "ec99e3524f1a78667c2b41801556a9d25d65b01cea7afa60ec14c33523da3978",
-  "wasmBytes": 13212135,
+  "wasmSha256": "2e65b7c2fda13352e80f73ee224d3614551455f7361fa8b1596bb5f702653feb",
+  "wasmBytes": 15069305,
   "claims": {
     "source": "formal/lean4 (L4Factoidal): no sorry, no user axioms, no native_decide; W3C behaviour pinned by build-time #guard",
     "suitesAtBuildSha": "see docs/test-results and formal/lean4/PORT_NOTES.md at gitSha"

package/lib/api.mjs

@@ -29,6 +29,7 @@ import { openGeneration, readRegion, manifestKeys, hexOfBytes } from './store.mj
 import { fullEngineMessage } from './lean-entry.mjs';
 import { memoryDeltaLogStore } from './delta-log-hosts.mjs';
 import { FactoidalError, errorFromEnvelope, envelopeResult } from './errors.mjs';
+import { buildNodes } from './nodes.mjs';
 
 // The format names, regimes and query outputs are the engine's tables (op
 // engineTables, formal/lean4/Wasm/Ops/Handles.lean), read once per engine:
@@ -530,7 +531,10 @@ function buildApi(driver) {
       },
       missing: (what, op) => missingOpError(what, e, op),
       wrap(r, prefixes, extra) {
-        const { ok: _ok, handle, count, prefixes: own, ...info } = r;
+        // `warnings` (the reader's language-tag warnings) is not an info
+        // member: openText() and the lenient parse() pass the warnings of the
+        // caller's text in `extra`, with their offsets in UTF-16 units.
+        const { ok: _ok, handle, count, prefixes: own, warnings: _w, ...info } = r;
         return new Dataset(INTERNAL, c, handle, count,
           prefixes !== undefined ? prefixes : own, { ...(extra || {}), info });
       },
@@ -595,7 +599,10 @@ function buildApi(driver) {
       }
       throw err;
     }
-    return c.wrap(r, undefined, { format: tag, formatInferred: inferred });
+    return c.wrap(r, undefined, {
+      format: tag, formatInferred: inferred,
+      warnings: utf16Diagnostics(text, r.warnings),
+    });
   }
 
   // The Dataset a consumer reads: `data` itself when it is a Dataset, else
@@ -741,6 +748,7 @@ function buildApi(driver) {
       const opened = entryResult(c.e.datasetOpen(r.nquads, 'nquads', ''), 'parse');
       return c.wrap(opened, r.prefixes, {
         diagnostics: utf16Diagnostics(text, r.diagnostics),
+        warnings: utf16Diagnostics(text, r.warnings),
         format: tag, formatInferred: inferred,
       });
     }
@@ -1023,6 +1031,36 @@ function buildApi(driver) {
   /** Literature-name alias for coreRdfsCheck. */
   const rhoDfFragmentCheck = coreRdfsCheck;
 
+  /**
+   * Is `description` (a graph whose blank nodes are shared variables)
+   * RDFS-entailed by `sources`? Returns the evidence bundle when it is
+   * (https://github.com/danbri/factoidal/issues/1002). Op explainGraph, full
+   * engine only. `entailed: false` also relies on the named assumption in
+   * `assumptions`. Text inputs are Turtle unless `format` says otherwise.
+   * @param {Dataset|string|Array} sources
+   * @param {Dataset|string|Array} description default graph only
+   * @param {{profile?: 'rdfs', format?: string, baseIRI?: string,
+   *   sourcesFormat?: string, descriptionFormat?: string}} [options]
+   * @returns {Promise<{profile: string, entailed: boolean, bundle: object|null,
+   *   assumptions: string[], rejection: object|null, entailedMeans: string}>}
+   */
+  async function explain(sources, description, options) {
+    const o = optionsOf('explain', options);
+    if (o.profile !== undefined && o.profile !== 'rdfs') {
+      throw new TypeError(`explain: unsupported profile '${o.profile}' (only 'rdfs')`);
+    }
+    const { profile: _profile, sourcesFormat, descriptionFormat, ...rest } = o;
+    // The engine's option table has no entry for explain; the options here are read-only hints.
+    const opts = rest;
+    const fmt = opts.format || 'turtle';
+    const srcNq = await nquadsOf(sources, { ...opts, format: sourcesFormat || fmt }, 'explain(sources)');
+    const descNq = await nquadsOf(description, { ...opts, format: descriptionFormat || fmt }, 'explain(description)');
+    const e = await entry();
+    requireEntryFn(e, 'explainGraph', 'explain');
+    const { ok: _ok, ...out } = entryResult(e.explainGraph(srcNq, descNq), 'explain');
+    return out;
+  }
+
   /**
    * RDFS-Plus closure (RDFS with owl:sameAs, inverseOf, Symmetric,
    * Transitive, Functional and InverseFunctional properties,
@@ -1071,8 +1109,9 @@ function buildApi(driver) {
   }
 
   /**
-   * OWL DL consistency: `consistent` is true, false, or null (the refuter's
-   * budget ran out; `reason` names the cap).
+   * Checked atomic OWL consistency of the default graph: false is a checked
+   * contradiction; null means unsupported syntax or no accepted refutation.
+   * No model producer exists. fuel does not change the fixed checker bound.
    * @param {Dataset|string|Array} data
    * @param {{format?: string, baseIRI?: string, fuel?: number|string}} [options]
    * @returns {Promise<{consistent: boolean|null, reason?: string}>}
@@ -2077,7 +2116,7 @@ function buildApi(driver) {
    * @returns {Promise<{entry: boolean, construct: boolean,
    *   update: boolean, canonicalize: boolean, graphs: boolean,
    *   canonicalHash: boolean, shacl: boolean, shex: boolean,
-   *   owlClosure: boolean, rml: boolean, csvw: boolean, jsonld: boolean,
+   *   owlClosure: boolean, explain: boolean, stages: boolean, rml: boolean, csvw: boolean, jsonld: boolean,
    *   rif: boolean}>}
    */
   let capsCache = null;
@@ -2098,6 +2137,8 @@ function buildApi(driver) {
       shacl: has('shaclValidate'),
       shex: has('shexValidate'),
       owlClosure: has('owlClosure'),
+      explain: has('explainGraph'),
+      stages: has('stageList'),
       entailment: has('queryRaw'),
       tableau: has('tableauMaterialise') && has('tableauDlInconsistent'),
       rml: has('rmlMap'),
@@ -2131,6 +2172,12 @@ function buildApi(driver) {
     };
   }
 
+  // The node-composition API (lib/nodes.mjs, issue 1002 step 2).
+  const nodeApi = buildNodes({
+    entry, entryResult, requireEntryFn, Dataset,
+    parse, closure, shaclValidate, query, serialize, canonicalize, explain,
+  });
+
   return {
     parse,
     query,
@@ -2153,6 +2200,11 @@ function buildApi(driver) {
     owlClosure,
     coreRdfsClosure,
     coreRdfsCheck,
+    explain,
+    stages: nodeApi.stages,
+    node: nodeApi.node,
+    pipe: nodeApi.pipe,
+    run: nodeApi.run,
     rdfsPlusClosure,
     rhoDfClosure,
     rhoDfFragmentCheck,

package/lib/dataset.mjs

@@ -152,6 +152,7 @@ class Dataset {
     this._prefixes = Object.freeze({ ...(prefixes || {}) });
     const x = extra || {};
     this._diagnostics = Object.freeze((x.diagnostics || []).slice());
+    this._warnings = Object.freeze((x.warnings || []).slice());
     this._format = x.format;
     this._formatInferred = !!x.formatInferred;
     this._info = Object.freeze({ ...(x.info || {}) });
@@ -169,6 +170,13 @@ class Dataset {
   get prefixes() { return this._prefixes; }
   /** Diagnostics of a lenient parse ({lenient:true}); else empty. */
   get diagnostics() { return this._diagnostics; }
+  /**
+   * Warnings of the parse: one per language tag that is not well-formed
+   * under BCP 47 (class 'ill-formed-language-tag'). The triple is kept and
+   * the writers write the tag unchanged. Empty for a Dataset not read from
+   * text.
+   */
+  get warnings() { return this._warnings; }
   /** The syntax the data was read from, when it was read from text. */
   get format() { return this._format; }
   /** True when `format` was inferred because the caller gave none. */

package/lib/evidence.mjs

@@ -0,0 +1,84 @@
+// The evidence logic of the node-composition API (issue 1002), kept apart
+// from the engine so it runs, and is tested, without the wasm.
+//
+// Rule (owner-approved, issue 975 comment 6393905605 item 3): a stage that
+// is not `proved` may run only after an explicit opt-in, and its evidence
+// record says so. A result never reports a guarantee the path lacks:
+// `proved` is true only when every record is `checked`.
+//
+// ES module, no Node built-ins.
+
+import { FactoidalError } from './errors.mjs';
+
+/** A stage is checked exactly when its registry status is `proved`. */
+export const isChecked = (status) => status === 'proved';
+
+/** The reason text of an unchecked step. */
+export function reasonOf(n) {
+  if (n.status === 'missing') return 'no contract';
+  return n.assumptions.length > 0
+    ? `status ${n.status}; assumptions: ${n.assumptions.join(', ')}`
+    : `status ${n.status}`;
+}
+
+/**
+ * The refusal for node `n` before anything runs, or null. `hasRunner` is
+ * whether the package has a function that runs the stage.
+ * Without the opt-in a `missing` stage refuses (op.failed). With it, a stage
+ * runs when it has a runner; one with no runner refuses (op.unknown).
+ */
+export function refusalFor(n, unchecked, hasRunner) {
+  if (!n.runnable && !unchecked) {
+    return new FactoidalError(`run: stage '${n.stage}' has status ${n.status}: ` +
+      'no contract and no test suite, so it does not run as a node ' +
+      '(pass { unchecked: true } to run it without a guarantee)', { code: 'op.failed' });
+  }
+  if (!hasRunner) {
+    return new FactoidalError(`run: stage '${n.stage}' has no package function that runs it`,
+      { code: 'op.unknown' });
+  }
+  return null;
+}
+
+/**
+ * One evidence record. `checked` is true iff the status is `proved`.
+ * A step that ran under the opt-in and is not checked also carries
+ * `unchecked: true` and `reason`.
+ */
+export function makeRecord(n, artefact, unchecked) {
+  const checked = isChecked(n.status);
+  const base = {
+    stage: n.stage,
+    status: n.status,
+    contract: n.contract,
+    assumptions: n.assumptions,
+    checked,
+    artefact: artefact === undefined ? null : artefact,
+  };
+  if (unchecked && !checked) {
+    base.unchecked = true;
+    base.reason = reasonOf(n);
+  }
+  return Object.freeze(base);
+}
+
+/** A record is checked; a record without `checked` (older producer) falls back to its status. */
+export const recordChecked = (r) => (typeof r.checked === 'boolean' ? r.checked : isChecked(r.status));
+
+/** The union of the named assumptions of the records, first-seen order. */
+export function unionAssumptions(records) {
+  const seen = new Set();
+  const out = [];
+  for (const r of records) {
+    for (const a of r.assumptions) {
+      if (!seen.has(a)) { seen.add(a); out.push(a); }
+    }
+  }
+  return out;
+}
+
+/** `{ assumptions, proved, uncheckedSteps }` of a record list. */
+export function summarize(records) {
+  const uncheckedSteps = records.filter((r) => !recordChecked(r)).map((r) => r.stage);
+  return { assumptions: unionAssumptions(records), proved: uncheckedSteps.length === 0, uncheckedSteps };
+}