opencode-session-port 0.0.0-stage → 0.1.0

package/src/tui/adapters/host-client.ts

@@ -0,0 +1,254 @@
+/**
+ * Narrow structural boundary over the public TUI `context.client` surface.
+ *
+ * These adapters never import the host runtime; they accept the host-provided
+ * client as an untrusted value, resolve the specific methods they use with
+ * runtime checks, and call only through public client methods. The narrow
+ * interfaces below document the exact surface the adapters call and are used
+ * for compile-time assertions against the installed OpenCode v2.0.22 TUI
+ * declaration (`Plugin.Context["client"]`, the generated `OpenCodeClient`).
+ *
+ * Declaration boundary (O-12/OQ-12): the installed plugin hook `SessionDomain`
+ * declaration omits `session.import` while the generated TUI client
+ * declaration includes it; the generated client is also what the TUI plugin
+ * context actually carries. This module therefore does not depend on any host
+ * type at runtime: capability is detected at runtime (see
+ * `probeSessionImportCapability`), and the compile-time assertions below only
+ * pin the installed declaration relation so `tsc` flags a drift. No blanket
+ * `any` is used anywhere; the single unknown-to-callable conversion point is
+ * `resolveUnaryMethod`, which narrows a value proven callable by `typeof` to a typed call signature
+ * and always invokes it with its owning object (`client[container]`) preserved
+ * as the receiver, so a `this`-dependent host method behaves exactly as a
+ * direct `client[container][method](input)` call would.
+ *
+ * Bounded evidence only: the v2.0.22 declaration/source research (E13/E14/E18)
+ * and the one-run actual-TUI probe (E33) are not a cross-version or support
+ * claim. Do not extend them.
+ */
+
+import type { Plugin } from "@opencode/plugin/tui";
+import type { JsonObject } from "../../core/contracts/index.ts";
+
+/* ------------------------------------------------------------------------- */
+/* Errors                                                                    */
+/* ------------------------------------------------------------------------- */
+
+/** Stable machine-readable failure codes for host adapter setup/invocation. */
+export type HostAdapterErrorCode =
+	/** The installed client does not expose the required callable method. */
+	| "capability-unavailable"
+	/** The adapter was called with a request that violates the core port contract. */
+	| "invalid-request"
+	/** The host call resolved with a value that violates the declared response contract. */
+	| "invalid-response";
+
+/**
+ * Fail-closed adapter error. Never wraps or replaces host API errors: errors
+ * thrown by the public client itself propagate unchanged so restore/checkpoint
+ * reporting stays truthful.
+ */
+export class HostAdapterError extends Error {
+	readonly code: HostAdapterErrorCode;
+
+	constructor(code: HostAdapterErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "HostAdapterError";
+		this.code = code;
+	}
+}
+
+/* ------------------------------------------------------------------------- */
+/* Narrow client surface (documentation + compile-time assertions)           */
+/* ------------------------------------------------------------------------- */
+
+/** One `session.list` request as mapped from `SessionListPageRequest`. */
+export interface SessionListCallInput {
+	/** Explicit project scope; mapped to the list route's `project` filter. */
+	readonly project: string;
+	/** Explicit page size; the API default is never relied on. */
+	readonly limit: number;
+	/** Opaque `cursor.next`; absent on the first request. */
+	readonly cursor?: string;
+}
+
+/** One `message.list` request as mapped from `MessageListPageRequest`. */
+export interface MessageListCallInput {
+	/** Route-scoped session ID (the ownership boundary). */
+	readonly sessionID: string;
+	/** Explicit page size; the API default is never relied on. */
+	readonly limit: number;
+	/** First page only: ascending order. */
+	readonly order?: "asc";
+	/** Subsequent pages only: opaque cursor; no `order`, no `type` filter. */
+	readonly cursor?: string;
+}
+
+/**
+ * Narrow structural view of the public read surface used for enumeration.
+ *
+ * All members are optional because capability absence is a real runtime state
+ * (E1/OQ-12): the adapters fail closed with a clear `HostAdapterError` when a
+ * method is missing or not callable. Method syntax is intentional: it keeps
+ * the installed generated client assignable (bivariant parameter check) while
+ * the runtime resolver below still validates callability before every use.
+ */
+export interface SessionReadClientLike {
+	readonly session?: {
+		list?(input: SessionListCallInput): Promise<unknown>;
+	};
+	readonly message?: {
+		list?(input: MessageListCallInput): Promise<unknown>;
+	};
+}
+
+/**
+ * One `session.import` call payload: the final planned record (`info` and
+ * `messages` are passed through verbatim, never re-derived here) plus the
+ * explicit target location supplied by the caller.
+ *
+ * `location` is typed optional/nullable only so the installed v2.0.22
+ * generated declaration (`SessionImportInput`, whose `location` is optional
+ * and nullable) remains assignable to this narrow view; the import adapter
+ * always supplies it (O-16: V1 always supplies an explicit target).
+ */
+export interface SessionImportCallInput {
+	readonly info: JsonObject;
+	readonly messages: readonly JsonObject[];
+	readonly location?: { readonly directory: string } | null;
+}
+
+/**
+ * Validated narrow view of one `session.import` response.
+ *
+ * The pinned v2.0.22 public TUI client (`context.client`, the generated promise
+ * client) unwraps the raw protocol `{ data: SessionInfo }` envelope and
+ * resolves the `SessionInfo` directly: its declaration is
+ * `import(input) => Promise<SessionInfo>`, and `SessionInfo` carries
+ * non-optional `id`, `projectID`, and `location.directory`. The generated
+ * client casts the JSON body to that declared type without runtime validation,
+ * so the import adapter re-proves these fields at this dynamic boundary before
+ * treating a response as confirmed; it returns the original response value
+ * unchanged after narrowing. Only the fields SessionPort relies on are
+ * declared here.
+ */
+export interface SessionImportResult {
+	readonly id: string;
+	readonly projectID: string;
+	readonly location: { readonly directory: string };
+}
+
+/**
+ * Narrow structural view of the public import surface. `import` is optional
+ * because it may be absent or non-callable at runtime (O-12 policy: probe at
+ * restore start and stop with a clear message before reading or decrypting).
+ * The resolved value is intentionally `unknown` at this raw boundary: the
+ * generated client does not runtime-validate its JSON, so the import adapter
+ * proves the declared `SessionInfo` fields (`SessionImportResult`) before a
+ * response is treated as confirmed.
+ */
+export interface SessionImportClientLike {
+	readonly session?: {
+		import?(input: SessionImportCallInput): Promise<unknown>;
+	};
+}
+
+/* ------------------------------------------------------------------------- */
+/* Compile-time assertions against the installed TUI client declaration      */
+/* ------------------------------------------------------------------------- */
+
+type HostTuiClient = Plugin.Context["client"];
+type AssertTrue<T extends true> = T;
+
+/**
+ * The installed v2.0.22 TUI client (`Plugin.Context["client"]`) must satisfy
+ * the narrow read surface; if a future pinned declaration drifts, `tsc` fails
+ * here instead of failing at runtime.
+ */
+type _AssertHostReadClientCompatible = AssertTrue<HostTuiClient extends SessionReadClientLike ? true : false>;
+
+/**
+ * The installed declaration must expose the import surface with a payload
+ * shape compatible with `SessionImportCallInput` and a top-level `location`
+ * target field. This pins the declaration side of the known
+ * `SessionDomain`-vs-generated-client mismatch to the narrowest typed
+ * boundary; runtime callability is still checked by the probe.
+ */
+type _AssertHostImportClientCompatible = AssertTrue<HostTuiClient extends SessionImportClientLike ? true : false>;
+type _AssertHostImportInputCompatible = AssertTrue<
+	Parameters<HostTuiClient["session"]["import"]>[0] extends SessionImportCallInput ? true : false
+>;
+type _AssertHostImportInputHasLocationTarget = AssertTrue<
+	Parameters<HostTuiClient["session"]["import"]>[0] extends { location?: { directory: string } | null | undefined }
+		? true
+		: false
+>;
+
+/**
+ * The declared `session.import` output must keep exposing the fields the
+ * adapter validates (`id`, `projectID`, `location.directory`); drift in those
+ * fields is a compile error, not a silent runtime fallback. The declaration
+ * type is the unwrapped `SessionInfo` (the raw `{ data }` envelope is already
+ * unwrapped by the generated promise client), which is exactly what the
+ * runtime guard in `session-import.ts` re-proves.
+ */
+type HostImportOutput = Awaited<ReturnType<HostTuiClient["session"]["import"]>>;
+type _AssertHostImportOutputHasValidatedFields = AssertTrue<
+	HostImportOutput extends {
+		readonly id: string;
+		readonly projectID: string;
+		readonly location: { readonly directory: string };
+	}
+		? true
+		: false
+>;
+
+/* ------------------------------------------------------------------------- */
+/* Runtime resolution helpers                                                */
+/* ------------------------------------------------------------------------- */
+
+/** True for non-null, non-array object values; used on untrusted client values. */
+export function isObjectRecord(value: unknown): value is { readonly [key: string]: unknown } {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+type UnaryMethod<Input> = (input: Input) => Promise<unknown>;
+
+/**
+ * Resolves `client[container][method]` to a typed call signature only when the
+ * value is actually a function. This is the single unknown-to-typed conversion
+ * boundary: the `typeof` check proves callability, and the returned wrapper
+ * awaits whatever the host method returns so the result is always a Promise.
+ *
+ * The wrapper preserves the exact owning object (`client[container]`) as the
+ * receiver via `Reflect.apply`, so a host method that depends on `this` (class
+ * method, prototype method, non-arrow object property) is invoked with the
+ * same receiver a direct `client[container][method](input)` call would supply.
+ * The installed v2.0.22 generated promise client happens to build these
+ * methods as arrow closures over its transport (which ignore the receiver),
+ * but the adapter must not depend on that implementation detail.
+ */
+export function resolveUnaryMethod<Input>(client: unknown, container: string, method: string): UnaryMethod<Input> | undefined {
+	if (!isObjectRecord(client)) return undefined;
+	const owner = client[container];
+	if (!isObjectRecord(owner)) return undefined;
+	const candidate = owner[method];
+	if (typeof candidate !== "function") return undefined;
+	const callable = candidate as (...args: unknown[]) => unknown;
+	return async (input: Input) => Reflect.apply(callable, owner, [input]);
+}
+
+/** Requires a non-empty string or fails closed with `invalid-request`. */
+export function requireNonEmptyString(value: unknown, label: string): string {
+	if (typeof value !== "string" || value.length === 0) {
+		throw new HostAdapterError("invalid-request", `${label} must be a non-empty string`);
+	}
+	return value;
+}
+
+/** Requires a positive safe integer or fails closed with `invalid-request`. */
+export function requirePositiveSafeInteger(value: unknown, label: string): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+		throw new HostAdapterError("invalid-request", `${label} must be a positive safe integer`);
+	}
+	return value;
+}

