@factoidal/core 0.1.0 → 0.2.0

package/l4-core.js

@@ -0,0 +1,188 @@
+// factoidal — Node entry point for the **Lean 4** engine.
+//
+// The same typed public API shape as index.js / wasm.js (parse /
+// query / update / serialize / canonicalize / dataFactory / Dataset /
+// the closure and checker family), served by the Lean 4 extraction
+// compiled to WebAssembly (L4Factoidal — formal/lean4/) instead of
+// the F* extraction. Asset resolution is l4.js's three-step ladder:
+// @factoidal/lean, $FACTOIDAL_L4_ASSETS, then the repository checkout.
+//
+//   const factoidal = require('@factoidal/core/l4-core');
+//   const ds = await factoidal.parse('<a> <b> "c" .', { format: 'ntriples' });
+//
+// Surface: the subset capabilities() reports. Operations the Lean
+// engine does not implement (SHACL, ShEx, HDT, COTTAS, VC crypto,
+// entailment-regime query modes, tableauMaterialise /
+// tableauDlInconsistent, RML/CSVW/JSON-LD/RIF) reject with a clear
+// engine-capability error rather than silently falling back to the F*
+// engine — the point of this entry is that everything it answers came
+// through the Lean extraction. See ./select.js (factoidal/select) for
+// an explicit, observable lean/fstar/lean1st/fstar1st/slowcompareboth
+// switch built on top of this and ./index.js (issue #618); this module
+// itself never falls back. owlIsConsistent / owlEntails ARE served
+// (the three-valued OWL DL verdict, formal/lean4 issue 586) when the
+// resolved wasm carries the ops — an older bundle answers "unknown op",
+// which surfaces as the entryResult error, so probe the `ops`
+// reflection before relying on them. The export list mirrors wasm.js
+// so callers can swap engines by import path alone.
+
+'use strict';
+
+const { buildApi } = require('./lib/api.js');
+const rdfjs = require('./rdfjs.js');
+const l4 = require('./l4.js');
+const pkg = require('./package.json');
+
+const NOT_SUPPORTED =
+  'factoidal/l4-core: this operation is not implemented by the Lean 4 ' +
+  'engine (see capabilities()); use the F* engine entry points for it. ' +
+  'If the Lean assets are missing, npm install @factoidal/lean or set ' +
+  'FACTOIDAL_L4_ASSETS.';
+
+// The entry-ABI method names lib/api.js dispatches on, mapped onto the
+// Lean wasm module's single dispatch export. Methods absent from this
+// list are deliberately absent from the entry object: api.js
+// typeof-guards each one and capabilities() reports the truth.
+//
+// The resolved wasm's full dispatch surface has 21 ops
+// (`bin/linux-x86_64/l4factoidal ops`); this list wires 16 of them.
+// `clParse` reads CLIF text into a CL syntax tree and reports its
+// shape (sentence count, CL-vs-IKL dialect, canonical re-serialisation)
+// -- it never produces RDF, so it is NOT part of the IKL-to-RDF
+// projection family below. `clSerialize`, `clAlphaNorm` and
+// `clNormalize` join it as the same kind of entry (CLIF text in, CLIF/
+// CL text out, never RDF) -- see lib/api.js's doc comments on each for
+// what their answers are worth (clSerialize's `roundTripProved: false`,
+// clNormalize's `preserves`/`noIntrusion`). All four are Lean-only
+// entries in the typed capability table (formal/fstar has no CL/IKL
+// parser at all); see ./select.js, which throws on `backend:'fstar'`
+// for each rather than answering from Lean silently.
+//
+// `clFiniteSat` (the fifth CL/IKL op) is DEFERRED from this typed
+// layer, not excluded (owner decision, 2026-08-26): it takes a
+// caller-supplied finite-interpretation JSON encoding that has no user
+// yet, and a typed wrapper would freeze that shape before we know
+// whether it is right. It stays reachable only through the raw
+// dispatch ABI (`l4.call('clFiniteSat', [interpJson, clifText])`) --
+// see lib/api.js's comment next to the other three clNormalize/
+// clAlphaNorm/clSerialize wrappers for the same note.
+//
+// The IKL-to-RDF projection ("direction B": `clToDataset`,
+// `queryWithIklService`) was removed from the engine source on
+// 2026-08-26 (https://github.com/danbri/factoidal/issues/626): both
+// ops went through the deleted `CL/ToRdf.lean`, whose content-addressed
+// proposition graph names were never asked for. They had already been held off this JS surface by owner
+// decision (https://github.com/danbri/factoidal/issues/618 — "I don't
+// want npm code for direction b at this stage ... Take it out of npm
+// for now."), and there is now nothing to wire. The compiled wasm
+// artifact still CONTAINS both ops until it is rebuilt
+// (https://github.com/danbri/factoidal/issues/627) — it is ahead of
+// its source. The same #618 ruling is why an x-ikl-<suffix>
+// entailment-regime family is rejected in lib/api.js's query() and
+// fn.js's entail().
+//
+// CORRECTION 2026-08-26: an earlier version of this comment listed
+// `clParse` alongside those two and cited #618 as the reason for all
+// three. That misattributed a decision the owner did not make --
+// `clParse` was unwired only because nobody had decided to wrap it,
+// which is why it is wired above instead of here.
+//
+// A second group is withheld for an unrelated, non-owner reason:
+//
+//   - dataset handles (`datasetOpen`/`datasetQuery`/`datasetUpdate`/
+//     `datasetSerialize`/`datasetClose`): ordinary RDF dataset handles,
+//     not part of the CL/IKL decision above. Held back only because
+//     lib/api.js has no typed wrapper shape for a stateful handle yet
+//     (every existing typed op is request/response) — a scope
+//     judgement, not an owner ruling. Wiring these in is a reasonable
+//     follow-up.
+const OPS = [
+  'parseToDatasetJson',
+  'queryDataset',
+  'updateDataset',
+  'serializeNQuads',
+  'serializeTurtle',
+  'canonicalizeToNQuads',
+  'owlClosure',
+  'owlIsConsistent',
+  'owlEntails',
+  'rhoDfClosure',
+  'rhoDfFragmentCheck',
+  'rdfsPlusClosure',
+  'clParse',
+  'clSerialize',
+  'clAlphaNorm',
+  'clNormalize',
+];
+
+async function loadLeanEntry() {
+  const eng = await l4.loadL4();
+  if (typeof eng.call !== 'function') {
+    throw new Error(
+      'factoidal/l4-core: the resolved Lean wasm module predates the ' +
+      'dispatch ABI (no call export); update @factoidal/lean or ' +
+      'FACTOIDAL_L4_ASSETS to a build with l4_call'
+    );
+  }
+  const entry = { abiVersion: '1' };
+  for (const op of OPS) {
+    // lib/api.js's entryResult() takes the envelope as a JSON STRING
+    // (entry_jsoo.ml's wire shape). The Lean loader's call() parses the
+    // envelope and throws on {"ok":false}; re-encode both outcomes so
+    // this entry object is wire-compatible with the F* one.
+    entry[op] = (...args) => {
+      try {
+        return JSON.stringify(eng.call(op, args.map(String)));
+      } catch (err) {
+        return JSON.stringify({
+          ok: false,
+          error: String((err && err.message) || err),
+        });
+      }
+    };
+  }
+  return entry;
+}
+
+const api = buildApi({
+  engineName: 'l4',
+  loadEntry: loadLeanEntry,
+  runCli: async () => ({ exitCode: 1, stdout: '', stderr: NOT_SUPPORTED }),
+});
+
+module.exports = {
+  parse: api.parse,
+  query: api.query,
+  update: api.update,
+  serialize: api.serialize,
+  canonicalize: api.canonicalize,
+  graphs: api.graphs,
+  canonicalHash: api.canonicalHash,
+  owlClosure: api.owlClosure,
+  coreRdfsClosure: api.coreRdfsClosure,
+  coreRdfsCheck: api.coreRdfsCheck,
+  rhoDfClosure: api.rhoDfClosure,
+  rhoDfFragmentCheck: api.rhoDfFragmentCheck,
+  rdfsPlusClosure: api.rdfsPlusClosure,
+  // Lean-only: formal/fstar has no CL/IKL parser, so these are NOT
+  // exported from index.js/wasm.js. See the OPS comment above.
+  clParse: api.clParse,
+  clSerialize: api.clSerialize,
+  clAlphaNorm: api.clAlphaNorm,
+  clNormalize: api.clNormalize,
+  // Served by the Lean engine's dispatch ABI when the resolved wasm
+  // carries the ops (see the header note).
+  owlIsConsistent: api.owlIsConsistent,
+  owlEntails: api.owlEntails,
+  // Not implemented by this engine — kept on the surface so a caller
+  // swapping engines gets the pinned capability error, not
+  // `undefined is not a function`.
+  shaclValidate: api.shaclValidate,
+  shexValidate: api.shexValidate,
+  capabilities: api.capabilities,
+  Dataset: rdfjs.Dataset,
+  dataFactory: rdfjs.dataFactory,
+  engine: 'lean4-wasm',
+  available: l4.available,
+  version: pkg.version,
+};

