@factoidal/core 0.7.1 → 0.11.0

package/index.js

@@ -1,237 +1,7 @@
-// factoidal — formally-verified SPARQL 1.1 + RDF 1.1 for Node.
-//
-// CommonJS entry point (js_of_ocaml engine). Public API:
-//
-//   parse(text, {format, baseIRI})      -> Promise<Dataset>
-//   query(data, sparql, {entail})       -> Promise<Bindings[] | boolean | Dataset>
-//   queryHdt(hdtBytes, sparql)          -> Promise<Bindings[] | boolean>
-//                                          (read-only HDT artifact, CLI-only,
-//                                          no npm-entry bundle needed)
-//   update(data, updateText)            -> Promise<Dataset>
-//   serialize(data, {format})           -> Promise<string>
-//   canonicalize(data, {format})        -> Promise<string>   (RDFC-1.0)
-//   graphs(dataset)                     -> Array<[iri, Dataset]>  (named graphs)
-//   canonicalHash(datasetOrGraph)       -> Promise<string>   (RDFC-1.0, one graph)
-//   shaclValidate(data, shapes)         -> Promise<{conforms, report: Dataset}>
-//   shexValidate(data, schema, focus, shape) -> Promise<boolean|null>
-//   owlClosure(data, mode)              -> Promise<Dataset>  ('RDFS'|'OWL-RL')
-//   rmlMap(mapping, sourceData, kind)   -> Promise<Dataset>  (kind: 'json'|'csv')
-//   csvwToRdf(csvText, metadataJson, options) -> Promise<Dataset>  (CSVW csv2rdf)
-//   jsonldToRdf(jsonldText, options)    -> Promise<Dataset>
-//   rifEval(data, rifRulesXml)          -> Promise<Dataset>  (RIF Core saturation)
-//   openCottas(bytes)                   -> Promise<string>   (handle; bytes is
-//                                          hex|Uint8Array|ArrayBuffer of a
-//                                          whole .cottas artifact)
-//   queryCottas(handle, sparql)         -> Promise<Bindings[] | boolean | Dataset>
-//                                          (in-memory COTTAS bytes store --
-//                                          rows decode lazily, no heap Dataset)
-//   closeCottas(handle)                 -> Promise<void>
-//   toCottas(data)                      -> Promise<Uint8Array>  (native COTTAS
-//                                          writer; round-trips into openCottas)
-//   dataFactory                         -> RDF/JS DataFactory
-//   Dataset                             -> RDF/JS DatasetCore class
-//
-// shaclValidate/shexValidate/owlClosure/rmlMap/csvwToRdf/jsonldToRdf/rifEval/
-// openCottas/queryCottas/closeCottas/toCottas need the npm-entry ABI bundle
-// (same gate as update()/canonicalize()); see capabilities() to probe for it.
-// See docs/designissues/2026-07-06-inmemory-bytes-store.md for the
-// openCottas/queryCottas/toCottas design and its documented divergences
-// from parse()/query() (no entailment, no write overlay, read-only).
-//
-// Bindings are Maps of variable name -> RDF/JS Term. See index.d.ts
-// for the full types and README.md for examples.
-//
-// The legacy single-shot API from 0.1.0-alpha scaffolding is kept as
-// queryRaw(dataString, queryString, {dataFormat, entail, output}) —
-// it returns parsed SPARQL Results JSON (or a raw string for
-// non-JSON output formats).
-//
-// For the wasm engine with the same API, require('factoidal/wasm').
+// @factoidal/core for require(). The ES module index.mjs is the source;
+// Node 22.12 and later load it through require(), so CommonJS and ES module
+// callers share one module instance (one engine, one `Dataset` class).
 
 'use strict';
 
