@verbatra/sdk 0.6.0 → 0.6.2

package/dist/index.d.ts

@@ -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
@@ -246,23 +317,27 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     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">;
@@ -271,6 +346,7 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         model: z.ZodString;
         maxOutputTokens: z.ZodNumber;
         apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
 }, z.core.$strip>], "id">;
 /** One validated provider section: the provider id plus that provider's own options. */
@@ -294,6 +370,7 @@ declare const verbatraConfigSchema: z.ZodObject<{
         xliff: "xliff";
         yaml: "yaml";
         arb: "arb";
+        properties: "properties";
     }>;
     files: z.ZodObject<{
         pattern: z.ZodString;
@@ -303,23 +380,27 @@ declare const verbatraConfigSchema: z.ZodObject<{
         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">;
@@ -328,6 +409,7 @@ declare const verbatraConfigSchema: z.ZodObject<{
             model: z.ZodString;
             maxOutputTokens: z.ZodNumber;
             apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+            requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>;
     }, z.core.$strip>], "id">;
     glossary: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodString>, z.ZodString]>>;
@@ -435,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";
@@ -610,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. */
@@ -635,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>;
@@ -930,6 +971,9 @@ interface DiffDeps {
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
+/** Why {@link gateCandidateValue} rejected a candidate value. */
+type IntegrityGateReason = "placeholder" | "icu" | "degenerate";
+
 /** Input for {@link editEntry}: the validated config, exactly one target locale/key pair, and the human-typed replacement value. */
 interface EditEntryInput {
     /** The validated configuration (typically from {@link loadConfig}). */
@@ -959,7 +1003,7 @@ type EditEntryResult = {
     readonly value: string;
 } | {
     readonly accepted: false;
-    readonly reason: "placeholder" | "icu";
+    readonly reason: IntegrityGateReason;
     readonly value: string;
 };
 /**
@@ -968,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.
@@ -1248,7 +1295,7 @@ type RetranslateEntryResult = {
     readonly reviewReasons: readonly ReviewReasonCode[];
 } | {
     readonly accepted: false;
-    readonly reason: "placeholder" | "icu";
+    readonly reason: IntegrityGateReason;
     readonly value: string;
 };
 /**
@@ -1259,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
@@ -1344,12 +1394,47 @@ 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. */
     readonly locale: string;
-    /** Whether this locale's run succeeded or failed (a failure does not abort the run). */
-    readonly status: "succeeded" | "failed";
+    /**
+     * This locale's honest run status (a non-success does not abort the run). `"succeeded"` when
+     * nothing was withheld, including a genuine no-op with no candidate keys at all. `"partial"` when
+     * at least one key was accepted and written (a {@link LocaleSummary.translated} key or a
+     * {@link LocaleSummary.generated} plural form) but at least one was withheld (any of
+     * {@link LocaleSummary.integrityMismatches}, {@link LocaleSummary.providerFailures}, or
+     * {@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 `changed` row unfilled while accepting its other rows can still be `"succeeded"`.
+     */
+    readonly status: "succeeded" | "partial" | "failed";
     /**
      * Keys translated and written this run. In dry-run, the keys that would be translated
      * (the provider is not called and nothing is written).
@@ -1367,6 +1452,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}
@@ -1419,9 +1513,34 @@ interface LocaleSummary {
      */
     readonly needsReview: readonly NeedsReviewEntry[];
     /**
-     * Present only when status is "failed": a structured, secret-free error. `code` is a preserved string
-     * (the underlying provider/adapter error's `code`, or `"LOCALE_FAILED"` as a fallback), intentionally
-     * wider than {@link SdkErrorCode}, so do not treat it as a closed set.
+     * Keys the workbook exported as `changed` (needing an updated translation) that the translator left
+     * blank, 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.
+     */
+    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.
+     * A locale that is "failed" because every candidate key was withheld (all under `providerFailures`,
+     * `integrityMismatches`, or `budgetWithheld`) carries those lists and any notices instead, and has
+     * no `error`. `code` is a preserved string (the underlying provider/adapter error's `code`, or
+     * `"LOCALE_FAILED"` as a fallback), intentionally wider than {@link SdkErrorCode}, so do not treat
+     * it as a closed set.
      */
     readonly error?: {
         readonly code: string;
@@ -1434,9 +1553,15 @@ interface RunSummary {
     readonly dryRun: boolean;
     /** One {@link LocaleSummary} per target locale, in config order. */
     readonly locales: readonly LocaleSummary[];
-    /** Locales whose run succeeded. */
+    /** Locales whose run succeeded with nothing withheld (status `"succeeded"`). */
     readonly succeeded: readonly string[];
-    /** Locales whose run failed (see each locale's `error`). */
+    /**
+     * Locales that wrote at least one translation but withheld at least one candidate key (status
+     * `"partial"`). A partial locale still exits the CLI `0`: it made progress, and its withheld keys
+     * retry next run. Never overlaps `succeeded` or `failed`.
+     */
+    readonly partial: readonly string[];
+    /** Locales whose run failed, having accepted nothing (status `"failed"`; see each locale's `error`). */
     readonly failed: readonly string[];
     /**
      * Summed token usage across every locale's {@link LocaleSummary.usage}. Absent when no locale in the
@@ -1449,12 +1574,12 @@ interface RunSummary {
 
 /**
  * One target locale's snapshot inside the persisted run-status file. `status` is carried over from
- * `LocaleSummary.status` unchanged, so an empty `needsReview` on a failed locale is never misread as
- * "this locale ran clean with nothing to review".
+ * `LocaleSummary.status` unchanged, so an empty `needsReview` on a failed or partial locale is never
+ * misread as "this locale ran clean with nothing to review".
  */
 interface RunStatusLocale {
     readonly locale: string;
-    readonly status: "succeeded" | "failed";
+    readonly status: "succeeded" | "partial" | "failed";
     /** The full, unmodified list from `LocaleSummary.needsReview`; already bounded and content-free. */
     readonly needsReview: readonly NeedsReviewEntry[];
     /** Absent exactly when the source `LocaleSummary.usage` was absent; never a fabricated zero. */
@@ -1510,6 +1635,85 @@ type RunStatusResult = {
  */
 declare function runStatus(input?: RunStatusInput, deps?: RunStatusDeps): Promise<RunStatusResult>;
 
+/** Diagnostic details, read leniently from a held lock file, about the process currently holding it. */
+interface LockHolder {
+    /** The holder's process id, when the lock file could be read and carried a numeric `pid`. */
+    readonly pid?: number;
+    /** The holder's acquire time as an ISO-8601 string, when the lock file carried a string `acquiredAt`. */
+    readonly acquiredAt?: string;
+}
+/** One wait-progress notification emitted while an acquire is blocked on a held lock. */
+interface LockWaitEvent {
+    /** The on-disk path of the contended lock file, the exact path a person can delete if it is orphaned. */
+    readonly lockPath: string;
+    /** Milliseconds elapsed since this acquire started waiting, for a "still waiting" progress line. */
+    readonly elapsedMs: number;
+    /**
+     * Diagnostics about the holding process, present only when the lock file could be read and parsed.
+     * Purely for messaging; never consulted for any acquire decision.
+     */
+    readonly holder?: LockHolder;
+}
+/** 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;
+}
+/** 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}). */
@@ -1531,6 +1735,50 @@ interface TranslateInput {
      * unset, the config's `generatePlurals` applies.
      */
     readonly generatePlurals?: boolean;
+    /**
+     * Called while a locale's write lock is blocked on another process holding it: once after the first
+     * failed acquire (with the holder's pid/acquiredAt when the lock file is readable), then periodically
+     * with the growing elapsed time. Never called for an uncontended run. The SDK writes no output; this
+     * 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 {
@@ -1568,7 +1816,7 @@ interface TranslateDeps {
  *
  * @param input - The validated config and run options (cwd, dryRun, prune, generatePlurals).
  * @param deps - Optional composition seams (registry, provider builder, file system) for tests.
- * @returns A {@link RunSummary}: the per-locale {@link LocaleSummary}s and the succeeded/failed locale lists.
+ * @returns A {@link RunSummary}: the per-locale {@link LocaleSummary}s and the succeeded/partial/failed locale lists.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
  * @throws {@link SdkError} `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw (this wraps the
  *   provider's own error, including a missing `*_API_KEY` reported as `MISSING_API_KEY`); only on a
@@ -1577,6 +1825,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";
@@ -1668,10 +1921,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
@@ -1750,7 +2006,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. */
@@ -1789,6 +2045,30 @@ interface WatchInput {
     readonly debounceMs?: number;
     /** Called once per run with its result. The SDK does no logging; this is the only output. */
     readonly onRun: (result: WatchRunResult) => void;
+    /**
+     * Passed through to every run's {@link TranslateInput.onLockWait}: called while a locale's write lock
+     * is blocked on another process, so a watch caller can surface the same "still waiting" progress a
+     * 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). The per-cycle tracker is fresh, so a budgeted watch
+     * with concurrency greater than 1 still fails each run with `CONCURRENCY_BUDGET_CONFLICT`.
+     */
+    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 {
@@ -1845,4 +2125,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 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 LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, 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 };