@factoidal/core 0.10.0 → 0.12.0

package/lib/dataset.mjs

@@ -13,49 +13,131 @@
 // Lifetime: dispose() (or `using ds = ...`, Symbol.dispose) releases the
 // engine copy. A Dataset that is garbage collected without dispose() is
 // released by a FinalizationRegistry callback. Every method of a disposed
-// Dataset throws a TypeError that names the method.
+// Dataset throws the engine's FactoidalError, code handle.disposed.
 
-import { nquadsLineToQuad, quadToNQuads, termToNQuads, termFromSrj } from '../rdfjs.mjs';
+import { dataFactory, quadFromJson, quadToJson, termToJson, termFromSrj, Literal, NamedNode } from '../rdfjs.mjs';
+import { FactoidalError, envelopeResult } from './errors.mjs';
 
 const INTERNAL = Symbol('factoidal.Dataset.internal');
 
-// Writer names (lower case) -> the engine's writer tag. JSON-LD is served
+// Writer names (lower case) -> the engine's writer tag: the engine's table
+// (op engineTables, `writerFormats`), read once per engine. JSON-LD is served
 // by the op datasetToJsonLd; the SPARQL results formats are query outputs.
-const WRITER_TAGS = {
-  nquads: 'nquads', nq: 'nquads', 'n-quads': 'nquads',
-  ntriples: 'ntriples', nt: 'ntriples', 'n-triples': 'ntriples',
-  turtle: 'turtle', ttl: 'turtle',
-  trig: 'trig',
-  rdfxml: 'rdfxml', 'rdf-xml': 'rdfxml', rdf: 'rdfxml',
-  jsonld: 'jsonld', 'json-ld': 'jsonld',
-  rdfc: 'rdfc', canonical: 'rdfc', 'rdfc-1.0': 'rdfc',
-};
+// `WRITER_TAGS` stays exported for callers that read it; it is filled from
+// the engine on the first Dataset.
+const WRITER_TAGS = {};
 
 const VERSIONS = { '1.1': '11', '1.2': '12' };
 
