Skip to content

feat: FFI instances, and napi instances on service threads beside wasm modules - #25698

Draft
charlielye wants to merge 8 commits into
cl/avm-host-callfrom
cl/ffi-instances
Draft

charlielye wants to merge 8 commits into
cl/avm-host-callfrom
cl/ffi-instances

Conversation

@charlielye

@charlielye charlielye commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #25695 (host calls, the TXE on wsdb-ref and the AVM's wasm module), the top of stack #25863. This PR is the eight commits on top.

Why

A process or a wasm module is an instance of its service: the TXE runs one AVM and one world state per session, side by side. A service loaded in-process through napi was not. A library is loaded once per process, and the FFI entry kept one context per library, so every napi backend in a process shared one service, and its calls ran on the libuv pool where nothing chose the thread. This PR makes instances part of the FFI contract and runs napi instances where wasm modules run, so IPC, wasm and napi are three transports for the same model: a backend is an instance of the service, and you choose the thread it runs on.

Since the stack moved napi onto plain shared libraries loaded by ipc-runtime's one Node-API addon (#25861), this PR no longer generates an addon per service. The instances and the host calls live in ipc-runtime's FfiLibrary, and a service ships only a .so.

What changes

The FFI contract: instances, and a host-call setter

  • Next to <svc>_ipc_ffi_entry, every generated FFI server exports <svc>_ipc_ffi_create, _call(instance, …) and _destroy. An instance is what a connection is over a transport: a context of its own. Calls on one instance must not overlap; calls on different instances may run concurrently, on any threads. SCHEMA_SPEC.md says so.
  • _entry is _call on one instance of the process, made on first use. Callers that only know _entry (bb.js's wasm, the generated client backends) see no change, and schemas and the wire format don't change.
  • C++: a service defines ipc_ffi_create_instance() in place of ipc_ffi_dispatcher(), usually return std::make_unique<FfiContext<Ctx>>();. bb, bb-avm-sim, wsdb-ref and the echo example do. A service that doesn't fails to link.
  • Rust (export_<svc>_ffi!) and Zig (exportFfi()): each instance is a Default (.{}) handler of the given type.
  • Native C++ libraries also export <svc>_ipc_ffi_set_host_call(fn). fn has the wasm import's signature (ipc_runtime_host_call(target, request, &response), the answer in a buffer from _alloc). The native ipc_runtime_host_call in ipc_codegen/host_call_backend.hpp forwards to it, and still answers with an error until one is set.

ipc-runtime's FfiLibrary: instances, with host calls answered in JS

  • FfiLibrary gains hasInstances(), createInstance(), callInstance(instance, bytes, hostCall?) and destroyInstance(instance). loadNapiFfiLibrary exposes them on NapiFfiLibrary.
  • When it loads a library, it hands the library one host-call function. That function answers through the hostCall of the callInstance in progress on its thread (a thread-local scope), on the same thread, allocating the answer with that library's _alloc. So a napi instance reaches its host's services the way a wasm module does.
  • An instance called again from inside one of its own host calls refuses with an error rather than re-entering.
  • call/callAsync stay, over the process instance, for libraries without instances.

ipc-runtime: ServiceThread hosts wasm modules and napi instances

  • WasmWorker from feat: host_call for wasm modules; Simulate in bb-avm-sim's wasm module; the TXE in memory on wsdb-ref #25695 is now ServiceThread (createServiceThread()). A slot on it holds a wasm module or a library instance ({ napi: { libraryPath, ffiName } }). A target on the same thread is called directly; anything else is answered on the owner's thread.
  • How an instance waits for the owner's answer depends on what it is. A wasm module is suspended by JSPI and the answer comes back by message, as in feat: host_call for wasm modules; Simulate in bb-avm-sim's wasm module; the TXE in memory on wsdb-ref #25695. A napi instance makes its host calls from a native stack, which JSPI can't suspend, so its thread blocks on a shared buffer (Atomics.wait) until the answer arrives; napi is node-only, and node always has shared buffers. For the same reason a napi instance's siblings must answer it synchronously: a wasm module that itself waits on its host fails such a call with a message saying so.
  • NapiFfiBackend.instance({ libraryPath, ffiName, worker, hostCall }) puts an instance on a thread (its own by default). NapiFfiBackendSync.instance({ libraryPath, ffiName, hostCall }) runs one on the calling thread.
  • Generated packages take the same worker and hostCall options for napi as for wasm. They use instances when the library has them and fall back to the process instance otherwise.
const thread = createServiceThread();
const wsdb = await WsdbService.create({ backend: 'napi', napi: { worker: thread } });
const avm = await AvmService.create({ backend: 'napi', napi: { worker: thread, hostCall: { wsdb, cdb } } });

Mixing works too: a napi AVM beside a wasm wsdb-ref, or the reverse. Parallelism comes from more threads, as it comes from more processes over IPC.

bb-avm-sim: a shared library

  • libbb_avm_sim.so is built like libwsdb_ref.so: the FFI objects as a plain shared library exporting only avm_ipc_ffi_*, built by the native and the four cross presets, and shipped in the arch packages beside the binary through --package-native. The package's transports are now uds,napi,wasm.

TXE (labs patch 0005)

  • TXE_WORLD_STATE=napi runs each session's wsdb-ref and AVM as library instances on the session's thread, in place of wasm modules. Wasm stays the default.

Testing

On this head, node 26:

  • bb-avm-sim package tests 10/10, through libbb_avm_sim.so and ipc-runtime's addon. The three napi ones:
    • wsdb-ref and the AVM on one thread in all four napi/wasm combinations give the same result.
    • Four napi sessions on their own threads at once all match it.
    • On the calling thread, two napi wsdb-ref instances don't share state, and an AVM whose cdb handler calls back into the same AVM fails with "in progress".
  • wsdb_ref_test.sh 5/5 on process-uds, process-shm, napi and wasm.
  • ipc-runtime: C++ 39/39, TS 64/64, Rust passing.
  • ipc-codegen echo: the golden tests in all four languages, the C++ and Zig FFI tests, and the echo package on uds, shm and wasm.
  • labs-patches/bootstrap.sh check: the series applies, and make labs-yarn-project builds with patch 0005 (the TXE type-checks against these packages). The TXE suite was not run on this head.

Before this PR moved onto FfiLibrary, with a generated addon per service, the same model passed the TXE suite with TXE_WORLD_STATE=napi (48/48 chunks, at about wasm's speed: the TXE's time is not in AVM or world-state compute), and 8 threads × 25 simulations matched the reference, three times. Neither has been rerun on this head.

Not run: TSan on vm2. A read of vm2's statics found only ones set once and then read, which with the stress runs above is evidence, not proof, that instances in one process are safe. libbb_avm_sim.so was not built for macOS locally.

Not done

🤖 Generated with Claude Code

https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb

charlielye and others added 8 commits November 14, 2026 20:08
…fiLibrary with host calls answered in JS

The C++ FFI server exports <svc>_ipc_ffi_create/_call/_destroy beside _entry, and natively
<svc>_ipc_ffi_set_host_call, which hands the library the function its ipc_runtime_host_call
forwards to. ipc-runtime's FfiLibrary sets that function when it loads a library, and gains
createInstance/callInstance(instance, input, hostCall?)/destroyInstance, so a service's host
calls are answered by the JS function passed with each call, on the calling thread.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
A WasmWorker slot now holds a wasm module's main instance or an instance of a service's
shared library, with the same host-call routing: a target on the same worker is a
synchronous call whichever kind either side is, and anything else is answered on the
owning thread. NapiFfiBackend.instance puts a library instance on a worker, of its own or a
shared one; NapiFfiBackendSync.instance keeps one on the calling thread. Each backend gets
state of its own. Generated packages use instances when their library has them, with
worker and hostCall options like wasm's, and fall back to the process's one instance for
older libraries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
…ts napi instances too

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
…s napi transport

libbb_avm_sim.so, built like libwsdb_ref.so, joins the binary and the wasm module:
@aztec-foundation/bb-avm-sim generates uds,napi,wasm and ships the library in its arch
packages, and the native and cross presets build it. ipc-runtime's addon loads it and sets
its host-call function, so its wsdb and cdb host calls are answered in JS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
All four placements of wsdb-ref and the AVM on one thread (napi or wasm each) give the
same result, four sessions on their own threads at once match it, and on the calling
thread one instance's state is not another's and a host call back into the instance it
came from is refused. Each wsdb-ref service is sent Init first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
…stances of their shared libraries

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci-draft Run CI on draft PRs.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant