@deepagents/text2sql 7.0.2 → 7.1.1

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

@@ -1,1554 +1,1674 @@
-// 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));
+// packages/text2sql/src/lib/adapters/adapter.ts
+import { format as formatSql } from "sql-formatter";
+import { z } from "zod";
+
+// 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;
   }
-  if (filter instanceof RegExp) {
-    return columns.filter((col) => filter.test(col.name));
+  static isInstance(error) {
+    return error instanceof _SQLValidationError && error[sqlValidationMarker] === true;
   }
-  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;
+};
+var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
+  [unanswerableSqlMarker];
+  constructor(message) {
+    super(message);
+    this.name = "UnanswerableSQLError";
+    this[unanswerableSqlMarker] = true;
   }
-  /**
-   * 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) {
+  static isInstance(error) {
+    return error instanceof _UnanswerableSQLError && error[unanswerableSqlMarker] === true;
   }
 };
-
-// packages/text2sql/src/lib/adapters/groundings/column-stats.grounding.ts
-var ColumnStatsGrounding = class extends AbstractGrounding {
-  constructor(config = {}) {
-    super("columnStats", "column_stats");
+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;
   }
-  /**
-   * 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
-          );
-        }
-      }
-    }
+  static isInstance(error) {
+    return error instanceof _SQLScopeError && error[sqlScopeMarker] === true;
   }
 };
-
-// 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;
+var SQLReadOnlyError = class _SQLReadOnlyError extends Error {
+  [sqlReadOnlyMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLReadOnlyError";
+    this[sqlReadOnlyMarker] = true;
   }
-  /**
-   * 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;
+  static isInstance(error) {
+    return error instanceof _SQLReadOnlyError && error[sqlReadOnlyMarker] === true;
   }
-  /**
-   * 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;
+};
+
+// 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 }
     }
-    if (constraint2.columns && !constraint2.columns.includes(columnName)) {
-      return void 0;
+  };
+}
+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 }
     }
-    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]);
+  };
+}
+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 }
     }
-    const anyMatch = def.match(
-      new RegExp(
-        `${colPattern}\\s*=\\s*ANY\\s*\\(\\s*(?:ARRAY)?\\s*\\[([^\\]]+)\\]`,
-        "i"
-      )
-    );
-    if (anyMatch) {
-      return this.extractStringValues(anyMatch[1]);
+  };
+}
+function index(input) {
+  return {
+    name: "index",
+    data: {
+      name: input.name,
+      columns: input.columns,
+      ...input.unique && { unique: true },
+      ...input.type && { type: input.type }
     }
-    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]);
+  };
+}
+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
+      }
     }
-    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]);
+  };
+}
+function view(input) {
+  return {
+    name: "view",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      columns: input.columns,
+      ...input.definition && { definition: input.definition }
     }
-    return values.length > 0 ? values : void 0;
-  }
-  /**
-   * Escape special regex characters in a string.
-   */
-  escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  }
+  };
+}
+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
+function groundingFor(adapterType, create) {
+  return (adapter) => {
+    if (!(adapter instanceof adapterType)) {
+      throw new Error(
+        `A ${adapterType.name} grounding needs a ${adapterType.name} adapter, not ${adapter.constructor.name}.`
+      );
+    }
+    return create(adapter);
+  };
+}
+var Adapter = class {
+  #policyAnalyzer;
   /**
-   * Get the table from context by name.
+   * Injects the strategy that guards validate() and execute().
    */
-  getTable(ctx, name) {
-    return ctx.tables.find((t) => t.name === name);
+  constructor(policyAnalyzer) {
+    this.#policyAnalyzer = policyAnalyzer;
   }
   /**
-   * Execute the grounding process.
-   * Annotates columns in ctx.tables and ctx.views with values.
+   * 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 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
-          );
+  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.`
+          });
         }
       }
     }
-  }
-  exceedsMaxValueLength(values) {
-    return values.some((v) => v.length > this.maxValueLength);
+    return this.#toSchemaFragments(ctx);
   }
   /**
-   * Resolve column values from all sources in priority order.
+   * 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 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 };
+  async resolveAllowedEntities() {
+    const ctx = createGroundingContext();
+    for (const fn of this.grounding) {
+      await fn(this).contributeEntities(ctx);
     }
-    return void 0;
-  }
-};
-
-// packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
-var ConstraintGrounding = class extends AbstractGrounding {
-  constructor(config = {}) {
-    super("constraint", "constraints");
+    return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
   }
   /**
-   * Execute the grounding process.
-   * Annotates tables in ctx.tables with their constraints.
+   * Convert complete grounding context to schema fragments.
+   * Called after all groundings have populated ctx with data.
    */
-  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);
+  #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)
+      );
     }
