@verbatra/sdk 0.5.0-next.3 → 0.5.0

package/dist/index.js

@@ -3,7 +3,7 @@ import { dirname, resolve, join, basename, extname } from 'path';
 import { cosmiconfig } from 'cosmiconfig';
 import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
 import { randomUUID } from 'crypto';
-import { access, writeFile, rename, rm, open } from 'fs/promises';
+import { rm, access, mkdir, open, writeFile, rename } from 'fs/promises';
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
 import * as deepl from 'deepl-node';
@@ -115,6 +115,24 @@ async function atomicWrite(path, data) {
     throw error;
   }
 }
+async function createExclusive(path, data) {
+  await mkdir(dirname(path), { recursive: true });
+  let handle;
+  try {
+    handle = await open(path, "wx");
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(data, "utf8");
+  } finally {
+    await handle.close();
+  }
+  return true;
+}
 var defaultFs = {
   async fileExists(path) {
     try {
@@ -127,7 +145,11 @@ var defaultFs = {
   readFileBounded: (path, maxBytes) => readBounded(path, maxBytes),
   readBytesBounded: (path, maxBytes) => readBoundedBytes(path, maxBytes),
   writeFile: (path, data) => atomicWrite(path, data),
-  writeBytes: (path, data) => atomicWrite(path, data)
+  writeBytes: (path, data) => atomicWrite(path, data),
+  createExclusive: (path, data) => createExclusive(path, data),
+  deleteFile: async (path) => {
+    await rm(path, { force: true });
+  }
 };
 var MAX_GLOSSARY_FILE_BYTES = 1024 * 1024;
 var glossaryRecordSchema = z.record(z.string(), z.string());
@@ -316,29 +338,18 @@ var TIMEOUT_STATUS = 408;
 var AUTH_FAILED_STATUSES = /* @__PURE__ */ new Set([401, 403]);
 var RATE_LIMITED_CLASS_NAMES = /* @__PURE__ */ new Set([
   "RateLimitError",
-  // openai, @anthropic-ai/sdk
   "TooManyRequestsError"
-  // deepl-node
 ]);
 var AUTH_FAILED_CLASS_NAMES = /* @__PURE__ */ new Set([
   "AuthenticationError",
-  // openai, @anthropic-ai/sdk (401)
   "PermissionDeniedError",
-  // openai, @anthropic-ai/sdk (403)
   "AuthorizationError"
-  // deepl-node
 ]);
 var TIMEOUT_CLASS_NAMES = /* @__PURE__ */ new Set([
   "APIConnectionTimeoutError",
-  // openai, @anthropic-ai/sdk
-  // deepl-node has no distinct timeout class; ConnectionError is its only network-failure
-  // class, so it is folded into TIMEOUT rather than the PROVIDER_ERROR fallback.
   "ConnectionError"
 ]);
-var ABORT_ERROR_CLASS_NAMES = /* @__PURE__ */ new Set([
-  "APIUserAbortError"
-  // openai, @anthropic-ai/sdk
-]);
+var ABORT_ERROR_CLASS_NAMES = /* @__PURE__ */ new Set(["APIUserAbortError"]);
 function getErrorStatus(error) {
   if (typeof error !== "object" || error === null || !("status" in error)) {
     return void 0;
@@ -392,7 +403,6 @@ function isAbortError(error, signal) {
 }
 var REDACTED = "[REDACTED]";
 var KEY_PATTERNS = [
-  // The `\b` anchors `sk-` to a word start so hyphenated words like "risk-" or "task-" pass through.
   /\bsk-[A-Za-z0-9_-]{8,}/g,
   /AIza[0-9A-Za-z_-]{35}/g,
   /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(?::fx)?/g
@@ -414,6 +424,10 @@ var ProviderError = class extends Error {
   /** The stable {@link ProviderErrorCode} for this failure; branch on this, not the message. */
   code;
   /**
+   * Redacts the message as a defense-in-depth backstop before storing it. The redaction runs with an
+   * empty secret argument so the ANTHROPIC_API_KEY environment default is not re-applied, keeping
+   * this generic error decoupled from any one provider's environment variable.
+   *
    * @param code - The stable failure code.
    * @param message - A fixed, safe message; callers must never pass key, SDK, or request-derived text.
    */
@@ -472,6 +486,76 @@ function validateRequest(request) {
   }
   return parsed.data;
 }
+var LENGTH_RATIO_MIN = 0.35;
+var LENGTH_RATIO_MAX = 3;
+var LENGTH_RATIO_MIN_SOURCE_LENGTH = 12;
+var UNICODE_LETTER = /\p{L}/u;
+var DEGRADATION_NOTICE_CODES = /* @__PURE__ */ new Set([
+  "FORMALITY_DOWNGRADED",
+  "GLOSSARY_IGNORED"
+]);
+function isLengthRatioOutlier(sourceValue, translatedValue) {
+  const trimmedSource = sourceValue.trim();
+  if (trimmedSource.length < LENGTH_RATIO_MIN_SOURCE_LENGTH) {
+    return false;
+  }
+  const ratio = translatedValue.trim().length / trimmedSource.length;
+  return ratio < LENGTH_RATIO_MIN || ratio > LENGTH_RATIO_MAX;
+}
+function isEqualsSource(input) {
+  const trimmedSource = input.sourceValue.trim();
+  const trimmedTranslated = input.translatedValue.trim();
+  return trimmedTranslated === trimmedSource && input.targetLocale !== input.sourceLocale && UNICODE_LETTER.test(trimmedSource);
+}
+function isGlossaryTermMissed(input) {
+  const glossary = input.glossary;
+  if (glossary === void 0 || Object.keys(glossary).length === 0) {
+    return false;
+  }
+  const sourceLower = input.sourceValue.toLowerCase();
+  const translatedLower = input.translatedValue.toLowerCase();
+  for (const [sourceTerm, targetTerm] of Object.entries(glossary)) {
+    const sourceHit = sourceLower.includes(sourceTerm.toLowerCase());
+    const targetHit = translatedLower.includes(targetTerm.toLowerCase());
+    if (sourceHit && !targetHit) {
+      return true;
+    }
+  }
+  return false;
+}
+function isIntegrityReordered(integrity) {
+  return integrity.matches && integrity.reordered;
+}
+function computeReviewFlags(input) {
+  const reasons = [];
+  if (isLengthRatioOutlier(input.sourceValue, input.translatedValue)) {
+    reasons.push("LENGTH_RATIO_OUTLIER");
+  }
+  if (isEqualsSource(input)) {
+    reasons.push("EQUALS_SOURCE");
+  }
+  if (isGlossaryTermMissed(input)) {
+    reasons.push("GLOSSARY_TERM_MISSED");
+  }
+  if (isIntegrityReordered(input.integrity)) {
+    reasons.push("INTEGRITY_REORDERED");
+  }
+  return reasons.length > 0 ? { status: "review", reasons } : void 0;
+}
+function applyProviderDegraded(reviewFlags, notices, acceptedKeys) {
+  if (!notices.some((notice) => DEGRADATION_NOTICE_CODES.has(notice.code))) {
+    return reviewFlags;
+  }
+  const next = new Map(reviewFlags);
+  for (const key of acceptedKeys) {
+    const existing = next.get(key);
+    next.set(key, {
+      status: "review",
+      reasons: existing !== void 0 ? [...existing.reasons, "PROVIDER_DEGRADED"] : ["PROVIDER_DEGRADED"]
+    });
+  }
+  return next;
+}
 function toIntegrityInputs(entries, values) {
   const inputs = [];
   for (const entry of entries) {
@@ -567,7 +651,33 @@ async function runLlmTranslation(request, mechanism) {
     request.extractPlaceholders,
     request.comparePlaceholders
   );
-  return usage === void 0 ? { values, integrity, notices: [] } : { values, integrity, usage, notices: [] };
+  const notices = [];
+  const reviewFlags = applyProviderDegraded(buildReviewFlags(data, values, integrity), notices, [
+    ...values.keys()
+  ]);
+  return usage === void 0 ? { values, integrity, notices, reviewFlags } : { values, integrity, usage, notices, reviewFlags };
+}
+function buildReviewFlags(data, values, integrity) {
+  const reviewFlags = /* @__PURE__ */ new Map();
+  for (const entry of data.entries) {
+    const translatedValue = values.get(entry.key);
+    const entryIntegrity = integrity.get(entry.key);
+    if (translatedValue === void 0 || entryIntegrity === void 0) {
+      continue;
+    }
+    const flag = computeReviewFlags({
+      sourceValue: entry.value,
+      translatedValue,
+      sourceLocale: data.sourceLocale,
+      targetLocale: data.targetLocale,
+      integrity: entryIntegrity,
+      glossary: data.glossary
+    });
+    if (flag !== void 0) {
+      reviewFlags.set(entry.key, flag);
+    }
+  }
+  return reviewFlags;
 }
 async function requestTranslations(mechanism, data, signal) {
   const payloadJson = JSON.stringify(buildDataPayload(data));
@@ -885,9 +995,6 @@ function createDeepLProvider(config, deps = {}) {
   return {
     id: PROVIDER_ID2,
     kind: "machine-translation",
-    // Honest capability signal: DeepL only ever applies a pre-created native glossary id, never a
-    // generic term map (see buildTranslateOptions). Without one configured, a supplied term map is
-    // silently ignored and surfaces only as a GLOSSARY_IGNORED notice.
     supportsGlossary: validConfig.glossaryId !== void 0,
     translateBatch: (request) => translate(bundle, validConfig, request)
   };
@@ -922,7 +1029,34 @@ async function translate(bundle, config, request) {
   if (unprotectable.length > 0) {
     notices.push({ code: "PLACEHOLDER_UNSUPPORTED", message: PLACEHOLDER_UNSUPPORTED_MESSAGE });
   }
-  return { values, integrity, notices };
+  const reviewFlags = applyProviderDegraded(
+    buildReviewFlags2(protectable, data, values, integrity, request.glossary),
+    notices,
+    [...values.keys()]
+  );
+  return { values, integrity, notices, reviewFlags };
+}
+function buildReviewFlags2(protectable, data, values, integrity, glossary) {
+  const reviewFlags = /* @__PURE__ */ new Map();
+  for (const entry of protectable) {
+    const translatedValue = values.get(entry.key);
+    const entryIntegrity = integrity.get(entry.key);
+    if (translatedValue === void 0 || entryIntegrity === void 0) {
+      continue;
+    }
+    const flag = computeReviewFlags({
+      sourceValue: entry.value,
+      translatedValue,
+      sourceLocale: data.sourceLocale,
+      targetLocale: data.targetLocale,
+      integrity: entryIntegrity,
+      glossary
+    });
+    if (flag !== void 0) {
+      reviewFlags.set(entry.key, flag);
+    }
+  }
+  return reviewFlags;
 }
 async function translateProtectable(client, data, protectable, options, extract, compare, signal) {
   if (protectable.length === 0) {
@@ -972,14 +1106,14 @@ function throwAbort(signal) {
   throw new DOMException("This operation was aborted.", "AbortError");
 }
 function delay(ms, signal) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve9) => {
     const onAbort = () => {
       clearTimeout(timer);
-      resolve7();
+      resolve9();
     };
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve7();
+      resolve9();
     }, ms);
     signal?.addEventListener("abort", onAbort, { once: true });
   });
@@ -1027,12 +1161,10 @@ var TYPE_MAP = {
   object: "OBJECT"
 };
 var HANDLED_KEYWORDS = /* @__PURE__ */ new Set([
-  // transformed or recursed
   "type",
   "required",
   "properties",
   "items",
-  // deliberately dropped (not part of Google's Schema dialect)
   "$schema",
   "additionalProperties"
 ]);
@@ -1426,6 +1558,7 @@ function buildProvider(config) {
 
 // src/config/schema.ts
 var DEFAULT_MAX_BATCH_SIZE = 50;
+var DEFAULT_BUDGET_BEHAVIOR = "warn";
 function findCaseInsensitiveDuplicate(locales) {
   const seen = /* @__PURE__ */ new Set();
   for (const locale of locales) {
@@ -1474,7 +1607,23 @@ var verbatraConfigSchema = z.strictObject({
    * be a positive integer (zero, negative, or non-integer is rejected, never coerced). When absent,
    * {@link DEFAULT_MAX_BATCH_SIZE} applies.
    */
-  maxBatchSize: z.number().int().positive().optional()
+  maxBatchSize: z.number().int().positive().optional(),
+  /**
+   * Optional whole-run token ceiling (input plus output tokens summed across every provider call, main
+   * translation and plural generation alike, across all target locales). Checked after each completed
+   * sub-batch, never mid-batch: the sub-batch whose completion crosses the ceiling is retained and
+   * counted, since a call already in flight cannot be undone. Must be a positive integer. Config-only,
+   * no CLI flag. Absent means no budget is enforced. Inert (never a false trip) against a token-less
+   * provider such as DeepL, since it never reports usage to measure against the ceiling.
+   */
+  maxTokens: z.number().int().positive().optional(),
+  /**
+   * What happens once `maxTokens` is reached: `"warn"` (default) flags it and lets the run continue
+   * unchanged; `"stop"` withholds every not-yet-attempted key for the rest of the run (the current
+   * locale's remaining candidates and every later locale's), retried automatically next run. Present
+   * without `maxTokens` is accepted and has no effect. Never changes the command's exit code.
+   */
+  budgetBehavior: z.enum(["warn", "stop"]).optional()
 }).refine((config) => !config.targetLocales.includes(config.sourceLocale), {
   message: "targetLocales must not include the source locale",
   path: ["targetLocales"]
@@ -1583,6 +1732,60 @@ async function loadConfig(options = {}) {
   const { config } = await loadConfigWithMeta(options);
   return config;
 }
+var LOCAL_DIR_NAME = ".verbatra-local";
+var LOCK_FILE_GUARD_STEM = "_lockfile";
+var DEFAULT_POLL_INTERVAL_MS = 100;
+var DEFAULT_ACQUIRE_TIMEOUT_MS = 10 * 6e4;
+function lockPath(cwd, stem) {
+  return resolve(cwd, LOCAL_DIR_NAME, "locks", `${stem}.lock`);
+}
+function localeLockPath(cwd, locale) {
+  return lockPath(cwd, locale);
+}
+function lockFileGuardPath(cwd) {
+  return lockPath(cwd, LOCK_FILE_GUARD_STEM);
+}
+function sleep(ms) {
+  return new Promise((res) => {
+    setTimeout(res, ms);
+  });
+}
+function lockPayload() {
+  return JSON.stringify({ pid: process.pid, acquiredAt: (/* @__PURE__ */ new Date()).toISOString() });
+}
+async function acquireLock(path, fs, pollIntervalMs, deadline) {
+  for (; ; ) {
+    if (await fs.createExclusive(path, lockPayload())) {
+      return;
+    }
+    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.`
+      );
+    }
+    const jitter = Math.random() * pollIntervalMs;
+    await sleep(pollIntervalMs + jitter);
+  }
+}
+async function withFileLock(path, fs, fn, options) {
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const acquireTimeoutMs = options.acquireTimeoutMs ?? DEFAULT_ACQUIRE_TIMEOUT_MS;
+  await acquireLock(path, fs, pollIntervalMs, Date.now() + acquireTimeoutMs);
+  try {
+    return await fn();
+  } finally {
+    await fs.deleteFile(path);
+  }
+}
+async function withLocaleWriteLock(cwd, locale, fs, fn, options = {}) {
+  return withFileLock(localeLockPath(cwd, locale), fs, fn, options);
+}
+async function withLockFileGuard(cwd, fs, fn, options = {}) {
+  return withFileLock(lockFileGuardPath(cwd), fs, fn, options);
+}
+
+// src/lock/lock-file.ts
 var LOCK_FILE_NAME = "verbatra.lock.json";
 var CURRENT_VERSION = 1;
 var EMPTY_LOCK = { version: CURRENT_VERSION, locales: {} };
@@ -1594,8 +1797,7 @@ var lockFileSchema = z.object({
 function lockFilePath(cwd) {
   return resolve(cwd, LOCK_FILE_NAME);
 }
-async function readLockFile(path, fs) {
-  const read = await fs.readFileBounded(path, MAX_LOCK_FILE_BYTES);
+function parseLockFileRead(read, path) {
   if (read.kind === "missing") {
     return EMPTY_LOCK;
   }
@@ -1623,6 +1825,9 @@ async function readLockFile(path, fs) {
   }
   return result.data;
 }
+async function readLockFile(path, fs) {
+  return parseLockFileRead(await fs.readFileBounded(path, MAX_LOCK_FILE_BYTES), path);
+}
 function baselineFor(lock, locale) {
   return new Map(Object.entries(lock.locales[locale] ?? {}));
 }
@@ -1638,14 +1843,30 @@ function byKey(a, b) {
 function sortRecord(record) {
   return Object.fromEntries(Object.entries(record).sort(byKey));
 }
-async function writeLockFile(path, lock, fs) {
+function serializeLockFile(lock) {
   const locales = {};
   for (const [locale, entries] of Object.entries(lock.locales).sort(byKey)) {
     locales[locale] = sortRecord(entries);
   }
   const ordered = { version: lock.version, locales };
-  await fs.writeFile(path, `${JSON.stringify(ordered, null, 2)}
-`);
+  return `${JSON.stringify(ordered, null, 2)}
+`;
+}
+function applyLockLocalePatch(currentEntries, patch) {
+  if (patch.mode === "replace") {
+    return patch.entries;
+  }
+  return { ...currentEntries, ...patch.entries };
+}
+async function updateLockFileLocale(cwd, fs, locale, patch) {
+  return withLockFileGuard(cwd, fs, async () => {
+    const path = lockFilePath(cwd);
+    const lock = parseLockFileRead(await fs.readFileBounded(path, MAX_LOCK_FILE_BYTES), path);
+    const nextEntries = applyLockLocalePatch(lock.locales[locale], patch);
+    const next = updateLockLocale(lock, locale, nextEntries);
+    await fs.writeFile(path, serializeLockFile(next));
+    return next;
+  });
 }
 var VALID_EMPTY = { placeholders: [], isPlural: false, valid: true };
 var INVALID = { placeholders: [], isPlural: false, valid: false };
@@ -1907,10 +2128,68 @@ var AdapterError = class extends Error {
 };
 var MAX_DEPTH = 100;
 var MAX_INPUT_BYTES = 16 * 1024 * 1024;
-var jsonTreeSchema = z.lazy(
-  () => z.union([z.string(), z.record(z.string(), jsonTreeSchema)])
-);
-var rootSchema = z.record(z.string(), jsonTreeSchema);
+var SENTINEL_ESCAPE = "\\u0001";
+function isJsonWhitespace(char) {
+  return char === " " || char === "	" || char === "\n" || char === "\r";
+}
+function endOfStringToken(content, openQuote) {
+  let index = openQuote + 1;
+  while (index < content.length) {
+    const char = content[index];
+    if (char === "\\") {
+      index += 2;
+    } else if (char === '"') {
+      return index + 1;
+    } else {
+      index += 1;
+    }
+  }
+  return index;
+}
+function isKeyToken(content, end) {
+  let index = end;
+  while (isJsonWhitespace(content[index])) {
+    index += 1;
+  }
+  return content[index] === ":";
+}
+function prefixKeyToken(token) {
+  if (token.includes(SENTINEL_ESCAPE)) {
+    throw new AdapterError(
+      "INVALID_STRUCTURE",
+      "A key contains a reserved control-character escape."
+    );
+  }
+  return `"${SENTINEL_ESCAPE}${token.slice(1)}`;
+}
+function prefixKeyTokens(content) {
+  let out = "";
+  let index = 0;
+  while (index < content.length) {
+    const openQuote = content.indexOf('"', index);
+    if (openQuote === -1) {
+      return out + content.slice(index);
+    }
+    const end = endOfStringToken(content, openQuote);
+    const token = content.slice(openQuote, end);
+    out += content.slice(index, openQuote);
+    out += isKeyToken(content, end) ? prefixKeyToken(token) : token;
+    index = end;
+  }
+  return out;
+}
+function childrenOf(node) {
+  if (node instanceof Map) {
+    return node.values();
+  }
+  if (Array.isArray(node)) {
+    return node;
+  }
+  if (typeof node === "object" && node !== null) {
+    return Object.values(node);
+  }
+  return null;
+}
 function assertWithinDepth(value, max) {
   const stack = [{ node: value, depth: 1 }];
   while (stack.length > 0) {
@@ -1918,42 +2197,118 @@ function assertWithinDepth(value, max) {
     if (top === void 0) {
       break;
     }
-    const { node, depth } = top;
-    if (typeof node !== "object" || node === null) {
+    const children = childrenOf(top.node);
+    if (children === null) {
       continue;
     }
-    if (depth > max) {
+    if (top.depth > max) {
       throw new AdapterError("MAX_DEPTH_EXCEEDED", "The file nests objects too deeply.");
     }
-    for (const child of Object.values(node)) {
-      stack.push({ node: child, depth: depth + 1 });
+    for (const child of children) {
+      stack.push({ node: child, depth: top.depth + 1 });
     }
   }
 }
-function assertJsonRecord(value) {
-  assertWithinDepth(value, MAX_DEPTH);
-  const result = rootSchema.safeParse(value);
-  if (!result.success) {
-    throw new AdapterError(
-      "INVALID_STRUCTURE",
-      "The file is not a valid object (expected nested objects of string values)."
-    );
+function toOrdered(node) {
+  if (Array.isArray(node)) {
+    return node.map((child) => toOrdered(child));
   }
-  return result.data;
+  if (typeof node === "object" && node !== null) {
+    const out = /* @__PURE__ */ new Map();
+    for (const [key, child] of Object.entries(node)) {
+      out.set(key.slice(1), toOrdered(child));
+    }
+    return out;
+  }
+  return node;
 }
-function parseJsonObject(content) {
+function parseOrderedJson(content) {
+  const prefixed = prefixKeyTokens(content);
   let parsed;
   try {
-    parsed = JSON.parse(content);
+    parsed = JSON.parse(prefixed);
   } catch {
     throw new AdapterError("INVALID_JSON", "The file is not valid JSON.");
   }
-  return assertJsonRecord(parsed);
+  assertWithinDepth(parsed, MAX_DEPTH);
+  return toOrdered(parsed);
 }
-function serializeJsonTree(tree) {
-  return `${JSON.stringify(tree, null, 2)}
+function printRecord(record, indent) {
+  if (record.size === 0) {
+    return "{}";
+  }
+  const childIndent = `${indent}  `;
+  const lines = [];
+  for (const [key, child] of record) {
+    lines.push(`${childIndent}${JSON.stringify(key)}: ${printValue(child, childIndent)}`);
+  }
+  return `{
+${lines.join(",\n")}
+${indent}}`;
+}
+function printArray(items, indent) {
+  if (items.length === 0) {
+    return "[]";
+  }
+  const childIndent = `${indent}  `;
+  const lines = items.map((item) => `${childIndent}${printValue(item, childIndent)}`);
+  return `[
+${lines.join(",\n")}
+${indent}]`;
+}
+function printValue(value, indent) {
+  if (value instanceof Map) {
+    return printRecord(value, indent);
+  }
+  if (Array.isArray(value)) {
+    return printArray(value, indent);
+  }
+  return JSON.stringify(value);
+}
+function serializeOrderedJson(value) {
+  return `${printValue(value, "")}
 `;
 }
+var INVALID_STRUCTURE_MESSAGE = "The file is not a valid object (expected nested objects of string, number, boolean, or null leaves).";
+function isJsonLeaf(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null;
+}
+function assertNodesValid(root) {
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (node === void 0) {
+      break;
+    }
+    for (const [key, child] of node) {
+      if (typeof key !== "string") {
+        throw new AdapterError("INVALID_STRUCTURE", INVALID_STRUCTURE_MESSAGE);
+      }
+      if (child instanceof Map) {
+        stack.push(child);
+      } else if (!isJsonLeaf(child)) {
+        throw new AdapterError("INVALID_STRUCTURE", INVALID_STRUCTURE_MESSAGE);
+      }
+    }
+  }
+}
+function assertJsonRecord(value) {
+  assertWithinDepth(value, MAX_DEPTH);
+  if (!(value instanceof Map)) {
+    throw new AdapterError("INVALID_STRUCTURE", INVALID_STRUCTURE_MESSAGE);
+  }
+  assertNodesValid(value);
+  return value;
+}
+function parseJsonObject(content) {
+  return assertJsonRecord(parseOrderedJson(content));
+}
+function serializeJsonTree(tree) {
+  return serializeOrderedJson(tree);
+}
+function isJsonNode(value) {
+  return value instanceof Map;
+}
 function namespaceOf(filePath) {
   return basename(filePath, extname(filePath));
 }
@@ -1981,9 +2336,25 @@ function buildCanHandle(extensions, sniff) {
     return sample === void 0 || sniff === void 0 || sniff(sample);
   };
 }
+async function fsyncPath(path) {
+  const handle = await open(path, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function fsyncDirBestEffort(path) {
+  try {
+    await fsyncPath(path);
+  } catch {
+  }
+}
 var nodeOps = {
   writeFile: (path, data) => writeFile(path, data, "utf8"),
+  fsyncFile: (path) => fsyncPath(path),
   rename: (from, to) => rename(from, to),
+  fsyncDir: (path) => fsyncDirBestEffort(path),
   rm: (path) => rm(path, { force: true })
 };
 async function cleanup(ops, tmp) {
@@ -1999,11 +2370,16 @@ async function atomicWriteFile(path, data, ops = nodeOps) {
   const tmp = tempFileName2(path);
   try {
     await ops.writeFile(tmp, data);
+    await ops.fsyncFile(tmp);
     await ops.rename(tmp, path);
   } catch (error) {
     await cleanup(ops, tmp);
     throw error;
   }
+  try {
+    await ops.fsyncDir(dirname(path));
+  } catch {
+  }
 }
 function stripLeadingBom(content) {
   return content.charCodeAt(0) === 65279 ? content.slice(1) : content;
@@ -2125,21 +2501,25 @@ function addLeaf(ctx, segments, key, value) {
     );
   }
   ctx.claimed.set(effectivePath, mapKey);
+  if (typeof value !== "string") {
+    ctx.excluded.push(mapKey);
+    return;
+  }
   const { placeholders, isPlural } = ctx.derive(key, value);
   ctx.out.set(mapKey, { key: mapKey, namespace: ctx.namespace, value, placeholders, isPlural });
 }
 function addEntries(ctx, prefix, node) {
-  for (const [key, value] of Object.entries(node)) {
+  for (const [key, value] of node) {
     const segments = [...prefix, key];
-    if (typeof value === "string") {
-      addLeaf(ctx, segments, key, value);
-    } else {
+    if (isJsonNode(value)) {
       addEntries(ctx, segments, value);
+    } else {
+      addLeaf(ctx, segments, key, value);
     }
   }
 }
-function addPathEntries(node, prefix, namespace, derive, out, claimedPaths) {
-  for (const [key, value] of Object.entries(node)) {
+function addPathEntries(node, prefix, namespace, derive, out, claimedPaths, excluded) {
+  for (const [key, value] of node) {
     const path = prefix === "" ? key : `${prefix}.${key}`;
     if (claimedPaths.has(path)) {
       throw new AdapterError(
@@ -2148,34 +2528,35 @@ function addPathEntries(node, prefix, namespace, derive, out, claimedPaths) {
       );
     }
     claimedPaths.add(path);
-    if (typeof value === "string") {
+    if (isJsonNode(value)) {
+      addPathEntries(value, path, namespace, derive, out, claimedPaths, excluded);
+    } else if (typeof value === "string") {
       const { placeholders, isPlural } = derive(key, value);
       out.set(path, { key: path, namespace, value, placeholders, isPlural });
     } else {
-      addPathEntries(value, path, namespace, derive, out, claimedPaths);
+      excluded.push(path);
     }
   }
 }
 function flattenTree(tree, namespace, derive, keyMode = "literal-leaf") {
   const out = /* @__PURE__ */ new Map();
   if (keyMode === "path-notation") {
-    addPathEntries(tree, "", namespace, derive, out, /* @__PURE__ */ new Set());
-    return out;
+    const excluded = [];
+    addPathEntries(tree, "", namespace, derive, out, /* @__PURE__ */ new Set(), excluded);
+    return { entries: out, excludedLeafPaths: excluded };
   }
-  addEntries({ namespace, derive, out, claimed: /* @__PURE__ */ new Map() }, [], tree);
-  return out;
-}
-function emptyNode() {
-  return /* @__PURE__ */ Object.create(null);
+  const ctx = { namespace, derive, out, claimed: /* @__PURE__ */ new Map(), excluded: [] };
+  addEntries(ctx, [], tree);
+  return { entries: out, excludedLeafPaths: ctx.excluded };
 }
 function descend(node, segment) {
-  const next = node[segment];
+  const next = node.get(segment);
   if (next === void 0) {
-    const created = emptyNode();
-    node[segment] = created;
+    const created = /* @__PURE__ */ new Map();
+    node.set(segment, created);
     return created;
   }
-  if (typeof next === "object") {
+  if (next instanceof Map) {
     return next;
   }
   throw new AdapterError("INVALID_STRUCTURE", "A leaf key collides with a nested key path.");
@@ -2189,13 +2570,13 @@ function setPath(root, segments, value) {
   for (const segment of segments.slice(0, -1)) {
     node = descend(node, segment);
   }
-  if (typeof node[leaf] === "object") {
+  if (node.get(leaf) instanceof Map) {
     throw new AdapterError("INVALID_STRUCTURE", "A leaf key collides with a nested key path.");
   }
-  node[leaf] = value;
+  node.set(leaf, value);
 }
 function unflattenEntries(entries) {
-  const root = emptyNode();
+  const root = /* @__PURE__ */ new Map();
   for (const [key, entry] of entries) {
     setPath(root, decodeKeyToSegments(key), entry.value);
   }
@@ -2216,9 +2597,9 @@ function toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTre
   try {
     const tree = parse3(content);
     validateTree?.(tree);
-    const entries = flattenTree(tree, namespace, deriveEntry, keyMode);
-    mergeDescriptions(entries, content, deriveDescriptions);
-    return entries;
+    const result = flattenTree(tree, namespace, deriveEntry, keyMode);
+    mergeDescriptions(result.entries, content, deriveDescriptions);
+    return result;
   } catch (error) {
     rethrowStructured(error, "The file could not be parsed.");
   }
@@ -2249,7 +2630,7 @@ function createTreeFileAdapter(options) {
     async read(filePath, locale) {
       const content = await readFileContent(filePath);
       const namespace = namespaceOf(filePath);
-      const entries = toEntries(
+      const { entries, excludedLeafPaths } = toEntries(
         content,
         namespace,
         parse3,
@@ -2260,7 +2641,7 @@ function createTreeFileAdapter(options) {
       );
       const resource = { locale, namespace, format, entries };
       const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys);
-      return { resource, invalidIcuKeys };
+      return { resource, invalidIcuKeys, excludedLeafPaths };
     },
     async write(resource, filePath) {
       const tree = buildWriteTree ? await buildWriteTree(resource.entries, filePath) : unflattenEntries(resource.entries);
@@ -2272,13 +2653,8 @@ function isMetadataKey(key) {
   return key.startsWith("@");
 }
 function parseArbObject(content) {
-  let parsed;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    throw new AdapterError("INVALID_JSON", "The file is not valid JSON.");
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+  const parsed = parseOrderedJson(content);
+  if (!(parsed instanceof Map)) {
     throw new AdapterError(
       "INVALID_STRUCTURE",
       "The file is not a valid object (expected nested objects of string values)."
@@ -2287,10 +2663,10 @@ function parseArbObject(content) {
   return parsed;
 }
 function stripArbMetadata(tree) {
-  const out = /* @__PURE__ */ Object.create(null);
-  for (const [key, value] of Object.entries(tree)) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, value] of tree) {
     if (!isMetadataKey(key)) {
-      out[key] = value;
+      out.set(key, value);
     }
   }
   return out;
@@ -2302,16 +2678,16 @@ function messageKeyForMetadata(key) {
   return isMetadataKey(key) && !key.startsWith("@@") ? key.slice(1) : null;
 }
 function descriptionOf(value) {
-  if (typeof value !== "object" || value === null) {
+  if (!(value instanceof Map)) {
     return void 0;
   }
-  const description = value.description;
+  const description = value.get("description");
   return typeof description === "string" ? description : void 0;
 }
 function extractArbDescriptions(content) {
   const tree = parseArbObject(content);
   const out = /* @__PURE__ */ new Map();
-  for (const [key, value] of Object.entries(tree)) {
+  for (const [key, value] of tree) {
     const messageKey = messageKeyForMetadata(key);
     if (messageKey === null) {
       continue;
@@ -2343,23 +2719,25 @@ async function readDestinationPairs(filePath) {
     }
     throw error;
   }
-  return Object.entries(parseArbObject(content));
+  return [...parseArbObject(content)];
 }
 async function buildArbWriteTree(entries, filePath) {
   const messages = messagesFromEntries(entries);
   const pairs = await readDestinationPairs(filePath);
-  const out = /* @__PURE__ */ Object.create(null);
+  const out = /* @__PURE__ */ new Map();
   const consumed = /* @__PURE__ */ new Set();
   for (const [key, value] of pairs ?? []) {
     const translated = isMetadataKey(key) ? void 0 : messages.get(key);
     if (translated !== void 0) {
       consumed.add(key);
+      out.set(key, translated);
+    } else if (isMetadataKey(key) || typeof value === "string") {
+      out.set(key, value);
     }
-    out[key] = translated ?? value;
   }
   for (const [key, value] of messages) {
     if (!consumed.has(key)) {
-      out[key] = value;
+      out.set(key, value);
     }
   }
   return out;
@@ -2448,8 +2826,8 @@ function createNextIntlJsonAdapter() {
   });
 }
 function assertNoDottedNestedKey(tree) {
-  for (const [key, value] of Object.entries(tree)) {
-    if (typeof value !== "object") {
+  for (const [key, value] of tree) {
+    if (!isJsonNode(value)) {
       continue;
     }
     if (key.includes(".")) {
@@ -2464,8 +2842,8 @@ function assertNoDottedNestedKey(tree) {
 function assertNotMixed(tree) {
   let hasNested = false;
   let hasFlatDottedKey = false;
-  for (const [key, value] of Object.entries(tree)) {
-    if (typeof value === "object") {
+  for (const [key, value] of tree) {
+    if (isJsonNode(value)) {
       hasNested = true;
     } else if (key.includes(".")) {
       hasFlatDottedKey = true;
@@ -2501,9 +2879,9 @@ async function detectStyle(filePath) {
   return "flat";
 }
 function buildFlatTree(entries) {
-  const out = /* @__PURE__ */ Object.create(null);
+  const out = /* @__PURE__ */ new Map();
   for (const [key, entry] of entries) {
-    out[key] = entry.value;
+    out.set(key, entry.value);
   }
   return out;
 }
@@ -2521,7 +2899,6 @@ function createNgxTranslateJsonAdapter() {
     }),
     validateTree: assertNotMixed,
     buildWriteTree: buildNgxWriteTree,
-    // ngx-translate flat style uses dotted keys as path notation, not literal leaves.
     keyMode: "path-notation"
   });
 }
@@ -2547,6 +2924,11 @@ var AdapterRegistry = class {
     }
     return { status: "resolved", adapter };
   }
+  /**
+   * 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.
+   */
   resolveByDetection(filePath, sample) {
     const matches = this.adapters.filter((adapter) => adapter.canHandle(filePath, sample));
     const first = matches[0];
@@ -2626,7 +3008,7 @@ function createFlatFileAdapter(options) {
       const entries = toEntries2(content, namespace, parseEntries);
       const resource = { locale, namespace, format, entries };
       const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys);
-      return { resource, invalidIcuKeys };
+      return { resource, invalidIcuKeys, excludedLeafPaths: [] };
     },
     async write(resource, filePath) {
       const data = await serializeEntries(resource.entries, filePath);
@@ -2901,14 +3283,34 @@ function createXliffAdapter() {
     extractPlaceholders: extractXliffPlaceholders
   });
 }
+function normalizeKey(key) {
+  if (typeof key === "object" && key !== null) {
+    throw new AdapterError(
+      "INVALID_STRUCTURE",
+      "A mapping key is a map or sequence (expected scalar keys)."
+    );
+  }
+  return String(key);
+}
+function normalizeYamlTree(value) {
+  if (!(value instanceof Map)) {
+    return value;
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, child] of value) {
+    out.set(normalizeKey(key), normalizeYamlTree(child));
+  }
+  return out;
+}
 function parseYamlObject(content) {
   let parsed;
   try {
-    parsed = parse$1(content, { maxAliasCount: 100 });
+    parsed = parse$1(content, { mapAsMap: true, maxAliasCount: 100 });
   } catch {
     throw new AdapterError("INVALID_YAML", "The file is not valid YAML.");
   }
-  return assertJsonRecord(parsed);
+  assertWithinDepth(parsed, MAX_DEPTH);
+  return assertJsonRecord(normalizeYamlTree(parsed));
 }
 function createYamlAdapter() {
   return createTreeFileAdapter({
@@ -2939,6 +3341,15 @@ function selectAdapter(format, registry = createDefaultRegistry()) {
   );
 }
 
+// src/flow/read-target.ts
+async function readTargetResource(input) {
+  const path = localeFilePath(input.cwd, input.filesPattern, input.locale);
+  if (!await input.fs.fileExists(path)) {
+    return { locale: input.locale, namespace: "", format: input.format, entries: /* @__PURE__ */ new Map() };
+  }
+  return (await input.adapter.read(path, input.locale)).resource;
+}
+
 // src/flow/select-locales.ts
 function selectLocales(config, requested) {
   if (requested === void 0) {
@@ -2979,11 +3390,14 @@ async function readSource(config, cwd, fs, adapter) {
 
 // src/flow/diff-locales.ts
 async function readTarget(cwd, config, adapter, fs, locale) {
-  const path = localeFilePath(cwd, config.files.pattern, locale);
-  if (!await fs.fileExists(path)) {
-    return { locale, namespace: "", format: config.format, entries: /* @__PURE__ */ new Map() };
-  }
-  return (await adapter.read(path, locale)).resource;
+  return readTargetResource({
+    cwd,
+    filesPattern: config.files.pattern,
+    format: config.format,
+    locale,
+    adapter,
+    fs
+  });
 }
 async function diffLocales(input, deps = {}) {
   const config = input.config;
@@ -3033,6 +3447,166 @@ async function diff(input, deps = {}) {
   return { hasPendingChanges: locales.some((entry) => entry.hasPendingChanges), locales };
 }
 
+// src/flow/integrity-gate.ts
+function gateCandidateValue(sourceEntry, candidateValue, adapter) {
+  const placeholderResult = adapter.comparePlaceholders?.(sourceEntry.value, candidateValue) ?? checkPlaceholders(sourceEntry.placeholders, adapter.extractPlaceholders(candidateValue));
+  if (!placeholderResult.matches) {
+    return { accepted: false, reason: "placeholder" };
+  }
+  if (!adapter.validateMessage(candidateValue)) {
+    return { accepted: false, reason: "icu" };
+  }
+  return { accepted: true };
+}
+
+// src/flow/edit-entry.ts
+async function editEntry(input, deps = {}) {
+  const config = input.config;
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const [locale] = selectLocales(config, [input.locale]);
+  if (locale === void 0) {
+    throw new SdkError("UNKNOWN_LOCALE", `Locale "${input.locale}" could not be resolved.`);
+  }
+  const source = await readSource(config, cwd, fs, adapter);
+  const sourceEntry = source.resource.entries.get(input.key);
+  if (sourceEntry === void 0) {
+    throw new SdkError(
+      "UNKNOWN_KEY",
+      `The key "${input.key}" was not found in the source resource.`
+    );
+  }
+  return withLocaleWriteLock(cwd, locale, fs, async () => {
+    const target = await readTarget(cwd, config, adapter, fs, locale);
+    const gate = gateCandidateValue(sourceEntry, input.value, adapter);
+    if (!gate.accepted) {
+      return { accepted: false, reason: gate.reason, value: input.value };
+    }
+    const merged = new Map(target.entries);
+    merged.set(input.key, { ...sourceEntry, value: input.value, namespace: target.namespace });
+    const path = localeFilePath(cwd, config.files.pattern, locale);
+    await adapter.write(
+      { locale, namespace: target.namespace, format: config.format, entries: merged },
+      path
+    );
+    await updateLockFileLocale(cwd, fs, locale, {
+      mode: "merge",
+      entries: { [input.key]: contentHash(sourceEntry) }
+    });
+    return { accepted: true, value: input.value };
+  });
+}
+
+// src/flow/key-integrity.ts
+function checkEntryIntegrity(adapter, sourceEntry, targetEntry) {
+  const result = adapter.comparePlaceholders?.(sourceEntry.value, targetEntry.value) ?? checkPlaceholders(sourceEntry.placeholders, targetEntry.placeholders);
+  return {
+    key: sourceEntry.key,
+    hasPlaceholders: sourceEntry.placeholders.length > 0,
+    matches: result.matches,
+    missing: result.missing,
+    extra: result.extra,
+    icuValid: adapter.validateMessage(targetEntry.value)
+  };
+}
+function selectChangedKeys(changed, requested) {
+  if (requested === void 0) {
+    return changed;
+  }
+  const wanted = new Set(requested);
+  return changed.filter((key) => wanted.has(key));
+}
+function integrityEntriesFor(source, target, adapter, changedKeys) {
+  const entries = [];
+  for (const key of changedKeys) {
+    const sourceEntry = source.entries.get(key);
+    const targetEntry = target.entries.get(key);
+    if (sourceEntry === void 0 || targetEntry === void 0) {
+      continue;
+    }
+    entries.push(checkEntryIntegrity(adapter, sourceEntry, targetEntry));
+  }
+  return entries;
+}
+async function keyIntegrity(input, deps = {}) {
+  const config = input.config;
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const source = await readSource(config, cwd, fs, adapter);
+  const lock = await readLockFile(lockFilePath(cwd), fs);
+  return Promise.all(
+    selectLocales(config, input.locales).map(async (locale) => {
+      const target = await readTarget(cwd, config, adapter, fs, locale);
+      const diffResult = diffResources(source.resource, target, {
+        baseline: baselineFor(lock, locale)
+      });
+      const changedKeys = selectChangedKeys(diffResult.changed, input.keys);
+      const entries = integrityEntriesFor(source.resource, target, adapter, changedKeys);
+      return { locale, entries };
+    })
+  );
+}
+
+// src/flow/key-value.ts
+async function keyValue(input, deps = {}) {
+  const config = input.config;
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const [locale] = selectLocales(config, [input.locale]);
+  if (locale === void 0) {
+    throw new SdkError("UNKNOWN_LOCALE", `Locale "${input.locale}" could not be resolved.`);
+  }
+  const source = await readSource(config, cwd, fs, adapter);
+  const sourceEntry = source.resource.entries.get(input.key);
+  if (sourceEntry === void 0) {
+    throw new SdkError(
+      "UNKNOWN_KEY",
+      `The key "${input.key}" was not found in the source resource.`
+    );
+  }
+  const target = await readTarget(cwd, config, adapter, fs, locale);
+  const targetEntry = target.entries.get(input.key);
+  return {
+    source: sourceEntry.value,
+    ...targetEntry !== void 0 ? { target: targetEntry.value } : {}
+  };
+}
+
+// src/flow/locale-snapshot.ts
+async function readLocaleFileSnapshot(input, deps = {}) {
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const adapter = selectAdapter(input.config.format, deps.adapterRegistry);
+  const resource = await readTarget(cwd, input.config, adapter, fs, input.locale);
+  const hashes = /* @__PURE__ */ new Map();
+  for (const [key, entry] of resource.entries) {
+    hashes.set(key, contentHash(entry));
+  }
+  return { locale: input.locale, hashes };
+}
+function diffLocaleSnapshots(previous, current) {
+  let added = 0;
+  let changed = 0;
+  for (const [key, hash] of current.hashes) {
+    const previousHash = previous.hashes.get(key);
+    if (previousHash === void 0) {
+      added += 1;
+    } else if (previousHash !== hash) {
+      changed += 1;
+    }
+  }
+  let removed = 0;
+  for (const key of previous.hashes.keys()) {
+    if (!current.hashes.has(key)) {
+      removed += 1;
+    }
+  }
+  return { added, changed, removed };
+}
+
 // src/flow/lock-state.ts
 function toLockLocaleState(locale, keyCount, diff2) {
   return {
@@ -3080,6 +3654,214 @@ function selectProvider(config, createProvider = buildProvider) {
   }
 }
 
+// src/flow/retranslate-entry.ts
+function buildSingleEntryRequest(config, locale, sourceEntry, adapter) {
+  return {
+    sourceLocale: config.sourceLocale,
+    targetLocale: locale,
+    entries: [sourceEntry],
+    extractPlaceholders: adapter.extractPlaceholders,
+    ...config.glossary !== void 0 ? { glossary: config.glossary } : {},
+    ...config.tone !== void 0 ? { tone: config.tone } : {},
+    ...adapter.comparePlaceholders !== void 0 ? { comparePlaceholders: adapter.comparePlaceholders } : {}
+  };
+}
+async function retranslateEntry(input, deps = {}) {
+  const config = input.config;
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const [locale] = selectLocales(config, [input.locale]);
+  if (locale === void 0) {
+    throw new SdkError("UNKNOWN_LOCALE", `Locale "${input.locale}" could not be resolved.`);
+  }
+  const source = await readSource(config, cwd, fs, adapter);
+  const sourceEntry = source.resource.entries.get(input.key);
+  if (sourceEntry === void 0) {
+    throw new SdkError(
+      "UNKNOWN_KEY",
+      `The key "${input.key}" was not found in the source resource.`
+    );
+  }
+  const provider = selectProvider(config.provider, deps.createProvider);
+  return withLocaleWriteLock(cwd, locale, fs, async () => {
+    const target = await readTarget(cwd, config, adapter, fs, locale);
+    const result = await provider.translateBatch(
+      buildSingleEntryRequest(config, locale, sourceEntry, adapter)
+    );
+    const value = result.values.get(input.key);
+    if (value === void 0) {
+      throw new ProviderError(
+        "INVALID_RESPONSE",
+        `The provider returned no translated value for key "${input.key}".`
+      );
+    }
+    const gate = gateCandidateValue(sourceEntry, value, adapter);
+    if (!gate.accepted) {
+      return { accepted: false, reason: gate.reason, value };
+    }
+    const merged = new Map(target.entries);
+    merged.set(input.key, { ...sourceEntry, value, namespace: target.namespace });
+    const path = localeFilePath(cwd, config.files.pattern, locale);
+    await adapter.write(
+      { locale, namespace: target.namespace, format: config.format, entries: merged },
+      path
+    );
+    await updateLockFileLocale(cwd, fs, locale, {
+      mode: "merge",
+      entries: { [input.key]: contentHash(sourceEntry) }
+    });
+    const reviewReasons = result.reviewFlags?.get(input.key)?.reasons ?? [];
+    return { accepted: true, value, reviewReasons };
+  });
+}
+var RUN_STATUS_DIR_NAME = ".verbatra-local";
+var RUN_STATUS_FILE_NAME = "run-status.json";
+var CURRENT_VERSION2 = 1;
+var MAX_RUN_STATUS_FILE_BYTES = 16 * 1024 * 1024;
+var reviewReasonCodeSchema = z.enum([
+  "LENGTH_RATIO_OUTLIER",
+  "EQUALS_SOURCE",
+  "GLOSSARY_TERM_MISSED",
+  "INTEGRITY_REORDERED",
+  "PROVIDER_DEGRADED"
+]);
+var needsReviewEntrySchema = z.object({
+  key: z.string(),
+  reasons: z.array(reviewReasonCodeSchema)
+});
+var usageSummarySchema = z.object({
+  inputTokens: z.number().int().nonnegative(),
+  outputTokens: z.number().int().nonnegative()
+});
+var runBudgetSchema = z.object({
+  maxTokens: z.number().int().nonnegative(),
+  behavior: z.enum(["warn", "stop"]),
+  supported: z.boolean(),
+  tokensUsed: z.number().int().nonnegative(),
+  exceeded: z.boolean()
+});
+var runStatusLocaleSchema = z.object({
+  locale: z.string(),
+  status: z.enum(["succeeded", "failed"]),
+  needsReview: z.array(needsReviewEntrySchema),
+  usage: usageSummarySchema.optional()
+});
+var runStatusFileSchema = z.object({
+  version: z.number().int().positive(),
+  generatedAt: z.string(),
+  usage: usageSummarySchema.optional(),
+  budget: runBudgetSchema.optional(),
+  locales: z.array(runStatusLocaleSchema)
+});
+function runStatusFilePath(cwd) {
+  return resolve(cwd, RUN_STATUS_DIR_NAME, RUN_STATUS_FILE_NAME);
+}
+function toRunStatusLocale(locale) {
+  return {
+    locale: locale.locale,
+    status: locale.status,
+    needsReview: locale.needsReview,
+    ...locale.usage !== void 0 ? { usage: locale.usage } : {}
+  };
+}
+function buildRunStatusFile(summary, generatedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  return {
+    version: CURRENT_VERSION2,
+    generatedAt,
+    ...summary.usage !== void 0 ? { usage: summary.usage } : {},
+    ...summary.budget !== void 0 ? { budget: summary.budget } : {},
+    locales: summary.locales.map(toRunStatusLocale)
+  };
+}
+function fromParsed(data) {
+  return {
+    version: data.version,
+    generatedAt: data.generatedAt,
+    ...data.usage !== void 0 ? { usage: data.usage } : {},
+    ...data.budget !== void 0 ? { budget: data.budget } : {},
+    locales: data.locales.map((locale) => ({
+      locale: locale.locale,
+      status: locale.status,
+      needsReview: locale.needsReview,
+      ...locale.usage !== void 0 ? { usage: locale.usage } : {}
+    }))
+  };
+}
+async function readRunStatusFile(path, fs) {
+  const read = await fs.readFileBounded(path, MAX_RUN_STATUS_FILE_BYTES);
+  if (read.kind !== "ok") {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(read.content);
+  } catch {
+    return void 0;
+  }
+  const result = runStatusFileSchema.safeParse(parsed);
+  if (!result.success || result.data.version !== CURRENT_VERSION2) {
+    return void 0;
+  }
+  return fromParsed(result.data);
+}
+async function writeRunStatusFile(path, data, fs) {
+  await mkdir(dirname(path), { recursive: true });
+  await fs.writeFile(path, `${JSON.stringify(data, null, 2)}
+`);
+}
+
+// src/flow/run-status.ts
+async function runStatus(input = {}, deps = {}) {
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const file = await readRunStatusFile(runStatusFilePath(cwd), fs);
+  if (file === void 0) {
+    return { available: false };
+  }
+  return { available: true, ...file };
+}
+
+// src/flow/budget.ts
+function createBudgetTracker(maxTokens, behavior) {
+  return { maxTokens, behavior, tokensUsed: 0, usageSeen: false, exceeded: false, stopped: false };
+}
+function foldTrackerUsage(tracker, usage) {
+  if (usage === void 0) {
+    return;
+  }
+  tracker.usageSeen = true;
+  tracker.tokensUsed += usage.inputTokens + usage.outputTokens;
+}
+function checkBudgetTrip(tracker) {
+  if (tracker.maxTokens === void 0 || tracker.exceeded || tracker.tokensUsed < tracker.maxTokens) {
+    return false;
+  }
+  tracker.exceeded = true;
+  if (tracker.behavior === "stop") {
+    tracker.stopped = true;
+  }
+  return true;
+}
+function toBudgetSummary(tracker) {
+  if (tracker.maxTokens === void 0) {
+    return void 0;
+  }
+  return {
+    maxTokens: tracker.maxTokens,
+    behavior: tracker.behavior,
+    supported: tracker.usageSeen,
+    tokensUsed: tracker.tokensUsed,
+    exceeded: tracker.exceeded
+  };
+}
+function budgetExceededNotice(tracker) {
+  return {
+    code: "BUDGET_TOKENS_EXCEEDED",
+    message: `The run's cumulative token usage (${tracker.tokensUsed}) reached the configured budget of ${tracker.maxTokens} tokens (behavior: ${tracker.behavior}).`
+  };
+}
+
 // src/flow/locale-failure.ts
 function describeError(error) {
   if (error instanceof Error) {
@@ -3099,8 +3881,10 @@ function failureSummary(locale, error) {
     invalidIcuSource: [],
     integrityMismatches: [],
     providerFailures: [],
+    budgetWithheld: [],
     generated: [],
     notices: [],
+    needsReview: [],
     error: describeError(error)
   };
 }
@@ -3270,7 +4054,43 @@ function planPluralGeneration(source, targetLocale, format) {
   return { items };
 }
 
+// src/flow/usage.ts
+function createUsageAccumulator() {
+  return { total: void 0 };
+}
+function foldUsage(accumulator, usage) {
+  if (usage === void 0) {
+    return;
+  }
+  const prior = accumulator.total ?? { inputTokens: 0, outputTokens: 0 };
+  accumulator.total = {
+    inputTokens: prior.inputTokens + usage.inputTokens,
+    outputTokens: prior.outputTokens + usage.outputTokens
+  };
+}
+function combineUsage(a, b) {
+  if (a === void 0) {
+    return b;
+  }
+  if (b === void 0) {
+    return a;
+  }
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens
+  };
+}
+
 // src/flow/plural-generation.ts
+var EMPTY_RESULT = {
+  accepted: [],
+  withheld: [],
+  providerFailures: [],
+  budgetWithheld: [],
+  notices: [],
+  usage: void 0,
+  tripped: false
+};
 function generatedLockHash(governingEntries, category) {
   const governingHashes = governingEntries.map(contentHash).sort();
   return contentHash({
@@ -3284,7 +4104,6 @@ function syntheticEntry(item) {
     ...item.sourceEntry,
     key: item.targetKey,
     isPlural: true,
-    // The CLDR category travels as data context (the meaning field), never the instruction channel.
     meaning: `CLDR plural category "${item.category}"`
   };
 }
@@ -3309,23 +4128,45 @@ async function generatePluralForms(context) {
   const plan = planPluralGeneration(context.source, context.targetLocale, context.format);
   const stale = staleItems(plan.items, context.baseline);
   if (stale.length === 0) {
-    return { accepted: [], withheld: [], providerFailures: [], notices: [] };
+    return EMPTY_RESULT;
   }
   const accepted = [];
   const withheld = [];
   const providerFailures = [];
+  const budgetWithheld = [];
   const notices = [];
+  const usage = createUsageAccumulator();
+  let tripped = false;
   for (const batch of chunk(stale, context.maxBatchSize)) {
-    const batchNotices = await runGenerationSubBatch(
+    if (context.budget.stopped) {
+      for (const item of batch) {
+        budgetWithheld.push(item.targetKey);
+      }
+      continue;
+    }
+    const subResult = await runGenerationSubBatch(
       context,
       batch,
       accepted,
       withheld,
       providerFailures
     );
-    notices.push(...batchNotices);
+    notices.push(...subResult.notices);
+    foldUsage(usage, subResult.usage);
+    foldTrackerUsage(context.budget, subResult.usage);
+    if (checkBudgetTrip(context.budget)) {
+      tripped = true;
+    }
   }
-  return { accepted, withheld, providerFailures, notices };
+  return {
+    accepted,
+    withheld,
+    providerFailures,
+    budgetWithheld,
+    notices,
+    usage: usage.total,
+    tripped
+  };
 }
 async function runGenerationSubBatch(context, batch, accepted, withheld, providerFailures) {
   let result;
@@ -3336,20 +4177,20 @@ async function runGenerationSubBatch(context, batch, accepted, withheld, provide
     for (const item of batch) {
       providerFailures.push(item.targetKey);
     }
-    return [subBatchFailedNotice(batch.length, error)];
+    return { notices: [subBatchFailedNotice(batch.length, error)], usage: void 0 };
   }
   for (const item of batch) {
-    foldGenerationItem(item, result, accepted, withheld, providerFailures);
+    foldGenerationItem(item, result, context.adapter, accepted, withheld, providerFailures);
   }
-  return readNotices(result);
+  return { notices: readNotices(result), usage: result.usage };
 }
-function foldGenerationItem(item, result, accepted, withheld, providerFailures) {
+function foldGenerationItem(item, result, adapter, accepted, withheld, providerFailures) {
   const value = result.values.get(item.targetKey);
   if (value === void 0) {
     providerFailures.push(item.targetKey);
     return;
   }
-  if (result.integrity.get(item.targetKey)?.matches === true) {
+  if (gateCandidateValue(item.sourceEntry, value, adapter).accepted) {
     accepted.push({
       targetKey: item.targetKey,
       entry: { ...syntheticEntry(item), value },
@@ -3361,16 +4202,6 @@ function foldGenerationItem(item, result, accepted, withheld, providerFailures)
 }
 
 // src/flow/locale-run.ts
-function emptyResource(locale, format) {
-  return { locale, namespace: "", format, entries: /* @__PURE__ */ new Map() };
-}
-async function readTarget2(params) {
-  const path = localeFilePath(params.cwd, params.filesPattern, params.targetLocale);
-  if (!await params.fs.fileExists(path)) {
-    return emptyResource(params.targetLocale, params.format);
-  }
-  return (await params.adapter.read(path, params.targetLocale)).resource;
-}
 function buildRequest3(params, entries) {
   return {
     sourceLocale: params.sourceLocale,
@@ -3383,7 +4214,14 @@ function buildRequest3(params, entries) {
   };
 }
 async function runLocale(params) {
-  const target = await readTarget2(params);
+  const target = await readTargetResource({
+    cwd: params.cwd,
+    filesPattern: params.filesPattern,
+    format: params.format,
+    locale: params.targetLocale,
+    adapter: params.adapter,
+    fs: params.fs
+  });
   const diff2 = diffResources(params.source, target, { baseline: params.baseline });
   const orphaned = params.generatePlurals ? diff2.orphaned.filter((key) => !isGeneratedPluralKey(key, sourcePluralBaseKeys(params.source))) : diff2.orphaned;
   const pruned = params.prune ? orphaned : [];
@@ -3409,6 +4247,7 @@ async function runLocale(params) {
         generated: [],
         integrityMismatches: [],
         providerFailures: [],
+        budgetWithheld: [],
         pruned,
         notices: sdkNotices
       }),
@@ -3416,23 +4255,31 @@ async function runLocale(params) {
     };
   }
   const entries = toTranslate.map((key) => params.source.entries.get(key)).filter((entry) => entry !== void 0);
+  const startedStopped = params.budget.stopped;
   const accepted = /* @__PURE__ */ new Map();
   const integrityMismatches = [];
   const providerFailures = [];
-  const subBatchNotices = await translateAndCheck(
+  const budgetWithheld = [];
+  const reviewFlags = /* @__PURE__ */ new Map();
+  const translation = await translateAndCheck(
     provider,
     params,
     entries,
     accepted,
     integrityMismatches,
-    providerFailures
+    providerFailures,
+    budgetWithheld,
+    reviewFlags
   );
   const merged = new Map(target.entries);
   for (const key of pruned) {
     merged.delete(key);
   }
-  for (const [key, { value, source }] of accepted) {
-    merged.set(key, { ...source, value, namespace: target.namespace });
+  for (const key of params.source.entries.keys()) {
+    const hit = accepted.get(key);
+    if (hit !== void 0) {
+      merged.set(key, { ...hit.source, value: hit.value, namespace: target.namespace });
+    }
   }
   const generation = await runGeneration(params, provider);
   for (const form of generation.accepted) {
@@ -3451,16 +4298,19 @@ async function runLocale(params) {
   const pluralNotices = params.generatePlurals ? pluralNoticeFor(params, merged) : sdkNotices;
   const notices = [
     ...pluralNotices,
-    ...subBatchNotices,
-    ...generation.notices
+    ...translation.notices,
+    ...generation.notices,
+    ...budgetLocaleNotices(params.budget, startedStopped, translation.tripped, generation.tripped)
   ];
   const withheld = /* @__PURE__ */ new Set([
     ...integrityMismatches,
     ...providerFailures,
     ...invalidIcuSource,
     ...generation.withheld,
-    ...generation.providerFailures
+    ...generation.providerFailures,
+    ...budgetWithheld
   ]);
+  const localeUsage = combineUsage(translation.usage, generation.usage);
   return {
     summary: baseSummary({
       locale: params.targetLocale,
@@ -3469,19 +4319,29 @@ async function runLocale(params) {
       invalidIcuSource,
       translated: [...accepted.keys()],
       generated: generation.accepted.map((form) => form.targetKey).sort(),
-      // Withheld generated forms surface alongside withheld translations: both failed integrity.
       integrityMismatches: [...integrityMismatches, ...generation.withheld].sort(),
-      // A generation sub-batch whose provider call itself threw is a provider failure, never integrity.
       providerFailures: [...providerFailures, ...generation.providerFailures].sort(),
+      budgetWithheld: [...budgetWithheld, ...generation.budgetWithheld].sort(),
       pruned,
-      notices
+      notices,
+      needsReview: needsReviewFor(accepted.keys(), reviewFlags),
+      ...localeUsage !== void 0 ? { usage: localeUsage } : {}
     }),
     lockEntries: computeLockEntries(params, merged, withheld, generation.accepted)
   };
 }
+var NO_GENERATION_RESULT = {
+  accepted: [],
+  withheld: [],
+  providerFailures: [],
+  budgetWithheld: [],
+  notices: [],
+  usage: void 0,
+  tripped: false
+};
 async function runGeneration(params, provider) {
   if (!params.generatePlurals || provider.kind !== "llm") {
-    return { accepted: [], withheld: [], providerFailures: [], notices: [] };
+    return NO_GENERATION_RESULT;
   }
   return generatePluralForms({
     source: params.source,
@@ -3493,9 +4353,13 @@ async function runGeneration(params, provider) {
     glossary: params.glossary,
     tone: params.tone,
     baseline: params.baseline,
-    maxBatchSize: params.maxBatchSize
+    maxBatchSize: params.maxBatchSize,
+    budget: params.budget
   });
 }
+function budgetLocaleNotices(budget, startedStopped, mainTripped, generationTripped) {
+  return startedStopped || mainTripped || generationTripped ? [budgetExceededNotice(budget)] : [];
+}
 function pluralNoticeFor(params, merged) {
   if (params.format !== "i18next-json") {
     return [];
@@ -3516,26 +4380,53 @@ function baseSummary(parts) {
     invalidIcuSource: parts.invalidIcuSource,
     integrityMismatches: parts.integrityMismatches,
     providerFailures: parts.providerFailures,
+    budgetWithheld: parts.budgetWithheld,
     generated: parts.generated,
-    notices: parts.notices
+    notices: parts.notices,
+    needsReview: parts.needsReview ?? [],
+    ...parts.usage !== void 0 ? { usage: parts.usage } : {}
   };
 }
-async function translateAndCheck(provider, params, entries, accepted, integrityMismatches, providerFailures) {
+function needsReviewFor(acceptedKeys, reviewFlags) {
+  const entries = [];
+  for (const key of acceptedKeys) {
+    const flag = reviewFlags.get(key);
+    if (flag !== void 0) {
+      entries.push({ key, reasons: flag.reasons });
+    }
+  }
+  return entries.sort((a, b) => a.key < b.key ? -1 : 1);
+}
+async function translateAndCheck(provider, params, entries, accepted, integrityMismatches, providerFailures, budgetWithheld, reviewFlags) {
   const notices = [];
+  const usage = createUsageAccumulator();
+  let tripped = false;
   for (const batch of chunk(entries, params.maxBatchSize)) {
-    const subNotices = await runSubBatch(
+    if (params.budget.stopped) {
+      for (const entry of batch) {
+        budgetWithheld.push(entry.key);
+      }
+      continue;
+    }
+    const subResult = await runSubBatch(
       provider,
       params,
       batch,
       accepted,
       integrityMismatches,
-      providerFailures
+      providerFailures,
+      reviewFlags
     );
-    notices.push(...subNotices);
+    notices.push(...subResult.notices);
+    foldUsage(usage, subResult.usage);
+    foldTrackerUsage(params.budget, subResult.usage);
+    if (checkBudgetTrip(params.budget)) {
+      tripped = true;
+    }
   }
-  return notices;
+  return { notices, tripped, usage: usage.total };
 }
-async function runSubBatch(provider, params, batch, accepted, integrityMismatches, providerFailures) {
+async function runSubBatch(provider, params, batch, accepted, integrityMismatches, providerFailures, reviewFlags) {
   let result;
   try {
     result = await provider.translateBatch(buildRequest3(params, batch));
@@ -3543,20 +4434,25 @@ async function runSubBatch(provider, params, batch, accepted, integrityMismatche
     for (const entry of batch) {
       providerFailures.push(entry.key);
     }
-    return [subBatchFailedNotice(batch.length, error)];
+    return { notices: [subBatchFailedNotice(batch.length, error)], usage: void 0 };
   }
   for (const entry of batch) {
-    foldEntryResult(entry, result, accepted, integrityMismatches, providerFailures);
+    foldEntryResult(entry, result, params.adapter, accepted, integrityMismatches, providerFailures);
+  }
+  if (result.reviewFlags !== void 0) {
+    for (const [key, flag] of result.reviewFlags) {
+      reviewFlags.set(key, flag);
+    }
   }
-  return readNotices(result);
+  return { notices: readNotices(result), usage: result.usage };
 }
-function foldEntryResult(entry, result, accepted, integrityMismatches, providerFailures) {
+function foldEntryResult(entry, result, adapter, accepted, integrityMismatches, providerFailures) {
   const value = result.values.get(entry.key);
   if (value === void 0) {
     providerFailures.push(entry.key);
     return;
   }
-  if (result.integrity.get(entry.key)?.matches === true) {
+  if (gateCandidateValue(entry, value, adapter).accepted) {
     accepted.set(entry.key, { value, source: entry });
   } else {
     integrityMismatches.push(entry.key);
@@ -3598,6 +4494,79 @@ function carryGeneratedLock(lockEntries, baseline, key, sourceBaseKeys) {
 }
 
 // src/flow/translate-project.ts
+async function recordRunStatus(cwd, dryRun, summary, fs) {
+  if (dryRun) {
+    return;
+  }
+  try {
+    await writeRunStatusFile(runStatusFilePath(cwd), buildRunStatusFile(summary), fs);
+  } catch {
+  }
+}
+function buildLocaleRunParams(context, targetLocale, baseline) {
+  return {
+    source: context.source.resource,
+    sourceInvalidIcuKeys: context.source.invalidIcuKeys,
+    baseline,
+    adapter: context.adapter,
+    provider: context.provider,
+    cwd: context.cwd,
+    filesPattern: context.config.files.pattern,
+    sourceLocale: context.config.sourceLocale,
+    targetLocale,
+    format: context.config.format,
+    glossary: context.config.glossary,
+    tone: context.config.tone,
+    prune: context.prune,
+    generatePlurals: context.generatePlurals,
+    maxBatchSize: context.maxBatchSize,
+    fs: context.fs,
+    budget: context.budget
+  };
+}
+async function runDryLocale(context, targetLocale, lock) {
+  const params = buildLocaleRunParams(context, targetLocale, baselineFor(lock, targetLocale));
+  return (await runLocale(params)).summary;
+}
+async function runLiveLocale(context, targetLocale) {
+  return withLocaleWriteLock(context.cwd, targetLocale, context.fs, async () => {
+    const lock = await readLockFile(lockFilePath(context.cwd), context.fs);
+    const params = buildLocaleRunParams(context, targetLocale, baselineFor(lock, targetLocale));
+    const result = await runLocale(params);
+    await updateLockFileLocale(context.cwd, context.fs, targetLocale, {
+      mode: "replace",
+      entries: result.lockEntries
+    });
+    return result.summary;
+  });
+}
+async function runOneLocale(targetLocale, run) {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof SdkError && error.code === "LOCK_FILE_INVALID") {
+      throw error;
+    }
+    return failureSummary(targetLocale, error);
+  }
+}
+async function runAllLocalesDry(context, targetLocales) {
+  const lock = await readLockFile(lockFilePath(context.cwd), context.fs);
+  const summaries = [];
+  for (const targetLocale of targetLocales) {
+    summaries.push(
+      await runOneLocale(targetLocale, () => runDryLocale(context, targetLocale, lock))
+    );
+  }
+  return summaries;
+}
+async function runAllLocalesLive(context, targetLocales) {
+  const summaries = [];
+  for (const targetLocale of targetLocales) {
+    summaries.push(await runOneLocale(targetLocale, () => runLiveLocale(context, targetLocale)));
+  }
+  return summaries;
+}
 async function translate2(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
@@ -3606,44 +4575,42 @@ async function translate2(input, deps = {}) {
   const generatePlurals = input.generatePlurals ?? config.generatePlurals ?? false;
   const maxBatchSize = config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
   const fs = deps.fs ?? defaultFs;
+  const budget = createBudgetTracker(
+    config.maxTokens,
+    config.budgetBehavior ?? DEFAULT_BUDGET_BEHAVIOR
+  );
   const adapter = selectAdapter(config.format, deps.adapterRegistry);
   const provider = dryRun ? void 0 : selectProvider(config.provider, deps.createProvider);
   const source = await readSource(config, cwd, fs, adapter);
-  const lockPath = lockFilePath(cwd);
-  let lock = await readLockFile(lockPath, fs);
-  const summaries = [];
-  for (const targetLocale of config.targetLocales) {
-    try {
-      const params = {
-        source: source.resource,
-        sourceInvalidIcuKeys: source.invalidIcuKeys,
-        baseline: baselineFor(lock, targetLocale),
-        adapter,
-        provider,
-        cwd,
-        filesPattern: config.files.pattern,
-        sourceLocale: config.sourceLocale,
-        targetLocale,
-        format: config.format,
-        glossary: config.glossary,
-        tone: config.tone,
-        prune,
-        generatePlurals,
-        maxBatchSize,
-        fs
-      };
-      const { summary, lockEntries } = await runLocale(params);
-      if (!dryRun) {
-        lock = updateLockLocale(lock, targetLocale, lockEntries);
-        await writeLockFile(lockPath, lock, fs);
-      }
-      summaries.push(summary);
-    } catch (error) {
-      summaries.push(failureSummary(targetLocale, error));
-    }
-  }
+  const context = {
+    source,
+    adapter,
+    provider,
+    cwd,
+    config,
+    prune,
+    generatePlurals,
+    maxBatchSize,
+    fs,
+    budget
+  };
+  const summaries = dryRun ? await runAllLocalesDry(context, config.targetLocales) : await runAllLocalesLive(context, config.targetLocales);
   const { succeeded, failed } = partition(summaries);
-  return { dryRun, locales: summaries, succeeded, failed };
+  const usage = summaries.reduce(
+    (total, summary2) => combineUsage(total, summary2.usage),
+    void 0
+  );
+  const budgetSummary = toBudgetSummary(budget);
+  const summary = {
+    dryRun,
+    locales: summaries,
+    succeeded,
+    failed,
+    ...usage !== void 0 ? { usage } : {},
+    ...budgetSummary !== void 0 ? { budget: budgetSummary } : {}
+  };
+  await recordRunStatus(cwd, dryRun, summary, fs);
+  return summary;
 }
 var ExchangeError = class extends Error {
   code;
@@ -3684,7 +4651,9 @@ var COLUMN = {
   status: 4,
   translation: 5,
   sourceHash: 6,
-  context: 7
+  context: 7,
+  reviewStatus: 8,
+  reviewReasons: 9
 };
 var HEADERS = [
   "Key",
@@ -3693,7 +4662,9 @@ var HEADERS = [
   "Status",
   "Translation",
   "Source hash",
-  "Context"
+  "Context",
+  "Review status",
+  "Review reasons"
 ];
 var HEADER_ROW = 1;
 var INSTRUCTIONS_SHEET_NAME = "Instructions";
@@ -3713,7 +4684,9 @@ var COLUMN_WIDTHS = {
   [COLUMN.current]: 50,
   [COLUMN.status]: 12,
   [COLUMN.translation]: 50,
-  [COLUMN.context]: 50
+  [COLUMN.context]: 50,
+  [COLUMN.reviewStatus]: 12,
+  [COLUMN.reviewReasons]: 40
 };
 var TEXT_NUMBER_FORMAT = "@";
 function styleHeader(sheet) {
@@ -3745,7 +4718,9 @@ function writeRow(sheet, sheetRow) {
   translationCell.value = sheetRow.translation === "" ? null : sheetRow.translation;
   row.getCell(COLUMN.sourceHash).value = sheetRow.sourceHash;
   row.getCell(COLUMN.context).value = sheetRow.context;
-  for (let column = COLUMN.key; column <= COLUMN.context; column += 1) {
+  row.getCell(COLUMN.reviewStatus).value = sheetRow.reviewStatus;
+  row.getCell(COLUMN.reviewReasons).value = sheetRow.reviewReasons;
+  for (let column = COLUMN.key; column <= COLUMN.reviewReasons; column += 1) {
     const cell = row.getCell(column);
     cell.protection = { locked: column !== COLUMN.translation };
     if (column !== COLUMN.translation) {
@@ -3920,7 +4895,9 @@ var rowSchema = z.object({
   status: z.enum(["new", "changed", "unchanged"]),
   sourceHash: z.string(),
   translation: z.string(),
-  context: z.string()
+  context: z.string(),
+  reviewStatus: z.enum(["ok", "review"]).catch("ok"),
+  reviewReasons: z.string().catch("")
 });
 function cellString(cell) {
   const value = cell.value;
@@ -3954,9 +4931,9 @@ function parseRow(sheet, row) {
     status: cellString(row.getCell(COLUMN.status)),
     sourceHash: cellString(row.getCell(COLUMN.sourceHash)),
     translation: cellString(row.getCell(COLUMN.translation)),
-    // A workbook built before the Context column existed has no cell here; getCell auto-vivifies an
-    // empty one, so cellString yields "" and the row still validates, keeping import backward-compatible.
-    context: cellString(row.getCell(COLUMN.context))
+    context: cellString(row.getCell(COLUMN.context)),
+    reviewStatus: cellString(row.getCell(COLUMN.reviewStatus)),
+    reviewReasons: cellString(row.getCell(COLUMN.reviewReasons))
   };
   const result = rowSchema.safeParse(candidate);
   if (!result.success) {
@@ -4023,14 +5000,34 @@ async function readWorkbook(bytes, options = {}) {
 
 // src/flow/workbook/export-workbook.ts
 var DEFAULT_WORKBOOK_PATH = "verbatra-translations.xlsx";
-async function readTarget3(cwd, config, adapter, fs, locale) {
-  const path = localeFilePath(cwd, config.files.pattern, locale);
-  if (!await fs.fileExists(path)) {
-    return { locale, namespace: "", format: config.format, entries: /* @__PURE__ */ new Map() };
+function reasonLabel(reason) {
+  return reason.toLowerCase().replace(/_/g, "-");
+}
+function reviewColumns(flag) {
+  if (flag === void 0) {
+    return { reviewStatus: "ok", reviewReasons: "" };
   }
-  return (await adapter.read(path, locale)).resource;
+  return { reviewStatus: "review", reviewReasons: flag.reasons.map(reasonLabel).join(", ") };
 }
-function buildRows(source, target, baseline, includeUnchanged) {
+function computeRowReview(adapter, sourceValue, currentTarget, sourceLocale, targetLocale, glossary) {
+  if (currentTarget === "") {
+    return { reviewStatus: "ok", reviewReasons: "" };
+  }
+  const integrity = adapter.comparePlaceholders?.(sourceValue, currentTarget) ?? checkPlaceholders(
+    adapter.extractPlaceholders(sourceValue),
+    adapter.extractPlaceholders(currentTarget)
+  );
+  const flag = computeReviewFlags({
+    sourceValue,
+    translatedValue: currentTarget,
+    sourceLocale,
+    targetLocale,
+    integrity,
+    glossary
+  });
+  return reviewColumns(flag);
+}
+function buildRows(source, target, baseline, includeUnchanged, adapter, glossary) {
   const diff2 = diffResources(source, target, { baseline });
   const rows = [];
   const add = (keys, status) => {
@@ -4039,14 +5036,23 @@ function buildRows(source, target, baseline, includeUnchanged) {
       if (sourceEntry === void 0) {
         continue;
       }
+      const currentTarget = target.entries.get(key)?.value ?? "";
       rows.push({
         key,
         source: sourceEntry.value,
-        currentTarget: target.entries.get(key)?.value ?? "",
+        currentTarget,
         status,
         sourceHash: contentHash(sourceEntry),
         translation: "",
-        context: sourceEntry.description ?? ""
+        context: sourceEntry.description ?? "",
+        ...computeRowReview(
+          adapter,
+          sourceEntry.value,
+          currentTarget,
+          source.locale,
+          target.locale,
+          glossary
+        )
       });
     }
   };
@@ -4067,12 +5073,14 @@ async function exportWorkbook(input, deps = {}) {
   const locales = selectLocales(config, input.locales);
   const sheets = await Promise.all(
     locales.map(async (locale) => {
-      const target = await readTarget3(cwd, config, adapter, fs, locale);
+      const target = await readTarget(cwd, config, adapter, fs, locale);
       const rows = buildRows(
         source.resource,
         target,
         baselineFor(lock, locale),
-        input.includeUnchanged ?? false
+        input.includeUnchanged ?? false,
+        adapter,
+        config.glossary
       );
       return { locale, rows };
     })
@@ -4103,14 +5111,8 @@ function judge(row, sourceEntry, adapter) {
   if (contentHash(sourceEntry) !== row.sourceHash) {
     return "drift";
   }
-  const integrity = adapter.comparePlaceholders !== void 0 ? adapter.comparePlaceholders(sourceEntry.value, row.translation) : checkPlaceholders(sourceEntry.placeholders, adapter.extractPlaceholders(row.translation));
-  if (!integrity.matches) {
-    return "placeholder";
-  }
-  if (!adapter.validateMessage(row.translation)) {
-    return "icu";
-  }
-  return void 0;
+  const gate = gateCandidateValue(sourceEntry, row.translation, adapter);
+  return gate.accepted ? void 0 : gate.reason;
 }
 function trackBlankDrift(row, params, buckets) {
   const sourceEntry = params.source.entries.get(row.key);
@@ -4167,15 +5169,14 @@ function importLocale(params) {
     translated: [...buckets.accepted.keys()].sort(),
     unchanged: diff2.unchanged,
     orphaned: diff2.orphaned,
-    // Import never prunes: orphans are reported but never removed here (pruning is a translate-flow concern).
     pruned: [],
     invalidIcuSource,
     integrityMismatches: [...buckets.mismatches].sort(),
-    // A workbook import never calls a provider, so a provider-call failure cannot occur here.
     providerFailures: [],
-    // Plural generation is a translate-flow concern; the manual workbook import never generates forms.
+    budgetWithheld: [],
     generated: [],
-    notices: buckets.blankDrifted.size > 0 ? [blankRowBaselineNotice(buckets.blankDrifted.size)] : []
+    notices: buckets.blankDrifted.size > 0 ? [blankRowBaselineNotice(buckets.blankDrifted.size)] : [],
+    needsReview: []
   };
   return { summary, accepted: buckets.accepted, withheld: buckets.withheld };
 }
@@ -4195,13 +5196,6 @@ async function readWorkbookBytes(path, fs) {
   }
   return read.bytes;
 }
-async function readTarget4(cwd, config, adapter, fs, locale) {
-  const path = localeFilePath(cwd, config.files.pattern, locale);
-  if (!await fs.fileExists(path)) {
-    return { locale, namespace: "", format: config.format, entries: /* @__PURE__ */ new Map() };
-  }
-  return (await adapter.read(path, locale)).resource;
-}
 function mergeAccepted(target, accepted) {
   const merged = new Map(target.entries);
   for (const [key, { value, source }] of accepted) {
@@ -4232,7 +5226,7 @@ async function runSheet(ctx, sheet, lock) {
       `The workbook has a sheet for locale "${sheet.locale}", which is not a configured target locale.`
     );
   }
-  const target = await readTarget4(ctx.cwd, ctx.config, ctx.adapter, ctx.fs, sheet.locale);
+  const target = await readTarget(ctx.cwd, ctx.config, ctx.adapter, ctx.fs, sheet.locale);
   const baseline = baselineFor(lock, sheet.locale);
   const { summary, accepted } = importLocale({
     sheet,
@@ -4275,8 +5269,7 @@ async function importWorkbook(input, deps = {}) {
   } catch (error) {
     throw new SdkError("SOURCE_INVALID", error.message);
   }
-  const lockPath = lockFilePath(cwd);
-  let lock = await readLockFile(lockPath, fs);
+  const lock = await readLockFile(lockFilePath(cwd), fs);
   const ctx = {
     config,
     cwd,
@@ -4289,10 +5282,18 @@ async function importWorkbook(input, deps = {}) {
   const summaries = [];
   for (const sheet of data.sheets) {
     try {
-      const { summary, lockEntries } = await runSheet(ctx, sheet, lock);
-      if (!dryRun) {
-        lock = updateLockLocale(lock, sheet.locale, lockEntries);
-        await writeLockFile(lockPath, lock, fs);
+      let summary;
+      if (dryRun) {
+        summary = (await runSheet(ctx, sheet, lock)).summary;
+      } else {
+        summary = await withLocaleWriteLock(cwd, sheet.locale, fs, async () => {
+          const result = await runSheet(ctx, sheet, lock);
+          await updateLockFileLocale(cwd, fs, sheet.locale, {
+            mode: "replace",
+            entries: result.lockEntries
+          });
+          return result.summary;
+        });
       }
       summaries.push(summary);
     } catch (error) {
@@ -4425,6 +5426,6 @@ async function watch(input, deps = {}) {
   return { stop };
 }
 
-export { DEFAULT_WORKBOOK_PATH, LOCK_FILE_NAME, SdkError, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate2 as translate, verbatraConfigSchema, watch };
+export { DEFAULT_WORKBOOK_PATH, LOCK_FILE_NAME, SdkError, check, defineConfig, diff, diffLocaleSnapshots, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate2 as translate, verbatraConfigSchema, watch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map