@askdb/core 0.5.0-beta.0

package/dist/ask.d.ts

@@ -0,0 +1,81 @@
+import type { LanguageModel, generateText as defaultGenerateText } from "ai";
+import type { AskDbLogger } from "./logging/askdb-logger.js";
+import type { AnyNormalizedSchema } from "./schema/types.js";
+import { type AskDbModeV1 } from "./modes/types.js";
+import type { Retriever } from "./retrieval/types.js";
+/** Options forwarded to a dialect's generator. Stable across dialects. */
+export type AskDialectGenerateOptions = {
+    logger?: AskDbLogger;
+    explain?: boolean;
+    omitSensitiveIdentifiersFromNlToSqlPrompt?: boolean;
+    generateText?: typeof defaultGenerateText;
+    prebuiltDdl?: string;
+};
+/** Output of a dialect's generator: validated SQL plus optional dialect-specific explain metadata. */
+export type AskDialectGenerateResult = {
+    sql: string;
+    explain?: unknown;
+};
+/** Adapter that knows how to turn a question + schema + model into validated dialect-specific SQL. */
+export type AskDialect = {
+    generate(question: string, schema: AnyNormalizedSchema, model: LanguageModel, options?: AskDialectGenerateOptions): Promise<AskDialectGenerateResult>;
+};
+/** Generic deps the pipeline forwards into the dialect (test-time mock for `generateText`, etc.). */
+export type AskGenerateDeps = {
+    generateText?: typeof defaultGenerateText;
+};
+export type AskPipelineOptions = {
+    question: string;
+    schema: AnyNormalizedSchema;
+    model: LanguageModel;
+    /** Required: the SQL dialect adapter to use (e.g. `postgresDialect` from `@askdb/postgres`). */
+    dialect: AskDialect;
+    /** When true, callers may inspect heuristic guardrail metadata (hosts/CLI). */
+    explain?: boolean;
+    /**
+     * When true, omit sensitive table/column names from NL→SQL DDL. Default false — names are included
+     * with `(sensitive)` tags so the model can ground SQL.
+     */
+    omitSensitiveIdentifiersFromNlToSqlPrompt?: boolean;
+    deps?: AskGenerateDeps;
+    /** Optional structured logger (host-provided — e.g. `createAskDbLogger` wraps Pino). */
+    logger?: AskDbLogger;
+    /**
+     * Trust boundary for optional post-execute model paths. Default {@link DEFAULT_ASKDB_MODE}.
+     * @see `docs/contracts/modes-v1.md`
+     */
+    mode?: AskDbModeV1;
+    /**
+     * Optional retriever from `@askdb/rag` (or any compatible implementation).
+     * When supplied **and** the schema's chunk count exceeds
+     * {@link retrievalThresholdChunks} (default 30), the retriever is called
+     * with the user question and the retrieved chunks replace the full DDL
+     * block in the NL→SQL prompt.
+     *
+     * When omitted, the Phase 5 behavior is preserved (full DDL inlined when
+     * v2 fields exist).
+     */
+    retriever?: Retriever;
+    /** Top-k forwarded to the retriever. Default 8. */
+    retrievalK?: number;
+    /**
+     * Chunk-count threshold above which retrieval is preferred. When the
+     * total chunk count for the schema is at or below this number, the full
+     * DDL is inlined even if a retriever is supplied. Default 30.
+     */
+    retrievalThresholdChunks?: number;
+    /**
+     * Total chunk count for the indexed schema. Hosts that built the index
+     * via `buildSchemaIndex` should pass `result.stats.chunksTotal` here so
+     * the threshold check is meaningful. Defaults to `Infinity` — i.e. always
+     * use the retriever when one is supplied — which matches the spec's
+     * "consumer decides" stance for hosts that don't surface a count.
+     */
+    totalSchemaChunkCount?: number;
+};
+export type AskPipelineResult = {
+    sql: string;
+    explain?: unknown;
+};
+export declare function ask(options: AskPipelineOptions): Promise<AskPipelineResult>;
+//# sourceMappingURL=ask.d.ts.map

