dsh-ab-ocr 0.1.0

package/lib/index.js

@@ -0,0 +1,1761 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { existsSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { sandboxDenialMarker } from "@deepseek-ai/dsh-sandbox";
+import { spawn } from "node:child_process";
+import z from "@deepseek-ai/schemastery";
+//#region lib/render.js
+/**
+* Model-facing text of one ocr call's result. Pure: it reads only the canonical
+* value the call recorded, so a replayed session renders the same lines.
+* @module @deepseek-ai/dsh-ab-ocr/render
+*/
+/**
+* Describe one recognized document.
+* @param document - the document's canonical value.
+* @returns the document's result lines.
+*/
+function renderDocument(document) {
+	const scope = document.pages === document.totalPages ? String(document.pages) : document.pages + " of " + document.totalPages;
+	const lines = [
+		document.corrections > 0 ? "Corrected " + document.corrections + " heading level(s) in " + document.input : "Recognized " + document.input,
+		"Saved to " + document.output,
+		"Pages: " + scope + " | lines: " + document.lines + " | headings: " + document.headings + " | characters: " + document.chars,
+		"Removed " + document.droppedPageNumbers + " page numbers and " + document.droppedRunningHeads + " running heads; joined " + document.joinedAcrossPages + " paragraph(s) across a page break"
+	];
+	if (document.pageDir !== "") lines.push("Per-page text: " + document.pageDir);
+	lines.push("Outline: " + document.outlinePath + (document.outlineTruncated ? " (incomplete)" : ""));
+	return lines.join("\n");
+}
+/**
+* Compose the model-facing text of one call's result.
+* @param value - the canonical value the call recorded.
+* @returns one block per document, then one per failure.
+*/
+function renderOcr(value) {
+	const blocks = value.documents.map(renderDocument);
+	for (const failure of value.failures) blocks.push("Failed " + failure.input + "\n" + failure.error);
+	if (blocks.length === 0) return "Nothing was recognized.";
+	return blocks.join("\n\n---\n\n");
+}
+/** Stem used when a source name compacts to nothing. */
+const FALLBACK_STEM = "document";
+/** Characters no file name may carry: Windows' reserved set, the POSIX separator, and controls. */
+const ILLEGAL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/g;
+/** Device names Windows reserves in every directory, with or without an extension. */
+const RESERVED_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+/** Leading and trailing characters a file name may not carry on Windows. */
+const EDGE_NOISE = /^[\s.\-]+|[\s.\-]+$/g;
+/** Every spacing character Unicode offers, which the source name is stripped of. */
+const SPACES = /[\s\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/g;
+/**
+* Build the stem one source document's artifacts are named after: the source's
+* own base name with its extension dropped and every space removed.
+* @param sourcePath - the path the model asked to recognize.
+* @returns a stem with no spaces and no characters a file system rejects.
+*/
+function markdownStem(sourcePath) {
+	const text = basename(sourcePath);
+	const safe = text.slice(0, text.length - extname(text).length).replace(SPACES, "").normalize("NFC").replace(ILLEGAL_CHARACTERS, "-").replace(/-{2,}/g, "-").replace(EDGE_NOISE, "");
+	return safe === "" ? FALLBACK_STEM : safe;
+}
+/**
+* Build the Markdown file name one source document is saved under.
+* @param sourcePath - the path the model asked to recognize.
+* @returns the stem, with a leading underscore when the name is a reserved
+*   Windows device name, carrying the Markdown extension.
+*/
+function markdownFileName(sourcePath) {
+	const stem = markdownStem(sourcePath);
+	return (RESERVED_DEVICE_NAME.test(stem) ? "_" + stem : stem) + ".md";
+}
+/**
+* Build the Markdown file name one recognition's own revision is saved under,
+* used when the plain name already holds a different document.
+* @param sourcePath - the path the model asked to recognize.
+* @param digest - the recognition's content digest.
+* @returns the source's Markdown name with the digest before its extension.
+*/
+function markdownDigestFileName(sourcePath, digest) {
+	const name = markdownFileName(sourcePath);
+	return name.slice(0, name.length - 3) + "." + digest + ".md";
+}
+/**
+* Resolve where one source document's Markdown file is written.
+* @param sourcePath - the absolute path the model asked to recognize.
+* @param outputDir - the deployment's directory, or an empty string for the source's own.
+* @returns the absolute path of the Markdown file.
+*/
+function markdownPath(sourcePath, outputDir) {
+	return join(outputDir === "" ? dirname(sourcePath) : outputDir, markdownFileName(sourcePath));
+}
+/** How many digits a per-page file index carries, which keeps a 99999-page scan in lexicographic order. */
+const PAGE_INDEX_DIGITS = 5;
+/**
+* Build the file name one page's recognized text is written under.
+* @param index - the page's one-based number.
+* @returns the page file's base name.
+*/
+function pageFileName(index) {
+	return "page-" + String(index).padStart(PAGE_INDEX_DIGITS, "0") + ".txt";
+}
+//#endregion
+//#region lib/artifacts.js
+/**
+* Where one source document's artifacts live, and the content digest that names
+* the recognition they belong to.
+*
+* A source named `<stem>` under a base directory `<base>` keeps its Markdown at
+* `<base>/<stem>.md`, its records under `<base>/<pageDirName>/<stem>/`, and one
+* revision of those records under that page root's `<digest>` directory. The
+* digest covers everything a recognition is: the source path and content, the page
+* selection, and the merge options. The same digest therefore names the same record
+* on a repeat call, so the record directory is found without scanning the page root
+* — and a source whose content changed is a different recognition even when its
+* length did not change with it.
+* @module @deepseek-ai/dsh-ab-ocr/artifacts
+*/
+/** File name of the pointer to a document's newest recognition. */
+const LATEST_NAME = "latest.json";
+/** File name of a recognition's record. */
+const RECORD_NAME = "record.json";
+/** File name of a recognition's heading outline. */
+const OUTLINE_NAME = "outline.json";
+/** Characters of the digest that name a record directory. */
+const DIGEST_LENGTH = 12;
+/**
+* Resolve the base directory one source document's artifacts sit under.
+* @param sourcePath - the absolute path the model asked to recognize.
+* @param outputDir - the call's output directory, or an empty string for the source's own.
+* @returns the base directory.
+*/
+function artifactBase(sourcePath, outputDir) {
+	return outputDir === "" ? dirname(sourcePath) : outputDir;
+}
+/**
+* Resolve the paths of one source document that do not depend on a recognition.
+* @param sourcePath - the absolute path the model asked to recognize.
+* @param base - the directory the document's artifacts sit under.
+* @param pageDirName - the page directory's name under the base directory.
+* @returns the document's stable artifact paths.
+*/
+function artifactRoot(sourcePath, base, pageDirName) {
+	const stem = markdownStem(sourcePath);
+	const pageRoot = join(base, pageDirName, stem);
+	return {
+		base,
+		stem,
+		document: join(base, markdownFileName(sourcePath)),
+		pageRoot,
+		latest: join(pageRoot, LATEST_NAME)
+	};
+}
+/**
+* Resolve every path one recognition's artifacts are written to.
+* @param sourcePath - the absolute path the model asked to recognize.
+* @param base - the directory the document's artifacts sit under.
+* @param pageDirName - the page directory's name under the base directory.
+* @param digest - the recognition's content digest.
+* @returns the document's artifact paths, including this recognition's revision.
+*/
+function artifactPaths(sourcePath, base, pageDirName, digest) {
+	const root = artifactRoot(sourcePath, base, pageDirName);
+	const recordDir = join(root.pageRoot, digest);
+	return {
+		...root,
+		digest,
+		digestedDocument: join(base, markdownDigestFileName(sourcePath, digest)),
+		recordDir,
+		record: join(recordDir, RECORD_NAME),
+		outline: join(recordDir, OUTLINE_NAME)
+	};
+}
+/**
+* Identify one recognition from the values that decided its text.
+*
+* The digest follows the source's content, not merely its length: a source edited
+* without changing size is a different recognition, and an unchanged one is the
+* same recognition however often it is read.
+* @param sourcePath - the absolute path the model asked to recognize.
+* @param stamp - the source metadata the digest covers alongside its content.
+* @param sourceDigest - digest of the source bytes, or an empty string when the
+*   worker did not report one.
+* @param pageSelection - the call's page selection, or null for the whole document.
+* @param merge - the merge options the call sends.
+* @returns the first 12 hex characters of the digest.
+*/
+function digest12(sourcePath, stamp, sourceDigest, pageSelection, merge) {
+	const material = JSON.stringify([
+		sourcePath,
+		sourceDigest === "" ? stamp.size : sourceDigest,
+		stamp.mtimeMs,
+		pageSelection,
+		merge
+	]);
+	return createHash("sha256").update(material, "utf8").digest("hex").slice(0, DIGEST_LENGTH);
+}
+//#endregion
+//#region lib/sandbox.js
+/**
+* The per-call file fence this plugin writes under, and the one place a write
+* is refused.
+*
+* `@deepseek-ai/dsh-fs-sandbox` fences each mutation by a per-call policy, and
+* that policy is the only thing naming the workspace the CALLING SESSION runs
+* in: omitted, the backend falls back to the deployment's root — the directory
+* the server was launched from — and a session working anywhere else has every
+* artifact refused. The tool layer therefore resolves one policy per call and
+* stamps it onto every write.
+*
+* The policy service is read with `ctx.get('sandboxPolicy')` rather than
+* declared in `inject`, for the same reason `ctx.fs` is: a declared injection
+* makes the service a provider requirement of this row. A composition that
+* mounts the confining filesystem WITHOUT the policy service therefore composes
+* cleanly and is refused at the first call, which is the earliest point where
+* its real shape is knowable — see {@link callFence}.
+* @module @deepseek-ai/dsh-ab-ocr/sandbox
+*/
+/**
+* The structured code a confining filesystem reports a refused mutation with.
+* Matched structurally rather than by importing the error class, so a backend
+* that throws its own equivalent is still recognized as a denial.
+*/
+const SANDBOX_DENIED = "FS_SANDBOX_DENIED";
+/**
+* Resolve the policy one call writes under, refusing a composition that could
+* only ever write to the wrong place.
+* @param ctx - the registrant context, carrying the filesystem and the policy service.
+* @param request - the calling session whose cwd is the workspace root, or `undefined` for an agentless call.
+* @returns the fence to stamp onto this call's writes, or undefined when the mounted backend does not confine.
+* @throws Error when a confining backend is mounted but no policy service can name the calling session's workspace.
+*/
+function callFence(ctx, request) {
+	const policy = ctx.get("sandboxPolicy");
+	if (ctx.get("fs")?.sandboxMode === void 0) return void 0;
+	if (policy === void 0) throw new Error("dsh-ab-ocr: the mounted filesystem confines but ctx.sandboxPolicy is missing, so no workspace root can be resolved for this session and none of its artifacts could be written");
+	return policy.resolve(request ?? {});
+}
+/**
+* Whether one thrown error is the file sandbox refusing a mutation, judged by
+* the structured code the capability publishes rather than by its message text.
+* @param error - the error a write threw.
+* @returns true when a confining filesystem denied the write.
+*/
+function isSandboxDenial(error) {
+	return typeof error === "object" && error !== null && error.code === SANDBOX_DENIED;
+}
+/**
+* Write one text artifact under the call's fence. Every text this plugin
+* persists goes through here, so the fence is applied in one place and a
+* refusal is restated with the path, the mode, and the workspace to move under
+* — what the provider's own text leaves out and a caller needs.
+* @param fs - the mounted filesystem capability every write goes through.
+* @param target - the resolved target to write.
+* @param content - the complete file content.
+* @param fence - the per-call fence to stamp onto the write; absent on a bare backend.
+* @param signal - caller cancellation, forwarded to the write.
+* @throws Error as the backend raised it, or the same refusal restated with the remedy.
+*/
+async function saveText(fs, target, content, fence, signal) {
+	try {
+		await fs.writeText(target, content, void 0, signal, fence);
+	} catch (error) {
+		if (fence === void 0 || !isSandboxDenial(error)) throw error;
+		throw restated(fence, fs.processPath(target), error);
+	}
+}
+/**
+* Restate one refused write as the path, the mode, and the workspace it has to
+* move under.
+* @param fence - the fence the refused write was stamped with.
+* @param path - the target's path in the backend's execution world.
+* @param cause - the refusal the backend raised.
+* @returns the error to throw in its place, keeping the denial code a consumer keys off.
+*/
+function restated(fence, path, cause) {
+	const stamped = new Error(sandboxDenialMarker(fence.mode) + ": cannot write " + path + "; this session's workspace is " + fence.workspaceRoot + ". Name an `outputDir` inside it, or a source file inside it.", { cause });
+	stamped.code = SANDBOX_DENIED;
+	return stamped;
+}
+//#endregion
+//#region lib/records.js
+/**
+* The record of one recognition, as it is stored beside the pages it came from.
+*
+* A recognition writes three files: `record.json` holds everything the assembly
+* pass needs to rebuild the document —the merge options, the page geometry,
+* and the digest that identifies them —`outline.json` holds the heading
+* candidates the caller may correct, and `latest.json` points at the document
+* the newest recognition produced so a later call finds it without scanning.
+* This module owns that format for every reader and writer of it.
+* @module @deepseek-ai/dsh-ab-ocr/records
+*/
+/**
+* Ceiling on one artifact read back through the filesystem capability. This is a
+* fixed safety invariant rather than a deployment knob: it exists so a path that
+* is not one of this plugin's records cannot make the plugin load an arbitrarily
+* large file into memory, and a deployment tunes how large a record can get
+* through `maxPages` instead.
+*/
+const MAX_RECORD_BYTES = 67108864;
+/**
+* Read the positive whole numbers a stored array carries.
+* @param value - the parsed field.
+* @returns the numbers it carries, in order; empty for anything else.
+*/
+function wholeNumbers(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((entry) => typeof entry === "number" && Number.isInteger(entry) && entry > 0);
+}
+/**
+* Read one JSON artifact through the filesystem capability.
+* @param fs - the mounted filesystem capability.
+* @param path - the artifact's absolute path.
+* @param signal - caller cancellation.
+* @returns the parsed value, or undefined when the file is absent, unreadable,
+*   or not JSON.
+*/
+async function readJson(fs, path, signal) {
+	try {
+		const target = await fs.resolve(path);
+		const bytes = await fs.readBytes(target, signal, MAX_RECORD_BYTES);
+		return JSON.parse(Buffer.from(bytes).toString("utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* Read the pointer to a document's newest recognition.
+* @param fs - the mounted filesystem capability.
+* @param path - the `latest.json` path.
+* @param signal - caller cancellation.
+* @returns the stored pointer.
+* @throws Error when the file is missing or does not name a document and its digest.
+*/
+async function readLatest(fs, path, signal) {
+	const latest = await readJson(fs, path, signal);
+	if (latest === null || typeof latest !== "object") throw new Error("ocr cannot correct heading levels: no " + path + "; recognize the document first");
+	if (typeof latest.digest !== "string" || latest.digest === "" || typeof latest.output !== "string" || latest.output === "") throw new Error("ocr cannot correct heading levels: " + path + " names no document to correct");
+	return {
+		digest: latest.digest,
+		output: latest.output,
+		input: typeof latest.input === "string" ? latest.input : "",
+		pages: wholeNumbers(latest.pages),
+		totalPages: typeof latest.totalPages === "number" ? latest.totalPages : 0
+	};
+}
+/**
+* Read the record one recognition stored.
+* @param fs - the mounted filesystem capability.
+* @param path - the `record.json` path.
+* @param signal - caller cancellation.
+* @returns the stored record.
+* @throws Error when the file is missing or does not carry the merge options
+*   and page geometry the correction needs.
+*/
+async function readRecord(fs, path, signal) {
+	const record = await readJson(fs, path, signal);
+	if (record === null || typeof record !== "object") throw new Error("ocr cannot correct heading levels: no " + path + "; recognize the document first");
+	const merge = record.merge;
+	if (merge === void 0 || typeof merge !== "object" || merge === null) throw new Error("ocr cannot correct heading levels: " + path + " carries no merge options");
+	const geometry = record.geometry;
+	if (geometry === void 0 || typeof geometry !== "object" || geometry === null || !Array.isArray(geometry.pages)) throw new Error("ocr cannot correct heading levels: " + path + " carries no page geometry");
+	const source = record.source;
+	return {
+		digest: typeof record.digest === "string" ? record.digest : "",
+		input: typeof record.input === "string" ? record.input : "",
+		pages: wholeNumbers(record.pages),
+		totalPages: typeof record.totalPages === "number" ? record.totalPages : 0,
+		merge,
+		geometry,
+		source: {
+			size: typeof source?.size === "number" ? source.size : "",
+			mtimeMs: typeof source?.mtimeMs === "number" ? source.mtimeMs : 0
+		},
+		statUnavailable: record.statUnavailable === true
+	};
+}
+/**
+* Write one JSON artifact under the call's fence.
+* @param fs - the mounted filesystem capability.
+* @param path - the artifact's absolute path.
+* @param value - the value to store.
+* @param signal - caller cancellation.
+* @param fence - the per-call fence the confining backend judges the write by;
+*   absent on a bare backend.
+* @returns nothing, once the write settled.
+* @throws Error as the backend raised it, or the same refusal restated with the remedy.
+*/
+async function writeJson(fs, path, value, signal, fence) {
+	await saveText(fs, await fs.resolve(path), JSON.stringify(value, null, 2) + "\n", fence, signal);
+}
+//#endregion
+//#region lib/documents.js
+/**
+* Writing one recognition's artifacts: the Markdown document the reader keeps,
+* the record a later correction reads back, the outline sheet the model
+* corrects, and the pointer to the newest recognition.
+*
+* Every write goes through the mounted filesystem capability, so a deployment's
+* file policy sees it and its own backend decides how the bytes are published.
+* The plain Markdown name is never overwritten with different content: when it
+* already holds another document, the new one takes the digest name.
+* @module @deepseek-ai/dsh-ab-ocr/documents
+*/
+/**
+* Decide whether one plain Markdown path already holds this document's text.
+* @param fs - the mounted filesystem capability.
+* @param path - the path to read.
+* @param markdown - the document's text, as the worker produced it.
+* @param signal - caller cancellation.
+* @returns true when the file holds exactly this text.
+*/
+async function holdsText(fs, path, markdown, signal) {
+	const expected = Buffer.from(markdown, "utf8");
+	try {
+		const target = await fs.resolve(path);
+		const bytes = await fs.readBytes(target, signal, expected.length + 1);
+		return Buffer.from(bytes).equals(expected);
+	} catch {
+		return false;
+	}
+}
+/**
+* Choose the Markdown path one recognized document is written to.
+* @param fs - the mounted filesystem capability.
+* @param artifacts - the document's artifact paths.
+* @param markdown - the document's text, as the worker produced it.
+* @param signal - caller cancellation.
+* @returns the plain path when it is free or already holds this text, and the
+*   digest path otherwise.
+*/
+async function chooseDocument(fs, artifacts, markdown, signal) {
+	if (await fs.stat(await fs.resolve(artifacts.document), signal) === void 0) return artifacts.document;
+	if (await holdsText(fs, artifacts.document, markdown, signal)) return artifacts.document;
+	return artifacts.digestedDocument;
+}
+/**
+* Read the level corrections one recognition's stored record already carries.
+* @param fs - the mounted filesystem capability.
+* @param path - the record's path.
+* @param signal - caller cancellation.
+* @returns the corrections, or undefined when there is no record or it carries none.
+*/
+async function carriedLevels(fs, path, signal) {
+	let record;
+	try {
+		record = await readRecord(fs, path, signal);
+	} catch {
+		return;
+	}
+	const overrides = record.merge.levelOverrides;
+	return overrides === void 0 || Object.keys(overrides).length === 0 ? void 0 : overrides;
+}
+/**
+* Record the level each candidate's line was given.
+*
+* The worker reports the level the merge inferred; a correction replaces it. Both
+* are kept, because a caller re-reading the sheet after a correction has to be
+* able to see that the correction took, and what it took the place of.
+* @param outline - the candidates the merge collected.
+* @param overrides - the corrections that were applied, if any.
+* @returns the candidates, each carrying the level the document used.
+*/
+function appliedOutline(outline, overrides) {
+	return outline.map((entry) => {
+		const applied = overrides?.[entry.id];
+		if (applied === void 0) return {
+			...entry,
+			inferred: entry.level
+		};
+		return {
+			...entry,
+			inferred: entry.level,
+			level: applied <= 0 ? null : Math.min(applied, 6)
+		};
+	});
+}
+/**
+* Write one finished document and the record an assembly pass reads back.
+* @param fs - the mounted filesystem capability.
+* @param artifacts - the paths this recognition's artifacts are written to.
+* @param state - the document's state, carrying the geometry it collected.
+* @param markdown - the document's text, after any carried correction was applied.
+* @param outline - the heading candidates the merge collected.
+* @param rawOutline - the event's outline field, which may carry none.
+* @param carried - the corrections this recognition carried forward, if any.
+* @param signal - caller cancellation.
+* @param fence - the per-call fence this document and its records are written under; absent on a bare backend.
+* @returns the Markdown path this call wrote.
+*/
+async function writeDocument(fs, artifacts, state, markdown, outline, rawOutline, carried, signal, fence) {
+	const output = await chooseDocument(fs, artifacts, markdown, signal);
+	await saveText(fs, await fs.resolve(output), markdown, fence, signal);
+	state.carried = carried;
+	const record = {
+		digest: artifacts.digest,
+		input: state.job.input,
+		pages: [...state.selection],
+		totalPages: state.totalPages,
+		merge: carried === void 0 ? state.job.job.merge : {
+			...state.job.job.merge,
+			levelOverrides: carried
+		},
+		geometry: { pages: state.geometry },
+		source: {
+			size: state.job.stamp.size,
+			mtimeMs: state.job.stamp.mtimeMs
+		},
+		statUnavailable: state.job.stamp.unavailable
+	};
+	await writeJson(fs, artifacts.record, record, signal, fence);
+	if (Array.isArray(rawOutline)) await writeJson(fs, artifacts.outline, appliedOutline(outline, carried), signal, fence);
+	const latest = {
+		digest: artifacts.digest,
+		output,
+		input: state.job.input,
+		pages: [...state.selection],
+		totalPages: state.totalPages
+	};
+	await writeJson(fs, artifacts.latest, latest, signal, fence);
+	return output;
+}
+/**
+* Build the document one finished recognition reports.
+* @param state - the document's state, carrying what its start event named.
+* @param artifacts - the paths this recognition's artifacts were written to.
+* @param done - the finished-document event.
+* @param output - the Markdown path the call wrote.
+* @param pageDir - the directory holding the per-page text, or an empty string.
+* @param truncated - whether the heading candidate ceiling cut the outline short.
+* @param corrections - heading-level corrections this call applied.
+* @returns the document's canonical value.
+*/
+function recognizedDocument(state, artifacts, done, output, pageDir, truncated, corrections) {
+	return {
+		input: state.job.input,
+		output,
+		pages: state.selection.length > 0 ? state.selection.length : done.pages,
+		totalPages: state.totalPages > 0 ? state.totalPages : done.totalPages,
+		lines: done.lines,
+		headings: done.headings,
+		chars: done.chars,
+		droppedPageNumbers: done.droppedPageNumbers,
+		droppedRunningHeads: done.droppedRunningHeads,
+		joinedAcrossPages: done.joinedAcrossPages,
+		pageDir,
+		seconds: done.seconds,
+		digest: artifacts.digest,
+		selection: [...state.selection],
+		outlinePath: artifacts.outline,
+		outlineTruncated: truncated,
+		corrections
+	};
+}
+//#endregion
+//#region lib/events.js
+/**
+* Interpretation of the worker's event stream, and the per-call state that
+* interpretation accumulates.
+*
+* The worker is a separate process, so every value on this boundary is read
+* defensively: a field that is absent, of the wrong type, or carries no page
+* number is a protocol violation rather than a value to coerce. Everything an
+* event reports about one document is kept in that document's
+* {@link DocumentState} until it finishes, because the merge pass reads the
+* geometry back.
+* @module @deepseek-ai/dsh-ab-ocr/events
+*/
+/**
+* Read one worker event into the value the merge-shaped result is built from.
+* @param event - the parsed event.
+* @returns the document's counts and body, or undefined for another event.
+*/
+function readDoneEvent(event) {
+	if (event.event !== "done") return void 0;
+	return {
+		id: String(event.id ?? ""),
+		pages: Number(event.pages ?? 0),
+		totalPages: Number(event.totalPages ?? 0),
+		lines: Number(event.lines ?? 0),
+		headings: Number(event.headings ?? 0),
+		chars: Number(event.chars ?? 0),
+		droppedPageNumbers: Number(event.droppedPageNumbers ?? 0),
+		droppedRunningHeads: Number(event.droppedRunningHeads ?? 0),
+		joinedAcrossPages: Number(event.joinedAcrossPages ?? 0),
+		seconds: Number(event.seconds ?? 0),
+		markdown: String(event.markdown ?? "")
+	};
+}
+/**
+* Read one whole positive number off a worker event.
+* @param value - the event field.
+* @returns the number, or undefined when the field carries none.
+*/
+function wholeNumber(value) {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
+}
+/**
+* Read the geometry one page event carries, which an assembly pass needs back.
+* @param value - the event's `geometry` field.
+* @returns the page's geometry, or undefined when the field does not carry it.
+*/
+function readGeometry(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const geometry = value;
+	if (wholeNumber(geometry.index) === void 0) return void 0;
+	if (typeof geometry.width !== "number" || typeof geometry.height !== "number") return void 0;
+	if (!Array.isArray(geometry.lines)) return void 0;
+	return geometry;
+}
+/**
+* Read the outline a finished document reported.
+*
+* The worker reports the level the merge inferred; the candidate carries that
+* same level as its starting point until a correction replaces it.
+* @param value - the event's `outline` field.
+* @returns the outline entries, or an empty list when the field carries none.
+*/
+function readOutline(value) {
+	if (!Array.isArray(value)) return [];
+	return value.map((entry) => ({
+		...entry,
+		inferred: entry.level
+	}));
+}
+/**
+* Read the failures a finished batch reported.
+* @param value - the end event's `failures` field.
+* @returns the failures, each naming a path and its reason.
+*/
+function readFailures(value) {
+	if (!Array.isArray(value)) return [];
+	return value.map((entry) => {
+		const failure = entry;
+		return {
+			id: String(failure?.id ?? ""),
+			input: String(failure?.input ?? ""),
+			error: String(failure?.error ?? "")
+		};
+	});
+}
+/**
+* Start the record one document reports into.
+* @param job - the prepared job.
+* @returns the document's empty state.
+*/
+function documentState(job) {
+	return {
+		job,
+		selection: [],
+		totalPages: 0,
+		lastPage: 0,
+		geometry: [],
+		carried: void 0
+	};
+}
+/**
+* Report why one page event breaks the order a document's files rely on.
+* @param page - the page number the event carried.
+* @param state - what the document has reported so far.
+* @returns the problem, or undefined when the page is in order.
+*/
+function pageProblem(page, state) {
+	if (page === state.lastPage) return "page " + page + " arrived twice";
+	if (page < state.lastPage) return "page " + page + " arrived after page " + state.lastPage;
+	if (state.totalPages > 0 && page > state.totalPages) return "page " + page + " is past the last page of the document, " + state.totalPages;
+}
+/**
+* Serialize a call's artifact writes behind one chain, so two writes never race
+* for one path and a failed write is recorded once.
+* @param controller - the controller whose abort stops the recognition.
+* @returns the queue's enqueue and settle operations.
+*/
+function writeQueue(controller) {
+	let chain = Promise.resolve();
+	let failed;
+	return {
+		enqueue(task) {
+			chain = chain.then(task).catch((error) => {
+				if (failed !== void 0) return;
+				failed = error instanceof Error ? error : new Error(String(error));
+				controller.abort();
+			});
+		},
+		async settle() {
+			await chain;
+			return failed;
+		}
+	};
+}
+/**
+* Report one document's failure once, whether it arrived as its own event or in
+* the batch's closing list. The worker reports a failure both ways, and its two
+* reports agree on the job identifier as well as on the path and the reason.
+* @param call - the call collecting failures.
+* @param failure - the failure the worker reported.
+* @returns nothing.
+*/
+function reportFailure(call, failure) {
+	const keys = ["pair:" + failure.input + "\0" + failure.error];
+	if (failure.id !== "") keys.push("job:" + failure.id);
+	if (keys.some((key) => call.reported.has(key))) return;
+	for (const key of keys) call.reported.add(key);
+	call.failures.push({
+		input: failure.input,
+		error: failure.error
+	});
+}
+//#endregion
+//#region lib/levels.js
+/**
+* The `levels` request value: heading-level corrections a caller makes after
+* reading the outline a recognition saved.
+*
+* The value is compact because the model writes it: `"h12=2,h15=0,h20=3"`,
+* where the id is an outline candidate and the number is the Markdown heading
+* depth it should take. Zero, or anything below it, takes the line out of the
+* heading hierarchy and leaves it as body text, which is what makes the pass
+* able to demote a line the merge promoted. Anything else is rejected rather
+* than half-applied.
+* @module @deepseek-ai/dsh-ab-ocr/levels
+*/
+/** One correction: an outline candidate id, then the level it should take. */
+const CORRECTION = /^h([1-9][0-9]*)=(.+)$/;
+/** A level the worker accepts: a whole number, 0 or below meaning body text. */
+const LEVEL = /^-?[0-9]+$/;
+/**
+* Parse the corrections one `levels` value carries.
+* @param value - the model-supplied value.
+* @returns the candidate id to heading level corrections.
+* @throws Error when the value is empty, when a piece is not `<id>=<level>`,
+*   when the level is not a whole number, or when two pieces give one
+*   candidate different levels.
+*/
+function parseLevels(value) {
+	const trimmed = value.trim();
+	if (trimmed === "") throw new Error("invalid ocr: levels is empty; write corrections such as \"h12=2,h15=0\"");
+	const overrides = {};
+	for (const piece of trimmed.split(",")) {
+		const entry = piece.trim();
+		const match = CORRECTION.exec(entry);
+		if (match === null) throw new Error("invalid ocr: levels cannot read \"" + entry + "\"; write an outline id and its level such as \"h12=2\"");
+		const id = "h" + (match[1] ?? "");
+		const raw = match[2] ?? "";
+		if (!LEVEL.test(raw)) throw new Error("invalid ocr: levels gives \"" + raw + "\" to " + id + "; a level is a whole number, 0 for a line that is not a heading and 1 to 6 for a heading");
+		const level = Number(raw);
+		const previous = overrides[id];
+		if (previous !== void 0 && previous !== level) throw new Error("invalid ocr: levels gives " + id + " both " + String(previous) + " and " + String(level));
+		overrides[id] = level;
+	}
+	return overrides;
+}
+//#endregion
+//#region lib/plan.js
+/**
+* Request planning: which files one call recognizes, where each document's
+* artifacts go, and what the worker is told about each one.
+*
+* Everything here is decided before a worker process starts, so a call that
+* names a file the worker cannot read is reported as a failure without paying
+* for a process. The one exception is the source's own content digest, which
+* only the worker can compute; {@link prepareJob} therefore resolves the paths
+* that do not depend on a recognition, and the entry module names the rest when
+* the document reports it started.
+* @module @deepseek-ai/dsh-ab-ocr/plan
+*/
+/** Extensions the worker accepts as a still image or a PDF. */
+const SUPPORTED_EXTENSIONS = [
+	".pdf",
+	".png",
+	".jpg",
+	".jpeg",
+	".jpe",
+	".bmp",
+	".dib",
+	".tif",
+	".tiff",
+	".webp",
+	".gif",
+	".jp2",
+	".pbm",
+	".pgm",
+	".ppm",
+	".tga",
+	".ico"
+];
+/**
+* Resolve the Python executable that carries the OCR dependencies.
+* @param configured - the row's pythonPath value.
+* @param packageRoot - this package's directory.
+* @param platform - the platform the plugin is running on.
+* @returns the configured path, the package's own environment, or the platform's interpreter name.
+*/
+function resolvePython(configured, packageRoot, platform) {
+	if (configured !== "") return configured;
+	const bundled = platform === "win32" ? join(packageRoot, "python", ".venv", "Scripts", "python.exe") : join(packageRoot, "python", ".venv", "bin", "python");
+	return existsSync(bundled) ? bundled : platform === "win32" ? "python" : "python3";
+}
+/**
+* Resolve the worker script this package runs.
+* @param configured - the row's workerScript value.
+* @param packageRoot - this package's directory.
+* @returns the configured path, or the script shipped inside the package.
+*/
+function resolveWorkerScript(configured, packageRoot) {
+	return configured !== "" ? configured : join(packageRoot, "python", "ocr_worker.py");
+}
+/**
+* Resolve a deployment directory value against a base.
+* @param configured - the configured or requested directory.
+* @param base - the directory a relative value resolves against.
+* @returns the absolute directory, or an empty string when the value is empty.
+*/
+function resolveDirectory(configured, base) {
+	if (configured === "") return "";
+	return isAbsolute(configured) ? configured : resolve(base, configured);
+}
+/**
+* Collect the paths one call named, in request order and without duplicates.
+* @param args - the model-supplied call arguments.
+* @param base - the directory a relative path resolves against.
+* @param maxDocuments - documents one call may name.
+* @returns the absolute paths to recognize.
+* @throws Error when the call names no path, or more than the ceiling.
+*/
+function requestPaths(args, base, maxDocuments) {
+	const named = [...args.path === void 0 ? [] : [args.path], ...args.paths ?? []];
+	if (named.length === 0) throw new Error("invalid ocr: give path or paths with at least one file");
+	const paths = [];
+	for (const raw of named) {
+		const trimmed = raw.trim();
+		if (trimmed === "") throw new Error("invalid ocr: path must be a non-empty string");
+		const absolute = isAbsolute(trimmed) ? trimmed : resolve(base, trimmed);
+		if (!paths.includes(absolute)) paths.push(absolute);
+	}
+	if (paths.length > maxDocuments) throw new Error("invalid ocr: one call recognizes at most " + maxDocuments + " files");
+	return paths;
+}
+/**
+* Report why a path cannot be recognized, before any process is started.
+* @param path - the absolute path to check.
+* @returns the reason, or undefined when the worker can read the path.
+*/
+function rejectPath(path) {
+	if (!existsSync(path)) return "no such file: " + path;
+	const lower = path.toLowerCase();
+	if (!SUPPORTED_EXTENSIONS.some((extension) => lower.endsWith(extension))) return "unsupported file type: neither a PDF nor a supported image";
+}
+/**
+* Collect the merge switches and thresholds one call sends.
+* @param config - the deployment's values.
+* @returns the merge options, in the names the worker reads them under.
+*/
+function mergeOptions(config) {
+	return {
+		removePageNumbers: config.removePageNumbers,
+		removeRunningHeads: config.removeRunningHeads,
+		runningHeadRatio: config.runningHeadRatio,
+		runningHeadMinPages: config.runningHeadMinPages,
+		detectHeadings: config.detectHeadings,
+		headingMinRatio: config.headingMinRatio,
+		indentRatio: config.indentRatio,
+		paragraphGapRatio: config.paragraphGapRatio,
+		outlineCandidateRatio: config.outlineCandidateRatio,
+		maxOutlineCandidates: config.maxOutlineCandidates
+	};
+}
+/**
+* Resolve the directory one call's artifacts are written to: the call's own
+* request when it made one, otherwise the deployment's configured directory.
+* @param args - the model-supplied call arguments.
+* @param config - the deployment's values.
+* @param base - the directory a relative value resolves against.
+* @returns the call's output directory, or an empty string for the source's own.
+*/
+function requestedOutputDir(args, config, base) {
+	const requested = resolveDirectory(args.outputDir ?? "", base);
+	return requested !== "" ? requested : resolveDirectory(config.outputDir, base);
+}
+/**
+* Build the worker spec and the failures that never reach the worker.
+* @param paths - the absolute paths one call named.
+* @param args - the model-supplied call arguments.
+* @param config - the deployment's values.
+* @param base - the directory a relative output directory resolves against.
+* @returns the jobs to run and the paths rejected before running.
+*/
+function planJobs(paths, args, config, base) {
+	const outputDir = requestedOutputDir(args, config, base);
+	const jobs = [];
+	const failures = [];
+	for (const input of paths) {
+		const rejection = rejectPath(input);
+		if (rejection !== void 0) {
+			failures.push({
+				input,
+				error: rejection
+			});
+			continue;
+		}
+		jobs.push({
+			input,
+			base: artifactBase(input, outputDir),
+			job: {
+				mode: "recognize",
+				id: String(jobs.length + 1),
+				input,
+				pages: args.pages ?? null,
+				dpi: config.dpi,
+				maxPixels: config.maxPixels,
+				textScore: config.textScore,
+				detectColumns: config.detectColumns,
+				maxPages: config.maxPages,
+				merge: mergeOptions(config)
+			}
+		});
+	}
+	return {
+		jobs,
+		failures
+	};
+}
+/**
+* Read the metadata the digest covers for one source file.
+* @param fs - the mounted filesystem capability.
+* @param target - the resolved source target.
+* @param signal - caller cancellation.
+* @returns the size and modification time the filesystem reported, or the
+*   documented fallbacks when it reported none or refused the read.
+*/
+async function sourceStamp(fs, target, signal) {
+	try {
+		const info = await fs.stat(target, signal);
+		if (info === void 0) return {
+			size: "",
+			mtimeMs: 0,
+			unavailable: true
+		};
+		const reported = info;
+		return {
+			size: typeof reported.size === "number" ? reported.size : "",
+			mtimeMs: typeof reported.mtimeMs === "number" ? reported.mtimeMs : 0,
+			unavailable: false
+		};
+	} catch {
+		return {
+			size: "",
+			mtimeMs: 0,
+			unavailable: true
+		};
+	}
+}
+/**
+* Resolve the digest and the artifact paths of one planned job.
+* @param fs - the mounted filesystem capability.
+* @param planned - the job {@link planJobs} produced.
+* @param pageDirName - the page directory's name under the base directory.
+* @param signal - caller cancellation.
+* @returns the job with its artifact paths and source metadata.
+*/
+async function prepareJob(fs, planned, pageDirName, signal) {
+	const target = await fs.resolve(planned.input);
+	const stamp = await sourceStamp(fs, target, signal);
+	planned.job.input = fs.processPath(target);
+	return {
+		...planned,
+		root: artifactRoot(planned.input, planned.base, pageDirName),
+		stamp
+	};
+}
+//#endregion
+//#region lib/worker.js
+/**
+* Transport to the OCR worker process. The worker speaks newline-delimited
+* JSON: one event per line on stdout, diagnostics on stderr. This module owns
+* the process lifetime, the spec handoff, the timeout, and the cancellation, so
+* the tool's entry module only has to interpret events.
+* @module @deepseek-ai/dsh-ab-ocr/worker
+*/
+/**
+* Split a run of text into whole lines, returning what is left of a partial one.
+* @param buffered - text received so far, including any partial final line.
+* @param chunk - newly received text.
+* @returns the complete lines and the remaining partial line.
+*/
+function splitLines(buffered, chunk) {
+	const parts = (buffered + chunk).split("\n");
+	return {
+		lines: parts,
+		rest: parts.pop() ?? ""
+	};
+}
+/**
+* Parse one event line, ignoring a line that is not a JSON object.
+* @param line - one complete stdout line.
+* @returns the parsed event, or undefined for a line that is not one.
+*/
+function parseEvent(line) {
+	const trimmed = line.trim();
+	if (trimmed === "") return void 0;
+	try {
+		const value = JSON.parse(trimmed);
+		if (typeof value !== "object" || value === null || typeof value.event !== "string") return;
+		return value;
+	} catch {
+		return;
+	}
+}
+/**
+* Run the worker once, feeding it a spec and reporting its events.
+* @param invocation - executable, script, and time ceiling.
+* @param args - extra command-line arguments.
+* @param input - text written to the worker's stdin, or an empty string to close it immediately.
+* @param onEvent - called with each parsed event as it arrives; never awaited, so a
+*   slow consumer cannot stall the read.
+* @param signal - caller cancellation.
+* @returns the events, diagnostics, and exit state.
+*/
+function spawnWorker(invocation, args, input, onEvent, signal) {
+	return new Promise((resolve) => {
+		const child = spawn(invocation.python, [invocation.script, ...args], {
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			windowsHide: true
+		});
+		const events = [];
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		let aborted = signal?.aborted === true;
+		let settled = false;
+		const timer = invocation.timeoutMs > 0 ? setTimeout(() => {
+			timedOut = true;
+			child.kill();
+		}, invocation.timeoutMs) : void 0;
+		const onAbort = () => {
+			aborted = true;
+			child.kill();
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		const accept = (line) => {
+			const event = parseEvent(line);
+			if (event === void 0) return;
+			events.push(event);
+			onEvent(event);
+		};
+		const settle = (exitCode) => {
+			if (settled) return;
+			settled = true;
+			if (timer !== void 0) clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			const tail = splitLines(stdout, "");
+			for (const line of [...tail.lines, tail.rest]) accept(line);
+			resolve({
+				events,
+				stderr,
+				exitCode,
+				timedOut,
+				aborted
+			});
+		};
+		child.stdout.setEncoding("utf8");
+		child.stdout.on("data", (chunk) => {
+			const split = splitLines(stdout, chunk);
+			stdout = split.rest;
+			for (const line of split.lines) accept(line);
+		});
+		child.stderr.setEncoding("utf8");
+		child.stderr.on("data", (chunk) => {
+			stderr = (stderr + chunk).slice(-4e3);
+		});
+		child.on("error", (error) => {
+			stderr = (stderr + error.message).slice(-4e3);
+			settle(null);
+		});
+		child.on("close", (code) => settle(code));
+		child.stdin.on("error", () => {});
+		child.stdin.end(input);
+	});
+}
+/**
+* Ask the worker to report its environment.
+* @param invocation - executable, script, and the ceiling this check may take.
+* @param signal - caller cancellation.
+* @returns the report and the diagnostics, whether or not the worker started.
+*/
+async function runSelfTest(invocation, signal) {
+	const run = await spawnWorker(invocation, ["--self-test"], "", () => {}, signal);
+	return {
+		report: run.events.find((event) => event.event === "ready"),
+		stderr: run.stderr,
+		exitCode: run.exitCode
+	};
+}
+/**
+* Run one batch of documents through the worker.
+*
+* The event callback sees each event as it is parsed, which is what lets the
+* caller persist a finished page before the next one is recognized instead of
+* holding the whole document until the process exits.
+* @param invocation - executable, script, and time ceiling.
+* @param spec - the documents and options to process.
+* @param onEvent - called with each parsed event as it arrives.
+* @param signal - caller cancellation.
+* @returns the events, diagnostics, and exit state.
+*/
+function runSpec(invocation, spec, onEvent, signal) {
+	return spawnWorker(invocation, [], JSON.stringify(spec), onEvent, signal);
+}
+//#endregion
+//#region lib/recognize.js
+/**
+* One `ocr` call: refuse an installation that cannot run, drive the worker
+* through the plan, write each page as it finishes, and merge the document only
+* after the last page.
+*
+* A later call carrying `levels` does not recognize anything: it reads the
+* record the recognition left behind and sends its stored geometry to the worker
+* with the caller's heading-level corrections, which rewrites the document at
+* the path the record named.
+*
+* The worker runs in its own execution world and writes only to stdout, so every
+* value this module persists travels back as an event and is written through the
+* mounted filesystem capability rather than by the worker.
+* @module @deepseek-ai/dsh-ab-ocr/recognize
+*/
+/** Package root, from which the worker script and its environment are resolved. */
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+/** The tail of a worker's diagnostics, for an error a caller can act on. */
+function diagnostics(stderr) {
+	const trimmed = stderr.trim().slice(-1200);
+	return trimmed === "" ? "" : " Worker diagnostics: " + trimmed;
+}
+/**
+* Resolve the worker and refuse an installation that cannot run.
+*
+* The startup check is a separate process from the batch, so it carries its own
+* ceiling: an environment whose engine never loads has to be refused in the
+* deployment's startup window rather than held for the whole recognition
+* ceiling.
+* @param config - the deployment's values.
+* @param signal - caller cancellation.
+* @returns the invocation every call spawns.
+* @throws Error when the worker program is missing from the installation, or
+*   when it starts without the OCR engine it needs.
+*/
+async function readyInvocation(config, signal) {
+	const invocation = {
+		python: resolvePython(config.pythonPath, PACKAGE_ROOT, process.platform),
+		script: resolveWorkerScript(config.workerScript, PACKAGE_ROOT),
+		timeoutMs: config.timeoutMs
+	};
+	if (!existsSync(invocation.script)) throw new Error("ocr cannot run: the OCR engine is not installed on this machine, because the worker program is missing from the plugin. The plugin's setup script installs it.");
+	const selfTest = await runSelfTest({
+		...invocation,
+		timeoutMs: config.startupTimeoutMs
+	}, signal);
+	if (selfTest.report?.ready !== true) {
+		const detail = selfTest.report === void 0 ? "its worker did not start" : "its worker started without the engine";
+		throw new Error("ocr cannot run: the OCR engine is not installed on this machine, because " + detail + ". The plugin's setup script installs it." + diagnostics(selfTest.stderr));
+	}
+	return invocation;
+}
+/**
+* Run one batch through the worker and report what it produced.
+* @param invocation - the worker to run.
+* @param config - the deployment's engine lifetime and time ceiling.
+* @param jobs - the jobs to run, in order.
+* @param call - the documents and failures the call collects.
+* @param apply - called with each parsed event as it arrives.
+* @param signal - caller cancellation.
+* @returns the canonical value the call records.
+* @throws Error when the batch was cancelled, stopped early, lost a document, or
+*   could not save one.
+*/
+async function runCall(invocation, config, jobs, call, apply, signal) {
+	const forward = () => call.controller.abort();
+	signal?.addEventListener("abort", forward, { once: true });
+	const spec = {
+		engineLifetime: config.engineLifetime,
+		jobs
+	};
+	let run;
+	try {
+		run = await runSpec(invocation, spec, apply, call.controller.signal);
+	} finally {
+		signal?.removeEventListener("abort", forward);
+	}
+	const writeError = await call.queue.settle();
+	if (call.problem !== void 0) throw call.problem;
+	if (writeError !== void 0) throw new Error("ocr could not save its output: " + writeError.message);
+	const end = run.events.find((event) => event.event === "end");
+	if (end === void 0) {
+		const fatal = run.events.find((event) => event.event === "fatal");
+		if (fatal !== void 0) throw new Error("ocr did not start: " + String(fatal.error ?? "no reason was reported"));
+		if (run.aborted) throw new Error("ocr was cancelled");
+		if (run.timedOut) throw new Error("ocr timed out after " + config.timeoutMs + " ms; recognize fewer pages in one call" + diagnostics(run.stderr));
+		throw new Error("ocr did not finish: the recognition stopped without a result" + diagnostics(run.stderr));
+	}
+	if (Number(end.documents) !== call.finished) throw new Error("ocr lost a document: the worker finished " + call.finished + " of the " + String(end.documents) + " it reported");
+	for (const failure of readFailures(end.failures)) reportFailure(call, failure);
+	return {
+		documents: call.documents,
+		failures: call.failures
+	};
+}
+/**
+* Re-merge a stored recognition with heading-level corrections, recognizing nothing.
+* @param config - the deployment's worker values.
+* @param input - the source path the worker names in its events.
+* @param geometry - the stored page geometry to merge.
+* @param merge - the merge options, carrying the corrections to apply.
+* @param signal - caller cancellation.
+* @returns the merged document, or undefined when the worker reported a failure.
+*/
+async function assembleStored(config, input, geometry, merge, signal) {
+	const job = {
+		mode: "assemble",
+		id: "1",
+		input,
+		record: geometry,
+		merge
+	};
+	const controller = new AbortController();
+	const call = {
+		documents: [],
+		failures: [],
+		reported: /* @__PURE__ */ new Set(),
+		controller,
+		queue: writeQueue(controller),
+		finished: 0
+	};
+	const captured = {};
+	const collect = (event) => {
+		const done = readDoneEvent(event);
+		if (done === void 0) return;
+		call.finished += 1;
+		captured.merged = {
+			markdown: done.markdown,
+			outline: readOutline(event.outline),
+			rawOutline: event.outline,
+			truncated: event.outlineTruncated === true,
+			done
+		};
+	};
+	let assembled;
+	try {
+		assembled = await runCall(await readyInvocation(config, signal), config, [job], call, collect, signal);
+	} catch {
+		return;
+	}
+	if (assembled.failures.length > 0) return void 0;
+	return captured.merged;
+}
+/**
+* Rewrite one recognized document with the heading levels the caller decided.
+*
+* No page is recognized again: the call reads the record the recognition left
+* behind and sends its stored geometry to the worker with the caller's level
+* corrections, then writes the assembled Markdown over the file the record
+* named. The digest is the recognition's, so this call finds the same record
+* without scanning.
+* @param fs - the mounted filesystem capability, or undefined when the
+*   composition mounts none.
+* @param args - the model-supplied call arguments, carrying `levels`.
+* @param config - the deployment's worker, render, and merge values.
+* @param base - the directory a relative path resolves against.
+* @param signal - caller cancellation.
+* @param fence - the per-call fence a confining backend judges the rewritten document and its records by; absent on a bare backend.
+* @returns the canonical value the call records.
+* @throws Error when the request is malformed, no filesystem is mounted, the
+*   environment is unusable, or the stored record is missing.
+*/
+async function refine(fs, args, config, base, signal, fence) {
+	const overrides = parseLevels(args.levels ?? "");
+	const paths = requestPaths(args, base, config.maxDocuments);
+	const input = paths.length === 1 ? paths[0] : void 0;
+	if (input === void 0) throw new Error("invalid ocr: levels corrects one document, so name exactly one path");
+	if (fs === void 0) throw new Error("ocr cannot save its result: no filesystem is available to write to");
+	const baseDir = artifactBase(input, requestedOutputDir(args, config, base));
+	const latest = await readLatest(fs, artifactRoot(input, baseDir, config.pageDirName).latest, signal);
+	const artifacts = artifactPaths(input, baseDir, config.pageDirName, latest.digest);
+	const record = await readRecord(fs, artifacts.record, signal);
+	const invocation = await readyInvocation(config, signal);
+	const job = {
+		mode: "assemble",
+		id: "1",
+		input: fs.processPath(await fs.resolve(input)),
+		record: record.geometry,
+		merge: {
+			...record.merge,
+			levelOverrides: overrides
+		}
+	};
+	const controller = new AbortController();
+	const call = {
+		documents: [],
+		failures: [],
+		reported: /* @__PURE__ */ new Set(),
+		controller,
+		queue: writeQueue(controller),
+		finished: 0
+	};
+	const corrections = Object.keys(overrides).length;
+	const apply = (event) => {
+		if (event.event === "error") {
+			reportFailure(call, {
+				id: String(event.id ?? ""),
+				input,
+				error: String(event.message ?? "")
+			});
+			return;
+		}
+		const done = readDoneEvent(event);
+		if (done === void 0) return;
+		call.finished += 1;
+		const truncated = event.outlineTruncated === true;
+		call.queue.enqueue(async () => {
+			await saveText(fs, await fs.resolve(latest.output), done.markdown, fence, signal);
+			await writeJson(fs, artifacts.record, {
+				...record,
+				merge: {
+					...record.merge,
+					levelOverrides: overrides
+				}
+			}, signal, fence);
+			if (Array.isArray(event.outline)) await writeJson(fs, artifacts.outline, appliedOutline(readOutline(event.outline), overrides), signal, fence);
+			call.documents.push({
+				input,
+				output: latest.output,
+				pages: latest.pages.length > 0 ? latest.pages.length : done.pages,
+				totalPages: done.totalPages > 0 ? done.totalPages : latest.totalPages,
+				lines: done.lines,
+				headings: done.headings,
+				chars: done.chars,
+				droppedPageNumbers: done.droppedPageNumbers,
+				droppedRunningHeads: done.droppedRunningHeads,
+				joinedAcrossPages: done.joinedAcrossPages,
+				pageDir: "",
+				seconds: done.seconds,
+				digest: latest.digest,
+				selection: [...latest.pages],
+				outlinePath: artifacts.outline,
+				outlineTruncated: truncated,
+				corrections
+			});
+		});
+	};
+	return runCall(invocation, config, [job], call, apply, signal);
+}
+/**
+* Read the documents one call asked for, writing every artifact through the
+* filesystem capability the composition mounted.
+* @param fs - the mounted filesystem capability every write goes through, or
+*   undefined when the composition mounts none.
+* @param args - the model-supplied call arguments.
+* @param config - the deployment's values.
+* @param base - the directory a relative path resolves against.
+* @param signal - caller cancellation.
+* @param fence - the fence every write is stamped with; absent on a bare backend.
+* @returns the canonical value the call records.
+* @throws Error when the request is malformed, no filesystem is mounted, the
+*   environment is unusable, the deployment denies a write, the worker reports
+*   pages out of order, or the worker fails.
+*/
+async function recognize(fs, args, config, base, signal, fence) {
+	if (args.levels !== void 0) return refine(fs, args, config, base, signal, fence);
+	const planned = planJobs(requestPaths(args, base, config.maxDocuments), args, config, base);
+	if (planned.jobs.length === 0) return {
+		documents: [],
+		failures: planned.failures
+	};
+	if (fs === void 0) throw new Error("ocr cannot save its result: no filesystem is available to write to");
+	const invocation = await readyInvocation(config, signal);
+	const states = /* @__PURE__ */ new Map();
+	for (const job of planned.jobs) {
+		const prepared = await prepareJob(fs, job, config.pageDirName, signal);
+		states.set(String(prepared.job.id), documentState(prepared));
+	}
+	const controller = new AbortController();
+	const call = {
+		documents: [],
+		failures: [...planned.failures],
+		reported: /* @__PURE__ */ new Set(),
+		controller,
+		queue: writeQueue(controller),
+		finished: 0
+	};
+	/** Report one protocol violation, which aborts the rest of the batch. */
+	const violate = (problem) => {
+		if (call.problem === void 0) call.problem = /* @__PURE__ */ new Error("ocr failed: " + problem);
+		controller.abort();
+	};
+	const apply = (event) => {
+		const state = states.get(String(event.id));
+		if (state === void 0) return;
+		if (event.event === "start") {
+			state.selection = wholeNumbers(event.pages);
+			state.totalPages = wholeNumber(event.totalPages) ?? 0;
+			state.artifacts = artifactPaths(state.job.input, state.job.base, config.pageDirName, digest12(state.job.input, state.job.stamp, String(event.sourceDigest ?? ""), state.job.job.pages ?? null, state.job.job.merge));
+			return;
+		}
+		if (event.event === "page") {
+			const page = wholeNumber(event.page);
+			if (page === void 0) {
+				violate("page " + JSON.stringify(event.page ?? null) + " is not a page number");
+				return;
+			}
+			const problem = pageProblem(page, state);
+			if (problem !== void 0) {
+				violate(problem);
+				return;
+			}
+			const geometry = readGeometry(event.geometry);
+			if (geometry === void 0) {
+				violate("page " + page + " arrived without the geometry its record needs");
+				return;
+			}
+			const artifacts = state.artifacts;
+			if (artifacts === void 0) {
+				violate("page " + page + " arrived before the document named its source");
+				return;
+			}
+			state.lastPage = page;
+			state.geometry.push(geometry);
+			if (!config.writePageFiles) return;
+			const name = pageFileName(page);
+			const text = String(event.text ?? "");
+			call.queue.enqueue(async () => {
+				await saveText(fs, await fs.resolve(join(artifacts.recordDir, name)), text === "" ? "\n" : text + "\n", fence, signal);
+			});
+			return;
+		}
+		if (event.event === "error") {
+			reportFailure(call, {
+				id: String(event.id ?? ""),
+				input: state.job.input,
+				error: String(event.message ?? "")
+			});
+			return;
+		}
+		const done = readDoneEvent(event);
+		if (done === void 0) return;
+		call.finished += 1;
+		const artifacts = state.artifacts;
+		if (artifacts === void 0) {
+			violate("document " + state.job.input + " finished without naming its source");
+			return;
+		}
+		const truncated = event.outlineTruncated === true;
+		call.queue.enqueue(async () => {
+			const carried = await carriedLevels(fs, artifacts.record, signal);
+			const merged = carried === void 0 ? void 0 : await assembleStored(config, state.job.job.input, { pages: state.geometry }, {
+				...state.job.job.merge,
+				levelOverrides: carried
+			}, signal);
+			const output = await writeDocument(fs, artifacts, state, merged?.markdown ?? done.markdown, merged?.outline ?? readOutline(event.outline), merged?.rawOutline ?? event.outline, carried, signal, fence);
+			call.documents.push(recognizedDocument(state, artifacts, merged?.done ?? done, output, config.writePageFiles ? artifacts.recordDir : "", merged?.truncated ?? truncated, carried === void 0 ? 0 : Object.keys(carried).length));
+		});
+	};
+	return runCall(invocation, config, [...states.values()].map((state) => state.job.job), call, apply, signal);
+}
+//#endregion
+//#region lib/config.js
+/**
+* Deployment configuration of the ocr tool.
+*
+* The fields fall into two groups. The first is a bound or a cost policy the
+* deployment owns: the render resolution, the per-page pixel ceiling, the page,
+* file, call, and startup ceilings, the outline candidate ceiling, the engine
+* lifetime, and whether per-page text is kept at all. None of them carries a
+* default, because a hidden one would state an agreement the deployment never
+* made; a row that omits one fails to load and names the field.
+*
+* The second group is a resolution rule or a recognition heuristic — where the
+* interpreter, the worker, and the artifacts are found, and how a page is read
+* and merged. Their defaults are what a document reader wants, they are stated
+* here rather than computed anywhere, and a deployment overrides the ones its
+* documents disagree with.
+* @module @deepseek-ai/dsh-ab-ocr/config
+*/
+/**
+* Schemastery configuration for the tool. A bound or a cost policy the
+* deployment owns is `.required()`, so the row states what this deployment is
+* willing to carry; a resolution rule or a recognition heuristic keeps its
+* documented default.
+*/
+const Config = z.object({
+	pythonPath: z.string().default(""),
+	workerScript: z.string().default(""),
+	outputDir: z.string().default(""),
+	pageDirName: z.string().default(".ocr-pages"),
+	writePageFiles: z.boolean().required(),
+	dpi: z.number().step(1).min(72).max(600).required(),
+	maxPixels: z.number().step(1).min(0).required(),
+	textScore: z.number().min(0).max(1).default(.5),
+	detectHeadings: z.boolean().default(true),
+	headingMinRatio: z.number().min(1).max(4).default(1.18),
+	indentRatio: z.number().min(0).max(4).default(1),
+	paragraphGapRatio: z.number().min(0).max(4).default(.85),
+	outlineCandidateRatio: z.number().min(1).max(4).default(1.05),
+	maxOutlineCandidates: z.number().step(1).min(1).max(1e4).required(),
+	detectColumns: z.boolean().default(true),
+	removePageNumbers: z.boolean().default(true),
+	removeRunningHeads: z.boolean().default(true),
+	runningHeadRatio: z.number().min(0).max(1).default(.6),
+	runningHeadMinPages: z.number().step(1).min(2).default(3),
+	engineLifetime: z.union(["perDocument", "shared"]).required(),
+	timeoutMs: z.number().step(1).min(1e3).required(),
+	startupTimeoutMs: z.number().step(1).min(1e3).required(),
+	maxPages: z.number().step(1).min(0).required(),
+	maxDocuments: z.number().step(1).min(1).max(200).required()
+});
+//#endregion
+//#region lib/index.js
+/**
+* Model-facing `ocr` tool. One call recognizes a PDF or an image and saves the
+* text as a Markdown file named after the source with its spaces removed.
+*
+* The document is processed one page at a time: the worker recognizes a page,
+* reports its text and its geometry, and releases its pixels before rendering
+* the next. The page's text is written to its own file as each page arrives, so
+* an interrupted run keeps every page it finished. Only after the last page does
+* the worker merge its records —dropping the folios and running heads,
+* rebuilding the outline from the recognized glyph sizes and numbering, and
+* stitching the paragraphs a page break cut in half —and reports the one
+* Markdown document, which is written last, beside the record an assembly pass
+* reads back. A later call carrying `levels` sends that stored geometry to the
+* worker again with the caller's heading-level corrections and rewrites the
+* document without recognizing it a second time.
+*
+* This module owns the plugin's identity, its deployment configuration, its
+* routing section, and its tool registration. The work behind them lives in
+* [`plan.ts`](./plan.ts) (what one call asks for), [`recognize.ts`](./recognize.ts)
+* (driving the worker and writing the artifacts), [`documents.ts`](./documents.ts)
+* (the artifact files of one recognition), and [`events.ts`](./events.ts) (the
+* worker's event stream), with the pure leaf modules beside them.
+*
+* Every file is written through the filesystem capability rather than the host
+* filesystem, so a deployment's file policy sees the write and its own backend
+* decides how the bytes are published. That capability is read with `ctx.get`
+* when a call runs — and so is the sandbox-policy service, whose resolved
+* per-call policy is the only thing naming the workspace the calling session
+* runs in. Both are looked up rather than declared in `inject`, for the same
+* reason: a declared injection waits for the service, which would make mounting
+* this row require providers of its own. The policy is resolved once per call
+* and stamped onto every write, and a composition that cannot resolve one is
+* refused at the call rather than writing under the deployment's fallback root.
+*
+* The tool reads no session state beyond the working directory it resolves
+* relative paths against and returns the canonical value alone, so model-facing
+* text and any replay read the same recorded call.
+* @module @deepseek-ai/dsh-ab-ocr
+*/
+const name = "ocr";
+const inject = ["tools", "systemPrompt"];
+/** Wire name this plugin registers. */
+const TOOL_NAME = "ocr";
+/**
+* Name and order of the routing section this plugin contributes. Repository-owned
+* tool sections allocate their order centrally; an external contribution states
+* its own finite order and sits after the built-in tool band (TOOL_REPORT, 2900).
+*/
+const SECTION_NAME = "tool:ocr";
+/** Order of {@link SECTION_NAME}, after the built-in tool sections. */
+const SECTION_ORDER = 2975;
+const DESCRIPTION = [
+	"Recognize the text of a scanned PDF or an image into one Markdown document.",
+	"Name the file with `path` or `paths`, optionally restrict `pages` and choose `outputDir`.",
+	"The call saves the document and an outline file, and reports both paths and the page, line, and heading counts."
+].join(" ");
+/** Model-facing routing rule: when to make a call, which a schema cannot carry. */
+const SECTION_TEXT = [
+	"When the reader needs the text of a scanned PDF or an image, answer with `ocr`: it recognizes every page and saves a Markdown document plus an outline file, reporting both paths.",
+	"When the heading levels matter, read the outline file and call `ocr` again with the same `path` and a `levels` value such as \"h12=2,h15=0\"; that rewrites the document without recognizing it again.",
+	"Pass the document to `present` when the reader should keep it."
+].join(" ");
+/**
+* The pending-call presentation of one ocr call: a titled row carrying the
+* source path. Exported so the test drives it without a registry.
+* @param args - the model-supplied call arguments.
+* @returns the pending generic card for this call.
+*/
+function presentCall(args) {
+	return {
+		card: "generic",
+		title: "Recognize document text",
+		kind: "read",
+		rawInput: args.path ?? (args.paths ?? []).join(", ")
+	};
+}
+/**
+* Contribute the routing section and register the ocr tool. The section is
+* empty wherever the tool is not visible in that scope, so a restricted
+* composition is not told to call a hidden tool.
+* @param ctx - registrant context carrying the tool, system-prompt, and filesystem registries.
+* @param config - the deployment's worker, render, and merge values.
+*/
+function apply(ctx, config) {
+	ctx.systemPrompt.section({
+		name: SECTION_NAME,
+		order: SECTION_ORDER,
+		text: ({ scope }) => ctx.tools.get("ocr", scope) === void 0 ? "" : SECTION_TEXT
+	});
+	ctx.tools.register(defineTool({
+		name: "ocr",
+		description: DESCRIPTION,
+		parameters: {
+			path: {
+				type: "string",
+				description: "One file to recognize: a PDF, or an image such as PNG, JPEG, BMP, TIFF, or WebP."
+			},
+			paths: {
+				type: "array",
+				items: { type: "string" },
+				description: "Several files to recognize in one call."
+			},
+			pages: {
+				type: "string",
+				description: "Pages to recognize, counted from one, as single pages and inclusive ranges, for example \"1-5,8\". Omit for every page."
+			},
+			outputDir: {
+				type: "string",
+				description: "Directory for the Markdown files, relative to the working directory. Omit to write beside each source file."
+			},
+			levels: {
+				type: "string",
+				description: "Heading levels to correct in a document an earlier call recognized: \"h<id>=<level>\" pairs from its outline file, such as \"h12=2,h15=0\". A level of 1 to 6 makes that line a heading at that depth; 0 leaves it as body text, which demotes a line the recognition promoted. The call rewrites the saved Markdown and recognizes nothing."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					documents: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								input: {
+									type: "string",
+									required: true
+								},
+								output: {
+									type: "string",
+									required: true
+								},
+								pages: {
+									type: "number",
+									required: true
+								},
+								totalPages: {
+									type: "number",
+									required: true
+								},
+								lines: {
+									type: "number",
+									required: true
+								},
+								headings: {
+									type: "number",
+									required: true
+								},
+								chars: {
+									type: "number",
+									required: true
+								},
+								droppedPageNumbers: {
+									type: "number",
+									required: true
+								},
+								droppedRunningHeads: {
+									type: "number",
+									required: true
+								},
+								joinedAcrossPages: {
+									type: "number",
+									required: true
+								},
+								pageDir: {
+									type: "string",
+									required: true
+								},
+								seconds: {
+									type: "number",
+									required: true
+								},
+								digest: {
+									type: "string",
+									required: true
+								},
+								selection: {
+									type: "array",
+									required: true,
+									items: { type: "number" }
+								},
+								outlinePath: {
+									type: "string",
+									required: true
+								},
+								outlineTruncated: {
+									type: "boolean",
+									required: true
+								},
+								corrections: {
+									type: "number",
+									required: true
+								}
+							}
+						}
+					},
+					failures: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								input: {
+									type: "string",
+									required: true
+								},
+								error: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderOcr(value)
+			}],
+			presentationMeta: (_args, value) => ({ documents: value.documents.map((document) => ({
+				output: document.output,
+				pages: document.pages,
+				totalPages: document.totalPages,
+				chars: document.chars,
+				headings: document.headings,
+				digest: document.digest
+			})) })
+		},
+		execute(args, exec) {
+			const fence = callFence(ctx, exec.agent === void 0 ? void 0 : { session: exec.agent.session });
+			return recognize(ctx.get("fs"), args, config, fence?.workspaceRoot ?? exec.agent?.session?.header?.cwd ?? process.cwd(), exec.signal, fence);
+		},
+		presentCall
+	}));
+}
+//#endregion
+export { Config, SECTION_NAME, SECTION_ORDER, SECTION_TEXT, SUPPORTED_EXTENSIONS, TOOL_NAME, appliedOutline, apply, artifactPaths, callFence, digest12, inject, markdownDigestFileName, markdownFileName, markdownPath, markdownStem, name, pageFileName, parseEvent, parseLevels, planJobs, presentCall, readDoneEvent, recognize, rejectPath, renderDocument, renderOcr, requestPaths, resolveDirectory, resolvePython, resolveWorkerScript, saveText, splitLines, writeDocument };