fix: defensive null guards in tool formatters and DuckDB concurrent access retry (#570)

- Add null/undefined guards across 8 tool formatters to prevent literal
  `undefined` in user-facing output (sql-analyze, schema-inspect,
  sql-translate, dbt-manifest, finops-analyze-credits, warehouse-list,
  altimate-core-check, altimate-core-rewrite)
- Add `error: msg` to catch block metadata in schema-inspect,
  dbt-manifest, warehouse-list so telemetry can classify exceptions
- DuckDB driver: auto-retry in `READ_ONLY` mode on `database is locked`
  errors, with clear actionable error message
- Add simulation suite (839 mock + 346 real E2E scenarios) covering
  10 personas x 11 dialects x 14 use-case categories

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anandgupta42

.github/meta/commit.txt

@@ -1,17 +1,14 @@
-ci: add Verdaccio sanity suite to CI and release workflows
-
-Adds the Verdaccio-based sanity suite (real `npm install -g` flow)
-to both CI and release pipelines:
-
-**CI (`ci.yml`):**
-- New `sanity-verdaccio` job on push to main
-- Builds linux-x64 binary + dbt-tools, runs full Docker Compose suite
-- Independent of other jobs (doesn't block PRs)
-
-**Release (`release.yml`):**
-- New `sanity-verdaccio` job between build and npm publish
-- Downloads linux-x64 artifact from build matrix
-- **Blocks `publish-npm`** — broken install flow prevents release
-- Dependency chain: build → sanity-verdaccio → publish-npm → github-release
+fix: defensive null guards in tool formatters and DuckDB concurrent access retry (#570)
+
+- Add null/undefined guards across 8 tool formatters to prevent literal
+  `undefined` in user-facing output (sql-analyze, schema-inspect,
+  sql-translate, dbt-manifest, finops-analyze-credits, warehouse-list,
+  altimate-core-check, altimate-core-rewrite)
+- Add `error: msg` to catch block metadata in schema-inspect,
+  dbt-manifest, warehouse-list so telemetry can classify exceptions
+- DuckDB driver: auto-retry in `READ_ONLY` mode on `database is locked`
+  errors, with clear actionable error message
+- Add simulation suite (839 mock + 346 real E2E scenarios) covering
+  10 personas x 11 dialects x 14 use-case categories
 
 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/drivers/src/duckdb.ts

@@ -17,10 +17,24 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
   let db: any
   let connection: any
 
+  // altimate_change start — improve DuckDB error messages
+  function wrapDuckDBError(err: Error): Error {
+    const msg = err.message || String(err)
+    if (msg.includes("locked") || msg.includes("SQLITE_BUSY")) {
+      return new Error(
+        `Database "${dbPath}" is locked by another process. ` +
+        `DuckDB does not support concurrent write access. ` +
+        `Close other connections to this file and try again.`,
+      )
+    }
+    return err
+  }
+  // altimate_change end
+
   function query(sql: string): Promise<any[]> {
     return new Promise((resolve, reject) => {
       connection.all(sql, (err: Error | null, rows: any[]) => {
-        if (err) reject(err)
+        if (err) reject(wrapDuckDBError(err))
         else resolve(rows ?? [])
       })
     })
@@ -29,33 +43,65 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
   function queryWithParams(sql: string, params: any[]): Promise<any[]> {
     return new Promise((resolve, reject) => {
       connection.all(sql, ...params, (err: Error | null, rows: any[]) => {
-        if (err) reject(err)
+        if (err) reject(wrapDuckDBError(err))
         else resolve(rows ?? [])
       })
     })
   }
 
   return {
     async connect() {
-      db = await new Promise<any>((resolve, reject) => {
-        let resolved = false
-        const instance = new duckdb.Database(
-          dbPath,
-          (err: Error | null) => {
-            if (resolved) return // Already resolved via timeout
-            resolved = true
-            if (err) reject(err)
-            else resolve(instance)
-          },
-        )
-        // Bun: native callback may not fire; fall back after 2s
-        setTimeout(() => {
-          if (!resolved) {
-            resolved = true
-            resolve(instance)
+      // altimate_change start — retry with read-only on lock errors
+      const tryConnect = (accessMode?: string): Promise<any> =>
+        new Promise<any>((resolve, reject) => {
+          let resolved = false
+          let timeout: ReturnType<typeof setTimeout> | undefined
+          const opts = accessMode ? { access_mode: accessMode } : undefined
+          const instance = new duckdb.Database(
+            dbPath,
+            opts,
+            (err: Error | null) => {
+              if (resolved) return
+              resolved = true
+              if (timeout) clearTimeout(timeout)
+              if (err) {
+                const msg = err.message || String(err)
+                if (msg.includes("locked") || msg.includes("SQLITE_BUSY")) {
+                  reject(new Error("DUCKDB_LOCKED"))
+                } else {
+                  reject(err)
+                }
+              } else {
+                resolve(instance)
+              }
+            },
+          )
+          // Bun: native callback may not fire; fall back after 2s
+          timeout = setTimeout(() => {
+            if (!resolved) {
+              resolved = true
+              reject(new Error(`Timed out opening DuckDB database "${dbPath}"`))
+            }
+          }, 2000)
+        })
+
+      try {
+        db = await tryConnect()
+      } catch (err: any) {
+        if (err.message === "DUCKDB_LOCKED" && dbPath !== ":memory:") {
+          // Retry in read-only mode — allows concurrent reads
+          try {
+            db = await tryConnect("READ_ONLY")
+          } catch (retryErr) {
+            throw wrapDuckDBError(
+              retryErr instanceof Error ? retryErr : new Error(String(retryErr)),
+            )
           }
-        }, 2000)
-      })
+        } else {
+          throw err
+        }
+      }
+      // altimate_change end
       connection = db.connect()
     },
 

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

@@ -84,7 +84,7 @@ export function formatCheck(data: Record<string, any>): string {
     lines.push("No lint findings.")
   } else {
     for (const f of data.lint?.findings ?? []) {
-      lines.push(`  [${f.severity}] ${f.rule}: ${f.message}`)
+      lines.push(`  [${f.severity ?? "warning"}] ${f.rule ?? "lint"}: ${f.message ?? ""}`)
     }
   }
 
@@ -93,7 +93,7 @@ export function formatCheck(data: Record<string, any>): string {
     lines.push("Safe — no threats.")
   } else {
     for (const t of data.safety?.threats ?? []) {
-      lines.push(`  [${t.severity}] ${t.type}: ${t.description}`)
+      lines.push(`  [${t.severity ?? "warning"}] ${t.type ?? "safety"}: ${t.description ?? ""}`)
     }
   }
 
@@ -102,7 +102,7 @@ export function formatCheck(data: Record<string, any>): string {
     lines.push("No PII detected.")
   } else {
     for (const p of data.pii?.findings ?? []) {
-      lines.push(`  ${p.column}: ${p.category} (${p.confidence} confidence)`)
+      lines.push(`  ${p.column ?? "unknown"}: ${p.category ?? "PII"} (${p.confidence ?? "unknown"} confidence)`)
     }
   }
 

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

@@ -54,7 +54,7 @@ function formatRewrite(data: Record<string, any>): string {
   }
   lines.push("Rewrites applied:")
   for (const r of suggestions) {
-    lines.push(`  - ${r.rule ?? r.type}: ${r.explanation ?? r.description ?? r.improvement}`)
+    lines.push(`  - ${r.rule ?? r.type ?? "rewrite"}: ${r.explanation ?? r.description ?? r.improvement ?? ""}`)
   }
   return lines.join("\n")
 }

packages/opencode/src/altimate/tools/dbt-manifest.ts

@@ -14,7 +14,7 @@ export const DbtManifestTool = Tool.define("dbt_manifest", {
       const result = await Dispatcher.call("dbt.manifest", { path: args.path })
 
       return {
-        title: `Manifest: ${result.model_count} models, ${result.source_count} sources`,
+        title: `Manifest: ${result.model_count ?? 0} models, ${result.source_count ?? 0} sources`,
         metadata: {
           model_count: result.model_count,
           source_count: result.source_count,
@@ -28,7 +28,7 @@ export const DbtManifestTool = Tool.define("dbt_manifest", {
       const msg = e instanceof Error ? e.message : String(e)
       return {
         title: "Manifest: ERROR",
-        metadata: { model_count: 0, source_count: 0, test_count: 0, snapshot_count: 0, seed_count: 0 },
+        metadata: { model_count: 0, source_count: 0, test_count: 0, snapshot_count: 0, seed_count: 0, error: msg },
         output: `Failed to parse manifest: ${msg}\n\nEnsure the manifest.json exists and the dispatcher is running.`,
       }
     }
@@ -39,31 +39,36 @@ function formatManifest(result: DbtManifestResult): string {
   const lines: string[] = []
 
   lines.push("=== Project Summary ===")
-  lines.push(`Models: ${result.model_count}`)
-  lines.push(`Sources: ${result.source_count}`)
-  lines.push(`Tests: ${result.test_count}`)
-  lines.push(`Snapshots: ${result.snapshot_count}`)
-  lines.push(`Seeds: ${result.seed_count}`)
+  lines.push(`Models: ${result.model_count ?? 0}`)
+  lines.push(`Sources: ${result.source_count ?? 0}`)
+  lines.push(`Tests: ${result.test_count ?? 0}`)
+  lines.push(`Snapshots: ${result.snapshot_count ?? 0}`)
+  lines.push(`Seeds: ${result.seed_count ?? 0}`)
 
-  if (result.models.length > 0) {
+  const models = result.models ?? []
+  const sources = result.sources ?? []
+
+  if (models.length > 0) {
     lines.push("")
     lines.push("=== Models ===")
     lines.push("Name | Schema | Materialized | Dependencies | Columns")
     lines.push("-----|--------|-------------|-------------|--------")
-    for (const model of result.models) {
-      const deps = model.depends_on.length > 0 ? model.depends_on.map((d) => d.split(".").pop()).join(", ") : "-"
-      const cols = model.columns.length > 0 ? model.columns.map((c) => c.name).join(", ") : "-"
+    for (const model of models) {
+      const depsArr = model.depends_on ?? []
+      const colsArr = model.columns ?? []
+      const deps = depsArr.length > 0 ? depsArr.map((d) => d.split(".").pop()).join(", ") : "-"
+      const cols = colsArr.length > 0 ? colsArr.map((c) => c.name).join(", ") : "-"
       lines.push(`${model.name} | ${model.schema_name ?? "-"} | ${model.materialized ?? "-"} | ${deps} | ${cols}`)
     }
   }
 
-  if (result.sources.length > 0) {
+  if (sources.length > 0) {
     lines.push("")
     lines.push("=== Sources ===")
     lines.push("Source | Table | Schema | Columns")
     lines.push("-------|-------|--------|--------")
-    for (const source of result.sources) {
-      const cols = source.columns.length > 0 ? source.columns.map((c) => c.name).join(", ") : "-"
+    for (const source of sources) {
+      const cols = (source.columns ?? []).length > 0 ? (source.columns ?? []).map((c) => c.name).join(", ") : "-"
       lines.push(`${source.source_name} | ${source.name} | ${source.schema_name ?? "-"} | ${cols}`)
     }
   }

packages/opencode/src/altimate/tools/finops-analyze-credits.ts

@@ -88,14 +88,16 @@ export const FinopsAnalyzeCreditsTool = Tool.define("finops_analyze_credits", {
         }
       }
 
+      const totalCredits = Number(result.total_credits ?? 0)
+      const daysAnalyzed = result.days_analyzed ?? args.days
       return {
-        title: `Credits: ${result.total_credits.toFixed(2)} over ${result.days_analyzed}d`,
-        metadata: { success: true, total_credits: result.total_credits },
+        title: `Credits: ${totalCredits.toFixed(2)} over ${daysAnalyzed}d`,
+        metadata: { success: true, total_credits: totalCredits },
         output: formatCreditsAnalysis(
-          result.total_credits as number,
-          result.warehouse_summary as unknown[],
-          result.recommendations as unknown[],
-          result.daily_usage as unknown[],
+          totalCredits,
+          (result.warehouse_summary ?? []) as unknown[],
+          (result.recommendations ?? []) as unknown[],
+          (result.daily_usage ?? []) as unknown[],
         ),
       }
     } catch (e) {

packages/opencode/src/altimate/tools/schema-inspect.ts

@@ -34,15 +34,15 @@ export const SchemaInspectTool = Tool.define("schema_inspect", {
       }
       // altimate_change end
       return {
-        title: `Schema: ${result.table}`,
-        metadata: { columnCount: result.columns.length, rowCount: result.row_count },
+        title: `Schema: ${result.table ?? args.table}`,
+        metadata: { columnCount: (result.columns ?? []).length, rowCount: result.row_count },
         output,
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
       return {
         title: "Schema: ERROR",
-        metadata: { columnCount: 0, rowCount: undefined },
+        metadata: { columnCount: 0, rowCount: undefined, error: msg },
         output: `Failed to inspect schema: ${msg}\n\nEnsure the dispatcher is running and a warehouse connection is configured.`,
       }
     }
@@ -51,17 +51,18 @@ export const SchemaInspectTool = Tool.define("schema_inspect", {
 
 function formatSchema(result: SchemaInspectResult): string {
   const lines: string[] = []
-  const qualified = result.schema_name ? `${result.schema_name}.${result.table}` : result.table
+  const table = result.table ?? "unknown"
+  const qualified = result.schema_name ? `${result.schema_name}.${table}` : table
   lines.push(`Table: ${qualified}`)
   if (result.row_count !== null && result.row_count !== undefined) {
     lines.push(`Rows: ${result.row_count.toLocaleString()}`)
   }
   lines.push("")
   lines.push("Column | Type | Nullable | PK")
   lines.push("-------|------|----------|---")
-  for (const col of result.columns) {
+  for (const col of result.columns ?? []) {
     lines.push(
-      `${col.name} | ${col.data_type} | ${col.nullable ? "YES" : "NO"} | ${col.primary_key ? "YES" : ""}`,
+      `${col.name} | ${col.data_type ?? "unknown"} | ${col.nullable ? "YES" : "NO"} | ${col.primary_key ? "YES" : ""}`,
     )
   }
   return lines.join("\n")

packages/opencode/src/altimate/tools/sql-analyze.ts

@@ -38,8 +38,8 @@ export const SqlAnalyzeTool = Tool.define("sql_analyze", {
       // there's an actual error (e.g. parse failure).
       const isRealFailure = !!result.error
       // altimate_change start — sql quality findings for telemetry
-      const findings: Telemetry.Finding[] = result.issues.map((issue) => ({
-        category: issue.rule ?? issue.type,
+      const findings: Telemetry.Finding[] = (result.issues ?? []).map((issue) => ({
+        category: issue.rule ?? issue.type ?? "analysis_issue",
       }))
       // altimate_change end
 
@@ -56,7 +56,7 @@ export const SqlAnalyzeTool = Tool.define("sql_analyze", {
       }
       // altimate_change end
       return {
-        title: `Analyze: ${result.error ? "ERROR" : `${result.issue_count} issue${result.issue_count !== 1 ? "s" : ""}`} [${result.confidence}]`,
+        title: `Analyze: ${result.error ? "ERROR" : `${result.issue_count ?? 0} issue${(result.issue_count ?? 0) !== 1 ? "s" : ""}`} [${result.confidence ?? "unknown"}]`,
         metadata: {
           success: !isRealFailure,
           issueCount: result.issue_count,
@@ -91,24 +91,27 @@ function formatAnalysis(result: SqlAnalyzeResult): string {
     return `Analysis failed: ${result.error}`
   }
 
-  if (result.issues.length === 0) {
+  const issues = result.issues ?? []
+  if (issues.length === 0) {
     return "No anti-patterns or issues detected."
   }
 
+  const issueCount = result.issue_count ?? issues.length
   const lines: string[] = [
-    `Found ${result.issue_count} issue${result.issue_count !== 1 ? "s" : ""} (confidence: ${result.confidence}):`,
+    `Found ${issueCount} issue${issueCount !== 1 ? "s" : ""} (confidence: ${result.confidence ?? "unknown"}):`,
   ]
-  if (result.confidence_factors.length > 0) {
-    lines.push(`  Note: ${result.confidence_factors.join("; ")}`)
+  const factors = result.confidence_factors ?? []
+  if (factors.length > 0) {
+    lines.push(`  Note: ${factors.join("; ")}`)
   }
   lines.push("")
 
-  for (const issue of result.issues) {
+  for (const issue of issues) {
     const loc = issue.location ? ` — ${issue.location}` : ""
-    const conf = issue.confidence !== "high" ? ` [${issue.confidence} confidence]` : ""
-    lines.push(`  [${issue.severity.toUpperCase()}] ${issue.type}${conf}`)
-    lines.push(`    ${issue.message}${loc}`)
-    lines.push(`    → ${issue.recommendation}`)
+    const conf = issue.confidence !== "high" ? ` [${issue.confidence ?? "unknown"} confidence]` : ""
+    lines.push(`  [${(issue.severity ?? "unknown").toUpperCase()}] ${issue.type ?? "unknown"}${conf}`)
+    lines.push(`    ${issue.message ?? ""}${loc}`)
+    lines.push(`    → ${issue.recommendation ?? ""}`)
     lines.push("")
   }
 

packages/opencode/src/altimate/tools/sql-translate.ts

@@ -29,7 +29,7 @@ export const SqlTranslateTool = Tool.define("sql_translate", {
           success: result.success,
           source_dialect: result.source_dialect,
           target_dialect: result.target_dialect,
-          warningCount: result.warnings.length,
+          warningCount: (result.warnings ?? []).length,
           ...(result.error && { error: result.error }),
         },
         output: formatTranslation(result, args.sql),
@@ -70,9 +70,10 @@ function formatTranslation(result: SqlTranslateResult, originalSql: string): str
   lines.push(result.translated_sql ?? "")
   lines.push("")
 
-  if (result.warnings.length > 0) {
+  const warnings = result.warnings ?? []
+  if (warnings.length > 0) {
     lines.push("--- Warnings ---")
-    for (const warning of result.warnings) {
+    for (const warning of warnings) {
       lines.push(`  ! ${warning}`)
     }
     lines.push("")