feat(context): add warehouse verification tools (#46)

* feat(context): add warehouse dialect dispatch * feat(context): read warehouse scan catalog * feat(context): add entity details verification tool * feat(context): add ingest SQL verification tool * feat(context): add raw warehouse discovery tool * feat(context): expose warehouse verification tools to ingest * docs(context): add ingest identifier verification protocol * test(context): guard ingest identifier verification prompts * chore(context): verify warehouse verification tools * docs: add warehouse verification tools plan and spec * fix(context): expose target warehouses to Notion ingest * fix(context): update ingest prompts for warehouse verification tools * fix(context): scope raw schema discovery to allowed connections * fix(context): verify warehouse column display targets * docs: add notion warehouse verification gap closure plan * fix(context): include raw discovery connection names * fix(context): expose warehouse targets for LookML and MetricFlow * fix(context): pass connection config to ingest query executors * fix(cli): enable read-only SQL probes for local ingest * docs: add warehouse verification final v1 closure plan * fix(context): align warehouse sql probe prompt shape * docs: add warehouse verification prompt shape closure plan * test(context): catch connectionless sql execution prompt examples * fix(context): include connection name in sl capture sql example * docs: add warehouse verification sql example closure plan * fix(context): report structured entity detail misses * docs: add warehouse verification structured target miss closure plan * fix: report untracked squash merge conflicts * feat: require ingest verification ledger * fix: stabilize ingest wiki references
2026-06-22 08:38:08 +02:00 · 2026-05-13 13:43:23 +02:00 · 2026-05-13 13:43:23 +02:00 · c22248dabf
commit c22248dabf
parent bcb0d2f8f7
89 changed files with 7818 additions and 191 deletions
--- a/packages/context/src/ingest/tools/warehouse-verification/sql-execution.tool.ts
+++ b/packages/context/src/ingest/tools/warehouse-verification/sql-execution.tool.ts
@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { assertReadOnlySql, limitSqlForExecution } from '../../../connections/index.js';
+import type { SlConnectionCatalogPort } from '../../../sl/index.js';
+import { BaseTool, type ToolContext, type ToolOutput } from '../../../tools/index.js';
+
+const sqlExecutionInputSchema = z.object({
+  connectionName: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/),
+  sql: z.string().min(1),
+  rowLimit: z.number().int().positive().max(1000).optional().default(100),
+});
+
+type SqlExecutionInput = z.input<typeof sqlExecutionInputSchema>;
+
+export interface SqlExecutionStructured {
+  headers: string[];
+  rows: unknown[][];
+  rowCount: number;
+  truncated: boolean;
+  sql: string;
+  wrappedSql: string;
+  error?: string;
+}
+
+function markdownTable(headers: string[], rows: unknown[][], totalRows: number): string {
+  if (headers.length === 0) {
+    return rows.length === 0 ? 'Query returned no rows.' : JSON.stringify(rows.slice(0, 20));
+  }
+  const visible = rows.slice(0, 20);
+  const lines = [
+    `| ${headers.join(' | ')} |`,
+    `| ${headers.map(() => '---').join(' | ')} |`,
+    ...visible.map((row) => `| ${row.map((value) => String(value ?? '')).join(' | ')} |`),
+  ];
+  if (totalRows > visible.length) {
+    lines.push(`... +${totalRows - visible.length} more rows`);
+  }
+  return lines.join('\n');
+}
+
+export class SqlExecutionTool extends BaseTool<typeof sqlExecutionInputSchema> {
+  readonly name = 'sql_execution';
+
+  constructor(private readonly connections: SlConnectionCatalogPort) {
+    super();
+  }
+
+  get description(): string {
+    return 'Run a single read-only SELECT or WITH probe against an allowed warehouse connection and return a capped markdown table or the warehouse error.';
+  }
+
+  get inputSchema() {
+    return sqlExecutionInputSchema;
+  }
+
+  async call(input: SqlExecutionInput, context: ToolContext): Promise<ToolOutput<SqlExecutionStructured>> {
+    const allowed = context.session?.allowedConnectionNames;
+    if (allowed && !allowed.has(input.connectionName)) {
+      return {
+        markdown: `Connection "${input.connectionName}" is not available to this ingest stage.`,
+        structured: {
+          headers: [],
+          rows: [],
+          rowCount: 0,
+          truncated: false,
+          sql: input.sql,
+          wrappedSql: '',
+          error: 'connection_not_allowed',
+        },
+      };
+    }
+
+    let sql: string;
+    let wrappedSql: string;
+    try {
+      sql = assertReadOnlySql(input.sql);
+      wrappedSql = limitSqlForExecution(sql, input.rowLimit);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        markdown: message,
+        structured: { headers: [], rows: [], rowCount: 0, truncated: false, sql: input.sql, wrappedSql: '', error: message },
+      };
+    }
+
+    try {
+      const result = await this.connections.executeQuery(input.connectionName, wrappedSql);
+      const headers = result.headers ?? [];
+      const rows = result.rows ?? [];
+      const rowCount = result.totalRows ?? rows.length;
+      return {
+        markdown: markdownTable(headers, rows, rowCount),
+        structured: { headers, rows, rowCount, truncated: rowCount > rows.length, sql, wrappedSql },
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        markdown: `SQL execution failed: ${message}`,
+        structured: { headers: [], rows: [], rowCount: 0, truncated: false, sql, wrappedSql, error: message },
+      };
+    }
+  }
+}