@devflow-tools/database 0.8.10 → 0.9.0

package/src/database.ts

@@ -14,9 +14,9 @@ export class DevFlowDatabase {
     const dbPath = join(devflowDir, 'devflow.db');
     this.db = new NodeSqliteDatabase(dbPath);
 
-    // 启用 WAL 模式
     this.db.exec('PRAGMA journal_mode = WAL');
     this.db.exec('PRAGMA busy_timeout = 5000');
+    this.db.exec('PRAGMA foreign_keys = OFF');
 
     this.initializeSchema();
   }
@@ -119,8 +119,7 @@ export class DevFlowDatabase {
         subagent_id TEXT,
         error TEXT,
         blocked INTEGER DEFAULT 0 CHECK (blocked IN (0, 1)),
-        block_reason TEXT,
-        FOREIGN KEY (execution_id) REFERENCES skill_executions(execution_id) ON DELETE CASCADE
+        block_reason TEXT
       );
 
       CREATE INDEX IF NOT EXISTS idx_executions_skill ON skill_executions(skill_name);
@@ -130,7 +129,82 @@ export class DevFlowDatabase {
       CREATE INDEX IF NOT EXISTS idx_events_timestamp ON tool_call_events(timestamp);
       CREATE INDEX IF NOT EXISTS idx_events_tool_type ON tool_call_events(tool_type);
       CREATE INDEX IF NOT EXISTS idx_events_mcp ON tool_call_events(is_mcp_tool);
+      CREATE INDEX IF NOT EXISTS idx_events_session ON tool_call_events(session_id);
+
+      -- Sessions table: top-level container per Claude Code session
+      CREATE TABLE IF NOT EXISTS sessions (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        label TEXT,
+        started_at INTEGER NOT NULL,
+        finished_at INTEGER,
+        duration_ms INTEGER DEFAULT 0,
+        total_tool_calls INTEGER DEFAULT 0,
+        mcp_tool_calls INTEGER DEFAULT 0,
+        direct_tool_calls INTEGER DEFAULT 0,
+        subagent_count INTEGER DEFAULT 0,
+        status TEXT NOT NULL DEFAULT 'running' CHECK (status IN ('running', 'completed', 'failed'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_root);
+      CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions(started_at DESC);
     `);
+
+    // Migration: add session_id to skill_executions (SQLite compat — ignore if exists)
+    try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN session_id TEXT REFERENCES sessions(id)'); } catch {}
+    // Migration: add session_id to tool_call_events
+    try { this.db.exec('ALTER TABLE tool_call_events ADD COLUMN session_id TEXT REFERENCES sessions(id)'); } catch {}
+    // Migration: kind column for event type classification
+    try { this.db.exec("ALTER TABLE tool_call_events ADD COLUMN kind TEXT DEFAULT 'tool_use'"); } catch {}
+    // Migration: workflow run persistence
+    try { this.db.exec('ALTER TABLE tool_call_events ADD COLUMN workflow_run_id TEXT'); } catch {}
+
+    // Migration: tool_metrics table for per-tool metrics collection
+    try {
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS tool_metrics (
+          id TEXT PRIMARY KEY,
+          tool_call_event_id TEXT NOT NULL,
+          session_id TEXT NOT NULL,
+          tool_name TEXT NOT NULL,
+          query TEXT,
+          status TEXT NOT NULL DEFAULT 'success',
+          result_count INTEGER DEFAULT 0,
+          result_size_bytes INTEGER DEFAULT 0,
+          latency_ms INTEGER DEFAULT 0,
+          engine TEXT,
+          accuracy_query_id TEXT,
+          metadata TEXT,
+          created_at INTEGER NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_tool_metrics_session ON tool_metrics(session_id);
+        CREATE INDEX IF NOT EXISTS idx_tool_metrics_tool ON tool_metrics(tool_name);
+        CREATE INDEX IF NOT EXISTS idx_tool_metrics_created ON tool_metrics(created_at);
+      `);
+    } catch {}
+
+    // Migration: accuracy queries table for search quality tracking
+    try {
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS accuracy_queries (
+          id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL,
+          engine TEXT NOT NULL CHECK(engine IN ('codegraph','knowledge','memory')),
+          query TEXT NOT NULL,
+          top_k_results TEXT NOT NULL,
+          selected_ids TEXT,
+          relevance_feedback TEXT CHECK(relevance_feedback IN ('hit','partial','miss')),
+          annotator_note TEXT,
+          annotated_at INTEGER,
+          created_at INTEGER NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_accuracy_queries_engine ON accuracy_queries(engine);
+        CREATE INDEX IF NOT EXISTS idx_accuracy_queries_session ON accuracy_queries(session_id);
+        CREATE INDEX IF NOT EXISTS idx_accuracy_queries_feedback ON accuracy_queries(relevance_feedback);
+      `);
+    } catch {}
   }
 
   insertRun(run: any): void {
@@ -213,14 +287,14 @@ export class DevFlowDatabase {
       INSERT INTO telemetry_events (run_id, kind, timestamp, duration, success, tool_name, plugin_name, metadata)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
-      event.runId,
-      event.kind,
-      event.timestamp,
-      event.duration,
-      event.success,
-      event.toolName,
-      event.pluginName,
-      JSON.stringify(event.metadata) ?? null
+      event.runId ?? null,
+      event.kind ?? null,
+      event.timestamp ?? null,
+      event.duration ?? null,
+      event.success ?? null,
+      event.toolName ?? null,
+      event.pluginName ?? null,
+      event.metadata ? JSON.stringify(event.metadata) : null
     );
   }
 
@@ -290,10 +364,165 @@ export class DevFlowDatabase {
     this.db.prepare('DELETE FROM settings WHERE key = ?').run(key);
   }
 
+  // ---- Sessions ----
+
+  insertSession(params: {
+    id: string;
+    projectRoot: string;
+    label?: string;
+    startedAt: number;
+  }): void {
+    this.db.prepare(`
+      INSERT OR IGNORE INTO sessions (id, project_root, label, started_at, status)
+      VALUES (?, ?, ?, ?, 'running')
+    `).run(params.id, params.projectRoot, params.label ?? null, params.startedAt);
+  }
+
+  getSession(id: string): any | null {
+    const row = this.db.prepare('SELECT * FROM sessions WHERE id = ?').get(id) as any;
+    if (!row) return null;
+    return {
+      id: row.id,
+      projectRoot: row.project_root,
+      label: row.label,
+      startedAt: row.started_at,
+      finishedAt: row.finished_at,
+      durationMs: row.duration_ms,
+      totalToolCalls: row.total_tool_calls,
+      mcpToolCalls: row.mcp_tool_calls,
+      directToolCalls: row.direct_tool_calls,
+      subagentCount: row.subagent_count,
+      status: row.status,
+    };
+  }
+
+  listSessions(limit: number, offset: number, projectRoot?: string): any[] {
+    let query = 'SELECT * FROM sessions';
+    const params: any[] = [];
+    if (projectRoot) {
+      query += ' WHERE project_root = ?';
+      params.push(projectRoot);
+    }
+    query += ' ORDER BY started_at DESC LIMIT ? OFFSET ?';
+    params.push(Number(limit), Number(offset));
+
+    const rows = this.db.prepare(query).all(...params) as any[];
+    return rows.map((row: any) => ({
+      id: row.id,
+      projectRoot: row.project_root,
+      label: row.label,
+      startedAt: row.started_at,
+      finishedAt: row.finished_at,
+      durationMs: row.duration_ms,
+      totalToolCalls: row.total_tool_calls,
+      mcpToolCalls: row.mcp_tool_calls,
+      directToolCalls: row.direct_tool_calls,
+      subagentCount: row.subagent_count,
+      status: row.status,
+    }));
+  }
+
+  closeSession(id: string, finishedAt?: number): void {
+    const events = this.db.prepare(
+      'SELECT * FROM tool_call_events WHERE session_id = ? OR execution_id = ?'
+    ).all(id, id) as any[];
+
+    // deduplicate by event_id
+    const seen = new Set<string>();
+    const unique = events.filter((e: any) => {
+      if (seen.has(e.event_id)) return false;
+      seen.add(e.event_id);
+      return true;
+    });
+
+    const totalToolCalls = unique.length;
+    const mcpToolCalls = unique.filter((e: any) => e.is_mcp_tool === 1).length;
+    const directToolCalls = totalToolCalls - mcpToolCalls;
+    const subagentCount = unique.filter((e: any) => e.tool_type === 'subagent').length;
+
+    const timestamps = unique.map((e: any) => e.timestamp).filter(Boolean) as number[];
+    const durationMs = timestamps.length >= 2
+      ? Math.max(...timestamps) - Math.min(...timestamps)
+      : 0;
+
+    this.db.prepare(`
+      UPDATE sessions
+      SET finished_at = ?, duration_ms = ?, total_tool_calls = ?,
+          mcp_tool_calls = ?, direct_tool_calls = ?, subagent_count = ?,
+          status = 'completed'
+      WHERE id = ?
+    `).run(finishedAt ?? Date.now(), durationMs, totalToolCalls, mcpToolCalls, directToolCalls, subagentCount, id);
+  }
+
+  listToolCallEventsBySession(sessionId: string): any[] {
+    const rows = this.db.prepare(
+      'SELECT * FROM tool_call_events WHERE session_id = ? ORDER BY timestamp ASC'
+    ).all(sessionId) as any[];
+
+    return rows.map(row => ({
+      eventId: row.event_id,
+      executionId: row.execution_id,
+      sessionId: row.session_id,
+      timestamp: row.timestamp,
+      toolName: row.tool_name,
+      toolType: row.tool_type,
+      isMcpTool: row.is_mcp_tool === 1,
+      mcpToolName: row.mcp_tool_name,
+      mcpEnforced: row.mcp_enforced === 1,
+      mcpFallback: row.mcp_fallback === 1,
+      kind: row.kind,
+      input: row.input ? JSON.parse(row.input) : null,
+      output: row.output ? JSON.parse(row.output) : null,
+      duration: row.duration,
+      parentToolCallId: row.parent_tool_call_id,
+      subagentId: row.subagent_id,
+      error: row.error,
+      blocked: row.blocked === 1,
+      blockReason: row.block_reason,
+    }));
+  }
+
+  listToolCallEventsBySessions(sessionIds: string[]): Record<string, any[]> {
+    if (sessionIds.length === 0) return {};
+    const placeholders = sessionIds.map(() => '?').join(',');
+    const rows = this.db.prepare(
+      `SELECT * FROM tool_call_events WHERE session_id IN (${placeholders}) ORDER BY timestamp ASC`
+    ).all(...sessionIds) as any[];
+
+    const grouped: Record<string, any[]> = {};
+    for (const row of rows) {
+      const sid = row.session_id as string;
+      if (!grouped[sid]) grouped[sid] = [];
+      grouped[sid].push({
+        eventId: row.event_id,
+        executionId: row.execution_id,
+        sessionId: row.session_id,
+        timestamp: row.timestamp,
+        toolName: row.tool_name,
+        toolType: row.tool_type,
+        isMcpTool: row.is_mcp_tool === 1,
+        mcpToolName: row.mcp_tool_name,
+        mcpEnforced: row.mcp_enforced === 1,
+        mcpFallback: row.mcp_fallback === 1,
+        kind: row.kind,
+        input: row.input ? JSON.parse(row.input) : null,
+        output: row.output ? JSON.parse(row.output) : null,
+        duration: row.duration,
+        parentToolCallId: row.parent_tool_call_id,
+        subagentId: row.subagent_id,
+        error: row.error,
+        blocked: row.blocked === 1,
+        blockReason: row.block_reason,
+      });
+    }
+    return grouped;
+  }
+
   // ---- Skill Executions ----
 
   insertSkillExecution(params: {
     executionId: string;
+    sessionId?: string;
     skillName: string;
     startedAt: number;
     status: string;
@@ -302,10 +531,11 @@ export class DevFlowDatabase {
   }): void {
     this.db.prepare(`
       INSERT INTO skill_executions
-      (execution_id, skill_name, started_at, status, required_mcp_tools, available_mcp_tools)
-      VALUES (?, ?, ?, ?, ?, ?)
+      (execution_id, session_id, skill_name, started_at, status, required_mcp_tools, available_mcp_tools)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
     `).run(
       params.executionId,
+      params.sessionId ?? null,
       params.skillName,
       params.startedAt,
       params.status,
@@ -319,6 +549,7 @@ export class DevFlowDatabase {
     if (!row) return null;
     return {
       executionId: row.execution_id,
+      sessionId: row.session_id,
       skillName: row.skill_name,
       startedAt: row.started_at,
       finishedAt: row.finished_at,
@@ -329,7 +560,6 @@ export class DevFlowDatabase {
       mcpToolCalls: row.mcp_tool_calls,
       directToolCalls: row.direct_tool_calls,
       subagentCount: row.subagent_count,
-      totalTokens: row.total_tokens,
       totalDuration: row.total_duration,
       mcpComplianceRate: row.mcp_compliance_rate,
       missedMcpTools: row.missed_mcp_tools ? JSON.parse(row.missed_mcp_tools) : null,
@@ -341,7 +571,6 @@ export class DevFlowDatabase {
     status?: string;
     finishedAt?: number;
     totalDuration?: number;
-    totalTokens?: number;
     mcpComplianceRate?: number;
     missedMcpTools?: string[];
     totalToolCalls?: number;
@@ -355,7 +584,6 @@ export class DevFlowDatabase {
     if (updates.status !== undefined) { sets.push('status = ?'); values.push(updates.status); }
     if (updates.finishedAt !== undefined) { sets.push('finished_at = ?'); values.push(updates.finishedAt); }
     if (updates.totalDuration !== undefined) { sets.push('total_duration = ?'); values.push(updates.totalDuration); }
-    if (updates.totalTokens !== undefined) { sets.push('total_tokens = ?'); values.push(updates.totalTokens); }
     if (updates.mcpComplianceRate !== undefined) { sets.push('mcp_compliance_rate = ?'); values.push(updates.mcpComplianceRate); }
     if (updates.missedMcpTools !== undefined) { sets.push('missed_mcp_tools = ?'); values.push(JSON.stringify(updates.missedMcpTools)); }
     if (updates.totalToolCalls !== undefined) { sets.push('total_tool_calls = ?'); values.push(updates.totalToolCalls); }
@@ -370,14 +598,6 @@ export class DevFlowDatabase {
   }
 
   listSkillExecutions(limit: number, skillName?: string): any[] {
-    // Auto-timeout stale running executions (> 30 minutes)
-    const timeoutThreshold = Date.now() - 30 * 60 * 1000;
-    this.db.prepare(`
-      UPDATE skill_executions
-      SET status = 'failed', finished_at = ?
-      WHERE status = 'running' AND started_at < ?
-    `).run(Date.now(), timeoutThreshold);
-
     let query = 'SELECT * FROM skill_executions';
     const params: any[] = [];
 
@@ -392,6 +612,7 @@ export class DevFlowDatabase {
     const rows = this.db.prepare(query).all(...params) as any[];
     return rows.map(row => ({
       executionId: row.execution_id,
+      sessionId: row.session_id,
       skillName: row.skill_name,
       startedAt: row.started_at,
       finishedAt: row.finished_at,
@@ -400,7 +621,6 @@ export class DevFlowDatabase {
       mcpToolCalls: row.mcp_tool_calls,
       directToolCalls: row.direct_tool_calls,
       subagentCount: row.subagent_count,
-      totalTokens: row.total_tokens,
       totalDuration: row.total_duration,
       mcpComplianceRate: row.mcp_compliance_rate,
     }));
@@ -411,6 +631,7 @@ export class DevFlowDatabase {
   insertToolCallEvent(params: {
     eventId: string;
     executionId: string;
+    sessionId?: string;
     timestamp: number;
     toolName: string;
     toolType: string;
@@ -418,25 +639,27 @@ export class DevFlowDatabase {
     mcpToolName?: string;
     mcpEnforced: boolean;
     mcpFallback: boolean;
+    kind?: string;
     input: unknown;
     output?: unknown;
-    tokensUsed: number;
     duration: number;
     parentToolCallId?: string;
     subagentId?: string;
     error?: string;
     blocked: boolean;
     blockReason?: string;
+    workflowRunId?: string;
   }): void {
     this.db.prepare(`
       INSERT INTO tool_call_events
-      (event_id, execution_id, timestamp, tool_name, tool_type, is_mcp_tool,
-       mcp_tool_name, mcp_enforced, mcp_fallback, input, output, tokens_used, duration,
-       parent_tool_call_id, subagent_id, error, blocked, block_reason)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      (event_id, execution_id, session_id, timestamp, tool_name, tool_type, is_mcp_tool,
+       mcp_tool_name, mcp_enforced, mcp_fallback, kind, input, output, duration,
+       parent_tool_call_id, subagent_id, error, blocked, block_reason, workflow_run_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       params.eventId,
-      params.executionId,
+      params.executionId || null,
+      params.sessionId ?? null,
       params.timestamp,
       params.toolName,
       params.toolType,
@@ -444,15 +667,16 @@ export class DevFlowDatabase {
       params.mcpToolName || null,
       params.mcpEnforced ? 1 : 0,
       params.mcpFallback ? 1 : 0,
+      params.kind ?? 'tool_use',
       JSON.stringify(params.input) ?? null,
       params.output ? JSON.stringify(params.output) : null,
-      params.tokensUsed,
       params.duration,
       params.parentToolCallId || null,
       params.subagentId || null,
       params.error || null,
       params.blocked ? 1 : 0,
       params.blockReason || null,
+      params.workflowRunId || null,
     );
 
     // Update execution summary counters
@@ -479,6 +703,7 @@ export class DevFlowDatabase {
     return rows.map(row => ({
       eventId: row.event_id,
       executionId: row.execution_id,
+      sessionId: row.session_id,
       timestamp: row.timestamp,
       toolName: row.tool_name,
       toolType: row.tool_type,
@@ -486,9 +711,9 @@ export class DevFlowDatabase {
       mcpToolName: row.mcp_tool_name,
       mcpEnforced: row.mcp_enforced === 1,
       mcpFallback: row.mcp_fallback === 1,
+      kind: row.kind,
       input: row.input ? JSON.parse(row.input) : null,
       output: row.output ? JSON.parse(row.output) : null,
-      tokensUsed: row.tokens_used,
       duration: row.duration,
       parentToolCallId: row.parent_tool_call_id,
       subagentId: row.subagent_id,
@@ -498,7 +723,7 @@ export class DevFlowDatabase {
     }));
   }
 
-  updateToolCallEvent(eventId: string, updates: { output?: string; error?: string }): void {
+  updateToolCallEvent(eventId: string, updates: { output?: string; error?: string; duration?: number }): void {
     const sets: string[] = [];
     const values: any[] = [];
 
@@ -510,6 +735,10 @@ export class DevFlowDatabase {
       sets.push('error = ?');
       values.push(updates.error);
     }
+    if (updates.duration !== undefined) {
+      sets.push('duration = ?');
+      values.push(updates.duration);
+    }
 
     if (sets.length > 0) {
       values.push(eventId);
@@ -569,6 +798,145 @@ export class DevFlowDatabase {
     return { overall, bySkill, missedTools };
   }
 
+  cleanupStaleRecords(): void {
+    const cutoff = Date.now() - 30 * 60 * 1000;
+    try {
+      this.db.prepare(
+        `UPDATE skill_executions SET status = 'failed', finished_at = ? WHERE status = 'running' AND started_at < ?`
+      ).run(Date.now(), cutoff);
+      this.db.prepare(
+        `UPDATE sessions SET status = 'failed', finished_at = ? WHERE status = 'running' AND started_at < ?`
+      ).run(Date.now(), cutoff);
+    } catch { /* best-effort */ }
+  }
+
+  insertToolMetric(metric: {
+    id: string;
+    toolCallEventId: string;
+    sessionId: string;
+    toolName: string;
+    query?: string;
+    status?: string;
+    resultCount?: number;
+    resultSizeBytes?: number;
+    latencyMs?: number;
+    engine?: string;
+    accuracyQueryId?: string;
+    metadata?: string;
+    createdAt: number;
+  }): void {
+    this.db.prepare(`
+      INSERT OR REPLACE INTO tool_metrics (id, tool_call_event_id, session_id, tool_name, query, status, result_count, result_size_bytes, latency_ms, engine, accuracy_query_id, metadata, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      metric.id, metric.toolCallEventId, metric.sessionId, metric.toolName,
+      metric.query ?? null, metric.status ?? 'success',
+      metric.resultCount ?? 0, metric.resultSizeBytes ?? 0,
+      metric.latencyMs ?? 0, metric.engine ?? null,
+      metric.accuracyQueryId ?? null, metric.metadata ?? null, metric.createdAt,
+    );
+  }
+
+  getToolMetrics(sessionId?: string, toolName?: string, limit = 100, offset = 0): any[] {
+    let sql = 'SELECT * FROM tool_metrics WHERE 1=1';
+    const params: any[] = [];
+    if (sessionId) { sql += ' AND session_id = ?'; params.push(sessionId); }
+    if (toolName) { sql += ' AND tool_name = ?'; params.push(toolName); }
+    sql += ' ORDER BY created_at DESC LIMIT ? OFFSET ?';
+    params.push(limit, offset);
+    return (this.db.prepare(sql).all(...params) as any[]);
+  }
+
+  getToolMetricsSummary(days = 7): any[] {
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const rows = (this.db.prepare(`
+      SELECT tool_name, COUNT(*) as call_count,
+        SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as success_count,
+        SUM(CASE WHEN result_count = 0 THEN 1 ELSE 0 END) as empty_count,
+        AVG(result_count) as avg_results,
+        AVG(latency_ms) as avg_latency
+      FROM tool_metrics
+      WHERE created_at >= ?
+      GROUP BY tool_name
+      ORDER BY call_count DESC
+    `).all(cutoff) as any[]);
+    return rows.map((r: any) => ({
+      toolName: r.tool_name,
+      callCount: r.call_count,
+      successRate: r.call_count > 0 ? Math.round((r.success_count / r.call_count) * 10000) / 100 : 0,
+      emptyRate: r.call_count > 0 ? Math.round((r.empty_count / r.call_count) * 10000) / 100 : 0,
+      avgResults: Math.round(r.avg_results * 10) / 10,
+      avgLatency: Math.round(r.avg_latency),
+    }));
+  }
+
+  // ---- Accuracy Queries ----
+
+  insertAccuracyQuery(q: {
+    id: string; sessionId: string; engine: string; query: string;
+    topKResults: string; selectedIds?: string; createdAt: number;
+  }): void {
+    this.db.prepare(`
+      INSERT INTO accuracy_queries (id, session_id, engine, query, top_k_results, selected_ids, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(q.id, q.sessionId, q.engine, q.query, q.topKResults, q.selectedIds ?? null, q.createdAt);
+  }
+
+  getAccuracyQueries(options: { engine?: string; status?: string; limit?: number; offset?: number }): any[] {
+    let sql = 'SELECT * FROM accuracy_queries WHERE 1=1';
+    const params: any[] = [];
+    if (options.engine) { sql += ' AND engine = ?'; params.push(options.engine); }
+    if (options.status === 'annotated') sql += ' AND relevance_feedback IS NOT NULL';
+    if (options.status === 'unannotated') sql += ' AND relevance_feedback IS NULL';
+    sql += ' ORDER BY created_at DESC LIMIT ? OFFSET ?';
+    params.push(options.limit ?? 50, options.offset ?? 0);
+    const rows = (this.db.prepare(sql).all(...params) as any[]);
+    return rows.map((r: any) => ({
+      id: r.id, sessionId: r.session_id, engine: r.engine, query: r.query,
+      topKResults: r.top_k_results ? JSON.parse(r.top_k_results) : [],
+      selectedIds: r.selected_ids ? JSON.parse(r.selected_ids) : null,
+      relevanceFeedback: r.relevance_feedback,
+      annotatorNote: r.annotator_note,
+      annotatedAt: r.annotated_at,
+      createdAt: r.created_at,
+    }));
+  }
+
+  updateAccuracyFeedback(id: string, feedback: { relevance: 'hit' | 'partial' | 'miss'; note?: string }): void {
+    this.db.prepare(
+      'UPDATE accuracy_queries SET relevance_feedback = ?, annotator_note = ?, annotated_at = ? WHERE id = ?'
+    ).run(feedback.relevance, feedback.note ?? null, Date.now(), id);
+  }
+
+  getAccuracyStats(engine?: string, since?: number): any {
+    let where = 'WHERE 1=1';
+    const params: any[] = [];
+    if (engine) { where += ' AND engine = ?'; params.push(engine); }
+    if (since) { where += ' AND created_at >= ?'; params.push(since); }
+
+    const totalQueries = (this.db.prepare(`SELECT COUNT(*) as c FROM accuracy_queries ${where}`).get(...params) as any)?.c ?? 0;
+    const annotatedQueries = (this.db.prepare(
+      `SELECT COUNT(*) as c FROM accuracy_queries ${where} AND relevance_feedback IS NOT NULL`
+    ).get(...params) as any)?.c ?? 0;
+    const hitCount = annotatedQueries > 0
+      ? ((this.db.prepare(
+          `SELECT COUNT(*) as c FROM accuracy_queries ${where} AND relevance_feedback = 'hit'`
+        ).get(...params) as any)?.c ?? 0)
+      : 0;
+    const hitRate = annotatedQueries > 0 ? hitCount / annotatedQueries : null;
+
+    return { totalQueries, annotatedQueries, hitRate };
+  }
+
+  // Convenience methods for raw SQL queries (used by AutoChecker)
+  all(sql: string, ...params: unknown[]): unknown[] {
+    return this.db.prepare(sql).all(...params);
+  }
+
+  get(sql: string, ...params: unknown[]): unknown {
+    return this.db.prepare(sql).get(...params);
+  }
+
   close(): void {
     this.db.close();
   }