@verbatra/sdk 0.5.0-next.3 → 0.5.0

package/dist/index.d.ts

@@ -3,19 +3,6 @@ import Anthropic from '@anthropic-ai/sdk';
 import { Interactions } from '@google/genai';
 import OpenAI from 'openai';
 
-/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
-declare const supportedFormatSchema$1: z.ZodEnum<{
-    "i18next-json": "i18next-json";
-    "vue-i18n-json": "vue-i18n-json";
-    "next-intl-json": "next-intl-json";
-    "ngx-translate-json": "ngx-translate-json";
-    xliff: "xliff";
-    yaml: "yaml";
-    arb: "arb";
-}>;
-/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
-type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
-
 /**
  * A single, format-neutral translation unit. Placeholders are supplied already
  * extracted; core never derives them from the value.
@@ -124,6 +111,24 @@ interface ProviderNotice {
     /** A static, safe description; never a key or translatable content. */
     readonly message: string;
 }
+/**
+ * Stable codes for a derived, per-key "needs review" signal. This is verbatra's own computed
+ * assessment, never a raw model self-score: four are recomputable from plain source/translated
+ * values (see the shared heuristic function), and `PROVIDER_DEGRADED` is applied by the caller from
+ * a provider notice.
+ *
+ * - `LENGTH_RATIO_OUTLIER`: the translated value's length is far shorter or longer than the source's.
+ * - `EQUALS_SOURCE`: the translated value equals the source value verbatim.
+ * - `GLOSSARY_TERM_MISSED`: a configured glossary target term did not appear in the translation.
+ * - `INTEGRITY_REORDERED`: the placeholder set matched but landed in a different order.
+ * - `PROVIDER_DEGRADED`: the batch this key came from carried a graceful-degradation notice.
+ */
+type ReviewReasonCode = "LENGTH_RATIO_OUTLIER" | "EQUALS_SOURCE" | "GLOSSARY_TERM_MISSED" | "INTEGRITY_REORDERED" | "PROVIDER_DEGRADED";
+/** A key flagged for human review, carrying every reason code that applies. */
+interface ReviewFlag {
+    readonly status: "review";
+    readonly reasons: readonly ReviewReasonCode[];
+}
 /** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
 interface TranslateResult {
     /** The translated value for each requested key. */
@@ -138,6 +143,11 @@ interface TranslateResult {
      * report returns an empty array rather than omitting the field.
      */
     readonly notices?: readonly ProviderNotice[];
+    /**
+     * Derived per-key review flags for this batch. A key absent from the map is implicitly "ok"; a
+     * present key carries one or more {@link ReviewReasonCode}s. Optional and additive.
+     */
+    readonly reviewFlags?: ReadonlyMap<string, ReviewFlag>;
 }
 /**
  * The single contract every provider implements. It is narrow enough that a machine-translation API like
@@ -212,6 +222,19 @@ type GeminiModel = Interactions.Model;
  */
 type OpenAiModel = OpenAI.ChatModel;
 
+/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
+declare const supportedFormatSchema$1: z.ZodEnum<{
+    "i18next-json": "i18next-json";
+    "vue-i18n-json": "vue-i18n-json";
+    "next-intl-json": "next-intl-json";
+    "ngx-translate-json": "ngx-translate-json";
+    xliff: "xliff";
+    yaml: "yaml";
+    arb: "arb";
+}>;
+/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
+type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
+
 /**
  * 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
@@ -250,7 +273,9 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         apiKeyEnvVar: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strip>], "id">;
+/** One validated provider section: the provider id plus that provider's own options. */
 type ProviderConfig = z.infer<typeof providerConfigSchema>;
+/** The closed set of configurable provider ids. */
 type ProviderId = ProviderConfig["id"];
 
 /**
@@ -314,6 +339,11 @@ declare const verbatraConfigSchema: z.ZodObject<{
     prune: z.ZodOptional<z.ZodBoolean>;
     generatePlurals: z.ZodOptional<z.ZodBoolean>;
     maxBatchSize: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    budgetBehavior: z.ZodOptional<z.ZodEnum<{
+        warn: "warn";
+        stop: "stop";
+    }>>;
 }, z.core.$strict>;
 /**
  * The as-authored (or as-parsed) shape of the verbatra configuration, straight from the schema: `glossary`
@@ -332,7 +362,14 @@ type VerbatraConfig = Omit<VerbatraConfigInput, "glossary"> & {
     glossary?: Readonly<Record<string, string>>;
 };
 
+/**
+ * A provider's known model literals, with the open `string` arm stripped, so the authoring field
+ * accepts only that provider's models. Static authoring aid only; the runtime schema stays a
+ * non-empty string, so a brand-new model the installed SDK does not yet list is flagged but still
+ * runs.
+ */
 type KnownModels<M extends string> = M extends string ? (string extends M ? never : M) : never;
