@askdb/core 0.5.0-beta.0

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

@@ -0,0 +1,47 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import pino from "pino";
+function wrapPinoAsAskDbLogger(pinoLogger) {
+    return {
+        info(context, message) {
+            pinoLogger.info(context, message);
+        },
+        error(context, message) {
+            pinoLogger.error(context, message);
+        },
+        debug(context, message) {
+            pinoLogger.debug(context, message);
+        },
+    };
+}
+/**
+ * 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 function createAskDbLogger(options) {
+    const level = options.level ?? "silent";
+    if (level === "silent") {
+        return wrapPinoAsAskDbLogger(pino({ level: "silent" }));
+    }
+    const stderrOn = options.stderr !== false;
+    const destinations = [];
+    if (stderrOn) {
+        destinations.push(pino.destination(2));
+    }
+    if (options.logStdout) {
+        destinations.push(pino.destination(1));
+    }
+    if (options.logFile) {
+        mkdirSync(dirname(options.logFile), { recursive: true });
+        destinations.push(pino.destination({ dest: options.logFile, sync: true }));
+    }
+    if (destinations.length === 0) {
+        return wrapPinoAsAskDbLogger(pino({ level: "silent" }));
+    }
+    const dest = destinations.length === 1
+        ? destinations[0]
+        : pino.multistream(destinations.map((stream) => ({ stream })));
+    const pinoLogger = pino({ level }, dest).child({ correlationId: options.correlationId });
+    return wrapPinoAsAskDbLogger(pinoLogger);
+}
+//# sourceMappingURL=create-askdb-logger.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-askdb-logger.js","sourceRoot":"","sources":["../../src/logging/create-askdb-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,IAAI,MAAM,MAAM,CAAC;AAuBxB,SAAS,qBAAqB,CAAC,UAAsB;IACnD,OAAO;QACL,IAAI,CAAC,OAAgC,EAAE,OAAe;YACpD,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,OAAgC,EAAE,OAAe;YACrD,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACrC,CAAC;QACD,KAAK,CAAC,OAAgC,EAAE,OAAe;YACrD,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACrC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IACjE,MAAM,KAAK,GAAkB,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC;IACvD,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO,qBAAqB,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC;IAC1C,MAAM,YAAY,GAA6B,EAAE,CAAC;IAClD,IAAI,QAAQ,EAAE,CAAC;QACb,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,qBAAqB,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,IAAI,GACR,YAAY,CAAC,MAAM,KAAK,CAAC;QACvB,CAAC,CAAC,YAAY,CAAC,CAAC,CAAE;QAClB,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAEnE,MAAM,UAAU,GAAG,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACzF,OAAO,qBAAqB,CAAC,UAAU,CAAC,CAAC;AAC3C,CAAC"}

package/dist/logging/log-contract.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal structured-log contract intended for headless surfaces (CLI now; reused by servers later).
+ *
+ * This is deliberately small:
+ * - Tests should fail on removal/rename of required fields/events (drift).
+ * - Tests should tolerate additive fields/events.
+ */
+export declare const ASKDB_LOG_REQUIRED_FIELDS: readonly ["event", "correlationId"];
+/**
+ * Minimal event taxonomy for an end-to-end run.
+ *
+ * These are the best “merge bar” anchors for CI spawn tests because they appear
+ * across common paths without depending on optional execution.
+ */
+export declare const ASKDB_LOG_REQUIRED_EVENTS: readonly ["askdb.run.start", "askdb.pipeline.mode", "askdb.pipeline.generate.start", "askdb.pipeline.generate.complete", "askdb.run.end"];
+//# sourceMappingURL=log-contract.d.ts.map

package/dist/logging/log-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-contract.d.ts","sourceRoot":"","sources":["../../src/logging/log-contract.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,qCAAsC,CAAC;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,2IAMW,CAAC"}

package/dist/logging/log-contract.js

@@ -0,0 +1,23 @@
+import { AskDbLogEvent } from "./log-events.js";
+/**
+ * Minimal structured-log contract intended for headless surfaces (CLI now; reused by servers later).
+ *
+ * This is deliberately small:
+ * - Tests should fail on removal/rename of required fields/events (drift).
+ * - Tests should tolerate additive fields/events.
+ */
+export const ASKDB_LOG_REQUIRED_FIELDS = ["event", "correlationId"];
+/**
+ * Minimal event taxonomy for an end-to-end run.
+ *
+ * These are the best “merge bar” anchors for CI spawn tests because they appear
+ * across common paths without depending on optional execution.
+ */
+export const ASKDB_LOG_REQUIRED_EVENTS = [
+    AskDbLogEvent.RunStart,
+    AskDbLogEvent.PipelineMode,
+    AskDbLogEvent.PipelineGenerateStart,
+    AskDbLogEvent.PipelineGenerateComplete,
+    AskDbLogEvent.RunEnd,
+];
+//# sourceMappingURL=log-contract.js.map

package/dist/logging/log-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-contract.js","sourceRoot":"","sources":["../../src/logging/log-contract.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,OAAO,EAAE,eAAe,CAAU,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,aAAa,CAAC,QAAQ;IACtB,aAAa,CAAC,YAAY;IAC1B,aAAa,CAAC,qBAAqB;IACnC,aAAa,CAAC,wBAAwB;IACtC,aAAa,CAAC,MAAM;CAC2B,CAAC"}

package/dist/logging/log-events.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Stable `event` field values for structured logs (JSON lines).
+ * See Phase 2 spec: observability / correlation ID contract.
+ */
+export declare const AskDbLogEvent: {
+    readonly RunStart: "askdb.run.start";
+    readonly RunEnd: "askdb.run.end";
+    readonly RunError: "askdb.run.error";
+    /** Operating mode for this pipeline run (`mode` field). Emitted before NL→SQL. */
+    readonly PipelineMode: "askdb.pipeline.mode";
+    readonly PipelineGenerateStart: "askdb.pipeline.generate.start";
+    readonly PipelineGenerateComplete: "askdb.pipeline.generate.complete";
+    /** NL→SQL prompt DDL omitted sensitive tables/columns — counts only (no identifiers). */
+    readonly PromptSensitiveRedacted: "askdb.prompt.sensitive_redacted";
+    /** Sensitive identifiers included in DDL for grounding — counts only (see `listedSensitiveColumnCount`). */
+    readonly PromptSensitiveIdentifiersListed: "askdb.prompt.sensitive_identifiers_listed";
+    /** Generation failed after pipeline logging began (includes `phase`). */
+    readonly PipelineFailed: "askdb.pipeline.failed";
+    /**
+     * Retriever was supplied to `ask()` and used to synthesize a focused DDL
+     * block (counts only — `tablesEmitted`, `resultCount`, `k`, `threshold`).
+     */
+    readonly PipelineRetrievalUsed: "askdb.pipeline.retrieval.used";
+    /**
+     * Retriever was supplied but **not** used (`reason`: `below_threshold` |
+     * `schema_not_v2` | `no_results`). Lets operators tell "supplied but
+     * skipped" apart from "never wired up".
+     */
+    readonly PipelineRetrievalSkipped: "askdb.pipeline.retrieval.skipped";
+};
+export type AskDbLogEventName = (typeof AskDbLogEvent)[keyof typeof AskDbLogEvent];
+//# sourceMappingURL=log-events.d.ts.map

package/dist/logging/log-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-events.d.ts","sourceRoot":"","sources":["../../src/logging/log-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;IAIxB,kFAAkF;;;;IAIlF,yFAAyF;;IAEzF,4GAA4G;;IAE5G,yEAAyE;;IAEzE;;;OAGG;;IAEH;;;;OAIG;;CAEK,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC"}

package/dist/logging/log-events.js

