feat: [AI-5975] add sql_quality telemetry for issue prevention metrics

suryaiyer95 · claude · suryaiyer95 · commit a04bcf0f36dc · 2026-03-24T11:47:36.000-07:00
Add a new `sql_quality` telemetry event that fires whenever tools
successfully detect SQL issues — turning findings into measurable
"issues prevented" data in App Insights.

Architecture:
- New `sql_quality` event type in `Telemetry.Event` with `finding_count`,
  `by_severity`, `by_category`, `has_schema`, `dialect`, `duration_ms`
- New `Telemetry.Finding` interface and `aggregateFindings()` helper
- Centralized emission in `tool.ts` — checks `metadata.findings` array
  after any tool completes, aggregates counts, emits event
- Tools populate `metadata.findings` with `{category, severity}` pairs:
  - `sql_analyze`: issue type + severity from lint/semantic/safety analysis
  - `altimate_core_validate`: classified validation errors (missing_table,
    missing_column, syntax_error, type_mismatch)
  - `altimate_core_semantics`: rule/type + severity from semantic checks
  - `altimate_core_fix`: fix_applied / unfixable_error categories
  - `altimate_core_correct`: correction_applied findings
  - `altimate_core_equivalence`: equivalence_difference findings

PII-safe: only category names and severity levels flow to telemetry,
never SQL content.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/packages/opencode/src/altimate/telemetry/index.ts b/packages/opencode/src/altimate/telemetry/index.ts
@@ -405,6 +405,23 @@ export namespace Telemetry {
         masked_args?: string
         duration_ms: number
       }
+    // altimate_change start — sql quality telemetry for issue prevention metrics
+    | {
+        type: "sql_quality"
+        timestamp: number
+        session_id: string
+        tool_name: string
+        tool_category: string
+        finding_count: number
+        /** JSON-encoded Record<string, number> — count per severity level */
+        by_severity: string
+        /** JSON-encoded Record<string, number> — count per issue category */
+        by_category: string
+        has_schema: boolean
+        dialect: string
+        duration_ms: number
+      }
+    // altimate_change end
 
   const ERROR_PATTERNS: Array<{
     class: Telemetry.Event & { type: "core_failure" } extends { error_class: infer C } ? C : never
@@ -774,6 +791,28 @@ export namespace Telemetry {
     }
   }
 