package/src/tui/adapters/index.ts

@@ -0,0 +1,72 @@
+/**
+ * SessionPort V1 TUI host adapters (Phase 4, non-visual lane).
+ *
+ * Public surface for orchestration integration:
+ * - `createSessionReadAdapter(client)` → core `SessionReadPort` backed by
+ *   `context.client.session.list` / `context.client.message.list`.
+ * - `probeSessionImportCapability(client)` → O-12 restore-start capability
+ *   probe (never throws).
+ * - `createSessionImportAdapter(client)` → single-session import adapter that
+ *   always supplies the caller's explicit `{ directory }` target (O-16) and
+ *   fail-closed validates the unwrapped host response before treating an
+ *   import as confirmed (`invalid-response`; see `SessionImportResult`).
+ * - `createProjectDestinationsAdapter(client)` → restore destination
+ *   candidates from `context.client.project.list` as declaration-derived
+ *   `{ projectID, targetDirectory, label }` pairs; the pairs are not
+ *   runtime-verified and require runtime pair validation before restore use
+ *   (OQ-16 stays OPEN).
+ * - `createSessionIdInventory(input)` → bounded metadata-only cross-project
+ *   session-ID inventory over the validated project-list candidates and an
+ *   injected `SessionReadPort` (only `session.list` is called; no message,
+ *   location, or import surface is touched). The returned IDs are occupancy
+ *   evidence only (2026-10-14 owner-approved collision amendment).
+ * - `createLocationResolver(client)` → experimental explicit-directory project
+ *   resolution through `context.client.location.get` with exact, non-blank
+ *   response matching and fail-closed absence/mismatch handling; `location.get`
+ *   may persist project state as one deliberate, bounded side effect (E42;
+ *   OQ-16 stays OPEN).
+ *
+ * All client-facing factories accept the host-provided client as an untrusted
+ * `unknown` value; see `host-client.ts` for the narrow typed boundary, runtime
+ * resolution, and the compile-time assertions against the installed v2.0.22
+ * TUI client declaration. `createSessionIdInventory` resolves no client surface
+ * at all: it consumes the already-validated candidates plus an injected
+ * `SessionReadPort`. No host types are imported at runtime and no host calls
+ * are made by this module.
+ */
+
+export { HostAdapterError } from "./host-client.ts";
+export type {
+	HostAdapterErrorCode,
+	MessageListCallInput,
+	SessionImportCallInput,
+	SessionImportResult,
+	SessionListCallInput,
+} from "./host-client.ts";
+export { createLocationResolver, LocationResolutionError } from "./location-resolver.ts";
+export type {
+	LocationGetCallInput,
+	LocationResolutionErrorCode,
+	LocationResolver,
+	ResolvedProjectLocation,
+	SelectedProjectCandidate,
+} from "./location-resolver.ts";
+export {
+	createProjectDestinationsAdapter,
+	mapProjectListResponse,
+	ProjectDestinationError,
+} from "./project-destinations.ts";
+export type {
+	ProjectDestinationCandidate,
+	ProjectDestinationErrorCode,
+	ProjectDestinationsAdapter,
+} from "./project-destinations.ts";
+export { createSessionIdInventory } from "./session-id-inventory.ts";
+export type {
+	SessionIdInventory,
+	SessionIdInventoryInput,
+	SessionIdInventoryProject,
+} from "./session-id-inventory.ts";
+export { createSessionReadAdapter, mapMessageListRequest, mapSessionListRequest } from "./session-read.ts";
+export { buildSessionImportCall, createSessionImportAdapter, probeSessionImportCapability } from "./session-import.ts";
+export type { SessionImportAdapter, SessionImportProbe, SessionImportRequest } from "./session-import.ts";

