@orkestrel/test 0.0.1 → 0.0.3

package/README.md

@@ -1,9 +1,11 @@
 # @orkestrel/test
 
-The test helpers every `@orkestrel` package had already written for itself, published once. A call
-recorder that is a real callback rather than a spy. A real host delay. A throw-to-value converter and
-a presence narrower, so `!` and `as` stay banned in tests. Two async collectors and a JSON copier. A
-scratch directory the test owns and destroys, and a symlink-refusing source-file walker. Add it as a
+The test helpers the `@orkestrel` fleet kept rewriting, published once. A call recorder that is a
+real callback rather than a spy. A real host delay. A throw-to-value converter and a presence
+narrower, so `!` and `as` stay banned in tests. Two async collectors and a JSON copier. A scratch
+directory the test owns and destroys, and a symlink-refusing source-file walker. A helper ships here
+only when enough packages had already written their own; the guide's
+[Limits](guides/test.md#limits) section states that rule and what it excluded. Add it as a
 devDependency; nothing here runs in production code. Part of the `@orkestrel` line.
 
 It has **zero runtime dependencies**, and no exported signature names an `@orkestrel/*` type. Both
@@ -48,16 +50,20 @@ recorder.clear() // truncates in place, so a `calls` reference captured earlier
 captureError(() => loader.read('missing.txt')) // the thrown value, or undefined
 requireValue(scratch.read('input.txt')) // 'hello' — narrows `string | undefined` without `!`
 
+scratch.remove('input.txt') // one contained entry, subtree and all; a missing target is a no-op
 scratch.destroy() // idempotent, and it removes only the directory it allocated
 ```
 
 The rest of core is `collect` (drains an async iterable), `collectStream` (drains a
-`ReadableStream`), `roundTripJSON` (copies a `JSONValue`, and throws rather than turning a non-finite
-number into `null`), and `resolveRoot` (the directory above the calling module, from `import.meta`).
+`ReadableStream`), `roundTripJSON` (copies any value `JSONSafe` accepts, including an
+interface-typed one, and throws rather than turning a non-finite number into `null`), and
+`resolveRoot` (the directory above the calling module, from `import.meta`).
 
 The server face adds `readInventory`, which reads a checkout into a map of root-relative path to
-file text that a parity suite can assert against, plus `resolveContained`, the lexical check it
-refuses escapes with.
+file text that a parity suite can assert against, plus the three pure leaves behind it and
+`createScratch`: `resolveContained`, the lexical check both refuse escapes with; `isExcluded`, the
+exclusion rule the walk applies; and `matchesIdentity`, the comparison `destroy()` makes before it
+removes anything.
 
 ```ts
 import { resolveRoot } from '@orkestrel/test'
@@ -66,7 +72,7 @@ import { readInventory } from '@orkestrel/test/server'
 // A suite in tests/ is one directory below the workspace root, which is what `resolveRoot` returns.
 const root = resolveRoot(import.meta)
 
-// Nothing is walked by default, so the directories are a required argument rather than an option.
+// Nothing is walked by default, so the targets are a required argument rather than an option.
 const sources = readInventory(root, ['src/core', 'src/server'], { extensions: ['.ts'] })
 
 Object.keys(sources)
@@ -77,7 +83,12 @@ Object.keys(sources)
 sources['src/core/index.ts']
 // "export * from './types.js'\nexport * from './helpers.js'\nexport * from './factories.js'\n"
 
-// An `exclude` entry is a whole key. A file key drops that file.
+// A target is a file or a directory. A named file is read whatever the extension filter says.
+Object.keys(readInventory(root, ['package.json', 'src/core'], { extensions: ['.ts'] }))
+// ['package.json', 'src/core/factories.ts', 'src/core/helpers.ts', 'src/core/index.ts',
+//  'src/core/types.ts']
+
+// An `exclude` entry matches whole key segments. A file key drops that file.
 Object.keys(
 	readInventory(root, ['src/core'], { extensions: ['.ts'], exclude: ['src/core/index.ts'] }),
 )
@@ -94,17 +105,24 @@ conversion. Keys are inserted in sorted order, and a plain object reads that ord
 key that is not integer-like.
 
 Two boundaries are worth stating up front, because the two filesystem helpers promise different
-things. `createScratch` allocates its own directory at POSIX mode `0700` and refuses a path that
-lexically escapes it. The suite asserts those bits on POSIX and proves nothing about a host that
-emulates them. The mode keeps another uid out, and neither a sibling test worker nor the code under
-test is another uid. It does not walk segments for symbolic links. A link inside its own allocation
-was created by the test process or by the code the test drives — handing that code `scratch.path`
-is the ordinary use of this helper — and `write` and `read` follow such a link, so either can reach
-outside the allocation through it. `readInventory` walks a directory you supply, usually a checkout
-the test did not create, so it throws on a symlinked root or requested directory and skips a
-symlink met while walking. Neither is a sandbox against hostile filesystem content:
-those refusals stop accidental escape, not an adversary who can create hard links where the test
-process already writes.
+things. `createScratch` allocates its own directory at POSIX mode `0700` — under the host temporary
+directory, or under a `parent` you name — and refuses a path that lexically escapes it. The suite
+asserts those bits on POSIX and proves nothing about a host that emulates them. The mode keeps
+another uid out, and neither a sibling test worker nor the code under test is another uid. It does
+not walk segments for symbolic links. A link inside its own allocation was created by the test
+process, by the code the test drives, or by this package's own `link` — handing that code
+`scratch.path` is the ordinary use of this helper — and a contained path reaches outside the
+allocation through one. The guide's [traversal](guides/test.md#traversal) section states what each
+member does with a link it meets. Naming a `parent` inside a package tree costs one more thing:
+while the allocation exists, everything that walks that tree sees it. `destroy()` is unaffected by
+where the allocation sits, because it matches the allocation's identity rather than its path. One
+field of that identity is the host's to supply: where a host reports no real creation time, libuv
+reports `ctime` in its place, the first write moves it, and `destroy()` then removes nothing and
+returns as if it had. `readInventory` walks a checkout you supply, usually one the test did not
+create, so it throws on a symlinked root or named target, throws on a named target whose real path
+leaves the root through a link in the middle, and skips a symlink met while walking. Neither is a
+sandbox against hostile filesystem content: those refusals stop accidental escape, not an adversary
+who can create hard links where the test process already writes.
 
 ## Guide
 

package/dist/src/core/index.cjs

@@ -69,14 +69,16 @@ async function collectStream(stream) {
 /**
 * Copies a JSON value through serialization and parsing.
 *
-* @typeParam T - The JSON value type.
-* @param value - The value to copy.
+* @typeParam T - The copied value's type, which the copy keeps.
+* @param value - The value to copy, bounded by its own `JSONSafe` projection.
 * @returns The parsed JSON copy.
 * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is
-* normalized to zero by JSON serialization.
+* normalized to zero by JSON serialization. The bound intersects `JSONSafe<T>` rather than
+* constraining `T` to `JSONValue`, so an interface-typed value round-trips.
 */
 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");
 		return current;
 	});
