@askdb/config 1.0.0-beta.12 → 1.0.0-beta.13

package/README.md

@@ -2,7 +2,7 @@
 
 Prisma-style helpers for AskDB: `env()`, `defineConfig()`, plus discovery and loading of `askdb.config.*` / `.config/askdb.*` files used by first-party apps (`askdb` CLI, `@askdb/http-api`, `@askdb/studio`).
 
-**`@askdb/config` is the single package that reads `process.env` directly** (during dotenv load, while `askdb.config.*` evaluates, and for a tiny bootstrap-time overlay allowlist). All other packages obtain configuration through **`getAskDbRuntimeConfig()`**.
+**`@askdb/config` is the single package that reads `process.env` directly** (during dotenv load, while `askdb.config.*` evaluates, for a tiny bootstrap-time overlay allowlist, and for the `ASKDB_DEBUG` diagnostics switch). All other packages obtain configuration through **`getAskDbRuntimeConfig()`**.
 
 ## Install
 
@@ -31,29 +31,25 @@ export default defineConfig({
     providerConfig: {
       openai: {
         apiKey: env("MY_OPENAI_API_KEY"),
-        model: env("MY_CHAT_MODEL"),
       },
     },
-  },
-  database: {
-    provider: "postgres",
-    providerConfig: { postgres: { databaseUrl: env("MY_DATABASE_URL") } },
+    language: {
+      model: env("MY_LANGUAGE_MODEL"),
+    },
   },
   introspection: {
     provider: "postgres",
-    providerConfig: { postgres: {} },
+    providerConfig: { postgres: { databaseUrl: env("MY_DATABASE_URL") } },
     outputDir: env("MY_INTROSPECT_OUTPUT_DIR"),
   },
-  rag: {
-    embedder: "mock",
-    embedderConfig: {},
-    store: "memory",
-    storeConfig: { memory: {} },
-  },
 } satisfies AskDbConfig);
 ```
 
-Your `.env` can use friendly names (`MY_OPENAI_API_KEY`, …). `defineConfig` runs `flattenAskDbConfig`, which maps the nested object onto the canonical environment variable names used in the **runtime flat map** (and in `aiEnv` for `@askdb/ai`). **Unset optional fields get defaults inside `flattenAskDbConfig`** (chat model, introspection output dir, database URL fallbacks, RAG embedding dimensions, file-store base path, pgvector index strategy, etc. — see `packages/config/src/defaults.ts`).
+Your `.env` can use friendly names (`MY_OPENAI_API_KEY`, …). `defineConfig` runs `flattenAskDbConfig`, which maps the nested object onto the canonical environment variable names used in the **runtime flat map** (and in `aiEnv` for `@askdb/ai`). **Unset optional fields get defaults inside `flattenAskDbConfig`** (language model, introspection output dir, database URL fallbacks, the mock embedder's vector width, file-store base path, pgvector index strategy, etc. — see `packages/config/src/defaults.ts`).
+
+The `rag` block is optional. Omit it when you don't use retrieval: AskDB then uses the mock embedder and the in-memory store, as if `rag: { embedder: "mock", store: "memory", storeConfig: {} }` were set. Setting `ai.embedding` without the block is an error, since nothing would use that model.
+
+`ai.providerConfig` holds provider connections only (one per provider, or a named list). The model choice lives in `ai.language` (the language model) and `ai.embedding` (the embedding model behind `rag.embedder: "ai"`), each with an optional `provider` and `connection`. Configs written in the older shape (`providerConfig.<provider>.model`, `ai.reasoning`, `rag.embedder: "openai" | "ai-sdk"`, `rag.embedderConfig`) still load: AskDB translates them at load, and `bootstrapAskDbEnv` emits one `DeprecationWarning` (code `ASKDB_CONFIG_DEPRECATED`) per old key. The old keys are removed at 1.0. See the [configuration reference](https://askdb.tools/reference/config/#the-ai-block).
 
 ## Architectural rule — `@askdb/config` is the sole `process.env` reader
 
@@ -67,11 +63,16 @@ const apiKey = opts.apiKey ?? config.rag.embedder.apiKey;
 const level = config.logging.level;
 // For @askdb/ai registry methods that accept an env-map argument:
 const model = await aiRegistry.createLanguageModelFromEnv(config.ai.aiEnv, { ... });
+// The embedding model, built from the ai.embedding connection only (ai.embedding is undefined unless
+// rag.embedder is "ai"). The env map doesn't carry the width, so pass it as an option:
+const embeddingModel = config.ai.embedding
+  ? await aiRegistry.createEmbeddingModelFromEnv(config.ai.embedding.env, { dimensions: config.ai.embedding.dimensions })
+  : undefined;
 ```
 
 **Rules:**
 
