opencode-session-port 0.0.0-stage → 0.1.1

package/src/tui/orchestration/restore-execution.ts

@@ -0,0 +1,381 @@
+/**
+ * Injected sequential restore execution (Phase 4, bounded orchestration).
+ *
+ * `runRestoreExecution` consumes one completed `RestorePlan` (from
+ * `planRestore`) plus an injected `SessionImportAdapter` and executes exactly
+ * `plan.importOrder` — the planner's deterministic parent-before-child order —
+ * one import at a time. This module performs no host call itself: the injected
+ * adapter owns the single public `session.import` invocation per planned entry
+ * and its explicit target (O-16).
+ *
+ * Owner handling policy (O-06, 2026-10-10; the final error taxonomy/report
+ * format stays OPEN as O-15):
+ * - No automatic retries: at most one `importSession` call per planned entry,
+ *   ever.
+ * - An individual import failure is caught and recorded as `failed`; unrelated
+ *   branches continue with the remaining `importOrder` entries.
+ * - Descendants by `info.parentID` of a parent that failed, was blocked, or was
+ *   not attempted are marked `blocked` and are never imported; blocking
+ *   propagates down the parent chain.
+ * - Exact skips from `plan.entries` initialize as `skipped` outcomes with their
+ *   planner `skipReason` preserved; they are treated as already present, are
+ *   never imported, and never block their descendants.
+ * - A `parentID` that resolves outside the plan is assumed to be an already
+ *   validated destination/local session (the planner only preserves such
+ *   references when the destination snapshot contains them) and never blocks.
+ * - `shouldContinue` is a minimal injected stop check (default: always
+ *   continue; no host cancellation is wired). Once it reports `false` — or
+ *   misbehaves by returning a nonboolean value or throwing — no further import
+ *   is attempted: remaining independent planned entries are `not-attempted`,
+ *   while descendants of an unattempted parent are `blocked` because that
+ *   parent is absent. Stop-check misbehavior only latches the injected stop
+ *   seam; the raw return value/error is never exposed, stringified, or logged,
+ *   and importer failure handling is unchanged (a failed import is still
+ *   recorded as `failed` and independent branches continue).
+ * - Every `plan.entries` entry receives exactly one outcome; a manual rerun
+ *   stays user-controlled (deterministic O-05 IDs let it reuse the same
+ *   targets), and no atomic rollback is attempted or promised (A-06).
+ *
+ * Secrecy and leak boundary: outcomes carry IDs, classifications, and statuses
+ * only. Host exceptions are caught and never rethrown, wrapped, stringified, or
+ * logged, so no session record content, message text, password material, or raw
+ * host error crosses this boundary; this module performs no console output.
+ * Error taxonomy and report formatting remain OPEN (O-15): these are raw
+ * per-session facts, not a user-facing report.
+ *
+ * Fail-closed input validation: the plan shape, the adapter surface, the
+ * explicit target directory, and the callable `shouldContinue` shape are
+ * validated before any import is attempted; a malformed plan (for example an
+ * `importOrder` that omits or repeats a planned entry, contains a skipped
+ * entry, is not parent-first, or an `exact-local-duplicate` skip whose
+ * `targetSessionID` differs from its `sourceSessionID`) throws a `TypeError`
+ * without calling the adapter. Only exact-local-duplicate skips must keep
+ * target equal to source (the planner never remaps a local duplicate);
+ * `exact-planned-retry` skips may legitimately be remapped, so no equality is
+ * imposed on them.
+ *
+ * Evidence boundary: exercised only with synthetic plans and fake importers in
+ * tests. No real host call, import, filesystem, crypto, or UI effect is
+ * performed by this lane, and no runtime, compatibility, or security claim
+ * follows; the adapter's Experimental-route and O-12/O-16 boundaries are
+ * unchanged.
+ */
+
+import type { SessionRecord } from "../../core/contracts/index.ts";
+import type {
+	RestoreClassification,
+	RestorePlan,
+	RestorePlanEntry,
+	RestoreSkipReason,
+} from "../../core/restore/index.ts";
+import type { SessionImportAdapter } from "../adapters/index.ts";
+import { isRecordValue, requireCallable, requireNonEmptyString } from "./shared.ts";
+
+/* ------------------------------------------------------------------------- */
+/* Public result shape                                                       */
+/* ------------------------------------------------------------------------- */
+
+/** Truthful per-session execution status for one restore run (O-06). */
+export type RestoreSessionExecutionStatus = "imported" | "skipped" | "failed" | "blocked" | "not-attempted";
+
+/** One artifact session's outcome: planner classification plus execution status. */
+export interface RestoreSessionOutcome {
+	/** Original artifact session ID; unique within the plan. */
+	readonly sourceSessionID: string;
+	/** Planned target session ID for this run (deterministic O-05 remap). */
+	readonly targetSessionID: string;
+	/** Planner classification preserved from `plan.entries` ("skipped" for exact skips). */
+	readonly classification: RestoreClassification;
+	/** Truthful execution status for this run. */
+	readonly status: RestoreSessionExecutionStatus;
+	/** Present exactly when `classification` is "skipped"; preserved from the plan. */
+	readonly skipReason?: RestoreSkipReason;
+}
+
+/** Raw per-session counts; no O-15 report format is implied. */
+export interface RestoreExecutionSummary {
+	readonly total: number;
+	readonly imported: number;
+	readonly skipped: number;
+	readonly failed: number;
+	readonly blocked: number;
+	readonly notAttempted: number;
+}
+
+/** Complete outcome accounting for one execution run. */
+export interface RestoreExecutionResult {
+	/** One outcome per `plan.entries` entry, in the same order. */
+	readonly outcomes: readonly RestoreSessionOutcome[];
+	readonly summary: RestoreExecutionSummary;
+}
+
+/** Explicit, fully injected execution dependencies. */
+export interface RestoreExecutionInput {
+	/** Completed `planRestore` output; consumed as-is (order, classifications, skip reasons). */
+	readonly plan: RestorePlan;
+	/** Single-session import surface; one call per planned entry, no retries. */
+	readonly importer: SessionImportAdapter;
+	/** Explicit import target directory supplied on every call (O-16); never inferred. */
+	readonly targetDirectory: string;
+	/**
+	 * Minimal stop check; defaults to always-continue. No host cancellation is
+	 * wired. A thrown error or nonboolean return is treated as a stop for the
+	 * remaining entries (never rethrown, wrapped, stringified, or logged);
+	 * importer failure handling is unaffected.
+	 */
+	readonly shouldContinue?: () => boolean;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Internal helpers                                                          */
+/* ------------------------------------------------------------------------- */
+
+interface MutableOutcome {
+	readonly sourceSessionID: string;
+	readonly targetSessionID: string;
+	readonly classification: RestoreClassification;
+	readonly skipReason?: RestoreSkipReason;
+	status: RestoreSessionExecutionStatus;
+}
+
+const CLASSIFICATIONS: ReadonlySet<string> = new Set(["skipped", "imported", "renamed"]);
+const SKIP_REASONS: ReadonlySet<string> = new Set(["exact-local-duplicate", "exact-planned-retry"]);
+
+function summarize(outcomes: readonly RestoreSessionOutcome[]): RestoreExecutionSummary {
+	const counts: Record<RestoreSessionExecutionStatus, number> = {
+		imported: 0,
+		skipped: 0,
+		failed: 0,
+		blocked: 0,
+		"not-attempted": 0,
+	};
+	for (const outcome of outcomes) counts[outcome.status] += 1;
+	return {
+		total: outcomes.length,
+		imported: counts.imported,
+		skipped: counts.skipped,
+		failed: counts.failed,
+		blocked: counts.blocked,
+		notAttempted: counts["not-attempted"],
+	};
+}
+
+/* ------------------------------------------------------------------------- */
+/* runRestoreExecution                                                       */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Executes one completed restore plan sequentially in `plan.importOrder` order
+ * and returns truthful per-session outcomes. See the module comment for the
+ * exact handling policy, blocking rules, and validation boundary.
+ */
+export async function runRestoreExecution(input: RestoreExecutionInput): Promise<RestoreExecutionResult> {
+	if (!isRecordValue(input)) {
+		throw new TypeError("runRestoreExecution requires an input object with plan, importer, and targetDirectory");
+	}
+	if (!isRecordValue(input.importer) || typeof input.importer.importSession !== "function") {
+		throw new TypeError("runRestoreExecution requires an importer with an importSession(request) function");
+	}
+	const targetDirectory = requireNonEmptyString(input.targetDirectory, "targetDirectory");
+	if (input.shouldContinue !== undefined) {
+		requireCallable(input.shouldContinue, "shouldContinue");
+	}
+	const shouldContinue: () => boolean = input.shouldContinue ?? (() => true);
+
+	/* -- 1. Fail-closed plan-shape validation before any import. -- */
+	const rawPlan: unknown = input.plan;
+	if (!isRecordValue(rawPlan)) {
+		throw new TypeError("runRestoreExecution requires a completed RestorePlan object");
+	}
+	const rawEntries = rawPlan["entries"];
+	const rawImportOrder = rawPlan["importOrder"];
+	if (!Array.isArray(rawEntries) || !Array.isArray(rawImportOrder)) {
+		throw new TypeError("runRestoreExecution requires a completed RestorePlan with entries and importOrder arrays");
+	}
+
+	const entries: RestorePlanEntry[] = [];
+	const entryBySourceID = new Map<string, RestorePlanEntry>();
+	const outcomeBySourceID = new Map<string, MutableOutcome>();
+	const outcomeByTargetID = new Map<string, MutableOutcome>();
+
+	for (let index = 0; index < rawEntries.length; index++) {
+		const raw: unknown = rawEntries[index];
+		if (!isRecordValue(raw)) throw new TypeError(`plan.entries[${index}] must be a restore plan entry object`);
+		const sourceSessionID = requireNonEmptyString(raw["sourceSessionID"], `plan.entries[${index}].sourceSessionID`);
+		const targetSessionID = requireNonEmptyString(raw["targetSessionID"], `plan.entries[${index}].targetSessionID`);
+		const classification = raw["classification"];
+		if (typeof classification !== "string" || !CLASSIFICATIONS.has(classification)) {
+			throw new TypeError(`plan.entries[${index}].classification must be "skipped", "imported", or "renamed"`);
+		}
+		const rawSkipReason = raw["skipReason"];
+		let skipReason: RestoreSkipReason | undefined;
+		if (classification === "skipped") {
+			if (typeof rawSkipReason !== "string" || !SKIP_REASONS.has(rawSkipReason)) {
+				throw new TypeError(`plan.entries[${index}] is skipped and must preserve an exact planner skipReason`);
+			}
+			skipReason = rawSkipReason as RestoreSkipReason;
+		} else if (rawSkipReason !== undefined) {
+			throw new TypeError(`plan.entries[${index}] carries a skipReason but is not skipped`);
+		}
+		if (classification === "skipped" && skipReason === "exact-local-duplicate" && sourceSessionID !== targetSessionID) {
+			// A genuine exact-local-duplicate skip is an unchanged local session:
+			// the planner never remaps its target. A remapped target would let
+			// execution treat an absent session as already present, so fail closed
+			// before any import. Exact-planned-retry skips are deliberately exempt
+			// (a renamed retry may target a derived ID).
+			throw new TypeError(
+				`plan.entries[${index}] is an exact-local-duplicate skip whose targetSessionID differs from its sourceSessionID; a local duplicate must target the same session`,
+			);
+		}
+		const rawRecord = raw["record"];
+		if (!isRecordValue(rawRecord)) {
+			throw new TypeError(`plan.entries[${index}].record must be an object with info and messages`);
+		}
+		const rawInfo = rawRecord["info"];
+		const rawMessages = rawRecord["messages"];
+		if (!isRecordValue(rawInfo) || !Array.isArray(rawMessages)) {
+			throw new TypeError(`plan.entries[${index}].record must be an object with info and messages`);
+		}
+		const recordID = rawInfo["id"];
+		if (typeof recordID !== "string" || recordID !== targetSessionID) {
+			throw new TypeError(`plan.entries[${index}].record.info.id must equal the planned targetSessionID`);
+		}
+		const parentID = rawInfo["parentID"];
+		if (parentID !== undefined && typeof parentID !== "string") {
+			throw new TypeError(`plan.entries[${index}].record.info.parentID must be a string when present`);
+		}
+		if (entryBySourceID.has(sourceSessionID)) {
+			throw new TypeError(`plan.entries repeats sourceSessionID ${JSON.stringify(sourceSessionID)}`);
+		}
+		if (outcomeByTargetID.has(targetSessionID)) {
+			throw new TypeError(`plan.entries repeats targetSessionID ${JSON.stringify(targetSessionID)}`);
+		}
+
+		const entry: RestorePlanEntry = {
+			sourceSessionID,
+			targetSessionID,
+			classification: classification as RestoreClassification,
+			record: rawRecord as unknown as SessionRecord,
+			...(skipReason !== undefined ? { skipReason } : {}),
+		};
+		const outcome: MutableOutcome = {
+			sourceSessionID,
+			targetSessionID,
+			classification: entry.classification,
+			...(skipReason !== undefined ? { skipReason } : {}),
+			status: classification === "skipped" ? "skipped" : "not-attempted",
+		};
+		entries.push(entry);
+		entryBySourceID.set(sourceSessionID, entry);
+		outcomeBySourceID.set(sourceSessionID, outcome);
+		outcomeByTargetID.set(targetSessionID, outcome);
+	}
+
+	const order: RestorePlanEntry[] = [];
+	const orderIndexByTargetID = new Map<string, number>();
+	const orderSeen = new Set<string>();
+	for (let index = 0; index < rawImportOrder.length; index++) {
+		const raw: unknown = rawImportOrder[index];
+		if (!isRecordValue(raw)) throw new TypeError(`plan.importOrder[${index}] must be a restore plan entry object`);
+		const sourceSessionID = requireNonEmptyString(raw["sourceSessionID"], `plan.importOrder[${index}].sourceSessionID`);
+		const entry = entryBySourceID.get(sourceSessionID);
+		if (entry === undefined) {
+			throw new TypeError(
+				`plan.importOrder[${index}] references sourceSessionID ${JSON.stringify(sourceSessionID)} that is not in plan.entries`,
+			);
+		}
+		if (raw["targetSessionID"] !== entry.targetSessionID || raw["classification"] !== entry.classification) {
+			throw new TypeError(`plan.importOrder[${index}] does not match the corresponding plan.entries entry`);
+		}
+		if (entry.classification === "skipped") {
+			throw new TypeError(
+				`plan.importOrder[${index}] contains skipped session ${JSON.stringify(sourceSessionID)}; exact skips are never imported`,
+			);
+		}
+		if (orderSeen.has(sourceSessionID)) {
+			throw new TypeError(`plan.importOrder repeats sourceSessionID ${JSON.stringify(sourceSessionID)}; a retry is never performed`);
+		}
+		orderSeen.add(sourceSessionID);
+		orderIndexByTargetID.set(entry.targetSessionID, index);
+		order.push(entry);
+	}
+	for (const entry of entries) {
+		if (entry.classification === "skipped") continue;
+		if (!orderSeen.has(entry.sourceSessionID)) {
+			throw new TypeError(
+				`plan.importOrder omits planned session ${JSON.stringify(entry.sourceSessionID)}; every planned entry must be accounted for`,
+			);
+		}
+	}
+	for (let index = 0; index < order.length; index++) {
+		const entry = order[index]!;
+		const parentID = entry.record.info["parentID"];
+		if (typeof parentID !== "string") continue;
+		const parentIndex = orderIndexByTargetID.get(parentID);
+		if (parentIndex !== undefined && parentIndex >= index) {
+			throw new TypeError(
+				`plan.importOrder is not parent-first: ${JSON.stringify(entry.sourceSessionID)} appears before its planned parent ${JSON.stringify(parentID)}`,
+			);
+		}
+	}
+
+	/* -- 2. Sequential execution in planner order. -- */
+	let stopLatched = false;
+	for (const entry of order) {
+		const outcome = outcomeBySourceID.get(entry.sourceSessionID)!;
+		const parentID = entry.record.info["parentID"];
+		if (typeof parentID === "string") {
+			const parent = outcomeByTargetID.get(parentID);
+			if (parent !== undefined && parent.status !== "imported" && parent.status !== "skipped") {
+				// The planned parent is absent: it failed, was blocked, or was
+				// never attempted, so this descendant is not imported.
+				outcome.status = "blocked";
+				continue;
+			}
+		}
+		if (!stopLatched) {
+			let decision: unknown;
+			try {
+				decision = shouldContinue();
+			} catch {
+				// Misbehaving injected stop seam: treat it as a stop. The raw
+				// callback error never crosses this boundary (no rethrow, wrap,
+				// stringify, or log), and importer failure handling is unchanged.
+				decision = false;
+			}
+			// Only an explicit boolean `true` continues; `false` and any
+			// nonboolean value latch the stop for the remaining entries.
+			if (decision !== true) stopLatched = true;
+		}
+		if (stopLatched) {
+			// Remaining independent planned entries are not attempted; their
+			// descendants are blocked on the next iterations because this
+			// parent stays absent.
+			outcome.status = "not-attempted";
+			continue;
+		}
+		try {
+			await input.importer.importSession({ record: entry.record, target: { directory: targetDirectory } });
+			outcome.status = "imported";
+		} catch {
+			// No retry, no wrapping, no logging: the failure is recorded as a
+			// truthful `failed` status and its raw error never crosses this
+			// boundary (O-15 taxonomy/report format stays OPEN).
+			outcome.status = "failed";
+		}
+	}
+
+	/* -- 3. Complete outcome accounting in plan.entries order. -- */
+	const outcomes: RestoreSessionOutcome[] = entries.map((entry) => {
+		const outcome = outcomeBySourceID.get(entry.sourceSessionID)!;
+		return {
+			sourceSessionID: outcome.sourceSessionID,
+			targetSessionID: outcome.targetSessionID,
+			classification: outcome.classification,
+			status: outcome.status,
+			...(outcome.skipReason !== undefined ? { skipReason: outcome.skipReason } : {}),
+		};
+	});
+
+	return { outcomes, summary: summarize(outcomes) };
+}

package/src/tui/orchestration/restore-preflight.ts

@@ -0,0 +1,223 @@
+/**
+ * Injected restore preflight (Phase 4, bounded orchestration; `fix-57`).
+ *
+ * `runRestorePreflight` performs capability detection, one password attempt,
+ * artifact authentication, strict payload parsing, the destination snapshot,
+ * the required cross-project session-ID occupancy inventory, and the pure
+ * `planRestore` preflight — and then stops. It never calls an
+ * importer and never touches destination history.
+ *
+ * Exact sequence (each step short-circuits the later ones):
+ *
+ *   1. `probeSessionImportCapability(client)` — the first externally
+ *      observable action. If `session.import` is not callable, return a clear
+ *      `capability-unavailable` outcome before the password provider, the
+ *      artifact read, crypto creation, the destination snapshot, or any
+ *      importer (O-12 policy).
+ *   2. `requestPassword("restore")` — one attempt. `undefined` ⇒ `canceled`
+ *      outcome; the artifact is not read and crypto is not created. The
+ *      owner-decided three-attempt TUI loop lives in the caller, and this
+ *      helper deliberately does not classify crypto rejections as wrong
+ *      password versus corrupt artifact; those errors propagate unchanged.
+ *   3. `readEncryptedArtifact(artifactPath)` — lazily constructs the
+ *      ciphertext source (no file IO yet).
+ *   4. `cryptoFactory.create(cryptoPolicy)` — explicit injected policy only.
+ *   5. `crypto.openAndStage(artifact, password)` — full authentication and
+ *      decompression must pass before any byte is parsed.
+ *   6. Strict UTF-8 decode (`fatal: true`, no BOM stripping, no Unicode
+ *      normalization) followed by `JSON.parse` to `unknown`; invalid bytes or
+ *      JSON fail closed before any destination read.
+ *   7. `readDestination(destinationProjectID)` — the complete destination
+ *      `SessionRecord[]` snapshot, only after successful authentication and
+ *      parse. The destination project ID is an explicit, caller-supplied
+ *      input: a `SessionReadPort` requires a known project ID and cannot
+ *      resolve an arbitrary target directory (OQ-10), so the source
+ *      `info.projectID` is never substituted for the destination scope and no
+ *      project/directory mapping is claimed.
+ *   8. `readGloballyVisibleSessionIDs()` — one required, bounded,
+ *      metadata-only cross-project session-ID inventory (owner-approved
+ *      2026-10-14 amendment), invoked after authentication/parse and the
+ *      destination snapshot and before planning. The returned IDs are
+ *      occupancy evidence only; they can never satisfy destination references,
+ *      classify an exact duplicate, or classify a retry (the planner enforces
+ *      that), and a malformed inventory fails closed. Inventory errors
+ *      propagate unchanged (their existing sanitized `SessionCollectionError`
+ *      taxonomy) and the whole preflight stops with no import and no retry.
+ *   9. `planRestore({ payload, artifactIdentity, destination,
+ *      globallyVisibleSessionIDs, idDeriver })` — schema validation, canonical
+ *      duplicate classification, ID remapping (including deterministic
+ *      cross-project collision renames), collision/dangling-reference checks,
+ *      and the parent-before-child `plan.importOrder` run to completion before
+ *      anything else happens.
+ *
+ * The password bytes are treated as flow-owned from the provider's resolution
+ * and are always best-effort zeroed in `finally` (success, auth failure,
+ * parse failure, destination failure, inventory failure, or planner failure).
+ * Best effort only — not secure deletion (A-07).
+ *
+ * Returned facts: the plan plus the explicit `targetDirectory` required by the
+ * caller (O-16: V1 always supplies an explicit import target and accepts the
+ * host assigning target project scope; no source `projectID`/`location`
+ * preservation is claimed). `plan.importOrder` is the only import-related
+ * output; no import executor, retry handling, partial-failure reporting, or
+ * product command exists in this lane (O-06/O-11/O-15 remain OPEN), and the
+ * adapter `createSessionImportAdapter` is deliberately not imported here.
+ *
+ * Evidence boundary: exercised only by fake clients, fake crypto, fake
+ * artifact sources, fake destination callbacks, and a fake inventory callback.
+ * No real host call, artifact read, KDF, destination enumeration, inventory
+ * scan, or import is performed by this lane, and no runtime or compatibility
+ * claim follows.
+ */
+
+import {
+	type ByteSource,
+	type CheckpointCryptoFactory,
+	type CheckpointPayload,
+	type CryptoPolicy,
+	type SessionRecord,
+} from "../../core/contracts/index.ts";
+import {
+	planRestore,
+	type RemappedIdDeriver,
+	type RestorePlan,
+} from "../../core/restore/index.ts";
+import { probeSessionImportCapability } from "../adapters/index.ts";
+import {
+	isRecordValue,
+	requireCallable,
+	requireNonEmptyString,
+	zeroPasswordBestEffort,
+	type PasswordProvider,
+} from "./shared.ts";
+
+/** Explicit, fully injected restore-preflight dependencies. Every field is required; no defaults exist. */
+export interface RestorePreflightInput {
+	/** Artifact path to open; passed verbatim to the injected lazy reader. */
+	readonly artifactPath: string;
+	/** Known destination project scope for the local snapshot; never taken from the artifact (OQ-10). */
+	readonly destinationProjectID: string;
+	/** Explicit import target directory the caller will use after a successful plan (O-16). */
+	readonly targetDirectory: string;
+	/** Caller-supplied crypto factory; no production factory or profile is created here. */
+	readonly cryptoFactory: CheckpointCryptoFactory;
+	/** Explicit allow-listed policy for `factory.create`; never taken from an artifact. */
+	readonly cryptoPolicy: CryptoPolicy;
+	/** Injected `readEncryptedArtifact`; must return a lazy ciphertext source. */
+	readonly readEncryptedArtifact: (targetPath: string) => ByteSource;
+	/** Interactive password provider; called once per run, `undefined` means canceled. */
+	readonly requestPassword: PasswordProvider;
+	/** Complete local session snapshot for the explicit destination project ID, called only after auth+parse. */
+	readonly readDestination: (projectID: string) => Promise<readonly SessionRecord[]>;
+	/**
+	 * Required cross-project session-ID occupancy inventory (owner-approved
+	 * 2026-10-14 amendment), called once after auth+parse and the destination
+	 * snapshot and before planning. Production wiring must supply the bounded
+	 * metadata-only inventory (`createSessionIdInventory`); this dependency is
+	 * deliberately not optional, so no production path can silently skip the
+	 * cross-project collision check. Errors fail the whole preflight unchanged
+	 * (existing sanitized taxonomy) with no import and no retry.
+	 */
+	readonly readGloballyVisibleSessionIDs: () => Promise<readonly string[]>;
+	/** Injected deterministic ID deriver; `planRestore` validates its outputs (O-22/OQ-24). */
+	readonly idDeriver: RemappedIdDeriver;
+}
+
+/** Restore-preflight outcome; imports remain unimplemented (O-06/O-11/O-15 OPEN). */
+export type RestorePreflightOutcome =
+	/** O-12: `session.import` is not callable; nothing was read, decrypted, or changed. */
+	| { readonly status: "capability-unavailable"; readonly reason: string }
+	/** The user canceled the password prompt; the artifact was not read. */
+	| { readonly status: "canceled" }
+	/** Preflight completed; the caller owns the import target and any later import execution. */
+	| {
+			readonly status: "planned";
+			readonly plan: RestorePlan;
+			readonly targetDirectory: string;
+	  };
+
+/**
+ * Runs one restore preflight to a completed `RestorePlan` or to a clear
+ * capability-unavailable/canceled outcome. Errors (crypto rejection, invalid
+ * UTF-8/JSON, destination/planner failures) propagate unchanged; see the
+ * module comment for the exact sequence and policy boundaries.
+ */
+export async function runRestorePreflight(
+	client: unknown,
+	input: RestorePreflightInput,
+): Promise<RestorePreflightOutcome> {
+	if (!isRecordValue(input)) {
+		throw new TypeError(
+			"runRestorePreflight requires an input object with explicit artifactPath, destinationProjectID, targetDirectory, cryptoFactory, cryptoPolicy, readEncryptedArtifact, requestPassword, readDestination, readGloballyVisibleSessionIDs, and idDeriver",
+		);
+	}
+	requireCallable(input.requestPassword, "requestPassword");
+	requireCallable(input.readEncryptedArtifact, "readEncryptedArtifact");
+	requireCallable(input.readDestination, "readDestination");
+	requireCallable(input.readGloballyVisibleSessionIDs, "readGloballyVisibleSessionIDs");
+	if (!isRecordValue(input.cryptoFactory) || typeof input.cryptoFactory.create !== "function") {
+		throw new TypeError("runRestorePreflight requires a CheckpointCryptoFactory with a create(policy) function");
+	}
+	if (!isRecordValue(input.idDeriver) || typeof input.idDeriver.derive !== "function") {
+		throw new TypeError("runRestorePreflight requires a RemappedIdDeriver with a derive(namespace, identity, id) function");
+	}
+	requireNonEmptyString(input.artifactPath, "artifactPath");
+	requireNonEmptyString(input.destinationProjectID, "destinationProjectID");
+	requireNonEmptyString(input.targetDirectory, "targetDirectory");
+
+	// O-12: the capability probe is the first externally observable action.
+	const probe = probeSessionImportCapability(client);
+	if (!probe.available) {
+		return { status: "capability-unavailable", reason: probe.reason };
+	}
+
+	const password = await input.requestPassword("restore");
+	if (password === undefined) {
+		return { status: "canceled" };
+	}
+	if (!(password instanceof Uint8Array)) {
+		throw new TypeError("The restore password provider must resolve with Uint8Array bytes or undefined");
+	}
+
+	try {
+		// Lazy ciphertext source: constructing it performs no IO; openAndStage pulls it.
+		const artifact = input.readEncryptedArtifact(input.artifactPath);
+		const crypto = await input.cryptoFactory.create(input.cryptoPolicy);
+		// Full authentication and decompression must pass before any parsing.
+		const authenticated = await crypto.openAndStage(artifact, password);
+		const payload = parseAuthenticatedJson(authenticated.bytes);
+		// The complete destination snapshot is read only after auth+parse.
+		const destination = await input.readDestination(input.destinationProjectID);
+		// Required cross-project session-ID occupancy inventory (2026-10-14
+		// owner amendment): metadata only, after auth+parse and the destination
+		// snapshot, before planning. Failures propagate unchanged with no import
+		// and no retry.
+		const globallyVisibleSessionIDs = await input.readGloballyVisibleSessionIDs();
+		// planRestore enforces payload/destination/inventory schema and the full
+		// preflight; the cast only satisfies the static boundary (the runtime
+		// value is unknown).
+		const plan = planRestore({
+			payload: payload as CheckpointPayload,
+			artifactIdentity: authenticated.artifactIdentity,
+			destination,
+			globallyVisibleSessionIDs,
+			idDeriver: input.idDeriver,
+		});
+		return { status: "planned", plan, targetDirectory: input.targetDirectory };
+	} finally {
+		// Best-effort only (A-07); always zeroed on success and every failure path.
+		zeroPasswordBestEffort(password);
+	}
+}
+
+/**
+ * Strict UTF-8 decode of the authenticated payload bytes, then `JSON.parse`
+ * to `unknown`. `fatal: true` rejects invalid byte sequences; `ignoreBOM:
+ * true` keeps a leading BOM as a character instead of silently stripping it,
+ * so it fails JSON parsing rather than being normalized away. No Unicode
+ * normalization is applied. Schema validation is left to `planRestore`.
+ */
+function parseAuthenticatedJson(bytes: Uint8Array): unknown {
+	const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+	return JSON.parse(text) as unknown;
+}

package/src/tui/orchestration/shared.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared injected-boundary types and fail-closed validation for the Phase 4
+ * orchestration helpers (`fix-57`).
+ *
+ * This module contains no host, filesystem, crypto, or UI code: every effect
+ * is supplied by the caller. It exists so the checkpoint flow and the restore
+ * preflight can share one password-provider contract and one best-effort
+ * zeroing helper without importing each other.
+ */
+
+import type { ByteSource } from "../../core/contracts/index.ts";
+
+/** Which command requested the password; only used for provider context, never for policy. */
+export type PasswordPurpose = "checkpoint" | "restore";
+
+/**
+ * Interactive password-provider callback.
+ *
+ * Resolves with the password bytes (UTF-8, no normalization — owner decision
+ * recorded in O-07) or `undefined` when the user canceled. Ownership of a
+ * resolved `Uint8Array` transfers to the orchestration helper, which
+ * best-effort zeroes it in a `finally` block; the provider (and the UI behind
+ * it) must not retain or reuse the array after resolving.
+ *
+ * The callback is expected to own all interactive retry/confirmation loops:
+ * the owner-decided checkpoint two-entry match loop and the restore
+ * three-attempt loop are not implemented here, and this helper calls the
+ * provider once per command run. It makes no attempt to classify a rejected
+ * password as "wrong password" versus "corrupt artifact".
+ */
+export type PasswordProvider = (purpose: PasswordPurpose) => Promise<Uint8Array | undefined>;
+
+/**
+ * Best-effort overwrite of the password array owned by the orchestration
+ * helper. This is not secure deletion (A-07) and does not reach copies the
+ * provider/UI/runtime may have retained (JavaScript strings and garbage
+ * collector state are outside this module's control).
+ */
+export function zeroPasswordBestEffort(password: Uint8Array): void {
+	password.fill(0);
+}
+
+/** True for non-null, non-array object values; used on untrusted caller inputs. */
+export function isRecordValue(value: unknown): value is { readonly [key: string]: unknown } {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Wraps already-serialized plaintext bytes as a one-shot `ByteSource` so the
+ * crypto boundary's `seal` can consume the serializer's `Uint8Array` output.
+ * The single yielded chunk is the caller-provided array itself; the flow hands
+ * it over and never mutates or retains it afterwards.
+ */
+export function asOneShotByteSource(bytes: Uint8Array): ByteSource {
+	return {
+		async *[Symbol.asyncIterator](): AsyncGenerator<Uint8Array> {
+			yield bytes;
+		},
+	};
+}
+
+/** Requires a callable dependency so a missing injection fails before any effect. */
+export function requireCallable(value: unknown, label: string): void {
+	if (typeof value !== "function") {
+		throw new TypeError(`${label} must be an injected function; no default is applied`);
+	}
+}
+
+/** Requires a non-empty string dependency so an omitted explicit scope fails closed. */
+export function requireNonEmptyString(value: unknown, label: string): string {
+	if (typeof value !== "string" || value.length === 0) {
+		throw new TypeError(`${label} must be an explicit non-empty string; no default is applied`);
+	}
+	return value;
+}