@@ -84,7 +86,6 @@ function roundTripJSON(value) {
 	const pending = [parsed];
 	while (pending.length > 0) {
 		const current = pending.pop();
-		if (current === void 0) continue;
 		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);

package/dist/src/core/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/core/helpers.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { JSONValue } from './types.js'\n\n/**\n * Waits for a host timer to elapse.\n *\n * @param ms - The delay in milliseconds.\n * @returns A promise that resolves after the timer fires.\n */\nexport function waitForDelay(ms = 0): Promise<void> {\n\treturn new Promise((resolve) => setTimeout(resolve, ms))\n}\n\n/**\n * Captures the value thrown by a thunk.\n *\n * @param thunk - The work whose thrown value to capture.\n * @returns The thrown value, or `undefined` when the thunk completes.\n */\nexport function captureError(thunk: () => unknown): unknown {\n\ttry {\n\t\tthunk()\n\t} catch (error) {\n\t\treturn error\n\t}\n\treturn undefined\n}\n\n/**\n * Requires a value to be present.\n *\n * @typeParam T - The required value type.\n * @param value - The value to check.\n * @param message - The error message used when the value is absent.\n * @returns The present value.\n */\nexport function requireValue<T>(value: T | null | undefined, message = 'Value is required'): T {\n\tif (value === null || value === undefined) throw new Error(message)\n\treturn value\n}\n\n/**\n * Collects every value from an async iterable.\n *\n * @typeParam T - The yielded value type.\n * @param source - The async iterable to drain.\n * @returns The yielded values in iteration order.\n */\nexport async function collect<T>(source: AsyncIterable<T>): Promise<readonly T[]> {\n\tconst values: T[] = []\n\tfor await (const value of source) values.push(value)\n\treturn values\n}\n\n/**\n * Collects every value from a readable stream.\n *\n * @typeParam T - The streamed value type.\n * @param stream - The readable stream to drain.\n * @returns The streamed values in read order.\n */\nexport async function collectStream<T>(stream: ReadableStream<T>): Promise<readonly T[]> {\n\tconst reader = stream.getReader()\n\tconst values: T[] = []\n\ttry {\n\t\twhile (true) {\n\t\t\tconst result = await reader.read()\n\t\t\tif (result.done) return values\n\t\t\tvalues.push(result.value)\n\t\t}\n\t} finally {\n\t\treader.releaseLock()\n\t}\n}\n\n/**\n * Copies a JSON value through serialization and parsing.\n *\n * @typeParam T - The JSON value type.\n * @param value - The value to copy.\n * @returns The parsed JSON copy.\n * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is\n * normalized to zero by JSON serialization.\n */\nexport function roundTripJSON<T extends JSONValue>(value: T): T {\n\tconst serialized = JSON.stringify(value, (_key, current) => {\n\t\tif (typeof current === 'number' && !Number.isFinite(current)) {\n\t\t\tthrow new Error('JSON values must contain finite numbers')\n\t\t}\n\t\treturn current\n\t})\n\tconst parsed: T = JSON.parse(serialized)\n\tconst pending: JSONValue[] = [parsed]\n\twhile (pending.length > 0) {\n\t\tconst current = pending.pop()\n\t\tif (current === undefined) continue\n\t\tif (typeof current === 'number' && !Number.isFinite(current)) {\n\t\t\tthrow new Error('JSON values must contain finite numbers')\n\t\t}\n\t\tif (Array.isArray(current)) {\n\t\t\tfor (const child of current) pending.push(child)\n\t\t} else if (typeof current === 'object' && current !== null) {\n\t\t\tfor (const child of Object.values(current)) pending.push(child)\n\t\t}\n\t}\n\treturn parsed\n}\n\n/**\n * Resolves the parent directory of a calling module, which is the workspace root when called from\n * the conventional `tests/setup.ts` location.\n *\n * @param meta - The calling module metadata.\n * @returns The root URL one directory above the calling file.\n */\nexport function resolveRoot(meta: ImportMeta): URL {\n\treturn new URL('../', meta.url)\n}\n","import type { RecorderInterface } from './types.js'\n\n/**\n * Creates a recorder for callback arguments.\n *\n * @typeParam TArgs - The argument tuple to record.\n * @returns A recorder whose handler appends calls in order.\n */\nexport function createRecorder<TArgs extends readonly unknown[]>(): RecorderInterface<TArgs> {\n\tconst calls: TArgs[] = []\n\treturn {\n\t\tcalls,\n\t\tget count() {\n\t\t\treturn calls.length\n\t\t},\n\t\thandler(...args) {\n\t\t\tcalls.push(args)\n\t\t},\n\t\tclear() {\n\t\t\tcalls.length = 0\n\t\t},\n\t}\n}\n"],"mappings":";;;;;;;;AAQA,SAAgB,aAAa,KAAK,GAAkB;CACnD,OAAO,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;AACxD;;;;;;;AAQA,SAAgB,aAAa,OAA+B;CAC3D,IAAI;EACH,MAAM;CACP,SAAS,OAAO;EACf,OAAO;CACR;AAED;;;;;;;;;AAUA,SAAgB,aAAgB,OAA6B,UAAU,qBAAwB;CAC9F,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW,MAAM,IAAI,MAAM,OAAO;CAClE,OAAO;AACR;;;;;;;;AASA,eAAsB,QAAW,QAAiD;CACjF,MAAM,SAAc,CAAC;CACrB,WAAW,MAAM,SAAS,QAAQ,OAAO,KAAK,KAAK;CACnD,OAAO;AACR;;;;;;;;AASA,eAAsB,cAAiB,QAAkD;CACxF,MAAM,SAAS,OAAO,UAAU;CAChC,MAAM,SAAc,CAAC;CACrB,IAAI;EACH,OAAO,MAAM;GACZ,MAAM,SAAS,MAAM,OAAO,KAAK;GACjC,IAAI,OAAO,MAAM,OAAO;GACxB,OAAO,KAAK,OAAO,KAAK;EACzB;CACD,UAAU;EACT,OAAO,YAAY;CACpB;AACD;;;;;;;;;;AAWA,SAAgB,cAAmC,OAAa;CAC/D,MAAM,aAAa,KAAK,UAAU,QAAQ,MAAM,YAAY;EAC3D,IAAI,OAAO,YAAY,YAAY,CAAC,OAAO,SAAS,OAAO,GAC1D,MAAM,IAAI,MAAM,yCAAyC;EAE1D,OAAO;CACR,CAAC;CACD,MAAM,SAAY,KAAK,MAAM,UAAU;CACvC,MAAM,UAAuB,CAAC,MAAM;CACpC,OAAO,QAAQ,SAAS,GAAG;EAC1B,MAAM,UAAU,QAAQ,IAAI;EAC5B,IAAI,YAAY,KAAA,GAAW;EAC3B,IAAI,OAAO,YAAY,YAAY,CAAC,OAAO,SAAS,OAAO,GAC1D,MAAM,IAAI,MAAM,yCAAyC;EAE1D,IAAI,MAAM,QAAQ,OAAO,GACxB,KAAK,MAAM,SAAS,SAAS,QAAQ,KAAK,KAAK;OACzC,IAAI,OAAO,YAAY,YAAY,YAAY,MACrD,KAAK,MAAM,SAAS,OAAO,OAAO,OAAO,GAAG,QAAQ,KAAK,KAAK;CAEhE;CACA,OAAO;AACR;;;;;;;;AASA,SAAgB,YAAY,MAAuB;CAClD,OAAO,IAAI,IAAI,OAAO,KAAK,GAAG;AAC/B;;;;;;;;;AC5GA,SAAgB,iBAA6E;CAC5F,MAAM,QAAiB,CAAC;CACxB,OAAO;EACN;EACA,IAAI,QAAQ;GACX,OAAO,MAAM;EACd;EACA,QAAQ,GAAG,MAAM;GAChB,MAAM,KAAK,IAAI;EAChB;EACA,QAAQ;GACP,MAAM,SAAS;EAChB;CACD;AACD"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/core/helpers.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { JSONSafe } from './types.js'\n\n/**\n * Waits for a host timer to elapse.\n *\n * @param ms - The delay in milliseconds.\n * @returns A promise that resolves after the timer fires.\n */\nexport function waitForDelay(ms = 0): Promise<void> {\n\treturn new Promise((resolve) => setTimeout(resolve, ms))\n}\n\n/**\n * Captures the value thrown by a thunk.\n *\n * @param thunk - The work whose thrown value to capture.\n * @returns The thrown value, or `undefined` when the thunk completes.\n */\nexport function captureError(thunk: () => unknown): unknown {\n\ttry {\n\t\tthunk()\n\t} catch (error) {\n\t\treturn error\n\t}\n\treturn undefined\n}\n\n/**\n * Requires a value to be present.\n *\n * @typeParam T - The required value type.\n * @param value - The value to check.\n * @param message - The error message used when the value is absent.\n * @returns The present value.\n */\nexport function requireValue<T>(value: T | null | undefined, message = 'Value is required'): T {\n\tif (value === null || value === undefined) throw new Error(message)\n\treturn value\n}\n\n/**\n * Collects every value from an async iterable.\n *\n * @typeParam T - The yielded value type.\n * @param source - The async iterable to drain.\n * @returns The yielded values in iteration order.\n */\nexport async function collect<T>(source: AsyncIterable<T>): Promise<readonly T[]> {\n\tconst values: T[] = []\n\tfor await (const value of source) values.push(value)\n\treturn values\n}\n\n/**\n * Collects every value from a readable stream.\n *\n * @typeParam T - The streamed value type.\n * @param stream - The readable stream to drain.\n * @returns The streamed values in read order.\n */\nexport async function collectStream<T>(stream: ReadableStream<T>): Promise<readonly T[]> {\n\tconst reader = stream.getReader()\n\tconst values: T[] = []\n\ttry {\n\t\twhile (true) {\n\t\t\tconst result = await reader.read()\n\t\t\tif (result.done) return values\n\t\t\tvalues.push(result.value)\n\t\t}\n\t} finally {\n\t\treader.releaseLock()\n\t}\n}\n\n/**\n * Copies a JSON value through serialization and parsing.\n *\n * @typeParam T - The copied value's type, which the copy keeps.\n * @param value - The value to copy, bounded by its own `JSONSafe` projection.\n * @returns The parsed JSON copy.\n * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is\n * normalized to zero by JSON serialization. The bound intersects `JSONSafe<T>` rather than\n * constraining `T` to `JSONValue`, so an interface-typed value round-trips.\n */\nexport function roundTripJSON<T>(value: T & JSONSafe<T>): T {\n\tconst serialized = JSON.stringify(value, (_key, current) => {\n\t\tif (current === undefined || typeof current === 'function' || typeof current === 'symbol') {\n\t\t\tthrow new Error('JSON values must not contain undefined, functions, or symbols')\n\t\t}\n\t\tif (typeof current === 'number' && !Number.isFinite(current)) {\n\t\t\tthrow new Error('JSON values must contain finite numbers')\n\t\t}\n\t\treturn current\n\t})\n\tconst parsed: T = JSON.parse(serialized)\n\tconst pending: unknown[] = [parsed]\n\twhile (pending.length > 0) {\n\t\tconst current = pending.pop()\n\t\tif (typeof current === 'number' && !Number.isFinite(current)) {\n\t\t\tthrow new Error('JSON values must contain finite numbers')\n\t\t}\n\t\tif (Array.isArray(current)) {\n\t\t\tfor (const child of current) pending.push(child)\n\t\t} else if (typeof current === 'object' && current !== null) {\n\t\t\tfor (const child of Object.values(current)) pending.push(child)\n\t\t}\n\t}\n\treturn parsed\n}\n\n/**\n * Resolves the parent directory of a calling module, which is the workspace root when called from\n * the conventional `tests/setup.ts` location.\n *\n * @param meta - The calling module metadata.\n * @returns The root URL one directory above the calling file.\n */\nexport function resolveRoot(meta: ImportMeta): URL {\n\treturn new URL('../', meta.url)\n}\n","import type { RecorderInterface } from './types.js'\n\n/**\n * Creates a recorder for callback arguments.\n *\n * @typeParam TArgs - The argument tuple to record.\n * @returns A recorder whose handler appends calls in order.\n */\nexport function createRecorder<TArgs extends readonly unknown[]>(): RecorderInterface<TArgs> {\n\tconst calls: TArgs[] = []\n\treturn {\n\t\tcalls,\n\t\tget count() {\n\t\t\treturn calls.length\n\t\t},\n\t\thandler(...args) {\n\t\t\tcalls.push(args)\n\t\t},\n\t\tclear() {\n\t\t\tcalls.length = 0\n\t\t},\n\t}\n}\n"],"mappings":";;;;;;;;AAQA,SAAgB,aAAa,KAAK,GAAkB;CACnD,OAAO,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;AACxD;;;;;;;AAQA,SAAgB,aAAa,OAA+B;CAC3D,IAAI;EACH,MAAM;CACP,SAAS,OAAO;EACf,OAAO;CACR;AAED;;;;;;;;;AAUA,SAAgB,aAAgB,OAA6B,UAAU,qBAAwB;CAC9F,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW,MAAM,IAAI,MAAM,OAAO;CAClE,OAAO;AACR;;;;;;;;AASA,eAAsB,QAAW,QAAiD;CACjF,MAAM,SAAc,CAAC;CACrB,WAAW,MAAM,SAAS,QAAQ,OAAO,KAAK,KAAK;CACnD,OAAO;AACR;;;;;;;;AASA,eAAsB,cAAiB,QAAkD;CACxF,MAAM,SAAS,OAAO,UAAU;CAChC,MAAM,SAAc,CAAC;CACrB,IAAI;EACH,OAAO,MAAM;GACZ,MAAM,SAAS,MAAM,OAAO,KAAK;GACjC,IAAI,OAAO,MAAM,OAAO;GACxB,OAAO,KAAK,OAAO,KAAK;EACzB;CACD,UAAU;EACT,OAAO,YAAY;CACpB;AACD;;;;;;;;;;;AAYA,SAAgB,cAAiB,OAA2B;CAC3D,MAAM,aAAa,KAAK,UAAU,QAAQ,MAAM,YAAY;EAC3D,IAAI,YAAY,KAAA,KAAa,OAAO,YAAY,cAAc,OAAO,YAAY,UAChF,MAAM,IAAI,MAAM,+DAA+D;EAEhF,IAAI,OAAO,YAAY,YAAY,CAAC,OAAO,SAAS,OAAO,GAC1D,MAAM,IAAI,MAAM,yCAAyC;EAE1D,OAAO;CACR,CAAC;CACD,MAAM,SAAY,KAAK,MAAM,UAAU;CACvC,MAAM,UAAqB,CAAC,MAAM;CAClC,OAAO,QAAQ,SAAS,GAAG;EAC1B,MAAM,UAAU,QAAQ,IAAI;EAC5B,IAAI,OAAO,YAAY,YAAY,CAAC,OAAO,SAAS,OAAO,GAC1D,MAAM,IAAI,MAAM,yCAAyC;EAE1D,IAAI,MAAM,QAAQ,OAAO,GACxB,KAAK,MAAM,SAAS,SAAS,QAAQ,KAAK,KAAK;OACzC,IAAI,OAAO,YAAY,YAAY,YAAY,MACrD,KAAK,MAAM,SAAS,OAAO,OAAO,OAAO,GAAG,QAAQ,KAAK,KAAK;CAEhE;CACA,OAAO;AACR;;;;;;;;AASA,SAAgB,YAAY,MAAuB;CAClD,OAAO,IAAI,IAAI,OAAO,KAAK,GAAG;AAC/B;;;;;;;;;AC/GA,SAAgB,iBAA6E;CAC5F,MAAM,QAAiB,CAAC;CACxB,OAAO;EACN;EACA,IAAI,QAAQ;GACX,OAAO,MAAM;EACd;EACA,QAAQ,GAAG,MAAM;GAChB,MAAM,KAAK,IAAI;EAChB;EACA,QAAQ;GACP,MAAM,SAAS;EAChB;CACD;AACD"}

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