@@ -0,0 +1,31 @@
+/**
+ * Stable `event` field values for structured logs (JSON lines).
+ * See Phase 2 spec: observability / correlation ID contract.
+ */
+export const AskDbLogEvent = {
+    RunStart: "askdb.run.start",
+    RunEnd: "askdb.run.end",
+    RunError: "askdb.run.error",
+    /** Operating mode for this pipeline run (`mode` field). Emitted before NL→SQL. */
+    PipelineMode: "askdb.pipeline.mode",
+    PipelineGenerateStart: "askdb.pipeline.generate.start",
+    PipelineGenerateComplete: "askdb.pipeline.generate.complete",
+    /** NL→SQL prompt DDL omitted sensitive tables/columns — counts only (no identifiers). */
+    PromptSensitiveRedacted: "askdb.prompt.sensitive_redacted",
+    /** Sensitive identifiers included in DDL for grounding — counts only (see `listedSensitiveColumnCount`). */
+    PromptSensitiveIdentifiersListed: "askdb.prompt.sensitive_identifiers_listed",
+    /** Generation failed after pipeline logging began (includes `phase`). */
+    PipelineFailed: "askdb.pipeline.failed",
+    /**
+     * Retriever was supplied to `ask()` and used to synthesize a focused DDL
+     * block (counts only — `tablesEmitted`, `resultCount`, `k`, `threshold`).
+     */
+    PipelineRetrievalUsed: "askdb.pipeline.retrieval.used",
+    /**
+     * Retriever was supplied but **not** used (`reason`: `below_threshold` |
+     * `schema_not_v2` | `no_results`). Lets operators tell "supplied but
+     * skipped" apart from "never wired up".
+     */
+    PipelineRetrievalSkipped: "askdb.pipeline.retrieval.skipped",
+};
+//# sourceMappingURL=log-events.js.map

package/dist/logging/log-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-events.js","sourceRoot":"","sources":["../../src/logging/log-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ,EAAE,iBAAiB;IAC3B,MAAM,EAAE,eAAe;IACvB,QAAQ,EAAE,iBAAiB;IAC3B,kFAAkF;IAClF,YAAY,EAAE,qBAAqB;IACnC,qBAAqB,EAAE,+BAA+B;IACtD,wBAAwB,EAAE,kCAAkC;IAC5D,yFAAyF;IACzF,uBAAuB,EAAE,iCAAiC;IAC1D,4GAA4G;IAC5G,gCAAgC,EAAE,2CAA2C;IAC7E,yEAAyE;IACzE,cAAc,EAAE,uBAAuB;IACvC;;;OAGG;IACH,qBAAqB,EAAE,+BAA+B;IACtD;;;;OAIG;IACH,wBAAwB,EAAE,kCAAkC;CACpD,CAAC"}

package/dist/logging/pino-supported-levels.d.ts

@@ -0,0 +1,9 @@
+import type { AskDbLogLevel } from "./create-askdb-logger.js";
+/**
+ * Valid `--log-level` / `ASKDB_LOG_LEVEL` strings: Pino's default levels from
+ * `pino.levels.values` plus `silent` (accepted by `LoggerOptions.level` but not a numeric level).
+ */
+export declare const SUPPORTED_ASKDB_LOG_LEVELS: ReadonlySet<string>;
+export declare function formatSupportedAskDbLogLevels(): string;
+export declare function isSupportedAskDbLogLevel(s: string): s is AskDbLogLevel;
+//# sourceMappingURL=pino-supported-levels.d.ts.map

package/dist/logging/pino-supported-levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pino-supported-levels.d.ts","sourceRoot":"","sources":["../../src/logging/pino-supported-levels.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAGzD,CAAC;AAEH,wBAAgB,6BAA6B,IAAI,MAAM,CAEtD;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,aAAa,CAEtE"}

package/dist/logging/pino-supported-levels.js

@@ -0,0 +1,16 @@
+import pino from "pino";
+/**
+ * Valid `--log-level` / `ASKDB_LOG_LEVEL` strings: Pino's default levels from
+ * `pino.levels.values` plus `silent` (accepted by `LoggerOptions.level` but not a numeric level).
+ */
+export const SUPPORTED_ASKDB_LOG_LEVELS = new Set([
+    ...Object.keys(pino.levels.values),
+    "silent",
+]);
+export function formatSupportedAskDbLogLevels() {
+    return [...SUPPORTED_ASKDB_LOG_LEVELS].sort().join(", ");
+}
+export function isSupportedAskDbLogLevel(s) {
+    return SUPPORTED_ASKDB_LOG_LEVELS.has(s);
+}
+//# sourceMappingURL=pino-supported-levels.js.map

package/dist/logging/pino-supported-levels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pino-supported-levels.js","sourceRoot":"","sources":["../../src/logging/pino-supported-levels.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAGxB;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAwB,IAAI,GAAG,CAAS;IAC7E,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAClC,QAAQ;CACT,CAAC,CAAC;AAEH,MAAM,UAAU,6BAA6B;IAC3C,OAAO,CAAC,GAAG,0BAA0B,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,CAAS;IAChD,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/modes/types.d.ts

