@verbatra/sdk 0.6.1 → 0.6.3

package/dist/index.d.cts

@@ -231,10 +231,81 @@ declare const supportedFormatSchema$1: z.ZodEnum<{
     xliff: "xliff";
     yaml: "yaml";
     arb: "arb";
+    properties: "properties";
 }>;
 /** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
 type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
 
+/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
+type BoundedFileRead = {
+    readonly kind: "ok";
+    readonly content: string;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
+/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
+type BoundedBytesRead = {
+    readonly kind: "ok";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
+/**
+ * The minimal file-system surface the SDK needs. Reads are bounded and writes are atomic. Injectable so
+ * tests stay deterministic; the format adapters do their own file IO and bypass this seam.
+ */
+interface SdkFs {
+    /** Whether a readable file exists at the path. */
+    fileExists(path: string): Promise<boolean>;
+    /**
+     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the handle is
+     * fstat'd and the read never advances past the sized length, so swapping in a larger file cannot
+     * bypass the cap. A missing or unreadable path is "missing"; a file over the cap is "too-large".
+     */
+    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
+    /** Read a file as raw bytes with the same TOCTOU-safe, bounded discipline as {@link readFileBounded}. */
+    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
+    /** Write atomically: a temp file in the same directory, then rename over the target. */
+    writeFile(path: string, data: string): Promise<void>;
+    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
+    writeBytes(path: string, data: Uint8Array): Promise<void>;
+    /**
+     * Atomically create a file only if it does not already exist (O_EXCL semantics), creating any
+     * missing parent directory first. Returns true if this call created the file, false if a file
+     * was already present (no write performed). The backbone of {@link withLocaleWriteLock}'s
+     * exclusive-create lock: the parent-directory creation lives here so that primitive never touches
+     * `node:fs` directly and a fake `SdkFs` in tests never needs a real directory to exist.
+     */
+    createExclusive(path: string, data: string): Promise<boolean>;
+    /** Delete a file if present; a no-op if it is already absent. */
+    deleteFile(path: string): Promise<void>;
+}
+
+/**
+ * The content-addressed translation-memory (TM) cache: a local, gitignored, regenerable sidecar to
+ * the lock file (`verbatra.cache.json`). It lets a translation whose source content is unchanged be
+ * reused for free, even under a renamed key or across two keys with byte-identical source text,
+ * instead of being re-sent to the provider.
+ *
+ * Nesting is `entries[fingerprint][targetLocale][contentHash] = value`. The fingerprint scopes every
+ * entry to one translation context (provider, model, tone, glossary), so a tone or glossary change
+ * never serves a stale value. Unlike the lock file, a corrupt or wrong-version cache degrades to an
+ * empty cache and never fails a run: it is a cost optimization, not a correctness record.
+ */
+interface TranslationMemory {
+    /** The cache schema version; a value this build does not recognize degrades the whole file to empty. */
+    readonly version: number;
+    /** Cached values, nested fingerprint to target locale to source content hash to translated value. */
+    readonly entries: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>>;
+}
+
+/** The cache file's name, a sibling of the lock file and obviously JSON. */
+declare const CACHE_FILE_NAME = "verbatra.cache.json";
+
 /**
  * The provider section of the config: a discriminated union over the provider id, reusing each
  * provider's own config schema. There is no key field anywhere in this union except
@@ -299,6 +370,7 @@ declare const verbatraConfigSchema: z.ZodObject<{
         xliff: "xliff";
         yaml: "yaml";
         arb: "arb";
+        properties: "properties";
     }>;
     files: z.ZodObject<{
         pattern: z.ZodString;
@@ -445,55 +517,6 @@ declare function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraCon
 declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfigInput;
 declare function defineConfig(config: AuthoringConfig): VerbatraConfigInput;
 
-/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
-type BoundedFileRead = {
-    readonly kind: "ok";
-    readonly content: string;
-} | {
-    readonly kind: "missing";
-} | {
-    readonly kind: "too-large";
-};
-/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
-type BoundedBytesRead = {
-    readonly kind: "ok";
-    readonly bytes: Uint8Array;
-} | {
-    readonly kind: "missing";
-} | {
-    readonly kind: "too-large";
-};
-/**
- * The minimal file-system surface the SDK needs. Reads are bounded and writes are atomic. Injectable so
- * tests stay deterministic; the format adapters do their own file IO and bypass this seam.
- */
-interface SdkFs {
-    /** Whether a readable file exists at the path. */
-    fileExists(path: string): Promise<boolean>;
-    /**
-     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the handle is
-     * fstat'd and the read never advances past the sized length, so swapping in a larger file cannot
-     * bypass the cap. A missing or unreadable path is "missing"; a file over the cap is "too-large".
-     */
-    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
-    /** Read a file as raw bytes with the same TOCTOU-safe, bounded discipline as {@link readFileBounded}. */
-    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
-    /** Write atomically: a temp file in the same directory, then rename over the target. */
-    writeFile(path: string, data: string): Promise<void>;
-    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
-    writeBytes(path: string, data: Uint8Array): Promise<void>;
-    /**
-     * Atomically create a file only if it does not already exist (O_EXCL semantics), creating any
-     * missing parent directory first. Returns true if this call created the file, false if a file
-     * was already present (no write performed). The backbone of {@link withLocaleWriteLock}'s
-     * exclusive-create lock: the parent-directory creation lives here so that primitive never touches
-     * `node:fs` directly and a fake `SdkFs` in tests never needs a real directory to exist.
-     */
-    createExclusive(path: string, data: string): Promise<boolean>;
-    /** Delete a file if present; a no-op if it is already absent. */
-    deleteFile(path: string): Promise<void>;
-}
-
 /** Where a config's resolved glossary came from: absent, inline, or a file at the recorded path. */
 type GlossaryProvenance = {
     readonly source: "none";
@@ -620,11 +643,18 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   its timeout elapsed, because another process is holding it (or an orphaned lock file was left
  *   behind by a killed process); the message names the lock file's path (thrown by `translate`,
  *   `importWorkbook`, `editEntry`, and `retranslateEntry`).
