@volter/tabnode 0.2.14-volter.88

package/src/node-lib/internals/modules.ts

@@ -0,0 +1,117 @@
+/**
+ * The internals Node's `internal/modules/customization_hooks.js` names.
+ *
+ * Each object holds exactly the names that file destructures from it. Node's
+ * real `internal/bootstrap/realm` is the builtin loader of a Node process --
+ * a snapshot, a compile cache and every `lib/` file -- and what the hooks file
+ * takes from it is two questions about a name: is this something a program can
+ * require, and what is its canonical id. The engine answers both from the same
+ * list its `module.builtinModules` reports, so a hook that reads `node:fs`
+ * reads the name the guest's own `module.isBuiltin` agrees with.
+ */
+import * as moduleShim from '../../shims/module';
+import { fileURLToPath, pathToFileURL } from '../../shims/url';
+
+/**
+ * `internal/bootstrap/realm`'s `BuiltinModule`, the two class methods the
+ * hooks file calls to turn a CommonJS filename into a URL and back.
+ */
+export const internalBootstrapRealm = {
+  BuiltinModule: {
+    /**
+     * Whether a normalized id (no `node:`) is a builtin a program may require.
+     * Node asks this of a filename to decide whether it is `node:<id>` rather
+     * than a path; a name the engine does not answer is a path or nothing.
+     */
+    canBeRequiredByUsers(id: string): boolean {
+      return moduleShim.builtinModules.includes(id);
+    },
+    /**
+     * The canonical id of a requirable builtin, `node:` prefix or not, and
+     * undefined for anything else -- a `file:` URL, a path, a bare package
+     * name. Node returns undefined rather than throwing, and the hooks file
+     * tests the result rather than catching.
+     */
+    normalizeRequirableId(id: string): string | undefined {
+      if (typeof id !== 'string') return void 0;
+      const name = id.startsWith('node:') ? id.slice(5) : id;
+      return moduleShim.builtinModules.includes(name) ? name : void 0;
+    },
+    /**
+     * Whether `id` is a compiled builtin, which `internal/util/inspect`
+     * asks of every `node:` stack frame when it colorizes an Error. Node's
+     * class answers from the realm's module map; the engine answers from
+     * the same list `canBeRequiredByUsers` reads, plus `internal/` files
+     * inspect also greys. The method was missing, so a pipe child that
+     * still had FORCE_COLOR threw `exists is not a function` while printing
+     * an assertion and the test exited 1.
+     */
+    exists(id: string): boolean {
+      if (typeof id !== 'string') return false;
+      const name = id.startsWith('node:') ? id.slice(5) : id;
+      return name.startsWith('internal/') || moduleShim.builtinModules.includes(name);
+    },
+  },
+};
+
+/**
+ * `internal/url`: the conversions between a path and a URL that the hooks
+ * file makes, and the three names `_http_client.js` and `https.js` take to
+ * turn a URL into the options a request is made from.
+ */
+export const internalUrl = {
+  fileURLToPath,
+  pathToFileURL,
+  /**
+   * Node's `toPathIfFileURL`: `fs` takes a path or a `file:` URL for every
+   * one of its calls, and this is the one line that turns the second into
+   * the first. Anything else is handed on untouched, for `fs` to validate.
+   */
+  toPathIfFileURL: (value: unknown): unknown => {
+    if (value instanceof URL) return fileURLToPath(value);
+    if (typeof value === 'string' && value.startsWith('file://')) return fileURLToPath(value);
+    return value;
+  },
+  get URL() { return (globalThis as unknown as { URL: unknown }).URL; },
+  /** Node's `isURL`: a `URL` of this realm, or one shaped like it. */
+  isURL: (value: unknown): boolean =>
+    value instanceof URL ||
+    (value !== null && typeof value === 'object' &&
+      typeof (value as { href?: unknown }).href === 'string' &&
+      typeof (value as { origin?: unknown }).origin === 'string' &&
+      typeof (value as { protocol?: unknown }).protocol === 'string'),
+  /**
+   * Node's `urlToHttpOptions`: the request options a `URL` stands for. The
+   * rules are Node's own -- an IPv6 host loses its brackets, the path is the
+   * pathname and the search together, and a password without a user is still
+   * an auth pair.
+   */
+  urlToHttpOptions: (url: URL): Record<string, unknown> => {
+    const options: Record<string, unknown> = {
+      protocol: url.protocol,
+      hostname: typeof url.hostname === 'string' && url.hostname.startsWith('[')
+        ? url.hostname.slice(1, -1)
+        : url.hostname,
+      hash: url.hash,
+      search: url.search,
+      pathname: url.pathname,
+      path: `${url.pathname || ''}${url.search || ''}`,
+      href: url.href,
+    };
+    if (url.port !== '') options.port = Number(url.port);
+    if (url.username || url.password) {
+      options.auth = `${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`;
+    }
+    return options;
+  },
+};
+
+/**
+ * `internal/encoding`: the realm's own `TextDecoder`. The hooks file decodes
+ * an `ArrayBuffer` or a typed array a load hook returned into the source
+ * string the loader compiles.
+ */
+export const internalEncoding = {
+  get TextDecoder() { return (globalThis as unknown as { TextDecoder: unknown }).TextDecoder; },
+  get TextEncoder() { return (globalThis as unknown as { TextEncoder: unknown }).TextEncoder; },
+};

