feat(core): restore and layer filename indexes across worktrees

README.md

@@ -552,7 +552,7 @@ Definition filtering occurs before page and per-file result limits. A timed-out
 
 Definition classification accepts source lines up to 256 bytes, including indentation and excluding line endings. Longer lines stay ordinary matches and are excluded from `definition_only`. The limit uses the original source bytes, regardless of display truncation or whitespace trimming. For multiline regex matches, it applies to the first physical line.
 
-Supported language families are Rust, Python, Go, JavaScript/TypeScript, Lua, C/C++/Objective-C, Java/C#/Dart/Groovy, Kotlin, Scala, Swift, Ruby, Elixir, Zig, PHP, shell, OCaml/ReScript/F#, and Haskell. The byte-keyword rules in [`definition/languages.rs`](crates/fff-core/src/definition/languages.rs) compile into per-language checkers. Each checker has fixed grammar constants and returns a boolean without a runtime rule dispatcher. Language detection checks at most the last eight filename bytes against a compile-time suffix table. Unknown extensions and extensionless filenames are not classified. `definition_only` excludes them before sorting, pagination, or content reads, and preserves explicit file constraints on empty results.
+Supported language families are Rust, Python, Go, JavaScript/TypeScript, Lua, C/C++/Objective-C, Java/C#/Dart/Groovy, Kotlin, Scala, Swift, Ruby, Zig, and OCaml/Reason/ReScript/F#. The byte-keyword rules in [`definition/languages.rs`](crates/fff-core/src/definition/languages.rs) compile into per-language checkers. Each checker has fixed grammar constants and returns a boolean without a runtime rule dispatcher. Language detection checks at most the last eight filename bytes against a compile-time suffix table. Unknown extensions and extensionless filenames are not classified. `definition_only` excludes them before sorting, pagination, or content reads, and preserves explicit file constraints on empty results.
 
 Identifier scanning uses compile-time byte tables for short tokens, then checks 16 bytes at a time with NEON on little-endian ARM64 or SSE2 on x86-64. Other targets use the scalar table. Loads stay within the source slice, including the final partial block. The parser uses `memchr` for quotes and bracket groups and does not allocate.
 
