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

package/dist/index.d.cts

@@ -100,7 +100,31 @@ interface Usage {
     readonly inputTokens: number;
     readonly outputTokens: number;
 }
-/** Result of a batch translation: per-key values and per-key integrity outcomes. */
+/**
+ * Stable codes for a provider's graceful-degradation notices. These are returned DATA on a
+ * successful result, NOT thrown:
+ *
+ * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (DeepL's free tier does not
+ *   support it).
+ * - `GLOSSARY_IGNORED`: a supplied generic glossary term map was not applied (DeepL only applies a
+ *   native glossary id, never a term map).
+ * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
+ *   because the provider cannot preserve those tokens; such entries are withheld (absent from the
+ *   result maps) rather than sent to the provider and mangled.
+ */
+type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED" | "PLACEHOLDER_UNSUPPORTED";
+/**
+ * An observable, structured signal that something was gracefully degraded (not an
+ * error). Carries only a stable code and a static message, never a key or content.
+ * Surfaced as result data, never thrown; callers inspect it but need not treat it as a failure.
+ */
+interface ProviderNotice {
+    /** The stable {@link ProviderNoticeCode} for what was degraded. */
+    readonly code: ProviderNoticeCode;
+    /** A static, safe description; never a key or translatable content. */
+    readonly message: string;
+}
+/** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
 interface TranslateResult {
     /** The translated value for each requested key. */
     readonly values: ReadonlyMap<string, string>;
@@ -108,6 +132,12 @@ interface TranslateResult {
     readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult$1>;
     /** Token usage when the provider reports it; absent for token-less providers. */
     readonly usage?: Usage;
+    /**
+     * Graceful-degradation notices for this batch. Every provider populates this as a present array:
+     * DeepL reports real notices (for example `GLOSSARY_IGNORED`); an LLM provider with nothing to
+     * report returns an empty array rather than omitting the field.
+     */
+    readonly notices?: readonly ProviderNotice[];
 }
 /**
  * The single contract every provider implements. It is narrow enough that a machine-translation API like
@@ -166,28 +196,6 @@ interface TranslationProvider {
  * are still accepted. This drives editor completions only; the runtime schema validates.
  */
 type AnthropicModel = Anthropic.Messages.Model;
-/**
- * Stable codes for the DeepL graceful-degradation notices, DeepL only. These are returned DATA on a
- * successful result, NOT thrown:
- *
- * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (the free tier does not support it).
- * - `GLOSSARY_IGNORED`: a supplied generic glossary was not applied.
- * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
- *   because DeepL cannot preserve those tokens; such entries are withheld (absent from the result maps)
- *   rather than sent to DeepL and mangled.
- */
-type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED" | "PLACEHOLDER_UNSUPPORTED";
-/**
- * An observable, structured signal that something was gracefully degraded (not an
- * error). Carries only a stable code and a static message, never a key or content.
- * Surfaced as result data, never thrown; callers inspect it but need not treat it as a failure.
- */
-interface ProviderNotice {
-    /** The stable {@link ProviderNoticeCode} for what was degraded. */
-    readonly code: ProviderNoticeCode;
-    /** A static, safe description; never a key or translatable content. */
-    readonly message: string;
-}
 
 /**
  * The Gemini authoring model type, sourced from the installed SDK's own model union so
@@ -943,11 +951,13 @@ interface LocaleSummary {
      */
     readonly integrityMismatches: readonly string[];
     /**
-     * Keys withheld because the provider call itself failed (for example a revoked API key, a rate
-     * limit, or a network timeout), as distinct from a translation that came back and failed the
-     * placeholder-integrity check. Nothing was translated for these keys. The corresponding
-     * {@link LocaleSummary.notices} entry carries the secret-free failure code and message. Empty in a
-     * dry-run and empty unless a provider call threw.
+     * Keys withheld because nothing was translated for them this run, as distinct from a translation
+     * that came back and failed the placeholder-integrity check. This covers two causes: the provider
+     * call itself failed (for example a revoked API key, a rate limit, or a network timeout), in which
+     * case the corresponding {@link LocaleSummary.notices} entry carries the secret-free failure code
+     * and message; or the call succeeded but the key was still missing or duplicated in the response
+     * after the shared LLM layer's bounded reconcile repair round, in which case no notice is added.
+     * Empty in a dry-run.
      */
     readonly providerFailures: readonly string[];
     /**

package/dist/index.d.ts

@@ -100,7 +100,31 @@ interface Usage {
     readonly inputTokens: number;
     readonly outputTokens: number;
 }
-/** Result of a batch translation: per-key values and per-key integrity outcomes. */
+/**
+ * Stable codes for a provider's graceful-degradation notices. These are returned DATA on a
+ * successful result, NOT thrown:
+ *
+ * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (DeepL's free tier does not
+ *   support it).
+ * - `GLOSSARY_IGNORED`: a supplied generic glossary term map was not applied (DeepL only applies a
+ *   native glossary id, never a term map).
+ * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
+ *   because the provider cannot preserve those tokens; such entries are withheld (absent from the
+ *   result maps) rather than sent to the provider and mangled.
+ */
+type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED" | "PLACEHOLDER_UNSUPPORTED";
+/**
+ * An observable, structured signal that something was gracefully degraded (not an
+ * error). Carries only a stable code and a static message, never a key or content.
+ * Surfaced as result data, never thrown; callers inspect it but need not treat it as a failure.
+ */
+interface ProviderNotice {
+    /** The stable {@link ProviderNoticeCode} for what was degraded. */
+    readonly code: ProviderNoticeCode;
+    /** A static, safe description; never a key or translatable content. */
+    readonly message: string;
+}
+/** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
 interface TranslateResult {
     /** The translated value for each requested key. */
     readonly values: ReadonlyMap<string, string>;
