Keep a build's Node island decision in a file and replay it

What

scriptc build|run … --node-island-decision=<file> keeps the Node island decision a build reaches in a file, and a later build of the same entry starts from it.

A build decides its islands in rounds: it lowers the whole program, islands the packages and modules whose lowering refused, loads again with their declarations and lowers again, until a round adds nothing. Only the last round's result is the build's. On a large program the earlier rounds are most of the build, and between two builds of the same program their answer rarely changes.

The file holds the islands the last round started from: the island packages with their class and first reason, and the island modules. Those are already parameters of prepareExecutableModule (lowerIslands, lowerModules), so a build that finds the file starts its first round where the recording build's last round started. Nothing else about the round changes:

• The first decision (refused, marked and patched packages) is made from the load as always.
• The lowering's own refusals and the fence rules judge the program as it is now, so a program that needs another island (a new import that refuses, a new dependency with a fence that surely fires) gets it by one more round, and the file then holds the grown set.
• An entry whose package directory or module file is gone, whose version changed, or that the policy now keeps native or unloaded is dropped and decided again. A file recorded for another entry, island policy, --npm-static request or target platform is not replayed.
• An island the program no longer needs stays until the file is deleted. Finding that out would take the native lowering the file saves; the package keeps running in Node, correctly.

Without the option nothing is read or written and no round changes.

Why

On a large multi-package program (three island rounds, 14 island packages) the build lowers 6,975, then 5,440, then 4,790 reachable functions to report the third round's result. Measured in 32 vCPU sandboxes, one build at a time, each pair in one sandbox:

A replayed build is 3.0 to 3.6 times faster than the build that decides from scratch on the same machine, and reports the same 544 lines. The recorded file holds the 13 packages the rounds grew, and every replay left it byte for byte as the recording build wrote it.

The measurements behind the choice of this mechanism over a decision made before lowering (the set depends on refusals in function bodies and on whether the whole program fails; a marker-based predictor would move packages that compile natively today into Node in 49 corpus programs) are in the design note this PR implements the first slice of.

How

• node-islands/decision-file.ts: the file's format, its key, the read (with per-entry validation) and the write (same decision, same bytes; written through a rename).
• executable/prepare.ts: prepareExecutableBuild reads the file, calls prepareExecutableModule with the recorded state, and writes back the state of the round whose result it returns. Each round that returns a result of its own reports the state it started from (onDecided); a round that retries leaves that to the retry.
• index.ts, native/prepare.ts: both compile paths call prepareExecutableBuild. The executable cache key and the native frontend cache key take the file's digest; the native executable cache is bypassed with the option, as it is for a profile.
• cli/usage.ts, cli/command.ts, packages/cli/src/bootstrap.ts: the option, for build and run.

This touches the round entry point that #2881 restructures. The two compose: in #2881's loop the state to record is its request.

Proof

• A replay ends where a build from scratch ends (packages/compiler/test/island-decision-replay.test.ts): for a fence-report island, a lowering-refusal island and a sure-fence island, the build from scratch takes two rounds and the replayed build one, with the same serialized IR, warnings and island list; a failing build's replay reports the same diagnostics from one round; a record that misses an island is grown by a round and written back; a dependency added after the record gets the island a build from scratch gives it; a recorded package whose version changed is decided again; a program without islands records an empty decision and builds as before.
• Command line (packages/cli/test/node-island-decision.test.ts): the same LLVM text and the same SC8001 notes from scratch, while recording and on replay, with one frontend-load instead of two; an executable is cached by the file's bytes; coverage refuses the option.
• File (node-islands/decision-file.test.ts): round trip, relative paths, key mismatches, dropped entries, unreadable files, the digest.
• Zero cost: the zero-cost gate over the whole corpus (--gate-corpus=all), this head 0d30b3d11 against its base 7954cf5d4, passes: 5,178 programs identical (IR, LLVM and release executables), 96 fail on both sides, 0 differ, 0 runtime-only. Compile time within tolerance: benchmarks +0.01 % [95 % CI −0.77 %, +0.94 %], the compiler compiling itself +0.76 % [−0.09 %, +1.04 %], fixtures −0.00 % [−0.29 %, +0.28 %].
• Native bootstraps: tests/harness/self-hosting-native-driver.test.ts and tests/harness/self-hosting-llvm-emitter.test.ts pass on this head (3 tests), and pass under SCRIPTC_SAN=1 on the first commit's diff (3 tests); the second commit removes one recorded field.
• pnpm lint, pnpm format:check: clean.

🤖 Generated with Claude Code