@@ -32,6 +32,39 @@ export declare function collectStream<T>(stream: ReadableStream<T>): Promise<rea
  */
 export declare function createRecorder<TArgs extends readonly unknown[]>(): RecorderInterface<TArgs>;
 
+/**
+ * The JSON-safe projection of a type: every member JSON preserves, mapped to itself, and every
+ * member it does not, mapped to `never`.
+ *
+ * @typeParam T - The type to project.
+ * @remarks Intersect a parameter with this rather than constraining it to `JSONValue`. A `JSONValue`
+ * constraint rejects every `interface`, because TypeScript grants an implicit index signature to a
+ * type alias and never to an interface, and interfaces are what this project's public types are. A
+ * value whose type survives the projection satisfies the intersection unchanged; one that carries a
+ * method, a `Date`, a `Map`, the opaque `object` type, or a symbol-keyed member meets `never` at that
+ * member and is rejected there. A member typed `undefined` is rejected the same way, because
+ * serialization drops it from an object and rewrites it to `null` in an array, so the returned type
+ * would claim a member the copy does not carry. An optional member survives, since its declared type
+ * still narrows to what JSON keeps. A member declared `?: X | undefined` and passed an explicit
+ * `undefined` is refused; declare it `?: X` and omit the member instead. `unknown` passes through
+ * unvetted by the projection. For an `unknown` member, `roundTripJSON` refuses `undefined`,
+ * functions, symbols, and non-finite numbers at runtime; JSON otherwise may silently reshape the
+ * value, such as a `Date` to a string or a `Map` to `{}`.
+ * @example
+ * ```ts
+ * interface Snapshot {
+ * 	readonly id: string
+ * 	readonly turns: number
+ * }
+ *
+ * // { readonly id: string; readonly turns: number } — every member survives.
+ * type Safe = JSONSafe<Snapshot>
+ * ```
+ */
+export declare type JSONSafe<T> = unknown extends T ? T : T extends string | number | boolean | null ? T : T extends ReadonlyArray<infer E> ? ReadonlyArray<JSONSafe<E>> : T extends (...args: never[]) => unknown ? never : T extends object ? object extends T ? never : {
+    readonly [K in keyof T]: K extends symbol ? never : JSONSafe<T[K]>;
+} : never;
+
 /** 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;
@@ -75,13 +108,14 @@ export declare function resolveRoot(meta: ImportMeta): URL;
 /**
  * Copies a JSON value through serialization and parsing.
  *
- * @typeParam T - The JSON value type.
- * @param value - The value to copy.
+ * @typeParam T - The copied value's type, which the copy keeps.
+ * @param value - The value to copy, bounded by its own `JSONSafe` projection.
  * @returns The parsed JSON copy.
  * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is
- * normalized to zero by JSON serialization.
+ * normalized to zero by JSON serialization. The bound intersects `JSONSafe<T>` rather than
+ * constraining `T` to `JSONValue`, so an interface-typed value round-trips.
  */
