@factoidal/core 0.7.1 → 0.11.0

package/l4-core.d.ts

@@ -1,159 +0,0 @@
-// TypeScript declarations for 'factoidal/l4-core' — the typed core
-// API served by the Lean 4 engine (L4Factoidal compiled to
-// WebAssembly) instead of the F* extraction. Assets resolve through
-// the 'factoidal/l4' ladder: @factoidal/lean, $FACTOIDAL_L4_ASSETS,
-// then the repository checkout.
-
-import {
-  DataFactory,
-  DataInput,
-  DataFormat,
-  Dataset,
-  ParseOptions,
-  QueryOptions,
-  SerializeOptions,
-  Bindings,
-  ShaclValidateResult,
-} from './index';
-
-export {
-  Dataset,
-  DataFactory,
-  DataInput,
-  DataFormat,
-  ParseOptions,
-  QueryOptions,
-  SerializeOptions,
-  Bindings,
-};
-
-export function parse(text: string, options?: ParseOptions): Promise<Dataset>;
-export function query(
-  data: DataInput,
-  sparql: string,
-  options?: QueryOptions
-): Promise<Bindings[] | boolean | Dataset>;
-export function update(data: DataInput, sparql: string): Promise<Dataset>;
-export function serialize(
-  data: DataInput,
-  options?: SerializeOptions
-): Promise<string>;
-export function canonicalize(data: DataInput): Promise<string>;
-export function graphs(data: DataInput): Promise<string[]>;
-export function canonicalHash(data: DataInput): Promise<string>;
-export function owlClosure(
-  data: DataInput,
-  options?: { regime?: 'RDFS' | 'OWL-RL' }
-): Promise<Dataset>;
-export function coreRdfsClosure(data: DataInput): Promise<Dataset>;
-export function coreRdfsCheck(data: DataInput): Promise<boolean>;
-export function rhoDfClosure(data: DataInput): Promise<Dataset>;
-export function rhoDfFragmentCheck(data: DataInput): Promise<boolean>;
-export function rdfsPlusClosure(data: DataInput): Promise<Dataset>;
-
-// Lean-only: formal/fstar has no CL/IKL parser, so `clParse` does not
-// exist on index.d.ts/wasm.d.ts. Reads Common Logic Interchange Format
-// text (ISO/IEC 24707:2018), with the IKL `that`-operator extension,
-// and reports its shape -- it never produces RDF. `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. A CLIF text that fails to parse rejects instead of
-// returning either value.
-export function clParse(clifText: string): Promise<{
-  ok: boolean;
-  sentences: number;
-  pureCL: boolean;
-  normalized: string;
-}>;
-
-// Lean-only, same reason as clParse. Reads CLIF text and writes it
-// back out in canonical spacing. `roundTripProved` is ALWAYS `false`:
-// `clif_roundTrip` (CL/ClifAdequacy.lean) is an OPEN lemma -- the
-// fragment boundary `marksLexable` is MEASURED, not proved. The field
-// is surfaced, not dropped or defaulted away, so a caller does not
-// have to go find that out.
-export function clSerialize(clifText: string): Promise<{
-  ok: boolean;
-  clif: string;
-  sentences: number;
-  roundTripProved: false;
-}>;
-
-// Lean-only, same reason as clParse. Alpha-normalises CLIF text: the
-// canonical representative of each sentence's bound-variable-renaming
-// equivalence class -- IKL GUIDE Appendix B condition (1), renaming a
-// bound variable does not change the proposition expressed. Two
-// sentences that differ only in bound-variable names produce
-// byte-identical `clif` output.
-export function clAlphaNorm(clifText: string): Promise<{
-  ok: boolean;
-  clif: string;
-  sentences: number;
-}>;
-
-// Lean-only, same reason as clParse. Hayes's reduction of IKL to
-// Common Logic (danbri/factoidal#625), over a whole text.
-//
-// `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 and returns output
-// either way; when `noIntrusion` is `false`, `tails_satisfiable` /
-// `normalize_preserves` do not cover that output.
-export function clNormalize(clifText: string): Promise<{
-  ok: boolean;
-  head: string[];
-  tail: string[];
-  clif: string;
-  sentences: number;
-  thatCount: number;
-  noIntrusion: boolean;
-  preserves: 'satisfiability';
-  provedUnder: string;
-}>;
-
-// clFiniteSat is DEFERRED from this typed surface (owner decision,
-// 2026-08-26), not excluded: it takes a caller-supplied finite-
-// interpretation JSON encoding that has no user yet. Reachable only
-// through the raw dispatch ABI (`l4.call('clFiniteSat', [interpJson,
-// clifText])`), which needs no typed shape commitment here.
-
-// Present on the surface, NOT implemented by the Lean engine: each
-// rejects with an engine-capability error so an engine swap fails
-// loudly rather than with `undefined is not a function`.
-// capabilities() reports the truth per feature.
-export function shaclValidate(
-  data: DataInput,
-  shapes: DataInput
-): Promise<ShaclValidateResult>;
-export function shexValidate(
-  data: DataInput,
-  schema: string,
-  shapeMap: string
-): Promise<unknown>;
-// Served by the Lean engine when the resolved wasm carries the ops
-// (dispatch ABI `owlIsConsistent` / `owlEntails`, formal/lean4 issue
-// 586); same three-valued envelopes as index.d.ts. An older bundle
-// rejects with an "unknown op" error.
-export function owlIsConsistent(
-  data: DataInput,
-  options?: { format?: string; fuel?: number | string }
-): Promise<{ consistent: boolean | null; reason?: string }>;
-export function owlEntails(
-  premise: DataInput,
-  conclusion: DataInput,
-  options?: { format?: string; fuel?: number | string }
-): Promise<{
-  entailed: boolean | null;
-  via: 'closure' | 'refutation';
-  reason?: string;
-}>;
-
-export function capabilities(): Promise<Record<string, boolean | string>>;
-export const dataFactory: DataFactory;
-export const engine: 'lean4-wasm';
-export function available(): boolean;
-export const version: string;