-  }
-};
-
-// packages/text2sql/src/lib/adapters/groundings/indexes.grounding.ts
-var IndexesGrounding = class extends AbstractGrounding {
-  constructor(config = {}) {
-    super("index", "indexes");
+    fragments.push(...ctx.fragments ?? []);
+    return fragments;
   }
   /**
-   * Execute the grounding process.
-   * Annotates tables in ctx.tables with their indexes and marks indexed columns.
+   * Convert a Table to a table fragment with nested column, index, and constraint fragments.
    */
-  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;
-          }
+  #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);
         }
       }
     }
-  }
-};
-
-// packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
-var InfoGrounding = class extends AbstractGrounding {
-  constructor(config = {}) {
-    super("dialectInfo", "info");
+    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
+    });
   }
   /**
-   * Execute the grounding process.
-   * Writes database info to ctx.info.
+   * Convert a View to a view fragment with nested column fragments.
    */
-  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");
+  #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
+    });
   }
   /**
-   * Execute the grounding process.
-   * Annotates tables in ctx.tables with row counts and size hints.
+   * Convert a Relationship to a relationship fragment.
+   * Infers cardinality from row counts if available.
    */
-  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);
+  #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
+    });
   }
-  /**
-   * 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";
+  format(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    try {
+      return formatSql(decoded, { language: this.formatterLanguage });
+    } catch {
+      return decoded;
+    }
   }
-};
-
-// 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;
+  #decodeShellEscapes(sql) {
+    return sql.replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\([().*$])/g, "$1").replace(/\\(?=$)/gm, "");
   }
-  async contributeEntities(ctx) {
-    await this.execute(ctx);
+  #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;
   }
   /**
-   * Execute the grounding process.
-   * Writes discovered tables and relationships to the context.
+   * Run an introspection query and check every row against `row`, the shape
+   * the driver returns for that query. A row of any other shape throws.
    */
-  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);
-        })
+  async runQuery(sql, row) {
+    const rows = z.array(row).safeParse(await this.queryRows(sql));
+    if (!rows.success) {
+      throw new Error(
+        `${this.constructor.name} introspection query returned rows of an unexpected shape:
+${z.prettifyError(rows.error)}
+SQL: ${sql.trim()}`,
+        { cause: rows.error }
       );
-      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 });
-          }
-        }
-      }
+    return rows.data;
+  }
+  /**
+   * The rows in a driver's execute() result: the result itself when it is an
+   * array, otherwise the first array found at one of `paths` (dot-separated,
+   * so `recordsets.0` reads `result.recordsets[0]`).
+   */
+  rowsFrom(result, paths) {
+    if (Array.isArray(result)) return result;
+    for (const path of paths) {
+      const rows = path.split(".").reduce(
+        (value, key) => typeof value === "object" && value !== null ? Reflect.get(value, key) : void 0,
+        result
+      );
+      if (Array.isArray(rows)) return rows;
     }
-    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);
+    throw new Error(
+      `${this.constructor.name} execute() must return an array of rows or an object holding one at ${paths.map((path) => `result.${path}`).join(", ")}.`
+    );
   }
   /**
-   * Apply the filter to get seed table names.
-   * If filter is an explicit array, skip querying all table names.
+   * Convert unknown database value to number.
+   * Handles number, bigint, and string types.
    */
