@verbatra/sdk 0.4.3 → 0.5.0-next.0

package/dist/index.cjs

@@ -4,6 +4,8 @@ var fs = require('fs');
 var path = require('path');
 var cosmiconfig = require('cosmiconfig');
 var cosmiconfigTypescriptLoader = require('cosmiconfig-typescript-loader');
+var crypto = require('crypto');
+var promises = require('fs/promises');
 var zod = require('zod');
 var Anthropic = require('@anthropic-ai/sdk');
 var deepl = require('deepl-node');
@@ -11,8 +13,6 @@ var module$1 = require('module');
 var log = require('loglevel');
 var genai = require('@google/genai');
 var OpenAI = require('openai');
-var crypto = require('crypto');
-var promises = require('fs/promises');
 var icuMessageformatParser = require('@formatjs/icu-messageformat-parser');
 var xmldom = require('@xmldom/xmldom');
 var yaml = require('yaml');
@@ -68,6 +68,155 @@ var SdkError = class extends Error {
     this.code = code;
   }
 };
+async function readBoundedUtf8(handle, size) {
+  const buffer = Buffer.allocUnsafe(size);
+  let offset = 0;
+  while (offset < size) {
+    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+    if (bytesRead === 0) {
+      break;
+    }
+    offset += bytesRead;
+  }
+  return buffer.toString("utf8", 0, offset);
+}
+async function readBounded(path, maxBytes) {
+  let handle;
+  try {
+    handle = await promises.open(path, "r");
+  } catch {
+    return { kind: "missing" };
+  }
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) {
+      return { kind: "missing" };
+    }
+    if (info.size > maxBytes) {
+      return { kind: "too-large" };
+    }
+    return { kind: "ok", content: await readBoundedUtf8(handle, info.size) };
+  } finally {
+    await handle.close();
+  }
+}
+async function readBoundedBytesInto(handle, size) {
+  const buffer = Buffer.allocUnsafeSlow(size);
+  let offset = 0;
+  while (offset < size) {
+    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+    if (bytesRead === 0) {
+      break;
+    }
+    offset += bytesRead;
+  }
+  return new Uint8Array(buffer.buffer, buffer.byteOffset, offset);
+}
+async function readBoundedBytes(path, maxBytes) {
+  let handle;
+  try {
+    handle = await promises.open(path, "r");
+  } catch {
+    return { kind: "missing" };
+  }
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) {
+      return { kind: "missing" };
+    }
+    if (info.size > maxBytes) {
+      return { kind: "too-large" };
+    }
+    return { kind: "ok", bytes: await readBoundedBytesInto(handle, info.size) };
+  } finally {
+    await handle.close();
+  }
+}
+function tempFileName(path$1) {
+  return path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`);
+}
+async function atomicWrite(path, data) {
+  const tmp = tempFileName(path);
+  await (typeof data === "string" ? promises.writeFile(tmp, data, "utf8") : promises.writeFile(tmp, data));
+  try {
+    await promises.rename(tmp, path);
+  } catch (error) {
+    await promises.rm(tmp, { force: true });
+    throw error;
+  }
+}
+var defaultFs = {
+  async fileExists(path) {
+    try {
+      await promises.access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  readFileBounded: (path, maxBytes) => readBounded(path, maxBytes),
+  readBytesBounded: (path, maxBytes) => readBoundedBytes(path, maxBytes),
+  writeFile: (path, data) => atomicWrite(path, data),
+  writeBytes: (path, data) => atomicWrite(path, data)
+};
+var MAX_GLOSSARY_FILE_BYTES = 1024 * 1024;
+var glossaryRecordSchema = zod.z.record(zod.z.string(), zod.z.string());
+var BOM = "\uFEFF";
+var REPLACEMENT_CHARACTER = "\uFFFD";
+var NUL = "\0";
+function stripBom(content) {
+  return content.startsWith(BOM) ? content.slice(BOM.length) : content;
+}
+function looksLikeInvalidEncoding(content) {
+  return content.startsWith(REPLACEMENT_CHARACTER) || content.includes(NUL);
+}
+async function readGlossaryFile(resolvedPath, fs) {
+  const read = await fs.readFileBounded(resolvedPath, MAX_GLOSSARY_FILE_BYTES);
+  if (read.kind === "missing") {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The glossary file at ${resolvedPath} was not found or could not be read.`
+    );
+  }
+  if (read.kind === "too-large") {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The glossary file at ${resolvedPath} exceeds the maximum allowed size of ${MAX_GLOSSARY_FILE_BYTES} bytes.`
+    );
+  }
+  const content = stripBom(read.content);
+  if (looksLikeInvalidEncoding(content)) {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The glossary file at ${resolvedPath} must be UTF-8 encoded.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new SdkError("CONFIG_INVALID", `The glossary file at ${resolvedPath} is not valid JSON.`);
+  }
+  const result = glossaryRecordSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The glossary file at ${resolvedPath} must contain a flat object of string keys to string values.`
+    );
+  }
+  return result.data;
+}
+async function resolveGlossary(glossary, baseDir, fs) {
+  if (glossary === void 0) {
+    return { glossary: void 0, provenance: { source: "none" } };
+  }
+  if (typeof glossary === "string") {
+    const resolvedPath = path.resolve(baseDir, glossary);
+    const record = await readGlossaryFile(resolvedPath, fs);
+    return { glossary: record, provenance: { source: "file", path: resolvedPath } };
+  }
+  return { glossary, provenance: { source: "inline" } };
+}
 var FNV_OFFSET_BASIS = 14695981039346656037n;
 var FNV_PRIME = 1099511628211n;
 var U64_MASK = (1n << 64n) - 1n;
