grov 0.1.0

package/dist/lib/store.js

@@ -0,0 +1,793 @@
+// SQLite store for task reasoning at ~/.grov/memory.db
+import Database from 'better-sqlite3';
+import { existsSync, mkdirSync, chmodSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+/**
+ * Escape LIKE pattern special characters to prevent SQL injection.
+ * SECURITY: Prevents wildcard injection in LIKE queries.
+ */
+function escapeLikePattern(str) {
+    return str.replace(/[%_\\]/g, '\\$&');
+}
+const GROV_DIR = join(homedir(), '.grov');
+const DB_PATH = join(GROV_DIR, 'memory.db');
+let db = null;
+// PERFORMANCE: Statement cache to avoid re-preparing frequently used queries
+const statementCache = new Map();
+/**
+ * Get a cached prepared statement or create a new one.
+ * PERFORMANCE: Avoids overhead of re-preparing the same SQL.
+ */
+function getCachedStatement(database, sql) {
+    let stmt = statementCache.get(sql);
+    if (!stmt) {
+        stmt = database.prepare(sql);
+        statementCache.set(sql, stmt);
+    }
+    return stmt;
+}
+/**
+ * Initialize the database connection and create tables
+ */
+export function initDatabase() {
+    if (db)
+        return db;
+    // Ensure .grov directory exists with secure permissions
+    if (!existsSync(GROV_DIR)) {
+        mkdirSync(GROV_DIR, { recursive: true, mode: 0o700 });
+    }
+    db = new Database(DB_PATH);
+    // Set secure file permissions on the database
+    try {
+        chmodSync(DB_PATH, 0o600);
+    }
+    catch {
+        // SECURITY: Warn user if permissions can't be set (e.g., on Windows)
+        // The database may be world-readable on some systems
+        console.warn('Warning: Could not set restrictive permissions on ~/.grov/memory.db');
+        console.warn('Please ensure the file has appropriate permissions for your system.');
+    }
+    // OPTIMIZATION: Enable WAL mode for better concurrent performance
+    db.pragma('journal_mode = WAL');
+    // Create all tables in a single transaction for efficiency
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS tasks (
+      id TEXT PRIMARY KEY,
+      project_path TEXT NOT NULL,
+      user TEXT,
+      original_query TEXT NOT NULL,
+      goal TEXT,
+      reasoning_trace JSON DEFAULT '[]',
+      files_touched JSON DEFAULT '[]',
+      status TEXT NOT NULL CHECK(status IN ('complete', 'question', 'partial', 'abandoned')),
+      linked_commit TEXT,
+      parent_task_id TEXT,
+      turn_number INTEGER,
+      tags JSON DEFAULT '[]',
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (parent_task_id) REFERENCES tasks(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_project ON tasks(project_path);
+    CREATE INDEX IF NOT EXISTS idx_status ON tasks(status);
+    CREATE INDEX IF NOT EXISTS idx_created ON tasks(created_at);
+  `);
+    // Create session_states table (temporary per-session tracking)
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS session_states (
+      session_id TEXT PRIMARY KEY,
+      user_id TEXT,
+      project_path TEXT NOT NULL,
+      original_goal TEXT,
+      actions_taken JSON DEFAULT '[]',
+      files_explored JSON DEFAULT '[]',
+      current_intent TEXT,
+      drift_warnings JSON DEFAULT '[]',
+      start_time TEXT NOT NULL,
+      last_update TEXT NOT NULL,
+      status TEXT DEFAULT 'active' CHECK(status IN ('active', 'completed', 'abandoned'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_session_project ON session_states(project_path);
+    CREATE INDEX IF NOT EXISTS idx_session_status ON session_states(status);
+  `);
+    // Create file_reasoning table (file-level reasoning with anchoring)
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS file_reasoning (
+      id TEXT PRIMARY KEY,
+      task_id TEXT,
+      file_path TEXT NOT NULL,
+      anchor TEXT,
+      line_start INTEGER,
+      line_end INTEGER,
+      code_hash TEXT,
+      change_type TEXT CHECK(change_type IN ('read', 'write', 'edit', 'create', 'delete')),
+      reasoning TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (task_id) REFERENCES tasks(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_file_task ON file_reasoning(task_id);
+    CREATE INDEX IF NOT EXISTS idx_file_path ON file_reasoning(file_path);
+    -- PERFORMANCE: Composite index for common query pattern (file_path + ORDER BY created_at)
+    CREATE INDEX IF NOT EXISTS idx_file_path_created ON file_reasoning(file_path, created_at DESC);
+  `);
+    // Migration: Add drift detection columns to session_states (safe to run multiple times)
+    const columns = db.pragma('table_info(session_states)');
+    const existingColumns = new Set(columns.map(c => c.name));
+    if (!existingColumns.has('expected_scope')) {
+        db.exec(`ALTER TABLE session_states ADD COLUMN expected_scope JSON DEFAULT '[]'`);
+    }
+    if (!existingColumns.has('constraints')) {
+        db.exec(`ALTER TABLE session_states ADD COLUMN constraints JSON DEFAULT '[]'`);
+    }
+    if (!existingColumns.has('success_criteria')) {
+        db.exec(`ALTER TABLE session_states ADD COLUMN success_criteria JSON DEFAULT '[]'`);
+    }
+    if (!existingColumns.has('keywords')) {
+        db.exec(`ALTER TABLE session_states ADD COLUMN keywords JSON DEFAULT '[]'`);
+    }
+    if (!existingColumns.has('last_drift_score')) {
+        db.exec(`ALTER TABLE session_states ADD COLUMN last_drift_score INTEGER`);
+    }
+    if (!existingColumns.has('escalation_count')) {
+        db.exec(`ALTER TABLE session_states ADD COLUMN escalation_count INTEGER DEFAULT 0`);
+    }
+    if (!existingColumns.has('pending_recovery_plan')) {
+        db.exec(`ALTER TABLE session_states ADD COLUMN pending_recovery_plan JSON`);
+    }
+    if (!existingColumns.has('drift_history')) {
+        db.exec(`ALTER TABLE session_states ADD COLUMN drift_history JSON DEFAULT '[]'`);
+    }
+    if (!existingColumns.has('last_checked_at')) {
+        db.exec(`ALTER TABLE session_states ADD COLUMN last_checked_at INTEGER DEFAULT 0`);
+    }
+    // Create steps table (Claude's actions for drift detection)
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS steps (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      action_type TEXT NOT NULL,
+      files JSON DEFAULT '[]',
+      folders JSON DEFAULT '[]',
+      command TEXT,
+      reasoning TEXT,
+      drift_score INTEGER,
+      is_key_decision BOOLEAN DEFAULT 0,
+      keywords JSON DEFAULT '[]',
+      timestamp INTEGER NOT NULL,
+      FOREIGN KEY (session_id) REFERENCES session_states(session_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_steps_session ON steps(session_id);
+    CREATE INDEX IF NOT EXISTS idx_steps_timestamp ON steps(timestamp);
+  `);
+    return db;
+}
+/**
+ * Close the database connection
+ */
+export function closeDatabase() {
+    if (db) {
+        db.close();
+        db = null;
+        // PERFORMANCE: Clear statement cache when database is closed
+        statementCache.clear();
+    }
+}
+/**
+ * Create a new task
+ */
+export function createTask(input) {
+    const database = initDatabase();
+    const task = {
+        id: randomUUID(),
+        project_path: input.project_path,
+        user: input.user,
+        original_query: input.original_query,
+        goal: input.goal,
+        reasoning_trace: input.reasoning_trace || [],
+        files_touched: input.files_touched || [],
+        status: input.status,
+        linked_commit: input.linked_commit,
+        parent_task_id: input.parent_task_id,
+        turn_number: input.turn_number,
+        tags: input.tags || [],
+        created_at: new Date().toISOString()
+    };
+    const stmt = database.prepare(`
+    INSERT INTO tasks (
+      id, project_path, user, original_query, goal,
+      reasoning_trace, files_touched, status, linked_commit,
+      parent_task_id, turn_number, tags, created_at
+    ) VALUES (
+      ?, ?, ?, ?, ?,
+      ?, ?, ?, ?,
+      ?, ?, ?, ?
+    )
+  `);
+    stmt.run(task.id, task.project_path, task.user || null, task.original_query, task.goal || null, JSON.stringify(task.reasoning_trace), JSON.stringify(task.files_touched), task.status, task.linked_commit || null, task.parent_task_id || null, task.turn_number || null, JSON.stringify(task.tags), task.created_at);
+    return task;
+}
+/**
+ * Get tasks for a project
+ */
+export function getTasksForProject(projectPath, options = {}) {
+    const database = initDatabase();
+    let sql = 'SELECT * FROM tasks WHERE project_path = ?';
+    const params = [projectPath];
+    if (options.status) {
+        sql += ' AND status = ?';
+        params.push(options.status);
+    }
+    sql += ' ORDER BY created_at DESC';
+    if (options.limit) {
+        sql += ' LIMIT ?';
+        params.push(options.limit);
+    }
+    const stmt = database.prepare(sql);
+    const rows = stmt.all(...params);
+    return rows.map(rowToTask);
+}
+/**
+ * Get tasks that touched specific files.
+ * SECURITY: Uses json_each for proper array handling and escaped LIKE patterns.
+ */
+// SECURITY: Maximum files per query to prevent SQL DoS
+const MAX_FILES_PER_QUERY = 100;
+export function getTasksByFiles(projectPath, files, options = {}) {
+    const database = initDatabase();
+    if (files.length === 0) {
+        return [];
+    }
+    // SECURITY: Limit file count to prevent SQL DoS via massive query generation
+    const limitedFiles = files.length > MAX_FILES_PER_QUERY
+        ? files.slice(0, MAX_FILES_PER_QUERY)
+        : files;
+    // Use json_each for proper array iteration with escaped LIKE patterns
+    const fileConditions = limitedFiles.map(() => "EXISTS (SELECT 1 FROM json_each(files_touched) WHERE value LIKE ? ESCAPE '\\')").join(' OR ');
+    let sql = `SELECT * FROM tasks WHERE project_path = ? AND (${fileConditions})`;
+    // Escape LIKE special characters to prevent injection
+    const params = [
+        projectPath,
+        ...limitedFiles.map(f => `%${escapeLikePattern(f)}%`)
+    ];
+    if (options.status) {
+        sql += ' AND status = ?';
+        params.push(options.status);
+    }
+    sql += ' ORDER BY created_at DESC';
+    if (options.limit) {
+        sql += ' LIMIT ?';
+        params.push(options.limit);
+    }
+    const stmt = database.prepare(sql);
+    const rows = stmt.all(...params);
+    return rows.map(rowToTask);
+}
+/**
+ * Get a task by ID
+ */
+export function getTaskById(id) {
+    const database = initDatabase();
+    const stmt = database.prepare('SELECT * FROM tasks WHERE id = ?');
+    const row = stmt.get(id);
+    return row ? rowToTask(row) : null;
+}
+/**
+ * Update a task's status
+ */
+export function updateTaskStatus(id, status) {
+    const database = initDatabase();
+    const stmt = database.prepare('UPDATE tasks SET status = ? WHERE id = ?');
+    stmt.run(status, id);
+}
+/**
+ * Get task count for a project
+ */
+export function getTaskCount(projectPath) {
+    const database = initDatabase();
+    const stmt = database.prepare('SELECT COUNT(*) as count FROM tasks WHERE project_path = ?');
+    const row = stmt.get(projectPath);
+    return row?.count ?? 0;
+}
+/**
+ * Safely parse JSON with fallback to empty array.
+ */
+function safeJsonParse(value, fallback) {
+    if (typeof value !== 'string' || !value) {
+        return fallback;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Convert database row to Task object
+ */
+function rowToTask(row) {
+    return {
+        id: row.id,
+        project_path: row.project_path,
+        user: row.user,
+        original_query: row.original_query,
+        goal: row.goal,
+        reasoning_trace: safeJsonParse(row.reasoning_trace, []),
+        files_touched: safeJsonParse(row.files_touched, []),
+        status: row.status,
+        linked_commit: row.linked_commit,
+        parent_task_id: row.parent_task_id,
+        turn_number: row.turn_number,
+        tags: safeJsonParse(row.tags, []),
+        created_at: row.created_at
+    };
+}
+// ============================================
+// SESSION STATE CRUD OPERATIONS
+// ============================================
+/**
+ * Create a new session state.
+ * FIXED: Uses INSERT OR IGNORE to handle race conditions safely.
+ */
+export function createSessionState(input) {
+    const database = initDatabase();
+    const now = new Date().toISOString();
+    const sessionState = {
+        session_id: input.session_id,
+        user_id: input.user_id,
+        project_path: input.project_path,
+        original_goal: input.original_goal,
+        actions_taken: [],
+        files_explored: [],
+        current_intent: undefined,
+        drift_warnings: [],
+        start_time: now,
+        last_update: now,
+        status: 'active',
+        // Drift detection fields
+        expected_scope: input.expected_scope || [],
+        constraints: input.constraints || [],
+        success_criteria: input.success_criteria || [],
+        keywords: input.keywords || [],
+        // Drift tracking fields
+        last_drift_score: undefined,
+        escalation_count: 0,
+        pending_recovery_plan: undefined,
+        drift_history: [],
+        // Action tracking
+        last_checked_at: 0
+    };
+    // Use INSERT OR IGNORE to safely handle race conditions where
+    // multiple processes might try to create the same session
+    const stmt = database.prepare(`
+    INSERT OR IGNORE INTO session_states (
+      session_id, user_id, project_path, original_goal,
+      actions_taken, files_explored, current_intent, drift_warnings,
+      start_time, last_update, status,
+      expected_scope, constraints, success_criteria, keywords,
+      last_drift_score, escalation_count, pending_recovery_plan, drift_history,
+      last_checked_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    stmt.run(sessionState.session_id, sessionState.user_id || null, sessionState.project_path, sessionState.original_goal || null, JSON.stringify(sessionState.actions_taken), JSON.stringify(sessionState.files_explored), sessionState.current_intent || null, JSON.stringify(sessionState.drift_warnings), sessionState.start_time, sessionState.last_update, sessionState.status, JSON.stringify(sessionState.expected_scope), JSON.stringify(sessionState.constraints), JSON.stringify(sessionState.success_criteria), JSON.stringify(sessionState.keywords), sessionState.last_drift_score || null, sessionState.escalation_count, sessionState.pending_recovery_plan ? JSON.stringify(sessionState.pending_recovery_plan) : null, JSON.stringify(sessionState.drift_history), sessionState.last_checked_at);
+    return sessionState;
+}
+/**
+ * Get a session state by ID
+ */
+export function getSessionState(sessionId) {
+    const database = initDatabase();
+    const stmt = database.prepare('SELECT * FROM session_states WHERE session_id = ?');
+    const row = stmt.get(sessionId);
+    return row ? rowToSessionState(row) : null;
+}
+/**
+ * Update a session state.
+ * SECURITY: Uses transaction for atomic updates to prevent race conditions.
+ */
+export function updateSessionState(sessionId, updates) {
+    const database = initDatabase();
+    const setClauses = [];
+    const params = [];
+    if (updates.user_id !== undefined) {
+        setClauses.push('user_id = ?');
+        params.push(updates.user_id || null);
+    }
+    if (updates.project_path !== undefined) {
+        setClauses.push('project_path = ?');
+        params.push(updates.project_path);
+    }
+    if (updates.original_goal !== undefined) {
+        setClauses.push('original_goal = ?');
+        params.push(updates.original_goal || null);
+    }
+    if (updates.actions_taken !== undefined) {
+        setClauses.push('actions_taken = ?');
+        params.push(JSON.stringify(updates.actions_taken));
+    }
+    if (updates.files_explored !== undefined) {
+        setClauses.push('files_explored = ?');
+        params.push(JSON.stringify(updates.files_explored));
+    }
+    if (updates.current_intent !== undefined) {
+        setClauses.push('current_intent = ?');
+        params.push(updates.current_intent || null);
+    }
+    if (updates.drift_warnings !== undefined) {
+        setClauses.push('drift_warnings = ?');
+        params.push(JSON.stringify(updates.drift_warnings));
+    }
+    if (updates.status !== undefined) {
+        setClauses.push('status = ?');
+        params.push(updates.status);
+    }
+    // Always update last_update
+    setClauses.push('last_update = ?');
+    params.push(new Date().toISOString());
+    if (setClauses.length === 0)
+        return;
+    params.push(sessionId);
+    const sql = `UPDATE session_states SET ${setClauses.join(', ')} WHERE session_id = ?`;
+    // SECURITY: Use transaction for atomic updates to prevent race conditions
+    const transaction = database.transaction(() => {
+        database.prepare(sql).run(...params);
+    });
+    transaction();
+}
+/**
+ * Delete a session state
+ */
+export function deleteSessionState(sessionId) {
+    const database = initDatabase();
+    database.prepare('DELETE FROM session_states WHERE session_id = ?').run(sessionId);
+}
+/**
+ * Get active sessions for a project
+ */
+export function getActiveSessionsForProject(projectPath) {
+    const database = initDatabase();
+    const stmt = database.prepare("SELECT * FROM session_states WHERE project_path = ? AND status = 'active' ORDER BY start_time DESC");
+    const rows = stmt.all(projectPath);
+    return rows.map(rowToSessionState);
+}
+/**
+ * Convert database row to SessionState object
+ */
+function rowToSessionState(row) {
+    return {
+        session_id: row.session_id,
+        user_id: row.user_id,
+        project_path: row.project_path,
+        original_goal: row.original_goal,
+        actions_taken: safeJsonParse(row.actions_taken, []),
+        files_explored: safeJsonParse(row.files_explored, []),
+        current_intent: row.current_intent,
+        drift_warnings: safeJsonParse(row.drift_warnings, []),
+        start_time: row.start_time,
+        last_update: row.last_update,
+        status: row.status,
+        // Drift detection fields
+        expected_scope: safeJsonParse(row.expected_scope, []),
+        constraints: safeJsonParse(row.constraints, []),
+        success_criteria: safeJsonParse(row.success_criteria, []),
+        keywords: safeJsonParse(row.keywords, []),
+        // Drift tracking fields
+        last_drift_score: row.last_drift_score,
+        escalation_count: row.escalation_count || 0,
+        pending_recovery_plan: safeJsonParse(row.pending_recovery_plan, undefined),
+        drift_history: safeJsonParse(row.drift_history, []),
+        // Action tracking
+        last_checked_at: row.last_checked_at || 0
+    };
+}
+/**
+ * Update session drift metrics after a prompt check
+ */
+export function updateSessionDrift(sessionId, driftScore, correctionLevel, promptSummary, recoveryPlan) {
+    const database = initDatabase();
+    const session = getSessionState(sessionId);
+    if (!session)
+        return;
+    const now = new Date().toISOString();
+    // Calculate new escalation count
+    let newEscalation = session.escalation_count;
+    if (driftScore >= 8) {
+        // Recovery - decrease escalation
+        newEscalation = Math.max(0, newEscalation - 1);
+    }
+    else if (correctionLevel && correctionLevel !== 'nudge') {
+        // Significant drift - increase escalation
+        newEscalation = Math.min(3, newEscalation + 1);
+    }
+    // Add to drift history
+    const driftEvent = {
+        timestamp: now,
+        score: driftScore,
+        level: correctionLevel || 'none',
+        prompt_summary: promptSummary.substring(0, 100)
+    };
+    const newHistory = [...session.drift_history, driftEvent];
+    // Add to drift_warnings if correction was given
+    const newWarnings = correctionLevel
+        ? [...session.drift_warnings, `[${now}] ${correctionLevel}: score ${driftScore}`]
+        : session.drift_warnings;
+    const stmt = database.prepare(`
+    UPDATE session_states SET
+      last_drift_score = ?,
+      escalation_count = ?,
+      pending_recovery_plan = ?,
+      drift_history = ?,
+      drift_warnings = ?,
+      last_update = ?
+    WHERE session_id = ?
+  `);
+    stmt.run(driftScore, newEscalation, recoveryPlan ? JSON.stringify(recoveryPlan) : null, JSON.stringify(newHistory), JSON.stringify(newWarnings), now, sessionId);
+}
+/**
+ * Check if a session should be flagged for review
+ * Returns true if: status=drifted OR warnings>=3 OR avg_score<6
+ */
+export function shouldFlagForReview(sessionId) {
+    const session = getSessionState(sessionId);
+    if (!session)
+        return false;
+    // Check number of warnings
+    if (session.drift_warnings.length >= 3) {
+        return true;
+    }
+    // Check drift history for average score
+    if (session.drift_history.length >= 2) {
+        const totalScore = session.drift_history.reduce((sum, e) => sum + e.score, 0);
+        const avgScore = totalScore / session.drift_history.length;
+        if (avgScore < 6) {
+            return true;
+        }
+    }
+    // Check if any HALT level drift occurred
+    if (session.drift_history.some(e => e.level === 'halt')) {
+        return true;
+    }
+    // Check current escalation level
+    if (session.escalation_count >= 2) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Get drift summary for a session (used by capture)
+ */
+export function getDriftSummary(sessionId) {
+    const session = getSessionState(sessionId);
+    if (!session || session.drift_history.length === 0) {
+        return { totalEvents: 0, resolved: true, finalScore: null, hadHalt: false };
+    }
+    const lastEvent = session.drift_history[session.drift_history.length - 1];
+    return {
+        totalEvents: session.drift_history.length,
+        resolved: lastEvent.score >= 8,
+        finalScore: lastEvent.score,
+        hadHalt: session.drift_history.some(e => e.level === 'halt')
+    };
+}
+// ============================================
+// FILE REASONING CRUD OPERATIONS
+// ============================================
+/**
+ * Create a new file reasoning entry
+ */
+export function createFileReasoning(input) {
+    const database = initDatabase();
+    const fileReasoning = {
+        id: randomUUID(),
+        task_id: input.task_id,
+        file_path: input.file_path,
+        anchor: input.anchor,
+        line_start: input.line_start,
+        line_end: input.line_end,
+        code_hash: input.code_hash,
+        change_type: input.change_type,
+        reasoning: input.reasoning,
+        created_at: new Date().toISOString()
+    };
+    const stmt = database.prepare(`
+    INSERT INTO file_reasoning (
+      id, task_id, file_path, anchor, line_start, line_end,
+      code_hash, change_type, reasoning, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    stmt.run(fileReasoning.id, fileReasoning.task_id || null, fileReasoning.file_path, fileReasoning.anchor || null, fileReasoning.line_start || null, fileReasoning.line_end || null, fileReasoning.code_hash || null, fileReasoning.change_type || null, fileReasoning.reasoning, fileReasoning.created_at);
+    return fileReasoning;
+}
+/**
+ * Get file reasoning entries for a task
+ */
+export function getFileReasoningForTask(taskId) {
+    const database = initDatabase();
+    const stmt = database.prepare('SELECT * FROM file_reasoning WHERE task_id = ? ORDER BY created_at DESC');
+    const rows = stmt.all(taskId);
+    return rows.map(rowToFileReasoning);
+}
+/**
+ * Get file reasoning entries by file path
+ */
+export function getFileReasoningByPath(filePath, limit = 10) {
+    const database = initDatabase();
+    const stmt = database.prepare('SELECT * FROM file_reasoning WHERE file_path = ? ORDER BY created_at DESC LIMIT ?');
+    const rows = stmt.all(filePath, limit);
+    return rows.map(rowToFileReasoning);
+}
+/**
+ * Get file reasoning entries matching a pattern (for files in a project).
+ * SECURITY: Uses escaped LIKE patterns to prevent injection.
+ */
+export function getFileReasoningByPathPattern(pathPattern, limit = 20) {
+    const database = initDatabase();
+    // Escape LIKE special characters to prevent injection
+    const escapedPattern = escapeLikePattern(pathPattern);
+    const stmt = database.prepare("SELECT * FROM file_reasoning WHERE file_path LIKE ? ESCAPE '\\' ORDER BY created_at DESC LIMIT ?");
+    const rows = stmt.all(`%${escapedPattern}%`, limit);
+    return rows.map(rowToFileReasoning);
+}
+/**
+ * Convert database row to FileReasoning object
+ */
+function rowToFileReasoning(row) {
+    return {
+        id: row.id,
+        task_id: row.task_id,
+        file_path: row.file_path,
+        anchor: row.anchor,
+        line_start: row.line_start,
+        line_end: row.line_end,
+        code_hash: row.code_hash,
+        change_type: row.change_type,
+        reasoning: row.reasoning,
+        created_at: row.created_at
+    };
+}
+/**
+ * Get the database path
+ */
+export function getDatabasePath() {
+    return DB_PATH;
+}
+/**
+ * Save a Claude action as a step
+ */
+export function saveStep(sessionId, action, driftScore, isKeyDecision = false, keywords = []) {
+    const database = initDatabase();
+    // Extract folders from files
+    const folders = [...new Set(action.files
+            .map(f => f.split('/').slice(0, -1).join('/'))
+            .filter(f => f.length > 0))];
+    database.prepare(`
+    INSERT INTO steps (id, session_id, action_type, files, folders, command, drift_score, is_key_decision, keywords, timestamp)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(randomUUID(), sessionId, action.type, JSON.stringify(action.files), JSON.stringify(folders), action.command || null, driftScore, isKeyDecision ? 1 : 0, JSON.stringify(keywords), action.timestamp);
+}
+/**
+ * Get recent steps for a session (most recent first)
+ */
+export function getRecentSteps(sessionId, limit = 10) {
+    const database = initDatabase();
+    const rows = database.prepare(`
+    SELECT * FROM steps WHERE session_id = ? ORDER BY timestamp DESC LIMIT ?
+  `).all(sessionId, limit);
+    return rows.map(rowToStepRecord);
+}
+/**
+ * Update last_checked_at timestamp for a session
+ */
+export function updateLastChecked(sessionId, timestamp) {
+    const database = initDatabase();
+    database.prepare(`
+    UPDATE session_states SET last_checked_at = ? WHERE session_id = ?
+  `).run(timestamp, sessionId);
+}
+// ============================================
+// 4-QUERY RETRIEVAL (from deep_dive.md)
+// ============================================
+/**
+ * Get steps that touched specific files
+ */
+export function getStepsByFiles(sessionId, files, limit = 5) {
+    if (files.length === 0)
+        return [];
+    const database = initDatabase();
+    const placeholders = files.map(() => `files LIKE ?`).join(' OR ');
+    const patterns = files.map(f => `%"${escapeLikePattern(f)}"%`);
+    const rows = database.prepare(`
+    SELECT * FROM steps
+    WHERE session_id = ? AND drift_score >= 5 AND (${placeholders})
+    ORDER BY timestamp DESC LIMIT ?
+  `).all(sessionId, ...patterns, limit);
+    return rows.map(rowToStepRecord);
+}
+/**
+ * Get steps that touched specific folders
+ */
+export function getStepsByFolders(sessionId, folders, limit = 5) {
+    if (folders.length === 0)
+        return [];
+    const database = initDatabase();
+    const placeholders = folders.map(() => `folders LIKE ?`).join(' OR ');
+    const patterns = folders.map(f => `%"${escapeLikePattern(f)}"%`);
+    const rows = database.prepare(`
+    SELECT * FROM steps
+    WHERE session_id = ? AND drift_score >= 5 AND (${placeholders})
+    ORDER BY timestamp DESC LIMIT ?
+  `).all(sessionId, ...patterns, limit);
+    return rows.map(rowToStepRecord);
+}
+/**
+ * Get steps matching keywords
+ */
+export function getStepsByKeywords(sessionId, keywords, limit = 5) {
+    if (keywords.length === 0)
+        return [];
+    const database = initDatabase();
+    const conditions = keywords.map(() => `keywords LIKE ?`).join(' OR ');
+    const patterns = keywords.map(k => `%"${escapeLikePattern(k)}"%`);
+    const rows = database.prepare(`
+    SELECT * FROM steps
+    WHERE session_id = ? AND drift_score >= 5 AND (${conditions})
+    ORDER BY timestamp DESC LIMIT ?
+  `).all(sessionId, ...patterns, limit);
+    return rows.map(rowToStepRecord);
+}
+/**
+ * Get key decision steps
+ */
+export function getKeyDecisionSteps(sessionId, limit = 5) {
+    const database = initDatabase();
+    const rows = database.prepare(`
+    SELECT * FROM steps
+    WHERE session_id = ? AND is_key_decision = 1
+    ORDER BY timestamp DESC LIMIT ?
+  `).all(sessionId, limit);
+    return rows.map(rowToStepRecord);
+}
+/**
+ * Combined retrieval: runs all 4 queries and deduplicates
+ * Priority: key decisions > files > folders > keywords
+ */
+export function getRelevantSteps(sessionId, currentFiles, currentFolders, keywords, limit = 10) {
+    const byFiles = getStepsByFiles(sessionId, currentFiles, 5);
+    const byFolders = getStepsByFolders(sessionId, currentFolders, 5);
+    const byKeywords = getStepsByKeywords(sessionId, keywords, 5);
+    const keyDecisions = getKeyDecisionSteps(sessionId, 5);
+    const seen = new Set();
+    const results = [];
+    // Priority order: key decisions > files > folders > keywords
+    for (const step of [...keyDecisions, ...byFiles, ...byFolders, ...byKeywords]) {
+        if (!seen.has(step.id)) {
+            seen.add(step.id);
+            results.push(step);
+            if (results.length >= limit)
+                break;
+        }
+    }
+    return results;
+}
+/**
+ * Convert database row to StepRecord
+ */
+function rowToStepRecord(row) {
+    return {
+        id: row.id,
+        session_id: row.session_id,
+        action_type: row.action_type,
+        files: safeJsonParse(row.files, []),
+        folders: safeJsonParse(row.folders, []),
+        command: row.command,
+        reasoning: row.reasoning,
+        drift_score: row.drift_score,
+        is_key_decision: row.is_key_decision === 1,
+        keywords: safeJsonParse(row.keywords, []),
+        timestamp: row.timestamp
+    };
+}