-  async applyFilter() {
-    const filter = this.#filter;
-    if (Array.isArray(filter)) {
-      return filter;
+  toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
     }
-    const names = await this.getAllTableNames();
-    if (!filter) {
-      return names;
+    if (typeof value === "bigint") {
+      return Number(value);
     }
-    if (filter instanceof RegExp) {
-      return names.filter((name) => filter.test(name));
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : void 0;
     }
-    return names.filter(filter);
+    return void 0;
   }
   /**
-   * Add a relationship to the collection, deduplicating by key.
+   * Parse a potentially qualified table name into schema and table parts.
    */
-  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);
+  parseTableName(name) {
+    if (name.includes(".")) {
+      const [schema, ...rest] = name.split(".");
+      return { schema, table: rest.join(".") };
     }
+    return { schema: this.defaultSchema ?? "", table: name };
   }
-  isRelationshipVisible(rel) {
-    return this.areColumnsVisible(rel.from, this.#columns?.[rel.table]) && this.areColumnsVisible(rel.to, this.#columns?.[rel.referenced_table]);
+  /**
+   * 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, "''");
   }
-  areColumnsVisible(names, filter) {
-    if (!filter) return true;
-    return filterColumns(
-      names.map((name) => ({ name })),
-      filter
-    ).length === names.length;
+  /**
+   * 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/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;
+// packages/text2sql/src/lib/adapters/duckdb/duckdb.groundings.ts
+import { z as z3 } from "zod";
+
+// 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));
   }
-  async contributeEntities(ctx) {
-    await this.execute(ctx);
+  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 {
   /**
-   * Execute the grounding process.
-   * Writes discovered views to the context.
+   * Grounding identifier for debugging/logging.
    */
-  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);
+  name;
+  phase;
+  constructor(name, phase) {
+    this.name = name;
+    this.phase = phase;
   }
   /**
-   * Apply the filter to get view names.
-   * If filter is an explicit array, skip querying all view names.
+   * 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 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);
+  async contributeEntities(_ctx) {
   }
 };
 
-// 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] };
+// packages/text2sql/src/lib/adapters/groundings/column-stats.grounding.ts
+var ColumnStatsGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("columnStats", "column_stats");
   }
-  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;
+  /**
+   * 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
+          );
+        }
       }
-    } 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;
+// 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;
   }
-  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
-          )
-        );
-      }
+  /**
+   * 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;
     }
-    return result;
+    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;
   }
-  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
-      );
-    });
+  /**
+   * 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;
   }
-  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."
+  /**
+   * 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
           );
         }
-        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));
+  exceedsMaxValueLength(values) {
+    return values.some((v) => v.length > this.maxValueLength);
   }
-  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);
-    });
+  /**
+   * 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;
   }
 };
-var DuckDBInfoGrounding = class extends InfoGrounding {
-  #adapter;
-  constructor(adapter, config = {}) {
-    super(config);
-    this.#adapter = adapter;
+
+// packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
+var ConstraintGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("constraint", "constraints");
   }
-  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"]
+  /**
+   * 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);
       }
-    };
+    }
   }
 };
-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
-          )
-        );
+
+// 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;
+          }
+        }
       }
     }
-    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;
+
+// packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
+var InfoGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("dialectInfo", "info");
   }
-  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;
+  /**
+   * Execute the grounding process.
+   * Writes database info to ctx.info.
+   */
+  async execute(ctx) {
+    ctx.info = await this.collectInfo();
   }
 };
