@yadsh/dsh-qa-surface 0.5.0 → 0.6.1

package/lib/types/documents/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { type QaDocumentsConfig, type ResolvedQaDocumentsConfig } from "./defaults.js";
+export { DEFAULT_QA_DOCUMENTS_CONFIG, type QaDocumentsCommandConfig, type QaDocumentsConfig, type QaDocumentsCreateConfig, type QaDocumentsEndpointConfig, type QaDocumentsExtractionConfig, type QaDocumentsLimitsConfig, type QaDocumentsRetentionConfig, type QaDocumentsStorageConfig, type QaDocumentsTemplatesConfig, type QaDocumentsWorkersConfig, type ResolvedQaDocumentsConfig, } from "./defaults.js";
+/** Materialize and validate the document configuration. */
+export declare function resolveDocumentsConfig(input?: QaDocumentsConfig): ResolvedQaDocumentsConfig;
+/**
+ * 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 declare function applyDocumentsEnvOverrides(config: QaDocumentsConfig, env: NodeJS.ProcessEnv): QaDocumentsConfig;
+/** Milliseconds a retention sweep interval would wait. */
+export declare function retentionIntervalMs(config: ResolvedQaDocumentsConfig): number;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/documents/defaults.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Canonical document defaults (§20).
+ *
+ * This module must stay free of Node builtins: it is the only part of the
+ * document subsystem the browser settings bundle reaches (through the QA
+ * surface's resolved configuration), and the page cannot load `node:*`. The
+ * resolver and everything that touches the filesystem live in `config.ts`,
+ * which imports these values.
+ */
+import type { CreateFormat, ExtractionMode, OcrMode, PdfMode } from "./types.js";
+export interface QaDocumentsStorageConfig {
+    /** Absolute artifact root; `null` means `<session cwd>/.qa/artifacts/documents`. */
+    readonly root?: string | null;
+    readonly retainSource?: boolean;
+    readonly retainInputs?: boolean;
+    /** Extra roots an input file may be read from, beside the session workspace. */
+    readonly allowedInputRoots?: readonly string[];
+}
+export interface QaDocumentsTemplatesConfig {
+    /** Absolute template root; `null` probes the session workspace. */
+    readonly root?: string | null;
+    readonly default?: string;
+}
+export interface QaDocumentsCreateConfig {
+    readonly defaultPdfMode?: PdfMode;
+    readonly allowFormats?: readonly CreateFormat[];
+    readonly allowRawMarkup?: boolean;
+    readonly toc?: boolean;
+}
+export interface QaDocumentsExtractionConfig {
+    readonly defaultMode?: ExtractionMode;
+    readonly ocr?: OcrMode;
+    readonly ocrLanguages?: readonly string[];
+    readonly extractImages?: boolean;
+    readonly extractTables?: boolean;
+    readonly preservePageMarkers?: boolean;
+    readonly allowFallback?: boolean;
+    /** Markdown returned inline to the model is capped at this many characters. */
+    readonly maxInlineChars?: number;
+}
+export interface QaDocumentsEndpointConfig {
+    readonly enabled?: boolean;
+    readonly baseUrl?: string;
+}
+export interface QaDocumentsCommandConfig {
+    readonly enabled?: boolean;
+    readonly executable?: string;
+    readonly timeoutMs?: number;
+}
+export interface QaDocumentsWorkersConfig {
+    readonly renderConcurrency?: number;
+    readonly extractionConcurrency?: number;
+    readonly ocrConcurrency?: number;
+}
+export interface QaDocumentsRetentionConfig {
+    readonly enabled?: boolean;
+    readonly maxAgeDays?: number;
+    readonly cleanupIntervalHours?: number;
+}
+export interface QaDocumentsLimitsConfig {
+    readonly maxInputBytes?: number;
+    readonly maxMarkdownChars?: number;
+    readonly maxPages?: number;
+    readonly maxExtractedImages?: number;
+    readonly maxAssetBytes?: number;
+    readonly maxResponseBytes?: number;
+    readonly maxExtractedMarkdownBytes?: number;
+    readonly allowedAssetMimeTypes?: readonly string[];
+}
+export interface QaDocumentsConfig {
+    readonly enabled?: boolean;
+    readonly storage?: QaDocumentsStorageConfig;
+    readonly templates?: QaDocumentsTemplatesConfig;
+    readonly create?: QaDocumentsCreateConfig;
+    readonly extraction?: QaDocumentsExtractionConfig;
+    readonly docling?: QaDocumentsEndpointConfig & {
+        readonly timeoutMs?: number;
+    };
+    readonly pandoc?: QaDocumentsCommandConfig;
+    readonly libreoffice?: QaDocumentsCommandConfig;
+    readonly typst?: QaDocumentsCommandConfig;
+    readonly markitdown?: QaDocumentsCommandConfig;
+    readonly workers?: QaDocumentsWorkersConfig;
+    readonly retention?: QaDocumentsRetentionConfig;
+    readonly limits?: QaDocumentsLimitsConfig;
+}
+export interface ResolvedQaDocumentsConfig {
+    readonly enabled: boolean;
+    readonly storage: {
+        readonly root: string | null;
+        readonly retainSource: boolean;
+        readonly retainInputs: boolean;
+        readonly allowedInputRoots: readonly string[];
+    };
+    readonly templates: {
+        readonly root: string | null;
+        readonly default: string;
+    };
+    readonly create: {
+        readonly defaultPdfMode: PdfMode;
+        readonly allowFormats: readonly CreateFormat[];
+        readonly allowRawMarkup: boolean;
+        readonly toc: boolean;
+    };
+    readonly extraction: {
+        readonly defaultMode: ExtractionMode;
+        readonly ocr: OcrMode;
+        readonly ocrLanguages: readonly string[];
+        readonly extractImages: boolean;
+        readonly extractTables: boolean;
+        readonly preservePageMarkers: boolean;
+        readonly allowFallback: boolean;
+        readonly maxInlineChars: number;
+    };
+    readonly docling: {
+        readonly enabled: boolean;
+        readonly baseUrl: string;
+        readonly timeoutMs: number;
+    };
+    readonly pandoc: {
+        readonly executable: string;
+        readonly timeoutMs: number;
+    };
+    readonly libreoffice: {
+        readonly executable: string;
+        readonly timeoutMs: number;
+    };
+    readonly typst: {
+        readonly enabled: boolean;
+        readonly executable: string;
+        readonly timeoutMs: number;
+    };
+    readonly markitdown: {
+        readonly enabled: boolean;
+        readonly executable: string;
+        readonly timeoutMs: number;
+    };
+    readonly workers: {
+        readonly renderConcurrency: number;
+        readonly extractionConcurrency: number;
+        readonly ocrConcurrency: number;
+    };
+    readonly retention: {
+        readonly enabled: boolean;
+        readonly maxAgeDays: number;
+        readonly cleanupIntervalHours: number;
+    };
+    readonly limits: {
+        readonly maxInputBytes: number;
+        readonly maxMarkdownChars: number;
+        readonly maxPages: number;
+        readonly maxExtractedImages: number;
+        readonly maxAssetBytes: number;
+        readonly maxResponseBytes: number;
+        readonly maxExtractedMarkdownBytes: number;
+        readonly allowedAssetMimeTypes: readonly string[];
+    };
+}
+/** The canonical resolved configuration; the schema and resolver both use it. */
+export declare const DEFAULT_QA_DOCUMENTS_CONFIG: ResolvedQaDocumentsConfig;
+//# sourceMappingURL=defaults.d.ts.map

package/lib/types/documents/errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Typed failures of the document pipeline.
+ *
+ * Every failure the agent can observe carries a stable machine-readable code
+ * (§24) and the backend that produced it. Backend output is never forwarded
+ * verbatim: {@link sanitizeBackendOutput} strips ANSI escapes, collapses
+ * whitespace, replaces absolute paths with the placeholder the operator can
+ * recognize as "inside the sandbox" and caps the length, so a converter's
+ * stderr cannot leak the deployment's layout or the document's content into a
+ * model request.
+ */
+export declare const DOCUMENT_ERROR_CODES: readonly ["INVALID_INPUT", "UNSUPPORTED_FORMAT", "UNSUPPORTED_CONVERSION", "INPUT_TOO_LARGE", "DOCUMENT_TOO_LARGE", "FILE_NOT_FOUND", "TEMPLATE_NOT_FOUND", "INVALID_TEMPLATE", "INVALID_ASSET", "PATH_NOT_ALLOWED", "ENCRYPTED_DOCUMENT", "MACRO_ENABLED_DOCUMENT", "OCR_FAILED", "EXTRACTION_FAILED", "RENDER_FAILED", "CONVERSION_FAILED", "BACKEND_UNAVAILABLE", "BACKEND_TIMEOUT", "BACKEND_FAILED", "ARTIFACT_WRITE_FAILED"];
+export type DocumentErrorCode = (typeof DOCUMENT_ERROR_CODES)[number];
+export interface DocumentErrorFields {
+    readonly backend?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly retryable?: boolean;
+    readonly cause?: unknown;
+}
+export declare class DocumentError extends Error {
+    readonly code: DocumentErrorCode;
+    readonly retryable: boolean;
+    readonly backend: string | undefined;
+    readonly details: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: DocumentErrorCode, message: string, fields?: DocumentErrorFields);
+    /** The structured form the manifest and the logs carry (§24). */
+    toShape(): {
+        readonly code: DocumentErrorCode;
+        readonly message: string;
+        readonly retryable: boolean;
+        readonly backend?: string;
+        readonly details?: Readonly<Record<string, unknown>>;
+    };
+}
+/**
+ * Make a backend's diagnostic text safe to show: no escapes, no absolute
+ * paths, one line per statement, at most `max` characters.
+ */
+export declare function sanitizeBackendOutput(text: string, max?: number): string;
+/** Wrap any thrown value into a {@link DocumentError} without losing its code. */
+export declare function asDocumentError(error: unknown, fallbackCode: DocumentErrorCode, backend?: string): DocumentError;
+//# sourceMappingURL=errors.d.ts.map