@@ -704,6 +704,12 @@ const hits = finder.value.grep("GetOffTheRecordProfile", {
 // Run extremely fast glob matching which is significantly (10-100 times) faster than Bun's and Node implementation
 const rustFiles = finder.value.glob("**/*.rs", { pageSize: 100 });
 
+// Index layers: append paths the scanner can't see and persist any layer (0 = base scan) to a file
+finder.value.createLayer("generated");
+finder.value.addPaths(["build/out/a.js", "build/out/b.js"]);
+finder.value.saveLayer(0, "/tmp/base.fff");   // later: loadBase(...) skips the rescan
+finder.value.loadLayer("/tmp/prebuilt.fff");  // built with FileFinder.buildLayerFile(paths, out)
+
 finder.value.destroy();
 ```
 
@@ -889,6 +895,22 @@ FffResult *res = fff_glob(handle, "**/*.rs", "", 0, 0, 100);
 // FffSearchResult in res->handle, free with fff_free_search_result.
 ```
 
+### Index layers
+
+`fff_layer_create` / `fff_layer_add_paths` append paths the scanner can't see;
+`fff_layer_save` writes any layer (0 = base scan) to a file and
+`fff_layer_load` attaches it back as a sealed overlay. Layer IDs never change, and the
+watcher writes only to layer 1. `fff_base_load` installs
+it as the base scan in the background (wait with `fff_wait_for_scan`).
+`fff_layer_build` packs a layer file without an instance. Pass NUL-terminated UTF-8 paths in one buffer, with optional parallel `sizes` / `modified` arrays (NULL to omit).
+
+```c
+const char paths[] = "build/out/a.js\0build/out/b.js";
+struct FffResult *added = fff_layer_add_paths(handle, paths, sizeof(paths), NULL, NULL, 2);
+if (!added->success) fprintf(stderr, "%s\n", added->error);
+fff_free_result(added);
+```
+
 ### Notes
 
 - Every function returning `FffResult*` allocates with Rust's `Box`. Free with `fff_free_result`, do not use malloc's free

crates/fff-c/include/fff.h

@@ -38,6 +38,7 @@
  * | `fff_health_check`         | `handle`      | `*mut c_char` (JSON string)   |
  * | `fff_get_historical_query` | `handle`      | `*mut c_char` (string or null)|
  * | `fff_wait_for_scan`        | `int_value`   | 1 = completed, 0 = timed out  |
+ * | `fff_wait_for_indexing_complete` | `int_value` | 1 = completed, 0 = timed out |
  * | `fff_track_query`          | `int_value`   | 1 = success, 0 = failure      |
  * | `fff_refresh_git_status`   | `int_value`   | number of files updated       |
  * | `fff_scan_files`           | (none)        | success flag only             |
@@ -743,6 +744,15 @@ struct FffResult *fff_get_scan_progress(void *fff_handle);
  */
 struct FffResult *fff_wait_for_scan(void *fff_handle, uint64_t timeout_ms);
 
+/**
+ * Wait for the filesystem walk and post-scan indexing before changing index layers.
+ * Returns 1 if the picker is ready, or 0 on timeout.
+ *
+ * # Safety
+ * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
+ */
+struct FffResult *fff_wait_for_indexing_complete(void *fff_handle, uint64_t timeout_ms);
+
 /**
  * Wait for the background file watcher to be ready.
  *
@@ -1397,6 +1407,88 @@ uint32_t fff_grep_result_get_next_file_offset(const struct FffGrepResult *r);
  */
 const char *fff_grep_result_get_regex_fallback_error(const struct FffGrepResult *r);
 
+/**
+ * Seal the open layer, open a new one for `fff_layer_add_paths`, and return its ID in `int_value`.
+ * Layer IDs and labels never change. Fails when every layer ID is in use or while a scan or
+ * post-scan indexing is running.
+ * # Safety
+ * Provide a live instance and a NULL or NUL-terminated UTF-8 label.
+ */
+struct FffResult *fff_layer_create(void *fff_handle, const char *label);
+
+/**
+ * Return the ID of the layer `fff_layer_add_paths` writes to in `int_value`. This is 1, the
+ * session layer where the watcher writes, until a layer is open.
+ * # Safety
+ * Provide a live instance.
+ */
+struct FffResult *fff_layer_current(void *fff_handle);
+
+/**
+ * Return the number of live files in the layer (0 for the base scan).
+ * # Safety
+ * Provide a live instance.
+ */
+struct FffResult *fff_layer_file_count(void *fff_handle, uint8_t layer);
+
+/**
+ * Return overlay metadata as a JSON array in `handle`. Free it with `fff_free_string`.
+ * # Safety
+ * Provide a live instance.
+ */
+struct FffResult *fff_layer_list(void *fff_handle);
+
+/**
+ * Append a batch of base-relative paths to the open layer and return the number of files added.
+ * Opens an unlabeled layer when none is open.
+ * # Safety
+ * Provide a live instance and `paths_len` readable bytes containing exactly `count` NUL-terminated UTF-8 paths.
+ * For an empty batch `paths` may be NULL. Each metadata array is NULL or holds `count` readable little-endian u64s (unaligned allowed).
+ */
+struct FffResult *fff_layer_add_paths(void *fff_handle,
+                                      const char *paths,
+                                      uintptr_t paths_len,
+                                      const uint64_t *sizes,
+                                      const uint64_t *modified,
+                                      uintptr_t count);
+
+/**
+ * Write a snapshot from a path batch and return the number of bytes written.
+ * Fails without writing when a path is not a relative file path.
+ * # Safety
+ * Use the buffers specified by `fff_layer_add_paths`. Provide a NUL-terminated UTF-8 output path and an optional NUL-terminated UTF-8 label.
+ */
+struct FffResult *fff_layer_build(const char *label,
+                                  const char *paths,
+                                  uintptr_t paths_len,
+                                  const uint64_t *sizes,
+                                  const uint64_t *modified,
+                                  uintptr_t count,
+                                  const char *out_path);
+
+/**
+ * Save a layer (0 for the base scan) and return the number of bytes written.
+ * # Safety
+ * Provide a live instance and a NUL-terminated UTF-8 path.
+ */
+struct FffResult *fff_layer_save(void *fff_handle, uint8_t layer, const char *path);
+
+/**
+ * Load a sealed overlay and return its layer ID. Fails when every layer ID is in use.
+ * # Safety
+ * Provide a live instance and a NUL-terminated UTF-8 path.
+ */
+struct FffResult *fff_layer_load(void *fff_handle, const char *path);
+
+/**
+ * Start a base scan from a snapshot and return its file count.
+ * Use `fff_wait_for_scan` before searching.
+ * Use `fff_wait_for_indexing_complete` before changing layers.
+ * # Safety
+ * Provide a live instance and a NUL-terminated UTF-8 path.
+ */
+struct FffResult *fff_base_load(void *fff_handle, const char *path);
+
 /**
  * Register the instance-wide watch callback used by all `fff_watch`
  * subscriptions; call before the first `fff_watch`, calling again replaces it.

crates/fff-c/src/ffi_types.rs

@@ -520,6 +520,7 @@ impl FffGrepResult {
 /// | `fff_health_check`         | `handle`      | `*mut c_char` (JSON string)   |
 /// | `fff_get_historical_query` | `handle`      | `*mut c_char` (string or null)|
 /// | `fff_wait_for_scan`        | `int_value`   | 1 = completed, 0 = timed out  |
+/// | `fff_wait_for_indexing_complete` | `int_value` | 1 = completed, 0 = timed out |
 /// | `fff_track_query`          | `int_value`   | 1 = success, 0 = failure      |
 /// | `fff_refresh_git_status`   | `int_value`   | number of files updated       |
 /// | `fff_scan_files`           | (none)        | success flag only             |