@verbatra/sdk 0.5.0-next.0 → 0.5.0-next.2

package/dist/index.js

@@ -11,9 +11,9 @@ import { createRequire } from 'module';
 import log from 'loglevel';
 import { GoogleGenAI } from '@google/genai';
 import OpenAI from 'openai';
-import { parse as parse$1, TYPE } from '@formatjs/icu-messageformat-parser';
+import { parse, TYPE } from '@formatjs/icu-messageformat-parser';
 import { XMLSerializer, DOMParser } from '@xmldom/xmldom';
-import { stringify, parse } from 'yaml';
+import { stringify, parse as parse$1 } from 'yaml';
 import ExcelJS from 'exceljs';
 import { Readable } from 'stream';
 import JSZip from 'jszip';
@@ -311,6 +311,85 @@ var LOCALE_TOKEN = "{locale}";
 function localeFilePath(cwd, pattern, locale) {
   return 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.
@@ -345,17 +424,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;
 }
@@ -377,16 +473,14 @@ function validateRequest(request) {
   return parsed.data;
 }
 function toIntegrityInputs(entries, values) {
-  return entries.map((entry) => {
+  const inputs = [];
+  for (const entry of entries) {
     const translatedValue = values.get(entry.key);
-    if (translatedValue === void 0) {
-      throw new ProviderError(
-        "INVALID_RESPONSE",
-        "The provider response is missing one or more keys."
-      );
+    if (translatedValue !== void 0) {
+      inputs.push({ key: entry.key, sourceValue: entry.value, translatedValue });
     }
-    return { key: entry.key, sourcePlaceholders: entry.placeholders, translatedValue };
-  });
+  }
+  return inputs;
 }
 function toItem(entry) {
   return {
@@ -418,25 +512,29 @@ function deriveJsonSchema(schema) {
   }
   return result;
 }
-function reconcile(translations, requestedKeys) {
-  const requested = new Set(requestedKeys);
-  const values = /* @__PURE__ */ new Map();
+function partitionTranslations(translations, requested) {
+  const firstSeen = /* @__PURE__ */ new Map();
+  const duplicated = /* @__PURE__ */ new Set();
   for (const { key, value } of translations) {
-    if (!requested.has(key) || values.has(key)) {
-      throw new ProviderError(
-        "INVALID_RESPONSE",
-        "The provider returned an unexpected or duplicate key."
-      );
+    if (!requested.has(key)) {
+      throw new ProviderError("INVALID_RESPONSE", "The provider returned an unexpected key.");
+    }
+    if (firstSeen.has(key)) {
+      duplicated.add(key);
+      continue;
     }
-    values.set(key, value);
+    firstSeen.set(key, value);
   }
-  if (values.size !== requested.size) {
-    throw new ProviderError(
-      "INVALID_RESPONSE",
-      "The provider response is missing one or more keys."
-    );
+  return { firstSeen, duplicated };
+}
+function reconcile(translations, requestedKeys) {
+  const requested = new Set(requestedKeys);
+  const { firstSeen, duplicated } = partitionTranslations(translations, requested);
+  const missingKeys = requestedKeys.filter((key) => duplicated.has(key) || !firstSeen.has(key));
+  for (const key of duplicated) {
+    firstSeen.delete(key);
   }
-  return values;
+  return { accepted: firstSeen, missingKeys };
 }
 function reconcileResult(raw, requestedKeys) {
   const parsed = translationsResultSchema.safeParse(raw);
@@ -448,17 +546,54 @@ function reconcileResult(raw, requestedKeys) {
   }
   return reconcile(parsed.data.translations, requestedKeys);
 }
+var MAX_REPAIR_ROUNDS = 1;
 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 values = reconcileResult(completion.raw, requestedKeys);
+  const signal = request.signal;
+  const first = await requestTranslations(mechanism, data, signal);
+  const values = first.outcome.accepted;
+  let usage = first.completion.usage;
+  let toRepair = entriesFor(data.entries, first.outcome.missingKeys);
+  for (let round = 0; round < MAX_REPAIR_ROUNDS && toRepair.length > 0; round += 1) {
+    const repair = await requestTranslations(mechanism, { ...data, entries: toRepair }, signal);
+    for (const [key, value] of repair.outcome.accepted) {
+      values.set(key, value);
+    }
+    usage = mergeUsage(usage, repair.completion.usage);
+    toRepair = entriesFor(data.entries, repair.outcome.missingKeys);
+  }
   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 };
+  return usage === void 0 ? { values, integrity, notices: [] } : { values, integrity, usage, notices: [] };
+}
+async function requestTranslations(mechanism, data, signal) {
+  const payloadJson = JSON.stringify(buildDataPayload(data));
+  const requestedKeys = data.entries.map((entry) => entry.key);
+  const completion = await mechanism.translate({
+    payloadJson,
+    requestedKeys,
+    ...signal !== void 0 ? { signal } : {}
+  });
+  return { completion, outcome: reconcileResult(completion.raw, requestedKeys) };
+}
+function entriesFor(entries, keys) {
+  const wanted = new Set(keys);
+  return entries.filter((entry) => wanted.has(entry.key));
+}
+function mergeUsage(first, second) {
+  if (first === void 0) {
+    return second;
+  }
+  if (second === void 0) {
+    return first;
+  }
+  return {
+    inputTokens: first.inputTokens + second.inputTokens,
+    outputTokens: first.outputTokens + second.outputTokens
+  };
 }
 var OUTPUT_TRUNCATED_MESSAGE = "The provider stopped because the output-token limit was reached. Reduce the batch size or raise the configured max output tokens.";
 function assertNotTruncated(truncated) {
@@ -491,12 +626,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({ apiKey: requireAnthropicKey(), logLevel: "off" });
   return {
     messages: {
-      create: async (body) => await sdk.messages.create(
-        body
+      create: async (body, options) => await sdk.messages.create(
+        body,
+        options
       )
     }
   };
@@ -564,9 +716,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);
@@ -574,8 +726,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) {
@@ -670,7 +825,7 @@ function zipResults(entries, results) {
     values.set(entry.key, translatedValue);
     integrityInputs.push({
       key: entry.key,
-      sourcePlaceholders: entry.placeholders,
+      sourceValue: entry.value,
       translatedValue
     });
   }
@@ -686,7 +841,10 @@ function createDeepLProvider(config, deps = {}) {
   return {
     id: PROVIDER_ID2,
     kind: "machine-translation",
-    supportsGlossary: true,
+    // 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)
   };
 }
@@ -711,36 +869,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 = z.object({
   model: z.string().min(1),
   maxOutputTokens: 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 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
       )
     }
   };
@@ -804,7 +1023,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 }] }],
@@ -812,7 +1031,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 } : {}
     }
   };
 }