package/dist/ask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,IAAI,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAItD,0EAA0E;AAC1E,MAAM,MAAM,yBAAyB,GAAG;IACtC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yCAAyC,CAAC,EAAE,OAAO,CAAC;IACpD,YAAY,CAAC,EAAE,OAAO,mBAAmB,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,sGAAsG;AACtG,MAAM,MAAM,wBAAwB,GAAG;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,sGAAsG;AACtG,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtC,CAAC;AAEF,qGAAqG;AACrG,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY,CAAC,EAAE,OAAO,mBAAmB,CAAC;CAC3C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,KAAK,EAAE,aAAa,CAAC;IACrB,gGAAgG;IAChG,OAAO,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,yCAAyC,CAAC,EAAE,OAAO,CAAC;IACpD,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,wFAAwF;IACxF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,wBAAsB,GAAG,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2BjF"}

package/dist/ask.js

@@ -0,0 +1,83 @@
+import { AskDbLogEvent } from "./logging/log-events.js";
+import { DEFAULT_ASKDB_MODE } from "./modes/types.js";
+import { synthesizeRetrievedDdl } from "./retrieval/synthesize-ddl.js";
+export async function ask(options) {
+    const logger = options.logger;
+    const mode = options.mode ?? DEFAULT_ASKDB_MODE;
+    logger?.info({ event: AskDbLogEvent.PipelineMode, mode }, "pipeline mode");
+    const explainRequested = options.explain ?? false;
+    const omitSensitive = options.omitSensitiveIdentifiersFromNlToSqlPrompt ?? false;
+    const prebuiltDdl = await maybeRetrieveDdl({
+        options,
+        logger,
+        omitSensitive,
+    });
+    const generated = await options.dialect.generate(options.question, options.schema, options.model, {
+        logger,
+        explain: explainRequested,
+        omitSensitiveIdentifiersFromNlToSqlPrompt: omitSensitive || undefined,
+        generateText: options.deps?.generateText,
+        prebuiltDdl,
+    });
+    const sql = generated.sql;
+    const explain = generated.explain;
+    return explain !== undefined ? { sql, explain } : { sql };
+}
+/** Default chunk-count threshold below which the full DDL is preferred. */
+const DEFAULT_RETRIEVAL_THRESHOLD_CHUNKS = 30;
+const DEFAULT_RETRIEVAL_K = 8;
+async function maybeRetrieveDdl(args) {
+    const { options, logger, omitSensitive } = args;
+    const retriever = options.retriever;
+    if (!retriever)
+        return undefined;
+    if (!isV2Schema(options.schema)) {
+        logger?.info({ event: AskDbLogEvent.PipelineRetrievalSkipped, reason: "schema_not_v2" }, "retriever supplied but schema is not v2 — skipping retrieval");
+        return undefined;
+    }
+    const threshold = options.retrievalThresholdChunks ?? DEFAULT_RETRIEVAL_THRESHOLD_CHUNKS;
+    const total = options.totalSchemaChunkCount ?? Number.POSITIVE_INFINITY;
+    if (total <= threshold) {
+        logger?.info({
+            event: AskDbLogEvent.PipelineRetrievalSkipped,
+            reason: "below_threshold",
+            totalChunks: total,
+            threshold,
+        }, "retriever supplied but schema is below threshold — using full DDL");
+        return undefined;
+    }
+    const k = options.retrievalK ?? DEFAULT_RETRIEVAL_K;
+    const results = await retriever({
+        question: options.question,
+        k,
+        filter: { schemaId: options.schema.schemaId },
+    });
+    if (results.length === 0) {
+        logger?.info({
+            event: AskDbLogEvent.PipelineRetrievalSkipped,
+            reason: "no_results",
+            k,
+            threshold,
+            totalChunks: total === Number.POSITIVE_INFINITY ? null : total,
+        }, "retriever returned no chunks — using full DDL");
+        return undefined;
+    }
+    const synth = synthesizeRetrievedDdl({
+        schema: options.schema,
+        results,
+        omitSensitiveIdentifiersFromPrompt: omitSensitive,
+    });
+    logger?.info({
+        event: AskDbLogEvent.PipelineRetrievalUsed,
+        k,
+        resultCount: results.length,
+        tablesEmitted: synth.tablesEmitted,
+        threshold,
+        totalChunks: total === Number.POSITIVE_INFINITY ? null : total,
+    }, "retriever supplied focused DDL");
+    return synth.ddl;
+}
+function isV2Schema(schema) {
+    return "schemaId" in schema;
+}
+//# sourceMappingURL=ask.js.map

