@orkestrel/test 0.0.8 → 0.0.10

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

@@ -215,6 +215,39 @@ export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
  */
 export declare function removeTree(path: string): void;
 
+/**
+ * Drives a real client upgrade request against a loopback port and reports what the server did.
+ *
+ * @param port - The port the server listens on at `127.0.0.1`.
+ * @param options - Optional request path, offered subprotocols, time bounds, and abort signal.
+ * @returns A promise resolving to the server's answer: a claimed upgrade with the protocol it
+ * selected, or a refusal with the status it answered.
+ * @throws The client's own transport error, such as the `ECONNREFUSED` a closed port answers, the
+ * abort reason, or an `Error` when a bound is invalid or the server does not answer within the
+ * budget.
+ * @remarks Default budget: `1000` milliseconds. The request carries `Connection: Upgrade` and
+ * `Upgrade: websocket`, which is what makes a server's `upgrade` handler the one that answers it.
+ * The `upgrade`, `response`, and `error` events are mutually exclusive in practice and the promise
+ * settles on whichever arrives first, so a second event changes nothing. The client socket is
+ * destroyed before every settlement, on the claimed path because an upgraded socket is detached from
+ * the request and outlives it otherwise. The request is made with no agent, so no pooled connection
+ * survives the call to keep a suite's event loop alive.
+ *
+ * A server that accepts the connection and answers nothing raises no transport error, so the budget
+ * is what ends that call: the rejection names the port and path it was waiting on. The interval is
+ * validated for consistency with the wait family but is not used, because this helper parks on the
+ * request's events.
+ *
+ * A `101` is the claimed path's status on the wire and is deliberately not reported: `status` is the
+ * refused arm's member, and a claimed upgrade produced no plain answer.
+ * @example
+ * ```ts
+ * const answer = await requestUpgrade(loopback.port, { path: '/socket', protocols: ['chat'] })
+ * // { claimed: true, protocol: 'chat' }
+ * ```
+ */
+export declare function requestUpgrade(port: number, options?: UpgradeOptions): Promise<UpgradeResult>;
+
 /**
  * Resolves a target that stays below a root directory.
  *
@@ -243,10 +276,11 @@ export declare interface ScratchInterface {
      *
      * @param target - A relative or absolute file path contained by the scratch directory.
      * @param text - The file contents.
+     * @returns The absolute path of the written file.
      * @throws When the target escapes the scratch directory, the scratch root is missing, a symbolic
      * link, or a file, or the host refuses to write the file.
      */
-    write(target: string, text: string): void;
+    write(target: string, text: string): string;
     /**
      * Reads a file.
      *
@@ -294,12 +328,13 @@ export declare interface ScratchInterface {
      * @param source - The destination path the link points at. The stored value is a path naming that
      * destination, but its exact text is not promised. The path may name a destination outside the
      * scratch directory and is not containment-checked.
+     * @returns The absolute path of the created link, whatever host mechanism created it.
      * @throws When the target escapes the scratch directory, the scratch root is missing, a symbolic
      * link, or a file, or the host refuses to create the link, including a host that creates no
      * symbolic link when the source names an existing non-directory.
      * @remarks {@link createLink} owns the host-specific link mechanism.
      */
