Make coverage report the islands a build runs, and warn when a build ships a reachable refusal

What was wrong

A build and a coverage report disagreed about Node islands by construction, in both directions (measured on 714482d49).

• Report says island, build says native. Coverage listed every package with any reason to need Node as a "would-be" island. A build keeps a package native unless it was refused before lowering, holds a refusal in its own module, or carries a runtime fence that surely fires. For uuid, date-fns, hono, commander and zod the report said island, the build said native with deferred throws, and the build printed nothing about them.
• Report says blocker, build succeeds. Coverage kept the SC2013 of a refused package the build runs in an island (yargs: success: false for a program that builds), did not make the failed-build retry (lodash: SC1090 on a use the build resolves through the island), checked preflight on the first load rather than the island reload, and never islanded a program module.
• On pi the report named 34 islands and 72 reached errors where the build runs 14 islands and reports 66.

What changes

One decision. The functions that decide a build's islands move from executable/prepare.ts to node-islands/decide.ts, and frontend/analysis.ts runs them in the build's order, round by round: the first-load decision (packages and modules), the refusals a load still has to place, the preflight rule, the lowering, and growth.ts's rules over what the lowering saw, including the one retry a failed lowering gets from the packages' island classes. The report names the set the last round lowered with (mode: "build"), with the build's class and reason. A package that stays native keeps its first reason in the report, so nothing the old list showed is lost. Coverage no longer seeds its set from the module graph alone, because a build does not; decideNodeIslands is the place to do that for both.

No fallback. When a build moves a package into an island for its fences and the island build fails, the build fails with that build's errors and SC8023, which names the packages and --npm-static as the way to keep them native. It no longer returns to the native build with a warning.

Nothing silent.

• A package a build keeps native with fences the program can reach gets an SC6006 warning, one per package: npm package 'uuid' compiles with an operation the program can reach that does not compile: it throws when the program reaches it (first SC2020: 'unescape' …). It is in the divergence band, so coverage --fail-on=divergences gates on it. A package named in --npm-static asked for its fences and is not reported.
• Coverage no longer calls a program with reachable deferred sites "fully static".
• Where the policy forbids an island the fence rule asks for (--node-islands=off or explicit, --native=<pkg>), the build fails with SC8002 or SC8003 instead of shipping the throw, as the SC8001 note's hint already said.

The fence rule is one predicate and does not change. fenceIslandsPackage in growth.ts answers what main answers: a fence in module code, or one that needs the runtime itself. Answering true for every reached fence is the intended rule and is one change there. It waits because of what running five such packages in Node does today:

All three boundary failures come from builds that succeed, and an island needs a libnode pack. The repros are in FOLLOWUPS (2026-11-07, build-island-policy).

The Node islands docs page (#3131)

Of the limits that page lists, this change removes or changes three:

• Coverage reports: the section no longer lists a package a build compiles natively; it lists the build's islands, and a native package keeps its first reason on its own line.
• Keeping a package native: --native=<pkg> and --node-islands=off fail the build with SC8003 or SC8002 for a package the default would have run in an island (measured with ejs 7.0.2, which on main builds and dies at start-up with SC1090). A package whose refusals sit only inside function bodies still builds, with SC6006.
• Values across the boundary: an SC8010 on an automatically chosen island stops the build, with SC8023 naming the package; it no longer falls back to the native compilation with a warning (measured with the page's WeakMap example).

Unchanged: command-line arguments, island objects in native APIs, the libnode pack, platforms, start-up and memory, worker threads, your own modules.

Also found, not fixed here

mustache 4.2.0 compiles natively and renders "". It has no deferred site: it is a miscompile in the JavaScript tier that reproduces in eleven lines without a package (FOLLOWUPS 2026-11-07, r11.mjs): a variable a function assigns is lowered as the literal undefined when passed to a method of a constructor-function instance. After this change coverage shows mustache as native with object-model: R2.1 constructor functions, as the build has it.

Order with other work

• #2881 also rewrites executable/prepare.ts. This lands after it; the conflict is the round structure in prepareExecutableModule, and the rules themselves live in node-islands/decide.ts and growth.ts.
• The retry a failed lowering gets from the packages' island classes is unchanged here and sits in one place (growFromClasses and the explain flag of growIslandSet, with one call site in the build and one in coverage). Its removal is separate work (island-decide-once slices 5 and 6); because coverage runs the same function, removing it there removes it from both.

Evidence

• packages/compiler/src/node-islands/growth.test.ts: SC6006 per package, --npm-static, the refusals under off, explicit and --native.
• tests/harness/node-island.test.ts: a fence in module code islands its package and is refused by name where the policy forbids it; a function-body fence stays native with SC6006.
• tests/harness/coverage.test.ts and its four snapshots: the report names the build's islands; a program whose refused package the build islands has no blocker.
• Coverage against an IR build over the 94 corpus programs that need a libnode pack and the 182 npm cases: the same island set and the same verdict for all 276. On main 96 differ, 30 on the verdict and 66 on the set. tests/harness/node-island.test.ts keeps seven of them as a test, one per way a set is decided.
• pi (packages/coding-agent/src/cli.ts, the usual --npm-static list): the report's 15 islands and 2 modules are the build's, and its 64 blocker sites are the build's 64 error sites. On main the report has 34 islands against the build's 14, and 70 sites against 64.
• An internal error in the native compilation of a package the fence rule moves into an island no longer fails the build: underscore 1.13.8 is two SC9001 on main and matches Node here.

Cost

Measured in one sandbox (32 vCPU, Intel Xeon @ 2.90GHz), base 714482d49, other jobs running beside both sides.

• pi build: 863.4 s to 866.7 s, three rounds both, the same 66 errors line for line. Its island set goes from 14 to 15: @stablelib/base64 has a fence in module code, and a failed lowering now applies the fence rule in the same round as its diagnostics, where main applied it only after a lowering that succeeded.
• pi coverage: 739 s to 1,041 s. It now makes the build's three rounds; main made two lowerings and reported a different program. The unreached remainder costs 8 to 17 s per round, so the time is the rounds. Deciding the set before lowering (node-islands/decide.ts is the one place now) shortens both.
• Coverage of programs without packages: 300 corpus programs in 40.3 s and 40.7 s against 39.9 s and 40.4 s on main.

Validation

Run against base 4bd24a1cd; the branch was then rebased onto 2fb13a01f without conflicts.

• Zero-cost gate, --gate-corpus=all: PASS. 5,183 programs identical, none differ; 96 fail to build on both sides (they need a libnode pack, and the gate has none). Bench geomean -0.06%, self -0.01%, fixtures -0.20%. The candidate compiles its own source.
• Lanes, plain and sanitized, with a libnode pack, both native bootstraps included: plain 21,532 passed, sanitized 18,305 passed, 3 failed in each. Two test groups pinned what this change replaces and are updated in a later commit (rerun: pass). The third, packages/runtime/test/regex.test.ts, is a 60 s hook timeout under lane load; it passes on main and on this branch when run alone.
• After the rebase: workspace build, lint, format, the docs gate, and 160 island, npm and coverage tests pass.
• The last commit answers two review findings in the report (a package only an automatically islanded module imports is inside that island; a report that has only native packages' reasons is kept), with unit tests in node-islands/report.test.ts; tests/harness/coverage.test.ts and the island unit tests pass with it.

🤖 Generated with Claude Code