@factoidal/core 0.7.0 → 0.10.0

package/lib/lean-entry.mjs

@@ -0,0 +1,204 @@
+// The entry object over a loaded Lean engine handle.
+//
+// A Lean engine handle is what `loadL4()` of l4-assets/l4factoidal.js
+// answers: `call(op, args)`, `callBlob(op, args, bytes)`,
+// `callBlobIO(op, args, bytes)` over the dispatch ABI of
+// formal/lean4/Wasm/Dispatch.lean. Those methods parse the envelope and
+// THROW on {"ok":false,...}. lib/api.mjs wants the other shape: one method
+// per op, string arguments, the envelope as a JSON string, errors as
+// {"ok":false} envelopes. entryFromEngine() builds that object.
+//
+// Which ops exist is the engine's own answer: the `ops` reflection op
+// lists them, and the entry object has a method for each name in that list
+// and for no other. capabilities() in lib/api.mjs probes the methods, so a
+// wasm module older than this package reports what it serves.
+//
+// Four ops need more than strings in and an envelope out, and get their
+// own adapters below:
+//   - queryHdt and storeOpen read a byte region (the dispatch ABI's blob);
+//   - registerExtensionFunction / unregisterExtensionFunction /
+//     clearExtensionFunctions install the JavaScript call-out of SPARQL 1.1
+//     section 17.6 (the ops extRegister, extUnregister, extClear).
+// 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.
+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).
+export const CORE_ENTRY = 'l4factoidal-core.js (the hub build of the core profile)';
+
+/**
+ * The message of a refusal by the core engine of something only the full
+ * engine serves.
+ * @param {string} what the function, op or format refused
+ */
+export function fullEngineMessage(what) {
+  return `${what} is not in the core engine (${CORE_ENTRY}, ` +
+    `l4factoidal-core.wasm); import '${FULL_ENTRY}', whose full engine ` +
+    '(l4factoidal.wasm) serves it';
+}
+
+// The ops whose second argument is a format tag of a document they read.
+const DOCUMENT_FORMAT_OPS = new Set(['parseToDatasetJson', 'datasetOpen', 'parseDocument']);
+const EXT_PENDING_MARKER = '__FACTOIDAL_EXT_PENDING__';
+
+function okEnvelope(extra) {
+  return JSON.stringify({ ok: true, ...(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>".
+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) });
+}
+
+// One SPARQL Results JSON term object per answer, the wire form
+// Wasm/ExtHost.lean reads; '' 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' });
+  }
+  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,
+// `globalThis.__factoidalExtCall(iri, argsJson)` (Wasm/ExtHost.lean). The
+// bridges lib/api.mjs registers are keyed by IRI here.
+function installExtensionBridge(eng, entry) {
+  const bridges = new Map();
+  const hostCall = (iri, argsJson) => {
+    const bridge = bridges.get(String(iri));
+    if (!bridge) return '';
+    try {
+      return encodeExtAnswer(bridge(String(iri), String(argsJson)));
+    } catch (_err) {
+      return '';
+    }
+  };
+  entry.registerExtensionFunction = (iri, bridge) => {
+    try {
+      eng.call('extRegister', [String(iri)]);
+      bridges.set(String(iri), bridge);
+      globalThis.__factoidalExtCall = hostCall;
+      return okEnvelope();
+    } catch (err) {
+      return failEnvelope(err);
+    }
+  };
+  entry.unregisterExtensionFunction = (iri) => {
+    try {
+      eng.call('extUnregister', [String(iri)]);
+      bridges.delete(String(iri));
+      return okEnvelope();
+    } catch (err) {
+      return failEnvelope(err);
+    }
+  };
+  entry.clearExtensionFunctions = () => {
+    try {
+      eng.call('extClear', []);
+      bridges.clear();
+      return okEnvelope();
+    } catch (err) {
+      return failEnvelope(err);
+    }
+  };
+}
+
+/**
+ * Build the entry object lib/api.mjs drives, from a loaded engine handle.
+ *
+ * @param {{call: Function, callBlob?: Function, callBlobIO?: Function}} eng
+ * @returns {Record<string, Function> & {abiVersion: string, engine: object}}
+ */
+export function entryFromEngine(eng) {
+  if (!eng || typeof eng.call !== 'function') {
+    throw new TypeError(
+      'factoidal: expected a Lean engine handle with a call(op, args) method ' +
+      '(the value loadL4() of l4-assets/l4factoidal.js resolves to)');
+  }
+  const reflection = eng.call('ops', []);
+  // `engine` is "core" for l4factoidal-core.wasm and "full" for
+  // l4factoidal.wasm; a module older than issue 713 stage 4 has no member and
+  // is the full engine.
+  const profile = reflection.engine === 'core' ? 'core' : 'full';
+  const entry = {
+    abiVersion: String(reflection.abiVersion),
+    engine: eng,
+    profile,
+    fullOnlyOps: Array.isArray(reflection.fullOnlyOps) ? reflection.fullOnlyOps.map(String) : [],
+    fullOnlyFormats: Array.isArray(reflection.fullOnlyFormats)
+      ? reflection.fullOnlyFormats.map((f) => String(f).toLowerCase()) : [],
+  };
+  const ops = Array.isArray(reflection.ops) ? reflection.ops : [];
+  for (const op of ops) {
+    if (op === 'ops') continue;
+    const formatChecked = DOCUMENT_FORMAT_OPS.has(op) && entry.fullOnlyFormats.length > 0;
+    entry[op] = (...args) => {
+      if (formatChecked && entry.fullOnlyFormats.includes(String(args[1] ?? '').toLowerCase())) {
+        return JSON.stringify({
+          ok: false, servedBy: 'full',
+          error: fullEngineMessage(`the format '${args[1]}'`),
+        });
+      }
+      try {
+        return JSON.stringify(eng.call(op, args.map(String)));
+      } catch (err) {
+        return failEnvelope(err);
+      }
+    };
+  }
+  if (ops.includes('extRegister')) installExtensionBridge(eng, entry);
+  // The byte-region ops. `bytes` is a Uint8Array; it crosses into the wasm
+  // heap with no encoding.
+  // queryHdt goes through the IO form of the blob entry when the engine has it:
+  // that entry reads the system clock once for the query, so NOW() (SPARQL 1.1
+  // section 17.4.5.1) is bound. The pure `callBlob` has no clock. An engine
+  // without `callBlobIO` serves the op through `callBlob`, as before
+  // (https://github.com/danbri/factoidal/issues/743).
+  if ((typeof eng.callBlobIO === 'function' || typeof eng.callBlob === 'function') &&
+      ops.includes('queryHdt')) {
+    entry.queryHdt = (bytes, sparql) => {
+      try {
+        const args = [String(sparql)];
+        return JSON.stringify(typeof eng.callBlobIO === 'function'
+          ? eng.callBlobIO('queryHdt', args, bytes).envelope
+          : eng.callBlob('queryHdt', args, bytes));
+      } catch (err) {
+        return failEnvelope(err);
+      }
+    };
+  }
+  if (typeof eng.callBlobIO === 'function' && ops.includes('storeOpen')) {
+    entry.storeOpen = (manifestHex, artifactsJson, bytes) => {
+      try {
+        return JSON.stringify(
+          eng.callBlobIO('storeOpen', [String(manifestHex), String(artifactsJson)], bytes).envelope);
+      } catch (err) {
+        return failEnvelope(err);
+      }
+    };
+  }
+  return entry;
+}

