opencode-session-port 0.0.0-stage → 0.1.0

package/src/tui/adapters/project-destinations.ts

@@ -0,0 +1,271 @@
+/**
+ * Host project-destinations adapter: lists candidate restore destinations from
+ * the public TUI client `context.client.project.list` method.
+ *
+ * Candidates are declaration/source-derived, not runtime-verified (OQ-16 stays
+ * OPEN). Each candidate pairs the declared `Project.id` with the declared
+ * `Project.canonical` path proposed as the import `targetDirectory`. The pinned
+ * v2.0.22 declaration/source research (`lib-31`) describes `canonical` as an
+ * absolute stored/main-checkout path that may be another clone and is NOT
+ * guaranteed to be current, existing, unique, or to map back to the listed
+ * project ID when used as a `session.import.location.directory` target. This
+ * adapter therefore makes no canonical→ID mapping claim and never asserts the
+ * pair is valid: callers MUST runtime-validate the selected
+ * `{ projectID, targetDirectory }` pair before restore use and fail closed
+ * whenever the pair cannot be resolved unambiguously.
+ *
+ * Scope and data rules:
+ * - Returns destination candidates only; no restore or import behavior.
+ * - Reads only `Project.id`, `Project.canonical`, and `Project.name`.
+ *   `Project.sandboxes`, artifact fields, and any source project/location
+ *   field are never read or returned.
+ * - Paths are never normalized, resolved, joined, or trimmed: `canonical` is
+ *   carried verbatim into `targetDirectory`, and blank values fail closed.
+ * - `label` is `name` when it is a non-blank string, otherwise the verbatim
+ *   `canonical` path, so the label is always non-empty.
+ *
+ * Fail-closed behavior (invalid entries are never silently skipped):
+ * - missing or non-callable `project.list` → `HostAdapterError`
+ *   (`capability-unavailable`) before any host call, matching the other host
+ *   adapters;
+ * - non-array responses, non-object records, missing/blank/non-string `id` or
+ *   `canonical`, and non-string `name` values → `ProjectDestinationError`
+ *   (`invalid-response`);
+ * - conflicting `projectID` ↔ `targetDirectory` pairs (one ID mapping to
+ *   different paths, one path mapping to different IDs, or a repeated pair
+ *   with different labels) → `ProjectDestinationError` (`invalid-response`);
+ *   only entries that are unambiguously identical (same ID, same canonical,
+ *   same label) are deduplicated.
+ * - Error messages carry only record positions/counts and value types, never
+ *   project IDs, paths, or names.
+ *
+ * Method invocation follows the `host-client.ts` resolver convention:
+ * `resolveUnaryMethod` resolves `client.project.list` and invokes it with the
+ * owning `client.project` object preserved as the receiver via `Reflect.apply`.
+ * `project.list` takes no required argument; the pinned declaration types its
+ * only parameter as optional (`requestOptions?`), so the resolver's single
+ * `undefined` argument is declaration-equivalent to `client.project.list()`.
+ * Host/API rejections propagate unchanged; this adapter never wraps, retries,
+ * or swallows them.
+ *
+ * Evidence boundary: pinned v2.0.22 declaration/source research (`lib-31`) and
+ * synthetic fake-client tests only. This module makes no live host call and no
+ * cross-version, mapping, compatibility, or support claim follows from it.
+ */
+
+import type { Plugin } from "@opencode/plugin/tui";
+import { HostAdapterError, isObjectRecord, resolveUnaryMethod } from "./host-client.ts";
+
+/* ------------------------------------------------------------------------- */
+/* Errors                                                                    */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Stable machine-readable failure code for project-list response validation.
+ * Capability absence reuses `HostAdapterError("capability-unavailable")`;
+ * this code covers a response that violated the declared `Project` record
+ * shape or contained an ambiguous `projectID` ↔ `canonical` pair. The shared
+ * `HostAdapterErrorCode` also includes `invalid-response` for other boundaries,
+ * but this module retains its specific `ProjectDestinationError` type and
+ * taxonomy for project-list failures.
+ */
+export type ProjectDestinationErrorCode = "invalid-response";
+
+/** Fail-closed project-list response error; host API errors are never wrapped in it. */
+export class ProjectDestinationError extends Error {
+	readonly code: ProjectDestinationErrorCode;
+
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "ProjectDestinationError";
+		this.code = "invalid-response";
+	}
+}
+
+/* ------------------------------------------------------------------------- */
+/* Narrow client surface (documentation + compile-time assertions)           */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Narrow structural view of the public project surface used for destination
+ * enumeration. `project` and `list` are optional because capability absence is
+ * a real runtime state; the factory fails closed with a clear
+ * `HostAdapterError` when the method is missing or not callable.
+ */
+export interface ProjectListClientLike {
+	readonly project?: {
+		list?(): Promise<unknown>;
+	};
+}
+
+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 project-list surface; if a future pinned declaration drifts,
+ * `tsc` fails here instead of failing at runtime.
+ */
+type _AssertHostProjectListClientCompatible = AssertTrue<HostTuiClient extends ProjectListClientLike ? true : false>;
+
+/**
+ * The declared `project.list` output must keep exposing the candidate source
+ * fields (`id`, `canonical`, optional `name`) this adapter maps from. Drift in
+ * those fields is a compile error, not a silent runtime fallback.
+ */
+type HostProjectListOutput = Awaited<ReturnType<HostTuiClient["project"]["list"]>>;
+type _AssertHostProjectListOutputHasCandidateFields = AssertTrue<
+	HostProjectListOutput extends readonly { readonly id: string; readonly canonical: string; readonly name?: string }[]
+		? true
+		: false
+>;
+
+/* ------------------------------------------------------------------------- */
+/* Public types                                                              */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * One destination candidate. `projectID` and `targetDirectory` are the
+ * declaration-derived proposed pair (`Project.id` / `Project.canonical`);
+ * `targetDirectory` is verbatim, never normalized. The pair requires runtime
+ * validation before restore use — see the module header (OQ-16 OPEN).
+ */
+export interface ProjectDestinationCandidate {
+	readonly projectID: string;
+	/** `Project.canonical`, verbatim, proposed as the explicit import target. */
+	readonly targetDirectory: string;
+	/** Non-empty display label: `Project.name` when non-blank, else `canonical`. */
+	readonly label: string;
+}
+
+/** Destination-candidate listing surface. One call per selection flow; no caching. */
+export interface ProjectDestinationsAdapter {
+	/**
+	 * Calls the public `project.list` once and maps the response to candidates.
+	 * Rejects with `HostAdapterError` (`capability-unavailable`) only when the
+	 * method is unavailable (checked at construction), with
+	 * `ProjectDestinationError` (`invalid-response`) for malformed/ambiguous
+	 * responses, and with the unchanged host error for host rejections.
+	 */
+	listDestinations(): Promise<readonly ProjectDestinationCandidate[]>;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Factory                                                                   */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Creates the destination-candidates adapter. Fails closed with
+ * `HostAdapterError` (`capability-unavailable`) when `project.list` is absent
+ * or not callable, before any host call.
+ */
+export function createProjectDestinationsAdapter(client: unknown): ProjectDestinationsAdapter {
+	const projectList = resolveUnaryMethod<undefined>(client, "project", "list");
+	if (projectList === undefined) {
+		throw new HostAdapterError(
+			"capability-unavailable",
+			"The installed TUI client does not expose a callable project.list; cannot enumerate destination candidates",
+		);
+	}
+	return {
+		async listDestinations(): Promise<readonly ProjectDestinationCandidate[]> {
+			// The resolver always applies exactly one argument; the pinned
+			// declaration's only parameter is optional, so `undefined` is the
+			// declaration-equivalent of calling `client.project.list()`.
+			const response = await projectList(undefined);
+			return mapProjectListResponse(response);
+		},
+	};
+}
+
+/* ------------------------------------------------------------------------- */
+/* Response mapping (fail closed, no silent skips)                           */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Maps a raw `project.list` response to destination candidates.
+ *
+ * Strict and fail-closed: any non-array response or any malformed record
+ * rejects the entire list (no filtering, no partial results). Duplicate
+ * entries are collapsed only when unambiguously identical; every other
+ * repeated `projectID` or `canonical` value rejects as an ambiguous pair.
+ * Error messages never embed project data (only positions, counts, types).
+ */
+export function mapProjectListResponse(response: unknown): readonly ProjectDestinationCandidate[] {
+	if (!Array.isArray(response)) {
+		throw new ProjectDestinationError(
+			`project.list response must be an array of project records; received ${describeValue(response)}`,
+		);
+	}
+	const total = response.length;
+	const candidates: ProjectDestinationCandidate[] = [];
+	const byProjectID = new Map<string, ProjectDestinationCandidate>();
+	const byTargetDirectory = new Map<string, ProjectDestinationCandidate>();
+
+	for (let index = 0; index < total; index += 1) {
+		const candidate = parseProjectRecord(response[index], index, total);
+		const knownByProjectID = byProjectID.get(candidate.projectID);
+		const knownByTargetDirectory = byTargetDirectory.get(candidate.targetDirectory);
+		if (knownByProjectID !== undefined || knownByTargetDirectory !== undefined) {
+			// Deduplicate only an unambiguously identical entry: both lookups
+			// must resolve to the same previously accepted candidate and every
+			// candidate field must match. Anything else is a conflicting pair.
+			const isExactDuplicate =
+				knownByProjectID !== undefined &&
+				knownByProjectID === knownByTargetDirectory &&
+				candidate.projectID === knownByProjectID.projectID &&
+				candidate.targetDirectory === knownByProjectID.targetDirectory &&
+				candidate.label === knownByProjectID.label;
+			if (isExactDuplicate) continue;
+			throw new ProjectDestinationError(
+				`project.list record ${index + 1} of ${total} conflicts with an earlier project ID/canonical directory pair; refusing to guess a destination`,
+			);
+		}
+		byProjectID.set(candidate.projectID, candidate);
+		byTargetDirectory.set(candidate.targetDirectory, candidate);
+		candidates.push(candidate);
+	}
+	return candidates;
+}
+
+/**
+ * Validates one `Project` record against the fields this adapter reads and
+ * builds a candidate. `id` and `canonical` must be non-blank strings and are
+ * carried verbatim (blankness is checked with `trim`, the value is never
+ * trimmed or normalized). `name` must be absent or a string; a non-blank
+ * string is the label, otherwise the label falls back to `canonical`.
+ */
+function parseProjectRecord(raw: unknown, index: number, total: number): ProjectDestinationCandidate {
+	const position = `project.list record ${index + 1} of ${total}`;
+	if (!isObjectRecord(raw)) {
+		throw new ProjectDestinationError(`${position} must be an object; received ${describeValue(raw)}`);
+	}
+	const projectID = requireResponseString(raw["id"], "id", position);
+	const targetDirectory = requireResponseString(raw["canonical"], "canonical", position);
+	const rawName = raw["name"];
+	if (rawName === undefined) {
+		return { projectID, targetDirectory, label: targetDirectory };
+	}
+	if (typeof rawName !== "string") {
+		throw new ProjectDestinationError(`${position} has a non-string name; received ${describeValue(rawName)}`);
+	}
+	const label = rawName.trim().length > 0 ? rawName : targetDirectory;
+	return { projectID, targetDirectory, label };
+}
+
+/** Requires a non-blank string field or fails closed; the value is returned verbatim. */
+function requireResponseString(value: unknown, field: string, position: string): string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new ProjectDestinationError(
+			`${position} must carry a non-blank string ${field}; received ${describeValue(value)}`,
+		);
+	}
+	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;
+}