-const fs = require('node:fs');
-const path = require('node:path');
-
-const engine = require('./lib/engine-js.js');
-const { buildApi } = require('./lib/api.js');
-const rdfjs = require('./rdfjs.js');
-
-const pkg = require('./package.json');
-const version = pkg.version;
-
-// ---------------------------------------------------------------------
-// npm-entry ABI loader. The entry bundle (built from
-// bin/npm-entry/entry_jsoo.ml) registers `factoidalNpmEntry` on
-// module.exports (Node) / globalThis (browser). Optional — everything
-// the CLI bundle can do works without it.
-// ---------------------------------------------------------------------
-
-function entryCandidates() {
-  const c = [];
-  if (process.env.FACTOIDAL_NPM_ENTRY) c.push(process.env.FACTOIDAL_NPM_ENTRY);
-  c.push(path.join(__dirname, 'factoidal-npm-entry.js'));
-  c.push(path.resolve(
-    __dirname, '..', '..', 'docs', 'fstar-extracted', 'factoidal-npm-entry.js'));
-  return c;
-}
-
-function loadEntry() {
-  for (const p of entryCandidates()) {
-    if (!p || !fs.existsSync(p)) continue;
-    const mod = require(p);
-    const abi = (mod && mod.factoidalNpmEntry) ||
-      (globalThis.factoidalNpmEntry);
-    if (abi && typeof abi.queryDataset === 'function') return abi;
-  }
-  return null;
-}
-
-const api = buildApi({
-  engineName: 'js',
-  runCli: engine.runCli,
-  loadEntry,
-  // VC crypto init hook: the typed vc* wrappers auto-await this once,
-  // on the first VC call, so a Node caller never has to remember the
-  // HACL* wasm init step. initHacl() is idempotent + memoized.
-  initCrypto: () => require('./hacl-init.js').initHacl(),
-});
-
-// ---------------------------------------------------------------------
-// Legacy raw API (pre-RDF/JS scaffolding surface, kept for the smoke
-// tests and for callers that want the CLI's other output formats).
-// ---------------------------------------------------------------------
-
-const OUTPUT_FORMATS = new Set(['json', 'csv', 'tsv', 'xml', 'table', 'ntriples']);
-const ENTAIL_VALUES = new Set(['none', 'RDFS', 'OWL-RL']);
-const DATA_FORMAT_EXT = {
-  turtle: 'ttl', ttl: 'ttl', ntriples: 'nt', nt: 'nt', nquads: 'nq',
-  nq: 'nq', trig: 'trig', rdfxml: 'rdf', 'rdf-xml': 'rdf', rdf: 'rdf',
-};
-
-function queryRaw(dataString, queryString, options) {
-  return Promise.resolve().then(() => {
-    if (typeof dataString !== 'string') {
-      throw new TypeError('queryRaw: dataString must be a string');
-    }
-    if (typeof queryString !== 'string') {
-      throw new TypeError('queryRaw: queryString must be a string');
-    }
-    const opts = options || {};
-    const dataFormat = String(opts.dataFormat || 'turtle').toLowerCase();
-    const entail = opts.entail || 'none';
-    const output = opts.output || 'json';
-    if (!(dataFormat in DATA_FORMAT_EXT)) {
-      throw new TypeError(`queryRaw: unknown dataFormat '${opts.dataFormat}'`);
-    }
-    if (!ENTAIL_VALUES.has(entail)) {
-      throw new TypeError(
-        `queryRaw: entail must be one of ${[...ENTAIL_VALUES].join(', ')}`);
-    }
-    if (!OUTPUT_FORMATS.has(output)) {
-      throw new TypeError(
-        `queryRaw: output must be one of ${[...OUTPUT_FORMATS].join(', ')}`);
-    }
-
-    const name = `/static/data.${DATA_FORMAT_EXT[dataFormat]}`;
-    const args = ['-d', name, '-e', queryString, '-o', output];
-    if (entail !== 'none') args.push('--entail', entail);
-
-    const res = engine.runCli(args, [{ name, content: dataString }]);
-    if (res.exitCode !== 0) {
-      const msg = (res.stderr || res.stdout ||
-        `factoidal exited with code ${res.exitCode}`).trim();
-      const err = new Error('SPARQL query failed: ' + msg);
-      err.exitCode = res.exitCode;
-      err.stderr = res.stderr;
-      err.stdout = res.stdout;
-      throw err;
-    }
-    if (output !== 'json') return res.stdout;
-
-    const first = res.stdout.indexOf('{');
-    const last = res.stdout.lastIndexOf('}');
-    if (first < 0 || last < first) {
-      const err = new Error(
-        'factoidal did not produce JSON on stdout. Raw output: ' + res.stdout);
-      err.stdout = res.stdout;
-      err.stderr = res.stderr;
-      throw err;
-    }
-    return JSON.parse(res.stdout.slice(first, last + 1));
-  });
-}
-
-module.exports = {
-  // Public typed API
-  parse: api.parse,
-  query: api.query,
-  queryHdt: api.queryHdt,
-  registerExtensionFunction: api.registerExtensionFunction,
-  unregisterExtensionFunction: api.unregisterExtensionFunction,
-  clearExtensionFunctions: api.clearExtensionFunctions,
-  registerServiceEndpoint: api.registerServiceEndpoint,
-  clearServiceEndpoints: api.clearServiceEndpoints,
-  update: api.update,
-  serialize: api.serialize,
-  canonicalize: api.canonicalize,
-  graphs: api.graphs,
-  canonicalHash: api.canonicalHash,
-  shaclValidate: api.shaclValidate,
-  shexValidate: api.shexValidate,
-  owlClosure: api.owlClosure,
-  coreRdfsClosure: api.coreRdfsClosure,
-  rdfsPlusClosure: api.rdfsPlusClosure,
-  coreRdfsCheck: api.coreRdfsCheck,
-  rhoDfClosure: api.rhoDfClosure,
-  rhoDfFragmentCheck: api.rhoDfFragmentCheck,
-  tableauMaterialise: api.tableauMaterialise,
-  tableauDlInconsistent: api.tableauDlInconsistent,
-  owlIsConsistent: api.owlIsConsistent,
-  owlEntails: api.owlEntails,
-  rmlMap: api.rmlMap,
-  csvwToRdf: api.csvwToRdf,
-  jsonldToRdf: api.jsonldToRdf,
-  jsonldFromRdf: api.jsonldFromRdf,
-  didKeyResolve: api.didKeyResolve,
-  xmlWellformed: api.xmlWellformed,
-  xpathEval: api.xpathEval,
-  rifEval: api.rifEval,
-  xsltTransform: api.xsltTransform,
-  mathmlEval: api.mathmlEval,
-  xformsRecalc: api.xformsRecalc,
-  jsonSchemaValidate: api.jsonSchemaValidate,
-  schematronValidate: api.schematronValidate,
-  toanSummation: api.toanSummation,
-  toanProduct: api.toanProduct,
-  toanSimplify: api.toanSimplify,
-  toanDiff: api.toanDiff,
-  toanSubst: api.toanSubst,
-  matrixDeterminant: api.matrixDeterminant,
-  matrixScalarProduct: api.matrixScalarProduct,
-  matrixVectorProduct: api.matrixVectorProduct,
-  matrixOuterProduct: api.matrixOuterProduct,
-  sigmoidPoints: api.sigmoidPoints,
-  sigmoidFormulaMathml: api.sigmoidFormulaMathml,
-  vcSha256Hex: api.vcSha256Hex,
-  vcEd25519SecretToPublic: api.vcEd25519SecretToPublic,
-  vcEd25519Sign: api.vcEd25519Sign,
-  vcEd25519Verify: api.vcEd25519Verify,
-  vcEddsaCreateFromCanonical: api.vcEddsaCreateFromCanonical,
-  vcEddsaVerifyFromCanonical: api.vcEddsaVerifyFromCanonical,
-  vcCheckCredential: api.vcCheckCredential,
-  vcCheckCredentialSubject: api.vcCheckCredentialSubject,
-  vcCheckNoDataLoss: api.vcCheckNoDataLoss,
-  vcCheckRelatedResourceDigests: api.vcCheckRelatedResourceDigests,
-  openCottas: api.openCottas,
-  queryCottas: api.queryCottas,
-  closeCottas: api.closeCottas,
-  toCottas: api.toCottas,
-  capabilities: api.capabilities,
-  Dataset: rdfjs.Dataset,
-  dataFactory: rdfjs.dataFactory,
-  // Legacy raw surface
-  queryRaw,
-  // Metadata
-  version,
-};
+module.exports = require('./index.mjs');

