@factoidal/core 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.14.0
+
+**Checked pipelines.** Each component (reader, store, query evaluator, writer, reasoner, validator, proof checker) has one interface type whose contract against the W3C specifications is part of the type. A component cannot be added without a contract; a contract that is not proved yet is a named assumption, listed and counted in CI. A theorem states that the SPARQL answer agrees with the SPARQL 1.1 semantics for data from any source (a parsed document, a Dataset after edits, an update, a reasoner's output, a union of stores), given the listed assumptions. Status and gaps: https://github.com/danbri/factoidal/issues/975.
+
+- `explain(sources, description, { profile: "rdfs" })`: whether the sources RDFS-entail a description graph (its blank nodes are variables), with a checked derivation (`bundle`) when it does and the reason (`rejection`) when not (https://github.com/danbri/factoidal/issues/1002).
+- `run(pipeline, input, { unchecked: true })`: runs nodes whose stage is not proved; each evidence record has `checked`, and the result has `proved` and `uncheckedSteps`. Without the option a stage with no contract does not run.
+- `Dataset.warnings`: a language tag that is not well-formed BCP 47 is kept and reported with its line, column and offset; the writers write it unchanged (https://github.com/danbri/factoidal/issues/1004).
+- SPARQL `SELECT *` on the store path returns the variables in query order, the same header as the in-memory path (https://github.com/danbri/factoidal/issues/1014).
+- SBM11 in npm (`openSbm11`) is **not** in this release. Its wasm op `sbm11Open` traps (`unreachable`) in the release build, so the ops are not dispatched and the functions are not exported; the native `l4sbm11` commands are unchanged (https://github.com/danbri/factoidal/issues/1009).
+- `factoidal pack`, `factoidal sample-store` and `sampleStorePath()` write the IBK5 layout (wire version 10, manifest layout `quad-ibk5-ptd2-lgi4-gbi1-merkle-v0`) when no `--layout` is given; the default was IBK3. Owner, 2026-10-25: "yes IBK5 not IBK3 as default sounds sensible, assuming no major downside" (https://github.com/danbri/factoidal/issues/1009). `factoidal serve` over such a store takes changes to every graph; over an IBK3 store a change to a named graph answered 501. `--layout ibk3` still writes IBK3. `sampleStoreFacts.layout` is now `'ibk5'`.
+- `stages()`, `node()`, `pipe()`, `run()`: the registered Lean stages as nodes (https://github.com/danbri/factoidal/issues/1002, step 2). `stages()` is the engine's op `stageList`, read from the Lean stage registry: name, interface type, wire types, status, contract and named assumptions of each stage. A value on a wire is `{graph, evidence}`; each node adds one evidence record `{stage, status, contract, assumptions, artefact}`, and `run()` reports the union of the named assumptions of the nodes. A stage with status `missing` does not run. Needs a wasm build with the op `stageList`.
+- `factoidal pack` writes a set of rows in every layout (https://github.com/danbri/factoidal/issues/1006). Correction to 0.13.0: its entry says that the stores keep one copy of a repeated triple, but in 0.13.0 that was true for the IBK4 and IBK5 layouts only, and only on read. The default layout (IBK3) kept a repeated triple, and kept `"a"@en` and `"a"@EN` as two rows, so `COUNT(*)` counted both; the IBK4 and IBK5 packers also wrote the repeated rows. Now each packer keeps the distinct triples it has written and writes a triple only once (per graph on the quad layouts). A source with no repeated triple gives the same generation as before. The packer's memory now grows with the number of distinct triples of the source. Proved: `Dataflow.packedRows_keyNodup`; tests: `test/pack-is-a-set-1006.test.mjs`.
+- The N-Triples, N-Quads, Turtle and TriG writers give a fresh valid label to a blank-node label outside BLANK_NODE_LABEL (the same label for each occurrence, never a label of another blank node), and refuse a language tag outside LANGTAG with an error that names the tag (https://github.com/danbri/factoidal/issues/986).
+- A language tag is kept in lower case (RDF 1.2 Concepts §3.4: `"x"@en` and `"x"@EN` are one RDF term). Every reader, `STRLANG`, `STRLANGDIR` and the term constructors write the tag in lower case, so `LANG()` returns it in lower case, and a SPARQL answer no longer depends on the order of the triple patterns when the data spells one tag in two ways (https://github.com/danbri/factoidal/issues/1001).
+
 ## 0.13.0
 
 **A parsed document is a set of quads** (RDF 1.1 Concepts §3 and §4;

package/README.md

@@ -52,6 +52,50 @@ RDF 1.2 input uses `turtle12`, `ntriples12`, `nquads12` or `trig12`.
   "Terms given as strings".
 - RDF/JS DataFactory and DatasetCore (`/rdfjs`), a functional API (`/fn`)
 
+## Checked pipelines
+
+Each component kind has one interface type whose contract against the W3C
+specifications is part of the type: readers, stores, the SPARQL evaluator,
+writers, reasoners, validators and the proof checker. A contract that is not
+proved yet is a named assumption; CI fails when the list of assumptions grows
+without a stated reason. A theorem states that the SPARQL answer agrees with
+the SPARQL 1.1 semantics for data from any source (a parsed document, an
+edited Dataset, an update, a reasoner's output, a union of stores), given the
+listed assumptions. No new command-line verbs. Status:
+https://github.com/danbri/factoidal/issues/975.
+
+The same components are nodes you can compose. A value on a wire is
+`{graph, evidence}`; each node adds one evidence record; the result lists the
+union of the named assumptions of the nodes, so a pipeline says exactly what
+its answer depends on.
+
+```js
+import { stages, node, pipe, run } from "@factoidal/core";
+
+const sources = `@prefix ex: <http://example.org/> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ex:alice ex:worksFor ex:acme .
+ex:worksFor rdfs:domain ex:Employee .
+ex:Employee rdfs:subClassOf ex:Person .`;
+const description = `@prefix ex: <http://example.org/> .
+_:x a ex:Person . _:x ex:worksFor ex:acme .`;
+
+console.log((await stages()).length);  // registered components, each with status and contract
+const p = pipe(
+  await node("turtleDocumentReader"),
+  await node("rdfsReasoner"),
+  await node("rdfsExplainGraphStage", { description }),
+);
+const r = await run(p, sources);
+console.log(r.evidence.map((e) => e.stage)); // one record per node
+console.log(r.evidence[2].artefact.entailed); // true, with a checked derivation
+console.log(r.assumptions, r.proved);       // what the answer depends on
+```
+
+`run(p, input, { unchecked: true })` also runs components that are not proved,
+and marks those steps in the evidence. Details: API.md, "Stages as nodes" and
+"Explaining an entailment" (`explain()` is the same check as one call).
+
 Formats (generated from `formats()`):
 
 <!-- formats-table:start (generated by test/formats-table.test.mjs) -->
@@ -135,7 +179,7 @@ Changes: [CHANGELOG.md](CHANGELOG.md).
 ```console
 $ npx factoidal serve --file data.ttl /ds          # SPARQL endpoint at /ds/sparql
 $ npx factoidal serve --tdb2 DIR /ds               # serve a Jena TDB2 database
-$ npx factoidal pack data.ttl store/gen-1 && npx factoidal activate store gen-1
+$ npx factoidal pack data.ttl store/gen-1 && npx factoidal activate store gen-1   # IBK5 quad blocks
 $ npx factoidal query store 'SELECT * WHERE { ?s ?p ?o } LIMIT 5'
 $ npx factoidal query "$(npx factoidal sample-store)" 'SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }'
 $ npx factoidal lws-serve DIR --issuer IRI         # Linked Web Storage
@@ -150,13 +194,15 @@ $ npx factoidal solid-serve DIR                    # Solid Protocol
 Official test suites, pass / fail / total, 2026-10-09 [B] unless marked.
 
 The OWL DL rows below are historical measurements of the legacy harness;
-they do not measure the current `owlIsConsistent` API. That API now checks
-only an admitted atomic fragment of the default graph. It returns `false`
-for a checked contradiction and `null` for unsupported input or an incomplete
-check; it never returns `true`. Restrictions, negative property assertions,
-imports and equivalentClass are unsupported, and `fuel` does not change its
-fixed 64-round checker bound. `owlEntails` still uses a separate legacy path
-whose positive verdicts do not have this source-to-verdict proof. See the
+they do not measure the current `owlIsConsistent` API. That API checks only
+an admitted fragment of the default graph (atomic classes,
+`owl:someValuesFrom`, `owl:TransitiveProperty`, and annotations, axiom
+annotations included). It returns `true` for a checked finite model, `false`
+for a checked contradiction and `null` for unsupported input, exhausted
+`fuel` or an incomplete check. Other restrictions, negative property
+assertions, imports and equivalentClass are unsupported. `owlEntails`
+answers `false` only with a checked countermodel; its positive verdicts use a
+separate legacy path that does not have this source-to-verdict proof. See the
 [OWL API contract](https://github.com/danbri/factoidal-core/blob/main/npm/factoidal/API.md)
 and the [assurance record](https://github.com/danbri/factoidal-core/blob/main/docs/20261022-owl-pr-reconciliation.md).
 

package/bin/factoidal.mjs

@@ -224,9 +224,9 @@ INPUT is an RDF file. OUTPUT is the generation directory to create; it is
 normally STORE/gen-N. Packing does not activate: run activate next.
 
 options:
-  --layout LAYOUT    ibk3 (triples, default), ibk4 (quads, wire version 9)
-                     or ibk5 (quads, wire version 10: RDF 1.2 terms,
-                     out-of-line literals, zone maps)
+  --layout LAYOUT    ibk5 (quads, wire version 10: RDF 1.2 terms,
+                     out-of-line literals, zone maps; default), ibk4
+                     (quads, wire version 9) or ibk3 (triples)
   --syntax SYNTAX    turtle, trig or nquads; default from the file extension
   --chunk-bytes N    Merkle chunk size; default is the engine's
   --batch-bytes N    ibk4 only: source bytes between publication batches;
@@ -319,7 +319,7 @@ activated generation's delta log as one batch before the response is sent,
 and is visible to the next request. An IBK3 (triples) generation accepts
 changes to the default graph only, because its delta log is replayed and
 compacted for that graph only; a change to a named graph answers 501. A
-quad generation (ibk4, ibk5) accepts every graph. Fold the log into a new
+quad generation (ibk4, ibk5, the default) accepts every graph. Fold the log into a new
 generation with l4block-shard-compact, activate it, and restart the server.
 
 The server makes no protocol decision: the request framing, routing,
@@ -1266,7 +1266,7 @@ function currentDirectory () {
 }
 
 function packLayout (options) {
-  if (typeof options.layout !== 'string') return 'ibk3'
+  if (typeof options.layout !== 'string') return 'ibk5'
   const layout = options.layout.toLowerCase()
   if (PACK_LAYOUTS.indexOf(layout) >= 0) return layout
   throw new UsageError(`--layout ${options.layout} is not one of ${PACK_LAYOUTS.join(', ')}`)
@@ -1528,7 +1528,7 @@ async function commandServe (positional, options) {
     const { tmpdir } = await import('node:os')
     const { join } = await import('node:path')
     const root = mkdtempSync(join(tmpdir(), 'factoidal-serve-'))
-    const packOptions = { quiet: true, layout: typeof options.layout === 'string' ? options.layout : 'ibk5' }
+    const packOptions = { quiet: true, layout: packLayout(options) }
     let rc = await commandPack([options.file, join(root, 'gen-1')], packOptions)
     if (rc !== 0) return rc
     rc = await commandActivate([root, 'gen-1'], { quiet: true })

package/browser.d.ts

@@ -11,6 +11,8 @@ export type {
   DataFormat, EntailRegime, Bindings, DataInput, QueryInput, ParseOptions,
   QueryOptions, SerializeOptions, StoreReader, OpenStoreOptions,
   DeltaLogHandle, DeltaLogInspection,
+  Sbm11Reader, Sbm11Answer, Sbm11Store,
+  ExplainResult, StageInfo, EvidenceRecord, Wire, FactoidalNode, Pipeline, RunResult, RunOptions,
 } from './index';
 
 export {
@@ -50,6 +52,11 @@ export {
   owlClosure,
   coreRdfsClosure,
   coreRdfsCheck,
+  explain,
+  stages,
+  node,
+  pipe,
+  run,
   rdfsPlusClosure,
   rhoDfClosure,
   rhoDfFragmentCheck,

package/browser.js

@@ -59,6 +59,9 @@ const api = buildApi({
   deltaLogStore: indexedDbDeltaLogStore(),
 });
 
+// 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).
+
 // RDF and SPARQL
 export const parse = api.parse;
 export const query = api.query;
@@ -102,6 +105,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/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,
@@ -681,15 +842,17 @@ export function tableauDlInconsistent(
 
 /**
  * Checked consistency for the original default graph in a restricted
- * atomic OWL fragment (named subclass/class assertions, Thing/Nothing,
- * sameAs/differentFrom and limited declarations/annotations).
- * false requires an accepted certificate; null means unsupported-syntax
- * or incomplete-search. No model producer exists, so true is not returned.
- * Named graphs do not contribute axioms. RDF 1.2 terms are refused.
- * This narrows earlier unchecked coverage: restrictions, object/data
- * property axioms, imports and equivalentClass are unsupported.
- * fuel is retained for compatibility but does not change this fixed
- * 64-round certificate check. This is not complete OWL DL support.
+ * 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,
@@ -703,7 +866,9 @@ export function owlIsConsistent(
  * 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.
- * No checked countermodel constructor exists, so it never returns `false`.
+ * `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.
  */
@@ -897,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,
@@ -1302,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 = "1b55f66d8e19";
+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-6f5b96407a4c-web",
-  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/40076270080",
-  "gitSha": "6f5b96407a4cd95ac7452256ed2d4b9c938a7c49",
-  "builtAt": "2026-10-24T08:40:08Z",
+  "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": "1b55f66d8e193c6a3d168838bd77e8a5b1accb94e0a7c84209b63429f4989396",
-  "wasmBytes": 14483288,
+  "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,
@@ -2078,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;
@@ -2099,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'),
@@ -2132,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,
@@ -2154,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 };
+}

package/lib/nodes.mjs

@@ -0,0 +1,215 @@
+// The node-composition API (https://github.com/danbri/factoidal/issues/1002,
+// step 2): registered Lean stages as nodes, each carrying its contract name
+// and its proof status, with evidence flowing on the wires.
+//
+// The stage list is the engine's (op stageList, formal/lean4/Wasm/Ops/
+// StageList.lean), read from the Lean registry
+// L4Factoidal.Dataflow.registry: name, interface type, wire types, status,
+// contract, named assumptions, and whether the stage may run at all
+// (`runnable`, false for status `missing`). This file holds no copy of it.
+//
+// What this file adds is the binding of a stage NAME to the package
+// function that runs it (RUNNERS below; each is the function that
+// foundation/entrypoints.toml maps to that stage), and the wiring: a value
+// on a wire is `{ graph, evidence }`, and each node appends one evidence
+// record `{ stage, status, contract, assumptions, checked, artefact }` (plus
+// `unchecked` and `reason` for a step run under run()'s `unchecked` opt-in;
+// the record logic is in evidence.mjs). The result of
+// a run also reports the union of the named assumptions of the nodes it
+// passed: the premise list of the pipeline's soundness statement
+// (Dataflow/EndToEnd.lean) as the user sees it.
+//
+// ES module, no Node built-ins: the browser loads this file as it is.
+
+import { FactoidalError } from './errors.mjs';
+import { refusalFor, makeRecord, summarize, unionAssumptions } from './evidence.mjs';
+
+/**
+ * @param {object} deps the package functions and the engine entry
+ * @returns {{stages: Function, node: Function, pipe: Function, run: Function}}
+ */
+export function buildNodes(deps) {
+  const { entry, entryResult, requireEntryFn, Dataset,
+    parse, closure, shaclValidate, query, serialize, canonicalize, explain } = deps;
+
+  const reader = (format) => async (wire, params) => {
+    if (typeof wire.graph !== 'string') {
+      throw new TypeError(`node: a reader takes text on its wire (got ${typeof wire.graph})`);
+    }
+    const ds = await parse(wire.graph, { format, ...params });
+    return { graph: ds, artefact: { format } };
+  };
+  const reasoner = (regime) => async (wire, params) => ({
+    graph: await closure(wire.graph, regime, params),
+    artefact: { regime },
+  });
+  const writer = (format) => async (wire, params) => ({
+    artefact: { format, text: await serialize(wire.graph, { ...params, format }) },
+  });
+
+  // Stage name (stageList `name`) -> the package function that runs it.
+  // A runner answers `{ graph?, artefact }`; no `graph` passes the input
+  // graph on unchanged.
+  const RUNNERS = {
+    ntriplesDocumentReader: reader('ntriples'),
+    nquadsDocumentReader: reader('nquads'),
+    turtleDocumentReader: reader('turtle'),
+    trigDocumentReader: reader('trig'),
+    rdfxmlDocumentReader: reader('rdfxml'),
+    jsonldDocumentReader: reader('jsonld'),
+    rdfsReasoner: reasoner('rdfs'),
+    owlRlReasoner: reasoner('owl-rl'),
+    rhoDfReasoner: reasoner('rho-df'),
+    shaclValidator: async (wire, params) => {
+      const { shapes, ...opts } = params;
+      if (shapes === undefined) throw new TypeError('node shaclValidator: params.shapes is required');
+      const r = await shaclValidate(wire.graph, shapes, opts);
+      return { artefact: { conforms: r.conforms, report: r.report } };
+    },
+    shippedEvaluator: async (wire, params) => {
+      const { query: sparql, ...opts } = params;
+      if (typeof sparql !== 'string') throw new TypeError('node shippedEvaluator: params.query must be a string');
+      const answer = await query(wire.graph, sparql, opts);
+      return answer instanceof Dataset ? { graph: answer, artefact: { form: 'graph' } }
+        : { artefact: { answer } };
+    },
+    ntriplesDocumentWriter: writer('ntriples'),
+    nquadsDocumentWriter: writer('nquads'),
+    turtleDocumentWriter: writer('turtle'),
+    trigDocumentWriter: writer('trig'),
+    rdfxmlDocumentWriter: writer('rdfxml'),
+    rdfcStage: async (wire, params) => ({
+      artefact: { canonical: await canonicalize(wire.graph, params) },
+    }),
+    rdfsExplainGraphStage: async (wire, params) => {
+      const { description, ...opts } = params;
+      if (description === undefined) {
+        throw new TypeError('node rdfsExplainGraphStage: params.description is required');
+      }
+      return { artefact: await explain(wire.graph, description, { ...opts, profile: 'rdfs' }) };
+    },
+  };
+
+  let stageCache = null;
+
+  /**
+   * The engine's stage list (op stageList), one element per registry entry.
+   * @returns {Promise<object[]>}
+   */
+  async function stages() {
+    if (!stageCache) {
+      stageCache = (async () => {
+        const e = await entry();
+        requireEntryFn(e, 'stageList', 'stages');
+        const r = entryResult(e.stageList(), 'stages');
+        return Object.freeze(r.stages.map((s) => Object.freeze({
+          ...s,
+          theorems: Object.freeze([...s.theorems]),
+          assumptions: Object.freeze([...s.assumptions]),
+          tests: Object.freeze([...s.tests]),
+          bound: Object.prototype.hasOwnProperty.call(RUNNERS, s.name),
+        })));
+      })();
+      stageCache.catch(() => { stageCache = null; });
+    }
+    return stageCache;
+  }
+
+  const NODE = Symbol('factoidal.node');
+
+  /**
+   * A node for the registered stage `name`, with its parameters (the
+   * second argument of the package function it calls, e.g. `{shapes}`,
+   * `{query}`, `{description}`, reader options).
+   * @param {string} name a stageList `name`
+   * @param {object} [params]
+   * @returns {Promise<object>}
+   */
+  async function node(name, params) {
+    if (typeof name !== 'string') throw new TypeError('node: name must be a string');
+    if (params !== undefined && (params === null || typeof params !== 'object')) {
+      throw new TypeError('node: params must be an object');
+    }
+    const info = (await stages()).find((s) => s.name === name);
+    if (!info) {
+      throw new FactoidalError(`node: no registered stage named '${name}' (see stages())`,
+        { code: 'option.invalid-value' });
+    }
+    return Object.freeze({
+      [NODE]: true,
+      stage: info.name,
+      kind: info.kind,
+      status: info.status,
+      contract: info.contract,
+      assumptions: info.assumptions,
+      wireIn: info.wireIn,
+      wireOut: info.wireOut,
+      runnable: info.runnable,
+      bound: info.bound,
+      params: Object.freeze({ ...(params || {}) }),
+    });
+  }
+
+  function nodesOf(items, who) {
+    const out = [];
+    for (const n of items) {
+      if (n && n[NODE]) out.push(n);
+      else if (n && Array.isArray(n.nodes)) out.push(...nodesOf(n.nodes, who));
+      else throw new TypeError(`${who}: expected nodes from node() or pipelines from pipe()`);
+    }
+    return out;
+  }
+
+  /**
+   * A pipeline: the nodes in order (pipelines are flattened).
+   * `assumptions` is the union of the nodes' named assumptions.
+   * @returns {{nodes: object[], assumptions: string[]}}
+   */
+  function pipe(...items) {
+    const nodes = nodesOf(items, 'pipe');
+    if (nodes.length === 0) throw new TypeError('pipe: no nodes');
+    return Object.freeze({ nodes: Object.freeze(nodes), assumptions: Object.freeze(unionAssumptions(nodes)) });
+  }
+
+  const isWire = (v) => v !== null && typeof v === 'object' && !(v instanceof Dataset) &&
+    Object.prototype.hasOwnProperty.call(v, 'graph') && Array.isArray(v.evidence);
+
+  /**
+   * Run a node or a pipeline. `input` is a wire value `{graph, evidence}`
+   * or the graph itself (text for a reader, else a Dataset or data input).
+   * `options.unchecked: true` lets stages that are not `proved` run,
+   * `missing` ones too when the package has a runner for them; each such
+   * step's record says so (evidence.mjs). Without it, a `missing` stage
+   * refuses before any node runs.
+   * @returns {Promise<{graph: any, evidence: object[], assumptions: string[],
+   *   proved: boolean, uncheckedSteps: string[]}>}
+   */
+  async function run(pipeline, input, options) {
+    if (options !== undefined && (options === null || typeof options !== 'object')) {
+      throw new TypeError('run: options must be an object');
+    }
+    const unchecked = !!(options && options.unchecked);
+    const nodes = nodesOf([pipeline], 'run');
+    for (const n of nodes) {
+      const why = refusalFor(n, unchecked, Object.prototype.hasOwnProperty.call(RUNNERS, n.stage));
+      if (why) throw why;
+    }
+    let wire = isWire(input) ? { graph: input.graph, evidence: [...input.evidence] }
+      : { graph: input, evidence: [] };
+    let owned = null; // a Dataset an earlier node of this run made
+    for (const n of nodes) {
+      const out = await RUNNERS[n.stage](wire, n.params);
+      const record = makeRecord(n, out.artefact, unchecked);
+      let graph = wire.graph;
+      if (out.graph !== undefined && out.graph !== wire.graph) {
+        if (owned && owned === wire.graph && typeof owned.dispose === 'function') owned.dispose();
+        graph = out.graph;
+        owned = out.graph instanceof Dataset ? out.graph : null;
+      }
+      wire = { graph, evidence: [...wire.evidence, record] };
+    }
+    return { graph: wire.graph, evidence: wire.evidence, ...summarize(wire.evidence) };
+  }
+
+  return { stages, node, pipe, run };
+}

package/lib/sbm11-node.mjs

@@ -0,0 +1,61 @@
+// The Node reader of an SBM11 generation directory for lib/sbm11.mjs: the
+// source is a directory path, and a file of the generation is read with
+// fs.readSync at an offset (https://github.com/danbri/factoidal/issues/1009
+// KR1). It moves bytes only (iron rule 7); the engine checks every length.
+//
+// One open file descriptor per file, kept while the reader lives: a query
+// makes many small reads of the same few files.
+
+import { closeSync, fstatSync, openSync, readSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export function nodeDirectoryReader (dir) {
+  const fds = new Map()
+  function fdOf (file) {
+    let fd = fds.get(file)
+    if (fd === undefined) {
+      fd = openSync(join(dir, file), 'r')
+      fds.set(file, fd)
+    }
+    return fd
+  }
+  return {
+    readAt (file, offset, length) {
+      const out = new Uint8Array(length)
+      const fd = fdOf(file)
+      let done = 0
+      while (done < length) {
+        const n = readSync(fd, out, done, length - done, offset + done)
+        if (n === 0) break
+        done += n
+      }
+      return done === length ? out : null
+    },
+    size (file) {
+      try {
+        const fd = fds.get(file)
+        const st = fd === undefined ? statSync(join(dir, file)) : fstatSync(fd)
+        return st.isFile() ? st.size : null
+      } catch {
+        return null
+      }
+    },
+    close () {
+      for (const fd of fds.values()) closeSync(fd)
+      fds.clear()
+    }
+  }
+}
+
+/** A default-reader factory: one reader per directory, kept. */
+export function nodeDefaultReaderFactory () {
+  const byDir = new Map()
+  return (source) => {
+    let r = byDir.get(source)
+    if (!r) {
+      r = nodeDirectoryReader(source)
+      byDir.set(source, r)
+    }
+    return r
+  }
+}

package/lib/sbm11.mjs

@@ -0,0 +1,148 @@
+// SPARQL over an SBM11 generation, in Node and in the browser, through the
+// wasm ops sbm11Open / sbm11Query / sbm11Close
+// (formal/lean4/Wasm/Ops/Sbm11.lean; https://github.com/danbri/factoidal/issues/1009 KR1).
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Move bytes. The engine asks for (source, file, offset, length) through the
+// bridge globalThis.__factoidalReadAt, and for the size of a file through
+// globalThis.__factoidalFileSize (the EM_JS bodies in
+// formal/lean4/ffi/l4_hostread.c call them synchronously). This file finds
+// the reader that serves `source` and answers. It never reads a manifest,
+// checks a length or a digest, or decides which file a query needs: the
+// engine names every file and checks every answer against the manifest
+// (formal/lean4/L4Factoidal/Storage/Sbm11/HostSession.lean). Iron rule 7.
+//
+// READERS
+// A reader is { readAt(file, offset, length) -> Uint8Array, size(file) ->
+// number | null }, both synchronous: the engine is inside WebAssembly and
+// cannot wait for a promise. Node: lib/sbm11-node.mjs reads a directory with
+// fs. A browser worker: a reader over OPFS FileSystemSyncAccessHandle
+// (stage 4 of https://github.com/danbri/factoidal/issues/1007). A caller
+// registers a reader under a source name; a source with no registered reader
+// goes to the default reader (Node: the directory of that name).
+
+const readers = new Map()
+let defaultReader = null
+let bridgeInstalled = false
+
+function readerFor (source) {
+  const r = readers.get(source)
+  if (r) return r
+  if (defaultReader) return defaultReader(source)
+  return null
+}
+
+function installBridge () {
+  if (bridgeInstalled) return
+  bridgeInstalled = true
+  // A thrown error and a wrong length both reach Lean as "the host gave no
+  // bytes"; the engine then refuses the read with the file name.
+  globalThis.__factoidalReadAt = (source, file, offset, length) => {
+    const r = readerFor(source)
+    if (!r) return null
+    return r.readAt(file, offset, length)
+  }
+  globalThis.__factoidalFileSize = (source, file) => {
+    const r = readerFor(source)
+    if (!r) return null
+    return r.size(file)
+  }
+}
+
+/**
+ * Serve `source` with `reader` ({ readAt(file, offset, length), size(file) },
+ * both synchronous). `null` removes the registration.
+ */
+export function registerSbm11Source (source, reader) {
+  installBridge()
+  if (reader === null) { readers.delete(String(source)); return }
+  if (!reader || typeof reader.readAt !== 'function' || typeof reader.size !== 'function') {
+    throw new TypeError('registerSbm11Source: reader needs readAt(file, offset, length) and size(file)')
+  }
+  readers.set(String(source), reader)
+}
+
+/** The reader for a source with no registration: `(source) => reader | null`. */
+export function setDefaultSbm11Reader (factory) {
+  installBridge()
+  defaultReader = factory
+}
+
+function envelope (raw) {
+  const j = typeof raw === 'string' ? JSON.parse(raw) : raw
+  if (!j || j.ok !== true) {
+    const e = new Error((j && j.error) || 'sbm11: unknown error')
+    e.code = 'SBM11'
+    throw e
+  }
+  return j
+}
+
+/**
+ * The SBM11 functions over an engine loader: `loadEngine()` resolves to the
+ * engine handle (`call(op, args)`).
+ */
+export function sbm11Api (loadEngine) {
+  /**
+   * Open an SBM11 generation (a generation directory, or a collection root
+   * whose CURRENT file names one). Returns { generation, terms, query(sparql,
+   * options), close() }. `query` answers { path, rows, format, result, json }:
+   * `result` is the text `l4sbm11 query` writes (SPARQL JSON for SELECT and
+   * ASK, N-Triples for CONSTRUCT and DESCRIBE), `json` its parse for
+   * SELECT and ASK.
+   */
+  async function openSbm11 (source, options = {}) {
+    installBridge()
+    if (options.reader) registerSbm11Source(source, options.reader)
+    const eng = await loadEngine()
+    const opened = envelope(eng.call('sbm11Open', [String(source)]))
+    const handle = opened.handle
+    let open = true
+    return {
+      handle,
+      generation: opened.generation,
+      terms: Number(opened.terms),
+      query (sparql, qopts = {}) {
+        if (!open) throw new Error('sbm11: the store is closed')
+        const o = {}
+        if (qopts.base != null) o.base = String(qopts.base)
+        if (qopts.sparql12) o.sparql12 = true
+        if (qopts.reference) o.reference = true
+        const args = [handle, String(sparql), JSON.stringify(o)]
+        // The byte-region entry returns the result bytes outside the
+        // envelope; a large answer is then not escaped into a JSON string
+        // and parsed again (Wasm/Ops/Sbm11.lean sbm11QueryBlob).
+        let j, bytes
+        if (typeof eng.callBlobIO === 'function') {
+          const answer = eng.callBlobIO('sbm11Query', args, new Uint8Array(0))
+          j = envelope(answer.envelope)
+          bytes = answer.bytes
+        } else {
+          j = envelope(eng.call('sbm11Query', args))
+        }
+        let text = bytes === undefined ? j.result : undefined
+        return {
+          path: j.path,
+          rows: Number(j.rows),
+          format: j.format,
+          bytesRead: Number(j.bytesRead),
+          reads: Number(j.reads),
+          /** the answer as bytes (UTF-8) */
+          get bytes () { return bytes ?? new TextEncoder().encode(text) },
+          /** the answer as text */
+          get result () {
+            if (text === undefined) text = new TextDecoder().decode(bytes)
+            return text
+          },
+          get json () { return j.format === 'srj' ? JSON.parse(this.result) : undefined }
+        }
+      },
+      close () {
+        if (!open) return
+        open = false
+        envelope(eng.call('sbm11Close', [handle]))
+      }
+    }
+  }
+  return { openSbm11 }
+}

package/lib/version.mjs

@@ -2,4 +2,4 @@
 // needs import attributes, which not every runtime this package targets
 // reads). test/dts-drift.test.js checks that it equals package.json's
 // `version`.
-export const version = '0.13.0';
+export const version = '0.14.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factoidal/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "RDF parsing and writing (Turtle, TriG, N-Triples, N-Quads, RDF/XML, JSON-LD), SPARQL 1.1 and 1.2, RDFS and OWL reasoning, SHACL and ShEx validation, CSVW and RML mapping, RDFC-1.0, and SPARQL, LWS and Solid servers, for Node, Deno and browsers.",
   "keywords": [
     "sparql",

package/sample-store.mjs

@@ -27,7 +27,7 @@ ex:c3 a skos:Concept ; skos:inScheme ex:scheme ; skos:prefLabel "SECAM"@en ; sko
 export const sampleStoreFacts = Object.freeze({
   triples: 15,
   source: 'SAMPLE_TURTLE in sample-store.mjs (written for this package)',
-  layout: 'ibk3'
+  layout: 'ibk5'
 })
 
 /**