@verbatra/sdk 0.4.4 → 0.5.0-next.1

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;
@@ -192,6 +341,85 @@ var LOCALE_TOKEN = "{locale}";
 function localeFilePath(cwd, pattern, locale) {
   return path.resolve(cwd, pattern.replaceAll(LOCALE_TOKEN, locale));
 }
+var RATE_LIMITED_STATUS = 429;
+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
+]);
+function getErrorStatus(error) {
+  if (typeof error !== "object" || error === null || !("status" in error)) {
+    return void 0;
+  }
+  const status = error.status;
+  return typeof status === "number" ? status : void 0;
+}
+function readClassName(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  return error.constructor?.name;
+}
+function classifyProviderError(error) {
+  const status = getErrorStatus(error);
+  if (status === RATE_LIMITED_STATUS) {
+    return "RATE_LIMITED";
+  }
+  if (status !== void 0 && AUTH_FAILED_STATUSES.has(status)) {
+    return "AUTH_FAILED";
+  }
+  if (status === TIMEOUT_STATUS) {
+    return "TIMEOUT";
+  }
+  const className = readClassName(error);
+  if (className !== void 0) {
+    if (RATE_LIMITED_CLASS_NAMES.has(className)) {
+      return "RATE_LIMITED";
+    }
+    if (AUTH_FAILED_CLASS_NAMES.has(className)) {
+      return "AUTH_FAILED";
+    }
+    if (TIMEOUT_CLASS_NAMES.has(className)) {
+      return "TIMEOUT";
+    }
+  }
+  return "PROVIDER_ERROR";
+}
+function isAbortShapedError(error) {
+  if (error instanceof Error && error.name === "AbortError") {
+    return true;
+  }
+  const className = readClassName(error);
+  return className !== void 0 && ABORT_ERROR_CLASS_NAMES.has(className);
+}
+function isAbortError(error, signal) {
+  if (signal !== void 0) {
+    return signal.aborted === true && isAbortShapedError(error);
+  }
+  return isAbortShapedError(error);
+}
 var REDACTED = "[REDACTED]";
 var KEY_PATTERNS = [
   // The `\b` anchors `sk-` to a word start so hyphenated words like "risk-" or "task-" pass through.
@@ -226,17 +454,34 @@ var ProviderError = class extends Error {
   }
 };
 var PROVIDER_CALL_FAILED_MESSAGE = "The translation provider request failed.";
