@verbatra/sdk 0.5.0-next.3 → 0.5.0-next.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -3,19 +3,6 @@ import Anthropic from '@anthropic-ai/sdk';
3
3
  import { Interactions } from '@google/genai';
4
4
  import OpenAI from 'openai';
5
5
 
6
- /** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
7
- declare const supportedFormatSchema$1: z.ZodEnum<{
8
- "i18next-json": "i18next-json";
9
- "vue-i18n-json": "vue-i18n-json";
10
- "next-intl-json": "next-intl-json";
11
- "ngx-translate-json": "ngx-translate-json";
12
- xliff: "xliff";
13
- yaml: "yaml";
14
- arb: "arb";
15
- }>;
16
- /** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
17
- type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
18
-
19
6
  /**
20
7
  * A single, format-neutral translation unit. Placeholders are supplied already
21
8
  * extracted; core never derives them from the value.
@@ -124,6 +111,24 @@ interface ProviderNotice {
124
111
  /** A static, safe description; never a key or translatable content. */
125
112
  readonly message: string;
126
113
  }
114
+ /**
115
+ * Stable codes for a derived, per-key "needs review" signal. This is verbatra's own computed
116
+ * assessment, never a raw model self-score: four are recomputable from plain source/translated
117
+ * values (see the shared heuristic function), and `PROVIDER_DEGRADED` is applied by the caller from
118
+ * a provider notice.
119
+ *
120
+ * - `LENGTH_RATIO_OUTLIER`: the translated value's length is far shorter or longer than the source's.
121
+ * - `EQUALS_SOURCE`: the translated value equals the source value verbatim.
122
+ * - `GLOSSARY_TERM_MISSED`: a configured glossary target term did not appear in the translation.
123
+ * - `INTEGRITY_REORDERED`: the placeholder set matched but landed in a different order.
124
+ * - `PROVIDER_DEGRADED`: the batch this key came from carried a graceful-degradation notice.
125
+ */
126
+ type ReviewReasonCode = "LENGTH_RATIO_OUTLIER" | "EQUALS_SOURCE" | "GLOSSARY_TERM_MISSED" | "INTEGRITY_REORDERED" | "PROVIDER_DEGRADED";
127
+ /** A key flagged for human review, carrying every reason code that applies. */
128
+ interface ReviewFlag {
129
+ readonly status: "review";
130
+ readonly reasons: readonly ReviewReasonCode[];
131
+ }
127
132
  /** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
128
133
  interface TranslateResult {
129
134
  /** The translated value for each requested key. */
@@ -138,6 +143,11 @@ interface TranslateResult {
138
143
  * report returns an empty array rather than omitting the field.
139
144
  */
140
145
  readonly notices?: readonly ProviderNotice[];
146
+ /**
147
+ * Derived per-key review flags for this batch. A key absent from the map is implicitly "ok"; a
148
+ * present key carries one or more {@link ReviewReasonCode}s. Optional and additive.
149
+ */
150
+ readonly reviewFlags?: ReadonlyMap<string, ReviewFlag>;
141
151
  }
142
152
  /**
143
153
  * The single contract every provider implements. It is narrow enough that a machine-translation API like
@@ -212,6 +222,19 @@ type GeminiModel = Interactions.Model;
212
222
  */
213
223
  type OpenAiModel = OpenAI.ChatModel;
214
224
 
225
+ /** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
226
+ declare const supportedFormatSchema$1: z.ZodEnum<{
227
+ "i18next-json": "i18next-json";
228
+ "vue-i18n-json": "vue-i18n-json";
229
+ "next-intl-json": "next-intl-json";
230
+ "ngx-translate-json": "ngx-translate-json";
231
+ xliff: "xliff";
232
+ yaml: "yaml";
233
+ arb: "arb";
234
+ }>;
235
+ /** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
236
+ type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
237
+
215
238
  /**
216
239
  * The provider section of the config: a discriminated union over the provider id, reusing each
217
240
  * provider's own config schema. There is no key field anywhere in this union except
@@ -314,6 +337,11 @@ declare const verbatraConfigSchema: z.ZodObject<{
314
337
  prune: z.ZodOptional<z.ZodBoolean>;
315
338
  generatePlurals: z.ZodOptional<z.ZodBoolean>;
316
339
  maxBatchSize: z.ZodOptional<z.ZodNumber>;
340
+ maxTokens: z.ZodOptional<z.ZodNumber>;
341
+ budgetBehavior: z.ZodOptional<z.ZodEnum<{
342
+ warn: "warn";
343
+ stop: "stop";
344
+ }>>;
317
345
  }, z.core.$strict>;
318
346
  /**
319
347
  * The as-authored (or as-parsed) shape of the verbatra configuration, straight from the schema: `glossary`
@@ -623,6 +651,13 @@ interface ReadResult {
623
651
  readonly resource: LocaleResource;
624
652
  /** Keys whose values are invalid for the format's message syntax. Empty for non-ICU formats. */
