/jco

Running Wado on Node via jco

jco (bytecodealliance) transpiles a Wasm component into JS + core Wasm so it runs on a plain Wasm engine (V8/Node, browsers) instead of a Component Model runtime. Wado targets WASI P3; this doc covers what the released jco does for Wado today and what is still blocked.

TL;DR

• Use the released npm jco as a library (scripts/jco, mise run jco-*).
• Compile Wado with -f no-wide-arithmetic — V8 has no wide-arithmetic proposal, and float formatting / i128 emit it.
• Run on Node 26+ — stable JSPI, no flag.
• Compute programs work (including float formatting). Filesystem programs run to completion; reading through a preopen is unverified (see below).
• Quick check: mise run jco-hello-released. Benchmark: mise run jco-bench <program.wado>.

Environment

• Node 26+ required. Node 26 (V8 14.6) ships stable JSPI (WebAssembly.Suspending), so no flag is needed; the repo pins node = "26" in mise.toml. Node 24 needs --experimental-wasm-jspi; Node 22's older JSPI fails (WebAssembly.Suspending is not a constructor).
• /tmp pitfall: outside the repo, node may resolve to a system Node 22 (mise activation is path-scoped). Run inside the repo, or use the pinned binary's absolute path.
• V8 has no wide-arithmetic in any version (no flag exists). This is a V8 gap, not a jco one — handled by -f no-wide-arithmetic (see below).

Vendor-free pipeline (scripts/jco)

Released @bytecodealliance/jco as a library. transpile-released.mjs is a plain transpile() — jco's own preview3-shim serves every import a Wado program makes, and the output links to it through a node_modules symlink the script writes beside the files.

The shim flushes stdout after run() resolves, so a runner that calls process.exit on that promise loses the output. Let the event loop drain.

mise tasks:

mise run jco-deps                       # npm install released jco under scripts/jco
mise run jco-transpile-released foo.wasm [out-dir]
mise run jco-hello-released             # compile + transpile + run hello on Node
mise run jco-bench <program.wado> [runs] # compile -f no-wide-arithmetic, transpile, self-time

Released jco status (verified at 1.30.0)

wide-arithmetic (-f no-wide-arithmetic)

Wado emits the Wasm wide-arithmetic proposal (i64.mul_wide_u/s, i64.add128, i64.sub128) for float formatting (core:prelude/fpfmt.wado) and i128. No V8 implements it (checked through Node 26; no flag, --wasm-staging no help), so any component containing those opcodes fails WebAssembly.compile with invalid numeric opcode: 0xfc16.

-f no-wide-arithmetic lowers them to plain 32-bit-limb i64 sequences in wado-compiler/src/codegen/emit/wide_arith_downlevel.rs (delete that file once V8 ships the proposal). The WIR still shows the wide ops; only the final Wasm changes. Compile every Node-bound Wado program with this flag — a bare println of a float needs it.

WASI shims

BA ships a preview3-shim implementing P3 cli / clocks / filesystem / http, with a browser build beside the Node one. A plain jco transpile wires it, and stdout, float formatting, wasi:random, MonotonicClock and an HTTP handle all run through it unaided. Its browser cli is unimplemented (throw new Todo()), which is why the playground keeps a hand-written one.

A hand-written clock is where precision goes missing: system-clock.now is an instant carrying sub-second nanoseconds, and get-resolution a bare duration.

Benchmarking on Node

mise run jco-bench <program.wado> [runs] compiles with -f no-wide-arithmetic, transpiles via the released pipeline, and runs the program self-timed runs times (default 3; keep the best). The benchmark programs already self-time via core:benchmark + MonotonicClock and print their own throughput line, so no host timing is needed.

mise run jco-bench benchmark/mandelbrot/mandelbrot.wado

Works today (compute-only — Stdout + MonotonicClock):

Compute throughput on V8 lands within ~5–10% of wasmtime (sieve is much faster on V8). Numbers are indicative on a noisy cloud VM; keep best-of-3.

Unported (the other benchmarks — Preopens / wasi:filesystem): zlib, json-{twitter,canada,catalog}, sqlite-parse, syntax-highlight, cbor. They read input data from preopened files, which the pipeline does not set. The data load sits outside the timed loop, so wiring preopens runs these unchanged.

Known blockers (jco / V8 gaps)

wide-arithmetic (V8)

Not jco. Handled by -f no-wide-arithmetic.

Filesystem reads (jco)

A file-reading program no longer hangs — example/cat.wado runs to completion against preview3-shim. What it reads is unconfirmed: the shim needs its preopens set (_setPreopens in filesystem/descriptor.js), and the benchmarks that load data from a preopen are still unported.

Reusing an instance (jco)

An instance serves a couple of calls, then the next suspends on a stream read whose host injection is never driven (JCO_DEBUG=1 ends at [StreamEnd#copy()] blocked). cloudflare-worker/ builds one per request.

Debugging jco runtime errors

Transpiled output is one large JS file. Useful canonical-builtin → JS mappings:

Techniques

• Catch swallowed errors — jco's async machinery loses errors as unhandled rejections:

  process.on('unhandledRejection', e => { console.error('UNHANDLED:', e); process.exit(1); });

• JCO_DEBUG=1 node run.mjs — verbose trace of every instruction/trampoline. A trailing [ComponentAsyncState#suspendTask()] with no progress = a rendezvous deadlock.

• Inject logging by string-replacing a function header in the transpiled JS (e.g. add console.error(...) to streamRead/generatedStreamHostInject).

• Timeout hangs: timeout 12 node run.mjs so a deadlock doesn't wedge.

Common error patterns