package/lib/pure.mjs

@@ -0,0 +1,98 @@
+// Pure functions over engine ops that had no JavaScript function before
+// 0.10.0. Each one takes values and returns a value: no handle, no hidden
+// state. Every decision is made by the Lean op it calls
+// (formal/lean4/Wasm/Ops/Crypto.lean, Wasm/Ops/Proof.lean,
+// Wasm/CoreDispatch.lean). This file converts bytes to hex and back.
+// No Node built-ins: the browser imports it as it is.
+
+function hexOf(bytes) {
+  if (!(bytes instanceof Uint8Array)) throw new TypeError('expected a Uint8Array');
+  let s = '';
+  for (const b of bytes) s += b.toString(16).padStart(2, '0');
+  return s;
+}
+
+function bytesOf(hex) {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.substr(2 * i, 2), 16);
+  return out;
+}
+
+function optHex(v) {
+  return v === undefined ? undefined : hexOf(v);
+}
+
+function str(name, v) {
+  if (typeof v !== 'string') throw new TypeError(`${name}: argument must be a string`);
+  return v;
+}
+
+/**
+ * @param {() => Promise<object>} loadEngine resolves to an engine handle
+ *   with `call(op, args)` (bin/engine.mjs, lib/browser-engine.mjs).
+ */
+export function buildPure(loadEngine) {
+  const call = async (op, args) => (await loadEngine()).call(op, args);
+
+  /** ChaCha20-Poly1305 seal (RFC 8439). key 32 bytes, nonce 12 bytes. */
+  async function aeadSeal({ key, nonce, plaintext, aad }) {
+    const r = await call('aeadSeal', [JSON.stringify({
+      alg: 'chacha20-poly1305', key: hexOf(key), nonce: hexOf(nonce),
+      aad: optHex(aad), plaintext: optHex(plaintext),
+    })]);
+    return bytesOf(r.ciphertext);
+  }
+
+  /** ChaCha20-Poly1305 open. Rejects when the tag does not authenticate. */
+  async function aeadOpen({ key, nonce, ciphertext, aad }) {
+    const r = await call('aeadOpen', [JSON.stringify({
+      alg: 'chacha20-poly1305', key: hexOf(key), nonce: hexOf(nonce),
+      aad: optHex(aad), ciphertext: hexOf(ciphertext),
+    })]);
+    return bytesOf(r.plaintext);
+  }
+
+  /** HPKE base mode seal, RFC 9180 DHKEM(X25519)/HKDF-SHA256/ChaCha20-Poly1305. */
+  async function hpkeSeal({ skE, pkR, plaintext, info, aad }) {
+    const r = await call('hpkeSeal', [JSON.stringify({
+      skE: hexOf(skE), pkR: hexOf(pkR), info: optHex(info),
+      aad: optHex(aad), plaintext: optHex(plaintext),
+    })]);
+    return { message: bytesOf(r.message), enc: bytesOf(r.enc), ciphertext: bytesOf(r.ciphertext) };
+  }
+
+  /** HPKE base mode open over the `message` that hpkeSeal returned. */
+  async function hpkeOpen({ skR, message, info, aad }) {
+    const r = await call('hpkeOpen', [JSON.stringify({
+      skR: hexOf(skR), info: optHex(info), aad: optHex(aad), message: hexOf(message),
+    })]);
+    return bytesOf(r.plaintext);
+  }
+
+  /** Check an FPP0 proof bundle (JSON text). Returns the engine's report. */
+  async function proofCheck(bundleJson) {
+    const { ok, ...rest } = await call('proofCheck', [str('proofCheck', bundleJson)]);
+    return rest;
+  }
+
+  /** Describe the shape of an FPP0 proof bundle without checking it. */
+  async function proofInspect(bundleJson) {
+    const { ok, ...rest } = await call('proofInspect', [str('proofInspect', bundleJson)]);
+    return rest;
+  }
+
+  /** RDFC-1.0 over N-Quads text, N-Quads text out. */
+  async function canonicalizeNQuads(nquads) {
+    return (await call('canonicalizeToNQuads', [str('canonicalizeNQuads', nquads)])).nquads;
+  }
+
+  /** Parse N-Quads (or N-Triples) text and write it back as N-Quads. */
+  async function normalizeNQuads(nquads) {
+    return (await call('serializeNQuads', [str('normalizeNQuads', nquads)])).nquads;
+  }
+
+  return {
+    aeadSeal, aeadOpen, hpkeSeal, hpkeOpen,
+    proofCheck, proofInspect, canonicalizeNQuads, normalizeNQuads,
+  };
+}