@@ -903,7 +1052,13 @@ var verbatraConfigSchema = zod.z.strictObject({
     pattern: zod.z.string().min(1)
   }),
   provider: providerConfigSchema,
-  glossary: zod.z.record(zod.z.string(), zod.z.string()).optional(),
+  /**
+   * A glossary of source terms to preferred target terms, either inline or as a path to a JSON file
+   * carrying the same shape. The two forms are mutually exclusive by type; there is no merge or
+   * precedence between them. A path is resolved and validated by the loader, not by this schema; see
+   * `resolve-glossary.ts`.
+   */
+  glossary: zod.z.union([zod.z.record(zod.z.string(), zod.z.string()), zod.z.string().min(1)]).optional(),
   tone: zod.z.enum(["formal", "informal", "neutral"]).optional(),
   /**
    * Opt-in orphan pruning, off by default. When true, keys present in a target file but absent from
@@ -957,7 +1112,7 @@ function formatIssues(error) {
     return issue.code === "unrecognized_keys" ? `${base} (API keys are read from the environment, not the config)` : base;
   }).join("; ");
 }
-function validate(input) {
+function parseConfig(input) {
   const parsed = verbatraConfigSchema.safeParse(input);
   if (!parsed.success) {
     throw new SdkError(
@@ -967,7 +1122,16 @@ function validate(input) {
   }
   return parsed.data;
 }
-async function loadExplicit(explorer, configPath, cwd) {
+async function finalizeConfig(parsed, baseDir, fs) {
+  const { glossary: glossaryInput, ...rest } = parsed;
+  const resolved = await resolveGlossary(glossaryInput, baseDir, fs);
+  const config = {
+    ...rest,
+    ...resolved.glossary !== void 0 ? { glossary: resolved.glossary } : {}
+  };
+  return { config, glossary: resolved.provenance };
+}
+async function loadExplicitWithMeta(explorer, configPath, cwd, fs$1) {
   const resolved = path.resolve(cwd ?? process.cwd(), configPath);
   if (!fs.existsSync(resolved)) {
     throw new SdkError("CONFIG_NOT_FOUND", `No verbatra configuration file at ${resolved}.`);
@@ -979,18 +1143,23 @@ async function loadExplicit(explorer, configPath, cwd) {
     const detail = error instanceof Error ? error.message : String(error);
     throw new SdkError("CONFIG_INVALID", `Failed to load the verbatra configuration: ${detail}`);
   }
-  return validate(result?.config);
+  const parsed = parseConfig(result?.config);
+  const { config, glossary } = await finalizeConfig(parsed, path.dirname(resolved), fs$1);
+  return { config, source: { kind: "explicit", filepath: resolved }, glossary };
 }
-async function loadConfig(options = {}) {
+async function loadConfigWithMeta(options = {}) {
+  const fs = options.fs ?? defaultFs;
   if (options.configOverride !== void 0) {
-    return validate(options.configOverride);
+    const parsed2 = parseConfig(options.configOverride);
+    const { config: config2, glossary: glossary2 } = await finalizeConfig(parsed2, options.cwd ?? process.cwd(), fs);
+    return { config: config2, source: { kind: "override" }, glossary: glossary2 };
   }
   const explorer = cosmiconfig.cosmiconfig(MODULE_NAME, {
     searchPlaces: SEARCH_PLACES,
     loaders: { ".ts": cosmiconfigTypescriptLoader.TypeScriptLoader() }
   });
   if (options.configPath !== void 0) {
-    return loadExplicit(explorer, options.configPath, options.cwd);
+    return loadExplicitWithMeta(explorer, options.configPath, options.cwd, fs);
   }
   let result;
   try {
@@ -1005,99 +1174,14 @@ async function loadConfig(options = {}) {
       "No verbatra configuration found. Create a verbatra.config.ts, a .verbatrarc.json, or a 'verbatra' property in package.json."
     );
   }
-  return validate(result.config);
-}
-async function readBoundedUtf8(handle, size) {
-  const buffer = Buffer.allocUnsafe(size);
-  let offset = 0;
-  while (offset < size) {
-    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
-    if (bytesRead === 0) {
-      break;
-    }
-    offset += bytesRead;
-  }
-  return buffer.toString("utf8", 0, offset);
-}
-async function readBounded(path, maxBytes) {
-  let handle;
-  try {
-    handle = await promises.open(path, "r");
-  } catch {
-    return { kind: "missing" };
-  }
-  try {
-    const info = await handle.stat();
-    if (!info.isFile()) {
-      return { kind: "missing" };
-    }
-    if (info.size > maxBytes) {
-      return { kind: "too-large" };
-    }
-    return { kind: "ok", content: await readBoundedUtf8(handle, info.size) };
-  } finally {
-    await handle.close();
-  }
-}
-async function readBoundedBytesInto(handle, size) {
-  const buffer = Buffer.allocUnsafeSlow(size);
-  let offset = 0;
-  while (offset < size) {
-    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
-    if (bytesRead === 0) {
-      break;
-    }
-    offset += bytesRead;
-  }
-  return new Uint8Array(buffer.buffer, buffer.byteOffset, offset);
-}
-async function readBoundedBytes(path, maxBytes) {
-  let handle;
-  try {
-    handle = await promises.open(path, "r");
-  } catch {
-    return { kind: "missing" };
-  }
-  try {
-    const info = await handle.stat();
-    if (!info.isFile()) {
-      return { kind: "missing" };
-    }
-    if (info.size > maxBytes) {
-      return { kind: "too-large" };
-    }
-    return { kind: "ok", bytes: await readBoundedBytesInto(handle, info.size) };
-  } finally {
-    await handle.close();
-  }
-}
-function tempFileName(path$1) {
-  return path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`);
+  const parsed = parseConfig(result.config);
+  const { config, glossary } = await finalizeConfig(parsed, path.dirname(result.filepath), fs);
+  return { config, source: { kind: "search", filepath: result.filepath }, glossary };
 }
-async function atomicWrite(path, data) {
-  const tmp = tempFileName(path);
-  await (typeof data === "string" ? promises.writeFile(tmp, data, "utf8") : promises.writeFile(tmp, data));
-  try {
-    await promises.rename(tmp, path);
-  } catch (error) {
-    await promises.rm(tmp, { force: true });
-    throw error;
-  }
+async function loadConfig(options = {}) {
+  const { config } = await loadConfigWithMeta(options);
+  return config;
 }
-var defaultFs = {
-  async fileExists(path) {
-    try {
-      await promises.access(path);
-      return true;
-    } catch {
-      return false;
-    }
-  },
-  readFileBounded: (path, maxBytes) => readBounded(path, maxBytes),
-  readBytesBounded: (path, maxBytes) => readBoundedBytes(path, maxBytes),
-  writeFile: (path, data) => atomicWrite(path, data),
-  writeBytes: (path, data) => atomicWrite(path, data)
-};
 var LOCK_FILE_NAME = "verbatra.lock.json";
 var CURRENT_VERSION = 1;
 var EMPTY_LOCK = { version: CURRENT_VERSION, locales: {} };
@@ -1182,19 +1266,53 @@ function childMessages(element) {
   }
   return [];
 }
-function collect(elements, add, state) {
+function addCount(target, token, count) {
+  target.set(token, (target.get(token) ?? 0) + count);
+}
+function combineBranches(branchMultisets) {
+  const combined = /* @__PURE__ */ new Map();
+  const tokens = /* @__PURE__ */ new Set();
+  for (const branch of branchMultisets) {
+    for (const token of branch.keys()) {
+      tokens.add(token);
+    }
+  }
+  for (const token of tokens) {
+    const minCount = Math.min(...branchMultisets.map((branch) => branch.get(token) ?? 0));
+    if (minCount > 0) {
+      combined.set(token, minCount);
+    }
+  }
+  return combined;
+}
+function collect(elements, state) {
+  const result = /* @__PURE__ */ new Map();
   for (const element of elements) {
     const token = tokenOf(element);
     if (token !== void 0) {
-      add(token);
+      addCount(result, token, 1);
     }
     if (element.type === icuMessageformatParser.TYPE.plural) {
       state.isPlural = true;
     }
-    for (const child of childMessages(element)) {
-      collect(child, add, state);
+    const branches = childMessages(element);
+    if (branches.length > 0) {
+      const branchMultisets = branches.map((branch) => collect(branch, state));
+      for (const [branchToken, branchCount] of combineBranches(branchMultisets)) {
+        addCount(result, branchToken, branchCount);
+      }
+    }
+  }
+  return result;
+}
+function flatten(multiset) {
+  const flattened = [];
+  for (const [token, count] of multiset) {
+    for (let i = 0; i < count; i += 1) {
+      flattened.push(token);
     }
   }
+  return flattened;
 }
 function analyzeIcuValue(value) {
   if (!value.includes("{") && !value.includes("<")) {
@@ -1202,16 +1320,9 @@ function analyzeIcuValue(value) {
   }
   try {
     const ast = icuMessageformatParser.parse(value);
-    const placeholders = [];
     const state = { isPlural: false };
-    collect(
-      ast,
-      (token) => {
-        placeholders.push(token);
-      },
-      state
-    );
-    return { placeholders, isPlural: state.isPlural, valid: true };
+    const multiset = collect(ast, state);
+    return { placeholders: flatten(multiset), isPlural: state.isPlural, valid: true };
   } catch {
     return INVALID;
   }
@@ -1473,21 +1584,28 @@ function addEntries(ctx, prefix, node) {
     }
   }
 }
-function addPathEntries(node, prefix, namespace, derive, out) {
+function addPathEntries(node, prefix, namespace, derive, out, claimedPaths) {
   for (const [key, value] of Object.entries(node)) {
     const path = prefix === "" ? key : `${prefix}.${key}`;
+    if (claimedPaths.has(path)) {
+      throw new AdapterError(
+        "INVALID_STRUCTURE",
+        "A dotted key and a nested key path resolve to the same path."
+      );
+    }
+    claimedPaths.add(path);
     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);
+      addPathEntries(value, path, namespace, derive, out, claimedPaths);
     }
   }
 }
 function flattenTree(tree, namespace, derive, keyMode = "literal-leaf") {
   const out = /* @__PURE__ */ new Map();
   if (keyMode === "path-notation") {
-    addPathEntries(tree, "", namespace, derive, out);
+    addPathEntries(tree, "", namespace, derive, out, /* @__PURE__ */ new Set());
     return out;
   }
   addEntries({ namespace, derive, out, claimed: /* @__PURE__ */ new Map() }, [], tree);
@@ -1609,21 +1727,20 @@ function messagesFromEntries(entries) {
   }
   return out;
 }