@@ -0,0 +1,8 @@
+/** Operating modes selectable in Phase 2 v1 (see `docs/contracts/modes-v1.md`). */
+export declare const ASKDB_MODES_V1: readonly ["schema_only", "bounded_results"];
+export type AskDbModeV1 = (typeof ASKDB_MODES_V1)[number];
+/** Default mode when unset — strictest trust boundary. */
+export declare const DEFAULT_ASKDB_MODE: AskDbModeV1;
+export declare function parseAskDbModeV1(raw: string | undefined): AskDbModeV1;
+export declare function formatAskDbModesV1(): string;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/modes/types.ts"],"names":[],"mappings":"AAEA,mFAAmF;AACnF,eAAO,MAAM,cAAc,6CAA8C,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAI1D,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,EAAE,WAA2B,CAAC;AAE7D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAWrE;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/modes/types.js

@@ -0,0 +1,20 @@
+import { AskDbError } from "../errors.js";
+/** Operating modes selectable in Phase 2 v1 (see `docs/contracts/modes-v1.md`). */
+export const ASKDB_MODES_V1 = ["schema_only", "bounded_results"];
+const MODE_SET = new Set(ASKDB_MODES_V1);
+/** Default mode when unset — strictest trust boundary. */
+export const DEFAULT_ASKDB_MODE = "schema_only";
+export function parseAskDbModeV1(raw) {
+    if (raw === undefined || raw === "") {
+        return DEFAULT_ASKDB_MODE;
+    }
+    const n = raw.trim().toLowerCase().replace(/-/g, "_");
+    if (!MODE_SET.has(n)) {
+        throw new AskDbError(`Invalid mode: ${JSON.stringify(raw)}. Expected one of: ${ASKDB_MODES_V1.join(", ")}.`);
+    }
+    return n;
+}
+export function formatAskDbModesV1() {
+    return ASKDB_MODES_V1.join("|");
+}
+//# sourceMappingURL=types.js.map

package/dist/modes/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/modes/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,aAAa,EAAE,iBAAiB,CAAU,CAAC;AAG1E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,cAAc,CAAC,CAAC;AAEjD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,kBAAkB,GAAgB,aAAa,CAAC;AAE7D,MAAM,UAAU,gBAAgB,CAAC,GAAuB;IACtD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACpC,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IACD,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACtD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,UAAU,CAClB,iBAAiB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,sBAAsB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACvF,CAAC;IACJ,CAAC;IACD,OAAO,CAAgB,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClC,CAAC"}

package/dist/retrieval/synthesize-ddl.d.ts

@@ -0,0 +1,29 @@
+import type { NormalizedSchemaV2 } from "../schema/v2/normalized.js";
+import type { RetrievedResult } from "./types.js";
+/**
+ * Build a focused DDL block for NL→SQL prompts from retrieved chunks.
+ *
+ * Layout (decided in implementation, per Phase 8 spec's "open choice"):
+ *   1. Each table referenced by any retrieved chunk gets a TABLE block with
+ *      its full column definitions (so the model has complete column lists).
+ *   2. Column-chunk descriptions become inline `-- aliases / values / desc`
+ *      annotations on the matching column line.
+ *   3. CQL chunks land as a `-- common query language --` block under the
+ *      table.
+ *   4. Concept and question chunks attach as system-context paragraphs at
+ *      the bottom (before the question).
+ *
+ * Sensitive identifiers retain their `(sensitive)` tagging exactly as
+ * `formatSchemaV2ForNlToSql` does.
+ */
+export declare function synthesizeRetrievedDdl(args: {
+    schema: NormalizedSchemaV2;
+    results: RetrievedResult[];
+    /** Mirrors `formatSchemaV2ForNlToSql`'s `omitSensitiveIdentifiersFromPrompt`. */
+    omitSensitiveIdentifiersFromPrompt?: boolean;
+}): {
+    ddl: string;
+    tablesEmitted: number;
+    chunksUsed: number;
+};
+//# sourceMappingURL=synthesize-ddl.d.ts.map

