Skip to main content

reflex/
cache.rs

1//! Cache management and memory-mapped I/O
2//!
3//! The cache module handles the `.reflex/` directory structure:
4//! - `meta.db`: Metadata, file fingerprints, dependencies and the symbol cache (SQLite)
5//! - `content.bin`: Memory-mapped file contents (binary)
6//! - `trigrams.bin`: Trigram inverted index (per-file varint blocks, V4 format)
7//! - `config.toml`: Index settings (TOML text)
8
9use anyhow::{Context, Result};
10use rusqlite::{Connection, OptionalExtension};
11use std::collections::HashMap;
12use std::fs::File;
13use std::path::{Path, PathBuf};
14
15use crate::models::IndexedFile;
16
17/// Default cache directory name
18pub const CACHE_DIR: &str = ".reflex";
19
20/// File names within the cache directory
21pub const META_DB: &str = "meta.db";
22#[deprecated(note = "tokens.bin is no longer written")]
23pub const TOKENS_BIN: &str = "tokens.bin";
24#[deprecated(note = "hashes.json is no longer written; hashes live in meta.db")]
25pub const HASHES_JSON: &str = "hashes.json";
26pub const CONFIG_TOML: &str = "config.toml";
27/// `statistics` key: the `--languages` of the last `rfx index` run that passed one
28/// (JSON list). Older binaries ignore it.
29pub const LANGUAGES_OVERRIDE_KEY: &str = "languages_override";
30
31/// Open a SQLite database with Reflex's standard pragmas.
32///
33/// Every connection to `meta.db` (and to the symbol cache, which lives in the same
34/// file) MUST go through this helper. Plain `Connection::open` leaves SQLite at its
35/// defaults, which caused three separate production failures:
36///
37/// 1. **No `busy_timeout`** — the default is 0, so `BEGIN IMMEDIATE` returned
38///    `database is locked` *instantly* whenever the background symbol indexer held a
39///    write. Agents saw a raw SQLite error instead of a retry.
40/// 2. **No `journal_mode=WAL`** — readers blocked writers and vice versa, and
41///    [`CacheManager::checkpoint_wal`] was issuing `wal_checkpoint(TRUNCATE)` against a
42///    rollback-journal database, where it does nothing.
43/// 3. **No `foreign_keys=ON`** — SQLite disables foreign keys per connection by
44///    default, so the `ON DELETE CASCADE` clauses in the schema never fired and
45///    deleting a row from `files` orphaned its `file_branches` / `file_dependencies` /
46///    `file_exports` rows.
47///
48/// Pragma order is load-bearing: `journal_mode=WAL` itself can return `SQLITE_BUSY`
49/// when another connection is attached, so `busy_timeout` must be set first.
50///
51/// Set `REFLEX_SQLITE_JOURNAL=delete` to opt out of WAL on network filesystems, where
52/// WAL requires shared-memory support that NFS/SMB do not reliably provide.
53pub fn open_meta_db(db_path: impl AsRef<Path>) -> Result<Connection> {
54    let db_path = db_path.as_ref();
55    let conn = Connection::open(db_path)
56        .with_context(|| format!("Failed to open {}", db_path.display()))?;
57
58    // Must come first: the journal_mode change below can itself hit a busy database.
59    conn.busy_timeout(std::time::Duration::from_millis(SQLITE_BUSY_TIMEOUT_MS))
60        .context("Failed to set busy_timeout")?;
61
62    let journal_mode = std::env::var("REFLEX_SQLITE_JOURNAL")
63        .unwrap_or_else(|_| "WAL".to_string())
64        .to_uppercase();
65
66    // query_row, not execute: `PRAGMA journal_mode` returns the resulting mode as a row.
67    if let Err(e) = conn.query_row(
68        &format!("PRAGMA journal_mode={}", journal_mode),
69        [],
70        |row| row.get::<_, String>(0),
71    ) {
72        // A read-only or network filesystem can refuse WAL. Degrading to the default
73        // journal is correct here — losing concurrency beats failing to open the cache.
74        log::warn!(
75            "Could not set journal_mode={} on {}: {} (continuing with the default journal)",
76            journal_mode,
77            db_path.display(),
78            e
79        );
80    }
81
82    conn.execute_batch("PRAGMA foreign_keys=ON;")
83        .context("Failed to enable foreign keys")?;
84
85    Ok(conn)
86}
87
88/// How long a SQLite connection waits for a competing writer before giving up.
89///
90/// The background symbol indexer writes in batches; 5s comfortably covers one batch.
91/// A pass that holds the database for longer than this is caught earlier and more
92/// clearly by the `BackgroundIndexer::is_running` gate in `Indexer::index`.
93const SQLITE_BUSY_TIMEOUT_MS: u64 = 5_000;
94
95/// Manages the Reflex cache directory
96#[derive(Clone)]
97pub struct CacheManager {
98    cache_path: PathBuf,
99}
100
101impl CacheManager {
102    /// Create a new cache manager for the given root directory
103    pub fn new(root: impl AsRef<Path>) -> Self {
104        let cache_path = root.as_ref().join(CACHE_DIR);
105        Self { cache_path }
106    }
107
108    /// Initialize the cache directory structure if it doesn't exist
109    pub fn init(&self) -> Result<()> {
110        log::info!("Initializing cache at {:?}", self.cache_path);
111
112        if !self.cache_path.exists() {
113            std::fs::create_dir_all(&self.cache_path)?;
114        }
115
116        // Create meta.db with schema
117        self.init_meta_db()?;
118
119        // Create default config.toml
120        self.init_config_toml()?;
121
122        log::info!("Cache initialized successfully");
123        Ok(())
124    }
125
126    /// Create `config.toml` if it is missing: what `init` does besides the schema,
127    /// for a cache whose schema this binary already completed a run on.
128    pub(crate) fn ensure_config(&self) -> Result<()> {
129        self.init_config_toml()
130    }
131
132    /// Initialize meta.db with SQLite schema
133    fn init_meta_db(&self) -> Result<()> {
134        let db_path = self.cache_path.join(META_DB);
135
136        // Always run: every statement is `IF NOT EXISTS`, so this is a no-op on
137        // a complete database and a repair on a half-built one. (An indexer
138        // killed during schema creation used to leave meta.db with some tables
139        // missing; the old "skip if the file exists" check then made every later
140        // run fail with `no such table: file_branches`.) One transaction so a
141        // kill mid-way leaves either the old state or the full schema.
142        let conn = open_meta_db(&db_path).context("Failed to create meta.db")?;
143        conn.execute_batch("BEGIN IMMEDIATE")
144            .context("Failed to begin meta.db schema transaction")?;
145
146        // Create files table.
147        //
148        // The last four columns are the working-tree fingerprint: what freshness
149        // compares the tree against. Before 2.0.0 the baseline was the indexed
150        // COMMIT, so a dirty tree could never be reported fresh, however many times
151        // it was re-indexed. `hash` is the blake3 of the bytes that went into
152        // content.bin; `size`/`mtime_ns` let a status check skip the hash for files
153        // that have not been touched; `dirty_at_index` marks paths `git status`
154        // listed at index time, which must be re-checked even once git reports them
155        // clean again (an edit reverted after it was indexed).
156        conn.execute(
157            "CREATE TABLE IF NOT EXISTS files (
158                id INTEGER PRIMARY KEY AUTOINCREMENT,
159                path TEXT NOT NULL UNIQUE,
160                last_indexed INTEGER NOT NULL,
161                language TEXT NOT NULL,
162                token_count INTEGER DEFAULT 0,
163                line_count INTEGER DEFAULT 0,
164                size INTEGER NOT NULL DEFAULT 0,
165                mtime_ns INTEGER NOT NULL DEFAULT 0,
166                hash TEXT NOT NULL DEFAULT '',
167                dirty_at_index INTEGER NOT NULL DEFAULT 0,
168                walk_seq INTEGER NOT NULL DEFAULT 0
169            )",
170            [],
171        )?;
172        Self::migrate_files_columns(&conn)?;
173
174        conn.execute(
175            "CREATE INDEX IF NOT EXISTS idx_files_path ON files(path)",
176            [],
177        )?;
178        // Walk-order probes of a library update (`Indexer::update_paths`).
179        conn.execute(
180            "CREATE INDEX IF NOT EXISTS idx_files_walk_seq ON files(walk_seq)",
181            [],
182        )?;
183
184        // Create statistics table
185        conn.execute(
186            "CREATE TABLE IF NOT EXISTS statistics (
187                key TEXT PRIMARY KEY,
188                value TEXT NOT NULL,
189                updated_at INTEGER NOT NULL
190            )",
191            [],
192        )?;
193
194        // Initialize default statistics. `OR IGNORE`: an existing cache keeps its
195        // `total_files` (its `updated_at` is the "Last updated" time) and its
196        // `last_compaction`. Resetting them on every run made the unlocked
197        // background compaction start on every `rfx` command.
198        let now = chrono::Utc::now().timestamp();
199        conn.execute(
200            "INSERT OR IGNORE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
201            ["total_files", "0", &now.to_string()],
202        )?;
203        // Who wrote this cache. The old `cache_version = "1"` row was never read by
204        // anything; this replaces it with something actionable, so a refusal can name
205        // the version that owns the cache instead of just a hash.
206        conn.execute(
207            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
208            [
209                "writer_version",
210                env!("CARGO_PKG_VERSION"),
211                &now.to_string(),
212            ],
213        )?;
214        if let Some(sha) = option_env!("REFLEX_GIT_SHA") {
215            conn.execute(
216                "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
217                ["writer_git_sha", sha, &now.to_string()],
218            )?;
219        }
220
221        // Store cache schema hash for automatic invalidation detection
222        // This hash is computed at build time from cache-critical source files.
223        //
224        // `OR IGNORE`: only a NEW cache is stamped here. An existing cache keeps the
225        // hash of the binary that last completed an index, until
226        // `update_schema_hash` at the end of the next complete run. Stamping it here
227        // meant the indexer's "schema changed → full rebuild" check could never fire.
228        let schema_hash = env!("CACHE_SCHEMA_HASH");
229        conn.execute(
230            "INSERT OR IGNORE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
231            ["schema_hash", schema_hash, &now.to_string()],
232        )?;
233
234        // Initialize last_compaction timestamp (0 = never compacted)
235        conn.execute(
236            "INSERT OR IGNORE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
237            ["last_compaction", "0", &now.to_string()],
238        )?;
239
240        // Create config table
241        conn.execute(
242            "CREATE TABLE IF NOT EXISTS config (
243                key TEXT PRIMARY KEY,
244                value TEXT NOT NULL
245            )",
246            [],
247        )?;
248
249        // Create branch tracking tables for git-aware indexing
250        conn.execute(
251            "CREATE TABLE IF NOT EXISTS file_branches (
252                file_id INTEGER NOT NULL,
253                branch_id INTEGER NOT NULL,
254                hash TEXT NOT NULL,
255                last_indexed INTEGER NOT NULL,
256                PRIMARY KEY (file_id, branch_id),
257                FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE,
258                FOREIGN KEY (branch_id) REFERENCES branches(id) ON DELETE CASCADE
259            )",
260            [],
261        )?;
262
263        conn.execute(
264            "CREATE INDEX IF NOT EXISTS idx_branch_lookup ON file_branches(branch_id, file_id)",
265            [],
266        )?;
267
268        conn.execute(
269            "CREATE INDEX IF NOT EXISTS idx_hash_lookup ON file_branches(hash)",
270            [],
271        )?;
272
273        // Create branches metadata table
274        conn.execute(
275            "CREATE TABLE IF NOT EXISTS branches (
276                id INTEGER PRIMARY KEY AUTOINCREMENT,
277                name TEXT NOT NULL UNIQUE,
278                commit_sha TEXT NOT NULL,
279                last_indexed INTEGER NOT NULL,
280                file_count INTEGER DEFAULT 0,
281                is_dirty INTEGER DEFAULT 0
282            )",
283            [],
284        )?;
285
286        // Create file dependencies table for tracking imports/includes
287        conn.execute(
288            "CREATE TABLE IF NOT EXISTS file_dependencies (
289                id INTEGER PRIMARY KEY AUTOINCREMENT,
290                file_id INTEGER NOT NULL,
291                imported_path TEXT NOT NULL,
292                resolved_file_id INTEGER,
293                import_type TEXT NOT NULL,
294                line_number INTEGER NOT NULL,
295                imported_symbols TEXT,
296                FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE,
297                FOREIGN KEY (resolved_file_id) REFERENCES files(id) ON DELETE SET NULL
298            )",
299            [],
300        )?;
301
302        conn.execute(
303            "CREATE INDEX IF NOT EXISTS idx_deps_file ON file_dependencies(file_id)",
304            [],
305        )?;
306
307        conn.execute(
308            "CREATE INDEX IF NOT EXISTS idx_deps_resolved ON file_dependencies(resolved_file_id)",
309            [],
310        )?;
311
312        conn.execute(
313            "CREATE INDEX IF NOT EXISTS idx_deps_type ON file_dependencies(import_type)",
314            [],
315        )?;
316
317        // Create file exports table for tracking barrel re-exports
318        conn.execute(
319            "CREATE TABLE IF NOT EXISTS file_exports (
320                id INTEGER PRIMARY KEY AUTOINCREMENT,
321                file_id INTEGER NOT NULL,
322                exported_symbol TEXT,
323                source_path TEXT NOT NULL,
324                resolved_source_id INTEGER,
325                line_number INTEGER NOT NULL,
326                FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE,
327                FOREIGN KEY (resolved_source_id) REFERENCES files(id) ON DELETE SET NULL
328            )",
329            [],
330        )?;
331
332        conn.execute(
333            "CREATE INDEX IF NOT EXISTS idx_exports_file ON file_exports(file_id)",
334            [],
335        )?;
336
337        conn.execute(
338            "CREATE INDEX IF NOT EXISTS idx_exports_resolved ON file_exports(resolved_source_id)",
339            [],
340        )?;
341
342        conn.execute(
343            "CREATE INDEX IF NOT EXISTS idx_exports_symbol ON file_exports(exported_symbol)",
344            [],
345        )?;
346
347        conn.execute_batch("COMMIT")
348            .context("Failed to commit meta.db schema transaction")?;
349
350        log::debug!("Created meta.db with schema");
351        Ok(())
352    }
353
354    /// Add the fingerprint columns to a `files` table written before 2.0.0.
355    ///
356    /// `CREATE TABLE IF NOT EXISTS` leaves an existing table alone, and the first
357    /// non-`--force` `rfx index` on an old cache would otherwise fail its INSERT.
358    /// The schema hash already forces that index to rebuild every row, so the
359    /// columns only need to exist; their defaults are overwritten immediately.
360    fn migrate_files_columns(conn: &Connection) -> Result<()> {
361        const WANTED: [(&str, &str); 5] = [
362            ("size", "INTEGER NOT NULL DEFAULT 0"),
363            ("mtime_ns", "INTEGER NOT NULL DEFAULT 0"),
364            ("hash", "TEXT NOT NULL DEFAULT ''"),
365            ("dirty_at_index", "INTEGER NOT NULL DEFAULT 0"),
366            ("walk_seq", "INTEGER NOT NULL DEFAULT 0"),
367        ];
368        let mut stmt = conn.prepare("SELECT name FROM pragma_table_info('files')")?;
369        let present: std::collections::HashSet<String> = stmt
370            .query_map([], |row| row.get::<_, String>(0))?
371            .collect::<Result<_, _>>()?;
372        for (name, decl) in WANTED {
373            if !present.contains(name) {
374                log::info!("meta.db: adding files.{} (pre-2.0.0 cache)", name);
375                conn.execute(
376                    &format!("ALTER TABLE files ADD COLUMN {} {}", name, decl),
377                    [],
378                )?;
379            }
380        }
381        Ok(())
382    }
383
384    /// `path → fingerprint` for exactly the given paths, in 900-path chunks.
385    ///
386    /// The git freshness path asks only about the paths `git status` (and the
387    /// dirty-at-index set) name, never the whole table.
388    pub fn fingerprints_for(&self, paths: &[&str]) -> Result<HashMap<String, FileFingerprint>> {
389        let db_path = self.cache_path.join(META_DB);
390        if paths.is_empty() || !db_path.exists() {
391            return Ok(HashMap::new());
392        }
393        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
394        const BATCH_SIZE: usize = 900;
395        let mut out = HashMap::with_capacity(paths.len());
396        for chunk in paths.chunks(BATCH_SIZE) {
397            let placeholders = chunk.iter().map(|_| "?").collect::<Vec<_>>().join(", ");
398            let sql = format!(
399                "SELECT path, size, mtime_ns, hash FROM files WHERE path IN ({})",
400                placeholders
401            );
402            let mut stmt = conn.prepare(&sql)?;
403            let rows = stmt.query_map(rusqlite::params_from_iter(chunk.iter()), |row| {
404                Ok((
405                    row.get::<_, String>(0)?,
406                    FileFingerprint {
407                        size: row.get::<_, i64>(1)? as u64,
408                        mtime_ns: row.get::<_, i64>(2)?,
409                        hash: row.get::<_, String>(3)?,
410                    },
411                ))
412            })?;
413            for row in rows {
414                let (path, fp) = row?;
415                out.insert(path, fp);
416            }
417        }
418        Ok(out)
419    }
420
421    /// Every indexed path with its fingerprint.
422    ///
423    /// Used outside git, where the tree is walked and every file compared; the
424    /// query handle memoises the result until the index is rewritten.
425    pub fn load_fingerprints(&self) -> Result<HashMap<String, FileFingerprint>> {
426        let db_path = self.cache_path.join(META_DB);
427        if !db_path.exists() {
428            return Ok(HashMap::new());
429        }
430        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
431        let mut stmt = conn.prepare("SELECT path, size, mtime_ns, hash FROM files")?;
432        let rows = stmt.query_map([], |row| {
433            Ok((
434                row.get::<_, String>(0)?,
435                FileFingerprint {
436                    size: row.get::<_, i64>(1)? as u64,
437                    mtime_ns: row.get::<_, i64>(2)?,
438                    hash: row.get::<_, String>(3)?,
439                },
440            ))
441        })?;
442        rows.collect::<Result<HashMap<_, _>, _>>()
443            .context("Failed to read file fingerprints")
444    }
445
446    /// Initialize config.toml with defaults
447    fn init_config_toml(&self) -> Result<()> {
448        let config_path = self.cache_path.join(CONFIG_TOML);
449
450        if config_path.exists() {
451            return Ok(());
452        }
453
454        let default_config = r#"[index]
455languages = []  # Empty = all supported languages
456text_tier = true  # Also index docs, config and every other non-binary file
457# "tracked" (default): every non-binary file that is not gitignored and not under a
458#   dot-directory — ripgrep's defaults (hidden = true walks dot-directories). Lock and generated files are indexed but excluded from
459#   searches unless asked for (include_locks / include_generated / lang).
460# "allowlist": code plus a fixed docs/config extension list.
461mode = "tracked"
462hidden = false  # true also walks dot-directories (.githooks/), never .git/ or .reflex/
463max_file_size = 10485760  # 10 MB
464follow_symlinks = false
465
466[index.include]
467patterns = []
468
469[index.exclude]
470patterns = []
471
472[performance]
473parallel_threads = 0  # 0 = auto (80% of available cores, max 32), or set a specific number
474symbol_threads = 0  # background symbol pass; 0 = auto (50% of available cores, max 32)
475
476# AI provider settings for `rfx ask` / `rfx pulse` live in ~/.reflex/config.toml
477# (run `rfx llm config`), not here.
478"#;
479
480        std::fs::write(&config_path, default_config)?;
481
482        log::debug!("Created default config.toml");
483        Ok(())
484    }
485
486    /// Check if cache exists and is valid
487    pub fn exists(&self) -> bool {
488        self.cache_path.exists() && self.cache_path.join(META_DB).exists()
489    }
490
491    /// Validate cache integrity and detect corruption
492    ///
493    /// Performs basic integrity checks on the cache:
494    /// - Verifies all required files exist
495    /// - Checks SQLite database can be opened
496    /// - Validates binary file headers (trigrams.bin, content.bin)
497    ///
498    /// Returns Ok(()) if cache is valid, Err with details if corrupted.
499    pub fn validate(&self) -> Result<()> {
500        let start = std::time::Instant::now();
501
502        // Check if cache directory exists
503        if !self.cache_path.exists() {
504            anyhow::bail!(
505                "Cache directory does not exist: {}",
506                self.cache_path.display()
507            );
508        }
509
510        // Check meta.db exists and can be opened
511        let db_path = self.cache_path.join(META_DB);
512        if !db_path.exists() {
513            anyhow::bail!("Database file missing: {}", db_path.display());
514        }
515
516        // Try to open database
517        let conn =
518            open_meta_db(&db_path).context("Failed to open meta.db - database may be corrupted")?;
519
520        // Verify schema exists
521        let tables: Result<Vec<String>, _> = conn
522            .prepare("SELECT name FROM sqlite_master WHERE type='table'")
523            .and_then(|mut stmt| {
524                stmt.query_map([], |row| row.get(0))
525                    .map(|rows| rows.collect())
526            })
527            .and_then(|result| result);
528
529        match tables {
530            Ok(table_list) => {
531                // Check for required tables
532                let required_tables = vec![
533                    "files",
534                    "statistics",
535                    "config",
536                    "file_branches",
537                    "branches",
538                    "file_dependencies",
539                    "file_exports",
540                ];
541                for table in &required_tables {
542                    if !table_list.iter().any(|t| t == table) {
543                        anyhow::bail!("Required table '{}' missing from database schema", table);
544                    }
545                }
546            }
547            Err(e) => {
548                anyhow::bail!("Failed to read database schema: {}", e);
549            }
550        }
551
552        // Run SQLite integrity check (fast quick_check)
553        // Use quick_check instead of integrity_check for speed (<10ms vs 100ms+)
554        let integrity_result: String =
555            conn.query_row("PRAGMA quick_check", [], |row| row.get(0))?;
556
557        if integrity_result != "ok" {
558            log::warn!("Database integrity check failed: {}", integrity_result);
559            anyhow::bail!(
560                "Database integrity check failed: {}. Cache may be corrupted. \
561                 Run 'rfx index' to rebuild cache.",
562                integrity_result
563            );
564        }
565
566        // The stores the manifest names (or the fixed names of a cache without
567        // one); messages use the logical names.
568        let summary = crate::snapshot::store_summary(&self.cache_path);
569
570        // Check trigrams.bin if it exists
571        let trigrams_path = summary.trigram_files[0].clone();
572        if trigrams_path.exists() {
573            use std::io::Read;
574
575            match File::open(&trigrams_path) {
576                Ok(mut file) => {
577                    let mut header = [0u8; 4];
578                    match file.read_exact(&mut header) {
579                        Ok(_) => {
580                            // Check magic bytes
581                            if &header != b"RFTG" {
582                                log::warn!(
583                                    "trigrams.bin has invalid magic bytes - may be corrupted"
584                                );
585                                anyhow::bail!(
586                                    "trigrams.bin appears to be corrupted (invalid magic bytes)"
587                                );
588                            }
589                        }
590                        Err(_) => {
591                            anyhow::bail!("trigrams.bin is too small - appears to be corrupted");
592                        }
593                    }
594                }
595                Err(e) => {
596                    anyhow::bail!("Failed to open trigrams.bin: {}", e);
597                }
598            }
599        }
600
601        // Check content.bin if it exists
602        let content_path = summary.content_files[0].clone();
603        if content_path.exists() {
604            use std::io::Read;
605
606            match File::open(&content_path) {
607                Ok(mut file) => {
608                    let mut header = [0u8; 4];
609                    match file.read_exact(&mut header) {
610                        Ok(_) => {
611                            // Check magic bytes
612                            if &header != b"RFCT" {
613                                log::warn!(
614                                    "content.bin has invalid magic bytes - may be corrupted"
615                                );
616                                anyhow::bail!(
617                                    "content.bin appears to be corrupted (invalid magic bytes)"
618                                );
619                            }
620                        }
621                        Err(_) => {
622                            anyhow::bail!("content.bin is too small - appears to be corrupted");
623                        }
624                    }
625                }
626                Err(e) => {
627                    anyhow::bail!("Failed to open content.bin: {}", e);
628                }
629            }
630        }
631
632        // NOT checked here any more: the schema hash.
633        //
634        // `validate()` runs on EVERY search (query/mod.rs), and a bail here becomes
635        // ReflexError::CacheCorrupted, which the MCP layer answers by force-rebuilding
636        // the index. With several Reflex versions sharing one `.reflex/` — three
637        // `rfx mcp` servers from three Claude Code sessions, in the field report —
638        // each one saw a mismatch, each force-rebuilt, and they streamed into
639        // content.bin concurrently. That is what produced `content.bin is too small`.
640        //
641        // A version mismatch is not corruption. Readers are now allowed through and
642        // the mismatch surfaces via `get_index_status` as stale with
643        // can_trust_results: false, naming the owner version. WRITERS refuse — see
644        // `assert_writable`. Structural checks above (magic bytes, short files,
645        // quick_check) still bail, because those really are corruption.
646
647        log::debug!("Cache validation passed (took {:?})", start.elapsed());
648        Ok(())
649    }
650
651    /// Get the path to the cache directory
652    pub fn path(&self) -> &Path {
653        &self.cache_path
654    }
655
656    /// Get the workspace root directory (parent of .reflex/)
657    pub fn workspace_root(&self) -> PathBuf {
658        self.cache_path
659            .parent()
660            .expect(".reflex directory should have a parent")
661            .to_path_buf()
662    }
663
664    /// The config every index run in this workspace uses: `.reflex/config.toml`,
665    /// with `languages` replaced by `languages` when it is not empty, else by the
666    /// `--languages` of the last `rfx index` run that passed one.
667    ///
668    /// `rfx index`, automatic updates, `index_project`, `POST /index`, `rfx watch`
669    /// and interactive mode all start here, so they index the same file set the
670    /// freshness check expects.
671    pub fn effective_index_config(
672        &self,
673        languages: &[crate::models::Language],
674    ) -> Result<crate::models::IndexConfig> {
675        let mut config = self.load_index_config()?;
676        if !languages.is_empty() {
677            config.languages = languages.to_vec();
678        } else if let Some(saved) = self.languages_override() {
679            config.languages = saved;
680        }
681        Ok(config)
682    }
683
684    /// The `--languages` of the last `rfx index` run that passed one, if any.
685    fn languages_override(&self) -> Option<Vec<crate::models::Language>> {
686        let db_path = self.cache_path.join(META_DB);
687        if !db_path.exists() {
688            return None;
689        }
690        let conn = open_meta_db(&db_path).ok()?;
691        let raw = crate::meta_update::get_statistic(&conn, LANGUAGES_OVERRIDE_KEY)
692            .ok()
693            .flatten()?;
694        serde_json::from_str(&raw).ok()
695    }
696
697    /// Record the `--languages` of an `rfx index` run (empty: none was passed),
698    /// so later automatic updates index the same languages.
699    pub fn set_languages_override(&self, languages: &[crate::models::Language]) -> Result<()> {
700        let conn = open_meta_db(self.cache_path.join(META_DB))?;
701        if languages.is_empty() {
702            conn.execute(
703                "DELETE FROM statistics WHERE key = ?",
704                [LANGUAGES_OVERRIDE_KEY],
705            )?;
706        } else {
707            crate::meta_update::set_statistic(
708                &conn,
709                LANGUAGES_OVERRIDE_KEY,
710                &serde_json::to_string(languages)?,
711                chrono::Utc::now().timestamp(),
712            )?;
713        }
714        Ok(())
715    }
716
717    /// Load IndexConfig from `.reflex/config.toml` if it exists.
718    ///
719    /// Returns `IndexConfig::default()` when the file is absent or a section
720    /// is missing.  Parse errors are surfaced so the user gets a clear message
721    /// rather than silently falling back to defaults.
722    pub fn load_index_config(&self) -> Result<crate::models::IndexConfig> {
723        use crate::models::{IndexConfig, Language};
724
725        let config_path = self.cache_path.join(CONFIG_TOML);
726        if !config_path.exists() {
727            return Ok(IndexConfig::default());
728        }
729
730        let raw = std::fs::read_to_string(&config_path)
731            .with_context(|| format!("Failed to read {}", config_path.display()))?;
732
733        let toml_val: toml::Value = toml::from_str(&raw)
734            .with_context(|| format!("Failed to parse {}", config_path.display()))?;
735
736        let mut cfg = IndexConfig::default();
737
738        if let Some(index_tbl) = toml_val.get("index") {
739            if let Some(langs) = index_tbl.get("languages").and_then(|v| v.as_array()) {
740                let parsed: Vec<Language> = langs
741                    .iter()
742                    .filter_map(|v| v.as_str())
743                    .filter_map(|s| {
744                        Language::from_name(s).or_else(|| {
745                            log::warn!(
746                                "Unknown language '{}' in config.toml [index] section — ignoring",
747                                s
748                            );
749                            None
750                        })
751                    })
752                    .collect();
753                if !parsed.is_empty() {
754                    cfg.languages = parsed;
755                }
756            }
757            if let Some(text_tier) = index_tbl.get("text_tier").and_then(|v| v.as_bool()) {
758                cfg.text_tier = text_tier;
759            }
760            if let Some(mode) = index_tbl.get("mode").and_then(|v| v.as_str()) {
761                match crate::models::IndexMode::from_name(mode) {
762                    Some(m) => cfg.mode = m,
763                    None => log::warn!(
764                        "Unknown [index] mode '{}' in config.toml (expected \"tracked\" or \
765                         \"allowlist\") — using \"tracked\"",
766                        mode
767                    ),
768                }
769            }
770            if let Some(hidden) = index_tbl.get("hidden").and_then(|v| v.as_bool()) {
771                cfg.hidden = hidden;
772            }
773
774            if let Some(max_size) = index_tbl.get("max_file_size").and_then(|v| v.as_integer()) {
775                cfg.max_file_size = max_size as usize;
776            }
777            if let Some(follow) = index_tbl.get("follow_symlinks").and_then(|v| v.as_bool()) {
778                cfg.follow_symlinks = follow;
779            }
780            if let Some(include) = index_tbl
781                .get("include")
782                .and_then(|v| v.get("patterns"))
783                .and_then(|v| v.as_array())
784            {
785                cfg.include_patterns = include
786                    .iter()
787                    .filter_map(|v| v.as_str().map(String::from))
788                    .collect();
789            }
790            if let Some(exclude) = index_tbl
791                .get("exclude")
792                .and_then(|v| v.get("patterns"))
793                .and_then(|v| v.as_array())
794            {
795                cfg.exclude_patterns = exclude
796                    .iter()
797                    .filter_map(|v| v.as_str().map(String::from))
798                    .collect();
799            }
800        }
801
802        if let Some(perf) = toml_val.get("performance")
803            && let Some(threads) = perf.get("parallel_threads").and_then(|v| v.as_integer())
804        {
805            cfg.parallel_threads = threads as usize;
806        }
807        if let Some(perf) = toml_val.get("performance")
808            && let Some(threads) = perf.get("symbol_threads").and_then(|v| v.as_integer())
809        {
810            cfg.symbol_threads = threads.max(0) as usize;
811        }
812
813        log::debug!("Loaded IndexConfig from config.toml: {:?}", cfg);
814        Ok(cfg)
815    }
816
817    /// Clear the entire cache
818    pub fn clear(&self) -> Result<()> {
819        log::info!("Clearing cache at {:?}", self.cache_path);
820
821        if !self.cache_path.exists() {
822            return Ok(());
823        }
824
825        // No query in this process may keep serving from the files about to go.
826        crate::query::invalidate_caches(&self.workspace_root());
827
828        // Hold the workspace index lock while deleting so we never pull
829        // content.bin out from under a running indexer. Everything except the
830        // lock file goes while the lock is held; the lock file and the (now
831        // empty) directory are removed afterwards, best-effort, so callers
832        // that expect `.reflex/` to vanish keep working.
833        let lock =
834            crate::atomic_write::IndexLock::try_acquire(&self.cache_path)?.ok_or_else(|| {
835                crate::errors::ReflexError::IndexLocked(
836                    crate::atomic_write::IndexLock::lock_path(&self.cache_path)
837                        .display()
838                        .to_string(),
839                )
840            })?;
841
842        for entry in std::fs::read_dir(&self.cache_path)? {
843            let entry = entry?;
844            let path = entry.path();
845            if path.file_name().and_then(|n| n.to_str())
846                == Some(crate::atomic_write::INDEX_LOCK_FILE)
847            {
848                continue;
849            }
850            if path.is_dir() {
851                std::fs::remove_dir_all(&path)?;
852            } else {
853                std::fs::remove_file(&path)?;
854            }
855        }
856
857        let lock_path = lock.path().to_path_buf();
858        drop(lock);
859        let _ = std::fs::remove_file(&lock_path);
860        let _ = std::fs::remove_dir(&self.cache_path);
861
862        Ok(())
863    }
864
865    /// Force SQLite WAL (Write-Ahead Log) checkpoint
866    ///
867    /// Ensures all data written in transactions is flushed to the main database file.
868    /// This is critical when spawning background processes that open new connections,
869    /// as they need to see the committed data immediately.
870    ///
871    /// Uses TRUNCATE mode to completely flush and reset the WAL file.
872    pub fn checkpoint_wal(&self) -> Result<()> {
873        let db_path = self.cache_path.join(META_DB);
874
875        if !db_path.exists() {
876            // No database to checkpoint
877            return Ok(());
878        }
879
880        let conn = open_meta_db(&db_path).context("Failed to open meta.db for WAL checkpoint")?;
881
882        // PRAGMA wal_checkpoint(TRUNCATE) forces a full checkpoint and truncates the WAL
883        // This ensures background processes see all committed data
884        // Note: Returns (busy, log_pages, checkpointed_pages) - use query instead of execute
885        conn.query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |row| {
886            let busy: i64 = row.get(0)?;
887            let log_pages: i64 = row.get(1)?;
888            let checkpointed: i64 = row.get(2)?;
889            log::debug!(
890                "WAL checkpoint completed: busy={}, log_pages={}, checkpointed_pages={}",
891                busy,
892                log_pages,
893                checkpointed
894            );
895            Ok(())
896        })
897        .context("Failed to execute WAL checkpoint")?;
898
899        log::debug!("Executed WAL checkpoint (TRUNCATE) on meta.db");
900        Ok(())
901    }
902
903    /// `path → (file_id, hash)` for every indexed file, in one query.
904    ///
905    /// What the background symbol pass needs to decide, without touching SQLite
906    /// again, which files are already cached and which ids to write. The hash is
907    /// `files.hash`, the hash of the bytes in the stores: a branch row's hash can
908    /// name another version of the file once other branches' rows are kept.
909    pub fn load_all_file_rows(&self) -> Result<HashMap<String, (i64, String)>> {
910        let db_path = self.cache_path.join(META_DB);
911        if !db_path.exists() {
912            return Ok(HashMap::new());
913        }
914        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
915        let mut stmt = conn.prepare("SELECT path, id, hash FROM files")?;
916        let rows: HashMap<String, (i64, String)> = stmt
917            .query_map([], |row| {
918                Ok((
919                    row.get(0)?,
920                    (row.get::<_, i64>(1)?, row.get::<_, String>(2)?),
921                ))
922            })?
923            .collect::<Result<HashMap<_, _>, _>>()?;
924        Ok(rows)
925    }
926
927    pub fn load_all_hashes(&self) -> Result<HashMap<String, String>> {
928        let db_path = self.cache_path.join(META_DB);
929
930        if !db_path.exists() {
931            return Ok(HashMap::new());
932        }
933
934        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
935
936        // Get all hashes from file_branches, joined with files to get paths
937        // If a file appears in multiple branches, we'll get multiple entries
938        // (HashMap will keep the last one, which is fine for background indexer)
939        let mut stmt = conn.prepare(
940            "SELECT f.path, fb.hash
941             FROM file_branches fb
942             JOIN files f ON fb.file_id = f.id",
943        )?;
944        let hashes: HashMap<String, String> = stmt
945            .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?
946            .collect::<Result<HashMap<_, _>, _>>()?;
947
948        log::debug!(
949            "Loaded {} file hashes across all branches from SQLite",
950            hashes.len()
951        );
952        Ok(hashes)
953    }
954
955    /// Load file hashes for a specific branch from SQLite
956    ///
957    /// Used by indexer and query engine to get hashes for the current branch.
958    /// This ensures branch-specific incremental indexing and symbol cache lookups.
959    pub fn load_hashes_for_branch(&self, branch: &str) -> Result<HashMap<String, String>> {
960        let db_path = self.cache_path.join(META_DB);
961
962        if !db_path.exists() {
963            return Ok(HashMap::new());
964        }
965
966        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
967
968        // Get hashes for specific branch only
969        let mut stmt = conn.prepare(
970            "SELECT f.path, fb.hash
971             FROM file_branches fb
972             JOIN files f ON fb.file_id = f.id
973             JOIN branches b ON fb.branch_id = b.id
974             WHERE b.name = ?",
975        )?;
976        let hashes: HashMap<String, String> = stmt
977            .query_map([branch], |row| Ok((row.get(0)?, row.get(1)?)))?
978            .collect::<Result<HashMap<_, _>, _>>()?;
979
980        log::debug!(
981            "Loaded {} file hashes for branch '{}' from SQLite",
982            hashes.len(),
983            branch
984        );
985        Ok(hashes)
986    }
987
988    /// `path → (file_id, hash)` for the given paths only, `hash` = `files.hash`.
989    ///
990    /// The symbol path used to load every hash on the branch (a three-way join over
991    /// the whole index) and then look up every candidate's file id in a second
992    /// query. A `--symbols` query touches tens of files; this asks for exactly
993    /// those, in 900-path chunks, on a connection the caller already holds. The
994    /// key is the hash of the stored bytes, so a checkout without a reindex can
995    /// never cache one version's symbols under another version's hash.
996    pub fn file_rows_on(
997        conn: &Connection,
998        paths: &[String],
999    ) -> Result<HashMap<String, (i64, String)>> {
1000        const BATCH_SIZE: usize = 900;
1001        let mut out = HashMap::with_capacity(paths.len());
1002        for chunk in paths.chunks(BATCH_SIZE) {
1003            let placeholders = chunk.iter().map(|_| "?").collect::<Vec<_>>().join(", ");
1004            let sql = format!(
1005                "SELECT path, id, hash FROM files WHERE path IN ({})",
1006                placeholders
1007            );
1008            let mut stmt = conn.prepare(&sql)?;
1009            let rows = stmt.query_map(rusqlite::params_from_iter(chunk.iter()), |row| {
1010                Ok((
1011                    row.get::<_, String>(0)?,
1012                    row.get::<_, i64>(1)?,
1013                    row.get::<_, String>(2)?,
1014                ))
1015            })?;
1016            for row in rows {
1017                let (path, id, hash) = row?;
1018                out.insert(path, (id, hash));
1019            }
1020        }
1021        Ok(out)
1022    }
1023
1024    /// Save file hashes for incremental indexing
1025    ///
1026    /// DEPRECATED: Hashes are now saved via record_branch_file() or batch_record_branch_files().
1027    /// This method is kept for backward compatibility but does nothing.
1028    #[deprecated(note = "Hashes are now stored in file_branches table via record_branch_file()")]
1029    pub fn save_hashes(&self, _hashes: &HashMap<String, String>) -> Result<()> {
1030        // No-op: hashes are now persisted to SQLite in record_branch_file()
1031        Ok(())
1032    }
1033
1034    /// Update file metadata in the files table
1035    ///
1036    /// Note: File content hashes are stored separately in the file_branches table
1037    /// via record_branch_file() or batch_record_branch_files().
1038    pub fn update_file(&self, path: &str, language: &str, line_count: usize) -> Result<()> {
1039        let db_path = self.cache_path.join(META_DB);
1040        let conn = open_meta_db(&db_path).context("Failed to open meta.db for file update")?;
1041
1042        let now = chrono::Utc::now().timestamp();
1043
1044        conn.execute(
1045            "INSERT OR REPLACE INTO files (path, last_indexed, language, line_count)
1046             VALUES (?, ?, ?, ?)",
1047            [path, &now.to_string(), language, &line_count.to_string()],
1048        )?;
1049
1050        Ok(())
1051    }
1052
1053    /// Batch update multiple files in a single transaction for performance
1054    ///
1055    /// Note: File content hashes are stored separately in the file_branches table
1056    /// via batch_update_files_and_branch().
1057    pub fn batch_update_files(&self, files: &[(String, String, usize)]) -> Result<()> {
1058        let db_path = self.cache_path.join(META_DB);
1059        let mut conn = open_meta_db(&db_path).context("Failed to open meta.db for batch update")?;
1060
1061        let now = chrono::Utc::now().timestamp();
1062        let now_str = now.to_string();
1063
1064        // Use a transaction for batch inserts
1065        let tx = conn.transaction()?;
1066
1067        for (path, language, line_count) in files {
1068            tx.execute(
1069                "INSERT OR REPLACE INTO files (path, last_indexed, language, line_count)
1070                 VALUES (?, ?, ?, ?)",
1071                [
1072                    path.as_str(),
1073                    &now_str,
1074                    language.as_str(),
1075                    &line_count.to_string(),
1076                ],
1077            )?;
1078        }
1079
1080        tx.commit()?;
1081        Ok(())
1082    }
1083
1084    /// Update statistics after indexing by calculating totals from database for a specific branch
1085    ///
1086    /// Counts only files indexed for the given branch, not all files across all branches.
1087    pub fn update_stats(&self, branch: &str) -> Result<()> {
1088        let db_path = self.cache_path.join(META_DB);
1089        let conn = open_meta_db(&db_path).context("Failed to open meta.db for stats update")?;
1090        Self::update_stats_on(&conn, branch)
1091    }
1092
1093    /// Record `total_files` (and its `updated_at`, the "Last updated" time) as `n`:
1094    /// what [`Self::update_stats_on`] counts, for a caller that knows every file
1095    /// has its branch row.
1096    pub(crate) fn set_total_files_on(conn: &Connection, n: usize, now: i64) -> Result<()> {
1097        conn.execute(
1098            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1099            ["total_files", &n.to_string(), &now.to_string()],
1100        )?;
1101        Ok(())
1102    }
1103
1104    /// [`Self::update_stats`] on an open connection (inside the caller's transaction).
1105    pub(crate) fn update_stats_on(conn: &Connection, branch: &str) -> Result<()> {
1106        // Count files for specific branch only (branch-aware statistics)
1107        let total_files: usize = conn
1108            .query_row(
1109                "SELECT COUNT(DISTINCT fb.file_id)
1110             FROM file_branches fb
1111             JOIN branches b ON fb.branch_id = b.id
1112             WHERE b.name = ?",
1113                [branch],
1114                |row| row.get(0),
1115            )
1116            .unwrap_or(0);
1117
1118        let now = chrono::Utc::now().timestamp();
1119
1120        conn.execute(
1121            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1122            ["total_files", &total_files.to_string(), &now.to_string()],
1123        )?;
1124
1125        log::debug!(
1126            "Updated statistics for branch '{}': {} files",
1127            branch,
1128            total_files
1129        );
1130        Ok(())
1131    }
1132
1133    /// Check if the stored schema hash matches the current binary's hash.
1134    /// Returns Ok(true) if they match, Ok(false) if they don't, Err on DB errors.
1135    pub fn check_schema_hash(&self) -> Result<bool> {
1136        let db_path = self.cache_path.join(META_DB);
1137        if !db_path.exists() {
1138            return Ok(false);
1139        }
1140        let conn = open_meta_db(&db_path)?;
1141        Self::check_schema_hash_on(&conn)
1142    }
1143
1144    fn check_schema_hash_on(conn: &Connection) -> Result<bool> {
1145        let current = env!("CACHE_SCHEMA_HASH");
1146        let stored: Option<String> = conn
1147            .query_row(
1148                "SELECT value FROM statistics WHERE key = 'schema_hash'",
1149                [],
1150                |row| row.get(0),
1151            )
1152            .optional()?;
1153        Ok(stored.as_deref() == Some(current))
1154    }
1155
1156    /// Whether this cache's dependency, export and symbol rows were written by
1157    /// this binary's extraction code (see `build.rs`, `EXTRACTION_HASH`).
1158    pub fn check_extraction_hash(&self) -> Result<bool> {
1159        let db_path = self.cache_path.join(META_DB);
1160        if !db_path.exists() {
1161            return Ok(false);
1162        }
1163        let conn = open_meta_db(&db_path)?;
1164        let stored: Option<String> = conn
1165            .query_row(
1166                "SELECT value FROM statistics WHERE key = 'extraction_hash'",
1167                [],
1168                |row| row.get(0),
1169            )
1170            .optional()?;
1171        Ok(stored.as_deref() == Some(env!("EXTRACTION_HASH")))
1172    }
1173
1174    /// Stamp the extraction hash; called at the end of a complete index run.
1175    pub fn update_extraction_hash(&self) -> Result<()> {
1176        let conn = open_meta_db(self.cache_path.join(META_DB))
1177            .context("Failed to open meta.db for extraction hash update")?;
1178        Self::update_extraction_hash_on(&conn)
1179    }
1180
1181    /// [`Self::update_extraction_hash`] on an open connection.
1182    pub(crate) fn update_extraction_hash_on(conn: &Connection) -> Result<()> {
1183        conn.execute(
1184            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1185            [
1186                "extraction_hash",
1187                env!("EXTRACTION_HASH"),
1188                &chrono::Utc::now().timestamp().to_string(),
1189            ],
1190        )?;
1191        Ok(())
1192    }
1193
1194    /// Delete every symbol cache row; returns how many. A cache without the
1195    /// symbols table (no symbol pass has run) has nothing to delete.
1196    pub fn clear_symbol_cache(&self) -> Result<usize> {
1197        let db_path = self.cache_path.join(META_DB);
1198        if !db_path.exists() {
1199            return Ok(0);
1200        }
1201        let conn = open_meta_db(&db_path)?;
1202        let has_table: bool = conn
1203            .query_row(
1204                "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'symbols'",
1205                [],
1206                |row| row.get::<_, i64>(0),
1207            )
1208            .map(|n| n > 0)?;
1209        if !has_table {
1210            return Ok(0);
1211        }
1212        Ok(conn.execute("DELETE FROM symbols", [])?)
1213    }
1214
1215    /// Everything the freshness check reads from `meta.db`, on ONE connection.
1216    ///
1217    /// The per-query status check used to open three connections (`check_schema_hash`,
1218    /// `branch_exists`, `get_branch_info`); on a 35 MB database each open is not free.
1219    /// `branch` is `None` outside git, in which case only the schema is read.
1220    pub fn status_reads(&self, branch: Option<&str>) -> Result<StatusReads> {
1221        let db_path = self.cache_path.join(META_DB);
1222        if !db_path.exists() {
1223            return Ok(StatusReads {
1224                schema_ok: false,
1225                owner: None,
1226                branch_indexed: false,
1227                branch_info: None,
1228                dirty_at_index: Vec::new(),
1229                rule_files: None,
1230            });
1231        }
1232        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1233
1234        let schema_ok = Self::check_schema_hash_on(&conn).unwrap_or(true);
1235        if !schema_ok {
1236            return Ok(StatusReads {
1237                schema_ok,
1238                owner: Self::cache_owner_on(&conn),
1239                branch_indexed: false,
1240                branch_info: None,
1241                dirty_at_index: Vec::new(),
1242                rule_files: None,
1243            });
1244        }
1245
1246        let rule_files = crate::meta_update::get_statistic(&conn, crate::indexer::RULE_FILES_KEY)
1247            .ok()
1248            .flatten();
1249        let Some(branch) = branch else {
1250            return Ok(StatusReads {
1251                schema_ok,
1252                owner: None,
1253                branch_indexed: false,
1254                branch_info: None,
1255                dirty_at_index: Vec::new(),
1256                rule_files,
1257            });
1258        };
1259
1260        let branch_indexed = Self::branch_exists_on(&conn, branch);
1261        // The `files` table (and content.bin) is global: the baseline is the tree
1262        // the LAST run indexed, whichever branch that was. Its row says which
1263        // commit and when. The current branch's own row is not the baseline:
1264        // after `checkout main` from an indexed side branch, main's row still
1265        // names main's commit, and comparing against it reported `fresh` while the
1266        // index held the side branch's files (2.0.3). Freshness is judged by file
1267        // content, so a branch switch that leaves every byte unchanged is fresh.
1268        let synced =
1269            crate::meta_update::get_statistic(&conn, crate::meta_update::SYNCED_BRANCH_KEY)
1270                .ok()
1271                .flatten();
1272        let branch_info = match synced
1273            .as_deref()
1274            .and_then(|b| Self::get_branch_info_on(&conn, b).ok())
1275        {
1276            Some(info) => Some(info),
1277            None if branch_indexed => Self::get_branch_info_on(&conn, branch).ok(),
1278            None => Self::latest_branch_info_on(&conn).ok(),
1279        };
1280
1281        Ok(StatusReads {
1282            schema_ok,
1283            owner: None,
1284            branch_indexed,
1285            branch_info,
1286            dirty_at_index: Self::dirty_at_index_on(&conn).unwrap_or_default(),
1287            rule_files,
1288        })
1289    }
1290
1291    /// Paths that `git status` listed when the index was last written.
1292    fn dirty_at_index_on(conn: &Connection) -> Result<Vec<String>> {
1293        let mut stmt = conn.prepare("SELECT path FROM files WHERE dirty_at_index = 1")?;
1294        let rows = stmt.query_map([], |row| row.get::<_, String>(0))?;
1295        Ok(rows.collect::<Result<Vec<_>, _>>()?)
1296    }
1297
1298    /// Who wrote this cache: `(version, git_sha)`, when the cache records it.
1299    ///
1300    /// `None` for a cache written before 1.7.2, or none at all.
1301    pub fn cache_owner(&self) -> Option<(String, Option<String>)> {
1302        let db_path = self.cache_path.join(META_DB);
1303        if !db_path.exists() {
1304            return None;
1305        }
1306        let conn = open_meta_db(&db_path).ok()?;
1307        Self::cache_owner_on(&conn)
1308    }
1309
1310    fn cache_owner_on(conn: &Connection) -> Option<(String, Option<String>)> {
1311        let get = |key: &str| -> Option<String> {
1312            conn.query_row("SELECT value FROM statistics WHERE key = ?", [key], |row| {
1313                row.get(0)
1314            })
1315            .optional()
1316            .ok()
1317            .flatten()
1318        };
1319        get("writer_version").map(|v| (v, get("writer_git_sha")))
1320    }
1321
1322    /// Refuse to write a cache a DIFFERENT RELEASED VERSION owns.
1323    ///
1324    /// Cross-version writers into one `.reflex/` is a corruption vector: the field
1325    /// report had three `rfx mcp` servers at two versions sharing a cache, and 1.6.0
1326    /// had already produced `content.bin is too small`.
1327    ///
1328    /// Scoped deliberately narrowly, to the one case that is actually unsafe and
1329    /// actually detectable:
1330    ///
1331    /// * A differing SCHEMA HASH alone is NOT refused. It flips on any change to
1332    ///   cache-critical sources, so it fires for every user on every upgrade and for
1333    ///   every developer on every branch switch. A full rebuild is what it already
1334    ///   triggers, it happens under the workspace `IndexLock`, and it truncates the
1335    ///   binary stores — which is safe.
1336    /// * An UNSTAMPED cache is adopted, not refused. Everything written before 1.7.2
1337    ///   is unstamped, so refusing would break every upgrade.
1338    /// * A cache stamped by a different released version IS refused, because that is
1339    ///   the multi-version-sharing case, and only there can the error name who owns it.
1340    ///
1341    /// `force` (which clears the cache first) and `REFLEX_ALLOW_SCHEMA_REBUILD=1`
1342    /// always pass — taking ownership is what force means.
1343    pub fn assert_writable(&self, force: bool) -> Result<()> {
1344        if force || std::env::var("REFLEX_ALLOW_SCHEMA_REBUILD").is_ok() {
1345            return Ok(());
1346        }
1347
1348        if !self.cache_path.join(META_DB).exists() {
1349            return Ok(());
1350        }
1351
1352        let Some((owner_version, owner_sha)) = self.cache_owner() else {
1353            // Unstamped: written before 1.7.2. Adopt it.
1354            return Ok(());
1355        };
1356
1357        if owner_version == env!("CARGO_PKG_VERSION") {
1358            return Ok(());
1359        }
1360
1361        Err(crate::errors::ReflexError::CacheVersionMismatch {
1362            owner_version,
1363            owner_sha: owner_sha
1364                .map(|s| format!(" (sha {})", &s[..s.len().min(7)]))
1365                .unwrap_or_default(),
1366            this_version: env!("CARGO_PKG_VERSION").to_string(),
1367        }
1368        .into())
1369    }
1370
1371    /// Update cache schema hash in statistics table
1372    ///
1373    /// This should be called after every index operation to ensure the cache
1374    /// is marked as compatible with the current binary version.
1375    pub fn update_schema_hash(&self) -> Result<()> {
1376        let db_path = self.cache_path.join(META_DB);
1377        let conn =
1378            open_meta_db(&db_path).context("Failed to open meta.db for schema hash update")?;
1379        Self::update_schema_hash_on(&conn)
1380    }
1381
1382    /// [`Self::update_schema_hash`] on an open connection.
1383    pub(crate) fn update_schema_hash_on(conn: &Connection) -> Result<()> {
1384        let schema_hash = env!("CACHE_SCHEMA_HASH");
1385        let now = chrono::Utc::now().timestamp();
1386
1387        conn.execute(
1388            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1389            ["schema_hash", schema_hash, &now.to_string()],
1390        )?;
1391        // Keep ownership in step with the hash, so a refusal can always name a version.
1392        conn.execute(
1393            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1394            [
1395                "writer_version",
1396                env!("CARGO_PKG_VERSION"),
1397                &now.to_string(),
1398            ],
1399        )?;
1400        if let Some(sha) = option_env!("REFLEX_GIT_SHA") {
1401            conn.execute(
1402                "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1403                ["writer_git_sha", sha, &now.to_string()],
1404            )?;
1405        }
1406
1407        log::debug!("Updated schema hash to: {}", schema_hash);
1408        Ok(())
1409    }
1410
1411    /// Get list of all indexed files
1412    pub fn list_files(&self) -> Result<Vec<IndexedFile>> {
1413        let db_path = self.cache_path.join(META_DB);
1414
1415        if !db_path.exists() {
1416            return Ok(Vec::new());
1417        }
1418
1419        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1420
1421        let mut stmt =
1422            conn.prepare("SELECT path, language, last_indexed FROM files ORDER BY path")?;
1423
1424        let files = stmt
1425            .query_map([], |row| {
1426                let path: String = row.get(0)?;
1427                let language: String = row.get(1)?;
1428                let last_indexed: i64 = row.get(2)?;
1429
1430                Ok(IndexedFile {
1431                    path,
1432                    language,
1433                    last_indexed: chrono::DateTime::from_timestamp(last_indexed, 0)
1434                        .unwrap_or_else(chrono::Utc::now)
1435                        .to_rfc3339(),
1436                })
1437            })?
1438            .collect::<Result<Vec<_>, _>>()?;
1439
1440        Ok(files)
1441    }
1442
1443    /// Get statistics about the current cache
1444    ///
1445    /// Returns statistics for the current git branch if in a git repo,
1446    /// or global statistics if not in a git repo.
1447    pub fn stats(&self) -> Result<crate::models::IndexStats> {
1448        let db_path = self.cache_path.join(META_DB);
1449
1450        if !db_path.exists() {
1451            // Cache not initialized
1452            return Ok(crate::models::IndexStats {
1453                total_files: 0,
1454                index_size_bytes: 0,
1455                last_updated: chrono::Utc::now().to_rfc3339(),
1456                files_by_language: std::collections::HashMap::new(),
1457                lines_by_language: std::collections::HashMap::new(),
1458                ..Default::default()
1459            });
1460        }
1461
1462        // Determine current branch for branch-aware statistics
1463        let workspace_root = self.workspace_root();
1464        let current_branch = if crate::git::is_git_repo(&workspace_root) {
1465            crate::git::get_git_state(&workspace_root)
1466                .ok()
1467                .map(|state| state.branch)
1468        } else {
1469            Some("_default".to_string())
1470        };
1471        self.stats_on_branch(current_branch)
1472    }
1473
1474    /// [`stats`](Self::stats) for a branch the caller already knows (`"_default"`
1475    /// outside git), without running git again.
1476    pub fn stats_on_branch(
1477        &self,
1478        current_branch: Option<String>,
1479    ) -> Result<crate::models::IndexStats> {
1480        let db_path = self.cache_path.join(META_DB);
1481        if !db_path.exists() {
1482            return self.stats();
1483        }
1484        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1485
1486        log::debug!("stats(): current_branch = {:?}", current_branch);
1487
1488        // Read total files (branch-aware)
1489        let total_files: usize = if let Some(ref branch) = current_branch {
1490            log::debug!("stats(): Counting files for branch '{}'", branch);
1491
1492            // Debug: Check all branches (two full scans: only when debug is on)
1493            let debug = log::log_enabled!(log::Level::Debug);
1494            let branches: Vec<(i64, String, i64)> = if !debug {
1495                Vec::new()
1496            } else {
1497                conn.prepare("SELECT id, name, file_count FROM branches")
1498                    .and_then(|mut stmt| {
1499                        stmt.query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
1500                            .map(|rows| rows.collect())
1501                    })
1502                    .and_then(|result| result)
1503                    .unwrap_or_default()
1504            };
1505
1506            for (id, name, count) in &branches {
1507                log::debug!(
1508                    "stats(): Branch ID={}, Name='{}', FileCount={}",
1509                    id,
1510                    name,
1511                    count
1512                );
1513            }
1514
1515            // Debug: Count file_branches per branch
1516            let fb_counts: Vec<(String, i64)> = if !debug {
1517                Vec::new()
1518            } else {
1519                conn.prepare(
1520                    "SELECT b.name, COUNT(*) FROM file_branches fb
1521                 JOIN branches b ON fb.branch_id = b.id
1522                 GROUP BY b.name",
1523                )
1524                .and_then(|mut stmt| {
1525                    stmt.query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
1526                        .map(|rows| rows.collect())
1527                })
1528                .and_then(|result| result)
1529                .unwrap_or_default()
1530            };
1531
1532            for (name, count) in &fb_counts {
1533                log::debug!(
1534                    "stats(): file_branches count for branch '{}': {}",
1535                    name,
1536                    count
1537                );
1538            }
1539
1540            // Count files for current branch only
1541            let count: usize = conn
1542                .query_row(
1543                    "SELECT COUNT(DISTINCT fb.file_id)
1544                 FROM file_branches fb
1545                 JOIN branches b ON fb.branch_id = b.id
1546                 WHERE b.name = ?",
1547                    [branch],
1548                    |row| row.get(0),
1549                )
1550                .unwrap_or(0);
1551
1552            log::debug!("stats(): Query returned total_files = {}", count);
1553            count
1554        } else {
1555            // No branch info - should not happen, but return 0
1556            log::warn!("stats(): No current_branch detected!");
1557            0
1558        };
1559
1560        // Read last updated timestamp
1561        let last_updated: String = conn
1562            .query_row(
1563                "SELECT updated_at FROM statistics WHERE key = 'total_files'",
1564                [],
1565                |row| {
1566                    let timestamp: i64 = row.get(0)?;
1567                    Ok(chrono::DateTime::from_timestamp(timestamp, 0)
1568                        .unwrap_or_else(chrono::Utc::now)
1569                        .to_rfc3339())
1570                },
1571            )
1572            .unwrap_or_else(|_| chrono::Utc::now().to_rfc3339());
1573
1574        let (index_size_bytes, trigram_index_bytes, corpus_bytes) = self.store_sizes();
1575
1576        // Get file count breakdown by language (branch-aware if possible)
1577        let mut files_by_language = std::collections::HashMap::new();
1578        if let Some(ref branch) = current_branch {
1579            // Query files for current branch only
1580            let mut stmt = conn.prepare(
1581                "SELECT f.language, COUNT(DISTINCT f.id)
1582                 FROM files f
1583                 JOIN file_branches fb ON f.id = fb.file_id
1584                 JOIN branches b ON fb.branch_id = b.id
1585                 WHERE b.name = ?
1586                 GROUP BY f.language",
1587            )?;
1588            let lang_counts = stmt.query_map([branch], |row| {
1589                let language: String = row.get(0)?;
1590                let count: i64 = row.get(1)?;
1591                Ok((language, count as usize))
1592            })?;
1593
1594            for result in lang_counts {
1595                let (language, count) = result?;
1596                files_by_language.insert(language, count);
1597            }
1598        } else {
1599            // Fallback: query all files
1600            let mut stmt =
1601                conn.prepare("SELECT language, COUNT(*) FROM files GROUP BY language")?;
1602            let lang_counts = stmt.query_map([], |row| {
1603                let language: String = row.get(0)?;
1604                let count: i64 = row.get(1)?;
1605                Ok((language, count as usize))
1606            })?;
1607
1608            for result in lang_counts {
1609                let (language, count) = result?;
1610                files_by_language.insert(language, count);
1611            }
1612        }
1613
1614        // Get line count breakdown by language (branch-aware if possible)
1615        let mut lines_by_language = std::collections::HashMap::new();
1616        if let Some(ref branch) = current_branch {
1617            // Query lines for current branch only
1618            let mut stmt = conn.prepare(
1619                "SELECT f.language, SUM(f.line_count)
1620                 FROM files f
1621                 JOIN file_branches fb ON f.id = fb.file_id
1622                 JOIN branches b ON fb.branch_id = b.id
1623                 WHERE b.name = ?
1624                 GROUP BY f.language",
1625            )?;
1626            let line_counts = stmt.query_map([branch], |row| {
1627                let language: String = row.get(0)?;
1628                let count: i64 = row.get(1)?;
1629                Ok((language, count as usize))
1630            })?;
1631
1632            for result in line_counts {
1633                let (language, count) = result?;
1634                lines_by_language.insert(language, count);
1635            }
1636        } else {
1637            // Fallback: query all files
1638            let mut stmt =
1639                conn.prepare("SELECT language, SUM(line_count) FROM files GROUP BY language")?;
1640            let line_counts = stmt.query_map([], |row| {
1641                let language: String = row.get(0)?;
1642                let count: i64 = row.get(1)?;
1643                Ok((language, count as usize))
1644            })?;
1645
1646            for result in line_counts {
1647                let (language, count) = result?;
1648                lines_by_language.insert(language, count);
1649            }
1650        }
1651
1652        Ok(crate::models::IndexStats {
1653            total_files,
1654            index_size_bytes,
1655            last_updated,
1656            files_by_language,
1657            lines_by_language,
1658            corpus_bytes,
1659            trigram_index_bytes,
1660            ..Default::default()
1661        })
1662    }
1663
1664    /// On-disk size of the cache, of its trigram stores, and the live corpus
1665    /// bytes (see `stats_on_branch`).
1666    pub(crate) fn store_sizes(&self) -> (u64, u64, u64) {
1667        // Calculate total cache size (all binary files)
1668        let mut index_size_bytes: u64 = 0;
1669        let mut trigram_index_bytes: u64 = 0;
1670
1671        let summary = crate::snapshot::store_summary(&self.cache_path);
1672        for file_path in [
1673            self.cache_path.join(META_DB),
1674            self.cache_path.join(CONFIG_TOML),
1675        ]
1676        .iter()
1677        .chain(summary.files())
1678        {
1679            if let Ok(metadata) = std::fs::metadata(file_path) {
1680                index_size_bytes += metadata.len();
1681            }
1682        }
1683        for file_path in &summary.trigram_files {
1684            if let Ok(metadata) = std::fs::metadata(file_path) {
1685                trigram_index_bytes += metadata.len();
1686            }
1687        }
1688
1689        // Raw corpus size: the manifest records the live text bytes. A cache
1690        // without one: content.bin stores the concatenated file bytes directly
1691        // after its 32-byte header, and `index_offset` (bytes 16..24) marks where
1692        // they end. Read just the header; never load the store.
1693        let corpus_bytes: u64 = summary.live_corpus_bytes.unwrap_or_else(|| {
1694            use std::io::Read;
1695            std::fs::File::open(&summary.content_files[0])
1696                .ok()
1697                .and_then(|mut f| {
1698                    let mut header = [0u8; 32];
1699                    f.read_exact(&mut header).ok()?;
1700                    if &header[..4] != b"RFCT" {
1701                        return None;
1702                    }
1703                    let index_offset = u64::from_le_bytes(header[16..24].try_into().ok()?);
1704                    Some(index_offset.saturating_sub(32))
1705                })
1706                .unwrap_or(0)
1707        });
1708
1709        (index_size_bytes, trigram_index_bytes, corpus_bytes)
1710    }
1711
1712    /// [`Self::stats_on_branch`] for a branch whose `file_branches` rows name every
1713    /// file (the index run just synced them): the same numbers from `files` alone,
1714    /// one scan instead of three joins.
1715    pub(crate) fn stats_synced(&self) -> Result<crate::models::IndexStats> {
1716        let conn = open_meta_db(self.cache_path.join(META_DB)).context("Failed to open meta.db")?;
1717        let mut files_by_language = std::collections::HashMap::new();
1718        let mut lines_by_language = std::collections::HashMap::new();
1719        let mut total_files = 0usize;
1720        {
1721            let mut stmt = conn.prepare(
1722                "SELECT language, COUNT(*), SUM(line_count) FROM files GROUP BY language",
1723            )?;
1724            let rows = stmt.query_map([], |row| {
1725                Ok((
1726                    row.get::<_, String>(0)?,
1727                    row.get::<_, i64>(1)? as usize,
1728                    row.get::<_, i64>(2)? as usize,
1729                ))
1730            })?;
1731            for row in rows {
1732                let (language, files, lines) = row?;
1733                total_files += files;
1734                files_by_language.insert(language.clone(), files);
1735                lines_by_language.insert(language, lines);
1736            }
1737        }
1738        let last_updated: String = conn
1739            .query_row(
1740                "SELECT updated_at FROM statistics WHERE key = 'total_files'",
1741                [],
1742                |row| {
1743                    let timestamp: i64 = row.get(0)?;
1744                    Ok(chrono::DateTime::from_timestamp(timestamp, 0)
1745                        .unwrap_or_else(chrono::Utc::now)
1746                        .to_rfc3339())
1747                },
1748            )
1749            .unwrap_or_else(|_| chrono::Utc::now().to_rfc3339());
1750        let (index_size_bytes, trigram_index_bytes, corpus_bytes) = self.store_sizes();
1751        Ok(crate::models::IndexStats {
1752            total_files,
1753            index_size_bytes,
1754            last_updated,
1755            files_by_language,
1756            lines_by_language,
1757            corpus_bytes,
1758            trigram_index_bytes,
1759            ..Default::default()
1760        })
1761    }
1762
1763    // ===== Branch-aware indexing methods =====
1764
1765    /// Get or create a branch ID by name
1766    ///
1767    /// Returns the numeric branch ID, creating a new entry if needed.
1768    pub(crate) fn get_or_create_branch_id(
1769        &self,
1770        conn: &Connection,
1771        branch_name: &str,
1772        commit_sha: Option<&str>,
1773    ) -> Result<i64> {
1774        // Try to get existing branch
1775        let existing_id: Option<i64> = conn
1776            .query_row(
1777                "SELECT id FROM branches WHERE name = ?",
1778                [branch_name],
1779                |row| row.get(0),
1780            )
1781            .optional()?;
1782
1783        if let Some(id) = existing_id {
1784            return Ok(id);
1785        }
1786
1787        // Create new branch entry
1788        let now = chrono::Utc::now().timestamp();
1789        conn.execute(
1790            "INSERT INTO branches (name, commit_sha, last_indexed, file_count, is_dirty)
1791             VALUES (?, ?, ?, 0, 0)",
1792            [
1793                branch_name,
1794                commit_sha.unwrap_or("unknown"),
1795                &now.to_string(),
1796            ],
1797        )?;
1798
1799        // Get the ID we just created
1800        let id: i64 = conn.last_insert_rowid();
1801        Ok(id)
1802    }
1803
1804    /// Record a file's hash for a specific branch
1805    pub fn record_branch_file(
1806        &self,
1807        path: &str,
1808        branch: &str,
1809        hash: &str,
1810        commit_sha: Option<&str>,
1811    ) -> Result<()> {
1812        let db_path = self.cache_path.join(META_DB);
1813        let conn =
1814            open_meta_db(&db_path).context("Failed to open meta.db for branch file recording")?;
1815
1816        // Lookup file_id from path
1817        let file_id: i64 = conn
1818            .query_row("SELECT id FROM files WHERE path = ?", [path], |row| {
1819                row.get(0)
1820            })
1821            .context(format!("File not found in index: {}", path))?;
1822
1823        // Get or create branch_id
1824        let branch_id = self.get_or_create_branch_id(&conn, branch, commit_sha)?;
1825
1826        let now = chrono::Utc::now().timestamp();
1827
1828        // Insert using proper INTEGER types (not strings!)
1829        conn.execute(
1830            "INSERT OR REPLACE INTO file_branches (file_id, branch_id, hash, last_indexed)
1831             VALUES (?, ?, ?, ?)",
1832            rusqlite::params![file_id, branch_id, hash, now],
1833        )?;
1834
1835        Ok(())
1836    }
1837
1838    /// Batch record multiple files for a specific branch in a single transaction
1839    ///
1840    /// IMPORTANT: Files must already exist in the `files` table before calling this method.
1841    /// For atomic insertion of both files and branch hashes, use `batch_update_files_and_branch()` instead.
1842    pub fn batch_record_branch_files(
1843        &self,
1844        files: &[(String, String)], // (path, hash)
1845        branch: &str,
1846        commit_sha: Option<&str>,
1847    ) -> Result<()> {
1848        log::info!(
1849            "batch_record_branch_files: Processing {} files for branch '{}'",
1850            files.len(),
1851            branch
1852        );
1853
1854        let db_path = self.cache_path.join(META_DB);
1855        let mut conn =
1856            open_meta_db(&db_path).context("Failed to open meta.db for batch branch recording")?;
1857
1858        let now = chrono::Utc::now().timestamp();
1859
1860        // Use a transaction for batch inserts
1861        let tx = conn.transaction()?;
1862
1863        // Get or create branch_id (use transaction connection)
1864        let branch_id = self.get_or_create_branch_id(&tx, branch, commit_sha)?;
1865        log::debug!("Got branch_id={} for branch '{}'", branch_id, branch);
1866
1867        let mut inserted = 0;
1868        for (path, hash) in files {
1869            // Lookup file_id from path
1870            log::trace!("Looking up file_id for path: {}", path);
1871            let file_id: i64 = tx
1872                .query_row(
1873                    "SELECT id FROM files WHERE path = ?",
1874                    [path.as_str()],
1875                    |row| row.get(0),
1876                )
1877                .context(format!("File not found in index: {}", path))?;
1878            log::trace!("Found file_id={} for path: {}", file_id, path);
1879
1880            // Insert using proper INTEGER types (not strings!)
1881            tx.execute(
1882                "INSERT OR REPLACE INTO file_branches (file_id, branch_id, hash, last_indexed)
1883                 VALUES (?, ?, ?, ?)",
1884                rusqlite::params![file_id, branch_id, hash.as_str(), now],
1885            )?;
1886            inserted += 1;
1887        }
1888
1889        log::info!("Inserted {} file_branches entries", inserted);
1890        tx.commit()?;
1891        log::info!("Transaction committed successfully");
1892        Ok(())
1893    }
1894
1895    /// Get all files indexed for a specific branch
1896    ///
1897    /// Returns a HashMap of path → hash for all files in the branch.
1898    pub fn get_branch_files(&self, branch: &str) -> Result<HashMap<String, String>> {
1899        let db_path = self.cache_path.join(META_DB);
1900
1901        if !db_path.exists() {
1902            return Ok(HashMap::new());
1903        }
1904
1905        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1906
1907        let mut stmt = conn.prepare(
1908            "SELECT f.path, fb.hash
1909             FROM file_branches fb
1910             JOIN files f ON fb.file_id = f.id
1911             JOIN branches b ON fb.branch_id = b.id
1912             WHERE b.name = ?",
1913        )?;
1914        let files: HashMap<String, String> = stmt
1915            .query_map([branch], |row| Ok((row.get(0)?, row.get(1)?)))?
1916            .collect::<Result<HashMap<_, _>, _>>()?;
1917
1918        log::debug!(
1919            "Loaded {} files for branch '{}' from file_branches table",
1920            files.len(),
1921            branch
1922        );
1923        Ok(files)
1924    }
1925
1926    /// Check if a branch has any indexed files
1927    ///
1928    /// Fast existence check using LIMIT 1 for O(1) performance.
1929    pub fn branch_exists(&self, branch: &str) -> Result<bool> {
1930        let db_path = self.cache_path.join(META_DB);
1931
1932        if !db_path.exists() {
1933            return Ok(false);
1934        }
1935
1936        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1937        Ok(Self::branch_exists_on(&conn, branch))
1938    }
1939
1940    fn branch_exists_on(conn: &Connection, branch: &str) -> bool {
1941        let count: i64 = conn
1942            .query_row(
1943                "SELECT COUNT(*)
1944                 FROM file_branches fb
1945                 JOIN branches b ON fb.branch_id = b.id
1946                 WHERE b.name = ?
1947                 LIMIT 1",
1948                [branch],
1949                |row| row.get(0),
1950            )
1951            .unwrap_or(0);
1952        count > 0
1953    }
1954
1955    /// Get branch metadata (commit, last_indexed, file_count, dirty status)
1956    pub fn get_branch_info(&self, branch: &str) -> Result<BranchInfo> {
1957        let db_path = self.cache_path.join(META_DB);
1958
1959        if !db_path.exists() {
1960            anyhow::bail!("Database not initialized");
1961        }
1962
1963        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1964        Self::get_branch_info_on(&conn, branch)
1965    }
1966
1967    /// The most recently written branch row, whatever its name.
1968    pub(crate) fn latest_branch_info_on(conn: &Connection) -> Result<BranchInfo> {
1969        let info = conn.query_row(
1970            "SELECT name, commit_sha, last_indexed, file_count, is_dirty FROM branches
1971             ORDER BY last_indexed DESC LIMIT 1",
1972            [],
1973            |row| {
1974                Ok(BranchInfo {
1975                    branch: row.get(0)?,
1976                    commit_sha: row.get(1)?,
1977                    last_indexed: row.get(2)?,
1978                    file_count: row.get(3)?,
1979                    is_dirty: row.get::<_, i64>(4)? != 0,
1980                })
1981            },
1982        )?;
1983        Ok(info)
1984    }
1985
1986    fn get_branch_info_on(conn: &Connection, branch: &str) -> Result<BranchInfo> {
1987        let info = conn.query_row(
1988            "SELECT commit_sha, last_indexed, file_count, is_dirty FROM branches WHERE name = ?",
1989            [branch],
1990            |row| {
1991                Ok(BranchInfo {
1992                    branch: branch.to_string(),
1993                    commit_sha: row.get(0)?,
1994                    last_indexed: row.get(1)?,
1995                    file_count: row.get(2)?,
1996                    is_dirty: row.get::<_, i64>(3)? != 0,
1997                })
1998            },
1999        )?;
2000
2001        Ok(info)
2002    }
2003
2004    /// Update branch metadata after indexing
2005    ///
2006    /// Uses UPDATE instead of INSERT OR REPLACE to preserve branch_id and prevent
2007    /// CASCADE DELETE on file_branches table.
2008    pub fn update_branch_metadata(
2009        &self,
2010        branch: &str,
2011        commit_sha: Option<&str>,
2012        file_count: usize,
2013        is_dirty: bool,
2014    ) -> Result<()> {
2015        let db_path = self.cache_path.join(META_DB);
2016        let conn =
2017            open_meta_db(&db_path).context("Failed to open meta.db for branch metadata update")?;
2018        Self::update_branch_metadata_on(&conn, branch, commit_sha, file_count, is_dirty)
2019    }
2020
2021    /// [`Self::update_branch_metadata`] on an open connection.
2022    pub(crate) fn update_branch_metadata_on(
2023        conn: &Connection,
2024        branch: &str,
2025        commit_sha: Option<&str>,
2026        file_count: usize,
2027        is_dirty: bool,
2028    ) -> Result<()> {
2029        let now = chrono::Utc::now().timestamp();
2030        let is_dirty_int = if is_dirty { 1 } else { 0 };
2031
2032        // Try UPDATE first to preserve branch_id (prevents CASCADE DELETE)
2033        let rows_updated = conn.execute(
2034            "UPDATE branches
2035             SET commit_sha = ?, last_indexed = ?, file_count = ?, is_dirty = ?
2036             WHERE name = ?",
2037            rusqlite::params![
2038                commit_sha.unwrap_or("unknown"),
2039                now,
2040                file_count,
2041                is_dirty_int,
2042                branch
2043            ],
2044        )?;
2045
2046        // If no rows updated (branch doesn't exist yet), INSERT new one
2047        if rows_updated == 0 {
2048            conn.execute(
2049                "INSERT INTO branches (name, commit_sha, last_indexed, file_count, is_dirty)
2050                 VALUES (?, ?, ?, ?, ?)",
2051                rusqlite::params![
2052                    branch,
2053                    commit_sha.unwrap_or("unknown"),
2054                    now,
2055                    file_count,
2056                    is_dirty_int
2057                ],
2058            )?;
2059        }
2060
2061        log::debug!(
2062            "Updated branch metadata for '{}': commit={}, files={}, dirty={}",
2063            branch,
2064            commit_sha.unwrap_or("unknown"),
2065            file_count,
2066            is_dirty
2067        );
2068        Ok(())
2069    }
2070
2071    /// Find a file with a specific hash (for symbol reuse optimization)
2072    ///
2073    /// Returns the path and branch where this hash was first seen,
2074    /// enabling reuse of parsed symbols across branches.
2075    pub fn find_file_with_hash(&self, hash: &str) -> Result<Option<(String, String)>> {
2076        let db_path = self.cache_path.join(META_DB);
2077
2078        if !db_path.exists() {
2079            return Ok(None);
2080        }
2081
2082        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
2083
2084        let result = conn
2085            .query_row(
2086                "SELECT f.path, b.name
2087                 FROM file_branches fb
2088                 JOIN files f ON fb.file_id = f.id
2089                 JOIN branches b ON fb.branch_id = b.id
2090                 WHERE fb.hash = ?
2091                 LIMIT 1",
2092                [hash],
2093                |row| Ok((row.get(0)?, row.get(1)?)),
2094            )
2095            .optional()?;
2096
2097        Ok(result)
2098    }
2099
2100    /// Get file ID by path
2101    ///
2102    /// Returns the integer ID for a file path, or None if not found.
2103    pub fn get_file_id(&self, path: &str) -> Result<Option<i64>> {
2104        let db_path = self.cache_path.join(META_DB);
2105
2106        if !db_path.exists() {
2107            return Ok(None);
2108        }
2109
2110        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
2111
2112        let result = conn
2113            .query_row("SELECT id FROM files WHERE path = ?", [path], |row| {
2114                row.get(0)
2115            })
2116            .optional()?;
2117
2118        Ok(result)
2119    }
2120
2121    /// Batch get file IDs for multiple paths
2122    ///
2123    /// Returns a HashMap of path → file_id for all found paths.
2124    /// Paths not in the database are omitted from the result.
2125    ///
2126    /// Automatically chunks large batches to avoid SQLite parameter limits (999 max).
2127    pub fn batch_get_file_ids(&self, paths: &[String]) -> Result<HashMap<String, i64>> {
2128        let db_path = self.cache_path.join(META_DB);
2129
2130        if !db_path.exists() {
2131            return Ok(HashMap::new());
2132        }
2133
2134        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
2135
2136        // SQLite has a limit of 999 parameters by default
2137        // Chunk requests to stay well under that limit
2138        const BATCH_SIZE: usize = 900;
2139
2140        let mut results = HashMap::new();
2141
2142        for chunk in paths.chunks(BATCH_SIZE) {
2143            // Build IN clause for this chunk
2144            let placeholders = chunk.iter().map(|_| "?").collect::<Vec<_>>().join(", ");
2145
2146            let query = format!(
2147                "SELECT path, id FROM files WHERE path IN ({})",
2148                placeholders
2149            );
2150
2151            let params: Vec<&str> = chunk.iter().map(|s| s.as_str()).collect();
2152            let mut stmt = conn.prepare(&query)?;
2153
2154            let chunk_results = stmt
2155                .query_map(rusqlite::params_from_iter(params), |row| {
2156                    Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
2157                })?
2158                .collect::<Result<HashMap<_, _>, _>>()?;
2159
2160            results.extend(chunk_results);
2161        }
2162
2163        log::debug!(
2164            "Batch loaded {} file IDs (out of {} requested, {} chunks)",
2165            results.len(),
2166            paths.len(),
2167            paths.len().div_ceil(BATCH_SIZE)
2168        );
2169        Ok(results)
2170    }
2171
2172    // ===== Cache compaction methods =====
2173
2174    /// Check if cache compaction should run
2175    ///
2176    /// Returns true if 24+ hours have passed since last compaction (or never compacted).
2177    /// Compaction threshold: 86400 seconds (24 hours)
2178    pub fn should_compact(&self) -> Result<bool> {
2179        let db_path = self.cache_path.join(META_DB);
2180
2181        if !db_path.exists() {
2182            // No database means no compaction needed
2183            return Ok(false);
2184        }
2185
2186        let conn = open_meta_db(&db_path).context("Failed to open meta.db for compaction check")?;
2187
2188        // Get last_compaction timestamp (defaults to "0" if not found)
2189        let last_compaction: i64 = conn
2190            .query_row(
2191                "SELECT value FROM statistics WHERE key = 'last_compaction'",
2192                [],
2193                |row| {
2194                    let value: String = row.get(0)?;
2195                    Ok(value.parse::<i64>().unwrap_or(0))
2196                },
2197            )
2198            .unwrap_or(0);
2199
2200        // Get current timestamp
2201        let now = chrono::Utc::now().timestamp();
2202
2203        // Compaction threshold: 24 hours (86400 seconds)
2204        const COMPACTION_THRESHOLD_SECS: i64 = 86400;
2205
2206        let elapsed_secs = now - last_compaction;
2207        let should_run = elapsed_secs >= COMPACTION_THRESHOLD_SECS;
2208
2209        log::debug!(
2210            "Compaction check: last={}, now={}, elapsed={}s, should_compact={}",
2211            last_compaction,
2212            now,
2213            elapsed_secs,
2214            should_run
2215        );
2216
2217        Ok(should_run)
2218    }
2219
2220    /// Update last_compaction timestamp in statistics table
2221    ///
2222    /// Called after successful compaction to record when it ran.
2223    pub fn update_compaction_timestamp(&self) -> Result<()> {
2224        let db_path = self.cache_path.join(META_DB);
2225        let conn = open_meta_db(&db_path)
2226            .context("Failed to open meta.db for compaction timestamp update")?;
2227
2228        let now = chrono::Utc::now().timestamp();
2229
2230        conn.execute(
2231            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
2232            ["last_compaction", &now.to_string(), &now.to_string()],
2233        )?;
2234
2235        log::debug!("Updated last_compaction timestamp to: {}", now);
2236        Ok(())
2237    }
2238
2239    /// Compact the cache by removing deleted files and reclaiming disk space
2240    ///
2241    /// This operation:
2242    /// 1. Identifies files in the database that no longer exist on disk
2243    /// 2. Deletes those files from all database tables (CASCADE handles related data)
2244    /// 3. Runs VACUUM to reclaim disk space from deleted rows
2245    /// 4. Updates the last_compaction timestamp
2246    ///
2247    /// Returns a CompactionReport with statistics about the operation.
2248    /// Safe to run concurrently with queries (uses SQLite transactions).
2249    pub fn compact(&self) -> Result<crate::models::CompactionReport> {
2250        let start_time = std::time::Instant::now();
2251        log::info!("Starting cache compaction...");
2252
2253        // Get initial cache size
2254        let size_before = self.calculate_cache_size()?;
2255
2256        // Deleted files are NOT removed here. An index run removes a file's row
2257        // and tombstones it in the stores in one publish; removing only the row
2258        // left the stores returning the file while the freshness check (which
2259        // compares rows with the disk) could no longer see the deletion.
2260        let free_pages: i64 = {
2261            let conn = open_meta_db(self.cache_path.join(META_DB))?;
2262            conn.query_row("PRAGMA freelist_count", [], |r| r.get(0))
2263                .unwrap_or(0)
2264        };
2265        if free_pages > 0 {
2266            self.vacuum_database()?;
2267            log::info!("Completed VACUUM operation ({} free pages)", free_pages);
2268        }
2269
2270        let size_after = self.calculate_cache_size()?;
2271        let space_saved = size_before.saturating_sub(size_after);
2272        self.update_compaction_timestamp()?;
2273        let duration_ms = start_time.elapsed().as_millis() as u64;
2274        log::info!(
2275            "Cache compaction completed: {} bytes saved, took {}ms",
2276            space_saved,
2277            duration_ms
2278        );
2279
2280        Ok(crate::models::CompactionReport {
2281            files_removed: 0,
2282            space_saved_bytes: space_saved,
2283            duration_ms,
2284        })
2285    }
2286
2287    /// Run VACUUM on SQLite database to reclaim disk space
2288    ///
2289    /// VACUUM rebuilds the database file, removing free pages and compacting the file.
2290    /// This can take several seconds on large databases but significantly reduces disk usage.
2291    fn vacuum_database(&self) -> Result<()> {
2292        let db_path = self.cache_path.join(META_DB);
2293        let conn = open_meta_db(&db_path).context("Failed to open meta.db for VACUUM")?;
2294
2295        // VACUUM cannot run inside a transaction
2296        // It rebuilds the entire database file
2297        conn.execute("VACUUM", [])?;
2298
2299        log::debug!("VACUUM completed successfully");
2300        Ok(())
2301    }
2302
2303    /// Calculate total cache size in bytes
2304    ///
2305    /// Sums up the size of all cache files:
2306    /// - meta.db (SQLite database)
2307    /// - trigrams.bin (inverted index)
2308    /// - content.bin (file contents)
2309    /// - config.toml (configuration)
2310    fn calculate_cache_size(&self) -> Result<u64> {
2311        let mut total_size: u64 = 0;
2312
2313        let summary = crate::snapshot::store_summary(&self.cache_path);
2314        for file_path in [
2315            self.cache_path.join(META_DB),
2316            self.cache_path.join(CONFIG_TOML),
2317        ]
2318        .iter()
2319        .chain(summary.files())
2320        {
2321            if let Ok(metadata) = std::fs::metadata(file_path) {
2322                total_size += metadata.len();
2323            }
2324        }
2325
2326        Ok(total_size)
2327    }
2328}
2329
2330/// Result of [`CacheManager::status_reads`].
2331#[derive(Debug, Clone)]
2332pub struct StatusReads {
2333    /// The stored schema hash matches this binary.
2334    pub schema_ok: bool,
2335    /// `(version, git_sha)` of the writer, read only when `schema_ok` is false.
2336    pub owner: Option<(String, Option<String>)>,
2337    /// The current branch has indexed files.
2338    pub branch_indexed: bool,
2339    /// Branch metadata, when the branch is indexed.
2340    pub branch_info: Option<BranchInfo>,
2341    /// Paths `git status` listed when the index was written. They must be
2342    /// re-checked by content even when git now reports them clean.
2343    pub dirty_at_index: Vec<String>,
2344    /// The rule-file record of the last index run (`indexer::RULE_FILES_KEY`),
2345    /// when the schema matches.
2346    pub rule_files: Option<String>,
2347}
2348
2349/// One `files` row as the indexer writes it.
2350#[derive(Debug, Clone)]
2351pub struct FileRow {
2352    /// Workspace-relative path with forward slashes.
2353    pub path: String,
2354    /// blake3 of the bytes written to content.bin.
2355    pub hash: String,
2356    /// `format!("{:?}", Language)`.
2357    pub language: String,
2358    pub line_count: usize,
2359    pub size: u64,
2360    /// See [`mtime_ns`]; `0` when unknown, which forces a hash on the next check.
2361    pub mtime_ns: i64,
2362    /// `git status` listed this path when it was indexed.
2363    pub dirty: bool,
2364    /// Position in walk order (see [`WALK_SEQ_GAP`]). Every output that used to
2365    /// list files by `files.id` sorts by this instead: a full build numbers files
2366    /// in walk order, and ids stay stable across updates.
2367    pub walk_seq: i64,
2368}
2369
2370/// Spacing of `files.walk_seq` in a full build (`position * WALK_SEQ_GAP`), so a
2371/// file added later can take a value between its neighbours without renumbering.
2372pub const WALK_SEQ_GAP: i64 = 1 << 20;
2373
2374/// What freshness compares a file on disk against.
2375#[derive(Debug, Clone, PartialEq, Eq)]
2376pub struct FileFingerprint {
2377    pub size: u64,
2378    pub mtime_ns: i64,
2379    pub hash: String,
2380}
2381
2382impl FileFingerprint {
2383    /// Whether `md` describes a file that has not been touched since indexing.
2384    ///
2385    /// A mismatch is not proof of change (a `touch`, an edit reverted byte for
2386    /// byte); the caller then hashes. `mtime_ns == 0` means "unknown", never equal.
2387    pub fn stat_matches(&self, md: &std::fs::Metadata) -> bool {
2388        self.mtime_ns != 0 && self.size == md.len() && self.mtime_ns == mtime_ns(md)
2389    }
2390}
2391
2392/// Modification time as nanoseconds since the Unix epoch, `0` when unavailable.
2393/// The size and mtime a walk records for a file: all that change detection and a
2394/// stored fingerprint need (24 bytes, where a `Metadata` is ~150; a walk keeps one
2395/// per file).
2396#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2397pub struct FileStat {
2398    len: u64,
2399    modified: Option<std::time::SystemTime>,
2400}
2401
2402impl FileStat {
2403    pub fn of(md: &std::fs::Metadata) -> Self {
2404        Self {
2405            len: md.len(),
2406            modified: md.modified().ok(),
2407        }
2408    }
2409
2410    pub fn size(&self) -> u64 {
2411        self.len
2412    }
2413
2414    /// See [`mtime_ns`].
2415    pub fn mtime_ns(&self) -> i64 {
2416        self.modified
2417            .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
2418            .map(|d| d.as_nanos().min(i64::MAX as u128) as i64)
2419            .unwrap_or(0)
2420    }
2421
2422    /// See [`recorded_mtime_ns`].
2423    pub fn recorded_mtime_ns(&self, run_start: std::time::SystemTime) -> i64 {
2424        match self.modified {
2425            Some(t) if t < run_start => self.mtime_ns(),
2426            _ => 0,
2427        }
2428    }
2429}
2430
2431pub fn mtime_ns(md: &std::fs::Metadata) -> i64 {
2432    md.modified()
2433        .ok()
2434        .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
2435        .map(|d| d.as_nanos().min(i64::MAX as u128) as i64)
2436        .unwrap_or(0)
2437}
2438
2439/// The mtime to record for a file read during an index run that began at `run_start`.
2440///
2441/// A write landing in the same clock tick as the read could leave the index with the
2442/// old bytes and the new mtime (git's "racy" case). A file modified at or after the
2443/// run started records `0`, so the next status check hashes it instead of trusting
2444/// the stat.
2445pub fn recorded_mtime_ns(md: &std::fs::Metadata, run_start: std::time::SystemTime) -> i64 {
2446    match md.modified() {
2447        Ok(t) if t < run_start => mtime_ns(md),
2448        _ => 0,
2449    }
2450}
2451
2452/// Branch metadata information
2453#[derive(Debug, Clone)]
2454pub struct BranchInfo {
2455    pub branch: String,
2456    pub commit_sha: String,
2457    pub last_indexed: i64,
2458    pub file_count: usize,
2459    pub is_dirty: bool,
2460}
2461
2462#[cfg(test)]
2463mod tests {
2464    use super::*;
2465    use tempfile::TempDir;
2466
2467    #[test]
2468    fn test_cache_init() {
2469        let temp = TempDir::new().unwrap();
2470        let cache = CacheManager::new(temp.path());
2471
2472        assert!(!cache.exists());
2473        cache.init().unwrap();
2474        assert!(cache.exists());
2475        assert!(cache.path().exists());
2476
2477        // Verify all expected files were created
2478        assert!(cache.path().join(META_DB).exists());
2479        assert!(cache.path().join(CONFIG_TOML).exists());
2480    }
2481
2482    #[test]
2483    fn test_cache_init_idempotent() {
2484        let temp = TempDir::new().unwrap();
2485        let cache = CacheManager::new(temp.path());
2486
2487        // Initialize twice - should not error
2488        cache.init().unwrap();
2489        cache.init().unwrap();
2490
2491        assert!(cache.exists());
2492    }
2493
2494    #[test]
2495    fn test_cache_clear() {
2496        let temp = TempDir::new().unwrap();
2497        let cache = CacheManager::new(temp.path());
2498
2499        cache.init().unwrap();
2500        assert!(cache.exists());
2501
2502        cache.clear().unwrap();
2503        assert!(!cache.exists());
2504    }
2505
2506    #[test]
2507    fn test_cache_clear_nonexistent() {
2508        let temp = TempDir::new().unwrap();
2509        let cache = CacheManager::new(temp.path());
2510
2511        // Clearing non-existent cache should not error
2512        assert!(!cache.exists());
2513        cache.clear().unwrap();
2514        assert!(!cache.exists());
2515    }
2516
2517    #[test]
2518    fn test_load_all_hashes_empty() {
2519        let temp = TempDir::new().unwrap();
2520        let cache = CacheManager::new(temp.path());
2521
2522        cache.init().unwrap();
2523        let hashes = cache.load_all_hashes().unwrap();
2524        assert_eq!(hashes.len(), 0);
2525    }
2526
2527    #[test]
2528    fn test_load_all_hashes_before_init() {
2529        let temp = TempDir::new().unwrap();
2530        let cache = CacheManager::new(temp.path());
2531
2532        // Loading hashes before init should return empty map
2533        let hashes = cache.load_all_hashes().unwrap();
2534        assert_eq!(hashes.len(), 0);
2535    }
2536
2537    #[test]
2538    fn test_load_hashes_for_branch_empty() {
2539        let temp = TempDir::new().unwrap();
2540        let cache = CacheManager::new(temp.path());
2541
2542        cache.init().unwrap();
2543        let hashes = cache.load_hashes_for_branch("main").unwrap();
2544        assert_eq!(hashes.len(), 0);
2545    }
2546
2547    #[test]
2548    fn test_update_file() {
2549        let temp = TempDir::new().unwrap();
2550        let cache = CacheManager::new(temp.path());
2551
2552        cache.init().unwrap();
2553        cache.update_file("src/main.rs", "rust", 100).unwrap();
2554
2555        // Verify file was stored (check via list_files)
2556        let files = cache.list_files().unwrap();
2557        assert_eq!(files.len(), 1);
2558        assert_eq!(files[0].path, "src/main.rs");
2559        assert_eq!(files[0].language, "rust");
2560    }
2561
2562    #[test]
2563    fn test_update_file_multiple() {
2564        let temp = TempDir::new().unwrap();
2565        let cache = CacheManager::new(temp.path());
2566
2567        cache.init().unwrap();
2568        cache.update_file("src/main.rs", "rust", 100).unwrap();
2569        cache.update_file("src/lib.rs", "rust", 200).unwrap();
2570        cache.update_file("README.md", "markdown", 50).unwrap();
2571
2572        // Verify files were stored
2573        let files = cache.list_files().unwrap();
2574        assert_eq!(files.len(), 3);
2575    }
2576
2577    #[test]
2578    fn test_update_file_replace() {
2579        let temp = TempDir::new().unwrap();
2580        let cache = CacheManager::new(temp.path());
2581
2582        cache.init().unwrap();
2583        cache.update_file("src/main.rs", "rust", 100).unwrap();
2584        cache.update_file("src/main.rs", "rust", 150).unwrap();
2585
2586        // Second update should replace the first
2587        let files = cache.list_files().unwrap();
2588        assert_eq!(files.len(), 1);
2589        assert_eq!(files[0].path, "src/main.rs");
2590    }
2591
2592    #[test]
2593    fn test_batch_update_files() {
2594        let temp = TempDir::new().unwrap();
2595        let cache = CacheManager::new(temp.path());
2596
2597        cache.init().unwrap();
2598
2599        let files = vec![
2600            ("src/main.rs".to_string(), "rust".to_string(), 100),
2601            ("src/lib.rs".to_string(), "rust".to_string(), 200),
2602            ("test.py".to_string(), "python".to_string(), 50),
2603        ];
2604
2605        cache.batch_update_files(&files).unwrap();
2606
2607        // Verify files were stored
2608        let stored_files = cache.list_files().unwrap();
2609        assert_eq!(stored_files.len(), 3);
2610    }
2611
2612    #[test]
2613    fn test_update_stats() {
2614        let temp = TempDir::new().unwrap();
2615        let cache = CacheManager::new(temp.path());
2616
2617        cache.init().unwrap();
2618        cache.update_file("src/main.rs", "rust", 100).unwrap();
2619        cache.update_file("src/lib.rs", "rust", 200).unwrap();
2620
2621        // Record files for a test branch
2622        cache
2623            .record_branch_file("src/main.rs", "_default", "hash1", None)
2624            .unwrap();
2625        cache
2626            .record_branch_file("src/lib.rs", "_default", "hash2", None)
2627            .unwrap();
2628        cache.update_stats("_default").unwrap();
2629
2630        let stats = cache.stats().unwrap();
2631        assert_eq!(stats.total_files, 2);
2632    }
2633
2634    #[test]
2635    fn test_stats_empty_cache() {
2636        let temp = TempDir::new().unwrap();
2637        let cache = CacheManager::new(temp.path());
2638
2639        cache.init().unwrap();
2640        let stats = cache.stats().unwrap();
2641
2642        assert_eq!(stats.total_files, 0);
2643        assert_eq!(stats.files_by_language.len(), 0);
2644    }
2645
2646    #[test]
2647    fn test_stats_before_init() {
2648        let temp = TempDir::new().unwrap();
2649        let cache = CacheManager::new(temp.path());
2650
2651        // Stats before init should return zeros
2652        let stats = cache.stats().unwrap();
2653        assert_eq!(stats.total_files, 0);
2654    }
2655
2656    #[test]
2657    fn test_stats_by_language() {
2658        let temp = TempDir::new().unwrap();
2659        let cache = CacheManager::new(temp.path());
2660
2661        cache.init().unwrap();
2662        cache.update_file("main.rs", "Rust", 100).unwrap();
2663        cache.update_file("lib.rs", "Rust", 200).unwrap();
2664        cache.update_file("script.py", "Python", 50).unwrap();
2665        cache.update_file("test.py", "Python", 80).unwrap();
2666
2667        // Record files for a test branch
2668        cache
2669            .record_branch_file("main.rs", "_default", "hash1", None)
2670            .unwrap();
2671        cache
2672            .record_branch_file("lib.rs", "_default", "hash2", None)
2673            .unwrap();
2674        cache
2675            .record_branch_file("script.py", "_default", "hash3", None)
2676            .unwrap();
2677        cache
2678            .record_branch_file("test.py", "_default", "hash4", None)
2679            .unwrap();
2680        cache.update_stats("_default").unwrap();
2681
2682        let stats = cache.stats().unwrap();
2683        assert_eq!(stats.files_by_language.get("Rust"), Some(&2));
2684        assert_eq!(stats.files_by_language.get("Python"), Some(&2));
2685        assert_eq!(stats.lines_by_language.get("Rust"), Some(&300)); // 100 + 200
2686        assert_eq!(stats.lines_by_language.get("Python"), Some(&130)); // 50 + 80
2687    }
2688
2689    #[test]
2690    fn test_list_files_empty() {
2691        let temp = TempDir::new().unwrap();
2692        let cache = CacheManager::new(temp.path());
2693
2694        cache.init().unwrap();
2695        let files = cache.list_files().unwrap();
2696        assert_eq!(files.len(), 0);
2697    }
2698
2699    #[test]
2700    fn test_list_files() {
2701        let temp = TempDir::new().unwrap();
2702        let cache = CacheManager::new(temp.path());
2703
2704        cache.init().unwrap();
2705        cache.update_file("src/main.rs", "rust", 100).unwrap();
2706        cache.update_file("src/lib.rs", "rust", 200).unwrap();
2707
2708        let files = cache.list_files().unwrap();
2709        assert_eq!(files.len(), 2);
2710
2711        // Files should be sorted by path
2712        assert_eq!(files[0].path, "src/lib.rs");
2713        assert_eq!(files[1].path, "src/main.rs");
2714
2715        assert_eq!(files[0].language, "rust");
2716    }
2717
2718    #[test]
2719    fn test_list_files_before_init() {
2720        let temp = TempDir::new().unwrap();
2721        let cache = CacheManager::new(temp.path());
2722
2723        // Listing files before init should return empty vec
2724        let files = cache.list_files().unwrap();
2725        assert_eq!(files.len(), 0);
2726    }
2727
2728    #[test]
2729    fn test_branch_exists() {
2730        let temp = TempDir::new().unwrap();
2731        let cache = CacheManager::new(temp.path());
2732
2733        cache.init().unwrap();
2734
2735        assert!(!cache.branch_exists("main").unwrap());
2736
2737        // Add file to index first (required for record_branch_file)
2738        cache.update_file("src/main.rs", "rust", 100).unwrap();
2739        cache
2740            .record_branch_file("src/main.rs", "main", "hash1", Some("commit123"))
2741            .unwrap();
2742
2743        assert!(cache.branch_exists("main").unwrap());
2744        assert!(!cache.branch_exists("feature-branch").unwrap());
2745    }
2746
2747    #[test]
2748    fn test_record_branch_file() {
2749        let temp = TempDir::new().unwrap();
2750        let cache = CacheManager::new(temp.path());
2751
2752        cache.init().unwrap();
2753        // Add file to index first (required for record_branch_file)
2754        cache.update_file("src/main.rs", "rust", 100).unwrap();
2755        cache
2756            .record_branch_file("src/main.rs", "main", "hash1", Some("commit123"))
2757            .unwrap();
2758
2759        let files = cache.get_branch_files("main").unwrap();
2760        assert_eq!(files.len(), 1);
2761        assert_eq!(files.get("src/main.rs"), Some(&"hash1".to_string()));
2762    }
2763
2764    #[test]
2765    fn test_get_branch_files_empty() {
2766        let temp = TempDir::new().unwrap();
2767        let cache = CacheManager::new(temp.path());
2768
2769        cache.init().unwrap();
2770        let files = cache.get_branch_files("nonexistent").unwrap();
2771        assert_eq!(files.len(), 0);
2772    }
2773
2774    #[test]
2775    fn test_batch_record_branch_files() {
2776        let temp = TempDir::new().unwrap();
2777        let cache = CacheManager::new(temp.path());
2778
2779        cache.init().unwrap();
2780
2781        // Add files to index first (required for batch_record_branch_files)
2782        let file_metadata = vec![
2783            ("src/main.rs".to_string(), "rust".to_string(), 100),
2784            ("src/lib.rs".to_string(), "rust".to_string(), 200),
2785            ("README.md".to_string(), "markdown".to_string(), 50),
2786        ];
2787        cache.batch_update_files(&file_metadata).unwrap();
2788
2789        let files = vec![
2790            ("src/main.rs".to_string(), "hash1".to_string()),
2791            ("src/lib.rs".to_string(), "hash2".to_string()),
2792            ("README.md".to_string(), "hash3".to_string()),
2793        ];
2794
2795        cache
2796            .batch_record_branch_files(&files, "main", Some("commit123"))
2797            .unwrap();
2798
2799        let branch_files = cache.get_branch_files("main").unwrap();
2800        assert_eq!(branch_files.len(), 3);
2801        assert_eq!(branch_files.get("src/main.rs"), Some(&"hash1".to_string()));
2802        assert_eq!(branch_files.get("src/lib.rs"), Some(&"hash2".to_string()));
2803        assert_eq!(branch_files.get("README.md"), Some(&"hash3".to_string()));
2804    }
2805
2806    #[test]
2807    fn test_update_branch_metadata() {
2808        let temp = TempDir::new().unwrap();
2809        let cache = CacheManager::new(temp.path());
2810
2811        cache.init().unwrap();
2812        cache
2813            .update_branch_metadata("main", Some("commit123"), 10, false)
2814            .unwrap();
2815
2816        let info = cache.get_branch_info("main").unwrap();
2817        assert_eq!(info.branch, "main");
2818        assert_eq!(info.commit_sha, "commit123");
2819        assert_eq!(info.file_count, 10);
2820        assert!(!info.is_dirty);
2821    }
2822
2823    #[test]
2824    fn test_update_branch_metadata_dirty() {
2825        let temp = TempDir::new().unwrap();
2826        let cache = CacheManager::new(temp.path());
2827
2828        cache.init().unwrap();
2829        cache
2830            .update_branch_metadata("feature", Some("commit456"), 5, true)
2831            .unwrap();
2832
2833        let info = cache.get_branch_info("feature").unwrap();
2834        assert!(info.is_dirty);
2835    }
2836
2837    #[test]
2838    fn test_find_file_with_hash() {
2839        let temp = TempDir::new().unwrap();
2840        let cache = CacheManager::new(temp.path());
2841
2842        cache.init().unwrap();
2843        // Add file to index first (required for record_branch_file)
2844        cache.update_file("src/main.rs", "rust", 100).unwrap();
2845        cache
2846            .record_branch_file("src/main.rs", "main", "unique_hash", Some("commit123"))
2847            .unwrap();
2848
2849        let result = cache.find_file_with_hash("unique_hash").unwrap();
2850        assert!(result.is_some());
2851
2852        let (path, branch) = result.unwrap();
2853        assert_eq!(path, "src/main.rs");
2854        assert_eq!(branch, "main");
2855    }
2856
2857    #[test]
2858    fn test_find_file_with_hash_not_found() {
2859        let temp = TempDir::new().unwrap();
2860        let cache = CacheManager::new(temp.path());
2861
2862        cache.init().unwrap();
2863
2864        let result = cache.find_file_with_hash("nonexistent_hash").unwrap();
2865        assert!(result.is_none());
2866    }
2867
2868    #[test]
2869    fn test_config_toml_created() {
2870        let temp = TempDir::new().unwrap();
2871        let cache = CacheManager::new(temp.path());
2872
2873        cache.init().unwrap();
2874
2875        let config_path = cache.path().join(CONFIG_TOML);
2876        let config_content = std::fs::read_to_string(&config_path).unwrap();
2877
2878        // Verify config contains expected sections
2879        assert!(config_content.contains("[index]"));
2880        assert!(config_content.contains("[performance]"));
2881        assert!(config_content.contains("max_file_size"));
2882        assert!(config_content.contains("symbol_threads"));
2883        // Keys nothing reads must not be advertised.
2884        for dead in [
2885            "[search]",
2886            "default_limit",
2887            "fuzzy_threshold",
2888            "compression_level",
2889            "[semantic]",
2890        ] {
2891            assert!(
2892                !config_content.contains(dead),
2893                "template advertises unused {dead}"
2894            );
2895        }
2896    }
2897
2898    #[test]
2899    fn test_meta_db_schema() {
2900        let temp = TempDir::new().unwrap();
2901        let cache = CacheManager::new(temp.path());
2902
2903        cache.init().unwrap();
2904
2905        let db_path = cache.path().join(META_DB);
2906        let conn = open_meta_db(&db_path).unwrap();
2907
2908        // Verify tables exist
2909        let tables: Vec<String> = conn
2910            .prepare("SELECT name FROM sqlite_master WHERE type='table'")
2911            .unwrap()
2912            .query_map([], |row| row.get(0))
2913            .unwrap()
2914            .collect::<Result<Vec<_>, _>>()
2915            .unwrap();
2916
2917        assert!(tables.contains(&"files".to_string()));
2918        assert!(tables.contains(&"statistics".to_string()));
2919        assert!(tables.contains(&"config".to_string()));
2920        assert!(tables.contains(&"file_branches".to_string()));
2921        assert!(tables.contains(&"branches".to_string()));
2922        assert!(tables.contains(&"file_dependencies".to_string()));
2923        assert!(tables.contains(&"file_exports".to_string()));
2924    }
2925
2926    #[test]
2927    fn test_concurrent_file_updates() {
2928        use std::thread;
2929
2930        let temp = TempDir::new().unwrap();
2931        let cache_path = temp.path().to_path_buf();
2932
2933        let cache = CacheManager::new(&cache_path);
2934        cache.init().unwrap();
2935
2936        // Spawn multiple threads updating different files
2937        let handles: Vec<_> = (0..10)
2938            .map(|i| {
2939                let path = cache_path.clone();
2940                thread::spawn(move || {
2941                    let cache = CacheManager::new(&path);
2942                    cache
2943                        .update_file(&format!("file_{}.rs", i), "rust", i * 10)
2944                        .unwrap();
2945                })
2946            })
2947            .collect();
2948
2949        for handle in handles {
2950            handle.join().unwrap();
2951        }
2952
2953        let cache = CacheManager::new(&cache_path);
2954        let files = cache.list_files().unwrap();
2955        assert_eq!(files.len(), 10);
2956    }
2957
2958    // ===== Corruption Detection Tests =====
2959
2960    #[test]
2961    fn test_validate_corrupted_database() {
2962        use std::io::Write;
2963
2964        let temp = TempDir::new().unwrap();
2965        let cache = CacheManager::new(temp.path());
2966
2967        cache.init().unwrap();
2968
2969        // Corrupt the database by overwriting it with invalid data
2970        let db_path = cache.path().join(META_DB);
2971        let mut file = File::create(&db_path).unwrap();
2972        file.write_all(b"CORRUPTED DATA").unwrap();
2973
2974        // Validation should fail due to database corruption
2975        let result = cache.validate();
2976        assert!(result.is_err());
2977        let err_msg = result.unwrap_err().to_string();
2978        eprintln!("Error message: {}", err_msg);
2979        assert!(err_msg.contains("corrupted") || err_msg.contains("not a database"));
2980    }
2981
2982    #[test]
2983    fn test_validate_corrupted_trigrams() {
2984        use std::io::Write;
2985
2986        let temp = TempDir::new().unwrap();
2987        let cache = CacheManager::new(temp.path());
2988
2989        cache.init().unwrap();
2990
2991        // Create trigrams.bin with invalid magic bytes
2992        let trigrams_path = cache.path().join("trigrams.bin");
2993        let mut file = File::create(&trigrams_path).unwrap();
2994        file.write_all(b"BADM").unwrap(); // Wrong magic bytes (should be "RFTG")
2995
2996        // Validation should fail due to invalid magic bytes
2997        let result = cache.validate();
2998        assert!(result.is_err());
2999        let err = result.unwrap_err().to_string();
3000        assert!(err.contains("trigrams.bin") && err.contains("corrupted"));
3001    }
3002
3003    #[test]
3004    fn test_validate_corrupted_content() {
3005        use std::io::Write;
3006
3007        let temp = TempDir::new().unwrap();
3008        let cache = CacheManager::new(temp.path());
3009
3010        cache.init().unwrap();
3011
3012        // Create content.bin with invalid magic bytes
3013        let content_path = cache.path().join("content.bin");
3014        let mut file = File::create(&content_path).unwrap();
3015        file.write_all(b"BADM").unwrap(); // Wrong magic bytes (should be "RFCT")
3016
3017        // Validation should fail due to invalid magic bytes
3018        let result = cache.validate();
3019        assert!(result.is_err());
3020        let err = result.unwrap_err().to_string();
3021        assert!(err.contains("content.bin") && err.contains("corrupted"));
3022    }
3023
3024    #[test]
3025    fn test_validate_missing_schema_table() {
3026        let temp = TempDir::new().unwrap();
3027        let cache = CacheManager::new(temp.path());
3028
3029        cache.init().unwrap();
3030
3031        // Drop a required table to simulate schema corruption
3032        let db_path = cache.path().join(META_DB);
3033        let conn = open_meta_db(&db_path).unwrap();
3034        conn.execute("DROP TABLE files", []).unwrap();
3035
3036        // Validation should fail due to missing required table
3037        let result = cache.validate();
3038        assert!(result.is_err());
3039        let err = result.unwrap_err().to_string();
3040        assert!(err.contains("files") && err.contains("missing"));
3041    }
3042
3043    #[test]
3044    fn effective_config_uses_the_saved_languages_until_a_run_clears_them() {
3045        use crate::models::Language;
3046        let temp = TempDir::new().unwrap();
3047        let cache = CacheManager::new(temp.path());
3048        cache.init().unwrap();
3049        assert!(
3050            cache
3051                .effective_index_config(&[])
3052                .unwrap()
3053                .languages
3054                .is_empty()
3055        );
3056
3057        cache.set_languages_override(&[Language::Rust]).unwrap();
3058        assert_eq!(
3059            cache.effective_index_config(&[]).unwrap().languages,
3060            vec![Language::Rust]
3061        );
3062        // An explicit list wins over the saved one.
3063        assert_eq!(
3064            cache
3065                .effective_index_config(&[Language::Go])
3066                .unwrap()
3067                .languages,
3068            vec![Language::Go]
3069        );
3070
3071        cache.set_languages_override(&[]).unwrap();
3072        assert!(
3073            cache
3074                .effective_index_config(&[])
3075                .unwrap()
3076                .languages
3077                .is_empty()
3078        );
3079    }
3080}