@scriptc/compiler 0.3.6 → 0.4.0

package/ambient/scriptc-node-fallback.d.ts

@@ -80,21 +80,54 @@ declare namespace NodeJS {
     path?: string | undefined;
     syscall?: string | undefined;
   }
-  /* The piped child-output stream (child.stdout / child.stderr under
-   * stdio ["ignore", "pipe", "pipe"]): 'data' fires one Buffer chunk per
-   * read (≤64KB, consumer-driven — no listener, no read), 'end' fires
-   * once at EOF and always BEFORE the child's 'exit'. A flowing stream
-   * keeps the loop alive. */
+  /* The readable-stream interface every Node stream implements. The
+   * piped child-output stream (child.stdout / child.stderr under stdio
+   * ["ignore", "pipe", "pipe"]) is declared with it: 'data' fires one
+   * Buffer chunk per read (≤64KB, consumer-driven — no listener, no
+   * read), 'end' fires once at EOF and always BEFORE the child's 'exit'. A
+   * flowing stream keeps the loop alive. A program that also passes
+   * other streams (fs, zlib, node:stream) where this interface is
+   * expected compiles it as the node:stream Readable, with child output
+   * bridged into one. */
   interface ReadableStream {
     on(event: "data", listener: (chunk: Buffer) => void): void;
     on(event: "data", listener: (chunk: string) => void): void;
     on(event: "end", listener: () => void): void;
+    on(event: string, listener: (...args: any[]) => void): void;
     once(event: "data", listener: (chunk: Buffer) => void): void;
     once(event: "data", listener: (chunk: string) => void): void;
     once(event: "end", listener: () => void): void;
+    once(event: string, listener: (...args: any[]) => void): void;
     /* setEncoding('utf8') makes subsequent data chunks strings, including
      * multibyte sequences split across native pipe reads. */
     setEncoding(encoding: string): this;
+    readonly readable: boolean;
+    pause(): this;
+    resume(): this;
+    isPaused(): boolean;
+    pipe<T extends WritableStream>(destination: T, options?: { end?: boolean }): T;
+    unpipe(destination?: WritableStream): this;
+    [Symbol.asyncIterator](): AsyncIterableIterator<string | Buffer>;
+  }
+  /* The writable-stream interface every Node stream implements:
+   * process.stdout/process.stderr, fs.WriteStream and the node:stream
+   * Writable family. Written only to the process streams, it compiles as
+   * their descriptor; with other streams flowing into it, as the
+   * node:stream Writable (the process streams convert into one). */
+  interface WritableStream {
+    readonly writable: boolean;
+    write(data: string | Uint8Array, callback?: (error?: Error | null) => void): boolean;
+    write(
+      data: string | Uint8Array,
+      encoding: BufferEncoding,
+      callback?: (error?: Error | null) => void,
+    ): boolean;
+    end(callback?: () => void): void;
+    end(data: string | Uint8Array, callback?: () => void): void;
+    end(data: string | Uint8Array, encoding: BufferEncoding, callback?: () => void): void;
+    /* Node's EventEmitter signature: listeners take untyped arguments. */
+    on(event: string, listener: (...args: any[]) => void): void;
+    once(event: string, listener: (...args: any[]) => void): void;
   }
 }
 
@@ -511,14 +544,119 @@ declare var DOMException: {
   readonly prototype: DOMException;
 };
 
-/* Capability-gated globals harness code probes behind feature guards
- * (globalThis.crypto under a hasCrypto check, the SQLite-backed storage
- * pair): typed `unknown` — no lowering exists, the guard is expected to
- * be false in a compiled binary, and any reached use fences per site. */
-declare var crypto: unknown;
+/* WebCrypto's HMAC slice (scr_webcrypto.c): crypto.subtle's importKey for
+ * raw HMAC keys, HMAC sign/verify and the SHA-1/SHA-2 digests, typed as
+ * exactly that surface (the declarations mirror @types/node's webcrypto
+ * shapes). Every other SubtleCrypto method and crypto member is absent,
+ * so a use is an honest type error. CryptoKey values are native handles
+ * whose four members read through the handle. */
+declare var crypto: Crypto;
+/* The Crypto and SubtleCrypto constructors (feature probes only) stay
+ * `unknown`; the values keep this declaration order. */
 declare var Crypto: unknown;
-declare var CryptoKey: unknown;
+declare var CryptoKey: {
+  prototype: CryptoKey;
+  new (): CryptoKey;
+};
 declare var SubtleCrypto: unknown;