-async function guardProviderCall(call) {
+var RATE_LIMITED_MESSAGE = "The translation provider rate-limited this request.";
+var TIMEOUT_MESSAGE = "The translation provider request timed out.";
+var AUTH_FAILED_MESSAGE = "The translation provider rejected the request credentials.";
+var MESSAGE_BY_CODE = {
+  RATE_LIMITED: RATE_LIMITED_MESSAGE,
+  TIMEOUT: TIMEOUT_MESSAGE,
+  AUTH_FAILED: AUTH_FAILED_MESSAGE,
+  PROVIDER_ERROR: PROVIDER_CALL_FAILED_MESSAGE
+};
+async function guardProviderCall(call, signal) {
+  signal?.throwIfAborted();
   try {
     return await call();
-  } catch {
-    throw new ProviderError("PROVIDER_ERROR", PROVIDER_CALL_FAILED_MESSAGE);
+  } catch (error) {
+    if (isAbortError(error, signal)) {
+      throw error;
+    }
+    const code = classifyProviderError(error);
+    throw new ProviderError(code, MESSAGE_BY_CODE[code]);
   }
 }
-function checkBatchIntegrity(inputs, extract) {
+function checkBatchIntegrity(inputs, extract, compare) {
   const integrity = /* @__PURE__ */ new Map();
-  for (const { key, sourcePlaceholders, translatedValue } of inputs) {
-    integrity.set(key, checkPlaceholders(sourcePlaceholders, extract(translatedValue)));
+  for (const { key, sourceValue, translatedValue } of inputs) {
+    integrity.set(
+      key,
+      compare !== void 0 ? compare(sourceValue, translatedValue) : checkPlaceholders(extract(sourceValue), extract(translatedValue))
+    );
   }
   return integrity;
 }
@@ -266,7 +511,7 @@ function toIntegrityInputs(entries, values) {
         "The provider response is missing one or more keys."
       );
     }
-    return { key: entry.key, sourcePlaceholders: entry.placeholders, translatedValue };
+    return { key: entry.key, sourceValue: entry.value, translatedValue };
   });
 }
 function toItem(entry) {
@@ -333,11 +578,16 @@ async function runLlmTranslation(request, mechanism) {
   const data = validateRequest(request);
   const payloadJson = JSON.stringify(buildDataPayload(data));
   const requestedKeys = data.entries.map((entry) => entry.key);
-  const completion = await mechanism.translate({ payloadJson, requestedKeys });
+  const completion = await mechanism.translate({
+    payloadJson,
+    requestedKeys,
+    ...request.signal !== void 0 ? { signal: request.signal } : {}
+  });
   const values = reconcileResult(completion.raw, requestedKeys);
   const integrity = checkBatchIntegrity(
     toIntegrityInputs(data.entries, values),
-    request.extractPlaceholders
+    request.extractPlaceholders,
+    request.comparePlaceholders
   );
   return completion.usage === void 0 ? { values, integrity } : { values, integrity, usage: completion.usage };
 }
@@ -372,12 +622,29 @@ function requireGeminiKey() {
 function requireDeepLKey() {
   return readRequiredEnv(PROVIDER_ENV.deepl);
 }
+var OPENAI_COMPATIBLE_ENV_VAR = "OPENAI_COMPATIBLE_API_KEY";
+var OPENAI_COMPATIBLE_KEY_PLACEHOLDER = "local";
+function resolveOpenAiCompatibleKey(customEnvVar) {
+  const varName = customEnvVar ?? OPENAI_COMPATIBLE_ENV_VAR;
+  const value = process.env[varName];
+  if (value !== void 0 && value.length > 0) {
+    return value;
+  }
+  if (customEnvVar !== void 0) {
+    throw new ProviderError(
+      "MISSING_API_KEY",
+      `The ${customEnvVar} environment variable is not set.`
+    );
+  }
+  return OPENAI_COMPATIBLE_KEY_PLACEHOLDER;
+}
 function createDefaultClient() {
   const sdk = new Anthropic__default.default({ apiKey: requireAnthropicKey(), logLevel: "off" });
   return {
     messages: {
-      create: async (body) => await sdk.messages.create(
-        body
+      create: async (body, options) => await sdk.messages.create(
+        body,
+        options
       )
     }
   };
@@ -445,9 +712,9 @@ function createAnthropicProvider(config, deps = {}) {
 }
 function createMechanism(client, config) {
   return {
-    translate: async ({ payloadJson }) => {
+    translate: async ({ payloadJson, signal }) => {
       const body = buildRequest(config, payloadJson);
-      const message = await callClient(client, body);
+      const message = await callClient(client, body, signal);
       assertNotTruncated(message.stop_reason === "max_tokens");
       const raw = requireToolInput(message.content);
       const usage = toUsage(message.usage);
@@ -455,8 +722,11 @@ function createMechanism(client, config) {
     }
   };
 }
-function callClient(client, body) {
-  return guardProviderCall(() => client.messages.create(body));
+function callClient(client, body, signal) {
+  return guardProviderCall(
+    () => client.messages.create(body, signal !== void 0 ? { signal } : void 0),
+    signal
+  );
 }
 function toUsage(usage) {
   if (usage === void 0) {
@@ -551,7 +821,7 @@ function zipResults(entries, results) {
     values.set(entry.key, translatedValue);
     integrityInputs.push({
       key: entry.key,
-      sourcePlaceholders: entry.placeholders,
+      sourceValue: entry.value,
       translatedValue
     });
   }
@@ -592,36 +862,97 @@ async function translate(bundle, config, request) {
     data,
     protectable,
     options,
-    request.extractPlaceholders
+    request.extractPlaceholders,
+    request.comparePlaceholders,
+    request.signal
   );
   if (unprotectable.length > 0) {
     notices.push({ code: "PLACEHOLDER_UNSUPPORTED", message: PLACEHOLDER_UNSUPPORTED_MESSAGE });
   }
   return { values, integrity, notices };
 }
-async function translateProtectable(client, data, protectable, options, extract) {
+async function translateProtectable(client, data, protectable, options, extract, compare, signal) {
   if (protectable.length === 0) {
     return { values: /* @__PURE__ */ new Map(), integrity: /* @__PURE__ */ new Map() };
   }
   const texts = protectable.map((entry) => entry.value);
-  const results = await callClient2(client, texts, data.sourceLocale, data.targetLocale, options);
+  const results = await callClient2(
+    client,
+    texts,
+    data.sourceLocale,
+    data.targetLocale,
+    options,
+    signal
+  );
   const { values, integrityInputs } = zipResults(protectable, results);
-  const integrity = checkBatchIntegrity(integrityInputs, extract);
+  const integrity = checkBatchIntegrity(integrityInputs, extract, compare);
   return { values, integrity };
 }
-function callClient2(client, texts, sourceLang, targetLang, options) {
-  return guardProviderCall(() => client.translateText(texts, sourceLang, targetLang, options));
+function callClient2(client, texts, sourceLang, targetLang, options, signal) {
+  return guardProviderCall(
+    () => client.translateText(texts, sourceLang, targetLang, options),
+    signal
+  );
 }
 var geminiConfigSchema = zod.z.object({
   model: zod.z.string().min(1),
   maxOutputTokens: zod.z.number().int().positive()
 });
+var DEFAULT_GEMINI_RETRY = { attempts: 3, baseDelayMs: 250 };
+function isRetryableStatus(error) {
+  const status = getErrorStatus(error);
+  return status === 429 || status !== void 0 && status >= 500 && status < 600;
+}
+function isAborted(signal) {
+  return signal?.aborted === true;
+}
+function throwAbort(signal) {
+  signal?.throwIfAborted();
+  throw new DOMException("This operation was aborted.", "AbortError");
+}
+function delay(ms, signal) {
+  return new Promise((resolve7) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve7();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve7();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function withGeminiRetry(call, signal, config = DEFAULT_GEMINI_RETRY) {
+  let attempt = 1;
+  while (true) {
+    try {
+      return await call();
+    } catch (error) {
+      if (isAborted(signal)) {
+        throwAbort(signal);
+      }
+      const exhausted = attempt >= config.attempts;
+      if (exhausted || !isRetryableStatus(error)) {
+        throw error;
+      }
+      await delay(config.baseDelayMs * 2 ** (attempt - 1), signal);
+      if (isAborted(signal)) {
+        throwAbort(signal);
+      }
+      attempt += 1;
+    }
+  }
+}
 function createDefaultClient3() {
   const ai = new genai.GoogleGenAI({ apiKey: requireGeminiKey() });
   return {
     models: {
-      generateContent: async (request) => await ai.models.generateContent(
-        request
+      generateContent: (request) => withGeminiRetry(
+        async () => await ai.models.generateContent(
+          request
+        ),
+        request.config.abortSignal
       )
     }
   };
@@ -685,7 +1016,7 @@ var GEMINI_SYSTEM_RULES = [
   "When a tone is provided, honor it.",
   "Respond only with the structured object: exactly one entry per requested key, no commentary, no extra keys, and no key that was not requested."
 ].join("\n");
-function buildGeminiRequest(config, payloadJson) {
+function buildGeminiRequest(config, payloadJson, signal) {
   return {
     model: config.model,
     contents: [{ role: "user", parts: [{ text: payloadJson }] }],
@@ -693,7 +1024,8 @@ function buildGeminiRequest(config, payloadJson) {
       systemInstruction: GEMINI_SYSTEM_RULES,
       responseMimeType: "application/json",
       responseSchema: toGeminiSchema(deriveJsonSchema(translationsResultSchema)),
-      maxOutputTokens: config.maxOutputTokens
+      maxOutputTokens: config.maxOutputTokens,
+      ...signal !== void 0 ? { abortSignal: signal } : {}
     }
   };
 }
@@ -757,15 +1089,15 @@ function createGeminiProvider(config, deps = {}) {
 }
 function createMechanism2(client, config) {
   return {
-    translate: async ({ payloadJson }) => {
-      const request = buildGeminiRequest(config, payloadJson);
-      const response = await callClient3(client, request);
+    translate: async ({ payloadJson, signal }) => {
+      const request = buildGeminiRequest(config, payloadJson, signal);
+      const response = await callClient3(client, request, signal);
       return extractGeminiResult(response);
     }
   };
 }
-function callClient3(client, request) {
-  return guardProviderCall(() => client.models.generateContent(request));
+function callClient3(client, request, signal) {
+  return guardProviderCall(() => client.models.generateContent(request), signal);
 }
 var openAiConfigSchema = zod.z.object({
   model: zod.z.string().min(1),
@@ -776,8 +1108,9 @@ function createDefaultClient4() {
   return {
     chat: {
       completions: {
-        create: async (body) => await sdk.chat.completions.create(
-          body
+        create: async (body, options) => await sdk.chat.completions.create(
+          body,
+          options
         )
       }
     }
@@ -795,7 +1128,20 @@ var OPENAI_SYSTEM_RULES = [
   "When a tone is provided, honor it.",
   "Respond only with the structured object: exactly one entry per requested key, no commentary, no extra keys, and no key that was not requested."
 ].join("\n");
-function buildOpenAiRequest(config, payloadJson) {
+function buildResponseFormat(mode) {
+  if (mode === "json-object") {
+    return { type: "json_object" };
+  }
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: RESULT_SCHEMA_NAME,
+      strict: true,
+      schema: deriveJsonSchema(translationsResultSchema)
+    }
+  };
+}
+function buildOpenAiRequest(config, payloadJson, mode = "strict-schema") {
   return {
     model: config.model,
     max_completion_tokens: config.maxOutputTokens,
@@ -803,19 +1149,66 @@ function buildOpenAiRequest(config, payloadJson) {
       { role: "system", content: OPENAI_SYSTEM_RULES },
       { role: "user", content: payloadJson }
     ],
-    response_format: {
-      type: "json_schema",
-      json_schema: {
-        name: RESULT_SCHEMA_NAME,
-        strict: true,
-        schema: deriveJsonSchema(translationsResultSchema)
+    response_format: buildResponseFormat(mode)
+  };
+}
+function advanceStringScan(char, escaped) {
+  if (escaped) {
+    return { inString: true, escaped: false };
+  }
+  if (char === "\\") {
+    return { inString: true, escaped: true };
+  }
+  return { inString: char !== '"', escaped: false };
+}
+function scanBalancedObjectEnd(content, start) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < content.length; i += 1) {
+    const char = content[i];
+    if (inString) {
+      ({ inString, escaped } = advanceStringScan(char, escaped));
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+    } else if (char === "{") {
+      depth += 1;
+    } else if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return i;
       }
     }
-  };
+  }
+  return null;
+}
+function extractBalancedJson(content) {
+  let searchFrom = 0;
+  while (searchFrom < content.length) {
+    const start = content.indexOf("{", searchFrom);
+    if (start === -1) {
+      return null;
+    }
+    const end = scanBalancedObjectEnd(content, start);
+    if (end === null) {
+      return null;
+    }
+    const candidate = content.slice(start, end + 1);
+    try {
+      JSON.parse(candidate);
+      return candidate;
+    } catch {
+      searchFrom = end + 1;
+    }
+  }
+  return null;
 }
-function parseContent2(content) {
+function parseContent2(content, tolerant) {
+  const candidate = tolerant ? extractBalancedJson(content) ?? content : content;
   try {
-    return JSON.parse(content);
+    return JSON.parse(candidate);
   } catch {
     throw new ProviderError("INVALID_RESPONSE", "The provider returned unparseable content.");
   }
@@ -830,7 +1223,7 @@ function toUsage3(usage) {
   }
   return { inputTokens: prompt_tokens, outputTokens: completion_tokens };
 }
-function extractOpenAiResult(completion) {
+function extractOpenAiResult(completion, tolerant = false) {
   const choice = completion.choices[0];
   if (choice === void 0) {
     throw new ProviderError("INVALID_RESPONSE", "The provider returned no message.");
@@ -843,7 +1236,7 @@ function extractOpenAiResult(completion) {
   if (message.content === void 0 || message.content === null) {
     throw new ProviderError("INVALID_RESPONSE", "The provider returned no translation content.");
   }
-  const raw = parseContent2(message.content);
+  const raw = parseContent2(message.content, tolerant);
   const usage = toUsage3(completion.usage);
   return usage === void 0 ? { raw } : { raw, usage };
 }
@@ -861,15 +1254,84 @@ function createOpenAiProvider(config, deps = {}) {
 }
 function createMechanism3(client, config) {
   return {
-    translate: async ({ payloadJson }) => {
+    translate: async ({ payloadJson, signal }) => {
       const body = buildOpenAiRequest(config, payloadJson);
-      const completion = await callClient4(client, body);
+      const completion = await callClient4(client, body, signal);
       return extractOpenAiResult(completion);
     }
   };
 }
-function callClient4(client, body) {
-  return guardProviderCall(() => client.chat.completions.create(body));
+function callClient4(client, body, signal) {
+  return guardProviderCall(
+    () => client.chat.completions.create(body, signal !== void 0 ? { signal } : void 0),
+    signal
+  );
+}
+var HOSTED_PROVIDER_ENV_VARS = new Set(
+  Object.values(PROVIDER_ENV).map((name) => name.toUpperCase())
+);
+function isNotHostedProviderEnvVar(value) {
+  return !HOSTED_PROVIDER_ENV_VARS.has(value.toUpperCase());
+}
+function isHttpOrHttpsUrl(value) {
+  try {
+    const { protocol } = new URL(value);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+var openAiCompatibleConfigSchema = zod.z.object({
+  baseUrl: zod.z.url({ message: "baseUrl must be a valid absolute URL." }).refine(isHttpOrHttpsUrl, { message: "baseUrl must use the http or https scheme." }),
+  model: zod.z.string().min(1),
+  maxOutputTokens: zod.z.number().int().positive(),
+  apiKeyEnvVar: zod.z.string().min(1).refine(isNotHostedProviderEnvVar, {
+    message: "apiKeyEnvVar must not name a hosted provider's environment variable."
+  }).optional()
+});
+function createDefaultClient5(config) {
+  const sdk = new OpenAI__default.default({
+    apiKey: resolveOpenAiCompatibleKey(config.apiKeyEnvVar),
+    baseURL: config.baseUrl,
+    logLevel: "off"
+  });
+  return {
+    chat: {
+      completions: {
+        create: async (body, options) => await sdk.chat.completions.create(
+          body,
+          options
+        )
+      }
+    }
+  };
+}
+var PROVIDER_ID5 = "openai-compatible";
+function createOpenAiCompatibleProvider(config, deps = {}) {
+  const validConfig = openAiCompatibleConfigSchema.parse(config);
+  const client = deps.client ?? createDefaultClient5(validConfig);
+  const mechanism = createMechanism4(client, validConfig);
+  return {
+    id: PROVIDER_ID5,
+    kind: "llm",
+    supportsGlossary: true,
+    translateBatch: (request) => runLlmTranslation(request, mechanism)
+  };
+}
+function createMechanism4(client, config) {
+  return {
+    translate: async ({ payloadJson, signal }) => {
+      const body = buildOpenAiRequest(config, payloadJson, "strict-schema");
+      const completion = await callClient5(client, body, signal);
+      return extractOpenAiResult(completion, true);
+    }
+  };
+}
+function callClient5(client, body, signal) {
+  return guardProviderCall(
+    () => client.chat.completions.create(body, signal !== void 0 ? { signal } : void 0),
+    signal
+  );
 }
 var SCAFFOLD_MODELS = {
   anthropic: "claude-sonnet-4-6",
@@ -880,13 +1342,18 @@ var providerConfigSchema = zod.z.discriminatedUnion("id", [
   zod.z.object({ id: zod.z.literal("anthropic"), options: anthropicConfigSchema.strict() }),
   zod.z.object({ id: zod.z.literal("openai"), options: openAiConfigSchema.strict() }),
   zod.z.object({ id: zod.z.literal("gemini"), options: geminiConfigSchema.strict() }),
-  zod.z.object({ id: zod.z.literal("deepl"), options: deepLConfigSchema.strict() })
+  zod.z.object({ id: zod.z.literal("deepl"), options: deepLConfigSchema.strict() }),
+  zod.z.object({
+    id: zod.z.literal("openai-compatible"),
+    options: openAiCompatibleConfigSchema.strict()
+  })
 ]);
 var providerFactories = {
   anthropic: (options) => createAnthropicProvider(options),
   openai: (options) => createOpenAiProvider(options),
   gemini: (options) => createGeminiProvider(options),
-  deepl: (options) => createDeepLProvider(options)
+  deepl: (options) => createDeepLProvider(options),
+  "openai-compatible": (options) => createOpenAiCompatibleProvider(options)
 };
 function buildProvider(config) {
   const create = providerFactories[config.id];
@@ -903,7 +1370,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 +1430,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 +1440,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 +1461,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 +1492,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();
-  }
+  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 };
 }
-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;
-  }
+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: {} };
@@ -1130,6 +1532,12 @@ async function readLockFile(path, fs) {
   if (!result.success) {
     throw new SdkError("LOCK_FILE_INVALID", `The lock-file at ${path} has an unexpected shape.`);
   }
+  if (result.data.version !== CURRENT_VERSION) {
+    throw new SdkError(
+      "LOCK_FILE_INVALID",
+      `The lock-file at ${path} has version ${result.data.version}, but this version of verbatra supports version ${CURRENT_VERSION}.`
+    );
+  }
   return result.data;
 }
 function baselineFor(lock, locale) {
@@ -1262,6 +1670,150 @@ function icuInvalidKeys(entries) {
   }
   return invalid;
 }
+function tokenOf2(element) {
+  switch (element.type) {
+    case icuMessageformatParser.TYPE.argument:
+    case icuMessageformatParser.TYPE.number:
+    case icuMessageformatParser.TYPE.date:
+    case icuMessageformatParser.TYPE.time:
+    case icuMessageformatParser.TYPE.select:
+    case icuMessageformatParser.TYPE.plural:
+      return `{${element.value}}`;
+    case icuMessageformatParser.TYPE.tag:
+      return `<${element.value}>`;
+    default:
+      return void 0;
+  }
+}
+function isBranching(element) {
+  return element.type === icuMessageformatParser.TYPE.plural || element.type === icuMessageformatParser.TYPE.select;
+}
+function isTag(element) {
+  return element.type === icuMessageformatParser.TYPE.tag;
+}
+function layerTokens(elements) {
+  const tokens = [];
+  for (const element of elements) {
+    const token = tokenOf2(element);
+    if (token !== void 0) {
+      tokens.push(token);
+    }
+  }
+  return tokens;
+}
+function deepTokens(elements) {
+  const tokens = [];
+  for (const element of elements) {
+    const token = tokenOf2(element);
+    if (token !== void 0) {
+      tokens.push(token);
+    }
+    if (isTag(element)) {
+      tokens.push(...deepTokens(element.children));
+    } else if (isBranching(element)) {
+      for (const option of Object.values(element.options)) {
+        tokens.push(...deepTokens(option.value));
+      }
+    }
+  }
+  return tokens;
+}
+function branchesByCategory(element) {
+  return new Map(
+    Object.entries(element.options).map(([category, option]) => [category, option.value])
+  );
+}
+function findUnconsumed(target, consumed, isMatch) {
+  for (let index = 0; index < target.length; index += 1) {
+    if (consumed.has(index)) {
+      continue;
+    }
+    const candidate = target[index];
+    if (candidate !== void 0 && isMatch(candidate)) {
+      return { element: candidate, index };
+    }
+  }
+  return void 0;
+}
+function findMatchingBranching(source, target, consumed) {
+  return findUnconsumed(
+    target,
+    consumed,
+    (candidate) => isBranching(candidate) && candidate.value === source.value
+  );
+}
+function findMatchingTag(source, target, consumed) {
+  return findUnconsumed(
+    target,
+    consumed,
+    (candidate) => isTag(candidate) && candidate.value === source.value
+  );
+}
+function combineResults(results) {
+  const missing = results.flatMap((result) => result.missing).sort();
+  const extra = results.flatMap((result) => result.extra).sort();
+  return { matches: missing.length === 0 && extra.length === 0, missing, extra, reordered: false };
+}
+function compareAgainstSourceUnion(sourceBranches, targetBranch) {
+  const union = /* @__PURE__ */ new Set();
+  for (const branch of sourceBranches.values()) {
+    for (const token of deepTokens(branch)) {
+      union.add(token);
+    }
+  }
+  const extra = deepTokens(targetBranch).filter((token) => !union.has(token)).sort();
+  return { matches: extra.length === 0, missing: [], extra, reordered: false };
+}
+function compareBranching(source, target) {
+  const sourceBranches = branchesByCategory(source);
+  const targetBranches = branchesByCategory(target);
+  const categories = /* @__PURE__ */ new Set([...sourceBranches.keys(), ...targetBranches.keys()]);
+  const results = [];
+  for (const category of categories) {
+    const sourceBranch = sourceBranches.get(category);
+    const targetBranch = targetBranches.get(category);
+    if (sourceBranch !== void 0 && targetBranch !== void 0) {
+      results.push(compareElements(sourceBranch, targetBranch));
+    } else if (targetBranch !== void 0) {
+      results.push(compareAgainstSourceUnion(sourceBranches, targetBranch));
+    }
+  }
+  return combineResults(results);
+}
+function nestedResults(source, target) {
+  const results = [];
+  const consumed = /* @__PURE__ */ new Set();
+  for (const element of source) {
+    if (isBranching(element)) {
+      const found = findMatchingBranching(element, target, consumed);
+      if (found !== void 0) {
+        consumed.add(found.index);
+        results.push(compareBranching(element, found.element));
+      }
+    } else if (isTag(element)) {
+      const found = findMatchingTag(element, target, consumed);
+      if (found !== void 0) {
+        consumed.add(found.index);
+        results.push(compareElements(element.children, found.element.children));
+      }
+    }
+  }
+  return results;
+}
+function compareElements(source, target) {
+  const layer = checkPlaceholders(layerTokens(source), layerTokens(target));
+  const nested = nestedResults(source, target);
+  return nested.length === 0 ? layer : combineResults([layer, ...nested]);
+}
+function compareIcuPlaceholders(sourceValue, targetValue) {
+  try {
+    const sourceAst = icuMessageformatParser.parse(sourceValue);
+    const targetAst = icuMessageformatParser.parse(targetValue);
+    return compareElements(sourceAst, targetAst);
+  } catch {
+    return checkPlaceholders(icuPlaceholders(sourceValue), icuPlaceholders(targetValue));
+  }
+}
 var AdapterError = class extends Error {
   code;
   constructor(code, message) {
@@ -1563,9 +2115,9 @@ function unflattenEntries(entries) {
   }
   return root;
 }
-function toEntries(content, namespace, parse2, deriveEntry, keyMode, validateTree) {
+function toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTree) {
   try {
-    const tree = parse2(content);
+    const tree = parse3(content);
     validateTree?.(tree);
     return flattenTree(tree, namespace, deriveEntry, keyMode);
   } catch (error) {
@@ -1577,7 +2129,7 @@ function createTreeFileAdapter(options) {
     format,
     extensions,
     sniff,
-    parse: parse2,
+    parse: parse3,
     serialize,
     deriveEntry,
     extractPlaceholders,
@@ -1585,6 +2137,7 @@ function createTreeFileAdapter(options) {
     validateMessage,
     validateTree,
     buildWriteTree,
+    comparePlaceholders,
     keyMode = "literal-leaf"
   } = options;
   return {
@@ -1592,10 +2145,11 @@ function createTreeFileAdapter(options) {
     canHandle: buildCanHandle(extensions, sniff),
     extractPlaceholders,
     validateMessage: validateMessage ?? (() => true),
+    ...comparePlaceholders !== void 0 ? { comparePlaceholders } : {},
     async read(filePath, locale) {
       const content = await readFileContent(filePath);
       const namespace = namespaceOf(filePath);
-      const entries = toEntries(content, namespace, parse2, deriveEntry, keyMode, validateTree);
+      const entries = toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTree);
       const resource = { locale, namespace, format, entries };
       const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys);
       return { resource, invalidIcuKeys };
@@ -1691,6 +2245,7 @@ function createArbAdapter() {
     deriveEntry: icuDeriveEntry,
     computeInvalidIcuKeys: icuInvalidKeys,
     validateMessage: icuIsValid,
+    comparePlaceholders: compareIcuPlaceholders,
     buildWriteTree: buildArbWriteTree
   });
 }
@@ -1754,7 +2309,8 @@ function createNextIntlJsonAdapter() {
     extractPlaceholders: icuPlaceholders,
     deriveEntry: icuDeriveEntry,
     computeInvalidIcuKeys: icuInvalidKeys,
-    validateMessage: icuIsValid
+    validateMessage: icuIsValid,
+    comparePlaceholders: compareIcuPlaceholders
   });
 }
 function assertNoDottedNestedKey(tree) {
@@ -1956,6 +2512,7 @@ function extractXliffPlaceholders(value) {
   return result;
 }
 var ELEMENT_NODE = 1;
+var TEXT_NODE = 3;
 function isElement(node) {
   return node.nodeType === ELEMENT_NODE;
 }
@@ -2046,6 +2603,12 @@ function parseXliffEntries(content, namespace) {
   const serializer = new xmldom.XMLSerializer();
   const out = /* @__PURE__ */ new Map();
   for (const unit of walkUnits(root)) {
+    if (out.has(unit.key)) {
+      throw new AdapterError(
+        "INVALID_STRUCTURE",
+        "The XLIFF file has two trans-units with the same id."
+      );
+    }
     const value = unitValue(serializer, unit);
     out.set(unit.key, {
       key: unit.key,
@@ -2072,10 +2635,67 @@ async function readDestination(filePath) {
   }
   return outcome.content;
 }
+var XLIFF_INLINE_ELEMENTS = /* @__PURE__ */ new Set(["x", "g", "bx", "ex", "ph", "it", "mrk"]);
+var XLIFF_NAMESPACES = /* @__PURE__ */ new Set([
+  "urn:oasis:names:tc:xliff:document:1.2",
+  "urn:oasis:names:tc:xliff:document:2.0"
+]);
+var INLINE_ELEMENT_ATTRIBUTES = {
+  x: ["id", "ctype"],
+  ph: ["id", "ctype"],
+  g: ["id", "ctype"],
+  bx: ["id", "rid", "ctype"],
+  ex: ["id", "rid"],
+  it: ["id", "pos", "ctype"],
+  mrk: ["id", "mtype"]
+};
+function isAllowedInlineElement(element) {
+  const namespace = element.namespaceURI;
+  const hasAllowedNamespace = namespace === null || XLIFF_NAMESPACES.has(namespace);
+  return hasAllowedNamespace && XLIFF_INLINE_ELEMENTS.has(element.localName ?? "");
+}
+function isAllowedFragmentNode(node) {
+  if (node.nodeType === TEXT_NODE) {
+    return true;
+  }
+  return isElement(node) && isAllowedInlineElement(node);
+}
+function allDescendantNodes(node) {
+  const children = Array.from(node.childNodes);
+  return children.flatMap((child) => [child, ...allDescendantNodes(child)]);
+}
+function hasDisallowedNode(root) {
+  return allDescendantNodes(root).some((node) => !isAllowedFragmentNode(node));
+}
+function attributeNames(element) {
+  const names = [];
+  for (let i = 0; i < element.attributes.length; i += 1) {
+    const attr = element.attributes.item(i);
+    if (attr !== null) {
+      names.push(attr.name);
+    }
+  }
+  return names;
+}
+function sanitizeInlineAttributes(root) {
+  for (const el of collectByTag(root, "*")) {
+    const allowed = INLINE_ELEMENT_ATTRIBUTES[el.localName ?? ""] ?? [];
+    for (const name of attributeNames(el)) {
+      if (!allowed.includes(name)) {
+        el.removeAttribute(name);
+      }
+    }
+  }
+}
 function fragmentNodes(parser, value) {
+  assertNoDoctype(value);
   try {
     const root = parser.parseFromString(`<wrapper>${value}</wrapper>`, "text/xml").documentElement;
-    return root === null ? null : Array.from(root.childNodes);
+    if (root === null || hasDisallowedNode(root)) {
+      return null;
+    }
+    sanitizeInlineAttributes(root);
+    return Array.from(root.childNodes);
   } catch {
     return null;
   }
@@ -2254,6 +2874,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 {
@@ -2495,7 +3149,8 @@ function buildRequest2(context, entries) {
     entries,
     extractPlaceholders: context.adapter.extractPlaceholders,
     ...context.glossary !== void 0 ? { glossary: context.glossary } : {},
-    ...context.tone !== void 0 ? { tone: context.tone } : {}
+    ...context.tone !== void 0 ? { tone: context.tone } : {},
+    ...context.adapter.comparePlaceholders !== void 0 ? { comparePlaceholders: context.adapter.comparePlaceholders } : {}
   };
 }
 async function generatePluralForms(context) {
@@ -2565,7 +3220,8 @@ function buildRequest3(params, entries) {
     entries,
     extractPlaceholders: params.adapter.extractPlaceholders,
     ...params.glossary !== void 0 ? { glossary: params.glossary } : {},
-    ...params.tone !== void 0 ? { tone: params.tone } : {}
+    ...params.tone !== void 0 ? { tone: params.tone } : {},
+    ...params.adapter.comparePlaceholders !== void 0 ? { comparePlaceholders: params.adapter.comparePlaceholders } : {}
   };
 }
 async function runLocale(params) {
@@ -3028,7 +3684,7 @@ async function streamEntryBounded(file, remaining) {
       "The workbook decompresses to more than the permitted maximum bytes."
     );
   }
-  return Buffer.concat(chunks).toString("utf8");
+  return { raw, content: Buffer.concat(chunks).toString("utf8") };
 }
 async function guardWorkbookBytes(bytes, limits) {
   let zip;
@@ -3060,14 +3716,8 @@ async function guardWorkbookBytes(bytes, limits) {
   let actualTotal = 0;
   for (const file of files) {
     const remaining = limits.maxDecompressedBytes - actualTotal;
-    const content = await streamEntryBounded(file, remaining);
-    actualTotal += Buffer.byteLength(content, "utf8");
-    if (actualTotal > limits.maxDecompressedBytes) {
-      throw new ExchangeError(
-        "WORKBOOK_INVALID",
-        `The workbook decompresses to more than the maximum of ${limits.maxDecompressedBytes} bytes.`
-      );
-    }
+    const { raw, content } = await streamEntryBounded(file, remaining);
+    actualTotal += raw;
     assertNoDoctype2(file.name, content);
   }
 }
@@ -3256,10 +3906,7 @@ function judge(row, sourceEntry, adapter) {
   if (contentHash(sourceEntry) !== row.sourceHash) {
     return "drift";
   }
-  const integrity = checkPlaceholders(
-    sourceEntry.placeholders,
-    adapter.extractPlaceholders(row.translation)
-  );
+  const integrity = adapter.comparePlaceholders !== void 0 ? adapter.comparePlaceholders(sourceEntry.value, row.translation) : checkPlaceholders(sourceEntry.placeholders, adapter.extractPlaceholders(row.translation));
   if (!integrity.matches) {
     return "placeholder";
   }
@@ -3459,6 +4106,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. */
@@ -3575,6 +4229,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;
@@ -3582,6 +4237,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;