+function isEnoent(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
 async function readDestinationPairs(filePath) {
-  let parsed;
+  let content;
   try {
-    const outcome = await readBounded2(filePath);
-    if (outcome.kind !== "ok") {
+    content = await readFileContent(filePath);
+  } catch (error) {
+    if (isEnoent(error)) {
       return null;
     }
-    parsed = JSON.parse(outcome.content);
-  } catch {
-    return null;
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    return null;
+    throw error;
   }
-  return Object.entries(parsed);
+  return Object.entries(parseArbObject(content));
 }
 async function buildArbWriteTree(entries, filePath) {
   const messages = messagesFromEntries(entries);
@@ -1724,6 +1841,20 @@ function createNextIntlJsonAdapter() {
     validateMessage: icuIsValid
   });
 }
+function assertNoDottedNestedKey(tree) {
+  for (const [key, value] of Object.entries(tree)) {
+    if (typeof value !== "object") {
+      continue;
+    }
+    if (key.includes(".")) {
+      throw new AdapterError(
+        "MIXED_STRUCTURE",
+        "A nested object key contains a literal dot, which is ambiguous with a dotted path."
+      );
+    }
+    assertNoDottedNestedKey(value);
+  }
+}
 function assertNotMixed(tree) {
   let hasNested = false;
   let hasFlatDottedKey = false;
@@ -1740,6 +1871,7 @@ function assertNotMixed(tree) {
       "The file mixes flat dotted keys with nested objects."
     );
   }
+  assertNoDottedNestedKey(tree);
 }
 async function detectStyle(filePath) {
   let parsed;
@@ -2206,6 +2338,40 @@ async function diff(input, deps = {}) {
   return { hasPendingChanges: locales.some((entry) => entry.hasPendingChanges), locales };
 }
 
+// src/flow/lock-state.ts
+function toLockLocaleState(locale, keyCount, diff2) {
+  return {
+    locale,
+    keyCount,
+    missing: diff2.missing.length,
+    stale: diff2.changed.length,
+    upToDate: diff2.unchanged.length
+  };
+}
+async function lockState(input, deps = {}) {
+  const config = input.config;
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const locales = selectLocales(config, input.locales);
+  const path = lockFilePath(cwd);
+  const exists = await fs.fileExists(path);
+  if (!exists) {
+    return { exists: false };
+  }
+  const lock = await readLockFile(path, fs);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const source = await readSource(config, cwd, fs, adapter);
+  const localeStates = await Promise.all(
+    locales.map(async (locale) => {
+      const target = await readTarget(cwd, config, adapter, fs, locale);
+      const baseline = baselineFor(lock, locale);
+      const diff2 = diffResources(source.resource, target, { baseline });
+      return toLockLocaleState(locale, baseline.size, diff2);
+    })
+  );
+  return { exists: true, version: lock.version, locales: localeStates };
+}
+
 // src/selection/select-provider.ts
 function selectProvider(config, createProvider = buildProvider) {
   try {
@@ -2237,6 +2403,7 @@ function failureSummary(locale, error) {
     pruned: [],
     invalidIcuSource: [],
     integrityMismatches: [],
+    providerFailures: [],
     generated: [],
     notices: [],
     error: describeError(error)
@@ -2248,6 +2415,29 @@ function partition(locales) {
   return { succeeded, failed };
 }
 
+// src/flow/batching.ts
+function chunk(items, size) {
+  const chunks = [];
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size));
+  }
+  return chunks;
+}
+var GENERIC_PROVIDER_FAILURE_MESSAGE = "The provider call failed.";
+function classifyProviderFailure(error) {
+  if (error instanceof ProviderError) {
+    return { code: error.code, message: error.message };
+  }
+  return { code: "PROVIDER_CALL_FAILED", message: GENERIC_PROVIDER_FAILURE_MESSAGE };
+}
+function subBatchFailedNotice(count, error) {
+  const { code, message } = classifyProviderFailure(error);
+  return {
+    code: "SUB_BATCH_FAILED",
+    message: `A sub-batch of ${count} entries failed (${code}: ${message}) and was withheld; it will be retried next run.`
+  };
+}
+
 // src/flow/notices.ts
 function isNotice(value) {
   return typeof value === "object" && value !== null && typeof value.code === "string" && typeof value.message === "string";
@@ -2430,13 +2620,36 @@ 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: [] };
+    return { accepted: [], withheld: [], providerFailures: [], notices: [] };
   }