package/lib/types/documents/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The document subsystem of `dsh-qa-surface` (§38).
+ *
+ * Markdown is the canonical source for everything the agent creates, the
+ * backends that turn it into DOCX/PDF (or read it back out of them) live
+ * behind the provider interfaces in `providers/`, and the four semantic tools
+ * in `tools/` are the only surface the model ever sees. Everything else —
+ * artifact bundles, manifests, template resolution, path containment, limits —
+ * exists to make those four tools predictable.
+ *
+ * The public entry point is {@link installDocumentSubsystem}.
+ */
+export { DOCUMENT_ERROR_CODES, DocumentError, asDocumentError, sanitizeBackendOutput, type DocumentErrorCode, type DocumentErrorFields, } from "./errors.js";
+export { DEFAULT_QA_DOCUMENTS_CONFIG, applyDocumentsEnvOverrides, resolveDocumentsConfig, retentionIntervalMs, type QaDocumentsConfig, type ResolvedQaDocumentsConfig, } from "./config.js";
+export type * from "./types.js";
+export { createDocumentRuntime, DocumentRuntime, type DocumentRuntimeOptions, } from "./runtime.js";
+export { createDocumentTools, registerDocumentTools, DOCUMENT_TOOL_NAMES, DOCUMENT_CONVERT_TOOL, DOCUMENT_CREATE_TOOL, DOCUMENT_INSPECT_TOOL, DOCUMENT_TO_MARKDOWN_TOOL, type DocumentToolRegistry, } from "./tools/index.js";
+export { createProviders, type ProviderSeams, type ProviderSet, } from "./providers/registry.js";
+export { documentCapabilities, documentHealth } from "./capabilities.js";
+export { ArtifactStore, sha256Hex, sha256OfFile } from "./artifacts/store.js";
+export { createArtifactId, createUlid, isArtifactId } from "./artifacts/ids.js";
+export { MANIFEST_FILE, MANIFEST_SCHEMA_VERSION, readManifest, writeManifest, } from "./artifacts/manifest.js";
+export { BUILTIN_TEMPLATE_NAME, TEMPLATE_MANIFEST_FILE, loadTemplateRegistry, templateNames, type DocumentTemplate, type TemplateRegistry, } from "./templates/registry.js";
+export { resolveTemplate, type ResolvedTemplate, } from "./templates/resolver.js";
+export { CONVERSION_ROUTES } from "./orchestrator/convert-document.js";
+export { defaultArtifactRoot, resolveDocumentScope, type DocumentScope, type ResolvedDocumentScope, } from "./orchestrator/scope.js";
+export { silentDocumentLogger, type DocumentLogger, } from "./orchestrator/runtime-deps.js";
+export { assertInsideRoot, canonicalizeForContainment, isInsideRoot, resolveInsideRoot, sanitizeFilename, } from "./security/paths.js";
+export { DEFAULT_ASSET_MIME_TYPES, detectFormatByExtension, describeUnsupported, sniffDocument, supportedFormatOf, type SniffedDocument, } from "./security/file-types.js";
+export { applyDirectives } from "./markdown/directives.js";
+export { normalizeExtractedMarkdown } from "./markdown/normalize.js";
+export { parseFrontMatter } from "./markdown/frontmatter.js";
+export { readPdfFacts, readDocxFacts, readDocxMetadata, } from "./inspect/facts.js";
+export { readZipEntries, readZipEntry, readZipEntryByName, } from "./inspect/zip.js";
+import type { Context } from "@deepseek-ai/cordis";
+import { type QaDocumentsConfig } from "./config.js";
+import type { DocumentLogger } from "./orchestrator/runtime-deps.js";
+import type { ProviderSeams } from "./providers/registry.js";
+import { DocumentRuntime } from "./runtime.js";
+import { type DocumentToolRegistry } from "./tools/index.js";
+export interface InstallDocumentSubsystemOptions {
+    readonly config: QaDocumentsConfig;
+    readonly logger: DocumentLogger;
+    /** The host tool registry (`ctx.tools`). */
+    readonly register: DocumentToolRegistry["register"];
+    readonly seams?: ProviderSeams;
+    /** Environment overrides are applied by the caller, which owns the process. */
+    readonly now?: () => Date;
+}
+export interface DocumentSubsystem {
+    readonly runtime: DocumentRuntime;
+    readonly toolNames: readonly string[];
+    dispose(): void;
+}
+/**
+ * Wire the subsystem into a host context: build the runtime, register the four
+ * tools, and schedule the retention sweep when a storage root is pinned.
+ *
+ * `enabled: false` is answered with `undefined` — the caller then leaves both
+ * the tools and the timer absent instead of registering inert definitions.
+ */
+export declare function installDocumentSubsystem(ctx: Context, options: InstallDocumentSubsystemOptions): DocumentSubsystem | undefined;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/documents/inspect/facts.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Document facts read without converting anything (§11).
+ *
+ * `document_inspect` must be cheap and safe: it reads the bytes it was given
+ * and answers what they claim to be. Two tiny readers cover the formats the
+ * pipeline supports — a PDF dictionary scan and an OOXML package scan — which
+ * is what makes inspect useful on a 400-page file that nobody wants to render.
+ */
+import type { DetectedFormat } from "../types.js";
+export interface PdfFacts {
+    readonly pages?: number;
+    readonly encrypted: boolean;
+    readonly metadata: {
+        readonly title?: string;
+        readonly author?: string;
+        readonly createdAt?: string;
+        readonly modifiedAt?: string;
+    };
+    readonly images?: number;
+}
+/**
+ * Read a PDF's page count, encryption flag and document-information entries.
+ * This is a scan, not a parser: it is immune to malformed cross-reference
+ * tables (a broken PDF still answers "how many pages does it claim"), and it
+ * never follows an object stream.
+ */
+export declare function readPdfFacts(buffer: Buffer): PdfFacts;
+export interface DocxFacts {
+    readonly headings?: number;
+    readonly tables?: number;
+    readonly images?: number;
+}
+/** Count document structure from the OOXML package, without rendering it. */
+export declare function readDocxFacts(buffer: Buffer): DocxFacts;
+/** Metadata recorded in `docProps/core.xml`. */
+export declare function readDocxMetadata(buffer: Buffer): {
+    readonly title?: string;
+    readonly author?: string;
+    readonly createdAt?: string;
+    readonly modifiedAt?: string;
+};
+export declare function mediaTypeOfDetected(format: DetectedFormat): string;
+//# sourceMappingURL=facts.d.ts.map

