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

package/dist/index.d.cts

@@ -36,7 +36,7 @@ type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
  * Result of comparing source placeholders against translated-output placeholders as MULTISETS
  * (counts matter). Always returned (never thrown) for an ordinary mismatch.
  */
-interface PlaceholderIntegrityResult {
+interface PlaceholderIntegrityResult$1 {
     /** True when nothing is missing or extra: the multisets match, regardless of order. */
     readonly matches: boolean;
     /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
@@ -57,6 +57,13 @@ type Tone = "formal" | "informal" | "neutral";
  * derives placeholders itself.
  */
 type PlaceholderExtractor = (value: string) => readonly string[];
+/**
+ * Compares a source and translated value's placeholders directly, branch-aware, instead of
+ * independently extracting each side's flat placeholder list first. Supplied by the caller (the SDK, for
+ * a format whose adapter defines one, for example ICU plural/select) so it matches the entries' format;
+ * ai-providers never derives it itself and never parses a specific format's message syntax.
+ */
+type PlaceholderComparator = (source: string, translated: string) => PlaceholderIntegrityResult$1;
 /**
  * A batch translation request. Format- and provider-neutral: it carries no prompt,
  * model, key, or other provider-specific field. The placeholder extractor is
@@ -75,20 +82,62 @@ interface TranslateRequest {
     readonly tone?: Tone;
     /** Mandatory placeholder extractor; the output integrity check runs against it. */
     readonly extractPlaceholders: PlaceholderExtractor;
+    /**
+     * Optional branch-aware placeholder comparator. When present, the output integrity check uses it
+     * instead of independently extracting each side's placeholders with {@link extractPlaceholders} and
+     * diffing the flat lists. Absent for a format with no plural/select sub-message structure.
+     */
+    readonly comparePlaceholders?: PlaceholderComparator;
+    /**
+     * Optional cancellation signal for this batch. When aborted, an in-flight provider call rejects
+     * with the abort, unwrapped, instead of a {@link ProviderError} (see `guardProviderCall`). Not a
+     * plain-data field: it is never validated by `requestDataSchema` and never sent to a provider.
+     */
+    readonly signal?: AbortSignal;
 }
 /** Token usage, when the provider reports it. Absent for providers without tokens (DeepL). */
 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>;
     /** The placeholder-integrity outcome for each key (source vs translated placeholder sets). */
-    readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult>;
+    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
@@ -147,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
@@ -187,8 +214,9 @@ type OpenAiModel = OpenAI.ChatModel;
 
 /**
  * The provider section of the config: a discriminated union over the provider id, reusing each
- * provider's own config schema. There is no key field anywhere in this union; the provider reads its
- * API key from the environment at construction.
+ * provider's own config schema. There is no key field anywhere in this union except
+ * openai-compatible's optional `apiKeyEnvVar`, which names an environment variable rather than carrying
+ * a key value; every provider still reads its actual key from the environment at construction.
  */
 declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodLiteral<"anthropic">;
@@ -213,6 +241,14 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     options: z.ZodObject<{
         glossaryId: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"openai-compatible">;
+    options: z.ZodObject<{
+        baseUrl: z.ZodURL;
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+        apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
 }, z.core.$strip>], "id">;
 type ProviderConfig = z.infer<typeof providerConfigSchema>;
 type ProviderId = ProviderConfig["id"];
@@ -260,6 +296,14 @@ declare const verbatraConfigSchema: z.ZodObject<{
         options: z.ZodObject<{
             glossaryId: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodLiteral<"openai-compatible">;
+        options: z.ZodObject<{
+            baseUrl: z.ZodURL;
+            model: z.ZodString;
+            maxOutputTokens: z.ZodNumber;
+            apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
     }, z.core.$strip>], "id">;
     glossary: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodString>, z.ZodString]>>;
     tone: z.ZodOptional<z.ZodEnum<{
@@ -307,6 +351,9 @@ type AuthoringProviderVariant = {
     deepl: Extract<ProviderConfig, {
         id: "deepl";
     }>;
+    "openai-compatible": Extract<ProviderConfig, {
+        id: "openai-compatible";
+    }>;
 };
 /**
  * The authoring view of the whole config for a provider id: a {@link VerbatraConfigInput} whose
@@ -495,7 +542,8 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  * - `SOURCE_UNREADABLE`: the source locale file is absent (thrown by `translate`, and by `watch` at startup).
  * - `SOURCE_INVALID`: the source locale file could not be read or parsed; wraps the adapter read error
  *   (thrown by `translate`).
- * - `LOCK_FILE_INVALID`: the lock-file is present but corrupt or oversized (thrown by `translate`).
+ * - `LOCK_FILE_INVALID`: the lock-file is present but corrupt, oversized, or at an unsupported
+ *   version (thrown by `translate`, `check`, `diff`, `exportWorkbook`, and `importWorkbook`).
  * - `LOCALE_FAILED` (NOT thrown): the fallback `code` recorded on a failed `LocaleSummary` when a
  *   per-locale failure carries no string code of its own. See the surfaced-not-thrown distinction on
  *   `translate`.
@@ -552,6 +600,21 @@ interface LocaleResource {
     readonly entries: ReadonlyMap<string, TranslationEntry>;
 }
 
+/**
+ * Result of comparing source placeholders against translated-output placeholders as MULTISETS
+ * (counts matter). Always returned (never thrown) for an ordinary mismatch.
+ */
+interface PlaceholderIntegrityResult {
+    /** True when nothing is missing or extra: the multisets match, regardless of order. */
+    readonly matches: boolean;
+    /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
+    readonly missing: readonly string[];
+    /** Occurrences present in the translation but absent from source, one per surplus occurrence. Sorted. */
+    readonly extra: readonly string[];
+    /** Same multiset present in both, but in a different order. */
+    readonly reordered: boolean;
+}
+
 /**
  * The result of reading a file into core's intermediate representation.
  */
@@ -628,6 +691,18 @@ interface FormatAdapter {
      *   unparseable value returns false.
      */
     validateMessage(value: string): boolean;
+    /**
+     * Optional branch-aware placeholder comparison for formats with plural/select sub-message structure.
+     * When present, callers use it instead of independently extracting each side's placeholders with
+     * {@link extractPlaceholders} and diffing the flat lists, since flattening a plural/select value loses
+     * which branch a placeholder came from. Absent for every non-ICU adapter, which is compared via
+     * `extractPlaceholders` plus `checkPlaceholders` as before.
+     *
+     * @param sourceValue - The source value.
+     * @param targetValue - The translated value to check against it.
+     * @returns The merged placeholder-integrity result across every branch. Does not throw.
+     */
+    comparePlaceholders?(sourceValue: string, targetValue: string): PlaceholderIntegrityResult;
 }
 
 /** Outcome of resolving an adapter for a file. Structured; never throws. */
@@ -876,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[];
     /**
@@ -1108,13 +1185,24 @@ interface LoadLockFileDeps {
  * @param input - The directory the lock-file resolves against.
  * @param deps - Optional composition seam (file system) for tests.
  * @returns The parsed lock-file, or an empty lock when none exists yet.
- * @throws {@link SdkError} `LOCK_FILE_INVALID` when the lock-file is present but corrupt or oversized.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID` when the lock-file is present but corrupt, oversized,
+ * or at an unsupported version.
  */
 declare function loadLockFile(input?: LoadLockFileInput, deps?: LoadLockFileDeps): Promise<LockFile>;
 
 /** The committed lock-file name, chosen to be obviously JSON and to not match a `*.lock` ignore rule. */
 declare const LOCK_FILE_NAME = "verbatra.lock.json";
 
+/**
+ * The subset of {@link ProviderId} that `init` can scaffold: every provider with a single required
+ * environment variable. "openai-compatible" is deliberately excluded: unlike every other provider it
+ * has no single required environment variable, only a three-tier
+ * apiKeyEnvVar/OPENAI_COMPATIBLE_API_KEY/placeholder fallback (see resolveOpenAiCompatibleKey in
+ * @verbatra/ai-providers), so it does not fit the `providerEnv` table below and `init` scaffolding does
+ * not offer it. This is the single source of truth for the exclusion; other packages import this type
+ * rather than re-deriving `Exclude<ProviderId, "openai-compatible">` themselves.
+ */
+type ScaffoldableProviderId = Exclude<ProviderId, "openai-compatible">;
 /**
  * Read-only metadata the CLI `init` scaffold derives its tables from, so the CLI never restates the
  * provider, env-var, model, or format truth owned by core and ai-providers.
@@ -1229,4 +1317,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
+export { type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };

package/dist/index.d.ts

@@ -36,7 +36,7 @@ type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
  * Result of comparing source placeholders against translated-output placeholders as MULTISETS
  * (counts matter). Always returned (never thrown) for an ordinary mismatch.
  */
-interface PlaceholderIntegrityResult {
+interface PlaceholderIntegrityResult$1 {
     /** True when nothing is missing or extra: the multisets match, regardless of order. */
     readonly matches: boolean;
     /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
@@ -57,6 +57,13 @@ type Tone = "formal" | "informal" | "neutral";
  * derives placeholders itself.
  */
 type PlaceholderExtractor = (value: string) => readonly string[];
+/**
+ * Compares a source and translated value's placeholders directly, branch-aware, instead of
+ * independently extracting each side's flat placeholder list first. Supplied by the caller (the SDK, for
+ * a format whose adapter defines one, for example ICU plural/select) so it matches the entries' format;
+ * ai-providers never derives it itself and never parses a specific format's message syntax.
+ */
+type PlaceholderComparator = (source: string, translated: string) => PlaceholderIntegrityResult$1;
 /**
  * A batch translation request. Format- and provider-neutral: it carries no prompt,
  * model, key, or other provider-specific field. The placeholder extractor is
@@ -75,20 +82,62 @@ interface TranslateRequest {
     readonly tone?: Tone;
     /** Mandatory placeholder extractor; the output integrity check runs against it. */
     readonly extractPlaceholders: PlaceholderExtractor;
+    /**
+     * Optional branch-aware placeholder comparator. When present, the output integrity check uses it
+     * instead of independently extracting each side's placeholders with {@link extractPlaceholders} and
+     * diffing the flat lists. Absent for a format with no plural/select sub-message structure.
+     */
+    readonly comparePlaceholders?: PlaceholderComparator;
+    /**
+     * Optional cancellation signal for this batch. When aborted, an in-flight provider call rejects
+     * with the abort, unwrapped, instead of a {@link ProviderError} (see `guardProviderCall`). Not a
+     * plain-data field: it is never validated by `requestDataSchema` and never sent to a provider.
+     */
+    readonly signal?: AbortSignal;
 }
 /** Token usage, when the provider reports it. Absent for providers without tokens (DeepL). */
 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>;
     /** The placeholder-integrity outcome for each key (source vs translated placeholder sets). */
-    readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult>;
+    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
@@ -147,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
@@ -187,8 +214,9 @@ type OpenAiModel = OpenAI.ChatModel;
 
 /**
  * The provider section of the config: a discriminated union over the provider id, reusing each
- * provider's own config schema. There is no key field anywhere in this union; the provider reads its
- * API key from the environment at construction.
+ * provider's own config schema. There is no key field anywhere in this union except
+ * openai-compatible's optional `apiKeyEnvVar`, which names an environment variable rather than carrying
+ * a key value; every provider still reads its actual key from the environment at construction.
  */
 declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodLiteral<"anthropic">;
@@ -213,6 +241,14 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     options: z.ZodObject<{
         glossaryId: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"openai-compatible">;
+    options: z.ZodObject<{
+        baseUrl: z.ZodURL;
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+        apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
 }, z.core.$strip>], "id">;
 type ProviderConfig = z.infer<typeof providerConfigSchema>;
 type ProviderId = ProviderConfig["id"];
@@ -260,6 +296,14 @@ declare const verbatraConfigSchema: z.ZodObject<{
         options: z.ZodObject<{
             glossaryId: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodLiteral<"openai-compatible">;
+        options: z.ZodObject<{
+            baseUrl: z.ZodURL;
+            model: z.ZodString;
+            maxOutputTokens: z.ZodNumber;
+            apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
     }, z.core.$strip>], "id">;
     glossary: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodString>, z.ZodString]>>;
     tone: z.ZodOptional<z.ZodEnum<{
@@ -307,6 +351,9 @@ type AuthoringProviderVariant = {
     deepl: Extract<ProviderConfig, {
         id: "deepl";
     }>;
+    "openai-compatible": Extract<ProviderConfig, {
+        id: "openai-compatible";
+    }>;
 };
 /**
  * The authoring view of the whole config for a provider id: a {@link VerbatraConfigInput} whose
@@ -495,7 +542,8 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  * - `SOURCE_UNREADABLE`: the source locale file is absent (thrown by `translate`, and by `watch` at startup).
  * - `SOURCE_INVALID`: the source locale file could not be read or parsed; wraps the adapter read error
  *   (thrown by `translate`).
- * - `LOCK_FILE_INVALID`: the lock-file is present but corrupt or oversized (thrown by `translate`).
+ * - `LOCK_FILE_INVALID`: the lock-file is present but corrupt, oversized, or at an unsupported
+ *   version (thrown by `translate`, `check`, `diff`, `exportWorkbook`, and `importWorkbook`).
  * - `LOCALE_FAILED` (NOT thrown): the fallback `code` recorded on a failed `LocaleSummary` when a
  *   per-locale failure carries no string code of its own. See the surfaced-not-thrown distinction on
  *   `translate`.
@@ -552,6 +600,21 @@ interface LocaleResource {
     readonly entries: ReadonlyMap<string, TranslationEntry>;
 }
 
+/**
+ * Result of comparing source placeholders against translated-output placeholders as MULTISETS
+ * (counts matter). Always returned (never thrown) for an ordinary mismatch.
+ */
+interface PlaceholderIntegrityResult {
+    /** True when nothing is missing or extra: the multisets match, regardless of order. */
+    readonly matches: boolean;
+    /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
+    readonly missing: readonly string[];
+    /** Occurrences present in the translation but absent from source, one per surplus occurrence. Sorted. */
+    readonly extra: readonly string[];
+    /** Same multiset present in both, but in a different order. */
+    readonly reordered: boolean;
+}
+
 /**
  * The result of reading a file into core's intermediate representation.
  */
@@ -628,6 +691,18 @@ interface FormatAdapter {
      *   unparseable value returns false.
      */
     validateMessage(value: string): boolean;
+    /**
+     * Optional branch-aware placeholder comparison for formats with plural/select sub-message structure.
+     * When present, callers use it instead of independently extracting each side's placeholders with
+     * {@link extractPlaceholders} and diffing the flat lists, since flattening a plural/select value loses
+     * which branch a placeholder came from. Absent for every non-ICU adapter, which is compared via
+     * `extractPlaceholders` plus `checkPlaceholders` as before.
+     *
+     * @param sourceValue - The source value.
+     * @param targetValue - The translated value to check against it.
+     * @returns The merged placeholder-integrity result across every branch. Does not throw.
+     */
+    comparePlaceholders?(sourceValue: string, targetValue: string): PlaceholderIntegrityResult;
 }
 
 /** Outcome of resolving an adapter for a file. Structured; never throws. */
@@ -876,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[];
     /**
@@ -1108,13 +1185,24 @@ interface LoadLockFileDeps {
  * @param input - The directory the lock-file resolves against.
  * @param deps - Optional composition seam (file system) for tests.
  * @returns The parsed lock-file, or an empty lock when none exists yet.
- * @throws {@link SdkError} `LOCK_FILE_INVALID` when the lock-file is present but corrupt or oversized.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID` when the lock-file is present but corrupt, oversized,
+ * or at an unsupported version.
  */
 declare function loadLockFile(input?: LoadLockFileInput, deps?: LoadLockFileDeps): Promise<LockFile>;
 
 /** The committed lock-file name, chosen to be obviously JSON and to not match a `*.lock` ignore rule. */
 declare const LOCK_FILE_NAME = "verbatra.lock.json";
 
+/**
+ * The subset of {@link ProviderId} that `init` can scaffold: every provider with a single required
+ * environment variable. "openai-compatible" is deliberately excluded: unlike every other provider it
+ * has no single required environment variable, only a three-tier
+ * apiKeyEnvVar/OPENAI_COMPATIBLE_API_KEY/placeholder fallback (see resolveOpenAiCompatibleKey in
+ * @verbatra/ai-providers), so it does not fit the `providerEnv` table below and `init` scaffolding does
+ * not offer it. This is the single source of truth for the exclusion; other packages import this type
+ * rather than re-deriving `Exclude<ProviderId, "openai-compatible">` themselves.
+ */
+type ScaffoldableProviderId = Exclude<ProviderId, "openai-compatible">;
 /**
  * Read-only metadata the CLI `init` scaffold derives its tables from, so the CLI never restates the
  * provider, env-var, model, or format truth owned by core and ai-providers.
@@ -1229,4 +1317,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
+export { type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };