flatsql 3.11.1 → 3.12.1

package/wasm/ps-node-fault.d.mts

@@ -1,23 +0,0 @@
-// Types for wasm/ps-node-fault.mjs (the Node host's fault overlay).
-
-export type PsCrashMode = 'dropAll' | 'pageSubset' | 'keepAll';
-
-export interface PsFaultOverlay {
-  buffer: SharedArrayBuffer;
-  /** Every later mutating call fails with EIO (the process is dying). */
-  freeze(): void;
-  stats(): { writes: number; syncs: number; pagesUsed: number; overflow: boolean };
-  /** Apply a crash once every guest thread has stopped, then reset the overlay. */
-  crash(
-    mode: PsCrashMode,
-    random?: () => number,
-  ): { pagesUndone: number; pagesKept: number; filesTruncated: number; entriesDropped: number };
-}
-
-export const PAGE: number;
-export function createFaultOverlay(options?: { maxFiles?: number; maxPages?: number }): PsFaultOverlay;
-export function attachFaultOverlay(buffer: SharedArrayBuffer): PsFaultOverlay;
-export function createFaultInterposer(
-  buffer: SharedArrayBuffer,
-  root?: string,
-): (op: string, fn: (...args: unknown[]) => unknown, args: unknown[]) => unknown;

package/wasm/ps-node-fault.mjs

