@yadsh/dsh-qa-surface 0.5.0 → 0.6.1

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

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

@@ -0,0 +1,68 @@
+/**
+ * Backend registry and selection (§22, §23, §14.3, §45).
+ *
+ * Tools never import a concrete provider: they ask the registry for the
+ * renderer, extractor or converter that fits the request, and the registry
+ * decides — from configuration and from what is actually available — which
+ * implementation that is. Swapping Docling for another extractor, or Typst for
+ * another PDF engine, is a change here and nowhere else.
+ */
+import type { ResolvedQaDocumentsConfig } from "../config.js";
+import type { BackendStatus, DocumentConverter, DocumentExtractor, DocumentFormat, ExtractedDocument, ExtractInput, DocxRenderer, PdfMode, PdfRenderer, ExtractionMode } from "../types.js";
+export interface ProviderSeams {
+    /** Substituted for the global `fetch` when talking to docling-serve. */
+    readonly fetchImpl?: typeof fetch;
+    readonly pandoc?: {
+        readonly programPrefixArgs?: readonly string[];
+        readonly versionProbe?: () => Promise<string | undefined>;
+    };
+    readonly libreoffice?: {
+        readonly programPrefixArgs?: readonly string[];
+        readonly versionProbe?: () => Promise<string | undefined>;
+    };
+    readonly markitdown?: {
+        readonly programPrefixArgs?: readonly string[];
+        readonly versionProbe?: () => Promise<string | undefined>;
+    };
+}
+export interface ProviderSet {
+    readonly docx: DocxRenderer;
+    readonly typstPdf: PdfRenderer | undefined;
+    readonly converter: DocumentConverter;
+    readonly docling: DocumentExtractor | undefined;
+    readonly doclingHealth: (() => Promise<BackendStatus>) | undefined;
+    readonly markitdown: DocumentExtractor | undefined;
+    readonly markitdownHealth: (() => Promise<BackendStatus>) | undefined;
+}
+export declare function createProviders(config: ResolvedQaDocumentsConfig, seams?: ProviderSeams): ProviderSet;
+/**
+ * The PDF route (§14.3):
+ *
+ * ```text
+ * DOCX + PDF requested          → office
+ * PDF only, template has Typst  → typst
+ * otherwise                     → office
+ * ```
+ *
+ * A deployment that asked for `typst` without enabling the engine is answered
+ * with `BACKEND_UNAVAILABLE` instead of silently rendering an office PDF in
+ * the wrong layout.
+ */
+export declare function selectPdfMode(options: {
+    readonly requested: PdfMode;
+    readonly formats: readonly ("docx" | "pdf")[];
+    readonly templateHasTypst: boolean;
+    readonly typstEnabled: boolean;
+}): "office" | "typst";
+export interface ExtractorSelection {
+    readonly extractor: DocumentExtractor;
+    /** Extractors to try, in order, when the first one is unreachable. */
+    readonly fallbacks: readonly DocumentExtractor[];
+}
+export declare function selectExtractor(providers: ProviderSet, config: ResolvedQaDocumentsConfig, mode: ExtractionMode, format: DocumentFormat): ExtractorSelection;
+/** Run the selected extractor, falling back only when it is unreachable. */
+export declare function extractWithFallback(selection: ExtractorSelection, input: ExtractInput): Promise<{
+    document: ExtractedDocument;
+    fellBackFrom?: string;
+}>;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * Shared plumbing of the document providers.
+ *
+ * Providers report what they wrote through {@link verifyOutput}: a backend
+ * that exits 0 but leaves no file behind is a failure, and one that leaves an
+ * empty file is a failure too — the caller must never be handed a path that
+ * looks like an artifact and is not.
+ */
+import type { BackendInfo, DocumentWarning } from "../types.js";
+export type ProviderFailureCode = "RENDER_FAILED" | "CONVERSION_FAILED" | "EXTRACTION_FAILED";
+export interface VerifiedOutput {
+    readonly path: string;
+    readonly size: number;
+}
+export declare function verifyOutput(outputPath: string, backend: string, code: ProviderFailureCode): Promise<VerifiedOutput>;
+/** `--metadata=key=value` pairs, sanitized of control characters. */
+export declare function metadataArguments(metadata: Readonly<Record<string, string>> | undefined): string[];
+/** First line of a `--version` run, reduced to the version token. */
+export declare function parseVersionOutput(stdout: string, program: string): string | undefined;
+export declare function backendInfo(provider: string, version?: string): BackendInfo;
+/** Read a text output produced by a backend, with a bounded size. */
+export declare function readTextOutput(filePath: string, backend: string, maxBytes: number): Promise<{
+    text: string;
+    truncated: boolean;
+}>;
+export declare function truncationWarning(backend: string, contentType: string): DocumentWarning;
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1,59 @@
+/**
+ * The runtime facade the tools talk to.
+ *
+ * One instance lives in the plugin and survives across calls, so the backend
+ * registry, the concurrency semaphores and the version caches are shared
+ * instead of rebuilt per request. The four operations are the whole surface:
+ * everything else in this subsystem is an implementation detail behind them.
+ */
+import { type QaDocumentsConfig, type ResolvedQaDocumentsConfig } from "./config.js";
+import { type ProviderSeams, type ProviderSet } from "./providers/registry.js";
+import { type DocumentLogger } from "./orchestrator/runtime-deps.js";
+import { resolveDocumentScope, type DocumentScope } from "./orchestrator/scope.js";
+import type { DocumentCapabilities, DocumentConvertInput, DocumentConvertResult, DocumentCreateInput, DocumentCreateResult, DocumentHealth, DocumentInspectInput, DocumentInspectResult, DocumentToMarkdownInput, DocumentToMarkdownResult } from "./types.js";
+export interface DocumentRuntimeOptions {
+    readonly config: ResolvedQaDocumentsConfig;
+    readonly logger?: DocumentLogger;
+    readonly seams?: ProviderSeams;
+    /** Pre-built registry; tests substitute stub backends here. */
+    readonly providers?: ProviderSet;
+    readonly now?: () => Date;
+}
+export declare class DocumentRuntime {
+    readonly config: ResolvedQaDocumentsConfig;
+    readonly providers: ProviderSet;
+    private readonly deps;
+    private readonly seams;
+    constructor(options: DocumentRuntimeOptions);
+    create(input: DocumentCreateInput, scope: DocumentScope): Promise<DocumentCreateResult>;
+    toMarkdown(input: DocumentToMarkdownInput, scope: DocumentScope): Promise<DocumentToMarkdownResult>;
+    convert(input: DocumentConvertInput, scope: DocumentScope): Promise<DocumentConvertResult>;
+    inspect(input: DocumentInspectInput, scope: DocumentScope): Promise<DocumentInspectResult>;
+    health(options?: {
+        readonly probeProcessBackends?: boolean;
+    }): Promise<DocumentHealth>;
+    capabilities(scope?: DocumentScope): Promise<DocumentCapabilities>;
+    /** Routes this runtime advertises, in documentation order. */
+    routes(): readonly (readonly [string, string])[];
+    /**
+     * Retention sweep (§41). Meaningful only for a pinned storage root: with the
+     * default per-workspace layout the plugin cannot enumerate workspaces, and a
+     * sweep that guessed would delete other projects' artifacts.
+     */
+    cleanup(options?: {
+        readonly now?: Date;
+    }): Promise<{
+        removed: string[];
+    } | undefined>;
+}
+/** Build a runtime from raw (schema-parsed) configuration. */
+export declare function createDocumentRuntime(options: {
+    readonly config: QaDocumentsConfig;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly logger?: DocumentLogger;
+    readonly seams?: ProviderSeams;
+    readonly providers?: ProviderSet;
+    readonly now?: () => Date;
+}): DocumentRuntime;
+export { resolveDocumentScope };
+//# sourceMappingURL=runtime.d.ts.map

