@verbatra/sdk 0.6.2 → 0.6.4

package/dist/index.d.cts

@@ -527,6 +527,7 @@ type GlossaryProvenance = {
     readonly path: string;
 };
 
+/** Where {@link loadConfig} should obtain the configuration. The three sources are alternatives. */
 interface LoadConfigOptions {
     /** Directory to start the search from. Defaults to the current working directory. */
     readonly cwd?: string;
@@ -972,7 +973,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 {
@@ -1348,7 +1349,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;
@@ -1432,7 +1433,27 @@ interface LocaleSummary {
      * {@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"`.
+     * 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";
     /**
@@ -1513,11 +1534,16 @@ interface LocaleSummary {
      */
     readonly needsReview: readonly NeedsReviewEntry[];
     /**
-     * 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.
+     * 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[];
     /**
@@ -1697,6 +1723,19 @@ interface LocaleFinishedEvent {
     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 {
@@ -2060,8 +2099,9 @@ interface WatchInput {
     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`.
+     * 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;
     /**
@@ -2095,9 +2135,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

package/dist/index.d.ts

@@ -527,6 +527,7 @@ type GlossaryProvenance = {
     readonly path: string;
 };
 
+/** Where {@link loadConfig} should obtain the configuration. The three sources are alternatives. */
 interface LoadConfigOptions {
     /** Directory to start the search from. Defaults to the current working directory. */
     readonly cwd?: string;
@@ -972,7 +973,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 {
@@ -1348,7 +1349,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;
@@ -1432,7 +1433,27 @@ interface LocaleSummary {
      * {@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"`.
+     * 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";
     /**
@@ -1513,11 +1534,16 @@ interface LocaleSummary {
      */
     readonly needsReview: readonly NeedsReviewEntry[];
     /**
-     * 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.
+     * 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[];
     /**
@@ -1697,6 +1723,19 @@ interface LocaleFinishedEvent {
     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 {
@@ -2060,8 +2099,9 @@ interface WatchInput {
     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`.
+     * 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;
     /**
@@ -2095,9 +2135,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