[cramforce]

First half of scope-B milestone NI-1 (Node islands): the runtime loads Node.js into the scriptc process the first time a program calls into it, from a prebuilt libnode pack. The second half, the @scriptc/node call API and its tests, is the stacked PR on top of this one.

What changes

• scr_node_island.c (new optional runtime unit) dlopens the bridge library of a libnode pack on the first call, with RTLD_NOW | RTLD_GLOBAL. It checks the bridge ABI and that the bridge links exactly the Node version recorded at build time, starts one Node environment and runs the embedded bootstrap (scr_node_island_host.cjs, embedded as scr_node_island_host.h by scripts/node-island-host.mjs). A run that never calls into Node never maps libnode.
• scr_node_bridge.h is the C ABI between the runtime and the bridge. The runtime includes no Node or V8 header.
• The bridge (packages/libnode-common/bridge/scr_node_bridge.cc) is built against one exact Node release and ships next to libnode in its pack. It:
  • initializes Node once, without default signal handling, the debug-signal handler, the inspector or stdio reinitialization, and with one platform worker thread;
  • creates the environment from Node's built-in snapshot;
  • routes Node's process exit (process.exit, uncaught exceptions) to scriptc's exit sequence;
  • promotes libnode to the global scope so native addons resolve napi_*;
  • runs each call in a CallbackScope with a nested TryCatch.
• build-pack.mjs assembles a pack (libnode, the bridge, manifest.json, Node's license) from a Node --shared build and the matching headers. Published @scriptc/libnode-<platform> packs are milestone NI-13. Until then a pack is found through SCRIPTC_LIBNODE or --libnode.
• The SCR_NODE_ISLANDS build of scr_async.c adds one loop slot. Until NI-3 moves scriptc's queues onto Node's libuv, scriptc's loop drives Node's through this slot: the program stays alive while Node has ref'd work, the loop sleeps on Node's backend fd up to Node's next timer, and each loop turn runs one non-blocking turn of Node's loop.
• Compiler plumbing:
  • the nodeIsland runtime feature: rule, link features, unit table, pack matrix row and the scr_async.c variant;
  • the nodeIsland.call and nodeIsland.callSync libCalls;
  • scr_node_island_install(pack, version) in main;
  • node-islands/libnode.ts, which records the pack: --libnode=<pack dir>|beside, or SCRIPTC_LIBNODE at build time. It reports SC8005 when no pack is usable and requires Node >= 24.13.1.
• Zero-cost enforcement: the zero-cost gate and the bench nm test now require that no good-code executable defines a Node island symbol.

Locating Node, and bundling it

SCRIPTC_LIBNODE overrides the recorded pack directory at run time. A recorded path that starts with $ORIGIN/ resolves against the directory of the running executable. PATH is never searched, and a pack of another Node version or bridge ABI is a fatal error at first use, never a silent fallback.

--libnode=beside copies the pack next to the executable as <output>.libnode/ and records $ORIGIN/<output>.libnode, so the program and its Node travel together. This is the first form of shipping Node with the program, which the maintainer asked the design to support. The $ORIGIN hook is also what the default embedded packaging (NI-4) will use: the pack's compressed libnode and bridge are appended to the executable and extracted on first use to $XDG_CACHE_HOME/scriptc/node-islands/<hash>/, recorded as a cache-relative path. The same pack serves as the in-process backend, as the bundled Node, and as the build-time probe environment (DESIGN §2.13, §2.16.4). No node executable is ever shipped or required.

Zero cost

Programs without a nodeIsland.* libCall are unchanged:

• no new unit is linked;
• the plain scr_async.c object is selected (the variant code is entirely under #ifdef SCR_NODE_ISLANDS, so the default object is byte-identical);
• main gains no line.

Zero-cost gate (scripts/zero-cost-gate.mjs --set=bench,self,corpus --corpus=all --timing-runs=3, Linux Vercel Sandbox, baseline 0237d70df): 3541 of 3542 programs produced byte-identical IR, LLVM and release executables. In the remaining program, corpus/fs-extra-package, the LLVM and the executable are identical. Its IR differs only in source locations inside the fs-extra shim (packages/compiler/shims/fs-extra), which record each checkout's absolute path (/vercel/sandbox/prev/... against /vercel/sandbox/cand/...). That difference comes from the gate setup, not from this change. Compile time: bench geomean −0.68% [95% CI −2.06%, +0.99%]; the self-hosted compiler +0.27%. Both are within tolerance. The bench nm test passes, and no executable links a Node island symbol.

Tests

• Unit tests: pack recording (libnode.test.ts) and the host header's freshness (node-island-host.test.ts).
• End-to-end evidence is in the stacked PR, which adds the API: differential corpus programs against Node 24 run as binaries that load libnode (plain and sanitized lanes), plus harness tests for loading on first use, beside packaging, a missing pack, mismatched versions, and the executable's symbols.

Not yet covered: macOS has no libnode pack yet (NI-13). Process-state integration, signal routing and the hosted loop are NI-3.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
scriptc	Ready	Preview, v0	Oct 22, 2026 12:31pm UTC

[vercel-security-reviewer]

Security review details