-    link(target: string, source: string): void;
+    link(target: string, source: string): string;
     /**
      * Removes a file, an empty directory, or a directory and its descendants.
      *
@@ -339,6 +374,112 @@ export declare interface ScratchOptions {
     readonly files?: Readonly<Record<string, string>>;
 }
 
+/**
+ * Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves.
+ *
+ * @returns True if a name ending in byte `0x80` is written and read back; false otherwise, including
+ * every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @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.
+ */
+export declare function supportsBytes(): boolean;
+
+/**
+ * Checks whether this host treats two names differing only by case as distinct files.
+ *
+ * @returns True if `A` and `a` hold the contents each was written with; false otherwise, including
+ * every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @remarks The names `A` and `a` differ by case and by nothing else, which is what makes the reading
+ * an answer about case folding rather than an answer about two unrelated files. A case-folding volume
+ * 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.
+ */
+export declare function supportsCase(): boolean;
+
+/**
+ * Checks whether this host links a directory, by creating one link and reading through it.
+ *
+ * @returns True if the created link reports as a symbolic link, resolves to a directory, and reaches
+ * the destination's contents; false otherwise, including every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @remarks `symlinkSync(source, target, 'junction')` creates a directory junction on Windows, which
+ * needs no privilege, and Node ignores the type argument off Windows, so one call covers both hosts.
+ * 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.
+ */
+export declare function supportsDirectoryLinks(): boolean;
+
+/**
+ * Checks whether this host links a file, by creating one link and reading the file through it.
+ *
+ * @returns True if the file's contents are readable through the link; false otherwise, including
+ * every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @remarks `symlinkSync(source, target, 'file')` needs the symbolic-link privilege, which Windows
+ * grants under Developer Mode or administrator rights and refuses with `EPERM` otherwise, so the
+ * answer is true on POSIX and on a privileged Windows host. Where it is false, no mechanism reaches a
+ * file through a link and a proof that reads one back cannot run. This is a separate question from
+ * {@link supportsDirectoryLinks}, which an unprivileged Windows host answers true through a junction
+ * while answering this one false.
+ */
+export declare function supportsFileLinks(): boolean;
+
+/**
+ * Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`.
+ *
+ * @returns True if a directory created with mode `0o700` reports that mode back; false otherwise,
+ * including every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @remarks POSIX reports `mode & 0o777 === 0o700` and Windows reports `0o666` regardless, so the
+ * answer is true on POSIX and false on Windows. Storing a bit is a narrower question than enforcing
+ * 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.
+ */
+export declare function supportsMode(): boolean;
+
+/**
+ * Options for driving a client upgrade request.
+ *
+ * @remarks The time bounds and abort signal bound the wait for the server's answer, so a server
+ * that accepts the connection and never answers ends the call rather than parking it.
+ */
+export declare interface UpgradeOptions extends WaitOptions {
+    /** The request path, written with its leading slash. Defaults to `/`. */
+    readonly path?: string;
+    /**
+     * The subprotocol tokens the request offers. They are sent as one comma-separated
+     * `Sec-WebSocket-Protocol` field, and an empty or omitted list sends no field at all.
+     */
+    readonly protocols?: readonly string[];
+}
+
+/**
+ * What one server did with a client upgrade request.
+ *
+ * @remarks `claimed` is the discriminant. The claimed arm carries `protocol`, the subprotocol the
+ * server selected, which is `undefined` when it selected none; a claimed upgrade produced no plain
+ * answer, so it carries no status and the `101` on the wire is deliberately not reported as one.
+ * The refused arm carries `status`, the plain answer's status, and no subprotocol.
+ */
+export declare type UpgradeResult = {
+    readonly claimed: true;
+    readonly protocol: string | undefined;
+} | {
+    readonly claimed: false;
+    readonly status: number;
+};
+
 /**
  * Waits for a socket to close, accepting a peer reset as a forced close.
  *

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

@@ -215,6 +215,39 @@ export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
  */
 export declare function removeTree(path: string): void;
 