package/lib/types/documents/security/file-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * File-type identification and asset MIME policy (§26.3, §26.6, §17.1).
+ *
+ * The extension is a hint, never the authority: PDF is recognized by its
+ * header (after a bounded scan, because a PDF may carry leading junk), OOXML
+ * by its ZIP container plus the parts it holds, and macro-enabled documents by
+ * the presence of a VBA project. Legacy OLE documents (`.doc`, `.xls`, `.ppt`)
+ * are recognized only to be refused with a precise message.
+ */
+import type { DetectedFormat, DocumentFormat } from "../types.js";
+export declare const DOCUMENT_MEDIA_TYPES: Readonly<Record<DocumentFormat, string>>;
+export declare function mediaTypeFor(format: DocumentFormat): string;
+export declare function extensionFor(format: DocumentFormat): string;
+export interface SniffedDocument {
+    readonly format: DetectedFormat;
+    readonly mediaType: string;
+    /** The file is a ZIP container holding a Word processing document. */
+    readonly wordprocessing?: boolean;
+    /** `word/vbaProject.bin` or a macro-enabled content type is present. */
+    readonly macroEnabled?: boolean;
+    /** Container recognized as OOXML but not a supported document flavour. */
+    readonly unsupportedOffice?: boolean;
+}
+export declare function detectFormatByExtension(filename: string): DocumentFormat | undefined;
+/**
+ * Identify a document from its bytes, falling back to the extension only where
+ * bytes are inconclusive (plain text and Markdown are both just text).
+ */
+export declare function sniffDocument(buffer: Buffer, filename?: string): SniffedDocument;
+/** The supported source format behind a sniff result, or `undefined`. */
+export declare function supportedFormatOf(sniffed: SniffedDocument): DocumentFormat | undefined;
+/** Human-facing explanation of a sniff result the pipeline refuses. */
+export declare function describeUnsupported(sniffed: SniffedDocument, filename: string): string;
+export { DEFAULT_ASSET_MIME_TYPES, isAllowedAssetMimeType, mimeTypeForFilename, } from "./mime.js";
+/** Magic-byte MIME detection for the asset types the pipeline accepts. */
+export declare function mimeTypeOfBytes(buffer: Buffer): string | undefined;
+/** A short, sanitized description of the first bytes, for error messages. */
+export declare function describeBytes(buffer: Buffer): string;
+//# sourceMappingURL=file-types.d.ts.map

package/lib/types/documents/security/limits.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resource limits and concurrency control (§26.4, §27).
+ *
+ * Every expensive stage (render, extraction, OCR) runs behind a semaphore so a
+ * burst of documents cannot exhaust the host, and every size/count budget is
+ * checked before the work starts rather than after a backend has already spent
+ * minutes on it.
+ */
+export declare function assertBytesWithinBudget(bytes: number, maxBytes: number, label: string): void;
+export declare function assertCharsWithinBudget(chars: number, maxChars: number, label: string): void;
+export declare function assertCountWithinBudget(count: number, maxCount: number, label: string): void;
+export interface Semaphore {
+    /** Resolve with the release function once a slot is free. */
+    acquire(signal?: AbortSignal): Promise<() => void>;
+    readonly limit: number;
+    /** Slots in use right now (tests and health output). */
+    readonly inUse: number;
+}
+/**
+ * Counting semaphore with FIFO fairness. An aborted waiter leaves the queue
+ * without consuming a slot, so a stopped turn never leaks capacity.
+ */
+export declare function createSemaphore(limit: number): Semaphore;
+//# sourceMappingURL=limits.d.ts.map

package/lib/types/documents/security/mime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MIME policy for document assets (§17.1).
+ *
+ * Kept free of Node builtins on purpose: the QA settings schema reaches this
+ * module from the browser bundle, so anything imported here also has to run in
+ * a page. The byte sniffing stays with the pipeline's file-type module, which
+ * may import whatever it needs.
+ */
+/** Asset MIME types accepted by default. */
+export declare const DEFAULT_ASSET_MIME_TYPES: readonly string[];
+export declare function mimeTypeForFilename(filename: string): string | undefined;
+export declare function isAllowedAssetMimeType(mimeType: string, allowed: readonly string[]): boolean;
+//# sourceMappingURL=mime.d.ts.map