package/src/tui/adapters/location-resolver.ts

@@ -0,0 +1,281 @@
+/**
+ * Experimental project-location resolver over the public TUI client
+ * `context.client.location.get` method (Windows-first experimental lane).
+ *
+ * Scope and boundaries (owner decision 2026-10-11, decision-log F):
+ * - `Plugin.Context.location` carries only a directory, so the experimental
+ *   checkpoint path resolves that active directory through public
+ *   `location.get({ location: { directory } })`; restore calls `location.get`
+ *   only for the user-selected candidate (never speculatively, never to
+ *   enumerate candidates).
+ * - Responses are validated fail-closed: the returned `directory`, the
+ *   `project.directory`, and the `project.id` must be present, non-blank, and
+ *   exactly equal to the requested values. Absent/malformed/mismatched
+ *   responses reject before any artifact read, decrypt, write, or import.
+ * - E42 observed that `location.get` can persist/upsert project state in the
+ *   host store; that is a deliberate, bounded side effect of this one explicit
+ *   call per flow (checkpoint: active directory; restore: selected candidate).
+ *   OQ-16 remains OPEN for general/current-project and cross-runtime mapping,
+ *   and no project-ID algorithm, stability, or canonical-path generalization
+ *   is claimed.
+ * - Host/API errors propagate unchanged (never wrapped, retried, or
+ *   swallowed); this module adds no retry and no fallback resolution.
+ *
+ * Method invocation follows the `host-client.ts` resolver convention:
+ * `resolveUnaryMethod` resolves `client.location.get` and invokes it with the
+ * owning `client.location` object preserved as the receiver.
+ *
+ * Evidence boundary: pinned v2.0.22 declaration assertions plus synthetic
+ * fake-client tests only. No live host call is made by this module, and no
+ * cross-version, compatibility, or support claim follows.
+ */
+
+import type { Plugin } from "@opencode/plugin/tui";
+import { isObjectRecord, resolveUnaryMethod } from "./host-client.ts";
+
+/* ------------------------------------------------------------------------- */
+/* Errors                                                                    */
+/* ------------------------------------------------------------------------- */
+
+/** Stable machine-readable failure codes for project-location resolution. */
+export type LocationResolutionErrorCode =
+	/** The installed client does not expose a callable `location.get`. */
+	| "capability-unavailable"
+	/** The caller supplied a blank or missing explicit directory/project ID. */
+	| "invalid-request"
+	/** The host response did not carry the declared fields as non-blank strings. */
+	| "invalid-response"
+	/** The host response did not exactly match the requested directory/project ID. */
+	| "mismatch";
+
+/** Fail-closed resolution error; host API errors are never wrapped in it. */
+export class LocationResolutionError extends Error {
+	readonly code: LocationResolutionErrorCode;
+
+	constructor(code: LocationResolutionErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "LocationResolutionError";
+		this.code = code;
+	}
+}
+
+/* ------------------------------------------------------------------------- */
+/* Narrow client surface (documentation + compile-time assertions)           */
+/* ------------------------------------------------------------------------- */
+
+/** One `location.get` request as sent by this adapter. */
+export interface LocationGetCallInput {
+	readonly location: { readonly directory: string };
+}
+
+/**
+ * Narrow structural view of the public location surface. `location` and `get`
+ * are optional because capability absence is a real runtime state; the factory
+ * fails closed with a clear `LocationResolutionError` when the method is
+ * missing or not callable.
+ */
+export interface LocationGetClientLike {
+	readonly location?: {
+		get?(input: LocationGetCallInput): Promise<unknown>;
+	};
+}
+
+type HostTuiClient = Plugin.Context["client"];
+type AssertTrue<T extends true> = T;
+
+/**
+ * The installed v2.0.22 TUI client must satisfy the narrow `location.get`
+ * surface; if a future pinned declaration drifts, `tsc` fails here instead of
+ * failing at runtime.
+ */
+type _AssertHostLocationGetClientCompatible = AssertTrue<HostTuiClient extends LocationGetClientLike ? true : false>;
+
+/**
+ * The declared `location.get` output must keep exposing the fields this
+ * adapter validates (`directory`, `project.id`, `project.directory`). Drift in
+ * those fields is a compile error, not a silent runtime fallback.
+ */
+type HostLocationGetOutput = Awaited<ReturnType<HostTuiClient["location"]["get"]>>;
+type _AssertHostLocationGetOutputHasFields = AssertTrue<
+	HostLocationGetOutput extends {
+		readonly directory: string;
+		readonly project: { readonly id: string; readonly directory: string };
+	}
+		? true
+		: false
+>;
+
+/* ------------------------------------------------------------------------- */
+/* Public types                                                              */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * One exact, verified project location. `directory` is the requested directory
+ * that the host response confirmed verbatim; `projectID` is the host-returned
+ * project ID (for the selected-candidate flow it is also required to equal the
+ * candidate's declared project ID).
+ */
+export interface ResolvedProjectLocation {
+	readonly projectID: string;
+	readonly directory: string;
+}
+
+/** One selected destination candidate to verify against the host. */
+export interface SelectedProjectCandidate {
+	readonly projectID: string;
+	readonly targetDirectory: string;
+}
+
+/** Location-resolution surface. One `location.get` call per resolution; no caching. */
+export interface LocationResolver {
+	/**
+	 * Resolves the active project for an explicit directory via
+	 * `location.get({ location: { directory } })`. Requires the response
+	 * `directory` and `project.directory` to equal the requested directory and
+	 * `project.id` to be a non-blank string.
+	 */
+	resolveActiveProject(directory: string): Promise<ResolvedProjectLocation>;
+
+	/**
+	 * Resolves one user-selected candidate via
+	 * `location.get({ location: { directory: candidate.targetDirectory } })`.
+	 * Requires the response `directory` and `project.directory` to equal the
+	 * candidate directory and `project.id` to equal the candidate project ID.
+	 */
+	resolveSelectedProject(candidate: SelectedProjectCandidate): Promise<ResolvedProjectLocation>;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Factory                                                                   */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Creates the location resolver. Fails closed with
+ * `LocationResolutionError` (`capability-unavailable`) when `location.get` is
+ * absent or not callable, before any host call.
+ */
+export function createLocationResolver(client: unknown): LocationResolver {
+	const locationGet = resolveUnaryMethod<LocationGetCallInput>(client, "location", "get");
+	if (locationGet === undefined) {
+		throw new LocationResolutionError(
+			"capability-unavailable",
+			"The installed TUI client does not expose a callable location.get; cannot resolve a project",
+		);
+	}
+	return {
+		async resolveActiveProject(directory: string): Promise<ResolvedProjectLocation> {
+			const requestedDirectory = requireExplicitDirectory(directory, "active project directory");
+			const response = await locationGet({ location: { directory: requestedDirectory } });
+			return validateResolution(response, requestedDirectory, undefined);
+		},
+		async resolveSelectedProject(candidate: SelectedProjectCandidate): Promise<ResolvedProjectLocation> {
+			if (!isObjectRecord(candidate)) {
+				throw new LocationResolutionError(
+					"invalid-request",
+					"resolveSelectedProject requires a candidate object with projectID and targetDirectory",
+				);
+			}
+			const requestedProjectID = requireNonBlankString(candidate.projectID, "candidate project ID");
+			const requestedDirectory = requireExplicitDirectory(candidate.targetDirectory, "candidate target directory");
+			const response = await locationGet({ location: { directory: requestedDirectory } });
+			return validateResolution(response, requestedDirectory, requestedProjectID);
+		},
+	};
+}
+
+/* ------------------------------------------------------------------------- */
+/* Response validation (fail closed, no data in error messages)              */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Validates one `location.get` response against the requested directory and,
+ * for the selected-candidate flow, the requested project ID. Returns only
+ * exactly verified values; any absence, malformed field, or mismatch rejects.
+ * Error messages carry field labels and value types only — never directory
+ * paths, project IDs, or raw host data.
+ */
+function validateResolution(
+	response: unknown,
+	requestedDirectory: string,
+	expectedProjectID: string | undefined,
+): ResolvedProjectLocation {
+	if (!isObjectRecord(response)) {
+		throw new LocationResolutionError(
+			"invalid-response",
+			`location.get did not return an object; received ${describeValue(response)}`,
+		);
+	}
+	const responseDirectory = response["directory"];
+	if (typeof responseDirectory !== "string" || responseDirectory.trim().length === 0) {
+		throw new LocationResolutionError(
+			"invalid-response",
+			`location.get response must carry a non-blank string directory; received ${describeValue(responseDirectory)}`,
+		);
+	}
+	if (responseDirectory !== requestedDirectory) {
+		throw new LocationResolutionError(
+			"mismatch",
+			"location.get returned a directory that does not exactly match the requested directory",
+		);
+	}
+	const project = response["project"];
+	if (!isObjectRecord(project)) {
+		throw new LocationResolutionError(
+			"invalid-response",
+			`location.get response must carry a project object; received ${describeValue(project)}`,
+		);
+	}
+	const projectID = project["id"];
+	if (typeof projectID !== "string" || projectID.trim().length === 0) {
+		throw new LocationResolutionError(
+			"invalid-response",
+			`location.get response project must carry a non-blank string id; received ${describeValue(projectID)}`,
+		);
+	}
+	if (expectedProjectID !== undefined && projectID !== expectedProjectID) {
+		throw new LocationResolutionError(
+			"mismatch",
+			"location.get returned a project ID that does not exactly match the selected candidate",
+		);
+	}
+	const projectDirectory = project["directory"];
+	if (typeof projectDirectory !== "string" || projectDirectory.trim().length === 0) {
+		throw new LocationResolutionError(
+			"invalid-response",
+			`location.get response project must carry a non-blank string directory; received ${describeValue(projectDirectory)}`,
+		);
+	}
+	if (projectDirectory !== requestedDirectory) {
+		throw new LocationResolutionError(
+			"mismatch",
+			"location.get returned a project directory that does not exactly match the requested directory",
+		);
+	}
+	return { projectID, directory: requestedDirectory };
+}
+
+/** Requires an explicit non-blank directory; the value is returned verbatim. */
+function requireExplicitDirectory(value: unknown, label: string): string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new LocationResolutionError(
+			"invalid-request",
+			`${label} must be an explicit non-blank string; no default is applied`,
+		);
+	}
+	return value;
+}
+
+/** Requires a non-blank string; the value is returned verbatim (never trimmed). */
+function requireNonBlankString(value: unknown, label: string): string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new LocationResolutionError("invalid-request", `${label} must be a non-blank string`);
+	}
+	return value;
+}
+
+/** Type-only description for error messages; never includes the value itself. */
+function describeValue(value: unknown): string {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}