@pify/search 0.2.0 → 0.3.0

package/README.md

@@ -35,7 +35,7 @@ Three modes because three different questions get asked: the exact string, a sha
 
 ## Three engines, one interface
 
-**native** — this package's own Rust core, `native/`, built with napi. It indexes this suite (417 files) in **33ms**, and a literal search then reads the **5** files the trigram index says could match rather than all 417. Searches come back in about a millisecond.
+**native** — this package's own Rust core, `native/`, built with napi. It indexes this suite (417 files) in about **40ms** cold, and a literal search then reads the **5** files the trigram index says could match rather than all 417. Searches come back in about a millisecond. Its index is [stored between sessions](#the-index-survives-the-process), so the second start does not pay for the first.
 
 **fff** — [`@ff-labs/fff-node`](https://github.com/dmtrKovalenko/fff), used when it is installed and the native core is not. A mature engine with its own watcher and git integration.
 
@@ -61,6 +61,32 @@ Every overlapping three-byte window of every text file is a *trigram*, packed in
 
 The index only ever **narrows**; every surviving candidate is still matched for real, so a wrong candidate costs time and never correctness. The rule that makes it safe: a pattern with nothing indexable — `\d+`, a fuzzy query, one branch of an alternation that could match anywhere — reports "no candidate set is safe" and everything is read. Confusing *that* with "nothing matched" is how an index starts silently hiding results, so the two are different values throughout.
 
+## The index survives the process
+
+An index rebuilt at every start is one you pay for at every start. The native engine writes its index to disk and, next time, reloads it and reconciles instead of re-reading the tree.
+
+Measured on a synthetic 20,000-file tree (`node native/bench.mjs 20000`):
+
+| | build | files read | grep |
+|---|---|---|---|
+| cold (no stored index) | 1320ms | 20,000 | <1ms |
+| warm (unchanged tree) | **188ms** | 0 | <1ms |
+
+**7×**, and the cost that remains is the directory walk, not the files. Editing one file re-reads one file.
+
+Correctness rests on a single rule: a stored entry is trusted only while its **size and mtime still match what is on disk**. Anything changed, new, or vanished is re-read before a query can see it. A cache that answers confidently for a file that has moved on is worse than no cache. The reload path is checked against the rebuild path on every supported platform (`native/persist.mjs`, run in CI) — same totals, same lines, same order — including that a corrupt or truncated index is *discarded* rather than half-trusted.
+
+Trigram lists are stored as varint deltas, which is what makes this worth doing at all: 881KB for this suite, ~2.2KB per file, about a third of the naive encoding. Reading a cache that is larger than the sources it summarises costs more than the rebuild it was meant to avoid.
+
+The index lives in the platform cache directory — `%LOCALAPPDATA%`, `~/Library/Caches`, `$XDG_CACHE_HOME` — keyed by a hash of the absolute root, never inside your working tree.
+
+| variable | effect |
+|---|---|
+| `PIFY_SEARCH_NO_CACHE=1` | never store an index; rebuild every start |
+| `PIFY_SEARCH_CACHE_DIR` | store indexes somewhere else |
+| `PIFY_SEARCH_TIMING=1` | print how long the walk, the reload and the inversion each took |
+| `PIFY_SEARCH_ENGINE` | `builtin` or `fff` to force an engine |
+
 ## Ranking
 
 Frecency decays on a three-day half-life — an agent session is shorter and more concentrated than a human's week, so yesterday's file should not outrank today's. Every `read`, `edit` or `write` in the session counts as an access. History is capped at seven days and 128 timestamps per file, so the store cannot grow without bound.
@@ -71,7 +97,7 @@ This package adds two tools; it does not replace `find`, `grep` or `multi_grep`.
 
 ## Command
 
-`/search` — which engine is running, the indexed root, and how many files it holds.
+`/search` — which engine is running, the indexed root, how many files it holds, and how much of the index came back from the stored copy rather than from disk.
 
 ## License
 

package/native/src/lib.rs

@@ -9,6 +9,7 @@
 #![deny(clippy::all)]
 
 mod score;
+mod store;
 mod trigram;
 mod walk;
 
@@ -67,6 +68,9 @@ pub struct SearchIndex {
     by_path: RwLock<HashMap<String, u32>>,
     content: RwLock<Index>,
     frecency: RwLock<HashMap<String, i32>>,
+    cache: Option<PathBuf>,
+    reused: u32,
+    rebuilt: u32,
 }
 
 #[napi]
@@ -74,10 +78,23 @@ impl SearchIndex {
     /// Build the index. Walking and content extraction run in parallel;
     /// nothing is memory-mapped, so this behaves the same on every platform.
     #[napi(constructor)]
-    pub fn new(root: String, max_files: Option<u32>) -> Result<Self> {
+    pub fn new(root: String, max_files: Option<u32>, cache_path: Option<String>) -> Result<Self> {
         let root_path = PathBuf::from(&root);
         let cap = max_files.unwrap_or(200_000) as usize;
+        let t0 = std::time::Instant::now();
         let found = walk::collect(&root_path, cap);
+        let t_walk = t0.elapsed();
+
+        // Anything the last run already extracted and that still looks the
+        // same on disk is reused; only genuinely changed files are re-read.
+        // That is the whole point of persisting — a session on a large tree
+        // should pay for what changed, not for the tree.
+        let cache = cache_path.as_ref().map(PathBuf::from);
+        let t1 = std::time::Instant::now();
+        let loaded = cache.as_ref().and_then(|p| store::load(p));
+        let t_load = t1.elapsed();
+        let had_cache = loaded.is_some();
+        let mut known = loaded.map(store::index_by_path).unwrap_or_default();
 
         let mut entries = Vec::with_capacity(found.len());
         let mut by_path = HashMap::with_capacity(found.len());
@@ -91,13 +108,25 @@ impl SearchIndex {
             });
         }
 
+        let mut reused = 0usize;
+        let mut carried: Vec<(u32, Vec<u32>)> = Vec::new();
+        let mut stale: Vec<(u32, &walk::Found)> = Vec::new();
+        for (i, file) in found.iter().enumerate() {
+            match known.remove(&file.rel) {
+                Some(entry) if store::still_valid(&entry, file.size, file.mtime_ms) => {
+                    reused += 1;
+                    carried.push((i as u32, entry.trigrams));
+                }
+                _ => stale.push((i as u32, file)),
+            }
+        }
+
         // Reading and extracting is the expensive half and is embarrassingly
         // parallel; building the map from the results is not, so it is done
         // once at the end rather than behind a lock per file.
-        let extracted: Vec<(u32, Vec<u32>)> = found
+        let extracted: Vec<(u32, Vec<u32>)> = stale
             .par_iter()
-            .enumerate()
-            .filter_map(|(i, file)| {
+            .filter_map(|(id, file)| {
                 if !walk::index_content(&file.rel, file.size) {
                     return None;
                 }
@@ -109,22 +138,93 @@ impl SearchIndex {
                 trigram::extract(&bytes, &mut set);
                 let mut list: Vec<u32> = set.into_iter().collect();
                 list.sort_unstable();
-                Some((i as u32, list))
+                Some((*id, list))
             })
             .collect();
 
+        // Merged and sorted by id before insertion, which is not cosmetic:
+        // posting lists are kept sorted, so adding files in ascending order
+        // appends to each list, while the interleaved order that `carried` and
+        // `extracted` arrive in would insert into the middle and memmove the
+        // tail of every list it touches.
+        let rebuilt = extracted.len() as u32;
+        let mut all: Vec<(u32, Vec<u32>)> = carried;
+        all.extend(extracted);
+        all.sort_unstable_by_key(|(id, _)| *id);
+
+        let t2 = std::time::Instant::now();
         let mut index = Index::new();
-        for (id, trigrams) in &extracted {
+        for (id, trigrams) in &all {
             index.add(*id, trigrams);
         }
+        let t_index = t2.elapsed();
+        // Off unless asked for. The three phases have very different costs and
+        // guessing which one dominates is how the first version of this spent
+        // most of its time rebuilding an index it had just loaded.
+        if std::env::var_os("PIFY_SEARCH_TIMING").is_some() {
+            eprintln!("  walk {t_walk:?}  load {t_load:?}  invert {t_index:?}");
+        }
 
-        Ok(Self {
+        // Rewriting an unchanged index costs a full re-inversion and a
+        // multi-megabyte write on every start, which on a large tree is most
+        // of what reloading was supposed to save. Write only when the tree
+        // actually moved: something re-read, something gone, or no cache yet.
+        let vanished = !known.is_empty();
+        let dirty = !had_cache || rebuilt > 0 || vanished;
+
+        let this = Self {
             root: root_path,
             entries: RwLock::new(entries),
             by_path: RwLock::new(by_path),
             content: RwLock::new(index),
             frecency: RwLock::new(HashMap::new()),
-        })
+            cache,
+            reused: reused as u32,
+            rebuilt,
+        };
+        if dirty {
+            this.persist();
+        }
+        Ok(this)
+    }
+
+    /// Write the index back, best effort. A cache that cannot be written costs
+    /// the next session a rebuild, never this one a result.
+    fn persist(&self) {
+        let Some(path) = self.cache.as_ref() else { return };
+        let (Ok(entries), Ok(index)) = (self.entries.read(), self.content.read()) else {
+            return;
+        };
+        let mut by_file = index.by_file();
+        let mut files = Vec::with_capacity(by_file.len());
+        for (id, entry) in entries.iter().enumerate() {
+            if let Some(trigrams) = by_file.remove(&(id as u32)) {
+                files.push(store::StoredFile {
+                    rel: entry.path.clone(),
+                    size: entry.size,
+                    mtime_ms: entry.mtime_ms,
+                    trigrams,
+                });
+            }
+        }
+        let _ = store::save(path, &files);
+    }
+
+    /// How much of the last index survived, so the saving is observable.
+    #[napi]
+    pub fn reused_count(&self) -> u32 {
+        self.reused
+    }
+
+    #[napi]
+    pub fn rebuilt_count(&self) -> u32 {
+        self.rebuilt
+    }
+
+    /// Flush the index to its cache file.
+    #[napi]
+    pub fn save(&self) {
+        self.persist();
     }
 
     #[napi]

package/native/src/store.rs

@@ -0,0 +1,194 @@
+//! Making the index outlive the process.
+//!
+//! An in-memory index is rebuilt every time pi starts. On this suite that
+//! costs 33ms and nobody notices; on a hundred-thousand-file monorepo it is
+//! seconds, paid again at every session, for a tree that has barely changed.
+//! tgrep's answer is the whole reason it is fast in practice — build once,
+//! persist, and on the next start reload and reconcile instead of rebuilding.
+//!
+//! The format is deliberately dull: a header, the file table, then the posting
+//! lists, all little-endian. No mmap, because a memory-mapped file is a
+//! different set of failure modes on every platform and the load is already
+//! bounded by the disk read.
+//!
+//! Correctness rests on one rule. A stored entry is trusted only while its
+//! size and mtime still match what is on disk; anything that differs, or is
+//! new, or has vanished, is re-read before a query can see it. A stale index
+//! that answers confidently is worse than no index at all.
+
+use std::collections::HashMap;
+use std::fs::File;
+use std::io::{BufWriter, Write};
+use std::path::Path;
+
+/// Bumped whenever the layout changes. A mismatch is not an error — it means
+/// the cache is from another version and the tree is simply re-indexed.
+const MAGIC: &[u8; 8] = b"PIFYSRC2";
+
+pub struct StoredFile {
+    pub rel: String,
+    pub size: u64,
+    pub mtime_ms: i64,
+    pub trigrams: Vec<u32>,
+}
+
+fn write_u32(out: &mut impl Write, value: u32) -> std::io::Result<()> {
+    out.write_all(&value.to_le_bytes())
+}
+
+/// Trigram lists are sorted, so the gaps between neighbours are far smaller
+/// than the values themselves and a varint spends one or two bytes where a
+/// fixed `u32` spends four. This is what decides whether persisting is worth
+/// it at all: a cache that is larger than the source it summarises costs more
+/// to read back than the rebuild it was meant to avoid.
+fn write_varint(out: &mut impl Write, mut value: u32) -> std::io::Result<()> {
+    let mut buf = [0u8; 5];
+    let mut len = 0;
+    loop {
+        let byte = (value & 0x7f) as u8;
+        value >>= 7;
+        if value == 0 {
+            buf[len] = byte;
+            len += 1;
+            break;
+        }
+        buf[len] = byte | 0x80;
+        len += 1;
+    }
+    out.write_all(&buf[..len])
+}
+
+/// Decoding reads from a slice rather than a `Read`. The index is millions of
+/// varints, and one `read_exact` per byte through a `BufReader` spends more
+/// time in the reader than in the decode; the whole file is a handful of
+/// megabytes, so it is simply read once and walked in memory.
+struct Cursor<'a> {
+    bytes: &'a [u8],
+    at: usize,
+}
+
+impl<'a> Cursor<'a> {
+    fn take(&mut self, n: usize) -> Option<&'a [u8]> {
+        let end = self.at.checked_add(n)?;
+        let slice = self.bytes.get(self.at..end)?;
+        self.at = end;
+        Some(slice)
+    }
+
+    fn u32(&mut self) -> Option<u32> {
+        Some(u32::from_le_bytes(self.take(4)?.try_into().ok()?))
+    }
+
+    fn u64(&mut self) -> Option<u64> {
+        Some(u64::from_le_bytes(self.take(8)?.try_into().ok()?))
+    }
+
+    fn i64(&mut self) -> Option<i64> {
+        Some(i64::from_le_bytes(self.take(8)?.try_into().ok()?))
+    }
+
+    fn varint(&mut self) -> Option<u32> {
+        let mut value = 0u32;
+        let mut shift = 0;
+        loop {
+            let byte = *self.bytes.get(self.at)?;
+            self.at += 1;
+            // Five groups of seven bits is the most a u32 can occupy; anything
+            // longer is corruption, not a large number.
+            if shift > 28 {
+                return None;
+            }
+            value |= u32::from(byte & 0x7f) << shift;
+            if byte & 0x80 == 0 {
+                return Some(value);
+            }
+            shift += 7;
+        }
+    }
+}
+
+fn write_u64(out: &mut impl Write, value: u64) -> std::io::Result<()> {
+    out.write_all(&value.to_le_bytes())
+}
+
+/// Write atomically: a half-written index that still has a valid header would
+/// be loaded and believed, so the rename is what makes it safe.
+pub fn save(path: &Path, files: &[StoredFile]) -> std::io::Result<()> {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let temp = path.with_extension("tmp");
+    {
+        let mut out = BufWriter::new(File::create(&temp)?);
+        out.write_all(MAGIC)?;
+        write_u32(&mut out, files.len() as u32)?;
+        for file in files {
+            let bytes = file.rel.as_bytes();
+            write_u32(&mut out, bytes.len() as u32)?;
+            out.write_all(bytes)?;
+            write_u64(&mut out, file.size)?;
+            out.write_all(&file.mtime_ms.to_le_bytes())?;
+            write_u32(&mut out, file.trigrams.len() as u32)?;
+            let mut previous = 0u32;
+            for &t in &file.trigrams {
+                write_varint(&mut out, t - previous)?;
+                previous = t;
+            }
+        }
+        out.flush()?;
+    }
+    std::fs::rename(&temp, path)
+}
+
+/// Load, or `None` for anything unreadable, truncated or from another version.
+/// A cache is an optimisation; a broken one costs a rebuild and never a result.
+pub fn load(path: &Path) -> Option<Vec<StoredFile>> {
+    let bytes = std::fs::read(path).ok()?;
+    let mut input = Cursor { bytes: &bytes, at: 0 };
+    if input.take(MAGIC.len())? != MAGIC {
+        return None;
+    }
+
+    let count = input.u32()? as usize;
+    // A corrupt length field must not turn into a huge allocation.
+    if count > 5_000_000 {
+        return None;
+    }
+    let mut files = Vec::with_capacity(count.min(65_536));
+    for _ in 0..count {
+        let name_len = input.u32()? as usize;
+        if name_len > 4096 {
+            return None;
+        }
+        let rel = std::str::from_utf8(input.take(name_len)?).ok()?.to_string();
+        let size = input.u64()?;
+        let mtime_ms = input.i64()?;
+        let trigram_count = input.u32()? as usize;
+        if trigram_count > 4_000_000 {
+            return None;
+        }
+        let mut trigrams = Vec::with_capacity(trigram_count.min(8192));
+        let mut previous = 0u32;
+        for _ in 0..trigram_count {
+            previous = previous.checked_add(input.varint()?)?;
+            trigrams.push(previous);
+        }
+        files.push(StoredFile { rel, size, mtime_ms, trigrams });
+    }
+    Some(files)
+}
+
+/// What a stored index still knows, keyed by path, so a walk can ask whether
+/// each file it finds needs re-reading.
+pub fn index_by_path(files: Vec<StoredFile>) -> HashMap<String, StoredFile> {
+    let mut map = HashMap::with_capacity(files.len());
+    for file in files {
+        map.insert(file.rel.clone(), file);
+    }
+    map
+}
+
+/// A stored entry is only trusted while the file on disk still looks the same.
+pub fn still_valid(stored: &StoredFile, size: u64, mtime_ms: i64) -> bool {
+    stored.size == size && stored.mtime_ms == mtime_ms
+}

package/native/src/trigram.rs

@@ -111,9 +111,18 @@ impl Index {
         for &t in trigrams {
             let list = self.postings.entry(t).or_default();
             // Postings stay sorted so intersection is a merge, not a scan.
-            match list.binary_search(&file) {
-                Ok(_) => {}
-                Err(at) => list.insert(at, file),
+            //
+            // Bulk builds add files in ascending id order, so the new id
+            // belongs at the end and one comparison settles it. Falling
+            // through to a binary search here would cost fifteen scattered
+            // probes on a list held by every file — which measured as most of
+            // the time spent building the index.
+            match list.last() {
+                Some(&last) if last >= file => match list.binary_search(&file) {
+                    Ok(_) => {}
+                    Err(at) => list.insert(at, file),
+                },
+                _ => list.push(file),
             }
         }
         self.indexed.insert(file);
@@ -131,6 +140,30 @@ impl Index {
         });
     }
 
+    /// The index turned back the other way up: every trigram, grouped by the
+    /// file it came from, for writing the index out.
+    ///
+    /// One pass over the postings rather than one pass *per file* — asking each
+    /// file separately would rescan the entire index for every file, which on a
+    /// large tree is quadratic and would cost more than rebuilding from source.
+    pub fn by_file(&self) -> HashMap<u32, Vec<Trigram>> {
+        let mut out: HashMap<u32, Vec<Trigram>> = HashMap::with_capacity(self.indexed.len());
+        for &file in &self.indexed {
+            out.insert(file, Vec::new());
+        }
+        for (&t, files) in &self.postings {
+            for file in files {
+                if let Some(list) = out.get_mut(file) {
+                    list.push(t);
+                }
+            }
+        }
+        for list in out.values_mut() {
+            list.sort_unstable();
+        }
+        out
+    }
+
     /// Candidate file ids, or `None` meaning every file must be read.
     pub fn candidates(&self, plan: &Plan) -> Option<Vec<u32>> {
         match plan {

package/native/src/walk.rs

@@ -27,6 +27,7 @@ const BINARY_EXTENSIONS: &[&str] = &[
     "woff2", "eot", "db", "sqlite", "sqlite3", "pack", "idx",
 ];
 
+#[derive(Debug)]
 pub struct Found {
     pub rel: String,
     pub absolute: PathBuf,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/search",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Fuzzy file finding and indexed content search for pi, with no native binary and no daemon",
   "keywords": [
     "pi-package",

package/src/engine.ts

@@ -69,6 +69,14 @@ export interface SearchEngine {
   dispose(): void;
   /** How many files the index holds, when the engine can say. */
   indexed?(): number;
+  /**
+   * How the last index build was paid for: files whose contents came back from
+   * the stored index versus files that had to be read. Only an engine that
+   * persists its index can answer, and it is worth surfacing — "reused 0" on a
+   * tree that has not changed is the visible symptom of a cache that is
+   * silently not working.
+   */
+  stats?(): { reused: number; rebuilt: number };
 }
 
 /** fff calls it "plain"; this package calls it what a user would call it. */

package/src/format.ts

@@ -56,6 +56,13 @@ export function formatStatus(engine: SearchEngine | null, root: string): string
   ];
   const count = engine.indexed?.();
   if (typeof count === "number") lines.push(`Files:  ${count} indexed`);
+  const stats = engine.stats?.();
+  if (stats && stats.reused + stats.rebuilt > 0) {
+    lines.push(
+      `Index:  ${stats.reused} reused from cache, ${stats.rebuilt} read from disk` +
+        (stats.reused === 0 ? " (first run for this tree)" : ""),
+    );
+  }
   if (engine.name === "builtin") {
     lines.push(
       "",

package/src/native.ts

@@ -3,18 +3,23 @@
  *
  * A Rust index built for this package: the same trigram narrowing and the same
  * scoring constants as the TypeScript fallback, compiled. It builds an index
- * of this suite — 417 files — in about 33ms, and a literal search then reads 5
+ * of this suite — 417 files — in about 40ms, and a literal search then reads 5
  * of those files instead of all of them.
  *
+ * The index is stored between sessions, so a second start on an unchanged tree
+ * reloads instead of re-reading it. See `cachePathFor` for where it lives.
+ *
  * The binary is an optional dependency per platform, in the napi convention.
  * If none of them installed, this returns null and the caller falls back;
  * nothing here ever throws for a missing binary, because a missing binary is
  * the ordinary case this package is designed to survive.
  */
 
+import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import type { ContentHit, FileHit, GrepOptions, Page, SearchEngine, FindOptions } from "./engine.ts";
@@ -30,6 +35,11 @@ interface NativePage<T> {
 interface NativeIndex {
   fileCount(): number;
   indexedCount(): number;
+  /** Files whose contents came from the stored index instead of from disk. */
+  reusedCount(): number;
+  /** Files that had to be read because they were new or had changed. */
+  rebuiltCount(): number;
+  save(): void;
   touch(path: string): void;
   refresh(path: string): void;
   forget(path: string): void;
@@ -44,7 +54,39 @@ interface NativeIndex {
 }
 
 interface NativeModule {
-  SearchIndex: new (root: string, maxFiles?: number) => NativeIndex;
+  SearchIndex: new (root: string, maxFiles?: number, cachePath?: string) => NativeIndex;
+}
+
+/**
+ * Where a tree's stored index lives.
+ *
+ * Not inside the repository: an index is a derived artifact, it is large, and
+ * writing one into someone's working tree means it shows up in their `git
+ * status` and their diffs. It goes in the platform's cache directory, keyed by
+ * the absolute path of the root so two checkouts of the same project keep
+ * their own.
+ *
+ * `PIFY_SEARCH_CACHE_DIR` relocates it and `PIFY_SEARCH_NO_CACHE=1` turns it
+ * off, which is how the no-cache path stays tested on a machine that has one.
+ */
+export function cachePathFor(root: string): string | undefined {
+  if (process.env.PIFY_SEARCH_NO_CACHE === "1") return undefined;
+
+  const base =
+    process.env.PIFY_SEARCH_CACHE_DIR ??
+    (process.platform === "win32"
+      ? join(process.env.LOCALAPPDATA ?? tmpdir(), "pify-search")
+      : process.platform === "darwin"
+        ? join(homedir(), "Library", "Caches", "pify-search")
+        : join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "pify-search"));
+
+  const absolute = resolve(root);
+  // The readable part is for a human looking at the cache directory; the hash
+  // is what actually makes the name unique, since two projects can share a
+  // basename and paths differ only in case on some platforms.
+  const label = (basename(absolute) || "root").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 40);
+  const digest = createHash("sha256").update(absolute.toLowerCase()).digest("hex").slice(0, 16);
+  return join(base, `${label}-${digest}.idx`);
 }
 
 /** The napi triple for this host, matching how the binaries are published. */
@@ -104,7 +146,7 @@ export function loadNative(root: string, maxFiles?: number): SearchEngine | null
 
   let index: NativeIndex;
   try {
-    index = new mod.SearchIndex(root, maxFiles);
+    index = new mod.SearchIndex(root, maxFiles, cachePathFor(root));
   } catch {
     return null;
   }
@@ -167,8 +209,18 @@ export function loadNative(root: string, maxFiles?: number): SearchEngine | null
         return 0;
       }
     },
+    stats() {
+      try {
+        return { reused: index.reusedCount(), rebuilt: index.rebuiltCount() };
+      } catch {
+        return { reused: 0, rebuilt: 0 };
+      }
+    },
     dispose() {
-      // The Rust side owns nothing that outlives the object.
+      // Deliberately not saving here. Anything `refresh` changed during the
+      // session has a new mtime on disk, so the next start sees the mismatch
+      // and re-reads those files anyway — writing the whole index out at exit
+      // would cost a multi-megabyte write to save a handful of file reads.
     },
   };
 }