@@ -1,381 +0,0 @@
-// FlatSQL partition store: the Node host's fault overlay (design §19,
-// 22.3a-7; docs/PARTITION-STORE-WASM.md).
-//
-// A SharedArrayBuffer page table every worker consults. It sits under the
-// SDK's Node sync-fs flatsql_io provider (its `interpose` hook) and records,
-// for every file, what a power loss could take away:
-//   - the pre-image of every 4 KiB page written since the file's last sync,
-//     and the size the file had at that sync;
-//   - files created since their parent directory's last sync.
-// The supervisor freezes the overlay (every later mutating call fails with
-// EIO, as from a dying process), stops the guest, then applies a crash:
-//   dropAll     every unsynced page write and size change is undone, and
-//               entries created since the parent's last sync disappear;
-//   pageSubset  each unsynced page independently survives or is undone
-//               (writeback in any order), and the size is the synced or the
-//               current one;
-//   keepAll     kill -9 with the page cache intact: nothing is undone.
-// Reads and syncs pass through. The overlay never touches data the guest has
-// synced: a record acked after its durable append must survive every mode.
-
-import fs from "node:fs";
-import path from "node:path";
-
-export const PAGE = 4096;
-const MAGIC = 0x46534c54; // "FSLT"
-
-// Header words.
-const H_MAGIC = 0;
-const H_FROZEN = 1;
-const H_OVERFLOW = 2;
-const H_MAX_FILES = 3;
-const H_MAX_PAGES = 4;
-const H_NEXT_PAGE = 5;
-const H_WRITES = 6;
-const H_SYNCS = 7;
-const H_WORDS = 16;
-// File words: state, lock, flags, head page entry, pathLen, pad x3.
-const F_WORDS = 8;
-const F_STATE = 0;
-const F_LOCK = 1;
-const F_FLAGS = 2;
-const F_HEAD = 3;
-const F_PATHLEN = 4;
-const F_EMPTY = 0;
-const F_CLAIM = 1;
-const F_LIVE = 2;
-const FLAG_TRACKED = 1; // synced size recorded
-const FLAG_NEW_ENTRY = 2; // created since the parent directory's last sync
-const MAX_PATH = 1024;
-// Page entry words: fileId, pageNo, preimage length, next.
-const P_WORDS = 4;
-
-const mix = (s) => {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < s.length; i += 1) {
-    h ^= s.charCodeAt(i);
-    h = Math.imul(h, 0x01000193) >>> 0;
-  }
-  return h;
-};
-
-/**
- * Allocate an overlay. `maxPages` bounds the unsynced pages tracked at once
- * (4 KiB each); overflowing it is reported, never silently ignored.
- */
-export function createFaultOverlay({ maxFiles = 16384, maxPages = 65536 } = {}) {
-  const bytes =
-    H_WORDS * 4 + maxFiles * F_WORDS * 4 + maxFiles * 8 + maxFiles * MAX_PATH + maxPages * P_WORDS * 4 + maxPages * PAGE;
-  const buffer = new SharedArrayBuffer(bytes);
-  const h = new Int32Array(buffer, 0, H_WORDS);
-  h[H_MAGIC] = MAGIC;
-  h[H_MAX_FILES] = maxFiles;
-  h[H_MAX_PAGES] = maxPages;
-  const v = views(buffer);
-  v.files.fill(0);
-  for (let i = 0; i < maxFiles; i += 1) v.files[i * F_WORDS + F_HEAD] = -1;
-  return { buffer, ...overlayApi(buffer) };
-}
-
-function views(buffer) {
-  const h = new Int32Array(buffer, 0, H_WORDS);
-  if (h[H_MAGIC] !== MAGIC) throw new TypeError("not a fault overlay");
-  const maxFiles = h[H_MAX_FILES];
-  const maxPages = h[H_MAX_PAGES];
-  let off = H_WORDS * 4;
-  const files = new Int32Array(buffer, off, maxFiles * F_WORDS);
-  off += maxFiles * F_WORDS * 4;
-  const syncedSize = new Float64Array(buffer, off, maxFiles);
-  off += maxFiles * 8;
-  const paths = new Uint8Array(buffer, off, maxFiles * MAX_PATH);
-  off += maxFiles * MAX_PATH;
-  const pages = new Int32Array(buffer, off, maxPages * P_WORDS);
-  off += maxPages * P_WORDS * 4;
-  const images = new Uint8Array(buffer, off, maxPages * PAGE);
-  return { h, maxFiles, maxPages, files, syncedSize, paths, pages, images };
-}
-
-function lock(v, id) {
-  const at = id * F_WORDS + F_LOCK;
-  while (Atomics.compareExchange(v.files, at, 0, 1) !== 0) Atomics.wait(v.files, at, 1, 1);
-}
-function unlock(v, id) {
-  const at = id * F_WORDS + F_LOCK;
-  Atomics.store(v.files, at, 0);
-  Atomics.notify(v.files, at, 1);
-}
-
-function pathOf(v, id) {
-  const len = v.files[id * F_WORDS + F_PATHLEN];
-  return Buffer.from(v.paths.slice(id * MAX_PATH, id * MAX_PATH + len)).toString("utf8");
-}
-
-// File id for a host path (open addressing), created on first sight.
-function fileId(v, full, create) {
-  const bytes = Buffer.from(full);
-  if (bytes.length > MAX_PATH) return -1;
-  let i = mix(full) % v.maxFiles;
-  for (let n = 0; n < v.maxFiles; n += 1, i = (i + 1) % v.maxFiles) {
-    const at = i * F_WORDS;
-    let state = Atomics.load(v.files, at + F_STATE);
-    if (state === F_EMPTY) {
-      if (!create) return -1;
-      if (Atomics.compareExchange(v.files, at + F_STATE, F_EMPTY, F_CLAIM) === F_EMPTY) {
-        v.paths.set(bytes, i * MAX_PATH);
-        v.files[at + F_PATHLEN] = bytes.length;
-        v.files[at + F_FLAGS] = 0;
-        v.files[at + F_HEAD] = -1;
-        Atomics.store(v.files, at + F_STATE, F_LIVE);
-        Atomics.notify(v.files, at + F_STATE);
-        return i;
-      }
-      state = Atomics.load(v.files, at + F_STATE);
-    }
-    while (state === F_CLAIM) {
-      Atomics.wait(v.files, at + F_STATE, F_CLAIM, 1);
-      state = Atomics.load(v.files, at + F_STATE);
-    }
-    if (v.files[at + F_PATHLEN] === bytes.length && pathOf(v, i) === full) return i;
-  }
-  Atomics.store(v.h, H_OVERFLOW, 1);
-  return -1;
-}
-
-function sizeOf(fd) {
-  return fs.fstatSync(fd).size;
-}
-
-// Record the synced size the first time a file is written after a sync.
-function track(v, id, fd) {
-  const at = id * F_WORDS + F_FLAGS;
-  if (!(v.files[at] & FLAG_TRACKED)) {
-    v.syncedSize[id] = sizeOf(fd);
-    v.files[at] |= FLAG_TRACKED;
-  }
-}
-
-// Save the pre-image of page `p` unless it is already saved since the last
-// sync. Pages wholly past the synced size need none: a crash cuts the file
-// back to that size, or (pageSubset keeping the size) leaves new or zero bytes
-// there, both of which a real disk can produce.
-function savePage(v, id, fd, p) {
-  if (p * PAGE >= v.syncedSize[id]) return true;
-  for (let e = v.files[id * F_WORDS + F_HEAD]; e >= 0; e = v.pages[e * P_WORDS + 3]) {
-    if (v.pages[e * P_WORDS + 1] === p) return true;
-  }
-  const e = Atomics.add(v.h, H_NEXT_PAGE, 1);
-  if (e >= v.maxPages) {
-    Atomics.store(v.h, H_OVERFLOW, 1);
-    return false;
-  }
-  const img = v.images.subarray(e * PAGE, (e + 1) * PAGE);
-  const tmp = Buffer.alloc(PAGE);
-  const n = fs.readSync(fd, tmp, 0, PAGE, p * PAGE);
-  img.set(tmp);
-  v.pages[e * P_WORDS] = id;
-  v.pages[e * P_WORDS + 1] = p;
-  v.pages[e * P_WORDS + 2] = n;
-  v.pages[e * P_WORDS + 3] = v.files[id * F_WORDS + F_HEAD];
-  v.files[id * F_WORDS + F_HEAD] = e;
-  return true;
-}
-
-function frozenError() {
-  return Object.assign(new Error("fault overlay frozen"), { code: "EIO" });
-}
-
-/**
- * The `interpose` hook for one thread's SDK sync-fs provider. `root` is the
- * provider's root (paths it opens are absolute below it).
- */
-export function createFaultInterposer(buffer, _root) {
-  const v = views(buffer);
-  const fdFile = new Map(); // this thread's fds -> file id
-  const mutating = new Set(["write", "truncate", "mkdir", "unlink"]);
-  return (op, fn, args) => {
-    if (
-      Atomics.load(v.h, H_FROZEN) &&
-      (mutating.has(op) || op === "sync" || op === "syncdir" ||
-        (op === "open" && (args[1] & fs.constants.O_CREAT) !== 0))
-    ) {
-      throw frozenError();
-    }
-    if (op === "open") {
-      const full = args[0];
-      const creating = (args[1] & fs.constants.O_CREAT) !== 0;
-      const existed = creating ? fs.existsSync(full) : true;
-      const fd = fn(...args);
-      const id = fileId(v, full, true);
-      if (id >= 0) {
-        fdFile.set(fd, id);
-        if (creating && !existed) {
-          lock(v, id);
-          v.files[id * F_WORDS + F_FLAGS] = (v.files[id * F_WORDS + F_FLAGS] | FLAG_NEW_ENTRY) & ~FLAG_TRACKED;
-          // A new file's synced content is nothing.
-          v.syncedSize[id] = 0;
-          v.files[id * F_WORDS + F_FLAGS] |= FLAG_TRACKED;
-          unlock(v, id);
-        }
-      }
-      return fd;
-    }
-    if (op === "close") {
-      fdFile.delete(args[0]);
-      return fn(...args);
-    }
-    if (op === "write") {
-      const [fd, view, off, len, pos] = args;
-      const id = fdFile.get(fd);
-      if (id === undefined) return fn(...args);
-      lock(v, id);
-      try {
-        track(v, id, fd);
-        const first = Math.floor(pos / PAGE);
-        const last = Math.floor((pos + len - 1) / PAGE);
-        for (let p = first; p <= last; p += 1) savePage(v, id, fd, p);
-        Atomics.add(v.h, H_WRITES, 1);
-        return fn(fd, view, off, len, pos);
-      } finally {
-        unlock(v, id);
-      }
-    }
-    if (op === "truncate") {
-      const [fd, size] = args;
-      const id = fdFile.get(fd);
-      if (id === undefined) return fn(...args);
-      lock(v, id);
-      try {
-        track(v, id, fd);
-        const cur = sizeOf(fd);
-        for (let p = Math.floor(size / PAGE); p * PAGE < cur; p += 1) savePage(v, id, fd, p);
-        return fn(...args);
-      } finally {
-        unlock(v, id);
-      }
-    }
-    if (op === "sync") {
-      const [fd] = args;
-      const id = fdFile.get(fd);
-      const r = fn(...args);
-      if (id !== undefined) {
-        lock(v, id);
-        // Everything written before this sync returned is durable.
-        v.files[id * F_WORDS + F_HEAD] = -1;
-        v.files[id * F_WORDS + F_FLAGS] &= ~FLAG_TRACKED;
-        unlock(v, id);
-        Atomics.add(v.h, H_SYNCS, 1);
-      }
-      return r;
-    }
-    if (op === "syncdir") {
-      const r = fn(...args);
-      const dir = path.resolve(args[0]);
-      for (let id = 0; id < v.maxFiles; id += 1) {
-        if (Atomics.load(v.files, id * F_WORDS + F_STATE) !== F_LIVE) continue;
-        if (!(v.files[id * F_WORDS + F_FLAGS] & FLAG_NEW_ENTRY)) continue;
-        if (path.dirname(pathOf(v, id)) !== dir) continue;
-        lock(v, id);
-        v.files[id * F_WORDS + F_FLAGS] &= ~FLAG_NEW_ENTRY;
-        unlock(v, id);
-      }
-      return r;
-    }
-    if (op === "unlink") {
-      const full = args[0];
-      const r = fn(...args);
-      const id = fileId(v, full, false);
-      if (id >= 0) {
-        lock(v, id);
-        v.files[id * F_WORDS + F_FLAGS] = 0;
-        v.files[id * F_WORDS + F_HEAD] = -1;
-        unlock(v, id);
-      }
-      return r;
-    }
-    return fn(...args);
-  };
-}
-
-function overlayApi(buffer) {
-  const v = views(buffer);
-  return {
-    /** Every later mutating call fails with EIO (the process is dying). */
-    freeze() {
-      Atomics.store(v.h, H_FROZEN, 1);
-    },
-    stats() {
-      return {
-        writes: Atomics.load(v.h, H_WRITES),
-        syncs: Atomics.load(v.h, H_SYNCS),
-        pagesUsed: Math.min(Atomics.load(v.h, H_NEXT_PAGE), v.maxPages),
-        overflow: Atomics.load(v.h, H_OVERFLOW) !== 0,
-      };
-    },
-    /**
-     * Apply a crash after every guest thread has stopped, then reset the
-     * overlay (unfrozen, nothing tracked). `random` returns [0, 1).
-     * @returns {{ pagesUndone: number, pagesKept: number, filesTruncated: number, entriesDropped: number }}
-     */
-    crash(mode, random = Math.random) {
-      if (Atomics.load(v.h, H_OVERFLOW)) throw new Error("fault overlay overflowed: the crash would be incomplete");
-      const out = { pagesUndone: 0, pagesKept: 0, filesTruncated: 0, entriesDropped: 0 };
-      for (let id = 0; id < v.maxFiles; id += 1) {
-        const at = id * F_WORDS;
-        if (v.files[at + F_STATE] !== F_LIVE) continue;
-        const flags = v.files[at + F_FLAGS];
-        const full = pathOf(v, id);
-        if (mode !== "keepAll" && flags & FLAG_NEW_ENTRY) {
-          try {
-            fs.unlinkSync(full);
-            out.entriesDropped += 1;
-          } catch {
-            // already gone
-          }
-          continue;
-        }
-        if (mode === "keepAll" || !(flags & FLAG_TRACKED)) continue;
-        let fd;
-        try {
-          fd = fs.openSync(full, "r+");
-        } catch {
-          continue; // unlinked durably since
-        }
-        try {
-          for (let e = v.files[at + F_HEAD]; e >= 0; e = v.pages[e * P_WORDS + 3]) {
-            const undo = mode === "dropAll" || random() < 0.5;
-            if (!undo) {
-              out.pagesKept += 1;
-              continue;
-            }
-            const p = v.pages[e * P_WORDS + 1];
-            const n = v.pages[e * P_WORDS + 2];
-            if (n > 0) fs.writeSync(fd, v.images.subarray(e * PAGE, e * PAGE + n), 0, n, p * PAGE);
-            out.pagesUndone += 1;
-          }
-          const synced = v.syncedSize[id];
-          const size = fs.fstatSync(fd).size;
-          const keepSize = mode === "pageSubset" && random() < 0.5;
-          if (!keepSize && size !== synced) {
-            fs.ftruncateSync(fd, synced);
-            out.filesTruncated += 1;
-          }
-        } finally {
-          fs.closeSync(fd);
-        }
-      }
-      // Reset.
-      for (let id = 0; id < v.maxFiles; id += 1) {
-        v.files[id * F_WORDS + F_FLAGS] = 0;
-        v.files[id * F_WORDS + F_HEAD] = -1;
-      }
-      Atomics.store(v.h, H_NEXT_PAGE, 0);
-      Atomics.store(v.h, H_FROZEN, 0);
-      return out;
-    },
-  };
-}
-
-/** Re-attach to an overlay buffer (for example in another thread). */
-export function attachFaultOverlay(buffer) {
-  return { buffer, ...overlayApi(buffer) };
-}