package/lib/store.mjs

@@ -0,0 +1,115 @@
+// Host plumbing for the Lean persisted store (Shardborough IBK3/IBK4/IBK5
+// generations), shared by Node and the browser.
+//
+// A store is read through a READER: a function from a path relative to the
+// collection root ('CURRENT', 'gen-1/manifest.sbm2',
+// 'gen-1/predicate-0.ibk3', ...) to the bytes of that file (a Uint8Array or
+// an ArrayBuffer, or a Promise of either). index.mjs builds one over the
+// file system; a browser page builds one over fetch().
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Read CURRENT, read a manifest by name, read the artifact files the
+// engine named, concatenate their bytes and say where each one starts.
+// It never parses a manifest, verifies a digest, decodes a block or
+// chooses an artifact: the ops storeManifestInspect, storeQueryPlan and
+// storeOpen (formal/lean4/Wasm/Ops/Store.lean, StoreHandles.lean) decide
+// all of that. bin/store.mjs is the same plumbing over store-host/ for the
+// `factoidal` command.
+
+import { requireChildName } from '../store-host/paths.mjs';
+
+/** The manifest file names a generation directory can carry, in the order
+ *  the native tools try them. */
+export const MANIFEST_NAMES = ['manifest.sbm2', 'manifest.sbm1'];
+
+async function readBytes(reader, path) {
+  const out = await reader(path);
+  if (out instanceof Uint8Array) return out;
+  if (out instanceof ArrayBuffer) return new Uint8Array(out);
+  if (ArrayBuffer.isView(out)) return new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
+  throw new TypeError(
+    `store reader: '${path}' answered ${out === null ? 'null' : typeof out}, ` +
+    'expected a Uint8Array or an ArrayBuffer');
+}
+
+/**
+ * The generation to open and its manifest bytes. With no `generation`,
+ * CURRENT names it (an activated collection); with one, that generation is
+ * opened directly, activated or not.
+ */
+export async function openGeneration(reader, generation) {
+  let name = generation;
+  if (name == null) {
+    let pointer;
+    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;
+    }
+    // CURRENT holds a UTF-8 generation name (docs/shardborough-storage-spec.md
+    // section 6.4); trailing ASCII whitespace is tolerated, as in
+    // store-host/index.mjs.
+    name = new TextDecoder('utf-8', { fatal: true }).decode(pointer).replace(/[\r\n\t ]+$/, '');
+    requireChildName(name, 'CURRENT');
+  } else {
+    requireChildName(String(name), 'generation');
+    name = String(name);
+  }
+  for (const manifestName of MANIFEST_NAMES) {
+    let manifest;
+    try {
+      manifest = await readBytes(reader, `${name}/${manifestName}`);
+    } catch (_err) {
+      continue;
+    }
+    return { generation: name, manifestName, manifest, activated: generation == null };
+  }
+  throw new Error(`openStore: generation '${name}' has none of ${MANIFEST_NAMES.join(', ')}`);
+}
+
+/** Read the named artifacts of one generation into one region, with a
+ *  {key, offset, len} window per artifact. */
+export async function readRegion(reader, generation, keys) {
+  const chunks = [];
+  for (const key of keys) chunks.push(await readBytes(reader, `${generation}/${key}`));
+  let total = 0;
+  for (const c of chunks) total += c.length;
+  const blob = new Uint8Array(total);
+  const artifacts = [];
+  let offset = 0;
+  for (let i = 0; i < chunks.length; i += 1) {
+    blob.set(chunks[i], offset);
+    artifacts.push({ key: keys[i], offset, len: chunks[i].length });
+    offset += chunks[i].length;
+  }
+  return { blob, artifacts, total };
+}
+
+/** The artifact keys a manifest declares, as storeManifestInspect lists
+ *  them: every block, every index sidecar, every out-of-line literal. */
+export function manifestKeys(inspectEnvelope) {
+  const keys = [];
+  for (const entry of inspectEnvelope.entries || []) {
+    keys.push(entry.key);
+    for (const key of Object.values(entry.sidecars || {})) keys.push(key);
+  }
+  for (const blob of inspectEnvelope.blobs || []) keys.push(blob.key);
+  return keys;
+}
+
+const HEX = (() => {
+  const t = new Array(256);
+  for (let b = 0; b < 256; b += 1) t[b] = b.toString(16).padStart(2, '0');
+  return t;
+})();
+
+/** Lowercase hexadecimal: the transport the manifest argument of the store
+ *  ops takes. Artifact bytes never take this path. */
+export function hexOfBytes(bytes) {
+  const parts = new Array(bytes.length);
+  for (let i = 0; i < bytes.length; i += 1) parts[i] = HEX[bytes[i]];
+  return parts.join('');
+}