-export declare function roundTripJSON<T extends JSONValue>(value: T): T;
+export declare function roundTripJSON<T>(value: T & JSONSafe<T>): T;
 
 /**
  * Waits for a host timer to elapse.

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

@@ -32,6 +32,39 @@ export declare function collectStream<T>(stream: ReadableStream<T>): Promise<rea
  */
 export declare function createRecorder<TArgs extends readonly unknown[]>(): RecorderInterface<TArgs>;
 
+/**
+ * The JSON-safe projection of a type: every member JSON preserves, mapped to itself, and every
+ * member it does not, mapped to `never`.
+ *
+ * @typeParam T - The type to project.
+ * @remarks Intersect a parameter with this rather than constraining it to `JSONValue`. A `JSONValue`
+ * constraint rejects every `interface`, because TypeScript grants an implicit index signature to a
+ * type alias and never to an interface, and interfaces are what this project's public types are. A
+ * value whose type survives the projection satisfies the intersection unchanged; one that carries a
+ * method, a `Date`, a `Map`, the opaque `object` type, or a symbol-keyed member meets `never` at that
+ * member and is rejected there. A member typed `undefined` is rejected the same way, because
+ * serialization drops it from an object and rewrites it to `null` in an array, so the returned type
+ * would claim a member the copy does not carry. An optional member survives, since its declared type
+ * still narrows to what JSON keeps. A member declared `?: X | undefined` and passed an explicit
+ * `undefined` is refused; declare it `?: X` and omit the member instead. `unknown` passes through
+ * unvetted by the projection. For an `unknown` member, `roundTripJSON` refuses `undefined`,
+ * functions, symbols, and non-finite numbers at runtime; JSON otherwise may silently reshape the
+ * value, such as a `Date` to a string or a `Map` to `{}`.
+ * @example
+ * ```ts
+ * interface Snapshot {
+ * 	readonly id: string
+ * 	readonly turns: number
+ * }
+ *
+ * // { readonly id: string; readonly turns: number } — every member survives.
+ * type Safe = JSONSafe<Snapshot>
+ * ```
+ */
+export declare type JSONSafe<T> = unknown extends T ? T : T extends string | number | boolean | null ? T : T extends ReadonlyArray<infer E> ? ReadonlyArray<JSONSafe<E>> : T extends (...args: never[]) => unknown ? never : T extends object ? object extends T ? never : {
+    readonly [K in keyof T]: K extends symbol ? never : JSONSafe<T[K]>;
+} : never;
+
 /** 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;
@@ -75,13 +108,14 @@ export declare function resolveRoot(meta: ImportMeta): URL;
 /**
  * Copies a JSON value through serialization and parsing.
  *
- * @typeParam T - The JSON value type.
- * @param value - The value to copy.
+ * @typeParam T - The copied value's type, which the copy keeps.
+ * @param value - The value to copy, bounded by its own `JSONSafe` projection.
  * @returns The parsed JSON copy.
  * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is
- * normalized to zero by JSON serialization.
+ * normalized to zero by JSON serialization. The bound intersects `JSONSafe<T>` rather than
+ * constraining `T` to `JSONValue`, so an interface-typed value round-trips.
  */
