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

package/src/attachments/api.ts

@@ -0,0 +1,161 @@
+import { createHash, randomBytes } from "node:crypto";
+import { ManagedCallError, verifyManagedCall, type VerifiedManagedCall } from "../agent/managed-call.ts";
+import { maintenanceAuth } from "../maintenance.ts";
+import type { DeviceRecord, Store } from "../store.ts";
+import { AttachmentApiError, deviceRevision, type AttachmentService } from "./service.ts";
+import { AttachmentStoreError } from "./types.ts";
+
+const COOKIE = "zigmini_host_files";
+const CUSTOM = "x-zigmini-host-files";
+const MANAGED_HEADER = "x-zigmini-managed-call";
+const READ_ROUTE = "/internal/attachment-read";
+const DOCUMENT_ROUTE = "/internal/attachment-document";
+const MAX_BODY = 16 * 1024;
+type Kind = "bootstrap" | "mutation" | "status" | "download";
+export interface RequestContext { readonly trusted: boolean; readonly device: DeviceRecord | null }
+interface Deps { readonly store: Store; readonly service: AttachmentService; readonly webOrigins: readonly string[]; readonly omoToken: string }
+const refuse = (error: string, status: number, detail?: Record<string, unknown>) => Response.json({ error, ...detail }, { status });
+const sha = (value: string) => createHash("sha256").update(value).digest("hex");
+
+function cookieValue(headers: Headers): string | null {
+	for (const part of (headers.get("cookie") ?? "").split(";")) {
+		const [name, value] = part.trim().split("=");
+		if (name === COOKIE && value) return value;
+	}
+	return null;
+}
+function contentDisposition(name: string): string {
+	const ascii = name.replace(/[^\x20-\x7e]|["\\;]/g, "_");
+	return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name).replace(/['()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)}`;
+}
+
+/** Snapshot field for a client that declared the feature; absent means the client shows the unsupported state. */
+export function snapshotCapabilities(hello: { readonly capabilities?: { readonly hostFileAttachments?: unknown } }, available: boolean): { capabilities?: { hostFileAttachments: 1 } } {
+	return hello.capabilities?.hostFileAttachments === 1 && available ? { capabilities: { hostFileAttachments: 1 } } : {};
+}
+
+export class AttachmentApi {
+	private readonly hosts: ReadonlySet<string>;
+	constructor(private readonly d: Deps) { this.hosts = new Set(d.webOrigins.map(origin => new URL(origin).host)); }
+
+	private originAllowed(headers: Headers, kind: Kind): boolean {
+		const origin = headers.get("origin");
+		if (origin !== null) return this.d.webOrigins.includes(origin);
+		if (kind === "bootstrap" || kind === "mutation") return false;
+		const referer = headers.get("referer");
+		return referer !== null && URL.canParse(referer) && this.d.webOrigins.includes(new URL(referer).origin);
+	}
+	private registered(cookie: string | null): boolean { return cookie !== null && this.d.store.attachments.selectorKnown(sha(cookie)); }
+	private mint(): { cookie: string; header: string } {
+		const cookie = randomBytes(32).toString("hex");
+		this.d.store.attachments.registerSelector(sha(cookie));
+		return { cookie, header: `${COOKIE}=${cookie}; Path=/; HttpOnly; SameSite=Strict` };
+	}
+	/** Web sockets learn the selector at upgrade; a fresh context gets its cookie on the same response. */
+	webSocketPrincipal(headers: Headers): { readonly principal: string | null; readonly setCookie?: string } {
+		if (!this.d.webOrigins.includes(headers.get("origin") ?? "") || !this.hosts.has(headers.get("host") ?? "")) return { principal: null };
+		const present = cookieValue(headers);
+		if (this.registered(present) && present) return { principal: `web:${sha(present)}` };
+		const minted = this.mint();
+		return { principal: `web:${sha(minted.cookie)}`, setCookie: minted.header };
+	}
+	devicePrincipal(device: DeviceRecord): string { return `device:${device.id}:${deviceRevision(device)}`; }
+
+	private authorize(req: Request, ctx: RequestContext, kind: Kind): { principal: string; setCookie?: string } | Response {
+		if (ctx.device) {
+			if (ctx.trusted) return refuse("forbidden", 403);
+			if (ctx.device.status !== "approved") return refuse("device_not_approved", 401);
+			return { principal: this.devicePrincipal(ctx.device) };
+		}
+		if (!ctx.trusted) return refuse("unauthorized", 401);
+		if (!this.hosts.has(req.headers.get("host") ?? "")) return refuse("forbidden_host", 403);
+		if (!this.originAllowed(req.headers, kind)) return refuse("forbidden_origin", 403);
+		if (kind !== "download" && req.headers.get(CUSTOM) !== "1") return refuse("custom_header_required", 403);
+		const present = cookieValue(req.headers);
+		if (this.registered(present) && present) return { principal: `web:${sha(present)}` };
+		if (kind !== "bootstrap") return refuse("selector_cookie_required", 403);
+		const minted = this.mint();
+		return { principal: `web:${sha(minted.cookie)}`, setCookie: minted.header };
+	}
+	private async json(req: Request): Promise<unknown> {
+		if (Number(req.headers.get("content-length") ?? 0) > MAX_BODY) throw new AttachmentApiError("invalid_input", 413);
+		const text = await req.text();
+		if (Buffer.byteLength(text) > MAX_BODY) throw new AttachmentApiError("invalid_input", 413);
+		try { return JSON.parse(text); }
+		catch { throw new AttachmentApiError("invalid_input", 400); }
+	}
+	private static failure(error: unknown): Response {
+		if (error instanceof AttachmentApiError) return refuse(error.code, error.status, error.detail);
+		if (error instanceof AttachmentStoreError) return refuse(error.code, error.status);
+		if (error instanceof ManagedCallError) return refuse(error.code, 403);
+		if (error instanceof Error && "code" in error && typeof error.code === "string") {
+			const status = error.code === "host_access_denied" ? 403 : error.code === "processing_limit" ? 413 : error.code === "native_reader_unavailable" ? 503 :
+				/^(invalid_|picker_|operation_conflict|file_changed|entry_disabled|seal_conflict)/.test(error.code) ? 409 : 500;
+			return refuse(error.code.toLowerCase(), status);
+		}
+		throw error;
+	}
+	/** Returns null for paths outside this feature; the caller has already applied the listener gate. */
+	async handle(req: Request, url: URL, ctx: RequestContext): Promise<Response | null> {
+		const path = url.pathname;
+		if (path !== "/api/host-file-pickers" && !path.startsWith("/api/host-file-pickers/") && !path.startsWith("/api/attachments/")) return null;
+		try {
+			const picker = /^\/api\/host-file-pickers(?:\/([^/]+)\/(list|select))?$/.exec(path);
+			if (picker) {
+				if (req.method !== "POST") return refuse("method_not_allowed", 405);
+				const auth = this.authorize(req, ctx, picker[1] ? "mutation" : "bootstrap");
+				if (auth instanceof Response) return auth;
+				const body = await this.json(req);
+				const { service } = this.d, id = picker[1] ?? "";
+				const response = !picker[1] ? Response.json(await service.openPicker(auth.principal, body))
+					: picker[2] === "list" ? Response.json(await service.listPicker(auth.principal, id, body))
+					: Response.json(service.select(auth.principal, id, body), { status: 202 });
+				if (auth.setCookie) response.headers.set("set-cookie", auth.setCookie);
+				return response;
+			}
+			const attachment = /^\/api\/attachments\/([^/]+)(?:\/(prepare|discard|revoke|download|cleanup))?$/.exec(path);
+			if (!attachment) return refuse("not_found", 404);
+			const id = attachment[1] ?? "", action = attachment[2];
+			if (action === "download" || !action) {
+				if (req.method !== "GET") return refuse("method_not_allowed", 405);
+				const auth = this.authorize(req, ctx, action ? "download" : "status");
+				if (auth instanceof Response) return auth;
+				if (!action) return Response.json(this.d.service.status(auth.principal, id));
+				const file = this.d.service.download(auth.principal, id);
+				return new Response(Uint8Array.from(file.bytes), { headers: { "content-type": "application/octet-stream", "content-disposition": contentDisposition(file.name),
+					"x-content-type-options": "nosniff", "content-security-policy": "default-src 'none'; sandbox", "cache-control": "no-store" } });
+			}
+			if (req.method !== "POST") return refuse("method_not_allowed", 405);
+			const auth = this.authorize(req, ctx, "mutation");
+			if (auth instanceof Response) return auth;
+			const body = await this.json(req), { service } = this.d;
+			if (action === "prepare") return Response.json(service.prepare(auth.principal, id, body), { status: 202 });
+			if (action === "cleanup") return Response.json(await service.cleanup(auth.principal, id, body));
+			return Response.json(action === "discard" ? service.discard(auth.principal, id, body) : service.revoke(auth.principal, id, body));
+		} catch (error) { return AttachmentApi.failure(error); }
+	}
+	/** Listener and bearer come first, then the signed session identity. Neither alone yields content. */
+	internalRead(req: Request, trusted: boolean): Promise<Response> {
+		return this.managed(req, trusted, READ_ROUTE, "attachment.read", (call, params) => this.d.service.managedRead(call, params, req.signal));
+	}
+	internalDocument(req: Request, trusted: boolean): Promise<Response> {
+		return this.managed(req, trusted, DOCUMENT_ROUTE, "attachment.document", (call, params) => this.d.service.managedDocument(call, params, req.signal));
+	}
+	private async managed(req: Request, trusted: boolean, route: string, operation: string, run: (call: VerifiedManagedCall, params: unknown) => Promise<Record<string, unknown>>): Promise<Response> {
+		const denied = maintenanceAuth(req, trusted, this.d.omoToken);
+		if (denied) return denied;
+		if (req.method !== "POST") return refuse("method_not_allowed", 405);
+		try {
+			const body = new Uint8Array(await req.arrayBuffer());
+			if (body.byteLength > MAX_BODY) return refuse("invalid_read_input", 413);
+			let proof: unknown;
+			try { proof = JSON.parse(Buffer.from(req.headers.get(MANAGED_HEADER) ?? "", "base64").toString("utf8")); }
+			catch { throw new ManagedCallError("invalid_proof"); }
+			const call = verifyManagedCall({ method: "POST", route, operation, body, proof }, this.d.service.bindings.resolver);
+			let params: unknown;
+			try { params = JSON.parse(new TextDecoder().decode(body)); }
+			catch { return refuse("invalid_read_input", 400); }
+			return Response.json(await run(call, params));
+		} catch (error) { return AttachmentApi.failure(error); }
+	}
+}

package/src/attachments/document-reader.ts

@@ -0,0 +1,325 @@
+import { createHash, randomUUID } from "node:crypto";
+import { open, lstat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dlopen, FFIType } from "bun:ffi";
+import type { AttachmentEncoding, AttachmentFormat } from "./types.ts";
+
+// SIZE_OK: the fixed T4 write boundary assigns this sole module the native transport,
+// strict response codec and owned child supervisor. No new shared files or auth layer.
+export type NativeDocumentErrorCode = "native_reader_unavailable" | "invalid_document_options" | "invalid_native_output"
+	| "original_mismatch" | "invalid_cursor" | "cancelled" | "stale_preparation" | "password_required" | "invalid_pdf"
+	| "encoding_required" | "unsupported_encoding" | "ocr_failed" | "processing_limit";
+export class NativeDocumentError extends Error {
+	constructor(readonly code: NativeDocumentErrorCode, readonly limit?: "original_bytes" | "output_bytes" | "rss" | "page_time" | "total_time") {
+		super(code); this.name = "NativeDocumentError";
+	}
+}
+export interface NativeTextCursor {
+	readonly originalSha256: string;
+	readonly representationSha256: string;
+	readonly offset: number;
+}
+export interface NativeDocumentOptions {
+	readonly format: AttachmentFormat;
+	readonly encoding?: AttachmentEncoding;
+	readonly firstPage?: number;
+	readonly pageLimit?: number;
+	readonly lineLimit?: number;
+	readonly cursor?: NativeTextCursor;
+}
+export type DocumentOperation = "document.inspect" | "document.text" | "document.pages" | "document.ocr";
+export interface NativeDocumentBuild {
+	/** Operator-owned prebuilt helper manifest. Never model/client inputs. */
+	readonly executable: string;
+	readonly sourceSha256: string;
+	readonly buildSha256: string;
+	readonly privateHome: string;
+}
+export interface DocumentReadContext {
+	readonly signal: AbortSignal;
+	/** Aborts when the whole-document time limit that spans several helpers has passed. */
+	readonly deadline?: AbortSignal;
+	/** Preparation revision/job-generation check, not file-read authority. No publication occurs here. */
+	readonly isCurrent: () => boolean;
+	/** Observation only; cancellation tests subscribe to actual native barriers before requesting abort. */
+	readonly onProgress?: (event: { readonly stage: "isolated" | "page-start" | "page-end" | "ocr"; readonly page: number }) => void;
+}
+export interface NativeDocumentResult {
+	readonly originalSha256: string;
+	readonly representationSha256: string;
+	readonly representationKey: string;
+	readonly optionsSha256: string;
+	readonly helperSourceSha256: string;
+	readonly helperBuildSha256: string;
+	readonly ocrRevision: number;
+	readonly coverage: { readonly totalPages: number; readonly pages: readonly {
+		readonly page: number; readonly representation: "native-text" | "rendered-image" | "ocr-text" | "verified-blank" }[] };
+	readonly content: readonly ({ readonly type: "text"; readonly text: string }
+		| { readonly type: "image"; readonly data: string; readonly mimeType: "image/jpeg" | "image/png" })[];
+	readonly textRange?: { readonly start: number; readonly end: number; readonly totalScalars: number; readonly totalBytes: number };
+	readonly nextCursor?: NativeTextCursor;
+	readonly resources: { readonly peakRss: number; readonly rssSamples: number; readonly reaped: true };
+}
+const hash = (value: string | Uint8Array): string => createHash("sha256").update(value).digest("hex");
+const shaPattern = /^[0-9a-f]{64}$/;
+function fail(): never { throw new NativeDocumentError("invalid_native_output"); }
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const record = (value: unknown): Record<string, unknown> => {
+	if (!isRecord(value)) return fail();
+	return value;
+};
+const exact = (value: Record<string, unknown>, keys: readonly string[]): void => {
+	if (Object.keys(value).some(key => !keys.includes(key))) fail();
+};
+const integer = (value: unknown, min: number, max: number): number => {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) return fail();
+	return value;
+};
+const digest = (value: unknown): string => {
+	if (typeof value !== "string" || !shaPattern.test(value)) return fail();
+	return value;
+};
+
+function options(input: NativeDocumentOptions): NativeDocumentOptions {
+	const raw = record(input);
+	exact(raw, ["format", "encoding", "firstPage", "pageLimit", "lineLimit", "cursor"]);
+	if (!["pdf", "html", "txt", "md"].includes(input.format)) throw new NativeDocumentError("invalid_document_options");
+	if (input.encoding !== undefined && !["utf-8", "utf-16le", "utf-16be", "cp949", "euc-kr"].includes(input.encoding)) {
+		throw new NativeDocumentError("invalid_document_options");
+	}
+	if (input.firstPage !== undefined) integer(input.firstPage, 1, 300);
+	if (input.pageLimit !== undefined) integer(input.pageLimit, 1, 2);
+	if (input.lineLimit !== undefined) integer(input.lineLimit, 1, 2000);
+	if (input.cursor !== undefined) {
+		exact(record(input.cursor), ["originalSha256", "representationSha256", "offset"]);
+		digest(input.cursor.originalSha256); digest(input.cursor.representationSha256);
+		integer(input.cursor.offset, 1, 20 * 1024 * 1024 - 1);
+	}
+	return Object.freeze({ ...input, ...(input.cursor ? { cursor: Object.freeze({ ...input.cursor }) } : {}) });
+}
+
+function parseTerminal(raw: unknown, request: { readonly requestId: string; readonly operation: DocumentOperation;
+	readonly originalSha256: string; readonly options: NativeDocumentOptions }) {
+	const frame = record(raw);
+	if (frame.requestId !== request.requestId) fail();
+	if (frame.type === "error") {
+		exact(frame, ["type", "requestId", "code"]);
+		const codes: readonly NativeDocumentErrorCode[] = ["password_required", "invalid_pdf", "encoding_required",
+			"unsupported_encoding", "ocr_failed", "processing_limit"];
+		const code = codes.find(code => code === frame.code);
+		if (code === undefined) fail();
+		throw new NativeDocumentError(code);
+	}
+	exact(frame, ["type", "requestId", "originalSha256", "representationSha256", "coverage", "content", "textRange", "nextCursor"]);
+	if (frame.type !== "document.complete" || digest(frame.originalSha256) !== request.originalSha256) {
+		throw new NativeDocumentError("original_mismatch");
+	}
+	const representationSha256 = digest(frame.representationSha256);
+	const coverage = record(frame.coverage);
+	exact(coverage, ["totalPages", "pages"]);
+	const totalPages = integer(coverage.totalPages, 1, 300);
+	if (!Array.isArray(coverage.pages) || coverage.pages.length > totalPages || !Array.isArray(frame.content)) fail();
+	const pages = coverage.pages.map((raw: unknown) => {
+		const page = record(raw); exact(page, ["page", "representation"]);
+		const number = integer(page.page, 1, totalPages);
+		switch (page.representation) {
+			case "native-text": case "rendered-image": case "ocr-text": case "verified-blank":
+				return { page: number, representation: page.representation };
+			default: return fail();
+		}
+	});
+	if (pages.some((page, index) => index > 0 && page.page <= (pages[index - 1]?.page ?? 0))) fail();
+	let bytes = 0, images = 0, lines = 0;
+	const imageBytes: Buffer[] = [];
+	const content = frame.content.map((raw: unknown) => {
+		const part = record(raw);
+		switch (part.type) {
+			case "text": {
+				exact(part, ["type", "text"]);
+				if (typeof part.text !== "string" || part.text.includes("\0")) return fail();
+				bytes += Buffer.byteLength(part.text);
+				lines += part.text.split("\n").length - (part.text.endsWith("\n") || part.text === "" ? 1 : 0);
+				return { type: "text", text: part.text } as const;
+			}
+			case "image": {
+				exact(part, ["type", "data", "mimeType"]);
+				if (typeof part.data !== "string" || part.data.length > Math.ceil(4 * 1024 * 1024 / 3) * 4
+					|| (part.mimeType !== "image/jpeg" && part.mimeType !== "image/png")) return fail();
+				const decoded = Buffer.from(part.data, "base64");
+				if (decoded.length === 0 || decoded.length > 4 * 1024 * 1024 || decoded.toString("base64") !== part.data) fail();
+				imageBytes.push(decoded); images++;
+				return { type: "image", data: part.data, mimeType: part.mimeType } as const;
+			}
+			default: return fail();
+		}
+	});
+	if (bytes > 48 * 1024 || lines > (request.options.lineLimit ?? 2000) || images > 2) fail();
+	const base = { originalSha256: request.originalSha256, representationSha256, coverage: { totalPages, pages }, content };
+	switch (request.operation) {
+		case "document.text": case "document.ocr": {
+			const range = record(frame.textRange); exact(range, ["start", "end", "totalScalars", "totalBytes"]);
+			const totalBytes = integer(range.totalBytes, 0, 20 * 1024 * 1024);
+			const totalScalars = integer(range.totalScalars, 0, totalBytes);
+			const start = integer(range.start, 0, totalScalars), end = integer(range.end, start, totalScalars);
+			const part = content[0];
+			if (images !== 0 || content.length !== 1 || part?.type !== "text"
+				|| Array.from(part.text).length !== end - start || start !== (request.options.cursor?.offset ?? 0)
+				|| (end === start && totalScalars !== 0)) fail();
+			const residual = totalScalars - (end - start);
+			if (totalBytes - bytes < residual || totalBytes - bytes > 4 * residual) fail();
+			if (request.options.cursor && representationSha256 !== request.options.cursor.representationSha256) fail();
+			let nextCursor: NativeTextCursor | undefined;
+			if (end < totalScalars) {
+				const next = record(frame.nextCursor); exact(next, ["originalSha256", "representationSha256", "offset"]);
+				if (next.originalSha256 !== request.originalSha256 || next.representationSha256 !== representationSha256 || next.offset !== end) fail();
+				nextCursor = { originalSha256: request.originalSha256, representationSha256, offset: end };
+			} else if (frame.nextCursor !== undefined) fail();
+			if (start === 0 && end === totalScalars && (hash(part.text) !== representationSha256 || bytes !== totalBytes)) fail();
+			return { ...base, textRange: { start, end, totalScalars, totalBytes }, ...(nextCursor ? { nextCursor } : {}) };
+		}
+		case "document.inspect":
+			if (frame.textRange !== undefined || frame.nextCursor !== undefined || content.length !== 0 || pages.length !== totalPages) fail();
+			return base;
+		case "document.pages": {
+			const first = request.options.firstPage ?? 1, end = Math.min(first + (request.options.pageLimit ?? 2), totalPages + 1);
+			if (frame.textRange !== undefined || frame.nextCursor !== undefined || images !== end - first || pages.length !== images
+				|| pages.some((page, i) => page.page !== first + i || page.representation !== "rendered-image")
+				|| hash(Buffer.concat(imageBytes)) !== representationSha256) fail();
+			return base;
+		}
+		default: {
+			const exhaustive: never = request.operation;
+			return exhaustive;
+		}
+	}
+}
+
+/** Already sealed bytes only. Callers validate grants and CAS-publish returned data themselves. */
+export async function readNativeDocument(build: NativeDocumentBuild,
+	input: { readonly original: Uint8Array; readonly operation: DocumentOperation; readonly options: NativeDocumentOptions },
+	context: DocumentReadContext): Promise<NativeDocumentResult> {
+	if (process.platform !== "darwin" || process.arch !== "arm64") throw new NativeDocumentError("native_reader_unavailable");
+	const selected = options(input.options), original = input.original;
+	if (!["document.inspect", "document.text", "document.pages", "document.ocr"].includes(input.operation)
+		|| ((input.operation === "document.inspect" || input.operation === "document.pages") && selected.cursor)) {
+		throw new NativeDocumentError("invalid_document_options");
+	}
+	if (original.length === 0 || original.length > 10 * 1024 * 1024) throw new NativeDocumentError("processing_limit", "original_bytes");
+	const sealed = Uint8Array.from(original);
+	if (context.signal.aborted) throw new NativeDocumentError("cancelled");
+	if (context.deadline?.aborted) throw new NativeDocumentError("processing_limit", "total_time");
+	if (!context.isCurrent()) throw new NativeDocumentError("stale_preparation");
+	const originalSha256 = hash(sealed);
+	if (selected.cursor && selected.cursor.originalSha256 !== originalSha256) throw new NativeDocumentError("invalid_cursor");
+	if (!shaPattern.test(build.sourceSha256) || !shaPattern.test(build.buildSha256)) throw new NativeDocumentError("native_reader_unavailable");
+	const home = await lstat(build.privateHome);
+	if (!home.isDirectory() || home.isSymbolicLink() || (home.mode & 0o077) !== 0) throw new NativeDocumentError("native_reader_unavailable");
+	const descriptor = await open(build.executable, constants.O_RDONLY | constants.O_NOFOLLOW);
+	try {
+		const stat = await descriptor.stat();
+		if (!stat.isFile() || (stat.mode & 0o111) === 0 || hash(await descriptor.readFile()) !== build.buildSha256) {
+			throw new NativeDocumentError("native_reader_unavailable");
+		}
+	} finally { await descriptor.close(); }
+	const requestId = randomUUID(), operation = input.operation;
+	const wire = JSON.stringify({ version: 1, requestId, operation, originalBase64: Buffer.from(sealed).toString("base64"), options: selected });
+	const usage = dlopen("/usr/lib/libproc.dylib", { proc_pid_rusage: { args: [FFIType.i32, FFIType.i32, FFIType.ptr], returns: FFIType.i32 } });
+	const buffer = new Uint8Array(96), view = new DataView(buffer.buffer);
+	const child = Bun.spawn([build.executable, ...(operation === "document.ocr" ? ["--ocr"] : [])], { stdin: "pipe", stdout: "pipe", stderr: "pipe",
+		env: { HOME: build.privateHome, TMPDIR: build.privateHome, LANG: "en_US.UTF-8" } });
+	let failure: NativeDocumentError | undefined, peakRss = 0, rssSamples = 0, isolated = false, ocrRevision = 0;
+	const stop = (error: NativeDocumentError) => { failure ??= error; child.kill("SIGKILL"); };
+	const abort = () => stop(new NativeDocumentError("cancelled"));
+	const expire = () => stop(new NativeDocumentError("processing_limit", "total_time"));
+	context.signal.addEventListener("abort", abort, { once: true });
+	context.deadline?.addEventListener("abort", expire, { once: true });
+	if (context.signal.aborted) abort();
+	if (context.deadline?.aborted) expire();
+	const totalTimer = setTimeout(() => stop(new NativeDocumentError("processing_limit", "total_time")), 600_000);
+	let pageTimer: ReturnType<typeof setTimeout> | undefined;
+	const measureRss = () => {
+		if (usage.symbols.proc_pid_rusage(child.pid, 0, buffer) !== 0) return;
+		const resident = Number(view.getBigUint64(64, true));
+		peakRss = Math.max(peakRss, resident); rssSamples++;
+		if (resident > 1024 * 1024 * 1024) stop(new NativeDocumentError("processing_limit", "rss"));
+	};
+	const rssTimer = setInterval(measureRss, 20);
+	const output = async () => {
+		let bytes = 0;
+		const chunks: Uint8Array[] = [];
+		for await (const chunk of child.stdout) {
+			bytes += chunk.length;
+			if (bytes > 16 * 1024 * 1024) { stop(new NativeDocumentError("processing_limit", "output_bytes")); break; }
+			chunks.push(chunk);
+		}
+		return Buffer.concat(chunks);
+	};
+	const progress = async () => {
+		const decoder = new TextDecoder("utf-8", { fatal: true });
+		let line = "", bytes = 0;
+		for await (const chunk of child.stderr) {
+			bytes += chunk.length;
+			if (bytes > 64 * 1024) { stop(new NativeDocumentError("invalid_native_output")); break; }
+			line += decoder.decode(chunk, { stream: true });
+			let boundary: number;
+			while ((boundary = line.indexOf("\n")) >= 0) {
+				const current = line.slice(0, boundary); line = line.slice(boundary + 1);
+				if (current === '{"stage":"isolated","page":0}') {
+					if (isolated) { stop(new NativeDocumentError("invalid_native_output")); continue; }
+					isolated = true;
+					// The child is alive and blocked on stdin here. A required measurement at
+					// this barrier makes even sub-20ms decodes independent of timer scheduling.
+					measureRss();
+					context.onProgress?.({ stage: "isolated", page: 0 });
+					if (!context.isCurrent()) stop(new NativeDocumentError("stale_preparation"));
+					if (!failure) { child.stdin.write(wire); await child.stdin.end(); }
+				} else if (/^\{"stage":"page-start","page":(?:[1-9]|[1-9][0-9]|[12][0-9]{2}|300)\}$/.test(current)) {
+					if (pageTimer) { stop(new NativeDocumentError("invalid_native_output")); continue; }
+					pageTimer = setTimeout(() => stop(new NativeDocumentError("processing_limit", "page_time")), 60_000);
+					const page = /"page":(\d+)/.exec(current)?.[1];
+					context.onProgress?.({ stage: "page-start", page: Number(page) });
+				} else if (/^\{"stage":"page-end","page":\d+\}$/.test(current)) {
+					clearTimeout(pageTimer); pageTimer = undefined;
+					context.onProgress?.({ stage: "page-end", page: Number(/"page":(\d+)/.exec(current)?.[1]) });
+				} else if (/^\{"stage":"ocr","page":\d+\}$/.test(current)) {
+					context.onProgress?.({ stage: "ocr", page: Number(/"page":(\d+)/.exec(current)?.[1]) });
+				} else if (/^\{"stage":"ocr-config","revision":\d+,"languages":\["ko-KR","en-US"\]\}$/.test(current)) {
+					ocrRevision = Number(/"revision":(\d+)/.exec(current)?.[1]);
+				}
+			}
+		}
+	};
+	try {
+		const [stdout, , exit] = await Promise.all([output(), progress(), child.exited]);
+		if (failure) throw failure;
+		if (!isolated || rssSamples === 0 || (operation === "document.ocr" && (!Number.isSafeInteger(ocrRevision) || ocrRevision < 1))) {
+			throw new NativeDocumentError("native_reader_unavailable");
+		}
+		if (!context.isCurrent()) throw new NativeDocumentError("stale_preparation");
+		if (!stdout.length || stdout[stdout.length - 1] !== 10 || stdout.subarray(0, -1).includes(10)) fail();
+		const frame = parseTerminal(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(stdout)),
+			{ requestId, operation, originalSha256, options: selected });
+		if (exit !== 0 || pageTimer !== undefined) fail();
+		const optionsSha256 = hash(JSON.stringify({ version: 1, operation,
+			options: { format: selected.format, encoding: selected.encoding ?? null,
+				firstPage: selected.firstPage ?? 1, pageLimit: selected.pageLimit ?? 2, lineLimit: selected.lineLimit ?? 2000 },
+			render: { edge: 1568, imageBytes: 4 * 1024 * 1024, ocrDpi: 300, pixels: 12_000_000 },
+			ocrRevision: operation === "document.ocr" ? ocrRevision : null,
+			ocrLanguages: operation === "document.ocr" ? ["ko-KR", "en-US"] : [] }));
+		return { ...frame, optionsSha256,
+			representationKey: hash(JSON.stringify([originalSha256, build.sourceSha256, build.buildSha256, optionsSha256])),
+			helperSourceSha256: build.sourceSha256, helperBuildSha256: build.buildSha256,
+			ocrRevision,
+			resources: { peakRss, rssSamples, reaped: true } };
+	} catch (error) {
+		if (error instanceof SyntaxError || error instanceof TypeError) throw new NativeDocumentError("invalid_native_output");
+		throw error;
+	} finally {
+		clearInterval(rssTimer); clearTimeout(totalTimer); clearTimeout(pageTimer);
+		context.signal.removeEventListener("abort", abort);
+		context.deadline?.removeEventListener("abort", expire);
+		child.kill("SIGKILL"); await child.exited; usage.close();
+	}
+}