+/**
+ * Drives a real client upgrade request against a loopback port and reports what the server did.
+ *
+ * @param port - The port the server listens on at `127.0.0.1`.
+ * @param options - Optional request path, offered subprotocols, time bounds, and abort signal.
+ * @returns A promise resolving to the server's answer: a claimed upgrade with the protocol it
+ * selected, or a refusal with the status it answered.
+ * @throws The client's own transport error, such as the `ECONNREFUSED` a closed port answers, the
+ * abort reason, or an `Error` when a bound is invalid or the server does not answer within the
+ * budget.
+ * @remarks Default budget: `1000` milliseconds. The request carries `Connection: Upgrade` and
+ * `Upgrade: websocket`, which is what makes a server's `upgrade` handler the one that answers it.
+ * The `upgrade`, `response`, and `error` events are mutually exclusive in practice and the promise
+ * settles on whichever arrives first, so a second event changes nothing. The client socket is
+ * destroyed before every settlement, on the claimed path because an upgraded socket is detached from
+ * the request and outlives it otherwise. The request is made with no agent, so no pooled connection
+ * survives the call to keep a suite's event loop alive.
+ *
+ * A server that accepts the connection and answers nothing raises no transport error, so the budget
+ * is what ends that call: the rejection names the port and path it was waiting on. The interval is
+ * validated for consistency with the wait family but is not used, because this helper parks on the
+ * request's events.
+ *
+ * A `101` is the claimed path's status on the wire and is deliberately not reported: `status` is the
+ * refused arm's member, and a claimed upgrade produced no plain answer.
+ * @example
+ * ```ts
+ * const answer = await requestUpgrade(loopback.port, { path: '/socket', protocols: ['chat'] })
+ * // { claimed: true, protocol: 'chat' }
+ * ```
+ */
+export declare function requestUpgrade(port: number, options?: UpgradeOptions): Promise<UpgradeResult>;
+
 /**
  * Resolves a target that stays below a root directory.
  *
@@ -243,10 +276,11 @@ export declare interface ScratchInterface {
      *
      * @param target - A relative or absolute file path contained by the scratch directory.
      * @param text - The file contents.
+     * @returns The absolute path of the written file.
      * @throws When the target escapes the scratch directory, the scratch root is missing, a symbolic
      * link, or a file, or the host refuses to write the file.
      */
-    write(target: string, text: string): void;
+    write(target: string, text: string): string;
     /**
      * Reads a file.
      *
@@ -294,12 +328,13 @@ export declare interface ScratchInterface {
      * @param source - The destination path the link points at. The stored value is a path naming that
      * destination, but its exact text is not promised. The path may name a destination outside the
      * scratch directory and is not containment-checked.
+     * @returns The absolute path of the created link, whatever host mechanism created it.
      * @throws When the target escapes the scratch directory, the scratch root is missing, a symbolic
      * link, or a file, or the host refuses to create the link, including a host that creates no
      * symbolic link when the source names an existing non-directory.
      * @remarks {@link createLink} owns the host-specific link mechanism.
      */
