@nubjs/nub-linux-arm64 0.0.31 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubjs/nub-linux-arm64",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "description": "Nub binary for linux-arm64",
   "license": "MIT",
   "repository": "https://github.com/nubjs/nub",

package/runtime/floor-builtin.mjs

@@ -0,0 +1,57 @@
+// Compat-tier floor bootstrap: threads `node:module`'s `createRequire` into the
+// modules that fetch their `node:` builtins via `process.getBuiltinModule`
+// (transform-core.mjs, worker-polyfill.mjs) on the narrow FLOOR where that API is
+// absent — WITHOUT any globalThis surface.
+//
+// WHY those modules can't fetch the builtin themselves: both are loaded on the fast
+// tier via Node's `require(esm)`, which instantiates an ES module by walking its
+// STATIC IMPORT graph through whatever ESM loader chain is registered — including the
+// USER's `--experimental-loader` / `module.register` hooks. A static `import {
+// createRequire } from "node:module"` in either file therefore routed the builtin
+// through the user chain, and a user resolve/load hook that rejects or rewrites
+// `node:module` exploded nub's own load (observed against es-module/test-esm-example-
+// loader and the loader-chaining corpus). So they fetch builtins via
+// `process.getBuiltinModule` (synchronous, OFF the loader chain, no static import).
+//
+// `process.getBuiltinModule` only exists from Node 22.3 / 20.16 / 18.20.4. On the
+// narrow FLOOR below that (18.19.x, 20.11–20.15, 22.0–22.2) it is `undefined`, so the
+// floor needs another way to reach `node:module`'s `createRequire`. This file is that
+// fallback: it holds the LONE static `import { createRequire } from "node:module"`
+// and hands the value to transform-core / worker-polyfill through their module-scoped
+// SETTERS (no globalThis surface — a `globalThis.__nub*` sentinel is the same brand
+// leak as a NUB_* env var, enumerable in user code AND worker realms, so it is
+// forbidden; this threading honors the same enumeration-invisibility contract every
+// other nub polyfill keeps).
+//
+// WHY THIS IS LEAK-SAFE WHERE the static import in transform-core/worker-polyfill WAS
+// NOT: this module is imported ONLY by the compat-tier entries (preload.mjs and
+// preload-async-hooks.mjs), AHEAD of transform-core/worker-polyfill in their source
+// order. The FAST tier (preload.cjs) loads those via `require(esm)` directly and never
+// touches preload.mjs / preload-async-hooks.mjs — so this file's static `node:module`
+// import never enters the fast-tier `require(esm)` graph, and the user loader chain
+// can never observe it. On the compat tier the loader hooks run in nub's OWN worker
+// (preload-async-hooks) or on the main thread before any user `--loader` could
+// intercept a bare `node:` builtin, both off the user chain — so the static import is
+// harmless exactly where it's reachable.
+//
+// IMPORT ORDERING (load-bearing): the compat entries import this file BEFORE
+// transform-core/worker-polyfill, but ES modules evaluate the importEE before the
+// importer's body — so transform-core's body has ALREADY run by the time the setter
+// calls below fire (during THIS module's evaluation). That is fine: transform-core
+// acquires its floor builtins lazily and `setBootstrapCreateRequire` triggers that
+// acquisition immediately, so every binding is ready before the entry body and long
+// before any hook fires. On Node WITH getBuiltinModule this file is a near no-op (the
+// setters are called but those modules never consult `_bootstrapCreateRequire`).
+import { createRequire } from "node:module";
+import { setBootstrapCreateRequire as setTransformCoreCreateRequire } from "./transform-core.mjs";
+
+// The floor's `createRequire`, exported so the compat entries (and any future floor
+// consumer) can thread it elsewhere without re-importing `node:module` into their own
+// static graph.
+export { createRequire };
+
+// Thread it into transform-core unconditionally (the setter no-ops the floor branch
+// on Node WITH getBuiltinModule). worker-polyfill's setter is wired by the entries
+// themselves, AFTER they import worker-polyfill, since worker-polyfill is loaded later
+// in the entry's flow (via dynamic import) than this static import runs.
+setTransformCoreCreateRequire(createRequire);

package/runtime/preload-async-hooks.mjs

@@ -17,6 +17,16 @@
 // worker injects no watch hooks (watch IPC is main-thread only), so the core's
 // dependency reporters stay no-ops here, exactly as before the extraction.
 