625
653
  readonly invalidIcuKeys: readonly string[];
654
+ /**
655
+ * Dotted paths of leaves that were present in the source but excluded because they are not
656
+ * strings (a stray number, boolean, or null). These are never translated, hashed, diffed, or
657
+ * checked for placeholder or ICU integrity, and are not written back if the file is later
658
+ * rewritten. Empty for a file with no such leaves.
659
+ */
660
+ readonly excludedLeafPaths: readonly string[];
626
661
  }
627
662
  /**
628
663
  * The contract every format adapter implements. A new format attaches by implementing this interface
@@ -907,7 +942,32 @@ interface LockStateDeps {
907
942
  declare function lockState(input: LockStateInput, deps?: LockStateDeps): Promise<LockStateResult>;
908
943
 
909
944
  /** A stable code for an SDK-originated notice (not a provider notice). */
910
- type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED";
945
+ type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED";
946
+ /** Summed token usage across every provider call in a scope (one locale, or the whole run). */
947
+ interface UsageSummary {
948
+ readonly inputTokens: number;
949
+ readonly outputTokens: number;
950
+ }
951
+ /** The configured token-budget behavior: warn and continue, or stop making further provider calls. */
952
+ type BudgetBehavior = "warn" | "stop";
953
+ /**
954
+ * The run-wide token-budget outcome, present on {@link RunSummary} only when `maxTokens` is configured.
955
+ * `supported: false` means the configured provider never reported usage in this run (a token-less
956
+ * provider such as DeepL, or a dry-run): the guardrail is honestly inert, `tokensUsed` stays `0`, and
957
+ * `exceeded` stays `false`, never a false trip.
958
+ */
959
+ interface RunBudget {
960
+ /** The configured ceiling. */
961
+ readonly maxTokens: number;
962
+ /** The configured behavior once the ceiling is reached. */
963
+ readonly behavior: BudgetBehavior;
964
+ /** Whether the configured provider reported usage at all this run. */
965
+ readonly supported: boolean;
966
+ /** Cumulative input plus output tokens across the run so far. */
967
+ readonly tokensUsed: number;
968
+ /** Whether `tokensUsed` reached or passed `maxTokens` at any point this run. */
969
+ readonly exceeded: boolean;
970
+ }
911
971
  /**
912
972
  * A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
913
973
  * so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
@@ -921,6 +981,13 @@ interface SdkNotice {
921
981
  }
922
982
  /** A notice on a locale summary: either a provider-emitted notice or an SDK-emitted one. */
923
983
  type LocaleNotice = ProviderNotice | SdkNotice;
984
+ /** One key flagged for human review, and every reason code that applies to it. */
985
+ interface NeedsReviewEntry {
986
+ /** The flagged key. */
987
+ readonly key: string;
988
+ /** Every {@link ReviewReasonCode} that applies to this key. */
989
+ readonly reasons: readonly ReviewReasonCode[];
990
+ }
924
991
  /** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
925
992
  interface LocaleSummary {
926
993
  /** The target locale this summary is for. */
