@factoidal/core 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.15.0
+
+- `openSbm11(source)` and `registerSbm11Source(source, reader)` are back, with the wasm ops `sbm11Open`, `sbm11Query`, `sbm11Close`: SPARQL over an SBM11 generation (the Shardborough store) in Node and in the browser, reading each file at an offset through a host reader (https://github.com/danbri/factoidal/issues/1009, https://github.com/danbri/factoidal-core/pull/93). Fix: in 0.14.0 `sbm11Open` trapped (wasm `unreachable`) because the C host-read functions had a signature that differs from the generated one; the wasm build now fails on any such mismatch. Not yet: the Merkle check of each read, a generation with a delta log (refused at open), packing SBM11 from npm.
+- `lwsSbm11Reader(url, { auth, headers, transport })`: a reader for `openSbm11` of an SBM11 generation held as Linked Web Storage resources, by HTTP `Range` GETs when the server answers `206` with a matching `Content-Range`, else by whole GETs kept in memory; a changed `ETag` refuses the read, and `store.evidence` lists each resource read with its `ETag` (https://github.com/danbri/factoidal/issues/1010, https://github.com/danbri/factoidal-core/pull/90). In Lean every reader is now a storage `Medium`. `browser.d.ts` now types `openSbm11` and `registerSbm11Source`.
+- The native `l4factoidal query` command keeps a named graph with no triple (RDF 1.1 Concepts §4); before, the dataset went through an N-Quads round trip, which cannot state an empty graph (https://github.com/danbri/factoidal/issues/876 part 1, https://github.com/danbri/factoidal-core/pull/94).
+- SPARQL: a property-path alternative of IRIs (`?s p|q ?o`) is planned as the UNION of its triple patterns, so the store planners use their indexes for it; a theorem proves the two forms give the same solutions in the same order and multiplicity, and a test checks that both give the same plan and rows (https://github.com/danbri/factoidal/issues/1008, https://github.com/danbri/factoidal-core/pull/96).
+- `pipe()` and `run()` take the type check and the union of the named assumptions from the engine's op `pipelineCheck`, computed from the Lean stage registry; one theorem (`Pipeline.guarantee_sound`) gives the guarantee of every well-typed pipeline (https://github.com/danbri/factoidal/issues/1002 step 1, https://github.com/danbri/factoidal-core/pull/82). `pipe()` adds `wellTyped` and `check`; `run()` adds `wellTyped` and refuses a pipeline that is not well typed unless `{unchecked: true}`, then reports `proved: false`. `stages()` adds `params`. With a wasm build that has no op `pipelineCheck`, `wellTyped` is null and the union is computed from the nodes as before.
+
+## 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,54 @@ 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.
+`pipe()` and `run()` get the type check and that union from the engine
+(op `pipelineCheck`); the theorem `Pipeline.guarantee_sound` gives the
+guarantee of every well-typed pipeline, and `run()` refuses one that is not
+well typed unless `{ unchecked: true }`.
+
+```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 +183,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 +198,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, Sbm11ReadEvidence, Sbm11Transport,
+  ExplainResult, StageInfo, EvidenceRecord, Wire, FactoidalNode, Pipeline, RunResult, RunOptions,
 } from './index';
 
 export {
@@ -38,6 +40,9 @@ export {
   openStore,
   queryStore,
   listStores,
+  openSbm11,
+  registerSbm11Source,
+  lwsSbm11Reader,
   deltaLogOpen,
   deltaLogAppend,
   deltaLogReadAllHex,
@@ -50,6 +55,11 @@ export {
   owlClosure,
   coreRdfsClosure,
   coreRdfsCheck,
+  explain,
+  stages,
+  node,
+  pipe,
+  run,
   rdfsPlusClosure,
   rhoDfClosure,
   rhoDfFragmentCheck,

package/browser.js

@@ -26,6 +26,8 @@ import { buildApi } from './lib/api.mjs';
 import { entryFromEngine } from './lib/lean-entry.mjs';
 import { browserEngine } from './lib/browser-engine.mjs';
 import { indexedDbDeltaLogStore } from './lib/delta-log-hosts.mjs';
+import { sbm11Api, registerSbm11Source } from './lib/sbm11.mjs';
+import { lwsSbm11Reader } from './lib/sbm11-lws.mjs';
 
 const l4Engine = browserEngine('l4factoidal', new URL('./l4-assets/', import.meta.url).href);
 
@@ -59,6 +61,16 @@ const api = buildApi({
   deltaLogStore: indexedDbDeltaLogStore(),
 });
 
+// SBM11, the Shardborough store, through host positioned reads
+// (lib/sbm11.mjs; https://github.com/danbri/factoidal/issues/1009). In a
+// browser every source needs a registered synchronous reader, for example
+// over OPFS FileSystemSyncAccessHandle in a dedicated worker.
+export const openSbm11 = sbm11Api(loadEngine).openSbm11;
+export { registerSbm11Source };
+// A reader of an SBM11 generation held as LWS resources (issue 1010 KR3). In
+// a browser worker its default transport is a synchronous XMLHttpRequest.
+export { lwsSbm11Reader };
+
 // RDF and SPARQL
 export const parse = api.parse;
 export const query = api.query;
@@ -102,6 +114,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,190 @@ 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>>;
+}
+
+/** The engine's check of a list of stages (op pipelineCheck, Lean pipelineReport). */
+export interface PipelineCheck {
+  /** Each stage's output wire is the next stage's input wire or converts to it (Lean wellTyped_iff). */
+  readonly wellTyped: boolean;
+  readonly wireIn: string | null;
+  readonly wireOut: string | null;
+  /** The first stage `at` whose output does not feed stage `at + 1`. */
+  readonly mismatch: { readonly at: number; readonly out: string; readonly in: string } | null;
+  /** Where an output reaches the next input by a named conversion (Dataflow/Wire.lean). */
+  readonly conversions: readonly { readonly at: number; readonly from: string; readonly to: string }[];
+  /** The union of the stages' named assumptions: the premises of Pipeline.guarantee_sound. */
+  readonly assumptions: readonly string[];
+  readonly contract: { readonly theorem: string; readonly stages: readonly (string | null)[] };
+  readonly stages: readonly {
+    readonly name: string; readonly status: StageInfo['status']; readonly checked: boolean;
+    readonly contract: string | null; readonly assumptions: readonly string[];
+    readonly wireIn: string; readonly wireOut: string;
+  }[];
+}
+
+/**
+ * A pipeline: nodes in order. `check` is the engine's op pipelineCheck;
+ * `assumptions` and `wellTyped` are its fields. With an engine that has no
+ * such op, `check` and `wellTyped` are null and `assumptions` is the union
+ * of the nodes' assumptions.
+ */
+export interface Pipeline {
+  readonly nodes: readonly FactoidalNode[];
+  readonly assumptions: readonly string[];
+  readonly wellTyped: boolean | null;
+  readonly check: PipelineCheck | null;
+}
+
+/** The result of run(): the last graph, one record per node, the assumption union. */
+export interface RunResult<G = unknown> extends Wire<G> {
+  /** The assumptions of the records on the input wire, then the engine's union for the pipeline (op pipelineCheck). */
+  assumptions: string[];
+  /** true iff every evidence record is checked (status 'proved') and the pipeline is well typed. */
+  proved: boolean;
+  /** The engine's type check of the pipeline; null when the engine has no op pipelineCheck. */
+  wellTyped: boolean | null;
+  /** 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, or when the engine's check finds the pipeline not
+ * well typed (unless `options.unchecked`; then `proved` is false).
+ */
+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 +873,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 +897,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 +1093,74 @@ 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;
+  /** the resources the reader read, when its reader records them (lwsSbm11Reader) */
+  readonly evidence: Sbm11ReadEvidence[] | undefined;
+  close(): void;
+}
+
+/** Open an SBM11 generation (https://github.com/danbri/factoidal/issues/1009).
+ * Node: `source` is a directory unless a reader is given or registered. */
+export function openSbm11(source: string, options?: { reader?: Sbm11Reader }): Promise<Sbm11Store>;
+
+/** Serve `source` with `reader`; `null` removes it. */
+export function registerSbm11Source(source: string, reader: Sbm11Reader | null): void;
+
+/** One LWS resource an SBM11 reader read (https://github.com/danbri/factoidal/issues/1010). */
+export interface Sbm11ReadEvidence {
+  resource: string;
+  etag: string;
+  lastModified: string | null;
+  /** HTTP requests made for this resource */
+  requests: number;
+  /** answers that were 206 Partial Content */
+  partial: number;
+  /** content bytes received */
+  bytes: number;
+}
+
+/** A synchronous HTTP GET: `(url, headers) -> answer`. */
+export type Sbm11Transport = (url: string, headers: Record<string, string>) =>
+  { status: number; header(name: string): string | null; bytes: Uint8Array };
+
+/** A reader of the SBM11 files held as LWS resources under the container
+ * `url` (one resource per file, CURRENT a resource too), by HTTP Range GETs
+ * when the server answers 206, else by whole GETs kept in memory. Node: the
+ * default transport is a fetch in a worker thread; close() stops it. */
+export function lwsSbm11Reader(url: string, opts?: {
+  auth?: string; headers?: Record<string, string>; transport?: Sbm11Transport; timeoutMs?: number
+}): Sbm11Reader & { evidence(): Sbm11ReadEvidence[]; errors(): string[]; close(): void };
+
 /** One query against a store: open with the query's plan, query, close. */
 export function queryStore(
   source: string | StoreReader,
@@ -1302,6 +1566,10 @@ export function capabilities(): Promise<{
   shacl: boolean;
   shex: boolean;
   owlClosure: boolean;
+  explain: boolean;
+  stages: boolean;
+  /** The op pipelineCheck: pipe() and run() use the engine's type check and assumption union. */
+  pipelineCheck: boolean;
   tableau: boolean;
   rml: boolean;
   csvw: boolean;

package/index.mjs

@@ -21,6 +21,10 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { buildApi } from './lib/api.mjs';
 import { entryFromEngine } from './lib/lean-entry.mjs';
+import { sbm11Api, registerSbm11Source, setDefaultSbm11Reader } from './lib/sbm11.mjs';
+import { nodeDefaultReaderFactory } from './lib/sbm11-node.mjs';
+import { lwsSbm11Reader as lwsSbm11ReaderWith } from './lib/sbm11-lws.mjs';
+import { nodeSyncTransport } from './lib/sync-http-node.mjs';
 
 /**
  * The loaded Lean engine handle: `call(op, args)`, `callBlob`,
@@ -66,6 +70,23 @@ export const clearExtensionFunctions = api.clearExtensionFunctions;
 export const registerServiceEndpoint = api.registerServiceEndpoint;
 export const clearServiceEndpoints = api.clearServiceEndpoints;
 
+// SBM11, the Shardborough store, through host positioned reads
+// (lib/sbm11.mjs; https://github.com/danbri/factoidal/issues/1009). In Node a
+// source with no registered reader is a directory.
+setDefaultSbm11Reader(nodeDefaultReaderFactory());
+export const openSbm11 = sbm11Api(loadEngine).openSbm11;
+export { registerSbm11Source };
+
+// A reader of an SBM11 generation held as LWS resources (lib/sbm11-lws.mjs;
+// https://github.com/danbri/factoidal/issues/1010 KR3). In Node the default
+// synchronous transport is a fetch in a worker thread (lib/sync-http-node.mjs),
+// stopped by the reader's close().
+export function lwsSbm11Reader(url, opts = {}) {
+  if (typeof opts.transport === 'function') return lwsSbm11ReaderWith(url, opts);
+  const transport = nodeSyncTransport({ timeoutMs: opts.timeoutMs });
+  return lwsSbm11ReaderWith(url, { ...opts, transport, onClose: () => transport.close() });
+}
+
 // The persisted store
 export const openStore = api.openStore;
 export const queryStore = api.queryStore;
@@ -86,6 +107,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 = "06c67c273257";
 
 import createModule from './l4factoidal.mjs';