package/dist/ask.js.map

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

package/dist/enrichment/index.d.ts

@@ -0,0 +1,4 @@
+export { ENRICHMENT_SYSTEM_PROMPT, buildEnrichmentUserPrompt, } from "./prompt.js";
+export { parseCandidates, suggestEnrichment, type SuggestEnrichmentDeps, } from "./suggest.js";
+export type { EnrichmentCandidate, EnrichmentContext, EnrichmentTarget, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/enrichment/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/enrichment/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/enrichment/index.js

@@ -0,0 +1,3 @@
+export { ENRICHMENT_SYSTEM_PROMPT, buildEnrichmentUserPrompt, } from "./prompt.js";
+export { parseCandidates, suggestEnrichment, } from "./suggest.js";
+//# sourceMappingURL=index.js.map

package/dist/enrichment/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/enrichment/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,iBAAiB,GAElB,MAAM,cAAc,CAAC"}

package/dist/enrichment/prompt.d.ts

@@ -0,0 +1,4 @@
+import type { EnrichmentContext, EnrichmentTarget } from "./types.js";
+export declare const ENRICHMENT_SYSTEM_PROMPT = "You enrich AskDB Schema v2 describable metadata.\n\nRules:\n- Be concise. Descriptions: one sentence, no marketing language.\n- Aliases: 2\u20134 lowercase, comma-separated, the way people *say* the thing\n  in plain English. No quotes, no synonyms of synonyms.\n- Common query language: 2\u20134 short bullet lines mapping a colloquial term\n  to the SQL filter or aggregation it implies.\n- Never invent columns, tables, or relationships not in the schema.\n- Never suggest values for sensitive columns (they will be excluded by RAG).\n- Reply with 1\u20133 candidate options separated by exactly the line \"---\".\n  Do not number, prefix, or label the candidates.";
+export declare function buildEnrichmentUserPrompt(target: EnrichmentTarget, ctx: EnrichmentContext): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/enrichment/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/enrichment/prompt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEtE,eAAO,MAAM,wBAAwB,gqBAWa,CAAC;AAEnD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,iBAAiB,GACrB,MAAM,CAuBR"}

package/dist/enrichment/prompt.js

@@ -0,0 +1,72 @@
+export const ENRICHMENT_SYSTEM_PROMPT = `You enrich AskDB Schema v2 describable metadata.
+
+Rules:
+- Be concise. Descriptions: one sentence, no marketing language.
+- Aliases: 2–4 lowercase, comma-separated, the way people *say* the thing
+  in plain English. No quotes, no synonyms of synonyms.
+- Common query language: 2–4 short bullet lines mapping a colloquial term
+  to the SQL filter or aggregation it implies.
+- Never invent columns, tables, or relationships not in the schema.
+- Never suggest values for sensitive columns (they will be excluded by RAG).
+- Reply with 1–3 candidate options separated by exactly the line "---".
+  Do not number, prefix, or label the candidates.`;
+export function buildEnrichmentUserPrompt(target, ctx) {
+    const lines = [];
+    lines.push(`Schema: ${ctx.schemaId}`);
+    lines.push(`Table: ${qualifiedName(target.table)}`);
+    // Always include the column list for context.
+    lines.push("Columns:");
+    for (const c of target.table.columns) {
+        lines.push(`  - ${describeColumn(c)}`);
+    }
+    if (ctx.neighbors && ctx.neighbors.length > 0) {
+        lines.push("");
+        lines.push("Related tables (FK neighbors):");
+        for (const t of ctx.neighbors) {
+            lines.push(`  - ${qualifiedName(t)} (${t.columns.length} columns)`);
+        }
+    }
+    lines.push("");
+    lines.push(targetInstruction(target));
+    return lines.join("\n");
+}
+function targetInstruction(target) {
+    switch (target.kind) {
+        case "table-description":
+            return `Suggest a one-sentence description of what the \`${target.table.name}\` table holds and what each row represents.`;
+        case "table-aliases":
+            return `Suggest 2–4 short aliases (comma-separated) people might use to refer to the \`${target.table.name}\` table in plain English.`;
+        case "table-primary-entity":
+            return `Suggest the primary entity (a single noun) that one row of \`${target.table.name}\` represents.`;
+        case "column-description": {
+            const col = findColumn(target.table, target.columnId);
+            return `Suggest a one-sentence description of the \`${col.name}\` column (type \`${col.type}\`) on \`${target.table.name}\`.`;
+        }
+        case "column-aliases": {
+            const col = findColumn(target.table, target.columnId);
+            return `Suggest 2–4 short aliases (comma-separated) people might use for the \`${col.name}\` column on \`${target.table.name}\`.`;
+        }
+        case "common-query-language":
+            return `Suggest 2–4 "common query language" bullet lines for \`${target.table.name}\` that map colloquial business terms to the SQL conditions they imply.`;
+    }
+}
+function describeColumn(c) {
+    const parts = [c.name, c.type];
+    if (c.primaryKey)
+        parts.push("[pk]");
+    if (c.sensitive)
+        parts.push("[sensitive]");
+    if (c.nullable)
+        parts.push("[nullable]");
+    return parts.join(" ");
+}
+function findColumn(table, columnId) {
+    const col = table.columns.find((c) => c.id === columnId);
+    if (!col)
+        throw new Error(`Column not found: ${columnId} in ${qualifiedName(table)}`);
+    return col;
+}
+function qualifiedName(t) {
+    return `${t.schema}.${t.name}`;
+}
+//# sourceMappingURL=prompt.js.map

package/dist/enrichment/prompt.js.map

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

package/dist/enrichment/suggest.d.ts

@@ -0,0 +1,23 @@
+import type { LanguageModel } from "ai";
+import { generateText as defaultGenerateText } from "ai";
+import type { EnrichmentCandidate, EnrichmentContext, EnrichmentTarget } from "./types.js";
+export type SuggestEnrichmentDeps = {
+    generateText?: typeof defaultGenerateText;
+    /** Optional cap on the number of candidates returned. Default 3. */
+    maxCandidates?: number;
+    /** Sampling temperature. Default 0.4 — small variety, mostly grounded. */
+    temperature?: number;
+};
+/**
+ * Ask the model for 1–3 enrichment candidates for the given target. The model
+ * is expected to reply with candidates separated by lines containing only `---`.
+ *
+ * Falls back to a single candidate if no `---` separators are present.
+ */
+export declare function suggestEnrichment(target: EnrichmentTarget, context: EnrichmentContext, model: LanguageModel, deps?: SuggestEnrichmentDeps): Promise<EnrichmentCandidate[]>;
+/**
+ * Parse the model's reply into candidates. Splits on lines containing only
+ * three or more dashes (`---`, `----`, …). Trims each candidate; drops empties.
+ */
+export declare function parseCandidates(raw: string, max: number): EnrichmentCandidate[];
+//# sourceMappingURL=suggest.d.ts.map

package/dist/enrichment/suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../src/enrichment/suggest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,IAAI,CAAC;AAKzD,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,CAAC,EAAE,OAAO,mBAAmB,CAAC;IAC1C,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,aAAa,EACpB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAYhC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAU/E"}

package/dist/enrichment/suggest.js

@@ -0,0 +1,38 @@
+import { generateText as defaultGenerateText } from "ai";
+import { ENRICHMENT_SYSTEM_PROMPT, buildEnrichmentUserPrompt, } from "./prompt.js";
+/**
+ * Ask the model for 1–3 enrichment candidates for the given target. The model
+ * is expected to reply with candidates separated by lines containing only `---`.
+ *
+ * Falls back to a single candidate if no `---` separators are present.
+ */
+export async function suggestEnrichment(target, context, model, deps = {}) {
+    const generateText = deps.generateText ?? defaultGenerateText;
+    const maxCandidates = deps.maxCandidates ?? 3;
+    const result = await generateText({
+        model,
+        system: ENRICHMENT_SYSTEM_PROMPT,
+        prompt: buildEnrichmentUserPrompt(target, context),
+        temperature: deps.temperature ?? 0.4,
+    });
+    const text = result.text;
+    return parseCandidates(text, maxCandidates);
+}
+/**
+ * Parse the model's reply into candidates. Splits on lines containing only
+ * three or more dashes (`---`, `----`, …). Trims each candidate; drops empties.
+ */
+export function parseCandidates(raw, max) {
+    const parts = raw.split(/^-{3,}\s*$/m);
+    const candidates = [];
+    for (const part of parts) {
+        const text = part.trim();
+        if (!text)
+            continue;
+        candidates.push({ text });
+        if (candidates.length >= max)
+            break;
+    }
+    return candidates;
+}
+//# sourceMappingURL=suggest.js.map

package/dist/enrichment/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../../src/enrichment/suggest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,IAAI,CAAC;AACzD,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAerB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAwB,EACxB,OAA0B,EAC1B,KAAoB,EACpB,OAA8B,EAAE;IAEhC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,mBAAmB,CAAC;IAC9D,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;IAE9C,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;QAChC,KAAK;QACL,MAAM,EAAE,wBAAwB;QAChC,MAAM,EAAE,yBAAyB,CAAC,MAAM,EAAE,OAAO,CAAC;QAClD,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,GAAG;KACrC,CAAC,CAAC;IACH,MAAM,IAAI,GAAI,MAA2B,CAAC,IAAI,CAAC;IAC/C,OAAO,eAAe,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,GAAW;IACtD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,UAAU,GAA0B,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1B,IAAI,UAAU,CAAC,MAAM,IAAI,GAAG;YAAE,MAAM;IACtC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/enrichment/types.d.ts

@@ -0,0 +1,44 @@
+import type { V2Table } from "../schema/v2/physical.js";
+/**
+ * What to suggest for. The TUI builds one of these per active prompt and asks
+ * `suggestEnrichment` for 1–3 candidates the user reviews and confirms.
+ */
+export type EnrichmentTarget = {
+    kind: "table-description";
+    table: V2Table;
+} | {
+    kind: "table-aliases";
+    table: V2Table;
+} | {
+    kind: "table-primary-entity";
+    table: V2Table;
+} | {
+    kind: "column-description";
+    table: V2Table;
+    columnId: string;
+} | {
+    kind: "column-aliases";
+    table: V2Table;
+    columnId: string;
+} | {
+    kind: "common-query-language";
+    table: V2Table;
+};
+/**
+ * One suggestion candidate. For free-text fields, `text` is the value.
+ * For list fields (aliases), the TUI splits on `,` after editing.
+ */
+export type EnrichmentCandidate = {
+    /** The suggested text. Whitespace at the ends is stripped. */
+    text: string;
+};
+/**
+ * Optional context: neighboring tables (joined via FK) and the schema id, so
+ * the model can ground suggestions beyond the immediate table.
+ */
+export type EnrichmentContext = {
+    schemaId: string;
+    /** Tables linked to the target table by foreign keys. Capped by the caller. */
+    neighbors?: V2Table[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/enrichment/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/enrichment/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;CACvB,CAAC"}

package/dist/enrichment/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/enrichment/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/enrichment/types.ts"],"names":[],"mappings":""}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+export declare class AskDbError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class SchemaParseError extends AskDbError {
+    constructor(message: string, cause?: unknown);
+}
+/** Machine-readable ids for CLI and logs (Phase 2 guardrails). */
+export type SqlValidationRuleCode = "SQL_EMPTY" | "SQL_MULTI_STATEMENT" | "SQL_COMMENT" | "SQL_NOT_SELECT_OR_WITH" | "SQL_FORBIDDEN_KEYWORD";
+export declare class SqlValidationError extends AskDbError {
+    readonly rule: SqlValidationRuleCode;
+    /** Extra human context (why the rule exists, remediation). */
+    readonly hint?: string | undefined;
+    constructor(message: string, rule: SqlValidationRuleCode, 
+    /** Extra human context (why the rule exists, remediation). */
+    hint?: string | undefined);
+}
+export declare class SqlGenerationError extends AskDbError {
+    constructor(message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAW,SAAQ,KAAK;aAGjB,KAAK,CAAC,EAAE,OAAO;gBAD/B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AAED,qBAAa,gBAAiB,SAAQ,UAAU;gBAClC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,kEAAkE;AAClE,MAAM,MAAM,qBAAqB,GAC7B,WAAW,GACX,qBAAqB,GACrB,aAAa,GACb,wBAAwB,GACxB,uBAAuB,CAAC;AAE5B,qBAAa,kBAAmB,SAAQ,UAAU;aAG9B,IAAI,EAAE,qBAAqB;IAC3C,8DAA8D;aAC9C,IAAI,CAAC,EAAE,MAAM;gBAH7B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,qBAAqB;IAC3C,8DAA8D;IAC9C,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED,qBAAa,kBAAmB,SAAQ,UAAU;gBACpC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C"}

package/dist/errors.js

@@ -0,0 +1,33 @@
+export class AskDbError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "AskDbError";
+    }
+}
+export class SchemaParseError extends AskDbError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = "SchemaParseError";
+    }
+}
+export class SqlValidationError extends AskDbError {
+    rule;
+    hint;
+    constructor(message, rule, 
+    /** Extra human context (why the rule exists, remediation). */
+    hint) {
+        super(message);
+        this.rule = rule;
+        this.hint = hint;
+        this.name = "SqlValidationError";
+    }
+}
+export class SqlGenerationError extends AskDbError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = "SqlGenerationError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,UAAW,SAAQ,KAAK;IAGjB;IAFlB,YACE,OAAe,EACC,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAC9C,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAUD,MAAM,OAAO,kBAAmB,SAAQ,UAAU;IAG9B;IAEA;IAJlB,YACE,OAAe,EACC,IAA2B;IAC3C,8DAA8D;IAC9C,IAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAuB;QAE3B,SAAI,GAAJ,IAAI,CAAS;QAG7B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,UAAU;IAChD,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export * from "./errors.js";
+export { ask, type AskPipelineOptions, type AskPipelineResult, type AskDialect, type AskDialectGenerateOptions, type AskDialectGenerateResult, type AskGenerateDeps, } from "./ask.js";
+export { parseAskDbModeV1, formatAskDbModesV1, DEFAULT_ASKDB_MODE, ASKDB_MODES_V1, type AskDbModeV1, } from "./modes/types.js";
+export { AskDbLogEvent } from "./logging/log-events.js";
+export type { AskDbLogger } from "./logging/askdb-logger.js";
+export { ASKDB_LOG_REQUIRED_EVENTS, ASKDB_LOG_REQUIRED_FIELDS, } from "./logging/log-contract.js";
+export { createAskDbLogger, type AskDbLogLevel, type CreateAskDbLoggerOptions, } from "./logging/create-askdb-logger.js";
+export { formatSupportedAskDbLogLevels, isSupportedAskDbLogLevel, SUPPORTED_ASKDB_LOG_LEVELS, } from "./logging/pino-supported-levels.js";
+export { loadNormalizedSchemaFromJson, parseAskDbSchemaJson } from "./schema/parse.js";
+export type { AskDbSchemaFile, NormalizedSchema, AnyNormalizedSchema, } from "./schema/types.js";
+export { loadSchema, loadSchemaFromJson, parseTableMarkdown, parseConceptsMarkdown, writeTableMarkdown, writeConceptsMarkdown, formatSchemaV2ForNlToSql, v2SchemaJsonSchema, v2TableSchema, v2ColumnSchema, v2TableFrontmatterSchema, v2ColumnFrontmatterSchema, v2ConceptsFrontmatterSchema, v2ConceptSchema, RECOGNIZED_H2_SECTIONS, } from "./schema/v2/index.js";
+export type { V2SchemaJson, V2Table, V2Column, V2TableFrontmatter, V2ColumnFrontmatter, V2ConceptsFrontmatter, V2Concept, ParsedTableMarkdown, ParsedConceptsMarkdown, RecognizedH2Section, NormalizedSchemaV2, NormalizedV2Table, NormalizedV2Column, SchemaV2Warning, } from "./schema/v2/index.js";
+export { ENRICHMENT_SYSTEM_PROMPT, buildEnrichmentUserPrompt, parseCandidates, suggestEnrichment, } from "./enrichment/index.js";
+export type { EnrichmentCandidate, EnrichmentContext, EnrichmentTarget, SuggestEnrichmentDeps, } from "./enrichment/index.js";
+export { formatSchemaForNlToSql, formatSchemaForPrompt, normalizeAskDbSchema, type FormatNlToSqlOptions, type NlToSqlSchemaFormatStats, } from "./schema/normalize.js";
+export { extractSqlFromModelText } from "./sql/extract-sql.js";
+export { resolveAskDbAiConfig, resolveAskDbEmbeddingConfig, createAskDbLanguageModel, createAskDbLanguageModelFromEnv, createAskDbEmbeddingModel, createAskDbEmbeddingModelFromEnv, askDbAiKeyMissingMessage, type AskDbAiProvider, type AskDbAiConfig, type AskDbAiEnv, type ResolveAskDbAiConfigOptions, type ResolveAskDbEmbeddingConfigOptions, type CreateAskDbEmbeddingModelOptions, } from "./ai/provider.js";
+export type { Retriever, RetrievedChunk, RetrievedChunkType, RetrievedResult, } from "./retrieval/types.js";
+export { synthesizeRetrievedDdl } from "./retrieval/synthesize-ddl.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,GAAG,EACH,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,wBAAwB,GAC9B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACvF,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,eAAe,EACf,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,SAAS,EACT,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,eAAe,EACf,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,yBAAyB,EACzB,gCAAgC,EAChC,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,2BAA2B,EAChC,KAAK,kCAAkC,EACvC,KAAK,gCAAgC,GACtC,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+export * from "./errors.js";
+export { ask, } from "./ask.js";
+export { parseAskDbModeV1, formatAskDbModesV1, DEFAULT_ASKDB_MODE, ASKDB_MODES_V1, } from "./modes/types.js";
+export { AskDbLogEvent } from "./logging/log-events.js";
+export { ASKDB_LOG_REQUIRED_EVENTS, ASKDB_LOG_REQUIRED_FIELDS, } from "./logging/log-contract.js";
+export { createAskDbLogger, } from "./logging/create-askdb-logger.js";
+export { formatSupportedAskDbLogLevels, isSupportedAskDbLogLevel, SUPPORTED_ASKDB_LOG_LEVELS, } from "./logging/pino-supported-levels.js";
+export { loadNormalizedSchemaFromJson, parseAskDbSchemaJson } from "./schema/parse.js";
+export { loadSchema, loadSchemaFromJson, parseTableMarkdown, parseConceptsMarkdown, writeTableMarkdown, writeConceptsMarkdown, formatSchemaV2ForNlToSql, v2SchemaJsonSchema, v2TableSchema, v2ColumnSchema, v2TableFrontmatterSchema, v2ColumnFrontmatterSchema, v2ConceptsFrontmatterSchema, v2ConceptSchema, RECOGNIZED_H2_SECTIONS, } from "./schema/v2/index.js";
+export { ENRICHMENT_SYSTEM_PROMPT, buildEnrichmentUserPrompt, parseCandidates, suggestEnrichment, } from "./enrichment/index.js";
+export { formatSchemaForNlToSql, formatSchemaForPrompt, normalizeAskDbSchema, } from "./schema/normalize.js";
+export { extractSqlFromModelText } from "./sql/extract-sql.js";
+export { resolveAskDbAiConfig, resolveAskDbEmbeddingConfig, createAskDbLanguageModel, createAskDbLanguageModelFromEnv, createAskDbEmbeddingModel, createAskDbEmbeddingModelFromEnv, askDbAiKeyMissingMessage, } from "./ai/provider.js";
+export { synthesizeRetrievedDdl } from "./retrieval/synthesize-ddl.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,GAAG,GAOJ,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,GAEf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,iBAAiB,GAGlB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAMvF,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,eAAe,EACf,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,eAAe,EACf,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,yBAAyB,EACzB,gCAAgC,EAChC,wBAAwB,GAOzB,MAAM,kBAAkB,CAAC;AAO1B,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/logging/askdb-logger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Structured logging port for the pipeline (`@askdb/core`).
+ * Keeps NL→SQL and execution free of vendor logger types (DIP).
+ *
+ * Implementations may wrap Pino, OpenTelemetry, or no-ops — consumers pass an instance from the host (CLI, HTTP, MCP).
+ */
+export type AskDbLogger = {
+    info(context: Record<string, unknown>, message: string): void;
+    error(context: Record<string, unknown>, message: string): void;
+    /** Optional — used for prompt redaction notices without leaking sensitive identifiers. */
+    debug?(context: Record<string, unknown>, message: string): void;
+};
+//# sourceMappingURL=askdb-logger.d.ts.map