@@ -966,12 +1033,35 @@ interface LocaleSummary {
966
1033
  * and acted, and empty in a dry-run.
967
1034
  */
968
1035
  readonly generated: readonly string[];
1036
+ /**
1037
+ * Candidate keys never sent to the provider because a configured `maxTokens` budget already tripped
1038
+ * in `"stop"` mode: keys remaining in the current locale once the ceiling was crossed, and every
1039
+ * candidate key of a later, fully-skipped locale. Always present, empty by default, same convention as
1040
+ * {@link LocaleSummary.integrityMismatches} and {@link LocaleSummary.providerFailures}. Each key keeps
1041
+ * its prior lock hash and is picked up again next run, exactly like a `providerFailures` key.
1042
+ */
1043
+ readonly budgetWithheld: readonly string[];
1044
+ /**
1045
+ * Summed token usage across every provider call for this locale (main translation plus plural
1046
+ * generation). Absent when no call in this locale reported usage: a dry-run, a token-less provider
1047
+ * (DeepL), or a locale with nothing to translate. Never a fabricated `{ inputTokens: 0, outputTokens: 0 }`.
1048
+ */
1049
+ readonly usage?: UsageSummary;
969
1050
  /**
970
1051
  * Notices for this locale: provider notices (e.g. DeepL graceful-degradation) and SDK notices
971
1052
  * (e.g. a target language needing more CLDR plural categories than the source supplies). Empty when
972
1053
  * nothing was degraded or flagged.
973
1054
  */
974
1055
  readonly notices: readonly LocaleNotice[];
1056
+ /**
1057
+ * Keys accepted and written this run that the review heuristics flagged for a second look, sorted
1058
+ * by key. Distinct from the placeholder/ICU integrity gate: a review flag is advisory only and never
1059
+ * withholds a key, so this never double-reports a key already surfaced through
1060
+ * {@link LocaleSummary.integrityMismatches} or {@link LocaleSummary.providerFailures}. Empty when
1061
+ * nothing was flagged, always empty for a workbook import (which never calls a provider or recomputes
1062
+ * flags on its own path).
1063
+ */
1064
+ readonly needsReview: readonly NeedsReviewEntry[];
975
1065
  /**
976
1066
  * Present only when status is "failed": a structured, secret-free error. `code` is a PRESERVED string
977
1067
  * (the underlying provider/adapter error's `code`, or `"LOCALE_FAILED"` as a fallback), intentionally
@@ -992,6 +1082,13 @@ interface RunSummary {
992
1082
  readonly succeeded: readonly string[];
993
1083
  /** Locales whose run failed (see each locale's `error`). */
994
1084
  readonly failed: readonly string[];
1085
+ /**
1086
+ * Summed token usage across every locale's {@link LocaleSummary.usage}. Absent when no locale in the
1087
+ * run reported usage (a dry-run, or an all-token-less-provider run).
1088
+ */
1089
+ readonly usage?: UsageSummary;
1090
+ /** The run-wide token-budget outcome; present only when `maxTokens` is configured. */
1091
+ readonly budget?: RunBudget;
995
1092
  }
996
1093
 
997
1094
  /** Builds the provider from its config. Injectable so tests stay offline. */
