@factoidal/core 0.3.0 → 0.4.0

package/bin/pack-host.mjs

@@ -0,0 +1,341 @@
+// Giving `factoidal pack` a call stack big enough to finish, without
+// asking the reader for a runtime flag.
+// https://github.com/danbri/factoidal/issues/649
+//
+// THE DEFECT THIS FILE EXISTS FOR
+// The pack fold in the engine recurses one frame per term in one block's
+// local term index, and that is far deeper than a query recurses per row.
+// On the DEFAULT stack of Node 22 and of Deno 2 the pack of anything
+// above roughly 0.25 MB of Turtle ends with `Maximum call stack size
+// exceeded` -- measured 2026-09-04 against the committed module, where
+// `sequence_variant.ttl` (241,149 B) passes and `chromosome.ttl`
+// (316,116 B) does not. Every one of those inputs packs correctly once
+// the stack is raised, and the generation is byte-identical to
+// `l4block-shard-pack` output. So the defect is the frame budget alone.
+// The depth, what sets it, and why a browser cannot be given more are in
+// `docs/designissues/2026-09-03-npm-pack-in-wasm.md`.
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Start the same pack on a thread or in a child process that has a
+// bigger stack, carry the progress reports back, and re-raise the same
+// error. It reads no RDF, decides no artifact name, and moves no
+// artifact bytes: the worker writes the generation itself, through the
+// same `store-host` primitives, exactly where the artifacts arrive.
+// A reader must not be able to tell that a worker is involved, except
+// that the pack finishes (iron rule 7 of CLAUDE.md).
+//
+// THE TWO ROUTES
+//   Node -- `worker_threads`, with `resourceLimits.stackSizeMb`. The
+//           engine loads INSIDE the worker: a loaded WebAssembly
+//           instance does not cross a thread boundary.
+//   Deno -- `worker_threads` is not the route, and a Deno `Worker` takes
+//           no stack size. The command re-executes itself once with
+//           `--v8-flags=--stack-size=...`, guarded by an environment
+//           variable so it can never loop. Confirmed honoured by
+//           deno 2.9.4 / V8 15.0.245.2 on 2026-09-04:
+//           `deno run -A --v8-flags=--stack-size=8000` packs
+//           `anatomical_structure.ttl` (3,811,378 B) in 13.7 s, where
+//           the same command without the flag overflows.
+//
+// WHAT IT DOES NOT FIX
+// A browser tab has a fixed frame budget and no host flag, so neither
+// route rescues an in-page packer. See the closing section of
+// `docs/designissues/2026-09-03-npm-pack-in-wasm.md`.
+
+import { StoreHostError, listGeneration, readWhole } from '../store-host/index.mjs'
+import { fileUrlToPath, joinPath } from '../store-host/paths.mjs'
+import { loadEngine } from './engine.mjs'
+import { PackError, packFile, packSupported, verifyGeneration } from './pack.mjs'
+import { openStore } from './store.mjs'
+
+const isDeno = typeof globalThis.Deno !== 'undefined'
+
+/**
+ * The worker's stack, in mebibytes.
+ *
+ * MEASURED, 2026-09-04, macOS 15 arm64, Node 22.22.2, against
+ * `examples/wikidata/subsets/lifesci-kgx/data/gene.ttl` -- 17,363,312
+ * bytes, 888,949 triples, the largest input the milestone carries:
+ *
+ *   stackSizeMb  verdict
+ *   4 (default)  Maximum call stack size exceeded
+ *   6            Maximum call stack size exceeded
+ *   7            Maximum call stack size exceeded
+ *   8            pass, 42 s
+ *   10           pass
+ *   64           pass, 68 s
+ *
+ * 8 MiB is therefore the measured minimum, and 64 is eight times it.
+ * The headroom is deliberate and it is cheap: a thread stack is reserved
+ * address space, and only the pages actually touched become resident, so
+ * an unused 56 MiB costs nothing. The depth is set by the number of
+ * terms in ONE block's dictionary, not by the file size, so a file
+ * smaller than gene.ttl but with a wider dictionary needs more, and a
+ * value only just above the measured minimum would move the same defect
+ * to another input.
+ */
+export const WORKER_STACK_MB = 64
+
+/** The V8 stack limit the Deno re-exec asks for, in kibibytes -- the
+ *  unit `--stack-size` takes. Same budget as WORKER_STACK_MB. */
+export const REEXEC_STACK_KB = WORKER_STACK_MB * 1024
+
+/** Set in the re-executed Deno child, so the guard can never loop. */
+export const REEXEC_GUARD = 'FACTOIDAL_PACK_STACK_REEXEC'
+
+/** Read one environment variable, or null where reading it is refused. */
+function environment (name) {
+  try {
+    if (isDeno && globalThis.Deno.env) {
+      const value = globalThis.Deno.env.get(name)
+      return typeof value === 'string' && value.length > 0 ? value : null
+    }
+  } catch (_error) {
+    // Deno without --allow-env. An absent override is the normal case.
+    return null
+  }
+  const value = globalThis.process && globalThis.process.env
+    ? globalThis.process.env[name]
+    : undefined
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+/** The stack the worker asks for: `WORKER_STACK_MB`, or the override in
+ *  FACTOIDAL_PACK_STACK_MB, which exists so the measurement above can be
+ *  repeated without editing this file. */
+export function workerStackMb () {
+  const override = environment('FACTOIDAL_PACK_STACK_MB')
+  if (override === null) return WORKER_STACK_MB
+  const value = Number(override)
+  return Number.isSafeInteger(value) && value > 0 ? value : WORKER_STACK_MB
+}
+
+/** Whether the caller asked for the in-process path. `--no-worker` on the
+ *  command line, or FACTOIDAL_NO_WORKER in the environment. The old
+ *  behaviour stays testable, and a platform where the worker fails has a
+ *  way out. */
+export function workerRefused (options) {
+  if (options && options.worker === false) return true
+  return environment('FACTOIDAL_NO_WORKER') !== null
+}
+
+// ------------------------------------------------- carrying an error back
+//
+// `commandPack` distinguishes a PackError and a StoreHostError from
+// everything else, and prints the engine's own words in each case. A
+// worker boundary must not change any of that, so the failure crosses as
+// a plain description and is rebuilt on the other side.
+
+/** Describe a thrown value so it survives `postMessage`. */
+export function describeError (error) {
+  if (error instanceof PackError) {
+    return {
+      type: 'PackError',
+      message: error.message,
+      handle: error.handle,
+      notWired: error.notWired
+    }
+  }
+  if (error instanceof StoreHostError) {
+    return {
+      type: 'StoreHostError',
+      message: error.message,
+      code: error.code,
+      path: error.path === undefined ? null : error.path
+    }
+  }
+  return {
+    type: 'Error',
+    message: error && error.message ? String(error.message) : String(error)
+  }
+}
+
+/** Rebuild what `describeError` described. */
+export function reviveError (description) {
+  if (description.type === 'PackError') {
+    return new PackError(description.message,
+      { handle: description.handle, notWired: description.notWired })
+  }
+  if (description.type === 'StoreHostError') {
+    const detail = description.path === null ? {} : { path: description.path }
+    return new StoreHostError(description.code, description.message, detail)
+  }
+  return new Error(description.message)
+}
+
+/** Whether a failure is the runtime running out of call stack. */
+export function isStackOverflow (error) {
+  if (error instanceof RangeError) return true
+  const message = error && error.message ? String(error.message) : String(error)
+  return message.indexOf('call stack size exceeded') >= 0
+}
+
+// ------------------------------------------------------ the pack itself
+
+/**
+ * Load the engine and run one deep task, on whatever stack the caller has.
+ *
+ * This is the body both routes run: the worker calls it on its own big
+ * stack, and `--no-worker` calls it in the process it was started in.
+ *
+ * `task.kind` selects the work. Both kinds recurse once per distinct term
+ * in a block's local term index, so both need the raised stack -- the
+ * verification `activate` runs decodes the same blocks the pack encoded.
+ * `activate` overflowed on a 112,742-row generation that `pack` had just
+ * written successfully, which is how the two came to share this path
+ * (measured 2026-09-04, https://github.com/danbri/factoidal/issues/649).
+ *
+ * @returns {{notWired: true}|{report: object}}
+ */
+export async function packHere (task, onProgress) {
+  const engine = await loadEngine()
+  if (!packSupported(engine)) return { notWired: true }
+  if (task.kind === 'activate') {
+    return { report: activateHere(engine, task) }
+  }
+  const report = packFile(engine, task.input, task.output, {
+    syntax: task.syntax,
+    layout: task.layout,
+    base: task.base,
+    onProgress
+  })
+  return { report }
+}
+
+/**
+ * Verify one generation and answer the engine's verdict.
+ *
+ * The host reads the manifest and every artifact and hands them over; the
+ * engine checks each against the digest the manifest commits. Replacing
+ * CURRENT is NOT done here -- it is the caller's step, and it happens on
+ * the main thread only after this returns ok, so a worker that dies
+ * mid-verification can never leave a half-moved pointer.
+ */
+function activateHere (engine, task) {
+  const store = openStore(task.root, task.generation)
+  const files = listGeneration(store.generationDir)
+  const artifacts = files
+    .filter((file) => file.name !== store.manifestName)
+    .map((file) => ({
+      key: file.name,
+      bytes: readWhole(joinPath(store.generationDir, file.name))
+    }))
+  return verifyGeneration(engine, store.manifestHex, artifacts)
+}
+
+/**
+ * Pack on a `worker_threads` thread with a raised stack. Node only.
+ *
+ * The worker writes every artifact itself, so no artifact byte crosses
+ * the thread boundary; what crosses is the task, the progress reports
+ * and the finish envelope.
+ *
+ * @returns {{notWired: true}|{report: object}}
+ * @throws whatever the pack threw, rebuilt
+ */
+async function packInWorker (task, onProgress) {
+  const { Worker } = await import('node:worker_threads')
+  const entry = new URL('./pack-worker.mjs', import.meta.url)
+  const stackSizeMb = workerStackMb()
+  return await new Promise((resolve, reject) => {
+    const worker = new Worker(entry, {
+      workerData: { ...task, progress: typeof onProgress === 'function' },
+      resourceLimits: { stackSizeMb },
+      stdout: false,
+      stderr: false
+    })
+    let settled = false
+    const finish = (act) => {
+      if (settled) return
+      settled = true
+      worker.terminate().then(act, act)
+    }
+    worker.on('message', (message) => {
+      if (message.kind === 'progress') {
+        if (typeof onProgress === 'function') onProgress(message.progress)
+        return
+      }
+      if (message.kind === 'error') {
+        const failure = reviveError(message.error)
+        finish(() => reject(failure))
+        return
+      }
+      finish(() => resolve(message.kind === 'notWired'
+        ? { notWired: true }
+        : { report: message.report }))
+    })
+    worker.on('error', (error) => { finish(() => reject(error)) })
+    worker.on('exit', (code) => {
+      if (settled) return
+      settled = true
+      reject(new PackError(`the pack worker exited with code ${code}`))
+    })
+  })
+}
+
+/**
+ * Run one deep task, on the biggest stack this runtime will give it.
+ *
+ * On Node the worker route is the default. On Deno the caller has
+ * already re-executed (see `denoReexec`), so this runs in process.
+ *
+ * @param {object} task {kind, ...}: a pack takes
+ *   {input, output, syntax, layout, base}, an activate takes
+ *   {root, generation}
+ * @param {(progress: object) => void} [onProgress]
+ * @param {object} [options] {worker: false} forces the in-process path
+ */
+export async function runPack (task, onProgress, options) {
+  if (isDeno || workerRefused(options)) return await packHere(task, onProgress)
+  return await packInWorker(task, onProgress)
+}
+
+// -------------------------------------------------------- the Deno route
+
+/**
+ * Re-execute this command once under Deno with a raised V8 stack.
+ *
+ * Returns null when the re-exec is not available or not wanted, and the
+ * caller then packs in process. Returns the child's exit code when the
+ * child ran, and the caller exits with it. Permissions are NOT
+ * escalated: the child is given exactly the ones this process was
+ * granted, queried rather than requested so no prompt appears.
+ */
+export async function denoReexec (options) {
+  if (!isDeno) return null
+  if (workerRefused(options)) return null
+  if (environment(REEXEC_GUARD) !== null) return null
+  const Deno = globalThis.Deno
+  let granted
+  try {
+    granted = ['read', 'write', 'env', 'run', 'net', 'ffi', 'sys']
+      .filter((name) => Deno.permissions.querySync({ name }).state === 'granted')
+  } catch (_error) {
+    return null
+  }
+  if (granted.indexOf('run') < 0 || granted.indexOf('read') < 0) return null
+  const main = Deno.mainModule.startsWith('file://')
+    ? fileUrlToPath(Deno.mainModule)
+    : Deno.mainModule
+  const args = [
+    'run',
+    ...granted.map((name) => `--allow-${name}`),
+    `--v8-flags=--stack-size=${REEXEC_STACK_KB}`,
+    main,
+    ...Deno.args
+  ]
+  try {
+    const child = new Deno.Command(Deno.execPath(), {
+      args,
+      env: { [REEXEC_GUARD]: '1' },
+      stdin: 'inherit',
+      stdout: 'inherit',
+      stderr: 'inherit'
+    }).outputSync()
+    return child.code
+  } catch (_error) {
+    // No --allow-run at this exact path, or no executable. Pack here and
+    // let the overflow advice speak if the stack runs out.
+    return null
+  }
+}

package/bin/pack-worker.mjs

@@ -0,0 +1,31 @@
+// The thread `factoidal pack` runs on under Node, so that the pack has a
+// call stack big enough to finish.
+// https://github.com/danbri/factoidal/issues/649
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Load the engine, run the same pack the in-process path runs, post the
+// progress reports back, and post the failure back. It reads no RDF,
+// names no artifact and encodes nothing: `pack.mjs` drives the engine
+// and `store-host` writes the bytes, here exactly as they do on the
+// main thread (iron rule 7 of CLAUDE.md).
+//
+// The engine loads HERE, not on the main thread: a loaded WebAssembly
+// instance does not cross a thread boundary. The artifacts are written
+// HERE too, where they arrive, so no artifact byte crosses it either.
+
+import { parentPort, workerData } from 'node:worker_threads'
+import { describeError, packHere } from './pack-host.mjs'
+
+const port = parentPort
+const task = workerData
+
+packHere(task, task.progress
+  ? (progress) => port.postMessage({ kind: 'progress', progress })
+  : undefined)
+  .then((answer) => {
+    if (answer.notWired === true) port.postMessage({ kind: 'notWired' })
+    else port.postMessage({ kind: 'report', report: answer.report })
+  })
+  .catch((error) => {
+    port.postMessage({ kind: 'error', error: describeError(error) })
+  })

package/bin/pack.mjs

@@ -0,0 +1,174 @@
+// Building a Shardborough generation from a JavaScript host, with the
+// Lean engine running as WebAssembly.
+// https://github.com/danbri/factoidal/issues/641 stage 3.
+// Design record: docs/designissues/2026-09-03-npm-pack-in-wasm.md.
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Read the input file in chunks, hand each chunk to the engine, take back
+// whatever artifacts the engine says are ready, and write each one under
+// the name the engine gave it. It decides no artifact name, computes no
+// digest, encodes no block and writes no manifest field. Every one of
+// those is a format decision and it lives in the Lean source (iron rule
+// 7 of CLAUDE.md). A reviewer who finds a magic number, a field offset,
+// a file-name pattern or a hash in this file has found a violation.
+//
+// There is no file I/O inside the wasm module -- libuv is left out of the
+// Emscripten build by design -- so the engine cannot write the generation
+// itself. That is the whole reason this file exists.
+//
+// WHY IT STREAMS
+// wasm32 addresses 4 GiB. The native packer's own second pass is already
+// bounded: it publishes a batch of blocks every 64 input chunks and then
+// drops the triples. This host drives that same fold one chunk at a time
+// and writes each artifact as it appears, so neither side ever holds the
+// whole input or the whole generation.
+
+import { StoreHostError, readChunk, writeNew } from '../store-host/index.mjs'
+import { joinPath } from '../store-host/paths.mjs'
+
+/** The chunk the host feeds per call. The native packer reads 65,536
+ *  bytes at a time; matching it keeps the two folds in step, which is
+ *  what makes the byte-identity gate meaningful. */
+export const FEED_BYTES = 65536
+
+/** An error the pack operations reported, with the engine's own words. */
+export class PackError extends Error {
+  constructor (message, detail = {}) {
+    super(message)
+    this.name = 'PackError'
+    this.handle = detail.handle === undefined ? null : detail.handle
+    this.notWired = detail.notWired === true
+  }
+}
+
+/**
+ * Whether the loaded engine carries the pack operations.
+ *
+ * The engine reports its own operation lists in the `ops` reflection
+ * envelope, so the command asks it rather than guessing from a package
+ * version. An engine built before stage 3 answers a package that has the
+ * subcommand, and this is how that pairing is detected.
+ */
+export function packSupported (engine) {
+  let envelope
+  try {
+    envelope = engine.call('ops', [])
+  } catch (_error) {
+    return false
+  }
+  const named = (list) => Array.isArray(list) && list.indexOf('packBegin') >= 0
+  return named(envelope.ops) || named(envelope.blobOps) || named(envelope.blobIoOps)
+}
+
+/**
+ * Take every artifact the engine has ready and write it into `output`.
+ *
+ * `packNext` answers one artifact per call and reports when the queue is
+ * empty. The bytes come back in the module's out region, raw; nothing on
+ * this path encodes them.
+ *
+ * @returns {{names: string[], bytes: number}} what was written
+ */
+function drain (engine, handle, output) {
+  const names = []
+  let total = 0
+  for (;;) {
+    const answer = engine.callBlobIO('packNext', [handle], new Uint8Array(0))
+    const envelope = answer.envelope
+    if (envelope.done === true) break
+    if (typeof envelope.name !== 'string') {
+      throw new PackError('packNext answered no artifact name', { handle })
+    }
+    writeNew(joinPath(output, envelope.name), answer.bytes)
+    names.push(envelope.name)
+    total += answer.bytes.length
+  }
+  return { names, bytes: total }
+}
+
+/**
+ * Build one immutable generation from one RDF file.
+ *
+ * @param {object} engine the loaded engine
+ * @param {string} input the RDF file to read
+ * @param {string} output the generation directory to fill; it must exist
+ * @param {object} options
+ * @param {string} options.layout `ibk3` or `ibk4`
+ * @param {string} options.syntax `turtle`, `trig` or `nquads`
+ * @param {string} [options.base] the base IRI relative IRIs resolve against;
+ *   the empty string means no base
+ * @param {(progress: object) => void} [options.onProgress]
+ * @returns {object} the engine's own finish envelope, plus what was written
+ */
+export function packFile (engine, input, output, options) {
+  const begun = engine.call('packBegin',
+    [options.syntax, options.layout, typeof options.base === 'string' ? options.base : ''])
+  const handle = begun.handle
+  if (typeof handle !== 'string') {
+    throw new PackError('packBegin answered no handle')
+  }
+  const written = []
+  let bytesWritten = 0
+  let bytesRead = 0
+  try {
+    // The prepass the native packer runs first -- the source digest and
+    // the generated-blank-node prefix -- is the engine's business, so the
+    // host simply feeds the file twice and lets the engine say when it
+    // has moved from one pass to the next.
+    for (let pass = 0; pass < 2; pass += 1) {
+      const passName = pass === 0 ? 'prepass' : 'ingest'
+      let offset = 0
+      for (;;) {
+        const chunk = readChunk(input, offset, FEED_BYTES)
+        if (chunk.length === 0) break
+        offset += chunk.length
+        bytesRead += chunk.length
+        engine.callBlobIO('packFeed', [handle], chunk)
+        const drained = drain(engine, handle, output)
+        written.push(...drained.names)
+        bytesWritten += drained.bytes
+        if (typeof options.onProgress === 'function') {
+          options.onProgress({ pass: passName, bytesRead, artifacts: written.length })
+        }
+      }
+      engine.call('packEndPass', [handle])
+      const drained = drain(engine, handle, output)
+      written.push(...drained.names)
+      bytesWritten += drained.bytes
+    }
+    const finished = engine.call('packFinish', [handle])
+    const last = drain(engine, handle, output)
+    written.push(...last.names)
+    bytesWritten += last.bytes
+    return { ...finished, written, bytesWritten, bytesRead }
+  } finally {
+    try { engine.call('packClose', [handle]) } catch (_error) { /* already gone */ }
+  }
+}
+
+/**
+ * Verify one generation and report the engine's verdict.
+ *
+ * The host reads the manifest and every artifact the engine asks for; the
+ * engine checks each one against the digest the manifest commits and
+ * every cross-artifact relation. Replacing CURRENT is the host's step,
+ * and it happens only on a verdict of ok.
+ */
+export function verifyGeneration (engine, manifestHex, artifacts) {
+  const windows = []
+  let offset = 0
+  for (const artifact of artifacts) {
+    windows.push({ key: artifact.key, offset, len: artifact.bytes.length })
+    offset += artifact.bytes.length
+  }
+  const blob = new Uint8Array(offset)
+  let cursor = 0
+  for (const artifact of artifacts) {
+    blob.set(artifact.bytes, cursor)
+    cursor += artifact.bytes.length
+  }
+  return engine.callBlob('activateVerify',
+    [manifestHex, JSON.stringify(windows)], blob)
+}
+
+export { StoreHostError }

package/bin/store.mjs

@@ -70,6 +70,38 @@ function asStoreError (error) {
   return new StoreOperationError(message)
 }
 
+/**
+ * What to print when the runtime, not the engine, ran out of call stack.
+ *
+ * One copy of this text, used by every command that can hit the frame
+ * budget. `remedy` is the one line that differs: a query can be made
+ * smaller with a LIMIT, a pack cannot.
+ *
+ * The pack path normally never reaches this, because it runs on a worker
+ * thread with a raised stack (`bin/pack-host.mjs`,
+ * https://github.com/danbri/factoidal/issues/649). It is what a reader
+ * sees when the worker route is refused with --no-worker, is unavailable
+ * on their platform, or is not enough.
+ *
+ * @param {string} remedy
+ * @returns {string[]} the lines, in order, for stderr
+ */
+export function stackLimitAdvice (remedy) {
+  return [
+    'The runtime ran out of call stack inside the engine, not the store.',
+    'Some engine paths recurse once per row or per input chunk, and enough',
+    "of them exceed the runtime's default WebAssembly frame budget.",
+    remedy
+  ]
+}
+
+/** The remedies for each command that can run out of frames. */
+export const STACK_REMEDY = {
+  query: 'Raise it with node --stack-size=4000, add a LIMIT, or use Deno.',
+  pack: 'Raise it with node --stack-size=8000, or ' +
+    'deno run --v8-flags=--stack-size=8000.'
+}
+
 /**
  * Open a store and return its manifest bytes.
  *

package/l4-assets/l4factoidal.js

@@ -37,7 +37,7 @@
 // bytes change.
 
 // Stamped by formal/lean4/Wasm/build-wasm.sh step 9 -- do not hand-edit.
-const WASM_VERSION = "9084903e6877";
+const WASM_VERSION = "125d391e0ccc";
 
 import createModule from './l4factoidal.mjs';
 
@@ -187,6 +187,66 @@ export function loadL4() {
         }
       },
 
+      /**
+       * The dispatch ABI, plus ONE byte region IN and ONE byte region
+       * OUT.
+       *
+       * For the ops of `L4Wasm.blobIoOpNames` (the `ops` envelope lists
+       * them under `blobIoOps`), whose RESULT is bytes rather than
+       * text. The bytes leave the module raw — no hex, no base64 — and
+       * are copied out of the wasm heap into a fresh Uint8Array before
+       * the module's buffer is released. The copy is required: the heap
+       * is detached and replaced when the module grows, so a subarray
+       * view of it can go stale between calls.
+       *
+       * Every other op answers as `call` does, with an empty region.
+       *
+       * @param op     the method name, e.g. "blobEcho"
+       * @param args   array of positional STRING arguments
+       * @param blobIn Uint8Array (or ArrayBuffer) carried IN; may be omitted
+       * @returns      { envelope, bytes } — the parsed {"ok":true,...}
+       *               envelope and a Uint8Array of the out region
+       * @throws       if the Lean side reports {"ok":false,"error":...}
+       */
+      callBlobIO(op, args, blobIn) {
+        const bytes = blobIn instanceof Uint8Array
+          ? blobIn
+          : new Uint8Array(blobIn ?? 0);
+        // Two 32-bit out parameters, uint8_t **out_ptr and size_t
+        // *out_len, in one 8-byte cell.
+        const outCell = Module._malloc(8);
+        if (!outCell) throw new Error('l4factoidal: could not allocate the out-parameter cell');
+        const blobPtr = bytes.length > 0 ? Module._malloc(bytes.length) : 0;
+        if (bytes.length > 0 && !blobPtr) {
+          Module._free(outCell);
+          throw new Error('l4factoidal: could not allocate a WASM blob buffer');
+        }
+        let outPtr = 0;
+        try {
+          Module.setValue(outCell, 0, 'i32');
+          Module.setValue(outCell + 4, 0, 'i32');
+          if (bytes.length > 0) Module.HEAPU8.set(bytes, blobPtr);
+          const resultPtr = callWithHeapStrings(
+            (opPtr, argsPtr) => Module._l4_call_blob_io_c(
+              opPtr, argsPtr, blobPtr, bytes.length, outCell, outCell + 4),
+            [op, JSON.stringify(args)]);
+          outPtr = Module.getValue(outCell, 'i32') >>> 0;
+          const outLen = Module.getValue(outCell + 4, 'i32') >>> 0;
+          const envelope = JSON.parse(take(resultPtr));
+          if (envelope.ok === false) throw new Error(`l4factoidal: ${envelope.error}`);
+          // slice() copies; HEAPU8 is replaced wholesale when the
+          // module's memory grows, so a view would not survive.
+          const region = outPtr !== 0 && outLen > 0
+            ? Module.HEAPU8.slice(outPtr, outPtr + outLen)
+            : new Uint8Array(0);
+          return { envelope, bytes: region };
+        } finally {
+          if (outPtr) Module._l4_free_blob(outPtr);
+          if (blobPtr) Module._free(blobPtr);
+          Module._free(outCell);
+        }
+      },
+
       /** Escape hatch for tests: the raw Emscripten module. */
       _module: Module,
     };