+ * - `CONCURRENCY_INVALID`: the `concurrency` input is not an integer of at least 1 (thrown by
+ *   `translate` and, per run, by `watch`, before any locale runs).
+ * - `CONCURRENCY_BUDGET_CONFLICT`: a live run requested `concurrency` greater than 1 while a token
+ *   budget (`maxTokens`) is configured; the two are mutually exclusive because concurrency makes the
+ *   budget's stop guarantee nondeterministic (thrown by `translate` before any provider call; a dry
+ *   run is exempt, since it never folds usage into or consults the budget tracker, so the conflict
+ *   cannot arise).
  * - `LOCALE_FAILED` (NOT thrown): the fallback `code` recorded on a failed `LocaleSummary` when a
  *   per-locale failure carries no string code of its own. See the surfaced-not-thrown distinction
  *   on `translate`.
  */
-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" | "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" | "CONCURRENCY_INVALID" | "CONCURRENCY_BUDGET_CONFLICT" | "LOCALE_FAILED";
 /** The single structured error the SDK throws or records. Never carries a secret. */
 declare class SdkError extends Error {
     /** The stable {@link SdkErrorCode} for this failure; branch on this, not the message. */
@@ -645,6 +675,7 @@ declare const supportedFormatSchema: z.ZodEnum<{
     xliff: "xliff";
     yaml: "yaml";
     arb: "arb";
+    properties: "properties";
 }>;
 /** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
 type SupportedFormat = z.infer<typeof supportedFormatSchema>;
@@ -941,7 +972,7 @@ interface DiffDeps {
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
 /** Why {@link gateCandidateValue} rejected a candidate value. */
-type IntegrityGateReason = "placeholder" | "icu" | "degenerate";
+type IntegrityGateReason = "placeholder" | "icu" | "degenerate" | "empty";
 
 /** Input for {@link editEntry}: the validated config, exactly one target locale/key pair, and the human-typed replacement value. */
 interface EditEntryInput {
@@ -981,7 +1012,10 @@ type EditEntryResult = {
  * locale file (merging just this one key into its current entries, every other key untouched) and
  * updates the lock entry for this key only (see {@link updateLockFileLocale}'s `"merge"` mode); on
  * rejection, writes nothing. Never calls a provider: {@link EditEntryDeps} has no provider seam,
- * so there is no way to construct or call one.
+ * so there is no way to construct or call one. On acceptance it also feeds the accepted value into
+ * the local translation-memory cache (best-effort, keyed by the source content hash and the config
+ * fingerprint), so a later run can reuse it for free; a cache failure is swallowed and never fails
+ * the edit.
  *
  * `locale` and `key` are resolved fresh on every call, never from a cache: `locale` against
  * `config.targetLocales`, `key` against the source resource read fresh from disk.
@@ -1272,6 +1306,9 @@ type RetranslateEntryResult = {
  * the lock entry for this key only (see {@link updateLockFileLocale}'s `"merge"` mode); on rejection,
  * writes nothing. Reuses exactly the building blocks `translate()` already uses
  * (`selectProvider`/`provider.translateBatch`) and nothing else: no bespoke per-provider plumbing.
+ * Always calls the provider (it never consults the cache for a hit, since its whole purpose is a
+ * fresh translation), then feeds the accepted value into the translation-memory cache best-effort so
+ * a later run can reuse it; a cache failure is swallowed and never fails the retranslate.
  *
  * `locale` and `key` are resolved fresh on every call, never cached: `locale` against
  * `config.targetLocales` (`UNKNOWN_LOCALE`), `key` against the source resource's own keys, read
@@ -1311,7 +1348,7 @@ type RetranslateEntryResult = {
 declare function retranslateEntry(input: RetranslateEntryInput, deps?: RetranslateEntryDeps): Promise<RetranslateEntryResult>;
 
 /** A stable code for an SDK-originated notice (not a provider notice). */
-type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED";
+type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED" | "CACHE_VERSION_UNRECOGNIZED";
 /** Summed token usage across every provider call in a scope (one locale, or the whole run). */
 interface UsageSummary {
     readonly inputTokens: number;
@@ -1357,6 +1394,26 @@ interface NeedsReviewEntry {
     /** Every {@link ReviewReasonCode} that applies to this key. */
     readonly reasons: readonly ReviewReasonCode[];
 }
+/**
+ * One row a workbook import could not read: the 1-based worksheet row number and the header label of
+ * the offending column. Carries no cell content, so untrusted workbook text never reaches the summary.
+ */
+interface MalformedRowReport {
+    /** The 1-based worksheet row number of the malformed row. */
+    readonly row: number;
+    /** The header label of the column the row was rejected on (for example "Status"). */
+    readonly column: string;
+}
+/**
+ * One duplicate-key conflict a workbook import found in a locale's sheet: the duplicated key and the
+ * 1-based worksheet row number of the later (losing) occurrence. The first occurrence is the winner.
+ */
+interface DuplicateKeyReport {
+    /** The key that appeared more than once in the locale's sheet. */
+    readonly key: string;
+    /** The 1-based worksheet row number of the later occurrence that lost to the first. */
+    readonly row: number;
+}
 /** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
 interface LocaleSummary {
     /** The target locale this summary is for. */
@@ -1370,6 +1427,32 @@ interface LocaleSummary {
      * {@link LocaleSummary.budgetWithheld} non-empty). `"failed"` when the locale had candidate keys
      * but accepted nothing at all (neither translated nor generated) while withholding at least one.
      * Withheld keys keep their prior lock hash and retry next run.
+     *
+     * A workbook import's structural findings, {@link LocaleSummary.unfilled},
+     * {@link LocaleSummary.malformedRows}, and {@link LocaleSummary.duplicateKeys}, deliberately do NOT
+     * feed this status: they are surfaced in their own lists (and the CLI) but are not withholdings of
+     * an attempted translation, so a locale that dropped a malformed row, collapsed a duplicate key, or
+     * left a row unfilled while accepting its other rows can still be `"succeeded"`.
+     *
+     * This is a settled decision, not an omission. Recording the reasoning here so the question stops
+     * recurring:
+     *
+     * 1. Two questions, two commands. `import`'s exit code answers "did the import apply what the
+     *    translator gave me". `check` and `diff` answer "is this project fully translated", and both
+     *    already exit non-zero or report pending in every one of these cases. Folding pending human
+     *    work into the import exit code duplicates an existing gate rather than adding one.
+     * 2. It would break the staged handoff. With `de` and `fr` configured and only `de` filled in,
+     *    failing on unfilled work makes `fr` fail and takes the whole import with it, even though `de`
+     *    imported perfectly. Locale-at-a-time handoff is this feature's most common workflow.
+     * 3. {@link LocaleSummary.malformedRows} structurally cannot signal lost work. The Status column is
+     *    the only reachable rejection in the workbook reader; every other field is an unconstrained
+     *    string or a tolerant parse. So a row is malformed on its Status cell alone, entirely
+     *    independently of whether its Translation cell was filled. An untouched sheet with a mangled
+     *    Status column (spreadsheet autocorrect, a CAT-tool round trip) is all-malformed with zero lost
+     *    work. A bucket that cannot distinguish dropped work from absent work cannot honestly drive a
+     *    failure status.
+     * 4. {@link LocaleSummary.duplicateKeys} never could: the first occurrence wins and the intent is
+     *    honoured.
      */
     readonly status: "succeeded" | "partial" | "failed";
     /**
@@ -1389,6 +1472,15 @@ interface LocaleSummary {
     readonly pruned: readonly string[];
     /** Source keys flagged invalid-ICU that were skipped for translation this run. */
     readonly invalidIcuSource: readonly string[];
+    /**
+     * Keys served from the local translation-memory cache instead of the provider: their source content
+     * was unchanged (possibly under a renamed key or shared with another key) and the cached value passed
+     * the integrity gate, so no provider request was made for them. They are written and lock-advanced
+     * exactly like a translated key, but kept distinct from {@link LocaleSummary.translated} because they
+     * cost no provider usage. Always present, empty by default; empty in a dry-run and when the cache is
+     * bypassed. Sorted by key.
+     */
+    readonly cacheHits: readonly string[];
     /**
      * Translated keys that failed the placeholder-integrity check and were withheld. Never includes a
      * key withheld because the provider call itself failed; see {@link LocaleSummary.providerFailures}
@@ -1440,6 +1532,32 @@ interface LocaleSummary {
      * flags on its own path).
      */
     readonly needsReview: readonly NeedsReviewEntry[];
+    /**
+     * Keys the translator left blank that still need a translation, drifted or not, sorted by key.
+     * Pending work made visible: the row is skipped (nothing is written and the prior lock baseline is
+     * kept), but the key is surfaced so an unfinished import is never silently reported as done. Only a
+     * workbook import populates this; the provider path, which never leaves a candidate key unfilled by
+     * a person, always leaves it empty.
+     *
+     * Membership is decided by the import-time diff, not by the `status` the row was exported with: a
+     * never-translated key exports as `new`, and a first handoff is all-new, which is the most common
+     * unfilled case there is. A row exported as `changed` whose key no longer needs work by import time
+     * is correspondingly excluded.
+     */
+    readonly unfilled: readonly string[];
+    /**
+     * Rows a workbook import could not read for this locale, each by worksheet row number and offending
+     * column, in row order. The sheet's other rows still import; a malformed row is reported, not
+     * written. Only a workbook import populates this; the provider path always leaves it empty.
+     */
+    readonly malformedRows: readonly MalformedRowReport[];
+    /**
+     * Duplicate-key conflicts a workbook import found in this locale's sheet, in row order. The rule is
+     * first occurrence wins: the first row for a key is judged and its later occurrences are reported
+     * here and otherwise ignored. Only a workbook import populates this; the provider path always leaves
+     * it empty.
+     */
+    readonly duplicateKeys: readonly DuplicateKeyReport[];
     /**
      * A structured, secret-free error for a locale that threw (an adapter/lock/provider-construction
      * failure isolated as data): present only on a "failed" locale, and only that throw path sets it.
@@ -1564,6 +1682,76 @@ interface LockWaitEvent {
 /** Called while an acquire is blocked, to surface wait progress; the lock module itself writes no output. */
 type LockWaitListener = (event: LockWaitEvent) => void;
 
+/**
+ * One structured progress notification emitted while a run advances through its locales and their
+ * provider sub-batches. Emitted to a caller-supplied {@link ProgressListener}; the SDK itself writes
+ * nothing to any stream, so a caller (the CLI) is free to render these to stderr and keep stdout a
+ * clean summary or NDJSON stream. Discriminated on `type`, mirroring the lock-wait event contract.
+ */
+type ProgressEvent = LocaleStartedEvent | SubBatchProgressEvent | LocaleFinishedEvent | RunFinishedEvent;
+/** A locale is about to be processed: its position in the run's target-locale order. */
+interface LocaleStartedEvent {
+    readonly type: "locale-started";
+    /** The target locale about to run. */
+    readonly locale: string;
+    /** Zero-based index of this locale in the run's target-locale order. */
+    readonly localeIndex: number;
+    /** Total number of target locales in this run. */
+    readonly totalLocales: number;
+}
+/**
+ * One sub-batch of a locale's main translation loop has been reached. Emitted once per loop
+ * iteration, in order, so a caller can render a "batch N of M" line. Fired at the top of the
+ * iteration regardless of whether the batch then makes a provider call: a budget-withheld batch
+ * (the run's token budget already tripped) still emits this event, which keeps `batchIndex` 1-based
+ * and contiguous against the total. A dry-run never reaches this loop and so never emits it.
+ */
+interface SubBatchProgressEvent {
+    readonly type: "sub-batch";
+    /** The locale whose entries this sub-batch carries. */
+    readonly locale: string;
+    /** One-based index of this sub-batch within the locale. */
+    readonly batchIndex: number;
+    /** Total number of sub-batches this locale's main translation loop runs. */
+    readonly totalBatches: number;
+}
+/** A locale finished processing: how many keys it accepted (translated). */
+interface LocaleFinishedEvent {
+    readonly type: "locale-finished";
+    /** The target locale that finished. */
+    readonly locale: string;
+    /** Number of keys accepted (translated) for this locale. In a dry-run, the keys that would be translated. */
+    readonly translated: number;
+    /**
+     * Zero-based index of this locale in the run's target-locale order, carrying the same value as the
+     * matching {@link LocaleStartedEvent}. This is a correlation key, so a consumer can pair a finish
+     * with its start without matching on the locale name.
+     *
+     * It is deliberately NOT a progress counter. The worker pool claims indices up front, so this is a
+     * claim ordinal rather than a completion ordinal: under concurrency the locales finish in a
+     * different order, and rendering `localeIndex + 1` of `totalLocales` on a finish produces a
+     * counter that jumps around and never reaches its own total in order. Do not reintroduce one.
+     */
+    readonly localeIndex: number;
+    /** Total number of target locales in this run, mirroring {@link LocaleStartedEvent}. */
+    readonly totalLocales: number;
+}
+/** The run reached the end of its locale loop: how many locales it processed. */
+interface RunFinishedEvent {
+    readonly type: "run-finished";
+    /**
+     * Number of locales the run processed (including failed locales: a per-locale failure is isolated
+     * as a summary rather than thrown, so it is still counted here).
+     */
+    readonly localesCompleted: number;
+}
+/**
+ * Called with each {@link ProgressEvent} as a run advances; the SDK emits no output of its own. A
+ * caller (the CLI) uses this to render progress, always to stderr, so stdout stays byte-identical to
+ * a run with no listener attached.
+ */
+type ProgressListener = (event: ProgressEvent) => void;
+
 /** Everything the one-shot run needs: the validated config and where/how to run it. */
 interface TranslateInput {
     /** The validated configuration (typically from {@link loadConfig}). */
@@ -1592,12 +1780,43 @@ interface TranslateInput {
      * is the only wait-progress signal (the CLI renders its "still waiting" line from it).
      */
     readonly onLockWait?: LockWaitListener;
+    /**
+     * Called as the run advances: once per locale before it starts and once after it finishes, once
+     * per provider sub-batch within a locale, and once when the whole locale loop ends. Never fires a
+     * sub-batch event on a dry-run (no provider call is made). The SDK writes no output; this is the
+     * only progress signal (the CLI renders it to stderr, keeping stdout byte-identical).
+     *
+     * Pairing is not guaranteed when the run throws: a whole-run failure (for example a corrupt
+     * lock-file surfacing as `LOCK_FILE_INVALID`, which re-throws instead of being isolated per locale)
+     * can emit a `locale-started` event with no matching `locale-finished`, and no `run-finished` at
+     * all. A per-locale failure that is isolated (not re-thrown) still emits both, and is counted in
+     * `run-finished`.
+     */
+    readonly onProgress?: ProgressListener;
     /**
      * Override how long a locale's write lock keeps retrying before failing with `LOCK_CONTENDED`, in
      * milliseconds. Defaults to the lock's own 10-minute default when unset (surfaced to the CLI as
      * `--lock-timeout`).
      */
     readonly lockAcquireTimeoutMs?: number;
+    /**
+     * How many target locales may run at once, a positive integer (surfaced to the CLI as
+     * `--concurrency`). Defaults to 1, which runs locales strictly in sequence and is byte-identical
+     * to a run with this option unset. A value below 1 or a non-integer is rejected with a whole-run
+     * `CONCURRENCY_INVALID` error. On a live run, a value greater than 1 is rejected with a whole-run
+     * `CONCURRENCY_BUDGET_CONFLICT` error when the config sets a `maxTokens` budget, because
+     * concurrency would make the budget's stop guarantee nondeterministic; a dry run is exempt. The
+     * per-locale write locks already isolate concurrent locales on disk, so no extra locking is added.
+     */
+    readonly concurrency?: number;
+    /**
+     * Whether to use the local content-addressed translation-memory cache (`verbatra.cache.json`). On by
+     * default; the CLI exposes it as `--no-cache`. When false, both the cache read and the end-of-run
+     * cache write are skipped: the run makes exactly the provider calls it would with no cache present,
+     * and leaves any existing cache file untouched. Ignored on a dry-run, which never reads or writes the
+     * cache regardless. See the cache module for the fingerprint and degrade-to-empty contract.
+     */
+    readonly cache?: boolean;
 }
 /** Composition seam: inject a registry, a provider builder, and a file system for tests. */
 interface TranslateDeps {
@@ -1644,6 +1863,11 @@ interface TranslateDeps {
  * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be read or parsed (wraps the
  *   adapter read error).
  * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is present but corrupt or oversized.
+ * @throws {@link SdkError} `CONCURRENCY_INVALID`: `concurrency` is defined but not an integer of at
+ *   least 1; raised before any locale runs.
+ * @throws {@link SdkError} `CONCURRENCY_BUDGET_CONFLICT`: a live run set `concurrency` greater than 1
+ *   while the config configures a `maxTokens` budget; raised before any provider call (a dry run is
+ *   exempt).
  * @example
  * ```ts
  * import { loadConfig, translate } from "@verbatra/sdk";
@@ -1735,10 +1959,13 @@ interface ImportWorkbookDeps {
  * identical to `translate`'s.
  *
  * Whole-run failures (unknown format, unreadable/invalid/oversized workbook, corrupt lock) throw a
- * structured {@link SdkError}. A per-sheet failure (a locale not in config, a broken-round-trip key,
- * a write failure) is isolated as that locale's `status: "failed"`, not a throw; per-row rejections
- * are withheld and reported on the locale. Dry-run validates and reports without writing any locale or
- * lock file, and skips lock acquisition (there is nothing to protect).
+ * structured {@link SdkError}. A per-sheet failure (a sheet named for a locale not in config, a
+ * broken-round-trip key, a write failure) is isolated as that locale's `status: "failed"`, not a
+ * throw; per-row rejections are withheld and reported on the locale. A configured target locale with
+ * no sheet at all (a deleted, renamed, or reordered tab) is reconciled after the sheet loop and
+ * reported as that locale's `status: "failed"` (`WORKBOOK_SHEET_MISSING`) rather than silently
+ * dropped. Dry-run validates and reports without writing any locale or lock file, and skips lock
+ * acquisition (there is nothing to protect).
  *
  * The lock-file is read once, up front, for every sheet's diff baseline. On a non-dry-run, each
  * sheet's write-and-lock-update step then holds that locale's `withLocaleWriteLock` for its whole
@@ -1817,7 +2044,7 @@ declare const scaffoldingMetadata: {
         readonly gemini: "gemini-2.5-flash";
     };
     /** The closed set of source format ids. Owned by core. */
-    readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb"];
+    readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb", "properties"];
 };
 
 /** A minimal source-change event source. Production wraps chokidar; tests inject a stub. */
@@ -1862,8 +2089,25 @@ interface WatchInput {
      * one-shot run does.
      */
     readonly onLockWait?: LockWaitListener;
+    /**
+     * Passed through to every run's {@link TranslateInput.onProgress}: fires per locale and per provider
+     * sub-batch as each run advances, so a watch caller can surface the same progress a one-shot run does.
+     */
+    readonly onProgress?: ProgressListener;
     /** Passed through to every run's {@link TranslateInput.lockAcquireTimeoutMs}; the lock's 10-minute default when unset. */
     readonly lockAcquireTimeoutMs?: number;
+    /**
+     * Passed through to every run's {@link TranslateInput.concurrency}: how many locales each cycle may
+     * run at once. Defaults to 1 (strictly serial). Because the per-cycle budget tracker is fresh, a
+     * value greater than 1 cannot be honored alongside a `maxTokens` budget; {@link watch} refuses that
+     * combination at startup rather than letting every cycle fail on it.
+     */
+    readonly concurrency?: number;
+    /**
+     * Passed through to every run's {@link TranslateInput.cache}: when false, each run bypasses the
+     * translation-memory cache (both read and write). On by default.
+     */
+    readonly cache?: boolean;
 }
 /** Composition seam: inject the watcher and the run for deterministic, offline tests. */
 interface WatchDeps {
@@ -1890,9 +2134,23 @@ interface WatchController {
  * `onRun` as a {@link WatchRunResult} and watching continues. Returns a controller whose `stop()`
  * closes the watcher and awaits the in-flight run.
  *
+ * Both startup refusals are ordered deliberately: `concurrency` is resolved first because it is
+ * decidable from the arguments alone, while the missing-source check is an I/O probe of project
+ * state, so argument validation runs before any I/O and before the watcher exists. The concurrency
+ * resolve passes `dryRun: false` unconditionally, which is exact rather than a simplification: there
+ * is no dry-run watch, so the budget conflict always applies to a session.
+ *
+ * Resolving it here rather than leaving it to each cycle is the point, not an optimization: a watch
+ * session is long-lived, so a per-cycle refusal would fail the initial run and every run after it,
+ * indefinitely, while the session stayed alive and looked healthy.
+ *
  * @param input - The config, optional cwd/debounce, and the `onRun` callback that receives each result.
  * @param deps - Optional composition seams (watcher, run, registry, provider builder, file system) for tests.
  * @returns A {@link WatchController}; call `stop()` to close the watcher and await the in-flight run.
+ * @throws {@link SdkError} `CONCURRENCY_INVALID`: at startup only, when `concurrency` is defined but
+ *   not an integer of at least 1.
+ * @throws {@link SdkError} `CONCURRENCY_BUDGET_CONFLICT`: at startup only, when `concurrency` is
+ *   greater than 1 while the config sets a `maxTokens` budget.
  * @throws {@link SdkError} `SOURCE_UNREADABLE`: at startup only, when the source locale file is absent.
  * @example
  * ```ts
@@ -1920,4 +2178,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type BudgetBehavior, type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type EditEntryDeps, type EditEntryInput, type EditEntryResult, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, 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 LocaleKeyIntegrity, type LocaleNotice, type LocaleSnapshotDelta, type LocaleSummary, type LockFile, type LockHolder, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type LockWaitEvent, type LockWaitListener, type NeedsReviewEntry, type ProviderConfig, type ProviderId, type ReadLocaleFileSnapshotDeps, type ReadLocaleFileSnapshotInput, type RetranslateEntryDeps, type RetranslateEntryInput, type RetranslateEntryResult, type ReviewReasonCode, type RunBudget, 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 SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type UsageSummary, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, diffLocaleSnapshots, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
+export { type BudgetBehavior, CACHE_FILE_NAME, type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type DuplicateKeyReport, type EditEntryDeps, type EditEntryInput, type EditEntryResult, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, 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 LocaleSnapshotDelta, type LocaleStartedEvent, 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 UsageSummary, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, diffLocaleSnapshots, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate, verbatraConfigSchema, watch };