@verbatra/sdk 0.5.0-next.4 → 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.
    */
@@ -981,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)
   };
@@ -1095,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 });
   });
@@ -1150,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"
 ]);
@@ -1723,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: {} };
@@ -1734,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;
   }
@@ -1763,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] ?? {}));
 }
@@ -1778,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 };
@@ -2047,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.number(), z.boolean(), z.null(), 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) {
@@ -2058,44 +2197,117 @@ 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, number, boolean, or null leaves)."
-    );
+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 typeof value === "object" && value !== null;
+  return value instanceof Map;
 }
 function namespaceOf(filePath) {
   return basename(filePath, extname(filePath));
@@ -2297,7 +2509,7 @@ function addLeaf(ctx, segments, 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 (isJsonNode(value)) {
       addEntries(ctx, segments, value);
@@ -2307,7 +2519,7 @@ function addEntries(ctx, prefix, node) {
   }
 }
 function addPathEntries(node, prefix, namespace, derive, out, claimedPaths, excluded) {
-  for (const [key, value] of Object.entries(node)) {
+  for (const [key, value] of node) {
     const path = prefix === "" ? key : `${prefix}.${key}`;
     if (claimedPaths.has(path)) {
       throw new AdapterError(
@@ -2337,17 +2549,14 @@ function flattenTree(tree, namespace, derive, keyMode = "literal-leaf") {
   addEntries(ctx, [], tree);
   return { entries: out, excludedLeafPaths: ctx.excluded };
 }
-function emptyNode() {
-  return /* @__PURE__ */ Object.create(null);
-}
 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.");
@@ -2361,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);
   }
@@ -2444,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)."
@@ -2459,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;
@@ -2474,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;
@@ -2515,25 +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[key] = translated;
+      out.set(key, translated);
     } else if (isMetadataKey(key) || typeof value === "string") {
-      out[key] = value;
+      out.set(key, value);
     }
   }
   for (const [key, value] of messages) {
     if (!consumed.has(key)) {
-      out[key] = value;
+      out.set(key, value);
     }
   }
   return out;
@@ -2622,7 +2826,7 @@ function createNextIntlJsonAdapter() {
   });
 }
 function assertNoDottedNestedKey(tree) {
-  for (const [key, value] of Object.entries(tree)) {
+  for (const [key, value] of tree) {
     if (!isJsonNode(value)) {
       continue;
     }
@@ -2638,7 +2842,7 @@ function assertNoDottedNestedKey(tree) {
 function assertNotMixed(tree) {
   let hasNested = false;
   let hasFlatDottedKey = false;
-  for (const [key, value] of Object.entries(tree)) {
+  for (const [key, value] of tree) {
     if (isJsonNode(value)) {
       hasNested = true;
     } else if (key.includes(".")) {
@@ -2675,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;
 }
@@ -2695,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"
   });
 }
@@ -2721,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];
@@ -3075,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({
@@ -3113,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) {
@@ -3153,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;
@@ -3207,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 {
@@ -3254,6 +3654,174 @@ 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 };
@@ -3536,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}"`
   };
 }
@@ -3613,17 +4180,17 @@ async function runGenerationSubBatch(context, batch, accepted, withheld, provide
     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 { 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 },
@@ -3635,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,
@@ -3657,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 : [];
@@ -3711,8 +4275,11 @@ async function runLocale(params) {
   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) {
@@ -3741,7 +4308,6 @@ async function runLocale(params) {
     ...invalidIcuSource,
     ...generation.withheld,
     ...generation.providerFailures,
-    // Source-present keys withheld by the budget guardrail must keep their prior lock hash too.
     ...budgetWithheld
   ]);
   const localeUsage = combineUsage(translation.usage, generation.usage);
@@ -3753,9 +4319,7 @@ 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,
@@ -3873,7 +4437,7 @@ async function runSubBatch(provider, params, batch, accepted, integrityMismatche
     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) {
@@ -3882,13 +4446,13 @@ async function runSubBatch(provider, params, batch, accepted, integrityMismatche
   }
   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);
@@ -3930,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();
@@ -3945,47 +4582,26 @@ async function translate2(input, deps = {}) {
   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,
-        budget
-      };
-      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);
   const usage = summaries.reduce(
-    (total, summary) => combineUsage(total, summary.usage),
+    (total, summary2) => combineUsage(total, summary2.usage),
     void 0
   );
   const budgetSummary = toBudgetSummary(budget);
-  return {
+  const summary = {
     dryRun,
     locales: summaries,
     succeeded,
@@ -3993,6 +4609,8 @@ async function translate2(input, deps = {}) {
     ...usage !== void 0 ? { usage } : {},
     ...budgetSummary !== void 0 ? { budget: budgetSummary } : {}
   };
+  await recordRunStatus(cwd, dryRun, summary, fs);
+  return summary;
 }
 var ExchangeError = class extends Error {
   code;
@@ -4278,8 +4896,6 @@ var rowSchema = z.object({
   sourceHash: z.string(),
   translation: z.string(),
   context: z.string(),
-  // A legacy workbook exported before these columns existed has no such cell; cellString then yields
-  // "", and .catch maps it to "ok" / "" rather than rejecting the row.
   reviewStatus: z.enum(["ok", "review"]).catch("ok"),
   reviewReasons: z.string().catch("")
 });
@@ -4315,10 +4931,7 @@ 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)),
-    // Same backward-compatible pattern for a workbook built before the Review columns existed.
     reviewStatus: cellString(row.getCell(COLUMN.reviewStatus)),
     reviewReasons: cellString(row.getCell(COLUMN.reviewReasons))
   };
@@ -4387,13 +5000,6 @@ 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() };
-  }
-  return (await adapter.read(path, locale)).resource;
-}
 function reasonLabel(reason) {
   return reason.toLowerCase().replace(/_/g, "-");
 }
@@ -4467,7 +5073,7 @@ 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,
@@ -4505,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);
@@ -4569,19 +5169,13 @@ 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: [],
-    // A workbook import never calls a provider, so the budget guardrail never withholds anything here.
     budgetWithheld: [],
-    // Plural generation is a translate-flow concern; the manual workbook import never generates forms.
     generated: [],
     notices: buckets.blankDrifted.size > 0 ? [blankRowBaselineNotice(buckets.blankDrifted.size)] : [],
-    // A workbook import never calls a provider and never recomputes review flags on its own path; the
-    // Excel workbook's Review status/reasons columns are informational only (see export-workbook.ts).
     needsReview: []
   };
   return { summary, accepted: buckets.accepted, withheld: buckets.withheld };
@@ -4602,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) {
@@ -4639,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,
@@ -4682,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,
@@ -4696,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) {
@@ -4832,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