@deepagents/text2sql 6.1.0 → 7.0.0

package/dist/lib/adapters/duckdb/index.js

@@ -0,0 +1,1933 @@
+// packages/text2sql/src/lib/adapters/groundings/abstract.grounding.ts
+function filterColumns(columns, filter) {
+  if (Array.isArray(filter)) {
+    return columns.filter((col) => filter.includes(col.name));
+  }
+  if (filter instanceof RegExp) {
+    return columns.filter((col) => filter.test(col.name));
+  }
+  return columns.filter((col) => filter(col.name));
+}
+function applyColumnFilter(entity, columnsConfig) {
+  if (!columnsConfig) return entity;
+  const filter = columnsConfig[entity.name];
+  if (!filter) return entity;
+  return { ...entity, columns: filterColumns(entity.columns, filter) };
+}
+var AbstractGrounding = class {
+  /**
+   * Grounding identifier for debugging/logging.
+   */
+  name;
+  phase;
+  constructor(name, phase) {
+    this.name = name;
+    this.phase = phase;
+  }
+  /**
+   * Populate ctx with the tables/views this grounding makes available for scope
+   * resolution. Annotators decorate entities other groundings produced and add
+   * no membership, so the default is a no-op; entity-producing groundings
+   * override it. This lets scope resolution skip the annotators' metadata scans.
+   *
+   * @param _ctx - Shared context for accumulating entity membership
+   */
+  async contributeEntities(_ctx) {
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/column-stats.grounding.ts
+var ColumnStatsGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("columnStats", "column_stats");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with statistics.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    const total = allContainers.length;
+    for (let i = 0; i < allContainers.length; i++) {
+      const container = allContainers[i];
+      ctx.onProgress({
+        type: "phase:progress",
+        phase: "column_stats",
+        table: container.name,
+        message: `Collecting stats for ${container.name}...`,
+        current: i + 1,
+        total
+      });
+      for (const column2 of container.columns) {
+        try {
+          const stats = await this.collectStats(container.name, column2);
+          if (stats) {
+            column2.stats = stats;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting stats for",
+            container.name,
+            column2.name,
+            error
+          );
+        }
+      }
+    }
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/column-values.grounding.ts
+var ColumnValuesGrounding = class extends AbstractGrounding {
+  lowCardinalityLimit;
+  maxValueLength;
+  constructor(config = {}) {
+    super("columnValues", "column_values");
+    this.lowCardinalityLimit = config.lowCardinalityLimit ?? 20;
+    this.maxValueLength = config.maxValueLength ?? 100;
+  }
+  /**
+   * Get values for native ENUM type columns.
+   * Return undefined if column is not an ENUM type.
+   * Default implementation returns undefined (no native ENUM support).
+   */
+  async collectEnumValues(_tableName, _column) {
+    return void 0;
+  }
+  /**
+   * Parse CHECK constraint for enum-like IN clause.
+   * Extracts values from patterns like:
+   * - CHECK (status IN ('active', 'inactive'))
+   * - CHECK ((status)::text = ANY (ARRAY['a'::text, 'b'::text]))
+   * - CHECK (status = 'active' OR status = 'inactive')
+   */
+  parseCheckConstraint(constraint2, columnName) {
+    if (constraint2.type !== "CHECK" || !constraint2.definition) {
+      return void 0;
+    }
+    if (constraint2.columns && !constraint2.columns.includes(columnName)) {
+      return void 0;
+    }
+    const def = constraint2.definition;
+    const escapedCol = this.escapeRegex(columnName);
+    const colPattern = `(?:\\(?\\(?${escapedCol}\\)?(?:::(?:text|varchar|character varying))?\\)?)`;
+    const inMatch = def.match(
+      new RegExp(`${colPattern}\\s+IN\\s*\\(([^)]+)\\)`, "i")
+    );
+    if (inMatch) {
+      return this.extractStringValues(inMatch[1]);
+    }
+    const anyMatch = def.match(
+      new RegExp(
+        `${colPattern}\\s*=\\s*ANY\\s*\\(\\s*(?:ARRAY)?\\s*\\[([^\\]]+)\\]`,
+        "i"
+      )
+    );
+    if (anyMatch) {
+      return this.extractStringValues(anyMatch[1]);
+    }
+    const orPattern = new RegExp(
+      `\\b${this.escapeRegex(columnName)}\\b\\s*=\\s*'([^']*)'`,
+      "gi"
+    );
+    const orMatches = [...def.matchAll(orPattern)];
+    if (orMatches.length >= 2) {
+      return orMatches.map((m) => m[1]);
+    }
+    return void 0;
+  }
+  /**
+   * Extract string values from a comma-separated list.
+   */
+  extractStringValues(input) {
+    const values = [];
+    const matches = input.matchAll(/'([^']*)'/g);
+    for (const match of matches) {
+      values.push(match[1]);
+    }
+    return values.length > 0 ? values : void 0;
+  }
+  /**
+   * Escape special regex characters in a string.
+   */
+  escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  /**
+   * Get the table from context by name.
+   */
+  getTable(ctx, name) {
+    return ctx.tables.find((t) => t.name === name);
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with values.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    const total = allContainers.length;
+    for (let i = 0; i < allContainers.length; i++) {
+      const container = allContainers[i];
+      ctx.onProgress({
+        type: "phase:progress",
+        phase: "column_values",
+        table: container.name,
+        message: `Collecting column values for ${container.name}...`,
+        current: i + 1,
+        total
+      });
+      const table2 = this.getTable(ctx, container.name);
+      for (const column2 of container.columns) {
+        try {
+          const result = await this.resolveColumnValues(
+            container.name,
+            column2,
+            table2?.constraints
+          );
+          if (result) {
+            column2.kind = result.kind;
+            column2.values = result.values;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting column values for",
+            container.name,
+            column2.name,
+            error
+          );
+        }
+      }
+    }
+  }
+  exceedsMaxValueLength(values) {
+    return values.some((v) => v.length > this.maxValueLength);
+  }
+  /**
+   * Resolve column values from all sources in priority order.
+   */
+  async resolveColumnValues(tableName, column2, constraints2) {
+    const enumValues = await this.collectEnumValues(tableName, column2);
+    if (enumValues?.length && !this.exceedsMaxValueLength(enumValues)) {
+      return { kind: "Enum", values: enumValues };
+    }
+    if (constraints2) {
+      for (const constraint2 of constraints2) {
+        const checkValues = this.parseCheckConstraint(constraint2, column2.name);
+        if (checkValues?.length && !this.exceedsMaxValueLength(checkValues)) {
+          return { kind: "Enum", values: checkValues };
+        }
+      }
+    }
+    const lowCardValues = await this.collectLowCardinality(tableName, column2);
+    if (lowCardValues?.length && !this.exceedsMaxValueLength(lowCardValues)) {
+      return { kind: "LowCardinality", values: lowCardValues };
+    }
+    return void 0;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
+var ConstraintGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("constraint", "constraints");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their constraints.
+   */
+  async execute(ctx) {
+    const total = ctx.tables.length;
+    for (let i = 0; i < ctx.tables.length; i++) {
+      const table2 = ctx.tables[i];
+      ctx.onProgress({
+        type: "phase:progress",
+        phase: "constraints",
+        table: table2.name,
+        message: `Loading constraints for ${table2.name}...`,
+        current: i + 1,
+        total
+      });
+      try {
+        table2.constraints = await this.getConstraints(table2.name);
+      } catch (error) {
+        console.warn("Error collecting constraints for", table2.name, error);
+      }
+    }
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/indexes.grounding.ts
+var IndexesGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("index", "indexes");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their indexes and marks indexed columns.
+   */
+  async execute(ctx) {
+    const total = ctx.tables.length;
+    for (let i = 0; i < ctx.tables.length; i++) {
+      const table2 = ctx.tables[i];
+      ctx.onProgress({
+        type: "phase:progress",
+        phase: "indexes",
+        table: table2.name,
+        message: `Loading indexes for ${table2.name}...`,
+        current: i + 1,
+        total
+      });
+      table2.indexes = await this.getIndexes(table2.name);
+      for (const index2 of table2.indexes ?? []) {
+        for (const colName of index2.columns) {
+          const column2 = table2.columns.find((c) => c.name === colName);
+          if (column2) {
+            column2.isIndexed = true;
+          }
+        }
+      }
+    }
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
+var InfoGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("dialectInfo", "info");
+  }
+  /**
+   * Execute the grounding process.
+   * Writes database info to ctx.info.
+   */
+  async execute(ctx) {
+    ctx.info = await this.collectInfo();
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/row-count.grounding.ts
+var RowCountGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("rowCount", "row_counts");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with row counts and size hints.
+   */
+  async execute(ctx) {
+    const total = ctx.tables.length;
+    for (let i = 0; i < ctx.tables.length; i++) {
+      const table2 = ctx.tables[i];
+      ctx.onProgress({
+        type: "phase:progress",
+        phase: "row_counts",
+        table: table2.name,
+        message: `Counting rows in ${table2.name}...`,
+        current: i + 1,
+        total
+      });
+      const count = await this.getRowCount(table2.name);
+      if (count != null) {
+        table2.rowCount = count;
+        table2.sizeHint = this.#classifyRowCount(count);
+      }
+    }
+  }
+  /**
+   * Classify row count into a size hint category.
+   */
+  #classifyRowCount(count) {
+    if (count < 100) return "tiny";
+    if (count < 1e3) return "small";
+    if (count < 1e4) return "medium";
+    if (count < 1e5) return "large";
+    return "huge";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/table.grounding.ts
+var TableGrounding = class extends AbstractGrounding {
+  #filter;
+  #columns;
+  #forward;
+  #backward;
+  constructor(config = {}) {
+    super("table", "tables");
+    this.#filter = config.filter;
+    this.#columns = config.columns;
+    this.#forward = config.forward;
+    this.#backward = config.backward;
+  }
+  async contributeEntities(ctx) {
+    await this.execute(ctx);
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered tables and relationships to the context.
+   */
+  async execute(ctx) {
+    const seedTables = await this.applyFilter();
+    const forward = this.#forward;
+    const backward = this.#backward;
+    if (!forward && !backward) {
+      const tables3 = await Promise.all(
+        seedTables.map(async (name, index2) => {
+          ctx.onProgress({
+            type: "phase:progress",
+            phase: "tables",
+            table: name,
+            message: `Loading table ${name}...`,
+            current: index2 + 1,
+            total: seedTables.length
+          });
+          return applyColumnFilter(await this.getTable(name), this.#columns);
+        })
+      );
+      ctx.tables.push(...tables3);
+      return;
+    }
+    const tables2 = {};
+    const allRelationships = [];
+    const seenRelationships = /* @__PURE__ */ new Set();
+    const forwardQueue = [];
+    const backwardQueue = [];
+    const forwardVisited = /* @__PURE__ */ new Set();
+    const backwardVisited = /* @__PURE__ */ new Set();
+    let loadedCount = 0;
+    for (const name of seedTables) {
+      if (forward) forwardQueue.push({ name, depth: 0 });
+      if (backward) backwardQueue.push({ name, depth: 0 });
+    }
+    const forwardLimit = forward === true ? Infinity : forward || 0;
+    while (forwardQueue.length > 0) {
+      const item = forwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (forwardVisited.has(name)) continue;
+      forwardVisited.add(name);
+      if (!tables2[name]) {
+        loadedCount++;
+        ctx.onProgress({
+          type: "phase:progress",
+          phase: "tables",
+          table: name,
+          message: `Loading table ${name}...`,
+          current: loadedCount
+        });
+        tables2[name] = applyColumnFilter(
+          await this.getTable(name),
+          this.#columns
+        );
+      }
+      if (depth < forwardLimit) {
+        const rels = await this.findOutgoingRelations(name);
+        for (const rel of rels) {
+          if (!this.isRelationshipVisible(rel)) continue;
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!forwardVisited.has(rel.referenced_table)) {
+            forwardQueue.push({ name: rel.referenced_table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const backwardLimit = backward === true ? Infinity : backward || 0;
+    while (backwardQueue.length > 0) {
+      const item = backwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (backwardVisited.has(name)) continue;
+      backwardVisited.add(name);
+      if (!tables2[name]) {
+        loadedCount++;
+        ctx.onProgress({
+          type: "phase:progress",
+          phase: "tables",
+          table: name,
+          message: `Loading table ${name}...`,
+          current: loadedCount
+        });
+        tables2[name] = applyColumnFilter(
+          await this.getTable(name),
+          this.#columns
+        );
+      }
+      if (depth < backwardLimit) {
+        const rels = await this.findIncomingRelations(name);
+        for (const rel of rels) {
+          if (!this.isRelationshipVisible(rel)) continue;
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!backwardVisited.has(rel.table)) {
+            backwardQueue.push({ name: rel.table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const tablesList = Object.values(tables2);
+    ctx.tables.push(...tablesList);
+    ctx.relationships.push(...allRelationships);
+  }
+  /**
+   * Apply the filter to get seed table names.
+   * If filter is an explicit array, skip querying all table names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllTableNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+  /**
+   * Add a relationship to the collection, deduplicating by key.
+   */
+  addRelationship(rel, all, seen) {
+    const key = `${rel.table}:${rel.from.join(",")}:${rel.referenced_table}:${rel.to.join(",")}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      all.push(rel);
+    }
+  }
+  isRelationshipVisible(rel) {
+    return this.areColumnsVisible(rel.from, this.#columns?.[rel.table]) && this.areColumnsVisible(rel.to, this.#columns?.[rel.referenced_table]);
+  }
+  areColumnsVisible(names, filter) {
+    if (!filter) return true;
+    return filterColumns(
+      names.map((name) => ({ name })),
+      filter
+    ).length === names.length;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/view.grounding.ts
+var ViewGrounding = class extends AbstractGrounding {
+  #filter;
+  #columns;
+  includeDefinition;
+  constructor(config = {}) {
+    super("view", "views");
+    this.#filter = config.filter;
+    this.#columns = config.columns;
+    this.includeDefinition = config.includeDefinition ?? true;
+  }
+  async contributeEntities(ctx) {
+    await this.execute(ctx);
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered views to the context.
+   */
+  async execute(ctx) {
+    const viewNames = await this.applyFilter();
+    const views2 = await Promise.all(
+      viewNames.map(async (name, index2) => {
+        ctx.onProgress({
+          type: "phase:progress",
+          phase: "views",
+          table: name,
+          message: `Loading view ${name}...`,
+          current: index2 + 1,
+          total: viewNames.length
+        });
+        return applyColumnFilter(await this.getView(name), this.#columns);
+      })
+    );
+    ctx.views.push(...views2);
+  }
+  /**
+   * Apply the filter to get view names.
+   * If filter is an explicit array, skip querying all view names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllViewNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/duckdb/duckdb-identifiers.ts
+import { quotedIdentifier } from "@duckdb/node-api";
+function formatDuckDBIdentifierPath(parts) {
+  return parts.map(quotedIdentifier).join(".");
+}
+function parseDuckDBRelationName(name) {
+  const parts = splitIdentifierPath(name);
+  if (parts.length === 1) return { table: parts[0] };
+  if (parts.length === 2) {
+    return { schema: parts[0], table: parts[1] };
+  }
+  if (parts.length === 3) {
+    return { catalog: parts[0], schema: parts[1], table: parts[2] };
+  }
+  throw new Error(`DuckDB relation must have at most three parts: ${name}`);
+}
+function splitIdentifierPath(input) {
+  const parts = [];
+  let part = "";
+  let quoted = false;
+  for (let index2 = 0; index2 < input.length; index2++) {
+    const character = input[index2];
+    if (character === '"') {
+      if (quoted && input[index2 + 1] === '"') {
+        part += '"';
+        index2++;
+      } else {
+        quoted = !quoted;
+      }
+    } else if (character === "." && !quoted) {
+      if (!part) throw new Error(`Invalid DuckDB relation: ${input}`);
+      parts.push(part);
+      part = "";
+    } else {
+      part += character;
+    }
+  }
+  if (quoted || !part) throw new Error(`Invalid DuckDB relation: ${input}`);
+  parts.push(part);
+  return parts;
+}
+
+// packages/text2sql/src/lib/adapters/duckdb/duckdb.groundings.ts
+var CONSTRAINT_TYPES = /* @__PURE__ */ new Map([
+  ["CHECK", "CHECK"],
+  ["UNIQUE", "UNIQUE"],
+  ["NOT NULL", "NOT_NULL"],
+  ["PRIMARY KEY", "PRIMARY_KEY"],
+  ["FOREIGN KEY", "FOREIGN_KEY"]
+]);
+var DuckDBTableGrounding = class extends TableGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async applyFilter() {
+    const names = await super.applyFilter();
+    const { catalogs, schemas } = await this.#adapter.scopedNamespaces();
+    const result = [];
+    for (const name of names) {
+      const relation = await this.#adapter.resolveRelationName(name);
+      if (catalogs.includes(relation.catalog) && schemas.includes(relation.schema)) {
+        result.push(
+          this.#adapter.formatRelationName(
+            relation.catalog,
+            relation.schema,
+            relation.table
+          )
+        );
+      }
+    }
+    return result;
+  }
+  async getAllTableNames() {
+    const { catalogs, schemas } = await this.#adapter.scopedNamespaces();
+    const rows = await this.#adapter.runQuery(`
+      SELECT database_name, schema_name, table_name
+      FROM duckdb_tables()
+      WHERE NOT internal
+        AND NOT temporary
+        AND database_name IN (${sqlLiterals(this.#adapter, catalogs)})
+        AND schema_name IN (${sqlLiterals(this.#adapter, schemas)})
+      ORDER BY database_name, schema_name, table_name
+    `);
+    return rows.map((row) => {
+      if (typeof row.database_name !== "string" || typeof row.schema_name !== "string" || typeof row.table_name !== "string") {
+        throw new Error("DuckDB table catalog returned an unknown row shape.");
+      }
+      return this.#adapter.formatRelationName(
+        row.database_name,
+        row.schema_name,
+        row.table_name
+      );
+    });
+  }
+  async getTable(tableName) {
+    const { catalog, schema, table: table2 } = await this.#adapter.resolveRelationName(tableName);
+    const rows = await this.#adapter.runQuery(`
+      SELECT column_name, data_type
+      FROM duckdb_columns()
+      WHERE database_name = '${this.#adapter.escapeString(catalog)}'
+        AND schema_name = '${this.#adapter.escapeString(schema)}'
+        AND table_name = '${this.#adapter.escapeString(table2)}'
+      ORDER BY column_index
+    `);
+    return {
+      name: this.#adapter.formatRelationName(catalog, schema, table2),
+      schema: formatDuckDBIdentifierPath([catalog, schema]),
+      rawName: table2,
+      columns: rows.map((row) => {
+        if (typeof row.column_name !== "string" || typeof row.data_type !== "string") {
+          throw new Error(
+            "DuckDB column catalog returned an unknown row shape."
+          );
+        }
+        return { name: row.column_name, type: row.data_type };
+      })
+    };
+  }
+  async findOutgoingRelations(tableName) {
+    const relation = await this.#adapter.resolveRelationName(tableName);
+    const rows = await foreignKeys(this.#adapter, relation, "outgoing");
+    return rows.map((row) => relationshipFromRow(this.#adapter, relation, row));
+  }
+  async findIncomingRelations(tableName) {
+    const relation = await this.#adapter.resolveRelationName(tableName);
+    const rows = await foreignKeys(this.#adapter, relation, "incoming");
+    return rows.map((row) => {
+      const source = {
+        catalog: relation.catalog,
+        schema: relation.schema,
+        table: requiredString(row.table_name, "table_name")
+      };
+      return relationshipFromRow(this.#adapter, source, row);
+    });
+  }
+};
+var DuckDBInfoGrounding = class extends InfoGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectInfo() {
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        version() AS version,
+        current_database() AS catalog,
+        current_schema() AS schema
+    `);
+    const row = rows[0];
+    return {
+      dialect: "duckdb",
+      version: typeof row?.version === "string" ? row.version : void 0,
+      database: typeof row?.catalog === "string" ? row.catalog : void 0,
+      details: {
+        currentSchema: typeof row?.schema === "string" ? row.schema : "unknown",
+        identifierQualification: "catalog.schema.table",
+        parameterPlaceholders: ["$1", "$name"]
+      }
+    };
+  }
+};
+var DuckDBViewGrounding = class extends ViewGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async applyFilter() {
+    const names = await super.applyFilter();
+    const { catalogs, schemas } = await this.#adapter.scopedNamespaces();
+    const result = [];
+    for (const name of names) {
+      const relation = await this.#adapter.resolveRelationName(name);
+      if (catalogs.includes(relation.catalog) && schemas.includes(relation.schema)) {
+        result.push(
+          this.#adapter.formatRelationName(
+            relation.catalog,
+            relation.schema,
+            relation.table
+          )
+        );
+      }
+    }
+    return result;
+  }
+  async getAllViewNames() {
+    const { catalogs, schemas } = await this.#adapter.scopedNamespaces();
+    const rows = await this.#adapter.runQuery(`
+      SELECT database_name, schema_name, view_name
+      FROM duckdb_views()
+      WHERE NOT internal
+        AND NOT temporary
+        AND database_name IN (${sqlLiterals(this.#adapter, catalogs)})
+        AND schema_name IN (${sqlLiterals(this.#adapter, schemas)})
+      ORDER BY database_name, schema_name, view_name
+    `);
+    return rows.map(
+      (row) => this.#adapter.formatRelationName(
+        requiredString(row.database_name, "database_name"),
+        requiredString(row.schema_name, "schema_name"),
+        requiredString(row.view_name, "view_name")
+      )
+    );
+  }
+  async getView(viewName) {
+    const relation = await this.#adapter.resolveRelationName(viewName);
+    const where = relationPredicate(this.#adapter, relation);
+    const [columns, definitions] = await Promise.all([
+      this.#adapter.runQuery(`
+        SELECT column_name, data_type
+        FROM duckdb_columns()
+        WHERE ${where}
+        ORDER BY column_index
+      `),
+      this.includeDefinition ? this.#adapter.runQuery(`
+            SELECT sql
+            FROM duckdb_views()
+            WHERE database_name = '${this.#adapter.escapeString(relation.catalog)}'
+              AND schema_name = '${this.#adapter.escapeString(relation.schema)}'
+              AND view_name = '${this.#adapter.escapeString(relation.table)}'
+          `) : Promise.resolve([])
+    ]);
+    return {
+      name: this.#adapter.formatRelationName(
+        relation.catalog,
+        relation.schema,
+        relation.table
+      ),
+      schema: formatDuckDBIdentifierPath([relation.catalog, relation.schema]),
+      rawName: relation.table,
+      definition: typeof definitions[0]?.sql === "string" ? definitions[0].sql : void 0,
+      columns: columns.map(columnFromRow)
+    };
+  }
+};
+var DuckDBConstraintGrounding = class extends ConstraintGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getConstraints(tableName) {
+    const relation = await this.#adapter.resolveRelationName(tableName);
+    const [rows, columns] = await Promise.all([
+      this.#adapter.runQuery(`
+        SELECT
+          constraint_name,
+          constraint_type,
+          expression,
+          constraint_column_names,
+          referenced_table,
+          referenced_column_names
+        FROM duckdb_constraints()
+        WHERE ${relationPredicate(this.#adapter, relation)}
+        ORDER BY constraint_index
+      `),
+      this.#adapter.runQuery(`
+        SELECT column_name, column_default
+        FROM duckdb_columns()
+        WHERE ${relationPredicate(this.#adapter, relation)}
+          AND column_default IS NOT NULL
+        ORDER BY column_index
+      `)
+    ]);
+    const constraints2 = rows.map(
+      (row) => constraintFromRow(this.#adapter, relation, row)
+    );
+    for (const column2 of columns) {
+      if (typeof column2.column_name === "string" && typeof column2.column_default === "string") {
+        constraints2.push({
+          name: `${relation.table}_${column2.column_name}_default`,
+          type: "DEFAULT",
+          columns: [column2.column_name],
+          defaultValue: column2.column_default
+        });
+      }
+    }
+    return constraints2;
+  }
+};
+var DuckDBIndexesGrounding = class extends IndexesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getIndexes(tableName) {
+    const relation = await this.#adapter.resolveRelationName(tableName);
+    const [rows, columnRows] = await Promise.all([
+      this.#adapter.runQuery(`
+        SELECT
+          index_name,
+          TRY_CAST(expressions AS VARCHAR[]) AS expressions,
+          is_unique,
+          is_primary
+        FROM duckdb_indexes()
+        WHERE ${relationPredicate(this.#adapter, relation)}
+        ORDER BY index_name
+      `),
+      this.#adapter.runQuery(`
+        SELECT column_name
+        FROM duckdb_columns()
+        WHERE ${relationPredicate(this.#adapter, relation)}
+        ORDER BY column_index
+      `)
+    ]);
+    const tableColumns = columnRows.map(
+      (row) => requiredString(row.column_name, "column_name")
+    );
+    return rows.flatMap((row) => {
+      if (typeof row.index_name !== "string") {
+        throw new Error("DuckDB index catalog returned an unknown row shape.");
+      }
+      if (!Array.isArray(row.expressions) || row.expressions.some((expression) => typeof expression !== "string")) {
+        return [];
+      }
+      const columns = row.expressions.map(
+        (expression) => tableColumns.find(
+          (column2) => expression === column2 || expression === this.#adapter.quoteIdentifier(column2)
+        )
+      );
+      return columns.length > 0 && columns.every((column2) => column2 !== void 0) ? [
+        {
+          name: row.index_name,
+          columns,
+          unique: row.is_unique === true,
+          type: row.is_primary === true ? "PRIMARY" : void 0
+        }
+      ] : [];
+    });
+  }
+};
+var DuckDBRowCountGrounding = class extends RowCountGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getRowCount(tableName) {
+    const relation = await this.#adapter.resolveRelationName(tableName);
+    const rows = await this.#adapter.runQuery(`
+      SELECT estimated_size
+      FROM duckdb_tables()
+      WHERE ${relationPredicate(this.#adapter, relation)}
+    `);
+    return this.#adapter.toNumber(rows[0]?.estimated_size);
+  }
+};
+var DuckDBColumnStatsGrounding = class extends ColumnStatsGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectStats(tableName, column2) {
+    if (!/int|real|numeric|double|float|decimal|date|time|bool/i.test(column2.type)) {
+      return void 0;
+    }
+    const relation = this.#adapter.quoteRelationName(tableName);
+    const identifier = this.#adapter.quoteIdentifier(column2.name);
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        CAST(MIN(${identifier}) AS VARCHAR) AS min_value,
+        CAST(MAX(${identifier}) AS VARCHAR) AS max_value,
+        CASE
+          WHEN COUNT(*) = 0 THEN NULL
+          ELSE COUNT(*) FILTER (WHERE ${identifier} IS NULL)::DOUBLE / COUNT(*)
+        END AS null_fraction,
+        COUNT(DISTINCT ${identifier}) AS n_distinct
+      FROM ${relation}
+    `);
+    const row = rows[0];
+    if (!row) return void 0;
+    return {
+      min: typeof row.min_value === "string" ? row.min_value : void 0,
+      max: typeof row.max_value === "string" ? row.max_value : void 0,
+      nullFraction: this.#adapter.toNumber(row.null_fraction),
+      nDistinct: this.#adapter.toNumber(row.n_distinct)
+    };
+  }
+};
+var DuckDBColumnValuesGrounding = class extends ColumnValuesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectEnumValues(_tableName, column2) {
+    return parseEnumLabels(column2.type);
+  }
+  async collectLowCardinality(tableName, column2) {
+    if (/\b(?:BLOB|STRUCT|MAP|LIST|UNION|ARRAY)\b/i.test(column2.type)) {
+      return void 0;
+    }
+    const relation = this.#adapter.quoteRelationName(tableName);
+    const identifier = this.#adapter.quoteIdentifier(column2.name);
+    const rows = await this.#adapter.runQuery(`
+      SELECT DISTINCT CAST(${identifier} AS VARCHAR) AS value
+      FROM ${relation}
+      WHERE ${identifier} IS NOT NULL
+      ORDER BY value
+      LIMIT ${this.lowCardinalityLimit + 1}
+    `);
+    if (rows.length === 0 || rows.length > this.lowCardinalityLimit) {
+      return void 0;
+    }
+    if (rows.some((row) => typeof row.value !== "string")) return void 0;
+    return rows.map((row) => row.value);
+  }
+};
+function sqlLiterals(adapter, values) {
+  return values.map((value) => `'${adapter.escapeString(value)}'`).join(", ");
+}
+function relationPredicate(adapter, relation) {
+  return `database_name = '${adapter.escapeString(relation.catalog)}'
+    AND schema_name = '${adapter.escapeString(relation.schema)}'
+    AND table_name = '${adapter.escapeString(relation.table)}'`;
+}
+function columnFromRow(row) {
+  return {
+    name: requiredString(row.column_name, "column_name"),
+    type: requiredString(row.data_type, "data_type")
+  };
+}
+async function foreignKeys(adapter, relation, direction) {
+  const predicate = direction === "outgoing" ? `table_name = '${adapter.escapeString(relation.table)}'` : `referenced_table = '${adapter.escapeString(relation.table)}'`;
+  return adapter.runQuery(`
+    SELECT
+      table_name,
+      constraint_name,
+      constraint_type,
+      expression,
+      constraint_column_names,
+      referenced_table,
+      referenced_column_names
+    FROM duckdb_constraints()
+    WHERE database_name = '${adapter.escapeString(relation.catalog)}'
+      AND schema_name = '${adapter.escapeString(relation.schema)}'
+      AND constraint_type = 'FOREIGN KEY'
+      AND ${predicate}
+    ORDER BY table_name, constraint_index
+  `);
+}
+function relationshipFromRow(adapter, source, row) {
+  return {
+    table: adapter.formatRelationName(
+      source.catalog,
+      source.schema,
+      source.table
+    ),
+    from: stringArray(row.constraint_column_names, "constraint_column_names"),
+    referenced_table: adapter.formatRelationName(
+      source.catalog,
+      source.schema,
+      requiredString(row.referenced_table, "referenced_table")
+    ),
+    to: stringArray(row.referenced_column_names, "referenced_column_names")
+  };
+}
+function constraintFromRow(adapter, relation, row) {
+  const type = requiredString(row.constraint_type, "constraint_type");
+  const mapped = CONSTRAINT_TYPES.get(type);
+  if (!mapped) throw new Error(`Unknown DuckDB constraint type: ${type}`);
+  const referenced = mapped === "FOREIGN_KEY" ? adapter.formatRelationName(
+    relation.catalog,
+    relation.schema,
+    requiredString(row.referenced_table, "referenced_table")
+  ) : void 0;
+  return {
+    name: requiredString(row.constraint_name, "constraint_name"),
+    type: mapped,
+    columns: stringArray(
+      row.constraint_column_names,
+      "constraint_column_names"
+    ),
+    definition: mapped === "CHECK" && typeof row.expression === "string" ? row.expression : void 0,
+    referencedTable: referenced,
+    referencedColumns: mapped === "FOREIGN_KEY" ? stringArray(row.referenced_column_names, "referenced_column_names") : void 0
+  };
+}
+function parseEnumLabels(type) {
+  const body = /^ENUM\((.*)\)$/i.exec(type)?.[1];
+  if (body === void 0) return void 0;
+  const labels = [...body.matchAll(/'((?:''|[^'])*)'/g)].map(
+    (match) => match[1].replaceAll("''", "'")
+  );
+  return labels.length > 0 ? labels : void 0;
+}
+function requiredString(value, field) {
+  if (typeof value !== "string") {
+    throw new Error(`DuckDB catalog field ${field} must be a string.`);
+  }
+  return value;
+}
+function stringArray(value, field) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`DuckDB catalog field ${field} must be a string array.`);
+  }
+  return value;
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+import { format as formatSql } from "sql-formatter";
+
+// packages/text2sql/src/lib/agents/exceptions.ts
+var sqlValidationMarker = /* @__PURE__ */ Symbol("SQLValidationError");
+var unanswerableSqlMarker = /* @__PURE__ */ Symbol("UnanswerableSQLError");
+var sqlScopeMarker = /* @__PURE__ */ Symbol("SQLScopeError");
+var sqlReadOnlyMarker = /* @__PURE__ */ Symbol("SQLReadOnlyError");
+var SQLValidationError = class _SQLValidationError extends Error {
+  [sqlValidationMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLValidationError";
+    this[sqlValidationMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLValidationError && error[sqlValidationMarker] === true;
+  }
+};
+var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
+  [unanswerableSqlMarker];
+  constructor(message) {
+    super(message);
+    this.name = "UnanswerableSQLError";
+    this[unanswerableSqlMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _UnanswerableSQLError && error[unanswerableSqlMarker] === true;
+  }
+};
+var SQLScopeError = class _SQLScopeError extends Error {
+  [sqlScopeMarker];
+  payload;
+  errorType;
+  constructor(payload) {
+    super(JSON.stringify(payload));
+    this.name = "SQLScopeError";
+    this.payload = payload;
+    this.errorType = payload.error_type;
+    this[sqlScopeMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLScopeError && error[sqlScopeMarker] === true;
+  }
+};
+var SQLReadOnlyError = class _SQLReadOnlyError extends Error {
+  [sqlReadOnlyMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLReadOnlyError";
+    this[sqlReadOnlyMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLReadOnlyError && error[sqlReadOnlyMarker] === true;
+  }
+};
+
+// packages/text2sql/src/lib/fragments/schema.ts
+function dialectInfo(input) {
+  return {
+    name: "dialectInfo",
+    data: {
+      dialect: input.dialect,
+      ...input.version && { version: input.version },
+      ...input.database && { database: input.database },
+      ...input.details && { details: input.details }
+    }
+  };
+}
+function table(input) {
+  return {
+    name: "table",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      ...input.rowCount != null && { rowCount: input.rowCount },
+      ...input.sizeHint && { sizeHint: input.sizeHint },
+      columns: input.columns,
+      ...input.indexes?.length && { indexes: input.indexes },
+      ...input.constraints?.length && { constraints: input.constraints }
+    }
+  };
+}
+function column(input) {
+  return {
+    name: "column",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.pk && { pk: true },
+      ...input.fk && { fk: input.fk },
+      ...input.unique && { unique: true },
+      ...input.notNull && { notNull: true },
+      ...input.default && { default: input.default },
+      ...input.indexed && { indexed: true },
+      ...input.values?.length && { values: input.values },
+      ...input.stats && { stats: input.stats }
+    }
+  };
+}
+function index(input) {
+  return {
+    name: "index",
+    data: {
+      name: input.name,
+      columns: input.columns,
+      ...input.unique && { unique: true },
+      ...input.type && { type: input.type }
+    }
+  };
+}
+function constraint(input) {
+  return {
+    name: "constraint",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.columns?.length && { columns: input.columns },
+      ...input.definition && { definition: input.definition },
+      ...input.defaultValue && { defaultValue: input.defaultValue },
+      ...input.referencedTable && { referencedTable: input.referencedTable },
+      ...input.referencedColumns?.length && {
+        referencedColumns: input.referencedColumns
+      }
+    }
+  };
+}
+function view(input) {
+  return {
+    name: "view",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      columns: input.columns,
+      ...input.definition && { definition: input.definition }
+    }
+  };
+}
+function relationship(input) {
+  return {
+    name: "relationship",
+    data: {
+      from: input.from,
+      to: input.to,
+      ...input.cardinality && { cardinality: input.cardinality }
+    }
+  };
+}
+
+// packages/text2sql/src/lib/adapters/groundings/context.ts
+var noopProgress = () => {
+};
+function timestampProgress(onProgress) {
+  if (!onProgress) return noopProgress;
+  return (progress) => {
+    onProgress({
+      ...progress,
+      timestampMs: progress.timestampMs ?? Date.now()
+    });
+  };
+}
+function createGroundingContext(options = {}) {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0,
+    fragments: [],
+    cache: /* @__PURE__ */ new Map(),
+    onProgress: timestampProgress(options.onProgress)
+  };
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+var Adapter = class {
+  #policyAnalyzer;
+  /**
+   * Injects the strategy that guards validate() and execute().
+   */
+  constructor(policyAnalyzer) {
+    this.#policyAnalyzer = policyAnalyzer;
+  }
+  /**
+   * Introspect the database schema and return context fragments.
+   *
+   * Executes all configured groundings to populate the context, then
+   * generates fragments from the complete context data.
+   *
+   * @param ctx - Optional grounding context for sharing state between groundings
+   * @returns Array of context fragments representing the database schema
+   */
+  async introspect(ctx = createGroundingContext()) {
+    for (const fn of this.grounding) {
+      const grounding = fn(this);
+      if (grounding.phase) {
+        ctx.onProgress({
+          type: "phase:start",
+          phase: grounding.phase,
+          message: `Starting ${grounding.name} introspection...`
+        });
+      }
+      try {
+        await grounding.execute(ctx);
+      } finally {
+        if (grounding.phase) {
+          ctx.onProgress({
+            type: "phase:end",
+            phase: grounding.phase,
+            message: `Finished ${grounding.name} introspection.`
+          });
+        }
+      }
+    }
+    return this.#toSchemaFragments(ctx);
+  }
+  /**
+   * Resolve the allowed entity names (tables + views) from grounding config.
+   * Asks each grounding to contribute its entities; annotators contribute
+   * nothing, so their metadata scans are skipped.
+   * Results are NOT cached — call once and store the result.
+   */
+  async resolveAllowedEntities() {
+    const ctx = createGroundingContext();
+    for (const fn of this.grounding) {
+      await fn(this).contributeEntities(ctx);
+    }
+    return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
+  }
+  /**
+   * Convert complete grounding context to schema fragments.
+   * Called after all groundings have populated ctx with data.
+   */
+  #toSchemaFragments(ctx) {
+    const fragments = [];
+    if (ctx.info) {
+      fragments.push(
+        dialectInfo({
+          dialect: ctx.info.dialect,
+          version: ctx.info.version,
+          database: ctx.info.database,
+          details: ctx.info.details
+        })
+      );
+    }
+    for (const t of ctx.tables) {
+      fragments.push(this.#tableToFragment(t));
+    }
+    for (const v of ctx.views) {
+      fragments.push(this.#viewToFragment(v));
+    }
+    const tableMap = new Map(ctx.tables.map((t) => [t.name, t]));
+    const tableColumnSets = new Map(
+      ctx.tables.map((t) => [t.name, new Set(t.columns.map((c) => c.name))])
+    );
+    for (const rel of ctx.relationships) {
+      const sourceColumns = tableColumnSets.get(rel.table);
+      const targetColumns = tableColumnSets.get(rel.referenced_table);
+      if (sourceColumns && rel.from.some((column2) => !sourceColumns.has(column2))) {
+        continue;
+      }
+      if (targetColumns && rel.to.some((column2) => !targetColumns.has(column2))) {
+        continue;
+      }
+      const sourceTable = tableMap.get(rel.table);
+      const targetTable = tableMap.get(rel.referenced_table);
+      fragments.push(
+        this.#relationshipToFragment(rel, sourceTable, targetTable)
+      );
+    }
+    fragments.push(...ctx.fragments ?? []);
+    return fragments;
+  }
+  /**
+   * Convert a Table to a table fragment with nested column, index, and constraint fragments.
+   */
+  #tableToFragment(t) {
+    const pkConstraint = t.constraints?.find((c) => c.type === "PRIMARY_KEY");
+    const pkColumns = new Set(pkConstraint?.columns ?? []);
+    const notNullColumns = new Set(
+      t.constraints?.filter((c) => c.type === "NOT_NULL").flatMap((c) => c.columns ?? []) ?? []
+    );
+    const defaultByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "DEFAULT") ?? []) {
+      for (const col of c.columns ?? []) {
+        if (c.defaultValue != null) {
+          defaultByColumn.set(col, c.defaultValue);
+        }
+      }
+    }
+    const uniqueColumns = new Set(
+      t.constraints?.filter((c) => c.type === "UNIQUE" && c.columns?.length === 1).flatMap((c) => c.columns ?? []) ?? []
+    );
+    const fkByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "FOREIGN_KEY") ?? []) {
+      const cols = c.columns ?? [];
+      const refCols = c.referencedColumns ?? [];
+      for (let i = 0; i < cols.length; i++) {
+        const refCol = refCols[i] ?? refCols[0] ?? cols[i];
+        fkByColumn.set(cols[i], `${c.referencedTable}.${refCol}`);
+      }
+    }
+    const columnFragments = t.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        pk: pkColumns.has(col.name) || void 0,
+        fk: fkByColumn.get(col.name),
+        unique: uniqueColumns.has(col.name) || void 0,
+        notNull: notNullColumns.has(col.name) || void 0,
+        default: defaultByColumn.get(col.name),
+        indexed: col.isIndexed || void 0,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    const presentColumns = new Set(t.columns.map((c) => c.name));
+    const indexFragments = (t.indexes ?? []).filter(
+      (idx) => idx.columns.every((column2) => presentColumns.has(column2))
+    ).map(
+      (idx) => index({
+        name: idx.name,
+        columns: idx.columns,
+        unique: idx.unique,
+        type: idx.type
+      })
+    );
+    const constraintFragments = (t.constraints ?? []).filter(
+      (c) => c.type === "CHECK" || c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
+    ).filter(
+      (c) => !c.columns?.length || c.columns.every((column2) => presentColumns.has(column2))
+    ).map(
+      (c) => constraint({
+        name: c.name,
+        type: c.type,
+        columns: c.columns,
+        definition: c.definition
+      })
+    );
+    return table({
+      name: t.name,
+      schema: t.schema,
+      rowCount: t.rowCount,
+      sizeHint: t.sizeHint,
+      columns: columnFragments,
+      indexes: indexFragments.length > 0 ? indexFragments : void 0,
+      constraints: constraintFragments.length > 0 ? constraintFragments : void 0
+    });
+  }
+  /**
+   * Convert a View to a view fragment with nested column fragments.
+   */
+  #viewToFragment(v) {
+    const columnFragments = v.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    return view({
+      name: v.name,
+      schema: v.schema,
+      columns: columnFragments,
+      definition: v.definition
+    });
+  }
+  /**
+   * Convert a Relationship to a relationship fragment.
+   * Infers cardinality from row counts if available.
+   */
+  #relationshipToFragment(rel, sourceTable, targetTable) {
+    const sourceCount = sourceTable?.rowCount;
+    const targetCount = targetTable?.rowCount;
+    let cardinality;
+    if (sourceCount != null && targetCount != null && targetCount > 0) {
+      const ratio = sourceCount / targetCount;
+      if (ratio > 5) {
+        cardinality = "many-to-one";
+      } else if (ratio < 1.2 && ratio > 0.8) {
+        cardinality = "one-to-one";
+      } else if (ratio < 0.2) {
+        cardinality = "one-to-many";
+      }
+    }
+    return relationship({
+      from: { table: rel.table, columns: rel.from },
+      to: { table: rel.referenced_table, columns: rel.to },
+      cardinality
+    });
+  }
+  format(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    try {
+      return formatSql(decoded, { language: this.formatterLanguage });
+    } catch {
+      return decoded;
+    }
+  }
+  #decodeShellEscapes(sql) {
+    return sql.replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\([().*$])/g, "$1").replace(/\\(?=$)/gm, "");
+  }
+  #cachedAllowedEntities = null;
+  async #resolveScope() {
+    if (this.#cachedAllowedEntities) return this.#cachedAllowedEntities;
+    this.#cachedAllowedEntities = await this.resolveAllowedEntities();
+    return this.#cachedAllowedEntities;
+  }
+  async #analyzePolicy(sql) {
+    return this.#policyAnalyzer.analyze(sql, {
+      resolveAllowedEntities: () => this.#resolveScope()
+    });
+  }
+  async validate(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") return violation.message;
+    if (violation?.kind === "scope") return JSON.stringify(violation.payload);
+    return this.validateImpl(decoded);
+  }
+  async execute(sql) {
+    return this.executeImpl(await this.enforceExecutionPolicy(sql));
+  }
+  async enforceExecutionPolicy(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") {
+      throw new SQLReadOnlyError(violation.message);
+    }
+    if (violation?.kind === "scope") {
+      throw new SQLScopeError(violation.payload);
+    }
+    return decoded;
+  }
+  /**
+   * Convert unknown database value to number.
+   * Handles number, bigint, and string types.
+   */
+  toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Parse a potentially qualified table name into schema and table parts.
+   */
+  parseTableName(name) {
+    if (name.includes(".")) {
+      const [schema, ...rest] = name.split(".");
+      return { schema, table: rest.join(".") };
+    }
+    return { schema: this.defaultSchema ?? "", table: name };
+  }
+  /**
+   * Escape a string value for use in SQL string literals (single quotes).
+   * Used in WHERE clauses like: WHERE name = '${escapeString(value)}'
+   */
+  escapeString(value) {
+    return value.replace(/'/g, "''");
+  }
+  /**
+   * Build a SQL filter clause to include/exclude schemas.
+   * @param columnName - The schema column name (e.g., 'TABLE_SCHEMA')
+   * @param allowedSchemas - If provided, filter to these schemas only
+   */
+  buildSchemaFilter(columnName, allowedSchemas) {
+    if (allowedSchemas && allowedSchemas.length > 0) {
+      const values = allowedSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    if (this.systemSchemas.length > 0) {
+      const values = this.systemSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} NOT IN (${values})`;
+    }
+    return "";
+  }
+};
+
+// packages/text2sql/src/lib/sql-scope-error.ts
+function buildScopeParseErrorPayload(sql, parserDialect, error) {
+  const parserError = error instanceof Error ? error.message : String(error ?? "Unknown error");
+  return {
+    error: `SQL scope analysis failed before validation/execution: ${parserError}`,
+    error_type: "SQL_SCOPE_PARSE_ERROR",
+    suggestion: "Rewrite the query into simpler SQL that can be analyzed safely, or extend parser coverage for this dialect feature.",
+    sql_attempted: sql,
+    parser_dialect: parserDialect,
+    parser_error: parserError
+  };
+}
+
+// packages/text2sql/src/lib/adapters/duckdb/duckdb.sql-policy.ts
+var READ_ONLY_MESSAGE = "only SELECT queries allowed";
+var SAFE_TABLE_FUNCTIONS = /* @__PURE__ */ new Set(["generate_series", "range", "unnest"]);
+var DuckDBSqlPolicyAnalyzer = class {
+  #query;
+  #namespace;
+  constructor(query) {
+    this.#query = query;
+  }
+  async analyze(sql, context) {
+    try {
+      const namespace = await (this.#namespace ??= this.#loadNamespace());
+      const ast = await this.#serialize(sql);
+      const analysis = analyzeAst(ast, namespace);
+      if (analysis.tableFunctions.some(
+        (name) => !SAFE_TABLE_FUNCTIONS.has(caseFold(name))
+      ) || await this.#hasUnsafeFunction(analysis.functions)) {
+        return { kind: "read-only", message: READ_ONLY_MESSAGE };
+      }
+      const allowedEntities = await context.resolveAllowedEntities();
+      const allowed = new Set(
+        allowedEntities.map(
+          (name) => caseFold(qualifyAllowedRelation(name, namespace))
+        )
+      );
+      const rejected = analysis.relations.filter(
+        (relation) => !allowed.has(caseFold(relation))
+      );
+      return rejected.length > 0 ? {
+        kind: "scope",
+        payload: buildOutOfScopePayload(sql, rejected, [
+          ...allowedEntities
+        ])
+      } : null;
+    } catch (error) {
+      if (isReadOnlySerializationError(error)) {
+        return { kind: "read-only", message: READ_ONLY_MESSAGE };
+      }
+      return {
+        kind: "scope",
+        payload: buildScopeParseErrorPayload(sql, "duckdb", error)
+      };
+    }
+  }
+  async #loadNamespace() {
+    const rows = readRows(
+      await this.#query(`
+        SELECT current_database() AS catalog, current_schema() AS schema
+      `)
+    );
+    const row = rows[0];
+    if (rows.length !== 1 || typeof row?.catalog !== "string" || typeof row.schema !== "string") {
+      throw new Error(
+        "DuckDB current namespace returned an unknown row shape."
+      );
+    }
+    return { catalog: row.catalog, schema: row.schema };
+  }
+  async #serialize(sql) {
+    const literal = sql.replaceAll("'", "''");
+    const rows = readRows(
+      await this.#query(`
+        SELECT json_serialize_sql(
+          '${literal}',
+          skip_empty := true,
+          skip_null := true
+        ) AS ast
+      `)
+    );
+    if (rows.length !== 1 || typeof rows[0]?.ast !== "string") {
+      throw new Error(
+        "DuckDB json_serialize_sql returned an unknown row shape."
+      );
+    }
+    const result = JSON.parse(rows[0].ast);
+    if (!isRecord(result)) {
+      throw new Error("DuckDB json_serialize_sql returned invalid JSON.");
+    }
+    if (result.error === true) {
+      const message = typeof result.error_message === "string" ? result.error_message : "DuckDB could not serialize the SQL statement.";
+      if (result.error_type === "not implemented" && message === "Only SELECT statements can be serialized to json!") {
+        throw new DuckDBSerializationError(message);
+      }
+      throw new Error(
+        `DuckDB rejected the SQL during AST analysis: ${message}`
+      );
+    }
+    if (result.error !== false || !Array.isArray(result.statements) || result.statements.length !== 1) {
+      throw new Error("DuckDB policy requires exactly one SELECT statement.");
+    }
+    return result.statements[0];
+  }
+  async #hasUnsafeFunction(functionNames) {
+    const names = [...new Set(functionNames.map(caseFold))];
+    if (names.length === 0) return false;
+    const literals = names.map((name) => `'${name.replaceAll("'", "''")}'`).join(", ");
+    const rows = readRows(
+      await this.#query(`
+        SELECT function_name, has_side_effects, internal
+        FROM duckdb_functions()
+        WHERE lower(function_name) IN (${literals})
+      `)
+    );
+    return rows.some(
+      (row) => row.has_side_effects === true || row.internal === false
+    );
+  }
+};
+function analyzeAst(ast, namespace) {
+  const cteNames = /* @__PURE__ */ new Set();
+  const relations = /* @__PURE__ */ new Set();
+  const functions = /* @__PURE__ */ new Set();
+  const tableFunctions = /* @__PURE__ */ new Set();
+  visit(ast, (node) => {
+    if (Array.isArray(node.map)) {
+      for (const entry of node.map) {
+        if (isRecord(entry) && typeof entry.key === "string") {
+          cteNames.add(caseFold(entry.key));
+        }
+      }
+    }
+  });
+  visit(ast, (node) => {
+    if (node.type === "BASE_TABLE" && typeof node.table_name === "string") {
+      const unqualifiedCte = node.catalog_name === void 0 && node.schema_name === void 0 && cteNames.has(caseFold(node.table_name));
+      if (!unqualifiedCte) {
+        relations.add(
+          formatDuckDBIdentifierPath([
+            typeof node.catalog_name === "string" ? node.catalog_name : namespace.catalog,
+            typeof node.schema_name === "string" ? node.schema_name : namespace.schema,
+            node.table_name
+          ])
+        );
+      }
+    }
+    if (node.class === "FUNCTION" && typeof node.function_name === "string") {
+      functions.add(node.function_name);
+    }
+    if (node.type === "TABLE_FUNCTION") {
+      const fn = node.function;
+      if (!isRecord(fn) || typeof fn.function_name !== "string") {
+        throw new Error("DuckDB table function has an unknown AST shape.");
+      }
+      tableFunctions.add(fn.function_name);
+    }
+  });
+  return {
+    relations: [...relations],
+    functions: [...functions],
+    tableFunctions: [...tableFunctions]
+  };
+}
+function visit(value, callback) {
+  if (Array.isArray(value)) {
+    for (const item of value) visit(item, callback);
+    return;
+  }
+  if (!isRecord(value)) return;
+  callback(value);
+  for (const child of Object.values(value)) visit(child, callback);
+}
+function qualifyAllowedRelation(name, namespace) {
+  const relation = parseDuckDBRelationName(name);
+  return formatDuckDBIdentifierPath([
+    relation.catalog ?? namespace.catalog,
+    relation.schema ?? namespace.schema,
+    relation.table
+  ]);
+}
+function readRows(result) {
+  const rows = Array.isArray(result) ? result : isRecord(result) && Array.isArray(result.data) ? result.data : isRecord(result) && Array.isArray(result.rows) ? result.rows : void 0;
+  if (!rows || rows.some((row) => !isRecord(row))) {
+    throw new Error(
+      "DuckDB execute() must return row objects as an array, { data }, or { rows }."
+    );
+  }
+  return rows;
+}
+function buildOutOfScopePayload(sql, referencedEntities, allowedEntities) {
+  return {
+    error: `Query references entities outside grounded scope: ${referencedEntities.join(", ")}`,
+    error_type: "OUT_OF_SCOPE",
+    suggestion: "Restrict the query to grounded tables/views or expand grounding to include the referenced entities.",
+    sql_attempted: sql,
+    referenced_entities: referencedEntities,
+    allowed_entities: allowedEntities
+  };
+}
+var DuckDBSerializationError = class extends Error {
+};
+function isReadOnlySerializationError(error) {
+  return error instanceof DuckDBSerializationError;
+}
+function caseFold(value) {
+  return value.toLocaleLowerCase("en-US");
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/text2sql/src/lib/adapters/duckdb/duckdb.ts
+var DuckDB = class extends Adapter {
+  #options;
+  #namespace;
+  grounding;
+  defaultSchema = "main";
+  systemSchemas = ["information_schema", "pg_catalog"];
+  formatterLanguage = "duckdb";
+  constructor(options) {
+    if (!options || typeof options.execute !== "function") {
+      throw new Error("DuckDB adapter requires an execute(sql) function.");
+    }
+    validateScopeOption("catalogs", options.catalogs);
+    validateScopeOption("schemas", options.schemas);
+    super(new DuckDBSqlPolicyAnalyzer(options.execute));
+    this.#options = options;
+    this.grounding = options.grounding ?? [];
+  }
+  get catalogs() {
+    return this.#options.catalogs;
+  }
+  get schemas() {
+    return this.#options.schemas;
+  }
+  async executeImpl(sql) {
+    return rowsFromResult(await this.#options.execute(sql));
+  }
+  async validateImpl(sql) {
+    try {
+      if (this.#options.validate) return await this.#options.validate(sql);
+      await this.#options.execute(`EXPLAIN ${sql}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return JSON.stringify({
+        error: message,
+        error_type: "DUCKDB_ERROR",
+        suggestion: "Review the DuckDB syntax and verify referenced catalogs, schemas, tables, columns, and functions.",
+        sql_attempted: sql
+      });
+    }
+  }
+  async runQuery(sql) {
+    return rowsFromResult(await this.#options.execute(sql));
+  }
+  quoteIdentifier(name) {
+    return formatDuckDBIdentifierPath([name]);
+  }
+  escape(value) {
+    return value.replaceAll('"', '""');
+  }
+  buildSampleRowsQuery(tableName, columns, limit) {
+    const relation = parseDuckDBRelationName(tableName);
+    const path = [relation.catalog, relation.schema, relation.table].filter(
+      (part) => part !== void 0
+    );
+    const projection = columns?.length ? columns.map((column2) => this.quoteIdentifier(column2)).join(", ") : "*";
+    return `SELECT ${projection} FROM ${formatDuckDBIdentifierPath(path)} LIMIT ${limit}`;
+  }
+  async currentNamespace() {
+    return this.#namespace ??= this.#loadNamespace();
+  }
+  async resolveRelationName(name) {
+    const relation = parseDuckDBRelationName(name);
+    const current = await this.currentNamespace();
+    return {
+      catalog: relation.catalog ?? current.catalog,
+      schema: relation.schema ?? current.schema,
+      table: relation.table
+    };
+  }
+  formatRelationName(catalog, schema, table2) {
+    return formatDuckDBIdentifierPath([catalog, schema, table2]);
+  }
+  quoteRelationName(name) {
+    const relation = parseDuckDBRelationName(name);
+    return formatDuckDBIdentifierPath(
+      [relation.catalog, relation.schema, relation.table].filter(
+        (part) => part !== void 0
+      )
+    );
+  }
+  async scopedNamespaces() {
+    const current = await this.currentNamespace();
+    return {
+      catalogs: [...this.catalogs ?? [current.catalog]],
+      schemas: [...this.schemas ?? [current.schema]]
+    };
+  }
+  async #loadNamespace() {
+    const rows = await this.runQuery(`
+      SELECT current_database() AS catalog, current_schema() AS schema
+    `);
+    const row = rows[0];
+    if (rows.length !== 1 || typeof row?.catalog !== "string" || typeof row.schema !== "string") {
+      throw new Error(
+        "DuckDB current namespace returned an unknown row shape."
+      );
+    }
+    return { catalog: row.catalog, schema: row.schema };
+  }
+};
+function validateScopeOption(name, values) {
+  if (values !== void 0 && (values.length === 0 || values.some((value) => !value))) {
+    throw new Error(`DuckDB ${name} must contain at least one non-empty name.`);
+  }
+}
+function rowsFromResult(result) {
+  if (Array.isArray(result)) return result;
+  if (result && typeof result === "object") {
+    const candidate = result;
+    if (Array.isArray(candidate.data)) return candidate.data;
+    if (Array.isArray(candidate.rows)) return candidate.rows;
+  }
+  throw new Error(
+    "DuckDB execute() must return an array of rows, { data: rows }, or { rows }."
+  );
+}
+
+// packages/text2sql/src/lib/adapters/duckdb/index.ts
+function tables(config = {}) {
+  return (adapter) => new DuckDBTableGrounding(adapter, config);
+}
+function info(config = {}) {
+  return (adapter) => new DuckDBInfoGrounding(adapter, config);
+}
+function views(config = {}) {
+  return (adapter) => new DuckDBViewGrounding(adapter, config);
+}
+function constraints(config = {}) {
+  return (adapter) => new DuckDBConstraintGrounding(adapter, config);
+}
+function indexes(config = {}) {
+  return (adapter) => new DuckDBIndexesGrounding(adapter, config);
+}
+function rowCount(config = {}) {
+  return (adapter) => new DuckDBRowCountGrounding(adapter, config);
+}
+function columnStats(config = {}) {
+  return (adapter) => new DuckDBColumnStatsGrounding(adapter, config);
+}
+function columnValues(config = {}) {
+  return (adapter) => new DuckDBColumnValuesGrounding(adapter, config);
+}
+var duckdb_default = {
+  tables,
+  info,
+  views,
+  constraints,
+  indexes,
+  rowCount,
+  columnStats,
+  columnValues,
+  DuckDB
+};
+export {
+  DuckDB,
+  DuckDBSqlPolicyAnalyzer,
+  columnStats,
+  columnValues,
+  constraints,
+  duckdb_default as default,
+  indexes,
+  info,
+  rowCount,
+  tables,
+  views
+};
+//# sourceMappingURL=index.js.map