@nubjs/nub-win32-x64 0.0.13 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubjs/nub-win32-x64",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Nub binary for win32-x64",
   "license": "MIT",
   "repository": "https://github.com/nub-js/nub",

package/runtime/polyfills.cjs

@@ -0,0 +1,178 @@
+// Polyfill preloads for Nub v0.1 — the shared implementation for BOTH tiers.
+//
+// This is a CommonJS module with ZERO top-level await so the fast tier
+// (Node 22.15+, `--require` CJS preload) can `require()` it synchronously: a
+// `require()`-loaded preload keeps Node's synchronous `Module.runMain` CJS entry
+// path (top-level `executionAsyncId()===1`, sync exception origin), which the old
+// `--import` ESM preload broke (R1). The compat tier (`--import` preload.mjs)
+// reuses this same logic via the `installSyncPolyfills` export, then loads the two
+// ESM side-effect modules (worker-polyfill, navigator-locks) with dynamic
+// `import()` — on the < 22.15 floor `require()` of an ES module is unreliable.
+//
+// All polyfills feature-detect and bow out if the global is already present.
+//
+// Node 22.15+ (our floor) already has: navigator, navigator.locks,
+// navigator.hardwareConcurrency, WebSocket. No polyfills needed.
+//
+// Node 24+ adds: URLPattern, RegExp.escape, Error.isError, Promise.try.
+// We polyfill those on Node 22.x only.
+//
+// No Node version ships: Temporal, reportError, browser-shape Worker.
+// These need polyfills on all supported versions. (Temporal is a lazy global
+// installed by the preload entry, NOT here — see preload.cjs / preload.mjs.)
+
+const { createRequire } = require("node:module");
+const __require = createRequire(__filename);
+
+// Install every globalThis/prototype polyfill that doesn't depend on loading the
+// ESM side-effect modules (worker-polyfill, navigator-locks). Synchronous and
+// idempotent — safe to call once per realm. `preloaded` carries the CJS-required
+// polyfill packages the preload entry stashed (urlpattern, float16), since the
+// resolve hook would otherwise clobber a later import of them.
+function installSyncPolyfills(preloaded) {
+  preloaded = preloaded || {};
+
+  // ── reportError (WinterTC min-common-API, not in any Node) ──────────
+  // Defined NON-ENUMERABLE so it is invisible to `Object.keys(globalThis)` /
+  // for-in / structured-clone-of-keys — that invisibility-to-enumeration IS the
+  // additive contract: code written for vanilla Node must not observe nub's
+  // injected globals when it enumerates the global object. Node defines its own
+  // globals non-enumerably for the same reason. Kept writable+configurable so
+  // user code can still override or delete it, matching Node's global descriptors.
+  if (typeof globalThis.reportError !== "function") {
+    Object.defineProperty(globalThis, "reportError", {
+      value: (err) => {
+        queueMicrotask(() => {
+          throw err;
+        });
+      },
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+
+  // ── URLPattern (native on Node 24+, missing on 22.x) ───────────────
+  if (typeof globalThis.URLPattern === "undefined") {
+    const mod = preloaded.urlpattern;
+    const URLPattern = mod?.URLPattern;
+    if (URLPattern) globalThis.URLPattern = URLPattern;
+  }
+
+  // Temporal (in no Node version) is installed as a LAZY global by the preload
+  // entry after this runs — see preload.cjs / preload.mjs (A37). Touching
+  // globalThis.Temporal here would defeat that laziness, so we must not.
+
+  // ── Stage 4 polyfills (native on Node 24+, missing on 22.x) ────────
+
+  // RegExp.escape — spec-faithful port of the TC39 proposal (native on Node 24+),
+  // so the 22.x floor behaves byte-for-byte like native: a leading digit/letter is
+  // control-escaped, syntax chars are backslashed, control chars use \t\n\v\f\r, and
+  // the "other punctuators" + whitespace set is hex-escaped. Verified byte-identical
+  // to Node's native RegExp.escape across every ASCII char + leading/whitespace/
+  // astral cases (so a concatenated `escape(s)` is safe too, not just
+  // `new RegExp(escape(s))`). The earlier reduced-fidelity version only escaped the
+  // syntax chars.
+  if (typeof RegExp.escape !== "function") {
+    const SYNTAX = new Set(["^", "$", "\\", ".", "*", "+", "?", "(", ")", "[", "]", "{", "}", "|", "/"]);
+    const CONTROL = { "\t": "\\t", "\n": "\\n", "\v": "\\v", "\f": "\\f", "\r": "\\r" };
+    // ASCII "other punctuators" the spec escapes by code, plus SPACE.
+    const OTHER = new Set([..." ,-=<>#&!%:;@~'\"`"]);
+    const isWhiteSpace = (cp) =>
+      cp === 0x09 || cp === 0x0a || cp === 0x0b || cp === 0x0c || cp === 0x0d ||
+      cp === 0x20 || cp === 0xa0 || cp === 0x1680 || (cp >= 0x2000 && cp <= 0x200a) ||
+      cp === 0x2028 || cp === 0x2029 || cp === 0x202f || cp === 0x205f || cp === 0x3000 ||
+      cp === 0xfeff;
+    const hexEscape = (cp) => {
+      if (cp <= 0xff) return "\\x" + cp.toString(16).padStart(2, "0");
+      if (cp <= 0xffff) return "\\u" + cp.toString(16).padStart(4, "0");
+      const h = cp - 0x10000;
+      const hi = 0xd800 + (h >> 10);
+      const lo = 0xdc00 + (h & 0x3ff);
+      return "\\u" + hi.toString(16).padStart(4, "0") + "\\u" + lo.toString(16).padStart(4, "0");
+    };
+    const encode = (ch, cp) =>
+      SYNTAX.has(ch)
+        ? "\\" + ch
+        : CONTROL[ch] ?? ((OTHER.has(ch) || isWhiteSpace(cp)) ? hexEscape(cp) : ch);
+    RegExp.escape = (s) => {
+      if (typeof s !== "string") throw new TypeError("RegExp.escape argument must be a string");
+      const cps = [...s]; // iterate by code point (astral-safe)
+      let out = "";
+      for (let i = 0; i < cps.length; i++) {
+        const ch = cps[i];
+        const cp = ch.codePointAt(0);
+        // A leading decimal-digit/ASCII-letter is control-escaped so a preceding `\`
+        // in a concatenated pattern can't form an escape sequence.
+        if (i === 0 && ((cp >= 0x30 && cp <= 0x39) || (cp >= 0x41 && cp <= 0x5a) || (cp >= 0x61 && cp <= 0x7a))) {
+          out += "\\x" + cp.toString(16).padStart(2, "0");
+        } else {
+          out += encode(ch, cp);
+        }
+      }
+      return out;
+    };
+  }
+
+  // Error.isError (~95% fidelity — cross-realm internal-slot unreachable)
+  if (typeof Error.isError !== "function") {
+    Error.isError = (value) => {
+      if (value == null || typeof value !== "object") return false;
+      return value instanceof Error;
+    };
+  }
+
+  // Promise.try
+  if (typeof Promise.try !== "function") {
+    Promise.try = (fn, ...args) => {
+      return new Promise((resolve) => resolve(fn(...args)));
+    };
+  }
+
+  // Float16Array (TC39 Stage 4, native on Node 24+; absent on our 22.x floor).
+  // Installed from the spec-compliant @petamoriken/float16 polyfill (vendored,
+  // preloaded by the preload entry). It provides the full TypedArray method
+  // surface (map/filter/subarray/set/reduce/…) and correct round-to-nearest-even,
+  // including subnormals — unlike the prior hand-rolled Proxy shim, which had
+  // ~30 methods missing and truncating/denormal-flushing conversion.
+  //
+  // INHERENT userland limitation (not fixable by any JS polyfill): a polyfilled
+  // Float16Array isn't recognized by `ArrayBuffer.isView()` (it has no V8 internal
+  // [[TypedArrayName]] slot). Code needing that check should use the polyfill's
+  // `isFloat16Array`. See wiki/runtime/float16array-polyfill.md.
+  if (typeof globalThis.Float16Array === "undefined") {
+    const f16 = preloaded.float16;
+    if (f16?.Float16Array) {
+      globalThis.Float16Array = f16.Float16Array;
+
+      if (typeof DataView.prototype.getFloat16 !== "function") {
+        DataView.prototype.getFloat16 = function (offset, littleEndian) {
+          return f16.getFloat16(this, offset, littleEndian);
+        };
+        DataView.prototype.setFloat16 = function (offset, value, littleEndian) {
+          f16.setFloat16(this, offset, value, littleEndian);
+        };
+      }
+
+      if (typeof Math.f16round !== "function") {
+        Math.f16round = f16.f16round;
+      }
+    }
+  }
+}
+
+// Load the two ESM side-effect modules — Web Locks (navigator.locks) and the
+// browser-shape Worker global — synchronously via `require()`. Valid on the fast
+// tier ONLY (Node 22.15+), where require(esm) of these side-effecting ES modules
+// works (verified). The compat tier must NOT call this; it loads them with
+// dynamic `import()` from preload.mjs instead.
+function installEsmPolyfillsSync() {
+  // ── navigator.locks (native on Node 24+, missing on 22.x) ──────────
+  if (typeof globalThis.navigator?.locks === "undefined") {
+    __require("./navigator-locks.mjs");
+  }
+  // ── Worker (browser-shape global, not in any Node) ──────────────────
+  __require("./worker-polyfill.mjs");
+}
+
+module.exports = { installSyncPolyfills, installEsmPolyfillsSync };

package/runtime/preload-common.cjs

@@ -0,0 +1,548 @@
+// Shared preload machinery for BOTH tiers — CommonJS, zero top-level await.
+//
+// The fast tier (Node 22.15+) loads this from a `--require` CJS preload
+// (preload.cjs) so Node keeps its synchronous `Module.runMain` CJS entry path
+// (top-level `executionAsyncId()===1`, sync exception origin, `require.main.id`
+// `'.'`, `module.parent` `null`) — all of which the old `--import` ESM preload
+// broke by forcing eager ESM-loader init that routed even a CJS entry through the
+// async ESM module-job (R1). The compat tier (18.19–22.14) loads this from its
+// async `--import` preload.mjs and reuses the same hook/require/watch/Temporal
+// logic; only hook REGISTRATION differs (sync `module.registerHooks` on the fast
+// tier vs async `module.register` loader worker on compat), which each entry owns.
+//
+// EVERYTHING here is synchronous and import-of-transform-core is a plain
+// `require()` — transform-core.mjs has no top-level await and is require(esm)-able
+// on the fast tier; the compat entry passes its already-imported core bindings in
+// (it imported them as ESM), so this module never require()s the core there.
+
+const module_ = require("node:module");
+const { readdirSync } = require("node:fs");
+const { fileURLToPath, pathToFileURL } = require("node:url");
+const { join, dirname, extname: pathExtname } = require("node:path");
+
+// ── Watch-mode dependency reporting (main thread only) ──────────────
+// Under `nub watch`, Node's FilesWatcher only watches files in the import graph;
+// config files (tsconfig.json, package.json) and `.env*` are NOT in any graph, so
+// an edit to them otherwise goes stale. Node accepts incremental
+// `process.send({'watch:require': [...]})` over its WATCH_REPORT_DEPENDENCIES IPC
+// at ANY point in the child's life (it adds each path to the watch set), so we
+// report config paths AS the core loader discovers them. The reporters are
+// injected into the core via setWatchHooks so getTsconfigForDir / getPackageType
+// self-report. The flush is coalesced via setImmediate.
+function installWatchReporting(core) {
+  const WATCH_REPORTING =
+    process.env.WATCH_REPORT_DEPENDENCIES === "1" && typeof process.send === "function";
+  const watchReported = new Set();
+  const watchPending = [];
+  let watchFlushScheduled = false;
+  function flushWatchDeps() {
+    watchFlushScheduled = false;
+    if (watchPending.length === 0) return;
+    const batch = watchPending.splice(0, watchPending.length);
+    try { process.send({ "watch:require": batch }); } catch {}
+  }
+  function reportWatchDep(path) {
+    if (!WATCH_REPORTING || !path || watchReported.has(path)) return;
+    watchReported.add(path);
+    watchPending.push(path);
+    if (!watchFlushScheduled) {
+      watchFlushScheduled = true;
+      // A scheduled immediate is drained before the loop would exit, so even a
+      // script that finishes synchronously flushes its deps. (Don't unref: an
+      // unref'd immediate is skipped on a synchronous exit, dropping the report.)
+      setImmediate(flushWatchDeps);
+    }
+  }
+  // Report a directory's `.env*` files (the natural watch targets). Scanned once
+  // per directory, lazily.
+  const watchEnvScannedDirs = new Set();
+  function reportEnvFilesIn(dir) {
+    if (!WATCH_REPORTING || watchEnvScannedDirs.has(dir)) return;
+    watchEnvScannedDirs.add(dir);
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const name of entries) {
+      if (name === ".env" || name.startsWith(".env.")) reportWatchDep(join(dir, name));
+    }
+  }
+  core.setWatchHooks({ reportDep: reportWatchDep, reportEnvDir: reportEnvFilesIn });
+  return WATCH_REPORTING;
+}
+
+// ── Resolve / load hooks (sync `module.registerHooks` shape) ────────
+// Returns `{ resolve, load }` closing over `core` + the watch flag. The compat
+// tier does NOT use these (its hooks run async in the loader worker via
+// preload-async-hooks.mjs); only the fast tier's `module.registerHooks` does.
+
+// True once USER code registers its own `module.registerHooks` (a ts-node/tsx-style
+// transpiler). nub registers exactly one hook set from the preload (the FIRST call
+// after the wrap below); every later call is the user's. This lets the load hook
+// tell apart a bare `'typescript'` format that a USER resolve hook set (defer — the
+// user's own load hook will transpile) from the bare `'typescript'` that Node's
+// NATIVE CJS loader assigns to a `.ts` entry/require in a package with no explicit
+// `type` (transpile — there is no user hook to do it, and Node's strip-only mode
+// can't handle enums/namespaces). See makeHooks().load.
+let __userHooksRegistered = false;
+function installUserHookDetector() {
+  if (typeof module_.registerHooks !== "function") return;
+  const orig = module_.registerHooks;
+  if (orig.__nubWrapped) return;
+  let seen = 0;
+  const wrapped = function (...args) {
+    // Call #1 is nub's own preload registration; #2+ are user hooks.
+    if (seen >= 1) __userHooksRegistered = true;
+    seen += 1;
+    return orig.apply(this, args);
+  };
+  wrapped.__nubWrapped = true;
+  try { module_.registerHooks = wrapped; } catch {}
+}
+
+function makeHooks(core, watchReporting) {
+  installUserHookDetector();
+
+  function resolve(specifier, context, nextResolve) {
+    const r = core.resolveSpec(specifier, context.parentURL);
+    return r ?? nextResolve(specifier, context);
+  }
+
+  function load(url, context, nextLoad) {
+    const ext = core.extname(url);
+
+    // Watch mode: surface this file's nearest config files (tsconfig.json,
+    // package.json) + sibling `.env*` so edits to them restart the run. Done for
+    // every user file (not just transpiled ones) — getTsconfigForDir/
+    // getPackageType self-report via the injected watch hooks.
+    if (watchReporting && url.startsWith("file:") && !core.isNodeModules(url)) {
+      try {
+        const dir = dirname(fileURLToPath(url));
+        core.getTsconfigForDir(dir);
+        core.getPackageType(dir);
+      } catch {}
+    }
+
+    // A USER resolve hook (a ts-node/tsx-style transpiler registered AFTER nub's
+    // own preload hook) claimed this file with the bare 'typescript' format: defer
+    // to the user's own load chain. The discriminator is `__userHooksRegistered`,
+    // NOT the bare format alone — Node's NATIVE CJS loader ALSO emits the bare
+    // string 'typescript' for a `.ts` entry/require whose nearest package.json has
+    // no explicit `type` (cjs/loader.js getFormatOfExtensionlessFile, lines ~1986),
+    // and in that native case nub MUST transpile (Node's strip-only mode can't
+    // handle enums/namespaces). So we only step aside when a user hook is present:
+    // nub registers exactly one hook set from the preload, the user registers theirs
+    // later, and registering theirs OUTERMOST (LIFO) means their load hook wraps
+    // nub's — it sets format='typescript', calls nextLoad into nub, and (without this
+    // guard) nub would transpile with oxc — a type-stripper, not a module-format
+    // transformer — leaving `export {}` verbatim and, for a `type:commonjs` package,
+    // handing Node format='commonjs' + ESM source = invalid CJS. Stepping aside lets
+    // nub fall through to Node's native load, returning raw TS source back up to the
+    // user's outer hook, which does the real ESM->CJS conversion, matching Node.
+    // Native 'module-typescript'/'commonjs-typescript' formats still fall through to
+    // nub's transpile below, so normal augmentation is unchanged.
+    if (__userHooksRegistered && context && context.format === "typescript") {
+      return nextLoad(url, context);
+    }
+
+    // R12: never transpile `.ts`/`.tsx`/… inside node_modules. Node itself throws
+    // ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING for TS under node_modules; if
+    // nub transpiled it instead, that native error would never surface and nub
+    // would be MORE permissive than Node. Fall through to `nextLoad` so Node's own
+    // handling (and its error) applies. (The TS-parent extensionless resolution in
+    // the resolve hook is intended and stays — only this load-time transpile is
+    // gated.)
+    if (core.TRANSPILE_EXTS.has(ext) && !core.isNodeModules(url)) {
+      return core.loadTranspile(url, ext);
+    }
+    if (ext in core.DATA_EXTS) return core.loadData(url, ext);
+
+    const r = nextLoad(url, context);
+    // nub's sync `module.registerHooks` load hook forces the synchronous
+    // module-job (ModuleJobSync.syncLink -> loadAndTranslateForImportInRequiredESM),
+    // which cannot async-fetch source. When a user `--experimental-loader` resolve
+    // hook sets `format` without a `source` (a pattern vanilla Node tolerates on its
+    // async load path by fetching the source itself), the default load returns
+    // source:null and Node's assertBufferSource throws ERR_INVALID_RETURN_PROPERTY_VALUE.
+    // Backfill the source from disk so the sync path matches Node — without touching
+    // nub's own resolve/transpile hooks.
+    //
+    // EXCEPTION — format 'commonjs' (and 'builtin') MUST keep source:null. For those
+    // formats Node's ESM loader deliberately returns no source and hands the module
+    // off to the NATIVE CommonJS loader (Module._load), where `require()` uses CJS
+    // resolution. A CJS `.js` ENTRY, when a user `--experimental-loader` is active, is
+    // routed through the ESM loader for format detection but still loads as CJS this
+    // way. If we backfilled its source, the ESM loader would instead translate it via
+    // its CommonJS-to-ESM wrapper, routing every inner `require()` through the ESM
+    // resolve hook — so `require('assert')` would hand the bare 'assert' specifier to
+    // the user's resolve hook and crash with ERR_INVALID_RETURN_PROPERTY_VALUE (the
+    // shadow-realm/custom-loaders corpus failure). Only ESM-shaped formats ('module',
+    // 'json', 'wasm', …) genuinely need the source on the sync path.
+    if (
+      r && r.source == null && r.format &&
+      r.format !== "commonjs" && r.format !== "builtin" &&
+      typeof url === "string" && url.startsWith("file:")
+    ) {
+      try {
+        const { readFileSync } = require("node:fs");
+        return { ...r, source: readFileSync(fileURLToPath(url)) };
+      } catch { /* fall through with the original result */ }
+    }
+    return r;
+  }
+
+  return { resolve, load };
+}
+
+// ── CommonJS require() augmentation (BOTH tiers) ────────────────────
+// `module.registerHooks`' CJS-`require()` coverage is INCOMPLETE before ~Node 24:
+// on Node 22.15 a `require()` from a `.cts` parent (which Node loads via the ESM
+// translator's special-require) hits native Module._resolveFilename with no
+// tsconfig/extensionless handling — a `require('@alias')` or `require('./x')` of a
+// `.ts` target throws MODULE_NOT_FOUND, while the same code works on Node 26 (where
+// registerHooks does cover it) and on the fast `import` path. On the compat tier
+// (18.19–22.14) the only hook surface is `module.register`, which intercepts the
+// ESM loader ONLY — so `require()` is entirely unaugmented there. Both gaps have
+// the same closure: install this main-thread CJS shim, reusing the core's canonical
+// resolveCjsPath / loadTranspile (no drift). It tries nub's resolution first and
+// FALLS THROUGH to native on a miss, so it is a safe no-op on the versions where
+// registerHooks already covers require (Node 24+/26). Mechanism stays within the
+// augmenter rules: exactly what `--require`-installing the ts-node / tsx CJS shim
+// has always done.
+//
+// This error is surfaced ONLY on Node versions without native require(esm)
+// (< 20.19 / 22.0–22.11), where require() of an ES module genuinely cannot work.
+// On every require(esm)-capable Node, Node loads the ES module itself and this is
+// never reached. The message is user-facing: no internal mechanism names.
+function requireEsmError(filename) {
+  const err = new Error(
+    `Cannot require() this file — it is an ES module.\n` +
+    `  ${filename}\n` +
+    `It uses \`import\`/\`export\`, so it loads as an ES module, and this version of ` +
+    `Node can't require() an ES module. Load it with \`import(...)\` instead, rename ` +
+    `it to .cts for a CommonJS module, or upgrade Node.`,
+  );
+  err.code = "ERR_REQUIRE_ESM";
+  return err;
+}
+
+// `withClassicTranspile` — also install the `require.extensions` (classic CommonJS
+// loader) transpile hook. Needed ONLY on Node WITHOUT native require(esm)
+// (< 20.19 / 22.0–22.11): there, `module.register`'s ESM-loader hooks can't reach a
+// `require()`, AND an ES module simply can't be require()d, so we transpile CJS
+// content classically and surface a clean error for ESM content. On require(esm)-
+// capable Node we DON'T install it — registering `require.extensions['.ts']` would
+// shadow Node's own native require(esm) of ES-module `.ts` files (breaking
+// `require("./esm.ts")`), and the resolve shim below plus the tier's load hook
+// already cover resolution + transpile.
+function installCjsRequireHooks(core, withClassicTranspile) {
+  const origResolveFilename = module_._resolveFilename;
+  module_._resolveFilename = function (request, parent, isMain, options) {
+    let resolved = null;
+    try {
+      const parentPath = parent && typeof parent.filename === "string" ? parent.filename : null;
+      resolved = core.resolveCjsPath(request, parentPath);
+    } catch { /* fall through to Node */ }
+    if (resolved) {
+      if (withClassicTranspile && core.requireTargetIsEsm(resolved, pathExtname(resolved))) {
+        throw requireEsmError(resolved);
+      }
+      return resolved;
+    }
+    return origResolveFilename.call(this, request, parent, isMain, options);
+  };
+
+  if (!withClassicTranspile) return;
+
+  // require.extensions: transpile via the SAME loadTranspile the load hook uses —
+  // target:'es2022' lowering (`using`), tsconfig, source maps, the Stage-3
+  // decorator guard, and module-format detection are all identical to the fast
+  // tier. The path is already a real TS file (Module._resolveFilename ran first).
+  // A module-format source can't be _compile'd as CJS — same clean error as above.
+  const transpileExtension = (mod, filename) => {
+    const { source, format } = core.loadTranspile(pathToFileURL(filename).href, pathExtname(filename));
+    if (format === "module") throw requireEsmError(filename);
+    mod._compile(source, filename);
+  };
+  for (const ext of [".ts", ".cts", ".mts", ".tsx", ".jsx"]) {
+    module_._extensions[ext] = transpileExtension;
+  }
+}
+
+// ── Clobbered-polyfill preloading + Temporal lazy global ────────────
+// Packages in the core's CLOBBER_MAP can't be imported after hooks register
+// because the resolve hook returns a synthetic module instead of the real package.
+// Load them here via CJS require (not yet hooked) and return them so the polyfill
+// installer can stash them. Temporal is the exception (A37): the polyfill is ~18ms
+// to load and most scripts never touch it, so we only RESOLVE its path now (cheap)
+// and defer the load to a lazy global getter. Requiring it later by absolute path
+// bypasses the CLOBBER_MAP resolve-hook entry, which keys on the specifier.
+function preloadPolyfillPackages(reqFromRuntime) {
+  const preloaded = {};
+  // Feature-detect before requiring (A39): URLPattern is native on Node 24+, so
+  // skip loading the polyfill there. On 22.x it's absent → load it.
+  if (typeof globalThis.URLPattern === "undefined") {
+    try { preloaded.urlpattern = reqFromRuntime("urlpattern-polyfill"); } catch {}
+  }
+  // Float16Array: native on Node 24+, absent on the 22.x floor.
+  if (typeof globalThis.Float16Array === "undefined") {
+    try { preloaded.float16 = reqFromRuntime("@petamoriken/float16"); } catch {}
+  }
+  return preloaded;
+}
+
+// Install the lazy `globalThis.Temporal` getter. The polyfill is loaded — and even
+// RESOLVED — only on first access. CRITICAL ordering note (regexp one-off): the
+// `require.resolve("@js-temporal/polyfill")` is deferred INTO the getter, NOT run at
+// preload top level. An unconditional resolve at startup mutates the legacy
+// `RegExp.$_` static (the resolved node_modules path matches an internal regex), so
+// a program inspecting `RegExp.$_` on its first line would otherwise see a leaked
+// path (test-startup-empty-regexp-statics). Deferring the resolve keeps `RegExp.$_`
+// empty at user-code start; the cost is paid only by a program that touches Temporal.
+function installTemporalLazyGlobal(reqFromRuntime) {
+  if (typeof globalThis.Temporal !== "undefined") return;
+
+  const defineTemporal = (value) =>
+    Object.defineProperty(globalThis, "Temporal", {
+      value,
+      configurable: true,
+      writable: true,
+      enumerable: false,
+    });
+  Object.defineProperty(globalThis, "Temporal", {
+    configurable: true,
+    enumerable: false,
+    get() {
+      let temporalPath;
+      try { temporalPath = reqFromRuntime.resolve("@js-temporal/polyfill"); } catch {}
+      if (!temporalPath) return undefined;
+      const polyfill = reqFromRuntime(temporalPath);
+      // @js-temporal/polyfill exports `toTemporalInstant` as a function but does
+      // NOT auto-install it on Date.prototype (you assign it yourself). Install it
+      // here so that on the floor (no native Temporal) `date.toTemporalInstant()`
+      // AND the package clobber's re-export of `Date.prototype.toTemporalInstant`
+      // both work — matching native Node. Guarded so we never replace a native
+      // implementation on a runtime that ships Temporal.
+      if (
+        typeof Date.prototype.toTemporalInstant !== "function" &&
+        typeof polyfill.toTemporalInstant === "function"
+      ) {
+        Object.defineProperty(Date.prototype, "toTemporalInstant", {
+          value: polyfill.toTemporalInstant,
+          configurable: true,
+          writable: true,
+          enumerable: false,
+        });
+      }
+      const T = polyfill.Temporal;
+      defineTemporal(T);
+      return T;
+    },
+    set: defineTemporal,
+  });
+}
+
+// ── Compile-cache handling (R8) ─────────────────────────────────────
+// nub injects its preload chain via `--require`, which Node loads at bootstrap.
+// If the user set NODE_COMPILE_CACHE, Node would enable the V8 code cache BEFORE
+// this preload runs and cache every module the chain pulls in (preload.cjs,
+// transform-core.mjs, this file, polyfills.cjs, …) into the USER's dir — so a
+// program reading `fs.readdirSync(NODE_COMPILE_CACHE)` would see ~9 nub entries,
+// not its own 1 (program-observable; R8). spawn.rs prevents that by STRIPPING
+// NODE_COMPILE_CACHE from the child env (bootstrap caches nothing) and stashing
+// the original value in a sentinel file keyed on nub's PID — which is THIS child's
+// `process.ppid` (nub is our direct parent). The dir travels via a sentinel file,
+// never a NUB_* env var (brand boundary).
+//
+// Two preload steps consume it:
+//   1. restoreCompileCacheEnv() runs EARLY, before transform-core.mjs is required,
+//      to put the original value BACK into process.env.NODE_COMPILE_CACHE. That
+//      matters because (a) transform-core reads `NODE_COMPILE_CACHE === "0"` as
+//      nub's transpile-cache disable signal, and (b) user code may read the env.
+//      Restoring it in JS does NOT re-trigger Node's V8 compile cache (Node
+//      configures that once at bootstrap from the now-stripped env), so the
+//      preload chain stays uncached. It also DELETES the sentinel (consume-once,
+//      so a recycled PID can't read stale state and the file never leaks).
+//   2. reenableUserCompileCache() runs LAST, after all nub modules are loaded
+//      uncached and right before user code, and calls
+//      `module.enableCompileCache(dir)` for a real dir so the user's OWN modules
+//      cache as they always did. A value of "0" is nub's disable sentinel (Node
+//      treats "0" as a literal dir named 0, but nub honors it as "no caching"),
+//      so we skip enabling there.
+// Best-effort throughout: a missing/unreadable sentinel or an enableCompileCache
+// failure just means no user compile cache — strictly safer than the old pollution.
+// `os.tmpdir()` without requiring `node:os`. Requiring os at preload pulls
+// `Internal Binding os` + `NativeModule os` into process.moduleLoadList on EVERY
+// startup (test-bootstrap-modules observes this) even though almost no run touches
+// the compile-cache sentinel. This replica mirrors Node's libuv/os.tmpdir() env
+// resolution (POSIX: TMPDIR→TMP→TEMP→/tmp; Win32: TEMP→TMP→SystemRoot/windir+\temp),
+// trailing-separator-stripped, which is also what Rust's env::temp_dir() (the side
+// that WRITES the sentinel in spawn.rs) resolves to — so both ends agree.
+function tmpdirNoOs() {
+  const env = process.env;
+  if (process.platform === "win32") {
+    let dir = env.TEMP || env.TMP || ((env.SystemRoot || env.windir || "") + "\\temp");
+    if (dir.length > 1 && dir.endsWith("\\") && !dir.endsWith(":\\")) dir = dir.slice(0, -1);
+    return dir;
+  }
+  let dir = env.TMPDIR || env.TMP || env.TEMP || "/tmp";
+  if (dir.length > 1 && dir.endsWith("/")) dir = dir.slice(0, -1);
+  return dir;
+}
+
+function compileCacheSentinelPath() {
+  return join(tmpdirNoOs(), `nub-ccache-${process.ppid}`);
+}
+
+function restoreCompileCacheEnv() {
+  try {
+    const { readFileSync, rmSync } = require("node:fs");
+    const value = readFileSync(compileCacheSentinelPath(), "utf8");
+    try { rmSync(compileCacheSentinelPath()); } catch {}
+    if (value) process.env.NODE_COMPILE_CACHE = value;
+  } catch { /* no sentinel: env was never set, or already consumed */ }
+  // Propagate the R8 strip to node grandchildren the user spawns directly (plain
+  // node inheriting nub's --require preload + a live NODE_COMPILE_CACHE → it would
+  // cache nub's preload chain into the user's dir). The wrap MUST preserve each
+  // function's own symbols (esp. [util.promisify.custom]) — dropping them broke
+  // util.promisify(child_process.*) + abort/sync-io behavior. See wrapSpawnLike.
+  try { armChildProcessCompileCacheWrap(); } catch {}
+}
+
+// Arm the child_process compile-cache wrap WITHOUT eagerly requiring child_process.
+//
+// Eagerly `require("node:child_process")` at preload time pulls ~40 builtins into
+// process.moduleLoadList on EVERY startup — net, dgram, the entire streams tree,
+// spawn_sync/tty_wrap/pipe_wrap/tcp_wrap, os, vm, etc. (test-bootstrap-modules
+// observes the exact list; child_process is the dominant extra-builtin source).
+// A program that never spawns a child shouldn't pay that cost — and Node's own
+// startup never loads child_process.
+//
+// So we intercept `Module._load` and apply the wrap to the child_process module the
+// FIRST time USER code requires it (`require('child_process')` /
+// `require('node:child_process')`), patching the returned singleton before handing
+// it back. After patching once we restore the original `_load`, so steady-state
+// require() has zero added overhead. If the user never requires child_process, the
+// module is never loaded and the builtins stay out of the load list — matching Node.
+let __cpWrapArmed = false;
+function armChildProcessCompileCacheWrap() {
+  if (__cpWrapArmed || __cpWrapped) return;
+  __cpWrapArmed = true;
+  if (typeof module_._load !== "function") return;
+  const origLoad = module_._load;
+  module_._load = function (request, parent, isMain) {
+    const exports = origLoad.call(this, request, parent, isMain);
+    if (request === "child_process" || request === "node:child_process") {
+      module_._load = origLoad; // restore: one-shot, no steady-state overhead
+      try { wrapChildProcessCompileCache(exports); } catch {}
+    }
+    return exports;
+  };
+}
+
+// Monkey-patch child_process so node-targeted children the USER spawns with an
+// explicit live NODE_COMPILE_CACHE get the SAME R8 treatment spawn.rs gives nub's
+// own children: strip NODE_COMPILE_CACHE from the child env (so Node's bootstrap
+// caches nothing of nub's inherited preload chain) and stash the original dir in a
+// PID-keyed sentinel file the grandchild's restoreCompileCacheEnv() reads back via
+// `process.ppid` to re-enable caching for the USER's own modules post-bootstrap.
+// Brand rule: the dir travels via a sentinel file, never a NUB_* env var.
+// `cp` is the already-loaded child_process exports object, passed in by the lazy
+// `_load` interceptor so we never require it ourselves (which would defeat the
+// deferral).
+let __cpWrapped = false;
+function wrapChildProcessCompileCache(cp) {
+  if (__cpWrapped || !cp) return;
+  __cpWrapped = true;
+  const { writeFileSync } = require("node:fs");
+  const { basename } = require("node:path");
+
+  const isNodeTarget = (command) => {
+    if (typeof command !== "string" || command.length === 0) return false;
+    if (command === process.execPath) return true;
+    const base = basename(command).toLowerCase();
+    return base === "node" || base === "node.exe";
+  };
+
+  // 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.
+  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;
+    try {
+      writeFileSync(join(tmpdirNoOs(), `nub-ccache-${process.pid}`), String(dir));
+    } catch { return options; }
+    const newEnv = { ...env };
+    delete newEnv.NODE_COMPILE_CACHE;
+    return { ...options, env: newEnv };
+  };
+
+  // For (command, args?, options?) signatures the options object is the last arg
+  // that is a non-array object; args is an optional array in between. Rewrites the
+  // call in place and dispatches to the original.
+  // Copy `orig`'s OWN symbols onto `wrapped` — crucially [util.promisify.custom],
+  // which Node sets on execFile/exec so `util.promisify(execFile)` returns a
+  // {stdout,stderr} promise. A bare wrapper without it silently changes promisify's
+  // result shape (broke test-child-process-promisified / -abortController /
+  // util-promisify-custom-names / sync-io-option / test-output-abort).
+  const preserveSymbols = (wrapped, orig) => {
+    for (const s of Object.getOwnPropertySymbols(orig)) {
+      try { wrapped[s] = orig[s]; } catch { /* read-only symbol: skip */ }
+    }
+    return wrapped;
+  };
+  const wrapSpawnLike = (orig) => preserveSymbols(function (command, ...rest) {
+    if (isNodeTarget(command)) {
+      let optIdx = -1;
+      for (let i = rest.length - 1; i >= 0; i--) {
+        const a = rest[i];
+        if (a && typeof a === "object" && !Array.isArray(a)) { optIdx = i; break; }
+        if (typeof a === "function") continue; // execFile callback
+        if (Array.isArray(a)) break; // args array — no options object present
+      }
+      if (optIdx >= 0) rest[optIdx] = stripFromOptions(rest[optIdx]);
+    }
+    return orig.call(this, command, ...rest);
+  }, orig);
+
+  cp.spawn = wrapSpawnLike(cp.spawn);
+  cp.spawnSync = wrapSpawnLike(cp.spawnSync);
+  cp.execFile = wrapSpawnLike(cp.execFile);
+  cp.execFileSync = wrapSpawnLike(cp.execFileSync);
+
+  // fork() always runs `process.execPath`, so it is always a node target. Its
+  // signature is (modulePath, args?, options?); reuse the same options rewrite.
+  const origFork = cp.fork;
+  cp.fork = function (modulePath, ...rest) {
+    let optIdx = -1;
+    for (let i = rest.length - 1; i >= 0; i--) {
+      const a = rest[i];
+      if (a && typeof a === "object" && !Array.isArray(a)) { optIdx = i; break; }
+      if (Array.isArray(a)) break;
+    }
+    if (optIdx >= 0) rest[optIdx] = stripFromOptions(rest[optIdx]);
+    return origFork.call(this, modulePath, ...rest);
+  };
+}
+
+function reenableUserCompileCache() {
+  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.
+  if (!dir || dir === "0") return;
+  try { module_.enableCompileCache(dir); } catch {}
+}
+
+module.exports = {
+  installWatchReporting,
+  makeHooks,
+  installCjsRequireHooks,
+  preloadPolyfillPackages,
+  installTemporalLazyGlobal,
+  restoreCompileCacheEnv,
+  reenableUserCompileCache,
+};

package/runtime/preload.cjs

@@ -0,0 +1,273 @@
+// Nub fast-tier preload — Node 22.15+, injected via `--require` (CommonJS).
+//
+// WHY CJS / `--require` (not the `.mjs` `--import` the compat tier uses): the mere
+// presence of `--import` forces Node to eagerly initialize the ESM loader, which
+// then routes EVEN A CJS ENTRY POINT through the async ESM module-job
+// (`ModuleJob.run`) instead of the synchronous `Module.runMain` CJS path. That one
+// change is the root cause of a whole regression cluster (R1): top-level
+// `executionAsyncId()===0` (Node: 1), extra PROMISE async-hook events, a top-level
+// sync `throw` surfacing as `unhandledRejection` instead of `uncaughtException`,
+// `require.main.id` `'.'`→abspath, `module.parent` `null`→`undefined`, and a
+// missing-entry `ERR_MODULE_NOT_FOUND` instead of `MODULE_NOT_FOUND`. Loading this
+// preload via `--require` (CJS) keeps Node on the synchronous CJS entry path and
+// restores all of them, while STILL supporting `module.registerHooks` + TS
+// transpile (both work from a `--require` CJS module on Node 22.15+).
+//
+// HARD CONSTRAINT: this file and everything it pulls in synchronously must be
+// TLA-free. `require(esm)` (which loads transform-core.mjs / the polyfill ESM
+// modules) rejects any module with top-level await (ERR_REQUIRE_ASYNC_MODULE), so
+// transform-core.mjs, polyfills.cjs, worker-polyfill.mjs and navigator-locks.mjs
+// are all TLA-free by construction. The compat tier (< 22.15), where require(esm)
+// is unreliable, keeps its async `--import` preload.mjs path UNCHANGED.
+//
+// ROBUSTNESS TO `--no-experimental-require-module` (the require-module cluster):
+// a user may set `--no-experimental-require-module` (e.g. to assert the legacy
+// require(esm)→ERR_REQUIRE_ESM contract for THEIR code). That flag globally
+// disables require(esm) — including for THIS `--require` CJS preload's own
+// `require("./transform-core.mjs")`, which would otherwise crash the process at
+// startup (ERR_REQUIRE_ESM) before any user code runs. nub's preload must survive
+// that. The fix: detect when sync require(esm) is unavailable and fall back to the
+// compat tier's async loader-worker hooks (`module.register("./preload-async-
+// hooks.mjs")`), which loads transform-core.mjs as a STATIC ESM import inside the
+// worker — a path the flag does not gate. User code still gets Node's own
+// ERR_REQUIRE_ESM for ITS require(esm), exactly as the flag promises; only nub's
+// preload is made robust. (See the require-module corpus cluster:
+// test-cjs-esm-warn, test-disable-require-module-with-detection,
+// test-esm-type-field-errors-2, parallel/test-require-mjs.)
+
+const { createRequire } = require("node:module");
+const module_ = require("node:module");
+
+const __require = createRequire(__filename);
+
+// Load preload-common FIRST so we can restore NODE_COMPILE_CACHE (R8) BEFORE
+// transform-core.mjs is required: spawn.rs stripped that env var to keep nub's
+// preload chain out of the user's V8 compile cache, and transform-core reads
+// `NODE_COMPILE_CACHE === "0"` as its transpile-cache disable signal — so the
+// value must be back in process.env before transform-core's module body runs.
+// Restoring it in JS does NOT re-enable Node's bootstrap compile cache (already
+// configured from the stripped env), so the chain below stays uncached.
+const common = __require("./preload-common.cjs");
+common.restoreCompileCacheEnv();
+
+// `--no-experimental-require-module` disables require(esm) globally, so the
+// transform-core require below (and the worker/locks ESM side-effect modules)
+// would throw ERR_REQUIRE_ESM and abort the process before user code. Detect that
+// and load via the async-register fallback instead. We probe by attempting the
+// require and catching ERR_REQUIRE_ESM — robust regardless of how the flag arrived
+// (CLI, NODE_OPTIONS, or a config file), and a no-op cost on the common path where
+// require(esm) works.
+let core = null;
+let requireEsmDisabled = false;
+try {
+  // The transform core is the single source of truth for resolution + transpile,
+  // shared verbatim with the compat tier. It's an ES module with no top-level
+  // await, so `require(esm)` loads it synchronously here on Node 22.15+.
+  core = __require("./transform-core.mjs");
+} catch (err) {
+  if (err && err.code === "ERR_REQUIRE_ESM") {
+    requireEsmDisabled = true;
+  } else {
+    throw err;
+  }
+}
+
+const { installSyncPolyfills } = __require("./polyfills.cjs");
+
+if (!requireEsmDisabled) {
+  // ── Fast tier (sync require(esm) available) ───────────────────────
+
+  // ── Watch-mode dependency reporting + hooks ───────────────────────
+  const watchReporting = common.installWatchReporting(core);
+
+  // Best-effort bounded-cache eviction (main thread only; the core guards on it).
+  // DEFERRED to setImmediate: maybeSweepCache probes `worker_threads.isMainThread`
+  // and dynamic-imports cache-evict.mjs, which would otherwise pull worker_threads
+  // (and its streams/worker-io transitive set) into the BOOTSTRAP module-load list
+  // on every startup — a cold-start regression (test-bootstrap-modules snapshots
+  // process.moduleLoadList at user code's first line). Running it one turn later
+  // keeps those out of the bootstrap snapshot while preserving the once-a-day sweep.
+  // unref so a purely-synchronous program still exits promptly without waiting on it.
+  setImmediate(() => {
+    try { core.maybeSweepCache(); } catch {}
+  }).unref();
+
+  // ── Pre-load clobbered polyfill packages BEFORE hooks register ────
+  // Packages in the core's CLOBBER_MAP can't be imported after hooks register (the
+  // resolve hook returns a synthetic module instead of the real package), so
+  // require them now via the not-yet-hooked CJS require and stash them for the
+  // polyfill installer. Temporal is deferred entirely to a lazy global (below).
+  const __preloadedPolyfills = common.preloadPolyfillPackages(__require);
+
+  // ── Hook registration (fast tier: sync, in-thread) ────────────────
+  // Same realm as user code; covers `import` and (Node 24+) `require`.
+  // registerHooks' require RESOLUTION is incomplete on 22.15–24, so also install
+  // the main-thread CJS resolve shim. Install the classic require.extensions
+  // transpile shim only on 22.15–22.17 (no native `.ts`); on 22.18+/24+ skip it so
+  // Node's native require() of `.ts` — incl. ES modules — isn't shadowed (see
+  // installCjsRequireHooks).
+  const __hasNativeTs = !!process.features?.typescript;
+  const { resolve, load } = common.makeHooks(core, watchReporting);
+  module_.registerHooks({ resolve, load });
+  common.installCjsRequireHooks(core, !__hasNativeTs);
+
+  // ── Sync polyfills + lazy ESM-side-effect polyfills ───────────────
+  installSyncPolyfills(__preloadedPolyfills);
+  installLazyEsmPolyfills();
+
+  // ── Temporal: lazy global (A37) ───────────────────────────────────
+  common.installTemporalLazyGlobal(__require);
+
+  // ── Compile-cache: re-enable for the USER's modules (R8) ──────────
+  common.reenableUserCompileCache();
+} else {
+  // ── Fallback tier (`--no-experimental-require-module`): async hooks ─
+  // The user disabled require(esm), so the in-thread sync `module.registerHooks`
+  // core can't be loaded here. Register the SAME hooks the compat tier uses, run
+  // in a dedicated loader worker via `module.register`; that worker imports
+  // transform-core.mjs as a static ESM import (not gated by the flag). The
+  // main-thread CJS require() transpile shim, which would need the core
+  // synchronously in-thread, is unavailable in this mode — an honest, additive
+  // degradation: the user opted out of require(esm), and nub's `.ts`-via-require()
+  // transpile rides on exactly that mechanism. `import`-side TS still transpiles
+  // through the registered loader-worker hooks. User require(esm) of THEIR own ES
+  // modules still gets Node's native ERR_REQUIRE_ESM, exactly as the flag promises.
+  const { pathToFileURL } = require("node:url");
+  module_.register("./preload-async-hooks.mjs", pathToFileURL(__filename).href);
+
+  // Sync, non-require(esm) polyfills still install (none of them require(esm)).
+  // Clobbered-polyfill packages are CJS requires, unaffected by the flag.
+  const __preloadedPolyfills = common.preloadPolyfillPackages(__require);
+  installSyncPolyfills(__preloadedPolyfills);
+  installLazyEsmPolyfills();
+
+  // Temporal lazy global needs only `__require` (it loads a CJS package), and the
+  // user's compile-cache re-enable is independent of require(esm).
+  common.installTemporalLazyGlobal(__require);
+  common.reenableUserCompileCache();
+}
+
+// ── Lazy ESM-side-effect polyfills (R7) ─────────────────────────────
+// The two ESM side-effect polyfills — the browser-shape Worker global
+// (worker-polyfill.mjs) and Web Locks (navigator-locks.mjs) — were previously
+// installed EAGERLY at preload (polyfills.cjs:installEsmPolyfillsSync). That drags
+// ~50 builtins into bootstrap on EVERY startup: worker-polyfill.mjs imports
+// node:worker_threads, which pulls internal/streams/* (readable/writable/duplex/
+// transform/pipeline/…), internal/worker, internal/worker/io,
+// internal/worker/messaging, vm, net, child_process, os, etc.; navigator-locks.mjs
+// pulls internal/locks + internal/navigator. None of that is needed by the common
+// "run a plain file, never touch Worker or navigator.locks" case, and the eager
+// load is a cold-start regression that contradicts the fast-runner premise
+// (test-bootstrap-modules: moduleLoadList must match Node's bootstrap set).
+//
+// Replace the eager install with lazy globals:
+//   • `globalThis.Worker` — a non-enumerable getter that, on first access (the
+//     first `new Worker(...)`), deletes itself, requires worker-polyfill.mjs (which
+//     then defines the real `globalThis.Worker`), and returns it.
+//   • `navigator.locks` — a non-enumerable getter that loads navigator-locks.mjs on
+//     first access (only when not native — Node 24.5+ ships it).
+// In a WORKER thread, the worker-side bootstrap inside worker-polyfill.mjs (self/
+// postMessage/message wiring) MUST run at startup, so we load it eagerly there.
+// That costs nothing for bootstrap accounting: a worker already loaded
+// worker_threads to exist, and test-bootstrap-modules measures the main thread.
+function installLazyEsmPolyfills() {
+  // Cheap main-thread detection that does NOT pull node:worker_threads into the
+  // main-thread bootstrap (requiring it eagerly is exactly the regression we're
+  // fixing): in a worker, worker_threads is already in the module-load list by the
+  // time this preload runs; on the main thread it is not.
+  const inWorkerThread = process.moduleLoadList.some(
+    (m) => m === "NativeModule worker_threads",
+  );
+
+  const loadEsmSideEffect = (specifier) => {
+    try {
+      __require(specifier);
+    } catch (err) {
+      if (err && err.code === "ERR_REQUIRE_ESM") {
+        // require(esm) disabled — load via dynamic import (not flag-gated). Async,
+        // but side-effect-only; the Worker/locks polyfills are needed lazily, and
+        // for a worker thread the worker-side wiring lands a tick later, which is
+        // still before any user message round-trip can complete.
+        import(specifier).catch(() => {});
+      } else {
+        throw err;
+      }
+    }
+  };
+
+  if (inWorkerThread) {
+    // Worker-side scope bootstrap must be present synchronously where possible.
+    loadEsmSideEffect("./worker-polyfill.mjs");
+    if (typeof globalThis.navigator?.locks === "undefined") {
+      loadEsmSideEffect("./navigator-locks.mjs");
+    }
+    return;
+  }
+
+  // Main thread: lazy Worker global. Defined NON-ENUMERABLE so it stays invisible
+  // to `Object.keys(globalThis)` / for-in — the additive contract — matching how
+  // worker-polyfill.mjs defines the real one.
+  if (typeof globalThis.Worker === "undefined") {
+    let installing = false;
+    Object.defineProperty(globalThis, "Worker", {
+      configurable: true,
+      enumerable: false,
+      get() {
+        if (installing) return undefined;
+        installing = true;
+        // Drop this lazy accessor so worker-polyfill.mjs's own
+        // `if (typeof globalThis.Worker === "undefined")` guard fires and defines
+        // the real Worker.
+        delete globalThis.Worker;
+        loadEsmSideEffect("./worker-polyfill.mjs");
+        return globalThis.Worker;
+      },
+      set(value) {
+        // A user assigning their own Worker wins — replace the lazy accessor.
+        Object.defineProperty(globalThis, "Worker", {
+          value,
+          configurable: true,
+          enumerable: false,
+          writable: true,
+        });
+      },
+    });
+  }
+
+  // Main thread: lazy navigator.locks (native on Node 24.5+, absent on the 22.x
+  // floor). VERSION-GATE so we never even READ `globalThis.navigator` where locks
+  // is native: on Node 24.5+ the native `navigator` global is a lazy getter that,
+  // on first access, eagerly realizes internal/navigator + internal/locks AND the
+  // whole stream/worker-io transitive set (~30 builtins) — touching it at preload
+  // would be exactly the cold-start regression test-bootstrap-modules guards
+  // against, for zero benefit (locks is already there). Below 24.5 navigator is
+  // present but lacks `locks`, and accessing it is cheap (one internal module), so
+  // installing the lazy polyfill there is fine.
+  const [navMaj, navMin] = process.versions.node.split(".").map((n) => parseInt(n, 10));
+  const locksNative = navMaj > 24 || (navMaj === 24 && navMin >= 5);
+  if (locksNative) return;
+
+  const nav = globalThis.navigator;
+  if (nav && typeof nav.locks === "undefined") {
+    let installing = false;
+    Object.defineProperty(nav, "locks", {
+      configurable: true,
+      enumerable: true,
+      get() {
+        if (installing) return undefined;
+        installing = true;
+        delete nav.locks;
+        loadEsmSideEffect("./navigator-locks.mjs");
+        return nav.locks;
+      },
+      set(value) {
+        Object.defineProperty(nav, "locks", {
+          value,
+          configurable: true,
+          enumerable: true,
+          writable: true,
+        });
+      },
+    });
+  }
+}

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.13";
+export const NUB_VERSION = "0.0.14";