opencode-session-port 0.0.0-stage → 0.1.0

package/src/tui/adapters/session-import.ts

@@ -0,0 +1,189 @@
+/**
+ * Host import adapter: feature-detects and invokes the public TUI client
+ * `context.client.session.import` method for one planned session record.
+ *
+ * V1 policy boundaries:
+ * - O-12/OQ-12: the required capability is probed at restore start via
+ *   `probeSessionImportCapability`, before the artifact is read or decrypted.
+ *   The probe never throws; an absent or non-callable `session.import` is
+ *   reported as `{ available: false, reason }` so the caller can show a clear
+ *   "capability unavailable, no sessions were changed" message and stop.
+ * - O-16: every invocation supplies an explicit target
+ *   (`location: { directory }`) provided by the caller. The adapter never
+ *   infers a target and never derives one from the source record. It makes no
+ *   promise that the source `info.projectID` or `info.location` survives; the
+ *   host assigns target project scope (bounded E28/E31/E33 observations only).
+ * - The planned record's `info` and `messages` are passed through verbatim:
+ *   this adapter performs no remapping, filtering, or field stripping.
+ * - Response hardening (fail closed at this dynamic boundary): the pinned
+ *   v2.0.22 public client unwraps the raw protocol `{ data: SessionInfo }`
+ *   envelope and resolves the declared `SessionInfo` directly, but the
+ *   generated client casts the JSON body to that declared type without runtime
+ *   validation. The adapter therefore re-proves the fields SessionPort relies
+ *   on and fails closed with `invalid-response` unless the resolved value is a
+ *   non-null, non-array object with nonblank string `id` and `projectID` and an
+ *   object `location` with a nonblank string `directory`, and the returned
+ *   `id` equals the planned record's `info.id`. It never expects or unwraps a
+ *   `.data` envelope, never requires the returned directory to equal the
+ *   requested target, and never requires `projectID` to equal any selected or
+ *   source ID (no such equality is contract/runtime-proven here). On success
+ *   the original response value is returned unchanged after narrowing.
+ * - Host/API errors (for example a conflict or validation rejection) propagate
+ *   unchanged; this adapter never wraps, retries, or swallows them, so
+ *   per-session failure reporting stays truthful. No retry semantics are
+ *   implemented here (O-06 remains OPEN).
+ *
+ * Evidence boundary: the public import route is Experimental and the
+ * installed declaration mismatch (`SessionDomain` omits `import`) is bounded-
+ * addressed at runtime on one Windows v2.0.22 actual-TUI host (E33, one run,
+ * one import, no retry). These adapters are validated with synthetic
+ * fake-client tests only; no real host calls or imports are made by this lane,
+ * and no cross-version or support claim follows.
+ */
+
+import type { SessionRecord } from "../../core/contracts/index.ts";
+import {
+	HostAdapterError,
+	isObjectRecord,
+	requireNonEmptyString,
+	resolveUnaryMethod,
+	type SessionImportCallInput,
+	type SessionImportResult,
+} from "./host-client.ts";
+
+/** One import request: the final planned record plus the caller's explicit target. */
+export interface SessionImportRequest {
+	/**
+	 * Final planned record from restore preflight (`planRestore`). Passed
+	 * through verbatim; the caller owns preflight validation.
+	 */
+	readonly record: SessionRecord;
+	/** Explicit destination target; always required, never inferred (O-16). */
+	readonly target: { readonly directory: string };
+}
+
+/** Capability probe outcome (O-12). `reason` is technical detail for the caller's message. */
+export type SessionImportProbe = { readonly available: true } | { readonly available: false; readonly reason: string };
+
+/** Single-session import surface. One call per planned record; no batching or retry. */
+export interface SessionImportAdapter {
+	/**
+	 * Invokes the public `session.import` once with `{ info, messages, location }`.
+	 * Resolves with the validated narrow `SessionImportResult`: the original
+	 * unwrapped host response value unchanged after fail-closed narrowing
+	 * (`invalid-response` when the response violates the declared `SessionInfo`
+	 * fields or its `id` does not match the planned record). Rejects with the
+	 * unchanged host/API error.
+	 */
+	importSession(request: SessionImportRequest): Promise<SessionImportResult>;
+}
+
+/**
+ * Feature-detects `client.session.import` as a callable. Never throws; callers
+ * must stop without importing when `available` is false.
+ */
+export function probeSessionImportCapability(client: unknown): SessionImportProbe {
+	const importMethod = resolveUnaryMethod<SessionImportCallInput>(client, "session", "import");
+	if (importMethod === undefined) {
+		return {
+			available: false,
+			reason: "The installed TUI client does not expose a callable session.import",
+		};
+	}
+	return { available: true };
+}
+
+/**
+ * Creates the import adapter. Fails closed with `capability-unavailable` when
+ * the probe would report unavailable; callers should probe first and surface
+ * the probe reason, but this factory re-checks so an import can never be
+ * attempted through an unverified surface.
+ */
+export function createSessionImportAdapter(client: unknown): SessionImportAdapter {
+	const importMethod = resolveUnaryMethod<SessionImportCallInput>(client, "session", "import");
+	if (importMethod === undefined) {
+		throw new HostAdapterError(
+			"capability-unavailable",
+			"The installed TUI client does not expose a callable session.import; refusing to import (no sessions were changed)",
+		);
+	}
+	return {
+		async importSession(request: SessionImportRequest): Promise<SessionImportResult> {
+			const response: unknown = await importMethod(buildSessionImportCall(request));
+			if (!isSessionImportResult(response)) {
+				throw new HostAdapterError(
+					"invalid-response",
+					`session.import did not return an unwrapped SessionInfo-shaped object with a nonblank string id, a nonblank string projectID, and a location.directory; received ${describeValue(response)}`,
+				);
+			}
+			if (response.id !== request.record.info["id"]) {
+				throw new HostAdapterError(
+					"invalid-response",
+					"session.import returned an id that does not match the imported record id",
+				);
+			}
+			return response;
+		},
+	};
+}
+
+/**
+ * Builds the exact public-client import payload: the planned record's `info`
+ * and `messages` verbatim plus the explicit `location` target. Validates the
+ * request shape fail-closed before any host call so malformed data is never
+ * handed to the host as a confusing API error.
+ */
+export function buildSessionImportCall(request: SessionImportRequest): SessionImportCallInput {
+	const rawRequest: unknown = request;
+	if (!isObjectRecord(rawRequest)) {
+		throw new HostAdapterError("invalid-request", "SessionImportRequest must be an object with record and target");
+	}
+	const rawRecord = rawRequest["record"];
+	if (!isObjectRecord(rawRecord) || !isObjectRecord(rawRecord["info"]) || !Array.isArray(rawRecord["messages"])) {
+		throw new HostAdapterError("invalid-request", "SessionImportRequest.record must be an object with info and messages");
+	}
+	const rawTarget = rawRequest["target"];
+	if (!isObjectRecord(rawTarget)) {
+		throw new HostAdapterError("invalid-request", "SessionImportRequest.target must be an object with a directory");
+	}
+	const directory = requireNonEmptyString(rawTarget["directory"], "SessionImportRequest.target.directory");
+	return { info: request.record.info, messages: request.record.messages, location: { directory } };
+}
+
+/* ------------------------------------------------------------------------- */
+/* Response validation (fail closed, sanitized messages)                     */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Fail-closed narrowing of one untrusted `session.import` response.
+ *
+ * The pinned v2.0.22 public client resolves the already-unwrapped `SessionInfo`
+ * (the raw protocol `{ data }` envelope is unwrapped by the generated promise
+ * client), and the generated client casts the JSON body to the declared type
+ * without runtime validation. This guard is therefore the runtime proof behind
+ * `SessionImportResult`: a non-null, non-array object with nonblank string `id`
+ * and `projectID` and an object `location` carrying a nonblank string
+ * `directory`. It never unwraps a `{ data }`-shaped object (that is not the
+ * declared unwrapped contract) and never compares directories or project IDs;
+ * the caller compares the returned `id` to the planned record separately. The
+ * predicate is trusted only after every check in this body, and the response
+ * value itself is returned unchanged (same object identity).
+ */
+function isSessionImportResult(value: unknown): value is SessionImportResult {
+	if (!isObjectRecord(value)) return false;
+	const id = value["id"];
+	if (typeof id !== "string" || id.trim().length === 0) return false;
+	const projectID = value["projectID"];
+	if (typeof projectID !== "string" || projectID.trim().length === 0) return false;
+	const location = value["location"];
+	if (!isObjectRecord(location)) return false;
+	const directory = location["directory"];
+	return typeof directory === "string" && directory.trim().length > 0;
+}
+
+/** 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-read.ts

@@ -0,0 +1,115 @@
+/**
+ * Host read adapter: maps the core `SessionReadPort` onto the actual public
+ * TUI client methods `context.client.session.list` and
+ * `context.client.message.list`.
+ *
+ * Mapping contract (v2.0.22 declaration/source research, E13/E14/E18):
+ * - `listSessions` sends exactly `{ project, limit }`, plus the opaque
+ *   `cursor` only when the core request carries one. The project scope is
+ *   always explicit and the page size is always explicit; no API default is
+ *   relied on and no extra filter (`directory`, `search`, `parentID`,
+ *   `subpath`, `order`) is ever invented.
+ * - `listMessages` sends `{ sessionID, limit, order: "asc" }` for the first
+ *   page and `{ sessionID, limit, cursor }` for later pages, mirroring the
+ *   declared constraint that `order` and `cursor` cannot be combined. No
+ *   `type` filter is ever sent, so every message variant (including secret-
+ *   shaped or tool-bearing records) is preserved; the endpoint-scoped
+ *   `sessionID` is the ownership boundary.
+ * - Responses are returned to the caller as the raw `unknown` value the
+ *   client resolved. This adapter does not parse, validate, filter, truncate,
+ *   clone, or coerce pages or records: envelope validation, snapshotting, and
+ *   fail-closed completeness checks belong to the core collector, and a
+ *   malformed or partial page must fail there, never be silently repaired
+ *   here.
+ *
+ * Capability behavior: construction fails closed with a `HostAdapterError`
+ * (`capability-unavailable`) when either method is missing or not callable,
+ * before any request is made. Method errors propagate unchanged (no wrapping)
+ * so collection failures stay truthful.
+ *
+ * Evidence boundary: declaration/source research and synthetic fake-client
+ * tests only. Runtime pagination/scope behavior against a live host is
+ * untested (OQ-10); no snapshot-consistency claim is made (O-21/OQ-23), and
+ * no cross-version or support claim follows.
+ */
+
+import type { MessageListPageRequest, SessionListPageRequest, SessionReadPort } from "../../core/sessions/index.ts";
+import {
+	HostAdapterError,
+	requireNonEmptyString,
+	requirePositiveSafeInteger,
+	resolveUnaryMethod,
+	type MessageListCallInput,
+	type SessionListCallInput,
+} from "./host-client.ts";
+
+/**
+ * Creates a `SessionReadPort` backed by the public TUI client.
+ *
+ * `client` is accepted as `unknown` (it is the host-provided
+ * `context.client`): the two required methods are resolved and validated at
+ * construction time. The returned port satisfies `SessionReadPort` exactly.
+ */
+export function createSessionReadAdapter(client: unknown): SessionReadPort {
+	const sessionList = resolveUnaryMethod<SessionListCallInput>(client, "session", "list");
+	if (sessionList === undefined) {
+		throw new HostAdapterError(
+			"capability-unavailable",
+			"The installed TUI client does not expose a callable session.list; cannot enumerate project sessions",
+		);
+	}
+	const messageList = resolveUnaryMethod<MessageListCallInput>(client, "message", "list");
+	if (messageList === undefined) {
+		throw new HostAdapterError(
+			"capability-unavailable",
+			"The installed TUI client does not expose a callable message.list; cannot enumerate session messages",
+		);
+	}
+
+	return {
+		async listSessions(request: SessionListPageRequest): Promise<unknown> {
+			return sessionList(mapSessionListRequest(request));
+		},
+		async listMessages(request: MessageListPageRequest): Promise<unknown> {
+			return messageList(mapMessageListRequest(request));
+		},
+	};
+}
+
+/**
+ * Maps one core session page request onto the declared `session.list` input.
+ * The request is validated fail-closed first: a missing/blank project or a
+ * non-explicit page size would otherwise silently broaden the query scope or
+ * fall back to an API default.
+ */
+export function mapSessionListRequest(request: SessionListPageRequest): SessionListCallInput {
+	const project = requireNonEmptyString(request?.project, "SessionListPageRequest.project");
+	const limit = requirePositiveSafeInteger(request?.limit, "SessionListPageRequest.limit");
+	if (request.cursor === undefined) {
+		return { project, limit };
+	}
+	const cursor = requireNonEmptyString(request.cursor, "SessionListPageRequest.cursor");
+	return { project, limit, cursor };
+}
+
+/**
+ * Maps one core message page request onto the declared `message.list` input.
+ * The first page carries `order: "asc"` and no cursor; later pages carry only
+ * the opaque cursor. No `type` filter is ever added. The request is validated
+ * fail-closed first (explicit session scope and page size).
+ */
+export function mapMessageListRequest(request: MessageListPageRequest): MessageListCallInput {
+	const sessionID = requireNonEmptyString(request?.sessionID, "MessageListPageRequest.sessionID");
+	const limit = requirePositiveSafeInteger(request?.limit, "MessageListPageRequest.limit");
+	if ("cursor" in request) {
+		const cursor = requireNonEmptyString(request.cursor, "MessageListPageRequest.cursor");
+		return { sessionID, limit, cursor };
+	}
+	if (request.order !== "asc") {
+		throw new HostAdapterError(
+			"invalid-request",
+			'MessageListPageRequest must carry order "asc" on the first page (the declared API cannot combine order with cursor)',
+		);
+	}
+	return { sessionID, limit, order: "asc" };
+}