package/src/tui/adapters/session-id-inventory.ts

@@ -0,0 +1,378 @@
+/**
+ * Bounded, metadata-only cross-project session-ID inventory (2026-10-14
+ * owner-approved collision amendment).
+ *
+ * `createSessionIdInventory` builds one bounded read-only scan over the
+ * already-validated project list and an injected core `SessionReadPort`
+ * (`session.list` through the public client surface). It returns the session
+ * IDs the API reports as visible, without reading any message, without
+ * retaining any record content, and without any host call beyond
+ * `session.list`.
+ *
+ * Inputs are explicit and injected; no client surface is resolved here:
+ * - `projects` — the validated `project.list` candidates from the restore
+ *   selection flow (`ProjectDestinationCandidate` satisfies the structural
+ *   `SessionIdInventoryProject` view). Their `projectID`s scope the scan in
+ *   candidate order.
+ * - `selectedProjectID` — the resolved destination project. It is always
+ *   included in the scan; when the candidates omit it, it is appended rather
+ *   than silently ignored. Duplicate project IDs in the inventory fail closed.
+ * - `policy` — the existing `SessionCollectionPolicy`. Only `sessionPageSize`
+ *   (per-request page size) and `maxSessions` (aggregate ceiling across every
+ *   project and page) are applied; no new numeric default or cap is invented,
+ *   and the message limits are unused because no message is ever read.
+ *
+ * Scan semantics mirror the core collector's known page handling without
+ * modifying it (the collector stays untouched):
+ * - per project, `listSessions({ project, limit })` then
+ *   `listSessions({ project, limit, cursor })`, following `cursor.next` until
+ *   it is absent/null;
+ * - each item must snapshot to a JSON-stable object carrying a non-empty
+ *   string `id` and a `projectID` exactly equal to the requested project;
+ * - any malformed page/item/id/scope, duplicate session ID anywhere in the
+ *   scan, repeated cursor, empty page carrying a next cursor, aggregate
+ *   overflow, or API failure rejects the whole inventory with the collector's
+ *   existing `SessionCollectionError` codes (`invalid-request`,
+ *   `invalid-policy`, `session-list-failed`, `malformed-session-page`,
+ *   `malformed-session-record`, `session-project-mismatch`,
+ *   `duplicate-session-id`, `repeated-session-cursor`,
+ *   `session-limit-exceeded`). No partial ID list is ever returned.
+ *
+ * Data rules: only `info.id` and `info.projectID` are read from each record;
+ * the record is snapshotted solely to fail closed on non-JSON values and is
+ * never retained. Messages are never requested (`listMessages` is never
+ * called), no `message.list`/`location.get`/`project.list`/import call is made
+ * — the inventory takes an injected read port, not a client — and no project
+ * location side effect is possible.
+ *
+ * Snapshot/concurrency limitations (O-21/OQ-23 stay OPEN): the upstream list
+ * APIs document no snapshot consistency. This scan is a best-effort sequence
+ * of live page reads, not an atomic cross-project snapshot; sessions created,
+ * deleted, or renamed while it runs may be missed or stale, and the result is
+ * only the inventory the API returned during this scan. There is no
+ * completeness guarantee beyond that, no retry/re-read policy, and no claim
+ * that the ID set is point-in-time consistent across projects.
+ *
+ * Evidence boundary: synthetic fake-port tests only; no live host call,
+ * filesystem, crypto, or import is performed, and no runtime or compatibility
+ * claim follows.
+ */
+
+import { snapshotJsonValue, type JsonObject, type JsonValue } from "../../core/contracts/index.ts";
+import {
+	SessionCollectionError,
+	validateSessionCollectionPolicy,
+	type SessionCollectionPolicy,
+	type SessionListPageRequest,
+	type SessionReadPort,
+} from "../../core/sessions/index.ts";
+import { isObjectRecord } from "./host-client.ts";
+
+/* ------------------------------------------------------------------------- */
+/* Public types                                                              */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Structural view of one already-validated project-list candidate. Only the
+ * project ID is used; `ProjectDestinationCandidate` (which also carries the
+ * proposed `targetDirectory` and `label`) satisfies this view without being
+ * re-derived or re-validated here.
+ */
+export interface SessionIdInventoryProject {
+	/** Non-blank project ID from the validated `project.list` candidate set. */
+	readonly projectID: string;
+}
+
+/** Explicit, fully injected inventory dependencies. Every field is required; no defaults exist. */
+export interface SessionIdInventoryInput {
+	/** Injected core read port; only `listSessions` is ever called. */
+	readonly readPort: SessionReadPort;
+	/**
+	 * Validated project-list candidates whose project IDs scope the scan, in
+	 * candidate order. Malformed or duplicate entries fail closed.
+	 */
+	readonly projects: readonly SessionIdInventoryProject[];
+	/**
+	 * Resolved selected destination project; always included in the scan even
+	 * when the candidates omit it (it is appended, never silently ignored).
+	 */
+	readonly selectedProjectID: string;
+	/** Explicit collection policy; only `sessionPageSize` and `maxSessions` are applied. */
+	readonly policy: SessionCollectionPolicy;
+}
+
+/** One bounded metadata-only cross-project session-ID inventory surface. */
+export interface SessionIdInventory {
+	/**
+	 * Performs one scan and resolves with every session ID the API returned,
+	 * each exactly once, in deterministic project/page order. Rejects with a
+	 * `SessionCollectionError` (collector codes) without returning any partial
+	 * list; see the module header for the exact fail-closed rules and the
+	 * documented snapshot/concurrency limitations.
+	 */
+	readGloballyVisibleSessionIDs(): Promise<readonly string[]>;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Factory                                                                   */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Creates the metadata-only inventory. All inputs are validated fail-closed
+ * here, before any host call: a malformed/duplicate project inventory throws
+ * `SessionCollectionError("invalid-request")`, an invalid policy throws
+ * `SessionCollectionError("invalid-policy")` through the shared core
+ * validator, and a port without a callable `listSessions` throws
+ * `invalid-request`.
+ */
+export function createSessionIdInventory(input: SessionIdInventoryInput): SessionIdInventory {
+	if (!isObjectRecord(input)) {
+		throw new SessionCollectionError(
+			"invalid-request",
+			"createSessionIdInventory requires an input object with readPort, projects, selectedProjectID, and policy",
+		);
+	}
+	const readPort = input.readPort;
+	if (!isObjectRecord(readPort) || typeof readPort.listSessions !== "function") {
+		throw new SessionCollectionError(
+			"invalid-request",
+			"SessionIdInventory requires an injected SessionReadPort with a callable listSessions",
+		);
+	}
+	validateSessionCollectionPolicy(input.policy);
+	const projectIDs = resolveInventoryProjects(input.projects, input.selectedProjectID);
+	const policy = input.policy;
+
+	return {
+		async readGloballyVisibleSessionIDs(): Promise<readonly string[]> {
+			const sessionIDs: string[] = [];
+			const seenSessionIDs = new Set<string>();
+			for (const projectID of projectIDs) {
+				await collectProjectSessionIDs(readPort, projectID, policy, sessionIDs, seenSessionIDs);
+			}
+			return sessionIDs;
+		},
+	};
+}
+
+/* ------------------------------------------------------------------------- */
+/* Project-inventory validation (fail closed, no silent skips)               */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Validates the project inventory and returns the deterministic scan order:
+ * candidate project IDs verbatim in candidate order, then the selected
+ * project ID appended when it is not already present. Malformed entries,
+ * blank IDs, and any duplicate project ID reject the whole inventory before
+ * any host call.
+ */
+function resolveInventoryProjects(projects: unknown, selectedProjectID: unknown): readonly string[] {
+	if (!Array.isArray(projects)) {
+		throw new SessionCollectionError(
+			"invalid-request",
+			"SessionIdInventory projects must be an array of validated project candidates",
+		);
+	}
+	const projectIDs: string[] = [];
+	const seenProjectIDs = new Set<string>();
+	for (let index = 0; index < projects.length; index += 1) {
+		const entry: unknown = projects[index];
+		if (!isObjectRecord(entry)) {
+			throw new SessionCollectionError(
+				"invalid-request",
+				`SessionIdInventory projects[${index}] must be an object with a projectID`,
+			);
+		}
+		const projectID = entry["projectID"];
+		if (typeof projectID !== "string" || projectID.trim().length === 0) {
+			throw new SessionCollectionError(
+				"invalid-request",
+				`SessionIdInventory projects[${index}].projectID must be a non-blank string`,
+			);
+		}
+		if (seenProjectIDs.has(projectID)) {
+			throw new SessionCollectionError(
+				"invalid-request",
+				`SessionIdInventory project inventory repeats project id ${JSON.stringify(projectID)}; refusing an ambiguous scope`,
+			);
+		}
+		seenProjectIDs.add(projectID);
+		projectIDs.push(projectID);
+	}
+	if (typeof selectedProjectID !== "string" || selectedProjectID.trim().length === 0) {
+		throw new SessionCollectionError(
+			"invalid-request",
+			"SessionIdInventory requires an explicit non-blank selectedProjectID",
+		);
+	}
+	if (!seenProjectIDs.has(selectedProjectID)) {
+		projectIDs.push(selectedProjectID);
+	}
+	return projectIDs;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Per-project pagination (collector page semantics, metadata only)          */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Pages one project's session list to exhaustion and appends each newly seen
+ * session ID to the shared aggregate list. The aggregate `seenSessionIDs`
+ * set spans every project, so a duplicate ID anywhere in the scan fails
+ * closed; `sessionIDs.length` is the aggregate ceiling counter checked
+ * against `policy.maxSessions`.
+ */
+async function collectProjectSessionIDs(
+	readPort: SessionReadPort,
+	projectID: string,
+	policy: SessionCollectionPolicy,
+	sessionIDs: string[],
+	seenSessionIDs: Set<string>,
+): Promise<void> {
+	const usedCursors = new Set<string>();
+	let cursor: string | undefined;
+
+	for (;;) {
+		const pageRequest: SessionListPageRequest =
+			cursor === undefined
+				? { project: projectID, limit: policy.sessionPageSize }
+				: { project: projectID, limit: policy.sessionPageSize, cursor };
+		const label = `Session metadata inventory for project ${JSON.stringify(projectID)}`;
+		const rawPage = await callPort(
+			() => readPort.listSessions(pageRequest),
+			"session-list-failed",
+			`${label} request failed`,
+		);
+		const page = parsePageEnvelope(rawPage, "malformed-session-page", `${label} response`);
+
+		for (const rawSession of page.items) {
+			const info = snapshotJsonRecord(rawSession, "malformed-session-record", `${label} item ${sessionIDs.length}`);
+			const id = info["id"];
+			if (typeof id !== "string" || id.length === 0) {
+				throw new SessionCollectionError(
+					"malformed-session-record",
+					`${label} returned an item without a non-empty string id`,
+				);
+			}
+			const boundProjectID = info["projectID"];
+			if (typeof boundProjectID !== "string" || boundProjectID !== projectID) {
+				throw new SessionCollectionError(
+					"session-project-mismatch",
+					`${label} returned session ${JSON.stringify(id)} with ${
+						boundProjectID === undefined ? "no projectID" : `projectID ${JSON.stringify(boundProjectID)}`
+					}; refusing to include a session outside the requested project scope`,
+				);
+			}
+			if (seenSessionIDs.has(id)) {
+				throw new SessionCollectionError(
+					"duplicate-session-id",
+					`${label} returned session id ${JSON.stringify(id)} more than once across the inventory; refusing to continue`,
+				);
+			}
+			if (sessionIDs.length >= policy.maxSessions) {
+				throw new SessionCollectionError(
+					"session-limit-exceeded",
+					`Session metadata inventory exceeded SessionCollectionPolicy.maxSessions=${policy.maxSessions}; refusing to return a partial inventory`,
+				);
+			}
+			seenSessionIDs.add(id);
+			sessionIDs.push(id);
+		}
+
+		if (page.next === undefined) break;
+		if (usedCursors.has(page.next)) {
+			throw new SessionCollectionError(
+				"repeated-session-cursor",
+				`${label} returned a cursor that was already used: ${JSON.stringify(page.next)}; refusing to loop`,
+			);
+		}
+		usedCursors.add(page.next);
+		cursor = page.next;
+	}
+}
+
+/* ------------------------------------------------------------------------- */
+/* Shared page/record semantics (mirrors the core collector)                 */
+/* ------------------------------------------------------------------------- */
+
+interface ParsedPage {
+	readonly items: readonly unknown[];
+	/** `cursor.next` when present and non-null; `undefined` means the page sequence is complete. */
+	readonly next: string | undefined;
+}
+
+/**
+ * Validates the untrusted `{ data, cursor }` envelope with the same semantics
+ * the core collector uses: a non-object response, a missing `data` array, a
+ * non-object `cursor`, a non-string/blank `cursor.next`, or an empty page
+ * carrying a next cursor all fail closed.
+ */
+function parsePageEnvelope(value: unknown, code: "malformed-session-page", label: string): ParsedPage {
+	if (!isObjectRecord(value)) {
+		throw new SessionCollectionError(code, `${label} was not an object`);
+	}
+	const data = value["data"];
+	if (!Array.isArray(data)) {
+		throw new SessionCollectionError(code, `${label} did not contain a data array`);
+	}
+
+	let next: string | undefined;
+	const cursor = value["cursor"];
+	if (cursor !== undefined && cursor !== null) {
+		if (!isObjectRecord(cursor)) {
+			throw new SessionCollectionError(code, `${label} cursor was not an object`);
+		}
+		const rawNext = cursor["next"];
+		if (rawNext !== undefined && rawNext !== null) {
+			if (typeof rawNext !== "string" || rawNext.length === 0) {
+				throw new SessionCollectionError(code, `${label} cursor.next was not a non-empty string or null`);
+			}
+			next = rawNext;
+		}
+	}
+
+	if (next !== undefined && data.length === 0) {
+		throw new SessionCollectionError(
+			code,
+			`${label} returned no items with a next cursor; refusing to guess at an unbounded page sequence`,
+		);
+	}
+
+	return { items: data, next };
+}
+
+/** Copies one API record into a detached JSON-only object, rejecting anything JSON would omit or coerce. */
+function snapshotJsonRecord(value: unknown, code: "malformed-session-record", label: string): JsonObject {
+	if (!isObjectRecord(value)) {
+		throw new SessionCollectionError(code, `${label} was not an object`);
+	}
+	let snapshot: JsonValue;
+	try {
+		snapshot = snapshotJsonValue(value, label);
+	} catch (cause) {
+		throw new SessionCollectionError(code, `${label} is not JSON-stable: ${errorText(cause)}`, { cause });
+	}
+	if (!isObjectRecord(snapshot)) {
+		throw new SessionCollectionError(code, `${label} did not snapshot to an object`);
+	}
+	return snapshot as JsonObject;
+}
+
+/** Awaits one port call and converts non-collection failures into a coded error while preserving the cause. */
+async function callPort(
+	call: () => Promise<unknown>,
+	code: "session-list-failed",
+	label: string,
+): Promise<unknown> {
+	try {
+		return await call();
+	} catch (cause) {
+		if (cause instanceof SessionCollectionError) throw cause;
+		throw new SessionCollectionError(code, `${label}: ${errorText(cause)}`, { cause });
+	}
+}
+
+/** Best-effort message text for wrapping a caught `unknown` value. */
+function errorText(value: unknown): string {
+	return value instanceof Error ? value.message : String(value);
+}