@@ -876,15 +1096,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 = z.object({
   model: z.string().min(1),
@@ -895,8 +1115,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
         )
       }
     }
@@ -914,27 +1135,90 @@ 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 {
-    model: config.model,
-    max_completion_tokens: config.maxOutputTokens,
+    type: "json_schema",
+    json_schema: {
+      name: RESULT_SCHEMA_NAME,
+      strict: true,
+      schema: deriveJsonSchema(translationsResultSchema)
+    }
+  };
+}
+function buildOpenAiRequest(config, payloadJson, mode = "strict-schema", tokenLimitField = "max_completion_tokens") {
+  const base = {
     messages: [
       { 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)
+    model: config.model,
+    response_format: buildResponseFormat(mode)
+  };
+  if (tokenLimitField === "max_tokens") {
+    return { ...base, max_tokens: config.maxOutputTokens };
+  }
+  return { ...base, max_completion_tokens: config.maxOutputTokens };
+}
+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 parseContent2(content) {
+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, 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.");
   }
@@ -949,7 +1233,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.");
@@ -962,7 +1246,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 };
 }
@@ -980,15 +1264,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 = z.object({
+  baseUrl: z.url({ message: "baseUrl must be a valid absolute URL." }).refine(isHttpOrHttpsUrl, { message: "baseUrl must use the http or https scheme." }),
+  model: z.string().min(1),
+  maxOutputTokens: z.number().int().positive(),
+  apiKeyEnvVar: 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({
+    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", "max_tokens");
+      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",
@@ -999,13 +1352,18 @@ var providerConfigSchema = z.discriminatedUnion("id", [
   z.object({ id: z.literal("anthropic"), options: anthropicConfigSchema.strict() }),
   z.object({ id: z.literal("openai"), options: openAiConfigSchema.strict() }),
   z.object({ id: z.literal("gemini"), options: geminiConfigSchema.strict() }),
-  z.object({ id: z.literal("deepl"), options: deepLConfigSchema.strict() })
+  z.object({ id: z.literal("deepl"), options: deepLConfigSchema.strict() }),
+  z.object({
+    id: 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];
@@ -1184,6 +1542,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) {
@@ -1289,7 +1653,7 @@ function analyzeIcuValue(value) {
     return VALID_EMPTY;
   }
   try {
-    const ast = parse$1(value);
+    const ast = parse(value);
     const state = { isPlural: false };
     const multiset = collect(ast, state);
     return { placeholders: flatten(multiset), isPlural: state.isPlural, valid: true };
@@ -1316,6 +1680,150 @@ function icuInvalidKeys(entries) {
   }
   return invalid;
 }
+function tokenOf2(element) {
+  switch (element.type) {
+    case TYPE.argument:
+    case TYPE.number:
+    case TYPE.date:
+    case TYPE.time:
+    case TYPE.select:
+    case TYPE.plural:
+      return `{${element.value}}`;
+    case TYPE.tag:
+      return `<${element.value}>`;
+    default:
+      return void 0;
+  }
+}
+function isBranching(element) {
+  return element.type === TYPE.plural || element.type === TYPE.select;
+}
+function isTag(element) {
+  return element.type === 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 = parse(sourceValue);
+    const targetAst = parse(targetValue);
+    return compareElements(sourceAst, targetAst);
+  } catch {
+    return checkPlaceholders(icuPlaceholders(sourceValue), icuPlaceholders(targetValue));
+  }
+}
 var AdapterError = class extends Error {
   code;
   constructor(code, message) {
@@ -1424,6 +1932,9 @@ async function atomicWriteFile(path, data, ops = nodeOps) {
     throw error;
   }
 }
+function stripLeadingBom(content) {
+  return content.charCodeAt(0) === 65279 ? content.slice(1) : content;
+}
 async function readBoundedUtf82(handle, size) {
   const buffer = Buffer.allocUnsafe(size);
   let offset = 0;
@@ -1434,7 +1945,7 @@ async function readBoundedUtf82(handle, size) {
     }
     offset += bytesRead;
   }
-  return buffer.toString("utf8", 0, offset);
+  return stripLeadingBom(buffer.toString("utf8", 0, offset));
 }
 async function readBounded2(filePath) {
   const handle = await open(filePath, "r");
@@ -1617,9 +2128,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) {
@@ -1631,7 +2142,7 @@ function createTreeFileAdapter(options) {
     format,
     extensions,
     sniff,
-    parse: parse2,
+    parse: parse3,
     serialize,
     deriveEntry,
     extractPlaceholders,
@@ -1639,6 +2150,7 @@ function createTreeFileAdapter(options) {
     validateMessage,
     validateTree,
     buildWriteTree,
+    comparePlaceholders,
     keyMode = "literal-leaf"
   } = options;
   return {
@@ -1646,10 +2158,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 };
@@ -1745,6 +2258,7 @@ function createArbAdapter() {
     deriveEntry: icuDeriveEntry,
     computeInvalidIcuKeys: icuInvalidKeys,
     validateMessage: icuIsValid,
+    comparePlaceholders: compareIcuPlaceholders,
     buildWriteTree: buildArbWriteTree
   });
 }
@@ -1808,7 +2322,8 @@ function createNextIntlJsonAdapter() {
     extractPlaceholders: icuPlaceholders,
     deriveEntry: icuDeriveEntry,
     computeInvalidIcuKeys: icuInvalidKeys,
-    validateMessage: icuIsValid
+    validateMessage: icuIsValid,
+    comparePlaceholders: compareIcuPlaceholders
   });
 }
 function assertNoDottedNestedKey(tree) {
@@ -2010,6 +2525,7 @@ function extractXliffPlaceholders(value) {
   return result;
 }
 var ELEMENT_NODE = 1;
+var TEXT_NODE = 3;
 function isElement(node) {
   return node.nodeType === ELEMENT_NODE;
 }
@@ -2100,6 +2616,12 @@ function parseXliffEntries(content, namespace) {
   const serializer = new 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,
@@ -2126,10 +2648,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;
   }
@@ -2179,7 +2758,7 @@ function createXliffAdapter() {
 function parseYamlObject(content) {
   let parsed;
   try {
-    parsed = parse(content, { maxAliasCount: 100 });
+    parsed = parse$1(content, { maxAliasCount: 100 });
   } catch {
     throw new AdapterError("INVALID_YAML", "The file is not valid YAML.");
   }
@@ -2409,15 +2988,8 @@ function subBatchFailedNotice(count, error) {
 }
 
 // src/flow/notices.ts
-function isNotice(value) {
-  return typeof value === "object" && value !== null && typeof value.code === "string" && typeof value.message === "string";
-}
 function readNotices(result) {
-  const candidate = result.notices;
-  if (!Array.isArray(candidate)) {
-    return [];
-  }
-  return candidate.filter(isNotice);
+  return result.notices ?? [];
 }
 
 // src/flow/plural-categories.ts
@@ -2583,7 +3155,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) {
@@ -2620,20 +3193,26 @@ async function runGenerationSubBatch(context, batch, accepted, withheld, provide
     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) {
-      accepted.push({
-        targetKey: item.targetKey,
-        entry: { ...syntheticEntry(item), value },
-        lockHash: generatedLockHash(item.governingEntries, item.category)
-      });
-    } else {
-      withheld.push(item.targetKey);
-    }
+    foldGenerationItem(item, result, accepted, withheld, providerFailures);
   }
   return readNotices(result);
 }
+function foldGenerationItem(item, result, 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) {
+    accepted.push({
+      targetKey: item.targetKey,
+      entry: { ...syntheticEntry(item), value },
+      lockHash: generatedLockHash(item.governingEntries, item.category)
+    });
+  } else {
+    withheld.push(item.targetKey);
+  }
+}
 
 // src/flow/locale-run.ts
 function emptyResource(locale, format) {
@@ -2653,7 +3232,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) {
@@ -2820,16 +3400,22 @@ async function runSubBatch(provider, params, batch, accepted, integrityMismatche
     return [subBatchFailedNotice(batch.length, error)];
   }
   for (const entry of batch) {
-    const value = result.values.get(entry.key);
-    const integrity = result.integrity.get(entry.key);
-    if (value !== void 0 && integrity?.matches === true) {
-      accepted.set(entry.key, { value, source: entry });
-    } else {
-      integrityMismatches.push(entry.key);
-    }
+    foldEntryResult(entry, result, accepted, integrityMismatches, providerFailures);
   }
   return readNotices(result);
 }
+function foldEntryResult(entry, result, 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) {
+    accepted.set(entry.key, { value, source: entry });
+  } else {
+    integrityMismatches.push(entry.key);
+  }
+}
 function computeLockEntries(params, merged, withheld, generated) {
   const lockEntries = {};
   const sourceBaseKeys = sourcePluralBaseKeys(params.source);
@@ -3116,7 +3702,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;
@@ -3148,14 +3734,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);
   }
 }
@@ -3344,10 +3924,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";
   }