+/** One provider's config variant with `options.model` narrowed to that provider's known literals. */
 type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<ProviderConfig, {
     id: Id;
 }> extends infer Variant ? Variant extends {
@@ -344,6 +381,12 @@ type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<Provide
         model: KnownModels<M>;
     };
 } : never : never;
+/**
+ * The authoring view of one provider variant, keyed by id. LLM providers with a known SDK model
+ * union restrict `options.model` to that provider's literals. DeepL has no model field and
+ * openai-compatible's model is whatever the local server exposes (no known-model list to restrict
+ * against), so both are carried through unchanged.
+ */
 type AuthoringProviderVariant = {
     anthropic: AuthoringVariant<"anthropic", AnthropicModel>;
     openai: AuthoringVariant<"openai", OpenAiModel>;
@@ -429,9 +472,19 @@ interface SdkFs {
     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, recorded for later Studio consumption. */
+/** Where a config's resolved glossary came from: absent, inline, or a file at the recorded path. */
 type GlossaryProvenance = {
     readonly source: "none";
 } | {
@@ -533,22 +586,35 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *
  * - `CONFIG_NOT_FOUND`: no config was found by search, or an explicit `configPath` does not exist
  *   (thrown by `loadConfig`).
- * - `CONFIG_INVALID`: a config was found but is unparseable or fails validation (thrown by `loadConfig`).
- * - `UNKNOWN_FORMAT`: no adapter is registered for the configured format (thrown by `translate`).
- * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales (thrown by
- *   `check`, `diff`, and `exportWorkbook` via the shared locale selection).
- * - `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw; wraps the provider's own error, including
- *   a missing `*_API_KEY` reported as `MISSING_API_KEY` (thrown by `translate`, non-dry-run only).
- * - `SOURCE_UNREADABLE`: the source locale file is absent (thrown by `translate`, and by `watch` at startup).
- * - `SOURCE_INVALID`: the source locale file could not be read or parsed; wraps the adapter read error
- *   (thrown by `translate`).
+ * - `CONFIG_INVALID`: a config was found but is unparseable or fails validation, or its glossary
+ *   file path could not be resolved (thrown by `loadConfig`).
+ * - `UNKNOWN_FORMAT`: no adapter is registered for the configured format (thrown by every entry
+ *   point that selects an adapter, before any file is read).
+ * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales (thrown via
+ *   the shared locale selection by `check`, `diff`, `keyIntegrity`, `lockState`, `exportWorkbook`,
+ *   `keyValue`, `editEntry`, and `retranslateEntry`).
+ * - `UNKNOWN_KEY`: a requested key is not among the source resource's own keys (thrown by
+ *   `keyValue`, `editEntry`, and `retranslateEntry`).
+ * - `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw; wraps the provider's own error,
+ *   including a missing `*_API_KEY` reported as `MISSING_API_KEY` (thrown by non-dry-run
+ *   `translate` and by `retranslateEntry`).
+ * - `SOURCE_UNREADABLE`: the source locale file is absent (thrown by every entry point that reads
+ *   the source, and by `watch` at startup).
+ * - `SOURCE_INVALID`: the source locale file could not be read or parsed; wraps the adapter read
+ *   error (thrown by every entry point that reads the source).
  * - `LOCK_FILE_INVALID`: the lock-file is present but corrupt, oversized, or at an unsupported
- *   version (thrown by `translate`, `check`, `diff`, `exportWorkbook`, and `importWorkbook`).
+ *   version (thrown wherever the lock-file is read or updated: `translate`, `check`, `diff`,
+ *   `keyIntegrity`, `lockState`, `loadLockFile`, `exportWorkbook`, `importWorkbook`, `editEntry`,
+ *   and `retranslateEntry`).
+ * - `LOCK_CONTENDED`: a locale's write lock (`withLocaleWriteLock`) could not be acquired before
+ *   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`).
  * - `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`.
+ *   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" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "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" | "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. */
@@ -623,6 +689,13 @@ interface ReadResult {
     readonly resource: LocaleResource;
     /** Keys whose values are invalid for the format's message syntax. Empty for non-ICU formats. */
     readonly invalidIcuKeys: readonly string[];
+    /**
+     * Dotted paths of leaves that were present in the source but excluded because they are not
+     * strings (a stray number, boolean, or null). These are never translated, hashed, diffed, or
+     * checked for placeholder or ICU integrity, and are not written back if the file is later
+     * rewritten. Empty for a file with no such leaves.
+     */
+    readonly excludedLeafPaths: readonly string[];
 }
 /**
  * The contract every format adapter implements. A new format attaches by implementing this interface
@@ -740,6 +813,11 @@ declare class AdapterRegistry {
     register(adapter: FormatAdapter): this;
     private formats;
     private resolveByFormat;
+    /**
+     * Resolve by asking every registered adapter's `canHandle`. Several adapters can claim one file
+     * (all JSON adapters claim `.json`), so more than one match is reported as `ambiguous` rather
+     * than guessed at.
+     */
     private resolveByDetection;
     /**
      * Resolve the adapter for a file, by explicit format when given, otherwise by detection.
@@ -787,10 +865,11 @@ interface CheckDeps {
     readonly fs?: SdkFs;
 }
 /**
- * Report which keys are missing or stale per target locale, without calling a provider, writing any
- * file, or touching the lock. Each locale is reported as counts only (missing, stale, up-to-date);
- * a locale is `inSync` when nothing is missing or stale, and the top-level `inSync` is true only when
- * every checked locale is. Orphaned keys and integrity are not reported, since they concern a write.
+ * Reports how many keys are missing or stale per target locale, without calling a provider, writing
+ * any file, or touching the lock. Each locale is reported as counts only (missing, stale,
+ * up-to-date); a locale is `inSync` when nothing is missing or stale, and the top-level `inSync` is
+ * true only when every checked locale is. Orphaned keys and integrity are not reported, since they
+ * concern a write; use {@link diff} for the key lists.
  *
  * @param input - The validated config and which locales to check.
  * @param deps - Optional composition seams (registry, file system) for tests.
@@ -836,11 +915,11 @@ interface DiffDeps {
     readonly fs?: SdkFs;
 }
 /**
- * Report the exact pending change per target locale as three key lists (missing, changed, orphaned),
- * without calling a provider, writing any file, or touching the lock. This is the detailed sibling of
- * {@link check}. A locale's `hasPendingChanges` is driven by missing or changed only; orphaned keys are
- * reported but do not flip it, since a default `translate` run does not prune. The top-level
- * `hasPendingChanges` is true when any checked locale has pending changes.
+ * Reports the exact pending change per target locale as three key lists (missing, changed,
+ * orphaned), without calling a provider, writing any file, or touching the lock. The detailed
+ * sibling of {@link check}. A locale's `hasPendingChanges` is driven by missing or changed only;
+ * orphaned keys are reported but do not flip it, since a default `translate` run does not prune.
+ * The top-level `hasPendingChanges` is true when any checked locale has pending changes.
  *
  * @param input - The validated config and which locales to diff.
  * @param deps - Optional composition seams (registry, file system) for tests.
@@ -851,6 +930,238 @@ interface DiffDeps {
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
+/** 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}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** The target locale to write the correction into. Must be a configured target locale. */
+    readonly locale: string;
+    /** The source key being corrected. Must exist in the source resource. */
+    readonly key: string;
+    /** The human-typed replacement value. */
+    readonly value: string;
+}
+/** Composition seam for {@link editEntry}: inject a registry and a file system for tests. No provider builder: this seam never calls a provider. */
+interface EditEntryDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * The two-armed result of one edit attempt: acceptance carries the newly written value; a
+ * rejection carries the candidate value and which {@link gateCandidateValue} check failed it,
+ * with nothing written. Deliberately has no review-reasons field: a human-typed correction never
+ * touches a provider, so there is no provider-derived review signal to report.
+ */
+type EditEntryResult = {
+    readonly accepted: true;
+    readonly value: string;
+} | {
+    readonly accepted: false;
+    readonly reason: "placeholder" | "icu";
+    readonly value: string;
+};
+/**
+ * Writes exactly one human-typed correction for exactly one target locale, gated through the
+ * shared {@link gateCandidateValue} before anything reaches disk. On acceptance, writes the target
+ * 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.
+ *
+ * `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.
+ *
+ * The target-file write and the lock-file update run inside one held `withLocaleWriteLock`
+ * critical section, so no second writer for this locale can observe the target file updated but
+ * the lock entry not yet, or vice versa. Reading the source, resolving the key, and selecting the
+ * adapter stay outside the lock: they are read-only and need no protection.
+ *
+ * Never touches `.verbatra-local/run-status.json`: that file is rewritten wholesale by
+ * `translate()`/`watch()` outside any locale lock, so patching it here would race that rewrite. A
+ * key edited here stays stale in that persisted snapshot until the next real run, which self-heals
+ * it since this call already advanced the lock hash.
+ *
+ * @param input - The validated config, the target locale, the source key, and the replacement value.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns The two-armed {@link EditEntryResult}.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: `locale` is not among `config.targetLocales`.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE` / `SOURCE_INVALID`: the source locale file is absent
+ *   or unreadable.
+ * @throws {@link SdkError} `UNKNOWN_KEY`: `key` does not exist in the source resource.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ *   unsupported version.
+ * @throws {@link SdkError} `LOCK_CONTENDED`: this locale's write lock could not be acquired before
+ *   its timeout, because another process is holding it.
+ */
+declare function editEntry(input: EditEntryInput, deps?: EditEntryDeps): Promise<EditEntryResult>;
+
+/**
+ * One key's placeholder and ICU integrity result for one target locale. Only ever computed for a
+ * "changed" key (a current source and a current target value both exist). `hasPlaceholders` is
+ * false when the source value carries no placeholders, in which case `matches` is trivially true
+ * and carries no signal on its own. `icuValid` is computed unconditionally, independent of
+ * `matches`: unlike `gateCandidateValue`, which stops at the first failing check, this is an
+ * information report and stays accurate even when the key already fails on placeholders; it is
+ * always true for a non-ICU format. Carries no source or target string value: only the boolean
+ * results and, on a placeholder mismatch, the specific tokens involved.
+ */
+interface KeyIntegrityEntry {
+    readonly key: string;
+    readonly hasPlaceholders: boolean;
+    readonly matches: boolean;
+    readonly missing: readonly string[];
+    readonly extra: readonly string[];
+    readonly icuValid: boolean;
+}
+/** One target locale's integrity entries for the keys checked against it. */
+interface LocaleKeyIntegrity {
+    readonly locale: string;
+    readonly entries: readonly KeyIntegrityEntry[];
+}
+/** Input for {@link keyIntegrity}: the validated config, which locales to check, and an optional key filter. */
+interface KeyIntegrityInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** Subset of target locales to check; defaults to all configured target locales. */
+    readonly locales?: readonly string[];
+    /** Restrict the check to these keys; only the ones that are "changed" for a locale are checked. Defaults to every changed key. */
+    readonly keys?: readonly string[];
+}
+/** Composition seam for {@link keyIntegrity}: inject a registry and a file system for tests. */
+interface KeyIntegrityDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Runs the placeholder check and the ICU message-validity check for each selected target locale's
+ * "changed" keys (present with a current value on both sides, per core's `diffResources`) and
+ * reports a per-key result. Uses the adapter's own `comparePlaceholders` when present (the
+ * branch-aware ICU path), otherwise core's `checkPlaceholders` over the stored placeholder lists.
+ * `icuValid` is `adapter.validateMessage(target)`, computed unconditionally and independently of
+ * the placeholder result, so a target that is placeholder-valid but syntactically invalid ICU is
+ * still reported accurately. Read-only: it calls no provider, writes no file, and never touches
+ * the lock. Missing and orphaned keys are never checked, since one side's value does not exist for
+ * those.
+ *
+ * The returned entries never carry a source or target string value, only the boolean results and,
+ * on a placeholder mismatch, the specific tokens involved.
+ *
+ * @param input - The validated config, which locales to check, and an optional key filter.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns One entry per checked locale, each carrying the integrity result for its changed keys
+ *   (narrowed to `input.keys` when supplied).
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`,
+ *   `LOCK_FILE_INVALID`, or `UNKNOWN_LOCALE`, with the same meanings as in {@link diff}.
+ */
+declare function keyIntegrity(input: KeyIntegrityInput, deps?: KeyIntegrityDeps): Promise<readonly LocaleKeyIntegrity[]>;
+
+/** Input for {@link keyValue}: the validated config and exactly one target locale/key pair. */
+interface KeyValueInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern resolves against; defaults to cwd. */
+    readonly cwd?: string;
+    /** The target locale to read the current translation from. Must be a configured target locale. */
+    readonly locale: string;
+    /** The source key to read. Must exist in the source resource. */
+    readonly key: string;
+}
+/** Composition seam for {@link keyValue}: inject a registry and a file system for tests. */
+interface KeyValueDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * The current source and target values for one key/locale pair. `target` is absent exactly when
+ * the key does not yet exist in that target locale; a present-but-empty-string target is a real
+ * value and is returned as such.
+ */
+interface KeyValueResult {
+    readonly source: string;
+    readonly target?: string;
+}
+/**
+ * Reads a key's current source and target values for exactly one target locale. Read-only: it
+ * calls no provider, writes no file, and mutates nothing. Exposes only the current values on disk,
+ * never a previous one.
+ *
+ * `locale` and `key` are resolved fresh on every call, so a caller feeding an edit dialog with
+ * this result and then submitting through `editEntry` is always working from live data, never a
+ * cached snapshot.
+ *
+ * @param input - The validated config, the target locale, and the source key to read.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns The current source value and, when present, the current target value.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: `locale` is not among `config.targetLocales`.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE` / `SOURCE_INVALID`: the source locale file is absent
+ *   or unreadable.
+ * @throws {@link SdkError} `UNKNOWN_KEY`: `key` does not exist in the source resource.
+ */
+declare function keyValue(input: KeyValueInput, deps?: KeyValueDeps): Promise<KeyValueResult>;
+
+/**
+ * One locale file reduced to a content hash per key, taken at one point in time. Two snapshots of
+ * the same file can be compared with {@link diffLocaleSnapshots} to count what changed between
+ * them.
+ */
+interface LocaleFileSnapshot {
+    /** The locale this snapshot was read for (the configured source locale or a target locale). */
+    readonly locale: string;
+    /** Content hash per key, from core's `contentHash`. */
+    readonly hashes: ReadonlyMap<string, string>;
+}
+/** Input for {@link readLocaleFileSnapshot}: the validated config and which locale to snapshot. */
+interface ReadLocaleFileSnapshotInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** The locale to snapshot: the configured source locale or any configured target locale. */
+    readonly locale: string;
+    /** Directory the file pattern resolves against; defaults to cwd. */
+    readonly cwd?: string;
+}
+/** Composition seam for {@link readLocaleFileSnapshot}: inject a registry and a file system for tests. */
+interface ReadLocaleFileSnapshotDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Reads one locale file through the configured adapter and reduces it to a content hash per key.
+ * Uses the same tolerant read path as {@link readTarget}: a file that does not exist yet reads as
+ * an empty snapshot rather than throwing, so a caller can establish a baseline before a locale's
+ * first write.
+ *
+ * @param input - The validated config, the locale to snapshot, and the directory to resolve against.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns The locale's per-key content hash snapshot.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT` when the configured format has no registered adapter;
+ *   rejects with the adapter's own error when the file exists but its content is malformed.
+ */
+declare function readLocaleFileSnapshot(input: ReadLocaleFileSnapshotInput, deps?: ReadLocaleFileSnapshotDeps): Promise<LocaleFileSnapshot>;
+/** A locale file's added, changed, and removed key counts between two of its own snapshots. Counts only, never key names. */
+interface LocaleSnapshotDelta {
+    readonly added: number;
+    readonly changed: number;
+    readonly removed: number;
+}
+/**
+ * Compares two snapshots of the same locale file, taken at different points in time, and counts
+ * how many keys were added, changed, or removed. A direct key-to-hash comparison rather than
+ * core's `diffResources`: that function's source/target/baseline shape exists for cross-resource
+ * comparison, and forcing a same-file, two-points-in-time comparison through it would need a
+ * confusing relabeling (missing becomes removed, orphaned becomes added).
+ *
+ * @param previous - The earlier snapshot of the file.
+ * @param current - The later snapshot of the same file.
+ * @returns The counts of keys added, changed, and removed between the two snapshots.
+ */
+declare function diffLocaleSnapshots(previous: LocaleFileSnapshot, current: LocaleFileSnapshot): LocaleSnapshotDelta;
+
 /** Per-locale key count and drift against the source and target files, from the recorded lock baseline. */
 interface LockLocaleState {
     /** The target locale this entry reports on. */
@@ -906,8 +1217,113 @@ interface LockStateDeps {
  */
 declare function lockState(input: LockStateInput, deps?: LockStateDeps): Promise<LockStateResult>;
 
+/** Builds the provider from its config. Injectable so tests stay offline. */
+type CreateProvider = (config: ProviderConfig) => TranslationProvider;
+
+/** Input for {@link retranslateEntry}: the validated config and exactly one target locale/key pair. */
+interface RetranslateEntryInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** The target locale to retranslate the key into. Must be a configured target locale. */
+    readonly locale: string;
+    /** The source key to retranslate. Must exist in the source resource. */
+    readonly key: string;
+}
+/** Composition seam for {@link retranslateEntry}: inject a registry, a provider builder, and a file system for tests. */
+interface RetranslateEntryDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly createProvider?: CreateProvider;
+    readonly fs?: SdkFs;
+}
+/**
+ * The two-armed result of one retranslate attempt: `accepted` carries the newly written value and
+ * any derived "needs review" reasons; a rejection carries the candidate value and which
+ * {@link gateCandidateValue} check failed it, without writing anything.
+ */
+type RetranslateEntryResult = {
+    readonly accepted: true;
+    readonly value: string;
+    readonly reviewReasons: readonly ReviewReasonCode[];
+} | {
+    readonly accepted: false;
+    readonly reason: "placeholder" | "icu";
+    readonly value: string;
+};
+/**
+ * Retranslate exactly one key for exactly one target locale: a single-entry `translateBatch` call
+ * through the same provider registry `translate()` uses, gated through the shared
+ * {@link gateCandidateValue} before anything reaches disk. On acceptance, writes the target 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. Reuses exactly the building blocks `translate()` already uses
+ * (`selectProvider`/`provider.translateBatch`) and nothing else: no bespoke per-provider plumbing.
+ *
+ * `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
+ * fresh from disk (`UNKNOWN_KEY`), via a `Map`-backed lookup, never `key in obj` or
+ * `obj[key] !== undefined` against a plain object.
+ *
+ * The target-file write and the lock-file update run inside the same held
+ * `withLocaleWriteLock(cwd, locale, fs, ...)` critical section as the provider call itself, so no
+ * second writer for this locale can ever observe the target file updated but the lock entry not
+ * yet, or vice versa. The same locking also covers `translate()`/`watch()` and `importWorkbook()`.
+ *
+ * Not atomic across the two writes for a single caller's own run: the target locale file is
+ * written before the lock entry is updated. If `updateLockFileLocale` then throws
+ * (`LOCK_FILE_INVALID` for a corrupt lock-file, or `LOCK_CONTENDED` if its own internal lock-file
+ * guard cannot be acquired before its timeout), the target file already carries the new value
+ * while the lock still records the old hash, and the thrown error does not imply nothing was
+ * saved. The same ordering, and the same partial-write shape on that rare path, also exists in
+ * `translate()` and `importWorkbook()`.
+ *
+ * @param input - The validated config, the target locale, and the source key to retranslate.
+ * @param deps - Optional composition seams (registry, provider builder, file system) for tests.
+ * @returns The two-armed {@link RetranslateEntryResult}.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: `locale` is not among `config.targetLocales`.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE` / `SOURCE_INVALID`: the source locale file is absent
+ *   or unreadable.
+ * @throws {@link SdkError} `UNKNOWN_KEY`: `key` does not exist in the source resource.
+ * @throws {@link SdkError} `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw (wraps a
+ *   missing `*_API_KEY` as `MISSING_API_KEY`).
+ * @throws {@link ProviderError} the provider call itself failed, or returned no value at all for
+ *   this key (`INVALID_RESPONSE`).
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ *   unsupported version.
+ * @throws {@link SdkError} `LOCK_CONTENDED`: this locale's write lock could not be acquired before
+ *   its timeout, because another process (another CLI run, or a second Studio write) is holding it.
+ */
+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";
+type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED";
+/** Summed token usage across every provider call in a scope (one locale, or the whole run). */
+interface UsageSummary {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+/** The configured token-budget behavior: warn and continue, or stop making further provider calls. */
+type BudgetBehavior = "warn" | "stop";
+/**
+ * The run-wide token-budget outcome, present on {@link RunSummary} only when `maxTokens` is configured.
+ * `supported: false` means the configured provider never reported usage in this run (a token-less
+ * provider such as DeepL, or a dry-run): the guardrail is honestly inert, `tokensUsed` stays `0`, and
+ * `exceeded` stays `false`, never a false trip.
+ */
+interface RunBudget {
+    /** The configured ceiling. */
+    readonly maxTokens: number;
+    /** The configured behavior once the ceiling is reached. */
+    readonly behavior: BudgetBehavior;
+    /** Whether the configured provider reported usage at all this run. */
+    readonly supported: boolean;
+    /** Cumulative input plus output tokens across the run so far. */
+    readonly tokensUsed: number;
+    /** Whether `tokensUsed` reached or passed `maxTokens` at any point this run. */
+    readonly exceeded: boolean;
+}
 /**
  * A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
  * so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
@@ -921,6 +1337,13 @@ interface SdkNotice {
 }
 /** A notice on a locale summary: either a provider-emitted notice or an SDK-emitted one. */
 type LocaleNotice = ProviderNotice | SdkNotice;
+/** One key flagged for human review, and every reason code that applies to it. */
+interface NeedsReviewEntry {
+    /** The flagged key. */
+    readonly key: string;
+    /** Every {@link ReviewReasonCode} that applies to this key. */
+    readonly reasons: readonly ReviewReasonCode[];
+}
 /** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
 interface LocaleSummary {
     /** The target locale this summary is for. */
@@ -928,7 +1351,7 @@ interface LocaleSummary {
     /** Whether this locale's run succeeded or failed (a failure does not abort the run). */
     readonly status: "succeeded" | "failed";
     /**
-     * Keys translated and written this run. In dry-run, the keys that WOULD be translated
+     * Keys translated and written this run. In dry-run, the keys that would be translated
      * (the provider is not called and nothing is written).
      */
     readonly translated: readonly string[];
@@ -938,7 +1361,7 @@ interface LocaleSummary {
     readonly orphaned: readonly string[];
     /**
      * Orphaned keys actually removed this run because pruning was on. In a dry-run with pruning on, the keys
-     * that WOULD be removed. Empty when pruning is off (the orphans then survive and are reported in
+     * that would be removed. Empty when pruning is off (the orphans then survive and are reported in
      * `orphaned` only). A subset of `orphaned`; never includes a source-present key.
      */
     readonly pruned: readonly string[];
@@ -966,6 +1389,20 @@ interface LocaleSummary {
      * and acted, and empty in a dry-run.
      */
     readonly generated: readonly string[];
+    /**
+     * Candidate keys never sent to the provider because a configured `maxTokens` budget already tripped
+     * in `"stop"` mode: keys remaining in the current locale once the ceiling was crossed, and every
+     * candidate key of a later, fully-skipped locale. Always present, empty by default, same convention as
+     * {@link LocaleSummary.integrityMismatches} and {@link LocaleSummary.providerFailures}. Each key keeps
+     * its prior lock hash and is picked up again next run, exactly like a `providerFailures` key.
+     */
+    readonly budgetWithheld: readonly string[];
+    /**
+     * Summed token usage across every provider call for this locale (main translation plus plural
+     * generation). Absent when no call in this locale reported usage: a dry-run, a token-less provider
+     * (DeepL), or a locale with nothing to translate. Never a fabricated `{ inputTokens: 0, outputTokens: 0 }`.
+     */
+    readonly usage?: UsageSummary;
     /**
      * Notices for this locale: provider notices (e.g. DeepL graceful-degradation) and SDK notices
      * (e.g. a target language needing more CLDR plural categories than the source supplies). Empty when
@@ -973,7 +1410,16 @@ interface LocaleSummary {
      */
     readonly notices: readonly LocaleNotice[];
     /**
-     * Present only when status is "failed": a structured, secret-free error. `code` is a PRESERVED string
+     * Keys accepted and written this run that the review heuristics flagged for a second look, sorted
+     * by key. Distinct from the placeholder/ICU integrity gate: a review flag is advisory only and never
+     * withholds a key, so this never double-reports a key already surfaced through
+     * {@link LocaleSummary.integrityMismatches} or {@link LocaleSummary.providerFailures}. Empty when
+     * nothing was flagged, always empty for a workbook import (which never calls a provider or recomputes
+     * flags on its own path).
+     */
+    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.
      */
@@ -992,10 +1438,77 @@ interface RunSummary {
     readonly succeeded: readonly string[];
     /** Locales whose run 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
+     * run reported usage (a dry-run, or an all-token-less-provider run).
+     */
+    readonly usage?: UsageSummary;
+    /** The run-wide token-budget outcome; present only when `maxTokens` is configured. */
+    readonly budget?: RunBudget;
 }
 
-/** Builds the provider from its config. Injectable so tests stay offline. */
-type CreateProvider = (config: ProviderConfig) => TranslationProvider;
+/**
+ * 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".
+ */
+interface RunStatusLocale {
+    readonly locale: string;
+    readonly status: "succeeded" | "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. */
+    readonly usage?: UsageSummary;
+}
+/**
+ * The persisted shape of `.verbatra-local/run-status.json`: one whole-run snapshot, overwritten on
+ * every non-dry-run `translate()`/`watch()` run that reaches the end of its per-locale loop. Contains
+ * only the review-flag and token/usage data already computed for `RunSummary`; never a translation
+ * string, a provider error message, or a provider notice message.
+ */
+interface RunStatusFile {
+    readonly version: number;
+    /** ISO timestamp of when this snapshot was written. */
+    readonly generatedAt: string;
+    /** Summed run-wide token usage, mirroring `RunSummary.usage`; absent under the same conditions. */
+    readonly usage?: UsageSummary;
+    /** The run-wide token-budget outcome, mirroring `RunSummary.budget`; present only when configured. */
+    readonly budget?: RunBudget;
+    readonly locales: readonly RunStatusLocale[];
+}
+
+/** Input for {@link runStatus}: the persisted file is self-contained, so no `config` is needed. */
+interface RunStatusInput {
+    /** Directory the run-status file resolves against; defaults to cwd. */
+    readonly cwd?: string;
+}
+/** Composition seam for {@link runStatus}: inject a file system for tests. */
+interface RunStatusDeps {
+    readonly fs?: SdkFs;
+}
+/**
+ * The persisted run-status snapshot, or its absence. `available: false` covers a project that has
+ * never run a non-dry-run `translate()`/`watch()`, exactly like every other degrade case
+ * {@link runStatus} folds into it: never a distinct error, so a caller does not need to special-case
+ * "first run" apart from "corrupt file" apart from "unrecognized version".
+ */
+type RunStatusResult = {
+    readonly available: false;
+} | ({
+    readonly available: true;
+} & RunStatusFile);
+/**
+ * Read the most recent run's persisted review-flag and token/usage snapshot from
+ * `.verbatra-local/run-status.json`, without calling a provider, writing any file, or mutating the
+ * lock-file. Never throws: a missing file, invalid JSON, a schema mismatch, or an unrecognized
+ * `version` all degrade to `{ available: false }`, since this file is best-effort telemetry, not a
+ * correctness baseline (contrast {@link lockState}, which can throw `LOCK_FILE_INVALID`).
+ *
+ * @param input - Only the directory the file resolves against; no config is needed.
+ * @param deps - Optional composition seam (file system) for tests.
+ * @returns `{ available: false }`, or `{ available: true, ...the persisted fields }`.
+ */
+declare function runStatus(input?: RunStatusInput, deps?: RunStatusDeps): Promise<RunStatusResult>;
 
 /** Everything the one-shot run needs: the validated config and where/how to run it. */
 interface TranslateInput {
@@ -1036,12 +1549,23 @@ interface TranslateDeps {
  * locales that succeeded. Dry-run reads + diffs + reports without constructing/calling
  * the provider and without writing any file or the lock-file.
  *
- * A per-locale failure does NOT throw: it is recorded on that locale's {@link LocaleSummary} as
+ * A per-locale failure does not throw: it is recorded on that locale's {@link LocaleSummary} as
  * `status: "failed"` with a secret-free `{ code, message }`, where `code` is a preserved string (the
  * underlying provider/adapter code, or `"LOCALE_FAILED"` as a fallback), not necessarily an
  * {@link SdkErrorCode}. DeepL notices, integrity mismatches, and invalid-ICU source keys likewise
  * surface on each `LocaleSummary`, never as throws.
  *
+ * A dry-run reads the lock once, outside any lock, and reuses that one snapshot for every locale:
+ * it never writes, so there is nothing to serialize against. A live run instead re-reads the lock
+ * fresh inside each locale's own write lock (see `runLiveLocale`), so two concurrent live calls
+ * never both diff against the same stale pre-loop snapshot. The token-budget tracker is fresh per
+ * invocation: the `maxTokens` ceiling is per-run, not cumulative across watch cycles.
+ *
+ * On a non-dry-run that reaches the end of the loop, the run's review-flag and token/usage data is
+ * also written to `.verbatra-local/run-status.json` (readable back through {@link runStatus}). This
+ * write is best-effort: any failure is caught and swallowed, never re-thrown and never reflected on
+ * the returned {@link RunSummary}.
+ *
  * @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.
@@ -1147,7 +1671,11 @@ interface ImportWorkbookDeps {
  * 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.
+ * 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
+ * critical section, so a concurrent writer touching the same locale can never interleave with it.
  *
  * @param input - The validated config, the workbook path, and run options.
  * @param deps - Optional composition seams (registry, file system) for tests.
@@ -1317,4 +1845,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-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 };
+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 };