@verbatra/sdk 0.2.2 → 0.4.0

package/dist/index.d.cts

@@ -1,15 +1,12 @@
+export { SupportedFormat } from '@verbatra/core';
 import { AnthropicModel, OpenAiModel, GeminiModel, ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { z } from 'zod';
 import { AdapterRegistry } from '@verbatra/format-adapters';
 
 /**
- * The provider section of the config: a discriminated union over the provider id,
- * reusing each provider's own exported config schema. There is no key field anywhere
- * in this union. The provider reads its API key from the environment at construction.
- *
- * This union and the factory table below are co-located on purpose: adding a provider
- * is a single edit here (one union variant plus one table entry), and the mapped-type
- * table makes the two sets provably identical at compile time.
+ * 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.
  */
 declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodLiteral<"anthropic">;
@@ -39,10 +36,9 @@ type ProviderConfig = z.infer<typeof providerConfigSchema>;
 type ProviderId = ProviderConfig["id"];
 
 /**
- * The verbatra project configuration. Non-secret only: it carries no API key (the
- * provider reads its key from the environment), and unknown top-level keys are rejected
- * so a stray secret cannot hide in the config. Validated with zod at the boundary
- * regardless of where it was loaded from.
+ * The verbatra project configuration. It carries no API key (the provider reads its key from the
+ * environment), and unknown top-level keys are rejected so a stray secret cannot hide in it. Validated
+ * with zod at the boundary regardless of where it was loaded from.
  */
 declare const verbatraConfigSchema: z.ZodObject<{
     sourceLocale: z.ZodString;
@@ -52,6 +48,9 @@ declare const verbatraConfigSchema: z.ZodObject<{
         "vue-i18n-json": "vue-i18n-json";
         "next-intl-json": "next-intl-json";
         "ngx-translate-json": "ngx-translate-json";
+        xliff: "xliff";
+        yaml: "yaml";
+        arb: "arb";
     }>;
     files: z.ZodObject<{
         pattern: z.ZodString;
@@ -86,27 +85,14 @@ declare const verbatraConfigSchema: z.ZodObject<{
         informal: "informal";
         neutral: "neutral";
     }>>;
+    prune: z.ZodOptional<z.ZodBoolean>;
+    generatePlurals: z.ZodOptional<z.ZodBoolean>;
+    maxBatchSize: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 type VerbatraConfig = z.infer<typeof verbatraConfigSchema>;
 
-/**
- * An open union over a provider's known model IDs: the suggested IDs plus any other
- * non-empty string. The `string & {}` arm keeps the union from collapsing to plain
- * `string` (so editors still surface the literals as completions) while accepting a
- * brand-new model ID the tool has never heard of. This is a static authoring hint
- * only; the runtime schema stays `z.string().min(1)` and validates nothing against
- * these literals.
- */
-type OpenModel<M extends string> = M | (string & {});
-/**
- * The authoring view of one provider variant: its runtime config with `options.model`
- * narrowed to that provider's open model union. LLM providers (anthropic, openai,
- * gemini) get suggestions; DeepL has no model field and is carried through unchanged.
- */
-type AuthoringProviderConfig = AuthoringVariant<"anthropic", AnthropicModel> | AuthoringVariant<"openai", OpenAiModel> | AuthoringVariant<"gemini", GeminiModel> | Extract<ProviderConfig, {
-    id: "deepl";
-}>;
-type AuthoringVariant<Id extends ProviderConfig["id"], M extends string> = Extract<ProviderConfig, {
+type KnownModels<M extends string> = M extends string ? (string extends M ? never : M) : never;
+type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<ProviderConfig, {
     id: Id;
 }> extends infer Variant ? Variant extends {
     options: {
@@ -114,30 +100,49 @@ type AuthoringVariant<Id extends ProviderConfig["id"], M extends string> = Extra
     };
 } ? Omit<Variant, "options"> & {
     options: Omit<Variant["options"], "model"> & {
-        model: OpenModel<M>;
+        model: KnownModels<M>;
     };
 } : never : never;
+type AuthoringProviderVariant = {
+    anthropic: AuthoringVariant<"anthropic", AnthropicModel>;
+    openai: AuthoringVariant<"openai", OpenAiModel>;
+    gemini: AuthoringVariant<"gemini", GeminiModel>;
+    deepl: Extract<ProviderConfig, {
+        id: "deepl";
+    }>;
+};
 /**
- * The authoring view of the whole config: identical to {@link VerbatraConfig} except
- * that `provider` offers per-provider model completions. Every value assignable to
- * this type is assignable to {@link VerbatraConfig}, because the open model union is a
- * subtype of `string`; `defineConfig` returns the runtime {@link VerbatraConfig}.
+ * 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`.
  */
-type AuthoringConfig = Omit<VerbatraConfig, "provider"> & {
-    provider: AuthoringProviderConfig;
+type AuthoringConfigFor<TId extends ProviderId = ProviderId> = Omit<VerbatraConfig, "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
+ * `provider` offers per-provider model completions.
+ */
+type AuthoringConfig = AuthoringConfigFor;
 
 /**
- * Identity helper for authoring a code-defined verbatra.config.ts. It returns its
- * argument unchanged; its only purpose is to give the author full type inference and
- * editor autocomplete on the config object.
+ * Identity helper for authoring a typed `verbatra.config.ts`. It returns its argument unchanged; its
+ * only purpose is full type inference and editor autocomplete on the config object, including
+ * completion of the selected provider's known model literals.
  *
- * The argument type is {@link AuthoringConfig}, which is structurally a
- * {@link VerbatraConfig} whose `provider.options.model` offers the selected provider's
- * known model IDs as completions while still accepting any other string. The return
- * type is the runtime {@link VerbatraConfig}: the suggestions are a static authoring
- * hint, not a runtime constraint, and `loadConfig` validates `model` exactly as before.
+ * 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.
+ *
+ * @param config - The verbatra configuration object.
+ * @returns The same config, typed as {@link VerbatraConfig}.
  */
+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 LoadConfigOptions {
@@ -149,12 +154,10 @@ interface LoadConfigOptions {
      */
     readonly configOverride?: unknown;
     /**
-     * An explicit config file to load instead of searching. A relative path resolves
-     * against `cwd` (an absolute path is used as given), then cosmiconfig's load() parses
-     * it with the same loaders search uses (.json/.yaml/.ts), and it is zod-validated at
-     * the boundary exactly like a searched file. A missing file is CONFIG_NOT_FOUND; a
-     * present-but-unparseable/invalid file is CONFIG_INVALID. Precedence: configOverride
-     * wins over configPath, which wins over search.
+     * An explicit config file to load instead of searching. A relative path resolves against `cwd`; an
+     * absolute path is used as given. Parsed and zod-validated exactly like a searched file: a missing
+     * file is `CONFIG_NOT_FOUND`, a present but invalid one is `CONFIG_INVALID`. Takes precedence over
+     * search, but `configOverride` takes precedence over it.
      */
     readonly configPath?: string;
 }
@@ -192,16 +195,16 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  * any message: provider/adapter/core errors are already secret-free, and the SDK never
  * reads or holds a key. Each names a distinct boundary:
  *
- * - `CONFIG_NOT_FOUND`:no config was found by search, or an explicit `configPath` does not exist
+ * - `CONFIG_NOT_FOUND`: no config was found by search, or an explicit `configPath` does not exist
  *   (thrown by `loadConfig`).
- * - `CONFIG_INVALID`:a config was found but is unparseable or fails validation (thrown by `loadConfig`).
- * - `UNKNOWN_FORMAT`:no adapter is registered for the configured format (thrown by `translate`).
- * - `PROVIDER_CONSTRUCTION_FAILED`:the provider factory threw; wraps the provider's own error, including
+ * - `CONFIG_INVALID`: a config was found but is unparseable or fails validation (thrown by `loadConfig`).
+ * - `UNKNOWN_FORMAT`: no adapter is registered for the configured format (thrown by `translate`).
+ * - `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw; wraps the provider's own error, including
  *   a missing `*_API_KEY` reported as `MISSING_API_KEY` (thrown by `translate`, non-dry-run only).
- * - `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
+ * - `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 or oversized (thrown by `translate`).
  * - `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`.
@@ -218,6 +221,157 @@ declare class SdkError extends Error {
     constructor(code: SdkErrorCode, message: string);
 }
 
+/** 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. */
+    readonly locale: string;
+    /** 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;
+    /** True when nothing needs (re)translating for this locale. */
+    readonly inSync: boolean;
+}
+/** The aggregate read-only status across all checked target locales. */
+interface CheckSummary {
+    /** True only when every checked locale is in sync. */
+    readonly inSync: boolean;
+    /** One entry per checked target locale, in config order. */
+    readonly locales: readonly LocaleCheckSummary[];
+}
+/** Input for {@link check}: the validated config and which locales to check. */
+interface CheckInput {
+    /** 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 check; defaults to all configured target locales. */
+    readonly locales?: readonly string[];
+}
+/** Composition seam for {@link check}: inject a registry and a file system for tests. */
+interface CheckDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Report which keys are missing or stale per target locale, without calling a provider, writing any
+ * file, or touching the lock. Each locale is reported as counts only (missing, stale, up-to-date);
+ * a locale is `inSync` when nothing is missing or stale, and the top-level `inSync` is true only when
+ * every checked locale is. Orphaned keys and integrity are not reported, since they concern a write.
+ *
+ * @param input - The validated config and which locales to check.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns The aggregate and per-locale drift status.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
+ *   with the same meanings as in `translate`.
+ */
+declare function check(input: CheckInput, deps?: CheckDeps): Promise<CheckSummary>;
+
+/** Per-locale pending change: the key lists, not counts. */
+interface LocaleDiff {
+    /** The target locale this entry reports on. */
+    readonly locale: string;
+    /** Keys present in source but absent from the target; would be added by a run. */
+    readonly missing: readonly string[];
+    /** Keys whose source changed since last translated; would be re-translated. */
+    readonly changed: readonly string[];
+    /** Keys present in target but absent from source; report-only, never pending. */
+    readonly orphaned: readonly string[];
+    /** True when the locale has missing or changed keys; orphaned keys do not count. */
+    readonly hasPendingChanges: boolean;
+}
+/** The aggregate read-only diff across all checked target locales. */
+interface DiffSummary {
+    /** True when any checked locale has pending changes. */
+    readonly hasPendingChanges: boolean;
+    /** One entry per checked target locale, in config order. */
+    readonly locales: readonly LocaleDiff[];
+}
+/** Input for {@link diff}: the validated config and which locales to diff. */
+interface DiffInput {
+    /** 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 diff; defaults to all configured target locales. */
+    readonly locales?: readonly string[];
+}
+/** Composition seam for {@link diff}: inject a registry and a file system for tests. */
+interface DiffDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Report the exact pending change per target locale as three key lists (missing, changed, orphaned),
+ * without calling a provider, writing any file, or touching the lock. This is the detailed sibling of
+ * {@link check}. A locale's `hasPendingChanges` is driven by missing or changed only; orphaned keys are
+ * reported but do not flip it, since a default `translate` run does not prune. The top-level
+ * `hasPendingChanges` is true when any checked locale has pending changes.
+ *
+ * @param input - The validated config and which locales to diff.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns The aggregate and per-locale pending change.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
+ *   with the same meanings as in `translate`.
+ */
+declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
+
+/** A stable code for an SDK-originated notice (not a provider notice). */
+type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED";
+/**
+ * A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
+ * so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
+ * secret-free message; never a key value or translatable content.
+ */
+interface SdkNotice {
+    /** The stable {@link SdkNoticeCode} for what the SDK is reporting. */
+    readonly code: SdkNoticeCode;
+    /** A static, safe description; never a key or translatable content. */
+    readonly message: string;
+}
+/** A notice on a locale summary: either a provider-emitted notice or an SDK-emitted one. */
+type LocaleNotice = ProviderNotice | SdkNotice;
 /** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
 interface LocaleSummary {
     /** The target locale this summary is for. */
@@ -231,14 +385,30 @@ interface LocaleSummary {
     readonly translated: readonly string[];
     /** Keys already up to date, left unchanged this run. */
     readonly unchanged: readonly string[];
-    /** Target keys with no corresponding source key (candidates for removal). */
+    /** Target keys with no corresponding source key (candidates for removal). Reported regardless of pruning. */
     readonly orphaned: readonly string[];
+    /**
+     * Orphaned keys actually removed this run because pruning was on. In a dry-run with pruning on, the keys
+     * that WOULD be removed. Empty when pruning is off (the orphans then survive and are reported in
+     * `orphaned` only). A subset of `orphaned`; never includes a source-present key.
+     */
+    readonly pruned: readonly string[];
     /** Source keys flagged invalid-ICU that were skipped for translation this run. */
     readonly invalidIcuSource: readonly string[];
     /** Translated keys that failed the placeholder-integrity check and were withheld. */
     readonly integrityMismatches: readonly string[];
-    /** Provider notices for this locale (e.g. DeepL graceful-degradation); empty for LLM providers. */
-    readonly notices: readonly ProviderNotice[];
+    /**
+     * Plural-category keys verbatra synthesized this run (for example a Polish `items_few` the source
+     * never supplied), kept distinct from {@link translated}. Empty unless plural generation was enabled
+     * and acted, and empty in a dry-run.
+     */
+    readonly generated: readonly string[];
+    /**
+     * Notices for this locale: provider notices (e.g. DeepL graceful-degradation) and SDK notices
+     * (e.g. a target language needing more CLDR plural categories than the source supplies). Empty when
+     * nothing was degraded or flagged.
+     */
+    readonly notices: readonly LocaleNotice[];
     /**
      * Present only when status is "failed": a structured, secret-free error. `code` is a PRESERVED string
      * (the underlying provider/adapter error's `code`, or `"LOCALE_FAILED"` as a fallback), intentionally
@@ -261,54 +431,6 @@ interface RunSummary {
     readonly failed: readonly string[];
 }
 
-/** 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: existence checks, the lock-file read/write,
- * and the untrusted workbook bytes read/write for the export/import flow. Reads are bounded
- * (see {@link readFileBounded} / {@link readBytesBounded}) and writes are atomic. Injectable so
- * tests stay deterministic; the format adapters do their own file IO and are not routed through
- * 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 the
-     * path for a larger file after the size check cannot bypass the cap. A missing or
-     * unreadable path is "missing" (first-run); a file over the cap is "too-large".
-     */
-    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
-    /**
-     * Read a file as raw bytes through a single handle, bounded to maxBytes, with the SAME
-     * TOCTOU-safe discipline as {@link readFileBounded}: the handle is fstat'd and the read never
-     * advances past the sized length. Used for the untrusted workbook on import; a file over the
-     * cap is "too-large", a missing path is "missing".
-     */
-    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>;
-}
-
 /** Builds the provider from its config. Injectable so tests stay offline. */
 type CreateProvider = (config: ProviderConfig) => TranslationProvider;
 
@@ -320,6 +442,19 @@ interface TranslateInput {
     readonly cwd?: string;
     /** When true, read + diff + report only: the provider is never constructed or called and nothing is written. */
     readonly dryRun?: boolean;
+    /**
+     * When true, remove orphaned keys (target keys absent from source) from the written file and the lock.
+     * Off by default. When set, takes precedence over the config's `prune` option for this run; when unset,
+     * the config's `prune` applies. Only `diff.orphaned` keys are ever removed; no other key is touched.
+     */
+    readonly prune?: boolean;
+    /**
+     * When true, synthesize the CLDR plural forms a richer target language requires but the source lacks
+     * (i18next-JSON + LLM providers only; every other case falls back to the existing warning). Off by
+     * default. When set, takes precedence over the config's `generatePlurals` option for this run; when
+     * unset, the config's `generatePlurals` applies.
+     */
+    readonly generatePlurals?: boolean;
 }
 /** Composition seam: inject a registry, a provider builder, and a file system for tests. */
 interface TranslateDeps {
@@ -344,7 +479,7 @@ interface TranslateDeps {
  * {@link SdkErrorCode}. DeepL notices, integrity mismatches, and invalid-ICU source keys likewise
  * surface on each `LocaleSummary`, never as throws.
  *
- * @param input - The validated config and run options (cwd, dryRun).
+ * @param input - The validated config and run options (cwd, dryRun, prune, generatePlurals).
  * @param deps - Optional composition seams (registry, provider builder, file system) for tests.
  * @returns A {@link RunSummary}: the per-locale {@link LocaleSummary}s and the succeeded/failed locale lists.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
@@ -409,11 +544,10 @@ interface ExportWorkbookResult {
     }[];
 }
 /**
- * Export the strings needing human translation into a styled `.xlsx` workbook. Reuses the same
- * source read, adapter selection, and lock baseline the translate flow uses, runs `diffResources`
- * per target locale to pick the rows (missing and changed by default; add unchanged with
- * `includeUnchanged`), hands the neutral row model to `@verbatra/exchange`'s `buildWorkbook`, and
- * writes the bytes through the {@link SdkFs} seam. No provider is called and no lock-file is written.
+ * Export the strings needing human translation into a styled `.xlsx` workbook. Each target locale is
+ * diffed against the source and lock baseline to pick the rows (missing and changed by default; add
+ * unchanged with `includeUnchanged`), and the bytes are written to `out`. No provider is called and no
+ * lock-file is written.
  *
  * @param input - The validated config and export options.
  * @param deps - Optional composition seams (registry, file system) for tests.
@@ -440,19 +574,16 @@ interface ImportWorkbookDeps {
     readonly fs?: SdkFs;
 }
 /**
- * Import a filled workbook back into the locale files. Reads the untrusted workbook through the
- * SDK's bounded read, parses it with `@verbatra/exchange`'s `readWorkbook` (which bounds and
- * sanitizes it), then for each target-locale data sheet runs the EXISTING core checks (source-drift
- * via `contentHash`, placeholder integrity via `checkPlaceholders`, ICU via the adapter's
- * `validateMessage`), writes the accepted values through the format adapter, and updates the lock
- * through the existing lock logic. Returns a {@link RunSummary} structurally identical to
- * `translate`'s, so the CLI formatter and exit-code rule are shared with no special case.
+ * Import a filled workbook back into the locale files. Each target-locale data sheet runs the same
+ * source-drift, placeholder, and ICU checks as the translate flow, the accepted values are written
+ * through the format adapter, and the lock is updated. Returns a {@link RunSummary} structurally
+ * identical to `translate`'s.
  *
  * Whole-run failures (unknown format, unreadable/invalid/oversized workbook, corrupt lock) throw a
  * structured {@link SdkError}. A per-sheet failure (a locale not in config, a broken-round-trip key,
  * a write failure) is isolated as that locale's `status: "failed"`, not a throw; per-row rejections
- * are withheld and reported on the locale, exactly as the provider path treats integrity mismatches.
- * `--dry-run` validates and reports without writing any locale or lock file.
+ * are withheld and reported on the locale. Dry-run validates and reports without writing any locale or
+ * lock file.
  *
  * @param input - The validated config, the workbook path, and run options.
  * @param deps - Optional composition seams (registry, file system) for tests.
@@ -461,6 +592,28 @@ interface ImportWorkbookDeps {
  */
 declare function importWorkbook(input: ImportWorkbookInput, deps?: ImportWorkbookDeps): Promise<RunSummary>;
 
+/**
+ * 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.
+ */
+declare const scaffoldingMetadata: {
+    /** Provider id -> the environment variable its API key is read from. Owned by ai-providers. */
+    readonly providerEnv: {
+        readonly anthropic: "ANTHROPIC_API_KEY";
+        readonly openai: "OPENAI_API_KEY";
+        readonly gemini: "GEMINI_API_KEY";
+        readonly deepl: "DEEPL_API_KEY";
+    };
+    /** LLM provider id -> a cosmetic default scaffold model. Owned by ai-providers. DeepL has none. */
+    readonly scaffoldModels: {
+        readonly anthropic: "claude-sonnet-4-6";
+        readonly openai: "gpt-5.4-mini";
+        readonly gemini: "gemini-2.5-flash";
+    };
+    /** The closed set of source format ids. Owned by core. */
+    readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb"];
+};
+
 /** A minimal source-change event source. Production wraps chokidar; tests inject a stub. */
 interface Watcher {
     /** Register a listener invoked once per coalesced source-change event. */
@@ -470,7 +623,7 @@ interface Watcher {
 }
 /** Builds a {@link Watcher} for the given paths; the seam production fills with chokidar. */
 type CreateWatcher = (paths: readonly string[]) => Watcher;
-/** The run a watch trigger performs: the slice-1 one-shot translate, unchanged. */
+/** The run a watch trigger performs: the one-shot translate, unchanged. */
 type RunTranslate = (input: TranslateInput) => Promise<RunSummary>;
 /** The outcome of one run, surfaced to the caller; never carries a secret. */
 type WatchRunResult = {
@@ -517,16 +670,11 @@ interface WatchController {
     stop(): Promise<void>;
 }
 /**
- * Start watching the source file and re-run the one-shot translate on each debounced change.
- * Watch adds no translation/diff/lock logic: it watches, debounces, serializes, and invokes the
- * existing translate() unchanged. The state machine is IDLE <-> RUNNING with a single boolean
- * pending-rerun flag (mid-run changes collapse into one immediate follow-up; never two runs at
- * once). A missing source at startup is a hard error; a run that fails after start is reported and
- * watching continues. Returns a controller whose stop() closes the watcher and awaits the in-flight
- * run (the caller wires any signal, e.g. SIGINT, to it).
- *
- * Only the startup source check throws; every run outcome after start is surfaced through `onRun` as a
- * {@link WatchRunResult} (a failed run never rejects the in-flight promise).
+ * Start watching the source file and re-run the one-shot {@link translate} on each debounced change.
+ * Runs are serialized: changes during a run collapse into a single follow-up, so two runs never
+ * overlap. A missing source at startup throws; every run outcome after start is surfaced through
+ * `onRun` as a {@link WatchRunResult} and watching continues. Returns a controller whose `stop()`
+ * closes the watcher and awaits the in-flight run.
  *
  * @param input - The config, optional cwd/debounce, and the `onRun` callback that receives each result.
  * @param deps - Optional composition seams (watcher, run, registry, provider builder, file system) for tests.
@@ -558,4 +706,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, defineConfig, exportWorkbook, importWorkbook, loadConfig, translate, verbatraConfigSchema, watch };
+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 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 };