fuzzy: generic FuzzyMatcher, fuzzy @agent/@model mention resolution, research archive

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-25 18:13:20 +01:00
parent c5acc2249f
commit 0ac0584a96
80 changed files with 2615 additions and 81 deletions
@@ -0,0 +1,51 @@
+# fzy ALGORITHM.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | fuzzy-matching-selectors |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | fzy ALGORITHM.md |
+| Source URL | https://github.com/jhawthorn/fzy/blob/master/ALGORITHM.md |
+| Source publisher / author | jhawthorn (fzy maintainer) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-25 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+The design note of fzy, a terminal fuzzy selector. It frames fuzzy scoring as a modified edit-distance problem solved with a dynamic program, and compares fzy to other finders. The page names the bonuses and penalties but the fetched text carries no numeric values or complexity analysis.
+
+## Key findings
+
+- Scoring is treated as a modified edit distance related to Levenshtein, with dynamic programming similar to Wagner-Fischer and Needleman-Wunsch.
+- The matrix is n-by-m (search length by candidate length); an affine gap penalty inspired by the Gotoh algorithm is used.
+- A second matrix D holds the best score which ends in a match, computed alongside the score matrix.
+- Penalties (negative): gaps at the start of the match, at the end, and inside the match. Bonuses (positive): consecutive match, after a slash, start of a word (after space, underscore or dash), a capital letter (CamelCase), after a dot.
+- Comparison: fzf takes the first match with some logic to find a shorter one but is not guaranteed shortest; ctrlp, pick and selecta (<= 0.0.6) score by the length of the first match; pick can find the absolute shortest match at a speed cost; selecta master compares only the shortest match from the same start; fuzzaldrin-plus uses Smith-Waterman.
+- Stated limitations: every search is case-insensitive (scoring favors uppercase matches; smart case is suggested), and the page says fuzzy matching only accepts insertions, not deletions or substitutions.
+
+## Pros / strengths
+
+A clear statement of the model (consecutive + word-start + camelCase bonuses, gap penalties) and a useful comparison of why first-match and shortest-match schemes misrank.
+
+## Cons / limitations / caveats
+
+No constants and no complexity in the fetched text; the recurrences live in src/match.c. The Command-t section is marked incomplete by the author. Not a measured evaluation, a design note.
+
+## Relevance to tai
+
+Gave the bonus taxonomy and the D/M two-matrix recurrence structure that tai's `FuzzyMatcher::Subsequence` follows. Constants were taken from fzf instead (see the fzf-algo-go dossier) because they were actually retrieved.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-25 | Initial dossier created. |