feat: incremental matching

[ph1losof]

Hi @saghen, this is between a draft and fully ready, so feel free to share your opinion.

Note: AI was used to help write the benchmark code.

Closes #5, related to television discussion - #19

What this does

When you're typing into a fuzzy finder character by character (f -> fo -> foo), each keystroke can only eliminate matches from the previous set - it can never add new ones. IncrementalMatcher takes advantage of this by remembering which haystack indices matched last time and only rescoring that shrinking subset on each prefix extension. Everything else (completely different query, haystack list change) falls back to a full rescore.

The API mirrors Matcher but takes the needle per-call instead of at construction:

let mut matcher = IncrementalMatcher::new(&config);
let matches = matcher.match_list("f", &haystacks);
let matches = matcher.match_list("fo", &haystacks);  // only rescores previous matches

Also supports match_list_indices, match_list_parallel, reset(), and handles haystack growth between calls.

Benchmark results on synthetic file-path data (500k haystacks, 8 keystroke sequence):

Overall:  one-shot 319ms  incremental 166ms  (1.92x)

Per step:
 "s"        482088 matches    30ms →  30ms   1.0x
 "sr"       355063 matches    44ms →  43ms   1.0x
 "src"      188339 matches    41ms →  36ms   1.2x
 "src/"     112305 matches    43ms →  25ms   1.7x
 "src/c"     53330 matches    50ms →  18ms   2.7x
 "src/co"    42282 matches    51ms →   6ms   8.5x
 "src/com"   17301 matches    38ms →   3ms   9.8x
 "src/comp"   6293 matches    22ms →   1ms  16.2x

Early steps where almost everything matches show no overhead (1.0x). The wins kick in once selectivity increases and the narrowed subset gets meaningfully smaller.

Approaches I tested that didn't pan out

Delta prefilter - before running the full SIMD prefilter on the narrowed set, check if just the new character exists in the haystack (cheap scalar byte scan). Turns out the SIMD prefilter already runs at ~16ns/item, and the scalar check costs ~25ns/item. Adding it as a pre-pass actually made things slower since the SIMD path is already fast enough that the extra branch isn't worth it.

Incremental prefilter/SW construction - set_needle rebuilds both the prefilter and the Smith-Waterman matcher from scratch each call. Thought about making it append-only for prefix extensions. Measured it: set_needle costs 120-270ns depending on needle length. Over an 8-step sequence that's ~1.7µs total out of ~166ms. Not worth the complexity, and the SW matrix uses a variable stride that changes per haystack, making in-place growth impractical without reworking the core DP.

Partial SW reuse - cache the first N-1 rows of the score matrix from the previous needle, only compute the new row. Problem is the matrix is per-haystack (different haystack lengths = different column counts), so you'd need to store a matrix per surviving match. That's ~12KB per match. At 23k matches that's 280MB.

What could come next

• Top-K mode where you can stop scoring early once you have enough high-quality results. Right now we score everything because the API returns all matches. A match_list_top_k(needle, haystacks, k) variant could skip SW for items that can't possibly make the cut based on their previous score.
• Score threshold parameter for similar early-out behavior when the caller knows they only care about matches above a quality bar.

[saghen]

Thank you for working on this and sorry I didn't get to it sooner!

The dispatch code was moved to the Matcher and the matching path is much faster now (~2-4x faster than before). Using SmithWaterman and Prefilter directly would create a lot of duplicate code, so I created a match_one function on the Matcher temporarily, but that needs to go through the runtime dispatch! so performance regressed.

  "src/comp": one-shot   64.24ms  incr   80.98ms  (0.79x)
        needle  matches   one-shot       incr speedup
           "s"   484119     7.79ms    11.69ms   0.7x
          "sr"   394413     9.74ms    23.45ms   0.4x
         "src"   222418     9.50ms    17.53ms   0.5x
        "src/"   107357     8.29ms    10.10ms   0.8x
       "src/c"    63462     7.84ms     8.89ms   0.9x
      "src/co"    45059     7.83ms     5.95ms   1.3x
     "src/com"    18280     6.55ms     3.08ms   2.1x
    "src/comp"     7708     5.96ms     1.48ms   4.0x

I've pushed a commit that adds a match_indexed_list to the Matcher which takes a list of indices that it should process from the haystack. This doesn't add too much overhead, the remaining speed loss seems to be from doing matches.clone() to store in the incremental matcher.

  "src/comp": one-shot   64.45ms  incr   48.48ms  (1.33x)
        needle  matches   one-shot       incr speedup
           "s"   484119     8.00ms     9.44ms   0.8x
          "sr"   394413     9.81ms     9.60ms   1.0x
         "src"   222418     9.55ms     9.15ms   1.0x
        "src/"   107357     8.35ms     6.54ms   1.3x
       "src/c"    63462     8.00ms     6.17ms   1.3x
      "src/co"    45059     7.87ms     4.77ms   1.6x
     "src/com"    18280     6.68ms     2.11ms   3.2x
    "src/comp"     7708     6.05ms   402.10µs  15.1x

I've dropped most of the APIs for now while I explore ideas, they'll be easy to add back later.

Also, I think it makes sense to keep the haystacks on the IncrementalMatcher directly, and make them owned Vec<String>. We can then provide a push_list(haystacks: &[&str]) API and perhaps a push_and_match_list as well. Wdyt?