-    link(target: string, source: string): void;
+    link(target: string, source: string): string;
     /**
      * Removes a file, an empty directory, or a directory and its descendants.
      *
@@ -339,6 +374,112 @@ export declare interface ScratchOptions {
     readonly files?: Readonly<Record<string, string>>;
 }
 
+/**
+ * Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves.
+ *
+ * @returns True if a name ending in byte `0x80` is written and read back; false otherwise, including
+ * every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @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.
+ */
+export declare function supportsBytes(): boolean;
+
+/**
+ * Checks whether this host treats two names differing only by case as distinct files.
+ *
+ * @returns True if `A` and `a` hold the contents each was written with; false otherwise, including
+ * every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @remarks The names `A` and `a` differ by case and by nothing else, which is what makes the reading
+ * an answer about case folding rather than an answer about two unrelated files. A case-folding volume
+ * 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.
+ */
+export declare function supportsCase(): boolean;
+
+/**
+ * Checks whether this host links a directory, by creating one link and reading through it.
+ *
+ * @returns True if the created link reports as a symbolic link, resolves to a directory, and reaches
+ * the destination's contents; false otherwise, including every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @remarks `symlinkSync(source, target, 'junction')` creates a directory junction on Windows, which
+ * needs no privilege, and Node ignores the type argument off Windows, so one call covers both hosts.
+ * 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.
+ */
+export declare function supportsDirectoryLinks(): boolean;
+
+/**
+ * Checks whether this host links a file, by creating one link and reading the file through it.
+ *
+ * @returns True if the file's contents are readable through the link; false otherwise, including
+ * every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @remarks `symlinkSync(source, target, 'file')` needs the symbolic-link privilege, which Windows
+ * grants under Developer Mode or administrator rights and refuses with `EPERM` otherwise, so the
+ * answer is true on POSIX and on a privileged Windows host. Where it is false, no mechanism reaches a
+ * file through a link and a proof that reads one back cannot run. This is a separate question from
+ * {@link supportsDirectoryLinks}, which an unprivileged Windows host answers true through a junction
+ * while answering this one false.
+ */
+export declare function supportsFileLinks(): boolean;
+
+/**
+ * Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`.
+ *
+ * @returns True if a directory created with mode `0o700` reports that mode back; false otherwise,
+ * including every host refusal.
+ * @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+ * remove it afterwards, both propagate.
+ * @remarks POSIX reports `mode & 0o777 === 0o700` and Windows reports `0o666` regardless, so the
+ * answer is true on POSIX and false on Windows. Storing a bit is a narrower question than enforcing
+ * 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.
+ */
+export declare function supportsMode(): boolean;
+
+/**
+ * Options for driving a client upgrade request.
+ *
+ * @remarks The time bounds and abort signal bound the wait for the server's answer, so a server
+ * that accepts the connection and never answers ends the call rather than parking it.
+ */
+export declare interface UpgradeOptions extends WaitOptions {
+    /** The request path, written with its leading slash. Defaults to `/`. */
+    readonly path?: string;
+    /**
+     * The subprotocol tokens the request offers. They are sent as one comma-separated
+     * `Sec-WebSocket-Protocol` field, and an empty or omitted list sends no field at all.
+     */
+    readonly protocols?: readonly string[];
+}
+
+/**
+ * What one server did with a client upgrade request.
+ *
+ * @remarks `claimed` is the discriminant. The claimed arm carries `protocol`, the subprotocol the
+ * server selected, which is `undefined` when it selected none; a claimed upgrade produced no plain
+ * answer, so it carries no status and the `101` on the wire is deliberately not reported as one.
+ * The refused arm carries `status`, the plain answer's status, and no subprotocol.
+ */
+export declare type UpgradeResult = {
+    readonly claimed: true;
+    readonly protocol: string | undefined;
+} | {
+    readonly claimed: false;
+    readonly status: number;
+};
+
 /**
  * Waits for a socket to close, accepting a peer reset as a forced close.
  *

package/dist/src/server/index.js

@@ -1,9 +1,11 @@
+import { Buffer } from "node:buffer";
 import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+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 { waitForDelay } from "../core/index.js";
 import { once } from "node:events";
-import { tmpdir } from "node:os";
 //#region src/server/constants.ts
 /**
 * The attempts `removeTree` makes before rethrowing a retryable removal error.
@@ -312,6 +314,239 @@ async function destroyScratch(scratch, options) {
 		await waitForDelay(interval);
 	}
 }
+/**
+* Drives a real client upgrade request against a loopback port and reports what the server did.
+*
+* @param port - The port the server listens on at `127.0.0.1`.
+* @param options - Optional request path, offered subprotocols, time bounds, and abort signal.
+* @returns A promise resolving to the server's answer: a claimed upgrade with the protocol it
+* selected, or a refusal with the status it answered.
+* @throws The client's own transport error, such as the `ECONNREFUSED` a closed port answers, the
+* abort reason, or an `Error` when a bound is invalid or the server does not answer within the
+* budget.
+* @remarks Default budget: `1000` milliseconds. The request carries `Connection: Upgrade` and
+* `Upgrade: websocket`, which is what makes a server's `upgrade` handler the one that answers it.
+* The `upgrade`, `response`, and `error` events are mutually exclusive in practice and the promise
+* settles on whichever arrives first, so a second event changes nothing. The client socket is
+* destroyed before every settlement, on the claimed path because an upgraded socket is detached from
+* the request and outlives it otherwise. The request is made with no agent, so no pooled connection
+* survives the call to keep a suite's event loop alive.
+*
+* A server that accepts the connection and answers nothing raises no transport error, so the budget
+* is what ends that call: the rejection names the port and path it was waiting on. The interval is
+* validated for consistency with the wait family but is not used, because this helper parks on the
+* request's events.
+*
+* A `101` is the claimed path's status on the wire and is deliberately not reported: `status` is the
+* refused arm's member, and a claimed upgrade produced no plain answer.
+* @example
+* ```ts
+* const answer = await requestUpgrade(loopback.port, { path: '/socket', protocols: ['chat'] })
+* // { claimed: true, protocol: 'chat' }
+* ```
+*/
+async function requestUpgrade(port, options) {
+	const budget = options?.budget ?? 1e3;
+	const interval = options?.interval ?? 10;
+	if (!Number.isFinite(budget) || budget < 0) throw new Error("Upgrade budget must be finite and non-negative");
+	if (!Number.isFinite(interval) || interval < 0) throw new Error("Upgrade interval must be finite and non-negative");
+	const signal = options?.signal;
+	signal?.throwIfAborted();
+	const path = options?.path ?? "/";
+	const target = `127.0.0.1:${port}${path}`;
+	const headers = {
+		connection: "Upgrade",
+		upgrade: "websocket"
+	};
+	const protocols = options?.protocols ?? [];
+	if (protocols.length > 0) headers["sec-websocket-protocol"] = protocols.join(", ");
+	const request$1 = request({
+		agent: false,
+		headers,
+		host: "127.0.0.1",
+		path,
+		port
+	});
+	const settled = Promise.withResolvers();
+	const expiry = Promise.withResolvers();
+	const aborted = Promise.withResolvers();
+	const subscription = new AbortController();
+	request$1.on("upgrade", (response, socket) => {
+		const protocol = response.headers["sec-websocket-protocol"];
+		socket.destroy();
+		settled.resolve({
+			claimed: true,
+			protocol
+		});
+	});
+	request$1.on("response", (response) => {
+		const status = response.statusCode;
+		response.destroy();
+		request$1.destroy();
+		if (status === void 0) {
+			settled.reject(/* @__PURE__ */ new Error(`Upgrade request to ${target} was answered without a status`));
+			return;
+		}
+		settled.resolve({
+			claimed: false,
+			status
+		});
+	});
+	request$1.on("error", (error) => {
+		request$1.destroy();
+		settled.reject(error);
+	});
+	signal?.addEventListener("abort", () => aborted.reject(signal.reason), {
+		once: true,
+		signal: subscription.signal
+	});
+	const timer = setTimeout(() => {
+		expiry.reject(/* @__PURE__ */ new Error(`Upgrade request to ${target} was not answered within ${budget}ms`));
+	}, budget);
+	request$1.end();
+	try {
+		return await Promise.race([
+			settled.promise,
+			expiry.promise,
+			aborted.promise
+		]);
+	} finally {
+		clearTimeout(timer);
+		subscription.abort();
+		request$1.destroy();
+	}
+}
+/**
+* Checks whether this host links a directory, by creating one link and reading through it.
+*
+* @returns True if the created link reports as a symbolic link, resolves to a directory, and reaches
+* the destination's contents; false otherwise, including every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @remarks `symlinkSync(source, target, 'junction')` creates a directory junction on Windows, which
+* needs no privilege, and Node ignores the type argument off Windows, so one call covers both hosts.
+* 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.
+*/
+function supportsDirectoryLinks() {
+	const directory = mkdtempSync(join(tmpdir(), "orkestrel-test-directory-links-"));
+	try {
+		const source = join(directory, "source");
+		const link = join(directory, "link");
+		mkdirSync(source);
+		writeFileSync(join(source, "marker.txt"), "marked");
+		symlinkSync(source, link, "junction");
+		return lstatSync(link).isSymbolicLink() && statSync(link).isDirectory() && readFileSync(join(link, "marker.txt"), "utf8") === "marked";
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
+/**
+* Checks whether this host links a file, by creating one link and reading the file through it.
+*
+* @returns True if the file's contents are readable through the link; false otherwise, including
+* every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @remarks `symlinkSync(source, target, 'file')` needs the symbolic-link privilege, which Windows
+* grants under Developer Mode or administrator rights and refuses with `EPERM` otherwise, so the
+* answer is true on POSIX and on a privileged Windows host. Where it is false, no mechanism reaches a
+* file through a link and a proof that reads one back cannot run. This is a separate question from
+* {@link supportsDirectoryLinks}, which an unprivileged Windows host answers true through a junction
+* while answering this one false.
+*/
+function supportsFileLinks() {
+	const directory = mkdtempSync(join(tmpdir(), "orkestrel-test-file-links-"));
+	try {
+		const source = join(directory, "source.txt");
+		const link = join(directory, "link.txt");
+		writeFileSync(source, "linked");
+		symlinkSync(source, link, "file");
+		return readFileSync(link, "utf8") === "linked";
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
+/**
+* Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`.
+*
+* @returns True if a directory created with mode `0o700` reports that mode back; false otherwise,
+* including every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @remarks POSIX reports `mode & 0o777 === 0o700` and Windows reports `0o666` regardless, so the
+* answer is true on POSIX and false on Windows. Storing a bit is a narrower question than enforcing
+* 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.
+*/
+function supportsMode() {
+	const directory = mkdtempSync(join(tmpdir(), "orkestrel-test-mode-"));
+	try {
+		const path = join(directory, "moded");
+		mkdirSync(path, { mode: 448 });
+		return (statSync(path).mode & 511) === 448;
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
+/**
+* Checks whether this host treats two names differing only by case as distinct files.
+*
+* @returns True if `A` and `a` hold the contents each was written with; false otherwise, including
+* every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @remarks The names `A` and `a` differ by case and by nothing else, which is what makes the reading
+* an answer about case folding rather than an answer about two unrelated files. A case-folding volume
+* 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.
+*/
+function supportsCase() {
+	const directory = mkdtempSync(join(tmpdir(), "orkestrel-test-case-"));
+	try {
+		const upper = join(directory, "A");
+		const lower = join(directory, "a");
+		writeFileSync(upper, "upper");
+		writeFileSync(lower, "lower");
+		return readFileSync(upper, "utf8") === "upper" && readFileSync(lower, "utf8") === "lower";
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
+/**
+* Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves.
+*
+* @returns True if a name ending in byte `0x80` is written and read back; false otherwise, including
+* every host refusal.
+* @throws Nothing the attempt itself raises. Failing to allocate the probe directory, and failing to
+* remove it afterwards, both propagate.
+* @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.
+*/
+function supportsBytes() {
+	const directory = mkdtempSync(join(tmpdir(), "orkestrel-test-bytes-"));
+	try {
+		const name = Buffer.concat([Buffer.from(`${directory}${sep}`), Buffer.from([128])]);
+		writeFileSync(name, "raw");
+		return readFileSync(name, "utf8") === "raw";
+	} catch {
+		return false;
+	} finally {
+		removeTree(directory);
+	}
+}
 //#endregion
 //#region src/server/factories.ts
 /**
@@ -360,6 +595,7 @@ function createScratch(options) {
 			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			mkdirSync(dirname(candidate), { recursive: true });
 			writeFileSync(candidate, text);
+			return candidate;
 		},
 		read(target) {
 			const candidate = resolveContained(path, target);
@@ -403,6 +639,7 @@ function createScratch(options) {
 			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			mkdirSync(dirname(candidate), { recursive: true });
 			createLink(candidate, source);
+			return candidate;
 		},
 		remove(target) {
 			const candidate = resolveContained(path, target);
@@ -495,6 +732,6 @@ function createCookieJar() {
 	};
 }
 //#endregion
-export { REMOVE_TREE_MAX_ATTEMPTS, REMOVE_TREE_RETRYABLE_CODES, REMOVE_TREE_RETRY_DELAY_MS, createCookieJar, createLink, createLoopback, createScratch, destroyScratch, isExcluded, isRunning, matchesIdentity, readInventory, removeTree, resolveContained, waitForSocketClose };
+export { REMOVE_TREE_MAX_ATTEMPTS, REMOVE_TREE_RETRYABLE_CODES, REMOVE_TREE_RETRY_DELAY_MS, createCookieJar, createLink, createLoopback, createScratch, destroyScratch, isExcluded, isRunning, matchesIdentity, readInventory, removeTree, requestUpgrade, resolveContained, supportsBytes, supportsCase, supportsDirectoryLinks, supportsFileLinks, supportsMode, waitForSocketClose };
 
 //# sourceMappingURL=index.js.map