package/lib/types/documents/inspect/zip.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Minimal ZIP reader (central directory + per-entry inflate).
+ *
+ * The document pipeline inspects OOXML containers — `document_inspect` counts
+ * headings and images, `security/file-types.ts` decides DOCX vs macro-enabled
+ * DOCM — and neither may pull a ZIP dependency into the host plugin. Only the
+ * two compression methods OOXML writers actually produce are supported
+ * (stored and deflate); anything else is reported as unreadable instead of
+ * being guessed at.
+ */
+export interface ZipEntry {
+    readonly name: string;
+    readonly compressionMethod: number;
+    readonly compressedSize: number;
+    readonly uncompressedSize: number;
+    readonly localHeaderOffset: number;
+}
+/**
+ * Parse the central directory. Returns `undefined` when the buffer is not a
+ * ZIP archive (or is truncated) — the caller decides whether that is an error.
+ */
+export declare function readZipEntries(buffer: Buffer): ZipEntry[] | undefined;
+export declare function findZipEntry(entries: readonly ZipEntry[], name: string): ZipEntry | undefined;
+/** Decompress one entry, or `undefined` when it is unreadable/oversized. */
+export declare function readZipEntry(buffer: Buffer, entry: ZipEntry): Buffer | undefined;
+/** Convenience: read a named entry from an archive in one call. */
+export declare function readZipEntryByName(buffer: Buffer, name: string): Buffer | undefined;
+//# sourceMappingURL=zip.d.ts.map