-var DuckDBIndexesGrounding = class extends IndexesGrounding {
-  #adapter;
-  constructor(adapter, config = {}) {
-    super(config);
-    this.#adapter = adapter;
+
+// packages/text2sql/src/lib/adapters/groundings/row-count.grounding.ts
+var RowCountGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("rowCount", "row_counts");
   }
-  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 [];
+  /**
+   * 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);
       }
-      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);
+  /**
+   * 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";
   }
 };
-var DuckDBColumnStatsGrounding = class extends ColumnStatsGrounding {
-  #adapter;
-  constructor(adapter, config = {}) {
-    super(config);
-    this.#adapter = adapter;
+
+// packages/text2sql/src/lib/adapters/groundings/rows.ts
+import { z as z2 } from "zod";
+var nameRow = z2.object({ name: z2.string() });
+var versionRow = z2.object({ version: z2.string() });
+var databaseRow = z2.object({ db: z2.string() });
+var viewDefinitionRow = z2.object({
+  definition: z2.string().nullable()
+});
+var distinctValueRow = z2.object({ value: z2.unknown() });
+var textValueRow = z2.object({ value: z2.string() });
+var numericValue = z2.union([z2.number(), z2.bigint(), z2.string()]);
+
+// 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 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)
-    };
+  async contributeEntities(ctx) {
+    await this.execute(ctx);
   }
-};
-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 }
+  /**
+   * 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;
     }
-  };
-}
-function index(input) {
-  return {
-    name: "index",
-    data: {
-      name: input.name,
-      columns: input.columns,
-      ...input.unique && { unique: true },
-      ...input.type && { type: input.type }
+    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 });
     }
-  };
-}
-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
+    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
+        );
       }
-    }
-  };
-}
-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) {
+      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:start",
-          phase: grounding.phase,
-          message: `Starting ${grounding.name} introspection...`
+          type: "phase:progress",
+          phase: "tables",
+          table: name,
+          message: `Loading table ${name}...`,
+          current: loadedCount
         });
+        tables2[name] = applyColumnFilter(
+          await this.getTable(name),
+          this.#columns
+        );
       }
-      try {
-        await grounding.execute(ctx);
-      } finally {
-        if (grounding.phase) {
-          ctx.onProgress({
-            type: "phase:end",
-            phase: grounding.phase,
-            message: `Finished ${grounding.name} introspection.`
-          });
+      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 });
+          }
         }
       }
     }
-    return this.#toSchemaFragments(ctx);
+    const tablesList = Object.values(tables2);
+    ctx.tables.push(...tablesList);
+    ctx.relationships.push(...allRelationships);
   }
   /**
-   * 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.
+   * Apply the filter to get seed table names.
+   * If filter is an explicit array, skip querying all table names.
    */
-  async resolveAllowedEntities() {
-    const ctx = createGroundingContext();
-    for (const fn of this.grounding) {
-      await fn(this).contributeEntities(ctx);
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
     }
-    return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
+    const names = await this.getAllTableNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
   }
   /**
-   * Convert complete grounding context to schema fragments.
-   * Called after all groundings have populated ctx with data.
+   * Add a relationship to the collection, deduplicating by key.
    */
-  #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)
-      );
+  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);
     }
-    fragments.push(...ctx.fragments ?? []);
-    return fragments;
+  }
+  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);
   }
   /**
-   * Convert a Table to a table fragment with nested column, index, and constraint fragments.
+   * Execute the grounding process.
+   * Writes discovered views to the context.
    */
-  #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 ?? []) ?? []
+  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);
+      })
     );
-    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);
-        }
+    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;
     }