@@ -1317,4 +1414,4 @@ interface WatchController {
1317
1414
  */
1318
1415
  declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
1319
1416
 
1320
- export { type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type ProviderConfig, type ProviderId, 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 VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
1417
+ 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 ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type NeedsReviewEntry, type ProviderConfig, type ProviderId, type ReviewReasonCode, type RunBudget, 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, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
package/dist/index.d.ts CHANGED
@@ -3,19 +3,6 @@ import Anthropic from '@anthropic-ai/sdk';
3
3
  import { Interactions } from '@google/genai';
4
4
  import OpenAI from 'openai';
5
5
 
6
- /** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
7
- declare const supportedFormatSchema$1: z.ZodEnum<{
8
- "i18next-json": "i18next-json";
9
- "vue-i18n-json": "vue-i18n-json";
10
- "next-intl-json": "next-intl-json";
11
- "ngx-translate-json": "ngx-translate-json";
12
- xliff: "xliff";
13
- yaml: "yaml";
14
- arb: "arb";
15
- }>;
16
- /** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
17
- type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
18
-
19
6
  /**
20
7
  * A single, format-neutral translation unit. Placeholders are supplied already
21
8
  * extracted; core never derives them from the value.
@@ -124,6 +111,24 @@ interface ProviderNotice {
124
111
  /** A static, safe description; never a key or translatable content. */
125
112
  readonly message: string;
126
113
  }
114
+ /**
115
+ * Stable codes for a derived, per-key "needs review" signal. This is verbatra's own computed
116
+ * assessment, never a raw model self-score: four are recomputable from plain source/translated
117
+ * values (see the shared heuristic function), and `PROVIDER_DEGRADED` is applied by the caller from
118
+ * a provider notice.
119
+ *
120
+ * - `LENGTH_RATIO_OUTLIER`: the translated value's length is far shorter or longer than the source's.
121
+ * - `EQUALS_SOURCE`: the translated value equals the source value verbatim.
122
+ * - `GLOSSARY_TERM_MISSED`: a configured glossary target term did not appear in the translation.
123
+ * - `INTEGRITY_REORDERED`: the placeholder set matched but landed in a different order.
124
+ * - `PROVIDER_DEGRADED`: the batch this key came from carried a graceful-degradation notice.
125
+ */
126
+ type ReviewReasonCode = "LENGTH_RATIO_OUTLIER" | "EQUALS_SOURCE" | "GLOSSARY_TERM_MISSED" | "INTEGRITY_REORDERED" | "PROVIDER_DEGRADED";
127
+ /** A key flagged for human review, carrying every reason code that applies. */
128
+ interface ReviewFlag {
129
+ readonly status: "review";
130
+ readonly reasons: readonly ReviewReasonCode[];
131
+ }
127
132
  /** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
128
133
  interface TranslateResult {
129
134
  /** The translated value for each requested key. */
@@ -138,6 +143,11 @@ interface TranslateResult {
138
143
  * report returns an empty array rather than omitting the field.
139
144
  */
140
145
  readonly notices?: readonly ProviderNotice[];
146
+ /**
147
+ * Derived per-key review flags for this batch. A key absent from the map is implicitly "ok"; a
148
+ * present key carries one or more {@link ReviewReasonCode}s. Optional and additive.
149
+ */
150
+ readonly reviewFlags?: ReadonlyMap<string, ReviewFlag>;
141
151
  }
142
152
  /**
143
153
  * The single contract every provider implements. It is narrow enough that a machine-translation API like
@@ -212,6 +222,19 @@ type GeminiModel = Interactions.Model;
212
222
  */
213
223
  type OpenAiModel = OpenAI.ChatModel;
214
224
 
225
+ /** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
226
+ declare const supportedFormatSchema$1: z.ZodEnum<{
227
+ "i18next-json": "i18next-json";
228
+ "vue-i18n-json": "vue-i18n-json";
229
+ "next-intl-json": "next-intl-json";
230
+ "ngx-translate-json": "ngx-translate-json";
231
+ xliff: "xliff";
232
+ yaml: "yaml";
233
+ arb: "arb";
234
+ }>;
235
+ /** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
236
+ type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
237
+
215
238
  /**
216
239
  * The provider section of the config: a discriminated union over the provider id, reusing each
217
240
  * provider's own config schema. There is no key field anywhere in this union except
@@ -314,6 +337,11 @@ declare const verbatraConfigSchema: z.ZodObject<{
314
337
  prune: z.ZodOptional<z.ZodBoolean>;
315
338
  generatePlurals: z.ZodOptional<z.ZodBoolean>;
316
339
  maxBatchSize: z.ZodOptional<z.ZodNumber>;
340
+ maxTokens: z.ZodOptional<z.ZodNumber>;
341
+ budgetBehavior: z.ZodOptional<z.ZodEnum<{
342
+ warn: "warn";
343
+ stop: "stop";
344
+ }>>;
317
345
  }, z.core.$strict>;
318
346
  /**
319
347
  * The as-authored (or as-parsed) shape of the verbatra configuration, straight from the schema: `glossary`
@@ -623,6 +651,13 @@ interface ReadResult {
623
651
  readonly resource: LocaleResource;
624
652
  /** Keys whose values are invalid for the format's message syntax. Empty for non-ICU formats. */
625
653
  readonly invalidIcuKeys: readonly string[];
654
+ /**
655
+ * Dotted paths of leaves that were present in the source but excluded because they are not
656
+ * strings (a stray number, boolean, or null). These are never translated, hashed, diffed, or
657
+ * checked for placeholder or ICU integrity, and are not written back if the file is later
658
+ * rewritten. Empty for a file with no such leaves.
659
+ */
660
+ readonly excludedLeafPaths: readonly string[];
626
661
  }
627
662
  /**
628
663
  * The contract every format adapter implements. A new format attaches by implementing this interface
@@ -907,7 +942,32 @@ interface LockStateDeps {
907
942
  declare function lockState(input: LockStateInput, deps?: LockStateDeps): Promise<LockStateResult>;
908
943
 
909
944
  /** A stable code for an SDK-originated notice (not a provider notice). */
910
- type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED";
945
+ type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED";
946
+ /** Summed token usage across every provider call in a scope (one locale, or the whole run). */
947
+ interface UsageSummary {
948
+ readonly inputTokens: number;
949
+ readonly outputTokens: number;
950
+ }
951
+ /** The configured token-budget behavior: warn and continue, or stop making further provider calls. */
952
+ type BudgetBehavior = "warn" | "stop";
953
+ /**
954
+ * The run-wide token-budget outcome, present on {@link RunSummary} only when `maxTokens` is configured.
955
+ * `supported: false` means the configured provider never reported usage in this run (a token-less
956
+ * provider such as DeepL, or a dry-run): the guardrail is honestly inert, `tokensUsed` stays `0`, and
957
+ * `exceeded` stays `false`, never a false trip.
958
+ */
959
+ interface RunBudget {
960
+ /** The configured ceiling. */
961
+ readonly maxTokens: number;
962
+ /** The configured behavior once the ceiling is reached. */
963
+ readonly behavior: BudgetBehavior;
964
+ /** Whether the configured provider reported usage at all this run. */
965
+ readonly supported: boolean;
966
+ /** Cumulative input plus output tokens across the run so far. */
967
+ readonly tokensUsed: number;
968
+ /** Whether `tokensUsed` reached or passed `maxTokens` at any point this run. */
969
+ readonly exceeded: boolean;
970
+ }
911
971
  /**
912
972
  * A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
913
973
  * so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
@@ -921,6 +981,13 @@ interface SdkNotice {
921
981
  }
922
982
  /** A notice on a locale summary: either a provider-emitted notice or an SDK-emitted one. */