-export declare function roundTripJSON<T extends JSONValue>(value: T): T;
+export declare function roundTripJSON<T>(value: T & JSONSafe<T>): T;
 
 /**
  * Waits for a host timer to elapse.

package/dist/src/core/index.js

@@ -68,14 +68,16 @@ async function collectStream(stream) {
 /**
 * Copies a JSON value through serialization and parsing.
 *
-* @typeParam T - The JSON value type.
-* @param value - The value to copy.
+* @typeParam T - The copied value's type, which the copy keeps.
+* @param value - The value to copy, bounded by its own `JSONSafe` projection.
 * @returns The parsed JSON copy.
 * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is
-* normalized to zero by JSON serialization.
+* normalized to zero by JSON serialization. The bound intersects `JSONSafe<T>` rather than
+* constraining `T` to `JSONValue`, so an interface-typed value round-trips.
 */
 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");
 		return current;
 	});
@@ -83,7 +85,6 @@ function roundTripJSON(value) {
 	const pending = [parsed];
 	while (pending.length > 0) {
 		const current = pending.pop();
-		if (current === void 0) continue;
 		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);

package/dist/src/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/helpers.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { JSONValue } from './types.js'\n\n/**\n * Waits for a host timer to elapse.\n *\n * @param ms - The delay in milliseconds.\n * @returns A promise that resolves after the timer fires.\n */\nexport function waitForDelay(ms = 0): Promise<void> {\n\treturn new Promise((resolve) => setTimeout(resolve, ms))\n}\n\n/**\n * Captures the value thrown by a thunk.\n *\n * @param thunk - The work whose thrown value to capture.\n * @returns The thrown value, or `undefined` when the thunk completes.\n */\nexport function captureError(thunk: () => unknown): unknown {\n\ttry {\n\t\tthunk()\n\t} catch (error) {\n\t\treturn error\n\t}\n\treturn undefined\n}\n\n/**\n * Requires a value to be present.\n *\n * @typeParam T - The required value type.\n * @param value - The value to check.\n * @param message - The error message used when the value is absent.\n * @returns The present value.\n */\nexport function requireValue<T>(value: T | null | undefined, message = 'Value is required'): T {\n\tif (value === null || value === undefined) throw new Error(message)\n\treturn value\n}\n\n/**\n * Collects every value from an async iterable.\n *\n * @typeParam T - The yielded value type.\n * @param source - The async iterable to drain.\n * @returns The yielded values in iteration order.\n */\nexport async function collect<T>(source: AsyncIterable<T>): Promise<readonly T[]> {\n\tconst values: T[] = []\n\tfor await (const value of source) values.push(value)\n\treturn values\n}\n\n/**\n * Collects every value from a readable stream.\n *\n * @typeParam T - The streamed value type.\n * @param stream - The readable stream to drain.\n * @returns The streamed values in read order.\n */\nexport async function collectStream<T>(stream: ReadableStream<T>): Promise<readonly T[]> {\n\tconst reader = stream.getReader()\n\tconst values: T[] = []\n\ttry {\n\t\twhile (true) {\n\t\t\tconst result = await reader.read()\n\t\t\tif (result.done) return values\n\t\t\tvalues.push(result.value)\n\t\t}\n\t} finally {\n\t\treader.releaseLock()\n\t}\n}\n\n/**\n * Copies a JSON value through serialization and parsing.\n *\n * @typeParam T - The JSON value type.\n * @param value - The value to copy.\n * @returns The parsed JSON copy.\n * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is\n * normalized to zero by JSON serialization.\n */\nexport function roundTripJSON<T extends JSONValue>(value: T): T {\n\tconst serialized = JSON.stringify(value, (_key, current) => {\n\t\tif (typeof current === 'number' && !Number.isFinite(current)) {\n\t\t\tthrow new Error('JSON values must contain finite numbers')\n\t\t}\n\t\treturn current\n\t})\n\tconst parsed: T = JSON.parse(serialized)\n\tconst pending: JSONValue[] = [parsed]\n\twhile (pending.length > 0) {\n\t\tconst current = pending.pop()\n\t\tif (current === undefined) continue\n\t\tif (typeof current === 'number' && !Number.isFinite(current)) {\n\t\t\tthrow new Error('JSON values must contain finite numbers')\n\t\t}\n\t\tif (Array.isArray(current)) {\n\t\t\tfor (const child of current) pending.push(child)\n\t\t} else if (typeof current === 'object' && current !== null) {\n\t\t\tfor (const child of Object.values(current)) pending.push(child)\n\t\t}\n\t}\n\treturn parsed\n}\n\n/**\n * Resolves the parent directory of a calling module, which is the workspace root when called from\n * the conventional `tests/setup.ts` location.\n *\n * @param meta - The calling module metadata.\n * @returns The root URL one directory above the calling file.\n */\nexport function resolveRoot(meta: ImportMeta): URL {\n\treturn new URL('../', meta.url)\n}\n","import type { RecorderInterface } from './types.js'\n\n/**\n * Creates a recorder for callback arguments.\n *\n * @typeParam TArgs - The argument tuple to record.\n * @returns A recorder whose handler appends calls in order.\n */\nexport function createRecorder<TArgs extends readonly unknown[]>(): RecorderInterface<TArgs> {\n\tconst calls: TArgs[] = []\n\treturn {\n\t\tcalls,\n\t\tget count() {\n\t\t\treturn calls.length\n\t\t},\n\t\thandler(...args) {\n\t\t\tcalls.push(args)\n\t\t},\n\t\tclear() {\n\t\t\tcalls.length = 0\n\t\t},\n\t}\n}\n"],"mappings":";;;;;;;AAQA,SAAgB,aAAa,KAAK,GAAkB;CACnD,OAAO,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;AACxD;;;;;;;AAQA,SAAgB,aAAa,OAA+B;CAC3D,IAAI;EACH,MAAM;CACP,SAAS,OAAO;EACf,OAAO;CACR;AAED;;;;;;;;;AAUA,SAAgB,aAAgB,OAA6B,UAAU,qBAAwB;CAC9F,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW,MAAM,IAAI,MAAM,OAAO;CAClE,OAAO;AACR;;;;;;;;AASA,eAAsB,QAAW,QAAiD;CACjF,MAAM,SAAc,CAAC;CACrB,WAAW,MAAM,SAAS,QAAQ,OAAO,KAAK,KAAK;CACnD,OAAO;AACR;;;;;;;;AASA,eAAsB,cAAiB,QAAkD;CACxF,MAAM,SAAS,OAAO,UAAU;CAChC,MAAM,SAAc,CAAC;CACrB,IAAI;EACH,OAAO,MAAM;GACZ,MAAM,SAAS,MAAM,OAAO,KAAK;GACjC,IAAI,OAAO,MAAM,OAAO;GACxB,OAAO,KAAK,OAAO,KAAK;EACzB;CACD,UAAU;EACT,OAAO,YAAY;CACpB;AACD;;;;;;;;;;AAWA,SAAgB,cAAmC,OAAa;CAC/D,MAAM,aAAa,KAAK,UAAU,QAAQ,MAAM,YAAY;EAC3D,IAAI,OAAO,YAAY,YAAY,CAAC,OAAO,SAAS,OAAO,GAC1D,MAAM,IAAI,MAAM,yCAAyC;EAE1D,OAAO;CACR,CAAC;CACD,MAAM,SAAY,KAAK,MAAM,UAAU;CACvC,MAAM,UAAuB,CAAC,MAAM;CACpC,OAAO,QAAQ,SAAS,GAAG;EAC1B,MAAM,UAAU,QAAQ,IAAI;EAC5B,IAAI,YAAY,KAAA,GAAW;EAC3B,IAAI,OAAO,YAAY,YAAY,CAAC,OAAO,SAAS,OAAO,GAC1D,MAAM,IAAI,MAAM,yCAAyC;EAE1D,IAAI,MAAM,QAAQ,OAAO,GACxB,KAAK,MAAM,SAAS,SAAS,QAAQ,KAAK,KAAK;OACzC,IAAI,OAAO,YAAY,YAAY,YAAY,MACrD,KAAK,MAAM,SAAS,OAAO,OAAO,OAAO,GAAG,QAAQ,KAAK,KAAK;CAEhE;CACA,OAAO;AACR;;;;;;;;AASA,SAAgB,YAAY,MAAuB;CAClD,OAAO,IAAI,IAAI,OAAO,KAAK,GAAG;AAC/B;;;;;;;;;AC5GA,SAAgB,iBAA6E;CAC5F,MAAM,QAAiB,CAAC;CACxB,OAAO;EACN;EACA,IAAI,QAAQ;GACX,OAAO,MAAM;EACd;EACA,QAAQ,GAAG,MAAM;GAChB,MAAM,KAAK,IAAI;EAChB;EACA,QAAQ;GACP,MAAM,SAAS;EAChB;CACD;AACD"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/helpers.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { JSONSafe } from './types.js'\n\n/**\n * Waits for a host timer to elapse.\n *\n * @param ms - The delay in milliseconds.\n * @returns A promise that resolves after the timer fires.\n */\nexport function waitForDelay(ms = 0): Promise<void> {\n\treturn new Promise((resolve) => setTimeout(resolve, ms))\n}\n\n/**\n * Captures the value thrown by a thunk.\n *\n * @param thunk - The work whose thrown value to capture.\n * @returns The thrown value, or `undefined` when the thunk completes.\n */\nexport function captureError(thunk: () => unknown): unknown {\n\ttry {\n\t\tthunk()\n\t} catch (error) {\n\t\treturn error\n\t}\n\treturn undefined\n}\n\n/**\n * Requires a value to be present.\n *\n * @typeParam T - The required value type.\n * @param value - The value to check.\n * @param message - The error message used when the value is absent.\n * @returns The present value.\n */\nexport function requireValue<T>(value: T | null | undefined, message = 'Value is required'): T {\n\tif (value === null || value === undefined) throw new Error(message)\n\treturn value\n}\n\n/**\n * Collects every value from an async iterable.\n *\n * @typeParam T - The yielded value type.\n * @param source - The async iterable to drain.\n * @returns The yielded values in iteration order.\n */\nexport async function collect<T>(source: AsyncIterable<T>): Promise<readonly T[]> {\n\tconst values: T[] = []\n\tfor await (const value of source) values.push(value)\n\treturn values\n}\n\n/**\n * Collects every value from a readable stream.\n *\n * @typeParam T - The streamed value type.\n * @param stream - The readable stream to drain.\n * @returns The streamed values in read order.\n */\nexport async function collectStream<T>(stream: ReadableStream<T>): Promise<readonly T[]> {\n\tconst reader = stream.getReader()\n\tconst values: T[] = []\n\ttry {\n\t\twhile (true) {\n\t\t\tconst result = await reader.read()\n\t\t\tif (result.done) return values\n\t\t\tvalues.push(result.value)\n\t\t}\n\t} finally {\n\t\treader.releaseLock()\n\t}\n}\n\n/**\n * Copies a JSON value through serialization and parsing.\n *\n * @typeParam T - The copied value's type, which the copy keeps.\n * @param value - The value to copy, bounded by its own `JSONSafe` projection.\n * @returns The parsed JSON copy.\n * @remarks Non-finite numbers throw because JSON would replace them with `null`. Negative zero is\n * normalized to zero by JSON serialization. The bound intersects `JSONSafe<T>` rather than\n * constraining `T` to `JSONValue`, so an interface-typed value round-trips.\n */\nexport function roundTripJSON<T>(value: T & JSONSafe<T>): T {\n\tconst serialized = JSON.stringify(value, (_key, current) => {\n\t\tif (current === undefined || typeof current === 'function' || typeof current === 'symbol') {\n\t\t\tthrow new Error('JSON values must not contain undefined, functions, or symbols')\n\t\t}\n\t\tif (typeof current === 'number' && !Number.isFinite(current)) {\n\t\t\tthrow new Error('JSON values must contain finite numbers')\n\t\t}\n\t\treturn current\n\t})\n\tconst parsed: T = JSON.parse(serialized)\n\tconst pending: unknown[] = [parsed]\n\twhile (pending.length > 0) {\n\t\tconst current = pending.pop()\n\t\tif (typeof current === 'number' && !Number.isFinite(current)) {\n\t\t\tthrow new Error('JSON values must contain finite numbers')\n\t\t}\n\t\tif (Array.isArray(current)) {\n\t\t\tfor (const child of current) pending.push(child)\n\t\t} else if (typeof current === 'object' && current !== null) {\n\t\t\tfor (const child of Object.values(current)) pending.push(child)\n\t\t}\n\t}\n\treturn parsed\n}\n\n/**\n * Resolves the parent directory of a calling module, which is the workspace root when called from\n * the conventional `tests/setup.ts` location.\n *\n * @param meta - The calling module metadata.\n * @returns The root URL one directory above the calling file.\n */\nexport function resolveRoot(meta: ImportMeta): URL {\n\treturn new URL('../', meta.url)\n}\n","import type { RecorderInterface } from './types.js'\n\n/**\n * Creates a recorder for callback arguments.\n *\n * @typeParam TArgs - The argument tuple to record.\n * @returns A recorder whose handler appends calls in order.\n */\nexport function createRecorder<TArgs extends readonly unknown[]>(): RecorderInterface<TArgs> {\n\tconst calls: TArgs[] = []\n\treturn {\n\t\tcalls,\n\t\tget count() {\n\t\t\treturn calls.length\n\t\t},\n\t\thandler(...args) {\n\t\t\tcalls.push(args)\n\t\t},\n\t\tclear() {\n\t\t\tcalls.length = 0\n\t\t},\n\t}\n}\n"],"mappings":";;;;;;;AAQA,SAAgB,aAAa,KAAK,GAAkB;CACnD,OAAO,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;AACxD;;;;;;;AAQA,SAAgB,aAAa,OAA+B;CAC3D,IAAI;EACH,MAAM;CACP,SAAS,OAAO;EACf,OAAO;CACR;AAED;;;;;;;;;AAUA,SAAgB,aAAgB,OAA6B,UAAU,qBAAwB;CAC9F,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW,MAAM,IAAI,MAAM,OAAO;CAClE,OAAO;AACR;;;;;;;;AASA,eAAsB,QAAW,QAAiD;CACjF,MAAM,SAAc,CAAC;CACrB,WAAW,MAAM,SAAS,QAAQ,OAAO,KAAK,KAAK;CACnD,OAAO;AACR;;;;;;;;AASA,eAAsB,cAAiB,QAAkD;CACxF,MAAM,SAAS,OAAO,UAAU;CAChC,MAAM,SAAc,CAAC;CACrB,IAAI;EACH,OAAO,MAAM;GACZ,MAAM,SAAS,MAAM,OAAO,KAAK;GACjC,IAAI,OAAO,MAAM,OAAO;GACxB,OAAO,KAAK,OAAO,KAAK;EACzB;CACD,UAAU;EACT,OAAO,YAAY;CACpB;AACD;;;;;;;;;;;AAYA,SAAgB,cAAiB,OAA2B;CAC3D,MAAM,aAAa,KAAK,UAAU,QAAQ,MAAM,YAAY;EAC3D,IAAI,YAAY,KAAA,KAAa,OAAO,YAAY,cAAc,OAAO,YAAY,UAChF,MAAM,IAAI,MAAM,+DAA+D;EAEhF,IAAI,OAAO,YAAY,YAAY,CAAC,OAAO,SAAS,OAAO,GAC1D,MAAM,IAAI,MAAM,yCAAyC;EAE1D,OAAO;CACR,CAAC;CACD,MAAM,SAAY,KAAK,MAAM,UAAU;CACvC,MAAM,UAAqB,CAAC,MAAM;CAClC,OAAO,QAAQ,SAAS,GAAG;EAC1B,MAAM,UAAU,QAAQ,IAAI;EAC5B,IAAI,OAAO,YAAY,YAAY,CAAC,OAAO,SAAS,OAAO,GAC1D,MAAM,IAAI,MAAM,yCAAyC;EAE1D,IAAI,MAAM,QAAQ,OAAO,GACxB,KAAK,MAAM,SAAS,SAAS,QAAQ,KAAK,KAAK;OACzC,IAAI,OAAO,YAAY,YAAY,YAAY,MACrD,KAAK,MAAM,SAAS,OAAO,OAAO,OAAO,GAAG,QAAQ,KAAK,KAAK;CAEhE;CACA,OAAO;AACR;;;;;;;;AASA,SAAgB,YAAY,MAAuB;CAClD,OAAO,IAAI,IAAI,OAAO,KAAK,GAAG;AAC/B;;;;;;;;;AC/GA,SAAgB,iBAA6E;CAC5F,MAAM,QAAiB,CAAC;CACxB,OAAO;EACN;EACA,IAAI,QAAQ;GACX,OAAO,MAAM;EACd;EACA,QAAQ,GAAG,MAAM;GAChB,MAAM,KAAK,IAAI;EAChB;EACA,QAAQ;GACP,MAAM,SAAS;EAChB;CACD;AACD"}