+type KeyUsage =
+  | "encrypt"
+  | "decrypt"
+  | "sign"
+  | "verify"
+  | "deriveKey"
+  | "deriveBits"
+  | "encapsulateBits"
+  | "decapsulateBits"
+  | "encapsulateKey"
+  | "decapsulateKey"
+  | "wrapKey"
+  | "unwrapKey";
+type KeyType = "private" | "public" | "secret";
+interface Algorithm {
+  name: string;
+}
+type AlgorithmIdentifier = Algorithm | string;
+type HashAlgorithmIdentifier = AlgorithmIdentifier;
+interface HmacImportParams extends Algorithm {
+  hash: HashAlgorithmIdentifier;
+  length?: number;
+}
+interface KeyAlgorithm {
+  name: string;
+}
+interface HmacKeyAlgorithm extends KeyAlgorithm {
+  hash: KeyAlgorithm;
+  length: number;
+}
+interface CryptoKey {
+  readonly algorithm: KeyAlgorithm;
+  readonly extractable: boolean;
+  readonly type: KeyType;
+  readonly usages: KeyUsage[];
+}
+type KeyFormat =
+  | "jwk"
+  | "pkcs8"
+  | "raw"
+  | "raw-private"
+  | "raw-public"
+  | "raw-secret"
+  | "raw-seed"
+  | "spki";
+interface JsonWebKey {
+  alg?: string;
+  crv?: string;
+  d?: string;
+  dp?: string;
+  dq?: string;
+  e?: string;
+  ext?: boolean;
+  k?: string;
+  key_ops?: string[];
+  kty?: string;
+  n?: string;
+  p?: string;
+  q?: string;
+  qi?: string;
+  use?: string;
+  x?: string;
+  y?: string;
+}
+/* The 'jwk' form type-checks like @types/node's; the compiler refuses it
+ * (the JsonWebKey import is not implemented). */
+interface SubtleCrypto {
+  digest(algorithm: AlgorithmIdentifier, data: BufferSource): Promise<ArrayBuffer>;
+  importKey(
+    format: "jwk",
+    keyData: JsonWebKey,
+    algorithm: AlgorithmIdentifier | HmacImportParams,
+    extractable: boolean,
+    keyUsages: readonly KeyUsage[],
+  ): Promise<CryptoKey>;
+  importKey(
+    format: Exclude<KeyFormat, "jwk">,
+    keyData: BufferSource,
+    algorithm: AlgorithmIdentifier | HmacImportParams,
+    extractable: boolean,
+    keyUsages: readonly KeyUsage[],
+  ): Promise<CryptoKey>;
+  sign(algorithm: AlgorithmIdentifier, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+  verify(
+    algorithm: AlgorithmIdentifier,
+    key: CryptoKey,
+    signature: BufferSource,
+    data: BufferSource,
+  ): Promise<boolean>;
+}
+interface Crypto {
+  readonly subtle: SubtleCrypto;
+}
+
+/* Capability-gated globals harness code probes behind feature guards
+ * (the SQLite-backed storage pair): typed `unknown` — no lowering exists,
+ * the guard is expected to be false in a compiled binary, and any reached
+ * use fences per site. */
 declare var localStorage: unknown;
 declare var sessionStorage: unknown;
 
@@ -708,6 +846,7 @@ interface MessageEvent<T = unknown> extends Event {
   readonly data: T;
   readonly origin: string;
   readonly lastEventId: string;
+  readonly source: unknown;
   readonly ports: readonly MessagePort[];
 }
 declare var MessageEvent: {
@@ -1026,7 +1165,7 @@ declare module "node:timers/promises" {
     options?: unknown,
   ): AsyncGenerator<T, void, undefined>;
   export const scheduler: {
-    wait(delay?: number): Promise<void>;
+    wait(delay?: number, options?: TimerOptions): Promise<void>;
     yield(): Promise<void>;
   };
 }
@@ -1165,8 +1304,37 @@ declare module "node:perf_hooks" {
     getEntriesByType(type: EntryType): PerformanceEntry[];
     clearMarks(name?: string): void;
     clearMeasures(name?: string): void;
+    eventLoopUtilization(
+      utilization1?: EventLoopUtilization,
+      utilization2?: EventLoopUtilization,
+    ): EventLoopUtilization;
   }
   export const performance: Performance;
+  /* Event-loop metrics: utilization (idle/active ms since the loop started)
+   * and monitorEventLoopDelay's sampling histogram (nanoseconds). */
+  export interface EventLoopUtilization {
+    idle: number;
+    active: number;
+    utilization: number;
+  }
+  export interface EventLoopMonitorOptions {
+    resolution?: number | undefined;
+  }
+  export interface Histogram {
+    readonly count: number;
+    readonly exceeds: number;
+    readonly max: number;
+    readonly mean: number;
+    readonly min: number;
+    readonly stddev: number;
+    percentile(percentile: number): number;
+    reset(): void;
+  }
+  export interface IntervalHistogram extends Histogram {
+    enable(): boolean;
+    disable(): boolean;
+  }
+  export function monitorEventLoopDelay(options?: EventLoopMonitorOptions): IntervalHistogram;
 }
 declare module "perf_hooks" {
   export * from "node:perf_hooks";
@@ -1492,6 +1660,51 @@ declare module "node:fs" {
     readonly COPYFILE_EXCL: number;
     readonly COPYFILE_FICLONE: number;
     readonly COPYFILE_FICLONE_FORCE: number;
+    readonly UV_FS_SYMLINK_DIR: number;
+    readonly UV_FS_SYMLINK_JUNCTION: number;
+    readonly UV_DIRENT_UNKNOWN: number;
+    readonly UV_DIRENT_FILE: number;
+    readonly UV_DIRENT_DIR: number;
+    readonly UV_DIRENT_LINK: number;
+    readonly UV_DIRENT_FIFO: number;
+    readonly UV_DIRENT_SOCKET: number;
+    readonly UV_DIRENT_CHAR: number;
+    readonly UV_DIRENT_BLOCK: number;
+    readonly UV_FS_O_FILEMAP: number;
+    readonly UV_FS_O_TEMPORARY: number;
+    readonly UV_FS_O_SHORT_LIVED: number;
+    readonly UV_FS_O_SEQUENTIAL: number;
+    readonly UV_FS_O_RANDOM: number;
+    readonly UV_FS_COPYFILE_EXCL: number;
+    readonly UV_FS_COPYFILE_FICLONE: number;
+    readonly UV_FS_COPYFILE_FICLONE_FORCE: number;
+    readonly S_IFMT: number;
+    readonly S_IFREG: number;
+    readonly S_IFDIR: number;
+    readonly S_IFCHR: number;
+    readonly S_IFBLK: number;
+    readonly S_IFIFO: number;
+    readonly S_IFLNK: number;
+    readonly S_IFSOCK: number;
+    readonly O_NOCTTY: number;
+    readonly O_DIRECTORY: number;
+    readonly O_NOATIME: number;
+    readonly O_SYNC: number;
+    readonly O_DSYNC: number;
+    readonly O_SYMLINK: number;
+    readonly O_DIRECT: number;
+    readonly S_IRWXU: number;
+    readonly S_IRUSR: number;
+    readonly S_IWUSR: number;
+    readonly S_IXUSR: number;
+    readonly S_IRWXG: number;
+    readonly S_IRGRP: number;
+    readonly S_IWGRP: number;
+    readonly S_IXGRP: number;
+    readonly S_IRWXO: number;
+    readonly S_IROTH: number;
+    readonly S_IWOTH: number;
+    readonly S_IXOTH: number;
   };
   /* A stat(2) snapshot (statSync follows symlinks, lstatSync does not —
    * Node's split) — immutable; the supported surface is exactly these
@@ -1727,6 +1940,13 @@ declare module "node:fs" {
 declare module "fs" {
   export * from "node:fs";
 }
+/* graceful-fs — served as node:fs (it monkeypatches fs and retries on
+ * EMFILE/ENFILE; compiled programs call fs directly, without the retry
+ * queue). gracefulify is a no-op statement. The @types/graceful-fs shape. */
+declare module "graceful-fs" {
+  export * from "node:fs";
+  export function gracefulify<T>(fsModule: T): T;
+}
 
 /* fs/promises — the SAME synchronous operations behind already-settled
  * promises: success fulfills, failure REJECTS with the would-be thrown
@@ -2109,6 +2329,8 @@ declare module "os" {
   export function version(): string;
   export function endianness(): "BE" | "LE";
   export function getPriority(pid?: number): number;
+  export function setPriority(priority: number): void;
+  export function setPriority(pid: number, priority: number): void;
   /* The TARGET platform's null device ("\\\\.\\nul" under a win32 triple). */
   export const devNull: string;
   /* The platform's constants: null-prototype objects with read-only
@@ -2554,6 +2776,23 @@ declare module "crypto" {
     a: ArrayBufferView | ArrayBufferLike,
     b: ArrayBufferView | ArrayBufferLike,
   ): boolean;
+  /* WebCrypto's getRandomValues (also the webcrypto object's): integer
+   * typed arrays, filled in place and returned. The crypto GLOBAL stays
+   * unknown in fallback builds. */
+  type RandomValuesArray =
+    | Int8Array
+    | Uint8Array
+    | Uint8ClampedArray
+    | Int16Array
+    | Uint16Array
+    | Int32Array
+    | Uint32Array
+    | BigInt64Array
+    | BigUint64Array;
+  export function getRandomValues<T extends RandomValuesArray>(typedArray: T): T;
+  export const webcrypto: {
+    getRandomValues<T extends RandomValuesArray>(typedArray: T): T;
+  };
   export function randomFillSync<T extends ArrayBufferView | ArrayBufferLike>(
     buffer: T,
     offset?: number,
@@ -2889,8 +3128,10 @@ declare module "child_process" {
     destroy(): void;
     on(event: "drain" | "finish", listener: () => void): void;
     on(event: "error", listener: (err: Error) => void): void;
+    on(event: string, listener: (...args: any[]) => void): void;
     once(event: "drain" | "finish", listener: () => void): void;
     once(event: "error", listener: (err: Error) => void): void;
+    once(event: string, listener: (...args: any[]) => void): void;
   }
 
   export interface ChildProcess extends Disposable {
@@ -3030,10 +3271,10 @@ declare module "child_process" {
     args?: string[] | null,
     options?: ExecSyncOptions,
   ): unknown;
-  /* The async shell form — declared surface without full lowering (the
-   * type-level tolerance story): harness code on paths tests don't reach
-   * must typecheck; a reached call fences at its site. util.promisify
-   * recognizes it statically, as it does execFile. */
+  /* The async shell form. The callback forms lower like execFile's, with
+   * the command line run by /bin/sh -c, and util.promisify recognizes it
+   * statically, as it does execFile; reached calls without a callback
+   * fence at their site. */
   export function exec(
     command: string,
     options?: ExecSyncOptions | ((error: Error | null, stdout: string, stderr: string) => void),
@@ -3171,6 +3412,76 @@ declare module "util" {
   export function promisify(
     fn: typeof import("node:stream").finished,
   ): typeof import("node:stream/promises").finished;
+  /* The crypto callback functions: the promise settles with the callback's
+   * value. */
+  export function promisify(
+    fn: typeof import("node:crypto").randomBytes,
+  ): (size: number) => Promise<Buffer>;
+  export function promisify(
+    fn: typeof import("node:crypto").pbkdf2,
+  ): (
+    password: string | Uint8Array,
+    salt: string | Uint8Array,
+    iterations: number,
+    keylen: number,
+    digest: string,
+  ) => Promise<Buffer>;
+  export function promisify(
+    fn: typeof import("node:crypto").scrypt,
+  ): (
+    password: import("node:crypto").BinaryLike,
+    salt: import("node:crypto").BinaryLike,
+    keylen: number,
+    options?: import("node:crypto").ScryptOptions,
+  ) => Promise<Buffer>;
+  export function promisify(
+    fn: typeof import("node:crypto").hkdf,
+  ): (
+    digest: string,
+    ikm: import("node:crypto").BinaryLike | import("node:crypto").KeyObject,
+    salt: import("node:crypto").BinaryLike,
+    info: import("node:crypto").BinaryLike,
+    keylen: number,
+  ) => Promise<ArrayBuffer>;
+  /* A callback-only function (`obj.close.bind(obj)`): before the targets
+   * whose leading parameters would otherwise capture it. Builtins that take
+   * arguments before their callback never match these. */
+  export function promisify<TResult>(
+    fn: (callback: (err: any, result: TResult) => void) => void,
+  ): () => Promise<TResult>;
+  export function promisify(fn: (callback: (err?: any) => void) => void): () => Promise<void>;
+  export function promisify(
+    fn: typeof import("node:crypto").randomFill,
+  ): <T extends ArrayBufferView | ArrayBufferLike>(
+    buffer: T,
+    offset?: number,
+    size?: number,
+  ) => Promise<T>;
+  export function promisify(fn: typeof import("node:crypto").randomInt): {
+    (max: number): Promise<number>;
+    (min: number, max: number): Promise<number>;
+  };
+  export function promisify(
+    fn: typeof import("node:crypto").generateKey,
+  ): (
+    type: "hmac" | "aes",
+    options: { length: number },
+  ) => Promise<import("node:crypto").KeyObject>;
+  /* dns.lookup's promise settles with { address, family } (the address
+   * array with options.all), and lookupService's with { hostname, service }. */
+  export function promisify(fn: typeof import("node:dns").lookup): {
+    (
+      hostname: string,
+      options: import("node:dns").LookupAllOptions,
+    ): Promise<import("node:dns").LookupAddress[]>;
+    (
+      hostname: string,
+      options?: number | import("node:dns").LookupOneOptions,
+    ): Promise<import("node:dns").LookupAddress>;
+  };
+  export function promisify(
+    fn: typeof import("node:dns").lookupService,
+  ): (address: string, port: number) => Promise<{ hostname: string; service: string }>;
   /* Declared surface without full lowering (the type-level tolerance
    * story: guarded/diagnostic-path code must TYPECHECK; a reached use
    * without a lowering fences at its site). inspect's options carry the
@@ -3250,6 +3561,7 @@ declare module "util/types" {
   export function isInt8Array(value: unknown): value is Int8Array;
   export function isInt16Array(value: unknown): value is Int16Array;
   export function isInt32Array(value: unknown): value is Int32Array;
+  export function isFloat16Array(value: unknown): value is Float16Array;
   export function isFloat32Array(value: unknown): value is Float32Array;
   export function isFloat64Array(value: unknown): value is Float64Array;
   export function isMap(value: unknown): value is Map<unknown, unknown>;
@@ -3264,6 +3576,21 @@ declare module "util/types" {
   export function isGeneratorFunction(value: unknown): boolean;
   export function isGeneratorObject(value: unknown): boolean;
   export function isModuleNamespaceObject(value: unknown): boolean;
+  export function isDate(value: unknown): value is Date;
+  export function isSharedArrayBuffer(value: unknown): value is SharedArrayBuffer;
+  export function isMapIterator(value: unknown): boolean;
+  export function isSetIterator(value: unknown): boolean;
+  export function isKeyObject(value: unknown): boolean;
+  export function isNumberObject(value: unknown): boolean;
+  export function isStringObject(value: unknown): boolean;
+  export function isBooleanObject(value: unknown): boolean;
+  export function isBigIntObject(value: unknown): boolean;
+  export function isSymbolObject(value: unknown): boolean;
+  export function isBoxedPrimitive(value: unknown): boolean;
+  export function isBigInt64Array(value: unknown): value is BigInt64Array;
+  export function isBigUint64Array(value: unknown): value is BigUint64Array;
+  export function isCryptoKey(value: unknown): boolean;
+  export function isExternal(value: unknown): boolean;
 }
 declare module "node:util/types" {
   export * from "util/types";
@@ -3293,8 +3620,18 @@ declare module "node:util/types" {
  * suites typecheck but fence at their use sites (no lowering). */
 declare module "node:test" {
   type TestFn = (t: TestContext) => void | Promise<void>;
-  type SuiteFn = () => void;
-  type HookFn = () => void | Promise<void>;
+  type SuiteFn = (s: SuiteContext) => void;
+  type HookFn = (c: TestContext | SuiteContext) => void | Promise<void>;
+  /* The describe/suite callback's context, and the before/after hook
+   * context of a suite. */
+  interface SuiteContext {
+    readonly name: string;
+    readonly fullName: string;
+    readonly filePath: string | undefined;
+    readonly attempt: number;
+    readonly passed: boolean;
+    diagnostic(message: string): void;
+  }
   interface TestOptions {
     skip?: boolean | string;
     todo?: boolean | string;
@@ -3306,10 +3643,17 @@ declare module "node:test" {
   interface TestContext {
     readonly name: string;
     readonly fullName: string;
+    readonly filePath: string | undefined;
+    readonly attempt: number;
+    readonly passed: boolean;
+    readonly workerId: number | undefined;
+    readonly tags: readonly string[];
     readonly assert: TestContextAssert;
     readonly mock: MockTracker;
-    test(name: string, fn?: TestFn): Promise<void>;
-    test(name: string, options: TestOptions, fn?: TestFn): Promise<void>;
+    test(name?: string, fn?: TestFn): Promise<void>;
+    test(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
+    test(options?: TestOptions, fn?: TestFn): Promise<void>;
+    test(fn?: TestFn): Promise<void>;
     skip(message?: string): void;
     todo(message?: string): void;
     diagnostic(message: string): void;
@@ -3319,7 +3663,12 @@ declare module "node:test" {
     beforeEach(fn: HookFn): void;
     afterEach(fn: HookFn): void;
   }
+  interface AssertSnapshotOptions {
+    readonly serializers?: ReadonlyArray<(value: any) => any> | undefined;
+  }
   interface TestContextAssert {
+    snapshot(value: any, options?: AssertSnapshotOptions): void;
+    fileSnapshot(value: any, path: string, options?: AssertSnapshotOptions): void;
     ok(value: unknown, message?: string): void;
     strictEqual(actual: unknown, expected: unknown, message?: string): void;
     notStrictEqual(actual: unknown, expected: unknown, message?: string): void;
@@ -3334,23 +3683,44 @@ declare module "node:test" {
     match(value: string, regExp: RegExp, message?: string): void;
     doesNotMatch(value: string, regExp: RegExp, message?: string): void;
   }
-  function test(name: string, fn?: TestFn): Promise<void>;
-  function test(name: string, options: TestOptions, fn?: TestFn): Promise<void>;
+  /* The name, options and function are each optional, as in Node: a test
+   * without a name takes the function's name, or "<anonymous>". */
+  function test(name?: string, fn?: TestFn): Promise<void>;
+  function test(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
+  function test(options?: TestOptions, fn?: TestFn): Promise<void>;
+  function test(fn?: TestFn): Promise<void>;
   namespace test {
-    function skip(name: string, fn?: TestFn): Promise<void>;
-    function skip(name: string, options: TestOptions, fn?: TestFn): Promise<void>;
-    function todo(name: string, fn?: TestFn): Promise<void>;
-    function todo(name: string, options: TestOptions, fn?: TestFn): Promise<void>;
-    function only(name: string, fn?: TestFn): Promise<void>;
-    function only(name: string, options: TestOptions, fn?: TestFn): Promise<void>;
+    function skip(name?: string, fn?: TestFn): Promise<void>;
+    function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
+    function skip(options?: TestOptions, fn?: TestFn): Promise<void>;
+    function skip(fn?: TestFn): Promise<void>;
+    function todo(name?: string, fn?: TestFn): Promise<void>;
+    function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
+    function todo(options?: TestOptions, fn?: TestFn): Promise<void>;
+    function todo(fn?: TestFn): Promise<void>;
+    function only(name?: string, fn?: TestFn): Promise<void>;
+    function only(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
+    function only(options?: TestOptions, fn?: TestFn): Promise<void>;
+    function only(fn?: TestFn): Promise<void>;
   }
   const it: typeof test;
-  function describe(name: string, fn?: SuiteFn): void;
-  function describe(name: string, options: TestOptions, fn?: SuiteFn): void;
+  function describe(name?: string, fn?: SuiteFn): void;
+  function describe(name?: string, options?: TestOptions, fn?: SuiteFn): void;
+  function describe(options?: TestOptions, fn?: SuiteFn): void;
+  function describe(fn?: SuiteFn): void;
   namespace describe {
-    function skip(name: string, fn?: SuiteFn): void;
-    function todo(name: string, fn?: SuiteFn): void;
-    function only(name: string, fn?: SuiteFn): void;
+    function skip(name?: string, fn?: SuiteFn): void;
+    function skip(name?: string, options?: TestOptions, fn?: SuiteFn): void;
+    function skip(options?: TestOptions, fn?: SuiteFn): void;
+    function skip(fn?: SuiteFn): void;
+    function todo(name?: string, fn?: SuiteFn): void;
+    function todo(name?: string, options?: TestOptions, fn?: SuiteFn): void;
+    function todo(options?: TestOptions, fn?: SuiteFn): void;
+    function todo(fn?: SuiteFn): void;
+    function only(name?: string, fn?: SuiteFn): void;
+    function only(name?: string, options?: TestOptions, fn?: SuiteFn): void;
+    function only(options?: TestOptions, fn?: SuiteFn): void;
+    function only(fn?: SuiteFn): void;
   }
   const suite: typeof describe;
   function before(fn: HookFn): void;
@@ -3410,8 +3780,24 @@ declare module "node:test" {
       : never;
     reset(): void;
     restoreAll(): void;
+    readonly timers: MockTimers;
+  }
+  interface MockTimersOptions {
+    apis: ReadonlyArray<"setInterval" | "setTimeout" | "setImmediate" | "Date">;
+    now?: number | Date | undefined;
+  }
+  interface MockTimers {
+    enable(options?: MockTimersOptions): void;
+    setTime(milliseconds?: number): void;
+    reset(): void;
+    tick(milliseconds?: number): void;
+    runAll(): void;
+    [Symbol.dispose](): void;
   }
   const mock: MockTracker;
+  /* The context of the test, suite or hook running in the current async
+   * context; undefined outside one. */
+  function getTestContext(): TestContext | SuiteContext | undefined;
   /* Declared for typechecking only — every use fences (no lowering).
    * `assert` is the module-level custom-assertion registry (v24's
    * `const { assert } = require('node:test')`), not TestContext.assert. */
@@ -3429,14 +3815,18 @@ declare module "node:test" {
     afterEach,
     mock,
     assert,
+    getTestContext,
     run,
     snapshot,
     TestContext,
+    SuiteContext,
     TestOptions,
     Mock,
     MockFunctionContext,
     MockFunctionCall,
     MockTracker,
+    MockTimers,
+    MockTimersOptions,
   };
   export default test;
 }
@@ -3618,7 +4008,8 @@ declare module "querystring" {
       | string
       | number
       | boolean
-      | ReadonlyArray<string | number | boolean>
+      | bigint
+      | ReadonlyArray<string | number | boolean | bigint>
       | null
       | undefined;
   }
@@ -3643,6 +4034,39 @@ declare module "node:querystring" {
   export * from "querystring";
 }
 
+/* node:punycode (deprecated, DEP0040) — punycode.js 2.1.0: decode and
+ * toUnicode throw its RangeErrors on malformed input; ucs2 converts
+ * between strings and UTF-16 code point arrays. */
+declare module "punycode" {
+  export function decode(string: string): string;
+  export function encode(string: string): string;
+  export function toUnicode(domain: string): string;
+  export function toASCII(domain: string): string;
+  export namespace ucs2 {
+    function decode(string: string): number[];
+    function encode(codePoints: readonly number[]): string;
+  }
+  export const version: string;
+}
+declare module "node:punycode" {
+  export * from "punycode";
+}
+
+/* node:constants (deprecated, DEP0008) — one frozen object: os.constants'
+ * dlopen, errno, priority and signals groups, fs.constants, and
+ * crypto.constants. A platform's missing constant reads as undefined. */
+declare module "constants" {
+  const constants: { readonly [name: string]: number } & {
+    readonly defaultCoreCipherList: string;
+    readonly defaultCipherList: string;
+  };
+  export = constants;
+}
+declare module "node:constants" {
+  import constants = require("constants");
+  export = constants;
+}
+
 /* node:readline — the question/close slice: createInterface over exactly
  * { input: process.stdin, output: process.stdout }, question(query, cb)
  * (the query writes to stdout, the callback gets the next line's text),
@@ -3660,7 +4084,10 @@ declare module "readline" {
     meta?: boolean;
     shift?: boolean;
   }
-  export interface Interface extends Disposable {
+  export class Interface implements Disposable {
+    /* createInterface creates interfaces; instanceof tells the two
+     * modules' classes apart. */
+    protected constructor();
     /* terminal says whether the interface edits lines as a terminal;
      * line and cursor are the terminal's (line is '' otherwise). history
      * is the history option itself (or the interface's own empty array);
@@ -3775,7 +4202,10 @@ declare module "readline/promises" {
   /* The readline Interface with the promise question: it resolves with
    * the next line, rejects with an AbortError when options.signal aborts,
    * and with ERR_USE_AFTER_CLOSE after close(). */
-  export interface Interface extends Disposable {
+  export class Interface implements Disposable {
+    /* createInterface creates interfaces; instanceof tells the two
+     * modules' classes apart. */
+    protected constructor();
     /* terminal says whether the interface edits lines as a terminal;
      * line and cursor are the terminal's (line is '' otherwise). history
      * is the history option itself (or the interface's own empty array);
@@ -4328,6 +4758,11 @@ declare module "net" {
     on(event: "close", listener: (hadError: boolean) => void): void;
     on(event: "error", listener: (err: Error) => void): void;
     on(event: "session", listener: (session: Buffer) => void): void;
+    /* The host name's resolution, before the connect. */
+    on(
+      event: "lookup",
+      listener: (err: Error | null, address: string, family: number, host: string) => void,
+    ): void;
     /* addListener IS on (Node aliases them) — the suite spells both. */
     addListener(event: "data", listener: (chunk: Buffer) => void): void;
     /* After setEncoding the chunk is a string. */
@@ -4339,6 +4774,11 @@ declare module "net" {
     addListener(event: "close", listener: (hadError: boolean) => void): void;
     addListener(event: "error", listener: (err: Error) => void): void;
     addListener(event: "session", listener: (session: Buffer) => void): void;
+    /* The host name's resolution, before the connect. */
+    addListener(
+      event: "lookup",
+      listener: (err: Error | null, address: string, family: number, host: string) => void,
+    ): void;
     once(event: "data", listener: (chunk: Buffer) => void): void;
     /* After setEncoding the chunk is a string. */
     once(event: "data", listener: (chunk: string) => void): void;
@@ -4349,6 +4789,11 @@ declare module "net" {
     once(event: "close", listener: (hadError: boolean) => void): void;
     once(event: "error", listener: (err: Error) => void): void;
     once(event: "session", listener: (session: Buffer) => void): void;
+    /* The host name's resolution, before the connect. */
+    once(
+      event: "lookup",
+      listener: (err: Error | null, address: string, family: number, host: string) => void,
+    ): void;
   }
   export interface Server {
     /* Whether the server keeps the event loop alive (ref'd by default). */
@@ -4367,6 +4812,8 @@ declare module "net" {
     /* The positional bind address (the options form's host in argument
      * spelling). */
     listen(port: number, host: string, callback?: () => void): Server;
+    /* A Unix-socket server; the socket file is removed when it closes. */
+    listen(path: string, callback?: () => void): Server;
     /* The explicit-interface bind: host is an IP literal (absent = the
      * host-less dual-stack any); ipv6Only sets IPV6_V6ONLY and reusePort
      * requests kernel connection distribution where Node supports it. */
@@ -4436,6 +4883,48 @@ declare module "net" {
     remoteFamily?: string;
   }
   export type AddressInfo = import("node:dgram").AddressInfo;
+  export type IPVersion = "ipv4" | "ipv6";
+  export interface SocketAddressInitOptions {
+    address?: string;
+    family?: IPVersion;
+    flowlabel?: number;
+    port?: number;
+  }
+  /* A native handle (scr_net.c); the getters read its parsed address. */
+  export class SocketAddress {
+    constructor(options?: SocketAddressInitOptions);
+    readonly address: string;
+    readonly family: IPVersion;
+    readonly port: number;
+    readonly flowlabel: number;
+    toJSON(): { address: string; port: number; family: IPVersion; flowlabel: number };
+    /* undefined when the input is not "<ip>[:<port>]" */
+    static parse(input: string): SocketAddress | undefined;
+    static isSocketAddress(value: unknown): value is SocketAddress;
+  }
+  /* Address, range and subnet rules; check() matches IPv4 addresses
+   * against IPv6 rules through their IPv4-mapped form, as Node does. */
+  export class BlockList {
+    constructor();
+    readonly rules: readonly string[];
+    readonly size: number;
+    addAddress(address: string | SocketAddress, type?: IPVersion): void;
+    addAddresses(addresses: readonly (string | SocketAddress)[], type?: IPVersion): void;
+    addRange(start: string | SocketAddress, end: string | SocketAddress, type?: IPVersion): void;
+    addSubnet(net: string | SocketAddress, prefix: number, type?: IPVersion): void;
+    addCIDR(cidr: string): void;
+    addCIDRs(cidrs: readonly string[]): void;
+    removeAddress(address: string | SocketAddress, type?: IPVersion): void;
+    removeRange(start: string | SocketAddress, end: string | SocketAddress, type?: IPVersion): void;
+    removeSubnet(net: string | SocketAddress, prefix: number, type?: IPVersion): void;
+    removeCIDR(cidr: string): void;
+    clear(): void;
+    check(address: string | SocketAddress, type?: IPVersion): boolean;
+    toJSON(): string[];
+    fromJSON(data: string | readonly string[]): void;
+    static isBlockList(value: unknown): value is BlockList;
+    static readonly PRIVATE_RANGES: readonly string[];
+  }
   /* Node's IPv4Reg and IPv6Reg tests: 4, 6, or 0 for isIP. */
   export function isIP(input: string): number;
   export function isIPv4(input: string): boolean;
@@ -4648,10 +5137,11 @@ declare module "http" {
    * callback receives the response as an IncomingMessage (statusCode,
    * headers, body via on("data"/"end")). */
   export interface RequestOptions {
-    hostname?: string;
-    host?: string;
-    port?: number;
-    path?: string;
+    hostname?: string | null;
+    host?: string | null;
+    /* A string port (a URL's .port) is accepted, as by Node. */
+    port?: number | string | null;
+    path?: string | null;
     method?: string;
     timeout?: number;
     headers?: OutgoingHttpHeaders;
@@ -4665,6 +5155,8 @@ declare module "http" {
     agent?: Agent | boolean | null;
     /* Aborting destroys the request with an AbortError. */
     signal?: AbortSignal;
+    /* HTTP over the Unix socket at this path instead of host:port. */
+    socketPath?: string;
     /* The options-record stance: Node ignores an options record's
      * unknown keys, so every key typechecks here — the option WALK in
      * the lowering decides per key (lower, fence by name, or drop
@@ -4674,17 +5166,16 @@ declare module "http" {
   /* The Agent lowers to a checked-dynamic HANDLE: option parsing at the
    * literal construction site, getName, destroy, the sockets/requests/
    * freeSockets snapshots, and REAL maxSockets accounting (over-limit
-   * requests defer their dial and queue). keepAlive: true throws the
-   * named pooling fence — this client dials one connection per request
-   * and closes it with the response, so freeSockets is always
-   * empty. */
+   * requests defer their dial and queue). keepAlive: true keeps finished
+   * connections in freeSockets for the next request to the same name,
+   * taken in `scheduling` order. */
   export interface AgentOptions {
     keepAlive?: boolean;
     keepAliveMsecs?: number;
     maxSockets?: number;
     maxFreeSockets?: number;
     maxTotalSockets?: number;
-    scheduling?: string;
+    scheduling?: "fifo" | "lifo";
     timeout?: number;
     port?: number;
     [option: string]: unknown;
@@ -4714,6 +5205,7 @@ declare module "http" {
     readonly freeSockets: { [key: string]: unknown[] };
     readonly requests: { [key: string]: unknown[] };
   }
+  /* Node's keepAlive global agent for requests without an agent option. */
   export const globalAgent: Agent;
   export interface ClientRequest {
     readonly destroyed: boolean;
@@ -4850,6 +5342,8 @@ declare module "tls" {
     getProtocol(): string | null;
     /* OpenSSL's suite name, the IANA name and the suite's version */
     getCipher(): CipherNameAndProtocol;
+    /* whether the handshake resumed a cached session */
+    isSessionReused(): boolean;
   }
   export interface CipherNameAndProtocol {
     name: string;
@@ -4917,6 +5411,8 @@ declare module "https" {
   import { Server } from "http";
   import { Agent, ClientRequest, IncomingMessage, ServerResponse } from "http";
   export { Agent, Server };
+  /* Node's keepAlive global agent for requests without an agent option. */
+  export const globalAgent: Agent;
   export interface ServerOptions {
     cert: string | Uint8Array;
     key: string | Uint8Array;
@@ -4936,6 +5432,7 @@ declare module "https" {
     agent?: Agent | boolean | null;
     /* Aborting destroys the request with an AbortError. */
     signal?: AbortSignal;
+    socketPath?: string;
     /* The options-record stance (see http.RequestOptions). */
     [option: string]: unknown;
   }
@@ -5753,10 +6250,79 @@ declare module "dns" {
   export function getServers(): string[];
   export function getDefaultResultOrder(): "ipv4first" | "ipv6first" | "verbatim";
   export function setDefaultResultOrder(order: "ipv4first" | "ipv6first" | "verbatim"): void;
+  /* The promise forms (node:dns/promises). */
+  export const promises: typeof import("dns/promises");
 }
 declare module "node:dns" {
   export * from "dns";
 }
+/* node:dns/promises — lookup and lookupService as promises over the same
+ * resolution as the callback forms: argument errors throw synchronously,
+ * failures reject with the callbacks' errors. */
+declare module "dns/promises" {
+  import type { LookupAddress, LookupAllOptions, LookupOneOptions, LookupOptions } from "dns";
+  export function lookup(hostname: string, family: number): Promise<LookupAddress>;
+  export function lookup(hostname: string, options: LookupOneOptions): Promise<LookupAddress>;
+  export function lookup(hostname: string, options: LookupAllOptions): Promise<LookupAddress[]>;
+  export function lookup(
+    hostname: string,
+    options: LookupOptions,
+  ): Promise<LookupAddress | LookupAddress[]>;
+  export function lookup(hostname: string): Promise<LookupAddress>;
+  export function lookupService(
+    address: string,
+    port: number,
+  ): Promise<{ hostname: string; service: string }>;
+  export function getServers(): string[];
+  export function getDefaultResultOrder(): "ipv4first" | "ipv6first" | "verbatim";
+  export function setDefaultResultOrder(order: "ipv4first" | "ipv6first" | "verbatim"): void;
+}
+declare module "node:dns/promises" {
+  export * from "dns/promises";
+}
+
+/* node:v8 — importable for the packages that require it at top level.
+ * getHeapStatistics answers allocator-derived figures in Node's shape
+ * (approximate: the runtime heap's total and used bytes, the machine's
+ * memory as the limit; V8-only figures are 0). The other members observe
+ * V8 itself and fence at their use with the by-design reason; they are
+ * declared so programs that type-check under their own tsc reach that
+ * fence. */
+declare module "v8" {
+  type DoesZapCodeSpaceFlag = 0 | 1;
+  export interface HeapInfo {
+    total_heap_size: number;
+    total_heap_size_executable: number;
+    total_physical_size: number;
+    total_available_size: number;
+    used_heap_size: number;
+    heap_size_limit: number;
+    malloced_memory: number;
+    peak_malloced_memory: number;
+    does_zap_garbage: DoesZapCodeSpaceFlag;
+    number_of_native_contexts: number;
+    number_of_detached_contexts: number;
+    total_global_handles_size: number;
+    used_global_handles_size: number;
+    external_memory: number;
+  }
+  export function getHeapStatistics(): HeapInfo;
+  export function cachedDataVersionTag(): number;
+  export function getHeapSpaceStatistics(): unknown[];
+  export function getHeapCodeStatistics(): unknown;
+  export function getHeapSnapshot(options?: unknown): unknown;
+  export function writeHeapSnapshot(fileName?: string, options?: unknown): string;
+  export function setFlagsFromString(flags: string): void;
+  export function setHeapSnapshotNearHeapLimit(limit: number): void;
+  export function serialize(value: unknown): Buffer;
+  export function deserialize(buffer: Uint8Array): unknown;
+  export function takeCoverage(): void;
+  export function stopCoverage(): void;
+  export function isStringOneByteRepresentation(content: string): boolean;
+}
+declare module "node:v8" {
+  export * from "v8";
+}
 
 /* node:worker_threads — native workers use statically compiled entry points.
  * Lowering and runtime diagnostics define the supported options and methods. */
@@ -5764,19 +6330,42 @@ declare module "worker_threads" {
   export const isMainThread: boolean;
   export const isInternalThread: boolean;
   export const threadId: number;
+  export interface ResourceLimits {
+    maxYoungGenerationSizeMb?: number;
+    maxOldGenerationSizeMb?: number;
+    codeRangeSizeMb?: number;
+    stackSizeMb?: number;
+  }
+  /* {} in the main thread */
+  export const resourceLimits: ResourceLimits;
+  /* the Worker's name option, trimmed ("WorkerThread" by default); "" in the main thread */
+  export const threadName: string | null;
   export interface WorkerOptions {
     workerData?: unknown;
     transferList?: readonly unknown[];
     argv?: readonly unknown[];
     name?: string;
+    resourceLimits?: ResourceLimits;
+    stdout?: boolean;
+    stderr?: boolean;
+    stdin?: boolean;
     [option: string]: unknown;
   }
   export class Worker {
     constructor(filename: string | URL, options?: WorkerOptions);
     readonly threadId: number;
+    readonly resourceLimits?: ResourceLimits;
+    readonly threadName: string | null;
+    /* with the stdout/stderr options: the worker's writes to those streams */
+    readonly stdout: import("stream").Readable;
+    readonly stderr: import("stream").Readable;
+    /* with the stdin option: what the worker reads from process.stdin */
+    readonly stdin: import("stream").Writable | null;
+    /* terminate(), resolving with undefined once the worker exited */
+    [Symbol.asyncDispose](): Promise<void>;
     on(event: "online", listener: () => void): this;
     on(event: "message", listener: (value: any) => void): this;
-    on(event: "error", listener: (error: Error) => void): this;
+    on(event: "error", listener: (error: any) => void): this;
     on(event: "exit", listener: (code: number) => void): this;
     on(event: string, listener: (...args: any[]) => void): this;
     once(event: string, listener: (...args: any[]) => void): this;
@@ -5818,6 +6407,27 @@ declare module "worker_threads" {
     readonly port2: MessagePort;
   }
   export function receiveMessageOnPort(port: MessagePort): { message: any } | undefined;
+  /* This thread's environment data; each new Worker starts from a clone. */
+  export function setEnvironmentData(key: any, value?: any): void;
+  export function getEnvironmentData(key: any): any;
+  /* A marked object cannot be listed in a transfer list. */
+  export function markAsUntransferable(object: any): void;
+  /* structuredClone and postMessage throw DataCloneError for a marked
+   * object, error or class instance */
+  export function markAsUncloneable(object: any): void;
+  export function isMarkedAsUntransferable(object: any): boolean;
+  /* Delivers each message to every other open channel with the name, in
+   * any thread, as a 'message' MessageEvent. */
+  export class BroadcastChannel extends EventTarget {
+    constructor(name: string);
+    readonly name: string;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onmessageerror: ((event: MessageEvent) => void) | null;
+    postMessage(message: unknown): void;
+    close(): void;
+    ref(): this;
+    unref(): this;
+  }
   export const parentPort: MessagePort | null;
   export const workerData: any;
 }
@@ -5868,7 +6478,7 @@ declare module "node:cluster" {
 /* node:tty — the fd probe (the same isatty(3) behind process.*.isTTY)
  * and the supported structural view of a process output stream. */
 declare module "tty" {
-  export interface WriteStream {
+  export interface WriteStream extends NodeJS.WritableStream {
     write(data: string | Uint8Array, callback?: (error?: Error | null) => void): boolean;
     write(
       data: string | Uint8Array,
@@ -5959,10 +6569,16 @@ declare module "events" {
     export { internal as EventEmitter };
     // The event's arguments, as checked-dynamic values.
     export function once(
-      emitter: EventEmitter,
+      emitter: EventEmitter | NodeJS.ReadableStream | NodeJS.WritableStream,
       eventName: string,
       options?: { signal?: AbortSignal },
     ): Promise<unknown[]>;
+    /* The emitter's own listenerCount/getMaxListeners/setMaxListeners/
+     * listeners, over EventEmitter instances. */
+    export function listenerCount(emitter: EventEmitter, eventName: string | symbol): number;
+    export function getMaxListeners(emitter: EventEmitter): number;
+    export function setMaxListeners(n?: number, ...eventTargets: EventEmitter[]): void;
+    export function getEventListeners(emitter: EventEmitter, name: string): Array<() => void>;
   }
   export = EventEmitter;
 }
@@ -6112,8 +6728,8 @@ declare module "stream" {
     resume(): this;
     isPaused(): boolean;
     setEncoding(encoding: string): this;
-    pipe<T extends Writable>(destination: T, options?: { end?: boolean }): T;
-    unpipe(destination?: Writable): this;
+    pipe<T extends NodeJS.WritableStream>(destination: T, options?: { end?: boolean }): T;
+    unpipe(destination?: NodeJS.WritableStream): this;
     destroy(error?: Error): this;
     readonly readable: boolean;
     readonly readableEnded: boolean;
@@ -6496,6 +7112,22 @@ declare module "node:stream/consumers" {
   import streamConsumers = require("stream/consumers");
   export = streamConsumers;
 }
+/* node:stream/web — the module exports the web stream globals themselves
+ * (require("stream/web").ReadableStream === globalThis.ReadableStream).
+ * ReadableStream is the implemented class; its reader and controller are
+ * exported as types. */
+declare module "stream/web" {
+  export const ReadableStream: typeof globalThis.ReadableStream;
+  export type ReadableStream<T = unknown> = globalThis.ReadableStream<T>;
+  export type ReadableStreamDefaultReader<T = unknown> = globalThis.ReadableStreamDefaultReader<T>;
+  export type ReadableStreamDefaultController<T = unknown> =
+    globalThis.ReadableStreamDefaultController<T>;
+  export type UnderlyingSource<T = unknown> = globalThis.UnderlyingSource<T>;
+  export type QueuingStrategy<T = unknown> = globalThis.QueuingStrategy<T>;
+}
+declare module "node:stream/web" {
+  export * from "stream/web";
+}
 interface ErrorConstructor {
   stackTraceLimit: number;
 }