package/dist/retrieval/synthesize-ddl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize-ddl.d.ts","sourceRoot":"","sources":["../../src/retrieval/synthesize-ddl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,iFAAiF;IACjF,kCAAkC,CAAC,EAAE,OAAO,CAAC;CAC9C,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAuI7D"}

package/dist/retrieval/synthesize-ddl.js

@@ -0,0 +1,160 @@
+/**
+ * Build a focused DDL block for NL→SQL prompts from retrieved chunks.
+ *
+ * Layout (decided in implementation, per Phase 8 spec's "open choice"):
+ *   1. Each table referenced by any retrieved chunk gets a TABLE block with
+ *      its full column definitions (so the model has complete column lists).
+ *   2. Column-chunk descriptions become inline `-- aliases / values / desc`
+ *      annotations on the matching column line.
+ *   3. CQL chunks land as a `-- common query language --` block under the
+ *      table.
+ *   4. Concept and question chunks attach as system-context paragraphs at
+ *      the bottom (before the question).
+ *
+ * Sensitive identifiers retain their `(sensitive)` tagging exactly as
+ * `formatSchemaV2ForNlToSql` does.
+ */
+export function synthesizeRetrievedDdl(args) {
+    const { schema, results } = args;
+    const omit = args.omitSensitiveIdentifiersFromPrompt === true;
+    const tableIds = new Set();
+    const cqlPerTable = new Map();
+    const concepts = [];
+    const questions = [];
+    const relationships = [];
+    for (const r of results) {
+        const p = r.payload;
+        switch (p.type) {
+            case "table": {
+                const tid = p.refs[0];
+                if (tid)
+                    tableIds.add(tid);
+                break;
+            }
+            case "column": {
+                const tid = p.refs[0];
+                if (tid)
+                    tableIds.add(tid);
+                break;
+            }
+            case "cql": {
+                const tid = p.refs[0];
+                if (tid) {
+                    tableIds.add(tid);
+                    const list = cqlPerTable.get(tid) ?? [];
+                    list.push(p);
+                    cqlPerTable.set(tid, list);
+                }
+                break;
+            }
+            case "question": {
+                questions.push(p);
+                if (p.refs[0])
+                    tableIds.add(p.refs[0]);
+                break;
+            }
+            case "concept": {
+                concepts.push(p);
+                for (const ref of p.refs) {
+                    if (ref.startsWith("table:")) {
+                        const hash = ref.indexOf("#");
+                        tableIds.add(hash === -1 ? ref : ref.slice(0, hash));
+                    }
+                }
+                break;
+            }
+            case "relationship": {
+                relationships.push(p);
+                for (const ref of p.refs) {
+                    if (ref.startsWith("table:") && !ref.includes("#"))
+                        tableIds.add(ref);
+                }
+                break;
+            }
+        }
+    }
+    const lines = [];
+    let tablesEmitted = 0;
+    for (const t of schema.tables) {
+        if (!tableIds.has(t.id))
+            continue;
+        tablesEmitted++;
+        const qualifiedName = `${t.schema}.${t.name}`;
+        const aliasNote = !t.sensitive && t.aliases?.length ? ` -- aliases: ${t.aliases.join(", ")}` : "";
+        lines.push(`TABLE ${qualifiedName}${aliasNote}`);
+        if (!t.sensitive && t.description)
+            lines.push(`-- ${t.description}`);
+        if (omit && t.sensitive) {
+            lines.push(`  (sensitive table — column definitions withheld from model context)`);
+            lines.push("");
+            continue;
+        }
+        for (const c of t.columns) {
+            if (omit && c.sensitive)
+                continue;
+            const flags = [];
+            if (c.primaryKey)
+                flags.push("PK");
+            flags.push(c.nullable ? "NULL" : "NOT NULL");
+            const sensitiveTag = c.sensitive || t.sensitive ? " (sensitive)" : "";
+            let line = `  - ${c.name} ${c.type} (${flags.join(" ")})${sensitiveTag}`;
+            if (!c.sensitive && !t.sensitive) {
+                const extras = [];
+                if (c.aliases?.length)
+                    extras.push(`aliases: ${c.aliases.join(", ")}`);
+                if (c.enum?.length)
+                    extras.push(`values: ${c.enum.join("|")}`);
+                if (c.description)
+                    extras.push(c.description);
+                if (extras.length)
+                    line += ` -- ${extras.join("; ")}`;
+            }
+            lines.push(line);
+        }
+        const cqlList = cqlPerTable.get(t.id);
+        if (cqlList && cqlList.length > 0 && !t.sensitive) {
+            lines.push(`-- common query language --`);
+            for (const cql of cqlList) {
+                const body = stripHeaderLine(cql.text);
+                for (const cqlLine of body.split("\n")) {
+                    lines.push(`-- ${cqlLine}`);
+                }
+            }
+        }
+        lines.push("");
+    }
+    if (relationships.length > 0) {
+        lines.push("-- relationships --");
+        for (const r of relationships) {
+            lines.push(`-- ${stripHeaderLine(r.text).replace(/\n+/g, " ")}`);
+        }
+        lines.push("");
+    }
+    if (concepts.length > 0) {
+        lines.push("-- concepts --");
+        for (const c of concepts) {
+            lines.push(`-- ${stripHeaderLine(c.text).replace(/\n+/g, "; ")}`);
+        }
+        lines.push("");
+    }
+    if (questions.length > 0) {
+        lines.push("-- example questions for context --");
+        for (const q of questions) {
+            lines.push(`-- ${stripHeaderLine(q.text).replace(/\n+/g, " ")}`);
+        }
+        lines.push("");
+    }
+    return {
+        ddl: lines.join("\n").trimEnd(),
+        tablesEmitted,
+        chunksUsed: results.length,
+    };
+}
+function stripHeaderLine(text) {
+    if (text.startsWith("#")) {
+        const nl = text.indexOf("\n");
+        return nl === -1 ? "" : text.slice(nl + 1).trim();
+    }
+    return text.trim();
+}
+//# sourceMappingURL=synthesize-ddl.js.map

