@volter/tabnode 0.2.14-volter.88

package/src/node-lib/load.ts

@@ -0,0 +1,390 @@
+/**
+ * One loader for Node's own files.
+ *
+ * `src/shims/path.ts` is the precedent: a vendored file binds, it does not
+ * implement, and a bug in it is fixed by moving the file to a newer Node.
+ * `path` bound its own primordials and its own three internals by hand, which
+ * is affordable for one file that names fourteen names. `net.js` names two
+ * hundred, and `child_process.js` after it, so the binding is written once
+ * here instead: Node's own `internal/per_context/primordials.js` builds the
+ * whole `primordials` object over this realm's built-ins the way Node's
+ * bootstrap does, and a vendored file is evaluated in the scope Node's
+ * `BuiltinModule` gives one —
+ *
+ *     (function (exports, require, module, process, internalBinding, primordials) { … })
+ *
+ * — so nothing in a vendored file is hand-written and nothing in it is edited.
+ *
+ * Resolution, in the order Node's own `require` inside a builtin resolves: an
+ * `internal/…` name is a vendored file when one is vendored under that name,
+ * else the small hand-bound object in `./internals/` that holds exactly the
+ * names the vendored files destructure; a public name is the engine's own
+ * shim, the same object a guest's `require` answers with.
+ * `internalBinding(name)` is the libuv-shaped surface in `./binding/`.
+ */
+import PRIMORDIALS_SOURCE from './primordials.js?raw';
+import { NODE_LIB_SOURCES } from './sources';
+import { nodeLibInternal } from './internals';
+import { nodeLibBinding } from './binding';
+import { nodeLibPublic } from './public-modules';
+import { setLibRequire } from './require-hook';
+import { NODE_LTS_VERSION, nodeVersions } from './node-versions';
+
+/**
+ * The realm's built-ins, captured as Node captures them: before a program can
+ * monkey-patch them, in the shape every vendored file destructures. Node runs
+ * this file once per context with a `primordials` object to fill and the
+ * realm's `globalThis` around it; so does this.
+ */
+// `var`, not `let`: hoisted and already `undefined` when a cycle calls in.
+// eslint-disable-next-line no-var, vars-on-top
+var builtPrimordials: Record<string, unknown> | undefined;
+export function primordialsOf(): Record<string, unknown> {
+  if (builtPrimordials === undefined) {
+    const built: Record<string, unknown> = {};
+    // eslint-disable-next-line no-new-func
+    new Function('primordials', `${PRIMORDIALS_SOURCE}\n//# sourceURL=node:internal/per_context/primordials`)(built);
+    builtPrimordials = built;
+  }
+  return builtPrimordials;
+}
+
+/** A vendored file's module record, as Node's `BuiltinModule` holds one. */
+interface NodeLibModule {
+  exports: unknown;
+  id: string;
+  filename: string;
+  loaded: boolean;
+}
+
+/**
+ * The loader's own state, built on first use rather than when this module is
+ * evaluated. A vendored file is asked for from inside the import graph that
+ * leads here -- the engine's `string_decoder` shim wants Node's `Buffer`, and
+ * `Buffer` is a vendored file -- so the loader must answer whatever order the
+ * bundler settles on. Module-scope `const`s left it in its own temporal dead
+ * zone and the engine failed to load at all.
+ */
+/* eslint-disable no-var, vars-on-top */
+var cache: Map<string, NodeLibModule> | undefined;
+var builtInternals: Map<string, unknown> | undefined;
+var builtBindings: Map<string, unknown> | undefined;
+/* eslint-enable no-var, vars-on-top */
+
+/** The libuv-shaped surface, built once per name, on the first file that asks. */
+function internalBinding(name: string): unknown {
+  builtBindings ??= new Map<string, unknown>();
+  if (builtBindings.has(name)) return builtBindings.get(name);
+  const build = nodeLibBinding(name);
+  if (!build) throw new Error(`node-lib: no binding for internalBinding('${name}')`);
+  const value = build();
+  builtBindings.set(name, value);
+  return value;
+}
+
+/**
+ * The process a vendored file is handed where the realm has none: the engine
+ * loaded as a library, before any guest has run.
+ *
+ * Node compiles a builtin inside a bootstrapped process, and Node's own files
+ * read that process while they compile -- `internal/util` reads
+ * `process.versions.openssl` and `process.versions.amaro` at its top, and
+ * `internal/streams/state` reads `process.platform` -- so a realm with no
+ * process must still answer the static facts of one. It answers only those:
+ * everything a run owns -- its argv, its environment, its streams, its exit --
+ * belongs to that run's own process and is answered there.
+ *
+ * What made this a wall: the engine's `net-module` compiles Node's `net.js`
+ * while the bundle is still evaluating, `net` requires `events` and `events`
+ * requires `internal/util`, and in a page or a worker -- a realm with no
+ * `process` global -- `process.versions` was `undefined`, so the whole engine
+ * failed to import with `Cannot read properties of undefined (reading
+ * 'openssl')`.
+ */
+const NODE_LIB_LIBRARY_PROCESS: Record<string, unknown> = {
+  platform: 'linux',
+  arch: 'x64',
+  version: `v${NODE_LTS_VERSION}`,
+  versions: nodeVersions(),
+  env: {},
+  argv: ['node'],
+  argv0: 'node',
+  execArgv: [],
+  execPath: '/usr/local/bin/node',
+  nextTick: (fn: (...args: unknown[]) => void, ...args: unknown[]) => queueMicrotask(() => fn(...args)),
+};
+
+/**
+ * The `process` a vendored file is handed, built by a hoisted function for
+ * the reason `nodeLibInternalRequire` gives: a file can be compiled while the
+ * bundle is still evaluating, when a module-scope `var` is still undefined.
+ * Node hands a builtin the process of
+ * the realm it runs in; so does this, read at call time, because a guest's
+ * process is installed on the realm after this module is loaded and every run
+ * replaces it. Where the realm has no process at all the answer is
+ * {@link NODE_LIB_LIBRARY_PROCESS}.
+ */
+var nodeLibProcessCache: Record<string, unknown> | undefined;
+export function nodeLibProcessOf(): Record<string, unknown> {
+  return nodeLibProcessCache ??= new Proxy({} as Record<string, unknown>, {
+  get(_target, key) {
+    const realm = (globalThis as unknown as { process?: Record<string, unknown> }).process;
+    if (!realm) return NODE_LIB_LIBRARY_PROCESS[key as string];
+    const value = realm[key as string];
+    if (key === 'nextTick' && typeof value !== 'function') {
+      return (fn: (...args: unknown[]) => void, ...args: unknown[]) => queueMicrotask(() => fn(...args));
+    }
+    if (key === 'platform' && typeof value !== 'string') return 'linux';
+    return value;
+  },
+  set(_target, key, value) {
+    const realm = (globalThis as unknown as { process?: Record<string, unknown> }).process;
+    if (realm) realm[key as string] = value;
+    return true;
+  },
+  has(_target, key) {
+    const realm = (globalThis as unknown as { process?: Record<string, unknown> }).process;
+    return realm ? key in realm : key in NODE_LIB_LIBRARY_PROCESS;
+  },
+  });
+}
+
+function nodeLibRequire(specifier: string): unknown {
+  const name = specifier.startsWith('node:') ? specifier.slice(5) : specifier;
+  if (NODE_LIB_SOURCES[name] !== undefined) return loadNodeLib(name);
+  const internal = nodeLibInternal(name);
+  if (internal !== undefined) {
+    builtInternals ??= new Map<string, unknown>();
+    if (!builtInternals.has(name)) builtInternals.set(name, internal());
+    return builtInternals.get(name);
+  }
+  const shim = nodeLibPublic(name);
+  if (shim !== undefined) return shim();
+  throw new Error(`node-lib: a vendored Node file asked for '${specifier}', which the binding does not provide`);
+}
+
+/**
+ * A vendored file, evaluated as Node's `BuiltinModule.compileForInternalLoader`
+ * evaluates one and cached under its name. The record is cached before the
+ * body runs, as Node's is, so a cycle between two vendored files sees a
+ * partly-filled `exports` rather than looping.
+ */
+export function loadNodeLib(name: string): unknown {
+  cache ??= new Map<string, NodeLibModule>();
+  const cached = cache.get(name);
+  if (cached) return cached.exports;
+  const record = newNodeLibRecord(name);
+  // Cached before compile, as Node's is, so a cycle sees a partly-filled
+  // `exports`. A throw used to leave that empty record in the cache:
+  // `https.js` calls `assertCrypto()` at the top, the first read threw
+  // ERR_NO_CRYPTO, and every later `import("https")` answered `{}`, so
+  // `.request` was undefined (`r is not a function`).
+  cache.set(name, record);
+  try {
+    compileNodeLib(name, record);
+  } catch (error) {
+    cache.delete(name);
+    throw error;
+  }
+  return record.exports;
+}
+
+/**
+ * A vendored file evaluated into a module scope of its own, uncached.
+ *
+ * Node has one module graph per process and lets a builtin keep its state in
+ * its own file scope. The engine runs many guests in one realm, so a file
+ * whose scope IS the state is instantiated per run rather than shared:
+ * `internal/modules/customization_hooks` holds the hooks a program registered
+ * in two module-scope arrays, and one run's hooks must not resolve another
+ * run's imports. The caller holds the instance for as long as the run does.
+ */
+/**
+ * Node's ESM namespace for a CommonJS builtin: `default` is the module
+ * object, and every own key of `module.exports` is a named export, live.
+ * `import("https").then(m => m.request)` is `require("https").request`.
+ * Spread of a lazy proxy copied nothing; `Object.getOwnPropertyNames` reads
+ * the proxy's ownKeys trap, which is the module's keys.
+ */
+const builtinNamespaces: Array<{ cjs: object; ns: Record<string, unknown> }> = [];
+
+export function esmNamespaceOf(mod: unknown): Record<string, unknown> {
+  const ns: Record<string, unknown> = { default: mod };
+  if (mod !== null && (typeof mod === 'object' || typeof mod === 'function')) {
+    const cjs = mod as object;
+    for (const key of Object.getOwnPropertyNames(cjs)) {
+      if (key === 'default') continue;
+      Object.defineProperty(ns, key, {
+        enumerable: true,
+        configurable: true,
+        get(): unknown { return (cjs as Record<string, unknown>)[key]; },
+        set(value: unknown) { (cjs as Record<string, unknown>)[key] = value; },
+      });
+    }
+    builtinNamespaces.push({ cjs, ns });
+  }
+  return ns;
+}
+
+/** Node's `module.syncBuiltinESMExports`: newly assigned CJS keys appear on the namespace. */
+export function syncBuiltinESMExports(): void {
+  for (const { cjs, ns } of builtinNamespaces) {
+    for (const key of Object.getOwnPropertyNames(cjs)) {
+      if (key === 'default' || Object.prototype.hasOwnProperty.call(ns, key)) continue;
+      Object.defineProperty(ns, key, {
+        enumerable: true,
+        configurable: true,
+        get(): unknown { return (cjs as Record<string, unknown>)[key]; },
+        set(value: unknown) { (cjs as Record<string, unknown>)[key] = value; },
+      });
+    }
+  }
+}
+
+export function loadNodeLibInstance(name: string): unknown {
+  const record = newNodeLibRecord(name);
+  compileNodeLib(name, record);
+  return record.exports;
+}
+
+/**
+ * A vendored file cached on one engine instance rather than the realm.
+ *
+ * Node has one builtin cache per process. The engine runs many processes in
+ * one realm, and the realm cache is keyed only by name, so a second
+ * `Runtime`'s `require('fs')` was the first's module object: a `Symbol.for`
+ * tag written by one guest was readable by the other. The first instance
+ * still uses {@link loadNodeLib}; a later instance asks here, and the file
+ * is compiled once for that owner. Its `require` of other vendored files
+ * still hits the realm cache, so `net` and `events` stay one class.
+ */
+let byOwner: WeakMap<object, Map<string, NodeLibModule>> | undefined;
+export function loadNodeLibFor(owner: object, name: string): unknown {
+  byOwner ??= new WeakMap();
+  let owned = byOwner.get(owner);
+  if (!owned) {
+    owned = new Map();
+    byOwner.set(owner, owned);
+  }
+  const cached = owned.get(name);
+  if (cached) return cached.exports;
+  const record = newNodeLibRecord(name);
+  owned.set(name, record);
+  try {
+    compileNodeLib(name, record);
+  } catch (error) {
+    owned.delete(name);
+    throw error;
+  }
+  return record.exports;
+}
+
+function newNodeLibRecord(name: string): NodeLibModule {
+  if (NODE_LIB_SOURCES[name] === undefined) throw new Error(`node-lib: no vendored file for '${name}'`);
+  return { exports: {}, id: name, filename: `node:${name}`, loaded: false };
+}
+
+/** The scope Node's `BuiltinModule.compileForInternalLoader` gives a builtin. */
+function compileNodeLib(name: string, record: NodeLibModule): void {
+  // eslint-disable-next-line no-new-func
+  const compiled = new Function(
+    'exports', 'require', 'module', 'process', 'internalBinding', 'primordials',
+    `${NODE_LIB_SOURCES[name]}\n//# sourceURL=node:${name}`,
+  );
+  compiled(record.exports, nodeLibRequire, record, nodeLibProcessOf(), internalBinding, primordialsOf());
+  record.loaded = true;
+  bootstrapNodeLib(name, record.exports);
+}
+
+/**
+ * What Node's own bootstrap does to a builtin once it is compiled.
+ *
+ * A few of Node's files are compiled in a state that cannot answer yet and
+ * are finished by `internal/bootstrap/node.js`. `internal/util/debuglog.js`
+ * says so in its own comment: "calls to `debuglog()` before
+ * `initializeDebugEnv()` is called will throw", and it threw -- the first
+ * `readable.push` in the engine logged through a `debuglog` with no
+ * `testEnabled`. The engine has no bootstrap file, so the step lives here,
+ * beside the compile it belongs to.
+ */
+function bootstrapNodeLib(name: string, exports: unknown): void {
+  if (name === 'events') {
+    // Node's own `EventTarget` sets its listener ceiling on itself in its
+    // constructor, and `events.getMaxListeners` reads that field back. The
+    // realm's `EventTarget` -- the DOM's in a tab, Node's own where the
+    // engine runs inside a Node -- has no such field, and either way it is
+    // keyed by a symbol THIS `events.js` minted, not the one the realm's
+    // class was built against. So the default goes on the prototype under
+    // this file's own keys, where `getMaxListeners` looks, and a target given
+    // its own ceiling shadows it, which is what an own property does.
+    const events = exports as { kMaxEventTargetListeners?: symbol; kMaxEventTargetListenersWarned?: symbol };
+    const target = (globalThis as { EventTarget?: { prototype: object } }).EventTarget;
+    const defaults: Array<[symbol | undefined, unknown]> = [
+      [events.kMaxEventTargetListeners, 10],
+      [events.kMaxEventTargetListenersWarned, false],
+    ];
+    if (target) {
+      for (const [key, fallback] of defaults) {
+        if (!key || key in target.prototype) continue;
+        Object.defineProperty(target.prototype, key, {
+          configurable: true,
+          get(): unknown { return fallback; },
+          set(this: object, value: unknown) {
+            Object.defineProperty(this, key, { value, writable: true, configurable: true });
+          },
+        });
+      }
+    }
+    return;
+  }
+  if (name === 'internal/util/debuglog') {
+    const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+    (exports as { initializeDebugEnv?: (value: string) => void }).initializeDebugEnv?.(env?.NODE_DEBUG ?? '');
+    return;
+  }
+  if (name === 'assert') {
+    // Node 23 hangs `Assert` off the module; the vendored 22.18 file does not.
+    const assert = exports as { Assert?: unknown; strictEqual?: (a: unknown, b: unknown) => void };
+    if (typeof assert.Assert !== 'function') {
+      class Assert {
+        diff: string;
+        constructor(options?: { diff?: string }) { this.diff = options?.diff ?? 'simple'; }
+        strictEqual(a: unknown, b: unknown): void { assert.strictEqual?.(a, b); }
+      }
+      (assert as { Assert: unknown }).Assert = Assert;
+    }
+    return;
+  }
+  if (name === 'fs') {
+    // Node 23 hangs `mkdtempDisposableSync` off `fs`; the vendored 22.18
+    // file does not, and `openAsBlob`'s neighbour in the gate calls it.
+    const fs = exports as {
+      mkdtempSync?: (prefix: string, options?: unknown) => string;
+      mkdtempDisposableSync?: unknown;
+      rmSync?: (path: string, options?: { recursive?: boolean; force?: boolean }) => void;
+    };
+    if (typeof fs.mkdtempDisposableSync !== 'function' && typeof fs.mkdtempSync === 'function') {
+      fs.mkdtempDisposableSync = (prefix: string, options?: unknown) => {
+        const tempPath = fs.mkdtempSync!(prefix, options);
+        const remove = (): void => { try { fs.rmSync?.(tempPath, { recursive: true, force: true }); } catch { /* gone */ } };
+        return { path: tempPath, remove, [Symbol.dispose]: remove };
+      };
+    }
+  }
+}
+
+/**
+ * What a hand-bound internal, a binding or `./lazy.ts` calls to reach a
+ * vendored file.
+ *
+ * A function DECLARATION, not a `const`: a name that stands for a vendored
+ * class is read while the bundle is still evaluating -- `class Foo extends
+ * EventEmitter` runs `getPrototypeOf` on the proxy at the moment the class is
+ * defined, which is module-evaluation time, before this file's own bindings
+ * are initialized. A hoisted function is already callable then; a `const` is
+ * in its temporal dead zone and the engine failed to load at all.
+ */
+export function nodeLibInternalRequire(specifier: string): unknown {
+  return nodeLibRequire(specifier);
+}
+setLibRequire(nodeLibRequire);

