@orkestrel/test 0.0.13 → 0.0.15

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

@@ -9,6 +9,16 @@
  * @returns The exhaustion error, unthrown.
  * @remarks Both of `retryUntil`'s elapsed checks raise this one message, so an edit to it lands in
  * one place. The rendered value is appended only when the retry produced one.
+ *
+ * @example
+ * ```ts
+ * import { buildRetryExhausted } from '@orkestrel/test'
+ *
+ * const exhausted = buildRetryExhausted('registry answers', 30, 31, '"starting"', undefined)
+ *
+ * exhausted.message
+ * // 'Retry "registry answers" did not succeed within 30ms (waited 31ms) (last value: "starting")'
+ * ```
  */
 export declare function buildRetryExhausted(description: string, budget: number, elapsed: number, last: string | undefined, cause: unknown): Error;
 
@@ -30,6 +40,16 @@ export declare function captureError(thunk: () => unknown): unknown;
  * `<subject> interval must be finite and non-negative`.
  * @remarks Every member of the wait family resolves its own defaults first and passes the resolved
  * numbers here, so each keeps its own defaults while one contract states what a bound must be.
+ *
+ * @example
+ * ```ts
+ * import { checkBounds } from '@orkestrel/test'
+ *
+ * checkBounds('Wait', 1000, 10) // undefined
+ *
+ * // Throws Error: Retry budget must be finite and non-negative
+ * checkBounds('Retry', -1, 10)
+ * ```
  */
 export declare function checkBounds(subject: string, budget: number, interval: number): void;
 
@@ -157,6 +177,18 @@ export declare function createTeardown(): TeardownInterface;
  * @returns The decoded values in physical-line order.
  * @throws An `Error` naming the malformed physical line, with the native `SyntaxError` as its
  * `cause`.
+ * @remarks An empty line contributes no value, and a trailing carriage return is dropped before the
+ * line is parsed, so text written with either line ending decodes the same.
+ *
+ * @example
+ * ```ts
+ * import { decodeJSONLines } from '@orkestrel/test'
+ *
+ * decodeJSONLines('{"ready":true}\n7\n') // [{ ready: true }, 7]
+ *
+ * // Throws Error: Invalid JSON on line 3
+ * decodeJSONLines('{}\n\n{')
+ * ```
  */
 export declare function decodeJSONLines(text: string): readonly unknown[];
 
@@ -169,6 +201,21 @@ export declare function decodeJSONLines(text: string): readonly unknown[];
  * @remarks The dropped registration's cleanup controller is aborted as it leaves, so the scope
  * subscription installed beside it leaves with it. Removing the installed listener from the signal
  * stays with the caller, because only the scope-abort path has one to remove.
+ *
+ * @example
+ * ```ts
+ * import type { SignalRegistration } from '@orkestrel/test'
+ * import { dropRegistration } from '@orkestrel/test'
+ *
+ * const listener: EventListener = () => undefined
+ * const installed: EventListenerObject = { handleEvent: () => undefined }
+ * const cleanup = new AbortController()
+ * const registrations: SignalRegistration[] = [[listener, installed, true, cleanup]]
+ *
+ * dropRegistration(registrations, installed)?.[1] === installed // true
+ * cleanup.signal.aborted // true
+ * dropRegistration(registrations, installed) // undefined
+ * ```
  */
 export declare function dropRegistration(registrations: SignalRegistration[], installed: EventListener | EventListenerObject): SignalRegistration | undefined;
 