-  const entries = stale.map(syntheticEntry);
-  const result = await context.provider.translateBatch(buildRequest2(context, entries));
   const accepted = [];
   const withheld = [];
-  for (const item of stale) {
+  const providerFailures = [];
+  const notices = [];
+  for (const batch of chunk(stale, context.maxBatchSize)) {
+    const batchNotices = await runGenerationSubBatch(
+      context,
+      batch,
+      accepted,
+      withheld,
+      providerFailures
+    );
+    notices.push(...batchNotices);
+  }
+  return { accepted, withheld, providerFailures, notices };
+}
+async function runGenerationSubBatch(context, batch, accepted, withheld, providerFailures) {
+  let result;
+  try {
+    const entries = batch.map(syntheticEntry);
+    result = await context.provider.translateBatch(buildRequest2(context, entries));
+  } catch (error) {
+    for (const item of batch) {
+      providerFailures.push(item.targetKey);
+    }
+    return [subBatchFailedNotice(batch.length, error)];
+  }
+  for (const item of batch) {
     const value = result.values.get(item.targetKey);
     const integrity = result.integrity.get(item.targetKey);
     if (value !== void 0 && integrity?.matches === true) {
@@ -2449,7 +2662,7 @@ async function generatePluralForms(context) {
       withheld.push(item.targetKey);
     }
   }
-  return { accepted, withheld };
+  return readNotices(result);
 }
 
 // src/flow/locale-run.ts
@@ -2499,6 +2712,7 @@ async function runLocale(params) {
         translated: toTranslate,
         generated: [],
         integrityMismatches: [],
+        providerFailures: [],
         pruned,
         notices: sdkNotices
       }),