package/l4-core.js

@@ -1,188 +0,0 @@
-// 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

@@ -1,50 +0,0 @@
-// 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>> };
-}
-
-/** Result of the narrow canonical-block predicate scan. */
-export interface L4IBK2PredicateScan {
-  rows: number;
-  ntriples: string;
-}
-
-/** Result of a source-scoped current IBK3 predicate scan. */
-export interface L4IBK3PredicateScan extends L4IBK2PredicateScan {
-  format: 'IBK3';
-  blankNodeScope: string;
-}
-
-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>;
-export function scanIBK2Predicate(ibk2Hex: string, predicateIri: string): Promise<L4IBK2PredicateScan>;
-export function scanIBK3Predicate(ibk3Hex: string, predicateIri: string, blankNodeScope: string): Promise<L4IBK3PredicateScan>;

package/l4.js

@@ -1,104 +0,0 @@
-// 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 + narrow block scans). 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),
-  /**
-   * Validate a canonical IBK2 artifact and selectively scan one predicate.
-   * `ibk2Hex` is a diagnostic transport; high-throughput users should use a
-   * future bounded-buffer worker ABI rather than converting block bytes to hex.
-   */
-  scanIBK2Predicate: async (ibk2Hex, predicateIri) =>
-    (await loadL4()).call('scanIBK2Predicate', [ibk2Hex, predicateIri]),
-  /**
-   * Validate and scan one current IBK3 artifact. `blankNodeScope` identifies
-   * the RDF source/dataset import unit: reuse it across that unit's predicate
-   * blocks, and never reuse it for an unrelated input document.
-   */
-  scanIBK3Predicate: async (ibk3Hex, predicateIri, blankNodeScope) =>
-    (await loadL4()).call('scanIBK3Predicate', [ibk3Hex, predicateIri, blankNodeScope]),
-};