@@ -176,6 +223,8 @@ export declare function dropRegistration(registrations: SignalRegistration[], in
  * Subscribes handlers to a typed event source.
  *
  * @typeParam TMap - The event names and argument tuples the source delivers.
+ * @remarks The subscribe half is all this asks for, so a source that also removes handlers, emits,
+ * or counts subscriptions satisfies it unchanged.
  */
 export declare interface EventSourceInterface<TMap extends Record<string, readonly unknown[]>> {
     /**
@@ -251,18 +300,6 @@ export declare function executeScenario<TState extends string, TEvent extends st
  */
 export declare function executeScenarios<TState extends string, TEvent extends string, TContext>(scenarios: ReadonlyArray<StateScenario<TState, TEvent, TContext>>, build: (scenario: StateScenario<TState, TEvent, TContext>) => TContext | Promise<TContext>): Promise<void>;
 
-/**
- * Represents one operation that raised a failure instead of producing a value.
- *
- * @typeParam E - The failure type.
- */
-export declare interface Failure<E> {
-    /** Holds the discriminant that names the failed arm. */
-    readonly success: false;
-    /** Holds the failure the operation raised. */
-    readonly error: E;
-}
-
 /**
  * Normalizes headers into a frozen plain record.
  *
@@ -308,6 +345,18 @@ export declare function invokeUnchecked<T>(target: unknown, method: unknown, arg
  * wiring each recorder to exactly the event where it stores that recorder. A direct caller must
  * establish the same pairing before it relies on the narrowing. This guard takes the listed events
  * through a reference parameter rather than using the canonical single-value guard form.
+ *
+ * @example
+ * ```ts
+ * import { createRecorder, isRecorderMapComplete } from '@orkestrel/test'
+ *
+ * type ReadyEvents = { readonly ready: readonly [name: string, step: number] }
+ *
+ * const value: unknown = { ready: createRecorder<readonly [name: string, step: number]>() }
+ *
+ * isRecorderMapComplete<ReadyEvents, 'ready'>(value, ['ready']) // true
+ * isRecorderMapComplete<ReadyEvents, 'ready'>({ ready: 1 }, ['ready']) // false
+ * ```
  */
 export declare function isRecorderMapComplete<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(value: unknown, events: readonly TName[]): value is RecorderMap<TMap, TName>;
 
@@ -344,11 +393,6 @@ export declare type JSONSafe<T> = unknown extends T ? T : T extends string | num
     readonly [K in keyof T]: K extends symbol ? never : JSONSafe<T[K]>;
 } : never;
 
-/** Covers any value JSON can represent, so a round trip through JSON preserves the type. */
-export declare type JSONValue = string | number | boolean | null | readonly JSONValue[] | {
-    readonly [key: string]: JSONValue;
-};
-
 /**
  * Reads a property from an unknown object or function.
  *
@@ -374,7 +418,11 @@ export declare interface RecorderInterface<TArgs extends readonly unknown[]> {
     readonly count: number;
     /** Holds the callback to hand to the code under test. */
     readonly handler: (...args: TArgs) => void;
-    /** Discards the recorded calls and keeps the recorder usable. */
+    /**
+     * Discards the recorded calls and keeps the recorder usable.
+     *
+     * @remarks The list is truncated in place, so a `calls` reference taken earlier empties too.
+     */
     clear(): void;
 }
 
@@ -389,12 +437,13 @@ export declare type RecorderMap<TMap extends Record<string, readonly unknown[]>,
 };
 
 /**
- * Requires a value to be present.
+ * Narrows a value away from `null` and `undefined`, throwing when it is absent.
  *
  * @typeParam T - The required value type.
  * @param value - The value to check.
  * @param message - The error message used when the value is absent. Default: `'Value is required'`.
  * @returns The present value.
+ * @throws An `Error` carrying `message` when the value is `null` or `undefined`.
  */
 export declare function requireValue<T>(value: T | null | undefined, message?: string): T;
 
@@ -417,28 +466,22 @@ export declare interface ResourceFactoryInterface {
      * Creates a numbered resource.
      *
      * @returns The next monotonically increasing id.
+     * @remarks The id is the creation record's length plus one, so it counts allocations rather than
+     * live resources: a destroyed id is never reissued, and clearing `created` restarts the numbering
+     * at `1`.
      */
     create(): number;
     /**
      * Destroys a numbered resource.
      *
      * @param id - The resource id to destroy.
+     * @remarks It records the id and nothing else: it frees nothing, refuses nothing, and accepts an
+     * id that was never created, so a suite asserts on the record rather than on a refusal.
      */
     destroy(id: number): void;
 }
 
-/**
- * Represents the outcome of one operation: the value it produced, or the failure it raised.
- *
- * @typeParam T - The produced value type.
- * @typeParam E - The failure type. Defaults to `Error`.
- * @remarks `success` is the discriminant, so a caller narrows on it before reading `value` or
- * `error`. This package declares no runtime dependency, so this is the one outcome contract its own
- * members read rather than an anonymous union written at each call site.
- */
-export declare type Result<T, E = Error> = Success<T> | Failure<E>;
-
-/** Configures a bounded retry. */
+/** Configures a bounded retry, adding an optional producer-call limit to a bounded wait's bounds. */
 export declare interface RetryOptions extends WaitOptions {
     /** Caps the number of producer calls. When omitted, only the time budget bounds the retry. */
     readonly attempts?: number;
@@ -579,6 +622,7 @@ export declare interface StateScenario<TState extends string, TEvent extends str
      *
      * @param context - The fixture this row drives.
      * @param state - The transition's `to` state.
+     * @remarks Whatever it throws is renamed with the row's name and rethrown.
      */
     assert(context: TContext, state: TState): Promise<void> | void;
 }