package/lib/types/documents/security/paths.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Path containment and filename hygiene (§26.2, §32).
+ *
+ * Two rules hold everywhere in the pipeline:
+ *
+ * - every path the pipeline touches is resolved against an allowed root and
+ *   the resolution must stay inside it — traversal, absolute escapes and
+ *   `file://` references are refused before anything is opened;
+ * - a caller-supplied filename is a label, never a path: directories are
+ *   dropped, separators and reserved characters collapse to `-`, and the
+ *   extension is the one the operation itself chose.
+ */
+/** Whether `target` is `root` or a descendant of it (no symlink resolution). */
+export declare function isInsideRoot(root: string, target: string): boolean;
+export declare function assertInsideRoot(root: string, target: string, label: string): string;
+/**
+ * Canonicalize a path for containment checks: the existing prefix is resolved
+ * through symlinks, the non-existent remainder is appended unresolved. A
+ * symlink pointing outside the root therefore canonicalizes outside it.
+ */
+export declare function canonicalizeForContainment(input: string): Promise<string>;
+/** Resolve a caller-supplied path against `root`, refusing any escape. */
+export declare function resolveInsideRoot(root: string, requested: string, label: string): Promise<string>;
+/**
+ * Turn a caller-supplied filename into a safe file name (§32).
+ * `../../foo report?.docx` becomes `foo-report.docx`.
+ */
+export declare function sanitizeFilename(requested: string | undefined, fallbackStem: string, extension: string): string;
+/** `file:///...` form required by `-env:UserInstallation` and friends. */
+export declare function toFileUri(target: string): string;
+/**
+ * Assert an asset reference inside Markdown targets the assets directory and
+ * nothing else: no absolute paths, no URLs, no traversal (§17.1).
+ */
+export declare function assertRelativeAssetReference(reference: string): string;
+/** Recursively-size snapshot helper used by the limits guard. */
+export declare function assertNotBlank(value: string, label: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/lib/types/documents/templates/registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Template registry (§12.2).
+ *
+ * A deployment describes its templates in a `manifest.yml` beside the
+ * template files:
+ *
+ * ```yaml
+ * templates:
+ *   default:
+ *     docx: ./docx/default.docx
+ *   qa-report:
+ *     docx: ./docx/qa-report.docx
+ *     typst: ./typst/qa-report
+ * ```
+ *
+ * Every declared path is resolved against the template root and must stay
+ * inside it: a registry file is operator input, but it is read from the
+ * workspace, so it gets the same containment treatment as everything else
+ * (§26.2).
+ */
+import type { DocumentWarning } from "../types.js";
+export declare const TEMPLATE_MANIFEST_FILE = "manifest.yml";
+export interface DocumentTemplate {
+    readonly name: string;
+    /** Absolute path of the reference DOCX, when the template declares one. */
+    readonly docx?: string;
+    /** Absolute path of the Typst template directory, when it declares one. */
+    readonly typst?: string;
+}
+export interface TemplateRegistry {
+    /** Absolute template root, when the workspace provides one. */
+    readonly root?: string;
+    readonly templates: ReadonlyMap<string, DocumentTemplate>;
+    readonly warnings: readonly DocumentWarning[];
+}
+/** The template name that always resolves, with or without a registry. */
+export declare const BUILTIN_TEMPLATE_NAME = "default";
+/** Located registry file inside a candidate root. */
+export declare function findTemplateManifest(root: string): Promise<string | undefined>;
+/**
+ * Load a registry from a template root. A missing root, a missing manifest or
+ * an unreadable document all leave the builtin default in place and report a
+ * warning — a broken template directory must not stop the agent from writing a
+ * plain document, but it must not be silent either.
+ */
+export declare function loadTemplateRegistry(root: string | undefined): Promise<TemplateRegistry>;
+export declare function templateNames(registry: TemplateRegistry): string[];
+/** Load a registry from a candidate root, defaulting to a file-system probe. */
+export declare function loadTemplateRegistryFrom(roots: readonly (string | undefined)[], probe: (candidate: string) => Promise<boolean>): Promise<TemplateRegistry>;
+//# sourceMappingURL=registry.d.ts.map

package/lib/types/documents/templates/resolver.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Template resolution (§12.3).
+ *
+ * ```text
+ * requested template
+ *   ↓ (absent)
+ * project default
+ *   ↓ (absent)
+ * builtin default
+ * ```
+ *
+ * A requested template that does not exist is an error, never a silent
+ * fallback: a report rendered in the wrong corporate layout is worse than a
+ * failed call the operator can read. The builtin `default` name resolves
+ * without a registry entry — it means "the document backend's own defaults".
+ */
+import type { DocumentWarning } from "../types.js";
+import { type DocumentTemplate, type TemplateRegistry } from "./registry.js";
+export interface ResolvedTemplate {
+    readonly name: string;
+    readonly template?: DocumentTemplate;
+    /** How the effective name was chosen. */
+    readonly source: "requested" | "project-default" | "builtin";
+}
+export interface TemplateResolution {
+    readonly resolved: ResolvedTemplate;
+    readonly warnings: readonly DocumentWarning[];
+}
+export declare function resolveTemplate(registry: TemplateRegistry, requested: string | undefined, projectDefault: string): TemplateResolution;
+//# sourceMappingURL=resolver.d.ts.map

package/lib/types/documents/tools/convert.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `document_convert` — one supported format to another (§10, §34).
+ */
+import type { DocumentRuntime } from "../runtime.js";
+export declare const DOCUMENT_CONVERT_TOOL = "document_convert";
+export declare function createDocumentConvertTool(options: {
+    readonly runtime: DocumentRuntime;
+}): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=convert.d.ts.map

package/lib/types/documents/tools/create.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `document_create` — Markdown to DOCX and/or PDF (§8, §34).
+ *
+ * This is the tool the agent reaches for instead of driving pandoc and
+ * LibreOffice itself, which is the whole point of the pipeline: the intent is
+ * "give me this report as a Word file and a PDF", and the service decides how
+ * that happens.
+ */
+import type { DocumentRuntime } from "../runtime.js";
+export declare const DOCUMENT_CREATE_TOOL = "document_create";
+export declare function createDocumentCreateTool(options: {
+    readonly runtime: DocumentRuntime;
+}): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=create.d.ts.map