@verbatra/sdk 0.6.2 → 0.6.4

package/README.md

@@ -44,7 +44,9 @@ const config = await loadConfig();
 // The provider reads its API key from the environment (e.g. ANTHROPIC_API_KEY). No key is passed.
 const summary = await translate({ config });
 
-console.log(`${summary.succeeded.length} locale(s) translated, ${summary.failed.length} failed`);
+console.log(
+  `${summary.succeeded.length} locale(s) done, ${summary.partial.length} partial, ${summary.failed.length} failed`,
+);
 ```
 
 ## Defining config
@@ -71,21 +73,29 @@ export default defineConfig({
 });
 ```
 
-`files.pattern` must contain the `{locale}` token, and `targetLocales` must not include `sourceLocale`; both are enforced when the config is validated. The supported `format` values are `i18next-json`, `vue-i18n-json`, `next-intl-json`, `ngx-translate-json`, `xliff`, `yaml`, `arb`, and `properties`. JSON-family, YAML, and ARB files round-trip in exact document key order: integer-like keys keep their position, new keys append in source-document order, and a YAML composite key (a map or sequence used as a mapping key) fails with a structured error. The optional `glossary` (a term map) and `tone` (`"formal"`, `"informal"`, or `"neutral"`) refine the output. The optional `prune` boolean (off by default) opts in to removing orphaned keys (present in a target file but absent from the source) from the written target files and the lock; the `translate --prune` flag overrides it per run. The optional `generatePlurals` boolean (off by default) opts in to synthesizing the CLDR plural forms a richer target language requires but the source lacks (i18next-JSON projects translated by an LLM provider only; DeepL, non-i18next formats, and unknown languages fall back to the per-locale plural warning and never fail); a per-run `generatePlurals` override on `translate` takes precedence, and generated keys are reported separately from translated keys on the summary. OpenAI and Gemini take `{ model, maxOutputTokens }`; `openai-compatible` additionally takes a `baseUrl` (for a local or self-hosted server such as LM Studio, Ollama, or vLLM) and an optional `apiKeyEnvVar`; DeepL takes `{}` (with an optional `glossaryId`). API keys are never part of the config. Each provider reads its own environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPL_API_KEY`; `openai-compatible` resolves its key from `apiKeyEnvVar`, then `OPENAI_COMPATIBLE_API_KEY`, then falls back to a keyless placeholder).
+`files.pattern` must contain the `{locale}` token, `targetLocales` must not include `sourceLocale`, and `targetLocales` must not list the same locale twice, compared case-insensitively (two such entries would collide as one Excel worksheet on export); all three are enforced when the config is validated. The supported `format` values are `i18next-json`, `vue-i18n-json`, `next-intl-json`, `ngx-translate-json`, `xliff`, `yaml`, `arb`, and `properties`. JSON-family, YAML, and ARB files round-trip in exact document key order: integer-like keys keep their position, new keys append in source-document order, and a YAML composite key (a map or sequence used as a mapping key) fails with a structured error; a `.properties` write preserves the destination file's existing line endings. The optional `glossary` (a term map, inline or a path to a JSON file of the same shape) and `tone` (`"formal"`, `"informal"`, or `"neutral"`) refine the output. The optional `prune` boolean (off by default) opts in to removing orphaned keys (present in a target file but absent from the source) from the written target files and the lock; the `translate --prune` flag overrides it per run. The optional `generatePlurals` boolean (off by default) opts in to synthesizing the CLDR plural forms a richer target language requires but the source lacks (i18next-JSON projects translated by an LLM provider only; DeepL, non-i18next formats, and unknown languages fall back to the per-locale plural warning and never fail); a per-run `generatePlurals` override on `translate` takes precedence, and generated keys are reported separately from translated keys on the summary. The optional `maxBatchSize` (a positive integer, 50 when absent) caps how many entries go into a single provider request, so a large locale is split into sequential sub-batches and one oversized request cannot sink the whole locale. The optional `maxTokens` sets a whole-run ceiling on input plus output tokens across every provider call, and `budgetBehavior` decides what happens once it is reached: `"warn"` (the default) flags it and lets the run continue, `"stop"` withholds every not-yet-attempted key for the rest of the run so it retries next time. Both are config-only, have no CLI flag, and never change an exit code; against a token-less provider such as DeepL, which reports no usage, the budget stays inert rather than tripping falsely.
+
+Anthropic takes `{ model, maxTokens }`; OpenAI and Gemini take `{ model, maxOutputTokens }`; `openai-compatible` takes the same pair plus a `baseUrl` (for a local or self-hosted server such as LM Studio, Ollama, or vLLM) and an optional `apiKeyEnvVar`; DeepL takes `{}` (with an optional `glossaryId`). Every provider additionally accepts an optional `requestTimeoutMs`, a positive-integer per-request timeout in milliseconds that bounds each outbound call. API keys are never part of the config. Each provider reads its own environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPL_API_KEY`; `openai-compatible` resolves its key from `apiKeyEnvVar`, then `OPENAI_COMPATIBLE_API_KEY`, then falls back to a keyless placeholder).
 
 ## API reference
 
 ### `defineConfig(config)`
 
