@youweichen/pi-harness 1.1.0 → 1.2.0

package/dist/server/document-conversion/runtime.js

@@ -0,0 +1,321 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, access, writeFile, stat, readdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import lockfile from "proper-lockfile";
+import { killPidTree } from "../process-utils.js";
+import { documentDataDir, getDocumentSettings } from "./settings.js";
+export const DOCLING_VERSION = "2.136.0";
+export const CONVERSION_PROFILE = "docling-cpu-zh-v1";
+const ownedChildren = new Set();
+let shuttingDown = false;
+function trackChild(child) { ownedChildren.add(child); child.once("close", () => ownedChildren.delete(child)); }
+export async function shutdownDocumentRuntime() {
+    shuttingDown = true;
+    if (worker)
+        closeWorker(worker);
+    await Promise.all([...ownedChildren].map(child => new Promise(resolve => {
+        const done = () => { clearTimeout(timer); resolve(); };
+        const timer = setTimeout(done, 5000);
+        child.once("close", done);
+        if (child.pid)
+            killPidTree(child.pid);
+        else
+            done();
+    })));
+}
+export async function waitDocumentQueue(previous, signal) {
+    signal?.throwIfAborted();
+    if (!signal)
+        return previous;
+    await new Promise((resolve, reject) => {
+        const abort = () => reject(new DOMException("Document operation canceled", "AbortError"));
+        signal.addEventListener("abort", abort, { once: true });
+        previous.then(() => { signal.removeEventListener("abort", abort); resolve(); }, error => { signal.removeEventListener("abort", abort); reject(error); });
+    });
+}
+export function runtimeDirectory() {
+    return getDocumentSettings().runtimePath ?? join(documentDataDir(), "runtimes", CONVERSION_PROFILE);
+}
+export function runtimePython() {
+    return join(runtimeDirectory(), "venv", process.platform === "win32" ? "Scripts/python.exe" : "bin/python");
+}
+export function bridgePath() { return fileURLToPath(new URL("./python/bridge.py", import.meta.url)); }
+/** A separate process group lets cancellation remove only this conversion's children. */
+export async function runDocumentProcess(command, args, options = {}) {
+    if (shuttingDown)
+        throw new Error("Document runtime is shutting down");
+    options.signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32", windowsHide: true,
+            env: { ...process.env, PYTHONUNBUFFERED: "1", PYTHONUTF8: "1", ...(options.offline ? { HF_HUB_OFFLINE: "1", TRANSFORMERS_OFFLINE: "1", HF_DATASETS_OFFLINE: "1", HF_HUB_DISABLE_TELEMETRY: "1" } : {}) },
+        });
+        trackChild(child);
+        let stdout = "", stderr = "", pending = "", failure, lastProgress = 0;
+        const stop = (error) => { failure = error; if (child.pid)
+            killPidTree(child.pid); };
+        const abort = () => stop(new DOMException("Document operation canceled", "AbortError"));
+        const timer = setTimeout(() => stop(new Error("Document operation timed out")), options.timeout ?? 30 * 60_000);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+            if (stdout.length > 4 * 1024 * 1024)
+                stop(new Error("Parser response exceeds 4 MiB"));
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = chunk.toString("utf8");
+            stderr = (stderr + text).slice(-32_768);
+            pending += text;
+            const lines = pending.split(/\r\n|\r|\n/);
+            pending = lines.pop() ?? "";
+            const latest = lines.map(line => line.replace(/\x1b\[[0-9;]*[A-Za-z]/g, "").trim()).filter(Boolean).at(-1);
+            if (latest && Date.now() - lastProgress >= 400) {
+                options.onProgress?.(latest.slice(0, 1000));
+                lastProgress = Date.now();
+            }
+            if (pending.length > 2000)
+                pending = pending.slice(-2000);
+        });
+        child.on("error", error => { failure = error; });
+        child.on("close", code => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+            if (failure)
+                reject(failure);
+            else if (code !== 0)
+                reject(new Error(`Document process failed (${code}): ${stderr.trim().slice(-6000)}`));
+            else
+                resolve(stdout.trim());
+        });
+        child.stdin.on("error", () => { });
+        child.stdin.end(options.input === undefined ? undefined : JSON.stringify(options.input));
+        if (options.signal?.aborted)
+            abort();
+    });
+}
+export async function doctorRuntime(options = {}) {
+    const pythonPath = runtimePython();
+    try {
+        await access(pythonPath);
+        const result = JSON.parse(await runDocumentProcess(pythonPath, [bridgePath(), "doctor", runtimeDirectory()], { ...options, timeout: 60_000, offline: true }));
+        return { ...result, pythonPath };
+    }
+    catch (error) {
+        options.signal?.throwIfAborted();
+        return { ready: false, pythonPath, missing: [error instanceof Error ? error.message : String(error)], warnings: [] };
+    }
+}
+let qualification;
+async function qualificationSignature(root) {
+    const receipt = await readFile(join(root, "ready.json"), "utf8");
+    const parsed = JSON.parse(receipt);
+    const assets = (await readdir(dirname(bridgePath()))).filter(name => name.endsWith(".py")).sort().map(name => join(dirname(bridgePath()), name));
+    const paths = [join(root, "ready.json"), join(root, "requirements.lock"), runtimePython(), ...assets, ...Object.keys(parsed.models ?? {}).sort().map(path => join(root, "models", path))];
+    const identities = await Promise.all(paths.map(async (path) => { const value = await stat(path); return [path, value.dev, value.ino, value.size, value.mtimeMs, value.ctimeMs]; }));
+    return JSON.stringify([receipt, identities]);
+}
+/** Explicit doctor always hashes models; conversions reuse a successful check
+ * until the receipt, dependency lock, Python executable or model files change. */
+export async function ensureRuntimeReady(options = {}) {
+    options.signal?.throwIfAborted();
+    const root = runtimeDirectory();
+    let signature;
+    try {
+        signature = await qualificationSignature(root);
+    }
+    catch { /* Doctor gives actionable missing-runtime details. */ }
+    if (signature !== undefined && qualification?.root === root && qualification.signature === signature)
+        return qualification.result;
+    const result = await doctorRuntime(options);
+    if (result.ready && signature !== undefined)
+        qualification = { root, signature, result };
+    else
+        qualification = undefined;
+    return result;
+}
+let setupPromise;
+export async function setupRuntime(options = {}) {
+    if (setupPromise)
+        throw new Error("Document runtime setup is already running");
+    setupPromise = performSetup(options);
+    try {
+        return await setupPromise;
+    }
+    finally {
+        setupPromise = undefined;
+    }
+}
+async function performSetup(options) {
+    if (process.platform === "darwin" && process.arch === "x64")
+        throw new Error("The current local Docling profile has not been qualified on Intel macOS. A separately tested runtime is required.");
+    const root = runtimeDirectory(), pythonPath = runtimePython();
+    await mkdir(root, { recursive: true });
+    const release = await lockfile.lock(root, { realpath: false, stale: 120_000, retries: 0 });
+    try {
+        const existing = await doctorRuntime(options);
+        if (existing.ready) {
+            options.onProgress?.("The isolated document runtime is already qualified");
+            return existing;
+        }
+        if (worker?.root === root)
+            closeWorker(worker);
+        try {
+            await access(pythonPath);
+        }
+        catch {
+            const configured = getDocumentSettings().pythonPath;
+            if (configured) {
+                const version = await runDocumentProcess(configured, ["-c", "import sys; print('.'.join(map(str,sys.version_info[:2])))"], options);
+                if (version !== "3.12")
+                    throw new Error(`Python 3.12 is required for this profile; found ${version}`);
+                await runDocumentProcess(configured, ["-m", "venv", join(root, "venv")], options);
+            }
+            else {
+                options.onProgress?.("Creating the isolated Python 3.12 runtime with uv");
+                try {
+                    await runDocumentProcess("uv", ["venv", "--seed", "--python", "3.12", join(root, "venv")], options);
+                }
+                catch (error) {
+                    throw new Error(`Install uv or configure an absolute Python 3.12 executable path. ${error instanceof Error ? error.message : error}`);
+                }
+            }
+        }
+        options.onProgress?.(`Installing Docling ${DOCLING_VERSION} in the isolated runtime`);
+        const lockPath = join(root, "requirements.lock");
+        // The CPU Transformers backend is already a standard dependency. The broad
+        // vlm extra additionally installs unrelated MLX/audio backends on Apple Silicon.
+        let install = [`docling[rapidocr]==${DOCLING_VERSION}`, "transformers==5.19.0", "rapidocr==3.9.1"];
+        try {
+            const locked = await readFile(lockPath, "utf8");
+            if (!locked.trim().split(/\r?\n/).every(line => /^[A-Za-z0-9_.-]+==[A-Za-z0-9_.+!-]+$/.test(line)))
+                throw new Error("Invalid document runtime dependency lock");
+            install = ["-r", lockPath];
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        try {
+            await runDocumentProcess("uv", ["pip", "install", "--python", pythonPath, "--index-url", "https://pypi.org/simple", ...install], { ...options, timeout: 45 * 60_000 });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await runDocumentProcess(pythonPath, ["-m", "pip", "install", "--index-url", "https://pypi.org/simple", ...install], { ...options, timeout: 45 * 60_000 });
+        }
+        const freeze = await runDocumentProcess(pythonPath, ["-m", "pip", "freeze"], options);
+        if (!freeze.split(/\r?\n/).every(line => /^[A-Za-z0-9_.-]+==[A-Za-z0-9_.+!-]+$/.test(line)))
+            throw new Error("Installed dependencies contain unexpected non-registry references");
+        await writeFile(lockPath, freeze + "\n");
+        options.onProgress?.("Downloading local models and verifying the offline conversion profile");
+        await runDocumentProcess(pythonPath, [bridgePath(), "setup", root], { ...options, timeout: 60 * 60_000 });
+        return doctorRuntime(options);
+    }
+    finally {
+        await release();
+    }
+}
+export async function runtimeFingerprint() {
+    return readFile(join(runtimeDirectory(), "ready.json"), "utf8");
+}
+let worker;
+let workerQueue = Promise.resolve();
+function closeWorker(active) {
+    if (active.idle)
+        clearTimeout(active.idle);
+    if (active.child.pid)
+        killPidTree(active.child.pid);
+    if (worker === active)
+        worker = undefined;
+}
+function parserWorker() {
+    if (shuttingDown)
+        throw new Error("Document runtime is shutting down");
+    const root = runtimeDirectory();
+    if (worker?.root === root) {
+        if (worker.idle)
+            clearTimeout(worker.idle);
+        return worker;
+    }
+    if (worker)
+        closeWorker(worker);
+    const child = spawn(runtimePython(), [bridgePath(), "serve", root], { stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32", windowsHide: true, env: { ...process.env, PYTHONUNBUFFERED: "1", PYTHONUTF8: "1", HF_HUB_OFFLINE: "1", TRANSFORMERS_OFFLINE: "1", HF_HUB_DISABLE_TELEMETRY: "1" } });
+    trackChild(child);
+    const active = { child, root, stdout: "" };
+    worker = active;
+    child.stdout.on("data", (chunk) => {
+        active.stdout += chunk.toString("utf8");
+        if (active.stdout.length > 4 * 1024 * 1024) {
+            active.pending?.reject(new Error("Parser response exceeds 4 MiB"));
+            closeWorker(active);
+            return;
+        }
+        let end;
+        while ((end = active.stdout.indexOf("\n")) >= 0) {
+            const line = active.stdout.slice(0, end);
+            active.stdout = active.stdout.slice(end + 1);
+            try {
+                const response = JSON.parse(line);
+                if (response.error)
+                    active.pending?.reject(new Error(response.error));
+                else
+                    active.pending?.resolve(response);
+            }
+            catch {
+                active.pending?.reject(new Error("Invalid parser response"));
+                closeWorker(active);
+            }
+        }
+    });
+    let errorTail = "";
+    child.stderr.on("data", (chunk) => { const text = chunk.toString("utf8"); errorTail = (errorTail + text).slice(-6000); for (const line of text.split(/\r?\n/))
+        if (line.trim())
+            active.pending?.progress?.(line.slice(0, 1000)); });
+    child.on("error", error => { active.pending?.reject(error); if (worker === active)
+        worker = undefined; });
+    child.on("close", code => { active.pending?.reject(new Error(`Document worker exited (${code}): ${errorTail}`)); if (worker === active)
+        worker = undefined; });
+    child.stdin.on("error", error => active.pending?.reject(error));
+    return active;
+}
+/** One queued local worker keeps model weights warm without parallel RAM spikes. */
+export async function runConversionWorker(input, options) {
+    const previous = workerQueue;
+    let release;
+    const gate = new Promise(done => { release = done; });
+    workerQueue = previous.then(() => gate);
+    try {
+        await waitDocumentQueue(previous, options.signal);
+        options.signal?.throwIfAborted();
+        const active = parserWorker();
+        return await new Promise((resolve, reject) => {
+            const finish = (error, response) => {
+                if (!active.pending)
+                    return;
+                active.pending = undefined;
+                clearTimeout(timer);
+                options.signal?.removeEventListener("abort", abort);
+                if (error) {
+                    closeWorker(active);
+                    reject(error);
+                }
+                else {
+                    active.idle = setTimeout(() => closeWorker(active), 10_000);
+                    active.idle.unref();
+                    resolve(response);
+                }
+            };
+            const abort = () => finish(new DOMException("Document operation canceled", "AbortError"));
+            const timer = setTimeout(() => finish(new Error("Document conversion exceeded 30 minutes")), 30 * 60_000);
+            active.pending = { resolve: response => finish(undefined, response), reject: error => finish(error), progress: options.onProgress };
+            options.signal?.addEventListener("abort", abort, { once: true });
+            active.child.stdin.write(JSON.stringify(input) + "\n");
+            if (options.signal?.aborted)
+                abort();
+        });
+    }
+    finally {
+        release();
+    }
+}

package/dist/server/document-conversion/service.js

@@ -0,0 +1,340 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readFile, writeFile, stat, mkdir, rm, rename, access, lstat, readdir, cp, copyFile } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve, isAbsolute } from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import lockfile from "proper-lockfile";
+import { documentDataDir } from "./settings.js";
+import { decodeText } from "../text-sniff.js";
+import { CONVERSION_PROFILE, ensureRuntimeReady, runConversionWorker, runtimeFingerprint, waitDocumentQueue } from "./runtime.js";
+export const DOCUMENT_EXTENSIONS = new Set([".pdf", ".md", ".markdown", ".txt", ".docx", ".xlsx", ".pptx"]);
+const locks = new Map();
+async function hashFile(path, signal) {
+    const hash = createHash("sha256"), stream = createReadStream(path, { signal });
+    for await (const chunk of stream)
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+function digest(value) { return createHash("sha256").update(value).digest("hex"); }
+function markdownImageNodes(text) {
+    const tree = unified().use(remarkParse).parse(text);
+    const nodes = [], references = new Set();
+    const visit = (node) => { nodes.push(node); if (node.type === "imageReference" && node.identifier)
+        references.add(node.identifier); node.children?.forEach(visit); };
+    visit(tree);
+    return nodes.filter(node => node.type === "image" || (node.type === "definition" && node.identifier && references.has(node.identifier)));
+}
+function imageSource(url, source, assets) {
+    if (assets !== undefined) {
+        if (!Object.hasOwn(assets, url) || !assets[url])
+            throw new Error("Image is not present in the archived evidence snapshot");
+        return assets[url];
+    }
+    return resolve(dirname(source), decodeURIComponent(url.split("#")[0]));
+}
+async function markdownDependencyFingerprint(text, source, assets) {
+    const dependencies = [];
+    for (const node of markdownImageNodes(text)) {
+        const url = node.url ?? "";
+        if (!url || /^(?:[a-z]+:|#)/i.test(url) || isAbsolute(url))
+            continue;
+        try {
+            const path = imageSource(url, source, assets), info = await stat(path);
+            if (!info.isFile() || info.size > 20 * 1024 * 1024)
+                throw new Error("Unsupported asset");
+            dependencies.push(`${url}:${await hashFile(path)}`);
+        }
+        catch {
+            dependencies.push(`${url}:missing`);
+        }
+    }
+    return digest(JSON.stringify(dependencies));
+}
+async function preserveMarkdownImages(text, source, output, warnings, assets) {
+    const replacements = [];
+    for (const node of markdownImageNodes(text)) {
+        const url = node.url ?? "";
+        if (!url || /^(?:https?:|data:|#)/i.test(url))
+            continue;
+        try {
+            if (isAbsolute(url) || /^[a-z]+:/i.test(url))
+                throw new Error("absolute image paths are not portable");
+            const local = imageSource(url, source, assets);
+            if (![".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".bmp", ".tiff"].includes(extname(local).toLowerCase()))
+                throw new Error("unsupported image format");
+            const info = await stat(local);
+            if (!info.isFile() || info.size > 20 * 1024 * 1024)
+                throw new Error("image is not a regular file below 20 MiB");
+            const target = `assets/${(await hashFile(local)).slice(0, 24)}${extname(local).toLowerCase()}`;
+            await copyFile(local, join(output, target));
+            const start = node.position?.start.offset, end = node.position?.end.offset;
+            if (start !== undefined && end !== undefined)
+                replacements.push({ start, end, text: node.type === "definition" ? `[${node.identifier}]: ${target}${node.title ? ` ${JSON.stringify(node.title)}` : ""}` : `![${(node.alt ?? "").replace(/]/g, "\\]")}](${target}${node.title ? ` ${JSON.stringify(node.title)}` : ""})` });
+        }
+        catch (error) {
+            warnings.push(`Markdown image was not copied: ${url}: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    for (const replacement of replacements.sort((a, b) => b.start - a.start))
+        text = text.slice(0, replacement.start) + replacement.text + text.slice(replacement.end);
+    return text;
+}
+export function textBlocks(text) {
+    const lines = text.split("\n"), blocks = [];
+    let start = 0, heading, fence;
+    const emit = (end) => {
+        const value = lines.slice(start, end).join("\n");
+        if (value.trim())
+            blocks.push({ id: `block-${blocks.length + 1}`, text: value, locator: { lineStart: start + 1, lineEnd: end, ...(heading ? { heading } : {}) } });
+        start = end;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const marker = lines[i].match(/^\s*(`{3,}|~{3,})/);
+        if (marker) {
+            if (!fence)
+                fence = marker[1];
+            else if (marker[1][0] === fence[0] && marker[1].length >= fence.length)
+                fence = undefined;
+        }
+        if (!fence && /^#{1,6}\s+/.test(lines[i])) {
+            emit(i);
+            heading = lines[i].replace(/^#{1,6}\s+/, "");
+        }
+        if (!fence && !lines[i].trim()) {
+            emit(i);
+            start = i + 1;
+        }
+    }
+    emit(lines.length);
+    return blocks;
+}
+export async function convertDocument(options) {
+    const key = resolve(options.outputDir), prior = locks.get(key) ?? Promise.resolve();
+    let release;
+    const lock = new Promise(done => { release = done; });
+    const chain = prior.then(() => lock);
+    locks.set(key, chain);
+    try {
+        await waitDocumentQueue(prior, options.signal);
+        options.signal?.throwIfAborted();
+        return await convert({ ...options, outputDir: key });
+    }
+    finally {
+        release();
+        if (locks.get(key) === chain)
+            locks.delete(key);
+    }
+}
+async function artifactFiles(root, prefix = "") {
+    const paths = [];
+    for (const entry of await readdir(join(root, prefix), { withFileTypes: true })) {
+        const path = join(prefix, entry.name);
+        if (entry.isSymbolicLink())
+            throw new Error("Parser artifacts must not contain symlinks");
+        if (entry.isDirectory())
+            paths.push(...await artifactFiles(root, path));
+        else if (entry.isFile() && path !== "manifest.json")
+            paths.push(path);
+    }
+    return paths;
+}
+async function loadResult(root, manifest) {
+    const sourceMap = JSON.parse(await readFile(join(root, "source-map.json"), "utf8"));
+    return { markdownPath: join(root, "document.md"), structurePath: join(root, "structure.json"), sourceMapPath: join(root, "source-map.json"), assetsDir: join(root, "assets"), sourceHash: manifest.sourceHash, parserVersion: manifest.parserVersion, warnings: manifest.warnings, status: manifest.status, blocks: sourceMap.blocks };
+}
+async function existingManifest(root, signal) {
+    try {
+        await access(root);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if ((await lstat(root)).isSymbolicLink())
+        throw new Error("Output directory must not be a symlink");
+    if ((await readdir(root)).length === 0)
+        return undefined;
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(root, "manifest.json"), "utf8"));
+    }
+    catch {
+        throw new Error("Output directory contains existing files without a conversion manifest; choose another directory");
+    }
+    if (manifest.schemaVersion !== 1 || !manifest.files || typeof manifest.files !== "object")
+        throw new Error("Invalid existing conversion manifest");
+    const actual = await artifactFiles(root);
+    if (actual.length !== Object.keys(manifest.files).length)
+        throw new Error("Conversion output has added or removed files; choose another directory to preserve changes");
+    for (const path of actual) {
+        if (!manifest.files[path] || await hashFile(join(root, path), signal) !== manifest.files[path])
+            throw new Error(`Conversion output was edited: ${path}. Choose another directory to preserve changes.`);
+    }
+    for (const required of ["document.md", "structure.json", "source-map.json"])
+        if (!manifest.files[required])
+            throw new Error("Incomplete conversion manifest");
+    return manifest;
+}
+async function destinationLock(root, signal) {
+    for (;;) {
+        signal?.throwIfAborted();
+        try {
+            return await lockfile.lock(root, { realpath: false, lockfilePath: `${root}.conversion-lock`, stale: 120_000, retries: 0 });
+        }
+        catch (error) {
+            if (error.code !== "ELOCKED")
+                throw error;
+            await new Promise(done => setTimeout(done, 100));
+        }
+    }
+}
+async function withArtifactMutationQueues(root, paths, operation) {
+    const ordered = [...new Set(paths)].sort();
+    const acquire = (index) => index === ordered.length ? operation() : withFileMutationQueue(join(root, ordered[index]), () => acquire(index + 1));
+    return acquire(0);
+}
+async function convert(options) {
+    const { outputDir, signal, onProgress } = options, inputPath = resolve(options.inputPath), suffix = extname(inputPath).toLowerCase();
+    if (!DOCUMENT_EXTENSIONS.has(suffix))
+        throw new Error(`Unsupported document format: ${suffix}`);
+    if (inputPath === outputDir || inputPath.startsWith(outputDir + "/") || inputPath.startsWith(outputDir + "\\"))
+        throw new Error("Output directory must not contain the source document");
+    const info = await stat(inputPath);
+    if (!info.isFile() || info.size > 100 * 1024 * 1024)
+        throw new Error("Document must be a file no larger than 100 MiB");
+    const sourceHash = await hashFile(inputPath, signal), plain = [".md", ".markdown", ".txt"].includes(suffix);
+    let parserVersion = "text-v1", fingerprint = "text-v1", markdownDependencies;
+    if (suffix === ".md" || suffix === ".markdown") {
+        if (info.size > 16 * 1024 * 1024)
+            throw new Error("Text documents are limited to 16 MiB");
+        markdownDependencies = await markdownDependencyFingerprint(decodeText(await readFile(inputPath)), inputPath, options.markdownAssets);
+        fingerprint += markdownDependencies;
+    }
+    if (!plain) {
+        const doctor = await ensureRuntimeReady({ signal, onProgress });
+        if (!doctor.ready)
+            throw new Error(`Local document runtime is not ready. Run /pdf-md setup. ${doctor.missing.join("; ")}`);
+        parserVersion = `docling-${doctor.parserVersion}`;
+        fingerprint = await runtimeFingerprint();
+    }
+    const cacheKey = digest(JSON.stringify({ sourceHash, suffix, profile: CONVERSION_PROFILE, fingerprint }));
+    await mkdir(dirname(outputDir), { recursive: true });
+    const unlock = await destinationLock(outputDir, signal);
+    try {
+        const existing = await existingManifest(outputDir, signal);
+        if (existing?.cacheKey === cacheKey && existing.status === "complete") {
+            const priorSource = JSON.parse(await readFile(join(outputDir, "source-map.json"), "utf8")).source;
+            if (priorSource === inputPath) {
+                onProgress?.("Using unchanged document conversion");
+                return await loadResult(outputDir, existing);
+            }
+        }
+        const cacheDir = join(documentDataDir(), "document-cache", cacheKey);
+        const staging = join(dirname(outputDir), `.${basename(outputDir)}-${randomUUID()}.partial`), backup = `${staging}.previous`;
+        await mkdir(join(staging, "assets"), { recursive: true });
+        let installed = false, backedUp = false;
+        try {
+            let warnings = [], status = "complete";
+            let reused;
+            try {
+                reused = await existingManifest(cacheDir, signal);
+            }
+            catch {
+                signal?.throwIfAborted();
+            }
+            if (reused?.cacheKey === cacheKey && reused.status === "complete") {
+                await cp(cacheDir, staging, { recursive: true });
+                warnings = reused.warnings;
+                status = reused.status;
+                const sourceMap = JSON.parse(await readFile(join(staging, "source-map.json"), "utf8"));
+                sourceMap.source = inputPath;
+                await writeFile(join(staging, "source-map.json"), JSON.stringify(sourceMap, null, 2));
+                const structure = JSON.parse(await readFile(join(staging, "structure.json"), "utf8"));
+                if (structure.origin && typeof structure.origin === "object")
+                    structure.origin.filename = basename(inputPath);
+                await writeFile(join(staging, "structure.json"), JSON.stringify(structure, null, 2));
+                onProgress?.("Reusing the local document content cache");
+            }
+            else if (plain) {
+                if (info.size > 16 * 1024 * 1024)
+                    throw new Error("Text documents are limited to 16 MiB");
+                const data = await readFile(inputPath);
+                try {
+                    new TextDecoder("utf-8", { fatal: true }).decode(data);
+                }
+                catch {
+                    warnings.push("Source is not UTF-8; decoded using the legacy text encoding fallback. Verify non-ASCII text.");
+                }
+                const text = decodeText(data).replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n"), blocks = textBlocks(text);
+                const markdown = suffix === ".txt" ? text : await preserveMarkdownImages(text, inputPath, staging, warnings, options.markdownAssets);
+                if (warnings.some(warning => warning.startsWith("Markdown image was not copied")))
+                    status = "partial";
+                await writeFile(join(staging, "document.md"), markdown.endsWith("\n") ? markdown : markdown + "\n");
+                await writeFile(join(staging, "structure.json"), JSON.stringify({ schemaVersion: 1, kind: "text", blocks }, null, 2));
+                await writeFile(join(staging, "source-map.json"), JSON.stringify({ schemaVersion: 1, source: inputPath, sourceHash, blocks }, null, 2));
+            }
+            else {
+                onProgress?.(`Converting ${basename(inputPath)} locally`);
+                const response = await runConversionWorker({ inputPath, outputDir: staging, sourceHash }, { signal, onProgress });
+                if (response.status !== "complete" && response.status !== "partial")
+                    throw new Error("Invalid parser completion status");
+                status = response.status;
+                warnings = response.warnings ?? [];
+            }
+            if (await hashFile(inputPath, signal) !== sourceHash)
+                throw new Error("Source changed during conversion; retry with the current document");
+            if (markdownDependencies !== undefined && await markdownDependencyFingerprint(decodeText(await readFile(inputPath)), inputPath, options.markdownAssets) !== markdownDependencies)
+                throw new Error("Markdown images changed during conversion; retry with the current document");
+            for (const path of ["document.md", "structure.json", "source-map.json"])
+                await access(join(staging, path));
+            const files = {};
+            for (const path of await artifactFiles(staging))
+                files[path] = await hashFile(join(staging, path), signal);
+            const manifest = { schemaVersion: 1, cacheKey, sourceHash, parserVersion, status, warnings, files };
+            await writeFile(join(staging, "manifest.json"), JSON.stringify(manifest, null, 2));
+            signal?.throwIfAborted();
+            onProgress?.("Committing verified document artifacts");
+            await withArtifactMutationQueues(outputDir, ["manifest.json", ...Object.keys(existing?.files ?? {}), ...Object.keys(files)], async () => {
+                // Revalidate after the slow parser run, catching edits made during OCR.
+                await existingManifest(outputDir, signal);
+                try {
+                    await access(outputDir);
+                    await rename(outputDir, backup);
+                    backedUp = true;
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+                await rename(staging, outputDir);
+                installed = true;
+            });
+            if (status === "complete") {
+                await mkdir(dirname(cacheDir), { recursive: true });
+                const temporaryCache = `${cacheDir}.${randomUUID()}.partial`;
+                try {
+                    await cp(outputDir, temporaryCache, { recursive: true });
+                    await rename(temporaryCache, cacheDir);
+                }
+                catch { /* Cache races or cache I/O failures never invalidate the output. */ }
+                finally {
+                    await rm(temporaryCache, { recursive: true, force: true });
+                }
+            }
+            return await loadResult(outputDir, manifest);
+        }
+        finally {
+            if (!installed && backedUp)
+                await rename(backup, outputDir);
+            await rm(staging, { recursive: true, force: true });
+            if (installed)
+                await rm(backup, { recursive: true, force: true });
+        }
+    }
+    finally {
+        await unlock();
+    }
+}