@orkestrel/test 0.0.12 → 0.0.14

package/dist/src/server/index.d.cts

@@ -1,7 +1,7 @@
-import { Server } from 'node:net';
-import { Socket } from 'node:net';
-import { Stats } from 'node:fs';
-import { WaitOptions } from '@orkestrel/test';
+import type { Server } from 'node:net';
+import type { Socket } from 'node:net';
+import type { Stats } from 'node:fs';
+import type { WaitOptions } from '@orkestrel/test';
 
 /** Holds a name-keyed cookie store a test drives one origin with, filled from real responses. */
 export declare interface CookieJarInterface {
@@ -24,7 +24,8 @@ export declare interface CookieJarInterface {
      * @returns Those fields unmodified, in the order the response carried them.
      * @remarks Selection is by name alone. A field spelling `Max-Age=0` deletes its cookie and every
      * other field stores or replaces one, so `Domain`, `Path`, `Expires`, and `Secure` are read past
-     * rather than honoured. Nothing outlives the jar.
+     * rather than honoured. A field carrying no `name=value` pair is read past too and still
+     * returned. Nothing outlives the jar.
      */
     capture(response: Response): readonly string[];
 }
@@ -51,6 +52,17 @@ export declare function createCookieJar(): CookieJarInterface;
  * `EPERM`, while a directory or missing source is passed to a junction attempt. A missing source is
  * accepted to create a dangling junction. Where the host creates a junction, its stored value is the
  * resolved absolute path.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs'
+ * import { createLink } from '@orkestrel/test/server'
+ *
+ * // `/scratch/source` is a directory holding `file.txt`.
+ * createLink('/scratch/linked', '/scratch/source')
+ *
+ * readFileSync('/scratch/linked/file.txt', 'utf8') // 'linked'
+ * ```
  */
 export declare function createLink(path: string, source: string): void;
 
@@ -70,8 +82,69 @@ export declare function createLoopback(server: Server): Promise<LoopbackInterfac
  * @returns The scratch directory and its file operations.
  * @throws When the parent is missing, a symbolic link, or not a directory; when the prefix contains
  * `/` or `\`; or when allocation or seeding fails.
- * @remarks The parent defaults to the host temporary directory. The prefix defaults to
- * `orkestrel-test-`. Seed keys use root-relative paths.
+ * @remarks Default parent: the host temporary directory. Default prefix: `orkestrel-test-`. Seed
+ * keys use root-relative paths.
+ *
+ * @example Own a temporary directory
+ * ```ts
+ * import { createScratch } from '@orkestrel/test/server'
+ *
+ * const scratch = createScratch({ prefix: 'guide-', files: { 'src/index.ts': 'export {}\n' } })
+ *
+ * scratch.read('src/index.ts') // 'export {}\n'
+ * scratch.has('src') // true
+ * scratch.read('src') // throws Error: Scratch path is a directory: src
+ * scratch.read('missing.ts') // undefined
+ * scratch.write('../escape.ts', '') // throws Error: Path outside scratch directory: ../escape.ts
+ *
+ * // `write` answers the contained path it wrote, the way `ensure` and `link` answer theirs, so the
+ * // path goes straight to the code under test without joining it again.
+ * scratch.write('src/notes.ts', 'export {}\n') // `${scratch.path}/src/notes.ts`
+ *
+ * // `ensure` is how you get an empty directory, because every `write` creates a file.
+ * scratch.ensure('empty')
+ * scratch.names() // ['empty', 'src']
+ * scratch.names('empty') // []
+ *
+ * // `parent` puts the allocation somewhere other than the host temporary directory.
+ * const child = createScratch({ parent: scratch.path, prefix: 'child-' })
+ * scratch.names().length // 3 — 'empty', 'src', and the child allocation
+ * child.destroy()
+ * scratch.names().length // 2 — the child removed itself and nothing else
+ *
+ * // `link` creates the symbolic link the threat model names, and `read` follows it. A directory
+ * // source runs on a host that creates no symbolic link too; see "Hosts that create no symbolic
+ * // link" for what such a host does with a file source.
+ * const outside = createScratch({ prefix: 'outside-', files: { 'read.ts': 'export {}\n' } })
+ * scratch.link('gate', outside.path) // `${scratch.path}/gate` — the link's own path, not its destination
+ * scratch.read('gate/read.ts') // 'export {}\n' — read through the link, at its destination
+ *
+ * // A link pointing out of the allocation is resolved through, so a contained path acts outside it.
+ * scratch.ensure('gate/made') // `${scratch.path}/gate/made` — the lexical path, not the destination
+ * outside.names() // ['made', 'read.ts'] — the directory was made under `outside.path`
+ * scratch.names('gate') // ['made', 'read.ts'] — the same entries, listed through the link
+ *
+ * // `link` acts at the final segment rather than through it, so `gate` is occupied.
+ * scratch.link('gate', outside.path) // throws Error: EEXIST: file already exists
+ *
+ * // `has` reads the final segment without following it, and `read` follows it.
+ * scratch.link('dangling', 'missing.ts')
+ * scratch.has('dangling') // true — the link is there
+ * scratch.read('dangling') // undefined — what it points at is not
+ *
+ * // `remove` takes one contained entry and acts at the final segment, so a link goes and whatever it
+ * // pointed at stays. A missing target is a no-op.
+ * scratch.remove('dangling')
+ * scratch.has('dangling') // false
+ * scratch.remove('missing.ts') // no throw — there was nothing there
+ * scratch.remove('src') // the directory and everything under it
+ * scratch.names() // ['empty', 'gate']
+ *
+ * scratch.destroy()
+ * scratch.destroy() // no-op — destroy is idempotent
+ * outside.has('made') // true — destroy unlinks `gate` and leaves what it pointed at
+ * outside.destroy()
+ * ```
  */
 export declare function createScratch(options?: ScratchOptions): ScratchInterface;
 
@@ -84,7 +157,7 @@ export declare function createScratch(options?: ScratchOptions): ScratchInterfac
  * @throws The abort reason, or an `Error` when a bound is invalid or the budget elapses. The
  * exhaustion error carries the last host refusal as its `cause`.
  * @remarks Default budget: `10000` milliseconds. Default interval: `25` milliseconds. A host holds a
- * directory for a short interval after the process that held it exits, and a just-stopped child's
+ * directory for a short interval after the process that held it exits, and a recently stopped child's
  * working directory is the case this exists for, so removal is attempted until the host lets go
  * rather than exactly once. {@link ScratchInterface.destroy} stays synchronous and is unchanged; this
  * is the bounded retry around it. A directory nothing releases still fails, with the host's own
@@ -120,6 +193,14 @@ export declare interface InventoryOptions {
  * @param key - The root-relative key to test.
  * @param exclusions - The normalized root-relative exclusion keys.
  * @returns True if an exclusion names the key or one of its ancestors; false otherwise.
+ *
+ * @example
+ * ```ts
+ * import { isExcluded } from '@orkestrel/test/server'
+ *
+ * isExcluded('src/index.ts', ['src']) // true
+ * isExcluded('src-other/index.ts', ['src']) // false
+ * ```
  */
 export declare function isExcluded(key: string, exclusions: readonly string[]): boolean;
 
@@ -139,6 +220,14 @@ export declare function isExcluded(key: string, exclusions: readonly string[]):
  *
  * A Linux zombie — a process that has exited and whose parent has not reaped it — still accepts
  * signal `0`, so its `/proc` status is read and a `Z` state reads as false.
+ *
+ * @example
+ * ```ts
+ * import { isRunning } from '@orkestrel/test/server'
+ *
+ * isRunning(process.pid) // true
+ * isRunning(2 ** 31) // false
+ * ```
  */
 export declare function isRunning(pid: number): boolean;
 
@@ -169,6 +258,17 @@ export declare interface LoopbackInterface {
  * @remarks All three fields are compared because none of them alone identifies an allocation. A
  * device is shared by every directory on one filesystem, an index node is reused once its directory
  * is removed, and a creation time repeats within the host's timestamp resolution.
+ *
+ * @example
+ * ```ts
+ * import { statSync } from 'node:fs'
+ * import { matchesIdentity, readIdentity } from '@orkestrel/test/server'
+ *
+ * const allocation = readIdentity(statSync('/scratch'))
+ *
+ * matchesIdentity(readIdentity(statSync('/scratch')), allocation) // true
+ * matchesIdentity({ birth: 3, device: 1, inode: 9 }, { birth: 3, device: 1, inode: 2 }) // false
+ * ```
  */
 export declare function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean;
 
@@ -181,6 +281,16 @@ export declare function matchesIdentity(current: ScratchIdentity, allocation: Sc
  * `code`, and one carrying a `code` that is not a string all answer `undefined`. A null-prototype
  * object is read the same way, because the key is tested with `in` rather than through
  * `hasOwnProperty`.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs'
+ * import { captureError } from '@orkestrel/test'
+ * import { readErrorCode } from '@orkestrel/test/server'
+ *
+ * readErrorCode(captureError(() => readFileSync('/scratch/absent.txt', 'utf8'))) // 'ENOENT'
+ * readErrorCode(new Error('refused')) // undefined
+ * ```
  */
 export declare function readErrorCode(error: unknown): string | undefined;
 
@@ -189,6 +299,16 @@ export declare function readErrorCode(error: unknown): string | undefined;
  *
  * @param status - The status read from the directory's path.
  * @returns The device, index node, and creation time that together name the allocation.
+ *
+ * @example
+ * ```ts
+ * import { statSync } from 'node:fs'
+ * import { readIdentity } from '@orkestrel/test/server'
+ *
+ * const status = statSync('/scratch')
+ *
+ * readIdentity(status) // { birth: status.birthtimeMs, device: status.dev, inode: status.ino }
+ * ```
  */
 export declare function readIdentity(status: Stats): ScratchIdentity;
 
@@ -228,13 +348,23 @@ export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
  * @param path - The absolute directory to remove.
  * @throws The last removal error once {@link REMOVE_TREE_MAX_ATTEMPTS} attempts are exhausted,
  * or immediately for any error whose code is not in {@link REMOVE_TREE_RETRYABLE_CODES}.
- * @remarks On Windows, a directory that a just-exited process still holds as its current
+ * @remarks On Windows, a directory that a recently exited process still holds as its current
  * working directory throws `EPERM` for a short interval after that process exits. Node's own
  * `rmSync` `maxRetries`/`retryDelay` options do not cover this error class on that host: probed
  * against a real held directory, they neither delay nor retry before rethrowing, so the retry
  * is implemented here with a synchronous sleep instead. Ten attempts 100ms apart bound the wait
  * at roughly one second. A hold that outlasts that second is {@link destroyScratch}'s case, which
  * retries every refusal inside a caller's budget rather than the codes named here.
+ *
+ * @example
+ * ```ts
+ * import { existsSync } from 'node:fs'
+ * import { removeTree } from '@orkestrel/test/server'
+ *
+ * removeTree('/scratch/tree')
+ *
+ * existsSync('/scratch/tree') // false
+ * ```
  */
 export declare function removeTree(path: string): void;
 
@@ -282,6 +412,16 @@ export declare function requestUpgrade(port: number, options?: UpgradeOptions):
  * @remarks This is {@link resolveContained} with the refusal every contained scratch operation makes
  * of an escape, so the check and its one message are stated once. Read `resolveContained` where an
  * escape is an answer rather than a refusal.
+ *
+ * @example
+ * ```ts
+ * import { requireContained } from '@orkestrel/test/server'
+ *
+ * requireContained('/scratch', 'nested/file.txt') // '/scratch/nested/file.txt'
+ *
+ * // Throws Error: Path outside scratch directory: ../escape.ts
+ * requireContained('/scratch', '../escape.ts')
+ * ```
  */
 export declare function requireContained(root: string, target: string): string;
 
@@ -341,8 +481,8 @@ export declare interface ScratchInterface {
     /**
      * Lists the names directly inside a directory in sorted order.
      *
-     * @param target - A relative or absolute directory path contained by the scratch directory. The
-     * scratch root is used when omitted.
+     * @param target - A relative or absolute directory path contained by the scratch directory.
+     * Default: the scratch root.
      * @returns The sorted entry names, without their parent paths.
      * @throws When the path escapes the scratch directory, the target is missing or is not a
      * directory, or the scratch root is a symbolic link or file.
@@ -387,6 +527,7 @@ export declare interface ScratchInterface {
      * Removes the allocated directory and everything in it when its identity still matches.
      *
      * @throws When the host refuses to inspect or remove the matching allocation.
+     * @remarks Idempotent. An identity that no longer matches removes nothing.
      */
     destroy(): void;
 }
@@ -422,6 +563,13 @@ export declare interface ScratchOptions {
  * @remarks Byte `0x80` is an invalid UTF-8 lead byte. POSIX stores the name verbatim and Windows
  * rejects it with `ENOENT`, so the answer is true on POSIX and false on Windows. The path is passed
  * as a `Buffer` because the byte survives no string round trip.
+ *
+ * @example
+ * ```ts
+ * import { supportsBytes } from '@orkestrel/test/server'
+ *
+ * supportsBytes() // true on a POSIX host, false on Windows
+ * ```
  */
 export declare function supportsBytes(): boolean;
 
@@ -437,6 +585,13 @@ export declare function supportsBytes(): boolean;
  * routes the second write onto the first entry, so reading the first back returns the second's
  * contents and the answer is false. The answer is true on a typical POSIX host and false on a
  * case-folding Windows or macOS volume.
+ *
+ * @example
+ * ```ts
+ * import { supportsCase } from '@orkestrel/test/server'
+ *
+ * supportsCase() // true on a case-sensitive volume, false on a case-folding one
+ * ```
  */
 export declare function supportsCase(): boolean;
 
@@ -452,6 +607,13 @@ export declare function supportsCase(): boolean;
  * The answer is false on a filesystem carrying neither reparse points nor symbolic links. Every call
  * probes and cleans up after itself, so a host whose answer changes is read again rather than
  * remembered.
+ *
+ * @example
+ * ```ts
+ * import { supportsDirectoryLinks } from '@orkestrel/test/server'
+ *
+ * supportsDirectoryLinks() // true where the host creates a symbolic link or a junction
+ * ```
  */
 export declare function supportsDirectoryLinks(): boolean;
 
@@ -483,6 +645,13 @@ export declare function supportsFileLinks(): boolean;
  * it: a POSIX host running as uid `0` stores every bit faithfully and bypasses the access check the
  * bits describe, so a caller that needs a permission to be enforced probes the refusal it needs
  * rather than reading this.
+ *
+ * @example
+ * ```ts
+ * import { supportsMode } from '@orkestrel/test/server'
+ *
+ * supportsMode() // true on a POSIX host, false on Windows
+ * ```
  */
 export declare function supportsMode(): boolean;
 
@@ -531,6 +700,20 @@ export declare type UpgradeResult = {
  * every other error ends the wait. The interval is validated for consistency with the wait family but
  * is not used, because this helper parks on the socket's events. Both listeners are removed on every
  * settlement, so a caller may wait on one socket repeatedly.
+ *
+ * @example
+ * ```ts
+ * import { connect, createServer } from 'node:net'
+ * import { createLoopback, waitForSocketClose } from '@orkestrel/test/server'
+ *
+ * const loopback = await createLoopback(createServer((socket) => socket.end()))
+ * const client = connect(loopback.port, '127.0.0.1')
+ *
+ * await waitForSocketClose(client, { budget: 1000 }) // undefined
+ * client.destroyed // true
+ *
+ * await loopback.destroy()
+ * ```
  */
 export declare function waitForSocketClose(socket: Socket, options?: WaitOptions): Promise<void>;
 

package/dist/src/server/index.d.ts

@@ -1,7 +1,7 @@
-import { Server } from 'node:net';
-import { Socket } from 'node:net';
-import { Stats } from 'node:fs';
-import { WaitOptions } from '@orkestrel/test';
+import type { Server } from 'node:net';
+import type { Socket } from 'node:net';
+import type { Stats } from 'node:fs';
+import type { WaitOptions } from '@orkestrel/test';
 
 /** Holds a name-keyed cookie store a test drives one origin with, filled from real responses. */
 export declare interface CookieJarInterface {
@@ -24,7 +24,8 @@ export declare interface CookieJarInterface {
      * @returns Those fields unmodified, in the order the response carried them.
      * @remarks Selection is by name alone. A field spelling `Max-Age=0` deletes its cookie and every
      * other field stores or replaces one, so `Domain`, `Path`, `Expires`, and `Secure` are read past
-     * rather than honoured. Nothing outlives the jar.
+     * rather than honoured. A field carrying no `name=value` pair is read past too and still
+     * returned. Nothing outlives the jar.
      */
     capture(response: Response): readonly string[];
 }
@@ -51,6 +52,17 @@ export declare function createCookieJar(): CookieJarInterface;
  * `EPERM`, while a directory or missing source is passed to a junction attempt. A missing source is
  * accepted to create a dangling junction. Where the host creates a junction, its stored value is the
  * resolved absolute path.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs'
+ * import { createLink } from '@orkestrel/test/server'
+ *
+ * // `/scratch/source` is a directory holding `file.txt`.
+ * createLink('/scratch/linked', '/scratch/source')
+ *
+ * readFileSync('/scratch/linked/file.txt', 'utf8') // 'linked'
+ * ```
  */
 export declare function createLink(path: string, source: string): void;
 
@@ -70,8 +82,69 @@ export declare function createLoopback(server: Server): Promise<LoopbackInterfac
  * @returns The scratch directory and its file operations.
  * @throws When the parent is missing, a symbolic link, or not a directory; when the prefix contains
  * `/` or `\`; or when allocation or seeding fails.
- * @remarks The parent defaults to the host temporary directory. The prefix defaults to
- * `orkestrel-test-`. Seed keys use root-relative paths.
+ * @remarks Default parent: the host temporary directory. Default prefix: `orkestrel-test-`. Seed
+ * keys use root-relative paths.
+ *
+ * @example Own a temporary directory
+ * ```ts
+ * import { createScratch } from '@orkestrel/test/server'
+ *
+ * const scratch = createScratch({ prefix: 'guide-', files: { 'src/index.ts': 'export {}\n' } })
+ *
+ * scratch.read('src/index.ts') // 'export {}\n'
+ * scratch.has('src') // true
+ * scratch.read('src') // throws Error: Scratch path is a directory: src
+ * scratch.read('missing.ts') // undefined
+ * scratch.write('../escape.ts', '') // throws Error: Path outside scratch directory: ../escape.ts
+ *
+ * // `write` answers the contained path it wrote, the way `ensure` and `link` answer theirs, so the
+ * // path goes straight to the code under test without joining it again.
+ * scratch.write('src/notes.ts', 'export {}\n') // `${scratch.path}/src/notes.ts`
+ *
+ * // `ensure` is how you get an empty directory, because every `write` creates a file.
+ * scratch.ensure('empty')
+ * scratch.names() // ['empty', 'src']
+ * scratch.names('empty') // []
+ *
+ * // `parent` puts the allocation somewhere other than the host temporary directory.
+ * const child = createScratch({ parent: scratch.path, prefix: 'child-' })
+ * scratch.names().length // 3 — 'empty', 'src', and the child allocation
+ * child.destroy()
+ * scratch.names().length // 2 — the child removed itself and nothing else
+ *
+ * // `link` creates the symbolic link the threat model names, and `read` follows it. A directory
+ * // source runs on a host that creates no symbolic link too; see "Hosts that create no symbolic
+ * // link" for what such a host does with a file source.
+ * const outside = createScratch({ prefix: 'outside-', files: { 'read.ts': 'export {}\n' } })
+ * scratch.link('gate', outside.path) // `${scratch.path}/gate` — the link's own path, not its destination
+ * scratch.read('gate/read.ts') // 'export {}\n' — read through the link, at its destination
+ *
+ * // A link pointing out of the allocation is resolved through, so a contained path acts outside it.
+ * scratch.ensure('gate/made') // `${scratch.path}/gate/made` — the lexical path, not the destination
+ * outside.names() // ['made', 'read.ts'] — the directory was made under `outside.path`
+ * scratch.names('gate') // ['made', 'read.ts'] — the same entries, listed through the link
+ *
+ * // `link` acts at the final segment rather than through it, so `gate` is occupied.
+ * scratch.link('gate', outside.path) // throws Error: EEXIST: file already exists
+ *
+ * // `has` reads the final segment without following it, and `read` follows it.
+ * scratch.link('dangling', 'missing.ts')
+ * scratch.has('dangling') // true — the link is there
+ * scratch.read('dangling') // undefined — what it points at is not
+ *
+ * // `remove` takes one contained entry and acts at the final segment, so a link goes and whatever it
+ * // pointed at stays. A missing target is a no-op.
+ * scratch.remove('dangling')
+ * scratch.has('dangling') // false
+ * scratch.remove('missing.ts') // no throw — there was nothing there
+ * scratch.remove('src') // the directory and everything under it
+ * scratch.names() // ['empty', 'gate']
+ *
+ * scratch.destroy()
+ * scratch.destroy() // no-op — destroy is idempotent
+ * outside.has('made') // true — destroy unlinks `gate` and leaves what it pointed at
+ * outside.destroy()
+ * ```
  */
 export declare function createScratch(options?: ScratchOptions): ScratchInterface;
 
@@ -84,7 +157,7 @@ export declare function createScratch(options?: ScratchOptions): ScratchInterfac
  * @throws The abort reason, or an `Error` when a bound is invalid or the budget elapses. The
  * exhaustion error carries the last host refusal as its `cause`.
  * @remarks Default budget: `10000` milliseconds. Default interval: `25` milliseconds. A host holds a
- * directory for a short interval after the process that held it exits, and a just-stopped child's
+ * directory for a short interval after the process that held it exits, and a recently stopped child's
  * working directory is the case this exists for, so removal is attempted until the host lets go
  * rather than exactly once. {@link ScratchInterface.destroy} stays synchronous and is unchanged; this
  * is the bounded retry around it. A directory nothing releases still fails, with the host's own
@@ -120,6 +193,14 @@ export declare interface InventoryOptions {
  * @param key - The root-relative key to test.
  * @param exclusions - The normalized root-relative exclusion keys.
  * @returns True if an exclusion names the key or one of its ancestors; false otherwise.
+ *
+ * @example
+ * ```ts
+ * import { isExcluded } from '@orkestrel/test/server'
+ *
+ * isExcluded('src/index.ts', ['src']) // true
+ * isExcluded('src-other/index.ts', ['src']) // false
+ * ```
  */
 export declare function isExcluded(key: string, exclusions: readonly string[]): boolean;
 
@@ -139,6 +220,14 @@ export declare function isExcluded(key: string, exclusions: readonly string[]):
  *
  * A Linux zombie — a process that has exited and whose parent has not reaped it — still accepts
  * signal `0`, so its `/proc` status is read and a `Z` state reads as false.
+ *
+ * @example
+ * ```ts
+ * import { isRunning } from '@orkestrel/test/server'
+ *
+ * isRunning(process.pid) // true
+ * isRunning(2 ** 31) // false
+ * ```
  */
 export declare function isRunning(pid: number): boolean;
 
@@ -169,6 +258,17 @@ export declare interface LoopbackInterface {
  * @remarks All three fields are compared because none of them alone identifies an allocation. A
  * device is shared by every directory on one filesystem, an index node is reused once its directory
  * is removed, and a creation time repeats within the host's timestamp resolution.
+ *
+ * @example
+ * ```ts
+ * import { statSync } from 'node:fs'
+ * import { matchesIdentity, readIdentity } from '@orkestrel/test/server'
+ *
+ * const allocation = readIdentity(statSync('/scratch'))
+ *
+ * matchesIdentity(readIdentity(statSync('/scratch')), allocation) // true
+ * matchesIdentity({ birth: 3, device: 1, inode: 9 }, { birth: 3, device: 1, inode: 2 }) // false
+ * ```
  */
 export declare function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean;
 
@@ -181,6 +281,16 @@ export declare function matchesIdentity(current: ScratchIdentity, allocation: Sc
  * `code`, and one carrying a `code` that is not a string all answer `undefined`. A null-prototype
  * object is read the same way, because the key is tested with `in` rather than through
  * `hasOwnProperty`.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs'
+ * import { captureError } from '@orkestrel/test'
+ * import { readErrorCode } from '@orkestrel/test/server'
+ *
+ * readErrorCode(captureError(() => readFileSync('/scratch/absent.txt', 'utf8'))) // 'ENOENT'
+ * readErrorCode(new Error('refused')) // undefined
+ * ```
  */
 export declare function readErrorCode(error: unknown): string | undefined;
 
@@ -189,6 +299,16 @@ export declare function readErrorCode(error: unknown): string | undefined;
  *
  * @param status - The status read from the directory's path.
  * @returns The device, index node, and creation time that together name the allocation.
+ *
+ * @example
+ * ```ts
+ * import { statSync } from 'node:fs'
+ * import { readIdentity } from '@orkestrel/test/server'
+ *
+ * const status = statSync('/scratch')
+ *
+ * readIdentity(status) // { birth: status.birthtimeMs, device: status.dev, inode: status.ino }
+ * ```
  */
 export declare function readIdentity(status: Stats): ScratchIdentity;
 
@@ -228,13 +348,23 @@ export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
  * @param path - The absolute directory to remove.
  * @throws The last removal error once {@link REMOVE_TREE_MAX_ATTEMPTS} attempts are exhausted,
  * or immediately for any error whose code is not in {@link REMOVE_TREE_RETRYABLE_CODES}.
- * @remarks On Windows, a directory that a just-exited process still holds as its current
+ * @remarks On Windows, a directory that a recently exited process still holds as its current
  * working directory throws `EPERM` for a short interval after that process exits. Node's own
  * `rmSync` `maxRetries`/`retryDelay` options do not cover this error class on that host: probed
  * against a real held directory, they neither delay nor retry before rethrowing, so the retry
  * is implemented here with a synchronous sleep instead. Ten attempts 100ms apart bound the wait
  * at roughly one second. A hold that outlasts that second is {@link destroyScratch}'s case, which
  * retries every refusal inside a caller's budget rather than the codes named here.
+ *
+ * @example
+ * ```ts
+ * import { existsSync } from 'node:fs'
+ * import { removeTree } from '@orkestrel/test/server'
+ *
+ * removeTree('/scratch/tree')
+ *
+ * existsSync('/scratch/tree') // false
+ * ```
  */
 export declare function removeTree(path: string): void;
 
@@ -282,6 +412,16 @@ export declare function requestUpgrade(port: number, options?: UpgradeOptions):
  * @remarks This is {@link resolveContained} with the refusal every contained scratch operation makes
  * of an escape, so the check and its one message are stated once. Read `resolveContained` where an
  * escape is an answer rather than a refusal.
+ *
+ * @example
+ * ```ts
+ * import { requireContained } from '@orkestrel/test/server'
+ *
+ * requireContained('/scratch', 'nested/file.txt') // '/scratch/nested/file.txt'
+ *
+ * // Throws Error: Path outside scratch directory: ../escape.ts
+ * requireContained('/scratch', '../escape.ts')
+ * ```
  */
 export declare function requireContained(root: string, target: string): string;
 
@@ -341,8 +481,8 @@ export declare interface ScratchInterface {
     /**
      * Lists the names directly inside a directory in sorted order.
      *
-     * @param target - A relative or absolute directory path contained by the scratch directory. The
-     * scratch root is used when omitted.
+     * @param target - A relative or absolute directory path contained by the scratch directory.
+     * Default: the scratch root.
      * @returns The sorted entry names, without their parent paths.
      * @throws When the path escapes the scratch directory, the target is missing or is not a
      * directory, or the scratch root is a symbolic link or file.
@@ -387,6 +527,7 @@ export declare interface ScratchInterface {
      * Removes the allocated directory and everything in it when its identity still matches.
      *
      * @throws When the host refuses to inspect or remove the matching allocation.
+     * @remarks Idempotent. An identity that no longer matches removes nothing.
      */
     destroy(): void;
 }
@@ -422,6 +563,13 @@ export declare interface ScratchOptions {
  * @remarks Byte `0x80` is an invalid UTF-8 lead byte. POSIX stores the name verbatim and Windows
  * rejects it with `ENOENT`, so the answer is true on POSIX and false on Windows. The path is passed
  * as a `Buffer` because the byte survives no string round trip.
+ *
+ * @example
+ * ```ts
+ * import { supportsBytes } from '@orkestrel/test/server'
+ *
+ * supportsBytes() // true on a POSIX host, false on Windows
+ * ```
  */
 export declare function supportsBytes(): boolean;
 
@@ -437,6 +585,13 @@ export declare function supportsBytes(): boolean;
  * routes the second write onto the first entry, so reading the first back returns the second's
  * contents and the answer is false. The answer is true on a typical POSIX host and false on a
  * case-folding Windows or macOS volume.
+ *
+ * @example
+ * ```ts
+ * import { supportsCase } from '@orkestrel/test/server'
+ *
+ * supportsCase() // true on a case-sensitive volume, false on a case-folding one
+ * ```
  */
 export declare function supportsCase(): boolean;
 
@@ -452,6 +607,13 @@ export declare function supportsCase(): boolean;
  * The answer is false on a filesystem carrying neither reparse points nor symbolic links. Every call
  * probes and cleans up after itself, so a host whose answer changes is read again rather than
  * remembered.
+ *
+ * @example
+ * ```ts
+ * import { supportsDirectoryLinks } from '@orkestrel/test/server'
+ *
+ * supportsDirectoryLinks() // true where the host creates a symbolic link or a junction
+ * ```
  */
 export declare function supportsDirectoryLinks(): boolean;
 
@@ -483,6 +645,13 @@ export declare function supportsFileLinks(): boolean;
  * it: a POSIX host running as uid `0` stores every bit faithfully and bypasses the access check the
  * bits describe, so a caller that needs a permission to be enforced probes the refusal it needs
  * rather than reading this.
+ *
+ * @example
+ * ```ts
+ * import { supportsMode } from '@orkestrel/test/server'
+ *
+ * supportsMode() // true on a POSIX host, false on Windows
+ * ```
  */
 export declare function supportsMode(): boolean;
 
@@ -531,6 +700,20 @@ export declare type UpgradeResult = {
  * every other error ends the wait. The interval is validated for consistency with the wait family but
  * is not used, because this helper parks on the socket's events. Both listeners are removed on every
  * settlement, so a caller may wait on one socket repeatedly.
+ *
+ * @example
+ * ```ts
+ * import { connect, createServer } from 'node:net'
+ * import { createLoopback, waitForSocketClose } from '@orkestrel/test/server'
+ *
+ * const loopback = await createLoopback(createServer((socket) => socket.end()))
+ * const client = connect(loopback.port, '127.0.0.1')
+ *
+ * await waitForSocketClose(client, { budget: 1000 }) // undefined
+ * client.destroyed // true
+ *
+ * await loopback.destroy()
+ * ```
  */
 export declare function waitForSocketClose(socket: Socket, options?: WaitOptions): Promise<void>;