+  // altimate_change start — sql quality telemetry types
+  /** Lightweight finding record for quality telemetry. Only category/severity — never SQL content. */
+  export interface Finding {
+    category: string
+    severity: string
+  }
+
+  /** Aggregate an array of findings into counts suitable for the sql_quality event. */
+  export function aggregateFindings(findings: Finding[]): {
+    by_severity: Record<string, number>
+    by_category: Record<string, number>
+  } {
+    const by_severity: Record<string, number> = {}
+    const by_category: Record<string, number> = {}
+    for (const f of findings) {
+      by_severity[f.severity] = (by_severity[f.severity] ?? 0) + 1
+      by_category[f.category] = (by_category[f.category] ?? 0) + 1
+    }
+    return { by_severity, by_category }
+  }
+  // altimate_change end
+
   export async function shutdown() {
     // Wait for init to complete so we know whether telemetry is enabled
     // and have a valid endpoint to flush to.  init() is fire-and-forget
diff --git a/packages/opencode/src/altimate/tools/altimate-core-correct.ts b/packages/opencode/src/altimate/tools/altimate-core-correct.ts
@@ -1,6 +1,7 @@
 import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
+import type { Telemetry } from "../telemetry"
 
 export const AltimateCoreCorrectTool = Tool.define("altimate_core_correct", {
   description:
@@ -11,21 +12,34 @@ export const AltimateCoreCorrectTool = Tool.define("altimate_core_correct", {
     schema_context: z.record(z.string(), z.any()).optional().describe("Inline schema definition"),
   }),
   async execute(args, ctx) {
+    const hasSchema = !!(args.schema_path || (args.schema_context && Object.keys(args.schema_context).length > 0))
     try {
       const result = await Dispatcher.call("altimate_core.correct", {
         sql: args.sql,
         schema_path: args.schema_path ?? "",
         schema_context: args.schema_context,
       })
       const data = result.data as Record<string, any>
+      // altimate_change start — sql quality findings for telemetry
+      const findings: Telemetry.Finding[] = (data.changes ?? []).map(() => ({
+        category: "correction_applied" as const,
+        severity: "warning" as const,
+      }))
+      // altimate_change end
       return {
         title: `Correct: ${data.success ? "CORRECTED" : "COULD NOT CORRECT"}`,
-        metadata: { success: result.success, iterations: data.iterations },
+        metadata: {
+          success: result.success,
+          iterations: data.iterations,
+          has_schema: hasSchema,
+          dialect: "snowflake",
+          ...(findings.length > 0 && { findings }),
+        },
         output: formatCorrect(data),
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
-      return { title: "Correct: ERROR", metadata: { success: false, iterations: 0 }, output: `Failed: ${msg}` }
+      return { title: "Correct: ERROR", metadata: { success: false, iterations: 0, has_schema: hasSchema, dialect: "snowflake" }, output: `Failed: ${msg}` }
     }
   },
 })
diff --git a/packages/opencode/src/altimate/tools/altimate-core-equivalence.ts b/packages/opencode/src/altimate/tools/altimate-core-equivalence.ts
@@ -1,6 +1,7 @@
 import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
+import type { Telemetry } from "../telemetry"
 
 export const AltimateCoreEquivalenceTool = Tool.define("altimate_core_equivalence", {
   description:
@@ -12,6 +13,7 @@ export const AltimateCoreEquivalenceTool = Tool.define("altimate_core_equivalenc
     schema_context: z.record(z.string(), z.any()).optional().describe("Inline schema definition"),
   }),
   async execute(args, ctx) {
+    const hasSchema = !!(args.schema_path || (args.schema_context && Object.keys(args.schema_context).length > 0))
     try {
       const result = await Dispatcher.call("altimate_core.equivalence", {
         sql1: args.sql1,
@@ -20,14 +22,28 @@ export const AltimateCoreEquivalenceTool = Tool.define("altimate_core_equivalenc
         schema_context: args.schema_context,
       })
       const data = result.data as Record<string, any>
+      // altimate_change start — sql quality findings for telemetry
+      const findings: Telemetry.Finding[] = []
+      if (!data.equivalent && data.differences?.length) {
+        for (const d of data.differences) {
+          findings.push({ category: "equivalence_difference", severity: "warning" })
+        }
+      }
+      // altimate_change end
       return {
         title: `Equivalence: ${data.equivalent ? "EQUIVALENT" : "DIFFERENT"}`,
-        metadata: { success: result.success, equivalent: data.equivalent },
+        metadata: {
+          success: result.success,
+          equivalent: data.equivalent,
+          has_schema: hasSchema,
+          dialect: "snowflake",
+          ...(findings.length > 0 && { findings }),
+        },
         output: formatEquivalence(data),
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
-      return { title: "Equivalence: ERROR", metadata: { success: false, equivalent: false }, output: `Failed: ${msg}` }
+      return { title: "Equivalence: ERROR", metadata: { success: false, equivalent: false, has_schema: hasSchema, dialect: "snowflake" }, output: `Failed: ${msg}` }
     }
   },
 })
diff --git a/packages/opencode/src/altimate/tools/altimate-core-fix.ts b/packages/opencode/src/altimate/tools/altimate-core-fix.ts
@@ -1,6 +1,7 @@
 import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
+import type { Telemetry } from "../telemetry"
 
 export const AltimateCoreFixTool = Tool.define("altimate_core_fix", {
   description:
@@ -12,6 +13,7 @@ export const AltimateCoreFixTool = Tool.define("altimate_core_fix", {
     max_iterations: z.number().optional().describe("Maximum fix iterations (default: 5)"),
   }),
   async execute(args, ctx) {
+    const hasSchema = !!(args.schema_path || (args.schema_context && Object.keys(args.schema_context).length > 0))
     try {
       const result = await Dispatcher.call("altimate_core.fix", {
         sql: args.sql,
@@ -20,14 +22,29 @@ export const AltimateCoreFixTool = Tool.define("altimate_core_fix", {
         max_iterations: args.max_iterations ?? 5,
       })
       const data = result.data as Record<string, any>
+      // altimate_change start — sql quality findings for telemetry
+      const findings: Telemetry.Finding[] = []
+      for (const fix of data.fixes_applied ?? data.changes ?? []) {
+        findings.push({ category: "fix_applied", severity: "warning" })
+      }
+      for (const err of data.unfixable_errors ?? []) {
+        findings.push({ category: "unfixable_error", severity: "error" })
+      }
+      // altimate_change end
       return {
         title: `Fix: ${data.success ? "FIXED" : "COULD NOT FIX"}`,
-        metadata: { success: result.success, fixed: !!data.fixed_sql },
+        metadata: {
+          success: result.success,
+          fixed: !!data.fixed_sql,
+          has_schema: hasSchema,
+          dialect: "snowflake",
+          ...(findings.length > 0 && { findings }),
+        },
         output: formatFix(data),
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
-      return { title: "Fix: ERROR", metadata: { success: false, fixed: false }, output: `Failed: ${msg}` }
+      return { title: "Fix: ERROR", metadata: { success: false, fixed: false, has_schema: hasSchema, dialect: "snowflake" }, output: `Failed: ${msg}` }
     }
   },
 })
diff --git a/packages/opencode/src/altimate/tools/altimate-core-semantics.ts b/packages/opencode/src/altimate/tools/altimate-core-semantics.ts
@@ -1,6 +1,7 @@
 import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
+import type { Telemetry } from "../telemetry"
 
 export const AltimateCoreSemanticsTool = Tool.define("altimate_core_semantics", {
   description:
@@ -11,6 +12,7 @@ export const AltimateCoreSemanticsTool = Tool.define("altimate_core_semantics",
     schema_context: z.record(z.string(), z.any()).optional().describe("Inline schema definition"),
   }),
   async execute(args, ctx) {
+    const hasSchema = !!(args.schema_path || (args.schema_context && Object.keys(args.schema_context).length > 0))
     try {
       const result = await Dispatcher.call("altimate_core.semantics", {
         sql: args.sql,
@@ -19,14 +21,27 @@ export const AltimateCoreSemanticsTool = Tool.define("altimate_core_semantics",
       })
       const data = result.data as Record<string, any>
       const issueCount = data.issues?.length ?? 0
+      // altimate_change start — sql quality findings for telemetry
+      const findings: Telemetry.Finding[] = (data.issues ?? []).map((issue: any) => ({
+        category: issue.rule ?? issue.type ?? "semantic_issue",
+        severity: issue.severity ?? "warning",
+      }))
+      // altimate_change end
       return {
         title: `Semantics: ${data.valid ? "VALID" : `${issueCount} issues`}`,
-        metadata: { success: result.success, valid: data.valid, issue_count: issueCount },
+        metadata: {
+          success: result.success,
+          valid: data.valid,
+          issue_count: issueCount,
+          has_schema: hasSchema,
+          dialect: "snowflake",
+          ...(findings.length > 0 && { findings }),
+        },
         output: formatSemantics(data),
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
-      return { title: "Semantics: ERROR", metadata: { success: false, valid: false, issue_count: 0 }, output: `Failed: ${msg}` }
+      return { title: "Semantics: ERROR", metadata: { success: false, valid: false, issue_count: 0, has_schema: hasSchema, dialect: "snowflake" }, output: `Failed: ${msg}` }
     }
   },
 })
diff --git a/packages/opencode/src/altimate/tools/altimate-core-validate.ts b/packages/opencode/src/altimate/tools/altimate-core-validate.ts
@@ -1,6 +1,7 @@
 import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
+import type { Telemetry } from "../telemetry"
 
 export const AltimateCoreValidateTool = Tool.define("altimate_core_validate", {
   description:
@@ -11,25 +12,48 @@ export const AltimateCoreValidateTool = Tool.define("altimate_core_validate", {
     schema_context: z.record(z.string(), z.any()).optional().describe("Inline schema definition"),
   }),
   async execute(args, ctx) {
+    const hasSchema = !!(args.schema_path || (args.schema_context && Object.keys(args.schema_context).length > 0))
     try {
       const result = await Dispatcher.call("altimate_core.validate", {
         sql: args.sql,
         schema_path: args.schema_path ?? "",
         schema_context: args.schema_context,
       })
       const data = result.data as Record<string, any>
+      // altimate_change start — sql quality findings for telemetry
+      const findings: Telemetry.Finding[] = (data.errors ?? []).map((err: any) => ({
+        category: classifyValidationError(err.message ?? ""),
+        severity: "error",
+      }))
+      // altimate_change end
       return {
         title: `Validate: ${data.valid ? "VALID" : "INVALID"}`,
-        metadata: { success: result.success, valid: data.valid },
+        metadata: {
+          success: result.success,
+          valid: data.valid,
+          has_schema: hasSchema,
+          dialect: "snowflake",
+          ...(findings.length > 0 && { findings }),
+        },
         output: formatValidate(data),
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
-      return { title: "Validate: ERROR", metadata: { success: false, valid: false }, output: `Failed: ${msg}` }
+      return { title: "Validate: ERROR", metadata: { success: false, valid: false, has_schema: hasSchema, dialect: "snowflake" }, output: `Failed: ${msg}` }
     }
   },
 })
 
+function classifyValidationError(message: string): string {
+  const lower = message.toLowerCase()
+  // Column check before table — "column not found in table" would match both
+  if (lower.includes("column") && lower.includes("not found")) return "missing_column"
+  if (lower.includes("table") && lower.includes("not found")) return "missing_table"
+  if (lower.includes("syntax")) return "syntax_error"
+  if (lower.includes("type")) return "type_mismatch"
+  return "validation_error"
+}
+
 function formatValidate(data: Record<string, any>): string {
   if (data.error) return `Error: ${data.error}`
   if (data.valid) return "SQL is valid."
diff --git a/packages/opencode/src/altimate/tools/sql-analyze.ts b/packages/opencode/src/altimate/tools/sql-analyze.ts
@@ -1,6 +1,7 @@
 import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
+import type { Telemetry } from "../telemetry"
 import type { SqlAnalyzeResult } from "../native/types"
 
 export const SqlAnalyzeTool = Tool.define("sql_analyze", {
@@ -21,21 +22,30 @@ export const SqlAnalyzeTool = Tool.define("sql_analyze", {
         dialect: args.dialect,
       })
 
+      // altimate_change start — sql quality findings for telemetry
+      const findings: Telemetry.Finding[] = result.issues.map((issue) => ({
+        category: issue.type,
+        severity: issue.severity,
+      }))
+      // altimate_change end
       return {
         title: `Analyze: ${result.error ? "PARSE ERROR" : `${result.issue_count} issue${result.issue_count !== 1 ? "s" : ""}`} [${result.confidence}]`,
         metadata: {
           success: result.success,
           issueCount: result.issue_count,
           confidence: result.confidence,
+          dialect: args.dialect,
+          has_schema: false,
           ...(result.error && { error: result.error }),
+          ...(findings.length > 0 && { findings }),
         },
         output: formatAnalysis(result),
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
       return {
         title: "Analyze: ERROR",
-        metadata: { success: false, issueCount: 0, confidence: "unknown", error: msg },
+        metadata: { success: false, issueCount: 0, confidence: "unknown", dialect: args.dialect, has_schema: false, error: msg },
         output: `Failed to analyze SQL: ${msg}\n\nCheck your connection configuration and try again.`,
       }
     }
diff --git a/packages/opencode/src/tool/tool.ts b/packages/opencode/src/tool/tool.ts
@@ -156,6 +156,25 @@ export namespace Tool {
                 duration_ms: durationMs,
               })
             }
+            // altimate_change start — emit sql_quality when tools report findings
+            const findings = result.metadata?.findings as Telemetry.Finding[] | undefined
+            if (Array.isArray(findings) && findings.length > 0) {
+              const { by_severity, by_category } = Telemetry.aggregateFindings(findings)
+              Telemetry.track({
+                type: "sql_quality",
+                timestamp: Date.now(),
+                session_id: ctx.sessionID,
+                tool_name: id,
+                tool_category: toolCategory,
+                finding_count: findings.length,
+                by_severity: JSON.stringify(by_severity),
+                by_category: JSON.stringify(by_category),
+                has_schema: result.metadata?.has_schema ?? false,
+                dialect: (result.metadata?.dialect as string) ?? "unknown",
+                duration_ms: durationMs,
+              })
+            }
+            // altimate_change end
           } catch {
             // Telemetry must never break tool execution
           }
diff --git a/packages/opencode/test/altimate/sql-quality-telemetry.test.ts b/packages/opencode/test/altimate/sql-quality-telemetry.test.ts
