@factoidal/core 0.19.0 → 0.21.0

package/lib/browser-engine.mjs

@@ -13,6 +13,18 @@
 //
 // No Node built-ins: the browser imports this file as it is.
 
+import { checkEngineStamp } from './engine-integrity.mjs';
+
+// version.json next to the engine, or null (absent, unreadable, not JSON).
+async function stampOf(url) {
+  try {
+    const r = await fetch(url);
+    return r.ok ? await r.json() : null;
+  } catch {
+    return null;
+  }
+}
+
 async function instantiate(url, imports) {
   try {
     return await WebAssembly.instantiateStreaming(fetch(url), imports);
@@ -59,7 +71,22 @@ export function browserEngine(name, defaultAssetsUrl) {
       // newer loader (the loader's own locateFile does the same).
       const version = loader.wasmVersion ? `?v=${loader.wasmVersion}` : '';
       const wasmUrl = new URL(`${name}.wasm`, assetsUrl).href + version;
-      return loader.loadL4({ instantiateWasm: (imports) => instantiate(wasmUrl, imports) });
+      // The release stamp check (engine-integrity.mjs, issue 1106): with a
+      // stamped version.json next to the full engine, its bytes are hashed
+      // before they are compiled (no streaming compile then). Without one,
+      // the streaming path as before.
+      const stamp = name === 'l4factoidal'
+        ? await stampOf(new URL('version.json', assetsUrl).href + version) : null;
+      if (!stamp || stamp.stamped !== true) {
+        return loader.loadL4({ instantiateWasm: (imports) => instantiate(wasmUrl, imports) });
+      }
+      const response = await fetch(wasmUrl);
+      if (!response.ok) {
+        throw new Error(`factoidal: fetching ${wasmUrl} failed: ${response.status} ${response.statusText}`);
+      }
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      await checkEngineStamp(bytes, stamp, { where: wasmUrl });
+      return loader.loadL4({ instantiateWasm: (imports) => WebAssembly.instantiate(bytes, imports) });
     })();
     enginePromise.catch(() => { enginePromise = null; });
     return enginePromise;

package/lib/cid-node.mjs

@@ -0,0 +1,77 @@
+// The Node and Deno host of cidRetrieveVerificationMethod (lib/cid.mjs,
+// https://github.com/danbri/factoidal/issues/1100 item 9): name resolution,
+// and a GET that connects to the one address the engine chose, so a second
+// answer of a name server cannot move the request (the authorization
+// server's fetch, authz/server.mjs). Pure I/O: the engine decides which
+// URL, which address, and what the answer means
+// (formal/lean4/L4Factoidal/CID/Fetch.lean). No redirect is followed.
+
+const FETCH_TIMEOUT_MS = 10000;
+const MAX_DOCUMENT_BYTES = 1048576;
+
+/** Every address of a name, as the system resolver gives them. */
+async function resolve(host) {
+  try {
+    const dns = await import('node:dns');
+    const found = await dns.promises.lookup(host, { all: true, verbatim: true });
+    return found.map((a) => a.address);
+  } catch (_error) {
+    return [];
+  }
+}
+
+// A Response-like answer: status, headers.get, text().
+function answer(status, contentType, body) {
+  return {
+    status,
+    headers: { get: (name) => (String(name).toLowerCase() === 'content-type' ? contentType : null) },
+    text: async () => body,
+  };
+}
+
+/**
+ * GET `url` from `init.address`, sending `init.headers`. With no address
+ * (the engine named none), the system resolver connects.
+ */
+async function fetch(url, init) {
+  let target;
+  try {
+    target = new URL(url);
+  } catch (_error) {
+    return answer(0, '', '');
+  }
+  const mod = target.protocol === 'https:' ? await import('node:https') : await import('node:http');
+  const address = init && typeof init.address === 'string' ? init.address : null;
+  const family = address && address.indexOf(':') >= 0 ? 6 : 4;
+  const options = { method: 'GET', headers: (init && init.headers) || {}, timeout: FETCH_TIMEOUT_MS };
+  if (address) {
+    options.lookup = (_host, opts, callback) => {
+      if (opts && opts.all) callback(null, [{ address, family }]);
+      else callback(null, address, family);
+    };
+  }
+  return new Promise((done) => {
+    const request = mod.request(target, options, (response) => {
+      const chunks = [];
+      let size = 0;
+      response.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > MAX_DOCUMENT_BYTES) {
+          response.destroy();
+          done(answer(0, '', ''));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on('end', () => done(answer(response.statusCode || 0,
+        String(response.headers['content-type'] || ''), Buffer.concat(chunks).toString('utf8'))));
+      response.on('error', () => done(answer(0, '', '')));
+    });
+    request.on('timeout', () => request.destroy(new Error('timeout')));
+    request.on('error', () => done(answer(0, '', '')));
+    request.end();
+  });
+}
+
+/** The host index.mjs passes to the API. */
+export const nodeCidHost = Object.freeze({ resolve, fetch });

package/lib/cid.mjs

@@ -0,0 +1,146 @@
+// Controlled Identifiers v1.0 (https://www.w3.org/TR/cid-1.0/):
+// cidValidate and cidRetrieveVerificationMethod
+// (https://github.com/danbri/factoidal/issues/1100, items 7 and 9).
+//
+// The engine decides everything (formal/lean4/L4Factoidal/CID/Validate.lean,
+// CID/Fetch.lean, over the ops cidValidate and cidRetrieve of
+// formal/lean4/Wasm/Ops/Cid.lean): the §2 checks; which URL to fetch; whether
+// its scheme and addresses may be fetched (the private-address guard of the
+// authorization server); whether the status and the Content-Type of the
+// answer are accepted; §3.3; expiry and revocation with `now`. This file
+// moves bytes: it resolves the host name the engine names, GETs the URL the
+// engine names from the address the engine names, and passes the status,
+// the Content-Type and the body back.
+//
+// ES module, no Node built-ins: the browser loads this file as it is. The
+// Node and Deno host functions (name resolution, a GET pinned to one
+// address) are lib/cid-node.mjs, which index.mjs passes in.
+
+import { FactoidalError } from './errors.mjs';
+
+// The engine names at most one resolution and one fetch; a longer loop is
+// a defect, not a document.
+const MAX_STEPS = 4;
+
+/**
+ * The browser host: no name resolution (a page cannot resolve names; the
+ * engine then checks only IP literals and localhost names), and the page's
+ * fetch, which does not follow redirects and sends no credentials.
+ */
+export const browserCidHost = Object.freeze({
+  resolve: null,
+  fetch: (url, init) => globalThis.fetch(url, {
+    method: 'GET',
+    headers: init.headers,
+    redirect: 'manual',
+    credentials: 'omit',
+  }),
+});
+
+// The status, Content-Type and body of a fetch answer: a WHATWG Response,
+// or an object of the same shape.
+async function answerOf(url, response) {
+  const status = Number(response && response.status) || 0;
+  const headers = response && response.headers;
+  const contentType = headers && typeof headers.get === 'function'
+    ? (headers.get('content-type') || '') : '';
+  const body = response && typeof response.text === 'function' ? String(await response.text()) : '';
+  return { url, status, contentType, body };
+}
+
+function nowSeconds(now) {
+  if (now === undefined || now === null) return undefined;
+  if (now instanceof Date) return Math.floor(now.getTime() / 1000);
+  if (typeof now === 'number' && Number.isFinite(now)) return Math.floor(now);
+  throw new TypeError('cidRetrieveVerificationMethod: options.now must be a Date or a number of seconds');
+}
+
+/**
+ * The two functions over an entry (lib/lean-entry.mjs) and a host.
+ * @param {object} deps
+ * @param {() => Promise<object>} deps.entry
+ * @param {(jsonText: string, what: string) => object} deps.entryResult
+ * @param {(e: object, fn: string, what: string) => void} deps.requireEntryFn
+ * @param {{resolve: ((host: string) => Promise<string[]>)|null, fetch: Function}} [deps.host]
+ */
+export function cidFunctions({ entry, entryResult, requireEntryFn, host }) {
+  const defaults = host || browserCidHost;
+
+  /**
+   * CID 1.0 §2: check a controlled identifier document.
+   * @param {string|object} doc JSON text, or a value JSON.stringify writes
+   * @returns {Promise<{valid: boolean, errors: Array<{code: string, message: string, path: string}>}>}
+   */
+  async function cidValidate(doc) {
+    const text = typeof doc === 'string' ? doc : JSON.stringify(doc);
+    if (typeof text !== 'string') throw new TypeError('cidValidate: doc must be JSON text or a JSON value');
+    const e = await entry();
+    requireEntryFn(e, 'cidValidate', 'CID 1.0 document check');
+    const r = entryResult(e.cidValidate(text), 'cidValidate');
+    return { valid: r.valid === true, errors: Array.isArray(r.errors) ? r.errors : [] };
+  }
+
+  /**
+   * CID 1.0 §3.3 Retrieve Verification Method, with the fetch done here.
+   * @param {string} url the verification method URL
+   * @param {string} relationship a verification relationship of §2.3
+   * @param {object} [options]
+   * @returns {Promise<{ok: true, verificationMethod: object, controllerDocument: string}
+   *                  | {ok: false, code: string, problem: {type: string, title: string, detail: string}}>}
+   */
+  async function cidRetrieveVerificationMethod(url, relationship, options) {
+    if (typeof url !== 'string' || typeof relationship !== 'string') {
+      throw new TypeError('cidRetrieveVerificationMethod: url and relationship must be strings');
+    }
+    const o = options || {};
+    const fetchFn = typeof o.fetch === 'function' ? o.fetch : defaults.fetch;
+    // `resolve: null` says the caller cannot resolve names.
+    const resolveFn = 'resolve' in o ? o.resolve : defaults.resolve;
+    const request = {
+      vm: url,
+      relationship,
+      allowHttp: o.allowHttp === true,
+      allowPrivateFetch: o.allowPrivateFetch === true,
+      resolver: typeof resolveFn === 'function',
+      resolved: [],
+      fetched: [],
+    };
+    const now = nowSeconds(o.now);
+    if (now !== undefined) request.now = now;
+    const e = await entry();
+    requireEntryFn(e, 'cidRetrieve', 'CID 1.0 Retrieve Verification Method');
+    for (let i = 0; i < MAX_STEPS; i += 1) {
+      const r = entryResult(e.cidRetrieve(JSON.stringify(request)), 'cidRetrieve');
+      if (r.step === 'method') {
+        return { ok: true, verificationMethod: r.verificationMethod, controllerDocument: r.controllerDocument };
+      }
+      if (r.step === 'error') return { ok: false, code: r.code, problem: r.problem };
+      if (r.step === 'resolve') {
+        let addresses = [];
+        try {
+          const got = await resolveFn(r.host);
+          addresses = Array.isArray(got) ? got.map(String) : [];
+        } catch (_error) {
+          addresses = [];
+        }
+        request.resolved.push({ host: r.host, addresses });
+      } else if (r.step === 'fetch') {
+        let answer;
+        try {
+          const init = { method: 'GET', headers: { accept: r.accept }, redirect: 'manual' };
+          if (r.address !== null && r.address !== undefined) init.address = r.address;
+          answer = await answerOf(r.url, await fetchFn(r.url, init));
+        } catch (_error) {
+          answer = { url: r.url, status: 0, contentType: '', body: '' };
+        }
+        request.fetched.push(answer);
+      } else {
+        break;
+      }
+    }
+    throw new FactoidalError('cidRetrieveVerificationMethod: the engine asked for more steps than one retrieval needs',
+      { code: 'op.failed' });
+  }
+
+  return { cidValidate, cidRetrieveVerificationMethod };
+}

package/lib/cipher-host.mjs

@@ -0,0 +1,126 @@
+// cipher-host.mjs — the JavaScript host side of the AES call-out
+// (https://github.com/danbri/factoidal/issues/1081,
+// https://github.com/danbri/factoidal/issues/677; design record
+// docs/designissues/2026-10-27-xml-encryption-and-jwe.md, section "The AES
+// call-out on JavaScript hosts"; request format
+// formal/lean4/L4Factoidal/Crypto/CipherCall.lean).
+//
+// The engine (Lean, in the wasm) makes every decision: the algorithm, the key,
+// the IV, the lengths (`Req.wellFormed`), the document structure. When it needs
+// AES it answers `{need: {op, key, iv, aad, data}}` (bytes as base64). This
+// module runs exactly that one WebCrypto operation and gives back
+// `{ok: base64}` or `{refused: true}`. It reads no document, chooses no
+// algorithm and checks no length. Every failure becomes the same refusal with
+// no message, so no error text of the host's crypto library reaches the caller
+// (padding oracle, Jager and Somorovsky 2011).
+//
+// Only `globalThis.crypto.subtle` is used, so the same code runs in Node 22,
+// Deno and browsers (Node: OpenSSL; Chromium: BoringSSL; Firefox: NSS).
+//
+// PBKDF2 (https://github.com/danbri/factoidal/issues/1108, the login of
+// `factoidal webdav-serve` and `factoidal webdav-user`; owner, 2026-10-28:
+// PBKDF2-HMAC-SHA256 from WebCrypto, as AES): the engine answers
+// `{need: {op: 'pbkdf2-hmac-sha256', key, data, iterations, bits}}` with the
+// password as `key` and the salt as `data`. This module runs exactly that
+// `deriveBits` call; Lean chose the salt, the count and the output size
+// (formal/lean4/L4Factoidal/WebDAV/Login.lean) and compares the result.
+//
+// Key Wrap: WebCrypto wraps a CryptoKey, not bytes. The bytes to wrap are
+// imported as an extractable raw HMAC key (any byte length), wrapped with
+// `wrapKey('raw', ...)`; an unwrap gives an HMAC key whose raw export is the
+// unwrapped bytes.
+
+const subtle = () => globalThis.crypto.subtle;
+
+/** The most requests one engine operation may make (CipherCall.maxRequests). */
+export const MAX_CIPHER_REQUESTS = 64;
+
+function fromBase64(s) {
+  const bin = atob(s ?? '');
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function toBase64(buf) {
+  const b = new Uint8Array(buf);
+  let bin = '';
+  for (let i = 0; i < b.length; i += 0x8000) {
+    bin += String.fromCharCode.apply(null, b.subarray(i, i + 0x8000));
+  }
+  return btoa(bin);
+}
+
+const HMAC = { name: 'HMAC', hash: 'SHA-256' };
+
+// One entry per op name of CipherCall.Op.name: the WebCrypto call, nothing more.
+const OPS = {
+  'aes-gcm-encrypt': async (k, iv, aad, d) => {
+    const key = await subtle().importKey('raw', k, 'AES-GCM', false, ['encrypt']);
+    return subtle().encrypt({ name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, key, d);
+  },
+  'aes-gcm-decrypt': async (k, iv, aad, d) => {
+    const key = await subtle().importKey('raw', k, 'AES-GCM', false, ['decrypt']);
+    return subtle().decrypt({ name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, key, d);
+  },
+  'aes-kw-wrap': async (k, _iv, _aad, d) => {
+    const kek = await subtle().importKey('raw', k, 'AES-KW', false, ['wrapKey']);
+    const inner = await subtle().importKey('raw', d, HMAC, true, ['sign']);
+    return subtle().wrapKey('raw', inner, kek, 'AES-KW');
+  },
+  'aes-kw-unwrap': async (k, _iv, _aad, d) => {
+    const kek = await subtle().importKey('raw', k, 'AES-KW', false, ['unwrapKey']);
+    const inner = await subtle().unwrapKey('raw', d, kek, 'AES-KW', HMAC, true, ['sign']);
+    return subtle().exportKey('raw', inner);
+  },
+  'aes-cbc-encrypt': async (k, iv, _aad, d) => {
+    const key = await subtle().importKey('raw', k, 'AES-CBC', false, ['encrypt']);
+    return subtle().encrypt({ name: 'AES-CBC', iv }, key, d);
+  },
+  'aes-cbc-decrypt': async (k, iv, _aad, d) => {
+    const key = await subtle().importKey('raw', k, 'AES-CBC', false, ['decrypt']);
+    return subtle().decrypt({ name: 'AES-CBC', iv }, key, d);
+  },
+  'pbkdf2-hmac-sha256': async (k, _iv, _aad, d, req) => {
+    const key = await subtle().importKey('raw', k, 'PBKDF2', false, ['deriveBits']);
+    return subtle().deriveBits({ name: 'PBKDF2', hash: 'SHA-256', salt: d, iterations: req.iterations }, key, req.bits);
+  },
+};
+
+/**
+ * Answer one cipher request of the engine (AES, or the PBKDF2 of a login).
+ * @param {{op: string, key: string, iv?: string, aad?: string, data: string, iterations?: number, bits?: number}} req  bytes as base64
+ * @returns {Promise<{ok: string} | {refused: true}>}
+ */
+export async function answerCipherRequest(req) {
+  try {
+    const run = Object.prototype.hasOwnProperty.call(OPS, req?.op) ? OPS[req.op] : null;
+    if (!run) return { refused: true };
+    const out = await run(fromBase64(req.key), fromBase64(req.iv), fromBase64(req.aad), fromBase64(req.data), req);
+    return { ok: toBase64(out) };
+  } catch {
+    return { refused: true };
+  }
+}
+
+/**
+ * Run an engine operation that may ask for AES. `callOp(args)` calls the wasm
+ * op (sync or async) with `args` plus `answers`; while its result has `need`,
+ * the request is answered and the op is called again with the same inputs and
+ * the answer list extended by `{request, answer}`. The engine's format code is
+ * deterministic, so each call gets one request further.
+ * @param {(args: object) => any} callOp
+ * @param {object} args
+ */
+export async function runWithCipher(callOp, args) {
+  const answers = [];
+  for (let asked = 0; ; asked++) {
+    const res = await callOp({ ...args, answers: answers.slice() });
+    if (!res || res.need === undefined) return res;
+    // The request bound is the one check the host makes (design record step 4).
+    if (asked === MAX_CIPHER_REQUESTS) {
+      throw new Error(`runWithCipher: more than ${MAX_CIPHER_REQUESTS} cipher requests`);
+    }
+    answers.push({ request: res.need, answer: await answerCipherRequest(res.need) });
+  }
+}

package/lib/dataset.mjs

@@ -405,22 +405,44 @@ class Dataset {
       termToJson(graph)]);
   }
 
-  /** RDF/JS DatasetCore.has: one indexed lookup in the engine. */
-  has(quad) {
+  // The options argument of has, match and delete: `{match: 'term'|'value'}`,
+  // checked by the engine (op apiCheck). '' for the term match, which every
+  // engine serves with the two-argument ops.
+  _matchMode(who, options) {
+    if (options === undefined || options === null) return '';
+    checkOptions(this._ctx.e, `Dataset.${who}`, options);
+    if (options.match === undefined || options.match === null) return '';
+    const mode = String(options.match).toLowerCase();
+    return mode === 'term' ? '' : JSON.stringify({ match: mode });
+  }
+
+  /**
+   * RDF/JS DatasetCore.has: one indexed lookup in the engine. With
+   * `{match: 'value'}` a literal object matches every object literal of the
+   * same value (sameValue(); https://github.com/danbri/factoidal/issues/1052).
+   */
+  has(quad, options) {
     this._open('has');
-    const r = envelope(this._ctx.e.datasetMatchCount(this._handle,
-      this._pattern(quad.subject, quad.predicate, quad.object, quad.graph || { termType: 'DefaultGraph' })), 'has');
+    const mode = this._matchMode('has', options);
+    const pattern = this._pattern(quad.subject, quad.predicate, quad.object, quad.graph || { termType: 'DefaultGraph' });
+    const r = envelope(mode
+      ? this._ctx.e.datasetMatchCount(this._handle, pattern, mode)
+      : this._ctx.e.datasetMatchCount(this._handle, pattern), 'has');
     return r.count > 0;
   }
 
   /**
    * RDF/JS DatasetCore.match: the matching quads as a new Dataset, found
-   * through the engine's indexes. `null`/`undefined` matches any term.
+   * through the engine's indexes. `null`/`undefined` matches any term. With
+   * `{match: 'value'}` a literal object matches by value (as has()).
    */
-  match(subject, predicate, object, graph) {
+  match(subject, predicate, object, graph, options) {
     this._open('match');
-    const r = envelope(this._ctx.e.datasetMatch(this._handle,
-      this._pattern(subject, predicate, object, graph)), 'match');
+    const mode = this._matchMode('match', options);
+    const pattern = this._pattern(subject, predicate, object, graph);
+    const r = envelope(mode
+      ? this._ctx.e.datasetMatch(this._handle, pattern, mode)
+      : this._ctx.e.datasetMatch(this._handle, pattern), 'match');
     return this._ctx.wrap(r, this._prefixes);
   }
 
@@ -438,15 +460,77 @@ class Dataset {
     return this;
   }
 
-  /** RDF/JS DatasetCore.delete: remove one quad. */
-  delete(quad) {
+  /**
+   * RDF/JS DatasetCore.delete: remove one quad. With `{match: 'value'}` a
+   * literal object removes every quad of the same subject, predicate and
+   * graph whose object has the same value (as has()).
+   */
+  delete(quad, options) {
     this._open('delete');
-    const r = envelope(this._ctx.e.datasetDeleteQuadsJson(this._handle,
-      JSON.stringify([quadToJson(quad)])), 'delete');
+    const mode = this._matchMode('delete', options);
+    const quads = JSON.stringify([quadToJson(quad)]);
+    const r = envelope(mode
+      ? this._ctx.e.datasetDeleteQuadsJson(this._handle, quads, mode)
+      : this._ctx.e.datasetDeleteQuadsJson(this._handle, quads), 'delete');
     this._changed(r.count);
     return this;
   }
 
+  // RDF lists and containers (https://github.com/danbri/factoidal/issues/1051
+  // item 6). The engine walks and builds them (L4Factoidal.RDF.Collections).
+  // `graph`: null/undefined or the DefaultGraph for the default graph, else
+  // the graph name.
+  _collectionOp(op, who) {
+    this._open(who);
+    if (typeof this._ctx.e[op] !== 'function') {
+      throw new FactoidalError(`Dataset.${who}: the loaded engine has no op '${op}'; it is older than this package`,
+        { code: 'op.unknown' });
+    }
+    return this._ctx.e[op].bind(this._ctx.e);
+  }
+
+  _graphArg(graph) {
+    return graph === undefined || graph === null ? '' : JSON.stringify(termToJson(graph));
+  }
+
+  /**
+   * The items of the RDF list (rdf:first / rdf:rest) at `head`, in order.
+   * rdf:nil is the empty list. A list that is not well formed (a node with no
+   * or two rdf:first or rdf:rest, or a cycle) is a FactoidalError (op.failed)
+   * whose message names the reason and the node.
+   */
+  listItems(head, graph) {
+    const op = this._collectionOp('datasetListItems', 'listItems');
+    const r = envelope(op(this._handle, JSON.stringify(termToJson(head)), this._graphArg(graph)), 'listItems');
+    return r.items.map(termFromSrj);
+  }
+
+  /**
+   * The members rdf:_1, rdf:_2, ... of `node`, sorted by n, and its kind
+   * (rdf:Bag, rdf:Seq or rdf:Alt from its rdf:type, or null).
+   * @returns {{kind: NamedNode|null, items: Array<{ordinal: number, term: Term}>}}
+   */
+  containerItems(node, graph) {
+    const op = this._collectionOp('datasetContainerItems', 'containerItems');
+    const r = envelope(op(this._handle, JSON.stringify(termToJson(node)), this._graphArg(graph)), 'containerItems');
+    return {
+      kind: r.kind ? termFromSrj(r.kind) : null,
+      items: r.items.map((m) => ({ ordinal: m.ordinal, term: termFromSrj(m.term) })),
+    };
+  }
+
+  /**
+   * Add a new RDF list of `items` (new blank nodes, fresh in this Dataset)
+   * and answer its head; the empty list is rdf:nil and adds nothing.
+   */
+  addList(items, graph) {
+    const op = this._collectionOp('datasetAddList', 'addList');
+    const r = envelope(op(this._handle, JSON.stringify([...items].map((t) => termToJson(t))),
+      this._graphArg(graph)), 'addList');
+    this._changed(r.count);
+    return termFromSrj(r.head);
+  }
+
   /** Release the engine copy. Idempotent. */
   dispose() {
     if (this._disposed) return;

package/lib/engine-integrity.mjs

@@ -0,0 +1,56 @@
+// The load-time check of the engine against its release stamp
+// (https://github.com/danbri/factoidal/issues/1106, layer 1).
+//
+// A release stamps l4-assets/version.json with the SHA-256 and the size of
+// l4factoidal.wasm (tools/stamp-l4-version.mjs). Before an engine is
+// instantiated, its bytes are hashed and compared with the stamp: a stamped
+// copy whose bytes differ does not load. An unstamped copy (a source
+// checkout, a local build that did not stamp) loads as before.
+//
+// This catches accidents (a stale wasm next to a new loader, a partial
+// upgrade, a hand edit). It is not a defence against someone who can edit
+// the package: they can edit this file too. See issue 1106 for the checks
+// made from outside the package.
+//
+// ES module, no Node built-ins: Node, Deno and the browser load it as it is.
+// The digest is Web Crypto's SHA-256 (globalThis.crypto.subtle).
+
+/** Lowercase hex SHA-256 of `bytes` (a Uint8Array or an ArrayBuffer). */
+export async function sha256Hex(bytes) {
+  const subtle = globalThis.crypto && globalThis.crypto.subtle;
+  if (!subtle) throw new Error('factoidal: no Web Crypto SHA-256 to check the engine with');
+  const digest = new Uint8Array(await subtle.digest('SHA-256', bytes));
+  let hex = '';
+  for (const b of digest) hex += b.toString(16).padStart(2, '0');
+  return hex;
+}
+
+/**
+ * Check engine bytes against a version.json stamp.
+ * @param {Uint8Array|ArrayBuffer} bytes the wasm
+ * @param {object|null} stamp the parsed version.json, or null when absent
+ * @param {{where?: string, allowModified?: boolean, warn?: (msg: string) => void}} [opts]
+ * @returns {Promise<{checked: boolean, sha256?: string}>} `checked` false for
+ *   an absent or unstamped version.json
+ */
+export async function checkEngineStamp(bytes, stamp, opts = {}) {
+  if (!stamp || stamp.stamped !== true || typeof stamp.wasmSha256 !== 'string') {
+    return { checked: false };
+  }
+  const size = bytes.byteLength;
+  const sha256 = await sha256Hex(bytes);
+  const sizeOk = !Number.isInteger(stamp.wasmBytes) || stamp.wasmBytes === size;
+  if (sha256 === stamp.wasmSha256.toLowerCase() && sizeOk) return { checked: true, sha256 };
+  const where = opts.where || 'l4factoidal.wasm';
+  const msg = `factoidal: ${where} is not the engine of this release: version.json ` +
+    `(build ${stamp.release ?? stamp.gitSha ?? '?'}) says sha256 ${stamp.wasmSha256}, ${stamp.wasmBytes ?? '?'} bytes; ` +
+    `the file has sha256 ${sha256}, ${size} bytes. Reinstall @factoidal/core, ` +
+    'or set FACTOIDAL_ALLOW_MODIFIED_ENGINE=1 to load a changed engine on purpose.';
+  if (opts.allowModified) {
+    (opts.warn || (() => {}))(`${msg} Loading it because FACTOIDAL_ALLOW_MODIFIED_ENGINE is set.`);
+    return { checked: false, sha256 };
+  }
+  const err = new Error(msg);
+  err.code = 'engine.modified';
+  throw err;
+}

package/lib/lean-entry.mjs

@@ -63,22 +63,40 @@ function failEnvelope(err) {
   return JSON.stringify({ ok: false, code: 'op.failed', error: String((err && err.message) || err) });
 }
 
+/**
+ * A JavaScript value tagged with its JavaScript type, {js, v}, for the engine
+ * (Wasm/Ops/ExtFns.lean, Wasm/Ops/LiteralValue.lean). This copies the value
+ * as text; the engine chooses the datatype and the lexical form
+ * (L4Factoidal.XSD.JsValue.jsLiteral, issue 894 item 3, issue 1051 item 1).
+ * A number is its Number::toString text ('-0' for negative zero); a Date is
+ * the text of getTime() ('NaN' for an invalid Date). Any other value: null.
+ * @param {unknown} value
+ * @returns {{js: string, v: string|boolean} | null}
+ */
+export function encodeJsValue(value) {
+  switch (typeof value) {
+    case 'boolean': return { js: 'boolean', v: value };
+    case 'number': return { js: 'number', v: Object.is(value, -0) ? '-0' : String(value) };
+    case 'bigint': return { js: 'bigint', v: value.toString() };
+    case 'string': return { js: 'string', v: value };
+    case 'object':
+      if (value instanceof Date) return { js: 'date', v: String(value.getTime()) };
+      return null;
+    default: return null;
+  }
+}
+
 // 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).
+// JavaScript type (encodeJsValue), or a term object. '' means "no value" (the
+// section 17.6 error).
 function encodeExtAnswer(out) {
   if (out === null || out === undefined || out === EXT_PENDING_MARKER) return '';
-  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 '';
+  const tagged = encodeJsValue(out);
+  if (tagged) return JSON.stringify(tagged);
+  if (typeof out === 'object') {
+    try { return JSON.stringify(appTermToJson(out)); } catch (_error) { return ''; }
   }
+  return '';
 }
 
 // The Lean module asks its host through ONE global,