@factoidal/core 0.1.0

package/lib/engine-js.js

@@ -0,0 +1,165 @@
+// factoidal — Node driver for the js_of_ocaml CLI bundle.
+//
+// The engine bundle (factoidal.js) is a single-shot CLI: argv in,
+// stdout out. runCli() drives one invocation in-process:
+//   1. input documents are registered in js_of_ocaml's fake filesystem
+//      (globalThis.jsoo_fs_tmp, drained at engine startup — `/static/`
+//      is always the MlFakeDevice mount, in Node and browsers alike);
+//   2. globalThis.process.argv carries the flags;
+//   3. stdout/stderr are captured on BOTH channels the bundle may use:
+//      console.log/.error (the fstar_utf8_output_stubs.js path in
+//      current bundles) and require('fs').writeSync on fds 1/2 (the
+//      classic js_of_ocaml path), the latter via a proxied require;
+//   4. process.exit is replaced by a sentinel throw.
+//
+// This file also resolves WHICH bundle to load: an explicit override,
+// then the package-local copy (what npm ships), then the repo build
+// output (developer tree). The resolution is exported so tests can pin
+// the freshest artifact.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+/** Candidate bundle paths, in resolution order. */
+function bundleCandidates() {
+  const c = [];
+  if (process.env.FACTOIDAL_JS_BUNDLE) c.push(process.env.FACTOIDAL_JS_BUNDLE);
+  c.push(path.join(PKG_ROOT, 'factoidal.js'));
+  // Developer tree fallback: repo build output.
+  c.push(path.resolve(PKG_ROOT, '..', '..', 'docs', 'fstar-extracted', 'factoidal.js'));
+  return c;
+}
+
+// A bundle is usable for the typed API when its CLI knows --dump-nq
+// (the argv strings survive into the generated JavaScript, so a
+// substring check is a reliable capability sniff). Prefer the first
+// candidate that qualifies; fall back to the first that merely exists
+// so queryRaw() keeps working against very old bundles.
+function resolveBundlePath() {
+  let firstExisting = null;
+  for (const p of bundleCandidates()) {
+    if (!p || !fs.existsSync(p)) continue;
+    if (firstExisting === null) firstExisting = p;
+    try {
+      if (fs.readFileSync(p, 'utf8').includes('--dump-nq')) return p;
+    } catch (_) { /* unreadable candidate — keep looking */ }
+  }
+  if (firstExisting) return firstExisting;
+  throw new Error(
+    'factoidal.js engine bundle not found. Run ' +
+    "'formal/fstar/build-ocaml.sh js && formal/fstar/build-ocaml.sh npm' " +
+    'in the repo, or set FACTOIDAL_JS_BUNDLE.'
+  );
+}
+
+let _src = null;
+let _srcPath = null;
+
+function loadSource() {
+  const p = resolveBundlePath();
+  if (_src !== null && _srcPath === p) return _src;
+  _src = fs.readFileSync(p, 'utf8');
+  _srcPath = p;
+  return _src;
+}
+
+/**
+ * Run one CLI invocation of the js_of_ocaml engine bundle.
+ *
+ * @param {string[]} args   CLI arguments (after argv[0]/argv[1]).
+ * @param {Array<{name: string, content: string}>} files
+ *        Documents for the fake filesystem. Names must start
+ *        with '/static/'.
+ * @returns {{stdout: string, stderr: string, exitCode: number}}
+ */
+function runCli(args, files) {
+  const orig = {
+    argv: globalThis.process ? globalThis.process.argv : undefined,
+    exit: globalThis.process ? globalThis.process.exit : undefined,
+    jsooFs: globalThis.jsoo_fs_tmp,
+    consoleLog: console.log,
+    consoleError: console.error,
+  };
+
+  const stdoutChunks = [];
+  const stderrChunks = [];
+  function asUtf8(data) {
+    if (typeof data === 'string') return data;
+    if (data && typeof data.toString === 'function') {
+      try { return Buffer.from(data).toString('utf8'); }
+      catch (_) { return String(data); }
+    }
+    return String(data);
+  }
+
+  // js_of_ocaml's Node runtime opens fds 1/2 via require('fs') and
+  // writes with fs.writeSync — bypassing console.log and
+  // process.stdout. Proxy the fs module we hand the bundle.
+  const patchedFs = new Proxy(fs, {
+    get(target, prop, receiver) {
+      if (prop === 'writeSync') {
+        return function proxyWriteSync(fd, chunk, ...rest) {
+          if (fd === 1) { stdoutChunks.push(asUtf8(chunk)); return asUtf8(chunk).length; }
+          if (fd === 2) { stderrChunks.push(asUtf8(chunk)); return asUtf8(chunk).length; }
+          return target.writeSync(fd, chunk, ...rest);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+  function wrappedRequire(name) {
+    if (name === 'fs' || name === 'node:fs') return patchedFs;
+    return require(name);
+  }
+
+  globalThis.process = globalThis.process || {};
+  globalThis.process.argv = ['node', 'factoidal', ...args];
+  globalThis.jsoo_fs_tmp = (files || []).map((f) => ({
+    name: f.name,
+    content: f.content,
+  }));
+
+  // Current bundles emit stdout/stderr line-wise via console.log /
+  // console.error (fstar_utf8_output_stubs.js); console adds the
+  // trailing newline, so re-append it when capturing.
+  console.log = (...a) => { stdoutChunks.push(a.map(asUtf8).join(' ') + '\n'); };
+  console.error = (...a) => { stderrChunks.push(a.map(asUtf8).join(' ') + '\n'); };
+
+  let exitCode = 0;
+  const EXIT_SENTINEL = new Error('__factoidal_exit__');
+  globalThis.process.exit = (n) => { exitCode = n | 0; throw EXIT_SENTINEL; };
+
+  function restore() {
+    if (globalThis.process) {
+      globalThis.process.argv = orig.argv;
+      globalThis.process.exit = orig.exit;
+    }
+    globalThis.jsoo_fs_tmp = orig.jsooFs;
+    console.log = orig.consoleLog;
+    console.error = orig.consoleError;
+  }
+
+  try {
+    const src = loadSource();
+    (new Function('require', src))(wrappedRequire);
+  } catch (e) {
+    if (e !== EXIT_SENTINEL) {
+      restore();
+      throw e;
+    }
+  } finally {
+    restore();
+  }
+
+  return {
+    stdout: stdoutChunks.join(''),
+    stderr: stderrChunks.join(''),
+    exitCode,
+  };
+}
+
+module.exports = { runCli, resolveBundlePath };

package/lib/engine-wasm.js

@@ -0,0 +1,300 @@
+// factoidal — Node driver for the wasm_of_ocaml CLI bundle.
+//
+// Same runCli(args, files) contract as ./engine-js.js, but backed by
+// factoidal.wasm.js + factoidal.wasm.assets/*.wasm. The technique is
+// the one proven by browser-wasm.js / test/smoke-wasm.mjs:
+//
+//   - the wasm loader is an async IIFE whose Promise is discarded at
+//     source level; a one-marker rewrite captures it so we can await
+//     completion;
+//   - we force the loader down its Node branch (versions.node truthy)
+//     and hand it a fake require() whose 'node:fs' serves our
+//     in-memory input documents (the wasm build has no MlFakeDevice /
+//     jsoo_fs_tmp) and routes fds 1/2 into capture buffers;
+//   - 'node:fs/promises'.readFile serves the .wasm asset bytes from
+//     the real filesystem.
+//
+// Unlike engine-js.js this driver is async (wasm instantiation).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+// The bundle's entry is an immediately-invoked async factory:
+//   ;(<param>=>async <arg>=>{...})(...)
+// wasm_of_ocaml minifies <param> differently across versions ('$' in
+// 6.x releases before mid-2026, 'ag' in 6.4.1), so match the shape,
+// not a fixed name, and splice in the __fwPromise capture after the
+// leading ';'.
+const IIFE_RE = /;\((\$|[A-Za-z_$][\w$]*)=>async /;
+const IIFE_CAPTURE = ';globalThis.__fwPromise=';
+
+function bundleCandidates() {
+  const c = [];
+  if (process.env.FACTOIDAL_WASM_BUNDLE) c.push(process.env.FACTOIDAL_WASM_BUNDLE);
+  c.push(path.join(PKG_ROOT, 'factoidal.wasm.js'));
+  c.push(path.resolve(PKG_ROOT, '..', '..', 'docs', 'fstar-extracted', 'factoidal.wasm.js'));
+  return c;
+}
+
+function resolveBundlePath() {
+  for (const p of bundleCandidates()) {
+    if (p && fs.existsSync(p)) return p;
+  }
+  throw new Error(
+    'factoidal.wasm.js engine bundle not found. Run ' +
+    "'formal/fstar/build-ocaml.sh wasm-factoidal' in the repo, or set " +
+    'FACTOIDAL_WASM_BUNDLE.'
+  );
+}
+
+/** True if the wasm bundle (loader + .wasm asset) is present. */
+function wasmAvailable() {
+  try {
+    const loader = resolveBundlePath();
+    const assets = path.join(path.dirname(loader), 'factoidal.wasm.assets');
+    return fs.existsSync(assets) &&
+      fs.readdirSync(assets).some((f) => f.endsWith('.wasm'));
+  } catch (_) {
+    return false;
+  }
+}
+
+let _src = null;
+let _srcPath = null;
+let _assetsDir = null;
+
+function loadSource() {
+  const p = resolveBundlePath();
+  if (_src !== null && _srcPath === p) return _src;
+  const raw = fs.readFileSync(p, 'utf8');
+  const m = IIFE_RE.exec(raw);
+  if (!m) {
+    throw new Error(
+      'engine-wasm: could not locate the async IIFE marker in ' +
+      'factoidal.wasm.js — the bundle shape may have changed.'
+    );
+  }
+  // Keep everything, but capture the invoked IIFE's promise:
+  // ';(' → ';globalThis.__fwPromise=('
+  _src = raw.slice(0, m.index) + IIFE_CAPTURE + raw.slice(m.index + 1);
+  _srcPath = p;
+  _assetsDir = path.join(path.dirname(p), 'factoidal.wasm.assets');
+  return _src;
+}
+
+function makeStat(size, isFile, opts) {
+  const bigint = !!(opts && opts.bigint);
+  const toN = (v) => (bigint ? BigInt(v) : v);
+  return {
+    isFile:            () => isFile,
+    isDirectory:       () => false,
+    isCharacterDevice: () => !isFile,
+    isBlockDevice:     () => false,
+    isSymbolicLink:    () => false,
+    isFIFO:            () => false,
+    isSocket:          () => false,
+    dev: toN(0), ino: toN(0), mode: toN(0o100644),
+    nlink: toN(1), uid: toN(0), gid: toN(0), rdev: toN(0),
+    size: toN(size),
+    atimeMs: bigint ? 0n : 0,
+    mtimeMs: bigint ? 0n : 0,
+    ctimeMs: bigint ? 0n : 0,
+  };
+}
+
+/**
+ * Run one CLI invocation of the wasm engine bundle.
+ * Same contract as engine-js.runCli, but async.
+ *
+ * @param {string[]} args
+ * @param {Array<{name: string, content: string}>} files
+ * @returns {Promise<{stdout: string, stderr: string, exitCode: number}>}
+ */
+async function runCli(args, files) {
+  const src = loadSource();
+
+  const TE = new TextEncoder();
+  const TD = new TextDecoder('utf-8');
+  const fileMap = new Map(
+    (files || []).map((f) => [f.name, TE.encode(f.content)])
+  );
+
+  const stdoutBuf = [];
+  const stderrBuf = [];
+
+  let exitCode = 0;
+  const EXIT_SENTINEL = new Error('__factoidal_exit__');
+  EXIT_SENTINEL.__factoidalExit = true;
+
+  const fakeOpenFds = Object.create(null);
+  let nextFd = 100;
+
+  function writeSync(fd, buf, offset, length /*, position */) {
+    let s;
+    if (typeof buf === 'string') {
+      s = buf;
+    } else {
+      const u8 = buf instanceof Uint8Array
+        ? buf
+        : new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+      const start = offset || 0;
+      const end = start + (length === undefined ? u8.length - start : length);
+      s = TD.decode(u8.subarray(start, end));
+    }
+    (fd === 2 ? stderrBuf : stdoutBuf).push(s);
+    return length === undefined ? s.length : length;
+  }
+
+  const fileForPath = (p) => fileMap.get(String(p)) || null;
+
+  const fakeFs = {
+    constants: {
+      R_OK: 4, W_OK: 2, X_OK: 1, F_OK: 0,
+      O_RDONLY: 0, O_WRONLY: 1, O_RDWR: 2, O_APPEND: 8, O_CREAT: 512,
+      O_TRUNC: 1024, O_EXCL: 2048, O_NONBLOCK: 4096, O_NOCTTY: 8192,
+      O_DSYNC: 4194304, O_SYNC: 128,
+    },
+    writeSync,
+    openSync: (p /*, flags, mode */) => {
+      const f = fileForPath(p);
+      if (!f) {
+        throw Object.assign(
+          new Error(`ENOENT: no such file or directory, open '${p}'`),
+          { code: 'ENOENT', errno: -2, syscall: 'open', path: p });
+      }
+      const fd = nextFd++;
+      fakeOpenFds[fd] = { path: String(p), buf: f, offset: 0 };
+      return fd;
+    },
+    closeSync: (fd) => { delete fakeOpenFds[fd]; },
+    readSync: (fd, buf, offset, length, position) => {
+      const f = fakeOpenFds[fd];
+      if (!f) throw Object.assign(new Error('EBADF'), { code: 'EBADF', errno: -9 });
+      const pos = (position === null || position === undefined)
+        ? f.offset : Number(position);
+      const remaining = Math.max(0, f.buf.length - pos);
+      const n = Math.min(length, remaining);
+      for (let i = 0; i < n; i++) buf[offset + i] = f.buf[pos + i];
+      if (position === null || position === undefined) f.offset = pos + n;
+      return n;
+    },
+    fsyncSync: () => {},
+    existsSync: (p) => fileForPath(p) !== null,
+    accessSync: (p) => {
+      if (!fileForPath(p)) {
+        throw Object.assign(new Error('ENOENT'), { code: 'ENOENT', errno: -2 });
+      }
+    },
+    statSync: (p, o) => {
+      const f = fileForPath(p);
+      if (!f) {
+        if (o && o.throwIfNoEntry === false) return undefined;
+        throw Object.assign(new Error('ENOENT'), { code: 'ENOENT', errno: -2 });
+      }
+      return makeStat(f.length, true, o);
+    },
+    lstatSync: (p, o) => fakeFs.statSync(p, o),
+    fstatSync: (fd, o) => {
+      const f = fakeOpenFds[fd];
+      return makeStat(f ? f.buf.length : 0, !!f, o);
+    },
+  };
+
+  // Serve the .wasm asset from the real filesystem next to the loader.
+  async function readWasmAsset(requestedPath) {
+    const s = String(requestedPath);
+    const marker = 'factoidal.wasm.assets/';
+    const ix = s.lastIndexOf(marker);
+    const sub = ix < 0 ? s : s.slice(ix + marker.length);
+    const abs = path.join(_assetsDir, path.basename(sub));
+    return fs.readFileSync(abs);
+  }
+
+  const fakeRequire = (name) => {
+    if (name === 'node:fs')          return fakeFs;
+    if (name === 'node:fs/promises') return { readFile: readWasmAsset };
+    if (name === 'node:path')        return {
+      join:    (...parts) => parts.filter(Boolean).join('/').replace(/\/+/g, '/'),
+      dirname: (p)        => String(p).replace(/\/[^/]*$/, '') || '.',
+    };
+    if (name === 'node:os')            return { tmpdir: () => '/tmp' };
+    if (name === 'node:tty')           return { isatty: () => false };
+    if (name === 'node:child_process') return { spawnSync: () => ({ status: 0, signal: null }) };
+    throw new Error(`engine-wasm shim: unexpected require('${name}')`);
+  };
+  fakeRequire.main = { filename: '/factoidal/main.js' };
+
+  const fakeProc = {
+    argv: ['node', 'factoidal', ...args],
+    exit: (n) => { exitCode = n | 0; throw EXIT_SENTINEL; },
+    stdout: { write: (s) => stdoutBuf.push(String(s)) },
+    stderr: { write: (s) => stderrBuf.push(String(s)) },
+    platform: 'linux',
+    versions: { node: process.versions.node || '22.0.0' },
+    env: {},
+    cpuUsage: () => ({ user: 0, system: 0 }),
+    on:       () => {},
+    cwd:      () => '/static',
+    chdir:    () => {},
+  };
+
+  const orig = {
+    proc:      globalThis.process,
+    jsooFs:    globalThis.jsoo_fs_tmp,
+    require:   globalThis.require,
+    fwPromise: globalThis.__fwPromise,
+    consoleLog: console.log,
+    consoleError: console.error,
+  };
+
+  globalThis.process = fakeProc;
+  globalThis.require = fakeRequire;
+  globalThis.jsoo_fs_tmp = undefined;
+  delete globalThis.__fwPromise;
+  // Belt and braces: some bundle variants route output through
+  // console.log/.error (line-wise, newline re-appended on capture).
+  console.log = (...a) => { stdoutBuf.push(a.map(String).join(' ') + '\n'); };
+  console.error = (...a) => { stderrBuf.push(a.map(String).join(' ') + '\n'); };
+
+  function restoreGlobals() {
+    globalThis.process = orig.proc;
+    globalThis.jsoo_fs_tmp = orig.jsooFs;
+    if (orig.require === undefined) delete globalThis.require;
+    else globalThis.require = orig.require;
+    if (orig.fwPromise === undefined) delete globalThis.__fwPromise;
+    else globalThis.__fwPromise = orig.fwPromise;
+    console.log = orig.consoleLog;
+    console.error = orig.consoleError;
+  }
+
+  try {
+    (new Function(src))();
+    const p = globalThis.__fwPromise;
+    if (!p || typeof p.then !== 'function') {
+      throw new Error(
+        'engine-wasm: __fwPromise was not captured — the bundle shape ' +
+        'may have changed.');
+    }
+    try {
+      await p;
+    } catch (e) {
+      // process.exit throws the sentinel through the async IIFE; that
+      // is the normal completion path.
+      if (e !== EXIT_SENTINEL && !(e && e.__factoidalExit)) throw e;
+    }
+  } finally {
+    restoreGlobals();
+  }
+
+  return {
+    stdout: stdoutBuf.join(''),
+    stderr: stderrBuf.join(''),
+    exitCode,
+  };
+}
+
+module.exports = { runCli, resolveBundlePath, wasmAvailable };

package/package.json

@@ -0,0 +1,101 @@
+{
+  "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*.",
+  "keywords": [
+    "sparql",
+    "rdf",
+    "turtle",
+    "ntriples",
+    "nquads",
+    "trig",
+    "rdf-xml",
+    "fstar",
+    "formal-verification",
+    "semantic-web"
+  ],
+  "homepage": "https://github.com/danbri/factoidal",
+  "bugs": {
+    "url": "https://github.com/danbri/factoidal/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Dan Brickley <danbri@danbri.org>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danbri/factoidal.git",
+    "directory": "npm/factoidal"
+  },
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "browser": "./browser.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "browser": "./browser.js",
+      "import": "./index.mjs",
+      "require": "./index.js",
+      "default": "./index.js"
+    },
+    "./wasm": {
+      "types": "./wasm.d.ts",
+      "default": "./wasm.js"
+    },
+    "./rdfjs": "./rdfjs.js",
+    "./fn": {
+      "types": "./fn.d.ts",
+      "default": "./fn.js"
+    },
+    "./browser": {
+      "types": "./browser.d.ts",
+      "default": "./browser.js"
+    },
+    "./browser-wasm": {
+      "browser": "./browser-wasm.js",
+      "default": "./browser-wasm.js"
+    },
+    "./factoidal.js": "./factoidal.js",
+    "./factoidal.wasm.js": "./factoidal.wasm.js",
+    "./factoidal.wasm.assets/*": "./factoidal.wasm.assets/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "wasm.js",
+    "wasm.d.ts",
+    "rdfjs.js",
+    "fn.js",
+    "fn.d.ts",
+    "lib/",
+    "browser.js",
+    "browser.d.ts",
+    "browser-wasm.js",
+    "factoidal.js",
+    "factoidal.wasm.js",
+    "factoidal.wasm.assets/",
+    "factoidal-npm-entry.js",
+    "factoidal-npm-entry.wasm.js",
+    "factoidal-npm-entry.wasm.assets/",
+    "hacl-init.js",
+    "hacl-wasm/",
+    "version.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "cd ../../formal/fstar && ./build-ocaml.sh npm",
+    "test": "node --test 'test/*.test.js'",
+    "test:smoke": "node test/smoke.js && node test/smoke-wasm.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}