package/l4.d.ts

@@ -0,0 +1,36 @@
+// TypeScript declarations for factoidal/l4 — the Lean 4 (L4Factoidal)
+// engine compiled to WebAssembly, bundled in this package's l4-assets/
+// since issue #618. See l4.js for the asset-resolution ladder and
+// docs/designissues/2026-08-22-npm-l4-module-packaging.md for why the
+// wasm was split out originally and why that no longer applies.
+
+/** A term in SPARQL Query Results JSON shape, plus `var` for patterns. */
+export interface L4Term {
+  type: 'uri' | 'literal' | 'bnode' | 'var';
+  value: string;
+  datatype?: string;
+  'xml:lang'?: string;
+}
+
+export interface L4Triple {
+  subject: L4Term;
+  predicate: L4Term;
+  object: L4Term;
+}
+
+/** SPARQL 1.1 Query Results JSON document. */
+export interface L4ResultsDoc {
+  head: { vars: string[] };
+  results: { bindings: Array<Record<string, L4Term>> };
+}
+
+export interface L4Engine {
+  version(): string;
+  bgpQuery(triples: L4Triple[], bgp: L4Triple[]): Promise<L4ResultsDoc> | L4ResultsDoc;
+}
+
+export const engine: 'lean4-wasm';
+export function available(): boolean;
+export function loadL4(): Promise<L4Engine>;
+export function version(): Promise<string>;
+export function bgpQuery(triples: L4Triple[], bgp: L4Triple[]): Promise<L4ResultsDoc>;