package/index.mjs

@@ -1,85 +1,181 @@
-// ESM entry point. Re-exports the CJS implementation so we have one
-// source of truth for the Node-side driver. Browsers should import
-// `./browser.js` via the `"browser"` export condition instead.
+// @factoidal/core — the Node entry (ES module). One engine: the Lean 4
+// library L4Factoidal (formal/lean4) compiled to WebAssembly.
 //
-// import { parse, query, canonicalize, dataFactory } from '@factoidal/core';
-// const ds = await parse('@prefix : <http://ex/> . :a :p :b .');
-// const rows = await query(ds, 'SELECT * WHERE { ?s ?p ?o }');
-
-import cjs from './index.js';
-
-export const parse         = cjs.parse;
-export const query         = cjs.query;
-export const queryHdt      = cjs.queryHdt;
-export const registerExtensionFunction   = cjs.registerExtensionFunction;
-export const unregisterExtensionFunction = cjs.unregisterExtensionFunction;
-export const clearExtensionFunctions     = cjs.clearExtensionFunctions;
-export const registerServiceEndpoint     = cjs.registerServiceEndpoint;
-export const clearServiceEndpoints       = cjs.clearServiceEndpoints;
-export const update        = cjs.update;
-export const serialize     = cjs.serialize;
-export const canonicalize  = cjs.canonicalize;
-export const graphs        = cjs.graphs;
-export const canonicalHash = cjs.canonicalHash;
-export const capabilities  = cjs.capabilities;
-export const Dataset       = cjs.Dataset;
-export const dataFactory   = cjs.dataFactory;
-export const queryRaw      = cjs.queryRaw;
-export const version       = cjs.version;
-
-// Validation / inference / mapping engines (need the npm-entry bundle).
-export const shaclValidate      = cjs.shaclValidate;
-export const shexValidate       = cjs.shexValidate;
-export const owlClosure         = cjs.owlClosure;
-export const coreRdfsClosure    = cjs.coreRdfsClosure;
-export const rdfsPlusClosure    = cjs.rdfsPlusClosure;
-export const coreRdfsCheck      = cjs.coreRdfsCheck;
-export const rhoDfClosure       = cjs.rhoDfClosure;
-export const rhoDfFragmentCheck = cjs.rhoDfFragmentCheck;
-export const tableauMaterialise = cjs.tableauMaterialise;
-export const tableauDlInconsistent = cjs.tableauDlInconsistent;
-export const owlIsConsistent    = cjs.owlIsConsistent;
-export const owlEntails         = cjs.owlEntails;
-export const rmlMap             = cjs.rmlMap;
-export const csvwToRdf          = cjs.csvwToRdf;
-export const jsonldToRdf        = cjs.jsonldToRdf;
-export const jsonldFromRdf      = cjs.jsonldFromRdf;
-export const didKeyResolve      = cjs.didKeyResolve;
-export const xmlWellformed      = cjs.xmlWellformed;
-export const xpathEval          = cjs.xpathEval;
-export const rifEval            = cjs.rifEval;
-
-// In-memory COTTAS/Parquet bytes store (need the npm-entry bundle).
-export const openCottas        = cjs.openCottas;
-export const queryCottas       = cjs.queryCottas;
-export const closeCottas       = cjs.closeCottas;
-export const toCottas          = cjs.toCottas;
-
-// Typed engine functions (#74 npm FP surface).
-export const xsltTransform       = cjs.xsltTransform;
-export const mathmlEval          = cjs.mathmlEval;
-export const xformsRecalc        = cjs.xformsRecalc;
-export const jsonSchemaValidate  = cjs.jsonSchemaValidate;
-export const schematronValidate  = cjs.schematronValidate;
-export const toanSummation       = cjs.toanSummation;
-export const toanProduct         = cjs.toanProduct;
-export const toanSimplify        = cjs.toanSimplify;
-export const toanDiff            = cjs.toanDiff;
-export const toanSubst           = cjs.toanSubst;
-export const matrixDeterminant   = cjs.matrixDeterminant;
-export const matrixScalarProduct = cjs.matrixScalarProduct;
-export const matrixVectorProduct = cjs.matrixVectorProduct;
-export const matrixOuterProduct  = cjs.matrixOuterProduct;
-export const sigmoidPoints        = cjs.sigmoidPoints;
-export const sigmoidFormulaMathml = cjs.sigmoidFormulaMathml;
-
-// VC Data Integrity crypto (eddsa-rdfc-2022, HACL* wasm backend). The
-// typed wrappers auto-await initHacl() on first call (see index.js).
-export const vcSha256Hex                = cjs.vcSha256Hex;
-export const vcEd25519SecretToPublic    = cjs.vcEd25519SecretToPublic;
-export const vcEd25519Sign              = cjs.vcEd25519Sign;
-export const vcEd25519Verify            = cjs.vcEd25519Verify;
-export const vcEddsaCreateFromCanonical = cjs.vcEddsaCreateFromCanonical;
-export const vcEddsaVerifyFromCanonical = cjs.vcEddsaVerifyFromCanonical;
-
-export default cjs;
+//   import { parse, query } from '@factoidal/core';
+//   const ds = await parse('@prefix : <http://ex/> . :a :p :b .');
+//   const rows = await query(ds, 'SELECT * WHERE { ?s ?p ?o }');
+//
+// The engine loads on the first call. Its three files sit in this
+// package's l4-assets/ (l4factoidal.js, l4factoidal.mjs,
+// l4factoidal.wasm); $FACTOIDAL_L4_ASSETS names another directory with
+// the same three files, and a repository checkout falls back to
+// docs/web/hub/assets/l4/ (bin/engine.mjs resolves them, for this module
+// and for the `factoidal` command, so both share one engine instance).
+//
+// index.js gives the same module to require(). browser.js is the browser
+// entry; api.mjs takes an engine the caller loaded itself.
+//
+// Types: index.d.ts. Every function is in lib/api.mjs.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildApi } from './lib/api.mjs';
+import { entryFromEngine } from './lib/lean-entry.mjs';
+
+/**
+ * The loaded Lean engine handle: `call(op, args)`, `callBlob`,
+ * `callBlobIO`, `version()`, over the dispatch ABI of
+ * formal/lean4/Wasm/Dispatch.lean. For the ops this package does not wrap
+ * (the `ops` op lists every name). Loaded once per process.
+ * @returns {Promise<object>}
+ */
+export async function loadEngine() {
+  // A dynamic import: bin/engine.mjs reads files through store-host/, which
+  // picks its Node or Deno implementation with a top-level await, and a
+  // module that require() loads may not have one in its static graph.
+  const mod = await import('./bin/engine.mjs');
+  return mod.loadEngine();
+}
+
+const api = buildApi({
+  engineName: 'lean4-wasm',
+  loadEntry: async () => entryFromEngine(await loadEngine()),
+  storeReaderFor: (root) => (path) => readFileSync(join(root, path)),
+});
+
+// RDF and SPARQL
+export const parse = api.parse;
+export const query = api.query;
+export const update = api.update;
+export const serialize = api.serialize;
+export const canonicalize = api.canonicalize;
+export const graphs = api.graphs;
+export const canonicalHash = api.canonicalHash;
+export const isomorphic = api.isomorphic;
+export const fromQuads = api.fromQuads;
+export const ready = api.ready;
+export const engineTables = api.engineTables;
+export const openDataset = api.openDataset;
+export const closure = api.closure;
+export const formats = api.formats;
+export const queryRaw = api.queryRaw;
+export const queryHdt = api.queryHdt;
+export const registerExtensionFunction = api.registerExtensionFunction;
+export const unregisterExtensionFunction = api.unregisterExtensionFunction;
+export const clearExtensionFunctions = api.clearExtensionFunctions;
+export const registerServiceEndpoint = api.registerServiceEndpoint;
+export const clearServiceEndpoints = api.clearServiceEndpoints;
+
+// The persisted store
+export const openStore = api.openStore;
+export const queryStore = api.queryStore;
+export const listStores = api.listStores;
+
+// The durable update log (hub post 18)
+export const deltaLogOpen = api.deltaLogOpen;
+export const deltaLogAppend = api.deltaLogAppend;
+export const deltaLogReadAllHex = api.deltaLogReadAllHex;
+export const deltaLogMerge = api.deltaLogMerge;
+export const deltaLogInspect = api.deltaLogInspect;
+export const deltaLogDestroy = api.deltaLogDestroy;
+export const _deltaLogCorruptLastForTest = api._deltaLogCorruptLastForTest;
+
+// Validation and reasoning
+export const shaclValidate = api.shaclValidate;
+export const shexValidate = api.shexValidate;
+export const owlClosure = api.owlClosure;
+export const coreRdfsClosure = api.coreRdfsClosure;
+export const coreRdfsCheck = api.coreRdfsCheck;
+export const rdfsPlusClosure = api.rdfsPlusClosure;
+export const rhoDfClosure = api.rhoDfClosure;
+export const rhoDfFragmentCheck = api.rhoDfFragmentCheck;
+export const tableauMaterialise = api.tableauMaterialise;
+export const tableauDlInconsistent = api.tableauDlInconsistent;
+export const owlIsConsistent = api.owlIsConsistent;
+export const owlEntails = api.owlEntails;
+export const rifEval = api.rifEval;
+
+// Mappings and other formats
+export const rmlMap = api.rmlMap;
+export const csvwToRdf = api.csvwToRdf;
+export const jsonldToRdf = api.jsonldToRdf;
+export const jsonldFromRdf = api.jsonldFromRdf;
+export const xmlWellformed = api.xmlWellformed;
+export const xpathEval = api.xpathEval;
+export const xsltTransform = api.xsltTransform;
+export const schematronValidate = api.schematronValidate;
+export const jsonSchemaValidate = api.jsonSchemaValidate;
+export const mathmlEval = api.mathmlEval;
+export const xformsRecalc = api.xformsRecalc;
+
+// Common Logic
+export const clParse = api.clParse;
+export const clSerialize = api.clSerialize;
+export const clAlphaNorm = api.clAlphaNorm;
+export const clNormalize = api.clNormalize;
+
+// Maths
+export const toanSummation = api.toanSummation;
+export const toanProduct = api.toanProduct;
+export const toanSimplify = api.toanSimplify;
+export const toanDiff = api.toanDiff;
+export const toanSubst = api.toanSubst;
+
+// Verifiable Credentials and DID
+export const vcSha256Hex = api.vcSha256Hex;
+export const vcEd25519SecretToPublic = api.vcEd25519SecretToPublic;
+export const vcEd25519Sign = api.vcEd25519Sign;
+export const vcEd25519Verify = api.vcEd25519Verify;
+export const vcEddsaCreateFromCanonical = api.vcEddsaCreateFromCanonical;
+export const vcEddsaVerifyFromCanonical = api.vcEddsaVerifyFromCanonical;
+export const vcCheckCredential = api.vcCheckCredential;
+export const vcCheckCredentialSubject = api.vcCheckCredentialSubject;
+export const vcCheckNoDataLoss = api.vcCheckNoDataLoss;
+export const vcCheckRelatedResourceDigests = api.vcCheckRelatedResourceDigests;
+export const didKeyResolve = api.didKeyResolve;
+
+// Types, probes and metadata
+export const capabilities = api.capabilities;
+export const Dataset = api.Dataset;
+export const DatasetHandle = api.DatasetHandle;
+export const Store = api.Store;
+export const ParseError = api.ParseError;
+export const dataFactory = api.dataFactory;
+export const version = api.version;
+export const engine = api.engine;
+
+export default api;
+
+// Pure functions over engine ops added in 0.10.0 (lib/pure.mjs).
+import { buildPure } from './lib/pure.mjs';
+const pure = buildPure(loadEngine);
+export const aeadSeal = pure.aeadSeal;
+export const aeadOpen = pure.aeadOpen;
+export const hpkeSeal = pure.hpkeSeal;
+export const hpkeOpen = pure.hpkeOpen;
+export const proofCheck = pure.proofCheck;
+export const proofInspect = pure.proofInspect;
+export const canonicalizeNQuads = pure.canonicalizeNQuads;
+export const normalizeNQuads = pure.normalizeNQuads;
+
+/**
+ * Serve an activated store (a collection root that holds CURRENT) over the
+ * SPARQL 1.1 Protocol, the Graph Store Protocol and the Service
+ * Description: the same server as `factoidal serve STORE`. Node only.
+ * With `{tdb2: true}`, `root` is an Apache Jena TDB2 database directory,
+ * read in place and served read only (updates answer 501;
+ * https://github.com/danbri/factoidal/issues/834).
+ * @param {string} root
+ * @param {{port?: number, host?: string, queryPath?: string, gspPath?: string,
+ *          tdb2?: boolean}} [options] port 0 (default) picks one
+ * @returns {Promise<{url: string, port: number, close: () => Promise<void>}>}
+ */
+export async function serveStore(root, options = {}) {
+  const { listen } = await import('./bin/serve.mjs');
+  const s = await listen(root, { ...options, engine: await loadEngine() });
+  return { url: `${s.origin}${options.queryPath ?? "/sparql"}`, port: s.port, close: () => s.close() };
+}
+
+// A small store packed on demand from triples held in sample-store.mjs (no
+// data file ships; owner, 2026-10-20). Node only.
+export { sampleStorePath, sampleStoreFacts } from './sample-store.mjs';

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 = "a7720d5d5630";
+const WASM_VERSION = "15eb8d770829";
 
 import createModule from './l4factoidal.mjs';
 
