@devflow-tools/database 0.15.0 → 0.16.0

package/src/database.ts

@@ -1,11 +1,112 @@
 import { NodeSqliteDatabase } from './node-sqlite';
 import { join, dirname } from 'path';
 import { existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+
+export interface BenchmarkReportRecord {
+  runId: string;
+  suiteId: string;
+  suiteVersion: string;
+  projectRoot: string;
+  commit: string | null;
+  createdAt: number;
+  status: 'completed';
+  tasks: unknown[];
+}
+
+export interface BenchmarkReportMetaRecord {
+  runId: string;
+  suiteId: string;
+  suiteVersion: string;
+  projectRoot: string;
+  commit: string | null;
+  taskCount: number;
+  createdAt: number;
+  status: 'completed';
+}
+
+export interface FeedbackRecord {
+  id: string;
+  projectRoot: string;
+  query: string;
+  rating: 'hit' | 'partial' | 'miss';
+  taskType?: string;
+  contextMode?: 'general' | 'task';
+  runId?: string;
+  tokenCount?: number;
+  createdAt: number;
+}
+
+export interface TelemetryFailureRecord {
+  id: string;
+  operation: string;
+  payload: unknown;
+  error: string;
+  createdAt: number;
+  resolvedAt?: number;
+}
+
+export interface GovernanceRuleRecord {
+  id: string;
+  name: string;
+  gate: 1 | 2 | 3 | 4;
+  level: 'constitutional' | 'project' | 'session';
+  condition: Record<string, unknown>;
+  action: 'deny' | 'warn' | 'allow';
+  message: string;
+  enabled: boolean;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+export interface GovernanceAuditRecord {
+  seq: number;
+  ts: number;
+  tool: string;
+  argsHash: string;
+  decision: 'allow' | 'deny' | 'warn';
+  ruleId: string | null;
+  sessionId: string;
+  prevHash: string;
+  signature: string;
+}
+
+export interface HookReceiptRecord {
+  projectRoot: string;
+  lastMcpCall?: number;
+  bypassCount?: number;
+  updatedAt: number;
+}
+
+export interface MemoryDistillCheckpointRecord {
+  id: string;
+  projectRoot: string;
+  sessionId?: string;
+  trigger: 'pre_compact' | 'session_end';
+  pendingEvents: number;
+  releasedLeases: number;
+  createdAt: number;
+}
+
+export function getGlobalDevFlowDbPath(home = homedir()): string {
+  const stateDir = process.env.DEVFLOW_STATE_DIR ?? join(home, '.devflow', 'global');
+  return join(stateDir, 'devflow.db');
+}
+
+export function openGlobalDevFlowDatabase(
+  home = homedir(),
+  options?: { busyTimeoutMs?: number },
+): DevFlowDatabase {
+  return new DevFlowDatabase(home, {
+    dbPath: getGlobalDevFlowDbPath(home),
+    busyTimeoutMs: options?.busyTimeoutMs,
+  });
+}
 
 export class DevFlowDatabase {
   private db: NodeSqliteDatabase;
 
-  constructor(projectRoot: string, opts?: { dbPath?: string }) {
+  constructor(projectRoot: string, opts?: { dbPath?: string; busyTimeoutMs?: number }) {
     let dbPath: string;
     if (opts?.dbPath) {
       const dir = dirname(opts.dbPath);
@@ -16,10 +117,10 @@ export class DevFlowDatabase {
       if (!existsSync(devflowDir)) mkdirSync(devflowDir, { recursive: true });
       dbPath = join(devflowDir, 'devflow.db');
     }
-    this.db = new NodeSqliteDatabase(dbPath);
+    this.db = new NodeSqliteDatabase(dbPath, opts?.busyTimeoutMs);
 
     this.db.exec('PRAGMA journal_mode = WAL');
-    this.db.exec('PRAGMA busy_timeout = 5000');
+    this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(opts?.busyTimeoutMs ?? 5000))}`);
     this.db.exec('PRAGMA foreign_keys = OFF');
 
     this.initializeSchema();
@@ -123,7 +224,8 @@ export class DevFlowDatabase {
         subagent_id TEXT,
         error TEXT,
         blocked INTEGER DEFAULT 0 CHECK (blocked IN (0, 1)),
-        block_reason TEXT
+        block_reason TEXT,
+        failure_category TEXT
       );
 
       CREATE INDEX IF NOT EXISTS idx_executions_skill ON skill_executions(skill_name);
@@ -151,6 +253,80 @@ export class DevFlowDatabase {
 
       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);
+
+      CREATE TABLE IF NOT EXISTS feedback (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        query TEXT NOT NULL,
+        rating TEXT NOT NULL CHECK (rating IN ('hit', 'partial', 'miss')),
+        task_type TEXT,
+        context_mode TEXT,
+        run_id TEXT,
+        token_count INTEGER DEFAULT 0,
+        created_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_feedback_project ON feedback(project_root);
+      CREATE INDEX IF NOT EXISTS idx_feedback_created ON feedback(created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS telemetry_failures (
+        id TEXT PRIMARY KEY,
+        operation TEXT NOT NULL,
+        payload TEXT,
+        error TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        resolved_at INTEGER
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_telemetry_failures_created ON telemetry_failures(created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_telemetry_failures_unresolved ON telemetry_failures(resolved_at) WHERE resolved_at IS NULL;
+
+      CREATE TABLE IF NOT EXISTS devflow_rules (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        level TEXT NOT NULL DEFAULT 'project',
+        gate INTEGER NOT NULL DEFAULT 1,
+        condition_json TEXT NOT NULL,
+        action TEXT NOT NULL DEFAULT 'warn',
+        message TEXT NOT NULL,
+        enabled INTEGER NOT NULL DEFAULT 1,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS devflow_audit_chain (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts INTEGER NOT NULL,
+        tool TEXT NOT NULL,
+        args_hash TEXT NOT NULL,
+        decision TEXT NOT NULL,
+        rule_id TEXT,
+        session_id TEXT NOT NULL,
+        prev_hash TEXT NOT NULL,
+        signature TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_devflow_audit_ts ON devflow_audit_chain(ts DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_hook_receipts (
+        project_root TEXT PRIMARY KEY,
+        last_mcp_call INTEGER,
+        bypass_count INTEGER NOT NULL DEFAULT 0,
+        updated_at INTEGER NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS devflow_memory_distill_checkpoints (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        session_id TEXT,
+        trigger TEXT NOT NULL CHECK(trigger IN ('pre_compact', 'session_end')),
+        pending_events INTEGER NOT NULL DEFAULT 0,
+        released_leases INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_distill_checkpoints_project
+        ON devflow_memory_distill_checkpoints(project_root, created_at DESC);
     `);
 
     // Migration: add session_id to skill_executions (SQLite compat — ignore if exists)
@@ -163,6 +339,11 @@ export class DevFlowDatabase {
     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 {}
+    try { this.db.exec('ALTER TABLE tool_call_events ADD COLUMN failure_category TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_rules ADD COLUMN gate INTEGER NOT NULL DEFAULT 1'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_rules ADD COLUMN updated_at INTEGER'); } catch {}
+    this.db.exec('UPDATE devflow_rules SET updated_at = created_at WHERE updated_at IS NULL');
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_devflow_rules_gate ON devflow_rules(gate, enabled)');
 
     // Migration: tool_metrics table for per-tool metrics collection
     try {
@@ -211,6 +392,28 @@ export class DevFlowDatabase {
       `);
     } catch {}
 
+    // Canonical benchmark reports live in the global DevFlow database.
+    try {
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS benchmark_reports (
+          run_id TEXT PRIMARY KEY,
+          suite_id TEXT NOT NULL,
+          suite_version TEXT NOT NULL,
+          project_root TEXT NOT NULL,
+          commit_sha TEXT,
+          task_count INTEGER NOT NULL,
+          status TEXT NOT NULL CHECK(status IN ('completed')),
+          report_json TEXT NOT NULL,
+          created_at INTEGER NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_benchmark_reports_created
+          ON benchmark_reports(created_at DESC);
+        CREATE INDEX IF NOT EXISTS idx_benchmark_reports_suite
+          ON benchmark_reports(suite_id, suite_version, created_at DESC);
+      `);
+    } catch {}
+
     // Migration: logging system views for agent queries
     try {
       this.db.exec(`
@@ -259,7 +462,7 @@ export class DevFlowDatabase {
 
   insertRun(run: any): void {
     this.db.prepare(`
-      INSERT INTO runs (id, source, tool, input, status, started_at, finished_at, token_used, metadata, created_at)
+      INSERT OR IGNORE INTO runs (id, source, tool, input, status, started_at, finished_at, token_used, metadata, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       run.id,
@@ -535,6 +738,7 @@ export class DevFlowDatabase {
       error: row.error,
       blocked: row.blocked === 1,
       blockReason: row.block_reason,
+      failureCategory: row.failure_category,
       tokensUsed: row.tokens_used ?? 0,
     }));
   }
@@ -570,6 +774,7 @@ export class DevFlowDatabase {
         error: row.error,
         blocked: row.blocked === 1,
         blockReason: row.block_reason,
+        failureCategory: row.failure_category,
         tokensUsed: row.tokens_used ?? 0,
       });
     }
@@ -588,7 +793,7 @@ export class DevFlowDatabase {
     availableMcpTools?: string[];
   }): void {
     this.db.prepare(`
-      INSERT INTO skill_executions
+      INSERT OR IGNORE INTO skill_executions
       (execution_id, session_id, skill_name, started_at, status, required_mcp_tools, available_mcp_tools)
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).run(
@@ -707,50 +912,59 @@ export class DevFlowDatabase {
     blocked: boolean;
     blockReason?: string;
     workflowRunId?: string;
-  }): void {
-    this.db.prepare(`
-      INSERT INTO tool_call_events
-      (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 || null,
-      params.sessionId ?? null,
-      params.timestamp,
-      params.toolName,
-      params.toolType,
-      params.isMcpTool ? 1 : 0,
-      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.duration,
-      params.parentToolCallId || null,
-      params.subagentId || null,
-      params.error || null,
-      params.blocked ? 1 : 0,
-      params.blockReason || null,
-      params.workflowRunId || null,
-    );
+    failureCategory?: string;
+    tokensUsed?: number;
+  }): boolean {
+    return this.db.transaction(() => {
+      const result = this.db.prepare(`
+        INSERT OR IGNORE INTO tool_call_events
+        (event_id, execution_id, session_id, timestamp, tool_name, tool_type, is_mcp_tool,
+         mcp_tool_name, mcp_enforced, mcp_fallback, kind, input, output, tokens_used, duration,
+         parent_tool_call_id, subagent_id, error, blocked, block_reason, workflow_run_id,
+         failure_category)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        params.eventId,
+        params.executionId || '',
+        params.sessionId ?? null,
+        params.timestamp,
+        params.toolName,
+        params.toolType,
+        params.isMcpTool ? 1 : 0,
+        params.mcpToolName || null,
+        params.mcpEnforced ? 1 : 0,
+        params.mcpFallback ? 1 : 0,
+        params.kind ?? 'tool_use',
+        JSON.stringify(params.input) ?? null,
+        params.output !== undefined ? JSON.stringify(params.output) : null,
+        params.tokensUsed ?? 0,
+        params.duration,
+        params.parentToolCallId || null,
+        params.subagentId || null,
+        params.error || null,
+        params.blocked ? 1 : 0,
+        params.blockReason || null,
+        params.workflowRunId || null,
+        params.failureCategory || null,
+      );
 
-    // Update execution summary counters
-    this.db.prepare(`
-      UPDATE skill_executions
-      SET total_tool_calls = total_tool_calls + 1,
-          mcp_tool_calls = mcp_tool_calls + ?,
-          direct_tool_calls = direct_tool_calls + ?,
-          subagent_count = subagent_count + ?
-      WHERE execution_id = ?
-    `).run(
-      params.isMcpTool ? 1 : 0,
-      params.isMcpTool ? 0 : 1,
-      params.toolType === 'subagent' ? 1 : 0,
-      params.executionId,
-    );
+      if (result.changes === 0) return false;
+
+      this.db.prepare(`
+        UPDATE skill_executions
+        SET total_tool_calls = total_tool_calls + 1,
+            mcp_tool_calls = mcp_tool_calls + ?,
+            direct_tool_calls = direct_tool_calls + ?,
+            subagent_count = subagent_count + ?
+        WHERE execution_id = ?
+      `).run(
+        params.isMcpTool ? 1 : 0,
+        params.isMcpTool ? 0 : 1,
+        params.toolType === 'subagent' ? 1 : 0,
+        params.executionId,
+      );
+      return true;
+    });
   }
 
   listToolCallEvents(executionId: string): any[] {
@@ -778,10 +992,11 @@ export class DevFlowDatabase {
       error: row.error,
       blocked: row.blocked === 1,
       blockReason: row.block_reason,
+      failureCategory: row.failure_category,
     }));
   }
 
-  updateToolCallEvent(eventId: string, updates: { output?: string; error?: string; duration?: number }): void {
+  updateToolCallEvent(eventId: string, updates: { output?: string; error?: string; duration?: number }): boolean {
     const sets: string[] = [];
     const values: any[] = [];
 
@@ -800,10 +1015,12 @@ export class DevFlowDatabase {
 
     if (sets.length > 0) {
       values.push(eventId);
-      this.db.prepare(
+      const result = this.db.prepare(
         `UPDATE tool_call_events SET ${sets.join(', ')} WHERE event_id = ?`
       ).run(...values);
+      return result.changes > 0;
     }
+    return false;
   }
 
   // ---- MCP Compliance ----
@@ -884,7 +1101,7 @@ export class DevFlowDatabase {
     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)
+      INSERT OR IGNORE 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,
@@ -928,6 +1145,153 @@ export class DevFlowDatabase {
     }));
   }
 
+  aggregatePendingToolMetrics(limit = 1000): number {
+    const rows = this.db.prepare(`
+      SELECT e.*
+      FROM tool_call_events e
+      LEFT JOIN tool_metrics m ON m.tool_call_event_id = e.event_id
+      WHERE m.id IS NULL AND e.output IS NOT NULL
+      ORDER BY e.timestamp ASC
+      LIMIT ?
+    `).all(limit) as any[];
+
+    let inserted = 0;
+    this.db.transaction(() => {
+      for (const row of rows) {
+        const input = parseJson(row.input);
+        const output = parseJson(row.output);
+        const toolName = row.mcp_tool_name || row.tool_name;
+        const resultCount = countTelemetryResults(output);
+        const resultSizeBytes = Buffer.byteLength(row.output ?? '', 'utf8');
+        const status = row.error || row.blocked
+          ? 'error'
+          : resultCount === 0 ? 'empty' : 'success';
+        const result = this.db.prepare(`
+          INSERT OR IGNORE INTO tool_metrics
+          (id, tool_call_event_id, session_id, tool_name, query, status, result_count,
+           result_size_bytes, latency_ms, engine, metadata, created_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          `metric:${row.event_id}`,
+          row.event_id,
+          row.session_id || '',
+          toolName,
+          deriveQuery(input),
+          status,
+          resultCount,
+          resultSizeBytes,
+          row.duration ?? 0,
+          deriveEngine(toolName),
+          JSON.stringify({ executionId: row.execution_id, kind: row.kind }),
+          row.timestamp,
+        );
+        inserted += result.changes;
+      }
+    });
+    return inserted;
+  }
+
+  // ---- Context Feedback ----
+
+  insertFeedback(feedback: FeedbackRecord): void {
+    this.db.prepare(`
+      INSERT OR IGNORE INTO feedback
+      (id, project_root, query, rating, task_type, context_mode, run_id, token_count, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      feedback.id,
+      feedback.projectRoot,
+      feedback.query,
+      feedback.rating,
+      feedback.taskType ?? null,
+      feedback.contextMode ?? null,
+      feedback.runId ?? null,
+      feedback.tokenCount ?? 0,
+      feedback.createdAt,
+    );
+  }
+
+  listFeedback(projectRoot?: string, limit = 100): FeedbackRecord[] {
+    const rows = projectRoot
+      ? this.db.prepare('SELECT * FROM feedback WHERE project_root = ? ORDER BY created_at DESC LIMIT ?').all(projectRoot, limit)
+      : this.db.prepare('SELECT * FROM feedback ORDER BY created_at DESC LIMIT ?').all(limit);
+    return (rows as any[]).map(row => ({
+      id: row.id,
+      projectRoot: row.project_root,
+      query: row.query,
+      rating: row.rating,
+      taskType: row.task_type ?? undefined,
+      contextMode: row.context_mode ?? undefined,
+      runId: row.run_id ?? undefined,
+      tokenCount: row.token_count ?? 0,
+      createdAt: row.created_at,
+    }));
+  }
+
+  getFeedbackSummary(projectRoot?: string): { total: number; hits: number; partials: number; misses: number; hitRate: number } {
+    const row = (projectRoot
+      ? this.db.prepare(`SELECT COUNT(*) total, SUM(rating = 'hit') hits, SUM(rating = 'partial') partials, SUM(rating = 'miss') misses FROM feedback WHERE project_root = ?`).get(projectRoot)
+      : this.db.prepare(`SELECT COUNT(*) total, SUM(rating = 'hit') hits, SUM(rating = 'partial') partials, SUM(rating = 'miss') misses FROM feedback`).get()) as any;
+    const total = Number(row?.total ?? 0);
+    const hits = Number(row?.hits ?? 0);
+    const partials = Number(row?.partials ?? 0);
+    const misses = Number(row?.misses ?? 0);
+    return { total, hits, partials, misses, hitRate: total > 0 ? hits / total : 0 };
+  }
+
+  // ---- Telemetry Failures ----
+
+  insertTelemetryFailure(failure: TelemetryFailureRecord): void {
+    this.db.prepare(`
+      INSERT OR IGNORE INTO telemetry_failures
+      (id, operation, payload, error, created_at, resolved_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(
+      failure.id,
+      failure.operation,
+      JSON.stringify(failure.payload) ?? null,
+      failure.error,
+      failure.createdAt,
+      failure.resolvedAt ?? null,
+    );
+  }
+
+  resolveTelemetryFailure(id: string, resolvedAt = Date.now()): void {
+    this.db.prepare('UPDATE telemetry_failures SET resolved_at = ? WHERE id = ?').run(resolvedAt, id);
+  }
+
+  listTelemetryFailures(options?: { unresolvedOnly?: boolean; limit?: number }): TelemetryFailureRecord[] {
+    const where = options?.unresolvedOnly ? 'WHERE resolved_at IS NULL' : '';
+    const rows = this.db.prepare(`SELECT * FROM telemetry_failures ${where} ORDER BY created_at DESC LIMIT ?`)
+      .all(options?.limit ?? 100) as any[];
+    return rows.map(row => ({
+      id: row.id,
+      operation: row.operation,
+      payload: parseJson(row.payload),
+      error: row.error,
+      createdAt: row.created_at,
+      resolvedAt: row.resolved_at ?? undefined,
+    }));
+  }
+
+  countTelemetryFailures(unresolvedOnly = false): number {
+    const row = this.db.prepare(`SELECT COUNT(*) count FROM telemetry_failures ${unresolvedOnly ? 'WHERE resolved_at IS NULL' : ''}`).get() as any;
+    return Number(row?.count ?? 0);
+  }
+
+  trimTelemetryFailures(maxRows = 500): number {
+    const limit = Math.max(1, Math.floor(maxRows));
+    const result = this.db.prepare(`
+      DELETE FROM telemetry_failures
+      WHERE id IN (
+        SELECT id FROM telemetry_failures
+        ORDER BY created_at DESC, id DESC
+        LIMIT -1 OFFSET ?
+      )
+    `).run(limit);
+    return Number(result.changes);
+  }
+
   // ---- Accuracy Queries ----
 
   insertAccuracyQuery(q: {
@@ -992,6 +1356,266 @@ export class DevFlowDatabase {
     return statsByEngine;
   }
 
+  // ---- Benchmark Reports ----
+
+  insertBenchmarkReport<T extends BenchmarkReportRecord>(report: T): void {
+    this.db.prepare(`
+      INSERT INTO benchmark_reports
+        (run_id, suite_id, suite_version, project_root, commit_sha, task_count, status, report_json, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(run_id) DO UPDATE SET
+        suite_id = excluded.suite_id,
+        suite_version = excluded.suite_version,
+        project_root = excluded.project_root,
+        commit_sha = excluded.commit_sha,
+        task_count = excluded.task_count,
+        status = excluded.status,
+        report_json = excluded.report_json,
+        created_at = excluded.created_at
+    `).run(
+      report.runId,
+      report.suiteId,
+      report.suiteVersion,
+      report.projectRoot,
+      report.commit,
+      report.tasks.length,
+      report.status,
+      JSON.stringify(report),
+      report.createdAt,
+    );
+  }
+
+  getBenchmarkReport<T extends BenchmarkReportRecord = BenchmarkReportRecord>(runId: string): T | null {
+    const row = this.db.prepare(
+      'SELECT report_json FROM benchmark_reports WHERE run_id = ?',
+    ).get(runId) as { report_json?: string } | undefined;
+    return row?.report_json
+      ? JSON.parse(row.report_json) as T
+      : null;
+  }
+
+  getLatestBenchmarkReport<T extends BenchmarkReportRecord = BenchmarkReportRecord>(suiteId?: string): T | null {
+    const row = (suiteId
+      ? this.db.prepare(
+        'SELECT report_json FROM benchmark_reports WHERE suite_id = ? ORDER BY created_at DESC LIMIT 1',
+      ).get(suiteId)
+      : this.db.prepare(
+        'SELECT report_json FROM benchmark_reports ORDER BY created_at DESC LIMIT 1',
+      ).get()) as { report_json?: string } | undefined;
+    return row?.report_json
+      ? JSON.parse(row.report_json) as T
+      : null;
+  }
+
+  listBenchmarkReports(limit = 50): BenchmarkReportMetaRecord[] {
+    const rows = this.db.prepare(`
+      SELECT run_id, suite_id, suite_version, project_root, commit_sha,
+             task_count, status, created_at
+      FROM benchmark_reports
+      ORDER BY created_at DESC
+      LIMIT ?
+    `).all(Math.max(1, Math.min(limit, 500))) as Array<{
+      run_id: string;
+      suite_id: string;
+      suite_version: string;
+      project_root: string;
+      commit_sha: string | null;
+      task_count: number;
+      status: 'completed';
+      created_at: number;
+    }>;
+    return rows.map((row) => ({
+      runId: row.run_id,
+      suiteId: row.suite_id,
+      suiteVersion: row.suite_version,
+      projectRoot: row.project_root,
+      commit: row.commit_sha,
+      taskCount: row.task_count,
+      createdAt: row.created_at,
+      status: row.status,
+    }));
+  }
+
+  // ---- Enforcer Governance ----
+
+  listGovernanceRules(includeDisabled = true): GovernanceRuleRecord[] {
+    const where = includeDisabled ? '' : 'WHERE enabled = 1';
+    const rows = this.db.prepare(`
+      SELECT id, name, gate, level, condition_json, action, message,
+             enabled, created_at, updated_at
+      FROM devflow_rules ${where}
+      ORDER BY gate, id
+    `).all() as any[];
+    return rows.map(row => ({
+      id: row.id,
+      name: row.name,
+      gate: row.gate,
+      level: row.level,
+      condition: parseJson(row.condition_json) as Record<string, unknown>,
+      action: row.action,
+      message: row.message,
+      enabled: row.enabled === 1,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    }));
+  }
+
+  getGovernanceRule(id: string): GovernanceRuleRecord | null {
+    return this.listGovernanceRules(true).find(rule => rule.id === id) ?? null;
+  }
+
+  upsertGovernanceRule(rule: GovernanceRuleRecord): GovernanceRuleRecord {
+    const now = Date.now();
+    this.db.prepare(`
+      INSERT INTO devflow_rules
+        (id, name, gate, level, condition_json, action, message, enabled, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        name = excluded.name,
+        gate = excluded.gate,
+        level = excluded.level,
+        condition_json = excluded.condition_json,
+        action = excluded.action,
+        message = excluded.message,
+        enabled = excluded.enabled,
+        updated_at = excluded.updated_at
+    `).run(
+      rule.id,
+      rule.name,
+      rule.gate,
+      rule.level,
+      JSON.stringify(rule.condition),
+      rule.action,
+      rule.message,
+      rule.enabled ? 1 : 0,
+      rule.createdAt ?? now,
+      now,
+    );
+    return this.getGovernanceRule(rule.id)!;
+  }
+
+  deleteGovernanceRule(id: string): boolean {
+    return this.db.prepare('DELETE FROM devflow_rules WHERE id = ?').run(id).changes > 0;
+  }
+
+  listGovernanceAudit(limit = 100, offset = 0): { items: GovernanceAuditRecord[]; total: number } {
+    const boundedLimit = Math.max(1, Math.min(limit, 500));
+    const boundedOffset = Math.max(0, offset);
+    const rows = this.db.prepare(`
+      SELECT seq, ts, tool, args_hash, decision, rule_id, session_id, prev_hash, signature
+      FROM devflow_audit_chain
+      ORDER BY seq DESC
+      LIMIT ? OFFSET ?
+    `).all(boundedLimit, boundedOffset) as any[];
+    const count = this.db.prepare('SELECT COUNT(*) AS total FROM devflow_audit_chain').get() as { total?: number } | undefined;
+    return {
+      items: rows.map(row => ({
+        seq: row.seq,
+        ts: row.ts,
+        tool: row.tool,
+        argsHash: row.args_hash,
+        decision: row.decision,
+        ruleId: row.rule_id,
+        sessionId: row.session_id,
+        prevHash: row.prev_hash,
+        signature: row.signature,
+      })),
+      total: Number(count?.total ?? 0),
+    };
+  }
+
+  // ---- Hook Lifecycle ----
+
+  getHookReceipt(projectRoot: string): HookReceiptRecord | null {
+    const row = this.db.prepare(`
+      SELECT project_root, last_mcp_call, bypass_count, updated_at
+      FROM devflow_hook_receipts WHERE project_root = ?
+    `).get(projectRoot) as any;
+    if (!row) return null;
+    return {
+      projectRoot: row.project_root,
+      lastMcpCall: row.last_mcp_call ?? undefined,
+      bypassCount: Number(row.bypass_count ?? 0),
+      updatedAt: Number(row.updated_at),
+    };
+  }
+
+  updateHookReceipt(
+    projectRoot: string,
+    updater: (current: HookReceiptRecord | null) => Omit<HookReceiptRecord, 'projectRoot' | 'updatedAt'>,
+  ): HookReceiptRecord {
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const current = this.getHookReceipt(projectRoot);
+      const next = updater(current);
+      const updatedAt = Date.now();
+      this.db.prepare(`
+        INSERT INTO devflow_hook_receipts
+          (project_root, last_mcp_call, bypass_count, updated_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT(project_root) DO UPDATE SET
+          last_mcp_call = excluded.last_mcp_call,
+          bypass_count = excluded.bypass_count,
+          updated_at = excluded.updated_at
+      `).run(
+        projectRoot,
+        next.lastMcpCall ?? null,
+        next.bypassCount ?? 0,
+        updatedAt,
+      );
+      this.db.exec('COMMIT');
+      return {
+        projectRoot,
+        lastMcpCall: next.lastMcpCall,
+        bypassCount: next.bypassCount ?? 0,
+        updatedAt,
+      };
+    } catch (error) {
+      try { this.db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  }
+
+  deleteHookReceipt(projectRoot: string): boolean {
+    return this.db.prepare('DELETE FROM devflow_hook_receipts WHERE project_root = ?')
+      .run(projectRoot).changes > 0;
+  }
+
+  recordMemoryDistillCheckpoint(checkpoint: MemoryDistillCheckpointRecord): void {
+    this.db.prepare(`
+      INSERT INTO devflow_memory_distill_checkpoints
+        (id, project_root, session_id, trigger, pending_events, released_leases, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      checkpoint.id,
+      checkpoint.projectRoot,
+      checkpoint.sessionId ?? null,
+      checkpoint.trigger,
+      checkpoint.pendingEvents,
+      checkpoint.releasedLeases,
+      checkpoint.createdAt,
+    );
+  }
+
+  listMemoryDistillCheckpoints(projectRoot: string, limit = 50): MemoryDistillCheckpointRecord[] {
+    const rows = this.db.prepare(`
+      SELECT id, project_root, session_id, trigger, pending_events, released_leases, created_at
+      FROM devflow_memory_distill_checkpoints
+      WHERE project_root = ?
+      ORDER BY created_at DESC
+      LIMIT ?
+    `).all(projectRoot, Math.max(1, Math.min(limit, 500))) as any[];
+    return rows.map(row => ({
+      id: row.id,
+      projectRoot: row.project_root,
+      sessionId: row.session_id ?? undefined,
+      trigger: row.trigger,
+      pendingEvents: Number(row.pending_events),
+      releasedLeases: Number(row.released_leases),
+      createdAt: Number(row.created_at),
+    }));
+  }
+
   // Convenience methods for raw SQL queries (used by AutoChecker)
   all(sql: string, ...params: unknown[]): unknown[] {
     return this.db.prepare(sql).all(...params);
@@ -1005,3 +1629,42 @@ export class DevFlowDatabase {
     this.db.close();
   }
 }
+
+function parseJson(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  try { return JSON.parse(value); } catch { return value; }
+}
+
+function deriveQuery(input: unknown): string | null {
+  if (!input || typeof input !== 'object') return null;
+  const record = input as Record<string, unknown>;
+  for (const key of ['query', 'task', 'prompt', 'name', 'command']) {
+    if (typeof record[key] === 'string' && record[key]) return record[key] as string;
+  }
+  return null;
+}
+
+function deriveEngine(toolName: string): string | null {
+  if (/project_context|symbol|dependency_graph|codegraph/.test(toolName)) return 'codegraph';
+  if (/knowledge|docs/.test(toolName)) return 'knowledge';
+  if (/memory/.test(toolName)) return 'memory';
+  return null;
+}
+
+function countTelemetryResults(value: unknown, depth = 0): number {
+  if (value == null || depth > 2) return 0;
+  if (Array.isArray(value)) return value.length;
+  if (typeof value !== 'object') return value === '' ? 0 : 1;
+
+  const record = value as Record<string, unknown>;
+  const unwrapped = record.data ?? record.structuredContent;
+  if (unwrapped !== undefined && unwrapped !== value) return countTelemetryResults(unwrapped, depth + 1);
+
+  let count = 0;
+  for (const key of ['files', 'results', 'result', 'memories', 'nodes', 'chunks', 'findings', 'symbols', 'keySymbols']) {
+    if (Array.isArray(record[key])) count += record[key].length;
+  }
+  if (count > 0) return count;
+  if (record.error) return 0;
+  return Object.keys(record).length > 0 ? 1 : 0;
+}