@factoidal/core 0.13.0 → 0.15.0

package/lib/nodes.mjs

@@ -0,0 +1,274 @@
+// 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 type check and the assumption union are the engine's (op
+// pipelineCheck, formal/lean4/Wasm/Ops/StageList.lean, computed by
+// pipelineReport of formal/lean4/L4Factoidal/Dataflow/Pipeline.lean): a
+// pipeline is well typed when each stage's output wire is the next stage's
+// input wire or converts to it, and its `assumptions` are the premises of
+// Pipeline.guarantee_sound, the guarantee of any pipeline of components with
+// these signatures. This file does not compute the union. With an engine
+// built before the op, pipe() and run() fall back to the union of the
+// nodes' fields and report `wellTyped: null`.
+//
+// ES module, no Node built-ins: the browser loads this file as it is.
+
+import { FactoidalError } from './errors.mjs';
+import { refusalFor, makeRecord, summarize, unionAssumptions, unionLists } 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;
+  let engine = null; // the entry stages() loaded; node() calls stages(), so pipe() has it
+
+  /**
+   * 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');
+        engine = e;
+        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;
+  }
+
+  /**
+   * The engine's check of the stages of `nodes` in order (op pipelineCheck),
+   * or null when the loaded engine has no such op.
+   */
+  function check(nodes) {
+    if (!engine || typeof engine.pipelineCheck !== 'function') return null;
+    const r = entryResult(engine.pipelineCheck(JSON.stringify(nodes.map((n) => n.stage))), 'pipelineCheck');
+    return Object.freeze({
+      wellTyped: r.wellTyped,
+      wireIn: r.wireIn,
+      wireOut: r.wireOut,
+      mismatch: r.mismatch === null ? null : Object.freeze({ ...r.mismatch }),
+      conversions: Object.freeze(r.conversions.map((c) => Object.freeze({ ...c }))),
+      assumptions: Object.freeze([...r.assumptions]),
+      contract: Object.freeze({ theorem: r.contract.theorem, stages: Object.freeze([...r.contract.stages]) }),
+      stages: Object.freeze(r.stages.map((s) => Object.freeze({ ...s, assumptions: Object.freeze([...s.assumptions]) }))),
+    });
+  }
+
+  /**
+   * A pipeline: the nodes in order (pipelines are flattened). `check` is
+   * the engine's op pipelineCheck on the nodes' stages; `wellTyped` and
+   * `assumptions` (the union of the nodes' named assumptions) are its
+   * fields. Without the op: `check` and `wellTyped` are null and
+   * `assumptions` is the union of the nodes' fields.
+   * @returns {{nodes: object[], assumptions: string[], wellTyped: boolean|null, check: object|null}}
+   */
+  function pipe(...items) {
+    const nodes = nodesOf(items, 'pipe');
+    if (nodes.length === 0) throw new TypeError('pipe: no nodes');
+    const c = check(nodes);
+    return Object.freeze({
+      nodes: Object.freeze(nodes),
+      assumptions: c ? c.assumptions : Object.freeze(unionAssumptions(nodes)),
+      wellTyped: c ? c.wellTyped : null,
+      check: c,
+    });
+  }
+
+  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, and so does a pipeline that the engine's
+   * check finds not well typed (op pipelineCheck); with it such a pipeline
+   * runs and `proved` is false.
+   * `assumptions`: the assumptions of the records on the input wire, then
+   * the engine's union for this pipeline (op pipelineCheck), no duplicate.
+   * @returns {Promise<{graph: any, evidence: object[], assumptions: string[],
+   *   proved: boolean, uncheckedSteps: string[], wellTyped: boolean|null}>}
+   */
+  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;
+    }
+    const c = check(nodes);
+    if (c && !c.wellTyped && !unchecked) {
+      const m = c.mismatch;
+      throw new FactoidalError(`run: the pipeline is not well typed: stage ${m.at} ` +
+        `(${nodes[m.at].stage}) writes ${m.out}, stage ${m.at + 1} (${nodes[m.at + 1].stage}) ` +
+        `reads ${m.in} (pass { unchecked: true } to run it without a guarantee)`, { code: 'op.failed' });
+    }
+    const prior = isWire(input) ? input.evidence : [];
+    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] };
+    }
+    const s = summarize(wire.evidence);
+    if (!c) return { graph: wire.graph, evidence: wire.evidence, ...s, wellTyped: null };
+    return {
+      graph: wire.graph,
+      evidence: wire.evidence,
+      assumptions: prior.length === 0 ? [...c.assumptions]
+        : unionLists([unionAssumptions(prior), c.assumptions]),
+      proved: s.proved && c.wellTyped,
+      uncheckedSteps: s.uncheckedSteps,
+      wellTyped: c.wellTyped,
+    };
+  }
+
+  return { stages, node, pipe, run };
+}