@@ -603,18 +647,6 @@ export declare interface StateTransition<TState extends string, TEvent extends s
     readonly to: TState;
 }
 
-/**
- * Represents one operation that produced a value.
- *
- * @typeParam T - The produced value type.
- */
-export declare interface Success<T> {
-    /** Holds the discriminant that names the produced arm. */
-    readonly success: true;
-    /** Holds the value the operation produced. */
-    readonly value: T;
-}
-
 /** Represents the work one teardown entry performs when the list is destroyed. */
 export declare type TeardownHandler = () => void | Promise<void>;
 
@@ -626,6 +658,8 @@ export declare interface TeardownInterface {
      * Registers a handler to run when the list is destroyed.
      *
      * @param handler - The work to perform.
+     * @remarks Registration order is what `destroy` reverses, so the newest registration is undone
+     * first.
      */
     add(handler: TeardownHandler): void;
     /**
@@ -689,7 +723,8 @@ export declare function waitForDelay(ms?: number): Promise<void>;
 export declare function waitForEvent<TArgs extends readonly unknown[]>(subscribe: EventSubscriber<TArgs>, description: string, options?: WaitOptions): Promise<TArgs>;
 
 /**
- * Configures a bounded asynchronous wait.
+ * Configures a bounded asynchronous wait with an elapsed-time limit, a delay between readings, and
+ * an abort signal.
  *
  * @remarks
  * A default belongs to the function that reads these bounds rather than to the shape, because the

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

@@ -9,6 +9,16 @@
  * @returns The exhaustion error, unthrown.
  * @remarks Both of `retryUntil`'s elapsed checks raise this one message, so an edit to it lands in
  * one place. The rendered value is appended only when the retry produced one.
+ *
+ * @example
+ * ```ts
+ * import { buildRetryExhausted } from '@orkestrel/test'
+ *
+ * const exhausted = buildRetryExhausted('registry answers', 30, 31, '"starting"', undefined)
+ *
+ * exhausted.message
+ * // 'Retry "registry answers" did not succeed within 30ms (waited 31ms) (last value: "starting")'
+ * ```
  */
 export declare function buildRetryExhausted(description: string, budget: number, elapsed: number, last: string | undefined, cause: unknown): Error;
 
@@ -30,6 +40,16 @@ export declare function captureError(thunk: () => unknown): unknown;
  * `<subject> interval must be finite and non-negative`.
  * @remarks Every member of the wait family resolves its own defaults first and passes the resolved
  * numbers here, so each keeps its own defaults while one contract states what a bound must be.
+ *
+ * @example
+ * ```ts
+ * import { checkBounds } from '@orkestrel/test'
+ *
+ * checkBounds('Wait', 1000, 10) // undefined
+ *
+ * // Throws Error: Retry budget must be finite and non-negative
+ * checkBounds('Retry', -1, 10)
+ * ```
  */
 export declare function checkBounds(subject: string, budget: number, interval: number): void;
 
@@ -157,6 +177,18 @@ export declare function createTeardown(): TeardownInterface;
  * @returns The decoded values in physical-line order.
  * @throws An `Error` naming the malformed physical line, with the native `SyntaxError` as its
  * `cause`.
+ * @remarks An empty line contributes no value, and a trailing carriage return is dropped before the
+ * line is parsed, so text written with either line ending decodes the same.
+ *
+ * @example
+ * ```ts
+ * import { decodeJSONLines } from '@orkestrel/test'
+ *
+ * decodeJSONLines('{"ready":true}\n7\n') // [{ ready: true }, 7]
+ *
+ * // Throws Error: Invalid JSON on line 3
+ * decodeJSONLines('{}\n\n{')
+ * ```
  */
 export declare function decodeJSONLines(text: string): readonly unknown[];
 
@@ -169,6 +201,21 @@ export declare function decodeJSONLines(text: string): readonly unknown[];
  * @remarks The dropped registration's cleanup controller is aborted as it leaves, so the scope
  * subscription installed beside it leaves with it. Removing the installed listener from the signal
  * stays with the caller, because only the scope-abort path has one to remove.
+ *
+ * @example
+ * ```ts
+ * import type { SignalRegistration } from '@orkestrel/test'
+ * import { dropRegistration } from '@orkestrel/test'
+ *
+ * const listener: EventListener = () => undefined
+ * const installed: EventListenerObject = { handleEvent: () => undefined }
+ * const cleanup = new AbortController()
+ * const registrations: SignalRegistration[] = [[listener, installed, true, cleanup]]
+ *
+ * dropRegistration(registrations, installed)?.[1] === installed // true
+ * cleanup.signal.aborted // true
+ * dropRegistration(registrations, installed) // undefined
+ * ```
  */
 export declare function dropRegistration(registrations: SignalRegistration[], installed: EventListener | EventListenerObject): SignalRegistration | undefined;
 
@@ -176,6 +223,8 @@ export declare function dropRegistration(registrations: SignalRegistration[], in
  * Subscribes handlers to a typed event source.
  *
  * @typeParam TMap - The event names and argument tuples the source delivers.
+ * @remarks The subscribe half is all this asks for, so a source that also removes handlers, emits,
+ * or counts subscriptions satisfies it unchanged.
  */
 export declare interface EventSourceInterface<TMap extends Record<string, readonly unknown[]>> {
     /**
@@ -251,18 +300,6 @@ export declare function executeScenario<TState extends string, TEvent extends st
  */
 export declare function executeScenarios<TState extends string, TEvent extends string, TContext>(scenarios: ReadonlyArray<StateScenario<TState, TEvent, TContext>>, build: (scenario: StateScenario<TState, TEvent, TContext>) => TContext | Promise<TContext>): Promise<void>;
 
-/**
- * Represents one operation that raised a failure instead of producing a value.
- *
- * @typeParam E - The failure type.
- */
-export declare interface Failure<E> {
-    /** Holds the discriminant that names the failed arm. */
-    readonly success: false;
-    /** Holds the failure the operation raised. */
-    readonly error: E;
-}
-
 /**
  * Normalizes headers into a frozen plain record.
  *
@@ -308,6 +345,18 @@ export declare function invokeUnchecked<T>(target: unknown, method: unknown, arg
  * wiring each recorder to exactly the event where it stores that recorder. A direct caller must
  * establish the same pairing before it relies on the narrowing. This guard takes the listed events
  * through a reference parameter rather than using the canonical single-value guard form.
+ *
+ * @example
+ * ```ts
+ * import { createRecorder, isRecorderMapComplete } from '@orkestrel/test'
+ *
+ * type ReadyEvents = { readonly ready: readonly [name: string, step: number] }
+ *
+ * const value: unknown = { ready: createRecorder<readonly [name: string, step: number]>() }
+ *
+ * isRecorderMapComplete<ReadyEvents, 'ready'>(value, ['ready']) // true
+ * isRecorderMapComplete<ReadyEvents, 'ready'>({ ready: 1 }, ['ready']) // false
+ * ```
  */
 export declare function isRecorderMapComplete<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(value: unknown, events: readonly TName[]): value is RecorderMap<TMap, TName>;
 
@@ -344,11 +393,6 @@ export declare type JSONSafe<T> = unknown extends T ? T : T extends string | num
     readonly [K in keyof T]: K extends symbol ? never : JSONSafe<T[K]>;
 } : never;
 
-/** Covers any value JSON can represent, so a round trip through JSON preserves the type. */
-export declare type JSONValue = string | number | boolean | null | readonly JSONValue[] | {
-    readonly [key: string]: JSONValue;
-};
-
 /**
  * Reads a property from an unknown object or function.
  *
@@ -374,7 +418,11 @@ export declare interface RecorderInterface<TArgs extends readonly unknown[]> {
     readonly count: number;
     /** Holds the callback to hand to the code under test. */
     readonly handler: (...args: TArgs) => void;
-    /** Discards the recorded calls and keeps the recorder usable. */
+    /**
+     * Discards the recorded calls and keeps the recorder usable.
+     *
+     * @remarks The list is truncated in place, so a `calls` reference taken earlier empties too.
+     */
     clear(): void;
 }
 
@@ -389,12 +437,13 @@ export declare type RecorderMap<TMap extends Record<string, readonly unknown[]>,
 };
 
 /**
- * Requires a value to be present.
+ * Narrows a value away from `null` and `undefined`, throwing when it is absent.
  *
  * @typeParam T - The required value type.
  * @param value - The value to check.
  * @param message - The error message used when the value is absent. Default: `'Value is required'`.
  * @returns The present value.
+ * @throws An `Error` carrying `message` when the value is `null` or `undefined`.
  */
 export declare function requireValue<T>(value: T | null | undefined, message?: string): T;
 