+// Floor bootstrap (Node < 22.3/20.16/18.20.4): threads node:module's createRequire
+// into transform-core via a MODULE-SCOPE SETTER — never globalThis (brand boundary) —
+// because transform-core has no process.getBuiltinModule on the floor. floor-builtin
+// calls transform-core's setter during its own evaluation, so importing it FIRST
+// (ESM evaluates imports in source order) means the value is threaded before any hook
+// in this loader worker fires. No-op where getBuiltinModule exists. This worker runs
+// OFF any user loader chain, so floor-builtin's static node:module import never leaks
+// — see floor-builtin.mjs. (worker-polyfill is NOT loaded here: this is the dedicated
+// loader worker, not a user realm, so it installs no browser globals.)
+import "./floor-builtin.mjs";
 import {
   TRANSPILE_EXTS, DATA_EXTS,
   extname, resolveSpec, loadTranspile, loadData,

package/runtime/preload-common.cjs

@@ -305,12 +305,18 @@ function installCjsRequireHooks(core, withClassicTranspile) {
     // to it. The one snag is that a registered customization hook makes Node thread a
     // `conditions` option that PnP rejects ("aren't supported by PnP yet
     // (conditions)"), so strip it first. The require/default condition PnP then
-    // applies is exactly right for `require()`. (Stripping is a harmless no-op when
-    // origResolveFilename is plain Node — i.e. not a PnP project.) This replaces the
-    // former `pnpapi.resolveRequest` reimplementation: simpler, and with no
-    // `findPnpApi` in the hot path there is no lookup-miss to leak a `conditions`
-    // crash on Windows.
-    if (options && "conditions" in options) {
+    // applies is exactly right for `require()`. This replaces the former
+    // `pnpapi.resolveRequest` reimplementation: simpler, and with no `findPnpApi` in
+    // the hot path there is no lookup-miss to leak a `conditions` crash on Windows.
+    //
+    // GATED ON PnP (`process.versions.pnp`). Off PnP the strip is NOT a harmless
+    // no-op: a user who passes custom `conditions` to require-side resolution via
+    // `module.registerHooks` (Node's module-hooks custom-conditions tests) relies on
+    // Node's own `_resolveFilename` honoring them, and unconditionally deleting the
+    // key silently dropped their conditions — breaking module-hooks/test-module-hooks-
+    // custom-conditions{,-cjs}. PnP is the only resolver that rejects `conditions`, so
+    // only strip when PnP is actually active; everywhere else conditions pass through.
+    if (process.versions.pnp && options && "conditions" in options) {
       options = { ...options };
       delete options.conditions;
     }
@@ -544,22 +550,44 @@ function wrapChildProcessCompileCache(cp) {
   };
 
   // Returns a possibly-rewritten options object with NODE_COMPILE_CACHE stripped
-  // from its env, after writing the sentinel keyed on THIS process's pid (= the
-  // grandchild's process.ppid). No-op unless the child env explicitly carries a
-  // live (non-empty, != "0") NODE_COMPILE_CACHE — an inherited (undefined env)
-  // value was already stripped from this process by nub, so nothing to do there.
+  // from the child's env, after writing the sentinel keyed on THIS process's pid
+  // (= the grandchild's process.ppid). Two source cases, both stripped:
+  //   • EXPLICIT env (options.env carries NODE_COMPILE_CACHE) — strip from it.
+  //   • INHERITED env (no options.env, child inherits this process's env) — when
+  //     OUR process.env carries a live NODE_COMPILE_CACHE, materialize an explicit
+  //     env from process.env with it removed. This case matters now that the
+  //     DEFAULT (nub-owned) cache also travels via the sentinel and gets restored
+  //     into process.env: a node child the user spawns with NO explicit env would
+  //     otherwise inherit it and enable the cache AT BOOTSTRAP — before any preload
+  //     gate — collapsing that child's V8 coverage if it runs under
+  //     --experimental-test-coverage (the test-runner coverage-width fixtures, which
+  //     are spawned with inherited env). Stripping here makes every node-target
+  //     child boot cache-off; its own preload re-enables the cache post-bootstrap
+  //     via reenableUserCompileCache UNLESS it's collecting coverage.
   const stripFromOptions = (options) => {
-    if (!options || typeof options !== "object") return options;
-    const env = options.env;
-    if (!env || typeof env !== "object") return options;
-    const dir = env.NODE_COMPILE_CACHE;
-    if (!dir || dir === "0") return options;
+    const inheritedDir = process.env.NODE_COMPILE_CACHE;
+    const opts = options && typeof options === "object" ? options : {};
+    const env = opts.env;
+    if (env && typeof env === "object") {
+      const dir = env.NODE_COMPILE_CACHE;
+      if (!dir || dir === "0") return options;
+      try {
+        writeFileSync(join(tmpdirNoOs(), `nub-ccache-${process.pid}`), String(dir));
+      } catch { return options; }
+      const newEnv = { ...env };
+      delete newEnv.NODE_COMPILE_CACHE;
+      return { ...opts, env: newEnv };
+    }
+    // Inherited env path: only act when this process actually carries a live cache
+    // dir (otherwise there is nothing for the child to inherit and we leave the
+    // spawn's env untouched — `undefined` keeps Node's default inheritance).
+    if (!inheritedDir || inheritedDir === "0") return options;
     try {
-      writeFileSync(join(tmpdirNoOs(), `nub-ccache-${process.pid}`), String(dir));
+      writeFileSync(join(tmpdirNoOs(), `nub-ccache-${process.pid}`), String(inheritedDir));
     } catch { return options; }
-    const newEnv = { ...env };
+    const newEnv = { ...process.env };
     delete newEnv.NODE_COMPILE_CACHE;
-    return { ...options, env: newEnv };
+    return { ...opts, env: newEnv };
   };
 
   // For (command, args?, options?) signatures the options object is the last arg
@@ -610,7 +638,75 @@ function wrapChildProcessCompileCache(cp) {
   };
 }
 
+// True when V8 code coverage is active for THIS process — `--experimental-test-
+// coverage` / a bare `--test-coverage*` flag in our own argv or execArgv, or a
+// non-empty NODE_V8_COVERAGE env. A WARM compile cache makes V8 coverage imprecise
+// (cached bytecode collapses/omits per-branch ranges, so a fixture's coverage
+// JSON loses `functions[].ranges[1]` and the line/branch percentages drift from
+// plain node). nub must therefore NOT (re)enable its compile cache for any process
+// that is collecting coverage. This mirrors spawn.rs's coverage gate, but catches
+// the case spawn.rs cannot see: a grandchild the USER's test code spawns directly
+// (e.g. `spawnSync(execPath, [fixture], { env: { NODE_V8_COVERAGE } })`), which
+// inherits nub's preload via NODE_OPTIONS but never goes through nub's Rust spawn
+// path — so the gate has to live here too. (Observed against parallel/test-v8-
+// coverage, test-runner-coverage-thresholds, and the test-runner coverage-width
+// snapshot tests, all of which warm-cache then collect coverage in a child.)
+function coverageActiveInProcess() {
+  if (process.env.NODE_V8_COVERAGE) return true;
+  const hasCovFlag = (a) =>
+    typeof a === "string" &&
+    (a === "--experimental-test-coverage" || a.startsWith("--test-coverage"));
+  return (process.execArgv || []).some(hasCovFlag) || (process.argv || []).some(hasCovFlag);
+}
+
 function reenableUserCompileCache() {
+  // Coverage active: leave the compile cache OFF so V8 collects precise per-branch
+  // ranges (a warm cache collapses them — see coverageActiveInProcess). Two things
+  // matter, because Node's test runner spawns a SEPARATE isolated child to run the
+  // covered fixture and that child enables its cache at BOOTSTRAP from an inherited
+  // NODE_COMPILE_CACHE — too early for any preload gate to catch:
+  //   (a) don't enableCompileCache in THIS process, and
+  //   (b) set NODE_DISABLE_COMPILE_CACHE=1 in our env so EVERY descendant (incl. the
+  //       test runner's isolated coverage child) boots with the cache off. Node
+  //       honors NODE_DISABLE_COMPILE_CACHE at bootstrap and it travels via the env,
+  //       reaching children nub never spawns itself. We do NOT clear NODE_COMPILE_CACHE
+  //       (user code may read it); the disable var takes precedence at bootstrap.
+  // This is the JS half of the compile-cache/coverage fix; spawn.rs is the Rust half
+  // (it never sets the DEFAULT cache when it can see coverage in nub's own
+  // argv/NODE_OPTIONS/NODE_V8_COVERAGE).
+  //
+  // INTENTIONAL COVERAGE JUDGMENT CALL (b): NODE_DISABLE_COMPILE_CACHE=1 is set in
+  // process.env, so it propagates SUBTREE-WIDE for the rest of this coverage session —
+  // it is inherited by EVERY descendant, including non-coverage grandchildren the
+  // user's test code spawns mid-run (e.g. a build step a covered test shells out to).
+  // Those grandchildren therefore ALSO lose compile caching for the duration, even
+  // though they aren't themselves collecting coverage. We accept this: the disable var
+  // is the only mechanism that reaches the test runner's isolated coverage child
+  // (which boots its cache before any preload gate can fire), and scoping it more
+  // tightly than "the whole coverage subtree" isn't possible via an inherited env var.
+  // The cost is bounded (no caching during one coverage session) and self-healing (a
+  // grandchild spawned outside a coverage run is unaffected); surprising only to a
+  // user who expects an unrelated grandchild to keep caching while a parent collects
+  // coverage. Documented here and at the spawn.rs coverage branch (judgment call (a)).
+  if (coverageActiveInProcess()) {
+    const dir = process.env.NODE_COMPILE_CACHE;
+    if (!dir || dir === "0") {
+      // No explicit cache: keep coverage precise by disabling nub's default
+      // subtree-wide (the only mechanism that reaches the test runner's isolated
+      // coverage child, which boots its cache before any preload gate can fire).
+      process.env.NODE_DISABLE_COMPILE_CACHE = "1";
+      return;
+    }
+    // Explicit NODE_COMPILE_CACHE present: the user's choice wins over coverage
+    // precision (Colin, 2026-06-11) — same tradeoff they'd have on plain node.
+    // Narrow accepted caveat: a nub-DEFAULT dir restored from the sentinel is
+    // indistinguishable from a user dir here; that combination is reachable only
+    // when coverage is invisible to nub's own spawn (e.g. a c8-style grandchild
+    // setting NODE_V8_COVERAGE itself). Simple + documented beats provenance
+    // plumbing through the sentinel.
+    try { module_.enableCompileCache(dir); } catch {}
+    return;
+  }
   const dir = process.env.NODE_COMPILE_CACHE;
   // "0" is nub's disable signal (see transform-core); anything else is the user's
   // real cache dir, which we re-point Node's compile cache at for THEIR modules.

package/runtime/preload.mjs

@@ -26,6 +26,18 @@
 // side-effecting import has to precede the transform-core import. See
 // compile-cache-restore.mjs.
 import "./compile-cache-restore.mjs";
+// Floor bootstrap (Node < 22.3/20.16/18.20.4): threads node:module's createRequire
+// into transform-core (and, below, worker-polyfill) via MODULE-SCOPE SETTERS — never
+// globalThis (brand boundary) — so those fast-tier `require(esm)` modules can fetch
+// node: builtins on the floor, where process.getBuiltinModule is absent. floor-builtin
+// holds the lone static node:module import and calls transform-core's setter during
+// ITS evaluation; importing it FIRST (ESM evaluates imports in source order) means
+// that setter has fired before transform-core's hooks are used. No-op on Node with
+// getBuiltinModule. See floor-builtin.mjs for why this is leak-safe. We capture its
+// re-exported `createRequire` (the floor's, off any user chain) to thread into
+// worker-polyfill below — that module is loaded later (dynamic import) so its setter
+// can't be called from floor-builtin's own evaluation.
+import { createRequire as floorCreateRequire } from "./floor-builtin.mjs";
 import module from "node:module";
 import { createRequire } from "node:module";
 import * as core from "./transform-core.mjs";
@@ -99,7 +111,18 @@ installSyncPolyfills(__preloadedPolyfills);
 if (typeof globalThis.navigator?.locks === "undefined") {
   await import("./navigator-locks.mjs");
 }
-await import("./worker-polyfill.mjs");
+// worker-polyfill fetches its node: builtins via process.getBuiltinModule; on the
+// floor (where that's absent) it needs the threaded createRequire BEFORE its install
+// runs. The module no longer auto-installs on the floor, so thread the value in and
+// install explicitly. On the fast/modern-compat tier the module already auto-installed
+// at eval (getBuiltinModule present) and installWorkerPolyfill() is an idempotent
+// no-op (its globalThis.Worker / worker-scope guards already fired). See
+// floor-builtin.mjs + worker-polyfill.mjs for the brand-safe (globalThis-free)
+// threading contract; this same path re-runs per worker realm (preload re-runs via
+// NODE_OPTIONS), so each user worker thread gets the value threaded too.
+const __workerPolyfill = await import("./worker-polyfill.mjs");
+__workerPolyfill.setBootstrapCreateRequire(floorCreateRequire);
+__workerPolyfill.installWorkerPolyfill();
 
 // ── Temporal: lazy global (A37) ─────────────────────────────────────
 common.installTemporalLazyGlobal(__require);

package/runtime/transform-core.mjs

@@ -44,29 +44,76 @@
 // .getBuiltinModule` fetches node: builtins synchronously off the loader chain;
 // `createRequire(import.meta.url)` resolves the (now CommonJS-only) vendored
 // polyfills + the `@oxc-project/runtime` helpers from nub's distribution.
-// This file keeps its `export`s (it stays an ES module), but has ZERO static
-// imports, so `require(esm)` finds no dependency graph to route through the user.
+// This file keeps its `export`s (it stays an ES module) but has ZERO static
+// imports — INCLUDING zero static `import` of any `node:` builtin — so `require(esm)`
+// of transform-core finds no dependency graph to route through the user loader.
+// This is load-bearing, not cosmetic: transform-core previously carried a static
+// `import { createRequire } from "node:module"`. That import sat in transform-core's
+// static graph, so when nub's fast-tier preload.cjs does `require("./transform-core
+// .mjs")` (a `require(esm)`), Node instantiated transform-core by walking its static
+// import graph THROUGH the user's pre-registered `--experimental-loader` /
+// `module.register` chain — and a user resolve hook that rejects or rewrites
+// `node:module` (e.g. the example-loader that throws on any non-`./`/`../`/URL
+// specifier) then exploded nub's own load, while resolve-count loaders saw a phantom
+// `node:module` hit. (Observed against es-module/test-esm-example-loader,
+// -loader-chaining, -initialization, -preserve-symlinks-not-found, and
+// parallel/test-shadow-realm-custom-loaders.) The earlier comment here claimed the
+// `node:module` import was "never routed through a user loader hook" — that was
+// FALSE for the fast-tier `require(esm)` path, and is the bug this rewrite fixes.
+//
 // `process.getBuiltinModule` (Node 22.3 / backported to 20.16 / 18.20.4) fetches a
-// node: builtin synchronously off the loader chain. On older floor Node (18.19,
-// 20.11–20.15, 22.0–22.2) it's `undefined` — calling it threw `TypeError: process
-// .getBuiltinModule is not a function`, aborting every run. Fall back to a
-// createRequire bootstrapped from a single static `node:module` import. That import
-// is a BUILTIN specifier — resolved by Node natively, never routed through a user
-// loader hook (and resolved here at preload time, before any hook registers) — so
-// the "zero user-routable dependency graph for require(esm)" property still holds.
-import { createRequire as __bootstrapCreateRequire } from "node:module";
-const __getBuiltin =
-  typeof process.getBuiltinModule === "function"
-    ? (id) => process.getBuiltinModule(id)
-    : ((__r) => (id) => __r(id))(__bootstrapCreateRequire(import.meta.url));
-
-const { createRequire } = __getBuiltin("node:module");
-const __require = createRequire(import.meta.url);
-
-const module = __getBuiltin("node:module");
-const { readFileSync, writeFileSync, mkdirSync, statSync } = __getBuiltin("node:fs");
-const { fileURLToPath, pathToFileURL } = __getBuiltin("node:url");
-const { join, dirname } = __getBuiltin("node:path");
+// node: builtin synchronously OFF the loader chain, with no static import — so on
+// the fast tier (22.15+, the only tier that loads transform-core via `require(esm)`,
+// and where getBuiltinModule ALWAYS exists) there is nothing in the graph for a user
+// loader to observe. On the narrow FLOOR below 22.3/20.16/18.20.4 (18.19.x,
+// 20.11–20.15, 22.0–22.2) it's `undefined`; there, transform-core is loaded ONLY via
+// static ESM `import` from the compat-tier entries (preload.mjs main thread /
+// preload-async-hooks.mjs loader worker), both OFF any user loader chain — so the
+// floor's `node:module` access cannot leak.
+//
+// BRAND BOUNDARY — the floor's `createRequire` is THREADED IN THROUGH MODULE SCOPE,
+// not parked on `globalThis`. floor-builtin.mjs holds the lone static `import {
+// createRequire } from "node:module"` and pushes the value in here via the
+// `setBootstrapCreateRequire` setter below; nothing is ever written to the user's
+// global object (a `globalThis.__nub*` sentinel is the same brand leak as a NUB_*
+// env var — enumerable in user code AND worker realms — so it is forbidden). The
+// floor's `node:module` import lives only in floor-builtin.mjs, which the fast tier
+// never loads, so it never enters the fast-tier `require(esm)` graph.
+//
+// On the floor the threaded value isn't available at this module's top-level eval:
+// the compat entry imports floor-builtin AHEAD of transform-core, but ES modules
+// evaluate the importEE before the importer's body, so floor-builtin's setter call
+// (made during ITS evaluation) lands AFTER transform-core's body has run. So on the
+// floor every builtin is acquired LAZILY, on first hook use — by which point the
+// setter has run. On the fast tier getBuiltinModule is present, so the builtins are
+// acquired eagerly here at module eval (no setter, no floor path involved).
+let _bootstrapCreateRequire = null;
+// Called by floor-builtin.mjs (imported first by the compat entries) to hand in the
+// floor's `createRequire` without any globalThis surface. NEVER called on the fast
+// tier (getBuiltinModule covers it). The compat entries import floor-builtin ahead of
+// transform-core, so by the time this fires transform-core's body has already
+// evaluated (importEE before importer) — which is exactly why this setter also runs
+// __ensureBuiltins() right now: it lands DURING floor-builtin's evaluation, before the
+// entry's body and long before any hook fires, so every builtin binding is ready
+// without ever consulting globalThis.
+export function setBootstrapCreateRequire(fn) {
+  _bootstrapCreateRequire = fn;
+  __ensureBuiltins();
+}
+
+// node: builtins (lazy on the floor, eager on the fast tier — see above). On the
+// floor `_bootstrapCreateRequire` is read at FETCH time (inside the thunk), never at
+// definition time, so floor-builtin's setter has run before the first fetch fires.
+function __getBuiltin(id) {
+  if (typeof process.getBuiltinModule === "function") return process.getBuiltinModule(id);
+  return _bootstrapCreateRequire(import.meta.url)(id);
+}
+
+// Builtin bindings + the native addon, populated by __ensureBuiltins(). They stay
+// `let` (not `const`) because on the floor they are filled on first hook use rather
+// than at module eval — see the lazy-vs-eager note above.
+let createRequire, __require, module, readFileSync, writeFileSync, mkdirSync, statSync;
+let fileURLToPath, pathToFileURL, join, dirname;
 // Nub's N-API addon — the in-process TS/JSX transpiler (`transform`,
 // `transformCached`, `detectModuleInfo`), the tsconfig reader + additive
 // TS-resolver (`loadTsconfig`, `resolveTs`), AND the data-format parsers
@@ -80,9 +127,27 @@ const { join, dirname } = __getBuiltin("node:path");
 // package, no static-import graph to route. nub now loads ZERO npm packages
 // internally, so the user ESM loader chain can never observe a nub dependency.
 let nubNative = null;
-for (const rel of ["./addons/nub-native.node", "../runtime/addons/nub-native.node"]) {
-  try { nubNative = __require(fileURLToPath(new URL(rel, import.meta.url))); break; } catch {}
+
+// Idempotent. Acquires the node: builtins + the native addon. Runs eagerly at module
+// eval on the fast tier (getBuiltinModule present); on the floor it is invoked at the
+// top of every exported entry point, where the threaded createRequire is ready.
+let __builtinsReady = false;
+function __ensureBuiltins() {
+  if (__builtinsReady) return;
+  __builtinsReady = true;
+  ({ createRequire } = __getBuiltin("node:module"));
+  __require = createRequire(import.meta.url);
+  module = __getBuiltin("node:module");
+  ({ readFileSync, writeFileSync, mkdirSync, statSync } = __getBuiltin("node:fs"));
+  ({ fileURLToPath, pathToFileURL } = __getBuiltin("node:url"));
+  ({ join, dirname } = __getBuiltin("node:path"));
+  for (const rel of ["./addons/nub-native.node", "../runtime/addons/nub-native.node"]) {
+    try { nubNative = __require(fileURLToPath(new URL(rel, import.meta.url))); break; } catch {}
+  }
 }
+// Fast tier: getBuiltinModule is present, so acquire everything now (preserves the
+// original eager-at-eval behavior). The floor defers to first-use — see above.
+if (typeof process.getBuiltinModule === "function") __ensureBuiltins();
 
 // NOTE: the transpile-cache version component is no longer read here. nub's
 // version is baked into the native addon at compile time (`env!("CARGO_PKG_VERSION")`
@@ -455,27 +520,39 @@ function hasDecoratorSyntax(filePath, source, lang) {
 // nub-specific env var). Per wiki/runtime/transpile-cache.md (Colin 2026-05-18).
 const CACHE_DISABLED =
   process.permission?.has !== undefined || process.env.NODE_COMPILE_CACHE === "0";
+// Resolved lazily (memoized) rather than at module eval, because on the floor the
+// node:path builtins it needs aren't bound until __ensureBuiltins() runs on first
+// hook use. `null` = disabled / no writable dir; `undefined` cacheDirResolved means
+// "not yet computed".
 let cacheDir = null;
-if (!CACHE_DISABLED) {
+let cacheDirResolved = false;
+function getCacheDir() {
+  if (cacheDirResolved) return cacheDir;
+  cacheDirResolved = true;
+  if (CACHE_DISABLED) return cacheDir;
+  __ensureBuiltins();
   const base = process.env.XDG_CACHE_HOME || (process.env.HOME ? join(process.env.HOME, ".cache") : null);
   if (base) {
     cacheDir = join(base, "nub", "transpile");
     try { mkdirSync(cacheDir, { recursive: true }); } catch { cacheDir = null; }
   }
+  return cacheDir;
 }
 
 // ── Bounded-cache maintenance ───────────────────────────────────────
 const CACHE_MAX_BYTES = 512 * 1024 * 1024; // 512 MiB — bounds runaway growth, not normal use
 const SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1000; // ≤ one sweep per day
 export function maybeSweepCache() {
-  if (!cacheDir) return;
+  __ensureBuiltins();
+  const dir = getCacheDir();
+  if (!dir) return;
   // Workers inherit this preload (via execArgv); only the main thread sweeps.
   try {
     if (!__require("node:worker_threads").isMainThread) return;
   } catch {
     return;
   }
-  const sentinel = join(cacheDir, ".sweep");
+  const sentinel = join(dir, ".sweep");
   const s = statSync(sentinel, { throwIfNoEntry: false });
   if (s && Date.now() - s.mtimeMs < SWEEP_INTERVAL_MS) return;
   try {
@@ -484,7 +561,7 @@ export function maybeSweepCache() {
     return;
   }
   import("./cache-evict.mjs")
-    .then((m) => m.sweepCache(cacheDir, CACHE_MAX_BYTES))
+    .then((m) => m.sweepCache(dir, CACHE_MAX_BYTES))
     .catch(() => {});
 }
 
@@ -495,6 +572,7 @@ export function maybeSweepCache() {
 // fix that makes `require()` of a TS file work on the compat tier, where Node's
 // CJS translator loads it via this hook and keys on the returned format.
 export function loadTranspile(url, ext) {
+  __ensureBuiltins();
   const filePath = fileURLToPath(url);
   const source = readFileSync(filePath, "utf8");
   const dir = dirname(filePath);
@@ -555,7 +633,7 @@ export function loadTranspile(url, ext) {
   // JS enable/disable signal: native then skips all cache I/O and just transforms.
   const formatByte = format === "commonjs" ? "c" : "m";
   const result = nubNative.transformCached(
-    filePath, source, opts, ext, tsconfigHash || "", pkgType || "", formatByte, cacheDir ?? undefined,
+    filePath, source, opts, ext, tsconfigHash || "", pkgType || "", formatByte, getCacheDir() ?? undefined,
   );
   if (result.errors.length > 0) {
     const details = result.errors.map((e) => e.codeframe || e.message).join("\n\n");

package/runtime/version.mjs

@@ -9,4 +9,4 @@
 // previously lived as a literal inside preload.mjs, which `make version` patched,
 // while the worker carried a hand-maintained "…-compat" copy that `make version`
 // never touched — a latent staleness bug this module closes.)
-export const NUB_VERSION = "0.0.31";
+export const NUB_VERSION = "0.0.33";

package/runtime/worker-polyfill.mjs

@@ -3,31 +3,48 @@
 // real MessageEvent/ErrorEvent, and URL-only constructor (Deno shape).
 
 // node: builtins are fetched via `process.getBuiltinModule` rather than static
-// `import`. This file is loaded via `require(esm)` from the preload, and Node's
-// `require(esm)` instantiates an ES module by walking its STATIC IMPORT graph
-// through whatever ESM loader chain is registered — including the USER's
+// `import`. This file is loaded via `require(esm)` from the preload (polyfills.cjs),
+// and Node's `require(esm)` instantiates an ES module by walking its STATIC IMPORT
+// graph through whatever ESM loader chain is registered — including the USER's
 // `--loader`/`register()` hooks. A static `import { Worker } from
 // "node:worker_threads"` therefore routes the builtin through the user chain; a
 // user load hook that returns SOURCE for node:worker_threads makes V8 see no
 // `Worker` export, so `new NodeWorker(...)` references an undefined binding and
 // the child crashes (observed against test-esm-loader-chaining). `process
-// .getBuiltinModule` fetches the real builtin synchronously off the loader
-// graph, bypassing the user chain entirely — same fix transform-core.mjs uses.
-// `process.getBuiltinModule` doesn't exist below Node 22.3 / 20.16 / 18.20.4 (it
-// threw `TypeError: ... is not a function` there). Fall back to a createRequire
-// bootstrapped from a single static `node:module` import. The actual builtins below
-// are still fetched through `__getBuiltin` — getBuiltinModule on new Node, CJS
-// `__require` on old — and BOTH bypass the user ESM loader chain (the whole reason
-// this file avoids a static `import` of node:worker_threads). Only the bootstrap
-// touches node:module, which user loader hooks don't intercept (unlike the mockable
-// node:worker_threads the chaining test targets), so the bypass guarantee holds.
-import { createRequire as __bootstrapCreateRequire } from "node:module";
-const __getBuiltin =
-  typeof process.getBuiltinModule === "function"
-    ? (id) => process.getBuiltinModule(id)
-    : ((__r) => (id) => __r(id))(__bootstrapCreateRequire(import.meta.url));
-const { Worker: NodeWorker, parentPort, isMainThread } = __getBuiltin("node:worker_threads");
-const { fileURLToPath } = __getBuiltin("node:url");
+// .getBuiltinModule` fetches the real builtin synchronously off the loader graph,
+// bypassing the user chain entirely — same fix transform-core.mjs uses.
+//
+// The bootstrap MUST avoid a static `node:module` import too: it has the IDENTICAL
+// leak. The chaining corpus registers a user load hook (loader-load-foo-or-42.mjs)
+// that rewrites the SOURCE of `node:module` so its compiled namespace no longer
+// exports `createRequire` — so a static `import { createRequire } from "node:module"`
+// here threw `does not provide an export named 'createRequire'` and crashed every
+// run with that loader (the earlier comment claimed user hooks "don't intercept
+// node:module" — FALSE; this is the bug). So we use `process.getBuiltinModule` when
+// present (fast tier + modern compat: no static import, nothing for the user chain
+// to observe), and on the narrow FLOOR where it's absent (Node < 22.3/20.16/18.20.4,
+// loaded only via the compat-tier entries OFF any user chain) the createRequire
+// THREADED IN through `setBootstrapCreateRequire` below.
+//
+// BRAND BOUNDARY — the floor's `createRequire` is threaded through MODULE SCOPE, never
+// parked on `globalThis` (a `globalThis.__nub*` sentinel is the same brand leak as a
+// NUB_* env var — enumerable in user code AND worker realms — so it is forbidden). On
+// the floor this module is loaded ONLY via the compat-tier main-thread preload
+// (preload.mjs), which imports floor-builtin first, then — AFTER importing this module
+// — calls `setBootstrapCreateRequire(createRequire)` and `installWorkerPolyfill()`. So
+// the install work is deferred (this module does NOT auto-run on the floor): its body
+// fetches builtins, and on the floor those aren't reachable until the setter runs.
+// On the fast tier (getBuiltinModule present) the install runs eagerly at module eval
+// — see the auto-install at the bottom — so the existing side-effect-`require` call
+// sites (preload.cjs, polyfills.cjs) are unchanged.
+let _bootstrapCreateRequire = null;
+export function setBootstrapCreateRequire(fn) {
+  _bootstrapCreateRequire = fn;
+}
+function __getBuiltin(id) {
+  if (typeof process.getBuiltinModule === "function") return process.getBuiltinModule(id);
+  return _bootstrapCreateRequire(import.meta.url)(id);
+}
 
 // `ErrorEvent` only became a global in Node 26. On the 22/24 floor it is
 // undefined, so `new ErrorEvent(...)` below would throw a ReferenceError inside
@@ -62,7 +79,16 @@ function getErrorEventCtor() {
         });
 }
 
-if (typeof globalThis.Worker === "undefined") {
+// Define the browser-shape `Worker` global (main thread) + the worker-side scope
+// (self/postMessage/message wiring). Acquires its node: builtins on entry — on the
+// floor that needs the threaded createRequire, so this runs only after the compat
+// entry has called setBootstrapCreateRequire (or, on the fast tier, eagerly via the
+// auto-install at the bottom).
+export function installWorkerPolyfill() {
+  const { Worker: NodeWorker, parentPort, isMainThread } = __getBuiltin("node:worker_threads");
+  const { fileURLToPath } = __getBuiltin("node:url");
+
+  if (typeof globalThis.Worker === "undefined") {
   class Worker extends EventTarget {
     #worker;
 
@@ -288,4 +314,12 @@ if (!isMainThread && parentPort) {
   if (typeof scope.close !== "function") {
     defineGlobal("close", () => process.exit(0));
   }
+  }
 }
+
+// Fast tier (and modern compat): getBuiltinModule is present, so the install needs no
+// threaded createRequire — run it eagerly at module eval, preserving the side-effect-
+// on-`require` contract the fast-tier call sites (preload.cjs, polyfills.cjs) rely on.
+// On the FLOOR (getBuiltinModule absent) this is skipped; the compat main-thread
+// preload calls setBootstrapCreateRequire(...) + installWorkerPolyfill() explicitly.
+if (typeof process.getBuiltinModule === "function") installWorkerPolyfill();