package/wasm/ps-node-guest.mjs

@@ -1,173 +0,0 @@
-// FlatSQL partition store: a guest thread's worker under the Node host
-// (ps-node-host.mjs). Three modes:
-//
-//   command  the guest's own thread: runs `_start` (the wasm test commands)
-//            and reports its exit;
-//   reactor  the exec thread of one flatsql-ps-threads.wasm instance: runs
-//            `_initialize`, then serves the instance's C ABI calls (init,
-//            start, stats, stop) posted by the supervisor;
-//   pool     a pooled thread for wasi.thread-spawn: waits on its slot of the
-//            pool's SharedArrayBuffer, instantiates the module over the shared
-//            memory, runs wasi_thread_start(tid, arg), and returns to idle.
-//
-// Every mode imports the same host (ps-node-imports.mjs), including
-// wasi.thread-spawn, so any guest thread may spawn threads. The supervisor
-// on the main thread starts pool workers and is never blocked by the guest.
-
-import { parentPort, threadId, workerData } from "node:worker_threads";
-import { writeSync } from "node:fs";
-
-import {
-  CONTROL_EXITED,
-  CONTROL_EXIT_CODE,
-  CONTROL_FAULT,
-  CONTROL_FAULT_TID,
-  POOL_GEN,
-  POOL_HEADER,
-  POOL_MAX_RUNNING,
-  POOL_RUNNING,
-  POOL_SLOT_WORDS,
-  SLOT_ASSIGNED,
-  SLOT_DEAD,
-  SLOT_IDLE,
-  SLOT_RUNNING,
-  WasiExitError,
-  createThreadImports,
-  poolThreadSpawn,
-  registerThread,
-} from "./ps-node-imports.mjs";
-
-const { mode, wasmModule, memory, cfg } = workerData;
-// A pool worker counts as a guest OS thread once it runs a guest thread.
-let control = mode === "pool" ? new Int32Array(cfg.control) : registerThread(cfg.control);
-const pool = new Int32Array(cfg.pool);
-
-const built = createThreadImports(cfg, () => memory);
-const imports = {
-  ...built.imports,
-  env: { ...built.imports.env, memory },
-  wasi: { "thread-spawn": poolThreadSpawn(cfg.pool, cfg.spawnWaitMs) },
-};
-
-const isExit = (error) => error instanceof WasiExitError || error?.name === "WasiExitError";
-
-function exitProcess(code) {
-  if (Atomics.compareExchange(control, CONTROL_EXITED, 0, 1) === 0) {
-    Atomics.store(control, CONTROL_EXIT_CODE, code);
-  }
-  Atomics.notify(control, CONTROL_EXITED);
-}
-
-function fault(tid, error) {
-  // Written here, synchronously: the thread that would join this one may be
-  // blocked in the guest forever.
-  try {
-    writeSync(2, `[ps-node-host] guest thread ${tid} trapped: ${error?.stack ?? error}\n`);
-  } catch {
-    // stderr gone
-  }
-  Atomics.store(control, CONTROL_FAULT_TID, tid);
-  Atomics.store(control, CONTROL_FAULT, 1);
-  Atomics.notify(control, CONTROL_FAULT);
-}
-
-if (mode === "pool") {
-  const slot = POOL_HEADER + workerData.slot * POOL_SLOT_WORDS;
-  Atomics.store(pool, slot + 3, threadId);
-  let registered = false;
-  for (;;) {
-    Atomics.store(pool, slot, SLOT_IDLE);
-    Atomics.add(pool, POOL_GEN, 1);
-    Atomics.notify(pool, POOL_GEN);
-    for (;;) {
-      const state = Atomics.load(pool, slot);
-      if (state === SLOT_ASSIGNED) break;
-      Atomics.wait(pool, slot, state, 1000);
-    }
-    const tid = Atomics.load(pool, slot + 1);
-    const arg = Atomics.load(pool, slot + 2);
-    if (!registered) {
-      registerThread(cfg.control);
-      registered = true;
-    }
-    Atomics.store(pool, slot, SLOT_RUNNING);
-    const running = Atomics.add(pool, POOL_RUNNING, 1) + 1;
-    for (;;) {
-      const max = Atomics.load(pool, POOL_MAX_RUNNING);
-      if (running <= max || Atomics.compareExchange(pool, POOL_MAX_RUNNING, max, running) === max) break;
-    }
-    try {
-      const instance = new WebAssembly.Instance(wasmModule, imports);
-      instance.exports.wasi_thread_start(tid, arg);
-    } catch (error) {
-      Atomics.sub(pool, POOL_RUNNING, 1);
-      Atomics.store(pool, slot, SLOT_DEAD);
-      if (isExit(error)) exitProcess(error.code);
-      else fault(tid, error);
-      break;
-    }
-    Atomics.sub(pool, POOL_RUNNING, 1);
-  }
-  built.close();
-} else if (mode === "command") {
-  const instance = new WebAssembly.Instance(wasmModule, imports);
-  let code = 0;
-  let error = null;
-  try {
-    instance.exports._start();
-  } catch (e) {
-    if (isExit(e)) code = e.code;
-    else {
-      code = 134;
-      error = String(e?.stack ?? e);
-    }
-  }
-  exitProcess(code);
-  parentPort.postMessage({ t: "done", code: Atomics.load(control, CONTROL_EXIT_CODE), error });
-} else {
-  const instance = new WebAssembly.Instance(wasmModule, imports);
-  instance.exports._initialize?.();
-  const mem = () => new Uint8Array(memory.buffer);
-  parentPort.on("message", (msg) => {
-    const reply = (value, err) =>
-      parentPort.postMessage({ t: "reply", id: msg.id, value, error: err ? String(err?.stack ?? err) : null });
-    try {
-      if (msg.op === "call") {
-        const fn = instance.exports[msg.fn];
-        if (typeof fn !== "function") throw new Error(`no export ${msg.fn}`);
-        reply(fn(...(msg.args ?? [])));
-      } else if (msg.op === "write") {
-        const n = msg.bytes.length;
-        const ptr = instance.exports.flatsql_ps_alloc(Math.max(n, 1));
-        if (!ptr) throw new Error("flatsql_ps_alloc failed");
-        mem().set(msg.bytes, ptr);
-        reply(ptr);
-      } else if (msg.op === "read") {
-        reply(mem().slice(msg.ptr, msg.ptr + msg.len));
-      } else if (msg.op === "growHeap") {
-        // The heap to msg.limitBytes of memory before any guest thread starts
-        // (ps-node-host.mjs heapLimitBytes): allocate in steps from 1 GiB
-        // down to 1 MiB until each fails, then free them all. The guest
-        // allocator keeps the freed blocks; wasm memory never shrinks.
-        const { flatsql_ps_alloc: alloc, flatsql_ps_free: free } = instance.exports;
-        const held = [];
-        for (let step = 2 ** 30; step >= 2 ** 20 && held.length < 64; ) {
-          const p = memory.buffer.byteLength + step + 2 ** 20 <= msg.limitBytes ? alloc(step) : 0;
-          if (!p) {
-            step /= 2;
-            continue;
-          }
-          held.push(p);
-        }
-        for (const p of held) free(p);
-        reply(memory.buffer.byteLength);
-      } else {
-        throw new Error(`unknown op ${msg.op}`);
-      }
-    } catch (err) {
-      if (isExit(err)) exitProcess(err.code);
-      reply(undefined, err);
-    }
-  });
-  parentPort.postMessage({ t: "ready" });
-}

