@factoidal/core 0.12.0 → 0.14.0

package/lib/nodes.mjs

@@ -0,0 +1,215 @@
+// The node-composition API (https://github.com/danbri/factoidal/issues/1002,
+// step 2): registered Lean stages as nodes, each carrying its contract name
+// and its proof status, with evidence flowing on the wires.
+//
+// The stage list is the engine's (op stageList, formal/lean4/Wasm/Ops/
+// StageList.lean), read from the Lean registry
+// L4Factoidal.Dataflow.registry: name, interface type, wire types, status,
+// contract, named assumptions, and whether the stage may run at all
+// (`runnable`, false for status `missing`). This file holds no copy of it.
+//
+// What this file adds is the binding of a stage NAME to the package
+// function that runs it (RUNNERS below; each is the function that
+// foundation/entrypoints.toml maps to that stage), and the wiring: a value
+// on a wire is `{ graph, evidence }`, and each node appends one evidence
+// record `{ stage, status, contract, assumptions, checked, artefact }` (plus
+// `unchecked` and `reason` for a step run under run()'s `unchecked` opt-in;
+// the record logic is in evidence.mjs). The result of
+// a run also reports the union of the named assumptions of the nodes it
+// passed: the premise list of the pipeline's soundness statement
+// (Dataflow/EndToEnd.lean) as the user sees it.
+//
+// ES module, no Node built-ins: the browser loads this file as it is.
+
+import { FactoidalError } from './errors.mjs';
+import { refusalFor, makeRecord, summarize, unionAssumptions } from './evidence.mjs';
+
+/**
+ * @param {object} deps the package functions and the engine entry
+ * @returns {{stages: Function, node: Function, pipe: Function, run: Function}}
+ */
+export function buildNodes(deps) {
+  const { entry, entryResult, requireEntryFn, Dataset,
+    parse, closure, shaclValidate, query, serialize, canonicalize, explain } = deps;
+
+  const reader = (format) => async (wire, params) => {
+    if (typeof wire.graph !== 'string') {
+      throw new TypeError(`node: a reader takes text on its wire (got ${typeof wire.graph})`);
+    }
+    const ds = await parse(wire.graph, { format, ...params });
+    return { graph: ds, artefact: { format } };
+  };
+  const reasoner = (regime) => async (wire, params) => ({
+    graph: await closure(wire.graph, regime, params),
+    artefact: { regime },
+  });
+  const writer = (format) => async (wire, params) => ({
+    artefact: { format, text: await serialize(wire.graph, { ...params, format }) },
+  });
+
+  // Stage name (stageList `name`) -> the package function that runs it.
+  // A runner answers `{ graph?, artefact }`; no `graph` passes the input
+  // graph on unchanged.
+  const RUNNERS = {
+    ntriplesDocumentReader: reader('ntriples'),
+    nquadsDocumentReader: reader('nquads'),
+    turtleDocumentReader: reader('turtle'),
+    trigDocumentReader: reader('trig'),
+    rdfxmlDocumentReader: reader('rdfxml'),
+    jsonldDocumentReader: reader('jsonld'),
+    rdfsReasoner: reasoner('rdfs'),
+    owlRlReasoner: reasoner('owl-rl'),
+    rhoDfReasoner: reasoner('rho-df'),
+    shaclValidator: async (wire, params) => {
+      const { shapes, ...opts } = params;
+      if (shapes === undefined) throw new TypeError('node shaclValidator: params.shapes is required');
+      const r = await shaclValidate(wire.graph, shapes, opts);
+      return { artefact: { conforms: r.conforms, report: r.report } };
+    },
+    shippedEvaluator: async (wire, params) => {
+      const { query: sparql, ...opts } = params;
+      if (typeof sparql !== 'string') throw new TypeError('node shippedEvaluator: params.query must be a string');
+      const answer = await query(wire.graph, sparql, opts);
+      return answer instanceof Dataset ? { graph: answer, artefact: { form: 'graph' } }
+        : { artefact: { answer } };
+    },
+    ntriplesDocumentWriter: writer('ntriples'),
+    nquadsDocumentWriter: writer('nquads'),
+    turtleDocumentWriter: writer('turtle'),
+    trigDocumentWriter: writer('trig'),
+    rdfxmlDocumentWriter: writer('rdfxml'),
+    rdfcStage: async (wire, params) => ({
+      artefact: { canonical: await canonicalize(wire.graph, params) },
+    }),
+    rdfsExplainGraphStage: async (wire, params) => {
+      const { description, ...opts } = params;
+      if (description === undefined) {
+        throw new TypeError('node rdfsExplainGraphStage: params.description is required');
+      }
+      return { artefact: await explain(wire.graph, description, { ...opts, profile: 'rdfs' }) };
+    },
+  };
+
+  let stageCache = null;
+
+  /**
+   * The engine's stage list (op stageList), one element per registry entry.
+   * @returns {Promise<object[]>}
+   */
+  async function stages() {
+    if (!stageCache) {
+      stageCache = (async () => {
+        const e = await entry();
+        requireEntryFn(e, 'stageList', 'stages');
+        const r = entryResult(e.stageList(), 'stages');
+        return Object.freeze(r.stages.map((s) => Object.freeze({
+          ...s,
+          theorems: Object.freeze([...s.theorems]),
+          assumptions: Object.freeze([...s.assumptions]),
+          tests: Object.freeze([...s.tests]),
+          bound: Object.prototype.hasOwnProperty.call(RUNNERS, s.name),
+        })));
+      })();
+      stageCache.catch(() => { stageCache = null; });
+    }
+    return stageCache;
+  }
+
+  const NODE = Symbol('factoidal.node');
+
+  /**
+   * A node for the registered stage `name`, with its parameters (the
+   * second argument of the package function it calls, e.g. `{shapes}`,
+   * `{query}`, `{description}`, reader options).
+   * @param {string} name a stageList `name`
+   * @param {object} [params]
+   * @returns {Promise<object>}
+   */
+  async function node(name, params) {
+    if (typeof name !== 'string') throw new TypeError('node: name must be a string');
+    if (params !== undefined && (params === null || typeof params !== 'object')) {
+      throw new TypeError('node: params must be an object');
+    }
+    const info = (await stages()).find((s) => s.name === name);
+    if (!info) {
+      throw new FactoidalError(`node: no registered stage named '${name}' (see stages())`,
+        { code: 'option.invalid-value' });
+    }
+    return Object.freeze({
+      [NODE]: true,
+      stage: info.name,
+      kind: info.kind,
+      status: info.status,
+      contract: info.contract,
+      assumptions: info.assumptions,
+      wireIn: info.wireIn,
+      wireOut: info.wireOut,
+      runnable: info.runnable,
+      bound: info.bound,
+      params: Object.freeze({ ...(params || {}) }),
+    });
+  }
+
+  function nodesOf(items, who) {
+    const out = [];
+    for (const n of items) {
+      if (n && n[NODE]) out.push(n);
+      else if (n && Array.isArray(n.nodes)) out.push(...nodesOf(n.nodes, who));
+      else throw new TypeError(`${who}: expected nodes from node() or pipelines from pipe()`);
+    }
+    return out;
+  }
+
+  /**
+   * A pipeline: the nodes in order (pipelines are flattened).
+   * `assumptions` is the union of the nodes' named assumptions.
+   * @returns {{nodes: object[], assumptions: string[]}}
+   */
+  function pipe(...items) {
+    const nodes = nodesOf(items, 'pipe');
+    if (nodes.length === 0) throw new TypeError('pipe: no nodes');
+    return Object.freeze({ nodes: Object.freeze(nodes), assumptions: Object.freeze(unionAssumptions(nodes)) });
+  }
+
+  const isWire = (v) => v !== null && typeof v === 'object' && !(v instanceof Dataset) &&
+    Object.prototype.hasOwnProperty.call(v, 'graph') && Array.isArray(v.evidence);
+
+  /**
+   * Run a node or a pipeline. `input` is a wire value `{graph, evidence}`
+   * or the graph itself (text for a reader, else a Dataset or data input).
+   * `options.unchecked: true` lets stages that are not `proved` run,
+   * `missing` ones too when the package has a runner for them; each such
+   * step's record says so (evidence.mjs). Without it, a `missing` stage
+   * refuses before any node runs.
+   * @returns {Promise<{graph: any, evidence: object[], assumptions: string[],
+   *   proved: boolean, uncheckedSteps: string[]}>}
+   */
+  async function run(pipeline, input, options) {
+    if (options !== undefined && (options === null || typeof options !== 'object')) {
+      throw new TypeError('run: options must be an object');
+    }
+    const unchecked = !!(options && options.unchecked);
+    const nodes = nodesOf([pipeline], 'run');
+    for (const n of nodes) {
+      const why = refusalFor(n, unchecked, Object.prototype.hasOwnProperty.call(RUNNERS, n.stage));
+      if (why) throw why;
+    }
+    let wire = isWire(input) ? { graph: input.graph, evidence: [...input.evidence] }
+      : { graph: input, evidence: [] };
+    let owned = null; // a Dataset an earlier node of this run made
+    for (const n of nodes) {
+      const out = await RUNNERS[n.stage](wire, n.params);
+      const record = makeRecord(n, out.artefact, unchecked);
+      let graph = wire.graph;
+      if (out.graph !== undefined && out.graph !== wire.graph) {
+        if (owned && owned === wire.graph && typeof owned.dispose === 'function') owned.dispose();
+        graph = out.graph;
+        owned = out.graph instanceof Dataset ? out.graph : null;
+      }
+      wire = { graph, evidence: [...wire.evidence, record] };
+    }
+    return { graph: wire.graph, evidence: wire.evidence, ...summarize(wire.evidence) };
+  }
+
+  return { stages, node, pipe, run };
+}

