@yadsh/dsh-qa-surface 0.5.0 → 0.6.0

package/lib/documents/artifacts/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../src/documents/artifacts/ids.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AACpD,MAAM,UAAU,GAAG,EAAE,CAAC;AACtB,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,QAAQ,GAAG,cAAc,CAAC;AAEhC,SAAS,UAAU,CAAC,SAAiB;IACnC,IAAI,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACvE,MAAM,MAAM,GAAa,IAAI,KAAK,CAAS,UAAU,CAAC,CAAC;IACvD,KAAK,IAAI,KAAK,GAAG,UAAU,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACxD,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,SAAS,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC;QAChD,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,YAAY;IACnB,MAAM,KAAK,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;IACxC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,QAAQ,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC;IACvC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,UAAU,CAAC,GAAG,GAAW,IAAI,CAAC,GAAG,EAAE;IACjD,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,YAAY,EAAE,EAAE,CAAC;AAC/C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,gBAAgB,CAAC,GAAG,GAAW,IAAI,CAAC,GAAG,EAAE;IACvD,OAAO,OAAO,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,mBAAmB,GAAG,+BAA+B,CAAC;AAE5D,0EAA0E;AAC1E,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC"}

package/lib/documents/artifacts/manifest.js

@@ -0,0 +1,66 @@
+/**
+ * Manifest construction and persistence (§19).
+ *
+ * The manifest is the source of truth about an artifact: which operation,
+ * which backends and versions, which template (and its hash), which files came
+ * out, which warnings were raised, and which session/workspace the bundle
+ * belongs to. Logical reproducibility rests on it, because byte-level
+ * reproducibility of DOCX/PDF cannot be promised (§31).
+ */
+import path from "node:path";
+import { DocumentError, asDocumentError } from "../errors.js";
+export const MANIFEST_FILE = "manifest.json";
+export const MANIFEST_SCHEMA_VERSION = 1;
+export function buildManifest(input) {
+    return {
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
+        artifactId: input.artifactId,
+        operation: input.operation,
+        createdAt: input.createdAt,
+        input: input.input,
+        outputs: input.outputs,
+        ...(input.template === undefined ? {} : { template: input.template }),
+        ...(input.templateSha256 === undefined
+            ? {}
+            : { templateSha256: input.templateSha256 }),
+        backends: input.backends,
+        warnings: input.warnings,
+        scope: input.scope,
+    };
+}
+export async function writeManifest(store, artifactId, manifest) {
+    const written = await store.write(path.join(artifactId, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+    return written.path;
+}
+export async function readManifest(store, artifactId) {
+    const raw = await store
+        .read(path.join(artifactId, MANIFEST_FILE))
+        .catch((error) => {
+        throw asDocumentError(error, "FILE_NOT_FOUND", "artifact store");
+    });
+    try {
+        const parsed = JSON.parse(raw.toString("utf8"));
+        if (parsed.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+            throw new Error(`unsupported manifest schema ${String(parsed.schemaVersion)}`);
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new DocumentError("INVALID_INPUT", `the artifact manifest of ${artifactId} is unreadable`, { cause: error });
+    }
+}
+/** Project a tool-level file result onto the manifest's output record. */
+export function outputRecord(file) {
+    return {
+        format: file.format,
+        path: path.basename(file.path),
+        sha256: file.sha256,
+        size: file.size,
+        status: file.status,
+        ...(file.error === undefined ? {} : { error: file.error }),
+    };
+}
+export function formatOfOperation(operation) {
+    return operation === "document_create" ? "md" : "unknown";
+}
+//# sourceMappingURL=manifest.js.map

package/lib/documents/artifacts/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/documents/artifacts/manifest.ts"],"names":[],"mappings":"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"}

package/lib/documents/artifacts/store.js

@@ -0,0 +1,169 @@
+/**
+ * Artifact bundle storage (§18, §47).
+ *
+ * One directory per operation:
+ *
+ * ```text
+ * <root>/<artifact-id>/
+ *   manifest.json
+ *   source.md
+ *   input/original.pdf
+ *   assets/
+ *   output.docx
+ *   extracted.md
+ * ```
+ *
+ * Everything the store writes goes through a root-relative path that is
+ * validated first, and every file lands atomically (temp file + rename) so a
+ * crashed host never leaves a half-written artifact that a later read would
+ * trust. Job temp directories live under `<root>/.tmp` and are removed on both
+ * success and failure (§47).
+ */
+import { randomBytes } from "node:crypto";
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { DocumentError, asDocumentError } from "../errors.js";
+import { assertInsideRoot } from "../security/paths.js";
+import { createArtifactId, isArtifactId } from "./ids.js";
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+export async function sha256OfFile(filePath) {
+    return sha256Hex(await readFile(filePath));
+}
+export class ArtifactStore {
+    root;
+    constructor(options) {
+        this.root = path.resolve(options.root);
+    }
+    /** Absolute path of a root-relative artifact member, containment checked. */
+    path(relativePath) {
+        return assertInsideRoot(this.root, path.resolve(this.root, relativePath), "artifact path");
+    }
+    artifactDir(artifactId) {
+        if (!isArtifactId(artifactId)) {
+            throw new DocumentError("INVALID_INPUT", `"${artifactId}" is not an artifact id`);
+        }
+        return this.path(artifactId);
+    }
+    /** Prepare a fresh bundle directory and return its id. */
+    async create(now = Date.now()) {
+        for (let attempt = 0; attempt < 5; attempt += 1) {
+            const artifactId = createArtifactId(now);
+            const dir = this.artifactDir(artifactId);
+            try {
+                await mkdir(dir, { recursive: false });
+                return { artifactId, dir };
+            }
+            catch (error) {
+                if (error.code !== "EEXIST") {
+                    throw asDocumentError(error, "ARTIFACT_WRITE_FAILED");
+                }
+            }
+        }
+        throw new DocumentError("ARTIFACT_WRITE_FAILED", "unable to allocate an artifact directory");
+    }
+    async ensureDir(relativePath) {
+        const target = this.path(relativePath);
+        await mkdir(target, { recursive: true });
+        return target;
+    }
+    /** Atomically write a root-relative member. */
+    async write(relativePath, data) {
+        const target = this.path(relativePath);
+        const payload = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+        const temp = `${target}.tmp-${randomBytes(6).toString("hex")}`;
+        try {
+            await mkdir(path.dirname(target), { recursive: true });
+            await writeFile(temp, payload);
+            await rename(temp, target);
+        }
+        catch (error) {
+            await rm(temp, { force: true }).catch(() => undefined);
+            throw asDocumentError(error, "ARTIFACT_WRITE_FAILED");
+        }
+        return { path: target, size: payload.length, sha256: sha256Hex(payload) };
+    }
+    async read(relativePath) {
+        return readFile(this.path(relativePath));
+    }
+    async fingerprint(relativePath) {
+        const target = this.path(relativePath);
+        const details = await stat(target);
+        return {
+            path: target,
+            size: details.size,
+            sha256: await sha256OfFile(target),
+        };
+    }
+    async exists(relativePath) {
+        try {
+            await stat(this.path(relativePath));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Job-scoped temp directory: never an artifact, always removed (§47). */
+    async createWorkDir(jobId) {
+        const dir = this.path(path.join(".tmp", jobId));
+        await mkdir(dir, { recursive: true });
+        return dir;
+    }
+    async removeWorkDir(dir) {
+        if (!path.resolve(dir).startsWith(this.path(".tmp")))
+            return;
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+    /** Bundle directories, newest first, with their modification time. */
+    async list() {
+        let names;
+        try {
+            names = await readdir(this.root);
+        }
+        catch {
+            return [];
+        }
+        const artifacts = [];
+        for (const name of names) {
+            if (!isArtifactId(name))
+                continue;
+            const dir = this.path(name);
+            try {
+                const details = await stat(dir);
+                if (!details.isDirectory())
+                    continue;
+                artifacts.push({ artifactId: name, dir, modifiedAt: details.mtime });
+            }
+            catch {
+                continue;
+            }
+        }
+        return artifacts.sort((left, right) => left.modifiedAt < right.modifiedAt ? 1 : -1);
+    }
+    /** Retention sweep (§41): drop bundles older than `maxAgeDays`. */
+    async cleanup(options) {
+        const cutoff = (options.now ?? new Date()).getTime() - options.maxAgeDays * 86_400_000;
+        const removed = [];
+        for (const artifact of await this.list()) {
+            if (artifact.modifiedAt.getTime() >= cutoff)
+                continue;
+            await rm(artifact.dir, { recursive: true, force: true }).catch(() => undefined);
+            removed.push(artifact.artifactId);
+        }
+        const tempRoot = this.path(".tmp");
+        const tempNames = await readdir(tempRoot).catch(() => []);
+        for (const name of tempNames) {
+            const dir = path.join(tempRoot, name);
+            const details = await stat(dir).catch(() => undefined);
+            if (details === undefined || details.mtime.getTime() >= cutoff)
+                continue;
+            await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+        }
+        await rm(tempRoot, { recursive: true, force: true }).catch(() => undefined);
+        return { removed };
+    }
+}
+//# sourceMappingURL=store.js.map

package/lib/documents/artifacts/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/documents/artifacts/store.ts"],"names":[],"mappings":"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"}

package/lib/documents/capabilities.js

@@ -0,0 +1,93 @@
+/**
+ * Capability discovery (§43) and backend health (§42).
+ *
+ * Health separates required from optional backends on purpose: a deployment
+ * without Docling cannot extract PDFs, but it still creates documents, so the
+ * subsystem reports `degraded` and names what is missing instead of declaring
+ * itself down. An optional backend that was never enabled reports `disabled`,
+ * which is not a fault.
+ */
+import { createProviders, } from "./providers/registry.js";
+import { runProcess } from "./providers/process.js";
+import { CONVERSION_ROUTES } from "./orchestrator/convert-document.js";
+import { loadTemplateRegistry, templateNames, } from "./templates/registry.js";
+async function probeExecutable(executable, timeoutMs) {
+    try {
+        const result = await runProcess(executable, ["--version"], {
+            timeoutMs: Math.min(timeoutMs, 10_000),
+            maxStdoutBytes: 8 * 1024,
+            backend: executable,
+            context: "probing backend availability",
+        });
+        return result.exitCode === 0 ? "ok" : "unavailable";
+    }
+    catch {
+        return "unavailable";
+    }
+}
+export async function documentHealth(options) {
+    const { config, providers } = options;
+    const required = {};
+    const optional = {};
+    required["pandoc"] =
+        options.probeProcessBackends === false
+            ? "ok"
+            : await probeExecutable(config.pandoc.executable, config.pandoc.timeoutMs);
+    required["libreoffice"] =
+        options.probeProcessBackends === false
+            ? "ok"
+            : await probeExecutable(config.libreoffice.executable, config.libreoffice.timeoutMs);
+    required["docling"] =
+        providers.doclingHealth === undefined
+            ? "disabled"
+            : await providers.doclingHealth();
+    optional["typst"] = config.typst.enabled ? "ok" : "disabled";
+    optional["markitdown"] =
+        providers.markitdownHealth === undefined
+            ? "disabled"
+            : await providers.markitdownHealth();
+    const requiredValues = Object.values(required);
+    const status = requiredValues.every((entry) => entry === "ok")
+        ? "ok"
+        : requiredValues.every((entry) => entry !== "ok")
+            ? "unavailable"
+            : "degraded";
+    return { status, required, optional };
+}
+export function documentCapabilities(options) {
+    const config = options.config;
+    const create = [...config.create.allowFormats];
+    const extract = [];
+    if (options.providers.docling !== undefined)
+        extract.push("docx", "pdf");
+    else if (options.providers.markitdown !== undefined)
+        extract.push("docx", "pdf");
+    const convert = CONVERSION_ROUTES.filter(([from, to]) => {
+        if (from === "md")
+            return to === "docx" ? create.includes("docx") : create.includes("pdf");
+        return extract.includes(from);
+    }).map(([from, to]) => [from, to]);
+    return {
+        enabled: config.enabled,
+        create,
+        extract,
+        convert,
+        ocr: config.docling.enabled || options.providers.markitdown !== undefined,
+        templates: templateNames(options.templates),
+        pdfModes: config.typst.enabled
+            ? ["auto", "office", "typst"]
+            : ["auto", "office"],
+    };
+}
+/** Load the template registry of a workspace for capability reporting. */
+export async function capabilitiesForRoot(options) {
+    const templates = options.templateRoot === undefined
+        ? await loadTemplateRegistry(undefined)
+        : await loadTemplateRegistry(options.templateRoot);
+    return documentCapabilities({
+        config: options.config,
+        providers: createProviders(options.config, options.seams ?? {}),
+        templates,
+    });
+}
+//# sourceMappingURL=capabilities.js.map

package/lib/documents/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/documents/capabilities.ts"],"names":[],"mappings":"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"}

package/lib/documents/config.js

@@ -0,0 +1,302 @@
+/**
+ * Configuration of the document subsystem (§20).
+ *
+ * The subsystem is part of the `qa-surface` namespace, so this resolver
+ * follows the same shape as the other domains: it normalizes, validates and
+ * freezes, and the schema in `src/config.ts` takes every default from
+ * {@link DEFAULT_QA_DOCUMENTS_CONFIG} so an untouched deployment sends the
+ * resolver nothing at all.
+ *
+ * Environment overrides are applied in `applyDocumentsEnvOverrides`, on the
+ * way into the plugin, and only for the documented variables — a deployment
+ * that injects secrets into the process environment does not thereby get to
+ * reconfigure the pipeline.
+ */
+import { DEFAULT_QA_DOCUMENTS_CONFIG, } from "./defaults.js";
+import { DocumentError } from "./errors.js";
+export { DEFAULT_QA_DOCUMENTS_CONFIG, } from "./defaults.js";
+const MS_PER_MINUTE = 60_000;
+/**
+ * Absolute-path test for the configuration surface.
+ *
+ * A hand-rolled check rather than `node:path.isAbsolute`: the schema that reads
+ * these defaults is bundled into the browser settings page, and the page cannot
+ * load a Node builtin. Only absolute paths are accepted, so there is nothing to
+ * resolve here — canonicalization happens host-side, when the path is used.
+ */
+function isAbsolutePath(value) {
+    return (/^[A-Za-z]:[\\/]/u.test(value) ||
+        value.startsWith("/") ||
+        value.startsWith("\\\\"));
+}
+function readBoolean(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+function readInteger(value, fallback, bounds, label) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new DocumentError("INVALID_INPUT", `${label} must be a number`);
+    }
+    const rounded = Math.round(value);
+    if (rounded < bounds.min || rounded > bounds.max) {
+        throw new DocumentError("INVALID_INPUT", `${label} must be between ${bounds.min} and ${bounds.max}`, { details: { label, value } });
+    }
+    return rounded;
+}
+function readString(value, fallback, label) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "string") {
+        throw new DocumentError("INVALID_INPUT", `${label} must be a string`);
+    }
+    const trimmed = value.trim();
+    return trimmed === "" ? fallback : trimmed;
+}
+function readNullableAbsolutePath(value, label) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string") {
+        throw new DocumentError("INVALID_INPUT", `${label} must be a path`);
+    }
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return null;
+    if (!isAbsolutePath(trimmed)) {
+        throw new DocumentError("INVALID_INPUT", `${label} must be an absolute path (relative and traversal forms are refused)`, { details: { label } });
+    }
+    return trimmed;
+}
+function readEnum(value, allowed, fallback, label) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        throw new DocumentError("INVALID_INPUT", `${label} must be one of: ${allowed.join(", ")}`, { details: { label } });
+    }
+    return value;
+}
+function readStringList(value, fallback) {
+    if (!Array.isArray(value))
+        return [...fallback];
+    const entries = value
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== "");
+    return [...new Set(entries)];
+}
+function readAbsolutePathList(value, label) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((entry) => {
+        if (typeof entry !== "string" || entry.trim() === "") {
+            throw new DocumentError("INVALID_INPUT", `${label} entries must be paths`);
+        }
+        const entryPath = entry.trim();
+        if (!isAbsolutePath(entryPath)) {
+            throw new DocumentError("INVALID_INPUT", `${label} entries must be absolute paths`);
+        }
+        return entryPath;
+    });
+}
+function assertHttpUrl(value, label) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new DocumentError("INVALID_INPUT", `${label} must be an http(s) URL`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new DocumentError("INVALID_INPUT", `${label} must be an http(s) URL`);
+    }
+    return value;
+}
+/** Materialize and validate the document configuration. */
+export function resolveDocumentsConfig(input = {}) {
+    const D = DEFAULT_QA_DOCUMENTS_CONFIG;
+    const storage = input.storage ?? {};
+    const templates = input.templates ?? {};
+    const create = input.create ?? {};
+    const extraction = input.extraction ?? {};
+    const docling = input.docling ?? {};
+    const pandoc = input.pandoc ?? {};
+    const libreoffice = input.libreoffice ?? {};
+    const typst = input.typst ?? {};
+    const markitdown = input.markitdown ?? {};
+    const workers = input.workers ?? {};
+    const retention = input.retention ?? {};
+    const limits = input.limits ?? {};
+    const allowFormats = readStringList(create.allowFormats, D.create.allowFormats).filter((entry) => entry === "docx" || entry === "pdf");
+    if (allowFormats.length === 0) {
+        throw new DocumentError("INVALID_INPUT", "documents.create.allowFormats must list at least one of: docx, pdf");
+    }
+    return Object.freeze({
+        enabled: readBoolean(input.enabled, D.enabled),
+        storage: Object.freeze({
+            root: readNullableAbsolutePath(storage.root, "documents.storage.root"),
+            retainSource: readBoolean(storage.retainSource, D.storage.retainSource),
+            retainInputs: readBoolean(storage.retainInputs, D.storage.retainInputs),
+            allowedInputRoots: Object.freeze(readAbsolutePathList(storage.allowedInputRoots, "documents.storage.allowedInputRoots")),
+        }),
+        templates: Object.freeze({
+            root: readNullableAbsolutePath(templates.root, "documents.templates.root"),
+            default: readString(templates.default, D.templates.default, "documents.templates.default"),
+        }),
+        create: Object.freeze({
+            defaultPdfMode: readEnum(create.defaultPdfMode, ["auto", "office", "typst"], D.create.defaultPdfMode, "documents.create.defaultPdfMode"),
+            allowFormats: Object.freeze(allowFormats),
+            allowRawMarkup: readBoolean(create.allowRawMarkup, D.create.allowRawMarkup),
+            toc: readBoolean(create.toc, D.create.toc),
+        }),
+        extraction: Object.freeze({
+            defaultMode: readEnum(extraction.defaultMode, ["auto", "fast", "accurate"], D.extraction.defaultMode, "documents.extraction.defaultMode"),
+            ocr: readEnum(extraction.ocr, ["auto", "off", "force"], D.extraction.ocr, "documents.extraction.ocr"),
+            ocrLanguages: Object.freeze(readStringList(extraction.ocrLanguages, D.extraction.ocrLanguages)),
+            extractImages: readBoolean(extraction.extractImages, D.extraction.extractImages),
+            extractTables: readBoolean(extraction.extractTables, D.extraction.extractTables),
+            preservePageMarkers: readBoolean(extraction.preservePageMarkers, D.extraction.preservePageMarkers),
+            allowFallback: readBoolean(extraction.allowFallback, D.extraction.allowFallback),
+            maxInlineChars: readInteger(extraction.maxInlineChars, D.extraction.maxInlineChars, { min: 1_000, max: 5_000_000 }, "documents.extraction.maxInlineChars"),
+        }),
+        docling: Object.freeze({
+            enabled: readBoolean(docling.enabled, D.docling.enabled),
+            baseUrl: assertHttpUrl(readString(docling.baseUrl, D.docling.baseUrl, "documents.docling.baseUrl").replace(/\/+$/u, ""), "documents.docling.baseUrl"),
+            timeoutMs: readInteger(docling.timeoutMs, D.docling.timeoutMs, { min: 1_000, max: 600_000 }, "documents.docling.timeoutMs"),
+        }),
+        pandoc: Object.freeze({
+            executable: readString(pandoc.executable, D.pandoc.executable, "documents.pandoc.executable"),
+            timeoutMs: readInteger(pandoc.timeoutMs, D.pandoc.timeoutMs, { min: 1_000, max: 600_000 }, "documents.pandoc.timeoutMs"),
+        }),
+        libreoffice: Object.freeze({
+            executable: readString(libreoffice.executable, D.libreoffice.executable, "documents.libreoffice.executable"),
+            timeoutMs: readInteger(libreoffice.timeoutMs, D.libreoffice.timeoutMs, { min: 1_000, max: 600_000 }, "documents.libreoffice.timeoutMs"),
+        }),
+        typst: Object.freeze({
+            enabled: readBoolean(typst.enabled, D.typst.enabled),
+            executable: readString(typst.executable, D.typst.executable, "documents.typst.executable"),
+            timeoutMs: readInteger(typst.timeoutMs, D.typst.timeoutMs, { min: 1_000, max: 600_000 }, "documents.typst.timeoutMs"),
+        }),
+        markitdown: Object.freeze({
+            enabled: readBoolean(markitdown.enabled, D.markitdown.enabled),
+            executable: readString(markitdown.executable, D.markitdown.executable, "documents.markitdown.executable"),
+            timeoutMs: readInteger(markitdown.timeoutMs, D.markitdown.timeoutMs, { min: 1_000, max: 600_000 }, "documents.markitdown.timeoutMs"),
+        }),
+        workers: Object.freeze({
+            renderConcurrency: readInteger(workers.renderConcurrency, D.workers.renderConcurrency, { min: 1, max: 16 }, "documents.workers.renderConcurrency"),
+            extractionConcurrency: readInteger(workers.extractionConcurrency, D.workers.extractionConcurrency, { min: 1, max: 16 }, "documents.workers.extractionConcurrency"),
+            ocrConcurrency: readInteger(workers.ocrConcurrency, D.workers.ocrConcurrency, { min: 1, max: 16 }, "documents.workers.ocrConcurrency"),
+        }),
+        retention: Object.freeze({
+            enabled: readBoolean(retention.enabled, D.retention.enabled),
+            maxAgeDays: readInteger(retention.maxAgeDays, D.retention.maxAgeDays, { min: 1, max: 3_650 }, "documents.retention.maxAgeDays"),
+            cleanupIntervalHours: readInteger(retention.cleanupIntervalHours, D.retention.cleanupIntervalHours, { min: 1, max: 168 }, "documents.retention.cleanupIntervalHours"),
+        }),
+        limits: Object.freeze({
+            maxInputBytes: readInteger(limits.maxInputBytes, D.limits.maxInputBytes, { min: 1_024, max: 4_294_967_296 }, "documents.limits.maxInputBytes"),
+            maxMarkdownChars: readInteger(limits.maxMarkdownChars, D.limits.maxMarkdownChars, { min: 1_000, max: 50_000_000 }, "documents.limits.maxMarkdownChars"),
+            maxPages: readInteger(limits.maxPages, D.limits.maxPages, { min: 1, max: 100_000 }, "documents.limits.maxPages"),
+            maxExtractedImages: readInteger(limits.maxExtractedImages, D.limits.maxExtractedImages, { min: 0, max: 10_000 }, "documents.limits.maxExtractedImages"),
+            maxAssetBytes: readInteger(limits.maxAssetBytes, D.limits.maxAssetBytes, { min: 1_024, max: 1_073_741_824 }, "documents.limits.maxAssetBytes"),
+            maxResponseBytes: readInteger(limits.maxResponseBytes, D.limits.maxResponseBytes, { min: 1_024, max: 1_073_741_824 }, "documents.limits.maxResponseBytes"),
+            maxExtractedMarkdownBytes: readInteger(limits.maxExtractedMarkdownBytes, D.limits.maxExtractedMarkdownBytes, { min: 1_024, max: 1_073_741_824 }, "documents.limits.maxExtractedMarkdownBytes"),
+            allowedAssetMimeTypes: Object.freeze(readStringList(limits.allowedAssetMimeTypes, D.limits.allowedAssetMimeTypes).map((entry) => entry.toLowerCase())),
+        }),
+    });
+}
+/** Parse a boolean env value; unknown text leaves the configured value. */
+function envBoolean(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const normalized = raw.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+        return false;
+    return fallback;
+}
+function envInteger(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const parsed = Number.parseInt(raw.trim(), 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+/**
+ * Apply the documented environment overrides (§20). Kept out of
+ * {@link resolveDocumentsConfig} so the resolver stays a pure function of its
+ * input — configuration tests never depend on the ambient environment.
+ */
+export function applyDocumentsEnvOverrides(config, env) {
+    const value = (key) => {
+        const raw = env[key];
+        return raw === undefined || raw.trim() === "" ? undefined : raw.trim();
+    };
+    const storageRoot = value("QA_DOCUMENTS_STORAGE_ROOT");
+    const templatesRoot = value("QA_DOCUMENTS_TEMPLATES_ROOT");
+    const doclingBaseUrl = value("QA_DOCLING_BASE_URL");
+    const doclingTimeout = value("QA_DOCLING_TIMEOUT_MS");
+    const pandocExecutable = value("QA_PANDOC_EXECUTABLE");
+    const libreofficeExecutable = value("QA_LIBREOFFICE_EXECUTABLE");
+    const markitdownExecutable = value("QA_MARKITDOWN_EXECUTABLE");
+    const ocrLanguages = value("QA_DOCUMENTS_OCR_LANGUAGES");
+    const maxInputBytes = value("QA_DOCUMENTS_MAX_INPUT_BYTES");
+    return {
+        ...config,
+        enabled: envBoolean(value("QA_DOCUMENTS_ENABLED"), config.enabled ?? true),
+        storage: {
+            ...config.storage,
+            ...(storageRoot === undefined ? {} : { root: storageRoot }),
+        },
+        templates: {
+            ...config.templates,
+            ...(templatesRoot === undefined ? {} : { root: templatesRoot }),
+        },
+        docling: {
+            ...config.docling,
+            ...(doclingBaseUrl === undefined ? {} : { baseUrl: doclingBaseUrl }),
+            ...(doclingTimeout === undefined
+                ? {}
+                : {
+                    timeoutMs: envInteger(doclingTimeout, config.docling?.timeoutMs ?? 0),
+                }),
+        },
+        pandoc: {
+            ...config.pandoc,
+            ...(pandocExecutable === undefined
+                ? {}
+                : { executable: pandocExecutable }),
+        },
+        libreoffice: {
+            ...config.libreoffice,
+            ...(libreofficeExecutable === undefined
+                ? {}
+                : { executable: libreofficeExecutable }),
+        },
+        markitdown: {
+            ...config.markitdown,
+            ...(markitdownExecutable === undefined
+                ? {}
+                : { executable: markitdownExecutable }),
+        },
+        extraction: {
+            ...config.extraction,
+            ...(ocrLanguages === undefined
+                ? {}
+                : {
+                    ocrLanguages: ocrLanguages.split(",").map((entry) => entry.trim()),
+                }),
+        },
+        limits: {
+            ...config.limits,
+            ...(maxInputBytes === undefined
+                ? {}
+                : {
+                    maxInputBytes: envInteger(maxInputBytes, config.limits?.maxInputBytes ?? 0),
+                }),
+        },
+    };
+}
+/** Milliseconds a retention sweep interval would wait. */
+export function retentionIntervalMs(config) {
+    return config.retention.cleanupIntervalHours * 60 * MS_PER_MINUTE;
+}
+//# sourceMappingURL=config.js.map