@verbatra/sdk 0.9.3 → 0.11.0

package/dist/index.d.ts

@@ -17,7 +17,7 @@ import OpenAI from 'openai';
  * (an i18next plural key suffix, a vue-i18n pipe-separated value, or an ICU plural), which the adapter
  * decides and which feeds the content hash.
  */
-declare const translationEntrySchema$1: z.ZodObject<{
+declare const translationEntrySchema$2: z.ZodObject<{
     key: z.ZodString;
     namespace: z.ZodString;
     value: z.ZodString;
@@ -30,14 +30,14 @@ declare const translationEntrySchema$1: z.ZodObject<{
  * The validated shape of one translation unit; the inferred type of {@link translationEntrySchema},
  * made deeply readonly. See that schema for what each field carries.
  */
-type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
+type TranslationEntry$2 = Readonly<z.infer<typeof translationEntrySchema$2>>;
 
 /**
  * Result of comparing source placeholders against translated-output placeholders as MULTISETS
  * (counts matter, so dropping one of two occurrences of the same token is still a miss). Always
  * returned, never thrown: a mismatch is data the caller decides what to do about, not a failure.
  */
-interface PlaceholderIntegrityResult$1 {
+interface PlaceholderIntegrityResult$2 {
     /** True when nothing is missing or extra: the multisets match, regardless of order. */
     readonly matches: boolean;
     /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
@@ -74,7 +74,7 @@ type PlaceholderExtractor = (value: string) => readonly string[];
  * defines one) so it matches the entries' format; ai-providers never derives it itself and never parses
  * a specific format's message syntax.
  */
-type PlaceholderComparator = (source: string, translated: string) => PlaceholderIntegrityResult$1;
+type PlaceholderComparator = (source: string, translated: string) => PlaceholderIntegrityResult$2;
 /**
  * A batch translation request. Format- and provider-neutral: it carries no prompt,
  * model, key, or other provider-specific field. The placeholder extractor is
@@ -86,11 +86,18 @@ interface TranslateRequest {
     /** 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[];
+    readonly entries: readonly TranslationEntry$2[];
     /** Optional source-term to target-term map applied by glossary-capable providers. */
     readonly glossary?: Readonly<Record<string, string>>;
     /** Optional target {@link Tone}; machine-translation providers map it to formality. */
     readonly tone?: Tone;
+    /**
+     * Optional per-key maximum length budget, measured in grapheme clusters. A key present in the map
+     * whose translation comes back longer than its budget is flagged `MAX_LENGTH_EXCEEDED`; a key
+     * absent from the map is never flagged. Advisory only: it never changes what is sent to the
+     * provider and never withholds a value.
+     */
+    readonly maxLength?: ReadonlyMap<string, number>;
     /** Mandatory placeholder extractor; the output integrity check runs against it. */
     readonly extractPlaceholders: PlaceholderExtractor;
     /**
@@ -141,24 +148,65 @@ interface ProviderNotice {
 }
 /**
  * Stable codes for a derived, per-key "needs review" signal. This is verbatra's own computed
- * assessment, never a raw model self-score: four are recomputable from plain source and translated
- * values, and `PROVIDER_DEGRADED` is layered on afterwards from the batch's notices.
+ * assessment, never a raw model self-score: five are recomputable from plain source and translated
+ * values, and `FUZZY_CACHE_REUSE` and `PROVIDER_DEGRADED` are layered on afterwards, the first by
+ * the SDK from where the value came, the second from the batch's notices.
  *
  * - `LENGTH_RATIO_OUTLIER`: the translated value's length is far shorter or longer than the source's.
- *   Only considered once the trimmed source is long enough for the ratio to mean anything.
+ *   Only considered once the trimmed source is long enough for the ratio to mean anything. Relative
+ *   to the source, and measured in UTF-16 code units; contrast `MAX_LENGTH_EXCEEDED`.
+ * - `MAX_LENGTH_EXCEEDED`: the translated value is longer than the absolute budget configured for
+ *   its key. Measured in grapheme clusters (user-perceived characters), on the value exactly as
+ *   written with no trimming, and the comparison is inclusive, so a value of exactly the budget is
+ *   not flagged. A key with no configured budget is never flagged. Advisory only: an over-budget
+ *   value is still written to the locale file and still recorded in the lock file, because a
+ *   correct translation that overruns a layout budget is more useful than no translation at all.
  * - `EQUALS_SOURCE`: the translated value equals the source value once both are trimmed, so a
  *   difference in leading or trailing whitespace alone still counts as equal. Also requires that
  *   the locales differ and that the value contains at least one letter (so a bare symbol or number
  *   is not flagged).
  * - `GLOSSARY_TERM_MISSED`: a configured glossary source term appeared in the source but its target
- *   term did not appear in the translation.
+ *   term did not appear in the translation. Matching is case-insensitive, and the two sides are
+ *   held to deliberately different standards. The source side requires a whole-word occurrence, so
+ *   the term "AI" is not found inside "Airport" and cannot raise an expectation the translator was
+ *   never given; a source term whose edge character belongs to a script written without word
+ *   separators (Han, kana, Thai and similar) has no boundary to anchor to and falls back to
+ *   containment. The target side requires containment only, because a translated term legitimately
+ *   fuses with the text around it: German compounds ("Benutzerkonto"), Korean particles ("계정을")
+ *   and Japanese loanwords all carry the term with no boundary around it, and demanding one there
+ *   would flag correct translations in most languages a glossary is used for.
  * - `INTEGRITY_REORDERED`: the placeholder set matched but landed in a different order.
  * - `PROVIDER_DEGRADED`: the batch this key came from carried a `FORMALITY_DOWNGRADED` or
  *   `GLOSSARY_IGNORED` notice, either of which can silently change wording. A
  *   `PLACEHOLDER_UNSUPPORTED` notice does not raise it, since the affected entries are withheld
  *   rather than degraded.
+ * - `FUZZY_CACHE_REUSE`: the value was not translated for this source text at all. It was reused
+ *   from the translation memory for an earlier, near-identical source that has since been edited,
+ *   so it is a translation of text that is no longer the source text. Similarity is measured in
+ *   characters and meaning is not a function of character distance: a dropped negation, an
+ *   inverted modal or a swapped proper noun are all small edits with large consequences, and no
+ *   threshold separates them from a typo fix. Every such reuse therefore carries this reason, on
+ *   every run, regardless of score.
+ *
+ * This tuple is the single source of truth for the set. {@link ReviewReasonCode} is derived from
+ * it, so build any runtime validator or exhaustive lookup from this value rather than retyping the
+ * members; a hand-copied list silently falls behind the next addition.
+ *
+ * @example
+ * ```ts
+ * import { REVIEW_REASON_CODES } from "@verbatra/sdk";
+ * import { z } from "zod";
+ *
+ * const reasonSchema = z.enum(REVIEW_REASON_CODES);
+ * ```
+ */
+declare const REVIEW_REASON_CODES: readonly ["LENGTH_RATIO_OUTLIER", "MAX_LENGTH_EXCEEDED", "EQUALS_SOURCE", "GLOSSARY_TERM_MISSED", "INTEGRITY_REORDERED", "PROVIDER_DEGRADED", "FUZZY_CACHE_REUSE"];
+/**
+ * One of {@link REVIEW_REASON_CODES}. The union is derived from that tuple rather than written out
+ * again, so a code can only be added in one place and every consumer that builds a runtime schema
+ * or an exhaustive map from the tuple stays in step automatically.
  */
-type ReviewReasonCode = "LENGTH_RATIO_OUTLIER" | "EQUALS_SOURCE" | "GLOSSARY_TERM_MISSED" | "INTEGRITY_REORDERED" | "PROVIDER_DEGRADED";
+type ReviewReasonCode = (typeof REVIEW_REASON_CODES)[number];
 /** A key flagged for human review, carrying every reason code that applies. */
 interface ReviewFlag {
     /** Always "review": the flag exists only for flagged keys, so there is no "ok" member. */
@@ -175,7 +223,7 @@ interface TranslateResult {
      */
     readonly values: ReadonlyMap<string, string>;
     /** The placeholder-integrity outcome for each key (source vs translated placeholder sets). */
-    readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult$1>;
+    readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult$2>;
     /** Token usage when the provider reports it; absent for token-less providers. */
     readonly usage?: Usage;
     /**
@@ -260,16 +308,26 @@ type GeminiModel = "gemini-2.5-flash" | "gemini-2.5-pro" | "gemma-4-26b-a4b-it"
 type OpenAiModel = OpenAI.ChatModel;
 
 /**
- * Zod schema accepting exactly one of the eight source formats verbatra can read and write. Each
+ * Zod schema accepting exactly one of the fourteen source formats verbatra can read and write. Each
  * member names the ecosystem it round-trips, not just a file extension, because several of them share
  * one: `i18next-json` is i18next's nested JSON with its plural key suffixes, `vue-i18n-json` is Vue
  * I18n's JSON with its pipe-separated plural values, `next-intl-json` is next-intl's ICU-message JSON,
- * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining four are `xliff` (the XLIFF
- * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle), and
- * `properties` (Java and Spring `.properties` files).
- *
- * The set is closed: a format outside it cannot be represented, so adding one means adding a member
- * here and an adapter that claims it.
+ * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining ten are `xliff` (the XLIFF
+ * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle),
+ * `properties` (Java and Spring `.properties` files), `apple-strings` (Apple's flat `.strings`
+ * localization format for iOS and macOS), `apple-xcstrings` (Apple's Xcode String Catalog, a single
+ * JSON document holding every locale of a `.xcstrings` catalogue together), `android-xml` (Android's
+ * `res/values/strings.xml` resource format, including `<plurals>` and `translatable="false"` entries),
+ * `gettext-po` (GNU gettext's `.po` and `.pot` catalogs, including `msgctxt` disambiguation and
+ * `msgid_plural`/`msgstr[n]` plural forms keyed by the file's own `Plural-Forms` index count),
+ * `ini` (classic INI configuration files, one level of `[section]` headers over `key=value` lines,
+ * whose entries are addressed as `section.key`), and `resx` (.NET's XML resource format; its `<data>`
+ * elements carrying a `type` or `mimetype` attribute, and its designer metadata names, are preserved
+ * untouched rather than translated).
+ *
+ * The set is closed: adding a built-in format means adding a member here and an adapter that claims
+ * it. A format shipped by a package outside verbatra is named by a `custom:` identifier instead and
+ * never joins this set; see `FormatId`.
  */
 declare const supportedFormatSchema$1: z.ZodEnum<{
     "i18next-json": "i18next-json";
@@ -280,196 +338,1250 @@ declare const supportedFormatSchema$1: z.ZodEnum<{
     yaml: "yaml";
     arb: "arb";
     properties: "properties";
+    "apple-strings": "apple-strings";
+    "apple-xcstrings": "apple-xcstrings";
+    "android-xml": "android-xml";
+    "gettext-po": "gettext-po";
+    ini: "ini";
+    resx: "resx";
 }>;
-/** One of the eight supported source formats; the inferred type of {@link supportedFormatSchema}. */
+/** One of the fourteen supported source formats; the inferred type of {@link supportedFormatSchema}. */
 type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
-
 /**
- * The outcome of a size-bounded text read. A file that is absent or larger than the caller's limit
- * is reported as a state rather than thrown, so a caller can treat "no file yet" as normal and an
- * oversized file as a distinct, actionable condition.
+ * A format identifier claimed by an adapter that ships outside verbatra: the reserved
+ * `custom:` prefix followed by a lowercase, hyphen-separated name, for example
+ * `custom:my-format`.
+ *
+ * No built-in format name contains a colon, so a third-party identifier can never shadow a
+ * built-in one.
  */
-type BoundedFileRead = {
-    /** The file was read in full. */
-    readonly kind: "ok";
-    /** The file's content, decoded as UTF-8. */
-    readonly content: string;
-} | {
-    /** No readable file exists at the path. */
-    readonly kind: "missing";
-} | {
-    /** The file exists but exceeds the requested byte limit, so nothing was read. */
-    readonly kind: "too-large";
-};
+type CustomFormatId$1 = `custom:${string}`;
 /**
- * The outcome of a size-bounded binary read, used for interchange workbooks. Mirrors
- * {@link BoundedFileRead} but yields raw bytes rather than decoded text.
+ * Narrow a format identifier to a third-party one.
+ *
+ * @param format - The identifier to classify.
+ * @returns True when the identifier is a well-formed `custom:` identifier. A built-in format
+ *   name always returns false.
+ *
+ * @example
+ * ```ts
+ * isCustomFormatId("custom:toml"); // true
+ * isCustomFormatId("i18next-json"); // false
+ * ```
  */
-type BoundedBytesRead = {
-    /** The file was read in full. */
-    readonly kind: "ok";
-    /** The file's raw bytes. */
-    readonly bytes: Uint8Array;
-} | {
-    /** No readable file exists at the path. */
-    readonly kind: "missing";
-} | {
-    /** The file exists but exceeds the requested byte limit, so nothing was read. */
-    readonly kind: "too-large";
-};
+declare function isCustomFormatId(format: string): format is CustomFormatId$1;
 /**
- * The file-system port the SDK's own I/O goes through. Supplying your own implementation as a
- * `deps.fs` option redirects that I/O, which is how the SDK's tests avoid touching disk and how an
- * embedding application can back part of a project with something other than a local disk.
+ * Any format verbatra can be asked to handle: one of the built-in {@link SupportedFormat}
+ * members, or a third-party {@link CustomFormatId}.
  *
- * The seam carries every file the SDK touches: the run-status file, the lock-file, the config
- * glossary, workbook and interchange I/O, and the locale files themselves, which the adapters read
- * and write through a port built from this one. The single exception is a caller-supplied
- * `deps.adapterRegistry`: those adapters were constructed by the caller, so their file access is
- * whatever the caller wired into them, and supplying both means the caller owns that wiring.
+ * A built-in name is checked against the closed set at compile time. A `custom:` identifier is
+ * only checked for shape, because the adapter behind it lives outside this package; if no
+ * registered adapter claims it, the run fails with a structured error naming the format.
+ */
+type FormatId$1 = SupportedFormat$1 | CustomFormatId$1;
+
+/**
+ * A single, format-neutral translation unit. Placeholders are supplied already extracted; core never
+ * derives them from the value, so an adapter that reads a file is the one authority on what counts as
+ * a placeholder in that format.
  *
- * Reads are size-bounded by contract so that a hostile or accidentally huge file cannot exhaust
- * memory. Writes are expected to be atomic: the default implementation writes to a temporary file
- * and renames it into place, so a crash mid-write never leaves a half-written file behind.
- * Directory creation is the caller's job, so an implementation whose `writeFile` targets a real
- * directory tree must also implement `mkdir`.
+ * The fields are: `key`, the entry's identifier within its namespace, non-empty and already flattened
+ * to the dotted path an adapter produced; `namespace`, the namespace the entry belongs to, empty when
+ * the format has no namespacing; `value`, the translatable string itself, which is untrusted input and
+ * may be empty; `description` and `meaning`, both optional free-form context that a provider is told to
+ * use only for disambiguation and never to translate or echo back; `placeholders`, the format's
+ * placeholder tokens in document order, used for the output integrity check and to decide which entries
+ * a placeholder-blind provider must withhold; and `isPlural`, whether the entry carries plural forms
+ * (an i18next plural key suffix, a vue-i18n pipe-separated value, or an ICU plural), which the adapter
+ * decides and which feeds the content hash.
  */
-interface SdkFs {
-    /** Reports whether a readable file exists at the path. */
-    fileExists(path: string): Promise<boolean>;
-    /** Reads a file as UTF-8 text, refusing to read more than `maxBytes`. */
-    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
-    /** Reads a file as raw bytes, refusing to read more than `maxBytes`. */
-    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
-    /** Writes UTF-8 text to the path, replacing any existing file atomically. */
-    writeFile(path: string, data: string): Promise<void>;
-    /** Writes raw bytes to the path, replacing any existing file atomically. */
-    writeBytes(path: string, data: Uint8Array): Promise<void>;
+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},
+ * made deeply readonly. See that schema for what each field carries.
+ */
+type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
+
+/**
+ * All translation entries for one locale and namespace, keyed by entry key. This is the neutral
+ * intermediate representation every adapter reads into and writes back out of, so nothing downstream
+ * of an adapter parses a format's own syntax.
+ */
+interface LocaleResource$1 {
+    /** The locale these entries belong to (for example, "en" or "de"). */
+    readonly locale: string;
+    /** The namespace these entries belong to; empty when the format has no namespacing. */
+    readonly namespace: string;
+    /** The source format the resource came from, retained for round-trip fidelity on write. */
+    readonly format: FormatId$1;
+    /** Entries addressable by key, in the order the source file defined them. */
+    readonly entries: ReadonlyMap<string, TranslationEntry$1>;
+}
+
+/** One distinct translated value inside an {@link InconsistencyGroup}, with every key holding it. */
+interface InconsistentTranslation {
     /**
-     * Creates a file only if it does not already exist, returning `false` when it does. This is the
-     * primitive behind the per-locale write lock, so it must be atomic against other processes.
+     * The translated value in its compared form: Unicode NFC, line endings folded to `\n`, and
+     * leading and trailing whitespace trimmed. Internal whitespace and letter case are kept.
      */
-    createExclusive(path: string, data: string): Promise<boolean>;
-    /** Removes the file at the path, succeeding even when it is already absent. */
-    deleteFile(path: string): Promise<void>;
-    /** Creates a directory and any missing parents. Optional; omit it if the backing store has no directories. */
-    mkdir?(path: string): Promise<void>;
+    readonly value: string;
+    /** Every key in this locale holding this value, sorted by UTF-16 code unit. */
+    readonly keys: readonly string[];
+}
+/**
+ * One source string that is translated more than one way within a single target locale. Keys are
+ * grouped only when their source value, description, meaning, plural flag, plural form, and context
+ * all agree, so a string that deliberately carries different disambiguation metadata is never
+ * reported.
+ */
+interface InconsistencyGroup {
+    /** The shared source value in its compared form (see {@link InconsistentTranslation.value}). */
+    readonly source: string;
+    /** The disambiguation context every key in the group shares, when the format has one. */
+    readonly context?: string;
+    /** The description every key in the group shares, when there is one. */
+    readonly description?: string;
+    /** The meaning every key in the group shares, when there is one. */
+    readonly meaning?: string;
+    /** Whether the grouped source entries carry plural forms. */
+    readonly isPlural: boolean;
+    /**
+     * The plural form every key in the group shares (a CLDR category such as `one`, or a format's own
+     * plural index), when the format encodes one per key. Different forms of one key are never grouped.
+     */
+    readonly pluralForm?: string;
+    /** Every distinct translation, at least two, sorted by value in UTF-16 code unit order. */
+    readonly translations: readonly InconsistentTranslation[];
 }
 
 /**
- * The on-disk translation memory, read from and written to `verbatra.cache.json` (see
- * {@link CACHE_FILE_NAME}). A run consults it before calling the provider, so a string that was
- * already translated under the same configuration is reused instead of paid for again.
- *
- * Entries are keyed by configuration fingerprint, then locale, then source-content hash. The
- * fingerprint layer means that changing the provider, model, tone, or glossary does not silently
- * reuse translations produced under the old settings; those entries simply stop matching.
+ * Result of comparing source placeholders against translated-output placeholders as MULTISETS
+ * (counts matter, so dropping one of two occurrences of the same token is still a miss). Always
+ * returned, never thrown: a mismatch is data the caller decides what to do about, not a failure.
  */
-interface TranslationMemory {
-    /** The cache schema version. A file at an unrecognized version is ignored rather than trusted. */
-    readonly version: number;
-    /** Cached values, nested as configuration fingerprint, then locale, then source-content hash. */
-    readonly entries: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>>;
+interface PlaceholderIntegrityResult$1 {
+    /** True when nothing is missing or extra: the multisets match, regardless of order. */
+    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. Never true alongside a mismatch. */
+    readonly reordered: boolean;
 }
 
+declare const SOURCE_FRAMEWORKS: readonly ["i18next"];
 /**
- * The file name of the project's translation memory, resolved against the run's working directory.
- * Commit it to reuse translations across machines and CI runs, or add it to `.gitignore` to treat
- * the cache as purely local. Deleting it is always safe: the next run simply repays for the strings
- * it would have reused.
+ * The translation framework whose call sites a source scan looks for. The set is closed: a
+ * framework is only nameable here once an extractor ships for it, so a configured value that
+ * resolves to nothing cannot exist.
+ *
+ * `i18next` covers the `t(...)`, `$t(...)`, and `<object>.t(...)` shapes, each also through an
+ * optional call (`t?.(...)`) and an explicit type-argument list (`t<string>(...)`), with the key as
+ * the first argument and an optional default as either the second argument or a `defaultValue`
+ * field on the options object. A namespace-qualified key such as `t("common:nav.home")` is
+ * reported as a dynamic call site rather than extracted, because one configuration addresses one
+ * catalog file.
  */
-declare const CACHE_FILE_NAME = "verbatra.cache.json";
+type SourceFramework = (typeof SOURCE_FRAMEWORKS)[number];
 
+/** One application source file, already read, as it is handed to a {@link SourceExtractor}. */
+interface SourceFile {
+    /** The file's absolute path, used only for reporting. */
+    readonly path: string;
+    /** The file's full text. It is untrusted input and is never echoed into a result. */
+    readonly content: string;
+}
+/** One translation call site whose key argument was a static string. */
+interface ExtractedCallSite {
+    /** The key exactly as the call site spelled it. */
+    readonly key: string;
+    /** The default value the call site supplied, if any. Absent when the call named only a key. */
+    readonly defaultValue?: string;
+    /** The one-based line the call site sits on. */
+    readonly line: number;
+}
 /**
- * The zod schema for the `provider` block, discriminated on `id`. Each variant's options are
- * validated strictly, so an option that belongs to a different provider is reported as an error
- * rather than ignored. It is embedded in {@link verbatraConfigSchema} and produces
- * {@link ProviderConfig}.
+ * One translation call site whose key argument could not be resolved statically: a variable, a
+ * member expression, or a template literal carrying an expression. It is reported rather than
+ * guessed at, so no invented key ever reaches a catalog.
  */
-declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    id: z.ZodLiteral<"anthropic">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxTokens: z.ZodNumber;
-        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"openai">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxOutputTokens: z.ZodNumber;
-        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"gemini">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxOutputTokens: z.ZodNumber;
-        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"deepl">;
-    options: z.ZodObject<{
-        glossaryId: z.ZodOptional<z.ZodString>;
-        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"openai-compatible">;
-    options: z.ZodObject<{
-        baseUrl: z.ZodURL;
-        model: z.ZodString;
-        maxOutputTokens: z.ZodNumber;
-        apiKeyEnvVar: z.ZodOptional<z.ZodString>;
-        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>;
-}, z.core.$strip>], "id">;
+interface DynamicCallSite {
+    /** The one-based line the call site sits on. */
+    readonly line: number;
+}
+/** A catalog key a file names statically, wherever it names it. */
+interface ReferencedKeySite {
+    /** The key as the source can reach it. */
+    readonly key: string;
+    /** The one-based line it is named on. */
+    readonly line: number;
+}
 /**
- * The `provider` block of a verbatra config: a discriminated union on `id`, so each provider
- * carries exactly the options it supports and nothing else.
+ * A key argument with a static head and a dynamic rest, such as the template literal `nav.${page}`.
+ */
+interface KeyPrefixSite {
+    /** The static head every key this site can reach starts with. */
+    readonly prefix: string;
+    /** The one-based line the site sits on. */
+    readonly line: number;
+}
+/**
+ * Why a place in the source reaches keys a static reading cannot bound.
+ *
+ * - `dynamic-key-prefix`: a key prefix (a `keyPrefix` option or a `getFixedT` prefix argument) is
+ *   not a static string.
+ * - `trans-without-key`: a `Trans` element carries no static `i18nKey`, so its key is its children.
+ * - `aliased-translate-function`: the translate function is assigned somewhere its calls cannot be
+ *   followed, such as an object property.
+ * - `translate-function-escapes`: a translate function bound from a recognised source appears
+ *   somewhere other than a direct call, its own binding, a local alias, or the `t` attribute of a
+ *   `Trans` or `Translation` element (for example as an argument, a property, an export, or a
+ *   ternary operand), so other code can call it with keys this file never names.
+ * - `unrecognised-translate-source`: a translate source (`useTranslation`, `withTranslation`,
+ *   `getFixedT`, a `Translation` render prop, a member `t`, or a `t` import) is used in a shape the
+ *   scan does not recognise, so the keys and prefix the resulting function uses are unknown.
+ */
+type UnresolvedKeySiteReason = "dynamic-key-prefix" | "trans-without-key" | "aliased-translate-function" | "translate-function-escapes" | "unrecognised-translate-source";
+/** A place whose reachable keys cannot be bounded statically. */
+interface UnresolvedKeySite {
+    /** Why the keys it reaches are unknown. */
+    readonly reason: UnresolvedKeySiteReason;
+    /** The one-based line it sits on. */
+    readonly line: number;
+}
+/** Everything one file tells a caller about which catalog keys it can reach. */
+interface KeyUsage {
+    /** Every static key the file names, including the extracted calls, in line order. */
+    readonly references: readonly ReferencedKeySite[];
+    /** Key arguments with no static part at all. */
+    readonly dynamic: readonly DynamicCallSite[];
+    /** Key arguments with a static head. */
+    readonly prefixes: readonly KeyPrefixSite[];
+    /** Places whose reachable keys cannot be bounded. */
+    readonly unresolved: readonly UnresolvedKeySite[];
+}
+/** Everything one {@link SourceExtractor} found in one file. */
+interface FileExtraction {
+    /** Call sites whose key was a static string. */
+    readonly calls: readonly ExtractedCallSite[];
+    /** Call sites whose key could not be resolved statically. */
+    readonly dynamic: readonly DynamicCallSite[];
+    /**
+     * What the file tells a caller asking which catalog keys the source can reach, beyond the calls
+     * above: static keys named some other way, template keys with a static head, and constructs
+     * whose keys cannot be bounded. Absent for an extractor that does not report it, in which case
+     * the calls and dynamic sites above are all that is known.
+     */
+    readonly usage?: KeyUsage;
+    /**
+     * Whether the file could not be read to its end, so everything above it is partial. An
+     * unterminated block comment or template literal abandons the rest of the file. In a file read as
+     * markup (`.tsx`, `.jsx`, `.js`), so does a JSX element that never closes or is closed by an
+     * enclosing element's tag, and a quoted string in code that runs into the end of its line. The
+     * scan records it as an `unparseable` diagnostic and carries on, rather than reporting a short
+     * result as if it were the whole file.
+     */
+    readonly truncated?: boolean;
+}
+/**
+ * The contract every framework's source extractor implements: given one file's text, report the
+ * translation call sites it contains. One implementation per framework, selected by the configured
+ * `extract.framework`.
  *
- * No variant has a field for an API key. Keys are read from the environment by the provider itself
- * (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPL_API_KEY`), which is what keeps
- * them out of config files and out of version control. The `openai-compatible` variant may name a
- * different environment variable through `apiKeyEnvVar`, but still never holds the key itself.
+ * It is pure: it reads no file, makes no network call, and holds no state between files. Supplying
+ * your own as `deps.createExtractor` is how you teach `extract` a call shape verbatra does not
+ * ship yet.
  */
-type ProviderConfig = z.infer<typeof providerConfigSchema>;
+interface SourceExtractor {
+    /** The framework whose call shapes this extractor knows. */
+    readonly framework: SourceFramework;
+    /** The file extensions this extractor can read, each including its leading dot. */
+    readonly extensions: readonly string[];
+    /**
+     * Find every translation call site in one file.
+     *
+     * @param file - The file's path and full text.
+     * @returns The static and dynamic call sites found, in document order.
+     */
+    extract(file: SourceFile): FileExtraction;
+}
+
+/** Where something was found: a source file and a line inside it. Never a file's contents. */
+interface SourceLocation {
+    /** The source file, relative to the run's working directory, with forward slashes. */
+    readonly file: string;
+    /** The one-based line number. */
+    readonly line: number;
+}
 /**
- * The identifier of a supported translation provider: `anthropic`, `openai`, `gemini`, `deepl`, or
- * `openai-compatible`. The last one targets a local or self-hosted server that speaks the OpenAI
- * chat-completions API.
+ * One key found at two or more call sites that disagree on its default value. Neither value is
+ * written: resolving it last-write-wins would make the catalog depend on directory traversal order,
+ * so the disagreement is reported for a person to settle at the call sites.
  */
-type ProviderId = ProviderConfig["id"];
+interface KeyConflict {
+    /** The key the call sites disagree about. */
+    readonly key: string;
+    /** Every distinct default value found, in the order the scan met them. */
+    readonly values: readonly string[];
+    /** Where each of those values was found, index-aligned with `values`. */
+    readonly locations: readonly SourceLocation[];
+}
+type ScanDiagnosticReason = "unreadable" | "too-large" | "unparseable" | "unreadable-directory";
+/** One file or directory the scan could not read, reported as data so one bad file never aborts a run. */
+interface ScanDiagnostic {
+    /** The file or directory, relative to the run's working directory, with forward slashes. */
+    readonly file: string;
+    /** Why it was skipped. */
+    readonly reason: ScanDiagnosticReason;
+}
 
 /**
- * The zod schema every verbatra config is validated against. {@link loadConfig} applies it, so most
- * consumers never call it directly; reach for it when you build a config programmatically and want
- * to validate it before handing it to {@link translate}, or when you surface config errors in your
- * own tooling.
- *
- * The object is strict, so an unrecognized key is an error rather than being silently ignored: a
- * typo in a config file is reported instead of quietly doing nothing. The one exception is the
- * optional `$schema` key, accepted so a JSON or YAML config can point an editor at the JSON Schema
- * document the package ships as `@verbatra/sdk/config-schema.json`.
- *
- * Beyond the per-field checks, two whole-config rules are enforced: `targetLocales` must not
- * contain the source locale, and it must not contain two locales that differ only in case (they
- * would collide on a case-insensitive file system). The `{locale}` token requirement is a
- * per-field check on `files.pattern`.
+ * One hardcoded string literal that reads as user-facing text and never went through a translation
+ * call. It names where the literal sits and a bounded excerpt of it, never the surrounding source.
  */
-declare const verbatraConfigSchema: z.ZodObject<{
-    $schema: z.ZodOptional<z.ZodString>;
-    sourceLocale: z.ZodString;
-    targetLocales: z.ZodArray<z.ZodString>;
-    format: 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";
+interface LiteralFinding {
+    /** The source file, relative to the run's working directory, with forward slashes. */
+    readonly file: string;
+    /** The one-based line the literal starts on. */
+    readonly line: number;
+    /** The one-based column the literal starts at: its opening quote, or its first character of JSX text. */
+    readonly column: number;
+    /**
+     * The literal's text with whitespace collapsed, cut to at most 80 characters. In JSX text and a
+     * quoted JSX attribute value, character references such as `&amp;` are decoded.
+     */
+    readonly text: string;
+    /** Whether `text` was cut short. A cut excerpt ends in `...`. */
+    readonly truncated: boolean;
+}
+/**
+ * Why a literal that would have been reported was held back.
+ *
+ * - `directive`: a `verbatra-ignore-next-line` comment above it, or a `verbatra-ignore-line`
+ *   comment on the same line. A next-line directive targets the next line that holds code, skipping
+ *   blank and comment-only lines, and covers every literal that starts on that line plus every
+ *   attribute of a JSX opening tag that starts there, even when the tag spans several lines. Text and
+ *   nested elements on later lines are not covered.
+ * - `ignore-list`: its text is listed in `extract.literals.ignore`.
+ */
+type LiteralSuppressionReason = "directive" | "ignore-list";
+/** A literal the scan found and did not report, kept so a suppression is visible rather than silent. */
+interface SuppressedLiteral extends LiteralFinding {
+    /** Which suppression mechanism held it back. */
+    readonly reason: LiteralSuppressionReason;
+}
+/** Everything one untranslated-literal scan found across a project's source. */
+interface LiteralScan {
+    /** How many source files were read and scanned. */
+    readonly scannedFiles: number;
+    /** Literals that look user-facing and were not suppressed, in file then document order. */
+    readonly findings: readonly LiteralFinding[];
+    /** Literals that were found but suppressed, each with the reason. */
+    readonly suppressed: readonly SuppressedLiteral[];
+    /**
+     * Files and directories the scan could not read to the end. A file listed here was not fully
+     * checked, so a scan with any diagnostic is never a clean one.
+     */
+    readonly diagnostics: readonly ScanDiagnostic[];
+}
+
+/**
+ * Zod schema accepting exactly one of the fourteen source formats verbatra can read and write. Each
+ * member names the ecosystem it round-trips, not just a file extension, because several of them share
+ * one: `i18next-json` is i18next's nested JSON with its plural key suffixes, `vue-i18n-json` is Vue
+ * I18n's JSON with its pipe-separated plural values, `next-intl-json` is next-intl's ICU-message JSON,
+ * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining ten are `xliff` (the XLIFF
+ * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle),
+ * `properties` (Java and Spring `.properties` files), `apple-strings` (Apple's flat `.strings`
+ * localization format for iOS and macOS), `apple-xcstrings` (Apple's Xcode String Catalog, a single
+ * JSON document holding every locale of a `.xcstrings` catalogue together), `android-xml` (Android's
+ * `res/values/strings.xml` resource format, including `<plurals>` and `translatable="false"` entries),
+ * `gettext-po` (GNU gettext's `.po` and `.pot` catalogs, including `msgctxt` disambiguation and
+ * `msgid_plural`/`msgstr[n]` plural forms keyed by the file's own `Plural-Forms` index count),
+ * `ini` (classic INI configuration files, one level of `[section]` headers over `key=value` lines,
+ * whose entries are addressed as `section.key`), and `resx` (.NET's XML resource format; its `<data>`
+ * elements carrying a `type` or `mimetype` attribute, and its designer metadata names, are preserved
+ * untouched rather than translated).
+ *
+ * The set is closed: adding a built-in format means adding a member here and an adapter that claims
+ * it. A format shipped by a package outside verbatra is named by a `custom:` identifier instead and
+ * never joins this set; see `FormatId`.
+ */
+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";
+    properties: "properties";
+    "apple-strings": "apple-strings";
+    "apple-xcstrings": "apple-xcstrings";
+    "android-xml": "android-xml";
+    "gettext-po": "gettext-po";
+    ini: "ini";
+    resx: "resx";
+}>;
+/** One of the fourteen supported source formats; the inferred type of {@link supportedFormatSchema}. */
+type SupportedFormat = z.infer<typeof supportedFormatSchema>;
+/**
+ * A format identifier claimed by an adapter that ships outside verbatra: the reserved
+ * `custom:` prefix followed by a lowercase, hyphen-separated name, for example
+ * `custom:my-format`.
+ *
+ * No built-in format name contains a colon, so a third-party identifier can never shadow a
+ * built-in one.
+ */
+type CustomFormatId = `custom:${string}`;
+/**
+ * Any format verbatra can be asked to handle: one of the built-in {@link SupportedFormat}
+ * members, or a third-party {@link CustomFormatId}.
+ *
+ * A built-in name is checked against the closed set at compile time. A `custom:` identifier is
+ * only checked for shape, because the adapter behind it lives outside this package; if no
+ * registered adapter claims it, the run fails with a structured error naming the format.
+ */
+type FormatId = SupportedFormat | CustomFormatId;
+
+/**
+ * A single, format-neutral translation unit. Placeholders are supplied already extracted; core never
+ * derives them from the value, so an adapter that reads a file is the one authority on what counts as
+ * a placeholder in that format.
+ *
+ * The fields are: `key`, the entry's identifier within its namespace, non-empty and already flattened
+ * to the dotted path an adapter produced; `namespace`, the namespace the entry belongs to, empty when
+ * the format has no namespacing; `value`, the translatable string itself, which is untrusted input and
+ * may be empty; `description` and `meaning`, both optional free-form context that a provider is told to
+ * use only for disambiguation and never to translate or echo back; `placeholders`, the format's
+ * placeholder tokens in document order, used for the output integrity check and to decide which entries
+ * a placeholder-blind provider must withhold; and `isPlural`, whether the entry carries plural forms
+ * (an i18next plural key suffix, a vue-i18n pipe-separated value, or an ICU plural), which the adapter
+ * decides and which feeds the content hash.
+ */
+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},
+ * made deeply readonly. See that schema for what each field carries.
+ */
+type TranslationEntry = Readonly<z.infer<typeof translationEntrySchema>>;
+
+/**
+ * All translation entries for one locale and namespace, keyed by entry key. This is the neutral
+ * intermediate representation every adapter reads into and writes back out of, so nothing downstream
+ * of an adapter parses a format's own syntax.
+ */
+interface LocaleResource {
+    /** The locale these entries belong to (for example, "en" or "de"). */
+    readonly locale: string;
+    /** The namespace these entries belong to; empty when the format has no namespacing. */
+    readonly namespace: string;
+    /** The source format the resource came from, retained for round-trip fidelity on write. */
+    readonly format: FormatId;
+    /** Entries addressable by key, in the order the source file defined them. */
+    readonly entries: ReadonlyMap<string, TranslationEntry>;
+}
+
+/**
+ * Result of comparing source placeholders against translated-output placeholders as MULTISETS
+ * (counts matter, so dropping one of two occurrences of the same token is still a miss). Always
+ * returned, never thrown: a mismatch is data the caller decides what to do about, not a failure.
+ */
+interface PlaceholderIntegrityResult {
+    /** True when nothing is missing or extra: the multisets match, regardless of order. */
+    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. Never true alongside a mismatch. */
+    readonly reordered: boolean;
+}
+
+/**
+ * The result of reading a file into core's intermediate representation. The two diagnostic lists are
+ * reported as data rather than thrown, so one bad leaf never fails a whole read.
+ */
+interface ReadResult {
+    /** The parsed locale resource. */
+    readonly resource: LocaleResource;
+    /**
+     * Keys whose values are invalid for the format's message syntax. Empty for a format with no
+     * message-syntax check, which treats every value as valid.
+     */
+    readonly invalidIcuKeys: readonly string[];
+    /**
+     * Keys or dotted paths that were present in the source but excluded from translation: a stray
+     * non-string leaf (a number, boolean, or null) for a tree-based format, or a key the format's own
+     * metadata marks as not translatable, such as an Android `translatable="false"` resource. These
+     * are never translated, hashed, diffed, or checked for placeholder or ICU integrity.
+     *
+     * Reporting them is the adapter's choice, so an empty list means this adapter reported none, not
+     * necessarily that the file carried none. A tree-based adapter reports its non-string leaves
+     * automatically; a flat adapter reports by returning `{ entries, excludedLeafPaths }` from
+     * `parseEntries` instead of a bare map.
+     *
+     * Whether one survives a later rewrite of the same file depends on the adapter: an adapter that
+     * reconstructs the whole file from `resource.entries` alone drops it, while an adapter that
+     * patches only the entries it touches into the existing document (for example `apple-xcstrings`)
+     * preserves it verbatim.
+     */
+    readonly excludedLeafPaths: readonly string[];
+}
+/**
+ * The contract every format adapter implements. A new format attaches by implementing this interface
+ * and registering it in an {@link AdapterRegistry}.
+ *
+ * Implement it through one of the two shared factories rather than from scratch:
+ * `createTreeFileAdapter` for a nested-tree format and `createFlatFileAdapter` for a flat
+ * key/value format. A format that fits neither shape implements this interface directly.
+ *
+ * An adapter shipped outside verbatra names itself with a `custom:` identifier and is attached by
+ * registering it in a registry the caller hands to the SDK. It is ordinary trusted code: verbatra
+ * does not sandbox it.
+ */
+interface FormatAdapter {
+    /**
+     * The single format this adapter handles: one of core's built-in `SupportedFormat` members, or a
+     * third-party `custom:` identifier for an adapter that ships outside verbatra.
+     */
+    readonly format: FormatId;
+    /**
+     * 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 `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 `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. Only the
+     * ICU-message formats carry a real check today (next-intl and ARB); every other adapter has no
+     * message syntax to violate and returns true for any value.
+     *
+     * @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;
+    /**
+     * Optional whole-value placeholder comparison, used by callers instead of independently extracting
+     * each side's placeholders with {@link extractPlaceholders} and diffing the flat lists. Both
+     * adapter factories accept one, under the `comparePlaceholders` option. Among the shipped
+     * adapters two families define one, for different reasons:
+     *
+     * - The ICU formats (next-intl and ARB) compare branch by branch, because flattening a
+     *   plural/select value loses which branch a placeholder came from.
+     * - The double-brace formats (i18next, ngx-translate, and YAML) add a one-directional
+     *   single-brace check on top of their flat multiset comparison: a `{name}`-shaped token present
+     *   in the translated value but absent from the source is reported as `extra`. Single-brace text
+     *   is ordinary literal content under these formats' default delimiters, so it is never required
+     *   to survive a translation, but inventing one is never a legitimate translation either.
+     *
+     * Absent for the remaining adapters, which are compared via `extractPlaceholders` plus a flat
+     * multiset check.
+     *
+     * @param sourceValue - The source value.
+     * @param targetValue - The translated value to check against it.
+     * @returns The merged placeholder-integrity result. Does not throw.
+     */
+    comparePlaceholders?(sourceValue: string, targetValue: string): PlaceholderIntegrityResult;
+}
+
+/**
+ * The outcome of a size-bounded read through the {@link AdapterFs} port. A path that is not a file,
+ * or a file larger than the caller's limit, is reported as a state rather than thrown, so an adapter
+ * can treat "no file yet" and "too large to trust" as ordinary branches.
+ */
+type BoundedReadOutcome = {
+    readonly kind: "ok";
+    readonly content: string;
+} | {
+    readonly kind: "not-a-file";
+} | {
+    readonly kind: "too-large";
+};
+/**
+ * The file-system port every format adapter reads and writes through. An adapter that takes this
+ * port instead of importing `node:fs` can be tested against an in-memory implementation and stays
+ * honest about every path it touches.
+ *
+ * This is the supported path for an adapter shipped outside verbatra, and the one verbatra hands it.
+ * It is a convention, not a sandbox: nothing stops third-party code from reaching the file system
+ * another way.
+ */
+interface AdapterFs {
+    /**
+     * Read a UTF-8 text file, refusing anything larger than the caller's limit.
+     *
+     * @param path - The file to read.
+     * @param maxBytes - The largest file size to read; a larger file yields `too-large` and is not read.
+     * @returns The file's content, or the state that prevented reading it.
+     */
+    readBounded(path: string, maxBytes: number): Promise<BoundedReadOutcome>;
+    /**
+     * Write a UTF-8 text file atomically, creating missing parent directories.
+     *
+     * @param path - The destination file.
+     * @param data - The content to write.
+     * @returns Nothing, once the content is durably in place under `path`.
+     */
+    writeFileAtomic(path: string, data: string): Promise<void>;
+}
+/**
+ * The {@link AdapterFs} implementation backed by the real file system, and the default every adapter
+ * factory uses when no port is supplied. It writes through a temporary file and a rename, so an
+ * interrupted write never leaves a half-finished locale file.
+ *
+ * @example
+ * ```ts
+ * const adapter = createFlatFileAdapter({ ...options, fs: nodeAdapterFs });
+ * ```
+ */
+declare const nodeAdapterFs: AdapterFs;
+
+/**
+ * Outcome of resolving an adapter for a file. Structured, never thrown: an unresolvable file is a
+ * status the caller branches on, not an exception.
+ *
+ * `resolved` carries the single {@link FormatAdapter} to use. `no-match` means nothing claimed the
+ * file, and reports the formats that were tried (every registered format for a detection attempt, or
+ * just the one requested when an explicit format was given). `ambiguous` means more than one adapter
+ * claimed the file, which is routine since every JSON adapter claims `.json`; it reports the competing
+ * candidates instead of guessing, and the caller resolves it by naming a format explicitly.
+ */
+type AdapterResolution = {
+    /** Exactly one adapter claimed the file. */
+    readonly status: "resolved";
+    /** The adapter to read and write the file with. */
+    readonly adapter: FormatAdapter;
+} | {
+    /** No registered adapter claimed the file. */
+    readonly status: "no-match";
+    /** The file that could not be matched. */
+    readonly filePath: string;
+    /**
+     * The formats that were tried: every registered format for a detection attempt, or just the
+     * one requested when an explicit format was given.
+     */
+    readonly triedFormats: readonly FormatId[];
+} | {
+    /** More than one adapter claimed the file, so detection cannot choose between them. */
+    readonly status: "ambiguous";
+    /** The file that several adapters claimed. */
+    readonly filePath: string;
+    /** The competing formats. Resolve the ambiguity by naming one of them explicitly. */
+    readonly candidates: readonly FormatId[];
+};
+/** Options for {@link AdapterRegistry.resolve}: select a format explicitly, or aid detection. */
+interface ResolveOptions {
+    /** A leading content sample to aid detection. Ignored when `format` is given. */
+    readonly sample?: string;
+    /** Bypass detection and select this format explicitly. */
+    readonly format?: FormatId;
+}
+/**
+ * Holds the registered adapters and resolves one for a file. Open for extension: adapters attach
+ * through {@link AdapterRegistry.register} without changing resolution logic, and an unresolvable
+ * file is a structured status rather than an exception.
+ *
+ * @example
+ * ```ts
+ * const registry = createDefaultRegistry().register(createTomlAdapter());
+ * const resolution = registry.resolve("locales/de.toml");
+ * if (resolution.status === "resolved") {
+ *   const { resource } = await resolution.adapter.read("locales/de.toml", "de");
+ * }
+ * ```
+ */
+declare class AdapterRegistry {
+    private readonly adapters;
+    /**
+     * Register an adapter. Registration order is the order detection consults them.
+     *
+     * A format identifier may be registered only once: a second adapter claiming an identifier the
+     * registry already holds is rejected, so neither a third-party adapter nor a second copy of one
+     * can silently shadow what is already there.
+     *
+     * An adapter whose format is a third-party `custom:` identifier is wrapped so that an unexpected
+     * throw from any of its contract methods surfaces as an {@link AdapterError} naming the format.
+     * Built-in adapters are registered as they are.
+     *
+     * @param adapter - The adapter to add.
+     * @returns This registry, for chaining.
+     * @throws `AdapterError` with code `INVALID_FORMAT_ID` when the format carries the `custom:`
+     *   prefix but is not a well-formed identifier. Such an adapter is refused rather than registered
+     *   without the containment wrapper, which would silently lose its failure attribution.
+     * @throws `AdapterError` with code `DUPLICATE_FORMAT` when the registry already holds an adapter
+     *   for this format.
+     *
+     * @example
+     * ```ts
+     * const registry = createDefaultRegistry().register(createTomlAdapter());
+     * await translate({ config }, { adapterRegistry: registry });
+     * ```
+     */
+    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`. An
+     *   unresolvable file is a status, not an exception.
+     * @throws `AdapterError` with code `ADAPTER_FAILED` when a registered third-party adapter throws
+     *   from its own `canHandle` during detection. Resolution itself raises nothing.
+     */
+    resolve(filePath: string, options?: ResolveOptions): AdapterResolution;
+}
+
+/**
+ * Build a registry holding every format adapter verbatra ships, in detection order. This is the
+ * starting point for adding an adapter of your own: register it on the returned registry and hand
+ * that registry to an SDK flow as its `adapterRegistry` dependency.
+ *
+ * @param fs - The file-system port every built-in adapter reads and writes through. Defaults to
+ *   {@link nodeAdapterFs}.
+ * @returns A registry of the built-in adapters, ready for further registrations.
+ *
+ * @example
+ * ```ts
+ * const registry = createDefaultRegistry().register(createTomlAdapter());
+ * await translate({ config }, { adapterRegistry: registry });
+ * ```
+ */
+declare function createDefaultRegistry(fs?: AdapterFs): AdapterRegistry;
+
+/**
+ * The stable, secret-free codes an {@link AdapterError} carries.
+ *
+ * The first seven describe a file verbatra could not handle: `INVALID_JSON`, `INVALID_YAML` and
+ * `INVALID_XML` for malformed syntax, `INVALID_STRUCTURE` for a parseable file of the wrong shape,
+ * `MAX_DEPTH_EXCEEDED` and `INPUT_TOO_LARGE` for the read caps, and `MIXED_STRUCTURE` for a file
+ * that mixes flat and nested keys where the format forbids it.
+ *
+ * The last three describe an adapter rather than a file. `ADAPTER_FAILED` attributes an unexpected
+ * throw to the third-party adapter it came from, so a plugin defect never surfaces as an
+ * unattributed verbatra stack trace. `DUPLICATE_FORMAT` rejects registering a second adapter for a
+ * format identifier a registry already holds. `INVALID_FORMAT_ID` rejects registering an adapter
+ * whose `custom:` identifier is malformed, which would otherwise be registered without the
+ * containment wrapper and silently lose its failure attribution.
+ *
+ * The set is closed. A third-party adapter raises `INVALID_STRUCTURE` (or another member that fits)
+ * rather than minting its own code.
+ */
+type AdapterErrorCode = "INVALID_JSON" | "INVALID_YAML" | "INVALID_XML" | "INVALID_STRUCTURE" | "MAX_DEPTH_EXCEEDED" | "INPUT_TOO_LARGE" | "MIXED_STRUCTURE" | "ADAPTER_FAILED" | "DUPLICATE_FORMAT" | "INVALID_FORMAT_ID";
+/**
+ * A structured, secret-free failure raised by a format adapter or by the adapter registry. Catch it
+ * to branch on {@link AdapterErrorCode} instead of matching on message text.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await adapter.read("locales/de.json", "de");
+ * } catch (error) {
+ *   if (error instanceof AdapterError && error.code === "INVALID_JSON") {
+ *     console.error(error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class AdapterError extends Error {
+    /** The stable code for this failure. */
+    readonly code: AdapterErrorCode;
+    /**
+     * @param code - The stable code for this failure.
+     * @param message - A human-readable description. Never include a secret or a file's contents.
+     */
+    constructor(code: AdapterErrorCode, message: string);
+}
+
+/** A value in a locale tree about to be serialized, with key order preserved at every level. */
+type OrderedValue = string | number | boolean | null | OrderedRecord | readonly OrderedValue[];
+/** A locale tree about to be serialized, keyed in the order it will be written out. */
+type OrderedRecord = ReadonlyMap<string, OrderedValue>;
+
+/** A terminal value in a parsed locale tree: everything that is not a nested object. */
+type JsonLeaf = string | number | boolean | null;
+/** Any node in a parsed locale tree: a leaf, or a nested record of further nodes. */
+type JsonTree = JsonLeaf | JsonRecord;
+/** A parsed locale tree node, keyed in the order the source document defined its keys. */
+type JsonRecord = ReadonlyMap<string, JsonTree>;
+
+/**
+ * Finds a format's placeholder tokens in one translatable value, in document order. Resolves
+ * nothing and never throws; a value with no placeholders yields an empty list.
+ */
+type ExtractPlaceholders = (value: string) => readonly string[];
+/**
+ * Reports the keys whose values are invalid for a format's message syntax, given every entry read
+ * from one file. Only the ICU-message formats need one; a format with no message syntax omits it.
+ */
+type ComputeInvalidIcuKeys = (entries: ReadonlyMap<string, TranslationEntry>) => readonly string[];
+/**
+ * Decides whether one candidate value is valid for a format's message syntax before it is written.
+ * Never throws: an unparseable value returns false.
+ */
+type ValidateMessage = (value: string) => boolean;
+/**
+ * Compares a source value against its translation as whole values rather than as two flat token
+ * lists, for a format whose structure (an ICU plural or select branch, for example) would be lost by
+ * flattening. Never throws: a mismatch is data.
+ */
+type ComparePlaceholders = (sourceValue: string, targetValue: string) => PlaceholderIntegrityResult;
+/**
+ * Rejects a parsed tree that is structurally wrong for a format, by throwing an `AdapterError`.
+ * Returns nothing when the tree is acceptable.
+ */
+type ValidateTree = (tree: JsonRecord) => void;
+/**
+ * Decides whether a leading content sample looks like this format, so two adapters claiming the same
+ * file extension can still be told apart. Consulted only when a sample is available.
+ */
+type Sniff = (sample: string) => boolean;
+
+/**
+ * What a flat format's `parseEntries` returns when it has content to report as skipped. Returning a
+ * bare map instead is equivalent to returning one of these with no skipped paths.
+ */
+interface FlatParseResult {
+    /** The entries read from the file, keyed by entry key, in document order. */
+    readonly entries: Map<string, TranslationEntry>;
+    /**
+     * Keys the file carried but that are excluded from translation, for example one the format's own
+     * metadata marks as not translatable. Omit it when the format has no such concept.
+     */
+    readonly excludedLeafPaths?: readonly string[];
+}
+/** What a flat format's `parseEntries` may return: the entries alone, or entries plus diagnostics. */
+type FlatParseOutcome = Map<string, TranslationEntry> | FlatParseResult;
+/** Everything {@link createFlatFileAdapter} needs to turn a flat key/value format into an adapter. */
+interface FlatFileAdapterOptions {
+    /** The format this adapter claims: a built-in name, or a `custom:` identifier of your own. */
+    readonly format: FormatId;
+    /** The lowercase file extensions this format owns, each including the leading dot. */
+    readonly extensions: readonly string[];
+    /**
+     * Optional content check, consulted when a sample is available, so this adapter does not claim
+     * every file that merely shares one of its extensions.
+     */
+    readonly sniff?: Sniff;
+    /**
+     * Parse one file's text into entries keyed by entry key, in document order. Throw an
+     * `AdapterError` for content this format cannot represent; anything else thrown is reported as a
+     * structural failure.
+     */
+    readonly parseEntries: (content: string, namespace: string, filePath: string, fs: AdapterFs) => FlatParseOutcome | Promise<FlatParseOutcome>;
+    /**
+     * Render entries back to the format's text, preserving key order. Receives the destination path
+     * and the port, for a format that has to consult the existing file to write in place.
+     */
+    readonly serializeEntries: (entries: ReadonlyMap<string, TranslationEntry>, filePath: string, fs: AdapterFs) => Promise<string> | string;
+    /** Find this format's placeholder tokens in one value. */
+    readonly extractPlaceholders: ExtractPlaceholders;
+    /** Optional message-syntax check applied to a candidate value before it is written. */
+    readonly validateMessage?: ValidateMessage;
+    /** Optional per-file report of the keys whose values are invalid for this format's message syntax. */
+    readonly computeInvalidIcuKeys?: ComputeInvalidIcuKeys;
+    /**
+     * Optional whole-value placeholder comparison, for a format whose structure a flat token list
+     * would lose. Omitted adapters are compared by `extractPlaceholders` plus a flat multiset check.
+     */
+    readonly comparePlaceholders?: ComparePlaceholders;
+    /** The file-system port to read and write through. Defaults to `nodeAdapterFs`. */
+    readonly fs?: AdapterFs;
+}
+/**
+ * Build a {@link FormatAdapter} for a flat key/value format: one where every entry is addressed by a
+ * single key with no nesting, such as Java `.properties` or Android `strings.xml`. The factory
+ * supplies the bounded read, the atomic write, extension detection and the structured error
+ * handling; you supply only the format's own parsing and serialization.
+ *
+ * @param options - The format's parsing, serialization and detection behaviour.
+ * @returns A complete adapter, ready to register on an `AdapterRegistry`.
+ * @throws Nothing itself. The returned adapter's `read` and `write` raise `AdapterError` for content
+ *   this format cannot represent, and reject with the underlying filesystem error otherwise.
+ *
+ * @example
+ * ```ts
+ * const tomlAdapter = createFlatFileAdapter({
+ *   format: "custom:toml",
+ *   extensions: [".toml"],
+ *   parseEntries: (content, namespace) => parseToml(content, namespace),
+ *   serializeEntries: (entries) => serializeToml(entries),
+ *   extractPlaceholders: (value) => [...value.matchAll(/\{\w+\}/g)].map((m) => m[0]),
+ * });
+ * ```
+ */
+declare function createFlatFileAdapter(options: FlatFileAdapterOptions): FormatAdapter;
+
+/**
+ * Derives the per-entry facts a format decides for itself from one key and its string value: the
+ * placeholder tokens the value carries, and whether the key is one plural form of a set.
+ */
+type DeriveEntry = (key: string, value: string) => {
+    readonly placeholders: readonly string[];
+    readonly isPlural: boolean;
+};
+/**
+ * How a dotted key in the source document is addressed. `literal-leaf` keeps `"a.b"` as one key
+ * whose name contains a dot; `path-notation` reads it as the nested path `a` then `b`.
+ */
+type KeyMode = "literal-leaf" | "path-notation";
+
+/**
+ * Builds the tree to serialize from the entries about to be written, for a format that patches an
+ * existing document rather than rebuilding it from the entries alone.
+ */
+type BuildWriteTree = (entries: ReadonlyMap<string, TranslationEntry>, filePath: string, fs: AdapterFs) => OrderedRecord | Promise<OrderedRecord>;
+/**
+ * Pulls per-key translator descriptions out of the raw file text, for a format that carries them as
+ * metadata alongside the values.
+ */
+type DeriveDescriptions = (content: string) => ReadonlyMap<string, string>;
+/** Everything {@link createTreeFileAdapter} needs to turn a nested-tree format into an adapter. */
+interface TreeFileAdapterOptions {
+    /** The format this adapter claims: a built-in name, or a `custom:` identifier of your own. */
+    readonly format: FormatId;
+    /** The lowercase file extensions this format owns, each including the leading dot. */
+    readonly extensions: readonly string[];
+    /**
+     * Optional content check, consulted when a sample is available, so this adapter does not claim
+     * every file that merely shares one of its extensions.
+     */
+    readonly sniff?: Sniff;
+    /** Parse one file's text into a nested tree, preserving key order at every level. */
+    readonly parse: (content: string) => JsonRecord;
+    /** Render a nested tree back to the format's text, preserving key order at every level. */
+    readonly serialize: (tree: OrderedRecord) => string;
+    /** Derive the placeholder tokens and the plural flag for one leaf. */
+    readonly deriveEntry: DeriveEntry;
+    /** Find this format's placeholder tokens in one value. */
+    readonly extractPlaceholders: ExtractPlaceholders;
+    /** Optional per-file report of the keys whose values are invalid for this format's message syntax. */
+    readonly computeInvalidIcuKeys?: ComputeInvalidIcuKeys;
+    /** Optional message-syntax check applied to a candidate value before it is written. */
+    readonly validateMessage?: ValidateMessage;
+    /** Optional structural check on the parsed tree, throwing an `AdapterError` for a shape this format forbids. */
+    readonly validateTree?: ValidateTree;
+    /** Optional override for how the tree to write is assembled, for a format that patches the existing document. */
+    readonly buildWriteTree?: BuildWriteTree;
+    /** How a dotted key is addressed. Defaults to `"literal-leaf"`. */
+    readonly keyMode?: KeyMode;
+    /** Optional whole-value placeholder comparison, for a format whose structure flattening would lose. */
+    readonly comparePlaceholders?: ComparePlaceholders;
+    /** Optional extraction of per-key translator descriptions from the raw file text. */
+    readonly deriveDescriptions?: DeriveDescriptions;
+    /** The file-system port to read and write through. Defaults to `nodeAdapterFs`. */
+    readonly fs?: AdapterFs;
+}
+/**
+ * Build a {@link FormatAdapter} for a nested-tree format: one whose entries live at paths through
+ * nested objects, such as i18next JSON or YAML. The factory supplies the bounded read, the atomic
+ * write, tree flattening and unflattening, extension detection and the structured error handling;
+ * you supply only the format's own parsing, serialization and per-leaf facts.
+ *
+ * @param options - The format's parsing, serialization, detection and per-entry behaviour.
+ * @returns A complete adapter, ready to register on an `AdapterRegistry`.
+ * @throws Nothing itself. The returned adapter's `read` and `write` raise `AdapterError` for content
+ *   this format cannot represent, and reject with the underlying filesystem error otherwise.
+ *
+ * @example
+ * ```ts
+ * const hoconAdapter = createTreeFileAdapter({
+ *   format: "custom:hocon",
+ *   extensions: [".conf"],
+ *   parse: (content) => parseHocon(content),
+ *   serialize: (tree) => serializeHocon(tree),
+ *   deriveEntry: (_key, value) => ({ placeholders: tokensIn(value), isPlural: false }),
+ *   extractPlaceholders: (value) => tokensIn(value),
+ * });
+ * ```
+ */
+declare function createTreeFileAdapter(options: TreeFileAdapterOptions): FormatAdapter;
+
+/**
+ * The outcome of a size-bounded text read. A file that is absent or larger than the caller's limit
+ * is reported as a state rather than thrown, so a caller can treat "no file yet" as normal and an
+ * oversized file as a distinct, actionable condition.
+ */
+type BoundedFileRead = {
+    /** The file was read in full. */
+    readonly kind: "ok";
+    /** The file's content, decoded as UTF-8. */
+    readonly content: string;
+} | {
+    /** No readable file exists at the path. */
+    readonly kind: "missing";
+} | {
+    /** The file exists but exceeds the requested byte limit, so nothing was read. */
+    readonly kind: "too-large";
+};
+/**
+ * The outcome of a size-bounded binary read, used for interchange workbooks. Mirrors
+ * {@link BoundedFileRead} but yields raw bytes rather than decoded text.
+ */
+type BoundedBytesRead = {
+    /** The file was read in full. */
+    readonly kind: "ok";
+    /** The file's raw bytes. */
+    readonly bytes: Uint8Array;
+} | {
+    /** No readable file exists at the path. */
+    readonly kind: "missing";
+} | {
+    /** The file exists but exceeds the requested byte limit, so nothing was read. */
+    readonly kind: "too-large";
+};
+/**
+ * What one entry in a directory listing is: a regular file, a directory, or anything else. A
+ * symbolic link is reported as `other`, never followed, which is what keeps a source scan inside
+ * the roots it was given.
+ */
+interface DirectoryEntry {
+    /** The entry's own name, with no directory part. */
+    readonly name: string;
+    /** What the entry is. Anything that is not a regular file or a directory is `other`. */
+    readonly kind: "file" | "directory" | "other";
+}
+/**
+ * The file-system port the SDK's own I/O goes through. Supplying your own implementation as a
+ * `deps.fs` option redirects that I/O, which is how the SDK's tests avoid touching disk and how an
+ * embedding application can back part of a project with something other than a local disk.
+ *
+ * The seam carries every file the SDK touches: the run-status file, the lock-file, the config
+ * glossary, workbook and interchange I/O, and the locale files themselves, which the adapters read
+ * and write through a port built from this one. The single exception is a caller-supplied
+ * `deps.adapterRegistry`: those adapters were constructed by the caller, so their file access is
+ * whatever the caller wired into them, and supplying both means the caller owns that wiring.
+ *
+ * Reads are size-bounded by contract so that a hostile or accidentally huge file cannot exhaust
+ * memory. Writes are expected to be atomic: the default implementation writes to a temporary file
+ * and renames it into place, so a crash mid-write never leaves a half-written file behind.
+ * Directory creation is the caller's job, so an implementation whose `writeFile` targets a real
+ * directory tree must also implement `mkdir`.
+ */
+interface SdkFs {
+    /** Reports whether a readable file exists at the path. */
+    fileExists(path: string): Promise<boolean>;
+    /** Reads a file as UTF-8 text, refusing to read more than `maxBytes`. */
+    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
+    /** Reads a file as raw bytes, refusing to read more than `maxBytes`. */
+    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
+    /** Writes UTF-8 text to the path, replacing any existing file atomically. */
+    writeFile(path: string, data: string): Promise<void>;
+    /** Writes raw bytes to the path, replacing any existing file atomically. */
+    writeBytes(path: string, data: Uint8Array): Promise<void>;
+    /**
+     * Creates a file only if it does not already exist, returning `false` when it does. This is the
+     * primitive behind the per-locale write lock, so it must be atomic against other processes.
+     */
+    createExclusive(path: string, data: string): Promise<boolean>;
+    /** Removes the file at the path, succeeding even when it is already absent. */
+    deleteFile(path: string): Promise<void>;
+    /** Creates a directory and any missing parents. Optional; omit it if the backing store has no directories. */
+    mkdir?(path: string): Promise<void>;
+    /**
+     * Lists one directory's immediate entries, without recursing and without following symbolic
+     * links. Optional, so an implementation written before source extraction existed keeps working;
+     * {@link extract} is the only entry point that needs it and reports its absence as
+     * `EXTRACT_FS_UNSUPPORTED`.
+     *
+     * @param path - The directory to list.
+     * @returns Every immediate entry with its kind. Rejects when the path is not a readable directory.
+     */
+    readDirectory?(path: string): Promise<readonly DirectoryEntry[]>;
+}
+
+/**
+ * The on-disk translation memory, read from and written to `verbatra.cache.json` (see
+ * {@link CACHE_FILE_NAME}). A run consults it before calling the provider, so a string that was
+ * already translated under the same configuration is reused instead of paid for again.
+ *
+ * Entries are keyed by configuration fingerprint, then locale, then source-content hash. The
+ * fingerprint layer means that changing the provider, model, tone, or glossary does not silently
+ * reuse translations produced under the old settings; those entries simply stop matching.
+ *
+ * `sources` sits beside them as a flat hash-to-text index. A hash cannot be compared for
+ * similarity, so the source text itself has to be on file for a fuzzy match to have anything to
+ * measure a changed string against. It is deliberately outside the fingerprint layer: the source
+ * text a hash stands for does not depend on which provider translated it.
+ */
+interface TranslationMemory {
+    /** The cache schema version. A file from a newer version is ignored rather than trusted. */
+    readonly version: number;
+    /** Cached values, nested as configuration fingerprint, then locale, then source-content hash. */
+    readonly entries: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>>;
+    /**
+     * The source text each content hash stands for. Empty for a cache carried forward from schema
+     * version 1, which stored no source text; it fills in as later runs touch those hashes again.
+     */
+    readonly sources: Readonly<Record<string, string>>;
+}
+
+/**
+ * The file name of the project's translation memory, resolved against the run's working directory.
+ * Commit it to reuse translations across machines and CI runs, or add it to `.gitignore` to treat
+ * the cache as purely local. Deleting it is always safe: the next run simply repays for the strings
+ * it would have reused.
+ */
+declare const CACHE_FILE_NAME = "verbatra.cache.json";
+
+/**
+ * The zod schema for the `provider` block, discriminated on `id`. Each variant's options are
+ * validated strictly, so an option that belongs to a different provider is reported as an error
+ * rather than ignored. It is embedded in {@link verbatraConfigSchema} and produces
+ * {@link ProviderConfig}.
+ */
+declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodLiteral<"anthropic">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxTokens: z.ZodNumber;
+        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"openai">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"gemini">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"deepl">;
+    options: z.ZodObject<{
+        glossaryId: z.ZodOptional<z.ZodString>;
+        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"google-translate">;
+    options: z.ZodObject<{
+        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"openai-compatible">;
+    options: z.ZodObject<{
+        baseUrl: z.ZodURL;
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+        apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strip>], "id">;
+/**
+ * The `provider` block of a verbatra config: a discriminated union on `id`, so each provider
+ * carries exactly the options it supports and nothing else.
+ *
+ * No variant has a field for an API key. Keys are read from the environment by the provider itself
+ * (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPL_API_KEY`, or
+ * `GOOGLE_TRANSLATE_API_KEY`), which is what keeps them out of config files and out of version
+ * control. The `openai-compatible` variant may name a different environment variable through
+ * `apiKeyEnvVar`, but still never holds the key itself.
+ */
+type ProviderConfig = z.infer<typeof providerConfigSchema>;
+/**
+ * The identifier of a supported translation provider: `anthropic`, `openai`, `gemini`, `deepl`,
+ * `google-translate`, or `openai-compatible`. The last one targets a local or self-hosted server
+ * that speaks the OpenAI chat-completions API.
+ */
+type ProviderId = ProviderConfig["id"];
+
+/**
+ * The zod schema every verbatra config is validated against. {@link loadConfig} applies it, so most
+ * consumers never call it directly; reach for it when you build a config programmatically and want
+ * to validate it before handing it to {@link translate}, or when you surface config errors in your
+ * own tooling.
+ *
+ * The object is strict, so an unrecognized key is an error rather than being silently ignored: a
+ * typo in a config file is reported instead of quietly doing nothing. The one exception is the
+ * optional `$schema` key, accepted so a JSON or YAML config can point an editor at the JSON Schema
+ * document the package ships as `@verbatra/sdk/config-schema.json`.
+ *
+ * `fuzzyCache` is off unless `enabled` is set. With it on, a source string whose earlier form is in
+ * the translation memory close enough to clear `threshold` reuses that translation instead of
+ * paying the provider for it. `threshold` is a similarity ratio from `0.5` to `1` and defaults to `0.9`.
+ *
+ * Beyond the per-field checks, two whole-config rules are enforced: `targetLocales` must not
+ * contain the source locale, and it must not contain two locales that differ only in case (they
+ * would collide on a case-insensitive file system). The `{locale}` token requirement is a
+ * per-field check on `files.pattern`.
+ */
+declare const verbatraConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    sourceLocale: z.ZodString;
+    targetLocales: z.ZodArray<z.ZodString>;
+    format: z.ZodUnion<readonly [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";
         properties: "properties";
-    }>;
+        "apple-strings": "apple-strings";
+        "apple-xcstrings": "apple-xcstrings";
+        "android-xml": "android-xml";
+        "gettext-po": "gettext-po";
+        ini: "ini";
+        resx: "resx";
+    }>, z.ZodTemplateLiteral<`custom:${string}`>]>;
     files: z.ZodObject<{
         pattern: z.ZodString;
         localeStyle: z.ZodOptional<z.ZodEnum<{
@@ -505,6 +1617,11 @@ declare const verbatraConfigSchema: z.ZodObject<{
             glossaryId: z.ZodOptional<z.ZodString>;
             requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodLiteral<"google-translate">;
+        options: z.ZodObject<{
+            requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodLiteral<"openai-compatible">;
         options: z.ZodObject<{
@@ -523,12 +1640,40 @@ declare const verbatraConfigSchema: z.ZodObject<{
     }>>;
     prune: z.ZodOptional<z.ZodBoolean>;
     generatePlurals: z.ZodOptional<z.ZodBoolean>;
+    fuzzyCache: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        threshold: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
     maxBatchSize: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
     budgetBehavior: z.ZodOptional<z.ZodEnum<{
         warn: "warn";
         stop: "stop";
     }>>;
+    rates: z.ZodOptional<z.ZodObject<{
+        asOf: z.ZodISODate;
+        currency: z.ZodString;
+        table: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            inputPerMillionTokens: z.ZodNumber;
+            outputPerMillionTokens: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            perMillionCharacters: z.ZodNumber;
+        }, z.core.$strict>]>>;
+    }, z.core.$strict>>;
+    extract: z.ZodOptional<z.ZodObject<{
+        framework: z.ZodEnum<{
+            i18next: "i18next";
+        }>;
+        roots: z.ZodArray<z.ZodString>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        literals: z.ZodOptional<z.ZodObject<{
+            ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        unused: z.ZodOptional<z.ZodObject<{
+            ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /**
  * A config exactly as it is written in a `verbatra.config.ts` file, before the SDK resolves
@@ -578,9 +1723,9 @@ type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<Provide
 } : never : never;
 /**
  * Maps each provider ID to its authoring-time config variant. The three language-model providers
- * get narrowed model unions; DeepL has no model to narrow, and `openai-compatible` deliberately
- * keeps a free-form model string because the endpoint is a local or self-hosted server whose model
- * list the SDK cannot know ahead of time.
+ * get narrowed model unions; DeepL and Google Cloud Translation have no model to narrow, and
+ * `openai-compatible` deliberately keeps a free-form model string because the endpoint is a local
+ * or self-hosted server whose model list the SDK cannot know ahead of time.
  */
 type AuthoringProviderVariant = {
     /** Anthropic, with `model` narrowed to the Claude model IDs. */
@@ -593,6 +1738,13 @@ type AuthoringProviderVariant = {
     deepl: Extract<ProviderConfig, {
         id: "deepl";
     }>;
+    /**
+     * Google Cloud Translation (Basic, v2), which takes no model for the same reason as DeepL: it is
+     * a machine-translation API rather than a language model.
+     */
+    "google-translate": Extract<ProviderConfig, {
+        id: "google-translate";
+    }>;
     /** A local or self-hosted OpenAI-compatible endpoint, whose model stays a free-form string. */
     "openai-compatible": Extract<ProviderConfig, {
         id: "openai-compatible";
@@ -671,6 +1823,14 @@ declare function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraCon
  * @returns The same object, typed as {@link VerbatraConfigInput}.
  */
 declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfigInput;
+/**
+ * Types a `verbatra.config.ts` narrowed to the Google Cloud Translation provider. Like DeepL, it is
+ * a machine-translation API rather than a language model, so its options carry no model field.
+ *
+ * @param config - The config object, narrowed to the Google Cloud Translation provider.
+ * @returns The same object, typed as {@link VerbatraConfigInput}.
+ */
+declare function defineConfig(config: AuthoringConfigFor<"google-translate">): VerbatraConfigInput;
 /**
  * Types a `verbatra.config.ts` for any supported provider. This is the fallback overload, and the
  * one that serves `openai-compatible`, where the model is a free-form string because the endpoint
@@ -681,6 +1841,46 @@ declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConf
  */
 declare function defineConfig(config: AuthoringConfig): VerbatraConfigInput;
 
+/**
+ * The zod schema for the optional `extract` block, validated strictly so a misspelled field is
+ * reported rather than silently ignored. It is embedded in {@link verbatraConfigSchema} and
+ * produces {@link ExtractionConfig}.
+ */
+declare const extractionConfigSchema: z.ZodObject<{
+    framework: z.ZodEnum<{
+        i18next: "i18next";
+    }>;
+    roots: z.ZodArray<z.ZodString>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    literals: z.ZodOptional<z.ZodObject<{
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    unused: z.ZodOptional<z.ZodObject<{
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * The `extract` block of a verbatra config: which translation framework's call sites the source
+ * scan looks for, which directories it walks, and which directory names it skips on the way.
+ *
+ * `roots` are resolved against the run's working directory, and the scan never reads outside them.
+ * `exclude` adds directory names to the set that is always skipped, which already covers
+ * `node_modules`, `.git`, and the usual build output directories.
+ *
+ * `literals.ignore` lists string literals the untranslated-literal scan (`verbatra doctor
+ * --literals`) holds back project-wide, matched against the whole literal text as it is reported:
+ * whitespace collapsed and, in JSX text or a quoted JSX attribute value, character references such
+ * as `&amp;` decoded, so an entry is written `Tom & Jerry`, not `Tom &amp; Jerry`. A held-back
+ * literal is still reported, under `suppressed`, so nothing vanishes silently.
+ *
+ * `unused.ignore` names catalog keys the unused-key report must not count as unused, for a key
+ * referenced only from outside the scanned source (a server template, a CMS, a test fixture). Each
+ * entry is an exact key, or a pattern in which `*` matches any run of characters, such as
+ * `emails.*`. It matches the decoded key as the report shows it (`Welcome. Enjoy`, not the escaped
+ * catalog spelling). A matched key is reported as ignored, never dropped from the report.
+ */
+type ExtractionConfig = z.infer<typeof extractionConfigSchema>;
+
 /**
  * Where a loaded config's glossary came from, reported by {@link loadConfigWithMeta}. The resolved
  * {@link VerbatraConfig} holds only the final term map, so this is the one place a tool can tell an
@@ -890,6 +2090,67 @@ declare function loadConfigWithMeta(options?: LoadConfigOptions): Promise<Loaded
  */
 declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig>;
 
+/**
+ * What a provider charges for: `tokens` for the prompt-driven LLMs, which bill the prompt and the
+ * completion separately, and `characters` for the machine-translation APIs, which bill the source
+ * text they are handed and report no token usage at all.
+ */
+type BillingUnit = "tokens" | "characters";
+/**
+ * How one provider bills. `billedByApi` is false for a self-hosted endpoint, which still consumes
+ * tokens but sends no invoice, so an estimate reports its quantity and no currency figure.
+ */
+interface ProviderBilling {
+    /** The quantity this provider charges for. */
+    readonly unit: BillingUnit;
+    /** Whether a hosted API bills for the work at all. */
+    readonly billedByApi: boolean;
+}
+
+declare const tokenRateSchema: z.ZodObject<{
+    inputPerMillionTokens: z.ZodNumber;
+    outputPerMillionTokens: z.ZodNumber;
+}, z.core.$strict>;
+declare const characterRateSchema: z.ZodObject<{
+    perMillionCharacters: z.ZodNumber;
+}, z.core.$strict>;
+declare const modelRateSchema: z.ZodUnion<readonly [z.ZodObject<{
+    inputPerMillionTokens: z.ZodNumber;
+    outputPerMillionTokens: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    perMillionCharacters: z.ZodNumber;
+}, z.core.$strict>]>;
+declare const rateCardSchema: z.ZodObject<{
+    asOf: z.ZodISODate;
+    currency: z.ZodString;
+    table: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        inputPerMillionTokens: z.ZodNumber;
+        outputPerMillionTokens: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        perMillionCharacters: z.ZodNumber;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+/**
+ * A rate charging by tokens, with the prompt and the completion priced separately. Every hosted LLM
+ * provider bills this way.
+ */
+type TokenRate = z.infer<typeof tokenRateSchema>;
+/** A rate charging by source characters, which is how the machine-translation APIs bill. */
+type CharacterRate = z.infer<typeof characterRateSchema>;
+/** One entry of a {@link RateCard}: either a token rate or a character rate, never both. */
+type ModelRate = z.infer<typeof modelRateSchema>;
+/**
+ * The rates a project supplies so an estimate can be expressed in money. verbatra ships no prices of
+ * its own: they are a third party's, they change without notice, and a number baked into a release
+ * would quietly go stale. The card carries the date it was read and the currency it is written in,
+ * so any figure derived from it is visibly as old as `asOf` says it is.
+ *
+ * `table` is keyed by rate key: `provider/model` for a provider configured with a model (for
+ * example `gemini/gemini-2.5-flash`), and the bare provider id for one without (`deepl`,
+ * `google-translate`).
+ */
+type RateCard = z.infer<typeof rateCardSchema>;
+
 /**
  * The stable, structured failure codes the SDK throws. Branch on {@link SdkError.code} rather than
  * on a message; the messages are written for humans and are not part of the contract.
@@ -958,18 +2219,42 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   {@link translate} before any locale runs, and by {@link watch} once at startup, before any
  *   watching begins, since the value is fixed for the session rather than re-read per run.
  * - `CONCURRENCY_BUDGET_CONFLICT`: a live run requested a `concurrency` above 1 while a token
- *   budget is configured. The two are mutually exclusive because concurrency makes the budget's
- *   stop guarantee nondeterministic. A dry run is exempt, since it never consults the budget.
+ *   budget is configured. The ceiling itself would still hold, but which locale loses its
+ *   remaining work would depend on the order the locales interleave, so the same project would not
+ *   produce the same run twice. A dry run is exempt, since it never consults the budget.
  * - `TARGET_UNWRITABLE`: a target locale file could not be written, because its directory is not
  *   writable, does not exist, is read-only, or is out of space. The message names the target file
  *   relative to `cwd` and the underlying file-system code, never the internal temporary file the
  *   atomic write uses. Thrown by {@link editEntry} and {@link retranslateEntry}, which act on one
  *   locale. {@link translate} and {@link importWorkbook} do not throw it: they record it on that
  *   locale's {@link LocaleSummary} and carry on with the other locales.
+ * - `PSEUDO_OUTPUT_CONFLICT`: {@link pseudolocalize} was asked to generate a pseudolocale that
+ *   names a configured locale, or to write one onto a configured locale file. Refused before
+ *   anything is read or written, so a generated pseudolocale can never overwrite a real
+ *   translation or stand in for one.
+ * - `SOURCE_UNWRITABLE`: the source locale file could not be written. Thrown by {@link extract}
+ *   alone, since it is the only entry point that writes the source locale. The `xliff` and
+ *   `apple-xcstrings` formats reach it when no catalog exists yet, because neither is created from
+ *   nothing.
+ * - `EXTRACT_NOT_CONFIGURED`: {@link extract} was called with a config that carries no `extract`
+ *   block, so there is no framework to look for and no source root to walk.
+ * - `EXTRACT_FS_UNSUPPORTED`: {@link extract} was given a `deps.fs` that implements no
+ *   `readDirectory`, so no source file can be discovered. The member is optional on {@link SdkFs}
+ *   precisely so an implementation written before extraction existed keeps compiling; this is the
+ *   error it gets if it is then handed to {@link extract}.
+ * - `TYPES_OUTPUT_CONFLICT`: {@link generateTypes} refused its output path. Before anything is
+ *   read or written, it refuses a path that names no file, is absolute, climbs out of the working
+ *   directory, or does not end in `.ts`, `.mts` or `.cts`, and one naming a configured locale
+ *   file, the lock file, the translation-memory cache, a file verbatra searches for its
+ *   configuration, or the configuration file the run loaded, compared case-insensitively. A
+ *   generating run, never a `check` run, also refuses to replace an existing file there that does
+ *   not begin with the header line verbatra writes, and leaves that file untouched.
+ * - `TYPES_UNWRITABLE`: the declaration file {@link generateTypes} produces could not be written,
+ *   because its directory is not writable, does not exist, or the disk is out of space.
  * - `LOCALE_FAILED`: never thrown. It is the fallback code recorded on a failed
  *   {@link LocaleSummary} when a per-locale failure carries no code of its own.
  */
-type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "UNKNOWN_LOCALE" | "UNKNOWN_KEY" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCK_CONTENDED" | "GLOSSARY_NOT_FILE_BACKED" | "GLOSSARY_UNWRITABLE" | "LOCALE_LAYOUT_INVALID" | "LOCALE_PATH_COLLISION" | "CONCURRENCY_INVALID" | "CONCURRENCY_BUDGET_CONFLICT" | "TARGET_UNWRITABLE" | "LOCALE_FAILED";
+type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "UNKNOWN_LOCALE" | "UNKNOWN_KEY" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCK_CONTENDED" | "GLOSSARY_NOT_FILE_BACKED" | "GLOSSARY_UNWRITABLE" | "LOCALE_LAYOUT_INVALID" | "LOCALE_PATH_COLLISION" | "CONCURRENCY_INVALID" | "CONCURRENCY_BUDGET_CONFLICT" | "TARGET_UNWRITABLE" | "PSEUDO_OUTPUT_CONFLICT" | "SOURCE_UNWRITABLE" | "EXTRACT_NOT_CONFIGURED" | "EXTRACT_FS_UNSUPPORTED" | "TYPES_OUTPUT_CONFLICT" | "TYPES_UNWRITABLE" | "LOCALE_FAILED";
 /**
  * The single structured error the SDK throws. Every whole-run failure surfaces as an `SdkError`
  * carrying a stable {@link SdkErrorCode}; per-locale failures, provider notices, and integrity
@@ -977,275 +2262,504 @@ type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "
  *
  * An `SdkError` never carries a secret in its message.
  */
-declare class SdkError extends Error {
-    /** The stable {@link SdkErrorCode} for this failure. Branch on this, not on the message. */
-    readonly code: SdkErrorCode;
+declare class SdkError extends Error {
+    /** The stable {@link SdkErrorCode} for this failure. Branch on this, not on the message. */
+    readonly code: SdkErrorCode;
+    /**
+     * @param code - The stable failure code.
+     * @param message - A human-readable description of the failure. Never contains a secret.
+     * @param options - `cause` carries the error this one wraps, such as the interchange reader's
+     * error for a `SOURCE_INVALID` TMX file. Read that file's line, column and unit with
+     * `tmxErrorLocation` rather than from the cause directly.
+     */
+    constructor(code: SdkErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+
+/**
+ * Conditions the SDK itself reports on a locale, as opposed to the {@link ProviderNotice} codes a
+ * provider raises. Each marks a run that completed but did something a caller may want to know
+ * about.
+ *
+ * - `PLURAL_CATEGORIES_INCOMPLETE`: plural generation could not produce every category the target
+ *   language requires, so the entry is written with the categories that were produced.
+ * - `SUB_BATCH_FAILED`: one sub-batch of a locale failed while others succeeded. The locale is
+ *   reported as `partial` rather than failed.
+ * - `BLANK_ROW_BASELINE_RETAINED`: an imported handoff row was blank, so the existing translation
+ *   and its lock-file baseline were kept rather than being erased.
+ * - `BUDGET_TOKENS_EXCEEDED`: the configured token budget was reached. Under `warn` the run
+ *   continues and the overrun is reported; under `stop` the request that would have crossed the
+ *   ceiling is withheld before it is sent, and so is every request after it.
+ * - `CACHE_VERSION_UNRECOGNIZED`: the translation memory is at a version this release does not
+ *   understand, so it was ignored rather than trusted.
+ */
+type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED" | "CACHE_VERSION_UNRECOGNIZED";
+/**
+ * Token usage as reported by the provider. Absent when the provider does not report usage, which is
+ * the case for machine-translation APIs such as DeepL that do not bill in tokens.
+ */
+interface UsageSummary {
+    /** Tokens consumed by the prompts sent to the provider. */
+    readonly inputTokens: number;
+    /** Tokens consumed by the provider's responses. */
+    readonly outputTokens: number;
+}
+/**
+ * What a run does about its token budget. `warn`, the default, counts the spend and reports the
+ * overrun without withholding anything. `stop` turns the figure into a ceiling: before each
+ * provider request the run projects what that request will cost, and withholds it, and everything
+ * after it, rather than send a request that would take the run past `maxTokens`.
+ */
+type BudgetBehavior = "warn" | "stop";
+/**
+ * The token budget in force for one run, and how much of it that run consumed.
+ *
+ * It is enforced for every provider, including the machine-translation APIs that report no usage of
+ * their own: those are counted from the same projection the pre-run estimate uses, so a ceiling set
+ * against DeepL or Google Cloud Translation withholds work rather than sitting inert.
+ * {@link supported} says which of the two the figure came from.
+ *
+ * It bounds one run, not a session. {@link watch} starts a fresh budget for every run it triggers,
+ * so a watch session can spend up to `maxTokens` again on each source edit. It also covers
+ * {@link translate} and nothing else: `retranslateEntry` constructs its own provider on a separate
+ * path, reached from the Studio dashboard and the agent tools, and no budget here caps that spend.
+ *
+ * Under `stop` the ceiling is checked before every request the run sends, each half of a re-split
+ * request included, and a refused request is never sent. What a reservation cannot bound is what
+ * happens inside a request it already admitted. The provider layer sends one repair call of its own
+ * when keys come back missing, so one admitted batch can cost up to about twice its projection; and
+ * the count is only as good as what the provider reports, so a provider under-reporting its usage
+ * would leave the ceiling further away than it looks. Both land at reconciliation, and nothing
+ * further is admitted once they do. A request that fails or comes back truncated keeps its whole
+ * projection charged rather than being refunded, because such a call has usually already billed for
+ * its prompt.
+ */
+interface RunBudget {
+    /** The configured ceiling, in tokens. */
+    readonly maxTokens: number;
+    /** Whether passing the ceiling only warns, or withholds work to stay under it. */
+    readonly behavior: BudgetBehavior;
+    /**
+     * Whether {@link tokensUsed} is entirely the provider's own reported usage. False as soon as one
+     * counted request came back without a usable figure, so the total is partly verbatra's own
+     * projection: a machine-translation API reports none at all, and a failed or truncated request
+     * reports none either. The budget is enforced either way.
+     */
+    readonly supported: boolean;
+    /**
+     * Tokens counted across the run: reported usage for every request that gave one, and the
+     * projection for every request that did not.
+     */
+    readonly tokensUsed: number;
+    /**
+     * True once the run reached its ceiling: either `tokensUsed` reached or passed `maxTokens`, or,
+     * under `stop`, a request was withheld because sending it would have passed it.
+     */
+    readonly exceeded: boolean;
+}
+/**
+ * Why a {@link RunEstimate} does or does not carry a currency figure.
+ *
+ * - `priced`: a rate for this provider and model was found on the configured rate card and applied.
+ * - `no-rate-on-file`: no rate was configured for {@link RunEstimate.rateKey}. The quantity is still
+ *   reported; the money is not, because verbatra ships no prices of its own and will not guess one.
+ * - `rate-unit-mismatch`: a rate exists but is written in the wrong unit for this provider, for
+ *   instance a per-character price against a token-billed model. It is refused rather than applied.
+ * - `not-billed`: the provider is a self-hosted endpoint, so no API bills for the run at all.
+ */
+type EstimatePricing = "priced" | "no-rate-on-file" | "rate-unit-mismatch" | "not-billed";
+/**
+ * What a pre-run estimate deliberately leaves out. Each code names a way the real run can land
+ * below the figure, above it, or away from it, so an estimate is never mistaken for an invoice.
+ *
+ * - `CACHE_NOT_CONSULTED`: the estimate does not read the translation memory, so keys a live run
+ *   would serve from cache are still counted.
+ * - `SOURCE_DUPLICATES_NOT_DEDUPLICATED`: a live run sends one representative per identical source
+ *   string; the estimate counts every key.
+ * - `TRANSPORT_RETRIES_NOT_COUNTED`: the estimate counts one billable call per planned request. The
+ *   provider SDKs retry a failed call underneath that, so one planned request can become several
+ *   attempts on the wire, and a retried attempt that reached the model is still billed.
+ * - `TRANSLATION_LENGTH_IS_ESTIMATED`: the translation does not exist yet, so the response is sized
+ *   from the source value plus a fixed expansion allowance. A target language that runs longer than
+ *   the allowance reports more completion tokens than this figure predicts.
+ * - `TOKEN_COUNT_IS_HEURISTIC`: tokens are derived from character counts, not from the provider's
+ *   own tokenizer.
+ * - `REPAIR_REQUESTS_NOT_COUNTED`: the extra requests an incomplete response can trigger are not
+ *   counted: one bounded repair round when keys came back missing, and a retry in halves, which
+ *   recurses, when the output was cut off. A repair round re-sends the system rules, the glossary
+ *   and the tone in full, so repairing one key in a large-glossary batch costs close to a whole
+ *   extra request.
+ */
+type EstimateCaveatCode = "CACHE_NOT_CONSULTED" | "SOURCE_DUPLICATES_NOT_DEDUPLICATED" | "TRANSPORT_RETRIES_NOT_COUNTED" | "TRANSLATION_LENGTH_IS_ESTIMATED" | "TOKEN_COUNT_IS_HEURISTIC" | "REPAIR_REQUESTS_NOT_COUNTED";
+/**
+ * The estimated billing quantity for one target locale, without the money. `inputTokens` and
+ * `outputTokens` are present only for a token-billed provider, and `sourceCharacters` only for a
+ * character-billed one, so a machine-translation API is never handed a token figure it does not
+ * bill by.
+ */
+interface LocaleEstimateQuantity {
+    /** The target locale this estimate covers. */
+    readonly locale: string;
+    /** How many keys would be sent for this locale, translation and plural generation together. */
+    readonly keys: number;
+    /** How many provider requests those keys would be split into. */
+    readonly requests: number;
+    /** Estimated prompt tokens. Present only when the provider bills by tokens. */
+    readonly inputTokens?: number;
+    /** Estimated completion tokens. Present only when the provider bills by tokens. */
+    readonly outputTokens?: number;
+    /** Estimated source characters. Present only when the provider bills by characters. */
+    readonly sourceCharacters?: number;
+}
+/** One locale of a {@link PricedRunEstimate}: the quantity plus the money it comes to. */
+interface PricedLocaleEstimate extends LocaleEstimateQuantity {
+    /** The estimated cost for this locale, in {@link PricedRunEstimate.currency}. */
+    readonly cost: number;
+}
+/** One locale of an {@link UnpricedRunEstimate}: the quantity, and deliberately no money. */
+interface UnpricedLocaleEstimate extends LocaleEstimateQuantity {
+    /** Never present: the run carries no rate, so no locale of it carries a figure. */
+    readonly cost?: undefined;
+}
+/**
+ * One target locale of a {@link RunEstimate}. It carries a `cost` exactly when the run it belongs
+ * to was priced, so there is no such thing as a priced estimate with a costless locale.
+ */
+type LocaleEstimate = PricedLocaleEstimate | UnpricedLocaleEstimate;
+/**
+ * Everything a {@link RunEstimate} reports regardless of whether it could be priced: which provider
+ * the figure was computed for, how much would be sent, and what the figure leaves out.
+ */
+interface EstimateIdentity {
+    /** The provider the estimate was computed for. */
+    readonly provider: ProviderId;
+    /** The configured model, absent for a provider that takes none (`deepl`, `google-translate`). */
+    readonly model?: string;
+    /**
+     * The key a rate is filed under in the config's `rates.table`: `provider/model` for a provider
+     * configured with a model, and the bare provider id otherwise.
+     */
+    readonly rateKey: string;
+    /**
+     * Keys that would be sent across every locale, counting both the keys that would be translated
+     * and the plural forms that would be generated.
+     */
+    readonly keys: number;
+    /** Provider requests across every locale, generation batches included. */
+    readonly requests: number;
+    /** What this figure leaves out. Always present, never empty. See {@link EstimateCaveatCode}. */
+    readonly caveats: readonly EstimateCaveatCode[];
+}
+/** The quantity a token-billed provider charges for: the prompt and the completion, separately. */
+interface TokenRunQuantity extends EstimateIdentity {
+    /** Always `tokens` for a prompt-driven LLM. */
+    readonly unit: "tokens";
+    /** Estimated prompt tokens across every locale. */
+    readonly inputTokens: number;
+    /** Estimated completion tokens across every locale. */
+    readonly outputTokens: number;
+    /** Never present: a token-billed provider does not bill source characters. */
+    readonly sourceCharacters?: undefined;
+}
+/** The quantity a character-billed provider charges for: the source text handed to it. */
+interface CharacterRunQuantity extends EstimateIdentity {
+    /** Always `characters` for a machine-translation API. */
+    readonly unit: "characters";
+    /** Estimated source characters across every locale. */
+    readonly sourceCharacters: number;
+    /** Never present: a machine-translation API reports no token usage at all. */
+    readonly inputTokens?: undefined;
+    /** Never present: a machine-translation API reports no token usage at all. */
+    readonly outputTokens?: undefined;
+}
+/**
+ * What a run would send, discriminated on {@link unit} so the billed dimension is always present
+ * and the other one is never readable as a zero.
+ */
+type RunEstimateQuantity = TokenRunQuantity | CharacterRunQuantity;
+interface PricedEstimateMoney {
+    /** Always `priced`: a rate was found and applied. */
+    readonly pricing: "priced";
+    /** The rate card's currency code. */
+    readonly currency: string;
     /**
-     * @param code - The stable failure code.
-     * @param message - A human-readable description of the failure. Never contains a secret.
+     * The date the rates were read, as the config declared it. Print it beside any figure: a rate
+     * card is exactly as current as this date.
      */
-    constructor(code: SdkErrorCode, message: string);
+    readonly asOf: string;
+    /** The per-locale breakdown, in the same order as {@link RunSummary.locales}. */
+    readonly locales: readonly PricedLocaleEstimate[];
+    /** The estimated total, in {@link currency}. */
+    readonly cost: number;
+}
+interface UnpricedEstimateMoney {
+    /** Why no currency figure is present. See {@link EstimatePricing}. */
+    readonly pricing: Exclude<EstimatePricing, "priced">;
+    /** The per-locale breakdown, in the same order as {@link RunSummary.locales}. */
+    readonly locales: readonly UnpricedLocaleEstimate[];
+    /** Never present: there is no rate to express a figure in. */
+    readonly currency?: undefined;
+    /** Never present: there is no rate, so there is no date it was read on. */
+    readonly asOf?: undefined;
+    /** Never present: an absent rate is reported as absent, never as a cost of zero. */
+    readonly cost?: undefined;
+}
+interface TokenPricedRunEstimate extends TokenRunQuantity, PricedEstimateMoney {
+}
+interface CharacterPricedRunEstimate extends CharacterRunQuantity, PricedEstimateMoney {
+}
+interface TokenUnpricedRunEstimate extends TokenRunQuantity, UnpricedEstimateMoney {
+}
+interface CharacterUnpricedRunEstimate extends CharacterRunQuantity, UnpricedEstimateMoney {
 }
-
 /**
- * Zod schema accepting exactly one of the eight source formats verbatra can read and write. Each
- * member names the ecosystem it round-trips, not just a file extension, because several of them share
- * one: `i18next-json` is i18next's nested JSON with its plural key suffixes, `vue-i18n-json` is Vue
- * I18n's JSON with its pipe-separated plural values, `next-intl-json` is next-intl's ICU-message JSON,
- * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining four are `xliff` (the XLIFF
- * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle), and
- * `properties` (Java and Spring `.properties` files).
- *
- * The set is closed: a format outside it cannot be represented, so adding one means adding a member
- * here and an adapter that claims it.
+ * An estimate a rate could be applied to: the config supplied a rate for `rateKey` in the right
+ * unit, so the run carries a currency figure and the date that rate was read.
  */
-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";
-    properties: "properties";
-}>;
-/** One of the eight supported source formats; the inferred type of {@link supportedFormatSchema}. */
-type SupportedFormat = z.infer<typeof supportedFormatSchema>;
-
+type PricedRunEstimate = TokenPricedRunEstimate | CharacterPricedRunEstimate;
 /**
- * A single, format-neutral translation unit. Placeholders are supplied already extracted; core never
- * derives them from the value, so an adapter that reads a file is the one authority on what counts as
- * a placeholder in that format.
- *
- * The fields are: `key`, the entry's identifier within its namespace, non-empty and already flattened
- * to the dotted path an adapter produced; `namespace`, the namespace the entry belongs to, empty when
- * the format has no namespacing; `value`, the translatable string itself, which is untrusted input and
- * may be empty; `description` and `meaning`, both optional free-form context that a provider is told to
- * use only for disambiguation and never to translate or echo back; `placeholders`, the format's
- * placeholder tokens in document order, used for the output integrity check and to decide which entries
- * a placeholder-blind provider must withhold; and `isPlural`, whether the entry carries plural forms
- * (an i18next plural key suffix, a vue-i18n pipe-separated value, or an ICU plural), which the adapter
- * decides and which feeds the content hash.
+ * An estimate carrying quantity and no money, with `pricing` saying why. verbatra ships no prices
+ * of its own and will not guess one, so the absence is reported rather than rendered as a cost of
+ * zero.
  */
-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>;
+type UnpricedRunEstimate = TokenUnpricedRunEstimate | CharacterUnpricedRunEstimate;
 /**
- * The validated shape of one translation unit; the inferred type of {@link translationEntrySchema},
- * made deeply readonly. See that schema for what each field carries.
+ * A pre-run estimate: what a run would send, and what that would cost at the rates the project
+ * supplied. It is computed without constructing a provider, reading an API key, or making a network
+ * call.
+ *
+ * It bounds the plan, not the invoice. Every provider call a live run schedules is counted,
+ * including the plural-generation batches; the prompt is measured from the request payload that
+ * would actually be sent rather than modelled; and the response is sized from the source value plus
+ * an expansion allowance. Against that plan a live run usually spends less, because it consults the
+ * translation memory and collapses identical source strings.
+ *
+ * It can also spend more, and {@link EstimateCaveatCode} names every way: the provider SDKs retry a
+ * failed call underneath each planned request, an incomplete response triggers a repair round or a
+ * recursive split, a target language can expand past the allowance, and the token figure is a
+ * character heuristic rather than the provider's own tokenizer. Treat it as a planning figure, not
+ * as a ceiling that cannot be crossed.
+ *
+ * It covers {@link translate} and nothing else. `retranslateEntry` constructs a provider and calls
+ * it on its own path, reached from the Studio dashboard and the agent tools, and no estimate here
+ * sees that spend.
+ *
+ * Branch on {@link pricing}: a {@link PricedRunEstimate} carries `cost`, `currency` and `asOf`, and
+ * an {@link UnpricedRunEstimate} carries none of them and says why.
  */
-type TranslationEntry = Readonly<z.infer<typeof translationEntrySchema>>;
-
+type RunEstimate = PricedRunEstimate | UnpricedRunEstimate;
+/** A condition the SDK reported on a locale. See {@link SdkNoticeCode}. */
+interface SdkNotice {
+    /** The stable notice code. Branch on this, not on the message. */
+    readonly code: SdkNoticeCode;
+    /** A human-readable description of the condition. */
+    readonly message: string;
+}
 /**
- * All translation entries for one locale and namespace, keyed by entry key. This is the neutral
- * intermediate representation every adapter reads into and writes back out of, so nothing downstream
- * of an adapter parses a format's own syntax.
+ * Any notice attached to a locale: either one the provider raised, such as a downgraded formality
+ * or an ignored glossary, or one the SDK raised. Discriminate on `code`.
  */
-interface LocaleResource {
-    /** The locale these entries belong to (for example, "en" or "de"). */
-    readonly locale: string;
-    /** The namespace these entries belong to; empty when the format has no namespacing. */
-    readonly namespace: string;
-    /** The source format the resource came from, retained for round-trip fidelity on write. */
-    readonly format: SupportedFormat;
-    /** Entries addressable by key, in the order the source file defined them. */
-    readonly entries: ReadonlyMap<string, TranslationEntry>;
-}
-
+type LocaleNotice = ProviderNotice | SdkNotice;
 /**
- * Result of comparing source placeholders against translated-output placeholders as MULTISETS
- * (counts matter, so dropping one of two occurrences of the same token is still a miss). Always
- * returned, never thrown: a mismatch is data the caller decides what to do about, not a failure.
+ * A translated key the provider layer flagged as worth a human look. The translation was still
+ * written; these are advisory quality signals, not rejections.
  */
-interface PlaceholderIntegrityResult {
-    /** True when nothing is missing or extra: the multisets match, regardless of order. */
-    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. Never true alongside a mismatch. */
-    readonly reordered: boolean;
+interface NeedsReviewEntry {
+    /** The key that was flagged. */
+    readonly key: string;
+    /** Why it was flagged. A key can carry more than one reason. */
+    readonly reasons: readonly ReviewReasonCode[];
 }
-
 /**
- * The result of reading a file into core's intermediate representation. The two diagnostic lists are
- * reported as data rather than thrown, so one bad leaf never fails a whole read.
+ * A key whose translation was reused from the translation memory even though its source string had
+ * changed, because the earlier source it was translated from is close enough to the current one.
+ *
+ * It is reported apart from {@link LocaleSummary.cacheHits} on purpose: an exact cache hit is the
+ * same string it always was, while this is a translation of text that is no longer the source text.
+ * {@link similarity} and {@link previousSource} are the evidence for the reuse, so a reader can
+ * judge it rather than take it on trust.
+ *
+ * A reuse is written to the locale file but deliberately not locked: the key keeps the lock-file
+ * baseline it already had, so it stays changed, is offered and flagged again on every later run at
+ * no provider cost, and settles only once a real translation lands. Every key listed here also
+ * carries `FUZZY_CACHE_REUSE` in {@link LocaleSummary.needsReview}.
  */
-interface ReadResult {
-    /** The parsed locale resource. */
-    readonly resource: LocaleResource;
+interface FuzzyCacheHit {
+    /** The key whose translation was reused. */
+    readonly key: string;
+    /** The key's source text at the time this translation was produced. */
+    readonly previousSource: string;
     /**
-     * Keys whose values are invalid for the format's message syntax. Empty for a format with no
-     * message-syntax check, which treats every value as valid.
+     * How alike {@link previousSource} and the current source are, from `0` to `1`, as measured by
+     * the configured `fuzzyCache.threshold`. Always at or above that threshold.
      */
-    readonly invalidIcuKeys: readonly string[];
+    readonly similarity: number;
+}
+/** A row of an imported handoff that could not be read. Reported rather than aborting the import. */
+interface MalformedRowReport {
+    /** The row's 1-based index within its sheet or file. */
+    readonly row: number;
     /**
-     * Dotted paths of leaves that were present in the source but excluded because they are not
-     * strings (a stray number, boolean, or null). These are never translated, hashed, diffed, or
-     * checked for placeholder or ICU integrity, and are not written back if the file is later
-     * rewritten. Empty for a file with no such leaves.
+     * The 1-based physical line in the source file, for delimited formats where a quoted value can
+     * span several lines. Absent for `.xlsx`, which has rows but no lines.
      */
-    readonly excludedLeafPaths: readonly string[];
+    readonly line?: number;
+    /** The column whose value was missing or unusable. */
+    readonly column: string;
 }
 /**
- * The contract every format adapter implements. A new format attaches by implementing this interface
- * and registering it in an {@link AdapterRegistry}.
+ * A key that appeared more than once in an imported handoff. The first occurrence wins and the rest
+ * are reported here, so a translator who duplicated a row learns which value was actually used.
+ */
+interface DuplicateKeyReport {
+    /** The key that appeared more than once. */
+    readonly key: string;
+    /** The 1-based row index of the ignored occurrence. */
+    readonly row: number;
+    /** The 1-based physical line of the ignored occurrence, for delimited formats. Absent for `.xlsx`. */
+    readonly line?: number;
+}
+/**
+ * Everything that happened for one locale during a run. The key lists are disjoint accounts of what
+ * became of each key, so a caller can reconstruct the whole run without re-reading any file.
  *
- * Implement it through one of `@verbatra/format-adapters`' shared factories rather than from
- * scratch: `createTreeFileAdapter` for a nested-tree format (with `createJsonFileAdapter` as its
- * JSON specialization) and `createFlatFileAdapter` for a flat key/value format. A format that fits
- * neither shape implements this interface directly, and either way it first needs its member added
- * to core's {@link SupportedFormat}.
+ * A locale that failed outright still appears here with `status: "failed"` and an `error`, rather
+ * than the whole run throwing. That is the central contract of {@link translate}: one unreachable
+ * provider or one unwritable file does not discard the locales that succeeded.
  */
-interface FormatAdapter {
-    /** The single format this adapter handles (a {@link SupportedFormat} from core). */
-    readonly format: SupportedFormat;
+interface LocaleSummary {
+    /** The target locale this summary describes. */
+    readonly locale: string;
     /**
-     * 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.
+     * `succeeded` when everything asked for was done, `partial` when some keys were translated and
+     * others were not, and `failed` when the locale produced no usable result.
      */
-    canHandle(filePath: string, sample?: string): boolean;
+    readonly status: "succeeded" | "partial" | "failed";
+    /** Keys newly translated by the provider in this run. */
+    readonly translated: readonly string[];
+    /** Keys already up to date against the lock-file baseline, so no provider call was made. */
+    readonly unchanged: readonly string[];
+    /** Keys present in this locale but no longer in the source. Reported, and removed only when pruning. */
+    readonly orphaned: readonly string[];
+    /** Orphaned keys that were actually removed, which happens only when the run was asked to prune. */
+    readonly pruned: readonly string[];
     /**
-     * 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 `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.
+     * Keys whose source text is not valid ICU. They are skipped rather than sent to the provider,
+     * because a broken source message cannot yield a sound translation.
      */
-    read(filePath: string, locale: string): Promise<ReadResult>;
+    readonly invalidIcuSource: readonly string[];
     /**
-     * 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 `AdapterError` if the resource cannot be represented in the format; rejects with the
-     *   underlying filesystem error on a write failure.
+     * Keys served from the translation memory instead of the provider, and so not paid for. Only
+     * exact matches: a reuse for a source string that has since changed is reported in
+     * {@link fuzzyHits} instead, never here.
      */
-    write(resource: LocaleResource, filePath: string): Promise<void>;
+    readonly cacheHits: readonly string[];
     /**
-     * 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.
+     * Keys whose translation was reused for a source string that had changed, with the score and the
+     * earlier source behind each reuse. Always empty unless `fuzzyCache.enabled` was set. These keys
+     * are written but not locked, so they reappear here on every run until they are really
+     * translated. See {@link FuzzyCacheHit}.
      */
-    extractPlaceholders(value: string): readonly string[];
+    readonly fuzzyHits: readonly FuzzyCacheHit[];
     /**
-     * Validate a single value against the format's message syntax before it is written. Only the
-     * ICU-message formats carry a real check today (next-intl and ARB); every other adapter has no
-     * message syntax to violate and returns true for any value.
-     *
-     * @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.
+     * Keys whose translation was refused by the integrity gate, for instance because it dropped a
+     * placeholder. The previous translation, if any, is left untouched.
      */
-    validateMessage(value: string): boolean;
+    readonly integrityMismatches: readonly string[];
+    /** Keys the provider failed to translate, for instance because their sub-batch errored. */
+    readonly providerFailures: readonly string[];
     /**
-     * Optional whole-value placeholder comparison, used by callers instead of independently extracting
-     * each side's placeholders with {@link extractPlaceholders} and diffing the flat lists. Two adapter
-     * families define one, for different reasons:
-     *
-     * - The ICU formats (next-intl and ARB) compare branch by branch, because flattening a
-     *   plural/select value loses which branch a placeholder came from.
-     * - The double-brace formats (i18next, ngx-translate, and YAML) add a one-directional
-     *   single-brace check on top of their flat multiset comparison: a `{name}`-shaped token present
-     *   in the translated value but absent from the source is reported as `extra`. Single-brace text
-     *   is ordinary literal content under these formats' default delimiters, so it is never required
-     *   to survive a translation, but inventing one is never a legitimate translation either.
-     *
-     * Absent for the remaining adapters, which are compared via `extractPlaceholders` plus a flat
-     * multiset check.
-     *
-     * @param sourceValue - The source value.
-     * @param targetValue - The translated value to check against it.
-     * @returns The merged placeholder-integrity result. Does not throw.
+     * Keys whose plural categories were generated for the target language rather than translated one
+     * by one. On a dry run, the forms a live run would generate: generation is a provider call of
+     * its own, so a dry run reports it rather than reporting nothing.
      */
-    comparePlaceholders?(sourceValue: string, targetValue: string): PlaceholderIntegrityResult;
-}
-
-/**
- * Outcome of resolving an adapter for a file. Structured, never thrown: an unresolvable file is a
- * status the caller branches on, not an exception.
- *
- * `resolved` carries the single {@link FormatAdapter} to use. `no-match` means nothing claimed the
- * file, and reports the formats that were tried (every registered format for a detection attempt, or
- * just the one requested when an explicit format was given). `ambiguous` means more than one adapter
- * claimed the file, which is routine since every JSON adapter claims `.json`; it reports the competing
- * candidates instead of guessing, and the caller resolves it by naming a format explicitly.
- */
-type AdapterResolution = {
-    /** Exactly one adapter claimed the file. */
-    readonly status: "resolved";
-    /** The adapter to read and write the file with. */
-    readonly adapter: FormatAdapter;
-} | {
-    /** No registered adapter claimed the file. */
-    readonly status: "no-match";
-    /** The file that could not be matched. */
-    readonly filePath: string;
+    readonly generated: readonly string[];
+    /** Keys not translated because the token budget was exhausted under `stop` behavior. */
+    readonly budgetWithheld: readonly string[];
+    /** Token usage for this locale. Absent when the provider does not report usage. */
+    readonly usage?: UsageSummary;
+    /** Provider and SDK notices raised while running this locale. Always present, possibly empty. */
+    readonly notices: readonly LocaleNotice[];
+    /** Translated keys flagged as worth a human look. The translations were still written. */
+    readonly needsReview: readonly NeedsReviewEntry[];
+    /** Keys left with no translation after the run, whatever the cause. */
+    readonly unfilled: readonly string[];
+    /** Unreadable rows from an imported handoff. Always empty for a {@link translate} run. */
+    readonly malformedRows: readonly MalformedRowReport[];
+    /** Repeated keys from an imported handoff. Always empty for a {@link translate} run. */
+    readonly duplicateKeys: readonly DuplicateKeyReport[];
     /**
-     * The formats that were tried: every registered format for a detection attempt, or just the
-     * one requested when an explicit format was given.
+     * Why this locale failed, when the failure came from a thrown error. The `code` is the failure's
+     * own code where it has one, and `LOCALE_FAILED` otherwise. Never carries a secret.
+     *
+     * Absent unless `status` is `failed`, but a `failed` locale does not always carry it: a locale
+     * whose every key was withheld by the integrity gate, a provider failure, or the token budget is
+     * `failed` with nothing thrown, so this stays undefined and the withheld keys are the account of
+     * what went wrong. Treat it as an optional detail on a failure, never as the failure test.
      */
-    readonly triedFormats: readonly SupportedFormat[];
-} | {
-    /** More than one adapter claimed the file, so detection cannot choose between them. */
-    readonly status: "ambiguous";
-    /** The file that several adapters claimed. */
-    readonly filePath: string;
-    /** The competing formats. Resolve the ambiguity by naming one of them explicitly. */
-    readonly candidates: readonly SupportedFormat[];
-};
-/** Options for {@link AdapterRegistry.resolve}: select a format explicitly, or aid detection. */
-interface ResolveOptions {
-    /** A leading content sample to aid detection. Ignored when `format` is given. */
-    readonly sample?: string;
-    /** Bypass detection and select this format explicitly. */
-    readonly format?: SupportedFormat;
+    readonly error?: {
+        /** The failure's own code where it had one, and `LOCALE_FAILED` otherwise. */
+        readonly code: string;
+        /** A human-readable description of the failure. Never contains a secret. */
+        readonly message: string;
+    };
 }
 /**
- * Holds the registered adapters and resolves one for a file. Open for extension: adapters attach
- * through {@link AdapterRegistry.register} without changing resolution logic, and resolution never
- * throws.
+ * The result of a whole run, returned by {@link translate}, {@link watch}, and
+ * {@link importWorkbook}.
+ *
+ * Per-locale outcomes are data, not exceptions: inspect `failed` and `partial` to decide an exit
+ * code rather than relying on the call to throw. Only whole-run failures, such as an invalid config
+ * or an unreadable source file, throw an {@link SdkError}.
  */
-declare class AdapterRegistry {
-    private readonly adapters;
+interface RunSummary {
+    /** True when the run computed everything but wrote nothing and called no provider. */
+    readonly dryRun: boolean;
     /**
-     * Register an adapter. Registration order is the order detection consults them, and a format may be
-     * registered more than once, in which case an explicit-format lookup takes the first.
-     *
-     * @param adapter - The adapter to add.
-     * @returns This registry, for chaining.
+     * The full per-locale account. A {@link translate} or {@link watch} run reports them in
+     * configured target order, whatever order a `locales` subset was given in and whatever order
+     * concurrent locales finished in. An {@link importWorkbook} run does not: it reports them in the
+     * order the handoff yielded them, then appends the configured locales the handoff had nothing
+     * for. Match an entry on its `locale` rather than on its position.
      */
-    register(adapter: FormatAdapter): this;
-    private formats;
-    private resolveByFormat;
-    private resolveByDetection;
+    readonly locales: readonly LocaleSummary[];
+    /** Names of the locales whose status is `succeeded`. */
+    readonly succeeded: readonly string[];
     /**
-     * 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.
+     * Names of the locales whose status is `partial`: written to disk, but with keys still missing.
+     * Check this alongside `failed` before treating a run as clean. The CLI exits `1` on a partial
+     * locale for that reason.
      */
-    resolve(filePath: string, options?: ResolveOptions): AdapterResolution;
+    readonly partial: readonly string[];
+    /** Names of the locales whose status is `failed`. Check this before treating a run as clean. */
+    readonly failed: readonly string[];
+    /** Token usage summed across every locale. Absent when the provider does not report usage. */
+    readonly usage?: UsageSummary;
+    /** The token budget in force, present only when the config set one. */
+    readonly budget?: RunBudget;
+    /**
+     * What the run would have cost, present only when it was asked for a pre-run estimate. Always a
+     * dry run: an estimate constructs no provider and spends nothing.
+     */
+    readonly estimate?: RunEstimate;
 }
 
+/**
+ * Where a finished run stands against its token budget.
+ *
+ * - `within`: the run never reached its ceiling.
+ * - `stopped-before-ceiling`: under `stop`, a request was withheld because sending it would have
+ *   passed the ceiling, while the counted total was still below it.
+ * - `reached`: the counted total reached or passed the ceiling.
+ */
+type BudgetStanding = "within" | "stopped-before-ceiling" | "reached";
+/**
+ * Classifies a {@link RunBudget} into its {@link BudgetStanding}, so every surface that reports a
+ * budget tells a `stop` run halted short of its ceiling apart from one that actually reached it.
+ */
+declare function budgetStanding(budget: RunBudget): BudgetStanding;
+
 /** One locale's counts in a {@link CheckSummary}. */
 interface LocaleCheckSummary {
     /** The target locale these counts describe. */
@@ -1258,6 +2772,12 @@ interface LocaleCheckSummary {
     readonly upToDate: number;
     /** True when this locale has nothing missing and nothing stale. */
     readonly inSync: boolean;
+    /**
+     * Every source string this locale translates more than one way under different keys, present only
+     * when {@link CheckInput.consistency} is true (an empty array then means the locale is
+     * consistent). This is a report and nothing more: it never changes `inSync` or any count.
+     */
+    readonly inconsistencies?: readonly InconsistencyGroup[];
 }
 /** The result of {@link check}: per-locale counts plus one project-wide verdict. */
 interface CheckSummary {
@@ -1274,6 +2794,11 @@ interface CheckInput {
     readonly cwd?: string;
     /** Restrict the report to these target locales. Defaults to every configured target locale. */
     readonly locales?: readonly string[];
+    /**
+     * Also report, per locale, every source string translated more than one way under different keys
+     * (see {@link LocaleCheckSummary.inconsistencies}). Defaults to false.
+     */
+    readonly consistency?: boolean;
 }
 /** Injectable dependencies for {@link check}. Every field has a working default. */
 interface CheckDeps {
@@ -1294,6 +2819,16 @@ interface CheckDeps {
  *
  * Use {@link diff} instead when you need the key names rather than the counts.
  *
+ * With {@link CheckInput.consistency} set, each locale also lists the source strings it translates
+ * more than one way under different keys. Only keys that are up to date are compared, since a stale
+ * translation belongs to an older source text. Values are compared after Unicode NFC normalization,
+ * folding line endings, and trimming leading and trailing whitespace; internal whitespace and letter
+ * case count. Keys whose description, meaning, plural flag, or gettext `msgctxt` differ are never
+ * grouped, and neither are the different plural forms of one key: a format that stores each form
+ * under its own key (i18next, Apple `.stringsdict` and `.xcstrings`, Android, gettext) is compared
+ * per plural category or gettext `msgstr` index. The report never affects `inSync`, a count, or any
+ * file, and a translation identical to its own source is not a finding here.
+ *
  * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
  * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
  * locale and the resolved path. A caller that maps SDK codes should be ready for an unrecognized
@@ -1315,6 +2850,121 @@ interface CheckDeps {
  */
 declare function check(input: CheckInput, deps?: CheckDeps): Promise<CheckSummary>;
 
+/**
+ * Why an unused-key report could not be produced at all.
+ *
+ * - `EXTRACT_NOT_CONFIGURED`: the config carries no `extract` block, so there is no source to scan.
+ * - `EXTRACT_FS_UNSUPPORTED`: the supplied file system implements no `readDirectory`.
+ * - `FRAMEWORK_NOT_MODELED`: the configured format is loaded by a runtime (next-intl, Vue I18n, or
+ *   ngx-translate) whose key lookups the i18next source scan does not model.
+ * - `NO_SOURCE_FILES`: there is no source file under the configured roots at all.
+ * - `NO_REFERENCES_FOUND`: the scanned files name no translation key and hold no dynamic key site,
+ *   while the catalog is not empty, so the scan most likely looked at the wrong code.
+ */
+type UnusedKeysNotRunReason = "EXTRACT_NOT_CONFIGURED" | "EXTRACT_FS_UNSUPPORTED" | "FRAMEWORK_NOT_MODELED" | "NO_SOURCE_FILES" | "NO_REFERENCES_FOUND";
+/**
+ * Why a completed scan cannot rule a key unused with confidence.
+ *
+ * - `dynamic-keys`: a key argument has no static part (`t(key)`, a template literal with no static
+ *   head, a concatenation), so any catalog key could be the one it reaches.
+ * - `dynamic-key-prefix`: a `keyPrefix` option or a `getFixedT` prefix argument is not a static
+ *   string, so every key called under it is unknown.
+ * - `trans-without-key`: a `Trans` element carries no static `i18nKey`.
+ * - `aliased-translate-function`: the translate function is assigned somewhere its calls cannot be
+ *   followed, such as an object property.
+ * - `translate-function-escapes`: a translate function bound from a recognised source appears
+ *   somewhere other than a direct call, its own binding, a local alias, or the `t` attribute of a
+ *   `Trans` or `Translation` element, so code the scan cannot follow may call it with any key.
+ * - `unrecognised-translate-source`: `useTranslation`, `withTranslation`, `getFixedT`, a
+ *   `Translation` render prop, a member `t`, or a `t` import is used in a shape the scan does not
+ *   recognise, so the prefix and keys of the function it yields are unknown.
+ * - `template-files-not-scanned`: the roots hold template files (`.vue`, `.svelte`, `.html`, and
+ *   similar) the scan does not read.
+ * - `incomplete-scan`: a file or directory could not be read to its end.
+ */
+type UnusedKeysUnreliableReason = "dynamic-keys" | "dynamic-key-prefix" | "trans-without-key" | "aliased-translate-function" | "translate-function-escapes" | "unrecognised-translate-source" | "template-files-not-scanned" | "incomplete-scan";
+/** One place that makes an unused-key report unreliable. */
+interface UnusedKeysSite {
+    /** The file or directory, relative to the run's working directory, with forward slashes. */
+    readonly file: string;
+    /** The one-based line, when the reason points at a line. */
+    readonly line?: number;
+    /** For `incomplete-scan`, why the file was skipped (for example `too-large`). */
+    readonly detail?: string;
+}
+/** One reason an unused-key report is unreliable, with the places that caused it. */
+interface UnusedKeysUnreliability {
+    /** The stable reason code. */
+    readonly reason: UnusedKeysUnreliableReason;
+    /** How many places caused it. For template files this can exceed the listed `sites`. */
+    readonly count: number;
+    /**
+     * The places, deduplicated on file and line. Every place is listed, except template files, which
+     * are capped at the first 20.
+     */
+    readonly sites: readonly UnusedKeysSite[];
+}
+/**
+ * A source-catalog key in an unused-key report. `key` is the key as a person and the source spell
+ * it, with the format's internal encoding undone (`Welcome. Enjoy` rather than `Welcome\. Enjoy`,
+ * a gettext `msgctxt` shown as `context|msgid`); `extract.unused.ignore` patterns match it.
+ * `catalogKey` is the key exactly as the catalog adapter and the per-locale `orphaned` lists spell
+ * it, for a tool that needs to address the entry.
+ */
+interface UnusedKey {
+    /** The decoded key, as shown to people and matched by `extract.unused.ignore`. */
+    readonly key: string;
+    /** The key as the catalog adapter encodes it. */
+    readonly catalogKey: string;
+}
+/** A source-catalog key no static reference names, but a template-literal key could still reach. */
+interface PossiblyDynamicKey extends UnusedKey {
+    /** The static head of the template-literal key that could reach it. */
+    readonly prefix: string;
+}
+/** A template-literal key argument with a static head, located in the source. */
+interface UnusedKeysPrefixSite extends SourceLocation {
+    /** The static head every key the site can reach starts with. */
+    readonly prefix: string;
+}
+/** An unused-key report produced from a source scan. */
+interface UnusedKeysScan {
+    /**
+     * `complete` when nothing in the scan casts doubt on the verdict; `unreliable` when
+     * {@link UnusedKeysScan.unreliableBecause} is not empty, so a listed key may still be in use.
+     */
+    readonly status: "complete" | "unreliable";
+    /** Every reason the verdict cannot be trusted. Empty exactly when `status` is `complete`. */
+    readonly unreliableBecause: readonly UnusedKeysUnreliability[];
+    /** How many source files were read and scanned. */
+    readonly scannedFiles: number;
+    /** Source-catalog keys no scanned reference names, in catalog order. */
+    readonly unused: readonly UnusedKey[];
+    /**
+     * Unreferenced source-catalog keys a template-literal key with a static head could reach, in
+     * catalog order. They are listed apart from `unused` and never fail a run.
+     */
+    readonly possiblyDynamic: readonly PossiblyDynamicKey[];
+    /** Unreferenced source-catalog keys matched by `extract.unused.ignore`, in catalog order. */
+    readonly ignored: readonly UnusedKey[];
+    /** The template-literal key sites behind `possiblyDynamic`. */
+    readonly dynamicPrefixes: readonly UnusedKeysPrefixSite[];
+}
+/**
+ * The source-locale catalog keys that nothing in the scanned source references. Distinct from the
+ * per-locale `orphaned` lists, which compare a target locale against the source catalog.
+ */
+type UnusedKeysReport = UnusedKeysNotRun | UnusedKeysScan;
+/** An unused-key report that could not run. It carries no key list, so nothing is misreported. */
+interface UnusedKeysNotRun {
+    /** Always `not-run`. */
+    readonly status: "not-run";
+    /** The stable reason code. Branch on this, not on the message. */
+    readonly reason: UnusedKeysNotRunReason;
+    /** A human-readable explanation. */
+    readonly message: string;
+}
+
 /** One locale's pending work in a {@link DiffSummary}, as key names rather than counts. */
 interface LocaleDiff {
     /** The target locale this entry describes. */
@@ -1340,22 +2990,45 @@ interface DiffSummary {
     readonly hasPendingChanges: boolean;
     /** Per-locale key lists, in configured target order. */
     readonly locales: readonly LocaleDiff[];
+    /**
+     * Source-catalog keys nothing in the scanned application source references. Present only when
+     * {@link DiffInput.unused} was set. It is a separate axis from each locale's `orphaned` list and
+     * never flips {@link DiffSummary.hasPendingChanges}.
+     */
+    readonly unused?: UnusedKeysReport;
 }
 /** Input for {@link diff}. */
 interface DiffInput {
     /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
+    /**
+     * Directory the `files.pattern` is resolved against. Defaults to the process working directory.
+     */
     readonly cwd?: string;
     /** Restrict the report to these target locales. Defaults to every configured target locale. */
     readonly locales?: readonly string[];
+    /**
+     * Also scan the application source configured in the `extract` block and report the
+     * source-catalog keys nothing references, as {@link DiffSummary.unused}. Off by default.
+     */
+    readonly unused?: boolean;
 }
 /** Injectable dependencies for {@link diff}. Every field has a working default. */
 interface DiffDeps {
-    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
+    /**
+     * Format-adapter registry to resolve the configured format. Defaults to the built-in registry.
+     */
     readonly adapterRegistry?: AdapterRegistry;
-    /** File-system port. Defaults to the real file system. */
+    /**
+     * File-system port. Defaults to the real file system. The unused-key scan needs its
+     * `readDirectory` member and reports its absence as `EXTRACT_FS_UNSUPPORTED`.
+     */
     readonly fs?: SdkFs;
+    /**
+     * Extractor factory for the unused-key scan. Defaults to the built-in table keyed by the
+     * configured framework.
+     */
+    readonly createExtractor?: (framework: SourceFramework) => SourceExtractor;
 }
 /**
  * Reports the per-locale drift between the source and each target locale as key names, without
@@ -1366,19 +3039,34 @@ interface DiffDeps {
  * since the key was last translated rather than merely that the two strings differ. Orphaned keys
  * are reported but never removed here; pruning happens only in {@link translate}.
  *
+ * With `unused` set, it also scans the application source named by the config's `extract` block
+ * and reports, in {@link DiffSummary.unused}, the source-catalog keys no static reference names.
+ * The scan models the i18next runtime: `t` calls and their aliases, `keyPrefix` and `getFixedT`
+ * prefixes, `Trans` keys, namespace-qualified keys, and the plural and context variants of a
+ * referenced key. It is read-only like the rest of `diff`: it never removes, rewrites, or reorders
+ * a catalog, and it constructs no provider and reads no API key. Keys matched by
+ * `extract.unused.ignore` are listed as `ignored`, and keys a template-literal key with a static
+ * head could reach as `possiblyDynamic`, never as `unused`. The report is `complete` only when the
+ * scan can bound every key the source reaches; otherwise it is `unreliable` and names each reason
+ * with its sites, or `not-run` with a reason code and no key list at all when there is nothing
+ * trustworthy to judge by (no `extract` block, a format whose runtime is not modeled, no source
+ * file, or no reference anywhere in the scanned files).
+ *
  * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
  * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
  * locale and the resolved path. A caller that maps SDK codes should be ready for an unrecognized
  * error from a target file.
  *
- * @param input - The config and the optional locale filter.
- * @param deps - Optional adapter registry and file-system overrides.
- * @returns Per-locale missing, changed, and orphaned key lists.
+ * @param input - The config, the optional locale filter, and whether to report unused keys.
+ * @param deps - Optional adapter registry, file-system, and extractor-factory overrides.
+ * @returns Per-locale missing, changed, and orphaned key lists, plus the unused-key report when
+ *   asked for.
  *
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
  * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
  * cannot be combined, or a configured locale has no valid path spelling under that style.
- * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same
+ * path.
  * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
  * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
  * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
@@ -1396,8 +3084,11 @@ declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
  * - `api-key`: the environment variable the configured provider reads its key from is set.
  * - `source-file`: the source locale file exists at its resolved path, is a regular file, and
  *   parses under the configured format.
+ * - `untranslated-literals`: the application source configured in the `extract` block holds no
+ *   hardcoded user-facing string literal and no file the scan could not read. It runs only when
+ *   {@link DoctorInput.literals} is set.
  */
-type DoctorCheckId = "config" | "format-adapter" | "provider" | "api-key" | "source-file";
+type DoctorCheckId = "config" | "format-adapter" | "provider" | "api-key" | "source-file" | "untranslated-literals";
 /**
  * The verdict on one {@link DoctorCheck}. `skipped` is reported only for the checks that need a
  * loaded config when the `config` check itself failed, so a skipped check is never a problem of its
@@ -1423,8 +3114,18 @@ interface DoctorCheck {
 interface DoctorResult {
     /** True only when no check failed. This is the value a script should branch on. */
     readonly ok: boolean;
-    /** Every check, always in the same order, one entry per {@link DoctorCheckId}. */
+    /**
+     * Every check that ran, always in the same order. A setup run has one entry per setup check:
+     * `config`, `format-adapter`, `provider`, `api-key`, and `source-file`. A literal run
+     * ({@link DoctorInput.literals}) has exactly two: `config` and `untranslated-literals`.
+     */
     readonly checks: readonly DoctorCheck[];
+    /**
+     * What the untranslated-literal scan found. Present only on a literal run whose scan actually
+     * ran; absent when the config could not be loaded, no `extract` block is configured, or the
+     * file system cannot list directories.
+     */
+    readonly literals?: LiteralScan;
 }
 /** Input for {@link doctor}. */
 interface DoctorInput {
@@ -1432,6 +3133,13 @@ interface DoctorInput {
     readonly cwd?: string;
     /** An explicit config file to validate, bypassing the search. A missing file is an error rather than a failed check. */
     readonly configPath?: string;
+    /**
+     * Run the untranslated-literal scan instead of the setup checks: the config is loaded, then the
+     * source roots of its `extract` block are scanned for hardcoded user-facing string literals. The
+     * provider, API-key, format, and source-file checks do not run, so no API key environment
+     * variable is looked at and a run with no key set can pass.
+     */
+    readonly literals?: boolean;
 }
 /** Injectable dependencies for {@link doctor}. Every field has a working default. */
 interface DoctorDeps {
@@ -1476,7 +3184,18 @@ interface DoctorDeps {
  * verdict they could not reach, and {@link DoctorResult.ok} is false because the config check
  * itself failed.
  *
- * @param input - The working directory and an optional explicit config path.
+ * With `literals: true` it runs the untranslated-literal scan instead of the setup checks. The
+ * source roots of the config's `extract` block are read, never written, and every string literal
+ * or piece of JSX text that reads as user-facing text without going through a recognised
+ * translation call is returned in {@link DoctorResult.literals} with its file, line, column, and
+ * an excerpt of at most 80 characters. Literals held back by a `verbatra-ignore-next-line` or
+ * `verbatra-ignore-line` comment, or by `extract.literals.ignore`, are returned under `suppressed`
+ * rather than dropped. The check fails when anything was found or when a file could not be
+ * scanned, so a partial scan is never reported as clean. No provider is constructed and no API key
+ * environment variable is read.
+ *
+ * @param input - The working directory, an optional explicit config path, and whether to run the
+ *   untranslated-literal scan instead of the setup checks.
  * @param deps - Optional adapter registry, file-system, and config-loader overrides.
  * @returns Every check with its verdict, and the project-wide `ok` verdict.
  *
@@ -1497,7 +3216,7 @@ interface DoctorDeps {
 declare function doctor(input?: DoctorInput, deps?: DoctorDeps): Promise<DoctorResult>;
 
 /**
- * Why a candidate translation was refused before it could be written. The same gate guards
+ * Every reason a candidate translation can be refused before it is written. The same gate guards
  * {@link editEntry} and {@link retranslateEntry}, so a hand-typed value and a provider-produced one
  * are held to identical standards.
  *
@@ -1508,6 +3227,48 @@ declare function doctor(input?: DoctorInput, deps?: DoctorDeps): Promise<DoctorR
  *   interpolation would break at runtime. For the double-brace formats (i18next, ngx-translate, and
  *   YAML) this also covers a single-brace `{name}`-shaped token the candidate invented and the
  *   source never had, which is a fabrication whichever interpolation delimiters the project uses.
+ * - `markup`: the candidate does not carry the same inline HTML or XML tags as the source, or it
+ *   carries them unbalanced, mis-nested, or newly nested inside another tag of the same name, any
+ *   of which breaks the rendering of the string the way a dropped placeholder breaks its
+ *   interpolation, or it would make an HTML parser create markup the source does not have. Tags
+ *   are read the way an HTML parser reads them (quoted attribute values may contain `>`, and the
+ *   content of a raw text element such as `script`, `style`, `title` or `textarea` is text up to
+ *   its closing tag) and compared as a multiset of names plus attribute names, so a different word
+ *   order and a translated attribute value are both accepted, and the two spellings of a void
+ *   element (`<br>` and `<br/>`) are one tag. Tag names are compared exactly, while the HTML void
+ *   elements are recognised as needing no closing tag in any case spelling. An unclosed bracketed
+ *   word that is only a name of letters, digits, hyphens, and underscores, such as `<Enter>`, is
+ *   set aside on both sides and counted like a tag once the source carries tags; where the source
+ *   has no tags, the candidate is refused for a closing tag with no opening tag, an unclosed tag
+ *   that carries anything beyond its name, any closed pair, void, or self-closing tag, and a
+ *   bracketed word the source does not carry that names a standard HTML element, `image`, or a
+ *   custom element (any name with a hyphen). Comments, CDATA sections, declarations, processing
+ *   instructions, and a `</` not followed by a letter end where an HTML parser ends them and are
+ *   compared as a multiset of their text, so one the candidate adds, drops, or rewrites is
+ *   refused. A source whose own tags are not well formed is still compared as a multiset, and no
+ *   source is too large to compare; a candidate is refused once it carries more than twice its
+ *   source's tags and constructs, or more than 256 for a smaller source. Also refused: a tag the
+ *   candidate never finishes when the source finishes all of its own; a `javascript:`,
+ *   `vbscript:`, or `data:` scheme in a URL attribute value, read after decoding character
+ *   references, unless the source carries that exact value on the same tag and attribute; a URL
+ *   in such a value whose scheme and authority no source value of the same tag and attribute has,
+ *   or a relative URL made absolute; a changed value of `meta` `http-equiv` or `content`, `script`
+ *   `type`, `nomodule`, `integrity` or `crossorigin`, `link` `rel`, `as`, `integrity`,
+ *   `crossorigin` or `type`, `base` `target`, SVG animation `attributeName` or `attributeType`,
+ *   `iframe` `sandbox`, `allow` or `allowfullscreen`, `form` `method`, `enctype` or `target`, or
+ *   any `style`, `srcdoc` or event handler; any change to the content of a `script`, `style`,
+ *   `iframe`, `noembed`, `noframes`, `noscript`, `xmp`, or `plaintext` element (`title` and
+ *   `textarea` content may be translated); and, unless the candidate is the source unchanged,
+ *   raw text an HTML parser can read two ways (a `script` whose content opens `<!--`, a `noscript`
+ *   whose content holds a `<`, a raw text element whose content holds a `<` after an `svg`,
+ *   `math`, or `select` tag) or a CDATA section or `image` tag in a value that opens `svg`, `math`,
+ *   or `select`. The check stands down per tag: a tag the format already reports as a placeholder
+ *   (an XLIFF inline element, a next-intl or ARB ICU rich-text tag) is left to the `placeholder`
+ *   reason together with as many closing tags as it has openings, while one the candidate leaves
+ *   unclosed, one that no longer nests with the other tags as in the source, and one the source
+ *   carries only as text are still refused, and any other tag in the same value is still
+ *   compared, including a second spelling of the same name. The refusal's `details` names the
+ *   offending tags.
  * - `icu`: the candidate is not a valid ICU message under the configured format's adapter.
  * - `degenerate`: the candidate collapsed into runaway output rather than a translation. Two shapes
  *   are detected: the candidate is at least twelve times the length of a source of meaningful
@@ -1515,8 +3276,25 @@ declare function doctor(input?: DoctorInput, deps?: DoctorDeps): Promise<DoctorR
  *   echo of the source is not degenerate by this rule; it surfaces as the `EQUALS_SOURCE` review
  *   reason instead, which flags rather than refuses.
  * - `empty`: the source has text but the candidate is blank, which would silently erase a string.
+ *
+ * This tuple is the single source of truth for the set. {@link IntegrityGateReason} is derived from
+ * it, so build any runtime validator or exhaustive lookup from this value rather than retyping the
+ * members; a hand-copied list silently falls behind the next addition.
+ *
+ * @example
+ * ```ts
+ * import { INTEGRITY_GATE_REASONS } from "@verbatra/sdk";
+ * import { z } from "zod";
+ *
+ * const reasonSchema = z.enum(INTEGRITY_GATE_REASONS);
+ * ```
+ */
+declare const INTEGRITY_GATE_REASONS: readonly ["placeholder", "markup", "icu", "degenerate", "empty"];
+/**
+ * One of {@link INTEGRITY_GATE_REASONS}. The union is derived from that tuple rather than written
+ * out again, so a reason can only be added in one place.
  */
-type IntegrityGateReason = "placeholder" | "icu" | "degenerate" | "empty";
+type IntegrityGateReason = (typeof INTEGRITY_GATE_REASONS)[number];
 
 /** Input for {@link editEntry}. */
 interface EditEntryInput {
@@ -1553,6 +3331,14 @@ type EditEntryResult = {
     readonly accepted: false;
     /** Which integrity rule the value broke. */
     readonly reason: IntegrityGateReason;
+    /**
+     * The specific tags behind a `markup` refusal, each prefixed with `-` for one the source had
+     * and the candidate dropped or `+` for one the candidate invented. A candidate carrying more
+     * than twice its source's inline tags and constructs is named as `+more than N inline tags`
+     * instead, where N is at least 256. Absent when no single tag is at fault, such as markup
+     * that came back mis-nested, and absent for every other reason.
+     */
+    readonly details?: readonly string[];
     /** The rejected value, echoed back so a UI can show what was refused. */
     readonly value: string;
 };
@@ -1606,6 +3392,242 @@ type EditEntryResult = {
  */
 declare function editEntry(input: EditEntryInput, deps?: EditEntryDeps): Promise<EditEntryResult>;
 
+/** One key the run added to the source catalog, and the call site it was found at. */
+interface AddedKey {
+    /** The key as written at the call site. */
+    readonly key: string;
+    /** The value written into the catalog: the call site's default, or the empty string when it had none. */
+    readonly value: string;
+    /** The source file the key was found in, relative to the run's working directory. */
+    readonly file: string;
+    /** The one-based line the key was found on. */
+    readonly line: number;
+}
+/**
+ * The result of {@link extract}. Everything it reports is a key, a value, or a file and line: a
+ * source file's contents never travel in it.
+ */
+interface ExtractResult {
+    /** The source locale file the run targeted, relative to the run's working directory. */
+    readonly sourcePath: string;
+    /** How many source files were read and scanned. */
+    readonly scannedFiles: number;
+    /** Keys that were not in the catalog and were added, in the order they were found. */
+    readonly added: readonly AddedKey[];
+    /** How many of the keys found were already in the catalog and were left untouched. */
+    readonly existingKeys: number;
+    /** Added keys whose call site carried no default, so they were written with an empty value. */
+    readonly withoutDefault: readonly string[];
+    /** Call sites whose key argument was not a static string, reported rather than guessed at. */
+    readonly dynamic: readonly SourceLocation[];
+    /** Keys found twice with two different default values. Neither value is written. */
+    readonly conflicts: readonly KeyConflict[];
+    /** Files and directories the scan could not read, which never abort the run. */
+    readonly diagnostics: readonly ScanDiagnostic[];
+    /** Whether the source catalog was actually written. False for a dry run and for a run that added nothing. */
+    readonly written: boolean;
+    /** Whether this was a dry run. */
+    readonly dryRun: boolean;
+}
+/** Input for {@link extract}. */
+interface ExtractInput {
+    /** A resolved config whose `extract` block names the framework and the source roots. */
+    readonly config: VerbatraConfig;
+    /** Directory the roots and locale paths are resolved against. Defaults to the process working directory. */
+    readonly cwd?: string;
+    /** Report what would be added without writing anything. */
+    readonly dryRun?: boolean;
+}
+/** Injectable dependencies for {@link extract}. Every field has a working default. */
+interface ExtractDeps {
+    /** Format-adapter registry to resolve the configured format against. Defaults to the built-in registry. */
+    readonly adapterRegistry?: AdapterRegistry;
+    /**
+     * File-system port. It backs both the source scan and the catalog write, so its `readDirectory`
+     * member must be implemented. Defaults to the real file system.
+     */
+    readonly fs?: SdkFs;
+    /** Extractor factory. Defaults to the built-in table keyed by the configured framework. */
+    readonly createExtractor?: (framework: SourceFramework) => SourceExtractor;
+}
+/**
+ * Scans a project's own source for translation call sites and merges what it finds into the source
+ * locale catalog. It is the one entry point that reads application code rather than a locale file,
+ * which is what makes verbatra usable on a project that has no catalog yet.
+ *
+ * It spends nothing: no provider is constructed, no API key environment variable is read, and no
+ * network request is made. A run with no key set succeeds.
+ *
+ * Only the source locale file is ever written, and only keys that are genuinely new are added: a
+ * key already in the catalog keeps its value exactly as it stands, so an editorial fix is never
+ * reverted by a stale default left at a call site. A key in the catalog that no call site mentions
+ * is left alone. A run that finds nothing new writes nothing at all, so it leaves the file
+ * byte-identical and its modification time untouched.
+ *
+ * Everything the scan cannot resolve is reported as data rather than thrown. A call site whose key
+ * argument is not a static string is reported in `dynamic` and never written with a guessed key; a
+ * key found twice with two different defaults is reported in `conflicts` and neither value is
+ * written; a file or directory that cannot be read is reported in `diagnostics` and the scan
+ * carries on. The result never carries a source file's contents, only keys, values, and locations.
+ *
+ * @param input - The config (whose `extract` block names the framework and roots), the working
+ *   directory, and whether this is a dry run.
+ * @param deps - Optional adapter registry, file-system, and extractor-factory overrides.
+ * @returns What was added, what was already there, and everything the scan could not resolve.
+ *
+ * @throws {@link SdkError} `EXTRACT_NOT_CONFIGURED`: the config carries no `extract` block.
+ * @throws {@link SdkError} `EXTRACT_FS_UNSUPPORTED`: the supplied `deps.fs` implements no
+ * `readDirectory`, so no source file can be discovered.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `SOURCE_INVALID`: a source catalog exists but could not be parsed.
+ * @throws {@link SdkError} `SOURCE_UNWRITABLE`: the source catalog could not be written. The
+ * `xliff` and `apple-xcstrings` formats reach this when no catalog exists yet: neither is created
+ * from nothing, here or anywhere else in verbatra.
+ *
+ * @example
+ * ```ts
+ * import { extract, loadConfig } from "@verbatra/sdk";
+ *
+ * const config = await loadConfig();
+ * const result = await extract({ config, dryRun: true });
+ * console.log(`${result.added.length} new keys, ${result.dynamic.length} dynamic call sites`);
+ * ```
+ */
+declare function extract(input: ExtractInput, deps?: ExtractDeps): Promise<ExtractResult>;
+
+/** Why verbatra declined to describe a message's arguments rather than guessing at them. */
+type UnresolvedArgumentReason = "invalid-message-syntax" | "mixed-argument-styles" | "argument-index-out-of-range";
+
+/**
+ * Where {@link generateTypes} writes its declaration when the caller names no path: a `.d.ts` at
+ * the root of the working directory. The file is a checked-in artifact, not a local scratch file:
+ * it belongs in version control so a consumer type-checks against it without running verbatra
+ * first, and so `check` mode has a committed file to compare against.
+ */
+declare const DEFAULT_TYPES_PATH = "verbatra-types.d.ts";
+/** One key whose arguments verbatra declined to describe, and why. */
+interface UnresolvedMessage {
+    /** The key, which is still declared, with arguments nothing is claimed about. */
+    readonly key: string;
+    /** Why the arguments could not be determined. */
+    readonly reason: UnresolvedArgumentReason;
+}
+/** Input for {@link generateTypes}. */
+interface GenerateTypesInput {
+    /** The resolved project config, normally from {@link loadConfig}. */
+    readonly config: VerbatraConfig;
+    /** Directory the `files.pattern` and the output path are resolved against. Defaults to the process working directory. */
+    readonly cwd?: string;
+    /**
+     * Where to write the declaration, relative to `cwd`. Defaults to {@link DEFAULT_TYPES_PATH}.
+     * Refused with `TYPES_OUTPUT_CONFLICT`, before anything is read or written, when it names no
+     * file, is absolute, climbs out of `cwd`, does not end in `.ts`, `.mts` or `.cts`, or names a
+     * configured locale file, the lock file, the translation-memory cache, a file verbatra searches
+     * for its configuration, or the {@link GenerateTypesInput.configPath} file. Names are compared
+     * case-insensitively. A generating run also refuses to replace an existing file there unless
+     * that file begins with the header line verbatra writes, after any leading byte order mark and
+     * blank lines, and refuses one too large to verify.
+     */
+    readonly out?: string;
+    /**
+     * The configuration file `config` was loaded from, absolute or relative to `cwd`. It is refused
+     * as the output path even when its name is not one verbatra searches for.
+     */
+    readonly configPath?: string;
+    /**
+     * Compare instead of writing. The run reports whether the file on disk matches what a fresh
+     * generation would produce and leaves every file untouched.
+     */
+    readonly check?: boolean;
+}
+/** Injectable dependencies for {@link generateTypes}. Every field has a working default. */
+interface GenerateTypesDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
+    readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
+    readonly fs?: SdkFs;
+}
+/** The result of {@link generateTypes}: what was declared, and whether the file on disk matched. */
+interface GenerateTypesResult {
+    /** Absolute path of the declaration file. */
+    readonly path: string;
+    /** The source catalog the declaration was built from, relative to the working directory. */
+    readonly sourcePath: string;
+    /** How many keys the declaration carries. */
+    readonly keys: number;
+    /**
+     * How many of those keys take at least one argument verbatra could determine. A key listed in
+     * {@link GenerateTypesResult.unresolved} is not counted here.
+     */
+    readonly withArguments: number;
+    /** Keys that are declared but whose arguments could not be determined, and why. */
+    readonly unresolved: readonly UnresolvedMessage[];
+    /** Keys the adapter reported as excluded from translation, which are never declared. */
+    readonly excluded: readonly string[];
+    /** Keys the adapter marked as carrying plural forms. Each sibling is declared on its own. */
+    readonly plural: readonly string[];
+    /** Whether the declaration file was written. Always false in `check` mode. */
+    readonly written: boolean;
+    /** Whether the file on disk differed from the freshly generated declaration when the run started. */
+    readonly stale: boolean;
+    /** Whether this was a `check` run. */
+    readonly check: boolean;
+}
+/**
+ * Generates a TypeScript declaration for a project's source catalog: a union of every key it holds
+ * and, per key, the arguments its message interpolates. A consumer that types its translation
+ * function against it turns a misspelled key and a missing interpolation argument into compile
+ * errors instead of runtime lookup failures.
+ *
+ * It reads one file (the source locale catalog) and writes one file (the declaration). It
+ * constructs no provider, reads no API key and makes no network request, so it runs on a fresh
+ * checkout before any key exists.
+ *
+ * The keys are exactly what the format adapter produced when reading the catalog, in document
+ * order, so two runs over an unchanged catalog write byte-identical bytes. Arguments come from the
+ * placeholder tokens the adapter extracted, except for the ICU message formats (`next-intl-json`
+ * and `arb`): there each message is analysed with the same ICU parser the adapter uses, so an
+ * argument that only some `select` or `plural` branches use is still declared, as optional. Keys
+ * are emitted as quoted string literals, so a key carrying a dot, a reserved word, a leading digit,
+ * a quote, or nothing at all is declared verbatim rather than dropped or re-split.
+ *
+ * What it will not claim is as important as what it will. A message whose placeholders name their
+ * arguments gets an object shape; one whose placeholders are numbered or anonymous gets a readonly
+ * tuple; one that takes nothing gets a shape that makes passing an argument a type error. A
+ * message whose syntax the adapter reported as invalid, and one that appears to name and number
+ * its arguments at once, are declared with {@link GenerateTypesResult.unresolved} recording why,
+ * rather than being silently declared as taking nothing. Argument types come only from what the
+ * catalog actually records: `number` where the format annotated one, and a `string | number` alias
+ * everywhere else, never a permissive `any`. A name used with several types is declared as the
+ * union of what each use accepts.
+ *
+ * With `check` set, nothing is written: the run reports whether the committed file still matches
+ * what a fresh generation would produce, which is the shape a CI gate wants.
+ *
+ * @param input - The config, the output path, and whether to check rather than write.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns What was declared, and whether the file on disk matched.
+ *
+ * @example
+ * ```ts
+ * const result = await generateTypes({ config });
+ * console.log(`${result.keys} keys declared in ${result.path}`);
+ * ```
+ *
+ * @throws {@link SdkError} `TYPES_OUTPUT_CONFLICT`: the output path is refused (see
+ * {@link GenerateTypesInput.out} for the full set), or a generating run found a file there that
+ * does not begin with the header verbatra writes.
+ * @throws {@link SdkError} `TYPES_UNWRITABLE`: the declaration file could not be written.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same
+ * path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ */
+declare function generateTypes(input: GenerateTypesInput, deps?: GenerateTypesDeps): Promise<GenerateTypesResult>;
+
 /** One key's placeholder and ICU verdict in a {@link LocaleKeyIntegrity} report. */
 interface KeyIntegrityEntry {
     /** The key this verdict describes. */
@@ -1620,6 +3642,20 @@ interface KeyIntegrityEntry {
     readonly extra: readonly string[];
     /** True when the translation parses as a valid ICU message under the configured format. */
     readonly icuValid: boolean;
+    /**
+     * True when the translation carries the source's inline HTML or XML tags, well formed. Compared
+     * exactly as the write-time gate compares them, so a value already on disk is judged by the same
+     * rule as one about to be written.
+     */
+    readonly markupMatches: boolean;
+    /**
+     * The tags behind a `markupMatches: false` verdict, each prefixed with `-` for one the source has
+     * and the translation lacks or `+` for one the translation added, or `+more than N inline tags`
+     * for a translation carrying more than twice its source's inline tags and constructs (N is at
+     * least 256). Empty when the markup matches, and empty when no single tag is at fault because
+     * the translation's markup is structurally broken.
+     */
+    readonly markupDetails: readonly string[];
 }
 /** One locale's per-key integrity verdicts. */
 interface LocaleKeyIntegrity {
@@ -1655,9 +3691,13 @@ interface KeyIntegrityDeps {
  * edit may have just invalidated. Only keys present in both the source and the target are judged,
  * since a missing translation has no placeholders to compare.
  *
- * This is the read-only counterpart to the gate that {@link editEntry} and
- * {@link retranslateEntry} enforce at write time, and the data behind a review dashboard's
- * per-key integrity indicator.
+ * This is the read-only counterpart to the placeholder, ICU and inline-markup checks the gate that
+ * {@link editEntry} and {@link retranslateEntry} enforce at write time, and the data behind a
+ * review dashboard's per-key integrity indicator. Reporting markup here is what makes drift that
+ * predates the gate visible at all: a translation written before the check existed, edited outside
+ * verbatra, or produced by a path that never crossed the gate is judged here by the same rule.
+ * Emptiness and degeneracy are deliberately not reported: both describe a candidate that was
+ * refused rather than a state a stored translation can usefully be in.
  *
  * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
  * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
@@ -1808,7 +3848,91 @@ interface LocaleSnapshotDelta {
  * @param current - The later snapshot.
  * @returns The added, changed, and removed key counts.
  */
-declare function diffLocaleSnapshots(previous: LocaleFileSnapshot, current: LocaleFileSnapshot): LocaleSnapshotDelta;
+declare function diffLocaleSnapshots(previous: LocaleFileSnapshot, current: LocaleFileSnapshot): LocaleSnapshotDelta;
+
+/** One key's current source and target text within a {@link LocaleValues} map. */
+interface KeyValuePair {
+    /** The key's text in the source locale, absent when the key exists only in this target (orphaned). */
+    readonly source?: string;
+    /** The key's text in this target locale, absent when the key has not been translated yet. */
+    readonly target?: string;
+}
+/** One target locale's current source and target text for every key, as returned by {@link localeValues}. */
+interface LocaleValues {
+    /** The target locale these values were read for. */
+    readonly locale: string;
+    /**
+     * Source and target text per key, keyed by key name. Covers missing, changed, orphaned, and
+     * in-sync keys alike.
+     */
+    readonly values: Readonly<Record<string, KeyValuePair>>;
+}
+/** Input for {@link localeValues}. */
+interface LocaleValuesInput {
+    /** The resolved project config, normally from {@link loadConfig}. */
+    readonly config: VerbatraConfig;
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
+    readonly cwd?: string;
+    /** Restrict the report to these target locales. Defaults to every configured target locale. */
+    readonly locales?: readonly string[];
+}
+/** Injectable dependencies for {@link localeValues}. Every field has a working default. */
+interface LocaleValuesDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
+    readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
+    readonly fs?: SdkFs;
+}
+/**
+ * Reads every key's current source and target text, across every requested target locale, in one
+ * pass over the files already on disk. It writes nothing and calls no provider.
+ *
+ * This exists to back client-side search over translation content rather than key names alone: a
+ * caller holding the result in memory can match a query against source or target text without a
+ * further round trip per key. {@link keyValue} and {@link diff} answer narrower questions (one key,
+ * or key names only); this is the bulk read a caller would otherwise have to simulate with many
+ * {@link keyValue} calls.
+ *
+ * A key present in the source but not yet translated in a locale reports `target` as absent; a key
+ * present in a locale but no longer in the source (orphaned) reports `source` as absent instead. A
+ * target locale file that does not exist yet is treated as empty rather than as an error, so every
+ * key in a newly added locale reports `target` as absent.
+ *
+ * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
+ * locale and the resolved path. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file.
+ *
+ * @param input - The config and the optional locale filter.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns Per-locale source and target text, keyed by key name.
+ *
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
+ *
+ * @example
+ * ```ts
+ * import { loadConfig, localeValues } from "@verbatra/sdk";
+ *
+ * const config = await loadConfig();
+ * const locales = await localeValues({ config });
+ *
+ * const needle = "welcome";
+ * for (const locale of locales) {
+ *   for (const [key, pair] of Object.entries(locale.values)) {
+ *     if (pair.target?.toLowerCase().includes(needle)) {
+ *       console.log(`${locale.locale} ${key}: ${pair.target}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function localeValues(input: LocaleValuesInput, deps?: LocaleValuesDeps): Promise<readonly LocaleValues[]>;
 
 /** One locale's lock-file baseline and the drift measured against it. */
 interface LockLocaleState {
@@ -1887,313 +4011,229 @@ interface LockStateDeps {
  */
 declare function lockState(input: LockStateInput, deps?: LockStateDeps): Promise<LockStateResult>;
 
-/**
- * Builds a {@link TranslationProvider} from the config's `provider` block. Passed as
- * `deps.createProvider` to {@link translate}, {@link watch}, and {@link retranslateEntry}, it is the
- * seam for injecting a stub in a test or a provider the SDK does not ship.
- *
- * The default implementation dispatches on the provider ID and reads the API key from the
- * environment. A factory that throws is reported as `PROVIDER_CONSTRUCTION_FAILED`.
- */
-type CreateProvider = (config: ProviderConfig) => TranslationProvider;
-
-/** Input for {@link retranslateEntry}. */
-interface RetranslateEntryInput {
+/** Input for {@link pseudolocalize}. */
+interface PseudolocalizeInput {
     /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
     /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** The target locale to retranslate into. Must be a configured target locale. */
-    readonly locale: string;
-    /** The key to retranslate. Must exist in the source resource. */
-    readonly key: string;
+    /**
+     * The pseudolocale's BCP-47 code. Defaults to `en-XA`. It must not be the source locale or any
+     * configured target locale, so a pseudolocale can never stand in for a real translation.
+     */
+    readonly locale?: string;
+    /**
+     * Directory the pseudolocale file is written under, relative to `cwd`. Defaults to
+     * `.verbatra-local/pseudo`, which `verbatra init` already adds to `.gitignore`. The configured
+     * `files.pattern` is expanded inside it, so the file keeps the layout the application expects.
+     *
+     * It must name a directory inside `cwd`: an absolute path, one that climbs out with `..`, and
+     * `cwd` itself are all refused, as is any directory that already holds a configured locale file,
+     * so a generated pseudolocale never lands outside the project or beside the real translations
+     * where nothing ignores it.
+     */
+    readonly out?: string;
 }
-/** Injectable dependencies for {@link retranslateEntry}. Every field has a working default. */
-interface RetranslateEntryDeps {
+/** Injectable dependencies for {@link pseudolocalize}. Every field has a working default. */
+interface PseudolocalizeDeps {
     /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
-    /** Provider factory. Defaults to constructing the provider named in the config. */
-    readonly createProvider?: CreateProvider;
     /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
-/**
- * The outcome of {@link retranslateEntry}. As with {@link EditEntryResult}, a value refused by the
- * integrity gate is reported as data rather than thrown, because it is an expected outcome of
- * asking a provider for a fresh translation.
- */
-type RetranslateEntryResult = {
-    /** The provider's value passed the integrity gate and was written. */
-    readonly accepted: true;
-    /** The newly translated value now stored for the key. */
-    readonly value: string;
+/** The result of {@link pseudolocalize}: what was generated and where it landed. */
+interface PseudolocalizeResult {
+    /** The pseudolocale that was generated. */
+    readonly locale: string;
+    /** Absolute path of the file that was written, or would have been written on a changed run. */
+    readonly path: string;
+    /** How many source entries were processed. */
+    readonly entries: number;
+    /** How many entries carry a pseudolocalized value. */
+    readonly transformed: number;
     /**
-     * Quality signals the provider layer raised for this value, such as a length-ratio outlier or
-     * a value identical to the source. Empty when nothing was flagged. The value is written
-     * either way; these are advisory.
+     * Keys whose source value was copied verbatim because a pseudolocalized value would not have
+     * passed the same integrity gate a translation must pass. Never a failure: the entry is still
+     * present and still renders.
      */
-    readonly reviewReasons: readonly ReviewReasonCode[];
-} | {
-    /** The value was refused; nothing was written and the previous translation is intact. */
-    readonly accepted: false;
-    /** Which integrity rule the provider's value broke. */
-    readonly reason: IntegrityGateReason;
-    /** The rejected value, echoed back so a UI can show what was refused. */
-    readonly value: string;
-};
+    readonly copied: readonly string[];
+    /** False when the file on disk already matched, so nothing was rewritten. */
+    readonly written: boolean;
+}
 /**
- * Re-runs the configured provider for a single key and saves the result. This is the paid
- * counterpart to {@link editEntry}: it calls the provider and therefore spends tokens, which is why
- * a UI should gate it behind an explicit user action.
- *
- * The returned value goes through the same integrity gate as a full run, so a translation that
- * loses a placeholder or breaks ICU syntax is refused and nothing is written. Provider quality
- * signals are surfaced on an accepted result as `reviewReasons` rather than blocking the write.
- *
- * The locale's write lock is taken before the provider is called and held across it, covering the
- * whole read-translate-write cycle, so a slow provider keeps the lock for the length of its call
- * and a concurrent {@link translate} run on that locale waits. The lock is held for a refused
- * translation too, since the gate runs inside it. An accepted value then updates the lock-file
- * baseline and feeds the translation memory, so a later {@link translate} run sees the key as up
- * to date.
- *
- * Note that the target locale file surfaces the adapter's own error and code rather than a wrapped
- * {@link SdkError}, on the write as well as on the read, because only the source read is wrapped.
- * A malformed target file fails the read with a message naming the offending locale and the
- * resolved path. The write raises the adapter's error too, when the entries cannot be represented
- * in the configured format or the existing destination file cannot be read back to be updated in
- * place, and that error is re-thrown unchanged so its own code survives for a caller that maps
- * adapter codes to its own copy. A caller that maps SDK codes should be ready for an unrecognized
- * error from a target file on either path.
+ * Generates a pseudolocale from the source strings alone: every value is accented, expanded by
+ * roughly a third of its translatable length, and wrapped in `[` and `]` boundary markers, so a
+ * truncated or concatenated string is obvious on screen and an untranslated hardcoded string stands
+ * out for having escaped the transform.
+ *
+ * It constructs no provider, reads no API key and makes no network request, so it runs on a fresh
+ * checkout before any key exists or any budget is approved.
+ *
+ * Placeholders survive untouched in every syntax the shipped adapters recognise, and every
+ * generated value is held to the same integrity gate a provider's translation must pass. A value
+ * that would not pass it is copied from the source verbatim and reported in
+ * {@link PseudolocalizeResult.copied} rather than written in a broken form.
+ *
+ * The output is deliberately kept out of the project's real locale files: it is written under
+ * `.verbatra-local/pseudo` by default, which `verbatra init` already adds to `.gitignore`, and the
+ * pseudolocale is refused when it names a configured locale, when the output directory already
+ * holds a configured locale file, and when it is directed at the project root or outside the
+ * working directory. Because it lives outside `files.pattern`, {@link translate} never spends on it and
+ * {@link check} and {@link diff} never report it as drifted.
+ *
+ * The transform is deterministic, so a second run over unchanged source rewrites nothing and
+ * reports {@link PseudolocalizeResult.written} as false. For `xliff` and `apple-xcstrings`, whose
+ * writers only patch units already present in the destination, the output is re-copied from the
+ * source on every write, so a key added to the source after the first run still reaches the
+ * pseudolocale; a copied XLIFF has its target-language attribute rewritten to the pseudolocale, so
+ * the file never misdescribes what it holds.
+ *
+ * @param input - The config, the pseudolocale code, and the output directory.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns Where the pseudolocale landed, how many entries it carries, and whether it changed.
  *
- * @param input - The config, locale, and key to retranslate.
- * @param deps - Optional adapter registry, provider factory, and file-system overrides.
- * @returns Whether the new value was accepted, with review reasons or the rejection reason.
+ * @example
+ * ```ts
+ * const result = await pseudolocalize({ config });
+ * console.log(`${result.transformed} of ${result.entries} entries in ${result.path}`);
+ * ```
  *
+ * @throws {@link SdkError} `PSEUDO_OUTPUT_CONFLICT`: the pseudolocale names a configured locale, the
+ * output directory already holds a configured locale file, or it is not a relative path naming a
+ * directory inside `cwd`.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
- * @throws {@link SdkError} `UNKNOWN_LOCALE`: the requested locale is not a configured target locale.
  * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
- * cannot be combined, or the locale has no valid path spelling under that style.
+ * cannot be combined, or the pseudolocale has no valid path spelling under that style.
  * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
  * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
- * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
- * @throws {@link SdkError} `UNKNOWN_KEY`: the key is not present in the source resource.
- * @throws {@link SdkError} `PROVIDER_CONSTRUCTION_FAILED`: the provider could not be constructed,
- * most often because its API key environment variable is unset.
- * @throws {@link SdkError} `LOCK_CONTENDED`: the locale's write lock could not be acquired before
- * the timeout elapsed.
- * @throws {@link SdkError} `TARGET_UNWRITABLE`: the target locale file could not be written because
- * of a file-system failure. The message names the target file and the file-system code, never the
- * internal temporary file.
- * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
- * unsupported version.
- * @throws `AdapterError`: the adapter itself refused the target locale file, on the read because it
- * is malformed or on the write because the entries cannot be represented in the configured format.
- * Its own code is preserved rather than remapped onto an {@link SdkErrorCode}.
- * @throws `ProviderError` `INVALID_RESPONSE`: the provider returned no value for the key. Provider
- * transport and rate-limit failures propagate as `ProviderError` too, since a single-key call has
- * no per-locale summary to record them on.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed, or, for a
+ * format whose writer only patches an existing document (`xliff` and `apple-xcstrings`), the
+ * source file could not be copied to seed the output.
+ * @throws {@link SdkError} `TARGET_UNWRITABLE`: the pseudolocale file could not be written.
  */
-declare function retranslateEntry(input: RetranslateEntryInput, deps?: RetranslateEntryDeps): Promise<RetranslateEntryResult>;
+declare function pseudolocalize(input: PseudolocalizeInput, deps?: PseudolocalizeDeps): Promise<PseudolocalizeResult>;
 
 /**
- * Conditions the SDK itself reports on a locale, as opposed to the {@link ProviderNotice} codes a
- * provider raises. Each marks a run that completed but did something a caller may want to know
- * about.
- *
- * - `PLURAL_CATEGORIES_INCOMPLETE`: plural generation could not produce every category the target
- *   language requires, so the entry is written with the categories that were produced.
- * - `SUB_BATCH_FAILED`: one sub-batch of a locale failed while others succeeded. The locale is
- *   reported as `partial` rather than failed.
- * - `BLANK_ROW_BASELINE_RETAINED`: an imported handoff row was blank, so the existing translation
- *   and its lock-file baseline were kept rather than being erased.
- * - `BUDGET_TOKENS_EXCEEDED`: the configured token budget was passed. Under `warn` the run
- *   continues; under `stop` the remaining keys are withheld.
- * - `CACHE_VERSION_UNRECOGNIZED`: the translation memory is at a version this release does not
- *   understand, so it was ignored rather than trusted.
- */
-type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED" | "CACHE_VERSION_UNRECOGNIZED";
-/**
- * Token usage as reported by the provider. Absent when the provider does not report usage, which is
- * the case for machine-translation APIs such as DeepL that do not bill in tokens.
- */
-interface UsageSummary {
-    /** Tokens consumed by the prompts sent to the provider. */
-    readonly inputTokens: number;
-    /** Tokens consumed by the provider's responses. */
-    readonly outputTokens: number;
-}
-/**
- * What a run does when it passes its token budget: `warn` finishes the work and reports the
- * overrun, `stop` withholds the remaining keys.
- */
-type BudgetBehavior = "warn" | "stop";
-/** The token budget in force for a run, and how much of it was actually consumed. */
-interface RunBudget {
-    /** The configured ceiling, in tokens. */
-    readonly maxTokens: number;
-    /** Whether passing the ceiling warns or stops the run. */
-    readonly behavior: BudgetBehavior;
-    /**
-     * Whether the configured provider reports usage at all. When false the budget cannot be enforced,
-     * because there is nothing to count.
-     */
-    readonly supported: boolean;
-    /** Tokens consumed across the whole run so far. */
-    readonly tokensUsed: number;
-    /** True once `tokensUsed` passed `maxTokens`. */
-    readonly exceeded: boolean;
-}
-/** A condition the SDK reported on a locale. See {@link SdkNoticeCode}. */
-interface SdkNotice {
-    /** The stable notice code. Branch on this, not on the message. */
-    readonly code: SdkNoticeCode;
-    /** A human-readable description of the condition. */
-    readonly message: string;
-}
-/**
- * Any notice attached to a locale: either one the provider raised, such as a downgraded formality
- * or an ignored glossary, or one the SDK raised. Discriminate on `code`.
- */
-type LocaleNotice = ProviderNotice | SdkNotice;
-/**
- * A translated key the provider layer flagged as worth a human look. The translation was still
- * written; these are advisory quality signals, not rejections.
- */
-interface NeedsReviewEntry {
-    /** The key that was flagged. */
-    readonly key: string;
-    /** Why it was flagged. A key can carry more than one reason. */
-    readonly reasons: readonly ReviewReasonCode[];
-}
-/** A row of an imported handoff that could not be read. Reported rather than aborting the import. */
-interface MalformedRowReport {
-    /** The row's 1-based index within its sheet or file. */
-    readonly row: number;
-    /**
-     * The 1-based physical line in the source file, for delimited formats where a quoted value can
-     * span several lines. Absent for `.xlsx`, which has rows but no lines.
-     */
-    readonly line?: number;
-    /** The column whose value was missing or unusable. */
-    readonly column: string;
-}
-/**
- * A key that appeared more than once in an imported handoff. The first occurrence wins and the rest
- * are reported here, so a translator who duplicated a row learns which value was actually used.
- */
-interface DuplicateKeyReport {
-    /** The key that appeared more than once. */
-    readonly key: string;
-    /** The 1-based row index of the ignored occurrence. */
-    readonly row: number;
-    /** The 1-based physical line of the ignored occurrence, for delimited formats. Absent for `.xlsx`. */
-    readonly line?: number;
-}
-/**
- * Everything that happened for one locale during a run. The key lists are disjoint accounts of what
- * became of each key, so a caller can reconstruct the whole run without re-reading any file.
+ * Builds a {@link TranslationProvider} from the config's `provider` block. Passed as
+ * `deps.createProvider` to {@link translate}, {@link watch}, and {@link retranslateEntry}, it is the
+ * seam for injecting a stub in a test or a provider the SDK does not ship.
  *
- * A locale that failed outright still appears here with `status: "failed"` and an `error`, rather
- * than the whole run throwing. That is the central contract of {@link translate}: one unreachable
- * provider or one unwritable file does not discard the locales that succeeded.
- */
-interface LocaleSummary {
-    /** The target locale this summary describes. */
-    readonly locale: string;
-    /**
-     * `succeeded` when everything asked for was done, `partial` when some keys were translated and
-     * others were not, and `failed` when the locale produced no usable result.
-     */
-    readonly status: "succeeded" | "partial" | "failed";
-    /** Keys newly translated by the provider in this run. */
-    readonly translated: readonly string[];
-    /** Keys already up to date against the lock-file baseline, so no provider call was made. */
-    readonly unchanged: readonly string[];
-    /** Keys present in this locale but no longer in the source. Reported, and removed only when pruning. */
-    readonly orphaned: readonly string[];
-    /** Orphaned keys that were actually removed, which happens only when the run was asked to prune. */
-    readonly pruned: readonly string[];
-    /**
-     * Keys whose source text is not valid ICU. They are skipped rather than sent to the provider,
-     * because a broken source message cannot yield a sound translation.
-     */
-    readonly invalidIcuSource: readonly string[];
-    /** Keys served from the translation memory instead of the provider, and so not paid for. */
-    readonly cacheHits: readonly string[];
-    /**
-     * Keys whose translation was refused by the integrity gate, for instance because it dropped a
-     * placeholder. The previous translation, if any, is left untouched.
-     */
-    readonly integrityMismatches: readonly string[];
-    /** Keys the provider failed to translate, for instance because their sub-batch errored. */
-    readonly providerFailures: readonly string[];
-    /** Keys whose plural categories were generated for the target language rather than translated one by one. */
-    readonly generated: readonly string[];
-    /** Keys not translated because the token budget was exhausted under `stop` behavior. */
-    readonly budgetWithheld: readonly string[];
-    /** Token usage for this locale. Absent when the provider does not report usage. */
-    readonly usage?: UsageSummary;
-    /** Provider and SDK notices raised while running this locale. Always present, possibly empty. */
-    readonly notices: readonly LocaleNotice[];
-    /** Translated keys flagged as worth a human look. The translations were still written. */
-    readonly needsReview: readonly NeedsReviewEntry[];
-    /** Keys left with no translation after the run, whatever the cause. */
-    readonly unfilled: readonly string[];
-    /** Unreadable rows from an imported handoff. Always empty for a {@link translate} run. */
-    readonly malformedRows: readonly MalformedRowReport[];
-    /** Repeated keys from an imported handoff. Always empty for a {@link translate} run. */
-    readonly duplicateKeys: readonly DuplicateKeyReport[];
-    /**
-     * Why this locale failed, when the failure came from a thrown error. The `code` is the failure's
-     * own code where it has one, and `LOCALE_FAILED` otherwise. Never carries a secret.
-     *
-     * Absent unless `status` is `failed`, but a `failed` locale does not always carry it: a locale
-     * whose every key was withheld by the integrity gate, a provider failure, or the token budget is
-     * `failed` with nothing thrown, so this stays undefined and the withheld keys are the account of
-     * what went wrong. Treat it as an optional detail on a failure, never as the failure test.
-     */
-    readonly error?: {
-        /** The failure's own code where it had one, and `LOCALE_FAILED` otherwise. */
-        readonly code: string;
-        /** A human-readable description of the failure. Never contains a secret. */
-        readonly message: string;
-    };
+ * The default implementation dispatches on the provider ID and reads the API key from the
+ * environment. A factory that throws is reported as `PROVIDER_CONSTRUCTION_FAILED`.
+ */
+type CreateProvider = (config: ProviderConfig) => TranslationProvider;
+
+/** Input for {@link retranslateEntry}. */
+interface RetranslateEntryInput {
+    /** The resolved project config, normally from {@link loadConfig}. */
+    readonly config: VerbatraConfig;
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
+    readonly cwd?: string;
+    /** The target locale to retranslate into. Must be a configured target locale. */
+    readonly locale: string;
+    /** The key to retranslate. Must exist in the source resource. */
+    readonly key: string;
+}
+/** Injectable dependencies for {@link retranslateEntry}. Every field has a working default. */
+interface RetranslateEntryDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
+    readonly adapterRegistry?: AdapterRegistry;
+    /** Provider factory. Defaults to constructing the provider named in the config. */
+    readonly createProvider?: CreateProvider;
+    /** File-system port. Defaults to the real file system. */
+    readonly fs?: SdkFs;
 }
 /**
- * The result of a whole run, returned by {@link translate}, {@link watch}, and
- * {@link importWorkbook}.
- *
- * Per-locale outcomes are data, not exceptions: inspect `failed` and `partial` to decide an exit
- * code rather than relying on the call to throw. Only whole-run failures, such as an invalid config
- * or an unreadable source file, throw an {@link SdkError}.
+ * The outcome of {@link retranslateEntry}. As with {@link EditEntryResult}, a value refused by the
+ * integrity gate is reported as data rather than thrown, because it is an expected outcome of
+ * asking a provider for a fresh translation.
  */
-interface RunSummary {
-    /** True when the run computed everything but wrote nothing and called no provider. */
-    readonly dryRun: boolean;
+type RetranslateEntryResult = {
+    /** The provider's value passed the integrity gate and was written. */
+    readonly accepted: true;
+    /** The newly translated value now stored for the key. */
+    readonly value: string;
     /**
-     * The full per-locale account. A {@link translate} or {@link watch} run reports them in
-     * configured target order, whatever order a `locales` subset was given in and whatever order
-     * concurrent locales finished in. An {@link importWorkbook} run does not: it reports them in the
-     * order the handoff yielded them, then appends the configured locales the handoff had nothing
-     * for. Match an entry on its `locale` rather than on its position.
+     * Quality signals the provider layer raised for this value, such as a length-ratio outlier or
+     * a value identical to the source. Empty when nothing was flagged. The value is written
+     * either way; these are advisory.
      */
-    readonly locales: readonly LocaleSummary[];
-    /** Names of the locales whose status is `succeeded`. */
-    readonly succeeded: readonly string[];
+    readonly reviewReasons: readonly ReviewReasonCode[];
+} | {
+    /** The value was refused; nothing was written and the previous translation is intact. */
+    readonly accepted: false;
+    /** Which integrity rule the provider's value broke. */
+    readonly reason: IntegrityGateReason;
     /**
-     * Names of the locales whose status is `partial`: written to disk, but with keys still missing.
-     * Check this alongside `failed` before treating a run as clean. The CLI exits `1` on a partial
-     * locale for that reason.
+     * The specific tags behind a `markup` refusal, each prefixed with `-` for one the source had
+     * and the candidate dropped or `+` for one the candidate invented. A candidate carrying more
+     * than twice its source's inline tags and constructs is named as `+more than N inline tags`
+     * instead, where N is at least 256. Absent when no single tag is at fault, such as markup
+     * that came back mis-nested, and absent for every other reason.
      */
-    readonly partial: readonly string[];
-    /** Names of the locales whose status is `failed`. Check this before treating a run as clean. */
-    readonly failed: readonly string[];
-    /** Token usage summed across every locale. Absent when the provider does not report usage. */
-    readonly usage?: UsageSummary;
-    /** The token budget in force, present only when the config set one. */
-    readonly budget?: RunBudget;
-}
+    readonly details?: readonly string[];
+    /** The rejected value, echoed back so a UI can show what was refused. */
+    readonly value: string;
+};
+/**
+ * Re-runs the configured provider for a single key and saves the result. This is the paid
+ * counterpart to {@link editEntry}: it calls the provider and therefore spends tokens, which is why
+ * a UI should gate it behind an explicit user action.
+ *
+ * The returned value goes through the same integrity gate as a full run, so a translation that
+ * loses a placeholder or breaks ICU syntax is refused and nothing is written. Provider quality
+ * signals are surfaced on an accepted result as `reviewReasons` rather than blocking the write.
+ *
+ * The locale's write lock is taken before the provider is called and held across it, covering the
+ * whole read-translate-write cycle, so a slow provider keeps the lock for the length of its call
+ * and a concurrent {@link translate} run on that locale waits. The lock is held for a refused
+ * translation too, since the gate runs inside it. An accepted value then updates the lock-file
+ * baseline and feeds the translation memory, so a later {@link translate} run sees the key as up
+ * to date.
+ *
+ * Note that the target locale file surfaces the adapter's own error and code rather than a wrapped
+ * {@link SdkError}, on the write as well as on the read, because only the source read is wrapped.
+ * A malformed target file fails the read with a message naming the offending locale and the
+ * resolved path. The write raises the adapter's error too, when the entries cannot be represented
+ * in the configured format or the existing destination file cannot be read back to be updated in
+ * place, and that error is re-thrown unchanged so its own code survives for a caller that maps
+ * adapter codes to its own copy. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file on either path.
+ *
+ * It spends outside the token budget. `maxTokens` and `budgetBehavior` bound a {@link translate}
+ * run, and this is its own single-key path with its own provider, so a configured ceiling neither
+ * withholds this call nor counts it. A caller that exposes retranslation to users, as the Studio
+ * dashboard and the agent tools do, has to bound that spend itself.
+ *
+ * @param input - The config, locale, and key to retranslate.
+ * @param deps - Optional adapter registry, provider factory, and file-system overrides.
+ * @returns Whether the new value was accepted, with review reasons or the rejection reason.
+ *
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: the requested locale is not a configured target locale.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or the locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `UNKNOWN_KEY`: the key is not present in the source resource.
+ * @throws {@link SdkError} `PROVIDER_CONSTRUCTION_FAILED`: the provider could not be constructed,
+ * most often because its API key environment variable is unset.
+ * @throws {@link SdkError} `LOCK_CONTENDED`: the locale's write lock could not be acquired before
+ * the timeout elapsed.
+ * @throws {@link SdkError} `TARGET_UNWRITABLE`: the target locale file could not be written because
+ * of a file-system failure. The message names the target file and the file-system code, never the
+ * internal temporary file.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ * unsupported version.
+ * @throws `AdapterError`: the adapter itself refused the target locale file, on the read because it
+ * is malformed or on the write because the entries cannot be represented in the configured format.
+ * Its own code is preserved rather than remapped onto an {@link SdkErrorCode}.
+ * @throws `ProviderError` `INVALID_RESPONSE`: the provider returned no value for the key. Provider
+ * transport and rate-limit failures propagate as `ProviderError` too, since a single-key call has
+ * no per-locale summary to record them on.
+ */
+declare function retranslateEntry(input: RetranslateEntryInput, deps?: RetranslateEntryDeps): Promise<RetranslateEntryResult>;
 
 /**
  * One locale's entry in a persisted {@link RunStatusFile}. It is a deliberately narrow projection
@@ -2207,6 +4247,14 @@ interface RunStatusLocale {
     readonly status: "succeeded" | "partial" | "failed";
     /** Keys the run flagged as worth a human look. */
     readonly needsReview: readonly NeedsReviewEntry[];
+    /**
+     * Translations reused for a source string that had changed, with the score and the earlier
+     * source behind each one. Every key listed here also carries `FUZZY_CACHE_REUSE` in
+     * {@link needsReview}; this is the evidence a reviewer needs to judge the reuse without
+     * re-running. Absent for a locale that reused nothing, and for a file written before the field
+     * existed.
+     */
+    readonly fuzzyHits?: readonly FuzzyCacheHit[];
     /** Token usage for this locale. Absent when the provider does not report usage. */
     readonly usage?: UsageSummary;
 }
@@ -2225,7 +4273,11 @@ interface RunStatusFile {
     readonly generatedAt: string;
     /** Token usage summed across every locale. Absent when the provider does not report usage. */
     readonly usage?: UsageSummary;
-    /** The token budget in force during the run, present only when one was configured. */
+    /**
+     * The token budget in force during the run, present only when one was configured. A snapshot
+     * written before the budget was enforced, when `supported: false` meant nothing was counted at
+     * all, has such a budget left out rather than read as a count of zero.
+     */
     readonly budget?: RunBudget;
     /** Per-locale outcomes from the recorded run. */
     readonly locales: readonly RunStatusLocale[];
@@ -2272,6 +4324,314 @@ type RunStatusResult = {
  */
 declare function runStatus(input?: RunStatusInput, deps?: RunStatusDeps): Promise<RunStatusResult>;
 
+/** Default output path for a TMX export, used when {@link ExportTmxInput.out} is omitted. */
+declare const DEFAULT_TMX_PATH = "verbatra-memory.tmx";
+/** How many translation units one locale contributed to the exported file. */
+interface ExportTmxLocaleCount {
+    /** The configured target locale. */
+    readonly locale: string;
+    /** How many of its memory entries were written. */
+    readonly units: number;
+}
+/** What {@link exportTmx} wrote. */
+interface ExportTmxResult {
+    /** The resolved path the file was written to. */
+    readonly path: string;
+    /** How many `tu` elements the file holds, one per distinct source string. */
+    readonly units: number;
+    /** Per-locale contribution to that total. */
+    readonly locales: readonly ExportTmxLocaleCount[];
+    /**
+     * Translations left out because the memory holds no source text for their content hash, counted
+     * once per locale and hash rather than once per distinct source string. A cache carried forward
+     * from an older schema stores translations without their source, and TMX cannot represent a unit
+     * with no source segment. Those entries fill in as later runs touch the same strings.
+     */
+    readonly withoutSource: number;
+    /**
+     * Characters removed from segment text because XML 1.0 cannot represent them at all, such as a
+     * control character, a lone surrogate or a noncharacter, counted across every written segment.
+     * Writing them would produce a file no conformant parser accepts, so they are left out and counted
+     * rather than dropped silently.
+     */
+    readonly illegalCharactersRemoved: number;
+}
+/** Input for {@link exportTmx}. */
+interface ExportTmxInput {
+    /** The resolved project config, normally from {@link loadConfig}. */
+    readonly config: VerbatraConfig;
+    /** Where to write the file. Defaults to {@link DEFAULT_TMX_PATH}, resolved against `cwd`. */
+    readonly out?: string;
+    /** Directory the output path and the memory are resolved against. Defaults to the process working directory. */
+    readonly cwd?: string;
+    /** Subset of configured target locales to export. Defaults to all of them. */
+    readonly locales?: readonly string[];
+    /** Value for the TMX header's `creationtoolversion`. Defaults to `unknown`. */
+    readonly toolVersion?: string;
+}
+/** Injectable dependencies for {@link exportTmx}. Every field has a working default. */
+interface ExportTmxDeps {
+    /** File-system port. Defaults to the real file system. */
+    readonly fs?: SdkFs;
+}
+/**
+ * Writes the project's translation memory out as a TMX 1.4b file, the format every mainstream
+ * translation platform can read. It calls no provider and needs no API key: every value comes from
+ * the memory already on disk.
+ *
+ * Only entries stored under the project's current configuration fingerprint are written, which is
+ * the same set a run would reuse, so the file describes the memory as it is actually being used
+ * rather than every translation the project has ever produced. One `tu` element is written per
+ * distinct source string, carrying the source segment and one target segment per exported locale.
+ * An empty memory produces a valid, empty TMX file rather than an error.
+ *
+ * @param input - The config, the output path, the locale subset, and the tool version to stamp.
+ * @param deps - Optional file-system override.
+ * @returns The path written, the unit count, and what was left out.
+ *
+ * It reads the memory and writes a file; it never changes the memory, which is why the CLI refuses
+ * `--dry-run` and `--overwrite` on this direction rather than accepting and ignoring them.
+ *
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
+ * @throws {@link SdkError} `CONFIG_INVALID`: the source locale and one of the target locales are the
+ * same language tag once case and separators are normalized. Writing that file would produce two
+ * language attributes {@link importTmx} could not tell apart, so the file this project exported
+ * would be one it refuses to read back.
+ *
+ * @example
+ * ```ts
+ * const result = await exportTmx({ config, out: "memory.tmx" });
+ * console.log(`${result.units} units written to ${result.path}`);
+ * ```
+ */
+declare function exportTmx(input: ExportTmxInput, deps?: ExportTmxDeps): Promise<ExportTmxResult>;
+
+/**
+ * The two delimiter-separated interchange formats. They are one implementation with one parameter, the
+ * field delimiter: `tsv` is not a second format, it is `csv` with a tab. The member is also the file
+ * extension an export writes and an import reads back.
+ */
+type DelimitedFormat = "csv" | "tsv";
+/** Where in an interchange file a refusal happened. */
+interface ExchangeErrorLocation {
+    /** The 1-based line. */
+    readonly line: number;
+    /** The 1-based column on that line. */
+    readonly column: number;
+    /** The 1-based ordinal of the translation unit the problem sits in, when it sits in one. */
+    readonly unit?: number;
+}
+
+/**
+ * Why one translation unit in an imported TMX file was refused. The first five are the shared
+ * integrity gate's own reasons, so an imported unit is held to exactly the standard a provider's
+ * output and a filled translator handoff already face. `sourceBlank` is the one reason particular
+ * to interchange: a unit whose source segment is blank identifies no string, so it could never be
+ * matched and is never stored.
+ */
+type TmxRejectionReason = IntegrityGateReason | "sourceBlank";
+/**
+ * Where in a TMX file a `SOURCE_INVALID` refusal from {@link importTmx} happened: the 1-based `line`
+ * and `column`, and the 1-based `unit` ordinal when the problem sits inside a translation unit. Read
+ * it from a caught error with {@link tmxErrorLocation}; the same place is named in the message.
+ */
+type TmxErrorLocation = ExchangeErrorLocation;
+/**
+ * Reads where in a TMX file a refusal from {@link importTmx} happened, without casting the error or
+ * its `cause`.
+ *
+ * @param error - Whatever was caught from `importTmx`.
+ * @returns The {@link TmxErrorLocation} when `error` is an {@link SdkError} wrapping a TMX parse
+ * failure that has a place in the file; `undefined` for any other error, including a refusal with
+ * no place in the file such as a missing or oversized file.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await importTmx({ config, file: "legacy.tmx" });
+ * } catch (error) {
+ *   const at = tmxErrorLocation(error);
+ *   if (at !== undefined) console.error(`line ${at.line}, column ${at.column}`);
+ * }
+ * ```
+ */
+declare function tmxErrorLocation(error: unknown): TmxErrorLocation | undefined;
+/** How many units were refused, by reason. See {@link TmxRejectionReason}. */
+type TmxRejectionCounts = Readonly<Record<TmxRejectionReason, number>>;
+/** What an import did to the memory for one target locale. */
+interface ImportTmxLocaleResult {
+    /** The configured target locale, spelled as the config spells it. */
+    readonly locale: string;
+    /** Units stored for the first time. */
+    readonly added: number;
+    /** Units the memory already held with the same translation, so nothing changed. */
+    readonly unchanged: number;
+    /** Units that replaced a different existing translation, which needs `overwrite`. */
+    readonly overwritten: number;
+    /** Units refused because the memory already held a different translation and `overwrite` was off. */
+    readonly kept: number;
+    /** Later units in the same file repeating a source the file had already translated. */
+    readonly duplicates: number;
+    /**
+     * Units carrying two segments of equal standing for this locale with different values, such as
+     * `de-CH` and `de-AT` in a project configured for `de`. Which one is right cannot be known, so
+     * neither is stored. An exact tag always outranks one that only reaches the locale by subtag
+     * prefix, and two segments carrying the same value are not a conflict.
+     */
+    readonly conflicting: number;
+    /** Units refused before they could be stored, by reason. */
+    readonly rejected: TmxRejectionCounts;
+}
+/** A language tag in the file that no configured locale could be resolved to. */
+interface TmxLanguageReport {
+    /** The tag exactly as the file spelled it. */
+    readonly language: string;
+    /** How many units carried a segment in it. */
+    readonly units: number;
+}
+/** What {@link importTmx} read and what it wrote. */
+interface ImportTmxResult {
+    /** Whether the run was a dry run, in which case the memory file was not written. */
+    readonly dryRun: boolean;
+    /** The resolved path the file was read from. */
+    readonly file: string;
+    /** The `srclang` the file's header declared, or undefined if it declared none. */
+    readonly sourceLanguage: string | undefined;
+    /** How many translation units the file held. */
+    readonly units: number;
+    /** Per-target-locale account of what was stored. */
+    readonly locales: readonly ImportTmxLocaleResult[];
+    /** Units the reader could not use at all, such as a unit with no segment. */
+    readonly skippedUnits: number;
+    /** `tu` elements outside the file's first `body`, which the reader never walked. */
+    readonly unreachableUnits: number;
+    /**
+     * The header's `srclang` when it does not resolve to the configured source locale, so a file
+     * exported from a project with a different source language is visible rather than silently
+     * yielding nothing. Undefined when it matches, when the header declares none, or when it is the
+     * TMX `*all*` wildcard, which declares that the source varies per unit.
+     */
+    readonly sourceLanguageMismatch: string | undefined;
+    /** Units carrying no segment in the configured source locale, so nothing could be keyed. */
+    readonly unmatchedSourceUnits: number;
+    /**
+     * Units carrying two segments of equal standing that resolve to the configured source locale with
+     * different values, such as an `en-US` "Color" and an `en-GB` "Colour" segment in a project
+     * configured for `en`. An exact tag outranks a prefix match and identical values agree, so neither
+     * counts here. Which value the translations belong to cannot be known, so the unit is refused
+     * rather than attributed to whichever came last.
+     */
+    readonly conflictingSourceUnits: number;
+    /** Units whose segments carried inline markup, which is flattened to its text. */
+    readonly markupStrippedUnits: number;
+    /**
+     * Units whose inline markup carried a `sub` element, a sub-flow such as a tooltip or alternative
+     * text embedded in the markup. Its text is not part of the segment's own string, so it is left out
+     * of the segment rather than flattened into it.
+     */
+    readonly subflowDroppedUnits: number;
+    /** Language tags that resolved to no configured locale, with how many units carried each. */
+    readonly unmatchedLanguages: readonly TmxLanguageReport[];
+    /** Language tags that two or more configured locales could claim, so none was chosen. */
+    readonly ambiguousLanguages: readonly TmxLanguageReport[];
+    /**
+     * Segments that resolved cleanly to a configured target locale this run left out, because
+     * {@link ImportTmxInput.locales} narrowed it. Nothing is wrong with them; they are reported so a
+     * narrowed run does not look like a file that held less than it did.
+     */
+    readonly notImported: readonly TmxLanguageReport[];
+    /**
+     * Whether the memory file could be written. False when the project's cache was written by a newer
+     * build, which is left untouched rather than downgraded.
+     */
+    readonly memoryWritable: boolean;
+}
+/** Input for {@link importTmx}. */
+interface ImportTmxInput {
+    /** The resolved project config, normally from {@link loadConfig}. */
+    readonly config: VerbatraConfig;
+    /** Path to the TMX file, resolved against `cwd`. */
+    readonly file: string;
+    /** Directory the file and the memory are resolved against. Defaults to the process working directory. */
+    readonly cwd?: string;
+    /** Read and validate the file but write nothing. Defaults to false. */
+    readonly dryRun?: boolean;
+    /**
+     * Let an imported unit replace a translation the memory already holds for the same source and
+     * locale. Off by default, so the project's own memory wins a collision.
+     */
+    readonly overwrite?: boolean;
+    /** Subset of configured target locales to import. Defaults to all of them. */
+    readonly locales?: readonly string[];
+}
+/** Injectable dependencies for {@link importTmx}. Every field has a working default. */
+interface ImportTmxDeps {
+    /** Format-adapter registry, used for placeholder extraction and ICU validation. Defaults to the built-in registry. */
+    readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
+    readonly fs?: SdkFs;
+}
+/**
+ * Reads a TMX translation memory into the project's own memory, so a team arriving with years of
+ * accumulated translations does not start cold. It calls no provider and needs no API key: every
+ * value comes from the file.
+ *
+ * Nothing from the file is trusted. The XML is parsed under the interchange package's hardening
+ * (entity declarations refused, size and unit bounds enforced), a language tag is resolved to a
+ * configured locale by an explicit rule rather than guessed at, and every candidate translation
+ * must pass the same placeholder, inline markup, ICU, degeneracy and emptiness gate that a
+ * provider's output and a filled translator handoff already face before it is stored. A unit that
+ * fails is counted, never written, so it can never later be served as a cache hit that was never
+ * validated.
+ *
+ * Units are stored under the project's current configuration fingerprint, the same key a real run
+ * writes. That is deliberate: an imported memory is reused exactly when the configuration that
+ * would consume it matches, and stops matching when the provider, model, tone or glossary changes,
+ * which is the protection the fingerprint layer exists to give. Re-import after such a change.
+ *
+ * A collision is decided in favour of what the project already has: if the memory already holds a
+ * different translation for the same source and locale, the imported one is refused and counted as
+ * `kept` unless {@link ImportTmxInput.overwrite} is set. Importing the same file twice therefore
+ * changes nothing the second time, and writes no file at all.
+ *
+ * One consequence is worth stating plainly, because no import-time check can police it. An accepted
+ * unit's source text is written into the memory's source index, which is the same index fuzzy reuse
+ * scores a changed string against. An imported source that DIFFERS from a string in the project can
+ * therefore be served for that string by fuzzy reuse, which is what resemblance means.
+ *
+ * An imported source that is identical to a project string but hashes differently is not reachable
+ * at all. Fuzzy reuse discards any candidate whose normalized source equals the query, so a project
+ * entry that carries a description, a meaning, or a plural flag the unit cannot carry falls through
+ * to the provider rather than being served: the hashes differ, and the identical text disqualifies
+ * the fuzzy candidate.
+ *
+ * A fuzzy reuse is still held to the integrity gate against the real entry and is reported as a
+ * `FUZZY_CACHE_REUSE` review flag on the run summary, so it is visible rather than silent. A project
+ * that does not want an imported memory reachable that way should leave `fuzzyCache` out of its
+ * config.
+ *
+ * @param input - The config, the file path, and the dry-run, overwrite and locale-subset switches.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns What was read, what was stored, and everything that was skipped or refused.
+ *
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: no file exists at the given path.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the file is oversized, malformed, not a TMX document,
+ * or declares an XML entity. When the problem has a place in the file, the message names its line,
+ * column and, inside a translation unit, the unit's 1-based ordinal, and `cause` is the interchange
+ * reader's error carrying the same as a structured `location`.
+ *
+ * @example
+ * ```ts
+ * const result = await importTmx({ config, file: "legacy-memory.tmx" });
+ * for (const locale of result.locales) {
+ *   console.log(`${locale.locale}: ${locale.added} added, ${locale.kept} kept`);
+ * }
+ * ```
+ */
+declare function importTmx(input: ImportTmxInput, deps?: ImportTmxDeps): Promise<ImportTmxResult>;
+
 /**
  * Whatever could be read about the process currently holding a write lock. Both fields are optional
  * because a lock file left behind by a killed process may be truncated or unreadable, and reporting
@@ -2391,6 +4751,20 @@ interface TranslateInput {
      * preview work without spending anything. Defaults to false.
      */
     readonly dryRun?: boolean;
+    /**
+     * Compute a pre-run cost estimate and return it on {@link RunSummary.estimate}. Implies
+     * `dryRun`: an estimate constructs no provider, reads no API key, makes no network call, and
+     * writes no file, so it is safe to run anywhere. Defaults to false.
+     *
+     * The figure bounds the plan rather than the invoice: every provider call a live run schedules is
+     * counted, plural generation included, and the prompt is measured from the request payload that
+     * would be sent. Provider-side retries, a repair round, and a language that expands past the
+     * allowance can each push a live run above it; {@link EstimateCaveatCode} names them all. It
+     * carries a currency amount only when the config supplies a `rates` block covering the configured
+     * provider and model; otherwise it reports the quantity and says why the money is missing. See
+     * {@link RunEstimate}.
+     */
+    readonly estimate?: boolean;
     /**
      * Remove keys that no longer exist in the source. Defaults to the config's `prune`, then to
      * false, so orphaned keys are reported but kept unless removal is asked for explicitly.
@@ -2412,8 +4786,9 @@ interface TranslateInput {
     readonly lockAcquireTimeoutMs?: number;
     /**
      * How many locales to run at once. Must be an integer of at least 1; defaults to 1. On a live
-     * run it cannot be combined with a configured token budget, because concurrent locales would
-     * overshoot the budget nondeterministically.
+     * run it cannot be combined with a configured token budget: the ceiling would still hold, but
+     * which locale loses its remaining work would depend on the order the locales interleave, so the
+     * run would not be reproducible.
      */
     readonly concurrency?: number;
     /**
@@ -2431,6 +4806,29 @@ interface TranslateDeps {
     /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
+/**
+ * Whether a set of run options resolves to a dry run. `estimate` implies `dryRun`, and this is the
+ * one place that implication is decided: {@link translate} calls it, and so should any caller that
+ * has to know before the run starts whether anything will be written or spent, rather than
+ * re-deriving the rule and drifting from it.
+ *
+ * @param input - The `dryRun` and `estimate` options as the caller received them.
+ * @returns True when the run will construct no provider, write no file, and spend nothing.
+ *
+ * @example
+ * ```ts
+ * import { resolveDryRun, translate } from "@verbatra/sdk";
+ *
+ * if (!resolveDryRun(options)) {
+ *   await prepareWorkspaceForWrites();
+ * }
+ * const summary = await translate({ config, ...options });
+ * ```
+ */
+declare function resolveDryRun(input: {
+    readonly dryRun?: boolean | undefined;
+    readonly estimate?: boolean | undefined;
+}): boolean;
 /**
  * Runs the one-shot translation flow over every configured target locale, or over the subset named
  * by `locales`: read the source, diff
@@ -2505,13 +4903,6 @@ interface TranslateDeps {
  */
 declare function translate(input: TranslateInput, deps?: TranslateDeps): Promise<RunSummary>;
 
-/**
- * The two delimiter-separated interchange formats. They are one implementation with one parameter, the
- * field delimiter: `tsv` is not a second format, it is `csv` with a tab. The member is also the file
- * extension an export writes and an import reads back.
- */
-type DelimitedFormat = "csv" | "tsv";
-
 /**
  * The file shape of a translator handoff: a single styled `.xlsx` workbook with one sheet per
  * locale, or one plain `.csv` or `.tsv` file per locale.
@@ -2618,9 +5009,10 @@ interface ExportWorkbookResult {
  * unsupported version.
  * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
  * @throws The underlying file-system error, unwrapped, when the handoff could not be written: `out`
- * names a directory that does not exist or is not writable, or the device is full. Branch on the
- * Node `code`, such as `ENOENT`, rather than on the message, which can name the internal temporary
- * file the atomic write uses.
+ * resolves to a location the process lacks permission to write, or the device is full. A missing
+ * output directory is created automatically and is not a cause. Branch on the Node `code`, such as
+ * `EACCES` or `ENOSPC`, rather than on the message, which can name the internal temporary file the
+ * atomic write uses.
  */
 declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkbookDeps): Promise<ExportWorkbookResult>;
 
@@ -2721,6 +5113,12 @@ interface LocalePathResolverConfig {
     readonly sourceLocale: string;
     /** Every target locale. All of them are mapped up front so collisions are caught immediately. */
     readonly targetLocales: readonly string[];
+    /**
+     * The configured format. Every format maps each locale to a distinct path except a
+     * shared-catalogue format (one holding every locale in a single file, such as `apple-xcstrings`),
+     * which maps every locale to the same path.
+     */
+    readonly format: FormatId$1;
     /** The file layout. */
     readonly files: {
         /** The path pattern, which must contain the `{locale}` token. */
@@ -2740,6 +5138,9 @@ interface LocalePathResolver {
      * The configured locale owning an absolute path, or `undefined` when the path belongs to no
      * configured locale. The path is normalized before lookup, so a relative or non-canonical path
      * still resolves.
+     *
+     * Always `undefined` for a shared-catalogue format: every configured locale resolves to the same
+     * path there, so no single locale owns it.
      */
     localeFor(absolutePath: string): string | undefined;
 }
@@ -2755,15 +5156,21 @@ interface LocalePathResolver {
  * path collision is reported here, before any file is read and before any provider is called,
  * rather than partway through a run.
  *
+ * For a shared-catalogue format (such as `apple-xcstrings`), `pathFor` resolves every locale to the
+ * same path (the `{locale}` token is still required in the pattern but substitutes to the empty
+ * string), no locale style is applied, and `localeFor` always returns `undefined` rather than
+ * reporting a collision: every configured locale sharing one path is the expected shape for these
+ * formats, not a configuration mistake.
+ *
  * @param cwd - Directory the pattern is resolved against.
- * @param config - The source locale, target locales, and file layout.
+ * @param config - The source locale, target locales, format, and file layout.
  * @returns A resolver mapping locales to paths and paths back to locales.
  *
  * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the pattern lacks the `{locale}` token, a
  * segment style's token does not stand alone between separators, or a configured locale has no
  * valid single-segment spelling under the declared style.
  * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same
- * absolute path.
+ * absolute path, for a format that is not a shared-catalogue format.
  */
 declare function createLocalePathResolver(cwd: string, config: LocalePathResolverConfig): LocalePathResolver;
 
@@ -2818,6 +5225,33 @@ declare function loadLockFile(input?: LoadLockFileInput, deps?: LoadLockFileDeps
  */
 declare const LOCK_FILE_NAME = "verbatra.lock.json";
 
+/**
+ * Scrubs provider API key shapes and any currently configured provider environment variable value
+ * out of a string, replacing each match with `[REDACTED]`.
+ *
+ * Two independent passes run: a set of shape patterns for the major providers (OpenAI-style `sk-`
+ * keys, Gemini-style `AIza` keys, and hex UUID-shaped keys, with or without a `:fx` suffix), and an
+ * exact-value scrub of whatever `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`,
+ * `DEEPL_API_KEY`, `GOOGLE_TRANSLATE_API_KEY`, or `OPENAI_COMPATIBLE_API_KEY` currently holds in
+ * the process environment. Use this on any text a surface returns to a caller that did not itself
+ * generate that text, such as a file path, a config value, or an upstream error message, so a key
+ * value already present in the environment or written by a user can never reach an agent, a
+ * browser tab, or a log line.
+ *
+ * @param text - The text to scrub.
+ * @returns The same text with every matching key shape and configured key value replaced by
+ * `[REDACTED]`.
+ *
+ * @example
+ * ```ts
+ * import { redact } from "@verbatra/sdk";
+ *
+ * redact("key is sk-abcdEFGH12345678 in the log");
+ * // "key is [REDACTED] in the log"
+ * ```
+ */
+declare function redact(text: string): string;
+
 /**
  * A provider that project scaffolding can offer out of the box. It excludes `openai-compatible`,
  * which needs a `baseUrl` and a model name that only the user can supply, so there is nothing
@@ -2840,8 +5274,12 @@ declare const scaffoldingMetadata: {
         readonly openai: "OPENAI_API_KEY";
         readonly gemini: "GEMINI_API_KEY";
         readonly deepl: "DEEPL_API_KEY";
+        readonly "google-translate": "GOOGLE_TRANSLATE_API_KEY";
     };
-    /** A reasonable default model to prefill per language-model provider. DeepL has none, since it takes no model. */
+    /**
+     * A reasonable default model to prefill per language-model provider. DeepL and Google Cloud
+     * Translation have none, since neither takes a model.
+     */
     readonly scaffoldModels: {
         readonly anthropic: "claude-sonnet-4-6";
         readonly openai: "gpt-5.4-mini";
@@ -2852,7 +5290,7 @@ declare const scaffoldingMetadata: {
      * not agree: Anthropic calls it `maxTokens` and the others `maxOutputTokens`. A generator that
      * prefills a token limit must read the key from here rather than assume one, because
      * {@link verbatraConfigSchema} validates each provider's options strictly and rejects the wrong
-     * one. DeepL has no entry, since it takes no token limit.
+     * one. DeepL and Google Cloud Translation have no entry, since neither takes a token limit.
      */
     readonly providerTokenLimitKeys: {
         readonly anthropic: "maxTokens";
@@ -2860,7 +5298,7 @@ declare const scaffoldingMetadata: {
         readonly gemini: "maxOutputTokens";
     };
     /** Every i18n file format the SDK can read and write. */
-    readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb", "properties"];
+    readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb", "properties", "apple-strings", "apple-xcstrings", "android-xml", "gettext-po", "ini", "resx"];
 };
 
 /**
@@ -3005,4 +5443,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type BudgetBehavior, CACHE_FILE_NAME, type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_DELIMITED_PATH, DEFAULT_EXCHANGE_FORMAT, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type DoctorCheck, type DoctorCheckId, type DoctorCheckStatus, type DoctorDeps, type DoctorInput, type DoctorResult, type DuplicateKeyReport, EXCHANGE_FORMATS, type EditEntryDeps, type EditEntryInput, type EditEntryResult, type ExchangeFormat, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryFileDeps, type GlossaryFileInput, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, type IntegrityGateReason, type KeyIntegrityDeps, type KeyIntegrityEntry, type KeyIntegrityInput, type KeyValueDeps, type KeyValueInput, type KeyValueResult, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleFileSnapshot, type LocaleFinishedEvent, type LocaleKeyIntegrity, type LocaleNotice, type LocalePathResolver, type LocalePathResolverConfig, type LocaleSnapshotDelta, type LocaleStartedEvent, type LocaleStyle, type LocaleSummary, type LockFile, type LockHolder, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type LockWaitEvent, type LockWaitListener, type MalformedRowReport, type NeedsReviewEntry, type ProgressEvent, type ProgressListener, type ProviderConfig, type ProviderId, type ReadLocaleFileSnapshotDeps, type ReadLocaleFileSnapshotInput, type RetranslateEntryDeps, type RetranslateEntryInput, type RetranslateEntryResult, type ReviewReasonCode, type RunBudget, type RunFinishedEvent, type RunStatusDeps, type RunStatusFile, type RunStatusInput, type RunStatusLocale, type RunStatusResult, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SubBatchProgressEvent, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type TranslationMemory, type UpdateGlossaryTermInput, type UsageSummary, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, createLocalePathResolver, defineConfig, diff, diffLocaleSnapshots, doctor, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readGlossaryFile, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate, updateGlossaryTerm, verbatraConfigSchema, watch };
+export { AdapterError, type AdapterErrorCode, type AdapterFs, AdapterRegistry, type AdapterResolution, type AddedKey, type BillingUnit, type BoundedReadOutcome, type BudgetBehavior, type BudgetStanding, type BuildWriteTree, CACHE_FILE_NAME, type CharacterRate, type CharacterRunQuantity, type CheckDeps, type CheckInput, type CheckSummary, type ComparePlaceholders, type ComputeInvalidIcuKeys, type ConfigSource, type CreateProvider, type CreateWatcher, type CustomFormatId$1 as CustomFormatId, DEFAULT_DELIMITED_PATH, DEFAULT_EXCHANGE_FORMAT, DEFAULT_TMX_PATH, DEFAULT_TYPES_PATH, DEFAULT_WORKBOOK_PATH, type DeriveDescriptions, type DeriveEntry, type DiffDeps, type DiffInput, type DiffSummary, type DirectoryEntry, type DoctorCheck, type DoctorCheckId, type DoctorCheckStatus, type DoctorDeps, type DoctorInput, type DoctorResult, type DuplicateKeyReport, EXCHANGE_FORMATS, type EditEntryDeps, type EditEntryInput, type EditEntryResult, type EstimateCaveatCode, type EstimateIdentity, type EstimatePricing, type ExchangeFormat, type ExportTmxDeps, type ExportTmxInput, type ExportTmxLocaleCount, type ExportTmxResult, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ExtractDeps, type ExtractInput, type ExtractPlaceholders, type ExtractResult, type ExtractionConfig, type FlatFileAdapterOptions, type FlatParseOutcome, type FlatParseResult, type FormatAdapter, type FormatId$1 as FormatId, type FuzzyCacheHit, type GenerateTypesDeps, type GenerateTypesInput, type GenerateTypesResult, type GlossaryFileDeps, type GlossaryFileInput, type GlossaryProvenance, INTEGRITY_GATE_REASONS, type ImportTmxDeps, type ImportTmxInput, type ImportTmxLocaleResult, type ImportTmxResult, type ImportWorkbookDeps, type ImportWorkbookInput, type InconsistencyGroup, type InconsistentTranslation, type IntegrityGateReason, type JsonLeaf, type JsonRecord, type JsonTree, type KeyConflict, type KeyIntegrityDeps, type KeyIntegrityEntry, type KeyIntegrityInput, type KeyMode, type KeyValueDeps, type KeyValueInput, type KeyValuePair, type KeyValueResult, LOCK_FILE_NAME, type LiteralFinding, type LiteralScan, type LiteralSuppressionReason, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleEstimate, type LocaleEstimateQuantity, type LocaleFileSnapshot, type LocaleFinishedEvent, type LocaleKeyIntegrity, type LocaleNotice, type LocalePathResolver, type LocalePathResolverConfig, type LocaleResource$1 as LocaleResource, type LocaleSnapshotDelta, type LocaleStartedEvent, type LocaleStyle, type LocaleSummary, type LocaleValues, type LocaleValuesDeps, type LocaleValuesInput, type LockFile, type LockHolder, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type LockWaitEvent, type LockWaitListener, type MalformedRowReport, type ModelRate, type NeedsReviewEntry, type OrderedRecord, type OrderedValue, type PlaceholderIntegrityResult$1 as PlaceholderIntegrityResult, type PossiblyDynamicKey, type PricedLocaleEstimate, type PricedRunEstimate, type ProgressEvent, type ProgressListener, type ProviderBilling, type ProviderConfig, type ProviderId, type PseudolocalizeDeps, type PseudolocalizeInput, type PseudolocalizeResult, REVIEW_REASON_CODES, type RateCard, type ReadLocaleFileSnapshotDeps, type ReadLocaleFileSnapshotInput, type ReadResult, type ResolveOptions, type RetranslateEntryDeps, type RetranslateEntryInput, type RetranslateEntryResult, type ReviewReasonCode, type RunBudget, type RunEstimate, type RunEstimateQuantity, type RunFinishedEvent, type RunStatusDeps, type RunStatusFile, type RunStatusInput, type RunStatusLocale, type RunStatusResult, type RunSummary, type RunTranslate, type ScaffoldableProviderId, type ScanDiagnostic, type ScanDiagnosticReason, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type Sniff, type SourceFramework, type SourceLocation, type SubBatchProgressEvent, type SupportedFormat$1 as SupportedFormat, type SuppressedLiteral, type TmxErrorLocation, type TmxLanguageReport, type TmxRejectionCounts, type TmxRejectionReason, type TokenRate, type TokenRunQuantity, type TranslateDeps, type TranslateInput, type TranslationEntry$1 as TranslationEntry, type TranslationMemory, type TreeFileAdapterOptions, type UnpricedLocaleEstimate, type UnpricedRunEstimate, type UnresolvedArgumentReason, type UnresolvedMessage, type UnusedKey, type UnusedKeysNotRun, type UnusedKeysNotRunReason, type UnusedKeysPrefixSite, type UnusedKeysReport, type UnusedKeysScan, type UnusedKeysSite, type UnusedKeysUnreliability, type UnusedKeysUnreliableReason, type UpdateGlossaryTermInput, type UsageSummary, type ValidateMessage, type ValidateTree, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, budgetStanding, check, createDefaultRegistry, createFlatFileAdapter, createLocalePathResolver, createTreeFileAdapter, defineConfig, diff, diffLocaleSnapshots, doctor, editEntry, exportTmx, exportWorkbook, extract, generateTypes, importTmx, importWorkbook, isCustomFormatId, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, localeValues, lockState, nodeAdapterFs, pseudolocalize, readGlossaryFile, readLocaleFileSnapshot, redact, resolveDryRun, retranslateEntry, runStatus, scaffoldingMetadata, tmxErrorLocation, translate, updateGlossaryTerm, verbatraConfigSchema, watch };