@poetic-ai/poetic 1.42.0

package/dist/chunk-5RBHQYDB.js

@@ -0,0 +1,2206 @@
+import {
+  getTelemetryLogger
+} from "./chunk-U6C3VVWS.js";
+import {
+  SCHEMA_INVARIANTS,
+  VARIANT_EXECUTION_COLUMNS
+} from "./chunk-FYOILAN5.js";
+import {
+  projectScope
+} from "./chunk-GAFJEYLK.js";
+import {
+  TelemetryPathResolver
+} from "./chunk-ZDTGECTN.js";
+import {
+  emitTelemetryFallbackWarning
+} from "./chunk-YMX76IOS.js";
+import {
+  getSqliteBusyTimeoutMs
+} from "./chunk-QGJDMEOV.js";
+import {
+  LabPathResolver
+} from "./chunk-7GDRQBQC.js";
+import {
+  getGlobalTelemetryDir
+} from "./chunk-UUH2RVKS.js";
+import {
+  emitWarning
+} from "./chunk-EJGCZGUF.js";
+
+// src/telemetry/dashboard.ts
+import fs from "fs";
+import path from "path";
+import Database from "better-sqlite3";
+var TelemetryDashboard = class _TelemetryDashboard {
+  /**
+   * Exclude synthetic test rows from dashboard queries.
+   * Tests that leak into the real DB typically have NULL verdict and/or task IDs
+   * prefixed with common test IDs (test-* and task-*).
+   * Without this filter, synthetic rows appear as failures and distort success-rate metrics.
+   */
+  static REAL_DATA_FILTER = "verdict IS NOT NULL AND verdict != '' AND task_id NOT LIKE 'test-%' AND task_id NOT LIKE 'task-%'";
+  /** SQLite database connection for variant execution telemetry */
+  variantsDb;
+  /** SQLite database connection for validation telemetry */
+  validationsDb;
+  enabled = true;
+  projectScopeWhere;
+  projectScopeParams;
+  /**
+   * Creates a new TelemetryDashboard instance
+   *
+   * Establishes connections to SQLite telemetry databases in .poetic/telemetry/db/
+   *
+   * @param options - Configuration options
+   * @throws {Error} If database files cannot be accessed
+   */
+  constructor(options = {}) {
+    const poeticDir = options.poeticDir || path.join(process.cwd(), ".poetic");
+    const resolver = TelemetryPathResolver.getInstance();
+    const dbDir = resolver.resolveDbDir(poeticDir);
+    const projectId = options.projectId?.trim() || resolver.getProjectId(poeticDir, { register: false });
+    const isGlobalDb = path.resolve(dbDir) === path.resolve(path.join(getGlobalTelemetryDir(), "db"));
+    const tenancyScope = projectScope(projectId, {
+      includeLabs: true,
+      includeLegacyProjectRows: !isGlobalDb,
+      legacyProjectIds: [""]
+    });
+    this.projectScopeWhere = tenancyScope.where;
+    this.projectScopeParams = tenancyScope.params;
+    try {
+      if (!fs.existsSync(dbDir)) {
+        fs.mkdirSync(dbDir, { recursive: true });
+      }
+      this.variantsDb = new Database(path.join(dbDir, "variants.db"));
+      this.validationsDb = new Database(path.join(dbDir, "validations.db"));
+      try {
+        this.variantsDb.pragma("journal_mode = WAL");
+      } catch {
+      }
+      try {
+        this.variantsDb.pragma(`busy_timeout = ${getSqliteBusyTimeoutMs()}`);
+      } catch {
+      }
+      try {
+        this.validationsDb.pragma("journal_mode = WAL");
+      } catch {
+      }
+      try {
+        this.validationsDb.pragma(`busy_timeout = ${getSqliteBusyTimeoutMs()}`);
+      } catch {
+      }
+      this.enabled = true;
+    } catch (err) {
+      console.warn(
+        "Telemetry dashboard: directory creation failed, attempting to open DB files directly",
+        err
+      );
+      try {
+        this.variantsDb = new Database(path.join(dbDir, "variants.db"));
+        this.validationsDb = new Database(path.join(dbDir, "validations.db"));
+        try {
+          this.variantsDb.pragma("journal_mode = WAL");
+        } catch {
+        }
+        try {
+          this.variantsDb.pragma(`busy_timeout = ${getSqliteBusyTimeoutMs()}`);
+        } catch {
+        }
+        try {
+          this.validationsDb.pragma("journal_mode = WAL");
+        } catch {
+        }
+        try {
+          this.validationsDb.pragma(`busy_timeout = ${getSqliteBusyTimeoutMs()}`);
+        } catch {
+        }
+        this.enabled = true;
+      } catch (err2) {
+        emitWarning(
+          "CFG-002",
+          {
+            taskId: "system",
+            subsystem: "telemetry",
+            executionPhase: "setup"
+          },
+          {
+            severity: "ERROR" /* ERROR */,
+            metadata: {
+              operation: "dashboard_initialization",
+              error: err2 instanceof Error ? err2.message : String(err2),
+              dbDir
+            }
+          }
+        );
+        this.variantsDb = new Database(":memory:");
+        this.validationsDb = new Database(":memory:");
+        this.enabled = false;
+      }
+    }
+  }
+  /** Returns true if the dashboard has persistent DB backing (not in-memory fallback) */
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Retrieve leaderboard data with optional advanced metrics and CI bounds.
+   * Returns structured rows for programmatic consumption (CLI export, UI).
+   */
+  getLeaderboardData(options = {}) {
+    const filters = [
+      this.projectScopeWhere,
+      "completed_at IS NOT NULL",
+      _TelemetryDashboard.REAL_DATA_FILTER
+    ];
+    const params = [...this.projectScopeParams];
+    if (options.taskId && options.taskId.trim() !== "") {
+      filters.push("task_id = ?");
+      params.push(options.taskId.trim());
+    }
+    let baseQuery = `
+      SELECT
+        variant,
+        COUNT(*) as total_tasks,
+        SUM(CASE WHEN verdict = 'success' THEN 1 ELSE 0 END) as successes,
+        CAST(SUM(CASE WHEN verdict = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) as success_rate,
+        AVG(completeness) as avg_completeness,
+        AVG(total_duration_sec) as avg_duration_sec,
+        MIN(started_at) as first_execution,
+        MAX(started_at) as last_execution
+      FROM variant_executions
+      WHERE ${filters.join(" AND ")}
+      GROUP BY variant
+    `;
+    const limit = typeof options.limit === "number" && Number.isFinite(options.limit) && options.limit > 0 ? Math.floor(options.limit) : void 0;
+    if (limit !== void 0) {
+      baseQuery += " ORDER BY total_tasks DESC LIMIT ?";
+      params.push(limit);
+    }
+    const stmt = this.variantsDb.prepare(baseQuery);
+    const rows = params.length ? stmt.all(...params) : stmt.all();
+    if (!rows) {
+      return [];
+    }
+    const result = rows.map((row) => {
+      const enriched = { ...row };
+      if (options.includeCI) {
+        const { lower, upper, width } = this.wilsonCI(row.success_rate, row.total_tasks);
+        enriched.ci_lower = lower;
+        enriched.ci_upper = upper;
+        enriched.ci_width = width;
+      }
+      return enriched;
+    });
+    if (options.includeFScore) {
+      const perVariantConf = this.computeConfusionByVariant();
+      result.forEach((row) => {
+        const conf = perVariantConf.get(row.variant);
+        if (!conf) {
+          Object.assign(row, {
+            precision: null,
+            recall: null,
+            f1: null,
+            f05: null,
+            f2: null,
+            mcc: null,
+            balanced_accuracy: null
+          });
+          return;
+        }
+        const { tp, fp, tn, fn } = conf;
+        const precision = tp + fp > 0 ? tp / (tp + fp) : null;
+        const recall = tp + fn > 0 ? tp / (tp + fn) : null;
+        const f1 = precision && recall && precision + recall > 0 ? 2 * precision * recall / (precision + recall) : null;
+        const beta05 = 0.5;
+        const f05 = precision && recall && beta05 * beta05 * precision + recall > 0 ? (1 + beta05 * beta05) * precision * recall / (beta05 * beta05 * precision + recall) : null;
+        const beta2 = 2;
+        const f2 = precision && recall && beta2 * beta2 * precision + recall > 0 ? (1 + beta2 * beta2) * precision * recall / (beta2 * beta2 * precision + recall) : null;
+        const tpr = tp + fn > 0 ? tp / (tp + fn) : null;
+        const tnr = tn + fp > 0 ? tn / (tn + fp) : null;
+        const balancedAccuracy = tpr !== null && tnr !== null ? (tpr + tnr) / 2 : null;
+        const mccDen = Math.sqrt((tp + fp) * (tp + fn) * (tn + fp) * (tn + fn));
+        const mcc = mccDen > 0 ? (tp * tn - fp * fn) / mccDen : null;
+        Object.assign(row, {
+          precision,
+          recall,
+          f1,
+          f05,
+          f2,
+          mcc,
+          balanced_accuracy: balancedAccuracy
+        });
+      });
+    }
+    return result;
+  }
+  /**
+   * Retrieve prompt performance data with optional CI and F-scores.
+   * Grouped by prompt_version with per-variant breakdowns.
+   */
+  getPromptPerformanceData(options = {}) {
+    const query = `
+      SELECT
+        variant,
+        prompt_version,
+        COUNT(*) as sample_size,
+        CAST(SUM(CASE WHEN verdict = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) as success_rate
+      FROM variant_executions
+      WHERE ${this.projectScopeWhere}
+        AND completed_at IS NOT NULL AND prompt_version IS NOT NULL
+        AND ${_TelemetryDashboard.REAL_DATA_FILTER}
+      GROUP BY variant, prompt_version
+      ORDER BY variant, prompt_version
+    `;
+    const rows = this.variantsDb.prepare(query).all(...this.projectScopeParams);
+    if (rows.length === 0) return [];
+    const confByVariantPrompt = options.includeFScore ? this.computeConfusionByVariantPrompt() : /* @__PURE__ */ new Map();
+    const byPrompt = /* @__PURE__ */ new Map();
+    rows.forEach((r) => {
+      const arr = byPrompt.get(r.prompt_version) || [];
+      const enriched = {
+        variant: r.variant,
+        prompt_version: r.prompt_version,
+        total_tasks: r.sample_size,
+        successes: Math.round(r.success_rate * r.sample_size),
+        success_rate: r.success_rate,
+        avg_completeness: null,
+        // Not available in this query
+        sample_size: r.sample_size
+      };
+      if (options.includeCI) {
+        const { lower, upper } = this.wilsonCI(r.success_rate, r.sample_size);
+        enriched.ci_lower = lower;
+        enriched.ci_upper = upper;
+      }
+      if (options.includeFScore) {
+        const key = `${r.variant}@@${r.prompt_version}`;
+        const conf = confByVariantPrompt.get(key);
+        if (conf) {
+          const { tp, fp, fn } = conf;
+          const precision = tp + fp > 0 ? tp / (tp + fp) : null;
+          const recall = tp + fn > 0 ? tp / (tp + fn) : null;
+          const f1 = precision && recall && precision + recall > 0 ? 2 * precision * recall / (precision + recall) : null;
+          const b05 = 0.5, b2 = 2;
+          const f05 = precision && recall && b05 * b05 * precision + recall > 0 ? (1 + b05 * b05) * precision * recall / (b05 * b05 * precision + recall) : null;
+          const f2 = precision && recall && b2 * b2 * precision + recall > 0 ? (1 + b2 * b2) * precision * recall / (b2 * b2 * precision + recall) : null;
+          Object.assign(enriched, { precision, recall, f1, f05, f2 });
+        } else {
+          Object.assign(enriched, {
+            precision: null,
+            recall: null,
+            f1: null,
+            f05: null,
+            f2: null
+          });
+        }
+      }
+      arr.push(enriched);
+      byPrompt.set(r.prompt_version, arr);
+    });
+    const result = [];
+    for (const [prompt, arr] of byPrompt.entries()) {
+      const avgSuccessRate = arr.reduce((s, v) => s + v.success_rate, 0) / arr.length;
+      const totalSamples = arr.reduce((s, v) => s + v.sample_size, 0);
+      const mean = avgSuccessRate;
+      const variance = arr.reduce((s, v) => s + (v.success_rate - mean) ** 2, 0) / arr.length;
+      const consistencyScore = Math.max(0, 1 - Math.sqrt(variance));
+      const shouldPrune = avgSuccessRate < 0.5 || totalSamples < 3 || consistencyScore < 0.3;
+      result.push({
+        prompt_version: prompt,
+        total_samples: totalSamples,
+        avg_success_rate: avgSuccessRate,
+        consistency_score: consistencyScore,
+        should_prune: shouldPrune,
+        variants: arr.map((v) => ({
+          variant: String(v.variant),
+          sample_size: v.sample_size,
+          success_rate: v.success_rate,
+          ci_lower: v.ci_lower,
+          ci_upper: v.ci_upper,
+          precision: v.precision,
+          recall: v.recall,
+          f1: v.f1,
+          f05: v.f05,
+          f2: v.f2
+        }))
+      });
+    }
+    return result.sort(
+      (a, b) => b.avg_success_rate * 0.7 + b.consistency_score * 0.3 - (a.avg_success_rate * 0.7 + a.consistency_score * 0.3)
+    );
+  }
+  /**
+   * Retrieve trend data with optional CI and validation fusion (warnings/errors).
+   */
+  getTrendsData(limit = 10, options = {}) {
+    const query = `
+      SELECT task_id, variant, verdict, completeness, started_at, total_duration_sec
+      FROM variant_executions
+      WHERE ${this.projectScopeWhere}
+        AND completed_at IS NOT NULL
+        AND ${_TelemetryDashboard.REAL_DATA_FILTER}
+      ORDER BY started_at DESC
+      LIMIT ?
+    `;
+    const rows = this.variantsDb.prepare(query).all(...this.projectScopeParams, limit * 3);
+    if (rows.length === 0) return [];
+    const byVariant = {};
+    rows.forEach((r) => {
+      if (!byVariant[r.variant]) {
+        byVariant[r.variant] = [];
+      }
+      const variantArray = byVariant[r.variant];
+      if (variantArray) {
+        variantArray.push(r);
+      }
+    });
+    const out = [];
+    for (const variant of Object.keys(byVariant)) {
+      const variantData = byVariant[variant];
+      if (!variantData) continue;
+      const tasks = variantData.slice(0, limit);
+      const successes = tasks.filter((t) => t.verdict === "success").length;
+      const successRate = tasks.length > 0 ? successes / tasks.length : 0;
+      const avgCompleteness = tasks.reduce((s, t) => s + (t.completeness || 0), 0) / (tasks.length || 1);
+      const recentWindow = Math.min(5, Math.floor(tasks.length / 2));
+      const olderWindow = Math.min(5, tasks.length - recentWindow);
+      const recentTasks = tasks.slice(0, recentWindow);
+      const olderTasks = tasks.slice(recentWindow, recentWindow + olderWindow);
+      const recentSuccess = recentTasks.length ? recentTasks.filter((t) => t.verdict === "success").length / recentTasks.length : 0;
+      const olderSuccess = olderTasks.length ? olderTasks.filter((t) => t.verdict === "success").length / olderTasks.length : recentSuccess;
+      const delta = (recentSuccess - olderSuccess) * 100;
+      const entry = {
+        variant,
+        tasks: tasks.length,
+        success_rate: successRate,
+        avg_completeness: avgCompleteness,
+        recent_success_rate: recentSuccess,
+        older_success_rate: olderSuccess,
+        delta_pp: delta,
+        trend: delta > 5 ? "improving" : delta < -5 ? "declining" : "stable"
+      };
+      if (options.includeCI) {
+        const { lower, upper } = this.wilsonCI(successRate, tasks.length);
+        entry.ci_lower = lower;
+        entry.ci_upper = upper;
+      }
+      if (options.includeValidationFusion) {
+        const taskIds = tasks.map((t) => t.task_id);
+        if (taskIds.length) {
+          const placeholders = taskIds.map(() => "?").join(",");
+          const validations = this.validationsDb.prepare(
+            `SELECT task_id, AVG(warnings_count) as avg_warn, AVG(errors_count) as avg_err
+             FROM validations WHERE ${this.projectScopeWhere}
+               AND task_id IN (${placeholders}) GROUP BY task_id`
+          ).all(...this.projectScopeParams, ...taskIds);
+          const avgWarn = validations.reduce((s, v) => s + (v.avg_warn || 0), 0) / (validations.length || 1);
+          const avgErr = validations.reduce((s, v) => s + (v.avg_err || 0), 0) / (validations.length || 1);
+          entry.avg_validation_warnings = avgWarn;
+          entry.avg_validation_errors = avgErr;
+          entry.brittle_success = successRate >= 0.8 && (avgErr > 0 || avgWarn >= 2);
+        }
+      }
+      out.push(entry);
+    }
+    return out;
+  }
+  /**
+   * Generate variant performance leaderboard
+   *
+   * Queries the variant_executions table to rank all variants by a weighted score
+   * combining success rate and completeness. Displays comprehensive performance
+   * metrics in a formatted table with insights.
+   *
+   * **SQL Query Details:**
+   * - **Table:** variant_executions
+   * - **Filters:** completed_at IS NOT NULL (excludes in-flight executions)
+   * - **Groups by:** variant
+   * - **Orders by:** Weighted score DESC
+   *
+   * **Scoring Formula:**
+   * ```
+   * score = (success_rate × 0.5) + (avg_completeness / 100 × 0.5)
+   * ```
+   *
+   * **Metrics Calculated:**
+   * - Total tasks executed
+   * - Success count and rate
+   * - Average completeness percentage
+   * - Average execution duration
+   * - First and last execution timestamps
+   *
+   * **Output Format:**
+   * - Table header with scoring explanation
+   * - Ranked rows: Rank | Variant | Score | Success Rate | Completeness | Duration | Tasks
+   * - Performance insights: Best performer and improvement opportunity
+   *
+   * @example
+   * ```typescript
+   * dashboard.leaderboard();
+   * // Output:
+   * //
+   * // Ranked by weighted score: (success_rate × 0.5) + (completeness × 0.5)
+   * //
+   * // Rank | Variant      | Score | Success Rate | Completeness | Duration | Tasks
+   * //
+   * //    1 | CLAUDE       |  87.3 |       85.0%  |       89.5%  |      45s |    20
+   * //    2 | CURSOR       |  82.1 |       80.0%  |       84.2%  |      38s |    15
+   * // ...
+   * ```
+   *
+   * @returns {void} Prints formatted leaderboard to console
+   */
+  leaderboard(options = {}) {
+    try {
+      const results = this.getLeaderboardData({
+        includeCI: true,
+        includeFScore: true,
+        taskId: options.taskId,
+        limit: options.limit
+      });
+      if (results.length === 0) {
+        console.log("No variant execution data available.");
+        console.log("   Run some tasks to generate telemetry data.");
+        return;
+      }
+      console.log("\nVariant Performance Leaderboard");
+      console.log("Ranked by weighted score: (success_rate \xD7 0.5) + (completeness \xD7 0.5)");
+      console.log("Rank | Variant      | Score | Success Rate | Completeness | Duration | Tasks");
+      const computeScore = (r) => r.avg_completeness != null ? r.success_rate * 0.5 + r.avg_completeness / 100 * 0.5 : r.success_rate;
+      results.slice().sort((a, b) => computeScore(a) < computeScore(b) ? 1 : -1).forEach((row, i) => {
+        const score = computeScore(row) * 100;
+        const successRate = (row.success_rate * 100).toFixed(1);
+        const completeness = row.avg_completeness != null ? row.avg_completeness.toFixed(1) : "N/A";
+        const duration = row.avg_duration_sec ? `${Math.round(row.avg_duration_sec)}s` : "N/A";
+        const variantPadded = row.variant.toUpperCase().padEnd(12);
+        const scorePadded = `${score.toFixed(1)}`.padStart(5);
+        const successPadded = `${successRate}%`.padStart(12);
+        const completenessPadded = `${completeness}%`.padStart(12);
+        const durationPadded = duration.padStart(8);
+        const tasksPadded = row.total_tasks.toString().padStart(5);
+        console.log(
+          `${(i + 1).toString().padStart(4)} | ${variantPadded} | ${scorePadded} | ${successPadded} | ${completenessPadded} | ${durationPadded} | ${tasksPadded}`
+        );
+        const ciLower = row.ci_lower !== void 0 ? (row.ci_lower * 100).toFixed(1) : null;
+        const ciUpper = row.ci_upper !== void 0 ? (row.ci_upper * 100).toFixed(1) : null;
+        if (ciLower !== null && ciUpper !== null) {
+          console.log(
+            `     CI95: [${ciLower}%, ${ciUpper}%]  ` + (row.f1 != null ? `F1: ${(row.f1 * 100).toFixed(1)}  F0.5: ${row.f05 != null ? (row.f05 * 100).toFixed(1) : "\u2014"}  F2: ${row.f2 != null ? (row.f2 * 100).toFixed(1) : "\u2014"}` : "")
+          );
+        }
+      });
+      const sorted = results.slice().sort((a, b) => computeScore(a) < computeScore(b) ? 1 : -1);
+      const best = sorted[0];
+      const worst = sorted[sorted.length - 1];
+      if (best && worst) {
+        console.log(
+          `
+Best Performer: ${best.variant.toUpperCase()} (${(computeScore(best) * 100).toFixed(1)}/100)`
+        );
+        console.log(
+          `Improvement Opportunity: ${worst.variant.toUpperCase()} (${(computeScore(worst) * 100).toFixed(1)}/100)`
+        );
+      }
+      if (sorted.length >= 2) {
+        const a = sorted[0];
+        const b = sorted[1];
+        if (!a || !b) return;
+        const { lower: aL, upper: aU } = this.wilsonCI(a.success_rate, a.total_tasks);
+        const { lower: bL, upper: bU } = this.wilsonCI(b.success_rate, b.total_tasks);
+        const overlap = !(aL > bU || bL > aU);
+        const p = this.twoProportionPValue(
+          a.successes,
+          a.total_tasks - a.successes,
+          b.successes,
+          b.total_tasks - b.successes
+        );
+        if (!overlap && p < 0.05) {
+          console.log(
+            "Significance: Statistically higher than runner-up (p<0.05). Likely truly better."
+          );
+        } else {
+          console.log("Significance: Likely indistinguishable at 95% CI. Collect more data.");
+        }
+      }
+    } catch (error) {
+      console.error("Error generating leaderboard:", error.message);
+      console.log("   Ensure telemetry database exists and contains data.");
+    }
+  }
+  /**
+   * Analyze prompt performance across variants
+   *
+   * Queries variant_executions grouped by prompt_version to identify:
+   * - Reliable prompts (high success rate, low variance)
+   * - Unreliable prompts (low success rate, high variance)
+   * - Prompts that should be pruned
+   *
+   * **SQL Query Details:**
+   * - **Table:** variant_executions
+   * - **Filters:** completed_at IS NOT NULL AND prompt_version IS NOT NULL
+   * - **Groups by:** variant, prompt_version
+   * - **Orders by:** variant, prompt_version
+   *
+   * **Analysis Methodology:**
+   * 1. **Success Rate:** Average success across all variants for this prompt
+   * 2. **Consistency Score:** 1 - sqrt(variance) where variance measures success rate spread
+   * 3. **Overall Score:** success_rate × 0.7 + consistency_score × 0.3
+   * 4. **Prune Recommendations:** Flags prompts with:
+   *    - Success rate < 50%
+   *    - Sample size < 3
+   *    - Consistency score < 0.3
+   *
+   * **Metrics Per Prompt:**
+   * - Overall success rate across all variants
+   * - Consistency score (0-100, higher = more consistent)
+   * - Total sample size (sum across variants)
+   * - Per-variant breakdown with success rates
+   * - Pruning recommendation if applicable
+   *
+   * **Status Indicators:**
+   * -  EXCELLENT: ≥80% success rate
+   * -  GOOD: ≥60% success rate
+   * - Fair: FAIR: ≥50% success rate
+   * -  PRUNE: <50% success rate or poor consistency
+   *
+   * @example
+   * ```typescript
+   * dashboard.promptPerformance();
+   * // Output:
+   * //  Prompt: v2.1.0  EXCELLENT
+   * //
+   * // Overall Success Rate: 85.0%
+   * // Consistency Score: 92.3%
+   * // Total Sample Size: 45
+   * // Variant Breakdown:
+   * //    claude       : 87.5% success (n=16)
+   * //    cursor       : 82.4% success (n=17)
+   * //    codex        : 75.0% success (n=12)
+   * // ...
+   * ```
+   *
+   * @returns {void} Prints formatted prompt analysis to console
+   */
+  promptPerformance() {
+    try {
+      const query = `
+        SELECT
+          variant,
+          prompt_version,
+          COUNT(*) as sample_size,
+          CAST(SUM(CASE WHEN verdict = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) as success_rate,
+          AVG(completeness) as avg_completeness,
+          MIN(started_at) as first_used,
+          MAX(started_at) as last_used
+        FROM variant_executions
+        WHERE ${this.projectScopeWhere}
+          AND completed_at IS NOT NULL AND prompt_version IS NOT NULL
+          AND ${_TelemetryDashboard.REAL_DATA_FILTER}
+        GROUP BY variant, prompt_version
+        ORDER BY variant, prompt_version
+      `;
+      const results = this.variantsDb.prepare(query).all(...this.projectScopeParams);
+      if (results.length === 0) {
+        console.log("No prompt performance data available.");
+        console.log("   Run tasks with different prompt versions to generate data.");
+        return;
+      }
+      console.log("\nPrompt Performance Analysis");
+      const byPrompt = {};
+      results.forEach((row) => {
+        if (!byPrompt[row.prompt_version]) {
+          byPrompt[row.prompt_version] = [];
+        }
+        const promptArray = byPrompt[row.prompt_version];
+        if (promptArray) {
+          promptArray.push(row);
+        }
+      });
+      const promptAnalysis = Object.keys(byPrompt).map((promptVersion) => {
+        const variants = byPrompt[promptVersion];
+        if (!variants) return null;
+        const avgSuccessRate = variants.reduce((sum, v) => sum + v.success_rate, 0) / variants.length;
+        const totalSamples = variants.reduce(
+          (sum, v) => sum + v.sample_size,
+          0
+        );
+        const successRates = variants.map((v) => v.success_rate);
+        const mean = avgSuccessRate;
+        const variance = successRates.reduce((sum, rate) => sum + (rate - mean) ** 2, 0) / successRates.length;
+        const consistencyScore = Math.max(0, 1 - Math.sqrt(variance));
+        const shouldPrune = avgSuccessRate < 0.5 || totalSamples < 3 || consistencyScore < 0.3;
+        return {
+          promptVersion,
+          variants,
+          avgSuccessRate,
+          totalSamples,
+          consistencyScore,
+          shouldPrune
+        };
+      }).filter((a) => a !== null);
+      promptAnalysis.sort((a, b) => {
+        const scoreA = a.avgSuccessRate * 0.7 + a.consistencyScore * 0.3;
+        const scoreB = b.avgSuccessRate * 0.7 + b.consistencyScore * 0.3;
+        return scoreB - scoreA;
+      });
+      promptAnalysis.forEach((analysis) => {
+        const {
+          promptVersion,
+          variants,
+          avgSuccessRate,
+          totalSamples,
+          consistencyScore,
+          shouldPrune
+        } = analysis;
+        const status = shouldPrune ? "PRUNE" : avgSuccessRate >= 0.8 ? "EXCELLENT" : avgSuccessRate >= 0.6 ? "GOOD" : "FAIR";
+        console.log(`
+Prompt: ${promptVersion} ${status}`);
+        console.log(`Overall Success Rate: ${(avgSuccessRate * 100).toFixed(1)}%`);
+        console.log(`Consistency Score: ${(consistencyScore * 100).toFixed(1)}%`);
+        console.log(`Total Sample Size: ${totalSamples}`);
+        console.log("Variant Breakdown:");
+        if (variants) {
+          variants.forEach((v) => {
+            const performance = v.success_rate >= 0.8 ? "EXCELLENT" : v.success_rate >= 0.6 ? "GOOD" : "PRUNE";
+            console.log(
+              `  ${performance} ${String(v.variant).padEnd(12)}: ${(v.success_rate * 100).toFixed(1)}% success (n=${v.sample_size})`
+            );
+          });
+        }
+        if (shouldPrune) {
+          console.log("\nRECOMMENDATION: Consider pruning this prompt version");
+        }
+      });
+    } catch (error) {
+      console.error("Error analyzing prompt performance:", error.message);
+      console.log("   Ensure telemetry database exists and contains data.");
+    }
+  }
+  /**
+   * Show historical performance trends over time
+   *
+   * Queries recent variant executions to analyze performance trends by comparing
+   * recent vs. older task outcomes. Useful for identifying improving or declining
+   * variant performance over time.
+   *
+   * **SQL Query Details:**
+   * - **Table:** variant_executions
+   * - **Filters:** completed_at IS NOT NULL
+   * - **Orders by:** started_at DESC (most recent first)
+   * - **Limit:** limit × 3 (allows showing limit tasks per variant)
+   *
+   * **Trend Analysis Methodology:**
+   * 1. Splits tasks into two windows per variant:
+   *    - **Recent window:** Last N/2 tasks (up to 5 tasks)
+   *    - **Older window:** Previous N/2 tasks (up to 5 tasks)
+   * 2. Compares success rates between windows
+   * 3. Classifies trend as:
+   *    -  **Improving:** Recent success rate >10% higher
+   *    -  **Stable:** Within ±10% change
+   *    -  **Declining:** Recent success rate >10% lower
+   *
+   * **Metrics Per Variant:**
+   * - Overall success rate (all tasks in window)
+   * - Average completeness percentage
+   * - Recent window success rate
+   * - Older window success rate
+   * - Percentage point change with trend indicator
+   *
+   * @param limit - Maximum number of tasks to show per variant (default: 10)
+   *
+   * @example
+   * ```typescript
+   * dashboard.trends(15);
+   * // Output:
+   * // CLAUDE
+   * //
+   * // Overall Performance (15 tasks):
+   * //   Success Rate: 86.7% (13/15)
+   * //   Avg Completeness: 88.3%
+   * //
+   * // Trend Analysis (improving):
+   * //   Recent Success: 90.0% (last 5 tasks)
+   * //   Previous Success: 75.0% (previous 5 tasks)
+   * //   Change: +15.0 percentage points
+   * // ...
+   * ```
+   *
+   * @returns {void} Prints formatted trend analysis to console
+   */
+  trends(limit = 10) {
+    try {
+      const query = `
+        SELECT
+          task_id,
+          variant,
+          verdict,
+          completeness,
+          started_at,
+          total_duration_sec
+        FROM variant_executions
+        WHERE ${this.projectScopeWhere}
+          AND completed_at IS NOT NULL
+          AND ${_TelemetryDashboard.REAL_DATA_FILTER}
+        ORDER BY started_at DESC
+        LIMIT ?
+      `;
+      const results = this.variantsDb.prepare(query).all(...this.projectScopeParams, limit * 3);
+      if (results.length === 0) {
+        console.log("No historical trend data available.");
+        console.log("   Run some tasks to generate trend data.");
+        return;
+      }
+      console.log(`
+Historical Trends (last ${limit} tasks per variant)`);
+      const byVariant = {};
+      results.forEach((row) => {
+        if (!byVariant[row.variant]) {
+          byVariant[row.variant] = [];
+        }
+        const variantArray = byVariant[row.variant];
+        if (variantArray) {
+          variantArray.push(row);
+        }
+      });
+      Object.keys(byVariant).forEach((variant) => {
+        const variantData = byVariant[variant];
+        if (!variantData) return;
+        const tasks = variantData.slice(0, limit);
+        if (tasks.length === 0) {
+          return;
+        }
+        const successes = tasks.filter((t) => t.verdict === "success").length;
+        const avgCompleteness = tasks.reduce((sum, t) => sum + (t.completeness || 0), 0) / tasks.length;
+        const recentWindow = Math.min(5, Math.floor(tasks.length / 2));
+        const olderWindow = Math.min(5, tasks.length - recentWindow);
+        const recentTasks = tasks.slice(0, recentWindow);
+        const olderTasks = tasks.slice(recentWindow, recentWindow + olderWindow);
+        const recentSuccessRate = recentTasks.length > 0 ? recentTasks.filter((t) => t.verdict === "success").length / recentTasks.length : 0;
+        const olderSuccessRate = olderTasks.length > 0 ? olderTasks.filter((t) => t.verdict === "success").length / olderTasks.length : recentSuccessRate;
+        const successTrend = recentSuccessRate - olderSuccessRate;
+        const trendIcon = Math.abs(successTrend) < 0.1 ? "stable" : successTrend > 0 ? "improving" : "declining";
+        const trendText = Math.abs(successTrend) < 0.1 ? "stable" : successTrend > 0 ? "improving" : "declining";
+        console.log(`
+${variant.toUpperCase()} ${trendIcon}`);
+        console.log(`Overall Performance (${tasks.length} tasks):`);
+        console.log(
+          `  Success Rate: ${(successes / tasks.length * 100).toFixed(1)}% (${successes}/${tasks.length})`
+        );
+        console.log(`  Avg Completeness: ${avgCompleteness.toFixed(1)}%`);
+        console.log(`
+Trend Analysis (${trendText}):`);
+        console.log(
+          `  Recent Success: ${(recentSuccessRate * 100).toFixed(1)}% (last ${recentWindow} tasks)`
+        );
+        console.log(
+          `  Previous Success: ${(olderSuccessRate * 100).toFixed(1)}% (previous ${olderWindow} tasks)`
+        );
+        console.log(
+          `  Change: ${successTrend > 0 ? "+" : ""}${(successTrend * 100).toFixed(1)} percentage points`
+        );
+      });
+    } catch (error) {
+      console.error("Error analyzing trends:", error.message);
+      console.log("   Ensure telemetry database exists and contains data.");
+    }
+  }
+  /**
+   * Generate context-aware variant recommendations
+   *
+   * Queries variant_executions with optional context filters to recommend the best
+   * variant for specific project characteristics (language, framework, etc.). Uses
+   * a weighted scoring system with context matching bonuses and statistical confidence.
+   *
+   * **SQL Query Details:**
+   * - **Table:** variant_executions
+   * - **Filters:**
+   *   - completed_at IS NOT NULL (required)
+   *   - project_language = ? OR project_language IS NULL (if language specified)
+   *   - project_framework = ? OR project_framework IS NULL (if framework specified)
+   * - **Groups by:** variant
+   * - **Orders by:** success_rate DESC, avg_completeness DESC
+   *
+   * **Scoring Methodology:**
+   * 1. **Base Score:** success_rate × 0.6 + avg_completeness × 0.4
+   * 2. **Context Bonuses:**
+   *    - Language match: +10% bonus
+   *    - Framework match: +10% bonus
+   * 3. **Final Score:** min(1.0, base_score + bonuses)
+   * 4. **Confidence:** Calculated via Wilson score interval based on sample size
+   *
+   * **Confidence Levels (Wilson Score):**
+   * - **HIGH:** Sample size ≥10 with tight confidence interval (<0.2)
+   * - **MEDIUM:** Sample size 3-9 or moderate interval (0.2-0.4)
+   * - **LOW:** Sample size <3 or wide interval (>0.4)
+   *
+   * **Performance Tiers:**
+   * - EXCELLENT: Score ≥80%
+   * -  GOOD: Score ≥60%
+   * -  FAIR: Score ≥40%
+   * -  POOR: Score <40%
+   *
+   * @param context - Context filters for recommendations
+   *
+   * @example
+   * ```typescript
+   * // Get recommendations for TypeScript React projects
+   * dashboard.recommend({
+   *   language: 'typescript',
+   *   framework: 'react'
+   * });
+   * // Output:
+   * //  Variant Recommendations
+   * //
+   * // Context: typescript / react / any complexity / any type
+   * //
+   * //
+   * // 1. CLAUDE EXCELLENT
+   * //
+   * // Overall Score: 92.5/100
+   * // Success Rate: 88.0% (25 tasks)
+   * // Completeness: 90.2%
+   * // Avg Duration: 42s
+   * // Confidence: HIGH (High confidence)
+   * // Context Match: +20% bonus for matching context
+   * // ...
+   * ```
+   *
+   * @returns {void} Prints formatted recommendations to console
+   */
+  recommend(context = {}) {
+    try {
+      const { language, framework, taskComplexity, taskType } = context;
+      console.log("\nVariant Recommendations");
+      console.log(
+        `Context: ${language || "any"} / ${framework || "any"} / ${taskComplexity || "any"} complexity / ${taskType || "any"} type`
+      );
+      let query = `
+        SELECT
+          variant,
+          COUNT(*) as total_tasks,
+          CAST(SUM(CASE WHEN verdict = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) as success_rate,
+          AVG(completeness) as avg_completeness,
+          AVG(total_duration_sec) as avg_duration_sec,
+          MAX(project_language) as project_language,
+          MAX(project_framework) as project_framework
+        FROM variant_executions
+        WHERE ${this.projectScopeWhere}
+          AND completed_at IS NOT NULL
+          AND ${_TelemetryDashboard.REAL_DATA_FILTER}
+      `;
+      const params = [...this.projectScopeParams];
+      if (language && language !== "any") {
+        query += " AND (project_language = ? OR project_language IS NULL)";
+        params.push(language);
+      }
+      if (framework && framework !== "any") {
+        query += " AND (project_framework = ? OR project_framework IS NULL)";
+        params.push(framework);
+      }
+      query += " GROUP BY variant ORDER BY success_rate DESC, avg_completeness DESC";
+      const results = this.variantsDb.prepare(query).all(...params);
+      if (results.length === 0) {
+        console.log("No data available for the specified context.");
+        console.log("   Try with broader context filters or run more tasks.");
+        return;
+      }
+      const recommendations = results.map((row, i) => {
+        const baseScore = row.avg_completeness != null ? row.success_rate * 0.6 + row.avg_completeness / 100 * 0.4 : row.success_rate;
+        let contextBonus = 0;
+        if (language && language !== "any" && row.project_language === language) {
+          contextBonus += 0.1;
+        }
+        if (framework && framework !== "any" && row.project_framework === framework) {
+          contextBonus += 0.1;
+        }
+        const finalScore = Math.min(1, baseScore + contextBonus);
+        const confidence = this.calculateConfidence(row.total_tasks, row.success_rate);
+        const tier = finalScore >= 0.8 ? "EXCELLENT" : finalScore >= 0.6 ? "GOOD" : finalScore >= 0.4 ? "FAIR" : "POOR";
+        return {
+          ...row,
+          rank: i + 1,
+          finalScore,
+          contextBonus,
+          confidence,
+          tier
+        };
+      });
+      recommendations.forEach((rec) => {
+        console.log(`
+${rec.rank}. ${rec.variant.toUpperCase()} ${rec.tier}`);
+        console.log(`Overall Score: ${(rec.finalScore * 100).toFixed(1)}/100`);
+        console.log(
+          `Success Rate: ${(rec.success_rate * 100).toFixed(1)}% (${rec.total_tasks} tasks)`
+        );
+        console.log(`Completeness: ${rec.avg_completeness.toFixed(1)}%`);
+        console.log(
+          `Avg Duration: ${rec.avg_duration_sec ? `${Math.round(rec.avg_duration_sec)}s` : "N/A"}`
+        );
+        console.log(`Confidence: ${rec.confidence.level} (${rec.confidence.description})`);
+        if (rec.contextBonus > 0) {
+          console.log(
+            `Context Match: +${(rec.contextBonus * 100).toFixed(0)}% bonus for matching context`
+          );
+        }
+      });
+      const best = recommendations[0];
+      if (best) {
+        console.log("\nSummary");
+        console.log(`Recommended: ${best.variant.toUpperCase()}`);
+        console.log(
+          `   Best overall performance with ${(best.finalScore * 100).toFixed(1)}/100 score`
+        );
+        console.log(
+          `   ${(best.success_rate * 100).toFixed(1)}% success rate across ${best.total_tasks} tasks`
+        );
+      }
+    } catch (error) {
+      console.error("Error generating recommendations:", error.message);
+      console.log("   Ensure telemetry database exists and contains data.");
+    }
+  }
+  /**
+   * Calculate statistical confidence level for variant recommendations
+   *
+   * Uses the Wilson score interval method (at 95% confidence) to determine how
+   * reliable a variant's performance metrics are based on sample size and success
+   * rate. Larger sample sizes and tighter confidence intervals produce higher
+   * confidence levels.
+   *
+   * **Methodology:**
+   * 1. **Quick Checks (Sample Size):**
+   *    - <3 samples → LOW (very few samples)
+   *    - 3-4 samples → MEDIUM (limited samples)
+   *    - 5-9 samples → MEDIUM (moderate samples)
+   * 2. **Statistical Analysis (≥10 samples):**
+   *    - Calculate Wilson score interval at 95% confidence (z=1.96)
+   *    - Measure interval width (upperBound - lowerBound)
+   *    - Classify by interval width:
+   *      - <0.2 → HIGH confidence
+   *      - 0.2-0.4 → MEDIUM confidence
+   *      - >0.4 → LOW confidence
+   *
+   * **Wilson Score Interval Formula:**
+   * ```
+   * center = (p + z²/2n) / (1 + z²/n)
+   * margin = (z / (1 + z²/n)) × √(p(1-p)/n + z²/4n²)
+   * interval = [max(0, center - margin), min(1, center + margin)]
+   * ```
+   * Where:
+   * - p = success rate (proportion)
+   * - n = sample size
+   * - z = 1.96 (95% confidence level)
+   *
+   * @param sampleSize - Number of completed tasks for this variant
+   * @param successRate - Success rate as decimal (0.0 to 1.0)
+   *
+   * @returns {ConfidenceLevel} Object with level ('LOW' | 'MEDIUM' | 'HIGH') and description
+   *
+   * @example
+   * ```typescript
+   * // Very few samples
+   * calculateConfidence(2, 1.0);
+   * // Returns: { level: 'LOW', description: 'Very few samples' }
+   *
+   * // Limited samples
+   * calculateConfidence(4, 0.75);
+   * // Returns: { level: 'MEDIUM', description: 'Limited samples' }
+   *
+   * // High confidence with many successful samples
+   * calculateConfidence(100, 0.90);
+   * // Returns: { level: 'HIGH', description: 'High confidence' }
+   *
+   * // Low confidence despite many samples (high variance)
+   * calculateConfidence(50, 0.50);
+   * // Returns: { level: 'LOW', description: 'Low confidence' } (wide interval)
+   * ```
+   *
+   * @remarks
+   * The Wilson score interval is preferred over simple binomial confidence intervals
+   * because it performs better with small sample sizes and extreme success rates
+   * (near 0% or 100%). It provides more conservative estimates than the normal
+   * approximation method.
+   *
+   * @see {@link https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval}
+   * @private
+   */
+  calculateConfidence(sampleSize, successRate) {
+    if (sampleSize < 3) {
+      return { level: "LOW", description: "Very few samples" };
+    }
+    if (sampleSize < 5) {
+      return { level: "MEDIUM", description: "Limited samples" };
+    }
+    if (sampleSize < 10) {
+      return { level: "MEDIUM", description: "Moderate samples" };
+    }
+    const { width: interval } = this.wilsonCI(successRate, sampleSize);
+    if (interval < 0.2) {
+      return { level: "HIGH", description: "High confidence" };
+    } else if (interval < 0.4) {
+      return { level: "MEDIUM", description: "Moderate confidence" };
+    } else {
+      return { level: "LOW", description: "Low confidence" };
+    }
+  }
+  /** Compute Wilson 95% CI for success rate */
+  wilsonCI(p, n) {
+    if (!n || n <= 0) return { lower: 0, upper: 1, width: 1 };
+    const z = 1.96;
+    const denom = 1 + z * z / n;
+    const center = (p + z * z / (2 * n)) / denom;
+    const margin = z / denom * Math.sqrt(p * (1 - p) / n + z * z / (4 * n * n));
+    const lower = Math.max(0, center - margin);
+    const upper = Math.min(1, center + margin);
+    return { lower, upper, width: upper - lower };
+  }
+  /** Two-proportion z-test p-value (two-tailed). Inputs: successes/failures for A and B */
+  twoProportionPValue(aSucc, aFail, bSucc, bFail) {
+    const n1 = aSucc + aFail;
+    const n2 = bSucc + bFail;
+    if (n1 === 0 || n2 === 0) return 1;
+    const p1 = aSucc / n1;
+    const p2 = bSucc / n2;
+    const pPool = (aSucc + bSucc) / (n1 + n2);
+    const se = Math.sqrt(pPool * (1 - pPool) * (1 / n1 + 1 / n2));
+    if (se === 0) return 1;
+    const z = Math.abs((p1 - p2) / se);
+    const p = 2 * (1 - this.normalCdf(z));
+    return Math.max(0, Math.min(1, p));
+  }
+  /** Standard normal CDF approximation */
+  normalCdf(z) {
+    const t = 1 / (1 + 0.2316419 * z);
+    const d = Math.exp(-0.5 * z * z) / Math.sqrt(2 * Math.PI);
+    const poly = (((1.330274429 * t - 1.821255978) * t + 1.781477937) * t - 0.356563782) * t + 0.31938153;
+    const approx = 1 - d * poly;
+    return z >= 0 ? approx : 1 - approx;
+  }
+  /**
+   * Compute confusion-matrix aggregates by variant, using validations as predictor
+   * (predicted success = all validations for a task passed; conservative heuristic).
+   */
+  computeConfusionByVariant() {
+    const validations = this.validationsDb.prepare(
+      `SELECT task_id, MIN(passed) as all_passed, COUNT(*) as cnt
+         FROM validations WHERE ${this.projectScopeWhere} GROUP BY task_id`
+    ).all(...this.projectScopeParams);
+    const predMap = /* @__PURE__ */ new Map();
+    validations.forEach((v) => {
+      if (v.cnt > 0) predMap.set(v.task_id, v.all_passed);
+    });
+    const execRows = this.variantsDb.prepare(
+      `SELECT task_id, variant, CASE WHEN verdict = 'success' THEN 1 ELSE 0 END as actual_success
+       FROM variant_executions WHERE ${this.projectScopeWhere}
+         AND completed_at IS NOT NULL AND ${_TelemetryDashboard.REAL_DATA_FILTER}`
+    ).all(...this.projectScopeParams);
+    const confByVariant = /* @__PURE__ */ new Map();
+    for (const r of execRows) {
+      const pred = predMap.get(r.task_id);
+      if (pred === void 0) continue;
+      const key = r.variant;
+      let agg = confByVariant.get(key);
+      if (!agg) {
+        agg = { tp: 0, fp: 0, tn: 0, fn: 0 };
+        confByVariant.set(key, agg);
+      }
+      if (pred === 1 && r.actual_success === 1) agg.tp++;
+      else if (pred === 1 && r.actual_success === 0) agg.fp++;
+      else if (pred === 0 && r.actual_success === 0) agg.tn++;
+      else if (pred === 0 && r.actual_success === 1) agg.fn++;
+    }
+    return confByVariant;
+  }
+  /** Confusion by variant+prompt_version for prompt analytics */
+  computeConfusionByVariantPrompt() {
+    const validations = this.validationsDb.prepare(
+      `SELECT task_id, MIN(passed) as all_passed, COUNT(*) as cnt
+         FROM validations WHERE ${this.projectScopeWhere} GROUP BY task_id`
+    ).all(...this.projectScopeParams);
+    const predMap = /* @__PURE__ */ new Map();
+    validations.forEach((v) => {
+      if (v.cnt > 0) predMap.set(v.task_id, v.all_passed);
+    });
+    const execRows = this.variantsDb.prepare(
+      `SELECT task_id, variant, prompt_version, CASE WHEN verdict = 'success' THEN 1 ELSE 0 END as actual_success
+       FROM variant_executions WHERE ${this.projectScopeWhere}
+         AND completed_at IS NOT NULL AND prompt_version IS NOT NULL
+         AND ${_TelemetryDashboard.REAL_DATA_FILTER}`
+    ).all(...this.projectScopeParams);
+    const map = /* @__PURE__ */ new Map();
+    for (const r of execRows) {
+      const pred = predMap.has(r.task_id) ? predMap.get(r.task_id) : null;
+      if (pred === null) continue;
+      const key = `${r.variant}@@${r.prompt_version}`;
+      if (!map.has(key)) map.set(key, { tp: 0, fp: 0, tn: 0, fn: 0 });
+      const agg = map.get(key);
+      if (pred === 1 && r.actual_success === 1) agg.tp++;
+      else if (pred === 1 && r.actual_success === 0) agg.fp++;
+      else if (pred === 0 && r.actual_success === 0) agg.tn++;
+      else if (pred === 0 && r.actual_success === 1) agg.fn++;
+    }
+    return map;
+  }
+  /**
+   * Start telemetry dashboard
+   *
+   * Initializes the dashboard system and prepares it for metric collection
+   * and real-time updates. This method must be called before using other
+   * dashboard functionality.
+   *
+   * @returns {void}
+   *
+   * @example
+   * ```typescript
+   * const dashboard = new TelemetryDashboard();
+   * dashboard.start();
+   * // Now the dashboard is ready to collect metrics
+   * ```
+   */
+  start() {
+    if (!this.enabled) {
+      console.warn("TelemetryDashboard is disabled - using in-memory fallback");
+      return;
+    }
+    console.log("Starting TelemetryDashboard...");
+    try {
+      this.variantsDb.prepare("SELECT 1").get();
+      this.validationsDb.prepare("SELECT 1").get();
+      console.log("TelemetryDashboard started successfully");
+    } catch (error) {
+      console.error("Failed to start TelemetryDashboard:", error);
+      throw new Error("TelemetryDashboard database connections are not available");
+    }
+  }
+  /**
+   * Add a new metric to dashboard for tracking
+   *
+   * Registers a metric with the dashboard system, enabling real-time
+   * tracking and visualization of the specified metric.
+   *
+   * @param name - Unique identifier for the metric
+   * @param config - Metric configuration including type, labels, and description
+   * @returns {void}
+   *
+   * @example
+   * ```typescript
+   * dashboard.addMetric('task_completion', {
+   *   name: 'Task Completion Rate',
+   *   description: 'Real-time task completion percentage',
+   *   type: 'gauge',
+   *   labels: ['task_type', 'provider']
+   * });
+   * ```
+   */
+  addMetric(name, config) {
+    if (!this.enabled) {
+      console.warn(`Dashboard disabled - skipping metric registration: ${name}`);
+      return;
+    }
+    try {
+      const createTableQuery = `
+        CREATE TABLE IF NOT EXISTS metric_registry (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          name TEXT UNIQUE NOT NULL,
+          display_name TEXT NOT NULL,
+          description TEXT NOT NULL,
+          type TEXT NOT NULL,
+          labels TEXT,
+          created_at TEXT DEFAULT CURRENT_TIMESTAMP
+        )
+      `;
+      this.variantsDb.prepare(createTableQuery).run();
+      const insertQuery = `
+        INSERT OR REPLACE INTO metric_registry (name, display_name, description, type, labels)
+        VALUES (?, ?, ?, ?, ?)
+      `;
+      this.variantsDb.prepare(insertQuery).run(
+        name,
+        config.name,
+        config.description,
+        config.type,
+        JSON.stringify(config.labels || [])
+      );
+      console.log(`Registered metric: ${name} (${config.type})`);
+    } catch (error) {
+      console.error(`Failed to register metric ${name}:`, error);
+    }
+  }
+  /**
+   * Update a metric with a new value
+   *
+   * Updates the specified metric with a new value, storing it for
+   * real-time tracking and historical analysis.
+   *
+   * @param name - Name of the metric to update
+   * @param value - New value for the metric
+   * @param labels - Optional label values for metric segmentation
+   * @returns {void}
+   *
+   * @example
+   * ```typescript
+   * dashboard.updateMetric('task_completion', 85.5, {
+   *   task_type: 'feature',
+   *   provider: 'claude'
+   * });
+   * ```
+   */
+  updateMetric(name, value, labels) {
+    if (!this.enabled) {
+      console.warn(`Dashboard disabled - skipping metric update: ${name} = ${value}`);
+      return;
+    }
+    try {
+      const createTableQuery = `
+        CREATE TABLE IF NOT EXISTS metric_values (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          metric_name TEXT NOT NULL,
+          value REAL NOT NULL,
+          labels TEXT,
+          timestamp TEXT DEFAULT CURRENT_TIMESTAMP,
+          FOREIGN KEY (metric_name) REFERENCES metric_registry(name)
+        )
+      `;
+      this.variantsDb.prepare(createTableQuery).run();
+      const insertQuery = `
+        INSERT INTO metric_values (metric_name, value, labels)
+        VALUES (?, ?, ?)
+      `;
+      this.variantsDb.prepare(insertQuery).run(name, value, JSON.stringify(labels || {}));
+      const cleanupQuery = `
+        DELETE FROM metric_values
+        WHERE metric_name = ? AND id NOT IN (
+          SELECT id FROM metric_values
+          WHERE metric_name = ?
+          ORDER BY timestamp DESC
+          LIMIT 1000
+        )
+      `;
+      this.variantsDb.prepare(cleanupQuery).run(name, name);
+    } catch (error) {
+      console.error(`Failed to update metric ${name}:`, error);
+    }
+  }
+  /**
+   * Close all database connections
+   *
+   * Cleanly closes the SQLite database connections for both variants and validations
+   * databases. Should be called when the dashboard is no longer needed to free resources.
+   *
+   * @returns {void}
+   *
+   * @example
+   * ```typescript
+   * const dashboard = new TelemetryDashboard();
+   * try {
+   *   dashboard.leaderboard();
+   *   dashboard.recommend({ language: 'typescript' });
+   * } finally {
+   *   // Always close connections
+   *   dashboard.close();
+   * }
+   * ```
+   *
+   * @remarks
+   * This method is idempotent - calling it multiple times is safe and will not
+   * throw errors. However, attempting to use dashboard methods after closing will
+   * result in database errors.
+   */
+  close() {
+    this.variantsDb.close();
+    this.validationsDb.close();
+  }
+};
+
+// src/telemetry/event-types.ts
+function isCoreVariantEvent(event) {
+  return ["started", "first_commit", "completed", "failed", "evaluated"].includes(event);
+}
+function validateEventType(event) {
+  if (isCoreVariantEvent(event)) {
+    return event;
+  }
+  throw new Error(`Unrecognized telemetry event type: ${event}`);
+}
+
+// src/telemetry/insights.ts
+import fs2 from "fs";
+import path2 from "path";
+import Database2 from "better-sqlite3";
+var TelemetryInsightEngine = class _TelemetryInsightEngine {
+  static REAL_DATA_FILTER = "verdict IS NOT NULL AND verdict != '' AND task_id NOT LIKE 'test-%' AND task_id NOT LIKE 'task-%'";
+  poeticDir;
+  telemetryDir;
+  variantsDb;
+  enabled = true;
+  enableRealTime;
+  calculationInterval;
+  intervalId;
+  /**
+   * Initialize the TelemetryInsightEngine with configuration options.
+   *
+   * @param options - Configuration options for the insight engine
+   */
+  constructor(options = {}) {
+    this.poeticDir = options.poeticDir || path2.join(process.cwd(), ".poetic");
+    this.telemetryDir = LabPathResolver.getInstance().getTelemetryDir(this.poeticDir);
+    this.enableRealTime = options.enableRealTime ?? false;
+    this.calculationInterval = options.calculationInterval ?? 3e5;
+    const dbDir = path2.join(this.telemetryDir, "db");
+    try {
+      let parentDir = path2.dirname(dbDir);
+      while (!fs2.existsSync(parentDir) && parentDir !== path2.dirname(parentDir)) {
+        parentDir = path2.dirname(parentDir);
+      }
+      if (!fs2.existsSync(parentDir) || parentDir === path2.sep) {
+        throw new Error(`Telemetry base directory cannot be created at: ${dbDir}`);
+      }
+      const parentStats = fs2.statSync(parentDir);
+      if ((parentStats.mode & 146) === 0) {
+        throw new Error(`Telemetry parent directory is not writable: ${parentDir}`);
+      }
+      if (!fs2.existsSync(dbDir)) {
+        fs2.mkdirSync(dbDir, { recursive: true });
+      }
+      const stats = fs2.statSync(dbDir);
+      const writable = (stats.mode & 146) !== 0;
+      if (!writable) {
+        throw new Error(`Telemetry DB directory is not writable: ${dbDir}`);
+      }
+      this.variantsDb = new Database2(path2.join(dbDir, "variants.db"));
+      this.variantsDb.pragma("journal_mode = WAL");
+      this.variantsDb.pragma(`busy_timeout = ${getSqliteBusyTimeoutMs()}`);
+      this.bootstrapSchema();
+      this.enabled = true;
+    } catch (err) {
+      import("./warning-EGQGUUIO.js").then(({ emitTelemetryFallbackWarning: emitTelemetryFallbackWarning2 }) => {
+        emitTelemetryFallbackWarning2(
+          "could not initialize DB directory, using in-memory fallback",
+          err
+        );
+      }).catch(() => {
+      });
+      this.enabled = false;
+      this.variantsDb = new Database2(":memory:");
+      this.bootstrapSchema();
+    }
+    if (this.enableRealTime) {
+      this.startRealTimeMonitoring();
+    }
+  }
+  bootstrapSchema() {
+    const statements = [
+      `CREATE TABLE IF NOT EXISTS variant_executions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        task_id TEXT,
+        variant TEXT,
+        prompt_version TEXT,
+        completeness REAL,
+        verdict TEXT,
+        total_duration_sec REAL,
+        started_at TEXT,
+        completed_at TEXT,
+        project_language TEXT,
+        project_framework TEXT,
+        provider TEXT,
+        model TEXT,
+        task_complexity TEXT,
+        success_reason TEXT,
+        failure_reason TEXT,
+        code_quality_score REAL,
+        testing_score REAL,
+        documentation_score REAL,
+        architecture_score REAL,
+        anomaly_score REAL
+      )`,
+      "CREATE INDEX IF NOT EXISTS idx_variant_executions_variant ON variant_executions(variant)",
+      "CREATE INDEX IF NOT EXISTS idx_variant_executions_prompt_version ON variant_executions(prompt_version)",
+      "CREATE INDEX IF NOT EXISTS idx_variant_executions_completed_at ON variant_executions(completed_at)",
+      "CREATE INDEX IF NOT EXISTS idx_variant_executions_project_language ON variant_executions(project_language)",
+      "CREATE INDEX IF NOT EXISTS idx_variant_executions_task_id ON variant_executions(task_id)"
+    ];
+    for (const stmt of statements) {
+      try {
+        this.variantsDb.prepare(stmt).run();
+      } catch (error) {
+        emitTelemetryFallbackWarning("Schema bootstrap statement failed", error);
+      }
+    }
+  }
+  /** Returns true if the insight engine successfully initialized on-disk storage */
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Generate comprehensive insights from telemetry data.
+   *
+   * Analyzes all available telemetry data to produce actionable insights
+   * across multiple dimensions: performance, optimization, prediction, and anomaly detection.
+   *
+   * @returns Array of insight results with recommendations
+   */
+  async generateInsights() {
+    const insights = [];
+    try {
+      insights.push(...this.analyzePerformanceTrends());
+      insights.push(...this.generateOptimizationRecommendations());
+      insights.push(...this.generatePredictiveInsights());
+      insights.push(...this.detectAnomalies());
+      insights.sort((a, b) => {
+        const severityWeight = { critical: 3, warning: 2, info: 1 };
+        const aSeverity = severityWeight[a.severity];
+        const bSeverity = severityWeight[b.severity];
+        if (aSeverity !== bSeverity) {
+          return bSeverity - aSeverity;
+        }
+        return b.confidence - a.confidence;
+      });
+      return insights;
+    } catch (error) {
+      emitTelemetryFallbackWarning("Failed to generate insights", error);
+      return [];
+    }
+  }
+  /**
+   * Analyze performance trends across variants and providers.
+   */
+  analyzePerformanceTrends() {
+    const insights = [];
+    const query = `
+      SELECT
+        variant,
+        prompt_version,
+        COUNT(*) as total_tasks,
+        AVG(completeness) as avg_completeness,
+        CAST(SUM(CASE WHEN verdict = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) as success_rate,
+        AVG(total_duration_sec) as avg_duration,
+        MIN(started_at) as first_execution,
+        MAX(started_at) as last_execution
+      FROM variant_executions
+      WHERE completed_at IS NOT NULL
+        AND ${_TelemetryInsightEngine.REAL_DATA_FILTER}
+        AND started_at > datetime('now', '-30 days')
+      GROUP BY variant, prompt_version
+      HAVING total_tasks >= 3
+      ORDER BY success_rate DESC, avg_completeness DESC
+    `;
+    const results = this.variantsDb.prepare(query).all();
+    if (results.length >= 2) {
+      const topPerformer = results[0];
+      const worstPerformer = results[results.length - 1];
+      const performanceGap = topPerformer.success_rate - worstPerformer.success_rate;
+      if (performanceGap > 0.3) {
+        insights.push({
+          type: "performance",
+          severity: "warning",
+          title: "Significant Performance Gap Detected",
+          description: `Variant ${topPerformer.variant} (v${topPerformer.prompt_version || "unknown"}) significantly outperforms ${worstPerformer.variant} (v${worstPerformer.prompt_version || "unknown"})`,
+          data: {
+            topPerformer: {
+              variant: topPerformer.variant,
+              version: topPerformer.prompt_version || "unknown",
+              successRate: topPerformer.success_rate,
+              completeness: topPerformer.avg_completeness
+            },
+            worstPerformer: {
+              variant: worstPerformer.variant,
+              version: worstPerformer.prompt_version || "unknown",
+              successRate: worstPerformer.success_rate,
+              completeness: worstPerformer.avg_completeness
+            },
+            gap: performanceGap
+          },
+          recommendations: [
+            `Consider using ${topPerformer.variant} variant for similar tasks`,
+            `Review and optimize ${worstPerformer.variant} prompt strategy`,
+            "Analyze successful patterns from top performer"
+          ],
+          confidence: 0.85,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+    }
+    return insights;
+  }
+  /**
+   * Generate optimization recommendations based on performance data.
+   */
+  generateOptimizationRecommendations() {
+    const insights = [];
+    const promptQuery = `
+      SELECT
+        variant,
+        prompt_version,
+        COUNT(*) as sample_size,
+        AVG(completeness) as avg_completeness,
+        CAST(SUM(CASE WHEN verdict = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) as success_rate
+      FROM variant_executions
+      WHERE completed_at IS NOT NULL
+        AND prompt_version IS NOT NULL
+        AND ${_TelemetryInsightEngine.REAL_DATA_FILTER}
+      GROUP BY variant, prompt_version
+      HAVING sample_size >= 5
+      ORDER BY success_rate DESC
+    `;
+    const promptResults = this.variantsDb.prepare(promptQuery).all();
+    const byVariant = /* @__PURE__ */ new Map();
+    promptResults.forEach((row) => {
+      const entries = byVariant.get(row.variant) || [];
+      entries.push(row);
+      byVariant.set(row.variant, entries);
+    });
+    for (const [variant, versions] of Array.from(byVariant.entries())) {
+      if (versions.length >= 2) {
+        const best = versions[0];
+        const current = versions.find(
+          (v) => v.prompt_version.includes("latest") || v.prompt_version.includes("current")
+        ) || versions[versions.length - 1];
+        if (best.success_rate - current.success_rate > 0.15) {
+          insights.push({
+            type: "optimization",
+            severity: "warning",
+            title: `Prompt Optimization Opportunity for ${variant}`,
+            description: `Version ${best.prompt_version} significantly outperforms current version ${current.prompt_version}`,
+            data: {
+              variant,
+              bestVersion: best.prompt_version,
+              currentVersion: current.prompt_version,
+              improvement: best.success_rate - current.success_rate,
+              bestSuccessRate: best.success_rate,
+              currentSuccessRate: current.success_rate
+            },
+            recommendations: [
+              `Consider promoting version ${best.prompt_version} to current`,
+              `Analyze differences between ${best.prompt_version} and ${current.prompt_version}`,
+              `Apply successful patterns from ${best.prompt_version} to future prompts`
+            ],
+            confidence: 0.78,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        }
+      }
+    }
+    return insights;
+  }
+  /**
+   * Generate predictive insights based on historical patterns.
+   */
+  generatePredictiveInsights() {
+    const insights = [];
+    const predictionQuery = `
+      SELECT
+        project_language,
+        project_framework,
+        COUNT(*) as total_tasks,
+        CAST(SUM(CASE WHEN verdict = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) as success_rate,
+        AVG(completeness) as avg_completeness,
+        AVG(total_duration_sec) as avg_duration
+      FROM variant_executions
+      WHERE completed_at IS NOT NULL
+        AND project_language IS NOT NULL
+        AND ${_TelemetryInsightEngine.REAL_DATA_FILTER}
+      GROUP BY project_language, project_framework
+      HAVING total_tasks >= 10
+      ORDER BY success_rate DESC
+    `;
+    const predictions = this.variantsDb.prepare(predictionQuery).all();
+    const successfulScenarios = predictions.filter((p) => p.success_rate > 0.8);
+    const challengingScenarios = predictions.filter((p) => p.success_rate < 0.5);
+    if (successfulScenarios.length > 0 && challengingScenarios.length > 0) {
+      insights.push({
+        type: "prediction",
+        severity: "info",
+        title: "Project Type Success Patterns Identified",
+        description: `Analysis of ${predictions.length} project scenarios reveals distinct success patterns`,
+        data: {
+          successfulPatterns: successfulScenarios.slice(0, 3),
+          challengingPatterns: challengingScenarios.slice(0, 3),
+          totalAnalyzed: predictions.length
+        },
+        recommendations: [
+          "Leverage successful patterns for similar project types",
+          "Consider additional support for challenging scenarios",
+          "Adjust prompt strategies based on project characteristics"
+        ],
+        confidence: 0.72,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    return insights;
+  }
+  /**
+   * Detect anomalies in performance data.
+   */
+  detectAnomalies() {
+    const insights = [];
+    const durationQuery = `
+      SELECT
+        variant,
+        task_id,
+        total_duration_sec,
+        verdict,
+        completeness,
+        started_at
+      FROM variant_executions
+      WHERE completed_at IS NOT NULL
+        AND total_duration_sec IS NOT NULL
+        AND ${_TelemetryInsightEngine.REAL_DATA_FILTER}
+        AND started_at > datetime('now', '-7 days')
+      ORDER BY total_duration_sec DESC
+      LIMIT 20
+    `;
+    const durationResults = this.variantsDb.prepare(durationQuery).all();
+    if (durationResults.length >= 5) {
+      const durations = durationResults.map((r) => r.total_duration_sec);
+      const mean = durations.reduce((a, b) => a + b, 0) / durations.length;
+      const stdDev = Math.sqrt(
+        durations.reduce((sq, n) => sq + (n - mean) ** 2, 0) / durations.length
+      );
+      const anomalies = durationResults.filter(
+        (r) => Math.abs(r.total_duration_sec - mean) > 2 * stdDev
+      );
+      if (anomalies.length > 0) {
+        insights.push({
+          type: "anomaly",
+          severity: "warning",
+          title: "Unusual Execution Duration Patterns Detected",
+          description: `Found ${anomalies.length} executions with unusual duration patterns`,
+          data: {
+            anomalies: anomalies.map((a) => ({
+              taskId: a.task_id,
+              variant: a.variant,
+              duration: a.total_duration_sec,
+              verdict: a.verdict,
+              deviation: Math.abs(a.total_duration_sec - mean) / stdDev
+            })),
+            averageDuration: mean,
+            standardDeviation: stdDev
+          },
+          recommendations: [
+            "Investigate unusually long or short executions",
+            "Check for timeout issues or incomplete work",
+            "Review task complexity estimates"
+          ],
+          confidence: 0.68,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+    }
+    return insights;
+  }
+  /**
+   * Start real-time monitoring for continuous insight generation.
+   */
+  startRealTimeMonitoring() {
+    this.intervalId = setInterval(async () => {
+      try {
+        await this.generateInsights();
+      } catch (error) {
+        emitTelemetryFallbackWarning("Real-time insight generation failed", error);
+      }
+    }, this.calculationInterval);
+  }
+  /**
+   * Stop real-time monitoring.
+   */
+  stopRealTimeMonitoring() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = void 0;
+    }
+  }
+  /**
+   * Get provider performance DNA analysis.
+   *
+   * @internal Preview / not fully implemented. Only `provider`, a coarse
+   * `codeGeneration` capability, and `consistencyScore` are derived from real
+   * data; `model` is reported as `'unknown'` and `optimalUseCases`,
+   * `limitations`, and most adaptation fields are placeholders (empty/`null`).
+   * Public CLI surfaces must label this output as a preview and must not present
+   * the placeholder fields as real analytics.
+   */
+  async getProviderPerformanceDNA() {
+    const query = `
+      SELECT
+        CASE WHEN INSTR(variant, ':') > 0
+          THEN SUBSTR(variant, 1, INSTR(variant, ':') - 1)
+          ELSE variant
+        END as provider,
+        COUNT(*) as total_tasks,
+        CAST(SUM(CASE WHEN verdict = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) as success_rate,
+        AVG(completeness) as avg_completeness,
+        AVG(total_duration_sec) as avg_duration
+      FROM variant_executions
+      WHERE completed_at IS NOT NULL
+      GROUP BY CASE WHEN INSTR(variant, ':') > 0
+        THEN SUBSTR(variant, 1, INSTR(variant, ':') - 1)
+        ELSE variant
+      END
+      HAVING total_tasks >= 5
+    `;
+    const results = this.variantsDb.prepare(query).all();
+    return results.map((row) => ({
+      provider: row.provider,
+      model: "unknown",
+      // Would need more detailed tracking
+      capabilities: {
+        codeGeneration: row.success_rate,
+        debugging: null,
+        refactoring: null,
+        testing: null,
+        documentation: null,
+        architecture: null
+      },
+      optimalUseCases: [],
+      // Would need more detailed analysis
+      limitations: [],
+      // Would need failure pattern analysis
+      adaptationPatterns: {
+        learningRate: null,
+        consistencyScore: Math.min(row.success_rate / 0.8, 1),
+        contextRetention: null
+      }
+    }));
+  }
+  /**
+   * Analyze behavioral patterns from execution data.
+   *
+   * @internal Not yet implemented. Always returns an empty array; behavioral
+   * telemetry collection is not wired up. Do not present as real analytics.
+   */
+  async analyzeBehavioralPatterns() {
+    return [];
+  }
+  /**
+   * Generate semantic task profiles.
+   *
+   * @internal Not yet implemented. Always returns an empty array; semantic
+   * analysis is not wired up. Do not present as real analytics.
+   */
+  async generateSemanticProfiles() {
+    return [];
+  }
+  /**
+   * Start the telemetry insight engine
+   *
+   * Initializes the insight engine and prepares it for generating insights
+   * from telemetry data. This method must be called before using other
+   * insight engine functionality.
+   *
+   * @returns {void}
+   *
+   * @example
+   * ```typescript
+   * const engine = new TelemetryInsightEngine();
+   * engine.start();
+   * // Now the engine is ready to generate insights
+   * ```
+   */
+  start() {
+    if (!this.enabled) {
+      emitTelemetryFallbackWarning("TelemetryInsightEngine is disabled - using in-memory fallback");
+      return;
+    }
+    try {
+      this.variantsDb.prepare("SELECT 1").get();
+      if (this.enableRealTime) {
+        this.startRealTimeMonitoring();
+      }
+    } catch (error) {
+      emitTelemetryFallbackWarning("Failed to start TelemetryInsightEngine", error);
+      throw new Error("TelemetryInsightEngine database connection is not available");
+    }
+  }
+  /**
+   * Add a data source to the insight engine
+   *
+   * Registers a new data source that the insight engine can use for
+   * generating insights and analysis. Data sources provide structured
+   * information about different aspects of the system.
+   *
+   * @param name - Unique identifier for the data source
+   * @param config - Configuration describing the data source
+   * @returns {void}
+   *
+   * @example
+   * ```typescript
+   * engine.addDataSource('progress_tracker', {
+   *   name: 'Progress Tracker Data',
+   *   description: 'Progress tracking and performance data',
+   *   type: 'time_series'
+   * });
+   * ```
+   */
+  addDataSource(name, config) {
+    if (!this.enabled) {
+      emitTelemetryFallbackWarning(`Insight engine disabled - skipping data source: ${name}`);
+      return;
+    }
+    try {
+      const createTableQuery = `
+        CREATE TABLE IF NOT EXISTS data_sources (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          name TEXT UNIQUE NOT NULL,
+          display_name TEXT NOT NULL,
+          description TEXT NOT NULL,
+          type TEXT NOT NULL,
+          schema TEXT,
+          created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+          status TEXT DEFAULT 'active'
+        )
+      `;
+      this.variantsDb.prepare(createTableQuery).run();
+      const insertQuery = `
+        INSERT OR REPLACE INTO data_sources (name, display_name, description, type, schema)
+        VALUES (?, ?, ?, ?, ?)
+      `;
+      this.variantsDb.prepare(insertQuery).run(
+        name,
+        config.name,
+        config.description,
+        config.type,
+        JSON.stringify(config.schema || {})
+      );
+    } catch (error) {
+      emitTelemetryFallbackWarning(`Failed to register data source ${name}`, error);
+    }
+  }
+  /**
+   * Clean up resources and stop monitoring.
+   */
+  close() {
+    this.stopRealTimeMonitoring();
+    this.variantsDb.close();
+  }
+};
+
+// src/telemetry/integrity-check.ts
+function getSchemaColumns(db) {
+  return getTableColumns(db, "variant_executions");
+}
+function getTableColumns(db, table) {
+  try {
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    return new Set(rows.map((r) => r.name));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function getWhitelistColumns() {
+  return new Set(VARIANT_EXECUTION_COLUMNS);
+}
+function validateTelemetryIntegrity(db) {
+  const schemaColumns = getSchemaColumns(db);
+  const whitelistColumns = getWhitelistColumns();
+  const excludedColumns = /* @__PURE__ */ new Set([
+    "id",
+    // Auto-increment primary key
+    "project_id",
+    // Scope dimension, always set by context-aware writers
+    "lab_id",
+    // Optional lab scoping dimension
+    "lab_run_id",
+    // Optional lab run scoping dimension
+    "task_id",
+    // Part of UNIQUE constraint, not dynamically updated
+    "variant",
+    // Part of UNIQUE constraint, not dynamically updated
+    "created_at",
+    // Auto-managed by DEFAULT CURRENT_TIMESTAMP
+    "updated_at",
+    // Auto-managed by DEFAULT CURRENT_TIMESTAMP
+    "commit_sha_before",
+    // Managed separately via git integration
+    "commit_sha_after",
+    // Managed separately via git integration
+    "workspace_edit_success_rate",
+    // Derived metric
+    "score_breakdown_json"
+    // Managed by judge evaluation system
+  ]);
+  const schemaNotInWhitelist = [];
+  const whitelistNotInSchema = [];
+  for (const col of schemaColumns) {
+    if (!whitelistColumns.has(col) && !excludedColumns.has(col)) {
+      schemaNotInWhitelist.push(col);
+    }
+  }
+  for (const col of whitelistColumns) {
+    if (!schemaColumns.has(col)) {
+      whitelistNotInSchema.push(col);
+    }
+  }
+  const tableColumnCache = /* @__PURE__ */ new Map();
+  for (const inv of SCHEMA_INVARIANTS) {
+    let cols = tableColumnCache.get(inv.table);
+    if (!cols) {
+      cols = getTableColumns(db, inv.table);
+      tableColumnCache.set(inv.table, cols);
+    }
+    if (cols.size === 0) continue;
+    if (!cols.has(inv.column)) {
+      schemaNotInWhitelist.push(`${inv.table}.${inv.column}`);
+    }
+  }
+  return {
+    schemaNotInWhitelist,
+    whitelistNotInSchema
+  };
+}
+function formatIntegrityReport(issues) {
+  const lines = [];
+  if (issues.schemaNotInWhitelist.length > 0) {
+    lines.push(
+      `Warning: Schema columns not in whitelist: ${issues.schemaNotInWhitelist.join(", ")}`
+    );
+    lines.push("   These columns exist but cannot be queried safely.");
+    lines.push("   Action: Add to VARIANT_EXECUTION_COLUMNS in variant-execution-columns.ts");
+  }
+  if (issues.whitelistNotInSchema.length > 0) {
+    lines.push(
+      `Warning: Whitelist columns not in schema: ${issues.whitelistNotInSchema.join(", ")}`
+    );
+    lines.push("   These whitelisted columns do not exist in the schema.");
+    lines.push("   Action: Remove from VARIANT_EXECUTION_COLUMNS or add to schema");
+  }
+  if (lines.length === 0) {
+    lines.push("OK: Telemetry integrity check passed");
+  }
+  return lines.join("\n");
+}
+
+// src/telemetry/observability-metrics.ts
+import { EventEmitter } from "events";
+var ObservabilityMetricsTracker = class _ObservabilityMetricsTracker extends EventEmitter {
+  static DEFAULT_MAX_METRIC_KEYS = 500;
+  static DEFAULT_POOL_EXHAUSTION_ALERT_THRESHOLD = 10;
+  static DEFAULT_CONCURRENCY_ALERT_THRESHOLD = 5;
+  static DEFAULT_TIMEOUT_ALERT_THRESHOLD = 20;
+  metrics;
+  logger;
+  maxMetricKeys;
+  poolExhaustionAlertThreshold;
+  concurrencyAlertThreshold;
+  timeoutAlertThreshold;
+  static parsePositiveIntEnv(envVar, fallback) {
+    const raw = process.env[envVar];
+    if (!raw) {
+      return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+  }
+  constructor(logger) {
+    super();
+    this.logger = logger;
+    this.maxMetricKeys = _ObservabilityMetricsTracker.parsePositiveIntEnv(
+      "POETIC_TELEMETRY_OBSERVABILITY_MAX_KEYS",
+      _ObservabilityMetricsTracker.DEFAULT_MAX_METRIC_KEYS
+    );
+    this.poolExhaustionAlertThreshold = _ObservabilityMetricsTracker.parsePositiveIntEnv(
+      "POETIC_TELEMETRY_POOL_EXHAUSTION_ALERT_THRESHOLD",
+      _ObservabilityMetricsTracker.DEFAULT_POOL_EXHAUSTION_ALERT_THRESHOLD
+    );
+    this.concurrencyAlertThreshold = _ObservabilityMetricsTracker.parsePositiveIntEnv(
+      "POETIC_TELEMETRY_CONCURRENCY_ALERT_THRESHOLD",
+      _ObservabilityMetricsTracker.DEFAULT_CONCURRENCY_ALERT_THRESHOLD
+    );
+    this.timeoutAlertThreshold = _ObservabilityMetricsTracker.parsePositiveIntEnv(
+      "POETIC_TELEMETRY_TIMEOUT_ALERT_THRESHOLD",
+      _ObservabilityMetricsTracker.DEFAULT_TIMEOUT_ALERT_THRESHOLD
+    );
+    this.metrics = {
+      poolExhaustions: /* @__PURE__ */ new Map(),
+      concurrencyViolations: /* @__PURE__ */ new Map(),
+      timeouts: /* @__PURE__ */ new Map(),
+      lastUpdated: Date.now()
+    };
+  }
+  /**
+   * Record a pool exhaustion event
+   */
+  recordPoolExhaustion(params) {
+    const { poolType, maxSize, activeCount } = params;
+    const key = poolType;
+    const existing = this.metrics.poolExhaustions.get(key);
+    const metrics = {
+      totalExhaustions: (existing?.totalExhaustions ?? 0) + 1,
+      lastExhaustionAt: Date.now(),
+      poolType,
+      maxSize,
+      activeCount
+    };
+    this.metrics.poolExhaustions.set(key, metrics);
+    this.enforceBoundedMap(this.metrics.poolExhaustions, (entry) => entry.lastExhaustionAt);
+    this.metrics.lastUpdated = Date.now();
+    this.logger?.logCostEvent("pool_exhaustion", {
+      poolType,
+      maxSize,
+      activeCount,
+      totalExhaustions: metrics.totalExhaustions
+    });
+    this.emit("pool_exhaustion", metrics);
+    if (metrics.totalExhaustions > this.poolExhaustionAlertThreshold) {
+      this.emit("pool_exhaustion_alert", {
+        ...metrics,
+        severity: "high",
+        message: `Pool ${poolType} has exhausted ${metrics.totalExhaustions} times`
+      });
+    }
+  }
+  /**
+   * Record a concurrency limit violation
+   */
+  recordConcurrencyViolation(params) {
+    const { resource, configuredLimit, actualCount } = params;
+    const key = resource;
+    const existing = this.metrics.concurrencyViolations.get(key);
+    const metrics = {
+      totalViolations: (existing?.totalViolations ?? 0) + 1,
+      lastViolationAt: Date.now(),
+      resource,
+      configuredLimit,
+      actualCount
+    };
+    this.metrics.concurrencyViolations.set(key, metrics);
+    this.enforceBoundedMap(this.metrics.concurrencyViolations, (entry) => entry.lastViolationAt);
+    this.metrics.lastUpdated = Date.now();
+    this.logger?.logCostEvent("concurrency_limit_violation", {
+      resource,
+      configuredLimit,
+      actualCount,
+      totalViolations: metrics.totalViolations
+    });
+    this.emit("concurrency_violation", metrics);
+    if (metrics.totalViolations > this.concurrencyAlertThreshold) {
+      this.emit("concurrency_violation_alert", {
+        ...metrics,
+        severity: "high",
+        message: `Resource ${resource} has violated concurrency limit ${metrics.totalViolations} times`
+      });
+    }
+  }
+  /**
+   * Record a timeout event
+   */
+  recordTimeout(params) {
+    const { operationType, configuredTimeoutMs, actualDurationMs } = params;
+    const key = operationType;
+    const existing = this.metrics.timeouts.get(key);
+    const metrics = {
+      totalTimeouts: (existing?.totalTimeouts ?? 0) + 1,
+      lastTimeoutAt: Date.now(),
+      operationType,
+      configuredTimeoutMs,
+      actualDurationMs
+    };
+    this.metrics.timeouts.set(key, metrics);
+    this.enforceBoundedMap(this.metrics.timeouts, (entry) => entry.lastTimeoutAt);
+    this.metrics.lastUpdated = Date.now();
+    this.logger?.logCostEvent("timeout_hit", {
+      operationType,
+      configuredTimeoutMs,
+      actualDurationMs,
+      totalTimeouts: metrics.totalTimeouts
+    });
+    this.emit("timeout", metrics);
+    if (metrics.totalTimeouts > this.timeoutAlertThreshold) {
+      this.emit("timeout_alert", {
+        ...metrics,
+        severity: "high",
+        message: `Operation ${operationType} has timed out ${metrics.totalTimeouts} times`
+      });
+    }
+  }
+  /**
+   * Get current metrics snapshot
+   */
+  getMetrics() {
+    return {
+      poolExhaustions: new Map(this.metrics.poolExhaustions),
+      concurrencyViolations: new Map(this.metrics.concurrencyViolations),
+      timeouts: new Map(this.metrics.timeouts),
+      lastUpdated: this.metrics.lastUpdated
+    };
+  }
+  /**
+   * Get metrics summary for reporting
+   */
+  getSummary() {
+    const totalPoolExhaustions = Array.from(this.metrics.poolExhaustions.values()).reduce(
+      (sum, m) => sum + m.totalExhaustions,
+      0
+    );
+    const totalConcurrencyViolations = Array.from(
+      this.metrics.concurrencyViolations.values()
+    ).reduce((sum, m) => sum + m.totalViolations, 0);
+    const totalTimeouts = Array.from(this.metrics.timeouts.values()).reduce(
+      (sum, m) => sum + m.totalTimeouts,
+      0
+    );
+    return {
+      totalPoolExhaustions,
+      totalConcurrencyViolations,
+      totalTimeouts,
+      poolTypes: Array.from(this.metrics.poolExhaustions.keys()),
+      resources: Array.from(this.metrics.concurrencyViolations.keys()),
+      operationTypes: Array.from(this.metrics.timeouts.keys())
+    };
+  }
+  /**
+   * Reset all metrics
+   */
+  reset() {
+    this.metrics = {
+      poolExhaustions: /* @__PURE__ */ new Map(),
+      concurrencyViolations: /* @__PURE__ */ new Map(),
+      timeouts: /* @__PURE__ */ new Map(),
+      lastUpdated: Date.now()
+    };
+    this.emit("metrics_reset");
+  }
+  enforceBoundedMap(map, getTimestamp) {
+    if (map.size <= this.maxMetricKeys) {
+      return;
+    }
+    const entries = Array.from(map.entries()).sort(([, a], [, b]) => {
+      const aTs = getTimestamp(a) ?? 0;
+      const bTs = getTimestamp(b) ?? 0;
+      return aTs - bTs;
+    });
+    const toDelete = map.size - this.maxMetricKeys;
+    for (let i = 0; i < toDelete; i++) {
+      const key = entries[i]?.[0];
+      if (key) {
+        map.delete(key);
+      }
+    }
+  }
+};
+var globalObservabilityTracker = null;
+function getObservabilityTracker(logger) {
+  if (!globalObservabilityTracker) {
+    globalObservabilityTracker = new ObservabilityMetricsTracker(logger);
+  }
+  return globalObservabilityTracker;
+}
+function recordMetric(name, value, tags) {
+  try {
+    getTelemetryLogger().logEvent(`metric:${name}`, { value, ...tags ?? {} });
+  } catch {
+  }
+}
+
+export {
+  TelemetryDashboard,
+  isCoreVariantEvent,
+  validateEventType,
+  TelemetryInsightEngine,
+  getSchemaColumns,
+  getWhitelistColumns,
+  validateTelemetryIntegrity,
+  formatIntegrityReport,
+  getObservabilityTracker,
+  recordMetric
+};
+//# sourceMappingURL=chunk-5RBHQYDB.js.map