package/dist/src/server/index.cjs

@@ -18,36 +18,72 @@ function resolveContained(root, target) {
 	return candidate;
 }
 /**
-* Reads files from selected directories below a root directory.
+* Reports whether two directory identities name the same allocation.
+*
+* @param current - The identity read from the path now.
+* @param allocation - The identity recorded when the directory was allocated.
+* @returns Whether the device, the index node, and the creation time all match.
+* @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.
+*/
+function matchesIdentity(current, allocation) {
+	return current.device === allocation.device && current.inode === allocation.inode && current.birth === allocation.birth;
+}
+/**
+* Reports whether a root-relative key matches an exclusion.
+*
+* @param key - The root-relative key to test.
+* @param exclusions - The normalized root-relative exclusion keys.
+* @returns Whether an exclusion names the key or one of its ancestors.
+*/
+function isExcluded(key, exclusions) {
+	return exclusions.some((rule) => rule === "" || key === rule || key.startsWith(`${rule}/`));
+}
+/**
+* Reads files from selected targets below a root directory.
 *
 * @param root - The root directory as a path or file URL.
-* @param directories - The directories to visit below the root.
-* @param options - Optional file extension and exact-path exclusions.
+* @param targets - The files to read directly and directories to visit below the root.
+* @param options - Optional file extension and path exclusions.
 * @returns File contents keyed by sorted root-relative paths.
-* @remarks An absent extension filter includes every file. Exclusions match full root-relative keys.
+* @throws When the root or a named target is a symbolic link, is not a supported entry, or resolves
+* outside the root.
+* @remarks A named file is included regardless of the extension filter. An absent extension filter
+* includes every walked file. An exclusion matches whole root-relative key segments and covers every
+* key below it, and it applies to a named target and a walked entry alike.
 */