-Returns the config unchanged. It exists purely for type inference and editor autocomplete when authoring a code-defined config. The `model` field is restricted to the selected provider's known model IDs (sourced from that provider's own SDK), so a model from another provider is a type error at authoring time; the runtime still validates `model` only as a non-empty string, so an unlisted model runs even though the editor flags it.
+Returns the config unchanged. It exists purely for type inference and editor autocomplete when authoring a code-defined config. For Anthropic, OpenAI, and Gemini the `model` field is restricted to that provider's known model IDs (sourced from its own SDK), so a model from another provider is a type error at authoring time; the runtime still validates `model` only as a non-empty string, so an unlisted model runs even though the editor flags it. DeepL has no `model` field, and `openai-compatible`'s model is whatever the local server exposes, so neither is restricted.
 
 ### `loadConfig(options?): Promise<VerbatraConfig>`
 
-Discovers and validates the configuration. With no arguments it searches upward from the current working directory; `options` accepts `cwd`, an explicit `configPath`, or an in-memory `configOverride`. Resolves to the validated `VerbatraConfig`, and throws an `SdkError` if no config is found or it fails validation.
+Discovers and validates the configuration. With no arguments it searches upward from the current working directory; `options` accepts `cwd`, an explicit `configPath`, an in-memory `configOverride`, and an `fs` seam. Precedence is `configOverride`, then `configPath`, then the search. Resolves to the validated `VerbatraConfig`, and throws an `SdkError` if no config is found (`CONFIG_NOT_FOUND`) or it fails validation (`CONFIG_INVALID`). A `glossary` given as a file path is read and validated here, so every downstream call receives a plain term map.
 
 ### `translate(input): Promise<RunSummary>`
 