-/** Throw a TypeError when `options` has a key outside `allowed`. */
-function checkOptions(who, options, allowed) {
+/**
+ * The options object of public function `who`, checked by the engine (op
+ * apiCheck, formal/lean4/Wasm/Ops/Handles.lean): every key one the function
+ * takes, every format, regime, output and version in the engine's tables, and
+ * no two options that cannot be combined. A value that is not an object is a
+ * TypeError (a wrong JavaScript type); every other refusal is the engine's
+ * FactoidalError.
+ */
+function checkOptions(e, who, options) {
   if (options == null) return {};
   if (typeof options !== 'object' || Array.isArray(options)) {
     throw new TypeError(`${who}: options must be an object, got ${Array.isArray(options) ? 'array' : typeof options}`);
   }
+  // Each value as the engine reads it: a primitive as its String form, an
+  // object, array or function as {}, undefined as null.
+  const wire = {};
   for (const key of Object.keys(options)) {
-    if (!allowed.includes(key)) {
-      throw new TypeError(
-        `${who}: unknown option '${key}'. Known options: ${allowed.join(', ') || '(none)'}`);
-    }
+    const v = options[key];
+    wire[key] = v === undefined || v === null ? null
+      : (typeof v === 'object' || typeof v === 'function') ? {} : String(v);
   }
+  // An engine with no apiCheck op (the F* entry of tests/engine-compare, a
+  // private comparison build) has no option tables: its ops refuse instead.
+  if (typeof e.apiCheck !== 'function') return options;
+  envelopeResult(e.apiCheck(who, JSON.stringify(wire)));
   return options;
 }
 
-function envelope(jsonText, what) {
-  const r = JSON.parse(jsonText);
-  if (!r.ok) throw new Error(`${what}: ${r.error}`);
-  return r;
+function envelope(jsonText, _what, text) {
+  return envelopeResult(jsonText, text);
+}
+
+// The quads of the compact answer of datasetQuadsJson: each distinct term is
+// built once and shared (TermJson.compactCertified).
+function quadsFromCompact(terms, ixs) {
+  const ts = terms.map(termFromSrj);
+  const dg = dataFactory.defaultGraph();
+  return ixs.map((ix) => dataFactory.quad(ts[ix[0]], ts[ix[1]], ts[ix[2]],
+    ix.length > 3 ? ts[ix[3]] : dg));
 }
 
-const SERIALIZE_OPTIONS = ['format', 'version', 'prefixes', 'literalShorthand',
-  'useNativeTypes', 'useRdfType', 'rdfDirection'];
+// The region of op datasetQuadsBin, read as the engine wrote it
+// (formal/lean4/L4Factoidal/RDF/QuadsBin.lean: `binSpec` is the layout,
+// `decodeBin` the reader this function follows, `decodeBin_quadsBin` the
+// theorem that the region reads back as exactly the quads). Every number is a
+// u32 little-endian; each term is in the term codec of DLOG version 2, which
+// names the term kind, the datatype IRI, the language tag and the base
+// direction explicitly, so this function copies fields and decides nothing.
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
+const DIRECTION = ['', 'ltr', 'rtl'];
+
+function quadsFromRegion(bytes, out) {
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (bytes.length < 12 || v.getUint32(0, true) !== 0x31425146) {
+    throw new FactoidalError('iterate: the engine answered no datasetQuadsBin region', { code: 'op.failed' });
+  }
+  const nTerms = v.getUint32(4, true);
+  const nQuads = v.getUint32(8, true);
+  let p = 12;
+  // UTF-8 bytes to a string; a short run of bytes below 0x80 (one UTF-16
+  // unit each) is copied without a TextDecoder call.
+  const str = () => {
+    const n = v.getUint32(p, true);
+    const a = p + 4;
+    p = a + n;
+    if (n <= 64) {
+      let i = a;
+      while (i < p && bytes[i] < 0x80) i++;
+      if (i === p) return String.fromCharCode.apply(null, bytes.subarray(a, p));
+    }
+    return UTF8.decode(bytes.subarray(a, p));
+  };
+  const datatypes = new Map();
+  const term = () => {
+    switch (bytes[p++]) {
+      case 0: return new NamedNode(str());
+      case 1: return dataFactory.blankNode(str());
+      case 2: {
+        const lexical = str();
+        const dt = str();
+        let datatype = datatypes.get(dt);
+        if (datatype === undefined) { datatype = new NamedNode(dt); datatypes.set(dt, datatype); }
+        const flag = bytes[p++];
+        const language = flag === 0 ? '' : str();
+        const direction = flag === 2 ? DIRECTION[bytes[p++]] : '';
+        return new Literal(lexical, language, datatype, direction);
+      }
+      case 3: {
+        const s = term();
+        const pr = term();
+        return dataFactory.quad(s, pr, term());
+      }
+      default: throw new FactoidalError('iterate: a term tag outside the DLOG version 2 codec', { code: 'op.failed' });
+    }
+  };
+  const ts = new Array(nTerms);
+  for (let i = 0; i < nTerms; i++) ts[i] = term();
+  const dg = dataFactory.defaultGraph();
+  for (let i = 0; i < nQuads; i++, p += 16) {
+    const g = v.getUint32(p + 12, true);
+    out.push(dataFactory.quad(ts[v.getUint32(p, true)], ts[v.getUint32(p + 4, true)],
+      ts[v.getUint32(p + 8, true)], g === 0 ? dg : ts[g - 1]));
+  }
+  return nQuads;
+}
+
+// Quads of the first datasetQuadsBin call while iterating: an iteration that
+// stops early reads this many; the rest come in one more call.
+const FIRST_PAGE = 4096;
 
 class Dataset {
   /** @private Datasets come from parse(), csvwToRdf() and the other producers. */
@@ -99,9 +181,11 @@ class Dataset {
    */
   get info() { return this._info; }
 
+  // A disposed Dataset: the engine answers handle.disposed for its handle.
   _open(who) {
     if (this._disposed) {
-      throw new TypeError(`Dataset.${who}: the Dataset was disposed (handle '${this._handle}')`);
+      envelopeResult(this._ctx.e.datasetClose(this._handle));
+      throw new FactoidalError(`Dataset.${who}: the Dataset was disposed`, { code: 'handle.disposed' });
     }
   }
 
@@ -123,7 +207,7 @@ class Dataset {
   async query(sparql, options) {
     this._open('query');
     return this._ctx.queryHandle(this, sparql,
-      checkOptions('Dataset.query', options, ['sparql12', 'version', 'entail', 'output']));
+      checkOptions(this._ctx.e, 'Dataset.query', options));
   }
 
   /**
@@ -134,11 +218,11 @@ class Dataset {
    */
   async update(updateText, options) {
     this._open('update');
-    checkOptions('Dataset.update', options, []);
+    checkOptions(this._ctx.e, 'Dataset.update', options);
     if (typeof updateText !== 'string') {
       throw new TypeError('Dataset.update: updateText must be a string');
     }
-    const r = envelope(this._ctx.e.datasetUpdate(this._handle, updateText), 'update');
+    const r = envelope(this._ctx.e.datasetUpdate(this._handle, updateText), 'update', updateText);
     this._changed(r.count);
     return this;
   }
@@ -152,7 +236,7 @@ class Dataset {
   async validateShacl(shapes, options) {
     this._open('validateShacl');
     return this._ctx.shacl(this, shapes,
-      checkOptions('Dataset.validateShacl', options, ['format', 'baseIRI']));
+      checkOptions(this._ctx.e, 'Dataset.validateShacl', options));
   }
 
   /**
@@ -164,7 +248,7 @@ class Dataset {
   async validateShex(schema, options) {
     this._open('validateShex');
     return this._ctx.shex(this, schema,
-      checkOptions('Dataset.validateShex', options, ['focus', 'shape']));
+      checkOptions(this._ctx.e, 'Dataset.validateShex', options));
   }
 
   /**
@@ -194,8 +278,8 @@ class Dataset {
    */
   async serialize(options) {
     this._open('serialize');
-    if (typeof options === 'string') return this._write({ format: options });
-    return this._write(checkOptions('Dataset.serialize', options, SERIALIZE_OPTIONS));
+    const opts = typeof options === 'string' ? { format: options } : options;
+    return this._write(checkOptions(this._ctx.e, 'Dataset.serialize', opts));
   }
 
   /**
@@ -205,33 +289,18 @@ class Dataset {
    */
   toString(formatOrOptions) {
     this._open('toString');
-    const opts = typeof formatOrOptions === 'string'
-      ? { format: formatOrOptions }
-      : checkOptions('Dataset.toString', formatOrOptions, SERIALIZE_OPTIONS);
-    return this._write(opts);
+    const opts = typeof formatOrOptions === 'string' ? { format: formatOrOptions } : formatOrOptions;
+    return this._write(checkOptions(this._ctx.e, 'Dataset.toString', opts));
   }
 
   _write(opts) {
     const e = this._ctx.e;
     const name = String(opts.format || 'nquads').toLowerCase();
-    const tag = WRITER_TAGS[name];
-    if (!tag) {
-      throw new TypeError(
-        `Dataset.serialize: unknown format '${opts.format}'. Known formats: ` +
-        [...new Set(Object.values(WRITER_TAGS))].join(', '));
-    }
-    let suffix = '';
-    if (opts.version !== undefined) {
-      suffix = VERSIONS[String(opts.version)];
-      if (!suffix) throw new TypeError("Dataset.serialize: version must be '1.1' or '1.2'");
-    }
-    if (tag !== 'turtle' && (opts.prefixes !== undefined || opts.literalShorthand !== undefined)) {
-      throw new TypeError("Dataset.serialize: 'prefixes' and 'literalShorthand' apply to format 'turtle' only");
-    }
-    const jsonldKeys = ['useNativeTypes', 'useRdfType', 'rdfDirection'];
-    if (tag !== 'jsonld' && jsonldKeys.some((k) => opts[k] !== undefined)) {
-      throw new TypeError(`Dataset.serialize: ${jsonldKeys.join(', ')} apply to format 'jsonld' only`);
-    }
+    const writerTags = this._ctx.tables().writerFormats;
+    // The engine checked the format, the version and the option
+    // combination (op apiCheck) before this.
+    const tag = writerTags[name];
+    const suffix = opts.version !== undefined ? VERSIONS[String(opts.version)] : '';
     if (tag === 'jsonld') {
       if (typeof e.datasetToJsonLd !== 'function') throw this._ctx.missing('serialize {format:jsonld}', 'datasetToJsonLd');
       const r = envelope(e.datasetToJsonLd(this._handle, JSON.stringify({
@@ -273,40 +342,58 @@ class Dataset {
   }
 
   /**
-   * RDF/JS quads, read from the engine's N-Quads text one line at a time.
+   * RDF/JS quads, built from the engine's term objects (op datasetQuadsJson),
+   * in the line order of toNQuads(). No N-Quads text is read here.
    * @returns {Iterator<object>}
    */
   *[Symbol.iterator]() {
     this._open('iterate');
     if (this._quads) { yield* this._quads; return; }
-    const text = this.toNQuads();
-    let start = 0;
-    let lineNo = 0;
-    while (start < text.length) {
-      let end = text.indexOf('\n', start);
-      if (end < 0) end = text.length;
-      lineNo += 1;
-      const line = text.slice(start, end);
-      start = end + 1;
-      const q = nquadsLineToQuad(line, lineNo);
-      if (q) yield q;
+    const e = this._ctx.e;
+    if (typeof e.datasetQuadsBin !== 'function') { yield* this._allQuads(); return; }
+    // The engine's region (op datasetQuadsBin) in two calls, a first page and
+    // the rest; the whole list is cached when the rest is read.
+    const acc = [];
+    const first = e.datasetQuadsBin(this._handle, `{"offset":0,"limit":${FIRST_PAGE}}`);
+    quadsFromRegion(first.bytes, acc);
+    for (let i = 0; i < acc.length; i++) yield acc[i];
+    if (acc.length < first.envelope.total) {
+      const rest = e.datasetQuadsBin(this._handle, `{"offset":${acc.length}}`);
+      const from = acc.length;
+      quadsFromRegion(rest.bytes, acc);
+      for (let i = from; i < acc.length; i++) yield acc[i];
+    }
+    if (!this._quads) this._quads = Object.freeze(acc);
+  }
+
+  // Every quad, read once and cached.
+  _allQuads() {
+    if (!this._quads) {
+      const e = this._ctx.e;
+      if (typeof e.datasetQuadsBin === 'function') {
+        const acc = [];
+        quadsFromRegion(e.datasetQuadsBin(this._handle, '').bytes, acc);
+        this._quads = Object.freeze(acc);
+      } else {
+        const r = envelope(e.datasetQuadsJson(this._handle, '{"compact":true}'), 'iterate');
+        this._quads = Object.freeze(r.ixs ? quadsFromCompact(r.terms, r.ixs) : r.quads.map((q) => quadFromJson(q)));
+      }
     }
+    return this._quads;
   }
 
   /** Every quad as an array. */
   toArray() {
     this._open('toArray');
-    if (!this._quads) this._quads = Object.freeze([...this]);
-    return this._quads.slice();
+    return this._allQuads().slice();
   }
 
   // A quad pattern for the ops datasetMatch and datasetMatchCount: four
-  // N-Triples term tokens, '' for an unbound position, 'DEFAULT' for the
-  // default graph.
+  // engine term objects, null for an unbound position, {type:'default'} for
+  // the default graph.
   _pattern(subject, predicate, object, graph) {
-    const tok = (t) => (t == null ? '' : termToNQuads(t));
-    const g = graph == null ? '' : (graph.termType === 'DefaultGraph' ? 'DEFAULT' : termToNQuads(graph));
-    return JSON.stringify([tok(subject), tok(predicate), tok(object), g]);
+    return JSON.stringify([termToJson(subject), termToJson(predicate), termToJson(object),
+      termToJson(graph)]);
   }
 
   /** RDF/JS DatasetCore.has: one indexed lookup in the engine. */
@@ -336,7 +423,8 @@ class Dataset {
    */
   add(quad) {
     this._open('add');
-    const r = envelope(this._ctx.e.datasetAddQuads(this._handle, quadToNQuads(quad)), 'add');
+    const r = envelope(this._ctx.e.datasetAddQuadsJson(this._handle,
+      JSON.stringify([quadToJson(quad)])), 'add');
     this._changed(r.count);
     return this;
   }
@@ -344,7 +432,8 @@ class Dataset {
   /** RDF/JS DatasetCore.delete: remove one quad. */
   delete(quad) {
     this._open('delete');
-    const r = envelope(this._ctx.e.datasetDeleteQuads(this._handle, quadToNQuads(quad)), 'delete');
+    const r = envelope(this._ctx.e.datasetDeleteQuadsJson(this._handle,
+      JSON.stringify([quadToJson(quad)])), 'delete');
     this._changed(r.count);
     return this;
   }

package/lib/delta-log-hosts.mjs

@@ -20,6 +20,7 @@
 //                              would; false when the log is empty
 //
 // No Node built-ins: the browser imports this file as it is.
+import { hostError } from './errors.mjs';
 
 const DELTA_STORE = 'deltaBatches';
 
@@ -65,7 +66,7 @@ export function memoryDeltaLogStore() {
 function indexedDbFactory() {
   const factory = globalThis.indexedDB;
   if (!factory) {
-    throw new Error('deltaLog: this runtime has no indexedDB; the browser entry keeps the log in IndexedDB');
+    throw hostError('deltaLog: this runtime has no indexedDB; the browser entry keeps the log in IndexedDB');
   }
   return factory;
 }
@@ -80,23 +81,23 @@ function idbOpen(dbName) {
       }
     };
     req.onsuccess = () => resolve(req.result);
-    req.onerror = () => reject(req.error || new Error('indexedDB.open failed'));
-    req.onblocked = () => reject(new Error('indexedDB.open blocked (another tab holds an open connection at an older version)'));
+    req.onerror = () => reject(hostError('indexedDB.open failed', req.error));
+    req.onblocked = () => reject(hostError('indexedDB.open blocked (another tab holds an open connection at an older version)'));
   });
 }
 
 function requestDone(req) {
   return new Promise((resolve, reject) => {
     req.onsuccess = () => resolve(req.result);
-    req.onerror = () => reject(req.error || new Error('IndexedDB request failed'));
+    req.onerror = () => reject(hostError('IndexedDB request failed', req.error));
   });
 }
 
 function transactionDone(tx) {
   return new Promise((resolve, reject) => {
     tx.oncomplete = () => resolve();
-    tx.onerror = () => reject(tx.error || new Error('IndexedDB transaction failed'));
-    tx.onabort = () => reject(tx.error || new Error('IndexedDB transaction aborted'));
+    tx.onerror = () => reject(hostError('IndexedDB transaction failed', tx.error));
+    tx.onabort = () => reject(hostError('IndexedDB transaction aborted', tx.error));
   });
 }
 
@@ -164,8 +165,8 @@ export function indexedDbDeltaLogStore() {
       await new Promise((resolve, reject) => {
         const req = indexedDbFactory().deleteDatabase(name);
         req.onsuccess = () => resolve();
-        req.onerror = () => reject(req.error || new Error('indexedDB.deleteDatabase failed'));
-        req.onblocked = () => reject(new Error('indexedDB.deleteDatabase blocked (another open connection)'));
+        req.onerror = () => reject(hostError('indexedDB.deleteDatabase failed', req.error));
+        req.onblocked = () => reject(hostError('indexedDB.deleteDatabase blocked (another open connection)'));
       });
     },
     async corruptLast(name) {

package/lib/errors.mjs

@@ -0,0 +1,97 @@
+// factoidal — the one error class of the package
+// (https://github.com/danbri/factoidal/issues/882 item 4).
+//
+// Every function of the package rejects (or throws) with a FactoidalError.
+// The engine decides its `code`, its `spec` section and its `position`
+// (formal/lean4/Wasm/Ops/ErrorModel.lean); this file only copies them out
+// of the error envelope. A TypeError is thrown only when an argument has the
+// wrong JavaScript type (a number where a string is needed, and the like).
+//
+// ES module, no Node built-ins: the browser loads this file as it is.
+
+/**
+ * An engine refusal, or a host failure (`host.io`).
+ *
+ * - `code`: a stable machine code, one of the engine's `errorCodes` table
+ *   (op engineTables; README "Errors").
+ * - `position`: `{line, column, offset, byteOffset}` where the input defines
+ *   one, else `null`. `line` and `column` are 1-based (`column` counts
+ *   Unicode scalar values); `offset` is a UTF-16 index into the JavaScript
+ *   string, so `text.slice(err.position.offset)` starts at the error;
+ *   `byteOffset` counts UTF-8 bytes.
+ * - `spec`: the URL of the specification section that defines the
+ *   condition, or `null`.
+ * - `cause`: the underlying error, when there is one.
+ * - `format`, `formatInferred`: for a parse failure of text, the syntax it
+ *   was read as and whether that syntax was inferred.
+ */
+export class FactoidalError extends Error {
+  constructor(message, info) {
+    const i = info || {};
+    super(message, i.cause !== undefined ? { cause: i.cause } : undefined);
+    this.name = 'FactoidalError';
+    this.code = i.code || 'op.failed';
+    this.position = i.position || null;
+    this.spec = i.spec || null;
+    if (i.format !== undefined) this.format = i.format;
+    if (i.formatInferred !== undefined) this.formatInferred = i.formatInferred;
+    if (typeof Error.captureStackTrace === 'function') {
+      Error.captureStackTrace(this, FactoidalError);
+    }
+  }
+}
+
+// The engine counts `offset` in Unicode scalar values from the start of the
+// input; a JavaScript string is indexed in UTF-16 code units, where a
+// character at U+10000 or above takes two. This converts the count to the
+// UTF-16 index of the same position (a unit conversion of the host string;
+// a count past the end gives text.length).
+export 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;
+}
+
+/**
+ * The FactoidalError of an error envelope ({"ok":false,"error",...}).
+ * `text` is the input string the envelope's position counts into, when the
+ * caller has it.
+ */
+export function errorFromEnvelope(env, text) {
+  const p = env && env.position;
+  let position = null;
+  if (p && typeof p === 'object') {
+    position = {
+      line: p.line,
+      column: p.column,
+      offset: typeof text === 'string' ? utf16OffsetOf(text, p.offset) : p.offset,
+      byteOffset: p.byteOffset,
+    };
+  }
+  return new FactoidalError(String((env && env.error) || 'engine refusal'), {
+    code: env && env.code,
+    spec: env && env.spec,
+    position,
+    format: env && env.format,
+  });
+}
+
+/** Unwrap one op envelope: the envelope object, or throw its FactoidalError. */
+export function envelopeResult(jsonText, text) {
+  const r = typeof jsonText === 'string' ? JSON.parse(jsonText) : jsonText;
+  if (!r.ok) throw errorFromEnvelope(r, text);
+  return r;
+}
+
+/** A host failure (file system, IndexedDB): code `host.io`, with its cause. */
+export function hostError(message, cause) {
+  return new FactoidalError(message, { code: 'host.io', cause });
+}

package/lib/lean-entry.mjs

@@ -22,12 +22,13 @@
 // None of them makes a semantic decision: which IRIs reach the host, what
 // an absent answer means, which artifact a query reads, are decided in Lean.
 
-const XSD = 'http://www.w3.org/2001/XMLSchema#';
 
 // The two npm entries and the engine each loads (issue 713 stage 4). The
 // core engine's `ops` reflection lists what only the full engine serves
 // (`fullOnlyOps`, `fullOnlyFormats`); a call to one of those names the
 // entry that has it.
+import { appTermToJson, termToJson } from '../rdfjs.mjs';
+import { errorFromEnvelope } from './errors.mjs';
 export const FULL_ENTRY = '@factoidal/core';
 // The core profile is built for the hub pages only; the package ships the
 // full engine (owner, 2026-10-20).
@@ -53,33 +54,31 @@ function okEnvelope(extra) {
 }
 
 // An engine refusal arrives as an Error whose `.envelope` is the whole
-// {"ok":false,...} document (the loader keeps it, so a parse failure's
-// line, column, offset and format reach lib/api.mjs's ParseError). The
-// message stays the loader's own, "l4factoidal: <error>".
+// {"ok":false,...} document: the engine's message, code, spec section and
+// position pass to lib/errors.mjs unchanged. Any other throw (the wasm
+// trapped, the loader failed) is code op.failed.
 function failEnvelope(err) {
   const env = err && err.envelope;
-  if (env && typeof env === 'object' && env.ok === false) {
-    return JSON.stringify({ ...env, error: String(err.message) });
-  }
-  return JSON.stringify({ ok: false, error: String((err && err.message) || err) });
+  if (env && typeof env === 'object' && env.ok === false) return JSON.stringify(env);
+  return JSON.stringify({ ok: false, code: 'op.failed', error: String((err && err.message) || err) });
 }
 
-// One SPARQL Results JSON term object per answer, the wire form
-// Wasm/ExtHost.lean reads; '' means "no value" (the section 17.6 error).
+// One answer for Wasm/Ops/ExtFns.lean: the JavaScript value tagged with its
+// JavaScript type ({js, v}; a number as its Number::toString text), or a term
+// object. The engine chooses the datatype and the lexical form
+// (L4Factoidal.XSD.JsValue.jsLiteral, issue 894 item 3). '' means "no
+// value" (the section 17.6 error).
 function encodeExtAnswer(out) {
   if (out === null || out === undefined || out === EXT_PENDING_MARKER) return '';
-  if (typeof out === 'boolean') {
-    return JSON.stringify({ type: 'literal', value: out ? 'true' : 'false', datatype: XSD + 'boolean' });
-  }
-  if (typeof out === 'number') {
-    if (!Number.isFinite(out)) return '';
-    return Number.isInteger(out)
-      ? JSON.stringify({ type: 'literal', value: String(out), datatype: XSD + 'integer' })
-      : JSON.stringify({ type: 'literal', value: String(out), datatype: XSD + 'double' });
+  switch (typeof out) {
+    case 'boolean': return JSON.stringify({ js: 'boolean', v: out });
+    case 'number': return JSON.stringify({ js: 'number', v: Object.is(out, -0) ? '-0' : String(out) });
+    case 'bigint': return JSON.stringify({ js: 'bigint', v: out.toString() });
+    case 'string': return JSON.stringify({ js: 'string', v: out });
+    case 'object':
+      try { return JSON.stringify(appTermToJson(out)); } catch (_error) { return ''; }
+    default: return '';
   }
-  if (typeof out === 'string') return JSON.stringify({ type: 'literal', value: out });
-  if (typeof out === 'object' && typeof out.type === 'string') return JSON.stringify(out);
-  return '';
 }
 
 // The Lean module asks its host through ONE global,
@@ -158,7 +157,7 @@ export function entryFromEngine(eng) {
     entry[op] = (...args) => {
       if (formatChecked && entry.fullOnlyFormats.includes(String(args[1] ?? '').toLowerCase())) {
         return JSON.stringify({
-          ok: false, servedBy: 'full',
+          ok: false, servedBy: 'full', code: 'op.unknown',
           error: fullEngineMessage(`the format '${args[1]}'`),
         });
       }
@@ -200,5 +199,20 @@ export function entryFromEngine(eng) {
       }
     };
   }
+  // datasetQuadsBin answers a byte region (formal/lean4/L4Factoidal/RDF/QuadsBin.lean):
+  // this method answers {envelope, bytes} and throws on a refusal.
+  const blobIoOps = Array.isArray(reflection.blobIoOps) ? reflection.blobIoOps : [];
+  if (typeof eng.callBlobIO === 'function' && blobIoOps.includes('datasetQuadsBin')) {
+    entry.datasetQuadsBin = (handle, optsJson) => {
+      try {
+        return eng.callBlobIO('datasetQuadsBin', [String(handle), String(optsJson ?? '')], new Uint8Array(0));
+      } catch (err) {
+        if (err && err.envelope) throw errorFromEnvelope(err.envelope);
+        throw err;
+      }
+    };
+  } else {
+    delete entry.datasetQuadsBin;
+  }
   return entry;
 }

package/lib/store.mjs

@@ -17,6 +17,7 @@
 // `factoidal` command.
 
 import { requireChildName } from '../store-host/paths.mjs';
+import { hostError } from './errors.mjs';
 
 /** The manifest file names a generation directory can carry, in the order
  *  the native tools try them. */
@@ -44,10 +45,8 @@ export async function openGeneration(reader, generation) {
     try {
       pointer = await readBytes(reader, 'CURRENT');
     } catch (cause) {
-      const err = new Error(
-        `openStore: the collection root has no readable CURRENT pointer (${cause && cause.message})`);
-      err.cause = cause;
-      throw err;
+      throw hostError(
+        `openStore: the collection root has no readable CURRENT pointer (${cause && cause.message})`, cause);
     }
     // CURRENT holds a UTF-8 generation name (docs/shardborough-storage-spec.md
     // section 6.4); trailing ASCII whitespace is tolerated, as in
@@ -67,7 +66,7 @@ export async function openGeneration(reader, generation) {
     }
     return { generation: name, manifestName, manifest, activated: generation == null };
   }
-  throw new Error(`openStore: generation '${name}' has none of ${MANIFEST_NAMES.join(', ')}`);
+  throw hostError(`openStore: generation '${name}' has none of ${MANIFEST_NAMES.join(', ')}`);
 }
 
 /** Read the named artifacts of one generation into one region, with a

package/lib/version.mjs

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