@@ -2508,12 +2722,14 @@ async function runLocale(params) {
   const entries = toTranslate.map((key) => params.source.entries.get(key)).filter((entry) => entry !== void 0);
   const accepted = /* @__PURE__ */ new Map();
   const integrityMismatches = [];
+  const providerFailures = [];
   const subBatchNotices = await translateAndCheck(
     provider,
     params,
     entries,
     accepted,
-    integrityMismatches
+    integrityMismatches,
+    providerFailures
   );
   const merged = new Map(target.entries);
   for (const key of pruned) {
@@ -2537,8 +2753,18 @@ async function runLocale(params) {
     path
   );
   const pluralNotices = params.generatePlurals ? pluralNoticeFor(params, merged) : sdkNotices;
-  const notices = [...pluralNotices, ...subBatchNotices];
-  const withheld = /* @__PURE__ */ new Set([...integrityMismatches, ...invalidIcuSource, ...generation.withheld]);
+  const notices = [
+    ...pluralNotices,
+    ...subBatchNotices,
+    ...generation.notices
+  ];
+  const withheld = /* @__PURE__ */ new Set([
+    ...integrityMismatches,
+    ...providerFailures,
+    ...invalidIcuSource,
+    ...generation.withheld,
+    ...generation.providerFailures
+  ]);
   return {
     summary: baseSummary({
       locale: params.targetLocale,
@@ -2549,6 +2775,8 @@ async function runLocale(params) {
       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(),
       pruned,
       notices
     }),
@@ -2557,7 +2785,7 @@ async function runLocale(params) {
 }
 async function runGeneration(params, provider) {
   if (!params.generatePlurals || provider.kind !== "llm") {
-    return { accepted: [], withheld: [] };
+    return { accepted: [], withheld: [], providerFailures: [], notices: [] };
   }
   return generatePluralForms({
     source: params.source,
@@ -2568,7 +2796,8 @@ async function runGeneration(params, provider) {
     provider,
     glossary: params.glossary,
     tone: params.tone,
-    baseline: params.baseline
+    baseline: params.baseline,
+    maxBatchSize: params.maxBatchSize
   });
 }
 function pluralNoticeFor(params, merged) {
@@ -2590,27 +2819,35 @@ function baseSummary(parts) {
     pruned: parts.pruned,
     invalidIcuSource: parts.invalidIcuSource,
     integrityMismatches: parts.integrityMismatches,
+    providerFailures: parts.providerFailures,
     generated: parts.generated,
     notices: parts.notices
   };
 }
-async function translateAndCheck(provider, params, entries, accepted, integrityMismatches) {
+async function translateAndCheck(provider, params, entries, accepted, integrityMismatches, providerFailures) {
   const notices = [];
   for (const batch of chunk(entries, params.maxBatchSize)) {
-    const subNotices = await runSubBatch(provider, params, batch, accepted, integrityMismatches);
+    const subNotices = await runSubBatch(
+      provider,
+      params,
+      batch,
+      accepted,
+      integrityMismatches,
+      providerFailures
+    );
     notices.push(...subNotices);
   }
   return notices;
 }
-async function runSubBatch(provider, params, batch, accepted, integrityMismatches) {
+async function runSubBatch(provider, params, batch, accepted, integrityMismatches, providerFailures) {
   let result;
   try {
     result = await provider.translateBatch(buildRequest3(params, batch));
-  } catch {
+  } catch (error) {
     for (const entry of batch) {
-      integrityMismatches.push(entry.key);
+      providerFailures.push(entry.key);
     }
-    return [subBatchFailedNotice(batch.length)];
+    return [subBatchFailedNotice(batch.length, error)];
   }
   for (const entry of batch) {
     const value = result.values.get(entry.key);
@@ -2623,19 +2860,6 @@ async function runSubBatch(provider, params, batch, accepted, integrityMismatche
   }
   return readNotices(result);
 }
-function subBatchFailedNotice(count) {
-  return {
-    code: "SUB_BATCH_FAILED",
-    message: `A sub-batch of ${count} entries failed and was withheld; it will be retried next run.`
-  };
-}
-function chunk(items, size) {
-  const chunks = [];
-  for (let index = 0; index < items.length; index += size) {
-    chunks.push(items.slice(index, index + size));
-  }
-  return chunks;
-}
 function computeLockEntries(params, merged, withheld, generated) {
   const lockEntries = {};
   const sourceBaseKeys = sourcePluralBaseKeys(params.source);
@@ -2783,6 +3007,7 @@ var COLUMN_WIDTHS = {
   [COLUMN.status]: 12,
   [COLUMN.translation]: 50
 };
+var TEXT_NUMBER_FORMAT = "@";
 function styleHeader(sheet) {
   const header = sheet.getRow(HEADER_ROW);
   HEADERS.forEach((label, index) => {
@@ -2798,6 +3023,7 @@ function applyColumnGeometry(sheet) {
     sheet.getColumn(Number(column)).width = width;
   }
   sheet.getColumn(COLUMN.sourceHash).hidden = true;
+  sheet.getColumn(COLUMN.translation).numFmt = TEXT_NUMBER_FORMAT;
   sheet.views = [{ state: "frozen", ySplit: HEADER_ROW }];
 }
 function writeRow(sheet, sheetRow) {
@@ -2806,7 +3032,9 @@ function writeRow(sheet, sheetRow) {
   row.getCell(COLUMN.source).value = sheetRow.source;
   row.getCell(COLUMN.current).value = sheetRow.currentTarget;
   row.getCell(COLUMN.status).value = sheetRow.status;
-  row.getCell(COLUMN.translation).value = sheetRow.translation === "" ? null : sheetRow.translation;
+  const translationCell = row.getCell(COLUMN.translation);
+  translationCell.numFmt = TEXT_NUMBER_FORMAT;
+  translationCell.value = sheetRow.translation === "" ? null : sheetRow.translation;
   row.getCell(COLUMN.sourceHash).value = sheetRow.sourceHash;
   for (let column = COLUMN.key; column <= COLUMN.sourceHash; column += 1) {
     const cell = row.getCell(column);
@@ -3158,9 +3386,20 @@ function judge(row, sourceEntry, adapter) {
   }
   return void 0;
 }
+function trackBlankDrift(row, params, buckets) {
+  const sourceEntry = params.source.entries.get(row.key);
+  if (sourceEntry === void 0) {
+    return;
+  }
+  const priorHash = params.baseline.get(row.key);
+  if (priorHash !== void 0 && priorHash !== contentHash(sourceEntry)) {
+    buckets.blankDrifted.add(row.key);
+  }
+}
 function classifyRows(params, buckets) {
   for (const row of params.sheet.rows) {
     if (row.translation === "") {
+      trackBlankDrift(row, params, buckets);
       continue;
     }
     if (isUnknownKey(row, params.source, params.target)) {
@@ -3179,9 +3418,20 @@ function classifyRows(params, buckets) {
     }
   }
 }
+function blankRowBaselineNotice(count) {
+  return {
+    code: "BLANK_ROW_BASELINE_RETAINED",
+    message: `${count} row(s) were left blank for a key whose source changed since the row's baseline was recorded; the prior baseline was kept so the drift keeps being reported.`
+  };
+}
 function importLocale(params) {
   const diff2 = diffResources(params.source, params.target, { baseline: params.baseline });
-  const buckets = { accepted: /* @__PURE__ */ new Map(), mismatches: [], withheld: /* @__PURE__ */ new Set() };
+  const buckets = {
+    accepted: /* @__PURE__ */ new Map(),
+    mismatches: [],
+    withheld: /* @__PURE__ */ new Set(),
+    blankDrifted: /* @__PURE__ */ new Set()
+  };
   classifyRows(params, buckets);
   const rowKeys = new Set(params.sheet.rows.map((row) => row.key));
   const invalidIcuSource = [...new Set(params.sourceInvalidIcuKeys)].filter((key) => rowKeys.has(key)).sort();
@@ -3195,9 +3445,11 @@ function importLocale(params) {
     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.
     generated: [],
-    notices: []
+    notices: buckets.blankDrifted.size > 0 ? [blankRowBaselineNotice(buckets.blankDrifted.size)] : []
   };
   return { summary, accepted: buckets.accepted, withheld: buckets.withheld };
 }
@@ -3231,21 +3483,19 @@ function mergeAccepted(target, accepted) {
   }
   return merged;
 }
-function computeLockEntries2(source, merged, baseline, withheld) {
+function computeLockEntries2(source, merged, baseline, accepted) {
   const entries = {};
   for (const key of merged.keys()) {
     const sourceEntry = source.entries.get(key);
     if (sourceEntry === void 0) {
       continue;
     }
-    if (withheld.has(key)) {
-      const prior = baseline.get(key);
-      if (prior !== void 0) {
-        entries[key] = prior;
-      }
+    if (accepted.has(key)) {
+      entries[key] = contentHash(sourceEntry);
       continue;
     }
-    entries[key] = contentHash(sourceEntry);
+    const prior = baseline.get(key);
+    entries[key] = prior !== void 0 ? prior : contentHash(sourceEntry);
   }
   return entries;
 }
@@ -3258,7 +3508,7 @@ async function runSheet(ctx, sheet, lock) {
   }
   const target = await readTarget4(ctx.cwd, ctx.config, ctx.adapter, ctx.fs, sheet.locale);
   const baseline = baselineFor(lock, sheet.locale);
-  const { summary, accepted, withheld } = importLocale({
+  const { summary, accepted } = importLocale({
     sheet,
     source: ctx.source,
     target,
@@ -3282,7 +3532,7 @@ async function runSheet(ctx, sheet, lock) {
       path
     );
   }
-  return { summary, lockEntries: computeLockEntries2(ctx.source, merged, baseline, withheld) };
+  return { summary, lockEntries: computeLockEntries2(ctx.source, merged, baseline, accepted) };
 }
 async function importWorkbook(input, deps = {}) {
   const config = input.config;
@@ -3327,6 +3577,13 @@ async function importWorkbook(input, deps = {}) {
   return { dryRun, locales: summaries, succeeded, failed };
 }
 
+// src/lock/load-lock-file.ts
+async function loadLockFile(input = {}, deps = {}) {
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  return readLockFile(lockFilePath(cwd), fs);
+}
+
 // src/scaffolding.ts
 var scaffoldingMetadata = {
   /** Provider id -> the environment variable its API key is read from. Owned by ai-providers. */
@@ -3443,6 +3700,7 @@ async function watch(input, deps = {}) {
 }
 
 exports.DEFAULT_WORKBOOK_PATH = DEFAULT_WORKBOOK_PATH;
+exports.LOCK_FILE_NAME = LOCK_FILE_NAME;
 exports.SdkError = SdkError;
 exports.check = check;
 exports.defineConfig = defineConfig;
@@ -3450,6 +3708,9 @@ exports.diff = diff;
 exports.exportWorkbook = exportWorkbook;
 exports.importWorkbook = importWorkbook;
 exports.loadConfig = loadConfig;
+exports.loadConfigWithMeta = loadConfigWithMeta;
+exports.loadLockFile = loadLockFile;
+exports.lockState = lockState;
 exports.scaffoldingMetadata = scaffoldingMetadata;
 exports.translate = translate2;
 exports.verbatraConfigSchema = verbatraConfigSchema;