Design

docgate separates planning from execution so cost and scope are inspectable before work begins. plan() is local-only by contract.

Providers are an extension point rather than a product decision. The current core sends PNG page bytes to a Provider and expects one transcription per page. Built-in adapters cover Mistral OCR, Anthropic Messages, and OpenAI-compatible APIs; CallableProvider keeps local engines and private SDKs first-class.

That narrow contract is intentionally not frozen yet. Managed document APIs, async parsers, local OCR engines, and vision runtimes differ in granularity, execution, output, pricing, limits, and trust properties. The next contract is capability-driven. In particular, Docgate must never label a whole-document API as page-selective or turn provider credits/tokens into a fictional per-page charge merely to make unlike services look uniform.

The central invariant is structural: unreadable and unattempted pages are represented by Unknown, never by an ambiguous empty string. Check result.receipt.complete, not whether result.text is non-empty.

Rasterisation bounds the output pixel count rather than trusting a PDF's declared paper dimensions. Any reduction is returned as a Clamp.