package/dist/retrieval/synthesize-ddl.js.map

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

package/dist/retrieval/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal chunk-shaped payload that `@askdb/core` understands. The full
+ * `ChunkPayload` from `@askdb/rag` is assignable to this — splitting the
+ * shape this way avoids `@askdb/core` taking a hard dependency on
+ * `@askdb/rag` while keeping the retrieval seam in `ask()`.
+ */
+export type RetrievedChunkType = "table" | "column" | "cql" | "question" | "concept" | "relationship";
+export type RetrievedChunk = {
+    id: string;
+    type: RetrievedChunkType;
+    text: string;
+    schemaId: string;
+    refs: string[];
+    sensitive: boolean;
+};
+export type RetrievedResult = {
+    id: string;
+    score: number;
+    payload: RetrievedChunk;
+};
+/** Shape consumed by `ask({ retriever })`. */
+export type Retriever = (params: {
+    question: string;
+    k?: number;
+    filter?: {
+        schemaId?: string;
+        types?: RetrievedChunkType[];
+        refs?: string[];
+    };
+}) => Promise<RetrievedResult[]>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/retrieval/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,QAAQ,GACR,KAAK,GACL,UAAU,GACV,SAAS,GACT,cAAc,CAAC;AAEnB,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,CAAC;CACzB,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;QAC7B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;CACH,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC"}

package/dist/retrieval/types.js

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

package/dist/retrieval/types.js.map

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

package/dist/schema/format.d.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+export declare const askDbSchemaFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    tables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        columns: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            nullable: z.ZodOptional<z.ZodBoolean>;
+            primaryKey: z.ZodOptional<z.ZodBoolean>;
+            /** When true, column metadata is omitted from NL→SQL prompts (Phase 2 sensitive-field plumbing). */
+            sensitive: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            type: string;
+            nullable?: boolean | undefined;
+            primaryKey?: boolean | undefined;
+            sensitive?: boolean | undefined;
+        }, {
+            name: string;
+            type: string;
+            nullable?: boolean | undefined;
+            primaryKey?: boolean | undefined;
+            sensitive?: boolean | undefined;
+        }>, "many">;
+        /** When true, all column definitions for this table are withheld from NL→SQL prompts. */
+        sensitive: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        columns: {
+            name: string;
+            type: string;
+            nullable?: boolean | undefined;
+            primaryKey?: boolean | undefined;
+            sensitive?: boolean | undefined;
+        }[];
+        sensitive?: boolean | undefined;
+    }, {
+        name: string;
+        columns: {
+            name: string;
+            type: string;
+            nullable?: boolean | undefined;
+            primaryKey?: boolean | undefined;
+            sensitive?: boolean | undefined;
+        }[];
+        sensitive?: boolean | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    tables: {
+        name: string;
+        columns: {
+            name: string;
+            type: string;
+            nullable?: boolean | undefined;
+            primaryKey?: boolean | undefined;
+            sensitive?: boolean | undefined;
+        }[];
+        sensitive?: boolean | undefined;
+    }[];
+}, {
+    version: 1;
+    tables: {
+        name: string;
+        columns: {
+            name: string;
+            type: string;
+            nullable?: boolean | undefined;
+            primaryKey?: boolean | undefined;
+            sensitive?: boolean | undefined;
+        }[];
+        sensitive?: boolean | undefined;
+    }[];
+}>;
+//# sourceMappingURL=format.d.ts.map