package/lib/types/documents/markdown/directives.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Controlled document directives (§36).
+ *
+ * Markdown stays the canonical source, so the few structures Markdown cannot
+ * express — a page break, a callout — are written as fences the orchestrator
+ * rewrites into the target backend's own representation before the renderer
+ * sees the text:
+ *
+ * ```md
+ * :::pagebreak
+ * :::
+ *
+ * :::note
+ * Important information.
+ * :::
+ * ```
+ *
+ * Anything else is refused rather than passed through: an unknown `:::`
+ * directive would otherwise reach pandoc as literal text, and raw markup
+ * (HTML, LaTeX, Typst escapes) is only accepted when a deployment explicitly
+ * opts in with `documents.create.allowRawMarkup`.
+ */
+import type { DocumentWarning } from "../types.js";
+/** Backends whose directive spelling differs. */
+export type DirectiveBackend = "docx" | "typst";
+export interface DirectiveOptions {
+    readonly backend: DirectiveBackend;
+    readonly allowRawMarkup: boolean;
+}
+export interface DirectiveResult {
+    readonly markdown: string;
+    readonly warnings: readonly DocumentWarning[];
+}
+/**
+ * Rewrite directives for one backend. Line-oriented on purpose: a fence that
+ * appears inside a code block is content, not a directive.
+ */
+export declare function applyDirectives(markdown: string, options: DirectiveOptions): DirectiveResult;
+//# sourceMappingURL=directives.d.ts.map

package/lib/types/documents/markdown/frontmatter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Front-matter handling (§35).
+ *
+ * A generated document may carry a leading `---` block with scalar metadata.
+ * Only scalars are read: the block feeds document properties and the manifest,
+ * never a nested configuration surface, so there is nothing here an author
+ * could use to reach a backend option.
+ */
+export interface FrontMatter {
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/** Split leading front matter from the body. Malformed lines are ignored. */
+export declare function parseFrontMatter(markdown: string): FrontMatter;
+//# sourceMappingURL=frontmatter.d.ts.map

package/lib/types/documents/markdown/normalize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Markdown normalization for extracted documents (§16).
+ *
+ * The layer is deliberately conservative: it removes artifacts a converter
+ * reliably produces (platform line endings, non-breaking spaces, page-number
+ * lines, a running head repeated on every page) and never touches meaning.
+ * Guessing missing content is explicitly out of scope, and an LLM pass is not
+ * part of this stage at all — a document is never sent to a model to make its
+ * Markdown nicer.
+ */
+import type { DocumentWarning } from "../types.js";
+export interface NormalizeOptions {
+    /** Drop standalone page-number lines (`12`, `- 12 -`, `Page 12`). */
+    readonly stripPageNumbers?: boolean;
+    /** Drop short lines repeated on three or more pages. */
+    readonly stripRunningHeads?: boolean;
+}
+export interface NormalizeResult {
+    readonly markdown: string;
+    readonly warnings: readonly DocumentWarning[];
+}
+/** Normalize extracted Markdown; returns the text and what was changed. */
+export declare function normalizeExtractedMarkdown(markdown: string, options?: NormalizeOptions): NormalizeResult;
+/** Count Markdown structure for `document_inspect` on Markdown inputs. */
+export declare function markdownStructure(markdown: string): {
+    headings: number;
+    tables: number;
+    images: number;
+};
+//# sourceMappingURL=normalize.d.ts.map

package/lib/types/documents/orchestrator/assets.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Asset preparation and reference auditing (§17.1).
+ *
+ * Assets reach a document two ways: the caller names a file in the workspace,
+ * or it inlines bytes as a data URI. Both are copied into the bundle's
+ * `assets/` directory under a name the pipeline chooses, so the rendered
+ * document never depends on a path outside the artifact, and the Markdown
+ * references are rewritten to match.
+ *
+ * Before a renderer runs, every image reference in the source is accounted
+ * for: a missing local file, a reference that leaves the assets directory, or
+ * a remote URL (which the renderer would fetch from the network) is an error,
+ * not a silent drop.
+ */
+import type { ResolvedQaDocumentsConfig } from "../config.js";
+import type { DocumentAssetInput, DocumentWarning } from "../types.js";
+import { type ResolvedDocumentScope } from "./scope.js";
+export interface PreparedAsset {
+    readonly id: string;
+    /** Name inside the bundle's `assets/` directory. */
+    readonly fileName: string;
+    readonly mediaType: string;
+    readonly bytes: number;
+    /** How the caller referred to this asset, for reference rewriting. */
+    readonly references: readonly string[];
+}
+export interface PreparedAssets {
+    readonly assets: readonly PreparedAsset[];
+    readonly warnings: readonly DocumentWarning[];
+}
+export declare function prepareAssets(assets: readonly DocumentAssetInput[] | undefined, options: {
+    readonly config: ResolvedQaDocumentsConfig;
+    readonly scope: ResolvedDocumentScope;
+    readonly assetsDir: string;
+}): Promise<PreparedAssets>;
+/**
+ * Rewrite the image references that point at a provided asset to the bundle's
+ * own `assets/<name>`, keeping every other reference untouched. Matching is
+ * whole-reference (never a substring) and resolves relative spellings against
+ * the workspace, so an absolute path and a workspace-relative path to the same
+ * file both land on the same asset.
+ */
+export declare function rewriteAssetReferences(markdown: string, assets: readonly PreparedAsset[], options: {
+    readonly roots: readonly string[];
+}): string;
+/**
+ * Verify every image reference in the Markdown before a renderer can act on
+ * it: local files must exist inside the assets directory, and remote URLs are
+ * refused because the renderer would fetch them (§26.5).
+ */
+export declare function auditAssetReferences(markdown: string, options: {
+    readonly assetsDir: string;
+    readonly assets: readonly PreparedAsset[];
+}): Promise<readonly DocumentWarning[]>;
+//# sourceMappingURL=assets.d.ts.map

package/lib/types/documents/orchestrator/convert-document.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `document_convert` orchestration (§10).
+ *
+ * The route table is explicit and closed:
+ *
+ * ```text
+ * MD   → DOCX, PDF
+ * DOCX → PDF, MD
+ * PDF  → MD
+ * ```
+ *
+ * Anything else answers `UNSUPPORTED_CONVERSION` — the pipeline never falls
+ * back to "run some shell pipeline and hope", because a conversion the service
+ * does not model is a conversion it cannot bound, observe or secure.
+ */
+import type { DocumentConvertInput, DocumentConvertResult, DocumentFormat } from "../types.js";
+import { type DocumentScope } from "./scope.js";
+import { type DocumentRuntimeDeps } from "./runtime-deps.js";
+/** Routes this pipeline implements (source → target). */
+export declare const CONVERSION_ROUTES: readonly (readonly [
+    DocumentFormat,
+    DocumentFormat
+])[];
+export declare function convertDocument(deps: DocumentRuntimeDeps, input: DocumentConvertInput, scopeInput: DocumentScope): Promise<DocumentConvertResult>;
+//# sourceMappingURL=convert-document.d.ts.map

package/lib/types/documents/orchestrator/create-document.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `document_create` orchestration (§8, §13, §14, §45).
+ *
+ * Markdown in, DOCX and/or PDF out, with the source, the assets and a manifest
+ * kept beside the results. The orchestration is where the pipeline's promises
+ * are actually kept:
+ *
+ * - the caller picks intent (formats, template name, pdf mode), never a
+ *   command line;
+ * - a failure of the second format does not discard the first — partial
+ *   success is returned with a warning (§45);
+ * - every produced file is fingerprinted and recorded in the manifest.
+ */
+import type { DocumentCreateInput, DocumentCreateResult } from "../types.js";
+import { type DocumentScope } from "./scope.js";
+import { type DocumentRuntimeDeps } from "./runtime-deps.js";
+export declare function createDocument(deps: DocumentRuntimeDeps, input: DocumentCreateInput, scopeInput: DocumentScope): Promise<DocumentCreateResult>;
+//# sourceMappingURL=create-document.d.ts.map

package/lib/types/documents/orchestrator/extract-document.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `document_to_markdown` orchestration (§9, §15, §16).
+ *
+ * The tool returns the extracted Markdown, and the bundle keeps it: the model
+ * may only see a truncated view (a 300-page PDF is not a conversation), while
+ * the artifact always carries the full text with its assets and manifest.
+ */
+import type { DocumentToMarkdownInput, DocumentToMarkdownResult, ExtractionMode, OcrMode } from "../types.js";
+import { type DocumentScope } from "./scope.js";
+import { type DocumentRuntimeDeps } from "./runtime-deps.js";
+export type ExtractionOperation = "document_to_markdown" | "document_convert";
+export interface ExtractToMarkdownParams {
+    readonly file: string;
+    readonly mode?: ExtractionMode;
+    readonly ocr?: OcrMode;
+    readonly ocrLanguages?: readonly string[];
+    readonly extractImages?: boolean;
+    readonly extractTables?: boolean;
+    readonly preservePageMarkers?: boolean;
+    readonly outputFilename?: string;
+}
+export declare function extractToMarkdown(deps: DocumentRuntimeDeps, params: ExtractToMarkdownParams, scopeInput: DocumentScope, operation: ExtractionOperation): Promise<DocumentToMarkdownResult>;
+export declare function toMarkdown(deps: DocumentRuntimeDeps, input: DocumentToMarkdownInput, scope: DocumentScope): Promise<DocumentToMarkdownResult>;
+//# sourceMappingURL=extract-document.d.ts.map

package/lib/types/documents/orchestrator/inspect-document.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `document_inspect` orchestration (§11).
+ *
+ * A read-only pass over one file: what it is, how big it is, what it says
+ * about itself, and what structure it holds. No artifact is created — the
+ * operation answers a question, it does not make a document.
+ */
+import type { DocumentInspectInput, DocumentInspectResult } from "../types.js";
+import { type DocumentScope } from "./scope.js";
+import type { DocumentRuntimeDeps } from "./runtime-deps.js";
+export declare function inspectDocument(deps: DocumentRuntimeDeps, input: DocumentInspectInput, scopeInput: DocumentScope): Promise<DocumentInspectResult>;
+//# sourceMappingURL=inspect-document.d.ts.map

package/lib/types/documents/orchestrator/runtime-deps.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Runtime wiring shared by the four orchestrator operations.
+ *
+ * The runtime owns what must outlive a single call — the backend registry, the
+ * concurrency semaphores and the clock — and each operation reads its
+ * configuration and providers from here, so a test can substitute stub
+ * backends without touching a tool definition.
+ */
+import type { ResolvedQaDocumentsConfig } from "../config.js";
+import type { ProviderSet } from "../providers/registry.js";
+import { type Semaphore } from "../security/limits.js";
+/** The logging surface the subsystem uses; a structural subset of PluginLogger. */
+export interface DocumentLogger {
+    debug(event: string, fields?: Record<string, unknown>): void;
+    info(event: string, fields?: Record<string, unknown>): void;
+    warn(event: string, fields?: Record<string, unknown>): void;
+    error(event: string, fields?: Record<string, unknown>): void;
+}
+/** A logger that drops everything; the default when none is supplied. */
+export declare const silentDocumentLogger: DocumentLogger;
+export interface DocumentRuntimeDeps {
+    readonly config: ResolvedQaDocumentsConfig;
+    readonly providers: ProviderSet;
+    readonly logger: DocumentLogger;
+    readonly now: () => Date;
+    readonly semaphores: {
+        readonly render: Semaphore;
+        readonly extraction: Semaphore;
+        readonly ocr: Semaphore;
+    };
+}
+export declare function createRuntimeDeps(options: {
+    readonly config: ResolvedQaDocumentsConfig;
+    readonly providers: ProviderSet;
+    readonly logger?: DocumentLogger;
+    readonly now?: () => Date;
+}): DocumentRuntimeDeps;
+/** Run `body` with one render slot held, releasing it on every path. */
+export declare function withRenderSlot<T>(deps: DocumentRuntimeDeps, signal: AbortSignal | undefined, body: () => Promise<T>): Promise<T>;
+export declare function withExtractionSlot<T>(deps: DocumentRuntimeDeps, signal: AbortSignal | undefined, body: () => Promise<T>): Promise<T>;
+/** OCR runs behind its own, narrower slot (§27: `ocrConcurrency`). */
+export declare function withOcrSlot<T>(deps: DocumentRuntimeDeps, signal: AbortSignal | undefined, body: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=runtime-deps.d.ts.map