fix: [AI-5975] propagate actual error messages to telemetry instead of "unknown error"

Root cause: 6,905+ telemetry entries showed "unknown error" because tools
did not set `metadata.error` on failure paths. The telemetry layer in
`tool.ts` reads `metadata.error` — when missing, it logs "unknown error".

Changes:
- Add `error` field to `metadata` on all failure paths across 12 failing tools:
  `altimate_core_validate`, `altimate_core_fix`, `altimate_core_correct`,
  `altimate_core_semantics`, `altimate_core_equivalence`, `sql_explain`,
  `sql_analyze`, `finops_query_history`, `finops_expensive_queries`,
  `finops_analyze_credits`, `finops_unused_resources`, `finops_warehouse_advice`
- Add error extraction functions for nested napi-rs response structures:
  `extractValidationErrors()` (data.errors[]),
  `extractFixErrors()` (data.unfixable_errors[]),
  `extractCorrectErrors()` (data.final_validation.errors[]),
  `extractSemanticsErrors()` (data.validation_errors[]),
  `extractEquivalenceErrors()` (data.validation_errors[])
- Wire `schema_path`/`schema_context` params through `sql_analyze` tool
  to dispatcher (were completely disconnected — handler expected them)
- Add `schema_path` to `SqlAnalyzeParams` type
- Surface `unfixable_errors` from `sql.fix` handler in `register.ts`
- Clean up tool descriptions: remove "Rust-based altimate-core engine"
  boilerplate, add schema guidance where applicable
- Add `error?: string` to `Tool.Metadata` interface in `tool.ts`
- Add 18 regression tests using mock dispatcher with real failure shapes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: suryaiyer95

packages/opencode/src/altimate/native/sql/register.ts

@@ -215,13 +215,18 @@ register("sql.fix", async (params) => {
       fixed_sql: f.fixed_sql ?? f.rewritten_sql,
     }))
 
