@verbatra/sdk 0.4.4 → 0.5.0-next.1

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,6 +82,18 @@ 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 {
@@ -86,7 +105,7 @@ 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;
 }
@@ -187,8 +206,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 +233,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,8 +288,16 @@ 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.ZodRecord<z.ZodString, z.ZodString>>;
+    glossary: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodString>, z.ZodString]>>;
     tone: z.ZodOptional<z.ZodEnum<{
         formal: "formal";
         informal: "informal";
@@ -271,7 +307,22 @@ declare const verbatraConfigSchema: z.ZodObject<{
     generatePlurals: z.ZodOptional<z.ZodBoolean>;
     maxBatchSize: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
-type VerbatraConfig = z.infer<typeof verbatraConfigSchema>;
+/**
+ * The as-authored (or as-parsed) shape of the verbatra configuration, straight from the schema: `glossary`
+ * is still the union of an inline record or a file path. {@link defineConfig} and the authoring types are
+ * built on this; `loadConfig` accepts it as input and produces the resolved {@link VerbatraConfig}.
+ */
+type VerbatraConfigInput = z.infer<typeof verbatraConfigSchema>;
+/**
+ * The verbatra configuration after `loadConfig` has resolved it: identical to {@link VerbatraConfigInput}
+ * except `glossary`, which is always a plain record here. A glossary given as a file path is read,
+ * parsed, and validated by the loader before a `VerbatraConfig` is produced, so every downstream
+ * consumer (the translation flow, `watch`, the CLI) keeps receiving the same resolved shape it always
+ * did.
+ */
+type VerbatraConfig = Omit<VerbatraConfigInput, "glossary"> & {
+    glossary?: Readonly<Record<string, string>>;
+};
 
 type KnownModels<M extends string> = M extends string ? (string extends M ? never : M) : never;
 type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<ProviderConfig, {
@@ -292,19 +343,24 @@ 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 VerbatraConfig} whose `provider`
- * is that id's single authoring variant, so `options.model` offers only that provider's models. When
- * `TId` defaults to `ProviderId`, `provider` is the full authoring union. Every value here is assignable
- * to {@link VerbatraConfig}, since a model literal is a subtype of `string`.
+ * The authoring view of the whole config for a provider id: a {@link VerbatraConfigInput} whose
+ * `provider` is that id's single authoring variant, so `options.model` offers only that provider's
+ * models. `glossary` stays the as-authored union (inline record or file path); resolution happens only
+ * in `loadConfig`. When `TId` defaults to `ProviderId`, `provider` is the full authoring union. Every
+ * value here is assignable to {@link VerbatraConfigInput}, since a model literal is a subtype of
+ * `string`.
  */
-type AuthoringConfigFor<TId extends ProviderId = ProviderId> = Omit<VerbatraConfig, "provider"> & {
+type AuthoringConfigFor<TId extends ProviderId = ProviderId> = Omit<VerbatraConfigInput, "provider"> & {
     provider: AuthoringProviderVariant[TId];
 };
 /**
  * The authoring view of the whole config across every provider (the `TId = ProviderId`
- * case of {@link AuthoringConfigFor}): identical to {@link VerbatraConfig} except that
+ * case of {@link AuthoringConfigFor}): identical to {@link VerbatraConfigInput} except that
  * `provider` offers per-provider model completions.
  */
 type AuthoringConfig = AuthoringConfigFor;
@@ -316,16 +372,66 @@ type AuthoringConfig = AuthoringConfigFor;
  *
  * The model restriction is a static authoring constraint only: `loadConfig` validates `model` as a
  * non-empty string, so a model the installed provider SDK does not yet list is flagged in the editor
- * but still runs.
+ * but still runs. Likewise, `glossary` accepts either an inline record or a file path here; `loadConfig`
+ * resolves a path to a record before the translation flow ever sees it.
  *
  * @param config - The verbatra configuration object.
- * @returns The same config, typed as {@link VerbatraConfig}.
+ * @returns The same config, typed as {@link VerbatraConfigInput}.
+ */
+declare function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfigInput;
+declare function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfigInput;
+declare function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraConfigInput;
+declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfigInput;
+declare function defineConfig(config: AuthoringConfig): VerbatraConfigInput;
+
+/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
+type BoundedFileRead = {
+    readonly kind: "ok";
+    readonly content: string;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
+/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
+type BoundedBytesRead = {
+    readonly kind: "ok";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
+/**
+ * The minimal file-system surface the SDK needs. Reads are bounded and writes are atomic. Injectable so
+ * tests stay deterministic; the format adapters do their own file IO and bypass this seam.
  */
-declare function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfig;
-declare function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfig;
-declare function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraConfig;
-declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfig;
-declare function defineConfig(config: AuthoringConfig): VerbatraConfig;
+interface SdkFs {
+    /** Whether a readable file exists at the path. */
+    fileExists(path: string): Promise<boolean>;
+    /**
+     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the handle is
+     * fstat'd and the read never advances past the sized length, so swapping in a larger file cannot
+     * bypass the cap. A missing or unreadable path is "missing"; a file over the cap is "too-large".
+     */
+    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
+    /** Read a file as raw bytes with the same TOCTOU-safe, bounded discipline as {@link readFileBounded}. */
+    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
+    /** Write atomically: a temp file in the same directory, then rename over the target. */
+    writeFile(path: string, data: string): Promise<void>;
+    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
+    writeBytes(path: string, data: Uint8Array): Promise<void>;
+}
+
+/** Where a config's resolved glossary came from, recorded for later Studio consumption. */
+type GlossaryProvenance = {
+    readonly source: "none";
+} | {
+    readonly source: "inline";
+} | {
+    readonly source: "file";
+    readonly path: string;
+};
 
 interface LoadConfigOptions {
     /** Directory to start the search from. Defaults to the current working directory. */
@@ -342,7 +448,42 @@ interface LoadConfigOptions {
      * search, but `configOverride` takes precedence over it.
      */
     readonly configPath?: string;
+    /** The file-system seam a glossary file path is read through. Defaults to {@link defaultFs}. */
+    readonly fs?: SdkFs;
 }
+/** Where the loaded config came from: an in-memory override, one explicit file, or a search result. */
+type ConfigSource = {
+    readonly kind: "search" | "explicit";
+    readonly filepath: string;
+} | {
+    readonly kind: "override";
+};
+/**
+ * The result of {@link loadConfigWithMeta}: the resolved config, where it was loaded from, and where its
+ * glossary came from. `filepath` (when present) and a `glossary` file path are always absolute.
+ */
+interface LoadedConfig {
+    readonly config: VerbatraConfig;
+    readonly source: ConfigSource;
+    readonly glossary: GlossaryProvenance;
+}
+/**
+ * Load and validate the verbatra configuration, returning provenance alongside it: which source it was
+ * loaded from ({@link ConfigSource}), and whether its glossary is absent, inline, or resolved from a
+ * file ({@link GlossaryProvenance}). {@link loadConfig} is a thin wrapper that returns only the
+ * `config` field; use this directly when the provenance is needed (for example, to display it or to
+ * re-resolve a glossary file relative to the same base directory).
+ *
+ * @param options - Where/what to load: `cwd`, an in-memory `configOverride`, an explicit `configPath`,
+ *   or a `fs` seam override.
+ * @returns The resolved {@link VerbatraConfig}, its {@link ConfigSource}, and its {@link GlossaryProvenance}.
+ * @throws {@link SdkError} `CONFIG_NOT_FOUND`: no config was found by search, or the explicit `configPath`
+ *   does not exist.
+ * @throws {@link SdkError} `CONFIG_INVALID`: a config was found but is unparseable or fails validation, or
+ *   its glossary file path could not be read as a valid, UTF-8, flat string record (a raw error never
+ *   escapes).
+ */
+declare function loadConfigWithMeta(options?: LoadConfigOptions): Promise<LoadedConfig>;
 /**
  * Load and validate the verbatra configuration. Supports a code-defined
  * verbatra.config.ts and file-based configs (.verbatrarc.json/.yaml, package.json
@@ -352,12 +493,17 @@ interface LoadConfigOptions {
  *
  * Precedence: `configOverride` (validate in-memory) > `configPath` (load one explicit file) > search.
  *
+ * A `glossary` given as a file path is read, parsed, and validated at load time (see
+ * {@link loadConfigWithMeta} for its provenance); a relative path resolves against the loaded config
+ * file's directory, or against `cwd` for a `configOverride`. Watch mode does not re-resolve a glossary
+ * file on later edits; restart to pick up a change.
+ *
  * @param options - Where/what to load: `cwd`, an in-memory `configOverride`, or an explicit `configPath`.
  * @returns The validated {@link VerbatraConfig}.
  * @throws {@link SdkError} `CONFIG_NOT_FOUND`: no config was found by search, or the explicit `configPath`
  *   does not exist.
- * @throws {@link SdkError} `CONFIG_INVALID`: a config was found but is unparseable or fails validation
- *   (a raw zod error never escapes).
+ * @throws {@link SdkError} `CONFIG_INVALID`: a config was found but is unparseable or fails validation, or
+ *   its glossary file path could not be resolved (a raw error never escapes).
  * @example
  * ```ts
  * import { loadConfig, translate } from "@verbatra/sdk";
@@ -388,7 +534,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`.
@@ -445,6 +592,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.
  */
@@ -521,6 +683,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. */
@@ -570,45 +744,6 @@ declare class AdapterRegistry {
     resolve(filePath: string, options?: ResolveOptions): AdapterResolution;
 }
 
-/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
-type BoundedFileRead = {
-    readonly kind: "ok";
-    readonly content: string;
-} | {
-    readonly kind: "missing";
-} | {
-    readonly kind: "too-large";
-};
-/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
-type BoundedBytesRead = {
-    readonly kind: "ok";
-    readonly bytes: Uint8Array;
-} | {
-    readonly kind: "missing";
-} | {
-    readonly kind: "too-large";
-};
-/**
- * The minimal file-system surface the SDK needs. Reads are bounded and writes are atomic. Injectable so
- * tests stay deterministic; the format adapters do their own file IO and bypass this seam.
- */
-interface SdkFs {
-    /** Whether a readable file exists at the path. */
-    fileExists(path: string): Promise<boolean>;
-    /**
-     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the handle is
-     * fstat'd and the read never advances past the sized length, so swapping in a larger file cannot
-     * bypass the cap. A missing or unreadable path is "missing"; a file over the cap is "too-large".
-     */
-    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
-    /** Read a file as raw bytes with the same TOCTOU-safe, bounded discipline as {@link readFileBounded}. */
-    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
-    /** Write atomically: a temp file in the same directory, then rename over the target. */
-    writeFile(path: string, data: string): Promise<void>;
-    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
-    writeBytes(path: string, data: Uint8Array): Promise<void>;
-}
-
 /** Per-locale drift status: counts only, no key lists. */
 interface LocaleCheckSummary {
     /** The target locale this entry reports on. */
@@ -708,6 +843,61 @@ interface DiffDeps {
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
+/** Per-locale key count and drift against the source and target files, from the recorded lock baseline. */
+interface LockLocaleState {
+    /** The target locale this entry reports on. */
+    readonly locale: string;
+    /** Number of keys the lock records a baseline for, in this locale. */
+    readonly keyCount: number;
+    /** Keys present in source but absent from the target. */
+    readonly missing: number;
+    /** Keys whose source changed since the target was last translated. */
+    readonly stale: number;
+    /** Keys whose recorded baseline still matches the source. */
+    readonly upToDate: number;
+}
+/**
+ * The lock-file's existence, version, and per-locale drift. `exists` is the outcome of an explicit
+ * probe of the lock-file path, never inferred from {@link readLockFile}'s missing-file degrade, so
+ * "no lock-file yet" and "an empty but present lock-file" stay distinguishable.
+ */
+type LockStateResult = {
+    readonly exists: false;
+} | {
+    readonly exists: true;
+    readonly version: number;
+    readonly locales: readonly LockLocaleState[];
+};
+/** Input for {@link lockState}: the validated config and which locales to report on. */
+interface LockStateInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** Subset of target locales to report on; defaults to all configured target locales. */
+    readonly locales?: readonly string[];
+}
+/** Composition seam for {@link lockState}: inject a registry and a file system for tests. */
+interface LockStateDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Report the lock-file's existence, version, and per-locale drift (key count from the recorded
+ * baseline, plus missing, stale, and up-to-date counts against the current source and target),
+ * without calling a provider, writing any file, or mutating the lock. `exists` comes from an
+ * explicit probe of the lock-file path: when it is absent, the result is `{ exists: false }` and
+ * no source or target file is read, since there is no recorded baseline to report drift against.
+ *
+ * @param input - The validated config and which locales to report on.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns The lock-file's existence and, when present, its version and per-locale drift.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE` when a requested locale is not among the configured
+ *   target locales; when the lock-file exists, also `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`,
+ *   `SOURCE_INVALID`, or `LOCK_FILE_INVALID` with the same meanings as in `translate`.
+ */
+declare function lockState(input: LockStateInput, deps?: LockStateDeps): Promise<LockStateResult>;
+
 /** A stable code for an SDK-originated notice (not a provider notice). */
 type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED";
 /**
@@ -956,6 +1146,53 @@ interface ImportWorkbookDeps {
  */
 declare function importWorkbook(input: ImportWorkbookInput, deps?: ImportWorkbookDeps): Promise<RunSummary>;
 
+/**
+ * The lock-file shape: for each target locale, a map of key to the source content hash from which that
+ * target key was last translated. The baseline core's diff consumes to detect changed source strings.
+ */
+interface LockFile {
+    readonly version: number;
+    readonly locales: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+
+/** Input for {@link loadLockFile}: the directory the lock-file resolves against. */
+interface LoadLockFileInput {
+    /** Directory the lock-file resolves against; defaults to cwd. */
+    readonly cwd?: string;
+}
+/** Composition seam for {@link loadLockFile}: inject a file system for tests. */
+interface LoadLockFileDeps {
+    readonly fs?: SdkFs;
+}
+/**
+ * Read the project's lock-file: a thin public wrapper around the internal lock-file reader,
+ * following the same input/deps convention as {@link check}, {@link diff}, and {@link lockState}.
+ * A missing lock-file degrades to an empty lock (first-run), the same behavior `translate` and
+ * `watch` rely on internally. Callers that need to distinguish "no lock-file yet" from "an empty
+ * but present lock-file" should use {@link lockState} instead, which probes the file's existence
+ * explicitly.
+ *
+ * @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, 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.
@@ -1070,4 +1307,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CheckDeps, type CheckInput, type CheckSummary, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, 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 WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, 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 };