@yadsh/dsh-qa-surface 0.4.0 → 0.6.0

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

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

@@ -0,0 +1,52 @@
+/**
+ * Job scope: where an operation reads from and writes to.
+ *
+ * Artifacts live in the session workspace by default
+ * (`<cwd>/.qa/artifacts/documents/<artifact-id>`), which is what makes a QA
+ * deployment's per-user workspaces isolate document bundles for free (§40).
+ * A deployment may pin `documents.storage.root` to a shared volume instead, in
+ * which case the session workspace stays the only place inputs are read from.
+ * Inputs may additionally come from explicitly configured roots (§26.2).
+ */
+import { ArtifactStore } from "../artifacts/store.js";
+import type { ResolvedQaDocumentsConfig } from "../config.js";
+import { type TemplateRegistry } from "../templates/registry.js";
+/** What the caller (a tool) knows about the session. */
+export interface DocumentScope {
+    readonly workspaceRoot: string;
+    readonly sessionId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ResolvedDocumentScope {
+    readonly workspaceRoot: string;
+    readonly artifactRoot: string;
+    readonly sessionId?: string;
+    readonly signal?: AbortSignal;
+    readonly store: ArtifactStore;
+    readonly templates: TemplateRegistry;
+}
+/** Artifact root of one workspace: configured root, else the workspace itself. */
+export declare function defaultArtifactRoot(config: ResolvedQaDocumentsConfig, workspaceRoot: string): string;
+/**
+ * Template roots to probe, in order. An explicitly configured root is
+ * authoritative; a deployment that configures none gets the two conventional
+ * workspace directories.
+ */
+export declare function templateCandidateRoots(config: ResolvedQaDocumentsConfig, workspaceRoot: string): string[];
+/** Load the first candidate root that carries a registry manifest. */
+export declare function loadScopeTemplates(config: ResolvedQaDocumentsConfig, workspaceRoot: string): Promise<TemplateRegistry>;
+export declare function resolveDocumentScope(config: ResolvedQaDocumentsConfig, scope: DocumentScope): Promise<ResolvedDocumentScope>;
+/** Roots an input file may be read from, most specific first. */
+export declare function allowedInputRoots(config: ResolvedQaDocumentsConfig, scope: ResolvedDocumentScope): string[];
+/**
+ * Resolve a caller-supplied input path. The file must exist inside one of the
+ * allowed roots — traversal, symlinks out of the root and absolute paths to
+ * unrelated directories are all refused (§26.2).
+ */
+export declare function resolveInputPath(config: ResolvedQaDocumentsConfig, scope: ResolvedDocumentScope, requested: string, label: string): Promise<string>;
+/** Read an input file under a byte budget. */
+export declare function readInputBytes(filePath: string, config: ResolvedQaDocumentsConfig, label: string): Promise<Buffer>;
+/** Ensure the artifact root exists and is writable, failing with a clear code. */
+export declare function ensureArtifactRoot(scope: ResolvedDocumentScope): Promise<void>;
+export declare function assertInsideArtifactRoot(scope: ResolvedDocumentScope, target: string, label: string): string;
+//# sourceMappingURL=scope.d.ts.map

package/lib/types/documents/providers/docling.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Docling provider — the default DOCX/PDF → Markdown extractor (§6.1, §15).
+ *
+ * Docling runs as a separate HTTP service (`docling-serve`) rather than inside
+ * the host process: it is the heaviest dependency of the pipeline, it is where
+ * OCR happens, and keeping it across a network boundary is what lets the QA
+ * image stay small (§21, §39).
+ *
+ * Two behaviours are deliberate:
+ *
+ * - images come back inline as base64 data URIs (the only representation that
+ *   survives an HTTP boundary without a second fetch), and the extractor writes
+ *   them out as real files under `assets/`, rewriting references to relative
+ *   paths (§17.2);
+ * - nothing about the response shape is assumed beyond "there is Markdown
+ *   somewhere in it": a deployment upgrades docling-serve independently of
+ *   this plugin, so both the wrapped (`document.md_content`) and flat
+ *   (`md_content`) spellings are read.
+ */
+import type { BackendStatus, DocumentExtractor, DocumentFormat, ExtractInput, ExtractedDocument } from "../types.js";
+export interface DoclingProviderOptions {
+    /** Base URL of docling-serve, e.g. `http://docling:5001`. */
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    /** Cap on the response body the extractor will read. */
+    readonly maxResponseBytes: number;
+    readonly maxImages: number;
+    /** Test seam and proxy hook; defaults to the global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+}
+export declare class DoclingExtractor implements DocumentExtractor {
+    private readonly options;
+    readonly name = "docling";
+    constructor(options: DoclingProviderOptions);
+    supports(_format: DocumentFormat): boolean;
+    private get fetchImpl();
+    health(): Promise<BackendStatus>;
+    extract(input: ExtractInput): Promise<ExtractedDocument>;
+    /**
+     * Write inline images out as files and rewrite the Markdown to reference
+     * them relatively. Images beyond the configured cap are dropped with a
+     * warning rather than silently inflating the artifact (§25).
+     */
+    private materializeAssets;
+}
+interface DoclingPayload {
+    readonly markdown: string;
+    readonly pages?: number;
+    readonly serviceVersion?: string;
+}
+/** Read the Markdown out of a docling-serve response, in either spelling. */
+export declare function readDoclingPayload(payload: unknown, backend: string): DoclingPayload;
+export {};
+//# sourceMappingURL=docling.d.ts.map

package/lib/types/documents/providers/libreoffice.d.ts

@@ -0,0 +1,40 @@
+/**
+ * LibreOffice provider — DOCX → PDF (§6.1, §14.1, §46).
+ *
+ * Two details matter beyond "call the converter":
+ *
+ * - every invocation gets its own `-env:UserInstallation` profile, because
+ *   concurrent headless LibreOffice processes sharing one profile corrupt each
+ *   other's state; the temp profile is removed afterwards on success and on
+ *   failure alike;
+ * - a conversion that produced no file, timed out, or died is reported as a
+ *   failure of this step only. The orchestrator keeps whatever earlier steps
+ *   already produced (§45).
+ */
+import type { ConvertPdfInput, ConvertedDocument, DocumentConverter } from "../types.js";
+export interface LibreOfficeProviderOptions {
+    readonly executable: string;
+    readonly timeoutMs: number;
+    /** Directory the per-job profiles are created under (default: os temp). */
+    readonly profileRoot?: string;
+    /** Test seam: arguments placed before the provider's own argv. */
+    readonly programPrefixArgs?: readonly string[];
+    readonly versionProbe?: () => Promise<string | undefined>;
+}
+export declare class LibreOfficePdfConverter implements DocumentConverter {
+    private readonly options;
+    readonly name = "libreoffice";
+    private cachedVersion;
+    constructor(options: LibreOfficeProviderOptions);
+    supports(source: string, target: string): boolean;
+    version(): Promise<string | undefined>;
+    private probeVersion;
+    convert(input: ConvertPdfInput): Promise<ConvertedDocument>;
+    /**
+     * LibreOffice derives the output name from the input, so the expected path
+     * is a prediction. When it is absent exactly one PDF in the output directory
+     * is accepted; anything else is a failure rather than a guess.
+     */
+    private locateOutput;
+}
+//# sourceMappingURL=libreoffice.d.ts.map

package/lib/types/documents/providers/markitdown.d.ts

@@ -0,0 +1,28 @@
+/**
+ * MarkItDown provider — the optional fast extractor (§6.2, §9).
+ *
+ * Kept behind `documents.markitdown.enabled` (off by default): it is a
+ * convenient fallback when Docling is unreachable and high-fidelity parsing is
+ * not needed, but it is not the extractor a QA report should be built on.
+ */
+import type { BackendStatus, DocumentExtractor, DocumentFormat, ExtractInput, ExtractedDocument } from "../types.js";
+export interface MarkItDownProviderOptions {
+    readonly executable: string;
+    readonly timeoutMs: number;
+    readonly maxStdoutBytes: number;
+    /** Test seam: arguments placed before the provider's own argv. */
+    readonly programPrefixArgs?: readonly string[];
+    readonly versionProbe?: () => Promise<string | undefined>;
+}
+export declare class MarkItDownExtractor implements DocumentExtractor {
+    private readonly options;
+    readonly name = "markitdown";
+    private cachedVersion;
+    constructor(options: MarkItDownProviderOptions);
+    supports(format: DocumentFormat): boolean;
+    version(): Promise<string | undefined>;
+    private probeVersion;
+    health(): Promise<BackendStatus>;
+    extract(input: ExtractInput): Promise<ExtractedDocument>;
+}
+//# sourceMappingURL=markitdown.d.ts.map

package/lib/types/documents/providers/pandoc.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pandoc provider (§6.1, §13, §14.2).
+ *
+ * The command line is assembled here and nowhere else: the agent supplies
+ * content, a template *name* and a handful of enumerated options, and this
+ * module turns them into argv. There is no path through the pipeline by which
+ * a caller can add `--lua-filter`, an arbitrary `--resource-path`, or a
+ * `--pdf-engine-opt` (§26.1).
+ */
+import type { DocxRenderer, PdfRenderer, RenderDocxInput, RenderPdfInput, RenderedArtifact } from "../types.js";
+export interface PandocProviderOptions {
+    /** Executable name or absolute path (`pandoc`, `pandoc.exe`). */
+    readonly executable: string;
+    readonly timeoutMs: number;
+    /** Test seam: arguments placed before the provider's own argv. */
+    readonly programPrefixArgs?: readonly string[];
+    /** Test seam: replacement for `--version` probing. */
+    readonly versionProbe?: () => Promise<string | undefined>;
+}
+/** Pandoc renders Markdown into DOCX, optionally through a reference document. */
+export declare class PandocDocxRenderer implements DocxRenderer {
+    private readonly options;
+    readonly name = "pandoc";
+    private cachedVersion;
+    constructor(options: PandocProviderOptions);
+    version(): Promise<string | undefined>;
+    render(input: RenderDocxInput): Promise<RenderedArtifact>;
+}
+/**
+ * Pandoc-driven PDF renderer. The only engine this pipeline enables is Typst,
+ * so the provider exists for `pdfMode: "typst"` alone (§14.2); the office route
+ * renders DOCX first and converts it with LibreOffice.
+ */
+export declare class PandocTypstPdfRenderer implements PdfRenderer {
+    private readonly options;
+    readonly name = "typst";
+    private cachedVersion;
+    constructor(options: PandocProviderOptions);
+    version(): Promise<string | undefined>;
+    render(input: RenderPdfInput): Promise<RenderedArtifact>;
+}
+//# sourceMappingURL=pandoc.d.ts.map

package/lib/types/documents/providers/process.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Hardened child-process runner for document backends (§26.1, §28, §47).
+ *
+ * Every backend invocation goes through here. The contract mirrors the one the
+ * git tools use, because the threat is the same shape — a document is
+ * untrusted input and the backend is a powerful external program:
+ *
+ * - argv array only, built by the provider, never by the model, no shell;
+ * - an explicit environment allow-list, so ambient secrets and proxies do not
+ *   reach the backend;
+ * - output is byte-capped and the process is killed when the cap or the
+ *   timeout hits; a killed run is reported as `timedOut`/`truncated` rather
+ *   than being confused with a backend that failed on its own;
+ * - the caller's abort signal terminates the child and its descendants.
+ */
+export interface ProcessOptions {
+    readonly cwd?: string;
+    readonly timeoutMs: number;
+    /** Maximum stdout bytes retained; the process is killed beyond this. */
+    readonly maxStdoutBytes: number;
+    /** Maximum stderr bytes retained (collection stops, the process continues). */
+    readonly maxStderrBytes?: number;
+    readonly signal?: AbortSignal;
+    /** Extra environment entries layered over the allow-listed base. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Test seam: arguments between the program and the provider's own argv. */
+    readonly programPrefixArgs?: readonly string[];
+    /** Backend name for error reporting. */
+    readonly backend: string;
+    /** What the invocation is doing, for error messages. */
+    readonly context: string;
+}
+export interface ProcessResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number | null;
+    readonly truncated: boolean;
+    readonly timedOut: boolean;
+}
+/**
+ * Ambient variables a document backend legitimately needs. Everything else —
+ * API keys, proxy settings, cloud credentials — is withheld: a converter
+ * parsing a hostile document should not be able to read the deployment's
+ * secrets out of its own environment (§26.5).
+ */
+export declare function buildProcessEnv(extra?: Readonly<Record<string, string>>, source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function runProcess(program: string, argv: readonly string[], options: ProcessOptions): Promise<ProcessResult>;
+/** Map a finished run that the provider expected to succeed onto an error. */
+export declare function expectProcessOk(result: ProcessResult, options: {
+    backend: string;
+    context: string;
+    fallbackCode: "RENDER_FAILED" | "CONVERSION_FAILED" | "EXTRACTION_FAILED" | "OCR_FAILED";
+}): void;
+//# sourceMappingURL=process.d.ts.map