@@ -417,28 +466,22 @@ export declare interface ResourceFactoryInterface {
      * Creates a numbered resource.
      *
      * @returns The next monotonically increasing id.
+     * @remarks The id is the creation record's length plus one, so it counts allocations rather than
+     * live resources: a destroyed id is never reissued, and clearing `created` restarts the numbering
+     * at `1`.
      */
     create(): number;
     /**
      * Destroys a numbered resource.
      *
      * @param id - The resource id to destroy.
+     * @remarks It records the id and nothing else: it frees nothing, refuses nothing, and accepts an
+     * id that was never created, so a suite asserts on the record rather than on a refusal.
      */
     destroy(id: number): void;
 }
 
-/**
- * Represents the outcome of one operation: the value it produced, or the failure it raised.
- *
- * @typeParam T - The produced value type.
- * @typeParam E - The failure type. Defaults to `Error`.
- * @remarks `success` is the discriminant, so a caller narrows on it before reading `value` or
- * `error`. This package declares no runtime dependency, so this is the one outcome contract its own
- * members read rather than an anonymous union written at each call site.
- */
-export declare type Result<T, E = Error> = Success<T> | Failure<E>;
-
-/** Configures a bounded retry. */
+/** Configures a bounded retry, adding an optional producer-call limit to a bounded wait's bounds. */
 export declare interface RetryOptions extends WaitOptions {
     /** Caps the number of producer calls. When omitted, only the time budget bounds the retry. */
     readonly attempts?: number;
@@ -579,6 +622,7 @@ export declare interface StateScenario<TState extends string, TEvent extends str
      *
      * @param context - The fixture this row drives.
      * @param state - The transition's `to` state.
+     * @remarks Whatever it throws is renamed with the row's name and rethrown.
      */
     assert(context: TContext, state: TState): Promise<void> | void;
 }