-Runs the one-shot read, diff, translate, write flow over every target locale. `input` is `{ config, cwd?, dryRun?, prune?, generatePlurals? }`. With `dryRun: true` it reads, diffs, and reports without calling the provider or writing anything. `prune` and `generatePlurals` each override the matching config option for this run. Resolves to a `RunSummary` (`dryRun`, `locales`, `succeeded`, and `failed`); each locale summary lists `translated`, `generated`, `pruned`, `integrityMismatches`, `providerFailures`, and `notices`. `integrityMismatches` is a translation that came back and failed the placeholder-integrity check; `providerFailures` is a key withheld because the provider call itself failed (nothing was translated), with the secret-free failure code and message reported in `notices`.
+Runs the one-shot read, diff, translate, write flow over every target locale. `input` is a `TranslateInput`: `{ config, cwd?, dryRun?, prune?, generatePlurals?, cache?, concurrency?, lockAcquireTimeoutMs?, onProgress?, onLockWait? }`. With `dryRun: true` it reads, diffs, and reports without calling the provider or writing anything. `prune` and `generatePlurals` each override the matching config option for this run.
+
+`cache` (on by default, and ignored on a dry run) toggles the local content-addressed translation-memory cache in `verbatra.cache.json`: a key whose source content is unchanged, including under a renamed key or shared with another key, is served from the cache instead of being re-sent to the provider. A cached value is re-checked against that key's own current source first, and one that fails the gate falls through to the provider rather than being written. `concurrency` (defaults to 1, strictly serial) is how many target locales may run at once; it must be an integer of at least 1, and on a live run a value above 1 is refused when the config sets `maxTokens`, because concurrent locales would overshoot the budget nondeterministically. `lockAcquireTimeoutMs` overrides how long a locale's write lock keeps retrying before it fails. `onProgress` receives a structured event once per locale before and after it runs, once per provider sub-batch, and once when the locale loop ends; `onLockWait` fires while a locale's write lock is blocked on another process holding it. The SDK writes to no stream, so these callbacks are the only progress signal.
+
+Resolves to a `RunSummary`: `dryRun`, `locales`, `succeeded`, `partial`, `failed`, plus `usage` when any provider call reported tokens and `budget` when `maxTokens` is configured. A locale's `status` is `"succeeded"` when nothing was withheld (a no-op with no candidate keys included), `"partial"` when it accepted at least one key and withheld at least one, and `"failed"` when it withheld keys and accepted none, or threw. Each `LocaleSummary` carries `locale`, `status`, `translated`, `unchanged`, `orphaned`, `pruned`, `invalidIcuSource`, `cacheHits`, `integrityMismatches`, `providerFailures`, `budgetWithheld`, `generated`, `notices`, `needsReview`, `unfilled`, `malformedRows`, `duplicateKeys`, an optional `usage`, and an optional `error` on a locale that threw. `cacheHits` are keys served from the translation-memory cache rather than the provider. `integrityMismatches` is a translation that came back and was withheld by verbatra's integrity gate, whose rejection reasons are the exported `IntegrityGateReason` union. `providerFailures` is a key withheld because nothing was translated for it (the provider call failed, or the response was still missing that key), with any secret-free failure code and message reported in `notices`. `budgetWithheld` is a candidate never sent because a `maxTokens` budget in `"stop"` mode had already tripped. `needsReview` flags accepted keys the review heuristics want a human to look at, and never withholds anything. `unfilled`, `malformedRows`, and `duplicateKeys` are populated only by `importWorkbook`, which returns this same shape. Every withheld key keeps its prior lock hash and is retried next run.
+
+Whole-run failures throw an `SdkError`: an unknown format, provider construction (including a missing API key), an unreadable or invalid source file, a corrupt lock file, an invalid `concurrency`, or the concurrency-and-budget conflict above. A per-locale failure never throws; it is isolated on that locale's summary. On a non-dry run the flow also writes `.verbatra-local/run-status.json` (best-effort, read back through `runStatus`).
 
 ```ts
 const preview = await translate({ config, dryRun: true });
@@ -93,7 +103,9 @@ const preview = await translate({ config, dryRun: true });
 
 ### `watch(input): Promise<WatchController>`
 
-Watches the source file and re-runs the translate flow on each debounced change. `input` is `{ config, cwd?, debounceMs?, onRun }`, where `onRun` receives a `WatchRunResult` per run. Resolves to a `WatchController` whose `stop()` closes the watcher and awaits the in-flight run.
+Watches the source file and re-runs the translate flow on each debounced change. `input` is `{ config, cwd?, debounceMs?, onRun, cache?, concurrency?, lockAcquireTimeoutMs?, onLockWait?, onProgress? }`; `debounceMs` defaults to 300, and the last five are passed straight through to every run. One run starts immediately at startup, before any change arrives. Runs are serialized, so changes during a run collapse into a single follow-up.
+
+`onRun` receives a `WatchRunResult` per run: `{ status: "succeeded", summary }` or `{ status: "failed", error }` with a secret-free `{ code, message }`, so a failing run is reported and watching continues. `watch` itself throws only at startup: `CONCURRENCY_INVALID` or `CONCURRENCY_BUDGET_CONFLICT` for a `concurrency` no cycle could honor (resolved once, before the watcher exists, rather than failing every cycle), and `SOURCE_UNREADABLE` when the source locale file is absent. Resolves to a `WatchController` whose `stop()` closes the watcher and awaits the in-flight run.
 
 ```ts
 import { loadConfig, watch } from "@verbatra/sdk";