package/dist/schema/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/schema/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,eAAO,MAAM,qBAAqB;;;;;;;;;YAXhC,oGAAoG;;;;;;;;;;;;;;;QAOpG,yFAAyF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAOzF,CAAC"}

package/dist/schema/format.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+const columnSchema = z.object({
+    name: z.string().min(1),
+    type: z.string().min(1),
+    nullable: z.boolean().optional(),
+    primaryKey: z.boolean().optional(),
+    /** When true, column metadata is omitted from NL→SQL prompts (Phase 2 sensitive-field plumbing). */
+    sensitive: z.boolean().optional(),
+});
+const tableSchema = z.object({
+    name: z.string().min(1),
+    columns: z.array(columnSchema).min(1),
+    /** When true, all column definitions for this table are withheld from NL→SQL prompts. */
+    sensitive: z.boolean().optional(),
+});
+export const askDbSchemaFileSchema = z.object({
+    version: z.literal(1),
+    tables: z.array(tableSchema).min(1),
+});
+//# sourceMappingURL=format.js.map

package/dist/schema/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/schema/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAClC,oGAAoG;IACpG,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,yFAAyF;IACzF,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACpC,CAAC,CAAC"}

package/dist/schema/normalize.d.ts

@@ -0,0 +1,31 @@
+import type { AskDbSchemaFile, NormalizedSchema } from "./types.js";
+export declare function normalizeAskDbSchema(parsed: AskDbSchemaFile): NormalizedSchema;
+/** Options for {@link formatSchemaForNlToSql}. */
+export type FormatNlToSqlOptions = {
+    /**
+     * When true, sensitive table/column identifiers are **omitted** from NL→SQL DDL (stricter).
+     * Default **false** — names are **included** and tagged `(sensitive)` so the model can ground SQL without hallucinating missing columns.
+     */
+    omitSensitiveIdentifiersFromPrompt?: boolean;
+};
+/** Stats when building DDL for NL→SQL (meaning depends on {@link FormatNlToSqlOptions.omitSensitiveIdentifiersFromPrompt}). */
+export type NlToSqlSchemaFormatStats = {
+    omitSensitiveIdentifiersFromPrompt: boolean;
+    /** When omitting: columns withheld from DDL. When including: always 0. */
+    redactedColumnCount: number;
+    /** When omitting: tables fully stubbed. When including: always 0. */
+    sensitiveTableStubCount: number;
+    /** When including: sensitive-marked columns listed in DDL (with `(sensitive)`). When omitting: always 0. */
+    listedSensitiveColumnCount: number;
+};
+/**
+ * Format schema for LLM prompts. By default, **includes** sensitive column/table names (tagged) so NL→SQL can
+ * ground identifiers; set {@link FormatNlToSqlOptions.omitSensitiveIdentifiersFromPrompt} to omit them.
+ */
+export declare function formatSchemaForNlToSql(schema: NormalizedSchema, options?: FormatNlToSqlOptions): {
+    ddl: string;
+    stats: NlToSqlSchemaFormatStats;
+};
+/** Same DDL as {@link formatSchemaForNlToSql} with default options (sensitive names included, tagged). */
+export declare function formatSchemaForPrompt(schema: NormalizedSchema, options?: FormatNlToSqlOptions): string;
+//# sourceMappingURL=normalize.d.ts.map