package/lib/sbm11-lws.mjs

@@ -0,0 +1,200 @@
+// The LWS reader of an SBM11 generation for lib/sbm11.mjs: the files of a
+// generation (or of a collection root with its CURRENT pointer) stored as
+// Linked Web Storage resources, one resource per file, under one container
+// URL (https://github.com/danbri/factoidal/issues/1010 KR3, read part;
+// LWS 1.0: https://w3c.github.io/lws-protocol/lws10-core/).
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Move bytes. The engine names every file and checks every length against
+// the manifest (formal/lean4/L4Factoidal/Storage/Sbm11/HostSession.lean,
+// through the storage medium of formal/lean4/L4Factoidal/Storage/Medium.lean).
+// This file maps a file name to a resource URL, makes HTTP GETs, and hands
+// the bytes over. It reads no manifest and no byte of a file.
+//
+// HTTP (RFC 9110 section 14): each read asks for `Range: bytes=a-b`. A
+// partial answer is used only when it is status 206 and its Content-Range is
+// exactly `bytes a-b/N`. Any other successful answer is the whole
+// representation: it is kept in memory and every later read of that file is
+// cut from it, with no further request. A changed entity tag between two
+// reads of one file refuses the read (the bytes of two versions are never
+// mixed). Limits: no Merkle check here (the engine's Verify.none path), no
+// eviction of the in-memory copies, no retry.
+//
+// EVIDENCE
+// `evidence()` lists each resource read: { resource, etag, lastModified,
+// requests, partial, bytes } -- `partial` the number of 206 answers. The
+// store from openSbm11 answers it as `store.evidence`.
+//
+// SYNCHRONOUS TRANSPORT
+// The engine is inside WebAssembly and asks for bytes synchronously, so the
+// reader needs a synchronous GET: `transport(url, headers) -> { status,
+// header(name) -> string | null, bytes: Uint8Array }`. In Node the default
+// is lib/sync-http-node.mjs (fetch in a worker thread, Atomics.wait); in a
+// browser worker it is a synchronous XMLHttpRequest. A browser window
+// thread has neither: pass `transport` or run the engine in a worker.
+
+function containerUrl (url) {
+  const s = String(url)
+  return s.endsWith('/') ? s : s + '/'
+}
+
+function resourceUrl (base, file) {
+  return new URL(String(file).split('/').map(encodeURIComponent).join('/'), base).href
+}
+
+/** A synchronous GET with XMLHttpRequest (a browser worker). */
+export function xhrSyncTransport (url, headers) {
+  const x = new XMLHttpRequest()
+  x.open('GET', url, false)
+  x.responseType = 'arraybuffer'
+  for (const [k, v] of Object.entries(headers)) x.setRequestHeader(k, v)
+  x.send()
+  return {
+    status: x.status,
+    header: (name) => x.getResponseHeader(name),
+    bytes: new Uint8Array(x.response || new ArrayBuffer(0))
+  }
+}
+
+function parseContentRange (value) {
+  const m = /^bytes\s+(\d+)-(\d+)\/(\d+|\*)$/.exec(String(value || '').trim())
+  if (!m) return null
+  return { first: Number(m[1]), last: Number(m[2]), total: m[3] === '*' ? null : Number(m[3]) }
+}
+
+function unsatisfiedTotal (value) {
+  const m = /^bytes\s+\*\/(\d+)$/.exec(String(value || '').trim())
+  return m ? Number(m[1]) : null
+}
+
+/**
+ * A reader ({ readAt, size, evidence, close }) of the SBM11 files held as
+ * LWS resources under the container `url`.
+ *
+ * @param {string} url the container that holds CURRENT and the generation
+ *   (or the generation container itself)
+ * @param {object} [opts]
+ * @param {Function} [opts.transport] the synchronous GET (see above)
+ * @param {string} [opts.auth] a value for the Authorization header, such as
+ *   `Bearer <access token>` (an LWS access token)
+ * @param {object} [opts.headers] further request headers
+ */
+export function lwsSbm11Reader (url, opts = {}) {
+  const base = containerUrl(url)
+  let transport = opts.transport
+  if (typeof transport !== 'function') {
+    if (typeof XMLHttpRequest === 'function' && typeof document === 'undefined') {
+      transport = xhrSyncTransport
+    } else {
+      throw new TypeError('lwsSbm11Reader: no synchronous transport here; pass opts.transport (Node: @factoidal/core gives one)')
+    }
+  }
+  const extra = { ...(opts.headers || {}) }
+  if (opts.auth) extra.authorization = String(opts.auth)
+  // file -> { url, etag, lastModified, total, whole, requests, partial, bytes }
+  const files = new Map()
+  const errors = []
+
+  function entry (file) {
+    let e = files.get(file)
+    if (!e) {
+      e = { url: resourceUrl(base, file), etag: null, lastModified: null, total: undefined, whole: null, requests: 0, partial: 0, bytes: 0 }
+      files.set(file, e)
+    }
+    return e
+  }
+
+  function fail (file, message) {
+    errors.push(`${file}: ${message}`)
+    return null
+  }
+
+  function get (e, file, first, last) {
+    const headers = { ...extra, range: `bytes=${first}-${last}` }
+    let r
+    try {
+      r = transport(e.url, headers)
+    } catch (error) {
+      fail(file, `GET ${e.url}: ${error && error.message ? error.message : error}`)
+      return null
+    }
+    e.requests += 1
+    const tag = r.header('etag')
+    if (r.status >= 200 && r.status < 300) {
+      if (e.etag !== null && tag !== e.etag) {
+        fail(file, `the entity tag changed from ${e.etag} to ${tag}`)
+        return null
+      }
+      e.etag = tag
+      e.lastModified = r.header('last-modified')
+      e.bytes += r.bytes.length
+    }
+    return r
+  }
+
+  function sizeOf (file) {
+    const e = entry(file)
+    if (e.total !== undefined) return e.total
+    const r = get(e, file, 0, 0)
+    if (r === null) return null
+    const cr = parseContentRange(r.header('content-range'))
+    if (r.status === 206 && cr && cr.first === 0 && cr.last === 0 && cr.total !== null && r.bytes.length === 1) {
+      e.partial += 1
+      e.total = cr.total
+    } else if (r.status === 416 && unsatisfiedTotal(r.header('content-range')) !== null) {
+      e.total = unsatisfiedTotal(r.header('content-range'))
+      e.whole = new Uint8Array(0)
+    } else if (r.status === 200) {
+      e.whole = r.bytes
+      e.total = r.bytes.length
+    } else if (r.status === 404 || r.status === 410) {
+      e.total = null
+    } else {
+      fail(file, `GET ${e.url}: status ${r.status}`)
+      return null
+    }
+    return e.total
+  }
+
+  return {
+    readAt (file, offset, length) {
+      const e = entry(file)
+      if (length === 0) return new Uint8Array(0)
+      if (e.whole !== null) {
+        return offset + length <= e.whole.length ? e.whole.subarray(offset, offset + length) : null
+      }
+      const last = offset + length - 1
+      const r = get(e, file, offset, last)
+      if (r === null) return null
+      const cr = parseContentRange(r.header('content-range'))
+      if (r.status === 206 && cr && cr.first === offset && cr.last === last && r.bytes.length === length) {
+        e.partial += 1
+        return r.bytes
+      }
+      if (r.status === 200) {
+        e.whole = r.bytes
+        e.total = r.bytes.length
+        return offset + length <= r.bytes.length ? r.bytes.subarray(offset, offset + length) : null
+      }
+      return fail(file, `GET ${e.url} bytes ${offset}-${last}: status ${r.status}`)
+    },
+    size (file) {
+      return sizeOf(file)
+    },
+    /** Each resource read: { resource, etag, lastModified, requests, partial, bytes }. */
+    evidence () {
+      const out = []
+      for (const e of files.values()) {
+        if (e.requests === 0 || e.etag === null) continue
+        out.push({ resource: e.url, etag: e.etag, lastModified: e.lastModified, requests: e.requests, partial: e.partial, bytes: e.bytes })
+      }
+      return out
+    },
+    /** The transport failures, as text (a failed read reaches the engine as no bytes). */
+    errors () { return errors.slice() },
+    close () {
+      files.clear()
+      if (typeof opts.onClose === 'function') opts.onClose()
+    }
+  }
+}

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,155 @@
+// 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
+    const reader = options.reader || readers.get(String(source))
+    return {
+      handle,
+      /** The resources the reader read (`lwsSbm11Reader`): `[{ resource,
+       *  etag, lastModified, requests, partial, bytes }]`; undefined for a
+       *  reader that records none. */
+      get evidence () {
+        return reader && typeof reader.evidence === 'function' ? reader.evidence() : undefined
+      },
+      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 }
+}