923
983
  type LocaleNotice = ProviderNotice | SdkNotice;
984
+ /** One key flagged for human review, and every reason code that applies to it. */
985
+ interface NeedsReviewEntry {
986
+ /** The flagged key. */
987
+ readonly key: string;
988
+ /** Every {@link ReviewReasonCode} that applies to this key. */
989
+ readonly reasons: readonly ReviewReasonCode[];
990
+ }
924
991
  /** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
925
992
  interface LocaleSummary {
926
993
  /** The target locale this summary is for. */
@@ -966,12 +1033,35 @@ interface LocaleSummary {
966
1033
  * and acted, and empty in a dry-run.
967
1034
  */
968
1035
  readonly generated: readonly string[];
1036
+ /**
1037
+ * Candidate keys never sent to the provider because a configured `maxTokens` budget already tripped
1038
+ * in `"stop"` mode: keys remaining in the current locale once the ceiling was crossed, and every
1039
+ * candidate key of a later, fully-skipped locale. Always present, empty by default, same convention as
1040
+ * {@link LocaleSummary.integrityMismatches} and {@link LocaleSummary.providerFailures}. Each key keeps
1041
+ * its prior lock hash and is picked up again next run, exactly like a `providerFailures` key.
1042
+ */
1043
+ readonly budgetWithheld: readonly string[];
1044
+ /**
1045
+ * Summed token usage across every provider call for this locale (main translation plus plural
1046
+ * generation). Absent when no call in this locale reported usage: a dry-run, a token-less provider
1047
+ * (DeepL), or a locale with nothing to translate. Never a fabricated `{ inputTokens: 0, outputTokens: 0 }`.
1048
+ */
1049
+ readonly usage?: UsageSummary;
969
1050
  /**
970
1051
  * Notices for this locale: provider notices (e.g. DeepL graceful-degradation) and SDK notices
971
1052
  * (e.g. a target language needing more CLDR plural categories than the source supplies). Empty when
972
1053
  * nothing was degraded or flagged.
973
1054
  */
974
1055
  readonly notices: readonly LocaleNotice[];
1056
+ /**
1057
+ * Keys accepted and written this run that the review heuristics flagged for a second look, sorted
1058
+ * by key. Distinct from the placeholder/ICU integrity gate: a review flag is advisory only and never
1059
+ * withholds a key, so this never double-reports a key already surfaced through
1060
+ * {@link LocaleSummary.integrityMismatches} or {@link LocaleSummary.providerFailures}. Empty when
1061
+ * nothing was flagged, always empty for a workbook import (which never calls a provider or recomputes
1062
+ * flags on its own path).
1063
+ */
1064
+ readonly needsReview: readonly NeedsReviewEntry[];
975
1065
  /**
976
1066
  * Present only when status is "failed": a structured, secret-free error. `code` is a PRESERVED string
977
1067
  * (the underlying provider/adapter error's `code`, or `"LOCALE_FAILED"` as a fallback), intentionally
@@ -992,6 +1082,13 @@ interface RunSummary {
992
1082
  readonly succeeded: readonly string[];
993
1083
  /** Locales whose run failed (see each locale's `error`). */
994
1084
  readonly failed: readonly string[];
1085
+ /**
1086
+ * Summed token usage across every locale's {@link LocaleSummary.usage}. Absent when no locale in the
1087
+ * run reported usage (a dry-run, or an all-token-less-provider run).
1088
+ */
1089
+ readonly usage?: UsageSummary;
1090
+ /** The run-wide token-budget outcome; present only when `maxTokens` is configured. */
1091
+ readonly budget?: RunBudget;
995
1092
  }
996
1093
 
997
1094
  /** Builds the provider from its config. Injectable so tests stay offline. */
@@ -1317,4 +1414,4 @@ interface WatchController {
1317
1414
  */
1318
1415
  declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
1319
1416
 
1320
- export { type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type ProviderConfig, type ProviderId, 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 VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
1417
+ 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 ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type NeedsReviewEntry, type ProviderConfig, type ProviderId, type ReviewReasonCode, type RunBudget, 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, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };