@verbatra/sdk 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,15 +1,191 @@
-import { AnthropicModel, OpenAiModel, GeminiModel, ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { z } from 'zod';
-import { AdapterRegistry } from '@verbatra/format-adapters';
+import Anthropic from '@anthropic-ai/sdk';
+import { Interactions } from '@google/genai';
+import OpenAI from 'openai';
 
+/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
+declare const supportedFormatSchema$1: z.ZodEnum<{
+    "i18next-json": "i18next-json";
+    "vue-i18n-json": "vue-i18n-json";
+    "next-intl-json": "next-intl-json";
+    "ngx-translate-json": "ngx-translate-json";
+    xliff: "xliff";
+    yaml: "yaml";
+    arb: "arb";
+}>;
+/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
+type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
+
+/**
+ * A single, format-neutral translation unit. Placeholders are supplied already
+ * extracted; core never derives them from the value.
+ */
+declare const translationEntrySchema$1: z.ZodObject<{
+    key: z.ZodString;
+    namespace: z.ZodString;
+    value: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    meaning: z.ZodOptional<z.ZodString>;
+    placeholders: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    isPlural: z.ZodBoolean;
+}, z.core.$strip>;
+/** The validated shape of one translation unit; the inferred type of {@link translationEntrySchema}. */
+type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
+
+/**
+ * Result of comparing source placeholders against translated-output placeholders as MULTISETS
+ * (counts matter). Always returned (never thrown) for an ordinary mismatch.
+ */
+interface PlaceholderIntegrityResult {
+    /** True when nothing is missing or extra and order is preserved. */
+    readonly matches: boolean;
+    /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
+    readonly missing: readonly string[];
+    /** Occurrences present in the translation but absent from source, one per surplus occurrence. Sorted. */
+    readonly extra: readonly string[];
+    /** Same multiset present in both, but in a different order. */
+    readonly reordered: boolean;
+}
+
+/** A provider is either a prompt-driven LLM or a dedicated machine-translation API. */
+type ProviderKind = "llm" | "machine-translation";
+/** Target tone for a translation. Maps to formality for machine-translation providers. */
+type Tone = "formal" | "informal" | "neutral";
+/**
+ * Produces the placeholder set of a value for the output integrity check. Supplied
+ * by the caller (the SDK) so it matches the entries' format; ai-providers never
+ * derives placeholders itself.
+ */
+type PlaceholderExtractor = (value: string) => readonly string[];
+/**
+ * A batch translation request. Format- and provider-neutral: it carries no prompt,
+ * model, key, or other provider-specific field. The placeholder extractor is
+ * mandatory (see validateRequest).
+ */
+interface TranslateRequest {
+    /** BCP-47 source locale of the entries (for example, "en"). */
+    readonly sourceLocale: string;
+    /** BCP-47 target locale to translate into (for example, "de"). */
+    readonly targetLocale: string;
+    /** The entries to translate; at least one is required. */
+    readonly entries: readonly TranslationEntry$1[];
+    /** Optional source-term to target-term map applied by glossary-capable providers. */
+    readonly glossary?: Readonly<Record<string, string>>;
+    /** Optional target tone; machine-translation providers map it to formality. */
+    readonly tone?: Tone;
+    /** Mandatory placeholder extractor; the output integrity check runs against it. */
+    readonly extractPlaceholders: PlaceholderExtractor;
+}
+/** Token usage, when the provider reports it. Absent for providers without tokens (DeepL). */
+interface Usage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+/** Result of a batch translation: per-key values and per-key integrity outcomes. */
+interface TranslateResult {
+    /** The translated value for each requested key. */
+    readonly values: ReadonlyMap<string, string>;
+    /** The placeholder-integrity outcome for each key (source vs translated placeholder sets). */
+    readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult>;
+    /** Token usage when the provider reports it; absent for token-less providers. */
+    readonly usage?: Usage;
+}
 /**
- * The provider section of the config: a discriminated union over the provider id,
- * reusing each provider's own exported config schema. There is no key field anywhere
- * in this union. The provider reads its API key from the environment at construction.
+ * The single contract every provider implements. It is narrow enough that a machine-translation API like
+ * DeepL fits it directly, while LLM providers implement it by delegating to {@link runLlmTranslation}.
+ * A new provider attaches by implementing this and registering it in a {@link ProviderRegistry}.
  *
- * This union and the factory table below are co-located on purpose: adding a provider
- * is a single edit here (one union variant plus one table entry), and the mapped-type
- * table makes the two sets provably identical at compile time.
+ * Implementer invariants:
+ * - Translatable strings are UNTRUSTED. They travel only as data to the provider; never splice them into
+ *   instruction text, and never act on instructions a value appears to contain.
+ * - Read the API key ONLY from the environment (inside the SDK client). The request, config, and this
+ *   interface never carry a key.
+ * - Fail with a secret-free {@link ProviderError}: never bind, log, or re-throw raw SDK error text (it can
+ *   carry a key or request headers). Validate the request at the boundary with `validateRequest` so the
+ *   integrity check can never be skipped.
+ *
+ * @example
+ * ```ts
+ * // A machine-translation provider implements translateBatch directly (the DeepL shape).
+ * function createMyMtProvider(client: MyClient): TranslationProvider {
+ *   return {
+ *     id: "my-mt",
+ *     kind: "machine-translation",
+ *     supportsGlossary: false,
+ *     async translateBatch(request) {
+ *       const data = validateRequest(request); // throws INVALID_REQUEST on a bad request
+ *       const texts = data.entries.map((e) => e.value);
+ *       const out = await client.translate(texts, data.targetLocale); // SDK reads MY_API_KEY from env
+ *       // map out -> values, run the integrity check, return { values, integrity }
+ *       return buildResult(data, out, request.extractPlaceholders);
+ *     },
+ *   };
+ * }
+ * ```
+ */
+interface TranslationProvider {
+    /** A stable identifier for this provider (for example, "anthropic", "deepl"). */
+    readonly id: string;
+    /** Whether this provider is a prompt-driven LLM or a dedicated machine-translation API. */
+    readonly kind: ProviderKind;
+    /** Whether this provider applies a configured glossary. */
+    readonly supportsGlossary: boolean;
+    /**
+     * Translate a batch of entries.
+     *
+     * @param request - The provider-neutral batch request (no prompt, model, or key).
+     * @returns The per-key translated values and per-key placeholder-integrity outcomes.
+     * @throws {@link ProviderError}, secret-free, with the code for the failure (the concrete codes are
+     *   the implementation's; see each provider factory).
+     */
+    translateBatch(request: TranslateRequest): Promise<TranslateResult>;
+}
+
+/**
+ * The Anthropic authoring model type, sourced from the SDK's own model union. It is an
+ * open union (known literals plus `string & {}`), so unknown or newly released model IDs
+ * are still accepted. This drives editor completions only; the runtime schema validates.
+ */
+type AnthropicModel = Anthropic.Messages.Model;
+/**
+ * Stable codes for the DeepL graceful-degradation notices, DeepL only. These are returned DATA on a
+ * successful result, NOT thrown:
+ *
+ * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (the free tier does not support it).
+ * - `GLOSSARY_IGNORED`: a supplied generic glossary was not applied.
+ */
+type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED";
+/**
+ * An observable, structured signal that something was gracefully degraded (not an
+ * error). Carries only a stable code and a static message, never a key or content.
+ * Surfaced as result data, never thrown; callers inspect it but need not treat it as a failure.
+ */
+interface ProviderNotice {
+    /** The stable {@link ProviderNoticeCode} for what was degraded. */
+    readonly code: ProviderNoticeCode;
+    /** A static, safe description; never a key or translatable content. */
+    readonly message: string;
+}
+
+/**
+ * The Gemini authoring model type, sourced from the installed SDK's own model union so
+ * verbatra restates no model IDs. It is an open union, so unknown model IDs are still
+ * accepted. Type-only: it informs editor completions and is never validated at runtime,
+ * where the schema stays `z.string().min(1)`.
+ */
+type GeminiModel = Interactions.Model;
+
+/**
+ * The OpenAI authoring model type, sourced from the OpenAI SDK's published chat-model
+ * union. It drives editor completions only; it is never read at runtime, and the
+ * runtime schema stays `z.string().min(1)`.
+ */
+type OpenAiModel = OpenAI.ChatModel;
+
+/**
+ * The provider section of the config: a discriminated union over the provider id, reusing each
+ * provider's own config schema. There is no key field anywhere in this union; the provider reads its
+ * API key from the environment at construction.
  */
 declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodLiteral<"anthropic">;
@@ -38,6 +214,11 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 type ProviderConfig = z.infer<typeof providerConfigSchema>;
 type ProviderId = ProviderConfig["id"];
 
+/**
+ * The verbatra project configuration. It carries no API key (the provider reads its key from the
+ * environment), and unknown top-level keys are rejected so a stray secret cannot hide in it. Validated
+ * with zod at the boundary regardless of where it was loaded from.
+ */
 declare const verbatraConfigSchema: z.ZodObject<{
     sourceLocale: z.ZodString;
     targetLocales: z.ZodArray<z.ZodString>;
@@ -46,6 +227,9 @@ declare const verbatraConfigSchema: z.ZodObject<{
         "vue-i18n-json": "vue-i18n-json";
         "next-intl-json": "next-intl-json";
         "ngx-translate-json": "ngx-translate-json";
+        xliff: "xliff";
+        yaml: "yaml";
+        arb: "arb";
     }>;
     files: z.ZodObject<{
         pattern: z.ZodString;
@@ -86,16 +270,6 @@ declare const verbatraConfigSchema: z.ZodObject<{
 }, z.core.$strict>;
 type VerbatraConfig = z.infer<typeof verbatraConfigSchema>;
 
-/**
- * The closed set of a provider's known model IDs: exactly the string literals its SDK
- * model type ships, with the SDK's own open `string & {}` arm stripped out. Distributing
- * over the union and dropping any arm the wide `string` extends leaves only the literals,
- * so the authoring field offers and ACCEPTS only the selected provider's known models. A
- * foreign or unknown model (for example a Claude model under `id: "gemini"`) is a type
- * error at authoring time. This is a static authoring constraint only; the runtime schema
- * stays `z.string().min(1)` and still accepts any non-empty string, so a brand-new model
- * the installed SDK does not yet list is flagged in the editor but still runs.
- */
 type KnownModels<M extends string> = M extends string ? (string extends M ? never : M) : never;
 type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<ProviderConfig, {
     id: Id;
@@ -108,13 +282,6 @@ type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<Provide
         model: KnownModels<M>;
     };
 } : never : never;
-/**
- * The authoring view of one provider variant, keyed by id. LLM providers (anthropic,
- * openai, gemini) restrict `options.model` to that provider's known model literals; DeepL
- * has no model field and is carried through unchanged. Keying by id (rather than a flat
- * union) lets {@link AuthoringConfigFor} select exactly one variant for a literal id, so
- * the `options.model` site is one provider's literal set and never a multi-provider union.
- */
 type AuthoringProviderVariant = {
     anthropic: AuthoringVariant<"anthropic", AnthropicModel>;
     openai: AuthoringVariant<"openai", OpenAiModel>;
@@ -124,20 +291,10 @@ type AuthoringProviderVariant = {
     }>;
 };
 /**
- * The authoring view of the whole config for a given provider id. It is structurally a
- * {@link VerbatraConfig} whose `provider` is the single authoring variant for `TId`.
- *
- * When `TId` is a single provider literal, `provider` is one concrete variant, so
- * `options.model` is that provider's known model literals alone and not a union across
- * providers. `defineConfig` declares one overload per provider parameterized on this type
- * (`AuthoringConfigFor<"openai">` and so on), so overload resolution picks the variant from
- * the `provider.id` literal. That, together with the closed {@link KnownModels} set, makes a
- * foreign model (for example a Claude model under `id: "gemini"`) a type error and aims to
- * keep editors with weaker discriminated-union narrowing (for example the JetBrains/WebStorm
- * completion engine) offering only the selected provider's models, since each overload's
- * parameter is already a single variant with no nested union to narrow. When `TId` defaults
- * to `ProviderId`, `provider` is the full authoring union. Every value assignable here is
- * assignable to {@link VerbatraConfig}, because a model literal is a subtype of `string`.
+ * The authoring view of the whole config for a provider id: a {@link VerbatraConfig} whose `provider`
+ * is that id's single authoring variant, so `options.model` offers only that provider's models. When
+ * `TId` defaults to `ProviderId`, `provider` is the full authoring union. Every value here is assignable
+ * to {@link VerbatraConfig}, since a model literal is a subtype of `string`.
  */
 type AuthoringConfigFor<TId extends ProviderId = ProviderId> = Omit<VerbatraConfig, "provider"> & {
     provider: AuthoringProviderVariant[TId];
@@ -150,30 +307,16 @@ type AuthoringConfigFor<TId extends ProviderId = ProviderId> = Omit<VerbatraConf
 type AuthoringConfig = AuthoringConfigFor;
 
 /**
- * Identity helper for authoring a code-defined verbatra.config.ts. It returns its
- * argument unchanged; its only purpose is to give the author full type inference and
- * editor autocomplete on the config object.
- *
- * It is declared as one overload per provider id rather than a single generic. Each
- * overload's parameter is the concrete single-provider authoring config
- * ({@link AuthoringConfigFor}), so `provider.options.model` is already that one provider's
- * known model literals, with no union across providers and no generic for an editor to
- * infer. Overload resolution selects the matching overload from the `provider.id` literal,
- * so the editor offers only the selected provider's models and a foreign or unknown model
- * (for example a Claude model under `id: "gemini"`) is a type error. This is deliberately
- * overload-based: a generic whose type parameter is inferred from a nested `provider.id`
- * collapses correctly in tsserver but not in editors with weaker inference (notably the
- * JetBrains/WebStorm completion engine), which then fall back to the full union and offer
- * every provider's models. Concrete per-provider signatures avoid that inference step.
+ * Identity helper for authoring a typed `verbatra.config.ts`. It returns its argument unchanged; its
+ * only purpose is full type inference and editor autocomplete on the config object, including
+ * completion of the selected provider's known model literals.
  *
- * The final overload accepts the full {@link AuthoringConfig} union, so a config whose
- * provider id is not a single literal (for example a value typed as the union) still
- * type-checks.
+ * The model restriction is a static authoring constraint only: `loadConfig` validates `model` as a
+ * non-empty string, so a model the installed provider SDK does not yet list is flagged in the editor
+ * but still runs.
  *
- * The return type is the runtime {@link VerbatraConfig}. The model restriction is a static
- * authoring constraint, not a runtime one: `loadConfig` still validates `model` as
- * `z.string().min(1)`, so a model the installed provider SDK does not yet list is flagged
- * in the editor but still runs.
+ * @param config - The verbatra configuration object.
+ * @returns The same config, typed as {@link VerbatraConfig}.
  */
 declare function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfig;
 declare function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfig;
@@ -190,12 +333,10 @@ interface LoadConfigOptions {
      */
     readonly configOverride?: unknown;
     /**
-     * An explicit config file to load instead of searching. A relative path resolves
-     * against `cwd` (an absolute path is used as given), then cosmiconfig's load() parses
-     * it with the same loaders search uses (.json/.yaml/.ts), and it is zod-validated at
-     * the boundary exactly like a searched file. A missing file is CONFIG_NOT_FOUND; a
-     * present-but-unparseable/invalid file is CONFIG_INVALID. Precedence: configOverride
-     * wins over configPath, which wins over search.
+     * An explicit config file to load instead of searching. A relative path resolves against `cwd`; an
+     * absolute path is used as given. Parsed and zod-validated exactly like a searched file: a missing
+     * file is `CONFIG_NOT_FOUND`, a present but invalid one is `CONFIG_INVALID`. Takes precedence over
+     * search, but `configOverride` takes precedence over it.
      */
     readonly configPath?: string;
 }
@@ -259,14 +400,313 @@ declare class SdkError extends Error {
     constructor(code: SdkErrorCode, message: string);
 }
 
+/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
+declare const supportedFormatSchema: z.ZodEnum<{
+    "i18next-json": "i18next-json";
+    "vue-i18n-json": "vue-i18n-json";
+    "next-intl-json": "next-intl-json";
+    "ngx-translate-json": "ngx-translate-json";
+    xliff: "xliff";
+    yaml: "yaml";
+    arb: "arb";
+}>;
+/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
+type SupportedFormat = z.infer<typeof supportedFormatSchema>;
+
+/**
+ * A single, format-neutral translation unit. Placeholders are supplied already
+ * extracted; core never derives them from the value.
+ */
+declare const translationEntrySchema: z.ZodObject<{
+    key: z.ZodString;
+    namespace: z.ZodString;
+    value: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    meaning: z.ZodOptional<z.ZodString>;
+    placeholders: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    isPlural: z.ZodBoolean;
+}, z.core.$strip>;
+/** The validated shape of one translation unit; the inferred type of {@link translationEntrySchema}. */
+type TranslationEntry = Readonly<z.infer<typeof translationEntrySchema>>;
+/** All translation entries for one locale and namespace, keyed by entry key. */
+interface LocaleResource {
+    /** The locale these entries belong to (for example, "en" or "de"). */
+    readonly locale: string;
+    /** The namespace these entries belong to. */
+    readonly namespace: string;
+    /** The source format the resource came from, for round-trip fidelity. */
+    readonly format: SupportedFormat;
+    /** Entries addressable by key. */
+    readonly entries: ReadonlyMap<string, TranslationEntry>;
+}
+
+/**
+ * The result of reading a file into core's intermediate representation.
+ */
+interface ReadResult {
+    /** The parsed locale resource. */
+    readonly resource: LocaleResource;
+    /** Keys whose values are invalid for the format's message syntax. Empty for non-ICU formats. */
+    readonly invalidIcuKeys: readonly string[];
+}
+/**
+ * The contract every format adapter implements. A new format attaches by implementing this interface
+ * and registering it in an {@link AdapterRegistry}.
+ *
+ * For a JSON-family format, implement via {@link createJsonFileAdapter} rather than from scratch. A
+ * non-JSON format implements this interface directly and first needs its format added to core's
+ * `SupportedFormat`.
+ *
+ * @example
+ * ```ts
+ * const registry = createDefaultRegistry();
+ * const resolution = registry.resolve("locales/en.json", { format: "i18next-json" });
+ * if (resolution.status === "resolved") {
+ *   const { resource } = await resolution.adapter.read("locales/en.json", "en");
+ *   await resolution.adapter.write(resource, "locales/en.json");
+ * }
+ * ```
+ */
+interface FormatAdapter {
+    /** The single format this adapter handles (a `SupportedFormat` from core). */
+    readonly format: SupportedFormat;
+    /**
+     * Detect whether this adapter can handle a file, by path extension and an optional content sample.
+     * Best-effort and side-effect-free; it reads nothing from disk.
+     *
+     * @param filePath - The path of the file under consideration.
+     * @param sample - An optional leading content sample to aid detection.
+     * @returns True if this adapter could handle the file. Several adapters may return true for the same
+     *   file (all JSON adapters claim `.json`); the caller disambiguates by explicit format.
+     */
+    canHandle(filePath: string, sample?: string): boolean;
+    /**
+     * Read a file into a {@link LocaleResource} plus its message-validity result.
+     *
+     * @param filePath - The file to read.
+     * @param locale - The locale to tag the resource with.
+     * @returns The parsed resource and the keys whose values are invalid for the format.
+     * @throws {@link AdapterError} when the content is malformed, oversized, or structurally invalid
+     *   (the implementation names the specific codes). A missing or unopenable path instead rejects with
+     *   the underlying filesystem error.
+     */
+    read(filePath: string, locale: string): Promise<ReadResult>;
+    /**
+     * Write a {@link LocaleResource} back to a file, preserving key order and structure, atomically.
+     *
+     * @param resource - The resource to serialize.
+     * @param filePath - The destination file.
+     * @throws {@link AdapterError} if the resource cannot be represented in the format; rejects with the
+     *   underlying filesystem error on a write failure.
+     */
+    write(resource: LocaleResource, filePath: string): Promise<void>;
+    /**
+     * Extract the format's placeholder tokens from a single value, resolving nothing.
+     *
+     * @param value - The translatable string to scan.
+     * @returns The placeholder tokens found, in document order. Does not throw.
+     */
+    extractPlaceholders(value: string): readonly string[];
+    /**
+     * Validate a single value against the format's message syntax before it is written. Non-ICU formats
+     * (i18next, vue-i18n, ngx-translate) treat every value as valid and return true.
+     *
+     * @param value - The candidate translated value to validate.
+     * @returns True when the value is valid for the format's message syntax. Does not throw; an
+     *   unparseable value returns false.
+     */
+    validateMessage(value: string): boolean;
+}
+
+/** Outcome of resolving an adapter for a file. Structured; never throws. */
+type AdapterResolution = {
+    readonly status: "resolved";
+    readonly adapter: FormatAdapter;
+} | {
+    readonly status: "no-match";
+    readonly filePath: string;
+    readonly triedFormats: readonly SupportedFormat[];
+} | {
+    readonly status: "ambiguous";
+    readonly filePath: string;
+    readonly candidates: readonly SupportedFormat[];
+};
+/** Options for {@link AdapterRegistry.resolve}: select a format explicitly, or aid detection. */
+interface ResolveOptions {
+    /** A content sample to aid detection. */
+    readonly sample?: string;
+    /** Bypass detection and select this format explicitly. */
+    readonly format?: SupportedFormat;
+}
+/**
+ * Holds the registered adapters and resolves one for a file. Open for extension:
+ * adapters attach through register without changing resolution logic.
+ */
+declare class AdapterRegistry {
+    private readonly adapters;
+    /**
+     * Register an adapter.
+     *
+     * @param adapter - The adapter to add.
+     * @returns This registry, for chaining.
+     */
+    register(adapter: FormatAdapter): this;
+    private formats;
+    private resolveByFormat;
+    private resolveByDetection;
+    /**
+     * Resolve the adapter for a file, by explicit format when given, otherwise by detection.
+     *
+     * @param filePath - The file to resolve an adapter for.
+     * @param options - `format` selects explicitly and skips detection; `sample` aids detection.
+     * @returns A structured {@link AdapterResolution}: `resolved`, `no-match`, or `ambiguous`. Never
+     *   throws; an unresolvable file is a status, not an exception.
+     */
+    resolve(filePath: string, options?: ResolveOptions): AdapterResolution;
+}
+
+/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
+type BoundedFileRead = {
+    readonly kind: "ok";
+    readonly content: string;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
+/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
+type BoundedBytesRead = {
+    readonly kind: "ok";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
+/**
+ * The minimal file-system surface the SDK needs. Reads are bounded and writes are atomic. Injectable so
+ * tests stay deterministic; the format adapters do their own file IO and bypass this seam.
+ */
+interface SdkFs {
+    /** Whether a readable file exists at the path. */
+    fileExists(path: string): Promise<boolean>;
+    /**
+     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the handle is
+     * fstat'd and the read never advances past the sized length, so swapping in a larger file cannot
+     * bypass the cap. A missing or unreadable path is "missing"; a file over the cap is "too-large".
+     */
+    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
+    /** Read a file as raw bytes with the same TOCTOU-safe, bounded discipline as {@link readFileBounded}. */
+    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
+    /** Write atomically: a temp file in the same directory, then rename over the target. */
+    writeFile(path: string, data: string): Promise<void>;
+    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
+    writeBytes(path: string, data: Uint8Array): Promise<void>;
+}
+
+/** Per-locale drift status: counts only, no key lists. */
+interface LocaleCheckSummary {
+    /** The target locale this entry reports on. */
+    readonly locale: string;
+    /** Keys present in source but absent from the target. */
+    readonly missing: number;
+    /** Keys whose source changed since the target was last translated. */
+    readonly stale: number;
+    /** Keys whose recorded baseline still matches the source. */
+    readonly upToDate: number;
+    /** True when nothing needs (re)translating for this locale. */
+    readonly inSync: boolean;
+}
+/** The aggregate read-only status across all checked target locales. */
+interface CheckSummary {
+    /** True only when every checked locale is in sync. */
+    readonly inSync: boolean;
+    /** One entry per checked target locale, in config order. */
+    readonly locales: readonly LocaleCheckSummary[];
+}
+/** Input for {@link check}: the validated config and which locales to check. */
+interface CheckInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** Subset of target locales to check; defaults to all configured target locales. */
+    readonly locales?: readonly string[];
+}
+/** Composition seam for {@link check}: inject a registry and a file system for tests. */
+interface CheckDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Report which keys are missing or stale per target locale, without calling a provider, writing any
+ * file, or touching the lock. Each locale is reported as counts only (missing, stale, up-to-date);
+ * a locale is `inSync` when nothing is missing or stale, and the top-level `inSync` is true only when
+ * every checked locale is. Orphaned keys and integrity are not reported, since they concern a write.
+ *
+ * @param input - The validated config and which locales to check.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns The aggregate and per-locale drift status.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
+ *   with the same meanings as in `translate`.
+ */
+declare function check(input: CheckInput, deps?: CheckDeps): Promise<CheckSummary>;
+
+/** Per-locale pending change: the key lists, not counts. */
+interface LocaleDiff {
+    /** The target locale this entry reports on. */
+    readonly locale: string;
+    /** Keys present in source but absent from the target; would be added by a run. */
+    readonly missing: readonly string[];
+    /** Keys whose source changed since last translated; would be re-translated. */
+    readonly changed: readonly string[];
+    /** Keys present in target but absent from source; report-only, never pending. */
+    readonly orphaned: readonly string[];
+    /** True when the locale has missing or changed keys; orphaned keys do not count. */
+    readonly hasPendingChanges: boolean;
+}
+/** The aggregate read-only diff across all checked target locales. */
+interface DiffSummary {
+    /** True when any checked locale has pending changes. */
+    readonly hasPendingChanges: boolean;
+    /** One entry per checked target locale, in config order. */
+    readonly locales: readonly LocaleDiff[];
+}
+/** Input for {@link diff}: the validated config and which locales to diff. */
+interface DiffInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** Subset of target locales to diff; defaults to all configured target locales. */
+    readonly locales?: readonly string[];
+}
+/** Composition seam for {@link diff}: inject a registry and a file system for tests. */
+interface DiffDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Report the exact pending change per target locale as three key lists (missing, changed, orphaned),
+ * without calling a provider, writing any file, or touching the lock. This is the detailed sibling of
+ * {@link check}. A locale's `hasPendingChanges` is driven by missing or changed only; orphaned keys are
+ * reported but do not flip it, since a default `translate` run does not prune. The top-level
+ * `hasPendingChanges` is true when any checked locale has pending changes.
+ *
+ * @param input - The validated config and which locales to diff.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns The aggregate and per-locale pending change.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
+ *   with the same meanings as in `translate`.
+ */
+declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
+
 /** A stable code for an SDK-originated notice (not a provider notice). */
 type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED";
 /**
  * A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
  * so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
- * secret-free message; never a key value or translatable content. The SDK keeps its own codes here so
- * the ai-providers `ProviderNoticeCode` union stays free of SDK concerns (the dependency arrow points
- * sdk -> ai-providers, never the reverse).
+ * secret-free message; never a key value or translatable content.
  */
 interface SdkNotice {
     /** The stable {@link SdkNoticeCode} for what the SDK is reporting. */
@@ -302,10 +742,9 @@ interface LocaleSummary {
     /** Translated keys that failed the placeholder-integrity check and were withheld. */
     readonly integrityMismatches: readonly string[];
     /**
-     * Plural-category keys verbatra SYNTHESIZED this run (for example a Polish `items_few` the source
-     * never supplied), kept distinct from {@link translated} because they were generated from the meaning
-     * of the source plural forms, not translated 1:1 from a source string. Empty unless plural generation
-     * was enabled and acted. In a dry-run this is empty (the provider is not called).
+     * Plural-category keys verbatra synthesized this run (for example a Polish `items_few` the source
+     * never supplied), kept distinct from {@link translated}. Empty unless plural generation was enabled
+     * and acted, and empty in a dry-run.
      */
     readonly generated: readonly string[];
     /**
@@ -336,54 +775,6 @@ interface RunSummary {
     readonly failed: readonly string[];
 }
 
-/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
-type BoundedFileRead = {
-    readonly kind: "ok";
-    readonly content: string;
-} | {
-    readonly kind: "missing";
-} | {
-    readonly kind: "too-large";
-};
-/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
-type BoundedBytesRead = {
-    readonly kind: "ok";
-    readonly bytes: Uint8Array;
-} | {
-    readonly kind: "missing";
-} | {
-    readonly kind: "too-large";
-};
-/**
- * The minimal file-system surface the SDK needs: existence checks, the lock-file read/write,
- * and the untrusted workbook bytes read/write for the export/import flow. Reads are bounded
- * (see {@link readFileBounded} / {@link readBytesBounded}) and writes are atomic. Injectable so
- * tests stay deterministic; the format adapters do their own file IO and are not routed through
- * this seam.
- */
-interface SdkFs {
-    /** Whether a readable file exists at the path. */
-    fileExists(path: string): Promise<boolean>;
-    /**
-     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the
-     * handle is fstat'd and the read never advances past the sized length, so swapping the
-     * path for a larger file after the size check cannot bypass the cap. A missing or
-     * unreadable path is "missing" (first-run); a file over the cap is "too-large".
-     */
-    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
-    /**
-     * Read a file as raw bytes through a single handle, bounded to maxBytes, with the SAME
-     * TOCTOU-safe discipline as {@link readFileBounded}: the handle is fstat'd and the read never
-     * advances past the sized length. Used for the untrusted workbook on import; a file over the
-     * cap is "too-large", a missing path is "missing".
-     */
-    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
-    /** Write atomically: a temp file in the same directory, then rename over the target. */
-    writeFile(path: string, data: string): Promise<void>;
-    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
-    writeBytes(path: string, data: Uint8Array): Promise<void>;
-}
-
 /** Builds the provider from its config. Injectable so tests stay offline. */
 type CreateProvider = (config: ProviderConfig) => TranslationProvider;
 
@@ -497,11 +888,10 @@ interface ExportWorkbookResult {
     }[];
 }
 /**
- * Export the strings needing human translation into a styled `.xlsx` workbook. Reuses the same
- * source read, adapter selection, and lock baseline the translate flow uses, runs `diffResources`
- * per target locale to pick the rows (missing and changed by default; add unchanged with
- * `includeUnchanged`), hands the neutral row model to `@verbatra/exchange`'s `buildWorkbook`, and
- * writes the bytes through the {@link SdkFs} seam. No provider is called and no lock-file is written.
+ * Export the strings needing human translation into a styled `.xlsx` workbook. Each target locale is
+ * diffed against the source and lock baseline to pick the rows (missing and changed by default; add
+ * unchanged with `includeUnchanged`), and the bytes are written to `out`. No provider is called and no
+ * lock-file is written.
  *
  * @param input - The validated config and export options.
  * @param deps - Optional composition seams (registry, file system) for tests.
@@ -528,19 +918,16 @@ interface ImportWorkbookDeps {
     readonly fs?: SdkFs;
 }
 /**
- * Import a filled workbook back into the locale files. Reads the untrusted workbook through the
- * SDK's bounded read, parses it with `@verbatra/exchange`'s `readWorkbook` (which bounds and
- * sanitizes it), then for each target-locale data sheet runs the EXISTING core checks (source-drift
- * via `contentHash`, placeholder integrity via `checkPlaceholders`, ICU via the adapter's
- * `validateMessage`), writes the accepted values through the format adapter, and updates the lock
- * through the existing lock logic. Returns a {@link RunSummary} structurally identical to
- * `translate`'s, so the CLI formatter and exit-code rule are shared with no special case.
+ * Import a filled workbook back into the locale files. Each target-locale data sheet runs the same
+ * source-drift, placeholder, and ICU checks as the translate flow, the accepted values are written
+ * through the format adapter, and the lock is updated. Returns a {@link RunSummary} structurally
+ * identical to `translate`'s.
  *
  * Whole-run failures (unknown format, unreadable/invalid/oversized workbook, corrupt lock) throw a
  * structured {@link SdkError}. A per-sheet failure (a locale not in config, a broken-round-trip key,
  * a write failure) is isolated as that locale's `status: "failed"`, not a throw; per-row rejections
- * are withheld and reported on the locale, exactly as the provider path treats integrity mismatches.
- * `--dry-run` validates and reports without writing any locale or lock file.
+ * are withheld and reported on the locale. Dry-run validates and reports without writing any locale or
+ * lock file.
  *
  * @param input - The validated config, the workbook path, and run options.
  * @param deps - Optional composition seams (registry, file system) for tests.
@@ -549,6 +936,28 @@ interface ImportWorkbookDeps {
  */
 declare function importWorkbook(input: ImportWorkbookInput, deps?: ImportWorkbookDeps): Promise<RunSummary>;
 
+/**
+ * Read-only metadata the CLI `init` scaffold derives its tables from, so the CLI never restates the
+ * provider, env-var, model, or format truth owned by core and ai-providers.
+ */
+declare const scaffoldingMetadata: {
+    /** Provider id -> the environment variable its API key is read from. Owned by ai-providers. */
+    readonly providerEnv: {
+        readonly anthropic: "ANTHROPIC_API_KEY";
+        readonly openai: "OPENAI_API_KEY";
+        readonly gemini: "GEMINI_API_KEY";
+        readonly deepl: "DEEPL_API_KEY";
+    };
+    /** LLM provider id -> a cosmetic default scaffold model. Owned by ai-providers. DeepL has none. */
+    readonly scaffoldModels: {
+        readonly anthropic: "claude-sonnet-4-6";
+        readonly openai: "gpt-5.4-mini";
+        readonly gemini: "gemini-2.5-flash";
+    };
+    /** The closed set of source format ids. Owned by core. */
+    readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb"];
+};
+
 /** A minimal source-change event source. Production wraps chokidar; tests inject a stub. */
 interface Watcher {
     /** Register a listener invoked once per coalesced source-change event. */
@@ -605,16 +1014,11 @@ interface WatchController {
     stop(): Promise<void>;
 }
 /**
- * Start watching the source file and re-run the one-shot translate on each debounced change.
- * Watch adds no translation/diff/lock logic: it watches, debounces, serializes, and invokes the
- * existing translate() unchanged. The state machine is IDLE <-> RUNNING with a single boolean
- * pending-rerun flag (mid-run changes collapse into one immediate follow-up; never two runs at
- * once). A missing source at startup is a hard error; a run that fails after start is reported and
- * watching continues. Returns a controller whose stop() closes the watcher and awaits the in-flight
- * run (the caller wires any signal, e.g. SIGINT, to it).
- *
- * Only the startup source check throws; every run outcome after start is surfaced through `onRun` as a
- * {@link WatchRunResult} (a failed run never rejects the in-flight promise).
+ * Start watching the source file and re-run the one-shot {@link translate} on each debounced change.
+ * Runs are serialized: changes during a run collapse into a single follow-up, so two runs never
+ * overlap. A missing source at startup throws; every run outcome after start is surfaced through
+ * `onRun` as a {@link WatchRunResult} and watching continues. Returns a controller whose `stop()`
+ * closes the watcher and awaits the in-flight run.
  *
  * @param input - The config, optional cwd/debounce, and the `onRun` callback that receives each result.
  * @param deps - Optional composition seams (watcher, run, registry, provider builder, file system) for tests.
@@ -646,4 +1050,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleNotice, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, defineConfig, exportWorkbook, importWorkbook, loadConfig, translate, verbatraConfigSchema, watch };
+export { type CheckDeps, type CheckInput, type CheckSummary, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, scaffoldingMetadata, translate, verbatraConfigSchema, watch };