opencode-session-port 0.0.0-stage → 0.1.1

package/src/core/sessions/collector.ts

@@ -0,0 +1,323 @@
+import {
+	snapshotJsonValue,
+	type CheckpointPayload,
+	type JsonObject,
+	type JsonValue,
+	type SessionRecord,
+} from "../contracts/index.ts";
+import { SessionCollectionError, type SessionCollectionErrorCode } from "./errors.ts";
+import { errorText, isJsonObject } from "./guards.ts";
+import { validateSessionCollectionPolicy, type SessionCollectionPolicy } from "./policy.ts";
+import type { MessageListPageRequest, SessionListPageRequest, SessionReadPort } from "./port.ts";
+import { findUnsettledMessageReason } from "./unsettled.ts";
+
+/** Input for one checkpoint payload collection. The project and every bound are explicit. */
+export interface CollectCheckpointPayloadRequest {
+	/** Explicit project scope; current-project resolution is out of scope (OQ-10). */
+	readonly projectID: string;
+	/** Explicit local limits; no defaults are applied. */
+	readonly policy: SessionCollectionPolicy;
+}
+
+/**
+ * Collects a complete `CheckpointPayload` for one explicit project by paging
+ * the session list and each session's message list to exhaustion.
+ *
+ * Behavior (v2.0.22 declarations/source research, E13–E15):
+ * - Follows `cursor.next` until it is absent or `null`; page size always comes
+ *   from the explicit policy.
+ * - Includes every session the API returns. Archived sessions are not
+ *   filtered and child links are not inferred; child-association semantics and
+ *   legacy fork semantics remain OPEN (OQ-10).
+ * - First message page requests `order: "asc"`; subsequent pages pass only the
+ *   opaque cursor (the API cannot combine `order` with `cursor`). No `type`
+ *   filter is ever sent, and `session.export` is never used because it drops
+ *   unsettled entries silently (E15).
+ * - Every item is validated into a detached JSON-only snapshot via the shared
+ *   `snapshotJsonValue` contract; opaque `info`/message fields and all
+ *   IDs/references are preserved unchanged (no canonicalization or remapping
+ *   here — O-04/O-05 are OPEN).
+ * - Returned sessions are bound to the requested scope fail-closed: every
+ *   session from the list must carry a present `projectID` exactly equal to
+ *   the requested project; missing or mismatched values reject the whole
+ *   collection and out-of-scope sessions are neither filtered out nor
+ *   included.
+ * - Message association is endpoint-scoped instead of per-record: the
+ *   collector addresses each session's messages through
+ *   `listMessages(sessionID, ...)`, and the v2.0.22 route
+ *   `GET /api/session/:sessionID/message` scopes returned records to that path
+ *   session. v2.0.22 `Session.Message.Info` carries no per-message
+ *   `sessionID` (its common Base is `id`/metadata/`time`), so each message
+ *   record cannot independently assert its owning session. This collector
+ *   therefore does not require, validate, normalize, or invent a per-message
+ *   `sessionID`; message records are retained verbatim and unknown fields
+ *   (including any future `sessionID`-shaped field) stay opaque.
+ * - The `maxTotalMessages` bound spans every session and every message page:
+ *   before a page is accumulated, the number already collected plus that whole
+ *   page must not exceed the bound, or the entire collection fails with
+ *   `total-message-limit-exceeded`. A page that would push the collection over
+ *   the bound is rejected, never truncated.
+ * - Any unsettled message (assistant without `time.completed`; running
+ *   shell/compaction), duplicate session/message id, repeated cursor, API
+ *   failure, malformed page/record, session scope-binding violation (missing
+ *   or mismatched session `projectID`), or exceeded bound fails the whole
+ *   collection. It never returns a partial payload or truncated history.
+ *
+ * Caveat (O-21 / OQ-23): the upstream list APIs document no snapshot
+ * consistency, so this is a best-effort page sequence, not an atomic snapshot,
+ * and it defines no retry policy. This function is one step of a checkpoint,
+ * not a complete checkpoint transaction; compression, encryption, and artifact
+ * writing are separate concerns.
+ */
+export async function collectCheckpointPayload(
+	port: SessionReadPort,
+	input: CollectCheckpointPayloadRequest,
+): Promise<CheckpointPayload> {
+	if (!isJsonObject(input)) {
+		throw new SessionCollectionError(
+			"invalid-request",
+			"collectCheckpointPayload requires an input object with an explicit projectID and SessionCollectionPolicy",
+		);
+	}
+	if (typeof port?.listSessions !== "function" || typeof port?.listMessages !== "function") {
+		throw new SessionCollectionError("invalid-request", "SessionReadPort must provide listSessions and listMessages");
+	}
+	validateSessionCollectionPolicy(input.policy);
+	const projectID = input.projectID;
+	if (typeof projectID !== "string" || projectID.length === 0) {
+		throw new SessionCollectionError(
+			"invalid-request",
+			"collectCheckpointPayload requires an explicit non-empty projectID string; current-project resolution is out of scope (OQ-10)",
+		);
+	}
+
+	const sessions: SessionRecord[] = [];
+	const sessionIds = new Set<string>();
+	const usedSessionCursors = new Set<string>();
+	let sessionCursor: string | undefined;
+	/** Messages accumulated across every session and page so far; enforced against `maxTotalMessages`. */
+	let collectedMessageCount = 0;
+
+	for (;;) {
+		const pageRequest: SessionListPageRequest =
+			sessionCursor === undefined
+				? { project: projectID, limit: input.policy.sessionPageSize }
+				: { project: projectID, limit: input.policy.sessionPageSize, cursor: sessionCursor };
+		const label = `Session list for project ${JSON.stringify(projectID)}`;
+		const rawPage = await callPort(() => port.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", `Session list item ${sessions.length}`);
+			const id = info["id"];
+			if (typeof id !== "string" || id.length === 0) {
+				throw new SessionCollectionError("malformed-session-record", "Session list item did not contain 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 (sessionIds.has(id)) {
+				throw new SessionCollectionError(
+					"duplicate-session-id",
+					`Session list returned session id ${JSON.stringify(id)} more than once; refusing to continue`,
+				);
+			}
+			if (sessions.length >= input.policy.maxSessions) {
+				throw new SessionCollectionError(
+					"session-limit-exceeded",
+					`Session list exceeded SessionCollectionPolicy.maxSessions=${input.policy.maxSessions}; refusing to emit a partial checkpoint`,
+				);
+			}
+			sessionIds.add(id);
+			const messages = await collectSessionMessages(port, id, input.policy, collectedMessageCount);
+			collectedMessageCount += messages.length;
+			sessions.push({ info, messages });
+		}
+
+		if (page.next === undefined) break;
+		if (usedSessionCursors.has(page.next)) {
+			throw new SessionCollectionError(
+				"repeated-session-cursor",
+				`Session list returned a cursor that was already used: ${JSON.stringify(page.next)}; refusing to loop`,
+			);
+		}
+		usedSessionCursors.add(page.next);
+		sessionCursor = page.next;
+	}
+
+	return { sessions };
+}
+
+/**
+ * Pages one session's messages to exhaustion in server order.
+ *
+ * The first request is explicitly ascending; every later request carries only
+ * the opaque cursor (the API cannot combine `order` with `cursor`). The
+ * `sessionID` in the request is the ownership boundary: the v2.0.22 route
+ * scopes records to its `:sessionID` path parameter, and message records
+ * carry no `sessionID` of their own, so association is endpoint-scoped and is
+ * deliberately not re-asserted or normalized per record. Duplicate message
+ * ids, repeated cursors, malformed records, unsettled messages, API failures,
+ * the per-session bound, and the cross-session `maxTotalMessages` bound all
+ * fail closed. The total bound is checked against
+ * `alreadyCollectedMessages + messages collected so far in this session + whole
+ * page size` before the page is accumulated: a page that would push the
+ * collection over the bound rejects the whole collection instead of being
+ * truncated.
+ */
+async function collectSessionMessages(
+	port: SessionReadPort,
+	sessionID: string,
+	policy: SessionCollectionPolicy,
+	alreadyCollectedMessages: number,
+): Promise<readonly JsonObject[]> {
+	const messages: JsonObject[] = [];
+	const messageIds = new Set<string>();
+	const usedCursors = new Set<string>();
+	let cursor: string | undefined;
+
+	for (;;) {
+		const pageRequest: MessageListPageRequest =
+			cursor === undefined
+				? { sessionID, limit: policy.messagePageSize, order: "asc" }
+				: { sessionID, limit: policy.messagePageSize, cursor };
+		const label = `Message list for session ${JSON.stringify(sessionID)}`;
+		const rawPage = await callPort(() => port.listMessages(pageRequest), "message-list-failed", `${label} request failed`);
+		const page = parsePageEnvelope(rawPage, "malformed-message-page", `${label} response`);
+
+		// Fail closed before accumulating this page when the collection would
+		// exceed the cross-session total. The page is counted whole (every item
+		// either becomes a message or rejects the collection), so a partially
+		// fitting page is never truncated.
+		const pageTotal = alreadyCollectedMessages + messages.length + page.items.length;
+		if (pageTotal > policy.maxTotalMessages) {
+			throw new SessionCollectionError(
+				"total-message-limit-exceeded",
+				`${label} would bring the total message count to ${pageTotal}, exceeding SessionCollectionPolicy.maxTotalMessages=${policy.maxTotalMessages}; refusing to emit a partial checkpoint`,
+			);
+		}
+
+		for (const rawMessage of page.items) {
+			const message = snapshotJsonRecord(rawMessage, "malformed-message-record", `${label} item ${messages.length}`);
+			const id = message["id"];
+			if (typeof id !== "string" || id.length === 0) {
+				throw new SessionCollectionError("malformed-message-record", `${label} returned a message without a non-empty string id`);
+			}
+			if (messageIds.has(id)) {
+				throw new SessionCollectionError(
+					"duplicate-message-id",
+					`${label} returned message id ${JSON.stringify(id)} more than once; refusing to continue`,
+				);
+			}
+			if (messages.length >= policy.maxMessagesPerSession) {
+				throw new SessionCollectionError(
+					"message-limit-exceeded",
+					`${label} exceeded SessionCollectionPolicy.maxMessagesPerSession=${policy.maxMessagesPerSession}; refusing to emit a partial checkpoint`,
+				);
+			}
+			messageIds.add(id);
+			const unsettled = findUnsettledMessageReason(message);
+			if (unsettled !== undefined) {
+				throw new SessionCollectionError(
+					"unsettled-message",
+					`${label} message ${JSON.stringify(id)} is unsettled (${unsettled}); official transfer/import would drop it, so the checkpoint fails closed with no artifact`,
+				);
+			}
+			messages.push(message);
+		}
+
+		if (page.next === undefined) break;
+		if (usedCursors.has(page.next)) {
+			throw new SessionCollectionError(
+				"repeated-message-cursor",
+				`${label} returned a cursor that was already used: ${JSON.stringify(page.next)}; refusing to loop`,
+			);
+		}
+		usedCursors.add(page.next);
+		cursor = page.next;
+	}
+
+	return messages;
+}
+
+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. Unknown *items* are
+ * returned as-is and are snapshotted individually afterwards; the envelope's
+ * `next` is only ever used as an opaque string or as a stop signal.
+ */
+function parsePageEnvelope(value: unknown, code: SessionCollectionErrorCode, label: string): ParsedPage {
+	if (!isJsonObject(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 (!isJsonObject(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: SessionCollectionErrorCode, label: string): JsonObject {
+	if (!isJsonObject(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 (!isJsonObject(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: SessionCollectionErrorCode,
+	label: string,
+): Promise<unknown> {
+	try {
+		return await call();
+	} catch (cause) {
+		if (cause instanceof SessionCollectionError) throw cause;
+		throw new SessionCollectionError(code, `${label}: ${errorText(cause)}`, { cause });
+	}
+}

package/src/core/sessions/errors.ts

@@ -0,0 +1,37 @@
+/**
+ * Fail-closed failure codes for session collection.
+ *
+ * A thrown `SessionCollectionError` always means the collection stopped without
+ * producing a payload or serialized bytes. Callers must never catch it and
+ * continue with a partially collected result (P-05: complete history or no
+ * artifact; no silent filtering or truncation).
+ */
+export type SessionCollectionErrorCode =
+	| "invalid-request"
+	| "invalid-policy"
+	| "session-list-failed"
+	| "message-list-failed"
+	| "malformed-session-page"
+	| "malformed-message-page"
+	| "malformed-session-record"
+	| "malformed-message-record"
+	| "session-project-mismatch"
+	| "duplicate-session-id"
+	| "duplicate-message-id"
+	| "repeated-session-cursor"
+	| "repeated-message-cursor"
+	| "session-limit-exceeded"
+	| "message-limit-exceeded"
+	| "total-message-limit-exceeded"
+	| "unsettled-message";
+
+/** Collection failure with a stable machine-readable code; `cause` preserves the underlying API/validation error. */
+export class SessionCollectionError extends Error {
+	readonly code: SessionCollectionErrorCode;
+
+	constructor(code: SessionCollectionErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "SessionCollectionError";
+		this.code = code;
+	}
+}

package/src/core/sessions/guards.ts

@@ -0,0 +1,11 @@
+/** Internal runtime guards shared by the session collection modules. */
+
+/** True for JSON-shaped object values (non-null, not an array). */
+export function isJsonObject(value: unknown): value is { readonly [key: string]: unknown } {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Best-effort message text for wrapping a caught `unknown` value. */
+export function errorText(value: unknown): string {
+	return value instanceof Error ? value.message : String(value);
+}

package/src/core/sessions/index.ts

@@ -0,0 +1,29 @@
+/**
+ * SessionPort V1 core session lane (Phase 2).
+ *
+ * Bounded session enumeration, detached JSON snapshotting, and payload
+ * serialization against the approved shared contracts. Session records are
+ * bound to the requested scope fail-closed: each session `projectID` must
+ * equal the requested project or the whole collection rejects. Message
+ * association is endpoint-scoped through `listMessages(sessionID, ...)`: the
+ * v2.0.22 route scopes messages to its `:sessionID` path parameter, message
+ * records carry no `sessionID` of their own, and no per-record association
+ * check or normalization is invented. No TUI/OpenCode imports; the host API
+ * is reached only through the injected `SessionReadPort`.
+ *
+ * Consistency caveat (O-21 / OQ-23): upstream list APIs document no atomic
+ * snapshot. A successful collection is a best-effort page sequence, not a
+ * consistent point-in-time capture, and this lane invents no retry policy.
+ * Canonical duplicate comparison (O-04) and ID/reference conflict remapping
+ * (O-05) are intentionally not implemented here.
+ */
+export { collectCheckpointPayload } from "./collector.ts";
+export type { CollectCheckpointPayloadRequest } from "./collector.ts";
+export { SessionCollectionError } from "./errors.ts";
+export type { SessionCollectionErrorCode } from "./errors.ts";
+export { MESSAGE_PAGE_SIZE_CAP, validateSessionCollectionPolicy } from "./policy.ts";
+export type { SessionCollectionPolicy } from "./policy.ts";
+export type { MessageListPageRequest, SessionListPageRequest, SessionReadPort } from "./port.ts";
+export { serializeCheckpointPayload } from "./serialize.ts";
+export { findUnsettledMessageReason } from "./unsettled.ts";
+export type { UnsettledMessageReason } from "./unsettled.ts";

package/src/core/sessions/policy.ts

@@ -0,0 +1,80 @@
+import { SessionCollectionError } from "./errors.ts";
+import { isJsonObject } from "./guards.ts";
+
+/**
+ * Explicit, required collection bounds. Every field has no default and must be
+ * supplied by the caller: this lane deliberately ships no production caps or
+ * hidden fallbacks (O-03 / OQ-03 remain OPEN and must be benchmarked before
+ * freeze). Tests may pass synthetic small values.
+ *
+ * Exceeding any bound fails the whole collection; the collector never emits a
+ * silently truncated or partial payload.
+ */
+export interface SessionCollectionPolicy {
+	/** Page size for `GET /api/session` requests (v2.0.22 declares a default of 50, not a cap). */
+	readonly sessionPageSize: number;
+	/** Page size for message list requests; must not exceed the declared v2.0.22 cap of 200. */
+	readonly messagePageSize: number;
+	/** Hard bound on the number of sessions collected across all pages. */
+	readonly maxSessions: number;
+	/** Hard bound on messages collected for a single session. */
+	readonly maxMessagesPerSession: number;
+	/**
+	 * Hard bound on messages collected across all sessions and pages; checked
+	 * against the number already collected plus a whole page before that page
+	 * is accumulated, so a page that would push the collection over the bound
+	 * rejects it instead of being truncated. Zero is allowed and forbids
+	 * collecting any message.
+	 */
+	readonly maxTotalMessages: number;
+}
+
+/** Declared v2.0.22 maximum page size for `GET /api/session/:sessionID/message` (E14). */
+export const MESSAGE_PAGE_SIZE_CAP = 200;
+
+/**
+ * Validates an explicit policy at the collection boundary. Invalid or missing
+ * limits fail closed instead of silently substituting a default.
+ */
+export function validateSessionCollectionPolicy(policy: SessionCollectionPolicy): void {
+	if (!isJsonObject(policy)) {
+		throw new SessionCollectionError(
+			"invalid-policy",
+			"SessionCollectionPolicy is required and must be an explicit object with sessionPageSize, messagePageSize, maxSessions, maxMessagesPerSession, and maxTotalMessages; no defaults are applied",
+		);
+	}
+	requirePositiveSafeInteger(policy.sessionPageSize, "sessionPageSize");
+	requirePositiveSafeInteger(policy.messagePageSize, "messagePageSize");
+	if (typeof policy.messagePageSize === "number" && policy.messagePageSize > MESSAGE_PAGE_SIZE_CAP) {
+		throw new SessionCollectionError(
+			"invalid-policy",
+			`SessionCollectionPolicy.messagePageSize must not exceed the declared message page cap of ${MESSAGE_PAGE_SIZE_CAP} (got ${policy.messagePageSize})`,
+		);
+	}
+	requirePositiveSafeInteger(policy.maxSessions, "maxSessions");
+	requirePositiveSafeInteger(policy.maxMessagesPerSession, "maxMessagesPerSession");
+	requireNonNegativeSafeInteger(policy.maxTotalMessages, "maxTotalMessages");
+}
+
+function requirePositiveSafeInteger(value: unknown, field: keyof SessionCollectionPolicy): void {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+		throw new SessionCollectionError(
+			"invalid-policy",
+			`SessionCollectionPolicy.${field} must be an explicit positive safe integer (got ${String(value)})`,
+		);
+	}
+}
+
+/**
+ * `maxTotalMessages` is an aggregate cap where zero is a meaningful,
+ * fail-closed setting ("collect no messages"), so it accepts zero while the
+ * other bounds require at least one.
+ */
+function requireNonNegativeSafeInteger(value: unknown, field: keyof SessionCollectionPolicy): void {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+		throw new SessionCollectionError(
+			"invalid-policy",
+			`SessionCollectionPolicy.${field} must be an explicit non-negative safe integer (got ${String(value)})`,
+		);
+	}
+}

package/src/core/sessions/port.ts

@@ -0,0 +1,88 @@
+/**
+ * Dependency-injected read surface for session enumeration.
+ *
+ * This is the only host boundary the session core lane needs (no TUI/OpenCode
+ * imports here). Implementations live outside this module and map these calls
+ * onto the host client; tests inject synthetic ports.
+ *
+ * Expected upstream behavior (OpenCode v2.0.22 declarations/source research,
+ * E13/E14; declarations vs. runtime behavior still partially unvalidated —
+ * OQ-10):
+ * - `listSessions` maps to `GET /api/session`: declared filters include
+ *   `project`/`directory`; default page size 50; opaque cursor pagination with
+ *   no total/hasMore. Responses are `{ data: [...], cursor: { next?: string | null } }`.
+ * - `listMessages` maps to `GET /api/session/:sessionID/message`: declared
+ *   default page size 50, cap 200, default order `desc`; `order` cannot be
+ *   combined with `cursor`; secret-type filtering is possible and must be
+ *   omitted to preserve every message variant. The `:sessionID` path
+ *   parameter is the ownership boundary: the endpoint scopes returned records
+ *   to that session, and v2.0.22 message records carry no per-message
+ *   `sessionID` (their common Base is `id`/metadata/`time`), so a record
+ *   cannot independently assert session association.
+ *
+ * Response values are treated as untrusted `unknown` and are validated into
+ * detached JSON-only snapshots by the collector; a port must not pre-filter,
+ * pre-truncate, or coerce API data.
+ *
+ * Consistency caveat (O-21 / OQ-23): the upstream list APIs document no atomic
+ * snapshot or snapshot-consistency guarantee. A successful collection is a
+ * sequence of page reads, not a consistent point-in-time capture; no retry or
+ * re-read policy is defined here. Do not describe this utility as a complete
+ * checkpoint transaction — compression/encryption/writing remain separate.
+ */
+export interface SessionReadPort {
+	/**
+	 * Requests one page of the session list scoped to the explicit project.
+	 * Expected response: `{ data: unknown[]; cursor?: { next?: string | null } | null }`.
+	 */
+	listSessions(request: SessionListPageRequest): Promise<unknown>;
+
+	/**
+	 * Requests one page of messages for exactly one session, addressed by the
+	 * `sessionID` field of `MessageListPageRequest`. That request target is the
+	 * ownership boundary: the upstream route scopes returned records to the
+	 * path session and v2.0.22 message records carry no `sessionID`, so
+	 * per-record association cannot be independently asserted and must not be
+	 * inferred, required, or normalized. The first call must use `order: "asc"`;
+	 * later calls pass the opaque `cursor` and no `order`. No `type` filter is
+	 * ever sent.
+	 * Expected response: `{ data: unknown[]; cursor?: { next?: string | null } | null }`.
+	 */
+	listMessages(request: MessageListPageRequest): Promise<unknown>;
+}
+
+/** One session list page request. The project scope is always explicit; the collector never infers it. */
+export interface SessionListPageRequest {
+	/** Explicit project scope; mapped to the list route's `project` filter. */
+	readonly project: string;
+	/** Explicit page size from `SessionCollectionPolicy`; the API default is never relied on. */
+	readonly limit: number;
+	/** Opaque `cursor.next` from the previous page; absent on the first request. */
+	readonly cursor?: string;
+}
+
+/**
+ * One message list page request.
+ *
+ * `sessionID` is the endpoint-scoped ownership boundary (the route path
+ * parameter) and is always the session currently being collected; returned
+ * records are not expected to repeat it (v2.0.22 message records have no
+ * `sessionID` field). The union mirrors the declared API constraint that
+ * `order` and `cursor` cannot be combined: the first page is `{ order: "asc" }`
+ * with no cursor, and every subsequent page carries only the opaque cursor. No
+ * `type` filter is ever sent so all message variants and tool content are
+ * preserved.
+ */
+export type MessageListPageRequest =
+	| {
+			readonly sessionID: string;
+			readonly limit: number;
+			/** First page only: ascending order. */
+			readonly order: "asc";
+	  }
+	| {
+			readonly sessionID: string;
+			readonly limit: number;
+			/** Subsequent pages only: opaque cursor; no `order`, no `type` filter. */
+			readonly cursor: string;
+	  };

package/src/core/sessions/serialize.ts

@@ -0,0 +1,15 @@
+import { encodeJson, type CheckpointPayload } from "../contracts/index.ts";
+
+/**
+ * Serializes a complete, successfully collected `CheckpointPayload` to detached
+ * JSON bytes via the shared `encodeJson` contract.
+ *
+ * This is only the serialization step of a checkpoint; compression, encryption,
+ * and artifact writing are separate. The collector always either returns a
+ * complete payload or throws, so there is no partial payload to serialize.
+ * `encodeJson` additionally rejects non-JSON-stable values instead of silently
+ * omitting or coercing them.
+ */
+export function serializeCheckpointPayload(payload: CheckpointPayload): Uint8Array {
+	return encodeJson(payload);
+}

package/src/core/sessions/unsettled.ts

@@ -0,0 +1,35 @@
+import type { JsonObject } from "../contracts/index.ts";
+import { isJsonObject } from "./guards.ts";
+
+/**
+ * Reasons a message is "unsettled" under the official v2.0.22 transfer/import
+ * filter (E15). Such messages would be silently dropped by import/export;
+ * because completeness is DECIDED (P-05) the checkpoint must fail closed
+ * instead of filtering them.
+ */
+export type UnsettledMessageReason =
+	| "assistant-without-completion"
+	| "shell-running"
+	| "compaction-running";
+
+/**
+ * Detects messages that official transfer/import would drop:
+ * - assistant message without a numeric `time.completed`;
+ * - shell message with `status: "running"`;
+ * - compaction message with `status: "running"`.
+ *
+ * Unknown message types, unknown statuses, and unknown fields are preserved,
+ * not filtered or coerced. This mirrors the researched v2.0.22 rules only; it
+ * is not a general schema validator and it makes no claim beyond E15.
+ */
+export function findUnsettledMessageReason(message: JsonObject): UnsettledMessageReason | undefined {
+	const type = message["type"];
+	if (type === "assistant") {
+		const time = message["time"];
+		const completed = isJsonObject(time) ? time["completed"] : undefined;
+		if (typeof completed !== "number") return "assistant-without-completion";
+	}
+	if (type === "shell" && message["status"] === "running") return "shell-running";
+	if (type === "compaction" && message["status"] === "running") return "compaction-running";
+	return undefined;
+}

package/src/integrations/omo/index.ts

@@ -0,0 +1,28 @@
+/** V1 OMO boundary: no stable public session-transfer API exists, so transfer no OMO data. */
+export type OmoNoopResult = {
+	readonly status: "no-op";
+	readonly reason: "no-public-session-transfer-api";
+};
+
+export interface OmoAdapter {
+	capture(): Promise<OmoNoopResult>;
+	restore(): Promise<OmoNoopResult>;
+}
+
+const RESULT: OmoNoopResult = Object.freeze({
+	status: "no-op",
+	reason: "no-public-session-transfer-api",
+});
+
+/**
+ * Deliberately does not inspect OMO configuration, package inventory, job-board
+ * state, credentials, agents, tools, or host-managed files. Native OpenCode
+ * sessions are the complete V1 payload; a future adapter requires an explicit,
+ * stable, versioned public transfer API.
+ */
+export function createOmoAdapter(): OmoAdapter {
+	return Object.freeze({
+		capture: async () => RESULT,
+		restore: async () => RESULT,
+	});
+}