-- Library packages (`@askdb/rag`, `@askdb/enrich`, …) must call `getAskDbRuntimeConfig()` and use the returned typed fields. They must **not** call `env()`, `requiredEnv()`, or access `process.env` directly.
+- Library packages that read AskDB settings must call `getAskDbRuntimeConfig()`, or take the runtime snapshot from their host as `@askdb/client` does, and use the returned typed fields. They must **not** call `env()`, `requiredEnv()`, or access `process.env` directly.
 - `env(name)` is only for use inside `askdb.config.*` files authored by end users — it maps friendly `.env` names onto values that become part of the structured config and flat map.
 - First-party app entry points call `bootstrapAskDbEnv()` at start-up. That loads dotenv, evaluates `askdb.config.*`, and installs an **in-memory runtime snapshot** (structured config + flat map + derived `aiEnv`). It does **not** copy AskDB settings into `process.env`.
 
@@ -81,10 +82,11 @@ const model = await aiRegistry.createLanguageModelFromEnv(config.ai.aiEnv, { ...
 
 ## API
 
-- `getAskDbRuntimeConfig()` — **primary API for library packages**. Returns a typed `AskDbRuntimeConfig` from the bootstrapped snapshot (`structured`, `flat`-derived fields, and `ai.aiEnv` for `@askdb/core`).
+- `getAskDbRuntimeConfig()` — **primary API for library packages**. Returns a typed `AskDbRuntimeConfig` from the bootstrapped snapshot (`structured`, `flat`-derived fields, `ai.aiEnv` for `@askdb/core`, the resolved `ai.language` and `ai.embedding` sections, `rag.store` and `rag.storeConfig` (the vector store, `"memory"` when `rag` is omitted), and `deprecations`, the config's deprecation messages).
 - `env(name)` / `requiredEnv(name)` — read `process.env` while authoring `askdb.config.*` only.
+- `isAskDbDebugEnabled()` — `true` when the `ASKDB_DEBUG` shell variable is `1` or `true`. Binaries use it to print stack traces; it reads `process.env` directly so it works even when the config fails to load.
 - `defineConfig(config)` — returns an `AskDbEnvProjection` with `config` (structured) and `entries` (flattened canonical map).
-- `flattenAskDbConfig(config)` — nested config → flat canonical map (applies defaults for optional values).
+- `flattenAskDbConfig(config)` — nested config → flat canonical map (translates deprecated keys, applies defaults for optional values).
 - `bootstrapAskDbEnv(options?)` / `bootstrapAskDbRuntime` — load dotenv, load config, install the runtime snapshot.
 - `loadAskDbConfigProjection(cwd)` / `loadAskDbConfigProjectionSync(cwd)` — load projection without installing the singleton (advanced / tests).
 - `discoverAskDbConfigPath(cwd)` — returns the resolved config path, if any.

package/dist/bootstrap.d.ts

@@ -20,6 +20,9 @@ export type BootstrapAskDbEnvOptions = {
  *
  * `askdb.config.*` is the sole source of truth — use `env("VAR")` in the config file to read
  * from the environment at load time.
+ *
+ * Each deprecated config key in use is reported once per process as a `DeprecationWarning`
+ * (code `ASKDB_CONFIG_DEPRECATED`); `getAskDbRuntimeConfig().deprecations` lists them for UIs.
  */
 export declare function bootstrapAskDbEnv(options?: BootstrapAskDbEnvOptions): {
     dotenvPath?: string;

package/dist/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,wBAAwB,GAAG;IACrC,mGAAmG;IACnG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAeF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAkDA;AAED,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,0BAAoB,CAAC"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAuBA,MAAM,MAAM,wBAAwB,GAAG;IACrC,mGAAmG;IACnG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAeF;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAmDA;AAED,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,0BAAoB,CAAC"}

package/dist/bootstrap.js

@@ -5,6 +5,18 @@ import { loadAskDbConfigProjectionSync } from "./load-merge.js";
 import { setAskDbRuntime } from "./runtime-store.js";
 /** dotenv v17 logs injected keys by default; keep bootstrap silent like v16. */
 const DOTENV_LOAD_OPTIONS = { quiet: true };
+/** `process.emitWarning` code for a deprecated `askdb.config` key. */
+const CONFIG_DEPRECATION_CODE = "ASKDB_CONFIG_DEPRECATED";
+/** Deprecation messages already emitted: a process that bootstraps twice warns once. */
+const emittedDeprecations = new Set();
+function emitConfigDeprecations(deprecations) {
+    for (const message of deprecations ?? []) {
+        if (emittedDeprecations.has(message))
+            continue;
+        emittedDeprecations.add(message);
+        process.emitWarning(message, { type: "DeprecationWarning", code: CONFIG_DEPRECATION_CODE });
+    }
+}
 function handleDotenvError(error, nonFatal) {
     const err = error;
     const code = typeof err.code === "string" ? err.code : undefined;
@@ -26,6 +38,9 @@ function handleDotenvError(error, nonFatal) {
  *
  * `askdb.config.*` is the sole source of truth — use `env("VAR")` in the config file to read
  * from the environment at load time.
+ *
+ * Each deprecated config key in use is reported once per process as a `DeprecationWarning`
+ * (code `ASKDB_CONFIG_DEPRECATED`); `getAskDbRuntimeConfig().deprecations` lists them for UIs.
  */
 export function bootstrapAskDbEnv(options = {}) {
     const cwd = options.cwd ?? process.cwd();
@@ -75,6 +90,7 @@ export function bootstrapAskDbEnv(options = {}) {
         structured: projection.config,
         flat: { ...projection.entries },
     });
+    emitConfigDeprecations(projection.deprecations);
     return { dotenvPath, configPath };
 }
 /** Alias for {@link bootstrapAskDbEnv} (explicit naming). */

package/dist/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -8,16 +8,27 @@ export type AskDbModeV1 = (typeof ASKDB_MODES_V1)[number];
  */
 export declare const ASKDB_LOG_LEVELS: readonly ["fatal", "error", "warn", "info", "debug", "trace", "silent"];
 export type AskDbLogLevel = (typeof ASKDB_LOG_LEVELS)[number];
-/** RAG embedder modes used by Studio / docs (CLI RAG currently supports mock + openai). */
-export declare const ASKDB_RAG_EMBEDDERS: readonly ["mock", "openai", "ai-sdk"];
+/**
+ * `rag.embedder` values: `"mock"` (a local lexical embedder) or `"ai"` (the `ai.embedding`
+ * model). `"openai"` and `"ai-sdk"` are deprecated: they're translated to `"ai"` at load,
+ * with a warning, and removed at 1.0.
+ */
+export declare const ASKDB_RAG_EMBEDDERS: readonly ["mock", "ai", "openai", "ai-sdk"];
 export type AskDbRagEmbedder = (typeof ASKDB_RAG_EMBEDDERS)[number];
 export declare const ASKDB_RAG_STORES: readonly ["file", "memory", "pgvector"];
 export type AskDbRagStore = (typeof ASKDB_RAG_STORES)[number];
-export declare const ASKDB_AI_PROVIDERS: readonly ["openai", "azure", "foundry", "google"];
+/**
+ * Provider ids with a dedicated `ai.providerConfig.<id>` branch in `askdb.config.*`.
+ * Mirrors the built-in provider table in `@askdb/ai` (`BUILTIN_AI_PROVIDERS`: every
+ * built-in plus the `foundry` alias). `@askdb/config` must not depend on `@askdb/ai`,
+ * so the list is duplicated here; `packages/client/src/provider-config-drift.test.ts`
+ * fails if the two drift.
+ */
+export declare const ASKDB_AI_PROVIDERS: readonly ["openai", "azure", "foundry", "anthropic", "google", "gateway"];
 export type AskDbAiProviderId = (typeof ASKDB_AI_PROVIDERS)[number];
 /**
  * Provider-portable reasoning/latency effort for AskDB model calls. Maps to
- * each provider's native knob by the `@askdb/ai-*` adapter (see `@askdb/ai`'s
+ * each provider's native knob by the provider adapter (see `@askdb/ai`'s
  * `resolveProviderOptions`). Keep aligned with `REASONING_EFFORTS` in
  * `@askdb/ai` (`packages/ai/src/reasoning.ts`).
  */

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,cAAc,6CAA8C,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,gBAAgB,yEAQnB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,uCAAwC,CAAC;AACzE,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,eAAO,MAAM,gBAAgB,yCAA0C,CAAC;AACxE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,eAAO,MAAM,kBAAkB,mDAAoD,CAAC;AACpF,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,+CAAgD,CAAC;AACrF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,6BAA6B,iEAMhC,CAAC;AACX,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAExF;;;;GAIG;AACH,eAAO,MAAM,cAAc,iFAOjB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,8BAA8B,uDAKjC,CAAC;AACX,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,cAAc,6CAA8C,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,gBAAgB,yEAQnB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,6CAA8C,CAAC;AAC/E,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,eAAO,MAAM,gBAAgB,yCAA0C,CAAC;AACxE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,2EAA4E,CAAC;AAC5G,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,+CAAgD,CAAC;AACrF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,6BAA6B,iEAMhC,CAAC;AACX,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAExF;;;;GAIG;AACH,eAAO,MAAM,cAAc,iFAOjB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,8BAA8B,uDAKjC,CAAC;AACX,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/constants.js

@@ -14,13 +14,24 @@ export const ASKDB_LOG_LEVELS = [
     "trace",
     "silent",
 ];
-/** RAG embedder modes used by Studio / docs (CLI RAG currently supports mock + openai). */
-export const ASKDB_RAG_EMBEDDERS = ["mock", "openai", "ai-sdk"];
+/**
+ * `rag.embedder` values: `"mock"` (a local lexical embedder) or `"ai"` (the `ai.embedding`
+ * model). `"openai"` and `"ai-sdk"` are deprecated: they're translated to `"ai"` at load,
+ * with a warning, and removed at 1.0.
+ */
+export const ASKDB_RAG_EMBEDDERS = ["mock", "ai", "openai", "ai-sdk"];
 export const ASKDB_RAG_STORES = ["file", "memory", "pgvector"];
-export const ASKDB_AI_PROVIDERS = ["openai", "azure", "foundry", "google"];
+/**
+ * Provider ids with a dedicated `ai.providerConfig.<id>` branch in `askdb.config.*`.
+ * Mirrors the built-in provider table in `@askdb/ai` (`BUILTIN_AI_PROVIDERS`: every
+ * built-in plus the `foundry` alias). `@askdb/config` must not depend on `@askdb/ai`,
+ * so the list is duplicated here; `packages/client/src/provider-config-drift.test.ts`
+ * fails if the two drift.
+ */
+export const ASKDB_AI_PROVIDERS = ["openai", "azure", "foundry", "anthropic", "google", "gateway"];
 /**
  * Provider-portable reasoning/latency effort for AskDB model calls. Maps to
- * each provider's native knob by the `@askdb/ai-*` adapter (see `@askdb/ai`'s
+ * each provider's native knob by the provider adapter (see `@askdb/ai`'s
  * `resolveProviderOptions`). Keep aligned with `REASONING_EFFORTS` in
  * `@askdb/ai` (`packages/ai/src/reasoning.ts`).
  */

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,aAAa,EAAE,iBAAiB,CAAU,CAAC;AAG1E;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,OAAO;IACP,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IACP,QAAQ;CACA,CAAC;AAGX,2FAA2F;AAC3F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAGzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAU,CAAC;AAGxE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAGpF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAGrF,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,UAAU;IACV,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,WAAW;CACH,CAAC;AAGX;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU;IACV,aAAa;IACb,OAAO;IACP,SAAS;IACT,QAAQ;IACR,WAAW;CACH,CAAC;AAGX;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,UAAU;IACV,OAAO;IACP,QAAQ;IACR,WAAW;CACH,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,aAAa,EAAE,iBAAiB,CAAU,CAAC;AAG1E;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,OAAO;IACP,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IACP,QAAQ;CACA,CAAC;AAGX;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAG/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAU,CAAC;AAGxE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AAG5G;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAGrF,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,UAAU;IACV,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,WAAW;CACH,CAAC;AAGX;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU;IACV,aAAa;IACb,OAAO;IACP,SAAS;IACT,QAAQ;IACR,WAAW;CACH,CAAC;AAGX;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,UAAU;IACV,OAAO;IACP,QAAQ;IACR,WAAW;CACH,CAAC"}

package/dist/defaults.d.ts

@@ -2,12 +2,32 @@
  * Canonical defaults applied in {@link flattenAskDbConfig} when optional env-backed
  * fields are unset (missing, blank, or invalid after trim).
  */
+export declare const DEFAULT_OPENAI_LANGUAGE_MODEL = "gpt-4o-mini";
+/** @deprecated Use DEFAULT_OPENAI_LANGUAGE_MODEL. Removed at 1.0. */
 export declare const DEFAULT_OPENAI_CHAT_MODEL = "gpt-4o-mini";
 export declare const DEFAULT_AZURE_OPENAI_DEPLOYMENT = "gpt-4o-mini";
+export declare const DEFAULT_ANTHROPIC_LANGUAGE_MODEL = "claude-sonnet-4-6";
+/** @deprecated Use DEFAULT_ANTHROPIC_LANGUAGE_MODEL. Removed at 1.0. */
 export declare const DEFAULT_ANTHROPIC_CHAT_MODEL = "claude-sonnet-4-6";
+export declare const DEFAULT_GOOGLE_LANGUAGE_MODEL = "gemini-2.0-flash";
+/** @deprecated Use DEFAULT_GOOGLE_LANGUAGE_MODEL. Removed at 1.0. */
 export declare const DEFAULT_GOOGLE_CHAT_MODEL = "gemini-2.0-flash";
+export declare const DEFAULT_GATEWAY_LANGUAGE_MODEL = "openai/gpt-4o-mini";
+/** @deprecated Use DEFAULT_GATEWAY_LANGUAGE_MODEL. Removed at 1.0. */
+export declare const DEFAULT_GATEWAY_CHAT_MODEL = "openai/gpt-4o-mini";
 export declare const DEFAULT_INTROSPECT_OUTPUT_DIR = "./askdb/";
+/** Default model-call timeout for `@askdb/http-api` `POST /ask` (`httpApi.requestTimeoutMs`). */
+export declare const DEFAULT_HTTP_API_REQUEST_TIMEOUT_MS = 60000;
+/**
+ * Largest `httpApi.requestTimeoutMs`: the Node timer maximum (2^31 - 1 ms, about 24.8 days).
+ * A larger `AbortSignal.timeout()` fires after 1 ms, or throws `ERR_OUT_OF_RANGE` past 2^32 - 1.
+ */
+export declare const MAX_HTTP_API_REQUEST_TIMEOUT_MS = 2147483647;
 export declare const DEFAULT_LOCAL_POSTGRES_URL = "postgres://postgres:postgres@127.0.0.1:5432/postgres";
+/**
+ * @deprecated AskDB has no default embedding model: set `ai.embedding.model`. This is only the
+ * model a legacy `rag.embedder: "openai"` config translates to. Removed at 1.0.
+ */
 export declare const DEFAULT_RAG_EMBEDDING_MODEL = "text-embedding-3-small";
 /** Under the same visible tree as {@link DEFAULT_INTROSPECT_OUTPUT_DIR} (`./askdb/…`). */
 export declare const DEFAULT_RAG_FILE_BASE_PATH = "./askdb/rag";
@@ -19,8 +39,20 @@ export declare const DEFAULT_STUDIO_EXECUTE_TIMEOUT_MS = 30000;
 export declare const DEFAULT_STUDIO_EXECUTE_MAX_ROWS = 500;
 export declare const PGVECTOR_INDEX_STRATEGIES: readonly ["ivfflat", "hnsw", "none"];
 export type PgvectorIndexStrategyId = (typeof PGVECTOR_INDEX_STRATEGIES)[number];
-/** Same heuristics as Studio / `@askdb/rag` CLI for common OpenAI embedding models. */
+/**
+ * The width earlier versions assumed for an embedding model: 3072 for `text-embedding-3-large`,
+ * else 1536, whatever the provider.
+ *
+ * @deprecated AskDB no longer assumes a width: it learns it from the embedding model
+ * (`detectEmbeddingDimensions` in `@askdb/rag`). Removed at 1.0.
+ */
 export declare function defaultRagEmbeddingDimensions(model: string): number;
 export declare function parsePositiveInteger(value: string | number | undefined): number | undefined;
+/**
+ * Parse `httpApi.requestTimeoutMs` (or its flat key `ASKDB_HTTP_REQUEST_TIMEOUT_MS`).
+ * Returns `undefined` when unset; throws naming `source` unless the value is a positive
+ * integer no larger than {@link MAX_HTTP_API_REQUEST_TIMEOUT_MS}.
+ */
+export declare function parseHttpApiRequestTimeoutMs(value: string | number | undefined, source: string): number | undefined;
 export declare function normalizePgvectorIndexStrategy(raw: string | undefined): PgvectorIndexStrategyId;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,yBAAyB,gBAAgB,CAAC;AACvD,eAAO,MAAM,+BAA+B,gBAAgB,CAAC;AAC7D,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAChE,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAC5D,eAAO,MAAM,6BAA6B,aAAa,CAAC;AACxD,eAAO,MAAM,0BAA0B,yDAAyD,CAAC;AACjG,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AACpE,0FAA0F;AAC1F,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AACxD,eAAO,MAAM,qCAAqC,KAAK,CAAC;AACxD,eAAO,MAAM,+BAA+B,EAAG,MAAe,CAAC;AAC/D,2FAA2F;AAC3F,eAAO,MAAM,iCAAiC,QAAS,CAAC;AACxD,6EAA6E;AAC7E,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,eAAO,MAAM,yBAAyB,sCAAuC,CAAC;AAC9E,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjF,uFAAuF;AACvF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAU3F;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,uBAAuB,CAK/F"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,6BAA6B,gBAAgB,CAAC;AAC3D,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,gBAAgC,CAAC;AACvE,eAAO,MAAM,+BAA+B,gBAAgB,CAAC;AAC7D,eAAO,MAAM,gCAAgC,sBAAsB,CAAC;AACpE,wEAAwE;AACxE,eAAO,MAAM,4BAA4B,sBAAmC,CAAC;AAC7E,eAAO,MAAM,6BAA6B,qBAAqB,CAAC;AAChE,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,qBAAgC,CAAC;AACvE,eAAO,MAAM,8BAA8B,uBAAuB,CAAC;AACnE,sEAAsE;AACtE,eAAO,MAAM,0BAA0B,uBAAiC,CAAC;AACzE,eAAO,MAAM,6BAA6B,aAAa,CAAC;AACxD,iGAAiG;AACjG,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAC1D;;;GAGG;AACH,eAAO,MAAM,+BAA+B,aAAgB,CAAC;AAC7D,eAAO,MAAM,0BAA0B,yDAAyD,CAAC;AACjG;;;GAGG;AACH,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AACpE,0FAA0F;AAC1F,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AACxD,eAAO,MAAM,qCAAqC,KAAK,CAAC;AACxD,eAAO,MAAM,+BAA+B,EAAG,MAAe,CAAC;AAC/D,2FAA2F;AAC3F,eAAO,MAAM,iCAAiC,QAAS,CAAC;AACxD,6EAA6E;AAC7E,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,eAAO,MAAM,yBAAyB,sCAAuC,CAAC;AAC9E,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjF;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAU3F;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUnH;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,uBAAuB,CAK/F"}

package/dist/defaults.js

@@ -2,12 +2,32 @@
  * Canonical defaults applied in {@link flattenAskDbConfig} when optional env-backed
  * fields are unset (missing, blank, or invalid after trim).
  */
-export const DEFAULT_OPENAI_CHAT_MODEL = "gpt-4o-mini";
+export const DEFAULT_OPENAI_LANGUAGE_MODEL = "gpt-4o-mini";
+/** @deprecated Use DEFAULT_OPENAI_LANGUAGE_MODEL. Removed at 1.0. */
+export const DEFAULT_OPENAI_CHAT_MODEL = DEFAULT_OPENAI_LANGUAGE_MODEL;
 export const DEFAULT_AZURE_OPENAI_DEPLOYMENT = "gpt-4o-mini";
-export const DEFAULT_ANTHROPIC_CHAT_MODEL = "claude-sonnet-4-6";
-export const DEFAULT_GOOGLE_CHAT_MODEL = "gemini-2.0-flash";
+export const DEFAULT_ANTHROPIC_LANGUAGE_MODEL = "claude-sonnet-4-6";
+/** @deprecated Use DEFAULT_ANTHROPIC_LANGUAGE_MODEL. Removed at 1.0. */
+export const DEFAULT_ANTHROPIC_CHAT_MODEL = DEFAULT_ANTHROPIC_LANGUAGE_MODEL;
+export const DEFAULT_GOOGLE_LANGUAGE_MODEL = "gemini-2.0-flash";
+/** @deprecated Use DEFAULT_GOOGLE_LANGUAGE_MODEL. Removed at 1.0. */
+export const DEFAULT_GOOGLE_CHAT_MODEL = DEFAULT_GOOGLE_LANGUAGE_MODEL;
+export const DEFAULT_GATEWAY_LANGUAGE_MODEL = "openai/gpt-4o-mini";
+/** @deprecated Use DEFAULT_GATEWAY_LANGUAGE_MODEL. Removed at 1.0. */
+export const DEFAULT_GATEWAY_CHAT_MODEL = DEFAULT_GATEWAY_LANGUAGE_MODEL;
 export const DEFAULT_INTROSPECT_OUTPUT_DIR = "./askdb/";
+/** Default model-call timeout for `@askdb/http-api` `POST /ask` (`httpApi.requestTimeoutMs`). */
+export const DEFAULT_HTTP_API_REQUEST_TIMEOUT_MS = 60_000;
+/**
+ * Largest `httpApi.requestTimeoutMs`: the Node timer maximum (2^31 - 1 ms, about 24.8 days).
+ * A larger `AbortSignal.timeout()` fires after 1 ms, or throws `ERR_OUT_OF_RANGE` past 2^32 - 1.
+ */
+export const MAX_HTTP_API_REQUEST_TIMEOUT_MS = 2_147_483_647;
 export const DEFAULT_LOCAL_POSTGRES_URL = "postgres://postgres:postgres@127.0.0.1:5432/postgres";
+/**
+ * @deprecated AskDB has no default embedding model: set `ai.embedding.model`. This is only the
+ * model a legacy `rag.embedder: "openai"` config translates to. Removed at 1.0.
+ */
 export const DEFAULT_RAG_EMBEDDING_MODEL = "text-embedding-3-small";
 /** Under the same visible tree as {@link DEFAULT_INTROSPECT_OUTPUT_DIR} (`./askdb/…`). */
 export const DEFAULT_RAG_FILE_BASE_PATH = "./askdb/rag";
@@ -18,14 +38,15 @@ export const DEFAULT_STUDIO_EXECUTE_TIMEOUT_MS = 30_000;
 /** Default row cap for Studio execute results (`studio.execute.maxRows`). */
 export const DEFAULT_STUDIO_EXECUTE_MAX_ROWS = 500;
 export const PGVECTOR_INDEX_STRATEGIES = ["ivfflat", "hnsw", "none"];
-/** Same heuristics as Studio / `@askdb/rag` CLI for common OpenAI embedding models. */
+/**
+ * The width earlier versions assumed for an embedding model: 3072 for `text-embedding-3-large`,
+ * else 1536, whatever the provider.
+ *
+ * @deprecated AskDB no longer assumes a width: it learns it from the embedding model
+ * (`detectEmbeddingDimensions` in `@askdb/rag`). Removed at 1.0.
+ */
 export function defaultRagEmbeddingDimensions(model) {
-    const m = model.trim();
-    if (m === "text-embedding-3-large")
-        return 3072;
-    if (m === "text-embedding-ada-002")
-        return 1536;
-    return 1536;
+    return model.trim() === "text-embedding-3-large" ? 3072 : 1536;
 }
 export function parsePositiveInteger(value) {
     if (value === undefined)
@@ -41,6 +62,21 @@ export function parsePositiveInteger(value) {
         return undefined;
     return n;
 }
+/**
+ * Parse `httpApi.requestTimeoutMs` (or its flat key `ASKDB_HTTP_REQUEST_TIMEOUT_MS`).
+ * Returns `undefined` when unset; throws naming `source` unless the value is a positive
+ * integer no larger than {@link MAX_HTTP_API_REQUEST_TIMEOUT_MS}.
+ */
+export function parseHttpApiRequestTimeoutMs(value, source) {
+    if (value === undefined)
+        return undefined;
+    // A JavaScript config can pass any type; only numbers and numeric strings are parsed.
+    const n = typeof value === "number" || typeof value === "string" ? parsePositiveInteger(value) : undefined;
+    if (n === undefined || n > MAX_HTTP_API_REQUEST_TIMEOUT_MS) {
+        throw new Error(`askdb.config: invalid ${source} ${JSON.stringify(value)} (expected a positive integer number of milliseconds, at most ${MAX_HTTP_API_REQUEST_TIMEOUT_MS}).`);
+    }
+    return n;
+}
 export function normalizePgvectorIndexStrategy(raw) {
     if (raw === undefined || raw.trim() === "")
         return DEFAULT_PGVECTOR_INDEX_STRATEGY;

package/dist/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,aAAa,CAAC;AACvD,MAAM,CAAC,MAAM,+BAA+B,GAAG,aAAa,CAAC;AAC7D,MAAM,CAAC,MAAM,4BAA4B,GAAG,mBAAmB,CAAC;AAChE,MAAM,CAAC,MAAM,yBAAyB,GAAG,kBAAkB,CAAC;AAC5D,MAAM,CAAC,MAAM,6BAA6B,GAAG,UAAU,CAAC;AACxD,MAAM,CAAC,MAAM,0BAA0B,GAAG,sDAAsD,CAAC;AACjG,MAAM,CAAC,MAAM,2BAA2B,GAAG,wBAAwB,CAAC;AACpE,0FAA0F;AAC1F,MAAM,CAAC,MAAM,0BAA0B,GAAG,aAAa,CAAC;AACxD,MAAM,CAAC,MAAM,qCAAqC,GAAG,EAAE,CAAC;AACxD,MAAM,CAAC,MAAM,+BAA+B,GAAG,MAAe,CAAC;AAC/D,2FAA2F;AAC3F,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAC;AACxD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAEnD,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC;AAG9E,uFAAuF;AACvF,MAAM,UAAU,6BAA6B,CAAC,KAAa;IACzD,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACvB,IAAI,CAAC,KAAK,wBAAwB;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,CAAC,KAAK,wBAAwB;QAAE,OAAO,IAAI,CAAC;IAChD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAkC;IACrE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,CAAC;IACD,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACvB,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAC/B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACrD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,GAAuB;IACpE,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,+BAA+B,CAAC;IACnF,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC;IAC9D,MAAM,IAAI,KAAK,CAAC,mCAAmC,GAAG,qCAAqC,CAAC,CAAC;AAC/F,CAAC"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"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"}

package/dist/diagnostics.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether the `ASKDB_DEBUG` shell variable asks first-party binaries for debug diagnostics,
+ * such as the stack trace of an unexpected error.
+ *
+ * Reads `process.env` directly rather than the runtime snapshot, because it must work when
+ * `askdb.config.*` is missing or fails to load. Only `1` or `true` (case-insensitive) turn it on;
+ * `0`, `false`, and any other value leave it off.
+ */
+export declare function isAskDbDebugEnabled(): boolean;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAG7C"}

package/dist/diagnostics.js

@@ -0,0 +1,13 @@
+/**
+ * Whether the `ASKDB_DEBUG` shell variable asks first-party binaries for debug diagnostics,
+ * such as the stack trace of an unexpected error.
+ *
+ * Reads `process.env` directly rather than the runtime snapshot, because it must work when
+ * `askdb.config.*` is missing or fails to load. Only `1` or `true` (case-insensitive) turn it on;
+ * `0`, `false`, and any other value leave it off.
+ */
+export function isAskDbDebugEnabled() {
+    const raw = process.env.ASKDB_DEBUG?.trim().toLowerCase();
+    return raw === "1" || raw === "true";
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1D,OAAO,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,MAAM,CAAC;AACvC,CAAC"}

package/dist/flatten.d.ts

@@ -1,7 +1,14 @@
+import { type NormalizedAiEmbeddingSection, type NormalizedAiLanguageSection, type NormalizedAskDbConfig } from "./normalize.js";
 import type { AskDbConfig } from "./types.js";
+/** The env view of `ai.language`: its provider, its connection only, its model and reasoning. */
+export declare function aiLanguageEnv(section: NormalizedAiLanguageSection): Record<string, string>;
+/** The env view of `ai.embedding`: its provider, its connection only, and its model. Nothing from the language side. */
+export declare function aiEmbeddingEnv(section: NormalizedAiEmbeddingSection): Record<string, string>;
 /**
  * Flattens a nested {@link AskDbConfig} into canonical env keys for the runtime snapshot
- * (`AskDbEnvProjection.entries`).
+ * (`AskDbEnvProjection.entries`). Deprecated keys are translated first (see
+ * `normalizeAskDbConfig`); the AI keys come from the `ai.language` section's connection.
  */
 export declare function flattenAskDbConfig(config: AskDbConfig): Record<string, string>;
+export declare function flattenNormalizedAskDbConfig(config: NormalizedAskDbConfig): Record<string, string>;
 //# sourceMappingURL=flatten.d.ts.map

package/dist/flatten.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../src/flatten.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAIV,WAAW,EAUZ,MAAM,YAAY,CAAC;AA4FpB;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2M9E"}
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../src/flatten.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAA0B,WAAW,EAAE,MAAM,YAAY,CAAC;AAoEtE,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,OAAO,EAAE,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO1F;AAED,wHAAwH;AACxH,wBAAgB,cAAc,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM5F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE9E;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4KlG"}