@factoidal/core 0.10.0 → 0.12.0

package/lib/api.mjs

@@ -22,66 +22,26 @@
 // JSDoc note "entry_jsoo.ml's X" below names that lineage. The Lean op of
 // the same name serves X now (formal/lean4/Wasm/Dispatch.lean lists them).
 
-import { dataFactory, termFromSrj, quadToNQuads } from '../rdfjs.mjs';
+import { dataFactory, termFromSrj, termToJson, quadToJson, _setTextEngine } from '../rdfjs.mjs';
 import { Dataset, INTERNAL, checkOptions, makeRegistry, WRITER_TAGS } from './dataset.mjs';
 import { version as packageVersion } from './version.mjs';
 import { openGeneration, readRegion, manifestKeys, hexOfBytes } from './store.mjs';
 import { fullEngineMessage } from './lean-entry.mjs';
 import { memoryDeltaLogStore } from './delta-log-hosts.mjs';
+import { FactoidalError, errorFromEnvelope, envelopeResult } from './errors.mjs';
 
-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',
-  jsonld:    'jsonld',
-  'json-ld': 'jsonld',
-  // RDF 1.2 opt-in: these select the engine's RDF 1.2 parsers (triple
-  // terms <<( s p o )>>, ~ reifiers, {| |} annotations, VERSION,
-  // directional literals "x"@lang--dir; Wasm/Ops/Parse.lean's
-  // `Mode.rdf12`); the plain names above stay RDF 1.1.
-  turtle12:   'ttl12',
-  ttl12:      'ttl12',
-  ntriples12: 'nt12',
-  nt12:       'nt12',
-  nquads12:   'nq12',
-  nq12:       'nq12',
-  trig12:     'trig12',
-};
-
-// Canonical format tag for the engine's parse ops (parseToDatasetJson,
-// datasetOpen); the *12 tags select the RDF 1.2 mode.
-const DATA_FORMAT_TAG = {
-  ttl: 'turtle', nt: 'ntriples', nq: 'nquads', trig: 'trig', rdf: 'rdfxml',
-  jsonld: 'jsonld',
-  ttl12: 'turtle12', nt12: 'ntriples12', nq12: 'nquads12', trig12: 'trig12',
-};
-
-const ENTAIL_VALUES = new Set(['none', 'RDFS', 'OWL-RL', 'x-rdfscore', 'x-rdfsplus']);
-
-// queryRaw's options (op queryRaw, Wasm/Ops/QueryExtras.lean).
-const RAW_OUTPUT_FORMATS = new Set(['json', 'csv', 'tsv', 'xml', 'table', 'ntriples']);
-const RAW_DATA_FORMATS = {
-  turtle: 'turtle', ttl: 'turtle', ntriples: 'ntriples', nt: 'ntriples',
-  nquads: 'nquads', nq: 'nquads', trig: 'trig', rdfxml: 'rdfxml',
-  'rdf-xml': 'rdfxml', rdf: 'rdfxml',
-};
+// The format names, regimes and query outputs are the engine's tables (op
+// engineTables, formal/lean4/Wasm/Ops/Handles.lean), read once per engine:
+// no host copy (https://github.com/danbri/factoidal/issues/894 item 5).
 
-function extForFormat(fmt) {
+// The parse tag a format name selects, from the engine's table.
+// A name outside the table is refused by the engine (op apiCheck,
+// code format.unknown).
+function parseTagOf(e, tables, fmt, who) {
   const key = String(fmt || 'turtle').toLowerCase();
-  if (!(key in DATA_FORMAT_EXT)) {
-    throw new TypeError(
-      `Unknown format '${fmt}'. Expected one of: ` +
-      Object.keys(DATA_FORMAT_EXT).join(', ')
-    );
-  }
-  return DATA_FORMAT_EXT[key];
+  const tag = tables.parseFormats[key];
+  if (tag === undefined) checkOptions(e, who || 'parse', { format: String(fmt) });
+  return tag;
 }
 
 // Where a function takes an options object, a bare string names the
@@ -102,28 +62,37 @@ function optionsOf(fn, options) {
 // package, or a dispatch table that does not serve it). When the entry is
 // the core engine and the op is one only the full engine serves, the error
 // names the entry that has it (issue 713 stage 4).
+// The engine's own answer to the op is the error (code op.unknown); an entry
+// with no engine handle to ask gets the same code.
 function missingOpError(what, e, op) {
-  if (e && e.profile === 'core' && op && Array.isArray(e.fullOnlyOps) &&
-      e.fullOnlyOps.includes(op)) {
-    return new Error(`${what}: ${fullEngineMessage(`the op '${op}'`)}`);
+  const eng = e && e.engine;
+  if (eng && typeof eng.call === 'function' && op) {
+    try {
+      eng.call(op, []);
+    } catch (err) {
+      if (err && err.envelope && err.envelope.code === 'op.unknown') {
+        const out = errorFromEnvelope(err.envelope);
+        if (e.profile === 'core' && Array.isArray(e.fullOnlyOps) && e.fullOnlyOps.includes(op)) {
+          out.message = `${what}: ${fullEngineMessage(`the op '${op}'`)}`;
+        }
+        return out;
+      }
+    }
   }
-  return new Error(
+  return new FactoidalError(
     `${what}: the loaded Lean wasm module has no dispatch op for this ` +
     'operation. The module is older than this package; rebuild it with ' +
     'formal/lean4/Wasm/build-wasm.sh, or point FACTOIDAL_L4_ASSETS at a ' +
-    'current build.');
+    'current build.', { code: 'op.unknown' });
 }
 
-// Detect the query form for result-shape dispatch. IRIs and comments
-// are blanked first so '#' inside a PREFIX IRI cannot hide the verb.
-// The engine's SPARQL parser remains the authority — this only picks
-// the output shape.
-function sniffQueryForm(sparql) {
-  const cleaned = String(sparql)
-    .replace(/<[^>]*>/g, ' ')
-    .replace(/#[^\n]*/g, ' ');
-  const m = cleaned.match(/\b(select|ask|construct|describe)\b/i);
-  return m ? m[1].toLowerCase() : 'select';
+// The query form, from the engine's SPARQL parser (op queryForm). A query
+// the parser rejects answers 'select'; the query op then reports the parse
+// error itself.
+function queryFormOf(e, sparql) {
+  if (typeof e.queryForm !== 'function') return 'select';
+  const r = JSON.parse(e.queryForm(String(sparql)));
+  return r.ok ? r.kind : 'select';
 }
 
 // Bytes for an op that reads the byte region (queryHdt, storeOpen): a
@@ -157,85 +126,23 @@ function bindingsFromSrj(srj) {
 }
 
 // ---------------------------------------------------------------------
-// Strict parsing (issue #344) -- ParseError, and the shared envelope
-// unwrapper every engine call routes through.
+// The envelope unwrapper every engine call routes through. A refusal is a
+// FactoidalError (lib/errors.mjs) whose code, spec section and position the
+// engine decided (formal/lean4/Wasm/Ops/ErrorModel.lean).
 // ---------------------------------------------------------------------
 
-/**
- * A parse failure that carries a position: `line`/`column`/`offset`
- * when the failing engine call reported one (a parseToDatasetJson or
- * datasetOpen error over Turtle, TriG, N-Triples or N-Quads), else
- * `undefined`. RDF/XML and JSON-LD failures, and any non-parse engine
- * error, stay plain Error -- entryResult() below decides which one to
- * throw.
- *
- * Units: `line` and `column` are 1-based; `column` counts Unicode scalar
- * values, as the engine reports it. `offset` is a UTF-16 code-unit index
- * into the input JavaScript string, so `text.slice(err.offset)` starts
- * at the error. The engine counts Unicode scalar values;
- * utf16OffsetOf() below converts.
- */
-class ParseError extends Error {
-  constructor(message, info) {
-    super(message);
-    this.name = 'ParseError';
-    const i = info || {};
-    this.line = i.line;
-    this.column = i.column;
-    this.offset = i.offset;
-    this.format = i.format;
-    if (typeof Error.captureStackTrace === 'function') {
-      Error.captureStackTrace(this, ParseError);
-    }
-  }
-}
-
-// Unwrap one dispatch-op JSON envelope ({"ok":true,...} |
-// {"ok":false,"error":...}). A `line` or `offset` member on the error
-// envelope means the failing call was a parse (Turtle/TriG/N-Triples/
-// N-Quads carry a position; RDF/XML and JSON-LD carry a message only)
-// -- throw ParseError so a caller can branch on position without
-// string-matching the message. Every other failure stays a plain
-// Error, as before. Pure (no per-driver state), so every buildApi()
-// instance and DatasetHandle share this one function.
-function entryResult(jsonText, what) {
-  const r = JSON.parse(jsonText);
-  if (!r.ok) {
-    if (r.line !== undefined || r.offset !== undefined) {
-      throw new ParseError(`${what}: ${r.error}`, {
-        line: r.line, column: r.column, offset: r.offset, format: r.format,
-      });
-    }
-    throw new Error(`${what}: ${r.error}`);
-  }
-  return r;
+function entryResult(jsonText, _what, text) {
+  return envelopeResult(jsonText, text);
 }
 
-// The Lean engine reports a parse error's `offset` as a count of Unicode
-// scalar values from the start of the input. A JavaScript string is
-// indexed in UTF-16 code units, where a character outside the Basic
-// Multilingual Plane (U+10000 and above) takes two. This converts the
-// engine's count into the UTF-16 index of the same position. A count past
-// the end of the text gives text.length. Iterating a string with for..of
-// yields one element per code point (a lone surrogate is one element, and
-// the engine reads it as one replacement character), so both sides count
-// the same units.
-function utf16OffsetOf(text, scalarOffset) {
-  if (typeof text !== 'string' || !Number.isInteger(scalarOffset) || scalarOffset < 0) {
-    return scalarOffset;
-  }
-  let units = 0;
-  let scalars = 0;
-  for (const ch of text) {
-    if (scalars >= scalarOffset) break;
-    units += ch.length;
-    scalars += 1;
-  }
-  return units;
+// entryResult() for an op that read `text`: the position's offset becomes a
+// UTF-16 index into `text`.
+function parseResult(jsonText, what, text) {
+  return entryResult(jsonText, what, text);
 }
 
 // The lenient parse's diagnostics (https://github.com/danbri/factoidal/issues/716)
-// with each `offset` converted as utf16OffsetOf() converts a ParseError's, so
+// with each `offset` converted to a UTF-16 index as a FactoidalError's, so
 // `text.slice(d.offset)` starts at the error. `line` and `column` are kept as
 // the engine reports them. One pass over `text` for all diagnostics: the
 // offsets are visited in increasing order, whatever order the list has.
@@ -263,23 +170,6 @@ function utf16Diagnostics(text, diagnostics) {
   return diagnostics.map((d, i) => (units.has(i) ? { ...d, offset: units.get(i) } : d));
 }
 
-// entryResult() for an op that parsed `text`: a positioned ParseError gets
-// its offset converted to a UTF-16 index into `text`.
-function parseResult(jsonText, what, text) {
-  try {
-    return entryResult(jsonText, what);
-  } catch (err) {
-    if (err instanceof ParseError && typeof err.offset === 'number') {
-      err.offset = utf16OffsetOf(text, err.offset);
-    }
-    throw err;
-  }
-}
-
-// DatasetHandle: the name of the engine-resident dataset class before
-// 0.10.0. Deprecated alias of Dataset, kept for 0.10.x only.
-const DatasetHandle = Dataset;
-
 // ---------------------------------------------------------------------
 // The Lean persisted store (Shardborough generations: IBK3, IBK4, IBK5
 // blocks with their index sidecars; skills/shardborough-storage). A
@@ -322,7 +212,8 @@ class Store {
   get closed() { return this._closed; }
 
   _assertOpen(who) {
-    if (this._closed) throw new Error(`Store.${who}: store handle '${this.handle}' is closed`);
+    // The engine answers handle.disposed for a closed store handle.
+    if (this._closed) entryResult(this._e.storeHandleClose(this.handle), `Store.${who}`);
   }
 
   /**
@@ -333,7 +224,7 @@ class Store {
   async query(sparql) {
     this._assertOpen('query');
     if (typeof sparql !== 'string') throw new TypeError('Store.query: sparql must be a string');
-    const run = () => entryResult(this._e.storeHandleQuery(this.handle, sparql), 'Store.query');
+    const run = () => entryResult(this._e.storeHandleQuery(this.handle, sparql), 'Store.query', sparql);
     const r = this._withExtensionRounds ? await this._withExtensionRounds(run) : run();
     if (r.kind === 'ask') return r.boolean;
     if (r.kind === 'construct' || r.kind === 'describe') {
@@ -384,16 +275,24 @@ function buildApi(driver) {
       entryPromise = Promise.resolve()
         .then(() => driver.loadEntry())
         .then((e) => {
-          if (!e) throw new Error('factoidal: the engine loader returned no entry object');
+          if (!e) throw new FactoidalError('factoidal: the engine loader returned no entry object', { code: 'host.io' });
           return e;
         })
-        .catch((err) => { entryPromise = undefined; throw err; });
+        .catch((err) => {
+          entryPromise = undefined;
+          throw err instanceof FactoidalError ? err
+            : new FactoidalError(`factoidal: the engine did not load: ${err && err.message}`,
+              { code: 'host.io', cause: err });
+        });
     }
     return entryPromise;
   }
 
-  // entryResult() is now module-level (see above ParseError) -- pure,
-  // shared by every buildApi() instance and by DatasetHandle.
+  // The options object of a public function, checked by the engine (op
+  // apiCheck): unknown keys, format names, regimes, outputs and versions.
+  async function checkedOptions(who, options) {
+    return checkOptions(await entry(), who, options);
+  }
 
 
   // ---------------------------------------------------------------
@@ -525,7 +424,7 @@ function buildApi(driver) {
     if (typeof e.registerServiceEndpoint !== 'function') {
       throw missingOpError('registerServiceEndpoint');
     }
-    const opts = checkOptions('registerServiceEndpoint', optionsOf('registerServiceEndpoint', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('registerServiceEndpoint', optionsOf('registerServiceEndpoint', options));
     const nq = await nquadsOf(data, opts, 'registerServiceEndpoint');
     return entryResult(e.registerServiceEndpoint(iri, nq),
       'registerServiceEndpoint');
@@ -549,9 +448,9 @@ function buildApi(driver) {
       const result = runOnce();
       if (extPending.length === 0) return result;
       if (round >= EXT_MAX_ROUNDS) {
-        throw new Error(
+        throw new FactoidalError(
           'extension functions: async resolution did not converge ' +
-          `within ${EXT_MAX_ROUNDS} evaluation rounds`);
+          `within ${EXT_MAX_ROUNDS} evaluation rounds`, { code: 'capacity.exceeded' });
       }
       const pend = extPending;
       extPending = [];
@@ -585,15 +484,16 @@ function buildApi(driver) {
     return out;
   }
 
-  // A ShEx focus/shape-label argument is either a raw string (an IRI,
-  // or "_:label" for a blank node -- the entry ABI's own convention)
-  // or an RDF/JS term (NamedNode/BlankNode); accepting both lets a
-  // caller pass a term straight out of a query() binding.
+  // A ShEx focus/shape-label argument is a string in N-Triples term syntax
+  // ("<http://...>" or "_:label"), which the engine reads with its one
+  // term-string reader, or an RDF/JS term (NamedNode/BlankNode); accepting
+  // both lets a caller pass a term straight out of a query() binding.
   function shexTermToString(t, who) {
-    if (typeof t === 'string') return t;
+    if (typeof t === 'string') return JSON.stringify(termToJson(t));
     if (t && typeof t.termType === 'string') {
-      if (t.termType === 'BlankNode') return `_:${t.value}`;
-      if (t.termType === 'NamedNode') return t.value;
+      if (t.termType === 'BlankNode' || t.termType === 'NamedNode') {
+        return JSON.stringify(termToJson(t)); // the engine writes the node
+      }
       throw new TypeError(`${who}: expected an IRI or blank node term`);
     }
     throw new TypeError(`${who}: expected a string or an RDF/JS term`);
@@ -613,9 +513,21 @@ function buildApi(driver) {
   async function ctx() {
     const e = await entry();
     if (ctxCache && ctxCache.e === e) return ctxCache;
+    let tablesCache = null;
     const c = {
       e,
       registry,
+      tables() {
+        if (!tablesCache) {
+          requireEntryFn(e, 'engineTables', 'format and regime tables');
+          const t = entryResult(e.engineTables(), 'engineTables');
+          tablesCache = { ...t.tables, errorCodes: t.errorCodes || [],
+            errorModelExemptOps: t.errorModelExemptOps || [] };
+          for (const k of Object.keys(WRITER_TAGS)) delete WRITER_TAGS[k];
+          Object.assign(WRITER_TAGS, tablesCache.writerFormats);
+        }
+        return tablesCache;
+      },
       missing: (what, op) => missingOpError(what, e, op),
       wrap(r, prefixes, extra) {
         const { ok: _ok, handle, count, prefixes: own, ...info } = r;
@@ -638,16 +550,34 @@ function buildApi(driver) {
       async closure(ds, regime) { return closureOnHandle(c, ds, regime); },
     };
     ctxCache = c;
+    installTextEngine(e);
     return c;
   }
 
+  // rdfjs.mjs's N-Quads text functions (nquadsToQuads, quadsToNQuads,
+  // termToNQuads, DatasetCore.fromNQuads/toNQuads) call these engine ops.
+  function installTextEngine(e) {
+    if (typeof e.parseQuadsJson !== 'function') return;
+    _setTextEngine({
+      parseQuads(text) {
+        return parseResult(e.parseQuadsJson(text, 'nquads12', ''), 'nquadsToQuads', text).quads;
+      },
+      writeQuads(quadsJson) {
+        return entryResult(e.quadsToNQuads(JSON.stringify(quadsJson)), 'quadsToNQuads').nquads;
+      },
+      termTokens(termsJson) {
+        return entryResult(e.termsToNTriples(JSON.stringify(termsJson)), 'termToNQuads').tokens;
+      },
+    });
+  }
+
   // The parse tag of `format`, or the engine's inference when it is omitted.
   function formatTagOf(c, text, format, who) {
     if (format === undefined || format === null || format === '') {
       requireEntryFn(c.e, 'detectFormat', `${who} (format inference)`);
       return { tag: entryResult(c.e.detectFormat(text), who).format, inferred: true };
     }
-    return { tag: DATA_FORMAT_TAG[extForFormat(format)], inferred: false };
+    return { tag: parseTagOf(c.e, c.tables(), format, who), inferred: false };
   }
 
   // Open `text` as a Dataset. A parse error names the format and says
@@ -659,11 +589,10 @@ function buildApi(driver) {
     try {
       r = parseResult(c.e.datasetOpen(text, tag, baseIRI || ''), who, text);
     } catch (err) {
-      if (inferred) {
-        err.message += ` (format inferred as '${tag}' because none was given; pass {format} to choose)`;
-        err.formatInferred = true;
+      if (err instanceof FactoidalError) {
+        err.formatInferred = inferred;
+        err.format = err.format || tag;
       }
-      err.format = err.format || tag;
       throw err;
     }
     return c.wrap(r, undefined, { format: tag, formatInferred: inferred });
@@ -713,49 +642,29 @@ function buildApi(driver) {
 
   async function queryDatasetHandle(c, ds, sparql, opts) {
     if (typeof sparql !== 'string') throw new TypeError('query: sparql must be a string');
+    // The options were checked by the engine (op apiCheck, as 'query' or
+    // 'Dataset.query'): regime, version, output and their combination.
     const entail = opts.entail || 'none';
-    if (/^x-ikl/i.test(entail)) {
-      throw new TypeError(
-        `query: entail '${entail}' is not implemented. The x-ikl-* ` +
-        "entailment regimes are the owner's design " +
-        "(danbri/factoidal#581); the Lean engine's dispatch for them " +
-        'was deleted on 2026-08-26 as collateral of the IKL-to-RDF ' +
-        'projection purge (danbri/factoidal#626). This is not a ' +
-        'policy exclusion.');
-    }
-    if (!ENTAIL_VALUES.has(entail)) {
-      throw new TypeError(`query: entail must be one of ${[...ENTAIL_VALUES].join(', ')}`);
-    }
-    if (opts.version !== undefined && !['1.1', '1.2'].includes(String(opts.version))) {
-      throw new TypeError("query: version must be '1.1' or '1.2'");
-    }
     const sparql12 = opts.sparql12 === true || String(opts.version || '') === '1.2';
     const e = c.e;
     if (entail !== 'none' || opts.output !== undefined) {
       // queryRaw over the stored dataset: an entailment regime, or a
       // results format (SPARQL 1.1 Query Results JSON, XML, CSV, TSV).
-      if (sparql12) {
-        throw new TypeError(
-          "query: entail/output and SPARQL 1.2 cannot be combined; that path reads SPARQL 1.1");
-      }
       const output = opts.output || 'json';
-      if (!RAW_OUTPUT_FORMATS.has(output)) {
-        throw new TypeError(`query: output must be one of ${[...RAW_OUTPUT_FORMATS].join(', ')}`);
-      }
-      const form = sniffQueryForm(sparql);
+      const form = queryFormOf(e, sparql);
       const graphForm = form === 'construct' || form === 'describe';
       requireEntryFn(e, 'datasetQueryRaw', `query {entail/output}`);
       if (opts.output === undefined) {
         // An entailment regime with the default answer shape.
         const r = entryResult(e.datasetQueryRaw(ds.handle, sparql, JSON.stringify({
-          entail, output: graphForm ? 'ntriples' : 'json' })), 'query');
+          entail, output: graphForm ? 'ntriples' : 'json' })), 'query', sparql);
         if (graphForm) return c.fromNQuads(r.text, ds.prefixes);
         const srj = JSON.parse(r.text);
         if (typeof srj.boolean === 'boolean') return srj.boolean;
         return bindingsFromSrj(srj);
       }
       const r = entryResult(e.datasetQueryRaw(ds.handle, sparql,
-        JSON.stringify({ entail, output })), 'query');
+        JSON.stringify({ entail, output })), 'query', sparql);
       return output === 'json' && !graphForm ? JSON.parse(r.text) : r.text;
     }
     const fn = sparql12 ? e.datasetQuery12 : e.datasetQuery;
@@ -763,7 +672,7 @@ function buildApi(driver) {
       throw missingOpError(`query (datasetQuery${sparql12 ? '12' : ''})`, e,
         sparql12 ? 'datasetQuery12' : 'datasetQuery');
     }
-    const r = await withExtensionRounds(() => entryResult(fn(ds.handle, sparql), 'query'));
+    const r = await withExtensionRounds(() => entryResult(fn(ds.handle, sparql), 'query', sparql));
     if (r.kind === 'ask') return r.boolean;
     if (r.kind === 'construct' || r.kind === 'describe') {
       return c.fromNQuads(r.nquads, ds.prefixes);
@@ -791,18 +700,9 @@ function buildApi(driver) {
       c.e.datasetShexValidate(ds.handle, schema, focusStr, shapeStr), 'shexValidate').verdict;
   }
 
-  const CLOSURE_REGIMES = {
-    rdfs: 'rdfs', 'owl-rl': 'owl-rl', owlrl: 'owl-rl', owl_rl: 'owl-rl',
-    'rho-df': 'rho-df', rhodf: 'rho-df', 'core-rdfs': 'rho-df',
-    'rdfs-plus': 'rdfs-plus', rdfsplus: 'rdfs-plus',
-  };
-
   async function closureOnHandle(c, ds, regime) {
-    const r0 = CLOSURE_REGIMES[String(regime || '').toLowerCase()];
-    if (!r0) {
-      throw new TypeError(
-        `closure: regime must be one of rdfs, owl-rl, rho-df, rdfs-plus (got '${regime}')`);
-    }
+    const r0 = c.tables().closureAliases[String(regime || '').toLowerCase()];
+    if (!r0) checkOptions(c.e, 'Dataset.closure', { regime: String(regime == null ? '' : regime) });
     requireEntryFn(c.e, 'datasetClosure', 'closure');
     const r = entryResult(c.e.datasetClosure(ds.handle, r0), 'closure');
     return c.wrap(r, ds.prefixes);
@@ -813,7 +713,7 @@ function buildApi(driver) {
 
   /**
    * Parse one RDF document into a Dataset. Strict by default: a syntax
-   * error rejects with a ParseError (`line`/`column`/`offset` for Turtle,
+   * error rejects with a FactoidalError (`code`, `position`, `spec`; for Turtle,
    * TriG, N-Triples and N-Quads). `{lenient:true}` skips each bad statement
    * of Turtle, TriG, N-Triples and N-Quads and lists one diagnostic per
    * skipped statement in `dataset.diagnostics`
@@ -827,8 +727,7 @@ function buildApi(driver) {
    */
   async function parse(text, options) {
     if (typeof text !== 'string') throw new TypeError('parse: text must be a string');
-    const opts = checkOptions('parse', optionsOf('parse', options),
-      ['format', 'baseIRI', 'lenient', 'maxErrors']);
+    const opts = await checkedOptions('parse', optionsOf('parse', options));
     const c = await ctx();
     if (opts.lenient) {
       const { tag, inferred } = formatTagOf(c, text, opts.format, 'parse');
@@ -856,7 +755,7 @@ function buildApi(driver) {
    * @returns {Promise<Dataset>}
    */
   async function openDataset(data, options) {
-    const opts = checkOptions('openDataset', optionsOf('openDataset', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('openDataset', optionsOf('openDataset', options));
     const c = await ctx();
     if (data instanceof Dataset) return data.clone();
     return datasetOf(c, data, opts, 'openDataset').ds;
@@ -876,8 +775,7 @@ function buildApi(driver) {
    */
   async function query(data, sparql, options) {
     if (typeof sparql !== 'string') throw new TypeError('query: sparql must be a string');
-    const opts = checkOptions('query', optionsOf('query', options),
-      ['format', 'baseIRI', 'entail', 'sparql12', 'version', 'output']);
+    const opts = await checkedOptions('query', optionsOf('query', options));
     return withDataset(data, opts, 'query', (c, ds) => queryDatasetHandle(c, ds, sparql, opts));
   }
 
@@ -892,15 +790,11 @@ function buildApi(driver) {
     if (typeof sparql !== 'string') {
       throw new TypeError('queryHdt: sparql must be a string');
     }
-    const form = sniffQueryForm(sparql);
-    if (form === 'construct' || form === 'describe') {
-      throw new TypeError(
-        `queryHdt: ${form.toUpperCase()} is not supported over an HDT file (SELECT/ASK only)`);
-    }
     const e = await entry();
     requireEntryFn(e, 'queryHdt', 'queryHdt');
     const r = entryResult(e.queryHdt(bytesToUint8Array(hdtBytes, 'queryHdt'), sparql), 'queryHdt');
     if (r.kind === 'ask') return r.boolean;
+    if (r.kind === 'construct' || r.kind === 'describe') return (await ctx()).fromNQuads(r.nquads, {});
     return bindingsFromSrj(r.srj);
   }
 
@@ -914,7 +808,7 @@ function buildApi(driver) {
    */
   async function update(data, updateText, options) {
     if (typeof updateText !== 'string') throw new TypeError('update: updateText must be a string');
-    const opts = checkOptions('update', optionsOf('update', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('update', optionsOf('update', options));
     const c = await ctx();
     const { ds, temp } = datasetOf(c, data, opts, 'update');
     const out = temp ? ds : ds.clone();
@@ -938,14 +832,8 @@ function buildApi(driver) {
    * @returns {Promise<string>}
    */
   async function serialize(data, options) {
-    const opts = checkOptions('serialize', optionsOf('serialize', options),
-      ['format', 'version', 'prefixes', 'literalShorthand', 'useNativeTypes',
-        'useRdfType', 'rdfDirection', 'inputFormat', 'baseIRI']);
+    const opts = await checkedOptions('serialize', optionsOf('serialize', options));
     const { inputFormat, baseIRI, ...writeOpts } = opts;
-    if (writeOpts.format !== undefined && !WRITER_TAGS[String(writeOpts.format).toLowerCase()]) {
-      throw new TypeError(`serialize: unknown format '${writeOpts.format}'. Known formats: ` +
-        [...new Set(Object.values(WRITER_TAGS))].join(', '));
-    }
     return withDataset(data, { format: inputFormat, baseIRI }, 'serialize',
       (_c, ds) => ds.serialize(writeOpts));
   }
@@ -957,7 +845,7 @@ function buildApi(driver) {
    * @returns {Promise<string>}
    */
   async function canonicalize(data, options) {
-    const opts = checkOptions('canonicalize', optionsOf('canonicalize', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('canonicalize', optionsOf('canonicalize', options));
     return withDataset(data, opts, 'canonicalize', (_c, ds) => ds.toString('rdfc'));
   }
 
@@ -965,24 +853,24 @@ function buildApi(driver) {
    * The named graphs of a Dataset, each as a Dataset (default graph
    * excluded, first-seen order).
    * @param {Dataset} dataset
-   * @returns {Array<[iri: string, graph: Dataset]>}
+   * @returns {Array<[name: NamedNode|BlankNode, graph: Dataset]>}
    */
   function graphs(dataset) {
     if (!(dataset instanceof Dataset)) throw new TypeError('graphs: expected a Dataset');
-    const seen = new Map();
-    for (const q of dataset) {
-      const g = q.graph;
-      if (!g || g.termType === 'DefaultGraph') continue;
-      if (!seen.has(g.value)) seen.set(g.value, g);
-    }
-    const out = [];
-    for (const [iri, gTerm] of seen) out.push([iri, dataset.match(null, null, null, gTerm)]);
-    return out;
+    dataset.size; // throws the disposed error
+    const c = dataset._ctx;
+    requireEntryFn(c.e, 'datasetGraphNames', 'graphs');
+    const names = entryResult(c.e.datasetGraphNames(dataset.handle), 'graphs').graphs;
+    return names.map((g) => {
+      const term = termFromSrj(g);
+      return [term, dataset.match(null, null, null, term)];
+    });
   }
 
   /**
    * RDFC-1.0 canonical N-Quads of one graph: every quad's graph name is
-   * dropped first. Text, not a digest.
+   * dropped first (op datasetGraphAsDefault with the union of the graphs).
+   * Text, not a digest.
    * @param {Dataset} datasetOrGraph
    * @returns {Promise<string>}
    */
@@ -990,9 +878,59 @@ function buildApi(driver) {
     if (!(datasetOrGraph instanceof Dataset)) {
       throw new TypeError('canonicalHash: expected a Dataset (e.g. one entry of graphs())');
     }
-    const asDefault = datasetOrGraph.toArray()
-      .map((q) => quadToNQuads(dataFactory.quad(q.subject, q.predicate, q.object))).join('');
-    return canonicalize(asDefault, { format: 'nquads' });
+    datasetOrGraph.size; // throws the disposed error
+    const c = datasetOrGraph._ctx;
+    requireEntryFn(c.e, 'datasetGraphAsDefault', 'canonicalHash');
+    const merged = c.wrap(entryResult(c.e.datasetGraphAsDefault(datasetOrGraph.handle,
+      JSON.stringify({ type: 'union' })), 'canonicalHash'), {});
+    try {
+      return merged.toString('rdfc');
+    } finally {
+      merged.dispose();
+    }
+  }
+
+  /**
+   * Whether two datasets are isomorphic (RDF 1.1 Concepts 3.6 and 4; blank
+   * nodes inside RDF 1.2 triple terms included): the engine's
+   * Dataset.isomorphicOutcome (op datasetIsomorphic). Rejects when the
+   * blank-node search budget is exceeded.
+   * @param {Dataset|string|Array} a
+   * @param {Dataset|string|Array} b
+   * @param {{format?: string, baseIRI?: string}} [options] read text arguments
+   * @returns {Promise<boolean>}
+   */
+  async function isomorphic(a, b, options) {
+    const opts = await checkedOptions('isomorphic', optionsOf('isomorphic', options));
+    return withDataset(a, opts, 'isomorphic', (c, da) =>
+      withDataset(b, opts, 'isomorphic', (_c, db) => {
+        requireEntryFn(c.e, 'datasetIsomorphic', 'isomorphic');
+        return entryResult(c.e.datasetIsomorphic(da.handle, db.handle), 'isomorphic').isomorphic;
+      }));
+  }
+
+  /**
+   * A Dataset holding RDF/JS quads (op datasetFromQuadsJson). Each term is
+   * sent as its components; the engine reads no text.
+   * @param {Iterable<object>} quads
+   * @returns {Promise<Dataset>}
+   */
+  async function fromQuads(quads) {
+    const c = await ctx();
+    requireEntryFn(c.e, 'datasetFromQuadsJson', 'fromQuads');
+    const arr = [];
+    for (const q of quads) arr.push(quadToJson(q));
+    return c.wrap(entryResult(c.e.datasetFromQuadsJson(JSON.stringify(arr)), 'fromQuads'), {});
+  }
+
+  /** Load the engine; afterwards the N-Quads text functions of `@factoidal/core/rdfjs` work. */
+  async function ready() {
+    await ctx();
+  }
+
+  /** The engine's name tables (formats, regimes, query outputs, pack syntaxes). */
+  async function engineTables() {
+    return (await ctx()).tables();
   }
 
   // A wasm module older than this package can lack an op: `e[fnName]` is
@@ -1009,7 +947,7 @@ function buildApi(driver) {
    * @returns {Promise<{conforms: boolean, report: Dataset}>}
    */
   async function shaclValidate(data, shapes, options) {
-    const opts = checkOptions('shaclValidate', optionsOf('shaclValidate', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('shaclValidate', optionsOf('shaclValidate', options));
     return withDataset(data, opts, 'shaclValidate(data)', (c, ds) => shaclOnHandle(c, ds, shapes, opts));
   }
 
@@ -1025,7 +963,7 @@ function buildApi(driver) {
    * @returns {Promise<boolean>}
    */
   async function shexValidate(data, schema, focus, shape, options) {
-    const opts = checkOptions('shexValidate', optionsOf('shexValidate', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('shexValidate', optionsOf('shexValidate', options));
     if (typeof schema !== 'string') throw new TypeError('shexValidate: schema must be a string');
     return withDataset(data, opts, 'shexValidate(data)', (c, ds) => shexOnHandle(c, ds, schema, focus, shape));
   }
@@ -1038,7 +976,7 @@ function buildApi(driver) {
    * @returns {Promise<Dataset>}
    */
   async function closure(data, regime, options) {
-    const opts = checkOptions('closure', optionsOf('closure', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('closure', optionsOf('closure', options));
     return withDataset(data, opts, 'closure', (c, ds) => closureOnHandle(c, ds, regime));
   }
 
@@ -1051,9 +989,8 @@ function buildApi(driver) {
    */
   async function owlClosure(data, mode, options) {
     const m = String(mode || '').toLowerCase();
-    if (!['rdfs', 'owl-rl', 'owlrl', 'owl_rl'].includes(m)) {
-      throw new TypeError(`owlClosure: mode must be 'RDFS' or 'OWL-RL' (got '${mode}')`);
-    }
+    // The engine checks the mode against its regime table (op apiCheck).
+    await checkedOptions('owlClosure', { mode: String(mode == null ? '' : mode) });
     return closure(data, m, options);
   }
 
@@ -1077,7 +1014,7 @@ function buildApi(driver) {
    * @returns {Promise<{ok: boolean, fragment: boolean}>}
    */
   async function coreRdfsCheck(data, options) {
-    const opts = checkOptions('coreRdfsCheck', optionsOf('coreRdfsCheck', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('coreRdfsCheck', optionsOf('coreRdfsCheck', options));
     const nq = await nquadsOf(data, opts, 'coreRdfsCheck(data)');
     const e = await entry();
     requireEntryFn(e, 'rhoDfFragmentCheck', 'core-RDFS fragment check');
@@ -1105,7 +1042,7 @@ function buildApi(driver) {
    * @returns {Promise<{dataset: Dataset, addedCount: number, budgetHit?: boolean}>}
    */
   async function tableauMaterialise(data, options) {
-    const opts = checkOptions('tableauMaterialise', optionsOf('tableauMaterialise', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('tableauMaterialise', optionsOf('tableauMaterialise', options));
     const nq = await nquadsOf(data, opts, 'tableauMaterialise(data)');
     const c = await ctx();
     requireEntryFn(c.e, 'tableauMaterialise', 'OWL tableau materialisation');
@@ -1125,7 +1062,7 @@ function buildApi(driver) {
    * @returns {Promise<{inconsistent: boolean, rlAlone: boolean}>}
    */
   async function tableauDlInconsistent(data, options) {
-    const opts = checkOptions('tableauDlInconsistent', optionsOf('tableauDlInconsistent', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('tableauDlInconsistent', optionsOf('tableauDlInconsistent', options));
     const nq = await nquadsOf(data, opts, 'tableauDlInconsistent(data)');
     const e = await entry();
     requireEntryFn(e, 'tableauDlInconsistent', 'OWL tableau DL inconsistency check');
@@ -1141,7 +1078,7 @@ function buildApi(driver) {
    * @returns {Promise<{consistent: boolean|null, reason?: string}>}
    */
   async function owlIsConsistent(data, options) {
-    const opts = checkOptions('owlIsConsistent', optionsOf('owlIsConsistent', options), ['format', 'baseIRI', 'fuel']);
+    const opts = await checkedOptions('owlIsConsistent', optionsOf('owlIsConsistent', options));
     const nq = await nquadsOf(data, opts, 'owlIsConsistent(data)');
     const e = await entry();
     requireEntryFn(e, 'owlIsConsistent', 'OWL DL consistency check');
@@ -1161,7 +1098,7 @@ function buildApi(driver) {
    * @returns {Promise<{entailed: boolean|null, via: 'closure'|'refutation', reason?: string}>}
    */
   async function owlEntails(premise, conclusion, options) {
-    const opts = checkOptions('owlEntails', optionsOf('owlEntails', options), ['format', 'baseIRI', 'fuel']);
+    const opts = await checkedOptions('owlEntails', optionsOf('owlEntails', options));
     const premiseNq = await nquadsOf(premise, opts, 'owlEntails(premise)');
     const conclusionNq = await nquadsOf(conclusion, opts, 'owlEntails(conclusion)');
     const e = await entry();
@@ -1185,8 +1122,8 @@ function buildApi(driver) {
   async function rmlMap(mapping, sourceData, sourceKind, options) {
     if (typeof sourceData !== 'string') throw new TypeError('rmlMap: sourceData must be a string');
     const kind = String(sourceKind || '').toLowerCase();
-    if (kind !== 'json' && kind !== 'csv') throw new TypeError("rmlMap: sourceKind must be 'json' or 'csv'");
-    const opts = checkOptions('rmlMap', optionsOf('rmlMap', options), ['format', 'baseIRI']);
+    await checkedOptions('rmlMap', { sourceKind: kind });
+    const opts = await checkedOptions('rmlMap', optionsOf('rmlMap', options));
     return withDataset(mapping, opts, 'rmlMap(mapping)', (c, ds) => {
       requireEntryFn(c.e, 'datasetFromRml', 'RML mapping evaluation');
       return c.wrap(entryResult(c.e.datasetFromRml(ds.handle, sourceData, kind), 'rmlMap'), {});
@@ -1206,7 +1143,7 @@ function buildApi(driver) {
     if (typeof csvText !== 'string') throw new TypeError('csvwToRdf: csvText must be a string');
     const meta = metadataJson == null ? '' : metadataJson;
     if (typeof meta !== 'string') throw new TypeError('csvwToRdf: metadataJson must be a string');
-    const opts = checkOptions('csvwToRdf', options, ['mode', 'base', 'url']);
+    const opts = await checkedOptions('csvwToRdf', options);
     const c = await ctx();
     requireEntryFn(c.e, 'datasetFromCsvw', 'CSVW csv2rdf conversion');
     const optionsJson = JSON.stringify({
@@ -1227,7 +1164,7 @@ function buildApi(driver) {
    */
   async function jsonldToRdf(jsonldText, options) {
     if (typeof jsonldText !== 'string') throw new TypeError('jsonldToRdf: jsonldText must be a string');
-    const opts = checkOptions('jsonldToRdf', options, ['base', 'rdfDirection', 'expandContext', 'processingMode']);
+    const opts = await checkedOptions('jsonldToRdf', options);
     const c = await ctx();
     requireEntryFn(c.e, 'datasetFromJsonLd', 'jsonldToRdf');
     const optionsJson = JSON.stringify({
@@ -1250,7 +1187,7 @@ function buildApi(driver) {
    */
   async function rifEval(data, rifRulesXml, options) {
     if (typeof rifRulesXml !== 'string') throw new TypeError('rifEval: rifRulesXml must be a string');
-    const opts = checkOptions('rifEval', optionsOf('rifEval', options), ['format', 'baseIRI']);
+    const opts = await checkedOptions('rifEval', optionsOf('rifEval', options));
     return withDataset(data, opts, 'rifEval(data)', (c, ds) => {
       requireEntryFn(c.e, 'datasetRifEval', 'RIF Core evaluation');
       return c.wrap(entryResult(c.e.datasetRifEval(rifRulesXml, ds.handle), 'rifEval'), ds.prefixes);
@@ -1266,8 +1203,7 @@ function buildApi(driver) {
    * @returns {Promise<any>}
    */
   async function jsonldFromRdf(data, options) {
-    const opts = checkOptions('jsonldFromRdf', optionsOf('jsonldFromRdf', options),
-      ['useNativeTypes', 'useRdfType', 'rdfDirection', 'format', 'baseIRI']);
+    const opts = await checkedOptions('jsonldFromRdf', optionsOf('jsonldFromRdf', options));
     const { format, baseIRI, ...w } = opts;
     return withDataset(data, { format, baseIRI }, 'jsonldFromRdf(data)',
       (_c, ds) => JSON.parse(ds.toString({ format: 'jsonld', ...w })));
@@ -1980,28 +1916,16 @@ function buildApi(driver) {
     if (typeof queryString !== 'string') {
       throw new TypeError('queryRaw: queryString must be a string');
     }
-    const opts = checkOptions('queryRaw', options, ['dataFormat', 'entail', 'output']);
+    const opts = await checkedOptions('queryRaw', options);
     const dataFormat = String(opts.dataFormat || 'turtle').toLowerCase();
     const entail = opts.entail || 'none';
     const output = opts.output || 'json';
-    if (!(dataFormat in RAW_DATA_FORMATS)) {
-      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 (!RAW_OUTPUT_FORMATS.has(output)) {
-      throw new TypeError(`queryRaw: output must be one of ${[...RAW_OUTPUT_FORMATS].join(', ')}`);
-    }
+    const tables = (await ctx()).tables();
     const e = await entry();
     requireEntryFn(e, 'queryRaw', 'queryRaw');
-    const r = JSON.parse(e.queryRaw(dataString, queryString,
-      JSON.stringify({ dataFormat: RAW_DATA_FORMATS[dataFormat], entail, output })));
-    if (!r.ok) {
-      const err = new Error('SPARQL query failed: ' + r.error);
-      err.stderr = String(r.error);
-      throw err;
-    }
+    const r = entryResult(e.queryRaw(dataString, queryString,
+      JSON.stringify({ dataFormat: tables.rawDataFormats[dataFormat], entail, output })),
+    'queryRaw', queryString);
     return output === 'json' ? JSON.parse(r.text) : r.text;
   }
 
@@ -2280,10 +2204,13 @@ function buildApi(driver) {
     deltaLogDestroy,
     _deltaLogCorruptLastForTest,
     queryRaw,
+    isomorphic,
+    fromQuads,
+    ready,
+    engineTables,
     Dataset,
-    DatasetHandle,
     Store,
-    ParseError,
+    FactoidalError,
     dataFactory,
     // Metadata (issue #682): the same two fields on every driver's
     // typed surface, so a caller can log/report which package version
@@ -2295,6 +2222,6 @@ function buildApi(driver) {
 }
 
 export {
-  buildApi, sniffQueryForm, bindingsFromSrj, entryResult, parseResult,
-  utf16OffsetOf, missingOpError, ParseError, DatasetHandle, Store,
+  buildApi, bindingsFromSrj, entryResult, parseResult,
+  missingOpError, FactoidalError, Store,
 };