package/l4.js

@@ -0,0 +1,90 @@
+// factoidal/l4 — the Lean 4 engine (L4Factoidal compiled to wasm32)
+// behind the same package namespace as the F*-extracted engines.
+//
+//   const l4 = require('factoidal/l4');        // or import('factoidal/l4')
+//   await l4.version();                        // "L4Factoidal ..."
+//   await l4.bgpQuery(triples, bgp);           // SPARQL results JSON
+//
+// BUNDLED since issue #618: `@factoidal/core` now ships the Lean wasm
+// directly under `l4-assets/` (l4factoidal.{js,mjs,wasm} + version.json
+// — l4-assets/version.json, not this package's own version.json, which
+// stays the F* engine's), so one `npm install @factoidal/core` gets
+// both engines. The +23%-tarball objection that shaped the earlier
+// companion-package split
+// (docs/designissues/2026-08-22-npm-l4-module-packaging.md) no longer
+// applies once measured against the real 21-op dispatch surface — see
+// that doc's "issue #618: option A after all" section for the full
+// argument. This module is now a resolver over FOUR sources, first hit
+// wins:
+//
+//   1. this package's own l4-assets/ (the normal case, since #618);
+//   2. the companion package `@factoidal/lean` (never published — kept
+//      only as a manual-override path for anyone pinning an older
+//      Lean build against a newer core; see npm/factoidal-lean/README.md);
+//   3. $FACTOIDAL_L4_ASSETS — a directory holding
+//      l4factoidal.{js,mjs,wasm} (custom deployments);
+//   4. the repository checkout layout (docs/web/hub/assets/l4/) —
+//      what the hub tests and in-repo development use.
+//
+// Every source's three files must stay together and keep their names:
+// the Emscripten glue resolves the .wasm sidecar from its own basename
+// (see skills/lean4-wasm-export, "the naming trap").
+//
+// API surface mirrors docs/web/hub/assets/l4/l4factoidal.js (phase-1
+// ABI: version + bgpQuery). New exports appear here when they are
+// added to formal/lean4/Wasm/Exports.lean and the wasm is rebuilt.
+
+'use strict';
+
+const { existsSync } = require('node:fs');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+function resolveLoader() {
+  const inPkg = path.join(__dirname, 'l4-assets', 'l4factoidal.js');
+  if (existsSync(inPkg)) return inPkg;
+  try {
+    return require.resolve('@factoidal/lean/l4factoidal.js');
+  } catch { /* not installed */ }
+  const env = process.env.FACTOIDAL_L4_ASSETS;
+  if (env && existsSync(path.join(env, 'l4factoidal.js'))) {
+    return path.join(env, 'l4factoidal.js');
+  }
+  const repo = path.join(__dirname, '..', '..', 'docs', 'web', 'hub', 'assets', 'l4', 'l4factoidal.js');
+  if (existsSync(repo)) return repo;
+  return null;
+}
+
+let l4Promise = null;
+
+async function loadL4() {
+  if (l4Promise) return l4Promise;
+  const loaderPath = resolveLoader();
+  if (!loaderPath) {
+    throw new Error(
+      'factoidal/l4: Lean engine assets not found. They normally ship in ' +
+      "this package's own l4-assets/ directory — if it is missing, this " +
+      'checkout/install is incomplete. Otherwise set FACTOIDAL_L4_ASSETS ' +
+      'to a directory containing l4factoidal.js, l4factoidal.mjs and ' +
+      'l4factoidal.wasm, or install the (unpublished, override-only) ' +
+      'companion package @factoidal/lean.');
+  }
+  l4Promise = import(pathToFileURL(loaderPath).href).then((m) => m.loadL4());
+  return l4Promise;
+}
+
+module.exports = {
+  engine: 'lean4-wasm',
+  /** True when the wasm assets are resolvable without loading them. */
+  available: () => resolveLoader() !== null,
+  /** Load (once) and return the low-level engine handle. */
+  loadL4,
+  /** Engine identification string from the Lean side. */
+  version: async () => (await loadL4()).version(),
+  /**
+   * Evaluate a basic graph pattern over an in-memory triple list.
+   * Arguments and result use SPARQL Query Results JSON term shapes;
+   * see docs/web/hub/36-lean-in-the-browser.md for worked examples.
+   */
+  bgpQuery: async (triples, bgp) => (await loadL4()).bgpQuery(triples, bgp),
+};

