@verbatra/sdk 0.6.0 → 0.6.1

package/dist/index.d.cts

@@ -246,23 +246,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 +275,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. */
@@ -303,23 +308,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 +337,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]>>;
@@ -930,6 +940,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 +972,7 @@ type EditEntryResult = {
     readonly value: string;
 } | {
     readonly accepted: false;
-    readonly reason: "placeholder" | "icu";
+    readonly reason: IntegrityGateReason;
     readonly value: string;
 };
 /**
@@ -1248,7 +1261,7 @@ type RetranslateEntryResult = {
     readonly reviewReasons: readonly ReviewReasonCode[];
 } | {
     readonly accepted: false;
-    readonly reason: "placeholder" | "icu";
+    readonly reason: IntegrityGateReason;
     readonly value: string;
 };
 /**
@@ -1348,8 +1361,17 @@ interface NeedsReviewEntry {
 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.
+     */
+    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).
@@ -1419,9 +1441,13 @@ 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.
+     * 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 +1460,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 +1481,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 +1542,28 @@ 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;
+
 /** 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 +1585,19 @@ 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;
+    /**
+     * 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;
 }
 /** Composition seam: inject a registry, a provider builder, and a file system for tests. */
 interface TranslateDeps {
@@ -1568,7 +1635,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
@@ -1789,6 +1856,14 @@ 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.lockAcquireTimeoutMs}; the lock's 10-minute default when unset. */
+    readonly lockAcquireTimeoutMs?: number;
 }
 /** Composition seam: inject the watcher and the run for deterministic, offline tests. */
 interface WatchDeps {
@@ -1845,4 +1920,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, 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 };

package/dist/index.d.ts

@@ -246,23 +246,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 +275,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. */
@@ -303,23 +308,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 +337,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]>>;
@@ -930,6 +940,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 +972,7 @@ type EditEntryResult = {
     readonly value: string;
 } | {
     readonly accepted: false;
-    readonly reason: "placeholder" | "icu";
+    readonly reason: IntegrityGateReason;
     readonly value: string;
 };
 /**
@@ -1248,7 +1261,7 @@ type RetranslateEntryResult = {
     readonly reviewReasons: readonly ReviewReasonCode[];
 } | {
     readonly accepted: false;
-    readonly reason: "placeholder" | "icu";
+    readonly reason: IntegrityGateReason;
     readonly value: string;
 };
 /**
@@ -1348,8 +1361,17 @@ interface NeedsReviewEntry {
 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.
+     */
+    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).
@@ -1419,9 +1441,13 @@ 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.
+     * 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 +1460,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 +1481,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 +1542,28 @@ 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;
+
 /** 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 +1585,19 @@ 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;
+    /**
+     * 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;
 }
 /** Composition seam: inject a registry, a provider builder, and a file system for tests. */
 interface TranslateDeps {
@@ -1568,7 +1635,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
@@ -1789,6 +1856,14 @@ 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.lockAcquireTimeoutMs}; the lock's 10-minute default when unset. */
+    readonly lockAcquireTimeoutMs?: number;
 }
 /** Composition seam: inject the watcher and the run for deterministic, offline tests. */
 interface WatchDeps {
@@ -1845,4 +1920,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, 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 };