package/lib/sbm11-node.mjs

@@ -0,0 +1,61 @@
+// The Node reader of an SBM11 generation directory for lib/sbm11.mjs: the
+// source is a directory path, and a file of the generation is read with
+// fs.readSync at an offset (https://github.com/danbri/factoidal/issues/1009
+// KR1). It moves bytes only (iron rule 7); the engine checks every length.
+//
+// One open file descriptor per file, kept while the reader lives: a query
+// makes many small reads of the same few files.
+
+import { closeSync, fstatSync, openSync, readSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export function nodeDirectoryReader (dir) {
+  const fds = new Map()
+  function fdOf (file) {
+    let fd = fds.get(file)
+    if (fd === undefined) {
+      fd = openSync(join(dir, file), 'r')
+      fds.set(file, fd)
+    }
+    return fd
+  }
+  return {
+    readAt (file, offset, length) {
+      const out = new Uint8Array(length)
+      const fd = fdOf(file)
+      let done = 0
+      while (done < length) {
+        const n = readSync(fd, out, done, length - done, offset + done)
+        if (n === 0) break
+        done += n
+      }
+      return done === length ? out : null
+    },
+    size (file) {
+      try {
+        const fd = fds.get(file)
+        const st = fd === undefined ? statSync(join(dir, file)) : fstatSync(fd)
+        return st.isFile() ? st.size : null
+      } catch {
+        return null
+      }
+    },
+    close () {
+      for (const fd of fds.values()) closeSync(fd)
+      fds.clear()
+    }
+  }
+}
+
+/** A default-reader factory: one reader per directory, kept. */
+export function nodeDefaultReaderFactory () {
+  const byDir = new Map()
+  return (source) => {
+    let r = byDir.get(source)
+    if (!r) {
+      r = nodeDirectoryReader(source)
+      byDir.set(source, r)
+    }
+    return r
+  }
+}

package/lib/sbm11.mjs

@@ -0,0 +1,148 @@
+// SPARQL over an SBM11 generation, in Node and in the browser, through the
+// wasm ops sbm11Open / sbm11Query / sbm11Close
+// (formal/lean4/Wasm/Ops/Sbm11.lean; https://github.com/danbri/factoidal/issues/1009 KR1).
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Move bytes. The engine asks for (source, file, offset, length) through the
+// bridge globalThis.__factoidalReadAt, and for the size of a file through
+// globalThis.__factoidalFileSize (the EM_JS bodies in
+// formal/lean4/ffi/l4_hostread.c call them synchronously). This file finds
+// the reader that serves `source` and answers. It never reads a manifest,
+// checks a length or a digest, or decides which file a query needs: the
+// engine names every file and checks every answer against the manifest
+// (formal/lean4/L4Factoidal/Storage/Sbm11/HostSession.lean). Iron rule 7.
+//
+// READERS
+// A reader is { readAt(file, offset, length) -> Uint8Array, size(file) ->
+// number | null }, both synchronous: the engine is inside WebAssembly and
+// cannot wait for a promise. Node: lib/sbm11-node.mjs reads a directory with
+// fs. A browser worker: a reader over OPFS FileSystemSyncAccessHandle
+// (stage 4 of https://github.com/danbri/factoidal/issues/1007). A caller
+// registers a reader under a source name; a source with no registered reader
+// goes to the default reader (Node: the directory of that name).
+
+const readers = new Map()
+let defaultReader = null
+let bridgeInstalled = false
+
+function readerFor (source) {
+  const r = readers.get(source)
+  if (r) return r
+  if (defaultReader) return defaultReader(source)
+  return null
+}
+
+function installBridge () {
+  if (bridgeInstalled) return
+  bridgeInstalled = true
+  // A thrown error and a wrong length both reach Lean as "the host gave no
+  // bytes"; the engine then refuses the read with the file name.
+  globalThis.__factoidalReadAt = (source, file, offset, length) => {
+    const r = readerFor(source)
+    if (!r) return null
+    return r.readAt(file, offset, length)
+  }
+  globalThis.__factoidalFileSize = (source, file) => {
+    const r = readerFor(source)
+    if (!r) return null
+    return r.size(file)
+  }
+}
+
+/**
+ * Serve `source` with `reader` ({ readAt(file, offset, length), size(file) },
+ * both synchronous). `null` removes the registration.
+ */
+export function registerSbm11Source (source, reader) {
+  installBridge()
+  if (reader === null) { readers.delete(String(source)); return }
+  if (!reader || typeof reader.readAt !== 'function' || typeof reader.size !== 'function') {
+    throw new TypeError('registerSbm11Source: reader needs readAt(file, offset, length) and size(file)')
+  }
+  readers.set(String(source), reader)
+}
+
+/** The reader for a source with no registration: `(source) => reader | null`. */
+export function setDefaultSbm11Reader (factory) {
+  installBridge()
+  defaultReader = factory
+}
+
+function envelope (raw) {
+  const j = typeof raw === 'string' ? JSON.parse(raw) : raw
+  if (!j || j.ok !== true) {
+    const e = new Error((j && j.error) || 'sbm11: unknown error')
+    e.code = 'SBM11'
+    throw e
+  }
+  return j
+}
+
+/**
+ * The SBM11 functions over an engine loader: `loadEngine()` resolves to the
+ * engine handle (`call(op, args)`).
+ */
+export function sbm11Api (loadEngine) {
+  /**
+   * Open an SBM11 generation (a generation directory, or a collection root
+   * whose CURRENT file names one). Returns { generation, terms, query(sparql,
+   * options), close() }. `query` answers { path, rows, format, result, json }:
+   * `result` is the text `l4sbm11 query` writes (SPARQL JSON for SELECT and
+   * ASK, N-Triples for CONSTRUCT and DESCRIBE), `json` its parse for
+   * SELECT and ASK.
+   */
+  async function openSbm11 (source, options = {}) {
+    installBridge()
+    if (options.reader) registerSbm11Source(source, options.reader)
+    const eng = await loadEngine()
+    const opened = envelope(eng.call('sbm11Open', [String(source)]))
+    const handle = opened.handle
+    let open = true
+    return {
+      handle,
+      generation: opened.generation,
+      terms: Number(opened.terms),
+      query (sparql, qopts = {}) {
+        if (!open) throw new Error('sbm11: the store is closed')
+        const o = {}
+        if (qopts.base != null) o.base = String(qopts.base)
+        if (qopts.sparql12) o.sparql12 = true
+        if (qopts.reference) o.reference = true
+        const args = [handle, String(sparql), JSON.stringify(o)]
+        // The byte-region entry returns the result bytes outside the
+        // envelope; a large answer is then not escaped into a JSON string
+        // and parsed again (Wasm/Ops/Sbm11.lean sbm11QueryBlob).
+        let j, bytes
+        if (typeof eng.callBlobIO === 'function') {
+          const answer = eng.callBlobIO('sbm11Query', args, new Uint8Array(0))
+          j = envelope(answer.envelope)
+          bytes = answer.bytes
+        } else {
+          j = envelope(eng.call('sbm11Query', args))
+        }
+        let text = bytes === undefined ? j.result : undefined
+        return {
+          path: j.path,
+          rows: Number(j.rows),
+          format: j.format,
+          bytesRead: Number(j.bytesRead),
+          reads: Number(j.reads),
+          /** the answer as bytes (UTF-8) */
+          get bytes () { return bytes ?? new TextEncoder().encode(text) },
+          /** the answer as text */
+          get result () {
+            if (text === undefined) text = new TextDecoder().decode(bytes)
+            return text
+          },
+          get json () { return j.format === 'srj' ? JSON.parse(this.result) : undefined }
+        }
+      },
+      close () {
+        if (!open) return
+        open = false
+        envelope(eng.call('sbm11Close', [handle]))
+      }
+    }
+  }
+  return { openSbm11 }
+}

package/lib/version.mjs

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