package/lib/api.js

@@ -490,6 +490,31 @@ function buildApi(driver) {
     }
     const opts = options || {};
     const entail = opts.entail || 'none';
+    // x-ikl-* is NOT IMPLEMENTED. It is not withheld by policy.
+    //
+    // CORRECTION 2026-08-26: this comment previously cited the owner's
+    // direction-B ruling (danbri/factoidal#618) as the reason. That
+    // ruling was about the IKL-to-RDF projection, not this regime
+    // family, and citing it here misstated a decision the owner did
+    // not make. The family is the OWNER'S design
+    // (danbri/factoidal#581); its Lean dispatch was deleted on
+    // 2026-08-26 as collateral of the projection purge
+    // (danbri/factoidal#626), not as its target. The semantics
+    // survived -- Unified/ClBridge.lean's asserted_merge_sound is the
+    // regime's soundness statement -- so restoring it is a dispatch
+    // branch, not a redesign. Checked explicitly (not just left out of
+    // ENTAIL_VALUES below) so a future ENTAIL_VALUES edit can't
+    // reopen this without deliberately removing this check too; see
+    // test/select.test.js's regression test.
+    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(', ')}`);
@@ -651,8 +676,13 @@ function buildApi(driver) {
 
     if (outFormat === 'nquads') {
       const e = await entry();
-      if (e && docs.every((d) => d.ext === 'nq')) {
-        const nq = docs.map((d) => d.content).join('');
+      if (e) {
+        // Non-N-Quads documents normalize through parseToDatasetJson
+        // (docsToEntryNQuads), same as the turtle branch above — so
+        // entry-only drivers (e.g. l4-core.js) serve this path too.
+        const nq = docs.every((d) => d.ext === 'nq')
+          ? docs.map((d) => d.content).join('')
+          : docsToEntryNQuads(e, docs, 'serialize(nquads)');
         return entryResult(e.serializeNQuads(nq), 'serialize').nquads;
       }
     }
@@ -1254,6 +1284,132 @@ function buildApi(driver) {
     return entryResult(e.xpathEval(xmlText, xpathExpr), 'xpathEval');
   }
 
+  /**
+   * Parse Common Logic Interchange Format text (ISO/IEC 24707:2018),
+   * with the IKL `that`-operator extension (entry_jsoo.ml's clParse
+   * export -> L4Factoidal's CL/Clif.lean reader). Reads CLIF into a CL
+   * syntax tree and reports its shape; it never produces RDF -- the
+   * IKL-to-RDF projection that used to accompany it is deleted
+   * (danbri/factoidal#626). Lean 4 only: formal/fstar has no CL/IKL parser, so this
+   * function is absent from index.js/wasm.js -- see capabilities() /
+   * factoidal/select's capability table.
+   * @param {string} clifText
+   * @returns {Promise<{ok: boolean, sentences: number, pureCL: boolean,
+   *   normalized: string}>} `pureCL` is a DIALECT flag, not a validity
+   *   or quality signal: true while the text stays inside ISO/IEC
+   *   24707 Common Logic, false once it uses IKL's `that` operator.
+   *   Both values are returned only for text that parsed; a CLIF text
+   *   that fails to parse rejects instead (e.g. a bare `(that S)` used
+   *   as a proposition rather than a term -- see the GUIDE).
+   */
+  async function clParse(clifText) {
+    if (typeof clifText !== 'string') {
+      throw new TypeError('clParse: clifText must be a string');
+    }
+    const e = await entry();
+    if (!e) throw pendingError('clParse');
+    requireEntryFn(e, 'clParse', 'Common Logic / IKL parse');
+    return entryResult(e.clParse(clifText), 'clParse');
+  }
+
+  /**
+   * Read Common Logic Interchange Format text and write it back out in
+   * the canonical spacing of the CLIF writer (entry_jsoo.ml's
+   * clSerialize export -> L4Factoidal's CL/Clif.lean reader/writer
+   * pair). Lean 4 only: formal/fstar has no CL/IKL parser, so this
+   * function is absent from index.js/wasm.js -- see capabilities() /
+   * factoidal/select's capability table.
+   *
+   * `roundTripProved` is always `false`. The round-trip lemma
+   * `clif_roundTrip` (`CL/ClifAdequacy.lean`) is an OPEN lemma: the
+   * fragment boundary `marksLexable` is MEASURED, not proved. The
+   * field is in the envelope, unmodified, so a caller does not have to
+   * go and find that out.
+   * @param {string} clifText
+   * @returns {Promise<{ok: boolean, clif: string, sentences: number,
+   *   roundTripProved: false}>}
+   */
+  async function clSerialize(clifText) {
+    if (typeof clifText !== 'string') {
+      throw new TypeError('clSerialize: clifText must be a string');
+    }
+    const e = await entry();
+    if (!e) throw pendingError('clSerialize');
+    requireEntryFn(e, 'clSerialize', 'Common Logic / IKL serialize');
+    return entryResult(e.clSerialize(clifText), 'clSerialize');
+  }
+
+  /**
+   * Alpha-normalise Common Logic Interchange Format text: the canonical
+   * representative of each sentence's bound-variable-renaming
+   * equivalence class (entry_jsoo.ml's clAlphaNorm export ->
+   * L4Factoidal's `CL/Alpha.lean`, `Sentence.alphaNorm`). Bound names
+   * become `v1`, `v2`, ... in traversal order, so two sentences that
+   * differ only in bound-variable names produce byte-identical output
+   * -- IKL GUIDE Appendix B condition (1): renaming a bound variable
+   * does not change the proposition expressed. Lean 4 only: formal/fstar
+   * has no CL/IKL parser, so this function is absent from
+   * index.js/wasm.js -- see capabilities() / factoidal/select's
+   * capability table.
+   * @param {string} clifText
+   * @returns {Promise<{ok: boolean, clif: string, sentences: number}>}
+   */
+  async function clAlphaNorm(clifText) {
+    if (typeof clifText !== 'string') {
+      throw new TypeError('clAlphaNorm: clifText must be a string');
+    }
+    const e = await entry();
+    if (!e) throw pendingError('clAlphaNorm');
+    requireEntryFn(e, 'clAlphaNorm', 'Common Logic / IKL alpha-normalise');
+    return entryResult(e.clAlphaNorm(clifText), 'clAlphaNorm');
+  }
+
+  /**
+   * Hayes's satisfiability-preserving reduction of IKL to Common Logic
+   * (entry_jsoo.ml's clNormalize export -> L4Factoidal's
+   * `CL/Normalize.lean`, `normalizeText`; danbri/factoidal#625), over a
+   * whole text: one head text and one shared tail, with the
+   * proposition-name counter running across the text. Lean 4 only:
+   * formal/fstar has no CL/IKL parser, so this function is absent from
+   * index.js/wasm.js -- see capabilities() / factoidal/select's
+   * capability table.
+   *
+   * Two limits, both real, both in the answer, neither hidden:
+   *  - `preserves: "satisfiability"` -- the reduction preserves
+   *    satisfiability, NOT equivalence. It suits entailment and
+   *    consistency testing; it is not a transformation to apply to
+   *    data you intend to keep.
+   *  - `noIntrusion` IS the proof hypothesis `CL.noIntrSs [] []`
+   *    decides, not a paraphrase of it. The transformation runs either
+   *    way; when `noIntrusion` is `false`, the output is still
+   *    produced, but `tails_satisfiable` / `normalize_preserves` do
+   *    not cover that case.
+   * @param {string} clifText
+   * @returns {Promise<{ok: boolean, head: string[], tail: string[],
+   *   clif: string, sentences: number, thatCount: number,
+   *   noIntrusion: boolean, preserves: 'satisfiability',
+   *   provedUnder: string}>}
+   */
+  async function clNormalize(clifText) {
+    if (typeof clifText !== 'string') {
+      throw new TypeError('clNormalize: clifText must be a string');
+    }
+    const e = await entry();
+    if (!e) throw pendingError('clNormalize');
+    requireEntryFn(e, 'clNormalize', 'Common Logic / IKL normalize');
+    return entryResult(e.clNormalize(clifText), 'clNormalize');
+  }
+
+  // clFiniteSat (entry_jsoo.ml's clFiniteSat -> L4Factoidal's
+  // CL/FiniteSatTheorems.lean) is DEFERRED, not excluded, from this
+  // typed layer (owner decision, 2026-08-26): it takes a caller-supplied
+  // finite-interpretation JSON encoding (see Wasm/Ops/CL.lean's header
+  // for the wire format) that has no user yet, and a typed wrapper here
+  // would freeze that shape before anyone knows whether it is right. It
+  // stays reachable through the raw dispatch ABI (`l4.call('clFiniteSat',
+  // [interpJson, clifText])` / factoidal/select's `call('clFiniteSat',
+  // ...)`), which needs no shape commitment on this layer.
+
   // -----------------------------------------------------------------
   // VC Data Integrity crypto (eddsa-rdfc-2022) — HACL* wasm backend.
   // entry_jsoo.ml's vc* exports realise VC_DataIntegrity's four crypto
@@ -2100,6 +2256,10 @@ function buildApi(driver) {
     didKeyResolve,
     xmlWellformed,
     xpathEval,
+    clParse,
+    clSerialize,
+    clAlphaNorm,
+    clNormalize,
     rifEval,
     xsltTransform,
     mathmlEval,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@factoidal/core",
-  "version": "0.1.0",
-  "description": "Formally verified RDF/SPARQL engine, extracted from F* specifications, for Node and the browser (JS + Wasm). Parser and algebra spec verified in F*; on-disk backend has unverified OCaml-side optimization layers being migrated back to F*.",
+  "version": "0.2.0",
+  "description": "Factoidal: a linked information system with graph data and the Web at its heart - RDF parsing, SPARQL 1.1 query, canonicalization and entailment for Node and the browser (JS + Wasm), grounded in F* and Lean 4. Parser and algebra spec verified in F*; on-disk backend has unverified OCaml-side optimization layers being migrated back to F*.",
   "keywords": [
     "sparql",
     "rdf",
@@ -57,7 +57,20 @@
     "./factoidal.js": "./factoidal.js",
     "./factoidal.wasm.js": "./factoidal.wasm.js",
     "./factoidal.wasm.assets/*": "./factoidal.wasm.assets/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./l4": {
+      "types": "./l4.d.ts",
+      "default": "./l4.js"
+    },
+    "./l4-core": {
+      "types": "./l4-core.d.ts",
+      "default": "./l4-core.js"
+    },
+    "./l4-assets/*": "./l4-assets/*",
+    "./select": {
+      "types": "./select.d.ts",
+      "default": "./select.js"
+    }
   },
   "files": [
     "index.js",
@@ -68,6 +81,13 @@
     "rdfjs.js",
     "fn.js",
     "fn.d.ts",
+    "l4.js",
+    "l4.d.ts",
+    "l4-core.js",
+    "l4-core.d.ts",
+    "l4-assets/",
+    "select.js",
+    "select.d.ts",
     "lib/",
     "browser.js",
     "browser.d.ts",

package/select.d.ts

@@ -0,0 +1,116 @@
+// TypeScript declarations for factoidal/select — the backend selector
+// (issue #618): one typed surface over both the F* engine (./index.js)
+// and the Lean 4 engine (./l4-core.js), with an explicit, observable
+// lean/fstar/lean1st/fstar1st/slowcompareboth switch. See select.js for
+// the full design rationale and the sub-question decisions.
+
+export type Backend = 'lean' | 'fstar' | 'lean1st' | 'fstar1st' | 'slowcompareboth';
+
+export const BACKENDS: readonly Backend[];
+
+/** Function names the selector can route (see select.js's ALWAYS_IF_ENTRY/CAP_FLAG). */
+export const ROUTABLE: readonly string[];
+
+export interface CallOptions {
+  /** Per-call override of the selector instance's default backend. */
+  backend?: Backend;
+  /** lean1st/fstar1st only: function names routed to the OTHER engine
+   * regardless of what the primary engine implements. */
+  overrideFns?: string[];
+}
+
+export interface SingleEngineResult<T> {
+  engine: 'lean' | 'fstar';
+  backend: Backend;
+  value: T;
+}
+
+export interface CompareBothResult<T> {
+  engine: 'both';
+  backend: 'slowcompareboth';
+  /** false is a reportable finding, not a thrown error. */
+  agree: boolean;
+  comparison: { method: string };
+  lean: T;
+  fstar: T;
+}
+
+export type SelectResult<T> = SingleEngineResult<T> | CompareBothResult<T>;
+
+/** { lean: boolean, fstar: boolean } per routable function name, derived live. */
+export type CapabilityTable = Record<string, { lean: boolean; fstar: boolean }>;
+
+export function capabilityTable(): Promise<CapabilityTable>;
+export function engineSupports(engineApi: unknown, fnName: string): Promise<boolean>;
+export function compareValues(
+  fnName: string, leanValue: unknown, fstarValue: unknown
+): Promise<{ equal: boolean; method: string }>;
+
+export interface SelectorOptions {
+  backend?: Backend;
+  overrideFns?: string[];
+}
+
+export interface Selector {
+  readonly backend: Backend;
+  readonly overrideFns: string[];
+  call(fnName: string, args: unknown[], callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  capabilityTable(): Promise<CapabilityTable>;
+  parse(text: string, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  query(data: unknown, sparql: string, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  update(data: unknown, updateText: string, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  serialize(data: unknown, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<string>>;
+  canonicalize(data: unknown, callOptions?: CallOptions): Promise<SelectResult<string>>;
+  canonicalHash(data: unknown, callOptions?: CallOptions): Promise<SelectResult<string>>;
+  graphs(data: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  owlClosure(data: unknown, mode: string, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  owlIsConsistent(data: unknown, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  owlEntails(premise: unknown, conclusion: unknown, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  coreRdfsClosure(data: unknown, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  coreRdfsCheck(data: unknown, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  rhoDfClosure(data: unknown, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  rhoDfFragmentCheck(data: unknown, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  rdfsPlusClosure(data: unknown, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  shaclValidate(data: unknown, shapes: unknown, options?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  shexValidate(data: unknown, schema: string, focus: unknown, shape?: unknown, callOptions?: CallOptions): Promise<SelectResult<unknown>>;
+  /** Lean-only: `backend:'fstar'` throws (formal/fstar has no CL/IKL parser). */
+  clParse(clifText: string, callOptions?: CallOptions): Promise<SelectResult<{
+    ok: boolean;
+    sentences: number;
+    pureCL: boolean;
+    normalized: string;
+  }>>;
+  /** Lean-only, same reason as clParse. `roundTripProved` is always
+   * `false` -- `clif_roundTrip` is an OPEN lemma; see l4-core.d.ts. */
+  clSerialize(clifText: string, callOptions?: CallOptions): Promise<SelectResult<{
+    ok: boolean;
+    clif: string;
+    sentences: number;
+    roundTripProved: false;
+  }>>;
+  /** Lean-only, same reason as clParse. Bound-variable-renaming
+   * canonical form (IKL GUIDE Appendix B condition (1)). */
+  clAlphaNorm(clifText: string, callOptions?: CallOptions): Promise<SelectResult<{
+    ok: boolean;
+    clif: string;
+    sentences: number;
+  }>>;
+  /** Lean-only, same reason as clParse. Preserves SATISFIABILITY, not
+   * equivalence; `noIntrusion` is the proof hypothesis itself, not a
+   * paraphrase -- see l4-core.d.ts. */
+  clNormalize(clifText: string, callOptions?: CallOptions): Promise<SelectResult<{
+    ok: boolean;
+    head: string[];
+    tail: string[];
+    clif: string;
+    sentences: number;
+    thatCount: number;
+    noIntrusion: boolean;
+    preserves: 'satisfiability';
+    provedUnder: string;
+  }>>;
+  // clFiniteSat has no named sugar here (owner decision, 2026-08-26):
+  // use call('clFiniteSat', [interpJson, clifText], callOptions).
+}
+
+export function createSelector(options?: SelectorOptions): Selector;