@winspan/claude-forge 8.41.0 → 8.50.6

package/src/core/queue/index.ts

@@ -0,0 +1,193 @@
+/**
+ * Hook failure buffer queue — at-least-once event delivery
+ *
+ * When the daemon is not reachable (socket missing / nc fail), hook scripts
+ * write the raw event JSON to a per-file queue on disk. On the next daemon
+ * startup, `replayQueue` scans the directory and replays every file into
+ * SQLiteStorage.
+ *
+ * Design decisions:
+ * - One file per event: avoids concurrent-write collisions across 5 hook processes
+ * - File name: <iso-timestamp>-<event_id>.json  (sortable + unique)
+ * - Dedup: events table PRIMARY KEY; UNIQUE constraint error → silently skip
+ * - Capacity: MAX_FILES=500, TTL=7d; overflow → drop oldest; expired → dead-letter
+ */
+
+import { mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import type { SQLiteStorage } from '../storage/sqlite.js';
+import type { ForgeEvent } from '../types.js';
+import { logger } from '../utils/logger.js';
+
+// ── Constants ──────────────────────────────────────────────────────────────
+const FORGE_DIR = join(homedir(), '.claude-forge');
+export const QUEUE_DIR = join(FORGE_DIR, 'queue');
+export const DEAD_DIR = join(FORGE_DIR, 'queue', 'dead');
+export const MAX_FILES = 500;
+export const TTL_DAYS = 7;
+
+const TTL_MS = TTL_DAYS * 24 * 60 * 60 * 1000;
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function ensureDirs(): void {
+  mkdirSync(QUEUE_DIR, { recursive: true });
+  mkdirSync(DEAD_DIR, { recursive: true });
+}
+
+/** List all *.json queue files, sorted oldest-first (by filename). */
+function listQueueFiles(): string[] {
+  try {
+    return readdirSync(QUEUE_DIR)
+      .filter((f) => f.endsWith('.json'))
+      .sort(); // ISO timestamp prefix → lexicographic = chronological
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * pruneQueue — enforce MAX_FILES cap.
+ * Deletes the oldest files (smallest filename) until count < MAX_FILES.
+ * Called by enqueueEvent before writing a new file.
+ */
+export function pruneQueue(): void {
+  const files = listQueueFiles();
+  if (files.length < MAX_FILES) return;
+
+  const toDelete = files.slice(0, files.length - MAX_FILES + 1);
+  for (const f of toDelete) {
+    try {
+      rmSync(join(QUEUE_DIR, f));
+    } catch (err) {
+      logger.warn(`[Queue] Failed to prune ${f}: ${err}`);
+    }
+  }
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * enqueueEvent — write a single event to the queue directory.
+ *
+ * Designed to be called synchronously from hook scripts via a bash child
+ * process. This TypeScript version is used by tests; the bash implementation
+ * mirrors the same file-naming convention.
+ */
+export function enqueueEvent(event: ForgeEvent): void {
+  ensureDirs();
+  pruneQueue();
+
+  const eventId = event.event_id ?? randomUUID();
+  const ts = new Date().toISOString().replace(/[:.]/g, '-').replace('Z', 'Z');
+  const filename = `${ts}-${eventId}.json`;
+  const filePath = join(QUEUE_DIR, filename);
+
+  writeFileSync(filePath, JSON.stringify({ ...event, event_id: eventId }), 'utf8');
+}
+
+export interface ReplayResult {
+  replayed: number;
+  skipped: number;
+  dead: number;
+}
+
+/**
+ * replayQueue — called by daemon after socket starts listening.
+ *
+ * For each *.json in QUEUE_DIR:
+ *   - If mtime > TTL → move to dead-letter
+ *   - Parse JSON → storage.writeEvent()
+ *     - Success → rm file, replayed++
+ *     - UNIQUE constraint → rm file, skipped++ (already in DB)
+ *     - Other error → move to dead-letter, dead++
+ *   - Bad JSON → move to dead-letter, dead++
+ */
+export async function replayQueue(storage: SQLiteStorage): Promise<ReplayResult> {
+  ensureDirs();
+
+  const files = listQueueFiles();
+  if (files.length === 0) {
+    return { replayed: 0, skipped: 0, dead: 0 };
+  }
+
+  logger.info(`[Queue] Replaying ${files.length} queued event(s)…`);
+
+  let replayed = 0;
+  let skipped = 0;
+  let dead = 0;
+  const now = Date.now();
+
+  for (const filename of files) {
+    const filePath = join(QUEUE_DIR, filename);
+
+    // ── TTL check ──────────────────────────────────────────────────────────
+    try {
+      const stat = statSync(filePath);
+      if (now - stat.mtimeMs > TTL_MS) {
+        moveToDeadLetter(filePath, filename);
+        dead++;
+        logger.warn(`[Queue] TTL expired, dead-lettered: ${filename}`);
+        continue;
+      }
+    } catch (err) {
+      logger.warn(`[Queue] Cannot stat ${filename}, skipping: ${err}`);
+      continue;
+    }
+
+    // ── Read + parse ───────────────────────────────────────────────────────
+    let event: ForgeEvent;
+    try {
+      const raw = await readFile(filePath, 'utf8');
+      event = JSON.parse(raw) as ForgeEvent;
+    } catch {
+      moveToDeadLetter(filePath, filename);
+      dead++;
+      logger.warn(`[Queue] Bad JSON, dead-lettered: ${filename}`);
+      continue;
+    }
+
+    // ── Write to storage ───────────────────────────────────────────────────
+    try {
+      storage.writeEvent(event);
+      rmSync(filePath);
+      replayed++;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (isUniqueConstraintError(msg)) {
+        // Already in DB — remove the queue file silently
+        try { rmSync(filePath); } catch { /* ignore */ }
+        skipped++;
+      } else {
+        moveToDeadLetter(filePath, filename);
+        dead++;
+        logger.warn(`[Queue] writeEvent failed, dead-lettered ${filename}: ${msg}`);
+      }
+    }
+  }
+
+  return { replayed, skipped, dead };
+}
+
+// ── Internal helpers ───────────────────────────────────────────────────────
+
+function moveToDeadLetter(filePath: string, filename: string): void {
+  try {
+    mkdirSync(DEAD_DIR, { recursive: true });
+    renameSync(filePath, join(DEAD_DIR, filename));
+  } catch (err) {
+    logger.warn(`[Queue] Failed to move ${filename} to dead-letter: ${err}`);
+    try { rmSync(filePath); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Detect SQLite UNIQUE constraint violations.
+ * better-sqlite3 throws: "UNIQUE constraint failed: events.event_id"
+ */
+function isUniqueConstraintError(message: string): boolean {
+  return message.includes('UNIQUE constraint failed');
+}

package/src/core/storage/base.ts

@@ -0,0 +1,226 @@
+/**
+ * SQLiteBase — 数据库初始化、schema、迁移、辅助
+ *
+ * 拆分自 sqlite.ts。仅负责：
+ * - 打开数据库连接 + 配置 PRAGMA
+ * - 加载 schema.sql 或 inline fallback
+ * - 增量迁移（hasColumn / addColumnIfMissing）
+ * - 一次性 sessions 回填
+ *
+ * 不涉及业务读写。所有业务读写由 *Operations 类组合 db 实例实现。
+ */
+
+import Database from 'better-sqlite3';
+import { readFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DATABASE } from '../constants.js';
+import { logger } from '../utils/logger.js';
+
+export class SQLiteBase {
+  protected db: Database.Database;
+  protected dbPath: string;
+
+  constructor(dbPath: string) {
+    this.dbPath = dbPath;
+
+    const dir = dirname(dbPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    this.db = new Database(dbPath);
+
+    // WAL mode optimization for better concurrency
+    this.db.pragma('journal_mode = WAL');
+    this.db.pragma('synchronous = NORMAL');
+    this.db.pragma('wal_autocheckpoint = 1000'); // Increased from 100 for better performance
+    this.db.pragma(`cache_size = ${DATABASE.CACHE_SIZE}`);
+    this.db.pragma(`busy_timeout = ${DATABASE.BUSY_TIMEOUT}`);
+
+    // Additional performance optimizations
+    this.db.pragma('temp_store = MEMORY'); // Store temp tables in memory
+    this.db.pragma('mmap_size = 30000000000'); // 30GB memory-mapped I/O
+    this.db.pragma('page_size = 4096'); // Optimal page size for most systems
+
+    this.initSchema();
+    this.runMigrations();
+  }
+
+  private initSchema(): void {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const schemaPath = join(thisDir, 'schema.sql');
+
+    if (existsSync(schemaPath)) {
+      const schema = readFileSync(schemaPath, 'utf-8');
+      this.db.exec(schema);
+    } else {
+      // Inline fallback — events table only
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS events (
+          event_id TEXT PRIMARY KEY, session_id TEXT NOT NULL,
+          project_path TEXT NOT NULL, timestamp TEXT NOT NULL,
+          hook_type TEXT NOT NULL, tool_name TEXT, tool_input TEXT,
+          tool_output TEXT, user_prompt TEXT, ai_response TEXT,
+          distilled INTEGER DEFAULT 0, created_at TEXT DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id);
+        CREATE INDEX IF NOT EXISTS idx_events_project ON events(project_path);
+        CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp DESC);
+        CREATE INDEX IF NOT EXISTS idx_events_distilled ON events(distilled);
+      `);
+    }
+  }
+
+  protected hasColumn(table: string, column: string): boolean {
+    try {
+      const rows = this.db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+      return rows.some(r => r.name === column);
+    } catch {
+      return false;
+    }
+  }
+
+  protected addColumnIfMissing(table: string, column: string, definition: string): void {
+    if (!this.hasColumn(table, column)) {
+      try {
+        this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+        logger.info(`[SQLiteStorage] migration: added ${table}.${column}`);
+      } catch (err) {
+        logger.warn(`[SQLiteStorage] migration: ALTER ${table} ADD ${column} failed: ${err}`);
+      }
+    }
+  }
+
+  /**
+   * Incremental schema migrations. Kept idempotent so daemon restarts are safe.
+   */
+  private runMigrations(): void {
+    this.addColumnIfMissing('sessions', 'first_prompt', 'TEXT');
+
+    this.addColumnIfMissing('routing_events', 'skill_confidence', 'REAL');
+    this.addColumnIfMissing('routing_events', 'skill_source', 'TEXT');
+
+    this.addColumnIfMissing('skill_invocations', 'workflow', 'TEXT');
+    this.addColumnIfMissing('skill_invocations', 'phase', 'TEXT');
+    this.addColumnIfMissing('skill_invocations', 'feature_slug', 'TEXT');
+    this.addColumnIfMissing('skill_invocations', 'artifact_path', 'TEXT');
+
+    try {
+      this.db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_skill_invocations_workflow ON skill_invocations(workflow, phase);
+         CREATE INDEX IF NOT EXISTS idx_skill_invocations_feature ON skill_invocations(feature_slug);`,
+      );
+    } catch (err) {
+      logger.warn(`[SQLiteStorage] migration: create skill_invocations workflow indexes failed: ${err}`);
+    }
+
+    try {
+      this.db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time DESC)');
+    } catch (err) {
+      logger.warn(`[SQLiteStorage] migration: create idx_sessions_start_time failed: ${err}`);
+    }
+
+    // Composite indexes for high-frequency session-scoped queries (idempotent)
+    try {
+      this.db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_events_session_ts ON events(session_id, timestamp DESC);
+        CREATE INDEX IF NOT EXISTS idx_routing_events_session_ts ON routing_events(session_id, ts DESC);
+        CREATE INDEX IF NOT EXISTS idx_skill_invocations_session_ts ON skill_invocations(session_id, timestamp DESC);
+      `);
+    } catch (err) {
+      logger.warn(`[SQLiteStorage] migration: create composite indexes failed: ${err}`);
+    }
+
+    // Phase 1 Refactor: Additional performance indexes (idempotent)
+    try {
+      this.db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_routing_events_obeyed_ts ON routing_events(obeyed, ts DESC);
+        CREATE INDEX IF NOT EXISTS idx_events_session_hook ON events(session_id, hook_type, timestamp DESC);
+        CREATE INDEX IF NOT EXISTS idx_injections_session_handler ON injections(session_id, source_handler);
+      `);
+      logger.info('[SQLiteStorage] Phase 1 performance indexes created');
+    } catch (err) {
+      logger.warn(`[SQLiteStorage] migration: create Phase 1 performance indexes failed: ${err}`);
+    }
+
+    this.backfillSessionsIfNeeded();
+
+    const deprecatedTables = [
+      'quality_issues', 'distill_results', 'v2_decisions',
+      'v2_tool_events', 'experiment_assignments', 'routing_rule_states',
+    ];
+    for (const table of deprecatedTables) {
+      try { this.db.exec(`DROP TABLE IF EXISTS ${table}`); } catch { /* ignore */ }
+    }
+  }
+
+  /**
+   * 将 events 表按 session_id 聚合回填到 sessions 表，仅在 sessions 尚未对齐
+   * （没有任何一行带 first_prompt）时触发。
+   */
+  private backfillSessionsIfNeeded(): void {
+    const eventsExists = this.db
+      .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='events'`)
+      .get();
+    if (!eventsExists) return;
+
+    const aggRow = this.db
+      .prepare(`SELECT COUNT(*) AS total, COUNT(first_prompt) AS with_prompt FROM sessions`)
+      .get() as { total: number; with_prompt: number };
+
+    if (aggRow.with_prompt > 0) return;
+
+    logger.info('[SQLiteStorage] backfilling sessions aggregate from events...');
+    try {
+      const backfill = this.db.transaction(() => {
+        this.db.exec(`
+          INSERT INTO sessions (
+            session_id, project_path, status, first_prompt,
+            start_time, end_time, last_event_time, event_count
+          )
+          SELECT
+            e.session_id,
+            e.project_path,
+            'active' AS status,
+            (SELECT substr(COALESCE(e2.user_prompt, json_extract(e2.tool_input, '$.user_prompt')), 1, 200)
+             FROM events e2
+             WHERE e2.session_id = e.session_id
+               AND e2.hook_type = 'UserPromptSubmit'
+               AND (e2.user_prompt IS NOT NULL OR json_extract(e2.tool_input, '$.user_prompt') IS NOT NULL)
+             ORDER BY e2.timestamp ASC LIMIT 1) AS first_prompt,
+            MIN(e.timestamp) AS start_time,
+            MAX(e.timestamp) AS end_time,
+            MAX(e.timestamp) AS last_event_time,
+            COUNT(*) AS event_count
+          FROM events e
+          GROUP BY e.session_id, e.project_path
+          ON CONFLICT(session_id) DO UPDATE SET
+            first_prompt = COALESCE(sessions.first_prompt, excluded.first_prompt),
+            end_time = MAX(COALESCE(sessions.end_time, ''), excluded.end_time),
+            last_event_time = MAX(COALESCE(sessions.last_event_time, ''), excluded.last_event_time),
+            event_count = excluded.event_count,
+            updated_at = datetime('now')
+        `);
+      });
+      backfill();
+      const migrated = this.db.prepare('SELECT COUNT(*) AS c FROM sessions').get() as { c: number };
+      logger.info(`[SQLiteStorage] backfilled ${migrated.c} sessions from events`);
+    } catch (err) {
+      logger.warn(`[SQLiteStorage] backfillSessionsIfNeeded failed: ${err}`);
+    }
+  }
+
+  getDatabase(): Database.Database {
+    return this.db;
+  }
+
+  getDbPath(): string {
+    return this.dbPath;
+  }
+
+  protected getDbSizeMb(): number {
+    if (!existsSync(this.dbPath)) return 0;
+    return statSync(this.dbPath).size / (1024 * 1024);
+  }
+}

package/src/core/storage/events.ts

@@ -0,0 +1,255 @@
+/**
+ * EventOperations — 事件读写
+ *
+ * 拆分自 sqlite.ts。负责 events 表 + 触发 sessions 聚合 upsert。
+ *
+ * 注意：
+ * - writeEvent 会 emit 'event' 事件，因此构造时需要传入 EventEmitter 实例
+ * - upsertSession 通过 emitter（即 SQLiteStorage facade）调用，以保持原版本
+ *   "monkey-patch storage.upsertSession 能拦截 writeEvent 内部调用"的行为
+ */
+
+import type Database from 'better-sqlite3';
+import { randomUUID } from 'node:crypto';
+import type { EventEmitter } from 'node:events';
+import { z } from 'zod';
+import type { ForgeEvent } from '../types.js';
+import { logger } from '../utils/logger.js';
+
+interface UpsertCapableEmitter extends EventEmitter {
+  upsertSession(event: ForgeEvent): void;
+}
+
+// Zod schema for runtime validation
+const ForgeEventSchema = z.object({
+  event_id: z.string().uuid().optional(),
+  session_id: z.string().min(1),
+  project_path: z.string().min(1),
+  timestamp: z.string().min(1),
+  hook_type: z.enum([
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PostToolUse',
+    'Stop',
+    'Notification',
+    'HistoryExport',
+  ]),
+  tool_name: z.string().optional(),
+  tool_input: z.unknown().optional(),
+  tool_output: z.unknown().optional(),
+  user_prompt: z.string().optional(),
+  ai_response: z.string().optional(),
+});
+
+const DatabaseRowSchema = z.object({
+  event_id: z.string(),
+  session_id: z.string(),
+  project_path: z.string(),
+  timestamp: z.string(),
+  hook_type: z.string(),
+  tool_name: z.union([z.string(), z.null()]),
+  tool_input: z.union([z.string(), z.null()]),
+  tool_output: z.union([z.string(), z.null()]),
+  user_prompt: z.union([z.string(), z.null()]),
+  ai_response: z.union([z.string(), z.null()]),
+});
+
+interface UpsertCapableEmitter extends EventEmitter {
+  upsertSession(event: ForgeEvent): void;
+}
+
+export class EventOperations {
+  constructor(
+    private db: Database.Database,
+    private emitter: UpsertCapableEmitter,
+  ) {}
+
+  writeEvent(event: ForgeEvent): void {
+    // Runtime validation
+    try {
+      ForgeEventSchema.parse(event);
+    } catch (err) {
+      logger.error(`[EventOperations] Invalid event data: ${err}`);
+      throw new Error(`Invalid event data: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    const eventId = event.event_id || randomUUID();
+    const stmt = this.db.prepare(`
+      INSERT INTO events (event_id, session_id, project_path, timestamp, hook_type,
+                          tool_name, tool_input, tool_output, user_prompt, ai_response, distilled)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
+    `);
+
+    try {
+      stmt.run(
+        eventId,
+        event.session_id,
+        event.project_path,
+        event.timestamp,
+        event.hook_type,
+        event.tool_name ?? null,
+        event.tool_input ? JSON.stringify(event.tool_input) : null,
+        event.tool_output ? JSON.stringify(event.tool_output) : null,
+        event.user_prompt ?? null,
+        event.ai_response ?? null,
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('UNIQUE constraint failed')) {
+        // Duplicate event_id — expected during queue replay. Caller decides how to handle.
+        logger.debug(`[EventOperations] Duplicate event_id ${eventId} (UNIQUE constraint)`);
+      } else {
+        logger.error(`[EventOperations] Failed to write event: ${err}`);
+      }
+      throw new Error(`Failed to write event: ${msg}`);
+    }
+
+    // 聚合到 sessions 表。单独 try/catch：一旦聚合失败，不能影响原事件持久化。
+    // 通过 facade 调用以保持 monkey-patch 兼容性。
+    try {
+      this.emitter.upsertSession(event);
+    } catch (err) {
+      logger.warn(`[SQLiteStorage] upsertSession failed (event still written): ${err}`);
+    }
+
+    this.emitter.emit('event', { ...event, event_id: eventId });
+  }
+
+  queryEvents(filter: {
+    session_id?: string;
+    project_path?: string;
+    hook_type?: string;
+    limit?: number;
+    offset?: number;
+  }): ForgeEvent[] {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filter.session_id) {
+      conditions.push('session_id = ?');
+      params.push(filter.session_id);
+    }
+    if (filter.project_path) {
+      conditions.push('project_path = ?');
+      params.push(filter.project_path);
+    }
+    if (filter.hook_type) {
+      conditions.push('hook_type = ?');
+      params.push(filter.hook_type);
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const limit = filter.limit ?? 1000;
+    const offset = filter.offset ?? 0;
+    const sql = `SELECT * FROM events ${where} ORDER BY timestamp DESC LIMIT ? OFFSET ?`;
+
+    params.push(limit, offset);
+    const rows = this.db.prepare(sql).all(...params) as Array<Record<string, unknown>>;
+    return rows.map((row) => this.rowToEvent(row));
+  }
+
+  countEvents(filter?: {
+    session_id?: string;
+    project_path?: string;
+    hook_type?: string;
+  }): number {
+    if (!filter || (!filter.session_id && !filter.project_path && !filter.hook_type)) {
+      const result = this.db.prepare('SELECT COUNT(*) as count FROM events').get() as { count: number };
+      return result.count;
+    }
+
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filter.session_id) {
+      conditions.push('session_id = ?');
+      params.push(filter.session_id);
+    }
+    if (filter.project_path) {
+      conditions.push('project_path = ?');
+      params.push(filter.project_path);
+    }
+    if (filter.hook_type) {
+      conditions.push('hook_type = ?');
+      params.push(filter.hook_type);
+    }
+
+    const where = `WHERE ${conditions.join(' AND ')}`;
+    const sql = `SELECT COUNT(*) as count FROM events ${where}`;
+    const result = this.db.prepare(sql).all(...params)[0] as { count: number };
+    return result.count;
+  }
+
+  /**
+   * Server-side event search with filtering.
+   * Reduces data transfer by filtering events before sending to client.
+   */
+  searchEvents(filter: {
+    session_id: string;
+    query?: string;
+    tool_name?: string;
+    hook_type?: string;
+    limit?: number;
+    offset?: number;
+  }): ForgeEvent[] {
+    const conditions: string[] = ['session_id = ?'];
+    const params: unknown[] = [filter.session_id];
+
+    if (filter.query) {
+      conditions.push('(user_prompt LIKE ? OR ai_response LIKE ? OR tool_input LIKE ?)');
+      const pattern = `%${filter.query}%`;
+      params.push(pattern, pattern, pattern);
+    }
+    if (filter.tool_name) {
+      conditions.push('tool_name = ?');
+      params.push(filter.tool_name);
+    }
+    if (filter.hook_type) {
+      conditions.push('hook_type = ?');
+      params.push(filter.hook_type);
+    }
+
+    const limit = filter.limit ?? 100;
+    const offset = filter.offset ?? 0;
+
+    const sql = `SELECT * FROM events WHERE ${conditions.join(' AND ')} ORDER BY timestamp DESC LIMIT ? OFFSET ?`;
+    params.push(limit, offset);
+    const rows = this.db.prepare(sql).all(...params) as Array<Record<string, unknown>>;
+    return rows.map((row) => this.rowToEvent(row));
+  }
+
+  rowToEvent(row: Record<string, unknown>): ForgeEvent {
+    // Runtime validation of database row
+    try {
+      const validatedRow = DatabaseRowSchema.parse(row);
+
+      return {
+        event_id: validatedRow.event_id,
+        session_id: validatedRow.session_id,
+        project_path: validatedRow.project_path,
+        timestamp: validatedRow.timestamp,
+        hook_type: validatedRow.hook_type as ForgeEvent['hook_type'],
+        tool_name: validatedRow.tool_name || undefined,
+        tool_input: validatedRow.tool_input ? JSON.parse(validatedRow.tool_input) : undefined,
+        tool_output: validatedRow.tool_output ? JSON.parse(validatedRow.tool_output) : undefined,
+        user_prompt: validatedRow.user_prompt || undefined,
+        ai_response: validatedRow.ai_response || undefined,
+      };
+    } catch (err) {
+      logger.error(`[EventOperations] Invalid database row: ${err}`);
+      // Return a safe fallback instead of throwing to prevent query failures
+      return {
+        event_id: String(row.event_id || 'unknown'),
+        session_id: String(row.session_id || 'unknown'),
+        project_path: String(row.project_path || ''),
+        timestamp: String(row.timestamp || new Date().toISOString()),
+        hook_type: 'UserPromptSubmit', // Safe default
+        tool_name: undefined,
+        tool_input: undefined,
+        tool_output: undefined,
+        user_prompt: undefined,
+        ai_response: undefined,
+      };
+    }
+  }
+}