package/src/tui/artifacts/files.ts

@@ -0,0 +1,285 @@
+/**
+ * Encrypted artifact filesystem adapter (Phase 4, non-visual lane; `fix-56`).
+ *
+ * Scope and boundaries:
+ * - P-15 artifact-path policy only: the default checkpoint directory is
+ *   `<projectDirectory>/.sessionport/`, default artifact filenames are
+ *   timestamped and Windows-safe, an existing artifact is never overwritten
+ *   (path resolution and exclusive creation both fail closed), and an explicit
+ *   output path overrides the default with ordinary absolute/relative
+ *   resolution. The timestamp format and the `.sessionport` filename extension
+ *   are local implementation details — not a file-format, extension, or
+ *   compatibility freeze (O-02 remains OPEN).
+ * - Bytes only: `writeEncryptedArtifact` stores the already-sealed ciphertext
+ *   `ByteSource` exactly as the crypto boundary produced it, and
+ *   `readEncryptedArtifact` lazily streams the stored ciphertext back. This
+ *   module has no crypto or password interface: it never encrypts, decrypts,
+ *   authenticates, stages plaintext, selects profiles/parameters/caps, or
+ *   creates temp files. Decryption/authentication stay in the crypto
+ *   boundary (`openAndStage`).
+ *
+ * Filesystem behavior:
+ * - `writeEncryptedArtifact` creates the file with flag `"wx"` (exclusive
+ *   create). An existing path fails with the original `EEXIST` error and is
+ *   never truncated, overwritten, or auto-regenerated; the resolver's
+ *   existence check is the early clear failure, and `"wx"` remains the
+ *   authoritative race guard. Each write is awaited before the next source
+ *   chunk is pulled (natural backpressure) and partial writes are looped to
+ *   completion; the return value is the exact number of bytes written.
+ * - On any error after the exclusive open — including a source iterator
+ *   failure, a write failure, or a close failure — only the partial file this
+ *   call created is removed, best-effort, and the original error propagates
+ *   unchanged (cleanup failures never replace it). An `EEXIST` from the open
+ *   itself performs no cleanup because this call did not create the file.
+ * - `resolveCheckpointOutputPath` ensures the default `.sessionport/`
+ *   directory exists (recursive mkdir) so the default path works on a fresh
+ *   project; explicit override paths are resolved and collision-checked only
+ *   (their parent directories are not created). The writer writes at exactly
+ *   the given path and never creates directories or temp files.
+ * - Windows safety: the generated filename uses only `[A-Za-z0-9._-]` (no
+ *   `:` from the UTC timestamp, no reserved device name), and drive-relative
+ *   explicit paths (`C:foo`) fail closed instead of silently anchoring to the
+ *   per-drive current directory.
+ */
+
+/// <reference types="node" />
+import { lstat, mkdir, open, unlink } from "node:fs/promises";
+import * as path from "node:path";
+import type { ByteSource } from "../../core/contracts/index.ts";
+
+/* ------------------------------------------------------------------------- */
+/* Errors                                                                    */
+/* ------------------------------------------------------------------------- */
+
+/** Stable machine-readable failure codes for artifact path/file handling. */
+export type ArtifactFileErrorCode =
+	/** The caller supplied an unusable path, timestamp, or option value. */
+	| "invalid-request"
+	/** The resolved output path already exists; nothing is overwritten. */
+	| "path-exists";
+
+/**
+ * Fail-closed artifact path/input error. Filesystem and source errors from an
+ * in-progress write are never wrapped in this class: they propagate unchanged
+ * so failure reporting stays truthful (only the resolver's early collision
+ * check and caller-input validation use this type).
+ */
+export class ArtifactFileError extends Error {
+	readonly code: ArtifactFileErrorCode;
+
+	constructor(code: ArtifactFileErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "ArtifactFileError";
+		this.code = code;
+	}
+}
+
+/* ------------------------------------------------------------------------- */
+/* Path resolution (P-15)                                                    */
+/* ------------------------------------------------------------------------- */
+
+/** Default checkpoint directory name under the project directory (P-15). */
+const CHECKPOINT_DIRECTORY_NAME = ".sessionport";
+
+/**
+ * Default filename shape. Prefix/extension and the UTC timestamp layout are
+ * implementation details (P-15/O-08), not a format or compatibility claim.
+ */
+const CHECKPOINT_FILENAME_PREFIX = "checkpoint-";
+const CHECKPOINT_FILENAME_EXTENSION = ".sessionport";
+
+/** Options for `resolveCheckpointOutputPath`. */
+export interface ResolveCheckpointOutputPathOptions {
+	/** Current project directory; the default checkpoint directory sits beneath it. */
+	readonly projectDirectory: string;
+	/**
+	 * Explicit output-path override (P-15). Absolute paths stay absolute;
+	 * relative paths resolve against `projectDirectory`. Omitted → default.
+	 */
+	readonly explicitPath?: string;
+	/** Injectable current time for deterministic default filenames (tests). */
+	readonly now?: Date;
+}
+
+/**
+ * Resolves the exact artifact output path under the P-15 policy and fails
+ * clearly (`ArtifactFileError`, code `path-exists`) when the path already
+ * exists. The path is never auto-regenerated or suffixed.
+ *
+ * Default: `<projectDirectory>/.sessionport/checkpoint-<UTC timestamp>.sessionport`
+ * (the directory is created if needed). Explicit override: normal absolute/
+ * relative resolution only — no extension, timestamp, or safety rewriting.
+ * The `.sessionport` extension and timestamp format are implementation
+ * details, not compatibility claims.
+ */
+export async function resolveCheckpointOutputPath(options: ResolveCheckpointOutputPathOptions): Promise<string> {
+	const input: unknown = options;
+	if (typeof input !== "object" || input === null) {
+		throw new ArtifactFileError("invalid-request", "resolveCheckpointOutputPath options must be an object");
+	}
+	const fields = input as {
+		readonly projectDirectory?: unknown;
+		readonly explicitPath?: unknown;
+		readonly now?: unknown;
+	};
+	const projectDirectory = requireNonEmptyString(fields.projectDirectory, "projectDirectory");
+	const now = fields.now;
+	if (now !== undefined && (!(now instanceof Date) || Number.isNaN(now.getTime()))) {
+		throw new ArtifactFileError("invalid-request", "now must be a valid Date when provided");
+	}
+
+	let resolved: string;
+	const explicitPath = fields.explicitPath;
+	if (explicitPath !== undefined) {
+		const explicit = requireNonEmptyString(explicitPath, "explicitPath");
+		rejectDriveRelativePath(explicit);
+		resolved = path.isAbsolute(explicit) ? path.resolve(explicit) : path.resolve(projectDirectory, explicit);
+	} else {
+		const defaultDirectory = path.resolve(projectDirectory, CHECKPOINT_DIRECTORY_NAME);
+		resolved = path.join(defaultDirectory, buildDefaultFilename(now ?? new Date()));
+		// The default location must be usable on a fresh project; creating the
+		// directory is idempotent and creates no file.
+		await mkdir(defaultDirectory, { recursive: true });
+	}
+
+	await assertPathDoesNotExist(resolved);
+	return resolved;
+}
+
+/**
+ * UTC timestamp formatted with only Windows-safe characters (`:` replaced by
+ * `-`, milliseconds included, `Z` suffix). Deterministic for an injected Date.
+ */
+function buildDefaultFilename(instant: Date): string {
+	const pad = (value: number, width: number): string => String(value).padStart(width, "0");
+	const date = `${pad(instant.getUTCFullYear(), 4)}-${pad(instant.getUTCMonth() + 1, 2)}-${pad(instant.getUTCDate(), 2)}`;
+	const time = `${pad(instant.getUTCHours(), 2)}-${pad(instant.getUTCMinutes(), 2)}-${pad(instant.getUTCSeconds(), 2)}-${pad(instant.getUTCMilliseconds(), 3)}`;
+	return `${CHECKPOINT_FILENAME_PREFIX}${date}T${time}Z${CHECKPOINT_FILENAME_EXTENSION}`;
+}
+
+/**
+ * Fails closed on Windows drive-relative paths (`C:foo`): they are neither
+ * absolute nor project-relative, and ordinary resolution would silently
+ * anchor them to the per-drive current directory.
+ */
+function rejectDriveRelativePath(explicitPath: string): void {
+	if (process.platform === "win32" && !path.isAbsolute(explicitPath) && path.win32.parse(explicitPath).root.length > 0) {
+		throw new ArtifactFileError(
+			"invalid-request",
+			`explicitPath must be absolute or relative to projectDirectory (drive-relative paths are not supported): ${explicitPath}`,
+		);
+	}
+}
+
+/** Rejects (code `path-exists`) when any directory entry exists at `candidate`. */
+async function assertPathDoesNotExist(candidate: string): Promise<void> {
+	try {
+		// lstat: a dangling symlink is still an existing entry and must not be overwritten.
+		await lstat(candidate);
+	} catch (error) {
+		if (isErrnoCode(error, "ENOENT")) return;
+		throw error;
+	}
+	throw new ArtifactFileError("path-exists", `Refusing to overwrite an existing artifact: ${candidate}`);
+}
+
+function isErrnoCode(value: unknown, code: string): boolean {
+	return typeof value === "object" && value !== null && (value as { readonly code?: unknown }).code === code;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Exclusive write / lazy read                                               */
+/* ------------------------------------------------------------------------- */
+
+/** Streaming read chunk size; a fixed buffer, not a policy cap (O-03 OPEN). */
+const READ_CHUNK_BYTES = 64 * 1024;
+
+/**
+ * Writes the provided already-sealed bytes directly to `targetPath` as an
+ * exclusive new file (`"wx"`) and resolves with the exact number of bytes
+ * written. Never overwrites an existing path, never creates a temp file, and
+ * never accepts crypto/password material.
+ *
+ * Backpressure: each `FileHandle.write` is awaited before the next source
+ * chunk is pulled, and partial writes are looped to completion. On any error
+ * after the exclusive open, only the partial file this call created is
+ * removed (best-effort); the original error propagates unchanged. The parent
+ * directory must already exist (use `resolveCheckpointOutputPath` for the
+ * default location).
+ */
+export async function writeEncryptedArtifact(targetPath: string, source: ByteSource): Promise<number> {
+	const pathString = requireNonEmptyString(targetPath, "path");
+	// Exclusive create: an existing path fails with the original EEXIST and is
+	// never truncated; this open is the authoritative overwrite guard.
+	const handle = await open(pathString, "wx");
+	let closed = false;
+	try {
+		let totalBytes = 0;
+		for await (const chunk of source) {
+			if (chunk.byteLength === 0) continue;
+			let offset = 0;
+			while (offset < chunk.byteLength) {
+				const { bytesWritten } = await handle.write(chunk, offset, chunk.byteLength - offset, null);
+				if (bytesWritten < 1) {
+					throw new Error(`artifact write made no progress at byte ${totalBytes + offset}`);
+				}
+				offset += bytesWritten;
+			}
+			totalBytes += offset;
+		}
+		await handle.close();
+		closed = true;
+		return totalBytes;
+	} catch (error) {
+		if (!closed) {
+			try {
+				await handle.close();
+			} catch {
+				// Best-effort only; the original error below is authoritative.
+			}
+		}
+		try {
+			// Only the partial file this call created (exclusive open succeeded).
+			await unlink(pathString);
+		} catch {
+			// Best-effort only; cleanup failures must never replace the original error.
+		}
+		throw error;
+	}
+}
+
+/**
+ * Lazily streams the stored ciphertext bytes from `targetPath` as fresh
+ * chunks. The file is opened only when iteration starts; this function
+ * performs no decryption, authentication, plaintext staging, or file
+ * creation/deletion. Read and open errors propagate unchanged.
+ */
+export function readEncryptedArtifact(targetPath: string): ByteSource {
+	const pathString = requireNonEmptyString(targetPath, "path");
+	return {
+		async *[Symbol.asyncIterator](): AsyncGenerator<Uint8Array> {
+			const handle = await open(pathString, "r");
+			try {
+				for (;;) {
+					const chunk = new Uint8Array(READ_CHUNK_BYTES);
+					const { bytesRead } = await handle.read(chunk, 0, chunk.byteLength, null);
+					if (bytesRead === 0) return;
+					yield bytesRead === chunk.byteLength ? chunk : chunk.subarray(0, bytesRead);
+				}
+			} finally {
+				await handle.close();
+			}
+		},
+	};
+}
+
+/* ------------------------------------------------------------------------- */
+/* Small validation helpers                                                  */
+/* ------------------------------------------------------------------------- */
+
+function requireNonEmptyString(value: unknown, label: string): string {
+	if (typeof value !== "string" || value.length === 0) {
+		throw new ArtifactFileError("invalid-request", `${label} must be a non-empty string`);
+	}
+	return value;
+}