@@ -51,13 +51,28 @@ let modulePromise = null;
 // staleness this fixes can actually happen.
 const isNodeLike = !!(globalThis.process && globalThis.process.versions && globalThis.process.versions.node);
 
+/** The content-hash version of the wasm this loader was built with. */
+export const wasmVersion = WASM_VERSION;
+
 /**
  * Instantiate the Lean engine (once per module instance; repeated calls
- * return the same promise). Resolves to the API object.
+ * return the same promise, and options after the first call are ignored).
+ * Resolves to the API object.
+ *
+ * `options.instantiateWasm(imports)` replaces the glue's own fetch and
+ * compile: it receives the import object and answers a Promise of
+ * `{instance, module}`, the value of `WebAssembly.instantiateStreaming`.
+ * A page that serves the wasm from its own URL uses it:
+ *
+ *   loadL4({ instantiateWasm: (imports) =>
+ *     WebAssembly.instantiateStreaming(fetch(url), imports) });
+ *
+ * A rejection of that Promise rejects loadL4().
  */
-export function loadL4() {
+export function loadL4(options) {
   if (modulePromise) return modulePromise;
   modulePromise = (async () => {
+    const opts = options || {};
     const moduleArg = isNodeLike ? {} : {
       // Called by the Emscripten glue only to resolve the sibling
       // .wasm (see l4factoidal.mjs's findWasmBinary); appending the
@@ -69,7 +84,22 @@ export function loadL4() {
           : scriptDirectory + path;
       },
     };
-    const Module = await createModule(moduleArg);
+    // The glue calls Module.instantiateWasm(imports, receive) and waits for
+    // receive(); it has no failure path, so a failure is raced in here.
+    let instantiateFailed = null;
+    if (typeof opts.instantiateWasm === 'function') {
+      let fail;
+      instantiateFailed = new Promise((_resolve, reject) => { fail = reject; });
+      moduleArg.instantiateWasm = (imports, receive) => {
+        Promise.resolve()
+          .then(() => opts.instantiateWasm(imports))
+          .then((r) => receive(r.instance, r.module), fail);
+        return {};
+      };
+    }
+    const Module = instantiateFailed
+      ? await Promise.race([createModule(moduleArg), instantiateFailed])
+      : await createModule(moduleArg);
 
     const cVersion = Module.cwrap('l4_version_c', 'number', []);
     const cFree = Module.cwrap('l4_free_result', null, ['number']);
@@ -87,6 +117,16 @@ export function loadL4() {
 
     const asJson = (v) => (typeof v === 'string' ? v : JSON.stringify(v));
 
+    /**
+     * The Error thrown for an {"ok":false,...} envelope. The message is
+     * unchanged (`l4factoidal: <error>`); the WHOLE envelope rides along as
+     * `.envelope`, so a caller can read the members beyond `error` that some
+     * refusals carry (a parse failure's `line`, `column`, `offset` and
+     * `format`, https://github.com/danbri/factoidal/issues/685).
+     */
+    const refusal = (envelope) =>
+      Object.assign(new Error(`l4factoidal: ${envelope.error}`), { envelope });
+
     // Emscripten's cwrap `string` converter uses the WebAssembly stack.
     // Multi-megabyte RDF/block requests can therefore overflow STACK_SIZE
     // before Lean sees them. Allocate input UTF-8 on the wasm heap instead;
@@ -146,7 +186,7 @@ export function loadL4() {
         const resultPtr = callWithHeapStrings(Module._l4_call_c,
           [op, JSON.stringify(args)]);
         const parsed = JSON.parse(take(resultPtr));
-        if (parsed.ok === false) throw new Error(`l4factoidal: ${parsed.error}`);
+        if (parsed.ok === false) throw refusal(parsed);
         return parsed;
       },
 
@@ -180,7 +220,7 @@ export function loadL4() {
             (opPtr, argsPtr) => Module._l4_call_blob_c(opPtr, argsPtr, blobPtr, bytes.length),
             [op, JSON.stringify(args)]);
           const parsed = JSON.parse(take(resultPtr));
-          if (parsed.ok === false) throw new Error(`l4factoidal: ${parsed.error}`);
+          if (parsed.ok === false) throw refusal(parsed);
           return parsed;
         } finally {
           if (blobPtr) Module._free(blobPtr);
@@ -233,7 +273,7 @@ export function loadL4() {
           outPtr = Module.getValue(outCell, 'i32') >>> 0;
           const outLen = Module.getValue(outCell + 4, 'i32') >>> 0;
           const envelope = JSON.parse(take(resultPtr));
-          if (envelope.ok === false) throw new Error(`l4factoidal: ${envelope.error}`);
+          if (envelope.ok === false) throw refusal(envelope);
           // slice() copies; HEAPU8 is replaced wholesale when the
           // module's memory grows, so a view would not survive.
           const region = outPtr !== 0 && outLen > 0