package/src/node-lib/module-hooks.ts

@@ -0,0 +1,281 @@
+/**
+ * A run's module-customization hooks: `module.registerHooks` and `module.register`.
+ *
+ * Node has two of these systems and so does this. The synchronous one is
+ * Node's own file, `internal/modules/customization_hooks.js`, vendored and
+ * instantiated once per run: it owns the chain, the context merging, the
+ * `shortCircuit` rule and every validation message, and the engine's loader
+ * calls it exactly where Node's `cjs/loader.js` calls it -- around the resolve
+ * of a specifier and around the read of a source. The asynchronous one,
+ * `module.register`, is the engine's, because Node's is a second thread: a
+ * hooks worker, a `SharedArrayBuffer` and an `Atomics.wait` on the main thread
+ * for every resolution. A tab has no thread to block and nothing to block it
+ * for, so the registered hooks run in this realm, on this loop, and are
+ * awaited rather than waited on. The chain they form is the one
+ * `internal/modules/esm/hooks.js` builds -- last registered runs first, each
+ * hook gets the `next` below it, the bottom is the default step, a hook that
+ * returns without calling next must say `shortCircuit: true` -- transcribed
+ * here because that file cannot be vendored without the thread it is about.
+ *
+ * WHAT THIS COSTS, named rather than hidden:
+ *
+ * - An asynchronous hook is consulted where the engine can await: a dynamic
+ *   `import()`. The engine lowers a static `import` to a synchronous
+ *   `require`, so a hook registered with `register()` is not consulted for
+ *   one, where Node's is (its main thread blocks on the hooks thread). A
+ *   program that needs its hook on every specifier registers it with
+ *   `registerHooks`, which is synchronous and is consulted everywhere.
+ * - `data` reaches `initialize` by reference and `transferList` transfers
+ *   nothing, because there is no second thread to clone or transfer to. A
+ *   `MessagePort` in `data` is the same port object the caller holds; its
+ *   messages still cross on the loop, which is what a port is for.
+ * - `initialize` is awaited before the first resolution the chain serves,
+ *   which is where Node's synchronous `register()` has already blocked for it.
+ */
+import { loadNodeLibInstance } from './load';
+
+/** A resolve hook's answer, as `internal/modules/esm/hooks.js` validates one. */
+export interface ResolveResult {
+  url: string;
+  format?: string;
+  importAttributes?: Record<string, string>;
+  shortCircuit?: boolean;
+}
+
+/** A load hook's answer. */
+export interface LoadResult {
+  format?: string;
+  source?: string | ArrayBuffer | ArrayBufferView | null;
+  shortCircuit?: boolean;
+}
+
+type ResolveContext = { parentURL?: string; importAttributes?: Record<string, string>; conditions?: string[] };
+type LoadContext = { format?: string; importAttributes?: Record<string, string>; conditions?: string[] };
+type NextResolve = (specifier: string, context?: ResolveContext) => Promise<ResolveResult> | ResolveResult;
+type NextLoad = (url: string, context?: LoadContext) => Promise<LoadResult> | LoadResult;
+type AsyncResolveHook = (specifier: string, context: ResolveContext, next: NextResolve) => Promise<ResolveResult> | ResolveResult;
+type AsyncLoadHook = (url: string, context: LoadContext, next: NextLoad) => Promise<LoadResult> | LoadResult;
+
+/** What the vendored `internal/modules/customization_hooks.js` exports. */
+interface CustomizationHooks {
+  resolveHooks: unknown[];
+  loadHooks: unknown[];
+  registerHooks(hooks: { resolve?: unknown; load?: unknown }): { deregister(): void };
+  resolveWithHooks(
+    specifier: string, parentURL: string | undefined, importAttributes: Record<string, string> | undefined,
+    conditions: string[], defaultResolve: (specifier: string, context: ResolveContext) => ResolveResult,
+  ): ResolveResult;
+  loadWithHooks(
+    url: string, format: string | undefined, importAttributes: Record<string, string> | undefined,
+    conditions: string[], defaultLoad: (url: string, context: LoadContext) => LoadResult,
+  ): LoadResult;
+  convertCJSFilenameToURL(filename: string): string;
+  convertURLToCJSFilename(url: string): string;
+}
+
+/** A link of an asynchronous chain, the shape `hooks.js` pushes. */
+interface Link<Hook> { fn: Hook; url: string; next?: Link<Hook> }
+
+/**
+ * A hook of either chain, seen by the walk that runs one. The walk hands a
+ * hook its context and the link below it and reads back an object; which
+ * context and which next belong to the resolve chain or the load chain is
+ * what the two typed hooks above state, and the walk is the same either way.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ChainHook = (arg0: string, context: any, next: any) => unknown;
+
+/** The conditions a `require` resolves under, as Node's `getCjsConditions()` reports them. */
+const CJS_CONDITIONS = ['node', 'require', 'module-sync'];
+
+/**
+ * Node's own `import()` conditions. The engine resolves an import the way it
+ * resolves a require, so this is what a hook is told, not a second resolver.
+ */
+const ESM_CONDITIONS = ['node', 'import'];
+
+export class RunModuleHooks {
+  /** The vendored file's own instance, this run's alone. */
+  readonly sync: CustomizationHooks = loadNodeLibInstance('internal/modules/customization_hooks') as CustomizationHooks;
+  #resolveChain: Link<AsyncResolveHook>[] = [];
+  #loadChain: Link<AsyncLoadHook>[] = [];
+  #initializing: Promise<unknown>[] = [];
+  #initializeFailure: unknown;
+
+  /**
+   * Which chain has anything in it. The loader asks before it builds
+   * anything: a run that registered no hook pays for none, which is the fast
+   * path Node keeps in `Module._load` and `loadSource` too.
+   */
+  get hasSyncResolve(): boolean { return this.sync.resolveHooks.length > 0; }
+  get hasSyncLoad(): boolean { return this.sync.loadHooks.length > 0; }
+  get hasAsyncResolve(): boolean { return this.#resolveChain.length > 0; }
+  get hasAsyncLoad(): boolean { return this.#loadChain.length > 0; }
+
+  /**
+   * `module.register(specifier[, parentURL][, options])`.
+   *
+   * The argument shuffle is Node's own (`internal/modules/esm/loader.js`): a
+   * second argument that is an object and not a URL is the options. The hook
+   * module is loaded through the engine's own loader, which is what answers a
+   * `data:` URL, a `file:` URL and a bare specifier alike.
+   */
+  register(
+    specifier: unknown,
+    parentURL: unknown,
+    options: { parentURL?: unknown; data?: unknown; transferList?: unknown } | undefined,
+    load: (specifier: string, from: string) => unknown,
+  ): void {
+    if (parentURL != null && typeof parentURL === 'object' && !(parentURL instanceof URL)) {
+      options = parentURL as { parentURL?: unknown; data?: unknown };
+      parentURL = (options as { parentURL?: unknown }).parentURL;
+    }
+    const from = parentURL === undefined || parentURL === null ? 'data:' : String(parentURL);
+    const url = String(specifier);
+    const exports = load(url, from) as Record<string, unknown> | undefined;
+    this.addLoader(url, exports, options?.data);
+  }
+
+  /**
+   * `Hooks.addCustomLoader`: the three names a hook module may export, each
+   * onto its chain, and `initialize` called with the data.
+   */
+  addLoader(url: string, exports: Record<string, unknown> | undefined, data: unknown): void {
+    const initialize = exports?.initialize as ((data: unknown) => unknown) | undefined;
+    const resolve = exports?.resolve as AsyncResolveHook | undefined;
+    const load = exports?.load as AsyncLoadHook | undefined;
+    if (typeof resolve === 'function') {
+      this.#resolveChain.push({ fn: resolve, url, next: this.#resolveChain[this.#resolveChain.length - 1] });
+    }
+    if (typeof load === 'function') {
+      this.#loadChain.push({ fn: load, url, next: this.#loadChain[this.#loadChain.length - 1] });
+    }
+    if (typeof initialize === 'function') {
+      const settling = initialize(data);
+      if (settling && typeof (settling as Promise<unknown>).then === 'function') {
+        // Node's `register()` has already blocked on the hooks thread by the
+        // time it returns, so an `initialize` that throws throws there. Here
+        // the first resolution the chain serves waits for it instead, and a
+        // rejection is kept rather than left to reach the process as an
+        // unhandled rejection nothing is waiting on: every resolution from
+        // then on fails with it, which is the state Node would have refused
+        // to register in.
+        this.#initializing.push((settling as Promise<unknown>).then(
+          () => void 0,
+          (error: unknown) => { this.#initializeFailure ??= error; },
+        ));
+      }
+    }
+  }
+
+  /** Every `initialize` still settling, awaited before the chain serves anything. */
+  async ready(): Promise<void> {
+    while (this.#initializing.length > 0) {
+      const settling = this.#initializing.slice();
+      this.#initializing.length = 0;
+      await Promise.all(settling);
+    }
+    if (this.#initializeFailure !== undefined) throw this.#initializeFailure;
+  }
+
+  /**
+   * The resolve chain of `module.register`, awaited. `defaultResolve` is the
+   * engine's own resolution, the bottom of the chain.
+   */
+  async resolve(
+    specifier: string,
+    parentURL: string | undefined,
+    importAttributes: Record<string, string> | undefined,
+    defaultResolve: (specifier: string, context: ResolveContext) => ResolveResult | Promise<ResolveResult>,
+  ): Promise<ResolveResult> {
+    await this.ready();
+    const context: ResolveContext = { conditions: ESM_CONDITIONS, importAttributes, parentURL };
+    const result = await this.#run(this.#resolveChain, 'resolve', context, specifier, defaultResolve as never);
+    if (typeof (result as ResolveResult).url !== 'string') {
+      throw invalidReturnProperty('a URL string', 'resolve', 'url', (result as ResolveResult).url);
+    }
+    return result as ResolveResult;
+  }
+
+  /** The load chain of `module.register`, awaited. */
+  async load(
+    url: string,
+    format: string | undefined,
+    importAttributes: Record<string, string> | undefined,
+    defaultLoad: (url: string, context: LoadContext) => LoadResult | Promise<LoadResult>,
+  ): Promise<LoadResult> {
+    await this.ready();
+    const context: LoadContext = { conditions: ESM_CONDITIONS, format, importAttributes };
+    return await this.#run(this.#loadChain, 'load', context, url, defaultLoad as never) as LoadResult;
+  }
+
+  /**
+   * `nextHookFactory`: the chain walked from the top, each hook handed the one
+   * below it, the bottom the default step. A hook that returns without calling
+   * the next one and without `shortCircuit: true` has broken the chain, and
+   * Node says so rather than quietly honouring it.
+   */
+  async #run<T extends object>(
+    chain: Link<ChainHook>[],
+    name: 'resolve' | 'load',
+    context: object,
+    arg0: string,
+    defaultStep: (arg0: string, context: object) => T | Promise<T>,
+  ): Promise<T> {
+    const meta = { chainFinished: false, shortCircuited: false, identifier: '' };
+    const nextName = name === 'resolve' ? 'nextResolve' : 'nextLoad';
+    const build = (current?: Link<ChainHook>): (arg0: string, ctx?: object) => Promise<T> => {
+      if (!current) {
+        return async (value: string, ctx?: object): Promise<T> => {
+          meta.chainFinished = true;
+          if (ctx && ctx !== context) Object.assign(context, ctx);
+          return await defaultStep(value, context);
+        };
+      }
+      const below = build(current.next);
+      return async (value: string, ctx?: object): Promise<T> => {
+        meta.identifier = `${current.url} '${name}'`;
+        if (typeof value !== 'string') {
+          throw invalidArgType(`${meta.identifier} hook's ${nextName}() specifier`, 'string', value);
+        }
+        if (ctx && ctx !== context) Object.assign(context, ctx);
+        const output = await current.fn(value, context, below) as T & { shortCircuit?: boolean };
+        if (typeof output !== 'object' || output === null) {
+          throw invalidReturnValue('an object', `${meta.identifier} hook's ${nextName}()`, output);
+        }
+        if (output.shortCircuit === true) meta.shortCircuited = true;
+        return output;
+      };
+    };
+    const top = build(chain[chain.length - 1]);
+    const output = await top(arg0, context);
+    if (!meta.chainFinished && !meta.shortCircuited) {
+      const error = new Error(
+        `The ${name} hook from ${meta.identifier} did not call the next hook in its chain and did not ` +
+        "explicitly signal a short circuit. If this is intentional, include `shortCircuit: true` in the hook's return.",
+      );
+      throw Object.assign(error, { code: 'ERR_LOADER_CHAIN_INCOMPLETE' });
+    }
+    return output;
+  }
+}
+
+function invalidReturnProperty(expected: string, name: string, property: string, value: unknown): Error {
+  const error = new TypeError(
+    `Expected ${expected} to be returned for the "${property}" from the "${name}" function but got ${String(value)}.`,
+  );
+  return Object.assign(error, { code: 'ERR_INVALID_RETURN_PROPERTY_VALUE' });
+}
+
+function invalidReturnValue(expected: string, name: string, value: unknown): Error {
+  const error = new TypeError(`Expected ${expected} to be returned from the "${name}" function but got ${String(value)}.`);
+  return Object.assign(error, { code: 'ERR_INVALID_RETURN_VALUE' });
+}
+
+function invalidArgType(name: string, expected: string, value: unknown): Error {
+  const error = new TypeError(`The "${name}" argument must be of type ${expected}. Received ${String(value)}`);
+  return Object.assign(error, { code: 'ERR_INVALID_ARG_TYPE' });
+}
+
+export { CJS_CONDITIONS, ESM_CONDITIONS };
+export type { ResolveContext, LoadContext };