package/lib/version.mjs

@@ -0,0 +1,5 @@
+// The package version, as a module the browser can import (a JSON import
+// 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';

package/lws/README.md

@@ -0,0 +1,97 @@
+# `@factoidal/core/lws` — a Node host for Linked Web Storage 1.0
+
+The W3C Linked Web Storage Protocol 1.0 core
+(<https://w3c.github.io/lws-protocol/lws10-core/>, Linked Web Storage
+Working Group editor's draft) served over Node's `http` module.
+
+Tracking issue: <https://github.com/danbri/factoidal/issues/659>.
+Design record:
+[`docs/designissues/2026-09-06-lws-and-solid-protocols.md`](../../../docs/designissues/2026-09-06-lws-and-solid-protocols.md).
+Conformance ledger:
+[`docs/lws-solid-conformance.md`](../../../docs/lws-solid-conformance.md).
+
+## What is here and what is not
+
+`server.mjs` is a socket, a body reader and a header writer. Every
+protocol decision — status codes, `Link` relations, `Last-Modified`,
+containment, the blank-node refusal in PATCH — is made by
+`formal/lean4/L4Factoidal/LWS/` and reaches this file only as a
+`{status, headers, body}` record. Iron rule 7 of `CLAUDE.md`: no
+protocol logic in a host.
+
+The one status code this file writes itself is `500`, and only when the
+host or the engine failed rather than answered.
+
+## The wasm contract
+
+| op | arguments | answer |
+| --- | --- | --- |
+| `lwsOpen` | `[configJson]` | `{ ok, handle, root }` |
+| `lwsStep` | `[handle, requestJson]` | `{ ok, response }` |
+| `lwsClose` | `[handle]` | `{ ok }` |
+
+```
+request  { method, target, headers: [[name, value]], body }
+response { status, headers: [[name, value]], body }
+```
+
+`headers` is a list of pairs, not an object: HTTP allows a field name to
+repeat and the order of repeated fields carries meaning. `target` is a
+path within the storage, so Node's `request.url` is passed through
+unchanged and this host composes no IRI.
+
+`configJson` members, all optional: `baseIri` (the absolute IRI the
+storage root maps to), `now` (the engine clock in seconds, which advances
+by one second per mutation so a write sequence has increasing
+`Last-Modified` values with no real clock), `owner`, `agent`. A request
+may carry `now` and `agent` of its own to override the handle's for one
+step; `listen({realClock: true})` is how a server with a real clock feeds
+one in, and a test leaves it off to keep the engine's deterministic
+clock. The full contract is `docs/lws-solid-conformance.md`, section
+"wasm ABI".
+
+A WebAssembly module built before these ops landed answers `unknown op`.
+`lwsOpsAvailable(engine)` reports that as `{available: false, reason}`,
+and every test in `tests/lws/` skips with the reason printed rather than
+passing on an engine that cannot answer.
+
+## Use
+
+```js
+import { listen } from '@factoidal/core/lws'
+
+const running = await listen({ port: 3000, baseIri: 'https://storage.example/' })
+console.log(running.origin)
+await running.close()
+```
+
+From the command:
+
+```
+factoidal lws-serve /var/lib/lws --port 3000
+```
+
+`--port 0` takes an ephemeral port and the command prints the one it got;
+`--base IRI` sets `baseIri`, which defaults to the bound origin. `DIR`
+names the storage directory, but the first slice keeps the resource tree
+in the engine handle, so nothing is read from it or written to it yet
+(design record, section 2).
+
+## Exports
+
+| name | what it is |
+| --- | --- |
+| `listen(options)` | start a server, resolve when it is listening |
+| `createLwsServer(options)` | build the server without listening |
+| `openLwsStorage(options)` | open a handle and get `step` / `close` |
+| `createLwsServer(...).setBaseIri(iri)` | set `baseIri` before the first request |
+| `lwsOpsAvailable(engine)` | probe the loaded module for the ops |
+| `LWS_OPS` | the three op names |
+| `LwsHostError` | a host failure, with `unknownOp` set when the op is absent |
+
+## Tests
+
+```
+node tests/lws/server.mjs
+deno run --allow-read --allow-net --allow-write --allow-env tests/lws/server.mjs
+```