@yadsh/dsh-qa-surface 0.4.0 → 0.6.0

package/lib/types/client/user-settings/UserSettingsDialog.d.ts

@@ -0,0 +1,43 @@
+import type { QaAccountIdentityField, QaAccountProfile, QaAccountProfileInput, QaAccountStarters, QaAccountStartersInput } from "../../types.js";
+import type { QaBoundSkillApi } from "../types.js";
+import type { QaUserSettingsSections } from "../settings-extensions/index.js";
+/** Sections of the user-facing settings dialog. */
+export type QaSettingsSectionId = "profile" | "starters" | "general" | "skills" | (string & {});
+export interface QaUserSettingsDialogProps {
+    readonly open: boolean;
+    /** Section to show when the dialog opens. */
+    readonly initialSection: QaSettingsSectionId;
+    readonly onClose: () => void;
+    readonly email: string;
+    readonly role: string;
+    readonly chatCount: number;
+    /** Self-service profile editing; absent when the deployment turns it off. */
+    readonly profile?: {
+        readonly profile: QaAccountProfile;
+        readonly fields: readonly QaAccountIdentityField[];
+        readonly instructionsMaxLength: number;
+        readonly onSave: (input: QaAccountProfileInput) => Promise<string | null>;
+    };
+    /** Self-service starter buttons; absent when the deployment turns them off. */
+    readonly starters?: {
+        readonly starters: QaAccountStarters;
+        readonly onSave: (input: QaAccountStartersInput) => Promise<string | null>;
+    };
+    /** Personal skills; absent when the deployment cannot host them. */
+    readonly skills?: QaBoundSkillApi;
+    /** Additive pages contributed by separately shipped QA plugins. */
+    readonly extensions?: QaUserSettingsSections;
+    /** Current account token, passed only to the selected extension page. */
+    readonly token?: string;
+}
+/**
+ * One settings dialog for everything the signed-in user owns: the profile, a
+ * place for personal preferences, and their skills.
+ *
+ * It replaces the separate profile modal rather than sitting beside it — the
+ * section list is the single entry point — and it is deliberately a plain
+ * tablist inside the shared dialog shell: on a narrow screen the same element
+ * becomes a horizontal strip instead of a second navigation screen.
+ */
+export declare function QaUserSettingsDialog(props: QaUserSettingsDialogProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=UserSettingsDialog.d.ts.map

package/lib/types/client/user-settings/copy.d.ts

@@ -0,0 +1,25 @@
+import type { QaSkillDiagnostic } from "../../types.js";
+/**
+ * Audience-facing copy for the settings dialog. The Host sends stable codes
+ * and never Russian prose, so every message a user reads is written here.
+ */
+/** One message per diagnostic code; `detail` carries the offending value. */
+export declare function diagnosticMessage(diagnostic: QaSkillDiagnostic): string;
+/**
+ * Turn one remote refusal into copy. The Host folds domain failures into a
+ * `(reason: <code>)` marker on the wire message; anything else — a transport
+ * fault, an unknown code — reads as the generic failure.
+ */
+export declare function skillFailureCopy(error: unknown): string;
+/** Whether a failure is the optimistic-concurrency refusal. */
+export declare function isSkillConflict(error: unknown): boolean;
+export declare const SKILLS_EMPTY_COPY: {
+    readonly title: "У вас пока нет навыков.";
+    readonly body: "Навык — это набор инструкций, который помогает ассистенту стабильно выполнять повторяющиеся задачи.";
+    readonly action: "Создать первый навык";
+};
+export declare const SKILLS_TOOLS_HINT = "\u0418\u043D\u0441\u0442\u0440\u0443\u043C\u0435\u043D\u0442\u044B, \u043A\u043E\u0442\u043E\u0440\u044B\u0435 \u0438\u0441\u043F\u043E\u043B\u044C\u0437\u0443\u0435\u0442 \u044D\u0442\u043E\u0442 \u043D\u0430\u0432\u044B\u043A. \u041E\u043D\u0438 \u043D\u0435 \u043F\u0440\u0435\u0434\u043E\u0441\u0442\u0430\u0432\u043B\u044F\u044E\u0442 \u0434\u043E\u043F\u043E\u043B\u043D\u0438\u0442\u0435\u043B\u044C\u043D\u044B\u0445 \u0440\u0430\u0437\u0440\u0435\u0448\u0435\u043D\u0438\u0439.";
+export declare const SKILLS_DESCRIPTION_HINT = "\u041A\u0440\u0430\u0442\u043A\u043E \u043E\u043F\u0438\u0448\u0438\u0442\u0435, \u0447\u0442\u043E \u0434\u0435\u043B\u0430\u0435\u0442 \u043D\u0430\u0432\u044B\u043A \u0438 \u0432 \u043A\u0430\u043A\u0438\u0445 \u0441\u0438\u0442\u0443\u0430\u0446\u0438\u044F\u0445 \u0435\u0433\u043E \u0441\u0442\u043E\u0438\u0442 \u0438\u0441\u043F\u043E\u043B\u044C\u0437\u043E\u0432\u0430\u0442\u044C.";
+export declare const SKILLS_NAME_HINT = "\u0421\u0442\u0440\u043E\u0447\u043D\u044B\u0435 \u043B\u0430\u0442\u0438\u043D\u0441\u043A\u0438\u0435 \u0431\u0443\u043A\u0432\u044B, \u0446\u0438\u0444\u0440\u044B \u0438 \u0434\u0435\u0444\u0438\u0441\u044B. \u041D\u0430\u043F\u0440\u0438\u043C\u0435\u0440: jira-investigation.";
+export declare const SKILLS_BEHAVIOUR_HINT = "\u00AB\u0410\u0432\u0442\u043E\u043C\u0430\u0442\u0438\u0447\u0435\u0441\u043A\u0438\u00BB \u0437\u043D\u0430\u0447\u0438\u0442, \u0447\u0442\u043E \u0430\u0441\u0441\u0438\u0441\u0442\u0435\u043D\u0442 \u043C\u043E\u0436\u0435\u0442 \u043F\u0440\u0438\u043C\u0435\u043D\u0438\u0442\u044C \u043D\u0430\u0432\u044B\u043A \u0441\u0430\u043C, \u043A\u043E\u0433\u0434\u0430 \u0437\u0430\u0434\u0430\u0447\u0430 \u0441\u043E\u0432\u043F\u0430\u0434\u0451\u0442 \u0441 \u043E\u043F\u0438\u0441\u0430\u043D\u0438\u0435\u043C. \u0421\u043E\u0434\u0435\u0440\u0436\u0438\u043C\u043E\u0435 \u043D\u0430\u0432\u044B\u043A\u0430 \u043D\u0435 \u0445\u0440\u0430\u043D\u0438\u0442\u0441\u044F \u0432 \u043A\u043E\u043D\u0442\u0435\u043A\u0441\u0442\u0435 \u043F\u043E\u0441\u0442\u043E\u044F\u043D\u043D\u043E.";
+//# sourceMappingURL=copy.d.ts.map

package/lib/types/client/user-settings/draft.d.ts

@@ -0,0 +1,51 @@
+import type { QaSkillDiagnostic, QaSkillDocument, QaSkillDraftInput, QaSkillSummary } from "../../types.js";
+/**
+ * The editor's draft: a plain, mutable-shaped snapshot of one skill, plus the
+ * pure helpers the pages share.
+ *
+ * This module holds no serializer on purpose. The Host owns the file format;
+ * the editor checks the subset of rules it can check by itself — the name
+ * grammar, the required fields, the declared tools — and asks the Host for the
+ * rest: the exact file, the operator's size limit, the preserved frontmatter.
+ * A YAML library's Node build carries `require` calls the browser module
+ * loader cannot answer, so the format's YAML half stays on the Host.
+ */
+export interface QaSkillDraft {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    readonly allowedTools: readonly string[];
+    readonly body: string;
+}
+export declare function emptyDraft(): QaSkillDraft;
+export declare function draftFromDocument(document: QaSkillDocument): QaSkillDraft;
+/** Whether a fresh draft carries anything worth warning about on exit. */
+export declare function draftHasContent(draft: QaSkillDraft): boolean;
+/** Collapse diagnostics that describe the same thing for the same field. */
+export declare function mergeDiagnostics(...groups: readonly (readonly QaSkillDiagnostic[])[]): readonly QaSkillDiagnostic[];
+export declare function draftIsDirty(draft: QaSkillDraft, document: QaSkillDocument): boolean;
+export interface QaSkillDraftDiagnostics {
+    readonly availableTools: readonly string[];
+}
+/**
+ * The rules the editor checks by itself, so typing is answered immediately.
+ * The size limit, the preserved frontmatter and the serialized file are the
+ * Host's business and arrive from it; the Host also re-checks all of this on
+ * every write, so nothing here is the authority.
+ */
+export declare function draftDiagnostics(draft: QaSkillDraft, options: QaSkillDraftDiagnostics): readonly QaSkillDiagnostic[];
+/** Whether the draft is complete enough to send. */
+export declare function draftIsSavable(draft: QaSkillDraft): boolean;
+export declare function draftInput(draft: QaSkillDraft, revision: string | null): QaSkillDraftInput;
+/** The terse line under a catalog row: invocation, command, tool count. */
+export declare function skillMetaLine(skill: QaSkillSummary): string;
+/** Tools the catalog cannot use right now, as the row's warning text. */
+export declare function skillToolWarning(skill: QaSkillSummary): string | null;
+/** Case-insensitive search over the fields the catalog offers. */
+export declare function skillMatchesQuery(skill: QaSkillSummary, query: string): boolean;
+/** Editing one tool name out of a draft, wherever the picker put it. */
+export declare function withToolRemoved(tools: readonly string[], name: string): readonly string[];
+export declare function withToolAdded(tools: readonly string[], name: string): readonly string[];
+//# sourceMappingURL=draft.d.ts.map

package/lib/types/client/user-settings/fields.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+/**
+ * Field primitives for the settings dialog. The plugin's host-facing settings
+ * card owns `qa-card-*`, whose stylesheet is injected only where that card is
+ * mounted; the QA page carries its own `dsh-qa-settings-*` rules instead, so
+ * the dialog looks the same whether or not a loopback operator ever opened
+ * the deployment settings.
+ */
+export interface QaSettingsFieldProps {
+    readonly label: string;
+    /** Secondary line under the control; not part of the field's name. */
+    readonly hint?: string;
+    readonly children: ReactNode;
+}
+export declare function QaSettingsField(props: QaSettingsFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function QaSettingsSection(props: {
+    readonly title: string;
+    readonly aside?: ReactNode;
+    readonly children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function QaSettingsToggle(props: {
+    readonly label: string;
+    readonly checked: boolean;
+    readonly disabled?: boolean;
+    readonly hint?: string;
+    readonly onChange: (checked: boolean) => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function QaSettingsNotice(props: {
+    readonly tone: "info" | "warn" | "error";
+    readonly children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function QaSettingsActions(props: {
+    readonly children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function QaSettingsButton(props: {
+    readonly label: string;
+    readonly tone?: "primary" | "plain" | "danger";
+    readonly type?: "button" | "submit";
+    readonly disabled?: boolean;
+    readonly title?: string;
+    readonly onClick?: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=fields.d.ts.map

package/lib/types/config-resolvers/shared.d.ts

@@ -1,5 +1,12 @@
 /** Trim an optional string; a blank value collapses to null. */
 export declare function optionalText(value: string | null | undefined): string | null;
+/**
+ * Whether a configured directory is absolute. The rule reads a drive-letter
+ * path as absolute on every platform, like `session.cwd` does: a deployment
+ * profile is authored on one machine and may be read on another, so a
+ * Windows-style root is not a mistake to reject on a POSIX host.
+ */
+export declare function isAbsoluteDirectoryPath(value: string): boolean;
 /**
  * Shared numeric guard for operator-tuned limits: the value has to be a safe
  * integer inside [min, max], and every rejection carries the same message.

package/lib/types/config-resolvers/tools.d.ts

@@ -0,0 +1,6 @@
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
+type ToolsSlice = ResolvedQaSurfaceConfig["tools"];
+/** Resolve the QA tool delivery domain: activation trigger, policy, and scope. */
+export declare function resolveTools(input: QaSurfaceConfig): ToolsSlice;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/lib/types/documents/artifacts/ids.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ULID generation for artifact ids (§18).
+ *
+ * `doc_<ULID>` — 48 bits of time followed by 80 bits of randomness, encoded in
+ * Crockford base32. The time prefix keeps a directory listing chronological,
+ * and the randomness keeps ids unguessable without a UUID dependency.
+ */
+/** A fresh ULID for the current millisecond. */
+export declare function createUlid(now?: number): string;
+/** A fresh artifact id: `doc_<ULID>`. */
+export declare function createArtifactId(now?: number): string;
+/** Whether a string is an artifact id this pipeline could have issued. */
+export declare function isArtifactId(value: string): boolean;
+//# sourceMappingURL=ids.d.ts.map

package/lib/types/documents/artifacts/manifest.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Manifest construction and persistence (§19).
+ *
+ * The manifest is the source of truth about an artifact: which operation,
+ * which backends and versions, which template (and its hash), which files came
+ * out, which warnings were raised, and which session/workspace the bundle
+ * belongs to. Logical reproducibility rests on it, because byte-level
+ * reproducibility of DOCX/PDF cannot be promised (§31).
+ */
+import type { BackendInfo, DocumentFileResult, DocumentFormat, DocumentManifest, DocumentWarning } from "../types.js";
+import type { ArtifactStore } from "./store.js";
+export declare const MANIFEST_FILE = "manifest.json";
+export declare const MANIFEST_SCHEMA_VERSION: 1;
+export interface BuildManifestInput {
+    readonly artifactId: string;
+    readonly operation: DocumentManifest["operation"];
+    readonly createdAt: string;
+    readonly input: DocumentManifest["input"];
+    readonly outputs: DocumentManifest["outputs"];
+    readonly template?: string;
+    readonly templateSha256?: string;
+    readonly backends: Readonly<Record<string, BackendInfo>>;
+    readonly warnings: readonly DocumentWarning[];
+    readonly scope: DocumentManifest["scope"];
+}
+export declare function buildManifest(input: BuildManifestInput): DocumentManifest;
+export declare function writeManifest(store: ArtifactStore, artifactId: string, manifest: DocumentManifest): Promise<string>;
+export declare function readManifest(store: ArtifactStore, artifactId: string): Promise<DocumentManifest>;
+/** Project a tool-level file result onto the manifest's output record. */
+export declare function outputRecord(file: DocumentFileResult): DocumentManifest["outputs"][number];
+export declare function formatOfOperation(operation: DocumentManifest["operation"]): DocumentFormat | "unknown";
+//# sourceMappingURL=manifest.d.ts.map

package/lib/types/documents/artifacts/store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Artifact bundle storage (§18, §47).
+ *
+ * One directory per operation:
+ *
+ * ```text
+ * <root>/<artifact-id>/
+ *   manifest.json
+ *   source.md
+ *   input/original.pdf
+ *   assets/
+ *   output.docx
+ *   extracted.md
+ * ```
+ *
+ * Everything the store writes goes through a root-relative path that is
+ * validated first, and every file lands atomically (temp file + rename) so a
+ * crashed host never leaves a half-written artifact that a later read would
+ * trust. Job temp directories live under `<root>/.tmp` and are removed on both
+ * success and failure (§47).
+ */
+export interface FileFingerprint {
+    readonly path: string;
+    readonly size: number;
+    readonly sha256: string;
+}
+export declare function sha256Hex(data: string | Buffer): string;
+export declare function sha256OfFile(filePath: string): Promise<string>;
+export interface ArtifactStoreOptions {
+    /** Directory the bundles live in; created on demand. */
+    readonly root: string;
+}
+export declare class ArtifactStore {
+    readonly root: string;
+    constructor(options: ArtifactStoreOptions);
+    /** Absolute path of a root-relative artifact member, containment checked. */
+    path(relativePath: string): string;
+    artifactDir(artifactId: string): string;
+    /** Prepare a fresh bundle directory and return its id. */
+    create(now?: number): Promise<{
+        artifactId: string;
+        dir: string;
+    }>;
+    ensureDir(relativePath: string): Promise<string>;
+    /** Atomically write a root-relative member. */
+    write(relativePath: string, data: string | Buffer): Promise<FileFingerprint>;
+    read(relativePath: string): Promise<Buffer>;
+    fingerprint(relativePath: string): Promise<FileFingerprint>;
+    exists(relativePath: string): Promise<boolean>;
+    /** Job-scoped temp directory: never an artifact, always removed (§47). */
+    createWorkDir(jobId: string): Promise<string>;
+    removeWorkDir(dir: string): Promise<void>;
+    /** Bundle directories, newest first, with their modification time. */
+    list(): Promise<{
+        artifactId: string;
+        dir: string;
+        modifiedAt: Date;
+    }[]>;
+    /** Retention sweep (§41): drop bundles older than `maxAgeDays`. */
+    cleanup(options: {
+        readonly maxAgeDays: number;
+        readonly now?: Date;
+    }): Promise<{
+        removed: string[];
+    }>;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1,32 @@
+/**
+ * Capability discovery (§43) and backend health (§42).
+ *
+ * Health separates required from optional backends on purpose: a deployment
+ * without Docling cannot extract PDFs, but it still creates documents, so the
+ * subsystem reports `degraded` and names what is missing instead of declaring
+ * itself down. An optional backend that was never enabled reports `disabled`,
+ * which is not a fault.
+ */
+import type { ResolvedQaDocumentsConfig } from "./config.js";
+import { type ProviderSeams, type ProviderSet } from "./providers/registry.js";
+import type { DocumentCapabilities, DocumentHealth } from "./types.js";
+import { type TemplateRegistry } from "./templates/registry.js";
+export interface HealthOptions {
+    readonly config: ResolvedQaDocumentsConfig;
+    readonly providers: ProviderSet;
+    /** Probe the two process-based backends; `false` answers from configuration. */
+    readonly probeProcessBackends?: boolean;
+}
+export declare function documentHealth(options: HealthOptions): Promise<DocumentHealth>;
+export declare function documentCapabilities(options: {
+    readonly config: ResolvedQaDocumentsConfig;
+    readonly providers: ProviderSet;
+    readonly templates: TemplateRegistry;
+}): DocumentCapabilities;
+/** Load the template registry of a workspace for capability reporting. */
+export declare function capabilitiesForRoot(options: {
+    readonly config: ResolvedQaDocumentsConfig;
+    readonly templateRoot: string | undefined;
+    readonly seams?: ProviderSeams;
+}): Promise<DocumentCapabilities>;
+//# sourceMappingURL=capabilities.d.ts.map

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