@@ -125,7 +137,7 @@ if (!summary.inSync) {
 
 ### `diff(input): Promise<DiffSummary>`
 
-Lists the keys a run would touch, without writing anything. `input` is the same `{ config, cwd?, locales? }` shape as `check`. Resolves to a `DiffSummary` whose `locales` lists one `LocaleDiff` each, with the key arrays `missing` (would be added), `changed` (would be re-translated), and `orphaned` (present in the target but absent from the source).
+Lists the keys a run would touch, without writing anything. `input` is the same `{ config, cwd?, locales? }` shape as `check`. Resolves to a `DiffSummary` whose `locales` lists one `LocaleDiff` each, with the key arrays `missing` (would be added), `changed` (would be re-translated), and `orphaned` (present in the target but absent from the source), plus a per-locale `hasPendingChanges` driven by `missing` and `changed` only, since a default run does not prune. The top-level `hasPendingChanges` is true when any checked locale has some.
 
 ```ts
 import { diff, loadConfig } from "@verbatra/sdk";
@@ -136,11 +148,11 @@ const summary = await diff({ config });
 
 ### `exportWorkbook(input): Promise<ExportWorkbookResult>`
 
-Exports the strings that need translating into a styled Excel workbook for a human translator. `input` is `{ config, cwd?, out?, locales?, includeUnchanged? }`. By default it writes the missing and changed strings for every target locale to `verbatra-translations.xlsx`; `out` overrides the path, `locales` narrows which target locales are exported, and `includeUnchanged: true` also exports already up-to-date strings. Resolves to an `ExportWorkbookResult` with the written `path` and a per-locale row count.
+Exports the strings that need translating into a styled Excel workbook for a human translator. `input` is `{ config, cwd?, out?, locales?, includeUnchanged? }`. By default it writes the missing and changed strings for every target locale to `verbatra-translations.xlsx`; `out` overrides the path, `locales` narrows which target locales are exported, and `includeUnchanged: true` also exports already up-to-date strings. No provider is called and no lock file is written. Resolves to an `ExportWorkbookResult` with the absolute `path` written and a per-locale row count.
 
 ### `importWorkbook(input): Promise<RunSummary>`
 
-Imports a filled workbook back into the locale files, running the same placeholder and ICU checks as `translate`. `input` is `{ config, workbook, cwd?, dryRun? }`. With `dryRun: true` it validates and reports without writing locale files or updating the lock. Resolves to a `RunSummary`, the same shape `translate` returns.
+Imports a filled workbook back into the locale files, gating every row through the same integrity gate as `translate` on top of a fresh source-drift check. `input` is `{ config, workbook, cwd?, dryRun? }`. With `dryRun: true` it validates and reports without writing locale files or updating the lock. Resolves to a `RunSummary`, the same shape `translate` returns: a row the translator left blank whose key still needs a translation is reported in that locale's `unfilled` (nothing is written and the prior lock baseline is kept), an unreadable row in `malformedRows`, a repeated key in `duplicateKeys` (the first occurrence wins), and a configured target locale whose sheet is missing from the workbook is reported as that locale's failed summary rather than silently dropped. `unfilled`, `malformedRows`, and `duplicateKeys` do not feed a locale's `status`, so a partly filled sheet still imports the rows it has. A key is cleared by filling its Translation cell with the `[[CLEAR]]` sentinel; an ordinary blank never clears a value.
 
 ```ts
 import { exportWorkbook, importWorkbook, loadConfig } from "@verbatra/sdk";
@@ -160,17 +172,19 @@ See [Manual translation](https://verbatra.kreitz-webdev.de/docs/manual-translati
 
 Beyond the flows above, the SDK exports the building blocks Verbatra Studio and other tooling sit on, each a one-call read or a locked single-key write:
 
-- `keyIntegrity` reports, per changed key, whether its placeholders and ICU structure still match the source.
+- `keyIntegrity` reports, per changed key, whether its placeholders still match the source (with the missing and extra tokens on a mismatch) and whether the current target value is still valid ICU.
 - `lockState` reports the lock file's existence, version, and per-locale drift; `loadLockFile` reads the lock file itself.
-- `runStatus` reads the persisted review-flag and token-usage snapshot the last `translate` or `watch` run left behind.
+- `runStatus` reads the persisted review-flag and token-usage snapshot the last non-dry `translate` or `watch` run left behind; it never throws, and a missing, corrupt, or unrecognized file simply reports as unavailable.
 - `keyValue` reads one key's current source and target values.
-- `editEntry` saves a manually edited translation for one key, and `retranslateEntry` re-runs the provider for one key; both run the same placeholder and ICU integrity checks as a full run and hold the same per-locale write lock.
+- `editEntry` saves a manually edited translation for one key, and `retranslateEntry` re-runs the provider for one key; both run the candidate through the same integrity gate as a full run (a rejection names an `IntegrityGateReason` and writes nothing) and hold the same per-locale write lock.
 - `readLocaleFileSnapshot` and `diffLocaleSnapshots` snapshot one locale file as per-key content hashes and compare two snapshots, the primitives behind live-refresh watching.
 - `loadConfigWithMeta` is `loadConfig` plus config-source and glossary provenance.
 
 ## Errors and results
 
-The SDK throws a single structured error type, `SdkError`, for whole-run failures such as a missing or invalid config or an unreadable source file. It carries a stable `code` and never contains an API key. Per-locale failures do not throw: they are recorded on the `RunSummary` so one failing locale never aborts the others.
+`SdkError` is the SDK's own structured error type, thrown for whole-run failures such as a missing or invalid config or an unreadable source file. It carries a stable `code` from the exported `SdkErrorCode` union and never contains an API key. It is not the only error a caller can see: `retranslateEntry` propagates the provider's own `ProviderError` when the provider call fails or returns nothing for the key, and a target locale file that exists but is malformed rejects with the adapter's own error.
+
+Per-locale failures do not throw: they are recorded on the `RunSummary` so one failing locale never aborts the others, and that includes a locale whose write lock could not be acquired. A locale's `error.code` is a preserved string from the underlying provider or adapter failure (`"LOCALE_FAILED"` is only the fallback), deliberately wider than `SdkErrorCode`, so do not treat it as a closed set.
 
 ## Documentation
 

package/dist/index.cjs

@@ -61,27 +61,31 @@ var translationMemorySchema = zod.z.object({
 function cacheFilePath(cwd) {
   return path.resolve(cwd, CACHE_FILE_NAME);
 }
+var UNUSABLE = { memory: EMPTY_MEMORY, writable: true };
 async function readTranslationMemory(path, fs) {
   let read;
   try {
     read = await fs.readFileBounded(path, MAX_CACHE_FILE_BYTES);
   } catch {
-    return EMPTY_MEMORY;
+    return UNUSABLE;
   }
   if (read.kind !== "ok") {
-    return EMPTY_MEMORY;
+    return UNUSABLE;
   }
   let parsed;
   try {
     parsed = JSON.parse(read.content);
   } catch {
-    return EMPTY_MEMORY;
+    return UNUSABLE;
   }
   const result = translationMemorySchema.safeParse(parsed);
-  if (!result.success || result.data.version !== CURRENT_VERSION) {
-    return EMPTY_MEMORY;
+  if (!result.success) {
+    return UNUSABLE;
   }
-  return result.data;
+  if (result.data.version !== CURRENT_VERSION) {
+    return { memory: EMPTY_MEMORY, writable: false };
+  }
+  return { memory: result.data, writable: true };
 }
 function lookupMemory(memory, fingerprint, locale, contentHash2) {
   return memory.entries[fingerprint]?.[locale]?.[contentHash2];
@@ -133,7 +137,10 @@ async function feedTranslationMemory(cwd, fs, fingerprint, additionsByLocale) {
   }
   try {
     const path = cacheFilePath(cwd);
-    const memory = await readTranslationMemory(path, fs);
+    const { memory, writable } = await readTranslationMemory(path, fs);
+    if (!writable) {
+      return;
+    }
     await writeTranslationMemory(path, applyAdditions(memory, fingerprint, additionsByLocale), fs);
   } catch {
   }
@@ -145,6 +152,18 @@ function defineConfig(config) {
 }
 
 // src/errors.ts
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function stringCode(error) {
+  if (error instanceof Error && "code" in error && typeof error.code === "string") {
+    return error.code;
+  }
+  return void 0;
+}
+function describeError(error, fallbackCode) {
+  return { code: stringCode(error) ?? fallbackCode, message: errorMessage(error) };
+}
 var SdkError = class extends Error {
   /** The stable {@link SdkErrorCode} for this failure; branch on this, not the message. */
   code;
@@ -1942,7 +1961,7 @@ async function loadExplicitWithMeta(explorer, configPath, cwd, fs$1) {
   try {
     result = await explorer.load(resolved);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorMessage(error);
     throw new SdkError("CONFIG_INVALID", `Failed to load the verbatra configuration: ${detail}`);
   }
   const parsed = parseConfig(result?.config);
@@ -1967,7 +1986,7 @@ async function loadConfigWithMeta(options = {}) {
   try {
     result = await explorer.search(options.cwd);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorMessage(error);
     throw new SdkError("CONFIG_INVALID", `Failed to load the verbatra configuration: ${detail}`);
   }
   if (result === null || result.isEmpty === true) {
@@ -2052,15 +2071,15 @@ async function acquireLock(path, fs, pollIntervalMs, deadline, notify) {
     if (await fs.createExclusive(path, lockPayload())) {
       return;
     }
+    if (notify !== void 0) {
+      await notify();
+    }
     if (Date.now() >= deadline) {
       throw new SdkError(
         "LOCK_CONTENDED",
         `Could not acquire the write lock at ${path}: another process may be holding it. If no verbatra process is currently running, this lock file was likely left behind by one that was killed; delete it and retry.`
       );
     }
-    if (notify !== void 0) {
-      await notify();
-    }
     const jitter = Math.random() * pollIntervalMs;
     await sleep(pollIntervalMs + jitter);
   }
@@ -2650,6 +2669,9 @@ async function fsyncDirBestEffort(path) {
   }
 }
 var nodeOps = {
+  mkdir: async (path) => {
+    await promises.mkdir(path, { recursive: true });
+  },
   writeFile: (path, data) => promises.writeFile(path, data, "utf8"),
   fsyncFile: (path) => fsyncPath(path),
   rename: (from, to) => promises.rename(from, to),
@@ -2666,8 +2688,10 @@ function tempFileName2(path$1) {
   return path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`);
 }
 async function atomicWriteFile(path$1, data, ops = nodeOps) {
+  const directory = path.dirname(path$1);
   const tmp = tempFileName2(path$1);
   try {
+    await ops.mkdir(directory);
     await ops.writeFile(tmp, data);
     await ops.fsyncFile(tmp);
     await ops.rename(tmp, path$1);
@@ -2676,7 +2700,7 @@ async function atomicWriteFile(path$1, data, ops = nodeOps) {
     throw error;
   }
   try {
-    await ops.fsyncDir(path.dirname(path$1));
+    await ops.fsyncDir(directory);
   } catch {
   }
 }
@@ -3339,6 +3363,12 @@ function extractPropertiesPlaceholders(value) {
 var UNICODE_ESCAPE = /^[0-9a-fA-F]{4}$/;
 var LEADING_WHITESPACE = /^[ \t\f]+/;
 var TRAILING_TERMINATOR = /(?:\r\n|\r|\n)$/;
+function detectLineTerminator(content) {
+  if (content.includes("\r\n")) {
+    return "\r\n";
+  }
+  return content.includes("\r") ? "\r" : "\n";
+}
 function isPropertiesWhitespace(char) {
   return char === " " || char === "	" || char === "\f";
 }
@@ -3544,7 +3574,7 @@ async function readStructure(filePath) {
     outcome = await readBounded2(filePath);
   } catch (error) {
     if (isFileNotFound(error)) {
-      return [];
+      return { items: [], terminator: "\n" };
     }
     throw new AdapterError("INVALID_STRUCTURE", "The destination file could not be read.");
   }
@@ -3554,13 +3584,16 @@ async function readStructure(filePath) {
   if (outcome.kind === "too-large") {
     throw new AdapterError("INPUT_TOO_LARGE", "The file exceeds the maximum allowed size.");
   }
-  return parseItems(outcome.content);
+  return {
+    items: parseItems(outcome.content),
+    terminator: detectLineTerminator(outcome.content)
+  };
 }
 async function serializePropertiesEntries(entries, filePath) {
-  const structure = await readStructure(filePath);
+  const { items, terminator } = await readStructure(filePath);
   const emitted = /* @__PURE__ */ new Set();
   const lines = [];
-  for (const item of structure) {
+  for (const item of items) {
     if (item.kind === "raw") {
       lines.push(item.text);
       continue;
@@ -3576,8 +3609,7 @@ async function serializePropertiesEntries(entries, filePath) {
       lines.push(formatEntry(key, entry.value));
     }
   }
-  return lines.length === 0 ? "" : `${lines.join("\n")}
-`;
+  return lines.length === 0 ? "" : `${lines.join(terminator)}${terminator}`;
 }
 function createPropertiesAdapter() {
   return createFlatFileAdapter({
@@ -4029,7 +4061,7 @@ async function readSource(config, cwd, fs, adapter) {
   try {
     return await adapter.read(sourcePath, config.sourceLocale);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorMessage(error);
     throw new SdkError(
       "SOURCE_INVALID",
       `The source locale file at ${sourcePath} could not be read: ${detail}`
@@ -4130,6 +4162,9 @@ function gateCandidateValue(sourceEntry, candidateValue, adapter) {
   if (assessValueDegeneracy(sourceEntry.value, candidateValue).degenerate) {
     return { accepted: false, reason: "degenerate" };
   }
+  if (sourceEntry.value.trim() !== "" && candidateValue.trim() === "") {
+    return { accepted: false, reason: "empty" };
+  }
   return { accepted: true };
 }
 
@@ -4326,7 +4361,7 @@ function selectProvider(config, createProvider = buildProvider) {
   try {
     return createProvider(config);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorMessage(error);
     throw new SdkError(
       "PROVIDER_CONSTRUCTION_FAILED",
       `Failed to construct provider "${config.id}": ${detail}`
@@ -4549,13 +4584,6 @@ function budgetExceededNotice(tracker) {
 }
 
 // src/flow/locale-failure.ts
-function describeError(error) {
-  if (error instanceof Error) {
-    const code = error.code;
-    return { code: typeof code === "string" ? code : "LOCALE_FAILED", message: error.message };
-  }
-  return { code: "LOCALE_FAILED", message: String(error) };
-}
 function failureSummary(locale, error) {
   return {
     locale,
@@ -4575,7 +4603,7 @@ function failureSummary(locale, error) {
     unfilled: [],
     malformedRows: [],
     duplicateKeys: [],
-    error: describeError(error)
+    error: describeError(error, "LOCALE_FAILED")
   };
 }
 function deriveLocaleStatus(parts) {
@@ -4979,6 +5007,10 @@ function fanOutAccepted(params, group, acceptedRepresentative, outcome) {
     if (source === void 0) {
       continue;
     }
+    if (!gateCandidateValue(source, acceptedRepresentative.value, params.adapter).accepted) {
+      outcome.integrityMismatches.push(key);
+      continue;
+    }
     outcome.accepted.set(key, { value: acceptedRepresentative.value, source });
     if (flag !== void 0) {
       outcome.reviewFlags.set(key, flag);
@@ -5005,6 +5037,12 @@ function buildRequest3(params, entries) {
     ...params.adapter.comparePlaceholders !== void 0 ? { comparePlaceholders: params.adapter.comparePlaceholders } : {}
   };
 }
+async function shouldWriteTarget(params, path, changed) {
+  if (changed.accepted > 0 || changed.pruned > 0 || changed.generated > 0) {
+    return true;
+  }
+  return !await params.fs.fileExists(path);
+}
 async function runLocale(params) {
   const target = await readTargetResource({
     cwd: params.cwd,
@@ -5090,15 +5128,22 @@ async function runLocale(params) {
     merged.set(form.targetKey, { ...form.entry, namespace: target.namespace });
   }
   const path = localeFilePath(params.cwd, params.filesPattern, params.targetLocale);
-  await params.adapter.write(
-    {
-      locale: params.targetLocale,
-      namespace: target.namespace,
-      format: params.format,
-      entries: merged
-    },
-    path
-  );
+  const writeNeeded = await shouldWriteTarget(params, path, {
+    accepted: accepted.size,
+    pruned: pruned.length,
+    generated: generation.accepted.length
+  });
+  if (writeNeeded) {
+    await params.adapter.write(
+      {
+        locale: params.targetLocale,
+        namespace: target.namespace,
+        format: params.format,
+        entries: merged
+      },
+      path
+    );
+  }
   const pluralNotices = params.generatePlurals ? pluralNoticeFor(params, merged) : sdkNotices;
   const notices = [
     ...pluralNotices,
@@ -5370,14 +5415,21 @@ async function createRunCacheState(input, config, cwd, dryRun, fs) {
   if (dryRun || input.cache === false) {
     return void 0;
   }
-  return {
-    memory: await readTranslationMemory(cacheFilePath(cwd), fs),
-    fingerprint: computeFingerprint(config),
-    additions: /* @__PURE__ */ new Map()
+  const { memory, writable } = await readTranslationMemory(cacheFilePath(cwd), fs);
+  return { memory, writable, fingerprint: computeFingerprint(config), additions: /* @__PURE__ */ new Map() };
+}
+function withCacheNotices(summaries, cache) {
+  if (cache === void 0 || cache.writable) {
+    return [...summaries];
+  }
+  const notice = {
+    code: "CACHE_VERSION_UNRECOGNIZED",
+    message: `${CACHE_FILE_NAME} carries a version this build does not recognize, so it was written by a newer verbatra. It was left untouched and this run used no cache. Upgrade verbatra, or delete the file to rebuild it in this build's format.`
   };
+  return summaries.map((summary) => ({ ...summary, notices: [...summary.notices, notice] }));
 }
 async function recordCacheAdditions(cwd, cache, fs) {
-  if (cache === void 0 || cache.additions.size === 0) {
+  if (cache === void 0 || cache.additions.size === 0 || !cache.writable) {
     return;
   }
   try {
@@ -5464,18 +5516,25 @@ async function runLocaleAt(context, targetLocales, localeIndex, runOne, results)
   context.onProgress?.({
     type: "locale-finished",
     locale: targetLocale,
-    translated: summary.translated.length
+    translated: summary.translated.length,
+    localeIndex,
+    totalLocales: targetLocales.length
   });
 }
 async function runLocalesWithProgress(context, targetLocales, runOne, concurrency) {
   const totalLocales = targetLocales.length;
   const results = new Array(totalLocales);
   let nextIndex = 0;
+  let abort;
   async function worker() {
-    while (nextIndex < totalLocales) {
+    while (abort === void 0 && nextIndex < totalLocales) {
       const localeIndex = nextIndex;
       nextIndex += 1;
-      await runLocaleAt(context, targetLocales, localeIndex, runOne, results);
+      try {
+        await runLocaleAt(context, targetLocales, localeIndex, runOne, results);
+      } catch (error) {
+        abort ??= { reason: error };
+      }
     }
   }
   const workerCount = Math.min(concurrency, totalLocales);
@@ -5484,6 +5543,9 @@ async function runLocalesWithProgress(context, targetLocales, runOne, concurrenc
     workers.push(worker());
   }
   await Promise.all(workers);
+  if (abort !== void 0) {
+    throw abort.reason;
+  }
   return results.filter((summary) => summary !== void 0);
 }
 async function runAllLocalesDry(context, targetLocales, concurrency) {
@@ -5560,7 +5622,8 @@ async function translate2(input, deps = {}) {
   };
   const summaries = dryRun ? await runAllLocalesDry(context, config.targetLocales, concurrency) : await runAllLocalesLive(context, config.targetLocales, concurrency);
   input.onProgress?.({ type: "run-finished", localesCompleted: summaries.length });
-  const { succeeded, partial, failed } = partition(summaries);
+  const locales = withCacheNotices(summaries, cache);
+  const { succeeded, partial, failed } = partition(locales);
   const usage = summaries.reduce(
     (total, summary2) => combineUsage(total, summary2.usage),
     void 0
@@ -5568,7 +5631,7 @@ async function translate2(input, deps = {}) {
   const budgetSummary = toBudgetSummary(budget);
   const summary = {
     dryRun,
-    locales: summaries,
+    locales,
     succeeded,
     partial,
     failed,
@@ -6140,12 +6203,12 @@ function classifyClear(row, sourceEntry, buckets) {
     buckets.withheld.add(row.key);
     return;
   }
-  buckets.accepted.set(row.key, { value: "", source: sourceEntry });
+  buckets.accepted.set(row.key, { value: "", source: sourceEntry, cleared: true });
 }
-function classifyRows(params, buckets) {
+function classifyRows(params, buckets, liveCandidates) {
   for (const row of params.sheet.rows) {
     if (row.translation === "") {
-      if (row.status === "changed") {
+      if (liveCandidates.has(row.key)) {
         buckets.unfilled.push(row.key);
       }
       trackBlankDrift(row, params, buckets);
@@ -6164,7 +6227,11 @@ function classifyRows(params, buckets) {
     }
     const reason = judge(row, sourceEntry, params.adapter);
     if (reason === void 0) {
-      buckets.accepted.set(row.key, { value: row.translation, source: sourceEntry });
+      buckets.accepted.set(row.key, {
+        value: row.translation,
+        source: sourceEntry,
+        cleared: false
+      });
     } else {
       buckets.mismatches.push(row.key);
       buckets.withheld.add(row.key);
@@ -6186,7 +6253,7 @@ function importLocale(params) {
     blankDrifted: /* @__PURE__ */ new Set(),
     unfilled: []
   };
-  classifyRows(params, buckets);
+  classifyRows(params, buckets, /* @__PURE__ */ new Set([...diff2.missing, ...diff2.changed]));
   const rowKeys = new Set(params.sheet.rows.map((row) => row.key));
   const invalidIcuSource = [...new Set(params.sourceInvalidIcuKeys)].filter((key) => rowKeys.has(key)).sort();
   const translated = [...buckets.accepted.keys()].sort();
@@ -6244,8 +6311,10 @@ function mergeAccepted(target, accepted) {
 }
 function sheetCacheAdditions(accepted) {
   const record = {};
-  for (const [, { value, source }] of accepted) {
-    record[contentHash(source)] = value;
+  for (const [, { value, source, cleared }] of accepted) {
+    if (!cleared) {
+      record[contentHash(source)] = value;
+    }
   }
   return record;
 }
@@ -6334,7 +6403,7 @@ async function importWorkbook(input, deps = {}) {
   try {
     data = await readWorkbook(bytes);
   } catch (error) {
-    throw new SdkError("SOURCE_INVALID", error.message);
+    throw new SdkError("SOURCE_INVALID", errorMessage(error));
   }
   const lock = await readLockFile(lockFilePath(cwd), fs);
   const ctx = {
@@ -6420,17 +6489,11 @@ function defaultRunTranslate(deps) {
 
 // src/watch/watch.ts
 var DEFAULT_DEBOUNCE_MS = 300;
-function describeError2(error) {
-  if (error instanceof Error) {
-    const code = error.code;
-    return { code: typeof code === "string" ? code : "WATCH_RUN_FAILED", message: error.message };
-  }
-  return { code: "WATCH_RUN_FAILED", message: String(error) };
-}
 async function watch(input, deps = {}) {
   const cwd = input.cwd ?? process.cwd();
   const debounceMs = input.debounceMs ?? DEFAULT_DEBOUNCE_MS;
   const fs = deps.fs ?? defaultFs;
+  resolveRunConcurrency(input.concurrency, false, input.config);
   const sourcePath = localeFilePath(cwd, input.config.files.pattern, input.config.sourceLocale);
   if (!await fs.fileExists(sourcePath)) {
     throw new SdkError(
@@ -6457,7 +6520,7 @@ async function watch(input, deps = {}) {
     try {
       input.onRun({ status: "succeeded", summary: await runTranslate(runInput) });
     } catch (error) {
-      input.onRun({ status: "failed", error: describeError2(error) });
+      input.onRun({ status: "failed", error: describeError(error, "WATCH_RUN_FAILED") });
     }
   }
   function startRun() {