+    const unfixableError = !result.fixed && Array.isArray(result.unfixable_errors) && result.unfixable_errors.length > 0
+      ? result.unfixable_errors.map((e: any) => e.error?.message ?? e.reason ?? String(e)).join("; ")
+      : undefined
+
     return {
       success: result.fixed ?? true,
       original_sql: result.original_sql ?? params.sql,
       fixed_sql: result.fixed_sql ?? params.sql,
       error_message: params.error_message ?? "",
       suggestions,
       suggestion_count: suggestions.length,
+      ...(unfixableError && { error: unfixableError }),
     }
   } catch (e) {
     return {

packages/opencode/src/altimate/native/types.ts

@@ -24,6 +24,7 @@ export interface SqlExecuteResult {
 export interface SqlAnalyzeParams {
   sql: string
   dialect?: string
+  schema_path?: string
   schema_context?: Record<string, any>
 }
 
@@ -385,6 +386,7 @@ export interface SqlFixResult {
   error_message: string
   suggestions: SqlFixSuggestion[]
   suggestion_count: number
+  error?: string
 }
 
 // --- SQL Autocomplete ---

packages/opencode/src/altimate/tools/altimate-core-check.ts

@@ -4,7 +4,7 @@ import { Dispatcher } from "../native"
 
 export const AltimateCoreCheckTool = Tool.define("altimate_core_check", {
   description:
-    "Run full analysis pipeline: validate + lint + safety scan + PII check using the Rust-based altimate-core engine. Single call for comprehensive SQL analysis.",
+    "Run full analysis pipeline: validate + lint + safety scan + PII check. Single call for comprehensive SQL analysis. Provide schema_context or schema_path for accurate table/column resolution.",
   parameters: z.object({
     sql: z.string().describe("SQL query to analyze"),
     schema_path: z.string().optional().describe("Path to YAML/JSON schema file"),

packages/opencode/src/altimate/tools/altimate-core-classify-pii.ts

@@ -4,7 +4,7 @@ import { Dispatcher } from "../native"
 
 export const AltimateCoreClassifyPiiTool = Tool.define("altimate_core_classify_pii", {
   description:
-    "Classify PII columns in a schema using the Rust-based altimate-core engine. Identifies columns likely containing personal identifiable information by name patterns and data types.",
+    "Classify PII columns in a schema. Identifies columns likely containing personal identifiable information by name patterns and data types. Provide schema_context or schema_path for accurate table/column resolution.",
   parameters: z.object({
     schema_path: z.string().optional().describe("Path to YAML/JSON schema file"),
     schema_context: z.record(z.string(), z.any()).optional().describe("Inline schema definition"),

packages/opencode/src/altimate/tools/altimate-core-column-lineage.ts

@@ -4,7 +4,7 @@ import { Dispatcher } from "../native"
 
 export const AltimateCoreColumnLineageTool = Tool.define("altimate_core_column_lineage", {
   description:
-    "Trace schema-aware column lineage using the Rust-based altimate-core engine. Maps how columns flow through a query from source tables to output. Requires altimate_core.init() with API key.",
+    "Trace schema-aware column lineage. Maps how columns flow through a query from source tables to output. Requires altimate_core.init() with API key. Provide schema_context or schema_path for accurate table/column resolution.",
   parameters: z.object({
     sql: z.string().describe("SQL query to trace lineage for"),
     dialect: z.string().optional().describe("SQL dialect (e.g. snowflake, bigquery)"),

packages/opencode/src/altimate/tools/altimate-core-compare.ts

@@ -4,7 +4,7 @@ import { Dispatcher } from "../native"
 
 export const AltimateCoreCompareTool = Tool.define("altimate_core_compare", {
   description:
-    "Structurally compare two SQL queries using the Rust-based altimate-core engine. Identifies differences in table references, join conditions, filters, projections, and aggregations.",
+    "Structurally compare two SQL queries. Identifies differences in table references, join conditions, filters, projections, and aggregations.",
   parameters: z.object({
     left_sql: z.string().describe("First SQL query"),
     right_sql: z.string().describe("Second SQL query"),

packages/opencode/src/altimate/tools/altimate-core-complete.ts

@@ -4,7 +4,7 @@ import { Dispatcher } from "../native"
 
 export const AltimateCoreCompleteTool = Tool.define("altimate_core_complete", {
   description:
-    "Get cursor-aware SQL completion suggestions using the Rust-based altimate-core engine. Returns table names, column names, functions, and keywords relevant to the cursor position.",
+    "Get cursor-aware SQL completion suggestions. Returns table names, column names, functions, and keywords relevant to the cursor position. Provide schema_context or schema_path for accurate table/column resolution.",
   parameters: z.object({
     sql: z.string().describe("Partial SQL query"),
     cursor_pos: z.number().describe("Cursor position (0-indexed character offset)"),
@@ -23,12 +23,12 @@ export const AltimateCoreCompleteTool = Tool.define("altimate_core_complete", {
       const count = data.items?.length ?? data.suggestions?.length ?? 0
       return {
         title: `Complete: ${count} suggestion(s)`,
-        metadata: { success: result.success, suggestion_count: count },
+        metadata: { success: result.success, suggestion_count: count, error: result.error ?? (data as any).error },
         output: formatComplete(data),
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
-      return { title: "Complete: ERROR", metadata: { success: false, suggestion_count: 0 }, output: `Failed: ${msg}` }
+      return { title: "Complete: ERROR", metadata: { success: false, suggestion_count: 0, error: msg }, output: `Failed: ${msg}` }
     }
   },
 })

packages/opencode/src/altimate/tools/altimate-core-correct.ts

@@ -4,7 +4,7 @@ import { Dispatcher } from "../native"
 
 export const AltimateCoreCorrectTool = Tool.define("altimate_core_correct", {
   description:
-    "Iteratively correct SQL using a propose-verify-refine loop via the Rust-based altimate-core engine. More thorough than fix — applies multiple correction rounds to produce valid SQL.",
+    "Iteratively correct SQL using a propose-verify-refine loop. More thorough than fix — applies multiple correction rounds to produce valid SQL. Provide schema_context or schema_path for accurate table/column resolution.",
   parameters: z.object({
     sql: z.string().describe("SQL query to correct"),
     schema_path: z.string().optional().describe("Path to YAML/JSON schema file"),
@@ -18,18 +18,29 @@ export const AltimateCoreCorrectTool = Tool.define("altimate_core_correct", {
         schema_context: args.schema_context,
       })
       const data = result.data as Record<string, any>
+      const error = result.error ?? data.error ?? extractCorrectErrors(data)
       return {
         title: `Correct: ${data.success ? "CORRECTED" : "COULD NOT CORRECT"}`,
-        metadata: { success: result.success, iterations: data.iterations },
-        output: formatCorrect(data),
+        metadata: { success: result.success, iterations: data.iterations, error },
+        output: error ? `Error: ${error}` : 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, error: msg }, output: `Failed: ${msg}` }
     }
   },
 })
 
+function extractCorrectErrors(data: Record<string, any>): string | undefined {
+  if (data.final_validation?.errors?.length > 0) {
+    return data.final_validation.errors.map((e: any) => e.message ?? String(e)).join("; ")
+  }
+  if (Array.isArray(data.errors) && data.errors.length > 0) {
+    return data.errors.map((e: any) => e.message ?? String(e)).join("; ")
+  }
+  return undefined
+}
+
 function formatCorrect(data: Record<string, any>): string {
   if (data.error) return `Error: ${data.error}`
   const lines: string[] = []

packages/opencode/src/altimate/tools/altimate-core-equivalence.ts

@@ -4,7 +4,7 @@ import { Dispatcher } from "../native"
 
 export const AltimateCoreEquivalenceTool = Tool.define("altimate_core_equivalence", {
   description:
-    "Check semantic equivalence of two SQL queries using the Rust-based altimate-core engine. Determines if two queries produce the same result set regardless of syntactic differences.",
+    "Check semantic equivalence of two SQL queries. Determines if two queries produce the same result set regardless of syntactic differences. Provide schema_context or schema_path for accurate table/column resolution.",
   parameters: z.object({
     sql1: z.string().describe("First SQL query"),
     sql2: z.string().describe("Second SQL query"),
@@ -20,18 +20,26 @@ export const AltimateCoreEquivalenceTool = Tool.define("altimate_core_equivalenc
         schema_context: args.schema_context,
       })
       const data = result.data as Record<string, any>
+      const error = result.error ?? data.error ?? extractEquivalenceErrors(data)
       return {
         title: `Equivalence: ${data.equivalent ? "EQUIVALENT" : "DIFFERENT"}`,
-        metadata: { success: result.success, equivalent: data.equivalent },
+        metadata: { success: result.success, equivalent: data.equivalent, error },
         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, error: msg }, output: `Failed: ${msg}` }
     }
   },
 })
 
+function extractEquivalenceErrors(data: Record<string, any>): string | undefined {
+  if (Array.isArray(data.validation_errors) && data.validation_errors.length > 0) {
+    return data.validation_errors.join("; ")
+  }
+  return undefined
+}
+
 function formatEquivalence(data: Record<string, any>): string {
   if (data.error) return `Error: ${data.error}`
   const lines: string[] = []

packages/opencode/src/altimate/tools/altimate-core-export-ddl.ts

@@ -4,7 +4,7 @@ import { Dispatcher } from "../native"
 
 export const AltimateCoreExportDdlTool = Tool.define("altimate_core_export_ddl", {
   description:
-    "Export a YAML/JSON schema as CREATE TABLE DDL statements using the Rust-based altimate-core engine.",
+    "Export a YAML/JSON schema as CREATE TABLE DDL statements. Provide schema_context or schema_path for accurate table/column resolution.",
   parameters: z.object({
     schema_path: z.string().optional().describe("Path to YAML/JSON schema file"),
     schema_context: z.record(z.string(), z.any()).optional().describe("Inline schema definition"),