package/dist/logging/askdb-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"askdb-logger.d.ts","sourceRoot":"","sources":["../../src/logging/askdb-logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/D,0FAA0F;IAC1F,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjE,CAAC"}

package/dist/logging/askdb-logger.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=askdb-logger.js.map

package/dist/logging/askdb-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"askdb-logger.js","sourceRoot":"","sources":["../../src/logging/askdb-logger.ts"],"names":[],"mappings":""}

package/dist/logging/create-askdb-logger.d.ts

@@ -0,0 +1,25 @@
+import pino from "pino";
+import type { AskDbLogger } from "./askdb-logger.js";
+/** Pino levels plus `silent` (no output). */
+export type AskDbLogLevel = pino.LevelWithSilent;
+export type CreateAskDbLoggerOptions = {
+    /** Included on every log line via `pino.child`. */
+    correlationId: string;
+    /** Default `silent` — no structured logs unless overridden. */
+    level?: AskDbLogLevel;
+    /**
+     * Write JSON logs to stderr (recommended for CLI so stdout stays clean for results).
+     * Default true when logging is enabled and no sinks are disabled explicitly.
+     */
+    stderr?: boolean;
+    /** Append JSON logs to this file path (parent directories are created). */
+    logFile?: string;
+    /** Duplicate logs to stdout (e.g. piping aggregated output). */
+    logStdout?: boolean;
+};
+/**
+ * Builds an {@link AskDbLogger} backed by Pino (multi-destination per ADR 0001).
+ * Uses a single `destination` when only one sink is configured (simpler flushing); otherwise `pino.multistream`.
+ */
+export declare function createAskDbLogger(options: CreateAskDbLoggerOptions): AskDbLogger;
+//# sourceMappingURL=create-askdb-logger.d.ts.map

package/dist/logging/create-askdb-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-askdb-logger.d.ts","sourceRoot":"","sources":["../../src/logging/create-askdb-logger.ts"],"names":[],"mappings":"AAEA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,6CAA6C;AAC7C,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC;AAEjD,MAAM,MAAM,wBAAwB,GAAG;IACrC,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAgBF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,WAAW,CA8BhF"}