@@ -108,6 +132,12 @@ interface TranslateResult {
     readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult$1>;
     /** Token usage when the provider reports it; absent for token-less providers. */
     readonly usage?: Usage;
+    /**
+     * Graceful-degradation notices for this batch. Every provider populates this as a present array:
+     * DeepL reports real notices (for example `GLOSSARY_IGNORED`); an LLM provider with nothing to
+     * report returns an empty array rather than omitting the field.
+     */
+    readonly notices?: readonly ProviderNotice[];
 }
 /**
  * The single contract every provider implements. It is narrow enough that a machine-translation API like
@@ -166,28 +196,6 @@ interface TranslationProvider {
  * are still accepted. This drives editor completions only; the runtime schema validates.
  */
 type AnthropicModel = Anthropic.Messages.Model;
-/**
- * Stable codes for the DeepL graceful-degradation notices, DeepL only. These are returned DATA on a
- * successful result, NOT thrown:
- *
- * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (the free tier does not support it).
- * - `GLOSSARY_IGNORED`: a supplied generic glossary was not applied.
- * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
- *   because DeepL cannot preserve those tokens; such entries are withheld (absent from the result maps)
- *   rather than sent to DeepL and mangled.
- */
-type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED" | "PLACEHOLDER_UNSUPPORTED";
-/**
- * An observable, structured signal that something was gracefully degraded (not an
- * error). Carries only a stable code and a static message, never a key or content.
- * Surfaced as result data, never thrown; callers inspect it but need not treat it as a failure.
- */
-interface ProviderNotice {
-    /** The stable {@link ProviderNoticeCode} for what was degraded. */
-    readonly code: ProviderNoticeCode;
-    /** A static, safe description; never a key or translatable content. */
-    readonly message: string;
-}
 
 /**
  * The Gemini authoring model type, sourced from the installed SDK's own model union so
@@ -943,11 +951,13 @@ interface LocaleSummary {
      */
     readonly integrityMismatches: readonly string[];
     /**
-     * Keys withheld because the provider call itself failed (for example a revoked API key, a rate
-     * limit, or a network timeout), as distinct from a translation that came back and failed the
-     * placeholder-integrity check. Nothing was translated for these keys. The corresponding
-     * {@link LocaleSummary.notices} entry carries the secret-free failure code and message. Empty in a
-     * dry-run and empty unless a provider call threw.
+     * Keys withheld because nothing was translated for them this run, as distinct from a translation
+     * that came back and failed the placeholder-integrity check. This covers two causes: the provider
+     * call itself failed (for example a revoked API key, a rate limit, or a network timeout), in which
+     * case the corresponding {@link LocaleSummary.notices} entry carries the secret-free failure code
+     * and message; or the call succeeded but the key was still missing or duplicated in the response
+     * after the shared LLM layer's bounded reconcile repair round, in which case no notice is added.
+     * Empty in a dry-run.
      */
     readonly providerFailures: readonly string[];
     /**

package/dist/index.js

@@ -473,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, sourceValue: entry.value, translatedValue };
-  });
+  }
+  return inputs;
 }
 function toItem(entry) {
   return {
@@ -514,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.");
     }
-    values.set(key, value);
+    if (firstSeen.has(key)) {
+      duplicated.add(key);
+      continue;
+    }
+    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);
@@ -544,22 +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 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.comparePlaceholders
+  );
+  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,
-    ...request.signal !== void 0 ? { signal: request.signal } : {}
+    ...signal !== void 0 ? { signal } : {}
   });
-  const values = reconcileResult(completion.raw, requestedKeys);
-  const integrity = checkBatchIntegrity(
-    toIntegrityInputs(data.entries, values),
-    request.extractPlaceholders,
-    request.comparePlaceholders
-  );
-  return completion.usage === void 0 ? { values, integrity } : { values, integrity, usage: completion.usage };
+  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) {
@@ -807,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)
   };
 }
@@ -1111,16 +1148,19 @@ function buildResponseFormat(mode) {
     }
   };
 }
-function buildOpenAiRequest(config, payloadJson, mode = "strict-schema") {
-  return {
-    model: config.model,
-    max_completion_tokens: config.maxOutputTokens,
+function buildOpenAiRequest(config, payloadJson, mode = "strict-schema", tokenLimitField = "max_completion_tokens") {
+  const base = {
     messages: [
       { role: "system", content: OPENAI_SYSTEM_RULES },
       { role: "user", content: payloadJson }
     ],
+    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) {
@@ -1291,7 +1331,7 @@ function createOpenAiCompatibleProvider(config, deps = {}) {
 function createMechanism4(client, config) {
   return {
     translate: async ({ payloadJson, signal }) => {
-      const body = buildOpenAiRequest(config, payloadJson, "strict-schema");
+      const body = buildOpenAiRequest(config, payloadJson, "strict-schema", "max_tokens");
       const completion = await callClient5(client, body, signal);
       return extractOpenAiResult(completion, true);
     }
@@ -1892,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;
@@ -1902,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");
@@ -2945,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
@@ -3157,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) {
@@ -3358,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);