package/wasm/ps-node-host.d.mts

@@ -1,95 +0,0 @@
-// Types for wasm/ps-node-host.mjs (the partition store's Node wasi-threads host).
-
-export interface PsThreadReport {
-  /** wasi.thread-spawn calls that started a guest thread. */
-  guestThreadsSpawned: number;
-  /** Most guest threads running at once, the guest's own thread included. */
-  maxConcurrentGuestThreads: number;
-  runningGuestThreads: number;
-  spawnsDeclined: number;
-  /** Node worker threads (OS threads) that ran guest code. */
-  workerThreads: number;
-  distinctWorkerThreadIds: number;
-  memoryBytes: number;
-  /** Bytes the memory grew after the first guest thread ran (V8: a trap hazard). */
-  memoryGrownWhileThreadsRan: number;
-}
-
-export interface PsMount {
-  guest: string;
-  host: string;
-}
-
-export interface PsHostOptions {
-  /** Host directory the guest sees as "/" (WASI and flatsql_io). Default: a private temporary directory, removed afterwards. */
-  root?: string;
-  keepRoot?: boolean;
-  /** Further preopened directories. */
-  mounts?: PsMount[];
-  env?: Record<string, string>;
-  /** Pool cap on guest threads (default 512). */
-  maxThreads?: number;
-  /** Pool workers started up front (default 16). */
-  warmThreads?: number;
-  /** How long a spawn waits for a free worker before failing with EAGAIN (default 60000). */
-  spawnWaitMs?: number;
-  /** Fault overlay (ps-node-fault.mjs createFaultOverlay). */
-  fault?: { buffer: SharedArrayBuffer };
-  stdoutFd?: number;
-  stderrFd?: number;
-  /** Seeded random_get. */
-  deterministic?: { randomSeed?: bigint };
-  initialPages?: number;
-  maximumPages?: number;
-  /**
-   * createPsNodeInstance grows the guest heap to the memory's maximum before
-   * any guest thread starts (V8 can trap a thread touching memory another
-   * thread has just grown). false: no pre-grow. heapBytes caps the growth.
-   */
-  growHeap?: boolean;
-  heapBytes?: number;
-  maxHandles?: number;
-  instanceId?: number;
-}
-
-export interface PsCommandOptions extends PsHostOptions {
-  args?: string[];
-  timeoutMs?: number;
-  /** Kill the guest after this long: a crash (result.killed), not a failure. */
-  killAfterMs?: number;
-  beforeKill?: () => void;
-}
-
-export interface PsCommandResult {
-  exitCode: number;
-  killed: boolean;
-  timedOut: boolean;
-  fault: boolean;
-  error: string | null;
-  elapsedMs: number;
-  threads: PsThreadReport;
-  root: string;
-  poolErrors: string[];
-}
-
-export function runPsCommand(wasm: string | Uint8Array, options?: PsCommandOptions): Promise<PsCommandResult>;
-
-export interface PsNodeInstance {
-  memory: WebAssembly.Memory;
-  root: string;
-  /** Call an export of the instance on its exec thread. */
-  call(fn: string, ...args: number[]): Promise<number>;
-  /** Copy bytes into instance memory (flatsql_ps_alloc); returns the pointer. */
-  write(bytes: Uint8Array | ArrayBuffer): Promise<number>;
-  read(ptr: number, len: number): Promise<Uint8Array>;
-  threads(): PsThreadReport;
-  faulted(): boolean;
-  close(): Promise<void>;
-}
-
-/** flatsql-ps-threads.wasm as one instance (writer or reader) with its own exec thread and thread pool. */
-export function createPsNodeInstance(wasm: string | Uint8Array, options?: PsHostOptions): Promise<PsNodeInstance>;
-
-export function importedMemoryLimits(
-  bytes: Uint8Array | ArrayBuffer,
-): { module: string; name: string; initial: number; maximum?: number; shared: boolean } | null;