package/src/node-lib/internals/readline-access.ts

@@ -0,0 +1,16 @@
+/**
+ * The engine's `readline`, read on the first ask.
+ *
+ * `internal/fs/promises.js` takes `Interface` from `internal/readline/
+ * interface` at its top, so every use of `fs/promises` needs the class.
+ * `readline`'s own `Interface` extends the vendored `EventEmitter`, and this
+ * file is on the loader's path, so the name is read when it is wanted rather
+ * than when this module is evaluated -- the rule `../lazy.ts` states.
+ */
+import { nodeLibInternalRequire } from '../load';
+
+export function readlineModule(): Record<string, unknown> {
+  // Node's own `internal/readline/interface` is vendored now, so the name
+  // resolves to that file rather than to the engine's shim.
+  return nodeLibInternalRequire('internal/readline/interface') as Record<string, unknown>;
+}

package/src/node-lib/internals/runtime.ts

@@ -0,0 +1,277 @@
+/**
+ * The internals Node's `net` names that are neither vendored nor a binding:
+ * async ids, timers, stream defaults, the option table, and the three
+ * one-line answers (`assert`, `hasObserver`, `isBuildingSnapshot`).
+ *
+ * Each object holds exactly the names the vendored files destructure.
+ */
+
+/**
+ * `internal/async_hooks`. The engine has no async-hooks graph, so an id is a
+ * number nobody follows and a trigger scope is the call itself. The two
+ * symbols matter and are real: `owner_symbol` is how a handle finds its
+ * stream — `onStreamRead` reads `this[owner_symbol]` on every chunk — and
+ * `async_id_symbol` is where `net.js` keeps a socket's id.
+ */
+let nextAsyncId = 1;
+const symbols = {
+  async_id_symbol: Symbol('async_id_symbol'),
+  trigger_async_id_symbol: Symbol('trigger_async_id_symbol'),
+  owner_symbol: Symbol('owner_symbol'),
+  init_symbol: Symbol('init_symbol'),
+  destroy_symbol: Symbol('destroy_symbol'),
+  async_id_fields: Symbol('async_id_fields'),
+};
+
+export const internalAsyncHooks = {
+  symbols,
+  newAsyncId: (): number => nextAsyncId++,
+  /**
+   * Node's `getOrSetAsyncId`: the id an object already carries, or a new one
+   * put on it. `_http_server.js` asks it of every socket it accepts, to name
+   * the scope the connection listener runs in.
+   */
+  getOrSetAsyncId: (object: Record<symbol, unknown>): number => {
+    const key = symbols.async_id_symbol;
+    if (Object.prototype.hasOwnProperty.call(object, key)) return object[key] as number;
+    object[key] = nextAsyncId++;
+    return object[key] as number;
+  },
+  getDefaultTriggerAsyncId: (): number => 0,
+  defaultTriggerAsyncIdScope: <A extends unknown[], R>(
+    _triggerAsyncId: number, block: (...args: A) => R, ...args: A
+  ): R => block(...args),
+  initHooksExist: (): boolean => false,
+  afterHooksExist: (): boolean => false,
+  destroyHooksExist: (): boolean => false,
+  emitInit: (): void => {},
+  emitBefore: (): void => {},
+  emitAfter: (): void => {},
+  emitDestroy: (): void => {},
+  hasAsyncIdStack: (): boolean => false,
+  registerDestroyHook: (): void => {},
+};
+
+/**
+ * Node's `AsyncResource`, which `events.js` extends to build
+ * `EventEmitterAsyncResource`. A tab has no async-hooks graph, so an id is a
+ * number nobody follows -- but it is a real positive id, because a program
+ * that asks `asyncId` of a resource, as Node's own tests do, must see one.
+ * Served through `require('async_hooks')` so the vendored file can extend it;
+ * the class lives here, never in that file.
+ */
+let nextAsyncResourceId = 1;
+export class AsyncResource {
+  #asyncId: number;
+  #triggerAsyncId: number;
+
+  constructor(_type: string, options?: { triggerAsyncId?: number; requireManualDestroy?: boolean }) {
+    this.#asyncId = nextAsyncResourceId++;
+    this.#triggerAsyncId = options?.triggerAsyncId ?? 0;
+  }
+
+  runInAsyncScope<T>(fn: (...args: never[]) => T, thisArg?: unknown, ...args: never[]): T {
+    return fn.apply(thisArg, args);
+  }
+
+  emitDestroy(): this { return this; }
+  asyncId(): number { return this.#asyncId; }
+  triggerAsyncId(): number { return this.#triggerAsyncId; }
+
+  static bind<T extends (...args: never[]) => unknown>(fn: T, _type?: string): T {
+    return fn;
+  }
+}
+
+/**
+ * `internal/timers`. Only `setStreamTimeout` in
+ * `internal/stream_base_commons.js` uses it, for `socket.setTimeout`, and
+ * Node's timer for that is unref'd: a socket's idle timeout never holds a
+ * process open. The engine counts a guest's own timers to decide whether a
+ * program is still working, and a timer made here is made with the realm's
+ * own `setTimeout` rather than the guest's view of it, so it is not counted —
+ * which is exactly what unref'd means.
+ */
+const kTimeout = Symbol('timeout');
+
+/** The realm's own timer, never the guest's counted one. */
+function realmSetTimeout(fn: () => void, ms: number): unknown {
+  const realm = globalThis as unknown as {
+    __browserRuntimeNativeSetTimeout?: (fn: () => void, ms: number) => unknown;
+  };
+  return (realm.__browserRuntimeNativeSetTimeout ?? globalThis.setTimeout).call(globalThis, fn, ms);
+}
+function realmClearTimeout(id: unknown): void {
+  const realm = globalThis as unknown as {
+    __browserRuntimeNativeClearTimeout?: (id: unknown) => void;
+  };
+  (realm.__browserRuntimeNativeClearTimeout ?? globalThis.clearTimeout).call(globalThis, id as number);
+}
+
+/**
+ * What `setUnrefTimeout` answers: a timer that can be refreshed in place, as
+ * Node's `Timeout` can, and that `timers.clearTimeout` here knows how to stop.
+ */
+export class UnrefTimeout {
+  private id: unknown = null;
+  private readonly onTimeout: () => void;
+  private readonly msecs: number;
+
+  constructor(onTimeout: () => void, msecs: number) {
+    this.onTimeout = onTimeout;
+    this.msecs = msecs;
+    this.id = realmSetTimeout(() => { this.id = null; this.onTimeout(); }, msecs);
+  }
+
+  refresh(): this {
+    if (this.id !== null) realmClearTimeout(this.id);
+    this.id = realmSetTimeout(() => { this.id = null; this.onTimeout(); }, this.msecs);
+    return this;
+  }
+
+  stop(): void {
+    if (this.id !== null) realmClearTimeout(this.id);
+    this.id = null;
+  }
+
+  ref(): this { return this; }
+  unref(): this { return this; }
+  hasRef(): boolean { return false; }
+}
+
+export const TIMEOUT_MAX = 2 ** 31 - 1;
+
+export const internalTimers = {
+  kTimeout,
+  TIMEOUT_MAX,
+  setUnrefTimeout: (fn: () => void, msecs: number): UnrefTimeout => new UnrefTimeout(fn, msecs),
+  /** Node's `getTimerDuration`: a number in range, and 1 for anything under it. */
+  getTimerDuration(msecs: unknown, name: string): number {
+    if (typeof msecs !== 'number') {
+      throw Object.assign(new TypeError(`The "${name}" argument must be of type number. Received ${typeof msecs}`), { code: 'ERR_INVALID_ARG_TYPE' });
+    }
+    if (msecs < 0 || !Number.isFinite(msecs)) {
+      throw Object.assign(new RangeError(`The value of "${name}" is out of range. It must be a non-negative finite number. Received ${msecs}`), { code: 'ERR_OUT_OF_RANGE' });
+    }
+    if (msecs === 0) return 0;
+    if (msecs > TIMEOUT_MAX) return 1;
+    return msecs < 1 ? 1 : msecs;
+  },
+};
+
+/** `internal/streams/state`: Node's default high-water marks. */
+export const internalStreamsState = {
+  getDefaultHighWaterMark: (objectMode?: boolean): number => (objectMode ? 16 : 65536),
+  setDefaultHighWaterMark: (): void => {},
+};
+
+/** `internal/process/task_queues`: the realm's own microtask queue. */
+export const internalTaskQueues = {
+  queueMicrotask: (fn: () => void): void => queueMicrotask(fn),
+  setHasTickScheduled: (): void => {},
+  runNextTicks: (): void => {},
+};
+
+/** `internal/event_target`: the one symbol `abort_listener.js` reads. */
+// Registry symbols, not unique ones: the engine's bundle can be evaluated
+// more than once in a realm -- a page's copy and a worker's -- and each
+// evaluation would otherwise mint its own key. The default below was defined
+// under one key and `events.js` read another, so a fresh `EventTarget`
+// answered nothing while one that had been set answered fine.
+const kEventsSymbol = Symbol.for('nodejs.event_target.events');
+// Every `EventTarget` answers the symbol above with an empty map, for the
+// reason given on `kEvents` below. One getter on the prototype, installed
+// where the binding is defined rather than inside a guest's realm, because
+// `events.js` reads it off whatever target it was handed.
+if (typeof EventTarget === 'function' && !(kEventsSymbol in EventTarget.prototype)) {
+  const empty = new Map<unknown, unknown>();
+  Object.defineProperty(EventTarget.prototype, kEventsSymbol, { get: () => empty, configurable: true });
+}
+
+export const internalEventTarget = {
+  kResistStopPropagation: Symbol('kResistStopPropagation'),
+  /** `internal/streams/operators.js` marks its abort listener weak with this. */
+  kWeakHandler: Symbol('kWeakHandler'),
+  /**
+   * Whether a thing is an `EventTarget`. `events.js` asks before it treats a
+   * value as one -- `once`, `on`, `getEventListeners` and `setMaxListeners`
+   * all take either an emitter or a target. Node's own `EventTarget` is a
+   * class in `internal/event_target.js`; the engine's is the realm's, which
+   * is where that class comes from in the first place.
+   */
+  isEventTarget: (value: unknown): boolean =>
+    typeof EventTarget === 'function' && value instanceof EventTarget,
+  /**
+   * The map Node keeps its own EventTarget's listeners in.
+   *
+   * THE LOSS, named: the realm's `EventTarget` keeps its listeners where no
+   * JavaScript can reach them. The DOM has no way to ask what is listening --
+   * `addEventListener` is a door in, and there is no door out -- so
+   * `events.getEventListeners(target)` cannot answer for one. It reads this
+   * map unguarded, so every target answers with an empty one: the call
+   * reports no listeners rather than throwing at a program that asked a fair
+   * question. An `EventEmitter` is unaffected; it answers from its own
+   * `listeners()`, which is the branch above this one in `events.js`.
+   */
+  kEvents: kEventsSymbol,
+  kNewListener: Symbol('kNewListener'),
+  kRemoveListener: Symbol('kRemoveListener'),
+};
+
+/**
+ * `internal/options`: the command-line options Node's `net` reads. The engine
+ * takes no command line of its own, so each is Node's own default.
+ */
+const optionValues: Record<string, unknown> = {
+  '--network-family-autoselection': true,
+  '--network-family-autoselection-attempt-timeout': 250,
+  '--no-deprecation': false,
+  '--throw-deprecation': false,
+  '--trace-deprecation': false,
+  '--pending-deprecation': false,
+  '--report-uncaught-exception': false,
+  '--experimental-print-required-tla': false,
+};
+
+export const internalOptions = {
+  getOptionValue: (name: string): unknown => optionValues[name],
+  getEmbedderOptions: () => ({ shouldNotRegisterESMLoader: false, noGlobalSearchPaths: false, noBrowserGlobals: false }),
+};
+
+/** `internal/perf/observe`: nothing observes `net` in the engine. */
+export const internalPerfObserve = {
+  hasObserver: (): boolean => false,
+  startPerf: (): void => {},
+  stopPerf: (): void => {},
+};
+
+/** `internal/assert`: Node's internal assertion, which no program should ever see. */
+export function internalAssert(value: unknown, message?: string): asserts value {
+  if (!value) throw new Error(`Internal assertion failed${message ? `: ${message}` : ''}`);
+}
+internalAssert.fail = (message?: string): never => {
+  throw new Error(`Internal assertion failed${message ? `: ${message}` : ''}`);
+};
+internalAssert.ok = internalAssert;
+
+/** `internal/v8/startup_snapshot`: the engine never builds one. */
+export const internalStartupSnapshot = {
+  namespace: {
+    isBuildingSnapshot: (): boolean => false,
+    addSerializeCallback: (): void => {},
+    addDeserializeCallback: (): void => {},
+    setDeserializeMainFunction: (): void => {},
+  },
+  runDeserializeCallbacks: (): void => {},
+};
+
+/**
+ * `internal/process/permission`: the engine runs no permission model, so
+ * nothing is denied and there are no flags for `child_process.js` to copy
+ * into a child's `NODE_OPTIONS`.
+ */
+export const internalPermission = {
+  isEnabled: (): boolean => false,
+  has: (): boolean => true,
+  availableFlags: (): string[] => [],
+};

package/src/node-lib/internals/util.ts

@@ -0,0 +1,98 @@
+/**
+ * `internal/util/types`, bound by hand -- which is also `util.types`, because
+ * Node's `util.types` IS this module.
+ *
+ * Node's own is `internalBinding('types')`, V8 asking a value what it is from
+ * the outside. The engine asks the one question a tab can ask: the value's
+ * own `Object.prototype.toString` tag, which V8 fills in from the same
+ * internal type and which a program cannot forge without saying so. A
+ * `Symbol.toStringTag` a program sets IS such a statement, and Node's answer
+ * and this one differ only for an object that has lied about itself.
+ *
+ * Two exceptions, each for a reason a tab cannot get around:
+ *
+ * A `Proxy` shows the tag of the thing it wraps, by design, so no tag can
+ * find one. The engine's realm records every proxy it makes -- `runtime.ts`
+ * replaces the realm's `Proxy` for a guest -- and `isProxy` answers from that
+ * record. undici's `Headers` guard asks it of every init it converts, and a
+ * proxy the host made before the guest's realm existed is not in the record.
+ *
+ * `isExternal` is always false: nothing in a tab is a native handle.
+ *
+ * `internal/util` itself is no longer here: it is Node's own file now, and
+ * every name the vendored files used to take from a hand-bound object is
+ * Node's own code, on the bindings under `../binding/`.
+ */
+
+/**
+ * Every proxy a guest's realm has made. `runtime.ts` fills it, from the
+ * `Proxy` it installs for a guest; this module reads it.
+ */
+export const recordedProxies = new WeakSet<object>();
+
+const tagOf = (value: unknown): string => Object.prototype.toString.call(value);
+
+/** The `size` getters, which need a real Map or Set behind `this`. */
+const mapSize = Object.getOwnPropertyDescriptor(Map.prototype, 'size')?.get as () => number;
+const setSize = Object.getOwnPropertyDescriptor(Set.prototype, 'size')?.get as () => number;
+
+/**
+ * Whether a value carries the internal slot a built-in method needs. Calling
+ * the method is the only test of a slot JavaScript has, and a value without
+ * one throws rather than answering -- which is the answer.
+ */
+function hasSlot(value: unknown, method: (...args: never[]) => unknown, args: unknown[] = []): boolean {
+  if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return false;
+  try { (method as (...a: unknown[]) => unknown).apply(value, args); return true; } catch { return false; }
+}
+const taggedAs = (tag: string) => (value: unknown): boolean => tagOf(value) === tag;
+
+/** `internal/util/types`, which is `util.types`. */
+export const internalUtilTypes: Record<string, (value: unknown) => boolean> = {
+  isArgumentsObject: taggedAs('[object Arguments]'),
+  isArrayBuffer: taggedAs('[object ArrayBuffer]'),
+  isSharedArrayBuffer: taggedAs('[object SharedArrayBuffer]'),
+  isAnyArrayBuffer: (value) => tagOf(value) === '[object ArrayBuffer]' || tagOf(value) === '[object SharedArrayBuffer]',
+  isArrayBufferView: (value) => ArrayBuffer.isView(value),
+  isDataView: taggedAs('[object DataView]'),
+  isTypedArray: (value) => ArrayBuffer.isView(value) && tagOf(value) !== '[object DataView]',
+  isUint8Array: taggedAs('[object Uint8Array]'),
+  isAsyncFunction: taggedAs('[object AsyncFunction]'),
+  isGeneratorFunction: (value) => tagOf(value) === '[object GeneratorFunction]' || tagOf(value) === '[object AsyncGeneratorFunction]',
+  isGeneratorObject: (value) => tagOf(value) === '[object Generator]' || tagOf(value) === '[object AsyncGenerator]',
+  isRegExp: taggedAs('[object RegExp]'),
+  isMapIterator: taggedAs('[object Map Iterator]'),
+  isSetIterator: taggedAs('[object Set Iterator]'),
+  isModuleNamespaceObject: taggedAs('[object Module]'),
+  isPromise: taggedAs('[object Promise]'),
+  isNativeError: (value) => value instanceof Error && tagOf(value) === '[object Error]',
+  // A boxed primitive is asked the one question only a real one can answer:
+  // its own prototype's `valueOf` needs the internal slot and throws without
+  // it. A tag would say yes to `Object.create(String.prototype)`, which has
+  // no slot at all, and `isDeepStrictEqual` then compared it as a string and
+  // threw where Node answered.
+  isBooleanObject: (value) => hasSlot(value, Boolean.prototype.valueOf),
+  isNumberObject: (value) => hasSlot(value, Number.prototype.valueOf),
+  isStringObject: (value) => hasSlot(value, String.prototype.valueOf),
+  isSymbolObject: (value) => hasSlot(value, Symbol.prototype.valueOf),
+  isBigIntObject: (value) => hasSlot(value, BigInt.prototype.valueOf),
+  isDate: (value) => hasSlot(value, Date.prototype.valueOf),
+  isMap: (value) => hasSlot(value, mapSize),
+  isSet: (value) => hasSlot(value, setSize),
+  isWeakMap: (value) => hasSlot(value, WeakMap.prototype.has, ['x']),
+  isWeakSet: (value) => hasSlot(value, WeakSet.prototype.has, ['x']),
+  isKeyObject: () => false,
+  isCryptoKey: (value) => typeof CryptoKey !== 'undefined' && value instanceof CryptoKey,
+  isExternal: () => false,
+  isProxy: (value) => (typeof value === 'object' || typeof value === 'function') && value !== null && recordedProxies.has(value as object),
+};
+
+internalUtilTypes.isBoxedPrimitive = (value) =>
+  internalUtilTypes.isBooleanObject(value) || internalUtilTypes.isNumberObject(value) ||
+  internalUtilTypes.isStringObject(value) || internalUtilTypes.isSymbolObject(value) ||
+  internalUtilTypes.isBigIntObject(value);
+
+for (const name of ['Uint8Array', 'Uint8ClampedArray', 'Uint16Array', 'Uint32Array', 'Int8Array', 'Int16Array',
+  'Int32Array', 'Float16Array', 'Float32Array', 'Float64Array', 'BigInt64Array', 'BigUint64Array']) {
+  internalUtilTypes[`is${name}`] = taggedAs(`[object ${name}]`);
+}

package/src/node-lib/lazy.ts

@@ -0,0 +1,158 @@
+/**
+ * A vendored Node module, and a class out of one, named before the loader can
+ * build it.
+ *
+ * The engine's own TypeScript imports `Buffer` and `Readable` the way any
+ * program does -- as values, at the top of a file. But `buffer` and `stream`
+ * are vendored Node files that `./load.ts` builds out of the binding and the
+ * internals, and several of the engine's own shims are what that loader
+ * resolves a public name to: the two sit in one import cycle, and which side a
+ * bundler evaluates first is its own decision, not a thing the source can
+ * state. Taking the class at import time therefore failed to load the engine
+ * at all, differently on each build.
+ *
+ * So a name here stands for the thing rather than being it, until the first
+ * time anyone touches it. `Buffer.from(…)` is one property read through a
+ * proxy and then the real call; `x instanceof Buffer` reads the real class's
+ * `Symbol.hasInstance`; `new Readable()` constructs the real one. Node's own
+ * files never go through this -- they `require('buffer')` and get the class.
+ */
+// The loader itself, not the hook a binding uses: importing it is what puts
+// it in the graph at all, so a program that only ever touches `Readable`
+// still has a loader to build it with.
+import { nodeLibInternalRequire } from './load';
+
+
+/** The module a name stands for, loaded once, on the first property read. */
+function loadedModule(name: string, cache: { value?: Record<string, unknown> }): Record<string, unknown> {
+  return cache.value ??= nodeLibInternalRequire(name) as Record<string, unknown>;
+}
+
+/**
+ * A vendored module object, whose properties are read when they are asked for.
+ *
+ * A module object is a program's to write on, and packages do: `graceful-fs`
+ * -- which half of npm loads, openvscode-server through `fs-extra` and
+ * `@vscode/deviceid` -- defines `Symbol.for('graceful-fs.queue')` on `fs` with
+ * `Object.defineProperty` and then clones the module, which walks its keys.
+ * Every trap here read the loaded module and none read the proxy's own target,
+ * where a define with no trap of its own lands: the read came back
+ * `undefined`, `key in fs` answered false, and `Reflect.ownKeys(fs)` threw
+ * `'ownKeys' on proxy: trap result did not include
+ * 'Symbol(graceful-fs.queue)'` -- a proxy may neither hide nor deny a
+ * non-configurable own key of its target. graceful-fs threw out of its own
+ * module load, so every program that loads it died there: in the substrate's
+ * tab, openvscode-server's server at boot and its extension host, which exited
+ * 1 without a word because a forked host's console goes to its parent over IPC
+ * and the server drops those messages.
+ *
+ * So a define lands on the module, as it would in Node, and a
+ * non-configurable one lands on the target as well because the proxy has to
+ * report it from there; every read answers the target first and the module
+ * after. This is the shape the guest global's proxy in `src/runtime.ts` uses,
+ * for the same reason.
+ */
+export function lazyModule<T extends object>(name: string): T {
+  const cache: { value?: Record<string, unknown> } = {};
+  const own = (target: object, key: PropertyKey): boolean =>
+    Reflect.getOwnPropertyDescriptor(target, key) !== undefined;
+  return new Proxy({} as T, {
+    get: (target, key, receiver) => (own(target, key)
+      ? Reflect.get(target, key, receiver)
+      : Reflect.get(loadedModule(name, cache), key)),
+    set: (target, key, value, receiver) => (own(target, key)
+      ? Reflect.set(target, key, value, receiver)
+      : Reflect.set(loadedModule(name, cache), key, value)),
+    has: (target, key) => own(target, key) || Reflect.has(loadedModule(name, cache), key),
+    defineProperty: (target, key, descriptor) => {
+      const module = loadedModule(name, cache);
+      if (descriptor.configurable === false) {
+        if (!Reflect.defineProperty(target, key, descriptor)) return false;
+        Reflect.defineProperty(module, key, { ...descriptor, configurable: true });
+        return true;
+      }
+      return Reflect.defineProperty(module, key, descriptor)
+        || Reflect.defineProperty(target, key, descriptor);
+    },
+    deleteProperty: (target, key) => {
+      if (own(target, key) && !Reflect.deleteProperty(target, key)) return false;
+      return Reflect.deleteProperty(loadedModule(name, cache), key);
+    },
+    ownKeys: (target) => {
+      const keys = Reflect.ownKeys(target);
+      for (const key of Reflect.ownKeys(loadedModule(name, cache))) if (!keys.includes(key)) keys.push(key);
+      return keys;
+    },
+    getOwnPropertyDescriptor: (target, key) => {
+      const mine = Reflect.getOwnPropertyDescriptor(target, key);
+      if (mine !== undefined) return mine;
+      const descriptor = Reflect.getOwnPropertyDescriptor(loadedModule(name, cache), key);
+      return descriptor === undefined ? undefined : { ...descriptor, configurable: true };
+    },
+  }) as T;
+}
+
+/**
+ * One export of a vendored module that is a class or a function: callable,
+ * constructible, and the same object to `instanceof` as the real one.
+ */
+export function lazyExport<T>(name: string, key: string): T {
+  const cache: { value?: Record<string, unknown> } = {};
+  // The prototype a subclass takes when it is DEFINED. `class Socket extends
+  // EventEmitter` reads `EventEmitter.prototype` at the moment the class is
+  // written, which is while the bundle is still evaluating -- before the
+  // loader, its bindings, or the shims those bindings read have run their own
+  // bodies, and several of them are in one import cycle with this file (the
+  // `constants` binding reads the `crypto` shim, which is an EventEmitter).
+  // Loading there is not late, it is impossible. So a class defined that early
+  // is given this empty object as its parent prototype, and the first time the
+  // real class is built the object is grafted onto the real prototype: the
+  // subclass's chain becomes `Subclass.prototype -> stand -> EventEmitter.
+  // prototype`, so every method resolves and `instanceof` holds. After the
+  // graft the real prototype is what is handed out, so an instance Node's own
+  // code made is an instance of the same class to everyone.
+  const stand = Object.create(null) as object;
+  let grafted = false;
+  const real = (): object => {
+    const value = loadedModule(name, cache)[key] as object;
+    if (!grafted) {
+      grafted = true;
+      const prototype = (value as { prototype?: object }).prototype;
+      if (prototype) Object.setPrototypeOf(stand, prototype);
+    }
+    return value;
+  };
+  // A plain function is the target because it is the one thing that is both
+  // callable and constructible; nothing of it is ever read.
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  const target = function stand() {} as unknown as object;
+  return new Proxy(target, {
+    get: (_t, propertyKey, receiver) => {
+      // Before the real class exists, `prototype` is the stand-in above; from
+      // the first load on it is the real one.
+      if (propertyKey === 'prototype' && !grafted && !cache.value) return stand;
+      return Reflect.get(real(), propertyKey, receiver);
+    },
+    set: (_t, propertyKey, value) => Reflect.set(real(), propertyKey, value),
+    has: (_t, propertyKey) => Reflect.has(real(), propertyKey),
+    getPrototypeOf: () => Reflect.getPrototypeOf(real()),
+    // A module whose exports IS this function -- `require("events")` is
+    // Node's `EventEmitter` -- is read as a module too: destructured,
+    // enumerated, asked for its own keys. The target's own `prototype`,
+    // `length` and `name` are non-configurable and must be reported as the
+    // target has them, so they are answered from the target and everything
+    // else from the real class.
+    ownKeys: () => {
+      const own = Reflect.ownKeys(target);
+      return [...Reflect.ownKeys(real()).filter((key) => !own.includes(key)), ...own];
+    },
+    getOwnPropertyDescriptor: (_t, propertyKey) => {
+      const fromTarget = Reflect.getOwnPropertyDescriptor(target, propertyKey);
+      if (fromTarget !== undefined) return fromTarget;
+      const own = Reflect.getOwnPropertyDescriptor(real(), propertyKey);
+      return own === undefined ? undefined : { ...own, configurable: true };
+    },
+    apply: (_t, thisArg, args) => Reflect.apply(real() as (...a: unknown[]) => unknown, thisArg, args as unknown[]),
+    construct: (_t, args, newTarget) => Reflect.construct(real() as new (...a: unknown[]) => object, args as unknown[], newTarget === target ? (real() as new (...a: unknown[]) => object) : newTarget),
+  }) as T;
+}