-    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}`);
+  }
+  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 tableNameRow = z3.object({
+  database_name: z3.string(),
+  schema_name: z3.string(),
+  table_name: z3.string()
+});
+var viewNameRow = z3.object({
+  database_name: z3.string(),
+  schema_name: z3.string(),
+  view_name: z3.string()
+});
+var columnRow = z3.object({ column_name: z3.string(), data_type: z3.string() });
+var columnNameRow = z3.object({ column_name: z3.string() });
+var columnDefaultRow = z3.object({
+  column_name: z3.string(),
+  column_default: z3.string()
+});
+var infoRow = z3.object({
+  version: z3.string(),
+  catalog: z3.string(),
+  schema: z3.string()
+});
+var viewSqlRow = z3.object({ sql: z3.string().nullable() });
+var constraintRow = z3.object({
+  constraint_name: z3.string(),
+  constraint_type: z3.string(),
+  expression: z3.string().nullable(),
+  constraint_column_names: z3.array(z3.string()),
+  referenced_table: z3.string().nullable(),
+  referenced_column_names: z3.array(z3.string())
+});
+var foreignKeyRow = constraintRow.extend({ table_name: z3.string() });
+var indexRow = z3.object({
+  index_name: z3.string(),
+  expressions: z3.array(z3.string()).nullable(),
+  is_unique: z3.boolean(),
+  is_primary: z3.boolean()
+});
+var estimatedSizeRow = z3.object({ estimated_size: numericValue.nullable() });
+var columnStatsRow = z3.object({
+  min_value: z3.string().nullable(),
+  max_value: z3.string().nullable(),
+  null_fraction: z3.number().nullable(),
+  n_distinct: numericValue
+});
+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
+          )
+        );
       }
     }
-    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
-      })
+    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
+    `,
+      tableNameRow
     );
-    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
-      })
+    return rows.map(
+      (row) => this.#adapter.formatRelationName(
+        row.database_name,
+        row.schema_name,
+        row.table_name
+      )
     );
-    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
-      })
+  }
+  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
+    `,
+      columnRow
     );
-    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
+    return {
+      name: this.#adapter.formatRelationName(catalog, schema, table2),
+      schema: formatDuckDBIdentifierPath([catalog, schema]),
+      rawName: table2,
+      columns: rows.map(columnFromRow)
+    };
+  }
+  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: row.table_name
+      };
+      return relationshipFromRow(this.#adapter, source, row);
     });
   }
-  /**
-   * 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
-      })
+};
+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
+    `,
+      infoRow
     );
-    return view({
-      name: v.name,
-      schema: v.schema,
-      columns: columnFragments,
-      definition: v.definition
-    });
+    const row = rows.at(0);
+    return {
+      dialect: "duckdb",
+      version: row?.version,
+      database: row?.catalog,
+      details: {
+        currentSchema: row?.schema ?? "unknown",
+        identifierQualification: "catalog.schema.table",
+        parameterPlaceholders: ["$1", "$name"]
+      }
+    };
   }
