zigmini 1.0.0-beta.2 → 1.1.0-beta.1

package/src/attachments/service.ts

@@ -0,0 +1,729 @@
+import type { Database } from "bun:sqlite";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { VerifiedManagedCall } from "../agent/managed-call.ts";
+import type { AttachmentCleanupDeps } from "../housekeeping/collectors/attachment-cleanup.ts";
+import { moveToTrash, type Trash } from "../housekeeping/trash.ts";
+import { PROTOCOL_VERSION, type MessageReference } from "../protocol.ts";
+import { documentPrompt } from "../message-references.ts";
+import type { SecurityReceipt } from "../security-allow.ts";
+import type { SecurityOccurrence } from "../security-check.ts";
+import type { Store } from "../store.ts";
+import { NativeDocumentError, readNativeDocument, type NativeDocumentBuild, type NativeDocumentResult } from "./document-reader.ts";
+import type { ManagedBindings } from "./managed-binding.ts";
+import { DocumentPreparationError, prepareText, readPreparedText, type PreparedText } from "./prepare.ts";
+import {
+	AttachmentStoreError, type AttachmentAccepted, type AttachmentAdmission, type AttachmentCAS, type AttachmentEncoding, type AttachmentFormat, type AttachmentGate,
+	type AttachmentJob, type AttachmentManifest, type AttachmentMetadata, type AttachmentPreparation, type AttachmentRecipient, type AttachmentScope,
+	type SelectedAttachmentExport,
+} from "./types.ts";
+
+export type SelectedFile = { readonly root: string; readonly segments: readonly string[]; readonly name: string; readonly format: AttachmentFormat;
+	readonly identity: { readonly device: string; readonly inode: string; readonly size: number; readonly mtimeNs: string; readonly ctimeNs: string; readonly nlink: number } };
+export type PickerScopeRecord = AttachmentScope & { readonly principalRevision: number; readonly generation: string };
+/** Darwin selector boundary. The native descriptor rules live behind it and are proved in test/native. */
+export interface SelectorPort {
+	open(scope: PickerScopeRecord): Promise<{ pickerId: string; rootEntries: readonly { readonly name: string }[]; currentDirectoryToken: string; revision: number }>;
+	list(scope: PickerScopeRecord, id: string, input: unknown): Promise<unknown>;
+	resolve(scope: PickerScopeRecord, id: string, token: string): SelectedFile;
+	scopeOf(principal: string, id: string): PickerScopeRecord;
+	seal(id: string, source: SelectedFile, signal: AbortSignal, beforePublish: () => void): Promise<{ readonly bytes: number; readonly sha256: string }>;
+}
+export type DocumentRoute = "native-document" | "pages" | "ocr";
+export class AttachmentApiError extends Error {
+	constructor(readonly code: string, readonly status: number, readonly detail?: Record<string, unknown>) { super(code); this.name = "AttachmentApiError"; }
+}
+interface DerivedPage { readonly page: number; readonly representation: "native-text" | "ocr-text" | "rendered-image" }
+interface Derived { readonly prepared: PreparedText; readonly pages: readonly DerivedPage[] | null }
+interface CursorState { readonly g: string; readonly a: string; readonly r: string; readonly v: "text" | "pages"; readonly o: number }
+interface Options {
+	readonly store: Store; readonly runtimeHome: string; readonly selector: SelectorPort | null; readonly helper: NativeDocumentBuild | null;
+	readonly bindings: ManagedBindings; readonly emit: (principal: string, event: unknown) => void;
+	readonly agentExists: (id: string) => boolean;
+	readonly guard?: { check(texts: readonly string[]): readonly SecurityOccurrence[] | null };
+	/** Capability of the conversation's active model. A failed probe counts as text-only: OCR is always a safe representation. */
+	readonly documentRoute?: (convId: string) => DocumentRoute | Promise<DocumentRoute>;
+	readonly notice?: (convId: string, code: string) => void;
+	/** Observation point before the final revocation check. */
+	readonly beforeRelease?: () => void | Promise<void>;
+	readonly trash?: Trash;
+	readonly generation?: string;
+	/** Starts the whole-document preparation limit and returns its cancel. Tests drive expiry directly. */
+	readonly documentDeadline?: (expire: () => void, ms: number) => () => void;
+	readonly preparedTextBytes?: number;
+}
+export interface SendRequest {
+	readonly convId: string; readonly principal: string; readonly text: string; readonly images: readonly string[];
+	readonly references: readonly MessageReference[];
+	readonly src: unknown; readonly trust: unknown; readonly submissionId: string | undefined; readonly attachments: readonly string[];
+}
+export interface AdmissionPlan {
+	readonly retry: AttachmentAccepted | null; readonly findings: readonly SecurityOccurrence[] | null; readonly stableDigest: string;
+	readonly admission: AttachmentAdmission | null; readonly data: Readonly<Record<string, unknown>>; readonly body: string;
+	readonly references: SendRequest["references"];
+}
+export type CommittedAdmission = AttachmentAccepted & { readonly fresh: boolean; readonly prompt: string };
+const sha = (value: string | Uint8Array) => createHash("sha256").update(value).digest("hex");
+const VISIBLE = /[^\s\u00a0\u180e\u200b-\u200f\u2028-\u202f\u205f-\u206f\u3000\ufeff]/;
+const NO_HELPER = sha("zigmini-no-native-document-helper");
+const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+const maxInFlight = 2;
+interface OcrJob { readonly key: string; readonly abort: AbortController; waiters: number; readonly promise: Promise<Derived> }
+function untilAborted<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const cancel = () => reject(new NativeDocumentError("cancelled"));
+		if (signal.aborted) { cancel(); return; }
+		signal.addEventListener("abort", cancel, { once: true });
+		work.then(resolve, reject).finally(() => signal.removeEventListener("abort", cancel));
+	});
+}
+const PDF_PREPARATION_MS = 600_000;
+const PDF_PREPARED_TEXT_BYTES = 20 * 1024 * 1024;
+const timerDeadline = (expire: () => void, ms: number) => { const timer = setTimeout(expire, ms); return () => clearTimeout(timer); };
+/** What a revoke or cleanup cannot take back; the owner sees these with every receipt. */
+export const REVOCATION_LIMITS = ["model_context_already_supplied", "downloaded_copies", "user_derived_outputs", "committed_collaboration_copies"] as const;
+const object = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+export const inspectionDigest = (text: string, preparations: readonly Pick<AttachmentPreparation, "inspectedTextSha256">[]) =>
+	sha(JSON.stringify([text, ...preparations.map(p => p.inspectedTextSha256)]));
+
+export class AttachmentService {
+	private readonly running = new Map<string, Promise<void>>();
+	private readonly aborts = new Map<string, AbortController>();
+	private readonly cleaning = new Map<string, Promise<void>>();
+	private readonly ocrJobs = new Map<string, OcrJob>();
+	private active = 0;
+	private readonly waiting: (() => void)[] = [];
+	readonly generation: string;
+	readonly gate: AttachmentGate;
+	private readonly preparedTextBytes: number;
+	constructor(private readonly o: Options) {
+		this.generation = o.generation ?? randomUUID();
+		this.preparedTextBytes = o.preparedTextBytes ?? PDF_PREPARED_TEXT_BYTES;
+		this.gate = { current: (tx, scope) => this.current(tx, scope), original: (_tx, id) => this.originalFacts(id),
+			inspect: (_tx, admission, preparations) => {
+				if (admission.inspectedTextSha256 !== inspectionDigest(admission.text, preparations)) throw new AttachmentStoreError("attachment_manifest_conflict");
+				return undefined;
+			} };
+	}
+	get bindings(): ManagedBindings { return this.o.bindings; }
+
+	/** Standalone lifecycle adapter: deleting an agent advances its epoch, so a restored agent never matches an older scope. */
+	private current(tx: Database, scope: AttachmentScope) {
+		const row = tx.query<{ agent_id: string | null; hidden: number }, [string]>("SELECT agent_id,hidden FROM conversations WHERE id=?").get(scope.convId);
+		if (!row || (row.agent_id && (row.hidden === 1 || !this.o.agentExists(row.agent_id)))) throw new AttachmentStoreError("attachment_scope_mismatch");
+		const recipient: AttachmentRecipient = row.agent_id ? { kind: "agent", id: row.agent_id, epoch: this.o.store.attachments.recipientEpoch(row.agent_id) } : { kind: "main", id: "main", epoch: 1 };
+		return { convEpoch: 1, recipient, ownerActive: this.ownerActive(scope.ownerPrincipal) };
+	}
+	ownerActive(principal: string): boolean {
+		if (principal.startsWith("web:")) return true;
+		const [, id, revision] = /^device:([^:]+):(.+)$/.exec(principal) ?? [];
+		if (!id || !revision) return false;
+		const device = this.o.store.getDevice(id);
+		return device?.status === "approved" && deviceRevision(device) === revision;
+	}
+	private originalPath(id: string): string { return join(this.o.runtimeHome, "attachments", id, "original"); }
+	private readOriginal(id: string): Uint8Array | null {
+		let fd: number;
+		try { fd = openSync(this.originalPath(id), constants.O_RDONLY | constants.O_NOFOLLOW); }
+		catch (error) { if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ELOOP")) return null; throw error; }
+		try {
+			const stat = fstatSync(fd);
+			if (!stat.isFile() || stat.nlink !== 1) return null;
+			return readFileSync(fd);
+		} finally { closeSync(fd); }
+	}
+	private originalFacts(id: string) {
+		const bytes = this.readOriginal(id);
+		return bytes && { bytes: bytes.length, sha256: sha(bytes) };
+	}
+	private scope(principal: string, convId: unknown, draftId: unknown): AttachmentScope {
+		if (typeof convId !== "string" || !convId || typeof draftId !== "string" || !UUID.test(draftId)) throw new AttachmentApiError("invalid_input", 400);
+		const conv = this.o.store.getConversation(convId);
+		if (!conv) throw new AttachmentApiError("attachment_scope_mismatch", 409);
+		return { ownerPrincipal: principal, draftId, convId, convEpoch: 1,
+			recipient: conv.agentId ? { kind: "agent", id: conv.agentId, epoch: this.o.store.attachments.recipientEpoch(conv.agentId) } : { kind: "main", id: "main", epoch: 1 } };
+	}
+	currentPicker = (s: AttachmentScope): boolean => {
+		const conv = this.o.store.getConversation(s.convId);
+		return !!conv && this.ownerActive(s.ownerPrincipal) && (conv.agentId ?? "main") === s.recipient.id && (!conv.agentId || this.o.agentExists(conv.agentId)) &&
+			s.recipient.epoch === this.lifecycleEpoch(s.convId);
+	};
+	lifecycleEpoch(convId: string): number {
+		const agentId = this.o.store.getConversation(convId)?.agentId;
+		return agentId ? this.o.store.attachments.recipientEpoch(agentId) : 1;
+	}
+	private assertOwner(principal: string): void {
+		if (!this.ownerActive(principal)) throw new AttachmentStoreError("attachment_owner_inactive", 403);
+	}
+	private get selector(): SelectorPort {
+		if (!this.o.selector) throw new AttachmentApiError("host_selector_unavailable", 503);
+		return this.o.selector;
+	}
+	async openPicker(principal: string, body: unknown) {
+		if (!object(body)) throw new AttachmentApiError("invalid_input", 400);
+		const scope: PickerScopeRecord = { ...this.scope(principal, body.convId, body.draftId), principalRevision: 1, generation: this.generation };
+		const opened = await this.selector.open(scope);
+		return { ...opened, rootEntries: opened.rootEntries.filter(entry => entry.name !== "Downloads") };
+	}
+	listPicker(principal: string, id: string, input: unknown) {
+		const scope = this.selector.scopeOf(principal, id);
+		this.assertOwner(principal);
+		return this.selector.list(scope, id, input);
+	}
+	private update(principal: string, id: string, conv: string): void {
+		const scope = this.o.store.attachments.ownedScope(id, principal);
+		const s = this.o.store.attachments.status(scope, id, this.gate);
+		this.o.emit(principal, { v: PROTOCOL_VERSION, id: randomUUID(), ts: new Date().toISOString(), conv, type: "attachment.updated",
+			data: { draftId: scope.draftId, attachmentId: id, revision: s.revision, state: s.state, preparation: s.preparation, readMode: s.readMode, revokedGrantIds: this.o.store.attachments.revokedGrantIds(id),
+				...(s.error ? { error: s.error } : {}) } });
+	}
+	private safely(principal: string, id: string, conv: string): void {
+		try { this.update(principal, id, conv); }
+		catch (error) { if (!(error instanceof AttachmentStoreError)) throw error; }
+	}
+	select(principal: string, pickerId: string, body: unknown): { attachmentId: string; state: string; revision: number } {
+		if (!object(body) || typeof body.entryToken !== "string" || typeof body.operationId !== "string" || Object.keys(body).length !== 2) throw new AttachmentApiError("invalid_input", 400);
+		this.assertOwner(principal);
+		const scope = this.selector.scopeOf(principal, pickerId);
+		const source = this.selector.resolve(scope, pickerId, body.entryToken);
+		const jobGeneration = randomUUID();
+		const job = this.o.store.attachments.select({ scope, operationId: body.operationId, entryIdentity: { ...source.identity }, sourceIdentity: { ...source.identity, root: source.root, segments: [...source.segments] },
+			name: source.name, format: source.format, bytes: source.identity.size, jobGeneration }, this.gate);
+		if (job.jobGeneration === jobGeneration) this.track(job.attachmentId, principal, scope.convId, signal => this.seal(job, source, principal, scope.convId, signal));
+		return { attachmentId: job.attachmentId, state: job.state, revision: job.revision };
+	}
+	private track(id: string, principal: string, conv: string, work: (signal: AbortSignal) => Promise<void>): void {
+		const abort = new AbortController();
+		this.aborts.get(id)?.abort();
+		this.aborts.set(id, abort);
+		const run = (async () => {
+			try { await this.inProcessingSlot(() => work(abort.signal)); }
+			finally {
+				if (this.aborts.get(id) === abort) this.aborts.delete(id);
+				this.safely(principal, id, conv);
+			}
+		})();
+		this.running.set(id, run);
+		void run.finally(() => { if (this.running.get(id) === run) this.running.delete(id); });
+	}
+	/** C8: every preparation and OCR started by a read shares these two slots. */
+	private async inProcessingSlot<T>(work: () => Promise<T>): Promise<T> {
+		while (this.active >= maxInFlight) await new Promise<void>(resolve => this.waiting.push(resolve));
+		this.active += 1;
+		try { return await work(); }
+		finally { this.active -= 1; this.waiting.shift()?.(); }
+	}
+	/** One job per document. Later reads with the same key join it; any other work on the document finishes first. */
+	private async documentOcr(id: string, key: string, signal: AbortSignal, work: (signal: AbortSignal) => Promise<Derived>): Promise<Derived> {
+		for (;;) {
+			const current = this.ocrJobs.get(id);
+			if (current?.key === key) return this.joinOcr(current, signal);
+			const busy = this.running.get(id);
+			if (!busy) break;
+			await untilAborted(busy, signal);
+		}
+		if (signal.aborted) throw new NativeDocumentError("cancelled");
+		const abort = new AbortController();
+		const promise = this.inProcessingSlot(() => work(abort.signal)).finally(() => {
+			if (this.ocrJobs.get(id) === job) this.ocrJobs.delete(id);
+			if (this.running.get(id) === settled) this.running.delete(id);
+		});
+		const job: OcrJob = { key, abort, waiters: 0, promise };
+		const settled = promise.then(() => undefined, () => undefined);
+		this.ocrJobs.set(id, job);
+		this.running.set(id, settled);
+		return this.joinOcr(job, signal);
+	}
+	/** With no live grant left, nothing can receive this OCR. Another grant of the file keeps it running. */
+	private stopOcrIfRevoked(id: string): void {
+		if (this.o.store.attachments.info(id).state === "revoked") this.ocrJobs.get(id)?.abort.abort();
+	}
+	/** The job stops when its last reader has gone, so a shared job survives one reader's disconnect. */
+	private async joinOcr(job: OcrJob, signal: AbortSignal): Promise<Derived> {
+		job.waiters += 1;
+		try { return await untilAborted(job.promise, signal); }
+		finally { if (--job.waiters === 0) job.abort.abort(); }
+	}
+	/** Resolves when no worker for this attachment is left. */
+	async whenSettled(id: string): Promise<void> { for (let run = this.running.get(id); run; run = this.running.get(id)) await run; }
+	private fail(id: string, cas: AttachmentCAS, error: unknown): void {
+		const code = error instanceof DocumentPreparationError || error instanceof NativeDocumentError || (error instanceof Error && "code" in error && typeof error.code === "string")
+			? String((error as { code: unknown }).code).toLowerCase() : "preparation_failed";
+		try { this.o.store.attachments.failJob(id, cas, /^[a-z][a-z0-9_]{0,79}$/.test(code) ? code : "preparation_failed"); }
+		catch (failure) { if (!(failure instanceof AttachmentStoreError)) throw failure; }
+	}
+	private async seal(job: AttachmentJob, source: SelectedFile, principal: string, conv: string, signal: AbortSignal): Promise<void> {
+		const attachments = this.o.store.attachments, cas = { expectedRevision: job.revision, jobGeneration: job.jobGeneration };
+		let sealed: { bytes: number; sha256: string };
+		try {
+			sealed = await this.selector.seal(job.attachmentId, source, signal, () => {
+				if (attachments.info(job.attachmentId).state !== "snapshotting") throw new AttachmentApiError("picker_closed", 409);
+			});
+		} catch (error) { this.fail(job.attachmentId, cas, error); return; }
+		let prepared: AttachmentJob;
+		try {
+			const after = attachments.seal(job.attachmentId, cas, sealed, this.gate);
+			this.safely(principal, job.attachmentId, conv);
+			prepared = attachments.prepare(attachments.ownedScope(job.attachmentId, principal), job.attachmentId,
+				{ expectedRevision: after.revision, operationId: randomUUID(), jobGeneration: randomUUID() }, this.gate);
+		} catch (error) {
+			if (!(error instanceof AttachmentStoreError)) throw error;
+			this.fail(job.attachmentId, cas, error);
+			return;
+		}
+		await this.prepareBody(prepared, undefined, conv, signal);
+	}
+	prepare(principal: string, id: string, body: unknown): AttachmentJob {
+		if (!object(body) || typeof body.operationId !== "string" || typeof body.expectedRevision !== "number" ||
+			(body.encoding !== undefined && typeof body.encoding !== "string")) throw new AttachmentApiError("invalid_input", 400);
+		const attachments = this.o.store.attachments, scope = attachments.ownedScope(id, principal), jobGeneration = randomUUID();
+		const encoding = body.encoding as AttachmentEncoding | undefined;
+		const job = attachments.prepare(scope, id, { expectedRevision: body.expectedRevision, operationId: body.operationId, jobGeneration, ...(encoding ? { encoding } : {}) }, this.gate);
+		if (job.jobGeneration === jobGeneration) this.track(id, principal, scope.convId, signal => this.prepareBody(job, encoding, scope.convId, signal));
+		return job;
+	}
+	private async route(convId: string): Promise<DocumentRoute> {
+		if (!this.o.documentRoute) return "pages";
+		try { return await this.o.documentRoute(convId); }
+		catch { return "ocr"; }
+	}
+	/** C4: the model selected now decides. A PDF prepared for vision is prepared again before its OCR text is inspected. */
+	private async prepareForRoute(id: string, principal: string, route: DocumentRoute): Promise<void> {
+		const attachments = this.o.store.attachments;
+		let current: ReturnType<typeof attachments.manifest>;
+		try { current = attachments.manifest(id, principal); }
+		catch (error) { if (error instanceof AttachmentStoreError) return; throw error; }
+		const info = attachments.info(id);
+		if (info.state !== "ready" || info.format !== "pdf" || current.preparation.readMode === route) return;
+		const job = attachments.prepare(current.scope, id, { expectedRevision: current.manifest.expectedRevision, operationId: randomUUID(), jobGeneration: randomUUID() }, this.gate);
+		this.track(id, principal, current.scope.convId, signal => this.prepareBody(job, undefined, current.scope.convId, signal));
+		await this.whenSettled(id);
+	}
+	private build() {
+		return { helperSourceSha256: this.o.helper?.sourceSha256 ?? NO_HELPER, helperBuildSha256: this.o.helper?.buildSha256 ?? NO_HELPER };
+	}
+	private async prepareBody(job: AttachmentJob, encoding: AttachmentEncoding | undefined, conv: string, signal: AbortSignal): Promise<void> {
+		const id = job.attachmentId, attachments = this.o.store.attachments, cas = { expectedRevision: job.revision, jobGeneration: job.jobGeneration };
+		try {
+			const original = this.readOriginal(id);
+			const info = attachments.info(id);
+			if (!original || sha(original) !== info.sha256) throw new AttachmentStoreError("attachment_original_unavailable", 410);
+			const isCurrent = () => { try { attachments.preparationWork(id, cas); return true; } catch { return false; } };
+			const route = await this.route(conv), textOnly = route === "ocr";
+			const derived = info.format === "pdf" ? await this.preparePdf(original, textOnly, signal, isCurrent) : { prepared: await prepareText(original, { format: info.format, ...(encoding ? { encoding } : {}), ...this.build() },
+				this.o.helper ? { build: this.o.helper, context: { signal, isCurrent } } : undefined), pages: null };
+			this.writeDerived(id, job.preparationRevision, derived);
+			attachments.publish(id, cas, { originalSha256: derived.prepared.originalSha256, preparationRevision: job.preparationRevision, representationSha256: derived.prepared.representationSha256,
+				inspectedTextSha256: derived.prepared.representationSha256, readMode: info.format === "pdf" ? route : "text",
+				...(derived.pages ? { pageCount: derived.pages.length } : {}) });
+		} catch (error) { this.fail(id, cas, error); }
+	}
+	private async native(original: Uint8Array, operation: "document.inspect" | "document.text" | "document.pages" | "document.ocr", options: Record<string, unknown>, signal: AbortSignal, isCurrent: () => boolean, deadline?: AbortSignal): Promise<NativeDocumentResult> {
+		if (!this.o.helper) throw new NativeDocumentError("native_reader_unavailable");
+		return readNativeDocument(this.o.helper, { original, operation, options: { format: "pdf", ...options } }, { signal, isCurrent, ...(deadline ? { deadline } : {}) });
+	}
+	/** Per-page native text and OCR. A page without visible text is never reported as read: it stays rendered-image. */
+	private async pdfDocument(original: Uint8Array, ocrPages: (page: number, nativeText: string) => boolean, signal: AbortSignal, isCurrent: () => boolean): Promise<Derived> {
+		// One limit covers every helper this document starts; each helper alone is far below it.
+		const deadline = new AbortController();
+		const cancelDeadline = (this.o.documentDeadline ?? timerDeadline)(() => deadline.abort(), PDF_PREPARATION_MS);
+		try { return await this.readPdfPages(original, ocrPages, signal, isCurrent, deadline.signal); }
+		finally { cancelDeadline(); }
+	}
+	private async readPdfPages(original: Uint8Array, ocrPages: (page: number, nativeText: string) => boolean, signal: AbortSignal, isCurrent: () => boolean, deadline: AbortSignal): Promise<Derived> {
+		const inspected = await this.native(original, "document.inspect", {}, signal, isCurrent, deadline);
+		const total = inspected.coverage.totalPages;
+		const pageText = async (operation: "document.text" | "document.ocr", page: number): Promise<string> => {
+			let text = "";
+			let cursor: NativeDocumentResult["nextCursor"];
+			do {
+				const part = await this.native(original, operation, { firstPage: page, pageLimit: 1, ...(cursor ? { cursor } : {}) }, signal, isCurrent, deadline);
+				text += part.content.flatMap(item => item.type === "text" ? [item.text] : []).join("");
+				cursor = part.nextCursor;
+			} while (cursor);
+			return text;
+		};
+		const pages: { page: number; representation: DerivedPage["representation"] }[] = [], blocks: string[] = [];
+		let bytes = 0;
+		for (let page = 1; page <= total; page++) {
+			let text = await pageText("document.text", page);
+			let representation: DerivedPage["representation"] = VISIBLE.test(text) ? "native-text" : "rendered-image";
+			if (ocrPages(page, text)) {
+				const ocr = await pageText("document.ocr", page);
+				if (VISIBLE.test(ocr)) { text = ocr; representation = "ocr-text"; }
+			}
+			pages.push({ page, representation });
+			const block = `[page ${page}: ${representation}]\n${representation === "rendered-image" ? "[no extractable text; use view=pages]" : text}`;
+			bytes += Buffer.byteLength(block) + (blocks.length > 0 ? 2 : 0);
+			if (bytes > this.preparedTextBytes) throw new NativeDocumentError("processing_limit", "output_bytes");
+			blocks.push(block);
+		}
+		const text = blocks.join("\n\n");
+		const originalSha256 = sha(original), representationSha256 = sha(text), build = this.build();
+		const optionsSha256 = sha(JSON.stringify({ version: 1, format: "pdf", ocrPages: pages.filter(p => p.representation === "ocr-text").map(p => p.page) }));
+		const prepared: PreparedText = { format: "txt", encoding: "utf-8", originalSha256, representationSha256, optionsSha256, ...build,
+			representationKey: sha(JSON.stringify([originalSha256, build.helperSourceSha256, build.helperBuildSha256, optionsSha256])),
+			text, bytes, scalars: [...text].length };
+		return { prepared, pages: pages.map(({ page, representation }) => ({ page, representation })) };
+	}
+	private preparePdf(original: Uint8Array, textOnly: boolean, signal: AbortSignal, isCurrent: () => boolean): Promise<Derived> {
+		return this.pdfDocument(original, () => textOnly, signal, isCurrent);
+	}
+	private derivedPath(id: string, name: string): string { return join(this.o.runtimeHome, "attachments", id, "derived", name); }
+	private writeDerived(id: string, revision: number, derived: Derived): void {
+		mkdirSync(join(this.o.runtimeHome, "attachments", id, "derived"), { recursive: true, mode: 0o700 });
+		writeFileSync(this.derivedPath(id, `${revision}.json`), JSON.stringify(derived), { mode: 0o600 });
+	}
+	private readDerived(id: string, revision: number): Derived | null {
+		try { return JSON.parse(readFileSync(this.derivedPath(id, `${revision}.json`), "utf8")); }
+		catch (error) { if (error instanceof Error && "code" in error && error.code === "ENOENT") return null; throw error; }
+	}
+	private lateOcrFile(id: string, revision: number): string { return this.derivedPath(id, `${revision}.ocr.json`); }
+	/** Late OCR keeps its own digest beside the approved representation, which it never overwrites. */
+	private readLateOcr(id: string, revision: number, originalSha256: string): Derived | null {
+		const ledger = this.o.store.attachments.lateOcrDigest(id, revision);
+		if (ledger === null) return null;
+		let derived: Derived;
+		try { derived = JSON.parse(readFileSync(this.lateOcrFile(id, revision), "utf8")); }
+		catch (error) { if (error instanceof Error && "code" in error && error.code === "ENOENT") return null; throw error; }
+		if (derived.prepared.originalSha256 !== originalSha256 || sha(derived.prepared.text) !== ledger || derived.prepared.representationSha256 !== ledger) throw new AttachmentApiError("representation_mismatch", 409);
+		return derived;
+	}
+	status(principal: string, id: string) { return this.o.store.attachments.status(this.o.store.attachments.ownedScope(id, principal), id, this.gate); }
+	discard(principal: string, id: string, body: unknown): AttachmentJob {
+		if (!object(body) || typeof body.expectedRevision !== "number") throw new AttachmentApiError("invalid_input", 400);
+		const attachments = this.o.store.attachments, scope = attachments.ownedScope(id, principal);
+		const job = attachments.discard(scope, id, body.expectedRevision, this.gate);
+		this.aborts.get(id)?.abort();
+		this.update(principal, id, scope.convId);
+		return job;
+	}
+	revoke(principal: string, id: string, body: unknown) {
+		if (!object(body) || typeof body.grantId !== "string" || typeof body.expectedRevision !== "number") throw new AttachmentApiError("invalid_input", 400);
+		const attachments = this.o.store.attachments, scope = attachments.ownedScope(id, principal);
+		const receipt = attachments.revoke(scope, body.grantId, body.expectedRevision, this.gate);
+		this.stopOcrIfRevoked(id);
+		this.update(principal, id, scope.convId);
+		return { ...receipt, limits: REVOCATION_LIMITS };
+	}
+	private attachmentDir(id: string): string { return join(this.o.runtimeHome, "attachments", id); }
+	/** The tombstone is durable before the move, so a failed or interrupted move is retried and bytes are never removed any other way. */
+	private moveOut(id: string): Promise<void> {
+		const active = this.cleaning.get(id);
+		if (active) return active;
+		const move = (async () => {
+			const path = this.attachmentDir(id);
+			if (lstatSync(path, { throwIfNoEntry: false })) {
+				const moved = await (this.o.trash ?? moveToTrash)(path, "attachment");
+				if (!moved.ok || moved.method !== "trash") throw new AttachmentApiError("attachment_trash_failed", 503);
+			}
+			this.o.store.attachments.markTrashed(id);
+		})().finally(() => this.cleaning.delete(id));
+		this.cleaning.set(id, move);
+		return move;
+	}
+	private assertIdle(id: string): void {
+		if (this.running.has(id)) throw new AttachmentStoreError("attachment_busy");
+	}
+	private async cleanupReceipt(id: string) {
+		if (!this.o.store.attachments.tombstoneOf(id)?.trashed) await this.moveOut(id);
+		return { id, tombstone: this.o.store.attachments.tombstoneOf(id), limits: REVOCATION_LIMITS };
+	}
+	async cleanup(principal: string, id: string, body: unknown) {
+		if (!object(body) || (body.reason !== undefined && typeof body.reason !== "string")) throw new AttachmentApiError("invalid_input", 400);
+		const attachments = this.o.store.attachments, scope = attachments.ownedScope(id, principal);
+		this.assertOwner(principal);
+		if (!attachments.tombstoneOf(id)) {
+			this.assertIdle(id);
+			attachments.tombstone(scope, id, attachments.status(scope, id, this.gate).revision, body.reason ?? "owner_cleanup", this.gate);
+		}
+		return this.cleanupReceipt(id);
+	}
+	/** Housekeeping category: an operator-selected action, never a scheduled one. */
+	readonly housekeeping: AttachmentCleanupDeps = {
+		list: () => this.o.store.attachments.cleanupRows().map(row => ({ attachmentId: row.id, target: this.attachmentDir(row.id), state: row.state, bytes: row.bytes,
+			busy: { ...row.busy, preparing: this.running.has(row.id) ? 1 : 0 } })),
+		cleanup: async id => {
+			if (!this.o.store.attachments.tombstoneOf(id)) {
+				this.assertIdle(id);
+				this.o.store.attachments.operatorTombstone(id, "operator_cleanup");
+			}
+			await this.cleanupReceipt(id);
+		},
+	};
+	/** The caller has closed the exact session first; this never touches another conversation's activation. */
+	retireRecipient(convId: string, recipientId: string, hide: () => void): void {
+		for (const id of this.o.store.attachments.retireRecipient(convId, recipientId, hide)) this.aborts.get(id)?.abort();
+		for (const id of [...this.ocrJobs.keys()]) this.stopOcrIfRevoked(id);
+		this.o.bindings.retire(convId);
+	}
+	download(principal: string, id: string): { readonly bytes: Uint8Array; readonly name: string; readonly format: AttachmentFormat } {
+		const attachments = this.o.store.attachments, scope = attachments.ownedScope(id, principal);
+		attachments.status(scope, id, this.gate);
+		const info = attachments.info(id);
+		if (info.state === "revoked") throw new AttachmentStoreError("attachment_revoked", 410);
+		if (info.state === "discarded" || !info.sha256 || info.state === "snapshotting") throw new AttachmentStoreError("attachment_not_ready");
+		const bytes = this.readOriginal(id);
+		if (!bytes || sha(bytes) !== info.sha256) throw new AttachmentStoreError("attachment_original_unavailable", 410);
+		return { bytes, name: info.name, format: info.format };
+	}
+	/** Resolve, inspect and fix the exact manifest. Nothing is stored and no bytes reach the model here. */
+	async plan(request: SendRequest): Promise<AdmissionPlan> {
+		const attachments = this.o.store.attachments;
+		this.assertOwner(request.principal);
+		if (request.submissionId === undefined || !UUID.test(request.submissionId)) throw new AttachmentStoreError("invalid_attachment_input", 400);
+		const stableDigest = sha(JSON.stringify([request.principal, request.convId, request.text, request.images, request.attachments, request.references.map(r => r.seq)]));
+		const retry = attachments.retryReceipt(request.convId, request.submissionId, stableDigest);
+		const body = request.text.trim();
+		const empty = { stableDigest, admission: null, data: {}, body, references: request.references };
+		if (retry) return { retry, findings: null, ...empty };
+		const route = await this.route(request.convId);
+		for (const id of request.attachments) await this.prepareForRoute(id, request.principal, route);
+		const referenced = request.references.flatMap(reference => (reference.attachments ?? []).map(item => item.id));
+		const ids = [...new Set([...request.attachments, ...referenced])];
+		if (ids.length === 0 || ids.length + request.images.length > 4) throw new AttachmentStoreError(ids.length === 0 ? "invalid_attachment_input" : "too_many_attachments", ids.length === 0 ? 400 : 409);
+		const rows = ids.map(id => {
+			try { return attachments.manifest(id, request.principal); }
+			catch (error) {
+				if (referenced.includes(id) && !request.attachments.includes(id) && error instanceof AttachmentStoreError) throw new AttachmentStoreError("attachment_reference_unavailable", 410);
+				throw error;
+			}
+		});
+		const first = rows[0];
+		if (!first || rows.some(row => row.scope.convId !== request.convId)) throw new AttachmentStoreError("attachment_scope_mismatch");
+		const direct = request.attachments.length ? rows.filter(row => request.attachments.includes(row.manifest.attachmentId)) : rows;
+		const draftId = direct[0]?.scope.draftId ?? first.scope.draftId;
+		if (direct.some(row => row.scope.draftId !== draftId)) throw new AttachmentStoreError("attachment_scope_mismatch");
+		const texts = rows.map(row => {
+			const derived = this.readDerived(row.manifest.attachmentId, row.manifest.preparationRevision);
+			if (!derived || sha(derived.prepared.text) !== row.preparation.inspectedTextSha256) throw new AttachmentStoreError("attachment_manifest_conflict");
+			return derived.prepared.text;
+		});
+		const manifests: AttachmentManifest[] = rows.map(row => row.manifest);
+		const text = body || `[Attached: ${rows.map(row => row.name).join(", ")}]`;
+		const data = { text, src: request.src, trust: request.trust, ...(body ? {} : { documentFallback: true }),
+			...(request.images.length ? { images: [...request.images] } : {}), ...(request.references.length ? { references: request.references } : {}),
+			...(request.attachments.length ? { attachments: [...request.attachments] } : {}) };
+		const base = { ...first.scope, draftId, ownerPrincipal: request.principal, submissionId: request.submissionId, text, attachments: manifests,
+			inspectedTextSha256: inspectionDigest(text, rows.map(row => row.preparation)) };
+		const { attachmentRequestDigest } = await import("./store.ts");
+		const admission: AttachmentAdmission = { ...base, requestDigest: attachmentRequestDigest(base, data) };
+		return { retry: null, findings: this.o.guard?.check([body, ...texts]) ?? null, stableDigest, admission, data, body, references: request.references };
+	}
+	commit(plan: AdmissionPlan, receipt?: (ref: SecurityReceipt) => void): CommittedAdmission {
+		const prompt = (attachments: readonly AttachmentMetadata[]) => documentPrompt(plan.body, attachments);
+		if (plan.retry) return { ...plan.retry, fresh: false, prompt: prompt(plan.retry.attachments) };
+		if (!plan.admission) throw new AttachmentStoreError("invalid_attachment_input", 400);
+		const accepted = this.o.store.attachments.admitOnce(plan.admission, plan.data, this.gate, plan.stableDigest, receipt);
+		return { ...accepted, fresh: true, prompt: prompt(accepted.attachments) };
+	}
+	async send(request: SendRequest): Promise<CommittedAdmission> { return this.commit(await this.plan(request)); }
+
+	private encodeCursor(state: CursorState): string { return Buffer.from(JSON.stringify(state)).toString("base64url"); }
+	private decodeCursor(raw: unknown, expected: Omit<CursorState, "o">): number {
+		if (raw === undefined) return 0;
+		if (typeof raw !== "string" || raw.length > 512) throw new AttachmentApiError("invalid_cursor", 400);
+		let state: unknown;
+		try { state = JSON.parse(Buffer.from(raw, "base64url").toString("utf8")); }
+		catch { throw new AttachmentApiError("invalid_cursor", 400); }
+		if (!object(state) || state.g !== expected.g || state.a !== expected.a || state.r !== expected.r || state.v !== expected.v ||
+			typeof state.o !== "number" || !Number.isSafeInteger(state.o) || state.o <= 0) throw new AttachmentApiError("invalid_cursor", 400);
+		return state.o;
+	}
+	/** Shared parser entry. It issues no grant and resolves no path; the gateway assembles resourceRef and receipt. */
+	async readAuthorizedDocument(input: { readonly resourceRef: { readonly kind: "owner_attachment"; readonly attachmentId: string } | { readonly kind: "collaboration_artifact"; readonly artifactId: string; readonly requestId: string };
+		readonly authorizationReceipt: SelectedAttachmentExport; readonly view: "text" | "pages"; readonly cursor?: unknown; readonly limit?: unknown }): Promise<Record<string, unknown>> {
+		if (input.resourceRef.kind !== "owner_attachment") throw new AttachmentApiError("collaboration_artifact_unavailable", 501);
+		const { attachmentId } = input.resourceRef, receipt = input.authorizationReceipt;
+		if (receipt.attachmentId !== attachmentId) throw new AttachmentStoreError("attachment_scope_mismatch");
+		const attachments = this.o.store.attachments, manifest = attachments.preparationOf(attachmentId), approved = this.readDerived(attachmentId, manifest.preparationRevision);
+		if (!approved || sha(approved.prepared.text) !== manifest.representationSha256) throw new AttachmentApiError("representation_mismatch", 409);
+		const late = input.view === "text" ? this.readLateOcr(attachmentId, manifest.preparationRevision, receipt.originalSha256) : null;
+		const derived = late ?? approved, representationSha256 = derived.prepared.representationSha256;
+		const expected = { g: receipt.sourceGrantId, a: attachmentId, r: representationSha256 };
+		const base = { attachmentId, originalSha256: receipt.originalSha256, representationSha256, truncated: false as const };
+		if (input.view === "pages") {
+			if (receipt.format !== "pdf" || !derived.pages) throw new AttachmentApiError("view_unavailable", 422, { supportedViews: ["text"] });
+			const start = this.decodeCursor(input.cursor, { ...expected, v: "pages" }) || 1;
+			const count = input.limit === undefined ? 2 : Number(input.limit);
+			if (!Number.isSafeInteger(count) || count < 1 || count > 2 || start > derived.pages.length) throw new AttachmentApiError("invalid_read_input", 400);
+			const original = this.readOriginal(attachmentId);
+			if (!original || sha(original) !== receipt.originalSha256) throw new AttachmentStoreError("attachment_original_unavailable", 410);
+			const signal = new AbortController().signal;
+			const result = await this.native(original, "document.pages", { firstPage: start, pageLimit: count }, signal, () => true);
+			const images = result.content.filter(item => item.type === "image").length, requested = Math.min(count, derived.pages.length - start + 1);
+			if (result.originalSha256 !== receipt.originalSha256 || images < requested || result.coverage.pages.length !== requested) throw new AttachmentApiError("representation_incomplete", 409);
+			const next = start + requested;
+			return { ...base, view: "pages", coverage: { totalPages: derived.pages.length, pages: result.coverage.pages.map(p => ({ page: p.page, representation: "rendered-image" })) }, content: result.content,
+				...(next <= derived.pages.length ? { nextCursor: this.encodeCursor({ ...expected, v: "pages", o: next }) } : {}) };
+		}
+		const limit = input.limit === undefined ? 2000 : Number(input.limit);
+		if (!Number.isSafeInteger(limit) || limit < 1 || limit > 2000) throw new AttachmentApiError("invalid_read_input", 400);
+		const offset = this.decodeCursor(input.cursor, { ...expected, v: "text" });
+		const p = derived.prepared;
+		if (offset >= p.scalars && offset > 0) throw new AttachmentApiError("invalid_cursor", 400);
+		const part = readPreparedText(p, { ...(offset ? { cursor: { originalSha256: p.originalSha256, representationSha256: p.representationSha256, representationKey: p.representationKey, offset } } : {}), lineLimit: limit });
+		const coverage = derived.pages ? { totalPages: derived.pages.length, pages: derived.pages } : { totalPages: 1, pages: [{ page: 1, representation: "native-text" }] };
+		return { ...base, view: "text", coverage, content: [{ type: "text", text: part.text }],
+			...(part.nextCursor ? { nextCursor: this.encodeCursor({ ...expected, v: "text", o: part.nextCursor.offset }) } : {}) };
+	}
+	/** Later text OCR is inspected on its own; an earlier approval never covers it. */
+	private async lateOcr(attachmentId: string, receipt: SelectedAttachmentExport, derived: Derived, conv: string, signal: AbortSignal): Promise<void> {
+		const revision = this.o.store.attachments.preparationOf(attachmentId).preparationRevision;
+		if (!this.o.helper || !derived.pages?.some(page => page.representation === "rendered-image") ||
+			this.readLateOcr(attachmentId, revision, receipt.originalSha256)) return;
+		const original = this.readOriginal(attachmentId);
+		if (!original) return;
+		const rendered = new Set(derived.pages.filter(page => page.representation === "rendered-image").map(page => page.page));
+		await this.documentOcr(attachmentId, `late:${revision}`, signal, async jobSignal => {
+			const updated = await this.pdfDocument(original, page => rendered.has(page), jobSignal, () => true);
+			if (updated.prepared.originalSha256 !== receipt.originalSha256) throw new AttachmentApiError("representation_mismatch", 409);
+			if (this.o.guard?.check([updated.prepared.text])) {
+				this.o.notice?.(conv, "attachment_text_held");
+				throw new AttachmentApiError("attachment_text_held", 409);
+			}
+			const manifest = this.o.store.attachments.preparationOf(attachmentId);
+			writeFileSync(this.lateOcrFile(attachmentId, manifest.preparationRevision), JSON.stringify(updated), { mode: 0o600 });
+			this.o.store.attachments.recordLateOcr(attachmentId, manifest.preparationRevision, updated.prepared.representationSha256);
+			return updated;
+		});
+	}
+	/** Managed tool entry: authenticated identity selects the recipient, and revocation decides at the release instant. */
+	async managedRead(call: VerifiedManagedCall, params: unknown, signal: AbortSignal = new AbortController().signal): Promise<Record<string, unknown>> {
+		if (!object(params) || Object.keys(params).some(key => !["attachmentId", "view", "cursor", "limit"].includes(key)) ||
+			typeof params.attachmentId !== "string" || (params.view !== "text" && params.view !== "pages")) throw new AttachmentApiError("invalid_read_input", 400);
+		if (call.operation !== "attachment.read") throw new AttachmentApiError("invalid_read_input", 400);
+		const attachments = this.o.store.attachments, attachmentId = params.attachmentId;
+		const recipient = { kind: call.role, id: call.agentId ?? "main" };
+		const receipt = attachments.activeGrant(attachmentId, call.convId, recipient, this.gate);
+		if (receipt.sourceConvEpoch !== call.convEpoch || receipt.sourceRecipientEpoch !== call.lifecycleEpoch) throw new AttachmentStoreError("attachment_scope_mismatch");
+		const lease = attachments.acquireRead(receipt, this.gate);
+		try {
+			const manifest = attachments.preparationOf(attachmentId);
+			if (params.view === "text") {
+				const derived = this.readDerived(attachmentId, manifest.preparationRevision);
+				if (derived) await this.lateOcr(attachmentId, receipt, derived, call.convId, signal);
+			}
+			const result = await this.readAuthorizedDocument({ resourceRef: { kind: "owner_attachment", attachmentId }, authorizationReceipt: receipt, view: params.view, cursor: params.cursor, limit: params.limit });
+			await this.o.beforeRelease?.();
+			if (!this.o.bindings.isCurrent(call)) throw new AttachmentApiError("stale_activation", 409);
+			attachments.releaseRead(lease, this.gate);
+			return result;
+		} catch (error) { attachments.abandonRead(lease); throw error; }
+	}
+	/** Engine ingress for one admitted native PDF. It checks the digest, stores only a reference and never forwards these bytes itself. */
+	dispatchDocuments(convId: string, attachments: readonly AttachmentMetadata[]) {
+		const documents = attachments.map(item => {
+			const receipt = this.o.store.attachments.grantReceipt(item.grantId, item.id, convId, this.recipientOf(convId), this.gate);
+			return { type: "document" as const, mimeType: "application/pdf" as const, name: item.name, data: Buffer.from(this.sealed(receipt)).toString("base64"),
+				provenance: { attachmentId: item.id, grantId: item.grantId, originalSha256: receipt.originalSha256 } };
+		});
+		return { documents, attachments: [...attachments] };
+	}
+	private recipientOf(convId: string): { readonly kind: "main" | "agent"; readonly id: string } {
+		const agentId = this.o.store.getConversation(convId)?.agentId;
+		return agentId ? { kind: "agent", id: agentId } : { kind: "main", id: "main" };
+	}
+	private sealed(receipt: SelectedAttachmentExport): Uint8Array {
+		const bytes = this.readOriginal(receipt.attachmentId);
+		if (!bytes || sha(bytes) !== receipt.originalSha256) throw new AttachmentStoreError("attachment_original_unavailable", 410);
+		return bytes;
+	}
+	/** One delivery in the engine's envelope. Called only after the grant was confirmed for this provider request. */
+	private async representation(receipt: SelectedAttachmentExport, mode: DocumentRoute, signal: AbortSignal): Promise<Record<string, unknown>> {
+		const id = receipt.attachmentId, manifest = this.o.store.attachments.preparationOf(id), derived = this.readDerived(id, manifest.preparationRevision);
+		if (!derived?.pages || sha(derived.prepared.text) !== manifest.representationSha256) throw new AttachmentApiError("representation_mismatch", 409);
+		const totalPages = derived.pages.length, bytes = this.sealed(receipt);
+		let content: readonly unknown[], pages: readonly { page: number; representation: string }[], nextCursor: string | undefined, estimatedTokens: number;
+		if (mode === "native-document") {
+			content = [{ type: "document", mimeType: "application/pdf", name: receipt.name, data: Buffer.from(bytes).toString("base64"),
+				provenance: { attachmentId: id, grantId: receipt.sourceGrantId, originalSha256: receipt.originalSha256 } }];
+			pages = derived.pages.map(page => ({ page: page.page, representation: "rendered-image" }));
+			estimatedTokens = Math.max(1000, totalPages * 3000);
+		} else if (mode === "pages") {
+			const count = Math.min(2, totalPages);
+			const result = await this.native(bytes, "document.pages", { firstPage: 1, pageLimit: count }, signal, () => true);
+			if (result.originalSha256 !== receipt.originalSha256 || result.content.filter(item => item.type === "image").length !== count) throw new AttachmentApiError("representation_incomplete", 409);
+			// The engine verifies the digest over its own parsed key order.
+			content = result.content.map(item => item.type === "image" ? { type: "image", mimeType: item.mimeType, data: item.data } : { type: "text", text: item.text });
+			pages = result.coverage.pages.map(page => ({ page: page.page, representation: "rendered-image" }));
+			if (count < totalPages) nextCursor = this.encodeCursor({ g: receipt.sourceGrantId, a: id, r: manifest.representationSha256, v: "pages", o: count + 1 });
+			estimatedTokens = count * 3000;
+		} else {
+			const ocr = manifest.readMode === "ocr" ? derived : await this.documentOcr(id, `full:${manifest.preparationRevision}`, signal, jobSignal => this.pdfDocument(bytes, () => true, jobSignal, () => true));
+			if (manifest.readMode !== "ocr" && this.o.guard?.check([ocr.prepared.text])) throw new AttachmentApiError("attachment_text_held", 409);
+			if (ocr.pages?.some(page => page.representation !== "ocr-text")) throw new AttachmentApiError("representation_incomplete", 409);
+			const part = readPreparedText(ocr.prepared, {});
+			content = [{ type: "text", text: part.text }];
+			pages = ocr.pages ?? [];
+			if (part.nextCursor) nextCursor = this.encodeCursor({ g: receipt.sourceGrantId, a: id, r: ocr.prepared.representationSha256, v: "text", o: part.nextCursor.offset });
+			estimatedTokens = Math.ceil(Buffer.byteLength(part.text) / 3);
+		}
+		const coverage = { totalPages, pages };
+		const cursor = nextCursor === undefined ? {} : { nextCursor };
+		return { status: "ready", originalSha256: receipt.originalSha256, representationSha256: manifest.representationSha256,
+			payloadSha256: sha(JSON.stringify({ content, coverage, ...cursor })), grantRevision: receipt.sourceGrantRevision, estimatedTokens, content, coverage, ...cursor };
+	}
+	/** Engine resolver entry: signed session, exact live grant, epochs and digest, decided again at release. */
+	async managedDocument(call: VerifiedManagedCall, params: unknown, signal: AbortSignal = new AbortController().signal): Promise<Record<string, unknown>> {
+		if (!object(params) || Object.keys(params).some(key => !["attachmentId", "grantId", "originalSha256", "mode"].includes(key)) || call.operation !== "attachment.document" ||
+			typeof params.attachmentId !== "string" || typeof params.grantId !== "string" || typeof params.originalSha256 !== "string" ||
+			(params.mode !== "native-document" && params.mode !== "pages" && params.mode !== "ocr")) throw new AttachmentApiError("invalid_read_input", 400);
+		const attachments = this.o.store.attachments, unavailable = { status: "attachment_unavailable" };
+		const label = (error: unknown): Record<string, unknown> => {
+			if (error instanceof AttachmentStoreError) return error.code === "attachment_revoked" ? { status: "attachment_revoked" } : unavailable;
+			if (error instanceof AttachmentApiError) return error.code === "attachment_text_held" ? { status: "attachment_text_held" } : unavailable;
+			if (error instanceof NativeDocumentError) return unavailable;
+			throw error;
+		};
+		let lease: string;
+		let receipt: SelectedAttachmentExport;
+		try {
+			receipt = attachments.grantReceipt(params.grantId, params.attachmentId, call.convId, { kind: call.role, id: call.agentId ?? "main" }, this.gate);
+			if (receipt.originalSha256 !== params.originalSha256 || receipt.sourceConvEpoch !== call.convEpoch || receipt.sourceRecipientEpoch !== call.lifecycleEpoch) return unavailable;
+			lease = attachments.acquireRead(receipt, this.gate);
+		} catch (error) { return label(error); }
+		try {
+			const result = await this.representation(receipt, params.mode, signal);
+			await this.o.beforeRelease?.();
+			if (!this.o.bindings.isCurrent(call)) { attachments.abandonRead(lease); return unavailable; }
+			attachments.releaseRead(lease, this.gate);
+			return result;
+		} catch (error) { attachments.abandonRead(lease); return label(error); }
+	}
+	/** C9-2 standalone provider. 292 owns the request transaction, target policy and recipient grant. */
+	async exportSelectedAttachment(input: { readonly source: { readonly convId: string; readonly recipient: { readonly kind: "main" | "agent"; readonly id: string } }; readonly attachmentId: string; readonly targetAgentId: string; readonly operationKey: string }) {
+		const attachments = this.o.store.attachments;
+		if (typeof input.operationKey !== "string" || !input.operationKey || typeof input.targetAgentId !== "string" || !input.targetAgentId) throw new AttachmentStoreError("invalid_attachment_input", 400);
+		const eligible = attachments.activeGrant(input.attachmentId, input.source.convId, input.source.recipient, this.gate);
+		const receipt = attachments.recordExport(input.operationKey, sha(JSON.stringify([input.source, input.attachmentId, input.targetAgentId, eligible.originalSha256])), input.attachmentId, eligible);
+		const bytes = this.readOriginal(input.attachmentId);
+		if (!bytes || sha(bytes) !== receipt.originalSha256) throw new AttachmentStoreError("attachment_original_unavailable", 410);
+		return { bytes, sha256: receipt.originalSha256, format: receipt.format, name: receipt.name, receipt };
+	}
+	assertSelectedExportEligible(tx: Database, receipt: SelectedAttachmentExport): undefined {
+		return this.o.store.attachments.assertSelectedExportEligible(tx, receipt, this.gate);
+	}
+	/** Startup (C5): dead readers are gone, workers resume only from sealed bytes, and usable records are compared with their bytes. */
+	recover(): void {
+		const attachments = this.o.store.attachments;
+		attachments.clearReadLeases();
+		for (const row of attachments.unsettled()) {
+			if (attachments.recover(row.id, row.revision, randomUUID(), this.gate).state !== "sealed") continue;
+			const job = attachments.resumePreparation(row.id, randomUUID());
+			this.track(row.id, job.principal, job.convId, async signal => {
+				await Promise.resolve();
+				await this.prepareBody(job, job.encoding ?? undefined, job.convId, signal);
+			});
+		}
+		for (const row of attachments.integrityRows()) {
+			const original = this.originalFacts(row.id);
+			if (original?.bytes !== row.bytes || original.sha256 !== row.sha256) attachments.markUnavailable(row.id);
+		}
+	}
+}
+
+export const deviceRevision = (device: { readonly secretHash: string; readonly createdAt: string }): string =>
+	sha(JSON.stringify([device.secretHash, device.createdAt])).slice(0, 32);