-function readInventory(root, directories, options) {
+function readInventory(root, targets, options) {
 	const supplied = (0, node_path.resolve)(typeof root === "string" ? root : (0, node_url.fileURLToPath)(root));
 	const rootStatus = (0, node_fs.lstatSync)(supplied);
 	if (rootStatus.isSymbolicLink()) throw new Error("Root is a symbolic link");
 	if (!rootStatus.isDirectory()) throw new Error("Root is not a directory");
 	const base = node_fs.realpathSync.native(supplied);
-	if (directories.length === 0) return Object.fromEntries([]);
-	const excluded = new Set(options?.exclude);
+	if (targets.length === 0) return Object.fromEntries([]);
+	const exclusions = (options?.exclude ?? []).map((rule) => {
+		const collapsed = (rule.startsWith("./") ? rule.slice(2) : rule).replace(/\/+/g, "/");
+		const untrailed = collapsed.endsWith("/") ? collapsed.slice(0, -1) : collapsed;
+		return untrailed === "." ? "" : untrailed;
+	});
 	const pending = [];
 	const queued = /* @__PURE__ */ new Set();
 	const contents = /* @__PURE__ */ new Map();
-	for (const directory of directories) {
-		const candidate = resolveContained(base, directory);
-		if (candidate === void 0) throw new Error(`Directory outside root: ${directory}`);
+	for (const target of targets) {
+		const candidate = resolveContained(base, target);
+		if (candidate === void 0) throw new Error(`Target outside root: ${target}`);
 		const status = (0, node_fs.lstatSync)(candidate);
-		if (status.isSymbolicLink()) throw new Error(`Directory is a symbolic link: ${directory}`);
-		if (!status.isDirectory()) throw new Error(`Not a directory: ${directory}`);
+		if (status.isSymbolicLink()) throw new Error(`Target is a symbolic link: ${target}`);
+		if (!status.isDirectory() && !status.isFile()) throw new Error(`Target is not a file or directory: ${target}`);
 		const physical = node_fs.realpathSync.native(candidate);
 		const resolved = resolveContained(base, (0, node_path.relative)(base, physical));
-		if (resolved === void 0) throw new Error(`Directory outside root: ${directory}`);
+		if (resolved === void 0) throw new Error(`Target outside root: ${target}`);
 		const key = (0, node_path.relative)(base, resolved).split(node_path.sep).join("/");
-		if (excluded.has(key) || queued.has(physical)) continue;
+		if (isExcluded(key, exclusions)) continue;
+		if (status.isFile()) {
+			contents.set(key, (0, node_fs.readFileSync)(physical, "utf8"));
+			continue;
+		}
+		if (queued.has(physical)) continue;
 		queued.add(physical);
 		pending.push(physical);
 	}
@@ -59,7 +95,7 @@ function readInventory(root, directories, options) {
 			const status = (0, node_fs.lstatSync)(path);
 			if (status.isSymbolicLink()) continue;
 			const key = (0, node_path.relative)(base, path).split(node_path.sep).join("/");
-			if (excluded.has(key)) continue;
+			if (isExcluded(key, exclusions)) continue;
 			if (status.isDirectory()) {
 				const physical = node_fs.realpathSync.native(path);
 				if (resolveContained(base, (0, node_path.relative)(base, physical)) === void 0 || queued.has(physical)) continue;
@@ -78,17 +114,30 @@ function readInventory(root, directories, options) {
 /**
 * Allocates an owned temporary directory with contained file operations.
 *
-* @param options - Optional directory prefix and initial files.
+* @param options - Optional parent directory, name prefix, and initial files.
 * @returns The scratch directory and its file operations.
-* @remarks The prefix defaults to `orkestrel-test-`. Seed keys use root-relative paths.
+* @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.
 */
 function createScratch(options) {
-	const temporary = (0, node_path.resolve)((0, node_os.tmpdir)());
-	const prefix = (0, node_path.resolve)(temporary, options?.prefix ?? "orkestrel-test-");
-	if ((0, node_path.dirname)(prefix) !== temporary) throw new Error("Scratch prefix must stay within the temporary directory");
-	const path = (0, node_fs.mkdtempSync)(prefix);
-	const allocation = (0, node_fs.statSync)(path);
+	const parent = (0, node_path.resolve)(options?.parent ?? (0, node_os.tmpdir)());
+	const parentStatus = (0, node_fs.lstatSync)(parent, { throwIfNoEntry: false });
+	if (parentStatus === void 0) throw new Error("Scratch parent does not exist");
+	if (parentStatus.isSymbolicLink()) throw new Error("Scratch parent is a symbolic link");
+	if (!parentStatus.isDirectory()) throw new Error("Scratch parent is not a directory");
+	const prefix = options?.prefix ?? "orkestrel-test-";
+	if (prefix.includes("/") || prefix.includes("\\")) throw new Error("Scratch prefix must be a name fragment");
+	const path = (0, node_fs.mkdtempSync)(`${parent}${node_path.sep}${prefix}`);
+	const allocated = (0, node_fs.statSync)(path);
+	const allocation = {
+		birth: allocated.birthtimeMs,
+		device: allocated.dev,
+		inode: allocated.ino
+	};
 	const outside = "Path outside scratch directory";
+	const unremovable = "Scratch directory is not a removable target";
 	try {
 		for (const [target, text] of Object.entries(options?.files ?? {})) {
 			const candidate = resolveContained(path, target);
@@ -108,23 +157,20 @@ function createScratch(options) {
 		write(target, text) {
 			const candidate = resolveContained(path, target);
 			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
-			const rootStatus = (0, node_fs.lstatSync)(path, { throwIfNoEntry: false });
-			if (rootStatus === void 0) throw new Error("Scratch directory does not exist");
-			if (rootStatus.isSymbolicLink()) throw new Error("Scratch directory is a symbolic link");
-			if (!rootStatus.isDirectory()) throw new Error("Scratch path is not a directory");
+			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			(0, node_fs.mkdirSync)((0, node_path.dirname)(candidate), { recursive: true });
 			(0, node_fs.writeFileSync)(candidate, text);
 		},
 		read(target) {
 			const candidate = resolveContained(path, target);
 			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
-			if (!scratch.exists(target)) return void 0;
+			if (!scratch.has(target)) return void 0;
 			const status = (0, node_fs.statSync)(candidate, { throwIfNoEntry: false });
 			if (status === void 0) return void 0;
 			if (status.isDirectory()) throw new Error(`Scratch path is a directory: ${target}`);
 			return (0, node_fs.readFileSync)(candidate, "utf8");
 		},
-		exists(target) {
+		has(target) {
 			const candidate = resolveContained(path, target);
 			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
 			const rootStatus = (0, node_fs.lstatSync)(path, { throwIfNoEntry: false });
@@ -133,9 +179,57 @@ function createScratch(options) {
 			if (!rootStatus.isDirectory()) throw new Error("Scratch path is not a directory");
 			return (0, node_fs.lstatSync)(candidate, { throwIfNoEntry: false }) !== void 0;
 		},
+		names(target = ".") {
+			const candidate = resolveContained(path, target);
+			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
+			const status = (0, node_fs.statSync)(candidate, { throwIfNoEntry: false });
+			if (status === void 0) throw new Error(`Scratch path does not exist: ${target}`);
+			if (!status.isDirectory()) throw new Error(`Scratch path is not a directory: ${target}`);
+			return (0, node_fs.readdirSync)(candidate).sort();
+		},
+		ensure(target) {
+			const candidate = resolveContained(path, target);
+			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
+			const status = (0, node_fs.statSync)(candidate, { throwIfNoEntry: false });
+			if (status !== void 0 && !status.isDirectory()) throw new Error(`Scratch path is not a directory: ${target}`);
+			if (status === void 0) (0, node_fs.mkdirSync)(candidate, { recursive: true });
+			return candidate;
+		},
+		link(target, source) {
+			const candidate = resolveContained(path, target);
+			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
+			(0, node_fs.mkdirSync)((0, node_path.dirname)(candidate), { recursive: true });
+			(0, node_fs.symlinkSync)(source, candidate);
+		},
+		remove(target) {
+			const candidate = resolveContained(path, target);
+			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			if (candidate === path) throw new Error(`${unremovable}: ${target}`);
+			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
+			const status = (0, node_fs.lstatSync)(candidate, { throwIfNoEntry: false });
+			if (status !== void 0) {
+				if (matchesIdentity({
+					birth: status.birthtimeMs,
+					device: status.dev,
+					inode: status.ino
+				}, allocation)) throw new Error(`${unremovable}: ${target}`);
+			}
+			(0, node_fs.rmSync)(candidate, {
+				force: true,
+				recursive: true
+			});
+		},
 		destroy() {
 			const status = (0, node_fs.lstatSync)(path, { throwIfNoEntry: false });
-			if (status === void 0 || status.dev !== allocation.dev || status.ino !== allocation.ino || status.birthtimeMs !== allocation.birthtimeMs) return;
+			if (status === void 0) return;
+			if (!matchesIdentity({
+				birth: status.birthtimeMs,
+				device: status.dev,
+				inode: status.ino
+			}, allocation)) return;
 			(0, node_fs.rmSync)(path, {
 				force: true,
 				recursive: true
@@ -146,6 +240,8 @@ function createScratch(options) {
 }
 //#endregion
 exports.createScratch = createScratch;
+exports.isExcluded = isExcluded;
+exports.matchesIdentity = matchesIdentity;
 exports.readInventory = readInventory;
 exports.resolveContained = resolveContained;