@orkestrel/test 0.0.13 → 0.0.15

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;
 
@@ -72,6 +84,67 @@ export declare function createLoopback(server: Server): Promise<LoopbackInterfac
  * `/` or `\`; or when allocation or seeding fails.
  * @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;
 
@@ -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.js

@@ -4,6 +4,7 @@ import { request } from "node:http";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isFunction, isNumber, isObject, isString } from "@orkestrel/contract";
 import { checkBounds, waitForDelay } from "../core/index.js";
 import { once } from "node:events";
 //#region src/server/constants.ts
@@ -49,6 +50,16 @@ function resolveContained(root, target) {
 * @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')
+* ```
 */
 function requireContained(root, target) {
 	const candidate = resolveContained(root, target);
@@ -60,6 +71,16 @@ function requireContained(root, target) {
 *
 * @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 }
+* ```
 */
 function readIdentity(status) {
 	return {
@@ -77,9 +98,19 @@ function readIdentity(status) {
 * `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
+* ```
 */
 function readErrorCode(error) {
-	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : void 0;
+	return isObject(error) && "code" in error && isString(error.code) ? error.code : void 0;
 }
 /**
 * Reports whether two directory identities name the same allocation.
@@ -90,6 +121,17 @@ function readErrorCode(error) {
 * @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
+* ```
 */
 function matchesIdentity(current, allocation) {
 	return current.device === allocation.device && current.inode === allocation.inode && current.birth === allocation.birth;
@@ -100,6 +142,14 @@ function matchesIdentity(current, allocation) {
 * @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
+* ```
 */
 function isExcluded(key, exclusions) {
 	return exclusions.some((rule) => rule === "" || key === rule || key.startsWith(`${rule}/`));
@@ -116,6 +166,17 @@ function isExcluded(key, exclusions) {
 * `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'
+* ```
 */
 function createLink(path, source) {
 	try {
@@ -134,13 +195,23 @@ function createLink(path, source) {
 * @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
+* ```
 */
 function removeTree(path) {
 	for (let attempt = 1;; attempt++) try {
@@ -169,7 +240,7 @@ function removeTree(path) {
 * key below it, and it applies to a named target and a walked entry alike.
 */
 function readInventory(root, targets, options) {
-	const supplied = resolve(typeof root === "string" ? root : fileURLToPath(root));
+	const supplied = resolve(isString(root) ? root : fileURLToPath(root));
 	const rootStatus = lstatSync(supplied);
 	if (rootStatus.isSymbolicLink()) throw new Error("Root is a symbolic link");
 	if (!rootStatus.isDirectory()) throw new Error("Root is not a directory");
@@ -240,6 +311,14 @@ function readInventory(root, targets, options) {
 *
 * 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
+* ```
 */
 function isRunning(pid) {
 	try {
@@ -269,6 +348,20 @@ function isRunning(pid) {
 * 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()
+* ```
 */
 async function waitForSocketClose(socket, options) {
 	const budget = options?.budget ?? 1e3;
@@ -321,7 +414,7 @@ async function waitForSocketClose(socket, options) {
 * @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
@@ -468,6 +561,13 @@ async function requestUpgrade(port, options) {
 * 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
+* ```
 */
 function supportsDirectoryLinks() {
 	const directory = mkdtempSync(join(tmpdir(), "orkestrel-test-directory-links-"));
@@ -524,6 +624,13 @@ function supportsFileLinks() {
 * 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
+* ```
 */
 function supportsMode() {
 	const directory = mkdtempSync(join(tmpdir(), "orkestrel-test-mode-"));
@@ -549,6 +656,13 @@ function supportsMode() {
 * 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
+* ```
 */
 function supportsCase() {
 	const directory = mkdtempSync(join(tmpdir(), "orkestrel-test-case-"));
@@ -574,6 +688,13 @@ function supportsCase() {
 * @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
+* ```
 */
 function supportsBytes() {
 	const directory = mkdtempSync(join(tmpdir(), "orkestrel-test-bytes-"));
@@ -598,6 +719,67 @@ function supportsBytes() {
 * `/` or `\`; or when allocation or seeding fails.
 * @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()
+* ```
 */
 function createScratch(options) {
 	const parent = resolve(options?.parent ?? tmpdir());
@@ -696,7 +878,7 @@ async function createLoopback(server) {
 	server.listen(0, "127.0.0.1");
 	await once(server, "listening");
 	const address = server.address();
-	if (typeof address !== "object" || address === null || !("port" in address) || typeof address.port !== "number") throw new Error(`Loopback address must have a numeric port; found ${String(address)}`);
+	if (!isObject(address) || !("port" in address) || !isNumber(address.port)) throw new Error(`Loopback address must have a numeric port; found ${String(address)}`);
 	const port = address.port;
 	let destruction;
 	return {
@@ -704,7 +886,7 @@ async function createLoopback(server) {
 		port,
 		destroy() {
 			if (destruction === void 0) destruction = new Promise((resolveClose, rejectClose) => {
-				if ("closeAllConnections" in server && typeof server.closeAllConnections === "function") server.closeAllConnections();
+				if ("closeAllConnections" in server && isFunction(server.closeAllConnections)) server.closeAllConnections();
 				server.close((error) => {
 					if (error === void 0 || "code" in error && error.code === "ERR_SERVER_NOT_RUNNING") resolveClose();
 					else rejectClose(error);