-  /**
-   * 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";
+};
+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 relationship({
-      from: { table: rel.table, columns: rel.from },
-      to: { table: rel.referenced_table, columns: rel.to },
-      cardinality
-    });
+    return result;
   }
-  format(sql) {
-    const decoded = this.#decodeShellEscapes(sql);
-    try {
-      return formatSql(decoded, { language: this.formatterLanguage });
-    } catch {
-      return decoded;
+  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
+    `,
+      viewNameRow
+    );
+    return rows.map(
+      (row) => this.#adapter.formatRelationName(
+        row.database_name,
+        row.schema_name,
+        row.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
+      `,
+        columnRow
+      ),
+      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)}'
+          `,
+        viewSqlRow
+      ) : Promise.resolve([])
+    ]);
+    return {
+      name: this.#adapter.formatRelationName(
+        relation.catalog,
+        relation.schema,
+        relation.table
+      ),
+      schema: formatDuckDBIdentifierPath([relation.catalog, relation.schema]),
+      rawName: relation.table,
+      definition: definitions.at(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
+      `,
+        constraintRow
+      ),
+      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
+      `,
+        columnDefaultRow
+      )
+    ]);
+    const constraints2 = rows.map(
+      (row) => constraintFromRow(this.#adapter, relation, row)
+    );
+    for (const column2 of columns) {
+      constraints2.push({
+        name: `${relation.table}_${column2.column_name}_default`,
+        type: "DEFAULT",
+        columns: [column2.column_name],
+        defaultValue: column2.column_default
+      });
     }
+    return constraints2;
   }
-  #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;
+};
+var DuckDBIndexesGrounding = class extends IndexesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
   }
-  async #analyzePolicy(sql) {
-    return this.#policyAnalyzer.analyze(sql, {
-      resolveAllowedEntities: () => this.#resolveScope()
+  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
+      `,
+        indexRow
+      ),
+      this.#adapter.runQuery(
+        `
+        SELECT column_name
+        FROM duckdb_columns()
+        WHERE ${relationPredicate(this.#adapter, relation)}
+        ORDER BY column_index
+      `,
+        columnNameRow
+      )
+    ]);
+    const tableColumns = columnRows.map((row) => row.column_name);
+    return rows.flatMap((row) => {
+      if (row.expressions === null) {
+        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,
+          type: row.is_primary ? "PRIMARY" : void 0
+        }
+      ] : [];
     });
   }
-  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);
+};
+var DuckDBRowCountGrounding = class extends RowCountGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
   }
-  async execute(sql) {
-    return this.executeImpl(await this.enforceExecutionPolicy(sql));
+  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)}
+    `,
+      estimatedSizeRow
+    );
+    return this.#adapter.toNumber(rows.at(0)?.estimated_size);
   }
-  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;
+};
+var DuckDBColumnStatsGrounding = class extends ColumnStatsGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
   }
-  /**
-   * 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;
+  async collectStats(tableName, column2) {
+    if (!/int|real|numeric|double|float|decimal|date|time|bool/i.test(column2.type)) {
+      return void 0;
     }
-    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}
+    `,
+      columnStatsRow
+    );
+    const row = rows.at(0);
+    if (!row) return void 0;
+    return {
+      min: row.min_value ?? void 0,
+      max: row.max_value ?? void 0,
+      nullFraction: this.#adapter.toNumber(row.null_fraction),
+      nDistinct: this.#adapter.toNumber(row.n_distinct)
+    };
   }
-  /**
-   * 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 };
+};
+var DuckDBColumnValuesGrounding = class extends ColumnValuesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
   }
-  /**
-   * 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, "''");
+  async collectEnumValues(_tableName, column2) {
+    return parseEnumLabels(column2.type);
   }
-  /**
-   * 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})`;
+  async collectLowCardinality(tableName, column2) {
+    if (/\b(?:BLOB|STRUCT|MAP|LIST|UNION|ARRAY)\b/i.test(column2.type)) {
+      return void 0;
     }
-    if (this.systemSchemas.length > 0) {
-      const values = this.systemSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
-      return `AND ${columnName} NOT IN (${values})`;
+    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}
+    `,
+      textValueRow
+    );
+    if (rows.length === 0 || rows.length > this.lowCardinalityLimit) {
+      return void 0;
     }
-    return "";
+    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: row.column_name, type: row.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
+  `,
+    foreignKeyRow
+  );
+}
+function relationshipFromRow(adapter, source, row) {
+  return {
+    table: adapter.formatRelationName(
+      source.catalog,
+      source.schema,
+      source.table
+    ),
+    from: row.constraint_column_names,
+    referenced_table: adapter.formatRelationName(
+      source.catalog,
+      source.schema,
+      requiredString(row.referenced_table, "referenced_table")
+    ),
+    to: row.referenced_column_names
+  };
+}
+function constraintFromRow(adapter, relation, row) {
+  const mapped = CONSTRAINT_TYPES.get(row.constraint_type);
+  if (!mapped) {
+    throw new Error(`Unknown DuckDB constraint type: ${row.constraint_type}`);
+  }
+  const referenced = mapped === "FOREIGN_KEY" ? adapter.formatRelationName(
+    relation.catalog,
+    relation.schema,
+    requiredString(row.referenced_table, "referenced_table")
+  ) : void 0;
+  return {
+    name: row.constraint_name,
+    type: mapped,
+    columns: row.constraint_column_names,
+    definition: mapped === "CHECK" && row.expression !== null ? row.expression : void 0,
+    referencedTable: referenced,
+    referencedColumns: mapped === "FOREIGN_KEY" ? row.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 (value === null) {
+    throw new Error(`DuckDB catalog field ${field} must be a string.`);
+  }
+  return value;
+}
+
+// packages/text2sql/src/lib/adapters/duckdb/duckdb.ts
+import { z as z4 } from "zod";
 
 // packages/text2sql/src/lib/sql-scope-error.ts
 function buildScopeParseErrorPayload(sql, parserDialect, error) {
@@ -1764,6 +1884,7 @@ function isRecord(value) {
 }
 
 // packages/text2sql/src/lib/adapters/duckdb/duckdb.ts
+var namespaceRow = z4.object({ catalog: z4.string(), schema: z4.string() });
 var DuckDB = class extends Adapter {
   #options;
   #namespace;
@@ -1788,7 +1909,7 @@ var DuckDB = class extends Adapter {
     return this.#options.schemas;
   }
   async executeImpl(sql) {
-    return rowsFromResult(await this.#options.execute(sql));
+    return this.rowsFrom(await this.#options.execute(sql), ["data", "rows"]);
   }
   async validateImpl(sql) {
     try {
@@ -1804,8 +1925,8 @@ var DuckDB = class extends Adapter {
       });
     }
   }
-  async runQuery(sql) {
-    return rowsFromResult(await this.#options.execute(sql));
+  async queryRows(sql) {
+    return this.rowsFrom(await this.#options.execute(sql), ["data", "rows"]);
   }
   quoteIdentifier(name) {
     return formatDuckDBIdentifierPath([name]);
@@ -1852,11 +1973,14 @@ var DuckDB = class extends Adapter {
     };
   }
   async #loadNamespace() {
-    const rows = await this.runQuery(`
+    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") {
+    `,
+      namespaceRow
+    );
+    const row = rows.at(0);
+    if (rows.length !== 1 || !row) {
       throw new Error(
         "DuckDB current namespace returned an unknown row shape."
       );
@@ -1869,42 +1993,55 @@ function validateScopeOption(name, values) {
     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);
+  return groundingFor(
+    DuckDB,
+    (adapter) => new DuckDBTableGrounding(adapter, config)
+  );
 }
 function info(config = {}) {
-  return (adapter) => new DuckDBInfoGrounding(adapter, config);
+  return groundingFor(
+    DuckDB,
+    (adapter) => new DuckDBInfoGrounding(adapter, config)
+  );
 }
 function views(config = {}) {
-  return (adapter) => new DuckDBViewGrounding(adapter, config);
+  return groundingFor(
+    DuckDB,
+    (adapter) => new DuckDBViewGrounding(adapter, config)
+  );
 }
 function constraints(config = {}) {
-  return (adapter) => new DuckDBConstraintGrounding(adapter, config);
+  return groundingFor(
+    DuckDB,
+    (adapter) => new DuckDBConstraintGrounding(adapter, config)
+  );
 }
 function indexes(config = {}) {
-  return (adapter) => new DuckDBIndexesGrounding(adapter, config);
+  return groundingFor(
+    DuckDB,
+    (adapter) => new DuckDBIndexesGrounding(adapter, config)
+  );
 }
 function rowCount(config = {}) {
-  return (adapter) => new DuckDBRowCountGrounding(adapter, config);
+  return groundingFor(
+    DuckDB,
+    (adapter) => new DuckDBRowCountGrounding(adapter, config)
+  );
 }
 function columnStats(config = {}) {
-  return (adapter) => new DuckDBColumnStatsGrounding(adapter, config);
+  return groundingFor(
+    DuckDB,
+    (adapter) => new DuckDBColumnStatsGrounding(adapter, config)
+  );
 }
 function columnValues(config = {}) {
-  return (adapter) => new DuckDBColumnValuesGrounding(adapter, config);
+  return groundingFor(
+    DuckDB,
+    (adapter) => new DuckDBColumnValuesGrounding(adapter, config)
+  );
 }
 var duckdb_default = {
   tables,