@@ -603,18 +647,6 @@ export declare interface StateTransition<TState extends string, TEvent extends s
     readonly to: TState;
 }
 
-/**
- * Represents one operation that produced a value.
- *
- * @typeParam T - The produced value type.
- */
-export declare interface Success<T> {
-    /** Holds the discriminant that names the produced arm. */
-    readonly success: true;
-    /** Holds the value the operation produced. */
-    readonly value: T;
-}
-
 /** Represents the work one teardown entry performs when the list is destroyed. */
 export declare type TeardownHandler = () => void | Promise<void>;
 
@@ -626,6 +658,8 @@ export declare interface TeardownInterface {
      * Registers a handler to run when the list is destroyed.
      *
      * @param handler - The work to perform.
+     * @remarks Registration order is what `destroy` reverses, so the newest registration is undone
+     * first.
      */
     add(handler: TeardownHandler): void;
     /**
@@ -689,7 +723,8 @@ export declare function waitForDelay(ms?: number): Promise<void>;
 export declare function waitForEvent<TArgs extends readonly unknown[]>(subscribe: EventSubscriber<TArgs>, description: string, options?: WaitOptions): Promise<TArgs>;
 
 /**
- * Configures a bounded asynchronous wait.
+ * Configures a bounded asynchronous wait with an elapsed-time limit, a delay between readings, and
+ * an abort signal.
  *
  * @remarks
  * A default belongs to the function that reads these bounds rather than to the shape, because the

package/dist/src/core/index.js

@@ -1,3 +1,4 @@
+import { attempt, holds, isArray, isDefined, isError, isFiniteNumber, isFunction, isInteger, isNumber, isObject, isSymbol } from "@orkestrel/contract";
 //#region src/core/constants.ts
 /**
 * Names the attributes a statechart harness publishes, keyed by the fact each one carries.
@@ -65,19 +66,29 @@ var STATECHART_STATUSES = Object.freeze([
 * wiring each recorder to exactly the event where it stores that recorder. A direct caller must
 * establish the same pairing before it relies on the narrowing. This guard takes the listed events
 * through a reference parameter rather than using the canonical single-value guard form.
+*
+* @example
+* ```ts
+* import { createRecorder, isRecorderMapComplete } from '@orkestrel/test'
+*
+* type ReadyEvents = { readonly ready: readonly [name: string, step: number] }
+*
+* const value: unknown = { ready: createRecorder<readonly [name: string, step: number]>() }
+*
+* isRecorderMapComplete<ReadyEvents, 'ready'>(value, ['ready']) // true
+* isRecorderMapComplete<ReadyEvents, 'ready'>({ ready: 1 }, ['ready']) // false
+* ```
 */
 function isRecorderMapComplete(value, events) {
-	try {
-		if (typeof value !== "object" || value === null) return false;
+	return holds(() => {
+		if (!isObject(value)) return false;
 		return events.every((event) => {
 			if (!Object.hasOwn(value, event)) return false;
 			const recorder = Reflect.get(value, event);
-			if (typeof recorder !== "object" || recorder === null) return false;
-			return typeof Reflect.get(recorder, "handler") === "function" && Array.isArray(Reflect.get(recorder, "calls"));
+			if (!isObject(recorder)) return false;
+			return isFunction(Reflect.get(recorder, "handler")) && isArray(Reflect.get(recorder, "calls"));
 		});
-	} catch {
-		return false;
-	}
+	});
 }
 //#endregion
 //#region src/core/helpers.ts
@@ -91,10 +102,20 @@ function isRecorderMapComplete(value, events) {
 * `<subject> interval must be finite and non-negative`.
 * @remarks Every member of the wait family resolves its own defaults first and passes the resolved
 * numbers here, so each keeps its own defaults while one contract states what a bound must be.
+*
+* @example
+* ```ts
+* import { checkBounds } from '@orkestrel/test'
+*
+* checkBounds('Wait', 1000, 10) // undefined
+*
+* // Throws Error: Retry budget must be finite and non-negative
+* checkBounds('Retry', -1, 10)
+* ```
 */
 function checkBounds(subject, budget, interval) {
-	if (!Number.isFinite(budget) || budget < 0) throw new Error(`${subject} budget must be finite and non-negative`);
-	if (!Number.isFinite(interval) || interval < 0) throw new Error(`${subject} interval must be finite and non-negative`);
+	if (!isFiniteNumber(budget) || budget < 0) throw new Error(`${subject} budget must be finite and non-negative`);
+	if (!isFiniteNumber(interval) || interval < 0) throw new Error(`${subject} interval must be finite and non-negative`);
 }
 /**
 * Builds the error {@link retryUntil} raises when its elapsed-time budget runs out.
@@ -107,6 +128,16 @@ function checkBounds(subject, budget, interval) {
 * @returns The exhaustion error, unthrown.
 * @remarks Both of `retryUntil`'s elapsed checks raise this one message, so an edit to it lands in
 * one place. The rendered value is appended only when the retry produced one.
+*
+* @example
+* ```ts
+* import { buildRetryExhausted } from '@orkestrel/test'
+*
+* const exhausted = buildRetryExhausted('registry answers', 30, 31, '"starting"', undefined)
+*
+* exhausted.message
+* // 'Retry "registry answers" did not succeed within 30ms (waited 31ms) (last value: "starting")'
+* ```
 */
 function buildRetryExhausted(description, budget, elapsed, last, cause) {
 	return new Error(`Retry "${description}" did not succeed within ${budget}ms (waited ${elapsed}ms)${last === void 0 ? "" : ` (last value: ${last})`}`, { cause });
@@ -120,6 +151,21 @@ function buildRetryExhausted(description, budget, elapsed, last, cause) {
 * @remarks The dropped registration's cleanup controller is aborted as it leaves, so the scope
 * subscription installed beside it leaves with it. Removing the installed listener from the signal
 * stays with the caller, because only the scope-abort path has one to remove.
+*
+* @example
+* ```ts
+* import type { SignalRegistration } from '@orkestrel/test'
+* import { dropRegistration } from '@orkestrel/test'
+*
+* const listener: EventListener = () => undefined
+* const installed: EventListenerObject = { handleEvent: () => undefined }
+* const cleanup = new AbortController()
+* const registrations: SignalRegistration[] = [[listener, installed, true, cleanup]]
+*
+* dropRegistration(registrations, installed)?.[1] === installed // true
+* cleanup.signal.aborted // true
+* dropRegistration(registrations, installed) // undefined
+* ```
 */
 function dropRegistration(registrations, installed) {
 	const index = registrations.findIndex((registration) => registration[1] === installed);
@@ -197,7 +243,7 @@ async function retryUntil(description, produce, satisfied, options) {
 	const interval = options?.interval ?? 10;
 	const attempts = options?.attempts;
 	checkBounds("Retry", budget, interval);
-	if (attempts !== void 0 && (!Number.isInteger(attempts) || attempts < 1)) throw new Error("Retry attempts must be a positive integer");
+	if (isDefined(attempts) && (!isInteger(attempts) || attempts < 1)) throw new Error("Retry attempts must be a positive integer");
 	const start = performance.now();
 	let count = 0;
 	let cause;
@@ -338,6 +384,18 @@ async function waitForEvent(subscribe, description, options) {
 * @returns The decoded values in physical-line order.
 * @throws An `Error` naming the malformed physical line, with the native `SyntaxError` as its
 * `cause`.
+* @remarks An empty line contributes no value, and a trailing carriage return is dropped before the
+* line is parsed, so text written with either line ending decodes the same.
+*
+* @example
+* ```ts
+* import { decodeJSONLines } from '@orkestrel/test'
+*
+* decodeJSONLines('{"ready":true}\n7\n') // [{ ready: true }, 7]
+*
+* // Throws Error: Invalid JSON on line 3
+* decodeJSONLines('{}\n\n{')
+* ```
 */
 function decodeJSONLines(text) {
 	const values = [];
@@ -360,22 +418,20 @@ function decodeJSONLines(text) {
 * @returns The thrown value, or `undefined` when the thunk completes.
 */
 function captureError(thunk) {
-	try {
-		thunk();
-	} catch (error) {
-		return error;
-	}
+	const outcome = attempt(thunk);
+	return outcome.success ? void 0 : outcome.error;
 }
 /**
-* Requires a value to be present.
+* Narrows a value away from `null` and `undefined`, throwing when it is absent.
 *
 * @typeParam T - The required value type.
 * @param value - The value to check.
 * @param message - The error message used when the value is absent. Default: `'Value is required'`.
 * @returns The present value.
+* @throws An `Error` carrying `message` when the value is `null` or `undefined`.
 */
 function requireValue(value, message = "Value is required") {
-	if (value === null || value === void 0) throw new Error(message);
+	if (!isDefined(value)) throw new Error(message);
 	return value;
 }
 /**
@@ -422,17 +478,17 @@ async function collectStream(stream) {
 */
 function roundTripJSON(value) {
 	const serialized = JSON.stringify(value, (_key, current) => {
-		if (current === void 0 || typeof current === "function" || typeof current === "symbol") throw new Error("JSON values must not contain undefined, functions, or symbols");
-		if (typeof current === "number" && !Number.isFinite(current)) throw new Error("JSON values must contain finite numbers");
+		if (current === void 0 || isFunction(current) || isSymbol(current)) throw new Error("JSON values must not contain undefined, functions, or symbols");
+		if (isNumber(current) && !isFiniteNumber(current)) throw new Error("JSON values must contain finite numbers");
 		return current;
 	});
 	const parsed = JSON.parse(serialized);
 	const pending = [parsed];
 	while (pending.length > 0) {
 		const current = pending.pop();
-		if (typeof current === "number" && !Number.isFinite(current)) throw new Error("JSON values must contain finite numbers");
-		if (Array.isArray(current)) for (const child of current) pending.push(child);
-		else if (typeof current === "object" && current !== null) for (const child of Object.values(current)) pending.push(child);
+		if (isNumber(current) && !isFiniteNumber(current)) throw new Error("JSON values must contain finite numbers");
+		if (isArray(current)) for (const child of current) pending.push(child);
+		else if (isObject(current)) for (const child of Object.values(current)) pending.push(child);
 	}
 	return parsed;
 }
@@ -478,7 +534,7 @@ async function executeScenario(scenario, context) {
 		await scenario.act(context, transition.event);
 		await scenario.assert(context, transition.to);
 	} catch (cause) {
-		const message = cause instanceof Error ? cause.message : `threw a non-error ${typeof cause} value`;
+		const message = isError(cause) ? cause.message : `threw a non-error ${typeof cause} value`;
 		throw new Error(`${transition.name}: ${message}`, { cause });
 	}
 }