From 953651d8082e722d4673232edd1d701a821ebfb7 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 02:36:42 +0900
Subject: [PATCH 01/45] Refactor markup symbol extractors by language

---
 .../Indexer/Symbols/SymbolExtractor.Html.cs   |  943 +++++
 .../Symbols/SymbolExtractor.Markdown.cs       |  509 +++
 .../Indexer/Symbols/SymbolExtractor.Markup.cs | 3289 -----------------
 .../Indexer/Symbols/SymbolExtractor.Xaml.cs   | 1589 ++++++++
 .../Indexer/Symbols/SymbolExtractor.Xml.cs    |  282 ++
 5 files changed, 3323 insertions(+), 3289 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.Html.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.Markdown.cs
 delete mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.Markup.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.Xaml.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.Xml.cs

diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Html.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Html.cs
new file mode 100644
index 000000000..48eba1a7b
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Html.cs
@@ -0,0 +1,943 @@
+using System.Text;
+using System.Text.RegularExpressions;
+using Regex = CodeIndex.Indexer.BoundedRegex;
+using System.Runtime.CompilerServices;
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+
+    private static List<SymbolRecord> ExtractHtmlSymbols(long fileId, string rawText, string[] lines)
+    {
+        const string defaultSlotSymbolName = "(default)";
+
+        if (!LinesContain(lines, '<'))
+            return [];
+
+        // HTML needs proper tag-structure awareness so attribute lookalikes inside
+        // other attributes' quoted values (e.g. `<link title="href=evil.css" href="/real.css">`)
+        // don't leak phantom imports AND real attributes on the same tag aren't
+        // skipped. Regex alone can't do this — the outer tag context is lost once
+        // an attribute inside it is rejected — so walk the masked text with a
+        // character state machine that enumerates each tag's attributes in order.
+        // HTML は同一タグ内で別属性の引用符付き値に書かれた attribute 名の文字列（例:
+        // `<link title="href=evil.css" href="/real.css">`）から phantom な import を
+        // 漏らさず、かつ本物の属性を飛ばさないために、タグ構造を理解した走査が必要。
+        // regex だけでは、タグ内のある属性を mask で落とした瞬間に外側タグのコンテキスト
+        // を失うため不可能。マスク済みテキストを文字単位の state machine で走査し、タグ
+        // ごとに属性を列挙していく。
+        var maskedText = MayNeedHtmlRawTextMask(rawText)
+            ? MaskHtmlRawTextRegions(rawText)
+            : rawText;
+
+        // Build per-line absolute offsets only once a symbol needs O(log n)
+        // offset-to-line lookup. Plain markup with no emitted symbols can skip it.
+        // シンボルが offset-to-line lookup を必要とする時だけ行ごとの絶対 offset を作る。
+        // emit 対象のない plain markup では確保を避ける。
+        int[]? lineStarts = null;
+
+        List<SymbolRecord>? symbols = null;
+        var pos = 0;
+        while (pos < maskedText.Length)
+        {
+            if (maskedText[pos] != '<')
+            {
+                pos++;
+                continue;
+            }
+
+            // Skip closing tags, comments/doctypes/CDATA, and processing instructions.
+            // Raw-text bodies (<script>/<style>) and comments have already been masked
+            // by MaskHtmlRawTextRegions, but the opening/closing tags themselves remain.
+            // 閉じタグ / コメント / doctype / 処理命令はここで読み飛ばす。raw-text 本文と
+            // HTML コメントは MaskHtmlRawTextRegions で既に空白化されているが、開始タグ
+            // 自体はそのまま残っているため通常の属性走査対象になる。
+            if (pos + 1 < maskedText.Length && (maskedText[pos + 1] == '/' || maskedText[pos + 1] == '!' || maskedText[pos + 1] == '?'))
+            {
+                pos = IndexOfOrEnd(maskedText, '>', pos + 1) + 1;
+                continue;
+            }
+
+            var tagNameStart = pos + 1;
+            if (tagNameStart >= maskedText.Length || !IsHtmlTagNameStart(maskedText[tagNameStart]))
+            {
+                pos++;
+                continue;
+            }
+
+            var tagNameEnd = tagNameStart;
+            while (tagNameEnd < maskedText.Length && IsHtmlTagNameChar(maskedText[tagNameEnd]))
+                tagNameEnd++;
+
+            var tagName = maskedText[tagNameStart..tagNameEnd];
+            var sawNamedSlotDeclaration = false;
+
+            // Emit custom Web Components (hyphenated opening tag) at the `<` position,
+            // but skip the standard HTML/SVG/MathML tags that happen to contain a hyphen
+            // (`<font-face>`, `<color-profile>`, `<annotation-xml>`, etc.). Those are
+            // native elements, not user components, so labeling them as `class` symbols
+            // would pollute `symbols` / `definition` / `outline` on any project with
+            // inline SVG / MathML content.
+            // 開始タグ名にハイフンを含むカスタム Web Components を `<` の位置で emit する。
+            // ただしハイフン付きでも仕様で予約されている `<font-face>` / `<color-profile>`
+            // / `<annotation-xml>` などの標準タグは除外する。SVG / MathML を埋め込んだ
+            // ファイルで `symbols` / `definition` / `outline` が汚染されるのを防ぐ。
+            if (tagName.Contains('-') && !HtmlReservedHyphenatedTags.Contains(tagName))
+            {
+                var startLine = FindHtmlLineNumber(lineStarts ??= BuildLineStarts(lines), pos);
+                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+                (symbols ??= []).Add(new SymbolRecord
+                {
+                    FileId = fileId,
+                    Kind = "class",
+                    Name = tagName,
+                    Line = startLine,
+                    StartLine = startLine,
+                    EndLine = startLine,
+                    Signature = lines[signatureIndex].Trim(),
+                });
+            }
+
+            // Walk the tag body, enumerating attribute name/value pairs until `>` or EOF.
+            // タグ本体を走査し、`>` か EOF まで属性 name/value を順に列挙する。
+            var cursor = tagNameEnd;
+            while (cursor < maskedText.Length && maskedText[cursor] != '>')
+            {
+                // Skip whitespace and stray '/' (self-closing marker).
+                // 空白文字と self-closing の `/` を読み飛ばす。
+                if (char.IsWhiteSpace(maskedText[cursor]) || maskedText[cursor] == '/')
+                {
+                    cursor++;
+                    continue;
+                }
+
+                // Read attribute name. HTML5 allows broad attribute-name charsets, but for
+                // our emit rules we only need to recognize ASCII names plus `:` / `-` / `.`
+                // (xml:id, data-*, aria-*, etc.). Anything else aborts the parse of this tag
+                // gracefully by treating it as a non-matching attribute start.
+                // 属性名を読む。HTML5 の属性名は広いが、emit 対象の判定には ASCII の名前と
+                // `:` / `-` / `.` が拾えれば十分（xml:id, data-*, aria-* 等を含めるため）。
+                // それ以外の文字が来たら、このタグのパースは壊さずに 1 文字進めるだけで抜ける。
+                if (!IsHtmlAttrNameStart(maskedText[cursor]))
+                {
+                    cursor++;
+                    continue;
+                }
+                var attrNameStart = cursor;
+                while (cursor < maskedText.Length && IsHtmlAttrNameChar(maskedText[cursor]))
+                    cursor++;
+                var attrName = maskedText[attrNameStart..cursor];
+
+                // Skip whitespace between name and `=`.
+                while (cursor < maskedText.Length && char.IsWhiteSpace(maskedText[cursor]))
+                    cursor++;
+
+                string? attrValue = null;
+                int attrValueStart = -1;
+                if (cursor < maskedText.Length && maskedText[cursor] == '=')
+                {
+                    cursor++;
+                    while (cursor < maskedText.Length && char.IsWhiteSpace(maskedText[cursor]))
+                        cursor++;
+                    if (cursor < maskedText.Length && (maskedText[cursor] == '"' || maskedText[cursor] == '\''))
+                    {
+                        var quote = maskedText[cursor];
+                        cursor++;
+                        attrValueStart = cursor;
+                        // Use the shared FindHtmlQuoteClose helper so this and the raw-text
+                        // mask agree on where quoted attribute values end. The helper allows
+                        // multi-line quoted values (valid HTML5 like `<div title="line1\n
+                        // line2" id="real">` where `id="real"` must still be emitted) and
+                        // tag-like content inside quoted values, identifying the close by
+                        // post-value context (`>`, `/`, whitespace, or EOF). Only truly
+                        // unterminated quotes (no matching `"` at all) return -1, so the
+                        // caller can bail to EOL without walking to EOF.
+                        // 共有ヘルパー `FindHtmlQuoteClose` を使い、mask 側とも引用符終端の
+                        // 判断を一致させる。複数行 quoted 属性値 (`<div title="line1\n
+                        // line2" id="real">` など) とタグ様テキストを含む引用符付き値を
+                        // 許容し、`>` / `/` / 空白 / EOF が直後に来る位置を終端として検出する。
+                        // 真に未終端（マッチ `"` が存在しない）場合のみ -1 を返し、呼び出し側が
+                        // EOF まで走らず行末で被害を止められるようにする。
+                        var valueEnd = FindHtmlQuoteClose(maskedText, cursor, quote);
+                        if (valueEnd < 0)
+                        {
+                            // Unterminated: bail to end of current line so the outer tag
+                            // loop can restart at the beginning of the next line's `<`.
+                            // 未終端: 当該行末まで進め、次行先頭の `<` から外側ループが再開できるようにする。
+                            attrValue = null;
+                            var eol = maskedText.IndexOf('\n', cursor);
+                            cursor = eol < 0 ? maskedText.Length : eol;
+                            break;
+                        }
+                        attrValue = maskedText[cursor..valueEnd];
+                        cursor = valueEnd + 1;
+                    }
+                    else if (cursor < maskedText.Length && maskedText[cursor] != '>')
+                    {
+                        // Unquoted value: HTML5 excludes space, `"`, `'`, `=`, `<`, `>`, backtick.
+                        // 引用符なし値: HTML5 では空白、`"`、`'`、`=`、`<`、`>`、バッククォートを除外。
+                        attrValueStart = cursor;
+                        while (cursor < maskedText.Length && !IsHtmlUnquotedValueTerminator(maskedText[cursor]))
+                            cursor++;
+                        attrValue = maskedText[attrValueStart..cursor];
+                    }
+                }
+
+                if (IsHtmlSemanticStateAttributeName(attrName))
+                {
+                    var attrStartLine = FindHtmlLineNumber(lineStarts ??= BuildLineStarts(lines), attrNameStart);
+                    var attrSignatureIndex = Math.Clamp(attrStartLine - 1, 0, lines.Length - 1);
+                    (symbols ??= []).Add(new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "property",
+                        Name = NormalizeHtmlAttributeName(attrName),
+                        Line = attrStartLine,
+                        StartLine = attrStartLine,
+                        EndLine = attrStartLine,
+                        Signature = lines[attrSignatureIndex].Trim(),
+                    });
+                }
+
+                if (attrValue == null || attrValue.Length == 0)
+                    continue;
+
+                string? emitKind = null;
+                string? singleEmittedName = null;
+                IEnumerable<string>? emittedNames = null;
+                if (IsHtmlAttributeName(attrName, "src") && IsHtmlSrcResourceTag(tagName))
+                {
+                    emitKind = "import";
+                    singleEmittedName = attrValue.Trim();
+                }
+                else if (IsHtmlAttributeName(attrName, "srcset") && IsHtmlSrcsetResourceTag(tagName))
+                {
+                    emitKind = "import";
+                    emittedNames = EnumerateHtmlSrcsetUrls(attrValue);
+                }
+                else if ((IsHtmlAttributeName(attrName, "href") || IsHtmlAttributeName(attrName, "xlink:href")) && IsHtmlHrefResourceTag(tagName))
+                {
+                    emitKind = "import";
+                    singleEmittedName = attrValue.Trim();
+                }
+                else if (IsHtmlAttributeName(attrName, "data") && IsHtmlTagName(tagName, "object"))
+                {
+                    emitKind = "import";
+                    singleEmittedName = attrValue.Trim();
+                }
+                else if (IsHtmlAttributeName(attrName, "poster") && IsHtmlTagName(tagName, "video"))
+                {
+                    emitKind = "import";
+                    singleEmittedName = attrValue.Trim();
+                }
+                else if (IsHtmlAttributeName(attrName, "id") && !attrName.Contains(':') && !attrName.Contains('-') && !attrName.Contains('.'))
+                {
+                    emitKind = "property";
+                    singleEmittedName = attrValue.Trim();
+                }
+                else if (IsHtmlAttributeName(attrName, "class") || IsHtmlAttributeName(attrName, "classname"))
+                {
+                    emitKind = "reference";
+                    emittedNames = EnumerateHtmlClassNames(attrValue);
+                }
+                else if (IsHtmlAttributeName(attrName, "name") && IsHtmlTagName(tagName, "slot"))
+                {
+                    var slotName = attrValue.Trim();
+                    if (slotName.Length > 0)
+                    {
+                        emitKind = "property";
+                        singleEmittedName = slotName;
+                        sawNamedSlotDeclaration = true;
+                    }
+                }
+                else if (IsHtmlAttributeName(attrName, "slot"))
+                {
+                    var slotName = attrValue.Trim();
+                    if (slotName.Length > 0)
+                    {
+                        emitKind = "reference";
+                        singleEmittedName = slotName;
+                    }
+                }
+
+                if (emitKind == null || (singleEmittedName == null && emittedNames == null))
+                    continue;
+
+                // Anchor the symbol at the attribute value so cross-line tags like
+                // `<script\n  type="module"\n  src="/app.js">` land on the line that
+                // actually carries the value.
+                // 属性値の位置でシンボルを固定し、属性が折り返されたタグでも値が書かれた
+                // 行にジャンプできるようにする。
+                var anchor = attrValueStart >= 0 ? attrValueStart : pos;
+                var startLine = FindHtmlLineNumber(lineStarts ??= BuildLineStarts(lines), anchor);
+                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+
+                void AddEmittedName(string emittedName)
+                {
+                    (symbols ??= []).Add(new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = emitKind!,
+                        Name = emittedName,
+                        Line = startLine,
+                        StartLine = startLine,
+                        EndLine = startLine,
+                        Signature = lines[signatureIndex].Trim(),
+                    });
+                }
+
+                if (singleEmittedName != null)
+                {
+                    AddEmittedName(singleEmittedName);
+                    continue;
+                }
+
+                if (emittedNames == null)
+                    continue;
+
+                foreach (var emittedName in emittedNames)
+                    AddEmittedName(emittedName);
+            }
+
+            if (IsHtmlTagName(tagName, "slot") && !sawNamedSlotDeclaration)
+            {
+                var startLine = FindHtmlLineNumber(lineStarts ??= BuildLineStarts(lines), pos);
+                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+                (symbols ??= []).Add(new SymbolRecord
+                {
+                    FileId = fileId,
+                    Kind = "property",
+                    Name = defaultSlotSymbolName,
+                    Line = startLine,
+                    StartLine = startLine,
+                    EndLine = startLine,
+                    Signature = lines[signatureIndex].Trim(),
+                });
+            }
+
+            pos = cursor < maskedText.Length ? cursor + 1 : cursor;
+        }
+
+        if (symbols is null)
+            return [];
+
+        AssignContainers(symbols, lines, null);
+        PopulateDeclaredContainerQualifiedNames(symbols);
+        return symbols;
+    }
+
+    private static IEnumerable<string> EnumerateHtmlClassNames(string value)
+    {
+        var tokenStart = -1;
+        for (var index = 0; index <= value.Length; index++)
+        {
+            var atEnd = index == value.Length;
+            if (!atEnd && !char.IsWhiteSpace(value[index]))
+            {
+                if (tokenStart < 0)
+                    tokenStart = index;
+                continue;
+            }
+
+            if (tokenStart < 0)
+                continue;
+
+            yield return value[tokenStart..index];
+            tokenStart = -1;
+        }
+    }
+
+    private static bool IsHtmlSemanticStateAttributeName(string attrName)
+    {
+        return (attrName.StartsWith("data-", StringComparison.OrdinalIgnoreCase) ||
+                attrName.StartsWith("aria-", StringComparison.OrdinalIgnoreCase)) &&
+               attrName.Length > 5;
+    }
+
+    private static string NormalizeHtmlAttributeName(string attrName)
+    {
+        for (var index = 0; index < attrName.Length; index++)
+        {
+            var ch = attrName[index];
+            if (ch >= 'A' && ch <= 'Z')
+                return attrName.ToLowerInvariant();
+        }
+
+        return attrName;
+    }
+
+    private static bool IsHtmlAttributeName(string attrName, string expected) =>
+        attrName.Equals(expected, StringComparison.OrdinalIgnoreCase);
+
+    private static bool IsHtmlTagNameStart(char c) => (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z');
+
+    private static bool IsHtmlTagNameChar(char c) =>
+        (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-' || c == '_';
+
+    private static bool IsHtmlAttrNameStart(char c) =>
+        (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || c == '_' || c == ':';
+
+    private static bool IsHtmlAttrNameChar(char c) =>
+        IsHtmlAttrNameStart(c) || (c >= '0' && c <= '9') || c == '-' || c == '.';
+
+    private static bool IsHtmlUnquotedValueTerminator(char c) =>
+        char.IsWhiteSpace(c) || c == '"' || c == '\'' || c == '=' || c == '<' || c == '>' || c == '`';
+
+    private static int IndexOfOrEnd(string text, char needle, int start)
+    {
+        var idx = text.IndexOf(needle, start);
+        return idx < 0 ? text.Length : idx;
+    }
+
+    private static int FindHtmlLineNumber(int[] lineStarts, int offset)
+    {
+        if (lineStarts.Length == 0)
+            return 1;
+        var lo = 0;
+        var hi = lineStarts.Length - 1;
+        while (lo < hi)
+        {
+            var mid = (lo + hi + 1) / 2;
+            if (lineStarts[mid] <= offset)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo + 1;
+    }
+
+    private static readonly string[] HtmlRawTextElementNames = ["script", "style", "textarea", "title"];
+
+    // Native HTML/SVG/MathML tag names that happen to contain a hyphen but are
+    // reserved by the spec, so they must NOT be treated as custom-element class
+    // symbols. See https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
+    // for the PotentialCustomElementName / reserved names production.
+    // ハイフンを含むが仕様で予約されている標準 HTML / SVG / MathML タグ名。custom
+    // element の class シンボルとして扱ってはいけない。
+    private static readonly HashSet<string> HtmlReservedHyphenatedTags = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "annotation-xml",
+        "color-profile",
+        "font-face",
+        "font-face-src",
+        "font-face-uri",
+        "font-face-format",
+        "font-face-name",
+        "missing-glyph",
+    };
+
+    private static bool IsHtmlTagName(string tagName, string expected) =>
+        tagName.Equals(expected, StringComparison.OrdinalIgnoreCase);
+
+    private static bool IsHtmlSrcResourceTag(string tagName) =>
+        IsHtmlTagName(tagName, "audio")
+        || IsHtmlTagName(tagName, "embed")
+        || IsHtmlTagName(tagName, "iframe")
+        || IsHtmlTagName(tagName, "img")
+        || IsHtmlTagName(tagName, "input")
+        || IsHtmlTagName(tagName, "script")
+        || IsHtmlTagName(tagName, "source")
+        || IsHtmlTagName(tagName, "track")
+        || IsHtmlTagName(tagName, "video");
+
+    private static bool IsHtmlHrefResourceTag(string tagName) =>
+        IsHtmlTagName(tagName, "a")
+        || IsHtmlTagName(tagName, "area")
+        || IsHtmlTagName(tagName, "image")
+        || IsHtmlTagName(tagName, "link")
+        || IsHtmlTagName(tagName, "use");
+
+    private static bool IsHtmlSrcsetResourceTag(string tagName) =>
+        IsHtmlTagName(tagName, "img") || IsHtmlTagName(tagName, "source");
+
+    private static IEnumerable<string> EnumerateHtmlSrcsetUrls(string value)
+    {
+        var index = 0;
+        while (index < value.Length)
+        {
+            while (index < value.Length && (char.IsWhiteSpace(value[index]) || value[index] == ','))
+                index++;
+
+            if (index >= value.Length)
+                yield break;
+
+            var start = index;
+            var isDataUrl = value.AsSpan(index).StartsWith("data:", StringComparison.OrdinalIgnoreCase);
+            if (isDataUrl)
+            {
+                index += "data:".Length;
+                while (index < value.Length)
+                {
+                    if (char.IsWhiteSpace(value[index]))
+                        break;
+                    if (value[index] == ',' && (index + 1 >= value.Length || char.IsWhiteSpace(value[index + 1])))
+                        break;
+                    index++;
+                }
+            }
+            else
+            {
+                while (index < value.Length && !char.IsWhiteSpace(value[index]) && value[index] != ',')
+                    index++;
+            }
+
+            var url = value[start..index].Trim();
+            if (url.Length > 0)
+                yield return url;
+
+            while (index < value.Length && value[index] != ',')
+                index++;
+
+            if (index < value.Length && value[index] == ',')
+                index++;
+        }
+    }
+
+    internal static string MaskHtmlRawTextRegions(string text)
+    {
+        // Walk `text` character by character, masking the body of raw-text /
+        // RCDATA elements (`<script>` / `<style>` / `<textarea>` / `<title>`)
+        // and `<!-- ... -->` comments. Regex-based masking could not reliably
+        // handle cases like `<script data-note="a > b" src="/app.js">` (quoted
+        // `>` inside an attribute terminated the naive `[^>]*` pattern) or
+        // `<script data-note="oops\nconst tpl = '<evil-card id="phantom">';`
+        // (unterminated quote let nested `"..."` pairs match across script
+        // body content). The state machine uses the same quote-handling logic
+        // as the symbol extractor's state machine so both agree on where a
+        // raw-text opener ends, and falls back to masking through EOF when an
+        // opener is unterminated — that matches HTML's spec behavior (an
+        // unclosed raw-text element swallows everything until EOF or
+        // `</name>`) and prevents script-body content from leaking as phantom
+        // HTML symbols.
+        // マスクを正規表現ではなく文字単位の state machine で行い、`<script>` /
+        // `<style>` / `<textarea>` / `<title>` の本体と `<!-- ... -->` コメントを
+        // マスクする。正規表現だと `<script data-note="a > b" src="/app.js">` の
+        // ように属性値内の引用符付き `>` で早期終了したり、未終端引用符を持つ
+        // `<script data-note="oops\nconst tpl = '<evil-card id="phantom">';`
+        // のような入力で引用符ペアが script 本体をまたいで誤マッチする問題が
+        // あった。state machine は symbol extractor と同じ引用符処理を共有して
+        // 開始タグの境界を一致させ、開始タグが未終端の場合は EOF までマスクする
+        // （仕様上、未閉鎖 raw-text 要素は EOF か `</name>` まで本体を飲むため）。
+        if (!MayContainHtmlRawTextMaskTarget(text))
+            return text;
+
+        var chars = text.ToCharArray();
+        var i = 0;
+        while (i < chars.Length)
+        {
+            if (chars[i] != '<')
+            {
+                i++;
+                continue;
+            }
+
+            // `<!-- ... -->` comment. Closing `-->` is optional (masked through
+            // EOF) so mid-edit working-tree HTML with an unclosed comment does
+            // not leak following tags as phantom symbols.
+            // 未閉鎖コメントは EOF までマスクし、以降のタグが phantom にならないようにする。
+            if (i + 3 < chars.Length && chars[i + 1] == '!' && chars[i + 2] == '-' && chars[i + 3] == '-')
+            {
+                var commentClose = text.IndexOf("-->", i + 4, StringComparison.Ordinal);
+                var commentEnd = commentClose < 0 ? chars.Length : commentClose + 3;
+                BlankPreservingNewlines(chars, i, commentEnd);
+                i = commentEnd;
+                continue;
+            }
+
+            // `<![CDATA[ ... ]]>` section. In XHTML / SVG / MathML these are
+            // valid and must not leak their content as phantom tags. The
+            // terminator is specifically `]]>`, not the first `>`, so a naive
+            // `IndexOf('>', ...)` would stop early on inner markup and let the
+            // remaining CDATA body be parsed as real HTML. Unterminated CDATA
+            // masks through EOF, matching the comment-branch behavior.
+            // `<![CDATA[ ... ]]>` は XHTML / SVG / MathML で有効。終端は
+            // `]]>` のみであり、単純な `>` 検索では内部のタグで早期終了して
+            // 残り本体が phantom として抽出される。未閉鎖は EOF までマスクする。
+            if (i + 8 < chars.Length && chars[i + 1] == '!' && chars[i + 2] == '[' &&
+                chars[i + 3] == 'C' && chars[i + 4] == 'D' && chars[i + 5] == 'A' &&
+                chars[i + 6] == 'T' && chars[i + 7] == 'A' && chars[i + 8] == '[')
+            {
+                var cdataClose = text.IndexOf("]]>", i + 9, StringComparison.Ordinal);
+                var cdataEnd = cdataClose < 0 ? chars.Length : cdataClose + 3;
+                BlankPreservingNewlines(chars, i, cdataEnd);
+                i = cdataEnd;
+                continue;
+            }
+
+            // Other `<!...>` declarations (DOCTYPE and similar). Content
+            // between `<!` and the first unquoted `>` is a declaration, not a
+            // tag body, so mask it to prevent attribute-lookalike tokens from
+            // being emitted as symbols. Quoted values inside DOCTYPE PUBLIC /
+            // SYSTEM are walked via FindHtmlQuoteClose so embedded `>` does
+            // not terminate the declaration early.
+            // DOCTYPE などの `<!...>` 宣言は `FindHtmlTagOpenerEnd` で閉じ `>` を
+            // 探して丸ごとマスクする。引用符内の `>` で早期終了しないようにする。
+            if (i + 1 < chars.Length && chars[i + 1] == '!')
+            {
+                var declEnd = FindHtmlTagOpenerEnd(text, i);
+                if (declEnd < 0)
+                {
+                    BlankPreservingNewlines(chars, i, chars.Length);
+                    i = chars.Length;
+                    continue;
+                }
+                BlankPreservingNewlines(chars, i, declEnd + 1);
+                i = declEnd + 1;
+                continue;
+            }
+
+            // Processing instructions `<?...?>` (XML prolog, XSLT PIs, PHP
+            // short tags embedded in XHTML). Terminator is `?>`, not bare `>`.
+            // Content between can include tag-like markup that must not leak.
+            // `<?...?>` 処理命令。終端は `?>` で、内部のタグ様テキストは漏らさない。
+            if (i + 1 < chars.Length && chars[i + 1] == '?')
+            {
+                var piClose = text.IndexOf("?>", i + 2, StringComparison.Ordinal);
+                var piEnd = piClose < 0 ? chars.Length : piClose + 2;
+                BlankPreservingNewlines(chars, i, piEnd);
+                i = piEnd;
+                continue;
+            }
+
+            var rawName = TryMatchHtmlRawTextOpenerName(text, i);
+            if (rawName != null)
+            {
+                // Walk the opening tag to find its closing `>`. Multi-line
+                // quoted attribute values are allowed; the helper only returns
+                // -1 if the opener cannot be closed before EOF.
+                // 開始タグの `>` を探す。複数行に跨る引用符付き属性値は OK。
+                // EOF 前に閉じられない場合のみ -1 を返す。
+                var openerEnd = FindHtmlTagOpenerEnd(text, i);
+                if (openerEnd < 0)
+                {
+                    // Unterminated raw-text opener. Mask from `<` to EOF — this
+                    // matches HTML spec behavior and prevents script-body
+                    // content from leaking as phantom symbols.
+                    // 開始タグが未終端の場合、仕様どおり EOF までマスクする。
+                    BlankPreservingNewlines(chars, i, chars.Length);
+                    i = chars.Length;
+                    continue;
+                }
+
+                var bodyStart = openerEnd + 1;
+                var closeIdx = FindHtmlRawTextClose(text, bodyStart, rawName);
+                var bodyEnd = closeIdx < 0 ? chars.Length : closeIdx;
+                BlankPreservingNewlines(chars, bodyStart, bodyEnd);
+
+                if (closeIdx < 0)
+                {
+                    i = chars.Length;
+                    continue;
+                }
+
+                var closeGt = text.IndexOf('>', closeIdx);
+                i = closeGt < 0 ? chars.Length : closeGt + 1;
+                continue;
+            }
+
+            // Non-raw-text tag opener (including closing tags `</...`). Walk
+            // past the whole opener so quoted attribute values like
+            // `<div title="<script>">` or `<div title="<!--">` do not re-enter
+            // the raw-text / comment branches on the next character and get
+            // misidentified as raw-text/comment openers. Without this skip,
+            // the char-by-char scan would re-encounter `<script>` / `<!--`
+            // inside the attribute value and mask through EOF.
+            // raw-text 以外のタグ opener（`</...` を含む）に遭遇したら、opener 全体を
+            // 飛ばして属性値内の `<script>` / `<!--` が次の文字で raw-text / comment
+            // として再解釈されないようにする。これを入れないと属性値内の `<script>`
+            // を raw-text 本体マスク対象と誤認して以降の兄弟タグを全部飲み込む。
+            if (i + 1 < chars.Length && (IsHtmlTagNameStart(chars[i + 1]) || chars[i + 1] == '/'))
+            {
+                var openerEnd = FindHtmlTagOpenerEnd(text, i);
+                if (openerEnd >= 0)
+                {
+                    i = openerEnd + 1;
+                    continue;
+                }
+
+                // Unterminated non-raw-text tag opener (mid-edit quoted attribute
+                // like `<div title="<!--` or `<div title="<script>`). Advance
+                // past the current line so the `<!--` / `<script>` inside the
+                // broken quoted value is not re-encountered on the very next
+                // character and misidentified as a real comment / raw-text
+                // opener that would mask through EOF. Sibling tags on later
+                // lines still get their chance to be walked.
+                // 未終端の non-raw-text タグ opener（`<div title="<!--` のような
+                // 編集途中の引用属性）に遭遇した場合、`i++` で戻ると引用値内の
+                // `<!--` / `<script>` が次文字で comment / raw-text opener として
+                // 再解釈されて EOF までマスクされるため、現在行末まで一気に進めて
+                // 次行以降の兄弟タグを拾えるようにする。
+                var eolIdx = text.IndexOf('\n', i);
+                i = eolIdx < 0 ? chars.Length : eolIdx + 1;
+                continue;
+            }
+
+            i++;
+        }
+        return new string(chars);
+    }
+
+    private static bool MayContainHtmlRawTextMaskTarget(string text)
+    {
+        for (var index = text.IndexOf('<'); index >= 0; index = text.IndexOf('<', index + 1))
+        {
+            if (index + 1 >= text.Length)
+                continue;
+
+            var next = text[index + 1];
+            if (next is '!' or '?')
+                return true;
+
+            if (TryMatchHtmlRawTextOpenerName(text, index) != null)
+                return true;
+        }
+
+        return false;
+    }
+
+    private static string? TryMatchHtmlRawTextOpenerName(string text, int start)
+    {
+        // Check if `text[start]` (must be `<`) begins `<script` / `<style` /
+        // `<textarea` / `<title` followed by a non-tag-name-char (so `<scriptx`
+        // is NOT matched as `<script`).
+        // `start` は `<` の位置。`<script` / `<style` / `<textarea` / `<title`
+        // に続く文字がタグ名文字でないもののみ一致させる（`<scriptx` は除外）。
+        foreach (var name in HtmlRawTextElementNames)
+        {
+            var nameStart = start + 1;
+            if (nameStart + name.Length > text.Length)
+                continue;
+            var match = true;
+            for (var j = 0; j < name.Length; j++)
+            {
+                if (!EqualsHtmlAsciiIgnoreCase(text[nameStart + j], name[j]))
+                {
+                    match = false;
+                    break;
+                }
+            }
+            if (!match)
+                continue;
+            var after = nameStart + name.Length;
+            if (after >= text.Length || !IsHtmlTagNameChar(text[after]))
+                return name;
+        }
+        return null;
+    }
+
+    private static bool MayNeedHtmlRawTextMask(string text)
+        => text.IndexOf("<!", StringComparison.Ordinal) >= 0
+           || text.IndexOf("<?", StringComparison.Ordinal) >= 0
+           || text.IndexOf("<script", StringComparison.OrdinalIgnoreCase) >= 0
+           || text.IndexOf("<style", StringComparison.OrdinalIgnoreCase) >= 0
+           || text.IndexOf("<textarea", StringComparison.OrdinalIgnoreCase) >= 0
+           || text.IndexOf("<title", StringComparison.OrdinalIgnoreCase) >= 0;
+
+    private static int FindHtmlTagOpenerEnd(string text, int start)
+    {
+        // Walk from `start` (position of `<`) forward to find the opening `>`,
+        // skipping over quoted attribute values. Multi-line quoted values are
+        // allowed per HTML5 spec.
+        // `start` は `<` の位置。引用符付き属性値を `FindHtmlQuoteClose` で飛ばしつつ
+        // 開始タグの閉じ `>` を探す。HTML5 仕様どおり複数行値も許容する。
+        var i = start + 1;
+        while (i < text.Length)
+        {
+            var c = text[i];
+            if (c == '>')
+                return i;
+            if (c == '"' || c == '\'')
+            {
+                var closeIdx = FindHtmlQuoteClose(text, i + 1, c);
+                if (closeIdx < 0)
+                    return -1;
+                i = closeIdx + 1;
+                continue;
+            }
+            i++;
+        }
+        return -1;
+    }
+
+    private static int FindHtmlQuoteClose(string text, int start, char quote)
+    {
+        // Scan forward for the matching closing quote. HTML5 allows newlines
+        // inside quoted attribute values (`<meta description="line1\nline2">`)
+        // and tag-like content (`<div title="<section id=x>">`), so we cross
+        // line boundaries and tag-name-like bytes without bailing. A quote is
+        // accepted as the close when it has "strong valid" post-value context:
+        // per HTML5 the char immediately after a quoted attribute value must
+        // be whitespace, `>`, or EOF. `/` alone is intentionally excluded from
+        // strong context — a `/` following a quote is ambiguous between the
+        // self-closing marker (`attr="v"/>`) and the opening `"` of a later
+        // path-like attribute (`href="/app.css"`). Accepting bare `/` would
+        // let an earlier unterminated `title="...` silently steal the opening
+        // quote of `href="/app.css"` and swallow every sibling tag between
+        // them. The self-closing form `"/>` IS accepted (ambiguity gone —
+        // the `/` is followed by `>`), so void-element tags like
+        // `<link href="/app.css"/>` still close cleanly without triggering
+        // the nested-attribute fallback on the following sibling tag.
+        //
+        // When a non-strong `"` is encountered and it matches an "attribute-
+        // start" pattern (preceded by `[attr-name-chars]+=` with whitespace
+        // before the ident), the scanner treats it as a nested attribute
+        // opening: it walks past that attribute's value (finding the matching
+        // inner quote) and resumes scanning, instead of mis-taking the inner
+        // opening for our close. This preserves strict-HTML5 behavior on
+        // well-formed multi-line quoted values (they contain no spurious
+        // `ident="` patterns) while keeping mid-edit resilience — if the
+        // outer quote is truly unterminated, we'll walk through all nested
+        // attributes without finding a strong close, and return -1 so the
+        // attribute parser can bail at EOL and recover sibling tags on the
+        // next lines.
+        //
+        // If neither a strong close nor a nested pattern is ever seen, fall
+        // back to the first bare `"` candidate (matches spec tokenizer
+        // recovery for malformed content like `<div id="foo"bar>`). If nested
+        // patterns WERE seen but no strong close was found, return -1 to
+        // signal the attribute is effectively unterminated for our purposes.
+        //
+        // 閉じ引用符を探す。HTML5 は属性値内の改行とタグ様テキストを許容するため、
+        // 改行やタグ様の文字では早期中断しない。引用符を閉じとして採用する条件は、
+        // 直後が空白 / `>` / EOF の「strong な属性値終端」であること。`/` は
+        // self-closing (`attr="v"/>`) と後続属性の開始引用符 (`href="/app.css"`)
+        // の区別が文脈無しでは付かないため、`/` 単独は strong には含めない。
+        // bare `/` を許容すると、未終端の `title="...` が後続 `href="/app.css"`
+        // の開き `"` を奪って兄弟タグを丸呑みする。
+        //
+        // strong でない `"` が「属性開始パターン」(`[attr-name-chars]+=` の前が
+        // 空白) にマッチしたら、それは nested な属性開始と判断し、その属性の値を
+        // 次の引用符まで飛ばして外側 scan を再開する。これにより Blocker 2
+        // (`<div title="line1\n<section></section>\nline3" id="real">`) のような
+        // 真に妥当な複数行引用属性値は strong 終端まで到達して通り、一方で未終端な
+        // 外側 `"` は nested を何個かスキップしても strong 終端に到達せず、最終的に
+        // -1 を返して属性パーサが EOL で bail → 次行以降の兄弟タグを拾える。
+        //
+        // strong 終端にも nested にも該当しない `"` は弱い候補として記録し、EOF
+        // 到達時に nested を見ていなければ fallback として返す（`<div id="foo"bar>`
+        // のような malformed でも spec に近い形で拾う）。nested を見ていれば -1 を
+        // 返して、未終端扱いにする。
+        var firstCandidate = -1;
+        var sawNested = false;
+        var i = start;
+        while (i < text.Length)
+        {
+            if (text[i] == quote)
+            {
+                var after = i + 1;
+                if (after >= text.Length)
+                    return i;
+                var nextCh = text[after];
+                if (nextCh == '>' || char.IsWhiteSpace(nextCh))
+                    return i;
+                // Accept the XML-style self-closing marker `"/>` as strong
+                // post-context. Bare `/` is still rejected because it cannot
+                // be distinguished from a path-like `href="/app.css"` opener.
+                // 自己閉鎖タグの `"/>` は strong として受理する。bare `/` は
+                // `href="/app.css"` の開きとの区別が付かないため受理しない。
+                if (nextCh == '/' && after + 1 < text.Length && text[after + 1] == '>')
+                    return i;
+
+                if (IsPrecededByHtmlAttributeStart(text, i, start))
+                {
+                    sawNested = true;
+                    var inner = i + 1;
+                    while (inner < text.Length && text[inner] != quote)
+                        inner++;
+                    if (inner >= text.Length)
+                        break;
+                    i = inner + 1;
+                    continue;
+                }
+
+                if (firstCandidate < 0)
+                    firstCandidate = i;
+            }
+            i++;
+        }
+        if (sawNested)
+            return -1;
+        return firstCandidate;
+    }
+
+    private static bool IsPrecededByHtmlAttributeStart(string text, int quotePos, int scanStart)
+    {
+        // Return true if the characters immediately before `quotePos` form a
+        // `[attr-name-chars]+=` pattern AND the ident is preceded by whitespace
+        // within the current scan — i.e. it looks like the start of a new
+        // attribute inside an outer quoted value. This is the signal that the
+        // `"` is more likely a nested attribute opening than the true close of
+        // the outer value.
+        // `quotePos` の直前が `[attr-name-chars]+=` で、その ident の前が
+        // scan 範囲内の空白文字なら true。外側引用値の中で新しい属性が
+        // 始まっているパターンと判定する。
+        if (quotePos <= scanStart)
+            return false;
+        if (text[quotePos - 1] != '=')
+            return false;
+        var j = quotePos - 2;
+        var identEnd = j + 1;
+        while (j >= scanStart && IsHtmlAttrNameChar(text[j]))
+            j--;
+        if (j + 1 >= identEnd)
+            return false;
+        if (j < scanStart)
+            return false;
+        return char.IsWhiteSpace(text[j]);
+    }
+
+    private static int FindHtmlRawTextClose(string text, int start, string tagName)
+    {
+        // Locate the next `</tagName` (case-insensitive) at or after `start`.
+        // Returns the position of `<`, or -1 if none.
+        // `</tagName` を大文字小文字非区別で `start` 以降から探し、`<` の位置を返す。
+        var i = start;
+        while (i < text.Length - tagName.Length - 2)
+        {
+            if (text[i] == '<' && text[i + 1] == '/')
+            {
+                var match = true;
+                for (var j = 0; j < tagName.Length; j++)
+                {
+                    if (!EqualsHtmlAsciiIgnoreCase(text[i + 2 + j], tagName[j]))
+                    {
+                        match = false;
+                        break;
+                    }
+                }
+                if (match)
+                {
+                    var after = i + 2 + tagName.Length;
+                    if (after >= text.Length)
+                        return i;
+                    var nc = text[after];
+                    if (nc == '>' || nc == '/' || char.IsWhiteSpace(nc))
+                        return i;
+                }
+            }
+            i++;
+        }
+        return -1;
+    }
+
+    private static bool EqualsHtmlAsciiIgnoreCase(char actual, char expectedLower)
+    {
+        if (actual >= 'A' && actual <= 'Z')
+            actual = (char)(actual + ('a' - 'A'));
+
+        return actual == expectedLower;
+    }
+
+    private static void BlankPreservingNewlines(char[] chars, int start, int end)
+    {
+        var limit = Math.Min(end, chars.Length);
+        for (var i = start; i < limit; i++)
+        {
+            if (chars[i] != '\n' && chars[i] != '\r')
+                chars[i] = ' ';
+        }
+    }
+
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Markdown.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Markdown.cs
new file mode 100644
index 000000000..73f1be1b7
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Markdown.cs
@@ -0,0 +1,509 @@
+using System.Text;
+using System.Text.RegularExpressions;
+using Regex = CodeIndex.Indexer.BoundedRegex;
+using System.Runtime.CompilerServices;
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+
+    private static readonly IReadOnlyDictionary<string, string> EmptyMarkdownReferenceDefinitionTargets =
+        new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+
+    private static List<SymbolRecord> ExtractMarkdownSymbols(long fileId, string[] lines)
+    {
+        // Markdown headings are the closest thing to navigable symbols in docs files.
+        // Markdown の見出しは、ドキュメント内でナビゲート可能な symbol に最も近い。
+        List<SymbolRecord>? symbols = null;
+        Stack<(int Level, int SymbolIndex)>? headingStack = null;
+        var usedHeadingIdentities = new HashSet<string>(StringComparer.Ordinal);
+        var inFence = false;
+        var fenceChar = '\0';
+        var fenceLength = 0;
+        var fenceSymbolIndex = -1;
+        var inHtmlComment = false;
+        var sourceLineCount = lines.Length > 0 && lines[^1].Length == 0
+            ? lines.Length - 1
+            : lines.Length;
+
+        for (var i = 0; i < lines.Length; i++)
+        {
+            if (TryToggleMarkdownFence(lines[i], inFence, fenceChar, fenceLength, out var nextFenceChar, out var nextFenceLength, out var fenceInfo))
+            {
+                if (!inFence)
+                {
+                    var bodyStartLine = i + 2;
+                    var hasBodyAtEof = bodyStartLine <= sourceLineCount;
+                    var codeSymbol = new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "code",
+                        Name = NormalizeMarkdownFenceInfo(fenceInfo),
+                        Line = i + 1,
+                        StartLine = i + 1,
+                        EndLine = sourceLineCount,
+                        BodyStartLine = hasBodyAtEof ? bodyStartLine : null,
+                        BodyEndLine = hasBodyAtEof ? sourceLineCount : null,
+                        Signature = lines[i].Trim(),
+                    };
+
+                    if (headingStack is { Count: > 0 })
+                    {
+                        var parent = symbols![headingStack.Peek().SymbolIndex];
+                        codeSymbol.ContainerKind = "heading";
+                        codeSymbol.ContainerName = parent.Name;
+                    }
+
+                    (symbols ??= []).Add(codeSymbol);
+                    fenceSymbolIndex = symbols.Count - 1;
+                }
+                else if (fenceSymbolIndex >= 0)
+                {
+                    symbols![fenceSymbolIndex].EndLine = i + 1;
+                    symbols[fenceSymbolIndex].BodyEndLine = Math.Max(symbols[fenceSymbolIndex].BodyStartLine ?? i + 1, i);
+                    fenceSymbolIndex = -1;
+                }
+
+                inFence = nextFenceLength > 0;
+                fenceChar = nextFenceChar;
+                fenceLength = nextFenceLength;
+                continue;
+            }
+
+            if (inFence)
+                continue;
+
+            AddMarkdownExplicitAnchorSymbols(
+                fileId,
+                lines[i],
+                i + 1,
+                headingStack,
+                ref inHtmlComment,
+                ref symbols);
+
+            if (i + 1 < lines.Length
+                && TryParseMarkdownSetextHeading(lines[i], lines[i + 1], out var setextLevel, out var setextHeadingText))
+            {
+                while (headingStack is { Count: > 0 } && headingStack.Peek().Level >= setextLevel)
+                {
+                    var closedHeading = headingStack.Pop();
+                    CloseMarkdownHeading(symbols!, closedHeading.SymbolIndex, i);
+                }
+
+                var setextSymbol = new SymbolRecord
+                {
+                    FileId = fileId,
+                    Kind = "heading",
+                    Name = setextHeadingText,
+                    IdentityNameFolded = MarkdownAnchorIdentity.CreateUniqueHeadingIdentity(
+                        setextHeadingText,
+                        usedHeadingIdentities),
+                    Line = i + 1,
+                    StartLine = i + 1,
+                    EndLine = i + 2,
+                    BodyStartLine = i + 3,
+                    BodyEndLine = sourceLineCount,
+                    Signature = lines[i].TrimEnd(),
+                };
+
+                if (headingStack is { Count: > 0 })
+                {
+                    var parent = symbols![headingStack.Peek().SymbolIndex];
+                    setextSymbol.ContainerKind = "heading";
+                    setextSymbol.ContainerName = parent.Name;
+                }
+
+                (symbols ??= []).Add(setextSymbol);
+                (headingStack ??= new Stack<(int Level, int SymbolIndex)>()).Push((setextLevel, symbols.Count - 1));
+                i++;
+                continue;
+            }
+
+            if (!TryParseMarkdownHeading(lines[i], out var level, out var headingText))
+                continue;
+
+            while (headingStack is { Count: > 0 } && headingStack.Peek().Level >= level)
+            {
+                var closedHeading = headingStack.Pop();
+                CloseMarkdownHeading(symbols!, closedHeading.SymbolIndex, i);
+            }
+
+            var symbol = new SymbolRecord
+            {
+                FileId = fileId,
+                Kind = "heading",
+                Name = headingText,
+                IdentityNameFolded = MarkdownAnchorIdentity.CreateUniqueHeadingIdentity(
+                    headingText,
+                    usedHeadingIdentities),
+                Line = i + 1,
+                StartLine = i + 1,
+                EndLine = i + 1,
+                BodyStartLine = i + 2,
+                BodyEndLine = sourceLineCount,
+                Signature = lines[i].Trim(),
+            };
+
+            if (headingStack is { Count: > 0 })
+            {
+                var parent = symbols![headingStack.Peek().SymbolIndex];
+                symbol.ContainerKind = "heading";
+                symbol.ContainerName = parent.Name;
+            }
+
+            (symbols ??= []).Add(symbol);
+            (headingStack ??= new Stack<(int Level, int SymbolIndex)>()).Push((level, symbols.Count - 1));
+        }
+
+        while (headingStack is { Count: > 0 })
+        {
+            var closedHeading = headingStack.Pop();
+            CloseMarkdownHeading(symbols!, closedHeading.SymbolIndex, sourceLineCount);
+        }
+
+        return symbols ?? [];
+    }
+
+    private static void CloseMarkdownHeading(List<SymbolRecord> symbols, int symbolIndex, int endLine)
+    {
+        var symbol = symbols[symbolIndex];
+        symbol.EndLine = endLine;
+        if (symbol.BodyStartLine is int bodyStartLine && bodyStartLine <= endLine)
+        {
+            symbol.BodyEndLine = endLine;
+            return;
+        }
+
+        symbol.BodyStartLine = null;
+        symbol.BodyEndLine = null;
+    }
+
+    private static void AddMarkdownExplicitAnchorSymbols(
+        long fileId,
+        string line,
+        int lineNumber,
+        Stack<(int Level, int SymbolIndex)>? headingStack,
+        ref bool inHtmlComment,
+        ref List<SymbolRecord>? symbols)
+    {
+        for (var index = 0; index < line.Length;)
+        {
+            if (inHtmlComment)
+            {
+                var commentEnd = line.IndexOf("-->", index, StringComparison.Ordinal);
+                if (commentEnd < 0)
+                    return;
+                inHtmlComment = false;
+                index = commentEnd + 3;
+                continue;
+            }
+
+            if (line.AsSpan(index).StartsWith("<!--", StringComparison.Ordinal))
+            {
+                inHtmlComment = true;
+                index += 4;
+                continue;
+            }
+
+            if (line[index] == '`')
+            {
+                var delimiterLength = 1;
+                while (index + delimiterLength < line.Length
+                       && line[index + delimiterLength] == '`')
+                {
+                    delimiterLength++;
+                }
+
+                var closing = line.IndexOf(
+                    new string('`', delimiterLength),
+                    index + delimiterLength,
+                    StringComparison.Ordinal);
+                index = closing >= 0
+                    ? closing + delimiterLength
+                    : index + delimiterLength;
+                continue;
+            }
+
+            if (!IsMarkdownAnchorTagStart(line, index)
+                || !TryFindMarkdownTagEnd(line, index, out var tagEnd))
+            {
+                index++;
+                continue;
+            }
+
+            AddMarkdownExplicitAnchorTagSymbols(
+                fileId,
+                line,
+                lineNumber,
+                index,
+                tagEnd,
+                headingStack,
+                ref symbols);
+            index = tagEnd + 1;
+        }
+    }
+
+    private static bool IsMarkdownAnchorTagStart(string line, int index) =>
+        line[index] == '<'
+        && index + 2 < line.Length
+        && line[index + 1] is 'a' or 'A'
+        && (char.IsWhiteSpace(line[index + 2]) || line[index + 2] is '>' or '/');
+
+    private static bool TryFindMarkdownTagEnd(string line, int tagStart, out int tagEnd)
+    {
+        var quote = '\0';
+        for (var index = tagStart + 2; index < line.Length; index++)
+        {
+            var current = line[index];
+            if (quote != '\0')
+            {
+                if (current == quote)
+                    quote = '\0';
+                continue;
+            }
+
+            if (current is '"' or '\'')
+            {
+                quote = current;
+                continue;
+            }
+
+            if (current == '>')
+            {
+                tagEnd = index;
+                return true;
+            }
+        }
+
+        tagEnd = -1;
+        return false;
+    }
+
+    private static void AddMarkdownExplicitAnchorTagSymbols(
+        long fileId,
+        string line,
+        int lineNumber,
+        int tagStart,
+        int tagEnd,
+        Stack<(int Level, int SymbolIndex)>? headingStack,
+        ref List<SymbolRecord>? symbols)
+    {
+        var identities = new HashSet<string>(StringComparer.Ordinal);
+        var index = tagStart + 2;
+        while (index < tagEnd)
+        {
+            while (index < tagEnd && (char.IsWhiteSpace(line[index]) || line[index] == '/'))
+                index++;
+            if (index >= tagEnd)
+                break;
+
+            var nameStart = index;
+            while (index < tagEnd && IsHtmlAttrNameChar(line[index]))
+                index++;
+            if (index == nameStart)
+            {
+                index++;
+                continue;
+            }
+
+            var attributeName = line.AsSpan(nameStart, index - nameStart);
+            while (index < tagEnd && char.IsWhiteSpace(line[index]))
+                index++;
+            if (index >= tagEnd || line[index] != '=')
+                continue;
+
+            index++;
+            while (index < tagEnd && char.IsWhiteSpace(line[index]))
+                index++;
+            if (index >= tagEnd)
+                break;
+
+            var quote = line[index] is '"' or '\'' ? line[index++] : '\0';
+            var valueStart = index;
+            if (quote == '\0')
+            {
+                while (index < tagEnd && !char.IsWhiteSpace(line[index]) && line[index] != '>')
+                    index++;
+            }
+            else
+            {
+                while (index < tagEnd && line[index] != quote)
+                    index++;
+            }
+
+            var valueEnd = index;
+            if (quote != '\0' && index < tagEnd)
+                index++;
+
+            if (!attributeName.Equals("id", StringComparison.OrdinalIgnoreCase)
+                && !attributeName.Equals("name", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            var identity = MarkdownAnchorIdentity.NormalizeExplicitAnchorDefinition(
+                line[valueStart..valueEnd]);
+            if (identity.Length == 0 || !identities.Add(identity))
+                continue;
+
+            var symbol = new SymbolRecord
+            {
+                FileId = fileId,
+                Kind = "anchor",
+                Name = identity,
+                IdentityNameFolded = identity,
+                Line = lineNumber,
+                StartLine = lineNumber,
+                EndLine = lineNumber,
+                Signature = line[tagStart..(tagEnd + 1)].Trim(),
+            };
+            if (headingStack is { Count: > 0 } && symbols != null)
+            {
+                var parent = symbols[headingStack.Peek().SymbolIndex];
+                symbol.ContainerKind = "heading";
+                symbol.ContainerName = parent.Name;
+            }
+
+            (symbols ??= []).Add(symbol);
+        }
+    }
+
+    private static bool TryToggleMarkdownFence(
+        string line,
+        bool inFence,
+        char fenceChar,
+        int fenceLength,
+        out char nextFenceChar,
+        out int nextFenceLength,
+        out string fenceInfo)
+    {
+        nextFenceChar = '\0';
+        nextFenceLength = 0;
+        fenceInfo = string.Empty;
+
+        var index = 0;
+        while (index < line.Length && index < 3 && line[index] == ' ')
+            index++;
+
+        if (index > 3 || index >= line.Length)
+            return false;
+
+        var marker = line[index];
+        if (marker is not ('`' or '~'))
+            return false;
+
+        var length = index;
+        while (length < line.Length && line[length] == marker)
+            length++;
+
+        if (length - index < 3)
+            return false;
+
+        if (inFence && marker == fenceChar && length - index >= fenceLength)
+            return true;
+
+        if (!inFence)
+        {
+            nextFenceChar = marker;
+            nextFenceLength = length - index;
+            fenceInfo = line[length..].Trim();
+            return true;
+        }
+
+        return false;
+    }
+
+    private static string NormalizeMarkdownFenceInfo(string fenceInfo)
+    {
+        var normalized = fenceInfo.Trim();
+        if (normalized.Length == 0)
+            return "code";
+
+        var separatorIndex = normalized.IndexOfAny([' ', '\t', '\r', '\n']);
+        if (separatorIndex >= 0)
+            normalized = normalized[..separatorIndex];
+
+        return normalized.Length == 0 ? "code" : normalized;
+    }
+
+    private static bool TryParseMarkdownSetextHeading(string currentLine, string nextLine, out int level, out string headingText)
+    {
+        level = 0;
+        headingText = string.Empty;
+
+        var trimmedHeading = currentLine.AsSpan().Trim();
+        if (trimmedHeading.IsEmpty)
+            return false;
+
+        if (TryParseMarkdownHeading(currentLine, out _, out _))
+            return false;
+
+        var trimmedUnderline = nextLine.AsSpan().Trim();
+        if (trimmedUnderline.Length < 3)
+            return false;
+
+        var underlineChar = trimmedUnderline[0];
+        if (underlineChar is not ('=' or '-'))
+            return false;
+
+        for (var i = 1; i < trimmedUnderline.Length; i++)
+        {
+            if (trimmedUnderline[i] != underlineChar)
+                return false;
+        }
+
+        level = underlineChar == '=' ? 1 : 2;
+        headingText = trimmedHeading.ToString();
+        return true;
+    }
+
+    private static bool TryParseMarkdownHeading(string line, out int level, out string headingText)
+    {
+        level = 0;
+        headingText = string.Empty;
+
+        var index = 0;
+        while (index < line.Length && index < 3 && line[index] == ' ')
+            index++;
+
+        if (index > 3 || index >= line.Length || line[index] != '#')
+            return false;
+
+        var hashStart = index;
+        while (index < line.Length && line[index] == '#')
+            index++;
+
+        level = index - hashStart;
+        if (level is < 1 or > 6)
+            return false;
+
+        if (index < line.Length && !char.IsWhiteSpace(line[index]))
+            return false;
+
+        while (index < line.Length && char.IsWhiteSpace(line[index]))
+            index++;
+
+        if (index >= line.Length)
+            return false;
+
+        var headingSpan = line.AsSpan(index).Trim();
+        if (headingSpan.IsEmpty)
+            return false;
+
+        var closingHashesStart = headingSpan.Length;
+        while (closingHashesStart > 0 && headingSpan[closingHashesStart - 1] == '#')
+            closingHashesStart--;
+
+        if (closingHashesStart < headingSpan.Length && closingHashesStart > 0 && char.IsWhiteSpace(headingSpan[closingHashesStart - 1]))
+            headingSpan = headingSpan[..(closingHashesStart - 1)].TrimEnd();
+
+        if (headingSpan.IsEmpty)
+            return false;
+
+        headingText = headingSpan.ToString();
+        return true;
+    }
+
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Markup.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Markup.cs
deleted file mode 100644
index 1158cc0c8..000000000
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Markup.cs
+++ /dev/null
@@ -1,3289 +0,0 @@
-using System.Text;
-using System.Text.RegularExpressions;
-using Regex = CodeIndex.Indexer.BoundedRegex;
-using System.Runtime.CompilerServices;
-using CodeIndex.Models;
-
-namespace CodeIndex.Indexer;
-
-public static partial class SymbolExtractor
-{
-    private static readonly string[] WrappedXamlTypeBearingAttributeNames = ["x:Class", "x:DataType", "TargetType"];
-    private static readonly IReadOnlyDictionary<string, string> EmptyMarkdownReferenceDefinitionTargets =
-        new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
-
-    private static List<SymbolRecord> ExtractHtmlSymbols(long fileId, string rawText, string[] lines)
-    {
-        const string defaultSlotSymbolName = "(default)";
-
-        if (!LinesContain(lines, '<'))
-            return [];
-
-        // HTML needs proper tag-structure awareness so attribute lookalikes inside
-        // other attributes' quoted values (e.g. `<link title="href=evil.css" href="/real.css">`)
-        // don't leak phantom imports AND real attributes on the same tag aren't
-        // skipped. Regex alone can't do this — the outer tag context is lost once
-        // an attribute inside it is rejected — so walk the masked text with a
-        // character state machine that enumerates each tag's attributes in order.
-        // HTML は同一タグ内で別属性の引用符付き値に書かれた attribute 名の文字列（例:
-        // `<link title="href=evil.css" href="/real.css">`）から phantom な import を
-        // 漏らさず、かつ本物の属性を飛ばさないために、タグ構造を理解した走査が必要。
-        // regex だけでは、タグ内のある属性を mask で落とした瞬間に外側タグのコンテキスト
-        // を失うため不可能。マスク済みテキストを文字単位の state machine で走査し、タグ
-        // ごとに属性を列挙していく。
-        var maskedText = MayNeedHtmlRawTextMask(rawText)
-            ? MaskHtmlRawTextRegions(rawText)
-            : rawText;
-
-        // Build per-line absolute offsets only once a symbol needs O(log n)
-        // offset-to-line lookup. Plain markup with no emitted symbols can skip it.
-        // シンボルが offset-to-line lookup を必要とする時だけ行ごとの絶対 offset を作る。
-        // emit 対象のない plain markup では確保を避ける。
-        int[]? lineStarts = null;
-
-        List<SymbolRecord>? symbols = null;
-        var pos = 0;
-        while (pos < maskedText.Length)
-        {
-            if (maskedText[pos] != '<')
-            {
-                pos++;
-                continue;
-            }
-
-            // Skip closing tags, comments/doctypes/CDATA, and processing instructions.
-            // Raw-text bodies (<script>/<style>) and comments have already been masked
-            // by MaskHtmlRawTextRegions, but the opening/closing tags themselves remain.
-            // 閉じタグ / コメント / doctype / 処理命令はここで読み飛ばす。raw-text 本文と
-            // HTML コメントは MaskHtmlRawTextRegions で既に空白化されているが、開始タグ
-            // 自体はそのまま残っているため通常の属性走査対象になる。
-            if (pos + 1 < maskedText.Length && (maskedText[pos + 1] == '/' || maskedText[pos + 1] == '!' || maskedText[pos + 1] == '?'))
-            {
-                pos = IndexOfOrEnd(maskedText, '>', pos + 1) + 1;
-                continue;
-            }
-
-            var tagNameStart = pos + 1;
-            if (tagNameStart >= maskedText.Length || !IsHtmlTagNameStart(maskedText[tagNameStart]))
-            {
-                pos++;
-                continue;
-            }
-
-            var tagNameEnd = tagNameStart;
-            while (tagNameEnd < maskedText.Length && IsHtmlTagNameChar(maskedText[tagNameEnd]))
-                tagNameEnd++;
-
-            var tagName = maskedText[tagNameStart..tagNameEnd];
-            var sawNamedSlotDeclaration = false;
-
-            // Emit custom Web Components (hyphenated opening tag) at the `<` position,
-            // but skip the standard HTML/SVG/MathML tags that happen to contain a hyphen
-            // (`<font-face>`, `<color-profile>`, `<annotation-xml>`, etc.). Those are
-            // native elements, not user components, so labeling them as `class` symbols
-            // would pollute `symbols` / `definition` / `outline` on any project with
-            // inline SVG / MathML content.
-            // 開始タグ名にハイフンを含むカスタム Web Components を `<` の位置で emit する。
-            // ただしハイフン付きでも仕様で予約されている `<font-face>` / `<color-profile>`
-            // / `<annotation-xml>` などの標準タグは除外する。SVG / MathML を埋め込んだ
-            // ファイルで `symbols` / `definition` / `outline` が汚染されるのを防ぐ。
-            if (tagName.Contains('-') && !HtmlReservedHyphenatedTags.Contains(tagName))
-            {
-                var startLine = FindHtmlLineNumber(lineStarts ??= BuildLineStarts(lines), pos);
-                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-                (symbols ??= []).Add(new SymbolRecord
-                {
-                    FileId = fileId,
-                    Kind = "class",
-                    Name = tagName,
-                    Line = startLine,
-                    StartLine = startLine,
-                    EndLine = startLine,
-                    Signature = lines[signatureIndex].Trim(),
-                });
-            }
-
-            // Walk the tag body, enumerating attribute name/value pairs until `>` or EOF.
-            // タグ本体を走査し、`>` か EOF まで属性 name/value を順に列挙する。
-            var cursor = tagNameEnd;
-            while (cursor < maskedText.Length && maskedText[cursor] != '>')
-            {
-                // Skip whitespace and stray '/' (self-closing marker).
-                // 空白文字と self-closing の `/` を読み飛ばす。
-                if (char.IsWhiteSpace(maskedText[cursor]) || maskedText[cursor] == '/')
-                {
-                    cursor++;
-                    continue;
-                }
-
-                // Read attribute name. HTML5 allows broad attribute-name charsets, but for
-                // our emit rules we only need to recognize ASCII names plus `:` / `-` / `.`
-                // (xml:id, data-*, aria-*, etc.). Anything else aborts the parse of this tag
-                // gracefully by treating it as a non-matching attribute start.
-                // 属性名を読む。HTML5 の属性名は広いが、emit 対象の判定には ASCII の名前と
-                // `:` / `-` / `.` が拾えれば十分（xml:id, data-*, aria-* 等を含めるため）。
-                // それ以外の文字が来たら、このタグのパースは壊さずに 1 文字進めるだけで抜ける。
-                if (!IsHtmlAttrNameStart(maskedText[cursor]))
-                {
-                    cursor++;
-                    continue;
-                }
-                var attrNameStart = cursor;
-                while (cursor < maskedText.Length && IsHtmlAttrNameChar(maskedText[cursor]))
-                    cursor++;
-                var attrName = maskedText[attrNameStart..cursor];
-
-                // Skip whitespace between name and `=`.
-                while (cursor < maskedText.Length && char.IsWhiteSpace(maskedText[cursor]))
-                    cursor++;
-
-                string? attrValue = null;
-                int attrValueStart = -1;
-                if (cursor < maskedText.Length && maskedText[cursor] == '=')
-                {
-                    cursor++;
-                    while (cursor < maskedText.Length && char.IsWhiteSpace(maskedText[cursor]))
-                        cursor++;
-                    if (cursor < maskedText.Length && (maskedText[cursor] == '"' || maskedText[cursor] == '\''))
-                    {
-                        var quote = maskedText[cursor];
-                        cursor++;
-                        attrValueStart = cursor;
-                        // Use the shared FindHtmlQuoteClose helper so this and the raw-text
-                        // mask agree on where quoted attribute values end. The helper allows
-                        // multi-line quoted values (valid HTML5 like `<div title="line1\n
-                        // line2" id="real">` where `id="real"` must still be emitted) and
-                        // tag-like content inside quoted values, identifying the close by
-                        // post-value context (`>`, `/`, whitespace, or EOF). Only truly
-                        // unterminated quotes (no matching `"` at all) return -1, so the
-                        // caller can bail to EOL without walking to EOF.
-                        // 共有ヘルパー `FindHtmlQuoteClose` を使い、mask 側とも引用符終端の
-                        // 判断を一致させる。複数行 quoted 属性値 (`<div title="line1\n
-                        // line2" id="real">` など) とタグ様テキストを含む引用符付き値を
-                        // 許容し、`>` / `/` / 空白 / EOF が直後に来る位置を終端として検出する。
-                        // 真に未終端（マッチ `"` が存在しない）場合のみ -1 を返し、呼び出し側が
-                        // EOF まで走らず行末で被害を止められるようにする。
-                        var valueEnd = FindHtmlQuoteClose(maskedText, cursor, quote);
-                        if (valueEnd < 0)
-                        {
-                            // Unterminated: bail to end of current line so the outer tag
-                            // loop can restart at the beginning of the next line's `<`.
-                            // 未終端: 当該行末まで進め、次行先頭の `<` から外側ループが再開できるようにする。
-                            attrValue = null;
-                            var eol = maskedText.IndexOf('\n', cursor);
-                            cursor = eol < 0 ? maskedText.Length : eol;
-                            break;
-                        }
-                        attrValue = maskedText[cursor..valueEnd];
-                        cursor = valueEnd + 1;
-                    }
-                    else if (cursor < maskedText.Length && maskedText[cursor] != '>')
-                    {
-                        // Unquoted value: HTML5 excludes space, `"`, `'`, `=`, `<`, `>`, backtick.
-                        // 引用符なし値: HTML5 では空白、`"`、`'`、`=`、`<`、`>`、バッククォートを除外。
-                        attrValueStart = cursor;
-                        while (cursor < maskedText.Length && !IsHtmlUnquotedValueTerminator(maskedText[cursor]))
-                            cursor++;
-                        attrValue = maskedText[attrValueStart..cursor];
-                    }
-                }
-
-                if (IsHtmlSemanticStateAttributeName(attrName))
-                {
-                    var attrStartLine = FindHtmlLineNumber(lineStarts ??= BuildLineStarts(lines), attrNameStart);
-                    var attrSignatureIndex = Math.Clamp(attrStartLine - 1, 0, lines.Length - 1);
-                    (symbols ??= []).Add(new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "property",
-                        Name = NormalizeHtmlAttributeName(attrName),
-                        Line = attrStartLine,
-                        StartLine = attrStartLine,
-                        EndLine = attrStartLine,
-                        Signature = lines[attrSignatureIndex].Trim(),
-                    });
-                }
-
-                if (attrValue == null || attrValue.Length == 0)
-                    continue;
-
-                string? emitKind = null;
-                string? singleEmittedName = null;
-                IEnumerable<string>? emittedNames = null;
-                if (IsHtmlAttributeName(attrName, "src") && IsHtmlSrcResourceTag(tagName))
-                {
-                    emitKind = "import";
-                    singleEmittedName = attrValue.Trim();
-                }
-                else if (IsHtmlAttributeName(attrName, "srcset") && IsHtmlSrcsetResourceTag(tagName))
-                {
-                    emitKind = "import";
-                    emittedNames = EnumerateHtmlSrcsetUrls(attrValue);
-                }
-                else if ((IsHtmlAttributeName(attrName, "href") || IsHtmlAttributeName(attrName, "xlink:href")) && IsHtmlHrefResourceTag(tagName))
-                {
-                    emitKind = "import";
-                    singleEmittedName = attrValue.Trim();
-                }
-                else if (IsHtmlAttributeName(attrName, "data") && IsHtmlTagName(tagName, "object"))
-                {
-                    emitKind = "import";
-                    singleEmittedName = attrValue.Trim();
-                }
-                else if (IsHtmlAttributeName(attrName, "poster") && IsHtmlTagName(tagName, "video"))
-                {
-                    emitKind = "import";
-                    singleEmittedName = attrValue.Trim();
-                }
-                else if (IsHtmlAttributeName(attrName, "id") && !attrName.Contains(':') && !attrName.Contains('-') && !attrName.Contains('.'))
-                {
-                    emitKind = "property";
-                    singleEmittedName = attrValue.Trim();
-                }
-                else if (IsHtmlAttributeName(attrName, "class") || IsHtmlAttributeName(attrName, "classname"))
-                {
-                    emitKind = "reference";
-                    emittedNames = EnumerateHtmlClassNames(attrValue);
-                }
-                else if (IsHtmlAttributeName(attrName, "name") && IsHtmlTagName(tagName, "slot"))
-                {
-                    var slotName = attrValue.Trim();
-                    if (slotName.Length > 0)
-                    {
-                        emitKind = "property";
-                        singleEmittedName = slotName;
-                        sawNamedSlotDeclaration = true;
-                    }
-                }
-                else if (IsHtmlAttributeName(attrName, "slot"))
-                {
-                    var slotName = attrValue.Trim();
-                    if (slotName.Length > 0)
-                    {
-                        emitKind = "reference";
-                        singleEmittedName = slotName;
-                    }
-                }
-
-                if (emitKind == null || (singleEmittedName == null && emittedNames == null))
-                    continue;
-
-                // Anchor the symbol at the attribute value so cross-line tags like
-                // `<script\n  type="module"\n  src="/app.js">` land on the line that
-                // actually carries the value.
-                // 属性値の位置でシンボルを固定し、属性が折り返されたタグでも値が書かれた
-                // 行にジャンプできるようにする。
-                var anchor = attrValueStart >= 0 ? attrValueStart : pos;
-                var startLine = FindHtmlLineNumber(lineStarts ??= BuildLineStarts(lines), anchor);
-                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-
-                void AddEmittedName(string emittedName)
-                {
-                    (symbols ??= []).Add(new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = emitKind!,
-                        Name = emittedName,
-                        Line = startLine,
-                        StartLine = startLine,
-                        EndLine = startLine,
-                        Signature = lines[signatureIndex].Trim(),
-                    });
-                }
-
-                if (singleEmittedName != null)
-                {
-                    AddEmittedName(singleEmittedName);
-                    continue;
-                }
-
-                if (emittedNames == null)
-                    continue;
-
-                foreach (var emittedName in emittedNames)
-                    AddEmittedName(emittedName);
-            }
-
-            if (IsHtmlTagName(tagName, "slot") && !sawNamedSlotDeclaration)
-            {
-                var startLine = FindHtmlLineNumber(lineStarts ??= BuildLineStarts(lines), pos);
-                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-                (symbols ??= []).Add(new SymbolRecord
-                {
-                    FileId = fileId,
-                    Kind = "property",
-                    Name = defaultSlotSymbolName,
-                    Line = startLine,
-                    StartLine = startLine,
-                    EndLine = startLine,
-                    Signature = lines[signatureIndex].Trim(),
-                });
-            }
-
-            pos = cursor < maskedText.Length ? cursor + 1 : cursor;
-        }
-
-        if (symbols is null)
-            return [];
-
-        AssignContainers(symbols, lines, null);
-        PopulateDeclaredContainerQualifiedNames(symbols);
-        return symbols;
-    }
-
-    private static IEnumerable<string> EnumerateHtmlClassNames(string value)
-    {
-        var tokenStart = -1;
-        for (var index = 0; index <= value.Length; index++)
-        {
-            var atEnd = index == value.Length;
-            if (!atEnd && !char.IsWhiteSpace(value[index]))
-            {
-                if (tokenStart < 0)
-                    tokenStart = index;
-                continue;
-            }
-
-            if (tokenStart < 0)
-                continue;
-
-            yield return value[tokenStart..index];
-            tokenStart = -1;
-        }
-    }
-
-    private static bool IsHtmlSemanticStateAttributeName(string attrName)
-    {
-        return (attrName.StartsWith("data-", StringComparison.OrdinalIgnoreCase) ||
-                attrName.StartsWith("aria-", StringComparison.OrdinalIgnoreCase)) &&
-               attrName.Length > 5;
-    }
-
-    private static string NormalizeHtmlAttributeName(string attrName)
-    {
-        for (var index = 0; index < attrName.Length; index++)
-        {
-            var ch = attrName[index];
-            if (ch >= 'A' && ch <= 'Z')
-                return attrName.ToLowerInvariant();
-        }
-
-        return attrName;
-    }
-
-    private static bool IsHtmlAttributeName(string attrName, string expected) =>
-        attrName.Equals(expected, StringComparison.OrdinalIgnoreCase);
-
-    private static List<SymbolRecord> ExtractMarkdownSymbols(long fileId, string[] lines)
-    {
-        // Markdown headings are the closest thing to navigable symbols in docs files.
-        // Markdown の見出しは、ドキュメント内でナビゲート可能な symbol に最も近い。
-        List<SymbolRecord>? symbols = null;
-        Stack<(int Level, int SymbolIndex)>? headingStack = null;
-        var usedHeadingIdentities = new HashSet<string>(StringComparer.Ordinal);
-        var inFence = false;
-        var fenceChar = '\0';
-        var fenceLength = 0;
-        var fenceSymbolIndex = -1;
-        var inHtmlComment = false;
-        var sourceLineCount = lines.Length > 0 && lines[^1].Length == 0
-            ? lines.Length - 1
-            : lines.Length;
-
-        for (var i = 0; i < lines.Length; i++)
-        {
-            if (TryToggleMarkdownFence(lines[i], inFence, fenceChar, fenceLength, out var nextFenceChar, out var nextFenceLength, out var fenceInfo))
-            {
-                if (!inFence)
-                {
-                    var bodyStartLine = i + 2;
-                    var hasBodyAtEof = bodyStartLine <= sourceLineCount;
-                    var codeSymbol = new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "code",
-                        Name = NormalizeMarkdownFenceInfo(fenceInfo),
-                        Line = i + 1,
-                        StartLine = i + 1,
-                        EndLine = sourceLineCount,
-                        BodyStartLine = hasBodyAtEof ? bodyStartLine : null,
-                        BodyEndLine = hasBodyAtEof ? sourceLineCount : null,
-                        Signature = lines[i].Trim(),
-                    };
-
-                    if (headingStack is { Count: > 0 })
-                    {
-                        var parent = symbols![headingStack.Peek().SymbolIndex];
-                        codeSymbol.ContainerKind = "heading";
-                        codeSymbol.ContainerName = parent.Name;
-                    }
-
-                    (symbols ??= []).Add(codeSymbol);
-                    fenceSymbolIndex = symbols.Count - 1;
-                }
-                else if (fenceSymbolIndex >= 0)
-                {
-                    symbols![fenceSymbolIndex].EndLine = i + 1;
-                    symbols[fenceSymbolIndex].BodyEndLine = Math.Max(symbols[fenceSymbolIndex].BodyStartLine ?? i + 1, i);
-                    fenceSymbolIndex = -1;
-                }
-
-                inFence = nextFenceLength > 0;
-                fenceChar = nextFenceChar;
-                fenceLength = nextFenceLength;
-                continue;
-            }
-
-            if (inFence)
-                continue;
-
-            AddMarkdownExplicitAnchorSymbols(
-                fileId,
-                lines[i],
-                i + 1,
-                headingStack,
-                ref inHtmlComment,
-                ref symbols);
-
-            if (i + 1 < lines.Length
-                && TryParseMarkdownSetextHeading(lines[i], lines[i + 1], out var setextLevel, out var setextHeadingText))
-            {
-                while (headingStack is { Count: > 0 } && headingStack.Peek().Level >= setextLevel)
-                {
-                    var closedHeading = headingStack.Pop();
-                    CloseMarkdownHeading(symbols!, closedHeading.SymbolIndex, i);
-                }
-
-                var setextSymbol = new SymbolRecord
-                {
-                    FileId = fileId,
-                    Kind = "heading",
-                    Name = setextHeadingText,
-                    IdentityNameFolded = MarkdownAnchorIdentity.CreateUniqueHeadingIdentity(
-                        setextHeadingText,
-                        usedHeadingIdentities),
-                    Line = i + 1,
-                    StartLine = i + 1,
-                    EndLine = i + 2,
-                    BodyStartLine = i + 3,
-                    BodyEndLine = sourceLineCount,
-                    Signature = lines[i].TrimEnd(),
-                };
-
-                if (headingStack is { Count: > 0 })
-                {
-                    var parent = symbols![headingStack.Peek().SymbolIndex];
-                    setextSymbol.ContainerKind = "heading";
-                    setextSymbol.ContainerName = parent.Name;
-                }
-
-                (symbols ??= []).Add(setextSymbol);
-                (headingStack ??= new Stack<(int Level, int SymbolIndex)>()).Push((setextLevel, symbols.Count - 1));
-                i++;
-                continue;
-            }
-
-            if (!TryParseMarkdownHeading(lines[i], out var level, out var headingText))
-                continue;
-
-            while (headingStack is { Count: > 0 } && headingStack.Peek().Level >= level)
-            {
-                var closedHeading = headingStack.Pop();
-                CloseMarkdownHeading(symbols!, closedHeading.SymbolIndex, i);
-            }
-
-            var symbol = new SymbolRecord
-            {
-                FileId = fileId,
-                Kind = "heading",
-                Name = headingText,
-                IdentityNameFolded = MarkdownAnchorIdentity.CreateUniqueHeadingIdentity(
-                    headingText,
-                    usedHeadingIdentities),
-                Line = i + 1,
-                StartLine = i + 1,
-                EndLine = i + 1,
-                BodyStartLine = i + 2,
-                BodyEndLine = sourceLineCount,
-                Signature = lines[i].Trim(),
-            };
-
-            if (headingStack is { Count: > 0 })
-            {
-                var parent = symbols![headingStack.Peek().SymbolIndex];
-                symbol.ContainerKind = "heading";
-                symbol.ContainerName = parent.Name;
-            }
-
-            (symbols ??= []).Add(symbol);
-            (headingStack ??= new Stack<(int Level, int SymbolIndex)>()).Push((level, symbols.Count - 1));
-        }
-
-        while (headingStack is { Count: > 0 })
-        {
-            var closedHeading = headingStack.Pop();
-            CloseMarkdownHeading(symbols!, closedHeading.SymbolIndex, sourceLineCount);
-        }
-
-        return symbols ?? [];
-    }
-
-    private static void CloseMarkdownHeading(List<SymbolRecord> symbols, int symbolIndex, int endLine)
-    {
-        var symbol = symbols[symbolIndex];
-        symbol.EndLine = endLine;
-        if (symbol.BodyStartLine is int bodyStartLine && bodyStartLine <= endLine)
-        {
-            symbol.BodyEndLine = endLine;
-            return;
-        }
-
-        symbol.BodyStartLine = null;
-        symbol.BodyEndLine = null;
-    }
-
-    private static void AddMarkdownExplicitAnchorSymbols(
-        long fileId,
-        string line,
-        int lineNumber,
-        Stack<(int Level, int SymbolIndex)>? headingStack,
-        ref bool inHtmlComment,
-        ref List<SymbolRecord>? symbols)
-    {
-        for (var index = 0; index < line.Length;)
-        {
-            if (inHtmlComment)
-            {
-                var commentEnd = line.IndexOf("-->", index, StringComparison.Ordinal);
-                if (commentEnd < 0)
-                    return;
-                inHtmlComment = false;
-                index = commentEnd + 3;
-                continue;
-            }
-
-            if (line.AsSpan(index).StartsWith("<!--", StringComparison.Ordinal))
-            {
-                inHtmlComment = true;
-                index += 4;
-                continue;
-            }
-
-            if (line[index] == '`')
-            {
-                var delimiterLength = 1;
-                while (index + delimiterLength < line.Length
-                       && line[index + delimiterLength] == '`')
-                {
-                    delimiterLength++;
-                }
-
-                var closing = line.IndexOf(
-                    new string('`', delimiterLength),
-                    index + delimiterLength,
-                    StringComparison.Ordinal);
-                index = closing >= 0
-                    ? closing + delimiterLength
-                    : index + delimiterLength;
-                continue;
-            }
-
-            if (!IsMarkdownAnchorTagStart(line, index)
-                || !TryFindMarkdownTagEnd(line, index, out var tagEnd))
-            {
-                index++;
-                continue;
-            }
-
-            AddMarkdownExplicitAnchorTagSymbols(
-                fileId,
-                line,
-                lineNumber,
-                index,
-                tagEnd,
-                headingStack,
-                ref symbols);
-            index = tagEnd + 1;
-        }
-    }
-
-    private static bool IsMarkdownAnchorTagStart(string line, int index) =>
-        line[index] == '<'
-        && index + 2 < line.Length
-        && line[index + 1] is 'a' or 'A'
-        && (char.IsWhiteSpace(line[index + 2]) || line[index + 2] is '>' or '/');
-
-    private static bool TryFindMarkdownTagEnd(string line, int tagStart, out int tagEnd)
-    {
-        var quote = '\0';
-        for (var index = tagStart + 2; index < line.Length; index++)
-        {
-            var current = line[index];
-            if (quote != '\0')
-            {
-                if (current == quote)
-                    quote = '\0';
-                continue;
-            }
-
-            if (current is '"' or '\'')
-            {
-                quote = current;
-                continue;
-            }
-
-            if (current == '>')
-            {
-                tagEnd = index;
-                return true;
-            }
-        }
-
-        tagEnd = -1;
-        return false;
-    }
-
-    private static void AddMarkdownExplicitAnchorTagSymbols(
-        long fileId,
-        string line,
-        int lineNumber,
-        int tagStart,
-        int tagEnd,
-        Stack<(int Level, int SymbolIndex)>? headingStack,
-        ref List<SymbolRecord>? symbols)
-    {
-        var identities = new HashSet<string>(StringComparer.Ordinal);
-        var index = tagStart + 2;
-        while (index < tagEnd)
-        {
-            while (index < tagEnd && (char.IsWhiteSpace(line[index]) || line[index] == '/'))
-                index++;
-            if (index >= tagEnd)
-                break;
-
-            var nameStart = index;
-            while (index < tagEnd && IsHtmlAttrNameChar(line[index]))
-                index++;
-            if (index == nameStart)
-            {
-                index++;
-                continue;
-            }
-
-            var attributeName = line.AsSpan(nameStart, index - nameStart);
-            while (index < tagEnd && char.IsWhiteSpace(line[index]))
-                index++;
-            if (index >= tagEnd || line[index] != '=')
-                continue;
-
-            index++;
-            while (index < tagEnd && char.IsWhiteSpace(line[index]))
-                index++;
-            if (index >= tagEnd)
-                break;
-
-            var quote = line[index] is '"' or '\'' ? line[index++] : '\0';
-            var valueStart = index;
-            if (quote == '\0')
-            {
-                while (index < tagEnd && !char.IsWhiteSpace(line[index]) && line[index] != '>')
-                    index++;
-            }
-            else
-            {
-                while (index < tagEnd && line[index] != quote)
-                    index++;
-            }
-
-            var valueEnd = index;
-            if (quote != '\0' && index < tagEnd)
-                index++;
-
-            if (!attributeName.Equals("id", StringComparison.OrdinalIgnoreCase)
-                && !attributeName.Equals("name", StringComparison.OrdinalIgnoreCase))
-            {
-                continue;
-            }
-
-            var identity = MarkdownAnchorIdentity.NormalizeExplicitAnchorDefinition(
-                line[valueStart..valueEnd]);
-            if (identity.Length == 0 || !identities.Add(identity))
-                continue;
-
-            var symbol = new SymbolRecord
-            {
-                FileId = fileId,
-                Kind = "anchor",
-                Name = identity,
-                IdentityNameFolded = identity,
-                Line = lineNumber,
-                StartLine = lineNumber,
-                EndLine = lineNumber,
-                Signature = line[tagStart..(tagEnd + 1)].Trim(),
-            };
-            if (headingStack is { Count: > 0 } && symbols != null)
-            {
-                var parent = symbols[headingStack.Peek().SymbolIndex];
-                symbol.ContainerKind = "heading";
-                symbol.ContainerName = parent.Name;
-            }
-
-            (symbols ??= []).Add(symbol);
-        }
-    }
-
-    private static bool TryToggleMarkdownFence(
-        string line,
-        bool inFence,
-        char fenceChar,
-        int fenceLength,
-        out char nextFenceChar,
-        out int nextFenceLength,
-        out string fenceInfo)
-    {
-        nextFenceChar = '\0';
-        nextFenceLength = 0;
-        fenceInfo = string.Empty;
-
-        var index = 0;
-        while (index < line.Length && index < 3 && line[index] == ' ')
-            index++;
-
-        if (index > 3 || index >= line.Length)
-            return false;
-
-        var marker = line[index];
-        if (marker is not ('`' or '~'))
-            return false;
-
-        var length = index;
-        while (length < line.Length && line[length] == marker)
-            length++;
-
-        if (length - index < 3)
-            return false;
-
-        if (inFence && marker == fenceChar && length - index >= fenceLength)
-            return true;
-
-        if (!inFence)
-        {
-            nextFenceChar = marker;
-            nextFenceLength = length - index;
-            fenceInfo = line[length..].Trim();
-            return true;
-        }
-
-        return false;
-    }
-
-    private static string NormalizeMarkdownFenceInfo(string fenceInfo)
-    {
-        var normalized = fenceInfo.Trim();
-        if (normalized.Length == 0)
-            return "code";
-
-        var separatorIndex = normalized.IndexOfAny([' ', '\t', '\r', '\n']);
-        if (separatorIndex >= 0)
-            normalized = normalized[..separatorIndex];
-
-        return normalized.Length == 0 ? "code" : normalized;
-    }
-
-    private static bool TryParseMarkdownSetextHeading(string currentLine, string nextLine, out int level, out string headingText)
-    {
-        level = 0;
-        headingText = string.Empty;
-
-        var trimmedHeading = currentLine.AsSpan().Trim();
-        if (trimmedHeading.IsEmpty)
-            return false;
-
-        if (TryParseMarkdownHeading(currentLine, out _, out _))
-            return false;
-
-        var trimmedUnderline = nextLine.AsSpan().Trim();
-        if (trimmedUnderline.Length < 3)
-            return false;
-
-        var underlineChar = trimmedUnderline[0];
-        if (underlineChar is not ('=' or '-'))
-            return false;
-
-        for (var i = 1; i < trimmedUnderline.Length; i++)
-        {
-            if (trimmedUnderline[i] != underlineChar)
-                return false;
-        }
-
-        level = underlineChar == '=' ? 1 : 2;
-        headingText = trimmedHeading.ToString();
-        return true;
-    }
-
-    private static bool TryParseMarkdownHeading(string line, out int level, out string headingText)
-    {
-        level = 0;
-        headingText = string.Empty;
-
-        var index = 0;
-        while (index < line.Length && index < 3 && line[index] == ' ')
-            index++;
-
-        if (index > 3 || index >= line.Length || line[index] != '#')
-            return false;
-
-        var hashStart = index;
-        while (index < line.Length && line[index] == '#')
-            index++;
-
-        level = index - hashStart;
-        if (level is < 1 or > 6)
-            return false;
-
-        if (index < line.Length && !char.IsWhiteSpace(line[index]))
-            return false;
-
-        while (index < line.Length && char.IsWhiteSpace(line[index]))
-            index++;
-
-        if (index >= line.Length)
-            return false;
-
-        var headingSpan = line.AsSpan(index).Trim();
-        if (headingSpan.IsEmpty)
-            return false;
-
-        var closingHashesStart = headingSpan.Length;
-        while (closingHashesStart > 0 && headingSpan[closingHashesStart - 1] == '#')
-            closingHashesStart--;
-
-        if (closingHashesStart < headingSpan.Length && closingHashesStart > 0 && char.IsWhiteSpace(headingSpan[closingHashesStart - 1]))
-            headingSpan = headingSpan[..(closingHashesStart - 1)].TrimEnd();
-
-        if (headingSpan.IsEmpty)
-            return false;
-
-        headingText = headingSpan.ToString();
-        return true;
-    }
-
-    private static List<SymbolRecord> ExtractXmlSymbols(long fileId, string rawText, string[] lines)
-    {
-        if (!XamlReferenceExtractor.IsXaml(lines))
-            return ExtractGenericXmlSymbols(fileId, rawText, lines);
-        if (!MayContainXamlSymbolMarkers(lines))
-            return [];
-
-        if (TryGetXmlStructureIssue(rawText, out _))
-            return [];
-
-        int[]? lineStarts = null;
-
-        var symbols = CreateSymbolListForLines(lines.Length);
-        for (var i = 0; i < lines.Length; i++)
-        {
-            var line = lines[i];
-            var hasAttributeAssignment = line.IndexOf('=') >= 0;
-            string? signature = null;
-            string Signature() => signature ??= line.Trim();
-
-            if (hasAttributeAssignment && line.Contains("x:Class", StringComparison.Ordinal))
-            {
-                foreach (Match classMatch in Regex.EnumerateMatches(XamlClassRegex, line))
-                {
-                    var value = classMatch.Groups["value"].ValueSpan.Trim().ToString();
-                    if (value.Length == 0)
-                        continue;
-                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "class",
-                        Name = value,
-                        Line = i + 1,
-                        StartLine = i + 1,
-                        EndLine = i + 1,
-                        Signature = Signature(),
-                    }))
-                        continue;
-
-                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
-                }
-            }
-
-            if (hasAttributeAssignment && line.Contains("x:DataType", StringComparison.Ordinal))
-            {
-                foreach (Match dataTypeMatch in Regex.EnumerateMatches(XamlDataTypeRegex, line))
-                {
-                    var value = NormalizeXamlKeyValue(dataTypeMatch.Groups["value"].Value);
-                    if (value.Length == 0)
-                        continue;
-                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "class",
-                        Name = value,
-                        Line = i + 1,
-                        StartLine = i + 1,
-                        EndLine = i + 1,
-                        Signature = Signature(),
-                    }))
-                        continue;
-
-                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
-                }
-            }
-
-            if (hasAttributeAssignment && line.Contains("x:TypeArguments", StringComparison.Ordinal))
-            {
-                foreach (Match typeArgumentsMatch in Regex.EnumerateMatches(XamlTypeArgumentsRegex, line))
-                {
-                    foreach (var value in NormalizeXamlTypeArgumentsValue(typeArgumentsMatch.Groups["value"].Value))
-                    {
-                        if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                        {
-                            FileId = fileId,
-                            Kind = "class",
-                            Name = value,
-                            Line = i + 1,
-                            StartLine = i + 1,
-                            EndLine = i + 1,
-                            Signature = Signature(),
-                        }))
-                            continue;
-
-                        return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
-                    }
-                }
-            }
-
-            if (hasAttributeAssignment && line.Contains("TargetType", StringComparison.Ordinal))
-            {
-                foreach (Match targetTypeMatch in Regex.EnumerateMatches(XamlTargetTypeRegex, line))
-                {
-                    var value = NormalizeXamlKeyValue(targetTypeMatch.Groups["value"].Value);
-                    if (value.Length == 0)
-                        continue;
-                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "class",
-                        Name = value,
-                        Line = i + 1,
-                        StartLine = i + 1,
-                        EndLine = i + 1,
-                        Signature = Signature(),
-                    }))
-                        continue;
-
-                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
-                }
-            }
-
-            if (hasAttributeAssignment && line.Contains("x:Name", StringComparison.Ordinal))
-            {
-                foreach (Match nameMatch in Regex.EnumerateMatches(XamlNameRegex, line))
-                {
-                    var value = nameMatch.Groups["value"].ValueSpan.Trim().ToString();
-                    if (value.Length == 0)
-                        continue;
-                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "property",
-                        Name = value,
-                        Line = i + 1,
-                        StartLine = i + 1,
-                        EndLine = i + 1,
-                        Signature = Signature(),
-                    }))
-                        continue;
-
-                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
-                }
-            }
-
-            if (hasAttributeAssignment && line.Contains("x:Key", StringComparison.Ordinal))
-            {
-                foreach (Match keyMatch in Regex.EnumerateMatches(XamlKeyRegex, line))
-                {
-                    var value = NormalizeXamlKeyValue(keyMatch.Groups["value"].Value);
-                    if (value.Length == 0)
-                        continue;
-                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "property",
-                        Name = value,
-                        Line = i + 1,
-                        StartLine = i + 1,
-                        EndLine = i + 1,
-                        Signature = Signature(),
-                    }))
-                        continue;
-
-                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
-                }
-            }
-
-            if (MayContainXamlEventHandlerAttribute(line))
-            {
-                foreach (Match handlerMatch in Regex.EnumerateMatches(XamlEventHandlerRegex, line))
-                {
-                    var value = handlerMatch.Groups["value"].ValueSpan.Trim().ToString();
-                    if (value.Length == 0)
-                        continue;
-                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "function",
-                        Name = value,
-                        Line = i + 1,
-                        StartLine = i + 1,
-                        EndLine = i + 1,
-                        Signature = Signature(),
-                    }))
-                        continue;
-
-                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
-                }
-            }
-        }
-
-        if (symbols.Count < StructuredDataMaxSymbols
-            && rawText.Contains("x:TypeArguments", StringComparison.Ordinal))
-        {
-            AddWrappedXamlTypeArgumentSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && MayContainWrappedXamlTypeBearingAttribute(rawText))
-        {
-            AddWrappedXamlTypeBearingAttributeSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && MayContainWrappedXamlSearchAttribute(rawText))
-        {
-            AddWrappedXamlSearchAttributeSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && rawText.Contains("x:Type", StringComparison.Ordinal)
-            && rawText.Contains("TypeName", StringComparison.Ordinal))
-        {
-            AddXamlTypeObjectElementSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && rawText.Contains(".TypeName", StringComparison.Ordinal))
-        {
-            AddXamlTypePropertyElementSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && rawText.Contains("{x:Type", StringComparison.Ordinal))
-        {
-            AddXamlTypeMarkupSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && rawText.Contains("{x:Static", StringComparison.Ordinal))
-        {
-            AddXamlStaticMemberTypeSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && MayContainXamlReferenceSymbol(rawText))
-        {
-            AddXamlReferenceSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && TextContainsAny(rawText, XamlResourceReferenceMarkupPrefixes))
-        {
-            AddXamlResourceReferenceSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && MayContainXamlBindingElementNameSymbol(rawText))
-        {
-            AddXamlBindingElementNameSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-        if (symbols.Count < StructuredDataMaxSymbols
-            && MayContainXamlBindingObjectElementSymbol(rawText))
-        {
-            AddXamlBindingObjectElementSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
-        }
-
-        if (symbols.Count <= StructuredDataMaxSymbols
-            && MayContainXamlBindingMarkup(rawText))
-        {
-            foreach (Match bindingMatch in Regex.EnumerateMatches(XamlBindingRegex, rawText))
-            {
-                var value = NormalizeXamlBindingValue(bindingMatch.Groups["kind"].Value, bindingMatch.Groups["content"].Value);
-                if (value.Length == 0)
-                    continue;
-
-                var currentLineStarts = lineStarts ??= BuildLineStarts(lines);
-                var startLine = FindHtmlLineNumber(currentLineStarts, bindingMatch.Index);
-                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-                if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                {
-                    FileId = fileId,
-                    Kind = "property",
-                    Name = value,
-                    Line = startLine,
-                    StartLine = startLine,
-                    EndLine = startLine,
-                    Signature = lines[signatureIndex].Trim(),
-                }))
-                    continue;
-
-                return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
-            }
-        }
-
-        return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
-    }
-
-    private static bool MayContainXamlSymbolMarkers(string[] lines)
-    {
-        for (var i = 0; i < lines.Length; i++)
-        {
-            var line = lines[i];
-            if (line.IndexOf('=') >= 0
-                || line.Contains("x:", StringComparison.Ordinal)
-                || line.IndexOf('{') >= 0
-                || line.Contains(".TypeName", StringComparison.Ordinal)
-                || line.Contains("Binding", StringComparison.Ordinal)
-                || line.Contains("Resource", StringComparison.Ordinal))
-            {
-                return true;
-            }
-        }
-
-        return false;
-    }
-
-    private static bool MayContainXamlEventHandlerAttribute(string line)
-    {
-        if (line.IndexOf('=') < 0)
-            return false;
-
-        foreach (var eventName in XamlEventAttributeNames)
-        {
-            if (line.Contains(eventName, StringComparison.Ordinal))
-                return true;
-        }
-
-        return false;
-    }
-
-    private static bool MayContainXamlBindingMarkup(string rawText)
-        => rawText.Contains("{Binding", StringComparison.Ordinal)
-        || rawText.Contains("{x:Bind", StringComparison.Ordinal)
-        || rawText.Contains("{TemplateBinding", StringComparison.Ordinal)
-        || rawText.Contains("{CompiledBinding", StringComparison.Ordinal)
-        || rawText.Contains("{ReflectionBinding", StringComparison.Ordinal);
-
-    private static bool MayContainXamlReferenceSymbol(string rawText)
-        => TextContainsAny(rawText, XamlReferenceMarkupPrefixes)
-        || TextContainsAny(rawText, XamlReferenceObjectElementPrefixes)
-        || (rawText.Contains("x:Reference", StringComparison.Ordinal)
-            && rawText.Contains(".Name", StringComparison.Ordinal));
-
-    private static bool MayContainXamlBindingElementNameSymbol(string rawText)
-        => rawText.Contains("ElementName", StringComparison.Ordinal)
-        && (MayContainXamlBindingMarkup(rawText)
-            || rawText.Contains("<Binding", StringComparison.Ordinal)
-            || rawText.Contains("Binding.ElementName", StringComparison.Ordinal));
-
-    private static bool MayContainXamlBindingObjectElementSymbol(string rawText)
-        => (rawText.Contains("<Binding", StringComparison.Ordinal)
-            && rawText.Contains("Path", StringComparison.Ordinal))
-        || rawText.Contains("Binding.Path", StringComparison.Ordinal);
-
-    private static bool TextContainsAny(string text, IReadOnlyList<string> values)
-    {
-        for (var i = 0; i < values.Count; i++)
-        {
-            if (text.Contains(values[i], StringComparison.Ordinal))
-                return true;
-        }
-
-        return false;
-    }
-
-    private static bool MayContainWrappedXamlTypeBearingAttribute(string rawText) =>
-        rawText.Contains("x:Class", StringComparison.Ordinal)
-        || rawText.Contains("x:DataType", StringComparison.Ordinal)
-        || rawText.Contains("TargetType", StringComparison.Ordinal);
-
-    private static bool MayContainWrappedXamlSearchAttribute(string rawText)
-    {
-        if (rawText.Contains("x:Name", StringComparison.Ordinal)
-            || rawText.Contains("x:Key", StringComparison.Ordinal))
-        {
-            return true;
-        }
-
-        foreach (var attributeName in XamlEventAttributeNames)
-        {
-            if (rawText.Contains(attributeName, StringComparison.Ordinal))
-                return true;
-        }
-
-        return false;
-    }
-
-    private static void AddWrappedXamlTypeArgumentSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        var cursor = 0;
-        while (cursor < rawText.Length)
-        {
-            var attributeIndex = rawText.IndexOf("x:TypeArguments", cursor, StringComparison.Ordinal);
-            if (attributeIndex < 0)
-                break;
-
-            var equalsIndex = rawText.IndexOf('=', attributeIndex);
-            if (equalsIndex < 0)
-            {
-                cursor = attributeIndex + 1;
-                continue;
-            }
-
-            var quoteIndex = equalsIndex + 1;
-            while (quoteIndex < rawText.Length && char.IsWhiteSpace(rawText[quoteIndex]))
-                quoteIndex++;
-
-            if (quoteIndex >= rawText.Length)
-                break;
-
-            var quote = rawText[quoteIndex];
-            if (quote is not ('"' or '\''))
-            {
-                cursor = quoteIndex + 1;
-                continue;
-            }
-
-            var valueStart = quoteIndex + 1;
-            var valueEnd = valueStart;
-            while (valueEnd < rawText.Length && rawText[valueEnd] != quote)
-                valueEnd++;
-
-            if (valueEnd >= rawText.Length)
-            {
-                cursor = valueStart;
-                continue;
-            }
-
-            if (FindHtmlLineNumber(lineStarts, valueEnd) == FindHtmlLineNumber(lineStarts, attributeIndex))
-            {
-                cursor = valueEnd + 1;
-                continue;
-            }
-
-            var value = rawText[valueStart..valueEnd];
-            if (value.Length > 0)
-            {
-                var startLine = FindHtmlLineNumber(lineStarts, attributeIndex);
-                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-                foreach (var normalized in NormalizeXamlTypeArgumentsValue(value))
-                {
-                    if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "class",
-                        Name = normalized,
-                        Line = startLine,
-                        StartLine = startLine,
-                        EndLine = startLine,
-                        Signature = lines[signatureIndex].Trim(),
-                    }))
-                        return;
-                }
-            }
-
-            cursor = valueEnd + 1;
-        }
-    }
-
-    private static void AddWrappedXamlTypeBearingAttributeSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        // Handle XAML values that are split away from `=` onto later lines.
-        // `x:Class`, `x:DataType`, and `TargetType` are intentionally kept on the
-        // same normalization path as the line-based extractor so search results stay consistent.
-        foreach (var attributeName in WrappedXamlTypeBearingAttributeNames)
-        {
-            var cursor = 0;
-            while (cursor < rawText.Length)
-            {
-                var attributeIndex = rawText.IndexOf(attributeName, cursor, StringComparison.Ordinal);
-                if (attributeIndex < 0)
-                    break;
-
-                var equalsIndex = rawText.IndexOf('=', attributeIndex);
-                if (equalsIndex < 0)
-                {
-                    cursor = attributeIndex + 1;
-                    continue;
-                }
-
-                var quoteIndex = equalsIndex + 1;
-                while (quoteIndex < rawText.Length && char.IsWhiteSpace(rawText[quoteIndex]))
-                    quoteIndex++;
-
-                if (quoteIndex >= rawText.Length)
-                    break;
-
-                var quote = rawText[quoteIndex];
-                if (quote is not ('"' or '\''))
-                {
-                    cursor = quoteIndex + 1;
-                    continue;
-                }
-
-                var valueStart = quoteIndex + 1;
-                var valueEnd = valueStart;
-                while (valueEnd < rawText.Length && rawText[valueEnd] != quote)
-                    valueEnd++;
-
-                if (valueEnd >= rawText.Length)
-                {
-                    cursor = valueStart;
-                    continue;
-                }
-
-                if (FindHtmlLineNumber(lineStarts, valueEnd) == FindHtmlLineNumber(lineStarts, attributeIndex))
-                {
-                    cursor = valueEnd + 1;
-                    continue;
-                }
-
-                var value = NormalizeXamlKeyValue(rawText[valueStart..valueEnd]);
-                if (value.Length > 0)
-                {
-                    var startLine = FindHtmlLineNumber(lineStarts, attributeIndex);
-                    var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-                    if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "class",
-                        Name = value,
-                        Line = startLine,
-                        StartLine = startLine,
-                        EndLine = startLine,
-                        Signature = lines[signatureIndex].Trim(),
-                    }))
-                        return;
-                }
-
-                cursor = valueEnd + 1;
-            }
-        }
-    }
-
-    private static void AddWrappedXamlSearchAttributeSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        if (rawText.Contains("x:Name", StringComparison.Ordinal))
-        {
-            foreach (var occurrence in EnumerateWrappedXamlAttributeValues(rawText, lineStarts, "x:Name"))
-            {
-                if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, occurrence.AttributeIndex, "property", occurrence.Value))
-                    return;
-            }
-        }
-
-        if (rawText.Contains("x:Key", StringComparison.Ordinal))
-        {
-            foreach (var occurrence in EnumerateWrappedXamlAttributeValues(rawText, lineStarts, "x:Key"))
-            {
-                if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, occurrence.AttributeIndex, "property", NormalizeXamlKeyValue(occurrence.Value)))
-                    return;
-            }
-        }
-
-        foreach (var attributeName in XamlEventAttributeNames)
-        {
-            if (!rawText.Contains(attributeName, StringComparison.Ordinal))
-                continue;
-
-            foreach (var occurrence in EnumerateWrappedXamlAttributeValues(rawText, lineStarts, attributeName))
-            {
-                if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, occurrence.AttributeIndex, "function", occurrence.Value))
-                    return;
-            }
-        }
-    }
-
-    private static IEnumerable<(int AttributeIndex, string Value)> EnumerateWrappedXamlAttributeValues(
-        string rawText,
-        int[] lineStarts,
-        string attributeName)
-    {
-        var cursor = 0;
-        while (cursor < rawText.Length)
-        {
-            var attributeIndex = rawText.IndexOf(attributeName, cursor, StringComparison.Ordinal);
-            if (attributeIndex < 0)
-                yield break;
-
-            if (!TryReadXamlAttributeValue(rawText, attributeName, attributeIndex, out var valueStart, out var valueEnd))
-            {
-                cursor = attributeIndex + 1;
-                continue;
-            }
-
-            if (FindHtmlLineNumber(lineStarts, valueEnd) != FindHtmlLineNumber(lineStarts, attributeIndex))
-                yield return (attributeIndex, rawText[valueStart..valueEnd]);
-
-            cursor = valueEnd + 1;
-        }
-    }
-
-    private static bool TryReadXamlAttributeValue(
-        string rawText,
-        string attributeName,
-        int attributeIndex,
-        out int valueStart,
-        out int valueEnd)
-    {
-        valueStart = -1;
-        valueEnd = -1;
-
-        if (!IsXamlAttributeNameMatch(rawText, attributeIndex, attributeName.Length))
-            return false;
-
-        var cursor = attributeIndex + attributeName.Length;
-        while (cursor < rawText.Length && char.IsWhiteSpace(rawText[cursor]))
-            cursor++;
-
-        if (cursor >= rawText.Length || rawText[cursor] != '=')
-            return false;
-
-        cursor++;
-        while (cursor < rawText.Length && char.IsWhiteSpace(rawText[cursor]))
-            cursor++;
-
-        if (cursor >= rawText.Length)
-            return false;
-
-        var quote = rawText[cursor];
-        if (quote is not ('"' or '\''))
-            return false;
-
-        valueStart = cursor + 1;
-        valueEnd = valueStart;
-        while (valueEnd < rawText.Length && rawText[valueEnd] != quote)
-            valueEnd++;
-
-        return valueEnd < rawText.Length;
-    }
-
-    private static bool IsXamlAttributeNameMatch(string rawText, int index, int length)
-    {
-        if (index > 0 && IsXamlAttributeNameChar(rawText[index - 1]))
-            return false;
-
-        var after = index + length;
-        return after >= rawText.Length || !IsXamlAttributeNameChar(rawText[after]);
-    }
-
-    private static bool IsXamlAttributeNameChar(char c)
-        => IsXamlMarkupNameChar(c) || c == '-';
-
-    private static bool AddXamlAttributeSymbol(
-        long fileId,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols,
-        int attributeIndex,
-        string kind,
-        string value)
-    {
-        value = value.Trim();
-        if (value.Length == 0)
-            return symbols.Count <= StructuredDataMaxSymbols;
-
-        var startLine = FindHtmlLineNumber(lineStarts, attributeIndex);
-        var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-        return TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-        {
-            FileId = fileId,
-            Kind = kind,
-            Name = value,
-            Line = startLine,
-            StartLine = startLine,
-            EndLine = startLine,
-            Signature = lines[signatureIndex].Trim(),
-        });
-    }
-
-    private static void AddXamlBindingElementNameSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        if (MayContainXamlBindingMarkup(rawText)
-            && rawText.Contains("ElementName", StringComparison.Ordinal))
-        {
-            foreach (Match bindingMatch in Regex.EnumerateMatches(XamlBindingRegex, rawText))
-            {
-                if (!bindingMatch.Groups["kind"].Value.Equals("Binding", StringComparison.OrdinalIgnoreCase))
-                    continue;
-
-                var value = NormalizeXamlBindingElementNameValue(bindingMatch.Groups["content"].Value);
-                if (value.Length == 0)
-                    continue;
-
-                if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, bindingMatch.Index, "property", value))
-                    return;
-            }
-        }
-
-        if (rawText.Contains("<Binding", StringComparison.Ordinal)
-            && rawText.Contains("ElementName", StringComparison.Ordinal))
-        {
-            var cursor = 0;
-            while (cursor < rawText.Length)
-            {
-                var tagIndex = rawText.IndexOf("<Binding", cursor, StringComparison.Ordinal);
-                if (tagIndex < 0)
-                    break;
-
-                var nameEnd = tagIndex + "<Binding".Length;
-                if (nameEnd < rawText.Length && IsXamlAttributeNameChar(rawText[nameEnd]))
-                {
-                    cursor = nameEnd;
-                    continue;
-                }
-
-                var tagEnd = FindXamlTagEnd(rawText, nameEnd);
-                if (tagEnd < 0)
-                    break;
-
-                var elementNameAttributeIndex = IndexOfXamlAttributeInRange(rawText, "ElementName", nameEnd, tagEnd);
-                if (elementNameAttributeIndex >= 0
-                    && TryReadXamlAttributeValue(rawText, "ElementName", elementNameAttributeIndex, out var valueStart, out var valueEnd)
-                    && valueEnd <= tagEnd)
-                {
-                    if (!AddXamlAttributeSymbol(
-                        fileId,
-                        lines,
-                        lineStarts,
-                        symbols,
-                        elementNameAttributeIndex,
-                        "property",
-                        NormalizeXamlElementReferenceValue(rawText[valueStart..valueEnd])))
-                    {
-                        return;
-                    }
-                }
-
-                cursor = tagEnd + 1;
-            }
-        }
-
-        if (!rawText.Contains("Binding.ElementName", StringComparison.Ordinal))
-            return;
-
-        foreach (Match elementNameMatch in Regex.EnumerateMatches(XamlBindingElementNamePropertyElementRegex, rawText))
-        {
-            var value = NormalizeXamlElementReferenceValue(elementNameMatch.Groups["value"].Value);
-            if (value.Length == 0)
-                continue;
-
-            if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, elementNameMatch.Index, "property", value))
-                return;
-        }
-    }
-
-    private static string NormalizeXamlBindingElementNameValue(string content)
-    {
-        content = content.Trim();
-        if (content.Length == 0)
-            return "";
-
-        foreach (var argument in SplitTopLevelMarkupArguments(content))
-        {
-            var equalsIndex = IndexOfTopLevelEquals(argument);
-            if (equalsIndex < 0)
-                continue;
-
-            var argumentName = argument.AsSpan(0, equalsIndex).Trim();
-            if (!argumentName.Equals("ElementName", StringComparison.OrdinalIgnoreCase))
-                continue;
-
-            var value = NormalizeXamlElementReferenceValue(argument[(equalsIndex + 1)..]);
-            if (value.Length > 0)
-                return value;
-        }
-
-        return "";
-    }
-
-    private static string NormalizeXamlElementReferenceValue(string value)
-    {
-        return NormalizeXamlMarkupValue(value);
-    }
-
-    private static void AddXamlBindingObjectElementSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        if (rawText.Contains("<Binding", StringComparison.Ordinal)
-            && rawText.Contains("Path", StringComparison.Ordinal))
-        {
-            var cursor = 0;
-            while (cursor < rawText.Length)
-            {
-                var tagIndex = rawText.IndexOf("<Binding", cursor, StringComparison.Ordinal);
-                if (tagIndex < 0)
-                    break;
-
-                var nameEnd = tagIndex + "<Binding".Length;
-                if (nameEnd < rawText.Length && IsXamlAttributeNameChar(rawText[nameEnd]))
-                {
-                    cursor = nameEnd;
-                    continue;
-                }
-
-                var tagEnd = FindXamlTagEnd(rawText, nameEnd);
-                if (tagEnd < 0)
-                    break;
-
-                var pathAttributeIndex = IndexOfXamlAttributeInRange(rawText, "Path", nameEnd, tagEnd);
-                if (pathAttributeIndex >= 0
-                    && TryReadXamlAttributeValue(rawText, "Path", pathAttributeIndex, out var valueStart, out var valueEnd)
-                    && valueEnd <= tagEnd)
-                {
-                    if (!AddXamlAttributeSymbol(
-                        fileId,
-                        lines,
-                        lineStarts,
-                        symbols,
-                        pathAttributeIndex,
-                        "property",
-                        NormalizeXamlBindingPathValue(rawText[valueStart..valueEnd])))
-                    {
-                        return;
-                    }
-                }
-
-                cursor = tagEnd + 1;
-            }
-        }
-
-        if (!rawText.Contains("Binding.Path", StringComparison.Ordinal))
-            return;
-
-        foreach (Match pathMatch in Regex.EnumerateMatches(XamlBindingPathPropertyElementRegex, rawText))
-        {
-            var value = NormalizeXamlBindingPathValue(pathMatch.Groups["value"].Value);
-            if (value.Length == 0)
-                continue;
-
-            var startLine = FindHtmlLineNumber(lineStarts, pathMatch.Index);
-            var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-            if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-            {
-                FileId = fileId,
-                Kind = "property",
-                Name = value,
-                Line = startLine,
-                StartLine = startLine,
-                EndLine = startLine,
-                Signature = lines[signatureIndex].Trim(),
-            }))
-                return;
-        }
-    }
-
-    private static int FindXamlTagEnd(string rawText, int startIndex)
-    {
-        char? quote = null;
-        for (var i = startIndex; i < rawText.Length; i++)
-        {
-            var ch = rawText[i];
-            if (quote is { } activeQuote)
-            {
-                if (ch == activeQuote)
-                    quote = null;
-                continue;
-            }
-
-            if (ch is '"' or '\'')
-            {
-                quote = ch;
-                continue;
-            }
-
-            if (ch == '>')
-                return i;
-        }
-
-        return -1;
-    }
-
-    private static int IndexOfXamlAttributeInRange(string rawText, string attributeName, int startIndex, int endIndex)
-    {
-        char? quote = null;
-        for (var i = startIndex; i < endIndex; i++)
-        {
-            var ch = rawText[i];
-            if (quote is { } activeQuote)
-            {
-                if (ch == activeQuote)
-                    quote = null;
-                continue;
-            }
-
-            if (ch is '"' or '\'')
-            {
-                quote = ch;
-                continue;
-            }
-
-            if (!rawText.AsSpan(i, endIndex - i).StartsWith(attributeName, StringComparison.Ordinal))
-                continue;
-
-            if (IsXamlAttributeNameMatch(rawText, i, attributeName.Length)
-                && TryReadXamlAttributeValue(rawText, attributeName, i, out _, out var valueEnd)
-                && valueEnd <= endIndex)
-            {
-                return i;
-            }
-        }
-
-        return -1;
-    }
-
-    private static void AddXamlTypeObjectElementSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        if (!rawText.Contains("x:Type", StringComparison.Ordinal)
-            || !rawText.Contains("TypeName", StringComparison.Ordinal))
-        {
-            return;
-        }
-
-        foreach (Match typeMatch in Regex.EnumerateMatches(XamlTypeObjectElementRegex, rawText))
-        {
-            var value = NormalizeXamlKeyValue(typeMatch.Groups["value"].Value);
-            if (value.Length == 0)
-                continue;
-
-            var startLine = FindHtmlLineNumber(lineStarts, typeMatch.Index);
-            var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-            if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-            {
-                FileId = fileId,
-                Kind = "class",
-                Name = value,
-                Line = startLine,
-                StartLine = startLine,
-                EndLine = startLine,
-                Signature = lines[signatureIndex].Trim(),
-            }))
-                return;
-        }
-    }
-
-    private static void AddXamlTypePropertyElementSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        if (!rawText.Contains(".TypeName", StringComparison.Ordinal))
-            return;
-
-        foreach (Match typeMatch in Regex.EnumerateMatches(XamlTypePropertyElementRegex, rawText))
-        {
-            var value = NormalizeXamlKeyValue(typeMatch.Groups["value"].Value);
-            if (value.Length == 0)
-                continue;
-
-            var startLine = FindHtmlLineNumber(lineStarts, typeMatch.Index);
-            var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-            if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-            {
-                FileId = fileId,
-                Kind = "class",
-                Name = value,
-                Line = startLine,
-                StartLine = startLine,
-                EndLine = startLine,
-                Signature = lines[signatureIndex].Trim(),
-            }))
-                return;
-        }
-    }
-
-    private static void AddXamlTypeMarkupSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        if (rawText.Contains("{x:TypeExtension", StringComparison.Ordinal))
-            AddXamlMarkupExtensionTypeSymbols(fileId, rawText, lines, lineStarts, symbols, "{x:TypeExtension", false);
-        if (symbols.Count > StructuredDataMaxSymbols)
-            return;
-        if (rawText.Contains("{x:Type", StringComparison.Ordinal))
-            AddXamlMarkupExtensionTypeSymbols(fileId, rawText, lines, lineStarts, symbols, "{x:Type", true);
-    }
-
-    private static void AddXamlMarkupExtensionTypeSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols,
-        string prefix,
-        bool rejectNameCharAfterPrefix)
-    {
-        var cursor = 0;
-        while (cursor < rawText.Length)
-        {
-            var braceIndex = rawText.IndexOf(prefix, cursor, StringComparison.Ordinal);
-            if (braceIndex < 0)
-                break;
-
-            var afterPrefix = braceIndex + prefix.Length;
-            if (rejectNameCharAfterPrefix
-                && afterPrefix < rawText.Length
-                && IsXamlMarkupNameChar(rawText[afterPrefix]))
-            {
-                cursor = afterPrefix;
-                continue;
-            }
-
-            var closingBraceIndex = FindMatchingBrace(rawText, braceIndex);
-            if (closingBraceIndex < 0)
-            {
-                cursor = braceIndex + 1;
-                continue;
-            }
-
-            if (ShouldSkipXamlMarkupExtensionSymbol(rawText, braceIndex))
-            {
-                cursor = closingBraceIndex + 1;
-                continue;
-            }
-
-            var value = NormalizeXamlMarkupValue(rawText[braceIndex..(closingBraceIndex + 1)]);
-            if (value.Length > 0)
-            {
-                var startLine = FindHtmlLineNumber(lineStarts, braceIndex);
-                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-                if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                {
-                    FileId = fileId,
-                    Kind = "class",
-                    Name = value,
-                    Line = startLine,
-                    StartLine = startLine,
-                    EndLine = startLine,
-                    Signature = lines[signatureIndex].Trim(),
-                }))
-                    return;
-            }
-
-            cursor = closingBraceIndex + 1;
-        }
-    }
-
-    private static bool ShouldSkipXamlMarkupExtensionSymbol(string rawText, int braceIndex)
-    {
-        var tagStart = rawText.LastIndexOf('<', braceIndex);
-        if (tagStart < 0 || tagStart > braceIndex)
-            return false;
-
-        var tagEnd = rawText.IndexOf('>', tagStart);
-        if (tagEnd >= 0 && tagEnd < braceIndex)
-            return false;
-
-        var tagSlice = rawText[tagStart..braceIndex];
-        if (tagSlice.IndexOf("<x:Type", StringComparison.OrdinalIgnoreCase) >= 0
-            || tagSlice.IndexOf("<x:TypeExtension", StringComparison.OrdinalIgnoreCase) >= 0)
-        {
-            return true;
-        }
-
-        if (tagSlice.IndexOf("TargetType=", StringComparison.OrdinalIgnoreCase) >= 0)
-            return true;
-
-        return false;
-    }
-
-    private static void AddXamlStaticMemberTypeSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        if (!rawText.Contains("{x:Static", StringComparison.Ordinal))
-            return;
-
-        var cursor = 0;
-        while (cursor < rawText.Length)
-        {
-            var braceIndex = rawText.IndexOf("{x:Static", cursor, StringComparison.Ordinal);
-            if (braceIndex < 0)
-                break;
-
-            var closingBraceIndex = FindMatchingBrace(rawText, braceIndex);
-            if (closingBraceIndex < 0)
-            {
-                cursor = braceIndex + 1;
-                continue;
-            }
-
-            var value = NormalizeXamlMarkupValue(rawText[braceIndex..(closingBraceIndex + 1)]);
-            var lastDot = value.LastIndexOf('.');
-            if (lastDot > 0)
-            {
-                var typeName = value[..lastDot].Trim();
-                if (typeName.Length > 0)
-                {
-                    var startLine = FindHtmlLineNumber(lineStarts, braceIndex);
-                    var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-                    if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                    {
-                        FileId = fileId,
-                        Kind = "class",
-                        Name = typeName,
-                        Line = startLine,
-                        StartLine = startLine,
-                        EndLine = startLine,
-                        Signature = lines[signatureIndex].Trim(),
-                    }))
-                        return;
-                }
-            }
-
-            cursor = closingBraceIndex + 1;
-        }
-    }
-
-    private static void AddXamlReferenceSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        foreach (var prefix in XamlReferenceMarkupPrefixes)
-        {
-            if (rawText.Contains(prefix, StringComparison.Ordinal))
-                AddXamlReferenceMarkupSymbols(fileId, rawText, lines, lineStarts, symbols, prefix);
-            if (symbols.Count > StructuredDataMaxSymbols)
-                return;
-        }
-
-        foreach (var prefix in XamlReferenceObjectElementPrefixes)
-        {
-            if (rawText.Contains(prefix, StringComparison.Ordinal))
-                AddXamlReferenceObjectElementSymbols(fileId, rawText, lines, lineStarts, symbols, prefix);
-            if (symbols.Count > StructuredDataMaxSymbols)
-                return;
-        }
-
-        if (!rawText.Contains("x:Reference", StringComparison.Ordinal)
-            || !rawText.Contains(".Name", StringComparison.Ordinal))
-        {
-            return;
-        }
-
-        foreach (Match nameMatch in Regex.EnumerateMatches(XamlReferenceNamePropertyElementRegex, rawText))
-        {
-            var value = NormalizeXamlElementReferenceValue(nameMatch.Groups["value"].Value);
-            if (value.Length == 0)
-                continue;
-
-            if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, nameMatch.Index, "property", value))
-                return;
-        }
-    }
-
-    private static void AddXamlReferenceMarkupSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols,
-        string prefix)
-    {
-        var cursor = 0;
-        while (cursor < rawText.Length)
-        {
-            var braceIndex = rawText.IndexOf(prefix, cursor, StringComparison.Ordinal);
-            if (braceIndex < 0)
-                break;
-
-            var afterPrefix = braceIndex + prefix.Length;
-            if (afterPrefix < rawText.Length && IsXamlMarkupNameChar(rawText[afterPrefix]))
-            {
-                cursor = afterPrefix;
-                continue;
-            }
-
-            var closingBraceIndex = FindMatchingBrace(rawText, braceIndex);
-            if (closingBraceIndex < 0)
-            {
-                cursor = braceIndex + 1;
-                continue;
-            }
-
-            var value = NormalizeXamlRequiredMarkupArgumentValue(rawText[braceIndex..(closingBraceIndex + 1)]);
-            if (value.Length > 0
-                && !AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, braceIndex, "property", value))
-            {
-                return;
-            }
-
-            cursor = closingBraceIndex + 1;
-        }
-    }
-
-    private static void AddXamlReferenceObjectElementSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols,
-        string prefix)
-    {
-        var cursor = 0;
-        while (cursor < rawText.Length)
-        {
-            var tagIndex = rawText.IndexOf(prefix, cursor, StringComparison.Ordinal);
-            if (tagIndex < 0)
-                break;
-
-            var nameEnd = tagIndex + prefix.Length;
-            if (nameEnd < rawText.Length && IsXamlAttributeNameChar(rawText[nameEnd]))
-            {
-                cursor = nameEnd;
-                continue;
-            }
-
-            var tagEnd = FindXamlTagEnd(rawText, nameEnd);
-            if (tagEnd < 0)
-                break;
-
-            var nameAttributeIndex = IndexOfXamlAttributeInRange(rawText, "Name", nameEnd, tagEnd);
-            if (nameAttributeIndex >= 0
-                && TryReadXamlAttributeValue(rawText, "Name", nameAttributeIndex, out var valueStart, out var valueEnd)
-                && valueEnd <= tagEnd)
-            {
-                if (!AddXamlAttributeSymbol(
-                    fileId,
-                    lines,
-                    lineStarts,
-                    symbols,
-                    nameAttributeIndex,
-                    "property",
-                    NormalizeXamlElementReferenceValue(rawText[valueStart..valueEnd])))
-                {
-                    return;
-                }
-            }
-
-            cursor = tagEnd + 1;
-        }
-    }
-
-    private static void AddXamlResourceReferenceSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols)
-    {
-        foreach (var prefix in XamlResourceReferenceMarkupPrefixes)
-        {
-            if (rawText.Contains(prefix, StringComparison.Ordinal))
-                AddXamlResourceReferenceSymbols(fileId, rawText, lines, lineStarts, symbols, prefix);
-            if (symbols.Count > StructuredDataMaxSymbols)
-                return;
-        }
-    }
-
-    private static void AddXamlResourceReferenceSymbols(
-        long fileId,
-        string rawText,
-        string[] lines,
-        int[] lineStarts,
-        List<SymbolRecord> symbols,
-        string prefix)
-    {
-        var cursor = 0;
-        while (cursor < rawText.Length)
-        {
-            var braceIndex = rawText.IndexOf(prefix, cursor, StringComparison.Ordinal);
-            if (braceIndex < 0)
-                break;
-
-            var afterPrefix = braceIndex + prefix.Length;
-            if (afterPrefix < rawText.Length && IsXamlMarkupNameChar(rawText[afterPrefix]))
-            {
-                cursor = afterPrefix;
-                continue;
-            }
-
-            var closingBraceIndex = FindMatchingBrace(rawText, braceIndex);
-            if (closingBraceIndex < 0)
-            {
-                cursor = braceIndex + 1;
-                continue;
-            }
-
-            var value = NormalizeXamlResourceReferenceValue(rawText[braceIndex..(closingBraceIndex + 1)]);
-            if (value.Length > 0)
-            {
-                var startLine = FindHtmlLineNumber(lineStarts, braceIndex);
-                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
-                if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
-                {
-                    FileId = fileId,
-                    Kind = "property",
-                    Name = value,
-                    Line = startLine,
-                    StartLine = startLine,
-                    EndLine = startLine,
-                    Signature = lines[signatureIndex].Trim(),
-                }))
-                    return;
-            }
-
-            cursor = closingBraceIndex + 1;
-        }
-    }
-
-    private static string NormalizeXamlResourceReferenceValue(string value)
-        => NormalizeXamlRequiredMarkupArgumentValue(value);
-
-    private static string NormalizeXamlRequiredMarkupArgumentValue(string value)
-    {
-        value = value.Trim();
-        if (value.Length == 0 || value[0] != '{')
-            return value;
-
-        var closingBraceIndex = FindMatchingBrace(value, 0);
-        if (closingBraceIndex < 0)
-            return "";
-
-        var content = value.AsSpan(1, closingBraceIndex - 1).Trim().ToString();
-        var payloadStart = FindTopLevelMarkupPayloadStart(content);
-        if (payloadStart < 0)
-            return "";
-
-        var payloadStartIndex = SkipXamlMarkupWhitespace(content, payloadStart + 1);
-        if (payloadStartIndex >= content.Length)
-            return "";
-
-        var payload = content[payloadStartIndex..];
-        foreach (var argument in SplitTopLevelMarkupArguments(payload))
-        {
-            var normalized = NormalizeXamlMarkupArgument(argument);
-            if (normalized.Length > 0)
-                return normalized;
-        }
-
-        return "";
-    }
-
-    private static bool IsXamlMarkupNameChar(char c)
-        => char.IsLetterOrDigit(c) || c == '_' || c == ':' || c == '.';
-
-    private static string NormalizeXamlKeyValue(string value)
-    {
-        var trimmed = value.AsSpan().Trim();
-        if (trimmed.Length < 2 || trimmed[0] != '{' || trimmed[^1] != '}')
-            return trimmed.ToString();
-
-        return NormalizeXamlMarkupExtensionContent(trimmed[1..^1].Trim().ToString());
-    }
-
-    private static string NormalizeXamlBindingValue(string kind, string content)
-    {
-        var kindSpan = kind.AsSpan().Trim();
-        var contentSpan = content.AsSpan().Trim();
-        if (contentSpan.IsEmpty)
-            return "";
-
-        var contentText = contentSpan.ToString();
-        var isTemplateBinding = kindSpan.Equals("TemplateBinding", StringComparison.OrdinalIgnoreCase);
-        var payload = kindSpan.Equals("x:Bind", StringComparison.OrdinalIgnoreCase)
-            ? $"x:Bind {contentText}"
-            : isTemplateBinding
-                ? $"TemplateBinding {contentText}"
-                : $"Binding {contentText}";
-
-        var firstPath = NormalizeXamlBindingPath(payload, isTemplateBinding);
-        return firstPath.Length > 0 ? firstPath : contentText;
-    }
-
-    private static string NormalizeXamlBindingPath(string value, bool allowPropertyArgument)
-    {
-        var trimmed = value.AsSpan().Trim();
-        if (trimmed.IsEmpty)
-            return "";
-
-        var payloadStart = FindTopLevelMarkupPayloadStart(trimmed);
-        if (payloadStart < 0)
-            return trimmed.ToString();
-
-        var payloadStartIndex = SkipXamlMarkupWhitespace(trimmed, payloadStart + 1);
-        if (payloadStartIndex >= trimmed.Length)
-            return trimmed.ToString();
-
-        var payload = trimmed[payloadStartIndex..].ToString();
-        string? fallback = null;
-        foreach (var argument in SplitTopLevelMarkupArguments(payload))
-        {
-            var equalsIndex = IndexOfTopLevelEquals(argument);
-            if (equalsIndex >= 0)
-            {
-                var argumentName = argument.AsSpan(0, equalsIndex).Trim();
-                if (argumentName.Equals("Path", StringComparison.OrdinalIgnoreCase)
-                    || (allowPropertyArgument && argumentName.Equals("Property", StringComparison.OrdinalIgnoreCase)))
-                {
-                    var pathValue = NormalizeXamlBindingPathValue(argument[(equalsIndex + 1)..]);
-                    if (pathValue.Length > 0)
-                        return pathValue;
-                }
-
-                continue;
-            }
-
-            var normalized = NormalizeXamlBindingArgument(argument);
-            if (normalized.Length == 0)
-                continue;
-
-            fallback ??= normalized;
-        }
-
-        return fallback ?? trimmed.ToString();
-    }
-
-    private static string NormalizeXamlBindingArgument(string value)
-    {
-        var trimmed = value.AsSpan().Trim();
-        if (trimmed.IsEmpty)
-            return "";
-
-        var equalsIndex = IndexOfTopLevelEquals(trimmed);
-        if (equalsIndex >= 0)
-        {
-            var name = trimmed[..equalsIndex].Trim();
-            var normalized = trimmed[(equalsIndex + 1)..].Trim();
-            if (name.Equals("Path", StringComparison.OrdinalIgnoreCase))
-                return NormalizeXamlBindingPathValue(normalized.ToString());
-            if (!normalized.IsEmpty)
-                return NormalizeXamlMarkupValue(normalized.ToString());
-        }
-
-        return NormalizeXamlBindingPathValue(trimmed.ToString());
-    }
-
-    private static string NormalizeXamlBindingPathValue(string value)
-    {
-        var trimmed = value.AsSpan().Trim();
-        if (trimmed.IsEmpty)
-            return "";
-
-        value = NormalizeXamlMarkupValue(trimmed.ToString());
-        var lastDot = value.LastIndexOf('.');
-        if (lastDot >= 0 && lastDot + 1 < value.Length)
-            return value.AsSpan(lastDot + 1).Trim().ToString();
-
-        return value.AsSpan().Trim().ToString();
-    }
-
-    private static string NormalizeXamlMarkupValue(string value)
-    {
-        var trimmed = value.AsSpan().Trim();
-        if (trimmed.IsEmpty || trimmed[0] != '{')
-            return trimmed.ToString();
-
-        var closingBraceIndex = FindMatchingBrace(trimmed, 0);
-        if (closingBraceIndex < 0)
-            return trimmed.ToString();
-
-        var normalized = NormalizeXamlMarkupExtensionContent(trimmed.Slice(1, closingBraceIndex - 1).Trim().ToString());
-        var suffix = trimmed[(closingBraceIndex + 1)..].Trim();
-        return suffix.IsEmpty ? normalized : string.Concat(normalized, suffix.ToString());
-    }
-
-    private static string NormalizeXamlMarkupExtensionContent(string value)
-    {
-        var trimmed = value.AsSpan().Trim();
-        if (trimmed.IsEmpty)
-            return "";
-
-        var payloadStart = FindTopLevelMarkupPayloadStart(trimmed);
-        if (payloadStart < 0)
-            return trimmed.ToString();
-
-        var payloadStartIndex = SkipXamlMarkupWhitespace(trimmed, payloadStart + 1);
-        if (payloadStartIndex >= trimmed.Length)
-            return trimmed.ToString();
-
-        var payload = trimmed[payloadStartIndex..].ToString();
-        foreach (var argument in SplitTopLevelMarkupArguments(payload))
-        {
-            var normalized = NormalizeXamlMarkupArgument(argument);
-            if (normalized.Length > 0)
-                return normalized;
-        }
-
-        return trimmed.ToString();
-    }
-
-    private static IEnumerable<string> NormalizeXamlTypeArgumentsValue(string value)
-    {
-        var trimmed = value.AsSpan().Trim();
-        if (trimmed.IsEmpty)
-            yield break;
-
-        foreach (var argument in SplitTopLevelTypeArguments(trimmed.ToString()))
-        {
-            var normalized = NormalizeXamlMarkupArgument(argument);
-            if (normalized.Length > 0)
-            {
-                foreach (var expanded in ExpandXamlTypeArgument(normalized))
-                    yield return expanded;
-            }
-        }
-    }
-
-    private static IEnumerable<string> ExpandXamlTypeArgument(string value)
-    {
-        // Peel nested generic constructor shapes recursively so XAML type arguments like
-        // `Outer(Inner(A, B), C)` still surface every referenced type name.
-        value = value.Trim();
-        if (value.Length == 0)
-            yield break;
-
-        var payloadStart = FindTopLevelTypeConstructorStart(value);
-        if (payloadStart < 0)
-        {
-            yield return value;
-            yield break;
-        }
-
-        var payloadEnd = FindMatchingTypeConstructorEnd(value, payloadStart);
-        if (payloadEnd < 0)
-        {
-            yield return value;
-            yield break;
-        }
-
-        var prefix = value.AsSpan(0, payloadStart).Trim();
-        if (!prefix.IsEmpty)
-            yield return prefix.ToString();
-
-        var payload = value.AsSpan(payloadStart + 1, payloadEnd - payloadStart - 1).Trim();
-        if (!payload.IsEmpty)
-        {
-            foreach (var nestedArgument in SplitTopLevelTypeArguments(payload.ToString()))
-            {
-                var nestedNormalized = NormalizeXamlMarkupArgument(nestedArgument);
-                if (nestedNormalized.Length == 0)
-                    continue;
-
-                foreach (var nestedExpanded in ExpandXamlTypeArgument(nestedNormalized))
-                    yield return nestedExpanded;
-            }
-        }
-
-        var suffix = value.AsSpan(payloadEnd + 1).Trim();
-        if (!suffix.IsEmpty)
-        {
-            foreach (var expanded in ExpandXamlTypeArgument(suffix.ToString()))
-                yield return expanded;
-        }
-    }
-
-    private static string NormalizeXamlMarkupArgument(string value)
-    {
-        var trimmed = value.AsSpan().Trim();
-        if (trimmed.IsEmpty)
-            return "";
-
-        var equalsIndex = IndexOfTopLevelEquals(trimmed);
-        if (equalsIndex >= 0)
-            return NormalizeXamlMarkupValue(trimmed[(equalsIndex + 1)..].ToString());
-
-        return NormalizeXamlMarkupValue(trimmed.ToString());
-    }
-
-    private static int FindTopLevelMarkupPayloadStart(string value) => FindTopLevelMarkupPayloadStart(value.AsSpan());
-
-    private static int FindTopLevelMarkupPayloadStart(ReadOnlySpan<char> value)
-    {
-        var braceDepth = 0;
-        for (var i = 0; i < value.Length; i++)
-        {
-            var ch = value[i];
-            if (ch == '{')
-            {
-                braceDepth++;
-                continue;
-            }
-            if (ch == '}')
-            {
-                if (braceDepth > 0)
-                    braceDepth--;
-                continue;
-            }
-            if (braceDepth == 0 && (char.IsWhiteSpace(ch) || ch == ','))
-                return i;
-        }
-
-        return -1;
-    }
-
-    private static int SkipXamlMarkupWhitespace(string value, int start) => SkipXamlMarkupWhitespace(value.AsSpan(), start);
-
-    private static int SkipXamlMarkupWhitespace(ReadOnlySpan<char> value, int start)
-    {
-        start = Math.Clamp(start, 0, value.Length);
-        while (start < value.Length && char.IsWhiteSpace(value[start]))
-            start++;
-
-        return start;
-    }
-
-    private static int FindTopLevelTypeConstructorStart(string value)
-    {
-        var braceDepth = 0;
-        var parenDepth = 0;
-        var angleDepth = 0;
-        for (var i = 0; i < value.Length; i++)
-        {
-            var ch = value[i];
-            if (ch == '{')
-            {
-                braceDepth++;
-                continue;
-            }
-            if (ch == '}')
-            {
-                if (braceDepth > 0)
-                    braceDepth--;
-                continue;
-            }
-            if (ch == '(' || ch == '<')
-            {
-                if (braceDepth == 0 && parenDepth == 0 && angleDepth == 0)
-                    return i;
-
-                if (ch == '(')
-                    parenDepth++;
-                else
-                    angleDepth++;
-                continue;
-            }
-            if (ch == ')')
-            {
-                if (parenDepth > 0)
-                    parenDepth--;
-                continue;
-            }
-            if (ch == '>')
-            {
-                if (angleDepth > 0)
-                    angleDepth--;
-                continue;
-            }
-        }
-
-        return -1;
-    }
-
-    private static int FindMatchingTypeConstructorEnd(string value, int startIndex)
-    {
-        var open = value[startIndex];
-        var close = open == '(' ? ')' : '>';
-        var depth = 0;
-        var braceDepth = 0;
-        for (var i = startIndex; i < value.Length; i++)
-        {
-            var ch = value[i];
-            if (ch == '{')
-            {
-                braceDepth++;
-                continue;
-            }
-            if (ch == '}')
-            {
-                if (braceDepth > 0)
-                    braceDepth--;
-                continue;
-            }
-            if (braceDepth > 0)
-                continue;
-
-            if (ch == open)
-            {
-                depth++;
-                continue;
-            }
-            if (ch == close)
-            {
-                depth--;
-                if (depth == 0)
-                    return i;
-            }
-        }
-
-        return -1;
-    }
-
-    private static int IndexOfTopLevelEquals(string value) => IndexOfTopLevelEquals(value.AsSpan());
-
-    private static int IndexOfTopLevelEquals(ReadOnlySpan<char> value)
-    {
-        var braceDepth = 0;
-        for (var i = 0; i < value.Length; i++)
-        {
-            var ch = value[i];
-            if (ch == '{')
-            {
-                braceDepth++;
-                continue;
-            }
-            if (ch == '}')
-            {
-                if (braceDepth > 0)
-                    braceDepth--;
-                continue;
-            }
-            if (braceDepth == 0 && ch == '=')
-                return i;
-        }
-
-        return -1;
-    }
-
-    private static IEnumerable<string> SplitTopLevelMarkupArguments(string value)
-    {
-        var braceDepth = 0;
-        char? quote = null;
-        var start = 0;
-        for (var i = 0; i < value.Length; i++)
-        {
-            var ch = value[i];
-            if (quote is { } activeQuote)
-            {
-                if (ch == activeQuote)
-                    quote = null;
-                continue;
-            }
-            if (ch is '"' or '\'')
-            {
-                quote = ch;
-                continue;
-            }
-            if (ch == '{')
-            {
-                braceDepth++;
-                continue;
-            }
-            if (ch == '}')
-            {
-                if (braceDepth > 0)
-                    braceDepth--;
-                continue;
-            }
-            if (braceDepth == 0 && ch == ',')
-            {
-                var segment = value.AsSpan(start, i - start).Trim();
-                if (!segment.IsEmpty)
-                    yield return segment.ToString();
-                start = i + 1;
-            }
-        }
-
-        var tail = value.AsSpan(start).Trim();
-        if (!tail.IsEmpty)
-            yield return tail.ToString();
-    }
-
-    private static IEnumerable<string> SplitTopLevelTypeArguments(string value)
-    {
-        var braceDepth = 0;
-        var parenDepth = 0;
-        var angleDepth = 0;
-        var start = 0;
-        for (var i = 0; i < value.Length; i++)
-        {
-            var ch = value[i];
-            if (ch == '{')
-            {
-                braceDepth++;
-                continue;
-            }
-            if (ch == '}')
-            {
-                if (braceDepth > 0)
-                    braceDepth--;
-                continue;
-            }
-            if (ch == '(')
-            {
-                parenDepth++;
-                continue;
-            }
-            if (ch == ')')
-            {
-                if (parenDepth > 0)
-                    parenDepth--;
-                continue;
-            }
-            if (ch == '<')
-            {
-                angleDepth++;
-                continue;
-            }
-            if (ch == '>')
-            {
-                if (angleDepth > 0)
-                    angleDepth--;
-                continue;
-            }
-            if (braceDepth == 0 && parenDepth == 0 && angleDepth == 0 && ch == ',')
-            {
-                var segment = value.AsSpan(start, i - start).Trim();
-                if (!segment.IsEmpty)
-                    yield return segment.ToString();
-                start = i + 1;
-            }
-        }
-
-        var tail = value.AsSpan(start).Trim();
-        if (!tail.IsEmpty)
-            yield return tail.ToString();
-    }
-
-    private static int FindMatchingBrace(string value, int startIndex) => FindMatchingBrace(value.AsSpan(), startIndex);
-
-    private static int FindMatchingBrace(ReadOnlySpan<char> value, int startIndex)
-    {
-        var braceDepth = 0;
-        for (var i = startIndex; i < value.Length; i++)
-        {
-            var ch = value[i];
-            if (ch == '{')
-            {
-                braceDepth++;
-                continue;
-            }
-            if (ch == '}')
-            {
-                braceDepth--;
-                if (braceDepth == 0)
-                    return i;
-            }
-        }
-
-        return -1;
-    }
-
-    private static bool IsHtmlTagNameStart(char c) => (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z');
-
-    private static bool IsHtmlTagNameChar(char c) =>
-        (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-' || c == '_';
-
-    private static bool IsHtmlAttrNameStart(char c) =>
-        (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || c == '_' || c == ':';
-
-    private static bool IsHtmlAttrNameChar(char c) =>
-        IsHtmlAttrNameStart(c) || (c >= '0' && c <= '9') || c == '-' || c == '.';
-
-    private static bool IsHtmlUnquotedValueTerminator(char c) =>
-        char.IsWhiteSpace(c) || c == '"' || c == '\'' || c == '=' || c == '<' || c == '>' || c == '`';
-
-    private static int IndexOfOrEnd(string text, char needle, int start)
-    {
-        var idx = text.IndexOf(needle, start);
-        return idx < 0 ? text.Length : idx;
-    }
-
-    private static int FindHtmlLineNumber(int[] lineStarts, int offset)
-    {
-        if (lineStarts.Length == 0)
-            return 1;
-        var lo = 0;
-        var hi = lineStarts.Length - 1;
-        while (lo < hi)
-        {
-            var mid = (lo + hi + 1) / 2;
-            if (lineStarts[mid] <= offset)
-                lo = mid;
-            else
-                hi = mid - 1;
-        }
-        return lo + 1;
-    }
-
-    private static readonly string[] HtmlRawTextElementNames = ["script", "style", "textarea", "title"];
-
-    // Native HTML/SVG/MathML tag names that happen to contain a hyphen but are
-    // reserved by the spec, so they must NOT be treated as custom-element class
-    // symbols. See https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
-    // for the PotentialCustomElementName / reserved names production.
-    // ハイフンを含むが仕様で予約されている標準 HTML / SVG / MathML タグ名。custom
-    // element の class シンボルとして扱ってはいけない。
-    private static readonly HashSet<string> HtmlReservedHyphenatedTags = new(StringComparer.OrdinalIgnoreCase)
-    {
-        "annotation-xml",
-        "color-profile",
-        "font-face",
-        "font-face-src",
-        "font-face-uri",
-        "font-face-format",
-        "font-face-name",
-        "missing-glyph",
-    };
-
-    private static bool IsHtmlTagName(string tagName, string expected) =>
-        tagName.Equals(expected, StringComparison.OrdinalIgnoreCase);
-
-    private static bool IsHtmlSrcResourceTag(string tagName) =>
-        IsHtmlTagName(tagName, "audio")
-        || IsHtmlTagName(tagName, "embed")
-        || IsHtmlTagName(tagName, "iframe")
-        || IsHtmlTagName(tagName, "img")
-        || IsHtmlTagName(tagName, "input")
-        || IsHtmlTagName(tagName, "script")
-        || IsHtmlTagName(tagName, "source")
-        || IsHtmlTagName(tagName, "track")
-        || IsHtmlTagName(tagName, "video");
-
-    private static bool IsHtmlHrefResourceTag(string tagName) =>
-        IsHtmlTagName(tagName, "a")
-        || IsHtmlTagName(tagName, "area")
-        || IsHtmlTagName(tagName, "image")
-        || IsHtmlTagName(tagName, "link")
-        || IsHtmlTagName(tagName, "use");
-
-    private static bool IsHtmlSrcsetResourceTag(string tagName) =>
-        IsHtmlTagName(tagName, "img") || IsHtmlTagName(tagName, "source");
-
-    private static IEnumerable<string> EnumerateHtmlSrcsetUrls(string value)
-    {
-        var index = 0;
-        while (index < value.Length)
-        {
-            while (index < value.Length && (char.IsWhiteSpace(value[index]) || value[index] == ','))
-                index++;
-
-            if (index >= value.Length)
-                yield break;
-
-            var start = index;
-            var isDataUrl = value.AsSpan(index).StartsWith("data:", StringComparison.OrdinalIgnoreCase);
-            if (isDataUrl)
-            {
-                index += "data:".Length;
-                while (index < value.Length)
-                {
-                    if (char.IsWhiteSpace(value[index]))
-                        break;
-                    if (value[index] == ',' && (index + 1 >= value.Length || char.IsWhiteSpace(value[index + 1])))
-                        break;
-                    index++;
-                }
-            }
-            else
-            {
-                while (index < value.Length && !char.IsWhiteSpace(value[index]) && value[index] != ',')
-                    index++;
-            }
-
-            var url = value[start..index].Trim();
-            if (url.Length > 0)
-                yield return url;
-
-            while (index < value.Length && value[index] != ',')
-                index++;
-
-            if (index < value.Length && value[index] == ',')
-                index++;
-        }
-    }
-
-    internal static string MaskHtmlRawTextRegions(string text)
-    {
-        // Walk `text` character by character, masking the body of raw-text /
-        // RCDATA elements (`<script>` / `<style>` / `<textarea>` / `<title>`)
-        // and `<!-- ... -->` comments. Regex-based masking could not reliably
-        // handle cases like `<script data-note="a > b" src="/app.js">` (quoted
-        // `>` inside an attribute terminated the naive `[^>]*` pattern) or
-        // `<script data-note="oops\nconst tpl = '<evil-card id="phantom">';`
-        // (unterminated quote let nested `"..."` pairs match across script
-        // body content). The state machine uses the same quote-handling logic
-        // as the symbol extractor's state machine so both agree on where a
-        // raw-text opener ends, and falls back to masking through EOF when an
-        // opener is unterminated — that matches HTML's spec behavior (an
-        // unclosed raw-text element swallows everything until EOF or
-        // `</name>`) and prevents script-body content from leaking as phantom
-        // HTML symbols.
-        // マスクを正規表現ではなく文字単位の state machine で行い、`<script>` /
-        // `<style>` / `<textarea>` / `<title>` の本体と `<!-- ... -->` コメントを
-        // マスクする。正規表現だと `<script data-note="a > b" src="/app.js">` の
-        // ように属性値内の引用符付き `>` で早期終了したり、未終端引用符を持つ
-        // `<script data-note="oops\nconst tpl = '<evil-card id="phantom">';`
-        // のような入力で引用符ペアが script 本体をまたいで誤マッチする問題が
-        // あった。state machine は symbol extractor と同じ引用符処理を共有して
-        // 開始タグの境界を一致させ、開始タグが未終端の場合は EOF までマスクする
-        // （仕様上、未閉鎖 raw-text 要素は EOF か `</name>` まで本体を飲むため）。
-        if (!MayContainHtmlRawTextMaskTarget(text))
-            return text;
-
-        var chars = text.ToCharArray();
-        var i = 0;
-        while (i < chars.Length)
-        {
-            if (chars[i] != '<')
-            {
-                i++;
-                continue;
-            }
-
-            // `<!-- ... -->` comment. Closing `-->` is optional (masked through
-            // EOF) so mid-edit working-tree HTML with an unclosed comment does
-            // not leak following tags as phantom symbols.
-            // 未閉鎖コメントは EOF までマスクし、以降のタグが phantom にならないようにする。
-            if (i + 3 < chars.Length && chars[i + 1] == '!' && chars[i + 2] == '-' && chars[i + 3] == '-')
-            {
-                var commentClose = text.IndexOf("-->", i + 4, StringComparison.Ordinal);
-                var commentEnd = commentClose < 0 ? chars.Length : commentClose + 3;
-                BlankPreservingNewlines(chars, i, commentEnd);
-                i = commentEnd;
-                continue;
-            }
-
-            // `<![CDATA[ ... ]]>` section. In XHTML / SVG / MathML these are
-            // valid and must not leak their content as phantom tags. The
-            // terminator is specifically `]]>`, not the first `>`, so a naive
-            // `IndexOf('>', ...)` would stop early on inner markup and let the
-            // remaining CDATA body be parsed as real HTML. Unterminated CDATA
-            // masks through EOF, matching the comment-branch behavior.
-            // `<![CDATA[ ... ]]>` は XHTML / SVG / MathML で有効。終端は
-            // `]]>` のみであり、単純な `>` 検索では内部のタグで早期終了して
-            // 残り本体が phantom として抽出される。未閉鎖は EOF までマスクする。
-            if (i + 8 < chars.Length && chars[i + 1] == '!' && chars[i + 2] == '[' &&
-                chars[i + 3] == 'C' && chars[i + 4] == 'D' && chars[i + 5] == 'A' &&
-                chars[i + 6] == 'T' && chars[i + 7] == 'A' && chars[i + 8] == '[')
-            {
-                var cdataClose = text.IndexOf("]]>", i + 9, StringComparison.Ordinal);
-                var cdataEnd = cdataClose < 0 ? chars.Length : cdataClose + 3;
-                BlankPreservingNewlines(chars, i, cdataEnd);
-                i = cdataEnd;
-                continue;
-            }
-
-            // Other `<!...>` declarations (DOCTYPE and similar). Content
-            // between `<!` and the first unquoted `>` is a declaration, not a
-            // tag body, so mask it to prevent attribute-lookalike tokens from
-            // being emitted as symbols. Quoted values inside DOCTYPE PUBLIC /
-            // SYSTEM are walked via FindHtmlQuoteClose so embedded `>` does
-            // not terminate the declaration early.
-            // DOCTYPE などの `<!...>` 宣言は `FindHtmlTagOpenerEnd` で閉じ `>` を
-            // 探して丸ごとマスクする。引用符内の `>` で早期終了しないようにする。
-            if (i + 1 < chars.Length && chars[i + 1] == '!')
-            {
-                var declEnd = FindHtmlTagOpenerEnd(text, i);
-                if (declEnd < 0)
-                {
-                    BlankPreservingNewlines(chars, i, chars.Length);
-                    i = chars.Length;
-                    continue;
-                }
-                BlankPreservingNewlines(chars, i, declEnd + 1);
-                i = declEnd + 1;
-                continue;
-            }
-
-            // Processing instructions `<?...?>` (XML prolog, XSLT PIs, PHP
-            // short tags embedded in XHTML). Terminator is `?>`, not bare `>`.
-            // Content between can include tag-like markup that must not leak.
-            // `<?...?>` 処理命令。終端は `?>` で、内部のタグ様テキストは漏らさない。
-            if (i + 1 < chars.Length && chars[i + 1] == '?')
-            {
-                var piClose = text.IndexOf("?>", i + 2, StringComparison.Ordinal);
-                var piEnd = piClose < 0 ? chars.Length : piClose + 2;
-                BlankPreservingNewlines(chars, i, piEnd);
-                i = piEnd;
-                continue;
-            }
-
-            var rawName = TryMatchHtmlRawTextOpenerName(text, i);
-            if (rawName != null)
-            {
-                // Walk the opening tag to find its closing `>`. Multi-line
-                // quoted attribute values are allowed; the helper only returns
-                // -1 if the opener cannot be closed before EOF.
-                // 開始タグの `>` を探す。複数行に跨る引用符付き属性値は OK。
-                // EOF 前に閉じられない場合のみ -1 を返す。
-                var openerEnd = FindHtmlTagOpenerEnd(text, i);
-                if (openerEnd < 0)
-                {
-                    // Unterminated raw-text opener. Mask from `<` to EOF — this
-                    // matches HTML spec behavior and prevents script-body
-                    // content from leaking as phantom symbols.
-                    // 開始タグが未終端の場合、仕様どおり EOF までマスクする。
-                    BlankPreservingNewlines(chars, i, chars.Length);
-                    i = chars.Length;
-                    continue;
-                }
-
-                var bodyStart = openerEnd + 1;
-                var closeIdx = FindHtmlRawTextClose(text, bodyStart, rawName);
-                var bodyEnd = closeIdx < 0 ? chars.Length : closeIdx;
-                BlankPreservingNewlines(chars, bodyStart, bodyEnd);
-
-                if (closeIdx < 0)
-                {
-                    i = chars.Length;
-                    continue;
-                }
-
-                var closeGt = text.IndexOf('>', closeIdx);
-                i = closeGt < 0 ? chars.Length : closeGt + 1;
-                continue;
-            }
-
-            // Non-raw-text tag opener (including closing tags `</...`). Walk
-            // past the whole opener so quoted attribute values like
-            // `<div title="<script>">` or `<div title="<!--">` do not re-enter
-            // the raw-text / comment branches on the next character and get
-            // misidentified as raw-text/comment openers. Without this skip,
-            // the char-by-char scan would re-encounter `<script>` / `<!--`
-            // inside the attribute value and mask through EOF.
-            // raw-text 以外のタグ opener（`</...` を含む）に遭遇したら、opener 全体を
-            // 飛ばして属性値内の `<script>` / `<!--` が次の文字で raw-text / comment
-            // として再解釈されないようにする。これを入れないと属性値内の `<script>`
-            // を raw-text 本体マスク対象と誤認して以降の兄弟タグを全部飲み込む。
-            if (i + 1 < chars.Length && (IsHtmlTagNameStart(chars[i + 1]) || chars[i + 1] == '/'))
-            {
-                var openerEnd = FindHtmlTagOpenerEnd(text, i);
-                if (openerEnd >= 0)
-                {
-                    i = openerEnd + 1;
-                    continue;
-                }
-
-                // Unterminated non-raw-text tag opener (mid-edit quoted attribute
-                // like `<div title="<!--` or `<div title="<script>`). Advance
-                // past the current line so the `<!--` / `<script>` inside the
-                // broken quoted value is not re-encountered on the very next
-                // character and misidentified as a real comment / raw-text
-                // opener that would mask through EOF. Sibling tags on later
-                // lines still get their chance to be walked.
-                // 未終端の non-raw-text タグ opener（`<div title="<!--` のような
-                // 編集途中の引用属性）に遭遇した場合、`i++` で戻ると引用値内の
-                // `<!--` / `<script>` が次文字で comment / raw-text opener として
-                // 再解釈されて EOF までマスクされるため、現在行末まで一気に進めて
-                // 次行以降の兄弟タグを拾えるようにする。
-                var eolIdx = text.IndexOf('\n', i);
-                i = eolIdx < 0 ? chars.Length : eolIdx + 1;
-                continue;
-            }
-
-            i++;
-        }
-        return new string(chars);
-    }
-
-    private static bool MayContainHtmlRawTextMaskTarget(string text)
-    {
-        for (var index = text.IndexOf('<'); index >= 0; index = text.IndexOf('<', index + 1))
-        {
-            if (index + 1 >= text.Length)
-                continue;
-
-            var next = text[index + 1];
-            if (next is '!' or '?')
-                return true;
-
-            if (TryMatchHtmlRawTextOpenerName(text, index) != null)
-                return true;
-        }
-
-        return false;
-    }
-
-    private static string? TryMatchHtmlRawTextOpenerName(string text, int start)
-    {
-        // Check if `text[start]` (must be `<`) begins `<script` / `<style` /
-        // `<textarea` / `<title` followed by a non-tag-name-char (so `<scriptx`
-        // is NOT matched as `<script`).
-        // `start` は `<` の位置。`<script` / `<style` / `<textarea` / `<title`
-        // に続く文字がタグ名文字でないもののみ一致させる（`<scriptx` は除外）。
-        foreach (var name in HtmlRawTextElementNames)
-        {
-            var nameStart = start + 1;
-            if (nameStart + name.Length > text.Length)
-                continue;
-            var match = true;
-            for (var j = 0; j < name.Length; j++)
-            {
-                if (!EqualsHtmlAsciiIgnoreCase(text[nameStart + j], name[j]))
-                {
-                    match = false;
-                    break;
-                }
-            }
-            if (!match)
-                continue;
-            var after = nameStart + name.Length;
-            if (after >= text.Length || !IsHtmlTagNameChar(text[after]))
-                return name;
-        }
-        return null;
-    }
-
-    private static bool MayNeedHtmlRawTextMask(string text)
-        => text.IndexOf("<!", StringComparison.Ordinal) >= 0
-           || text.IndexOf("<?", StringComparison.Ordinal) >= 0
-           || text.IndexOf("<script", StringComparison.OrdinalIgnoreCase) >= 0
-           || text.IndexOf("<style", StringComparison.OrdinalIgnoreCase) >= 0
-           || text.IndexOf("<textarea", StringComparison.OrdinalIgnoreCase) >= 0
-           || text.IndexOf("<title", StringComparison.OrdinalIgnoreCase) >= 0;
-
-    private static int FindHtmlTagOpenerEnd(string text, int start)
-    {
-        // Walk from `start` (position of `<`) forward to find the opening `>`,
-        // skipping over quoted attribute values. Multi-line quoted values are
-        // allowed per HTML5 spec.
-        // `start` は `<` の位置。引用符付き属性値を `FindHtmlQuoteClose` で飛ばしつつ
-        // 開始タグの閉じ `>` を探す。HTML5 仕様どおり複数行値も許容する。
-        var i = start + 1;
-        while (i < text.Length)
-        {
-            var c = text[i];
-            if (c == '>')
-                return i;
-            if (c == '"' || c == '\'')
-            {
-                var closeIdx = FindHtmlQuoteClose(text, i + 1, c);
-                if (closeIdx < 0)
-                    return -1;
-                i = closeIdx + 1;
-                continue;
-            }
-            i++;
-        }
-        return -1;
-    }
-
-    private static int FindHtmlQuoteClose(string text, int start, char quote)
-    {
-        // Scan forward for the matching closing quote. HTML5 allows newlines
-        // inside quoted attribute values (`<meta description="line1\nline2">`)
-        // and tag-like content (`<div title="<section id=x>">`), so we cross
-        // line boundaries and tag-name-like bytes without bailing. A quote is
-        // accepted as the close when it has "strong valid" post-value context:
-        // per HTML5 the char immediately after a quoted attribute value must
-        // be whitespace, `>`, or EOF. `/` alone is intentionally excluded from
-        // strong context — a `/` following a quote is ambiguous between the
-        // self-closing marker (`attr="v"/>`) and the opening `"` of a later
-        // path-like attribute (`href="/app.css"`). Accepting bare `/` would
-        // let an earlier unterminated `title="...` silently steal the opening
-        // quote of `href="/app.css"` and swallow every sibling tag between
-        // them. The self-closing form `"/>` IS accepted (ambiguity gone —
-        // the `/` is followed by `>`), so void-element tags like
-        // `<link href="/app.css"/>` still close cleanly without triggering
-        // the nested-attribute fallback on the following sibling tag.
-        //
-        // When a non-strong `"` is encountered and it matches an "attribute-
-        // start" pattern (preceded by `[attr-name-chars]+=` with whitespace
-        // before the ident), the scanner treats it as a nested attribute
-        // opening: it walks past that attribute's value (finding the matching
-        // inner quote) and resumes scanning, instead of mis-taking the inner
-        // opening for our close. This preserves strict-HTML5 behavior on
-        // well-formed multi-line quoted values (they contain no spurious
-        // `ident="` patterns) while keeping mid-edit resilience — if the
-        // outer quote is truly unterminated, we'll walk through all nested
-        // attributes without finding a strong close, and return -1 so the
-        // attribute parser can bail at EOL and recover sibling tags on the
-        // next lines.
-        //
-        // If neither a strong close nor a nested pattern is ever seen, fall
-        // back to the first bare `"` candidate (matches spec tokenizer
-        // recovery for malformed content like `<div id="foo"bar>`). If nested
-        // patterns WERE seen but no strong close was found, return -1 to
-        // signal the attribute is effectively unterminated for our purposes.
-        //
-        // 閉じ引用符を探す。HTML5 は属性値内の改行とタグ様テキストを許容するため、
-        // 改行やタグ様の文字では早期中断しない。引用符を閉じとして採用する条件は、
-        // 直後が空白 / `>` / EOF の「strong な属性値終端」であること。`/` は
-        // self-closing (`attr="v"/>`) と後続属性の開始引用符 (`href="/app.css"`)
-        // の区別が文脈無しでは付かないため、`/` 単独は strong には含めない。
-        // bare `/` を許容すると、未終端の `title="...` が後続 `href="/app.css"`
-        // の開き `"` を奪って兄弟タグを丸呑みする。
-        //
-        // strong でない `"` が「属性開始パターン」(`[attr-name-chars]+=` の前が
-        // 空白) にマッチしたら、それは nested な属性開始と判断し、その属性の値を
-        // 次の引用符まで飛ばして外側 scan を再開する。これにより Blocker 2
-        // (`<div title="line1\n<section></section>\nline3" id="real">`) のような
-        // 真に妥当な複数行引用属性値は strong 終端まで到達して通り、一方で未終端な
-        // 外側 `"` は nested を何個かスキップしても strong 終端に到達せず、最終的に
-        // -1 を返して属性パーサが EOL で bail → 次行以降の兄弟タグを拾える。
-        //
-        // strong 終端にも nested にも該当しない `"` は弱い候補として記録し、EOF
-        // 到達時に nested を見ていなければ fallback として返す（`<div id="foo"bar>`
-        // のような malformed でも spec に近い形で拾う）。nested を見ていれば -1 を
-        // 返して、未終端扱いにする。
-        var firstCandidate = -1;
-        var sawNested = false;
-        var i = start;
-        while (i < text.Length)
-        {
-            if (text[i] == quote)
-            {
-                var after = i + 1;
-                if (after >= text.Length)
-                    return i;
-                var nextCh = text[after];
-                if (nextCh == '>' || char.IsWhiteSpace(nextCh))
-                    return i;
-                // Accept the XML-style self-closing marker `"/>` as strong
-                // post-context. Bare `/` is still rejected because it cannot
-                // be distinguished from a path-like `href="/app.css"` opener.
-                // 自己閉鎖タグの `"/>` は strong として受理する。bare `/` は
-                // `href="/app.css"` の開きとの区別が付かないため受理しない。
-                if (nextCh == '/' && after + 1 < text.Length && text[after + 1] == '>')
-                    return i;
-
-                if (IsPrecededByHtmlAttributeStart(text, i, start))
-                {
-                    sawNested = true;
-                    var inner = i + 1;
-                    while (inner < text.Length && text[inner] != quote)
-                        inner++;
-                    if (inner >= text.Length)
-                        break;
-                    i = inner + 1;
-                    continue;
-                }
-
-                if (firstCandidate < 0)
-                    firstCandidate = i;
-            }
-            i++;
-        }
-        if (sawNested)
-            return -1;
-        return firstCandidate;
-    }
-
-    private static bool IsPrecededByHtmlAttributeStart(string text, int quotePos, int scanStart)
-    {
-        // Return true if the characters immediately before `quotePos` form a
-        // `[attr-name-chars]+=` pattern AND the ident is preceded by whitespace
-        // within the current scan — i.e. it looks like the start of a new
-        // attribute inside an outer quoted value. This is the signal that the
-        // `"` is more likely a nested attribute opening than the true close of
-        // the outer value.
-        // `quotePos` の直前が `[attr-name-chars]+=` で、その ident の前が
-        // scan 範囲内の空白文字なら true。外側引用値の中で新しい属性が
-        // 始まっているパターンと判定する。
-        if (quotePos <= scanStart)
-            return false;
-        if (text[quotePos - 1] != '=')
-            return false;
-        var j = quotePos - 2;
-        var identEnd = j + 1;
-        while (j >= scanStart && IsHtmlAttrNameChar(text[j]))
-            j--;
-        if (j + 1 >= identEnd)
-            return false;
-        if (j < scanStart)
-            return false;
-        return char.IsWhiteSpace(text[j]);
-    }
-
-    private static int FindHtmlRawTextClose(string text, int start, string tagName)
-    {
-        // Locate the next `</tagName` (case-insensitive) at or after `start`.
-        // Returns the position of `<`, or -1 if none.
-        // `</tagName` を大文字小文字非区別で `start` 以降から探し、`<` の位置を返す。
-        var i = start;
-        while (i < text.Length - tagName.Length - 2)
-        {
-            if (text[i] == '<' && text[i + 1] == '/')
-            {
-                var match = true;
-                for (var j = 0; j < tagName.Length; j++)
-                {
-                    if (!EqualsHtmlAsciiIgnoreCase(text[i + 2 + j], tagName[j]))
-                    {
-                        match = false;
-                        break;
-                    }
-                }
-                if (match)
-                {
-                    var after = i + 2 + tagName.Length;
-                    if (after >= text.Length)
-                        return i;
-                    var nc = text[after];
-                    if (nc == '>' || nc == '/' || char.IsWhiteSpace(nc))
-                        return i;
-                }
-            }
-            i++;
-        }
-        return -1;
-    }
-
-    private static bool EqualsHtmlAsciiIgnoreCase(char actual, char expectedLower)
-    {
-        if (actual >= 'A' && actual <= 'Z')
-            actual = (char)(actual + ('a' - 'A'));
-
-        return actual == expectedLower;
-    }
-
-    private static void BlankPreservingNewlines(char[] chars, int start, int end)
-    {
-        var limit = Math.Min(end, chars.Length);
-        for (var i = start; i < limit; i++)
-        {
-            if (chars[i] != '\n' && chars[i] != '\r')
-                chars[i] = ' ';
-        }
-    }
-
-
-
-
-
-}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Xaml.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Xaml.cs
new file mode 100644
index 000000000..043c6bd7c
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Xaml.cs
@@ -0,0 +1,1589 @@
+using System.Text;
+using System.Text.RegularExpressions;
+using Regex = CodeIndex.Indexer.BoundedRegex;
+using System.Runtime.CompilerServices;
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+
+    private static readonly string[] WrappedXamlTypeBearingAttributeNames = ["x:Class", "x:DataType", "TargetType"];
+
+    private static bool MayContainXamlSymbolMarkers(string[] lines)
+    {
+        for (var i = 0; i < lines.Length; i++)
+        {
+            var line = lines[i];
+            if (line.IndexOf('=') >= 0
+                || line.Contains("x:", StringComparison.Ordinal)
+                || line.IndexOf('{') >= 0
+                || line.Contains(".TypeName", StringComparison.Ordinal)
+                || line.Contains("Binding", StringComparison.Ordinal)
+                || line.Contains("Resource", StringComparison.Ordinal))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private static bool MayContainXamlEventHandlerAttribute(string line)
+    {
+        if (line.IndexOf('=') < 0)
+            return false;
+
+        foreach (var eventName in XamlEventAttributeNames)
+        {
+            if (line.Contains(eventName, StringComparison.Ordinal))
+                return true;
+        }
+
+        return false;
+    }
+
+    private static bool MayContainXamlBindingMarkup(string rawText)
+        => rawText.Contains("{Binding", StringComparison.Ordinal)
+        || rawText.Contains("{x:Bind", StringComparison.Ordinal)
+        || rawText.Contains("{TemplateBinding", StringComparison.Ordinal)
+        || rawText.Contains("{CompiledBinding", StringComparison.Ordinal)
+        || rawText.Contains("{ReflectionBinding", StringComparison.Ordinal);
+
+    private static bool MayContainXamlReferenceSymbol(string rawText)
+        => TextContainsAny(rawText, XamlReferenceMarkupPrefixes)
+        || TextContainsAny(rawText, XamlReferenceObjectElementPrefixes)
+        || (rawText.Contains("x:Reference", StringComparison.Ordinal)
+            && rawText.Contains(".Name", StringComparison.Ordinal));
+
+    private static bool MayContainXamlBindingElementNameSymbol(string rawText)
+        => rawText.Contains("ElementName", StringComparison.Ordinal)
+        && (MayContainXamlBindingMarkup(rawText)
+            || rawText.Contains("<Binding", StringComparison.Ordinal)
+            || rawText.Contains("Binding.ElementName", StringComparison.Ordinal));
+
+    private static bool MayContainXamlBindingObjectElementSymbol(string rawText)
+        => (rawText.Contains("<Binding", StringComparison.Ordinal)
+            && rawText.Contains("Path", StringComparison.Ordinal))
+        || rawText.Contains("Binding.Path", StringComparison.Ordinal);
+
+    private static bool TextContainsAny(string text, IReadOnlyList<string> values)
+    {
+        for (var i = 0; i < values.Count; i++)
+        {
+            if (text.Contains(values[i], StringComparison.Ordinal))
+                return true;
+        }
+
+        return false;
+    }
+
+    private static bool MayContainWrappedXamlTypeBearingAttribute(string rawText) =>
+        rawText.Contains("x:Class", StringComparison.Ordinal)
+        || rawText.Contains("x:DataType", StringComparison.Ordinal)
+        || rawText.Contains("TargetType", StringComparison.Ordinal);
+
+    private static bool MayContainWrappedXamlSearchAttribute(string rawText)
+    {
+        if (rawText.Contains("x:Name", StringComparison.Ordinal)
+            || rawText.Contains("x:Key", StringComparison.Ordinal))
+        {
+            return true;
+        }
+
+        foreach (var attributeName in XamlEventAttributeNames)
+        {
+            if (rawText.Contains(attributeName, StringComparison.Ordinal))
+                return true;
+        }
+
+        return false;
+    }
+
+    private static void AddWrappedXamlTypeArgumentSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        var cursor = 0;
+        while (cursor < rawText.Length)
+        {
+            var attributeIndex = rawText.IndexOf("x:TypeArguments", cursor, StringComparison.Ordinal);
+            if (attributeIndex < 0)
+                break;
+
+            var equalsIndex = rawText.IndexOf('=', attributeIndex);
+            if (equalsIndex < 0)
+            {
+                cursor = attributeIndex + 1;
+                continue;
+            }
+
+            var quoteIndex = equalsIndex + 1;
+            while (quoteIndex < rawText.Length && char.IsWhiteSpace(rawText[quoteIndex]))
+                quoteIndex++;
+
+            if (quoteIndex >= rawText.Length)
+                break;
+
+            var quote = rawText[quoteIndex];
+            if (quote is not ('"' or '\''))
+            {
+                cursor = quoteIndex + 1;
+                continue;
+            }
+
+            var valueStart = quoteIndex + 1;
+            var valueEnd = valueStart;
+            while (valueEnd < rawText.Length && rawText[valueEnd] != quote)
+                valueEnd++;
+
+            if (valueEnd >= rawText.Length)
+            {
+                cursor = valueStart;
+                continue;
+            }
+
+            if (FindHtmlLineNumber(lineStarts, valueEnd) == FindHtmlLineNumber(lineStarts, attributeIndex))
+            {
+                cursor = valueEnd + 1;
+                continue;
+            }
+
+            var value = rawText[valueStart..valueEnd];
+            if (value.Length > 0)
+            {
+                var startLine = FindHtmlLineNumber(lineStarts, attributeIndex);
+                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+                foreach (var normalized in NormalizeXamlTypeArgumentsValue(value))
+                {
+                    if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "class",
+                        Name = normalized,
+                        Line = startLine,
+                        StartLine = startLine,
+                        EndLine = startLine,
+                        Signature = lines[signatureIndex].Trim(),
+                    }))
+                        return;
+                }
+            }
+
+            cursor = valueEnd + 1;
+        }
+    }
+
+    private static void AddWrappedXamlTypeBearingAttributeSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        // Handle XAML values that are split away from `=` onto later lines.
+        // `x:Class`, `x:DataType`, and `TargetType` are intentionally kept on the
+        // same normalization path as the line-based extractor so search results stay consistent.
+        foreach (var attributeName in WrappedXamlTypeBearingAttributeNames)
+        {
+            var cursor = 0;
+            while (cursor < rawText.Length)
+            {
+                var attributeIndex = rawText.IndexOf(attributeName, cursor, StringComparison.Ordinal);
+                if (attributeIndex < 0)
+                    break;
+
+                var equalsIndex = rawText.IndexOf('=', attributeIndex);
+                if (equalsIndex < 0)
+                {
+                    cursor = attributeIndex + 1;
+                    continue;
+                }
+
+                var quoteIndex = equalsIndex + 1;
+                while (quoteIndex < rawText.Length && char.IsWhiteSpace(rawText[quoteIndex]))
+                    quoteIndex++;
+
+                if (quoteIndex >= rawText.Length)
+                    break;
+
+                var quote = rawText[quoteIndex];
+                if (quote is not ('"' or '\''))
+                {
+                    cursor = quoteIndex + 1;
+                    continue;
+                }
+
+                var valueStart = quoteIndex + 1;
+                var valueEnd = valueStart;
+                while (valueEnd < rawText.Length && rawText[valueEnd] != quote)
+                    valueEnd++;
+
+                if (valueEnd >= rawText.Length)
+                {
+                    cursor = valueStart;
+                    continue;
+                }
+
+                if (FindHtmlLineNumber(lineStarts, valueEnd) == FindHtmlLineNumber(lineStarts, attributeIndex))
+                {
+                    cursor = valueEnd + 1;
+                    continue;
+                }
+
+                var value = NormalizeXamlKeyValue(rawText[valueStart..valueEnd]);
+                if (value.Length > 0)
+                {
+                    var startLine = FindHtmlLineNumber(lineStarts, attributeIndex);
+                    var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+                    if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "class",
+                        Name = value,
+                        Line = startLine,
+                        StartLine = startLine,
+                        EndLine = startLine,
+                        Signature = lines[signatureIndex].Trim(),
+                    }))
+                        return;
+                }
+
+                cursor = valueEnd + 1;
+            }
+        }
+    }
+
+    private static void AddWrappedXamlSearchAttributeSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        if (rawText.Contains("x:Name", StringComparison.Ordinal))
+        {
+            foreach (var occurrence in EnumerateWrappedXamlAttributeValues(rawText, lineStarts, "x:Name"))
+            {
+                if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, occurrence.AttributeIndex, "property", occurrence.Value))
+                    return;
+            }
+        }
+
+        if (rawText.Contains("x:Key", StringComparison.Ordinal))
+        {
+            foreach (var occurrence in EnumerateWrappedXamlAttributeValues(rawText, lineStarts, "x:Key"))
+            {
+                if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, occurrence.AttributeIndex, "property", NormalizeXamlKeyValue(occurrence.Value)))
+                    return;
+            }
+        }
+
+        foreach (var attributeName in XamlEventAttributeNames)
+        {
+            if (!rawText.Contains(attributeName, StringComparison.Ordinal))
+                continue;
+
+            foreach (var occurrence in EnumerateWrappedXamlAttributeValues(rawText, lineStarts, attributeName))
+            {
+                if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, occurrence.AttributeIndex, "function", occurrence.Value))
+                    return;
+            }
+        }
+    }
+
+    private static IEnumerable<(int AttributeIndex, string Value)> EnumerateWrappedXamlAttributeValues(
+        string rawText,
+        int[] lineStarts,
+        string attributeName)
+    {
+        var cursor = 0;
+        while (cursor < rawText.Length)
+        {
+            var attributeIndex = rawText.IndexOf(attributeName, cursor, StringComparison.Ordinal);
+            if (attributeIndex < 0)
+                yield break;
+
+            if (!TryReadXamlAttributeValue(rawText, attributeName, attributeIndex, out var valueStart, out var valueEnd))
+            {
+                cursor = attributeIndex + 1;
+                continue;
+            }
+
+            if (FindHtmlLineNumber(lineStarts, valueEnd) != FindHtmlLineNumber(lineStarts, attributeIndex))
+                yield return (attributeIndex, rawText[valueStart..valueEnd]);
+
+            cursor = valueEnd + 1;
+        }
+    }
+
+    private static bool TryReadXamlAttributeValue(
+        string rawText,
+        string attributeName,
+        int attributeIndex,
+        out int valueStart,
+        out int valueEnd)
+    {
+        valueStart = -1;
+        valueEnd = -1;
+
+        if (!IsXamlAttributeNameMatch(rawText, attributeIndex, attributeName.Length))
+            return false;
+
+        var cursor = attributeIndex + attributeName.Length;
+        while (cursor < rawText.Length && char.IsWhiteSpace(rawText[cursor]))
+            cursor++;
+
+        if (cursor >= rawText.Length || rawText[cursor] != '=')
+            return false;
+
+        cursor++;
+        while (cursor < rawText.Length && char.IsWhiteSpace(rawText[cursor]))
+            cursor++;
+
+        if (cursor >= rawText.Length)
+            return false;
+
+        var quote = rawText[cursor];
+        if (quote is not ('"' or '\''))
+            return false;
+
+        valueStart = cursor + 1;
+        valueEnd = valueStart;
+        while (valueEnd < rawText.Length && rawText[valueEnd] != quote)
+            valueEnd++;
+
+        return valueEnd < rawText.Length;
+    }
+
+    private static bool IsXamlAttributeNameMatch(string rawText, int index, int length)
+    {
+        if (index > 0 && IsXamlAttributeNameChar(rawText[index - 1]))
+            return false;
+
+        var after = index + length;
+        return after >= rawText.Length || !IsXamlAttributeNameChar(rawText[after]);
+    }
+
+    private static bool IsXamlAttributeNameChar(char c)
+        => IsXamlMarkupNameChar(c) || c == '-';
+
+    private static bool AddXamlAttributeSymbol(
+        long fileId,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols,
+        int attributeIndex,
+        string kind,
+        string value)
+    {
+        value = value.Trim();
+        if (value.Length == 0)
+            return symbols.Count <= StructuredDataMaxSymbols;
+
+        var startLine = FindHtmlLineNumber(lineStarts, attributeIndex);
+        var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+        return TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+        {
+            FileId = fileId,
+            Kind = kind,
+            Name = value,
+            Line = startLine,
+            StartLine = startLine,
+            EndLine = startLine,
+            Signature = lines[signatureIndex].Trim(),
+        });
+    }
+
+    private static void AddXamlBindingElementNameSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        if (MayContainXamlBindingMarkup(rawText)
+            && rawText.Contains("ElementName", StringComparison.Ordinal))
+        {
+            foreach (Match bindingMatch in Regex.EnumerateMatches(XamlBindingRegex, rawText))
+            {
+                if (!bindingMatch.Groups["kind"].Value.Equals("Binding", StringComparison.OrdinalIgnoreCase))
+                    continue;
+
+                var value = NormalizeXamlBindingElementNameValue(bindingMatch.Groups["content"].Value);
+                if (value.Length == 0)
+                    continue;
+
+                if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, bindingMatch.Index, "property", value))
+                    return;
+            }
+        }
+
+        if (rawText.Contains("<Binding", StringComparison.Ordinal)
+            && rawText.Contains("ElementName", StringComparison.Ordinal))
+        {
+            var cursor = 0;
+            while (cursor < rawText.Length)
+            {
+                var tagIndex = rawText.IndexOf("<Binding", cursor, StringComparison.Ordinal);
+                if (tagIndex < 0)
+                    break;
+
+                var nameEnd = tagIndex + "<Binding".Length;
+                if (nameEnd < rawText.Length && IsXamlAttributeNameChar(rawText[nameEnd]))
+                {
+                    cursor = nameEnd;
+                    continue;
+                }
+
+                var tagEnd = FindXamlTagEnd(rawText, nameEnd);
+                if (tagEnd < 0)
+                    break;
+
+                var elementNameAttributeIndex = IndexOfXamlAttributeInRange(rawText, "ElementName", nameEnd, tagEnd);
+                if (elementNameAttributeIndex >= 0
+                    && TryReadXamlAttributeValue(rawText, "ElementName", elementNameAttributeIndex, out var valueStart, out var valueEnd)
+                    && valueEnd <= tagEnd)
+                {
+                    if (!AddXamlAttributeSymbol(
+                        fileId,
+                        lines,
+                        lineStarts,
+                        symbols,
+                        elementNameAttributeIndex,
+                        "property",
+                        NormalizeXamlElementReferenceValue(rawText[valueStart..valueEnd])))
+                    {
+                        return;
+                    }
+                }
+
+                cursor = tagEnd + 1;
+            }
+        }
+
+        if (!rawText.Contains("Binding.ElementName", StringComparison.Ordinal))
+            return;
+
+        foreach (Match elementNameMatch in Regex.EnumerateMatches(XamlBindingElementNamePropertyElementRegex, rawText))
+        {
+            var value = NormalizeXamlElementReferenceValue(elementNameMatch.Groups["value"].Value);
+            if (value.Length == 0)
+                continue;
+
+            if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, elementNameMatch.Index, "property", value))
+                return;
+        }
+    }
+
+    private static string NormalizeXamlBindingElementNameValue(string content)
+    {
+        content = content.Trim();
+        if (content.Length == 0)
+            return "";
+
+        foreach (var argument in SplitTopLevelMarkupArguments(content))
+        {
+            var equalsIndex = IndexOfTopLevelEquals(argument);
+            if (equalsIndex < 0)
+                continue;
+
+            var argumentName = argument.AsSpan(0, equalsIndex).Trim();
+            if (!argumentName.Equals("ElementName", StringComparison.OrdinalIgnoreCase))
+                continue;
+
+            var value = NormalizeXamlElementReferenceValue(argument[(equalsIndex + 1)..]);
+            if (value.Length > 0)
+                return value;
+        }
+
+        return "";
+    }
+
+    private static string NormalizeXamlElementReferenceValue(string value)
+    {
+        return NormalizeXamlMarkupValue(value);
+    }
+
+    private static void AddXamlBindingObjectElementSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        if (rawText.Contains("<Binding", StringComparison.Ordinal)
+            && rawText.Contains("Path", StringComparison.Ordinal))
+        {
+            var cursor = 0;
+            while (cursor < rawText.Length)
+            {
+                var tagIndex = rawText.IndexOf("<Binding", cursor, StringComparison.Ordinal);
+                if (tagIndex < 0)
+                    break;
+
+                var nameEnd = tagIndex + "<Binding".Length;
+                if (nameEnd < rawText.Length && IsXamlAttributeNameChar(rawText[nameEnd]))
+                {
+                    cursor = nameEnd;
+                    continue;
+                }
+
+                var tagEnd = FindXamlTagEnd(rawText, nameEnd);
+                if (tagEnd < 0)
+                    break;
+
+                var pathAttributeIndex = IndexOfXamlAttributeInRange(rawText, "Path", nameEnd, tagEnd);
+                if (pathAttributeIndex >= 0
+                    && TryReadXamlAttributeValue(rawText, "Path", pathAttributeIndex, out var valueStart, out var valueEnd)
+                    && valueEnd <= tagEnd)
+                {
+                    if (!AddXamlAttributeSymbol(
+                        fileId,
+                        lines,
+                        lineStarts,
+                        symbols,
+                        pathAttributeIndex,
+                        "property",
+                        NormalizeXamlBindingPathValue(rawText[valueStart..valueEnd])))
+                    {
+                        return;
+                    }
+                }
+
+                cursor = tagEnd + 1;
+            }
+        }
+
+        if (!rawText.Contains("Binding.Path", StringComparison.Ordinal))
+            return;
+
+        foreach (Match pathMatch in Regex.EnumerateMatches(XamlBindingPathPropertyElementRegex, rawText))
+        {
+            var value = NormalizeXamlBindingPathValue(pathMatch.Groups["value"].Value);
+            if (value.Length == 0)
+                continue;
+
+            var startLine = FindHtmlLineNumber(lineStarts, pathMatch.Index);
+            var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+            if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+            {
+                FileId = fileId,
+                Kind = "property",
+                Name = value,
+                Line = startLine,
+                StartLine = startLine,
+                EndLine = startLine,
+                Signature = lines[signatureIndex].Trim(),
+            }))
+                return;
+        }
+    }
+
+    private static int FindXamlTagEnd(string rawText, int startIndex)
+    {
+        char? quote = null;
+        for (var i = startIndex; i < rawText.Length; i++)
+        {
+            var ch = rawText[i];
+            if (quote is { } activeQuote)
+            {
+                if (ch == activeQuote)
+                    quote = null;
+                continue;
+            }
+
+            if (ch is '"' or '\'')
+            {
+                quote = ch;
+                continue;
+            }
+
+            if (ch == '>')
+                return i;
+        }
+
+        return -1;
+    }
+
+    private static int IndexOfXamlAttributeInRange(string rawText, string attributeName, int startIndex, int endIndex)
+    {
+        char? quote = null;
+        for (var i = startIndex; i < endIndex; i++)
+        {
+            var ch = rawText[i];
+            if (quote is { } activeQuote)
+            {
+                if (ch == activeQuote)
+                    quote = null;
+                continue;
+            }
+
+            if (ch is '"' or '\'')
+            {
+                quote = ch;
+                continue;
+            }
+
+            if (!rawText.AsSpan(i, endIndex - i).StartsWith(attributeName, StringComparison.Ordinal))
+                continue;
+
+            if (IsXamlAttributeNameMatch(rawText, i, attributeName.Length)
+                && TryReadXamlAttributeValue(rawText, attributeName, i, out _, out var valueEnd)
+                && valueEnd <= endIndex)
+            {
+                return i;
+            }
+        }
+
+        return -1;
+    }
+
+    private static void AddXamlTypeObjectElementSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        if (!rawText.Contains("x:Type", StringComparison.Ordinal)
+            || !rawText.Contains("TypeName", StringComparison.Ordinal))
+        {
+            return;
+        }
+
+        foreach (Match typeMatch in Regex.EnumerateMatches(XamlTypeObjectElementRegex, rawText))
+        {
+            var value = NormalizeXamlKeyValue(typeMatch.Groups["value"].Value);
+            if (value.Length == 0)
+                continue;
+
+            var startLine = FindHtmlLineNumber(lineStarts, typeMatch.Index);
+            var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+            if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+            {
+                FileId = fileId,
+                Kind = "class",
+                Name = value,
+                Line = startLine,
+                StartLine = startLine,
+                EndLine = startLine,
+                Signature = lines[signatureIndex].Trim(),
+            }))
+                return;
+        }
+    }
+
+    private static void AddXamlTypePropertyElementSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        if (!rawText.Contains(".TypeName", StringComparison.Ordinal))
+            return;
+
+        foreach (Match typeMatch in Regex.EnumerateMatches(XamlTypePropertyElementRegex, rawText))
+        {
+            var value = NormalizeXamlKeyValue(typeMatch.Groups["value"].Value);
+            if (value.Length == 0)
+                continue;
+
+            var startLine = FindHtmlLineNumber(lineStarts, typeMatch.Index);
+            var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+            if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+            {
+                FileId = fileId,
+                Kind = "class",
+                Name = value,
+                Line = startLine,
+                StartLine = startLine,
+                EndLine = startLine,
+                Signature = lines[signatureIndex].Trim(),
+            }))
+                return;
+        }
+    }
+
+    private static void AddXamlTypeMarkupSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        if (rawText.Contains("{x:TypeExtension", StringComparison.Ordinal))
+            AddXamlMarkupExtensionTypeSymbols(fileId, rawText, lines, lineStarts, symbols, "{x:TypeExtension", false);
+        if (symbols.Count > StructuredDataMaxSymbols)
+            return;
+        if (rawText.Contains("{x:Type", StringComparison.Ordinal))
+            AddXamlMarkupExtensionTypeSymbols(fileId, rawText, lines, lineStarts, symbols, "{x:Type", true);
+    }
+
+    private static void AddXamlMarkupExtensionTypeSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols,
+        string prefix,
+        bool rejectNameCharAfterPrefix)
+    {
+        var cursor = 0;
+        while (cursor < rawText.Length)
+        {
+            var braceIndex = rawText.IndexOf(prefix, cursor, StringComparison.Ordinal);
+            if (braceIndex < 0)
+                break;
+
+            var afterPrefix = braceIndex + prefix.Length;
+            if (rejectNameCharAfterPrefix
+                && afterPrefix < rawText.Length
+                && IsXamlMarkupNameChar(rawText[afterPrefix]))
+            {
+                cursor = afterPrefix;
+                continue;
+            }
+
+            var closingBraceIndex = FindMatchingBrace(rawText, braceIndex);
+            if (closingBraceIndex < 0)
+            {
+                cursor = braceIndex + 1;
+                continue;
+            }
+
+            if (ShouldSkipXamlMarkupExtensionSymbol(rawText, braceIndex))
+            {
+                cursor = closingBraceIndex + 1;
+                continue;
+            }
+
+            var value = NormalizeXamlMarkupValue(rawText[braceIndex..(closingBraceIndex + 1)]);
+            if (value.Length > 0)
+            {
+                var startLine = FindHtmlLineNumber(lineStarts, braceIndex);
+                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+                if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                {
+                    FileId = fileId,
+                    Kind = "class",
+                    Name = value,
+                    Line = startLine,
+                    StartLine = startLine,
+                    EndLine = startLine,
+                    Signature = lines[signatureIndex].Trim(),
+                }))
+                    return;
+            }
+
+            cursor = closingBraceIndex + 1;
+        }
+    }
+
+    private static bool ShouldSkipXamlMarkupExtensionSymbol(string rawText, int braceIndex)
+    {
+        var tagStart = rawText.LastIndexOf('<', braceIndex);
+        if (tagStart < 0 || tagStart > braceIndex)
+            return false;
+
+        var tagEnd = rawText.IndexOf('>', tagStart);
+        if (tagEnd >= 0 && tagEnd < braceIndex)
+            return false;
+
+        var tagSlice = rawText[tagStart..braceIndex];
+        if (tagSlice.IndexOf("<x:Type", StringComparison.OrdinalIgnoreCase) >= 0
+            || tagSlice.IndexOf("<x:TypeExtension", StringComparison.OrdinalIgnoreCase) >= 0)
+        {
+            return true;
+        }
+
+        if (tagSlice.IndexOf("TargetType=", StringComparison.OrdinalIgnoreCase) >= 0)
+            return true;
+
+        return false;
+    }
+
+    private static void AddXamlStaticMemberTypeSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        if (!rawText.Contains("{x:Static", StringComparison.Ordinal))
+            return;
+
+        var cursor = 0;
+        while (cursor < rawText.Length)
+        {
+            var braceIndex = rawText.IndexOf("{x:Static", cursor, StringComparison.Ordinal);
+            if (braceIndex < 0)
+                break;
+
+            var closingBraceIndex = FindMatchingBrace(rawText, braceIndex);
+            if (closingBraceIndex < 0)
+            {
+                cursor = braceIndex + 1;
+                continue;
+            }
+
+            var value = NormalizeXamlMarkupValue(rawText[braceIndex..(closingBraceIndex + 1)]);
+            var lastDot = value.LastIndexOf('.');
+            if (lastDot > 0)
+            {
+                var typeName = value[..lastDot].Trim();
+                if (typeName.Length > 0)
+                {
+                    var startLine = FindHtmlLineNumber(lineStarts, braceIndex);
+                    var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+                    if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "class",
+                        Name = typeName,
+                        Line = startLine,
+                        StartLine = startLine,
+                        EndLine = startLine,
+                        Signature = lines[signatureIndex].Trim(),
+                    }))
+                        return;
+                }
+            }
+
+            cursor = closingBraceIndex + 1;
+        }
+    }
+
+    private static void AddXamlReferenceSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        foreach (var prefix in XamlReferenceMarkupPrefixes)
+        {
+            if (rawText.Contains(prefix, StringComparison.Ordinal))
+                AddXamlReferenceMarkupSymbols(fileId, rawText, lines, lineStarts, symbols, prefix);
+            if (symbols.Count > StructuredDataMaxSymbols)
+                return;
+        }
+
+        foreach (var prefix in XamlReferenceObjectElementPrefixes)
+        {
+            if (rawText.Contains(prefix, StringComparison.Ordinal))
+                AddXamlReferenceObjectElementSymbols(fileId, rawText, lines, lineStarts, symbols, prefix);
+            if (symbols.Count > StructuredDataMaxSymbols)
+                return;
+        }
+
+        if (!rawText.Contains("x:Reference", StringComparison.Ordinal)
+            || !rawText.Contains(".Name", StringComparison.Ordinal))
+        {
+            return;
+        }
+
+        foreach (Match nameMatch in Regex.EnumerateMatches(XamlReferenceNamePropertyElementRegex, rawText))
+        {
+            var value = NormalizeXamlElementReferenceValue(nameMatch.Groups["value"].Value);
+            if (value.Length == 0)
+                continue;
+
+            if (!AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, nameMatch.Index, "property", value))
+                return;
+        }
+    }
+
+    private static void AddXamlReferenceMarkupSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols,
+        string prefix)
+    {
+        var cursor = 0;
+        while (cursor < rawText.Length)
+        {
+            var braceIndex = rawText.IndexOf(prefix, cursor, StringComparison.Ordinal);
+            if (braceIndex < 0)
+                break;
+
+            var afterPrefix = braceIndex + prefix.Length;
+            if (afterPrefix < rawText.Length && IsXamlMarkupNameChar(rawText[afterPrefix]))
+            {
+                cursor = afterPrefix;
+                continue;
+            }
+
+            var closingBraceIndex = FindMatchingBrace(rawText, braceIndex);
+            if (closingBraceIndex < 0)
+            {
+                cursor = braceIndex + 1;
+                continue;
+            }
+
+            var value = NormalizeXamlRequiredMarkupArgumentValue(rawText[braceIndex..(closingBraceIndex + 1)]);
+            if (value.Length > 0
+                && !AddXamlAttributeSymbol(fileId, lines, lineStarts, symbols, braceIndex, "property", value))
+            {
+                return;
+            }
+
+            cursor = closingBraceIndex + 1;
+        }
+    }
+
+    private static void AddXamlReferenceObjectElementSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols,
+        string prefix)
+    {
+        var cursor = 0;
+        while (cursor < rawText.Length)
+        {
+            var tagIndex = rawText.IndexOf(prefix, cursor, StringComparison.Ordinal);
+            if (tagIndex < 0)
+                break;
+
+            var nameEnd = tagIndex + prefix.Length;
+            if (nameEnd < rawText.Length && IsXamlAttributeNameChar(rawText[nameEnd]))
+            {
+                cursor = nameEnd;
+                continue;
+            }
+
+            var tagEnd = FindXamlTagEnd(rawText, nameEnd);
+            if (tagEnd < 0)
+                break;
+
+            var nameAttributeIndex = IndexOfXamlAttributeInRange(rawText, "Name", nameEnd, tagEnd);
+            if (nameAttributeIndex >= 0
+                && TryReadXamlAttributeValue(rawText, "Name", nameAttributeIndex, out var valueStart, out var valueEnd)
+                && valueEnd <= tagEnd)
+            {
+                if (!AddXamlAttributeSymbol(
+                    fileId,
+                    lines,
+                    lineStarts,
+                    symbols,
+                    nameAttributeIndex,
+                    "property",
+                    NormalizeXamlElementReferenceValue(rawText[valueStart..valueEnd])))
+                {
+                    return;
+                }
+            }
+
+            cursor = tagEnd + 1;
+        }
+    }
+
+    private static void AddXamlResourceReferenceSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols)
+    {
+        foreach (var prefix in XamlResourceReferenceMarkupPrefixes)
+        {
+            if (rawText.Contains(prefix, StringComparison.Ordinal))
+                AddXamlResourceReferenceSymbols(fileId, rawText, lines, lineStarts, symbols, prefix);
+            if (symbols.Count > StructuredDataMaxSymbols)
+                return;
+        }
+    }
+
+    private static void AddXamlResourceReferenceSymbols(
+        long fileId,
+        string rawText,
+        string[] lines,
+        int[] lineStarts,
+        List<SymbolRecord> symbols,
+        string prefix)
+    {
+        var cursor = 0;
+        while (cursor < rawText.Length)
+        {
+            var braceIndex = rawText.IndexOf(prefix, cursor, StringComparison.Ordinal);
+            if (braceIndex < 0)
+                break;
+
+            var afterPrefix = braceIndex + prefix.Length;
+            if (afterPrefix < rawText.Length && IsXamlMarkupNameChar(rawText[afterPrefix]))
+            {
+                cursor = afterPrefix;
+                continue;
+            }
+
+            var closingBraceIndex = FindMatchingBrace(rawText, braceIndex);
+            if (closingBraceIndex < 0)
+            {
+                cursor = braceIndex + 1;
+                continue;
+            }
+
+            var value = NormalizeXamlResourceReferenceValue(rawText[braceIndex..(closingBraceIndex + 1)]);
+            if (value.Length > 0)
+            {
+                var startLine = FindHtmlLineNumber(lineStarts, braceIndex);
+                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+                if (!TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                {
+                    FileId = fileId,
+                    Kind = "property",
+                    Name = value,
+                    Line = startLine,
+                    StartLine = startLine,
+                    EndLine = startLine,
+                    Signature = lines[signatureIndex].Trim(),
+                }))
+                    return;
+            }
+
+            cursor = closingBraceIndex + 1;
+        }
+    }
+
+    private static string NormalizeXamlResourceReferenceValue(string value)
+        => NormalizeXamlRequiredMarkupArgumentValue(value);
+
+    private static string NormalizeXamlRequiredMarkupArgumentValue(string value)
+    {
+        value = value.Trim();
+        if (value.Length == 0 || value[0] != '{')
+            return value;
+
+        var closingBraceIndex = FindMatchingBrace(value, 0);
+        if (closingBraceIndex < 0)
+            return "";
+
+        var content = value.AsSpan(1, closingBraceIndex - 1).Trim().ToString();
+        var payloadStart = FindTopLevelMarkupPayloadStart(content);
+        if (payloadStart < 0)
+            return "";
+
+        var payloadStartIndex = SkipXamlMarkupWhitespace(content, payloadStart + 1);
+        if (payloadStartIndex >= content.Length)
+            return "";
+
+        var payload = content[payloadStartIndex..];
+        foreach (var argument in SplitTopLevelMarkupArguments(payload))
+        {
+            var normalized = NormalizeXamlMarkupArgument(argument);
+            if (normalized.Length > 0)
+                return normalized;
+        }
+
+        return "";
+    }
+
+    private static bool IsXamlMarkupNameChar(char c)
+        => char.IsLetterOrDigit(c) || c == '_' || c == ':' || c == '.';
+
+    private static string NormalizeXamlKeyValue(string value)
+    {
+        var trimmed = value.AsSpan().Trim();
+        if (trimmed.Length < 2 || trimmed[0] != '{' || trimmed[^1] != '}')
+            return trimmed.ToString();
+
+        return NormalizeXamlMarkupExtensionContent(trimmed[1..^1].Trim().ToString());
+    }
+
+    private static string NormalizeXamlBindingValue(string kind, string content)
+    {
+        var kindSpan = kind.AsSpan().Trim();
+        var contentSpan = content.AsSpan().Trim();
+        if (contentSpan.IsEmpty)
+            return "";
+
+        var contentText = contentSpan.ToString();
+        var isTemplateBinding = kindSpan.Equals("TemplateBinding", StringComparison.OrdinalIgnoreCase);
+        var payload = kindSpan.Equals("x:Bind", StringComparison.OrdinalIgnoreCase)
+            ? $"x:Bind {contentText}"
+            : isTemplateBinding
+                ? $"TemplateBinding {contentText}"
+                : $"Binding {contentText}";
+
+        var firstPath = NormalizeXamlBindingPath(payload, isTemplateBinding);
+        return firstPath.Length > 0 ? firstPath : contentText;
+    }
+
+    private static string NormalizeXamlBindingPath(string value, bool allowPropertyArgument)
+    {
+        var trimmed = value.AsSpan().Trim();
+        if (trimmed.IsEmpty)
+            return "";
+
+        var payloadStart = FindTopLevelMarkupPayloadStart(trimmed);
+        if (payloadStart < 0)
+            return trimmed.ToString();
+
+        var payloadStartIndex = SkipXamlMarkupWhitespace(trimmed, payloadStart + 1);
+        if (payloadStartIndex >= trimmed.Length)
+            return trimmed.ToString();
+
+        var payload = trimmed[payloadStartIndex..].ToString();
+        string? fallback = null;
+        foreach (var argument in SplitTopLevelMarkupArguments(payload))
+        {
+            var equalsIndex = IndexOfTopLevelEquals(argument);
+            if (equalsIndex >= 0)
+            {
+                var argumentName = argument.AsSpan(0, equalsIndex).Trim();
+                if (argumentName.Equals("Path", StringComparison.OrdinalIgnoreCase)
+                    || (allowPropertyArgument && argumentName.Equals("Property", StringComparison.OrdinalIgnoreCase)))
+                {
+                    var pathValue = NormalizeXamlBindingPathValue(argument[(equalsIndex + 1)..]);
+                    if (pathValue.Length > 0)
+                        return pathValue;
+                }
+
+                continue;
+            }
+
+            var normalized = NormalizeXamlBindingArgument(argument);
+            if (normalized.Length == 0)
+                continue;
+
+            fallback ??= normalized;
+        }
+
+        return fallback ?? trimmed.ToString();
+    }
+
+    private static string NormalizeXamlBindingArgument(string value)
+    {
+        var trimmed = value.AsSpan().Trim();
+        if (trimmed.IsEmpty)
+            return "";
+
+        var equalsIndex = IndexOfTopLevelEquals(trimmed);
+        if (equalsIndex >= 0)
+        {
+            var name = trimmed[..equalsIndex].Trim();
+            var normalized = trimmed[(equalsIndex + 1)..].Trim();
+            if (name.Equals("Path", StringComparison.OrdinalIgnoreCase))
+                return NormalizeXamlBindingPathValue(normalized.ToString());
+            if (!normalized.IsEmpty)
+                return NormalizeXamlMarkupValue(normalized.ToString());
+        }
+
+        return NormalizeXamlBindingPathValue(trimmed.ToString());
+    }
+
+    private static string NormalizeXamlBindingPathValue(string value)
+    {
+        var trimmed = value.AsSpan().Trim();
+        if (trimmed.IsEmpty)
+            return "";
+
+        value = NormalizeXamlMarkupValue(trimmed.ToString());
+        var lastDot = value.LastIndexOf('.');
+        if (lastDot >= 0 && lastDot + 1 < value.Length)
+            return value.AsSpan(lastDot + 1).Trim().ToString();
+
+        return value.AsSpan().Trim().ToString();
+    }
+
+    private static string NormalizeXamlMarkupValue(string value)
+    {
+        var trimmed = value.AsSpan().Trim();
+        if (trimmed.IsEmpty || trimmed[0] != '{')
+            return trimmed.ToString();
+
+        var closingBraceIndex = FindMatchingBrace(trimmed, 0);
+        if (closingBraceIndex < 0)
+            return trimmed.ToString();
+
+        var normalized = NormalizeXamlMarkupExtensionContent(trimmed.Slice(1, closingBraceIndex - 1).Trim().ToString());
+        var suffix = trimmed[(closingBraceIndex + 1)..].Trim();
+        return suffix.IsEmpty ? normalized : string.Concat(normalized, suffix.ToString());
+    }
+
+    private static string NormalizeXamlMarkupExtensionContent(string value)
+    {
+        var trimmed = value.AsSpan().Trim();
+        if (trimmed.IsEmpty)
+            return "";
+
+        var payloadStart = FindTopLevelMarkupPayloadStart(trimmed);
+        if (payloadStart < 0)
+            return trimmed.ToString();
+
+        var payloadStartIndex = SkipXamlMarkupWhitespace(trimmed, payloadStart + 1);
+        if (payloadStartIndex >= trimmed.Length)
+            return trimmed.ToString();
+
+        var payload = trimmed[payloadStartIndex..].ToString();
+        foreach (var argument in SplitTopLevelMarkupArguments(payload))
+        {
+            var normalized = NormalizeXamlMarkupArgument(argument);
+            if (normalized.Length > 0)
+                return normalized;
+        }
+
+        return trimmed.ToString();
+    }
+
+    private static IEnumerable<string> NormalizeXamlTypeArgumentsValue(string value)
+    {
+        var trimmed = value.AsSpan().Trim();
+        if (trimmed.IsEmpty)
+            yield break;
+
+        foreach (var argument in SplitTopLevelTypeArguments(trimmed.ToString()))
+        {
+            var normalized = NormalizeXamlMarkupArgument(argument);
+            if (normalized.Length > 0)
+            {
+                foreach (var expanded in ExpandXamlTypeArgument(normalized))
+                    yield return expanded;
+            }
+        }
+    }
+
+    private static IEnumerable<string> ExpandXamlTypeArgument(string value)
+    {
+        // Peel nested generic constructor shapes recursively so XAML type arguments like
+        // `Outer(Inner(A, B), C)` still surface every referenced type name.
+        value = value.Trim();
+        if (value.Length == 0)
+            yield break;
+
+        var payloadStart = FindTopLevelTypeConstructorStart(value);
+        if (payloadStart < 0)
+        {
+            yield return value;
+            yield break;
+        }
+
+        var payloadEnd = FindMatchingTypeConstructorEnd(value, payloadStart);
+        if (payloadEnd < 0)
+        {
+            yield return value;
+            yield break;
+        }
+
+        var prefix = value.AsSpan(0, payloadStart).Trim();
+        if (!prefix.IsEmpty)
+            yield return prefix.ToString();
+
+        var payload = value.AsSpan(payloadStart + 1, payloadEnd - payloadStart - 1).Trim();
+        if (!payload.IsEmpty)
+        {
+            foreach (var nestedArgument in SplitTopLevelTypeArguments(payload.ToString()))
+            {
+                var nestedNormalized = NormalizeXamlMarkupArgument(nestedArgument);
+                if (nestedNormalized.Length == 0)
+                    continue;
+
+                foreach (var nestedExpanded in ExpandXamlTypeArgument(nestedNormalized))
+                    yield return nestedExpanded;
+            }
+        }
+
+        var suffix = value.AsSpan(payloadEnd + 1).Trim();
+        if (!suffix.IsEmpty)
+        {
+            foreach (var expanded in ExpandXamlTypeArgument(suffix.ToString()))
+                yield return expanded;
+        }
+    }
+
+    private static string NormalizeXamlMarkupArgument(string value)
+    {
+        var trimmed = value.AsSpan().Trim();
+        if (trimmed.IsEmpty)
+            return "";
+
+        var equalsIndex = IndexOfTopLevelEquals(trimmed);
+        if (equalsIndex >= 0)
+            return NormalizeXamlMarkupValue(trimmed[(equalsIndex + 1)..].ToString());
+
+        return NormalizeXamlMarkupValue(trimmed.ToString());
+    }
+
+    private static int FindTopLevelMarkupPayloadStart(string value) => FindTopLevelMarkupPayloadStart(value.AsSpan());
+
+    private static int FindTopLevelMarkupPayloadStart(ReadOnlySpan<char> value)
+    {
+        var braceDepth = 0;
+        for (var i = 0; i < value.Length; i++)
+        {
+            var ch = value[i];
+            if (ch == '{')
+            {
+                braceDepth++;
+                continue;
+            }
+            if (ch == '}')
+            {
+                if (braceDepth > 0)
+                    braceDepth--;
+                continue;
+            }
+            if (braceDepth == 0 && (char.IsWhiteSpace(ch) || ch == ','))
+                return i;
+        }
+
+        return -1;
+    }
+
+    private static int SkipXamlMarkupWhitespace(string value, int start) => SkipXamlMarkupWhitespace(value.AsSpan(), start);
+
+    private static int SkipXamlMarkupWhitespace(ReadOnlySpan<char> value, int start)
+    {
+        start = Math.Clamp(start, 0, value.Length);
+        while (start < value.Length && char.IsWhiteSpace(value[start]))
+            start++;
+
+        return start;
+    }
+
+    private static int FindTopLevelTypeConstructorStart(string value)
+    {
+        var braceDepth = 0;
+        var parenDepth = 0;
+        var angleDepth = 0;
+        for (var i = 0; i < value.Length; i++)
+        {
+            var ch = value[i];
+            if (ch == '{')
+            {
+                braceDepth++;
+                continue;
+            }
+            if (ch == '}')
+            {
+                if (braceDepth > 0)
+                    braceDepth--;
+                continue;
+            }
+            if (ch == '(' || ch == '<')
+            {
+                if (braceDepth == 0 && parenDepth == 0 && angleDepth == 0)
+                    return i;
+
+                if (ch == '(')
+                    parenDepth++;
+                else
+                    angleDepth++;
+                continue;
+            }
+            if (ch == ')')
+            {
+                if (parenDepth > 0)
+                    parenDepth--;
+                continue;
+            }
+            if (ch == '>')
+            {
+                if (angleDepth > 0)
+                    angleDepth--;
+                continue;
+            }
+        }
+
+        return -1;
+    }
+
+    private static int FindMatchingTypeConstructorEnd(string value, int startIndex)
+    {
+        var open = value[startIndex];
+        var close = open == '(' ? ')' : '>';
+        var depth = 0;
+        var braceDepth = 0;
+        for (var i = startIndex; i < value.Length; i++)
+        {
+            var ch = value[i];
+            if (ch == '{')
+            {
+                braceDepth++;
+                continue;
+            }
+            if (ch == '}')
+            {
+                if (braceDepth > 0)
+                    braceDepth--;
+                continue;
+            }
+            if (braceDepth > 0)
+                continue;
+
+            if (ch == open)
+            {
+                depth++;
+                continue;
+            }
+            if (ch == close)
+            {
+                depth--;
+                if (depth == 0)
+                    return i;
+            }
+        }
+
+        return -1;
+    }
+
+    private static int IndexOfTopLevelEquals(string value) => IndexOfTopLevelEquals(value.AsSpan());
+
+    private static int IndexOfTopLevelEquals(ReadOnlySpan<char> value)
+    {
+        var braceDepth = 0;
+        for (var i = 0; i < value.Length; i++)
+        {
+            var ch = value[i];
+            if (ch == '{')
+            {
+                braceDepth++;
+                continue;
+            }
+            if (ch == '}')
+            {
+                if (braceDepth > 0)
+                    braceDepth--;
+                continue;
+            }
+            if (braceDepth == 0 && ch == '=')
+                return i;
+        }
+
+        return -1;
+    }
+
+    private static IEnumerable<string> SplitTopLevelMarkupArguments(string value)
+    {
+        var braceDepth = 0;
+        char? quote = null;
+        var start = 0;
+        for (var i = 0; i < value.Length; i++)
+        {
+            var ch = value[i];
+            if (quote is { } activeQuote)
+            {
+                if (ch == activeQuote)
+                    quote = null;
+                continue;
+            }
+            if (ch is '"' or '\'')
+            {
+                quote = ch;
+                continue;
+            }
+            if (ch == '{')
+            {
+                braceDepth++;
+                continue;
+            }
+            if (ch == '}')
+            {
+                if (braceDepth > 0)
+                    braceDepth--;
+                continue;
+            }
+            if (braceDepth == 0 && ch == ',')
+            {
+                var segment = value.AsSpan(start, i - start).Trim();
+                if (!segment.IsEmpty)
+                    yield return segment.ToString();
+                start = i + 1;
+            }
+        }
+
+        var tail = value.AsSpan(start).Trim();
+        if (!tail.IsEmpty)
+            yield return tail.ToString();
+    }
+
+    private static IEnumerable<string> SplitTopLevelTypeArguments(string value)
+    {
+        var braceDepth = 0;
+        var parenDepth = 0;
+        var angleDepth = 0;
+        var start = 0;
+        for (var i = 0; i < value.Length; i++)
+        {
+            var ch = value[i];
+            if (ch == '{')
+            {
+                braceDepth++;
+                continue;
+            }
+            if (ch == '}')
+            {
+                if (braceDepth > 0)
+                    braceDepth--;
+                continue;
+            }
+            if (ch == '(')
+            {
+                parenDepth++;
+                continue;
+            }
+            if (ch == ')')
+            {
+                if (parenDepth > 0)
+                    parenDepth--;
+                continue;
+            }
+            if (ch == '<')
+            {
+                angleDepth++;
+                continue;
+            }
+            if (ch == '>')
+            {
+                if (angleDepth > 0)
+                    angleDepth--;
+                continue;
+            }
+            if (braceDepth == 0 && parenDepth == 0 && angleDepth == 0 && ch == ',')
+            {
+                var segment = value.AsSpan(start, i - start).Trim();
+                if (!segment.IsEmpty)
+                    yield return segment.ToString();
+                start = i + 1;
+            }
+        }
+
+        var tail = value.AsSpan(start).Trim();
+        if (!tail.IsEmpty)
+            yield return tail.ToString();
+    }
+
+    private static int FindMatchingBrace(string value, int startIndex) => FindMatchingBrace(value.AsSpan(), startIndex);
+
+    private static int FindMatchingBrace(ReadOnlySpan<char> value, int startIndex)
+    {
+        var braceDepth = 0;
+        for (var i = startIndex; i < value.Length; i++)
+        {
+            var ch = value[i];
+            if (ch == '{')
+            {
+                braceDepth++;
+                continue;
+            }
+            if (ch == '}')
+            {
+                braceDepth--;
+                if (braceDepth == 0)
+                    return i;
+            }
+        }
+
+        return -1;
+    }
+
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Xml.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Xml.cs
new file mode 100644
index 000000000..45598f9be
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Xml.cs
@@ -0,0 +1,282 @@
+using System.Text;
+using System.Text.RegularExpressions;
+using Regex = CodeIndex.Indexer.BoundedRegex;
+using System.Runtime.CompilerServices;
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+
+    private static List<SymbolRecord> ExtractXmlSymbols(long fileId, string rawText, string[] lines)
+    {
+        if (!XamlReferenceExtractor.IsXaml(lines))
+            return ExtractGenericXmlSymbols(fileId, rawText, lines);
+        if (!MayContainXamlSymbolMarkers(lines))
+            return [];
+
+        if (TryGetXmlStructureIssue(rawText, out _))
+            return [];
+
+        int[]? lineStarts = null;
+
+        var symbols = CreateSymbolListForLines(lines.Length);
+        for (var i = 0; i < lines.Length; i++)
+        {
+            var line = lines[i];
+            var hasAttributeAssignment = line.IndexOf('=') >= 0;
+            string? signature = null;
+            string Signature() => signature ??= line.Trim();
+
+            if (hasAttributeAssignment && line.Contains("x:Class", StringComparison.Ordinal))
+            {
+                foreach (Match classMatch in Regex.EnumerateMatches(XamlClassRegex, line))
+                {
+                    var value = classMatch.Groups["value"].ValueSpan.Trim().ToString();
+                    if (value.Length == 0)
+                        continue;
+                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "class",
+                        Name = value,
+                        Line = i + 1,
+                        StartLine = i + 1,
+                        EndLine = i + 1,
+                        Signature = Signature(),
+                    }))
+                        continue;
+
+                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
+                }
+            }
+
+            if (hasAttributeAssignment && line.Contains("x:DataType", StringComparison.Ordinal))
+            {
+                foreach (Match dataTypeMatch in Regex.EnumerateMatches(XamlDataTypeRegex, line))
+                {
+                    var value = NormalizeXamlKeyValue(dataTypeMatch.Groups["value"].Value);
+                    if (value.Length == 0)
+                        continue;
+                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "class",
+                        Name = value,
+                        Line = i + 1,
+                        StartLine = i + 1,
+                        EndLine = i + 1,
+                        Signature = Signature(),
+                    }))
+                        continue;
+
+                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
+                }
+            }
+
+            if (hasAttributeAssignment && line.Contains("x:TypeArguments", StringComparison.Ordinal))
+            {
+                foreach (Match typeArgumentsMatch in Regex.EnumerateMatches(XamlTypeArgumentsRegex, line))
+                {
+                    foreach (var value in NormalizeXamlTypeArgumentsValue(typeArgumentsMatch.Groups["value"].Value))
+                    {
+                        if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                        {
+                            FileId = fileId,
+                            Kind = "class",
+                            Name = value,
+                            Line = i + 1,
+                            StartLine = i + 1,
+                            EndLine = i + 1,
+                            Signature = Signature(),
+                        }))
+                            continue;
+
+                        return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
+                    }
+                }
+            }
+
+            if (hasAttributeAssignment && line.Contains("TargetType", StringComparison.Ordinal))
+            {
+                foreach (Match targetTypeMatch in Regex.EnumerateMatches(XamlTargetTypeRegex, line))
+                {
+                    var value = NormalizeXamlKeyValue(targetTypeMatch.Groups["value"].Value);
+                    if (value.Length == 0)
+                        continue;
+                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "class",
+                        Name = value,
+                        Line = i + 1,
+                        StartLine = i + 1,
+                        EndLine = i + 1,
+                        Signature = Signature(),
+                    }))
+                        continue;
+
+                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
+                }
+            }
+
+            if (hasAttributeAssignment && line.Contains("x:Name", StringComparison.Ordinal))
+            {
+                foreach (Match nameMatch in Regex.EnumerateMatches(XamlNameRegex, line))
+                {
+                    var value = nameMatch.Groups["value"].ValueSpan.Trim().ToString();
+                    if (value.Length == 0)
+                        continue;
+                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "property",
+                        Name = value,
+                        Line = i + 1,
+                        StartLine = i + 1,
+                        EndLine = i + 1,
+                        Signature = Signature(),
+                    }))
+                        continue;
+
+                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
+                }
+            }
+
+            if (hasAttributeAssignment && line.Contains("x:Key", StringComparison.Ordinal))
+            {
+                foreach (Match keyMatch in Regex.EnumerateMatches(XamlKeyRegex, line))
+                {
+                    var value = NormalizeXamlKeyValue(keyMatch.Groups["value"].Value);
+                    if (value.Length == 0)
+                        continue;
+                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "property",
+                        Name = value,
+                        Line = i + 1,
+                        StartLine = i + 1,
+                        EndLine = i + 1,
+                        Signature = Signature(),
+                    }))
+                        continue;
+
+                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
+                }
+            }
+
+            if (MayContainXamlEventHandlerAttribute(line))
+            {
+                foreach (Match handlerMatch in Regex.EnumerateMatches(XamlEventHandlerRegex, line))
+                {
+                    var value = handlerMatch.Groups["value"].ValueSpan.Trim().ToString();
+                    if (value.Length == 0)
+                        continue;
+                    if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                    {
+                        FileId = fileId,
+                        Kind = "function",
+                        Name = value,
+                        Line = i + 1,
+                        StartLine = i + 1,
+                        EndLine = i + 1,
+                        Signature = Signature(),
+                    }))
+                        continue;
+
+                    return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
+                }
+            }
+        }
+
+        if (symbols.Count < StructuredDataMaxSymbols
+            && rawText.Contains("x:TypeArguments", StringComparison.Ordinal))
+        {
+            AddWrappedXamlTypeArgumentSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && MayContainWrappedXamlTypeBearingAttribute(rawText))
+        {
+            AddWrappedXamlTypeBearingAttributeSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && MayContainWrappedXamlSearchAttribute(rawText))
+        {
+            AddWrappedXamlSearchAttributeSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && rawText.Contains("x:Type", StringComparison.Ordinal)
+            && rawText.Contains("TypeName", StringComparison.Ordinal))
+        {
+            AddXamlTypeObjectElementSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && rawText.Contains(".TypeName", StringComparison.Ordinal))
+        {
+            AddXamlTypePropertyElementSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && rawText.Contains("{x:Type", StringComparison.Ordinal))
+        {
+            AddXamlTypeMarkupSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && rawText.Contains("{x:Static", StringComparison.Ordinal))
+        {
+            AddXamlStaticMemberTypeSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && MayContainXamlReferenceSymbol(rawText))
+        {
+            AddXamlReferenceSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && TextContainsAny(rawText, XamlResourceReferenceMarkupPrefixes))
+        {
+            AddXamlResourceReferenceSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && MayContainXamlBindingElementNameSymbol(rawText))
+        {
+            AddXamlBindingElementNameSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+        if (symbols.Count < StructuredDataMaxSymbols
+            && MayContainXamlBindingObjectElementSymbol(rawText))
+        {
+            AddXamlBindingObjectElementSymbols(fileId, rawText, lines, lineStarts ??= BuildLineStarts(lines), symbols);
+        }
+
+        if (symbols.Count <= StructuredDataMaxSymbols
+            && MayContainXamlBindingMarkup(rawText))
+        {
+            foreach (Match bindingMatch in Regex.EnumerateMatches(XamlBindingRegex, rawText))
+            {
+                var value = NormalizeXamlBindingValue(bindingMatch.Groups["kind"].Value, bindingMatch.Groups["content"].Value);
+                if (value.Length == 0)
+                    continue;
+
+                var currentLineStarts = lineStarts ??= BuildLineStarts(lines);
+                var startLine = FindHtmlLineNumber(currentLineStarts, bindingMatch.Index);
+                var signatureIndex = Math.Clamp(startLine - 1, 0, lines.Length - 1);
+                if (TryAddBoundedStructuredDataSymbol(symbols, new SymbolRecord
+                {
+                    FileId = fileId,
+                    Kind = "property",
+                    Name = value,
+                    Line = startLine,
+                    StartLine = startLine,
+                    EndLine = startLine,
+                    Signature = lines[signatureIndex].Trim(),
+                }))
+                    continue;
+
+                return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
+            }
+        }
+
+        return TrimStructuredDataSymbols(symbols, fileId, "structured_data_xml_symbol_budget_exceeded", lines);
+    }
+
+}

From 257fd0ff106070acab9593f5c38571bf4963a54c Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 02:52:41 +0900
Subject: [PATCH 02/45] Refactor MCP tool catalog into families

---
 src/CodeIndex/Mcp/McpToolCatalog.cs | 68 +++++++++++++++++++++++++----
 1 file changed, 60 insertions(+), 8 deletions(-)

diff --git a/src/CodeIndex/Mcp/McpToolCatalog.cs b/src/CodeIndex/Mcp/McpToolCatalog.cs
index 606fa8155..a252d3a2b 100644
--- a/src/CodeIndex/Mcp/McpToolCatalog.cs
+++ b/src/CodeIndex/Mcp/McpToolCatalog.cs
@@ -17,8 +17,29 @@ private static JsonArray CreateLanguageCapabilityEnum()
 
     private static JsonArray CreateToolCatalog()
     {
-        var tools = new JsonArray
-        {
+        var tools = new JsonArray();
+        AddToolDefinitions(tools, CreateQueryAndDiscoveryTools());
+        AddToolDefinitions(tools, CreateGraphAndAnalysisTools());
+        AddToolDefinitions(tools, CreateWorkspaceInspectionTools());
+        AddToolDefinitions(tools, CreateProtocolUtilityTools());
+        AddToolDefinitions(tools, CreateIndexMaintenanceTools());
+        AddToolDefinitions(tools, CreateAuditAndFeedbackTools());
+
+        AddProjectScopeProperties(tools);
+        AddCommonSchemaConstraints(tools);
+        return tools;
+    }
+
+    private static void AddToolDefinitions(JsonArray catalog, JsonObject[] definitions)
+    {
+        foreach (var definition in definitions)
+            catalog.Add(definition);
+    }
+
+    private static JsonObject[] CreateQueryAndDiscoveryTools()
+    {
+        return
+        [
             CreateToolDefinition(
                 "search",
                 "Use this when starting broad code discovery, checking error text, or running named search audit recipes. Prefer it before shell grep; common next step is `excerpt`, `definition`, or `references` on the best hit. Returns snippets plus `result_stable_at`, `next_cursor`, and `next_step_suggestion` or `recovery_hint`. Use `prefix`/trailing `*` to widen token matching, `rawQuery` for FTS5 syntax, `exactSubstring` for case-sensitive identity, and `tokenBoundary` when a code phrase must not match inside longer identifiers. Details and examples: USER_GUIDE.md#search. / 広いコード調査、エラー文言確認、search audit recipe 実行の起点に使う。shell grep より優先し、次は最有力ヒットに `excerpt` / `definition` / `references` を使う。`prefix` / 末尾 `*` / `rawQuery` / `exactSubstring` / `tokenBoundary` の詳細と例は USER_GUIDE.md#search を参照。",
@@ -350,6 +371,13 @@ private static JsonArray CreateToolCatalog()
                     ["required"] = new JsonArray { "query", "path" }
                 },
                 ReadOnlyAnnotations()),
+        ];
+    }
+
+    private static JsonObject[] CreateGraphAndAnalysisTools()
+    {
+        return
+        [
             CreateToolDefinition(
                 "map",
                 "Use this when orienting in an unfamiliar repo, module, language mix, or hotspot area before searching. Prefer `search`, `symbols`, `outline`, or `excerpt` as the next step after choosing a path. Return a repo-level overview with selectable sections (`tree`, `languages`, `hotspots`, `metrics`) and optional module depth control. / 不慣れなリポジトリ、モジュール、言語構成、hotspot 領域を search 前に把握するときに使う。path を選んだ後は `search` / `symbols` / `outline` / `excerpt` を優先する。セクション選択（`tree`, `languages`, `hotspots`, `metrics`）とモジュール深さ制御に対応したリポジトリ俯瞰情報を返す。",
@@ -419,6 +447,13 @@ private static JsonArray CreateToolCatalog()
                     ["required"] = new JsonArray { "query" }
                 },
                 ReadOnlyAnnotations()),
+        ];
+    }
+
+    private static JsonObject[] CreateWorkspaceInspectionTools()
+    {
+        return
+        [
             CreateToolDefinition(
                 "status",
                 "Get database statistics, readiness state, and optional CLI-style freshness checks. Use `check`, `scopes`, `staleAfterSeconds`, `explain`, `config`, `logPath`, `format`, or `fields` for bounded health-check views. / DB統計、readiness 状態、必要に応じて CLI 風の freshness check を取得。`check` / `scopes` / `staleAfterSeconds` / `explain` / `config` / `logPath` / `format` / `fields` で health-check 用の出力に絞り込める。",
@@ -577,6 +612,13 @@ private static JsonArray CreateToolCatalog()
                     }
                 },
                 ReadOnlyAnnotations()),
+        ];
+    }
+
+    private static JsonObject[] CreateProtocolUtilityTools()
+    {
+        return
+        [
             CreateToolDefinition(
                 "ping",
                 "Lightweight connection check. Returns server version and timestamp. No database required. / 軽量接続チェック。サーバーバージョンとタイムスタンプを返す。DB不要。",
@@ -619,6 +661,13 @@ private static JsonArray CreateToolCatalog()
                     ["required"] = new JsonArray { "queries" }
                 },
                 ReadOnlyAnnotations()),
+        ];
+    }
+
+    private static JsonObject[] CreateIndexMaintenanceTools()
+    {
+        return
+        [
             CreateToolDefinition(
                 "index",
                 "Index or re-index a project directory. Scans source files, extracts symbols, and builds FTS5 search index. On transports that can carry out-of-band server messages (stdio, and HTTP clients connected to `/events`), when the tools/call request includes a bounded scalar/object `_meta.progressToken`, this tool emits `notifications/progress` with that token while scanning, indexing, and finalizing; oversized or unsupported tokens are ignored instead of echoed. / プロジェクトディレクトリをインデックス（再インデックス）。ソースファイルをスキャンし、シンボルを抽出してFTS5検索インデックスを構築。out-of-band のサーバーメッセージを送れる transport（stdio、および `/events` に接続した HTTP クライアント）では、tools/call リクエストに bounded scalar/object の `_meta.progressToken` が含まれる場合、スキャン・インデックス・finalize 中に同じ token の `notifications/progress` を送信し、上限超過または未対応 token は echo せず無視する。",
@@ -660,6 +709,13 @@ private static JsonArray CreateToolCatalog()
                     }
                 },
                 IndexAnnotations()),
+        ];
+    }
+
+    private static JsonObject[] CreateAuditAndFeedbackTools()
+    {
+        return
+        [
             CreateToolDefinition(
                 "symbol_hotspots",
                 "Find the most-referenced symbols in the codebase (hotspot analysis). "
@@ -742,11 +798,7 @@ private static JsonArray CreateToolCatalog()
                     },
                     ["required"] = new JsonArray { "category", "description" }
                 },
-                SuggestionAnnotations())
-        };
-
-        AddProjectScopeProperties(tools);
-        AddCommonSchemaConstraints(tools);
-        return tools;
+                SuggestionAnnotations()),
+        ];
     }
 }

From f283dee8f19043e920f3f2f23605834be882fd8b Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 03:41:27 +0900
Subject: [PATCH 03/45] Consolidate C# base-list parsing

---
 TESTING_GUIDE.md                              |   6 +-
 .../+csharp-base-list-parser.fixed.md         |  16 ++
 .../Database/CSharpBaseListParser.cs          | 261 ++++++++++++++++++
 .../Database/DbContext.ConnectionFunctions.cs |   2 +-
 .../Database/DbReader.CSharpResolution.cs     | 132 +--------
 .../DbWriter.CSharpMetadataTargets.cs         | 145 +---------
 .../CSharpBaseListParserTests.cs              | 115 ++++++++
 7 files changed, 408 insertions(+), 269 deletions(-)
 create mode 100644 changelog.d/unreleased/+csharp-base-list-parser.fixed.md
 create mode 100644 src/CodeIndex/Database/CSharpBaseListParser.cs
 create mode 100644 tests/CodeIndex.Tests/CSharpBaseListParserTests.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 548c23c1e..0c8d15c95 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -186,8 +186,9 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   Cross-language taxonomy coverage requires every declared symbol and reference kind to be unique and accepted by the exact Ordinal lookup, while null, empty, whitespace-only, case variants, trailing-space variants, and unknown values remain rejected. Keep the writer's unknown symbol/reference and container-kind diagnostics, schema/catalog parity, and pattern-sidecar invalid-kind rejection in the same focused validation set.
   `DbSchemaConstraintTests` runs the public-array mutation regression in the non-parallel SQLite-sensitive collection and restores both arrays in `finally`. It must prove that writer validation and newly generated symbol/reference CHECK clauses continue to use the same private canonical taxonomy while the compatibility arrays are visibly mutated.
   Do not put a timing assertion in this test class. When a static lookup replay is useful, keep its Release harness temporary, feed the same persisted kind/count distribution to the legacy and candidate lookups, alternate execution order, and remove it before committing. The normal empty-database full-index A/B remains authoritative for the user-visible performance decision.
-- `DatabaseTests.cs`, `DatabasePermissionPolicyTests.cs`, `DbReader*Tests.cs`
+- `DatabaseTests.cs`, `DatabasePermissionPolicyTests.cs`, `DbReader*Tests.cs`, `CSharpBaseListParserTests.cs`
   SQLite schema, write paths, migrations, and query behavior. DbReader coverage is split by query family, including search, SQL qualified-name handling, file dependencies, impact, and symbol-query suites, while shared seeded fixture state remains on the root `DbReaderTests` part.
+  `CSharpBaseListParserTests` keeps the SQLite-free base-list grammar matrix together, including generic constraints, nested generic/tuple/array syntax, alias qualifiers, primary/base constructors, declaration terminators, and the distinct reader type-reference and metadata head-identifier projections.
   Maintenance-lookup coverage keeps the `files(checksum)`, `files(path COLLATE NOCASE)`, and `file_issues(file_id, kind)` indexes aligned with their predicates and requires `EXPLAIN QUERY PLAN` index `SEARCH` operations for checksum purge, ASCII case-alias lookup, reusable-stat issue probes, and directory/stem rename candidates. The case-alias fixture uses changed content so checksum cannot hide a missing path lookup, and managed validation remains authoritative because SQLite `NOCASE` is only an ASCII prefilter, not a Unicode casing contract. Keep wildcard-bearing, extensionless, and near-match stem semantics in one fixture. Scoped-cleanup planning coverage unions checksum and exact same-directory/stem candidates into ascending deduplicated ID snapshots, merges overlapping plans, proves apply does not absorb matching rows added after planning, and rereads planned IDs immediately before apply so a deleted C# contract that reappears is deferred until a clean retry. The grouped C# fixture gives many targets one common checksum/stem and requires candidate-reader work to grow with unique keys plus returned rows rather than target-count squared; it also asserts that C# pre-workspace planning never deletes matching non-C# rows.
   Reference-resolution lookup coverage keeps the exact fresh-schema and read-migration index sets aligned for file/name, retained folded/NOCASE composite prefixes, resolved reverse edges, and the partial unresolved-mutual path. Assert the absence of all six retired single-prefix indexes plus the former all-row mutual index after migration and reopen, exact column order/collation/partial predicates, and `EXPLAIN QUERY PLAN` `SEARCH` operations for both full and scoped mutual SQL. Preserve fold-ready and legacy-fallback CLI/MCP exact-query signals, and rerun the same-name/different-container plus partial-class-over-same-file ranking fixtures when these indexes change.
   Repository-metadata graph coverage indexes TOML local paths and application-manifest assembly dependencies through the normal writer, then requires explicit `project_reference` / `dependency` caller queries so capability advertising cannot drift from persisted graph behavior.
@@ -1244,8 +1245,9 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   全言語共通の taxonomy coverage では、宣言済みの全 symbol / reference kind が重複せず、完全一致の Ordinal lookup で受理されることを必須とします。null、空文字、空白のみ、case 違い、末尾空白、未知の値は引き続き拒否してください。writer の未知 symbol/reference kind と container kind の診断、schema/catalog parity、pattern sidecar の invalid-kind 拒否も同じ focused validation set で維持します。
   `DbSchemaConstraintTests` の公開 array mutation 回帰は、並列実行しない SQLite-sensitive collection で実行し、`finally` で両 array を復元します。互換 array の変更が実際に見える間も、writer validation と新規生成する symbol / reference CHECK 句が同じ private canonical taxonomy を使い続けることを必須とします。
   この test class に timing assertion を追加してはいけません。static lookup replay が有用な場合は Release harness を一時的なものに限定し、同一の保存済み kind/count 分布を旧来経路と候補経路へ流し、実行順を交互にしたうえで commit 前に削除します。ユーザーに見える性能の採否は、通常の空 database full-index A/B を authoritative としてください。
-- `DatabaseTests.cs`、`DatabasePermissionPolicyTests.cs`、`DbReader*Tests.cs`
+- `DatabaseTests.cs`、`DatabasePermissionPolicyTests.cs`、`DbReader*Tests.cs`、`CSharpBaseListParserTests.cs`
   SQLite スキーマ、書き込み経路、マイグレーション、クエリ挙動のテスト。DbReader のカバレッジは search、SQL qualified name、file dependency、impact、symbol query などの query family ごとの partial suite に分割し、共有の seed 済み fixture 状態は root 側の `DbReaderTests` に残します。
+  `CSharpBaseListParserTests` には SQLite を使わない base-list 構文 matrix をまとめ、generic constraint、nested generic / tuple / array、alias qualifier、primary / base constructor、宣言終端、および reader の type-reference 投影と metadata の head-identifier 投影の差を固定します。
   maintenance lookup の coverage では `files(checksum)`、`files(path COLLATE NOCASE)`、`file_issues(file_id, kind)` の index を predicate と同期させ、checksum purge、ASCII case-alias lookup、再利用 stat の issue probe、directory/stem rename 候補が `EXPLAIN QUERY PLAN` で index `SEARCH` を使うことを必須とします。case-alias fixture は checksum で path lookup の欠落が隠れないよう content も変更し、SQLite `NOCASE` は Unicode casing contract ではなく ASCII prefilter にすぎないため managed 検証を authoritative に保ちます。wildcard を含む stem、拡張子なし、近似 stem の意味論は1つの fixture にまとめます。scoped cleanup planning の coverage では checksum と正確な同一 directory/stem の候補を昇順・重複排除済み ID snapshot に統合し、重複 plan の merge、plan 後に追加された一致 row を apply が取り込まないこと、apply 直前に planned ID を再読込して再出現した C# contract を clean retry まで延期することを固定します。grouped C# fixture は多数の target に共通 checksum/stem を与え、candidate reader の処理量が target 数の二乗ではなく unique key 数と返却 row 数に比例すること、および C# workspace 前の plan が一致する non-C# row を削除しないことを要求します。
   参照解決 lookup の coverage では fresh schema / read migration の正確な index setを、file/name、保持したfolded/NOCASE composite prefix、解決済み逆辺、未解決mutual用partial pathまで同期させます。migrationと再open後に退役したsingle-prefix 6本と旧全row mutual indexが存在しないこと、列順・collation・partial predicateを厳密に検証し、full/scoped mutual SQLの両方で`EXPLAIN QUERY PLAN`のindex `SEARCH`を必須とします。fold-ready/legacy fallback双方のCLI/MCP exact-query signalを維持し、これらのindexを変える際は同名・別containerとpartial classが同一file候補より優先される既存ranking fixtureも再実行してください。
   repository metadata の graph coverage では TOML の local path と application manifest の assembly dependency を通常 writer 経由で index し、明示的な `project_reference` / `dependency` caller query を必須にして capability 広告と永続化済み graph のずれを防いでください。
diff --git a/changelog.d/unreleased/+csharp-base-list-parser.fixed.md b/changelog.d/unreleased/+csharp-base-list-parser.fixed.md
new file mode 100644
index 000000000..ef5bef604
--- /dev/null
+++ b/changelog.d/unreleased/+csharp-base-list-parser.fixed.md
@@ -0,0 +1,16 @@
+---
+category: fixed
+affected:
+  - src/CodeIndex/Database/CSharpBaseListParser.cs
+  - src/CodeIndex/Database/DbContext.ConnectionFunctions.cs
+  - src/CodeIndex/Database/DbReader.CSharpResolution.cs
+  - src/CodeIndex/Database/DbWriter.CSharpMetadataTargets.cs
+---
+
+## English
+
+- **C# inheritance resolution now shares one grammar-aware base-list parser** — exact caller and metadata-target resolution no longer confuse generic `where` constraints with base types, and nested generics, tuples, arrays, alias qualifiers, and primary/base-constructor syntax are split consistently.
+
+## 日本語
+
+- **C# 継承解決が grammar-aware な base-list parser を共有するようになりました** — exact caller と metadata-target の解決で generic `where` constraint を基底型と誤認せず、nested generic、tuple、array、alias qualifier、primary / base constructor 構文を一貫して分割します。
diff --git a/src/CodeIndex/Database/CSharpBaseListParser.cs b/src/CodeIndex/Database/CSharpBaseListParser.cs
new file mode 100644
index 000000000..fdf0fe4b1
--- /dev/null
+++ b/src/CodeIndex/Database/CSharpBaseListParser.cs
@@ -0,0 +1,261 @@
+namespace CodeIndex.Database;
+
+internal enum CSharpBaseListProjection
+{
+    // DbReader resolves the complete type expression, including generic arguments.
+    TypeReference,
+
+    // Metadata propagation needs only the qualified type name before generic/constructor syntax.
+    HeadIdentifier,
+}
+
+internal static class CSharpBaseListParser
+{
+    internal static List<string> Parse(string? signature, CSharpBaseListProjection projection)
+    {
+        var result = new List<string>();
+        if (string.IsNullOrWhiteSpace(signature))
+            return result;
+
+        var colonIndex = FindBaseListColon(signature);
+        if (colonIndex < 0)
+            return result;
+
+        var state = new ScanState();
+        var entryStart = colonIndex + 1;
+        for (var i = entryStart; i < signature.Length; i++)
+        {
+            if (!state.IsCodeCharacter(signature, ref i))
+                continue;
+
+            var ch = signature[i];
+            if (state.IsTopLevel)
+            {
+                if (ch is '{' or ';')
+                {
+                    AddProjectedEntry(result, signature[entryStart..i], projection);
+                    return result;
+                }
+
+                if (ch == ',')
+                {
+                    AddProjectedEntry(result, signature[entryStart..i], projection);
+                    entryStart = i + 1;
+                    continue;
+                }
+
+                if (IsWhereKeyword(signature, i))
+                {
+                    AddProjectedEntry(result, signature[entryStart..i], projection);
+                    return result;
+                }
+            }
+
+            state.UpdateDelimiterDepth(ch);
+        }
+
+        AddProjectedEntry(result, signature[entryStart..], projection);
+        return result;
+    }
+
+    private static int FindBaseListColon(string signature)
+    {
+        var state = new ScanState();
+        for (var i = 0; i < signature.Length; i++)
+        {
+            if (!state.IsCodeCharacter(signature, ref i))
+                continue;
+
+            var ch = signature[i];
+            if (state.IsTopLevel)
+            {
+                if (ch is '{' or ';' || IsWhereKeyword(signature, i))
+                    return -1;
+
+                if (ch == ':' && !IsAliasQualifierColon(signature, i))
+                    return i;
+            }
+
+            state.UpdateDelimiterDepth(ch);
+        }
+
+        return -1;
+    }
+
+    private static bool IsAliasQualifierColon(string signature, int index)
+    {
+        return (index > 0 && signature[index - 1] == ':')
+            || (index + 1 < signature.Length && signature[index + 1] == ':');
+    }
+
+    private static bool IsWhereKeyword(string signature, int index)
+    {
+        const string Keyword = "where";
+        if (index + Keyword.Length > signature.Length
+            || !signature.AsSpan(index, Keyword.Length).SequenceEqual(Keyword))
+        {
+            return false;
+        }
+
+        if (index > 0 && IsIdentifierPart(signature[index - 1]))
+            return false;
+
+        return index + Keyword.Length >= signature.Length
+            || !IsIdentifierPart(signature[index + Keyword.Length]);
+    }
+
+    private static bool IsIdentifierPart(char ch)
+    {
+        return char.IsLetterOrDigit(ch) || ch is '_' or '@';
+    }
+
+    private static void AddProjectedEntry(List<string> result, string rawEntry, CSharpBaseListProjection projection)
+    {
+        var entry = rawEntry.Trim();
+        if (entry.Length == 0)
+            return;
+
+        if (projection == CSharpBaseListProjection.TypeReference)
+        {
+            result.Add(entry);
+            return;
+        }
+
+        if (projection != CSharpBaseListProjection.HeadIdentifier)
+            throw new ArgumentOutOfRangeException(nameof(projection), projection, null);
+
+        var cut = entry.Length;
+        for (var i = 0; i < entry.Length; i++)
+        {
+            var ch = entry[i];
+            if (ch is '<' or '(' || char.IsWhiteSpace(ch))
+            {
+                cut = i;
+                break;
+            }
+        }
+
+        if (cut > 0)
+            result.Add(entry[..cut]);
+    }
+
+    private struct ScanState
+    {
+        private int _angleDepth;
+        private int _parenDepth;
+        private int _squareDepth;
+        private char _quote;
+        private bool _escaped;
+        private bool _verbatimString;
+        private bool _lineComment;
+        private bool _blockComment;
+
+        internal readonly bool IsTopLevel => _angleDepth == 0 && _parenDepth == 0 && _squareDepth == 0;
+
+        internal bool IsCodeCharacter(string text, ref int index)
+        {
+            var ch = text[index];
+            if (_lineComment)
+            {
+                if (ch is '\r' or '\n')
+                    _lineComment = false;
+                return false;
+            }
+
+            if (_blockComment)
+            {
+                if (ch == '*' && index + 1 < text.Length && text[index + 1] == '/')
+                {
+                    _blockComment = false;
+                    index++;
+                }
+                return false;
+            }
+
+            if (_quote != '\0')
+            {
+                if (_escaped)
+                {
+                    _escaped = false;
+                    return false;
+                }
+
+                if (!_verbatimString && ch == '\\')
+                {
+                    _escaped = true;
+                    return false;
+                }
+
+                if (_verbatimString && ch == '"' && index + 1 < text.Length && text[index + 1] == '"')
+                {
+                    index++;
+                    return false;
+                }
+
+                if (ch == _quote)
+                {
+                    _quote = '\0';
+                    _verbatimString = false;
+                }
+                return false;
+            }
+
+            if (ch == '/' && index + 1 < text.Length)
+            {
+                if (text[index + 1] == '/')
+                {
+                    _lineComment = true;
+                    index++;
+                    return false;
+                }
+
+                if (text[index + 1] == '*')
+                {
+                    _blockComment = true;
+                    index++;
+                    return false;
+                }
+            }
+
+            if (ch is '"' or '\'')
+            {
+                _quote = ch;
+                _verbatimString = ch == '"'
+                    && ((index > 0 && text[index - 1] == '@')
+                        || (index > 1 && text[index - 2] == '@' && text[index - 1] == '$'));
+                return false;
+            }
+
+            return true;
+        }
+
+        internal void UpdateDelimiterDepth(char ch)
+        {
+            switch (ch)
+            {
+                case '<':
+                    if (_parenDepth == 0 && _squareDepth == 0)
+                        _angleDepth++;
+                    break;
+                case '>':
+                    if (_parenDepth == 0 && _squareDepth == 0 && _angleDepth > 0)
+                        _angleDepth--;
+                    break;
+                case '(':
+                    _parenDepth++;
+                    break;
+                case ')':
+                    if (_parenDepth > 0)
+                        _parenDepth--;
+                    break;
+                case '[':
+                    _squareDepth++;
+                    break;
+                case ']':
+                    if (_squareDepth > 0)
+                        _squareDepth--;
+                    break;
+            }
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbContext.ConnectionFunctions.cs b/src/CodeIndex/Database/DbContext.ConnectionFunctions.cs
index b33e80a8c..c9b321681 100644
--- a/src/CodeIndex/Database/DbContext.ConnectionFunctions.cs
+++ b/src/CodeIndex/Database/DbContext.ConnectionFunctions.cs
@@ -186,7 +186,7 @@ private static void RegisterConnectionFunctionsCore(SqliteConnection connection)
             "csharp_base_identifiers_json",
             (string? signature) =>
                 JsonSerializer.Serialize(
-                    DbWriter.ParseCSharpBaseIdentifiers(signature),
+                    CSharpBaseListParser.Parse(signature, CSharpBaseListProjection.HeadIdentifier),
                     CliJsonSerializerContext.Default.ListString));
         connection.CreateFunction(
             "csharp_base_name_folded",
diff --git a/src/CodeIndex/Database/DbReader.CSharpResolution.cs b/src/CodeIndex/Database/DbReader.CSharpResolution.cs
index de9cb6899..ce3a11fe9 100644
--- a/src/CodeIndex/Database/DbReader.CSharpResolution.cs
+++ b/src/CodeIndex/Database/DbReader.CSharpResolution.cs
@@ -267,7 +267,10 @@ private static void AddCSharpBaseListDispatchNamesFromSignature(string containin
         if (lastDot > 0)
             namespacePrefix = containingTypeName[..lastDot];
 
-        foreach (var baseTypeReference in ParseCSharpBaseTypeReferences(signature))
+        var baseTypeReferences = CSharpBaseListParser.Parse(
+            signature,
+            CSharpBaseListProjection.TypeReference);
+        foreach (var baseTypeReference in baseTypeReferences)
         {
             var normalizedBase = NormalizeCSharpBaseTypeReference(baseTypeReference);
             if (string.IsNullOrWhiteSpace(normalizedBase))
@@ -312,7 +315,9 @@ private List<CSharpContainingTypeScope> ResolveDirectCSharpInheritedContainingTy
         if (containingTypeScope.Kind is not ("class" or "struct" or "interface"))
             return [];
 
-        var baseTypeReferences = ParseCSharpBaseTypeReferences(containingTypeScope.Signature);
+        var baseTypeReferences = CSharpBaseListParser.Parse(
+            containingTypeScope.Signature,
+            CSharpBaseListProjection.TypeReference);
         if (baseTypeReferences.Count == 0)
             return [];
 
@@ -743,7 +748,9 @@ AND s.kind IN ('class', 'struct', 'interface')
         if (!string.Equals(containingTypeScope.Kind, "class", StringComparison.Ordinal))
             return null;
 
-        var baseTypeReference = ParseCSharpBaseTypeReference(containingTypeScope.Signature);
+        var baseTypeReference = CSharpBaseListParser.Parse(
+            containingTypeScope.Signature,
+            CSharpBaseListProjection.TypeReference).FirstOrDefault();
         if (string.IsNullOrWhiteSpace(baseTypeReference))
             return null;
 
@@ -824,125 +831,6 @@ AND s.kind IN ('class', 'struct', 'interface')
         return normalizedReference;
     }
 
-    private static string? ParseCSharpBaseTypeReference(string? signature)
-    {
-        var references = ParseCSharpBaseTypeReferences(signature);
-        return references.Count == 0 ? null : references[0];
-    }
-
-    private static List<string> ParseCSharpBaseTypeReferences(string? signature)
-    {
-        if (string.IsNullOrWhiteSpace(signature))
-            return [];
-
-        var text = signature.TrimEnd();
-        if (text.EndsWith("{", StringComparison.Ordinal))
-            text = text[..^1].TrimEnd();
-
-        var colonIndex = FindCSharpBaseListColonIndex(text);
-        if (colonIndex < 0)
-            return [];
-
-        var baseList = text[(colonIndex + 1)..];
-        var whereIndex = baseList.IndexOf(" where ", StringComparison.Ordinal);
-        if (whereIndex >= 0)
-            baseList = baseList[..whereIndex];
-
-        var entries = new List<string>();
-        foreach (var entry in EnumerateCSharpBaseListEntries(baseList))
-        {
-            var trimmed = entry.Trim();
-            if (trimmed.Length > 0)
-                entries.Add(trimmed);
-        }
-
-        return entries;
-    }
-
-    private static int FindCSharpBaseListColonIndex(string signature)
-    {
-        var angleDepth = 0;
-        var parenDepth = 0;
-        var squareDepth = 0;
-        for (var i = 0; i < signature.Length; i++)
-        {
-            switch (signature[i])
-            {
-                case '<':
-                    angleDepth++;
-                    break;
-                case '>':
-                    if (angleDepth > 0)
-                        angleDepth--;
-                    break;
-                case '(':
-                    parenDepth++;
-                    break;
-                case ')':
-                    if (parenDepth > 0)
-                        parenDepth--;
-                    break;
-                case '[':
-                    squareDepth++;
-                    break;
-                case ']':
-                    if (squareDepth > 0)
-                        squareDepth--;
-                    break;
-                case ':':
-                    if (angleDepth == 0 && parenDepth == 0 && squareDepth == 0)
-                        return i;
-                    break;
-            }
-        }
-
-        return -1;
-    }
-
-    private static IEnumerable<string> EnumerateCSharpBaseListEntries(string baseList)
-    {
-        var angleDepth = 0;
-        var parenDepth = 0;
-        var squareDepth = 0;
-        var start = 0;
-        for (var i = 0; i < baseList.Length; i++)
-        {
-            switch (baseList[i])
-            {
-                case '<':
-                    angleDepth++;
-                    break;
-                case '>':
-                    if (angleDepth > 0)
-                        angleDepth--;
-                    break;
-                case '(':
-                    parenDepth++;
-                    break;
-                case ')':
-                    if (parenDepth > 0)
-                        parenDepth--;
-                    break;
-                case '[':
-                    squareDepth++;
-                    break;
-                case ']':
-                    if (squareDepth > 0)
-                        squareDepth--;
-                    break;
-                case ',':
-                    if (angleDepth == 0 && parenDepth == 0 && squareDepth == 0)
-                    {
-                        yield return baseList[start..i];
-                        start = i + 1;
-                    }
-                    break;
-            }
-        }
-
-        yield return baseList[start..];
-    }
-
     private static string NormalizeCSharpBaseTypeReference(string typeReference)
     {
         if (string.IsNullOrWhiteSpace(typeReference))
diff --git a/src/CodeIndex/Database/DbWriter.CSharpMetadataTargets.cs b/src/CodeIndex/Database/DbWriter.CSharpMetadataTargets.cs
index 0b2890d9d..a8f4ef5c8 100644
--- a/src/CodeIndex/Database/DbWriter.CSharpMetadataTargets.cs
+++ b/src/CodeIndex/Database/DbWriter.CSharpMetadataTargets.cs
@@ -117,7 +117,7 @@ internal CSharpMetadataTargetResolutionStats ResolveCSharpMetadataTargetsCore(
             dependencies.Clear();
             perFileImports.TryGetValue(row.FileId, out var fileImports);
             bool directTarget = CollectMetadataTargetDependencies(
-                ParseCSharpBaseIdentifiers(row.Signature),
+                CSharpBaseListParser.Parse(row.Signature, CSharpBaseListProjection.HeadIdentifier),
                 GetEnclosingScope(row.QualifiedName, row.Name),
                 scopeNameToIds,
                 qualifiedToIds,
@@ -904,147 +904,4 @@ private static void CollectNamespaceImportDependencies(
         }
     }
 
-    /// <summary>
-    /// Extract base-type head identifiers from a C# class signature, respecting generic depth
-    /// so that `Foo<Bar, Baz> : IBase, IOther<Bar>` yields ["IBase", "IOther"]. Stops at the
-    /// first `where` clause (generic constraints are not bases) and trims modifiers like
-    /// `public sealed`.
-    /// C# class signature から基底/インターフェース識別子の頭を抜き出す。`<...>` の depth を
-    /// 数えて generic argument 内の `,` を区切りに誤認しないようにし、`where` 制約は除外する。
-    /// </summary>
-    internal static List<string> ParseCSharpBaseIdentifiers(string? signature)
-    {
-        var result = new List<string>();
-        if (string.IsNullOrEmpty(signature))
-            return result;
-
-        int colonIdx = FindBaseListColon(signature);
-        if (colonIdx < 0)
-            return result;
-
-        int start = colonIdx + 1;
-        int genericDepth = 0;
-        var current = new System.Text.StringBuilder();
-        for (int i = start; i < signature.Length; i++)
-        {
-            char c = signature[i];
-            if (c == '<')
-            {
-                genericDepth++;
-                current.Append(c);
-                continue;
-            }
-            if (c == '>')
-            {
-                if (genericDepth > 0)
-                    genericDepth--;
-                current.Append(c);
-                continue;
-            }
-            if (c == '{')
-                break;
-            if (genericDepth == 0 && c == ',')
-            {
-                AddBaseIfPresent(result, current.ToString());
-                current.Clear();
-                continue;
-            }
-            // `where T : ...` ends the base list
-            if (genericDepth == 0 && (c == 'w' || c == 'W'))
-            {
-                if (LooksLikeWhereKeyword(signature, i))
-                {
-                    AddBaseIfPresent(result, current.ToString());
-                    current.Clear();
-                    return result;
-                }
-            }
-            current.Append(c);
-        }
-        AddBaseIfPresent(result, current.ToString());
-        return result;
-    }
-
-    private static int FindBaseListColon(string signature)
-    {
-        int genericDepth = 0;
-        int parenDepth = 0;
-        for (int i = 0; i < signature.Length; i++)
-        {
-            char c = signature[i];
-            if (c == '<') { genericDepth++; continue; }
-            if (c == '>') { if (genericDepth > 0) genericDepth--; continue; }
-            if (c == '(') { parenDepth++; continue; }
-            if (c == ')') { if (parenDepth > 0) parenDepth--; continue; }
-            if (c == '{')
-                return -1;
-            // `class Foo<T> where T : IBar {}` has no base list — only a generic constraint.
-            // If we reach a top-level `where` before finding `:`, treat that `:` as a
-            // constraint separator, not a base list opener. Issue #435 codex review.
-            // `class Foo<T> where T : IBar {}` のように base list を持たない場合、ここで遭遇する
-            // `:` は generic constraint の区切りなので base list colon として採用しない。
-            if (genericDepth == 0 && parenDepth == 0 && (c == 'w' || c == 'W')
-                && LooksLikeWhereKeyword(signature, i))
-            {
-                return -1;
-            }
-            if (c == ':' && genericDepth == 0 && parenDepth == 0)
-            {
-                // Skip `::` namespace alias separator / `::` 名前空間エイリアスは除外
-                if (i + 1 < signature.Length && signature[i + 1] == ':')
-                {
-                    i++;
-                    continue;
-                }
-                if (i > 0 && signature[i - 1] == ':')
-                    continue;
-                return i;
-            }
-        }
-        return -1;
-    }
-
-    private static bool LooksLikeWhereKeyword(string signature, int i)
-    {
-        if (i + 5 > signature.Length)
-            return false;
-        if (string.Compare(signature, i, "where", 0, 5, StringComparison.OrdinalIgnoreCase) != 0)
-            return false;
-        if (i > 0)
-        {
-            char prev = signature[i - 1];
-            if (char.IsLetterOrDigit(prev) || prev == '_')
-                return false;
-        }
-        if (i + 5 < signature.Length)
-        {
-            char next = signature[i + 5];
-            if (char.IsLetterOrDigit(next) || next == '_')
-                return false;
-        }
-        return true;
-    }
-
-    private static void AddBaseIfPresent(List<string> result, string raw)
-    {
-        var trimmed = raw.Trim();
-        if (trimmed.Length == 0)
-            return;
-        // Take the head identifier (everything before `<` or whitespace) but preserve
-        // any namespace prefix so the caller can treat `System.Attribute` directly.
-        // `<` 以前と空白以前を頭とし、`System.Attribute` などの名前空間付きはそのまま残す。
-        int cut = trimmed.Length;
-        for (int i = 0; i < trimmed.Length; i++)
-        {
-            char c = trimmed[i];
-            if (c == '<' || char.IsWhiteSpace(c))
-            {
-                cut = i;
-                break;
-            }
-        }
-        var head = trimmed.Substring(0, cut);
-        if (head.Length > 0)
-            result.Add(head);
-    }
 }
diff --git a/tests/CodeIndex.Tests/CSharpBaseListParserTests.cs b/tests/CodeIndex.Tests/CSharpBaseListParserTests.cs
new file mode 100644
index 000000000..ef7714eab
--- /dev/null
+++ b/tests/CodeIndex.Tests/CSharpBaseListParserTests.cs
@@ -0,0 +1,115 @@
+using CodeIndex.Database;
+
+namespace CodeIndex.Tests;
+
+public sealed class CSharpBaseListParserTests
+{
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("public class Plain {")]
+    [InlineData("public class Generic<T> where T : System.Attribute {")]
+    [InlineData("public record Generic<T>(T Value) where T : class;")]
+    [InlineData("public record Generic(string Value = \"where: value\");")]
+    public void Parse_DoesNotTreatNonBaseColonsAsBaseLists(string? signature)
+    {
+        var typeReferences = CSharpBaseListParser.Parse(
+            signature,
+            CSharpBaseListProjection.TypeReference);
+        var headIdentifiers = CSharpBaseListParser.Parse(
+            signature,
+            CSharpBaseListProjection.HeadIdentifier);
+
+        Assert.Empty(typeReferences);
+        Assert.Empty(headIdentifiers);
+    }
+
+    [Fact]
+    public void Parse_PreservesNestedCSharpTypeReferences()
+    {
+        const string Signature =
+            "public sealed class Derived<T>(string value = \"where:,{}\") "
+            + ": global::Demo.Base<(int Left, string Right)>(value), "
+            + "IFoo<T[]>, Alias::IBar where T : class {";
+
+        var result = CSharpBaseListParser.Parse(
+            Signature,
+            CSharpBaseListProjection.TypeReference);
+
+        Assert.Equal(
+        [
+            "global::Demo.Base<(int Left, string Right)>(value)",
+            "IFoo<T[]>",
+            "Alias::IBar",
+        ], result);
+    }
+
+    [Fact]
+    public void Parse_ProjectsMetadataHeadIdentifiersWithoutChangingReaderEntries()
+    {
+        const string Signature =
+            "public sealed class Derived<T>(T value) "
+            + ": global::Demo.Base<(int Left, string Right)>(value), "
+            + "IFoo<T[]>, Alias::IBar where T : class {";
+
+        var result = CSharpBaseListParser.Parse(
+            Signature,
+            CSharpBaseListProjection.HeadIdentifier);
+
+        Assert.Equal(["global::Demo.Base", "IFoo", "Alias::IBar"], result);
+    }
+
+    [Theory]
+    [InlineData("public class Somewhere : Base", "Base")]
+    [InlineData("public class Where : Base", "Base")]
+    [InlineData("public class @where : Base", "Base")]
+    [InlineData("public record Derived(int Value) : Base(Value);", "Base(Value)")]
+    [InlineData("public class Derived(int Value = 1 < 2 ? 1 : 0) : Base(Value)", "Base(Value)")]
+    [InlineData("[global::Demo.Marker(Name = \"where: value\")] public class Derived : global::Demo.Base", "global::Demo.Base")]
+    public void Parse_RecognizesWhereOnlyAsTheConstraintKeyword(
+        string signature,
+        string expectedBase)
+    {
+        var result = CSharpBaseListParser.Parse(
+            signature,
+            CSharpBaseListProjection.TypeReference);
+
+        Assert.Equal([expectedBase], result);
+    }
+
+    [Fact]
+    public void Parse_SplitsOnlyTopLevelCommasAcrossMultilineDeclarations()
+    {
+        const string Signature = """
+            public class Derived<T> :
+                Base<Dictionary<string, (int Left, int Right)>>,
+                IFoo<Action<int[], string>>
+                where T : class
+            {
+            """;
+
+        var result = CSharpBaseListParser.Parse(
+            Signature,
+            CSharpBaseListProjection.TypeReference);
+
+        Assert.Equal(
+        [
+            "Base<Dictionary<string, (int Left, int Right)>>",
+            "IFoo<Action<int[], string>>",
+        ], result);
+    }
+
+    [Fact]
+    public void Parse_IgnoresComparisonOperatorsInsideBaseConstructorArguments()
+    {
+        const string Signature =
+            "public class Derived(int value, int limit) "
+            + ": Base(value < limit ? value : limit), IFoo {";
+
+        var result = CSharpBaseListParser.Parse(
+            Signature,
+            CSharpBaseListProjection.HeadIdentifier);
+
+        Assert.Equal(["Base", "IFoo"], result);
+    }
+}

From eba355cf3200f411af4c0e90f4722240d207ab86 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 05:04:36 +0900
Subject: [PATCH 04/45] Decompose the symbol extraction pipeline

---
 .../Symbols/SymbolExtractor.ExtractCore.cs    | 1333 +----------------
 .../SymbolExtractor.PatternCandidates.cs      |  199 +++
 .../SymbolExtractor.PatternEmissionFlow.cs    |  186 +++
 .../SymbolExtractor.PatternExtraction.cs      |  274 ++++
 .../Symbols/SymbolExtractor.PatternFlow.cs    |  119 ++
 .../Symbols/SymbolExtractor.PatternGates.cs   |  392 +++++
 .../Symbols/SymbolExtractor.PatternLoop.cs    |  329 ++++
 .../SymbolExtractor.PatternMatching.cs        |  201 +++
 .../SymbolExtractor.PatternProgression.cs     |  352 +++++
 9 files changed, 2066 insertions(+), 1319 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternCandidates.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternEmissionFlow.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternExtraction.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternFlow.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternGates.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternLoop.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternMatching.cs
 create mode 100644 src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternProgression.cs

diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.ExtractCore.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.ExtractCore.cs
index b9bb4fae9..d5949483d 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.ExtractCore.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.ExtractCore.cs
@@ -56,1330 +56,25 @@ private static List<SymbolRecord> ExtractCore(
             return specializedSymbols;
         }
 
-        // Normalize CRLF / CR to LF first so direct callers that bypass FileIndexer
-        // still present a `\n`-only content stream, and then strip line-leading
-        // UTF-8 BOM (U+FEFF) defensively so `^\s*`-anchored patterns match on
-        // line 1 and on any mid-file line that begins with a BOM (e.g. from file
-        // concatenation or tool insertion). StripLineLeadingBom assumes `\n` is
-        // the sole line separator, so the CRLF pass must come first. Non-line-
-        // leading U+FEFF is preserved so content with intentional ZWNBSP inside
-        // a string literal stays verbatim. Closes #183.
-        // まず CRLF / CR を LF に正規化する。StripLineLeadingBom は `\n` を唯一の
-        // 行区切りとして行頭判定するので、FileIndexer を経由しない direct call
-        // でも CRLF 正規化を済ませてから呼ばないと mid-file の行頭 BOM を剥がし
-        // 損なう。続いて行頭 U+FEFF のみ剥がし、1 行目と mid-file の行頭 BOM 両方
-        // で `^\s*` 固定パターンを成立させる。行頭以外の U+FEFF (文字列リテラル中
-        // の意図的な ZWNBSP 等) はそのまま保持する。Closes #183.
-        List<SymbolPattern>? patterns = null;
-        var usesLineBasedExtractor = lang is "commonlisp" or "racket" or "solidity" or "html" or "assembly"
-            || (lang is not null && PatternCache.TryGetValue(lang, out patterns));
-        if (!usesLineBasedExtractor)
-            return [];
-
-        var lines = SplitContentLines(content);
-        cancellationToken.ThrowIfCancellationRequested();
-        if (lang is "commonlisp" or "racket")
-            return ExtractLispSymbols(fileId, lang, lines);
-
-        if (lang == "solidity")
-            return ExtractSoliditySymbols(fileId, lines);
-
-        // HTML has no brace/indent-scoped bodies, so the generic pattern loop's
-        // "first match per line" semantics drop every additional symbol on the
-        // same line. HTML also needs cross-line masking of `<!-- ... -->` and
-        // raw-text children of `<script>` / `<style>` before patterns run, or
-        // phantom imports/classes/properties leak out of commented-out tags
-        // and inline template string literals. Closes #215 codex review blocker.
-        // HTML は brace/indent スコープの本体を持たないため、汎用パターンループの
-        // 「1 行の先勝ち」意味論を通すと同一行の追加シンボルを取りこぼす。加えて
-        // `<!-- ... -->` と `<script>` / `<style>` の raw-text 子要素を跨ぎ行で
-        // マスクしておかないと、コメントアウトされたタグやインラインテンプレート
-        // 文字列から phantom な import / class / property が漏れる。#215 の codex
-        // レビュー blocker 対応としてここで専用抽出に分岐する。
-        if (lang == "html")
-            return ExtractHtmlSymbols(fileId, content, lines);
-
-        if (lang == "assembly")
-            return ExtractAssemblySymbols(fileId, lines);
-
-        if (patterns == null || lang == null)
-            return [];
-
-        var applicablePatterns = SelectApplicablePatterns(
-            patterns,
-            content,
-            applyRequiredLiteralFileGate);
-        if (requiredLiteralGateCounts != null)
-        {
-            requiredLiteralGateCounts.PatternCount = patterns.Count;
-            requiredLiteralGateCounts.ApplicablePatternCount = applicablePatterns.Count;
-        }
-
-        var scanInputs = new PatternScanInputs(
+        var preparation = PreparePatternExtraction(
+            fileId,
+            originalLang,
             lang,
+            content,
             filePath,
-            lines,
-            applicablePatterns,
+            projectRoot,
+            cancellationToken,
+            maxSymbols,
+            applyRequiredLiteralFileGate,
             applyRequiredLiteralMatchInputGate,
             requiredLiteralGateCounts);
-        var pythonModulePrefix = scanInputs.PythonModulePrefix;
-        var structuralLines = scanInputs.StructuralLines;
-        var scientificBodyScannerLines = scanInputs.ScientificBodyScannerLines;
-        var matlabExplicitOuterClosureByLine = scanInputs.MatlabExplicitOuterClosureByLine;
-        Func<string[]> GetJavaScriptTypeScriptSanitizedLines = scanInputs.GetJavaScriptTypeScriptSanitizedLines;
-        var cssScannerLines = scanInputs.CssScannerLines;
-        var sassStylusScannerLines = scanInputs.SassStylusScannerLines;
-        var shellScannerLines = scanInputs.ShellScannerLines;
-        var prologClauseContinuationLines = scanInputs.PrologClauseContinuationLines;
-        var prologMultilineHeads = scanInputs.PrologMultilineHeads;
-        var powershellEnumBodyLines = scanInputs.PowershellEnumBodyLines;
-        var csharpMatchColumnToRaw = scanInputs.CSharpMatchColumnToRaw;
-        var csharpMatchLines = scanInputs.CSharpMatchLines;
-        var getCSharpLineStartStates = scanInputs.GetCSharpLineStartStates;
-        Func<DartClassBodyScope> GetDartInsideClassBody = scanInputs.GetDartInsideClassBody;
-        var getPrivateScopeColumns = scanInputs.GetPrivateScopeColumns;
-        Func<CSharpTypeBodyScope> GetCSharpInsideTypeBody = scanInputs.GetCSharpInsideTypeBody;
-        Func<CSharpCallableParameterScope> GetCSharpCallableParameterScope = scanInputs.GetCSharpCallableParameterScope;
-        Func<CSharpDeclarationStartScope> GetCSharpDeclarationStartScope = scanInputs.GetCSharpDeclarationStartScope;
-        var getCSharpSwitchExpressionLines = scanInputs.GetCSharpSwitchExpressionLines;
-        var getCssQualifiedRuleAncestors = scanInputs.GetCssQualifiedRuleAncestors;
-        var initialSymbolCapacity = EstimateSymbolListInitialCapacity(lines.Length);
-        var symbols = new SymbolExtractionList(initialSymbolCapacity, maxSymbols);
-        var extractionState = symbols.ExtractionState;
-        var scanState = new PatternScanState();
-        List<PendingRecordPrimaryComponents>? pendingRecordPrimaryComponents = null;
-        RecordPrimaryComponentParentIndex? recordPrimaryComponentParentIndex = null;
-        var cssSeenSymbols = lang == "css"
-            ? new HashSet<SymbolLineIdentity>()
-            : null;
-        var dockerfileStageNames = lang == "dockerfile"
-            ? new HashSet<string>(StringComparer.Ordinal)
-            : null;
-        for (int i = 0; i < lines.Length; i++)
-        {
-            if (symbols.IsAtCapacity)
-                break;
-
-            if ((i & 0x3f) == 0)
-                cancellationToken.ThrowIfCancellationRequested();
-
-            if (!TryPreparePatternLine(
-                    fileId,
-                    lang,
-                    filePath,
-                    projectRoot,
-                    lines,
-                    scanInputs,
-                    scanState,
-                    symbols,
-                    extractionState,
-                    dockerfileStageNames,
-                    i,
-                    out var preparedLine))
-            {
-                continue;
-            }
-
-            var line = preparedLine.SourceLine;
-            var matchLine = preparedLine.MatchLine;
-            var cssScannerLine = preparedLine.CssScannerLine;
-            var fortranContinuationCandidate = preparedLine.FortranContinuationCandidate;
-            var patternStartOffset = preparedLine.PatternStartOffset;
-            var prologContinuationResumeOffset = preparedLine.PrologContinuationResumeOffset;
-            while (patternStartOffset >= 0 && patternStartOffset < matchLine.Length)
-            {
-                var stopAfterFirstPatternMatch = false;
-                var restartPatternScanOffset = -1;
-                CSharpPropertyMatchCandidate? csharpPropertyCandidateForLine = null;
-                bool? deferCSharpBracePropertyAtPatternStart = null;
-                bool? deferCSharpFunctionAtPatternStart = null;
-                bool? deferCSharpEventAtPatternStart = null;
-                bool? deferCSharpDelegateAtPatternStart = null;
-                bool? recoverableCSharpPatternAtPatternStart = null;
-                foreach (var pattern in applicablePatterns)
-                {
-                    if (prologClauseContinuationLines?[i] == true
-                        && prologContinuationResumeOffset < 0
-                        && pattern.Kind == "function")
-                        continue;
-                    if (lang == "csharp" && ReferenceEquals(pattern.Regex, CSharpEnumMemberRegex))
-                        continue;
-                    if (lang == "powershell"
-                        && pattern.Kind == "enum"
-                        && pattern.BodyStyle == BodyStyle.None
-                        && !powershellEnumBodyLines![i])
-                    {
-                        continue;
-                    }
-                    // Merge multi-line field headers for C# regardless of kind. Kind "property" (plain
-                    // fields) and kind "function" (const / static readonly fields) both need the
-                    // merge. Non-field function patterns (methods, constructors, operators, indexers)
-                    // are unaffected because CSharpPropertyHeaderPrefixRegex requires the line to end
-                    // before `(` or `{`, so lines like `public int Foo()` never satisfy the header
-                    // prefix and the merger returns the original line. Closes #355.
-                    // C# の複数行フィールドヘッダ結合は kind に依らず適用する。kind "property"（通常
-                    // フィールド）と kind "function"（`const` / `static readonly` フィールド）の両方で
-                    // 結合が必要。method / constructor / operator / indexer のような非フィールド
-                    // function パターンは `CSharpPropertyHeaderPrefixRegex` が `(` や `{` を含む行を
-                    // 受け付けないため影響を受けず、merger は元の行をそのまま返す。Closes #355.
-                    var csharpPropertyCandidate = lang == "csharp" && pattern.Kind is "property" or "function"
-                        ? csharpPropertyCandidateForLine ??= BuildCSharpPropertyMatchLine(lines, csharpMatchLines!, i)
-                        : new CSharpPropertyMatchCandidate(matchLine, i, i);
-                    var patternMatchLine = csharpPropertyCandidate.MatchLine;
-                    if (fortranContinuationCandidate != null)
-                        patternMatchLine = fortranContinuationCandidate.Value.MatchLine;
-                    var lineOffset = patternStartOffset;
-                    string? csharpWrappedModifierPrefix = null;
-                    while (lineOffset >= 0 && lineOffset < patternMatchLine.Length)
-                    {
-                        var javaLeadingAnnotationOffset = 0;
-                        Match match;
-                        if (lang is "java" or "kotlin")
-                        {
-                            var javaPatternMatched = TryMatchJavaDeclarationPatternSegment(
-                                pattern,
-                                patternMatchLine,
-                                lineOffset,
-                                lang == "kotlin",
-                                applyRequiredLiteralMatchInputGate,
-                                requiredLiteralGateCounts,
-                                out match,
-                                out javaLeadingAnnotationOffset,
-                                out var initialJavaInputAttempted);
-                            if (!javaPatternMatched
-                                && initialJavaInputAttempted
-                                && ShouldAttemptPatternRegex(
-                                    pattern,
-                                    patternMatchLine.AsSpan(lineOffset),
-                                    applyRequiredLiteralMatchInputGate,
-                                    requiredLiteralGateCounts))
-                            {
-                                // Preserve the existing failed-helper fallback attempt. This is
-                                // intentionally gated again because it is a distinct regex call.
-                                match = pattern.Regex.Match(patternMatchLine[lineOffset..]);
-                            }
-                        }
-                        else if (ShouldAttemptPatternRegex(
-                                     pattern,
-                                     patternMatchLine.AsSpan(lineOffset),
-                                     applyRequiredLiteralMatchInputGate,
-                                     requiredLiteralGateCounts))
-                        {
-                            match = pattern.Regex.Match(patternMatchLine[lineOffset..]);
-                        }
-                        else
-                        {
-                            match = Match.Empty;
-                        }
-
-                        if (!match.Success
-                            && lang == "csharp"
-                            && pattern.Kind == "function"
-                            && lineOffset == 0
-                            && csharpMatchLines != null
-                            && csharpWrappedModifierPrefix == null)
-                        {
-                            // Wrapped leading modifier recovery: when a C# function-kind pattern
-                            // fails at column 0 of the identifier line, try prepending the
-                            // modifier prefix accumulated from preceding modifier-only lines
-                            // (`static\nFoo() { ... }`, `public\nBar() { ... }`, etc.) and retry.
-                            // The method regex already tolerates an omitted modifier run, so it
-                            // matches on the identifier line alone — this branch only fires for
-                            // constructor / static-constructor shapes that require the modifier
-                            // on the same line as the name. Closes #348.
-                            // ラップされた先頭モディファイアの救済: C# の function 系パターンが
-                            // 識別子行の先頭マッチに失敗した場合、直前のモディファイアのみ行
-                            // （`static\nFoo() { ... }` や `public\nBar() { ... }` 等）から
-                            // 再構築した prefix を付け直して再試行する。メソッド regex は
-                            // 先頭モディファイアが無くても識別子行単体でマッチするため、この
-                            // 分岐は修飾子が識別子と同行に必要な constructor / static ctor
-                            // シェイプでのみ発火する。Closes #348.
-                            var wrappedInfo = TryFindCSharpWrappedHeaderModifier(csharpMatchLines!, i);
-                            if (wrappedInfo != null)
-                            {
-                                foreach (var candidatePrefix in EnumerateCSharpWrappedModifierCandidates(wrappedInfo.Value.Prefix))
-                                {
-                                    var wrappedMatchLine = candidatePrefix + " " + patternMatchLine.TrimStart();
-                                    if (!ShouldAttemptPatternRegex(
-                                            pattern,
-                                            wrappedMatchLine.AsSpan(),
-                                            applyRequiredLiteralMatchInputGate,
-                                            requiredLiteralGateCounts))
-                                    {
-                                        continue;
-                                    }
-
-                                    var wrappedMatch = pattern.Regex.Match(wrappedMatchLine);
-                                    if (wrappedMatch.Success)
-                                    {
-                                        match = wrappedMatch;
-                                        patternMatchLine = wrappedMatchLine;
-                                        // Preserve the full prefix in the stored signature so
-                                        // declarations like `public\nstatic\nP1()` retain
-                                        // `public static P1()`, even when the matching regex
-                                        // variant only accepted `static P1()`. Closes #348.
-                                        // シグネチャには完全な prefix を残し、`public\nstatic\nP1()`
-                                        // のような宣言を `public static P1()` として保存する。
-                                        // マッチした regex 変種が `static P1()` 形だけを受け付けた
-                                        // 場合でも、保存シグネチャは完全な prefix を保持する。Closes #348.
-                                        csharpWrappedModifierPrefix = wrappedInfo.Value.Prefix;
-                                        break;
-                                    }
-                                }
-                            }
-                        }
-
-                        if (!match.Success)
-                        {
-                            if (lang == "csharp"
-                                && pattern.Kind == "property"
-                                && pattern.BodyStyle == BodyStyle.Brace
-                                && (lineOffset != patternStartOffset
-                                    ? ShouldDeferCSharpBracePropertySameLineAdvance(matchLine, lineOffset)
-                                    : deferCSharpBracePropertyAtPatternStart ??=
-                                        ShouldDeferCSharpBracePropertySameLineAdvance(matchLine, lineOffset)))
-                            {
-                                break;
-                            }
-
-                            if (lang == "csharp"
-                                && pattern.Kind == "function"
-                                && (lineOffset != patternStartOffset
-                                    ? ShouldDeferCSharpFunctionSameLineAdvance(matchLine, lineOffset)
-                                    : deferCSharpFunctionAtPatternStart ??=
-                                        ShouldDeferCSharpFunctionSameLineAdvance(matchLine, lineOffset)))
-                            {
-                                break;
-                            }
-
-                            if (lang == "csharp"
-                                && pattern.Kind is "event" or "delegate"
-                                && pattern.BodyStyle == BodyStyle.None
-                                && (lineOffset != patternStartOffset
-                                    ? ShouldDeferCSharpEventOrDelegateSameLineAdvance(matchLine, lineOffset, pattern.Kind)
-                                    : pattern.Kind == "event"
-                                        ? deferCSharpEventAtPatternStart ??=
-                                            ShouldDeferCSharpEventOrDelegateSameLineAdvance(matchLine, lineOffset, pattern.Kind)
-                                        : deferCSharpDelegateAtPatternStart ??=
-                                            ShouldDeferCSharpEventOrDelegateSameLineAdvance(matchLine, lineOffset, pattern.Kind)))
-                            {
-                                break;
-                            }
-
-                            if (lang is "javascript" or "typescript" or "css" or "java"
-                                || (lang == "csharp"
-                                    && pattern.Kind == "enum"
-                                    && pattern.BodyStyle == BodyStyle.Brace
-                                    && patternStartOffset > 0)
-                                || (lang == "csharp"
-                                    && pattern.Kind == "property"
-                                    && pattern.BodyStyle == BodyStyle.None
-                                    && !(lineOffset != patternStartOffset
-                                        ? TryMatchAnyRecoverableCSharpPattern(
-                                            matchLine,
-                                            lineOffset,
-                                            insideEnumBody: false,
-                                            attributeParenDepth: 0,
-                                            applicablePatterns,
-                                            applyRequiredLiteralMatchInputGate,
-                                            requiredLiteralGateCounts)
-                                        : recoverableCSharpPatternAtPatternStart ??=
-                                            TryMatchAnyRecoverableCSharpPattern(
-                                                matchLine,
-                                                lineOffset,
-                                                insideEnumBody: false,
-                                                attributeParenDepth: 0,
-                                                applicablePatterns,
-                                                applyRequiredLiteralMatchInputGate,
-                                                requiredLiteralGateCounts))))
-                            {
-                                lineOffset = FindNextSameLineBraceStatementStart(matchLine, lineOffset + 1, lang);
-                                continue;
-                            }
-
-                            break;
-                        }
-
-                        var absoluteStartColumn = lineOffset + match.Index;
-                        if (lang is "java" or "kotlin" && javaLeadingAnnotationOffset > 0)
-                            absoluteStartColumn = lineOffset + javaLeadingAnnotationOffset;
-                        var nextSameLineOffsetAfterRejectedCSharpProperty = -1;
-                        if (ShouldSkipCSharpSwitchExpressionPropertyCandidate(lang, pattern, patternMatchLine, getCSharpSwitchExpressionLines, i)
-                            || TrySkipCSharpBracePropertyCandidate(
-                                lang,
-                                pattern,
-                                patternMatchLine,
-                                absoluteStartColumn,
-                                match.Value.Contains("=>", StringComparison.Ordinal),
-                                out nextSameLineOffsetAfterRejectedCSharpProperty))
-                        {
-                            // False-positive C# property matches can happen at the start of a
-                            // same-line type header (`public class C { ... }`) because the
-                            // property regex allows omitted visibility/modifier runs and can
-                            // initially treat the header as `returnType + name + {`. Do not break
-                            // the whole same-line scan on that rejection — advance to the next
-                            // brace-delimited statement so a real nested property later on the
-                            // same physical line still gets a chance to match. Closes #470.
-                            // C# の property 正規表現は visibility / modifier 省略を許すため、
-                            // 同一行の型ヘッダ先頭 (`public class C { ... }`) を一旦
-                            // `returnType + name + {` と誤認することがある。この偽候補を弾いた
-                            // ときに同一行スキャン全体を break せず、次の brace 区切り宣言へ進めて
-                            // 後続の本物 property にもマッチ機会を残す。Closes #470.
-                            lineOffset = nextSameLineOffsetAfterRejectedCSharpProperty >= 0
-                                ? nextSameLineOffsetAfterRejectedCSharpProperty
-                                : FindNextSameLineBraceStatementStart(
-                                    matchLine,
-                                    absoluteStartColumn + Math.Max(1, match.Length),
-                                    lang);
-                            continue;
-                        }
-
-                        // Gate the C# plain-field pattern (internally tagged as `property`,
-                        // BodyStyle.None, then normalized to the public `field` kind) to lines
-                        // that sit directly inside a type body. Without this gate, local
-                        // variable declarations inside method / property / accessor / lambda
-                        // bodies match the same shape and leak into `symbols`, `definition`,
-                        // `outline`, `inspect`, and `unused` as phantom field symbols.
-                        // Closes #298 follow-up (codex review blocker).
-                        // C# の通常フィールド用パターン（内部タグは `property`、BodyStyle.None、
-                        // 公開時に `field` へ正規化）は型本体（class / struct / interface /
-                        // record / enum の直下）でしか許可しない。このゲートを入れないと、
-                        // メソッド・プロパティ・アクセサ・ラムダの内部にあるローカル変数宣言が
-                        // 同じ形でマッチしてしまい、
-                        // `symbols` / `definition` / `outline` / `inspect` / `unused` に
-                        // 擬似シンボルが混入する。Closes #298 の codex レビュー blocker 対応。
-                        if (ShouldSkipCssNestedSelectorCandidate(lang, pattern, patternMatchLine, getCssQualifiedRuleAncestors, i))
-                            break;
-
-                        // JS/TS HOC binding gate: the `styled.` / `styled(` / `styled\`` regex
-                        // branch matches three shapes — factory capture (`const F = styled.div;`),
-                        // plain call (`const F = styled(Component);`), and tagged template
-                        // (`const F = styled.div\`...\``). Only the tagged-template shape
-                        // actually declares a styled-component binding; the other two produce
-                        // a factory / a styled wrapper-of-component without a component body
-                        // on that line and must stay 0-symbol. This gate looks at the raw
-                        // (unmasked) line because StructuralLineMasker.MaskJsTsTemplateLiteralContents
-                        // replaces template-literal delimiters with space, so the masked
-                        // `patternMatchLine` cannot see the backtick. Closes #240 follow-up
-                        // (codex review #5 blocker).
-                        // JS/TS HOC 束縛ゲート: `styled.` / `styled(` / `styled\`` の regex
-                        // 分岐は 3 形状にマッチする — factory 捕捉（`const F = styled.div;`）、
-                        // 素の呼び出し（`const F = styled(Component);`）、タグ付きテンプレート
-                        // （`const F = styled.div\`...\``）。実際に styled-component 束縛を
-                        // 生むのはタグ付きテンプレート形のみで、前者 2 つはその行で component
-                        // 本体を生やさないため 0 シンボルに保つ必要がある。このゲートは raw 行
-                        // （マスク前）を参照する — `StructuralLineMasker.MaskJsTsTemplateLiteralContents`
-                        // がテンプレート区切りを空白にマスクするため、マスク後の
-                        // `patternMatchLine` ではバッククォートが見えないことへの対処。
-                        // Closes #240 follow-up（codex レビュー #5 の blocker 対応）。
-                        if (ShouldSkipJavaScriptTypeScriptStyledFactoryCandidate(lang, pattern, match, lineOffset, lines, i))
-                        {
-                            lineOffset = FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, lineOffset + Math.Max(1, match.Length));
-                            continue;
-                        }
-
-                        // For C#, collapsed-space column (from CollapseCSharpGenericTypeWhitespace)
-                        // has to be translated back to raw-space before it can be compared against
-                        // CSharpTypeBodyScope's per-line transitions, which were built from
-                        // structural (raw) columns. Only translate when the pattern match runs on
-                        // the per-line collapsed string (single-line case); multi-line merged
-                        // candidates use a different composed string whose column domain does not
-                        // line up with a single line's map, so we leave the column alone there to
-                        // preserve pre-existing behavior. Closes #400.
-                        // C# では CollapseCSharpGenericTypeWhitespace で空白を取り除いた列を、
-                        // structural 行の生列で構築された CSharpTypeBodyScope に渡す前に
-                        // raw 列へ戻す必要がある。複数行を結合した match では単一行の map が
-                        // 使えないため、単一行ケース（per-line collapsed line そのものにマッチした
-                        // 場合）だけ変換する。Closes #400.
-                        var csharpNormalizedStartColumn = lang == "csharp"
-                            ? SkipWhitespace(patternMatchLine, absoluteStartColumn)
-                            : absoluteStartColumn;
-                        var csharpGateRawStartColumn = csharpNormalizedStartColumn;
-                        if (lang == "csharp"
-                            && csharpMatchLines != null
-                            && ReferenceEquals(patternMatchLine, csharpMatchLines[i]))
-                        {
-                            csharpGateRawStartColumn = TranslateCSharpCollapsedColumnToRaw(
-                                csharpMatchColumnToRaw,
-                                i,
-                                csharpNormalizedStartColumn,
-                                line.Length);
-                        }
-
-                        if (lang == "dart"
-                            && ReferenceEquals(pattern.Regex, DartBareConstConstructorRegex)
-                            && !GetDartInsideClassBody().IsInsideClassBodyAt(i))
-                        {
-                            // Bare `const` constructors need class-body context; otherwise
-                            // `const Widget(key: k)` expressions become phantom symbols.
-                            // bare な `const` コンストラクタは class 本体内でのみ許可する。
-                            // そうしないと `const Widget(key: k)` の式を phantom symbol にしてしまう。
-                            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
-                            continue;
-                        }
-
-                        // C# candidates that only become visible after string-literal content is
-                        // blanked (for example, code inside an interpolation hole of an outer
-                        // string) must not be emitted as declarations. A real declaration starts in
-                        // root code, not in nested interpolation code. Gate on the raw-line start
-                        // column so exact definition / inspect lookups do not pick up call-site
-                        // fragments from interpolated log strings. Closes #790.
-                        // C# では、外側文字列本文を空白化した結果として見えるようになった候補
-                        // （例: 補間文字列ホール内のコード）を宣言として emit してはならない。
-                        // 本物の宣言は root code から始まり、入れ子の補間コードからは始まらない。
-                        // raw 行上の開始列でゲートし、補間ログ文字列内の呼び出し断片が
-                        // exact definition / inspect に混入しないようにする。Closes #790.
-                        var csharpLineStartStatesForGate = lang == "csharp"
-                            ? getCSharpLineStartStates?.Invoke()
-                            : null;
-                        if (csharpLineStartStatesForGate != null
-                            && !IsCSharpRootCodePosition(line, csharpLineStartStatesForGate[i], csharpGateRawStartColumn))
-                        {
-                            lineOffset = FindNextSameLineBraceStatementStart(
-                                matchLine,
-                                absoluteStartColumn + Math.Max(1, match.Length),
-                                lang);
-                            continue;
-                        }
-
-                        if (lang == "csharp"
-                            && (pattern.Kind is "function" or "property")
-                            && match.Groups["name"].Success
-                            && IsCSharpStaticLambdaHeaderCandidate(
-                                patternMatchLine,
-                                lineOffset + match.Groups["name"].Index,
-                                FindCSharpEnclosingTypeName(symbols, i + 1)))
-                        {
-                            // Multi-line call arguments are composed into the same candidate
-                            // string as the following lambda. A declaration-shaped regex can then
-                            // reinterpret the state argument as a return type and `static` (or a
-                            // parameter) as a member name. Reject only names that occupy a
-                            // confirmed static-lambda header; real static members and local
-                            // functions remain eligible. Closes #4830; regression of #4453.
-                            // 複数行の呼び出し引数と後続 lambda は同じ候補文字列に結合されるため、
-                            // 宣言形 regex が state 引数を戻り値型、`static`（または parameter）を
-                            // member 名として再解釈し得る。確認済み static-lambda header 内の名前
-                            // だけを除外し、本物の static member / local function は維持する。
-                            // Closes #4830; regression of #4453.
-                            lineOffset = absoluteStartColumn + Math.Max(1, match.Length);
-                            continue;
-                        }
-
-                        if (lang == "csharp"
-                            && pattern.Kind == "function"
-                            && pattern.BodyStyle == BodyStyle.Brace
-                            && !GetCSharpDeclarationStartScope().CanStartDeclarationAt(i, csharpGateRawStartColumn))
-                        {
-                            // Method and constructor patterns are intentionally broad enough to
-                            // recognize multi-line declarations. Do not let that merger begin from
-                            // an invocation argument or callable-parameter continuation, even when
-                            // a later declaration brace makes the combined text look method-shaped.
-                            // The scope is column-aware so a real same-line sibling remains eligible.
-                            // メソッドとコンストラクタのパターンは複数行宣言を認識するため意図的に
-                            // 広い。後続の宣言 brace によって結合テキストがメソッド形に見えても、
-                            // 呼び出し引数や callable parameter の継続位置から開始してはならない。
-                            // 列単位の scope により、同一行の後続にある本物の sibling は維持する。
-                            // Fixes #4831; prevents regressions covered by #496 and #4413.
-                            lineOffset = FindNextSameLineBraceStatementStart(
-                                matchLine,
-                                absoluteStartColumn + Math.Max(1, match.Length),
-                                lang);
-                            continue;
-                        }
-
-                        if (lang == "csharp"
-                            && pattern.Kind == "function"
-                            && HasCSharpTokenBeforeIndex(matchLine, "when", absoluteStartColumn + match.Groups["name"].Index))
-                        {
-                            lineOffset = absoluteStartColumn + Math.Max(1, match.Length);
-                            continue;
-                        }
-                        if (lang == "csharp"
-                            && pattern.Kind == "function"
-                            && csharpPropertyCandidate.ExpressionBodyEndLineIndex.HasValue
-                            && IsCSharpFunctionMatchInsideExpressionBody(
-                                patternMatchLine,
-                                absoluteStartColumn + match.Groups["name"].Index))
-                        {
-                            // The property/function header merger is shared by all C# member
-                            // patterns. Once it has identified an expression body, a function-shaped
-                            // call after `=>` is an expression, not a declaration. Preserve a real
-                            // same-line sibling after the terminating `;`.
-                            // C# の property/function header merger は全 member pattern で共有される。
-                            // 式本体を特定した後、`=>` より後の function 形呼び出しは宣言ではなく式である。
-                            // 終端 `;` より後にある本物の same-line sibling は維持する。
-                            lineOffset = absoluteStartColumn + Math.Max(1, match.Length);
-                            continue;
-                        }
-                        if (lang == "csharp"
-                            && pattern.BodyStyle == BodyStyle.None
-                          && (pattern.Kind == "property" || IsCSharpFieldLikeFunctionPattern(pattern))
-                          && GetCSharpCallableParameterScope().IsInsideParameterListAt(i, csharpGateRawStartColumn))
-                        {
-                            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
-                            continue;
-                        }
-                        if (lang == "csharp"
-                            && pattern.BodyStyle == BodyStyle.None
-                          && (pattern.Kind == "property" || IsCSharpFieldLikeFunctionPattern(pattern))
-                          && !GetCSharpInsideTypeBody().IsInsideTypeBodyAt(i, csharpGateRawStartColumn))
-                        {
-                            // Move the cursor past this same-line candidate so a later
-                            // column on the same line (e.g. a real field that lives after
-                            // a same-line method body or similar non-type-body scope) can
-                            // still be evaluated against its own column-aware scope.
-                            // Without this advance, the outer `while` would exit the line
-                            // entirely on the first rejection and drop any following match.
-                            // 同一行に続く別候補（例: 同一行の method 本体など非型本体の
-                            // 後ろにある実フィールド）を取りこぼさないよう、次の候補探索
-                            // 位置へ進める。この進行が無いと最初の拒否で while ループが
-                            // 行を抜けてしまい、後続候補が失われる。Closes #400.
-                            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
-                            continue;
-                        }
-                        if (lang == "csharp"
-                            && pattern.BodyStyle == BodyStyle.None
-                            && (pattern.Kind == "property" || IsCSharpFieldLikeFunctionPattern(pattern))
-                            && IsInsidePreviouslyEmittedCSharpMemberBody(lines, symbols, i + 1, csharpGateRawStartColumn))
-                        {
-                            // Brace-based type-body scope tracking correctly rejects locals inside
-                            // block bodies, but multi-line expression-bodied members have no brace
-                            // transition for their continuation lines. Without an additional guard,
-                            // those later lines can still match the plain-field regex and emit
-                            // phantom `property` rows like `Red` from `value is\n Red\n or Red;`.
-                            // Only reject lines after the member's declaration line so same-line
-                            // siblings such as `int M() => 0; int X;` keep working through the
-                            // existing column-aware scope gate. Closes #779.
-                            // brace ベースの型本体スコープ追跡は block body 内の local を弾けるが、
-                            // 複数行の式本体メンバーには continuation 行用の brace 遷移が無い。
-                            // そのため追加ガードが無いと `value is\n Red\n or Red;` の後続行が
-                            // plain-field regex にマッチして `property Red` の phantom を出してしまう。
-                            // `int M() => 0; int X;` のような same-line sibling は既存の列単位
-                            // ゲートで扱えるよう、宣言行そのものではなく後続行だけを拒否する。
-                            // Closes #779.
-                            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
-                            continue;
-                        }
-                        if (lang == "rust"
-                            && pattern.Kind == "property"
-                            && pattern.BodyStyle == BodyStyle.None
-                            && pattern.ReturnTypeGroup != null
-                            && !IsRustDirectTraitBodyMember(symbols, i + 1))
-                        {
-                            break;
-                        }
-                        var rawReturnType = NormalizeCSharpImplicitPartialMethodReturnType(
-                            lang,
-                            pattern,
-                            match,
-                            TryGetGroup(match, pattern.ReturnTypeGroup));
-                        if (lang == "csharp"
-                            && pattern.ReturnTypeGroup != null
-                            && HasInvalidCSharpReturnTypeSuffix(rawReturnType))
-                        {
-                            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
-                            continue;
-                        }
-                        if (lang == "csharp"
-                            && pattern.Kind == "function"
-                            && HasCSharpTokenBeforeIndex(matchLine, "when", absoluteStartColumn + match.Groups["name"].Index))
-                        {
-                            lineOffset = absoluteStartColumn + Math.Max(1, match.Length);
-                            continue;
-                        }
-                        if (lang == "csharp"
-                            && pattern.Kind == "property"
-                            && IsStandaloneCSharpAccessorCandidate(patternMatchLine))
-                        {
-                            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
-                            continue;
-                        }
-                        var jsTsPrivateScopeColumnsForClassGate = lang is "javascript" or "typescript" && pattern.Kind == "class"
-                            ? getPrivateScopeColumns?.Invoke()
-                            : null;
-                        if (jsTsPrivateScopeColumnsForClassGate != null
-                            && pattern.Kind == "class"
-                            && IsJavaScriptTypeScriptMatchInPrivateScope(jsTsPrivateScopeColumnsForClassGate, i, absoluteStartColumn, matchLine, includeBlockScope: true))
-                        {
-                            if (lang is "javascript" or "typescript")
-                            {
-                                var skippedEndColumn = pattern.BodyStyle == BodyStyle.Brace
-                                    ? FindJavaScriptTypeScriptSameLineBraceEndColumn(line, absoluteStartColumn, lang)
-                                    : -1;
-                                lineOffset = skippedEndColumn >= absoluteStartColumn
-                                    ? FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, skippedEndColumn + 1)
-                                    : FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, absoluteStartColumn + Math.Max(1, match.Length));
-                                continue;
-                            }
-
-                            break;
-                        }
-
-                        if (jsTsPrivateScopeColumnsForClassGate != null
-                            && pattern.Kind == "class"
-                            && TryGetGroup(match, pattern.VisibilityGroup) != "export"
-                            && IsJavaScriptTypeScriptMatchInNamespaceScope(jsTsPrivateScopeColumnsForClassGate, i, absoluteStartColumn, matchLine))
-                        {
-                            if (lang is "javascript" or "typescript")
-                            {
-                                var skippedEndColumn = pattern.BodyStyle == BodyStyle.Brace
-                                    ? FindJavaScriptTypeScriptSameLineBraceEndColumn(line, absoluteStartColumn, lang)
-                                    : -1;
-                                lineOffset = skippedEndColumn >= absoluteStartColumn
-                                    ? FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, skippedEndColumn + 1)
-                                    : FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, absoluteStartColumn + Math.Max(1, match.Length));
-                                continue;
-                            }
-
-                            break;
-                        }
-
-                        var name = match.Groups["name"].Success
-                            ? match.Groups["name"].ValueSpan.Trim().ToString()
-                            : match.ValueSpan.Trim().ToString();
-                        name = NormalizeExtractedSymbolName(lang, name, match, matchLine);
-                        if (pattern.Kind == "import" && lang is "javascript" or "typescript")
-                            name = ResolveJavaScriptTypeScriptModuleSpecifier(lang, filePath, projectRoot, name);
-                        var rubyAttrNames = lang == "ruby"
-                            && pattern.Kind == "property"
-                            ? TryExpandRubyAttrDeclaratorList(patternMatchLine, absoluteStartColumn, match, name)
-                            : null;
-
-                        var rangeLines = lang == "css" && cssScannerLines != null
-                            ? cssScannerLines
-                            : lang == "shell" && shellScannerLines != null
-                                ? shellScannerLines
-                            : structuralLines;
-                        var scalaBracelessClassEndLine = lang == "scala" && pattern.Kind == "class"
-                            ? TryFindScalaBracelessClassEndLine(lines, i, absoluteStartColumn)
-                            : null;
-                        var (endLine, bodyStartLine, bodyEndLine) = lang is "kotlin" or "scala"
-                            && pattern.Kind == "function"
-                            && TryFindKotlinScalaExpressionBodyEndLine(line, absoluteStartColumn)
-                                ? (i + 1, null, null)
-                                : scalaBracelessClassEndLine.HasValue
-                                        ? (scalaBracelessClassEndLine.Value + 1, null, null)
-                                        : lang == "csharp" && pattern.BodyStyle == BodyStyle.Brace && csharpMatchLines != null
-                                            ? FindCSharpPatternBraceRange(
-                                                lines,
-                                                csharpMatchLines,
-                                                getCSharpLineStartStates,
-                                                i,
-                                                absoluteStartColumn,
-                                                csharpGateRawStartColumn)
-                                            : ResolveRange(
-                                                rangeLines,
-                                                i,
-                                                pattern.BodyStyle,
-                                                lang,
-                                                absoluteStartColumn,
-                                                scientificBodyScannerLines,
-                                                matlabExplicitOuterClosureByLine);
-                        if (fortranContinuationCandidate != null)
-                            endLine = Math.Max(endLine, fortranContinuationCandidate.Value.LastConsumedLineIndex + 1);
-                        var startLine = i + 1;
-                        if (lang == "csharp"
-                            && pattern.Kind == "property"
-                            && pattern.BodyStyle == BodyStyle.None
-                            && csharpPropertyCandidate.ExpressionBodyEndLineIndex.HasValue)
-                        {
-                            endLine = Math.Max(endLine, csharpPropertyCandidate.ExpressionBodyEndLineIndex.Value + 1);
-                        }
-
-                        // Python @property decorator: reclassify the def as property
-                        // Python @property デコレータ: def を property に再分類
-                        var kind = pattern.Kind;
-                        string? pythonSubKind = null;
-                        if (kind == "function" && lang == "python" && HasPythonPropertyDecorator(lines, i))
-                        {
-                            kind = "property";
-                            pythonSubKind = GetPythonPropertyAccessorSubKind(lines, i);
-                        }
-                        else if (kind == "function" && lang == "python" && IsPythonClassHook(name))
-                        {
-                            kind = "class_hook";
-                            pythonSubKind = "dunder";
-                            (endLine, bodyStartLine, bodyEndLine) = FindPythonIndentedBodyRange(lines, i);
-                        }
-                        else if (kind == "function" && lang is "javascript" or "typescript")
-                        {
-                            kind = ResolveJavaScriptTypeScriptFunctionKind(
-                                TryGetGroup(match, "async") != null,
-                                TryGetGroup(match, "generator") != null);
-                        }
-
-                        if (lang == "css")
-                            name = ResolveCssSymbolName(matchLine[absoluteStartColumn..], name, lines, i, endLine);
-
-                        if (lang == "css" && string.IsNullOrWhiteSpace(name))
-                        {
-                            var skippedEndColumn = pattern.BodyStyle == BodyStyle.Brace
-                                && bodyEndLine == startLine
-                                ? FindSameLineBraceEndColumn(line, absoluteStartColumn, lang, kind)
-                                : -1;
-                            if (skippedEndColumn >= absoluteStartColumn)
-                            {
-                                lineOffset = FindNextSameLineBraceStatementStart(matchLine, skippedEndColumn + 1, lang);
-                                continue;
-                            }
-
-                            stopAfterFirstPatternMatch = true;
-                            break;
-                        }
-
-                        var signatureResult = BuildPatternSignature(
-                            lang,
-                            pattern,
-                            lines,
-                            i,
-                            line,
-                            patternMatchLine,
-                            absoluteStartColumn,
-                            match,
-                            csharpPropertyCandidate,
-                            csharpWrappedModifierPrefix,
-                            csharpMatchColumnToRaw,
-                            csharpMatchLines,
-                            csharpGateRawStartColumn,
-                            startLine,
-                            bodyStartLine,
-                            bodyEndLine,
-                            kind);
-                        var signature = signatureResult.Signature;
-                        kind = signatureResult.Kind;
-                        var csharpSingleLineCollapsedMatch = signatureResult.Bounds.CSharpSingleLineCollapsedMatch;
-                        var csharpSignatureRawStartColumn = signatureResult.Bounds.CSharpSignatureRawStartColumn;
-                        var sameLineEndColumn = signatureResult.Bounds.SameLineEndColumn;
-                        var sameLineEndUsesRawColumns = signatureResult.Bounds.SameLineEndUsesRawColumns;
-
-                        kind = EmitPatternSymbols(
-                            new PatternSymbolEmissionContext(
-                                fileId,
-                                lang,
-                                pattern,
-                                lines,
-                                i,
-                                lineOffset,
-                                absoluteStartColumn,
-                                line,
-                                patternMatchLine,
-                                match,
-                                name,
-                                kind,
-                                signature,
-                                rawReturnType,
-                                pythonSubKind,
-                                pythonModulePrefix,
-                                rubyAttrNames,
-                                new PatternSymbolRange(endLine, bodyStartLine, bodyEndLine),
-                                signatureResult.Bounds,
-                                symbols,
-                                extractionState,
-                                cssSeenSymbols,
-                                dockerfileStageNames));
-
-                        if (lang == "css"
-                            && pattern.Kind == "namespace"
-                            && pattern.BodyStyle == BodyStyle.Brace
-                            && cssScannerLines != null)
-                        {
-                            TryAddCssMediaFeatureSymbols(
-                                fileId,
-                                line,
-                                cssScannerLines[i],
-                                i,
-                                symbols,
-                                cssSeenSymbols);
-                        }
-
-                        if (lang == "css"
-                            && pattern.Kind == "class"
-                            && pattern.BodyStyle == BodyStyle.Brace
-                            && cssScannerLines != null)
-                        {
-                            var openingBraceIndex = cssScannerLines[i].IndexOf('{', absoluteStartColumn);
-                            if (openingBraceIndex > absoluteStartColumn)
-                            {
-                                TryAddCssSelectorListSegments(
-                                    fileId,
-                                    line[absoluteStartColumn..openingBraceIndex],
-                                    cssScannerLines[i][absoluteStartColumn..openingBraceIndex],
-                                    cssScannerLines,
-                                    i,
-                                    openingBraceIndex,
-                                    applicablePatterns,
-                                    symbols,
-                                    cssSeenSymbols,
-                                    applyRequiredLiteralMatchInputGate,
-                                    requiredLiteralGateCounts);
-                            }
-                        }
-
-                        if (lang == "csharp"
-                            && pattern.Kind == "property"
-                            && csharpPropertyCandidate.ExpressionBodyEndLineIndex.HasValue)
-                        {
-                            var expressionEndLineIndex = csharpPropertyCandidate.ExpressionBodyEndLineIndex.Value;
-                            if (expressionEndLineIndex > i
-                                && csharpPropertyCandidate.ExpressionBodyEndLineExclusiveEndColumn.HasValue)
-                            {
-                                // Suppress complete continuation lines, but resume after the
-                                // terminating semicolon so a valid same-line sibling remains visible.
-                                // 完全な continuation 行だけを抑止し、終端 semicolon の後から
-                                // 再開して有効な same-line sibling を維持する。
-                                scanState.CSharpSuppressedContinuationUntil = Math.Max(
-                                    scanState.CSharpSuppressedContinuationUntil,
-                                    expressionEndLineIndex - 1);
-                                scanState.CSharpSuppressedContinuationResumeLine = expressionEndLineIndex;
-                                scanState.CSharpSuppressedContinuationResumeRawColumn =
-                                    csharpPropertyCandidate.ExpressionBodyEndLineExclusiveEndColumn.Value;
-                            }
-                            else
-                            {
-                                scanState.CSharpSuppressedContinuationUntil = Math.Max(
-                                    scanState.CSharpSuppressedContinuationUntil,
-                                    expressionEndLineIndex);
-                            }
-                        }
-
-                        if (lang == "csharp"
-                            && pattern.Kind is "event" or "delegate"
-                            && pattern.BodyStyle == BodyStyle.None
-                            && (TryGetCSharpSameLineEventSiblingOffset(patternMatchLine, absoluteStartColumn, out var nextSemicolonSiblingOffset)
-                                || TryGetCSharpSameLineSemicolonSiblingOffset(patternMatchLine, absoluteStartColumn, out nextSemicolonSiblingOffset)))
-                        {
-                            restartPatternScanOffset = nextSemicolonSiblingOffset;
-                            break;
-                        }
-
-                        if (lang == "java"
-                            && pattern.BodyStyle == BodyStyle.Brace
-                            && bodyStartLine == null
-                            && TryGetJavaSameLineSemicolonSiblingOffset(patternMatchLine, absoluteStartColumn, out var nextJavaSiblingOffset))
-                        {
-                            // Body-less Java members inside `interface` / `@interface` / abstract-style
-                            // declarations can share one physical line (`String[] value(); int age();`).
-                            // Restart at the next sibling after the top-level `;` instead of stopping at
-                            // the first match, or later members on the same line disappear. Closes #788.
-                            // Java の body-less member（`interface` / `@interface` / abstract 形）は
-                            // `String[] value(); int age();` のように 1 行へ並ぶ。top-level `;`
-                            // の直後から sibling へ再開しないと、同一行の後続 member が最初の 1 個で
-                            // 途切れて消える。Closes #788.
-                            restartPatternScanOffset = nextJavaSiblingOffset;
-                            break;
-                        }
-                        if (lang is "prolog" or "ambiguous_pl"
-                            && pattern.Kind == "function"
-                            && TryGetNextPrologClauseOffset(
-                                patternMatchLine,
-                                absoluteStartColumn,
-                                out var nextPrologClauseOffset))
-                        {
-                            restartPatternScanOffset = nextPrologClauseOffset;
-                            break;
-                        }
-
-                        CollectRecordPrimaryComponentSymbols(
-                            fileId,
-                            lang,
-                            lines,
-                            i,
-                            absoluteStartColumn,
-                            kind,
-                            name,
-                            ref pendingRecordPrimaryComponents,
-                            ref recordPrimaryComponentParentIndex,
-                            symbols);
-
-                        // C# plain-field matches (internally tagged as `property`, BodyStyle.None,
-                        // then normalized to public `field`) need their own advance path. The
-                        // generic `sameLineEndColumn`-based advance below resolves
-                        // to -1 for BodyStyle.None and would set `stopAfterFirstPatternMatch`, which
-                        // prevents structural siblings on the same line (e.g. the enclosing
-                        // `public class C` in `public class C { public int X; }`) from being
-                        // captured by later patterns. Instead, advance past the field terminator
-                        // and continue the same-pattern scan so multiple same-line fields are
-                        // still collected, and skip the stop flag so later patterns can still run.
-                        // Closes #400.
-                        // C# 通常フィールド（内部タグは `property`、BodyStyle.None、公開時に
-                        // `field` へ正規化）は専用の前進経路を使う。
-                        // 既定の `sameLineEndColumn` ベースの前進は BodyStyle.None では -1 に落ち、
-                        // `stopAfterFirstPatternMatch` を立ててしまうため、同一行に存在する構造宣言
-                        // （例: `public class C { public int X; }` の外側 class）を後続パターンで
-                        // 取得できなくなる。代わりにフィールド終端を越えて同一パターンのスキャンを
-                        // 続け、stop フラグを立てずに次のパターンにも機会を残す。Closes #400.
-                        if (lang == "csharp"
-                            && pattern.Kind == "property"
-                            && pattern.BodyStyle == BodyStyle.None)
-                        {
-                            // Advance past the end of the full field declaration statement
-                            // (the top-level `;`, with paren / bracket / brace depth tracking
-                            // so `{` / `;` inside an initializer cannot short-circuit the
-                            // scan) and continue. Using the statement end rather than the
-                            // regex match end keeps later same-line field statements visible
-                            // to the same pattern: without this, `A = 1; B;` stopped after
-                            // capturing `A` and dropped `B`, and `A, B; C;` stopped after
-                            // expanding `A, B` as a declarator list and dropped `C`. It also
-                            // avoids the earlier regression where advancing to the match end
-                            // (which sits on `=` when the field has an initializer) made the
-                            // regex re-match the tail `1, _b, _c =` as a bogus field with
-                            // `return_type = "1, _b,"`. If the scanner hits an unbalanced
-                            // `}` (the closing brace of the enclosing type body) before a
-                            // `;`, break out without setting `stopAfterFirstPatternMatch` so
-                            // later unrelated patterns on the same line still get a chance
-                            // to run. Closes #400.
-                            // フィールド宣言文全体の終端（`;`、paren / bracket / brace 深さを
-                            // 追って初期化子内の `{` や `;` で途切れないようにする）まで進めて
-                            // 同一パターンで scan を続ける。regex match の末尾ではなく文の
-                            // 終端で advance するのが肝心で、これが無いと `A = 1; B;` は
-                            // `A` を拾った時点で止まって `B` を取り落とし、`A, B; C;` は
-                            // `A, B` を declarator list として展開した時点で `C` を取り落とす。
-                            // さらに、match の末尾（初期化子付きなら `=`）まで進めて continue
-                            // すると正規表現が残りの `1, _b, _c =` を `return_type = "1, _b,"`
-                            // の偽フィールドとして再マッチしていた旧 regression も再発しない。
-                            // `;` より先に囲む型本体の閉じ `}`（深さ 0）に到達した場合は、
-                            // `stopAfterFirstPatternMatch` を立てずに break して同一行の他
-                            // パターン（class 等）へ機会を残す。Closes #400.
-                            var statementEnd = FindCSharpSameLineStatementEnd(patternMatchLine, absoluteStartColumn);
-                            if (statementEnd < patternMatchLine.Length
-                                && patternMatchLine[statementEnd] == '}')
-                            {
-                                break;
-                            }
-                            // Only continue the same-pattern same-line scan when the regex
-                            // ran on a per-line single-line candidate (patternMatchLine ===
-                            // csharpMatchLines[i]). For multi-line merged candidates,
-                            // BuildCSharpPropertyMatchLine joined the header line with one
-                            // or more continuation lines, so absoluteStartColumn sits in
-                            // the merged-string column domain and does not line up with
-                            // lines[i]'s raw columns. Continuing past statementEnd into a
-                            // second regex hit would then feed a column > lines[i].Length
-                            // into BuildCSharpMultilineSignature (which slices
-                            // lines[startLineIndex][startColumn..]) and crash indexing with
-                            // `startIndex cannot be larger than length of string`. The
-                            // continuation line is revisited by the outer physical-line
-                            // loop anyway (csharpSuppressedContinuationUntil is only bumped
-                            // for expression-bodied properties), so for multi-line merged
-                            // candidates we break here and let the outer loop handle any
-                            // additional fields on that line. Closes #400.
-                            // same-pattern での同一行 scan 継続は、per-line の単一行候補
-                            // （patternMatchLine === csharpMatchLines[i]）のときだけ許す。
-                            // BuildCSharpPropertyMatchLine が header 行と continuation 行を
-                            // マージした複数行候補では、absoluteStartColumn がマージ後文字列の
-                            // 列を指しており lines[i] の raw 列として使えない。この状態で
-                            // statementEnd を越えて 2 個目の regex ヒットに進むと、
-                            // BuildCSharpMultilineSignature の lines[startLineIndex][startColumn..]
-                            // で範囲外アクセスとなり
-                            // 「startIndex cannot be larger than length of string」で indexing が
-                            // 落ちる。continuation 行は外側の物理行ループが再訪する
-                            // （csharpSuppressedContinuationUntil は expression-bodied property
-                            // でしか進まない）ため、複数行候補ではここで break して後続の
-                            // 同一行フィールド抽出を外側ループに任せる。Closes #400.
-                            if (csharpMatchLines == null
-                                || !ReferenceEquals(patternMatchLine, csharpMatchLines[i]))
-                            {
-                                break;
-                            }
-                            var advance = statementEnd;
-                            if (advance <= lineOffset)
-                                advance = lineOffset + 1;
-                            if (advance >= patternMatchLine.Length)
-                                break;
-                            lineOffset = advance;
-                            continue;
-                        }
-
-                        if (!CanContinueScanningSameLineBraceBody(lang, kind, pattern.BodyStyle, bodyEndLine, startLine, sameLineEndColumn, absoluteStartColumn))
-                        {
-                            if (lang == "csharp"
-                                && pattern.BodyStyle == BodyStyle.Brace
-                                && bodyStartLine == startLine
-                                && kind is "class" or "struct" or "interface" or "enum" or "namespace")
-                            {
-                                // Hybrid same-line C# type headers can open the body on the header
-                                // line and still close on a later line (`class C { int P { get; }`
-                                // + next-line `}`). They are not compact same-line bodies, so the
-                                // generic same-line brace-body path does not restart inside them.
-                                // Explicitly restart just after the opening `{` so the first member
-                                // that shares the header line is still visible to the full pattern
-                                // list. Closes #580.
-                                // ハイブリッドな C# の same-line 型ヘッダは、本体開始 `{` がヘッダ行に
-                                // ありつつ閉じ `}` は後続行に置かれうる (`class C { int P { get; }`
-                                // + 次行 `}`)。これは compact な same-line body ではないため、
-                                // 既定の same-line brace-body 経路だけでは本体内へ再開できない。
-                                // そこで開始 `{` の直後から明示的に再開し、ヘッダ行を共有する最初の
-                                // member も通常の pattern 列で拾えるようにする。Closes #580.
-                                var nextHeaderLineMemberOffset = FindNextSameLineNonClosingBraceStatementStart(
-                                    matchLine,
-                                    absoluteStartColumn + Math.Max(1, match.Length),
-                                    lang);
-                                if (nextHeaderLineMemberOffset > absoluteStartColumn
-                                    && nextHeaderLineMemberOffset < matchLine.Length)
-                                {
-                                    restartPatternScanOffset = nextHeaderLineMemberOffset;
-                                    break;
-                                }
-                            }
-
-                            if (lang == "csharp"
-                                && sameLineEndColumn >= absoluteStartColumn
-                                && CanRestartCSharpSameLineSiblingScan(kind))
-                            {
-                                // Compact same-line C# members form a sibling stream rather than a
-                                // single terminal match: after `event E;`, `void M();`, or
-                                // `int P { get; set; }`, later same-line declarations still need
-                                // to reach earlier patterns in the list. Restart from the next
-                                // top-level statement boundary so mixed-kind siblings like
-                                // `event + property`, `method + property`, and `property + event`
-                                // are all visible. When there is no later statement, keep the old
-                                // stop-after-first-match behavior to avoid reopening duplicate
-                                // paths on ordinary single-declaration lines. Closes #470 / #473.
-                                // 同一行のコンパクトな C# member は 1 回限りの terminal match ではなく、
-                                // sibling 宣言のストリームとして扱う。`event E;` や `void M();`、
-                                // `int P { get; set; }` の後ろに続く宣言も、pattern 列の先頭側にある
-                                // property などへ到達できる必要がある。そこで次の top-level 文境界から
-                                // pattern 列全体を再走査し、`event + property`、`method + property`、
-                                // `property + event` のような mixed-kind sibling をすべて可視化する。
-                                // 後続宣言が無い行では従来どおり stop-after-first-match を維持し、
-                                // 通常の単独宣言行で duplicate 経路を再び開かない。Closes #470 / #473.
-                                if (csharpSingleLineCollapsedMatch && sameLineEndUsesRawColumns)
-                                {
-                                    var rawNextSiblingOffset = FindNextSameLineNonClosingBraceStatementStart(line, sameLineEndColumn + 1, lang);
-                                    if (rawNextSiblingOffset > sameLineEndColumn)
-                                    {
-                                        restartPatternScanOffset = TranslateCSharpRawColumnToCollapsed(
-                                            csharpMatchColumnToRaw,
-                                            i,
-                                            rawNextSiblingOffset,
-                                            matchLine.Length,
-                                            line.Length);
-                                        break;
-                                    }
-                                }
-                                else
-                                {
-                                    var nextSiblingOffset = FindNextSameLineNonClosingBraceStatementStart(matchLine, sameLineEndColumn + 1, lang);
-                                    if (nextSiblingOffset > sameLineEndColumn
-                                        && nextSiblingOffset < matchLine.Length)
-                                    {
-                                        restartPatternScanOffset = nextSiblingOffset;
-                                        break;
-                                    }
-                                }
-                            }
-
-                            // Batch `set` assignments can legitimately repeat on a single line via
-                            // `&` command-chaining (`set A=1 & set B=2`), parenthesized grouping
-                            // (`if ... ( set P=1 ) else set Q=2`), or `for`-loop bodies
-                            // (`for %%I in (1) do set LOOPVAR=%%I`). The brace-body rescan path
-                            // above is JS/TS/CSS/C#-only, so drive the advance explicitly for the
-                            // batch property pattern instead of short-circuiting after the first
-                            // match. Forward progress is guaranteed because `match.Length >= 1`
-                            // (the regex requires a literal `set\s+NAME=` tail).
-                            // batch の `set` 代入は `&` 連結や `( ... ) else ... `、`for ... do ...` で
-                            // 1 行に複数回現れうる。上の brace-body 再スキャンは JS/TS/CSS/C# 限定なので、
-                            // batch の property パターンだけは explicit に advance して追加マッチも拾う。
-                            // 前進は `match.Length >= 1` (正規表現が `set\s+NAME=` を要求するため) で保証される。
-                            if (lang == "batch"
-                                && pattern.BodyStyle == BodyStyle.None
-                                && pattern.Kind == "property")
-                            {
-                                var nextBatchOffset = absoluteStartColumn + Math.Max(1, match.Length);
-                                if (nextBatchOffset <= lineOffset)
-                                    break;
-                                lineOffset = nextBatchOffset;
-                                continue;
-                            }
-
-                            // Stop after first match per line to avoid duplicate symbols
-                            // (e.g. C# method pattern + constructor pattern both matching)
-                            // 1行につき最初のマッチのみ採用し重複を防ぐ
-                            stopAfterFirstPatternMatch = true;
-                            break;
-                        }
-
-                        // For C# class-like kinds with a same-line brace body, step into the body
-                        // (advance just past the match header) instead of jumping past the closing
-                        // `}`. This lets nested same-line declarations be captured, e.g.
-                        // `public class Outer { public class Inner { public int X; } }` matches
-                        // Outer and Inner, with X correctly attached to Inner. JavaScript/TypeScript
-                        // does not need this because class-body members there are extracted via the
-                        // separate JS/TS lexer/state machine; the brace-skip path only handles
-                        // same-line siblings like `class A {} class B {}`. Closes #400.
-                        // C# の class 系 kind は同一行の `{...}` 本体を飛び越えず、ヘッダ直後へ
-                        // 進めて本体内部の宣言（例: `public class Outer { public class Inner { ... } }`
-                        // の Inner）を拾えるようにする。JavaScript/TypeScript は class body の
-                        // member 抽出を専用 lexer/state machine で行うため従来通り終端の後ろへ
-                        // 進め、同一行 sibling（`class A {} class B {}` など）だけを扱う。Closes #400.
-                        var sameLineRestartComparisonColumn = csharpSingleLineCollapsedMatch && sameLineEndUsesRawColumns
-                            ? TranslateCSharpRawColumnToCollapsed(
-                                csharpMatchColumnToRaw,
-                                i,
-                                sameLineEndColumn,
-                                matchLine.Length,
-                                line.Length)
-                            : sameLineEndColumn;
-                        if (CanStepIntoSameLineTypeBody(lang, kind))
-                        {
-                            var nextTypeBodyOffset = FindNextSameLineNonClosingBraceStatementStart(
-                                matchLine,
-                                absoluteStartColumn + Math.Max(1, match.Length),
-                                lang);
-                            if (nextTypeBodyOffset > absoluteStartColumn
-                                && nextTypeBodyOffset < sameLineRestartComparisonColumn
-                                && (nextTypeBodyOffset >= matchLine.Length || matchLine[nextTypeBodyOffset] != '}'))
-                            {
-                                restartPatternScanOffset = nextTypeBodyOffset;
-                                break;
-                            }
-                        }
-
-                        var nextSameLineOffset = -1;
-                        if (csharpSingleLineCollapsedMatch && sameLineEndUsesRawColumns)
-                        {
-                            var rawNextSameLineOffset = FindNextSameLineNonClosingBraceStatementStart(line, sameLineEndColumn + 1, lang);
-                            if (rawNextSameLineOffset > sameLineEndColumn)
-                            {
-                                nextSameLineOffset = TranslateCSharpRawColumnToCollapsed(
-                                    csharpMatchColumnToRaw,
-                                    i,
-                                    rawNextSameLineOffset,
-                                    matchLine.Length,
-                                    line.Length);
-                            }
-                        }
-                        else
-                        {
-                            nextSameLineOffset = FindNextSameLineNonClosingBraceStatementStart(matchLine, sameLineEndColumn + 1, lang);
-                        }
-                        var sameLineAdvanceComparisonColumn = sameLineRestartComparisonColumn;
-                        if (CanStepIntoSameLineTypeBody(lang, kind)
-                            && nextSameLineOffset > sameLineAdvanceComparisonColumn
-                            && nextSameLineOffset < matchLine.Length
-                            && matchLine[nextSameLineOffset] != '}')
-                        {
-                            restartPatternScanOffset = nextSameLineOffset;
-                            break;
-                        }
-                        if (lang == "csharp"
-                            && kind == "property"
-                            && pattern.BodyStyle == BodyStyle.Brace
-                            && nextSameLineOffset > sameLineAdvanceComparisonColumn
-                            && nextSameLineOffset < matchLine.Length)
-                        {
-                            // A same-line brace-body property that is followed by another sibling
-                            // declaration (`P { get; set; } public void M() { }`) must hand control
-                            // back to the whole pattern list at the next statement start, otherwise
-                            // earlier rows like the C# method regex never get a chance to see the
-                            // trailing sibling and mixed-kind lines lose one side.
-                            // Closes #473 follow-up.
-                            // 後続 sibling 宣言を伴う same-line brace-body property
-                            // (`P { get; set; } public void M() { }`) は、次の文開始位置から
-                            // pattern 全体へ制御を戻す必要がある。そうしないと、C# method regex
-                            // のような earlier row が後続 sibling を見られず、mixed-kind の
-                            // 同一行で片側が欠落する。Closes #473 follow-up.
-                            restartPatternScanOffset = nextSameLineOffset;
-                            break;
-                        }
-
-                        lineOffset = nextSameLineOffset;
-                    }
-
-                    if (restartPatternScanOffset >= 0 || stopAfterFirstPatternMatch)
-                        break;
-                }
-
-                if (restartPatternScanOffset >= 0)
-                {
-                    if (restartPatternScanOffset <= patternStartOffset)
-                        break;
-
-                    patternStartOffset = restartPatternScanOffset;
-                    continue;
-                }
-
-                break;
-            }
-
-            if (lang == "css" && cssScannerLine != null)
-            {
-                if (cssScannerLine.IndexOf("--", StringComparison.Ordinal) >= 0)
-                {
-                    foreach (Match match in Regex.EnumerateMatches(CssInlineCustomPropertyRegex, cssScannerLine))
-                    {
-                        var propertyName = match.Groups["name"].ValueSpan.Trim().ToString();
-                        if (propertyName.Length == 0)
-                            continue;
-
-                        AddSymbolRecord(
-                            symbols,
-                            extractionState,
-                            cssSeenSymbols,
-                            i + 1,
-                            new SymbolRecord
-                            {
-                                FileId = fileId,
-                                Kind = "property",
-                                Name = propertyName,
-                                Line = i + 1,
-                                StartLine = i + 1,
-                                EndLine = i + 1,
-                                Signature = line.Trim(),
-                            });
-                    }
-                }
-
-                ExtractCssInlineGroupingSelectors(
-                    fileId,
-                    line,
-                    cssScannerLine,
-                    cssScannerLines!,
-                    i,
-                    applicablePatterns,
-                    symbols,
-                    cssSeenSymbols);
-            }
-        }
+        if (preparation.ImmediateSymbols != null)
+            return preparation.ImmediateSymbols;
 
-        if (!symbols.IsAtCapacity)
-        {
-            AddSupplementalSymbols(
-                fileId,
-                originalLang,
-                lang,
-                content,
-                filePath,
-                lines,
-                structuralLines,
-                symbols,
-                extractionState,
-                getPrivateScopeColumns,
-                GetJavaScriptTypeScriptSanitizedLines,
-                csharpMatchLines,
-                pythonModulePrefix,
-                prologMultilineHeads,
-                applicablePatterns,
-                applyRequiredLiteralMatchInputGate,
-                requiredLiteralGateCounts);
-        }
-        if (lang == "csharp")
-        {
-            PopulateCSharpPartialDeclarationMetadata(
-                lines,
-                symbols,
-                getCSharpLineStartStates);
-        }
-        FinalizePatternSymbols(
-            fileId,
-            lang,
-            filePath,
-            projectRoot,
-            lines,
-            symbols,
-            extractionState,
-            getCSharpLineStartStates,
-            pendingRecordPrimaryComponents);
-        return symbols;
+        var context = preparation.Context!;
+        ScanPatternLines(context);
+        CompletePatternExtraction(context);
+        return context.Symbols;
     }
 
     private static IReadOnlyList<SymbolPattern> SelectApplicablePatterns(
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternCandidates.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternCandidates.cs
new file mode 100644
index 000000000..5e953958a
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternCandidates.cs
@@ -0,0 +1,199 @@
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+    private static PatternSymbolDraft BuildPatternSymbolDraft(
+        MatchedPatternCandidateContext candidate,
+        PatternCandidateColumns columns,
+        string? rawReturnType)
+    {
+        var lineContext = candidate.LineContext;
+        var extraction = lineContext.Extraction;
+        var lang = extraction.Lang;
+        var filePath = extraction.FilePath;
+        var projectRoot = extraction.ProjectRoot;
+        var pattern = candidate.Pattern;
+        var patternMatchLine = candidate.PatternMatchLine;
+        var matchLine = lineContext.PreparedLine.MatchLine;
+        var match = candidate.CapturedMatch.Match;
+        var absoluteStartColumn = candidate.CapturedMatch.AbsoluteStartColumn;
+        var csharpPropertyCandidate = candidate.CSharpPropertyCandidate;
+        var csharpGateRawStartColumn = columns.CSharpGateRawStartColumn;
+        var lines = extraction.Lines;
+        var line = lineContext.PreparedLine.SourceLine;
+        var i = lineContext.LineIndex;
+        var fortranContinuationCandidate = lineContext.PreparedLine.FortranContinuationCandidate;
+        var scanInputs = extraction.ScanInputs;
+        var structuralLines = scanInputs.StructuralLines;
+        var scientificBodyScannerLines = scanInputs.ScientificBodyScannerLines;
+        var matlabExplicitOuterClosureByLine = scanInputs.MatlabExplicitOuterClosureByLine;
+        var cssScannerLines = scanInputs.CssScannerLines;
+        var shellScannerLines = scanInputs.ShellScannerLines;
+        var csharpMatchLines = scanInputs.CSharpMatchLines;
+        var getCSharpLineStartStates = scanInputs.GetCSharpLineStartStates;
+        var name = match.Groups["name"].Success
+            ? match.Groups["name"].ValueSpan.Trim().ToString()
+            : match.ValueSpan.Trim().ToString();
+        name = NormalizeExtractedSymbolName(lang, name, match, matchLine);
+        if (pattern.Kind == "import" && lang is "javascript" or "typescript")
+            name = ResolveJavaScriptTypeScriptModuleSpecifier(lang, filePath, projectRoot, name);
+        var rubyAttrNames = lang == "ruby"
+            && pattern.Kind == "property"
+            ? TryExpandRubyAttrDeclaratorList(patternMatchLine, absoluteStartColumn, match, name)
+            : null;
+
+        var rangeLines = lang == "css" && cssScannerLines != null
+            ? cssScannerLines
+            : lang == "shell" && shellScannerLines != null
+                ? shellScannerLines
+            : structuralLines;
+        var scalaBracelessClassEndLine = lang == "scala" && pattern.Kind == "class"
+            ? TryFindScalaBracelessClassEndLine(lines, i, absoluteStartColumn)
+            : null;
+        var (endLine, bodyStartLine, bodyEndLine) = lang is "kotlin" or "scala"
+            && pattern.Kind == "function"
+            && TryFindKotlinScalaExpressionBodyEndLine(line, absoluteStartColumn)
+                ? (i + 1, null, null)
+                : scalaBracelessClassEndLine.HasValue
+                        ? (scalaBracelessClassEndLine.Value + 1, null, null)
+                        : lang == "csharp" && pattern.BodyStyle == BodyStyle.Brace && csharpMatchLines != null
+                            ? FindCSharpPatternBraceRange(
+                                lines,
+                                csharpMatchLines,
+                                getCSharpLineStartStates,
+                                i,
+                                absoluteStartColumn,
+                                csharpGateRawStartColumn)
+                            : ResolveRange(
+                                rangeLines,
+                                i,
+                                pattern.BodyStyle,
+                                lang,
+                                absoluteStartColumn,
+                                scientificBodyScannerLines,
+                                matlabExplicitOuterClosureByLine);
+        if (fortranContinuationCandidate != null)
+            endLine = Math.Max(endLine, fortranContinuationCandidate.Value.LastConsumedLineIndex + 1);
+        var startLine = i + 1;
+        if (lang == "csharp"
+            && pattern.Kind == "property"
+            && pattern.BodyStyle == BodyStyle.None
+            && csharpPropertyCandidate.ExpressionBodyEndLineIndex.HasValue)
+        {
+            endLine = Math.Max(endLine, csharpPropertyCandidate.ExpressionBodyEndLineIndex.Value + 1);
+        }
+
+        return new PatternSymbolDraft(
+            name,
+            rawReturnType,
+            rubyAttrNames,
+            startLine,
+            endLine,
+            bodyStartLine,
+            bodyEndLine);
+    }
+
+    private static PatternScanResult TryShapePatternSymbol(
+        MatchedPatternCandidateContext candidate,
+        PatternCandidateColumns columns,
+        PatternSymbolDraft draft,
+        out ShapedPatternSymbol shapedSymbol)
+    {
+        shapedSymbol = default;
+        var lineContext = candidate.LineContext;
+        var extraction = lineContext.Extraction;
+        var lang = extraction.Lang;
+        var pattern = candidate.Pattern;
+        var patternMatchLine = candidate.PatternMatchLine;
+        var matchLine = lineContext.PreparedLine.MatchLine;
+        var lineOffset = candidate.LineOffset;
+        var match = candidate.CapturedMatch.Match;
+        var absoluteStartColumn = candidate.CapturedMatch.AbsoluteStartColumn;
+        var csharpPropertyCandidate = candidate.CSharpPropertyCandidate;
+        var csharpWrappedModifierPrefix = candidate.CSharpWrappedModifierPrefix;
+        var csharpGateRawStartColumn = columns.CSharpGateRawStartColumn;
+        var lines = extraction.Lines;
+        var line = lineContext.PreparedLine.SourceLine;
+        var i = lineContext.LineIndex;
+        var scanInputs = extraction.ScanInputs;
+        var csharpMatchColumnToRaw = scanInputs.CSharpMatchColumnToRaw;
+        var csharpMatchLines = scanInputs.CSharpMatchLines;
+        var name = draft.Name;
+        var startLine = draft.StartLine;
+        var endLine = draft.EndLine;
+        var bodyStartLine = draft.BodyStartLine;
+        var bodyEndLine = draft.BodyEndLine;
+        // Python @property decorator: reclassify the def as property
+        // Python @property デコレータ: def を property に再分類
+        var kind = pattern.Kind;
+        string? pythonSubKind = null;
+        if (kind == "function" && lang == "python" && HasPythonPropertyDecorator(lines, i))
+        {
+            kind = "property";
+            pythonSubKind = GetPythonPropertyAccessorSubKind(lines, i);
+        }
+        else if (kind == "function" && lang == "python" && IsPythonClassHook(name))
+        {
+            kind = "class_hook";
+            pythonSubKind = "dunder";
+            (endLine, bodyStartLine, bodyEndLine) = FindPythonIndentedBodyRange(lines, i);
+        }
+        else if (kind == "function" && lang is "javascript" or "typescript")
+        {
+            kind = ResolveJavaScriptTypeScriptFunctionKind(
+                TryGetGroup(match, "async") != null,
+                TryGetGroup(match, "generator") != null);
+        }
+
+        if (lang == "css")
+            name = ResolveCssSymbolName(matchLine[absoluteStartColumn..], name, lines, i, endLine);
+
+        if (lang == "css" && string.IsNullOrWhiteSpace(name))
+        {
+            var skippedEndColumn = pattern.BodyStyle == BodyStyle.Brace
+                && bodyEndLine == startLine
+                ? FindSameLineBraceEndColumn(line, absoluteStartColumn, lang, kind)
+                : -1;
+            if (skippedEndColumn >= absoluteStartColumn)
+            {
+                lineOffset = FindNextSameLineBraceStatementStart(matchLine, skippedEndColumn + 1, lang);
+                return PatternScanResult.ContinueAt(lineOffset);
+            }
+
+            return PatternScanResult.StopLine;
+        }
+
+        var signatureResult = BuildPatternSignature(
+            lang,
+            pattern,
+            lines,
+            i,
+            line,
+            patternMatchLine,
+            absoluteStartColumn,
+            match,
+            csharpPropertyCandidate,
+            csharpWrappedModifierPrefix,
+            csharpMatchColumnToRaw,
+            csharpMatchLines,
+            csharpGateRawStartColumn,
+            startLine,
+            bodyStartLine,
+            bodyEndLine,
+            kind);
+        kind = signatureResult.Kind;
+
+        shapedSymbol = new ShapedPatternSymbol(
+            name,
+            kind,
+            draft.RawReturnType,
+            pythonSubKind,
+            draft.RubyAttributeNames,
+            startLine,
+            endLine,
+            bodyStartLine,
+            bodyEndLine,
+            signatureResult);
+        return PatternScanResult.Accepted;
+    }
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternEmissionFlow.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternEmissionFlow.cs
new file mode 100644
index 000000000..f67384b9e
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternEmissionFlow.cs
@@ -0,0 +1,186 @@
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+    private static PatternScanResult EmitAcceptedPatternSymbol(
+        MatchedPatternCandidateContext candidate,
+        ShapedPatternSymbol shapedSymbol,
+        out string emittedKind)
+    {
+        var lineContext = candidate.LineContext;
+        var extraction = lineContext.Extraction;
+        var fileId = extraction.FileId;
+        var lang = extraction.Lang;
+        var pattern = candidate.Pattern;
+        var lines = extraction.Lines;
+        var i = lineContext.LineIndex;
+        var lineOffset = candidate.LineOffset;
+        var absoluteStartColumn = candidate.CapturedMatch.AbsoluteStartColumn;
+        var line = lineContext.PreparedLine.SourceLine;
+        var patternMatchLine = candidate.PatternMatchLine;
+        var match = candidate.CapturedMatch.Match;
+        var name = shapedSymbol.Name;
+        var kind = shapedSymbol.Kind;
+        var signature = shapedSymbol.SignatureResult.Signature;
+        var rawReturnType = shapedSymbol.RawReturnType;
+        var pythonSubKind = shapedSymbol.PythonSubKind;
+        var pythonModulePrefix = extraction.ScanInputs.PythonModulePrefix;
+        var rubyAttrNames = shapedSymbol.RubyAttributeNames;
+        var endLine = shapedSymbol.EndLine;
+        var bodyStartLine = shapedSymbol.BodyStartLine;
+        var bodyEndLine = shapedSymbol.BodyEndLine;
+        var signatureResult = shapedSymbol.SignatureResult;
+        var csharpPropertyCandidate = candidate.CSharpPropertyCandidate;
+        var scanInputs = extraction.ScanInputs;
+        var cssScannerLines = scanInputs.CssScannerLines;
+        var applicablePatterns = extraction.ApplicablePatterns;
+        var applyRequiredLiteralMatchInputGate = extraction.ApplyRequiredLiteralMatchInputGate;
+        var requiredLiteralGateCounts = extraction.RequiredLiteralGateCounts;
+        var symbols = extraction.Symbols;
+        var extractionState = extraction.ExtractionState;
+        var cssSeenSymbols = extraction.CssSeenSymbols;
+        var dockerfileStageNames = extraction.DockerfileStageNames;
+        var scanState = extraction.ScanState;
+        ref var pendingRecordPrimaryComponents = ref extraction.PendingRecordPrimaryComponents;
+        ref var recordPrimaryComponentParentIndex = ref extraction.RecordPrimaryComponentParentIndex;
+        emittedKind = kind;
+        kind = EmitPatternSymbols(
+            new PatternSymbolEmissionContext(
+                fileId,
+                lang,
+                pattern,
+                lines,
+                i,
+                lineOffset,
+                absoluteStartColumn,
+                line,
+                patternMatchLine,
+                match,
+                name,
+                kind,
+                signature,
+                rawReturnType,
+                pythonSubKind,
+                pythonModulePrefix,
+                rubyAttrNames,
+                new PatternSymbolRange(endLine, bodyStartLine, bodyEndLine),
+                signatureResult.Bounds,
+                symbols,
+                extractionState,
+                cssSeenSymbols,
+                dockerfileStageNames));
+
+        if (lang == "css"
+            && pattern.Kind == "namespace"
+            && pattern.BodyStyle == BodyStyle.Brace
+            && cssScannerLines != null)
+        {
+            TryAddCssMediaFeatureSymbols(
+                fileId,
+                line,
+                cssScannerLines[i],
+                i,
+                symbols,
+                cssSeenSymbols);
+        }
+
+        if (lang == "css"
+            && pattern.Kind == "class"
+            && pattern.BodyStyle == BodyStyle.Brace
+            && cssScannerLines != null)
+        {
+            var openingBraceIndex = cssScannerLines[i].IndexOf('{', absoluteStartColumn);
+            if (openingBraceIndex > absoluteStartColumn)
+            {
+                TryAddCssSelectorListSegments(
+                    fileId,
+                    line[absoluteStartColumn..openingBraceIndex],
+                    cssScannerLines[i][absoluteStartColumn..openingBraceIndex],
+                    cssScannerLines,
+                    i,
+                    openingBraceIndex,
+                    applicablePatterns,
+                    symbols,
+                    cssSeenSymbols,
+                    applyRequiredLiteralMatchInputGate,
+                    requiredLiteralGateCounts);
+            }
+        }
+
+        if (lang == "csharp"
+            && pattern.Kind == "property"
+            && csharpPropertyCandidate.ExpressionBodyEndLineIndex.HasValue)
+        {
+            var expressionEndLineIndex = csharpPropertyCandidate.ExpressionBodyEndLineIndex.Value;
+            if (expressionEndLineIndex > i
+                && csharpPropertyCandidate.ExpressionBodyEndLineExclusiveEndColumn.HasValue)
+            {
+                // Suppress complete continuation lines, but resume after the
+                // terminating semicolon so a valid same-line sibling remains visible.
+                // 完全な continuation 行だけを抑止し、終端 semicolon の後から
+                // 再開して有効な same-line sibling を維持する。
+                scanState.CSharpSuppressedContinuationUntil = Math.Max(
+                    scanState.CSharpSuppressedContinuationUntil,
+                    expressionEndLineIndex - 1);
+                scanState.CSharpSuppressedContinuationResumeLine = expressionEndLineIndex;
+                scanState.CSharpSuppressedContinuationResumeRawColumn =
+                    csharpPropertyCandidate.ExpressionBodyEndLineExclusiveEndColumn.Value;
+            }
+            else
+            {
+                scanState.CSharpSuppressedContinuationUntil = Math.Max(
+                    scanState.CSharpSuppressedContinuationUntil,
+                    expressionEndLineIndex);
+            }
+        }
+
+        if (lang == "csharp"
+            && pattern.Kind is "event" or "delegate"
+            && pattern.BodyStyle == BodyStyle.None
+            && (TryGetCSharpSameLineEventSiblingOffset(patternMatchLine, absoluteStartColumn, out var nextSemicolonSiblingOffset)
+                || TryGetCSharpSameLineSemicolonSiblingOffset(patternMatchLine, absoluteStartColumn, out nextSemicolonSiblingOffset)))
+        {
+            return PatternScanResult.RestartAt(nextSemicolonSiblingOffset);
+        }
+
+        if (lang == "java"
+            && pattern.BodyStyle == BodyStyle.Brace
+            && bodyStartLine == null
+            && TryGetJavaSameLineSemicolonSiblingOffset(patternMatchLine, absoluteStartColumn, out var nextJavaSiblingOffset))
+        {
+            // Body-less Java members inside `interface` / `@interface` / abstract-style
+            // declarations can share one physical line (`String[] value(); int age();`).
+            // Restart at the next sibling after the top-level `;` instead of stopping at
+            // the first match, or later members on the same line disappear. Closes #788.
+            // Java の body-less member（`interface` / `@interface` / abstract 形）は
+            // `String[] value(); int age();` のように 1 行へ並ぶ。top-level `;`
+            // の直後から sibling へ再開しないと、同一行の後続 member が最初の 1 個で
+            // 途切れて消える。Closes #788.
+            return PatternScanResult.RestartAt(nextJavaSiblingOffset);
+        }
+        if (lang is "prolog" or "ambiguous_pl"
+            && pattern.Kind == "function"
+            && TryGetNextPrologClauseOffset(
+                patternMatchLine,
+                absoluteStartColumn,
+                out var nextPrologClauseOffset))
+        {
+            return PatternScanResult.RestartAt(nextPrologClauseOffset);
+        }
+
+        CollectRecordPrimaryComponentSymbols(
+            fileId,
+            lang,
+            lines,
+            i,
+            absoluteStartColumn,
+            kind,
+            name,
+            ref pendingRecordPrimaryComponents,
+            ref recordPrimaryComponentParentIndex,
+            symbols);
+
+        emittedKind = kind;
+        return PatternScanResult.Accepted;
+    }
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternExtraction.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternExtraction.cs
new file mode 100644
index 000000000..3e84e8b68
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternExtraction.cs
@@ -0,0 +1,274 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+    private readonly record struct PatternExtractionPreparation(
+        PatternExtractionContext? Context,
+        List<SymbolRecord>? ImmediateSymbols);
+
+    private sealed class PatternExtractionContext
+    {
+        public PatternExtractionContext(
+            long fileId,
+            string? originalLang,
+            string lang,
+            string content,
+            string? filePath,
+            string? projectRoot,
+            string[] lines,
+            IReadOnlyList<SymbolPattern> applicablePatterns,
+            bool applyRequiredLiteralMatchInputGate,
+            RequiredLiteralGateCounts? requiredLiteralGateCounts,
+            CancellationToken cancellationToken,
+            int? maxSymbols)
+        {
+            FileId = fileId;
+            OriginalLang = originalLang;
+            Lang = lang;
+            Content = content;
+            FilePath = filePath;
+            ProjectRoot = projectRoot;
+            Lines = lines;
+            ApplicablePatterns = applicablePatterns;
+            ApplyRequiredLiteralMatchInputGate = applyRequiredLiteralMatchInputGate;
+            RequiredLiteralGateCounts = requiredLiteralGateCounts;
+            CancellationToken = cancellationToken;
+
+            ScanInputs = new PatternScanInputs(
+                lang,
+                filePath,
+                lines,
+                applicablePatterns,
+                applyRequiredLiteralMatchInputGate,
+                requiredLiteralGateCounts);
+            GetJavaScriptTypeScriptSanitizedLines = ScanInputs.GetJavaScriptTypeScriptSanitizedLines;
+            GetDartInsideClassBody = ScanInputs.GetDartInsideClassBody;
+            GetCSharpInsideTypeBody = ScanInputs.GetCSharpInsideTypeBody;
+            GetCSharpCallableParameterScope = ScanInputs.GetCSharpCallableParameterScope;
+            GetCSharpDeclarationStartScope = ScanInputs.GetCSharpDeclarationStartScope;
+            Symbols = new SymbolExtractionList(
+                EstimateSymbolListInitialCapacity(lines.Length),
+                maxSymbols);
+            ExtractionState = Symbols.ExtractionState;
+            ScanState = new PatternScanState();
+            CssSeenSymbols = lang == "css"
+                ? new HashSet<SymbolLineIdentity>()
+                : null;
+            DockerfileStageNames = lang == "dockerfile"
+                ? new HashSet<string>(StringComparer.Ordinal)
+                : null;
+        }
+
+        public long FileId { get; }
+        public string? OriginalLang { get; }
+        public string Lang { get; }
+        public string Content { get; }
+        public string? FilePath { get; }
+        public string? ProjectRoot { get; }
+        public string[] Lines { get; }
+        public IReadOnlyList<SymbolPattern> ApplicablePatterns { get; }
+        public bool ApplyRequiredLiteralMatchInputGate { get; }
+        public RequiredLiteralGateCounts? RequiredLiteralGateCounts { get; }
+        public CancellationToken CancellationToken { get; }
+        public PatternScanInputs ScanInputs { get; }
+        public Func<string[]> GetJavaScriptTypeScriptSanitizedLines { get; }
+        public Func<DartClassBodyScope> GetDartInsideClassBody { get; }
+        public Func<CSharpTypeBodyScope> GetCSharpInsideTypeBody { get; }
+        public Func<CSharpCallableParameterScope> GetCSharpCallableParameterScope { get; }
+        public Func<CSharpDeclarationStartScope> GetCSharpDeclarationStartScope { get; }
+        public SymbolExtractionList Symbols { get; }
+        public SymbolExtractionState ExtractionState { get; }
+        public PatternScanState ScanState { get; }
+        public HashSet<SymbolLineIdentity>? CssSeenSymbols { get; }
+        public HashSet<string>? DockerfileStageNames { get; }
+        public List<PendingRecordPrimaryComponents>? PendingRecordPrimaryComponents;
+        public RecordPrimaryComponentParentIndex? RecordPrimaryComponentParentIndex;
+    }
+
+    private static PatternExtractionPreparation PreparePatternExtraction(
+        long fileId,
+        string? originalLang,
+        string? lang,
+        string content,
+        string? filePath,
+        string? projectRoot,
+        CancellationToken cancellationToken,
+        int? maxSymbols,
+        bool applyRequiredLiteralFileGate,
+        bool applyRequiredLiteralMatchInputGate,
+        RequiredLiteralGateCounts? requiredLiteralGateCounts)
+    {
+        // Normalize CRLF / CR to LF first so direct callers that bypass FileIndexer
+        // still present a `\n`-only content stream, and then strip line-leading
+        // UTF-8 BOM (U+FEFF) defensively so `^\s*`-anchored patterns match on
+        // line 1 and on any mid-file line that begins with a BOM (e.g. from file
+        // concatenation or tool insertion). StripLineLeadingBom assumes `\n` is
+        // the sole line separator, so the CRLF pass must come first. Non-line-
+        // leading U+FEFF is preserved so content with intentional ZWNBSP inside
+        // a string literal stays verbatim. Closes #183.
+        // まず CRLF / CR を LF に正規化する。StripLineLeadingBom は `\n` を唯一の
+        // 行区切りとして行頭判定するので、FileIndexer を経由しない direct call
+        // でも CRLF 正規化を済ませてから呼ばないと mid-file の行頭 BOM を剥がし
+        // 損なう。続いて行頭 U+FEFF のみ剥がし、1 行目と mid-file の行頭 BOM 両方
+        // で `^\s*` 固定パターンを成立させる。行頭以外の U+FEFF (文字列リテラル中
+        // の意図的な ZWNBSP 等) はそのまま保持する。Closes #183.
+        List<SymbolPattern>? patterns = null;
+        var usesLineBasedExtractor = lang is "commonlisp" or "racket" or "solidity" or "html" or "assembly"
+            || (lang is not null && PatternCache.TryGetValue(lang, out patterns));
+        if (!usesLineBasedExtractor)
+            return new(null, []);
+
+        var lines = SplitContentLines(content);
+        cancellationToken.ThrowIfCancellationRequested();
+        if (TryExtractDedicatedLineBasedSymbols(
+            fileId,
+            lang,
+            content,
+            lines,
+            out var dedicatedSymbols))
+        {
+            return new(null, dedicatedSymbols);
+        }
+
+        if (patterns == null || lang == null)
+            return new(null, []);
+
+        var applicablePatterns = SelectApplicablePatterns(
+            patterns,
+            content,
+            applyRequiredLiteralFileGate);
+        if (requiredLiteralGateCounts != null)
+        {
+            requiredLiteralGateCounts.PatternCount = patterns.Count;
+            requiredLiteralGateCounts.ApplicablePatternCount = applicablePatterns.Count;
+        }
+
+        return new(
+            new PatternExtractionContext(
+                fileId,
+                originalLang,
+                lang,
+                content,
+                filePath,
+                projectRoot,
+                lines,
+                applicablePatterns,
+                applyRequiredLiteralMatchInputGate,
+                requiredLiteralGateCounts,
+                cancellationToken,
+                maxSymbols),
+            null);
+    }
+
+    private static bool TryExtractDedicatedLineBasedSymbols(
+        long fileId,
+        string? lang,
+        string content,
+        string[] lines,
+        out List<SymbolRecord> symbols)
+    {
+        if (lang is "commonlisp" or "racket")
+        {
+            symbols = ExtractLispSymbols(fileId, lang, lines);
+            return true;
+        }
+
+        if (lang == "solidity")
+        {
+            symbols = ExtractSoliditySymbols(fileId, lines);
+            return true;
+        }
+
+        // HTML has no brace/indent-scoped bodies, so the generic pattern loop's
+        // "first match per line" semantics drop every additional symbol on the
+        // same line. HTML also needs cross-line masking of `<!-- ... -->` and
+        // raw-text children of `<script>` / `<style>` before patterns run, or
+        // phantom imports/classes/properties leak out of commented-out tags
+        // and inline template string literals. Closes #215 codex review blocker.
+        // HTML は brace/indent スコープの本体を持たないため、汎用パターンループの
+        // 「1 行の先勝ち」意味論を通すと同一行の追加シンボルを取りこぼす。加えて
+        // `<!-- ... -->` と `<script>` / `<style>` の raw-text 子要素を跨ぎ行で
+        // マスクしておかないと、コメントアウトされたタグやインラインテンプレート
+        // 文字列から phantom な import / class / property が漏れる。#215 の codex
+        // レビュー blocker 対応としてここで専用抽出に分岐する。
+        if (lang == "html")
+        {
+            symbols = ExtractHtmlSymbols(fileId, content, lines);
+            return true;
+        }
+
+        if (lang == "assembly")
+        {
+            symbols = ExtractAssemblySymbols(fileId, lines);
+            return true;
+        }
+
+        symbols = null!;
+        return false;
+    }
+
+    private static void CompletePatternExtraction(PatternExtractionContext context)
+    {
+        var fileId = context.FileId;
+        var originalLang = context.OriginalLang;
+        var lang = context.Lang;
+        var content = context.Content;
+        var filePath = context.FilePath;
+        var projectRoot = context.ProjectRoot;
+        var lines = context.Lines;
+        var applicablePatterns = context.ApplicablePatterns;
+        var applyRequiredLiteralMatchInputGate = context.ApplyRequiredLiteralMatchInputGate;
+        var requiredLiteralGateCounts = context.RequiredLiteralGateCounts;
+        var scanInputs = context.ScanInputs;
+        var structuralLines = scanInputs.StructuralLines;
+        var pythonModulePrefix = scanInputs.PythonModulePrefix;
+        var prologMultilineHeads = scanInputs.PrologMultilineHeads;
+        var csharpMatchLines = scanInputs.CSharpMatchLines;
+        var getCSharpLineStartStates = scanInputs.GetCSharpLineStartStates;
+        var getPrivateScopeColumns = scanInputs.GetPrivateScopeColumns;
+        var GetJavaScriptTypeScriptSanitizedLines = context.GetJavaScriptTypeScriptSanitizedLines;
+        var symbols = context.Symbols;
+        var extractionState = context.ExtractionState;
+        var pendingRecordPrimaryComponents = context.PendingRecordPrimaryComponents;
+        if (!symbols.IsAtCapacity)
+        {
+            AddSupplementalSymbols(
+                fileId,
+                originalLang,
+                lang,
+                content,
+                filePath,
+                lines,
+                structuralLines,
+                symbols,
+                extractionState,
+                getPrivateScopeColumns,
+                GetJavaScriptTypeScriptSanitizedLines,
+                csharpMatchLines,
+                pythonModulePrefix,
+                prologMultilineHeads,
+                applicablePatterns,
+                applyRequiredLiteralMatchInputGate,
+                requiredLiteralGateCounts);
+        }
+        if (lang == "csharp")
+        {
+            PopulateCSharpPartialDeclarationMetadata(
+                lines,
+                symbols,
+                getCSharpLineStartStates);
+        }
+        FinalizePatternSymbols(
+            fileId,
+            lang,
+            filePath,
+            projectRoot,
+            lines,
+            symbols,
+            extractionState,
+            getCSharpLineStartStates,
+            pendingRecordPrimaryComponents);
+    }
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternFlow.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternFlow.cs
new file mode 100644
index 000000000..8fbf97724
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternFlow.cs
@@ -0,0 +1,119 @@
+using System.Text.RegularExpressions;
+
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+    private enum PatternScanFlow
+    {
+        Accepted,
+        ContinueCurrentPattern,
+        NextPattern,
+        RestartPatternList,
+        StopLine,
+    }
+
+    private readonly record struct PatternScanResult(
+        PatternScanFlow Flow,
+        int NextOffset = -1)
+    {
+        public static PatternScanResult Accepted => new(PatternScanFlow.Accepted);
+        public static PatternScanResult NextPattern => new(PatternScanFlow.NextPattern);
+        public static PatternScanResult StopLine => new(PatternScanFlow.StopLine);
+
+        public static PatternScanResult ContinueAt(int nextOffset) =>
+            new(PatternScanFlow.ContinueCurrentPattern, nextOffset);
+
+        public static PatternScanResult RestartAt(int nextOffset) =>
+            new(PatternScanFlow.RestartPatternList, nextOffset);
+    }
+
+    private readonly record struct PatternLineScanContext(
+        PatternExtractionContext Extraction,
+        int LineIndex,
+        PreparedPatternLine PreparedLine);
+
+    private struct PatternStartScanState
+    {
+        public PatternStartScanState()
+        {
+            CSharpPropertyCandidateForLine = null;
+            DeferCSharpBraceProperty = null;
+            DeferCSharpFunction = null;
+            DeferCSharpEvent = null;
+            DeferCSharpDelegate = null;
+            RecoverableCSharpPattern = null;
+        }
+
+        public CSharpPropertyMatchCandidate? CSharpPropertyCandidateForLine;
+        public bool? DeferCSharpBraceProperty;
+        public bool? DeferCSharpFunction;
+        public bool? DeferCSharpEvent;
+        public bool? DeferCSharpDelegate;
+        public bool? RecoverableCSharpPattern;
+    }
+
+    private struct PatternCandidateScan
+    {
+        public PatternCandidateScan(
+            PatternLineScanContext lineContext,
+            SymbolPattern pattern,
+            int patternStartOffset,
+            CSharpPropertyMatchCandidate csharpPropertyCandidate,
+            string patternMatchLine)
+        {
+            LineContext = lineContext;
+            Pattern = pattern;
+            PatternStartOffset = patternStartOffset;
+            CSharpPropertyCandidate = csharpPropertyCandidate;
+            PatternMatchLine = patternMatchLine;
+            CSharpWrappedModifierPrefix = null;
+            LineOffset = patternStartOffset;
+        }
+
+        public PatternLineScanContext LineContext;
+        public SymbolPattern Pattern;
+        public int PatternStartOffset;
+        public CSharpPropertyMatchCandidate CSharpPropertyCandidate;
+        public string PatternMatchLine;
+        public string? CSharpWrappedModifierPrefix;
+        public int LineOffset;
+    }
+
+    private readonly record struct CapturedPatternMatch(
+        Match Match,
+        int AbsoluteStartColumn);
+
+    private readonly record struct MatchedPatternCandidateContext(
+        PatternLineScanContext LineContext,
+        SymbolPattern Pattern,
+        int LineOffset,
+        CSharpPropertyMatchCandidate CSharpPropertyCandidate,
+        string PatternMatchLine,
+        string? CSharpWrappedModifierPrefix,
+        CapturedPatternMatch CapturedMatch);
+
+    private readonly record struct PatternCandidateColumns(
+        int CSharpGateRawStartColumn);
+
+    private readonly record struct PatternSymbolDraft(
+        string Name,
+        string? RawReturnType,
+        List<string>? RubyAttributeNames,
+        int StartLine,
+        int EndLine,
+        int? BodyStartLine,
+        int? BodyEndLine);
+
+    private readonly record struct ShapedPatternSymbol(
+        string Name,
+        string Kind,
+        string? RawReturnType,
+        string? PythonSubKind,
+        List<string>? RubyAttributeNames,
+        int StartLine,
+        int EndLine,
+        int? BodyStartLine,
+        int? BodyEndLine,
+        PatternSignatureResult SignatureResult);
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternGates.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternGates.cs
new file mode 100644
index 000000000..966086f2f
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternGates.cs
@@ -0,0 +1,392 @@
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+    private static PatternScanResult EvaluateCandidateSyntaxGates(
+        MatchedPatternCandidateContext candidate,
+        out PatternCandidateColumns columns)
+    {
+        columns = default;
+        var lineContext = candidate.LineContext;
+        var extraction = lineContext.Extraction;
+        var lang = extraction.Lang;
+        var pattern = candidate.Pattern;
+        var patternMatchLine = candidate.PatternMatchLine;
+        var matchLine = lineContext.PreparedLine.MatchLine;
+        var lineOffset = candidate.LineOffset;
+        var match = candidate.CapturedMatch.Match;
+        var absoluteStartColumn = candidate.CapturedMatch.AbsoluteStartColumn;
+        var lines = extraction.Lines;
+        var line = lineContext.PreparedLine.SourceLine;
+        var i = lineContext.LineIndex;
+        var scanInputs = extraction.ScanInputs;
+        var csharpMatchColumnToRaw = scanInputs.CSharpMatchColumnToRaw;
+        var csharpMatchLines = scanInputs.CSharpMatchLines;
+        var getCSharpSwitchExpressionLines = scanInputs.GetCSharpSwitchExpressionLines;
+        var getCssQualifiedRuleAncestors = scanInputs.GetCssQualifiedRuleAncestors;
+        var nextSameLineOffsetAfterRejectedCSharpProperty = -1;
+        if (ShouldSkipCSharpSwitchExpressionPropertyCandidate(lang, pattern, patternMatchLine, getCSharpSwitchExpressionLines, i)
+            || TrySkipCSharpBracePropertyCandidate(
+                lang,
+                pattern,
+                patternMatchLine,
+                absoluteStartColumn,
+                match.Value.Contains("=>", StringComparison.Ordinal),
+                out nextSameLineOffsetAfterRejectedCSharpProperty))
+        {
+            // False-positive C# property matches can happen at the start of a
+            // same-line type header (`public class C { ... }`) because the
+            // property regex allows omitted visibility/modifier runs and can
+            // initially treat the header as `returnType + name + {`. Do not break
+            // the whole same-line scan on that rejection — advance to the next
+            // brace-delimited statement so a real nested property later on the
+            // same physical line still gets a chance to match. Closes #470.
+            // C# の property 正規表現は visibility / modifier 省略を許すため、
+            // 同一行の型ヘッダ先頭 (`public class C { ... }`) を一旦
+            // `returnType + name + {` と誤認することがある。この偽候補を弾いた
+            // ときに同一行スキャン全体を break せず、次の brace 区切り宣言へ進めて
+            // 後続の本物 property にもマッチ機会を残す。Closes #470.
+            lineOffset = nextSameLineOffsetAfterRejectedCSharpProperty >= 0
+                ? nextSameLineOffsetAfterRejectedCSharpProperty
+                : FindNextSameLineBraceStatementStart(
+                    matchLine,
+                    absoluteStartColumn + Math.Max(1, match.Length),
+                    lang);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+
+        // Gate the C# plain-field pattern (internally tagged as `property`,
+        // BodyStyle.None, then normalized to the public `field` kind) to lines
+        // that sit directly inside a type body. Without this gate, local
+        // variable declarations inside method / property / accessor / lambda
+        // bodies match the same shape and leak into `symbols`, `definition`,
+        // `outline`, `inspect`, and `unused` as phantom field symbols.
+        // Closes #298 follow-up (codex review blocker).
+        // C# の通常フィールド用パターン（内部タグは `property`、BodyStyle.None、
+        // 公開時に `field` へ正規化）は型本体（class / struct / interface /
+        // record / enum の直下）でしか許可しない。このゲートを入れないと、
+        // メソッド・プロパティ・アクセサ・ラムダの内部にあるローカル変数宣言が
+        // 同じ形でマッチしてしまい、
+        // `symbols` / `definition` / `outline` / `inspect` / `unused` に
+        // 擬似シンボルが混入する。Closes #298 の codex レビュー blocker 対応。
+        if (ShouldSkipCssNestedSelectorCandidate(lang, pattern, patternMatchLine, getCssQualifiedRuleAncestors, i))
+            return PatternScanResult.NextPattern;
+
+        // JS/TS HOC binding gate: the `styled.` / `styled(` / `styled\`` regex
+        // branch matches three shapes — factory capture (`const F = styled.div;`),
+        // plain call (`const F = styled(Component);`), and tagged template
+        // (`const F = styled.div\`...\``). Only the tagged-template shape
+        // actually declares a styled-component binding; the other two produce
+        // a factory / a styled wrapper-of-component without a component body
+        // on that line and must stay 0-symbol. This gate looks at the raw
+        // (unmasked) line because StructuralLineMasker.MaskJsTsTemplateLiteralContents
+        // replaces template-literal delimiters with space, so the masked
+        // `patternMatchLine` cannot see the backtick. Closes #240 follow-up
+        // (codex review #5 blocker).
+        // JS/TS HOC 束縛ゲート: `styled.` / `styled(` / `styled\`` の regex
+        // 分岐は 3 形状にマッチする — factory 捕捉（`const F = styled.div;`）、
+        // 素の呼び出し（`const F = styled(Component);`）、タグ付きテンプレート
+        // （`const F = styled.div\`...\``）。実際に styled-component 束縛を
+        // 生むのはタグ付きテンプレート形のみで、前者 2 つはその行で component
+        // 本体を生やさないため 0 シンボルに保つ必要がある。このゲートは raw 行
+        // （マスク前）を参照する — `StructuralLineMasker.MaskJsTsTemplateLiteralContents`
+        // がテンプレート区切りを空白にマスクするため、マスク後の
+        // `patternMatchLine` ではバッククォートが見えないことへの対処。
+        // Closes #240 follow-up（codex レビュー #5 の blocker 対応）。
+        if (ShouldSkipJavaScriptTypeScriptStyledFactoryCandidate(lang, pattern, match, lineOffset, lines, i))
+        {
+            lineOffset = FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, lineOffset + Math.Max(1, match.Length));
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+
+        // For C#, collapsed-space column (from CollapseCSharpGenericTypeWhitespace)
+        // has to be translated back to raw-space before it can be compared against
+        // CSharpTypeBodyScope's per-line transitions, which were built from
+        // structural (raw) columns. Only translate when the pattern match runs on
+        // the per-line collapsed string (single-line case); multi-line merged
+        // candidates use a different composed string whose column domain does not
+        // line up with a single line's map, so we leave the column alone there to
+        // preserve pre-existing behavior. Closes #400.
+        // C# では CollapseCSharpGenericTypeWhitespace で空白を取り除いた列を、
+        // structural 行の生列で構築された CSharpTypeBodyScope に渡す前に
+        // raw 列へ戻す必要がある。複数行を結合した match では単一行の map が
+        // 使えないため、単一行ケース（per-line collapsed line そのものにマッチした
+        // 場合）だけ変換する。Closes #400.
+        var csharpNormalizedStartColumn = lang == "csharp"
+            ? SkipWhitespace(patternMatchLine, absoluteStartColumn)
+            : absoluteStartColumn;
+        var csharpGateRawStartColumn = csharpNormalizedStartColumn;
+        if (lang == "csharp"
+            && csharpMatchLines != null
+            && ReferenceEquals(patternMatchLine, csharpMatchLines[i]))
+        {
+            csharpGateRawStartColumn = TranslateCSharpCollapsedColumnToRaw(
+                csharpMatchColumnToRaw,
+                i,
+                csharpNormalizedStartColumn,
+                line.Length);
+        }
+
+        columns = new PatternCandidateColumns(csharpGateRawStartColumn);
+        return PatternScanResult.Accepted;
+    }
+
+    private static PatternScanResult EvaluateCandidateScopeAndTypeGates(
+        MatchedPatternCandidateContext candidate,
+        PatternCandidateColumns columns,
+        out string? rawReturnType)
+    {
+        rawReturnType = null;
+        var lineContext = candidate.LineContext;
+        var extraction = lineContext.Extraction;
+        var lang = extraction.Lang;
+        var pattern = candidate.Pattern;
+        var patternMatchLine = candidate.PatternMatchLine;
+        var matchLine = lineContext.PreparedLine.MatchLine;
+        var lineOffset = candidate.LineOffset;
+        var match = candidate.CapturedMatch.Match;
+        var absoluteStartColumn = candidate.CapturedMatch.AbsoluteStartColumn;
+        var csharpPropertyCandidate = candidate.CSharpPropertyCandidate;
+        var csharpGateRawStartColumn = columns.CSharpGateRawStartColumn;
+        var lines = extraction.Lines;
+        var line = lineContext.PreparedLine.SourceLine;
+        var i = lineContext.LineIndex;
+        var symbols = extraction.Symbols;
+        var scanInputs = extraction.ScanInputs;
+        var getCSharpLineStartStates = scanInputs.GetCSharpLineStartStates;
+        var getPrivateScopeColumns = scanInputs.GetPrivateScopeColumns;
+        var GetDartInsideClassBody = extraction.GetDartInsideClassBody;
+        var GetCSharpInsideTypeBody = extraction.GetCSharpInsideTypeBody;
+        var GetCSharpCallableParameterScope = extraction.GetCSharpCallableParameterScope;
+        var GetCSharpDeclarationStartScope = extraction.GetCSharpDeclarationStartScope;
+        if (lang == "dart"
+            && ReferenceEquals(pattern.Regex, DartBareConstConstructorRegex)
+            && !GetDartInsideClassBody().IsInsideClassBodyAt(i))
+        {
+            // Bare `const` constructors need class-body context; otherwise
+            // `const Widget(key: k)` expressions become phantom symbols.
+            // bare な `const` コンストラクタは class 本体内でのみ許可する。
+            // そうしないと `const Widget(key: k)` の式を phantom symbol にしてしまう。
+            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+
+        // C# candidates that only become visible after string-literal content is
+        // blanked (for example, code inside an interpolation hole of an outer
+        // string) must not be emitted as declarations. A real declaration starts in
+        // root code, not in nested interpolation code. Gate on the raw-line start
+        // column so exact definition / inspect lookups do not pick up call-site
+        // fragments from interpolated log strings. Closes #790.
+        // C# では、外側文字列本文を空白化した結果として見えるようになった候補
+        // （例: 補間文字列ホール内のコード）を宣言として emit してはならない。
+        // 本物の宣言は root code から始まり、入れ子の補間コードからは始まらない。
+        // raw 行上の開始列でゲートし、補間ログ文字列内の呼び出し断片が
+        // exact definition / inspect に混入しないようにする。Closes #790.
+        var csharpLineStartStatesForGate = lang == "csharp"
+            ? getCSharpLineStartStates?.Invoke()
+            : null;
+        if (csharpLineStartStatesForGate != null
+            && !IsCSharpRootCodePosition(line, csharpLineStartStatesForGate[i], csharpGateRawStartColumn))
+        {
+            lineOffset = FindNextSameLineBraceStatementStart(
+                matchLine,
+                absoluteStartColumn + Math.Max(1, match.Length),
+                lang);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+
+        if (lang == "csharp"
+            && (pattern.Kind is "function" or "property")
+            && match.Groups["name"].Success
+            && IsCSharpStaticLambdaHeaderCandidate(
+                patternMatchLine,
+                lineOffset + match.Groups["name"].Index,
+                FindCSharpEnclosingTypeName(symbols, i + 1)))
+        {
+            // Multi-line call arguments are composed into the same candidate
+            // string as the following lambda. A declaration-shaped regex can then
+            // reinterpret the state argument as a return type and `static` (or a
+            // parameter) as a member name. Reject only names that occupy a
+            // confirmed static-lambda header; real static members and local
+            // functions remain eligible. Closes #4830; regression of #4453.
+            // 複数行の呼び出し引数と後続 lambda は同じ候補文字列に結合されるため、
+            // 宣言形 regex が state 引数を戻り値型、`static`（または parameter）を
+            // member 名として再解釈し得る。確認済み static-lambda header 内の名前
+            // だけを除外し、本物の static member / local function は維持する。
+            // Closes #4830; regression of #4453.
+            lineOffset = absoluteStartColumn + Math.Max(1, match.Length);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+
+        if (lang == "csharp"
+            && pattern.Kind == "function"
+            && pattern.BodyStyle == BodyStyle.Brace
+            && !GetCSharpDeclarationStartScope().CanStartDeclarationAt(i, csharpGateRawStartColumn))
+        {
+            // Method and constructor patterns are intentionally broad enough to
+            // recognize multi-line declarations. Do not let that merger begin from
+            // an invocation argument or callable-parameter continuation, even when
+            // a later declaration brace makes the combined text look method-shaped.
+            // The scope is column-aware so a real same-line sibling remains eligible.
+            // メソッドとコンストラクタのパターンは複数行宣言を認識するため意図的に
+            // 広い。後続の宣言 brace によって結合テキストがメソッド形に見えても、
+            // 呼び出し引数や callable parameter の継続位置から開始してはならない。
+            // 列単位の scope により、同一行の後続にある本物の sibling は維持する。
+            // Fixes #4831; prevents regressions covered by #496 and #4413.
+            lineOffset = FindNextSameLineBraceStatementStart(
+                matchLine,
+                absoluteStartColumn + Math.Max(1, match.Length),
+                lang);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+
+        if (lang == "csharp"
+            && pattern.Kind == "function"
+            && HasCSharpTokenBeforeIndex(matchLine, "when", absoluteStartColumn + match.Groups["name"].Index))
+        {
+            lineOffset = absoluteStartColumn + Math.Max(1, match.Length);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+        if (lang == "csharp"
+            && pattern.Kind == "function"
+            && csharpPropertyCandidate.ExpressionBodyEndLineIndex.HasValue
+            && IsCSharpFunctionMatchInsideExpressionBody(
+                patternMatchLine,
+                absoluteStartColumn + match.Groups["name"].Index))
+        {
+            // The property/function header merger is shared by all C# member
+            // patterns. Once it has identified an expression body, a function-shaped
+            // call after `=>` is an expression, not a declaration. Preserve a real
+            // same-line sibling after the terminating `;`.
+            // C# の property/function header merger は全 member pattern で共有される。
+            // 式本体を特定した後、`=>` より後の function 形呼び出しは宣言ではなく式である。
+            // 終端 `;` より後にある本物の same-line sibling は維持する。
+            lineOffset = absoluteStartColumn + Math.Max(1, match.Length);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+        if (lang == "csharp"
+            && pattern.BodyStyle == BodyStyle.None
+          && (pattern.Kind == "property" || IsCSharpFieldLikeFunctionPattern(pattern))
+          && GetCSharpCallableParameterScope().IsInsideParameterListAt(i, csharpGateRawStartColumn))
+        {
+            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+        if (lang == "csharp"
+            && pattern.BodyStyle == BodyStyle.None
+          && (pattern.Kind == "property" || IsCSharpFieldLikeFunctionPattern(pattern))
+          && !GetCSharpInsideTypeBody().IsInsideTypeBodyAt(i, csharpGateRawStartColumn))
+        {
+            // Move the cursor past this same-line candidate so a later
+            // column on the same line (e.g. a real field that lives after
+            // a same-line method body or similar non-type-body scope) can
+            // still be evaluated against its own column-aware scope.
+            // Without this advance, the outer `while` would exit the line
+            // entirely on the first rejection and drop any following match.
+            // 同一行に続く別候補（例: 同一行の method 本体など非型本体の
+            // 後ろにある実フィールド）を取りこぼさないよう、次の候補探索
+            // 位置へ進める。この進行が無いと最初の拒否で while ループが
+            // 行を抜けてしまい、後続候補が失われる。Closes #400.
+            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+        if (lang == "csharp"
+            && pattern.BodyStyle == BodyStyle.None
+            && (pattern.Kind == "property" || IsCSharpFieldLikeFunctionPattern(pattern))
+            && IsInsidePreviouslyEmittedCSharpMemberBody(lines, symbols, i + 1, csharpGateRawStartColumn))
+        {
+            // Brace-based type-body scope tracking correctly rejects locals inside
+            // block bodies, but multi-line expression-bodied members have no brace
+            // transition for their continuation lines. Without an additional guard,
+            // those later lines can still match the plain-field regex and emit
+            // phantom `property` rows like `Red` from `value is\n Red\n or Red;`.
+            // Only reject lines after the member's declaration line so same-line
+            // siblings such as `int M() => 0; int X;` keep working through the
+            // existing column-aware scope gate. Closes #779.
+            // brace ベースの型本体スコープ追跡は block body 内の local を弾けるが、
+            // 複数行の式本体メンバーには continuation 行用の brace 遷移が無い。
+            // そのため追加ガードが無いと `value is\n Red\n or Red;` の後続行が
+            // plain-field regex にマッチして `property Red` の phantom を出してしまう。
+            // `int M() => 0; int X;` のような same-line sibling は既存の列単位
+            // ゲートで扱えるよう、宣言行そのものではなく後続行だけを拒否する。
+            // Closes #779.
+            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+        if (lang == "rust"
+            && pattern.Kind == "property"
+            && pattern.BodyStyle == BodyStyle.None
+            && pattern.ReturnTypeGroup != null
+            && !IsRustDirectTraitBodyMember(symbols, i + 1))
+        {
+            return PatternScanResult.NextPattern;
+        }
+        rawReturnType = NormalizeCSharpImplicitPartialMethodReturnType(
+            lang,
+            pattern,
+            match,
+            TryGetGroup(match, pattern.ReturnTypeGroup));
+        if (lang == "csharp"
+            && pattern.ReturnTypeGroup != null
+            && HasInvalidCSharpReturnTypeSuffix(rawReturnType))
+        {
+            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+        if (lang == "csharp"
+            && pattern.Kind == "function"
+            && HasCSharpTokenBeforeIndex(matchLine, "when", absoluteStartColumn + match.Groups["name"].Index))
+        {
+            lineOffset = absoluteStartColumn + Math.Max(1, match.Length);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+        if (lang == "csharp"
+            && pattern.Kind == "property"
+            && IsStandaloneCSharpAccessorCandidate(patternMatchLine))
+        {
+            lineOffset = FindNextSameLineBraceStatementStart(matchLine, absoluteStartColumn + Math.Max(1, match.Length), lang);
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+        var jsTsPrivateScopeColumnsForClassGate = lang is "javascript" or "typescript" && pattern.Kind == "class"
+            ? getPrivateScopeColumns?.Invoke()
+            : null;
+        if (jsTsPrivateScopeColumnsForClassGate != null
+            && pattern.Kind == "class"
+            && IsJavaScriptTypeScriptMatchInPrivateScope(jsTsPrivateScopeColumnsForClassGate, i, absoluteStartColumn, matchLine, includeBlockScope: true))
+        {
+            if (lang is "javascript" or "typescript")
+            {
+                var skippedEndColumn = pattern.BodyStyle == BodyStyle.Brace
+                    ? FindJavaScriptTypeScriptSameLineBraceEndColumn(line, absoluteStartColumn, lang)
+                    : -1;
+                lineOffset = skippedEndColumn >= absoluteStartColumn
+                    ? FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, skippedEndColumn + 1)
+                    : FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, absoluteStartColumn + Math.Max(1, match.Length));
+                return PatternScanResult.ContinueAt(lineOffset);
+            }
+
+            return PatternScanResult.NextPattern;
+        }
+
+        if (jsTsPrivateScopeColumnsForClassGate != null
+            && pattern.Kind == "class"
+            && TryGetGroup(match, pattern.VisibilityGroup) != "export"
+            && IsJavaScriptTypeScriptMatchInNamespaceScope(jsTsPrivateScopeColumnsForClassGate, i, absoluteStartColumn, matchLine))
+        {
+            if (lang is "javascript" or "typescript")
+            {
+                var skippedEndColumn = pattern.BodyStyle == BodyStyle.Brace
+                    ? FindJavaScriptTypeScriptSameLineBraceEndColumn(line, absoluteStartColumn, lang)
+                    : -1;
+                lineOffset = skippedEndColumn >= absoluteStartColumn
+                    ? FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, skippedEndColumn + 1)
+                    : FindNextJavaScriptTypeScriptStatementStart(patternMatchLine, absoluteStartColumn + Math.Max(1, match.Length));
+                return PatternScanResult.ContinueAt(lineOffset);
+            }
+
+            return PatternScanResult.NextPattern;
+        }
+
+        return PatternScanResult.Accepted;
+    }
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternLoop.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternLoop.cs
new file mode 100644
index 000000000..ee0063be3
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternLoop.cs
@@ -0,0 +1,329 @@
+using System.Text.RegularExpressions;
+using Regex = CodeIndex.Indexer.BoundedRegex;
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+    private static void ScanPatternLines(PatternExtractionContext context)
+    {
+        var fileId = context.FileId;
+        var lang = context.Lang;
+        var filePath = context.FilePath;
+        var projectRoot = context.ProjectRoot;
+        var cancellationToken = context.CancellationToken;
+        var lines = context.Lines;
+        var scanInputs = context.ScanInputs;
+        var symbols = context.Symbols;
+        var extractionState = context.ExtractionState;
+        var scanState = context.ScanState;
+        var dockerfileStageNames = context.DockerfileStageNames;
+        for (int i = 0; i < lines.Length; i++)
+        {
+            if (symbols.IsAtCapacity)
+                break;
+
+            if ((i & 0x3f) == 0)
+                cancellationToken.ThrowIfCancellationRequested();
+
+            if (!TryPreparePatternLine(
+                    fileId,
+                    lang,
+                    filePath,
+                    projectRoot,
+                    lines,
+                    scanInputs,
+                    scanState,
+                    symbols,
+                    extractionState,
+                    dockerfileStageNames,
+                    i,
+                    out var preparedLine))
+            {
+                continue;
+            }
+
+            ScanPreparedPatternLine(context, i, preparedLine);
+            EmitCssLineSupplementals(context, i, preparedLine);
+        }
+    }
+
+    private static void ScanPreparedPatternLine(
+        PatternExtractionContext context,
+        int i,
+        PreparedPatternLine preparedLine)
+    {
+        var lineContext = new PatternLineScanContext(context, i, preparedLine);
+        var patternStartOffset = preparedLine.PatternStartOffset;
+        while (patternStartOffset >= 0
+            && patternStartOffset < preparedLine.MatchLine.Length)
+        {
+            var result = ScanPatternListAtOffset(lineContext, patternStartOffset);
+            if (result.Flow != PatternScanFlow.RestartPatternList
+                || result.NextOffset <= patternStartOffset)
+            {
+                break;
+            }
+
+            patternStartOffset = result.NextOffset;
+        }
+    }
+
+    private static PatternScanResult ScanPatternListAtOffset(
+        PatternLineScanContext lineContext,
+        int patternStartOffset)
+    {
+        var extraction = lineContext.Extraction;
+        var patternStartState = new PatternStartScanState();
+        foreach (var pattern in extraction.ApplicablePatterns)
+        {
+            if (!IsPatternApplicableToLine(lineContext, pattern))
+                continue;
+
+            var patternScan = CreatePatternCandidateScan(
+                lineContext,
+                pattern,
+                patternStartOffset,
+                ref patternStartState);
+            var result = ScanApplicablePattern(
+                ref patternScan,
+                ref patternStartState);
+            if (result.Flow is PatternScanFlow.RestartPatternList
+                or PatternScanFlow.StopLine)
+            {
+                return result;
+            }
+        }
+
+        return PatternScanResult.NextPattern;
+    }
+
+    private static bool IsPatternApplicableToLine(
+        PatternLineScanContext lineContext,
+        SymbolPattern pattern)
+    {
+        var extraction = lineContext.Extraction;
+        var i = lineContext.LineIndex;
+        var scanInputs = extraction.ScanInputs;
+        if (scanInputs.PrologClauseContinuationLines?[i] == true
+            && lineContext.PreparedLine.PrologContinuationResumeOffset < 0
+            && pattern.Kind == "function")
+        {
+            return false;
+        }
+
+        if (extraction.Lang == "csharp"
+            && ReferenceEquals(pattern.Regex, CSharpEnumMemberRegex))
+        {
+            return false;
+        }
+
+        return extraction.Lang != "powershell"
+            || pattern.Kind != "enum"
+            || pattern.BodyStyle != BodyStyle.None
+            || scanInputs.PowershellEnumBodyLines![i];
+    }
+
+    private static PatternCandidateScan CreatePatternCandidateScan(
+        PatternLineScanContext lineContext,
+        SymbolPattern pattern,
+        int patternStartOffset,
+        ref PatternStartScanState patternStartState)
+    {
+        var extraction = lineContext.Extraction;
+        var lines = extraction.Lines;
+        var i = lineContext.LineIndex;
+        var csharpMatchLines = extraction.ScanInputs.CSharpMatchLines;
+
+        // Merge multi-line field headers for C# regardless of kind. Kind "property" (plain
+        // fields) and kind "function" (const / static readonly fields) both need the
+        // merge. Non-field function patterns (methods, constructors, operators, indexers)
+        // are unaffected because CSharpPropertyHeaderPrefixRegex requires the line to end
+        // before `(` or `{`, so lines like `public int Foo()` never satisfy the header
+        // prefix and the merger returns the original line. Closes #355.
+        // C# の複数行フィールドヘッダ結合は kind に依らず適用する。kind "property"（通常
+        // フィールド）と kind "function"（`const` / `static readonly` フィールド）の両方で
+        // 結合が必要。method / constructor / operator / indexer のような非フィールド
+        // function パターンは `CSharpPropertyHeaderPrefixRegex` が `(` や `{` を含む行を
+        // 受け付けないため影響を受けず、merger は元の行をそのまま返す。Closes #355.
+        var csharpPropertyCandidate = extraction.Lang == "csharp"
+            && pattern.Kind is "property" or "function"
+                ? patternStartState.CSharpPropertyCandidateForLine ??=
+                    BuildCSharpPropertyMatchLine(lines, csharpMatchLines!, i)
+                : new CSharpPropertyMatchCandidate(
+                    lineContext.PreparedLine.MatchLine,
+                    i,
+                    i);
+        var patternMatchLine = lineContext.PreparedLine.FortranContinuationCandidate?.MatchLine
+            ?? csharpPropertyCandidate.MatchLine;
+        return new PatternCandidateScan(
+            lineContext,
+            pattern,
+            patternStartOffset,
+            csharpPropertyCandidate,
+            patternMatchLine);
+    }
+
+    private static PatternScanResult ScanApplicablePattern(
+        ref PatternCandidateScan patternScan,
+        ref PatternStartScanState patternStartState)
+    {
+        while (patternScan.LineOffset >= 0
+            && patternScan.LineOffset < patternScan.PatternMatchLine.Length)
+        {
+            var captureResult = TryCapturePatternMatch(
+                patternScan.LineContext,
+                patternScan.Pattern,
+                patternScan.PatternStartOffset,
+                patternScan.LineOffset,
+                ref patternScan.PatternMatchLine,
+                ref patternScan.CSharpWrappedModifierPrefix,
+                ref patternStartState,
+                out var capturedMatch);
+            if (captureResult.Flow == PatternScanFlow.ContinueCurrentPattern)
+            {
+                patternScan.LineOffset = captureResult.NextOffset;
+                continue;
+            }
+            if (captureResult.Flow != PatternScanFlow.Accepted)
+                return captureResult;
+
+            var candidate = new MatchedPatternCandidateContext(
+                patternScan.LineContext,
+                patternScan.Pattern,
+                patternScan.LineOffset,
+                patternScan.CSharpPropertyCandidate,
+                patternScan.PatternMatchLine,
+                patternScan.CSharpWrappedModifierPrefix,
+                capturedMatch);
+            var result = EvaluateCandidateSyntaxGates(
+                candidate,
+                out var candidateColumns);
+            if (result.Flow == PatternScanFlow.ContinueCurrentPattern)
+            {
+                patternScan.LineOffset = result.NextOffset;
+                continue;
+            }
+            if (result.Flow != PatternScanFlow.Accepted)
+                return result;
+
+            result = EvaluateCandidateScopeAndTypeGates(
+                candidate,
+                candidateColumns,
+                out var rawReturnType);
+            if (result.Flow == PatternScanFlow.ContinueCurrentPattern)
+            {
+                patternScan.LineOffset = result.NextOffset;
+                continue;
+            }
+            if (result.Flow != PatternScanFlow.Accepted)
+                return result;
+
+            var draft = BuildPatternSymbolDraft(
+                candidate,
+                candidateColumns,
+                rawReturnType);
+            result = TryShapePatternSymbol(
+                candidate,
+                candidateColumns,
+                draft,
+                out var shapedSymbol);
+            if (result.Flow == PatternScanFlow.ContinueCurrentPattern)
+            {
+                patternScan.LineOffset = result.NextOffset;
+                continue;
+            }
+            if (result.Flow != PatternScanFlow.Accepted)
+                return result;
+
+            result = EmitAcceptedPatternSymbol(
+                candidate,
+                shapedSymbol,
+                out var emittedKind);
+            if (result.Flow != PatternScanFlow.Accepted)
+                return result;
+
+            result = ResolveCSharpFieldProgression(
+                candidate);
+            if (result.Flow == PatternScanFlow.Accepted)
+            {
+                result = ResolveTerminalPatternProgression(
+                    candidate,
+                    shapedSymbol,
+                    emittedKind);
+            }
+            if (result.Flow == PatternScanFlow.Accepted)
+            {
+                result = ResolveBraceBodyPatternProgression(
+                    candidate,
+                    shapedSymbol,
+                    emittedKind);
+            }
+
+            if (result.Flow == PatternScanFlow.ContinueCurrentPattern)
+            {
+                patternScan.LineOffset = result.NextOffset;
+                continue;
+            }
+
+            return result;
+        }
+
+        return PatternScanResult.NextPattern;
+    }
+
+    private static void EmitCssLineSupplementals(
+        PatternExtractionContext context,
+        int i,
+        PreparedPatternLine preparedLine)
+    {
+        var lang = context.Lang;
+        var fileId = context.FileId;
+        var line = preparedLine.SourceLine;
+        var cssScannerLine = preparedLine.CssScannerLine;
+        var cssScannerLines = context.ScanInputs.CssScannerLines;
+        var applicablePatterns = context.ApplicablePatterns;
+        var symbols = context.Symbols;
+        var extractionState = context.ExtractionState;
+        var cssSeenSymbols = context.CssSeenSymbols;
+        if (lang == "css" && cssScannerLine != null)
+        {
+            if (cssScannerLine.IndexOf("--", StringComparison.Ordinal) >= 0)
+            {
+                foreach (Match match in Regex.EnumerateMatches(CssInlineCustomPropertyRegex, cssScannerLine))
+                {
+                    var propertyName = match.Groups["name"].ValueSpan.Trim().ToString();
+                    if (propertyName.Length == 0)
+                        continue;
+
+                    AddSymbolRecord(
+                        symbols,
+                        extractionState,
+                        cssSeenSymbols,
+                        i + 1,
+                        new SymbolRecord
+                        {
+                            FileId = fileId,
+                            Kind = "property",
+                            Name = propertyName,
+                            Line = i + 1,
+                            StartLine = i + 1,
+                            EndLine = i + 1,
+                            Signature = line.Trim(),
+                        });
+                }
+            }
+
+            ExtractCssInlineGroupingSelectors(
+                fileId,
+                line,
+                cssScannerLine,
+                cssScannerLines!,
+                i,
+                applicablePatterns,
+                symbols,
+                cssSeenSymbols);
+        }
+    }
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternMatching.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternMatching.cs
new file mode 100644
index 000000000..12ceb8ced
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternMatching.cs
@@ -0,0 +1,201 @@
+using System.Text.RegularExpressions;
+
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+    private static PatternScanResult TryCapturePatternMatch(
+        PatternLineScanContext lineContext,
+        SymbolPattern pattern,
+        int patternStartOffset,
+        int lineOffset,
+        ref string patternMatchLine,
+        ref string? csharpWrappedModifierPrefix,
+        ref PatternStartScanState patternStartState,
+        out CapturedPatternMatch capturedMatch)
+    {
+        capturedMatch = default;
+        var extraction = lineContext.Extraction;
+        var lang = extraction.Lang;
+        var i = lineContext.LineIndex;
+        var matchLine = lineContext.PreparedLine.MatchLine;
+        var applicablePatterns = extraction.ApplicablePatterns;
+        var applyRequiredLiteralMatchInputGate = extraction.ApplyRequiredLiteralMatchInputGate;
+        var requiredLiteralGateCounts = extraction.RequiredLiteralGateCounts;
+        var csharpMatchLines = extraction.ScanInputs.CSharpMatchLines;
+        var javaLeadingAnnotationOffset = 0;
+        Match match;
+        if (lang is "java" or "kotlin")
+        {
+            var javaPatternMatched = TryMatchJavaDeclarationPatternSegment(
+                pattern,
+                patternMatchLine,
+                lineOffset,
+                lang == "kotlin",
+                applyRequiredLiteralMatchInputGate,
+                requiredLiteralGateCounts,
+                out match,
+                out javaLeadingAnnotationOffset,
+                out var initialJavaInputAttempted);
+            if (!javaPatternMatched
+                && initialJavaInputAttempted
+                && ShouldAttemptPatternRegex(
+                    pattern,
+                    patternMatchLine.AsSpan(lineOffset),
+                    applyRequiredLiteralMatchInputGate,
+                    requiredLiteralGateCounts))
+            {
+                // Preserve the existing failed-helper fallback attempt. This is
+                // intentionally gated again because it is a distinct regex call.
+                match = pattern.Regex.Match(patternMatchLine[lineOffset..]);
+            }
+        }
+        else if (ShouldAttemptPatternRegex(
+                     pattern,
+                     patternMatchLine.AsSpan(lineOffset),
+                     applyRequiredLiteralMatchInputGate,
+                     requiredLiteralGateCounts))
+        {
+            match = pattern.Regex.Match(patternMatchLine[lineOffset..]);
+        }
+        else
+        {
+            match = Match.Empty;
+        }
+
+        if (!match.Success
+            && lang == "csharp"
+            && pattern.Kind == "function"
+            && lineOffset == 0
+            && csharpMatchLines != null
+            && csharpWrappedModifierPrefix == null)
+        {
+            // Wrapped leading modifier recovery: when a C# function-kind pattern
+            // fails at column 0 of the identifier line, try prepending the
+            // modifier prefix accumulated from preceding modifier-only lines
+            // (`static\nFoo() { ... }`, `public\nBar() { ... }`, etc.) and retry.
+            // The method regex already tolerates an omitted modifier run, so it
+            // matches on the identifier line alone — this branch only fires for
+            // constructor / static-constructor shapes that require the modifier
+            // on the same line as the name. Closes #348.
+            // ラップされた先頭モディファイアの救済: C# の function 系パターンが
+            // 識別子行の先頭マッチに失敗した場合、直前のモディファイアのみ行
+            // （`static\nFoo() { ... }` や `public\nBar() { ... }` 等）から
+            // 再構築した prefix を付け直して再試行する。メソッド regex は
+            // 先頭モディファイアが無くても識別子行単体でマッチするため、この
+            // 分岐は修飾子が識別子と同行に必要な constructor / static ctor
+            // シェイプでのみ発火する。Closes #348.
+            var wrappedInfo = TryFindCSharpWrappedHeaderModifier(csharpMatchLines!, i);
+            if (wrappedInfo != null)
+            {
+                foreach (var candidatePrefix in EnumerateCSharpWrappedModifierCandidates(wrappedInfo.Value.Prefix))
+                {
+                    var wrappedMatchLine = candidatePrefix + " " + patternMatchLine.TrimStart();
+                    if (!ShouldAttemptPatternRegex(
+                            pattern,
+                            wrappedMatchLine.AsSpan(),
+                            applyRequiredLiteralMatchInputGate,
+                            requiredLiteralGateCounts))
+                    {
+                        continue;
+                    }
+
+                    var wrappedMatch = pattern.Regex.Match(wrappedMatchLine);
+                    if (wrappedMatch.Success)
+                    {
+                        match = wrappedMatch;
+                        patternMatchLine = wrappedMatchLine;
+                        // Preserve the full prefix in the stored signature so
+                        // declarations like `public\nstatic\nP1()` retain
+                        // `public static P1()`, even when the matching regex
+                        // variant only accepted `static P1()`. Closes #348.
+                        // シグネチャには完全な prefix を残し、`public\nstatic\nP1()`
+                        // のような宣言を `public static P1()` として保存する。
+                        // マッチした regex 変種が `static P1()` 形だけを受け付けた
+                        // 場合でも、保存シグネチャは完全な prefix を保持する。Closes #348.
+                        csharpWrappedModifierPrefix = wrappedInfo.Value.Prefix;
+                        break;
+                    }
+                }
+            }
+        }
+
+        if (!match.Success)
+        {
+            if (lang == "csharp"
+                && pattern.Kind == "property"
+                && pattern.BodyStyle == BodyStyle.Brace
+                && (lineOffset != patternStartOffset
+                    ? ShouldDeferCSharpBracePropertySameLineAdvance(matchLine, lineOffset)
+                    : patternStartState.DeferCSharpBraceProperty ??=
+                        ShouldDeferCSharpBracePropertySameLineAdvance(matchLine, lineOffset)))
+            {
+                return PatternScanResult.NextPattern;
+            }
+
+            if (lang == "csharp"
+                && pattern.Kind == "function"
+                && (lineOffset != patternStartOffset
+                    ? ShouldDeferCSharpFunctionSameLineAdvance(matchLine, lineOffset)
+                    : patternStartState.DeferCSharpFunction ??=
+                        ShouldDeferCSharpFunctionSameLineAdvance(matchLine, lineOffset)))
+            {
+                return PatternScanResult.NextPattern;
+            }
+
+            if (lang == "csharp"
+                && pattern.Kind is "event" or "delegate"
+                && pattern.BodyStyle == BodyStyle.None
+                && (lineOffset != patternStartOffset
+                    ? ShouldDeferCSharpEventOrDelegateSameLineAdvance(matchLine, lineOffset, pattern.Kind)
+                    : pattern.Kind == "event"
+                        ? patternStartState.DeferCSharpEvent ??=
+                            ShouldDeferCSharpEventOrDelegateSameLineAdvance(matchLine, lineOffset, pattern.Kind)
+                        : patternStartState.DeferCSharpDelegate ??=
+                            ShouldDeferCSharpEventOrDelegateSameLineAdvance(matchLine, lineOffset, pattern.Kind)))
+            {
+                return PatternScanResult.NextPattern;
+            }
+
+            if (lang is "javascript" or "typescript" or "css" or "java"
+                || (lang == "csharp"
+                    && pattern.Kind == "enum"
+                    && pattern.BodyStyle == BodyStyle.Brace
+                    && patternStartOffset > 0)
+                || (lang == "csharp"
+                    && pattern.Kind == "property"
+                    && pattern.BodyStyle == BodyStyle.None
+                    && !(lineOffset != patternStartOffset
+                        ? TryMatchAnyRecoverableCSharpPattern(
+                            matchLine,
+                            lineOffset,
+                            insideEnumBody: false,
+                            attributeParenDepth: 0,
+                            applicablePatterns,
+                            applyRequiredLiteralMatchInputGate,
+                            requiredLiteralGateCounts)
+                        : patternStartState.RecoverableCSharpPattern ??=
+                            TryMatchAnyRecoverableCSharpPattern(
+                                matchLine,
+                                lineOffset,
+                                insideEnumBody: false,
+                                attributeParenDepth: 0,
+                                applicablePatterns,
+                                applyRequiredLiteralMatchInputGate,
+                                requiredLiteralGateCounts))))
+            {
+                lineOffset = FindNextSameLineBraceStatementStart(matchLine, lineOffset + 1, lang);
+                return PatternScanResult.ContinueAt(lineOffset);
+            }
+
+            return PatternScanResult.NextPattern;
+        }
+
+        var absoluteStartColumn = lineOffset + match.Index;
+        if (lang is "java" or "kotlin" && javaLeadingAnnotationOffset > 0)
+            absoluteStartColumn = lineOffset + javaLeadingAnnotationOffset;
+
+        capturedMatch = new CapturedPatternMatch(match, absoluteStartColumn);
+        return PatternScanResult.Accepted;
+    }
+}
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternProgression.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternProgression.cs
new file mode 100644
index 000000000..1d9d626cb
--- /dev/null
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternProgression.cs
@@ -0,0 +1,352 @@
+namespace CodeIndex.Indexer;
+
+public static partial class SymbolExtractor
+{
+    private static PatternScanResult ResolveCSharpFieldProgression(
+        MatchedPatternCandidateContext candidate)
+    {
+        var lineContext = candidate.LineContext;
+        var extraction = lineContext.Extraction;
+        var lang = extraction.Lang;
+        var pattern = candidate.Pattern;
+        var patternMatchLine = candidate.PatternMatchLine;
+        var lineOffset = candidate.LineOffset;
+        var absoluteStartColumn = candidate.CapturedMatch.AbsoluteStartColumn;
+        var i = lineContext.LineIndex;
+        var csharpMatchLines = extraction.ScanInputs.CSharpMatchLines;
+        // C# plain-field matches (internally tagged as `property`, BodyStyle.None,
+        // then normalized to public `field`) need their own advance path. The
+        // generic `sameLineEndColumn`-based advance below resolves
+        // to -1 for BodyStyle.None and would set `stopAfterFirstPatternMatch`, which
+        // prevents structural siblings on the same line (e.g. the enclosing
+        // `public class C` in `public class C { public int X; }`) from being
+        // captured by later patterns. Instead, advance past the field terminator
+        // and continue the same-pattern scan so multiple same-line fields are
+        // still collected, and skip the stop flag so later patterns can still run.
+        // Closes #400.
+        // C# 通常フィールド（内部タグは `property`、BodyStyle.None、公開時に
+        // `field` へ正規化）は専用の前進経路を使う。
+        // 既定の `sameLineEndColumn` ベースの前進は BodyStyle.None では -1 に落ち、
+        // `stopAfterFirstPatternMatch` を立ててしまうため、同一行に存在する構造宣言
+        // （例: `public class C { public int X; }` の外側 class）を後続パターンで
+        // 取得できなくなる。代わりにフィールド終端を越えて同一パターンのスキャンを
+        // 続け、stop フラグを立てずに次のパターンにも機会を残す。Closes #400.
+        if (lang == "csharp"
+            && pattern.Kind == "property"
+            && pattern.BodyStyle == BodyStyle.None)
+        {
+            // Advance past the end of the full field declaration statement
+            // (the top-level `;`, with paren / bracket / brace depth tracking
+            // so `{` / `;` inside an initializer cannot short-circuit the
+            // scan) and continue. Using the statement end rather than the
+            // regex match end keeps later same-line field statements visible
+            // to the same pattern: without this, `A = 1; B;` stopped after
+            // capturing `A` and dropped `B`, and `A, B; C;` stopped after
+            // expanding `A, B` as a declarator list and dropped `C`. It also
+            // avoids the earlier regression where advancing to the match end
+            // (which sits on `=` when the field has an initializer) made the
+            // regex re-match the tail `1, _b, _c =` as a bogus field with
+            // `return_type = "1, _b,"`. If the scanner hits an unbalanced
+            // `}` (the closing brace of the enclosing type body) before a
+            // `;`, break out without setting `stopAfterFirstPatternMatch` so
+            // later unrelated patterns on the same line still get a chance
+            // to run. Closes #400.
+            // フィールド宣言文全体の終端（`;`、paren / bracket / brace 深さを
+            // 追って初期化子内の `{` や `;` で途切れないようにする）まで進めて
+            // 同一パターンで scan を続ける。regex match の末尾ではなく文の
+            // 終端で advance するのが肝心で、これが無いと `A = 1; B;` は
+            // `A` を拾った時点で止まって `B` を取り落とし、`A, B; C;` は
+            // `A, B` を declarator list として展開した時点で `C` を取り落とす。
+            // さらに、match の末尾（初期化子付きなら `=`）まで進めて continue
+            // すると正規表現が残りの `1, _b, _c =` を `return_type = "1, _b,"`
+            // の偽フィールドとして再マッチしていた旧 regression も再発しない。
+            // `;` より先に囲む型本体の閉じ `}`（深さ 0）に到達した場合は、
+            // `stopAfterFirstPatternMatch` を立てずに break して同一行の他
+            // パターン（class 等）へ機会を残す。Closes #400.
+            var statementEnd = FindCSharpSameLineStatementEnd(patternMatchLine, absoluteStartColumn);
+            if (statementEnd < patternMatchLine.Length
+                && patternMatchLine[statementEnd] == '}')
+            {
+                return PatternScanResult.NextPattern;
+            }
+            // Only continue the same-pattern same-line scan when the regex
+            // ran on a per-line single-line candidate (patternMatchLine ===
+            // csharpMatchLines[i]). For multi-line merged candidates,
+            // BuildCSharpPropertyMatchLine joined the header line with one
+            // or more continuation lines, so absoluteStartColumn sits in
+            // the merged-string column domain and does not line up with
+            // lines[i]'s raw columns. Continuing past statementEnd into a
+            // second regex hit would then feed a column > lines[i].Length
+            // into BuildCSharpMultilineSignature (which slices
+            // lines[startLineIndex][startColumn..]) and crash indexing with
+            // `startIndex cannot be larger than length of string`. The
+            // continuation line is revisited by the outer physical-line
+            // loop anyway (csharpSuppressedContinuationUntil is only bumped
+            // for expression-bodied properties), so for multi-line merged
+            // candidates we break here and let the outer loop handle any
+            // additional fields on that line. Closes #400.
+            // same-pattern での同一行 scan 継続は、per-line の単一行候補
+            // （patternMatchLine === csharpMatchLines[i]）のときだけ許す。
+            // BuildCSharpPropertyMatchLine が header 行と continuation 行を
+            // マージした複数行候補では、absoluteStartColumn がマージ後文字列の
+            // 列を指しており lines[i] の raw 列として使えない。この状態で
+            // statementEnd を越えて 2 個目の regex ヒットに進むと、
+            // BuildCSharpMultilineSignature の lines[startLineIndex][startColumn..]
+            // で範囲外アクセスとなり
+            // 「startIndex cannot be larger than length of string」で indexing が
+            // 落ちる。continuation 行は外側の物理行ループが再訪する
+            // （csharpSuppressedContinuationUntil は expression-bodied property
+            // でしか進まない）ため、複数行候補ではここで break して後続の
+            // 同一行フィールド抽出を外側ループに任せる。Closes #400.
+            if (csharpMatchLines == null
+                || !ReferenceEquals(patternMatchLine, csharpMatchLines[i]))
+            {
+                return PatternScanResult.NextPattern;
+            }
+            var advance = statementEnd;
+            if (advance <= lineOffset)
+                advance = lineOffset + 1;
+            if (advance >= patternMatchLine.Length)
+                return PatternScanResult.NextPattern;
+            lineOffset = advance;
+            return PatternScanResult.ContinueAt(lineOffset);
+        }
+
+        return PatternScanResult.Accepted;
+    }
+
+    private static PatternScanResult ResolveTerminalPatternProgression(
+        MatchedPatternCandidateContext candidate,
+        ShapedPatternSymbol shapedSymbol,
+        string emittedKind)
+    {
+        var lineContext = candidate.LineContext;
+        var extraction = lineContext.Extraction;
+        var lang = extraction.Lang;
+        var pattern = candidate.Pattern;
+        var matchLine = lineContext.PreparedLine.MatchLine;
+        var lineOffset = candidate.LineOffset;
+        var match = candidate.CapturedMatch.Match;
+        var absoluteStartColumn = candidate.CapturedMatch.AbsoluteStartColumn;
+        var line = lineContext.PreparedLine.SourceLine;
+        var i = lineContext.LineIndex;
+        var csharpMatchColumnToRaw = extraction.ScanInputs.CSharpMatchColumnToRaw;
+        var kind = emittedKind;
+        var startLine = shapedSymbol.StartLine;
+        var bodyStartLine = shapedSymbol.BodyStartLine;
+        var bodyEndLine = shapedSymbol.BodyEndLine;
+        var csharpSingleLineCollapsedMatch = shapedSymbol.SignatureResult.Bounds.CSharpSingleLineCollapsedMatch;
+        var sameLineEndColumn = shapedSymbol.SignatureResult.Bounds.SameLineEndColumn;
+        var sameLineEndUsesRawColumns = shapedSymbol.SignatureResult.Bounds.SameLineEndUsesRawColumns;
+        if (!CanContinueScanningSameLineBraceBody(lang, kind, pattern.BodyStyle, bodyEndLine, startLine, sameLineEndColumn, absoluteStartColumn))
+        {
+            if (lang == "csharp"
+                && pattern.BodyStyle == BodyStyle.Brace
+                && bodyStartLine == startLine
+                && kind is "class" or "struct" or "interface" or "enum" or "namespace")
+            {
+                // Hybrid same-line C# type headers can open the body on the header
+                // line and still close on a later line (`class C { int P { get; }`
+                // + next-line `}`). They are not compact same-line bodies, so the
+                // generic same-line brace-body path does not restart inside them.
+                // Explicitly restart just after the opening `{` so the first member
+                // that shares the header line is still visible to the full pattern
+                // list. Closes #580.
+                // ハイブリッドな C# の same-line 型ヘッダは、本体開始 `{` がヘッダ行に
+                // ありつつ閉じ `}` は後続行に置かれうる (`class C { int P { get; }`
+                // + 次行 `}`)。これは compact な same-line body ではないため、
+                // 既定の same-line brace-body 経路だけでは本体内へ再開できない。
+                // そこで開始 `{` の直後から明示的に再開し、ヘッダ行を共有する最初の
+                // member も通常の pattern 列で拾えるようにする。Closes #580.
+                var nextHeaderLineMemberOffset = FindNextSameLineNonClosingBraceStatementStart(
+                    matchLine,
+                    absoluteStartColumn + Math.Max(1, match.Length),
+                    lang);
+                if (nextHeaderLineMemberOffset > absoluteStartColumn
+                    && nextHeaderLineMemberOffset < matchLine.Length)
+                {
+                    return PatternScanResult.RestartAt(nextHeaderLineMemberOffset);
+                }
+            }
+
+            if (lang == "csharp"
+                && sameLineEndColumn >= absoluteStartColumn
+                && CanRestartCSharpSameLineSiblingScan(kind))
+            {
+                // Compact same-line C# members form a sibling stream rather than a
+                // single terminal match: after `event E;`, `void M();`, or
+                // `int P { get; set; }`, later same-line declarations still need
+                // to reach earlier patterns in the list. Restart from the next
+                // top-level statement boundary so mixed-kind siblings like
+                // `event + property`, `method + property`, and `property + event`
+                // are all visible. When there is no later statement, keep the old
+                // stop-after-first-match behavior to avoid reopening duplicate
+                // paths on ordinary single-declaration lines. Closes #470 / #473.
+                // 同一行のコンパクトな C# member は 1 回限りの terminal match ではなく、
+                // sibling 宣言のストリームとして扱う。`event E;` や `void M();`、
+                // `int P { get; set; }` の後ろに続く宣言も、pattern 列の先頭側にある
+                // property などへ到達できる必要がある。そこで次の top-level 文境界から
+                // pattern 列全体を再走査し、`event + property`、`method + property`、
+                // `property + event` のような mixed-kind sibling をすべて可視化する。
+                // 後続宣言が無い行では従来どおり stop-after-first-match を維持し、
+                // 通常の単独宣言行で duplicate 経路を再び開かない。Closes #470 / #473.
+                if (csharpSingleLineCollapsedMatch && sameLineEndUsesRawColumns)
+                {
+                    var rawNextSiblingOffset = FindNextSameLineNonClosingBraceStatementStart(line, sameLineEndColumn + 1, lang);
+                    if (rawNextSiblingOffset > sameLineEndColumn)
+                    {
+                        return PatternScanResult.RestartAt(
+                            TranslateCSharpRawColumnToCollapsed(
+                                csharpMatchColumnToRaw,
+                                i,
+                                rawNextSiblingOffset,
+                                matchLine.Length,
+                                line.Length));
+                    }
+                }
+                else
+                {
+                    var nextSiblingOffset = FindNextSameLineNonClosingBraceStatementStart(matchLine, sameLineEndColumn + 1, lang);
+                    if (nextSiblingOffset > sameLineEndColumn
+                        && nextSiblingOffset < matchLine.Length)
+                    {
+                        return PatternScanResult.RestartAt(nextSiblingOffset);
+                    }
+                }
+            }
+
+            // Batch `set` assignments can legitimately repeat on a single line via
+            // `&` command-chaining (`set A=1 & set B=2`), parenthesized grouping
+            // (`if ... ( set P=1 ) else set Q=2`), or `for`-loop bodies
+            // (`for %%I in (1) do set LOOPVAR=%%I`). The brace-body rescan path
+            // above is JS/TS/CSS/C#-only, so drive the advance explicitly for the
+            // batch property pattern instead of short-circuiting after the first
+            // match. Forward progress is guaranteed because `match.Length >= 1`
+            // (the regex requires a literal `set\s+NAME=` tail).
+            // batch の `set` 代入は `&` 連結や `( ... ) else ... `、`for ... do ...` で
+            // 1 行に複数回現れうる。上の brace-body 再スキャンは JS/TS/CSS/C# 限定なので、
+            // batch の property パターンだけは explicit に advance して追加マッチも拾う。
+            // 前進は `match.Length >= 1` (正規表現が `set\s+NAME=` を要求するため) で保証される。
+            if (lang == "batch"
+                && pattern.BodyStyle == BodyStyle.None
+                && pattern.Kind == "property")
+            {
+                var nextBatchOffset = absoluteStartColumn + Math.Max(1, match.Length);
+                if (nextBatchOffset <= lineOffset)
+                    return PatternScanResult.NextPattern;
+                lineOffset = nextBatchOffset;
+                return PatternScanResult.ContinueAt(lineOffset);
+            }
+
+            // Stop after first match per line to avoid duplicate symbols
+            // (e.g. C# method pattern + constructor pattern both matching)
+            // 1行につき最初のマッチのみ採用し重複を防ぐ
+            return PatternScanResult.StopLine;
+        }
+
+        return PatternScanResult.Accepted;
+    }
+
+    private static PatternScanResult ResolveBraceBodyPatternProgression(
+        MatchedPatternCandidateContext candidate,
+        ShapedPatternSymbol shapedSymbol,
+        string emittedKind)
+    {
+        var lineContext = candidate.LineContext;
+        var extraction = lineContext.Extraction;
+        var lang = extraction.Lang;
+        var pattern = candidate.Pattern;
+        var matchLine = lineContext.PreparedLine.MatchLine;
+        var match = candidate.CapturedMatch.Match;
+        var absoluteStartColumn = candidate.CapturedMatch.AbsoluteStartColumn;
+        var line = lineContext.PreparedLine.SourceLine;
+        var i = lineContext.LineIndex;
+        var csharpMatchColumnToRaw = extraction.ScanInputs.CSharpMatchColumnToRaw;
+        var kind = emittedKind;
+        var csharpSingleLineCollapsedMatch = shapedSymbol.SignatureResult.Bounds.CSharpSingleLineCollapsedMatch;
+        var sameLineEndColumn = shapedSymbol.SignatureResult.Bounds.SameLineEndColumn;
+        var sameLineEndUsesRawColumns = shapedSymbol.SignatureResult.Bounds.SameLineEndUsesRawColumns;
+        // For C# class-like kinds with a same-line brace body, step into the body
+        // (advance just past the match header) instead of jumping past the closing
+        // `}`. This lets nested same-line declarations be captured, e.g.
+        // `public class Outer { public class Inner { public int X; } }` matches
+        // Outer and Inner, with X correctly attached to Inner. JavaScript/TypeScript
+        // does not need this because class-body members there are extracted via the
+        // separate JS/TS lexer/state machine; the brace-skip path only handles
+        // same-line siblings like `class A {} class B {}`. Closes #400.
+        // C# の class 系 kind は同一行の `{...}` 本体を飛び越えず、ヘッダ直後へ
+        // 進めて本体内部の宣言（例: `public class Outer { public class Inner { ... } }`
+        // の Inner）を拾えるようにする。JavaScript/TypeScript は class body の
+        // member 抽出を専用 lexer/state machine で行うため従来通り終端の後ろへ
+        // 進め、同一行 sibling（`class A {} class B {}` など）だけを扱う。Closes #400.
+        var sameLineRestartComparisonColumn = csharpSingleLineCollapsedMatch && sameLineEndUsesRawColumns
+            ? TranslateCSharpRawColumnToCollapsed(
+                csharpMatchColumnToRaw,
+                i,
+                sameLineEndColumn,
+                matchLine.Length,
+                line.Length)
+            : sameLineEndColumn;
+        if (CanStepIntoSameLineTypeBody(lang, kind))
+        {
+            var nextTypeBodyOffset = FindNextSameLineNonClosingBraceStatementStart(
+                matchLine,
+                absoluteStartColumn + Math.Max(1, match.Length),
+                lang);
+            if (nextTypeBodyOffset > absoluteStartColumn
+                && nextTypeBodyOffset < sameLineRestartComparisonColumn
+                && (nextTypeBodyOffset >= matchLine.Length || matchLine[nextTypeBodyOffset] != '}'))
+            {
+                return PatternScanResult.RestartAt(nextTypeBodyOffset);
+            }
+        }
+
+        var nextSameLineOffset = -1;
+        if (csharpSingleLineCollapsedMatch && sameLineEndUsesRawColumns)
+        {
+            var rawNextSameLineOffset = FindNextSameLineNonClosingBraceStatementStart(line, sameLineEndColumn + 1, lang);
+            if (rawNextSameLineOffset > sameLineEndColumn)
+            {
+                nextSameLineOffset = TranslateCSharpRawColumnToCollapsed(
+                    csharpMatchColumnToRaw,
+                    i,
+                    rawNextSameLineOffset,
+                    matchLine.Length,
+                    line.Length);
+            }
+        }
+        else
+        {
+            nextSameLineOffset = FindNextSameLineNonClosingBraceStatementStart(matchLine, sameLineEndColumn + 1, lang);
+        }
+        var sameLineAdvanceComparisonColumn = sameLineRestartComparisonColumn;
+        if (CanStepIntoSameLineTypeBody(lang, kind)
+            && nextSameLineOffset > sameLineAdvanceComparisonColumn
+            && nextSameLineOffset < matchLine.Length
+            && matchLine[nextSameLineOffset] != '}')
+        {
+            return PatternScanResult.RestartAt(nextSameLineOffset);
+        }
+        if (lang == "csharp"
+            && kind == "property"
+            && pattern.BodyStyle == BodyStyle.Brace
+            && nextSameLineOffset > sameLineAdvanceComparisonColumn
+            && nextSameLineOffset < matchLine.Length)
+        {
+            // A same-line brace-body property that is followed by another sibling
+            // declaration (`P { get; set; } public void M() { }`) must hand control
+            // back to the whole pattern list at the next statement start, otherwise
+            // earlier rows like the C# method regex never get a chance to see the
+            // trailing sibling and mixed-kind lines lose one side.
+            // Closes #473 follow-up.
+            // 後続 sibling 宣言を伴う same-line brace-body property
+            // (`P { get; set; } public void M() { }`) は、次の文開始位置から
+            // pattern 全体へ制御を戻す必要がある。そうしないと、C# method regex
+            // のような earlier row が後続 sibling を見られず、mixed-kind の
+            // 同一行で片側が欠落する。Closes #473 follow-up.
+            return PatternScanResult.RestartAt(nextSameLineOffset);
+        }
+
+        return PatternScanResult.ContinueAt(nextSameLineOffset);
+    }
+}

From 3293288515a5c7a5241ee9afa44063ef3dae033a Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 05:44:45 +0900
Subject: [PATCH 05/45] Unify caller and callee graph queries

---
 .../Database/DbReader.GraphQueries.cs         | 970 +++---------------
 .../DbReader.GraphReferenceQueries.cs         | 659 ++++++++++++
 .../DbReader.GraphReferenceQueryExecution.cs  | 144 +++
 3 files changed, 918 insertions(+), 855 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbReader.GraphReferenceQueries.cs
 create mode 100644 src/CodeIndex/Database/DbReader.GraphReferenceQueryExecution.cs

diff --git a/src/CodeIndex/Database/DbReader.GraphQueries.cs b/src/CodeIndex/Database/DbReader.GraphQueries.cs
index 0023cda06..b851bba92 100644
--- a/src/CodeIndex/Database/DbReader.GraphQueries.cs
+++ b/src/CodeIndex/Database/DbReader.GraphQueries.cs
@@ -86,205 +86,30 @@ private List<CallerResult> GetCallersCore(string query, int limit, string? lang,
             return new List<CallerResult>();
         lang = NormalizeQueryLanguage(lang);
         query = NormalizeSymbolSearchQuery(query, lang, exact) ?? query ?? string.Empty;
-        if (!_hasReferencesTable) return new List<CallerResult>();
-        using var cmd = _conn.CreateCommand();
-        var referenceLineJoin = ReferenceLineJoinSql("r");
-        var contextSql = ReferenceContextSql("r");
-        var selfReferenceSql = _referenceColumns.Contains("is_self_reference") ? "r.is_self_reference" : "0";
-        var mutualRecursionSql = _referenceColumns.Contains("is_mutual_recursion") ? "r.is_mutual_recursion" : "0";
-        var callerContainerPredicate = BuildCallerContainerPredicate("f", "r");
-        var supportedLangPredicate = BuildGraphSupportedLanguagePredicate(cmd, "f", "graphLang");
-
-        var groupedReferenceKindSql = rawKinds
-            ? GetGroupedCallerReferenceKindSql("r.reference_kind")
-            : GetGroupedCallerLogicalReferenceKindSql("r.reference_kind");
-        var groupedReferenceKindGroupSql = rawKinds
-            ? GetRawReferenceKindSql("r.reference_kind")
-            : GetLogicalReferenceKindSql("r.reference_kind");
-        var sql = @"
-            WITH logical_references AS (
-                SELECT f.path, f.lang, r.container_kind, r.container_name, r.symbol_name,
-                       " + groupedReferenceKindSql + @" AS reference_kind,
-                       r.reference_kind AS raw_reference_kind,
-                       " + groupedReferenceKindGroupSql + @" AS count_reference_kind,
-                       COUNT(*) AS reference_count,
-                       " + ReferenceWeightedScoreSql("r.reference_kind") + @" AS weighted_score,
-                       (CAST(r.line AS INTEGER) * 4294967296 + r.column_number) AS location_key,
-                       MAX(" + selfReferenceSql + @") AS is_self_reference,
-                       MAX(" + mutualRecursionSql + @") AS is_mutual_recursion
-                FROM symbol_references r
-                JOIN files f ON r.file_id = f.id" + referenceLineJoin + @"
-                WHERE " + callerContainerPredicate + @"
-                  AND " + GetCallableReferenceKindPredicateSql("r.reference_kind", referenceKind, "f.lang", includeMemberReads) + @"
-                  AND " + supportedLangPredicate;
-        if (targetSymbolId != null && HasTable("symbol_reference_candidates"))
-        {
-            // Candidate membership alone is not an edge: an ambiguous reference can list
-            // several possible targets. Only authoritative resolution states may contribute
-            // callers to a candidate-specific inspect bundle.
-            // candidate membership だけでは edge ではない。ambiguous reference は複数の
-            // 候補を持ち得るため、candidate 別 inspect bundle の callers には authoritative
-            // な resolution state だけを採用する。
-            sql += _referenceColumns.Contains("resolution_state")
-                ? " AND r.resolution_state IN ('resolved', 'resolved_group')"
-                : " AND 1 = 0";
-            sql += @"
-                AND EXISTS (
-                    SELECT 1
-                    FROM symbol_reference_candidates AS identity_candidate
-                    WHERE identity_candidate.reference_id = r.id
-                      AND identity_candidate.symbol_id = @targetSymbolId
-                )";
-        }
-        if (excludeSelfReferences)
-            sql += $" AND {selfReferenceSql} = 0";
-        var allowSqlLeafFallback = AllowSqlLeafFallbackForQuery(query);
-        var allowCSharpQualifiedContextMatch = SqlNameResolver.HasQualifier(query)
-            && !HasQualifiedSymbolDefinition(query, lang, pathPatterns, excludePathPatterns, excludeTests);
-        var allowQualifiedLeafFallback = HasSingleQualifiedSymbolDefinition(query, lang, pathPatterns, excludePathPatterns, excludeTests);
-        var useSqlQualifiedContextMatch = SqlNameResolver.HasQualifier(query);
-        var cssScssVariableAlias = ComputeCssScssVariableAlias(query);
-        var cssScssVariableAliasScope = cssScssVariableAlias != null
-            ? " AND f.lang = 'css'"
-            : string.Empty;
-        if (useSqlQualifiedContextMatch && exact && _foldReady)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: true, like: false);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: true);
-            sql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND {BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")}) OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContextMatch && exact)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: false, like: false);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: false);
-            sql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND r.symbol_name = @query COLLATE NOCASE) OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContextMatch && _foldReady)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: true, like: true);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: true);
-            sql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND r.symbol_name LIKE @query ESCAPE '\\') OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContextMatch)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: false, like: true);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: false);
-            sql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND r.symbol_name LIKE @query ESCAPE '\\') OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (exact && _foldReady)
-            sql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND ({BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")} OR (r.symbol_name_folded = @queryCssScssVariableAlias{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND r.symbol_name_folded = @aliasQueryLeafFolded))"
-                    : $" AND ({BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")} OR (f.lang = 'sql' AND r.symbol_name_folded = @aliasQueryLeafFolded))"
-                : $" AND {BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")}";
-        else if (exact)
-            sql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND (r.symbol_name = @query COLLATE NOCASE OR (r.symbol_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))"
-                    : " AND (r.symbol_name = @query COLLATE NOCASE OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))"
-                : " AND r.symbol_name = @query COLLATE NOCASE";
-        else
-            sql += cssScssVariableAlias != null
-                ? $" AND (r.symbol_name LIKE @query ESCAPE '\\' OR (r.symbol_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))"
-                : " AND (r.symbol_name LIKE @query ESCAPE '\\' OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))";
-        if (lang != null)
-        {
-            sql += IncludeAmbiguousMSourceForIdentityTarget(lang, targetSymbolId)
-                ? " AND (f.lang = @lang OR f.lang = 'ambiguous_m')"
-                : " AND f.lang = @lang";
-        }
-        sql += BuildCSharpBareMemberReferenceFilter(
+        if (!_hasReferencesTable)
+            return new List<CallerResult>();
+
+        var request = CreateGraphReferenceQueryRequest(
             query,
+            limit,
             lang,
-            "f",
-            "r",
-            includeQualifiedCommonCalls);
-        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
-        sql += @"
-            GROUP BY f.path, f.lang, r.container_kind, r.container_name, r.symbol_name, r.file_id, r.line, r.column_number, " + groupedReferenceKindGroupSql + @", r.reference_kind
-            )
-            SELECT path, lang, " + BuildCallerKindProjectionSql("r") + @" AS container_kind, " + BuildCallerNameProjectionSql("r") + @" AS container_name, symbol_name,
-                   " + (rawKinds ? GetGroupedCallerReferenceKindSql("r.reference_kind") : GetPreferredLogicalReferenceKindSql("r.reference_kind")) + @" AS reference_kind,
-                   (MIN(location_key) / 4294967296) AS first_line,
-                   (MIN(location_key) % 4294967296) AS first_column,
-                   SUM(r.reference_count) AS reference_count,
-                   GROUP_CONCAT(DISTINCT r.reference_kind) AS reference_kinds,
-                   GROUP_CONCAT(r.count_reference_kind || ':' || r.reference_count) AS reference_kind_counts,
-                   SUM(r.weighted_score) AS weighted_score,
-                   MAX(r.is_self_reference) AS is_self_reference,
-                   MAX(r.is_mutual_recursion) AS is_mutual_recursion
-            FROM logical_references r
-            GROUP BY path, lang, container_kind, container_name, symbol_name";
-        sql += $" ORDER BY {BuildReferenceRankOrderSql(rankMode, "r.symbol_name")} LIMIT @limit OFFSET @offset";
-
-        cmd.CommandText = sql;
-        string callersQueryParam;
-        if (!exact)
-            callersQueryParam = $"%{EscapeLikeQuery(query)}%";
-        else if (_foldReady)
-            callersQueryParam = FoldNameForLanguage(query, lang);
-        else
-            callersQueryParam = query;
-        if (exact && _foldReady)
-            AddPersistedFoldedNameQueryParameters(cmd, "@query", query, lang);
-        else
-            SqliteCommandPolicy.Add(cmd, "@query", callersQueryParam);
-        SqliteCommandPolicy.Add(cmd, "@aliasQuery", query);
-        AddQualifiedGraphQueryParameters(cmd, query, allowQualifiedLeafFallback, allowCSharpQualifiedContextMatch);
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryLeafFolded", NameFold.Fold(SqlNameResolver.GetLeafName(query)) ?? SqlNameResolver.GetLeafName(query));
-        if (cssScssVariableAlias != null)
-        {
-            var aliasParam = exact && _foldReady
-                ? NameFold.Fold(cssScssVariableAlias) ?? cssScssVariableAlias
-                : cssScssVariableAlias;
-            SqliteCommandPolicy.Add(cmd, "@queryCssScssVariableAlias", aliasParam);
-        }
-        SqliteCommandPolicy.Add(cmd, "@rawQuery", query);
-        SqliteCommandPolicy.Add(cmd, "@rankingQuery", query.Trim());
-        if (RequiresReferenceKindParameter(referenceKind))
-            SqliteCommandPolicy.Add(cmd, "@referenceKind", referenceKind);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", NormalizeQueryLanguage(lang));
-        if (targetSymbolId != null && HasTable("symbol_reference_candidates"))
-            SqliteCommandPolicy.Add(cmd, "@targetSymbolId", targetSymbolId.Value);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        SqliteCommandPolicy.Add(cmd, "@limit", limit);
-        SqliteCommandPolicy.Add(cmd, "@offset", Math.Max(0, offset));
-
-        var results = new List<CallerResult>();
-        using var reader = cmd.ExecuteTrackedReader();
-        while (reader.TrackedRead())
-        {
-            var primaryKind = reader.GetString(5);
-            var kindAggregate = TruncateReferenceKindAggregate(GetNullableString(reader, 9), out var kindsTruncated);
-            var countAggregate = TruncateReferenceKindAggregate(GetNullableString(reader, 10), out var countsTruncated);
-            var kinds = ParseDistinctReferenceKinds(kindAggregate, primaryKind);
-            var counts = ParseReferenceKindCounts(countAggregate, primaryKind, reader.GetInt32(8));
-            results.Add(new CallerResult
-            {
-                Path = reader.GetString(0),
-                Lang = GetNullableString(reader, 1),
-                CallerKind = GetNullableString(reader, 2),
-                CallerName = GetNullableString(reader, 3),
-                CalleeName = reader.GetString(4),
-                ReferenceKind = primaryKind,
-                ReferenceKinds = kinds,
-                HasMixedReferenceKinds = kinds.Count > 1,
-                ReferenceKindCounts = counts,
-                AggregateTruncated = kindsTruncated || countsTruncated,
-                ReferenceWeightScore = reader.GetDouble(11),
-                FirstLine = reader.GetInt32(6),
-                FirstColumn = reader.GetInt32(7),
-                ReferenceCount = reader.GetInt32(8),
-                HasSelfReference = reader.GetInt32(12) != 0,
-                HasMutualRecursion = reader.GetInt32(13) != 0,
-            });
-        }
-        return results;
+            referenceKind,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            exact,
+            rawKinds,
+            includeQualifiedCommonCalls,
+            includeMemberReads,
+            identitySymbolId: targetSymbolId,
+            excludeSelfReferences,
+            offset);
+        var plan = BuildGraphReferenceQueryPlan(
+            CallerGraphReferenceDirection,
+            request,
+            GraphReferenceQueryShape.List,
+            rankMode);
+        return ExecuteGraphReferenceList(plan, ProjectCallerResult);
     }
 
     public int CountCallers(string query, int limit = 20, string? lang = null, string? referenceKind = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, bool exact = false, bool rawKinds = false, bool includeQualifiedCommonCalls = false, bool includeMemberReads = false)
@@ -293,115 +118,26 @@ public int CountCallers(string query, int limit = 20, string? lang = null, strin
             return 0;
         lang = NormalizeQueryLanguage(lang);
         query = NormalizeSymbolSearchQuery(query, lang, exact) ?? query ?? string.Empty;
-        if (!_hasReferencesTable) return 0;
-        using var cmd = _conn.CreateCommand();
-        var referenceLineJoin = ReferenceLineJoinSql("r");
-        var contextSql = ReferenceContextSql("r");
-        var groupedSql = @"
-            SELECT path, lang, container_kind, container_name, symbol_name
-            FROM (
-                SELECT f.path AS path, f.lang AS lang, r.container_kind AS container_kind,
-                       r.container_name AS container_name, r.symbol_name AS symbol_name
-            FROM symbol_references r
-            JOIN files f ON r.file_id = f.id" + referenceLineJoin + @"
-            WHERE " + BuildCallerContainerPredicate("f", "r");
-        groupedSql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "f", "graphLang")}";
-
-        groupedSql += $" AND {GetCallableReferenceKindPredicateSql("r.reference_kind", referenceKind, "f.lang", includeMemberReads)}";
-        var allowSqlLeafFallback = AllowSqlLeafFallbackForQuery(query);
-        var allowCSharpQualifiedContextMatch = SqlNameResolver.HasQualifier(query)
-            && !HasQualifiedSymbolDefinition(query, lang, pathPatterns, excludePathPatterns, excludeTests);
-        var allowQualifiedLeafFallback = HasSingleQualifiedSymbolDefinition(query, lang, pathPatterns, excludePathPatterns, excludeTests);
-        var useSqlQualifiedContextMatch = SqlNameResolver.HasQualifier(query);
-        var cssScssVariableAlias = ComputeCssScssVariableAlias(query);
-        var cssScssVariableAliasScope = cssScssVariableAlias != null
-            ? " AND f.lang = 'css'"
-            : string.Empty;
-        if (useSqlQualifiedContextMatch && exact && _foldReady)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: true, like: false);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: true);
-            groupedSql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND {BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")}) OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContextMatch && exact)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: false, like: false);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: false);
-            groupedSql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND r.symbol_name = @query COLLATE NOCASE) OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContextMatch && _foldReady)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: true, like: true);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: true);
-            groupedSql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND r.symbol_name LIKE @query ESCAPE '\\') OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContextMatch)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: false, like: true);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: false);
-            groupedSql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND r.symbol_name LIKE @query ESCAPE '\\') OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (exact && _foldReady)
-            groupedSql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND ({BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")} OR (r.symbol_name_folded = @queryCssScssVariableAlias{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND r.symbol_name_folded = @aliasQueryLeafFolded))"
-                    : $" AND ({BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")} OR (f.lang = 'sql' AND r.symbol_name_folded = @aliasQueryLeafFolded))"
-                : $" AND {BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")}";
-        else if (exact)
-            groupedSql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND (r.symbol_name = @query COLLATE NOCASE OR (r.symbol_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))"
-                    : " AND (r.symbol_name = @query COLLATE NOCASE OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))"
-                : " AND r.symbol_name = @query COLLATE NOCASE";
-        else
-            groupedSql += cssScssVariableAlias != null
-                ? $" AND (r.symbol_name LIKE @query ESCAPE '\\' OR (r.symbol_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))"
-                : " AND (r.symbol_name LIKE @query ESCAPE '\\' OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))";
-        if (lang != null)
-            groupedSql += " AND f.lang = @lang";
-        groupedSql += BuildCSharpBareMemberReferenceFilter(
+        if (!_hasReferencesTable)
+            return 0;
+
+        var request = CreateGraphReferenceQueryRequest(
             query,
+            limit,
             lang,
-            "f",
-            "r",
-            includeQualifiedCommonCalls);
-        AppendPathFilters(ref groupedSql, pathPatterns, excludePathPatterns, excludeTests);
-        groupedSql += $" GROUP BY f.path, f.lang, r.container_kind, r.container_name, r.symbol_name, r.file_id, r.line, r.column_number, {(rawKinds ? GetRawReferenceKindSql("r.reference_kind") : GetLogicalReferenceKindSql("r.reference_kind"))}";
-        groupedSql += " ) grouped_call_sites GROUP BY path, lang, container_kind, container_name, symbol_name LIMIT @limit";
-
-        cmd.CommandText = $"SELECT COUNT(*) FROM ({groupedSql})";
-        var value = !exact
-            ? $"%{EscapeLikeQuery(query)}%"
-            : _foldReady
-                ? FoldNameForLanguage(query, lang)
-                : query;
-        if (exact && _foldReady)
-            AddPersistedFoldedNameQueryParameters(cmd, "@query", query, lang);
-        else
-            SqliteCommandPolicy.Add(cmd, "@query", value);
-        SqliteCommandPolicy.Add(cmd, "@aliasQuery", query);
-        AddQualifiedGraphQueryParameters(cmd, query, allowQualifiedLeafFallback, allowCSharpQualifiedContextMatch);
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryLeafFolded", NameFold.Fold(SqlNameResolver.GetLeafName(query)) ?? SqlNameResolver.GetLeafName(query));
-        if (cssScssVariableAlias != null)
-        {
-            var aliasParam = exact && _foldReady
-                ? NameFold.Fold(cssScssVariableAlias) ?? cssScssVariableAlias
-                : cssScssVariableAlias;
-            SqliteCommandPolicy.Add(cmd, "@queryCssScssVariableAlias", aliasParam);
-        }
-        if (RequiresReferenceKindParameter(referenceKind))
-            SqliteCommandPolicy.Add(cmd, "@referenceKind", referenceKind);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", NormalizeQueryLanguage(lang));
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        SqliteCommandPolicy.Add(cmd, "@limit", limit);
-
-        var raw = cmd.ExecuteScalar();
-        return raw is long l ? (int)l : Convert.ToInt32(raw);
+            referenceKind,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            exact,
+            rawKinds,
+            includeQualifiedCommonCalls,
+            includeMemberReads);
+        var plan = BuildGraphReferenceQueryPlan(
+            CallerGraphReferenceDirection,
+            request,
+            GraphReferenceQueryShape.LimitedCount);
+        return ExecuteGraphReferenceLimitedCount(plan);
     }
 
     public QueryCountResult CountCallersTotal(string query, string? lang = null, string? referenceKind = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, bool exact = false, bool rawKinds = false, bool includeQualifiedCommonCalls = false, bool includeMemberReads = false)
@@ -434,131 +170,24 @@ private QueryCountResult CountCallersTotalCore(
         if (!_hasReferencesTable)
             return new QueryCountResult(0, 0);
 
-        using var cmd = _conn.CreateCommand();
-        var referenceLineJoin = ReferenceLineJoinSql("r");
-        var contextSql = ReferenceContextSql("r");
-        var cssScssVariableAlias = ComputeCssScssVariableAlias(query);
-        var cssScssVariableAliasScope = cssScssVariableAlias != null
-            ? " AND f.lang = 'css'"
-            : string.Empty;
-        var groupedSql = @"
-            SELECT path, lang
-            FROM (
-                SELECT f.path AS path, f.lang AS lang, r.container_kind AS container_kind,
-                       r.container_name AS container_name, r.symbol_name AS symbol_name
-                FROM symbol_references r
-                JOIN files f ON r.file_id = f.id" + referenceLineJoin + @"
-                WHERE " + BuildCallerContainerPredicate("f", "r");
-        groupedSql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "f", "graphLang")}";
-
-        groupedSql += $" AND {GetCallableReferenceKindPredicateSql("r.reference_kind", referenceKind, "f.lang", includeMemberReads)}";
-        if (targetSymbolId != null && HasTable("symbol_reference_candidates"))
-        {
-            groupedSql += _referenceColumns.Contains("resolution_state")
-                ? " AND r.resolution_state IN ('resolved', 'resolved_group')"
-                : " AND 1 = 0";
-            groupedSql += @"
-                AND EXISTS (
-                    SELECT 1
-                    FROM symbol_reference_candidates AS identity_candidate
-                    WHERE identity_candidate.reference_id = r.id
-                      AND identity_candidate.symbol_id = @targetSymbolId
-                )";
-        }
-        var allowSqlLeafFallback = AllowSqlLeafFallbackForQuery(query);
-        var allowCSharpQualifiedContextMatch = SqlNameResolver.HasQualifier(query)
-            && !HasQualifiedSymbolDefinition(query, lang, pathPatterns, excludePathPatterns, excludeTests);
-        var allowQualifiedLeafFallback = HasSingleQualifiedSymbolDefinition(query, lang, pathPatterns, excludePathPatterns, excludeTests);
-        var useSqlQualifiedContextMatch = SqlNameResolver.HasQualifier(query);
-        if (useSqlQualifiedContextMatch && exact && _foldReady)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: true, like: false);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: true);
-            groupedSql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND {BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")}) OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContextMatch && exact)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: false, like: false);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: false);
-            groupedSql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND r.symbol_name = @query COLLATE NOCASE) OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContextMatch && _foldReady)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: true, like: true);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: true);
-            groupedSql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND r.symbol_name LIKE @query ESCAPE '\\') OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContextMatch)
-        {
-            var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: false, like: true);
-            var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: false);
-            groupedSql += $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND r.symbol_name LIKE @query ESCAPE '\\') OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
-        }
-        else if (exact && _foldReady)
-            groupedSql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND ({BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")} OR (r.symbol_name_folded = @queryCssScssVariableAlias{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND r.symbol_name_folded = @aliasQueryLeafFolded))"
-                    : $" AND ({BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")} OR (f.lang = 'sql' AND r.symbol_name_folded = @aliasQueryLeafFolded))"
-                : $" AND {BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")}";
-        else if (exact)
-            groupedSql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND (r.symbol_name = @query COLLATE NOCASE OR (r.symbol_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))"
-                    : " AND (r.symbol_name = @query COLLATE NOCASE OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))"
-                : " AND r.symbol_name = @query COLLATE NOCASE";
-        else
-            groupedSql += cssScssVariableAlias != null
-                ? $" AND (r.symbol_name LIKE @query ESCAPE '\\' OR (r.symbol_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))"
-                : " AND (r.symbol_name LIKE @query ESCAPE '\\' OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE))";
-        if (lang != null)
-        {
-            groupedSql += IncludeAmbiguousMSourceForIdentityTarget(lang, targetSymbolId)
-                ? " AND (f.lang = @lang OR f.lang = 'ambiguous_m')"
-                : " AND f.lang = @lang";
-        }
-        groupedSql += BuildCSharpBareMemberReferenceFilter(
+        var request = CreateGraphReferenceQueryRequest(
             query,
+            limit: 0,
             lang,
-            "f",
-            "r",
-            includeQualifiedCommonCalls);
-        AppendPathFilters(ref groupedSql, pathPatterns, excludePathPatterns, excludeTests);
-        groupedSql += $" GROUP BY f.path, f.lang, r.container_kind, r.container_name, r.symbol_name, r.file_id, r.line, r.column_number, {(rawKinds ? GetRawReferenceKindSql("r.reference_kind") : GetLogicalReferenceKindSql("r.reference_kind"))}";
-        groupedSql += " ) grouped_call_sites GROUP BY path, lang, container_kind, container_name, symbol_name";
-
-        cmd.CommandText = $"SELECT COUNT(*), COUNT(DISTINCT path), MAX(CASE WHEN lang = 'sql' THEN 1 ELSE 0 END) FROM ({groupedSql})";
-        var value = !exact
-            ? $"%{EscapeLikeQuery(query)}%"
-            : _foldReady
-              ? FoldNameForLanguage(query, lang)
-                : query;
-        if (exact && _foldReady)
-            AddPersistedFoldedNameQueryParameters(cmd, "@query", query, lang);
-        else
-            SqliteCommandPolicy.Add(cmd, "@query", value);
-        SqliteCommandPolicy.Add(cmd, "@aliasQuery", query);
-        AddQualifiedGraphQueryParameters(cmd, query, allowQualifiedLeafFallback, allowCSharpQualifiedContextMatch);
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryLeafFolded", NameFold.Fold(SqlNameResolver.GetLeafName(query)) ?? SqlNameResolver.GetLeafName(query));
-        if (cssScssVariableAlias != null)
-        {
-            var aliasParam = exact && _foldReady
-                ? NameFold.Fold(cssScssVariableAlias) ?? cssScssVariableAlias
-                : cssScssVariableAlias;
-            SqliteCommandPolicy.Add(cmd, "@queryCssScssVariableAlias", aliasParam);
-        }
-        if (RequiresReferenceKindParameter(referenceKind))
-            SqliteCommandPolicy.Add(cmd, "@referenceKind", referenceKind);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", NormalizeQueryLanguage(lang));
-        if (targetSymbolId != null)
-            SqliteCommandPolicy.Add(cmd, "@targetSymbolId", targetSymbolId.Value);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-
-        return ExecuteCountSummary(cmd);
+            referenceKind,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            exact,
+            rawKinds,
+            includeQualifiedCommonCalls,
+            includeMemberReads,
+            identitySymbolId: targetSymbolId);
+        var plan = BuildGraphReferenceQueryPlan(
+            CallerGraphReferenceDirection,
+            request,
+            GraphReferenceQueryShape.TotalCount);
+        return ExecuteGraphReferenceTotalCount(plan);
     }
 
     /// <summary>
@@ -596,177 +225,29 @@ private List<CalleeResult> GetCalleesCore(string query, int limit, string? lang,
             return new List<CalleeResult>();
         lang = NormalizeQueryLanguage(lang);
         query = NormalizeSymbolSearchQuery(query, lang, exact) ?? query ?? string.Empty;
-        if (!_hasReferencesTable) return new List<CalleeResult>();
-        using var cmd = _conn.CreateCommand();
-
-        var preferredCalleeKindSql = rawKinds
-            ? GetPreferredReferenceKindSql("r.reference_kind")
-            : GetPreferredLogicalReferenceKindSql("r.reference_kind");
-        var calleeGroupKindSql = rawKinds
-            ? GetRawReferenceKindSql("r.reference_kind")
-            : GetLogicalReferenceKindSql("r.reference_kind");
-        var referenceSpanLengthSql = _referenceColumns.Contains("span_length")
-            ? "r.span_length"
-            : "NULL";
-        var sql = $@"
-            WITH logical_references AS (
-                SELECT f.path, f.lang, r.container_kind, r.container_name, r.symbol_name,
-                       {preferredCalleeKindSql} AS reference_kind,
-                       r.reference_kind AS raw_reference_kind,
-                       {calleeGroupKindSql} AS count_reference_kind,
-                       COUNT(*) AS reference_count,
-                       {ReferenceWeightedScoreSql("r.reference_kind")} AS weighted_score,
-                       r.line,
-                       r.column_number,
-                       {referenceSpanLengthSql} AS span_length
-                FROM symbol_references r
-                JOIN files f ON r.file_id = f.id
-                WHERE r.container_name IS NOT NULL
-                  AND {GetCallableReferenceKindPredicateSql("r.reference_kind", referenceKind, "f.lang", includeMemberReads)}
-                  AND {BuildGraphSupportedLanguagePredicate(cmd, "f", "graphLang")}";
-        if (sourceSymbolId != null && _referenceColumns.Contains("source_symbol_id"))
-            sql += " AND r.source_symbol_id = @sourceSymbolId";
-        var allowSqlLeafFallback = AllowSqlLeafFallbackForQuery(query);
-        var allowQualifiedLeafFallback = HasSingleQualifiedSymbolDefinition(query, lang, pathPatterns, excludePathPatterns, excludeTests);
-        var useSqlQualifiedContainerMatch = SqlNameResolver.HasQualifier(query);
-        var cssScssVariableAlias = ComputeCssScssVariableAlias(query);
-        var cssScssVariableAliasScope = cssScssVariableAlias != null
-            ? " AND f.lang = 'css'"
-            : string.Empty;
-        if (exact && useSqlQualifiedContainerMatch && _foldReady)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: true);
-            sql += $" AND (((f.lang = 'sql') AND sql_segment_count(r.container_name) = @aliasQuerySegmentCount AND sql_normalize_name_folded(r.container_name) = @aliasQueryNormalizedFolded) OR ((f.lang != 'sql') AND {BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")}) OR {qualifiedLeafFallbackSql})";
-        }
-        else if (exact && useSqlQualifiedContainerMatch)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: false);
-            sql += $" AND (((f.lang = 'sql') AND sql_segment_count(r.container_name) = @aliasQuerySegmentCount AND sql_normalize_name(r.container_name) = @aliasQueryNormalized COLLATE NOCASE) OR ((f.lang != 'sql') AND r.container_name = @query COLLATE NOCASE) OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContainerMatch && _foldReady)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: true);
-            sql += $" AND (r.container_name LIKE @query ESCAPE '\\' OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContainerMatch)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: false);
-            sql += $" AND (r.container_name LIKE @query ESCAPE '\\' OR {qualifiedLeafFallbackSql})";
-        }
-        else if (exact && _foldReady)
-            sql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND ({BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")} OR (r.container_name_folded = @queryCssScssVariableAlias{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND sql_leaf_name_folded(r.container_name) = @aliasQueryLeafFolded))"
-                    : $" AND ({BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")} OR (f.lang = 'sql' AND sql_leaf_name_folded(r.container_name) = @aliasQueryLeafFolded))"
-                : $" AND {BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")}";
-        else if (exact)
-            sql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND (r.container_name = @query COLLATE NOCASE OR (r.container_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))"
-                    : " AND (r.container_name = @query COLLATE NOCASE OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))"
-                : " AND r.container_name = @query COLLATE NOCASE";
-        else
-            sql += cssScssVariableAlias != null
-                ? $" AND (r.container_name LIKE @query ESCAPE '\\' OR (r.container_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))"
-                : " AND (r.container_name LIKE @query ESCAPE '\\' OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))";
-        if (lang != null)
-            sql += " AND f.lang = @lang";
-        if (!includeQualifiedCommonCalls)
-            sql += BuildCSharpQualifiedCommonCallNoiseFilter("f", "r");
-        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
-        sql += $@"
-                GROUP BY f.path, f.lang, r.container_kind, r.container_name, r.symbol_name, r.file_id, r.line, r.column_number, {referenceSpanLengthSql}, r.reference_kind
-            ),
-            ranked_call_sites AS (
-                SELECT logical_references.*,
-                       ROW_NUMBER() OVER (
-                           PARTITION BY path, lang, container_kind, container_name, symbol_name, reference_kind
-                           ORDER BY CASE WHEN column_number IS NULL THEN 1 ELSE 0 END,
-                                    line,
-                                    column_number,
-                                    COALESCE(span_length, 0)
-                       ) AS location_rank
-                FROM logical_references
-            )
-            SELECT path, lang, container_kind, container_name, symbol_name,
-                   reference_kind,
-                   MAX(CASE WHEN location_rank = 1 THEN line END) AS first_line,
-                   MAX(CASE WHEN location_rank = 1 THEN column_number END) AS first_column,
-                   MAX(CASE WHEN location_rank = 1 THEN span_length END) AS first_length,
-                   SUM(r.reference_count) AS reference_count,
-                   GROUP_CONCAT(DISTINCT reference_kind) AS reference_kinds,
-                   GROUP_CONCAT(r.count_reference_kind || ':' || r.reference_count) AS reference_kind_counts,
-                   SUM(r.weighted_score) AS weighted_score
-            FROM ranked_call_sites r
-            GROUP BY path, lang, container_kind, container_name, symbol_name, reference_kind";
-        sql += $" ORDER BY {BuildReferenceRankOrderSql(rankMode, "r.container_name")} LIMIT @limit OFFSET @offset";
-
-        cmd.CommandText = sql;
-        string calleesQueryParam;
-        if (!exact)
-            calleesQueryParam = $"%{EscapeLikeQuery(query)}%";
-        else if (_foldReady)
-            calleesQueryParam = FoldNameForLanguage(query, lang);
-        else
-            calleesQueryParam = query;
-        if (exact && _foldReady)
-            AddPersistedFoldedNameQueryParameters(cmd, "@query", query, lang);
-        else
-            SqliteCommandPolicy.Add(cmd, "@query", calleesQueryParam);
-        SqliteCommandPolicy.Add(cmd, "@aliasQuery", query);
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryLeafFolded", NameFold.Fold(SqlNameResolver.GetLeafName(query)) ?? SqlNameResolver.GetLeafName(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryNormalized", SqlNameResolver.NormalizeQualifiedName(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryNormalizedFolded", NameFold.Fold(SqlNameResolver.NormalizeQualifiedName(query)) ?? SqlNameResolver.NormalizeQualifiedName(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQuerySegmentCount", SqlNameResolver.GetSegmentCount(query));
-        if (cssScssVariableAlias != null)
-        {
-            var aliasParam = exact && _foldReady
-                ? NameFold.Fold(cssScssVariableAlias) ?? cssScssVariableAlias
-                : cssScssVariableAlias;
-            SqliteCommandPolicy.Add(cmd, "@queryCssScssVariableAlias", aliasParam);
-        }
-        SqliteCommandPolicy.Add(cmd, "@rawQuery", query);
-        SqliteCommandPolicy.Add(cmd, "@rankingQuery", query.Trim());
-        AddQualifiedGraphQueryParameters(cmd, query, allowQualifiedLeafFallback);
-        if (RequiresReferenceKindParameter(referenceKind))
-            SqliteCommandPolicy.Add(cmd, "@referenceKind", referenceKind);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        if (sourceSymbolId != null && _referenceColumns.Contains("source_symbol_id"))
-            SqliteCommandPolicy.Add(cmd, "@sourceSymbolId", sourceSymbolId.Value);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        SqliteCommandPolicy.Add(cmd, "@limit", limit);
-        SqliteCommandPolicy.Add(cmd, "@offset", Math.Max(0, offset));
+        if (!_hasReferencesTable)
+            return new List<CalleeResult>();
 
-        var results = new List<CalleeResult>();
-        using var reader = cmd.ExecuteTrackedReader();
-        while (reader.TrackedRead())
-        {
-            var primaryKind = reader.GetString(5);
-            var kindAggregate = TruncateReferenceKindAggregate(GetNullableString(reader, 10), out var kindsTruncated);
-            var countAggregate = TruncateReferenceKindAggregate(GetNullableString(reader, 11), out var countsTruncated);
-            var kinds = ParseDistinctReferenceKinds(kindAggregate, primaryKind);
-            var counts = ParseReferenceKindCounts(countAggregate, primaryKind, reader.GetInt32(9));
-            results.Add(new CalleeResult
-            {
-                Path = reader.GetString(0),
-                Lang = GetNullableString(reader, 1),
-                CallerKind = GetNullableString(reader, 2),
-                CallerName = GetNullableString(reader, 3),
-                CalleeName = reader.GetString(4),
-                ReferenceKind = primaryKind,
-                ReferenceKinds = kinds,
-                HasMixedReferenceKinds = kinds.Count > 1,
-                ReferenceKindCounts = counts,
-                AggregateTruncated = kindsTruncated || countsTruncated,
-                ReferenceWeightScore = reader.GetDouble(12),
-                FirstLine = reader.GetInt32(6),
-                FirstColumn = GetNullableInt32(reader, 7),
-                FirstLength = GetNullableInt32(reader, 8),
-                ReferenceCount = reader.GetInt32(9),
-            });
-        }
-        return results;
+        var request = CreateGraphReferenceQueryRequest(
+            query,
+            limit,
+            lang,
+            referenceKind,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            exact,
+            rawKinds,
+            includeQualifiedCommonCalls,
+            includeMemberReads,
+            identitySymbolId: sourceSymbolId,
+            offset: offset);
+        var plan = BuildGraphReferenceQueryPlan(
+            CalleeGraphReferenceDirection,
+            request,
+            GraphReferenceQueryShape.List,
+            rankMode);
+        return ExecuteGraphReferenceList(plan, ProjectCalleeResult);
     }
 
     public int CountCallees(string query, int limit = 20, string? lang = null, string? referenceKind = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, bool exact = false, bool rawKinds = false, bool includeQualifiedCommonCalls = false, bool includeMemberReads = false)
@@ -775,103 +256,26 @@ public int CountCallees(string query, int limit = 20, string? lang = null, strin
             return 0;
         lang = NormalizeQueryLanguage(lang);
         query = NormalizeSymbolSearchQuery(query, lang, exact) ?? query ?? string.Empty;
-        if (!_hasReferencesTable) return 0;
-        using var cmd = _conn.CreateCommand();
-        var groupedSql = @"
-            SELECT path, lang, container_kind, container_name, symbol_name, reference_kind
-            FROM (
-                SELECT f.path AS path, f.lang AS lang, r.container_kind AS container_kind,
-                       r.container_name AS container_name, r.symbol_name AS symbol_name,
-                       " + (rawKinds ? GetPreferredReferenceKindSql("r.reference_kind") : GetPreferredLogicalReferenceKindSql("r.reference_kind")) + @" AS reference_kind
-            FROM symbol_references r
-            JOIN files f ON r.file_id = f.id
-            WHERE r.container_name IS NOT NULL";
-        groupedSql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "f", "graphLang")}";
-
-        groupedSql += $" AND {GetCallableReferenceKindPredicateSql("r.reference_kind", referenceKind, "f.lang", includeMemberReads)}";
-        var allowSqlLeafFallback = AllowSqlLeafFallbackForQuery(query);
-        var allowQualifiedLeafFallback = HasSingleQualifiedSymbolDefinition(query, lang, pathPatterns, excludePathPatterns, excludeTests);
-        var useSqlQualifiedContainerMatch = SqlNameResolver.HasQualifier(query);
-        var cssScssVariableAlias = ComputeCssScssVariableAlias(query);
-        var cssScssVariableAliasScope = cssScssVariableAlias != null
-            ? " AND f.lang = 'css'"
-            : string.Empty;
-        if (exact && useSqlQualifiedContainerMatch && _foldReady)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: true);
-            groupedSql += $" AND (((f.lang = 'sql') AND sql_segment_count(r.container_name) = @aliasQuerySegmentCount AND sql_normalize_name_folded(r.container_name) = @aliasQueryNormalizedFolded) OR ((f.lang != 'sql') AND {BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")}) OR {qualifiedLeafFallbackSql})";
-        }
-        else if (exact && useSqlQualifiedContainerMatch)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: false);
-            groupedSql += $" AND (((f.lang = 'sql') AND sql_segment_count(r.container_name) = @aliasQuerySegmentCount AND sql_normalize_name(r.container_name) = @aliasQueryNormalized COLLATE NOCASE) OR ((f.lang != 'sql') AND r.container_name = @query COLLATE NOCASE) OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContainerMatch && _foldReady)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: true);
-            groupedSql += $" AND (r.container_name LIKE @query ESCAPE '\\' OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContainerMatch)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: false);
-            groupedSql += $" AND (r.container_name LIKE @query ESCAPE '\\' OR {qualifiedLeafFallbackSql})";
-        }
-        else if (exact && _foldReady)
-            groupedSql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND ({BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")} OR (r.container_name_folded = @queryCssScssVariableAlias{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND sql_leaf_name_folded(r.container_name) = @aliasQueryLeafFolded))"
-                    : $" AND ({BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")} OR (f.lang = 'sql' AND sql_leaf_name_folded(r.container_name) = @aliasQueryLeafFolded))"
-                : $" AND {BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")}";
-        else if (exact)
-            groupedSql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND (r.container_name = @query COLLATE NOCASE OR (r.container_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))"
-                    : " AND (r.container_name = @query COLLATE NOCASE OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))"
-                : " AND r.container_name = @query COLLATE NOCASE";
-        else
-            groupedSql += cssScssVariableAlias != null
-                ? $" AND (r.container_name LIKE @query ESCAPE '\\' OR (r.container_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))"
-                : " AND (r.container_name LIKE @query ESCAPE '\\' OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))";
-        if (lang != null)
-            groupedSql += " AND f.lang = @lang";
-        if (!includeQualifiedCommonCalls)
-            groupedSql += BuildCSharpQualifiedCommonCallNoiseFilter("f", "r");
-        AppendPathFilters(ref groupedSql, pathPatterns, excludePathPatterns, excludeTests);
-        groupedSql += $" GROUP BY f.path, f.lang, r.container_kind, r.container_name, r.symbol_name, r.file_id, r.line, r.column_number, {(rawKinds ? GetRawReferenceKindSql("r.reference_kind") : GetLogicalReferenceKindSql("r.reference_kind"))}";
-        groupedSql += " ) grouped_call_sites GROUP BY path, lang, container_kind, container_name, symbol_name, reference_kind LIMIT @limit";
-
-        cmd.CommandText = $"SELECT COUNT(*) FROM ({groupedSql})";
-        var value = !exact
-            ? $"%{EscapeLikeQuery(query)}%"
-            : _foldReady
-                ? FoldNameForLanguage(query, lang)
-                : query;
-        if (exact && _foldReady)
-            AddPersistedFoldedNameQueryParameters(cmd, "@query", query, lang);
-        else
-            SqliteCommandPolicy.Add(cmd, "@query", value);
-        SqliteCommandPolicy.Add(cmd, "@aliasQuery", query);
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryLeafFolded", NameFold.Fold(SqlNameResolver.GetLeafName(query)) ?? SqlNameResolver.GetLeafName(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryNormalized", SqlNameResolver.NormalizeQualifiedName(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryNormalizedFolded", NameFold.Fold(SqlNameResolver.NormalizeQualifiedName(query)) ?? SqlNameResolver.NormalizeQualifiedName(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQuerySegmentCount", SqlNameResolver.GetSegmentCount(query));
-        AddQualifiedGraphQueryParameters(cmd, query, allowQualifiedLeafFallback);
-        if (cssScssVariableAlias != null)
-        {
-            var aliasParam = exact && _foldReady
-                ? NameFold.Fold(cssScssVariableAlias) ?? cssScssVariableAlias
-                : cssScssVariableAlias;
-            SqliteCommandPolicy.Add(cmd, "@queryCssScssVariableAlias", aliasParam);
-        }
-        if (RequiresReferenceKindParameter(referenceKind))
-            SqliteCommandPolicy.Add(cmd, "@referenceKind", referenceKind);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        SqliteCommandPolicy.Add(cmd, "@limit", limit);
+        if (!_hasReferencesTable)
+            return 0;
 
-        var raw = cmd.ExecuteScalar();
-        return raw is long l ? (int)l : Convert.ToInt32(raw);
+        var request = CreateGraphReferenceQueryRequest(
+            query,
+            limit,
+            lang,
+            referenceKind,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            exact,
+            rawKinds,
+            includeQualifiedCommonCalls,
+            includeMemberReads);
+        var plan = BuildGraphReferenceQueryPlan(
+            CalleeGraphReferenceDirection,
+            request,
+            GraphReferenceQueryShape.LimitedCount);
+        return ExecuteGraphReferenceLimitedCount(plan);
     }
 
     public QueryCountResult CountCalleesTotal(string query, string? lang = null, string? referenceKind = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, bool exact = false, bool rawKinds = false, bool includeQualifiedCommonCalls = false, bool includeMemberReads = false)
@@ -905,168 +309,24 @@ private QueryCountResult CountCalleesTotalCore(
         if (!_hasReferencesTable)
             return new QueryCountResult(0, 0);
 
-        using var cmd = _conn.CreateCommand();
-        var groupedSql = @"
-            SELECT path, lang
-            FROM (
-                SELECT f.path AS path, f.lang AS lang, r.container_kind AS container_kind,
-                       r.container_name AS container_name, r.symbol_name AS symbol_name,
-                       " + (rawKinds ? GetPreferredReferenceKindSql("r.reference_kind") : GetPreferredLogicalReferenceKindSql("r.reference_kind")) + @" AS reference_kind
-                FROM symbol_references r
-                JOIN files f ON r.file_id = f.id
-                WHERE r.container_name IS NOT NULL";
-        groupedSql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "f", "graphLang")}";
-
-        groupedSql += $" AND {GetCallableReferenceKindPredicateSql("r.reference_kind", referenceKind, "f.lang", includeMemberReads)}";
-        if (sourceSymbolId != null && _referenceColumns.Contains("source_symbol_id"))
-            groupedSql += " AND r.source_symbol_id = @sourceSymbolId";
-        var allowSqlLeafFallback = AllowSqlLeafFallbackForQuery(query);
-        var allowQualifiedLeafFallback = HasSingleQualifiedSymbolDefinition(query, lang, pathPatterns, excludePathPatterns, excludeTests);
-        var useSqlQualifiedContainerMatch = SqlNameResolver.HasQualifier(query);
-        var cssScssVariableAlias = ComputeCssScssVariableAlias(query);
-        var cssScssVariableAliasScope = cssScssVariableAlias != null
-            ? " AND f.lang = 'css'"
-            : string.Empty;
-        if (exact && useSqlQualifiedContainerMatch && _foldReady)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: true);
-            groupedSql += $" AND (((f.lang = 'sql') AND sql_segment_count(r.container_name) = @aliasQuerySegmentCount AND sql_normalize_name_folded(r.container_name) = @aliasQueryNormalizedFolded) OR ((f.lang != 'sql') AND {BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")}) OR {qualifiedLeafFallbackSql})";
-        }
-        else if (exact && useSqlQualifiedContainerMatch)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: false);
-            groupedSql += $" AND (((f.lang = 'sql') AND sql_segment_count(r.container_name) = @aliasQuerySegmentCount AND sql_normalize_name(r.container_name) = @aliasQueryNormalized COLLATE NOCASE) OR ((f.lang != 'sql') AND r.container_name = @query COLLATE NOCASE) OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContainerMatch && _foldReady)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: true);
-            groupedSql += $" AND (r.container_name LIKE @query ESCAPE '\\' OR {qualifiedLeafFallbackSql})";
-        }
-        else if (useSqlQualifiedContainerMatch)
-        {
-            var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.container_name", "r.container_name_folded", folded: false);
-            groupedSql += $" AND (r.container_name LIKE @query ESCAPE '\\' OR {qualifiedLeafFallbackSql})";
-        }
-        else if (exact && _foldReady)
-            groupedSql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND ({BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")} OR (r.container_name_folded = @queryCssScssVariableAlias{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND sql_leaf_name_folded(r.container_name) = @aliasQueryLeafFolded))"
-                    : $" AND ({BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")} OR (f.lang = 'sql' AND sql_leaf_name_folded(r.container_name) = @aliasQueryLeafFolded))"
-                : $" AND {BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")}";
-        else if (exact)
-            groupedSql += allowSqlLeafFallback
-                ? cssScssVariableAlias != null
-                    ? $" AND (r.container_name = @query COLLATE NOCASE OR (r.container_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))"
-                    : " AND (r.container_name = @query COLLATE NOCASE OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))"
-                : " AND r.container_name = @query COLLATE NOCASE";
-        else
-            groupedSql += cssScssVariableAlias != null
-                ? $" AND (r.container_name LIKE @query ESCAPE '\\' OR (r.container_name = @queryCssScssVariableAlias COLLATE NOCASE{cssScssVariableAliasScope}) OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))"
-                : " AND (r.container_name LIKE @query ESCAPE '\\' OR (f.lang = 'sql' AND sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE))";
-        if (lang != null)
-            groupedSql += " AND f.lang = @lang";
-        if (!includeQualifiedCommonCalls)
-            groupedSql += BuildCSharpQualifiedCommonCallNoiseFilter("f", "r");
-        AppendPathFilters(ref groupedSql, pathPatterns, excludePathPatterns, excludeTests);
-        groupedSql += $" GROUP BY f.path, f.lang, r.container_kind, r.container_name, r.symbol_name, r.file_id, r.line, r.column_number, {(rawKinds ? GetRawReferenceKindSql("r.reference_kind") : GetLogicalReferenceKindSql("r.reference_kind"))}";
-        groupedSql += " ) grouped_call_sites GROUP BY path, lang, container_kind, container_name, symbol_name, reference_kind";
-
-        cmd.CommandText = $"SELECT COUNT(*), COUNT(DISTINCT path), MAX(CASE WHEN lang = 'sql' THEN 1 ELSE 0 END) FROM ({groupedSql})";
-        var value = !exact
-            ? $"%{EscapeLikeQuery(query)}%"
-            : _foldReady
-                ? FoldNameForLanguage(query, lang)
-                : query;
-        if (exact && _foldReady)
-            AddPersistedFoldedNameQueryParameters(cmd, "@query", query, lang);
-        else
-            SqliteCommandPolicy.Add(cmd, "@query", value);
-        SqliteCommandPolicy.Add(cmd, "@aliasQuery", query);
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryLeafFolded", NameFold.Fold(SqlNameResolver.GetLeafName(query)) ?? SqlNameResolver.GetLeafName(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryNormalized", SqlNameResolver.NormalizeQualifiedName(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryNormalizedFolded", NameFold.Fold(SqlNameResolver.NormalizeQualifiedName(query)) ?? SqlNameResolver.NormalizeQualifiedName(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQuerySegmentCount", SqlNameResolver.GetSegmentCount(query));
-        AddQualifiedGraphQueryParameters(cmd, query, allowQualifiedLeafFallback);
-        if (cssScssVariableAlias != null)
-        {
-            var aliasParam = exact && _foldReady
-                ? NameFold.Fold(cssScssVariableAlias) ?? cssScssVariableAlias
-                : cssScssVariableAlias;
-            SqliteCommandPolicy.Add(cmd, "@queryCssScssVariableAlias", aliasParam);
-        }
-        if (RequiresReferenceKindParameter(referenceKind))
-            SqliteCommandPolicy.Add(cmd, "@referenceKind", referenceKind);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        if (sourceSymbolId != null)
-            SqliteCommandPolicy.Add(cmd, "@sourceSymbolId", sourceSymbolId.Value);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-
-        return ExecuteCountSummary(cmd);
-    }
-
-    private static string ReferenceWeightedScoreSql(string columnSql) => $@"
-        SUM(CASE {columnSql}
-            WHEN 'instantiate' THEN 3.0
-            WHEN 'generic_type_argument' THEN 0.5
-            WHEN 'call' THEN 1.0
-            WHEN 'subscribe' THEN 0.1
-            WHEN 'unsubscribe' THEN 0.1
-            WHEN 'razor_event_binding' THEN 0.1
-            ELSE 0.0
-        END)";
-
-    private static string BuildReferenceRankOrderSql(
-        ReferenceRankMode rankMode,
-        string queriedNameSql)
-        => string.Join(
-            ", ",
-            ReferenceRankRecipes.Get(rankMode).Select(dimension => dimension switch
-            {
-                ReferenceRankDimension.ReferenceWeightScoreDescending => "weighted_score DESC",
-                ReferenceRankDimension.ReferenceCountDescending => "reference_count DESC",
-                ReferenceRankDimension.ReferenceKindPriorityAscending =>
-                    "CASE reference_kind WHEN 'instantiate' THEN 0 WHEN 'call' THEN 1 WHEN 'generic_type_argument' THEN 2 WHEN 'subscribe' THEN 3 ELSE 4 END",
-                ReferenceRankDimension.ExactCaseMatchDescending =>
-                    $"CASE WHEN {queriedNameSql} = @rawQuery THEN 0 ELSE 1 END",
-                ReferenceRankDimension.ExactNameMatchDescending =>
-                    $"CASE WHEN lower({queriedNameSql}) = lower(@rankingQuery) THEN 0 ELSE 1 END",
-                ReferenceRankDimension.PathCategoryAscending => GetPathBucketOrderSql("r.path"),
-                ReferenceRankDimension.PathAscending => "r.path",
-                ReferenceRankDimension.FirstLineAscending => "first_line",
-                ReferenceRankDimension.FirstColumnAscending => "first_column",
-                ReferenceRankDimension.LanguageAscending => "r.lang",
-                ReferenceRankDimension.ContainerKindAscending => "r.container_kind",
-                ReferenceRankDimension.ContainerNameAscending => "r.container_name",
-                ReferenceRankDimension.SymbolNameAscending => "r.symbol_name",
-                ReferenceRankDimension.ReferenceKindAscending => "reference_kind",
-                _ => throw new ArgumentOutOfRangeException(nameof(dimension), dimension, null),
-            }));
-
-    private static IReadOnlyDictionary<string, int> ParseReferenceKindCounts(string? aggregate, string primaryKind, int fallbackCount)
-    {
-        var counts = new Dictionary<string, int>(StringComparer.Ordinal);
-        counts["call"] = 0;
-        counts["instantiate"] = 0;
-        counts["subscribe"] = 0;
-        if (!string.IsNullOrWhiteSpace(aggregate))
-        {
-            foreach (var entry in aggregate.Split(','))
-            {
-                var separator = entry.LastIndexOf(':');
-                if (separator <= 0 || separator == entry.Length - 1)
-                    continue;
-                var kind = entry[..separator].Trim();
-                if (kind.Length == 0 || !int.TryParse(entry[(separator + 1)..], out var count))
-                    continue;
-                counts[kind] = counts.TryGetValue(kind, out var existing)
-                    ? existing + count
-                    : count;
-            }
-        }
-        if (counts.Count == 0 && !string.IsNullOrEmpty(primaryKind))
-            counts[primaryKind] = fallbackCount;
-        return counts;
+        var request = CreateGraphReferenceQueryRequest(
+            query,
+            limit: 0,
+            lang,
+            referenceKind,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            exact,
+            rawKinds,
+            includeQualifiedCommonCalls,
+            includeMemberReads,
+            identitySymbolId: sourceSymbolId);
+        var plan = BuildGraphReferenceQueryPlan(
+            CalleeGraphReferenceDirection,
+            request,
+            GraphReferenceQueryShape.TotalCount);
+        return ExecuteGraphReferenceTotalCount(plan);
     }
 
     /// <summary>
diff --git a/src/CodeIndex/Database/DbReader.GraphReferenceQueries.cs b/src/CodeIndex/Database/DbReader.GraphReferenceQueries.cs
new file mode 100644
index 000000000..a9de38190
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.GraphReferenceQueries.cs
@@ -0,0 +1,659 @@
+using CodeIndex.Indexer;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private enum GraphReferenceQueryShape
+    {
+        List,
+        LimitedCount,
+        TotalCount,
+    }
+
+    private sealed record GraphReferenceQueryRequest(
+        string Query,
+        int Limit,
+        string? Lang,
+        string? ReferenceKind,
+        IReadOnlyList<string>? PathPatterns,
+        IReadOnlyList<string>? ExcludePathPatterns,
+        bool ExcludeTests,
+        bool Exact,
+        bool RawKinds,
+        bool IncludeQualifiedCommonCalls,
+        bool IncludeMemberReads,
+        long? IdentitySymbolId,
+        bool ExcludeSelfReferences,
+        int Offset);
+
+    private sealed record GraphReferenceMatchPlan(
+        bool AllowSqlLeafFallback,
+        bool AllowQualifiedLeafFallback,
+        bool AllowCSharpQualifiedContextMatch,
+        bool UsesQualifiedName,
+        string? CssScssVariableAlias);
+
+    private sealed record GraphReferenceBuildContext(
+        string SupportedLanguagePredicateSql,
+        string IdentityFilterSql,
+        GraphReferenceMatchPlan Match);
+
+    private sealed record GraphReferenceRowLayout(
+        int FirstLineOrdinal,
+        int FirstColumnOrdinal,
+        bool FirstColumnIsNullable,
+        int? FirstLengthOrdinal,
+        int ReferenceCountOrdinal,
+        int ReferenceKindsOrdinal,
+        int ReferenceKindCountsOrdinal,
+        int ReferenceWeightOrdinal,
+        int? SelfReferenceOrdinal,
+        int? MutualRecursionOrdinal);
+
+    private sealed record GraphReferenceDirectionSpec(
+        string MatchColumnSql,
+        string FoldedMatchColumnSql,
+        string SqlLeafExactMatchSql,
+        string SqlLeafFoldedMatchSql,
+        string RankQueriedNameSql,
+        bool UsesCSharpQualifiedContext,
+        bool CountGroupsByReferenceKind,
+        bool NormalizeBoundLanguage,
+        string IdentityParameterName,
+        GraphReferenceRowLayout RowLayout,
+        Func<DbReader, string> BuildReferenceJoinSql,
+        Func<DbReader, string> BuildSourcePredicateSql,
+        Func<DbReader, GraphReferenceQueryRequest, string> BuildIdentityFilterSql,
+        Func<DbReader, GraphReferenceQueryRequest, string> BuildPreNameFilterSql,
+        Func<DbReader, GraphReferenceQueryRequest, string> BuildPostNameFilterSql,
+        Func<DbReader, GraphReferenceQueryRequest, GraphReferenceMatchPlan, string> BuildQualifiedNameFilterSql,
+        Func<DbReader, GraphReferenceQueryRequest, GraphReferenceBuildContext, string> BuildListSql,
+        Action<DbReader, SqliteCommand, GraphReferenceQueryPlan> BindMatchParameters);
+
+    private sealed record GraphReferenceQueryPlan(
+        string Sql,
+        GraphReferenceQueryShape Shape,
+        GraphReferenceDirectionSpec Direction,
+        GraphReferenceQueryRequest Request,
+        GraphReferenceMatchPlan Match,
+        IReadOnlyList<string> SupportedLanguages,
+        bool BindIdentityParameter);
+
+    private sealed record GraphReferenceRow(
+        string Path,
+        string? Lang,
+        string? CallerKind,
+        string? CallerName,
+        string CalleeName,
+        string ReferenceKind,
+        IReadOnlyList<string> ReferenceKinds,
+        IReadOnlyDictionary<string, int> ReferenceKindCounts,
+        bool AggregateTruncated,
+        double ReferenceWeightScore,
+        int FirstLine,
+        int? FirstColumn,
+        int? FirstLength,
+        int ReferenceCount,
+        bool HasSelfReference,
+        bool HasMutualRecursion);
+
+    private static readonly GraphReferenceDirectionSpec CallerGraphReferenceDirection = new(
+        MatchColumnSql: "r.symbol_name",
+        FoldedMatchColumnSql: "r.symbol_name_folded",
+        SqlLeafExactMatchSql: "r.symbol_name = sql_leaf_name(@aliasQuery) COLLATE NOCASE",
+        SqlLeafFoldedMatchSql: "r.symbol_name_folded = @aliasQueryLeafFolded",
+        RankQueriedNameSql: "r.symbol_name",
+        UsesCSharpQualifiedContext: true,
+        CountGroupsByReferenceKind: false,
+        NormalizeBoundLanguage: true,
+        IdentityParameterName: "@targetSymbolId",
+        RowLayout: new GraphReferenceRowLayout(6, 7, false, null, 8, 9, 10, 11, 12, 13),
+        BuildReferenceJoinSql: static reader => reader.ReferenceLineJoinSql("r"),
+        BuildSourcePredicateSql: static _ => BuildCallerContainerPredicate("f", "r"),
+        BuildIdentityFilterSql: static (reader, request) => reader.BuildCallerIdentityFilterSql(request),
+        BuildPreNameFilterSql: static (reader, request) => reader.BuildCallerPreNameFilterSql(request),
+        BuildPostNameFilterSql: static (reader, request) => reader.BuildCallerPostNameFilterSql(request),
+        BuildQualifiedNameFilterSql: static (reader, request, _) => reader.BuildCallerQualifiedNameFilterSql(request),
+        BuildListSql: static (reader, request, context) => reader.BuildCallerListSql(request, context),
+        BindMatchParameters: static (reader, command, plan) => reader.BindCallerMatchParameters(command, plan));
+
+    private static readonly GraphReferenceDirectionSpec CalleeGraphReferenceDirection = new(
+        MatchColumnSql: "r.container_name",
+        FoldedMatchColumnSql: "r.container_name_folded",
+        SqlLeafExactMatchSql: "sql_leaf_name(r.container_name) = @aliasQuery COLLATE NOCASE",
+        SqlLeafFoldedMatchSql: "sql_leaf_name_folded(r.container_name) = @aliasQueryLeafFolded",
+        RankQueriedNameSql: "r.container_name",
+        UsesCSharpQualifiedContext: false,
+        CountGroupsByReferenceKind: true,
+        NormalizeBoundLanguage: false,
+        IdentityParameterName: "@sourceSymbolId",
+        RowLayout: new GraphReferenceRowLayout(6, 7, true, 8, 9, 10, 11, 12, null, null),
+        BuildReferenceJoinSql: static _ => string.Empty,
+        BuildSourcePredicateSql: static _ => "r.container_name IS NOT NULL",
+        BuildIdentityFilterSql: static (reader, request) => reader.BuildCalleeIdentityFilterSql(request),
+        BuildPreNameFilterSql: static (_, _) => string.Empty,
+        BuildPostNameFilterSql: static (reader, request) => reader.BuildCalleePostNameFilterSql(request),
+        BuildQualifiedNameFilterSql: static (reader, request, _) => reader.BuildCalleeQualifiedNameFilterSql(request),
+        BuildListSql: static (reader, request, context) => reader.BuildCalleeListSql(request, context),
+        BindMatchParameters: static (reader, command, plan) => reader.BindCalleeMatchParameters(command, plan));
+
+    private static GraphReferenceQueryRequest CreateGraphReferenceQueryRequest(
+        string query,
+        int limit,
+        string? lang,
+        string? referenceKind,
+        IReadOnlyList<string>? pathPatterns,
+        IReadOnlyList<string>? excludePathPatterns,
+        bool excludeTests,
+        bool exact,
+        bool rawKinds,
+        bool includeQualifiedCommonCalls,
+        bool includeMemberReads,
+        long? identitySymbolId = null,
+        bool excludeSelfReferences = false,
+        int offset = 0)
+        => new(
+            query,
+            limit,
+            lang,
+            referenceKind,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            exact,
+            rawKinds,
+            includeQualifiedCommonCalls,
+            includeMemberReads,
+            identitySymbolId,
+            excludeSelfReferences,
+            offset);
+
+    private GraphReferenceQueryPlan BuildGraphReferenceQueryPlan(
+        GraphReferenceDirectionSpec direction,
+        GraphReferenceQueryRequest request,
+        GraphReferenceQueryShape shape,
+        ReferenceRankMode rankMode = ReferenceRankMode.Weighted)
+    {
+        var supportedLanguages = GetWorkspaceSupportedReferenceLanguages()
+            .OrderBy(static language => language, StringComparer.Ordinal)
+            .ToList()
+            .AsReadOnly();
+        var supportedLanguagePredicateSql = BuildGraphSupportedLanguagePredicateSql(
+            supportedLanguages,
+            "f",
+            "graphLang");
+        var match = BuildGraphReferenceMatchPlan(direction, request);
+        var identityFilterSql = direction.BuildIdentityFilterSql(this, request);
+        var context = new GraphReferenceBuildContext(
+            supportedLanguagePredicateSql,
+            identityFilterSql,
+            match);
+        var sql = shape switch
+        {
+            GraphReferenceQueryShape.List => direction.BuildListSql(this, request, context),
+            GraphReferenceQueryShape.LimitedCount => BuildGraphReferenceCountSql(direction, request, context, limited: true),
+            GraphReferenceQueryShape.TotalCount => BuildGraphReferenceCountSql(direction, request, context, limited: false),
+            _ => throw new ArgumentOutOfRangeException(nameof(shape), shape, null),
+        };
+        if (shape == GraphReferenceQueryShape.List)
+            sql += $" ORDER BY {BuildReferenceRankOrderSql(rankMode, direction.RankQueriedNameSql)} LIMIT @limit OFFSET @offset";
+
+        return new GraphReferenceQueryPlan(
+            sql,
+            shape,
+            direction,
+            request,
+            match,
+            supportedLanguages,
+            BindIdentityParameter: identityFilterSql.Length > 0);
+    }
+
+    private GraphReferenceMatchPlan BuildGraphReferenceMatchPlan(
+        GraphReferenceDirectionSpec direction,
+        GraphReferenceQueryRequest request)
+    {
+        var usesQualifiedName = SqlNameResolver.HasQualifier(request.Query);
+        var allowCSharpQualifiedContextMatch = direction.UsesCSharpQualifiedContext
+            && usesQualifiedName
+            && !HasQualifiedSymbolDefinition(
+                request.Query,
+                request.Lang,
+                request.PathPatterns,
+                request.ExcludePathPatterns,
+                request.ExcludeTests);
+
+        return new GraphReferenceMatchPlan(
+            AllowSqlLeafFallbackForQuery(request.Query),
+            HasSingleQualifiedSymbolDefinition(
+                request.Query,
+                request.Lang,
+                request.PathPatterns,
+                request.ExcludePathPatterns,
+                request.ExcludeTests),
+            allowCSharpQualifiedContextMatch,
+            usesQualifiedName,
+            ComputeCssScssVariableAlias(request.Query));
+    }
+
+    private static string BuildGraphSupportedLanguagePredicateSql(
+        IReadOnlyList<string> supportedLanguages,
+        string fileAlias,
+        string parameterPrefix)
+    {
+        if (supportedLanguages.Count == 0)
+            return "1 = 0";
+
+        var parameterNames = Enumerable.Range(0, supportedLanguages.Count)
+            .Select(index => $"@{parameterPrefix}{index}");
+        return $"{fileAlias}.lang IN ({string.Join(", ", parameterNames)})";
+    }
+
+    private string BuildGraphReferenceCountSql(
+        GraphReferenceDirectionSpec direction,
+        GraphReferenceQueryRequest request,
+        GraphReferenceBuildContext context,
+        bool limited)
+    {
+        var outerReferenceKindColumn = direction.CountGroupsByReferenceKind
+            ? ", reference_kind"
+            : string.Empty;
+        var innerReferenceKindColumn = direction.CountGroupsByReferenceKind
+            ? ",\n                       " + (request.RawKinds
+                ? GetPreferredReferenceKindSql("r.reference_kind")
+                : GetPreferredLogicalReferenceKindSql("r.reference_kind")) + " AS reference_kind"
+            : string.Empty;
+        var sql = @"
+            SELECT path, lang, container_kind, container_name, symbol_name" + outerReferenceKindColumn + @"
+            FROM (
+                SELECT f.path AS path, f.lang AS lang, r.container_kind AS container_kind,
+                       r.container_name AS container_name, r.symbol_name AS symbol_name" + innerReferenceKindColumn + @"
+            FROM symbol_references r
+            JOIN files f ON r.file_id = f.id" + direction.BuildReferenceJoinSql(this) + @"
+            WHERE " + direction.BuildSourcePredicateSql(this);
+        sql += $" AND {context.SupportedLanguagePredicateSql}";
+
+        sql += $" AND {GetCallableReferenceKindPredicateSql("r.reference_kind", request.ReferenceKind, "f.lang", request.IncludeMemberReads)}";
+        AppendGraphReferenceTailFilters(ref sql, direction, request, context);
+        sql += $" GROUP BY f.path, f.lang, r.container_kind, r.container_name, r.symbol_name, r.file_id, r.line, r.column_number, {(request.RawKinds ? GetRawReferenceKindSql("r.reference_kind") : GetLogicalReferenceKindSql("r.reference_kind"))}";
+        sql += " ) grouped_call_sites GROUP BY path, lang, container_kind, container_name, symbol_name" + outerReferenceKindColumn;
+        if (limited)
+            sql += " LIMIT @limit";
+
+        return limited
+            ? $"SELECT COUNT(*) FROM ({sql})"
+            : $"SELECT COUNT(*), COUNT(DISTINCT path), MAX(CASE WHEN lang = 'sql' THEN 1 ELSE 0 END) FROM ({sql})";
+    }
+
+    private string BuildCallerListSql(
+        GraphReferenceQueryRequest request,
+        GraphReferenceBuildContext context)
+    {
+        var groupedReferenceKindSql = request.RawKinds
+            ? GetGroupedCallerReferenceKindSql("r.reference_kind")
+            : GetGroupedCallerLogicalReferenceKindSql("r.reference_kind");
+        var groupedReferenceKindGroupSql = request.RawKinds
+            ? GetRawReferenceKindSql("r.reference_kind")
+            : GetLogicalReferenceKindSql("r.reference_kind");
+        var selfReferenceSql = _referenceColumns.Contains("is_self_reference") ? "r.is_self_reference" : "0";
+        var mutualRecursionSql = _referenceColumns.Contains("is_mutual_recursion") ? "r.is_mutual_recursion" : "0";
+        var sql = @"
+            WITH logical_references AS (
+                SELECT f.path, f.lang, r.container_kind, r.container_name, r.symbol_name,
+                       " + groupedReferenceKindSql + @" AS reference_kind,
+                       r.reference_kind AS raw_reference_kind,
+                       " + groupedReferenceKindGroupSql + @" AS count_reference_kind,
+                       COUNT(*) AS reference_count,
+                       " + ReferenceWeightedScoreSql("r.reference_kind") + @" AS weighted_score,
+                       (CAST(r.line AS INTEGER) * 4294967296 + r.column_number) AS location_key,
+                       MAX(" + selfReferenceSql + @") AS is_self_reference,
+                       MAX(" + mutualRecursionSql + @") AS is_mutual_recursion
+                FROM symbol_references r
+                JOIN files f ON r.file_id = f.id" + ReferenceLineJoinSql("r") + @"
+                WHERE " + BuildCallerContainerPredicate("f", "r") + @"
+                  AND " + GetCallableReferenceKindPredicateSql("r.reference_kind", request.ReferenceKind, "f.lang", request.IncludeMemberReads) + @"
+                  AND " + context.SupportedLanguagePredicateSql;
+        AppendGraphReferenceTailFilters(ref sql, CallerGraphReferenceDirection, request, context);
+        sql += @"
+            GROUP BY f.path, f.lang, r.container_kind, r.container_name, r.symbol_name, r.file_id, r.line, r.column_number, " + groupedReferenceKindGroupSql + @", r.reference_kind
+            )
+            SELECT path, lang, " + BuildCallerKindProjectionSql("r") + @" AS container_kind, " + BuildCallerNameProjectionSql("r") + @" AS container_name, symbol_name,
+                   " + (request.RawKinds ? GetGroupedCallerReferenceKindSql("r.reference_kind") : GetPreferredLogicalReferenceKindSql("r.reference_kind")) + @" AS reference_kind,
+                   (MIN(location_key) / 4294967296) AS first_line,
+                   (MIN(location_key) % 4294967296) AS first_column,
+                   SUM(r.reference_count) AS reference_count,
+                   GROUP_CONCAT(DISTINCT r.reference_kind) AS reference_kinds,
+                   GROUP_CONCAT(r.count_reference_kind || ':' || r.reference_count) AS reference_kind_counts,
+                   SUM(r.weighted_score) AS weighted_score,
+                   MAX(r.is_self_reference) AS is_self_reference,
+                   MAX(r.is_mutual_recursion) AS is_mutual_recursion
+            FROM logical_references r
+            GROUP BY path, lang, container_kind, container_name, symbol_name";
+        return sql;
+    }
+
+    private string BuildCalleeListSql(
+        GraphReferenceQueryRequest request,
+        GraphReferenceBuildContext context)
+    {
+        var preferredCalleeKindSql = request.RawKinds
+            ? GetPreferredReferenceKindSql("r.reference_kind")
+            : GetPreferredLogicalReferenceKindSql("r.reference_kind");
+        var calleeGroupKindSql = request.RawKinds
+            ? GetRawReferenceKindSql("r.reference_kind")
+            : GetLogicalReferenceKindSql("r.reference_kind");
+        var referenceSpanLengthSql = _referenceColumns.Contains("span_length")
+            ? "r.span_length"
+            : "NULL";
+        var sql = $@"
+            WITH logical_references AS (
+                SELECT f.path, f.lang, r.container_kind, r.container_name, r.symbol_name,
+                       {preferredCalleeKindSql} AS reference_kind,
+                       r.reference_kind AS raw_reference_kind,
+                       {calleeGroupKindSql} AS count_reference_kind,
+                       COUNT(*) AS reference_count,
+                       {ReferenceWeightedScoreSql("r.reference_kind")} AS weighted_score,
+                       r.line,
+                       r.column_number,
+                       {referenceSpanLengthSql} AS span_length
+                FROM symbol_references r
+                JOIN files f ON r.file_id = f.id
+                WHERE r.container_name IS NOT NULL
+                  AND {GetCallableReferenceKindPredicateSql("r.reference_kind", request.ReferenceKind, "f.lang", request.IncludeMemberReads)}
+                  AND {context.SupportedLanguagePredicateSql}";
+        AppendGraphReferenceTailFilters(ref sql, CalleeGraphReferenceDirection, request, context);
+        sql += $@"
+                GROUP BY f.path, f.lang, r.container_kind, r.container_name, r.symbol_name, r.file_id, r.line, r.column_number, {referenceSpanLengthSql}, r.reference_kind
+            ),
+            ranked_call_sites AS (
+                SELECT logical_references.*,
+                       ROW_NUMBER() OVER (
+                           PARTITION BY path, lang, container_kind, container_name, symbol_name, reference_kind
+                           ORDER BY CASE WHEN column_number IS NULL THEN 1 ELSE 0 END,
+                                    line,
+                                    column_number,
+                                    COALESCE(span_length, 0)
+                       ) AS location_rank
+                FROM logical_references
+            )
+            SELECT path, lang, container_kind, container_name, symbol_name,
+                   reference_kind,
+                   MAX(CASE WHEN location_rank = 1 THEN line END) AS first_line,
+                   MAX(CASE WHEN location_rank = 1 THEN column_number END) AS first_column,
+                   MAX(CASE WHEN location_rank = 1 THEN span_length END) AS first_length,
+                   SUM(r.reference_count) AS reference_count,
+                   GROUP_CONCAT(DISTINCT reference_kind) AS reference_kinds,
+                   GROUP_CONCAT(r.count_reference_kind || ':' || r.reference_count) AS reference_kind_counts,
+                   SUM(r.weighted_score) AS weighted_score
+            FROM ranked_call_sites r
+            GROUP BY path, lang, container_kind, container_name, symbol_name, reference_kind";
+        return sql;
+    }
+
+    private void AppendGraphReferenceTailFilters(
+        ref string sql,
+        GraphReferenceDirectionSpec direction,
+        GraphReferenceQueryRequest request,
+        GraphReferenceBuildContext context)
+    {
+        sql += context.IdentityFilterSql;
+        sql += direction.BuildPreNameFilterSql(this, request);
+        sql += BuildGraphReferenceNameFilterSql(direction, request, context.Match);
+        sql += direction.BuildPostNameFilterSql(this, request);
+        AppendPathFilters(ref sql, request.PathPatterns, request.ExcludePathPatterns, request.ExcludeTests);
+    }
+
+    private string BuildGraphReferenceNameFilterSql(
+        GraphReferenceDirectionSpec direction,
+        GraphReferenceQueryRequest request,
+        GraphReferenceMatchPlan match)
+    {
+        if (match.UsesQualifiedName)
+            return direction.BuildQualifiedNameFilterSql(this, request, match);
+
+        var cssAliasScope = match.CssScssVariableAlias != null
+            ? " AND f.lang = 'css'"
+            : string.Empty;
+        if (request.Exact && _foldReady)
+        {
+            var foldedMatchSql = BuildPersistedFoldedNameMatchSql(direction.FoldedMatchColumnSql, "@query");
+            if (!match.AllowSqlLeafFallback)
+                return $" AND {foldedMatchSql}";
+            if (match.CssScssVariableAlias != null)
+                return $" AND ({foldedMatchSql} OR ({direction.FoldedMatchColumnSql} = @queryCssScssVariableAlias{cssAliasScope}) OR (f.lang = 'sql' AND {direction.SqlLeafFoldedMatchSql}))";
+            return $" AND ({foldedMatchSql} OR (f.lang = 'sql' AND {direction.SqlLeafFoldedMatchSql}))";
+        }
+
+        if (request.Exact)
+        {
+            if (!match.AllowSqlLeafFallback)
+                return $" AND {direction.MatchColumnSql} = @query COLLATE NOCASE";
+            if (match.CssScssVariableAlias != null)
+                return $" AND ({direction.MatchColumnSql} = @query COLLATE NOCASE OR ({direction.MatchColumnSql} = @queryCssScssVariableAlias COLLATE NOCASE{cssAliasScope}) OR (f.lang = 'sql' AND {direction.SqlLeafExactMatchSql}))";
+            return $" AND ({direction.MatchColumnSql} = @query COLLATE NOCASE OR (f.lang = 'sql' AND {direction.SqlLeafExactMatchSql}))";
+        }
+
+        if (match.CssScssVariableAlias != null)
+            return $" AND ({direction.MatchColumnSql} LIKE @query ESCAPE '\\' OR ({direction.MatchColumnSql} = @queryCssScssVariableAlias COLLATE NOCASE{cssAliasScope}) OR (f.lang = 'sql' AND {direction.SqlLeafExactMatchSql}))";
+        return $" AND ({direction.MatchColumnSql} LIKE @query ESCAPE '\\' OR (f.lang = 'sql' AND {direction.SqlLeafExactMatchSql}))";
+    }
+
+    private string BuildCallerQualifiedNameFilterSql(GraphReferenceQueryRequest request)
+    {
+        var folded = _foldReady;
+        var like = !request.Exact;
+        var contextSql = ReferenceContextSql("r");
+        var qualifiedContextSql = BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded, like);
+        var csharpQualifiedContextSql = BuildCSharpQualifiedContextFallbackSql(qualifiedContextSql);
+        var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded);
+        var nonSqlMatchSql = request.Exact
+            ? folded
+                ? BuildPersistedFoldedNameMatchSql("r.symbol_name_folded", "@query")
+                : "r.symbol_name = @query COLLATE NOCASE"
+            : "r.symbol_name LIKE @query ESCAPE '\\'";
+        return $" AND (((f.lang = 'sql') AND {qualifiedContextSql}) OR ((f.lang != 'sql') AND {nonSqlMatchSql}) OR {csharpQualifiedContextSql} OR {qualifiedLeafFallbackSql})";
+    }
+
+    private string BuildCalleeQualifiedNameFilterSql(GraphReferenceQueryRequest request)
+    {
+        var qualifiedLeafFallbackSql = BuildQualifiedLeafFallbackSql(
+            "r.container_name",
+            "r.container_name_folded",
+            folded: _foldReady);
+        if (!request.Exact)
+            return $" AND (r.container_name LIKE @query ESCAPE '\\' OR {qualifiedLeafFallbackSql})";
+        if (_foldReady)
+            return $" AND (((f.lang = 'sql') AND sql_segment_count(r.container_name) = @aliasQuerySegmentCount AND sql_normalize_name_folded(r.container_name) = @aliasQueryNormalizedFolded) OR ((f.lang != 'sql') AND {BuildPersistedFoldedNameMatchSql("r.container_name_folded", "@query")}) OR {qualifiedLeafFallbackSql})";
+        return $" AND (((f.lang = 'sql') AND sql_segment_count(r.container_name) = @aliasQuerySegmentCount AND sql_normalize_name(r.container_name) = @aliasQueryNormalized COLLATE NOCASE) OR ((f.lang != 'sql') AND r.container_name = @query COLLATE NOCASE) OR {qualifiedLeafFallbackSql})";
+    }
+
+    private string BuildCallerIdentityFilterSql(GraphReferenceQueryRequest request)
+    {
+        if (request.IdentitySymbolId == null || !HasTable("symbol_reference_candidates"))
+            return string.Empty;
+
+        var resolutionFilterSql = _referenceColumns.Contains("resolution_state")
+            ? " AND r.resolution_state IN ('resolved', 'resolved_group')"
+            : " AND 1 = 0";
+        return resolutionFilterSql + @"
+                AND EXISTS (
+                    SELECT 1
+                    FROM symbol_reference_candidates AS identity_candidate
+                    WHERE identity_candidate.reference_id = r.id
+                      AND identity_candidate.symbol_id = @targetSymbolId
+                )";
+    }
+
+    private string BuildCalleeIdentityFilterSql(GraphReferenceQueryRequest request)
+        => request.IdentitySymbolId != null && _referenceColumns.Contains("source_symbol_id")
+            ? " AND r.source_symbol_id = @sourceSymbolId"
+            : string.Empty;
+
+    private string BuildCallerPreNameFilterSql(GraphReferenceQueryRequest request)
+    {
+        if (!request.ExcludeSelfReferences)
+            return string.Empty;
+        var selfReferenceSql = _referenceColumns.Contains("is_self_reference")
+            ? "r.is_self_reference"
+            : "0";
+        return $" AND {selfReferenceSql} = 0";
+    }
+
+    private string BuildCallerPostNameFilterSql(GraphReferenceQueryRequest request)
+    {
+        var sql = string.Empty;
+        if (request.Lang != null)
+        {
+            sql += IncludeAmbiguousMSourceForIdentityTarget(request.Lang, request.IdentitySymbolId)
+                ? " AND (f.lang = @lang OR f.lang = 'ambiguous_m')"
+                : " AND f.lang = @lang";
+        }
+        sql += BuildCSharpBareMemberReferenceFilter(
+            request.Query,
+            request.Lang,
+            "f",
+            "r",
+            request.IncludeQualifiedCommonCalls);
+        return sql;
+    }
+
+    private string BuildCalleePostNameFilterSql(GraphReferenceQueryRequest request)
+    {
+        var sql = request.Lang != null
+            ? " AND f.lang = @lang"
+            : string.Empty;
+        if (!request.IncludeQualifiedCommonCalls)
+            sql += BuildCSharpQualifiedCommonCallNoiseFilter("f", "r");
+        return sql;
+    }
+
+    private void BindGraphReferenceQueryPlan(SqliteCommand command, GraphReferenceQueryPlan plan)
+    {
+        for (var index = 0; index < plan.SupportedLanguages.Count; index++)
+            SqliteCommandPolicy.Add(command, $"@graphLang{index}", plan.SupportedLanguages[index]);
+
+        var request = plan.Request;
+        var value = !request.Exact
+            ? $"%{EscapeLikeQuery(request.Query)}%"
+            : _foldReady
+                ? FoldNameForLanguage(request.Query, request.Lang)
+                : request.Query;
+        if (request.Exact && _foldReady)
+            AddPersistedFoldedNameQueryParameters(command, "@query", request.Query, request.Lang);
+        else
+            SqliteCommandPolicy.Add(command, "@query", value);
+        SqliteCommandPolicy.Add(command, "@aliasQuery", request.Query);
+        plan.Direction.BindMatchParameters(this, command, plan);
+
+        if (RequiresReferenceKindParameter(request.ReferenceKind))
+            SqliteCommandPolicy.Add(command, "@referenceKind", request.ReferenceKind);
+        if (request.Lang != null)
+        {
+            var language = plan.Direction.NormalizeBoundLanguage
+                ? NormalizeQueryLanguage(request.Lang)
+                : request.Lang;
+            SqliteCommandPolicy.Add(command, "@lang", language);
+        }
+        if (plan.BindIdentityParameter)
+            SqliteCommandPolicy.Add(command, plan.Direction.IdentityParameterName, request.IdentitySymbolId!.Value);
+        AddPathFilterParameters(command, request.PathPatterns, request.ExcludePathPatterns);
+        if (plan.Shape != GraphReferenceQueryShape.TotalCount)
+            SqliteCommandPolicy.Add(command, "@limit", request.Limit);
+        if (plan.Shape == GraphReferenceQueryShape.List)
+            SqliteCommandPolicy.Add(command, "@offset", Math.Max(0, request.Offset));
+    }
+
+    private void BindCallerMatchParameters(SqliteCommand command, GraphReferenceQueryPlan plan)
+    {
+        var request = plan.Request;
+        AddQualifiedGraphQueryParameters(
+            command,
+            request.Query,
+            plan.Match.AllowQualifiedLeafFallback,
+            plan.Match.AllowCSharpQualifiedContextMatch);
+        SqliteCommandPolicy.Add(command, "@aliasQueryLeafFolded", NameFold.Fold(SqlNameResolver.GetLeafName(request.Query)) ?? SqlNameResolver.GetLeafName(request.Query));
+        AddCssScssVariableAliasParameter(command, request, plan.Match.CssScssVariableAlias);
+        if (plan.Shape == GraphReferenceQueryShape.List)
+            AddGraphReferenceRankingParameters(command, request.Query);
+    }
+
+    private void BindCalleeMatchParameters(SqliteCommand command, GraphReferenceQueryPlan plan)
+    {
+        var request = plan.Request;
+        var normalizedQuery = SqlNameResolver.NormalizeQualifiedName(request.Query);
+        SqliteCommandPolicy.Add(command, "@aliasQueryLeafFolded", NameFold.Fold(SqlNameResolver.GetLeafName(request.Query)) ?? SqlNameResolver.GetLeafName(request.Query));
+        SqliteCommandPolicy.Add(command, "@aliasQueryNormalized", normalizedQuery);
+        SqliteCommandPolicy.Add(command, "@aliasQueryNormalizedFolded", NameFold.Fold(normalizedQuery) ?? normalizedQuery);
+        SqliteCommandPolicy.Add(command, "@aliasQuerySegmentCount", SqlNameResolver.GetSegmentCount(request.Query));
+        if (plan.Shape == GraphReferenceQueryShape.List)
+        {
+            AddCssScssVariableAliasParameter(command, request, plan.Match.CssScssVariableAlias);
+            AddGraphReferenceRankingParameters(command, request.Query);
+            AddQualifiedGraphQueryParameters(command, request.Query, plan.Match.AllowQualifiedLeafFallback);
+        }
+        else
+        {
+            AddQualifiedGraphQueryParameters(command, request.Query, plan.Match.AllowQualifiedLeafFallback);
+            AddCssScssVariableAliasParameter(command, request, plan.Match.CssScssVariableAlias);
+        }
+    }
+
+    private void AddCssScssVariableAliasParameter(
+        SqliteCommand command,
+        GraphReferenceQueryRequest request,
+        string? cssScssVariableAlias)
+    {
+        if (cssScssVariableAlias == null)
+            return;
+        var aliasParameter = request.Exact && _foldReady
+            ? NameFold.Fold(cssScssVariableAlias) ?? cssScssVariableAlias
+            : cssScssVariableAlias;
+        SqliteCommandPolicy.Add(command, "@queryCssScssVariableAlias", aliasParameter);
+    }
+
+    private static void AddGraphReferenceRankingParameters(SqliteCommand command, string query)
+    {
+        SqliteCommandPolicy.Add(command, "@rawQuery", query);
+        SqliteCommandPolicy.Add(command, "@rankingQuery", query.Trim());
+    }
+
+    private static string ReferenceWeightedScoreSql(string columnSql) => $@"
+        SUM(CASE {columnSql}
+            WHEN 'instantiate' THEN 3.0
+            WHEN 'generic_type_argument' THEN 0.5
+            WHEN 'call' THEN 1.0
+            WHEN 'subscribe' THEN 0.1
+            WHEN 'unsubscribe' THEN 0.1
+            WHEN 'razor_event_binding' THEN 0.1
+            ELSE 0.0
+        END)";
+
+    private static string BuildReferenceRankOrderSql(
+        ReferenceRankMode rankMode,
+        string queriedNameSql)
+        => string.Join(
+            ", ",
+            ReferenceRankRecipes.Get(rankMode).Select(dimension => dimension switch
+            {
+                ReferenceRankDimension.ReferenceWeightScoreDescending => "weighted_score DESC",
+                ReferenceRankDimension.ReferenceCountDescending => "reference_count DESC",
+                ReferenceRankDimension.ReferenceKindPriorityAscending =>
+                    "CASE reference_kind WHEN 'instantiate' THEN 0 WHEN 'call' THEN 1 WHEN 'generic_type_argument' THEN 2 WHEN 'subscribe' THEN 3 ELSE 4 END",
+                ReferenceRankDimension.ExactCaseMatchDescending =>
+                    $"CASE WHEN {queriedNameSql} = @rawQuery THEN 0 ELSE 1 END",
+                ReferenceRankDimension.ExactNameMatchDescending =>
+                    $"CASE WHEN lower({queriedNameSql}) = lower(@rankingQuery) THEN 0 ELSE 1 END",
+                ReferenceRankDimension.PathCategoryAscending => GetPathBucketOrderSql("r.path"),
+                ReferenceRankDimension.PathAscending => "r.path",
+                ReferenceRankDimension.FirstLineAscending => "first_line",
+                ReferenceRankDimension.FirstColumnAscending => "first_column",
+                ReferenceRankDimension.LanguageAscending => "r.lang",
+                ReferenceRankDimension.ContainerKindAscending => "r.container_kind",
+                ReferenceRankDimension.ContainerNameAscending => "r.container_name",
+                ReferenceRankDimension.SymbolNameAscending => "r.symbol_name",
+                ReferenceRankDimension.ReferenceKindAscending => "reference_kind",
+                _ => throw new ArgumentOutOfRangeException(nameof(dimension), dimension, null),
+            }));
+
+}
diff --git a/src/CodeIndex/Database/DbReader.GraphReferenceQueryExecution.cs b/src/CodeIndex/Database/DbReader.GraphReferenceQueryExecution.cs
new file mode 100644
index 000000000..06f3ff573
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.GraphReferenceQueryExecution.cs
@@ -0,0 +1,144 @@
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private List<TResult> ExecuteGraphReferenceList<TResult>(
+        GraphReferenceQueryPlan plan,
+        Func<GraphReferenceRow, TResult> projector)
+    {
+        using var command = _conn.CreateCommand();
+        command.CommandText = plan.Sql;
+        BindGraphReferenceQueryPlan(command, plan);
+
+        var results = new List<TResult>();
+        using var reader = command.ExecuteTrackedReader();
+        while (reader.TrackedRead())
+            results.Add(projector(ReadGraphReferenceRow(reader, plan.Direction.RowLayout)));
+        return results;
+    }
+
+    private int ExecuteGraphReferenceLimitedCount(GraphReferenceQueryPlan plan)
+    {
+        using var command = _conn.CreateCommand();
+        command.CommandText = plan.Sql;
+        BindGraphReferenceQueryPlan(command, plan);
+        var raw = command.ExecuteScalar();
+        return raw is long count ? (int)count : Convert.ToInt32(raw);
+    }
+
+    private QueryCountResult ExecuteGraphReferenceTotalCount(GraphReferenceQueryPlan plan)
+    {
+        using var command = _conn.CreateCommand();
+        command.CommandText = plan.Sql;
+        BindGraphReferenceQueryPlan(command, plan);
+        return ExecuteCountSummary(command);
+    }
+
+    private GraphReferenceRow ReadGraphReferenceRow(
+        SqliteDataReader reader,
+        GraphReferenceRowLayout layout)
+    {
+        var primaryKind = reader.GetString(5);
+        var kindAggregate = TruncateReferenceKindAggregate(
+            GetNullableString(reader, layout.ReferenceKindsOrdinal),
+            out var kindsTruncated);
+        var countAggregate = TruncateReferenceKindAggregate(
+            GetNullableString(reader, layout.ReferenceKindCountsOrdinal),
+            out var countsTruncated);
+        var referenceCount = reader.GetInt32(layout.ReferenceCountOrdinal);
+        var firstColumn = layout.FirstColumnIsNullable
+            ? GetNullableInt32(reader, layout.FirstColumnOrdinal)
+            : reader.GetInt32(layout.FirstColumnOrdinal);
+        return new GraphReferenceRow(
+            reader.GetString(0),
+            GetNullableString(reader, 1),
+            GetNullableString(reader, 2),
+            GetNullableString(reader, 3),
+            reader.GetString(4),
+            primaryKind,
+            ParseDistinctReferenceKinds(kindAggregate, primaryKind),
+            ParseReferenceKindCounts(countAggregate, primaryKind, referenceCount),
+            kindsTruncated || countsTruncated,
+            reader.GetDouble(layout.ReferenceWeightOrdinal),
+            reader.GetInt32(layout.FirstLineOrdinal),
+            firstColumn,
+            layout.FirstLengthOrdinal is int lengthOrdinal ? GetNullableInt32(reader, lengthOrdinal) : null,
+            referenceCount,
+            layout.SelfReferenceOrdinal is int selfOrdinal && reader.GetInt32(selfOrdinal) != 0,
+            layout.MutualRecursionOrdinal is int mutualOrdinal && reader.GetInt32(mutualOrdinal) != 0);
+    }
+
+    private static CallerResult ProjectCallerResult(GraphReferenceRow row)
+        => new()
+        {
+            Path = row.Path,
+            Lang = row.Lang,
+            CallerKind = row.CallerKind,
+            CallerName = row.CallerName,
+            CalleeName = row.CalleeName,
+            ReferenceKind = row.ReferenceKind,
+            ReferenceKinds = row.ReferenceKinds,
+            HasMixedReferenceKinds = row.ReferenceKinds.Count > 1,
+            ReferenceKindCounts = row.ReferenceKindCounts,
+            AggregateTruncated = row.AggregateTruncated,
+            ReferenceWeightScore = row.ReferenceWeightScore,
+            FirstLine = row.FirstLine,
+            FirstColumn = row.FirstColumn!.Value,
+            ReferenceCount = row.ReferenceCount,
+            HasSelfReference = row.HasSelfReference,
+            HasMutualRecursion = row.HasMutualRecursion,
+        };
+
+    private static CalleeResult ProjectCalleeResult(GraphReferenceRow row)
+        => new()
+        {
+            Path = row.Path,
+            Lang = row.Lang,
+            CallerKind = row.CallerKind,
+            CallerName = row.CallerName,
+            CalleeName = row.CalleeName,
+            ReferenceKind = row.ReferenceKind,
+            ReferenceKinds = row.ReferenceKinds,
+            HasMixedReferenceKinds = row.ReferenceKinds.Count > 1,
+            ReferenceKindCounts = row.ReferenceKindCounts,
+            AggregateTruncated = row.AggregateTruncated,
+            ReferenceWeightScore = row.ReferenceWeightScore,
+            FirstLine = row.FirstLine,
+            FirstColumn = row.FirstColumn,
+            FirstLength = row.FirstLength,
+            ReferenceCount = row.ReferenceCount,
+        };
+
+    private static IReadOnlyDictionary<string, int> ParseReferenceKindCounts(
+        string? aggregate,
+        string primaryKind,
+        int fallbackCount)
+    {
+        var counts = new Dictionary<string, int>(StringComparer.Ordinal)
+        {
+            ["call"] = 0,
+            ["instantiate"] = 0,
+            ["subscribe"] = 0,
+        };
+        if (!string.IsNullOrWhiteSpace(aggregate))
+        {
+            foreach (var entry in aggregate.Split(','))
+            {
+                var separator = entry.LastIndexOf(':');
+                if (separator <= 0 || separator == entry.Length - 1)
+                    continue;
+                var kind = entry[..separator].Trim();
+                if (kind.Length == 0 || !int.TryParse(entry[(separator + 1)..], out var count))
+                    continue;
+                counts[kind] = counts.TryGetValue(kind, out var existing)
+                    ? existing + count
+                    : count;
+            }
+        }
+        if (counts.Count == 0 && !string.IsNullOrEmpty(primaryKind))
+            counts[primaryKind] = fallbackCount;
+        return counts;
+    }
+}

From d10806010ebf804c06b449aa98db6161ee942f9f Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 06:17:00 +0900
Subject: [PATCH 06/45] Decompose file content loading

---
 .../Scanning/FileContentLoader.Decoding.cs    |  94 ++-
 .../Scanning/FileContentLoader.GitLfs.cs      | 111 ++++
 .../Scanning/FileContentLoader.Loading.cs     |  42 ++
 .../FileContentLoader.Normalization.cs        | 494 +++++++++++++++
 .../Scanning/FileContentLoader.RawBytes.cs    |  41 +-
 .../Indexer/Scanning/FileContentLoader.cs     | 596 +-----------------
 6 files changed, 776 insertions(+), 602 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/Scanning/FileContentLoader.GitLfs.cs
 create mode 100644 src/CodeIndex/Indexer/Scanning/FileContentLoader.Loading.cs
 create mode 100644 src/CodeIndex/Indexer/Scanning/FileContentLoader.Normalization.cs

diff --git a/src/CodeIndex/Indexer/Scanning/FileContentLoader.Decoding.cs b/src/CodeIndex/Indexer/Scanning/FileContentLoader.Decoding.cs
index 197136321..de3afcca8 100644
--- a/src/CodeIndex/Indexer/Scanning/FileContentLoader.Decoding.cs
+++ b/src/CodeIndex/Indexer/Scanning/FileContentLoader.Decoding.cs
@@ -11,12 +11,38 @@ internal sealed partial class FileContentLoader
     private static readonly UnicodeEncoding Utf16BeBomEncoding = new(bigEndian: true, byteOrderMark: true, throwOnInvalidBytes: false);
     private static readonly UnicodeEncoding Utf16BeNoBomEncoding = new(bigEndian: true, byteOrderMark: false, throwOnInvalidBytes: false);
 
-    private (string Content, string? Warning, FileContentInspection Inspection, bool HadInvalidUtf8Replacement) DecodeIndexableContent(
+    private readonly record struct DecodedFileContent(
+        string Content,
+        string? Warning,
+        FileContentInspection Inspection,
+        bool HadInvalidUtf8Replacement);
+
+    private readonly record struct ContentDecodePreparation(
+        bool IsUtf16Encoded,
+        bool Utf16BigEndian,
+        bool HasUtf16Bom,
+        bool RawByteContentInspected,
+        FileContentInspection Inspection);
+
+    private DecodedFileContent DecodeIndexableContent(
         byte[] bytes,
         string relativePath,
         bool inspectRawByteContent = true)
     {
-        var isUtf16Encoded = TryDetectUtf16Encoding(bytes, allowHeuristic: true, out var utf16BigEndian, out var hasUtf16Bom);
+        var preparation = PrepareContentDecode(bytes, inspectRawByteContent);
+        ThrowIfBinaryContent(bytes, relativePath, preparation);
+        return DecodePreparedContent(bytes, relativePath, preparation);
+    }
+
+    private static ContentDecodePreparation PrepareContentDecode(
+        byte[] bytes,
+        bool inspectRawByteContent)
+    {
+        var isUtf16Encoded = TryDetectUtf16Encoding(
+            bytes,
+            allowHeuristic: true,
+            out var utf16BigEndian,
+            out var hasUtf16Bom);
         var rawByteContentInspected = !isUtf16Encoded && inspectRawByteContent;
         var rawByteContent = rawByteContentInspected
             ? RawByteContentInspection.Inspect(bytes)
@@ -28,36 +54,70 @@ internal sealed partial class FileContentLoader
             HasUtf16Bom: hasUtf16Bom,
             RawByteContent: rawByteContent);
 
-        if (!isUtf16Encoded && TryFindIndexBlockingNullByte(
-            bytes,
-            rawByteContent,
+        return new ContentDecodePreparation(
+            isUtf16Encoded,
+            utf16BigEndian,
+            hasUtf16Bom,
             rawByteContentInspected,
+            inspection);
+    }
+
+    private static void ThrowIfBinaryContent(
+        byte[] bytes,
+        string relativePath,
+        ContentDecodePreparation preparation)
+    {
+        if (preparation.IsUtf16Encoded
+            || !TryFindIndexBlockingNullByte(
+            bytes,
+            preparation.Inspection.RawByteContent,
+            preparation.RawByteContentInspected,
             out var nullByteOffset))
-            throw new FileIndexer.BinaryFileSkippedException(
-                relativePath,
-                nullByteOffset,
-                $"{relativePath}: binary file skipped because it contains NULL byte at byte offset {nullByteOffset}");
+        {
+            return;
+        }
+
+        throw new FileIndexer.BinaryFileSkippedException(
+            relativePath,
+            nullByteOffset,
+            $"{relativePath}: binary file skipped because it contains NULL byte at byte offset {nullByteOffset}");
+    }
 
-        if (isUtf16Encoded)
+    private static DecodedFileContent DecodePreparedContent(
+        byte[] bytes,
+        string relativePath,
+        ContentDecodePreparation preparation)
+    {
+        if (preparation.IsUtf16Encoded)
         {
-            var content = GetUtf16Encoding(utf16BigEndian, hasUtf16Bom).GetString(bytes);
-            var warning = hasUtf16Bom
+            var content = GetUtf16Encoding(
+                preparation.Utf16BigEndian,
+                preparation.HasUtf16Bom).GetString(bytes);
+            var warning = preparation.HasUtf16Bom
                 ? null
-                : $"{relativePath}: decoded as {(utf16BigEndian ? "UTF-16BE" : "UTF-16LE")} without BOM by NUL-byte heuristic";
-            return (content, warning, inspection, HadInvalidUtf8Replacement: false);
+                : $"{relativePath}: decoded as {(preparation.Utf16BigEndian ? "UTF-16BE" : "UTF-16LE")} without BOM by NUL-byte heuristic";
+            return new DecodedFileContent(
+                content,
+                warning,
+                preparation.Inspection,
+                HadInvalidUtf8Replacement: false);
         }
 
         try
         {
-            return (StrictUtf8Encoding.GetString(bytes), null, inspection, HadInvalidUtf8Replacement: false);
+            return new DecodedFileContent(
+                StrictUtf8Encoding.GetString(bytes),
+                null,
+                preparation.Inspection,
+                HadInvalidUtf8Replacement: false);
         }
         catch (DecoderFallbackException)
         {
             var content = LenientUtf8Encoding.GetString(bytes);
-            return (
+            return new DecodedFileContent(
                 content,
                 $"{relativePath}: contains invalid UTF-8 bytes (replaced with U+FFFD)",
-                inspection,
+                preparation.Inspection,
                 HadInvalidUtf8Replacement: true);
         }
     }
diff --git a/src/CodeIndex/Indexer/Scanning/FileContentLoader.GitLfs.cs b/src/CodeIndex/Indexer/Scanning/FileContentLoader.GitLfs.cs
new file mode 100644
index 000000000..95297a9f6
--- /dev/null
+++ b/src/CodeIndex/Indexer/Scanning/FileContentLoader.GitLfs.cs
@@ -0,0 +1,111 @@
+namespace CodeIndex.Indexer;
+
+internal sealed partial class FileContentLoader
+{
+    private const int GitLfsPointerMaxBytes = 1024;
+    private static ReadOnlySpan<byte> GitLfsPointerPrefix
+        => "version https://git-lfs.github.com/spec/v1"u8;
+    private static ReadOnlySpan<byte> GitLfsExtensionPrefix => "ext-"u8;
+    private static ReadOnlySpan<byte> GitLfsSha256OidPrefix => "oid sha256:"u8;
+    private static ReadOnlySpan<byte> GitLfsSizePrefix => "size "u8;
+
+    internal static bool IsGitLfsPointer(byte[] rawBytes)
+    {
+        if (rawBytes.Length == 0 || rawBytes.Length >= GitLfsPointerMaxBytes)
+            return false;
+
+        ReadOnlySpan<byte> remaining = rawBytes;
+        if (!remaining.StartsWith(GitLfsPointerPrefix))
+            return false;
+
+        if (!TryReadGitLfsLine(ref remaining, out var line)
+            || !line.SequenceEqual(GitLfsPointerPrefix))
+        {
+            return false;
+        }
+
+        if (!TryReadGitLfsLine(ref remaining, out line))
+            return false;
+        while (line.StartsWith(GitLfsExtensionPrefix))
+        {
+            if (!TryReadGitLfsLine(ref remaining, out line))
+                return false;
+        }
+
+        if (!IsGitLfsSha256OidLine(line))
+            return false;
+        if (!TryReadGitLfsLine(ref remaining, out line)
+            || !IsGitLfsSizeLine(line))
+        {
+            return false;
+        }
+
+        return remaining.IsEmpty;
+    }
+
+    private static bool TryReadGitLfsLine(
+        ref ReadOnlySpan<byte> remaining,
+        out ReadOnlySpan<byte> line)
+    {
+        if (remaining.IsEmpty)
+        {
+            line = default;
+            return false;
+        }
+
+        var newlineIndex = remaining.IndexOfAny((byte)'\r', (byte)'\n');
+        if (newlineIndex < 0)
+        {
+            line = remaining;
+            remaining = ReadOnlySpan<byte>.Empty;
+            return true;
+        }
+
+        line = remaining[..newlineIndex];
+        var nextIndex = newlineIndex + 1;
+        if (remaining[newlineIndex] == (byte)'\r'
+            && nextIndex < remaining.Length
+            && remaining[nextIndex] == (byte)'\n')
+        {
+            nextIndex++;
+        }
+
+        remaining = remaining[nextIndex..];
+        return true;
+    }
+
+    private static bool IsGitLfsSha256OidLine(ReadOnlySpan<byte> line)
+    {
+        if (!line.StartsWith(GitLfsSha256OidPrefix))
+            return false;
+
+        var hash = line[GitLfsSha256OidPrefix.Length..];
+        if (hash.Length != 64)
+            return false;
+        foreach (var value in hash)
+        {
+            if (!((value >= (byte)'0' && value <= (byte)'9')
+                  || (value >= (byte)'a' && value <= (byte)'f')))
+            {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private static bool IsGitLfsSizeLine(ReadOnlySpan<byte> line)
+    {
+        if (!line.StartsWith(GitLfsSizePrefix))
+            return false;
+
+        var size = line[GitLfsSizePrefix.Length..];
+        if (size.Length == 0)
+            return false;
+        foreach (var value in size)
+        {
+            if (value < (byte)'0' || value > (byte)'9')
+                return false;
+        }
+        return true;
+    }
+}
diff --git a/src/CodeIndex/Indexer/Scanning/FileContentLoader.Loading.cs b/src/CodeIndex/Indexer/Scanning/FileContentLoader.Loading.cs
new file mode 100644
index 000000000..65ec6f909
--- /dev/null
+++ b/src/CodeIndex/Indexer/Scanning/FileContentLoader.Loading.cs
@@ -0,0 +1,42 @@
+namespace CodeIndex.Indexer;
+
+internal sealed partial class FileContentLoader
+{
+    private static LoadedFileContent BuildGitLfsPointerContent(
+        RawFileSnapshot rawFile)
+    {
+        return new LoadedFileContent(
+            string.Empty,
+            rawFile.Bytes,
+            rawFile.SizeBytes,
+            rawFile.ModifiedUtc,
+            NormalizedContentFacts.Empty,
+            ComputeChecksum(rawFile.Bytes),
+            null,
+            FileContentInspection.GitLfsPointer());
+    }
+
+    private static LoadedFileContent BuildLoadedFileContent(
+        RawFileSnapshot rawFile,
+        DecodedFileContent decoded,
+        NormalizedIndexableContent normalized)
+    {
+        var checksum = CanReuseRawBytesForNormalizedChecksum(
+            decoded.Content,
+            decoded.Warning,
+            decoded.Inspection,
+            normalized)
+                ? ComputeRawChecksum(rawFile.Bytes)
+                : ComputeChecksumFromNormalizedContent(normalized.Content);
+
+        return new LoadedFileContent(
+            normalized.Content,
+            rawFile.Bytes,
+            rawFile.SizeBytes,
+            rawFile.ModifiedUtc,
+            normalized.Facts,
+            checksum,
+            decoded.Warning,
+            decoded.Inspection);
+    }
+}
diff --git a/src/CodeIndex/Indexer/Scanning/FileContentLoader.Normalization.cs b/src/CodeIndex/Indexer/Scanning/FileContentLoader.Normalization.cs
new file mode 100644
index 000000000..12c129223
--- /dev/null
+++ b/src/CodeIndex/Indexer/Scanning/FileContentLoader.Normalization.cs
@@ -0,0 +1,494 @@
+using System.Text;
+
+namespace CodeIndex.Indexer;
+
+internal sealed partial class FileContentLoader
+{
+    internal readonly record struct NormalizedIndexableContent(
+        string Content,
+        NormalizedContentFacts Facts)
+    {
+        internal int LineCount => Facts.LineCount;
+        internal bool HasOversizeLine => Facts.HasOversizeLine;
+        internal int ConflictMarkerLine => Facts.ConflictMarkerLine;
+    }
+
+    internal static string NormalizeLineEndings(string content)
+    {
+        var firstCarriageReturn = content.IndexOf('\r');
+        if (firstCarriageReturn < 0)
+            return content;
+
+        var builder = new StringBuilder(content.Length);
+        builder.Append(content, 0, firstCarriageReturn);
+
+        for (var index = firstCarriageReturn; index < content.Length; index++)
+        {
+            if (content[index] != '\r')
+            {
+                builder.Append(content[index]);
+                continue;
+            }
+
+            builder.Append('\n');
+            if (index + 1 < content.Length && content[index + 1] == '\n')
+                index++;
+        }
+
+        return builder.ToString();
+    }
+
+    internal static string StripLineLeadingInvisibles(string content)
+    {
+        if (string.IsNullOrEmpty(content))
+            return content;
+
+        var firstStripIndex = FindFirstLineLeadingInvisible(content);
+        if (firstStripIndex < 0)
+            return content;
+
+        var builder = new StringBuilder(content.Length - 1);
+        if (firstStripIndex > 0)
+            builder.Append(content, 0, firstStripIndex);
+        var atLineStart = true;
+        for (var index = firstStripIndex + 1; index < content.Length; index++)
+        {
+            var current = content[index];
+            if (IsLineLeadingInvisible(current) && atLineStart)
+                continue;
+            builder.Append(current);
+            atLineStart = current == '\n';
+        }
+        return builder.ToString();
+    }
+
+    private static int FindFirstLineLeadingInvisible(string content)
+    {
+        var searchOffset = 0;
+        while (searchOffset < content.Length)
+        {
+            var relativeIndex = content.AsSpan(searchOffset).IndexOfAny('\uFEFF', '\u200B');
+            if (relativeIndex < 0)
+                return -1;
+
+            var index = searchOffset + relativeIndex;
+            if (index == 0 || content[index - 1] == '\n')
+                return index;
+
+            searchOffset = index + 1;
+        }
+
+        return -1;
+    }
+
+    private static bool IsLineLeadingInvisible(char current)
+        => current is '\uFEFF' or '\u200B';
+
+    internal static NormalizedIndexableContent NormalizeForIndexing(
+        string content,
+        bool discardReplacementLinesWhenNonUtf8Likely = false)
+    {
+        if (content.Length == 0)
+            return new NormalizedIndexableContent(content, NormalizedContentFacts.Empty);
+
+        var scanner = new IndexingNormalizationScanner(
+            content,
+            discardReplacementLinesWhenNonUtf8Likely);
+        return scanner.Normalize();
+    }
+
+    internal static string NormalizeContentForPrepass(string content)
+    {
+        if (content.Length == 0)
+            return content;
+        var firstNormalizationIndex = FindFirstPrepassNormalizationIndex(content);
+        if (firstNormalizationIndex < 0)
+            return content;
+
+        StringBuilder? builder = null;
+        var atLineStart = firstNormalizationIndex == 0 || content[firstNormalizationIndex - 1] == '\n';
+
+        StringBuilder EnsureBuilder(int sourceIndex)
+        {
+            builder ??= new StringBuilder(content.Length).Append(content, 0, sourceIndex);
+            return builder;
+        }
+
+        for (var index = firstNormalizationIndex; index < content.Length; index++)
+        {
+            var current = content[index];
+            if (IsLineLeadingInvisible(current) && atLineStart)
+            {
+                EnsureBuilder(index);
+                continue;
+            }
+
+            if (current == '\r')
+            {
+                EnsureBuilder(index).Append('\n');
+                if (index + 1 < content.Length && content[index + 1] == '\n')
+                    index++;
+                atLineStart = true;
+                continue;
+            }
+
+            builder?.Append(current);
+            atLineStart = current == '\n';
+        }
+
+        return builder?.ToString() ?? content;
+    }
+
+    private static int FindFirstPrepassNormalizationIndex(string content)
+    {
+        var searchOffset = 0;
+        while (searchOffset < content.Length)
+        {
+            var relativeIndex = content.AsSpan(searchOffset).IndexOfAny('\r', '\uFEFF', '\u200B');
+            if (relativeIndex < 0)
+                return -1;
+
+            var index = searchOffset + relativeIndex;
+            if (content[index] == '\r' || index == 0 || content[index - 1] == '\n')
+                return index;
+
+            searchOffset = index + 1;
+        }
+
+        return -1;
+    }
+
+    private struct IndexingNormalizationScanner
+    {
+        private readonly string _content;
+        private readonly bool _discardReplacementLinesWhenNonUtf8Likely;
+        private readonly bool _trackFtsTokens;
+        private StringBuilder? _builder;
+        private int _outputLength;
+        private int _lineCount;
+        private int _currentLineLength;
+        private int _firstOversizeLine;
+        private int _conflictMarkerLine;
+        private int _conflictScanByteCount;
+        private bool _conflictScanComplete;
+        private int _replacementCharacterCount;
+        private List<int>? _replacementCharacterLines;
+        private bool _retainReplacementCharacterLines;
+        private int _firstOversizeFtsTokenLine;
+        private int _ftsTokenLength;
+        private int _pendingChunkStartOffset;
+        private int _pendingFullChunkEndOffset;
+        private List<int>? _additionalChunkStartOffsets;
+        private List<int>? _fullChunkEndOffsets;
+        private bool _trackChunkSlices;
+        private bool _previousOutputWasLineBreak;
+        private bool _atLineStart;
+
+        internal IndexingNormalizationScanner(
+            string content,
+            bool discardReplacementLinesWhenNonUtf8Likely)
+        {
+            this = default;
+            _content = content;
+            _discardReplacementLinesWhenNonUtf8Likely =
+                discardReplacementLinesWhenNonUtf8Likely;
+            _trackFtsTokens = content.Length
+                > CodeIndex.Database.DbReader.FtsUnicode61MaxTokenLength;
+            _retainReplacementCharacterLines = true;
+            _trackChunkSlices = true;
+            _atLineStart = true;
+        }
+
+        internal NormalizedIndexableContent Normalize()
+        {
+            ScanContent();
+            return BuildResult();
+        }
+
+        private void ScanContent()
+        {
+            for (var index = 0; index < _content.Length; index++)
+            {
+                var current = _content[index];
+                if (IsLineLeadingInvisible(current) && _atLineStart)
+                {
+                    EnsureBuilder(index);
+                    continue;
+                }
+
+                if (current == '\r')
+                {
+                    NormalizeCarriageReturn(ref index);
+                    continue;
+                }
+
+                if (char.IsHighSurrogate(current)
+                    && index + 1 < _content.Length
+                    && char.IsLowSurrogate(_content[index + 1]))
+                {
+                    NormalizeSurrogatePair(ref index, current);
+                    continue;
+                }
+
+                NormalizeSingleCharacter(index, current);
+            }
+        }
+
+        private void NormalizeCarriageReturn(ref int sourceIndex)
+        {
+            EnsureBuilder(sourceIndex).Append('\n');
+            BeginOutputUnit();
+            TrackConflictBytes(1);
+            FinishOutputLineBreak();
+            if (sourceIndex + 1 < _content.Length
+                && _content[sourceIndex + 1] == '\n')
+            {
+                sourceIndex++;
+            }
+        }
+
+        private void NormalizeSurrogatePair(ref int sourceIndex, char highSurrogate)
+        {
+            var lowSurrogate = _content[++sourceIndex];
+            _builder?.Append(highSurrogate).Append(lowSurrogate);
+            BeginOutputUnit();
+            var rune = new Rune(highSurrogate, lowSurrogate);
+            TrackConflictBytes(rune.Utf8SequenceLength);
+            if (_trackFtsTokens)
+                TrackFtsRune(rune);
+            FinishOutputChars(2);
+        }
+
+        private void NormalizeSingleCharacter(int sourceIndex, char current)
+        {
+            _builder?.Append(current);
+            BeginOutputUnit();
+            if (char.IsSurrogate(current))
+            {
+                TrackConflictBytes(3);
+                if (_trackFtsTokens)
+                    TrackInvalidFtsRune();
+                FinishOutputChars(1);
+                return;
+            }
+
+            var utf8ByteLength = current <= '\u007F'
+                ? 1
+                : new Rune(current).Utf8SequenceLength;
+            TrackConflictBytes(utf8ByteLength, current, sourceIndex);
+            TrackReplacementCharacter(current);
+            if (current == '\n')
+            {
+                FinishOutputLineBreak();
+                return;
+            }
+
+            if (_trackFtsTokens)
+                TrackFtsRune(new Rune(current));
+            FinishOutputChars(1);
+        }
+
+        private StringBuilder EnsureBuilder(int sourceIndex)
+        {
+            _builder ??= new StringBuilder(_content.Length)
+                .Append(_content, 0, sourceIndex);
+            return _builder;
+        }
+
+        private void BeginOutputUnit()
+        {
+            if (_outputLength == 0)
+            {
+                _lineCount = 1;
+            }
+            else if (_previousOutputWasLineBreak)
+            {
+                _lineCount++;
+
+                if (!_trackChunkSlices)
+                    return;
+
+                var chunkStep = ChunkSplitter.ChunkSize - ChunkSplitter.Overlap;
+                if (_lineCount > ChunkSplitter.ChunkSize
+                    && (_lineCount - ChunkSplitter.ChunkSize - 1) % chunkStep == 0)
+                {
+                    (_additionalChunkStartOffsets ??= []).Add(_pendingChunkStartOffset);
+                    (_fullChunkEndOffsets ??= []).Add(_pendingFullChunkEndOffset);
+                }
+
+                if (_lineCount > 1
+                    && (_lineCount - 1) % chunkStep == 0)
+                {
+                    _pendingChunkStartOffset = _outputLength;
+                }
+            }
+        }
+
+        private void TrackConflictBytes(
+            int utf8ByteLength,
+            char firstChar = '\0',
+            int sourceIndex = -1)
+        {
+            if (_conflictMarkerLine > 0 || _conflictScanComplete)
+                return;
+
+            _conflictScanByteCount += utf8ByteLength;
+            if (_conflictScanByteCount > FileIndexer.ConflictMarkerScanLimitBytes)
+            {
+                _conflictScanComplete = true;
+                return;
+            }
+
+            if (_atLineStart
+                && sourceIndex >= 0
+                && firstChar is '<' or '>'
+                && FileIndexer.IsConflictMarkerLineStart(_content.AsSpan(sourceIndex)))
+            {
+                _conflictMarkerLine = _lineCount;
+            }
+        }
+
+        private void TrackReplacementCharacter(char current)
+        {
+            if (current != '\uFFFD')
+                return;
+
+            _replacementCharacterCount++;
+            if (_discardReplacementLinesWhenNonUtf8Likely
+                && FileIndexer.MeetsNonUtf8LikelyReplacementThreshold(
+                    _replacementCharacterCount,
+                    _content.Length))
+            {
+                _replacementCharacterLines = null;
+                _retainReplacementCharacterLines = false;
+                return;
+            }
+
+            if (!_retainReplacementCharacterLines)
+                return;
+
+            if (_replacementCharacterLines is null
+                || _replacementCharacterLines[^1] != _lineCount)
+            {
+                (_replacementCharacterLines ??= []).Add(_lineCount);
+            }
+        }
+
+        private void TrackFtsRune(Rune rune)
+        {
+            if (_firstOversizeFtsTokenLine > 0)
+                return;
+
+            var isTokenRune = rune.Value <= '\u007F'
+                ? FileIndexer.IsLikelyUnicode61AsciiTokenChar((char)rune.Value)
+                : FileIndexer.IsLikelyUnicode61TokenRune(rune);
+            if (isTokenRune)
+            {
+                _ftsTokenLength++;
+                if (_ftsTokenLength > CodeIndex.Database.DbReader.FtsUnicode61MaxTokenLength)
+                    _firstOversizeFtsTokenLine = _lineCount;
+            }
+            else
+            {
+                _ftsTokenLength = 0;
+            }
+        }
+
+        private void TrackInvalidFtsRune()
+        {
+            if (_firstOversizeFtsTokenLine == 0)
+                _ftsTokenLength = 0;
+        }
+
+        private void FinishOutputChars(int charCount)
+        {
+            _currentLineLength += charCount;
+            if (_firstOversizeLine == 0
+                && _currentLineLength > ChunkSplitter.MaxLineLength)
+            {
+                _firstOversizeLine = _lineCount;
+                _trackChunkSlices = false;
+                _additionalChunkStartOffsets = null;
+                _fullChunkEndOffsets = null;
+            }
+
+            _outputLength += charCount;
+            _previousOutputWasLineBreak = false;
+            _atLineStart = false;
+        }
+
+        private void FinishOutputLineBreak()
+        {
+            if (_trackChunkSlices
+                && _lineCount >= ChunkSplitter.ChunkSize
+                && (_lineCount - ChunkSplitter.ChunkSize)
+                    % (ChunkSplitter.ChunkSize - ChunkSplitter.Overlap) == 0)
+            {
+                _pendingFullChunkEndOffset = _outputLength;
+            }
+
+            _outputLength++;
+            _currentLineLength = 0;
+            _ftsTokenLength = 0;
+            _previousOutputWasLineBreak = true;
+            _atLineStart = true;
+        }
+
+        private NormalizedIndexableContent BuildResult()
+        {
+            var normalized = _builder?.ToString() ?? _content;
+            var replacementLines = _discardReplacementLinesWhenNonUtf8Likely
+                && FileIndexer.MeetsNonUtf8LikelyReplacementThreshold(
+                    _replacementCharacterCount,
+                    normalized.Length)
+                    ? null
+                    : _replacementCharacterLines?.ToArray();
+            return new NormalizedIndexableContent(
+                normalized,
+                new NormalizedContentFacts(
+                    _lineCount,
+                    _firstOversizeLine,
+                    _conflictMarkerLine,
+                    _replacementCharacterCount,
+                    replacementLines,
+                    _firstOversizeFtsTokenLine,
+                    BuildChunkSlices()));
+        }
+
+        private NormalizedChunkSlice[]? BuildChunkSlices()
+        {
+            if (_outputLength == 0
+                || _firstOversizeLine > 0
+                || _lineCount <= ChunkSplitter.ChunkSize)
+            {
+                return null;
+            }
+
+            var chunkStep = ChunkSplitter.ChunkSize - ChunkSplitter.Overlap;
+            var chunkCount = 1
+                + (_lineCount - ChunkSplitter.ChunkSize + chunkStep - 1) / chunkStep;
+            var slices = new NormalizedChunkSlice[chunkCount];
+            var effectiveContentLength = _previousOutputWasLineBreak
+                ? _outputLength - 1
+                : _outputLength;
+            for (var chunkIndex = 0; chunkIndex < chunkCount; chunkIndex++)
+            {
+                var startOffset = chunkIndex == 0
+                    ? 0
+                    : _additionalChunkStartOffsets![chunkIndex - 1];
+                var startLineIndex = chunkIndex * chunkStep;
+                var endLineIndex = Math.Min(
+                    startLineIndex + ChunkSplitter.ChunkSize,
+                    _lineCount);
+                var endOffset = endLineIndex < _lineCount
+                    ? _fullChunkEndOffsets![chunkIndex]
+                    : effectiveContentLength;
+                slices[chunkIndex] = new NormalizedChunkSlice(
+                    startOffset,
+                    endOffset - startOffset);
+            }
+
+            return slices;
+        }
+    }
+}
diff --git a/src/CodeIndex/Indexer/Scanning/FileContentLoader.RawBytes.cs b/src/CodeIndex/Indexer/Scanning/FileContentLoader.RawBytes.cs
index 876e4d101..d2409d301 100644
--- a/src/CodeIndex/Indexer/Scanning/FileContentLoader.RawBytes.cs
+++ b/src/CodeIndex/Indexer/Scanning/FileContentLoader.RawBytes.cs
@@ -8,7 +8,12 @@ internal sealed partial class FileContentLoader
 
     internal delegate bool RawByteChunkPredicate(ReadOnlySpan<byte> bytes);
 
-    private (byte[] Bytes, long SizeBytes, DateTime ModifiedUtc) ReadRawBytesWithSizeLimit(
+    private readonly record struct RawFileSnapshot(
+        byte[] Bytes,
+        long SizeBytes,
+        DateTime ModifiedUtc);
+
+    private RawFileSnapshot ReadRawBytesWithSizeLimit(
         string absolutePath,
         string normalizedRelativePath,
         CancellationToken cancellationToken)
@@ -37,12 +42,9 @@ internal sealed partial class FileContentLoader
             {
                 modifiedBeforeRead = File.GetLastWriteTimeUtc(stream.SafeFileHandle);
                 var initialLength = stream.Length;
-                if (initialLength > maxFileSizeBytes)
-                    throw new FileIndexer.FileTooLargeSkippedException(
-                        normalizedRelativePath,
-                        initialLength,
-                        maxFileSizeBytes,
-                        BuildFileTooLargeMessage(initialLength, grewDuringRead: false));
+                ThrowIfInitialLengthExceedsMaxFileSize(
+                    normalizedRelativePath,
+                    initialLength);
 
                 (bytes, sizeBytes) = ReadStreamBytesWithKnownInitialLength(
                     stream,
@@ -56,7 +58,7 @@ internal sealed partial class FileContentLoader
                 break;
         }
 
-        return (bytes, sizeBytes, modifiedUtc);
+        return new RawFileSnapshot(bytes, sizeBytes, modifiedUtc);
     }
 
     internal bool RawByteChunksMayMatch(
@@ -76,12 +78,9 @@ internal bool RawByteChunksMayMatch(
             {
                 modifiedBeforeRead = File.GetLastWriteTimeUtc(stream.SafeFileHandle);
                 var initialLength = stream.Length;
-                if (initialLength > maxFileSizeBytes)
-                    throw new FileIndexer.FileTooLargeSkippedException(
-                        normalizedRelativePath,
-                        initialLength,
-                        maxFileSizeBytes,
-                        BuildFileTooLargeMessage(initialLength, grewDuringRead: false));
+                ThrowIfInitialLengthExceedsMaxFileSize(
+                    normalizedRelativePath,
+                    initialLength);
 
                 matched = RawByteChunksMayMatch(
                     stream,
@@ -323,6 +322,20 @@ private void ThrowIfReadExceedsMaxFileSize(string normalizedRelativePath, long t
             BuildFileTooLargeMessage(total, grewDuringRead: true));
     }
 
+    private void ThrowIfInitialLengthExceedsMaxFileSize(
+        string normalizedRelativePath,
+        long initialLength)
+    {
+        if (initialLength <= maxFileSizeBytes)
+            return;
+
+        throw new FileIndexer.FileTooLargeSkippedException(
+            normalizedRelativePath,
+            initialLength,
+            maxFileSizeBytes,
+            BuildFileTooLargeMessage(initialLength, grewDuringRead: false));
+    }
+
     private static int GetReadLengthWithinLimit(long total, long maxBytes, int bufferLength)
     {
         var remaining = maxBytes - total;
diff --git a/src/CodeIndex/Indexer/Scanning/FileContentLoader.cs b/src/CodeIndex/Indexer/Scanning/FileContentLoader.cs
index 2c432e20a..4adbbb9fe 100644
--- a/src/CodeIndex/Indexer/Scanning/FileContentLoader.cs
+++ b/src/CodeIndex/Indexer/Scanning/FileContentLoader.cs
@@ -1,5 +1,3 @@
-using System.Text;
-
 namespace CodeIndex.Indexer;
 
 internal sealed partial class FileContentLoader(
@@ -17,20 +15,6 @@ internal sealed partial class FileContentLoader(
         bindReadToFileSystemIdentity;
     private readonly Action<string>? _validateResolvedFileReadPath =
         validateResolvedFileReadPath;
-    private const int GitLfsPointerMaxBytes = 1024;
-    private static ReadOnlySpan<byte> GitLfsPointerPrefix => "version https://git-lfs.github.com/spec/v1"u8;
-    private static ReadOnlySpan<byte> GitLfsExtensionPrefix => "ext-"u8;
-    private static ReadOnlySpan<byte> GitLfsSha256OidPrefix => "oid sha256:"u8;
-    private static ReadOnlySpan<byte> GitLfsSizePrefix => "size "u8;
-
-    internal readonly record struct NormalizedIndexableContent(
-        string Content,
-        NormalizedContentFacts Facts)
-    {
-        internal int LineCount => Facts.LineCount;
-        internal bool HasOversizeLine => Facts.HasOversizeLine;
-        internal int ConflictMarkerLine => Facts.ConflictMarkerLine;
-    }
 
     internal readonly record struct CSharpPrepassCandidateContent(
         string Content,
@@ -42,41 +26,18 @@ internal LoadedFileContent Load(
         string relativePath,
         CancellationToken cancellationToken)
     {
-        var (bytes, sizeBytes, modifiedUtc) = ReadRawBytesWithSizeLimit(
+        var rawFile = ReadRawBytesWithSizeLimit(
             absolutePath,
             normalizedRelativePath,
             cancellationToken);
-        if (IsGitLfsPointer(bytes))
-        {
-            var lfsInspection = FileContentInspection.GitLfsPointer();
-            return new LoadedFileContent(
-                string.Empty,
-                bytes,
-                sizeBytes,
-                modifiedUtc,
-                NormalizedContentFacts.Empty,
-                ComputeChecksum(bytes),
-                null,
-                lfsInspection);
-        }
+        if (IsGitLfsPointer(rawFile.Bytes))
+            return BuildGitLfsPointerContent(rawFile);
 
-        var (content, warning, inspection, hadInvalidUtf8Replacement) = DecodeIndexableContent(bytes, relativePath);
+        var decoded = DecodeIndexableContent(rawFile.Bytes, relativePath);
         var normalized = NormalizeForIndexing(
-            content,
-            discardReplacementLinesWhenNonUtf8Likely: hadInvalidUtf8Replacement);
-        var checksum = CanReuseRawBytesForNormalizedChecksum(content, warning, inspection, normalized)
-            ? ComputeRawChecksum(bytes)
-            : ComputeChecksumFromNormalizedContent(normalized.Content);
-
-        return new LoadedFileContent(
-            normalized.Content,
-            bytes,
-            sizeBytes,
-            modifiedUtc,
-            normalized.Facts,
-            checksum,
-            warning,
-            inspection);
+            decoded.Content,
+            discardReplacementLinesWhenNonUtf8Likely: decoded.HadInvalidUtf8Replacement);
+        return BuildLoadedFileContent(rawFile, decoded, normalized);
     }
 
     internal static bool CanReuseRawBytesForNormalizedChecksum(
@@ -96,15 +57,18 @@ internal string LoadNormalizedContentForPrepass(
         string relativePath,
         CancellationToken cancellationToken)
     {
-        var (bytes, _, _) = ReadRawBytesWithSizeLimit(
+        var rawFile = ReadRawBytesWithSizeLimit(
             absolutePath,
             normalizedRelativePath,
             cancellationToken);
-        if (IsGitLfsPointer(bytes))
+        if (IsGitLfsPointer(rawFile.Bytes))
             return string.Empty;
 
-        var (content, _, _, _) = DecodeIndexableContent(bytes, relativePath, inspectRawByteContent: false);
-        return NormalizeContentForPrepass(content);
+        var decoded = DecodeIndexableContent(
+            rawFile.Bytes,
+            relativePath,
+            inspectRawByteContent: false);
+        return NormalizeContentForPrepass(decoded.Content);
     }
 
     internal (CSharpPrepassCandidateContent? Content, bool RequiresRetry)
@@ -128,12 +92,9 @@ internal string LoadNormalizedContentForPrepass(
         {
             modifiedBeforeRead = File.GetLastWriteTimeUtc(stream.SafeFileHandle);
             var initialLength = stream.Length;
-            if (initialLength > maxFileSizeBytes)
-                throw new FileIndexer.FileTooLargeSkippedException(
-                    normalizedRelativePath,
-                    initialLength,
-                    maxFileSizeBytes,
-                    BuildFileTooLargeMessage(initialLength, grewDuringRead: false));
+            ThrowIfInitialLengthExceedsMaxFileSize(
+                normalizedRelativePath,
+                initialLength);
 
             var probe = CSharpStaticInterfacePrepass.CreateRawByteContractProbe();
             var rawCandidate = RawByteChunksMayMatch(
@@ -163,19 +124,22 @@ internal string LoadNormalizedContentForPrepass(
 
         if (retryOnMutation
             && (modifiedAfterRead != modifiedBeforeRead || lengthChanged || pathIdentityChanged))
+        {
             return (null, RequiresRetry: true);
+        }
+
         if (bytes is null || IsGitLfsPointer(bytes))
             return (null, RequiresRetry: false);
 
-        var (content, warning, inspection, _) = DecodeIndexableContent(
+        var decoded = DecodeIndexableContent(
             bytes,
             relativePath,
             inspectRawByteContent: false);
-        var normalized = NormalizeContentForPrepass(content);
+        var normalized = NormalizeContentForPrepass(decoded.Content);
         var checksum = includeChecksum
-            ? warning is null
-                && !inspection.IsUtf16
-                && ReferenceEquals(normalized, content)
+            ? decoded.Warning is null
+                && !decoded.Inspection.IsUtf16
+                && ReferenceEquals(normalized, decoded.Content)
                     ? ComputeRawChecksum(bytes)
                     : ComputeChecksumFromNormalizedContent(normalized)
             : string.Empty;
@@ -183,516 +147,6 @@ internal string LoadNormalizedContentForPrepass(
             new CSharpPrepassCandidateContent(normalized, checksum),
             RequiresRetry: false);
     }
-
-    internal static string NormalizeLineEndings(string content)
-    {
-        var firstCarriageReturn = content.IndexOf('\r');
-        if (firstCarriageReturn < 0)
-            return content;
-
-        var builder = new StringBuilder(content.Length);
-        builder.Append(content, 0, firstCarriageReturn);
-
-        for (var index = firstCarriageReturn; index < content.Length; index++)
-        {
-            if (content[index] != '\r')
-            {
-                builder.Append(content[index]);
-                continue;
-            }
-
-            builder.Append('\n');
-            if (index + 1 < content.Length && content[index + 1] == '\n')
-                index++;
-        }
-
-        return builder.ToString();
-    }
-
-    internal static string StripLineLeadingInvisibles(string content)
-    {
-        if (string.IsNullOrEmpty(content))
-            return content;
-
-        var firstStripIndex = FindFirstLineLeadingInvisible(content);
-        if (firstStripIndex < 0)
-            return content;
-
-        var sb = new StringBuilder(content.Length - 1);
-        if (firstStripIndex > 0)
-            sb.Append(content, 0, firstStripIndex);
-        var atLineStart = true;
-        for (var i = firstStripIndex + 1; i < content.Length; i++)
-        {
-            var c = content[i];
-            if (IsLineLeadingInvisible(c) && atLineStart)
-                continue;
-            sb.Append(c);
-            atLineStart = c == '\n';
-        }
-        return sb.ToString();
-    }
-
-    private static int FindFirstLineLeadingInvisible(string content)
-    {
-        var searchOffset = 0;
-        while (searchOffset < content.Length)
-        {
-            var relativeIndex = content.AsSpan(searchOffset).IndexOfAny('\uFEFF', '\u200B');
-            if (relativeIndex < 0)
-                return -1;
-
-            var index = searchOffset + relativeIndex;
-            if (index == 0 || content[index - 1] == '\n')
-                return index;
-
-            searchOffset = index + 1;
-        }
-
-        return -1;
-    }
-
-    private static bool IsLineLeadingInvisible(char c) => c is '\uFEFF' or '\u200B';
-
-    internal static NormalizedIndexableContent NormalizeForIndexing(
-        string content,
-        bool discardReplacementLinesWhenNonUtf8Likely = false)
-    {
-        if (content.Length == 0)
-            return new NormalizedIndexableContent(content, NormalizedContentFacts.Empty);
-
-        StringBuilder? builder = null;
-        var outputLength = 0;
-        var lineCount = 0;
-        var currentLineLength = 0;
-        var firstOversizeLine = 0;
-        var conflictMarkerLine = 0;
-        var conflictScanByteCount = 0;
-        var conflictScanComplete = false;
-        var replacementCharacterCount = 0;
-        List<int>? replacementCharacterLines = null;
-        var retainReplacementCharacterLines = true;
-        var firstOversizeFtsTokenLine = 0;
-        var ftsTokenLength = 0;
-        var trackFtsTokens = content.Length
-            > CodeIndex.Database.DbReader.FtsUnicode61MaxTokenLength;
-        var pendingChunkStartOffset = 0;
-        var pendingFullChunkEndOffset = 0;
-        List<int>? additionalChunkStartOffsets = null;
-        List<int>? fullChunkEndOffsets = null;
-        var trackChunkSlices = true;
-        var previousOutputWasLineBreak = false;
-        var atLineStart = true;
-
-        StringBuilder EnsureBuilder(int sourceIndex)
-        {
-            builder ??= new StringBuilder(content.Length).Append(content, 0, sourceIndex);
-            return builder;
-        }
-
-        void BeginOutputUnit()
-        {
-            if (outputLength == 0)
-            {
-                lineCount = 1;
-            }
-            else if (previousOutputWasLineBreak)
-            {
-                lineCount++;
-
-                if (!trackChunkSlices)
-                    return;
-
-                var chunkStep = ChunkSplitter.ChunkSize - ChunkSplitter.Overlap;
-                if (lineCount > ChunkSplitter.ChunkSize
-                    && (lineCount - ChunkSplitter.ChunkSize - 1) % chunkStep == 0)
-                {
-                    (additionalChunkStartOffsets ??= []).Add(pendingChunkStartOffset);
-                    (fullChunkEndOffsets ??= []).Add(pendingFullChunkEndOffset);
-                }
-
-                if (lineCount > 1
-                    && (lineCount - 1) % chunkStep == 0)
-                {
-                    pendingChunkStartOffset = outputLength;
-                }
-            }
-        }
-
-        void TrackConflictBytes(int utf8ByteLength, char firstChar = '\0', int sourceIndex = -1)
-        {
-            if (conflictMarkerLine > 0 || conflictScanComplete)
-                return;
-
-            conflictScanByteCount += utf8ByteLength;
-            if (conflictScanByteCount > FileIndexer.ConflictMarkerScanLimitBytes)
-            {
-                conflictScanComplete = true;
-                return;
-            }
-
-            if (atLineStart
-                && sourceIndex >= 0
-                && firstChar is '<' or '>'
-                && FileIndexer.IsConflictMarkerLineStart(content.AsSpan(sourceIndex)))
-            {
-                conflictMarkerLine = lineCount;
-            }
-        }
-
-        void TrackReplacementCharacter(char c)
-        {
-            if (c != '\uFFFD')
-                return;
-
-            replacementCharacterCount++;
-            if (discardReplacementLinesWhenNonUtf8Likely
-                && FileIndexer.MeetsNonUtf8LikelyReplacementThreshold(
-                    replacementCharacterCount,
-                    content.Length))
-            {
-                replacementCharacterLines = null;
-                retainReplacementCharacterLines = false;
-                return;
-            }
-
-            if (!retainReplacementCharacterLines)
-                return;
-
-            if (replacementCharacterLines is null || replacementCharacterLines[^1] != lineCount)
-                (replacementCharacterLines ??= []).Add(lineCount);
-        }
-
-        void TrackFtsRune(Rune rune)
-        {
-            if (firstOversizeFtsTokenLine > 0)
-                return;
-
-            var isTokenRune = rune.Value <= '\u007F'
-                ? FileIndexer.IsLikelyUnicode61AsciiTokenChar((char)rune.Value)
-                : FileIndexer.IsLikelyUnicode61TokenRune(rune);
-            if (isTokenRune)
-            {
-                ftsTokenLength++;
-                if (ftsTokenLength > CodeIndex.Database.DbReader.FtsUnicode61MaxTokenLength)
-                    firstOversizeFtsTokenLine = lineCount;
-            }
-            else
-            {
-                ftsTokenLength = 0;
-            }
-        }
-
-        void TrackInvalidFtsRune()
-        {
-            if (firstOversizeFtsTokenLine == 0)
-                ftsTokenLength = 0;
-        }
-
-        void FinishOutputChars(int charCount)
-        {
-            currentLineLength += charCount;
-            if (firstOversizeLine == 0
-                && currentLineLength > ChunkSplitter.MaxLineLength)
-            {
-                firstOversizeLine = lineCount;
-                trackChunkSlices = false;
-                additionalChunkStartOffsets = null;
-                fullChunkEndOffsets = null;
-            }
-
-            outputLength += charCount;
-            previousOutputWasLineBreak = false;
-            atLineStart = false;
-        }
-
-        void FinishOutputLineBreak()
-        {
-            if (trackChunkSlices
-                && lineCount >= ChunkSplitter.ChunkSize
-                && (lineCount - ChunkSplitter.ChunkSize) % (ChunkSplitter.ChunkSize - ChunkSplitter.Overlap) == 0)
-            {
-                pendingFullChunkEndOffset = outputLength;
-            }
-
-            outputLength++;
-            currentLineLength = 0;
-            ftsTokenLength = 0;
-            previousOutputWasLineBreak = true;
-            atLineStart = true;
-        }
-
-        NormalizedChunkSlice[]? BuildChunkSlices()
-        {
-            if (outputLength == 0
-                || firstOversizeLine > 0
-                || lineCount <= ChunkSplitter.ChunkSize)
-            {
-                return null;
-            }
-
-            var chunkCount = 1 + (lineCount - ChunkSplitter.ChunkSize + (ChunkSplitter.ChunkSize - ChunkSplitter.Overlap) - 1)
-                / (ChunkSplitter.ChunkSize - ChunkSplitter.Overlap);
-            var slices = new NormalizedChunkSlice[chunkCount];
-            var effectiveContentLength = previousOutputWasLineBreak
-                ? outputLength - 1
-                : outputLength;
-            for (var chunkIndex = 0; chunkIndex < chunkCount; chunkIndex++)
-            {
-                var startOffset = chunkIndex == 0
-                    ? 0
-                    : additionalChunkStartOffsets![chunkIndex - 1];
-                var startLineIndex = chunkIndex * (ChunkSplitter.ChunkSize - ChunkSplitter.Overlap);
-                var endLineIndex = Math.Min(startLineIndex + ChunkSplitter.ChunkSize, lineCount);
-                var endOffset = endLineIndex < lineCount
-                    ? fullChunkEndOffsets![chunkIndex]
-                    : effectiveContentLength;
-                slices[chunkIndex] = new NormalizedChunkSlice(
-                    startOffset,
-                    endOffset - startOffset);
-            }
-
-            return slices;
-        }
-
-        for (var i = 0; i < content.Length; i++)
-        {
-            var c = content[i];
-            if (IsLineLeadingInvisible(c) && atLineStart)
-            {
-                EnsureBuilder(i);
-                continue;
-            }
-
-            if (c == '\r')
-            {
-                EnsureBuilder(i).Append('\n');
-                BeginOutputUnit();
-                TrackConflictBytes(1);
-                FinishOutputLineBreak();
-                if (i + 1 < content.Length && content[i + 1] == '\n')
-                    i++;
-                continue;
-            }
-
-            if (char.IsHighSurrogate(c)
-                && i + 1 < content.Length
-                && char.IsLowSurrogate(content[i + 1]))
-            {
-                var lowSurrogate = content[++i];
-                builder?.Append(c).Append(lowSurrogate);
-                BeginOutputUnit();
-                var rune = new Rune(c, lowSurrogate);
-                TrackConflictBytes(rune.Utf8SequenceLength);
-                if (trackFtsTokens)
-                    TrackFtsRune(rune);
-                FinishOutputChars(2);
-                continue;
-            }
-
-            builder?.Append(c);
-            BeginOutputUnit();
-            if (char.IsSurrogate(c))
-            {
-                TrackConflictBytes(3);
-                if (trackFtsTokens)
-                    TrackInvalidFtsRune();
-                FinishOutputChars(1);
-                continue;
-            }
-
-            var utf8ByteLength = c <= '\u007F'
-                ? 1
-                : new Rune(c).Utf8SequenceLength;
-            TrackConflictBytes(utf8ByteLength, c, i);
-            TrackReplacementCharacter(c);
-            if (c == '\n')
-            {
-                FinishOutputLineBreak();
-                continue;
-            }
-
-            if (trackFtsTokens)
-                TrackFtsRune(new Rune(c));
-            FinishOutputChars(1);
-        }
-
-        var normalized = builder?.ToString() ?? content;
-        var replacementLines = discardReplacementLinesWhenNonUtf8Likely
-            && FileIndexer.MeetsNonUtf8LikelyReplacementThreshold(
-                replacementCharacterCount,
-                normalized.Length)
-                ? null
-                : replacementCharacterLines?.ToArray();
-        return new NormalizedIndexableContent(
-            normalized,
-            new NormalizedContentFacts(
-                lineCount,
-                firstOversizeLine,
-                conflictMarkerLine,
-                replacementCharacterCount,
-                replacementLines,
-                firstOversizeFtsTokenLine,
-                BuildChunkSlices()));
-    }
-
-    internal static string NormalizeContentForPrepass(string content)
-    {
-        if (content.Length == 0)
-            return content;
-        var firstNormalizationIndex = FindFirstPrepassNormalizationIndex(content);
-        if (firstNormalizationIndex < 0)
-            return content;
-
-        StringBuilder? builder = null;
-        var atLineStart = firstNormalizationIndex == 0 || content[firstNormalizationIndex - 1] == '\n';
-
-        StringBuilder EnsureBuilder(int sourceIndex)
-        {
-            builder ??= new StringBuilder(content.Length).Append(content, 0, sourceIndex);
-            return builder;
-        }
-
-        for (var i = firstNormalizationIndex; i < content.Length; i++)
-        {
-            var c = content[i];
-            if (IsLineLeadingInvisible(c) && atLineStart)
-            {
-                EnsureBuilder(i);
-                continue;
-            }
-
-            if (c == '\r')
-            {
-                EnsureBuilder(i).Append('\n');
-                if (i + 1 < content.Length && content[i + 1] == '\n')
-                    i++;
-                atLineStart = true;
-                continue;
-            }
-
-            builder?.Append(c);
-            atLineStart = c == '\n';
-        }
-
-        return builder?.ToString() ?? content;
-    }
-
-    private static int FindFirstPrepassNormalizationIndex(string content)
-    {
-        var searchOffset = 0;
-        while (searchOffset < content.Length)
-        {
-            var relativeIndex = content.AsSpan(searchOffset).IndexOfAny('\r', '\uFEFF', '\u200B');
-            if (relativeIndex < 0)
-                return -1;
-
-            var index = searchOffset + relativeIndex;
-            if (content[index] == '\r' || index == 0 || content[index - 1] == '\n')
-                return index;
-
-            searchOffset = index + 1;
-        }
-
-        return -1;
-    }
-
-    internal static bool IsGitLfsPointer(byte[] rawBytes)
-    {
-        if (rawBytes.Length == 0 || rawBytes.Length >= GitLfsPointerMaxBytes)
-            return false;
-
-        ReadOnlySpan<byte> remaining = rawBytes;
-        if (!remaining.StartsWith(GitLfsPointerPrefix))
-            return false;
-
-        if (!TryReadGitLfsLine(ref remaining, out var line)
-            || !line.SequenceEqual(GitLfsPointerPrefix))
-            return false;
-
-        if (!TryReadGitLfsLine(ref remaining, out line))
-            return false;
-        while (line.StartsWith(GitLfsExtensionPrefix))
-        {
-            if (!TryReadGitLfsLine(ref remaining, out line))
-                return false;
-        }
-
-        if (!IsGitLfsSha256OidLine(line))
-            return false;
-        if (!TryReadGitLfsLine(ref remaining, out line)
-            || !IsGitLfsSizeLine(line))
-        {
-            return false;
-        }
-
-        return remaining.IsEmpty;
-    }
-
-    private static bool TryReadGitLfsLine(ref ReadOnlySpan<byte> remaining, out ReadOnlySpan<byte> line)
-    {
-        if (remaining.IsEmpty)
-        {
-            line = default;
-            return false;
-        }
-
-        var newlineIndex = remaining.IndexOfAny((byte)'\r', (byte)'\n');
-        if (newlineIndex < 0)
-        {
-            line = remaining;
-            remaining = ReadOnlySpan<byte>.Empty;
-            return true;
-        }
-
-        line = remaining[..newlineIndex];
-        var nextIndex = newlineIndex + 1;
-        if (remaining[newlineIndex] == (byte)'\r'
-            && nextIndex < remaining.Length
-            && remaining[nextIndex] == (byte)'\n')
-        {
-            nextIndex++;
-        }
-
-        remaining = remaining[nextIndex..];
-        return true;
-    }
-
-    private static bool IsGitLfsSha256OidLine(ReadOnlySpan<byte> line)
-    {
-        if (!line.StartsWith(GitLfsSha256OidPrefix))
-            return false;
-
-        var hash = line[GitLfsSha256OidPrefix.Length..];
-        if (hash.Length != 64)
-            return false;
-        foreach (var value in hash)
-        {
-            if (!((value >= (byte)'0' && value <= (byte)'9')
-                  || (value >= (byte)'a' && value <= (byte)'f')))
-            {
-                return false;
-            }
-        }
-        return true;
-    }
-
-    private static bool IsGitLfsSizeLine(ReadOnlySpan<byte> line)
-    {
-        if (!line.StartsWith(GitLfsSizePrefix))
-            return false;
-
-        var size = line[GitLfsSizePrefix.Length..];
-        if (size.Length == 0)
-            return false;
-        foreach (var value in size)
-        {
-            if (value < (byte)'0' || value > (byte)'9')
-                return false;
-        }
-        return true;
-    }
-
 }
 
 internal readonly record struct LoadedFileContent(

From cf6d58284efb14f26ca7c76fa838969c5a9da1d7 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 06:56:52 +0900
Subject: [PATCH 07/45] Decompose bounded indexed content reading

---
 .../Database/BoundedIndexedChunkSelector.cs   | 533 +++++++++++++
 .../Database/BoundedIndexedContentReader.cs   | 188 +++++
 .../Database/BoundedUtf8ContentDecoder.cs     | 496 ++++++++++++
 .../Database/DbReader.FilesStatus.cs          | 731 +-----------------
 4 files changed, 1232 insertions(+), 716 deletions(-)
 create mode 100644 src/CodeIndex/Database/BoundedIndexedChunkSelector.cs
 create mode 100644 src/CodeIndex/Database/BoundedIndexedContentReader.cs
 create mode 100644 src/CodeIndex/Database/BoundedUtf8ContentDecoder.cs

diff --git a/src/CodeIndex/Database/BoundedIndexedChunkSelector.cs b/src/CodeIndex/Database/BoundedIndexedChunkSelector.cs
new file mode 100644
index 000000000..b5e73110d
--- /dev/null
+++ b/src/CodeIndex/Database/BoundedIndexedChunkSelector.cs
@@ -0,0 +1,533 @@
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+internal sealed class BoundedIndexedChunkSelector
+{
+    private const int LegacyResourceReadProgressOperations = 100;
+
+    private static readonly string LegacyPredecessorSql = $"""
+        SELECT c.id, c.start_line, c.end_line, c.chunk_index
+        FROM chunks c INDEXED BY {DbReader.LegacyBoundedResourceReadFileIndexName}
+        WHERE c.file_id = @fileId
+          AND c.content IS NOT NULL
+          AND c.start_line <= @startLine
+        ORDER BY c.start_line DESC, c.chunk_index DESC
+        LIMIT @chunkLimit
+        """;
+
+    private static readonly string LegacyEndSql = $"""
+        SELECT c.id, c.start_line, c.end_line, c.chunk_index
+        FROM chunks c INDEXED BY {DbReader.LegacyBoundedResourceReadFileIndexName}
+        WHERE c.file_id = @fileId
+          AND c.content IS NOT NULL
+          AND c.end_line >= @startLine
+        ORDER BY c.end_line, c.start_line, c.chunk_index
+        LIMIT @chunkLimit
+        """;
+
+    private static readonly string LegacyForwardSql = $"""
+        SELECT c.id, c.start_line, c.end_line, c.chunk_index
+        FROM chunks c INDEXED BY {DbReader.LegacyBoundedResourceReadFileIndexName}
+        WHERE c.file_id = @fileId
+          AND c.content IS NOT NULL
+          AND c.start_line > @startLine
+          AND c.start_line <= @endLine
+        ORDER BY c.start_line, c.chunk_index
+        LIMIT @chunkLimit
+        """;
+
+    private readonly SqliteConnection _connection;
+    private readonly CancellationToken _cancellation;
+    private readonly bool _hasChunksTable;
+    private readonly IReadOnlySet<string> _chunkIndexes;
+    private readonly int? _legacyVmStepLimitOverride;
+
+    internal BoundedIndexedChunkSelector(
+        SqliteConnection connection,
+        CancellationToken cancellation,
+        bool hasChunksTable,
+        IReadOnlySet<string> chunkIndexes,
+        int? legacyVmStepLimitOverride)
+    {
+        _connection = connection;
+        _cancellation = cancellation;
+        _hasChunksTable = hasChunksTable;
+        _chunkIndexes = chunkIndexes;
+        _legacyVmStepLimitOverride = legacyVmStepLimitOverride;
+    }
+
+    internal IReadOnlyList<BoundedIndexedChunk>? Select(
+        BoundedIndexedContentContext context,
+        out BoundedIndexedContentFailure? failure)
+    {
+        failure = ValidateFileMetadata(context);
+        if (failure != null)
+            return null;
+
+        var queryMode = ResolveChunkQueryMode(context.File.Id, out failure);
+        if (failure != null)
+            return null;
+        if (context.NextLine > context.EffectiveEndLine)
+        {
+            failure = new BoundedIndexedContentFailure(BoundedFileReadStatus.InvalidContinuation);
+            return null;
+        }
+
+        return SelectChunks(context, queryMode, out failure);
+    }
+
+    private BoundedIndexedContentFailure? ValidateFileMetadata(BoundedIndexedContentContext context)
+    {
+        var file = context.File;
+        if (file.Size < 0 || file.Lines < 0 || (file.Size == 0 && file.Lines > 0))
+        {
+            return new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.InvalidTopology,
+                "resource_file_metadata_inconsistent");
+        }
+        if (file.Lines != 0)
+            return null;
+
+        if (_hasChunksTable && HasAnyResourceChunk(file.Id))
+        {
+            return new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.InvalidTopology,
+                "resource_file_metadata_inconsistent");
+        }
+        if (DbReader.IsAffirmativelyEmptyIndexedFile(file.Lines, file.Checksum))
+            return new BoundedIndexedContentFailure(BoundedFileReadStatus.Empty);
+        if (file.Size == 0 && file.Checksum != null)
+        {
+            return new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.InvalidTopology,
+                "resource_file_metadata_inconsistent");
+        }
+        return new BoundedIndexedContentFailure(
+            BoundedFileReadStatus.ContentUnavailable,
+            "resource_content_unavailable");
+    }
+
+    private ChunkQueryMode ResolveChunkQueryMode(
+        long fileId,
+        out BoundedIndexedContentFailure? failure)
+    {
+        if (!_hasChunksTable)
+        {
+            failure = new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.ContentUnavailable,
+                "resource_content_unavailable");
+            return default;
+        }
+
+        var hasBoundedIndexes = _chunkIndexes.Contains(DbReader.BoundedResourceReadChunkIndexName)
+                                && _chunkIndexes.Contains(DbReader.BoundedResourceReadChunkEndIndexName);
+        var mode = hasBoundedIndexes
+            ? ChunkQueryMode.Bounded
+            : _chunkIndexes.Contains(DbReader.LegacyBoundedResourceReadFileIndexName)
+                ? ChunkQueryMode.Legacy
+                : ChunkQueryMode.Unavailable;
+        if (mode == ChunkQueryMode.Unavailable)
+        {
+            failure = new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.ContentUnavailable,
+                "resource_bounded_read_index_unavailable");
+            return mode;
+        }
+        if (!TryHasNullResourceChunkBoundary(fileId, mode, out var hasNullBoundary))
+        {
+            failure = new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.ContentUnavailable,
+                "resource_bounded_read_index_unavailable");
+            return mode;
+        }
+        if (hasNullBoundary)
+        {
+            failure = new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.InvalidTopology,
+                "resource_chunk_topology_invalid");
+            return mode;
+        }
+
+        failure = null;
+        return mode;
+    }
+
+    private IReadOnlyList<BoundedIndexedChunk>? SelectChunks(
+        BoundedIndexedContentContext context,
+        ChunkQueryMode queryMode,
+        out BoundedIndexedContentFailure? failure)
+    {
+        var scanEndLine = (int)Math.Min(
+            context.EffectiveEndLine,
+            (long)context.NextLine + context.MaxLines - 1L);
+        var candidates = new ChunkCandidateSet();
+
+        failure = ReadCoveringCandidates(context, scanEndLine, queryMode, candidates);
+        if (failure != null)
+            return null;
+
+        ReadForwardCandidates(context, scanEndLine, queryMode, candidates);
+        return FinalizeChunkSelection(context, queryMode, candidates, out failure);
+    }
+
+    private BoundedIndexedContentFailure? ReadCoveringCandidates(
+        BoundedIndexedContentContext context,
+        int scanEndLine,
+        ChunkQueryMode queryMode,
+        ChunkCandidateSet candidates)
+    {
+        var predecessorCount = ReadChunkCandidates(
+            context,
+            scanEndLine,
+            queryMode,
+            candidates,
+            queryMode == ChunkQueryMode.Legacy ? LegacyPredecessorSql : DbReader.BoundedResourceReadPredecessorSql,
+            includeEndLine: false);
+        if (candidates.IndexUnavailable)
+            return IndexUnavailableFailure();
+
+        if (candidates.TopologyFailure != null
+            || candidates.Chunks.Count > DbReader.MaxBoundedFileReadChunks
+            || candidates.Covers(context.NextLine)
+            || predecessorCount <= DbReader.MaxBoundedFileReadChunks)
+        {
+            return null;
+        }
+
+        var endCount = ReadChunkCandidates(
+            context,
+            scanEndLine,
+            queryMode,
+            candidates,
+            queryMode == ChunkQueryMode.Legacy ? LegacyEndSql : DbReader.BoundedResourceReadEndSql,
+            includeEndLine: false);
+        if (candidates.IndexUnavailable)
+            return IndexUnavailableFailure();
+        if (candidates.TopologyFailure == null
+            && !candidates.Covers(context.NextLine)
+            && endCount > DbReader.MaxBoundedFileReadChunks)
+        {
+            return new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.InvalidTopology,
+                "chunk_candidate_scan_limit_exceeded");
+        }
+        return null;
+    }
+
+    private void ReadForwardCandidates(
+        BoundedIndexedContentContext context,
+        int scanEndLine,
+        ChunkQueryMode queryMode,
+        ChunkCandidateSet candidates)
+    {
+        if (candidates.TopologyFailure != null
+            || candidates.Chunks.Count > DbReader.MaxBoundedFileReadChunks)
+        {
+            return;
+        }
+
+        ReadChunkCandidates(
+            context,
+            scanEndLine,
+            queryMode,
+            candidates,
+            queryMode == ChunkQueryMode.Legacy ? LegacyForwardSql : DbReader.BoundedResourceReadForwardSql,
+            includeEndLine: true);
+    }
+
+    private IReadOnlyList<BoundedIndexedChunk>? FinalizeChunkSelection(
+        BoundedIndexedContentContext context,
+        ChunkQueryMode queryMode,
+        ChunkCandidateSet candidates,
+        out BoundedIndexedContentFailure? failure)
+    {
+        if (candidates.IndexUnavailable)
+            return Fail(IndexUnavailableFailure(), out failure);
+        if (candidates.TopologyFailure != null)
+        {
+            return Fail(
+                new BoundedIndexedContentFailure(
+                    BoundedFileReadStatus.InvalidTopology,
+                    candidates.TopologyFailure),
+                out failure);
+        }
+        if (candidates.Chunks.Count > DbReader.MaxBoundedFileReadChunks)
+        {
+            return Fail(
+                new BoundedIndexedContentFailure(BoundedFileReadStatus.InvalidTopology, "chunk_limit_exceeded"),
+                out failure);
+        }
+
+        candidates.Chunks.Sort(static (left, right) =>
+        {
+            var byStartLine = left.StartLine.CompareTo(right.StartLine);
+            return byStartLine != 0 ? byStartLine : left.ChunkIndex.CompareTo(right.ChunkIndex);
+        });
+        if (candidates.Chunks.Count != 0)
+        {
+            failure = null;
+            return candidates.Chunks;
+        }
+
+        if (!TryHasAnyStoredResourceChunk(context.File.Id, queryMode, out var hasStoredChunk))
+            return Fail(IndexUnavailableFailure(), out failure);
+        var emptyFailure = hasStoredChunk
+            ? new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.IncompleteCoverage,
+                "resource_chunk_coverage_incomplete")
+            : new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.ContentUnavailable,
+                "resource_content_unavailable");
+        return Fail(emptyFailure, out failure);
+    }
+
+    private static IReadOnlyList<BoundedIndexedChunk>? Fail(
+        BoundedIndexedContentFailure value,
+        out BoundedIndexedContentFailure? failure)
+    {
+        failure = value;
+        return null;
+    }
+
+    private static BoundedIndexedContentFailure IndexUnavailableFailure()
+        => new(
+            BoundedFileReadStatus.ContentUnavailable,
+            "resource_bounded_read_index_unavailable");
+
+    private int ReadChunkCandidates(
+        BoundedIndexedContentContext context,
+        int scanEndLine,
+        ChunkQueryMode queryMode,
+        ChunkCandidateSet candidates,
+        string commandText,
+        bool includeEndLine)
+    {
+        int ExecuteQuery()
+            => ExecuteChunkCandidateQuery(
+                context,
+                scanEndLine,
+                candidates,
+                commandText,
+                includeEndLine);
+
+        if (queryMode != ChunkQueryMode.Legacy)
+            return ExecuteQuery();
+        if (TryRunLegacyResourceMetadataQuery(ExecuteQuery, out var candidateCount))
+            return candidateCount;
+
+        candidates.IndexUnavailable = true;
+        return 0;
+    }
+
+    private int ExecuteChunkCandidateQuery(
+        BoundedIndexedContentContext context,
+        int scanEndLine,
+        ChunkCandidateSet candidates,
+        string commandText,
+        bool includeEndLine)
+    {
+        using var command = _connection.CreateCommand();
+        command.CommandText = commandText;
+        SqliteCommandPolicy.AddInt64(command, "@fileId", context.File.Id);
+        SqliteCommandPolicy.AddInt32(command, "@startLine", context.NextLine);
+        if (includeEndLine)
+            SqliteCommandPolicy.AddInt32(command, "@endLine", scanEndLine);
+        SqliteCommandPolicy.AddInt32(command, "@chunkLimit", DbReader.MaxBoundedFileReadChunks + 1);
+
+        var rawCandidateCount = 0;
+        using var reader = command.ExecuteTrackedReader();
+        while (reader.TrackedRead())
+        {
+            rawCandidateCount++;
+            _cancellation.ThrowIfCancellationRequested();
+            if (!TryReadChunkCandidate(reader, candidates, out var chunk))
+                break;
+            if (chunk.EndLine < context.NextLine || chunk.StartLine > scanEndLine)
+                continue;
+
+            if (candidates.RowIds.Add(chunk.RowId))
+                candidates.Chunks.Add(chunk);
+            if (candidates.Chunks.Count > DbReader.MaxBoundedFileReadChunks)
+                break;
+        }
+        return rawCandidateCount;
+    }
+
+    private static bool TryReadChunkCandidate(
+        SqliteDataReader reader,
+        ChunkCandidateSet candidates,
+        out BoundedIndexedChunk chunk)
+    {
+        if (reader.IsDBNull(1) || reader.IsDBNull(2) || reader.IsDBNull(3))
+        {
+            candidates.TopologyFailure = "resource_chunk_topology_invalid";
+            chunk = default;
+            return false;
+        }
+
+        chunk = new BoundedIndexedChunk(
+            reader.GetInt64(0),
+            reader.GetInt32(1),
+            reader.GetInt32(2),
+            reader.GetInt32(3));
+        if (chunk.StartLine > 0 && chunk.EndLine >= chunk.StartLine && chunk.ChunkIndex >= 0)
+            return true;
+
+        candidates.TopologyFailure = "resource_chunk_topology_invalid";
+        return false;
+    }
+
+    private bool HasAnyResourceChunk(long fileId)
+    {
+        _cancellation.ThrowIfCancellationRequested();
+        using var command = _connection.CreateCommand();
+        command.CommandText = "SELECT 1 FROM chunks WHERE file_id = @fileId LIMIT 1";
+        SqliteCommandPolicy.AddInt64(command, "@fileId", fileId);
+        var hasChunk = command.ExecuteScalar() != null;
+        _cancellation.ThrowIfCancellationRequested();
+        return hasChunk;
+    }
+
+    private bool TryHasAnyStoredResourceChunk(
+        long fileId,
+        ChunkQueryMode queryMode,
+        out bool hasChunk)
+    {
+        bool ExecuteQuery()
+        {
+            _cancellation.ThrowIfCancellationRequested();
+            using var command = _connection.CreateCommand();
+            var indexName = queryMode == ChunkQueryMode.Legacy
+                ? DbReader.LegacyBoundedResourceReadFileIndexName
+                : DbReader.BoundedResourceReadChunkIndexName;
+            command.CommandText = $"""
+                SELECT 1
+                FROM chunks INDEXED BY {indexName}
+                WHERE file_id = @fileId AND content IS NOT NULL
+                LIMIT 1
+                """;
+            SqliteCommandPolicy.AddInt64(command, "@fileId", fileId);
+            var result = command.ExecuteScalar() != null;
+            _cancellation.ThrowIfCancellationRequested();
+            return result;
+        }
+
+        if (queryMode != ChunkQueryMode.Legacy)
+        {
+            hasChunk = ExecuteQuery();
+            return true;
+        }
+        return TryRunLegacyResourceMetadataQuery(ExecuteQuery, out hasChunk);
+    }
+
+    private bool TryHasNullResourceChunkBoundary(
+        long fileId,
+        ChunkQueryMode queryMode,
+        out bool hasNullBoundary)
+    {
+        bool ExecuteQuery()
+        {
+            var startIndexName = queryMode == ChunkQueryMode.Legacy
+                ? DbReader.LegacyBoundedResourceReadFileIndexName
+                : DbReader.BoundedResourceReadChunkIndexName;
+            var endIndexName = queryMode == ChunkQueryMode.Legacy
+                ? DbReader.LegacyBoundedResourceReadFileIndexName
+                : DbReader.BoundedResourceReadChunkEndIndexName;
+            _cancellation.ThrowIfCancellationRequested();
+            var result = ResourceChunkExists($"""
+                SELECT 1
+                FROM chunks INDEXED BY {startIndexName}
+                WHERE file_id = @fileId
+                  AND content IS NOT NULL
+                  AND start_line IS NULL
+                LIMIT 1
+                """, fileId) || ResourceChunkExists($"""
+                SELECT 1
+                FROM chunks INDEXED BY {endIndexName}
+                WHERE file_id = @fileId
+                  AND content IS NOT NULL
+                  AND end_line IS NULL
+                LIMIT 1
+                """, fileId);
+            _cancellation.ThrowIfCancellationRequested();
+            return result;
+        }
+
+        if (queryMode != ChunkQueryMode.Legacy)
+        {
+            hasNullBoundary = ExecuteQuery();
+            return true;
+        }
+        return TryRunLegacyResourceMetadataQuery(ExecuteQuery, out hasNullBoundary);
+    }
+
+    private bool ResourceChunkExists(string commandText, long fileId)
+    {
+        using var command = _connection.CreateCommand();
+        command.CommandText = commandText;
+        SqliteCommandPolicy.AddInt64(command, "@fileId", fileId);
+        return command.ExecuteScalar() != null;
+    }
+
+    private bool TryRunLegacyResourceMetadataQuery<T>(Func<T> action, out T result)
+    {
+        var maxVmSteps = _legacyVmStepLimitOverride ?? DbReader.MaxLegacyResourceReadSqliteVmSteps;
+        maxVmSteps = Math.Clamp(maxVmSteps, 1, DbReader.MaxLegacyResourceReadSqliteVmSteps);
+        var callbackLimit = Math.Max(1, (maxVmSteps + LegacyResourceReadProgressOperations - 1)
+                                        / LegacyResourceReadProgressOperations);
+        var callbackCount = 0;
+        var budgetExceeded = false;
+        SQLitePCL.delegate_progress progress = _ =>
+        {
+            callbackCount++;
+            if (callbackCount <= callbackLimit)
+                return 0;
+
+            budgetExceeded = true;
+            return 1;
+        };
+
+        SQLitePCL.raw.sqlite3_progress_handler(
+            _connection.Handle,
+            LegacyResourceReadProgressOperations,
+            progress,
+            null!);
+        try
+        {
+            result = action();
+            return true;
+        }
+        catch (SqliteException exception) when (
+            budgetExceeded
+            && !_cancellation.IsCancellationRequested
+            && exception.SqliteErrorCode == 9)
+        {
+            result = default!;
+            return false;
+        }
+        finally
+        {
+            SQLitePCL.raw.sqlite3_progress_handler(_connection.Handle, 0, null!, null!);
+            GC.KeepAlive(progress);
+        }
+    }
+
+    private enum ChunkQueryMode
+    {
+        Unavailable,
+        Bounded,
+        Legacy,
+    }
+
+    private sealed class ChunkCandidateSet
+    {
+        internal List<BoundedIndexedChunk> Chunks { get; } = [];
+        internal HashSet<long> RowIds { get; } = [];
+        internal string? TopologyFailure { get; set; }
+        internal bool IndexUnavailable { get; set; }
+
+        internal bool Covers(int line)
+            => Chunks.Any(chunk => chunk.StartLine <= line && chunk.EndLine >= line);
+    }
+}
diff --git a/src/CodeIndex/Database/BoundedIndexedContentReader.cs b/src/CodeIndex/Database/BoundedIndexedContentReader.cs
new file mode 100644
index 000000000..a95f0940b
--- /dev/null
+++ b/src/CodeIndex/Database/BoundedIndexedContentReader.cs
@@ -0,0 +1,188 @@
+using CodeIndex.Indexer;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+internal readonly record struct BoundedIndexedContentRequest(
+    ResourceFileMetadata File,
+    int StartLine,
+    int EndLine,
+    int MaxUtf8Bytes,
+    int MaxLines,
+    int? ContinuationLine,
+    int ContinuationByteOffset);
+
+internal readonly record struct BoundedIndexedContentFailure(
+    BoundedFileReadStatus Status,
+    string? Reason = null);
+
+internal sealed record BoundedIndexedContentContext(
+    ResourceFileMetadata File,
+    int StartLine,
+    int EndLine,
+    int MaxUtf8Bytes,
+    int MaxLines,
+    int NextLine,
+    int ContinuationByteOffset)
+{
+    internal int EffectiveEndLine => Math.Min(EndLine, File.Lines);
+}
+
+internal readonly record struct BoundedIndexedChunk(
+    long RowId,
+    int StartLine,
+    int EndLine,
+    int ChunkIndex);
+
+internal sealed class BoundedIndexedContentReader
+{
+    private readonly BoundedIndexedChunkSelector _chunkSelector;
+    private readonly BoundedUtf8ContentDecoder _decoder;
+
+    internal BoundedIndexedContentReader(
+        SqliteConnection connection,
+        CancellationToken cancellation,
+        bool hasChunksTable,
+        IReadOnlySet<string> chunkIndexes,
+        int? scanByteLimitOverride,
+        int? legacyVmStepLimitOverride)
+    {
+        _chunkSelector = new BoundedIndexedChunkSelector(
+            connection,
+            cancellation,
+            hasChunksTable,
+            chunkIndexes,
+            legacyVmStepLimitOverride);
+        _decoder = new BoundedUtf8ContentDecoder(
+            connection,
+            cancellation,
+            scanByteLimitOverride);
+    }
+
+    internal BoundedFileReadResult Read(BoundedIndexedContentRequest request)
+    {
+        var context = NormalizeRequest(request, out var earlyResult);
+        if (context == null)
+            return earlyResult!;
+
+        var chunks = _chunkSelector.Select(context, out var selectionFailure);
+        if (selectionFailure is { } failure)
+            return CreateResult(context, failure.Status, failure.Reason);
+
+        var decoded = _decoder.Decode(context, chunks!);
+        return BuildDecodedResult(context, decoded);
+    }
+
+    private static BoundedIndexedContentContext? NormalizeRequest(
+        BoundedIndexedContentRequest request,
+        out BoundedFileReadResult? earlyResult)
+    {
+        var path = request.File.Path;
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            earlyResult = new BoundedFileReadResult { Status = BoundedFileReadStatus.FileNotFound };
+            return null;
+        }
+
+        ValidateBudgets(request);
+        if (!request.ContinuationLine.HasValue && request.ContinuationByteOffset != 0)
+        {
+            earlyResult = CreateInvalidContinuationResult(path);
+            return null;
+        }
+
+        var startLine = Math.Max(1, request.StartLine);
+        var endLine = Math.Max(startLine, request.EndLine);
+        var nextLine = request.ContinuationLine ?? startLine;
+        if (nextLine < startLine || nextLine > endLine)
+        {
+            earlyResult = CreateInvalidContinuationResult(path);
+            return null;
+        }
+
+        earlyResult = null;
+        return new BoundedIndexedContentContext(
+            request.File,
+            startLine,
+            endLine,
+            request.MaxUtf8Bytes,
+            request.MaxLines,
+            nextLine,
+            request.ContinuationByteOffset);
+    }
+
+    private static void ValidateBudgets(BoundedIndexedContentRequest request)
+    {
+        if (request.MaxUtf8Bytes is <= 0 or > DbReader.MaxBoundedFileReadUtf8Bytes)
+        {
+            throw new ArgumentOutOfRangeException(
+                "maxUtf8Bytes",
+                request.MaxUtf8Bytes,
+                $"UTF-8 byte budget must be between 1 and {DbReader.MaxBoundedFileReadUtf8Bytes}.");
+        }
+        if (request.MaxLines is <= 0 or > DbReader.MaxBoundedFileReadLines)
+        {
+            throw new ArgumentOutOfRangeException(
+                "maxLines",
+                request.MaxLines,
+                $"Line budget must be between 1 and {DbReader.MaxBoundedFileReadLines}.");
+        }
+        if (request.ContinuationByteOffset < 0)
+        {
+            throw new ArgumentOutOfRangeException(
+                "continuationByteOffset",
+                request.ContinuationByteOffset,
+                "Continuation byte offset must be non-negative.");
+        }
+    }
+
+    private static BoundedFileReadResult CreateInvalidContinuationResult(string path)
+        => new()
+        {
+            Status = BoundedFileReadStatus.InvalidContinuation,
+            Path = path,
+        };
+
+    private static BoundedFileReadResult BuildDecodedResult(
+        BoundedIndexedContentContext context,
+        BoundedUtf8DecodeResult decoded)
+    {
+        if (decoded.Failure is { } failure)
+            return CreateResult(context, failure.Status, failure.Reason);
+
+        return new BoundedFileReadResult
+        {
+            Status = BoundedFileReadStatus.Success,
+            Path = context.File.Path,
+            Lang = context.File.Lang,
+            TotalLines = context.File.Lines,
+            RequestedStartLine = context.StartLine,
+            RequestedEndLine = context.EndLine,
+            StartLine = decoded.FirstReturnedLine ?? context.NextLine,
+            EndLine = decoded.LastReturnedLine ?? context.NextLine,
+            Content = decoded.Content.ToString(),
+            Utf8Bytes = decoded.Utf8Bytes,
+            Truncated = decoded.TruncationReason != null,
+            TruncationReason = decoded.TruncationReason,
+            NextLine = decoded.TruncationReason != null ? decoded.NextLine : null,
+            NextByteOffset = decoded.TruncationReason != null ? decoded.NextByteOffset : null,
+        };
+    }
+
+    private static BoundedFileReadResult CreateResult(
+        BoundedIndexedContentContext context,
+        BoundedFileReadStatus status,
+        string? failureReason = null)
+        => new()
+        {
+            Status = status,
+            FailureReason = failureReason,
+            Path = context.File.Path,
+            Lang = context.File.Lang,
+            TotalLines = context.File.Lines,
+            RequestedStartLine = context.StartLine,
+            RequestedEndLine = context.EndLine,
+            StartLine = context.NextLine,
+            EndLine = context.NextLine,
+        };
+}
diff --git a/src/CodeIndex/Database/BoundedUtf8ContentDecoder.cs b/src/CodeIndex/Database/BoundedUtf8ContentDecoder.cs
new file mode 100644
index 000000000..c6eca7c7c
--- /dev/null
+++ b/src/CodeIndex/Database/BoundedUtf8ContentDecoder.cs
@@ -0,0 +1,496 @@
+using System.Buffers;
+using System.Text;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+internal sealed record BoundedUtf8DecodeResult(
+    StringBuilder Content,
+    BoundedIndexedContentFailure? Failure,
+    int NextLine,
+    int NextByteOffset,
+    int Utf8Bytes,
+    int? FirstReturnedLine,
+    int? LastReturnedLine,
+    string? TruncationReason);
+
+internal sealed class BoundedUtf8ContentDecoder
+{
+    private const int ReadBufferSize = 4 * 1024;
+
+    private readonly SqliteConnection _connection;
+    private readonly CancellationToken _cancellation;
+    private readonly int? _scanByteLimitOverride;
+
+    internal BoundedUtf8ContentDecoder(
+        SqliteConnection connection,
+        CancellationToken cancellation,
+        int? scanByteLimitOverride)
+    {
+        _connection = connection;
+        _cancellation = cancellation;
+        _scanByteLimitOverride = scanByteLimitOverride;
+    }
+
+    internal BoundedUtf8DecodeResult Decode(
+        BoundedIndexedContentContext context,
+        IReadOnlyList<BoundedIndexedChunk> chunks)
+    {
+        var state = new ReadState(context.NextLine, context.ContinuationByteOffset);
+        var scanByteLimit = _scanByteLimitOverride ?? DbReader.MaxBoundedFileReadScannedUtf8Bytes;
+        if (scanByteLimit <= 0 || scanByteLimit > DbReader.MaxBoundedFileReadScannedUtf8Bytes)
+            scanByteLimit = DbReader.MaxBoundedFileReadScannedUtf8Bytes;
+        var settings = new ChunkDecodeSettings(
+            context.EffectiveEndLine,
+            context.MaxUtf8Bytes,
+            context.MaxLines,
+            scanByteLimit,
+            _cancellation);
+        var content = new StringBuilder(Math.Min(context.MaxUtf8Bytes, ReadBufferSize));
+        var buffer = ArrayPool<byte>.Shared.Rent(ReadBufferSize);
+        try
+        {
+            DecodeChunks(chunks, settings, content, buffer, ref state);
+        }
+        catch (BoundedFileScanLimitException)
+        {
+            state.ScanLimitExceeded = true;
+        }
+        catch (InvalidDataException)
+        {
+            state.InvalidTopologyReason = "invalid_utf8_content";
+        }
+        finally
+        {
+            // Indexed source may contain secrets. Clear the entire pooled array before reuse.
+            // index済みsourceにsecretが含まれうるため、poolへ戻す前に配列全体を消去する。
+            ArrayPool<byte>.Shared.Return(buffer, clearArray: true);
+        }
+        return CreateResult(content, state);
+    }
+
+    private void DecodeChunks(
+        IReadOnlyList<BoundedIndexedChunk> chunks,
+        ChunkDecodeSettings settings,
+        StringBuilder content,
+        byte[] buffer,
+        ref ReadState state)
+    {
+        foreach (var chunk in chunks)
+        {
+            _cancellation.ThrowIfCancellationRequested();
+            if (state.Stopped)
+                break;
+            if (chunk.EndLine < state.NextLine)
+                continue;
+            if (chunk.StartLine > state.NextLine)
+            {
+                state.IncompleteCoverage = true;
+                break;
+            }
+
+            using var blob = new SqliteBlob(_connection, "chunks", "content", chunk.RowId, readOnly: true);
+            ReadBoundedChunk(blob, chunk, settings, content, buffer, ref state);
+        }
+    }
+
+    private static BoundedUtf8DecodeResult CreateResult(StringBuilder content, ReadState state)
+    {
+        BoundedIndexedContentFailure? failure = null;
+        if (state.ScanLimitExceeded)
+        {
+            failure = new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.InvalidTopology,
+                "scan_limit_exceeded");
+        }
+        else if (state.InvalidTopologyReason != null)
+        {
+            failure = new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.InvalidTopology,
+                state.InvalidTopologyReason);
+        }
+        else if (state.InvalidContinuation)
+        {
+            failure = new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.InvalidContinuation,
+                "invalid_continuation");
+        }
+        else if (state.IncompleteCoverage || (!state.Completed && state.TruncationReason == null))
+        {
+            failure = new BoundedIndexedContentFailure(
+                BoundedFileReadStatus.IncompleteCoverage,
+                "resource_chunk_coverage_incomplete");
+        }
+
+        return new BoundedUtf8DecodeResult(
+            content,
+            failure,
+            state.NextLine,
+            state.NextByteOffset,
+            state.Utf8Bytes,
+            state.FirstReturnedLine,
+            state.LastReturnedLine,
+            state.TruncationReason);
+    }
+
+    private static void ReadBoundedChunk(
+        SqliteBlob blob,
+        BoundedIndexedChunk chunk,
+        ChunkDecodeSettings settings,
+        StringBuilder content,
+        byte[] buffer,
+        ref ReadState state)
+    {
+        var cursor = new ChunkReadCursor(chunk.StartLine);
+        Span<byte> runeBytes = stackalloc byte[4];
+        Span<char> runeChars = stackalloc char[2];
+        while (TryReadBlobByte(
+                   blob,
+                   buffer,
+                   settings.MaxScannedUtf8Bytes,
+                   settings.CancellationToken,
+                   ref cursor,
+                   ref state,
+                   out var firstByte))
+        {
+            if (!ProcessChunkByte(
+                    blob,
+                    chunk,
+                    firstByte,
+                    settings,
+                    content,
+                    buffer,
+                    runeBytes,
+                    runeChars,
+                    ref cursor,
+                    ref state))
+            {
+                return;
+            }
+        }
+
+        CompleteChunkFinalLine(chunk, settings, content, cursor, ref state);
+    }
+
+    private static bool ProcessChunkByte(
+        SqliteBlob blob,
+        BoundedIndexedChunk chunk,
+        byte firstByte,
+        ChunkDecodeSettings settings,
+        StringBuilder content,
+        byte[] buffer,
+        Span<byte> runeBytes,
+        Span<char> runeChars,
+        ref ChunkReadCursor cursor,
+        ref ReadState state)
+    {
+        if (cursor.LocalLine > chunk.EndLine)
+            return false;
+        if (cursor.LocalLine < state.NextLine)
+        {
+            AdvanceSkippedByte(firstByte, ref cursor);
+            return true;
+        }
+        if (cursor.LocalLine > state.NextLine)
+        {
+            state.InvalidContinuation = true;
+            return false;
+        }
+        if (firstByte == (byte)'\n')
+            return ProcessLineBreak(settings, content, ref cursor, ref state);
+        return ProcessRune(
+            blob,
+            firstByte,
+            settings,
+            content,
+            buffer,
+            runeBytes,
+            runeChars,
+            ref cursor,
+            ref state);
+    }
+
+    private static void AdvanceSkippedByte(byte value, ref ChunkReadCursor cursor)
+    {
+        if (value == (byte)'\n')
+        {
+            cursor.LocalLine++;
+            cursor.LocalByteOffset = 0;
+        }
+        else
+        {
+            cursor.LocalByteOffset++;
+        }
+    }
+
+    private static bool ProcessLineBreak(
+        ChunkDecodeSettings settings,
+        StringBuilder content,
+        ref ChunkReadCursor cursor,
+        ref ReadState state)
+    {
+        if (state.NextByteOffset != cursor.LocalByteOffset)
+        {
+            state.InvalidContinuation = true;
+            return false;
+        }
+        if (!CompleteBoundedLine(
+                cursor.LocalLine,
+                cursor.LocalByteOffset,
+                settings,
+                content,
+                ref state))
+        {
+            return false;
+        }
+
+        cursor.LocalLine++;
+        cursor.LocalByteOffset = 0;
+        return true;
+    }
+
+    private static bool ProcessRune(
+        SqliteBlob blob,
+        byte firstByte,
+        ChunkDecodeSettings settings,
+        StringBuilder content,
+        byte[] buffer,
+        Span<byte> runeBytes,
+        Span<char> runeChars,
+        ref ChunkReadCursor cursor,
+        ref ReadState state)
+    {
+        var runeByteCount = ReadUtf8Rune(
+            blob,
+            firstByte,
+            buffer,
+            settings.MaxScannedUtf8Bytes,
+            settings.CancellationToken,
+            runeBytes,
+            ref cursor,
+            ref state,
+            out var rune);
+        var scalarStartOffset = cursor.LocalByteOffset;
+        cursor.LocalByteOffset += runeByteCount;
+        if (scalarStartOffset < state.NextByteOffset)
+        {
+            if (cursor.LocalByteOffset > state.NextByteOffset)
+                state.InvalidContinuation = true;
+            return !state.InvalidContinuation;
+        }
+        if (scalarStartOffset != state.NextByteOffset)
+        {
+            state.InvalidContinuation = true;
+            return false;
+        }
+        if (state.Utf8Bytes > settings.MaxUtf8Bytes - runeByteCount)
+        {
+            state.TruncationReason = "max_bytes";
+            return false;
+        }
+        if (!TryEnterBoundedLine(cursor.LocalLine, settings.MaxLines, ref state))
+            return false;
+
+        var runeCharCount = rune.EncodeToUtf16(runeChars);
+        content.Append(runeChars[..runeCharCount]);
+        state.Utf8Bytes += runeByteCount;
+        state.NextByteOffset = cursor.LocalByteOffset;
+        return true;
+    }
+
+    private static void CompleteChunkFinalLine(
+        BoundedIndexedChunk chunk,
+        ChunkDecodeSettings settings,
+        StringBuilder content,
+        ChunkReadCursor cursor,
+        ref ReadState state)
+    {
+        // Persisted chunks omit the separator after their final line. Treat blob EOF as
+        // that line boundary and synthesize exactly one LF when the requested range continues.
+        // 永続化chunkは最終行後のseparatorを持たないため、blob EOFを行境界として扱い、
+        // 要求範囲が続く場合だけLFを1つ合成する。
+        if (state.Stopped || cursor.LocalLine > chunk.EndLine || cursor.LocalLine != state.NextLine)
+            return;
+        if (state.NextByteOffset != cursor.LocalByteOffset)
+        {
+            state.InvalidContinuation = true;
+            return;
+        }
+
+        _ = CompleteBoundedLine(
+            cursor.LocalLine,
+            cursor.LocalByteOffset,
+            settings,
+            content,
+            ref state);
+    }
+
+    private static bool CompleteBoundedLine(
+        int line,
+        int lineByteLength,
+        ChunkDecodeSettings settings,
+        StringBuilder content,
+        ref ReadState state)
+    {
+        if (!TryEnterBoundedLine(line, settings.MaxLines, ref state))
+            return false;
+        if (line >= settings.EffectiveEndLine)
+        {
+            state.Completed = true;
+            return false;
+        }
+        if (state.Utf8Bytes >= settings.MaxUtf8Bytes)
+        {
+            state.NextLine = line;
+            state.NextByteOffset = lineByteLength;
+            state.TruncationReason = "max_bytes";
+            return false;
+        }
+
+        content.Append('\n');
+        state.Utf8Bytes++;
+        state.NextLine = line + 1;
+        state.NextByteOffset = 0;
+        if (state.ReturnedLineCount >= settings.MaxLines)
+        {
+            state.TruncationReason = "max_lines";
+            return false;
+        }
+        return true;
+    }
+
+    private static bool TryEnterBoundedLine(
+        int line,
+        int maxLines,
+        ref ReadState state)
+    {
+        if (state.LastReturnedLine == line)
+            return true;
+        if (state.ReturnedLineCount >= maxLines)
+        {
+            state.TruncationReason = "max_lines";
+            return false;
+        }
+
+        state.FirstReturnedLine ??= line;
+        state.LastReturnedLine = line;
+        state.ReturnedLineCount++;
+        return true;
+    }
+
+    private static int ReadUtf8Rune(
+        SqliteBlob blob,
+        byte firstByte,
+        byte[] buffer,
+        int maxScannedUtf8Bytes,
+        CancellationToken cancellationToken,
+        Span<byte> runeBytes,
+        ref ChunkReadCursor cursor,
+        ref ReadState state,
+        out Rune rune)
+    {
+        var byteCount = firstByte switch
+        {
+            <= 0x7f => 1,
+            >= 0xc2 and <= 0xdf => 2,
+            >= 0xe0 and <= 0xef => 3,
+            >= 0xf0 and <= 0xf4 => 4,
+            _ => throw new InvalidDataException("Indexed chunk contains invalid UTF-8."),
+        };
+        runeBytes[0] = firstByte;
+        for (var index = 1; index < byteCount; index++)
+        {
+            if (!TryReadBlobByte(
+                    blob,
+                    buffer,
+                    maxScannedUtf8Bytes,
+                    cancellationToken,
+                    ref cursor,
+                    ref state,
+                    out runeBytes[index]))
+            {
+                throw new InvalidDataException("Indexed chunk ends inside a UTF-8 scalar value.");
+            }
+        }
+
+        var status = Rune.DecodeFromUtf8(runeBytes[..byteCount], out rune, out var bytesConsumed);
+        if (status != OperationStatus.Done || bytesConsumed != byteCount)
+            throw new InvalidDataException("Indexed chunk contains invalid UTF-8.");
+        return byteCount;
+    }
+
+    private static bool TryReadBlobByte(
+        SqliteBlob blob,
+        byte[] buffer,
+        int maxScannedUtf8Bytes,
+        CancellationToken cancellationToken,
+        ref ChunkReadCursor cursor,
+        ref ReadState state,
+        out byte value)
+    {
+        if (cursor.BufferOffset >= cursor.BufferedBytes)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            if (blob.Position >= blob.Length)
+            {
+                value = 0;
+                return false;
+            }
+            var remaining = maxScannedUtf8Bytes - state.ScannedUtf8Bytes;
+            if (remaining <= 0)
+                throw new BoundedFileScanLimitException();
+            cursor.BufferedBytes = blob.Read(buffer, 0, Math.Min(buffer.Length, remaining));
+            cursor.BufferOffset = 0;
+            if (cursor.BufferedBytes == 0)
+            {
+                value = 0;
+                return false;
+            }
+        }
+
+        value = buffer[cursor.BufferOffset++];
+        state.ScannedUtf8Bytes++;
+        return true;
+    }
+
+    private readonly record struct ChunkDecodeSettings(
+        int EffectiveEndLine,
+        int MaxUtf8Bytes,
+        int MaxLines,
+        int MaxScannedUtf8Bytes,
+        CancellationToken CancellationToken);
+
+    private sealed class BoundedFileScanLimitException : Exception;
+
+    private struct ChunkReadCursor(int localLine)
+    {
+        internal int BufferOffset;
+        internal int BufferedBytes;
+        internal int LocalLine = localLine;
+        internal int LocalByteOffset;
+    }
+
+    private struct ReadState(int nextLine, int nextByteOffset)
+    {
+        internal int NextLine = nextLine;
+        internal int NextByteOffset = nextByteOffset;
+        internal int Utf8Bytes;
+        internal int ScannedUtf8Bytes;
+        internal int ReturnedLineCount;
+        internal int? FirstReturnedLine;
+        internal int? LastReturnedLine;
+        internal string? TruncationReason;
+        internal string? InvalidTopologyReason;
+        internal bool Completed;
+        internal bool InvalidContinuation;
+        internal bool IncompleteCoverage;
+        internal bool ScanLimitExceeded;
+
+        internal readonly bool Stopped
+            => Completed
+               || InvalidContinuation
+               || IncompleteCoverage
+               || ScanLimitExceeded
+               || TruncationReason != null;
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.FilesStatus.cs b/src/CodeIndex/Database/DbReader.FilesStatus.cs
index 22afb7ab8..812b559a5 100644
--- a/src/CodeIndex/Database/DbReader.FilesStatus.cs
+++ b/src/CodeIndex/Database/DbReader.FilesStatus.cs
@@ -34,8 +34,6 @@ public partial class DbReader
     internal const string BoundedResourceReadChunkIndexName = "idx_chunks_file_start_chunk_nonnull";
     internal const string LegacyBoundedResourceReadFileIndexName = "idx_chunks_file";
     internal const int MaxLegacyResourceReadSqliteVmSteps = 250_000;
-    private const int LegacyResourceReadProgressOperations = 100;
-    private const int BoundedFileReadBufferSize = 4 * 1024;
     private const string EmptyIndexedContentChecksum =
         "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 
@@ -75,36 +73,6 @@ AND c.start_line > @startLine
         LIMIT @chunkLimit
         """;
 
-    private static readonly string LegacyBoundedResourceReadPredecessorSql = $"""
-        SELECT c.id, c.start_line, c.end_line, c.chunk_index
-        FROM chunks c INDEXED BY {LegacyBoundedResourceReadFileIndexName}
-        WHERE c.file_id = @fileId
-          AND c.content IS NOT NULL
-          AND c.start_line <= @startLine
-        ORDER BY c.start_line DESC, c.chunk_index DESC
-        LIMIT @chunkLimit
-        """;
-
-    private static readonly string LegacyBoundedResourceReadEndSql = $"""
-        SELECT c.id, c.start_line, c.end_line, c.chunk_index
-        FROM chunks c INDEXED BY {LegacyBoundedResourceReadFileIndexName}
-        WHERE c.file_id = @fileId
-          AND c.content IS NOT NULL
-          AND c.end_line >= @startLine
-        ORDER BY c.end_line, c.start_line, c.chunk_index
-        LIMIT @chunkLimit
-        """;
-
-    private static readonly string LegacyBoundedResourceReadForwardSql = $"""
-        SELECT c.id, c.start_line, c.end_line, c.chunk_index
-        FROM chunks c INDEXED BY {LegacyBoundedResourceReadFileIndexName}
-        WHERE c.file_id = @fileId
-          AND c.content IS NOT NULL
-          AND c.start_line > @startLine
-          AND c.start_line <= @endLine
-        ORDER BY c.start_line, c.chunk_index
-        LIMIT @chunkLimit
-        """;
 
     internal static TimeSpan? FindRegexMatchTimeoutForTesting
     {
@@ -1210,692 +1178,23 @@ internal BoundedFileReadResult GetBoundedFileContent(
         int continuationByteOffset = 0)
     {
         ArgumentNullException.ThrowIfNull(file);
-        var path = file.Path;
-        if (string.IsNullOrWhiteSpace(path))
-            return new BoundedFileReadResult { Status = BoundedFileReadStatus.FileNotFound };
-        if (maxUtf8Bytes is <= 0 or > MaxBoundedFileReadUtf8Bytes)
-            throw new ArgumentOutOfRangeException(nameof(maxUtf8Bytes), maxUtf8Bytes,
-                $"UTF-8 byte budget must be between 1 and {MaxBoundedFileReadUtf8Bytes}.");
-        if (maxLines is <= 0 or > MaxBoundedFileReadLines)
-            throw new ArgumentOutOfRangeException(nameof(maxLines), maxLines,
-                $"Line budget must be between 1 and {MaxBoundedFileReadLines}.");
-        if (continuationByteOffset < 0)
-            throw new ArgumentOutOfRangeException(nameof(continuationByteOffset), continuationByteOffset,
-                "Continuation byte offset must be non-negative.");
-        if (!continuationLine.HasValue && continuationByteOffset != 0)
-            return new BoundedFileReadResult { Status = BoundedFileReadStatus.InvalidContinuation, Path = path };
-
-        startLine = Math.Max(1, startLine);
-        endLine = Math.Max(startLine, endLine);
-        var nextLine = continuationLine ?? startLine;
-        if (nextLine < startLine || nextLine > endLine)
-            return new BoundedFileReadResult { Status = BoundedFileReadStatus.InvalidContinuation, Path = path };
-
-        var fileId = file.Id;
-        var lang = file.Lang;
-        var totalLines = file.Lines;
-        var fileSize = file.Size;
-
-        BoundedFileReadResult CreateResult(BoundedFileReadStatus status, string? failureReason = null) => new()
-        {
-            Status = status,
-            FailureReason = failureReason,
-            Path = path,
-            Lang = lang,
-            TotalLines = totalLines,
-            RequestedStartLine = startLine,
-            RequestedEndLine = endLine,
-            StartLine = nextLine,
-            EndLine = nextLine,
-        };
-
-        if (fileSize < 0 || totalLines < 0 || (fileSize == 0 && totalLines > 0))
-            return CreateResult(BoundedFileReadStatus.InvalidTopology, "resource_file_metadata_inconsistent");
-        if (totalLines == 0)
-        {
-            if (_hasChunksTable && HasAnyResourceChunk(fileId))
-                return CreateResult(BoundedFileReadStatus.InvalidTopology, "resource_file_metadata_inconsistent");
-            if (IsAffirmativelyEmptyIndexedFile(totalLines, file.Checksum))
-                return CreateResult(BoundedFileReadStatus.Empty);
-            if (fileSize == 0 && file.Checksum != null)
-                return CreateResult(BoundedFileReadStatus.InvalidTopology, "resource_file_metadata_inconsistent");
-            return CreateResult(BoundedFileReadStatus.ContentUnavailable, "resource_content_unavailable");
-        }
-        if (!_hasChunksTable)
-            return CreateResult(BoundedFileReadStatus.ContentUnavailable, "resource_content_unavailable");
-        var hasBoundedChunkIndexes = _chunkIndexes.Contains(BoundedResourceReadChunkIndexName)
-                                     && _chunkIndexes.Contains(BoundedResourceReadChunkEndIndexName);
-        var useLegacyChunkQueries = !hasBoundedChunkIndexes
-                                    && _chunkIndexes.Contains(LegacyBoundedResourceReadFileIndexName);
-        if (!hasBoundedChunkIndexes && !useLegacyChunkQueries)
-            return CreateResult(BoundedFileReadStatus.ContentUnavailable, "resource_bounded_read_index_unavailable");
-        if (!TryHasNullResourceChunkBoundary(fileId, useLegacyChunkQueries, out var hasNullBoundary))
-            return CreateResult(BoundedFileReadStatus.ContentUnavailable, "resource_bounded_read_index_unavailable");
-        if (hasNullBoundary)
-            return CreateResult(BoundedFileReadStatus.InvalidTopology, "resource_chunk_topology_invalid");
-
-        var effectiveEndLine = Math.Min(endLine, totalLines);
-        if (nextLine > effectiveEndLine)
-            return CreateResult(BoundedFileReadStatus.InvalidContinuation);
-
-        // Bound SQLite work as well as returned metadata. Two disjoint index seeks collect
-        // at most one capped predecessor set and one capped forward set; overlap filtering
-        // then happens only over those bounded rows in memory. This avoids a full file_id
-        // scan for late ranges and gaps while retaining legacy chunks that span many lines.
-        // 返却metadataだけでなくSQLiteの走査量も制限する。互いに素なpredecessor/forwardの
-        // index seekを各上限件数まで取得し、重複範囲の判定はbounded rowだけmemory上で行う。
-        // これにより後方rangeやgapでもfile_id全走査を避け、長いlegacy chunkも扱える。
-        var scanEndLine = (int)Math.Min(effectiveEndLine, (long)nextLine + maxLines - 1L);
-        var chunks = new List<BoundedFileChunk>();
-        var chunkIds = new HashSet<long>();
-        string? chunkTopologyFailure = null;
-        var chunkIndexUnavailable = false;
-
-        int ReadChunkCandidates(string commandText, bool includeEndLine)
-        {
-            int ExecuteQuery()
-            {
-                using var chunkCmd = _conn.CreateCommand();
-                chunkCmd.CommandText = commandText;
-                SqliteCommandPolicy.AddInt64(chunkCmd, "@fileId", fileId);
-                SqliteCommandPolicy.AddInt32(chunkCmd, "@startLine", nextLine);
-                if (includeEndLine)
-                    SqliteCommandPolicy.AddInt32(chunkCmd, "@endLine", scanEndLine);
-                SqliteCommandPolicy.AddInt32(chunkCmd, "@chunkLimit", MaxBoundedFileReadChunks + 1);
-
-                var rawCandidateCount = 0;
-                using var chunkReader = chunkCmd.ExecuteTrackedReader();
-                while (chunkReader.TrackedRead())
-                {
-                    rawCandidateCount++;
-                    _cancellation.ThrowIfCancellationRequested();
-                    if (chunkReader.IsDBNull(1) || chunkReader.IsDBNull(2) || chunkReader.IsDBNull(3))
-                    {
-                        chunkTopologyFailure = "resource_chunk_topology_invalid";
-                        break;
-                    }
-
-                    var chunk = new BoundedFileChunk(
-                        chunkReader.GetInt64(0),
-                        chunkReader.GetInt32(1),
-                        chunkReader.GetInt32(2),
-                        chunkReader.GetInt32(3));
-                    if (chunk.StartLine <= 0 || chunk.EndLine < chunk.StartLine || chunk.ChunkIndex < 0)
-                    {
-                        chunkTopologyFailure = "resource_chunk_topology_invalid";
-                        break;
-                    }
-                    if (chunk.EndLine < nextLine || chunk.StartLine > scanEndLine)
-                        continue;
-
-                    if (chunkIds.Add(chunk.RowId))
-                        chunks.Add(chunk);
-                    if (chunks.Count > MaxBoundedFileReadChunks)
-                        break;
-                }
-
-                return rawCandidateCount;
-            }
-
-            if (!useLegacyChunkQueries)
-                return ExecuteQuery();
-            if (TryRunLegacyResourceMetadataQuery(ExecuteQuery, out var legacyCandidateCount))
-                return legacyCandidateCount;
-
-            chunkIndexUnavailable = true;
-            return 0;
-        }
-
-        var predecessorCandidateCount = ReadChunkCandidates(
-            useLegacyChunkQueries
-                ? LegacyBoundedResourceReadPredecessorSql
-                : BoundedResourceReadPredecessorSql,
-            includeEndLine: false);
-        if (chunkIndexUnavailable)
-            return CreateResult(BoundedFileReadStatus.ContentUnavailable, "resource_bounded_read_index_unavailable");
-
-        bool HasChunkCoveringNextLine()
-            => chunks.Any(chunk => chunk.StartLine <= nextLine && chunk.EndLine >= nextLine);
-
-        if (chunkTopologyFailure == null
-            && chunks.Count <= MaxBoundedFileReadChunks
-            && !HasChunkCoveringNextLine()
-            && predecessorCandidateCount > MaxBoundedFileReadChunks)
-        {
-            var endCandidateCount = ReadChunkCandidates(
-                useLegacyChunkQueries
-                    ? LegacyBoundedResourceReadEndSql
-                    : BoundedResourceReadEndSql,
-                includeEndLine: false);
-            if (chunkIndexUnavailable)
-                return CreateResult(BoundedFileReadStatus.ContentUnavailable, "resource_bounded_read_index_unavailable");
-            if (chunkTopologyFailure == null
-                && !HasChunkCoveringNextLine()
-                && endCandidateCount > MaxBoundedFileReadChunks)
-            {
-                return CreateResult(BoundedFileReadStatus.InvalidTopology, "chunk_candidate_scan_limit_exceeded");
-            }
-        }
-
-        if (chunkTopologyFailure == null && chunks.Count <= MaxBoundedFileReadChunks)
-        {
-            ReadChunkCandidates(
-                useLegacyChunkQueries
-                    ? LegacyBoundedResourceReadForwardSql
-                    : BoundedResourceReadForwardSql,
-                includeEndLine: true);
-        }
-
-        if (chunkIndexUnavailable)
-            return CreateResult(BoundedFileReadStatus.ContentUnavailable, "resource_bounded_read_index_unavailable");
-        if (chunkTopologyFailure != null)
-            return CreateResult(BoundedFileReadStatus.InvalidTopology, chunkTopologyFailure);
-        if (chunks.Count > MaxBoundedFileReadChunks)
-            return CreateResult(BoundedFileReadStatus.InvalidTopology, "chunk_limit_exceeded");
-        chunks.Sort(static (left, right) =>
-        {
-            var byStartLine = left.StartLine.CompareTo(right.StartLine);
-            return byStartLine != 0 ? byStartLine : left.ChunkIndex.CompareTo(right.ChunkIndex);
-        });
-        if (chunks.Count == 0)
-        {
-            if (!TryHasAnyStoredResourceChunk(fileId, useLegacyChunkQueries, out var hasStoredChunk))
-                return CreateResult(BoundedFileReadStatus.ContentUnavailable, "resource_bounded_read_index_unavailable");
-            return hasStoredChunk
-                ? CreateResult(BoundedFileReadStatus.IncompleteCoverage, "resource_chunk_coverage_incomplete")
-                : CreateResult(BoundedFileReadStatus.ContentUnavailable, "resource_content_unavailable");
-        }
-
-        var state = new BoundedFileReadState(nextLine, continuationByteOffset);
-        var scanByteLimit = BoundedFileReadScanByteLimitOverride.Value ?? MaxBoundedFileReadScannedUtf8Bytes;
-        if (scanByteLimit <= 0 || scanByteLimit > MaxBoundedFileReadScannedUtf8Bytes)
-            scanByteLimit = MaxBoundedFileReadScannedUtf8Bytes;
-        var content = new StringBuilder(Math.Min(maxUtf8Bytes, BoundedFileReadBufferSize));
-        var buffer = ArrayPool<byte>.Shared.Rent(BoundedFileReadBufferSize);
-        try
-        {
-            for (var chunkIndex = 0; chunkIndex < chunks.Count; chunkIndex++)
-            {
-                var chunk = chunks[chunkIndex];
-                _cancellation.ThrowIfCancellationRequested();
-                if (state.Stopped)
-                    break;
-                if (chunk.EndLine < state.NextLine)
-                    continue;
-                if (chunk.StartLine > state.NextLine)
-                {
-                    state.IncompleteCoverage = true;
-                    break;
-                }
-
-                using var blob = new SqliteBlob(_conn, "chunks", "content", chunk.RowId, readOnly: true);
-                ReadBoundedChunk(
-                    blob,
-                    chunk,
-                    effectiveEndLine,
-                    maxUtf8Bytes,
-                    maxLines,
-                    content,
-                    buffer,
-                    scanByteLimit,
-                    _cancellation,
-                    ref state);
-            }
-        }
-        catch (BoundedFileScanLimitException)
-        {
-            state.ScanLimitExceeded = true;
-        }
-        catch (InvalidDataException)
-        {
-            state.InvalidTopologyReason = "invalid_utf8_content";
-        }
-        finally
-        {
-            // Indexed source may contain secrets. Clear the entire pooled array before reuse.
-            // index済みsourceにsecretが含まれうるため、poolへ戻す前に配列全体を消去する。
-            ArrayPool<byte>.Shared.Return(buffer, clearArray: true);
-        }
-
-        if (state.ScanLimitExceeded)
-            return CreateResult(BoundedFileReadStatus.InvalidTopology, "scan_limit_exceeded");
-        if (state.InvalidTopologyReason != null)
-            return CreateResult(BoundedFileReadStatus.InvalidTopology, state.InvalidTopologyReason);
-        if (state.InvalidContinuation)
-            return CreateResult(BoundedFileReadStatus.InvalidContinuation, "invalid_continuation");
-        if (state.IncompleteCoverage || (!state.Completed && state.TruncationReason == null))
-            return CreateResult(BoundedFileReadStatus.IncompleteCoverage, "resource_chunk_coverage_incomplete");
-
-        return new BoundedFileReadResult
-        {
-            Status = BoundedFileReadStatus.Success,
-            Path = path,
-            Lang = lang,
-            TotalLines = totalLines,
-            RequestedStartLine = startLine,
-            RequestedEndLine = endLine,
-            StartLine = state.FirstReturnedLine ?? nextLine,
-            EndLine = state.LastReturnedLine ?? nextLine,
-            Content = content.ToString(),
-            Utf8Bytes = state.Utf8Bytes,
-            Truncated = state.TruncationReason != null,
-            TruncationReason = state.TruncationReason,
-            NextLine = state.TruncationReason != null ? state.NextLine : null,
-            NextByteOffset = state.TruncationReason != null ? state.NextByteOffset : null,
-        };
-    }
-
-    private bool HasAnyResourceChunk(long fileId)
-    {
-        _cancellation.ThrowIfCancellationRequested();
-        using var command = _conn.CreateCommand();
-        command.CommandText = "SELECT 1 FROM chunks WHERE file_id = @fileId LIMIT 1";
-        SqliteCommandPolicy.AddInt64(command, "@fileId", fileId);
-        var hasChunk = command.ExecuteScalar() != null;
-        _cancellation.ThrowIfCancellationRequested();
-        return hasChunk;
-    }
-
-    private bool TryHasAnyStoredResourceChunk(long fileId, bool useLegacyChunkQueries, out bool hasChunk)
-    {
-        bool ExecuteQuery()
-        {
-            _cancellation.ThrowIfCancellationRequested();
-            using var command = _conn.CreateCommand();
-            var indexName = useLegacyChunkQueries
-                ? LegacyBoundedResourceReadFileIndexName
-                : BoundedResourceReadChunkIndexName;
-            command.CommandText = $"""
-                SELECT 1
-                FROM chunks INDEXED BY {indexName}
-                WHERE file_id = @fileId AND content IS NOT NULL
-                LIMIT 1
-                """;
-            SqliteCommandPolicy.AddInt64(command, "@fileId", fileId);
-            var result = command.ExecuteScalar() != null;
-            _cancellation.ThrowIfCancellationRequested();
-            return result;
-        }
-
-        if (!useLegacyChunkQueries)
-        {
-            hasChunk = ExecuteQuery();
-            return true;
-        }
-
-        return TryRunLegacyResourceMetadataQuery(ExecuteQuery, out hasChunk);
+        var reader = new BoundedIndexedContentReader(
+            _conn,
+            _cancellation,
+            _hasChunksTable,
+            _chunkIndexes,
+            BoundedFileReadScanByteLimitOverride.Value,
+            LegacyResourceReadSqliteVmStepLimitOverride.Value);
+        return reader.Read(new BoundedIndexedContentRequest(
+            file,
+            startLine,
+            endLine,
+            maxUtf8Bytes,
+            maxLines,
+            continuationLine,
+            continuationByteOffset));
     }
 
-    private bool TryHasNullResourceChunkBoundary(long fileId, bool useLegacyChunkQueries, out bool hasNullBoundary)
-    {
-        bool ExecuteQuery()
-        {
-            bool Exists(string commandText)
-            {
-                using var command = _conn.CreateCommand();
-                command.CommandText = commandText;
-                SqliteCommandPolicy.AddInt64(command, "@fileId", fileId);
-                return command.ExecuteScalar() != null;
-            }
-
-            var startIndexName = useLegacyChunkQueries
-                ? LegacyBoundedResourceReadFileIndexName
-                : BoundedResourceReadChunkIndexName;
-            var endIndexName = useLegacyChunkQueries
-                ? LegacyBoundedResourceReadFileIndexName
-                : BoundedResourceReadChunkEndIndexName;
-            _cancellation.ThrowIfCancellationRequested();
-            var result = Exists($"""
-                SELECT 1
-                FROM chunks INDEXED BY {startIndexName}
-                WHERE file_id = @fileId
-                  AND content IS NOT NULL
-                  AND start_line IS NULL
-                LIMIT 1
-                """) || Exists($"""
-                SELECT 1
-                FROM chunks INDEXED BY {endIndexName}
-                WHERE file_id = @fileId
-                  AND content IS NOT NULL
-                  AND end_line IS NULL
-                LIMIT 1
-                """);
-            _cancellation.ThrowIfCancellationRequested();
-            return result;
-        }
-
-        if (!useLegacyChunkQueries)
-        {
-            hasNullBoundary = ExecuteQuery();
-            return true;
-        }
-
-        return TryRunLegacyResourceMetadataQuery(ExecuteQuery, out hasNullBoundary);
-    }
-
-    private bool TryRunLegacyResourceMetadataQuery<T>(Func<T> action, out T result)
-    {
-        var maxVmSteps = LegacyResourceReadSqliteVmStepLimitOverride.Value
-                         ?? MaxLegacyResourceReadSqliteVmSteps;
-        maxVmSteps = Math.Clamp(maxVmSteps, 1, MaxLegacyResourceReadSqliteVmSteps);
-        var callbackLimit = Math.Max(1, (maxVmSteps + LegacyResourceReadProgressOperations - 1)
-                                        / LegacyResourceReadProgressOperations);
-        var callbackCount = 0;
-        var budgetExceeded = false;
-        SQLitePCL.delegate_progress progress = _ =>
-        {
-            callbackCount++;
-            if (callbackCount <= callbackLimit)
-                return 0;
-
-            budgetExceeded = true;
-            return 1;
-        };
-
-        SQLitePCL.raw.sqlite3_progress_handler(
-            _conn.Handle,
-            LegacyResourceReadProgressOperations,
-            progress,
-            null!);
-        try
-        {
-            result = action();
-            return true;
-        }
-        catch (SqliteException exception) when (
-            budgetExceeded
-            && !_cancellation.IsCancellationRequested
-            && exception.SqliteErrorCode == 9)
-        {
-            result = default!;
-            return false;
-        }
-        finally
-        {
-            SQLitePCL.raw.sqlite3_progress_handler(_conn.Handle, 0, null!, null!);
-            GC.KeepAlive(progress);
-        }
-    }
-
-    private static void ReadBoundedChunk(
-        SqliteBlob blob,
-        BoundedFileChunk chunk,
-        int effectiveEndLine,
-        int maxUtf8Bytes,
-        int maxLines,
-        StringBuilder content,
-        byte[] buffer,
-        int maxScannedUtf8Bytes,
-        CancellationToken cancellationToken,
-        ref BoundedFileReadState state)
-    {
-        var bufferOffset = 0;
-        var bufferedBytes = 0;
-        var localLine = chunk.StartLine;
-        var localByteOffset = 0;
-        Span<byte> runeBytes = stackalloc byte[4];
-        Span<char> runeChars = stackalloc char[2];
-
-        while (TryReadBlobByte(blob, buffer, ref bufferOffset, ref bufferedBytes, maxScannedUtf8Bytes, cancellationToken, ref state, out var firstByte))
-        {
-            if (localLine > chunk.EndLine)
-                break;
-
-            if (localLine < state.NextLine)
-            {
-                if (firstByte == (byte)'\n')
-                {
-                    localLine++;
-                    localByteOffset = 0;
-                }
-                else
-                {
-                    localByteOffset++;
-                }
-                continue;
-            }
-
-            if (localLine > state.NextLine)
-            {
-                state.InvalidContinuation = true;
-                return;
-            }
-
-            if (firstByte == (byte)'\n')
-            {
-                if (state.NextByteOffset != localByteOffset)
-                {
-                    state.InvalidContinuation = true;
-                    return;
-                }
-
-                if (!CompleteBoundedLine(
-                    localLine,
-                    localByteOffset,
-                    effectiveEndLine,
-                    maxUtf8Bytes,
-                    maxLines,
-                    content,
-                    ref state))
-                {
-                    return;
-                }
-
-                localLine++;
-                localByteOffset = 0;
-                continue;
-            }
-
-            var runeByteCount = ReadUtf8Rune(
-                blob,
-                firstByte,
-                buffer,
-                ref bufferOffset,
-                ref bufferedBytes,
-                maxScannedUtf8Bytes,
-                cancellationToken,
-                ref state,
-                runeBytes,
-                out var rune);
-            var scalarStartOffset = localByteOffset;
-            localByteOffset += runeByteCount;
-
-            if (scalarStartOffset < state.NextByteOffset)
-            {
-                if (localByteOffset > state.NextByteOffset)
-                    state.InvalidContinuation = true;
-                if (state.InvalidContinuation)
-                    return;
-                continue;
-            }
-
-            if (scalarStartOffset != state.NextByteOffset)
-            {
-                state.InvalidContinuation = true;
-                return;
-            }
-            if (state.Utf8Bytes > maxUtf8Bytes - runeByteCount)
-            {
-                state.TruncationReason = "max_bytes";
-                return;
-            }
-            if (!TryEnterBoundedLine(localLine, maxLines, ref state))
-                return;
-
-            var runeCharCount = rune.EncodeToUtf16(runeChars);
-            content.Append(runeChars[..runeCharCount]);
-            state.Utf8Bytes += runeByteCount;
-            state.NextByteOffset = localByteOffset;
-        }
-
-        // Persisted chunks omit the separator after their final line. Treat blob EOF as
-        // that line boundary and synthesize exactly one LF when the requested range continues.
-        // 永続化chunkは最終行後のseparatorを持たないため、blob EOFを行境界として扱い、
-        // 要求範囲が続く場合だけLFを1つ合成する。
-        if (!state.Stopped && localLine <= chunk.EndLine && localLine == state.NextLine)
-        {
-            if (state.NextByteOffset != localByteOffset)
-            {
-                state.InvalidContinuation = true;
-                return;
-            }
-
-            _ = CompleteBoundedLine(
-                localLine,
-                localByteOffset,
-                effectiveEndLine,
-                maxUtf8Bytes,
-                maxLines,
-                content,
-                ref state);
-        }
-    }
-
-    private static bool CompleteBoundedLine(
-        int line,
-        int lineByteLength,
-        int effectiveEndLine,
-        int maxUtf8Bytes,
-        int maxLines,
-        StringBuilder content,
-        ref BoundedFileReadState state)
-    {
-        if (!TryEnterBoundedLine(line, maxLines, ref state))
-            return false;
-
-        if (line >= effectiveEndLine)
-        {
-            state.Completed = true;
-            return false;
-        }
-
-        if (state.Utf8Bytes >= maxUtf8Bytes)
-        {
-            state.NextLine = line;
-            state.NextByteOffset = lineByteLength;
-            state.TruncationReason = "max_bytes";
-            return false;
-        }
-
-        content.Append('\n');
-        state.Utf8Bytes++;
-        state.NextLine = line + 1;
-        state.NextByteOffset = 0;
-        if (state.ReturnedLineCount >= maxLines)
-        {
-            state.TruncationReason = "max_lines";
-            return false;
-        }
-
-        return true;
-    }
-
-    private static bool TryEnterBoundedLine(int line, int maxLines, ref BoundedFileReadState state)
-    {
-        if (state.LastReturnedLine == line)
-            return true;
-        if (state.ReturnedLineCount >= maxLines)
-        {
-            state.TruncationReason = "max_lines";
-            return false;
-        }
-
-        state.FirstReturnedLine ??= line;
-        state.LastReturnedLine = line;
-        state.ReturnedLineCount++;
-        return true;
-    }
-
-    private static int ReadUtf8Rune(
-        SqliteBlob blob,
-        byte firstByte,
-        byte[] buffer,
-        ref int bufferOffset,
-        ref int bufferedBytes,
-        int maxScannedUtf8Bytes,
-        CancellationToken cancellationToken,
-        ref BoundedFileReadState state,
-        Span<byte> runeBytes,
-        out Rune rune)
-    {
-        var byteCount = firstByte switch
-        {
-            <= 0x7f => 1,
-            >= 0xc2 and <= 0xdf => 2,
-            >= 0xe0 and <= 0xef => 3,
-            >= 0xf0 and <= 0xf4 => 4,
-            _ => throw new InvalidDataException("Indexed chunk contains invalid UTF-8."),
-        };
-
-        runeBytes[0] = firstByte;
-        for (var i = 1; i < byteCount; i++)
-        {
-            if (!TryReadBlobByte(blob, buffer, ref bufferOffset, ref bufferedBytes, maxScannedUtf8Bytes, cancellationToken, ref state, out runeBytes[i]))
-                throw new InvalidDataException("Indexed chunk ends inside a UTF-8 scalar value.");
-        }
-
-        var status = Rune.DecodeFromUtf8(runeBytes[..byteCount], out rune, out var bytesConsumed);
-        if (status != OperationStatus.Done || bytesConsumed != byteCount)
-            throw new InvalidDataException("Indexed chunk contains invalid UTF-8.");
-        return byteCount;
-    }
-
-    private static bool TryReadBlobByte(
-        SqliteBlob blob,
-        byte[] buffer,
-        ref int bufferOffset,
-        ref int bufferedBytes,
-        int maxScannedUtf8Bytes,
-        CancellationToken cancellationToken,
-        ref BoundedFileReadState state,
-        out byte value)
-    {
-        if (bufferOffset >= bufferedBytes)
-        {
-            cancellationToken.ThrowIfCancellationRequested();
-            if (blob.Position >= blob.Length)
-            {
-                value = 0;
-                return false;
-            }
-            var remaining = maxScannedUtf8Bytes - state.ScannedUtf8Bytes;
-            if (remaining <= 0)
-                throw new BoundedFileScanLimitException();
-            bufferedBytes = blob.Read(buffer, 0, Math.Min(buffer.Length, remaining));
-            bufferOffset = 0;
-            if (bufferedBytes == 0)
-            {
-                value = 0;
-                return false;
-            }
-        }
-
-        value = buffer[bufferOffset++];
-        state.ScannedUtf8Bytes++;
-        return true;
-    }
-
-    private readonly record struct BoundedFileChunk(long RowId, int StartLine, int EndLine, int ChunkIndex);
-
-    private sealed class BoundedFileScanLimitException : Exception;
-
-    private struct BoundedFileReadState(int nextLine, int nextByteOffset)
-    {
-        public int NextLine = nextLine;
-        public int NextByteOffset = nextByteOffset;
-        public int Utf8Bytes;
-        public int ScannedUtf8Bytes;
-        public int ReturnedLineCount;
-        public int? FirstReturnedLine;
-        public int? LastReturnedLine;
-        public string? TruncationReason;
-        public string? InvalidTopologyReason;
-        public bool Completed;
-        public bool InvalidContinuation;
-        public bool IncompleteCoverage;
-        public bool ScanLimitExceeded;
-        public readonly bool Stopped => Completed || InvalidContinuation || IncompleteCoverage || ScanLimitExceeded || TruncationReason != null;
-    }
 
     /// <summary>
     /// Return the length of the focused excerpt line when it is part of the reconstructed range.

From bf743c9c988da13b48efaa3feeaa53d6ab820a2a Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 07:12:00 +0900
Subject: [PATCH 08/45] Decompose cross-language reference extraction loop

---
 ...erenceExtractor.CoreContainerResolution.cs | 170 ++++
 .../ReferenceExtractor.CoreReferenceLine.cs   | 326 ++++++++
 .../ReferenceExtractor.CoreReferenceLoop.cs   | 767 ++----------------
 .../ReferenceExtractor.CoreReferencePhases.cs | 291 +++++++
 4 files changed, 856 insertions(+), 698 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreContainerResolution.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs

diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreContainerResolution.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreContainerResolution.cs
new file mode 100644
index 000000000..7cf40728c
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreContainerResolution.cs
@@ -0,0 +1,170 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private sealed class CoreReferenceLineContainerResolver
+    {
+        private readonly CoreReferenceLoopContext _loop;
+        private readonly int _lineIndex;
+        private readonly int _lineNumber;
+        private readonly SymbolRecord? _container;
+        private readonly bool _csharpLineHasWhereClause;
+        private readonly (
+            SymbolRecord Synthetic,
+            int NameIndex,
+            int OpenBraceIndex,
+            int CloseBraceIndex)? _javaSameLineCtor;
+
+        internal CoreReferenceLineContainerResolver(
+            CoreReferenceLoopContext loop,
+            int lineIndex,
+            int lineNumber,
+            SymbolRecord? container,
+            bool csharpLineHasWhereClause,
+            (SymbolRecord Synthetic, int NameIndex, int OpenBraceIndex,
+                int CloseBraceIndex)? javaSameLineCtor)
+        {
+            _loop = loop;
+            _lineIndex = lineIndex;
+            _lineNumber = lineNumber;
+            _container = container;
+            _csharpLineHasWhereClause = csharpLineHasWhereClause;
+            _javaSameLineCtor = javaSameLineCtor;
+            ResolveContainerForCall = ResolveContainer;
+            ResolveSwiftPropertyContainerForCall =
+                ResolveSwiftPropertyContainer;
+        }
+
+        internal Func<int, SymbolRecord?> ResolveContainerForCall { get; }
+
+        internal Func<int, SymbolRecord?> ResolveSwiftPropertyContainerForCall
+        {
+            get;
+        }
+
+        private SymbolRecord? ResolveContainer(int column)
+        {
+            var language = _loop.Request.Language;
+            if (language == "csharp")
+            {
+                var recordContainer = ResolveCSharpRecordContainer(column);
+                if (recordContainer.IsResolved)
+                    return recordContainer.Container;
+            }
+
+            if (_javaSameLineCtor != null)
+            {
+                var info = _javaSameLineCtor.Value;
+                if (info.CloseBraceIndex >= 0
+                    && column > info.OpenBraceIndex
+                    && column < info.CloseBraceIndex)
+                {
+                    return info.Synthetic;
+                }
+            }
+
+            if (language == "csharp")
+            {
+                if (_csharpLineHasWhereClause)
+                {
+                    var declarationRangeContainer =
+                        FindInnermostCSharpDeclarationRangeContainer(
+                            _loop.ContainerCandidates,
+                            _loop.Preparation.StructuralLines[_lineIndex],
+                            _lineNumber,
+                            column);
+                    if (declarationRangeContainer != null)
+                        return declarationRangeContainer;
+                }
+
+                var sameLineContainer =
+                    FindInnermostSameLineCSharpContainer(
+                        _loop.Lookups
+                            .GetCSharpSameLineContainerCandidatesByLine(),
+                        _loop.Preparation.StructuralLines[_lineIndex],
+                        _lineNumber,
+                        column);
+                if (sameLineContainer != null)
+                    return sameLineContainer;
+
+                if (_csharpLineHasWhereClause
+                    && _container?.Kind == "function"
+                    && _container.StartLine == _lineNumber
+                    && (!TryFindCSharpFunctionNameColumn(
+                            _loop.Preparation.StructuralLines[_lineIndex],
+                            _container.Name,
+                            out var containerNameColumn)
+                        || column < containerNameColumn))
+                {
+                    return null;
+                }
+            }
+
+            return _loop.DynamicDeclarativeState?.ResolveContainer(
+                _lineNumber,
+                column,
+                _container) ?? _container;
+        }
+
+        private (bool IsResolved, SymbolRecord? Container)
+            ResolveCSharpRecordContainer(int column)
+        {
+            SymbolRecord? primaryCtorOwner = null;
+            foreach (var (
+                         rangeStart,
+                         rangeStartColumn,
+                         rangeEnd,
+                         rangeEndColumn,
+                         syntheticRecordCtor,
+                         owner) in
+                     _loop.Lookups.GetRecordPrimaryCtorRanges())
+            {
+                if (ReferenceEquals(_container, syntheticRecordCtor)
+                    || (_container?.Kind == "function"
+                        && _container.FileId == syntheticRecordCtor.FileId
+                        && _container.StartLine == syntheticRecordCtor.StartLine
+                        && (_container.StartLine < rangeEnd
+                            || (_container.StartColumn
+                                    is int containerStartColumn
+                                && containerStartColumn < rangeEndColumn))
+                        && string.Equals(
+                            _container.Name,
+                            syntheticRecordCtor.Name,
+                            StringComparison.Ordinal)))
+                {
+                    primaryCtorOwner ??= owner;
+                }
+                if (_lineNumber < rangeStart || _lineNumber > rangeEnd)
+                    continue;
+                if (_lineNumber == rangeStart && column < rangeStartColumn)
+                    return (true, owner);
+                if (_lineNumber == rangeEnd && column >= rangeEndColumn)
+                    continue;
+                return (true, syntheticRecordCtor);
+            }
+
+            return primaryCtorOwner != null
+                ? (true, primaryCtorOwner)
+                : (false, null);
+        }
+
+        private SymbolRecord? ResolveSwiftPropertyContainer(int column)
+        {
+            if (_loop.SwiftPropertyDefinitionsByLine != null
+                && _loop.SwiftPropertyDefinitionsByLine.TryGetValue(
+                    _lineNumber,
+                    out var sameLineProperties))
+            {
+                foreach (var property in sameLineProperties)
+                {
+                    if ((property.StartColumn ?? 0) <= column)
+                        return property;
+                }
+            }
+
+            return ResolveContainer(column);
+        }
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs
new file mode 100644
index 000000000..e45a9fcd1
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs
@@ -0,0 +1,326 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static CoreReferenceLineFlow ProcessCoreReferenceLine(
+        CoreReferenceLoopContext loop,
+        CoreReferenceLoopState state,
+        int lineIndex)
+    {
+        if (!TryPrepareCoreReferenceLine(
+                loop,
+                state,
+                lineIndex,
+                out var prepared))
+        {
+            return CoreReferenceLineFlow.LineConsumed;
+        }
+
+        return EmitCoreOrderedReferencePhases(loop, state, prepared);
+    }
+
+    private static bool TryPrepareCoreReferenceLine(
+        CoreReferenceLoopContext loop,
+        CoreReferenceLoopState state,
+        int lineIndex,
+        out CorePreparedReferenceLine prepared)
+    {
+        var request = loop.Request;
+        var input = loop.Preparation;
+        var language = request.Language;
+        var lineNumber = lineIndex + 1;
+        var originalLine = input.Lines[lineIndex];
+        var languageLines = PrepareCoreLanguageLine(
+            loop,
+            state,
+            lineIndex,
+            originalLine);
+        var preparedLine = languageLines.PreparedLine;
+        var preparedLineIsWhiteSpace =
+            string.IsNullOrWhiteSpace(preparedLine);
+        var csharpAttributeRanges = loop.CSharpAttributeRanges?[lineIndex];
+        var csharpAttributeTopLevelRanges =
+            loop.CSharpAttributeTopLevelRanges?[lineIndex];
+
+        if (EmitCoreDocumentationAndSpecialLineReferences(
+                loop,
+                state,
+                lineIndex,
+                originalLine,
+                preparedLine,
+                preparedLineIsWhiteSpace,
+                csharpAttributeRanges,
+                out var sourceContext))
+        {
+            prepared = default;
+            return false;
+        }
+
+        if (preparedLineIsWhiteSpace)
+        {
+            if (language == "csharp"
+                && (state.PendingCSharpMultiLineTypePattern.WaitingForHead
+                    || state.PendingCSharpMultiLineTypePattern
+                        .PendingTypeExpression != null))
+            {
+                prepared = default;
+                return false;
+            }
+
+            if (language == "csharp")
+            {
+                CSharpReferenceExtractor
+                    .FlushPendingMultiLineTypePatternReference(
+                        ref state.PendingCSharpMultiLineTypePattern,
+                        loop.CSharpQualifiedConstantPatternMemberLookup,
+                        loop.CSharpUsingAliases,
+                        loop.CSharpUsingStatics,
+                        loop.Lookups.HasActiveSameFileCSharpTypeCandidate,
+                        loop.References,
+                        loop.Seen,
+                        request.FileId);
+            }
+
+            prepared = default;
+            return false;
+        }
+
+        if (sourceContext.Length == 0)
+        {
+            prepared = default;
+            return false;
+        }
+
+        var definitionNames =
+            loop.DefinitionNamesByLine.TryGetValue(
+                lineNumber,
+                out var namesOnLine)
+                ? namesOnLine
+                : null;
+        Dictionary<string, HashSet<int>>?
+            scientificDefinitionNameIndices = null;
+        loop.ScientificDefinitionNameIndicesByLine?.TryGetValue(
+            lineNumber,
+            out scientificDefinitionNameIndices);
+        List<SqlReferenceExtractor.DefinitionLeafSpan>?
+            sqlDefinitionLeafSpans = null;
+        if (language == "sql")
+        {
+            loop.SqlDefinitionLeafSpansByLine?.TryGetValue(
+                lineNumber,
+                out sqlDefinitionLeafSpans);
+        }
+
+        var container = loop.ContainerResolver.Find(lineNumber);
+        var definitionState = new CoreLineDefinitionState(
+            language,
+            sourceContext,
+            preparedLine,
+            definitionNames,
+            loop.DefinitionNamesComparer,
+            scientificDefinitionNameIndices,
+            sqlDefinitionLeafSpans);
+        var csharpLineHasWhereClause = language == "csharp"
+            && preparedLine.IndexOf("where", StringComparison.Ordinal) >= 0
+            && CSharpWhereClauseRegex.IsMatch(preparedLine);
+
+        (SymbolRecord Synthetic, int NameIndex, int OpenBraceIndex,
+            int CloseBraceIndex)? javaSameLineCtor = null;
+        if (language == "java")
+        {
+            javaSameLineCtor =
+                JavaReferenceExtractor.TryBuildSameLineCtorSpan(
+                    preparedLine,
+                    lineNumber,
+                    loop.Lookups.GetEnclosingTypeCandidates);
+        }
+
+        var containerResolver = new CoreReferenceLineContainerResolver(
+            loop,
+            lineIndex,
+            lineNumber,
+            container,
+            csharpLineHasWhereClause,
+            javaSameLineCtor);
+        var line = new CoreReferenceLineContext(
+            request.FileId,
+            language,
+            input.Lines,
+            input.PreparedLines,
+            lineIndex,
+            preparedLine,
+            originalLine,
+            sourceContext,
+            lineNumber,
+            loop.References,
+            loop.Seen,
+            container,
+            definitionNames,
+            containerResolver.ResolveContainerForCall,
+            state.IsIgnoredCallName);
+        prepared = new CorePreparedReferenceLine(
+            line,
+            languageLines.OriginalLineForLanguage,
+            csharpAttributeRanges,
+            csharpAttributeTopLevelRanges,
+            definitionState,
+            javaSameLineCtor,
+            containerResolver);
+        return true;
+    }
+
+    private static (
+        string PreparedLine,
+        string OriginalLineForLanguage) PrepareCoreLanguageLine(
+        CoreReferenceLoopContext loop,
+        CoreReferenceLoopState state,
+        int lineIndex,
+        string originalLine)
+    {
+        var input = loop.Preparation;
+        var preparedLine = input.LuaPreparedLines?[lineIndex]
+            ?? input.LispReferenceLines?[lineIndex]
+            ?? input.PreparedLines[lineIndex];
+        var originalLineForLanguage = originalLine;
+        if (loop.Request.Language == "sass")
+        {
+            preparedLine = CssReferenceExtractor.MaskSassBlockCommentLine(
+                preparedLine,
+                state.SassPreparedCommentState!);
+            originalLineForLanguage =
+                CssReferenceExtractor.MaskSassBlockCommentLine(
+                    originalLine,
+                    state.SassOriginalCommentState!);
+        }
+        else if (loop.Request.Language == "stylus")
+        {
+            preparedLine =
+                CssReferenceExtractor.MaskSassStylusBlockCommentLine(
+                    preparedLine,
+                    ref state.SassStylusPreparedInBlockComment);
+            originalLineForLanguage =
+                CssReferenceExtractor.MaskSassStylusBlockCommentLine(
+                    originalLine,
+                    ref state.SassStylusOriginalInBlockComment);
+        }
+
+        return (preparedLine, originalLineForLanguage);
+    }
+
+    private static bool EmitCoreDocumentationAndSpecialLineReferences(
+        CoreReferenceLoopContext loop,
+        CoreReferenceLoopState state,
+        int lineIndex,
+        string originalLine,
+        string preparedLine,
+        bool preparedLineIsWhiteSpace,
+        List<(int start, int end)>? csharpAttributeRangesOnLine,
+        out string sourceContext)
+    {
+        var request = loop.Request;
+        var input = loop.Preparation;
+        var lineNumber = lineIndex + 1;
+        if (request.Language is "csharp" or "java" or "kotlin" or "r" or "php")
+        {
+            Func<SymbolRecord?>? getPhpLineContainer = null;
+            if (request.Language == "php")
+            {
+                SymbolRecord? phpLineContainer = null;
+                var phpLineContainerResolved = false;
+
+                SymbolRecord? GetPhpLineContainer()
+                {
+                    if (!phpLineContainerResolved)
+                    {
+                        phpLineContainer =
+                            loop.ContainerResolver.Find(lineNumber);
+                        phpLineContainerResolved = true;
+                    }
+
+                    return phpLineContainer;
+                }
+
+                getPhpLineContainer = GetPhpLineContainer;
+            }
+
+            var documentationLine = new CoreDocumentationLineContext(
+                request.FileId,
+                request.Language,
+                input.Lines,
+                input.PreparedLines,
+                input.StructuralLines,
+                lineIndex,
+                lineNumber,
+                originalLine,
+                preparedLine,
+                loop.References,
+                loop.Seen,
+                loop.ContainerCandidates,
+                loop.ContainerResolver,
+                loop.Lookups,
+                input.CSharpLinesInsideMultilineStringContent,
+                input.CSharpLinesInsideBlockComment,
+                csharpAttributeRangesOnLine,
+                loop.CSharpAttributeRanges,
+                getPhpLineContainer);
+            EmitCoreDocumentationReferences(
+                documentationLine,
+                ref state.CSharpInDelimitedDocComment,
+                ref state.JvmInDelimitedDocComment,
+                ref state.PhpInDocblock,
+                ref state.PhpDocblockContainer,
+                ref state.PhpDocblockPropertyNames);
+        }
+
+        if (preparedLineIsWhiteSpace
+            && request.Language
+                is not ("cmake"
+                    or "justfile"
+                    or "makefile"
+                    or "msbuild"
+                    or "graphql"
+                    or "html"
+                    or "markdown"))
+        {
+            sourceContext = string.Empty;
+            return false;
+        }
+
+        sourceContext = originalLine.Trim();
+        if (request.Language
+                is "cmake" or "justfile" or "makefile" or "msbuild"
+            && sourceContext.Length > 0)
+        {
+            BuildAutomationReferenceExtractor.EmitReferences(
+                request.Language,
+                originalLine,
+                sourceContext,
+                lineNumber,
+                loop.References,
+                loop.Seen,
+                request.FileId,
+                loop.ContainerResolver.Find(lineNumber));
+            return true;
+        }
+
+        if (request.Language is not ("graphql" or "html" or "markdown")
+            || sourceContext.Length == 0)
+        {
+            return false;
+        }
+
+        MarkupSchemaReferenceExtractor.EmitReferences(
+            request.Language,
+            originalLine,
+            sourceContext,
+            lineNumber,
+            loop.References,
+            loop.Seen,
+            request.FileId,
+            loop.ContainerResolver.Find(lineNumber),
+            state.MarkupSchemaState);
+        return true;
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
index c738ab492..57581ec75 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
@@ -4,6 +4,13 @@ namespace CodeIndex.Indexer;
 
 public static partial class ReferenceExtractor
 {
+    private enum CoreReferenceLineFlow
+    {
+        Continue,
+        LineConsumed,
+        StopExtraction,
+    }
+
     private sealed class CoreReferenceLoopContext
     {
         internal required ReferenceExtractionContext Request { get; init; }
@@ -46,25 +53,53 @@ private sealed class CoreReferenceLoopContext
         internal required ReferenceDedupeSet Seen { get; init; }
     }
 
-    private sealed class CoreReferenceLoopMutableState
+    private sealed class CoreReferenceLoopState
     {
+        internal CSharpMultiLineTypePatternState PendingCSharpMultiLineTypePattern;
+        internal readonly CSharpWhereConstraintState? PendingCSharpWhereConstraint;
+        internal readonly Dictionary<string, HashSet<string>>? CSharpLocalNamesByFunction;
+        internal readonly SqlReferenceExtractor.State? SqlState;
+        internal bool XamlInXmlComment;
+        internal readonly XamlReferenceExtractor.BindingPropertyElementState? XamlBindingPropertyElementState;
+        internal readonly XamlReferenceExtractor.BindingMarkupExtensionState? XamlBindingMarkupExtensionState;
         internal bool CSharpInDelimitedDocComment;
         internal bool JvmInDelimitedDocComment;
         internal bool PhpInDocblock;
         internal SymbolRecord? PhpDocblockContainer;
         internal HashSet<string>? PhpDocblockPropertyNames;
-        internal MarkupSchemaReferenceExtractor.MarkupState? MarkupSchemaState;
-        internal CssReferenceExtractor.SassLoudCommentState? SassPreparedCommentState;
-        internal CssReferenceExtractor.SassLoudCommentState? SassOriginalCommentState;
+        internal readonly MarkupSchemaReferenceExtractor.MarkupState? MarkupSchemaState;
+        internal readonly CssReferenceExtractor.SassLoudCommentState? SassPreparedCommentState;
+        internal readonly CssReferenceExtractor.SassLoudCommentState? SassOriginalCommentState;
         internal bool SassStylusPreparedInBlockComment;
         internal bool SassStylusOriginalInBlockComment;
+        internal readonly ShaderReferenceExtractor.State? ShaderState;
+        internal readonly Func<string, bool> IsIgnoredCallName;
 
-        internal CoreReferenceLoopMutableState(string language, string[] lines)
+        internal CoreReferenceLoopState(CoreReferenceLoopContext loop)
         {
+            var language = loop.Request.Language;
+            var preparation = loop.Preparation;
+            PendingCSharpWhereConstraint = language == "csharp"
+                ? new CSharpWhereConstraintState()
+                : null;
+            CSharpLocalNamesByFunction = language == "csharp"
+                ? new Dictionary<string, HashSet<string>>(StringComparer.Ordinal)
+                : null;
+            SqlState = language == "sql"
+                ? SqlReferenceExtractor.CreateState()
+                : null;
+            XamlBindingPropertyElementState = language == "xml"
+                ? new XamlReferenceExtractor.BindingPropertyElementState()
+                : null;
+            XamlBindingMarkupExtensionState = language == "xml"
+                ? new XamlReferenceExtractor.BindingMarkupExtensionState()
+                : null;
             if (language is "graphql" or "html" or "markdown")
             {
                 MarkupSchemaState =
-                    MarkupSchemaReferenceExtractor.CreateState(language, lines);
+                    MarkupSchemaReferenceExtractor.CreateState(
+                        language,
+                        preparation.Lines);
             }
             if (language == "sass")
             {
@@ -73,710 +108,46 @@ internal CoreReferenceLoopMutableState(string language, string[] lines)
                 SassOriginalCommentState =
                     new CssReferenceExtractor.SassLoudCommentState();
             }
+
+            ShaderState = ShaderReferenceExtractor.CreateState(
+                language,
+                preparation.PreparedLines,
+                loop.Request.Symbols,
+                loop.Request.WorkspaceSymbols,
+                loop.Request.ReportDiagnostic);
+            IsIgnoredCallName =
+                name => ReferenceExtractor.IsIgnoredCallName(language, name);
         }
     }
 
+    private readonly record struct CorePreparedReferenceLine(
+        CoreReferenceLineContext Line,
+        string OriginalLineForLanguage,
+        List<(int start, int end)>? CSharpAttributeRanges,
+        List<(int start, int end)>? CSharpAttributeTopLevelRanges,
+        CoreLineDefinitionState DefinitionState,
+        (SymbolRecord Synthetic, int NameIndex, int OpenBraceIndex, int CloseBraceIndex)? JavaSameLineCtor,
+        CoreReferenceLineContainerResolver ContainerResolver);
+
     private static CSharpMultiLineTypePatternState EmitCoreReferenceLines(
         CoreReferenceLoopContext loop)
     {
-        var request = loop.Request;
-        var fileId = request.FileId;
-        var language = request.Language;
-        var symbols = request.Symbols;
-        var workspaceSymbols = request.WorkspaceSymbols;
-        var input = loop.Preparation;
-        var lines = input.Lines;
-        var preparedLines = input.PreparedLines;
-        var structuralLines = input.StructuralLines;
-        var referenceStructuralLines = input.ReferenceStructuralLines;
-        var references = loop.References;
-        var seen = loop.Seen;
-        var containerCandidates = loop.ContainerCandidates;
-        var containerResolver = loop.ContainerResolver;
-        var lookups = loop.Lookups;
-        var csharpAttrRanges = loop.CSharpAttributeRanges;
-        var csharpAttrTopLevelRanges = loop.CSharpAttributeTopLevelRanges;
-        var csharpUsingAliases = loop.CSharpUsingAliases;
-        var csharpUsingStatics = loop.CSharpUsingStatics;
-        var dynamicDeclarativeState = loop.DynamicDeclarativeState;
-        Func<string, bool> isIgnoredCallName =
-            name => IsIgnoredCallName(language, name);
-        var pendingCSharpMultiLineTypePattern =
-            default(CSharpMultiLineTypePatternState);
-        var pendingCSharpWhereConstraint = language == "csharp"
-            ? new CSharpWhereConstraintState()
-            : null;
-        var csharpLocalNamesByFunction = language == "csharp"
-            ? new Dictionary<string, HashSet<string>>(StringComparer.Ordinal)
-            : null;
-        var sqlState = language == "sql"
-            ? SqlReferenceExtractor.CreateState()
-            : null;
-        var xamlInXmlComment = false;
-        var xamlBindingPropertyElementState = language == "xml"
-            ? new XamlReferenceExtractor.BindingPropertyElementState()
-            : null;
-        var xamlBindingMarkupExtensionState = language == "xml"
-            ? new XamlReferenceExtractor.BindingMarkupExtensionState()
-            : null;
-        var mutableState = new CoreReferenceLoopMutableState(language, lines);
-        var shaderState = ShaderReferenceExtractor.CreateState(
-            language,
-            preparedLines,
-            symbols,
-            workspaceSymbols,
-            request.ReportDiagnostic);
-
-        for (var i = 0; i < lines.Length; i++)
+        var state = new CoreReferenceLoopState(loop);
+        for (var lineIndex = 0;
+             lineIndex < loop.Preparation.Lines.Length;
+             lineIndex++)
         {
-            if (ReferenceLimitReached(references))
-                break;
-
-            if ((i & 0x3f) == 0)
-                request.CancellationToken.ThrowIfCancellationRequested();
-
-            var lineNumber = i + 1;
-            var originalLine = lines[i];
-            var languageLines = PrepareCoreLanguageLine(
-                loop,
-                mutableState,
-                i,
-                originalLine);
-            var preparedLine = languageLines.PreparedLine;
-            var preparedLineIsWhiteSpace =
-                string.IsNullOrWhiteSpace(preparedLine);
-            var originalLineForLanguage =
-                languageLines.OriginalLineForLanguage;
-            var csharpAttrRangesOnLine = csharpAttrRanges?[i];
-            var csharpAttrTopLevelOnLine = csharpAttrTopLevelRanges?[i];
-            if (EmitCoreDocumentationAndSpecialLineReferences(
-                    loop,
-                    mutableState,
-                    i,
-                    originalLine,
-                    preparedLine,
-                    preparedLineIsWhiteSpace,
-                    csharpAttrRangesOnLine,
-                    out var sourceContext))
-            {
-                continue;
-            }
-
-            if (preparedLineIsWhiteSpace)
-            {
-                if (language == "csharp"
-                    && (pendingCSharpMultiLineTypePattern.WaitingForHead
-                        || pendingCSharpMultiLineTypePattern
-                            .PendingTypeExpression != null))
-                {
-                    continue;
-                }
-
-                if (language == "csharp")
-                {
-                    CSharpReferenceExtractor
-                        .FlushPendingMultiLineTypePatternReference(
-                            ref pendingCSharpMultiLineTypePattern,
-                            loop.CSharpQualifiedConstantPatternMemberLookup,
-                            csharpUsingAliases,
-                            csharpUsingStatics,
-                            lookups.HasActiveSameFileCSharpTypeCandidate,
-                            references,
-                            seen,
-                            fileId);
-                }
-                continue;
-            }
-
-            if (sourceContext.Length == 0)
-                continue;
-
-            var definitionNames =
-                loop.DefinitionNamesByLine.TryGetValue(
-                    lineNumber,
-                    out var namesOnLine)
-                    ? namesOnLine
-                    : null;
-            Dictionary<string, HashSet<int>>?
-                scientificDefinitionNameIndices = null;
-            loop.ScientificDefinitionNameIndicesByLine?.TryGetValue(
-                lineNumber,
-                out scientificDefinitionNameIndices);
-            List<SqlReferenceExtractor.DefinitionLeafSpan>?
-                sqlDefinitionLeafSpans = null;
-            if (language == "sql")
-            {
-                loop.SqlDefinitionLeafSpansByLine?.TryGetValue(
-                    lineNumber,
-                    out sqlDefinitionLeafSpans);
-            }
-            var container = containerResolver.Find(lineNumber);
-            var definitionState = new CoreLineDefinitionState(
-                language,
-                sourceContext,
-                preparedLine,
-                definitionNames,
-                loop.DefinitionNamesComparer,
-                scientificDefinitionNameIndices,
-                sqlDefinitionLeafSpans);
-            var csharpLineHasWhereClause = language == "csharp"
-                && preparedLine.IndexOf(
-                    "where",
-                    StringComparison.Ordinal) >= 0
-                && CSharpWhereClauseRegex.IsMatch(preparedLine);
-
-            (SymbolRecord Synthetic, int NameIndex, int OpenBraceIndex,
-                int CloseBraceIndex)? javaSameLineCtor = null;
-            if (language == "java")
-            {
-                javaSameLineCtor =
-                    JavaReferenceExtractor.TryBuildSameLineCtorSpan(
-                        preparedLine,
-                        lineNumber,
-                        lookups.GetEnclosingTypeCandidates);
-            }
-
-            SymbolRecord? ResolveContainerForCall(int column)
-            {
-                if (language == "csharp")
-                {
-                    SymbolRecord? primaryCtorOwner = null;
-                    foreach (var (
-                                 rangeStart,
-                                 rangeStartColumn,
-                                 rangeEnd,
-                                 rangeEndColumn,
-                                 syntheticRecordCtor,
-                                 owner) in
-                             lookups.GetRecordPrimaryCtorRanges())
-                    {
-                        if (ReferenceEquals(container, syntheticRecordCtor)
-                            || (container?.Kind == "function"
-                                && container.FileId == syntheticRecordCtor.FileId
-                                && container.StartLine == syntheticRecordCtor.StartLine
-                                && (container.StartLine < rangeEnd
-                                    || (container.StartColumn is int containerStartColumn
-                                        && containerStartColumn < rangeEndColumn))
-                                && string.Equals(
-                                    container.Name,
-                                    syntheticRecordCtor.Name,
-                                    StringComparison.Ordinal)))
-                        {
-                            primaryCtorOwner ??= owner;
-                        }
-                        if (lineNumber < rangeStart || lineNumber > rangeEnd)
-                            continue;
-                        if (lineNumber == rangeStart
-                            && column < rangeStartColumn)
-                        {
-                            return owner;
-                        }
-                        if (lineNumber == rangeEnd && column >= rangeEndColumn)
-                            continue;
-                        return syntheticRecordCtor;
-                    }
-
-                    if (primaryCtorOwner != null)
-                        return primaryCtorOwner;
-                }
-
-                if (javaSameLineCtor != null)
-                {
-                    var info = javaSameLineCtor.Value;
-                    if (info.CloseBraceIndex >= 0
-                        && column > info.OpenBraceIndex
-                        && column < info.CloseBraceIndex)
-                    {
-                        return info.Synthetic;
-                    }
-                }
-
-                if (language == "csharp")
-                {
-                    if (csharpLineHasWhereClause)
-                    {
-                        var declarationRangeContainer =
-                            FindInnermostCSharpDeclarationRangeContainer(
-                                containerCandidates,
-                                structuralLines[i],
-                                lineNumber,
-                                column);
-                        if (declarationRangeContainer != null)
-                            return declarationRangeContainer;
-                    }
-
-                    var sameLineContainer =
-                        FindInnermostSameLineCSharpContainer(
-                            lookups
-                                .GetCSharpSameLineContainerCandidatesByLine(),
-                            structuralLines[i],
-                            lineNumber,
-                            column);
-                    if (sameLineContainer != null)
-                        return sameLineContainer;
-
-                    if (csharpLineHasWhereClause
-                        && container?.Kind == "function"
-                        && container.StartLine == lineNumber
-                        && (!TryFindCSharpFunctionNameColumn(
-                                structuralLines[i],
-                                container.Name,
-                                out var containerNameColumn)
-                            || column < containerNameColumn))
-                    {
-                        return null;
-                    }
-                }
-
-                return dynamicDeclarativeState?.ResolveContainer(
-                    lineNumber,
-                    column,
-                    container) ?? container;
-            }
-
-            SymbolRecord? ResolveSwiftPropertyContainerForCall(int column)
-            {
-                if (loop.SwiftPropertyDefinitionsByLine != null
-                    && loop.SwiftPropertyDefinitionsByLine.TryGetValue(
-                        lineNumber,
-                        out var sameLineProperties))
-                {
-                    foreach (var property in sameLineProperties)
-                    {
-                        if ((property.StartColumn ?? 0) <= column)
-                            return property;
-                    }
-                }
-
-                return ResolveContainerForCall(column);
-            }
-
-            var lineContext = new CoreReferenceLineContext(
-                fileId,
-                language,
-                lines,
-                preparedLines,
-                i,
-                preparedLine,
-                originalLine,
-                sourceContext,
-                lineNumber,
-                references,
-                seen,
-                container,
-                definitionNames,
-                ResolveContainerForCall,
-                isIgnoredCallName);
-
-            if (shaderState is not null)
-            {
-                ShaderReferenceExtractor.EmitLineReferences(
-                    shaderState,
-                    preparedLine,
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    sourceContext,
-                    lineNumber,
-                    ResolveContainerForCall);
-            }
-
-            if (ReferenceLimitReached(references))
-                break;
-
-            if (loop.IsJsxFile
-                && language is "javascript" or "typescript")
-            {
-                EmitJsxElementReferences(lineContext);
-            }
-
-            if (ReferenceLimitReached(references))
-                break;
-
-            var typeContext = new CoreTypeReferenceContext(
-                lineContext,
-                lookups,
-                containerCandidates,
-                symbols,
-                structuralLines,
-                loop.CSharpQualifiedConstantPatternMemberLookup,
-                loop.CSharpQualifiedTypePatternLookup,
-                csharpUsingAliases,
-                csharpUsingStatics,
-                csharpLocalNamesByFunction,
-                pendingCSharpWhereConstraint,
-                loop.KotlinConstructorTypeNames,
-                input.TypeScriptNamespaceAliases,
-                loop.TypeScriptTypeAliases,
-                loop.SwiftTypeAliases,
-                ResolveSwiftPropertyContainerForCall,
-                input.GoImportBlockLines,
-                input.LuaReferenceLines,
-                originalLineForLanguage,
-                loop.AllDefinitionNames,
-                loop.StylusVariableDefinitionNames,
-                loop.XamlReferenceEnabled,
-                xamlBindingPropertyElementState,
-                xamlBindingMarkupExtensionState);
-            if (EmitCoreTypeReferences(
-                    typeContext,
-                    ref pendingCSharpMultiLineTypePattern,
-                    ref xamlInXmlComment))
-            {
-                continue;
-            }
-
-            if (ReferenceLimitReached(references))
-                break;
-
-            EmitInfrastructureLineReferences(
-                lineContext,
-                loop.DockerfileStageNames,
-                loop.DockerfileVariableNames,
-                loop.CobolCallableSymbols);
-
-            if (ReferenceLimitReached(references))
-                break;
-
-            var sqlSuppressedCallIndices = EmitSqlLineReferences(
-                lineContext,
-                structuralLines[i],
-                sqlState,
-                definitionState);
-
-            if (ReferenceLimitReached(references))
-                break;
-
-            if (language is "csharp" or "java")
-                EmitParenlessInitializerReferences(lineContext);
-
-            EmitPhpAndScssLineReferences(lineContext);
-
-            if (ReferenceLimitReached(references))
-                break;
-
-            var callContext = new CoreCallReferenceContext(
-                lineContext,
-                lookups,
-                javaSameLineCtor,
-                csharpAttrRangesOnLine,
-                loop.KotlinConstructorTypeNames,
-                loop.KotlinInfixFunctionNames,
-                loop.ShellCallableNames,
-                loop.ShellGlobalAliasNames,
-                dynamicDeclarativeState,
-                referenceStructuralLines[i],
-                loop.ScientificNativeDependencyLimit,
-                request.ReportDiagnostic,
-                sqlSuppressedCallIndices,
-                loop.SqlWindowFunctionCallSiteSuppressions,
-                definitionState);
-            EmitCoreCallReferences(callContext);
-
-            if (ReferenceLimitReached(references))
-                break;
-
-            EmitCoreMethodAndMemberReferences(
-                loop,
-                lineContext,
-                preparedLine,
-                csharpAttrRangesOnLine,
-                ResolveContainerForCall);
-
-            if (ReferenceLimitReached(references))
-                break;
-
-            if (input.JsTaggedTemplatesByLine != null
-                && input.JsTaggedTemplatesByLine.TryGetValue(
-                    lineNumber,
-                    out var tagHitsOnLine))
-            {
-                EmitJavaScriptTaggedTemplateReferences(
-                    lineContext,
-                    tagHitsOnLine);
-            }
-
-            if (ReferenceLimitReached(references))
+            if (ReferenceLimitReached(loop.References))
                 break;
 
-            EmitMetadataLineReferences(
-                lineContext,
-                csharpAttrTopLevelOnLine);
+            if ((lineIndex & 0x3f) == 0)
+                loop.Request.CancellationToken.ThrowIfCancellationRequested();
 
-            if (ReferenceLimitReached(references))
+            var flow = ProcessCoreReferenceLine(loop, state, lineIndex);
+            if (flow == CoreReferenceLineFlow.StopExtraction)
                 break;
-
-            if (loop.IsRazorFile && language == "csharp")
-            {
-                RazorReferenceExtractor.EmitReferences(
-                    input.RazorReferenceLines?[i] ?? originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    sourceContext,
-                    lineNumber,
-                    ResolveContainerForCall,
-                    definitionNames,
-                    loop.FileDefinitionNames,
-                    input.RazorImplementedTypeNames);
-            }
-
-            if (ReferenceLimitReached(references))
-                break;
-
-            if (language == "python")
-            {
-                EmitPythonLineReferences(
-                    lineContext,
-                    lookups);
-            }
-            if (language == "r")
-                EmitRLineReferences(lineContext);
-        }
-
-        return pendingCSharpMultiLineTypePattern;
-    }
-
-    private static (
-        string PreparedLine,
-        string OriginalLineForLanguage) PrepareCoreLanguageLine(
-        CoreReferenceLoopContext loop,
-        CoreReferenceLoopMutableState state,
-        int lineIndex,
-        string originalLine)
-    {
-        var input = loop.Preparation;
-        var preparedLine = input.LuaPreparedLines?[lineIndex]
-            ?? input.LispReferenceLines?[lineIndex]
-            ?? input.PreparedLines[lineIndex];
-        var originalLineForLanguage = originalLine;
-        if (loop.Request.Language == "sass")
-        {
-            preparedLine = CssReferenceExtractor.MaskSassBlockCommentLine(
-                preparedLine,
-                state.SassPreparedCommentState!);
-            originalLineForLanguage =
-                CssReferenceExtractor.MaskSassBlockCommentLine(
-                    originalLine,
-                    state.SassOriginalCommentState!);
-        }
-        else if (loop.Request.Language == "stylus")
-        {
-            preparedLine =
-                CssReferenceExtractor.MaskSassStylusBlockCommentLine(
-                    preparedLine,
-                    ref state.SassStylusPreparedInBlockComment);
-            originalLineForLanguage =
-                CssReferenceExtractor.MaskSassStylusBlockCommentLine(
-                    originalLine,
-                    ref state.SassStylusOriginalInBlockComment);
-        }
-
-        return (preparedLine, originalLineForLanguage);
-    }
-
-    private static bool EmitCoreDocumentationAndSpecialLineReferences(
-        CoreReferenceLoopContext loop,
-        CoreReferenceLoopMutableState state,
-        int lineIndex,
-        string originalLine,
-        string preparedLine,
-        bool preparedLineIsWhiteSpace,
-        List<(int start, int end)>? csharpAttributeRangesOnLine,
-        out string sourceContext)
-    {
-        var request = loop.Request;
-        var input = loop.Preparation;
-        var lineNumber = lineIndex + 1;
-        if (request.Language is "csharp" or "java" or "kotlin" or "r" or "php")
-        {
-            Func<SymbolRecord?>? getPhpLineContainer = null;
-            if (request.Language == "php")
-            {
-                SymbolRecord? phpLineContainer = null;
-                var phpLineContainerResolved = false;
-
-                SymbolRecord? GetPhpLineContainer()
-                {
-                    if (!phpLineContainerResolved)
-                    {
-                        phpLineContainer =
-                            loop.ContainerResolver.Find(lineNumber);
-                        phpLineContainerResolved = true;
-                    }
-
-                    return phpLineContainer;
-                }
-
-                getPhpLineContainer = GetPhpLineContainer;
-            }
-
-            var documentationLine = new CoreDocumentationLineContext(
-                request.FileId,
-                request.Language,
-                input.Lines,
-                input.PreparedLines,
-                input.StructuralLines,
-                lineIndex,
-                lineNumber,
-                originalLine,
-                preparedLine,
-                loop.References,
-                loop.Seen,
-                loop.ContainerCandidates,
-                loop.ContainerResolver,
-                loop.Lookups,
-                input.CSharpLinesInsideMultilineStringContent,
-                input.CSharpLinesInsideBlockComment,
-                csharpAttributeRangesOnLine,
-                loop.CSharpAttributeRanges,
-                getPhpLineContainer);
-            EmitCoreDocumentationReferences(
-                documentationLine,
-                ref state.CSharpInDelimitedDocComment,
-                ref state.JvmInDelimitedDocComment,
-                ref state.PhpInDocblock,
-                ref state.PhpDocblockContainer,
-                ref state.PhpDocblockPropertyNames);
-        }
-
-        if (preparedLineIsWhiteSpace
-            && request.Language
-                is not ("cmake"
-                    or "justfile"
-                    or "makefile"
-                    or "msbuild"
-                    or "graphql"
-                    or "html"
-                    or "markdown"))
-        {
-            sourceContext = string.Empty;
-            return false;
-        }
-
-        sourceContext = originalLine.Trim();
-        if (request.Language
-                is "cmake" or "justfile" or "makefile" or "msbuild"
-            && sourceContext.Length > 0)
-        {
-            BuildAutomationReferenceExtractor.EmitReferences(
-                request.Language,
-                originalLine,
-                sourceContext,
-                lineNumber,
-                loop.References,
-                loop.Seen,
-                request.FileId,
-                loop.ContainerResolver.Find(lineNumber));
-            return true;
-        }
-
-        if (request.Language is not ("graphql" or "html" or "markdown")
-            || sourceContext.Length == 0)
-        {
-            return false;
-        }
-
-        MarkupSchemaReferenceExtractor.EmitReferences(
-            request.Language,
-            originalLine,
-            sourceContext,
-            lineNumber,
-            loop.References,
-            loop.Seen,
-            request.FileId,
-            loop.ContainerResolver.Find(lineNumber),
-            state.MarkupSchemaState);
-        return true;
-    }
-
-    private static void EmitCoreMethodAndMemberReferences(
-        CoreReferenceLoopContext loop,
-        CoreReferenceLineContext line,
-        string preparedLine,
-        List<(int start, int end)>? csharpAttributeRanges,
-        Func<int, SymbolRecord?> resolveContainerForCall)
-    {
-        var language = line.Language;
-        if (language == "csharp")
-        {
-            EmitMethodGroupReferences(
-                language,
-                preparedLine,
-                loop.CallableDefinitionNames,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                resolveContainerForCall);
-        }
-        else if (language == "java")
-        {
-            JavaReferenceExtractor.EmitMethodReferenceReferences(
-                preparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                resolveContainerForCall);
-        }
-        else if (language == "kotlin")
-        {
-            KotlinReferenceExtractor.EmitMethodReferenceReferences(
-                preparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                resolveContainerForCall);
-        }
-        else if (language == "scala")
-        {
-            ScalaReferenceExtractor.EmitMethodReferenceReferences(
-                preparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                resolveContainerForCall);
-        }
-
-        if (language == "csharp")
-        {
-            CSharpReferenceExtractor.EmitStaticMemberQualifierReferences(
-                preparedLine,
-                csharpAttributeRanges,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                resolveContainerForCall);
-        }
-
-        if (language != "csharp"
-            || loop.CSharpQualifiedEnumMemberLookup.Count == 0)
-        {
-            return;
         }
 
-        CSharpReferenceExtractor.EmitQualifiedEnumMemberReferences(
-            preparedLine,
-            loop.CSharpQualifiedEnumMemberLookup,
-            csharpAttributeRanges,
-            loop.CSharpUsingAliases,
-            loop.Lookups.GetCSharpValueReceiverNames,
-            loop.Lookups.GetCSharpFunctionValueReceiverNames,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            resolveContainerForCall);
+        return state.PendingCSharpMultiLineTypePattern;
     }
 }
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
new file mode 100644
index 000000000..620274cd8
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
@@ -0,0 +1,291 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static CoreReferenceLineFlow EmitCoreOrderedReferencePhases(
+        CoreReferenceLoopContext loop,
+        CoreReferenceLoopState state,
+        CorePreparedReferenceLine prepared)
+    {
+        var initialFlow = EmitCoreInitialReferencePhases(
+            loop,
+            state,
+            prepared);
+        if (initialFlow != CoreReferenceLineFlow.Continue)
+            return initialFlow;
+
+        return EmitCoreRemainingReferencePhases(loop, state, prepared);
+    }
+
+    private static CoreReferenceLineFlow EmitCoreInitialReferencePhases(
+        CoreReferenceLoopContext loop,
+        CoreReferenceLoopState state,
+        CorePreparedReferenceLine prepared)
+    {
+        var request = loop.Request;
+        var input = loop.Preparation;
+        var line = prepared.Line;
+        if (state.ShaderState is not null)
+        {
+            ShaderReferenceExtractor.EmitLineReferences(
+                state.ShaderState,
+                line.PreparedLine,
+                line.OriginalLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall);
+        }
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        if (loop.IsJsxFile
+            && line.Language is "javascript" or "typescript")
+        {
+            EmitJsxElementReferences(line);
+        }
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        var typeContext = new CoreTypeReferenceContext(
+            line,
+            loop.Lookups,
+            loop.ContainerCandidates,
+            request.Symbols,
+            input.StructuralLines,
+            loop.CSharpQualifiedConstantPatternMemberLookup,
+            loop.CSharpQualifiedTypePatternLookup,
+            loop.CSharpUsingAliases,
+            loop.CSharpUsingStatics,
+            state.CSharpLocalNamesByFunction,
+            state.PendingCSharpWhereConstraint,
+            loop.KotlinConstructorTypeNames,
+            input.TypeScriptNamespaceAliases,
+            loop.TypeScriptTypeAliases,
+            loop.SwiftTypeAliases,
+            prepared.ContainerResolver
+                .ResolveSwiftPropertyContainerForCall,
+            input.GoImportBlockLines,
+            input.LuaReferenceLines,
+            prepared.OriginalLineForLanguage,
+            loop.AllDefinitionNames,
+            loop.StylusVariableDefinitionNames,
+            loop.XamlReferenceEnabled,
+            state.XamlBindingPropertyElementState,
+            state.XamlBindingMarkupExtensionState);
+        if (EmitCoreTypeReferences(
+                typeContext,
+                ref state.PendingCSharpMultiLineTypePattern,
+                ref state.XamlInXmlComment))
+        {
+            return CoreReferenceLineFlow.LineConsumed;
+        }
+
+        return ReferenceLimitReached(line.References)
+            ? CoreReferenceLineFlow.StopExtraction
+            : CoreReferenceLineFlow.Continue;
+    }
+
+    private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
+        CoreReferenceLoopContext loop,
+        CoreReferenceLoopState state,
+        CorePreparedReferenceLine prepared)
+    {
+        var request = loop.Request;
+        var input = loop.Preparation;
+        var line = prepared.Line;
+        EmitInfrastructureLineReferences(
+            line,
+            loop.DockerfileStageNames,
+            loop.DockerfileVariableNames,
+            loop.CobolCallableSymbols);
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        var sqlSuppressedCallIndices = EmitSqlLineReferences(
+            line,
+            input.StructuralLines[line.LineIndex],
+            state.SqlState,
+            prepared.DefinitionState);
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        if (line.Language is "csharp" or "java")
+            EmitParenlessInitializerReferences(line);
+
+        EmitPhpAndScssLineReferences(line);
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        var callContext = new CoreCallReferenceContext(
+            line,
+            loop.Lookups,
+            prepared.JavaSameLineCtor,
+            prepared.CSharpAttributeRanges,
+            loop.KotlinConstructorTypeNames,
+            loop.KotlinInfixFunctionNames,
+            loop.ShellCallableNames,
+            loop.ShellGlobalAliasNames,
+            loop.DynamicDeclarativeState,
+            input.ReferenceStructuralLines[line.LineIndex],
+            loop.ScientificNativeDependencyLimit,
+            request.ReportDiagnostic,
+            sqlSuppressedCallIndices,
+            loop.SqlWindowFunctionCallSiteSuppressions,
+            prepared.DefinitionState);
+        EmitCoreCallReferences(callContext);
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        EmitCoreMethodAndMemberReferences(
+            loop,
+            line,
+            prepared.CSharpAttributeRanges,
+            prepared.ContainerResolver.ResolveContainerForCall);
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        if (input.JsTaggedTemplatesByLine != null
+            && input.JsTaggedTemplatesByLine.TryGetValue(
+                line.LineNumber,
+                out var tagHitsOnLine))
+        {
+            EmitJavaScriptTaggedTemplateReferences(line, tagHitsOnLine);
+        }
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        EmitMetadataLineReferences(
+            line,
+            prepared.CSharpAttributeTopLevelRanges);
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        if (loop.IsRazorFile && line.Language == "csharp")
+        {
+            RazorReferenceExtractor.EmitReferences(
+                input.RazorReferenceLines?[line.LineIndex]
+                    ?? line.OriginalLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall,
+                line.DefinitionNames,
+                loop.FileDefinitionNames,
+                input.RazorImplementedTypeNames);
+        }
+
+        if (ReferenceLimitReached(line.References))
+            return CoreReferenceLineFlow.StopExtraction;
+
+        if (line.Language == "python")
+            EmitPythonLineReferences(line, loop.Lookups);
+        if (line.Language == "r")
+            EmitRLineReferences(line);
+
+        return CoreReferenceLineFlow.Continue;
+    }
+
+    private static void EmitCoreMethodAndMemberReferences(
+        CoreReferenceLoopContext loop,
+        CoreReferenceLineContext line,
+        List<(int start, int end)>? csharpAttributeRanges,
+        Func<int, SymbolRecord?> resolveContainerForCall)
+    {
+        var language = line.Language;
+        if (language == "csharp")
+        {
+            EmitMethodGroupReferences(
+                language,
+                line.PreparedLine,
+                loop.CallableDefinitionNames,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                resolveContainerForCall);
+        }
+        else if (language == "java")
+        {
+            JavaReferenceExtractor.EmitMethodReferenceReferences(
+                line.PreparedLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                resolveContainerForCall);
+        }
+        else if (language == "kotlin")
+        {
+            KotlinReferenceExtractor.EmitMethodReferenceReferences(
+                line.PreparedLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                resolveContainerForCall);
+        }
+        else if (language == "scala")
+        {
+            ScalaReferenceExtractor.EmitMethodReferenceReferences(
+                line.PreparedLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                resolveContainerForCall);
+        }
+
+        if (language == "csharp")
+        {
+            CSharpReferenceExtractor.EmitStaticMemberQualifierReferences(
+                line.PreparedLine,
+                csharpAttributeRanges,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                resolveContainerForCall);
+        }
+
+        if (language != "csharp"
+            || loop.CSharpQualifiedEnumMemberLookup.Count == 0)
+        {
+            return;
+        }
+
+        CSharpReferenceExtractor.EmitQualifiedEnumMemberReferences(
+            line.PreparedLine,
+            loop.CSharpQualifiedEnumMemberLookup,
+            csharpAttributeRanges,
+            loop.CSharpUsingAliases,
+            loop.Lookups.GetCSharpValueReceiverNames,
+            loop.Lookups.GetCSharpFunctionValueReceiverNames,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            resolveContainerForCall);
+    }
+}

From 9bcb7a5fa7bc6b50af6a4fedc3119176108f4f72 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 07:37:15 +0900
Subject: [PATCH 09/45] Unify indexed find scanning

---
 .../Database/DbReader.FilesStatus.cs          | 784 ++----------------
 .../Database/FindSnippetAssembler.cs          | 102 +++
 .../Database/IndexedFindCollectors.cs         | 213 +++++
 src/CodeIndex/Database/IndexedFindModels.cs   | 172 ++++
 src/CodeIndex/Database/IndexedFindPipeline.cs | 320 +++++++
 .../Database/IndexedFindQuerySource.cs        | 193 +++++
 6 files changed, 1050 insertions(+), 734 deletions(-)
 create mode 100644 src/CodeIndex/Database/FindSnippetAssembler.cs
 create mode 100644 src/CodeIndex/Database/IndexedFindCollectors.cs
 create mode 100644 src/CodeIndex/Database/IndexedFindModels.cs
 create mode 100644 src/CodeIndex/Database/IndexedFindPipeline.cs
 create mode 100644 src/CodeIndex/Database/IndexedFindQuerySource.cs

diff --git a/src/CodeIndex/Database/DbReader.FilesStatus.cs b/src/CodeIndex/Database/DbReader.FilesStatus.cs
index 812b559a5..978e5cb96 100644
--- a/src/CodeIndex/Database/DbReader.FilesStatus.cs
+++ b/src/CodeIndex/Database/DbReader.FilesStatus.cs
@@ -98,302 +98,44 @@ internal static int? LegacyResourceReadSqliteVmStepLimitForTesting
         set => LegacyResourceReadSqliteVmStepLimitOverride.Value = value;
     }
 
+    private static Regex CreateFindRegexMatcher(string query, bool exact)
+        => RegexRegistry.CreateFindRegex(query, exact, ResolveFindRegexMatchTimeout());
+
+    private static TimeSpan ResolveFindRegexMatchTimeout()
+        => FindRegexMatchTimeoutForTesting is { } timeout && timeout > TimeSpan.Zero
+            ? timeout
+            : BoundedRegex.DefaultMatchTimeout;
+
     public FindResults FindInFiles(string query, int limit, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, int before = 0, int after = 0, bool exact = false, int maxLineWidth = LineWidthFormatter.DefaultMaxLineWidth, int? focusLine = null, int? focusColumn = null, bool regex = false, int? maxCandidateFiles = null, int? maxLinesScanned = null, int offset = 0, bool useIndexedLiteralCandidates = false, string? resumePath = null, int? resumeLine = null, int? resumeFileOrdinal = null, int? resumeMatchOrdinal = null, int? resumeByteOffset = null, bool captureContinuation = false, CancellationToken cancellationToken = default)
     {
-        cancellationToken.ThrowIfCancellationRequested();
-        if (string.IsNullOrWhiteSpace(query) || limit <= 0)
-            return new FindResults([], new FindScanSummary(0, 0, 0));
-        ValidateFindContinuation(
-            resumePath,
-            resumeLine,
-            resumeFileOrdinal,
-            resumeMatchOrdinal,
-            resumeByteOffset);
-
-        before = Math.Max(0, before);
-        after = Math.Max(0, after);
-        maxLineWidth = LineWidthFormatter.ClampMaxLineWidth(maxLineWidth);
-        var comparison = exact ? StringComparison.Ordinal : StringComparison.OrdinalIgnoreCase;
-        var regexMatcher = regex
-            ? CreateFindRegexMatcher(query, exact)
-            : null;
-
-        var searchPlan = CreateFindSearchPlan(query, exact, regex, useIndexedLiteralCandidates);
-        using var fileCmd = CreateFindFileCommand(
-            searchPlan,
+        var scanRequest = new IndexedFindScanRequest(
+            query,
             lang,
             pathPatterns,
             excludePathPatterns,
-            excludeTests);
-
-        var candidateFiles = CountFindCandidateFiles(lang, pathPatterns, excludePathPatterns, excludeTests);
-        var filesScanned = 0;
-        var linesScanned = 0;
-        var truncated = false;
-        string? truncationReason = null;
-        string? nextPath = null;
-        int? nextLine = null;
-        int? nextFileOrdinal = null;
-        int? nextMatchOrdinal = null;
-        int? nextByteOffset = null;
-        var resultLimitReached = false;
-        var matchesSkipped = 0;
-        offset = Math.Max(0, offset);
-        var resumePending = resumePath is not null;
-        var resumeMatchPending = resumeMatchOrdinal.HasValue;
-        var candidateFileOrdinal = -1;
-        var results = new List<FileFindResult>();
-        using var fileReader = fileCmd.ExecuteTrackedReader();
-        while (fileReader.TrackedRead())
-        {
-            cancellationToken.ThrowIfCancellationRequested();
-            if (!captureContinuation && results.Count >= limit)
-                break;
-            candidateFileOrdinal++;
-            var fileId = fileReader.GetInt64(0);
-            var path = fileReader.GetString(1);
-            var fileLang = GetNullableString(fileReader, 2);
-            var totalLines = fileReader.GetInt32(3);
-            if (resumePending)
-            {
-                if (resumeFileOrdinal.HasValue)
-                {
-                    if (candidateFileOrdinal < resumeFileOrdinal.Value)
-                        continue;
-                    if (candidateFileOrdinal != resumeFileOrdinal.Value
-                        || !string.Equals(path, resumePath, StringComparison.Ordinal))
-                    {
-                        throw new FindContinuationException(
-                            "cursor_malformed",
-                            "find cursor file position does not match the current candidate order.");
-                    }
-                }
-                else if (!string.Equals(path, resumePath, StringComparison.Ordinal))
-                {
-                    continue;
-                }
-                if (resumeLine > Math.Max(1, totalLines))
-                {
-                    throw new FindContinuationException(
-                        "cursor_malformed",
-                        "find cursor line position exceeds the selected file.");
-                }
-                resumePending = false;
-            }
-            if (maxCandidateFiles.HasValue && filesScanned >= maxCandidateFiles.Value)
-            {
-                truncated = true;
-                truncationReason ??= "candidate_file_limit";
-                nextPath = path;
-                nextLine = 1;
-                nextFileOrdinal = candidateFileOrdinal;
-                nextByteOffset = 0;
-                break;
-            }
-
-            var firstEligibleLine = string.Equals(path, resumePath, StringComparison.Ordinal)
-                ? Math.Max(1, resumeLine ?? 1)
-                : 1;
-            var firstContextLine = Math.Max(1, firstEligibleLine - before);
-            filesScanned++;
-            if (totalLines <= 0)
-                continue;
-
-            var searchQuery = exact && !regex ? ExactSourceSearchNormalizer.Normalize(query, fileLang) : query;
-            var pendingMatches = new Queue<PendingFileFindMatch>();
-            var snippetWindow = new Queue<IndexedLine>();
-            var snippetLinesByNumber = new Dictionary<int, string>();
-            var acceptedMatches = results.Count;
-            var stopScanning = false;
-
-            foreach (var indexedLine in EnumerateIndexedFileLines(fileId))
-            {
-                cancellationToken.ThrowIfCancellationRequested();
-                if (indexedLine.Number > totalLines)
-                    break;
-                if (indexedLine.Number < firstContextLine)
-                    continue;
-                var eligibleForMatch = indexedLine.Number >= firstEligibleLine;
-                if (maxLinesScanned.HasValue && linesScanned >= maxLinesScanned.Value)
-                {
-                    truncated = true;
-                    truncationReason ??= "line_scan_limit";
-                    if (nextPath is null)
-                    {
-                        nextPath = path;
-                        nextLine = indexedLine.Number;
-                        nextFileOrdinal = candidateFileOrdinal;
-                        nextByteOffset = 0;
-                    }
-                    stopScanning = true;
-                    break;
-                }
-                if (eligibleForMatch)
-                {
-                    linesScanned++;
-                    FindLineScannedForTesting?.Invoke();
-                    cancellationToken.ThrowIfCancellationRequested();
-                }
-
-                AddLineToFindWindow(indexedLine, snippetWindow, snippetLinesByNumber);
-
-                if (!resultLimitReached
-                    && (matchesSkipped < offset
-                        || captureContinuation && acceptedMatches <= limit
-                        || !captureContinuation && acceptedMatches < limit)
-                    && eligibleForMatch
-                    && (!focusLine.HasValue || indexedLine.Number == focusLine.Value))
-                {
-                    var matchOrdinal = 0;
-                    foreach (var lineMatch in EnumerateFindLineMatches(
-                        indexedLine.Text,
-                        fileLang,
-                        searchQuery,
-                        comparison,
-                        regexMatcher,
-                        exact && !regex,
-                        focusColumn))
-                    {
-                        if (resumeMatchPending
-                            && indexedLine.Number == firstEligibleLine)
-                        {
-                            if (matchOrdinal < resumeMatchOrdinal!.Value)
-                            {
-                                matchOrdinal++;
-                                continue;
-                            }
-                            var resumeBoundaryByteOffset = Encoding.UTF8.GetByteCount(
-                                indexedLine.Text.AsSpan(0, lineMatch.Column));
-                            if (matchOrdinal != resumeMatchOrdinal.Value
-                                || resumeBoundaryByteOffset != resumeByteOffset)
-                            {
-                                throw new FindContinuationException(
-                                    "cursor_malformed",
-                                    "find cursor match position is not a record boundary for the current query.");
-                            }
-                            resumeMatchPending = false;
-                        }
-
-                        if (matchesSkipped < offset)
-                        {
-                            matchesSkipped++;
-                            matchOrdinal++;
-                            continue;
-                        }
-                        if (acceptedMatches >= limit)
-                        {
-                            var byteOffset = Encoding.UTF8.GetByteCount(
-                                indexedLine.Text.AsSpan(0, lineMatch.Column));
-                            nextPath = path;
-                            nextLine = indexedLine.Number;
-                            nextFileOrdinal = candidateFileOrdinal;
-                            nextMatchOrdinal = matchOrdinal;
-                            nextByteOffset = byteOffset;
-                            resultLimitReached = true;
-                            stopScanning = true;
-                            break;
-                        }
-
-                        pendingMatches.Enqueue(new PendingFileFindMatch(
-                            indexedLine.Number,
-                            lineMatch.Column,
-                            lineMatch.Length,
-                            Math.Max(1, indexedLine.Number - before),
-                            Math.Min(totalLines, indexedLine.Number + after)));
-                        acceptedMatches++;
-                        matchOrdinal++;
-                    }
-                }
-
-                FlushReadyFindMatches(
-                    path,
-                    fileLang,
-                    pendingMatches,
-                    snippetLinesByNumber,
-                    results,
-                    maxLineWidth,
-                    indexedLine.Number);
-                PruneFindWindow(indexedLine.Number, before, pendingMatches, snippetWindow, snippetLinesByNumber);
-
-                if ((stopScanning || !captureContinuation && results.Count >= limit)
-                    && pendingMatches.Count == 0)
-                    break;
-            }
-
-            FlushReadyFindMatches(
-                path,
-                fileLang,
-                pendingMatches,
-                snippetLinesByNumber,
-                results,
-                maxLineWidth,
-                int.MaxValue);
-            if (stopScanning || !captureContinuation && results.Count >= limit)
-                break;
-        }
-        if (resumePending || resumeMatchPending)
-        {
-            throw new FindContinuationException(
-                "cursor_malformed",
-                "find cursor position does not exist in the current result sequence.");
-        }
-
-        var capReached = truncated;
-        return new FindResults(
-            results,
-            new FindScanSummary(
-                candidateFiles,
-                filesScanned,
-                linesScanned,
-                truncated,
-                capReached,
-                TimedOut: false,
-                truncationReason,
-                maxCandidateFiles,
-                maxLinesScanned,
-                searchPlan.Strategy,
-                searchPlan.FallbackReason,
-                nextPath,
-                nextLine,
-                nextFileOrdinal,
-                nextMatchOrdinal,
-                nextByteOffset,
-                resultLimitReached));
-    }
-
-    private static void ValidateFindContinuation(
-        string? resumePath,
-        int? resumeLine,
-        int? resumeFileOrdinal,
-        int? resumeMatchOrdinal,
-        int? resumeByteOffset)
-    {
-        if (resumePath is null)
-        {
-            if (resumeLine.HasValue
-                || resumeFileOrdinal.HasValue
-                || resumeMatchOrdinal.HasValue
-                || resumeByteOffset.HasValue)
-            {
-                throw new FindContinuationException(
-                    "cursor_malformed",
-                    "find cursor continuation fields require a resume path.");
-            }
-            return;
-        }
-
-        if (!resumeLine.HasValue
-            || resumeLine.Value <= 0
-            || resumeFileOrdinal is < 0
-            || resumeMatchOrdinal is < 0
-            || resumeByteOffset is < 0
-            || resumeMatchOrdinal.HasValue && !resumeByteOffset.HasValue
-            || !resumeMatchOrdinal.HasValue && resumeByteOffset is not (null or 0))
-        {
-            throw new FindContinuationException(
-                "cursor_malformed",
-                "find cursor continuation position is invalid.");
-        }
+            excludeTests,
+            exact,
+            focusLine,
+            focusColumn,
+            regex,
+            maxCandidateFiles,
+            maxLinesScanned,
+            useIndexedLiteralCandidates,
+            new FindResumePosition(
+                resumePath,
+                resumeLine,
+                resumeFileOrdinal,
+                resumeMatchOrdinal,
+                resumeByteOffset),
+            cancellationToken);
+        return new IndexedFindPipeline(this).Find(new IndexedFindListRequest(
+            scanRequest,
+            limit,
+            before,
+            after,
+            maxLineWidth,
+            offset,
+            captureContinuation));
     }
 
     public int CountFindCandidateFiles(string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false)
@@ -413,452 +155,26 @@ public int CountFindCandidateFiles(string? lang = null, IReadOnlyList<string>? p
 
     public FindCountResult CountFindInFiles(string query, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, bool exact = false, int? focusLine = null, int? focusColumn = null, bool regex = false, int? maxCandidateFiles = null, int? maxLinesScanned = null, bool useIndexedLiteralCandidates = false, string? resumePath = null, int? resumeLine = null, int? resumeFileOrdinal = null, int? resumeMatchOrdinal = null, int? resumeByteOffset = null, CancellationToken cancellationToken = default)
     {
-        cancellationToken.ThrowIfCancellationRequested();
-        if (string.IsNullOrWhiteSpace(query))
-            return new FindCountResult(0, 0, new FindScanSummary(0, 0, 0));
-        ValidateFindContinuation(
-            resumePath,
-            resumeLine,
-            resumeFileOrdinal,
-            resumeMatchOrdinal,
-            resumeByteOffset);
-        if (resumeMatchOrdinal.HasValue || resumeByteOffset is not (null or 0))
-        {
-            throw new FindContinuationException(
-                "cursor_malformed",
-                "find count cursor must resume at a line boundary.");
-        }
-
-        var comparison = exact ? StringComparison.Ordinal : StringComparison.OrdinalIgnoreCase;
-        var regexMatcher = regex
-            ? CreateFindRegexMatcher(query, exact)
-            : null;
-        var searchPlan = CreateFindSearchPlan(query, exact, regex, useIndexedLiteralCandidates);
-        using var fileCmd = CreateFindFileCommand(
-            searchPlan,
+        return new IndexedFindPipeline(this).Count(new IndexedFindScanRequest(
+            query,
             lang,
             pathPatterns,
             excludePathPatterns,
-            excludeTests);
-
-        var candidateFiles = CountFindCandidateFiles(lang, pathPatterns, excludePathPatterns, excludeTests);
-        var filesScanned = 0;
-        var linesScanned = 0;
-        var truncated = false;
-        string? truncationReason = null;
-        string? nextPath = null;
-        int? nextLine = null;
-        int? nextFileOrdinal = null;
-        var count = 0;
-        var fileCount = 0;
-        var resumePending = resumePath is not null;
-        var candidateFileOrdinal = -1;
-        using var fileReader = fileCmd.ExecuteTrackedReader();
-        while (fileReader.TrackedRead())
-        {
-            cancellationToken.ThrowIfCancellationRequested();
-            candidateFileOrdinal++;
-            var path = fileReader.GetString(1);
-            if (resumePending)
-            {
-                if (resumeFileOrdinal.HasValue)
-                {
-                    if (candidateFileOrdinal < resumeFileOrdinal.Value)
-                        continue;
-                    if (candidateFileOrdinal != resumeFileOrdinal.Value
-                        || !string.Equals(path, resumePath, StringComparison.Ordinal))
-                    {
-                        throw new FindContinuationException(
-                            "cursor_malformed",
-                            "find count cursor file position does not match the current candidate order.");
-                    }
-                }
-                else if (!string.Equals(path, resumePath, StringComparison.Ordinal))
-                {
-                    continue;
-                }
-                if (resumeLine > Math.Max(1, fileReader.GetInt32(3)))
-                {
-                    throw new FindContinuationException(
-                        "cursor_malformed",
-                        "find count cursor line position exceeds the selected file.");
-                }
-                resumePending = false;
-            }
-            if (maxCandidateFiles.HasValue && filesScanned >= maxCandidateFiles.Value)
-            {
-                truncated = true;
-                truncationReason ??= "candidate_file_limit";
-                nextPath = path;
-                nextLine = 1;
-                nextFileOrdinal = candidateFileOrdinal;
-                break;
-            }
-
-            var fileId = fileReader.GetInt64(0);
-            var fileLang = GetNullableString(fileReader, 2);
-            var totalLines = fileReader.GetInt32(3);
-            var firstEligibleLine = string.Equals(path, resumePath, StringComparison.Ordinal)
-                ? Math.Max(1, resumeLine ?? 1)
-                : 1;
-            filesScanned++;
-            if (totalLines <= 0)
-                continue;
-
-            var searchQuery = exact && !regex ? ExactSourceSearchNormalizer.Normalize(query, fileLang) : query;
-            var fileMatches = 0;
-            var stopScanning = false;
-            foreach (var indexedLine in EnumerateIndexedFileLines(fileId))
-            {
-                cancellationToken.ThrowIfCancellationRequested();
-                if (indexedLine.Number > totalLines)
-                    break;
-                if (indexedLine.Number < firstEligibleLine)
-                    continue;
-                if (maxLinesScanned.HasValue && linesScanned >= maxLinesScanned.Value)
-                {
-                    truncated = true;
-                    truncationReason ??= "line_scan_limit";
-                    nextPath = path;
-                    nextLine = indexedLine.Number;
-                    nextFileOrdinal = candidateFileOrdinal;
-                    stopScanning = true;
-                    break;
-                }
-                linesScanned++;
-
-                if (focusLine.HasValue && indexedLine.Number != focusLine.Value)
-                    continue;
-
-                foreach (var _ in EnumerateFindLineMatches(
-                    indexedLine.Text,
-                    fileLang,
-                    searchQuery,
-                    comparison,
-                    regexMatcher,
-                    exact && !regex,
-                    focusColumn))
-                {
-                    fileMatches++;
-                }
-            }
-
-            if (fileMatches > 0)
-            {
-                count += fileMatches;
-                fileCount++;
-            }
-            if (stopScanning)
-                break;
-        }
-        if (resumePending)
-        {
-            throw new FindContinuationException(
-                "cursor_malformed",
-                "find count cursor position does not exist in the current candidate sequence.");
-        }
-
-        var capReached = truncated;
-        return new FindCountResult(
-            count,
-            fileCount,
-            new FindScanSummary(
-                candidateFiles,
-                filesScanned,
-                linesScanned,
-                truncated,
-                capReached,
-                TimedOut: false,
-                truncationReason,
-                maxCandidateFiles,
-                maxLinesScanned,
-                searchPlan.Strategy,
-                searchPlan.FallbackReason,
-                nextPath,
-                nextLine,
-                nextFileOrdinal,
-                NextByteOffset: nextPath is null ? null : 0));
-    }
-
-    private readonly record struct FindSearchPlan(
-        string Strategy,
-        string? FallbackReason,
-        string? TrigramMatchExpression);
-
-    private readonly record struct IndexedLine(int Number, string Text);
-
-    private readonly record struct FindLineMatch(int Column, int Length);
-
-    private readonly record struct PendingFileFindMatch(int LineNumber, int Column, int Length, int SnippetStart, int SnippetEnd);
-
-    private FindSearchPlan CreateFindSearchPlan(
-        string query,
-        bool exact,
-        bool regex,
-        bool useIndexedLiteralCandidates)
-    {
-        if (!useIndexedLiteralCandidates)
-            return new FindSearchPlan("line_scan", null, null);
-        if (regex)
-            return new FindSearchPlan("line_scan", "regex", null);
-        if (exact)
-            return new FindSearchPlan("line_scan", "exact_source_normalization", null);
-        if (query.Length < 3)
-            return new FindSearchPlan("line_scan", "query_too_short", null);
-        if (query.Any(character => character < ' ' || character > '~'))
-            return new FindSearchPlan("line_scan", "unsupported_query_characters", null);
-        if (!HasTable(DbContext.FtsChunksTrigramTableName))
-            return new FindSearchPlan("line_scan", "trigram_index_unavailable", null);
-        if (DbWriter.IsFtsBulkLoadMarkerSet(GetMetaString(DbWriter.FtsBulkLoadInProgressMetaKey)))
-            return new FindSearchPlan("line_scan", "trigram_index_rebuilding", null);
-        if (!HasAllTrigramFtsSyncTriggers())
-            return new FindSearchPlan("line_scan", "trigram_index_unsynchronized", null);
-
-        var phrase = "\"" + query.Replace("\"", "\"\"", StringComparison.Ordinal) + "\"";
-        return new FindSearchPlan("indexed_trigram", null, phrase);
-    }
-
-    private bool HasAllTrigramFtsSyncTriggers()
-    {
-        using var command = _conn.CreateCommand();
-        command.CommandText = DbContext.CountFtsChunksTrigramSyncTriggersSql;
-        return SqliteCommandPolicy.ReadInt32Scalar(
-            command,
-            "find trigram FTS synchronization trigger count") == 3;
-    }
-
-    private SqliteCommand CreateFindFileCommand(
-        FindSearchPlan searchPlan,
-        string? lang,
-        IReadOnlyList<string>? pathPatterns,
-        IReadOnlyList<string>? excludePathPatterns,
-        bool excludeTests)
-    {
-        var fileCmd = _conn.CreateCommand();
-        string sql;
-        if (searchPlan.TrigramMatchExpression != null)
-        {
-            sql = $"""
-                SELECT f.id, f.path, f.lang, f.lines
-                FROM (
-                    SELECT DISTINCT find_chunk.file_id
-                    FROM {DbContext.FtsChunksTrigramTableName}
-                    JOIN chunks find_chunk ON find_chunk.id = {DbContext.FtsChunksTrigramTableName}.rowid
-                    WHERE {DbContext.FtsChunksTrigramTableName} MATCH @trigramQuery
-                ) find_candidate
-                JOIN files f ON f.id = find_candidate.file_id
-                WHERE 1=1
-                """;
-        }
-        else
-        {
-            sql = "SELECT f.id, f.path, f.lang, f.lines FROM files f WHERE 1=1";
-        }
-        if (lang != null)
-            sql += " AND f.lang = @lang";
-        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
-        sql += $" ORDER BY {PathBucketOrder}, f.path";
-        fileCmd.CommandText = sql;
-        if (searchPlan.TrigramMatchExpression != null)
-            SqliteCommandPolicy.AddText(fileCmd, "@trigramQuery", searchPlan.TrigramMatchExpression);
-        if (lang != null)
-            SqliteCommandPolicy.Add(fileCmd, "@lang", lang);
-        AddPathFilterParameters(fileCmd, pathPatterns, excludePathPatterns);
-        return fileCmd;
-    }
-
-    private IEnumerable<IndexedLine> EnumerateIndexedFileLines(long fileId)
-    {
-        using var chunkCmd = _conn.CreateCommand();
-        chunkCmd.CommandText = @"
-            SELECT c.start_line, c.end_line, c.content
-            FROM chunks c
-            WHERE c.file_id = @fileId
-            ORDER BY c.start_line, c.chunk_index";
-        SqliteCommandPolicy.Add(chunkCmd, "@fileId", fileId);
-
-        var lastEmittedLine = 0;
-        using var chunkReader = chunkCmd.ExecuteTrackedReader();
-        while (chunkReader.TrackedRead())
-        {
-            var chunkStartLine = chunkReader.GetInt32(0);
-            var chunkEndLine = chunkReader.GetInt32(1);
-            var chunkLines = chunkReader.GetString(2).Split('\n');
-            var lineCount = chunkEndLine - chunkStartLine + 1;
-
-            for (int i = 0; i < chunkLines.Length && i < lineCount; i++)
-            {
-                var absoluteLine = chunkStartLine + i;
-                if (absoluteLine <= lastEmittedLine)
-                    continue;
-
-                lastEmittedLine = absoluteLine;
-                yield return new IndexedLine(absoluteLine, chunkLines[i]);
-            }
-        }
-    }
-
-    private static IEnumerable<FindLineMatch> EnumerateFindLineMatches(
-        string lineText,
-        string? fileLang,
-        string searchQuery,
-        StringComparison comparison,
-        Regex? regexMatcher,
-        bool normalizeExactSource,
-        int? focusColumn)
-    {
-        int[]? rawIndexMap = null;
-        var searchLine = normalizeExactSource
-            ? ExactSourceSearchNormalizer.Normalize(lineText, fileLang, out rawIndexMap)
-            : lineText;
-
-        if (regexMatcher != null)
-        {
-            foreach (Match match in regexMatcher.Matches(searchLine))
-            {
-                if (!match.Success)
-                    continue;
-                if (TryCreateFindLineMatch(match.Index, match.Length, rawIndexMap, focusColumn, out var lineMatch))
-                    yield return lineMatch;
-            }
-
-            yield break;
-        }
-
-        for (int searchStart = 0; searchStart < searchLine.Length;)
-        {
-            var matchColumn = searchLine.IndexOf(searchQuery, searchStart, comparison);
-            if (matchColumn < 0)
-                break;
-
-            if (TryCreateFindLineMatch(matchColumn, searchQuery.Length, rawIndexMap, focusColumn, out var lineMatch))
-                yield return lineMatch;
-            searchStart = matchColumn + 1;
-        }
-    }
-
-    private static bool TryCreateFindLineMatch(int matchColumn, int matchLength, int[]? rawIndexMap, int? focusColumn, out FindLineMatch lineMatch)
-    {
-        var rawMatchColumn = rawIndexMap == null ? matchColumn : rawIndexMap[matchColumn];
-        var rawMatchLength = matchLength;
-        if (rawIndexMap != null && matchLength > 0)
-        {
-            var rawMatchEndIndex = rawIndexMap[matchColumn + matchLength - 1];
-            rawMatchLength = rawMatchEndIndex - rawMatchColumn + 1;
-        }
-
-        lineMatch = new FindLineMatch(rawMatchColumn, rawMatchLength);
-        var focusEndColumn = rawMatchColumn + Math.Max(1, rawMatchLength);
-        return !focusColumn.HasValue || (focusColumn.Value >= rawMatchColumn + 1 && focusColumn.Value <= focusEndColumn);
-    }
-
-    private static Regex CreateFindRegexMatcher(string query, bool exact)
-        => RegexRegistry.CreateFindRegex(query, exact, ResolveFindRegexMatchTimeout());
-
-    private static TimeSpan ResolveFindRegexMatchTimeout()
-        => FindRegexMatchTimeoutForTesting is { } timeout && timeout > TimeSpan.Zero
-            ? timeout
-            : BoundedRegex.DefaultMatchTimeout;
-
-    private static void AddLineToFindWindow(IndexedLine indexedLine, Queue<IndexedLine> snippetWindow, Dictionary<int, string> snippetLinesByNumber)
-    {
-        snippetWindow.Enqueue(indexedLine);
-        snippetLinesByNumber[indexedLine.Number] = indexedLine.Text;
-    }
-
-    private static void FlushReadyFindMatches(
-        string path,
-        string? fileLang,
-        Queue<PendingFileFindMatch> pendingMatches,
-        Dictionary<int, string> snippetLinesByNumber,
-        List<FileFindResult> results,
-        int maxLineWidth,
-        int availableThroughLine)
-    {
-        while (pendingMatches.Count > 0 && pendingMatches.Peek().SnippetEnd <= availableThroughLine)
-        {
-            var pending = pendingMatches.Dequeue();
-            var snippetLineNumbers = Enumerable.Range(pending.SnippetStart, pending.SnippetEnd - pending.SnippetStart + 1)
-                .Where(snippetLinesByNumber.ContainsKey)
-                .ToList();
-            if (snippetLineNumbers.Count == 0)
-                continue;
-
-            var snippetLines = snippetLineNumbers.Select(line => snippetLinesByNumber[line]).ToList();
-            var (snippet, truncationContext) = ClampFindSnippetLines(
-                snippetLines,
-                maxLineWidth,
-                focusLineIndex: snippetLineNumbers.IndexOf(pending.LineNumber),
-                focusColumn: pending.Column + 1,
-                focusLength: pending.Length);
-            var matchLine = snippetLinesByNumber[pending.LineNumber];
-
-            results.Add(new FileFindResult
-            {
-                Path = path,
-                Lang = fileLang,
-                Line = pending.LineNumber,
-                Column = pending.Column + 1,
-                Length = pending.Length,
-                OriginalLineLength = matchLine.Length,
-                StartLine = snippetLineNumbers[0],
-                EndLine = snippetLineNumbers[^1],
-                Snippet = snippet,
-                SnippetTruncated = truncationContext.LineCount > 0,
-                SnippetTruncationContext = truncationContext,
-            });
-        }
-    }
-
-    private static (string Text, FileFindSnippetTruncationContext Context) ClampFindSnippetLines(
-        IReadOnlyList<string> lines,
-        int maxLineWidth,
-        int focusLineIndex,
-        int focusColumn,
-        int focusLength)
-    {
-        if (lines.Count == 0)
-            return (string.Empty, new FileFindSnippetTruncationContext());
-
-        var output = new string[lines.Count];
-        var truncatedCharCounts = new List<int>();
-        for (var i = 0; i < lines.Count; i++)
-        {
-            var clamped = i == focusLineIndex
-                ? LineWidthFormatter.ClampLine(lines[i], maxLineWidth, focusColumn, focusLength)
-                : LineWidthFormatter.ClampLine(lines[i], maxLineWidth);
-            output[i] = clamped.Text;
-            if (clamped.Truncated)
-                truncatedCharCounts.Add(clamped.TruncatedCharCount);
-        }
-
-        return (
-            string.Join('\n', output),
-            new FileFindSnippetTruncationContext
-            {
-                LineCount = truncatedCharCounts.Count,
-                CharCounts = truncatedCharCounts,
-                TotalChars = truncatedCharCounts.Sum(),
-                Reason = truncatedCharCounts.Count > 0 ? "line_width" : null,
-            });
-    }
-
-    private static void PruneFindWindow(
-        int currentLine,
-        int before,
-        Queue<PendingFileFindMatch> pendingMatches,
-        Queue<IndexedLine> snippetWindow,
-        Dictionary<int, string> snippetLinesByNumber)
-    {
-        var minLineToKeep = currentLine - before;
-        if (pendingMatches.Count > 0)
-            minLineToKeep = Math.Min(minLineToKeep, pendingMatches.Peek().SnippetStart);
-
-        while (snippetWindow.Count > 0 && snippetWindow.Peek().Number < minLineToKeep)
-        {
-            var removed = snippetWindow.Dequeue();
-            snippetLinesByNumber.Remove(removed.Number);
-        }
+            excludeTests,
+            exact,
+            focusLine,
+            focusColumn,
+            regex,
+            maxCandidateFiles,
+            maxLinesScanned,
+            useIndexedLiteralCandidates,
+            new FindResumePosition(
+                resumePath,
+                resumeLine,
+                resumeFileOrdinal,
+                resumeMatchOrdinal,
+                resumeByteOffset),
+            cancellationToken));
     }
 
     /// <summary>
diff --git a/src/CodeIndex/Database/FindSnippetAssembler.cs b/src/CodeIndex/Database/FindSnippetAssembler.cs
new file mode 100644
index 000000000..e1668f2a5
--- /dev/null
+++ b/src/CodeIndex/Database/FindSnippetAssembler.cs
@@ -0,0 +1,102 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private static class FindSnippetAssembler
+    {
+        internal static void FlushReadyMatches(
+            FindCandidateFile file,
+            Queue<PendingFileFindMatch> pendingMatches,
+            Dictionary<int, string> snippetLinesByNumber,
+            List<FileFindResult> results,
+            int maxLineWidth,
+            int availableThroughLine)
+        {
+            while (pendingMatches.Count > 0
+                   && pendingMatches.Peek().SnippetEnd <= availableThroughLine)
+            {
+                var pending = pendingMatches.Dequeue();
+                var lineNumbers = Enumerable
+                    .Range(pending.SnippetStart, pending.SnippetEnd - pending.SnippetStart + 1)
+                    .Where(snippetLinesByNumber.ContainsKey)
+                    .ToList();
+                if (lineNumbers.Count == 0)
+                    continue;
+
+                var lines = lineNumbers.Select(line => snippetLinesByNumber[line]).ToList();
+                var (snippet, truncationContext) = ClampSnippetLines(
+                    lines,
+                    maxLineWidth,
+                    lineNumbers.IndexOf(pending.LineNumber),
+                    pending.Column + 1,
+                    pending.Length);
+                var matchLine = snippetLinesByNumber[pending.LineNumber];
+                results.Add(new FileFindResult
+                {
+                    Path = file.Path,
+                    Lang = file.Lang,
+                    Line = pending.LineNumber,
+                    Column = pending.Column + 1,
+                    Length = pending.Length,
+                    OriginalLineLength = matchLine.Length,
+                    StartLine = lineNumbers[0],
+                    EndLine = lineNumbers[^1],
+                    Snippet = snippet,
+                    SnippetTruncated = truncationContext.LineCount > 0,
+                    SnippetTruncationContext = truncationContext,
+                });
+            }
+        }
+
+        private static (string Text, FileFindSnippetTruncationContext Context) ClampSnippetLines(
+            IReadOnlyList<string> lines,
+            int maxLineWidth,
+            int focusLineIndex,
+            int focusColumn,
+            int focusLength)
+        {
+            if (lines.Count == 0)
+                return (string.Empty, new FileFindSnippetTruncationContext());
+
+            var output = new string[lines.Count];
+            var truncatedCharCounts = new List<int>();
+            for (var index = 0; index < lines.Count; index++)
+            {
+                var clamped = index == focusLineIndex
+                    ? LineWidthFormatter.ClampLine(lines[index], maxLineWidth, focusColumn, focusLength)
+                    : LineWidthFormatter.ClampLine(lines[index], maxLineWidth);
+                output[index] = clamped.Text;
+                if (clamped.Truncated)
+                    truncatedCharCounts.Add(clamped.TruncatedCharCount);
+            }
+
+            return (
+                string.Join('\n', output),
+                new FileFindSnippetTruncationContext
+                {
+                    LineCount = truncatedCharCounts.Count,
+                    CharCounts = truncatedCharCounts,
+                    TotalChars = truncatedCharCounts.Sum(),
+                    Reason = truncatedCharCounts.Count > 0 ? "line_width" : null,
+                });
+        }
+
+        internal static void PruneWindow(
+            int currentLine,
+            int before,
+            Queue<PendingFileFindMatch> pendingMatches,
+            Queue<IndexedLine> snippetWindow,
+            Dictionary<int, string> snippetLinesByNumber)
+        {
+            var minLineToKeep = currentLine - before;
+            if (pendingMatches.Count > 0)
+                minLineToKeep = Math.Min(minLineToKeep, pendingMatches.Peek().SnippetStart);
+
+            while (snippetWindow.Count > 0 && snippetWindow.Peek().Number < minLineToKeep)
+            {
+                var removed = snippetWindow.Dequeue();
+                snippetLinesByNumber.Remove(removed.Number);
+            }
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/IndexedFindCollectors.cs b/src/CodeIndex/Database/IndexedFindCollectors.cs
new file mode 100644
index 000000000..6edf1c633
--- /dev/null
+++ b/src/CodeIndex/Database/IndexedFindCollectors.cs
@@ -0,0 +1,213 @@
+using System.Text;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class FindResultCollector(
+        IndexedFindListRequest request,
+        FindScanState state) : IFindScanCollector
+    {
+        private readonly List<FileFindResult> _results = [];
+        private readonly Queue<PendingFileFindMatch> _pendingMatches = [];
+        private readonly Queue<IndexedLine> _snippetWindow = [];
+        private readonly Dictionary<int, string> _snippetLinesByNumber = [];
+        private int _acceptedMatches;
+        private int _matchesSkipped;
+        private bool _resumeMatchPending = request.Scan.Resume.MatchOrdinal.HasValue;
+
+        public FindScanMode Mode => FindScanMode.Results;
+        public int ContextBefore => request.Before;
+        public bool NotifyLineScanned => true;
+        public bool ShouldStopBeforeCandidate
+            => !request.CaptureContinuation && _results.Count >= request.Limit;
+        public bool ShouldStopAfterFile
+            => state.Truncated
+               || state.ResultLimitReached
+               || !request.CaptureContinuation && _results.Count >= request.Limit;
+
+        public void BeginFile(FindCandidateFile file)
+        {
+            _pendingMatches.Clear();
+            _snippetWindow.Clear();
+            _snippetLinesByNumber.Clear();
+            _acceptedMatches = _results.Count;
+        }
+
+        public void ObserveLine(IndexedLine line)
+        {
+            _snippetWindow.Enqueue(line);
+            _snippetLinesByNumber[line.Number] = line.Text;
+        }
+
+        public bool ShouldEvaluateMatches(IndexedLine line, bool eligibleForMatch)
+            => !state.ResultLimitReached
+               && (_matchesSkipped < request.Offset
+                   || request.CaptureContinuation && _acceptedMatches <= request.Limit
+                   || !request.CaptureContinuation && _acceptedMatches < request.Limit)
+               && eligibleForMatch
+               && (!request.Scan.FocusLine.HasValue
+                   || line.Number == request.Scan.FocusLine.Value);
+
+        public bool AcceptMatch(
+            FindCandidateFile file,
+            IndexedLine line,
+            FindLineMatch match,
+            int matchOrdinal)
+        {
+            if (_resumeMatchPending && line.Number == file.FirstEligibleLine)
+            {
+                if (matchOrdinal < request.Scan.Resume.MatchOrdinal!.Value)
+                    return false;
+                var boundaryByteOffset = Encoding.UTF8.GetByteCount(
+                    line.Text.AsSpan(0, match.Column));
+                if (matchOrdinal != request.Scan.Resume.MatchOrdinal.Value
+                    || boundaryByteOffset != request.Scan.Resume.ByteOffset)
+                {
+                    throw new FindContinuationException(
+                        "cursor_malformed",
+                        "find cursor match position is not a record boundary for the current query.");
+                }
+                _resumeMatchPending = false;
+            }
+
+            if (_matchesSkipped < request.Offset)
+            {
+                _matchesSkipped++;
+                return false;
+            }
+            if (_acceptedMatches >= request.Limit)
+            {
+                state.SetResultLimit(
+                    file.Path,
+                    line.Number,
+                    file.Ordinal,
+                    matchOrdinal,
+                    Encoding.UTF8.GetByteCount(line.Text.AsSpan(0, match.Column)));
+                return true;
+            }
+
+            _pendingMatches.Enqueue(new PendingFileFindMatch(
+                line.Number,
+                match.Column,
+                match.Length,
+                Math.Max(1, line.Number - request.Before),
+                Math.Min(file.TotalLines, line.Number + request.After)));
+            _acceptedMatches++;
+            return false;
+        }
+
+        public void CompleteLine(FindCandidateFile file, IndexedLine line)
+        {
+            FindSnippetAssembler.FlushReadyMatches(
+                file,
+                _pendingMatches,
+                _snippetLinesByNumber,
+                _results,
+                request.MaxLineWidth,
+                line.Number);
+            FindSnippetAssembler.PruneWindow(
+                line.Number,
+                request.Before,
+                _pendingMatches,
+                _snippetWindow,
+                _snippetLinesByNumber);
+        }
+
+        public bool CanStopAfterLine(bool stopScanning)
+            => (stopScanning
+                || !request.CaptureContinuation && _results.Count >= request.Limit)
+               && _pendingMatches.Count == 0;
+
+        public void CompleteFile(FindCandidateFile file)
+            => FindSnippetAssembler.FlushReadyMatches(
+                file,
+                _pendingMatches,
+                _snippetLinesByNumber,
+                _results,
+                request.MaxLineWidth,
+                int.MaxValue);
+
+        public void ValidateCompletedScan()
+        {
+            if (_resumeMatchPending)
+            {
+                throw new FindContinuationException(
+                    "cursor_malformed",
+                    "find cursor position does not exist in the current result sequence.");
+            }
+        }
+
+        internal FindResults CreateResult(FindSearchPlan searchPlan)
+            => new(
+                _results,
+                state.CreateSummary(
+                    searchPlan,
+                    request.Scan.MaxCandidateFiles,
+                    request.Scan.MaxLinesScanned));
+    }
+
+    private sealed class FindCountCollector(
+        IndexedFindScanRequest request,
+        FindScanState state) : IFindScanCollector
+    {
+        private int _fileMatches;
+        private int _count;
+        private int _fileCount;
+
+        public FindScanMode Mode => FindScanMode.Count;
+        public int ContextBefore => 0;
+        public bool NotifyLineScanned => false;
+        public bool ShouldStopBeforeCandidate => false;
+        public bool ShouldStopAfterFile => false;
+
+        public void BeginFile(FindCandidateFile file)
+            => _fileMatches = 0;
+
+        public void ObserveLine(IndexedLine line)
+        {
+        }
+
+        public bool ShouldEvaluateMatches(IndexedLine line, bool eligibleForMatch)
+            => eligibleForMatch
+               && (!request.FocusLine.HasValue || line.Number == request.FocusLine.Value);
+
+        public bool AcceptMatch(
+            FindCandidateFile file,
+            IndexedLine line,
+            FindLineMatch match,
+            int matchOrdinal)
+        {
+            _fileMatches++;
+            return false;
+        }
+
+        public void CompleteLine(FindCandidateFile file, IndexedLine line)
+        {
+        }
+
+        public bool CanStopAfterLine(bool stopScanning)
+            => stopScanning;
+
+        public void CompleteFile(FindCandidateFile file)
+        {
+            if (_fileMatches <= 0)
+                return;
+            _count += _fileMatches;
+            _fileCount++;
+        }
+
+        public void ValidateCompletedScan()
+        {
+        }
+
+        internal FindCountResult CreateResult(FindSearchPlan searchPlan)
+            => new(
+                _count,
+                _fileCount,
+                state.CreateSummary(
+                    searchPlan,
+                    request.MaxCandidateFiles,
+                    request.MaxLinesScanned));
+    }
+}
diff --git a/src/CodeIndex/Database/IndexedFindModels.cs b/src/CodeIndex/Database/IndexedFindModels.cs
new file mode 100644
index 000000000..e115af40f
--- /dev/null
+++ b/src/CodeIndex/Database/IndexedFindModels.cs
@@ -0,0 +1,172 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private readonly record struct FindResumePosition(
+        string? Path,
+        int? Line,
+        int? FileOrdinal,
+        int? MatchOrdinal,
+        int? ByteOffset);
+
+    private sealed record IndexedFindScanRequest(
+        string Query,
+        string? Lang,
+        IReadOnlyList<string>? PathPatterns,
+        IReadOnlyList<string>? ExcludePathPatterns,
+        bool ExcludeTests,
+        bool Exact,
+        int? FocusLine,
+        int? FocusColumn,
+        bool Regex,
+        int? MaxCandidateFiles,
+        int? MaxLinesScanned,
+        bool UseIndexedLiteralCandidates,
+        FindResumePosition Resume,
+        CancellationToken CancellationToken);
+
+    private sealed record IndexedFindListRequest(
+        IndexedFindScanRequest Scan,
+        int Limit,
+        int Before,
+        int After,
+        int MaxLineWidth,
+        int Offset,
+        bool CaptureContinuation);
+
+    private interface IFindScanCollector
+    {
+        FindScanMode Mode { get; }
+        int ContextBefore { get; }
+        bool NotifyLineScanned { get; }
+        bool ShouldStopBeforeCandidate { get; }
+        bool ShouldStopAfterFile { get; }
+        void BeginFile(FindCandidateFile file);
+        void ObserveLine(IndexedLine line);
+        bool ShouldEvaluateMatches(IndexedLine line, bool eligibleForMatch);
+        bool AcceptMatch(
+            FindCandidateFile file,
+            IndexedLine line,
+            FindLineMatch match,
+            int matchOrdinal);
+        void CompleteLine(FindCandidateFile file, IndexedLine line);
+        bool CanStopAfterLine(bool stopScanning);
+        void CompleteFile(FindCandidateFile file);
+        void ValidateCompletedScan();
+    }
+
+    private enum FindScanMode
+    {
+        Results,
+        Count,
+    }
+
+    private readonly record struct FindSearchPlan(
+        string Strategy,
+        string? FallbackReason,
+        string? TrigramMatchExpression);
+
+    private readonly record struct FindCandidateFile(
+        long Id,
+        string Path,
+        string? Lang,
+        int TotalLines,
+        int Ordinal,
+        int FirstEligibleLine);
+
+    private readonly record struct IndexedLine(int Number, string Text);
+
+    private readonly record struct FindLineMatch(int Column, int Length);
+
+    private readonly record struct PendingFileFindMatch(
+        int LineNumber,
+        int Column,
+        int Length,
+        int SnippetStart,
+        int SnippetEnd);
+
+    private sealed class FindScanState(FindResumePosition resume)
+    {
+        internal int CandidateFiles { get; set; }
+        internal int FilesScanned { get; set; }
+        internal int LinesScanned { get; set; }
+        internal int CandidateFileOrdinal { get; set; } = -1;
+        internal bool ResumePending { get; set; } = resume.Path is not null;
+        internal bool Truncated { get; private set; }
+        internal string? TruncationReason { get; private set; }
+        internal string? NextPath { get; private set; }
+        internal int? NextLine { get; private set; }
+        internal int? NextFileOrdinal { get; private set; }
+        internal int? NextMatchOrdinal { get; private set; }
+        internal int? NextByteOffset { get; private set; }
+        internal bool ResultLimitReached { get; private set; }
+
+        internal void Truncate(
+            string reason,
+            string path,
+            int nextLine,
+            int fileOrdinal)
+        {
+            Truncated = true;
+            TruncationReason ??= reason;
+            NextPath = path;
+            NextLine = nextLine;
+            NextFileOrdinal = fileOrdinal;
+            NextByteOffset = 0;
+        }
+
+        internal void TruncateIfUnset(
+            string reason,
+            string path,
+            int nextLine,
+            int fileOrdinal)
+        {
+            Truncated = true;
+            TruncationReason ??= reason;
+            if (NextPath != null)
+                return;
+            NextPath = path;
+            NextLine = nextLine;
+            NextFileOrdinal = fileOrdinal;
+            NextByteOffset = 0;
+        }
+
+        internal void SetResultLimit(
+            string path,
+            int line,
+            int fileOrdinal,
+            int matchOrdinal,
+            int byteOffset)
+        {
+            NextPath = path;
+            NextLine = line;
+            NextFileOrdinal = fileOrdinal;
+            NextMatchOrdinal = matchOrdinal;
+            NextByteOffset = byteOffset;
+            ResultLimitReached = true;
+        }
+
+        internal FindScanSummary CreateSummary(
+            FindSearchPlan searchPlan,
+            int? candidateFileLimit,
+            int? lineLimit)
+            => new(
+                CandidateFiles,
+                FilesScanned,
+                LinesScanned,
+                Truncated,
+                CapReached: Truncated,
+                TimedOut: false,
+                TruncationReason,
+                candidateFileLimit,
+                lineLimit,
+                searchPlan.Strategy,
+                searchPlan.FallbackReason,
+                NextPath,
+                NextLine,
+                NextFileOrdinal,
+                NextMatchOrdinal,
+                NextByteOffset,
+                ResultLimitReached);
+    }
+}
diff --git a/src/CodeIndex/Database/IndexedFindPipeline.cs b/src/CodeIndex/Database/IndexedFindPipeline.cs
new file mode 100644
index 000000000..7312977c0
--- /dev/null
+++ b/src/CodeIndex/Database/IndexedFindPipeline.cs
@@ -0,0 +1,320 @@
+using System.Text.RegularExpressions;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class IndexedFindPipeline(DbReader owner)
+    {
+        private readonly DbReader _owner = owner;
+        private readonly IndexedFindQuerySource _querySource = new(owner);
+
+        internal FindResults Find(IndexedFindListRequest request)
+        {
+            var scan = request.Scan;
+            scan.CancellationToken.ThrowIfCancellationRequested();
+            if (string.IsNullOrWhiteSpace(scan.Query) || request.Limit <= 0)
+                return new FindResults([], new FindScanSummary(0, 0, 0));
+            ValidateContinuation(scan.Resume);
+
+            var normalizedRequest = request with
+            {
+                Before = Math.Max(0, request.Before),
+                After = Math.Max(0, request.After),
+                MaxLineWidth = LineWidthFormatter.ClampMaxLineWidth(request.MaxLineWidth),
+                Offset = Math.Max(0, request.Offset),
+            };
+            var state = new FindScanState(scan.Resume);
+            var collector = new FindResultCollector(normalizedRequest, state);
+            var searchPlan = ScanFiles(scan, collector, state);
+            ValidateCompletedScan(collector.Mode, state, collector);
+            return collector.CreateResult(searchPlan);
+        }
+
+        internal FindCountResult Count(IndexedFindScanRequest request)
+        {
+            request.CancellationToken.ThrowIfCancellationRequested();
+            if (string.IsNullOrWhiteSpace(request.Query))
+                return new FindCountResult(0, 0, new FindScanSummary(0, 0, 0));
+            ValidateContinuation(request.Resume);
+            if (request.Resume.MatchOrdinal.HasValue || request.Resume.ByteOffset is not (null or 0))
+            {
+                throw new FindContinuationException(
+                    "cursor_malformed",
+                    "find count cursor must resume at a line boundary.");
+            }
+
+            var state = new FindScanState(request.Resume);
+            var collector = new FindCountCollector(request, state);
+            var searchPlan = ScanFiles(request, collector, state);
+            ValidateCompletedScan(collector.Mode, state, collector);
+            return collector.CreateResult(searchPlan);
+        }
+
+        private FindSearchPlan ScanFiles(
+            IndexedFindScanRequest request,
+            IFindScanCollector collector,
+            FindScanState state)
+        {
+            var comparison = request.Exact ? StringComparison.Ordinal : StringComparison.OrdinalIgnoreCase;
+            var regexMatcher = request.Regex
+                ? CreateFindRegexMatcher(request.Query, request.Exact)
+                : null;
+            var searchPlan = _querySource.CreateSearchPlan(request);
+            using var fileCommand = _querySource.CreateFileCommand(searchPlan, request);
+            state.CandidateFiles = _owner.CountFindCandidateFiles(
+                request.Lang,
+                request.PathPatterns,
+                request.ExcludePathPatterns,
+                request.ExcludeTests);
+
+            using var fileReader = fileCommand.ExecuteTrackedReader();
+            while (fileReader.TrackedRead())
+            {
+                request.CancellationToken.ThrowIfCancellationRequested();
+                if (collector.ShouldStopBeforeCandidate)
+                    break;
+
+                state.CandidateFileOrdinal++;
+                var file = ReadCandidateFile(fileReader, state.CandidateFileOrdinal);
+                if (!TryReachResumeFile(request.Resume, collector.Mode, file, state))
+                    continue;
+                if (ReachedCandidateFileLimit(request, file, state))
+                    break;
+
+                var firstEligibleLine = string.Equals(file.Path, request.Resume.Path, StringComparison.Ordinal)
+                    ? Math.Max(1, request.Resume.Line ?? 1)
+                    : 1;
+                file = file with { FirstEligibleLine = firstEligibleLine };
+                state.FilesScanned++;
+                if (file.TotalLines <= 0)
+                    continue;
+
+                collector.BeginFile(file);
+                var searchQuery = request.Exact && !request.Regex
+                    ? ExactSourceSearchNormalizer.Normalize(request.Query, file.Lang)
+                    : request.Query;
+                var stopScanning = ScanFileLines(
+                    request,
+                    collector,
+                    state,
+                    file,
+                    searchQuery,
+                    comparison,
+                    regexMatcher);
+                collector.CompleteFile(file);
+                if (stopScanning || collector.ShouldStopAfterFile)
+                    break;
+            }
+
+            return searchPlan;
+        }
+
+        private bool ScanFileLines(
+            IndexedFindScanRequest request,
+            IFindScanCollector collector,
+            FindScanState state,
+            FindCandidateFile file,
+            string searchQuery,
+            StringComparison comparison,
+            Regex? regexMatcher)
+        {
+            var firstContextLine = Math.Max(1, file.FirstEligibleLine - collector.ContextBefore);
+            var stopScanning = false;
+            foreach (var indexedLine in _querySource.EnumerateIndexedFileLines(file.Id))
+            {
+                request.CancellationToken.ThrowIfCancellationRequested();
+                if (indexedLine.Number > file.TotalLines)
+                    break;
+                if (indexedLine.Number < firstContextLine)
+                    continue;
+
+                var eligibleForMatch = indexedLine.Number >= file.FirstEligibleLine;
+                if (ReachedLineScanLimit(request, file, indexedLine, state))
+                {
+                    stopScanning = true;
+                    break;
+                }
+                RecordScannedLine(request, collector, state, eligibleForMatch);
+                collector.ObserveLine(indexedLine);
+
+                if (collector.ShouldEvaluateMatches(indexedLine, eligibleForMatch))
+                {
+                    var matchOrdinal = 0;
+                    foreach (var lineMatch in IndexedFindQuerySource.EnumerateLineMatches(
+                        indexedLine.Text,
+                        file.Lang,
+                        searchQuery,
+                        comparison,
+                        regexMatcher,
+                        request.Exact && !request.Regex,
+                        request.FocusColumn))
+                    {
+                        if (collector.AcceptMatch(file, indexedLine, lineMatch, matchOrdinal))
+                        {
+                            stopScanning = true;
+                            break;
+                        }
+                        matchOrdinal++;
+                    }
+                }
+
+                collector.CompleteLine(file, indexedLine);
+                if (collector.CanStopAfterLine(stopScanning))
+                    break;
+            }
+            return stopScanning;
+        }
+
+        private static void RecordScannedLine(
+            IndexedFindScanRequest request,
+            IFindScanCollector collector,
+            FindScanState state,
+            bool eligibleForMatch)
+        {
+            if (!eligibleForMatch)
+                return;
+
+            state.LinesScanned++;
+            if (!collector.NotifyLineScanned)
+                return;
+            FindLineScannedForTesting?.Invoke();
+            request.CancellationToken.ThrowIfCancellationRequested();
+        }
+
+        private static FindCandidateFile ReadCandidateFile(SqliteDataReader reader, int ordinal)
+            => new(
+                reader.GetInt64(0),
+                reader.GetString(1),
+                GetNullableString(reader, 2),
+                reader.GetInt32(3),
+                ordinal,
+                FirstEligibleLine: 1);
+
+        private static bool TryReachResumeFile(
+            FindResumePosition resume,
+            FindScanMode mode,
+            FindCandidateFile file,
+            FindScanState state)
+        {
+            if (!state.ResumePending)
+                return true;
+
+            if (resume.FileOrdinal.HasValue)
+            {
+                if (file.Ordinal < resume.FileOrdinal.Value)
+                    return false;
+                if (file.Ordinal != resume.FileOrdinal.Value
+                    || !string.Equals(file.Path, resume.Path, StringComparison.Ordinal))
+                {
+                    throw new FindContinuationException(
+                        "cursor_malformed",
+                        mode == FindScanMode.Count
+                            ? "find count cursor file position does not match the current candidate order."
+                            : "find cursor file position does not match the current candidate order.");
+                }
+            }
+            else if (!string.Equals(file.Path, resume.Path, StringComparison.Ordinal))
+            {
+                return false;
+            }
+
+            if (resume.Line > Math.Max(1, file.TotalLines))
+            {
+                throw new FindContinuationException(
+                    "cursor_malformed",
+                    mode == FindScanMode.Count
+                        ? "find count cursor line position exceeds the selected file."
+                        : "find cursor line position exceeds the selected file.");
+            }
+            state.ResumePending = false;
+            return true;
+        }
+
+        private static bool ReachedCandidateFileLimit(
+            IndexedFindScanRequest request,
+            FindCandidateFile file,
+            FindScanState state)
+        {
+            if (!request.MaxCandidateFiles.HasValue
+                || state.FilesScanned < request.MaxCandidateFiles.Value)
+            {
+                return false;
+            }
+
+            state.Truncate(
+                "candidate_file_limit",
+                file.Path,
+                nextLine: 1,
+                file.Ordinal);
+            return true;
+        }
+
+        private static bool ReachedLineScanLimit(
+            IndexedFindScanRequest request,
+            FindCandidateFile file,
+            IndexedLine indexedLine,
+            FindScanState state)
+        {
+            if (!request.MaxLinesScanned.HasValue
+                || state.LinesScanned < request.MaxLinesScanned.Value)
+            {
+                return false;
+            }
+
+            state.TruncateIfUnset(
+                "line_scan_limit",
+                file.Path,
+                indexedLine.Number,
+                file.Ordinal);
+            return true;
+        }
+
+        private static void ValidateContinuation(FindResumePosition resume)
+        {
+            if (resume.Path is null)
+            {
+                if (resume.Line.HasValue
+                    || resume.FileOrdinal.HasValue
+                    || resume.MatchOrdinal.HasValue
+                    || resume.ByteOffset.HasValue)
+                {
+                    throw new FindContinuationException(
+                        "cursor_malformed",
+                        "find cursor continuation fields require a resume path.");
+                }
+                return;
+            }
+
+            if (!resume.Line.HasValue
+                || resume.Line.Value <= 0
+                || resume.FileOrdinal is < 0
+                || resume.MatchOrdinal is < 0
+                || resume.ByteOffset is < 0
+                || resume.MatchOrdinal.HasValue && !resume.ByteOffset.HasValue
+                || !resume.MatchOrdinal.HasValue && resume.ByteOffset is not (null or 0))
+            {
+                throw new FindContinuationException(
+                    "cursor_malformed",
+                    "find cursor continuation position is invalid.");
+            }
+        }
+
+        private static void ValidateCompletedScan(
+            FindScanMode mode,
+            FindScanState state,
+            IFindScanCollector collector)
+        {
+            if (state.ResumePending)
+            {
+                throw new FindContinuationException(
+                    "cursor_malformed",
+                    mode == FindScanMode.Count
+                        ? "find count cursor position does not exist in the current candidate sequence."
+                        : "find cursor position does not exist in the current result sequence.");
+            }
+            collector.ValidateCompletedScan();
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/IndexedFindQuerySource.cs b/src/CodeIndex/Database/IndexedFindQuerySource.cs
new file mode 100644
index 000000000..79bf3151f
--- /dev/null
+++ b/src/CodeIndex/Database/IndexedFindQuerySource.cs
@@ -0,0 +1,193 @@
+using System.Text.RegularExpressions;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class IndexedFindQuerySource(DbReader owner)
+    {
+        private readonly DbReader _owner = owner;
+
+        internal FindSearchPlan CreateSearchPlan(IndexedFindScanRequest request)
+        {
+            if (!request.UseIndexedLiteralCandidates)
+                return new FindSearchPlan("line_scan", null, null);
+            if (request.Regex)
+                return new FindSearchPlan("line_scan", "regex", null);
+            if (request.Exact)
+                return new FindSearchPlan("line_scan", "exact_source_normalization", null);
+            if (request.Query.Length < 3)
+                return new FindSearchPlan("line_scan", "query_too_short", null);
+            if (request.Query.Any(character => character < ' ' || character > '~'))
+                return new FindSearchPlan("line_scan", "unsupported_query_characters", null);
+            if (!_owner.HasTable(DbContext.FtsChunksTrigramTableName))
+                return new FindSearchPlan("line_scan", "trigram_index_unavailable", null);
+            if (DbWriter.IsFtsBulkLoadMarkerSet(_owner.GetMetaString(DbWriter.FtsBulkLoadInProgressMetaKey)))
+                return new FindSearchPlan("line_scan", "trigram_index_rebuilding", null);
+            if (!HasAllTrigramFtsSyncTriggers())
+                return new FindSearchPlan("line_scan", "trigram_index_unsynchronized", null);
+
+            var phrase = "\"" + request.Query.Replace("\"", "\"\"", StringComparison.Ordinal) + "\"";
+            return new FindSearchPlan("indexed_trigram", null, phrase);
+        }
+
+        private bool HasAllTrigramFtsSyncTriggers()
+        {
+            using var command = _owner._conn.CreateCommand();
+            command.CommandText = DbContext.CountFtsChunksTrigramSyncTriggersSql;
+            return SqliteCommandPolicy.ReadInt32Scalar(
+                command,
+                "find trigram FTS synchronization trigger count") == 3;
+        }
+
+        internal SqliteCommand CreateFileCommand(
+            FindSearchPlan searchPlan,
+            IndexedFindScanRequest request)
+        {
+            var command = _owner._conn.CreateCommand();
+            string sql;
+            if (searchPlan.TrigramMatchExpression != null)
+            {
+                sql = $"""
+                    SELECT f.id, f.path, f.lang, f.lines
+                    FROM (
+                        SELECT DISTINCT find_chunk.file_id
+                        FROM {DbContext.FtsChunksTrigramTableName}
+                        JOIN chunks find_chunk ON find_chunk.id = {DbContext.FtsChunksTrigramTableName}.rowid
+                        WHERE {DbContext.FtsChunksTrigramTableName} MATCH @trigramQuery
+                    ) find_candidate
+                    JOIN files f ON f.id = find_candidate.file_id
+                    WHERE 1=1
+                    """;
+            }
+            else
+            {
+                sql = "SELECT f.id, f.path, f.lang, f.lines FROM files f WHERE 1=1";
+            }
+            if (request.Lang != null)
+                sql += " AND f.lang = @lang";
+            AppendPathFilters(
+                ref sql,
+                request.PathPatterns,
+                request.ExcludePathPatterns,
+                request.ExcludeTests);
+            sql += $" ORDER BY {PathBucketOrder}, f.path";
+            command.CommandText = sql;
+            if (searchPlan.TrigramMatchExpression != null)
+                SqliteCommandPolicy.AddText(command, "@trigramQuery", searchPlan.TrigramMatchExpression);
+            if (request.Lang != null)
+                SqliteCommandPolicy.Add(command, "@lang", request.Lang);
+            AddPathFilterParameters(
+                command,
+                request.PathPatterns,
+                request.ExcludePathPatterns);
+            return command;
+        }
+
+        internal IEnumerable<IndexedLine> EnumerateIndexedFileLines(long fileId)
+        {
+            using var command = _owner._conn.CreateCommand();
+            command.CommandText = @"
+                SELECT c.start_line, c.end_line, c.content
+                FROM chunks c
+                WHERE c.file_id = @fileId
+                ORDER BY c.start_line, c.chunk_index";
+            SqliteCommandPolicy.Add(command, "@fileId", fileId);
+
+            var lastEmittedLine = 0;
+            using var reader = command.ExecuteTrackedReader();
+            while (reader.TrackedRead())
+            {
+                var chunkStartLine = reader.GetInt32(0);
+                var chunkEndLine = reader.GetInt32(1);
+                var chunkLines = reader.GetString(2).Split('\n');
+                var lineCount = chunkEndLine - chunkStartLine + 1;
+
+                for (var index = 0; index < chunkLines.Length && index < lineCount; index++)
+                {
+                    var absoluteLine = chunkStartLine + index;
+                    if (absoluteLine <= lastEmittedLine)
+                        continue;
+
+                    lastEmittedLine = absoluteLine;
+                    yield return new IndexedLine(absoluteLine, chunkLines[index]);
+                }
+            }
+        }
+
+        internal static IEnumerable<FindLineMatch> EnumerateLineMatches(
+            string lineText,
+            string? fileLang,
+            string searchQuery,
+            StringComparison comparison,
+            Regex? regexMatcher,
+            bool normalizeExactSource,
+            int? focusColumn)
+        {
+            int[]? rawIndexMap = null;
+            var searchLine = normalizeExactSource
+                ? ExactSourceSearchNormalizer.Normalize(lineText, fileLang, out rawIndexMap)
+                : lineText;
+
+            if (regexMatcher != null)
+            {
+                foreach (Match match in regexMatcher.Matches(searchLine))
+                {
+                    if (!match.Success)
+                        continue;
+                    if (TryCreateLineMatch(
+                            match.Index,
+                            match.Length,
+                            rawIndexMap,
+                            focusColumn,
+                            out var lineMatch))
+                    {
+                        yield return lineMatch;
+                    }
+                }
+                yield break;
+            }
+
+            for (var searchStart = 0; searchStart < searchLine.Length;)
+            {
+                var matchColumn = searchLine.IndexOf(searchQuery, searchStart, comparison);
+                if (matchColumn < 0)
+                    break;
+
+                if (TryCreateLineMatch(
+                        matchColumn,
+                        searchQuery.Length,
+                        rawIndexMap,
+                        focusColumn,
+                        out var lineMatch))
+                {
+                    yield return lineMatch;
+                }
+                searchStart = matchColumn + 1;
+            }
+        }
+
+        private static bool TryCreateLineMatch(
+            int matchColumn,
+            int matchLength,
+            int[]? rawIndexMap,
+            int? focusColumn,
+            out FindLineMatch lineMatch)
+        {
+            var rawMatchColumn = rawIndexMap == null ? matchColumn : rawIndexMap[matchColumn];
+            var rawMatchLength = matchLength;
+            if (rawIndexMap != null && matchLength > 0)
+            {
+                var rawMatchEndIndex = rawIndexMap[matchColumn + matchLength - 1];
+                rawMatchLength = rawMatchEndIndex - rawMatchColumn + 1;
+            }
+
+            lineMatch = new FindLineMatch(rawMatchColumn, rawMatchLength);
+            var focusEndColumn = rawMatchColumn + Math.Max(1, rawMatchLength);
+            return !focusColumn.HasValue
+                   || focusColumn.Value >= rawMatchColumn + 1
+                   && focusColumn.Value <= focusEndColumn;
+        }
+    }
+}

From 2223e251fc68c967ad7b297e38b411bc8e7f2b21 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 07:49:03 +0900
Subject: [PATCH 10/45] Unify JVM triple-string masking

---
 ...StructuralLineMasker.JvmAndSwiftStrings.cs | 342 ----------------
 .../StructuralLineMasker.JvmTripleStrings.cs  | 386 ++++++++++++++++++
 ...StructuralLineMasker.ScalaTripleStrings.cs | 371 -----------------
 3 files changed, 386 insertions(+), 713 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmTripleStrings.cs
 delete mode 100644 src/CodeIndex/Indexer/References/Support/StructuralLineMasker.ScalaTripleStrings.cs

diff --git a/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmAndSwiftStrings.cs b/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmAndSwiftStrings.cs
index 2564a95e9..d52d03169 100644
--- a/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmAndSwiftStrings.cs
+++ b/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmAndSwiftStrings.cs
@@ -127,348 +127,6 @@ private static int SkipJsSingleLineStringContinuation(string line, int startInde
         return p;
     }
 
-    // Kotlin multi-line raw string literals: """...""".
-    // Body is raw (no backslash escape processing). Interpolation: $identifier and
-    // ${expression}. Only ${expr} hole contents are preserved so downstream reference
-    // extraction still sees real call edges; $ident is a bare identifier that cannot
-    // be a call by itself, so masking the surrounding body is safe.
-    // Regression target: issue #385.
-    // Kotlin の複数行 raw 文字列 """...""" を扱う。本文は raw（\ エスケープなし）。
-    // 補間は $identifier と ${expression}。${expr} ホール内の本物の呼び出しを
-    // 参照抽出に残すため、ホール内は保存する。$ident は単独識別子で call にならないため
-    // 周囲本体と一緒にマスクしてよい。回帰対象: issue #385。
-    private static void MaskKotlinTripleStringContents(string[] lines)
-    {
-        var insideTriple = false;
-        var blockCommentDepth = 0;
-        // Hole state persists across lines so multi-line ${ ... } bodies keep real
-        // call edges and do not accidentally close at the wrong `}`.
-        // -1 when outside a hole, >=0 = nested `{` depth inside the hole (0 = top).
-        // ホール状態は行をまたいで保持する。ホール外は -1、ホール内は `{` 深さ（0 が最上位）。
-        var holeBraceDepth = -1;
-        // Persistent across lines: a nested `"""..."""` literal opened inside the
-        // current `${ ... }` hole. While true, the nested literal acts like its own
-        // mini triple body — `${...}` holes inside it still preserve real call
-        // edges (closes #996), but body chars between holes are masked through to
-        // the next `"""` closer so call-shaped identifiers cannot leak (closes #992).
-        // ホール内に開いた nested triple-quoted string の状態。nested literal 内も
-        // 自身の `${...}` ホールでは本物の call を残しつつ、本文は次の `"""` まで
-        // 空白化して phantom call の漏れを防ぐ。
-        var nestedTripleOpen = false;
-        // -1 when not inside a nested-triple ${...} hole, >=0 = brace depth of that
-        // inner hole. The inner hole preserves real call edges inside the nested
-        // triple-quoted literal.
-        // nested triple 内 `${...}` ホールの brace 深さ。-1 はホール外。
-        var nestedHoleBraceDepth = -1;
-        // Defensive depth tracking for triple-quoted literals opened 3+ levels deep
-        // (i.e. inside the nested triple's own `${...}` hole). >0 = current 3+ deep
-        // body. While >0, every char is masked and `"""` toggles depth so phantom
-        // calls cannot leak. Real calls 4+ levels deep are not preserved — full
-        // stack tracking would be needed for that — but masking soundness is.
-        // 3 段以上のネスト triple に対する防御的な深さ追跡。> 0 の間は本文をマスクし、
-        // 4 段以上の本物の call は保持しないが、phantom の漏れは防ぐ。
-        var deepNestedTripleDepth = 0;
-        var deepNestedTripleHashCounts = new Stack<int>();
-
-        for (int i = 0; i < lines.Length; i++)
-        {
-            var line = lines[i];
-            if (line.Length == 0)
-                continue;
-
-            char[]? masked = null;
-            char[] GetMaskedLine() => masked ??= line.ToCharArray();
-            var pos = 0;
-
-            while (pos < line.Length)
-            {
-                if (blockCommentDepth > 0)
-                {
-                    if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '*')
-                    {
-                        ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                        blockCommentDepth++;
-                        pos += 2;
-                        continue;
-                    }
-                    if (pos + 1 < line.Length && line[pos] == '*' && line[pos + 1] == '/')
-                    {
-                        ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                        blockCommentDepth--;
-                        pos += 2;
-                        continue;
-                    }
-                    GetMaskedLine()[pos] = ' ';
-                    pos++;
-                    continue;
-                }
-
-                if (insideTriple)
-                {
-                    if (holeBraceDepth >= 0)
-                    {
-                        // Inside ${expr} hole: preserve body. Block comments and line
-                        // comments must be recognized first so a legal `/* } */` inside
-                        // the hole does not close the hole at the comment body's `}`.
-                        // Nested single-line strings and char literals are also skipped
-                        // so their `}` does not close the hole, and nested `{` / `}`
-                        // are tracked for lambdas / object literals.
-                        // ${expr} ホール内: 本文を保存。block / line コメントを先に
-                        // 認識して `/* } */` のようなコメント内 `}` でホールを早閉じ
-                        // しないようにする。単行文字列・char リテラルも同様にスキップし、
-                        // lambda / object literal 用のネスト `{` / `}` を追跡する。
-                        if (nestedTripleOpen)
-                        {
-                            if (nestedHoleBraceDepth >= 0)
-                            {
-                                // Inside the nested triple's own ${expr} hole: preserve
-                                // body chars so real call edges land in the reference
-                                // graph. Closes #996.
-                                // nested triple 内の `${expr}` ホール内: 本文を保存し、
-                                // 本物の call が reference graph に届くようにする。
-                                if (deepNestedTripleDepth > 0)
-                                {
-                                    // 3+ level deep triple body: keep masking through
-                                    // nested open/close pairs so a 4th opener cannot
-                                    // unwind the 3-deep frame early.
-                                    // 3 段以上深い triple 本文: ネスト open/close を
-                                    // 追跡し、4 段目の opener で 3 段深い frame が
-                                    // 早抜けしないようにする。
-                                    if (pos + 2 < line.Length
-                                        && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                                    {
-                                        var looksLikeNestedOpen = LooksLikeDeepTripleOpenerContext(lines, i, pos, 3);
-                                        if (looksLikeNestedOpen)
-                                        {
-                                            ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                                            pos += 3;
-                                            deepNestedTripleDepth++;
-                                            deepNestedTripleHashCounts.Push(0);
-                                            continue;
-                                        }
-
-                                        ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                                        pos += 3;
-                                        deepNestedTripleDepth--;
-                                        if (deepNestedTripleHashCounts.Count > 0)
-                                            deepNestedTripleHashCounts.Pop();
-                                        continue;
-                                    }
-                                    GetMaskedLine()[pos] = ' ';
-                                    pos++;
-                                    continue;
-                                }
-                                if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '/')
-                                {
-                                    ReplaceWithSpaces(GetMaskedLine(), pos, line.Length - pos);
-                                    pos = line.Length;
-                                    continue;
-                                }
-                                if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '*')
-                                {
-                                    ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                                    blockCommentDepth = 1;
-                                    pos += 2;
-                                    continue;
-                                }
-                                // 3rd-level triple opener inside the inner hole.
-                                // Detect before the single-line-string skipper so the
-                                // leading `"` does not advance us into the literal
-                                // body via SkipJsSingleLineString and break paren / brace
-                                // counting.
-                                // 3 段目の triple opener。先頭 `"` が単行スキッパーへ
-                                // 渡って literal 本体に進まないよう先に検知する。
-                                if (pos + 2 < line.Length
-                                    && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                                {
-                                    ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                                    pos += 3;
-                                    deepNestedTripleDepth = 1;
-                                    deepNestedTripleHashCounts.Push(0);
-                                    continue;
-                                }
-                                if (line[pos] == '"' || line[pos] == '\'')
-                                {
-                                    pos = SkipJsSingleLineString(line, pos);
-                                    continue;
-                                }
-                                if (line[pos] == '{')
-                                {
-                                    nestedHoleBraceDepth++;
-                                    pos++;
-                                    continue;
-                                }
-                                if (line[pos] == '}')
-                                {
-                                    if (nestedHoleBraceDepth == 0)
-                                    {
-                                        GetMaskedLine()[pos] = ' ';
-                                        nestedHoleBraceDepth = -1;
-                                        pos++;
-                                        continue;
-                                    }
-                                    nestedHoleBraceDepth--;
-                                    pos++;
-                                    continue;
-                                }
-                                pos++;
-                                continue;
-                            }
-
-                            // Inside a nested `"""..."""` literal opened earlier in this
-                            // outer hole. Recognize a closing `"""`, an opening `${...}`
-                            // hole inside the nested literal (so real calls inside it
-                            // still reach the reference graph), and otherwise mask.
-                            // 外側ホール内で開いた nested triple 本体。閉じ `"""`、内側
-                            // `${...}` ホール、それ以外は body としてマスク。
-                            if (pos + 2 < line.Length
-                                && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                            {
-                                ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                                pos += 3;
-                                nestedTripleOpen = false;
-                                nestedHoleBraceDepth = -1;
-                                deepNestedTripleDepth = 0;
-                                deepNestedTripleHashCounts.Clear();
-                                continue;
-                            }
-                            if (pos + 1 < line.Length && line[pos] == '$' && line[pos + 1] == '{')
-                            {
-                                ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                                nestedHoleBraceDepth = 0;
-                                pos += 2;
-                                continue;
-                            }
-                            GetMaskedLine()[pos] = ' ';
-                            pos++;
-                            continue;
-                        }
-
-                        if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '/')
-                        {
-                            ReplaceWithSpaces(GetMaskedLine(), pos, line.Length - pos);
-                            pos = line.Length;
-                            continue;
-                        }
-
-                        if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '*')
-                        {
-                            ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                            blockCommentDepth = 1;
-                            pos += 2;
-                            continue;
-                        }
-
-                        // Nested `"""..."""` literal opener inside the hole. Detect
-                        // before the single-line-string skipper so the first `"` does
-                        // not advance us into the literal body via `SkipJsSingleLineString`.
-                        // ホール内で開く nested `"""..."""` の opener。先頭 `"` が単行
-                        // 文字列スキッパーに渡って literal 本体へ進まないよう先に検知する。
-                        if (pos + 2 < line.Length
-                            && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                        {
-                            ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                            pos += 3;
-                            nestedTripleOpen = true;
-                            nestedHoleBraceDepth = -1;
-                            continue;
-                        }
-
-                        if (line[pos] == '"' || line[pos] == '\'')
-                        {
-                            pos = SkipJsSingleLineString(line, pos);
-                            continue;
-                        }
-
-                        if (line[pos] == '{')
-                        {
-                            holeBraceDepth++;
-                            pos++;
-                            continue;
-                        }
-
-                        if (line[pos] == '}')
-                        {
-                            if (holeBraceDepth == 0)
-                            {
-                                GetMaskedLine()[pos] = ' ';
-                                holeBraceDepth = -1;
-                                pos++;
-                                continue;
-                            }
-
-                            holeBraceDepth--;
-                            pos++;
-                            continue;
-                        }
-
-                        pos++;
-                        continue;
-                    }
-
-                    if (pos + 2 < line.Length
-                        && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                    {
-                        ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                        pos += 3;
-                        insideTriple = false;
-                        // Defensive: any open nested-triple state is owned by the just-
-                        // closed outer triple, so reset it as well.
-                        // 防御的に、外側 triple を閉じた時点で nested-triple 状態も解除する。
-                        nestedTripleOpen = false;
-                        nestedHoleBraceDepth = -1;
-                        deepNestedTripleDepth = 0;
-                        deepNestedTripleHashCounts.Clear();
-                        continue;
-                    }
-
-                    if (pos + 1 < line.Length && line[pos] == '$' && line[pos + 1] == '{')
-                    {
-                        ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                        holeBraceDepth = 0;
-                        pos += 2;
-                        continue;
-                    }
-
-                    GetMaskedLine()[pos] = ' ';
-                    pos++;
-                    continue;
-                }
-
-                if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '/')
-                    break;
-
-                if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '*')
-                {
-                    ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                    blockCommentDepth = 1;
-                    pos += 2;
-                    continue;
-                }
-
-                if (pos + 2 < line.Length
-                    && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                {
-                    ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                    pos += 3;
-                    insideTriple = true;
-                    continue;
-                }
-
-                if (line[pos] == '"' || line[pos] == '\'')
-                {
-                    pos = SkipJsSingleLineString(line, pos);
-                    continue;
-                }
-
-                pos++;
-            }
-
-            if (masked is not null)
-                lines[i] = new string(masked);
-        }
-    }
-
     // Swift multi-line string literals: """...""" and extended """#"""..."""# forms.
     // Plain form supports \(expr) interpolation; N-hash extended form needs \#(expr)
     // (matching hash count). Interpolation hole contents are preserved so downstream
diff --git a/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmTripleStrings.cs b/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmTripleStrings.cs
new file mode 100644
index 000000000..c7b1d067d
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmTripleStrings.cs
@@ -0,0 +1,386 @@
+namespace CodeIndex.Indexer;
+
+internal static partial class StructuralLineMasker
+{
+    private enum JvmTripleStringPolicy
+    {
+        Kotlin,
+        Scala,
+    }
+
+    private static void MaskKotlinTripleStringContents(string[] lines) =>
+        new JvmTripleStringScanner(
+            lines,
+            JvmTripleStringPolicy.Kotlin).MaskLines();
+
+    private static void MaskScalaTripleStringContents(string[] lines) =>
+        new JvmTripleStringScanner(
+            lines,
+            JvmTripleStringPolicy.Scala).MaskLines();
+
+    private sealed class JvmTripleStringScanner(
+        string[] lines,
+        JvmTripleStringPolicy policy)
+    {
+        private readonly Stack<int> _deepTripleHashCounts = new();
+        private bool _insideTriple;
+        private bool _tripleInterpolates;
+        private int _blockCommentDepth;
+        private int _holeBraceDepth = -1;
+        private bool _nestedTripleOpen;
+        private bool _nestedTripleInterpolates;
+        private int _nestedHoleBraceDepth = -1;
+        private int _deepTripleDepth;
+
+        internal void MaskLines()
+        {
+            for (var lineIndex = 0; lineIndex < lines.Length; lineIndex++)
+            {
+                if (lines[lineIndex].Length == 0)
+                    continue;
+
+                ScanLine(lineIndex);
+            }
+        }
+
+        private void ScanLine(int lineIndex)
+        {
+            var line = new JvmTripleStringLine(lines[lineIndex]);
+            while (line.Position < line.Text.Length)
+            {
+                if (_blockCommentDepth > 0)
+                {
+                    ScanBlockComment(ref line);
+                    continue;
+                }
+
+                if (!_insideTriple)
+                {
+                    ScanCode(ref line);
+                    continue;
+                }
+
+                if (_holeBraceDepth < 0)
+                {
+                    ScanTripleBody(ref line);
+                    continue;
+                }
+
+                if (!_nestedTripleOpen)
+                {
+                    ScanInterpolationHole(ref line);
+                    continue;
+                }
+
+                if (_nestedHoleBraceDepth < 0)
+                {
+                    ScanNestedTripleBody(ref line);
+                    continue;
+                }
+
+                if (_deepTripleDepth > 0)
+                    ScanOpaqueDeepTriple(ref line, lineIndex);
+                else
+                    ScanNestedInterpolationHole(ref line);
+            }
+
+            if (line.WasMasked)
+                lines[lineIndex] = line.CreateMaskedText();
+        }
+
+        private void ScanBlockComment(ref JvmTripleStringLine line)
+        {
+            if (StartsWith(line.Text, line.Position, "/*"))
+            {
+                line.MaskAndAdvance(2);
+                _blockCommentDepth++;
+                return;
+            }
+
+            if (StartsWith(line.Text, line.Position, "*/"))
+            {
+                line.MaskAndAdvance(2);
+                _blockCommentDepth--;
+                return;
+            }
+
+            line.MaskAndAdvance();
+        }
+
+        private void ScanCode(ref JvmTripleStringLine line)
+        {
+            if (StartsWith(line.Text, line.Position, "//"))
+            {
+                line.MoveToEnd();
+                return;
+            }
+
+            if (StartsWith(line.Text, line.Position, "/*"))
+            {
+                line.MaskAndAdvance(2);
+                _blockCommentDepth = 1;
+                return;
+            }
+
+            if (IsTripleQuoteAt(line.Text, line.Position))
+            {
+                _tripleInterpolates =
+                    TripleAtPositionInterpolates(line.Text, line.Position);
+                line.MaskAndAdvance(3);
+                _insideTriple = true;
+                return;
+            }
+
+            if (line.Text[line.Position] is '"' or '\'')
+            {
+                line.Position =
+                    SkipJsSingleLineString(line.Text, line.Position);
+                return;
+            }
+
+            line.Position++;
+        }
+
+        private void ScanTripleBody(ref JvmTripleStringLine line)
+        {
+            if (IsTripleQuoteAt(line.Text, line.Position))
+            {
+                line.MaskAndAdvance(3);
+                _insideTriple = false;
+                _tripleInterpolates = false;
+                ResetNestedTripleState();
+                return;
+            }
+
+            if (_tripleInterpolates
+                && StartsWith(line.Text, line.Position, "${"))
+            {
+                line.MaskAndAdvance(2);
+                _holeBraceDepth = 0;
+                return;
+            }
+
+            line.MaskAndAdvance();
+        }
+
+        private void ScanInterpolationHole(ref JvmTripleStringLine line)
+        {
+            if (TryScanHoleComment(ref line))
+                return;
+
+            if (IsTripleQuoteAt(line.Text, line.Position))
+            {
+                _nestedTripleInterpolates =
+                    TripleAtPositionInterpolates(line.Text, line.Position);
+                line.MaskAndAdvance(3);
+                _nestedTripleOpen = true;
+                _nestedHoleBraceDepth = -1;
+                return;
+            }
+
+            if (TrySkipQuotedHoleLiteral(ref line))
+                return;
+
+            if (line.Text[line.Position] == '{')
+            {
+                _holeBraceDepth++;
+                line.Position++;
+                return;
+            }
+
+            if (line.Text[line.Position] == '}')
+            {
+                if (_holeBraceDepth == 0)
+                {
+                    line.MaskAndAdvance();
+                    _holeBraceDepth = -1;
+                    return;
+                }
+
+                _holeBraceDepth--;
+            }
+
+            line.Position++;
+        }
+
+        private void ScanNestedTripleBody(ref JvmTripleStringLine line)
+        {
+            if (IsTripleQuoteAt(line.Text, line.Position))
+            {
+                line.MaskAndAdvance(3);
+                ResetNestedTripleState();
+                return;
+            }
+
+            if (_nestedTripleInterpolates
+                && StartsWith(line.Text, line.Position, "${"))
+            {
+                line.MaskAndAdvance(2);
+                _nestedHoleBraceDepth = 0;
+                return;
+            }
+
+            line.MaskAndAdvance();
+        }
+
+        private void ScanNestedInterpolationHole(
+            ref JvmTripleStringLine line)
+        {
+            if (TryScanHoleComment(ref line))
+                return;
+
+            if (IsTripleQuoteAt(line.Text, line.Position))
+            {
+                line.MaskAndAdvance(3);
+                _deepTripleDepth = 1;
+                _deepTripleHashCounts.Push(0);
+                return;
+            }
+
+            if (TrySkipQuotedHoleLiteral(ref line))
+                return;
+
+            if (line.Text[line.Position] == '{')
+            {
+                _nestedHoleBraceDepth++;
+                line.Position++;
+                return;
+            }
+
+            if (line.Text[line.Position] == '}')
+            {
+                if (_nestedHoleBraceDepth == 0)
+                {
+                    line.MaskAndAdvance();
+                    _nestedHoleBraceDepth = -1;
+                    return;
+                }
+
+                _nestedHoleBraceDepth--;
+            }
+
+            line.Position++;
+        }
+
+        private void ScanOpaqueDeepTriple(
+            ref JvmTripleStringLine line,
+            int lineIndex)
+        {
+            var hashCount = policy == JvmTripleStringPolicy.Scala
+                ? CountRun(line.Text, line.Position, '#')
+                : 0;
+            var quoteIndex = line.Position + hashCount;
+            if (!IsTripleQuoteAt(line.Text, quoteIndex))
+            {
+                line.MaskAndAdvance();
+                return;
+            }
+
+            var delimiterLength = hashCount + 3;
+            if (LooksLikeDeepTripleOpenerContext(
+                    lines,
+                    lineIndex,
+                    line.Position,
+                    delimiterLength))
+            {
+                line.MaskAndAdvance(delimiterLength);
+                _deepTripleDepth++;
+                _deepTripleHashCounts.Push(hashCount);
+                return;
+            }
+
+            var currentHashCount = _deepTripleHashCounts.Count > 0
+                ? _deepTripleHashCounts.Peek()
+                : 0;
+            if (hashCount != currentHashCount)
+            {
+                line.MaskAndAdvance();
+                return;
+            }
+
+            line.MaskAndAdvance(delimiterLength);
+            _deepTripleDepth--;
+            if (_deepTripleHashCounts.Count > 0)
+                _deepTripleHashCounts.Pop();
+        }
+
+        private bool TryScanHoleComment(ref JvmTripleStringLine line)
+        {
+            if (StartsWith(line.Text, line.Position, "//"))
+            {
+                line.MaskToEnd();
+                return true;
+            }
+
+            if (!StartsWith(line.Text, line.Position, "/*"))
+                return false;
+
+            line.MaskAndAdvance(2);
+            _blockCommentDepth = 1;
+            return true;
+        }
+
+        private static bool TrySkipQuotedHoleLiteral(
+            ref JvmTripleStringLine line)
+        {
+            if (line.Text[line.Position] is not ('"' or '\''))
+                return false;
+
+            line.Position =
+                SkipJsSingleLineString(line.Text, line.Position);
+            return true;
+        }
+
+        private bool TripleAtPositionInterpolates(
+            string line,
+            int quoteIndex) =>
+            policy == JvmTripleStringPolicy.Kotlin
+            || (quoteIndex > 0 && IsIdentifierPart(line[quoteIndex - 1]));
+
+        private void ResetNestedTripleState()
+        {
+            _nestedTripleOpen = false;
+            _nestedTripleInterpolates = false;
+            _nestedHoleBraceDepth = -1;
+            _deepTripleDepth = 0;
+            _deepTripleHashCounts.Clear();
+        }
+
+        private static bool IsTripleQuoteAt(string line, int position) =>
+            position + 2 < line.Length
+            && line[position] == '"'
+            && line[position + 1] == '"'
+            && line[position + 2] == '"';
+    }
+
+    private struct JvmTripleStringLine(string text)
+    {
+        private char[]? _masked;
+
+        internal string Text { get; } = text;
+
+        internal int Position { get; set; }
+
+        internal readonly bool WasMasked => _masked is not null;
+
+        internal void MaskAndAdvance(int length = 1)
+        {
+            _masked ??= Text.ToCharArray();
+            ReplaceWithSpaces(_masked, Position, length);
+            Position += length;
+        }
+
+        internal void MaskToEnd()
+        {
+            MaskAndAdvance(Text.Length - Position);
+        }
+
+        internal void MoveToEnd()
+        {
+            Position = Text.Length;
+        }
+
+        internal readonly string CreateMaskedText() =>
+            new(_masked!);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.ScalaTripleStrings.cs b/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.ScalaTripleStrings.cs
deleted file mode 100644
index c882a497d..000000000
--- a/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.ScalaTripleStrings.cs
+++ /dev/null
@@ -1,371 +0,0 @@
-namespace CodeIndex.Indexer;
-
-internal static partial class StructuralLineMasker
-{
-    private static void MaskScalaTripleStringContents(string[] lines)
-    {
-        var insideTriple = false;
-        // Whether the currently-open triple is an interpolator form (prefixed by an
-        // identifier): only interpolators recognize ${expr} holes. Plain `"""..."""`
-        // has no interpolation.
-        // 現在開いている triple が interpolator 形式か。interpolator のみ ${expr}
-        // を補間として扱う。プレーン `"""..."""` は補間なし。
-        var isInterpolator = false;
-        var blockCommentDepth = 0;
-        var holeBraceDepth = -1;
-        // Persistent across lines: a nested `"""..."""` literal opened inside the
-        // current `${ ... }` hole. While true, the nested literal acts like its own
-        // mini triple body — interpolator-prefixed nested triples (`s"""`, `f"""`,
-        // `raw"""`, ...) keep `${expr}` holes alive so real call edges still reach
-        // the reference graph (closes #996), while plain nested `"""..."""` masks
-        // everything (closes #992).
-        // ホール内で開いた nested triple-quoted string の状態。interpolator 付きの
-        // nested triple は内部の `${expr}` ホールを保存して real call を残し、
-        // プレーンな nested triple は全文を masking する。
-        var nestedTripleOpen = false;
-        // Whether the nested triple-quoted literal in the current hole was opened
-        // with an identifier prefix (interpolator form).
-        // ホール内で開いた nested triple が interpolator 形式かどうか。
-        var nestedTripleIsInterpolator = false;
-        // -1 when not inside a nested-triple ${...} hole, >=0 = brace depth of that
-        // inner hole. The inner hole preserves real call edges inside the nested
-        // triple-quoted literal.
-        // nested triple 内 `${...}` ホールの brace 深さ。-1 はホール外。
-        var nestedHoleBraceDepth = -1;
-        // Defensive depth tracking for triple-quoted literals opened 3+ levels deep
-        // (i.e. inside the nested triple's own `${...}` hole). >0 = current 3+ deep
-        // body. While >0, every char is masked and `"""` toggles depth so phantom
-        // calls cannot leak. Real calls 4+ levels deep are not preserved — full
-        // stack tracking would be needed for that — but masking soundness is.
-        // 3 段以上のネスト triple に対する防御的な深さ追跡。> 0 の間は本文をマスクし、
-        // 4 段以上の本物の call は保持しないが、phantom の漏れは防ぐ。
-        var deepNestedTripleDepth = 0;
-        var deepNestedTripleHashCounts = new Stack<int>();
-
-        for (int i = 0; i < lines.Length; i++)
-        {
-            var line = lines[i];
-            if (line.Length == 0)
-                continue;
-
-            char[]? masked = null;
-            char[] GetMaskedLine() => masked ??= line.ToCharArray();
-            var pos = 0;
-
-            while (pos < line.Length)
-            {
-                if (blockCommentDepth > 0)
-                {
-                    if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '*')
-                    {
-                        ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                        blockCommentDepth++;
-                        pos += 2;
-                        continue;
-                    }
-                    if (pos + 1 < line.Length && line[pos] == '*' && line[pos + 1] == '/')
-                    {
-                        ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                        blockCommentDepth--;
-                        pos += 2;
-                        continue;
-                    }
-                    GetMaskedLine()[pos] = ' ';
-                    pos++;
-                    continue;
-                }
-
-                if (insideTriple)
-                {
-                    if (holeBraceDepth >= 0)
-                    {
-                        // Inside ${expr} hole: preserve body. Block comments and line
-                        // comments must be recognized first so a legal `/* } */` inside
-                        // the hole does not close the hole at the comment body's `}`.
-                        // ${expr} ホール内: 本文を保存。block / line コメントを先に
-                        // 認識して `/* } */` のようなコメント内 `}` でホールを早閉じ
-                        // しないようにする。
-                        if (nestedTripleOpen)
-                        {
-                            if (nestedHoleBraceDepth >= 0)
-                            {
-                                // Inside the interpolator-prefixed nested triple's own
-                                // ${expr} hole: preserve body chars so real call edges
-                                // land in the reference graph. Closes #996.
-                                // interpolator 付き nested triple 内の `${expr}` ホール
-                                // 内: 本物の call を残す。
-                                if (deepNestedTripleDepth > 0)
-                                {
-                                    // 3+ level deep triple body: keep masking through
-                                    // nested open/close pairs so a 4th opener cannot
-                                    // unwind the 3-deep frame early.
-                                    // 3 段以上深い triple 本文: ネスト open/close を
-                                    // 追跡し、4 段目の opener で 3 段深い frame が
-                                    // 早抜けしないようにする。
-                                    var deepHashes = CountRun(line, pos, '#');
-                                    if (pos + deepHashes + 2 < line.Length
-                                        && line[pos + deepHashes] == '"'
-                                        && line[pos + deepHashes + 1] == '"'
-                                        && line[pos + deepHashes + 2] == '"')
-                                    {
-                                        var looksLikeNestedOpen = LooksLikeDeepTripleOpenerContext(lines, i, pos, deepHashes + 3);
-                                        if (looksLikeNestedOpen)
-                                        {
-                                            ReplaceWithSpaces(GetMaskedLine(), pos, deepHashes + 3);
-                                            pos += deepHashes + 3;
-                                            deepNestedTripleDepth++;
-                                            deepNestedTripleHashCounts.Push(deepHashes);
-                                            continue;
-                                        }
-
-                                        var currentDeepHashCount = deepNestedTripleHashCounts.Count > 0
-                                            ? deepNestedTripleHashCounts.Peek()
-                                            : 0;
-                                        if (deepHashes == currentDeepHashCount)
-                                        {
-                                            ReplaceWithSpaces(GetMaskedLine(), pos, 3 + deepHashes);
-                                            pos += 3 + deepHashes;
-                                            deepNestedTripleDepth--;
-                                            if (deepNestedTripleHashCounts.Count > 0)
-                                                deepNestedTripleHashCounts.Pop();
-                                            continue;
-                                        }
-                                    }
-
-                                    GetMaskedLine()[pos] = ' ';
-                                    pos++;
-                                    continue;
-                                }
-                                if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '/')
-                                {
-                                    ReplaceWithSpaces(GetMaskedLine(), pos, line.Length - pos);
-                                    pos = line.Length;
-                                    continue;
-                                }
-                                if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '*')
-                                {
-                                    ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                                    blockCommentDepth = 1;
-                                    pos += 2;
-                                    continue;
-                                }
-                                // 3rd-level triple opener inside the inner hole.
-                                // Detect before the single-line-string skipper so the
-                                // leading `"` does not advance us into the literal
-                                // body via SkipJsSingleLineString and break brace counting.
-                                // 3 段目の triple opener。先頭 `"` が単行スキッパーへ
-                                // 渡って literal 本体に進まないよう先に検知する。
-                                if (pos + 2 < line.Length
-                                    && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                                {
-                                    ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                                    pos += 3;
-                                    deepNestedTripleDepth = 1;
-                                    deepNestedTripleHashCounts.Push(0);
-                                    continue;
-                                }
-                                if (line[pos] == '"' || line[pos] == '\'')
-                                {
-                                    pos = SkipJsSingleLineString(line, pos);
-                                    continue;
-                                }
-                                if (line[pos] == '{')
-                                {
-                                    nestedHoleBraceDepth++;
-                                    pos++;
-                                    continue;
-                                }
-                                if (line[pos] == '}')
-                                {
-                                    if (nestedHoleBraceDepth == 0)
-                                    {
-                                        GetMaskedLine()[pos] = ' ';
-                                        nestedHoleBraceDepth = -1;
-                                        pos++;
-                                        continue;
-                                    }
-                                    nestedHoleBraceDepth--;
-                                    pos++;
-                                    continue;
-                                }
-                                pos++;
-                                continue;
-                            }
-
-                            // Inside a nested `"""..."""` literal opened earlier in this
-                            // outer hole. Recognize a closing `"""`; only interpolator-
-                            // prefixed nested triples honor `${...}` holes, plain ones
-                            // mask everything.
-                            // 外側ホール内で開いた nested triple 本体。閉じ `"""`、
-                            // interpolator 付きでは `${...}` を内部ホールとして開く、
-                            // それ以外は body としてマスク。
-                            if (pos + 2 < line.Length
-                                && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                            {
-                                ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                                pos += 3;
-                                nestedTripleOpen = false;
-                                nestedTripleIsInterpolator = false;
-                                nestedHoleBraceDepth = -1;
-                                deepNestedTripleDepth = 0;
-                                deepNestedTripleHashCounts.Clear();
-                                continue;
-                            }
-                            if (nestedTripleIsInterpolator
-                                && pos + 1 < line.Length
-                                && line[pos] == '$' && line[pos + 1] == '{')
-                            {
-                                ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                                nestedHoleBraceDepth = 0;
-                                pos += 2;
-                                continue;
-                            }
-                            GetMaskedLine()[pos] = ' ';
-                            pos++;
-                            continue;
-                        }
-
-                        if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '/')
-                        {
-                            ReplaceWithSpaces(GetMaskedLine(), pos, line.Length - pos);
-                            pos = line.Length;
-                            continue;
-                        }
-
-                        if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '*')
-                        {
-                            ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                            blockCommentDepth = 1;
-                            pos += 2;
-                            continue;
-                        }
-
-                        // Nested `"""..."""` literal opener inside the hole. Detect
-                        // before the single-line-string skipper so the first `"` does
-                        // not advance us into the literal body via `SkipJsSingleLineString`.
-                        // ホール内で開く nested `"""..."""` の opener。先頭 `"` が単行
-                        // 文字列スキッパーに渡って literal 本体へ進まないよう先に検知する。
-                        if (pos + 2 < line.Length
-                            && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                        {
-                            // Interpolator detection: an identifier character immediately
-                            // before the nested `"""` marks this as a prefixed form
-                            // (s""", f""", raw""", or user-defined).
-                            // interpolator 判定: 直前が識別子文字なら prefix 付き。
-                            var nestedPrefixIsInterpolator = pos > 0 && IsIdentifierPart(line[pos - 1]);
-                            ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                            pos += 3;
-                            nestedTripleOpen = true;
-                            nestedTripleIsInterpolator = nestedPrefixIsInterpolator;
-                            nestedHoleBraceDepth = -1;
-                            continue;
-                        }
-
-                        if (line[pos] == '"' || line[pos] == '\'')
-                        {
-                            pos = SkipJsSingleLineString(line, pos);
-                            continue;
-                        }
-
-                        if (line[pos] == '{')
-                        {
-                            holeBraceDepth++;
-                            pos++;
-                            continue;
-                        }
-
-                        if (line[pos] == '}')
-                        {
-                            if (holeBraceDepth == 0)
-                            {
-                                GetMaskedLine()[pos] = ' ';
-                                holeBraceDepth = -1;
-                                pos++;
-                                continue;
-                            }
-
-                            holeBraceDepth--;
-                            pos++;
-                            continue;
-                        }
-
-                        pos++;
-                        continue;
-                    }
-
-                    if (pos + 2 < line.Length
-                        && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                    {
-                        ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                        pos += 3;
-                        insideTriple = false;
-                        isInterpolator = false;
-                        // Defensive: outer triple owns any nested-triple state from a
-                        // hole, so reset it as well when the outer literal closes.
-                        // 防御的に、外側 triple が閉じた時点で nested-triple 状態も解除する。
-                        nestedTripleOpen = false;
-                        nestedTripleIsInterpolator = false;
-                        nestedHoleBraceDepth = -1;
-                        deepNestedTripleDepth = 0;
-                        deepNestedTripleHashCounts.Clear();
-                        continue;
-                    }
-
-                    if (isInterpolator
-                        && pos + 1 < line.Length
-                        && line[pos] == '$' && line[pos + 1] == '{')
-                    {
-                        ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                        holeBraceDepth = 0;
-                        pos += 2;
-                        continue;
-                    }
-
-                    GetMaskedLine()[pos] = ' ';
-                    pos++;
-                    continue;
-                }
-
-                if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '/')
-                    break;
-
-                if (pos + 1 < line.Length && line[pos] == '/' && line[pos + 1] == '*')
-                {
-                    ReplaceWithSpaces(GetMaskedLine(), pos, 2);
-                    blockCommentDepth = 1;
-                    pos += 2;
-                    continue;
-                }
-
-                if (pos + 2 < line.Length
-                    && line[pos] == '"' && line[pos + 1] == '"' && line[pos + 2] == '"')
-                {
-                    // Interpolator detection: an identifier character immediately before
-                    // `"""` marks this as a prefixed form (s""", f""", raw""", or a
-                    // user-defined interpolator). Only those forms honor ${expr} holes.
-                    // interpolator 判定: `"""` の直前が識別子文字なら prefix 付き
-                    // （`s"""` / `f"""` / `raw"""` / ユーザー定義）で、${expr} ホールを有効化する。
-                    var prefixIsInterpolator = pos > 0 && IsIdentifierPart(line[pos - 1]);
-                    ReplaceWithSpaces(GetMaskedLine(), pos, 3);
-                    pos += 3;
-                    insideTriple = true;
-                    isInterpolator = prefixIsInterpolator;
-                    continue;
-                }
-
-                if (line[pos] == '"' || line[pos] == '\'')
-                {
-                    pos = SkipJsSingleLineString(line, pos);
-                    continue;
-                }
-
-                pos++;
-            }
-
-            if (masked is not null)
-                lines[i] = new string(masked);
-        }
-    }
-
-
-}

From 0eaa1f8fdb2b4fe2358d1f9f9386d590c24134de Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 08:09:22 +0900
Subject: [PATCH 11/45] Extract cross-language symbol query normalization

---
 src/CodeIndex/Database/DbReader.References.cs |  28 +-
 .../DbReader.SymbolSearchQueryNormalizer.cs   | 355 ++++++++++++++++++
 .../Database/DbSymbolReader.Search.cs         | 300 +--------------
 3 files changed, 369 insertions(+), 314 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchQueryNormalizer.cs

diff --git a/src/CodeIndex/Database/DbReader.References.cs b/src/CodeIndex/Database/DbReader.References.cs
index 5ff578d91..245870b32 100644
--- a/src/CodeIndex/Database/DbReader.References.cs
+++ b/src/CodeIndex/Database/DbReader.References.cs
@@ -653,34 +653,8 @@ private bool ShouldSuppressCSharpQualifiedConstantPatternReference(string path,
         return false;
     }
 
-
-    // Query-side mirror of the C# declaration canonicalizer. Users commonly type source
-    // spellings such as `@class` or `Outer.@class`; the DB stores the canonical names
-    // without the verbatim `@`, so query entrypoints normalize to the persisted form first.
-    // Rust macro names are also accepted with a trailing `!` because the extractor stores
-    // them without the punctuation, so `my_macro!` and `my_macro` resolve to the same row.
-    // The normalization is applied when `--lang` is omitted or explicitly `csharp` because
-    // name-based lookup still needs to treat C# verbatim spellings as canonical symbol names.
-    // Other languages, including SQL, must preserve leading `@` characters.
-    // C# 宣言側 canonicalizer の query 側ミラー。`@class` / `Outer.@class` のような source
-    // spelling を受けても、DB 側の `@` なし canonical 名に合わせてから検索する。
-    // Rust macro 名も extractor 側では末尾 `!` を落として保存するため、`my_macro!` と `my_macro`
-    // を同じ行へ解決できるようにする。
-    // `--lang` 未指定または `csharp` 指定では name-based lookup が verbatim spelling を canonical 名へ寄せる。
-    // それ以外の言語、特に SQL では先頭 `@` を保持する。
     private static string? NormalizeCSharpVerbatimQuery(string? query, string? lang)
-    {
-        if (!string.IsNullOrWhiteSpace(lang) && string.Equals(lang, "rust", StringComparison.OrdinalIgnoreCase))
-        {
-            var rustNormalized = NormalizeRustSymbolSearchQuery(query);
-            return string.IsNullOrWhiteSpace(rustNormalized) ? null : rustNormalized;
-        }
-
-        if (!string.IsNullOrWhiteSpace(lang) && !string.Equals(lang, "csharp", StringComparison.OrdinalIgnoreCase))
-            return query;
-        var normalized = query == null ? null : NormalizeDbCSharpQualifiedName(query);
-        return string.IsNullOrWhiteSpace(normalized) ? null : normalized;
-    }
+        => SymbolSearchQueryNormalizer.NormalizeCSharpVerbatim(query, lang);
 
     private static bool IsBareVerbatimQueryToken(string? value)
     {
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchQueryNormalizer.cs b/src/CodeIndex/Database/DbReader.SymbolSearchQueryNormalizer.cs
new file mode 100644
index 000000000..700013d4c
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchQueryNormalizer.cs
@@ -0,0 +1,355 @@
+using System.Text.RegularExpressions;
+using CodeIndex.Indexer;
+using Regex = CodeIndex.Indexer.BoundedRegex;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private static class SymbolSearchQueryNormalizer
+    {
+        private sealed class NormalizedSymbolSearchQueryList : List<string>
+        {
+            public NormalizedSymbolSearchQueryList(IEnumerable<string> queries)
+                : base(queries)
+            {
+            }
+        }
+
+        public static IReadOnlyList<string> MarkNormalized(IEnumerable<string> queries)
+            => new NormalizedSymbolSearchQueryList(queries);
+
+        public static IReadOnlyList<string>? NormalizeQueries(
+            IReadOnlyList<string>? queries,
+            string? lang,
+            bool exact)
+        {
+            if (queries == null)
+                return null;
+            if (queries is NormalizedSymbolSearchQueryList)
+                return queries;
+
+            var seen = new HashSet<string>(StringComparer.Ordinal);
+            var normalized = new List<string>();
+            foreach (var query in queries)
+            {
+                var value = NormalizeForSymbolSearch(query, lang, exact) ?? query ?? string.Empty;
+                if (value.Length == 0 || !seen.Add(value))
+                    continue;
+                normalized.Add(value);
+            }
+
+            return new NormalizedSymbolSearchQueryList(normalized);
+        }
+
+        public static string? Normalize(string? query, string? lang, bool exact)
+        {
+            if (!string.IsNullOrWhiteSpace(lang)
+                && string.Equals(lang, "rust", StringComparison.OrdinalIgnoreCase))
+            {
+                return RustQueryStrategy.Normalize(query, exact);
+            }
+
+            if (!string.IsNullOrWhiteSpace(lang)
+                && string.Equals(lang, "javascript", StringComparison.OrdinalIgnoreCase))
+            {
+                return JavaScriptQueryStrategy.Normalize(query);
+            }
+
+            var terraformNormalized = TerraformQueryStrategy.Normalize(query, lang);
+            return terraformNormalized ?? CSharpQueryStrategy.NormalizeVerbatim(query, lang);
+        }
+
+        public static string? NormalizeForSymbolSearch(string? query, string? lang, bool exact)
+        {
+            if (RustQueryStrategy.ShouldPreserveQualifiedExactQuery(query, lang, exact))
+                return query?.Trim();
+
+            if (exact
+                && !string.IsNullOrWhiteSpace(query)
+                && SqlNameResolver.HasQualifier(query))
+            {
+                if (string.Equals(NormalizeQueryLanguage(lang), "csharp", StringComparison.Ordinal))
+                    return CSharpSymbolNameNormalizer.NormalizeExplicitInterfaceQueryDisplayName(query);
+
+                // Without a language filter the query must retain its original spelling for
+                // non-C# exact matching. C#-specific display and identity aliases are supplied
+                // through their own SQL parameters.
+                // 言語フィルターがない場合、C# 以外の完全一致を保つため query の元表記を
+                // 維持する。C# 専用の表示名・identity alias は個別の SQL parameter で渡す。
+                if (string.IsNullOrWhiteSpace(lang))
+                {
+                    var terraformNormalized = TerraformQueryStrategy.Normalize(query, lang);
+                    return terraformNormalized ?? query.Trim();
+                }
+            }
+
+            return Normalize(query, lang, exact) ?? query;
+        }
+
+        public static string? NormalizeCSharpVerbatim(string? query, string? lang)
+            => CSharpQueryStrategy.NormalizeVerbatim(query, lang);
+
+        public static string? ComputeSwiftBacktickAlias(string? query, string? lang)
+            => SwiftQueryStrategy.ComputeBacktickAlias(query, lang);
+
+        public static bool ShouldPreserveRustQualifiedExactQuery(string? query, string? lang, bool exact)
+            => RustQueryStrategy.ShouldPreserveQualifiedExactQuery(query, lang, exact);
+
+        public static (string? QualifiedPath, string? ContainerPath, string? LeafName)
+            NormalizeRustQualifiedExactQueryParts(string query)
+            => RustQueryStrategy.NormalizeQualifiedExactQueryParts(query);
+
+        private static class TerraformQueryStrategy
+        {
+            private static readonly Regex VarLocalModuleQueryRegex = new(
+                @"^(?:var|local|module)\.(?<name>[A-Za-z_]\w*)(?:\..*)?$",
+                RegexOptions.Compiled);
+
+            private static readonly Regex DataQueryRegex = new(
+                @"^data\.[A-Za-z_]\w*\.(?<name>[A-Za-z_]\w*)(?:\..*)?$",
+                RegexOptions.Compiled);
+
+            public static string? Normalize(string? query, string? lang)
+            {
+                if (!string.IsNullOrWhiteSpace(lang)
+                    && !string.Equals(lang, "terraform", StringComparison.OrdinalIgnoreCase))
+                {
+                    return null;
+                }
+
+                if (string.IsNullOrWhiteSpace(query))
+                    return null;
+
+                var trimmed = query.Trim();
+                if (trimmed.Length == 0)
+                    return null;
+
+                // Terraform dotted prefixes are stored as bare names in references and symbols.
+                var simpleMatch = VarLocalModuleQueryRegex.Match(trimmed);
+                if (simpleMatch.Success)
+                    return simpleMatch.Groups["name"].Value;
+
+                var dataMatch = DataQueryRegex.Match(trimmed);
+                return dataMatch.Success ? dataMatch.Groups["name"].Value : null;
+            }
+        }
+
+        private static class JavaScriptQueryStrategy
+        {
+            public static string? Normalize(string? query)
+            {
+                if (query == null)
+                    return null;
+
+                var trimmed = query.Trim();
+                if (trimmed.Length == 0)
+                    return null;
+
+                var commonJsPrefixLength = GetCommonJsPrefixLength(trimmed);
+                if (commonJsPrefixLength == 0)
+                    return trimmed;
+
+                trimmed = trimmed[commonJsPrefixLength..];
+                if (trimmed.Length == 0)
+                    return null;
+
+                trimmed = trimmed.TrimStart();
+                if (trimmed.StartsWith(".", StringComparison.Ordinal))
+                    trimmed = trimmed[1..].TrimStart();
+
+                return GetCommonJsLeaf(trimmed);
+            }
+
+            private static int GetCommonJsPrefixLength(string query)
+            {
+                if (query.StartsWith("module.exports", StringComparison.Ordinal))
+                {
+                    var nextIndex = "module.exports".Length;
+                    return query.Length > nextIndex && query[nextIndex] is '.' or '[' ? nextIndex : 0;
+                }
+
+                if (query.StartsWith("exports", StringComparison.Ordinal))
+                {
+                    var nextIndex = "exports".Length;
+                    return query.Length > nextIndex && query[nextIndex] is '.' or '[' ? nextIndex : 0;
+                }
+
+                return 0;
+            }
+
+            private static string? GetCommonJsLeaf(string query)
+            {
+                var bracketLeaf = NormalizeBracketLeaf(query);
+                if (bracketLeaf != null)
+                    return bracketLeaf;
+
+                var leafIndex = query.LastIndexOf('.');
+                var leaf = leafIndex >= 0 ? query[(leafIndex + 1)..] : query;
+                return NormalizeBracketLeaf(leaf) ?? (leaf.Length == 0 ? null : leaf);
+            }
+
+            private static string? NormalizeBracketLeaf(string query)
+            {
+                var trimmed = query.Trim();
+                if (trimmed.Length < 3 || trimmed[0] != '[' || trimmed[^1] != ']')
+                    return null;
+
+                var inner = trimmed[1..^1].Trim();
+                if (inner.Length < 2)
+                    return null;
+
+                var quote = inner[0];
+                if (quote is not '\'' and not '"')
+                    return null;
+                if (inner[^1] != quote)
+                    return null;
+
+                var leaf = inner[1..^1].Trim();
+                return leaf.Length == 0 ? null : leaf;
+            }
+        }
+
+        private static class RustQueryStrategy
+        {
+            public static string? Normalize(string? query, bool exact = false)
+            {
+                if (query == null)
+                    return null;
+
+                var macroQuery = query.Trim();
+                if (macroQuery.Length == 0)
+                    return null;
+
+                var isMacroQuery = macroQuery.EndsWith("!", StringComparison.Ordinal);
+                if (isMacroQuery)
+                    macroQuery = macroQuery[..^1].TrimEnd();
+                if (macroQuery.Length == 0)
+                    return null;
+
+                if (exact && isMacroQuery && macroQuery.Contains("::", StringComparison.Ordinal))
+                    return NormalizeQualifiedMacroQuery(macroQuery);
+
+                var leafIndex = macroQuery.LastIndexOf("::", StringComparison.Ordinal);
+                if (leafIndex >= 0)
+                    macroQuery = macroQuery[(leafIndex + 2)..].Trim();
+                if (macroQuery.StartsWith("r#", StringComparison.Ordinal))
+                    macroQuery = macroQuery[2..];
+
+                return macroQuery.Length == 0 ? null : macroQuery;
+            }
+
+            public static bool ShouldPreserveQualifiedExactQuery(string? query, string? lang, bool exact)
+            {
+                return exact
+                    && !string.IsNullOrWhiteSpace(lang)
+                    && string.Equals(lang, "rust", StringComparison.OrdinalIgnoreCase)
+                    && !string.IsNullOrWhiteSpace(query)
+                    && query.Contains("::", StringComparison.Ordinal);
+            }
+
+            public static (string? QualifiedPath, string? ContainerPath, string? LeafName)
+                NormalizeQualifiedExactQueryParts(string query)
+            {
+                var trimmed = query.Trim();
+                if (trimmed.Length == 0)
+                    return (null, null, null);
+
+                if (trimmed.EndsWith("!", StringComparison.Ordinal))
+                    trimmed = trimmed[..^1].TrimEnd();
+
+                var normalized = NormalizeQualifiedMacroQuery(trimmed);
+                if (string.IsNullOrWhiteSpace(normalized))
+                    return (null, null, null);
+
+                normalized = TrimQualifiedPathPrefixes(normalized.Replace("::", "."));
+                var lastDot = normalized.LastIndexOf('.');
+                return lastDot < 0
+                    ? (normalized, string.Empty, normalized)
+                    : (normalized, normalized[..lastDot], normalized[(lastDot + 1)..]);
+            }
+
+            private static string? NormalizeQualifiedMacroQuery(string query)
+            {
+                var segments = query
+                    .Split("::", StringSplitOptions.None)
+                    .Select(segment => segment.Trim())
+                    .Where(segment => segment.Length > 0)
+                    .Select(segment => segment.StartsWith("r#", StringComparison.Ordinal) ? segment[2..] : segment)
+                    .ToList();
+
+                return segments.Count == 0 ? null : string.Join("::", segments);
+            }
+
+            private static string TrimQualifiedPathPrefixes(string query)
+            {
+                while (query.StartsWith("crate.", StringComparison.Ordinal)
+                    || query.StartsWith("self.", StringComparison.Ordinal)
+                    || query.StartsWith("super.", StringComparison.Ordinal))
+                {
+                    var dotIndex = query.IndexOf('.');
+                    if (dotIndex < 0 || dotIndex == query.Length - 1)
+                        break;
+
+                    query = query[(dotIndex + 1)..];
+                }
+
+                return query;
+            }
+        }
+
+        private static class SwiftQueryStrategy
+        {
+            public static string? ComputeBacktickAlias(string? query, string? lang)
+            {
+                if (!string.Equals(lang, "swift", StringComparison.OrdinalIgnoreCase)
+                    || string.IsNullOrWhiteSpace(query))
+                {
+                    return null;
+                }
+
+                var trimmed = query.Trim();
+                if (trimmed.Length == 0
+                    || trimmed.IndexOfAny(['`', ':', '/', '<', '>', '(', ')', '[', ']', ' ']) >= 0)
+                {
+                    return null;
+                }
+
+                var lastDot = trimmed.LastIndexOf('.');
+                if (lastDot < 0)
+                    return $"`{trimmed}`";
+                if (lastDot == 0 || lastDot == trimmed.Length - 1)
+                    return null;
+
+                var prefix = trimmed[..(lastDot + 1)];
+                var leaf = trimmed[(lastDot + 1)..];
+                return leaf.IndexOf('.') >= 0 ? null : $"{prefix}`{leaf}`";
+            }
+        }
+
+        private static class CSharpQueryStrategy
+        {
+            // Query-side mirror of the C# declaration canonicalizer. C# source spellings such as
+            // `@class` are canonicalized when no language or C# is selected. Other languages,
+            // especially SQL, retain a leading `@`. Rust also retains its macro query policy.
+            public static string? NormalizeVerbatim(string? query, string? lang)
+            {
+                if (!string.IsNullOrWhiteSpace(lang)
+                    && string.Equals(lang, "rust", StringComparison.OrdinalIgnoreCase))
+                {
+                    var rustNormalized = RustQueryStrategy.Normalize(query);
+                    return string.IsNullOrWhiteSpace(rustNormalized) ? null : rustNormalized;
+                }
+
+                if (!string.IsNullOrWhiteSpace(lang)
+                    && !string.Equals(lang, "csharp", StringComparison.OrdinalIgnoreCase))
+                {
+                    return query;
+                }
+
+                var normalized = query == null ? null : NormalizeDbCSharpQualifiedName(query);
+                return string.IsNullOrWhiteSpace(normalized) ? null : normalized;
+            }
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbSymbolReader.Search.cs b/src/CodeIndex/Database/DbSymbolReader.Search.cs
index 37d812f66..c9a710b67 100644
--- a/src/CodeIndex/Database/DbSymbolReader.Search.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.Search.cs
@@ -1,9 +1,7 @@
 using System.Globalization;
 using System.Text.Json;
-using System.Text.RegularExpressions;
 using CodeIndex.Indexer;
 using Microsoft.Data.Sqlite;
-using Regex = CodeIndex.Indexer.BoundedRegex;
 
 namespace CodeIndex.Database;
 
@@ -12,33 +10,11 @@ public partial class DbReader
     private const string GenericSymbolRankNamePenaltySqlLiteral = "0.01";
     private const string GenericSymbolRankNamesSql = "('add','all','any','append','appendline','average','build','call','combine','contains','convert','count','create','distinct','equal','equals','execute','exists','file','files','first','firstordefault','get','getboolean','getbyte','getbytes','getchar','getchars','getdatetime','getdecimal','getdouble','getfieldvalue','getfloat','getguid','getint16','getint32','getint64','getordinal','getstring','gettemppath','getvalue','getvalues','groupby','handle','id','invoke','isdbnull','key','kind','last','lastordefault','length','line','list','load','name','orderby','orderbydescending','parse','path','process','read','resolve','run','set','single','singleordefault','skip','start','stop','sum','take','text','thenby','thenbydescending','tolist','tostring','tryparse','type','update','value','values','write')";
 
-    private sealed class NormalizedSymbolSearchQueryList : List<string>
-    {
-        public NormalizedSymbolSearchQueryList(IEnumerable<string> queries)
-            : base(queries)
-        {
-        }
-    }
-
-    private static IReadOnlyList<string>? NormalizeSymbolSearchQueries(IReadOnlyList<string>? queries, string? lang, bool exact)
-    {
-        if (queries == null)
-            return null;
-        if (queries is NormalizedSymbolSearchQueryList)
-            return queries;
-
-        var seen = new HashSet<string>(StringComparer.Ordinal);
-        var normalized = new List<string>();
-        foreach (var query in queries)
-        {
-            var value = NormalizeSymbolSearchQueryForSymbolSearch(query, lang, exact) ?? query ?? string.Empty;
-            if (value.Length == 0 || !seen.Add(value))
-                continue;
-            normalized.Add(value);
-        }
-
-        return new NormalizedSymbolSearchQueryList(normalized);
-    }
+    private static IReadOnlyList<string>? NormalizeSymbolSearchQueries(
+        IReadOnlyList<string>? queries,
+        string? lang,
+        bool exact)
+        => SymbolSearchQueryNormalizer.NormalizeQueries(queries, lang, exact);
 
     /// <summary>
     /// Escape LIKE wildcards (%, _) in user input to prevent unintended pattern matching.
@@ -84,7 +60,7 @@ public List<SymbolResult> SearchSymbols(string? query = null, int limit = 20, st
         return SearchSymbols(
             normalizedQuery == null
                 ? null
-                : new NormalizedSymbolSearchQueryList([normalizedQuery]),
+                : SymbolSearchQueryNormalizer.MarkNormalized([normalizedQuery]),
             limit, kind, lang, pathPatterns, excludePathPatterns, excludeTests, since, exact,
             visibilityFilters, excludeVisibilityFilters, sortMode, startLine, endLine,
             groupPartials, offset);
@@ -96,7 +72,7 @@ public int CountSearchSymbols(string? query = null, int limit = 20, string? kind
         return CountSearchSymbols(
             normalizedQuery == null
                 ? null
-                : new NormalizedSymbolSearchQueryList([normalizedQuery]),
+                : SymbolSearchQueryNormalizer.MarkNormalized([normalizedQuery]),
             limit, kind, lang, pathPatterns, excludePathPatterns, excludeTests, since, exact,
             visibilityFilters, excludeVisibilityFilters);
     }
@@ -110,7 +86,7 @@ public bool AnySearchSymbols(IReadOnlyList<string>? queries, string? kind = null
         foreach (var query in validQueries)
         {
             if (CountSearchSymbols(
-                    new NormalizedSymbolSearchQueryList([query]),
+                    SymbolSearchQueryNormalizer.MarkNormalized([query]),
                     1,
                     kind,
                     lang,
@@ -1193,268 +1169,18 @@ private string BuildSymbolSortOrderBy(
     }
 
     private static string? NormalizeSymbolSearchQuery(string? query, string? lang, bool exact = false)
-    {
-        if (!string.IsNullOrWhiteSpace(lang) && string.Equals(lang, "rust", StringComparison.OrdinalIgnoreCase))
-            return NormalizeRustSymbolSearchQuery(query, exact);
-
-        if (!string.IsNullOrWhiteSpace(lang) && string.Equals(lang, "javascript", StringComparison.OrdinalIgnoreCase))
-            return NormalizeJavaScriptSymbolSearchQuery(query);
-
-        // Terraform dotted prefixes (var.X / local.X / module.X / data.TYPE.X) are stored as bare names in
-        // the references and symbols tables. Strip the prefix so queries pasted from HCL still resolve.
-        // Terraform の dotted prefix（var.X / local.X / module.X / data.TYPE.X）は参照/シンボルの bare 名で格納されるため、
-        // HCL からそのまま貼り付けたクエリでも解決できるよう prefix を取り除く。
-        var terraformNormalized = NormalizeTerraformDottedQuery(query, lang);
-        if (terraformNormalized != null)
-            return terraformNormalized;
-
-        return NormalizeCSharpVerbatimQuery(query, lang);
-    }
-
-    private static readonly Regex TerraformVarLocalModuleQueryRegex = new(
-        @"^(?:var|local|module)\.(?<name>[A-Za-z_]\w*)(?:\..*)?$",
-        RegexOptions.Compiled);
-
-    private static readonly Regex TerraformDataQueryRegex = new(
-        @"^data\.[A-Za-z_]\w*\.(?<name>[A-Za-z_]\w*)(?:\..*)?$",
-        RegexOptions.Compiled);
-
-    private static string? NormalizeTerraformDottedQuery(string? query, string? lang)
-    {
-        if (!string.IsNullOrWhiteSpace(lang)
-            && !string.Equals(lang, "terraform", StringComparison.OrdinalIgnoreCase))
-        {
-            return null;
-        }
-
-        if (string.IsNullOrWhiteSpace(query))
-            return null;
-
-        var trimmed = query.Trim();
-        if (trimmed.Length == 0)
-            return null;
-
-        var simpleMatch = TerraformVarLocalModuleQueryRegex.Match(trimmed);
-        if (simpleMatch.Success)
-            return simpleMatch.Groups["name"].Value;
-
-        var dataMatch = TerraformDataQueryRegex.Match(trimmed);
-        if (dataMatch.Success)
-            return dataMatch.Groups["name"].Value;
-
-        return null;
-    }
+        => SymbolSearchQueryNormalizer.Normalize(query, lang, exact);
 
     private static string? ComputeSwiftBacktickAlias(string? query, string? lang)
-    {
-        if (!string.Equals(lang, "swift", StringComparison.OrdinalIgnoreCase) || string.IsNullOrWhiteSpace(query))
-            return null;
-
-        var trimmed = query.Trim();
-        if (trimmed.Length == 0)
-            return null;
-
-        if (trimmed.IndexOfAny(['`', ':', '/', '<', '>', '(', ')', '[', ']', ' ']) >= 0)
-            return null;
-
-        var lastDot = trimmed.LastIndexOf('.');
-        if (lastDot < 0)
-            return $"`{trimmed}`";
-
-        if (lastDot == 0 || lastDot == trimmed.Length - 1)
-            return null;
-
-        var prefix = trimmed[..(lastDot + 1)];
-        var leaf = trimmed[(lastDot + 1)..];
-        if (leaf.IndexOf('.') >= 0)
-            return null;
-
-        return $"{prefix}`{leaf}`";
-    }
-
-    private static string? NormalizeJavaScriptSymbolSearchQuery(string? query)
-    {
-        if (query == null)
-            return null;
-
-        var trimmed = query.Trim();
-        if (trimmed.Length == 0)
-            return null;
-
-        var commonJsPrefixLength = 0;
-        if (trimmed.StartsWith("module.exports", StringComparison.Ordinal))
-        {
-            var nextIndex = "module.exports".Length;
-            if (trimmed.Length > nextIndex && trimmed[nextIndex] is '.' or '[')
-                commonJsPrefixLength = nextIndex;
-        }
-        else if (trimmed.StartsWith("exports", StringComparison.Ordinal))
-        {
-            var nextIndex = "exports".Length;
-            if (trimmed.Length > nextIndex && trimmed[nextIndex] is '.' or '[')
-                commonJsPrefixLength = nextIndex;
-        }
-
-        if (commonJsPrefixLength == 0)
-            return trimmed;
-
-        trimmed = trimmed[commonJsPrefixLength..];
-        if (trimmed.Length == 0)
-            return null;
-
-        trimmed = trimmed.TrimStart();
-        if (trimmed.StartsWith(".", StringComparison.Ordinal))
-            trimmed = trimmed[1..].TrimStart();
-
-        var bracketLeaf = NormalizeJavaScriptBracketLeaf(trimmed);
-        if (bracketLeaf != null)
-            return bracketLeaf;
-
-        var leafIndex = trimmed.LastIndexOf('.');
-        if (leafIndex >= 0)
-            trimmed = trimmed[(leafIndex + 1)..];
-
-        bracketLeaf = NormalizeJavaScriptBracketLeaf(trimmed);
-        if (bracketLeaf != null)
-            return bracketLeaf;
-
-        return trimmed.Length == 0 ? null : trimmed;
-    }
-
-    private static string? NormalizeJavaScriptBracketLeaf(string query)
-    {
-        var trimmed = query.Trim();
-        if (trimmed.Length < 3 || trimmed[0] != '[' || trimmed[^1] != ']')
-            return null;
-
-        var inner = trimmed[1..^1].Trim();
-        if (inner.Length < 2)
-            return null;
-
-        var quote = inner[0];
-        if (quote is not '\'' and not '"')
-            return null;
-
-        if (inner[^1] != quote)
-            return null;
-
-        var leaf = inner[1..^1].Trim();
-        return leaf.Length == 0 ? null : leaf;
-    }
-
-    private static string? NormalizeRustSymbolSearchQuery(string? query, bool exact = false)
-    {
-        if (query == null)
-            return null;
-
-        var trimmed = query.Trim();
-        if (trimmed.Length == 0)
-            return null;
-
-        var macroQuery = trimmed;
-        var isMacroQuery = macroQuery.EndsWith("!", StringComparison.Ordinal);
-        if (isMacroQuery)
-            macroQuery = macroQuery[..^1].TrimEnd();
-
-        if (macroQuery.Length == 0)
-            return null;
-
-        if (exact && isMacroQuery && macroQuery.Contains("::", StringComparison.Ordinal))
-            return NormalizeRustQualifiedMacroQuery(macroQuery);
-
-        var leafIndex = macroQuery.LastIndexOf("::", StringComparison.Ordinal);
-        if (leafIndex >= 0)
-            macroQuery = macroQuery[(leafIndex + 2)..].Trim();
-
-        if (macroQuery.StartsWith("r#", StringComparison.Ordinal))
-            macroQuery = macroQuery[2..];
-
-        return macroQuery.Length == 0 ? null : macroQuery;
-    }
-
-    private static string? NormalizeRustQualifiedMacroQuery(string query)
-    {
-        var segments = query
-            .Split("::", StringSplitOptions.None)
-            .Select(segment => segment.Trim())
-            .Where(segment => segment.Length > 0)
-            .Select(segment => segment.StartsWith("r#", StringComparison.Ordinal) ? segment[2..] : segment)
-            .ToList();
-
-        return segments.Count == 0 ? null : string.Join("::", segments);
-    }
+        => SymbolSearchQueryNormalizer.ComputeSwiftBacktickAlias(query, lang);
 
     private static bool ShouldPreserveRustQualifiedExactQuery(string? query, string? lang, bool exact)
-    {
-        return exact
-            && !string.IsNullOrWhiteSpace(lang)
-            && string.Equals(lang, "rust", StringComparison.OrdinalIgnoreCase)
-            && !string.IsNullOrWhiteSpace(query)
-            && query.Contains("::", StringComparison.Ordinal);
-    }
+        => SymbolSearchQueryNormalizer.ShouldPreserveRustQualifiedExactQuery(query, lang, exact);
 
     private static string? NormalizeSymbolSearchQueryForSymbolSearch(string? query, string? lang, bool exact)
-    {
-        if (ShouldPreserveRustQualifiedExactQuery(query, lang, exact))
-            return query?.Trim();
-        if (exact
-            && !string.IsNullOrWhiteSpace(query)
-            && SqlNameResolver.HasQualifier(query))
-        {
-            if (string.Equals(
-                    NormalizeQueryLanguage(lang),
-                    "csharp",
-                    StringComparison.Ordinal))
-            {
-                return CSharpSymbolNameNormalizer.NormalizeExplicitInterfaceQueryDisplayName(query);
-            }
-
-            // Without a language filter the query must retain its original spelling for
-            // non-C# exact matching. C#-specific display and identity aliases are supplied
-            // through their own SQL parameters.
-            // 言語フィルターがない場合、C# 以外の完全一致を保つため query の元表記を
-            // 維持する。C# 専用の表示名・identity alias は個別の SQL parameter で渡す。
-            if (string.IsNullOrWhiteSpace(lang))
-            {
-                var terraformNormalized = NormalizeTerraformDottedQuery(query, lang);
-                if (terraformNormalized != null)
-                    return terraformNormalized;
-                return query.Trim();
-            }
-        }
-
-        return NormalizeSymbolSearchQuery(query, lang, exact) ?? query;
-    }
+        => SymbolSearchQueryNormalizer.NormalizeForSymbolSearch(query, lang, exact);
 
     private static (string? QualifiedPath, string? ContainerPath, string? LeafName) NormalizeRustQualifiedExactQueryParts(string query)
-    {
-        var trimmed = query.Trim();
-        if (trimmed.Length == 0)
-            return (null, null, null);
-
-        if (trimmed.EndsWith("!", StringComparison.Ordinal))
-            trimmed = trimmed[..^1].TrimEnd();
-
-        var normalized = NormalizeRustQualifiedMacroQuery(trimmed);
-        if (string.IsNullOrWhiteSpace(normalized))
-            return (null, null, null);
-
-        normalized = normalized.Replace("::", ".");
-        while (normalized.StartsWith("crate.", StringComparison.Ordinal)
-            || normalized.StartsWith("self.", StringComparison.Ordinal)
-            || normalized.StartsWith("super.", StringComparison.Ordinal))
-        {
-            var dotIndex = normalized.IndexOf('.');
-            if (dotIndex < 0 || dotIndex == normalized.Length - 1)
-                break;
-
-            normalized = normalized[(dotIndex + 1)..];
-        }
-        var lastDot = normalized.LastIndexOf('.');
-        if (lastDot < 0)
-            return (normalized, string.Empty, normalized);
-
-        return (normalized, normalized[..lastDot], normalized[(lastDot + 1)..]);
-    }
+        => SymbolSearchQueryNormalizer.NormalizeRustQualifiedExactQueryParts(query);
 
 }

From 5e67fff6ee3195e8e0909b1e0398ffc117203821 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 08:48:06 +0900
Subject: [PATCH 12/45] Decompose symbol search execution

---
 .../DbReader.SymbolSearchBoundedCount.cs      |   64 +
 .../Database/DbReader.SymbolSearchList.cs     |   61 +
 .../DbReader.SymbolSearchListQueryBuilder.cs  |  274 +++++
 .../DbReader.SymbolSearchMultiQuery.cs        |   59 +
 .../DbReader.SymbolSearchPredicates.cs        |  177 +++
 .../DbReader.SymbolSearchProjection.cs        |  158 +++
 .../DbReader.SymbolSearchQueryBinding.cs      |  338 ++++++
 .../DbReader.SymbolSearchQueryPlan.cs         |   37 +
 .../Database/DbReader.SymbolSearchSql.cs      |  174 +++
 .../DbReader.SymbolSearchTotalCount.cs        |   68 ++
 .../Database/DbSymbolReader.Search.cs         | 1071 -----------------
 11 files changed, 1410 insertions(+), 1071 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchBoundedCount.cs
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchList.cs
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchListQueryBuilder.cs
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchMultiQuery.cs
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchPredicates.cs
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchProjection.cs
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchQueryBinding.cs
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchQueryPlan.cs
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchSql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.SymbolSearchTotalCount.cs

diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchBoundedCount.cs b/src/CodeIndex/Database/DbReader.SymbolSearchBoundedCount.cs
new file mode 100644
index 000000000..5dcfecbc5
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchBoundedCount.cs
@@ -0,0 +1,64 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    public int CountSearchSymbols(IReadOnlyList<string>? queries, int limit = 20, string? kind = null, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, DateTime? since = null, bool exact = false, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null)
+    {
+        var plan = SymbolSearchQueryPlanBuilder.Build(new SymbolSearchQueryPlan
+        {
+            Queries = queries,
+            Limit = limit,
+            Kind = kind,
+            Lang = lang,
+            PathPatterns = pathPatterns,
+            ExcludePathPatterns = excludePathPatterns,
+            ExcludeTests = excludeTests,
+            Since = since,
+            Exact = exact,
+            VisibilityFilters = visibilityFilters,
+            ExcludeVisibilityFilters = excludeVisibilityFilters,
+        });
+        return ExecuteBoundedSymbolSearch(plan);
+    }
+
+    private int ExecuteBoundedSymbolSearch(SymbolSearchQueryPlan plan)
+    {
+        if (plan.Queries != null
+            && (plan.Queries.Count > 1
+                || string.Equals(plan.Lang, "markdown", StringComparison.Ordinal)))
+        {
+            return SearchSymbols(
+                plan.Queries,
+                plan.Limit,
+                plan.Kind,
+                plan.Lang,
+                plan.PathPatterns,
+                plan.ExcludePathPatterns,
+                plan.ExcludeTests,
+                plan.Since,
+                plan.Exact,
+                plan.VisibilityFilters,
+                plan.ExcludeVisibilityFilters).Count;
+        }
+
+        using var cmd = _conn.CreateCommand();
+
+        var innerSql = @"
+            SELECT 1
+            FROM symbols s
+            JOIN files f ON s.file_id = f.id
+            WHERE 1=1";
+
+        innerSql += SymbolSearchQueryPredicateBuilder.BuildBounded(this, plan);
+        SymbolSearchQueryPredicateBuilder.AppendFilters(this, ref innerSql, plan, includeLineRange: false);
+        innerSql += " LIMIT @limit";
+
+        cmd.CommandText = $"SELECT COUNT(*) FROM ({innerSql})";
+        SymbolSearchQueryBinder.BindBoundedQuery(this, cmd, plan);
+        SymbolSearchQueryBinder.BindFilters(this, cmd, plan, includeLineRange: false);
+        SqliteCommandPolicy.Add(cmd, "@limit", plan.Limit);
+
+        var raw = cmd.ExecuteScalar();
+        return raw is long l ? (int)l : Convert.ToInt32(raw);
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchList.cs b/src/CodeIndex/Database/DbReader.SymbolSearchList.cs
new file mode 100644
index 000000000..af743d787
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchList.cs
@@ -0,0 +1,61 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    /// <summary>
+    /// Search symbols by one or more name patterns (OR-joined). Empty/null list returns all symbols matching other filters.
+    /// When <paramref name="exact"/> is true, names are matched case-insensitively for equality instead of substring.
+    /// 複数名前パターン（OR結合）でシンボルを検索。空/null なら他フィルタに一致する全シンボルを返す。
+    /// <paramref name="exact"/> が true の場合、部分一致ではなく大文字小文字を無視した完全一致になる。
+    /// </summary>
+    public List<SymbolResult> SearchSymbols(IReadOnlyList<string>? queries, int limit = 20, string? kind = null, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, DateTime? since = null, bool exact = false, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null, SymbolSortMode sortMode = SymbolSortMode.Name, int? startLine = null, int? endLine = null, bool groupPartials = false, int offset = 0)
+    {
+        var plan = SymbolSearchQueryPlanBuilder.Build(new SymbolSearchQueryPlan
+        {
+            Queries = queries,
+            Limit = limit,
+            Kind = kind,
+            Lang = lang,
+            PathPatterns = pathPatterns,
+            ExcludePathPatterns = excludePathPatterns,
+            ExcludeTests = excludeTests,
+            Since = since,
+            Exact = exact,
+            VisibilityFilters = visibilityFilters,
+            ExcludeVisibilityFilters = excludeVisibilityFilters,
+            SortMode = sortMode,
+            StartLine = startLine,
+            EndLine = endLine,
+            GroupPartials = groupPartials,
+            Offset = offset,
+        });
+        return ExecuteSymbolSearchList(plan);
+    }
+
+    private List<SymbolResult> ExecuteSymbolSearchList(SymbolSearchQueryPlan plan)
+    {
+        if (plan.Queries is { Count: > 1 })
+            return ExecuteMultiQuerySymbolSearch(plan);
+
+        if (plan.GroupPartials)
+        {
+            EnsureCSharpCallableTypeKinds(
+                plan.Lang,
+                plan.Queries,
+                plan.Exact,
+                plan.Kind);
+        }
+        using var cmd = _conn.CreateCommand();
+
+        var sql = BuildSymbolSearchListSql(plan);
+        cmd.CommandText = sql;
+        SymbolSearchQueryBinder.BindFullQueries(this, cmd, plan);
+        SymbolSearchQueryBinder.BindListOrdering(cmd, plan);
+        SymbolSearchQueryBinder.BindFilters(this, cmd, plan, includeLineRange: true);
+        SqliteCommandPolicy.Add(cmd, "@limit", plan.Limit);
+        SqliteCommandPolicy.Add(cmd, "@offset", Math.Max(0, plan.Offset));
+
+        using var reader = cmd.ExecuteTrackedReader();
+        return SymbolSearchRowProjector.ReadAll(reader, plan);
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchListQueryBuilder.cs b/src/CodeIndex/Database/DbReader.SymbolSearchListQueryBuilder.cs
new file mode 100644
index 000000000..471e29cbb
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchListQueryBuilder.cs
@@ -0,0 +1,274 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed record SymbolSearchColumnSql(
+        string StartLine,
+        string EndLine,
+        string BodyStartLine,
+        string BodyEndLine,
+        string Signature,
+        string ContainerKind,
+        string ContainerName,
+        string ContainerQualifiedName,
+        string FamilyKey,
+        string Visibility,
+        string ReturnType,
+        string StartColumn,
+        string SizeLines);
+
+    private sealed record SymbolSearchRankingSql(
+        string Join,
+        string GenericNamePenalty,
+        string DefinitionSites,
+        string ReferenceCount,
+        string HotspotScore,
+        string RankingReferenceScore,
+        string RankingHotspotScore,
+        string StructuralRankPenalty,
+        string ComplexityScore,
+        string ExactNameOrder);
+
+    private sealed record SymbolSearchCanonicalSql(
+        string LogicalPartialKey,
+        string Generated,
+        string PrimaryRank,
+        string SemanticScore,
+        string DeclarationIdentity);
+
+    private string BuildSymbolSearchListSql(SymbolSearchQueryPlan plan)
+    {
+        var columns = BuildSymbolSearchColumnSql();
+        var includeRankSignals =
+            plan.SortMode != SymbolSortMode.Name && _hasReferencesTable;
+        var ranking = BuildSymbolSearchRankingSql(columns, includeRankSignals);
+        var canonical = BuildSymbolSearchCanonicalSql(columns);
+        var sql = BuildSymbolSearchSelectSql(columns, ranking, canonical);
+        sql += SymbolSearchQueryPredicateBuilder.BuildFull(this, plan);
+        SymbolSearchQueryPredicateBuilder.AppendFilters(
+            this,
+            ref sql,
+            plan,
+            includeLineRange: true);
+        if (plan.GroupPartials)
+        {
+            sql = BuildLogicalPartialSymbolQuery(sql, plan.SortMode);
+        }
+        else
+        {
+            sql += BuildSymbolSortOrderBy(
+                plan.SortMode,
+                ranking.ExactNameOrder,
+                ranking.ReferenceCount,
+                ranking.HotspotScore,
+                ranking.RankingReferenceScore,
+                ranking.RankingHotspotScore,
+                columns.SizeLines,
+                ranking.ComplexityScore,
+                columns.StartColumn);
+        }
+
+        return sql + " LIMIT @limit OFFSET @offset";
+    }
+
+    private SymbolSearchColumnSql BuildSymbolSearchColumnSql()
+    {
+        var startLine = GetSymbolColumnSql("start_line", "s.line");
+        var endLine = GetSymbolColumnSql("end_line", "s.line");
+        return new SymbolSearchColumnSql(
+            startLine,
+            endLine,
+            GetSymbolColumnSql("body_start_line"),
+            GetSymbolColumnSql("body_end_line"),
+            GetSymbolColumnSql("signature"),
+            GetSymbolColumnSql("container_kind"),
+            GetSymbolColumnSql("container_name"),
+            GetSymbolColumnSql("container_qualified_name"),
+            GetSymbolColumnSql("family_key"),
+            GetSymbolColumnSql("visibility"),
+            GetSymbolColumnSql("return_type"),
+            GetSymbolColumnSql("start_column", "CAST(2147483647 AS INTEGER)"),
+            $"CASE WHEN ({endLine}) >= ({startLine}) THEN ({endLine}) - ({startLine}) + 1 ELSE 1 END");
+    }
+
+    private SymbolSearchRankingSql BuildSymbolSearchRankingSql(
+        SymbolSearchColumnSql columns,
+        bool includeRankSignals)
+    {
+        var genericPenalty = includeRankSignals
+            ? GetGenericSymbolRankNamePenaltySql("s.name")
+            : "1.0";
+        var definitionSites = includeRankSignals
+            ? "COALESCE(symbol_defs.definition_sites, 1)"
+            : "CAST(1 AS INTEGER)";
+        var conservativeSignal = includeRankSignals
+            ? $"(f.lang = 'csharp' AND (s.kind = 'property' OR ({definitionSites}) > 1 OR lower(s.name) IN {GenericSymbolRankNamesSql}))"
+            : "0";
+        var referenceCount = includeRankSignals
+            ? $"CASE WHEN {conservativeSignal} THEN COALESCE(symbol_file_rank.reference_count, 0) ELSE COALESCE(symbol_rank.reference_count, 0) END"
+            : "CAST(0 AS INTEGER)";
+        var hotspotScore = includeRankSignals
+            ? $"CASE WHEN {conservativeSignal} THEN COALESCE(symbol_file_rank.hotspot_score, 0.0) ELSE COALESCE(symbol_rank.hotspot_score, 0.0) END"
+            : "CAST(0.0 AS REAL)";
+        var dilution = $"CASE WHEN ({definitionSites}) > 1 THEN CAST(({definitionSites}) * ({definitionSites}) AS REAL) ELSE 1.0 END";
+        var structuralPenalty = includeRankSignals
+            ? $"CASE WHEN s.kind IN ('property', 'enum') AND ({columns.SizeLines}) <= 1 THEN 0.1 ELSE 1.0 END"
+            : "1.0";
+        var rankingReference = includeRankSignals
+            ? $"(({referenceCount}) * ({genericPenalty}) * ({structuralPenalty}) / ({dilution}))"
+            : referenceCount;
+        var rankingHotspot = includeRankSignals
+            ? $"(({hotspotScore}) * ({genericPenalty}) * ({structuralPenalty}) / ({dilution}))"
+            : hotspotScore;
+        var cappedReference = $"CASE WHEN ({rankingReference}) > 100.0 THEN 100.0 ELSE ({rankingReference}) END";
+        var cappedHotspot = $"CASE WHEN ({rankingHotspot}) > 150.0 THEN 150.0 ELSE ({rankingHotspot}) END";
+        var complexity = $@"(({columns.SizeLines} * 16.0) + ({cappedReference} * 0.75) + ({cappedHotspot} * 0.35) + CASE
+                       WHEN {columns.Visibility} IN ('public', 'pub', 'open', 'export') THEN 8.0
+                       WHEN {columns.Visibility} IN ('protected', 'internal', 'protected internal') THEN 4.0
+                       ELSE 0.0
+                   END)";
+        return new SymbolSearchRankingSql(
+            BuildSymbolRankJoin(includeRankSignals),
+            genericPenalty,
+            definitionSites,
+            referenceCount,
+            hotspotScore,
+            rankingReference,
+            rankingHotspot,
+            structuralPenalty,
+            complexity,
+            BuildExactSymbolNameOrderSql());
+    }
+
+    private static string BuildSymbolRankJoin(bool includeRankSignals)
+    {
+        return includeRankSignals
+            ? $@"
+            LEFT JOIN (
+                SELECT rf.lang AS lang,
+                       sr.symbol_name AS symbol_name,
+                       COUNT(*) AS reference_count,
+                       SUM({GetHotspotReferenceWeightSql("sr.reference_kind")}) AS hotspot_score
+                FROM symbol_references sr
+                JOIN files rf ON rf.id = sr.file_id
+                WHERE sr.reference_kind IN {CallGraphReferenceKindsSql}
+                  AND sr.symbol_name IS NOT NULL
+                  AND sr.symbol_name <> ''
+                GROUP BY rf.lang, sr.symbol_name COLLATE NOCASE
+            ) symbol_rank
+              ON symbol_rank.lang = f.lang
+             AND symbol_rank.symbol_name = s.name COLLATE NOCASE
+            LEFT JOIN (
+                SELECT sr.file_id AS file_id,
+                       sr.symbol_name AS symbol_name,
+                       COUNT(*) AS reference_count,
+                       SUM({GetHotspotReferenceWeightSql("sr.reference_kind")}) AS hotspot_score
+                FROM symbol_references sr
+                WHERE sr.reference_kind IN {CallGraphReferenceKindsSql}
+                  AND sr.symbol_name IS NOT NULL
+                  AND sr.symbol_name <> ''
+                GROUP BY sr.file_id, sr.symbol_name COLLATE NOCASE
+            ) symbol_file_rank
+              ON symbol_file_rank.file_id = s.file_id
+             AND symbol_file_rank.symbol_name = s.name COLLATE NOCASE
+            LEFT JOIN (
+                SELECT df.lang AS lang,
+                       ds.name AS symbol_name,
+                       COUNT(*) AS definition_sites
+                FROM symbols ds
+                JOIN files df ON df.id = ds.file_id
+                WHERE ds.name IS NOT NULL
+                  AND ds.name <> ''
+                GROUP BY df.lang, ds.name COLLATE NOCASE
+            ) symbol_defs
+              ON symbol_defs.lang = f.lang
+             AND symbol_defs.symbol_name = s.name COLLATE NOCASE"
+            : string.Empty;
+    }
+
+    private SymbolSearchCanonicalSql BuildSymbolSearchCanonicalSql(
+        SymbolSearchColumnSql columns)
+    {
+        var logicalPartialKey = BuildLogicalPartialKeySql(
+            columns.Signature,
+            columns.ContainerName,
+            columns.ContainerQualifiedName,
+            columns.FamilyKey,
+            columns.ReturnType);
+        var generated = _fileColumns.Contains("generated")
+            ? "CASE WHEN COALESCE(f.generated, 0) <> 0 OR codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END"
+            : "CASE WHEN codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END";
+        var primaryRank = LogicalPartialSymbolGrouper.BuildSqlPrimaryRankExpression(
+            "s.kind",
+            columns.BodyStartLine,
+            columns.BodyEndLine);
+        var semanticScore = LogicalPartialSymbolGrouper.BuildSqlSemanticScoreExpression(
+            columns.Signature,
+            "s.kind",
+            GetSymbolColumnSql("declaration_semantic_score"));
+        var fallbackIdentity = BuildCanonicalDeclarationIdentitySql(columns.Signature);
+        var declarationIdentity =
+            $"CASE WHEN s.kind IN ('function', 'test.method') THEN COALESCE(csharp_partial_callable_identity({columns.Signature}, s.name, {columns.ReturnType}), {fallbackIdentity}) ELSE {fallbackIdentity} END";
+        return new SymbolSearchCanonicalSql(
+            logicalPartialKey,
+            generated,
+            primaryRank,
+            semanticScore,
+            declarationIdentity);
+    }
+
+    private string BuildSymbolSearchSelectSql(
+        SymbolSearchColumnSql columns,
+        SymbolSearchRankingSql ranking,
+        SymbolSearchCanonicalSql canonical)
+    {
+        return $@"
+            SELECT f.path, f.lang, s.kind, {GetSymbolColumnSql("sub_kind")} AS sub_kind, s.name, s.line,
+                   {columns.StartLine} AS start_line,
+                   {GetSymbolColumnSql("start_column")} AS start_column,
+                   {columns.EndLine} AS end_line,
+                   {columns.BodyStartLine} AS body_start_line,
+                   {columns.BodyEndLine} AS body_end_line,
+                   {columns.Signature} AS signature,
+                   {columns.ContainerKind} AS container_kind,
+                   {columns.ContainerName} AS container_name,
+                   {columns.Visibility} AS visibility,
+                   {columns.ReturnType} AS return_type,
+                   {ranking.ReferenceCount} AS reference_count,
+                   {ranking.HotspotScore} AS hotspot_score,
+                   {ranking.RankingReferenceScore} AS ranking_reference_score,
+                   {ranking.RankingHotspotScore} AS ranking_hotspot_score,
+                   {ranking.GenericNamePenalty} AS generic_name_penalty,
+                   {ranking.StructuralRankPenalty} AS structural_rank_penalty,
+                   {ranking.DefinitionSites} AS definition_sites,
+                   {columns.SizeLines} AS size_lines,
+                   {ranking.ComplexityScore} AS complexity_score,
+                   {columns.ContainerQualifiedName} AS container_qualified_name,
+                   {canonical.LogicalPartialKey} AS logical_partial_key,
+                   s.id AS symbol_id,
+                   {ranking.ExactNameOrder} AS exact_name_order,
+                   {PathBucketOrder} AS path_bucket,
+                   {VisibilityOrder} AS visibility_rank,
+                   {columns.StartColumn} AS stable_start_column,
+                   {canonical.PrimaryRank} AS canonical_primary_rank,
+                   {canonical.Generated} AS canonical_generated_rank,
+                   {canonical.SemanticScore} AS canonical_semantic_score,
+                   {canonical.DeclarationIdentity} AS canonical_declaration_identity,
+                   {GetSymbolColumnSql("identifier_start_column")} AS identifier_start_column
+            FROM symbols s
+            JOIN files f ON s.file_id = f.id
+            {ranking.Join}
+            WHERE 1=1";
+    }
+
+    private static string BuildExactSymbolNameOrderSql()
+    {
+        return "CASE " +
+            "WHEN @preferLiteralExactMatch = 1 AND s.name = @rawQuery THEN 0 " +
+            "WHEN @preferLiteralNormalizedSqlMatch = 1 AND f.lang = 'sql' AND sql_segment_count(s.name) = @rawQuerySegmentCount AND sql_normalize_name(s.name) = @rawQueryNormalized THEN 1 " +
+            "WHEN @preferCaseInsensitiveExactMatch = 1 AND s.name = @rawQuery COLLATE NOCASE THEN 2 " +
+            "WHEN @preferCaseInsensitiveNormalizedSqlMatch = 1 AND f.lang = 'sql' AND sql_segment_count(s.name) = @rawQuerySegmentCount AND sql_normalize_name_folded(s.name) = @rawQueryNormalizedFolded THEN 3 " +
+            "WHEN @preferCaseInsensitiveSqlLeafMatch = 1 AND f.lang = 'sql' AND sql_leaf_name_folded(s.name) = @rawQueryLeafFolded THEN 4 " +
+            "ELSE 5 END";
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchMultiQuery.cs b/src/CodeIndex/Database/DbReader.SymbolSearchMultiQuery.cs
new file mode 100644
index 000000000..ff3f69063
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchMultiQuery.cs
@@ -0,0 +1,59 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    // Run one search per name so a common earlier-sorting name cannot starve another
+    // query, then round-robin under the original global limit/offset contract.
+    private List<SymbolResult> ExecuteMultiQuerySymbolSearch(SymbolSearchQueryPlan plan)
+    {
+        var queries = plan.Queries!;
+        var requestedPrefix = checked(plan.Limit + Math.Max(0, plan.Offset));
+        var perName = new List<List<SymbolResult>>(queries.Count);
+        foreach (var query in queries)
+        {
+            perName.Add(SearchSymbols(
+                new[] { query! },
+                requestedPrefix,
+                plan.Kind,
+                plan.Lang,
+                plan.PathPatterns,
+                plan.ExcludePathPatterns,
+                plan.ExcludeTests,
+                plan.Since,
+                plan.Exact,
+                plan.VisibilityFilters,
+                plan.ExcludeVisibilityFilters,
+                plan.SortMode,
+                plan.StartLine,
+                plan.EndLine,
+                plan.GroupPartials));
+        }
+
+        var seen = new HashSet<long?>();
+        var merged = new List<SymbolResult>();
+        var cursors = new int[perName.Count];
+        bool advanced;
+        do
+        {
+            advanced = false;
+            for (var index = 0; index < perName.Count && merged.Count < requestedPrefix; index++)
+            {
+                while (cursors[index] < perName[index].Count)
+                {
+                    var result = perName[index][cursors[index]++];
+                    if (seen.Add(result.SymbolId))
+                    {
+                        merged.Add(result);
+                        advanced = true;
+                        break;
+                    }
+                }
+            }
+        } while (advanced && merged.Count < requestedPrefix);
+
+        return merged
+            .Skip(Math.Max(0, plan.Offset))
+            .Take(plan.Limit)
+            .ToList();
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchPredicates.cs b/src/CodeIndex/Database/DbReader.SymbolSearchPredicates.cs
new file mode 100644
index 000000000..abbd692bc
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchPredicates.cs
@@ -0,0 +1,177 @@
+using CodeIndex.Indexer;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private string BuildQualifiedSymbolMatchSql(string parameterStem, bool useFoldedName, string symbolAlias = "s", string fileAlias = "f")
+    {
+        var containerNameSql = GetSymbolColumnSql("container_name", "''", symbolAlias);
+        var containerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name", containerNameSql, symbolAlias);
+        var nameMatchSql = useFoldedName
+            ? $"{symbolAlias}.name_folded = @{parameterStem}CSharpLeafFolded"
+            : $"{symbolAlias}.name = @{parameterStem}CSharpLeaf COLLATE NOCASE";
+        var qualifiedNameMatchSql = useFoldedName
+            ? $"{symbolAlias}.name_folded = @{parameterStem}CSharpQualifiedFolded"
+            : $"{symbolAlias}.name = @{parameterStem}CSharpQualified COLLATE NOCASE";
+        return $@"({fileAlias}.lang = 'csharp'
+                  AND ({qualifiedNameMatchSql}
+                       OR ({nameMatchSql}
+                           AND ({containerNameSql} = @{parameterStem}Container COLLATE NOCASE
+                                OR {containerQualifiedNameSql} = @{parameterStem}Container COLLATE NOCASE
+                                OR {containerQualifiedNameSql} COLLATE NOCASE LIKE @{parameterStem}ContainerSuffixLike ESCAPE '\'))))";
+    }
+
+    private string BuildExactPrimarySymbolNameMatchSql(
+        string parameterSql,
+        bool useFoldedName,
+        string query,
+        string? lang)
+    {
+        var matchSql = useFoldedName
+            ? BuildPersistedFoldedNameMatchSql("s.name_folded", parameterSql)
+            : $"s.name = {parameterSql} COLLATE NOCASE";
+        if (!string.IsNullOrWhiteSpace(lang) || !SqlNameResolver.HasQualifier(query))
+            return matchSql;
+
+        // Preserve direct qualified matching for ordinary and legacy C# rows. Only v3
+        // explicit-interface rows have a display alias; those rows must use the C# identity
+        // clause so `IFoo.this` cannot also match a distinct `IFoo.@this` implementation.
+        // 通常および legacy C# row の修飾直接一致は維持する。表示 alias を持つ v3 の
+        // 明示的 interface row だけを C# identity 条件へ限定し、`IFoo.this` が別の
+        // `IFoo.@this` 実装にも一致しないようにする。
+        var displayNameFoldedSql = GetSymbolColumnSql("display_name_folded", "NULL");
+        return $"((f.lang <> 'csharp' OR {displayNameFoldedSql} IS NULL) AND {matchSql})";
+    }
+
+    private string BuildCSharpExplicitInterfaceIdentityMatchSql(
+        string parameterStem,
+        string symbolAlias = "s",
+        string fileAlias = "f")
+    {
+        if (!_csharpSymbolNameContractCurrent
+            || !_foldMetadataCurrent
+            || !_symbolColumns.Contains("name_folded"))
+            return "0";
+
+        return $"({fileAlias}.lang = 'csharp' AND {symbolAlias}.name_folded = @{parameterStem}CSharpExplicitInterfaceIdentityFolded)";
+    }
+
+    private string BuildCSharpExplicitInterfaceShortAliasMatchSql(
+        string parameterStem,
+        string symbolAlias = "s",
+        string fileAlias = "f")
+        => _foldReady
+            && _csharpSymbolNameContractCurrent
+            && _symbolColumns.Contains("display_name_folded")
+            && HasSymbolIndex("idx_symbols_display_name_folded")
+            ? $"({fileAlias}.lang = 'csharp' AND {symbolAlias}.display_name_folded = @{parameterStem}LeafFolded)"
+            : $"({fileAlias}.lang = 'csharp' AND {symbolAlias}.name = @{parameterStem}Leaf COLLATE NOCASE)";
+
+    private static void AddCSharpExplicitInterfaceIdentityQueryParameter(
+        SqliteCommand cmd,
+        string parameterStem,
+        string query)
+    {
+        SqliteCommandPolicy.Add(
+            cmd,
+            $"@{parameterStem}CSharpExplicitInterfaceIdentityFolded",
+            CSharpSymbolNameNormalizer.NormalizeExplicitInterfaceQueryIdentityNameFolded(query));
+    }
+
+    private static string GetQualifiedQueryContainer(string query)
+    {
+        var normalized = SqlNameResolver.NormalizeQualifiedName(query);
+        var lastDot = normalized.LastIndexOf('.');
+        return lastDot > 0 ? normalized[..lastDot] : string.Empty;
+    }
+
+    private static string GetQualifiedQuerySuffix(string query)
+    {
+        var normalized = SqlNameResolver.NormalizeQualifiedName(query);
+        var lastDot = normalized.LastIndexOf('.');
+        if (lastDot <= 0)
+            return normalized;
+        var previousDot = normalized.LastIndexOf('.', lastDot - 1);
+        return previousDot >= 0 ? normalized[(previousDot + 1)..] : normalized;
+    }
+
+    private static string GetQualifiedQueryLeaf(string query, string? lang)
+    {
+        var leaf = SqlNameResolver.GetLeafName(query);
+        return NormalizeCSharpVerbatimQuery(leaf, lang) ?? leaf;
+    }
+
+    private static void AddQualifiedSymbolQueryParameters(SqliteCommand cmd, string parameterStem, string query)
+    {
+        var csharpDisplayQuery =
+            CSharpSymbolNameNormalizer.NormalizeExplicitInterfaceQueryDisplayName(query);
+        var csharpQualifiedQuery =
+            NormalizeCSharpVerbatimQuery(csharpDisplayQuery, "csharp")
+            ?? csharpDisplayQuery;
+        var container = GetQualifiedQueryContainer(csharpQualifiedQuery);
+        var csharpLeaf = GetQualifiedQueryLeaf(csharpQualifiedQuery, "csharp");
+        SqliteCommandPolicy.Add(cmd, $"@{parameterStem}Container", container);
+        SqliteCommandPolicy.Add(cmd, $"@{parameterStem}ContainerSuffixLike", $"%.{EscapeLikeQuery(container)}");
+        SqliteCommandPolicy.Add(cmd, $"@{parameterStem}CSharpQualified", csharpQualifiedQuery);
+        SqliteCommandPolicy.Add(
+            cmd,
+            $"@{parameterStem}CSharpQualifiedFolded",
+            NameFold.Fold(csharpQualifiedQuery) ?? csharpQualifiedQuery);
+        SqliteCommandPolicy.Add(cmd, $"@{parameterStem}CSharpLeaf", csharpLeaf);
+        SqliteCommandPolicy.Add(
+            cmd,
+            $"@{parameterStem}CSharpLeafFolded",
+            NameFold.Fold(csharpLeaf) ?? csharpLeaf);
+    }
+
+    private bool HasSingleQualifiedSymbolDefinition(string query, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests)
+    {
+        if (!SqlNameResolver.HasQualifier(query))
+            return false;
+
+        var matches = SearchSymbols(query, 2, kind: null, lang, pathPatterns: null, excludePathPatterns: null, excludeTests, since: null, exact: false);
+        if (matches.Count != 1)
+            return false;
+
+        var leafMatches = SearchSymbols(SqlNameResolver.GetLeafName(query), 2, kind: null, lang, pathPatterns: null, excludePathPatterns: null, excludeTests, since: null, exact: true);
+        return leafMatches.Count == 1;
+    }
+
+    private bool HasQualifiedSymbolDefinition(string query, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests)
+    {
+        if (!SqlNameResolver.HasQualifier(query))
+            return false;
+
+        return SearchSymbols(query, 1, kind: null, lang, pathPatterns: null, excludePathPatterns: null, excludeTests, since: null, exact: false).Count > 0;
+    }
+
+    private static string BuildQualifiedContextMatchSql(string contextSql, string columnSql, bool folded, bool like)
+    {
+        var functionName = (folded, like) switch
+        {
+            (true, true) => "sql_context_like_name_folded_at",
+            (true, false) => "sql_context_has_name_folded_at",
+            (false, true) => "sql_context_like_name_at",
+            _ => "sql_context_has_name_at",
+        };
+        return $"({functionName}({contextSql}, @aliasQuery, {columnSql}) = 1 OR {functionName}({contextSql}, @aliasQuerySuffix, {columnSql}) = 1)";
+    }
+
+    private static string BuildQualifiedLeafFallbackSql(string nameSql, string foldedNameSql, bool folded)
+        => folded
+            ? $"(@allowQualifiedLeafFallback = 1 AND f.lang = 'csharp' AND {foldedNameSql} = @aliasQueryLeafFolded)"
+            : $"(@allowQualifiedLeafFallback = 1 AND f.lang = 'csharp' AND {nameSql} = @aliasQueryLeaf COLLATE NOCASE)";
+
+    private static string BuildCSharpQualifiedContextFallbackSql(string qualifiedContextSql)
+        => $"(@allowCSharpQualifiedContextMatch = 1 AND f.lang = 'csharp' AND {qualifiedContextSql})";
+
+    private static void AddQualifiedGraphQueryParameters(SqliteCommand cmd, string query, bool allowLeafFallback, bool allowCSharpContextMatch = false)
+    {
+        SqliteCommandPolicy.Add(cmd, "@aliasQuerySuffix", GetQualifiedQuerySuffix(query));
+        SqliteCommandPolicy.Add(cmd, "@aliasQueryLeaf", SqlNameResolver.GetLeafName(query));
+        SqliteCommandPolicy.Add(cmd, "@allowQualifiedLeafFallback", allowLeafFallback ? 1 : 0);
+        SqliteCommandPolicy.Add(cmd, "@allowCSharpQualifiedContextMatch", allowCSharpContextMatch ? 1 : 0);
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchProjection.cs b/src/CodeIndex/Database/DbReader.SymbolSearchProjection.cs
new file mode 100644
index 000000000..0328f8dcb
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchProjection.cs
@@ -0,0 +1,158 @@
+using System.Text.Json;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private static class SymbolSearchRowProjector
+    {
+        private const int DefinitionSitesIndex = 22;
+        private const int UngroupedIdentifierStartColumnIndex = 36;
+        private const int GroupedIdentifierStartColumnIndex = 31;
+
+        public static List<SymbolResult> ReadAll(
+            SqliteDataReader reader,
+            SymbolSearchQueryPlan plan)
+        {
+            var results = new List<SymbolResult>();
+            var includeRankingMetadata = plan.SortMode != SymbolSortMode.Name;
+            var sortModeName = includeRankingMetadata
+                ? plan.SortMode.ToString().ToLowerInvariant()
+                : null;
+            while (reader.TrackedRead())
+                results.Add(Read(reader, plan, includeRankingMetadata, sortModeName));
+            return results;
+        }
+
+        private static SymbolResult Read(
+            SqliteDataReader reader,
+            SymbolSearchQueryPlan plan,
+            bool includeRankingMetadata,
+            string? sortModeName)
+        {
+            var definitionSites = Convert.ToInt32(reader.GetInt64(DefinitionSitesIndex));
+            var identifierColumn = plan.GroupPartials
+                ? GroupedIdentifierStartColumnIndex
+                : UngroupedIdentifierStartColumnIndex;
+            var result = new SymbolResult
+            {
+                Path = reader.GetString(0),
+                Lang = GetNullableString(reader, 1),
+                Kind = reader.GetString(2),
+                SubKind = GetNullableString(reader, 3),
+                Name = reader.GetString(4),
+                Line = reader.GetInt32(5),
+                StartLine = GetInt32OrFallback(reader, 6, 5),
+                StartColumn = GetNullableInt32(reader, identifierColumn)
+                    ?? ResolveSymbolIdentifierStartColumn(
+                        GetNullableInt32(reader, 7),
+                        GetNullableString(reader, 11),
+                        reader.GetString(4),
+                        reader.GetString(2)),
+                EndLine = GetInt32OrFallback(reader, 8, 5),
+                BodyStartLine = GetNullableInt32(reader, 9),
+                BodyEndLine = GetNullableInt32(reader, 10),
+                Signature = GetNullableString(reader, 11),
+                ContainerKind = GetNullableString(reader, 12),
+                ContainerName = GetNullableString(reader, 13),
+                ContainerQualifiedName = GetNullableString(reader, 25),
+                LogicalPartialKey = GetNullableString(reader, 26),
+                Visibility = GetNullableString(reader, 14),
+                ReturnType = GetNullableString(reader, 15),
+                SortMode = sortModeName,
+                ReferenceCount = includeRankingMetadata ? Convert.ToInt32(reader.GetInt64(16)) : null,
+                HotspotScore = includeRankingMetadata ? Math.Round(reader.GetDouble(17), 3) : null,
+                RankingReferenceScore = includeRankingMetadata ? Math.Round(reader.GetDouble(18), 3) : null,
+                RankingHotspotScore = includeRankingMetadata ? Math.Round(reader.GetDouble(19), 3) : null,
+                GenericNamePenalty = includeRankingMetadata ? Math.Round(reader.GetDouble(20), 3) : null,
+                StructuralRankPenalty = includeRankingMetadata ? Math.Round(reader.GetDouble(21), 3) : null,
+                DefinitionSites = includeRankingMetadata || (plan.GroupPartials && definitionSites > 1) ? definitionSites : null,
+                SizeLines = includeRankingMetadata ? Convert.ToInt32(reader.GetInt64(23)) : null,
+                ComplexityScore = includeRankingMetadata ? Math.Round(reader.GetDouble(24), 3) : null,
+                SymbolId = reader.GetInt64(27),
+            };
+            AddPartialFamily(reader, plan, definitionSites, result);
+            return result;
+        }
+
+        private static void AddPartialFamily(
+            SqliteDataReader reader,
+            SymbolSearchQueryPlan plan,
+            int definitionSites,
+            SymbolResult result)
+        {
+            if (!plan.GroupPartials || definitionSites <= 1)
+                return;
+
+            result.PartialFamilyId =
+                LogicalPartialSymbolGrouper.BuildPartialFamilyId(result.LogicalPartialKey!);
+            result.RepresentativeReason = reader.GetString(28);
+            result.FamilyMembers = ReadPartialFamilyMembers(reader.GetString(29), result);
+            result.FamilyMembersTruncated = reader.GetInt64(30) != 0;
+        }
+    }
+
+    private static List<PartialFamilyMember> ReadPartialFamilyMembers(string json, SymbolResult representative)
+    {
+        using var document = JsonDocument.Parse(json);
+        var members = new List<PartialFamilyMember>();
+        foreach (var element in document.RootElement.EnumerateArray())
+        {
+            var symbolId = element.GetProperty("symbol_id").GetInt64();
+            var path = element.GetProperty("path").GetString() ?? string.Empty;
+            var startLine = element.GetProperty("start_line").GetInt32();
+            var rawStartColumn = element.GetProperty("start_column").ValueKind == JsonValueKind.Null
+                ? (int?)null
+                : element.GetProperty("start_column").GetInt32();
+            var memberName = element.GetProperty("name").GetString() ?? representative.Name;
+            var memberSignature = element.GetProperty("signature").ValueKind == JsonValueKind.Null
+                ? null
+                : element.GetProperty("signature").GetString();
+            var identifierStartColumn = element.TryGetProperty("identifier_start_column", out var identifierColumnElement)
+                && identifierColumnElement.ValueKind != JsonValueKind.Null
+                    ? identifierColumnElement.GetInt32()
+                    : (int?)null;
+            members.Add(new PartialFamilyMember
+            {
+                SymbolId = symbolId,
+                Path = path,
+                Line = element.GetProperty("line").GetInt32(),
+                StartLine = startLine,
+                StartColumn = identifierStartColumn
+                    ?? ResolveSymbolIdentifierStartColumn(
+                        rawStartColumn,
+                        memberSignature,
+                        memberName,
+                        representative.Kind),
+                EndLine = element.GetProperty("end_line").GetInt32(),
+                Generated = element.GetProperty("generated").GetInt32() != 0,
+                Representative = representative.SymbolId == symbolId
+                    || (representative.SymbolId == null
+                        && string.Equals(representative.Path, path, StringComparison.Ordinal)
+                        && representative.StartLine == startLine),
+            });
+        }
+        return members;
+    }
+
+    private static int? ResolveSymbolIdentifierStartColumn(
+        int? declarationStartColumn,
+        string? signature,
+        string name,
+        string kind)
+    {
+        if (!declarationStartColumn.HasValue || string.IsNullOrWhiteSpace(signature) || string.IsNullOrEmpty(name))
+            return declarationStartColumn;
+
+        var firstLineEnd = signature.IndexOfAny(['\r', '\n']);
+        var firstLine = firstLineEnd >= 0 ? signature[..firstLineEnd] : signature;
+        var callable = kind is "function" or "test.method";
+        var relativeColumn = callable
+            ? LogicalPartialSymbolGrouper.FindCallableNameOffset(firstLine, name)
+            : firstLine.IndexOf(name, StringComparison.Ordinal);
+        if (relativeColumn < 0 && callable)
+            relativeColumn = firstLine.IndexOf(name, StringComparison.Ordinal);
+        return relativeColumn >= 0 ? declarationStartColumn.Value + relativeColumn : declarationStartColumn;
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchQueryBinding.cs b/src/CodeIndex/Database/DbReader.SymbolSearchQueryBinding.cs
new file mode 100644
index 000000000..1506fc92a
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchQueryBinding.cs
@@ -0,0 +1,338 @@
+using CodeIndex.Indexer;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private static class SymbolSearchQueryPredicateBuilder
+    {
+        public static string BuildFull(DbReader reader, SymbolSearchQueryPlan plan)
+        {
+            if (plan.Queries is not { Count: > 0 } queries)
+                return string.Empty;
+
+            var clauses = plan.Exact
+                ? queries.Select((query, index) => BuildFullExact(reader, plan, query, index))
+                : queries.Select((query, index) => BuildFullLike(reader, query, index));
+            return $" AND ({string.Join(" OR ", clauses)})";
+        }
+
+        public static string BuildBounded(DbReader reader, SymbolSearchQueryPlan plan)
+        {
+            if (plan.Queries is not { Count: 1 } queries)
+                return string.Empty;
+
+            var query = queries[0];
+            var allowLeafFallback = !SqlNameResolver.HasQualifier(query);
+            var qualifiedSymbolClause = SqlNameResolver.HasQualifier(query)
+                ? reader.BuildQualifiedSymbolMatchSql("query0", reader._foldReady)
+                : null;
+            var csharpExplicitInterfaceClause = allowLeafFallback
+                ? reader.BuildCSharpExplicitInterfaceShortAliasMatchSql("query0")
+                : reader.BuildCSharpExplicitInterfaceIdentityMatchSql("query0");
+            var rustQualifiedExact = ShouldPreserveRustQualifiedExactQuery(query, plan.Lang, plan.Exact);
+            var rustQualifiedParts = rustQualifiedExact
+                ? NormalizeRustQualifiedExactQueryParts(query)
+                : default;
+            if (!plan.Exact)
+            {
+                return $" AND (s.name LIKE @query0 ESCAPE '\\' OR (f.lang = 'sql' AND sql_normalize_name(s.name) LIKE @query0NormalizedLike ESCAPE '\\'){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause} OR {csharpExplicitInterfaceClause}" : string.Empty)})";
+            }
+
+            if (rustQualifiedParts.QualifiedPath != null)
+            {
+                return reader._foldReady
+                    ? " AND ((s.container_qualified_name = @query0RustContainer COLLATE NOCASE OR s.container_name = @query0RustContainer COLLATE NOCASE) AND s.name_folded = @query0RustLeafFolded)"
+                    : " AND ((s.container_qualified_name = @query0RustContainer COLLATE NOCASE OR s.container_name = @query0RustContainer COLLATE NOCASE) AND s.name = @query0RustLeaf COLLATE NOCASE)";
+            }
+
+            return " AND " + BuildExactCore(
+                reader,
+                query,
+                plan.Lang,
+                "query0",
+                allowLeafFallback,
+                qualifiedSymbolClause,
+                csharpExplicitInterfaceClause,
+                markdownAnchorClause: null,
+                swiftBacktickClause: string.Empty);
+        }
+
+        public static void AppendFilters(
+            DbReader reader,
+            ref string sql,
+            SymbolSearchQueryPlan plan,
+            bool includeLineRange)
+        {
+            if (plan.Kind != null)
+                sql += " AND s.kind = @kind";
+            if (plan.Lang != null)
+                sql += SymbolLanguageFileIdFilter;
+            if (plan.Since != null && reader._fileColumns.Contains("modified"))
+                sql += " AND f.modified >= @since";
+            if (includeLineRange && plan.StartLine != null)
+                sql += " AND s.line >= @startLine";
+            if (includeLineRange && plan.EndLine != null)
+                sql += " AND s.line <= @endLine";
+            AppendPathFilters(
+                ref sql,
+                plan.PathPatterns,
+                plan.ExcludePathPatterns,
+                plan.ExcludeTests);
+            reader.AppendVisibilityFilters(
+                ref sql,
+                plan.VisibilityFilters,
+                plan.ExcludeVisibilityFilters);
+        }
+
+        private static string BuildFullExact(
+            DbReader reader,
+            SymbolSearchQueryPlan plan,
+            string query,
+            int index)
+        {
+            var parameterStem = $"query{index}";
+            var rustQualifiedExact =
+                ShouldPreserveRustQualifiedExactQuery(query, plan.Lang, plan.Exact);
+            var rustQualifiedParts = rustQualifiedExact
+                ? NormalizeRustQualifiedExactQueryParts(query)
+                : default;
+            if (rustQualifiedParts.QualifiedPath != null)
+            {
+                return reader._foldReady
+                    ? $"((s.container_qualified_name = @{parameterStem}RustContainer COLLATE NOCASE OR s.container_name = @{parameterStem}RustContainer COLLATE NOCASE) AND s.name_folded = @{parameterStem}RustLeafFolded)"
+                    : $"((s.container_qualified_name = @{parameterStem}RustContainer COLLATE NOCASE OR s.container_name = @{parameterStem}RustContainer COLLATE NOCASE) AND s.name = @{parameterStem}RustLeaf COLLATE NOCASE)";
+            }
+
+            var allowLeafFallback = !SqlNameResolver.HasQualifier(query);
+            var markdownAnchorClause = reader._symbolColumns.Contains("name_folded")
+                ? $"(f.lang = 'markdown' AND ((s.kind = 'heading' AND s.name_folded = @{parameterStem}MarkdownHeading) OR (s.kind = 'anchor' AND s.name_folded = @{parameterStem}MarkdownExplicitAnchor COLLATE BINARY)))"
+                : "0";
+            var qualifiedSymbolClause = SqlNameResolver.HasQualifier(query)
+                ? reader.BuildQualifiedSymbolMatchSql(parameterStem, reader._foldReady)
+                : null;
+            var csharpExplicitInterfaceClause = allowLeafFallback
+                ? reader.BuildCSharpExplicitInterfaceShortAliasMatchSql(parameterStem)
+                : reader.BuildCSharpExplicitInterfaceIdentityMatchSql(parameterStem);
+            var swiftBacktickAlias = ComputeSwiftBacktickAlias(query, plan.Lang);
+            var swiftBacktickClause = swiftBacktickAlias != null
+                ? reader._foldReady
+                    ? $" OR s.name_folded = @{parameterStem}SwiftBacktickAlias"
+                    : $" OR s.name = @{parameterStem}SwiftBacktickAlias COLLATE NOCASE"
+                : string.Empty;
+            return BuildExactCore(
+                reader,
+                query,
+                plan.Lang,
+                parameterStem,
+                allowLeafFallback,
+                qualifiedSymbolClause,
+                csharpExplicitInterfaceClause,
+                markdownAnchorClause,
+                swiftBacktickClause);
+        }
+
+        private static string BuildExactCore(
+            DbReader reader,
+            string query,
+            string? lang,
+            string parameterStem,
+            bool allowLeafFallback,
+            string? qualifiedSymbolClause,
+            string csharpExplicitInterfaceClause,
+            string? markdownAnchorClause,
+            string swiftBacktickClause)
+        {
+            var parameterSql = $"@{parameterStem}";
+            var aliasClauses = $"{swiftBacktickClause} OR {csharpExplicitInterfaceClause}";
+            if (markdownAnchorClause != null)
+                aliasClauses += $" OR {markdownAnchorClause}";
+            if (reader._foldReady)
+            {
+                return allowLeafFallback
+                    ? $"({reader.BuildExactPrimarySymbolNameMatchSql(parameterSql, true, query, lang)}{aliasClauses} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @{parameterStem}SegmentCount AND sql_normalize_name_folded(s.name) = @{parameterStem}NormalizedFolded) OR sql_leaf_name_folded(s.name) = @{parameterStem}LeafFolded)))"
+                    : $"({reader.BuildExactPrimarySymbolNameMatchSql(parameterSql, true, query, lang)}{aliasClauses} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @{parameterStem}SegmentCount AND sql_normalize_name_folded(s.name) = @{parameterStem}NormalizedFolded){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause}" : string.Empty)})";
+            }
+
+            return allowLeafFallback
+                ? $"({reader.BuildExactPrimarySymbolNameMatchSql(parameterSql, false, query, lang)}{aliasClauses} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @{parameterStem}SegmentCount AND sql_normalize_name(s.name) = @{parameterStem}Normalized COLLATE NOCASE) OR sql_leaf_name(s.name) = @{parameterStem}Leaf COLLATE NOCASE)))"
+                : $"({reader.BuildExactPrimarySymbolNameMatchSql(parameterSql, false, query, lang)}{aliasClauses} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @{parameterStem}SegmentCount AND sql_normalize_name(s.name) = @{parameterStem}Normalized COLLATE NOCASE){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause}" : string.Empty)})";
+        }
+
+        private static string BuildFullLike(DbReader reader, string query, int index)
+        {
+            var parameterStem = $"query{index}";
+            var qualifiedSymbolClause = SqlNameResolver.HasQualifier(query)
+                ? reader.BuildQualifiedSymbolMatchSql(parameterStem, reader._foldReady)
+                : null;
+            var csharpExplicitInterfaceClause = SqlNameResolver.HasQualifier(query)
+                ? reader.BuildCSharpExplicitInterfaceIdentityMatchSql(parameterStem)
+                : null;
+            var markdownAnchorLikeClause = reader._symbolColumns.Contains("name_folded")
+                ? $" OR (f.lang = 'markdown' AND ((s.kind = 'heading' AND s.name_folded LIKE @{parameterStem}MarkdownHeadingLike ESCAPE '\\') OR (s.kind = 'anchor' AND instr(s.name_folded, @{parameterStem}MarkdownExplicitAnchor) > 0)))"
+                : string.Empty;
+            return $"(s.name LIKE @{parameterStem} ESCAPE '\\'{markdownAnchorLikeClause} OR (f.lang = 'sql' AND sql_normalize_name(s.name) LIKE @{parameterStem}NormalizedLike ESCAPE '\\'){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause} OR {csharpExplicitInterfaceClause}" : string.Empty)})";
+        }
+    }
+
+    private static class SymbolSearchQueryBinder
+    {
+        public static void BindFullQueries(
+            DbReader reader,
+            SqliteCommand command,
+            SymbolSearchQueryPlan plan)
+        {
+            if (plan.Queries == null)
+                return;
+
+            for (var index = 0; index < plan.Queries.Count; index++)
+                BindFullQuery(reader, command, plan, plan.Queries[index], index);
+        }
+
+        public static void BindBoundedQuery(
+            DbReader reader,
+            SqliteCommand command,
+            SymbolSearchQueryPlan plan)
+        {
+            if (plan.Queries is not { Count: 1 } queries)
+                return;
+
+            BindBaseQuery(reader, command, plan, queries[0], 0);
+            BindQualifiedAndRust(command, plan, queries[0], 0);
+        }
+
+        public static void BindFilters(
+            DbReader reader,
+            SqliteCommand command,
+            SymbolSearchQueryPlan plan,
+            bool includeLineRange)
+        {
+            if (plan.Kind != null)
+                SqliteCommandPolicy.Add(command, "@kind", plan.Kind);
+            if (plan.Lang != null)
+                SqliteCommandPolicy.Add(command, "@lang", plan.Lang);
+            if (plan.Since != null && reader._fileColumns.Contains("modified"))
+                SqliteCommandPolicy.Add(command, "@since", plan.Since.Value);
+            if (includeLineRange && plan.StartLine != null)
+                SqliteCommandPolicy.Add(command, "@startLine", plan.StartLine.Value);
+            if (includeLineRange && plan.EndLine != null)
+                SqliteCommandPolicy.Add(command, "@endLine", plan.EndLine.Value);
+            AddPathFilterParameters(
+                command,
+                plan.PathPatterns,
+                plan.ExcludePathPatterns);
+            AddVisibilityFilterParameters(
+                command,
+                plan.VisibilityFilters,
+                plan.ExcludeVisibilityFilters);
+        }
+
+        public static void BindListOrdering(SqliteCommand command, SymbolSearchQueryPlan plan)
+        {
+            var hasSingleQuery = plan.Queries is { Count: 1 };
+            var query = hasSingleQuery ? plan.Queries![0] : string.Empty;
+            var preferSqlLeafMatch = hasSingleQuery && !SqlNameResolver.HasQualifier(query);
+            SqliteCommandPolicy.Add(command, "@preferLiteralExactMatch", hasSingleQuery ? 1 : 0);
+            SqliteCommandPolicy.Add(command, "@preferLiteralNormalizedSqlMatch", hasSingleQuery ? 1 : 0);
+            SqliteCommandPolicy.Add(command, "@preferCaseInsensitiveExactMatch", hasSingleQuery ? 1 : 0);
+            SqliteCommandPolicy.Add(command, "@preferCaseInsensitiveNormalizedSqlMatch", hasSingleQuery ? 1 : 0);
+            SqliteCommandPolicy.Add(command, "@preferCaseInsensitiveSqlLeafMatch", preferSqlLeafMatch ? 1 : 0);
+            SqliteCommandPolicy.Add(command, "@rawQuery", query);
+            var normalized = hasSingleQuery ? SqlNameResolver.NormalizeQualifiedName(query) : string.Empty;
+            SqliteCommandPolicy.Add(command, "@rawQueryNormalized", normalized);
+            SqliteCommandPolicy.Add(command, "@rawQueryNormalizedFolded", hasSingleQuery ? NameFold.Fold(normalized) ?? normalized : string.Empty);
+            var leaf = hasSingleQuery ? SqlNameResolver.GetLeafName(query) : string.Empty;
+            SqliteCommandPolicy.Add(command, "@rawQueryLeaf", leaf);
+            SqliteCommandPolicy.Add(command, "@rawQueryLeafFolded", hasSingleQuery ? NameFold.Fold(leaf) ?? leaf : string.Empty);
+            SqliteCommandPolicy.Add(command, "@rawQuerySegmentCount", hasSingleQuery ? SqlNameResolver.GetSegmentCount(query) : 0);
+        }
+
+        private static void BindFullQuery(
+            DbReader reader,
+            SqliteCommand command,
+            SymbolSearchQueryPlan plan,
+            string query,
+            int index)
+        {
+            BindBaseQuery(reader, command, plan, query, index);
+            var parameterStem = $"query{index}";
+            if (reader._symbolColumns.Contains("name_folded"))
+            {
+                var heading = MarkdownAnchorIdentity.NormalizeHeadingFragment(query);
+                SqliteCommandPolicy.Add(command, $"@{parameterStem}MarkdownHeading", heading);
+                SqliteCommandPolicy.Add(command, $"@{parameterStem}MarkdownHeadingLike", $"%{EscapeLikeQuery(heading)}%");
+                SqliteCommandPolicy.Add(
+                    command,
+                    $"@{parameterStem}MarkdownExplicitAnchor",
+                    MarkdownAnchorIdentity.NormalizeExplicitAnchorDefinition(query));
+            }
+
+            BindQualifiedAndRust(command, plan, query, index);
+            var swiftBacktickAlias = ComputeSwiftBacktickAlias(query, plan.Lang);
+            if (swiftBacktickAlias != null)
+            {
+                SqliteCommandPolicy.Add(
+                    command,
+                    $"@{parameterStem}SwiftBacktickAlias",
+                    reader._foldReady
+                        ? NameFold.Fold(swiftBacktickAlias) ?? swiftBacktickAlias
+                        : swiftBacktickAlias);
+            }
+        }
+
+        private static void BindBaseQuery(
+            DbReader reader,
+            SqliteCommand command,
+            SymbolSearchQueryPlan plan,
+            string query,
+            int index)
+        {
+            var parameterStem = $"query{index}";
+            var parameterName = $"@{parameterStem}";
+            var parameterValue = !plan.Exact
+                ? $"%{EscapeLikeQuery(query)}%"
+                : reader._foldReady
+                    ? FoldNameForLanguage(query, plan.Lang)
+                    : query;
+            if (plan.Exact && reader._foldReady)
+                AddPersistedFoldedNameQueryParameters(command, parameterName, query, plan.Lang);
+            else
+                SqliteCommandPolicy.Add(command, parameterName, parameterValue);
+
+            var normalized = SqlNameResolver.NormalizeQualifiedName(query);
+            SqliteCommandPolicy.Add(command, $"@{parameterStem}Normalized", normalized);
+            SqliteCommandPolicy.Add(command, $"@{parameterStem}NormalizedFolded", NameFold.Fold(normalized) ?? normalized);
+            var leaf = GetQualifiedQueryLeaf(query, plan.Lang);
+            SqliteCommandPolicy.Add(command, $"@{parameterStem}Leaf", leaf);
+            SqliteCommandPolicy.Add(command, $"@{parameterStem}LeafFolded", NameFold.Fold(leaf) ?? leaf);
+            SqliteCommandPolicy.Add(command, $"@{parameterStem}SegmentCount", SqlNameResolver.GetSegmentCount(query));
+            SqliteCommandPolicy.Add(command, $"@{parameterStem}NormalizedLike", $"%{EscapeLikeQuery(normalized)}%");
+            AddCSharpExplicitInterfaceIdentityQueryParameter(command, parameterStem, query);
+        }
+
+        private static void BindQualifiedAndRust(
+            SqliteCommand command,
+            SymbolSearchQueryPlan plan,
+            string query,
+            int index)
+        {
+            var parameterStem = $"query{index}";
+            if (SqlNameResolver.HasQualifier(query))
+                AddQualifiedSymbolQueryParameters(command, parameterStem, query);
+
+            var rustQualifiedExact =
+                ShouldPreserveRustQualifiedExactQuery(query, plan.Lang, plan.Exact);
+            var rustQualifiedParts = rustQualifiedExact
+                ? NormalizeRustQualifiedExactQueryParts(query)
+                : default;
+            if (rustQualifiedParts.QualifiedPath != null)
+            {
+                var rustLeaf = rustQualifiedParts.LeafName ?? string.Empty;
+                SqliteCommandPolicy.Add(command, $"@{parameterStem}RustContainer", rustQualifiedParts.ContainerPath ?? string.Empty);
+                SqliteCommandPolicy.Add(command, $"@{parameterStem}RustLeaf", rustLeaf);
+                SqliteCommandPolicy.Add(command, $"@{parameterStem}RustLeafFolded", NameFold.Fold(rustLeaf) ?? rustLeaf);
+            }
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchQueryPlan.cs b/src/CodeIndex/Database/DbReader.SymbolSearchQueryPlan.cs
new file mode 100644
index 000000000..374e9c7ab
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchQueryPlan.cs
@@ -0,0 +1,37 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed record SymbolSearchQueryPlan
+    {
+        public IReadOnlyList<string>? Queries { get; init; }
+        public int Limit { get; init; } = 20;
+        public string? Kind { get; init; }
+        public string? Lang { get; init; }
+        public IReadOnlyList<string>? PathPatterns { get; init; }
+        public IReadOnlyList<string>? ExcludePathPatterns { get; init; }
+        public bool ExcludeTests { get; init; }
+        public DateTime? Since { get; init; }
+        public bool Exact { get; init; }
+        public IReadOnlyList<string>? VisibilityFilters { get; init; }
+        public IReadOnlyList<string>? ExcludeVisibilityFilters { get; init; }
+        public SymbolSortMode SortMode { get; init; } = SymbolSortMode.Name;
+        public int? StartLine { get; init; }
+        public int? EndLine { get; init; }
+        public bool GroupPartials { get; init; }
+        public int Offset { get; init; }
+    }
+
+    private static class SymbolSearchQueryPlanBuilder
+    {
+        public static SymbolSearchQueryPlan Build(SymbolSearchQueryPlan source)
+        {
+            var lang = NormalizeQueryLanguage(source.Lang);
+            return source with
+            {
+                Lang = lang,
+                Queries = NormalizeSymbolSearchQueries(source.Queries, lang, source.Exact),
+            };
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchSql.cs b/src/CodeIndex/Database/DbReader.SymbolSearchSql.cs
new file mode 100644
index 000000000..e1a9f08ee
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchSql.cs
@@ -0,0 +1,174 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private string BuildLogicalPartialKeySql(
+        string signatureSql,
+        string containerNameSql,
+        string containerQualifiedNameSql,
+        string familyKeySql,
+        string returnTypeSql)
+    {
+        return LogicalPartialSymbolGrouper.BuildSqlKeyExpression(
+            "f.lang",
+            "s.kind",
+            "s.name",
+            "s.id",
+            "f.path",
+            signatureSql,
+            containerNameSql,
+            containerQualifiedNameSql,
+            familyKeySql,
+            returnTypeSql,
+            GetSymbolColumnSql("is_partial_declaration"),
+            _hotspotFamilyReadyLanguages.Contains("csharp"));
+    }
+
+    private static string GetGenericSymbolRankNamePenaltySql(string nameSql)
+        => $"CASE WHEN lower({nameSql}) IN {GenericSymbolRankNamesSql} THEN {GenericSymbolRankNamePenaltySqlLiteral} ELSE 1.0 END";
+
+    private static string BuildCanonicalDeclarationIdentitySql(string signatureSql)
+        => $"csharp_partial_declaration_identity({signatureSql})";
+
+    private static string BuildLogicalPartialSymbolQuery(string matchingSymbolsSql, SymbolSortMode sortMode)
+    {
+        var orderBy = BuildLogicalPartialSortOrderBy(sortMode);
+        return $@"
+            WITH matching_symbols AS (
+                {matchingSymbolsSql}
+            ),
+            ranked_symbols AS (
+                SELECT matching_symbols.*,
+                       ROW_NUMBER() OVER (
+                           PARTITION BY logical_partial_key
+                           ORDER BY canonical_primary_rank,
+                                    canonical_generated_rank,
+                                    canonical_semantic_score DESC,
+                                    canonical_declaration_identity COLLATE BINARY,
+                                    logical_partial_key COLLATE BINARY,
+                                    path COLLATE BINARY,
+                                    start_line,
+                                    stable_start_column,
+                                    symbol_id
+                       ) AS logical_row_number,
+                       ROW_NUMBER() OVER (
+                           PARTITION BY logical_partial_key
+                           ORDER BY path COLLATE BINARY, start_line, stable_start_column, symbol_id
+                       ) AS family_member_row_number,
+                       COUNT(*) OVER (PARTITION BY logical_partial_key) AS logical_definition_sites
+                FROM matching_symbols
+            ),
+            family_ranked_symbols AS (
+                SELECT ranked_symbols.*,
+                       MAX(CASE WHEN logical_row_number = 1 THEN family_member_row_number END) OVER (
+                           PARTITION BY logical_partial_key
+                       ) AS representative_member_row_number
+                FROM ranked_symbols
+            ),
+            logical_symbols AS (
+                SELECT family_ranked_symbols.*,
+                       MAX(reference_count) OVER (PARTITION BY logical_partial_key) AS logical_reference_count,
+                       MAX(hotspot_score) OVER (PARTITION BY logical_partial_key) AS logical_hotspot_score,
+                       MAX(ranking_reference_score) OVER (PARTITION BY logical_partial_key) AS logical_ranking_reference_score,
+                       MAX(ranking_hotspot_score) OVER (PARTITION BY logical_partial_key) AS logical_ranking_hotspot_score,
+                       MAX(generic_name_penalty) OVER (PARTITION BY logical_partial_key) AS logical_generic_name_penalty,
+                       MAX(structural_rank_penalty) OVER (PARTITION BY logical_partial_key) AS logical_structural_rank_penalty,
+                       MAX(size_lines) OVER (PARTITION BY logical_partial_key) AS logical_size_lines,
+                       MAX(complexity_score) OVER (PARTITION BY logical_partial_key) AS logical_complexity_score,
+                       MIN(exact_name_order) OVER (PARTITION BY logical_partial_key) AS logical_exact_name_order,
+                       MIN(path_bucket) OVER (PARTITION BY logical_partial_key) AS logical_path_bucket,
+                       MIN(visibility_rank) OVER (PARTITION BY logical_partial_key) AS logical_visibility_rank,
+                       MIN(canonical_primary_rank) OVER (PARTITION BY logical_partial_key) AS logical_primary_rank_min,
+                       MAX(canonical_primary_rank) OVER (PARTITION BY logical_partial_key) AS logical_primary_rank_max,
+                       MIN(canonical_generated_rank) OVER (PARTITION BY logical_partial_key) AS logical_generated_rank_min,
+                       MAX(canonical_generated_rank) OVER (PARTITION BY logical_partial_key) AS logical_generated_rank_max,
+                       MIN(canonical_semantic_score) OVER (PARTITION BY logical_partial_key) AS logical_semantic_score_min,
+                       MAX(canonical_semantic_score) OVER (PARTITION BY logical_partial_key) AS logical_semantic_score_max,
+                       MIN(canonical_declaration_identity) OVER (PARTITION BY logical_partial_key) AS logical_declaration_identity_min,
+                       MAX(canonical_declaration_identity) OVER (PARTITION BY logical_partial_key) AS logical_declaration_identity_max,
+                       json_group_array(json_object(
+                           'symbol_id', symbol_id,
+                           'path', path,
+                           'line', line,
+                           'start_line', start_line,
+                           'start_column', start_column,
+                           'end_line', end_line,
+                           'name', name,
+                           'signature', signature,
+                           'identifier_start_column', identifier_start_column,
+                           'generated', canonical_generated_rank
+                       )) FILTER (WHERE
+                           family_member_row_number <= CASE
+                               WHEN representative_member_row_number <= {LogicalPartialSymbolGrouper.FamilyMemberLimit}
+                               THEN {LogicalPartialSymbolGrouper.FamilyMemberLimit}
+                               ELSE {LogicalPartialSymbolGrouper.FamilyMemberLimit - 1}
+                           END
+                           OR logical_row_number = 1
+                       ) OVER (
+                           PARTITION BY logical_partial_key
+                           ORDER BY path COLLATE BINARY, start_line, stable_start_column, symbol_id
+                           ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+                       ) AS logical_family_members_json
+                FROM family_ranked_symbols
+            )
+            SELECT path, lang, kind, sub_kind, name, line,
+                   start_line, start_column, end_line,
+                   body_start_line, body_end_line, signature,
+                   container_kind, container_name, visibility, return_type,
+                   logical_reference_count, logical_hotspot_score,
+                   logical_ranking_reference_score, logical_ranking_hotspot_score,
+                   logical_generic_name_penalty, logical_structural_rank_penalty,
+                   logical_definition_sites, logical_size_lines, logical_complexity_score,
+                   container_qualified_name, logical_partial_key, symbol_id,
+                   CASE
+                       WHEN logical_primary_rank_min <> logical_primary_rank_max THEN '{LogicalPartialSymbolGrouper.ImplementationBodyReason}'
+                       WHEN logical_generated_rank_min <> logical_generated_rank_max THEN '{LogicalPartialSymbolGrouper.NonGeneratedSourceReason}'
+                       WHEN logical_semantic_score_min <> logical_semantic_score_max THEN '{LogicalPartialSymbolGrouper.SemanticDeclarationReason}'
+                       WHEN logical_declaration_identity_min <> logical_declaration_identity_max THEN '{LogicalPartialSymbolGrouper.CanonicalDeclarationIdentityReason}'
+                       ELSE '{LogicalPartialSymbolGrouper.StableLocationReason}'
+                   END AS representative_reason,
+                   logical_family_members_json,
+                   CASE WHEN logical_definition_sites > {LogicalPartialSymbolGrouper.FamilyMemberLimit} THEN 1 ELSE 0 END AS family_members_truncated,
+                   identifier_start_column
+            FROM logical_symbols
+            WHERE logical_row_number = 1
+            {orderBy}";
+    }
+
+    private static string BuildLogicalPartialSortOrderBy(SymbolSortMode sortMode)
+    {
+        const string stableTieBreakers = "logical_path_bucket, logical_visibility_rank, name, path COLLATE BINARY, line, stable_start_column, symbol_id";
+        return sortMode switch
+        {
+            SymbolSortMode.Hotspot => $"ORDER BY logical_ranking_hotspot_score DESC, logical_ranking_reference_score DESC, logical_hotspot_score DESC, logical_reference_count DESC, logical_size_lines DESC, {stableTieBreakers}",
+            SymbolSortMode.References => $"ORDER BY logical_ranking_reference_score DESC, logical_ranking_hotspot_score DESC, logical_reference_count DESC, logical_hotspot_score DESC, logical_size_lines DESC, {stableTieBreakers}",
+            SymbolSortMode.Size => $"ORDER BY logical_size_lines DESC, logical_ranking_reference_score DESC, logical_ranking_hotspot_score DESC, logical_reference_count DESC, {stableTieBreakers}",
+            SymbolSortMode.Complexity => $"ORDER BY logical_complexity_score DESC, logical_ranking_hotspot_score DESC, logical_ranking_reference_score DESC, logical_reference_count DESC, logical_size_lines DESC, {stableTieBreakers}",
+            SymbolSortMode.Path => "ORDER BY path COLLATE BINARY, line, stable_start_column, name, symbol_id",
+            _ => $"ORDER BY logical_exact_name_order, {stableTieBreakers}",
+        };
+    }
+
+    private string BuildSymbolSortOrderBy(
+        SymbolSortMode sortMode,
+        string exactNameOrderSql,
+        string referenceCountSql,
+        string rawHotspotScoreSql,
+        string rankingReferenceScoreSql,
+        string rankingHotspotScoreSql,
+        string sizeLinesSql,
+        string complexityScoreSql,
+        string startColumnSql)
+    {
+        var stableTieBreakers = $"{PathBucketOrder}, {VisibilityOrder}, s.name, f.path, s.line, {startColumnSql} ASC, s.id ASC";
+        return sortMode switch
+        {
+            SymbolSortMode.Hotspot => $" ORDER BY {rankingHotspotScoreSql} DESC, {rankingReferenceScoreSql} DESC, {rawHotspotScoreSql} DESC, {referenceCountSql} DESC, {sizeLinesSql} DESC, {stableTieBreakers}",
+            SymbolSortMode.References => $" ORDER BY {rankingReferenceScoreSql} DESC, {rankingHotspotScoreSql} DESC, {referenceCountSql} DESC, {rawHotspotScoreSql} DESC, {sizeLinesSql} DESC, {stableTieBreakers}",
+            SymbolSortMode.Size => $" ORDER BY {sizeLinesSql} DESC, {rankingReferenceScoreSql} DESC, {rankingHotspotScoreSql} DESC, {referenceCountSql} DESC, {stableTieBreakers}",
+            SymbolSortMode.Complexity => $" ORDER BY {complexityScoreSql} DESC, {rankingHotspotScoreSql} DESC, {rankingReferenceScoreSql} DESC, {referenceCountSql} DESC, {sizeLinesSql} DESC, {stableTieBreakers}",
+            SymbolSortMode.Path => $" ORDER BY f.path, s.line, {startColumnSql} ASC, s.name, s.id ASC",
+            _ => $" ORDER BY {exactNameOrderSql}, {stableTieBreakers}",
+        };
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchTotalCount.cs b/src/CodeIndex/Database/DbReader.SymbolSearchTotalCount.cs
new file mode 100644
index 000000000..53040064b
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchTotalCount.cs
@@ -0,0 +1,68 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    public QueryCountResult CountSearchSymbolsTotal(string? query = null, string? kind = null, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, DateTime? since = null, bool exact = false, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null, bool groupPartials = false)
+    {
+        return CountSearchSymbolsTotal(query == null ? null : new[] { NormalizeSymbolSearchQueryForSymbolSearch(query, lang, exact) ?? query ?? string.Empty }, kind, lang, pathPatterns, excludePathPatterns, excludeTests, since, exact, visibilityFilters, excludeVisibilityFilters, groupPartials);
+    }
+
+    public QueryCountResult CountSearchSymbolsTotal(IReadOnlyList<string>? queries, string? kind = null, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, DateTime? since = null, bool exact = false, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null, bool groupPartials = false)
+    {
+        var plan = SymbolSearchQueryPlanBuilder.Build(new SymbolSearchQueryPlan
+        {
+            Queries = queries,
+            Kind = kind,
+            Lang = lang,
+            PathPatterns = pathPatterns,
+            ExcludePathPatterns = excludePathPatterns,
+            ExcludeTests = excludeTests,
+            Since = since,
+            Exact = exact,
+            VisibilityFilters = visibilityFilters,
+            ExcludeVisibilityFilters = excludeVisibilityFilters,
+            GroupPartials = groupPartials,
+        });
+        return ExecuteTotalSymbolSearch(plan);
+    }
+
+    private QueryCountResult ExecuteTotalSymbolSearch(SymbolSearchQueryPlan plan)
+    {
+        if (plan.GroupPartials)
+        {
+            EnsureCSharpCallableTypeKinds(
+                plan.Lang,
+                plan.Queries,
+                plan.Exact,
+                plan.Kind);
+        }
+        using var cmd = _conn.CreateCommand();
+
+        var logicalPartialKeySql = BuildLogicalPartialKeySql(
+            GetSymbolColumnSql("signature"),
+            GetSymbolColumnSql("container_name"),
+            GetSymbolColumnSql("container_qualified_name"),
+            GetSymbolColumnSql("family_key"),
+            GetSymbolColumnSql("return_type"));
+        var countSql = plan.GroupPartials
+            ? $"COUNT(DISTINCT ({logicalPartialKeySql}))"
+            : "COUNT(*)";
+        var sql = $@"
+            SELECT {countSql}, COUNT(DISTINCT f.path)
+            FROM symbols s
+            JOIN files f ON s.file_id = f.id
+            WHERE 1=1";
+
+        sql += SymbolSearchQueryPredicateBuilder.BuildFull(this, plan);
+        SymbolSearchQueryPredicateBuilder.AppendFilters(this, ref sql, plan, includeLineRange: false);
+
+        cmd.CommandText = sql;
+        SymbolSearchQueryBinder.BindFullQueries(this, cmd, plan);
+        SymbolSearchQueryBinder.BindFilters(this, cmd, plan, includeLineRange: false);
+
+        using var reader = cmd.ExecuteTrackedReader();
+        return reader.TrackedRead()
+            ? new QueryCountResult(reader.GetInt32(0), reader.GetInt32(1))
+            : new QueryCountResult(0, 0);
+    }
+}
diff --git a/src/CodeIndex/Database/DbSymbolReader.Search.cs b/src/CodeIndex/Database/DbSymbolReader.Search.cs
index c9a710b67..4c2123ed4 100644
--- a/src/CodeIndex/Database/DbSymbolReader.Search.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.Search.cs
@@ -1,8 +1,3 @@
-using System.Globalization;
-using System.Text.Json;
-using CodeIndex.Indexer;
-using Microsoft.Data.Sqlite;
-
 namespace CodeIndex.Database;
 
 public partial class DbReader
@@ -103,1071 +98,6 @@ public bool AnySearchSymbols(IReadOnlyList<string>? queries, string? kind = null
         return false;
     }
 
-    private string BuildQualifiedSymbolMatchSql(string parameterStem, bool useFoldedName, string symbolAlias = "s", string fileAlias = "f")
-    {
-        var containerNameSql = GetSymbolColumnSql("container_name", "''", symbolAlias);
-        var containerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name", containerNameSql, symbolAlias);
-        var nameMatchSql = useFoldedName
-            ? $"{symbolAlias}.name_folded = @{parameterStem}CSharpLeafFolded"
-            : $"{symbolAlias}.name = @{parameterStem}CSharpLeaf COLLATE NOCASE";
-        var qualifiedNameMatchSql = useFoldedName
-            ? $"{symbolAlias}.name_folded = @{parameterStem}CSharpQualifiedFolded"
-            : $"{symbolAlias}.name = @{parameterStem}CSharpQualified COLLATE NOCASE";
-        return $@"({fileAlias}.lang = 'csharp'
-                  AND ({qualifiedNameMatchSql}
-                       OR ({nameMatchSql}
-                           AND ({containerNameSql} = @{parameterStem}Container COLLATE NOCASE
-                                OR {containerQualifiedNameSql} = @{parameterStem}Container COLLATE NOCASE
-                                OR {containerQualifiedNameSql} COLLATE NOCASE LIKE @{parameterStem}ContainerSuffixLike ESCAPE '\'))))";
-    }
-
-    private string BuildExactPrimarySymbolNameMatchSql(
-        string parameterSql,
-        bool useFoldedName,
-        string query,
-        string? lang)
-    {
-        var matchSql = useFoldedName
-            ? BuildPersistedFoldedNameMatchSql("s.name_folded", parameterSql)
-            : $"s.name = {parameterSql} COLLATE NOCASE";
-        if (!string.IsNullOrWhiteSpace(lang) || !SqlNameResolver.HasQualifier(query))
-            return matchSql;
-
-        // Preserve direct qualified matching for ordinary and legacy C# rows. Only v3
-        // explicit-interface rows have a display alias; those rows must use the C# identity
-        // clause so `IFoo.this` cannot also match a distinct `IFoo.@this` implementation.
-        // 通常および legacy C# row の修飾直接一致は維持する。表示 alias を持つ v3 の
-        // 明示的 interface row だけを C# identity 条件へ限定し、`IFoo.this` が別の
-        // `IFoo.@this` 実装にも一致しないようにする。
-        var displayNameFoldedSql = GetSymbolColumnSql("display_name_folded", "NULL");
-        return $"((f.lang <> 'csharp' OR {displayNameFoldedSql} IS NULL) AND {matchSql})";
-    }
-
-    private string BuildCSharpExplicitInterfaceIdentityMatchSql(
-        string parameterStem,
-        string symbolAlias = "s",
-        string fileAlias = "f")
-    {
-        if (!_csharpSymbolNameContractCurrent
-            || !_foldMetadataCurrent
-            || !_symbolColumns.Contains("name_folded"))
-            return "0";
-
-        return $"({fileAlias}.lang = 'csharp' AND {symbolAlias}.name_folded = @{parameterStem}CSharpExplicitInterfaceIdentityFolded)";
-    }
-
-    private string BuildCSharpExplicitInterfaceShortAliasMatchSql(
-        string parameterStem,
-        string symbolAlias = "s",
-        string fileAlias = "f")
-        => _foldReady
-            && _csharpSymbolNameContractCurrent
-            && _symbolColumns.Contains("display_name_folded")
-            && HasSymbolIndex("idx_symbols_display_name_folded")
-            ? $"({fileAlias}.lang = 'csharp' AND {symbolAlias}.display_name_folded = @{parameterStem}LeafFolded)"
-            : $"({fileAlias}.lang = 'csharp' AND {symbolAlias}.name = @{parameterStem}Leaf COLLATE NOCASE)";
-
-    private static void AddCSharpExplicitInterfaceIdentityQueryParameter(
-        SqliteCommand cmd,
-        string parameterStem,
-        string query)
-    {
-        SqliteCommandPolicy.Add(
-            cmd,
-            $"@{parameterStem}CSharpExplicitInterfaceIdentityFolded",
-            CSharpSymbolNameNormalizer.NormalizeExplicitInterfaceQueryIdentityNameFolded(query));
-    }
-
-    private static string GetQualifiedQueryContainer(string query)
-    {
-        var normalized = SqlNameResolver.NormalizeQualifiedName(query);
-        var lastDot = normalized.LastIndexOf('.');
-        return lastDot > 0 ? normalized[..lastDot] : string.Empty;
-    }
-
-    private static string GetQualifiedQuerySuffix(string query)
-    {
-        var normalized = SqlNameResolver.NormalizeQualifiedName(query);
-        var lastDot = normalized.LastIndexOf('.');
-        if (lastDot <= 0)
-            return normalized;
-        var previousDot = normalized.LastIndexOf('.', lastDot - 1);
-        return previousDot >= 0 ? normalized[(previousDot + 1)..] : normalized;
-    }
-
-    private static string GetQualifiedQueryLeaf(string query, string? lang)
-    {
-        var leaf = SqlNameResolver.GetLeafName(query);
-        return NormalizeCSharpVerbatimQuery(leaf, lang) ?? leaf;
-    }
-
-    private static void AddQualifiedSymbolQueryParameters(SqliteCommand cmd, string parameterStem, string query)
-    {
-        var csharpDisplayQuery =
-            CSharpSymbolNameNormalizer.NormalizeExplicitInterfaceQueryDisplayName(query);
-        var csharpQualifiedQuery =
-            NormalizeCSharpVerbatimQuery(csharpDisplayQuery, "csharp")
-            ?? csharpDisplayQuery;
-        var container = GetQualifiedQueryContainer(csharpQualifiedQuery);
-        var csharpLeaf = GetQualifiedQueryLeaf(csharpQualifiedQuery, "csharp");
-        SqliteCommandPolicy.Add(cmd, $"@{parameterStem}Container", container);
-        SqliteCommandPolicy.Add(cmd, $"@{parameterStem}ContainerSuffixLike", $"%.{EscapeLikeQuery(container)}");
-        SqliteCommandPolicy.Add(cmd, $"@{parameterStem}CSharpQualified", csharpQualifiedQuery);
-        SqliteCommandPolicy.Add(
-            cmd,
-            $"@{parameterStem}CSharpQualifiedFolded",
-            NameFold.Fold(csharpQualifiedQuery) ?? csharpQualifiedQuery);
-        SqliteCommandPolicy.Add(cmd, $"@{parameterStem}CSharpLeaf", csharpLeaf);
-        SqliteCommandPolicy.Add(
-            cmd,
-            $"@{parameterStem}CSharpLeafFolded",
-            NameFold.Fold(csharpLeaf) ?? csharpLeaf);
-    }
-
-    private bool HasSingleQualifiedSymbolDefinition(string query, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests)
-    {
-        if (!SqlNameResolver.HasQualifier(query))
-            return false;
-
-        var matches = SearchSymbols(query, 2, kind: null, lang, pathPatterns: null, excludePathPatterns: null, excludeTests, since: null, exact: false);
-        if (matches.Count != 1)
-            return false;
-
-        var leafMatches = SearchSymbols(SqlNameResolver.GetLeafName(query), 2, kind: null, lang, pathPatterns: null, excludePathPatterns: null, excludeTests, since: null, exact: true);
-        return leafMatches.Count == 1;
-    }
-
-    private bool HasQualifiedSymbolDefinition(string query, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests)
-    {
-        if (!SqlNameResolver.HasQualifier(query))
-            return false;
-
-        return SearchSymbols(query, 1, kind: null, lang, pathPatterns: null, excludePathPatterns: null, excludeTests, since: null, exact: false).Count > 0;
-    }
-
-    private static string BuildQualifiedContextMatchSql(string contextSql, string columnSql, bool folded, bool like)
-    {
-        var functionName = (folded, like) switch
-        {
-            (true, true) => "sql_context_like_name_folded_at",
-            (true, false) => "sql_context_has_name_folded_at",
-            (false, true) => "sql_context_like_name_at",
-            _ => "sql_context_has_name_at",
-        };
-        return $"({functionName}({contextSql}, @aliasQuery, {columnSql}) = 1 OR {functionName}({contextSql}, @aliasQuerySuffix, {columnSql}) = 1)";
-    }
-
-    private static string BuildQualifiedLeafFallbackSql(string nameSql, string foldedNameSql, bool folded)
-        => folded
-            ? $"(@allowQualifiedLeafFallback = 1 AND f.lang = 'csharp' AND {foldedNameSql} = @aliasQueryLeafFolded)"
-            : $"(@allowQualifiedLeafFallback = 1 AND f.lang = 'csharp' AND {nameSql} = @aliasQueryLeaf COLLATE NOCASE)";
-
-    private static string BuildCSharpQualifiedContextFallbackSql(string qualifiedContextSql)
-        => $"(@allowCSharpQualifiedContextMatch = 1 AND f.lang = 'csharp' AND {qualifiedContextSql})";
-
-    private static void AddQualifiedGraphQueryParameters(SqliteCommand cmd, string query, bool allowLeafFallback, bool allowCSharpContextMatch = false)
-    {
-        SqliteCommandPolicy.Add(cmd, "@aliasQuerySuffix", GetQualifiedQuerySuffix(query));
-        SqliteCommandPolicy.Add(cmd, "@aliasQueryLeaf", SqlNameResolver.GetLeafName(query));
-        SqliteCommandPolicy.Add(cmd, "@allowQualifiedLeafFallback", allowLeafFallback ? 1 : 0);
-        SqliteCommandPolicy.Add(cmd, "@allowCSharpQualifiedContextMatch", allowCSharpContextMatch ? 1 : 0);
-    }
-
-    public int CountSearchSymbols(IReadOnlyList<string>? queries, int limit = 20, string? kind = null, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, DateTime? since = null, bool exact = false, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null)
-    {
-        lang = DbReader.NormalizeQueryLanguage(lang);
-        var validQueries = NormalizeSymbolSearchQueries(queries, lang, exact);
-        if (validQueries != null
-            && (validQueries.Count > 1 || string.Equals(lang, "markdown", StringComparison.Ordinal)))
-            return SearchSymbols(validQueries, limit, kind, lang, pathPatterns, excludePathPatterns, excludeTests, since, exact, visibilityFilters, excludeVisibilityFilters).Count;
-
-        using var cmd = _conn.CreateCommand();
-
-        var innerSql = @"
-            SELECT 1
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE 1=1";
-
-        if (validQueries != null && validQueries.Count == 1)
-        {
-            var allowLeafFallback = !SqlNameResolver.HasQualifier(validQueries[0]);
-            var qualifiedSymbolClause = SqlNameResolver.HasQualifier(validQueries[0])
-                ? BuildQualifiedSymbolMatchSql("query0", _foldReady)
-                : null;
-            var csharpExplicitInterfaceClause = allowLeafFallback
-                ? BuildCSharpExplicitInterfaceShortAliasMatchSql("query0")
-                : BuildCSharpExplicitInterfaceIdentityMatchSql("query0");
-            var rustQualifiedExact = ShouldPreserveRustQualifiedExactQuery(validQueries[0], lang, exact);
-            var rustQualifiedParts = rustQualifiedExact ? NormalizeRustQualifiedExactQueryParts(validQueries[0]) : default;
-            innerSql += exact
-                ? rustQualifiedParts.QualifiedPath != null
-                    ? _foldReady
-                        ? " AND ((s.container_qualified_name = @query0RustContainer COLLATE NOCASE OR s.container_name = @query0RustContainer COLLATE NOCASE) AND s.name_folded = @query0RustLeafFolded)"
-                        : " AND ((s.container_qualified_name = @query0RustContainer COLLATE NOCASE OR s.container_name = @query0RustContainer COLLATE NOCASE) AND s.name = @query0RustLeaf COLLATE NOCASE)"
-                    : _foldReady
-                        ? allowLeafFallback
-                            ? $" AND ({BuildExactPrimarySymbolNameMatchSql("@query0", true, validQueries[0], lang)} OR {csharpExplicitInterfaceClause} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @query0SegmentCount AND sql_normalize_name_folded(s.name) = @query0NormalizedFolded) OR sql_leaf_name_folded(s.name) = @query0LeafFolded)))"
-                            : $" AND ({BuildExactPrimarySymbolNameMatchSql("@query0", true, validQueries[0], lang)} OR {csharpExplicitInterfaceClause} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @query0SegmentCount AND sql_normalize_name_folded(s.name) = @query0NormalizedFolded){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause}" : string.Empty)})"
-                        : allowLeafFallback
-                            ? $" AND ({BuildExactPrimarySymbolNameMatchSql("@query0", false, validQueries[0], lang)} OR {csharpExplicitInterfaceClause} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @query0SegmentCount AND sql_normalize_name(s.name) = @query0Normalized COLLATE NOCASE) OR sql_leaf_name(s.name) = @query0Leaf COLLATE NOCASE)))"
-                            : $" AND ({BuildExactPrimarySymbolNameMatchSql("@query0", false, validQueries[0], lang)} OR {csharpExplicitInterfaceClause} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @query0SegmentCount AND sql_normalize_name(s.name) = @query0Normalized COLLATE NOCASE){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause}" : string.Empty)})"
-                : $" AND (s.name LIKE @query0 ESCAPE '\\' OR (f.lang = 'sql' AND sql_normalize_name(s.name) LIKE @query0NormalizedLike ESCAPE '\\'){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause} OR {csharpExplicitInterfaceClause}" : string.Empty)})";
-        }
-        if (kind != null)
-            innerSql += " AND s.kind = @kind";
-        if (lang != null)
-            innerSql += SymbolLanguageFileIdFilter;
-        if (since != null && _fileColumns.Contains("modified"))
-            innerSql += " AND f.modified >= @since";
-        AppendPathFilters(ref innerSql, pathPatterns, excludePathPatterns, excludeTests);
-        AppendVisibilityFilters(ref innerSql, visibilityFilters, excludeVisibilityFilters);
-        innerSql += " LIMIT @limit";
-
-        cmd.CommandText = $"SELECT COUNT(*) FROM ({innerSql})";
-        if (validQueries != null && validQueries.Count == 1)
-        {
-            var value = validQueries[0];
-            var rustQualifiedExact = ShouldPreserveRustQualifiedExactQuery(value, lang, exact);
-            var rustQualifiedParts = rustQualifiedExact ? NormalizeRustQualifiedExactQueryParts(value) : default;
-            var paramValue = !exact
-                ? $"%{EscapeLikeQuery(value)}%"
-                : _foldReady
-                    ? FoldNameForLanguage(value, lang)
-                    : value;
-            if (exact && _foldReady)
-                AddPersistedFoldedNameQueryParameters(cmd, "@query0", value, lang);
-            else
-                SqliteCommandPolicy.Add(cmd, "@query0", paramValue);
-            SqliteCommandPolicy.Add(cmd, "@query0Normalized", SqlNameResolver.NormalizeQualifiedName(value));
-            SqliteCommandPolicy.Add(cmd, "@query0NormalizedFolded", NameFold.Fold(SqlNameResolver.NormalizeQualifiedName(value)) ?? SqlNameResolver.NormalizeQualifiedName(value));
-            var queryLeaf = GetQualifiedQueryLeaf(value, lang);
-            SqliteCommandPolicy.Add(cmd, "@query0Leaf", queryLeaf);
-            SqliteCommandPolicy.Add(cmd, "@query0LeafFolded", NameFold.Fold(queryLeaf) ?? queryLeaf);
-            SqliteCommandPolicy.Add(cmd, "@query0SegmentCount", SqlNameResolver.GetSegmentCount(value));
-            SqliteCommandPolicy.Add(cmd, "@query0NormalizedLike", $"%{EscapeLikeQuery(SqlNameResolver.NormalizeQualifiedName(value))}%");
-            AddCSharpExplicitInterfaceIdentityQueryParameter(cmd, "query0", value);
-            if (SqlNameResolver.HasQualifier(value))
-                AddQualifiedSymbolQueryParameters(cmd, "query0", value);
-            if (rustQualifiedParts.QualifiedPath != null)
-            {
-                SqliteCommandPolicy.Add(cmd, "@query0RustContainer", rustQualifiedParts.ContainerPath ?? string.Empty);
-                SqliteCommandPolicy.Add(cmd, "@query0RustLeaf", rustQualifiedParts.LeafName ?? string.Empty);
-                SqliteCommandPolicy.Add(cmd, "@query0RustLeafFolded", NameFold.Fold(rustQualifiedParts.LeafName ?? string.Empty) ?? rustQualifiedParts.LeafName ?? string.Empty);
-            }
-        }
-        if (kind != null)
-            SqliteCommandPolicy.Add(cmd, "@kind", kind);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        if (since != null && _fileColumns.Contains("modified"))
-            SqliteCommandPolicy.Add(cmd, "@since", since.Value);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        AddVisibilityFilterParameters(cmd, visibilityFilters, excludeVisibilityFilters);
-        SqliteCommandPolicy.Add(cmd, "@limit", limit);
-
-        var raw = cmd.ExecuteScalar();
-        return raw is long l ? (int)l : Convert.ToInt32(raw);
-    }
-
-    public QueryCountResult CountSearchSymbolsTotal(string? query = null, string? kind = null, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, DateTime? since = null, bool exact = false, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null, bool groupPartials = false)
-    {
-        return CountSearchSymbolsTotal(query == null ? null : new[] { NormalizeSymbolSearchQueryForSymbolSearch(query, lang, exact) ?? query ?? string.Empty }, kind, lang, pathPatterns, excludePathPatterns, excludeTests, since, exact, visibilityFilters, excludeVisibilityFilters, groupPartials);
-    }
-
-    public QueryCountResult CountSearchSymbolsTotal(IReadOnlyList<string>? queries, string? kind = null, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, DateTime? since = null, bool exact = false, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null, bool groupPartials = false)
-    {
-        lang = DbReader.NormalizeQueryLanguage(lang);
-        var effectiveQueries = NormalizeSymbolSearchQueries(queries, lang, exact);
-        if (groupPartials)
-            EnsureCSharpCallableTypeKinds(lang, effectiveQueries, exact, kind);
-        using var cmd = _conn.CreateCommand();
-
-        var logicalPartialKeySql = LogicalPartialSymbolGrouper.BuildSqlKeyExpression(
-            "f.lang",
-            "s.kind",
-            "s.name",
-            "s.id",
-            "f.path",
-            GetSymbolColumnSql("signature"),
-            GetSymbolColumnSql("container_name"),
-            GetSymbolColumnSql("container_qualified_name"),
-            GetSymbolColumnSql("family_key"),
-            GetSymbolColumnSql("return_type"),
-            GetSymbolColumnSql("is_partial_declaration"),
-            _hotspotFamilyReadyLanguages.Contains("csharp"));
-        var countSql = groupPartials
-            ? $"COUNT(DISTINCT ({logicalPartialKeySql}))"
-            : "COUNT(*)";
-        var sql = $@"
-            SELECT {countSql}, COUNT(DISTINCT f.path)
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE 1=1";
-
-        if (effectiveQueries != null && effectiveQueries.Count > 0)
-        {
-            var orClauses = exact
-                ? string.Join(" OR ", effectiveQueries.Select((queryValue, idx) =>
-                {
-                    var rustQualifiedExact = ShouldPreserveRustQualifiedExactQuery(queryValue, lang, exact);
-                    var rustQualifiedParts = rustQualifiedExact ? NormalizeRustQualifiedExactQueryParts(queryValue) : default;
-                    var allowLeafFallback = !SqlNameResolver.HasQualifier(queryValue);
-                    var markdownAnchorClause = _symbolColumns.Contains("name_folded")
-                        ? $"(f.lang = 'markdown' AND ((s.kind = 'heading' AND s.name_folded = @query{idx}MarkdownHeading) OR (s.kind = 'anchor' AND s.name_folded = @query{idx}MarkdownExplicitAnchor COLLATE BINARY)))"
-                        : "0";
-                    var qualifiedSymbolClause = SqlNameResolver.HasQualifier(queryValue)
-                        ? BuildQualifiedSymbolMatchSql($"query{idx}", _foldReady)
-                        : null;
-                    var csharpExplicitInterfaceClause = allowLeafFallback
-                        ? BuildCSharpExplicitInterfaceShortAliasMatchSql($"query{idx}")
-                        : BuildCSharpExplicitInterfaceIdentityMatchSql($"query{idx}");
-                    var swiftBacktickAlias = ComputeSwiftBacktickAlias(queryValue, lang);
-                    var swiftBacktickClause = swiftBacktickAlias != null
-                        ? _foldReady
-                            ? $" OR s.name_folded = @query{idx}SwiftBacktickAlias"
-                            : $" OR s.name = @query{idx}SwiftBacktickAlias COLLATE NOCASE"
-                        : string.Empty;
-                    if (rustQualifiedParts.QualifiedPath != null)
-                        return _foldReady
-                            ? $"((s.container_qualified_name = @query{idx}RustContainer COLLATE NOCASE OR s.container_name = @query{idx}RustContainer COLLATE NOCASE) AND s.name_folded = @query{idx}RustLeafFolded)"
-                            : $"((s.container_qualified_name = @query{idx}RustContainer COLLATE NOCASE OR s.container_name = @query{idx}RustContainer COLLATE NOCASE) AND s.name = @query{idx}RustLeaf COLLATE NOCASE)";
-                    return _foldReady
-                        ? allowLeafFallback
-                            ? $"({BuildExactPrimarySymbolNameMatchSql($"@query{idx}", true, queryValue, lang)}{swiftBacktickClause} OR {csharpExplicitInterfaceClause} OR {markdownAnchorClause} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @query{idx}SegmentCount AND sql_normalize_name_folded(s.name) = @query{idx}NormalizedFolded) OR sql_leaf_name_folded(s.name) = @query{idx}LeafFolded)))"
-                            : $"({BuildExactPrimarySymbolNameMatchSql($"@query{idx}", true, queryValue, lang)}{swiftBacktickClause} OR {csharpExplicitInterfaceClause} OR {markdownAnchorClause} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @query{idx}SegmentCount AND sql_normalize_name_folded(s.name) = @query{idx}NormalizedFolded){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause}" : string.Empty)})"
-                        : allowLeafFallback
-                            ? $"({BuildExactPrimarySymbolNameMatchSql($"@query{idx}", false, queryValue, lang)}{swiftBacktickClause} OR {csharpExplicitInterfaceClause} OR {markdownAnchorClause} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @query{idx}SegmentCount AND sql_normalize_name(s.name) = @query{idx}Normalized COLLATE NOCASE) OR sql_leaf_name(s.name) = @query{idx}Leaf COLLATE NOCASE)))"
-                            : $"({BuildExactPrimarySymbolNameMatchSql($"@query{idx}", false, queryValue, lang)}{swiftBacktickClause} OR {csharpExplicitInterfaceClause} OR {markdownAnchorClause} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @query{idx}SegmentCount AND sql_normalize_name(s.name) = @query{idx}Normalized COLLATE NOCASE){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause}" : string.Empty)})";
-                }))
-                : string.Join(" OR ", effectiveQueries.Select((queryValue, idx) =>
-                {
-                    var qualifiedSymbolClause = SqlNameResolver.HasQualifier(queryValue)
-                        ? BuildQualifiedSymbolMatchSql($"query{idx}", _foldReady)
-                        : null;
-                    var csharpExplicitInterfaceClause = SqlNameResolver.HasQualifier(queryValue)
-                        ? BuildCSharpExplicitInterfaceIdentityMatchSql($"query{idx}")
-                        : null;
-                    var markdownAnchorLikeClause = _symbolColumns.Contains("name_folded")
-                        ? $" OR (f.lang = 'markdown' AND ((s.kind = 'heading' AND s.name_folded LIKE @query{idx}MarkdownHeadingLike ESCAPE '\\') OR (s.kind = 'anchor' AND instr(s.name_folded, @query{idx}MarkdownExplicitAnchor) > 0)))"
-                        : string.Empty;
-                    return $"(s.name LIKE @query{idx} ESCAPE '\\'{markdownAnchorLikeClause} OR (f.lang = 'sql' AND sql_normalize_name(s.name) LIKE @query{idx}NormalizedLike ESCAPE '\\'){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause} OR {csharpExplicitInterfaceClause}" : string.Empty)})";
-                }));
-            sql += $" AND ({orClauses})";
-        }
-        if (kind != null)
-            sql += " AND s.kind = @kind";
-        if (lang != null)
-            sql += SymbolLanguageFileIdFilter;
-        if (since != null && _fileColumns.Contains("modified"))
-            sql += " AND f.modified >= @since";
-        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
-        AppendVisibilityFilters(ref sql, visibilityFilters, excludeVisibilityFilters);
-
-        cmd.CommandText = sql;
-        if (effectiveQueries != null)
-        {
-            for (int i = 0; i < effectiveQueries.Count; i++)
-            {
-                var value = effectiveQueries[i];
-                var paramValue = !exact
-                    ? $"%{EscapeLikeQuery(value)}%"
-                    : _foldReady
-                        ? FoldNameForLanguage(value, lang)
-                        : value;
-                if (exact && _foldReady)
-                    AddPersistedFoldedNameQueryParameters(cmd, $"@query{i}", value, lang);
-                else
-                    SqliteCommandPolicy.Add(cmd, $"@query{i}", paramValue);
-                SqliteCommandPolicy.Add(cmd, $"@query{i}Normalized", SqlNameResolver.NormalizeQualifiedName(value));
-                SqliteCommandPolicy.Add(cmd, $"@query{i}NormalizedFolded", NameFold.Fold(SqlNameResolver.NormalizeQualifiedName(value)) ?? SqlNameResolver.NormalizeQualifiedName(value));
-                var queryLeaf = GetQualifiedQueryLeaf(value, lang);
-                SqliteCommandPolicy.Add(cmd, $"@query{i}Leaf", queryLeaf);
-                SqliteCommandPolicy.Add(cmd, $"@query{i}LeafFolded", NameFold.Fold(queryLeaf) ?? queryLeaf);
-                SqliteCommandPolicy.Add(cmd, $"@query{i}SegmentCount", SqlNameResolver.GetSegmentCount(value));
-                SqliteCommandPolicy.Add(cmd, $"@query{i}NormalizedLike", $"%{EscapeLikeQuery(SqlNameResolver.NormalizeQualifiedName(value))}%");
-                AddCSharpExplicitInterfaceIdentityQueryParameter(cmd, $"query{i}", value);
-                if (_symbolColumns.Contains("name_folded"))
-                {
-                    var markdownHeadingIdentity = MarkdownAnchorIdentity.NormalizeHeadingFragment(value);
-                    SqliteCommandPolicy.Add(cmd, $"@query{i}MarkdownHeading", markdownHeadingIdentity);
-                    SqliteCommandPolicy.Add(cmd, $"@query{i}MarkdownHeadingLike", $"%{EscapeLikeQuery(markdownHeadingIdentity)}%");
-                    SqliteCommandPolicy.Add(cmd, $"@query{i}MarkdownExplicitAnchor", MarkdownAnchorIdentity.NormalizeExplicitAnchorDefinition(value));
-                }
-                if (SqlNameResolver.HasQualifier(value))
-                    AddQualifiedSymbolQueryParameters(cmd, $"query{i}", value);
-                var rustQualifiedExact = ShouldPreserveRustQualifiedExactQuery(value, lang, exact);
-                var rustQualifiedParts = rustQualifiedExact
-                    ? NormalizeRustQualifiedExactQueryParts(value)
-                    : default;
-                if (rustQualifiedParts.QualifiedPath != null)
-                {
-                    SqliteCommandPolicy.Add(cmd, $"@query{i}RustContainer", rustQualifiedParts.ContainerPath ?? string.Empty);
-                    SqliteCommandPolicy.Add(cmd, $"@query{i}RustLeaf", rustQualifiedParts.LeafName ?? string.Empty);
-                    SqliteCommandPolicy.Add(cmd, $"@query{i}RustLeafFolded", NameFold.Fold(rustQualifiedParts.LeafName ?? string.Empty) ?? rustQualifiedParts.LeafName ?? string.Empty);
-                }
-                var swiftBacktickAlias = ComputeSwiftBacktickAlias(value, lang);
-                if (swiftBacktickAlias != null)
-                {
-                    SqliteCommandPolicy.Add(cmd, $"@query{i}SwiftBacktickAlias", _foldReady
-                        ? NameFold.Fold(swiftBacktickAlias) ?? swiftBacktickAlias
-                        : swiftBacktickAlias);
-                }
-            }
-        }
-        if (kind != null)
-            SqliteCommandPolicy.Add(cmd, "@kind", kind);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        if (since != null && _fileColumns.Contains("modified"))
-            SqliteCommandPolicy.Add(cmd, "@since", since.Value);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        AddVisibilityFilterParameters(cmd, visibilityFilters, excludeVisibilityFilters);
-
-        using var reader = cmd.ExecuteTrackedReader();
-        return reader.TrackedRead()
-            ? new QueryCountResult(reader.GetInt32(0), reader.GetInt32(1))
-            : new QueryCountResult(0, 0);
-    }
-
-    /// <summary>
-    /// Search symbols by one or more name patterns (OR-joined). Empty/null list returns all symbols matching other filters.
-    /// When <paramref name="exact"/> is true, names are matched case-insensitively for equality instead of substring.
-    /// 複数名前パターン（OR結合）でシンボルを検索。空/null なら他フィルタに一致する全シンボルを返す。
-    /// <paramref name="exact"/> が true の場合、部分一致ではなく大文字小文字を無視した完全一致になる。
-    /// </summary>
-    public List<SymbolResult> SearchSymbols(IReadOnlyList<string>? queries, int limit = 20, string? kind = null, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, DateTime? since = null, bool exact = false, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null, SymbolSortMode sortMode = SymbolSortMode.Name, int? startLine = null, int? endLine = null, bool groupPartials = false, int offset = 0)
-    {
-        lang = DbReader.NormalizeQueryLanguage(lang);
-        // Multi-name queries: run one search per name to guarantee per-name candidate coverage
-        // (a common/earlier-sorting name cannot starve others out of the candidate pool), then
-        // round-robin interleave the per-name results under a single global `limit` cap so the
-        // public `limit` contract stays "Max total results", not per-name.
-        // 複数名指定: 名前ごとに独立検索して候補プールを確保した上で、round-robin で統合し、
-        // 最終的に全体で `limit` 件に収める。`limit` は従来どおり「合計の上限」。
-        var validQueries = NormalizeSymbolSearchQueries(queries, lang, exact);
-        if (validQueries != null && validQueries.Count > 1)
-        {
-            var requestedPrefix = checked(limit + Math.Max(0, offset));
-            var perName = new List<List<SymbolResult>>(validQueries.Count);
-            foreach (var q in validQueries)
-                perName.Add(SearchSymbols(new[] { q! }, requestedPrefix, kind, lang, pathPatterns, excludePathPatterns, excludeTests, since, exact, visibilityFilters, excludeVisibilityFilters, sortMode, startLine, endLine, groupPartials));
-
-            // De-duplicate the same physical symbol returned by multiple query branches while
-            // preserving distinct indexed rows that happen to share a path/line/name/kind tuple.
-            // 複数 query branch が返した同一 physical symbol は除外する一方、path/line/name/kind が
-            // 偶然一致する別の indexed row は保持する。
-            var seen = new HashSet<long?>();
-            var merged = new List<SymbolResult>();
-            var cursors = new int[perName.Count];
-            bool advanced;
-            do
-            {
-                advanced = false;
-                for (int i = 0; i < perName.Count && merged.Count < requestedPrefix; i++)
-                {
-                    while (cursors[i] < perName[i].Count)
-                    {
-                        var r = perName[i][cursors[i]++];
-                        if (seen.Add(r.SymbolId))
-                        {
-                            merged.Add(r);
-                            advanced = true;
-                            break;
-                        }
-                    }
-                }
-            } while (advanced && merged.Count < requestedPrefix);
-            return merged.Skip(Math.Max(0, offset)).Take(limit).ToList();
-        }
-
-        if (groupPartials)
-            EnsureCSharpCallableTypeKinds(lang, validQueries, exact, kind);
-        using var cmd = _conn.CreateCommand();
-
-        var startLineSql = GetSymbolColumnSql("start_line", "s.line");
-        var endLineSql = GetSymbolColumnSql("end_line", "s.line");
-        var bodyStartLineSql = GetSymbolColumnSql("body_start_line");
-        var bodyEndLineSql = GetSymbolColumnSql("body_end_line");
-        var signatureSql = GetSymbolColumnSql("signature");
-        var containerKindSql = GetSymbolColumnSql("container_kind");
-        var containerNameSql = GetSymbolColumnSql("container_name");
-        var containerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name");
-        var familyKeySql = GetSymbolColumnSql("family_key");
-        var visibilitySql = GetSymbolColumnSql("visibility");
-        var returnTypeSql = GetSymbolColumnSql("return_type");
-        var startColumnSql = GetSymbolColumnSql("start_column", "CAST(2147483647 AS INTEGER)");
-        var sizeLinesSql = $"CASE WHEN ({endLineSql}) >= ({startLineSql}) THEN ({endLineSql}) - ({startLineSql}) + 1 ELSE 1 END";
-        var includeRankSignals = sortMode != SymbolSortMode.Name && _hasReferencesTable;
-        // Keep aggregate grouping aligned with the NOCASE joins below. Binary grouping would emit
-        // one aggregate row per case variant and multiply the same physical s.id before LIMIT/OFFSET (#4753).
-        // 集計側と下記 NOCASE JOIN の照合順序を揃え、大小文字 variant による同一 s.id の増殖を防ぐ。
-        var symbolRankJoin = includeRankSignals
-            ? $@"
-            LEFT JOIN (
-                SELECT rf.lang AS lang,
-                       sr.symbol_name AS symbol_name,
-                       COUNT(*) AS reference_count,
-                       SUM({GetHotspotReferenceWeightSql("sr.reference_kind")}) AS hotspot_score
-                FROM symbol_references sr
-                JOIN files rf ON rf.id = sr.file_id
-                WHERE sr.reference_kind IN {CallGraphReferenceKindsSql}
-                  AND sr.symbol_name IS NOT NULL
-                  AND sr.symbol_name <> ''
-                GROUP BY rf.lang, sr.symbol_name COLLATE NOCASE
-            ) symbol_rank
-              ON symbol_rank.lang = f.lang
-             AND symbol_rank.symbol_name = s.name COLLATE NOCASE
-            LEFT JOIN (
-                SELECT sr.file_id AS file_id,
-                       sr.symbol_name AS symbol_name,
-                       COUNT(*) AS reference_count,
-                       SUM({GetHotspotReferenceWeightSql("sr.reference_kind")}) AS hotspot_score
-                FROM symbol_references sr
-                WHERE sr.reference_kind IN {CallGraphReferenceKindsSql}
-                  AND sr.symbol_name IS NOT NULL
-                  AND sr.symbol_name <> ''
-                GROUP BY sr.file_id, sr.symbol_name COLLATE NOCASE
-            ) symbol_file_rank
-              ON symbol_file_rank.file_id = s.file_id
-             AND symbol_file_rank.symbol_name = s.name COLLATE NOCASE
-            LEFT JOIN (
-                SELECT df.lang AS lang,
-                       ds.name AS symbol_name,
-                       COUNT(*) AS definition_sites
-                FROM symbols ds
-                JOIN files df ON df.id = ds.file_id
-                WHERE ds.name IS NOT NULL
-                  AND ds.name <> ''
-                GROUP BY df.lang, ds.name COLLATE NOCASE
-            ) symbol_defs
-              ON symbol_defs.lang = f.lang
-             AND symbol_defs.symbol_name = s.name COLLATE NOCASE"
-            : string.Empty;
-        var genericNamePenaltySql = includeRankSignals ? GetGenericSymbolRankNamePenaltySql("s.name") : "1.0";
-        var definitionSitesSql = includeRankSignals ? "COALESCE(symbol_defs.definition_sites, 1)" : "CAST(1 AS INTEGER)";
-        var csharpConservativeRankSignalSql = includeRankSignals
-            ? $"(f.lang = 'csharp' AND (s.kind = 'property' OR ({definitionSitesSql}) > 1 OR lower(s.name) IN {GenericSymbolRankNamesSql}))"
-            : "0";
-        var referenceCountSql = includeRankSignals
-            ? $"CASE WHEN {csharpConservativeRankSignalSql} THEN COALESCE(symbol_file_rank.reference_count, 0) ELSE COALESCE(symbol_rank.reference_count, 0) END"
-            : "CAST(0 AS INTEGER)";
-        var hotspotScoreSql = includeRankSignals
-            ? $"CASE WHEN {csharpConservativeRankSignalSql} THEN COALESCE(symbol_file_rank.hotspot_score, 0.0) ELSE COALESCE(symbol_rank.hotspot_score, 0.0) END"
-            : "CAST(0.0 AS REAL)";
-        var definitionDilutionSql = $"CASE WHEN ({definitionSitesSql}) > 1 THEN CAST(({definitionSitesSql}) * ({definitionSitesSql}) AS REAL) ELSE 1.0 END";
-        var structuralRankPenaltySql = includeRankSignals ? $"CASE WHEN s.kind IN ('property', 'enum') AND ({sizeLinesSql}) <= 1 THEN 0.1 ELSE 1.0 END" : "1.0";
-        var rankingReferenceScoreSql = includeRankSignals ? $"(({referenceCountSql}) * ({genericNamePenaltySql}) * ({structuralRankPenaltySql}) / ({definitionDilutionSql}))" : referenceCountSql;
-        var rankingHotspotScoreSql = includeRankSignals ? $"(({hotspotScoreSql}) * ({genericNamePenaltySql}) * ({structuralRankPenaltySql}) / ({definitionDilutionSql}))" : hotspotScoreSql;
-        var cappedRankingReferenceScoreSql = $"CASE WHEN ({rankingReferenceScoreSql}) > 100.0 THEN 100.0 ELSE ({rankingReferenceScoreSql}) END";
-        var cappedRankingHotspotScoreSql = $"CASE WHEN ({rankingHotspotScoreSql}) > 150.0 THEN 150.0 ELSE ({rankingHotspotScoreSql}) END";
-        var complexityScoreSql = $@"(({sizeLinesSql} * 16.0) + ({cappedRankingReferenceScoreSql} * 0.75) + ({cappedRankingHotspotScoreSql} * 0.35) + CASE
-                       WHEN {visibilitySql} IN ('public', 'pub', 'open', 'export') THEN 8.0
-                       WHEN {visibilitySql} IN ('protected', 'internal', 'protected internal') THEN 4.0
-                       ELSE 0.0
-                   END)";
-        var logicalPartialKeySql = LogicalPartialSymbolGrouper.BuildSqlKeyExpression(
-            "f.lang",
-            "s.kind",
-            "s.name",
-            "s.id",
-            "f.path",
-            signatureSql,
-            containerNameSql,
-            containerQualifiedNameSql,
-            familyKeySql,
-            returnTypeSql,
-            GetSymbolColumnSql("is_partial_declaration"),
-            _hotspotFamilyReadyLanguages.Contains("csharp"));
-        var generatedSql = _fileColumns.Contains("generated")
-            ? "CASE WHEN COALESCE(f.generated, 0) <> 0 OR codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END"
-            : "CASE WHEN codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END";
-        var canonicalPrimaryRankSql = LogicalPartialSymbolGrouper.BuildSqlPrimaryRankExpression(
-            "s.kind",
-            bodyStartLineSql,
-            bodyEndLineSql);
-        var canonicalSemanticScoreSql = LogicalPartialSymbolGrouper.BuildSqlSemanticScoreExpression(
-            signatureSql,
-            "s.kind",
-            GetSymbolColumnSql("declaration_semantic_score"));
-        var fallbackCanonicalDeclarationIdentitySql = BuildCanonicalDeclarationIdentitySql(signatureSql);
-        var canonicalDeclarationIdentitySql = $"CASE WHEN s.kind IN ('function', 'test.method') THEN COALESCE(csharp_partial_callable_identity({signatureSql}, s.name, {returnTypeSql}), {fallbackCanonicalDeclarationIdentitySql}) ELSE {fallbackCanonicalDeclarationIdentitySql} END";
-        var exactNameOrderSql = "CASE " +
-            "WHEN @preferLiteralExactMatch = 1 AND s.name = @rawQuery THEN 0 " +
-            "WHEN @preferLiteralNormalizedSqlMatch = 1 AND f.lang = 'sql' AND sql_segment_count(s.name) = @rawQuerySegmentCount AND sql_normalize_name(s.name) = @rawQueryNormalized THEN 1 " +
-            "WHEN @preferCaseInsensitiveExactMatch = 1 AND s.name = @rawQuery COLLATE NOCASE THEN 2 " +
-            "WHEN @preferCaseInsensitiveNormalizedSqlMatch = 1 AND f.lang = 'sql' AND sql_segment_count(s.name) = @rawQuerySegmentCount AND sql_normalize_name_folded(s.name) = @rawQueryNormalizedFolded THEN 3 " +
-            "WHEN @preferCaseInsensitiveSqlLeafMatch = 1 AND f.lang = 'sql' AND sql_leaf_name_folded(s.name) = @rawQueryLeafFolded THEN 4 " +
-            "ELSE 5 END";
-
-        var sql = $@"
-            SELECT f.path, f.lang, s.kind, {GetSymbolColumnSql("sub_kind")} AS sub_kind, s.name, s.line,
-                   {startLineSql} AS start_line,
-                   {GetSymbolColumnSql("start_column")} AS start_column,
-                   {endLineSql} AS end_line,
-                   {bodyStartLineSql} AS body_start_line,
-                   {bodyEndLineSql} AS body_end_line,
-                   {signatureSql} AS signature,
-                   {containerKindSql} AS container_kind,
-                   {containerNameSql} AS container_name,
-                   {visibilitySql} AS visibility,
-                   {returnTypeSql} AS return_type,
-                   {referenceCountSql} AS reference_count,
-                   {hotspotScoreSql} AS hotspot_score,
-                   {rankingReferenceScoreSql} AS ranking_reference_score,
-                   {rankingHotspotScoreSql} AS ranking_hotspot_score,
-                   {genericNamePenaltySql} AS generic_name_penalty,
-                   {structuralRankPenaltySql} AS structural_rank_penalty,
-                   {definitionSitesSql} AS definition_sites,
-                   {sizeLinesSql} AS size_lines,
-                   {complexityScoreSql} AS complexity_score,
-                   {containerQualifiedNameSql} AS container_qualified_name,
-                   {logicalPartialKeySql} AS logical_partial_key,
-                   s.id AS symbol_id,
-                   {exactNameOrderSql} AS exact_name_order,
-                   {PathBucketOrder} AS path_bucket,
-                   {VisibilityOrder} AS visibility_rank,
-                   {startColumnSql} AS stable_start_column,
-                   {canonicalPrimaryRankSql} AS canonical_primary_rank,
-                   {generatedSql} AS canonical_generated_rank,
-                   {canonicalSemanticScoreSql} AS canonical_semantic_score,
-                   {canonicalDeclarationIdentitySql} AS canonical_declaration_identity,
-                   {GetSymbolColumnSql("identifier_start_column")} AS identifier_start_column
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            {symbolRankJoin}
-            WHERE 1=1";
-
-        var effectiveQueries = validQueries;
-        if (effectiveQueries != null && effectiveQueries.Count > 0)
-        {
-            // --exact: Unicode-aware equality when FoldReady (#86), else ASCII COLLATE NOCASE.
-            // Fold path: `s.name_folded = @qFolded` (indexed by idx_symbols_name_folded), query
-            // value is pre-folded in .NET with NameFold.Fold so Ä vs ä / 全角 vs 半角 match.
-            // Fallback: `s.name = @q COLLATE NOCASE` (indexed by idx_symbols_name_nocase). Both
-            // paths stay SARGable. Using `lower(col)` would force a full scan per name.
-            // --exact: FoldReady なら Unicode 折り畳み経路、未 ready ならレガシー NOCASE 経路へ fallback。
-            var orClauses = exact
-                ? string.Join(" OR ", effectiveQueries.Select((queryValue, idx) =>
-                {
-                    var rustQualifiedExact = ShouldPreserveRustQualifiedExactQuery(queryValue, lang, exact);
-                    var rustQualifiedParts = rustQualifiedExact ? NormalizeRustQualifiedExactQueryParts(queryValue) : default;
-                    var allowLeafFallback = !SqlNameResolver.HasQualifier(queryValue);
-                    var markdownAnchorClause = _symbolColumns.Contains("name_folded")
-                        ? $"(f.lang = 'markdown' AND ((s.kind = 'heading' AND s.name_folded = @query{idx}MarkdownHeading) OR (s.kind = 'anchor' AND s.name_folded = @query{idx}MarkdownExplicitAnchor COLLATE BINARY)))"
-                        : "0";
-                    var qualifiedSymbolClause = SqlNameResolver.HasQualifier(queryValue)
-                        ? BuildQualifiedSymbolMatchSql($"query{idx}", _foldReady)
-                        : null;
-                    var csharpExplicitInterfaceClause = allowLeafFallback
-                        ? BuildCSharpExplicitInterfaceShortAliasMatchSql($"query{idx}")
-                        : BuildCSharpExplicitInterfaceIdentityMatchSql($"query{idx}");
-                    var swiftBacktickAlias = ComputeSwiftBacktickAlias(queryValue, lang);
-                    var swiftBacktickClause = swiftBacktickAlias != null
-                        ? _foldReady
-                            ? $" OR s.name_folded = @query{idx}SwiftBacktickAlias"
-                            : $" OR s.name = @query{idx}SwiftBacktickAlias COLLATE NOCASE"
-                        : string.Empty;
-                    if (rustQualifiedParts.QualifiedPath != null)
-                        return _foldReady
-                            ? $"((s.container_qualified_name = @query{idx}RustContainer COLLATE NOCASE OR s.container_name = @query{idx}RustContainer COLLATE NOCASE) AND s.name_folded = @query{idx}RustLeafFolded)"
-                            : $"((s.container_qualified_name = @query{idx}RustContainer COLLATE NOCASE OR s.container_name = @query{idx}RustContainer COLLATE NOCASE) AND s.name = @query{idx}RustLeaf COLLATE NOCASE)";
-                    return _foldReady
-                        ? allowLeafFallback
-                            ? $"({BuildExactPrimarySymbolNameMatchSql($"@query{idx}", true, queryValue, lang)}{swiftBacktickClause} OR {csharpExplicitInterfaceClause} OR {markdownAnchorClause} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @query{idx}SegmentCount AND sql_normalize_name_folded(s.name) = @query{idx}NormalizedFolded) OR sql_leaf_name_folded(s.name) = @query{idx}LeafFolded)))"
-                            : $"({BuildExactPrimarySymbolNameMatchSql($"@query{idx}", true, queryValue, lang)}{swiftBacktickClause} OR {csharpExplicitInterfaceClause} OR {markdownAnchorClause} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @query{idx}SegmentCount AND sql_normalize_name_folded(s.name) = @query{idx}NormalizedFolded){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause}" : string.Empty)})"
-                        : allowLeafFallback
-                            ? $"({BuildExactPrimarySymbolNameMatchSql($"@query{idx}", false, queryValue, lang)}{swiftBacktickClause} OR {csharpExplicitInterfaceClause} OR {markdownAnchorClause} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @query{idx}SegmentCount AND sql_normalize_name(s.name) = @query{idx}Normalized COLLATE NOCASE) OR sql_leaf_name(s.name) = @query{idx}Leaf COLLATE NOCASE)))"
-                            : $"({BuildExactPrimarySymbolNameMatchSql($"@query{idx}", false, queryValue, lang)}{swiftBacktickClause} OR {csharpExplicitInterfaceClause} OR {markdownAnchorClause} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @query{idx}SegmentCount AND sql_normalize_name(s.name) = @query{idx}Normalized COLLATE NOCASE){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause}" : string.Empty)})";
-                }))
-                : string.Join(" OR ", effectiveQueries.Select((queryValue, idx) =>
-                {
-                    var qualifiedSymbolClause = SqlNameResolver.HasQualifier(queryValue)
-                        ? BuildQualifiedSymbolMatchSql($"query{idx}", _foldReady)
-                        : null;
-                    var csharpExplicitInterfaceClause = SqlNameResolver.HasQualifier(queryValue)
-                        ? BuildCSharpExplicitInterfaceIdentityMatchSql($"query{idx}")
-                        : null;
-                    var markdownAnchorLikeClause = _symbolColumns.Contains("name_folded")
-                        ? $" OR (f.lang = 'markdown' AND ((s.kind = 'heading' AND s.name_folded LIKE @query{idx}MarkdownHeadingLike ESCAPE '\\') OR (s.kind = 'anchor' AND instr(s.name_folded, @query{idx}MarkdownExplicitAnchor) > 0)))"
-                        : string.Empty;
-                    return $"(s.name LIKE @query{idx} ESCAPE '\\'{markdownAnchorLikeClause} OR (f.lang = 'sql' AND sql_normalize_name(s.name) LIKE @query{idx}NormalizedLike ESCAPE '\\'){(qualifiedSymbolClause != null ? $" OR {qualifiedSymbolClause} OR {csharpExplicitInterfaceClause}" : string.Empty)})";
-                }));
-            sql += $" AND ({orClauses})";
-        }
-        if (kind != null)
-            sql += " AND s.kind = @kind";
-        if (lang != null)
-            sql += SymbolLanguageFileIdFilter;
-        if (since != null && _fileColumns.Contains("modified"))
-            sql += " AND f.modified >= @since";
-        if (startLine != null)
-            sql += " AND s.line >= @startLine";
-        if (endLine != null)
-            sql += " AND s.line <= @endLine";
-        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
-        AppendVisibilityFilters(ref sql, visibilityFilters, excludeVisibilityFilters);
-        if (groupPartials)
-            sql = BuildLogicalPartialSymbolQuery(sql, sortMode);
-        else
-            sql += BuildSymbolSortOrderBy(sortMode, exactNameOrderSql, referenceCountSql, hotspotScoreSql, rankingReferenceScoreSql, rankingHotspotScoreSql, sizeLinesSql, complexityScoreSql, startColumnSql);
-        sql += " LIMIT @limit OFFSET @offset";
-
-        cmd.CommandText = sql;
-        if (effectiveQueries != null)
-        {
-            for (int idx = 0; idx < effectiveQueries.Count; idx++)
-            {
-                string paramValue;
-                var rustQualifiedExact = ShouldPreserveRustQualifiedExactQuery(effectiveQueries[idx], lang, exact);
-                var rustQualifiedParts = rustQualifiedExact ? NormalizeRustQualifiedExactQueryParts(effectiveQueries[idx]) : default;
-                if (!exact)
-                    paramValue = $"%{EscapeLikeQuery(effectiveQueries[idx])}%";
-                else if (_foldReady)
-                    paramValue = FoldNameForLanguage(effectiveQueries[idx], lang);
-                else
-                    paramValue = effectiveQueries[idx];
-                if (exact && _foldReady)
-                {
-                    AddPersistedFoldedNameQueryParameters(
-                        cmd,
-                        $"@query{idx}",
-                        effectiveQueries[idx],
-                        lang);
-                }
-                else
-                {
-                    SqliteCommandPolicy.Add(cmd, $"@query{idx}", paramValue);
-                }
-                SqliteCommandPolicy.Add(cmd, $"@query{idx}Normalized", SqlNameResolver.NormalizeQualifiedName(effectiveQueries[idx]));
-                SqliteCommandPolicy.Add(cmd, $"@query{idx}NormalizedFolded", NameFold.Fold(SqlNameResolver.NormalizeQualifiedName(effectiveQueries[idx])) ?? SqlNameResolver.NormalizeQualifiedName(effectiveQueries[idx]));
-                var queryLeaf = GetQualifiedQueryLeaf(effectiveQueries[idx], lang);
-                SqliteCommandPolicy.Add(cmd, $"@query{idx}Leaf", queryLeaf);
-                SqliteCommandPolicy.Add(cmd, $"@query{idx}LeafFolded", NameFold.Fold(queryLeaf) ?? queryLeaf);
-                SqliteCommandPolicy.Add(cmd, $"@query{idx}SegmentCount", SqlNameResolver.GetSegmentCount(effectiveQueries[idx]));
-                SqliteCommandPolicy.Add(cmd, $"@query{idx}NormalizedLike", $"%{EscapeLikeQuery(SqlNameResolver.NormalizeQualifiedName(effectiveQueries[idx]))}%");
-                AddCSharpExplicitInterfaceIdentityQueryParameter(cmd, $"query{idx}", effectiveQueries[idx]);
-                if (_symbolColumns.Contains("name_folded"))
-                {
-                    var markdownHeadingIdentity = MarkdownAnchorIdentity.NormalizeHeadingFragment(effectiveQueries[idx]);
-                    SqliteCommandPolicy.Add(cmd, $"@query{idx}MarkdownHeading", markdownHeadingIdentity);
-                    SqliteCommandPolicy.Add(cmd, $"@query{idx}MarkdownHeadingLike", $"%{EscapeLikeQuery(markdownHeadingIdentity)}%");
-                    SqliteCommandPolicy.Add(cmd, $"@query{idx}MarkdownExplicitAnchor", MarkdownAnchorIdentity.NormalizeExplicitAnchorDefinition(effectiveQueries[idx]));
-                }
-                if (SqlNameResolver.HasQualifier(effectiveQueries[idx]))
-                    AddQualifiedSymbolQueryParameters(cmd, $"query{idx}", effectiveQueries[idx]);
-                if (rustQualifiedParts.QualifiedPath != null)
-                {
-                    SqliteCommandPolicy.Add(cmd, $"@query{idx}RustContainer", rustQualifiedParts.ContainerPath ?? string.Empty);
-                    SqliteCommandPolicy.Add(cmd, $"@query{idx}RustLeaf", rustQualifiedParts.LeafName ?? string.Empty);
-                    SqliteCommandPolicy.Add(cmd, $"@query{idx}RustLeafFolded", NameFold.Fold(rustQualifiedParts.LeafName ?? string.Empty) ?? rustQualifiedParts.LeafName ?? string.Empty);
-                }
-                var swiftBacktickAlias = ComputeSwiftBacktickAlias(effectiveQueries[idx], lang);
-                if (swiftBacktickAlias != null)
-                {
-                    SqliteCommandPolicy.Add(cmd, $"@query{idx}SwiftBacktickAlias", _foldReady
-                        ? NameFold.Fold(swiftBacktickAlias) ?? swiftBacktickAlias
-                        : swiftBacktickAlias);
-                }
-            }
-        }
-        var preferLiteralExactMatch = effectiveQueries != null && effectiveQueries.Count == 1;
-        var preferCaseInsensitiveExactMatch = effectiveQueries != null && effectiveQueries.Count == 1;
-        var preferSqlLeafMatch = preferCaseInsensitiveExactMatch && !SqlNameResolver.HasQualifier(effectiveQueries![0]);
-        SqliteCommandPolicy.Add(cmd, "@preferLiteralExactMatch", preferLiteralExactMatch ? 1 : 0);
-        SqliteCommandPolicy.Add(cmd, "@preferLiteralNormalizedSqlMatch", preferLiteralExactMatch ? 1 : 0);
-        SqliteCommandPolicy.Add(cmd, "@preferCaseInsensitiveExactMatch", preferCaseInsensitiveExactMatch ? 1 : 0);
-        SqliteCommandPolicy.Add(cmd, "@preferCaseInsensitiveNormalizedSqlMatch", preferCaseInsensitiveExactMatch ? 1 : 0);
-        SqliteCommandPolicy.Add(cmd, "@preferCaseInsensitiveSqlLeafMatch", preferSqlLeafMatch ? 1 : 0);
-        SqliteCommandPolicy.Add(cmd, "@rawQuery", preferLiteralExactMatch ? effectiveQueries![0] : string.Empty);
-        SqliteCommandPolicy.Add(cmd, "@rawQueryNormalized", preferLiteralExactMatch ? SqlNameResolver.NormalizeQualifiedName(effectiveQueries![0]) : string.Empty);
-        SqliteCommandPolicy.Add(cmd, "@rawQueryNormalizedFolded", preferLiteralExactMatch ? NameFold.Fold(SqlNameResolver.NormalizeQualifiedName(effectiveQueries![0])) ?? SqlNameResolver.NormalizeQualifiedName(effectiveQueries![0]) : string.Empty);
-        SqliteCommandPolicy.Add(cmd, "@rawQueryLeaf", preferLiteralExactMatch ? SqlNameResolver.GetLeafName(effectiveQueries![0]) : string.Empty);
-        SqliteCommandPolicy.Add(cmd, "@rawQueryLeafFolded", preferLiteralExactMatch ? NameFold.Fold(SqlNameResolver.GetLeafName(effectiveQueries![0])) ?? SqlNameResolver.GetLeafName(effectiveQueries![0]) : string.Empty);
-        SqliteCommandPolicy.Add(cmd, "@rawQuerySegmentCount", preferLiteralExactMatch ? SqlNameResolver.GetSegmentCount(effectiveQueries![0]) : 0);
-        if (kind != null)
-            SqliteCommandPolicy.Add(cmd, "@kind", kind);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        if (since != null && _fileColumns.Contains("modified"))
-            SqliteCommandPolicy.Add(cmd, "@since", since.Value);
-        if (startLine != null)
-            SqliteCommandPolicy.Add(cmd, "@startLine", startLine.Value);
-        if (endLine != null)
-            SqliteCommandPolicy.Add(cmd, "@endLine", endLine.Value);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        AddVisibilityFilterParameters(cmd, visibilityFilters, excludeVisibilityFilters);
-        SqliteCommandPolicy.Add(cmd, "@limit", limit);
-        SqliteCommandPolicy.Add(cmd, "@offset", Math.Max(0, offset));
-
-        var includeRankingMetadata = sortMode != SymbolSortMode.Name;
-        var sortModeName = sortMode.ToString().ToLowerInvariant();
-        var identifierStartColumnIndex = groupPartials ? 31 : 36;
-        var results = new List<SymbolResult>();
-        using var reader = cmd.ExecuteTrackedReader();
-        while (reader.TrackedRead())
-        {
-            var definitionSites = Convert.ToInt32(reader.GetInt64(22));
-            var result = new SymbolResult
-            {
-                Path = reader.GetString(0),
-                Lang = GetNullableString(reader, 1),
-                Kind = reader.GetString(2),
-                SubKind = GetNullableString(reader, 3),
-                Name = reader.GetString(4),
-                Line = reader.GetInt32(5),
-                StartLine = GetInt32OrFallback(reader, 6, 5),
-                StartColumn = GetNullableInt32(reader, identifierStartColumnIndex)
-                    ?? ResolveSymbolIdentifierStartColumn(
-                        GetNullableInt32(reader, 7),
-                        GetNullableString(reader, 11),
-                        reader.GetString(4),
-                        reader.GetString(2)),
-                EndLine = GetInt32OrFallback(reader, 8, 5),
-                BodyStartLine = GetNullableInt32(reader, 9),
-                BodyEndLine = GetNullableInt32(reader, 10),
-                Signature = GetNullableString(reader, 11),
-                ContainerKind = GetNullableString(reader, 12),
-                ContainerName = GetNullableString(reader, 13),
-                ContainerQualifiedName = GetNullableString(reader, 25),
-                LogicalPartialKey = GetNullableString(reader, 26),
-                Visibility = GetNullableString(reader, 14),
-                ReturnType = GetNullableString(reader, 15),
-                SortMode = includeRankingMetadata ? sortModeName : null,
-                ReferenceCount = includeRankingMetadata ? Convert.ToInt32(reader.GetInt64(16)) : null,
-                HotspotScore = includeRankingMetadata ? Math.Round(reader.GetDouble(17), 3) : null,
-                RankingReferenceScore = includeRankingMetadata ? Math.Round(reader.GetDouble(18), 3) : null,
-                RankingHotspotScore = includeRankingMetadata ? Math.Round(reader.GetDouble(19), 3) : null,
-                GenericNamePenalty = includeRankingMetadata ? Math.Round(reader.GetDouble(20), 3) : null,
-                StructuralRankPenalty = includeRankingMetadata ? Math.Round(reader.GetDouble(21), 3) : null,
-                DefinitionSites = includeRankingMetadata || (groupPartials && definitionSites > 1) ? definitionSites : null,
-                SizeLines = includeRankingMetadata ? Convert.ToInt32(reader.GetInt64(23)) : null,
-                ComplexityScore = includeRankingMetadata ? Math.Round(reader.GetDouble(24), 3) : null,
-                SymbolId = reader.GetInt64(27),
-            };
-            if (groupPartials && definitionSites > 1)
-            {
-                result.PartialFamilyId = LogicalPartialSymbolGrouper.BuildPartialFamilyId(result.LogicalPartialKey!);
-                result.RepresentativeReason = reader.GetString(28);
-                result.FamilyMembers = ReadPartialFamilyMembers(reader.GetString(29), result);
-                result.FamilyMembersTruncated = reader.GetInt64(30) != 0;
-            }
-            results.Add(result);
-        }
-        return results;
-    }
-
-    private static List<PartialFamilyMember> ReadPartialFamilyMembers(string json, SymbolResult representative)
-    {
-        using var document = JsonDocument.Parse(json);
-        var members = new List<PartialFamilyMember>();
-        foreach (var element in document.RootElement.EnumerateArray())
-        {
-            var symbolId = element.GetProperty("symbol_id").GetInt64();
-            var path = element.GetProperty("path").GetString() ?? string.Empty;
-            var startLine = element.GetProperty("start_line").GetInt32();
-            var rawStartColumn = element.GetProperty("start_column").ValueKind == JsonValueKind.Null
-                ? (int?)null
-                : element.GetProperty("start_column").GetInt32();
-            var memberName = element.GetProperty("name").GetString() ?? representative.Name;
-            var memberSignature = element.GetProperty("signature").ValueKind == JsonValueKind.Null
-                ? null
-                : element.GetProperty("signature").GetString();
-            var identifierStartColumn = element.TryGetProperty("identifier_start_column", out var identifierColumnElement)
-                && identifierColumnElement.ValueKind != JsonValueKind.Null
-                    ? identifierColumnElement.GetInt32()
-                    : (int?)null;
-            members.Add(new PartialFamilyMember
-            {
-                SymbolId = symbolId,
-                Path = path,
-                Line = element.GetProperty("line").GetInt32(),
-                StartLine = startLine,
-                StartColumn = identifierStartColumn
-                    ?? ResolveSymbolIdentifierStartColumn(
-                        rawStartColumn,
-                        memberSignature,
-                        memberName,
-                        representative.Kind),
-                EndLine = element.GetProperty("end_line").GetInt32(),
-                Generated = element.GetProperty("generated").GetInt32() != 0,
-                Representative = representative.SymbolId == symbolId
-                    || (representative.SymbolId == null
-                        && string.Equals(representative.Path, path, StringComparison.Ordinal)
-                        && representative.StartLine == startLine),
-            });
-        }
-        return members;
-    }
-
-    private static int? ResolveSymbolIdentifierStartColumn(
-        int? declarationStartColumn,
-        string? signature,
-        string name,
-        string kind)
-    {
-        if (!declarationStartColumn.HasValue || string.IsNullOrWhiteSpace(signature) || string.IsNullOrEmpty(name))
-            return declarationStartColumn;
-
-        var firstLineEnd = signature.IndexOfAny(['\r', '\n']);
-        var firstLine = firstLineEnd >= 0 ? signature[..firstLineEnd] : signature;
-        var callable = kind is "function" or "test.method";
-        var relativeColumn = callable
-            ? LogicalPartialSymbolGrouper.FindCallableNameOffset(firstLine, name)
-            : firstLine.IndexOf(name, StringComparison.Ordinal);
-        if (relativeColumn < 0 && callable)
-            relativeColumn = firstLine.IndexOf(name, StringComparison.Ordinal);
-        return relativeColumn >= 0 ? declarationStartColumn.Value + relativeColumn : declarationStartColumn;
-    }
-
-    private static string GetGenericSymbolRankNamePenaltySql(string nameSql)
-        => $"CASE WHEN lower({nameSql}) IN {GenericSymbolRankNamesSql} THEN {GenericSymbolRankNamePenaltySqlLiteral} ELSE 1.0 END";
-
-    private static string BuildCanonicalDeclarationIdentitySql(string signatureSql)
-        => $"csharp_partial_declaration_identity({signatureSql})";
-
-    private static string BuildLogicalPartialSymbolQuery(string matchingSymbolsSql, SymbolSortMode sortMode)
-    {
-        var orderBy = BuildLogicalPartialSortOrderBy(sortMode);
-        return $@"
-            WITH matching_symbols AS (
-                {matchingSymbolsSql}
-            ),
-            ranked_symbols AS (
-                SELECT matching_symbols.*,
-                       ROW_NUMBER() OVER (
-                           PARTITION BY logical_partial_key
-                           ORDER BY canonical_primary_rank,
-                                    canonical_generated_rank,
-                                    canonical_semantic_score DESC,
-                                    canonical_declaration_identity COLLATE BINARY,
-                                    logical_partial_key COLLATE BINARY,
-                                    path COLLATE BINARY,
-                                    start_line,
-                                    stable_start_column,
-                                    symbol_id
-                       ) AS logical_row_number,
-                       ROW_NUMBER() OVER (
-                           PARTITION BY logical_partial_key
-                           ORDER BY path COLLATE BINARY, start_line, stable_start_column, symbol_id
-                       ) AS family_member_row_number,
-                       COUNT(*) OVER (PARTITION BY logical_partial_key) AS logical_definition_sites
-                FROM matching_symbols
-            ),
-            family_ranked_symbols AS (
-                SELECT ranked_symbols.*,
-                       MAX(CASE WHEN logical_row_number = 1 THEN family_member_row_number END) OVER (
-                           PARTITION BY logical_partial_key
-                       ) AS representative_member_row_number
-                FROM ranked_symbols
-            ),
-            logical_symbols AS (
-                SELECT family_ranked_symbols.*,
-                       MAX(reference_count) OVER (PARTITION BY logical_partial_key) AS logical_reference_count,
-                       MAX(hotspot_score) OVER (PARTITION BY logical_partial_key) AS logical_hotspot_score,
-                       MAX(ranking_reference_score) OVER (PARTITION BY logical_partial_key) AS logical_ranking_reference_score,
-                       MAX(ranking_hotspot_score) OVER (PARTITION BY logical_partial_key) AS logical_ranking_hotspot_score,
-                       MAX(generic_name_penalty) OVER (PARTITION BY logical_partial_key) AS logical_generic_name_penalty,
-                       MAX(structural_rank_penalty) OVER (PARTITION BY logical_partial_key) AS logical_structural_rank_penalty,
-                       MAX(size_lines) OVER (PARTITION BY logical_partial_key) AS logical_size_lines,
-                       MAX(complexity_score) OVER (PARTITION BY logical_partial_key) AS logical_complexity_score,
-                       MIN(exact_name_order) OVER (PARTITION BY logical_partial_key) AS logical_exact_name_order,
-                       MIN(path_bucket) OVER (PARTITION BY logical_partial_key) AS logical_path_bucket,
-                       MIN(visibility_rank) OVER (PARTITION BY logical_partial_key) AS logical_visibility_rank,
-                       MIN(canonical_primary_rank) OVER (PARTITION BY logical_partial_key) AS logical_primary_rank_min,
-                       MAX(canonical_primary_rank) OVER (PARTITION BY logical_partial_key) AS logical_primary_rank_max,
-                       MIN(canonical_generated_rank) OVER (PARTITION BY logical_partial_key) AS logical_generated_rank_min,
-                       MAX(canonical_generated_rank) OVER (PARTITION BY logical_partial_key) AS logical_generated_rank_max,
-                       MIN(canonical_semantic_score) OVER (PARTITION BY logical_partial_key) AS logical_semantic_score_min,
-                       MAX(canonical_semantic_score) OVER (PARTITION BY logical_partial_key) AS logical_semantic_score_max,
-                       MIN(canonical_declaration_identity) OVER (PARTITION BY logical_partial_key) AS logical_declaration_identity_min,
-                       MAX(canonical_declaration_identity) OVER (PARTITION BY logical_partial_key) AS logical_declaration_identity_max,
-                       json_group_array(json_object(
-                           'symbol_id', symbol_id,
-                           'path', path,
-                           'line', line,
-                           'start_line', start_line,
-                           'start_column', start_column,
-                           'end_line', end_line,
-                           'name', name,
-                           'signature', signature,
-                           'identifier_start_column', identifier_start_column,
-                           'generated', canonical_generated_rank
-                       )) FILTER (WHERE
-                           family_member_row_number <= CASE
-                               WHEN representative_member_row_number <= {LogicalPartialSymbolGrouper.FamilyMemberLimit}
-                               THEN {LogicalPartialSymbolGrouper.FamilyMemberLimit}
-                               ELSE {LogicalPartialSymbolGrouper.FamilyMemberLimit - 1}
-                           END
-                           OR logical_row_number = 1
-                       ) OVER (
-                           PARTITION BY logical_partial_key
-                           ORDER BY path COLLATE BINARY, start_line, stable_start_column, symbol_id
-                           ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
-                       ) AS logical_family_members_json
-                FROM family_ranked_symbols
-            )
-            SELECT path, lang, kind, sub_kind, name, line,
-                   start_line, start_column, end_line,
-                   body_start_line, body_end_line, signature,
-                   container_kind, container_name, visibility, return_type,
-                   logical_reference_count, logical_hotspot_score,
-                   logical_ranking_reference_score, logical_ranking_hotspot_score,
-                   logical_generic_name_penalty, logical_structural_rank_penalty,
-                   logical_definition_sites, logical_size_lines, logical_complexity_score,
-                   container_qualified_name, logical_partial_key, symbol_id,
-                   CASE
-                       WHEN logical_primary_rank_min <> logical_primary_rank_max THEN '{LogicalPartialSymbolGrouper.ImplementationBodyReason}'
-                       WHEN logical_generated_rank_min <> logical_generated_rank_max THEN '{LogicalPartialSymbolGrouper.NonGeneratedSourceReason}'
-                       WHEN logical_semantic_score_min <> logical_semantic_score_max THEN '{LogicalPartialSymbolGrouper.SemanticDeclarationReason}'
-                       WHEN logical_declaration_identity_min <> logical_declaration_identity_max THEN '{LogicalPartialSymbolGrouper.CanonicalDeclarationIdentityReason}'
-                       ELSE '{LogicalPartialSymbolGrouper.StableLocationReason}'
-                   END AS representative_reason,
-                   logical_family_members_json,
-                   CASE WHEN logical_definition_sites > {LogicalPartialSymbolGrouper.FamilyMemberLimit} THEN 1 ELSE 0 END AS family_members_truncated,
-                   identifier_start_column
-            FROM logical_symbols
-            WHERE logical_row_number = 1
-            {orderBy}";
-    }
-
-    private static string BuildLogicalPartialSortOrderBy(SymbolSortMode sortMode)
-    {
-        const string stableTieBreakers = "logical_path_bucket, logical_visibility_rank, name, path COLLATE BINARY, line, stable_start_column, symbol_id";
-        return sortMode switch
-        {
-            SymbolSortMode.Hotspot => $"ORDER BY logical_ranking_hotspot_score DESC, logical_ranking_reference_score DESC, logical_hotspot_score DESC, logical_reference_count DESC, logical_size_lines DESC, {stableTieBreakers}",
-            SymbolSortMode.References => $"ORDER BY logical_ranking_reference_score DESC, logical_ranking_hotspot_score DESC, logical_reference_count DESC, logical_hotspot_score DESC, logical_size_lines DESC, {stableTieBreakers}",
-            SymbolSortMode.Size => $"ORDER BY logical_size_lines DESC, logical_ranking_reference_score DESC, logical_ranking_hotspot_score DESC, logical_reference_count DESC, {stableTieBreakers}",
-            SymbolSortMode.Complexity => $"ORDER BY logical_complexity_score DESC, logical_ranking_hotspot_score DESC, logical_ranking_reference_score DESC, logical_reference_count DESC, logical_size_lines DESC, {stableTieBreakers}",
-            SymbolSortMode.Path => "ORDER BY path COLLATE BINARY, line, stable_start_column, name, symbol_id",
-            _ => $"ORDER BY logical_exact_name_order, {stableTieBreakers}",
-        };
-    }
-
-    private string BuildSymbolSortOrderBy(
-        SymbolSortMode sortMode,
-        string exactNameOrderSql,
-        string referenceCountSql,
-        string rawHotspotScoreSql,
-        string rankingReferenceScoreSql,
-        string rankingHotspotScoreSql,
-        string sizeLinesSql,
-        string complexityScoreSql,
-        string startColumnSql)
-    {
-        var stableTieBreakers = $"{PathBucketOrder}, {VisibilityOrder}, s.name, f.path, s.line, {startColumnSql} ASC, s.id ASC";
-        return sortMode switch
-        {
-            SymbolSortMode.Hotspot => $" ORDER BY {rankingHotspotScoreSql} DESC, {rankingReferenceScoreSql} DESC, {rawHotspotScoreSql} DESC, {referenceCountSql} DESC, {sizeLinesSql} DESC, {stableTieBreakers}",
-            SymbolSortMode.References => $" ORDER BY {rankingReferenceScoreSql} DESC, {rankingHotspotScoreSql} DESC, {referenceCountSql} DESC, {rawHotspotScoreSql} DESC, {sizeLinesSql} DESC, {stableTieBreakers}",
-            SymbolSortMode.Size => $" ORDER BY {sizeLinesSql} DESC, {rankingReferenceScoreSql} DESC, {rankingHotspotScoreSql} DESC, {referenceCountSql} DESC, {stableTieBreakers}",
-            SymbolSortMode.Complexity => $" ORDER BY {complexityScoreSql} DESC, {rankingHotspotScoreSql} DESC, {rankingReferenceScoreSql} DESC, {referenceCountSql} DESC, {sizeLinesSql} DESC, {stableTieBreakers}",
-            SymbolSortMode.Path => $" ORDER BY f.path, s.line, {startColumnSql} ASC, s.name, s.id ASC",
-            _ => $" ORDER BY {exactNameOrderSql}, {stableTieBreakers}",
-        };
-    }
-
     private static string? NormalizeSymbolSearchQuery(string? query, string? lang, bool exact = false)
         => SymbolSearchQueryNormalizer.Normalize(query, lang, exact);
 
@@ -1182,5 +112,4 @@ private static bool ShouldPreserveRustQualifiedExactQuery(string? query, string?
 
     private static (string? QualifiedPath, string? ContainerPath, string? LeafName) NormalizeRustQualifiedExactQueryParts(string query)
         => SymbolSearchQueryNormalizer.NormalizeRustQualifiedExactQueryParts(query);
-
 }

From 852aad60171f933c1ddd08c597aa3098357086a3 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 09:38:09 +0900
Subject: [PATCH 13/45] Decompose cross-language call reference extraction

---
 ...eExtractor.CoreCallAdditionalReferences.cs | 261 +++++++++
 ...ferenceExtractor.CoreCallClassification.cs | 320 ++--------
 .../ReferenceExtractor.CoreCallDispatch.cs    | 148 +++++
 .../ReferenceExtractor.CoreCallKinds.cs       | 193 ++++++
 .../ReferenceExtractor.CoreCallReferences.cs  | 552 ++++--------------
 .../ReferenceExtractor.CoreCallScanning.cs    | 242 ++++++++
 ...ReferenceExtractor.CoreCallSuppressions.cs | 149 +++++
 .../ReferenceExtractor.CoreReferencePhases.cs |   4 +-
 8 files changed, 1151 insertions(+), 718 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallAdditionalReferences.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallDispatch.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallKinds.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallScanning.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallSuppressions.cs

diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallAdditionalReferences.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallAdditionalReferences.cs
new file mode 100644
index 000000000..7212a9fab
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallAdditionalReferences.cs
@@ -0,0 +1,261 @@
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitRubyOrPerlCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language == "ruby")
+        {
+            var matchedCallIndices = GetOrCreateMatchedCallIndices(ref state);
+            var addCallLikeReference = GetOrCreateCallLikeReferenceEmitter(
+                in call,
+                ref state);
+            RubyReferenceExtractor.EmitAdditionalCallReferences(
+                line.PreparedLine,
+                line.OriginalLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall,
+                matchedCallIndices,
+                addCallLikeReference);
+        }
+        else if (line.Language is "perl" or "ambiguous_pl")
+        {
+            PerlReferenceExtractor.EmitAdditionalReferences(
+                line.Language == "ambiguous_pl"
+                    ? state.CallScanLine
+                    : line.PreparedLine,
+                line.OriginalLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+                emitArrowCallReferences: line.Language != "ambiguous_pl"
+                    || call.DynamicDeclarativeState?.HasPrologContainer(
+                        line.LineNumber) != true);
+        }
+    }
+
+    private static void EmitDynamicDeclarativeCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        if (call.DynamicDeclarativeState == null)
+            return;
+
+        ref readonly var line = ref call.Line;
+        DynamicDeclarativeReferenceExtractor.EmitAdditionalReferences(
+            line.Language,
+            state.CallScanLine,
+            call.ReferenceStructuralLine,
+            call.DynamicDeclarativeState,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall,
+            GetOrCreateCallLikeReferenceEmitter(in call, ref state));
+    }
+
+    private static void EmitGoCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language != "go")
+            return;
+
+        LanguageReferenceExtractionSupport.EmitGoBranchLabelReferences(
+            line.PreparedLine,
+            GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+            line.References);
+    }
+
+    private static void EmitSwiftOrKotlinCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language == "swift")
+        {
+            SwiftReferenceExtractor.EmitTrailingClosureReferences(
+                line.PreparedLine,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+                line.References);
+        }
+        else if (line.Language == "kotlin")
+        {
+            var addCallLikeReference = GetOrCreateCallLikeReferenceEmitter(
+                in call,
+                ref state);
+            KotlinReferenceExtractor.EmitInfixCallReferences(
+                line.PreparedLine,
+                line.OriginalLine,
+                call.KotlinInfixFunctionNames!,
+                addCallLikeReference);
+            KotlinReferenceExtractor.EmitTrailingLambdaReferences(
+                line.PreparedLine,
+                addCallLikeReference,
+                line.References);
+        }
+    }
+
+    private static void EmitFSharpCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language != "fsharp")
+            return;
+
+        FSharpReferenceExtractor.EmitAdditionalCallReferences(
+            line.PreparedLine,
+            GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+            line.References);
+    }
+
+    private static void EmitScalaOrGradleCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language == "scala")
+        {
+            var addCallLikeReference = GetOrCreateCallLikeReferenceEmitter(
+                in call,
+                ref state);
+            ScalaReferenceExtractor.EmitTrailingBlockCallReferences(
+                line.PreparedLine,
+                addCallLikeReference,
+                line.References);
+            ScalaReferenceExtractor.EmitAdditionalReferences(
+                line.PreparedLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall,
+                addCallLikeReference);
+        }
+        else if (line.Language == "gradle")
+        {
+            GradleReferenceExtractor.EmitDslCallReferences(
+                line.PreparedLine,
+                CreateGradleDslReferenceEmitter(in line),
+                line.References);
+        }
+    }
+
+    private static void EmitSecondaryLanguageCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language == "fortran")
+        {
+            FortranReferenceExtractor.EmitAdditionalCallReferences(
+                line.PreparedLine,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state));
+        }
+        else if (line.Language == "pascal")
+        {
+            PascalReferenceExtractor.EmitAdditionalCallReferences(
+                line.PreparedLine,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+                line.DefinitionNames);
+        }
+        else if (line.Language == "objc")
+        {
+            ObjectiveCReferenceExtractor.EmitAdditionalCallReferences(
+                line.PreparedLine,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall);
+        }
+        else if (line.Language == "haskell")
+        {
+            HaskellReferenceExtractor.EmitAdditionalCallReferences(
+                line.PreparedLine,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+                line.DefinitionNames);
+        }
+        else if (line.Language == "elixir")
+        {
+            ElixirReferenceExtractor.EmitAdditionalCallReferences(
+                line.PreparedLine,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+                line.DefinitionNames);
+        }
+        else if (line.Language == "lua")
+        {
+            LuaReferenceExtractor.EmitAdditionalCallReferences(
+                line.PreparedLine,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall,
+                line.DefinitionNames);
+        }
+        else if (line.Language == "smalltalk")
+        {
+            SmalltalkReferenceExtractor.EmitAdditionalCallReferences(
+                line.PreparedLine,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+                line.DefinitionNames);
+        }
+        else if (line.Language == "vb")
+        {
+            LanguageReferenceExtractionSupport.EmitAdditionalCallReferences(
+                "vb",
+                line.PreparedLine,
+                line.OriginalLine,
+                GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall,
+                line.DefinitionNames);
+        }
+    }
+
+    private static void EmitRustPostCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language != "rust")
+            return;
+
+        RustReferenceExtractor.EmitAdditionalCallReferences(
+            line.PreparedLine,
+            GetOrCreateCallLikeReferenceEmitter(in call, ref state));
+        RustReferenceExtractor.EmitAttributeReferences(
+            line.PreparedLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.Container);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallClassification.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallClassification.cs
index a32283f95..dcb77e8fe 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallClassification.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallClassification.cs
@@ -5,217 +5,47 @@ namespace CodeIndex.Indexer;
 public static partial class ReferenceExtractor
 {
     private static bool TryAddCoreCallLikeReference(
-        CoreCallReferenceContext call,
+        in CoreCallReferenceContext call,
         string name,
         int callIndex,
+        bool isScientificNativeLanguage,
         string? targetQualifier = null)
     {
-        var line = call.Line;
-        var normalizedName =
-            line.Language == "fsharp"
-            && FSharpReferenceExtractor.IsOperatorCallName(name)
-                ? $"operator {name}"
-                : line.Language == "rust"
-                    ? RustReferenceExtractor.NormalizeIdentifier(name)
-                    : NormalizeAtPrefixedIdentifier(name);
-
-        // In tuple-return declarations such as `private static (int Value, string Error)
-        // Resolve(...)`, CallRegex sees the modifier token as `static(`. It is a C# keyword,
-        // never a callable identifier, so suppress the phantom edge before graph ingestion.
-        // `private static (int Value, string Error) Resolve(...)` のような tuple return 宣言では
-        // CallRegex が modifier を `static(` と誤認する。C# keyword は呼び出し対象にならないため、
-        // graph に入る前に phantom edge を除外する。
-        if (line.Language == "csharp" && name == "static")
-            return false;
-
-        if (line.Language == "rust"
-            && RustReferenceExtractor.IsFunctionDeclarationCallSite(
-                line.PreparedLine,
-                callIndex))
-        {
-            return false;
-        }
-        if (line.Language == "rust"
-            && RustReferenceExtractor.IsDeriveAttributeCallSite(
-                line.PreparedLine,
+        ref readonly var line = ref call.Line;
+        var normalizedName = NormalizeCoreCallName(
+            line.Language,
+            name);
+        if (ShouldSuppressCoreCallCandidate(
+                in call,
+                name,
                 normalizedName,
                 callIndex))
         {
             return false;
         }
-        if (line.Language == "wgsl" && name.StartsWith('@'))
-            return false;
-        if (line.Language == "kotlin"
-            && KotlinReferenceExtractor.IsInfixFunctionDeclarationSite(
-                line.PreparedLine,
-                callIndex))
-        {
-            return false;
-        }
-
-        // Suppress the same-line Java ctor declarator's self-call. CallRegex matches
-        // `CtorName(` at the declarator once per same-line ctor, but it is a declaration
-        // site — not a call — so attributing it to `class:CtorName` produces a phantom
-        // `CtorName|call|class|CtorName` edge. `line.DefinitionNames` does not cover this
-        // because same-line ctors do not appear in the symbol table.
-        // 同一行 ctor の宣言子 `CtorName(` は呼び出しではないため CallRegex の対象から除外する。
-        if (call.JavaSameLineCtor != null
-            && callIndex == call.JavaSameLineCtor.Value.NameIndex
-            && string.Equals(
-                normalizedName,
-                call.JavaSameLineCtor.Value.Synthetic.Name,
-                StringComparison.Ordinal))
-        {
-            return false;
-        }
 
-        // C# positional patterns such as `case Point(var x, var y):` are type-pattern
-        // heads, not calls. `CallRegex` still sees `Point(` and would otherwise emit a
-        // phantom `call` edge alongside the real `type_reference`.
-        // C# の positional pattern (`case Point(var x, var y):`) は型パターンの先頭であり、
-        // 呼び出しではない。`CallRegex` が `Point(` を拾ってしまうため、そのままだと
-        // 本物の `type_reference` に加えて phantom な `call` エッジが出る。
-        if (line.Language == "csharp"
-            && CSharpReferenceExtractor.IsPatternHeadCallSite(
-                line.PreparedLines,
-                line.LineIndex,
-                line.PreparedLine,
-                callIndex))
-        {
-            return false;
-        }
-        if (line.Language == "typescript"
-            && TypeScriptReferenceExtractor.IsSatisfiesTypeOperand(
-                line.PreparedLine,
-                callIndex))
-        {
-            return false;
-        }
-        if (call.Definitions.ShouldSuppressDefinitionCall(
-                normalizedName,
+        var callContainer = line.ResolveContainerForCall(callIndex);
+        if (TryHandleCSharpValueReceiverCall(
+                in call,
                 name,
-                callIndex))
+                normalizedName,
+                callIndex,
+                callContainer))
         {
             return false;
         }
 
-        var callContainer = line.ResolveContainerForCall(callIndex);
-        if (line.Language == "csharp"
-            && callIndex + name.Length < line.PreparedLine.Length
-            && line.PreparedLine.AsSpan(callIndex + name.Length)
-                .TrimStart()
-                .StartsWith(".", StringComparison.Ordinal))
-        {
-            var receiverLookups = call.Lookups.GetCSharpValueReceiverLookups();
-            if (HasCSharpValueReceiverConflict(
-                    normalizedName,
-                    normalizedName,
-                    line.LineNumber,
-                    callIndex,
-                    callContainer,
-                    receiverLookups.ByContainingType,
-                    receiverLookups.ByFunctionStartLine))
-            {
-                var containingType =
-                    GetContainingTypeQualifiedName(callContainer);
-                if (containingType != null
-                    && receiverLookups.ByContainingType.TryGetValue(
-                        containingType,
-                        out var receiverNames)
-                    && (receiverNames.InstanceNames.Contains(normalizedName)
-                        || receiverNames.StaticNames.Contains(normalizedName))
-                    && call.Lookups.HasCSharpFieldOrPropertyMember(
-                        containingType,
-                        normalizedName))
-                {
-                    line.References.RemoveAll(reference =>
-                        reference.FileId == line.FileId
-                        && reference.Line == line.LineNumber
-                        && reference.Column == callIndex + 1
-                        && reference.ReferenceKind == "type_reference"
-                        && string.Equals(
-                            reference.SymbolName,
-                            normalizedName,
-                            StringComparison.Ordinal));
-                    AddReference(
-                        line.References,
-                        line.Seen,
-                        line.FileId,
-                        $"{containingType}.{normalizedName}",
-                        callIndex,
-                        "reference",
-                        line.Context,
-                        line.LineNumber,
-                        callContainer,
-                        line.Language,
-                        sourceLength: name.Length);
-                }
-
-                return false;
-            }
-        }
-        if (IsConstructorCallName(
-                line.Language,
-                line.PreparedLine,
-                callIndex))
-        {
-            AddReference(
-                line.References,
-                line.Seen,
-                line.FileId,
-                normalizedName,
-                callIndex,
-                "instantiate",
-                line.Context,
-                line.LineNumber,
-                callContainer,
-                line.Language,
-                targetQualifier,
-                name.Length);
-            return true;
-        }
-        if (line.Language == "rust"
-            && RustReferenceExtractor.IsLikelyInstantiationCallName(
+        if (TryAddCoreInstantiationReference(
+                in call,
                 name,
                 normalizedName,
-                line.PreparedLine,
-                callIndex))
-        {
-            AddReference(
-                line.References,
-                line.Seen,
-                line.FileId,
-                normalizedName,
                 callIndex,
-                "instantiate",
-                line.Context,
-                line.LineNumber,
                 callContainer,
-                line.Language,
-                sourceLength: name.Length);
-            return true;
-        }
-        if (line.Language == "python"
-            && TryGetKnownPythonTypeCall(
-                call,
-                normalizedName,
-                callIndex,
-                out var pythonTypeName))
+                targetQualifier))
         {
-            AddReference(
-                line.References,
-                line.Seen,
-                line.FileId,
-                pythonTypeName,
-                callIndex,
-                "instantiate",
-                line.Context,
-                line.LineNumber,
-                callContainer,
-                line.Language,
-                sourceLength: name.Length);
             return true;
         }
+
         if (IsIgnoredCallName(line.Language, name)
             && !(line.Language == "scala"
                 && string.Equals(name, "foreach", StringComparison.Ordinal)))
@@ -223,113 +53,55 @@ private static bool TryAddCoreCallLikeReference(
             return false;
         }
 
-        var insideCSharpAttributeRange = call.CSharpAttributeRanges != null
-            && IsInsideCSharpAttributeRange(
-                call.CSharpAttributeRanges,
-                callIndex);
-        var metadataKind = TryClassifyMetadataReference(
-            line.Language,
-            line.PreparedLine,
-            callIndex,
-            insideCSharpAttributeRange);
-        if (metadataKind != null)
-        {
-            AddReference(
-                line.References,
-                line.Seen,
-                line.FileId,
+        if (TryAddCoreMetadataReference(
+                in call,
+                name,
                 normalizedName,
                 callIndex,
-                metadataKind,
-                line.Context,
-                line.LineNumber,
-                callContainer,
-                line.Language,
-                sourceLength: name.Length);
-            if (line.Language == "csharp"
-                && metadataKind == "attribute"
-                && CSharpReferenceExtractor.TryGetCallerInfoAttributeTypeName(
-                    name,
-                    line.PreparedLine,
-                    callIndex) is { } callerInfoAttributeTypeName)
-            {
-                AddReference(
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    callerInfoAttributeTypeName,
-                    callIndex,
-                    "type_reference",
-                    line.Context,
-                    line.LineNumber,
-                    callContainer,
-                    line.Language,
-                    sourceLength: name.Length);
-            }
-            return true;
-        }
-
-        if (line.Language == "kotlin"
-            && KotlinReferenceExtractor.IsConstructorCallName(
-                normalizedName,
-                call.KotlinConstructorTypeNames!))
+                callContainer))
         {
-            AddReference(
-                line.References,
-                line.Seen,
-                line.FileId,
-                normalizedName,
-                callIndex,
-                "instantiate",
-                line.Context,
-                line.LineNumber,
-                callContainer,
-                sourceLength: name.Length);
             return true;
         }
 
-        if (line.Language is "javascript" or "typescript"
-            && SymbolExtractor.IsJavaScriptTypeScriptReactHookName(
-                normalizedName))
-        {
-            AddReference(
-                line.References,
-                line.Seen,
-                line.FileId,
+        if (TryAddSpecialCoreCallReference(
+                in call,
+                name,
                 normalizedName,
                 callIndex,
-                "consumes_hook",
-                line.Context,
-                line.LineNumber,
-                callContainer,
-                sourceLength: name.Length);
+                callContainer))
+        {
             return true;
         }
 
-        AddReference(
-            line.References,
-            line.Seen,
-            line.FileId,
+        AddCoreClassifiedReference(
+            in call,
             normalizedName,
             callIndex,
             "call",
-            line.Context,
-            line.LineNumber,
             callContainer,
-            ScientificNativeReferenceExtractor.Supports(line.Language)
-                ? line.Language
-                : null,
-            targetQualifier: targetQualifier,
-            sourceLength: name.Length);
+            isScientificNativeLanguage ? line.Language : null,
+            targetQualifier,
+            name.Length);
         return true;
     }
 
+    private static string NormalizeCoreCallName(
+        string language,
+        string name) =>
+        language == "fsharp"
+            && FSharpReferenceExtractor.IsOperatorCallName(name)
+                ? $"operator {name}"
+                : language == "rust"
+                    ? RustReferenceExtractor.NormalizeIdentifier(name)
+                    : NormalizeAtPrefixedIdentifier(name);
+
     private static bool TryGetKnownPythonTypeCall(
-        CoreCallReferenceContext call,
+        in CoreCallReferenceContext call,
         string candidate,
         int callIndex,
         out string canonicalName)
     {
+        ref readonly var line = ref call.Line;
         canonicalName = candidate;
         var separator = candidate.LastIndexOf('.');
         var leaf = separator >= 0 ? candidate[(separator + 1)..] : candidate;
@@ -341,7 +113,7 @@ private static bool TryGetKnownPythonTypeCall(
 
         return PythonImportBindingResolver.TryResolveImportedTypeCall(
             candidate,
-            call.Line.PreparedLine,
+            line.PreparedLine,
             callIndex,
             call.Lookups.GetPythonImportedTypeCallLookup(),
             out canonicalName);
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallDispatch.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallDispatch.cs
new file mode 100644
index 000000000..28a20c2c7
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallDispatch.cs
@@ -0,0 +1,148 @@
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitCoreCallPrelude(
+        in CoreCallReferenceContext call)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language is "javascript" or "typescript")
+        {
+            JavaScriptReferenceExtractor.EmitOptionalMemberChainReferences(
+                line.PreparedLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall);
+
+            JavaScriptReferenceExtractor.EmitDiscriminantStringGuardReferences(
+                call.ReferenceStructuralLine,
+                line.OriginalLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall);
+
+            JavaScriptReferenceExtractor.EmitParenlessConstructorReferences(
+                line.PreparedLine,
+                line.PreparedLines,
+                line.LineIndex,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall);
+        }
+
+        if (line.Language == "batch")
+        {
+            BatchReferenceExtractor.EmitJumpTargetReferences(
+                line.OriginalLine,
+                line.PreparedLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall);
+        }
+
+        if (line.Language == "assembly")
+        {
+            AssemblyReferenceExtractor.EmitInstructionTargetReferences(
+                line.OriginalLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall);
+        }
+    }
+
+    private static void EmitCoreLanguageCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        switch (line.Language)
+        {
+            case "commonlisp":
+            case "racket":
+                EmitLispCallReferences(in call);
+                break;
+            case "powershell":
+                EmitPowerShellCallReferences(in call, ref state);
+                break;
+            case "shell":
+                EmitShellCallReferences(in call, ref state);
+                break;
+            case "assembly":
+                // Assembly references are operand-driven, not `name(...)` call syntax.
+                break;
+            default:
+                EmitGeneralCoreCallReferences(in call, ref state);
+                break;
+        }
+    }
+
+    private static void EmitLispCallReferences(
+        in CoreCallReferenceContext call)
+    {
+        ref readonly var line = ref call.Line;
+        LispReferenceExtractor.EmitReferences(
+            line.Language,
+            line.PreparedLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall,
+            line.DefinitionNames);
+    }
+
+    private static void EmitPowerShellCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        PowerShellReferenceExtractor.EmitCallReferences(
+            line.PreparedLine,
+            GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+            line.References);
+        if (ReferenceLimitReached(line.References))
+            return;
+
+        PowerShellReferenceExtractor.EmitSplatParameterReferences(
+            line.PreparedLine,
+            call.Lookups.GetPowerShellSplatAssignments,
+            line.LineNumber,
+            CreatePowerShellParameterReferenceEmitter(in line),
+            line.References);
+    }
+
+    private static void EmitShellCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        ShellReferenceExtractor.EmitReferences(
+            line.PreparedLine,
+            line.OriginalLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            call.ShellCallableNames,
+            call.ShellGlobalAliasNames,
+            line.ResolveContainerForCall,
+            GetOrCreateCallLikeReferenceEmitter(in call, ref state));
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallKinds.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallKinds.cs
new file mode 100644
index 000000000..92bf5b09d
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallKinds.cs
@@ -0,0 +1,193 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static bool TryAddCoreInstantiationReference(
+        in CoreCallReferenceContext call,
+        string name,
+        string normalizedName,
+        int callIndex,
+        SymbolRecord? callContainer,
+        string? targetQualifier)
+    {
+        ref readonly var line = ref call.Line;
+        if (IsConstructorCallName(
+                line.Language,
+                line.PreparedLine,
+                callIndex))
+        {
+            AddCoreClassifiedReference(
+                in call,
+                normalizedName,
+                callIndex,
+                "instantiate",
+                callContainer,
+                line.Language,
+                targetQualifier,
+                name.Length);
+            return true;
+        }
+
+        if (line.Language == "rust"
+            && RustReferenceExtractor.IsLikelyInstantiationCallName(
+                name,
+                normalizedName,
+                line.PreparedLine,
+                callIndex))
+        {
+            AddCoreClassifiedReference(
+                in call,
+                normalizedName,
+                callIndex,
+                "instantiate",
+                callContainer,
+                line.Language,
+                targetQualifier: null,
+                name.Length);
+            return true;
+        }
+
+        if (line.Language == "python"
+            && TryGetKnownPythonTypeCall(
+                in call,
+                normalizedName,
+                callIndex,
+                out var pythonTypeName))
+        {
+            AddCoreClassifiedReference(
+                in call,
+                pythonTypeName,
+                callIndex,
+                "instantiate",
+                callContainer,
+                line.Language,
+                targetQualifier: null,
+                name.Length);
+            return true;
+        }
+
+        return false;
+    }
+
+    private static bool TryAddCoreMetadataReference(
+        in CoreCallReferenceContext call,
+        string name,
+        string normalizedName,
+        int callIndex,
+        SymbolRecord? callContainer)
+    {
+        ref readonly var line = ref call.Line;
+        var insideCSharpAttributeRange = call.CSharpAttributeRanges != null
+            && IsInsideCSharpAttributeRange(
+                call.CSharpAttributeRanges,
+                callIndex);
+        var metadataKind = TryClassifyMetadataReference(
+            line.Language,
+            line.PreparedLine,
+            callIndex,
+            insideCSharpAttributeRange);
+        if (metadataKind == null)
+            return false;
+
+        AddCoreClassifiedReference(
+            in call,
+            normalizedName,
+            callIndex,
+            metadataKind,
+            callContainer,
+            line.Language,
+            targetQualifier: null,
+            name.Length);
+        if (line.Language == "csharp"
+            && metadataKind == "attribute"
+            && CSharpReferenceExtractor.TryGetCallerInfoAttributeTypeName(
+                name,
+                line.PreparedLine,
+                callIndex) is { } callerInfoAttributeTypeName)
+        {
+            AddCoreClassifiedReference(
+                in call,
+                callerInfoAttributeTypeName,
+                callIndex,
+                "type_reference",
+                callContainer,
+                line.Language,
+                targetQualifier: null,
+                name.Length);
+        }
+
+        return true;
+    }
+
+    private static bool TryAddSpecialCoreCallReference(
+        in CoreCallReferenceContext call,
+        string name,
+        string normalizedName,
+        int callIndex,
+        SymbolRecord? callContainer)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language == "kotlin"
+            && KotlinReferenceExtractor.IsConstructorCallName(
+                normalizedName,
+                call.KotlinConstructorTypeNames!))
+        {
+            AddCoreClassifiedReference(
+                in call,
+                normalizedName,
+                callIndex,
+                "instantiate",
+                callContainer,
+                referenceLanguage: null,
+                targetQualifier: null,
+                name.Length);
+            return true;
+        }
+
+        if (line.Language is "javascript" or "typescript"
+            && SymbolExtractor.IsJavaScriptTypeScriptReactHookName(
+                normalizedName))
+        {
+            AddCoreClassifiedReference(
+                in call,
+                normalizedName,
+                callIndex,
+                "consumes_hook",
+                callContainer,
+                referenceLanguage: null,
+                targetQualifier: null,
+                name.Length);
+            return true;
+        }
+
+        return false;
+    }
+
+    private static void AddCoreClassifiedReference(
+        in CoreCallReferenceContext call,
+        string symbolName,
+        int callIndex,
+        string referenceKind,
+        SymbolRecord? callContainer,
+        string? referenceLanguage,
+        string? targetQualifier,
+        int sourceLength)
+    {
+        ref readonly var line = ref call.Line;
+        AddReference(
+            line.References,
+            line.Seen,
+            line.FileId,
+            symbolName,
+            callIndex,
+            referenceKind,
+            line.Context,
+            line.LineNumber,
+            callContainer,
+            referenceLanguage,
+            targetQualifier,
+            sourceLength);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallReferences.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallReferences.cs
index 8d5b90f73..100101832 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallReferences.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallReferences.cs
@@ -1,4 +1,3 @@
-using System.Text.RegularExpressions;
 using CodeIndex.Models;
 
 namespace CodeIndex.Indexer;
@@ -6,7 +5,6 @@ namespace CodeIndex.Indexer;
 public static partial class ReferenceExtractor
 {
     private readonly record struct CoreCallReferenceContext(
-        CoreReferenceLineContext Line,
         CoreExtractionLookups Lookups,
         (SymbolRecord Synthetic, int NameIndex, int OpenBraceIndex, int CloseBraceIndex)? JavaSameLineCtor,
         List<(int start, int end)>? CSharpAttributeRanges,
@@ -20,18 +18,68 @@ private readonly record struct CoreCallReferenceContext(
         Action<ReferenceExtractionDiagnostic>? ReportDiagnostic,
         HashSet<int>? SqlSuppressedCallIndices,
         HashSet<(int LineNumber, int ColumnIndex)>? SqlWindowFunctionCallSiteSuppressions,
-        CoreLineDefinitionState Definitions);
+        CoreLineDefinitionState Definitions)
+    {
+        public readonly CoreReferenceLineContext Line;
+
+        public CoreCallReferenceContext(
+            in CoreReferenceLineContext line,
+            CoreExtractionLookups lookups,
+            (SymbolRecord Synthetic, int NameIndex, int OpenBraceIndex, int CloseBraceIndex)? javaSameLineCtor,
+            List<(int start, int end)>? cSharpAttributeRanges,
+            HashSet<string>? kotlinConstructorTypeNames,
+            HashSet<string>? kotlinInfixFunctionNames,
+            HashSet<string>? shellCallableNames,
+            HashSet<string>? shellGlobalAliasNames,
+            DynamicDeclarativeReferenceExtractor.ExtractionState? dynamicDeclarativeState,
+            string referenceStructuralLine,
+            int scientificNativeDependencyLimit,
+            Action<ReferenceExtractionDiagnostic>? reportDiagnostic,
+            HashSet<int>? sqlSuppressedCallIndices,
+            HashSet<(int LineNumber, int ColumnIndex)>? sqlWindowFunctionCallSiteSuppressions,
+            CoreLineDefinitionState definitions)
+            : this(
+                lookups,
+                javaSameLineCtor,
+                cSharpAttributeRanges,
+                kotlinConstructorTypeNames,
+                kotlinInfixFunctionNames,
+                shellCallableNames,
+                shellGlobalAliasNames,
+                dynamicDeclarativeState,
+                referenceStructuralLine,
+                scientificNativeDependencyLimit,
+                reportDiagnostic,
+                sqlSuppressedCallIndices,
+                sqlWindowFunctionCallSiteSuppressions,
+                definitions)
+        {
+            Line = line;
+        }
+    }
+
+    private struct CoreCallEmissionState(
+        string callScanLine,
+        bool isScientificNativeLanguage)
+    {
+        public string CallScanLine { get; } = callScanLine;
+        public bool IsScientificNativeLanguage { get; } = isScientificNativeLanguage;
+        public Action<string, int>? CallLikeReferenceEmitter { get; set; }
+        public HashSet<int>? MatchedCallIndices { get; set; }
+    }
 
     private static Action<string, int> CreateCallLikeReferenceEmitter(
-        CoreCallReferenceContext call) =>
+        CoreCallReferenceContext call,
+        bool isScientificNativeLanguage) =>
         (name, callIndex) =>
         {
-            var line = call.Line;
+            ref readonly var line = ref call.Line;
             _ = TryAddCoreCallLikeReference(
-                call,
+                in call,
                 name,
                 callIndex,
-                ScientificNativeReferenceExtractor.Supports(line.Language)
+                isScientificNativeLanguage,
+                isScientificNativeLanguage
                     ? ScientificNativeReferenceExtractor.GetParenthesizedCallTargetQualifier(
                         line.Language,
                         line.PreparedLine,
@@ -39,471 +87,91 @@ private static Action<string, int> CreateCallLikeReferenceEmitter(
                     : null);
         };
 
+    private static Action<string, int> GetOrCreateCallLikeReferenceEmitter(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state) =>
+        state.CallLikeReferenceEmitter ??=
+            CreateCallLikeReferenceEmitter(call, state.IsScientificNativeLanguage);
+
+    private static HashSet<int> GetOrCreateMatchedCallIndices(
+        ref CoreCallEmissionState state) =>
+        state.MatchedCallIndices ??= [];
+
     private static Action<string, int> CreatePowerShellParameterReferenceEmitter(
-        CoreReferenceLineContext line) =>
-        (name, callIndex) =>
+        in CoreReferenceLineContext line)
+    {
+        var references = line.References;
+        var seen = line.Seen;
+        var fileId = line.FileId;
+        var context = line.Context;
+        var lineNumber = line.LineNumber;
+        var language = line.Language;
+        var resolveContainerForCall = line.ResolveContainerForCall;
+        return (name, callIndex) =>
         {
-            var callContainer = line.ResolveContainerForCall(callIndex);
+            var callContainer = resolveContainerForCall(callIndex);
             AddReference(
-                line.References,
-                line.Seen,
-                line.FileId,
+                references,
+                seen,
+                fileId,
                 name,
                 callIndex,
                 "parameter",
-                line.Context,
-                line.LineNumber,
+                context,
+                lineNumber,
                 callContainer,
-                line.Language,
+                language,
                 sourceLength: name.Length);
         };
+    }
 
     private static Action<string, int> CreateGradleDslReferenceEmitter(
-        CoreReferenceLineContext line) =>
-        (name, callIndex) =>
+        in CoreReferenceLineContext line)
+    {
+        var references = line.References;
+        var seen = line.Seen;
+        var fileId = line.FileId;
+        var context = line.Context;
+        var lineNumber = line.LineNumber;
+        var language = line.Language;
+        var resolveContainerForCall = line.ResolveContainerForCall;
+        return (name, callIndex) =>
         {
             var normalizedName = NormalizeAtPrefixedIdentifier(name);
-            var callContainer = line.ResolveContainerForCall(callIndex);
+            var callContainer = resolveContainerForCall(callIndex);
             AddReference(
-                line.References,
-                line.Seen,
-                line.FileId,
+                references,
+                seen,
+                fileId,
                 normalizedName,
                 callIndex,
                 "call",
-                line.Context,
-                line.LineNumber,
+                context,
+                lineNumber,
                 callContainer,
-                line.Language,
+                language,
                 sourceLength: name.Length);
         };
+    }
 
-    private static void EmitCoreCallReferences(CoreCallReferenceContext call)
+    private static void EmitCoreCallReferences(
+        in CoreCallReferenceContext call)
     {
-        var line = call.Line;
-        Action<string, int>? addCallLikeReference = null;
-        if (line.Language is "javascript" or "typescript")
-        {
-            JavaScriptReferenceExtractor.EmitOptionalMemberChainReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-
-            JavaScriptReferenceExtractor.EmitDiscriminantStringGuardReferences(
-                call.ReferenceStructuralLine,
-                line.OriginalLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
+        ref readonly var line = ref call.Line;
+        EmitCoreCallPrelude(in call);
 
-            JavaScriptReferenceExtractor.EmitParenlessConstructorReferences(
-                line.PreparedLine,
-                line.PreparedLines,
-                line.LineIndex,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-        }
-
-        if (line.Language is "batch")
-            BatchReferenceExtractor.EmitJumpTargetReferences(
-                line.OriginalLine,
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-
-        if (line.Language is "assembly")
-            AssemblyReferenceExtractor.EmitInstructionTargetReferences(
-                line.OriginalLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-
-        HashSet<int>? matchedCallIndices = null;
         var callScanLine = call.DynamicDeclarativeState?.GetCallScanLine(
             line.Language,
             line.LineNumber,
             line.PreparedLine) ?? line.PreparedLine;
-
-        if (line.Language is "commonlisp" or "racket")
-        {
-            LispReferenceExtractor.EmitReferences(
-                line.Language,
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall,
-                line.DefinitionNames);
-        }
-        else if (line.Language is "powershell")
-        {
-            PowerShellReferenceExtractor.EmitCallReferences(
-                line.PreparedLine,
-                addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                line.References);
-            if (!ReferenceLimitReached(line.References))
-            {
-                PowerShellReferenceExtractor.EmitSplatParameterReferences(
-                    line.PreparedLine,
-                    call.Lookups.GetPowerShellSplatAssignments,
-                    line.LineNumber,
-                    CreatePowerShellParameterReferenceEmitter(line),
-                    line.References);
-            }
-        }
-        else if (line.Language is "shell")
-        {
-            ShellReferenceExtractor.EmitReferences(
-                line.PreparedLine,
-                line.OriginalLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                call.ShellCallableNames,
-                call.ShellGlobalAliasNames,
-                line.ResolveContainerForCall,
-                addCallLikeReference ??= CreateCallLikeReferenceEmitter(call));
-        }
-        else if (line.Language is "assembly")
-        {
-            // Assembly line.References are operand-driven, not `name(...)` call syntax.
-        }
-        else
-        {
-            IReadOnlyList<ScientificNativeReferenceExtractor.DTemplateArgumentCallSpan>?
-                dTemplateArgumentCallSpans = null;
-            if (ScientificNativeReferenceExtractor.Supports(line.Language))
-            {
-                dTemplateArgumentCallSpans = ScientificNativeReferenceExtractor.EmitReferences(
-                    line.Language,
-                    line.PreparedLine,
-                    line.OriginalLine,
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    line.Context,
-                    line.LineNumber,
-                    line.ResolveContainerForCall,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    call.ScientificNativeDependencyLimit,
-                    call.ReportDiagnostic);
-            }
-
-            var dTemplateArgumentCallSpanIndex = 0;
-            if (line.Language is not ("tcl" or "prolog")
-                && callScanLine.IndexOf('(') >= 0)
-            {
-                foreach (Match match in EnumerateReferenceMatches(CallRegex, callScanLine, line.References))
-                {
-                    var name = match.Groups["name"].Value;
-                    var callIndex = match.Groups["name"].Index;
-                    if (line.Language == "rust" && RustReferenceExtractor.IsRawIdentifierPrefix(line.PreparedLine, callIndex))
-                        continue;
-                    if (line.Language == "d"
-                        && ScientificNativeReferenceExtractor.IsDTemplateArgumentCall(
-                            dTemplateArgumentCallSpans,
-                            ref dTemplateArgumentCallSpanIndex,
-                            callIndex))
-                    {
-                        continue;
-                    }
-                    if (line.Language == "ada"
-                        && callIndex > 0
-                        && line.PreparedLine[callIndex - 1] == '\'')
-                    {
-                        continue;
-                    }
-                    if (line.Language == "objc" && IsObjCSelectorLiteralCall(line.PreparedLine, name, callIndex))
-                        continue;
-                    if (call.SqlSuppressedCallIndices != null && call.SqlSuppressedCallIndices.Contains(callIndex))
-                        continue;
-                    if (call.SqlWindowFunctionCallSiteSuppressions != null
-                        && call.SqlWindowFunctionCallSiteSuppressions.Contains((line.LineNumber, callIndex)))
-                        continue;
-                    if (DynamicDeclarativeReferenceExtractor.ShouldSuppressGenericCall(
-                            line.Language,
-                            callScanLine,
-                            name,
-                            callIndex,
-                            line.LineNumber,
-                            call.DynamicDeclarativeState,
-                            line.Language == "groovy"
-                                ? line.ResolveContainerForCall(callIndex)
-                                : null))
-                    {
-                        continue;
-                    }
-                    (matchedCallIndices ??= []).Add(callIndex);
-                    if (TryAddCoreCallLikeReference(
-                            call,
-                            name,
-                            callIndex,
-                            ScientificNativeReferenceExtractor.Supports(line.Language)
-                                ? ScientificNativeReferenceExtractor.GetParenthesizedCallTargetQualifier(
-                                    line.Language,
-                                    line.PreparedLine,
-                                    callIndex)
-                                : null))
-                    {
-                        EmitGenericInvocationTypeArgumentReferences(
-                            line.Language,
-                            line.PreparedLine,
-                            callIndex,
-                            line.References,
-                            line.Seen,
-                            line.FileId,
-                            line.Context,
-                            line.LineNumber,
-                            line.ResolveContainerForCall(callIndex));
-                    }
-                    if (line.Language == "ruby")
-                        RubyReferenceExtractor.EmitCommandTargetReferences(
-                            name,
-                            callIndex,
-                            line.OriginalLine,
-                            line.References,
-                            line.Seen,
-                            line.FileId,
-                            line.Context,
-                            line.LineNumber,
-                            line.ResolveContainerForCall);
-                }
-            }
-
-            if (line.Language == "ruby")
-            {
-                RubyReferenceExtractor.EmitAdditionalCallReferences(
-                    line.PreparedLine,
-                    line.OriginalLine,
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    line.Context,
-                    line.LineNumber,
-                    line.ResolveContainerForCall,
-                    matchedCallIndices ??= [],
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call));
-            }
-            else if (line.Language is "perl" or "ambiguous_pl")
-            {
-                PerlReferenceExtractor.EmitAdditionalReferences(
-                    line.Language == "ambiguous_pl" ? callScanLine : line.PreparedLine,
-                    line.OriginalLine,
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    line.Context,
-                    line.LineNumber,
-                    line.ResolveContainerForCall,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    emitArrowCallReferences: line.Language != "ambiguous_pl"
-                        || call.DynamicDeclarativeState?.HasPrologContainer(line.LineNumber) != true);
-            }
-
-            if (call.DynamicDeclarativeState != null)
-            {
-                DynamicDeclarativeReferenceExtractor.EmitAdditionalReferences(
-                    line.Language,
-                    callScanLine,
-                    call.ReferenceStructuralLine,
-                    call.DynamicDeclarativeState,
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    line.Context,
-                    line.LineNumber,
-                    line.ResolveContainerForCall,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call));
-            }
-
-            if (line.Language == "go")
-                LanguageReferenceExtractionSupport.EmitGoBranchLabelReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.References);
-
-            if (line.Language == "swift")
-                SwiftReferenceExtractor.EmitTrailingClosureReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.References);
-            else if (line.Language == "kotlin")
-            {
-                KotlinReferenceExtractor.EmitInfixCallReferences(
-                    line.PreparedLine,
-                    line.OriginalLine,
-                    call.KotlinInfixFunctionNames!,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call));
-                KotlinReferenceExtractor.EmitTrailingLambdaReferences(
-                    line.PreparedLine,
-                    addCallLikeReference,
-                    line.References);
-            }
-
-            if (line.Language == "fsharp")
-            {
-                FSharpReferenceExtractor.EmitAdditionalCallReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.References);
-            }
-
-            if (line.Language == "scala")
-            {
-                ScalaReferenceExtractor.EmitTrailingBlockCallReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.References);
-                ScalaReferenceExtractor.EmitAdditionalReferences(
-                    line.PreparedLine,
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    line.Context,
-                    line.LineNumber,
-                    line.ResolveContainerForCall,
-                    addCallLikeReference);
-            }
-            else if (line.Language == "gradle")
-            {
-                GradleReferenceExtractor.EmitDslCallReferences(
-                    line.PreparedLine,
-                    CreateGradleDslReferenceEmitter(line),
-                    line.References);
-            }
-
-            if (line.Language == "fortran")
-                FortranReferenceExtractor.EmitAdditionalCallReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call));
-            else if (line.Language == "pascal")
-                PascalReferenceExtractor.EmitAdditionalCallReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.DefinitionNames);
-            else if (line.Language == "objc")
-                ObjectiveCReferenceExtractor.EmitAdditionalCallReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    line.Context,
-                    line.LineNumber,
-                    line.ResolveContainerForCall);
-            else if (line.Language == "haskell")
-                HaskellReferenceExtractor.EmitAdditionalCallReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.DefinitionNames);
-            else if (line.Language == "elixir")
-                ElixirReferenceExtractor.EmitAdditionalCallReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.DefinitionNames);
-            else if (line.Language == "lua")
-                LuaReferenceExtractor.EmitAdditionalCallReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    line.Context,
-                    line.LineNumber,
-                    line.ResolveContainerForCall,
-                    line.DefinitionNames);
-            else if (line.Language == "smalltalk")
-                SmalltalkReferenceExtractor.EmitAdditionalCallReferences(
-                    line.PreparedLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.DefinitionNames);
-            else if (line.Language == "vb")
-                LanguageReferenceExtractionSupport.EmitAdditionalCallReferences(
-                    "vb",
-                    line.PreparedLine,
-                    line.OriginalLine,
-                    addCallLikeReference ??= CreateCallLikeReferenceEmitter(call),
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    line.Context,
-                    line.LineNumber,
-                    line.ResolveContainerForCall,
-                    line.DefinitionNames);
-
-            // The flat CallRegex misses nested generic tails like `>>(` because `<[^>\n]+>`
-            // stops at the first `>`. Add a depth-aware fallback so `Foo<Bar<int>>()` and
-            // `new Dict<K, List<V>>()` still emit call/instantiate rows. See issue #263.
-            // 平坦な CallRegex は `<[^>\n]+>` が最初の `>` で止まるため `>>(` 形を取りこぼす。
-            // depth-aware な fallback を足し、`Foo<Bar<int>>()` や `new Dict<K, List<V>>()` でも
-            // `call` / `instantiate` を発行する。issue #263 参照。
-            if (line.Language is not ("tcl" or "prolog" or "ambiguous_pl")
-                && line.PreparedLine.IndexOf('(') >= 0
-                && MayContainNestedGenericSyntax(line.PreparedLine))
-            {
-                foreach (var candidate in EnumerateNestedGenericCallCandidates(line.PreparedLine, matchedCallIndices ?? EmptyMatchedIndices))
-                {
-                    if (ReferenceLimitReached(line.References))
-                        break;
-
-                    if (TryAddCoreCallLikeReference(
-                            call,
-                            candidate.Name,
-                            candidate.NameIndex))
-                    {
-                        EmitGenericInvocationTypeArgumentReferences(
-                            line.Language,
-                            line.PreparedLine,
-                            candidate.NameIndex,
-                            line.References,
-                            line.Seen,
-                            line.FileId,
-                            line.Context,
-                            line.LineNumber,
-                            line.ResolveContainerForCall(candidate.NameIndex));
-                    }
-                }
-            }
-        }
+        var state = new CoreCallEmissionState(
+            callScanLine,
+            ScientificNativeReferenceExtractor.Supports(line.Language));
+        EmitCoreLanguageCallReferences(in call, ref state);
 
         if (ReferenceLimitReached(line.References))
             return;
 
-        if (line.Language == "rust")
-        {
-            RustReferenceExtractor.EmitAdditionalCallReferences(
-                line.PreparedLine,
-                addCallLikeReference ??= CreateCallLikeReferenceEmitter(call));
-            RustReferenceExtractor.EmitAttributeReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-        }
+        EmitRustPostCallReferences(in call, ref state);
     }
 }
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallScanning.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallScanning.cs
new file mode 100644
index 000000000..06824d736
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallScanning.cs
@@ -0,0 +1,242 @@
+using System.Text.RegularExpressions;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitGeneralCoreCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        var dTemplateArgumentCallSpans = EmitScientificNativeCallReferences(
+            in call,
+            ref state);
+        EmitParenthesizedCoreCallReferences(
+            in call,
+            dTemplateArgumentCallSpans,
+            ref state);
+        EmitRubyOrPerlCallReferences(in call, ref state);
+        EmitDynamicDeclarativeCallReferences(in call, ref state);
+        EmitGoCallReferences(in call, ref state);
+        EmitSwiftOrKotlinCallReferences(in call, ref state);
+        EmitFSharpCallReferences(in call, ref state);
+        EmitScalaOrGradleCallReferences(in call, ref state);
+        EmitSecondaryLanguageCallReferences(in call, ref state);
+        EmitNestedGenericCallReferences(in call, ref state);
+    }
+
+    private static IReadOnlyList<ScientificNativeReferenceExtractor.DTemplateArgumentCallSpan>?
+        EmitScientificNativeCallReferences(
+            in CoreCallReferenceContext call,
+            ref CoreCallEmissionState state)
+    {
+        if (!state.IsScientificNativeLanguage)
+            return null;
+
+        ref readonly var line = ref call.Line;
+        return ScientificNativeReferenceExtractor.EmitReferences(
+            line.Language,
+            line.PreparedLine,
+            line.OriginalLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall,
+            GetOrCreateCallLikeReferenceEmitter(in call, ref state),
+            call.ScientificNativeDependencyLimit,
+            call.ReportDiagnostic);
+    }
+
+    private static void EmitParenthesizedCoreCallReferences(
+        in CoreCallReferenceContext call,
+        IReadOnlyList<ScientificNativeReferenceExtractor.DTemplateArgumentCallSpan>?
+            dTemplateArgumentCallSpans,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language is "tcl" or "prolog"
+            || state.CallScanLine.IndexOf('(') < 0)
+        {
+            return;
+        }
+
+        var dTemplateArgumentCallSpanIndex = 0;
+        foreach (Match match in EnumerateReferenceMatches(
+                     CallRegex,
+                     state.CallScanLine,
+                     line.References))
+        {
+            var name = match.Groups["name"].Value;
+            var callIndex = match.Groups["name"].Index;
+            if (ShouldSuppressParenthesizedCoreCall(
+                    in call,
+                    state.CallScanLine,
+                    name,
+                    callIndex,
+                    dTemplateArgumentCallSpans,
+                    ref dTemplateArgumentCallSpanIndex))
+            {
+                continue;
+            }
+
+            GetOrCreateMatchedCallIndices(ref state).Add(callIndex);
+            EmitParenthesizedCoreCallMatch(
+                in call,
+                name,
+                callIndex,
+                ref state);
+        }
+    }
+
+    private static bool ShouldSuppressParenthesizedCoreCall(
+        in CoreCallReferenceContext call,
+        string callScanLine,
+        string name,
+        int callIndex,
+        IReadOnlyList<ScientificNativeReferenceExtractor.DTemplateArgumentCallSpan>?
+            dTemplateArgumentCallSpans,
+        ref int dTemplateArgumentCallSpanIndex)
+    {
+        ref readonly var line = ref call.Line;
+        if (line.Language == "rust"
+            && RustReferenceExtractor.IsRawIdentifierPrefix(
+                line.PreparedLine,
+                callIndex))
+        {
+            return true;
+        }
+
+        if (line.Language == "d"
+            && ScientificNativeReferenceExtractor.IsDTemplateArgumentCall(
+                dTemplateArgumentCallSpans,
+                ref dTemplateArgumentCallSpanIndex,
+                callIndex))
+        {
+            return true;
+        }
+
+        if (line.Language == "ada"
+            && callIndex > 0
+            && line.PreparedLine[callIndex - 1] == '\'')
+        {
+            return true;
+        }
+
+        if (line.Language == "objc"
+            && IsObjCSelectorLiteralCall(line.PreparedLine, name, callIndex))
+        {
+            return true;
+        }
+
+        if (call.SqlSuppressedCallIndices?.Contains(callIndex) == true)
+            return true;
+
+        if (call.SqlWindowFunctionCallSiteSuppressions?.Contains(
+                (line.LineNumber, callIndex)) == true)
+        {
+            return true;
+        }
+
+        return DynamicDeclarativeReferenceExtractor.ShouldSuppressGenericCall(
+            line.Language,
+            callScanLine,
+            name,
+            callIndex,
+            line.LineNumber,
+            call.DynamicDeclarativeState,
+            line.Language == "groovy"
+                ? line.ResolveContainerForCall(callIndex)
+                : null);
+    }
+
+    private static void EmitParenthesizedCoreCallMatch(
+        in CoreCallReferenceContext call,
+        string name,
+        int callIndex,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        var targetQualifier = state.IsScientificNativeLanguage
+            ? ScientificNativeReferenceExtractor.GetParenthesizedCallTargetQualifier(
+                line.Language,
+                line.PreparedLine,
+                callIndex)
+            : null;
+        if (TryAddCoreCallLikeReference(
+                in call,
+                name,
+                callIndex,
+                state.IsScientificNativeLanguage,
+                targetQualifier))
+        {
+            EmitGenericInvocationTypeArgumentReferences(
+                line.Language,
+                line.PreparedLine,
+                callIndex,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall(callIndex));
+        }
+
+        if (line.Language == "ruby")
+        {
+            RubyReferenceExtractor.EmitCommandTargetReferences(
+                name,
+                callIndex,
+                line.OriginalLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall);
+        }
+    }
+
+    private static void EmitNestedGenericCallReferences(
+        in CoreCallReferenceContext call,
+        ref CoreCallEmissionState state)
+    {
+        ref readonly var line = ref call.Line;
+        // CallRegex stops at the first `>`. Keep the depth-aware fallback for
+        // nested tails such as `Foo<Bar<int>>()` (issue #263).
+        if (line.Language is "tcl" or "prolog" or "ambiguous_pl"
+            || line.PreparedLine.IndexOf('(') < 0
+            || !MayContainNestedGenericSyntax(line.PreparedLine))
+        {
+            return;
+        }
+
+        var matchedCallIndices = state.MatchedCallIndices ?? EmptyMatchedIndices;
+        foreach (var candidate in EnumerateNestedGenericCallCandidates(
+                     line.PreparedLine,
+                     matchedCallIndices))
+        {
+            if (ReferenceLimitReached(line.References))
+                break;
+
+            if (TryAddCoreCallLikeReference(
+                    in call,
+                    candidate.Name,
+                    candidate.NameIndex,
+                    state.IsScientificNativeLanguage))
+            {
+                EmitGenericInvocationTypeArgumentReferences(
+                    line.Language,
+                    line.PreparedLine,
+                    candidate.NameIndex,
+                    line.References,
+                    line.Seen,
+                    line.FileId,
+                    line.Context,
+                    line.LineNumber,
+                    line.ResolveContainerForCall(candidate.NameIndex));
+            }
+        }
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallSuppressions.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallSuppressions.cs
new file mode 100644
index 000000000..e7e24efad
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCallSuppressions.cs
@@ -0,0 +1,149 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static bool ShouldSuppressCoreCallCandidate(
+        in CoreCallReferenceContext call,
+        string name,
+        string normalizedName,
+        int callIndex)
+    {
+        ref readonly var line = ref call.Line;
+
+        // In tuple-return declarations, CallRegex can see the modifier in
+        // `static (int Value, ...)` as a call. A verbatim `@static()` remains valid.
+        if (line.Language == "csharp" && name == "static")
+            return true;
+
+        if (line.Language == "rust"
+            && RustReferenceExtractor.IsFunctionDeclarationCallSite(
+                line.PreparedLine,
+                callIndex))
+        {
+            return true;
+        }
+
+        if (line.Language == "rust"
+            && RustReferenceExtractor.IsDeriveAttributeCallSite(
+                line.PreparedLine,
+                normalizedName,
+                callIndex))
+        {
+            return true;
+        }
+
+        if (line.Language == "wgsl" && name.StartsWith('@'))
+            return true;
+
+        if (line.Language == "kotlin"
+            && KotlinReferenceExtractor.IsInfixFunctionDeclarationSite(
+                line.PreparedLine,
+                callIndex))
+        {
+            return true;
+        }
+
+        // A same-line Java constructor declarator is a declaration, not a call.
+        if (call.JavaSameLineCtor is { } javaSameLineCtor
+            && callIndex == javaSameLineCtor.NameIndex
+            && string.Equals(
+                normalizedName,
+                javaSameLineCtor.Synthetic.Name,
+                StringComparison.Ordinal))
+        {
+            return true;
+        }
+
+        if (line.Language == "csharp"
+            && CSharpReferenceExtractor.IsPatternHeadCallSite(
+                line.PreparedLines,
+                line.LineIndex,
+                line.PreparedLine,
+                callIndex))
+        {
+            return true;
+        }
+
+        if (line.Language == "typescript"
+            && TypeScriptReferenceExtractor.IsSatisfiesTypeOperand(
+                line.PreparedLine,
+                callIndex))
+        {
+            return true;
+        }
+
+        return call.Definitions.ShouldSuppressDefinitionCall(
+            normalizedName,
+            name,
+            callIndex);
+    }
+
+    private static bool TryHandleCSharpValueReceiverCall(
+        in CoreCallReferenceContext call,
+        string name,
+        string normalizedName,
+        int callIndex,
+        SymbolRecord? callContainer)
+    {
+        ref readonly var line = ref call.Line;
+        var afterNameIndex = callIndex + name.Length;
+        if (line.Language != "csharp"
+            || afterNameIndex >= line.PreparedLine.Length
+            || !line.PreparedLine.AsSpan(afterNameIndex)
+                .TrimStart()
+                .StartsWith(".", StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        var receiverLookups = call.Lookups.GetCSharpValueReceiverLookups();
+        if (!HasCSharpValueReceiverConflict(
+                normalizedName,
+                normalizedName,
+                line.LineNumber,
+                callIndex,
+                callContainer,
+                receiverLookups.ByContainingType,
+                receiverLookups.ByFunctionStartLine))
+        {
+            return false;
+        }
+
+        var containingType = GetContainingTypeQualifiedName(callContainer);
+        if (containingType != null
+            && receiverLookups.ByContainingType.TryGetValue(
+                containingType,
+                out var receiverNames)
+            && (receiverNames.InstanceNames.Contains(normalizedName)
+                || receiverNames.StaticNames.Contains(normalizedName))
+            && call.Lookups.HasCSharpFieldOrPropertyMember(
+                containingType,
+                normalizedName))
+        {
+            var fileId = line.FileId;
+            var lineNumber = line.LineNumber;
+            line.References.RemoveAll(reference =>
+                reference.FileId == fileId
+                && reference.Line == lineNumber
+                && reference.Column == callIndex + 1
+                && reference.ReferenceKind == "type_reference"
+                && string.Equals(
+                    reference.SymbolName,
+                    normalizedName,
+                    StringComparison.Ordinal));
+            AddCoreClassifiedReference(
+                in call,
+                $"{containingType}.{normalizedName}",
+                callIndex,
+                "reference",
+                callContainer,
+                line.Language,
+                targetQualifier: null,
+                name.Length);
+        }
+
+        return true;
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
index 620274cd8..80bc5d09d 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
@@ -127,7 +127,7 @@ private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
             return CoreReferenceLineFlow.StopExtraction;
 
         var callContext = new CoreCallReferenceContext(
-            line,
+            in line,
             loop.Lookups,
             prepared.JavaSameLineCtor,
             prepared.CSharpAttributeRanges,
@@ -142,7 +142,7 @@ private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
             sqlSuppressedCallIndices,
             loop.SqlWindowFunctionCallSiteSuppressions,
             prepared.DefinitionState);
-        EmitCoreCallReferences(callContext);
+        EmitCoreCallReferences(in callContext);
 
         if (ReferenceLimitReached(line.References))
             return CoreReferenceLineFlow.StopExtraction;

From 75c386dfca8092aeee99c4201a710f31482c2930 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 10:30:49 +0900
Subject: [PATCH 14/45] Decompose transitive impact traversal

---
 .../Database/DbReader.GraphQueries.cs         | 1063 -----------------
 .../DbReader.ImpactTraversal.Cycles.cs        |  221 ++++
 .../DbReader.ImpactTraversal.Engine.cs        |  266 +++++
 ...DbReader.ImpactTraversal.PathResolution.cs |  125 ++
 .../DbReader.ImpactTraversal.Paths.cs         |  228 ++++
 .../DbReader.ImpactTraversal.State.cs         |  224 ++++
 .../Database/DbReader.ImpactTraversal.cs      |  302 +++++
 tests/CodeIndex.Tests/DbReaderImpactTests.cs  |    1 +
 tests/CodeIndex.Tests/DbReaderTests.cs        |   32 +
 .../QueryCommandRunnerImpactTests.cs          |   78 +-
 10 files changed, 1433 insertions(+), 1107 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactTraversal.Cycles.cs
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactTraversal.Engine.cs
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactTraversal.PathResolution.cs
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactTraversal.Paths.cs
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactTraversal.State.cs
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactTraversal.cs

diff --git a/src/CodeIndex/Database/DbReader.GraphQueries.cs b/src/CodeIndex/Database/DbReader.GraphQueries.cs
index b851bba92..126989cfb 100644
--- a/src/CodeIndex/Database/DbReader.GraphQueries.cs
+++ b/src/CodeIndex/Database/DbReader.GraphQueries.cs
@@ -400,15 +400,6 @@ ELSE 5
     /// SQL 側で要求された LIMIT/OFFSET を適用し、呼び出し側が要求以上の中間ページを
     /// materialize しないようにする。
     /// </summary>
-    private List<CallerResult> GetCallersExact(string symbolName, int limit, int offset = 0, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, bool includeAmbiguousMSource = false, bool includeMemberReads = false)
-        => GetCallersExactCore(symbolName, limit, offset, lang, pathPatterns, excludePathPatterns, excludeTests, targetSymbolIds: null, includeAmbiguousMSource, includeMemberReads);
-
-    private List<CallerResult> GetCallersExactForTarget(string symbolName, long targetSymbolId, int limit, int offset, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests, bool includeAmbiguousMSource = false, bool includeMemberReads = false)
-        => GetCallersExactCore(symbolName, limit, offset, lang, pathPatterns, excludePathPatterns, excludeTests, [targetSymbolId], includeAmbiguousMSource, includeMemberReads);
-
-    private List<CallerResult> GetCallersExactForTargets(string symbolName, IReadOnlyList<long> targetSymbolIds, int limit, int offset, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests, bool includeAmbiguousMSource = false, bool includeMemberReads = false)
-        => GetCallersExactCore(symbolName, limit, offset, lang, pathPatterns, excludePathPatterns, excludeTests, targetSymbolIds, includeAmbiguousMSource, includeMemberReads);
-
     private List<CallerResult> GetCallersExactCore(string symbolName, int limit, int offset, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests, IReadOnlyList<long>? targetSymbolIds, bool includeAmbiguousMSource, bool includeMemberReads)
     {
         if (!_hasReferencesTable) return new List<CallerResult>();
@@ -611,1060 +602,6 @@ FROM logical_references r
         return results;
     }
 
-    private static string BuildImpactVisitedKey(
-        CallerResult caller,
-        string callerName,
-        bool useCanonicalIdentity,
-        bool deduplicateLogicalNodes = false)
-    {
-        var identity = useCanonicalIdentity && caller.CallerSymbolId is long callerSymbolId
-            ? $"id:{callerSymbolId}"
-            : $"{caller.Path}:{callerName}";
-        return deduplicateLogicalNodes ? identity : $"{identity}:{caller.ReferenceKind}";
-    }
-
-    private static string BuildImpactTraversalNodeKey(long? symbolId, string name)
-        => symbolId is long canonicalSymbolId ? $"id:{canonicalSymbolId}" : $"name:{name}";
-
-    // Per-result cap on the number of distinct shortest paths surfaced by impact --with-paths.
-    // Each call chain row may carry multiple converging paths from the resolved root through
-    // distinct intermediates; the cap keeps JSON output bounded for diamond-heavy graphs and
-    // is signaled by ImpactResult.PathsTruncated when exceeded.
-    // impact --with-paths が 1 caller につき保持する経路数の上限。ダイヤモンド型で多経路が
-    // 収束する場合に JSON 膨張を抑える役割があり、超過時は PathsTruncated で通知する。
-    private const int DefaultImpactPathsPerResult = 10;
-    internal const int DefaultImpactGraphStateEntryBudget = 10_000;
-    internal const int DefaultImpactPartialFamilyMemberBudget = 10_000;
-    internal int ImpactPartialFamilyMemberBudget { get; set; } = DefaultImpactPartialFamilyMemberBudget;
-    internal const int ImpactBoundaryCallerProbeBudget = 512;
-    private const int ImpactBoundaryCallerProbePageSize = 64;
-
-    /// <summary>
-    /// Compute transitive callers of a symbol using BFS with exact matching.
-    /// Returns each unique caller in the call chain with its depth from the root symbol.
-    /// The <paramref name="maxDepth"/> bound is inclusive: when <paramref name="maxDepth"/> is N,
-    /// callers at depth 1 through N are returned (so a chain A→B→C→D queried against D with
-    /// <c>maxDepth: 2</c> yields C at depth 1 and B at depth 2). Truncation is signaled via the
-    /// Truncated property in results. When Truncated is true, TruncatedReason distinguishes
-    /// user_limit (raise <c>--limit</c>) from safety_cap (pathological graph). See Issue #1533.
-    /// When <paramref name="withPaths"/> is true, each ImpactResult is populated with the
-    /// distinct shortest call paths from the resolved root through any intermediates to that
-    /// caller (issue #1536); converging diamond chains surface every shortest route up to
-    /// <paramref name="maxPathsPerResult"/>.
-    /// 完全一致の BFS でシンボルの推移的呼び出し元を算出。各呼び出し元とルートシンボルからの深さを返す。
-    /// <paramref name="maxDepth"/> は inclusive で、N を指定すると depth 1〜N の caller を返す
-    /// (例: A→B→C→D のチェーンで D を <c>maxDepth: 2</c> 検索すると C(depth=1) と B(depth=2) を返す)。
-    /// 結果が切り詰められた場合は Truncated フラグで通知し、TruncatedReason で
-    /// user_limit (--limit 到達、緩和で増える) と safety_cap (病的グラフ、--limit 緩和では解消しない) を区別する (#1533)。
-    /// <paramref name="withPaths"/> を true にすると、各 caller に対してルートからの推移経路
-    /// （ダイヤモンド収束時は複数）を <paramref name="maxPathsPerResult"/> 件まで付与する（issue #1536）。
-    /// </summary>
-    public (List<ImpactResult> Results, bool Truncated, string? TruncatedReason, string TerminationReason, List<ImpactCycleResult> Cycles) GetTransitiveCallers(string symbolName, int maxDepth = 5, int limit = 50, string? lang = null, IReadOnlyList<string>? pathPatterns = null, IReadOnlyList<string>? excludePathPatterns = null, bool excludeTests = false, bool withPaths = false, int maxPathsPerResult = DefaultImpactPathsPerResult, int resultOffset = 0, bool includeMemberReads = false)
-    {
-        // Resolve the symbol name through definitions first so case-mismatched queries
-        // like "run" find the actual "Run" symbol. Falls back to user input if not found.
-        // 定義を通じてシンボル名を解決し、"run" → "Run" のようなケース違いを補正する。
-        // 見つからなければユーザ入力をフォールバック使用。
-        var resolvedName = ResolveSymbolName(symbolName, lang);
-        var hasResolvedIdentityGraph = _referenceIdentityContractCurrent;
-        var canResolveQualifiedCSharpIdentity =
-            hasResolvedIdentityGraph
-            && SqlNameResolver.HasQualifier(symbolName)
-            && lang is null or "csharp";
-        var rootDefinitionLimit = canResolveQualifiedCSharpIdentity
-            ? DefaultImpactGraphStateEntryBudget
-            : limit;
-        var rootDefinitionResolution = ResolveImpactDefinitions(symbolName, rootDefinitionLimit, lang, pathPatterns, excludePathPatterns, excludeTests);
-        if (rootDefinitionResolution.Definitions.Count == 0
-            && !string.Equals(symbolName, resolvedName, StringComparison.Ordinal))
-        {
-            rootDefinitionResolution = ResolveImpactDefinitions(resolvedName, rootDefinitionLimit, lang, pathPatterns, excludePathPatterns, excludeTests);
-        }
-        var rootDefinitions = rootDefinitionResolution.Definitions;
-        var rootDefinitionPaths = rootDefinitions
-            .Select(definition => definition.Path)
-            .ToHashSet(StringComparer.OrdinalIgnoreCase);
-        var isLogicalPartialFamilyRoot =
-            hasResolvedIdentityGraph
-            && rootDefinitionResolution.LogicalCount == 1
-            && rootDefinitions.Count == 1
-            && rootDefinitions[0].Lang == "csharp"
-            && rootDefinitions[0].PartialFamilyId != null
-            && rootDefinitionResolution.PhysicalSymbolIds.Count > 0;
-        var qualifiedCSharpRootSymbolIds =
-            (canResolveQualifiedCSharpIdentity || isLogicalPartialFamilyRoot)
-            && rootDefinitions.Count > 0
-            && rootDefinitions.All(definition => definition.Lang == "csharp")
-            && rootDefinitions.All(definition => definition.SymbolId != null)
-            && (isLogicalPartialFamilyRoot || rootDefinitionResolution.LogicalCount == rootDefinitions.Count)
-                ? rootDefinitionResolution.PhysicalSymbolIds.ToHashSet()
-                : [];
-        if (hasResolvedIdentityGraph
-            && rootDefinitionPaths.Count > 1
-            && qualifiedCSharpRootSymbolIds.Count == 0)
-        {
-            return ([], false, null, ImpactTerminationReasons.Completed, []);
-        }
-        var ambiguousMRootSymbolId = hasResolvedIdentityGraph
-                                     && rootDefinitions.Count == 1
-                                     && lang is "matlab" or "objc"
-                                     && string.Equals(rootDefinitions[0].Lang, lang, StringComparison.Ordinal)
-            ? rootDefinitions[0].SymbolId
-            : null;
-        var identityRootSymbolIds = qualifiedCSharpRootSymbolIds.Count > 0
-            ? qualifiedCSharpRootSymbolIds
-            : ambiguousMRootSymbolId is long ambiguousRootSymbolId
-                ? [ambiguousRootSymbolId]
-                : [];
-        var singleIdentityRootSymbolId = identityRootSymbolIds.Count == 1
-            ? identityRootSymbolIds.Single()
-            : (long?)null;
-        var includeAmbiguousMSource = ambiguousMRootSymbolId != null;
-
-        var results = new List<ImpactResult>();
-        resultOffset = Math.Max(0, resultOffset);
-        var resultWindowEnd = checked(resultOffset + limit);
-        var discoveredResultCount = 0;
-        var visited = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
-        var rootTraversalNodeKey = identityRootSymbolIds.Count > 1
-            ? $"identity:{NameFold.Fold(symbolName) ?? symbolName}"
-            : BuildImpactTraversalNodeKey(singleIdentityRootSymbolId, resolvedName);
-        var queue = new Queue<(string Symbol, long? SymbolId, IReadOnlyList<long>? TargetSymbolIds, string NodeKey, int Depth)>();
-        if (isLogicalPartialFamilyRoot)
-        {
-            queue.Enqueue((resolvedName, null, identityRootSymbolIds.Order().ToArray(), rootTraversalNodeKey, 0));
-        }
-        else if (identityRootSymbolIds.Count > 0)
-        {
-            foreach (var identityRootSymbolId in identityRootSymbolIds.Order())
-                queue.Enqueue((resolvedName, identityRootSymbolId, null, rootTraversalNodeKey, 0));
-        }
-        else
-        {
-            queue.Enqueue((resolvedName, null, null, rootTraversalNodeKey, 0));
-        }
-        visited.Add(resolvedName);
-        // A partial-family root cap is reported independently on ImpactAnalysisResult.
-        // It must not masquerade as a traversal/result cap, because raising --limit does
-        // not expand the family root and the BFS may otherwise have completed normally.
-        // partial family の root 上限は ImpactAnalysisResult で独立して報告する。
-        // --limit 由来の traversal truncation と混同せず、通常完了した BFS を
-        // safety_cap 扱いしない。
-        var truncated = !isLogicalPartialFamilyRoot
-                        && qualifiedCSharpRootSymbolIds.Count > 0
-                        && rootDefinitionResolution.PhysicalSymbolIdsTruncated;
-        var maxDepthReached = false;
-        var cycles = new List<ImpactCycleResult>();
-        var cycleKeys = new HashSet<string>(StringComparer.Ordinal);
-        var cycleNodesByKey = new Dictionary<string, ImpactCycleMemberResult>(StringComparer.Ordinal);
-        // truncatedReason tracks the *strongest* signal observed: safety_cap wins over
-        // user_limit because it tells callers that raising --limit alone will not help
-        // (the input graph is likely pathological). See Issue #1533.
-        // truncatedReason は強い方の信号を保持する: safety_cap は --limit を緩和しても解消しない
-        // ことを示すため、user_limit より優先する (#1533)。
-        string? truncatedReason = truncated ? ImpactTruncatedReasons.SafetyCap : null;
-        // Safety cap to prevent infinite loops on pathological graphs / 病的グラフでの無限ループ防止
-        const int maxFetchIterations = 1000;
-        var graphStateEntryBudget = GetImpactGraphStateEntryBudget(resultWindowEnd);
-        var graphStateBudgetHit = false;
-        var boundaryProbeBudgetHit = false;
-
-        // Traversal state uses canonical symbol IDs when they are available. Display names are
-        // applied only while materializing output, so consecutive same-name symbols remain
-        // distinct path nodes (issue #4847) while legacy graphs retain name-keyed behavior.
-        // traversal state は利用可能なら正規 symbol ID をキーにする。表示名への変換は出力時
-        // だけ行い、同名 symbol が連続する経路も別ノードとして保持する (#4847)。
-        Dictionary<string, HashSet<string>> parentsByNodeKey = new(StringComparer.OrdinalIgnoreCase);
-        Dictionary<string, HashSet<string>> cycleParentsByKey = new(StringComparer.Ordinal);
-        Dictionary<string, int> depthByNodeKey = new(StringComparer.OrdinalIgnoreCase)
-        {
-            [rootTraversalNodeKey] = 0,
-        };
-        var resultIndicesByNodeKey = withPaths
-            ? new Dictionary<string, List<int>>(StringComparer.OrdinalIgnoreCase)
-            : null;
-        var resultIndexByVisitedKey = isLogicalPartialFamilyRoot
-            ? new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase)
-            : null;
-        var pathNodesByKey = withPaths
-            ? new Dictionary<string, ImpactPathNode>(StringComparer.OrdinalIgnoreCase)
-            : null;
-        if (withPaths)
-        {
-            var rootPathNode = ResolveImpactPathNode(
-                resolvedName,
-                singleIdentityRootSymbolId,
-                kind: null,
-                lang,
-                referencePath: null,
-                referenceLine: null);
-            if (isLogicalPartialFamilyRoot)
-            {
-                var representative = rootDefinitions[0];
-                rootPathNode.SymbolId = null;
-                rootPathNode.Name = resolvedName;
-                rootPathNode.Kind = representative.Kind;
-                rootPathNode.Lang = representative.Lang;
-                rootPathNode.DefinitionPath = representative.Path;
-                rootPathNode.DefinitionLine = representative.Line;
-                rootPathNode.Container = representative.ContainerQualifiedName ?? representative.ContainerName;
-                rootPathNode.PartialFamilyId = representative.PartialFamilyId;
-                rootPathNode.LogicalTargetKey = $"partial|{representative.PartialFamilyId}";
-            }
-            pathNodesByKey![rootTraversalNodeKey] = rootPathNode;
-        }
-
-        while (queue.Count > 0 && discoveredResultCount < resultWindowEnd && !graphStateBudgetHit && !boundaryProbeBudgetHit)
-        {
-            var (currentSymbol, currentSymbolId, currentTargetSymbolIds, currentNodeKey, depth) = queue.Dequeue();
-
-            // Fetch callers in pages, filtering out already-visited before counting toward limit.
-            // This prevents diamond graphs from hiding reachable callers behind visited duplicates.
-            // ページングで caller を取得し、visited フィルタ後にカウント。
-            // ダイヤモンド型グラフで到達可能な caller が visited 重複に隠れるのを防止。
-            var needed = resultWindowEnd - discoveredResultCount;
-            var pageOffset = 0;
-            var pageSize = Math.Max(1, needed + 1);
-            var fetchIterations = 0;
-
-            while (discoveredResultCount < resultWindowEnd && fetchIterations < maxFetchIterations && !graphStateBudgetHit && !boundaryProbeBudgetHit)
-            {
-                fetchIterations++;
-                var page = currentTargetSymbolIds is { Count: > 0 }
-                    ? GetCallersExactForTargets(currentSymbol, currentTargetSymbolIds, pageSize, pageOffset, lang, pathPatterns, excludePathPatterns, excludeTests, includeAmbiguousMSource, includeMemberReads)
-                    : currentSymbolId is long targetSymbolId
-                        ? GetCallersExactForTarget(currentSymbol, targetSymbolId, pageSize, pageOffset, lang, pathPatterns, excludePathPatterns, excludeTests, includeAmbiguousMSource, includeMemberReads)
-                        : GetCallersExact(currentSymbol, pageSize, pageOffset, lang, pathPatterns, excludePathPatterns, excludeTests, includeAmbiguousMSource, includeMemberReads);
-
-                if (page.Count == 0)
-                    break; // No more callers for this symbol / このシンボルの caller は尽きた
-
-                foreach (var caller in page)
-                {
-                    if (discoveredResultCount >= resultWindowEnd)
-                    {
-                        truncated = true;
-                        truncatedReason ??= ImpactTruncatedReasons.UserLimit;
-                        break;
-                    }
-
-                    var callerName = caller.CallerName ?? SyntheticTopLevelCallerName;
-                    var callerSymbolId = hasResolvedIdentityGraph ? caller.CallerSymbolId : null;
-                    var calleeSymbolId = hasResolvedIdentityGraph ? caller.CalleeSymbolId : null;
-                    var cycleEdges = BuildImpactCycleEdges(
-                        caller,
-                        callerName,
-                        currentSymbol,
-                        hasResolvedIdentityGraph,
-                        isLogicalPartialFamilyRoot ? identityRootSymbolIds : null,
-                        rootTraversalNodeKey,
-                        resolvedName);
-                    foreach (var cycleEdge in cycleEdges)
-                    {
-                        RegisterImpactCycleNode(cycleNodesByKey, cycleEdge.Caller);
-                        RegisterImpactCycleNode(cycleNodesByKey, cycleEdge.Callee);
-                        if (IsCycleEdge(cycleEdge.Caller.Key, cycleEdge.Callee.Key, cycleParentsByKey))
-                            AddImpactCycle(cycles, cycleKeys, BuildCycleMembers(cycleEdge.Caller.Key, cycleEdge.Callee.Key, cycleParentsByKey), cycleNodesByKey);
-                    }
-                    if (IsImpactRootCaller(caller, callerName, resolvedName, rootDefinitionPaths, identityRootSymbolIds))
-                        continue;
-                    var callerNodeKey = BuildImpactTraversalNodeKey(callerSymbolId, callerName);
-                    var key = BuildImpactVisitedKey(
-                        caller,
-                        callerName,
-                        hasResolvedIdentityGraph,
-                        deduplicateLogicalNodes: isLogicalPartialFamilyRoot);
-                    foreach (var cycleEdge in cycleEdges)
-                    {
-                        if (!cycleParentsByKey.TryGetValue(cycleEdge.Caller.Key, out var cycleParentSet))
-                        {
-                            cycleParentSet = new HashSet<string>(StringComparer.Ordinal);
-                            cycleParentsByKey[cycleEdge.Caller.Key] = cycleParentSet;
-                        }
-                        cycleParentSet.Add(cycleEdge.Callee.Key);
-                    }
-                    if (ImpactGraphStateEntryCount(parentsByNodeKey, cycleParentsByKey, depthByNodeKey, resultIndicesByNodeKey) > graphStateEntryBudget)
-                    {
-                        graphStateBudgetHit = true;
-                        truncated = true;
-                        truncatedReason = ImpactTruncatedReasons.GraphStateBudget;
-                        break;
-                    }
-
-                    if (!visited.Add(key))
-                    {
-                        if (resultIndexByVisitedKey != null
-                            && resultIndexByVisitedKey.TryGetValue(key, out var existingResultIndex))
-                        {
-                            MergeImpactReferenceEvidence(results[existingResultIndex], caller);
-                        }
-                        // Same-depth convergence: record the additional parent so path
-                        // enumeration can discover this alternate route. Other-depth re-arrivals
-                        // are intentionally dropped — BFS already keeps the shortest route.
-                        // 同 depth で再到達した場合のみ親辺を追加し、別 depth の到達は破棄。
-                        // BFS により最短経路だけが残る。
-                        if (withPaths
-                            && depthByNodeKey.TryGetValue(callerNodeKey, out var existingDepth)
-                            && existingDepth == depth + 1)
-                        {
-                            parentsByNodeKey[callerNodeKey].Add(currentNodeKey);
-                            if (ImpactGraphStateEntryCount(parentsByNodeKey, cycleParentsByKey, depthByNodeKey, resultIndicesByNodeKey) > graphStateEntryBudget)
-                            {
-                                graphStateBudgetHit = true;
-                                truncated = true;
-                                truncatedReason = ImpactTruncatedReasons.GraphStateBudget;
-                                break;
-                            }
-                        }
-                        continue;
-                    }
-
-                    var includeInPage = discoveredResultCount >= resultOffset;
-                    var resultIndex = -1;
-                    if (includeInPage)
-                    {
-                        results.Add(new ImpactResult
-                        {
-                            Path = caller.Path,
-                            Lang = caller.Lang,
-                            CallerKind = caller.CallerKind,
-                            CallerName = caller.CallerName,
-                            CalleeName = caller.CalleeName,
-                            CallerSymbolId = callerSymbolId,
-                            CalleeSymbolId = calleeSymbolId,
-                            Depth = depth + 1,
-                            FirstLine = caller.FirstLine,
-                            ReferenceCount = caller.ReferenceCount,
-                            ReferenceKind = caller.ReferenceKind,
-                            ReferenceKinds = caller.ReferenceKinds,
-                            ReferenceKindCounts = caller.ReferenceKindCounts,
-                        });
-                        resultIndex = results.Count - 1;
-                        resultIndexByVisitedKey?.Add(key, resultIndex);
-                    }
-                    discoveredResultCount++;
-
-                    if (withPaths)
-                    {
-                        pathNodesByKey!.TryAdd(
-                            callerNodeKey,
-                            ResolveImpactPathNode(
-                                callerName,
-                                callerSymbolId,
-                                caller.CallerKind,
-                                caller.Lang ?? lang,
-                                caller.Path,
-                                caller.FirstLine));
-                        if (!depthByNodeKey.ContainsKey(callerNodeKey))
-                            depthByNodeKey[callerNodeKey] = depth + 1;
-                        if (includeInPage)
-                        {
-                            if (!resultIndicesByNodeKey!.TryGetValue(callerNodeKey, out var idxList))
-                            {
-                                idxList = new List<int>();
-                                resultIndicesByNodeKey[callerNodeKey] = idxList;
-                            }
-                            idxList.Add(resultIndex);
-                        }
-                    }
-                    else if (!depthByNodeKey.ContainsKey(callerNodeKey))
-                    {
-                        depthByNodeKey[callerNodeKey] = depth + 1;
-                    }
-                    if (!parentsByNodeKey.TryGetValue(callerNodeKey, out var parentSet))
-                    {
-                        parentSet = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
-                        parentsByNodeKey[callerNodeKey] = parentSet;
-                    }
-                    parentSet.Add(currentNodeKey);
-                    if (ImpactGraphStateEntryCount(parentsByNodeKey, cycleParentsByKey, depthByNodeKey, resultIndicesByNodeKey) > graphStateEntryBudget)
-                    {
-                        graphStateBudgetHit = true;
-                        truncated = true;
-                        truncatedReason = ImpactTruncatedReasons.GraphStateBudget;
-                        break;
-                    }
-
-                    // Only recurse if the just-added caller (at depth + 1) is strictly below
-                    // maxDepth, so that the next BFS step can reach depth + 2 ≤ maxDepth.
-                    // This keeps the maxDepth bound inclusive of depth = maxDepth results.
-                    // 追加した caller (depth + 1) が maxDepth より小さいときだけ再帰し、
-                    // 次の BFS で depth + 2 ≤ maxDepth まで到達できるようにする。
-                    // これにより maxDepth は inclusive な上限として機能する。
-                    if (caller.CallerName != null
-                        && caller.CallerName != SyntheticTopLevelCallerName
-                        && depth + 1 < maxDepth)
-                    {
-                        queue.Enqueue((caller.CallerName, callerSymbolId, null, callerNodeKey, depth + 1));
-                    }
-                    else if (caller.CallerName != null
-                             && caller.CallerName != SyntheticTopLevelCallerName
-                             && depth + 1 == maxDepth)
-                    {
-                        var boundaryInspection = InspectBoundaryCallersCore(
-                            caller.CallerName,
-                            callerSymbolId,
-                            resolvedName,
-                            rootDefinitionPaths,
-                            identityRootSymbolIds,
-                            visited,
-                            cycleParentsByKey,
-                            cycleNodesByKey,
-                            cycles,
-                            cycleKeys,
-                            hasResolvedIdentityGraph,
-                            lang,
-                            pathPatterns,
-                            excludePathPatterns,
-                            excludeTests,
-                            includeAmbiguousMSource,
-                            includeMemberReads,
-                            isLogicalPartialFamilyRoot ? identityRootSymbolIds : null,
-                            rootTraversalNodeKey,
-                            resolvedName);
-                        maxDepthReached |= boundaryInspection.HasUnvisitedCaller;
-                        if (boundaryInspection.ProbeBudgetHit)
-                        {
-                            boundaryProbeBudgetHit = true;
-                            truncated = true;
-                            truncatedReason = ImpactTruncatedReasons.BoundaryProbeBudget;
-                            break;
-                        }
-                    }
-                }
-
-                pageOffset += page.Count;
-
-                // If this page was full, there might be more — continue paging
-                // ページが満杯なら、まだある可能性 — ページングを継続
-                if (page.Count < pageSize)
-                    break;
-            }
-
-            // If fetch iteration cap was hit, mark as truncated / フェッチ反復上限に達した場合も truncated
-            if (fetchIterations >= maxFetchIterations)
-            {
-                truncated = true;
-                truncatedReason = ImpactTruncatedReasons.SafetyCap;
-            }
-        }
-
-        if (queue.Count > 0 && discoveredResultCount >= resultWindowEnd)
-        {
-            truncated = true;
-            truncatedReason ??= ImpactTruncatedReasons.UserLimit;
-        }
-
-        if (withPaths)
-        {
-            var effectiveCap = maxPathsPerResult > 0 ? maxPathsPerResult : DefaultImpactPathsPerResult;
-            foreach (var (callerNodeKey, indices) in resultIndicesByNodeKey!)
-            {
-                var (pathKeys, more) = EnumerateImpactPaths(callerNodeKey, parentsByNodeKey, rootTraversalNodeKey, effectiveCap);
-                var paths = pathKeys
-                    .Select(path => path.Select(nodeKey => pathNodesByKey![nodeKey].Name).ToList())
-                    .ToList();
-                foreach (var idx in indices)
-                {
-                    results[idx].Paths = paths;
-                    results[idx].PathDetails = BuildImpactPathDetails(pathKeys, pathNodesByKey!, results[idx]);
-                    results[idx].PathsTruncated = more;
-                }
-            }
-        }
-
-        var terminationReason = truncatedReason switch
-        {
-            ImpactTruncatedReasons.GraphStateBudget => ImpactTerminationReasons.GraphStateBudget,
-            ImpactTruncatedReasons.BoundaryProbeBudget => ImpactTerminationReasons.BoundaryProbeBudget,
-            ImpactTruncatedReasons.SafetyCap => ImpactTerminationReasons.SafetyCap,
-            ImpactTruncatedReasons.UserLimit => ImpactTerminationReasons.RowLimitTruncated,
-            _ when cycles.Count > 0 => ImpactTerminationReasons.CycleDetected,
-            _ when maxDepthReached => ImpactTerminationReasons.MaxDepthReached,
-            _ => ImpactTerminationReasons.Completed,
-        };
-
-        return (results, truncated, truncatedReason, terminationReason, cycles);
-    }
-
-    private static int GetImpactGraphStateEntryBudget(int limit)
-    {
-        var limitScaled = Math.Max(1, limit) * 200;
-        return Math.Max(1024, Math.Min(DefaultImpactGraphStateEntryBudget, limitScaled));
-    }
-
-    private static void MergeImpactReferenceEvidence(ImpactResult result, CallerResult caller)
-    {
-        var counts = result.ReferenceKindCounts.ToDictionary(
-            pair => pair.Key,
-            pair => pair.Value,
-            StringComparer.Ordinal);
-        foreach (var (kind, count) in caller.ReferenceKindCounts)
-        {
-            counts[kind] = counts.TryGetValue(kind, out var existingCount)
-                ? Math.Max(existingCount, count)
-                : count;
-        }
-
-        result.ReferenceKindCounts = counts;
-        result.ReferenceKinds = counts.Keys.Order(StringComparer.Ordinal).ToArray();
-        result.ReferenceCount = counts.Values.Sum();
-        result.FirstLine = Math.Min(result.FirstLine, caller.FirstLine);
-    }
-
-    private static int ImpactGraphStateEntryCount(
-        Dictionary<string, HashSet<string>> parentsByNodeKey,
-        Dictionary<string, HashSet<string>> cycleParentsByNodeKey,
-        Dictionary<string, int> depthByNodeKey,
-        Dictionary<string, List<int>>? resultIndicesByNodeKey)
-    {
-        var count = depthByNodeKey.Count + parentsByNodeKey.Count + cycleParentsByNodeKey.Count + (resultIndicesByNodeKey?.Count ?? 0);
-        foreach (var parents in parentsByNodeKey.Values)
-            count += parents.Count;
-        foreach (var parents in cycleParentsByNodeKey.Values)
-            count += parents.Count;
-        if (resultIndicesByNodeKey != null)
-            foreach (var indices in resultIndicesByNodeKey.Values)
-                count += indices.Count;
-        return count;
-    }
-
-    private readonly record struct ImpactBoundaryInspection(bool HasUnvisitedCaller, bool ProbeBudgetHit);
-    private readonly record struct ImpactCycleNode(string Key, long? SymbolId, string Name);
-    private readonly record struct ImpactCycleEdge(ImpactCycleNode Caller, ImpactCycleNode Callee);
-
-    private static void RegisterImpactCycleNode(
-        Dictionary<string, ImpactCycleMemberResult> nodesByKey,
-        ImpactCycleNode node)
-        => nodesByKey.TryAdd(node.Key, new ImpactCycleMemberResult
-        {
-            SymbolId = node.SymbolId,
-            Name = node.Name,
-        });
-
-    private static ImpactCycleNode? BuildImpactCycleNode(long? symbolId, string name, bool hasResolvedIdentityGraph)
-    {
-        if (!hasResolvedIdentityGraph)
-            return new ImpactCycleNode($"name:{NameFold.Fold(name) ?? name}", null, name);
-        if (symbolId is long canonicalSymbolId)
-            return new ImpactCycleNode($"id:{canonicalSymbolId}", canonicalSymbolId, name);
-        return null;
-    }
-
-    private static List<ImpactCycleEdge> BuildImpactCycleEdges(
-        CallerResult caller,
-        string callerName,
-        string calleeName,
-        bool hasResolvedIdentityGraph,
-        IReadOnlySet<long>? logicalRootSymbolIds = null,
-        string? logicalRootKey = null,
-        string? logicalRootName = null)
-    {
-        var callerNode = NormalizeImpactCycleRootNode(
-            BuildImpactCycleNode(caller.CallerSymbolId, callerName, hasResolvedIdentityGraph),
-            logicalRootSymbolIds,
-            logicalRootKey,
-            logicalRootName);
-        if (callerNode is not { } canonicalCaller)
-            return [];
-
-        if (!hasResolvedIdentityGraph)
-        {
-            var legacyCallee = BuildImpactCycleNode(symbolId: null, calleeName, hasResolvedIdentityGraph: false)!.Value;
-            return [new ImpactCycleEdge(canonicalCaller, legacyCallee)];
-        }
-
-        var calleeSymbolIds = caller.CalleeSymbolIds.Count > 0
-            ? caller.CalleeSymbolIds
-            : caller.CalleeSymbolId is long calleeSymbolId
-                ? [calleeSymbolId]
-                : Array.Empty<long>();
-        return calleeSymbolIds
-            .Distinct()
-            .Order()
-            .Select(calleeSymbolId => new ImpactCycleEdge(
-                canonicalCaller,
-                NormalizeImpactCycleRootNode(
-                    new ImpactCycleNode($"id:{calleeSymbolId}", calleeSymbolId, calleeName),
-                    logicalRootSymbolIds,
-                    logicalRootKey,
-                    logicalRootName)!.Value))
-            .ToList();
-    }
-
-    private static ImpactCycleNode? NormalizeImpactCycleRootNode(
-        ImpactCycleNode? node,
-        IReadOnlySet<long>? logicalRootSymbolIds,
-        string? logicalRootKey,
-        string? logicalRootName)
-    {
-        if (node is not { SymbolId: long symbolId }
-            || logicalRootSymbolIds is not { Count: > 0 }
-            || !logicalRootSymbolIds.Contains(symbolId))
-        {
-            return node;
-        }
-
-        return new ImpactCycleNode(
-            logicalRootKey ?? "logical-partial-root",
-            SymbolId: null,
-            logicalRootName ?? node.Value.Name);
-    }
-
-    private static bool IsImpactRootCaller(
-        CallerResult caller,
-        string callerName,
-        string resolvedName,
-        HashSet<string> rootDefinitionPaths,
-        IReadOnlySet<long>? identityRootSymbolIds)
-    {
-        if (identityRootSymbolIds is { Count: > 0 }
-            && caller.CallerSymbolId is long callerSymbolId)
-        {
-            return identityRootSymbolIds.Contains(callerSymbolId);
-        }
-        return string.Equals(callerName, resolvedName, StringComparison.OrdinalIgnoreCase)
-               && (rootDefinitionPaths.Count == 0 || rootDefinitionPaths.Contains(caller.Path));
-    }
-
-    private ImpactBoundaryInspection InspectBoundaryCallers(
-        string symbolName,
-        long? symbolId,
-        string resolvedName,
-        HashSet<string> rootDefinitionPaths,
-        IReadOnlySet<long>? identityRootSymbolIds,
-        HashSet<string> visited,
-        Dictionary<string, HashSet<string>> cycleParentsByKey,
-        Dictionary<string, ImpactCycleMemberResult> cycleNodesByKey,
-        List<ImpactCycleResult> cycles,
-        HashSet<string> cycleKeys,
-        bool hasResolvedIdentityGraph,
-        string? lang,
-        IReadOnlyList<string>? pathPatterns,
-        IReadOnlyList<string>? excludePathPatterns,
-        bool excludeTests,
-        bool includeAmbiguousMSource,
-        bool includeMemberReads)
-        => InspectBoundaryCallersCore(
-            symbolName,
-            symbolId,
-            resolvedName,
-            rootDefinitionPaths,
-            identityRootSymbolIds,
-            visited,
-            cycleParentsByKey,
-            cycleNodesByKey,
-            cycles,
-            cycleKeys,
-            hasResolvedIdentityGraph,
-            lang,
-            pathPatterns,
-            excludePathPatterns,
-            excludeTests,
-            includeAmbiguousMSource,
-            includeMemberReads,
-            logicalRootSymbolIds: null,
-            logicalRootKey: null,
-            logicalRootName: null);
-
-    private ImpactBoundaryInspection InspectBoundaryCallersCore(
-        string symbolName,
-        long? symbolId,
-        string resolvedName,
-        HashSet<string> rootDefinitionPaths,
-        IReadOnlySet<long>? identityRootSymbolIds,
-        HashSet<string> visited,
-        Dictionary<string, HashSet<string>> cycleParentsByKey,
-        Dictionary<string, ImpactCycleMemberResult> cycleNodesByKey,
-        List<ImpactCycleResult> cycles,
-        HashSet<string> cycleKeys,
-        bool hasResolvedIdentityGraph,
-        string? lang,
-        IReadOnlyList<string>? pathPatterns,
-        IReadOnlyList<string>? excludePathPatterns,
-        bool excludeTests,
-        bool includeAmbiguousMSource,
-        bool includeMemberReads,
-        IReadOnlySet<long>? logicalRootSymbolIds,
-        string? logicalRootKey,
-        string? logicalRootName)
-    {
-        var offset = 0;
-        var probes = 0;
-        while (true)
-        {
-            if (probes >= ImpactBoundaryCallerProbeBudget)
-                return new ImpactBoundaryInspection(HasUnvisitedCaller: true, ProbeBudgetHit: true);
-
-            var pageSize = Math.Min(ImpactBoundaryCallerProbePageSize, ImpactBoundaryCallerProbeBudget - probes);
-            var page = symbolId is long targetSymbolId
-                ? GetCallersExactForTarget(symbolName, targetSymbolId, pageSize, offset, lang, pathPatterns, excludePathPatterns, excludeTests, includeAmbiguousMSource, includeMemberReads)
-                : GetCallersExact(symbolName, pageSize, offset, lang, pathPatterns, excludePathPatterns, excludeTests, includeAmbiguousMSource, includeMemberReads);
-            if (page.Count == 0)
-                return new ImpactBoundaryInspection(HasUnvisitedCaller: false, ProbeBudgetHit: false);
-            probes += page.Count;
-
-            foreach (var caller in page)
-            {
-                var callerName = caller.CallerName ?? SyntheticTopLevelCallerName;
-                var cycleEdges = BuildImpactCycleEdges(
-                    caller,
-                    callerName,
-                    symbolName,
-                    hasResolvedIdentityGraph,
-                    logicalRootSymbolIds,
-                    logicalRootKey,
-                    logicalRootName);
-                foreach (var cycleEdge in cycleEdges)
-                {
-                    RegisterImpactCycleNode(cycleNodesByKey, cycleEdge.Caller);
-                    RegisterImpactCycleNode(cycleNodesByKey, cycleEdge.Callee);
-                    if (IsCycleEdge(cycleEdge.Caller.Key, cycleEdge.Callee.Key, cycleParentsByKey))
-                        AddImpactCycle(cycles, cycleKeys, BuildCycleMembers(cycleEdge.Caller.Key, cycleEdge.Callee.Key, cycleParentsByKey), cycleNodesByKey);
-                }
-                var isRoot = IsImpactRootCaller(caller, callerName, resolvedName, rootDefinitionPaths, identityRootSymbolIds);
-                if (isRoot)
-                    continue;
-
-                foreach (var cycleEdge in cycleEdges)
-                {
-                    if (!cycleParentsByKey.TryGetValue(cycleEdge.Caller.Key, out var cycleParentSet))
-                    {
-                        cycleParentSet = new HashSet<string>(StringComparer.Ordinal);
-                        cycleParentsByKey[cycleEdge.Caller.Key] = cycleParentSet;
-                    }
-                    cycleParentSet.Add(cycleEdge.Callee.Key);
-                }
-
-                var key = BuildImpactVisitedKey(
-                    caller,
-                    callerName,
-                    hasResolvedIdentityGraph,
-                    deduplicateLogicalNodes: logicalRootSymbolIds is not null);
-                if (!visited.Contains(key))
-                    return new ImpactBoundaryInspection(HasUnvisitedCaller: true, ProbeBudgetHit: false);
-            }
-
-            if (page.Count < pageSize)
-                return new ImpactBoundaryInspection(HasUnvisitedCaller: false, ProbeBudgetHit: false);
-            offset += page.Count;
-        }
-    }
-
-    private static bool IsCycleEdge(
-        string callerKey,
-        string currentKey,
-        Dictionary<string, HashSet<string>> parentsByKey)
-    {
-        if (string.Equals(callerKey, currentKey, StringComparison.Ordinal))
-            return true;
-        return HasAncestor(currentKey, callerKey, parentsByKey);
-    }
-
-    private static bool HasAncestor(
-        string node,
-        string target,
-        Dictionary<string, HashSet<string>> parentsByKey)
-    {
-        var stack = new Stack<string>();
-        var seen = new HashSet<string>(StringComparer.Ordinal);
-        stack.Push(node);
-        while (stack.Count > 0)
-        {
-            var current = stack.Pop();
-            if (!seen.Add(current))
-                continue;
-            if (string.Equals(current, target, StringComparison.Ordinal))
-                return true;
-            if (!parentsByKey.TryGetValue(current, out var parents))
-                continue;
-            foreach (var parent in parents)
-                stack.Push(parent);
-        }
-        return false;
-    }
-
-    private static List<string> BuildCycleMembers(
-        string callerKey,
-        string currentKey,
-        Dictionary<string, HashSet<string>> parentsByKey)
-    {
-        var members = new HashSet<string>(StringComparer.Ordinal);
-        if (!TryBuildAncestorPath(currentKey, callerKey, parentsByKey, members))
-        {
-            members.Add(callerKey);
-            members.Add(currentKey);
-        }
-        var result = members.ToList();
-        result.Sort(StringComparer.Ordinal);
-        return result;
-    }
-
-    private static bool TryBuildAncestorPath(
-        string node,
-        string target,
-        Dictionary<string, HashSet<string>> parentsByKey,
-        HashSet<string> members)
-    {
-        var seen = new HashSet<string>(StringComparer.Ordinal);
-        return TryBuildAncestorPathCore(node, target, parentsByKey, members, seen);
-    }
-
-    private static bool TryBuildAncestorPathCore(
-        string node,
-        string target,
-        Dictionary<string, HashSet<string>> parentsByKey,
-        HashSet<string> members,
-        HashSet<string> seen)
-    {
-        if (!seen.Add(node))
-            return false;
-        members.Add(node);
-        if (string.Equals(node, target, StringComparison.Ordinal))
-            return true;
-        if (parentsByKey.TryGetValue(node, out var parents))
-        {
-            foreach (var parent in parents)
-            {
-                if (TryBuildAncestorPathCore(parent, target, parentsByKey, members, seen))
-                    return true;
-            }
-        }
-
-        members.Remove(node);
-        return false;
-    }
-
-    private static void AddImpactCycle(
-        List<ImpactCycleResult> cycles,
-        HashSet<string> cycleKeys,
-        List<string> memberKeys,
-        IReadOnlyDictionary<string, ImpactCycleMemberResult> nodesByKey)
-    {
-        if (memberKeys.Count == 0)
-            return;
-        var key = string.Join("\u001F", memberKeys);
-        if (!cycleKeys.Add(key))
-            return;
-        var identities = memberKeys
-            .Select(memberKey => nodesByKey[memberKey])
-            .OrderBy(node => node.Name, StringComparer.OrdinalIgnoreCase)
-            .ThenBy(node => node.SymbolId)
-            .Select(node => new ImpactCycleMemberResult
-            {
-                SymbolId = node.SymbolId,
-                Name = node.Name,
-            })
-            .ToList();
-        cycles.Add(new ImpactCycleResult
-        {
-            Members = identities.Select(identity => identity.Name).ToList(),
-            MemberIdentities = identities.Any(identity => identity.SymbolId != null) ? identities : null,
-        });
-    }
-
-    private static (List<List<string>> Paths, bool Truncated) EnumerateImpactPaths(
-        string callerNodeKey,
-        Dictionary<string, HashSet<string>> parentsByNodeKey,
-        string resolvedRootNodeKey,
-        int maxPathsPerResult)
-    {
-        // DFS upward through canonical node keys. The Stack<T> enumerator yields top-first,
-        // so the materialized key path is already ordered [resolvedRoot, ..., caller].
-        // 正規 node key の親辺を DFS で辿る。Stack<T> は top-first で列挙されるため、
-        // key path はそのまま [resolvedRoot, ..., caller] 順になる。
-        var paths = new List<List<string>>();
-        var stack = new Stack<string>();
-        var onStack = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
-        var truncatedRef = new bool[1];
-
-        stack.Push(callerNodeKey);
-        onStack.Add(callerNodeKey);
-        Dfs(callerNodeKey);
-        stack.Pop();
-        onStack.Remove(callerNodeKey);
-        return (paths, truncatedRef[0]);
-
-        void Dfs(string node)
-        {
-            if (string.Equals(node, resolvedRootNodeKey, StringComparison.OrdinalIgnoreCase))
-            {
-                paths.Add(stack.ToList());
-                return;
-            }
-            if (!parentsByNodeKey.TryGetValue(node, out var parents))
-                return;
-            foreach (var p in parents)
-            {
-                if (onStack.Contains(p))
-                    continue;
-                // Only mark truncated when the cap forces us to *skip* a still-unexplored parent;
-                // hitting cap exactly as the foreach drains naturally is not a truncation.
-                // 残りの parent を探索できなくなった瞬間にのみ truncated を立てる。foreach が
-                // 自然に終わるタイミングと一致しただけでは truncation 扱いしない。
-                if (paths.Count >= maxPathsPerResult)
-                {
-                    truncatedRef[0] = true;
-                    return;
-                }
-                stack.Push(p);
-                onStack.Add(p);
-                Dfs(p);
-                stack.Pop();
-                onStack.Remove(p);
-            }
-        }
-    }
-
-    private ImpactPathNode ResolveImpactPathNode(string name, long? symbolId, string? kind, string? lang, string? referencePath, int? referenceLine)
-    {
-        var node = TryResolveImpactPathNodeDefinition(name, symbolId, kind, lang, referencePath)
-            ?? new ImpactPathNode
-            {
-                SymbolId = symbolId,
-                Name = name,
-                Kind = kind,
-                Lang = lang,
-            };
-        node.ReferencePath = referencePath;
-        node.ReferenceLine = referenceLine;
-        return node;
-    }
-
-    private ImpactPathNode? TryResolveImpactPathNodeDefinition(string name, long? symbolId, string? kind, string? lang, string? preferredPath)
-    {
-        if (!_symbolColumns.Contains("name") || !_symbolColumns.Contains("kind"))
-            return null;
-
-        using var cmd = _conn.CreateCommand();
-        var containerNameSql = GetSymbolColumnSql("container_name");
-        var containerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name");
-        var familyKeySql = GetSymbolColumnSql("family_key");
-        var namePredicate = _foldReady && _symbolColumns.Contains("name_folded")
-            ? "s.name_folded = @nameFolded"
-            : "s.name = @name COLLATE NOCASE";
-
-        cmd.CommandText = $@"
-            SELECT s.id,
-                   f.path,
-                   f.lang,
-                   s.kind,
-                   s.name,
-                   s.line,
-                   {containerNameSql} AS container_name,
-                   {containerQualifiedNameSql} AS container_qualified_name,
-                   {familyKeySql} AS family_key,
-                   s.file_id,
-                   COUNT(*) OVER () AS matching_definition_count
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE ((@symbolId IS NOT NULL AND s.id = @symbolId)
-                   OR (@symbolId IS NULL AND {namePredicate}))
-              AND s.kind NOT IN ('import', 'namespace')
-              AND (@kind IS NULL OR s.kind = @kind)
-              AND (@lang IS NULL OR f.lang = @lang)
-            ORDER BY CASE WHEN @preferredPath IS NOT NULL AND f.path = @preferredPath THEN 0 ELSE 1 END,
-                     f.path,
-                     s.line
-            LIMIT 1";
-        SqliteCommandPolicy.Add(cmd, "@name", name);
-        SqliteCommandPolicy.AddNullableInt64(cmd, "@symbolId", symbolId);
-        if (_foldReady && _symbolColumns.Contains("name_folded"))
-            SqliteCommandPolicy.Add(cmd, "@nameFolded", NameFold.Fold(name) ?? name);
-        SqliteCommandPolicy.AddNullableText(cmd, "@kind", kind);
-        SqliteCommandPolicy.AddNullableText(cmd, "@lang", lang);
-        SqliteCommandPolicy.AddNullableText(cmd, "@preferredPath", preferredPath);
-
-        using var reader = cmd.ExecuteTrackedReader();
-        if (!reader.TrackedRead())
-            return null;
-
-        var definitionSymbolId = reader.GetInt64(0);
-        var definitionPath = reader.GetString(1);
-        var definitionLang = GetNullableString(reader, 2);
-        var definitionKind = reader.GetString(3);
-        var definitionName = reader.GetString(4);
-        var definitionLine = reader.IsDBNull(5) ? (int?)null : reader.GetInt32(5);
-        var containerName = GetNullableString(reader, 6);
-        var containerQualifiedName = GetNullableString(reader, 7);
-        var familyKey = GetNullableString(reader, 8);
-        var fileId = reader.GetInt64(9);
-        var matchingDefinitionCount = reader.GetInt64(10);
-
-        return new ImpactPathNode
-        {
-            SymbolId = symbolId ?? (matchingDefinitionCount == 1 ? definitionSymbolId : null),
-            Name = definitionName,
-            Kind = definitionKind,
-            Lang = definitionLang,
-            DefinitionPath = definitionPath,
-            DefinitionLine = definitionLine,
-            Container = containerName,
-            FamilyKey = familyKey,
-            LogicalTargetKey = BuildImpactPathLogicalTargetKey(definitionLang, definitionKind, familyKey, containerQualifiedName, fileId),
-        };
-    }
-
-    private static string BuildImpactPathLogicalTargetKey(string? lang, string kind, string? familyKey, string? containerQualifiedName, long fileId)
-    {
-        if (!string.IsNullOrWhiteSpace(familyKey))
-            return $"family|{lang ?? string.Empty}|{kind}|{familyKey}";
-        if (!string.IsNullOrWhiteSpace(containerQualifiedName))
-            return $"container|{fileId}|{kind}|{containerQualifiedName}";
-        return $"file|{fileId}";
-    }
-
-    private static List<List<ImpactPathNode>> BuildImpactPathDetails(
-        List<List<string>> pathKeys,
-        IReadOnlyDictionary<string, ImpactPathNode> nodesByKey,
-        ImpactResult result)
-    {
-        var details = new List<List<ImpactPathNode>>(pathKeys.Count);
-        foreach (var path in pathKeys)
-        {
-            var detailPath = new List<ImpactPathNode>(path.Count);
-            for (var i = 0; i < path.Count; i++)
-            {
-                var nodeKey = path[i];
-                var isResultNode = i == path.Count - 1;
-                if (!nodesByKey.TryGetValue(nodeKey, out var node))
-                    node = new ImpactPathNode { Name = nodeKey };
-                detailPath.Add(isResultNode
-                    ? CloneImpactPathNodeForResult(node, result)
-                    : CloneImpactPathNode(node));
-            }
-            details.Add(detailPath);
-        }
-        return details;
-    }
-
-    private static ImpactPathNode CloneImpactPathNodeForResult(ImpactPathNode node, ImpactResult result)
-    {
-        var clone = CloneImpactPathNode(node);
-        clone.Kind ??= result.CallerKind;
-        clone.Lang ??= result.Lang;
-        clone.ReferencePath = result.Path;
-        clone.ReferenceLine = result.FirstLine;
-        return clone;
-    }
-
-    private static ImpactPathNode CloneImpactPathNode(ImpactPathNode node)
-        => new()
-        {
-            SymbolId = node.SymbolId,
-            Name = node.Name,
-            Kind = node.Kind,
-            Lang = node.Lang,
-            DefinitionPath = node.DefinitionPath,
-            DefinitionLine = node.DefinitionLine,
-            Container = node.Container,
-            FamilyKey = node.FamilyKey,
-            PartialFamilyId = node.PartialFamilyId,
-            LogicalTargetKey = node.LogicalTargetKey,
-            ReferencePath = node.ReferencePath,
-            ReferenceLine = node.ReferenceLine,
-        };
-
     /// <summary>
     /// Analyze impact for a query by combining transitive callers with symbol-resolution
     /// metadata and a class-like file-dependency fallback when symbol-level callers are absent.
diff --git a/src/CodeIndex/Database/DbReader.ImpactTraversal.Cycles.cs b/src/CodeIndex/Database/DbReader.ImpactTraversal.Cycles.cs
new file mode 100644
index 000000000..d2a013d5d
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactTraversal.Cycles.cs
@@ -0,0 +1,221 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private readonly record struct ImpactCycleNode(string Key, long? SymbolId, string Name);
+
+    private readonly record struct ImpactCycleEdge(ImpactCycleNode Caller, ImpactCycleNode Callee);
+
+    private sealed class ImpactCycleTracker
+    {
+        private readonly bool _hasResolvedIdentityGraph;
+        private readonly IReadOnlySet<long>? _logicalRootSymbolIds;
+        private readonly string _logicalRootKey;
+        private readonly string _logicalRootName;
+        private readonly Dictionary<string, HashSet<string>> _parentsByKey = new(StringComparer.Ordinal);
+        private readonly Dictionary<string, ImpactCycleMemberResult> _nodesByKey = new(StringComparer.Ordinal);
+        private readonly HashSet<string> _cycleKeys = new(StringComparer.Ordinal);
+
+        internal ImpactCycleTracker(ImpactTraversalRoot root)
+        {
+            _hasResolvedIdentityGraph = root.HasResolvedIdentityGraph;
+            _logicalRootSymbolIds = root.IsLogicalPartialFamily ? root.IdentitySymbolIds : null;
+            _logicalRootKey = root.NodeKey;
+            _logicalRootName = root.ResolvedName;
+        }
+
+        internal List<ImpactCycleResult> Results { get; } = [];
+
+        internal int GraphStateEntryCount
+        {
+            get
+            {
+                var count = _parentsByKey.Count;
+                foreach (var parents in _parentsByKey.Values)
+                    count += parents.Count;
+                return count;
+            }
+        }
+
+        internal IReadOnlyList<ImpactCycleEdge> Observe(
+            CallerResult caller,
+            string callerName,
+            string calleeName)
+        {
+            var edges = BuildEdges(caller, callerName, calleeName);
+            foreach (var edge in edges)
+            {
+                RegisterNode(edge.Caller);
+                RegisterNode(edge.Callee);
+                if (IsCycleEdge(edge.Caller.Key, edge.Callee.Key))
+                    AddCycle(BuildCycleMembers(edge.Caller.Key, edge.Callee.Key));
+            }
+            return edges;
+        }
+
+        internal void CommitParents(IReadOnlyList<ImpactCycleEdge> edges)
+        {
+            foreach (var edge in edges)
+            {
+                if (!_parentsByKey.TryGetValue(edge.Caller.Key, out var parents))
+                {
+                    parents = new HashSet<string>(StringComparer.Ordinal);
+                    _parentsByKey[edge.Caller.Key] = parents;
+                }
+                parents.Add(edge.Callee.Key);
+            }
+        }
+
+        private List<ImpactCycleEdge> BuildEdges(
+            CallerResult caller,
+            string callerName,
+            string calleeName)
+        {
+            var callerNode = NormalizeLogicalRoot(
+                ImpactNodeIdentity.CycleNode(
+                    caller.CallerSymbolId,
+                    callerName,
+                    _hasResolvedIdentityGraph));
+            if (callerNode is not { } canonicalCaller)
+                return [];
+
+            if (!_hasResolvedIdentityGraph)
+            {
+                var calleeNode = ImpactNodeIdentity.CycleNode(null, calleeName, false)!.Value;
+                return [new ImpactCycleEdge(canonicalCaller, calleeNode)];
+            }
+
+            var calleeSymbolIds = caller.CalleeSymbolIds.Count > 0
+                ? caller.CalleeSymbolIds
+                : caller.CalleeSymbolId is long calleeSymbolId
+                    ? [calleeSymbolId]
+                    : Array.Empty<long>();
+            return calleeSymbolIds
+                .Distinct()
+                .Order()
+                .Select(calleeSymbolId => new ImpactCycleEdge(
+                    canonicalCaller,
+                    NormalizeLogicalRoot(new ImpactCycleNode(
+                        $"id:{calleeSymbolId}",
+                        calleeSymbolId,
+                        calleeName))!.Value))
+                .ToList();
+        }
+
+        private ImpactCycleNode? NormalizeLogicalRoot(ImpactCycleNode? node)
+        {
+            if (node is not { SymbolId: long symbolId }
+                || _logicalRootSymbolIds is not { Count: > 0 }
+                || !_logicalRootSymbolIds.Contains(symbolId))
+            {
+                return node;
+            }
+            return new ImpactCycleNode(_logicalRootKey, null, _logicalRootName);
+        }
+
+        private void RegisterNode(ImpactCycleNode node)
+            => _nodesByKey.TryAdd(node.Key, new ImpactCycleMemberResult
+            {
+                SymbolId = node.SymbolId,
+                Name = node.Name,
+            });
+
+        private bool IsCycleEdge(string callerKey, string calleeKey)
+            => string.Equals(callerKey, calleeKey, StringComparison.Ordinal)
+               || HasAncestor(calleeKey, callerKey);
+
+        private bool HasAncestor(string node, string target)
+        {
+            var stack = new Stack<string>();
+            var seen = new HashSet<string>(StringComparer.Ordinal);
+            stack.Push(node);
+            while (stack.Count > 0)
+            {
+                var current = stack.Pop();
+                if (!seen.Add(current))
+                    continue;
+                if (string.Equals(current, target, StringComparison.Ordinal))
+                    return true;
+                if (!_parentsByKey.TryGetValue(current, out var parents))
+                    continue;
+                foreach (var parent in parents)
+                    stack.Push(parent);
+            }
+            return false;
+        }
+
+        private List<string> BuildCycleMembers(string callerKey, string calleeKey)
+        {
+            var members = new HashSet<string>(StringComparer.Ordinal);
+            if (!TryBuildAncestorPath(calleeKey, callerKey, members))
+            {
+                members.Add(callerKey);
+                members.Add(calleeKey);
+            }
+            var result = members.ToList();
+            result.Sort(StringComparer.Ordinal);
+            return result;
+        }
+
+        private bool TryBuildAncestorPath(
+            string node,
+            string target,
+            HashSet<string> members)
+        {
+            var seen = new HashSet<string>(StringComparer.Ordinal);
+            return TryBuildAncestorPathCore(node, target, members, seen);
+        }
+
+        private bool TryBuildAncestorPathCore(
+            string node,
+            string target,
+            HashSet<string> members,
+            HashSet<string> seen)
+        {
+            if (!seen.Add(node))
+                return false;
+            members.Add(node);
+            if (string.Equals(node, target, StringComparison.Ordinal))
+                return true;
+            if (_parentsByKey.TryGetValue(node, out var parents))
+            {
+                foreach (var parent in parents)
+                {
+                    if (TryBuildAncestorPathCore(parent, target, members, seen))
+                        return true;
+                }
+            }
+
+            members.Remove(node);
+            return false;
+        }
+
+        private void AddCycle(List<string> memberKeys)
+        {
+            if (memberKeys.Count == 0)
+                return;
+            var key = string.Join("\u001F", memberKeys);
+            if (!_cycleKeys.Add(key))
+                return;
+            var identities = memberKeys
+                .Select(memberKey => _nodesByKey[memberKey])
+                .OrderBy(static node => node.Name, StringComparer.OrdinalIgnoreCase)
+                .ThenBy(static node => node.SymbolId)
+                .Select(static node => new ImpactCycleMemberResult
+                {
+                    SymbolId = node.SymbolId,
+                    Name = node.Name,
+                })
+                .ToList();
+            Results.Add(new ImpactCycleResult
+            {
+                Members = identities.Select(static identity => identity.Name).ToList(),
+                MemberIdentities = identities.Any(static identity => identity.SymbolId != null)
+                    ? identities
+                    : null,
+            });
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.ImpactTraversal.Engine.cs b/src/CodeIndex/Database/DbReader.ImpactTraversal.Engine.cs
new file mode 100644
index 000000000..5b1e6baaf
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactTraversal.Engine.cs
@@ -0,0 +1,266 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class ImpactTraversalEngine
+    {
+        private const int MaxFetchIterations = 1000;
+
+        private readonly DbReader _owner;
+        private readonly ImpactTraversalRequest _request;
+        private readonly ImpactTraversalRoot _root;
+        private readonly ImpactTraversalState _state;
+
+        internal ImpactTraversalEngine(
+            DbReader owner,
+            ImpactTraversalRequest request,
+            ImpactTraversalRoot root)
+        {
+            _owner = owner;
+            _request = request;
+            _root = root;
+            _state = new ImpactTraversalState(owner, request, root);
+        }
+
+        internal (List<ImpactResult> Results, bool Truncated, string? TruncatedReason, string TerminationReason, List<ImpactCycleResult> Cycles) Run()
+        {
+            while (_state.CanTraverse)
+            {
+                var node = _state.Queue.Dequeue();
+                TraverseNode(in node);
+            }
+
+            _state.CompleteTraversal();
+            _state.Paths.Materialize(_state.Results, _request.MaxPathsPerResult);
+            return (
+                _state.Results,
+                _state.Truncated,
+                _state.TruncatedReason,
+                _state.ResolveTerminationReason(),
+                _state.Cycles.Results);
+        }
+
+        private void TraverseNode(in ImpactTraversalFrontierNode node)
+        {
+            var needed = _state.ResultWindowEnd - _state.DiscoveredResultCount;
+            var pageSize = Math.Max(1, needed + 1);
+            var pageOffset = 0;
+            var fetchIterations = 0;
+
+            while (_state.CanFetchCurrentNode && fetchIterations < MaxFetchIterations)
+            {
+                fetchIterations++;
+                var page = _owner.ReadImpactCallerPage(
+                    in node,
+                    _request,
+                    pageSize,
+                    pageOffset,
+                    _root.IncludeAmbiguousMSource);
+                if (page.Count == 0)
+                    break;
+
+                ProcessPage(in node, page);
+                pageOffset += page.Count;
+                if (page.Count < pageSize)
+                    break;
+            }
+
+            if (fetchIterations >= MaxFetchIterations)
+                _state.MarkSafetyCap();
+        }
+
+        private void ProcessPage(
+            in ImpactTraversalFrontierNode node,
+            IReadOnlyList<CallerResult> page)
+        {
+            foreach (var caller in page)
+            {
+                if (_state.DiscoveredResultCount >= _state.ResultWindowEnd)
+                {
+                    _state.MarkUserLimit();
+                    break;
+                }
+                if (!ProcessCaller(in node, caller))
+                    break;
+            }
+        }
+
+        private bool ProcessCaller(
+            in ImpactTraversalFrontierNode node,
+            CallerResult caller)
+        {
+            var callerName = caller.CallerName ?? SyntheticTopLevelCallerName;
+            var callerSymbolId = _root.HasResolvedIdentityGraph ? caller.CallerSymbolId : null;
+            var calleeSymbolId = _root.HasResolvedIdentityGraph ? caller.CalleeSymbolId : null;
+            var cycleEdges = _state.Cycles.Observe(caller, callerName, node.Symbol);
+            if (IsRootCaller(caller, callerName))
+                return true;
+
+            var callerNodeKey = ImpactNodeIdentity.TraversalKey(callerSymbolId, callerName);
+            var visitedKey = ImpactNodeIdentity.VisitedKey(
+                caller,
+                callerName,
+                _root.HasResolvedIdentityGraph,
+                _root.IsLogicalPartialFamily);
+            _state.Cycles.CommitParents(cycleEdges);
+            if (_state.CheckGraphStateBudget())
+                return false;
+
+            if (!_state.TryVisit(visitedKey))
+            {
+                _state.MergeReferenceEvidence(visitedKey, caller);
+                if (_state.Paths.RecordSameDepthParent(
+                        callerNodeKey,
+                        node.NodeKey,
+                        node.Depth + 1)
+                    && _state.CheckGraphStateBudget())
+                {
+                    return false;
+                }
+                return true;
+            }
+
+            var result = _state.IncludeNextResult
+                ? BuildResult(caller, callerSymbolId, calleeSymbolId, node.Depth + 1)
+                : null;
+            var resultIndex = _state.AddResult(result, visitedKey);
+            _state.Paths.RecordCaller(
+                callerNodeKey,
+                node.NodeKey,
+                node.Depth + 1,
+                resultIndex,
+                caller,
+                callerName,
+                callerSymbolId,
+                _request.Lang);
+            if (_state.CheckGraphStateBudget())
+                return false;
+
+            return ContinueTraversal(in node, caller, callerSymbolId, callerNodeKey);
+        }
+
+        private bool ContinueTraversal(
+            in ImpactTraversalFrontierNode node,
+            CallerResult caller,
+            long? callerSymbolId,
+            string callerNodeKey)
+        {
+            if (caller.CallerName != null
+                && caller.CallerName != SyntheticTopLevelCallerName
+                && node.Depth + 1 < _request.MaxDepth)
+            {
+                _state.Queue.Enqueue(new ImpactTraversalFrontierNode(
+                    caller.CallerName,
+                    callerSymbolId,
+                    TargetSymbolIds: null,
+                    callerNodeKey,
+                    node.Depth + 1));
+            }
+            else if (caller.CallerName != null
+                     && caller.CallerName != SyntheticTopLevelCallerName
+                     && node.Depth + 1 == _request.MaxDepth)
+            {
+                var inspection = InspectBoundary(caller.CallerName, callerSymbolId);
+                _state.MaxDepthReached |= inspection.HasUnvisitedCaller;
+                if (inspection.ProbeBudgetHit)
+                {
+                    _state.MarkBoundaryProbeBudget();
+                    return false;
+                }
+            }
+            return true;
+        }
+
+        private ImpactBoundaryInspection InspectBoundary(
+            string symbolName,
+            long? symbolId)
+        {
+            var pageOffset = 0;
+            var probes = 0;
+            while (true)
+            {
+                if (probes >= _state.BoundaryProbeBudget)
+                    return new ImpactBoundaryInspection(true, true);
+
+                var pageSize = Math.Min(
+                    ImpactBoundaryCallerProbePageSize,
+                    _state.BoundaryProbeBudget - probes);
+                var node = new ImpactTraversalFrontierNode(
+                    symbolName,
+                    symbolId,
+                    TargetSymbolIds: null,
+                    NodeKey: string.Empty,
+                    Depth: 0);
+                var page = _owner.ReadImpactCallerPage(
+                    in node,
+                    _request,
+                    pageSize,
+                    pageOffset,
+                    _root.IncludeAmbiguousMSource);
+                if (page.Count == 0)
+                    return new ImpactBoundaryInspection(false, false);
+                probes += page.Count;
+
+                foreach (var caller in page)
+                {
+                    var callerName = caller.CallerName ?? SyntheticTopLevelCallerName;
+                    var cycleEdges = _state.Cycles.Observe(caller, callerName, symbolName);
+                    if (IsRootCaller(caller, callerName))
+                        continue;
+
+                    _state.Cycles.CommitParents(cycleEdges);
+                    var visitedKey = ImpactNodeIdentity.VisitedKey(
+                        caller,
+                        callerName,
+                        _root.HasResolvedIdentityGraph,
+                        _root.IsLogicalPartialFamily);
+                    if (!_state.Visited.Contains(visitedKey))
+                        return new ImpactBoundaryInspection(true, false);
+                }
+
+                if (page.Count < pageSize)
+                    return new ImpactBoundaryInspection(false, false);
+                pageOffset += page.Count;
+            }
+        }
+
+        private bool IsRootCaller(CallerResult caller, string callerName)
+        {
+            if (_root.IdentitySymbolIds.Count > 0
+                && caller.CallerSymbolId is long callerSymbolId)
+            {
+                return _root.IdentitySymbolIds.Contains(callerSymbolId);
+            }
+            return string.Equals(
+                       callerName,
+                       _root.ResolvedName,
+                       StringComparison.OrdinalIgnoreCase)
+                   && (_root.DefinitionPaths.Count == 0
+                       || _root.DefinitionPaths.Contains(caller.Path));
+        }
+
+        private static ImpactResult BuildResult(
+            CallerResult caller,
+            long? callerSymbolId,
+            long? calleeSymbolId,
+            int depth)
+            => new()
+            {
+                Path = caller.Path,
+                Lang = caller.Lang,
+                CallerKind = caller.CallerKind,
+                CallerName = caller.CallerName,
+                CalleeName = caller.CalleeName,
+                CallerSymbolId = callerSymbolId,
+                CalleeSymbolId = calleeSymbolId,
+                Depth = depth,
+                FirstLine = caller.FirstLine,
+                ReferenceCount = caller.ReferenceCount,
+                ReferenceKind = caller.ReferenceKind,
+                ReferenceKinds = caller.ReferenceKinds,
+                ReferenceKindCounts = caller.ReferenceKindCounts,
+            };
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.ImpactTraversal.PathResolution.cs b/src/CodeIndex/Database/DbReader.ImpactTraversal.PathResolution.cs
new file mode 100644
index 000000000..06a2454ed
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactTraversal.PathResolution.cs
@@ -0,0 +1,125 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private ImpactPathNode ResolveImpactPathNode(
+        string name,
+        long? symbolId,
+        string? kind,
+        string? lang,
+        string? referencePath,
+        int? referenceLine)
+    {
+        var node = TryResolveImpactPathNodeDefinition(name, symbolId, kind, lang, referencePath)
+            ?? new ImpactPathNode
+            {
+                SymbolId = symbolId,
+                Name = name,
+                Kind = kind,
+                Lang = lang,
+            };
+        node.ReferencePath = referencePath;
+        node.ReferenceLine = referenceLine;
+        return node;
+    }
+
+    private ImpactPathNode? TryResolveImpactPathNodeDefinition(
+        string name,
+        long? symbolId,
+        string? kind,
+        string? lang,
+        string? preferredPath)
+    {
+        if (!_symbolColumns.Contains("name") || !_symbolColumns.Contains("kind"))
+            return null;
+
+        using var cmd = _conn.CreateCommand();
+        var containerNameSql = GetSymbolColumnSql("container_name");
+        var containerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name");
+        var familyKeySql = GetSymbolColumnSql("family_key");
+        var namePredicate = _foldReady && _symbolColumns.Contains("name_folded")
+            ? "s.name_folded = @nameFolded"
+            : "s.name = @name COLLATE NOCASE";
+
+        cmd.CommandText = $@"
+            SELECT s.id,
+                   f.path,
+                   f.lang,
+                   s.kind,
+                   s.name,
+                   s.line,
+                   {containerNameSql} AS container_name,
+                   {containerQualifiedNameSql} AS container_qualified_name,
+                   {familyKeySql} AS family_key,
+                   s.file_id,
+                   COUNT(*) OVER () AS matching_definition_count
+            FROM symbols s
+            JOIN files f ON s.file_id = f.id
+            WHERE ((@symbolId IS NOT NULL AND s.id = @symbolId)
+                   OR (@symbolId IS NULL AND {namePredicate}))
+              AND s.kind NOT IN ('import', 'namespace')
+              AND (@kind IS NULL OR s.kind = @kind)
+              AND (@lang IS NULL OR f.lang = @lang)
+            ORDER BY CASE WHEN @preferredPath IS NOT NULL AND f.path = @preferredPath THEN 0 ELSE 1 END,
+                     f.path,
+                     s.line
+            LIMIT 1";
+        SqliteCommandPolicy.Add(cmd, "@name", name);
+        SqliteCommandPolicy.AddNullableInt64(cmd, "@symbolId", symbolId);
+        if (_foldReady && _symbolColumns.Contains("name_folded"))
+            SqliteCommandPolicy.Add(cmd, "@nameFolded", NameFold.Fold(name) ?? name);
+        SqliteCommandPolicy.AddNullableText(cmd, "@kind", kind);
+        SqliteCommandPolicy.AddNullableText(cmd, "@lang", lang);
+        SqliteCommandPolicy.AddNullableText(cmd, "@preferredPath", preferredPath);
+
+        using var reader = cmd.ExecuteTrackedReader();
+        if (!reader.TrackedRead())
+            return null;
+
+        var definitionSymbolId = reader.GetInt64(0);
+        var definitionPath = reader.GetString(1);
+        var definitionLang = GetNullableString(reader, 2);
+        var definitionKind = reader.GetString(3);
+        var definitionName = reader.GetString(4);
+        var definitionLine = reader.IsDBNull(5) ? (int?)null : reader.GetInt32(5);
+        var containerName = GetNullableString(reader, 6);
+        var containerQualifiedName = GetNullableString(reader, 7);
+        var familyKey = GetNullableString(reader, 8);
+        var fileId = reader.GetInt64(9);
+        var matchingDefinitionCount = reader.GetInt64(10);
+
+        return new ImpactPathNode
+        {
+            SymbolId = symbolId ?? (matchingDefinitionCount == 1 ? definitionSymbolId : null),
+            Name = definitionName,
+            Kind = definitionKind,
+            Lang = definitionLang,
+            DefinitionPath = definitionPath,
+            DefinitionLine = definitionLine,
+            Container = containerName,
+            FamilyKey = familyKey,
+            LogicalTargetKey = BuildImpactPathLogicalTargetKey(
+                definitionLang,
+                definitionKind,
+                familyKey,
+                containerQualifiedName,
+                fileId),
+        };
+    }
+
+    private static string BuildImpactPathLogicalTargetKey(
+        string? lang,
+        string kind,
+        string? familyKey,
+        string? containerQualifiedName,
+        long fileId)
+    {
+        if (!string.IsNullOrWhiteSpace(familyKey))
+            return $"family|{lang ?? string.Empty}|{kind}|{familyKey}";
+        if (!string.IsNullOrWhiteSpace(containerQualifiedName))
+            return $"container|{fileId}|{kind}|{containerQualifiedName}";
+        return $"file|{fileId}";
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.ImpactTraversal.Paths.cs b/src/CodeIndex/Database/DbReader.ImpactTraversal.Paths.cs
new file mode 100644
index 000000000..93d8b39f2
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactTraversal.Paths.cs
@@ -0,0 +1,228 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class ImpactPathTracker
+    {
+        private readonly DbReader _owner;
+        private readonly bool _withPaths;
+        private readonly string _rootNodeKey;
+        private readonly Dictionary<string, HashSet<string>> _parentsByNodeKey = new(StringComparer.OrdinalIgnoreCase);
+        private readonly Dictionary<string, int> _depthByNodeKey = new(StringComparer.OrdinalIgnoreCase);
+        private readonly Dictionary<string, List<int>>? _resultIndicesByNodeKey;
+        private readonly Dictionary<string, ImpactPathNode>? _nodesByKey;
+
+        internal ImpactPathTracker(DbReader owner, bool withPaths, ImpactTraversalRoot root)
+        {
+            _owner = owner;
+            _withPaths = withPaths;
+            _rootNodeKey = root.NodeKey;
+            _depthByNodeKey[root.NodeKey] = 0;
+            if (!withPaths)
+                return;
+
+            _resultIndicesByNodeKey = new Dictionary<string, List<int>>(StringComparer.OrdinalIgnoreCase);
+            _nodesByKey = new Dictionary<string, ImpactPathNode>(StringComparer.OrdinalIgnoreCase)
+            {
+                [root.NodeKey] = root.PathNode!,
+            };
+        }
+
+        internal int GraphStateEntryCount
+        {
+            get
+            {
+                var count = _depthByNodeKey.Count
+                            + _parentsByNodeKey.Count
+                            + (_resultIndicesByNodeKey?.Count ?? 0);
+                foreach (var parents in _parentsByNodeKey.Values)
+                    count += parents.Count;
+                if (_resultIndicesByNodeKey != null)
+                {
+                    foreach (var indices in _resultIndicesByNodeKey.Values)
+                        count += indices.Count;
+                }
+                return count;
+            }
+        }
+
+        internal bool RecordSameDepthParent(
+            string callerNodeKey,
+            string currentNodeKey,
+            int callerDepth)
+        {
+            if (!_withPaths
+                || !_depthByNodeKey.TryGetValue(callerNodeKey, out var existingDepth)
+                || existingDepth != callerDepth)
+            {
+                return false;
+            }
+
+            _parentsByNodeKey[callerNodeKey].Add(currentNodeKey);
+            return true;
+        }
+
+        internal void RecordCaller(
+            string callerNodeKey,
+            string currentNodeKey,
+            int callerDepth,
+            int resultIndex,
+            CallerResult caller,
+            string callerName,
+            long? callerSymbolId,
+            string? requestLang)
+        {
+            if (_withPaths)
+            {
+                _nodesByKey!.TryAdd(
+                    callerNodeKey,
+                    _owner.ResolveImpactPathNode(
+                        callerName,
+                        callerSymbolId,
+                        caller.CallerKind,
+                        caller.Lang ?? requestLang,
+                        caller.Path,
+                        caller.FirstLine));
+                _depthByNodeKey.TryAdd(callerNodeKey, callerDepth);
+                if (resultIndex >= 0)
+                {
+                    if (!_resultIndicesByNodeKey!.TryGetValue(callerNodeKey, out var indices))
+                    {
+                        indices = [];
+                        _resultIndicesByNodeKey[callerNodeKey] = indices;
+                    }
+                    indices.Add(resultIndex);
+                }
+            }
+            else
+            {
+                _depthByNodeKey.TryAdd(callerNodeKey, callerDepth);
+            }
+
+            if (!_parentsByNodeKey.TryGetValue(callerNodeKey, out var parents))
+            {
+                parents = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+                _parentsByNodeKey[callerNodeKey] = parents;
+            }
+            parents.Add(currentNodeKey);
+        }
+
+        internal void Materialize(List<ImpactResult> results, int maxPathsPerResult)
+        {
+            if (!_withPaths)
+                return;
+
+            var effectiveCap = maxPathsPerResult > 0
+                ? maxPathsPerResult
+                : DefaultImpactPathsPerResult;
+            foreach (var (callerNodeKey, indices) in _resultIndicesByNodeKey!)
+            {
+                var (pathKeys, pathsTruncated) = EnumeratePaths(callerNodeKey, effectiveCap);
+                var paths = pathKeys
+                    .Select(path => path.Select(nodeKey => _nodesByKey![nodeKey].Name).ToList())
+                    .ToList();
+                foreach (var resultIndex in indices)
+                {
+                    results[resultIndex].Paths = paths;
+                    results[resultIndex].PathDetails = BuildPathDetails(pathKeys, results[resultIndex]);
+                    results[resultIndex].PathsTruncated = pathsTruncated;
+                }
+            }
+        }
+
+        private (List<List<string>> Paths, bool Truncated) EnumeratePaths(
+            string callerNodeKey,
+            int maxPathsPerResult)
+        {
+            var paths = new List<List<string>>();
+            var stack = new Stack<string>();
+            var onStack = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            var truncated = false;
+
+            stack.Push(callerNodeKey);
+            onStack.Add(callerNodeKey);
+            Dfs(callerNodeKey);
+            return (paths, truncated);
+
+            void Dfs(string node)
+            {
+                if (string.Equals(node, _rootNodeKey, StringComparison.OrdinalIgnoreCase))
+                {
+                    paths.Add(stack.ToList());
+                    return;
+                }
+                if (!_parentsByNodeKey.TryGetValue(node, out var parents))
+                    return;
+                foreach (var parent in parents)
+                {
+                    if (onStack.Contains(parent))
+                        continue;
+                    if (paths.Count >= maxPathsPerResult)
+                    {
+                        truncated = true;
+                        return;
+                    }
+                    stack.Push(parent);
+                    onStack.Add(parent);
+                    Dfs(parent);
+                    stack.Pop();
+                    onStack.Remove(parent);
+                }
+            }
+        }
+
+        private List<List<ImpactPathNode>> BuildPathDetails(
+            List<List<string>> pathKeys,
+            ImpactResult result)
+        {
+            var details = new List<List<ImpactPathNode>>(pathKeys.Count);
+            foreach (var path in pathKeys)
+            {
+                var detailPath = new List<ImpactPathNode>(path.Count);
+                for (var i = 0; i < path.Count; i++)
+                {
+                    var nodeKey = path[i];
+                    var isResultNode = i == path.Count - 1;
+                    if (!_nodesByKey!.TryGetValue(nodeKey, out var node))
+                        node = new ImpactPathNode { Name = nodeKey };
+                    detailPath.Add(isResultNode
+                        ? ClonePathNodeForResult(node, result)
+                        : ClonePathNode(node));
+                }
+                details.Add(detailPath);
+            }
+            return details;
+        }
+
+        private static ImpactPathNode ClonePathNodeForResult(
+            ImpactPathNode node,
+            ImpactResult result)
+        {
+            var clone = ClonePathNode(node);
+            clone.Kind ??= result.CallerKind;
+            clone.Lang ??= result.Lang;
+            clone.ReferencePath = result.Path;
+            clone.ReferenceLine = result.FirstLine;
+            return clone;
+        }
+
+        private static ImpactPathNode ClonePathNode(ImpactPathNode node)
+            => new()
+            {
+                SymbolId = node.SymbolId,
+                Name = node.Name,
+                Kind = node.Kind,
+                Lang = node.Lang,
+                DefinitionPath = node.DefinitionPath,
+                DefinitionLine = node.DefinitionLine,
+                Container = node.Container,
+                FamilyKey = node.FamilyKey,
+                PartialFamilyId = node.PartialFamilyId,
+                LogicalTargetKey = node.LogicalTargetKey,
+                ReferencePath = node.ReferencePath,
+                ReferenceLine = node.ReferenceLine,
+            };
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.ImpactTraversal.State.cs b/src/CodeIndex/Database/DbReader.ImpactTraversal.State.cs
new file mode 100644
index 000000000..0a3a4a09f
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactTraversal.State.cs
@@ -0,0 +1,224 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private static class ImpactNodeIdentity
+    {
+        internal static string TraversalKey(long? symbolId, string name)
+            => symbolId is long canonicalId ? CanonicalIdKey(canonicalId) : $"name:{name}";
+
+        internal static string VisitedKey(
+            CallerResult caller,
+            string callerName,
+            bool useCanonicalIdentity,
+            bool deduplicateLogicalNodes)
+        {
+            var identity = useCanonicalIdentity && caller.CallerSymbolId is long callerId
+                ? CanonicalIdKey(callerId)
+                : $"{caller.Path}:{callerName}";
+            return deduplicateLogicalNodes ? identity : $"{identity}:{caller.ReferenceKind}";
+        }
+
+        internal static ImpactCycleNode? CycleNode(
+            long? symbolId,
+            string name,
+            bool hasResolvedIdentityGraph)
+        {
+            if (!hasResolvedIdentityGraph)
+                return new ImpactCycleNode($"name:{NameFold.Fold(name) ?? name}", null, name);
+            return symbolId is long canonicalId
+                ? new ImpactCycleNode(CanonicalIdKey(canonicalId), canonicalId, name)
+                : null;
+        }
+
+        private static string CanonicalIdKey(long symbolId) => $"id:{symbolId}";
+    }
+
+    private sealed class ImpactTraversalState
+    {
+        private readonly int _resultOffset;
+        private readonly int _graphStateEntryBudget;
+        private readonly Dictionary<string, int>? _resultIndexByVisitedKey;
+
+        internal ImpactTraversalState(
+            DbReader owner,
+            ImpactTraversalRequest request,
+            ImpactTraversalRoot root)
+        {
+            _resultOffset = Math.Max(0, request.ResultOffset);
+            ResultWindowEnd = checked(_resultOffset + request.Limit);
+            _graphStateEntryBudget = owner.GetImpactGraphStateEntryBudget(ResultWindowEnd);
+            BoundaryProbeBudget = owner.GetImpactBoundaryCallerProbeBudget();
+            Queue = CreateInitialQueue(root);
+            Visited = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { root.ResolvedName };
+            Cycles = new ImpactCycleTracker(root);
+            Paths = new ImpactPathTracker(owner, request.WithPaths, root);
+            _resultIndexByVisitedKey = root.IsLogicalPartialFamily
+                ? new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase)
+                : null;
+            Truncated = root.InitiallyTruncated;
+            TruncatedReason = root.InitiallyTruncated
+                ? ImpactTruncatedReasons.SafetyCap
+                : null;
+        }
+
+        internal Queue<ImpactTraversalFrontierNode> Queue { get; }
+        internal HashSet<string> Visited { get; }
+        internal ImpactCycleTracker Cycles { get; }
+        internal ImpactPathTracker Paths { get; }
+        internal List<ImpactResult> Results { get; } = [];
+        internal int ResultWindowEnd { get; }
+        internal int BoundaryProbeBudget { get; }
+        internal int DiscoveredResultCount { get; private set; }
+        internal bool Truncated { get; private set; }
+        internal string? TruncatedReason { get; private set; }
+        internal bool MaxDepthReached { get; set; }
+        internal bool GraphStateBudgetHit { get; private set; }
+        internal bool BoundaryProbeBudgetHit { get; private set; }
+
+        internal bool CanTraverse
+            => Queue.Count > 0
+               && DiscoveredResultCount < ResultWindowEnd
+               && !GraphStateBudgetHit
+               && !BoundaryProbeBudgetHit;
+
+        internal bool CanFetchCurrentNode
+            => DiscoveredResultCount < ResultWindowEnd
+               && !GraphStateBudgetHit
+               && !BoundaryProbeBudgetHit;
+
+        internal bool IncludeNextResult => DiscoveredResultCount >= _resultOffset;
+
+        private static Queue<ImpactTraversalFrontierNode> CreateInitialQueue(
+            ImpactTraversalRoot root)
+        {
+            var capacity = root.IsLogicalPartialFamily
+                ? 1
+                : Math.Max(1, root.IdentitySymbolIds.Count);
+            var queue = new Queue<ImpactTraversalFrontierNode>(capacity);
+            if (root.IsLogicalPartialFamily)
+            {
+                queue.Enqueue(new ImpactTraversalFrontierNode(
+                    root.ResolvedName,
+                    SymbolId: null,
+                    root.IdentitySymbolIds.Order().ToArray(),
+                    root.NodeKey,
+                    Depth: 0));
+            }
+            else if (root.IdentitySymbolIds.Count > 0)
+            {
+                foreach (var symbolId in root.IdentitySymbolIds.Order())
+                {
+                    queue.Enqueue(new ImpactTraversalFrontierNode(
+                        root.ResolvedName,
+                        symbolId,
+                        TargetSymbolIds: null,
+                        root.NodeKey,
+                        Depth: 0));
+                }
+            }
+            else
+            {
+                queue.Enqueue(new ImpactTraversalFrontierNode(
+                    root.ResolvedName,
+                    SymbolId: null,
+                    TargetSymbolIds: null,
+                    root.NodeKey,
+                    Depth: 0));
+            }
+            return queue;
+        }
+
+        internal bool TryVisit(string key) => Visited.Add(key);
+
+        internal int AddResult(ImpactResult? result, string visitedKey)
+        {
+            var resultIndex = -1;
+            if (IncludeNextResult)
+            {
+                Results.Add(result!);
+                resultIndex = Results.Count - 1;
+                _resultIndexByVisitedKey?.Add(visitedKey, resultIndex);
+            }
+            DiscoveredResultCount++;
+            return resultIndex;
+        }
+
+        internal void MergeReferenceEvidence(string visitedKey, CallerResult caller)
+        {
+            if (_resultIndexByVisitedKey != null
+                && _resultIndexByVisitedKey.TryGetValue(visitedKey, out var resultIndex))
+            {
+                MergeImpactReferenceEvidence(Results[resultIndex], caller);
+            }
+        }
+
+        internal bool CheckGraphStateBudget()
+        {
+            if (Paths.GraphStateEntryCount + Cycles.GraphStateEntryCount <= _graphStateEntryBudget)
+                return false;
+            GraphStateBudgetHit = true;
+            Truncated = true;
+            TruncatedReason = ImpactTruncatedReasons.GraphStateBudget;
+            return true;
+        }
+
+        internal void MarkBoundaryProbeBudget()
+        {
+            BoundaryProbeBudgetHit = true;
+            Truncated = true;
+            TruncatedReason = ImpactTruncatedReasons.BoundaryProbeBudget;
+        }
+
+        internal void MarkUserLimit()
+        {
+            Truncated = true;
+            TruncatedReason ??= ImpactTruncatedReasons.UserLimit;
+        }
+
+        internal void MarkSafetyCap()
+        {
+            Truncated = true;
+            TruncatedReason = ImpactTruncatedReasons.SafetyCap;
+        }
+
+        internal void CompleteTraversal()
+        {
+            if (Queue.Count > 0 && DiscoveredResultCount >= ResultWindowEnd)
+                MarkUserLimit();
+        }
+
+        internal string ResolveTerminationReason()
+            => TruncatedReason switch
+            {
+                ImpactTruncatedReasons.GraphStateBudget => ImpactTerminationReasons.GraphStateBudget,
+                ImpactTruncatedReasons.BoundaryProbeBudget => ImpactTerminationReasons.BoundaryProbeBudget,
+                ImpactTruncatedReasons.SafetyCap => ImpactTerminationReasons.SafetyCap,
+                ImpactTruncatedReasons.UserLimit => ImpactTerminationReasons.RowLimitTruncated,
+                _ when Cycles.Results.Count > 0 => ImpactTerminationReasons.CycleDetected,
+                _ when MaxDepthReached => ImpactTerminationReasons.MaxDepthReached,
+                _ => ImpactTerminationReasons.Completed,
+            };
+
+        private static void MergeImpactReferenceEvidence(ImpactResult result, CallerResult caller)
+        {
+            var counts = result.ReferenceKindCounts.ToDictionary(
+                static pair => pair.Key,
+                static pair => pair.Value,
+                StringComparer.Ordinal);
+            foreach (var (kind, count) in caller.ReferenceKindCounts)
+            {
+                counts[kind] = counts.TryGetValue(kind, out var existingCount)
+                    ? Math.Max(existingCount, count)
+                    : count;
+            }
+
+            result.ReferenceKindCounts = counts;
+            result.ReferenceKinds = counts.Keys.Order(StringComparer.Ordinal).ToArray();
+            result.ReferenceCount = counts.Values.Sum();
+            result.FirstLine = Math.Min(result.FirstLine, caller.FirstLine);
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.ImpactTraversal.cs b/src/CodeIndex/Database/DbReader.ImpactTraversal.cs
new file mode 100644
index 000000000..1fd501b01
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactTraversal.cs
@@ -0,0 +1,302 @@
+using CodeIndex.Indexer;
+using CodeIndex.Models;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    // Per-result cap on the number of distinct shortest paths surfaced by impact --with-paths.
+    // Each call chain row may carry multiple converging paths from the resolved root through
+    // distinct intermediates; the cap keeps JSON output bounded for diamond-heavy graphs and
+    // is signaled by ImpactResult.PathsTruncated when exceeded.
+    // impact --with-paths が 1 caller につき保持する経路数の上限。ダイヤモンド型で多経路が
+    // 収束する場合に JSON 膨張を抑える役割があり、超過時は PathsTruncated で通知する。
+    private const int DefaultImpactPathsPerResult = 10;
+    internal const int DefaultImpactGraphStateEntryBudget = 10_000;
+    internal const int DefaultImpactPartialFamilyMemberBudget = 10_000;
+    internal int ImpactPartialFamilyMemberBudget { get; set; } = DefaultImpactPartialFamilyMemberBudget;
+    internal const int ImpactBoundaryCallerProbeBudget = 512;
+    private const int ImpactBoundaryCallerProbePageSize = 64;
+
+    internal int? ImpactGraphStateEntryBudgetForTesting { get; set; }
+    internal int? ImpactBoundaryCallerProbeBudgetForTesting { get; set; }
+
+    private sealed record ImpactTraversalRequest(
+        string SymbolName,
+        int MaxDepth,
+        int Limit,
+        string? Lang,
+        IReadOnlyList<string>? PathPatterns,
+        IReadOnlyList<string>? ExcludePathPatterns,
+        bool ExcludeTests,
+        bool WithPaths,
+        int MaxPathsPerResult,
+        int ResultOffset,
+        bool IncludeMemberReads);
+
+    private sealed record ImpactTraversalRoot(
+        string ResolvedName,
+        HashSet<string> DefinitionPaths,
+        bool HasResolvedIdentityGraph,
+        bool IsLogicalPartialFamily,
+        HashSet<long> IdentitySymbolIds,
+        bool IncludeAmbiguousMSource,
+        bool InitiallyTruncated,
+        string NodeKey,
+        ImpactPathNode? PathNode);
+
+    private readonly record struct ImpactTraversalFrontierNode(
+        string Symbol,
+        long? SymbolId,
+        IReadOnlyList<long>? TargetSymbolIds,
+        string NodeKey,
+        int Depth);
+
+    private readonly record struct ImpactBoundaryInspection(
+        bool HasUnvisitedCaller,
+        bool ProbeBudgetHit);
+
+    /// <summary>
+    /// Compute transitive callers of a symbol using BFS with exact matching.
+    /// Returns each unique caller in the call chain with its depth from the root symbol.
+    /// The <paramref name="maxDepth"/> bound is inclusive: when <paramref name="maxDepth"/> is N,
+    /// callers at depth 1 through N are returned (so a chain A→B→C→D queried against D with
+    /// <c>maxDepth: 2</c> yields C at depth 1 and B at depth 2). Truncation is signaled via the
+    /// Truncated property in results. When Truncated is true, TruncatedReason distinguishes
+    /// user_limit (raise <c>--limit</c>) from safety_cap (pathological graph). See Issue #1533.
+    /// When <paramref name="withPaths"/> is true, each ImpactResult is populated with the
+    /// distinct shortest call paths from the resolved root through any intermediates to that
+    /// caller (issue #1536); converging diamond chains surface every shortest route up to
+    /// <paramref name="maxPathsPerResult"/>.
+    /// 完全一致の BFS でシンボルの推移的呼び出し元を算出。各呼び出し元とルートシンボルからの深さを返す。
+    /// <paramref name="maxDepth"/> は inclusive で、N を指定すると depth 1〜N の caller を返す
+    /// (例: A→B→C→D のチェーンで D を <c>maxDepth: 2</c> 検索すると C(depth=1) と B(depth=2) を返す)。
+    /// 結果が切り詰められた場合は Truncated フラグで通知し、TruncatedReason で
+    /// user_limit (--limit 到達、緩和で増える) と safety_cap (病的グラフ、--limit 緩和では解消しない) を区別する (#1533)。
+    /// <paramref name="withPaths"/> を true にすると、各 caller に対してルートからの推移経路
+    /// （ダイヤモンド収束時は複数）を <paramref name="maxPathsPerResult"/> 件まで付与する（issue #1536）。
+    /// </summary>
+    public (List<ImpactResult> Results, bool Truncated, string? TruncatedReason, string TerminationReason, List<ImpactCycleResult> Cycles) GetTransitiveCallers(
+        string symbolName,
+        int maxDepth = 5,
+        int limit = 50,
+        string? lang = null,
+        IReadOnlyList<string>? pathPatterns = null,
+        IReadOnlyList<string>? excludePathPatterns = null,
+        bool excludeTests = false,
+        bool withPaths = false,
+        int maxPathsPerResult = DefaultImpactPathsPerResult,
+        int resultOffset = 0,
+        bool includeMemberReads = false)
+    {
+        var request = new ImpactTraversalRequest(
+            symbolName,
+            maxDepth,
+            limit,
+            lang,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            withPaths,
+            maxPathsPerResult,
+            resultOffset,
+            includeMemberReads);
+        var root = ResolveImpactTraversalRoot(request);
+        if (root == null)
+            return ([], false, null, ImpactTerminationReasons.Completed, []);
+
+        return new ImpactTraversalEngine(this, request, root).Run();
+    }
+
+    private ImpactTraversalRoot? ResolveImpactTraversalRoot(ImpactTraversalRequest request)
+    {
+        var resolvedName = ResolveSymbolName(request.SymbolName, request.Lang);
+        var hasResolvedIdentityGraph = _referenceIdentityContractCurrent;
+        var canResolveQualifiedCSharpIdentity =
+            hasResolvedIdentityGraph
+            && SqlNameResolver.HasQualifier(request.SymbolName)
+            && request.Lang is null or "csharp";
+        var rootDefinitionLimit = canResolveQualifiedCSharpIdentity
+            ? DefaultImpactGraphStateEntryBudget
+            : request.Limit;
+        var resolution = ResolveImpactRootDefinitions(request, resolvedName, rootDefinitionLimit);
+        var definitions = resolution.Definitions;
+        var definitionPaths = definitions
+            .Select(static definition => definition.Path)
+            .ToHashSet(StringComparer.OrdinalIgnoreCase);
+        var isLogicalPartialFamily = IsLogicalPartialFamilyRoot(
+            hasResolvedIdentityGraph,
+            resolution,
+            definitions);
+        var qualifiedCSharpIds = ResolveQualifiedCSharpRootIds(
+            canResolveQualifiedCSharpIdentity,
+            isLogicalPartialFamily,
+            resolution,
+            definitions);
+
+        if (hasResolvedIdentityGraph && definitionPaths.Count > 1 && qualifiedCSharpIds.Count == 0)
+            return null;
+
+        var ambiguousMRootId = ResolveAmbiguousMRootId(
+            hasResolvedIdentityGraph,
+            request.Lang,
+            definitions);
+        var identityIds = qualifiedCSharpIds.Count > 0
+            ? qualifiedCSharpIds
+            : ambiguousMRootId is long ambiguousId
+                ? new HashSet<long> { ambiguousId }
+                : [];
+        var singleIdentityId = identityIds.Count == 1 ? identityIds.Single() : (long?)null;
+        var rootNodeKey = identityIds.Count > 1
+            ? $"identity:{NameFold.Fold(request.SymbolName) ?? request.SymbolName}"
+            : ImpactNodeIdentity.TraversalKey(singleIdentityId, resolvedName);
+        var pathNode = request.WithPaths
+            ? CreateImpactRootPathNode(
+                resolvedName,
+                singleIdentityId,
+                request.Lang,
+                isLogicalPartialFamily,
+                definitions)
+            : null;
+
+        return new ImpactTraversalRoot(
+            resolvedName,
+            definitionPaths,
+            hasResolvedIdentityGraph,
+            isLogicalPartialFamily,
+            identityIds,
+            ambiguousMRootId != null,
+            !isLogicalPartialFamily
+                && qualifiedCSharpIds.Count > 0
+                && resolution.PhysicalSymbolIdsTruncated,
+            rootNodeKey,
+            pathNode);
+    }
+
+    private ImpactDefinitionResolution ResolveImpactRootDefinitions(
+        ImpactTraversalRequest request,
+        string resolvedName,
+        int definitionLimit)
+    {
+        var resolution = ResolveImpactDefinitions(
+            request.SymbolName,
+            definitionLimit,
+            request.Lang,
+            request.PathPatterns,
+            request.ExcludePathPatterns,
+            request.ExcludeTests);
+        if (resolution.Definitions.Count == 0
+            && !string.Equals(request.SymbolName, resolvedName, StringComparison.Ordinal))
+        {
+            resolution = ResolveImpactDefinitions(
+                resolvedName,
+                definitionLimit,
+                request.Lang,
+                request.PathPatterns,
+                request.ExcludePathPatterns,
+                request.ExcludeTests);
+        }
+        return resolution;
+    }
+
+    private static bool IsLogicalPartialFamilyRoot(
+        bool hasResolvedIdentityGraph,
+        ImpactDefinitionResolution resolution,
+        IReadOnlyList<SymbolResult> definitions)
+        => hasResolvedIdentityGraph
+           && resolution.LogicalCount == 1
+           && definitions.Count == 1
+           && definitions[0].Lang == "csharp"
+           && definitions[0].PartialFamilyId != null
+           && resolution.PhysicalSymbolIds.Count > 0;
+
+    private static HashSet<long> ResolveQualifiedCSharpRootIds(
+        bool canResolveQualifiedCSharpIdentity,
+        bool isLogicalPartialFamily,
+        ImpactDefinitionResolution resolution,
+        IReadOnlyList<SymbolResult> definitions)
+        => (canResolveQualifiedCSharpIdentity || isLogicalPartialFamily)
+           && definitions.Count > 0
+           && definitions.All(static definition => definition.Lang == "csharp")
+           && definitions.All(static definition => definition.SymbolId != null)
+           && (isLogicalPartialFamily || resolution.LogicalCount == definitions.Count)
+            ? resolution.PhysicalSymbolIds.ToHashSet()
+            : [];
+
+    private static long? ResolveAmbiguousMRootId(
+        bool hasResolvedIdentityGraph,
+        string? lang,
+        IReadOnlyList<SymbolResult> definitions)
+        => hasResolvedIdentityGraph
+           && definitions.Count == 1
+           && lang is "matlab" or "objc"
+           && string.Equals(definitions[0].Lang, lang, StringComparison.Ordinal)
+            ? definitions[0].SymbolId
+            : null;
+
+    private ImpactPathNode CreateImpactRootPathNode(
+        string resolvedName,
+        long? symbolId,
+        string? lang,
+        bool isLogicalPartialFamily,
+        IReadOnlyList<SymbolResult> definitions)
+    {
+        var node = ResolveImpactPathNode(
+            resolvedName,
+            symbolId,
+            kind: null,
+            lang,
+            referencePath: null,
+            referenceLine: null);
+        if (!isLogicalPartialFamily)
+            return node;
+
+        var representative = definitions[0];
+        node.SymbolId = null;
+        node.Name = resolvedName;
+        node.Kind = representative.Kind;
+        node.Lang = representative.Lang;
+        node.DefinitionPath = representative.Path;
+        node.DefinitionLine = representative.Line;
+        node.Container = representative.ContainerQualifiedName ?? representative.ContainerName;
+        node.PartialFamilyId = representative.PartialFamilyId;
+        node.LogicalTargetKey = $"partial|{representative.PartialFamilyId}";
+        return node;
+    }
+
+    private List<CallerResult> ReadImpactCallerPage(
+        in ImpactTraversalFrontierNode node,
+        ImpactTraversalRequest request,
+        int pageSize,
+        int pageOffset,
+        bool includeAmbiguousMSource)
+    {
+        IReadOnlyList<long>? targetIds = node.TargetSymbolIds is { Count: > 0 }
+            ? node.TargetSymbolIds
+            : node.SymbolId is long symbolId
+                ? [symbolId]
+                : null;
+        return GetCallersExactCore(
+            node.Symbol,
+            pageSize,
+            pageOffset,
+            request.Lang,
+            request.PathPatterns,
+            request.ExcludePathPatterns,
+            request.ExcludeTests,
+            targetIds,
+            includeAmbiguousMSource,
+            request.IncludeMemberReads);
+    }
+
+    private int GetImpactGraphStateEntryBudget(int limit)
+    {
+        if (ImpactGraphStateEntryBudgetForTesting is int testBudget)
+            return testBudget;
+        var limitScaled = Math.Max(1, limit) * 200;
+        return Math.Max(1024, Math.Min(DefaultImpactGraphStateEntryBudget, limitScaled));
+    }
+
+    private int GetImpactBoundaryCallerProbeBudget()
+        => ImpactBoundaryCallerProbeBudgetForTesting ?? ImpactBoundaryCallerProbeBudget;
+}
diff --git a/tests/CodeIndex.Tests/DbReaderImpactTests.cs b/tests/CodeIndex.Tests/DbReaderImpactTests.cs
index 018cfad7b..82536b162 100644
--- a/tests/CodeIndex.Tests/DbReaderImpactTests.cs
+++ b/tests/CodeIndex.Tests/DbReaderImpactTests.cs
@@ -647,6 +647,7 @@ public void AnalyzeImpact_UserLimitTruncation_PropagatesTruncatedReason()
 
         Assert.True(analysis.Truncated);
         Assert.Equal(ImpactTruncatedReasons.UserLimit, analysis.TruncatedReason);
+        Assert.Equal(ImpactTerminationReasons.RowLimitTruncated, analysis.TerminationReason);
         Assert.Equal(2, analysis.Callers.Count);
     }
 
diff --git a/tests/CodeIndex.Tests/DbReaderTests.cs b/tests/CodeIndex.Tests/DbReaderTests.cs
index 123be1372..682a07935 100644
--- a/tests/CodeIndex.Tests/DbReaderTests.cs
+++ b/tests/CodeIndex.Tests/DbReaderTests.cs
@@ -5454,6 +5454,38 @@ public static class ImpactCallCycle
         Assert.Equal(1, caller.Depth);
     }
 
+    [Fact]
+    public void GetTransitiveCallers_GraphStateBudgetTerminatesAfterCycleState()
+    {
+        InsertIndexedFile("src/impact_graph_state_budget.cs", "csharp",
+            """
+            public static class ImpactGraphStateBudget
+            {
+                public static void ImpactGraphBudgetRoot() { ImpactGraphBudgetRoot(); }
+                public static void ImpactGraphBudgetZed() { ImpactGraphBudgetRoot(); }
+            }
+            """);
+        _writer.ClearReferenceIdentityContractReady();
+        using var reader = new DbReader(_db.Connection)
+        {
+            ImpactGraphStateEntryBudgetForTesting = 3,
+        };
+
+        var (results, truncated, truncatedReason, terminationReason, cycles) =
+            reader.GetTransitiveCallers(
+                "ImpactGraphBudgetRoot",
+                maxDepth: 1,
+                limit: 10,
+                lang: "csharp",
+                pathPatterns: ["src/*impact_graph_state_budget*"]);
+
+        Assert.Equal("ImpactGraphBudgetZed", Assert.Single(results).CallerName);
+        Assert.NotEmpty(cycles);
+        Assert.True(truncated);
+        Assert.Equal(ImpactTruncatedReasons.GraphStateBudget, truncatedReason);
+        Assert.Equal(ImpactTerminationReasons.GraphStateBudget, terminationReason);
+    }
+
     [Fact]
     public void GetCallers_ReportsAndCanExcludeSelfReferences()
     {
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerImpactTests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerImpactTests.cs
index c468b4d97..271ace613 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerImpactTests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerImpactTests.cs
@@ -1,4 +1,3 @@
-using System.Reflection;
 using System.Text.Json;
 using CodeIndex.Cli;
 using CodeIndex.Database;
@@ -196,7 +195,7 @@ public void GetTransitiveCallers_MaxDepthBoundaryProbeBudgetTerminatesStably_Iss
             });
 
             var references = new List<ReferenceRecord>();
-            for (var i = 0; i < ImpactBoundaryCallerProbeSourceCount(); i++)
+            for (var i = 0; i < 3; i++)
             {
                 references.Add(new ReferenceRecord
                 {
@@ -207,66 +206,57 @@ public void GetTransitiveCallers_MaxDepthBoundaryProbeBudgetTerminatesStably_Iss
                     Column = 1,
                     Context = $"Caller{i}();",
                     ContainerKind = "function",
-                    ContainerName = $"Caller{i}",
+                    ContainerName = $"A{i}",
                 });
-
-                if (i == 0)
-                    continue;
-
                 references.Add(new ReferenceRecord
                 {
                     FileId = fileId,
-                    SymbolName = "Caller0",
+                    SymbolName = "ZBoundary",
                     ReferenceKind = "call",
                     Line = i + 1,
                     Column = 1,
-                    Context = $"Caller{i}();",
+                    Context = "ZBoundary();",
                     ContainerKind = "function",
-                    ContainerName = $"Caller{i}",
+                    ContainerName = $"A{i}",
                 });
             }
+            references.Add(new ReferenceRecord
+            {
+                FileId = fileId,
+                SymbolName = "Root",
+                ReferenceKind = "call",
+                Line = 4,
+                Column = 1,
+                Context = "Root();",
+                ContainerKind = "function",
+                ContainerName = "ZBoundary",
+            });
 
             writer.InsertReferences(references);
             writer.MarkGraphReady();
-            using var reader = new DbReader(db.Connection);
-            var visited = Enumerable.Range(1, ImpactBoundaryCallerProbeSourceCount() - 1)
-                .Select(i => $"src/Dense.cs:Caller{i}:call")
-                .ToHashSet(StringComparer.OrdinalIgnoreCase);
-            var method = typeof(DbReader).GetMethod("InspectBoundaryCallers", BindingFlags.Instance | BindingFlags.NonPublic);
-            Assert.NotNull(method);
-
-            var inspection = method!.Invoke(reader,
-            [
-                "Caller0",
-                null,
-                "Root",
-                new HashSet<string>(StringComparer.OrdinalIgnoreCase),
-                null,
-                visited,
-                new Dictionary<string, HashSet<string>>(StringComparer.Ordinal),
-                new Dictionary<string, ImpactCycleMemberResult>(StringComparer.Ordinal),
-                new List<ImpactCycleResult>(),
-                new HashSet<string>(StringComparer.Ordinal),
-                false,
-                "csharp",
-                null,
-                null,
-                false,
-                false,
-                false,
-            ]);
-            Assert.NotNull(inspection);
-            var type = inspection!.GetType();
-
-            Assert.True((bool)type.GetProperty("HasUnvisitedCaller")!.GetValue(inspection)!);
-            Assert.True((bool)type.GetProperty("ProbeBudgetHit")!.GetValue(inspection)!);
+            using var reader = new DbReader(db.Connection)
+            {
+                ImpactBoundaryCallerProbeBudgetForTesting = 3,
+            };
+
+            var (results, truncated, truncatedReason, terminationReason, cycles) =
+                reader.GetTransitiveCallers(
+                    "Root",
+                    maxDepth: 1,
+                    limit: 10,
+                    lang: "csharp",
+                    pathPatterns: ["src/Dense.cs"]);
+
+            Assert.Equal(4, results.Count);
+            Assert.True(truncated);
+            Assert.Equal(ImpactTruncatedReasons.BoundaryProbeBudget, truncatedReason);
+            Assert.Equal(ImpactTerminationReasons.BoundaryProbeBudget, terminationReason);
+            Assert.Empty(cycles);
         }
         finally
         {
             TestProjectHelper.DeleteDirectory(projectRoot);
         }
-
-        static int ImpactBoundaryCallerProbeSourceCount() => DbReader.ImpactBoundaryCallerProbeBudget + 100;
     }
 
     [Fact]

From 06ff15db4474ffbf67f9930a2a693ab9b2e671de Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 10:59:39 +0900
Subject: [PATCH 15/45] Decompose cross-language type reference extraction

---
 .../ReferenceExtractor.CoreReferencePhases.cs |   4 +-
 ...renceExtractor.CoreTypeCSharpReferences.cs | 173 +++++++
 ...ctor.CoreTypeConsumedLanguageReferences.cs |  71 +++
 ...enceExtractor.CoreTypePreludeReferences.cs | 176 ++++++++
 ...actor.CoreTypePrimaryLanguageReferences.cs | 143 ++++++
 .../ReferenceExtractor.CoreTypeReferences.cs  | 426 +++---------------
 ...tor.CoreTypeSecondaryLanguageReferences.cs |  74 +++
 .../ReferenceExtractor.ReferenceRecords.cs    | 106 -----
 8 files changed, 708 insertions(+), 465 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeCSharpReferences.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeConsumedLanguageReferences.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypePreludeReferences.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypePrimaryLanguageReferences.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeSecondaryLanguageReferences.cs

diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
index 80bc5d09d..85693045c 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
@@ -54,7 +54,7 @@ private static CoreReferenceLineFlow EmitCoreInitialReferencePhases(
             return CoreReferenceLineFlow.StopExtraction;
 
         var typeContext = new CoreTypeReferenceContext(
-            line,
+            in line,
             loop.Lookups,
             loop.ContainerCandidates,
             request.Symbols,
@@ -80,7 +80,7 @@ private static CoreReferenceLineFlow EmitCoreInitialReferencePhases(
             state.XamlBindingPropertyElementState,
             state.XamlBindingMarkupExtensionState);
         if (EmitCoreTypeReferences(
-                typeContext,
+                in typeContext,
                 ref state.PendingCSharpMultiLineTypePattern,
                 ref state.XamlInXmlComment))
         {
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeCSharpReferences.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeCSharpReferences.cs
new file mode 100644
index 000000000..75b2aac8e
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeCSharpReferences.cs
@@ -0,0 +1,173 @@
+using System.Text.RegularExpressions;
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitCoreCSharpTypeReferences(
+        in CoreTypeReferenceContext type,
+        ref CSharpMultiLineTypePatternState pendingCSharpMultiLineTypePattern)
+    {
+        ref readonly var line = ref type.Line;
+        if (line.Language is not "csharp")
+            return;
+
+        if (line.PreparedLine.IndexOf("=>", StringComparison.Ordinal) >= 0)
+        {
+            EmitCSharpLambdaCaptureReferences(
+                line.PreparedLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.Container,
+                type.CSharpLocalNamesByFunction);
+        }
+
+        CSharpReferenceExtractor.EmitTypePositionReferences(
+            line.PreparedLine,
+            line.OriginalLine,
+            type.CSharpQualifiedConstantPatternMemberLookup,
+            type.CSharpQualifiedTypePatternLookup,
+            type.CSharpUsingAliases,
+            type.CSharpUsingStatics,
+            type.Lookups.HasActiveSameFileCSharpTypeCandidate,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall,
+            line.Container,
+            type.PendingCSharpWhereConstraint!,
+            ref pendingCSharpMultiLineTypePattern);
+
+        if (CSharpReferenceExtractor.HasTrailingIsAsTypePatternIntro(line.PreparedLine, line.OriginalLine))
+        {
+            CSharpReferenceExtractor.StartWaitingForMultiLineTypePatternHead(
+                ref pendingCSharpMultiLineTypePattern);
+        }
+
+        if (CSharpReferenceExtractor.HasTrailingCaseTypePatternIntro(line.PreparedLine, line.OriginalLine))
+        {
+            CSharpReferenceExtractor.StartWaitingForMultiLineTypePatternHead(
+                ref pendingCSharpMultiLineTypePattern);
+        }
+
+        TrackCSharpLocalDeclarations(
+            line.PreparedLine,
+            line.Container,
+            type.CSharpLocalNamesByFunction);
+    }
+
+    private static void EmitCSharpLambdaCaptureReferences(
+        string preparedLine,
+        List<ReferenceRecord> references,
+        ReferenceDedupeSet seen,
+        long fileId,
+        string context,
+        int lineNumber,
+        SymbolRecord? container,
+        Dictionary<string, HashSet<string>>? localNamesByFunction)
+    {
+        if (container?.Kind != "function"
+            || localNamesByFunction == null
+            || !localNamesByFunction.TryGetValue(GetCSharpContainerLocalScopeKey(container), out var localNames)
+            || localNames.Count == 0)
+        {
+            return;
+        }
+
+        foreach (Match lambda in BoundedRegex.EnumerateMatches(CSharpLambdaRegex, preparedLine))
+        {
+            var body = lambda.Groups["body"].Value;
+            if (string.IsNullOrWhiteSpace(body))
+                continue;
+
+            var parameterNames = CollectCSharpLambdaParameterNames(lambda.Groups["params"].Value);
+            foreach (var localName in localNames)
+            {
+                if (parameterNames.Contains(localName))
+                    continue;
+                if (!ContainsCSharpIdentifier(body, localName, out var bodyRelativeIndex))
+                    continue;
+
+                AddReference(
+                    references,
+                    seen,
+                    fileId,
+                    localName,
+                    lambda.Groups["body"].Index + bodyRelativeIndex,
+                    "capture",
+                    context,
+                    lineNumber,
+                    container,
+                    "csharp");
+            }
+        }
+    }
+
+    private static HashSet<string> CollectCSharpLambdaParameterNames(string parameterText)
+    {
+        var names = new HashSet<string>(StringComparer.Ordinal);
+        foreach (Match match in BoundedRegex.EnumerateMatches(parameterText, CSharpIdentifierPattern))
+        {
+            var name = NormalizeAtPrefixedIdentifier(match.Value);
+            if (!IsIgnoredCallName("csharp", name))
+                names.Add(name);
+        }
+
+        return names;
+    }
+
+    private static bool ContainsCSharpIdentifier(string text, string name, out int index)
+    {
+        index = -1;
+        var normalizedName = NormalizeAtPrefixedIdentifier(name);
+        foreach (Match match in BoundedRegex.EnumerateMatches(text, CSharpIdentifierPattern))
+        {
+            if (string.Equals(
+                    NormalizeAtPrefixedIdentifier(match.Value),
+                    normalizedName,
+                    StringComparison.Ordinal))
+            {
+                index = match.Index;
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private static void TrackCSharpLocalDeclarations(
+        string preparedLine,
+        SymbolRecord? container,
+        Dictionary<string, HashSet<string>>? localNamesByFunction)
+    {
+        if (container?.Kind != "function" || localNamesByFunction == null)
+            return;
+        if (preparedLine.Contains("=>", StringComparison.Ordinal))
+            return;
+
+        foreach (Match match in BoundedRegex.EnumerateMatches(CSharpLocalDeclarationRegex, preparedLine))
+        {
+            var name = NormalizeAtPrefixedIdentifier(match.Groups["name"].Value);
+            if (IsIgnoredCallName("csharp", name))
+                continue;
+
+            var scopeKey = GetCSharpContainerLocalScopeKey(container);
+            if (!localNamesByFunction.TryGetValue(scopeKey, out var localNames))
+            {
+                localNames = new HashSet<string>(StringComparer.Ordinal);
+                localNamesByFunction[scopeKey] = localNames;
+            }
+
+            localNames.Add(name);
+        }
+    }
+
+    private static string GetCSharpContainerLocalScopeKey(SymbolRecord container)
+        => $"{container.Kind}:{container.ContainerQualifiedName}:{container.ContainerKind}:{container.ContainerName}:{container.Name}:{container.StartLine}:{container.EndLine}:{container.BodyStartLine}:{container.BodyEndLine}:{container.StartColumn}";
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeConsumedLanguageReferences.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeConsumedLanguageReferences.cs
new file mode 100644
index 000000000..04e82d734
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeConsumedLanguageReferences.cs
@@ -0,0 +1,71 @@
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static bool EmitCoreConsumedLanguageTypeReferences(
+        in CoreTypeReferenceContext type,
+        ref bool xamlInXmlComment)
+    {
+        ref readonly var line = ref type.Line;
+        switch (line.Language)
+        {
+            case "css":
+                CssReferenceExtractor.EmitCss(
+                    line.PreparedLine,
+                    line.OriginalLine,
+                    line.Context,
+                    line.LineNumber,
+                    line.References,
+                    line.Seen,
+                    line.FileId,
+                    line.DefinitionNames,
+                    line.Container);
+                return false;
+            case "sass":
+                CssReferenceExtractor.EmitSass(
+                    line.PreparedLine,
+                    type.OriginalLineForLanguage,
+                    line.References,
+                    line.Seen,
+                    line.FileId,
+                    line.Context,
+                    line.LineNumber,
+                    line.Container);
+                return true;
+            case "stylus":
+                CssReferenceExtractor.EmitStylus(
+                    line.PreparedLine,
+                    type.OriginalLineForLanguage,
+                    line.References,
+                    line.Seen,
+                    line.FileId,
+                    line.Context,
+                    line.LineNumber,
+                    type.AllDefinitionNames,
+                    type.StylusVariableDefinitionNames,
+                    line.Container);
+                return true;
+            case "xml":
+                if (type.XamlReferenceEnabled)
+                {
+                    var xamlLine = XamlReferenceExtractor.StripXmlComments(
+                        line.OriginalLine,
+                        ref xamlInXmlComment);
+                    XamlReferenceExtractor.Emit(
+                        xamlLine,
+                        line.Context,
+                        line.LineNumber,
+                        line.References,
+                        line.Seen,
+                        line.FileId,
+                        line.Container,
+                        type.XamlBindingPropertyElementState!,
+                        type.XamlBindingMarkupExtensionState!);
+                }
+
+                return true;
+            default:
+                return false;
+        }
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypePreludeReferences.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypePreludeReferences.cs
new file mode 100644
index 000000000..7c08fa15b
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypePreludeReferences.cs
@@ -0,0 +1,176 @@
+using System.Text.RegularExpressions;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitCoreTypePreludeReferences(
+        in CoreTypeReferenceContext type,
+        ref CSharpMultiLineTypePatternState pendingCSharpMultiLineTypePattern)
+    {
+        AdvanceCoreCSharpMultiLineTypePattern(in type, ref pendingCSharpMultiLineTypePattern);
+        EmitCoreCSharpEventReferences(in type);
+        EmitCoreConstructorChainReferences(in type);
+        EmitCoreCompileTimeTypeReferences(in type);
+
+        ref readonly var line = ref type.Line;
+        if (line.Language is "csharp" or "java" or "kotlin")
+        {
+            EmitCatchTypeReferences(
+                line.Language,
+                line.PreparedLine,
+                line.References,
+                line.Seen,
+                line.FileId,
+                line.Context,
+                line.LineNumber,
+                line.ResolveContainerForCall);
+        }
+    }
+
+    private static void AdvanceCoreCSharpMultiLineTypePattern(
+        in CoreTypeReferenceContext type,
+        ref CSharpMultiLineTypePatternState pendingCSharpMultiLineTypePattern)
+    {
+        ref readonly var line = ref type.Line;
+        if (line.Language is not "csharp")
+            return;
+
+        CSharpReferenceExtractor.AdvanceMultiLineTypePatternState(
+            line.PreparedLine,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall,
+            type.CSharpQualifiedConstantPatternMemberLookup,
+            type.CSharpUsingAliases,
+            type.CSharpUsingStatics,
+            type.Lookups.HasActiveSameFileCSharpTypeCandidate,
+            line.References,
+            line.Seen,
+            line.FileId,
+            ref pendingCSharpMultiLineTypePattern);
+    }
+
+    private static void EmitCoreCSharpEventReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        if (line.Language is not "csharp"
+            || (line.PreparedLine.IndexOf("+=", StringComparison.Ordinal) < 0
+                && line.PreparedLine.IndexOf("-=", StringComparison.Ordinal) < 0))
+        {
+            return;
+        }
+
+        foreach (Match match in BoundedRegex.EnumerateMatches(EventSubscriptionRegex, line.PreparedLine))
+        {
+            if (ReferenceLimitReached(line.References))
+                break;
+            var eventContainer = line.ResolveContainerForCall(match.Groups["name"].Index);
+            AddReference(
+                line.References,
+                line.Seen,
+                line.FileId,
+                match,
+                "subscribe",
+                line.Context,
+                line.LineNumber,
+                eventContainer);
+        }
+    }
+
+    private static void EmitCoreConstructorChainReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        switch (line.Language)
+        {
+            case "csharp":
+                CSharpReferenceExtractor.EmitCtorChainReferences(
+                    line.PreparedLine, type.Lookups.GetEnclosingTypeCandidates, type.ContainerCandidates,
+                    type.StructuralLines, line.References, line.Seen, line.FileId, line.Context,
+                    line.LineNumber, line.Container);
+                break;
+            case "java":
+                JavaReferenceExtractor.EmitCtorChainReferences(
+                    line.PreparedLine, type.Lookups.GetEnclosingTypeCandidates, type.Symbols,
+                    type.StructuralLines, line.References, line.Seen, line.FileId, line.Context,
+                    line.LineNumber, line.Container);
+                break;
+            case "kotlin":
+                KotlinReferenceExtractor.EmitCtorDelegationReferences(
+                    line.PreparedLine, type.Lookups.GetEnclosingTypeCandidates, type.Symbols,
+                    type.StructuralLines, line.References, line.Seen, line.FileId, line.Context,
+                    line.LineNumber, line.Container);
+                break;
+        }
+    }
+
+    private static void EmitCoreCompileTimeTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        switch (line.Language)
+        {
+            case "csharp":
+                EmitCoreCSharpCompileTimeTypeReferences(in type);
+                break;
+            case "java":
+                JavaReferenceExtractor.EmitDotClassTypeLiteralReferences(
+                    line.PreparedLine,
+                    line.References,
+                    line.Seen,
+                    line.FileId,
+                    line.Context,
+                    line.LineNumber,
+                    line.Container);
+                break;
+            case "kotlin":
+                KotlinReferenceExtractor.EmitClassLiteralReferences(
+                    line.PreparedLine,
+                    line.References,
+                    line.Seen,
+                    line.FileId,
+                    line.Context,
+                    line.LineNumber,
+                    line.Container);
+                KotlinReferenceExtractor.EmitBacktickConstructorReferences(
+                    line.PreparedLine,
+                    type.KotlinConstructorTypeNames!,
+                    line.References,
+                    line.Seen,
+                    line.FileId,
+                    line.Context,
+                    line.LineNumber,
+                    line.ResolveContainerForCall);
+                break;
+        }
+    }
+
+    private static void EmitCoreCSharpCompileTimeTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        var hasTypeKeywordIntro = line.PreparedLine.IndexOf('(') >= 0
+            && (line.PreparedLine.IndexOf("nameof", StringComparison.Ordinal) >= 0
+                || line.PreparedLine.IndexOf("typeof", StringComparison.Ordinal) >= 0
+                || line.PreparedLine.IndexOf("sizeof", StringComparison.Ordinal) >= 0
+                || line.PreparedLine.IndexOf("default", StringComparison.Ordinal) >= 0);
+        if (hasTypeKeywordIntro)
+        {
+            var genericParameterNames = CollectCSharpGenericParameterNamesForDeclaration(line.PreparedLine);
+            foreach (Match match in BoundedRegex.EnumerateMatches(CSharpTypeKeywordIntroRegex, line.PreparedLine))
+            {
+                if (ReferenceLimitReached(line.References))
+                    break;
+                int parenIndex = match.Index + match.Length - 1;
+                ExtractCSharpTypeKeywordSegments(
+                    line.References, line.Seen, line.FileId, line.PreparedLine, parenIndex + 1,
+                    line.Context, line.LineNumber, line.Container, line.Language, genericParameterNames);
+            }
+        }
+
+        if (line.OriginalLine.IndexOf('"') >= 0)
+        {
+            ExtractCSharpReflectionNameLiteralReferences(
+                line.References, line.Seen, line.FileId, line.PreparedLine, line.OriginalLine,
+                line.Context, line.LineNumber, line.Container);
+        }
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypePrimaryLanguageReferences.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypePrimaryLanguageReferences.cs
new file mode 100644
index 000000000..06c71f1eb
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypePrimaryLanguageReferences.cs
@@ -0,0 +1,143 @@
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitCorePrimaryLanguageTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        switch (line.Language)
+        {
+            case "java":
+                EmitCoreJavaTypeReferences(in type);
+                break;
+            case "typescript":
+                EmitCoreTypeScriptTypeReferences(in type);
+                break;
+            case "kotlin":
+                EmitCoreKotlinTypeReferences(in type);
+                break;
+            case "swift":
+                EmitCoreSwiftTypeReferences(in type);
+                break;
+            case "rust":
+                EmitCoreRustTypeReferences(in type);
+                break;
+        }
+    }
+
+    private static void EmitCoreJavaTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        JavaReferenceExtractor.EmitModuleDirectiveReferences(
+            line.PreparedLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall);
+
+        JavaReferenceExtractor.EmitTypePositionReferences(
+            line.PreparedLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall,
+            line.Container);
+    }
+
+    private static void EmitCoreTypeScriptTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        TypeScriptReferenceExtractor.EmitTypePositionReferences(
+            line.PreparedLines,
+            line.Lines,
+            line.LineIndex,
+            line.PreparedLine,
+            line.Lines[line.LineIndex],
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall,
+            type.TypeScriptNamespaceAliases);
+
+        TypeScriptReferenceExtractor.EmitDeclarationTypeReferences(
+            line.PreparedLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall);
+
+        TypeScriptReferenceExtractor.EmitAliasTargetReferences(
+            line.PreparedLine,
+            type.TypeScriptTypeAliases!,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall);
+    }
+
+    private static void EmitCoreKotlinTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        KotlinReferenceExtractor.EmitTypePositionReferences(
+            line.PreparedLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall);
+    }
+
+    private static void EmitCoreSwiftTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        SwiftReferenceExtractor.EmitTypePositionReferences(
+            line.PreparedLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall,
+            type.ResolveSwiftPropertyContainerForCall);
+        SwiftReferenceExtractor.EmitAliasTargetReferences(
+            line.PreparedLine,
+            type.SwiftTypeAliases!,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall);
+    }
+
+    private static void EmitCoreRustTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        var enumCandidates = type.Lookups.GetRustEnumCandidates();
+        var enumContainer = enumCandidates != null
+            ? FindInnermostContainer(enumCandidates, line.LineNumber)
+            : null;
+        var typePositionLine = RustReferenceExtractor.MaskAttributeBodies(line.PreparedLine);
+        RustReferenceExtractor.EmitTypePositionReferences(
+            typePositionLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.ResolveContainerForCall,
+            line.Container,
+            enumContainer);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeReferences.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeReferences.cs
index 9694250f2..dea06d47c 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeReferences.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeReferences.cs
@@ -1,4 +1,3 @@
-using System.Text.RegularExpressions;
 using CodeIndex.Models;
 
 namespace CodeIndex.Indexer;
@@ -6,7 +5,6 @@ namespace CodeIndex.Indexer;
 public static partial class ReferenceExtractor
 {
     private readonly record struct CoreTypeReferenceContext(
-        CoreReferenceLineContext Line,
         CoreExtractionLookups Lookups,
         IReadOnlyList<SymbolRecord> ContainerCandidates,
         IReadOnlyList<SymbolRecord> Symbols,
@@ -35,365 +33,79 @@ private readonly record struct CoreTypeReferenceContext(
         HashSet<string>? StylusVariableDefinitionNames,
         bool XamlReferenceEnabled,
         XamlReferenceExtractor.BindingPropertyElementState? XamlBindingPropertyElementState,
-        XamlReferenceExtractor.BindingMarkupExtensionState? XamlBindingMarkupExtensionState);
+        XamlReferenceExtractor.BindingMarkupExtensionState? XamlBindingMarkupExtensionState)
+    {
+        public readonly CoreReferenceLineContext Line;
+
+        public CoreTypeReferenceContext(
+            in CoreReferenceLineContext line,
+            CoreExtractionLookups lookups,
+            IReadOnlyList<SymbolRecord> containerCandidates,
+            IReadOnlyList<SymbolRecord> symbols,
+            string[] structuralLines,
+            IReadOnlyDictionary<
+                string,
+                List<(string ContainerName, string? QualifiedContainerName, bool AllowShortNameFallback)>>
+                cSharpQualifiedConstantPatternMemberLookup,
+            IReadOnlyDictionary<
+                string,
+                List<(string ContainerName, string? QualifiedContainerName, bool AllowShortNameFallback)>>
+                cSharpQualifiedTypePatternLookup,
+            IReadOnlyList<CSharpUsingAliasRecord> cSharpUsingAliases,
+            IReadOnlyList<CSharpUsingStaticRecord> cSharpUsingStatics,
+            Dictionary<string, HashSet<string>>? cSharpLocalNamesByFunction,
+            CSharpWhereConstraintState? pendingCSharpWhereConstraint,
+            HashSet<string>? kotlinConstructorTypeNames,
+            IReadOnlyList<TypeScriptReferenceExtractor.NamespaceAliasBinding> typeScriptNamespaceAliases,
+            IReadOnlyList<TypeScriptReferenceExtractor.TypeAliasBinding>? typeScriptTypeAliases,
+            IReadOnlyList<SwiftReferenceExtractor.TypeAliasBinding>? swiftTypeAliases,
+            Func<int, SymbolRecord?> resolveSwiftPropertyContainerForCall,
+            bool[]? goImportBlockLines,
+            string[]? luaReferenceLines,
+            string originalLineForLanguage,
+            IReadOnlySet<string>? allDefinitionNames,
+            HashSet<string>? stylusVariableDefinitionNames,
+            bool xamlReferenceEnabled,
+            XamlReferenceExtractor.BindingPropertyElementState? xamlBindingPropertyElementState,
+            XamlReferenceExtractor.BindingMarkupExtensionState? xamlBindingMarkupExtensionState)
+            : this(
+                lookups,
+                containerCandidates,
+                symbols,
+                structuralLines,
+                cSharpQualifiedConstantPatternMemberLookup,
+                cSharpQualifiedTypePatternLookup,
+                cSharpUsingAliases,
+                cSharpUsingStatics,
+                cSharpLocalNamesByFunction,
+                pendingCSharpWhereConstraint,
+                kotlinConstructorTypeNames,
+                typeScriptNamespaceAliases,
+                typeScriptTypeAliases,
+                swiftTypeAliases,
+                resolveSwiftPropertyContainerForCall,
+                goImportBlockLines,
+                luaReferenceLines,
+                originalLineForLanguage,
+                allDefinitionNames,
+                stylusVariableDefinitionNames,
+                xamlReferenceEnabled,
+                xamlBindingPropertyElementState,
+                xamlBindingMarkupExtensionState)
+        {
+            Line = line;
+        }
+    }
 
     private static bool EmitCoreTypeReferences(
-        CoreTypeReferenceContext type,
+        in CoreTypeReferenceContext type,
         ref CSharpMultiLineTypePatternState pendingCSharpMultiLineTypePattern,
         ref bool xamlInXmlComment)
     {
-        var line = type.Line;
-        if (line.Language == "csharp")
-        {
-            CSharpReferenceExtractor.AdvanceMultiLineTypePatternState(
-                line.PreparedLine,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall,
-                type.CSharpQualifiedConstantPatternMemberLookup,
-                type.CSharpUsingAliases,
-                type.CSharpUsingStatics,
-                type.Lookups.HasActiveSameFileCSharpTypeCandidate,
-                line.References,
-                line.Seen,
-                line.FileId,
-                ref pendingCSharpMultiLineTypePattern);
-        }
-
-        // Event subscription/unsubscription (C#) / イベント購読・解除 (C#)
-        if (line.Language is "csharp"
-            && (line.PreparedLine.IndexOf("+=", StringComparison.Ordinal) >= 0
-                || line.PreparedLine.IndexOf("-=", StringComparison.Ordinal) >= 0))
-        {
-            foreach (Match match in BoundedRegex.EnumerateMatches(EventSubscriptionRegex, line.PreparedLine))
-            {
-                if (ReferenceLimitReached(line.References))
-                    break;
-                var eventContainer = line.ResolveContainerForCall(match.Groups["name"].Index);
-                AddReference(line.References, line.Seen, line.FileId, match, "subscribe", line.Context, line.LineNumber, eventContainer);
-            }
-        }
-
-        // Constructor chain-call rewrites: C# `: this(...)` / `: base(...)`, Java `this(...)` / `super(...)`,
-        // and Kotlin `constructor(...) : this(...)` / `: super(...)`.
-        // コンストラクタ連鎖呼び出しの書き換え
-        if (line.Language is "csharp")
-        {
-            CSharpReferenceExtractor.EmitCtorChainReferences(
-                line.PreparedLine, type.Lookups.GetEnclosingTypeCandidates, type.ContainerCandidates,
-                type.StructuralLines, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
-        }
-        else if (line.Language is "java")
-        {
-            JavaReferenceExtractor.EmitCtorChainReferences(
-                line.PreparedLine, type.Lookups.GetEnclosingTypeCandidates, type.Symbols, type.StructuralLines,
-                line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
-        }
-        else if (line.Language is "kotlin")
-        {
-            KotlinReferenceExtractor.EmitCtorDelegationReferences(
-                line.PreparedLine, type.Lookups.GetEnclosingTypeCandidates, type.Symbols, type.StructuralLines,
-                line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
-        }
-
-        // Compile-time type/member line.References that CallRegex cannot see because the
-        // argument has no trailing `(` of its own. See issue #253.
-        // 末尾の `(` を持たず CallRegex では取れないコンパイル時の型/メンバ参照。issue #253 参照。
-        if (line.Language is "csharp")
-        {
-            var hasTypeKeywordIntro = line.PreparedLine.IndexOf('(') >= 0
-                && (line.PreparedLine.IndexOf("nameof", StringComparison.Ordinal) >= 0
-                    || line.PreparedLine.IndexOf("typeof", StringComparison.Ordinal) >= 0
-                    || line.PreparedLine.IndexOf("sizeof", StringComparison.Ordinal) >= 0
-                    || line.PreparedLine.IndexOf("default", StringComparison.Ordinal) >= 0);
-            if (hasTypeKeywordIntro)
-            {
-                var csharpGenericParameterNames = CollectCSharpGenericParameterNamesForDeclaration(line.PreparedLine);
-                foreach (Match match in BoundedRegex.EnumerateMatches(CSharpTypeKeywordIntroRegex, line.PreparedLine))
-                {
-                    if (ReferenceLimitReached(line.References))
-                        break;
-                    int parenIndex = match.Index + match.Length - 1; // position of '(' / '(' の位置
-                    ExtractCSharpTypeKeywordSegments(
-                        line.References, line.Seen, line.FileId, line.PreparedLine, parenIndex + 1,
-                        line.Context, line.LineNumber, line.Container, line.Language, csharpGenericParameterNames);
-                }
-            }
-
-            if (line.OriginalLine.IndexOf('"') >= 0)
-            {
-                ExtractCSharpReflectionNameLiteralReferences(
-                    line.References, line.Seen, line.FileId, line.PreparedLine, line.OriginalLine, line.Context, line.LineNumber, line.Container);
-            }
-        }
-        else if (line.Language is "java")
-        {
-            JavaReferenceExtractor.EmitDotClassTypeLiteralReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-        }
-        else if (line.Language is "kotlin")
-        {
-            KotlinReferenceExtractor.EmitClassLiteralReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-            KotlinReferenceExtractor.EmitBacktickConstructorReferences(
-                line.PreparedLine,
-                type.KotlinConstructorTypeNames!,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-        }
-
-        // Type-position line.References without an introducing keyword-call: base lists,
-        // declaration types, generic constraints, throws clauses, type tests, and
-        // XML-doc crefs. These are dependency edges for `line.References` / `impact`, but
-        // not invocation edges for default `callers` / `callees`. See issue #256.
-        // キーワード呼び出しの外にある型位置参照（継承リスト、宣言型、generic 制約、
-        // throws、型テスト、XML doc cref）。`line.References` / `impact` では依存として扱うが、
-        // 既定の `callers` / `callees` では呼び出しエッジではない。issue #256 参照。
-        if (line.Language is "csharp" or "java" or "kotlin")
-        {
-            EmitCatchTypeReferences(
-                line.Language,
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-        }
-
-        if (line.Language == "csharp")
-        {
-            if (line.PreparedLine.IndexOf("=>", StringComparison.Ordinal) >= 0)
-            {
-                EmitCSharpLambdaCaptureReferences(
-                    line.PreparedLine,
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    line.Context,
-                    line.LineNumber,
-                    line.Container,
-                    type.CSharpLocalNamesByFunction);
-            }
-
-            CSharpReferenceExtractor.EmitTypePositionReferences(
-                line.PreparedLine,
-                line.OriginalLine,
-                type.CSharpQualifiedConstantPatternMemberLookup,
-                type.CSharpQualifiedTypePatternLookup,
-                type.CSharpUsingAliases,
-                type.CSharpUsingStatics,
-                type.Lookups.HasActiveSameFileCSharpTypeCandidate,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall,
-                line.Container,
-                type.PendingCSharpWhereConstraint!,
-                ref pendingCSharpMultiLineTypePattern);
-
-            if (CSharpReferenceExtractor.HasTrailingIsAsTypePatternIntro(line.PreparedLine, line.OriginalLine))
-            {
-                CSharpReferenceExtractor.StartWaitingForMultiLineTypePatternHead(ref pendingCSharpMultiLineTypePattern);
-            }
-
-            if (CSharpReferenceExtractor.HasTrailingCaseTypePatternIntro(line.PreparedLine, line.OriginalLine))
-            {
-                CSharpReferenceExtractor.StartWaitingForMultiLineTypePatternHead(ref pendingCSharpMultiLineTypePattern);
-            }
-
-            TrackCSharpLocalDeclarations(line.PreparedLine, line.Container, type.CSharpLocalNamesByFunction);
-        }
-        else if (line.Language == "java")
-        {
-            JavaReferenceExtractor.EmitModuleDirectiveReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-
-            JavaReferenceExtractor.EmitTypePositionReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall,
-                line.Container);
-        }
-        else if (line.Language == "typescript")
-        {
-            TypeScriptReferenceExtractor.EmitTypePositionReferences(
-                line.PreparedLines,
-                line.Lines,
-                line.LineIndex,
-                line.PreparedLine,
-                line.Lines[line.LineIndex],
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall,
-                type.TypeScriptNamespaceAliases);
-
-            TypeScriptReferenceExtractor.EmitDeclarationTypeReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-
-            TypeScriptReferenceExtractor.EmitAliasTargetReferences(
-                line.PreparedLine,
-                type.TypeScriptTypeAliases!,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-        }
-        else if (line.Language == "kotlin")
-        {
-            KotlinReferenceExtractor.EmitTypePositionReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-        }
-        else if (line.Language == "swift")
-        {
-            SwiftReferenceExtractor.EmitTypePositionReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall,
-                type.ResolveSwiftPropertyContainerForCall);
-            SwiftReferenceExtractor.EmitAliasTargetReferences(
-                line.PreparedLine,
-                type.SwiftTypeAliases!,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-        }
-        else if (line.Language == "rust")
-        {
-            var rustEnumCandidatesForLine = type.Lookups.GetRustEnumCandidates();
-            var rustEnumContainer = rustEnumCandidatesForLine != null
-                ? FindInnermostContainer(rustEnumCandidatesForLine, line.LineNumber)
-                : null;
-            var rustTypePositionLine = RustReferenceExtractor.MaskAttributeBodies(line.PreparedLine);
-            RustReferenceExtractor.EmitTypePositionReferences(
-                rustTypePositionLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall,
-                line.Container,
-                rustEnumContainer);
-        }
-        else if (line.Language == "c")
-            CReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.OriginalLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall);
-        else if (line.Language == "cpp")
-            CppReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.OriginalLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall);
-        else if (line.Language == "go")
-        {
-            GoReferenceExtractor.EmitConcurrencyReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.ResolveContainerForCall);
-            GoReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.OriginalLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall, type.GoImportBlockLines?[line.LineIndex] == true);
-        }
-        else if (line.Language == "dart")
-            DartReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall);
-        else if (line.Language == "vb")
-            VisualBasicReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall);
-        else if (line.Language == "fortran")
-            FortranReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.OriginalLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall, line.Container);
-        else if (line.Language == "pascal")
-            PascalReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall, line.Container);
-        else if (line.Language == "objc")
-            ObjectiveCReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall, line.Container);
-        else if (line.Language == "haskell")
-            HaskellReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
-        else if (line.Language == "elixir")
-            ElixirReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
-        else if (line.Language == "lua")
-            LuaReferenceExtractor.EmitTypePositionReferences(type.LuaReferenceLines?[line.LineIndex] ?? line.OriginalLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
-        else if (line.Language == "css")
-        {
-            CssReferenceExtractor.EmitCss(
-                line.PreparedLine,
-                line.OriginalLine,
-                line.Context,
-                line.LineNumber,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.DefinitionNames,
-                line.Container);
-        }
-        else if (line.Language == "sass")
-        {
-            CssReferenceExtractor.EmitSass(line.PreparedLine, type.OriginalLineForLanguage, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
-            return true;
-        }
-        else if (line.Language == "stylus")
-        {
-            CssReferenceExtractor.EmitStylus(line.PreparedLine, type.OriginalLineForLanguage, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, type.AllDefinitionNames, type.StylusVariableDefinitionNames, line.Container);
-            return true;
-        }
-        else if (line.Language == "xml" && type.XamlReferenceEnabled)
-        {
-            var xamlLine = XamlReferenceExtractor.StripXmlComments(line.OriginalLine, ref xamlInXmlComment);
-            XamlReferenceExtractor.Emit(xamlLine, line.Context, line.LineNumber, line.References, line.Seen, line.FileId, line.Container, type.XamlBindingPropertyElementState!, type.XamlBindingMarkupExtensionState!);
-            return true;
-        }
-        else if (line.Language == "xml")
-        {
-            return true;
-        }
-        return false;
+        EmitCoreTypePreludeReferences(in type, ref pendingCSharpMultiLineTypePattern);
+        EmitCoreCSharpTypeReferences(in type, ref pendingCSharpMultiLineTypePattern);
+        EmitCorePrimaryLanguageTypeReferences(in type);
+        EmitCoreSecondaryLanguageTypeReferences(in type);
+        return EmitCoreConsumedLanguageTypeReferences(in type, ref xamlInXmlComment);
     }
 }
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeSecondaryLanguageReferences.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeSecondaryLanguageReferences.cs
new file mode 100644
index 000000000..c75f4fa4c
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreTypeSecondaryLanguageReferences.cs
@@ -0,0 +1,74 @@
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitCoreSecondaryLanguageTypeReferences(in CoreTypeReferenceContext type)
+    {
+        EmitCoreCAndGoTypeReferences(in type);
+        EmitCoreAdditionalLanguageTypeReferences(in type);
+    }
+
+    private static void EmitCoreCAndGoTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        switch (line.Language)
+        {
+            case "c":
+                CReferenceExtractor.EmitTypePositionReferences(
+                    line.PreparedLine, line.OriginalLine, line.References, line.Seen, line.FileId,
+                    line.Context, line.LineNumber, line.ResolveContainerForCall);
+                break;
+            case "cpp":
+                CppReferenceExtractor.EmitTypePositionReferences(
+                    line.PreparedLine, line.OriginalLine, line.References, line.Seen, line.FileId,
+                    line.Context, line.LineNumber, line.ResolveContainerForCall);
+                break;
+            case "go":
+                GoReferenceExtractor.EmitConcurrencyReferences(
+                    line.PreparedLine,
+                    line.References,
+                    line.Seen,
+                    line.FileId,
+                    line.Context,
+                    line.LineNumber,
+                    line.ResolveContainerForCall);
+                GoReferenceExtractor.EmitTypePositionReferences(
+                    line.PreparedLine, line.OriginalLine, line.References, line.Seen, line.FileId,
+                    line.Context, line.LineNumber, line.ResolveContainerForCall,
+                    type.GoImportBlockLines?[line.LineIndex] == true);
+                break;
+        }
+    }
+
+    private static void EmitCoreAdditionalLanguageTypeReferences(in CoreTypeReferenceContext type)
+    {
+        ref readonly var line = ref type.Line;
+        switch (line.Language)
+        {
+            case "dart":
+                DartReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall);
+                break;
+            case "vb":
+                VisualBasicReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall);
+                break;
+            case "fortran":
+                FortranReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.OriginalLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall, line.Container);
+                break;
+            case "pascal":
+                PascalReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall, line.Container);
+                break;
+            case "objc":
+                ObjectiveCReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.ResolveContainerForCall, line.Container);
+                break;
+            case "haskell":
+                HaskellReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
+                break;
+            case "elixir":
+                ElixirReferenceExtractor.EmitTypePositionReferences(line.PreparedLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
+                break;
+            case "lua":
+                LuaReferenceExtractor.EmitTypePositionReferences(type.LuaReferenceLines?[line.LineIndex] ?? line.OriginalLine, line.References, line.Seen, line.FileId, line.Context, line.LineNumber, line.Container);
+                break;
+        }
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.ReferenceRecords.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.ReferenceRecords.cs
index 92fa1b355..02b1c361d 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.ReferenceRecords.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.ReferenceRecords.cs
@@ -360,112 +360,6 @@ internal static void CompactCSharpUsingAliasReferences(List<ReferenceRecord> ref
             references.RemoveRange(writeIndex, referenceCount - writeIndex);
     }
 
-    private static void EmitCSharpLambdaCaptureReferences(
-        string preparedLine,
-        List<ReferenceRecord> references,
-        ReferenceDedupeSet seen,
-        long fileId,
-        string context,
-        int lineNumber,
-        SymbolRecord? container,
-        Dictionary<string, HashSet<string>>? localNamesByFunction)
-    {
-        if (container?.Kind != "function"
-            || localNamesByFunction == null
-            || !localNamesByFunction.TryGetValue(GetCSharpContainerLocalScopeKey(container), out var localNames)
-            || localNames.Count == 0)
-        {
-            return;
-        }
-
-        foreach (Match lambda in BoundedRegex.EnumerateMatches(CSharpLambdaRegex, preparedLine))
-        {
-            var body = lambda.Groups["body"].Value;
-            if (string.IsNullOrWhiteSpace(body))
-                continue;
-
-            var parameterNames = CollectCSharpLambdaParameterNames(lambda.Groups["params"].Value);
-            foreach (var localName in localNames)
-            {
-                if (parameterNames.Contains(localName))
-                    continue;
-                if (!ContainsCSharpIdentifier(body, localName, out var bodyRelativeIndex))
-                    continue;
-
-                AddReference(
-                    references,
-                    seen,
-                    fileId,
-                    localName,
-                    lambda.Groups["body"].Index + bodyRelativeIndex,
-                    "capture",
-                    context,
-                    lineNumber,
-                    container,
-                    "csharp");
-            }
-        }
-    }
-
-    private static HashSet<string> CollectCSharpLambdaParameterNames(string parameterText)
-    {
-        var names = new HashSet<string>(StringComparer.Ordinal);
-        foreach (Match match in BoundedRegex.EnumerateMatches(parameterText, CSharpIdentifierPattern))
-        {
-            var name = NormalizeAtPrefixedIdentifier(match.Value);
-            if (!IsIgnoredCallName("csharp", name))
-                names.Add(name);
-        }
-
-        return names;
-    }
-
-    private static bool ContainsCSharpIdentifier(string text, string name, out int index)
-    {
-        index = -1;
-        var normalizedName = NormalizeAtPrefixedIdentifier(name);
-        foreach (Match match in BoundedRegex.EnumerateMatches(text, CSharpIdentifierPattern))
-        {
-            if (string.Equals(NormalizeAtPrefixedIdentifier(match.Value), normalizedName, StringComparison.Ordinal))
-            {
-                index = match.Index;
-                return true;
-            }
-        }
-
-        return false;
-    }
-
-    private static void TrackCSharpLocalDeclarations(
-        string preparedLine,
-        SymbolRecord? container,
-        Dictionary<string, HashSet<string>>? localNamesByFunction)
-    {
-        if (container?.Kind != "function" || localNamesByFunction == null)
-            return;
-        if (preparedLine.Contains("=>", StringComparison.Ordinal))
-            return;
-
-        foreach (Match match in BoundedRegex.EnumerateMatches(CSharpLocalDeclarationRegex, preparedLine))
-        {
-            var name = NormalizeAtPrefixedIdentifier(match.Groups["name"].Value);
-            if (IsIgnoredCallName("csharp", name))
-                continue;
-
-            var scopeKey = GetCSharpContainerLocalScopeKey(container);
-            if (!localNamesByFunction.TryGetValue(scopeKey, out var localNames))
-            {
-                localNames = new HashSet<string>(StringComparer.Ordinal);
-                localNamesByFunction[scopeKey] = localNames;
-            }
-
-            localNames.Add(name);
-        }
-    }
-
-    private static string GetCSharpContainerLocalScopeKey(SymbolRecord container)
-        => $"{container.Kind}:{container.ContainerQualifiedName}:{container.ContainerKind}:{container.ContainerName}:{container.Name}:{container.StartLine}:{container.EndLine}:{container.BodyStartLine}:{container.BodyEndLine}:{container.StartColumn}";
-
     internal static void MarkMutualRecursionReferences(List<ReferenceRecord> references)
     {
         var edges = new HashSet<(string Caller, string Callee)>();

From dfe8599826d282d3513578f16f15ee808a64d5b8 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 12:07:02 +0900
Subject: [PATCH 16/45] Decompose impact definition resolution

---
 .../Database/DbReader.GraphQueries.cs         | 463 ------------------
 .../DbReader.ImpactDefinitionFamilies.cs      | 178 +++++++
 .../DbReader.ImpactDefinitionProjection.cs    | 161 ++++++
 .../DbReader.ImpactDefinitionQuery.cs         | 239 +++++++++
 .../DbReader.ImpactDefinitionQuerySql.cs      | 173 +++++++
 .../Database/DbReader.ImpactDefinitions.cs    | 106 ++++
 .../DbReader.LogicalPartialQuerySql.cs        |  79 +++
 .../DbReader.SymbolSearchListQueryBuilder.cs  |  50 +-
 .../Database/DbReader.SymbolSearchSql.cs      |  25 -
 .../DbReader.SymbolSearchTotalCount.cs        |   3 +-
 tests/CodeIndex.Tests/DbReaderImpactTests.cs  |  41 ++
 11 files changed, 989 insertions(+), 529 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactDefinitionFamilies.cs
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactDefinitionProjection.cs
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactDefinitionQuery.cs
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactDefinitionQuerySql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.ImpactDefinitions.cs
 create mode 100644 src/CodeIndex/Database/DbReader.LogicalPartialQuerySql.cs

diff --git a/src/CodeIndex/Database/DbReader.GraphQueries.cs b/src/CodeIndex/Database/DbReader.GraphQueries.cs
index 126989cfb..e06fcbe30 100644
--- a/src/CodeIndex/Database/DbReader.GraphQueries.cs
+++ b/src/CodeIndex/Database/DbReader.GraphQueries.cs
@@ -1,5 +1,4 @@
 using CodeIndex.Indexer;
-using Microsoft.Data.Sqlite;
 using System.Text;
 using System.Text.RegularExpressions;
 
@@ -888,468 +887,6 @@ public ImpactAnalysisResult AnalyzeImpact(string symbolName, int maxDepth = 5, i
         };
     }
 
-    private sealed record ImpactDefinitionResolution(
-        List<SymbolResult> Definitions,
-        int PhysicalCount,
-        int PhysicalFileCount,
-        int LogicalCount,
-        int PreciseDefinitionCount,
-        int PreciseLogicalDefinitionCount,
-        int PreciseDefinitionFileCount,
-        int NonCallableDefinitionCount,
-        SymbolResult? SinglePreciseDefinition,
-        HashSet<long> PhysicalSymbolIds,
-        HashSet<string> PhysicalDefinitionPaths,
-        bool PhysicalSymbolIdsTruncated);
-
-    private ImpactDefinitionResolution ResolveImpactDefinitions(
-        string resolvedName,
-        int representativeLimit,
-        string? lang,
-        IReadOnlyList<string>? pathPatterns,
-        IReadOnlyList<string>? excludePathPatterns,
-        bool excludeTests,
-        int representativeOffset = 0)
-    {
-        var normalizedName = SqlNameResolver.NormalizeQualifiedName(resolvedName);
-        var leafName = SqlNameResolver.GetLeafName(resolvedName);
-        var segmentCount = SqlNameResolver.GetSegmentCount(resolvedName);
-        var allowLeafFallback = !SqlNameResolver.HasQualifier(resolvedName);
-        EnsureCSharpCallableTypeKinds(lang, [leafName], exact: true);
-        using var cmd = _conn.CreateCommand();
-        var supportedLangFilter = BuildGraphSupportedLanguagePredicate(cmd, "f", "impactDefLang");
-        var signatureSql = GetSymbolColumnSql("signature");
-        var returnTypeSql = GetSymbolColumnSql("return_type");
-        var bodyStartLineSql = GetSymbolColumnSql("body_start_line");
-        var bodyEndLineSql = GetSymbolColumnSql("body_end_line");
-        var startColumnSql = GetSymbolColumnSql("start_column");
-        var identifierStartColumnSql = GetSymbolColumnSql("identifier_start_column");
-        var logicalPartialKeySql = LogicalPartialSymbolGrouper.BuildSqlKeyExpression(
-            "f.lang",
-            "s.kind",
-            "s.name",
-            "s.id",
-            "f.path",
-            signatureSql,
-            GetSymbolColumnSql("container_name"),
-            GetSymbolColumnSql("container_qualified_name"),
-            GetSymbolColumnSql("family_key"),
-            returnTypeSql,
-            GetSymbolColumnSql("is_partial_declaration"),
-            _hotspotFamilyReadyLanguages.Contains("csharp"));
-        var generatedSql = _fileColumns.Contains("generated")
-            ? "CASE WHEN COALESCE(f.generated, 0) <> 0 OR codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END"
-            : "CASE WHEN codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END";
-        var canonicalPrimaryRankSql = LogicalPartialSymbolGrouper.BuildSqlPrimaryRankExpression(
-            "s.kind",
-            bodyStartLineSql,
-            bodyEndLineSql);
-        var canonicalSemanticScoreSql = LogicalPartialSymbolGrouper.BuildSqlSemanticScoreExpression(
-            signatureSql,
-            "s.kind",
-            GetSymbolColumnSql("declaration_semantic_score"));
-        var fallbackCanonicalDeclarationIdentitySql = BuildCanonicalDeclarationIdentitySql(signatureSql);
-        var canonicalDeclarationIdentitySql = $"CASE WHEN s.kind IN ('function', 'test.method') THEN COALESCE(csharp_partial_callable_identity({signatureSql}, s.name, {returnTypeSql}), {fallbackCanonicalDeclarationIdentitySql}) ELSE {fallbackCanonicalDeclarationIdentitySql} END";
-        var nameCondition = _foldReady
-            ? allowLeafFallback
-                ? $"({BuildPersistedFoldedNameMatchSql("s.name_folded", "@resolvedNameFolded")} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name_folded(s.name) = @resolvedNameNormalizedFolded) OR sql_leaf_name_folded(s.name) = @resolvedNameLeafFolded)))"
-                : $"({BuildPersistedFoldedNameMatchSql("s.name_folded", "@resolvedNameFolded")} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name_folded(s.name) = @resolvedNameNormalizedFolded))"
-            : allowLeafFallback
-                ? "(s.name = @resolvedName COLLATE NOCASE OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name(s.name) = @resolvedNameNormalized COLLATE NOCASE) OR sql_leaf_name(s.name) = @resolvedNameLeaf COLLATE NOCASE)))"
-                : "(s.name = @resolvedName COLLATE NOCASE OR (f.lang = 'sql' AND sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name(s.name) = @resolvedNameNormalized COLLATE NOCASE))";
-        var csharpExplicitInterfaceClause = allowLeafFallback
-            ? BuildCSharpExplicitInterfaceShortAliasMatchSql("resolvedName")
-            : BuildCSharpExplicitInterfaceIdentityMatchSql("resolvedName");
-        nameCondition = $"({nameCondition} OR {csharpExplicitInterfaceClause})";
-        if (SqlNameResolver.HasQualifier(resolvedName))
-        {
-            var containerNameSql = GetSymbolColumnSql("container_name", "''");
-            var containerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name", containerNameSql);
-            var csharpLeafCondition = _foldReady
-                ? "s.name_folded = @resolvedNameLeafFolded"
-                : "s.name = @resolvedNameLeaf COLLATE NOCASE";
-            nameCondition = $"({nameCondition} OR (f.lang = 'csharp' AND {csharpLeafCondition} AND ({containerNameSql} = @resolvedNameContainer COLLATE NOCASE OR {containerQualifiedNameSql} = @resolvedNameContainer COLLATE NOCASE OR {containerQualifiedNameSql} COLLATE NOCASE LIKE @resolvedNameContainerSuffix ESCAPE '\\')))";
-        }
-        var matchOrderSql = @"CASE
-                     WHEN s.name = @resolvedName THEN 0
-                     WHEN f.lang = 'sql' AND sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name(s.name) = @resolvedNameNormalized THEN 1
-                     WHEN f.lang = 'sql' AND sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name_folded(s.name) = @resolvedNameNormalizedFolded THEN 2
-                     WHEN @allowLeafFallback = 1 AND f.lang = 'sql' AND sql_leaf_name(s.name) = @resolvedNameLeaf THEN 3
-                     WHEN @allowLeafFallback = 1 AND f.lang = 'sql' AND sql_leaf_name_folded(s.name) = @resolvedNameLeafFolded THEN 4
-                     ELSE 5
-                   END";
-        var matchingSql = $@"
-            SELECT f.path, f.lang, s.kind, s.name, s.line,
-                   {GetSymbolColumnSql("start_line", "s.line")} AS start_line,
-                   {startColumnSql} AS start_column,
-                   {GetSymbolColumnSql("end_line", "s.line")} AS end_line,
-                   {bodyStartLineSql} AS body_start_line,
-                   {bodyEndLineSql} AS body_end_line,
-                   {signatureSql} AS signature,
-                   {GetSymbolColumnSql("container_kind")} AS container_kind,
-                   {GetSymbolColumnSql("container_name")} AS container_name,
-                   {GetSymbolColumnSql("visibility")} AS visibility,
-                   {returnTypeSql} AS return_type,
-                   {GetSymbolColumnSql("container_qualified_name")} AS container_qualified_name,
-                   {logicalPartialKeySql} AS logical_partial_key,
-                   s.id AS symbol_id,
-                   {matchOrderSql} AS match_order,
-                   {PathBucketOrder} AS path_bucket,
-                   {VisibilityOrder} AS visibility_rank,
-                   CASE WHEN s.kind IN ('class', 'struct', 'interface') THEN 1 ELSE 0 END AS is_precise,
-                   CASE WHEN s.kind IN ('namespace', 'import') THEN 1 ELSE 0 END AS is_non_callable,
-                   {canonicalPrimaryRankSql} AS canonical_primary_rank,
-                   {generatedSql} AS canonical_generated_rank,
-                   {canonicalSemanticScoreSql} AS canonical_semantic_score,
-                   {canonicalDeclarationIdentitySql} AS canonical_declaration_identity,
-                   COALESCE({GetSymbolColumnSql("start_column")}, 2147483647) AS stable_start_column,
-                   {identifierStartColumnSql} AS identifier_start_column
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE {nameCondition}
-              AND {supportedLangFilter}";
-
-        if (lang != null)
-            matchingSql += " AND f.lang = @lang";
-        AppendPathFilters(ref matchingSql, pathPatterns, excludePathPatterns, excludeTests);
-        var pathDistinctSql = ReferenceEquals(GetIndexedPathComparer(), StringComparer.Ordinal)
-            ? "COUNT(DISTINCT path)"
-            : "COUNT(DISTINCT path COLLATE NOCASE)";
-        var precisePathDistinctSql = ReferenceEquals(GetIndexedPathComparer(), StringComparer.Ordinal)
-            ? "COUNT(DISTINCT CASE WHEN is_precise = 1 THEN path END)"
-            : "COUNT(DISTINCT CASE WHEN is_precise = 1 THEN path END COLLATE NOCASE)";
-        const string canonicalRepresentativeOrder = "canonical_primary_rank, canonical_generated_rank, canonical_semantic_score DESC, canonical_declaration_identity COLLATE BINARY, path COLLATE BINARY, start_line, stable_start_column, symbol_id";
-        const string resultOrder = "match_order, path_bucket, visibility_rank, name, path COLLATE BINARY, line, symbol_id";
-        var sql = $@"
-            WITH matching_definitions AS (
-                {matchingSql}
-            ),
-            ranked_definitions AS (
-                SELECT matching_definitions.*,
-                       ROW_NUMBER() OVER (
-                           PARTITION BY logical_partial_key
-                           ORDER BY {canonicalRepresentativeOrder}
-                       ) AS logical_row_number,
-                       ROW_NUMBER() OVER (
-                           PARTITION BY logical_partial_key
-                           ORDER BY path COLLATE BINARY, start_line, stable_start_column, symbol_id
-                       ) AS family_member_row_number,
-                       COUNT(*) OVER (PARTITION BY logical_partial_key) AS logical_definition_sites
-                FROM matching_definitions
-            ),
-            family_ranked_definitions AS (
-                SELECT ranked_definitions.*,
-                       MAX(CASE WHEN logical_row_number = 1 THEN family_member_row_number END) OVER (
-                           PARTITION BY logical_partial_key
-                       ) AS representative_member_row_number
-                FROM ranked_definitions
-            ),
-            family_metadata_definitions AS (
-                SELECT family_ranked_definitions.*,
-                       MIN(canonical_primary_rank) OVER (PARTITION BY logical_partial_key) AS logical_primary_rank_min,
-                       MAX(canonical_primary_rank) OVER (PARTITION BY logical_partial_key) AS logical_primary_rank_max,
-                       MIN(canonical_generated_rank) OVER (PARTITION BY logical_partial_key) AS logical_generated_rank_min,
-                       MAX(canonical_generated_rank) OVER (PARTITION BY logical_partial_key) AS logical_generated_rank_max,
-                       MIN(canonical_semantic_score) OVER (PARTITION BY logical_partial_key) AS logical_semantic_score_min,
-                       MAX(canonical_semantic_score) OVER (PARTITION BY logical_partial_key) AS logical_semantic_score_max,
-                       MIN(canonical_declaration_identity) OVER (PARTITION BY logical_partial_key) AS logical_declaration_identity_min,
-                       MAX(canonical_declaration_identity) OVER (PARTITION BY logical_partial_key) AS logical_declaration_identity_max,
-                       json_group_array(json_object(
-                           'symbol_id', symbol_id,
-                           'path', path,
-                           'line', line,
-                           'start_line', start_line,
-                           'start_column', start_column,
-                           'end_line', end_line,
-                           'name', name,
-                           'signature', signature,
-                           'identifier_start_column', identifier_start_column,
-                           'generated', canonical_generated_rank
-                       )) FILTER (WHERE
-                           family_member_row_number <= CASE
-                               WHEN representative_member_row_number <= {LogicalPartialSymbolGrouper.FamilyMemberLimit}
-                               THEN {LogicalPartialSymbolGrouper.FamilyMemberLimit}
-                               ELSE {LogicalPartialSymbolGrouper.FamilyMemberLimit - 1}
-                           END
-                           OR logical_row_number = 1
-                       ) OVER (
-                           PARTITION BY logical_partial_key
-                           ORDER BY path COLLATE BINARY, start_line, stable_start_column, symbol_id
-                           ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
-                       ) AS logical_family_members_json
-                FROM family_ranked_definitions
-            ),
-            logical_definitions AS (
-                SELECT *
-                FROM family_metadata_definitions
-                WHERE logical_row_number = 1
-            ),
-            requested_definitions AS (
-                SELECT logical_partial_key, 1 AS requested_row
-                FROM logical_definitions
-                ORDER BY {resultOrder}
-                LIMIT @definitionLimit OFFSET @definitionOffset
-            ),
-            single_precise_definition AS (
-                SELECT logical_partial_key, 0 AS requested_row
-                FROM logical_definitions
-                WHERE is_precise = 1
-                ORDER BY {resultOrder}
-                LIMIT 1
-            ),
-            selected_definition_keys AS (
-                SELECT logical_partial_key, requested_row
-                FROM requested_definitions
-                UNION ALL
-                SELECT precise.logical_partial_key, precise.requested_row
-                FROM single_precise_definition precise
-                WHERE NOT EXISTS (
-                    SELECT 1
-                    FROM requested_definitions requested
-                    WHERE requested.logical_partial_key = precise.logical_partial_key
-                )
-            ),
-            definition_stats AS (
-                SELECT COUNT(*) AS physical_count,
-                       {pathDistinctSql} AS physical_file_count,
-                       COUNT(DISTINCT logical_partial_key) AS logical_count,
-                       SUM(is_precise) AS precise_count,
-                       COUNT(DISTINCT CASE WHEN is_precise = 1 THEN logical_partial_key END) AS precise_logical_count,
-                       {precisePathDistinctSql} AS precise_file_count,
-                       SUM(is_non_callable) AS non_callable_count
-                FROM matching_definitions
-            )
-            SELECT logical.path, logical.lang, logical.kind, logical.name, logical.line,
-                   logical.start_line, logical.start_column, logical.end_line,
-                   logical.body_start_line, logical.body_end_line, logical.signature,
-                   logical.container_kind, logical.container_name,
-                   logical.visibility, logical.return_type,
-                   logical.container_qualified_name, logical.logical_partial_key,
-                   logical.symbol_id, logical.logical_definition_sites, selected.requested_row,
-                   stats.physical_count, stats.physical_file_count, stats.logical_count,
-                   stats.precise_count, stats.precise_file_count, stats.non_callable_count,
-                   CASE
-                       WHEN logical.logical_primary_rank_min <> logical.logical_primary_rank_max THEN '{LogicalPartialSymbolGrouper.ImplementationBodyReason}'
-                       WHEN logical.logical_generated_rank_min <> logical.logical_generated_rank_max THEN '{LogicalPartialSymbolGrouper.NonGeneratedSourceReason}'
-                       WHEN logical.logical_semantic_score_min <> logical.logical_semantic_score_max THEN '{LogicalPartialSymbolGrouper.SemanticDeclarationReason}'
-                       WHEN logical.logical_declaration_identity_min <> logical.logical_declaration_identity_max THEN '{LogicalPartialSymbolGrouper.CanonicalDeclarationIdentityReason}'
-                       ELSE '{LogicalPartialSymbolGrouper.StableLocationReason}'
-                   END AS representative_reason,
-                   logical.logical_family_members_json,
-                   CASE WHEN logical.logical_definition_sites > {LogicalPartialSymbolGrouper.FamilyMemberLimit} THEN 1 ELSE 0 END AS family_members_truncated,
-                   logical.identifier_start_column,
-                   stats.precise_logical_count
-            FROM selected_definition_keys selected
-            JOIN logical_definitions logical
-              ON logical.logical_partial_key = selected.logical_partial_key
-            CROSS JOIN definition_stats stats
-            ORDER BY {resultOrder}";
-
-        cmd.CommandText = sql;
-        SqliteCommandPolicy.Add(cmd, "@resolvedName", resolvedName);
-        SqliteCommandPolicy.Add(cmd, "@resolvedNameNormalized", normalizedName);
-        SqliteCommandPolicy.Add(cmd, "@resolvedNameNormalizedFolded", FoldNameForLanguage(normalizedName, lang));
-        SqliteCommandPolicy.Add(cmd, "@resolvedNameLeaf", leafName);
-        SqliteCommandPolicy.Add(cmd, "@resolvedNameLeafFolded", FoldNameForLanguage(leafName, lang));
-        SqliteCommandPolicy.Add(cmd, "@resolvedNameSegmentCount", segmentCount);
-        SqliteCommandPolicy.Add(cmd, "@allowLeafFallback", allowLeafFallback ? 1 : 0);
-        AddCSharpExplicitInterfaceIdentityQueryParameter(cmd, "resolvedName", resolvedName);
-        if (SqlNameResolver.HasQualifier(resolvedName))
-        {
-            var container = GetQualifiedQueryContainer(resolvedName);
-            SqliteCommandPolicy.Add(cmd, "@resolvedNameContainer", container);
-            SqliteCommandPolicy.Add(cmd, "@resolvedNameContainerSuffix", $"%.{EscapeLikeQuery(container)}");
-        }
-        if (_foldReady)
-            AddPersistedFoldedNameQueryParameters(cmd, "@resolvedNameFolded", resolvedName, lang);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        SqliteCommandPolicy.Add(cmd, "@definitionLimit", Math.Max(1, representativeLimit));
-        SqliteCommandPolicy.Add(cmd, "@definitionOffset", Math.Max(0, representativeOffset));
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        var results = new List<SymbolResult>();
-        SymbolResult? preciseDefinition = null;
-        var physicalCount = 0;
-        var physicalFileCount = 0;
-        var logicalCount = 0;
-        var preciseCount = 0;
-        var preciseLogicalCount = 0;
-        var preciseFileCount = 0;
-        var nonCallableCount = 0;
-        using var reader = cmd.ExecuteTrackedReader();
-        while (reader.TrackedRead())
-        {
-            var definitionSites = reader.GetInt32(18);
-            var result = new SymbolResult
-            {
-                Path = reader.GetString(0),
-                Lang = reader.GetString(1),
-                Kind = reader.GetString(2),
-                Name = reader.GetString(3),
-                Line = reader.GetInt32(4),
-                StartLine = !reader.IsDBNull(5) ? reader.GetInt32(5) : reader.GetInt32(4),
-                StartColumn = !reader.IsDBNull(29)
-                    ? reader.GetInt32(29)
-                    : ResolveSymbolIdentifierStartColumn(
-                        !reader.IsDBNull(6) ? reader.GetInt32(6) : null,
-                        !reader.IsDBNull(10) ? reader.GetString(10) : null,
-                        reader.GetString(3),
-                        reader.GetString(2)),
-                EndLine = !reader.IsDBNull(7) ? reader.GetInt32(7) : reader.GetInt32(4),
-                BodyStartLine = !reader.IsDBNull(8) ? reader.GetInt32(8) : null,
-                BodyEndLine = !reader.IsDBNull(9) ? reader.GetInt32(9) : null,
-                Signature = !reader.IsDBNull(10) ? reader.GetString(10) : null,
-                ContainerKind = !reader.IsDBNull(11) ? reader.GetString(11) : null,
-                ContainerName = !reader.IsDBNull(12) ? reader.GetString(12) : null,
-                ContainerQualifiedName = !reader.IsDBNull(15) ? reader.GetString(15) : null,
-                LogicalPartialKey = !reader.IsDBNull(16) ? reader.GetString(16) : null,
-                Visibility = !reader.IsDBNull(13) ? reader.GetString(13) : null,
-                ReturnType = !reader.IsDBNull(14) ? reader.GetString(14) : null,
-                SymbolId = reader.GetInt64(17),
-                DefinitionSites = definitionSites > 1 ? definitionSites : null,
-            };
-            if (definitionSites > 1)
-            {
-                result.PartialFamilyId = LogicalPartialSymbolGrouper.BuildPartialFamilyId(result.LogicalPartialKey!);
-                result.RepresentativeReason = reader.GetString(26);
-                result.FamilyMembers = ReadPartialFamilyMembers(reader.GetString(27), result);
-                result.FamilyMembersTruncated = reader.GetInt64(28) != 0;
-            }
-            physicalCount = reader.GetInt32(20);
-            physicalFileCount = reader.GetInt32(21);
-            logicalCount = reader.GetInt32(22);
-            preciseCount = reader.GetInt32(23);
-            preciseFileCount = reader.GetInt32(24);
-            nonCallableCount = reader.GetInt32(25);
-            preciseLogicalCount = reader.GetInt32(30);
-            if (IsPreciseImpactFallbackKind(result.Kind))
-                preciseDefinition ??= result;
-            if (reader.GetInt32(19) == 1)
-                results.Add(result);
-        }
-
-        // Identity-scoped C# graph traversal keeps the representative-only
-        // definition payload, but retain every selected physical family ID internally so a
-        // call resolved to a partial declaration reaches the same graph as its implementation.
-        // identity-scoped C# のグラフ探索では definition の出力は代表1件のまま
-        // としつつ、partial 宣言側へ解決された call も実装側と同じグラフへ到達できるよう、
-        // 選択された family の全 physical ID を内部的に保持する。
-        reader.Dispose();
-        var physicalSymbolIds = new HashSet<long>();
-        var physicalDefinitionPaths = new HashSet<string>(GetIndexedPathComparer());
-        var physicalSymbolIdsTruncated = false;
-        foreach (var definition in results)
-        {
-            AddPhysicalDefinition(definition.SymbolId!.Value, definition.Path);
-            if (physicalSymbolIdsTruncated || definition.DefinitionSites is not > 1)
-                continue;
-
-            if (!definition.FamilyMembersTruncated)
-            {
-                foreach (var member in definition.FamilyMembers ?? [])
-                {
-                    if (member.SymbolId is long memberSymbolId)
-                        AddPhysicalDefinition(memberSymbolId, member.Path);
-                    if (physicalSymbolIdsTruncated)
-                        break;
-                }
-                continue;
-            }
-
-            var (familyMembers, familyIdsTruncated) = ResolveImpactPhysicalFamilyMembers(
-                definition,
-                logicalPartialKeySql,
-                lang,
-                pathPatterns,
-                excludePathPatterns,
-                excludeTests);
-            foreach (var familyMember in familyMembers)
-            {
-                AddPhysicalDefinition(familyMember.SymbolId, familyMember.Path);
-                if (physicalSymbolIdsTruncated)
-                    break;
-            }
-            physicalSymbolIdsTruncated |= familyIdsTruncated;
-        }
-
-        return new ImpactDefinitionResolution(
-            results,
-            physicalCount,
-            physicalFileCount,
-            logicalCount,
-            preciseCount,
-            preciseLogicalCount,
-            preciseFileCount,
-            nonCallableCount,
-            preciseLogicalCount == 1 ? preciseDefinition : null,
-            physicalSymbolIds,
-            physicalDefinitionPaths,
-            physicalSymbolIdsTruncated);
-
-        void AddPhysicalDefinition(long symbolId, string path)
-        {
-            if (physicalSymbolIds.Contains(symbolId))
-                return;
-            if (physicalSymbolIds.Count >= Math.Max(1, ImpactPartialFamilyMemberBudget))
-            {
-                physicalSymbolIdsTruncated = true;
-                return;
-            }
-            physicalSymbolIds.Add(symbolId);
-            physicalDefinitionPaths.Add(path);
-        }
-    }
-
-    private (List<(long SymbolId, string Path)> Members, bool Truncated) ResolveImpactPhysicalFamilyMembers(
-        SymbolResult definition,
-        string logicalPartialKeySql,
-        string? lang,
-        IReadOnlyList<string>? pathPatterns,
-        IReadOnlyList<string>? excludePathPatterns,
-        bool excludeTests)
-    {
-        using var cmd = _conn.CreateCommand();
-        var supportedLangFilter = BuildGraphSupportedLanguagePredicate(cmd, "f", "impactFamilyLang");
-        var familyKindPredicate = definition.Kind is "function" or "test.method"
-            ? "s.kind IN ('function', 'test.method')"
-            : "s.kind = @familyKind";
-        var sql = $@"
-            SELECT s.id, f.path
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE f.lang = @familyLang
-              AND {familyKindPredicate}
-              AND s.name = @familyName COLLATE BINARY
-              AND ({logicalPartialKeySql}) = @logicalPartialKey
-              AND {supportedLangFilter}";
-        if (lang != null)
-            sql += " AND f.lang = @lang";
-        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
-        sql += " ORDER BY s.id LIMIT @familyMemberLimit";
-
-        cmd.CommandText = sql;
-        SqliteCommandPolicy.Add(cmd, "@familyLang", definition.Lang!);
-        if (definition.Kind is not ("function" or "test.method"))
-            SqliteCommandPolicy.Add(cmd, "@familyKind", definition.Kind);
-        SqliteCommandPolicy.Add(cmd, "@familyName", definition.Name);
-        SqliteCommandPolicy.Add(cmd, "@logicalPartialKey", definition.LogicalPartialKey!);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        var familyMemberBudget = Math.Max(1, ImpactPartialFamilyMemberBudget);
-        SqliteCommandPolicy.Add(cmd, "@familyMemberLimit", familyMemberBudget + 1);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-
-        var members = new List<(long SymbolId, string Path)>();
-        using var reader = cmd.ExecuteTrackedReader();
-        while (reader.TrackedRead())
-        {
-            if (members.Count >= familyMemberBudget)
-                return (members, true);
-            members.Add((reader.GetInt64(0), reader.GetString(1)));
-        }
-        return (members, false);
-    }
-
     // C# convention: a class `FooAttribute` is used in source as `[Foo]`, so the reference
     // site is stored with `symbol_name = "Foo"`. When a user queries with the class name
     // (`references FooAttribute`, `inspect FooAttribute`, `analyze_symbol("FooAttribute")`),
diff --git a/src/CodeIndex/Database/DbReader.ImpactDefinitionFamilies.cs b/src/CodeIndex/Database/DbReader.ImpactDefinitionFamilies.cs
new file mode 100644
index 000000000..aa4a9f7c8
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactDefinitionFamilies.cs
@@ -0,0 +1,178 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private readonly record struct ImpactPhysicalFamilyMember(long SymbolId, string Path);
+
+    private sealed record ImpactDefinitionFamilyResolution(
+        HashSet<long> PhysicalSymbolIds,
+        HashSet<string> PhysicalDefinitionPaths,
+        bool Truncated);
+
+    private static class ImpactDefinitionFamilyResolver
+    {
+        private sealed class Accumulator(
+            int budget,
+            IEqualityComparer<string> pathComparer)
+        {
+            public HashSet<long> SymbolIds { get; } = [];
+            public HashSet<string> DefinitionPaths { get; } = new(pathComparer);
+            public bool Truncated { get; private set; }
+
+            public void Add(long symbolId, string path)
+            {
+                if (SymbolIds.Contains(symbolId))
+                    return;
+                if (SymbolIds.Count >= budget)
+                {
+                    Truncated = true;
+                    return;
+                }
+
+                SymbolIds.Add(symbolId);
+                DefinitionPaths.Add(path);
+            }
+
+            public void MarkTruncated() => Truncated = true;
+        }
+
+        public static ImpactDefinitionFamilyResolution Resolve(
+            DbReader reader,
+            ImpactDefinitionQueryPlan plan,
+            IReadOnlyList<SymbolResult> definitions)
+        {
+            var accumulator = new Accumulator(
+                Math.Max(1, reader.ImpactPartialFamilyMemberBudget),
+                reader.GetIndexedPathComparer());
+            foreach (var definition in definitions)
+            {
+                accumulator.Add(definition.SymbolId!.Value, definition.Path);
+                if (accumulator.Truncated || definition.DefinitionSites is not > 1)
+                    continue;
+
+                if (!definition.FamilyMembersTruncated)
+                {
+                    AddProjectedMembers(accumulator, definition);
+                    continue;
+                }
+
+                var (members, familyTruncated) = ResolvePhysicalMembers(
+                    reader,
+                    definition,
+                    plan);
+                foreach (var member in members)
+                {
+                    accumulator.Add(member.SymbolId, member.Path);
+                    if (accumulator.Truncated)
+                        break;
+                }
+                if (familyTruncated)
+                    accumulator.MarkTruncated();
+            }
+
+            return new ImpactDefinitionFamilyResolution(
+                accumulator.SymbolIds,
+                accumulator.DefinitionPaths,
+                accumulator.Truncated);
+        }
+
+        private static void AddProjectedMembers(
+            Accumulator accumulator,
+            SymbolResult definition)
+        {
+            foreach (var member in definition.FamilyMembers ?? [])
+            {
+                if (member.SymbolId is long memberSymbolId)
+                    accumulator.Add(memberSymbolId, member.Path);
+                if (accumulator.Truncated)
+                    break;
+            }
+        }
+
+        private static (List<ImpactPhysicalFamilyMember> Members, bool Truncated)
+        ResolvePhysicalMembers(
+            DbReader dbReader,
+            SymbolResult definition,
+            ImpactDefinitionQueryPlan plan)
+        {
+            using var cmd = dbReader._conn.CreateCommand();
+            var supportedLangFilter = dbReader.BuildGraphSupportedLanguagePredicate(
+                cmd,
+                "f",
+                "impactFamilyLang");
+            var familyKindPredicate = definition.Kind is "function" or "test.method"
+                ? "s.kind IN ('function', 'test.method')"
+                : "s.kind = @familyKind";
+            var sql = BuildSql(
+                dbReader,
+                plan.LogicalPartialKeySql,
+                familyKindPredicate,
+                supportedLangFilter,
+                plan.Request);
+            cmd.CommandText = sql;
+            Bind(dbReader, cmd, definition, plan.Request);
+
+            var familyMemberBudget = Math.Max(1, dbReader.ImpactPartialFamilyMemberBudget);
+            var members = new List<ImpactPhysicalFamilyMember>();
+            using var reader = cmd.ExecuteTrackedReader();
+            while (reader.TrackedRead())
+            {
+                if (members.Count >= familyMemberBudget)
+                    return (members, true);
+                members.Add(new ImpactPhysicalFamilyMember(
+                    reader.GetInt64(0),
+                    reader.GetString(1)));
+            }
+            return (members, false);
+        }
+
+        private static void Bind(
+            DbReader reader,
+            Microsoft.Data.Sqlite.SqliteCommand cmd,
+            SymbolResult definition,
+            ImpactDefinitionRequest request)
+        {
+            SqliteCommandPolicy.Add(cmd, "@familyLang", definition.Lang!);
+            if (definition.Kind is not ("function" or "test.method"))
+                SqliteCommandPolicy.Add(cmd, "@familyKind", definition.Kind);
+            SqliteCommandPolicy.Add(cmd, "@familyName", definition.Name);
+            SqliteCommandPolicy.Add(cmd, "@logicalPartialKey", definition.LogicalPartialKey!);
+            if (request.Lang != null)
+                SqliteCommandPolicy.Add(cmd, "@lang", request.Lang);
+            SqliteCommandPolicy.Add(
+                cmd,
+                "@familyMemberLimit",
+                Math.Max(1, reader.ImpactPartialFamilyMemberBudget) + 1);
+            DbReader.AddPathFilterParameters(
+                cmd,
+                request.PathPatterns,
+                request.ExcludePathPatterns);
+        }
+
+        private static string BuildSql(
+            DbReader reader,
+            string logicalPartialKeySql,
+            string familyKindPredicate,
+            string supportedLangFilter,
+            ImpactDefinitionRequest request)
+        {
+            var sql = $@"
+            SELECT s.id, f.path
+            FROM symbols s
+            JOIN files f ON s.file_id = f.id
+            WHERE f.lang = @familyLang
+              AND {familyKindPredicate}
+              AND s.name = @familyName COLLATE BINARY
+              AND ({logicalPartialKeySql}) = @logicalPartialKey
+              AND {supportedLangFilter}";
+            if (request.Lang != null)
+                sql += " AND f.lang = @lang";
+            DbReader.AppendPathFilters(
+                ref sql,
+                request.PathPatterns,
+                request.ExcludePathPatterns,
+                request.ExcludeTests);
+            return sql + " ORDER BY s.id LIMIT @familyMemberLimit";
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.ImpactDefinitionProjection.cs b/src/CodeIndex/Database/DbReader.ImpactDefinitionProjection.cs
new file mode 100644
index 000000000..a24279df4
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactDefinitionProjection.cs
@@ -0,0 +1,161 @@
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private readonly record struct ImpactDefinitionStats(
+        int PhysicalCount,
+        int PhysicalFileCount,
+        int LogicalCount,
+        int PreciseDefinitionCount,
+        int PreciseLogicalDefinitionCount,
+        int PreciseDefinitionFileCount,
+        int NonCallableDefinitionCount);
+
+    private sealed record ImpactDefinitionProjection(
+        List<SymbolResult> Definitions,
+        ImpactDefinitionStats Stats,
+        SymbolResult? SinglePreciseDefinition);
+
+    private static class ImpactDefinitionRowProjector
+    {
+        private static class Column
+        {
+            public const int Path = 0;
+            public const int Lang = 1;
+            public const int Kind = 2;
+            public const int Name = 3;
+            public const int Line = 4;
+            public const int StartLine = 5;
+            public const int StartColumn = 6;
+            public const int EndLine = 7;
+            public const int BodyStartLine = 8;
+            public const int BodyEndLine = 9;
+            public const int Signature = 10;
+            public const int ContainerKind = 11;
+            public const int ContainerName = 12;
+            public const int Visibility = 13;
+            public const int ReturnType = 14;
+            public const int ContainerQualifiedName = 15;
+            public const int LogicalPartialKey = 16;
+            public const int SymbolId = 17;
+            public const int DefinitionSites = 18;
+            public const int RequestedRow = 19;
+            public const int PhysicalCount = 20;
+            public const int PhysicalFileCount = 21;
+            public const int LogicalCount = 22;
+            public const int PreciseCount = 23;
+            public const int PreciseFileCount = 24;
+            public const int NonCallableCount = 25;
+            public const int RepresentativeReason = 26;
+            public const int FamilyMembersJson = 27;
+            public const int FamilyMembersTruncated = 28;
+            public const int IdentifierStartColumn = 29;
+            public const int PreciseLogicalCount = 30;
+        }
+
+        public static ImpactDefinitionProjection Read(SqliteCommand cmd)
+        {
+            var definitions = new List<SymbolResult>();
+            var stats = EmptyStats;
+            SymbolResult? preciseDefinition = null;
+            using var reader = cmd.ExecuteTrackedReader();
+            while (reader.TrackedRead())
+            {
+                var row = ReadRow(reader);
+                stats = ReadStats(reader);
+                if (IsPreciseImpactFallbackKind(row.Result.Kind))
+                    preciseDefinition ??= row.Result;
+                if (row.Requested)
+                    definitions.Add(row.Result);
+            }
+
+            return new ImpactDefinitionProjection(
+                definitions,
+                stats,
+                preciseDefinition);
+        }
+
+        private static readonly ImpactDefinitionStats EmptyStats =
+            new(0, 0, 0, 0, 0, 0, 0);
+
+        private static (SymbolResult Result, bool Requested) ReadRow(
+            SqliteDataReader reader)
+        {
+            var definitionSites = reader.GetInt32(Column.DefinitionSites);
+            var result = new SymbolResult
+            {
+                Path = reader.GetString(Column.Path),
+                Lang = reader.GetString(Column.Lang),
+                Kind = reader.GetString(Column.Kind),
+                Name = reader.GetString(Column.Name),
+                Line = reader.GetInt32(Column.Line),
+                StartLine = ReadStartLine(reader),
+                StartColumn = ReadStartColumn(reader),
+                EndLine = ReadEndLine(reader),
+                BodyStartLine = GetNullableInt32(reader, Column.BodyStartLine),
+                BodyEndLine = GetNullableInt32(reader, Column.BodyEndLine),
+                Signature = GetNullableString(reader, Column.Signature),
+                ContainerKind = GetNullableString(reader, Column.ContainerKind),
+                ContainerName = GetNullableString(reader, Column.ContainerName),
+                ContainerQualifiedName = GetNullableString(
+                    reader,
+                    Column.ContainerQualifiedName),
+                LogicalPartialKey = GetNullableString(reader, Column.LogicalPartialKey),
+                Visibility = GetNullableString(reader, Column.Visibility),
+                ReturnType = GetNullableString(reader, Column.ReturnType),
+                SymbolId = reader.GetInt64(Column.SymbolId),
+                DefinitionSites = definitionSites > 1 ? definitionSites : null,
+            };
+            AddFamily(reader, definitionSites, result);
+            return (result, reader.GetInt32(Column.RequestedRow) == 1);
+        }
+
+        private static int ReadStartLine(SqliteDataReader reader)
+            => GetInt32OrFallback(reader, Column.StartLine, Column.Line);
+
+        private static int ReadEndLine(SqliteDataReader reader)
+            => GetInt32OrFallback(reader, Column.EndLine, Column.Line);
+
+        private static int? ReadStartColumn(SqliteDataReader reader)
+        {
+            return GetNullableInt32(reader, Column.IdentifierStartColumn)
+                ?? ResolveSymbolIdentifierStartColumn(
+                    GetNullableInt32(reader, Column.StartColumn),
+                    GetNullableString(reader, Column.Signature),
+                    reader.GetString(Column.Name),
+                    reader.GetString(Column.Kind));
+        }
+
+        private static void AddFamily(
+            SqliteDataReader reader,
+            int definitionSites,
+            SymbolResult result)
+        {
+            if (definitionSites <= 1)
+                return;
+
+            result.PartialFamilyId =
+                LogicalPartialSymbolGrouper.BuildPartialFamilyId(result.LogicalPartialKey!);
+            result.RepresentativeReason = reader.GetString(Column.RepresentativeReason);
+            result.FamilyMembers = ReadPartialFamilyMembers(
+                reader.GetString(Column.FamilyMembersJson),
+                result);
+            result.FamilyMembersTruncated =
+                reader.GetInt64(Column.FamilyMembersTruncated) != 0;
+        }
+
+        private static ImpactDefinitionStats ReadStats(SqliteDataReader reader)
+        {
+            return new ImpactDefinitionStats(
+                reader.GetInt32(Column.PhysicalCount),
+                reader.GetInt32(Column.PhysicalFileCount),
+                reader.GetInt32(Column.LogicalCount),
+                reader.GetInt32(Column.PreciseCount),
+                reader.GetInt32(Column.PreciseLogicalCount),
+                reader.GetInt32(Column.PreciseFileCount),
+                reader.GetInt32(Column.NonCallableCount));
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.ImpactDefinitionQuery.cs b/src/CodeIndex/Database/DbReader.ImpactDefinitionQuery.cs
new file mode 100644
index 000000000..d59e65063
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactDefinitionQuery.cs
@@ -0,0 +1,239 @@
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed record ImpactDefinitionColumnSql(
+        string StartLine,
+        string StartColumn,
+        string EndLine,
+        string BodyStartLine,
+        string BodyEndLine,
+        string Signature,
+        string ContainerKind,
+        string ContainerName,
+        string ContainerQualifiedName,
+        string FamilyKey,
+        string Visibility,
+        string ReturnType,
+        string IdentifierStartColumn);
+
+    private sealed record ImpactDefinitionQueryPlan(
+        ImpactDefinitionRequest Request,
+        string Sql,
+        string LogicalPartialKeySql);
+
+    private static class ImpactDefinitionQueryBuilder
+    {
+        public static ImpactDefinitionQueryPlan Build(
+            DbReader reader,
+            SqliteCommand cmd,
+            ImpactDefinitionRequest request)
+        {
+            var supportedLangFilter = reader.BuildGraphSupportedLanguagePredicate(
+                cmd,
+                "f",
+                "impactDefLang");
+            var columns = BuildColumnSql(reader);
+            var canonical = LogicalPartialQuerySql.Build(
+                reader,
+                columns.Signature,
+                columns.ContainerName,
+                columns.ContainerQualifiedName,
+                columns.FamilyKey,
+                columns.ReturnType,
+                columns.BodyStartLine,
+                columns.BodyEndLine);
+            var matchingSql = BuildMatchingSql(
+                reader,
+                request,
+                columns,
+                canonical,
+                supportedLangFilter);
+            var pathCaseSensitive = ReferenceEquals(
+                reader.GetIndexedPathComparer(),
+                StringComparer.Ordinal);
+            var sql = ImpactDefinitionQuerySql.Build(matchingSql, pathCaseSensitive);
+            return new ImpactDefinitionQueryPlan(
+                request,
+                sql,
+                canonical.LogicalPartialKey);
+        }
+
+        private static ImpactDefinitionColumnSql BuildColumnSql(DbReader reader)
+        {
+            return new ImpactDefinitionColumnSql(
+                reader.GetSymbolColumnSql("start_line", "s.line"),
+                reader.GetSymbolColumnSql("start_column"),
+                reader.GetSymbolColumnSql("end_line", "s.line"),
+                reader.GetSymbolColumnSql("body_start_line"),
+                reader.GetSymbolColumnSql("body_end_line"),
+                reader.GetSymbolColumnSql("signature"),
+                reader.GetSymbolColumnSql("container_kind"),
+                reader.GetSymbolColumnSql("container_name"),
+                reader.GetSymbolColumnSql("container_qualified_name"),
+                reader.GetSymbolColumnSql("family_key"),
+                reader.GetSymbolColumnSql("visibility"),
+                reader.GetSymbolColumnSql("return_type"),
+                reader.GetSymbolColumnSql("identifier_start_column"));
+        }
+
+        private static string BuildMatchingSql(
+            DbReader reader,
+            ImpactDefinitionRequest request,
+            ImpactDefinitionColumnSql columns,
+            LogicalPartialCanonicalSql canonical,
+            string supportedLangFilter)
+        {
+            var nameCondition = BuildNameCondition(reader, request);
+            var matchOrderSql = BuildMatchOrderSql();
+            var sql = $@"
+            SELECT f.path, f.lang, s.kind, s.name, s.line,
+                   {columns.StartLine} AS start_line,
+                   {columns.StartColumn} AS start_column,
+                   {columns.EndLine} AS end_line,
+                   {columns.BodyStartLine} AS body_start_line,
+                   {columns.BodyEndLine} AS body_end_line,
+                   {columns.Signature} AS signature,
+                   {columns.ContainerKind} AS container_kind,
+                   {columns.ContainerName} AS container_name,
+                   {columns.Visibility} AS visibility,
+                   {columns.ReturnType} AS return_type,
+                   {columns.ContainerQualifiedName} AS container_qualified_name,
+                   {canonical.LogicalPartialKey} AS logical_partial_key,
+                   s.id AS symbol_id,
+                   {matchOrderSql} AS match_order,
+                   {DbReader.PathBucketOrder} AS path_bucket,
+                   {reader.VisibilityOrder} AS visibility_rank,
+                   CASE WHEN s.kind IN ('class', 'struct', 'interface') THEN 1 ELSE 0 END AS is_precise,
+                   CASE WHEN s.kind IN ('namespace', 'import') THEN 1 ELSE 0 END AS is_non_callable,
+                   {canonical.PrimaryRank} AS canonical_primary_rank,
+                   {canonical.Generated} AS canonical_generated_rank,
+                   {canonical.SemanticScore} AS canonical_semantic_score,
+                   {canonical.DeclarationIdentity} AS canonical_declaration_identity,
+                   COALESCE({columns.StartColumn}, 2147483647) AS stable_start_column,
+                   {columns.IdentifierStartColumn} AS identifier_start_column
+            FROM symbols s
+            JOIN files f ON s.file_id = f.id
+            WHERE {nameCondition}
+              AND {supportedLangFilter}";
+
+            if (request.Lang != null)
+                sql += " AND f.lang = @lang";
+            DbReader.AppendPathFilters(
+                ref sql,
+                request.PathPatterns,
+                request.ExcludePathPatterns,
+                request.ExcludeTests);
+            return sql;
+        }
+
+        private static string BuildNameCondition(
+            DbReader reader,
+            ImpactDefinitionRequest request)
+        {
+            var nameCondition = reader._foldReady
+                ? BuildFoldedNameCondition(request.AllowLeafFallback)
+                : BuildLegacyNameCondition(request.AllowLeafFallback);
+            var explicitInterfaceClause = request.AllowLeafFallback
+                ? reader.BuildCSharpExplicitInterfaceShortAliasMatchSql("resolvedName")
+                : reader.BuildCSharpExplicitInterfaceIdentityMatchSql("resolvedName");
+            nameCondition = $"({nameCondition} OR {explicitInterfaceClause})";
+            if (request.AllowLeafFallback)
+                return nameCondition;
+
+            var csharpLeafCondition = reader._foldReady
+                ? "s.name_folded = @resolvedNameLeafFolded"
+                : "s.name = @resolvedNameLeaf COLLATE NOCASE";
+            var containerName = reader.GetSymbolColumnSql("container_name", "''");
+            var containerQualifiedName = reader.GetSymbolColumnSql(
+                "container_qualified_name",
+                containerName);
+            return $"({nameCondition} OR (f.lang = 'csharp' AND {csharpLeafCondition} AND ({containerName} = @resolvedNameContainer COLLATE NOCASE OR {containerQualifiedName} = @resolvedNameContainer COLLATE NOCASE OR {containerQualifiedName} COLLATE NOCASE LIKE @resolvedNameContainerSuffix ESCAPE '\\')))";
+        }
+
+        private static string BuildFoldedNameCondition(bool allowLeafFallback)
+        {
+            return allowLeafFallback
+                ? $"({DbReader.BuildPersistedFoldedNameMatchSql("s.name_folded", "@resolvedNameFolded")} OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name_folded(s.name) = @resolvedNameNormalizedFolded) OR sql_leaf_name_folded(s.name) = @resolvedNameLeafFolded)))"
+                : $"({DbReader.BuildPersistedFoldedNameMatchSql("s.name_folded", "@resolvedNameFolded")} OR (f.lang = 'sql' AND sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name_folded(s.name) = @resolvedNameNormalizedFolded))";
+        }
+
+        private static string BuildLegacyNameCondition(bool allowLeafFallback)
+        {
+            return allowLeafFallback
+                ? "(s.name = @resolvedName COLLATE NOCASE OR (f.lang = 'sql' AND ((sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name(s.name) = @resolvedNameNormalized COLLATE NOCASE) OR sql_leaf_name(s.name) = @resolvedNameLeaf COLLATE NOCASE)))"
+                : "(s.name = @resolvedName COLLATE NOCASE OR (f.lang = 'sql' AND sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name(s.name) = @resolvedNameNormalized COLLATE NOCASE))";
+        }
+
+        private static string BuildMatchOrderSql()
+        {
+            return @"CASE
+                     WHEN s.name = @resolvedName THEN 0
+                     WHEN f.lang = 'sql' AND sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name(s.name) = @resolvedNameNormalized THEN 1
+                     WHEN f.lang = 'sql' AND sql_segment_count(s.name) = @resolvedNameSegmentCount AND sql_normalize_name_folded(s.name) = @resolvedNameNormalizedFolded THEN 2
+                     WHEN @allowLeafFallback = 1 AND f.lang = 'sql' AND sql_leaf_name(s.name) = @resolvedNameLeaf THEN 3
+                     WHEN @allowLeafFallback = 1 AND f.lang = 'sql' AND sql_leaf_name_folded(s.name) = @resolvedNameLeafFolded THEN 4
+                     ELSE 5
+                   END";
+        }
+
+        public static void Bind(
+            DbReader reader,
+            SqliteCommand cmd,
+            ImpactDefinitionQueryPlan plan)
+        {
+            var request = plan.Request;
+            SqliteCommandPolicy.Add(cmd, "@resolvedName", request.ResolvedName);
+            SqliteCommandPolicy.Add(cmd, "@resolvedNameNormalized", request.NormalizedName);
+            SqliteCommandPolicy.Add(
+                cmd,
+                "@resolvedNameNormalizedFolded",
+                DbReader.FoldNameForLanguage(request.NormalizedName, request.Lang));
+            SqliteCommandPolicy.Add(cmd, "@resolvedNameLeaf", request.LeafName);
+            SqliteCommandPolicy.Add(
+                cmd,
+                "@resolvedNameLeafFolded",
+                DbReader.FoldNameForLanguage(request.LeafName, request.Lang));
+            SqliteCommandPolicy.Add(cmd, "@resolvedNameSegmentCount", request.SegmentCount);
+            SqliteCommandPolicy.Add(cmd, "@allowLeafFallback", request.AllowLeafFallback ? 1 : 0);
+            DbReader.AddCSharpExplicitInterfaceIdentityQueryParameter(
+                cmd,
+                "resolvedName",
+                request.ResolvedName);
+            BindQualifiedContainer(cmd, request);
+            if (reader._foldReady)
+            {
+                DbReader.AddPersistedFoldedNameQueryParameters(
+                    cmd,
+                    "@resolvedNameFolded",
+                    request.ResolvedName,
+                    request.Lang);
+            }
+            if (request.Lang != null)
+                SqliteCommandPolicy.Add(cmd, "@lang", request.Lang);
+            SqliteCommandPolicy.Add(cmd, "@definitionLimit", request.RepresentativeLimit);
+            SqliteCommandPolicy.Add(cmd, "@definitionOffset", request.RepresentativeOffset);
+            DbReader.AddPathFilterParameters(
+                cmd,
+                request.PathPatterns,
+                request.ExcludePathPatterns);
+        }
+
+        private static void BindQualifiedContainer(
+            SqliteCommand cmd,
+            ImpactDefinitionRequest request)
+        {
+            if (request.AllowLeafFallback)
+                return;
+
+            var container = GetQualifiedQueryContainer(request.ResolvedName);
+            SqliteCommandPolicy.Add(cmd, "@resolvedNameContainer", container);
+            SqliteCommandPolicy.Add(
+                cmd,
+                "@resolvedNameContainerSuffix",
+                $"%.{EscapeLikeQuery(container)}");
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.ImpactDefinitionQuerySql.cs b/src/CodeIndex/Database/DbReader.ImpactDefinitionQuerySql.cs
new file mode 100644
index 000000000..3788dd296
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactDefinitionQuerySql.cs
@@ -0,0 +1,173 @@
+using System.Text;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private static class ImpactDefinitionQuerySql
+    {
+        private const string CanonicalRepresentativeOrder =
+            "canonical_primary_rank, canonical_generated_rank, canonical_semantic_score DESC, canonical_declaration_identity COLLATE BINARY, path COLLATE BINARY, start_line, stable_start_column, symbol_id";
+        private const string ResultOrder =
+            "match_order, path_bucket, visibility_rank, name, path COLLATE BINARY, line, symbol_id";
+
+        public static string Build(string matchingSql, bool pathCaseSensitive)
+        {
+            var pathDistinctSql = pathCaseSensitive
+                ? "COUNT(DISTINCT path)"
+                : "COUNT(DISTINCT path COLLATE NOCASE)";
+            var precisePathDistinctSql = pathCaseSensitive
+                ? "COUNT(DISTINCT CASE WHEN is_precise = 1 THEN path END)"
+                : "COUNT(DISTINCT CASE WHEN is_precise = 1 THEN path END COLLATE NOCASE)";
+            var sql = new StringBuilder();
+            sql.Append($@"
+            WITH matching_definitions AS (
+                {matchingSql}
+            ),
+            ");
+            AppendRankingCtes(sql);
+            sql.Append(@"
+            ");
+            AppendSelectionCtes(sql, pathDistinctSql, precisePathDistinctSql);
+            sql.Append(@"
+            ");
+            AppendFinalSelect(sql);
+            return sql.ToString();
+        }
+
+        private static void AppendRankingCtes(StringBuilder sql)
+        {
+            sql.Append($@"ranked_definitions AS (
+                SELECT matching_definitions.*,
+                       ROW_NUMBER() OVER (
+                           PARTITION BY logical_partial_key
+                           ORDER BY {CanonicalRepresentativeOrder}
+                       ) AS logical_row_number,
+                       ROW_NUMBER() OVER (
+                           PARTITION BY logical_partial_key
+                           ORDER BY path COLLATE BINARY, start_line, stable_start_column, symbol_id
+                       ) AS family_member_row_number,
+                       COUNT(*) OVER (PARTITION BY logical_partial_key) AS logical_definition_sites
+                FROM matching_definitions
+            ),
+            family_ranked_definitions AS (
+                SELECT ranked_definitions.*,
+                       MAX(CASE WHEN logical_row_number = 1 THEN family_member_row_number END) OVER (
+                           PARTITION BY logical_partial_key
+                       ) AS representative_member_row_number
+                FROM ranked_definitions
+            ),
+            family_metadata_definitions AS (
+                SELECT family_ranked_definitions.*,
+                       MIN(canonical_primary_rank) OVER (PARTITION BY logical_partial_key) AS logical_primary_rank_min,
+                       MAX(canonical_primary_rank) OVER (PARTITION BY logical_partial_key) AS logical_primary_rank_max,
+                       MIN(canonical_generated_rank) OVER (PARTITION BY logical_partial_key) AS logical_generated_rank_min,
+                       MAX(canonical_generated_rank) OVER (PARTITION BY logical_partial_key) AS logical_generated_rank_max,
+                       MIN(canonical_semantic_score) OVER (PARTITION BY logical_partial_key) AS logical_semantic_score_min,
+                       MAX(canonical_semantic_score) OVER (PARTITION BY logical_partial_key) AS logical_semantic_score_max,
+                       MIN(canonical_declaration_identity) OVER (PARTITION BY logical_partial_key) AS logical_declaration_identity_min,
+                       MAX(canonical_declaration_identity) OVER (PARTITION BY logical_partial_key) AS logical_declaration_identity_max,
+                       json_group_array(json_object(
+                           'symbol_id', symbol_id,
+                           'path', path,
+                           'line', line,
+                           'start_line', start_line,
+                           'start_column', start_column,
+                           'end_line', end_line,
+                           'name', name,
+                           'signature', signature,
+                           'identifier_start_column', identifier_start_column,
+                           'generated', canonical_generated_rank
+                       )) FILTER (WHERE
+                           family_member_row_number <= CASE
+                               WHEN representative_member_row_number <= {LogicalPartialSymbolGrouper.FamilyMemberLimit}
+                               THEN {LogicalPartialSymbolGrouper.FamilyMemberLimit}
+                               ELSE {LogicalPartialSymbolGrouper.FamilyMemberLimit - 1}
+                           END
+                           OR logical_row_number = 1
+                       ) OVER (
+                           PARTITION BY logical_partial_key
+                           ORDER BY path COLLATE BINARY, start_line, stable_start_column, symbol_id
+                           ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+                       ) AS logical_family_members_json
+                FROM family_ranked_definitions
+            ),");
+        }
+
+        private static void AppendSelectionCtes(
+            StringBuilder sql,
+            string pathDistinctSql,
+            string precisePathDistinctSql)
+        {
+            sql.Append($@"logical_definitions AS (
+                SELECT *
+                FROM family_metadata_definitions
+                WHERE logical_row_number = 1
+            ),
+            requested_definitions AS (
+                SELECT logical_partial_key, 1 AS requested_row
+                FROM logical_definitions
+                ORDER BY {ResultOrder}
+                LIMIT @definitionLimit OFFSET @definitionOffset
+            ),
+            single_precise_definition AS (
+                SELECT logical_partial_key, 0 AS requested_row
+                FROM logical_definitions
+                WHERE is_precise = 1
+                ORDER BY {ResultOrder}
+                LIMIT 1
+            ),
+            selected_definition_keys AS (
+                SELECT logical_partial_key, requested_row
+                FROM requested_definitions
+                UNION ALL
+                SELECT precise.logical_partial_key, precise.requested_row
+                FROM single_precise_definition precise
+                WHERE NOT EXISTS (
+                    SELECT 1
+                    FROM requested_definitions requested
+                    WHERE requested.logical_partial_key = precise.logical_partial_key
+                )
+            ),
+            definition_stats AS (
+                SELECT COUNT(*) AS physical_count,
+                       {pathDistinctSql} AS physical_file_count,
+                       COUNT(DISTINCT logical_partial_key) AS logical_count,
+                       SUM(is_precise) AS precise_count,
+                       COUNT(DISTINCT CASE WHEN is_precise = 1 THEN logical_partial_key END) AS precise_logical_count,
+                       {precisePathDistinctSql} AS precise_file_count,
+                       SUM(is_non_callable) AS non_callable_count
+                FROM matching_definitions
+            )");
+        }
+
+        private static void AppendFinalSelect(StringBuilder sql)
+        {
+            sql.Append($@"SELECT logical.path, logical.lang, logical.kind, logical.name, logical.line,
+                   logical.start_line, logical.start_column, logical.end_line,
+                   logical.body_start_line, logical.body_end_line, logical.signature,
+                   logical.container_kind, logical.container_name,
+                   logical.visibility, logical.return_type,
+                   logical.container_qualified_name, logical.logical_partial_key,
+                   logical.symbol_id, logical.logical_definition_sites, selected.requested_row,
+                   stats.physical_count, stats.physical_file_count, stats.logical_count,
+                   stats.precise_count, stats.precise_file_count, stats.non_callable_count,
+                   CASE
+                       WHEN logical.logical_primary_rank_min <> logical.logical_primary_rank_max THEN '{LogicalPartialSymbolGrouper.ImplementationBodyReason}'
+                       WHEN logical.logical_generated_rank_min <> logical.logical_generated_rank_max THEN '{LogicalPartialSymbolGrouper.NonGeneratedSourceReason}'
+                       WHEN logical.logical_semantic_score_min <> logical.logical_semantic_score_max THEN '{LogicalPartialSymbolGrouper.SemanticDeclarationReason}'
+                       WHEN logical.logical_declaration_identity_min <> logical.logical_declaration_identity_max THEN '{LogicalPartialSymbolGrouper.CanonicalDeclarationIdentityReason}'
+                       ELSE '{LogicalPartialSymbolGrouper.StableLocationReason}'
+                   END AS representative_reason,
+                   logical.logical_family_members_json,
+                   CASE WHEN logical.logical_definition_sites > {LogicalPartialSymbolGrouper.FamilyMemberLimit} THEN 1 ELSE 0 END AS family_members_truncated,
+                   logical.identifier_start_column,
+                   stats.precise_logical_count
+            FROM selected_definition_keys selected
+            JOIN logical_definitions logical
+              ON logical.logical_partial_key = selected.logical_partial_key
+            CROSS JOIN definition_stats stats
+            ORDER BY {ResultOrder}");
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.ImpactDefinitions.cs b/src/CodeIndex/Database/DbReader.ImpactDefinitions.cs
new file mode 100644
index 000000000..baa699913
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.ImpactDefinitions.cs
@@ -0,0 +1,106 @@
+using CodeIndex.Indexer;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed record ImpactDefinitionRequest(
+        string ResolvedName,
+        string NormalizedName,
+        string LeafName,
+        int SegmentCount,
+        bool AllowLeafFallback,
+        int RepresentativeLimit,
+        int RepresentativeOffset,
+        string? Lang,
+        IReadOnlyList<string>? PathPatterns,
+        IReadOnlyList<string>? ExcludePathPatterns,
+        bool ExcludeTests)
+    {
+        public static ImpactDefinitionRequest Create(
+            string resolvedName,
+            int representativeLimit,
+            int representativeOffset,
+            string? lang,
+            IReadOnlyList<string>? pathPatterns,
+            IReadOnlyList<string>? excludePathPatterns,
+            bool excludeTests)
+        {
+            return new ImpactDefinitionRequest(
+                resolvedName,
+                SqlNameResolver.NormalizeQualifiedName(resolvedName),
+                SqlNameResolver.GetLeafName(resolvedName),
+                SqlNameResolver.GetSegmentCount(resolvedName),
+                !SqlNameResolver.HasQualifier(resolvedName),
+                Math.Max(1, representativeLimit),
+                Math.Max(0, representativeOffset),
+                lang,
+                pathPatterns,
+                excludePathPatterns,
+                excludeTests);
+        }
+    }
+
+    private sealed record ImpactDefinitionResolution(
+        List<SymbolResult> Definitions,
+        int PhysicalCount,
+        int PhysicalFileCount,
+        int LogicalCount,
+        int PreciseDefinitionCount,
+        int PreciseLogicalDefinitionCount,
+        int PreciseDefinitionFileCount,
+        int NonCallableDefinitionCount,
+        SymbolResult? SinglePreciseDefinition,
+        HashSet<long> PhysicalSymbolIds,
+        HashSet<string> PhysicalDefinitionPaths,
+        bool PhysicalSymbolIdsTruncated);
+
+    private ImpactDefinitionResolution ResolveImpactDefinitions(
+        string resolvedName,
+        int representativeLimit,
+        string? lang,
+        IReadOnlyList<string>? pathPatterns,
+        IReadOnlyList<string>? excludePathPatterns,
+        bool excludeTests,
+        int representativeOffset = 0)
+    {
+        var request = ImpactDefinitionRequest.Create(
+            resolvedName,
+            representativeLimit,
+            representativeOffset,
+            lang,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests);
+        EnsureCSharpCallableTypeKinds(request.Lang, [request.LeafName], exact: true);
+
+        ImpactDefinitionProjection projection;
+        ImpactDefinitionQueryPlan plan;
+        using (var cmd = _conn.CreateCommand())
+        {
+            plan = ImpactDefinitionQueryBuilder.Build(this, cmd, request);
+            cmd.CommandText = plan.Sql;
+            ImpactDefinitionQueryBuilder.Bind(this, cmd, plan);
+            projection = ImpactDefinitionRowProjector.Read(cmd);
+        }
+
+        var families = ImpactDefinitionFamilyResolver.Resolve(
+            this,
+            plan,
+            projection.Definitions);
+        var stats = projection.Stats;
+        return new ImpactDefinitionResolution(
+            projection.Definitions,
+            stats.PhysicalCount,
+            stats.PhysicalFileCount,
+            stats.LogicalCount,
+            stats.PreciseDefinitionCount,
+            stats.PreciseLogicalDefinitionCount,
+            stats.PreciseDefinitionFileCount,
+            stats.NonCallableDefinitionCount,
+            stats.PreciseLogicalDefinitionCount == 1 ? projection.SinglePreciseDefinition : null,
+            families.PhysicalSymbolIds,
+            families.PhysicalDefinitionPaths,
+            families.Truncated);
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.LogicalPartialQuerySql.cs b/src/CodeIndex/Database/DbReader.LogicalPartialQuerySql.cs
new file mode 100644
index 000000000..51c02b916
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.LogicalPartialQuerySql.cs
@@ -0,0 +1,79 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed record LogicalPartialCanonicalSql(
+        string LogicalPartialKey,
+        string Generated,
+        string PrimaryRank,
+        string SemanticScore,
+        string DeclarationIdentity);
+
+    private static class LogicalPartialQuerySql
+    {
+        public static LogicalPartialCanonicalSql Build(
+            DbReader reader,
+            string signatureSql,
+            string containerNameSql,
+            string containerQualifiedNameSql,
+            string familyKeySql,
+            string returnTypeSql,
+            string bodyStartLineSql,
+            string bodyEndLineSql)
+        {
+            var logicalPartialKey = BuildKey(
+                reader,
+                signatureSql,
+                containerNameSql,
+                containerQualifiedNameSql,
+                familyKeySql,
+                returnTypeSql);
+            var generated = reader._fileColumns.Contains("generated")
+                ? "CASE WHEN COALESCE(f.generated, 0) <> 0 OR codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END"
+                : "CASE WHEN codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END";
+            var primaryRank = LogicalPartialSymbolGrouper.BuildSqlPrimaryRankExpression(
+                "s.kind",
+                bodyStartLineSql,
+                bodyEndLineSql);
+            var semanticScore = LogicalPartialSymbolGrouper.BuildSqlSemanticScoreExpression(
+                signatureSql,
+                "s.kind",
+                reader.GetSymbolColumnSql("declaration_semantic_score"));
+            var fallbackIdentity = BuildDeclarationIdentity(signatureSql);
+            var declarationIdentity =
+                $"CASE WHEN s.kind IN ('function', 'test.method') THEN COALESCE(csharp_partial_callable_identity({signatureSql}, s.name, {returnTypeSql}), {fallbackIdentity}) ELSE {fallbackIdentity} END";
+            return new LogicalPartialCanonicalSql(
+                logicalPartialKey,
+                generated,
+                primaryRank,
+                semanticScore,
+                declarationIdentity);
+        }
+
+        public static string BuildKey(
+            DbReader reader,
+            string signatureSql,
+            string containerNameSql,
+            string containerQualifiedNameSql,
+            string familyKeySql,
+            string returnTypeSql)
+        {
+            return LogicalPartialSymbolGrouper.BuildSqlKeyExpression(
+                "f.lang",
+                "s.kind",
+                "s.name",
+                "s.id",
+                "f.path",
+                signatureSql,
+                containerNameSql,
+                containerQualifiedNameSql,
+                familyKeySql,
+                returnTypeSql,
+                reader.GetSymbolColumnSql("is_partial_declaration"),
+                reader._hotspotFamilyReadyLanguages.Contains("csharp"));
+        }
+
+        private static string BuildDeclarationIdentity(string signatureSql)
+            => $"csharp_partial_declaration_identity({signatureSql})";
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchListQueryBuilder.cs b/src/CodeIndex/Database/DbReader.SymbolSearchListQueryBuilder.cs
index 471e29cbb..8cb3d1681 100644
--- a/src/CodeIndex/Database/DbReader.SymbolSearchListQueryBuilder.cs
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchListQueryBuilder.cs
@@ -29,20 +29,21 @@ private sealed record SymbolSearchRankingSql(
         string ComplexityScore,
         string ExactNameOrder);
 
-    private sealed record SymbolSearchCanonicalSql(
-        string LogicalPartialKey,
-        string Generated,
-        string PrimaryRank,
-        string SemanticScore,
-        string DeclarationIdentity);
-
     private string BuildSymbolSearchListSql(SymbolSearchQueryPlan plan)
     {
         var columns = BuildSymbolSearchColumnSql();
         var includeRankSignals =
             plan.SortMode != SymbolSortMode.Name && _hasReferencesTable;
         var ranking = BuildSymbolSearchRankingSql(columns, includeRankSignals);
-        var canonical = BuildSymbolSearchCanonicalSql(columns);
+        var canonical = LogicalPartialQuerySql.Build(
+            this,
+            columns.Signature,
+            columns.ContainerName,
+            columns.ContainerQualifiedName,
+            columns.FamilyKey,
+            columns.ReturnType,
+            columns.BodyStartLine,
+            columns.BodyEndLine);
         var sql = BuildSymbolSearchSelectSql(columns, ranking, canonical);
         sql += SymbolSearchQueryPredicateBuilder.BuildFull(this, plan);
         SymbolSearchQueryPredicateBuilder.AppendFilters(
@@ -186,41 +187,10 @@ AND ds.name <> ''
             : string.Empty;
     }
 
-    private SymbolSearchCanonicalSql BuildSymbolSearchCanonicalSql(
-        SymbolSearchColumnSql columns)
-    {
-        var logicalPartialKey = BuildLogicalPartialKeySql(
-            columns.Signature,
-            columns.ContainerName,
-            columns.ContainerQualifiedName,
-            columns.FamilyKey,
-            columns.ReturnType);
-        var generated = _fileColumns.Contains("generated")
-            ? "CASE WHEN COALESCE(f.generated, 0) <> 0 OR codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END"
-            : "CASE WHEN codeindex_generated_file_name(f.path) THEN 1 ELSE 0 END";
-        var primaryRank = LogicalPartialSymbolGrouper.BuildSqlPrimaryRankExpression(
-            "s.kind",
-            columns.BodyStartLine,
-            columns.BodyEndLine);
-        var semanticScore = LogicalPartialSymbolGrouper.BuildSqlSemanticScoreExpression(
-            columns.Signature,
-            "s.kind",
-            GetSymbolColumnSql("declaration_semantic_score"));
-        var fallbackIdentity = BuildCanonicalDeclarationIdentitySql(columns.Signature);
-        var declarationIdentity =
-            $"CASE WHEN s.kind IN ('function', 'test.method') THEN COALESCE(csharp_partial_callable_identity({columns.Signature}, s.name, {columns.ReturnType}), {fallbackIdentity}) ELSE {fallbackIdentity} END";
-        return new SymbolSearchCanonicalSql(
-            logicalPartialKey,
-            generated,
-            primaryRank,
-            semanticScore,
-            declarationIdentity);
-    }
-
     private string BuildSymbolSearchSelectSql(
         SymbolSearchColumnSql columns,
         SymbolSearchRankingSql ranking,
-        SymbolSearchCanonicalSql canonical)
+        LogicalPartialCanonicalSql canonical)
     {
         return $@"
             SELECT f.path, f.lang, s.kind, {GetSymbolColumnSql("sub_kind")} AS sub_kind, s.name, s.line,
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchSql.cs b/src/CodeIndex/Database/DbReader.SymbolSearchSql.cs
index e1a9f08ee..fd441c41f 100644
--- a/src/CodeIndex/Database/DbReader.SymbolSearchSql.cs
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchSql.cs
@@ -2,34 +2,9 @@ namespace CodeIndex.Database;
 
 public partial class DbReader
 {
-    private string BuildLogicalPartialKeySql(
-        string signatureSql,
-        string containerNameSql,
-        string containerQualifiedNameSql,
-        string familyKeySql,
-        string returnTypeSql)
-    {
-        return LogicalPartialSymbolGrouper.BuildSqlKeyExpression(
-            "f.lang",
-            "s.kind",
-            "s.name",
-            "s.id",
-            "f.path",
-            signatureSql,
-            containerNameSql,
-            containerQualifiedNameSql,
-            familyKeySql,
-            returnTypeSql,
-            GetSymbolColumnSql("is_partial_declaration"),
-            _hotspotFamilyReadyLanguages.Contains("csharp"));
-    }
-
     private static string GetGenericSymbolRankNamePenaltySql(string nameSql)
         => $"CASE WHEN lower({nameSql}) IN {GenericSymbolRankNamesSql} THEN {GenericSymbolRankNamePenaltySqlLiteral} ELSE 1.0 END";
 
-    private static string BuildCanonicalDeclarationIdentitySql(string signatureSql)
-        => $"csharp_partial_declaration_identity({signatureSql})";
-
     private static string BuildLogicalPartialSymbolQuery(string matchingSymbolsSql, SymbolSortMode sortMode)
     {
         var orderBy = BuildLogicalPartialSortOrderBy(sortMode);
diff --git a/src/CodeIndex/Database/DbReader.SymbolSearchTotalCount.cs b/src/CodeIndex/Database/DbReader.SymbolSearchTotalCount.cs
index 53040064b..9f88eb61f 100644
--- a/src/CodeIndex/Database/DbReader.SymbolSearchTotalCount.cs
+++ b/src/CodeIndex/Database/DbReader.SymbolSearchTotalCount.cs
@@ -38,7 +38,8 @@ private QueryCountResult ExecuteTotalSymbolSearch(SymbolSearchQueryPlan plan)
         }
         using var cmd = _conn.CreateCommand();
 
-        var logicalPartialKeySql = BuildLogicalPartialKeySql(
+        var logicalPartialKeySql = LogicalPartialQuerySql.BuildKey(
+            this,
             GetSymbolColumnSql("signature"),
             GetSymbolColumnSql("container_name"),
             GetSymbolColumnSql("container_qualified_name"),
diff --git a/tests/CodeIndex.Tests/DbReaderImpactTests.cs b/tests/CodeIndex.Tests/DbReaderImpactTests.cs
index 82536b162..74c56a412 100644
--- a/tests/CodeIndex.Tests/DbReaderImpactTests.cs
+++ b/tests/CodeIndex.Tests/DbReaderImpactTests.cs
@@ -736,6 +736,12 @@ public void Boot(FooService service)
             """);
 
         var analysis = _reader.AnalyzeImpact("FooService", maxDepth: 3, limit: 10);
+        var pagedAnalysis = _reader.AnalyzeImpact(
+            "FooService",
+            maxDepth: 3,
+            limit: 1,
+            offset: 1,
+            responseCollection: "definitions");
 
         Assert.Equal("file_dependency_hints", analysis.ImpactMode);
         Assert.True(analysis.Heuristic);
@@ -744,6 +750,15 @@ public void Boot(FooService service)
         Assert.Equal(2, analysis.DefinitionCount);
         Assert.Equal(1, analysis.HintCount);
         Assert.Equal("src/App.cs", Assert.Single(analysis.FileImpacts).SourcePath);
+
+        Assert.Equal("namespace", Assert.Single(pagedAnalysis.Definitions).Kind);
+        Assert.Equal(2, pagedAnalysis.DefinitionCount);
+        Assert.Equal(2, pagedAnalysis.LogicalDefinitionCount);
+        Assert.True(pagedAnalysis.HasClassLikeDefinitions);
+        Assert.Equal("file_dependency_hints", pagedAnalysis.ImpactMode);
+        Assert.True(pagedAnalysis.Heuristic);
+        Assert.Equal(1, pagedAnalysis.HintCount);
+        Assert.Equal("src/App.cs", Assert.Single(pagedAnalysis.FileImpacts).SourcePath);
     }
 
     [Fact]
@@ -1060,6 +1075,32 @@ public void AnalyzeImpact_PartialFamilyBudgetIsIndependentFromTraversalTruncatio
         Assert.False(analysis.CountIsAuthoritative);
     }
 
+    [Fact]
+    public void AnalyzeImpact_PartialFamilyBeyondProjectionLimitResolvesCompleteRootSet()
+    {
+        const int familyMemberCount = 51;
+        for (var index = 0; index < familyMemberCount; index++)
+        {
+            InsertIndexedFile(
+                $"src/Large.Part{index:D2}.cs",
+                "csharp",
+                "public partial class Large { }");
+        }
+        var reader = CreateReferenceIdentityReadyImpactReader();
+        reader.ImpactPartialFamilyMemberBudget = 64;
+
+        var analysis = reader.AnalyzeImpact("Large", maxDepth: 2, limit: 10);
+
+        Assert.Equal(familyMemberCount, analysis.DefinitionCount);
+        Assert.Equal(1, analysis.LogicalDefinitionCount);
+        Assert.Equal("logical_partial_family", analysis.TraversalRootScope);
+        Assert.Equal(familyMemberCount, analysis.PartialFamilyMemberCount);
+        Assert.Equal(familyMemberCount, analysis.PartialFamilyMemberRootCount);
+        Assert.Equal(64, analysis.PartialFamilyMemberRootLimit);
+        Assert.False(analysis.PartialFamilyMemberRootTruncated);
+        Assert.Equal(0, analysis.PartialFamilyMemberRootOmitted);
+    }
+
     [Fact]
     public void AnalyzeImpact_DuplicateDefinitionsInOneFile_ExplainsAmbiguity()
     {

From 2d4e745e04641ecec868a0947ffecc9552e7d079 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 13:28:05 +0900
Subject: [PATCH 17/45] Decompose MCP per-file indexing

---
 .../Mcp/McpToolHandlers.Indexing.Execution.cs | 585 ++++--------------
 ...dlers.Indexing.ExtractedFilePersistence.cs | 249 ++++++++
 .../Mcp/McpToolHandlers.Indexing.FileLoop.cs  | 201 ++++++
 ...cpToolHandlers.Indexing.FilePersistence.cs | 247 ++++++++
 .../McpToolHandlers.Indexing.SkippedFiles.cs  | 190 ++++++
 5 files changed, 991 insertions(+), 481 deletions(-)
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.Indexing.ExtractedFilePersistence.cs
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.Indexing.FileLoop.cs
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.Indexing.FilePersistence.cs
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.Indexing.SkippedFiles.cs

diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
index 4c2a7bb80..2249e0b18 100644
--- a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
@@ -839,7 +839,7 @@ void DeferCSharpMutationsForLoadedSnapshotDrift(string path)
         }
 
         bool LoadedCSharpWorkspaceSnapshotMatches(
-            CSharpStaticInterfacePrepass.FileTarget target,
+            in CSharpStaticInterfacePrepass.FileTarget target,
             FileRecord record)
         {
             if (target.Language != "csharp" || csharpWorkspaceFileSnapshots == null)
@@ -876,21 +876,8 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
         var freshCountChunks = 0L;
         var freshCountSymbols = 0L;
         var freshCountReferences = 0L;
-        void CountFreshInsertedRows(
-            int chunkCount = 0,
-            int symbolCount = 0,
-            int referenceCount = 0)
-        {
-            if (!startedWithNoIndexedFiles)
-                return;
-
-            freshCountFiles++;
-            freshCountChunks += chunkCount;
-            freshCountSymbols += symbolCount;
-            freshCountReferences += referenceCount;
-        }
-
-        IndexedFileStatReuseResult? GetStatMatchedFile(CSharpStaticInterfacePrepass.FileTarget target)
+        IndexedFileStatReuseResult? GetStatMatchedFile(
+            in CSharpStaticInterfacePrepass.FileTarget target)
         {
             var allowStatReuse = !rebuild
                 && !startedWithNoIndexedFiles
@@ -914,7 +901,7 @@ void CountFreshInsertedRows(
                         target.FilePath,
                         target.IndexPath,
                         target.Language,
-                        IsGeneratedExtractionSuppressed(target));
+                        target.GeneratedExtractionSuppressed == true);
         }
 
         IndexedFileStatReuseResult?[]? statMatchedFiles = null;
@@ -1333,478 +1320,114 @@ await EmitProgressNotificationAsync(
         if (purgedRefs > 0)
             mutualRecursionRefreshNeeded = true;
 
-        for (var targetIndex = 0; targetIndex < fileTargets.Length; targetIndex++)
+        void DeferCSharpMutationsForStatRevalidation(
+            in CSharpStaticInterfacePrepass.FileTarget target)
         {
-            var target = fileTargets[targetIndex];
-            var filePath = target.FilePath;
-            var fileBatchMarked = false;
+            // The final global C# check passed, but this file changed before its
+            // actual skip. Row mutations have already begun, so preserve every C#
+            // row from this point, leave evidence unknown, and require a clean retry.
+            // global最終check後にC# statが崩れた場合、以後のC# rowを保持してpartialにする。
+            preservePriorPositiveCSharpSourceNoOp = false;
+            deferCSharpMutationsForIncompleteScan = true;
+            csharpSourceEvidenceForStamp = false;
+            csharpSourceEvidenceComplete = false;
+            writer.SetCSharpStaticInterfaceSourceEvidence(null);
+            RecordCSharpWorkspaceFailure(
+                target.IndexPath,
+                "csharp_stat_revalidation",
+                new IOException(
+                    "A C# source changed after final workspace preflight; rerun indexing to refresh the complete C# graph."));
             try
             {
-                requestToken.ThrowIfCancellationRequested();
-                authorizedRoot.EnsureAuthorizedEntry(filePath);
-                if (deferCSharpMutationsForIncompleteScan
-                    && target.Language == "csharp")
-                {
-                    try
-                    {
-                        var info = new FileInfo(filePath);
-                        if (info.Exists && info.Length >= 0)
-                            RememberReadableFileSize(filePath, info.Length);
-                    }
-                    catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or NotSupportedException or ArgumentException)
-                    {
-                    }
-                    skipped++;
-                    processed++;
-                    await EmitProgressNotificationAsync(progressToken, processed, files.Count).ConfigureAwait(false);
-                    continue;
-                }
-                IndexedFileStatReuseResult? statMatchedFile = null;
-                if (statPreflightCompleted != null)
-                {
-                    if (statPreflightCompleted[targetIndex])
-                    {
-                        var cachedStatMatch = statMatchedFiles![targetIndex];
-                        if (cachedStatMatch != null)
-                        {
-                            // The dirty-byte preflight may span thousands of later files. Re-stat
-                            // cached matches at their actual skip point so that window cannot turn
-                            // a changed file into a clean-run stale-row skip. This intentionally
-                            // bypasses the C# prepass cache too.
-                            // dirty-byte preflight 後の skip 時点で再 stat し、後続 file の
-                            // preflight 中に変化した row を stale のまま再利用しない。
-                            statMatchedFile = reuseFinalCSharpStatAtActualSkip
-                                              && target.Language == "csharp"
-                                ? cachedStatMatch
-                                : IndexedFileStatReuse.TryGetReusableUnchangedFile(
-                                    reusableIndexedFileStats!,
-                                    target.FilePath,
-                                    target.IndexPath,
-                                    target.Language,
-                                    IsGeneratedExtractionSuppressed(target));
-                        }
-                    }
-                    else
-                    {
-                        statMatchedFile = GetStatMatchedFile(target);
-                    }
-                }
-                if (preservePriorPositiveCSharpSourceNoOp
-                    && target.Language == "csharp"
-                    && statMatchedFile == null)
-                {
-                    // The final global C# check passed, but this file changed before its
-                    // actual skip. Row mutations have already begun, so preserve every C#
-                    // row from this point, leave evidence unknown, and require a clean retry.
-                    // global最終check後にC# statが崩れた場合、以後のC# rowを保持してpartialにする。
-                    preservePriorPositiveCSharpSourceNoOp = false;
-                    deferCSharpMutationsForIncompleteScan = true;
-                    csharpSourceEvidenceForStamp = false;
-                    csharpSourceEvidenceComplete = false;
-                    writer.SetCSharpStaticInterfaceSourceEvidence(null);
-                    RecordCSharpWorkspaceFailure(
-                        target.IndexPath,
-                        "csharp_stat_revalidation",
-                        new IOException(
-                            "A C# source changed after final workspace preflight; rerun indexing to refresh the complete C# graph."));
-                    try
-                    {
-                        var info = new FileInfo(filePath);
-                        if (info.Exists && info.Length >= 0)
-                            RememberReadableFileSize(filePath, info.Length);
-                    }
-                    catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or NotSupportedException or ArgumentException)
-                    {
-                    }
-                    skipped++;
-                    processed++;
-                    await EmitProgressNotificationAsync(progressToken, processed, files.Count).ConfigureAwait(false);
-                    continue;
-                }
-                if (statMatchedFile != null)
-                {
-                    skipped++;
-                    processed++;
-                    RememberReadableFileSize(filePath, statMatchedFile.Value.Size);
-                    if (FileIndexer.SupportsHotspotFamilyMarkerLanguage(target.Language) && target.Language != null)
-                    {
-                        reusedHotspotFamilyLanguages ??= new HashSet<string>(StringComparer.Ordinal);
-                        reusedHotspotFamilyLanguages.Add(target.Language);
-                    }
-                    await EmitProgressNotificationAsync(progressToken, processed, files.Count).ConfigureAwait(false);
-                    continue;
-                }
-
-                McpIndexFileContentLoadForTesting?.Invoke(target.IndexPath);
-                var loaded = indexer.BuildLoadedRecordWithRawBytes(
-                    filePath,
-                    target.RelativePath,
-                    target.Language,
-                    requestToken);
-                var record = loaded.Record;
-                if (!LoadedCSharpWorkspaceSnapshotMatches(target, record))
-                {
-                    RememberReadableFileSize(filePath, record.Size);
-                    skipped++;
-                    processed++;
-                    await EmitProgressNotificationAsync(progressToken, processed, files.Count).ConfigureAwait(false);
-                    continue;
-                }
-                RememberReadableFileSize(filePath, record.Size);
-                var content = loaded.Content;
-                var rawBytes = loaded.RawBytes;
-                var generatedSuppressionIssue = IsGeneratedExtractionSuppressed(target)
-                    ? indexer.BuildGeneratedCodeExtractionSkippedIssue(record.Path)
-                    : null;
-                var existingId = writer.GetReusableUnchangedFileId(
-                    record.Path,
-                    record.Modified,
-                    record.Checksum,
-                    size: record.Size,
-                    lines: record.Lines,
-                    language: record.Lang,
-                    generated: record.Generated,
-                    maxSymbolsPerFile: maxSymbolsPerFile,
-                    maxReferencesPerFile: maxReferencesPerFile,
-                    generatedExtractionSuppressed: generatedSuppressionIssue != null,
-                    allowReuse: !rebuild
-                        && !startedWithNoIndexedFiles
-                        && symbolKindFilterMatchesPrior
-                        && (record.Lang != "csharp" || csharpIndexedProjectRootCompatible)
-                        && (record.Lang != "csharp" || csharpSymbolNameContractMatchesCurrent)
-                        && (record.Lang != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
-                        && (record.Lang != "sql" || sqlGraphContractMatchesCurrent)
-                        && (record.Lang is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent)
-                        && AllowReuseWithCurrentHotspotFamilyTrust(record.Lang, hotspotFamilyTrustMatchesCurrent));
-                if (existingId != null)
-                {
-                    skipped++;
-                    processed++;
-                    if (FileIndexer.SupportsHotspotFamilyMarkerLanguage(record.Lang) && record.Lang != null)
-                    {
-                        reusedHotspotFamilyLanguages ??= new HashSet<string>(StringComparer.Ordinal);
-                        reusedHotspotFamilyLanguages.Add(record.Lang);
-                    }
-                    continue;
-                }
-
-                if (!useFullRunBatchMarker)
-                {
-                    writer.MarkBatchInProgress();
-                    fileBatchMarked = true;
-                }
-                MarkSymbolKindFilterMetaIncompleteOnce();
-                if (record.Lang == "csharp")
-                    csharpMetadataTargetsNeedRefresh = true;
-                var recordRequiresTypeScriptAugmentationRefresh = record.Lang == "typescript";
-                using var txn = writer.BeginTransaction(requestToken, "mcp index file");
-                if (recordRequiresTypeScriptAugmentationRefresh)
-                    RequireTypeScriptAugmentationRefresh();
-                var referenceIdentityChanged = false;
-                var fileId = startedWithNoIndexedFiles
-                    ? writer.InsertNewFile(record)
-                    : writer.UpsertFile(record, out referenceIdentityChanged);
-                if (referenceIdentityChanged)
-                    mutualRecursionRefreshNeeded = true;
-                var chunks = ChunkSplitter.SplitNormalized(fileId, content, loaded.Facts);
-                if (generatedSuppressionIssue != null)
-                {
-                    writer.InsertChunks(chunks, requestToken);
-                    writer.InsertSymbols([], requestToken);
-                    writer.InsertReferencesInAtomicFileScope([], requestToken);
-                    var issues = IndexCommandRunner.AppendIssueIfMissing(
-                        FileIndexer.ValidateContent(record.Path, rawBytes, content, record.Lang, loaded.Inspection, loaded.Facts),
-                        generatedSuppressionIssue);
-                    InsertIssuesForIndexedFile(fileId, issues);
-                    WriteProjectRootOnce();
-                    if (!useFullRunBatchMarker)
-                        writer.ClearBatchInProgress();
-                    txn.Commit();
-                    if (!string.IsNullOrWhiteSpace(record.Lang))
-                        indexedSymbolExtractorLanguages.Add(record.Lang);
-                    CountFreshInsertedRows(chunkCount: chunks.Count);
-                    ftsMutated = true;
-                    processed++;
-                    await EmitProgressNotificationAsync(progressToken, processed, files.Count).ConfigureAwait(false);
-                    McpIndexFileCommittedForTesting?.Invoke(record.Path);
-                    continue;
-                }
-                List<SymbolRecord> symbols;
-                FileIssue? symbolRegexTimeoutIssue;
-                if (string.Equals(record.Lang, "csharp", StringComparison.Ordinal)
-                    && record.Checksum is { } checksum
-                    && csharpPrepassSymbolArtifacts?.TryTake(
-                        record.Path,
-                        checksum,
-                        out var symbolArtifact) == true)
-                {
-                    symbols = symbolArtifact.Symbols;
-                    foreach (var symbol in symbols)
-                        symbol.FileId = fileId;
-                    symbolRegexTimeoutIssue = null;
-                }
-                else
-                {
-                    using var regexTimeouts = BoundedRegex.CaptureTimeouts(
-                        record.Lang,
-                        "symbol_extraction");
-                    symbols = SymbolExtractor.ExtractNormalized(
-                        fileId,
-                        record.Lang,
-                        content,
-                        loaded.HasOversizeLine,
-                        filePath,
-                        projectPath,
-                        requestToken,
-                        loaded.ConflictMarkerLine,
-                        patternConfigsAlreadyLoaded: true);
-                    symbolRegexTimeoutIssue =
-                        IndexCommandRunner.BuildRegexTimeoutIssue(
-                            record.Path,
-                            regexTimeouts);
-                }
-                var familyScopeKey = indexer.GetFamilyScopeKey(filePath, record.Lang);
-                SymbolExtractor.ApplyFamilyScope(symbols, familyScopeKey, record.Lang);
-                var fileContext = new FileContext(projectPath, record.Path, filePath, record.Lang);
-                postExtractionHooks.Value.ObserveCSharpStaticInterfaceSourceSymbols(fileContext, symbols);
-                postExtractionHooks.Value.OnSymbolsExtractedAfterSourceObservation(
-                    fileContext,
-                    symbols,
-                    content,
-                    familyScopeKey);
-                symbolsDroppedByKindFilter += symbolKindFilter.Apply(symbols);
-                var committedChunkCount = 0;
-                var committedSymbolCount = 0;
-                var committedReferenceCount = 0;
-                if (symbols.Count > maxSymbolsPerFile)
-                {
-                    var issue = BuildMcpSymbolCountExceededIssue(record.Path, symbols.Count, maxSymbolsPerFile);
-                    IReadOnlyList<FileIssue> capIssues = symbolRegexTimeoutIssue == null
-                        ? [issue]
-                        : IndexCommandRunner.AppendIssue([symbolRegexTimeoutIssue], issue);
-                    writer.InsertSymbols([], requestToken);
-                    writer.InsertReferencesInAtomicFileScope([], requestToken);
-                    InsertIssuesForIndexedFile(fileId, capIssues);
-                }
-                else
-                {
-                    writer.InsertChunks(chunks, requestToken);
-                    writer.InsertSymbols(symbols, requestToken);
-                    List<ReferenceRecord> references;
-                    ReferenceExtractionResult referenceExtraction;
-                    FileIssue? regexTimeoutIssue;
-                    using (var regexTimeouts = BoundedRegex.CaptureTimeouts(record.Lang, "reference_extraction"))
-                    {
-                        referenceExtraction = ReferenceExtractor.ExtractDetailedNormalized(
-                            fileId,
-                            record.Lang,
-                            content,
-                            loaded.HasOversizeLine,
-                            symbols,
-                            record.Path,
-                            record.Lang == "csharp" ? csharpWorkspace.Symbols : null,
-                            requestToken,
-                            maxReferenceCount: maxReferencesPerFile + 1,
-                            conflictMarkerLine: loaded.ConflictMarkerLine,
-                            workspaceRoot: projectPath,
-                            csharpStaticInterfaceMemberLookups: csharpWorkspace.StaticInterfaceMemberLookups,
-                            csharpQualifiedPatternLookups: csharpWorkspace.QualifiedPatternLookups);
-                        references = referenceExtraction.References;
-                        regexTimeoutIssue = IndexCommandRunner.BuildRegexTimeoutIssue(record.Path, regexTimeouts);
-                    }
-                    postExtractionHooks.Value.OnReferencesExtracted(fileContext, references);
-                    FileIssue? referenceCapIssue = null;
-                    if (references.Count > maxReferencesPerFile)
-                    {
-                        referenceCapIssue = BuildMcpReferenceCountExceededIssue(record.Path, references.Count, maxReferencesPerFile);
-                        references = [];
-                    }
-                    if (startedWithNoIndexedFiles)
-                        writer.InsertReferencesForNewFilesInAtomicFileScope(references, refreshMutualRecursionFlags: false, requestToken);
-                    else
-                        writer.InsertReferencesInAtomicFileScope(references, refreshMutualRecursionFlags: false, requestToken);
-                    if (symbols.Count > 0 || references.Count > 0)
-                        mutualRecursionRefreshNeeded = true;
-                    committedChunkCount = chunks.Count;
-                    committedSymbolCount = symbols.Count;
-                    committedReferenceCount = references.Count;
-                    // Keep MCP index parity with CLI index: persist file-level validation issues too.
-                    // MCPインデックスもCLIインデックスと同等に、ファイル検証issueを保存する。
-                    IReadOnlyList<FileIssue> issues = FileIndexer.ValidateContent(record.Path, rawBytes, content, record.Lang, loaded.Inspection, loaded.Facts);
-                    if (symbolRegexTimeoutIssue != null)
-                        issues = IndexCommandRunner.AppendIssue(issues, symbolRegexTimeoutIssue);
-                    if (regexTimeoutIssue != null)
-                        issues = IndexCommandRunner.AppendIssue(issues, regexTimeoutIssue);
-                    issues = IndexCommandRunner.AppendReferenceExtractionDiagnosticIssues(
-                        issues,
-                        record.Path,
-                        referenceExtraction.Diagnostics);
-                    if (referenceCapIssue != null)
-                        issues = IndexCommandRunner.AppendIssue(issues, referenceCapIssue);
-                    InsertIssuesForIndexedFile(fileId, issues);
-                }
-                WriteProjectRootOnce();
-                if (!useFullRunBatchMarker)
-                    writer.ClearBatchInProgress();
-                txn.Commit();
-                if (!string.IsNullOrWhiteSpace(record.Lang))
-                    indexedSymbolExtractorLanguages.Add(record.Lang);
-                CountFreshInsertedRows(committedChunkCount, committedSymbolCount, committedReferenceCount);
-                ftsMutated = true;
-                McpIndexFileCommittedForTesting?.Invoke(record.Path);
-            }
-            catch (McpIndexAuthorizationException)
-            {
-                if (fileBatchMarked || useFullRunBatchMarker)
-                    writer.ClearBatchInProgress();
-                throw;
-            }
-            catch (FileIndexer.BinaryFileSkippedException ex)
-            {
-                try
-                {
-                    var skippedRecord = indexer.BuildSkippedFileRecord(filePath, target.RelativePath, target.Language);
-                    RememberReadableFileSize(filePath, skippedRecord.Size);
-                    if (!LoadedCSharpWorkspaceSnapshotMatches(target, skippedRecord))
-                    {
-                        skipped++;
-                    }
-                    else
-                    {
-                        if (skippedRecord.Lang == "csharp")
-                            csharpMetadataTargetsNeedRefresh = true;
-                        var skippedRecordRequiresTypeScriptAugmentationRefresh = skippedRecord.Lang == "typescript";
-                        using var txn = writer.BeginTransaction(requestToken, "mcp index skipped binary");
-                        if (skippedRecordRequiresTypeScriptAugmentationRefresh)
-                            RequireTypeScriptAugmentationRefresh();
-                        var referenceIdentityChanged = false;
-                        var fileId = startedWithNoIndexedFiles
-                            ? writer.InsertNewFile(skippedRecord)
-                            : writer.UpsertFile(skippedRecord, out referenceIdentityChanged);
-                        if (referenceIdentityChanged)
-                            mutualRecursionRefreshNeeded = true;
-                        writer.InsertChunks([], requestToken);
-                        writer.InsertSymbols([], requestToken);
-                        writer.InsertReferencesInAtomicFileScope([], requestToken);
-                        InsertIssuesForIndexedFile(fileId, [IndexCommandRunner.BuildNullByteIssue(ex)]);
-                        WriteProjectRootOnce();
-                        txn.Commit();
-                        if (!string.IsNullOrWhiteSpace(skippedRecord.Lang))
-                            indexedSymbolExtractorLanguages.Add(skippedRecord.Lang);
-                        CountFreshInsertedRows();
-                        ftsMutated = true;
-                    }
-                }
-                catch (Exception cleanupEx) when (cleanupEx is not McpIndexAuthorizationException)
-                {
-                    errors++;
-                    failures.Add(BuildIndexFileFailure(projectPath, filePath, cleanupEx, "record_skipped_binary"));
-                }
-            }
-            catch (FileIndexer.FileTooLargeSkippedException ex)
-            {
-                try
-                {
-                    var skippedRecord = indexer.BuildSkippedFileRecord(filePath, target.RelativePath, target.Language);
-                    RememberReadableFileSize(filePath, skippedRecord.Size);
-                    if (!LoadedCSharpWorkspaceSnapshotMatches(target, skippedRecord))
-                    {
-                        skipped++;
-                    }
-                    else
-                    {
-                        if (skippedRecord.Lang == "csharp")
-                            csharpMetadataTargetsNeedRefresh = true;
-                        var skippedRecordRequiresTypeScriptAugmentationRefresh = skippedRecord.Lang == "typescript";
-                        using var txn = writer.BeginTransaction(requestToken, "mcp index skipped oversized file");
-                        if (skippedRecordRequiresTypeScriptAugmentationRefresh)
-                            RequireTypeScriptAugmentationRefresh();
-                        var referenceIdentityChanged = false;
-                        var fileId = startedWithNoIndexedFiles
-                            ? writer.InsertNewFile(skippedRecord)
-                            : writer.UpsertFile(skippedRecord, out referenceIdentityChanged);
-                        if (referenceIdentityChanged)
-                            mutualRecursionRefreshNeeded = true;
-                        writer.InsertChunks([], requestToken);
-                        writer.InsertSymbols([], requestToken);
-                        writer.InsertReferencesInAtomicFileScope([], requestToken);
-                        InsertIssuesForIndexedFile(fileId,
-                        [
-                            new FileIssue
-                            {
-                                Path = ex.RelativePath,
-                                Kind = "file_too_large",
-                                Line = 0,
-                                Message = CommandErrorWriter.FormatSanitizedExceptionMessage(ex),
-                            }
-                        ]);
-                        WriteProjectRootOnce();
-                        txn.Commit();
-                        if (!string.IsNullOrWhiteSpace(skippedRecord.Lang))
-                            indexedSymbolExtractorLanguages.Add(skippedRecord.Lang);
-                        CountFreshInsertedRows();
-                        ftsMutated = true;
-                    }
-                }
-                catch (Exception cleanupEx) when (cleanupEx is not McpIndexAuthorizationException)
-                {
-                    errors++;
-                    failures.Add(BuildIndexFileFailure(projectPath, filePath, cleanupEx, "record_skipped_oversized_file"));
-                }
-            }
-            catch (Exception ex) when (ex is FileNotFoundException or DirectoryNotFoundException)
-            {
-                if (fileBatchMarked)
-                    writer.ClearBatchInProgress();
-
-                if (target.Language == "csharp" && csharpWorkspaceFileSnapshots != null)
-                {
-                    DeferCSharpMutationsForLoadedSnapshotDrift(target.DisplayRelativePath);
-                    skipped++;
-                    processed++;
-                    await EmitProgressNotificationAsync(progressToken, processed, files.Count).ConfigureAwait(false);
-                    continue;
-                }
-
-                try
-                {
-                    var relativePath = FileIndexer.NormalizePathSeparators(
-                        FileIndexer.GetRelativePathFromDirectory(projectPath, filePath));
-                    if (writer.HasFileAtPath(relativePath))
-                    {
-                        using var txn = writer.BeginTransaction(requestToken, "mcp index delete missing file");
-                        writer.DeleteFileByPath(relativePath);
-                        mutualRecursionRefreshNeeded = true;
-                        csharpMetadataTargetsNeedRefresh = true;
-                        RequireTypeScriptAugmentationRefresh();
-                        WriteProjectRootOnce();
-                        txn.Commit();
-                        ftsMutated = true;
-                    }
-                }
-                catch (Exception cleanupEx)
-                {
-                    errors++;
-                    failures.Add(BuildIndexFileFailure(projectPath, filePath, cleanupEx, "delete_missing_file"));
-                }
-            }
-            catch (OperationCanceledException) when (requestToken.IsCancellationRequested)
-            {
-                if (fileBatchMarked || useFullRunBatchMarker)
-                    writer.ClearBatchInProgress();
-                throw;
+                var info = new FileInfo(target.FilePath);
+                if (info.Exists && info.Length >= 0)
+                    RememberReadableFileSize(target.FilePath, info.Length);
             }
-            catch (Exception ex)
+            catch (Exception ex) when (ex is IOException or UnauthorizedAccessException
+                or NotSupportedException or ArgumentException)
             {
-                if (fileBatchMarked)
-                    writer.ClearBatchInProgress();
-                errors++;
-                failures.Add(BuildIndexFileFailure(projectPath, filePath, ex, "index_file"));
             }
-            processed++;
-            await EmitProgressNotificationAsync(progressToken, processed, files.Count).ConfigureAwait(false);
         }
 
+        var fileLoopContext = new McpIndexFileLoopContext
+        {
+            Writer = writer,
+            Indexer = indexer,
+            AuthorizedRoot = authorizedRoot,
+            Targets = fileTargets,
+            ProjectPath = projectPath,
+            TotalFileCount = files.Count,
+            ProgressToken = progressToken,
+            CancellationToken = requestToken,
+            MaxSymbolsPerFile = maxSymbolsPerFile,
+            MaxReferencesPerFile = maxReferencesPerFile,
+            Rebuild = rebuild,
+            StartedWithNoIndexedFiles = startedWithNoIndexedFiles,
+            UseFullRunBatchMarker = useFullRunBatchMarker,
+            ReuseFinalCSharpStatAtActualSkip = reuseFinalCSharpStatAtActualSkip,
+            SymbolKindFilterMatchesPrior = symbolKindFilterMatchesPrior,
+            CSharpIndexedProjectRootCompatible = csharpIndexedProjectRootCompatible,
+            CSharpSymbolNameContractMatchesCurrent = csharpSymbolNameContractMatchesCurrent,
+            SqlGraphContractMatchesCurrent = sqlGraphContractMatchesCurrent,
+            HdlGraphContractMatchesCurrent = hdlGraphContractMatchesCurrent,
+            HotspotFamilyTrustMatchesCurrent = hotspotFamilyTrustMatchesCurrent,
+            ReusableIndexedFileStats = reusableIndexedFileStats,
+            StatMatchedFiles = statMatchedFiles,
+            StatPreflightCompleted = statPreflightCompleted,
+            SymbolKindFilter = symbolKindFilter,
+            PostExtractionHooks = postExtractionHooks,
+            GetCSharpWorkspace = () => csharpWorkspace,
+            GetCSharpPrepassArtifacts = () => csharpPrepassSymbolArtifacts,
+            DeferCSharpMutations = () => deferCSharpMutationsForIncompleteScan,
+            PreservePriorPositiveCSharpSourceNoOp =
+                () => preservePriorPositiveCSharpSourceNoOp,
+            HasCSharpWorkspaceSnapshots = () => csharpWorkspaceFileSnapshots != null,
+            GetStatMatchedFile = GetStatMatchedFile,
+            LoadedCSharpWorkspaceSnapshotMatches = LoadedCSharpWorkspaceSnapshotMatches,
+            DeferCSharpStatRevalidation = DeferCSharpMutationsForStatRevalidation,
+            DeferCSharpLoadedSnapshotDrift = DeferCSharpMutationsForLoadedSnapshotDrift,
+            RememberReadableFileSize = RememberReadableFileSize,
+            InsertIssuesForIndexedFile = InsertIssuesForIndexedFile,
+            WriteProjectRootOnce = WriteProjectRootOnce,
+            MarkSymbolKindFilterMetaIncompleteOnce = MarkSymbolKindFilterMetaIncompleteOnce,
+            RequireTypeScriptAugmentationRefresh = RequireTypeScriptAugmentationRefresh,
+            Failures = failures,
+        };
+        var fileLoopSession = new McpIndexFileLoopSession
+        {
+            Processed = processed,
+            Skipped = skipped,
+            FtsMutated = ftsMutated,
+            MutualRecursionRefreshNeeded = mutualRecursionRefreshNeeded,
+            CSharpMetadataTargetsNeedRefresh = csharpMetadataTargetsNeedRefresh,
+            SymbolsDroppedByKindFilter = symbolsDroppedByKindFilter,
+            ReusedHotspotFamilyLanguages = reusedHotspotFamilyLanguages,
+            IndexedSymbolExtractorLanguages = indexedSymbolExtractorLanguages,
+            FreshCountFiles = freshCountFiles,
+            FreshCountChunks = freshCountChunks,
+            FreshCountSymbols = freshCountSymbols,
+            FreshCountReferences = freshCountReferences,
+        };
+        await RunMcpIndexFileLoopAsync(fileLoopContext, fileLoopSession)
+            .ConfigureAwait(false);
+        processed = fileLoopSession.Processed;
+        skipped = fileLoopSession.Skipped;
+        // Workspace-drift callbacks still own their outer validation state and append
+        // directly to the shared failure list. Per-file failures do the same through
+        // the session, so the list remains the authoritative error count at the join.
+        // workspace drift callback と file loop の双方が共有 failure list へ追記するため、
+        // join 時の error 数は同listから復元する。
+        errors = failures.Count;
+        ftsMutated = fileLoopSession.FtsMutated;
+        mutualRecursionRefreshNeeded = fileLoopSession.MutualRecursionRefreshNeeded;
+        csharpMetadataTargetsNeedRefresh = fileLoopSession.CSharpMetadataTargetsNeedRefresh;
+        symbolsDroppedByKindFilter = fileLoopSession.SymbolsDroppedByKindFilter;
+        reusedHotspotFamilyLanguages = fileLoopSession.ReusedHotspotFamilyLanguages;
+        freshCountFiles = fileLoopSession.FreshCountFiles;
+        freshCountChunks = fileLoopSession.FreshCountChunks;
+        freshCountSymbols = fileLoopSession.FreshCountSymbols;
+        freshCountReferences = fileLoopSession.FreshCountReferences;
+
         csharpPrepassSymbolArtifacts?.Clear();
         csharpPrepassSymbolArtifacts = null;
 
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.ExtractedFilePersistence.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.ExtractedFilePersistence.cs
new file mode 100644
index 000000000..936725a31
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.ExtractedFilePersistence.cs
@@ -0,0 +1,249 @@
+using CodeIndex.Cli;
+using CodeIndex.Database;
+using CodeIndex.Diagnostics;
+using CodeIndex.Indexer;
+using CodeIndex.Indexer.Extensibility;
+using CodeIndex.Indexer.Hooks;
+using CodeIndex.Models;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private static void PersistExtractedMcpIndexFile(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        in CSharpStaticInterfacePrepass.FileTarget target,
+        FileRecord record,
+        in LoadedFileRecord loaded,
+        long fileId,
+        IReadOnlyList<ChunkRecord> chunks,
+        DbWriter.TransactionScope txn)
+    {
+        var (symbols, symbolRegexTimeoutIssue) = ExtractMcpIndexSymbols(
+            context,
+            in target,
+            record,
+            in loaded,
+            fileId);
+        var familyScopeKey = context.Indexer.GetFamilyScopeKey(target.FilePath, record.Lang);
+        SymbolExtractor.ApplyFamilyScope(symbols, familyScopeKey, record.Lang);
+        var fileContext = new FileContext(
+            context.ProjectPath,
+            record.Path,
+            target.FilePath,
+            record.Lang);
+        context.PostExtractionHooks.Value.ObserveCSharpStaticInterfaceSourceSymbols(
+            fileContext,
+            symbols);
+        context.PostExtractionHooks.Value.OnSymbolsExtractedAfterSourceObservation(
+            fileContext,
+            symbols,
+            loaded.Content,
+            familyScopeKey);
+        session.SymbolsDroppedByKindFilter += context.SymbolKindFilter.Apply(symbols);
+
+        var committed = PersistMcpIndexSymbolsAndReferences(
+            context,
+            session,
+            record,
+            in loaded,
+            fileId,
+            chunks,
+            symbols,
+            symbolRegexTimeoutIssue,
+            fileContext);
+        CompleteMcpIndexFileTransaction(
+            context,
+            session,
+            record,
+            txn,
+            committed.Chunks,
+            committed.Symbols,
+            committed.References);
+    }
+
+    private static (List<SymbolRecord> Symbols, FileIssue? TimeoutIssue)
+        ExtractMcpIndexSymbols(
+            McpIndexFileLoopContext context,
+            in CSharpStaticInterfacePrepass.FileTarget target,
+            FileRecord record,
+            in LoadedFileRecord loaded,
+            long fileId)
+    {
+        if (record.Lang == "csharp"
+            && record.Checksum is { } checksum
+            && context.GetCSharpPrepassArtifacts()?.TryTake(
+                record.Path,
+                checksum,
+                out var artifact) == true)
+        {
+            foreach (var symbol in artifact.Symbols)
+                symbol.FileId = fileId;
+            return (artifact.Symbols, null);
+        }
+
+        using var regexTimeouts = BoundedRegex.CaptureTimeouts(
+            record.Lang,
+            "symbol_extraction");
+        var symbols = SymbolExtractor.ExtractNormalized(
+            fileId,
+            record.Lang,
+            loaded.Content,
+            loaded.HasOversizeLine,
+            target.FilePath,
+            context.ProjectPath,
+            context.CancellationToken,
+            loaded.ConflictMarkerLine,
+            patternConfigsAlreadyLoaded: true);
+        return (
+            symbols,
+            IndexCommandRunner.BuildRegexTimeoutIssue(record.Path, regexTimeouts));
+    }
+
+    private static McpIndexCommittedRows PersistMcpIndexSymbolsAndReferences(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        FileRecord record,
+        in LoadedFileRecord loaded,
+        long fileId,
+        IReadOnlyList<ChunkRecord> chunks,
+        List<SymbolRecord> symbols,
+        FileIssue? symbolRegexTimeoutIssue,
+        FileContext fileContext)
+    {
+        if (symbols.Count > context.MaxSymbolsPerFile)
+        {
+            PersistMcpSymbolCap(
+                context,
+                record,
+                fileId,
+                symbols.Count,
+                symbolRegexTimeoutIssue);
+            return default;
+        }
+
+        context.Writer.InsertChunks(chunks, context.CancellationToken);
+        context.Writer.InsertSymbols(symbols, context.CancellationToken);
+        var extracted = ExtractMcpIndexReferences(
+            context,
+            record,
+            in loaded,
+            fileId,
+            symbols,
+            fileContext);
+        var references = extracted.References;
+        FileIssue? referenceCapIssue = null;
+        if (references.Count > context.MaxReferencesPerFile)
+        {
+            referenceCapIssue = BuildMcpReferenceCountExceededIssue(
+                record.Path,
+                references.Count,
+                context.MaxReferencesPerFile);
+            references = [];
+        }
+        PersistMcpIndexReferences(context, references);
+        if (symbols.Count > 0 || references.Count > 0)
+            session.MutualRecursionRefreshNeeded = true;
+        PersistMcpIndexValidationIssues(
+            context,
+            record,
+            in loaded,
+            fileId,
+            symbolRegexTimeoutIssue,
+            extracted.TimeoutIssue,
+            extracted.Extraction.Diagnostics,
+            referenceCapIssue);
+        return new McpIndexCommittedRows(chunks.Count, symbols.Count, references.Count);
+    }
+
+    private static (List<ReferenceRecord> References,
+        ReferenceExtractionResult Extraction,
+        FileIssue? TimeoutIssue) ExtractMcpIndexReferences(
+        McpIndexFileLoopContext context,
+        FileRecord record,
+        in LoadedFileRecord loaded,
+        long fileId,
+        IReadOnlyList<SymbolRecord> symbols,
+        FileContext fileContext)
+    {
+        ReferenceExtractionResult extraction;
+        FileIssue? timeoutIssue;
+        using (var regexTimeouts = BoundedRegex.CaptureTimeouts(
+                   record.Lang,
+                   "reference_extraction"))
+        {
+            var workspace = context.GetCSharpWorkspace();
+            extraction = ReferenceExtractor.ExtractDetailedNormalized(
+                fileId,
+                record.Lang,
+                loaded.Content,
+                loaded.HasOversizeLine,
+                symbols,
+                record.Path,
+                record.Lang == "csharp" ? workspace.Symbols : null,
+                context.CancellationToken,
+                maxReferenceCount: context.MaxReferencesPerFile + 1,
+                conflictMarkerLine: loaded.ConflictMarkerLine,
+                workspaceRoot: context.ProjectPath,
+                csharpStaticInterfaceMemberLookups:
+                    workspace.StaticInterfaceMemberLookups,
+                csharpQualifiedPatternLookups: workspace.QualifiedPatternLookups);
+            timeoutIssue = IndexCommandRunner.BuildRegexTimeoutIssue(
+                record.Path,
+                regexTimeouts);
+        }
+        context.PostExtractionHooks.Value.OnReferencesExtracted(
+            fileContext,
+            extraction.References);
+        return (extraction.References, extraction, timeoutIssue);
+    }
+
+    private static void PersistMcpIndexReferences(
+        McpIndexFileLoopContext context,
+        IReadOnlyList<ReferenceRecord> references)
+    {
+        if (context.StartedWithNoIndexedFiles)
+        {
+            context.Writer.InsertReferencesForNewFilesInAtomicFileScope(
+                references,
+                refreshMutualRecursionFlags: false,
+                context.CancellationToken);
+            return;
+        }
+        context.Writer.InsertReferencesInAtomicFileScope(
+            references,
+            refreshMutualRecursionFlags: false,
+            context.CancellationToken);
+    }
+
+    private static void PersistMcpIndexValidationIssues(
+        McpIndexFileLoopContext context,
+        FileRecord record,
+        in LoadedFileRecord loaded,
+        long fileId,
+        FileIssue? symbolTimeoutIssue,
+        FileIssue? referenceTimeoutIssue,
+        IReadOnlyList<ReferenceExtractionDiagnostic> diagnostics,
+        FileIssue? referenceCapIssue)
+    {
+        IReadOnlyList<FileIssue> issues = FileIndexer.ValidateContent(
+            record.Path,
+            loaded.RawBytes,
+            loaded.Content,
+            record.Lang,
+            loaded.Inspection,
+            loaded.Facts);
+        if (symbolTimeoutIssue != null)
+            issues = IndexCommandRunner.AppendIssue(issues, symbolTimeoutIssue);
+        if (referenceTimeoutIssue != null)
+            issues = IndexCommandRunner.AppendIssue(issues, referenceTimeoutIssue);
+        issues = IndexCommandRunner.AppendReferenceExtractionDiagnosticIssues(
+            issues,
+            record.Path,
+            diagnostics);
+        if (referenceCapIssue != null)
+            issues = IndexCommandRunner.AppendIssue(issues, referenceCapIssue);
+        context.InsertIssuesForIndexedFile(fileId, issues);
+    }
+}
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FileLoop.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FileLoop.cs
new file mode 100644
index 000000000..c2f3b10f3
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FileLoop.cs
@@ -0,0 +1,201 @@
+using System.Text.Json.Nodes;
+using CodeIndex.Cli;
+using CodeIndex.Database;
+using CodeIndex.Indexer;
+using CodeIndex.Indexer.Hooks;
+using CodeIndex.Models;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private delegate IndexedFileStatReuseResult? McpIndexStatMatchResolver(
+        in CSharpStaticInterfacePrepass.FileTarget target);
+
+    private delegate bool McpIndexLoadedSnapshotMatcher(
+        in CSharpStaticInterfacePrepass.FileTarget target,
+        FileRecord record);
+
+    private delegate void McpIndexStatRevalidationHandler(
+        in CSharpStaticInterfacePrepass.FileTarget target);
+
+    private sealed class McpIndexFileLoopContext
+    {
+        internal required DbWriter Writer { get; init; }
+        internal required FileIndexer Indexer { get; init; }
+        internal required McpPathBoundary.IndexRootAuthorization AuthorizedRoot { get; init; }
+        internal required CSharpStaticInterfacePrepass.FileTarget[] Targets { get; init; }
+        internal required string ProjectPath { get; init; }
+        internal required int TotalFileCount { get; init; }
+        internal JsonNode? ProgressToken { get; init; }
+        internal required CancellationToken CancellationToken { get; init; }
+        internal required int MaxSymbolsPerFile { get; init; }
+        internal required int MaxReferencesPerFile { get; init; }
+        internal required bool Rebuild { get; init; }
+        internal required bool StartedWithNoIndexedFiles { get; init; }
+        internal required bool UseFullRunBatchMarker { get; init; }
+        internal required bool ReuseFinalCSharpStatAtActualSkip { get; init; }
+        internal required bool SymbolKindFilterMatchesPrior { get; init; }
+        internal required bool CSharpIndexedProjectRootCompatible { get; init; }
+        internal required bool CSharpSymbolNameContractMatchesCurrent { get; init; }
+        internal required bool SqlGraphContractMatchesCurrent { get; init; }
+        internal required bool HdlGraphContractMatchesCurrent { get; init; }
+        internal required IReadOnlyDictionary<string, bool> HotspotFamilyTrustMatchesCurrent { get; init; }
+        internal ReusableIndexedFileStatsSnapshot? ReusableIndexedFileStats { get; init; }
+        internal IndexedFileStatReuseResult?[]? StatMatchedFiles { get; init; }
+        internal bool[]? StatPreflightCompleted { get; init; }
+        internal required SymbolKindFilter SymbolKindFilter { get; init; }
+        internal required IndexCommandRunner.LazyDisposable<PostExtractionHookRunner> PostExtractionHooks { get; init; }
+        internal required Func<CSharpStaticInterfaceWorkspaceSymbols> GetCSharpWorkspace { get; init; }
+        internal required Func<CSharpPrepassSymbolArtifactCache?> GetCSharpPrepassArtifacts { get; init; }
+        internal required Func<bool> DeferCSharpMutations { get; init; }
+        internal required Func<bool> PreservePriorPositiveCSharpSourceNoOp { get; init; }
+        internal required Func<bool> HasCSharpWorkspaceSnapshots { get; init; }
+        internal required McpIndexStatMatchResolver GetStatMatchedFile { get; init; }
+        internal required McpIndexLoadedSnapshotMatcher LoadedCSharpWorkspaceSnapshotMatches { get; init; }
+        internal required McpIndexStatRevalidationHandler DeferCSharpStatRevalidation { get; init; }
+        internal required Action<string> DeferCSharpLoadedSnapshotDrift { get; init; }
+        internal required Action<string, long> RememberReadableFileSize { get; init; }
+        internal required Action<long, IReadOnlyList<FileIssue>> InsertIssuesForIndexedFile { get; init; }
+        internal required Action WriteProjectRootOnce { get; init; }
+        internal required Action MarkSymbolKindFilterMetaIncompleteOnce { get; init; }
+        internal required Action RequireTypeScriptAugmentationRefresh { get; init; }
+        internal required List<IndexFileFailure> Failures { get; init; }
+    }
+
+    private sealed class McpIndexFileLoopSession
+    {
+        internal int Processed { get; set; }
+        internal int Skipped { get; set; }
+        internal bool FileBatchMarked { get; set; }
+        internal bool FtsMutated { get; set; }
+        internal bool MutualRecursionRefreshNeeded { get; set; }
+        internal bool CSharpMetadataTargetsNeedRefresh { get; set; }
+        internal int SymbolsDroppedByKindFilter { get; set; }
+        internal HashSet<string>? ReusedHotspotFamilyLanguages { get; set; }
+        internal required HashSet<string> IndexedSymbolExtractorLanguages { get; init; }
+        internal long FreshCountFiles { get; set; }
+        internal long FreshCountChunks { get; set; }
+        internal long FreshCountSymbols { get; set; }
+        internal long FreshCountReferences { get; set; }
+    }
+
+    private async Task RunMcpIndexFileLoopAsync(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session)
+    {
+        for (var targetIndex = 0; targetIndex < context.Targets.Length; targetIndex++)
+        {
+            session.FileBatchMarked = false;
+            try
+            {
+                if (await ProcessMcpIndexFileAsync(context, session, targetIndex)
+                        .ConfigureAwait(false))
+                    continue;
+            }
+            catch (McpIndexAuthorizationException)
+            {
+                if (session.FileBatchMarked || context.UseFullRunBatchMarker)
+                    context.Writer.ClearBatchInProgress();
+                throw;
+            }
+            catch (FileIndexer.BinaryFileSkippedException ex)
+            {
+                HandleMcpSkippedFile(context, session, in context.Targets[targetIndex], ex);
+            }
+            catch (FileIndexer.FileTooLargeSkippedException ex)
+            {
+                HandleMcpSkippedFile(context, session, in context.Targets[targetIndex], ex);
+            }
+            catch (Exception ex) when (ex is FileNotFoundException or DirectoryNotFoundException)
+            {
+                if (await HandleMissingMcpIndexFileAsync(context, session, targetIndex)
+                        .ConfigureAwait(false))
+                    continue;
+            }
+            catch (OperationCanceledException) when (context.CancellationToken.IsCancellationRequested)
+            {
+                if (session.FileBatchMarked || context.UseFullRunBatchMarker)
+                    context.Writer.ClearBatchInProgress();
+                throw;
+            }
+            catch (Exception ex)
+            {
+                if (session.FileBatchMarked)
+                    context.Writer.ClearBatchInProgress();
+                context.Failures.Add(BuildIndexFileFailure(
+                    context.ProjectPath,
+                    context.Targets[targetIndex].FilePath,
+                    ex,
+                    "index_file"));
+            }
+
+            session.Processed++;
+            await EmitProgressNotificationAsync(
+                    context.ProgressToken,
+                    session.Processed,
+                    context.TotalFileCount)
+                .ConfigureAwait(false);
+        }
+    }
+
+    private async Task<bool> CompleteMcpIndexFileEarlyAsync(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        bool emitProgress)
+    {
+        session.Skipped++;
+        session.Processed++;
+        if (emitProgress)
+        {
+            await EmitProgressNotificationAsync(
+                    context.ProgressToken,
+                    session.Processed,
+                    context.TotalFileCount)
+                .ConfigureAwait(false);
+        }
+        return true;
+    }
+
+    private static void CountFreshMcpIndexRows(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        int chunkCount = 0,
+        int symbolCount = 0,
+        int referenceCount = 0)
+    {
+        if (!context.StartedWithNoIndexedFiles)
+            return;
+
+        session.FreshCountFiles++;
+        session.FreshCountChunks += chunkCount;
+        session.FreshCountSymbols += symbolCount;
+        session.FreshCountReferences += referenceCount;
+    }
+
+    private static void RememberReusedHotspotFamilyLanguage(
+        McpIndexFileLoopSession session,
+        string? language)
+    {
+        if (!FileIndexer.SupportsHotspotFamilyMarkerLanguage(language) || language == null)
+            return;
+        session.ReusedHotspotFamilyLanguages ??= new HashSet<string>(StringComparer.Ordinal);
+        session.ReusedHotspotFamilyLanguages.Add(language);
+    }
+
+    private static void TryRememberMcpIndexFileSize(
+        McpIndexFileLoopContext context,
+        string path)
+    {
+        try
+        {
+            var info = new FileInfo(path);
+            if (info.Exists && info.Length >= 0)
+                context.RememberReadableFileSize(path, info.Length);
+        }
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException
+            or NotSupportedException or ArgumentException)
+        {
+        }
+    }
+}
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FilePersistence.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FilePersistence.cs
new file mode 100644
index 000000000..c4640617c
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FilePersistence.cs
@@ -0,0 +1,247 @@
+using CodeIndex.Cli;
+using CodeIndex.Database;
+using CodeIndex.Diagnostics;
+using CodeIndex.Indexer;
+using CodeIndex.Indexer.Hooks;
+using CodeIndex.Models;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private readonly record struct McpIndexCommittedRows(
+        int Chunks,
+        int Symbols,
+        int References);
+
+    private async Task<bool> ProcessMcpIndexFileAsync(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        int targetIndex)
+    {
+        var target = context.Targets[targetIndex];
+        context.CancellationToken.ThrowIfCancellationRequested();
+        context.AuthorizedRoot.EnsureAuthorizedEntry(target.FilePath);
+        if (context.DeferCSharpMutations()
+            && target.Language == "csharp")
+        {
+            TryRememberMcpIndexFileSize(context, target.FilePath);
+            return await CompleteMcpIndexFileEarlyAsync(context, session, emitProgress: true)
+                .ConfigureAwait(false);
+        }
+
+        var statMatchedFile = ResolveMcpStatMatch(context, targetIndex, in target);
+        if (context.PreservePriorPositiveCSharpSourceNoOp()
+            && target.Language == "csharp"
+            && statMatchedFile == null)
+        {
+            context.DeferCSharpStatRevalidation(in target);
+            return await CompleteMcpIndexFileEarlyAsync(context, session, emitProgress: true)
+                .ConfigureAwait(false);
+        }
+        if (statMatchedFile != null)
+        {
+            context.RememberReadableFileSize(target.FilePath, statMatchedFile.Value.Size);
+            RememberReusedHotspotFamilyLanguage(session, target.Language);
+            return await CompleteMcpIndexFileEarlyAsync(context, session, emitProgress: true)
+                .ConfigureAwait(false);
+        }
+
+        McpIndexFileContentLoadForTesting?.Invoke(target.IndexPath);
+        var loaded = context.Indexer.BuildLoadedRecordWithRawBytes(
+            target.FilePath,
+            target.RelativePath,
+            target.Language,
+            context.CancellationToken);
+        var record = loaded.Record;
+        if (!context.LoadedCSharpWorkspaceSnapshotMatches(in target, record))
+        {
+            context.RememberReadableFileSize(target.FilePath, record.Size);
+            return await CompleteMcpIndexFileEarlyAsync(context, session, emitProgress: true)
+                .ConfigureAwait(false);
+        }
+        context.RememberReadableFileSize(target.FilePath, record.Size);
+
+        var generatedSuppressionIssue = target.GeneratedExtractionSuppressed == true
+            ? context.Indexer.BuildGeneratedCodeExtractionSkippedIssue(record.Path)
+            : null;
+        if (CanReuseLoadedMcpIndexFile(context, record, generatedSuppressionIssue != null))
+        {
+            RememberReusedHotspotFamilyLanguage(session, record.Lang);
+            return await CompleteMcpIndexFileEarlyAsync(context, session, emitProgress: false)
+                .ConfigureAwait(false);
+        }
+
+        if (!context.UseFullRunBatchMarker)
+        {
+            context.Writer.MarkBatchInProgress();
+            session.FileBatchMarked = true;
+        }
+        context.MarkSymbolKindFilterMetaIncompleteOnce();
+        if (record.Lang == "csharp")
+            session.CSharpMetadataTargetsNeedRefresh = true;
+        using var txn = context.Writer.BeginTransaction(
+            context.CancellationToken,
+            "mcp index file");
+        if (record.Lang == "typescript")
+            context.RequireTypeScriptAugmentationRefresh();
+        var referenceIdentityChanged = false;
+        var fileId = context.StartedWithNoIndexedFiles
+            ? context.Writer.InsertNewFile(record)
+            : context.Writer.UpsertFile(record, out referenceIdentityChanged);
+        if (referenceIdentityChanged)
+            session.MutualRecursionRefreshNeeded = true;
+        var chunks = ChunkSplitter.SplitNormalized(fileId, loaded.Content, loaded.Facts);
+
+        if (generatedSuppressionIssue != null)
+        {
+            PersistGeneratedMcpIndexFile(
+                context,
+                session,
+                record,
+                in loaded,
+                fileId,
+                chunks,
+                generatedSuppressionIssue,
+                txn);
+            session.Processed++;
+            await EmitProgressNotificationAsync(
+                    context.ProgressToken,
+                    session.Processed,
+                    context.TotalFileCount)
+                .ConfigureAwait(false);
+            McpIndexFileCommittedForTesting?.Invoke(record.Path);
+            return true;
+        }
+
+        PersistExtractedMcpIndexFile(
+            context,
+            session,
+            in target,
+            record,
+            in loaded,
+            fileId,
+            chunks,
+            txn);
+        McpIndexFileCommittedForTesting?.Invoke(record.Path);
+        return false;
+    }
+
+    private static IndexedFileStatReuseResult? ResolveMcpStatMatch(
+        McpIndexFileLoopContext context,
+        int targetIndex,
+        in CSharpStaticInterfacePrepass.FileTarget target)
+    {
+        if (context.StatPreflightCompleted == null)
+            return null;
+        if (!context.StatPreflightCompleted[targetIndex])
+            return context.GetStatMatchedFile(in target);
+
+        var cached = context.StatMatchedFiles![targetIndex];
+        if (cached == null)
+            return null;
+        return context.ReuseFinalCSharpStatAtActualSkip && target.Language == "csharp"
+            ? cached
+            : IndexedFileStatReuse.TryGetReusableUnchangedFile(
+                context.ReusableIndexedFileStats!,
+                target.FilePath,
+                target.IndexPath,
+                target.Language,
+                target.GeneratedExtractionSuppressed == true);
+    }
+
+    private static bool CanReuseLoadedMcpIndexFile(
+        McpIndexFileLoopContext context,
+        FileRecord record,
+        bool generatedExtractionSuppressed)
+    {
+        return context.Writer.GetReusableUnchangedFileId(
+            record.Path,
+            record.Modified,
+            record.Checksum,
+            size: record.Size,
+            lines: record.Lines,
+            language: record.Lang,
+            generated: record.Generated,
+            maxSymbolsPerFile: context.MaxSymbolsPerFile,
+            maxReferencesPerFile: context.MaxReferencesPerFile,
+            generatedExtractionSuppressed: generatedExtractionSuppressed,
+            allowReuse: !context.Rebuild
+                && !context.StartedWithNoIndexedFiles
+                && context.SymbolKindFilterMatchesPrior
+                && (record.Lang != "csharp" || context.CSharpIndexedProjectRootCompatible)
+                && (record.Lang != "csharp" || context.CSharpSymbolNameContractMatchesCurrent)
+                && (record.Lang != "csharp" || !context.GetCSharpWorkspace().HasStaticInterfaceContracts)
+                && (record.Lang != "sql" || context.SqlGraphContractMatchesCurrent)
+                && (record.Lang is not ("verilog" or "systemverilog" or "vhdl")
+                    || context.HdlGraphContractMatchesCurrent)
+                && AllowReuseWithCurrentHotspotFamilyTrust(
+                    record.Lang,
+                    context.HotspotFamilyTrustMatchesCurrent)) != null;
+    }
+
+    private static void PersistMcpSymbolCap(
+        McpIndexFileLoopContext context,
+        FileRecord record,
+        long fileId,
+        int symbolCount,
+        FileIssue? symbolRegexTimeoutIssue)
+    {
+        var issue = BuildMcpSymbolCountExceededIssue(
+            record.Path,
+            symbolCount,
+            context.MaxSymbolsPerFile);
+        IReadOnlyList<FileIssue> issues = symbolRegexTimeoutIssue == null
+            ? [issue]
+            : IndexCommandRunner.AppendIssue([symbolRegexTimeoutIssue], issue);
+        context.Writer.InsertSymbols([], context.CancellationToken);
+        context.Writer.InsertReferencesInAtomicFileScope([], context.CancellationToken);
+        context.InsertIssuesForIndexedFile(fileId, issues);
+    }
+
+    private static void PersistGeneratedMcpIndexFile(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        FileRecord record,
+        in LoadedFileRecord loaded,
+        long fileId,
+        IReadOnlyList<ChunkRecord> chunks,
+        FileIssue generatedSuppressionIssue,
+        DbWriter.TransactionScope txn)
+    {
+        context.Writer.InsertChunks(chunks, context.CancellationToken);
+        context.Writer.InsertSymbols([], context.CancellationToken);
+        context.Writer.InsertReferencesInAtomicFileScope([], context.CancellationToken);
+        var issues = IndexCommandRunner.AppendIssueIfMissing(
+            FileIndexer.ValidateContent(
+                record.Path,
+                loaded.RawBytes,
+                loaded.Content,
+                record.Lang,
+                loaded.Inspection,
+                loaded.Facts),
+            generatedSuppressionIssue);
+        context.InsertIssuesForIndexedFile(fileId, issues);
+        CompleteMcpIndexFileTransaction(context, session, record, txn, chunks.Count, 0, 0);
+    }
+
+    private static void CompleteMcpIndexFileTransaction(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        FileRecord record,
+        DbWriter.TransactionScope txn,
+        int chunks,
+        int symbols,
+        int references)
+    {
+        context.WriteProjectRootOnce();
+        if (!context.UseFullRunBatchMarker)
+            context.Writer.ClearBatchInProgress();
+        txn.Commit();
+        if (!string.IsNullOrWhiteSpace(record.Lang))
+            session.IndexedSymbolExtractorLanguages.Add(record.Lang);
+        CountFreshMcpIndexRows(context, session, chunks, symbols, references);
+        session.FtsMutated = true;
+    }
+
+}
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.SkippedFiles.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.SkippedFiles.cs
new file mode 100644
index 000000000..997db8c4b
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.SkippedFiles.cs
@@ -0,0 +1,190 @@
+using CodeIndex.Cli;
+using CodeIndex.Indexer;
+using CodeIndex.Models;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private enum McpSkippedFileKind
+    {
+        Binary,
+        Oversized,
+    }
+
+    private void HandleMcpSkippedFile(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        in CSharpStaticInterfacePrepass.FileTarget target,
+        FileIndexer.BinaryFileSkippedException exception)
+    {
+        PersistMcpSkippedFile(
+            context,
+            session,
+            in target,
+            McpSkippedFileKind.Binary,
+            exception);
+    }
+
+    private void HandleMcpSkippedFile(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        in CSharpStaticInterfacePrepass.FileTarget target,
+        FileIndexer.FileTooLargeSkippedException exception)
+    {
+        PersistMcpSkippedFile(
+            context,
+            session,
+            in target,
+            McpSkippedFileKind.Oversized,
+            exception);
+    }
+
+    private void PersistMcpSkippedFile(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        in CSharpStaticInterfacePrepass.FileTarget target,
+        McpSkippedFileKind kind,
+        Exception exception)
+    {
+        try
+        {
+            var record = context.Indexer.BuildSkippedFileRecord(
+                target.FilePath,
+                target.RelativePath,
+                target.Language);
+            context.RememberReadableFileSize(target.FilePath, record.Size);
+            if (!context.LoadedCSharpWorkspaceSnapshotMatches(in target, record))
+            {
+                session.Skipped++;
+                return;
+            }
+            if (record.Lang == "csharp")
+                session.CSharpMetadataTargetsNeedRefresh = true;
+            using var txn = context.Writer.BeginTransaction(
+                context.CancellationToken,
+                GetMcpSkippedFileTransactionOperation(kind));
+            if (record.Lang == "typescript")
+                context.RequireTypeScriptAugmentationRefresh();
+            var referenceIdentityChanged = false;
+            var fileId = context.StartedWithNoIndexedFiles
+                ? context.Writer.InsertNewFile(record)
+                : context.Writer.UpsertFile(record, out referenceIdentityChanged);
+            if (referenceIdentityChanged)
+                session.MutualRecursionRefreshNeeded = true;
+            context.Writer.InsertChunks([], context.CancellationToken);
+            context.Writer.InsertSymbols([], context.CancellationToken);
+            context.Writer.InsertReferencesInAtomicFileScope([], context.CancellationToken);
+            context.InsertIssuesForIndexedFile(
+                fileId,
+                BuildMcpSkippedFileIssues(kind, exception));
+            context.WriteProjectRootOnce();
+            txn.Commit();
+            if (!string.IsNullOrWhiteSpace(record.Lang))
+                session.IndexedSymbolExtractorLanguages.Add(record.Lang);
+            CountFreshMcpIndexRows(context, session);
+            session.FtsMutated = true;
+        }
+        catch (Exception cleanupException) when (
+            cleanupException is not McpIndexAuthorizationException)
+        {
+            context.Failures.Add(BuildIndexFileFailure(
+                context.ProjectPath,
+                target.FilePath,
+                cleanupException,
+                GetMcpSkippedFileFailureStage(kind)));
+        }
+    }
+
+    private static IReadOnlyList<FileIssue> BuildMcpSkippedFileIssues(
+        McpSkippedFileKind kind,
+        Exception exception)
+    {
+        return kind switch
+        {
+            McpSkippedFileKind.Binary =>
+                [IndexCommandRunner.BuildNullByteIssue(
+                    (FileIndexer.BinaryFileSkippedException)exception)],
+            McpSkippedFileKind.Oversized =>
+            [
+                new FileIssue
+                {
+                    Path = ((FileIndexer.FileTooLargeSkippedException)exception).RelativePath,
+                    Kind = "file_too_large",
+                    Line = 0,
+                    Message = CommandErrorWriter.FormatSanitizedExceptionMessage(exception),
+                }
+            ],
+            _ => throw new ArgumentOutOfRangeException(nameof(kind)),
+        };
+    }
+
+    private static string GetMcpSkippedFileTransactionOperation(McpSkippedFileKind kind)
+        => kind switch
+        {
+            McpSkippedFileKind.Binary => "mcp index skipped binary",
+            McpSkippedFileKind.Oversized => "mcp index skipped oversized file",
+            _ => throw new ArgumentOutOfRangeException(nameof(kind)),
+        };
+
+    private static string GetMcpSkippedFileFailureStage(McpSkippedFileKind kind)
+        => kind switch
+        {
+            McpSkippedFileKind.Binary => "record_skipped_binary",
+            McpSkippedFileKind.Oversized => "record_skipped_oversized_file",
+            _ => throw new ArgumentOutOfRangeException(nameof(kind)),
+        };
+
+    private async Task<bool> HandleMissingMcpIndexFileAsync(
+        McpIndexFileLoopContext context,
+        McpIndexFileLoopSession session,
+        int targetIndex)
+    {
+        var target = context.Targets[targetIndex];
+        if (session.FileBatchMarked)
+            context.Writer.ClearBatchInProgress();
+
+        if (target.Language == "csharp" && context.HasCSharpWorkspaceSnapshots())
+        {
+            context.DeferCSharpLoadedSnapshotDrift(target.DisplayRelativePath);
+            session.Skipped++;
+            session.Processed++;
+            await EmitProgressNotificationAsync(
+                    context.ProgressToken,
+                    session.Processed,
+                    context.TotalFileCount)
+                .ConfigureAwait(false);
+            return true;
+        }
+
+        try
+        {
+            var relativePath = FileIndexer.NormalizePathSeparators(
+                FileIndexer.GetRelativePathFromDirectory(
+                    context.ProjectPath,
+                    target.FilePath));
+            if (context.Writer.HasFileAtPath(relativePath))
+            {
+                using var txn = context.Writer.BeginTransaction(
+                    context.CancellationToken,
+                    "mcp index delete missing file");
+                context.Writer.DeleteFileByPath(relativePath);
+                session.MutualRecursionRefreshNeeded = true;
+                session.CSharpMetadataTargetsNeedRefresh = true;
+                context.RequireTypeScriptAugmentationRefresh();
+                context.WriteProjectRootOnce();
+                txn.Commit();
+                session.FtsMutated = true;
+            }
+        }
+        catch (Exception cleanupException)
+        {
+            context.Failures.Add(BuildIndexFileFailure(
+                context.ProjectPath,
+                target.FilePath,
+                cleanupException,
+                "delete_missing_file"));
+        }
+        return false;
+    }
+}

From 12c489cce63baa2fe433ede97c79a572ef7755cf Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 14:03:38 +0900
Subject: [PATCH 18/45] Decompose Python and R reference phases

---
 TESTING_GUIDE.md                              |   4 +-
 ...ferenceExtractor.CoreDocumentationLines.cs |   2 +-
 .../ReferenceExtractor.CoreLanguageLines.cs   | 454 +-----------------
 .../ReferenceExtractor.CorePythonLines.cs     | 228 +++++++++
 .../ReferenceExtractor.CoreRLines.cs          |  83 ++++
 .../ReferenceExtractor.CoreReferenceLine.cs   |   6 +-
 .../ReferenceExtractor.CoreReferenceLoop.cs   |  25 +-
 .../ReferenceExtractor.CoreReferencePhases.cs |  36 +-
 ...ReferenceExtractor.CoreSpecializedLines.cs |  12 +-
 .../ReferenceExtractorPythonTests.cs          |  27 ++
 10 files changed, 394 insertions(+), 483 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CorePythonLines.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreRLines.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 0c8d15c95..97604efc3 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -542,7 +542,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
 - C# constructor base-target coverage shares generic, interface-list, nested-generic, multiline, and constrained layouts in one fixture and asserts each rewritten edge by its unique terminal type.
 - C# multiline member attribution shares expression-bodied method and property layouts, Allman/same-line braces, and intervening block comments in one fixture, using unique member containers for assertions.
 - Python `isinstance`/`issubclass` runtime type checks share single-type and tuple forms in one module fixture, with function containers retaining case-level assertions.
-- Python class-header type references share single-base, multiple-base, and metaclass forms in one module fixture, distinguished by class container.
+- Python class-header type references share single-base, multiple-base, and metaclass forms in one module fixture, distinguished by class container; a dedicated capped-output fixture also locks multiline class-header remapping after the reference limit is reached.
 - Python annotation coverage shares direct and generic return, parameter, and local-variable forms in one module fixture, with function containers preserving each assertion.
 - Python semantic-type symbol coverage shares PEP 695 aliases, `TypeAlias`, `NewType`, `TypeVar`, `ParamSpec`, `TypeVarTuple`, and real imports in one module fixture, asserting dedicated kinds and import-filter exclusion; typing-factory reference coverage keeps unique target types in its shared module fixture.
 - Python advanced-typing coverage shares multiline/commented `TypeVar`, `ParamSpec`, callable annotations, variadic tuple unpacking, and literal unions in one logical-header fixture with unique type names.
@@ -1598,7 +1598,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
 - C# constructor の base-target coverage は generic、interface list、nested generic、multiline、constraint 付き layout を1つの fixture で共有し、一意な末尾型ごとに書き換え後の edge を検証します。
 - C# multiline member 帰属テストは expression-bodied method/property、Allman/same-line brace、途中の block comment を1つの fixture で共有し、一意な member container ごとに検証します。
 - Python の `isinstance`/`issubclass` runtime type check は単一型と tuple 形式を1つの module fixture で共有し、function container ごとの検証を維持します。
-- Python class header の type reference は単一 base、複数 base、metaclass 形式を1つの module fixture で共有し、class container で区別します。
+- Python class header の type reference は単一 base、複数 base、metaclass 形式を1つの module fixture で共有して class container で区別し、専用の capped-output fixture で reference limit 到達後の multiline class-header remap も固定します。
 - Python annotation coverage は direct/generic の return、parameter、local variable 形式を1つの module fixture で共有し、function container ごとの検証を維持します。
 - Python semantic-type symbol coverage は PEP 695 alias、`TypeAlias`、`NewType`、`TypeVar`、`ParamSpec`、`TypeVarTuple`、実際の import を1つの module fixture で共有し、専用 kind と import filter からの除外を検証します。typing factory の reference coverage は一意な target type を持つ共有 module fixture を維持します。
 - Python advanced typing coverage は multiline/comment 付き `TypeVar`、`ParamSpec`、callable annotation、variadic tuple unpack、literal union を一意な型名を持つ1つの logical-header fixture で共有します。
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreDocumentationLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreDocumentationLines.cs
index 8df7c39ba..a3c7dd1c8 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreDocumentationLines.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreDocumentationLines.cs
@@ -26,7 +26,7 @@ private readonly record struct CoreDocumentationLineContext(
         Func<SymbolRecord?>? GetPhpLineContainer);
 
     private static void EmitCoreDocumentationReferences(
-        CoreDocumentationLineContext line,
+        in CoreDocumentationLineContext line,
         ref bool csharpInDelimitedDocComment,
         ref bool jvmInDelimitedDocComment,
         ref bool phpInDocblock,
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreLanguageLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreLanguageLines.cs
index 7f178eb88..0948d4ec3 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreLanguageLines.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreLanguageLines.cs
@@ -23,7 +23,7 @@ private readonly record struct CoreReferenceLineContext(
         Func<string, bool> IsIgnoredCallName);
 
     private static void EmitJavaScriptTaggedTemplateReferences(
-        CoreReferenceLineContext line,
+        in CoreReferenceLineContext line,
         IReadOnlyList<JsTaggedTemplateHit> tagHitsOnLine)
     {
         foreach (var hit in tagHitsOnLine)
@@ -59,7 +59,7 @@ private static void EmitJavaScriptTaggedTemplateReferences(
     }
 
     private static void EmitMetadataLineReferences(
-        CoreReferenceLineContext line,
+        in CoreReferenceLineContext line,
         List<(int start, int end)>? csharpAttrTopLevelOnLine)
     {
         if (line.Language == "csharp" && csharpAttrTopLevelOnLine != null && csharpAttrTopLevelOnLine.Count > 0)
@@ -153,454 +153,4 @@ private static void EmitMetadataLineReferences(
             }
         }
     }
-
-    private static Func<int, SymbolRecord?> CreatePythonDefinitionContainerResolver(
-        CoreReferenceLineContext line,
-        CoreExtractionLookups lookups,
-        SymbolRecord? headerContainer,
-        string definitionKind) =>
-        column =>
-        {
-            if (headerContainer != null)
-                return headerContainer;
-
-            var container = line.ResolveContainerForCall(column);
-            if (container != null)
-                return container;
-
-            var definitionContainers =
-                lookups.GetPythonDefinitionContainersByLineAndKind();
-            if (definitionContainers == null)
-                return null;
-            return definitionContainers.TryGetValue(
-                (line.LineNumber, definitionKind),
-                out var symbol)
-                ? symbol
-                : null;
-        };
-
-    private static void EmitPythonLineReferences(
-        CoreReferenceLineContext line,
-        CoreExtractionLookups lookups)
-    {
-
-        var pythonPreparedLine = line.PreparedLine;
-        var pythonHeaderMap = default(PythonLogicalHeaderReferenceLine?);
-        SymbolRecord? pythonHeaderSymbol = null;
-        lookups.GetPythonHeaderSymbolsByLine()?.TryGetValue(line.LineNumber, out pythonHeaderSymbol);
-        if (pythonHeaderSymbol?.Signature != null
-            && TryBuildPythonLogicalHeaderReferenceLine(line.Lines, line.LineIndex, pythonHeaderSymbol.StartColumn ?? 0, out var builtPythonHeaderMap))
-        {
-            pythonPreparedLine = builtPythonHeaderMap.Text;
-            pythonHeaderMap = builtPythonHeaderMap;
-        }
-        var pythonTypeFactoryLine = line.PreparedLine;
-        var pythonTypeFactoryMap = default(PythonLogicalHeaderReferenceLine?);
-        if (line.PreparedLine.Contains("TypeVar", StringComparison.Ordinal)
-            || line.PreparedLine.Contains("ParamSpec", StringComparison.Ordinal))
-        {
-            var typeFactoryStartColumn = line.OriginalLine.IndexOfAny(['T', 'P']);
-            if (typeFactoryStartColumn < 0)
-                typeFactoryStartColumn = 0;
-            if (TryBuildPythonLogicalStatementReferenceLine(line.Lines, line.LineIndex, typeFactoryStartColumn, out var builtPythonTypeFactoryMap))
-            {
-                pythonTypeFactoryLine = builtPythonTypeFactoryMap.Text;
-                pythonTypeFactoryMap = builtPythonTypeFactoryMap;
-            }
-        }
-        var pythonHeaderContainer = pythonHeaderSymbol ?? line.Container;
-        var resolvePythonClassContainer =
-            pythonPreparedLine.IndexOf("class", StringComparison.Ordinal) >= 0
-                ? CreatePythonDefinitionContainerResolver(
-                    line,
-                    lookups,
-                    pythonHeaderContainer,
-                    "class")
-                : line.ResolveContainerForCall;
-        var resolvePythonFunctionContainer =
-            pythonPreparedLine.IndexOf("def", StringComparison.Ordinal) >= 0
-                ? CreatePythonDefinitionContainerResolver(
-                    line,
-                    lookups,
-                    pythonHeaderContainer,
-                    "function")
-                : line.ResolveContainerForCall;
-
-        var pythonReferenceStart = line.References.Count;
-        PythonReferenceExtractor.EmitDecoratorReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.DefinitionNames,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitRaiseReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitExceptReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitIsInstanceReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitIsSubclassReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitCastReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitAssertTypeReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitClassBaseReferences(
-            pythonPreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            pythonHeaderContainer,
-            resolvePythonClassContainer,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitFunctionReturnReferences(
-            pythonPreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            pythonHeaderContainer,
-            resolvePythonFunctionContainer,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitFunctionParameterReferences(
-            pythonPreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            pythonHeaderContainer,
-            resolvePythonFunctionContainer,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitVariableAnnotationReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitTypeAliasReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitNewTypeReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        var pythonTypeFactoryReferenceStart = line.References.Count;
-        PythonReferenceExtractor.EmitTypeVarBoundReferences(
-            pythonTypeFactoryLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitTypeVarConstraintReferences(
-            pythonTypeFactoryLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitGetTypeHintsReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitDataclassesFieldsReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitDataclassFieldReferences(
-            line.PreparedLines,
-            line.Lines,
-            line.LineIndex,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitAttrsFieldsReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitPydanticTypeAdapterReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitPytestRaisesReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-        PythonReferenceExtractor.EmitContextlibSuppressReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.IsIgnoredCallName);
-
-        if (pythonTypeFactoryMap.HasValue)
-            RemapPythonLogicalHeaderReferences(line.References, pythonTypeFactoryReferenceStart, pythonTypeFactoryMap.Value, line.Lines);
-        PythonReferenceExtractor.EmitDynamicImportReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        if (pythonHeaderMap.HasValue)
-            RemapPythonLogicalHeaderReferences(line.References, pythonReferenceStart, pythonHeaderMap.Value, line.Lines);
-    }
-
-    private static void EmitRLineReferences(CoreReferenceLineContext line)
-    {
-
-        RReferenceExtractor.EmitNamespaceReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.DefinitionNames);
-        RReferenceExtractor.EmitNamespaceDirectiveReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitS4DispatchReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitBacktickCallReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.DefinitionNames);
-        RReferenceExtractor.EmitInfixOperatorCallReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.DefinitionNames);
-        RReferenceExtractor.EmitSourceFileReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitLoadAllReferences(
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitDataCallReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitSystemFileReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitVignetteReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitHelpExampleReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitInstallPackagesReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitNamespacePackageInstallReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitGitHubPackageInstallReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container);
-        RReferenceExtractor.EmitDollarMemberReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.DefinitionNames);
-        RReferenceExtractor.EmitBracketMemberReferences(
-            line.PreparedLine,
-            line.OriginalLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.DefinitionNames);
-        RReferenceExtractor.EmitSlotMemberReferences(
-            line.PreparedLine,
-            line.References,
-            line.Seen,
-            line.FileId,
-            line.Context,
-            line.LineNumber,
-            line.Container,
-            line.DefinitionNames);
-    }
 }
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CorePythonLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CorePythonLines.cs
new file mode 100644
index 000000000..0d929277a
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CorePythonLines.cs
@@ -0,0 +1,228 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private readonly record struct CorePythonReferenceLinePreparation(
+        string HeaderLine,
+        PythonLogicalHeaderReferenceLine? HeaderMap,
+        SymbolRecord? HeaderContainer,
+        Func<int, SymbolRecord?> ResolveClassContainer,
+        Func<int, SymbolRecord?> ResolveFunctionContainer,
+        string TypeFactoryLine,
+        PythonLogicalHeaderReferenceLine? TypeFactoryMap);
+
+    private static Func<int, SymbolRecord?> CreatePythonDefinitionContainerResolver(
+        in CoreReferenceLineContext line,
+        CoreExtractionLookups lookups,
+        SymbolRecord? headerContainer,
+        string definitionKind)
+    {
+        var resolveContainerForCall = line.ResolveContainerForCall;
+        var lineNumber = line.LineNumber;
+        return column =>
+        {
+            if (headerContainer != null)
+                return headerContainer;
+
+            var container = resolveContainerForCall(column);
+            if (container != null)
+                return container;
+
+            var definitionContainers =
+                lookups.GetPythonDefinitionContainersByLineAndKind();
+            if (definitionContainers == null)
+                return null;
+            return definitionContainers.TryGetValue(
+                (lineNumber, definitionKind),
+                out var symbol)
+                ? symbol
+                : null;
+        };
+    }
+
+    private static CorePythonReferenceLinePreparation PrepareCorePythonReferenceLine(
+        in CoreReferenceLineContext line,
+        CoreExtractionLookups lookups)
+    {
+        var headerLine = line.PreparedLine;
+        var headerMap = default(PythonLogicalHeaderReferenceLine?);
+        SymbolRecord? headerSymbol = null;
+        lookups.GetPythonHeaderSymbolsByLine()?.TryGetValue(line.LineNumber, out headerSymbol);
+        if (headerSymbol?.Signature != null
+            && TryBuildPythonLogicalHeaderReferenceLine(
+                line.Lines,
+                line.LineIndex,
+                headerSymbol.StartColumn ?? 0,
+                out var builtHeaderMap))
+        {
+            headerLine = builtHeaderMap.Text;
+            headerMap = builtHeaderMap;
+        }
+
+        var typeFactoryLine = line.PreparedLine;
+        var typeFactoryMap = default(PythonLogicalHeaderReferenceLine?);
+        if (line.PreparedLine.Contains("TypeVar", StringComparison.Ordinal)
+            || line.PreparedLine.Contains("ParamSpec", StringComparison.Ordinal))
+        {
+            var startColumn = line.OriginalLine.IndexOfAny(['T', 'P']);
+            if (startColumn < 0)
+                startColumn = 0;
+            if (TryBuildPythonLogicalStatementReferenceLine(
+                    line.Lines,
+                    line.LineIndex,
+                    startColumn,
+                    out var builtTypeFactoryMap))
+            {
+                typeFactoryLine = builtTypeFactoryMap.Text;
+                typeFactoryMap = builtTypeFactoryMap;
+            }
+        }
+
+        var headerContainer = headerSymbol ?? line.Container;
+        var resolveClassContainer = headerLine.IndexOf("class", StringComparison.Ordinal) >= 0
+            ? CreatePythonDefinitionContainerResolver(
+                in line,
+                lookups,
+                headerContainer,
+                "class")
+            : line.ResolveContainerForCall;
+        var resolveFunctionContainer = headerLine.IndexOf("def", StringComparison.Ordinal) >= 0
+            ? CreatePythonDefinitionContainerResolver(
+                in line,
+                lookups,
+                headerContainer,
+                "function")
+            : line.ResolveContainerForCall;
+        return new CorePythonReferenceLinePreparation(
+            headerLine,
+            headerMap,
+            headerContainer,
+            resolveClassContainer,
+            resolveFunctionContainer,
+            typeFactoryLine,
+            typeFactoryMap);
+    }
+
+    private static void EmitPythonLineReferences(
+        in CoreReferenceLineContext line,
+        CoreExtractionLookups lookups)
+    {
+        var preparation = PrepareCorePythonReferenceLine(in line, lookups);
+        var referenceStart = line.References.Count;
+        EmitPythonRuntimeTypeReferences(in line);
+        EmitPythonDeclarationTypeReferences(in line, in preparation);
+
+        var typeFactoryReferenceStart = line.References.Count;
+        EmitPythonTypingAndFrameworkReferences(
+            in line,
+            preparation.TypeFactoryLine);
+        if (preparation.TypeFactoryMap.HasValue)
+        {
+            RemapPythonLogicalHeaderReferences(
+                line.References,
+                typeFactoryReferenceStart,
+                preparation.TypeFactoryMap.Value,
+                line.Lines);
+        }
+
+        PythonReferenceExtractor.EmitDynamicImportReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+        if (preparation.HeaderMap.HasValue)
+        {
+            RemapPythonLogicalHeaderReferences(
+                line.References,
+                referenceStart,
+                preparation.HeaderMap.Value,
+                line.Lines);
+        }
+    }
+
+    private static void EmitPythonRuntimeTypeReferences(
+        in CoreReferenceLineContext line)
+    {
+        PythonReferenceExtractor.EmitDecoratorReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.DefinitionNames, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitRaiseReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitExceptReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitIsInstanceReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitIsSubclassReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitCastReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitAssertTypeReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+    }
+
+    private static void EmitPythonDeclarationTypeReferences(
+        in CoreReferenceLineContext line,
+        in CorePythonReferenceLinePreparation preparation)
+    {
+        PythonReferenceExtractor.EmitClassBaseReferences(
+            preparation.HeaderLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, preparation.HeaderContainer, preparation.ResolveClassContainer,
+            line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitFunctionReturnReferences(
+            preparation.HeaderLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, preparation.HeaderContainer, preparation.ResolveFunctionContainer,
+            line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitFunctionParameterReferences(
+            preparation.HeaderLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, preparation.HeaderContainer, preparation.ResolveFunctionContainer,
+            line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitVariableAnnotationReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitTypeAliasReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitNewTypeReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+    }
+
+    private static void EmitPythonTypingAndFrameworkReferences(
+        in CoreReferenceLineContext line,
+        string typeFactoryLine)
+    {
+        PythonReferenceExtractor.EmitTypeVarBoundReferences(
+            typeFactoryLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitTypeVarConstraintReferences(
+            typeFactoryLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitGetTypeHintsReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitDataclassesFieldsReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitDataclassFieldReferences(
+            line.PreparedLines, line.Lines, line.LineIndex, line.References, line.Seen,
+            line.FileId, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitAttrsFieldsReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitPydanticTypeAdapterReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitPytestRaisesReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+        PythonReferenceExtractor.EmitContextlibSuppressReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.IsIgnoredCallName);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreRLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreRLines.cs
new file mode 100644
index 000000000..3ebc1bc49
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreRLines.cs
@@ -0,0 +1,83 @@
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitRLineReferences(in CoreReferenceLineContext line)
+    {
+        EmitRNamespaceAndDispatchReferences(in line);
+        EmitRWorkspaceAndDataReferences(in line);
+        EmitRHelpAndPackageReferences(in line);
+        EmitRMemberReferences(in line);
+    }
+
+    private static void EmitRNamespaceAndDispatchReferences(
+        in CoreReferenceLineContext line)
+    {
+        RReferenceExtractor.EmitNamespaceReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.DefinitionNames);
+        RReferenceExtractor.EmitNamespaceDirectiveReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+        RReferenceExtractor.EmitS4DispatchReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+        RReferenceExtractor.EmitBacktickCallReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.DefinitionNames);
+        RReferenceExtractor.EmitInfixOperatorCallReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.DefinitionNames);
+    }
+
+    private static void EmitRWorkspaceAndDataReferences(
+        in CoreReferenceLineContext line)
+    {
+        RReferenceExtractor.EmitSourceFileReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+        RReferenceExtractor.EmitLoadAllReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+        RReferenceExtractor.EmitDataCallReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+        RReferenceExtractor.EmitSystemFileReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+        RReferenceExtractor.EmitVignetteReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+    }
+
+    private static void EmitRHelpAndPackageReferences(
+        in CoreReferenceLineContext line)
+    {
+        RReferenceExtractor.EmitHelpExampleReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+        RReferenceExtractor.EmitInstallPackagesReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+        RReferenceExtractor.EmitNamespacePackageInstallReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+        RReferenceExtractor.EmitGitHubPackageInstallReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container);
+    }
+
+    private static void EmitRMemberReferences(in CoreReferenceLineContext line)
+    {
+        RReferenceExtractor.EmitDollarMemberReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.DefinitionNames);
+        RReferenceExtractor.EmitBracketMemberReferences(
+            line.PreparedLine, line.OriginalLine, line.References, line.Seen,
+            line.FileId, line.Context, line.LineNumber, line.Container,
+            line.DefinitionNames);
+        RReferenceExtractor.EmitSlotMemberReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container, line.DefinitionNames);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs
index e45a9fcd1..5ba816590 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs
@@ -18,7 +18,7 @@ private static CoreReferenceLineFlow ProcessCoreReferenceLine(
             return CoreReferenceLineFlow.LineConsumed;
         }
 
-        return EmitCoreOrderedReferencePhases(loop, state, prepared);
+        return EmitCoreOrderedReferencePhases(loop, state, in prepared);
     }
 
     private static bool TryPrepareCoreReferenceLine(
@@ -161,7 +161,7 @@ private static bool TryPrepareCoreReferenceLine(
             containerResolver.ResolveContainerForCall,
             state.IsIgnoredCallName);
         prepared = new CorePreparedReferenceLine(
-            line,
+            in line,
             languageLines.OriginalLineForLanguage,
             csharpAttributeRanges,
             csharpAttributeTopLevelRanges,
@@ -266,7 +266,7 @@ private static bool EmitCoreDocumentationAndSpecialLineReferences(
                 loop.CSharpAttributeRanges,
                 getPhpLineContainer);
             EmitCoreDocumentationReferences(
-                documentationLine,
+                in documentationLine,
                 ref state.CSharpInDelimitedDocComment,
                 ref state.JvmInDelimitedDocComment,
                 ref state.PhpInDocblock,
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
index 57581ec75..5ed5ee27d 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
@@ -121,13 +121,34 @@ internal CoreReferenceLoopState(CoreReferenceLoopContext loop)
     }
 
     private readonly record struct CorePreparedReferenceLine(
-        CoreReferenceLineContext Line,
         string OriginalLineForLanguage,
         List<(int start, int end)>? CSharpAttributeRanges,
         List<(int start, int end)>? CSharpAttributeTopLevelRanges,
         CoreLineDefinitionState DefinitionState,
         (SymbolRecord Synthetic, int NameIndex, int OpenBraceIndex, int CloseBraceIndex)? JavaSameLineCtor,
-        CoreReferenceLineContainerResolver ContainerResolver);
+        CoreReferenceLineContainerResolver ContainerResolver)
+    {
+        public readonly CoreReferenceLineContext Line;
+
+        public CorePreparedReferenceLine(
+            in CoreReferenceLineContext line,
+            string originalLineForLanguage,
+            List<(int start, int end)>? cSharpAttributeRanges,
+            List<(int start, int end)>? cSharpAttributeTopLevelRanges,
+            CoreLineDefinitionState definitionState,
+            (SymbolRecord Synthetic, int NameIndex, int OpenBraceIndex, int CloseBraceIndex)? javaSameLineCtor,
+            CoreReferenceLineContainerResolver containerResolver)
+            : this(
+                originalLineForLanguage,
+                cSharpAttributeRanges,
+                cSharpAttributeTopLevelRanges,
+                definitionState,
+                javaSameLineCtor,
+                containerResolver)
+        {
+            Line = line;
+        }
+    }
 
     private static CSharpMultiLineTypePatternState EmitCoreReferenceLines(
         CoreReferenceLoopContext loop)
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
index 85693045c..ccb08c0de 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
@@ -7,26 +7,26 @@ public static partial class ReferenceExtractor
     private static CoreReferenceLineFlow EmitCoreOrderedReferencePhases(
         CoreReferenceLoopContext loop,
         CoreReferenceLoopState state,
-        CorePreparedReferenceLine prepared)
+        in CorePreparedReferenceLine prepared)
     {
         var initialFlow = EmitCoreInitialReferencePhases(
             loop,
             state,
-            prepared);
+            in prepared);
         if (initialFlow != CoreReferenceLineFlow.Continue)
             return initialFlow;
 
-        return EmitCoreRemainingReferencePhases(loop, state, prepared);
+        return EmitCoreRemainingReferencePhases(loop, state, in prepared);
     }
 
     private static CoreReferenceLineFlow EmitCoreInitialReferencePhases(
         CoreReferenceLoopContext loop,
         CoreReferenceLoopState state,
-        CorePreparedReferenceLine prepared)
+        in CorePreparedReferenceLine prepared)
     {
         var request = loop.Request;
         var input = loop.Preparation;
-        var line = prepared.Line;
+        ref readonly var line = ref prepared.Line;
         if (state.ShaderState is not null)
         {
             ShaderReferenceExtractor.EmitLineReferences(
@@ -47,7 +47,7 @@ private static CoreReferenceLineFlow EmitCoreInitialReferencePhases(
         if (loop.IsJsxFile
             && line.Language is "javascript" or "typescript")
         {
-            EmitJsxElementReferences(line);
+            EmitJsxElementReferences(in line);
         }
 
         if (ReferenceLimitReached(line.References))
@@ -95,13 +95,13 @@ private static CoreReferenceLineFlow EmitCoreInitialReferencePhases(
     private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
         CoreReferenceLoopContext loop,
         CoreReferenceLoopState state,
-        CorePreparedReferenceLine prepared)
+        in CorePreparedReferenceLine prepared)
     {
         var request = loop.Request;
         var input = loop.Preparation;
-        var line = prepared.Line;
+        ref readonly var line = ref prepared.Line;
         EmitInfrastructureLineReferences(
-            line,
+            in line,
             loop.DockerfileStageNames,
             loop.DockerfileVariableNames,
             loop.CobolCallableSymbols);
@@ -110,7 +110,7 @@ private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
             return CoreReferenceLineFlow.StopExtraction;
 
         var sqlSuppressedCallIndices = EmitSqlLineReferences(
-            line,
+            in line,
             input.StructuralLines[line.LineIndex],
             state.SqlState,
             prepared.DefinitionState);
@@ -119,9 +119,9 @@ private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
             return CoreReferenceLineFlow.StopExtraction;
 
         if (line.Language is "csharp" or "java")
-            EmitParenlessInitializerReferences(line);
+            EmitParenlessInitializerReferences(in line);
 
-        EmitPhpAndScssLineReferences(line);
+        EmitPhpAndScssLineReferences(in line);
 
         if (ReferenceLimitReached(line.References))
             return CoreReferenceLineFlow.StopExtraction;
@@ -149,7 +149,7 @@ private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
 
         EmitCoreMethodAndMemberReferences(
             loop,
-            line,
+            in line,
             prepared.CSharpAttributeRanges,
             prepared.ContainerResolver.ResolveContainerForCall);
 
@@ -161,14 +161,14 @@ private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
                 line.LineNumber,
                 out var tagHitsOnLine))
         {
-            EmitJavaScriptTaggedTemplateReferences(line, tagHitsOnLine);
+            EmitJavaScriptTaggedTemplateReferences(in line, tagHitsOnLine);
         }
 
         if (ReferenceLimitReached(line.References))
             return CoreReferenceLineFlow.StopExtraction;
 
         EmitMetadataLineReferences(
-            line,
+            in line,
             prepared.CSharpAttributeTopLevelRanges);
 
         if (ReferenceLimitReached(line.References))
@@ -194,16 +194,16 @@ private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
             return CoreReferenceLineFlow.StopExtraction;
 
         if (line.Language == "python")
-            EmitPythonLineReferences(line, loop.Lookups);
+            EmitPythonLineReferences(in line, loop.Lookups);
         if (line.Language == "r")
-            EmitRLineReferences(line);
+            EmitRLineReferences(in line);
 
         return CoreReferenceLineFlow.Continue;
     }
 
     private static void EmitCoreMethodAndMemberReferences(
         CoreReferenceLoopContext loop,
-        CoreReferenceLineContext line,
+        in CoreReferenceLineContext line,
         List<(int start, int end)>? csharpAttributeRanges,
         Func<int, SymbolRecord?> resolveContainerForCall)
     {
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreSpecializedLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreSpecializedLines.cs
index 173aecd02..f36c9f97a 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreSpecializedLines.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreSpecializedLines.cs
@@ -5,7 +5,7 @@ namespace CodeIndex.Indexer;
 
 public static partial class ReferenceExtractor
 {
-    private static void EmitJsxElementReferences(CoreReferenceLineContext line)
+    private static void EmitJsxElementReferences(in CoreReferenceLineContext line)
     {
         if (line.PreparedLine.IndexOf('<') < 0)
             return;
@@ -77,7 +77,7 @@ private static void EmitJsxElementReferences(CoreReferenceLineContext line)
     }
 
     private static void EmitInfrastructureLineReferences(
-        CoreReferenceLineContext line,
+        in CoreReferenceLineContext line,
         HashSet<string>? dockerfileStageNames,
         HashSet<string>? dockerfileVariableNames,
         IReadOnlyList<SymbolRecord>? cobolCallableSymbols)
@@ -133,7 +133,7 @@ private static void EmitInfrastructureLineReferences(
     }
 
     private static HashSet<int>? EmitSqlLineReferences(
-        CoreReferenceLineContext line,
+        in CoreReferenceLineContext line,
         string structuralLine,
         SqlReferenceExtractor.State? sqlState,
         CoreLineDefinitionState definitionState)
@@ -158,7 +158,8 @@ private static void EmitInfrastructureLineReferences(
                     callIndex));
     }
 
-    private static void EmitParenlessInitializerReferences(CoreReferenceLineContext line)
+    private static void EmitParenlessInitializerReferences(
+        in CoreReferenceLineContext line)
     {
         if (line.PreparedLine.IndexOf("new", StringComparison.Ordinal) < 0)
             return;
@@ -274,7 +275,8 @@ private static void EmitParenlessInitializerReferences(CoreReferenceLineContext
         }
     }
 
-    private static void EmitPhpAndScssLineReferences(CoreReferenceLineContext line)
+    private static void EmitPhpAndScssLineReferences(
+        in CoreReferenceLineContext line)
     {
         if (line.Language == "css")
         {
diff --git a/tests/CodeIndex.Tests/ReferenceExtractorPythonTests.cs b/tests/CodeIndex.Tests/ReferenceExtractorPythonTests.cs
index 992de6a6f..fad841501 100644
--- a/tests/CodeIndex.Tests/ReferenceExtractorPythonTests.cs
+++ b/tests/CodeIndex.Tests/ReferenceExtractorPythonTests.cs
@@ -372,6 +372,33 @@ def build(
         Assert.Null(exception);
     }
 
+    [Fact]
+    public void Extract_PythonLogicalHeader_RemapRunsAfterReferenceLimitReached()
+    {
+        const string content = """
+            class Derived(
+                FirstBase,
+                SecondBase,
+            ):
+                pass
+            """;
+
+        var symbols = SymbolExtractor.Extract(1, "python", content);
+        var references = ReferenceExtractor.Extract(
+            1,
+            "python",
+            content,
+            symbols,
+            maxReferenceCount: 1);
+
+        var reference = Assert.Single(references);
+        Assert.Equal("FirstBase", reference.SymbolName);
+        Assert.Equal("type_reference", reference.ReferenceKind);
+        Assert.Equal(2, reference.Line);
+        Assert.Equal(5, reference.Column);
+        Assert.Equal("FirstBase,", reference.Context);
+    }
+
     [Fact]
     public void Extract_PythonClassHook_AssignsReferencesToHookContainer()
     {

From 3c7ada47f83180baa8b62cb2808ad7a9b305a713 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 14:49:18 +0900
Subject: [PATCH 19/45] Decompose file dependency queries

---
 TESTING_GUIDE.md                              |    4 +-
 .../Database/DbReader.Dependencies.cs         | 1151 +----------------
 .../Database/DbReader.DependencyCycleQuery.cs |  253 ++++
 .../Database/DbReader.DependencyEdgeSql.cs    |  121 ++
 .../Database/DbReader.DependencyFinalSql.cs   |  129 ++
 .../Database/DbReader.DependencyProjection.cs |   77 ++
 .../DbReader.DependencyQueryBinding.cs        |  179 +++
 .../DbReader.DependencyQueryExecution.cs      |   40 +
 .../Database/DbReader.DependencyQueryPlan.cs  |  215 +++
 .../DbReader.DependencyResolvedIdentitySql.cs |   55 +
 .../DbReader.DependencySourceCandidateSql.cs  |   86 ++
 .../Database/DbReader.DependencySourceSql.cs  |  161 +++
 .../DbReader.DependencySpecialEdgeSql.cs      |  137 ++
 .../Database/DbReader.DependencyTargetSql.cs  |  179 +++
 .../DbReaderFileDependencyTests.cs            |   11 +
 15 files changed, 1655 insertions(+), 1143 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyCycleQuery.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyEdgeSql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyFinalSql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyProjection.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyQueryBinding.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyQueryExecution.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyQueryPlan.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyResolvedIdentitySql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencySourceCandidateSql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencySourceSql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencySpecialEdgeSql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyTargetSql.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 97604efc3..050a395e0 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -187,7 +187,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   `DbSchemaConstraintTests` runs the public-array mutation regression in the non-parallel SQLite-sensitive collection and restores both arrays in `finally`. It must prove that writer validation and newly generated symbol/reference CHECK clauses continue to use the same private canonical taxonomy while the compatibility arrays are visibly mutated.
   Do not put a timing assertion in this test class. When a static lookup replay is useful, keep its Release harness temporary, feed the same persisted kind/count distribution to the legacy and candidate lookups, alternate execution order, and remove it before committing. The normal empty-database full-index A/B remains authoritative for the user-visible performance decision.
 - `DatabaseTests.cs`, `DatabasePermissionPolicyTests.cs`, `DbReader*Tests.cs`, `CSharpBaseListParserTests.cs`
-  SQLite schema, write paths, migrations, and query behavior. DbReader coverage is split by query family, including search, SQL qualified-name handling, file dependencies, impact, and symbol-query suites, while shared seeded fixture state remains on the root `DbReaderTests` part.
+  SQLite schema, write paths, migrations, and query behavior. DbReader coverage is split by query family, including search, SQL qualified-name handling, file dependencies, impact, and symbol-query suites, while shared seeded fixture state remains on the root `DbReaderTests` part. File-dependency coverage keeps pre-cancellation ahead of command construction and execution.
   `CSharpBaseListParserTests` keeps the SQLite-free base-list grammar matrix together, including generic constraints, nested generic/tuple/array syntax, alias qualifiers, primary/base constructors, declaration terminators, and the distinct reader type-reference and metadata head-identifier projections.
   Maintenance-lookup coverage keeps the `files(checksum)`, `files(path COLLATE NOCASE)`, and `file_issues(file_id, kind)` indexes aligned with their predicates and requires `EXPLAIN QUERY PLAN` index `SEARCH` operations for checksum purge, ASCII case-alias lookup, reusable-stat issue probes, and directory/stem rename candidates. The case-alias fixture uses changed content so checksum cannot hide a missing path lookup, and managed validation remains authoritative because SQLite `NOCASE` is only an ASCII prefilter, not a Unicode casing contract. Keep wildcard-bearing, extensionless, and near-match stem semantics in one fixture. Scoped-cleanup planning coverage unions checksum and exact same-directory/stem candidates into ascending deduplicated ID snapshots, merges overlapping plans, proves apply does not absorb matching rows added after planning, and rereads planned IDs immediately before apply so a deleted C# contract that reappears is deferred until a clean retry. The grouped C# fixture gives many targets one common checksum/stem and requires candidate-reader work to grow with unique keys plus returned rows rather than target-count squared; it also asserts that C# pre-workspace planning never deletes matching non-C# rows.
   Reference-resolution lookup coverage keeps the exact fresh-schema and read-migration index sets aligned for file/name, retained folded/NOCASE composite prefixes, resolved reverse edges, and the partial unresolved-mutual path. Assert the absence of all six retired single-prefix indexes plus the former all-row mutual index after migration and reopen, exact column order/collation/partial predicates, and `EXPLAIN QUERY PLAN` `SEARCH` operations for both full and scoped mutual SQL. Preserve fold-ready and legacy-fallback CLI/MCP exact-query signals, and rerun the same-name/different-container plus partial-class-over-same-file ranking fixtures when these indexes change.
@@ -1246,7 +1246,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   `DbSchemaConstraintTests` の公開 array mutation 回帰は、並列実行しない SQLite-sensitive collection で実行し、`finally` で両 array を復元します。互換 array の変更が実際に見える間も、writer validation と新規生成する symbol / reference CHECK 句が同じ private canonical taxonomy を使い続けることを必須とします。
   この test class に timing assertion を追加してはいけません。static lookup replay が有用な場合は Release harness を一時的なものに限定し、同一の保存済み kind/count 分布を旧来経路と候補経路へ流し、実行順を交互にしたうえで commit 前に削除します。ユーザーに見える性能の採否は、通常の空 database full-index A/B を authoritative としてください。
 - `DatabaseTests.cs`、`DatabasePermissionPolicyTests.cs`、`DbReader*Tests.cs`、`CSharpBaseListParserTests.cs`
-  SQLite スキーマ、書き込み経路、マイグレーション、クエリ挙動のテスト。DbReader のカバレッジは search、SQL qualified name、file dependency、impact、symbol query などの query family ごとの partial suite に分割し、共有の seed 済み fixture 状態は root 側の `DbReaderTests` に残します。
+  SQLite スキーマ、書き込み経路、マイグレーション、クエリ挙動のテスト。DbReader のカバレッジは search、SQL qualified name、file dependency、impact、symbol query などの query family ごとの partial suite に分割し、共有の seed 済み fixture 状態は root 側の `DbReaderTests` に残します。file dependency の coverage では、command 構築・実行より前の pre-cancellation を固定します。
   `CSharpBaseListParserTests` には SQLite を使わない base-list 構文 matrix をまとめ、generic constraint、nested generic / tuple / array、alias qualifier、primary / base constructor、宣言終端、および reader の type-reference 投影と metadata の head-identifier 投影の差を固定します。
   maintenance lookup の coverage では `files(checksum)`、`files(path COLLATE NOCASE)`、`file_issues(file_id, kind)` の index を predicate と同期させ、checksum purge、ASCII case-alias lookup、再利用 stat の issue probe、directory/stem rename 候補が `EXPLAIN QUERY PLAN` で index `SEARCH` を使うことを必須とします。case-alias fixture は checksum で path lookup の欠落が隠れないよう content も変更し、SQLite `NOCASE` は Unicode casing contract ではなく ASCII prefilter にすぎないため managed 検証を authoritative に保ちます。wildcard を含む stem、拡張子なし、近似 stem の意味論は1つの fixture にまとめます。scoped cleanup planning の coverage では checksum と正確な同一 directory/stem の候補を昇順・重複排除済み ID snapshot に統合し、重複 plan の merge、plan 後に追加された一致 row を apply が取り込まないこと、apply 直前に planned ID を再読込して再出現した C# contract を clean retry まで延期することを固定します。grouped C# fixture は多数の target に共通 checksum/stem を与え、candidate reader の処理量が target 数の二乗ではなく unique key 数と返却 row 数に比例すること、および C# workspace 前の plan が一致する non-C# row を削除しないことを要求します。
   参照解決 lookup の coverage では fresh schema / read migration の正確な index setを、file/name、保持したfolded/NOCASE composite prefix、解決済み逆辺、未解決mutual用partial pathまで同期させます。migrationと再open後に退役したsingle-prefix 6本と旧全row mutual indexが存在しないこと、列順・collation・partial predicateを厳密に検証し、full/scoped mutual SQLの両方で`EXPLAIN QUERY PLAN`のindex `SEARCH`を必須とします。fold-ready/legacy fallback双方のCLI/MCP exact-query signalを維持し、これらのindexを変える際は同名・別containerとpartial classが同一file候補より優先される既存ranking fixtureも再実行してください。
diff --git a/src/CodeIndex/Database/DbReader.Dependencies.cs b/src/CodeIndex/Database/DbReader.Dependencies.cs
index f0e502e40..e52142935 100644
--- a/src/CodeIndex/Database/DbReader.Dependencies.cs
+++ b/src/CodeIndex/Database/DbReader.Dependencies.cs
@@ -238,1153 +238,22 @@ public List<FileDependencyResult> GetFileDependencies(
         lang = NormalizeQueryLanguage(lang);
         if (!_hasReferencesTable) return new List<FileDependencyResult>();
         cancellationToken.ThrowIfCancellationRequested();
-        using var cmd = _conn.CreateCommand();
-        var referenceLineJoin = ReferenceLineJoinSql("r");
-        var contextSql = ReferenceContextSql("r");
-        var hasResolvedReferenceTargets = _referenceIdentityContractCurrent;
-        var resolutionStateSql = hasResolvedReferenceTargets ? "r.resolution_state" : "NULL";
-        var identityScopeConditionSql = """
-            (
-                (src.lang = 'csharp' AND r.reference_kind NOT IN ('attribute', 'annotation'))
-                OR (src.lang = 'dependency_lock' AND r.reference_kind = 'dependency')
-            )
-            """;
-        var referenceIdSql = $"CASE WHEN {identityScopeConditionSql} THEN r.id ELSE 0 END";
-        var scopedResolutionStateSql = $"CASE WHEN {identityScopeConditionSql} THEN {resolutionStateSql} ELSE NULL END";
-        var identityScopedSql = $"CASE WHEN {identityScopeConditionSql} THEN 1 ELSE 0 END";
-        var identityNameEdgePredicate = hasResolvedReferenceTargets
-            ? "snc.identity_scoped = 0"
-            : "snc.source_lang <> 'dependency_lock'";
-        var resolvedIdentityLimitSql = lang == "csharp"
-            ? " LIMIT @sourceCandidateLimit"
-            : string.Empty;
-        var resolvedIdentityEdgesSql = hasResolvedReferenceTargets
-            ? @"
-                SELECT resolved.source_path,
-                       resolved.target_path,
-                       resolved.symbol_name,
-                       COUNT(*) AS ref_count,
-                       resolved.source_lang,
-                       'resolved_identity' AS origin,
-                       resolved.raw_reference_kind,
-                       resolved.target_kind
-                FROM (
-                    SELECT DISTINCT lrp.source_path,
-                           target_file.path AS target_path,
-                           lrp.symbol_name,
-                           lrp.reference_id,
-                           lrp.source_lang,
-                           lrp.raw_reference_kind,
-                           target.kind AS target_kind
-                    FROM logical_references_primary lrp
-                    JOIN symbol_reference_candidates candidate
-                      ON candidate.reference_id = lrp.reference_id
-                    JOIN symbols target ON target.id = candidate.symbol_id
-                    JOIN files target_file ON target_file.id = target.file_id
-                    JOIN target_files scoped_target
-                      ON scoped_target.target_path = target_file.path
-                     AND scoped_target.target_lang = target_file.lang
-                    WHERE lrp.identity_scoped = 1
-                      AND lrp.resolution_state IN ('resolved', 'resolved_group')
-                      AND lrp.source_path != target_file.path"
-            : string.Empty;
-        if (hasResolvedReferenceTargets)
-        {
-            AppendDependencySymbolFilter(
-                cmd,
-                ref resolvedIdentityEdgesSql,
-                "lrp.symbol_name",
-                dependencySymbols,
-                dependencySymbolFamilies,
-                suppressDependencyNoise,
-                "resolvedDependency");
-            resolvedIdentityEdgesSql += @"
-                     ORDER BY lrp.source_path, lrp.symbol_name, lrp.reference_id" + resolvedIdentityLimitSql + @"
-                ) resolved
-                GROUP BY resolved.source_path, resolved.target_path, resolved.symbol_name,
-                         resolved.source_lang, resolved.raw_reference_kind, resolved.target_kind
-                UNION ALL
-                ";
-        }
-        // Aggregate logical reference sites per source-file/name first, then join that bounded
-        // set to distinct target files. This avoids the per-reference × per-symbol explosion that
-        // could exhaust SQLite temp-store on large indexes with many same-named symbols.
-        // まず source-file/name 単位に logical reference site 数を集約し、その後で distinct な
-        // target file と結合することで、大規模 index で SQLite temp-store を枯渇させる
-        // per-reference × per-symbol の膨張を防ぐ。
-        var sourceFilterAlias = "src";
-        var targetFilterAlias = "dst";
-        var targetLogicalSymbolNameExpr = BuildLogicalDependencySymbolNameExpr("dst", "s.name");
-        var targetLogicalSymbolSegmentCountExpr = BuildLogicalDependencySymbolSegmentCountExpr("dst", "s.name");
-        var pythonImportMatchSignatureExpr = GetSymbolColumnSql("signature", "NULL", "py_import_match");
-        var pythonImportSignatureExpr = GetSymbolColumnSql("signature", "NULL", "py_import");
-        var sqlDependencyTargetMatchExpr = @"(
-                    (tf.target_lang != 'sql'
-                     AND NOT (snc.source_lang IN ('msbuild', 'solution') AND snc.logical_reference_kind IN ('import', 'project_reference'))
-                     AND NOT (snc.source_lang = 'markdown' AND snc.logical_reference_kind = 'import')
-                     AND NOT (snc.source_lang = 'markdown' AND snc.logical_reference_kind = 'reference')
-                     AND tf.symbol_name = snc.symbol_name)
-                 OR (snc.source_lang = 'python'
-                     AND tf.target_lang = 'python'
-                     AND EXISTS (
-                         SELECT 1 FROM symbols py_import_match
-                         WHERE py_import_match.file_id = snc.source_file_id
-                           AND py_import_match.kind = 'import'
-                           AND python_import_target_name(snc.source_path, snc.symbol_name, snc.context, snc.column_number, " + pythonImportMatchSignatureExpr + @") = tf.symbol_name
-                     ))
-                 OR (tf.target_lang = 'sql' AND (
-                        (tf.symbol_segment_count = snc.symbol_segment_count AND tf.symbol_name = snc.symbol_name COLLATE NOCASE)
-                     OR (sql_segment_count(snc.raw_symbol_name) = 1
-                         AND snc.allow_leaf_fallback = 1
-                         AND tf.symbol_segment_count > 1
-                         AND sql_leaf_name(tf.symbol_name) = snc.raw_symbol_name COLLATE NOCASE
-                         AND NOT EXISTS (
-                                SELECT 1
-                                FROM target_files tf_exact
-                                WHERE tf_exact.target_lang = tf.target_lang
-                                  AND tf_exact.symbol_segment_count = 1
-                                  AND tf_exact.symbol_name = snc.symbol_name COLLATE NOCASE
-                            )
-                         AND NOT EXISTS (
-                                SELECT 1
-                                FROM target_files tf_resolved
-                                WHERE tf_resolved.target_lang = tf.target_lang
-                                  AND tf_resolved.symbol_segment_count = snc.symbol_segment_count
-                                  AND tf_resolved.symbol_name = snc.symbol_name COLLATE NOCASE
-                            ))
-                 ))
-                )";
-        var sql = @"
-            WITH logical_references_primary AS (
-                SELECT src.id AS source_file_id,
-                       src.path AS source_path,
-                       src.lang AS source_lang,
-                       " + referenceIdSql + @" AS reference_id,
-                       " + scopedResolutionStateSql + @" AS resolution_state,
-                       " + identityScopedSql + @" AS identity_scoped,
-                       r.symbol_name,
-                       " + contextSql + @" AS context,
-                       r.container_name,
-                       r.line,
-                       r.column_number,
-                       r.reference_kind AS raw_reference_kind,
-                       " + GetLogicalReferenceKindSql("r.reference_kind") + @" AS logical_reference_kind
-                FROM symbol_references r
-                JOIN files src ON r.file_id = src.id" + referenceLineJoin + @"
-                WHERE 1 = 1";
-        // `deps` intentionally includes metadata-only reference kinds
-        // (`attribute` / `annotation`). Same rationale as
-        // `GetFileDependencyHintsToResolvedType`: renaming or removing a type that
-        // is only referenced via `[JsonConverter(typeof(User))]` or
-        // `@Inject(User.class)` still breaks the annotated file at compile time, so
-        // file-level dependency analysis must treat those sites as real edges.
-        // Call-graph-specific commands (`callers` / `callees`) keep rejecting
-        // metadata kinds at the CLI / MCP boundary — that is a separate contract.
-        // `deps` は metadata-only 参照 (`attribute` / `annotation`) も意図的に
-        // 含める。`GetFileDependencyHintsToResolvedType` と同じ理由で、
-        // `[JsonConverter(typeof(User))]` や `@Inject(User.class)` 経由でしか参照
-        // されない型でも、rename / 削除すれば annotated ファイルは compile-time
-        // で壊れるため、ファイル単位の依存分析では本物の edge として扱う必要が
-        // ある。call-graph 専用コマンド (`callers` / `callees`) 側では metadata
-        // 種別の拒否を CLI / MCP boundary で引き続き行う — そちらは別契約。
-        sql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "src", "depsLang")}";
-        AppendDependencyGeneratedFilter(ref sql, sourceFilterAlias);
-        if (lang != null)
-            sql += " AND src.lang = @lang";
-        if (!reverse && pathPatterns is { Count: > 0 })
-        {
-            var ors = new List<string>(pathPatterns.Count);
-            for (int i = 0; i < pathPatterns.Count; i++)
-                ors.Add(BuildPathFilterPredicate(sourceFilterAlias, "pathPattern", i, pathPatterns[i]));
-            sql += " AND (" + string.Join(" OR ", ors) + ")";
-        }
-        if (!reverse && excludePathPatterns is { Count: > 0 })
-        {
-            for (int i = 0; i < excludePathPatterns.Count; i++)
-                sql += $" AND NOT {BuildPathFilterPredicate(sourceFilterAlias, "excludePath", i, excludePathPatterns[i])}";
-        }
-        if (excludeTests)
-            sql += $" AND NOT {DependencyTestPathCondition($"{sourceFilterAlias}.path")}";
-        sql += @"
-                GROUP BY src.id, src.path, src.lang, " + referenceIdSql + @", " + scopedResolutionStateSql + @", " + identityScopedSql + @", r.symbol_name, " + contextSql + @", r.container_name, r.line, r.column_number, r.reference_kind, logical_reference_kind
-            ),
-            logical_references AS (
-                SELECT source_file_id, source_path, source_lang, reference_id, identity_scoped,
-                       " + BuildLogicalReferenceNameExpr("source_lang", "symbol_name", "context", "container_name", "column_number") + @" AS symbol_name,
-                       " + BuildLogicalReferenceSegmentCountExpr("source_lang", "symbol_name", "context", "container_name", "column_number") + @" AS symbol_segment_count,
-                       " + BuildLogicalReferenceLeafFallbackAllowedExpr("source_lang", "symbol_name", "context", "container_name", "column_number") + @" AS allow_leaf_fallback,
-                       symbol_name AS raw_symbol_name,
-                       context, line, column_number, raw_reference_kind, logical_reference_kind,
-                       0 AS is_attribute_alias,
-                       CASE WHEN logical_reference_kind IN ('attribute', 'annotation') THEN 1 ELSE 0 END AS is_metadata
-                FROM logical_references_primary
-                UNION ALL
-                -- C# attribute suffix alias: [Foo] in source is stored with symbol_name='Foo',
-                -- but the defining class is named 'FooAttribute'. Emit the canonical 'Foo' + 'Attribute'
-                -- form so deps can match the class file as a target. The alias rows are flagged
-                -- so the edges CTE can restrict them to class-like targets and avoid spurious
-                -- edges to unrelated functions / properties that happen to be named 'FooAttribute'.
-                -- C# 属性のサフィックス別名: ソース上の [Foo] は symbol_name='Foo' で保存されるが、
-                -- 定義クラスは 'FooAttribute' 命名になるため、正規形 'Foo' + 'Attribute' を補って
-                -- deps がクラス側のファイルを target として join できるようにする。alias 行には
-                -- フラグを付け、edges CTE 側で class-like target だけに限定する。これにより、
-                -- 偶然 'FooAttribute' という名前を持つ関数やプロパティへの誤ったエッジを防ぐ。
-                SELECT source_file_id, source_path, source_lang, reference_id, identity_scoped,
-                       symbol_name || 'Attribute' AS symbol_name,
-                       1 AS symbol_segment_count,
-                       0 AS allow_leaf_fallback,
-                       symbol_name || 'Attribute' AS raw_symbol_name,
-                       context, line, column_number, raw_reference_kind, logical_reference_kind,
-                       1 AS is_attribute_alias,
-                       1 AS is_metadata
-                FROM logical_references_primary
-                WHERE source_lang = 'csharp'
-                  AND logical_reference_kind = 'attribute'
-                  AND symbol_name NOT LIKE '%Attribute'
-            ),
-            source_name_counts AS (
-                -- Grouping includes is_metadata so metadata-only groups ([Foo] / @Foo)
-                -- can be restricted to class-like targets independently from non-metadata
-                -- call-graph groups that share the same symbol_name in the same file
-                -- (e.g. `Foo()` call + `[Foo]` attribute both present in the same source).
-                -- is_metadata を GROUP BY に含めることで、同じ source file / symbol_name を
-                -- 共有する metadata 行と call-graph 行 (例: 同じファイル内の `Foo()` 呼び出し
-                -- と `[Foo]` 属性) を別グループとして扱い、metadata 側だけに class-like
-                -- target 制限を掛けられるようにする。
-                SELECT source_file_id,
-                       source_path,
-                       source_lang,
-                       identity_scoped,
-                       symbol_name,
-                       symbol_segment_count,
-                       allow_leaf_fallback,
-                       raw_symbol_name,
-                       context,
-                       column_number,
-                       raw_reference_kind,
-                       logical_reference_kind,
-                       is_attribute_alias,
-                       is_metadata,
-                       COUNT(*) AS ref_count
-                FROM logical_references
-                WHERE 1 = 1";
-        // C# reference names match the public dependency symbol, so filtering them here
-        // bounds source aggregation. Other languages may resolve an alias or path-like
-        // reference to a differently named target; retain those rows until target_files
-        // applies the public symbol filter.
-        // C# の reference 名は公開 dependency symbol と一致するため、ここで絞って source
-        // 集約を制限する。他言語は alias や path 形式の reference を異なる target 名へ
-        // 解決する場合があるため、target_files が公開 symbol filter を適用するまで保持する。
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "symbol_name",
-            dependencySymbols,
-            dependencySymbolFamilies,
-            suppressDependencyNoise,
-            "sourceDependency",
-            "source_lang = 'csharp'");
-        sql += @"
-                GROUP BY source_file_id, source_path, source_lang, identity_scoped, symbol_name, symbol_segment_count, allow_leaf_fallback, raw_symbol_name, context, column_number, raw_reference_kind, logical_reference_kind, is_attribute_alias, is_metadata
-            )";
-        if (lang == "csharp")
-        {
-            // Bound the expensive C# name-to-target join by the requested result limit.
-            // The final edge ranking already uses an over-fetched candidate window; applying
-            // the same window to source/name groups prevents a tiny --limit from comparing the
-            // complete C# reference graph before LIMIT can take effect.
-            // 高コストな C# の name-to-target join を要求された結果上限に連動して制限する。
-            // 最終 edge ranking と同じ over-fetch 候補窓を source/name group にも適用し、
-            // 小さな --limit でも LIMIT 前に C# 参照グラフ全体を比較する事態を防ぐ。
-            sql += @",
-            csharp_dependency_targets AS (
-                SELECT dst.path AS target_path,
-                       " + targetLogicalSymbolNameExpr + @" AS symbol_name,
-                       MAX(CASE WHEN " + BuildMetadataTargetKindExpr("dst") + @" THEN 1 ELSE 0 END) AS has_metadata_target_kind
-                FROM symbols s
-                JOIN files dst ON s.file_id = dst.id
-                WHERE dst.lang = 'csharp'";
-            AppendDependencyGeneratedFilter(ref sql, "dst");
-            if (reverse && pathPatterns is { Count: > 0 })
-            {
-                var ors = new List<string>(pathPatterns.Count);
-                for (int i = 0; i < pathPatterns.Count; i++)
-                    ors.Add(BuildPathFilterPredicate("dst", "pathPattern", i, pathPatterns[i]));
-                sql += " AND (" + string.Join(" OR ", ors) + ")";
-            }
-            if (reverse && excludePathPatterns is { Count: > 0 })
-            {
-                for (int i = 0; i < excludePathPatterns.Count; i++)
-                    sql += $" AND NOT {BuildPathFilterPredicate("dst", "excludePath", i, excludePathPatterns[i])}";
-            }
-            if (excludeTests)
-                sql += $" AND NOT {DependencyTestPathCondition("dst.path")}";
-            AppendDependencySymbolFilter(
-                cmd,
-                ref sql,
-                targetLogicalSymbolNameExpr,
-                dependencySymbols,
-                dependencySymbolFamilies,
-                suppressDependencyNoise,
-                "boundedTargetDependency");
-            sql += @"
-                GROUP BY dst.path, " + targetLogicalSymbolNameExpr + @"
-            ),
-            bounded_source_name_counts AS (
-                SELECT snc.*
-                FROM source_name_counts snc
-                WHERE EXISTS (
-                    SELECT 1
-                    FROM csharp_dependency_targets tf
-                    WHERE tf.symbol_name = snc.symbol_name
-                      AND tf.target_path != snc.source_path
-                      AND (snc.is_metadata = 0 OR tf.has_metadata_target_kind = 1)
-                )
-                ORDER BY snc.ref_count DESC, snc.source_path, snc.symbol_name, snc.context, snc.column_number, snc.raw_reference_kind
-                LIMIT @sourceCandidateLimit
-            ),";
-        }
-        else
-        {
-            sql += @",
-            bounded_source_name_counts AS (
-                SELECT * FROM source_name_counts
-            ),";
-        }
-        sql += @"
-            target_files AS (
-                -- Collapse per-symbol rows to one per (target_path, target_lang, symbol_name)
-                -- and remember whether any of the same-name symbols is a class-like kind
-                -- via MAX. Keeping kind in DISTINCT would split identical (path, lang, name)
-                -- rows when one file defines both a class and a same-name function (e.g. a
-                -- C# constructor), inflating the deps reference count.
-                -- (target_path, target_lang, symbol_name) 単位に集約し、同名のシンボルの
-                -- いずれかが class 系であるかを MAX で覚える。kind を DISTINCT に含めると、
-                -- 同じ (path, lang, name) でも class と同名 function (C# のコンストラクタ等)
-                -- が別行として残り、deps の参照カウントが膨らんでしまう。
-                -- has_metadata_target_kind further narrows the class-like set to targets
-                -- that can legitimately be referenced as [Attribute] metadata. For C#
-                -- we cannot resolve base types transitively at SQL time, so the best
-                -- portable approximation is an inheritance-clause check: any class
-                -- declared with a base list is a potential attribute type (direct or
-                -- indirect Attribute derivation). A plain class FooAttribute with no
-                -- base clause is not a valid [Foo] target at compile time.
-                -- Other languages keep the original class-like breadth. Legacy DBs
-                -- without a signature column degrade to the broad class-like set.
-                -- has_metadata_target_kind は [Attribute] metadata target として妥当な
-                -- class-like のみに絞る。C# は SQL 時点で基底型を遡れないため、継承節を
-                -- 持つクラスを候補とする近似を採る(直接・間接の Attribute 継承を
-                -- 取りこぼさない)。他言語は class-like 全体を残す。signature 列が無い
-                -- legacy DB では filter を無効化し class-like 全体に戻る。
-                SELECT dst.path AS target_path,
-                       dst.lang AS target_lang,
-                       " + targetLogicalSymbolNameExpr + @" AS symbol_name,
-                       " + targetLogicalSymbolSegmentCountExpr + @" AS symbol_segment_count,
-                       MAX(CASE WHEN s.kind IN ('class','struct','interface') THEN 1 ELSE 0 END) AS has_class_like_kind,
-                       MAX(CASE WHEN s.kind = 'heading' THEN 1 ELSE 0 END) AS has_heading_kind,
-                       MAX(CASE WHEN " + BuildMetadataTargetKindExpr("dst") + @"
-                                THEN 1 ELSE 0 END) AS has_metadata_target_kind
-                FROM symbols s
-                JOIN files dst ON s.file_id = dst.id
-                WHERE 1 = 1";
-        sql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "dst", "depsTargetLang")}";
-        AppendDependencyGeneratedFilter(ref sql, targetFilterAlias);
-        if (lang != null && !lang.Equals("solution", StringComparison.Ordinal))
-            sql += " AND dst.lang = @lang";
-        if (reverse && pathPatterns is { Count: > 0 })
-        {
-            var ors = new List<string>(pathPatterns.Count);
-            for (int i = 0; i < pathPatterns.Count; i++)
-                ors.Add(BuildPathFilterPredicate(targetFilterAlias, "pathPattern", i, pathPatterns[i]));
-            sql += " AND (" + string.Join(" OR ", ors) + ")";
-        }
-        if (reverse && excludePathPatterns is { Count: > 0 })
-        {
-            for (int i = 0; i < excludePathPatterns.Count; i++)
-                sql += $" AND NOT {BuildPathFilterPredicate(targetFilterAlias, "excludePath", i, excludePathPatterns[i])}";
-        }
-        if (excludeTests)
-            sql += $" AND NOT {DependencyTestPathCondition($"{targetFilterAlias}.path")}";
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            targetLogicalSymbolNameExpr,
-            dependencySymbols,
-            dependencySymbolFamilies,
-            suppressDependencyNoise,
-            "targetDependency",
-            "dst.lang = 'csharp'");
-        sql += @"
-                GROUP BY dst.path, dst.lang, " + targetLogicalSymbolNameExpr + @", " + targetLogicalSymbolSegmentCountExpr + @"
-            ),
-            path_target_files AS (
-                SELECT DISTINCT target_path, target_lang
-                FROM target_files
-            ),
-            metadata_raw_suppression AS (
-                -- When a raw C# attribute reference '[Foo]' (stored as symbol_name='Foo',
-                -- logical_reference_kind='attribute') also has a synthetic suffix alias
-                -- row that resolves to a class-like 'FooAttribute' target, drop the raw
-                -- row to avoid creating a duplicate edge to any unrelated 'Foo' symbol
-                -- (method, property, local class) that merely shares the bare name.
-                -- 生の C# 属性参照 '[Foo]' (symbol_name='Foo', kind='attribute') に対して
-                -- 同じ source_file 内で 'FooAttribute' の synthetic alias 行が
-                -- class 系 target に解決できる場合、この行自体は落として
-                -- 同名の関数/プロパティ/ローカルクラス 'Foo' への誤依存を防ぐ。
-                SELECT DISTINCT lrp.source_file_id, lrp.symbol_name
-                FROM logical_references_primary lrp
-                JOIN target_files tf_alias
-                  ON tf_alias.target_lang = lrp.source_lang
-                 AND tf_alias.symbol_name = lrp.symbol_name || 'Attribute'
-                 AND tf_alias.symbol_segment_count = 1
-                 AND tf_alias.has_metadata_target_kind = 1
-                WHERE lrp.source_lang = 'csharp'
-                  AND lrp.logical_reference_kind = 'attribute'
-                  AND lrp.symbol_name NOT LIKE '%Attribute'
-            ),
-            target_ambiguity AS (
-                -- Count class-like definitions at symbol-identity level rather than
-                -- file level. Two same-named class-like definitions in the same file
-                -- (e.g. `namespace A { class FooAttribute { } } namespace B { class
-                -- FooAttribute { } }` both inside one .cs file) collapse to a single
-                -- target_files row because target_files is GROUPed by dst.path, so
-                -- COUNT(DISTINCT target_path) alone would see count=1 and falsely
-                -- treat the metadata target as unambiguous. Joining target_files back
-                -- through files + symbols recovers the per-definition row count while
-                -- still inheriting target_files' lang / path / graph-supported scope
-                -- (since the join only keeps rows whose (path, lang, name) already
-                -- appear in target_files).
-                -- class-like 定義は path 単位ではなく symbol identity 単位で数える。
-                -- 同じ .cs ファイル内に別名前空間で同名 class-like が 2 つあるケースは
-                -- target_files (dst.path で GROUP BY) 上では 1 行に潰れており、
-                -- COUNT(DISTINCT target_path) だけでは count=1 となり metadata target
-                -- が一意と誤判定される。target_files から files + symbols に JOIN し直す
-                -- ことで定義単位の件数を復元する。JOIN が target_files 既存行にしか
-                -- 当たらないため、lang / path / graph-supported スコープはそのまま継承。
-                SELECT tf.target_lang,
-                       tf.symbol_name,
-                       tf.symbol_segment_count,
-                       COUNT(*) AS class_like_target_count
-                FROM target_files tf
-                JOIN files dst
-                  ON dst.path = tf.target_path
-                 AND dst.lang = tf.target_lang
-                JOIN symbols s
-                  ON s.file_id = dst.id
-                 AND " + targetLogicalSymbolNameExpr + @" = tf.symbol_name
-                 AND " + targetLogicalSymbolSegmentCountExpr + @" = tf.symbol_segment_count
-                 -- Same language-aware metadata-eligibility filter as
-                 -- target_files: C# restricts to `class` with inheritance
-                 -- clause (interface/struct cannot be attribute targets);
-                 -- JS/TS additionally accepts `function` (decorator
-                 -- factory); others keep the class-like candidate set.
-                 -- target_files と同じ言語別 metadata 適格性フィルタ。
-                 -- C# は class 限定 + 継承節 (interface/struct は除外)。
-                 -- JS/TS は decorator factory 用に function も許容。
-                 -- それ以外は class-like 全体を候補にする。
-                 AND " + BuildMetadataTargetKindExpr("dst") + @"
-                WHERE tf.has_metadata_target_kind = 1
-                GROUP BY tf.target_lang, tf.symbol_name, tf.symbol_segment_count
-            ),
-            edges AS (
-                " + resolvedIdentityEdgesSql + @"
-                SELECT snc.source_path,
-                       tf.target_path,
-                       tf.symbol_name,
-                       snc.ref_count,
-                       snc.source_lang,
-                       CASE
-                           WHEN snc.source_lang = 'markdown' AND tf.has_heading_kind = 1
-                               THEN 'markdown_heading_name_match'
-                           ELSE 'symbol_name_match'
-                       END AS origin,
-                       snc.raw_reference_kind,
-                       CASE WHEN tf.has_heading_kind = 1 THEN 'heading' ELSE 'symbol' END AS target_kind
-                FROM bounded_source_name_counts snc
-                JOIN target_files tf
-                  ON " + sqlDependencyTargetMatchExpr + @"
-                 AND tf.target_lang = snc.source_lang
-                LEFT JOIN metadata_raw_suppression mrs
-                  ON mrs.source_file_id = snc.source_file_id
-                 AND mrs.symbol_name = snc.symbol_name
-                LEFT JOIN target_ambiguity ta
-                  ON ta.target_lang = snc.source_lang
-                 AND ta.symbol_name = snc.symbol_name
-                 AND ta.symbol_segment_count = snc.symbol_segment_count
-                WHERE snc.source_path != tf.target_path
-                  AND " + identityNameEdgePredicate + @"
-                  -- All metadata references ([Foo] / @Foo) and their synthetic C#
-                  -- suffix aliases must only match class-like target kinds; otherwise
-                  -- a metadata reference would spuriously depend on any file that
-                  -- merely defines a function / property / variable sharing the name.
-                  -- Non-metadata call-graph refs keep matching any kind so e.g. a
-                  -- constructor call can still tie back to a class definition.
-                  -- metadata 参照 ([Foo] / @Foo) と C# の合成 alias 行はいずれも
-                  -- class 系の target 種別にのみ一致させる。これを許すと同名の
-                  -- 関数/プロパティ/変数を持つだけのファイルまで誤って依存してしまう。
-                  -- 非 metadata の call-graph 参照は任意の kind に一致させて構わない
-                  -- (コンストラクタ呼び出しがクラス定義に結び付くケースなど)。
-                  AND (snc.is_metadata = 0 OR tf.has_metadata_target_kind = 1)
-                  -- Drop raw C# '[Foo]' rows when the suffix alias already resolves
-                  -- to a class-like 'FooAttribute' target in the same source file.
-                  -- 同じ source file で suffix alias が class 系 'FooAttribute' に
-                  -- 解決できている C# の raw '[Foo]' 行は落とす。
-                  AND NOT (
-                        snc.is_metadata = 1
-                    AND snc.is_attribute_alias = 0
-                    AND snc.source_lang = 'csharp'
-                    AND mrs.source_file_id IS NOT NULL
-                  )
-                  -- Metadata edges only survive when the target symbol resolves to
-                  -- a single class-like definition within scope; ambiguous cases
-                  -- (multiple same-name attribute / annotation classes) are dropped.
-                  -- metadata エッジは同名 class 系 target が 1 つだけのときのみ残す。
-                  AND (snc.is_metadata = 0 OR COALESCE(ta.class_like_target_count, 0) <= 1)
-                  -- Python names are file-local bindings. A cross-file edge is valid only
-                  -- when an import in the source file names the referenced symbol/module
-                  -- and that module owns the target path. This prevents ubiquitous names
-                  -- such as Path, main, json, and dataclass from joining every definition.
-                  -- Python の名前はファイルローカルな binding である。cross-file edge は
-                  -- source file の import が参照名/module を束縛し、その module が target
-                  -- path を所有する場合だけ残し、Path/main/json/dataclass の誤結合を防ぐ。
-                  AND (snc.source_lang != 'python' OR EXISTS (
-                        SELECT 1
-                        FROM symbols py_import
-                        WHERE py_import.file_id = snc.source_file_id
-                          AND py_import.kind = 'import'
-                          AND python_import_resolves(snc.source_path, tf.target_path, snc.symbol_name, snc.raw_reference_kind, snc.context, snc.column_number, " + pythonImportSignatureExpr + @")
-                  ))";
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "tf.symbol_name",
-            dependencySymbols,
-            dependencySymbolFamilies,
-            suppressDependencyNoise: false,
-            parameterPrefix: "edgeDependencyNames");
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "tf.symbol_name",
-            dependencySymbols: null,
-            dependencySymbolFamilies: null,
-            suppressDependencyNoise: suppressDependencyNoise,
-            parameterPrefix: "edgeDependencyNoise",
-            filterScopeSql: "NOT (snc.source_lang = 'markdown' AND tf.has_heading_kind = 1)");
-        sql += @"
-                UNION ALL
-                -- Resolve explicit Markdown links once per target file. Joining these
-                -- path references through target_files would multiply one link by every
-                -- heading or symbol declared in the destination document.
-                -- 明示的な Markdown link は target file ごとに一度だけ解決する。
-                -- target_files 経由で結合すると、1 link が宛先 document 内の全見出し
-                -- / symbol の件数だけ増幅されるため、file-level path として扱う。
-                SELECT snc.source_path,
-                       ptf.target_path,
-                       snc.raw_symbol_name,
-                       snc.ref_count,
-                       snc.source_lang,
-                       'markdown_explicit_link',
-                       snc.raw_reference_kind,
-                       'file'
-                FROM bounded_source_name_counts snc
-                JOIN path_target_files ptf
-                  ON ptf.target_path = markdown_resolve_path(snc.source_path, snc.symbol_name)
-                WHERE snc.source_lang = 'markdown'
-                  AND snc.logical_reference_kind = 'import'
-                  AND snc.source_path != ptf.target_path";
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "snc.raw_symbol_name",
-            dependencySymbols,
-            dependencySymbolFamilies,
-            suppressDependencyNoise: false,
-            parameterPrefix: "markdownPathDependency");
-        sql += @"
-                UNION ALL
-                -- Dockerfile stages are symbols within one file, so their dependency edge is
-                -- intentionally a self-file edge. Keep this exception stage-specific rather
-                -- than weakening the cross-file contract for other symbols or languages.
-                -- Dockerfile stage は同一ファイル内の symbol であるため、この依存 edge は
-                -- 意図的に self-file edge とする。他の symbol / 言語の cross-file 契約を
-                -- 緩めないよう stage に限定する。
-                SELECT snc.source_path,
-                       snc.source_path,
-                       snc.symbol_name,
-                       snc.ref_count,
-                       snc.source_lang,
-                       'docker_stage_reference',
-                       snc.raw_reference_kind,
-                       'stage'
-                FROM source_name_counts snc
-                JOIN files self_dst ON self_dst.id = snc.source_file_id
-                WHERE snc.source_lang = 'dockerfile'
-                  AND snc.raw_reference_kind = 'call'
-                  AND EXISTS (
-                        SELECT 1
-                        FROM symbols stage
-                        WHERE stage.file_id = snc.source_file_id
-                          AND stage.kind = 'stage'
-                          AND stage.name = snc.symbol_name COLLATE NOCASE
-                  )";
-        if (reverse && pathPatterns is { Count: > 0 })
-        {
-            var ors = new List<string>(pathPatterns.Count);
-            for (int i = 0; i < pathPatterns.Count; i++)
-                ors.Add(BuildPathFilterPredicate("self_dst", "pathPattern", i, pathPatterns[i]));
-            sql += " AND (" + string.Join(" OR ", ors) + ")";
-        }
-        if (reverse && excludePathPatterns is { Count: > 0 })
-        {
-            for (int i = 0; i < excludePathPatterns.Count; i++)
-                sql += $" AND NOT {BuildPathFilterPredicate("self_dst", "excludePath", i, excludePathPatterns[i])}";
-        }
-        if (reverse && excludeTests)
-            sql += $" AND NOT {DependencyTestPathCondition("self_dst.path")}";
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "snc.symbol_name",
-            dependencySymbols,
-            dependencySymbolFamilies,
-            suppressDependencyNoise,
-            "dockerDependency");
-        sql += @"
-                UNION ALL
-                SELECT snc.source_path,
-                       ptf.target_path,
-                       snc.symbol_name,
-                       snc.ref_count,
-                       snc.source_lang,
-                       'explicit_path_reference',
-                       snc.raw_reference_kind,
-                       'file'
-                FROM bounded_source_name_counts snc
-                JOIN path_target_files ptf
-                  ON ptf.target_path = markdown_resolve_path(snc.source_path, snc.symbol_name)
-                 WHERE snc.source_lang IN ('msbuild', 'solution')
-                  AND snc.logical_reference_kind IN ('import', 'project_reference')
-                  AND snc.source_path != ptf.target_path";
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "snc.symbol_name",
-            dependencySymbols,
-            dependencySymbolFamilies,
-            suppressDependencyNoise,
-            "pathDependency");
-        var dependencyReferenceOrderSql = suppressDependencyNoise
-            ? "retained_reference_count DESC, reference_count DESC, source_path, target_path"
-            : "reference_count DESC, source_path, target_path";
-        var finalDependencyReferenceOrderSql = suppressDependencyNoise
-            ? "limited_edge_totals.retained_reference_count DESC, limited_edge_totals.reference_count DESC, limited_edge_totals.source_path, limited_edge_totals.target_path"
-            : "limited_edge_totals.reference_count DESC, limited_edge_totals.source_path, limited_edge_totals.target_path";
-        var retainedDependencySymbolFilterSql = suppressDependencyNoise
-            ? " WHERE edges.origin <> 'markdown_heading_name_match'"
-            : string.Empty;
-        sql += @"
-            ),
-            edge_totals AS (
-                SELECT source_path,
-                       target_path,
-                       SUM(ref_count) AS reference_count,
-                       SUM(CASE WHEN origin = 'markdown_heading_name_match' THEN 0 ELSE ref_count END) AS retained_reference_count
-                FROM edges
-                GROUP BY source_path, target_path
-            ),
-            limited_edge_totals AS (
-                SELECT source_path,
-                       target_path,
-                       reference_count,
-                       retained_reference_count
-                FROM edge_totals
-                ORDER BY " + dependencyReferenceOrderSql + @"
-                LIMIT @limit
-            ),
-            edge_evidence_rows AS (
-                SELECT edges.source_path,
-                       edges.target_path,
-                       edges.source_lang,
-                       edges.origin,
-                       edges.raw_reference_kind,
-                       edges.target_kind,
-                       SUM(edges.ref_count) AS evidence_reference_count
-                FROM edges
-                JOIN limited_edge_totals
-                  ON limited_edge_totals.source_path = edges.source_path
-                 AND limited_edge_totals.target_path = edges.target_path
-                GROUP BY edges.source_path,
-                         edges.target_path,
-                         edges.source_lang,
-                         edges.origin,
-                         edges.raw_reference_kind,
-                         edges.target_kind
-            ),
-            ordered_edge_evidence AS (
-                SELECT source_path,
-                       target_path,
-                       source_lang || char(31) ||
-                       origin || char(31) ||
-                       raw_reference_kind || char(31) ||
-                       target_kind || char(31) ||
-                       evidence_reference_count AS evidence_item
-                FROM edge_evidence_rows
-                ORDER BY source_path, target_path, source_lang, origin, raw_reference_kind, target_kind
-            ),
-            edge_evidence_payloads AS (
-                SELECT source_path,
-                       target_path,
-                       GROUP_CONCAT(evidence_item, char(30)) AS evidence_payload
-                FROM ordered_edge_evidence
-                GROUP BY source_path, target_path
-            ),
-            distinct_edge_symbols AS (
-                SELECT DISTINCT edges.source_path,
-                                edges.target_path,
-                                edges.symbol_name
-                FROM edges
-                JOIN limited_edge_totals
-                  ON limited_edge_totals.source_path = edges.source_path
-                 AND limited_edge_totals.target_path = edges.target_path" + retainedDependencySymbolFilterSql + @"
-            ),
-            ranked_edge_symbols AS (
-                SELECT source_path,
-                       target_path,
-                       symbol_name,
-                       ROW_NUMBER() OVER (PARTITION BY source_path, target_path ORDER BY symbol_name) AS symbol_rank
-                FROM distinct_edge_symbols
-            )
-            SELECT limited_edge_totals.source_path,
-                   limited_edge_totals.target_path,
-                   limited_edge_totals.reference_count,
-                   COALESCE(GROUP_CONCAT(CASE WHEN ranked_edge_symbols.symbol_rank <= @symbolSampleLimit THEN ranked_edge_symbols.symbol_name END, char(31)), '') AS symbols,
-                   COALESCE(edge_evidence_payloads.evidence_payload, '') AS evidence_payload
-            FROM limited_edge_totals
-            LEFT JOIN ranked_edge_symbols
-              ON ranked_edge_symbols.source_path = limited_edge_totals.source_path
-             AND ranked_edge_symbols.target_path = limited_edge_totals.target_path
-            LEFT JOIN edge_evidence_payloads
-              ON edge_evidence_payloads.source_path = limited_edge_totals.source_path
-             AND edge_evidence_payloads.target_path = limited_edge_totals.target_path
-            GROUP BY limited_edge_totals.source_path,
-                     limited_edge_totals.target_path,
-                     limited_edge_totals.reference_count,
-                     edge_evidence_payloads.evidence_payload
-            ORDER BY " + finalDependencyReferenceOrderSql;
-
-        cmd.CommandText = sql;
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        if (pathPatterns is { Count: > 0 })
-            AddPathFilterParameterSet(cmd, "pathPattern", pathPatterns);
-        if (excludePathPatterns is { Count: > 0 })
-            AddPathFilterParameterSet(cmd, "excludePath", excludePathPatterns);
-        SqliteCommandPolicy.Add(cmd, "@limit", DependencyNoiseProfile.GetRankingCandidateLimit(limit));
-        if (lang == "csharp")
-            SqliteCommandPolicy.Add(cmd, "@sourceCandidateLimit", DependencyNoiseProfile.GetRankingCandidateLimit(limit));
-        SqliteCommandPolicy.Add(cmd, "@symbolSampleLimit", DependencySymbolSampleLimit);
-
-        var results = new List<FileDependencyResult>();
-        cancellationToken.ThrowIfCancellationRequested();
-        using var cancellationRegistration = cancellationToken.Register(static state => ((SqliteCommand)state!).Cancel(), cmd);
-        try
-        {
-            using var reader = cmd.ExecuteTrackedReader();
-            while (reader.TrackedRead())
-            {
-                cancellationToken.ThrowIfCancellationRequested();
-                var symbolSamples = ParseDependencySymbols(reader.GetString(3));
-                results.Add(new FileDependencyResult
-                {
-                    SourcePath = reader.GetString(0),
-                    TargetPath = reader.GetString(1),
-                    ReferenceCount = reader.GetInt32(2),
-                    SymbolSamples = symbolSamples,
-                    Symbols = string.Join(",", symbolSamples),
-                    Evidence = ParseDependencyEvidence(reader.GetString(4)),
-                });
-            }
-        }
-        catch (SqliteException) when (cancellationToken.IsCancellationRequested)
-        {
-            throw new OperationCanceledException(cancellationToken);
-        }
-        return RankDependencyResults(results, limit, suppressDependencyNoise);
-    }
-
-    internal static List<FileDependencyEvidence> ParseDependencyEvidence(string payload)
-    {
-        if (string.IsNullOrEmpty(payload))
-            return [];
 
-        var evidence = new List<FileDependencyEvidence>();
-        foreach (var item in payload.Split('\u001e', StringSplitOptions.RemoveEmptyEntries))
-        {
-            var fields = item.Split('\u001f');
-            if (fields.Length != 5 || !int.TryParse(fields[4], out var referenceCount))
-                continue;
-
-            evidence.Add(new FileDependencyEvidence
-            {
-                SourceLanguage = fields[0],
-                Origin = fields[1],
-                ReferenceKind = fields[2],
-                TargetKind = fields[3],
-                ReferenceCount = referenceCount,
-            });
-        }
-
-        return evidence;
-    }
-
-    internal static List<string> ParseDependencySymbols(string payload)
-        => string.IsNullOrEmpty(payload)
-            ? []
-            : payload.Split('\u001f', StringSplitOptions.RemoveEmptyEntries).ToList();
-
-    private static List<FileDependencyResult> RankDependencyResults(
-        List<FileDependencyResult> results,
-        int limit,
-        bool suppressDependencyNoise)
-    {
-        foreach (var result in results)
-        {
-            var rankingReferenceCount = suppressDependencyNoise && result.Evidence is { Count: > 0 }
-                ? result.Evidence
-                    .Where(static evidence => evidence.Origin != "markdown_heading_name_match")
-                    .Sum(static evidence => evidence.ReferenceCount)
-                : result.ReferenceCount;
-            result.RankingScore = result.SymbolSamples is { } symbolSamples
-                ? DependencyNoiseProfile.ComputeRankingScore(rankingReferenceCount, symbolSamples)
-                : DependencyNoiseProfile.ComputeRankingScore(rankingReferenceCount, result.Symbols);
-        }
-
-        return results
-            .OrderByDescending(result => result.RankingScore)
-            .ThenByDescending(result => result.ReferenceCount)
-            .ThenBy(result => result.SourcePath, StringComparer.Ordinal)
-            .ThenBy(result => result.TargetPath, StringComparer.Ordinal)
-            .Take(limit)
-            .ToList();
-    }
-
-    public List<FileDependencyResult> GetFileDependencyCycleCandidates(
-        int limit,
-        out int candidateRowCount,
-        string? lang = null,
-        IReadOnlyList<string>? pathPatterns = null,
-        IReadOnlyList<string>? excludePathPatterns = null,
-        bool excludeTests = false,
-        bool reverse = false,
-        CancellationToken cancellationToken = default,
-        IReadOnlyList<string>? dependencySymbols = null,
-        IReadOnlyList<string>? dependencySymbolFamilies = null,
-        bool suppressDependencyNoise = false)
-    {
-        candidateRowCount = 0;
-        lang = NormalizeQueryLanguage(lang);
-        if (!_hasReferencesTable || limit <= 0)
-            return [];
-
-        cancellationToken.ThrowIfCancellationRequested();
-        using var cmd = _conn.CreateCommand();
-        var constrainedAlias = reverse ? "dst" : "src";
-        var cycleMarkdownExplicitLinkSql = _referenceColumns.Contains("target_qualifier")
-            ? "(src.lang = 'markdown' AND r.reference_kind = 'reference' AND r.target_qualifier IS NOT NULL AND dst.path = markdown_resolve_path(src.path, r.target_qualifier))"
-            : "0 = 1";
-        var cycleNoiseEvidenceScopeSql =
-            "(" + cycleMarkdownExplicitLinkSql + " OR (src.lang = 'markdown' AND s.kind = 'heading'))";
-        var cycleCandidateOrderSql = suppressDependencyNoise
-            ? "retained_evidence DESC, source_path, target_path"
-            : "source_path, target_path";
-        var retainedCycleSymbolFilterSql = suppressDependencyNoise
-            ? " WHERE origin <> 'markdown_heading_name_match'"
-            : string.Empty;
-        var sql = @"
-            WITH candidate_edges AS (
-                SELECT src.path AS source_path,
-                       dst.path AS target_path,
-                       MAX(CASE
-                               WHEN src.lang = 'markdown'
-                                AND s.kind = 'heading'
-                                AND NOT " + cycleMarkdownExplicitLinkSql + @" THEN 0
-                               ELSE 1
-                           END) AS retained_evidence
-            FROM symbol_references r
-            JOIN files src ON r.file_id = src.id
-            JOIN symbols s ON s.name = r.symbol_name
-            JOIN files dst ON s.file_id = dst.id
-            WHERE src.path != dst.path
-              AND src.lang = dst.lang";
-        sql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "src", "depsCycleSourceLang")}";
-        sql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "dst", "depsCycleTargetLang")}";
-        AppendDependencyGeneratedFilter(ref sql, "src");
-        AppendDependencyGeneratedFilter(ref sql, "dst");
-        if (lang != null)
-            sql += " AND src.lang = @lang AND dst.lang = @lang";
-        if (pathPatterns is { Count: > 0 })
-        {
-            var ors = new List<string>(pathPatterns.Count);
-            for (int i = 0; i < pathPatterns.Count; i++)
-                ors.Add(BuildPathFilterPredicate(constrainedAlias, "pathPattern", i, pathPatterns[i]));
-            sql += " AND (" + string.Join(" OR ", ors) + ")";
-        }
-        if (excludePathPatterns is { Count: > 0 })
-        {
-            for (int i = 0; i < excludePathPatterns.Count; i++)
-                sql += $" AND NOT {BuildPathFilterPredicate(constrainedAlias, "excludePath", i, excludePathPatterns[i])}";
-        }
-        if (excludeTests)
-        {
-            sql += $" AND NOT {DependencyTestPathCondition("src.path")}";
-            sql += $" AND NOT {DependencyTestPathCondition("dst.path")}";
-        }
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "r.symbol_name",
+        var request = new DependencyQueryRequest(
+            limit,
+            lang,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            reverse,
             dependencySymbols,
             dependencySymbolFamilies,
-            suppressDependencyNoise: false,
-            parameterPrefix: "cycleDependencyNames");
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "r.symbol_name",
-            dependencySymbols: null,
-            dependencySymbolFamilies: null,
-            suppressDependencyNoise: suppressDependencyNoise,
-            parameterPrefix: "cycleDependencyNoise",
-            filterScopeSql: "NOT " + cycleNoiseEvidenceScopeSql);
-        sql += @"
-                GROUP BY src.path, dst.path
-                ORDER BY " + cycleCandidateOrderSql + @"
-                LIMIT @limit
-            ),
-            candidate_symbols AS (
-                SELECT candidate_edges.source_path,
-                       candidate_edges.target_path,
-                       r.id AS reference_id,
-                       r.symbol_name,
-                       src.lang AS source_lang,
-                       CASE
-                           WHEN " + cycleMarkdownExplicitLinkSql + @"
-                               THEN 'markdown_explicit_link'
-                           WHEN src.lang = 'markdown' AND s.kind = 'heading'
-                               THEN 'markdown_heading_name_match'
-                           ELSE 'symbol_name_match'
-                       END AS origin,
-                       r.reference_kind AS raw_reference_kind,
-                       CASE WHEN s.kind = 'heading' THEN 'heading' ELSE 'symbol' END AS target_kind
-                FROM candidate_edges
-                JOIN files src ON src.path = candidate_edges.source_path
-                JOIN symbol_references r ON r.file_id = src.id
-                JOIN symbols s ON s.name = r.symbol_name
-                JOIN files dst ON s.file_id = dst.id
-                 AND dst.path = candidate_edges.target_path
-                WHERE src.path != dst.path
-                  AND src.lang = dst.lang";
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "r.symbol_name",
-            dependencySymbols,
-            dependencySymbolFamilies,
-            suppressDependencyNoise: false,
-            parameterPrefix: "cycleAggregateNames");
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "r.symbol_name",
-            dependencySymbols: null,
-            dependencySymbolFamilies: null,
-            suppressDependencyNoise: suppressDependencyNoise,
-            parameterPrefix: "cycleAggregateNoise",
-            filterScopeSql: "NOT " + cycleNoiseEvidenceScopeSql);
-        sql += @"
-            ),
-            edge_reference_totals AS (
-                SELECT source_path,
-                       target_path,
-                       COUNT(DISTINCT reference_id) AS reference_count
-                FROM candidate_symbols
-                GROUP BY source_path, target_path
-            ),
-            edge_evidence_rows AS (
-                SELECT source_path,
-                       target_path,
-                       source_lang,
-                       origin,
-                       raw_reference_kind,
-                       target_kind,
-                       COUNT(DISTINCT reference_id) AS evidence_reference_count
-                FROM candidate_symbols
-                GROUP BY source_path,
-                         target_path,
-                         source_lang,
-                         origin,
-                         raw_reference_kind,
-                         target_kind
-            ),
-            ordered_edge_evidence AS (
-                SELECT source_path,
-                       target_path,
-                       source_lang || char(31) ||
-                       origin || char(31) ||
-                       raw_reference_kind || char(31) ||
-                       target_kind || char(31) ||
-                       evidence_reference_count AS evidence_item
-                FROM edge_evidence_rows
-                ORDER BY source_path, target_path, source_lang, origin, raw_reference_kind, target_kind
-            ),
-            edge_evidence_payloads AS (
-                SELECT source_path,
-                       target_path,
-                       GROUP_CONCAT(evidence_item, char(30)) AS evidence_payload
-                FROM ordered_edge_evidence
-                GROUP BY source_path, target_path
-            ),
-            distinct_edge_symbols AS (
-                SELECT DISTINCT source_path,
-                                target_path,
-                                symbol_name
-                FROM candidate_symbols" + retainedCycleSymbolFilterSql + @"
-            ),
-            ranked_edge_symbols AS (
-                SELECT source_path,
-                       target_path,
-                       symbol_name,
-                       ROW_NUMBER() OVER (PARTITION BY source_path, target_path ORDER BY symbol_name) AS symbol_rank
-                FROM distinct_edge_symbols
-            )
-            SELECT edge_reference_totals.source_path,
-                   edge_reference_totals.target_path,
-                   edge_reference_totals.reference_count,
-                   COALESCE(GROUP_CONCAT(CASE WHEN symbol_rank <= @symbolSampleLimit THEN symbol_name END, char(31)), '') AS symbols,
-                   COALESCE(edge_evidence_payloads.evidence_payload, '') AS evidence_payload
-            FROM edge_reference_totals
-            LEFT JOIN ranked_edge_symbols
-              ON ranked_edge_symbols.source_path = edge_reference_totals.source_path
-             AND ranked_edge_symbols.target_path = edge_reference_totals.target_path
-            LEFT JOIN edge_evidence_payloads
-              ON edge_evidence_payloads.source_path = edge_reference_totals.source_path
-             AND edge_evidence_payloads.target_path = edge_reference_totals.target_path
-            GROUP BY edge_reference_totals.source_path,
-                     edge_reference_totals.target_path,
-                     edge_reference_totals.reference_count,
-                     edge_evidence_payloads.evidence_payload
-            ORDER BY edge_reference_totals.source_path, edge_reference_totals.target_path";
-
-        cmd.CommandText = sql;
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        if (pathPatterns is { Count: > 0 })
-            AddPathFilterParameterSet(cmd, "pathPattern", pathPatterns);
-        if (excludePathPatterns is { Count: > 0 })
-            AddPathFilterParameterSet(cmd, "excludePath", excludePathPatterns);
-        SqliteCommandPolicy.Add(cmd, "@limit", limit);
-        SqliteCommandPolicy.Add(cmd, "@symbolSampleLimit", DependencySymbolSampleLimit);
-
-        var results = new List<FileDependencyResult>();
-        using var cancellationRegistration = cancellationToken.Register(static state => ((SqliteCommand)state!).Cancel(), cmd);
-        try
-        {
-            using var reader = cmd.ExecuteTrackedReader();
-            while (reader.TrackedRead())
-            {
-                cancellationToken.ThrowIfCancellationRequested();
-                candidateRowCount++;
-                var symbolSamples = ParseDependencySymbols(reader.GetString(3));
-                results.Add(new FileDependencyResult
-                {
-                    SourcePath = reader.GetString(0),
-                    TargetPath = reader.GetString(1),
-                    ReferenceCount = reader.GetInt32(2),
-                    RankingScore = reader.GetInt32(2),
-                    SymbolSamples = symbolSamples,
-                    Symbols = string.Join(",", symbolSamples),
-                    Evidence = ParseDependencyEvidence(reader.GetString(4)),
-                });
-            }
-        }
-        catch (SqliteException) when (cancellationToken.IsCancellationRequested)
-        {
-            throw new OperationCanceledException(cancellationToken);
-        }
-        return results;
-    }
-
-    internal static void AppendDependencySymbolFilter(
-        SqliteCommand cmd,
-        ref string sql,
-        string symbolSql,
-        IReadOnlyList<string>? dependencySymbols,
-        IReadOnlyList<string>? dependencySymbolFamilies,
-        bool suppressDependencyNoise,
-        string parameterPrefix,
-        string? filterScopeSql = null)
-    {
-        if (dependencySymbols is { Count: > 0 } || dependencySymbolFamilies is { Count: > 0 })
-        {
-            var predicates = new List<string>(
-                (dependencySymbols?.Count ?? 0) + (dependencySymbolFamilies?.Count ?? 0));
-            if (dependencySymbols != null)
-            {
-                for (var i = 0; i < dependencySymbols.Count; i++)
-                {
-                    var parameterName = $"@{parameterPrefix}Symbol{i}";
-                    predicates.Add($"({symbolSql}) = {parameterName}");
-                    SqliteCommandPolicy.Add(cmd, parameterName, dependencySymbols[i]);
-                }
-            }
-            if (dependencySymbolFamilies != null)
-            {
-                for (var i = 0; i < dependencySymbolFamilies.Count; i++)
-                {
-                    var parameterName = $"@{parameterPrefix}Family{i}";
-                    predicates.Add($"({symbolSql}) GLOB {parameterName}");
-                    SqliteCommandPolicy.Add(cmd, parameterName, EscapeSqliteGlobLiteral(dependencySymbolFamilies[i]) + "*");
-                }
-            }
-            AppendScopedDependencyPredicate(ref sql, "(" + string.Join(" OR ", predicates) + ")", filterScopeSql);
-        }
-
-        if (!suppressDependencyNoise)
-            return;
-
-        var noiseParameters = new List<string>(DependencyNoiseProfile.SymbolNames.Length);
-        for (var i = 0; i < DependencyNoiseProfile.SymbolNames.Length; i++)
-        {
-            var parameterName = $"@{parameterPrefix}Noise{i}";
-            noiseParameters.Add(parameterName);
-            SqliteCommandPolicy.Add(cmd, parameterName, DependencyNoiseProfile.SymbolNames[i]);
-        }
-        AppendScopedDependencyPredicate(
-            ref sql,
-            $"({symbolSql}) COLLATE NOCASE NOT IN ({string.Join(", ", noiseParameters)})",
-            filterScopeSql);
+            suppressDependencyNoise);
+        return ExecuteDependencyQuery(BuildDependencyQueryPlan(request), cancellationToken);
     }
 
-    private static void AppendScopedDependencyPredicate(ref string sql, string predicate, string? filterScopeSql)
-    {
-        sql += filterScopeSql == null
-            ? " AND " + predicate
-            : $" AND (NOT ({filterScopeSql}) OR {predicate})";
-    }
 
-    private static string EscapeSqliteGlobLiteral(string value)
-        => value
-            .Replace("[", "[[]", StringComparison.Ordinal)
-            .Replace("*", "[*]", StringComparison.Ordinal)
-            .Replace("?", "[?]", StringComparison.Ordinal);
-
-    private static string DependencyTestPathCondition(string pathSql)
-        => "(" + TestPathCondition.Replace("f.path", pathSql) + $" OR lower({pathSql}) LIKE '%.test%/%')";
 
     private void AppendDependencyGeneratedFilter(ref string sql, string fileAlias)
-    {
-        if (!IncludeGeneratedScope.Value && _fileColumns.Contains("generated"))
-            sql += $" AND COALESCE({fileAlias}.generated, 0) = 0";
-    }
+        => sql += BuildDependencyGeneratedFilter(fileAlias);
 }
diff --git a/src/CodeIndex/Database/DbReader.DependencyCycleQuery.cs b/src/CodeIndex/Database/DbReader.DependencyCycleQuery.cs
new file mode 100644
index 000000000..c7b82928e
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyCycleQuery.cs
@@ -0,0 +1,253 @@
+using CodeIndex.Models;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    public List<FileDependencyResult> GetFileDependencyCycleCandidates(
+        int limit,
+        out int candidateRowCount,
+        string? lang = null,
+        IReadOnlyList<string>? pathPatterns = null,
+        IReadOnlyList<string>? excludePathPatterns = null,
+        bool excludeTests = false,
+        bool reverse = false,
+        CancellationToken cancellationToken = default,
+        IReadOnlyList<string>? dependencySymbols = null,
+        IReadOnlyList<string>? dependencySymbolFamilies = null,
+        bool suppressDependencyNoise = false)
+    {
+        candidateRowCount = 0;
+        lang = NormalizeQueryLanguage(lang);
+        if (!_hasReferencesTable || limit <= 0)
+            return [];
+
+        cancellationToken.ThrowIfCancellationRequested();
+        using var cmd = _conn.CreateCommand();
+        var constrainedAlias = reverse ? "dst" : "src";
+        var cycleMarkdownExplicitLinkSql = _referenceColumns.Contains("target_qualifier")
+            ? "(src.lang = 'markdown' AND r.reference_kind = 'reference' AND r.target_qualifier IS NOT NULL AND dst.path = markdown_resolve_path(src.path, r.target_qualifier))"
+            : "0 = 1";
+        var cycleNoiseEvidenceScopeSql =
+            "(" + cycleMarkdownExplicitLinkSql + " OR (src.lang = 'markdown' AND s.kind = 'heading'))";
+        var cycleCandidateOrderSql = suppressDependencyNoise
+            ? "retained_evidence DESC, source_path, target_path"
+            : "source_path, target_path";
+        var retainedCycleSymbolFilterSql = suppressDependencyNoise
+            ? " WHERE origin <> 'markdown_heading_name_match'"
+            : string.Empty;
+        var sql = @"
+            WITH candidate_edges AS (
+                SELECT src.path AS source_path,
+                       dst.path AS target_path,
+                       MAX(CASE
+                               WHEN src.lang = 'markdown'
+                                AND s.kind = 'heading'
+                                AND NOT " + cycleMarkdownExplicitLinkSql + @" THEN 0
+                               ELSE 1
+                           END) AS retained_evidence
+            FROM symbol_references r
+            JOIN files src ON r.file_id = src.id
+            JOIN symbols s ON s.name = r.symbol_name
+            JOIN files dst ON s.file_id = dst.id
+            WHERE src.path != dst.path
+              AND src.lang = dst.lang";
+        sql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "src", "depsCycleSourceLang")}";
+        sql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "dst", "depsCycleTargetLang")}";
+        AppendDependencyGeneratedFilter(ref sql, "src");
+        AppendDependencyGeneratedFilter(ref sql, "dst");
+        if (lang != null)
+            sql += " AND src.lang = @lang AND dst.lang = @lang";
+        if (pathPatterns is { Count: > 0 })
+        {
+            var ors = new List<string>(pathPatterns.Count);
+            for (int i = 0; i < pathPatterns.Count; i++)
+                ors.Add(BuildPathFilterPredicate(constrainedAlias, "pathPattern", i, pathPatterns[i]));
+            sql += " AND (" + string.Join(" OR ", ors) + ")";
+        }
+        if (excludePathPatterns is { Count: > 0 })
+        {
+            for (int i = 0; i < excludePathPatterns.Count; i++)
+                sql += $" AND NOT {BuildPathFilterPredicate(constrainedAlias, "excludePath", i, excludePathPatterns[i])}";
+        }
+        if (excludeTests)
+        {
+            sql += $" AND NOT {DependencyTestPathCondition("src.path")}";
+            sql += $" AND NOT {DependencyTestPathCondition("dst.path")}";
+        }
+        AppendDependencySymbolFilter(
+            cmd,
+            ref sql,
+            "r.symbol_name",
+            dependencySymbols,
+            dependencySymbolFamilies,
+            suppressDependencyNoise: false,
+            parameterPrefix: "cycleDependencyNames");
+        AppendDependencySymbolFilter(
+            cmd,
+            ref sql,
+            "r.symbol_name",
+            dependencySymbols: null,
+            dependencySymbolFamilies: null,
+            suppressDependencyNoise: suppressDependencyNoise,
+            parameterPrefix: "cycleDependencyNoise",
+            filterScopeSql: "NOT " + cycleNoiseEvidenceScopeSql);
+        sql += @"
+                GROUP BY src.path, dst.path
+                ORDER BY " + cycleCandidateOrderSql + @"
+                LIMIT @limit
+            ),
+            candidate_symbols AS (
+                SELECT candidate_edges.source_path,
+                       candidate_edges.target_path,
+                       r.id AS reference_id,
+                       r.symbol_name,
+                       src.lang AS source_lang,
+                       CASE
+                           WHEN " + cycleMarkdownExplicitLinkSql + @"
+                               THEN 'markdown_explicit_link'
+                           WHEN src.lang = 'markdown' AND s.kind = 'heading'
+                               THEN 'markdown_heading_name_match'
+                           ELSE 'symbol_name_match'
+                       END AS origin,
+                       r.reference_kind AS raw_reference_kind,
+                       CASE WHEN s.kind = 'heading' THEN 'heading' ELSE 'symbol' END AS target_kind
+                FROM candidate_edges
+                JOIN files src ON src.path = candidate_edges.source_path
+                JOIN symbol_references r ON r.file_id = src.id
+                JOIN symbols s ON s.name = r.symbol_name
+                JOIN files dst ON s.file_id = dst.id
+                 AND dst.path = candidate_edges.target_path
+                WHERE src.path != dst.path
+                  AND src.lang = dst.lang";
+        AppendDependencySymbolFilter(
+            cmd,
+            ref sql,
+            "r.symbol_name",
+            dependencySymbols,
+            dependencySymbolFamilies,
+            suppressDependencyNoise: false,
+            parameterPrefix: "cycleAggregateNames");
+        AppendDependencySymbolFilter(
+            cmd,
+            ref sql,
+            "r.symbol_name",
+            dependencySymbols: null,
+            dependencySymbolFamilies: null,
+            suppressDependencyNoise: suppressDependencyNoise,
+            parameterPrefix: "cycleAggregateNoise",
+            filterScopeSql: "NOT " + cycleNoiseEvidenceScopeSql);
+        sql += @"
+            ),
+            edge_reference_totals AS (
+                SELECT source_path,
+                       target_path,
+                       COUNT(DISTINCT reference_id) AS reference_count
+                FROM candidate_symbols
+                GROUP BY source_path, target_path
+            ),
+            edge_evidence_rows AS (
+                SELECT source_path,
+                       target_path,
+                       source_lang,
+                       origin,
+                       raw_reference_kind,
+                       target_kind,
+                       COUNT(DISTINCT reference_id) AS evidence_reference_count
+                FROM candidate_symbols
+                GROUP BY source_path,
+                         target_path,
+                         source_lang,
+                         origin,
+                         raw_reference_kind,
+                         target_kind
+            ),
+            ordered_edge_evidence AS (
+                SELECT source_path,
+                       target_path,
+                       source_lang || char(31) ||
+                       origin || char(31) ||
+                       raw_reference_kind || char(31) ||
+                       target_kind || char(31) ||
+                       evidence_reference_count AS evidence_item
+                FROM edge_evidence_rows
+                ORDER BY source_path, target_path, source_lang, origin, raw_reference_kind, target_kind
+            ),
+            edge_evidence_payloads AS (
+                SELECT source_path,
+                       target_path,
+                       GROUP_CONCAT(evidence_item, char(30)) AS evidence_payload
+                FROM ordered_edge_evidence
+                GROUP BY source_path, target_path
+            ),
+            distinct_edge_symbols AS (
+                SELECT DISTINCT source_path,
+                                target_path,
+                                symbol_name
+                FROM candidate_symbols" + retainedCycleSymbolFilterSql + @"
+            ),
+            ranked_edge_symbols AS (
+                SELECT source_path,
+                       target_path,
+                       symbol_name,
+                       ROW_NUMBER() OVER (PARTITION BY source_path, target_path ORDER BY symbol_name) AS symbol_rank
+                FROM distinct_edge_symbols
+            )
+            SELECT edge_reference_totals.source_path,
+                   edge_reference_totals.target_path,
+                   edge_reference_totals.reference_count,
+                   COALESCE(GROUP_CONCAT(CASE WHEN symbol_rank <= @symbolSampleLimit THEN symbol_name END, char(31)), '') AS symbols,
+                   COALESCE(edge_evidence_payloads.evidence_payload, '') AS evidence_payload
+            FROM edge_reference_totals
+            LEFT JOIN ranked_edge_symbols
+              ON ranked_edge_symbols.source_path = edge_reference_totals.source_path
+             AND ranked_edge_symbols.target_path = edge_reference_totals.target_path
+            LEFT JOIN edge_evidence_payloads
+              ON edge_evidence_payloads.source_path = edge_reference_totals.source_path
+             AND edge_evidence_payloads.target_path = edge_reference_totals.target_path
+            GROUP BY edge_reference_totals.source_path,
+                     edge_reference_totals.target_path,
+                     edge_reference_totals.reference_count,
+                     edge_evidence_payloads.evidence_payload
+            ORDER BY edge_reference_totals.source_path, edge_reference_totals.target_path";
+
+        cmd.CommandText = sql;
+        if (lang != null)
+            SqliteCommandPolicy.Add(cmd, "@lang", lang);
+        if (pathPatterns is { Count: > 0 })
+            AddPathFilterParameterSet(cmd, "pathPattern", pathPatterns);
+        if (excludePathPatterns is { Count: > 0 })
+            AddPathFilterParameterSet(cmd, "excludePath", excludePathPatterns);
+        SqliteCommandPolicy.Add(cmd, "@limit", limit);
+        SqliteCommandPolicy.Add(cmd, "@symbolSampleLimit", DependencySymbolSampleLimit);
+
+        var results = new List<FileDependencyResult>();
+        using var cancellationRegistration = cancellationToken.Register(static state => ((SqliteCommand)state!).Cancel(), cmd);
+        try
+        {
+            using var reader = cmd.ExecuteTrackedReader();
+            while (reader.TrackedRead())
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                candidateRowCount++;
+                var symbolSamples = ParseDependencySymbols(reader.GetString(3));
+                results.Add(new FileDependencyResult
+                {
+                    SourcePath = reader.GetString(0),
+                    TargetPath = reader.GetString(1),
+                    ReferenceCount = reader.GetInt32(2),
+                    RankingScore = reader.GetInt32(2),
+                    SymbolSamples = symbolSamples,
+                    Symbols = string.Join(",", symbolSamples),
+                    Evidence = ParseDependencyEvidence(reader.GetString(4)),
+                });
+            }
+        }
+        catch (SqliteException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw new OperationCanceledException(cancellationToken);
+        }
+        return results;
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyEdgeSql.cs b/src/CodeIndex/Database/DbReader.DependencyEdgeSql.cs
new file mode 100644
index 000000000..a01c0c135
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyEdgeSql.cs
@@ -0,0 +1,121 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class DependencyEdgeSqlBuilder
+    {
+        private readonly DependencyQueryRequest _request;
+        private readonly DependencyQueryExpressions _expressions;
+        private readonly DependencySqlFragment _resolvedIdentity;
+        private readonly DependencySqlFragmentBuilder _sql = new();
+
+        internal DependencyEdgeSqlBuilder(
+            DependencyQueryRequest request,
+            DependencyQueryExpressions expressions,
+            DependencySqlFragment resolvedIdentity)
+        {
+            _request = request;
+            _expressions = expressions;
+            _resolvedIdentity = resolvedIdentity;
+        }
+
+        internal DependencySqlFragment Build()
+        {
+            AppendNameMatchedEdges();
+            AppendNameFilters();
+            return _sql.Build();
+        }
+
+        private void AppendNameMatchedEdges()
+        {
+            _sql.Append(@"
+            edges AS (
+                ");
+            _sql.Append(_resolvedIdentity.Sql);
+            _sql.Append(@"
+                SELECT snc.source_path,
+                       tf.target_path,
+                       tf.symbol_name,
+                       snc.ref_count,
+                       snc.source_lang,
+                       CASE
+                           WHEN snc.source_lang = 'markdown' AND tf.has_heading_kind = 1
+                               THEN 'markdown_heading_name_match'
+                           ELSE 'symbol_name_match'
+                       END AS origin,
+                       snc.raw_reference_kind,
+                       CASE WHEN tf.has_heading_kind = 1 THEN 'heading' ELSE 'symbol' END AS target_kind
+                FROM bounded_source_name_counts snc
+                JOIN target_files tf
+                  ON " + _expressions.SqlDependencyTargetMatch + @"
+                 AND tf.target_lang = snc.source_lang
+                LEFT JOIN metadata_raw_suppression mrs
+                  ON mrs.source_file_id = snc.source_file_id
+                 AND mrs.symbol_name = snc.symbol_name
+                LEFT JOIN target_ambiguity ta
+                  ON ta.target_lang = snc.source_lang
+                 AND ta.symbol_name = snc.symbol_name
+                 AND ta.symbol_segment_count = snc.symbol_segment_count
+                WHERE snc.source_path != tf.target_path
+                  AND " + _expressions.IdentityNameEdgePredicate + @"
+                  -- All metadata references ([Foo] / @Foo) and their synthetic C#
+                  -- suffix aliases must only match class-like target kinds; otherwise
+                  -- a metadata reference would spuriously depend on any file that
+                  -- merely defines a function / property / variable sharing the name.
+                  -- Non-metadata call-graph refs keep matching any kind so e.g. a
+                  -- constructor call can still tie back to a class definition.
+                  -- metadata 参照 ([Foo] / @Foo) と C# の合成 alias 行はいずれも
+                  -- class 系の target 種別にのみ一致させる。これを許すと同名の
+                  -- 関数/プロパティ/変数を持つだけのファイルまで誤って依存してしまう。
+                  -- 非 metadata の call-graph 参照は任意の kind に一致させて構わない
+                  -- (コンストラクタ呼び出しがクラス定義に結び付くケースなど)。
+                  AND (snc.is_metadata = 0 OR tf.has_metadata_target_kind = 1)
+                  -- Drop raw C# '[Foo]' rows when the suffix alias already resolves
+                  -- to a class-like 'FooAttribute' target in the same source file.
+                  -- 同じ source file で suffix alias が class 系 'FooAttribute' に
+                  -- 解決できている C# の raw '[Foo]' 行は落とす。
+                  AND NOT (
+                        snc.is_metadata = 1
+                    AND snc.is_attribute_alias = 0
+                    AND snc.source_lang = 'csharp'
+                    AND mrs.source_file_id IS NOT NULL
+                  )
+                  -- Metadata edges only survive when the target symbol resolves to
+                  -- a single class-like definition within scope; ambiguous cases
+                  -- (multiple same-name attribute / annotation classes) are dropped.
+                  -- metadata エッジは同名 class 系 target が 1 つだけのときのみ残す。
+                  AND (snc.is_metadata = 0 OR COALESCE(ta.class_like_target_count, 0) <= 1)
+                  -- Python names are file-local bindings. A cross-file edge is valid only
+                  -- when an import in the source file names the referenced symbol/module
+                  -- and that module owns the target path. This prevents ubiquitous names
+                  -- such as Path, main, json, and dataclass from joining every definition.
+                  -- Python の名前はファイルローカルな binding である。cross-file edge は
+                  -- source file の import が参照名/module を束縛し、その module が target
+                  -- path を所有する場合だけ残し、Path/main/json/dataclass の誤結合を防ぐ。
+                  AND (snc.source_lang != 'python' OR EXISTS (
+                        SELECT 1
+                        FROM symbols py_import
+                        WHERE py_import.file_id = snc.source_file_id
+                          AND py_import.kind = 'import'
+                          AND python_import_resolves(snc.source_path, tf.target_path, snc.symbol_name, snc.raw_reference_kind, snc.context, snc.column_number, " + _expressions.PythonImportSignature + @")
+                  ))");
+        }
+
+        private void AppendNameFilters()
+        {
+            _sql.Append(BuildDependencySymbolFilter(
+                "tf.symbol_name",
+                _request.DependencySymbols,
+                _request.DependencySymbolFamilies,
+                suppressDependencyNoise: false,
+                parameterPrefix: "edgeDependencyNames"));
+            _sql.Append(BuildDependencySymbolFilter(
+                "tf.symbol_name",
+                dependencySymbols: null,
+                dependencySymbolFamilies: null,
+                suppressDependencyNoise: _request.SuppressDependencyNoise,
+                parameterPrefix: "edgeDependencyNoise",
+                filterScopeSql: "NOT (snc.source_lang = 'markdown' AND tf.has_heading_kind = 1)"));
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyFinalSql.cs b/src/CodeIndex/Database/DbReader.DependencyFinalSql.cs
new file mode 100644
index 000000000..b023edf92
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyFinalSql.cs
@@ -0,0 +1,129 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private static DependencySqlFragment BuildDependencyFinalSql(DependencyQueryRequest request)
+    {
+        var sql = new DependencySqlFragmentBuilder();
+        AppendDependencyEdgeTotals(sql, request.SuppressDependencyNoise);
+        AppendDependencyEvidence(sql);
+        AppendDependencySymbolsAndSelect(sql, request.SuppressDependencyNoise);
+        return sql.Build();
+    }
+
+    private static void AppendDependencyEdgeTotals(
+        DependencySqlFragmentBuilder sql,
+        bool suppressDependencyNoise)
+    {
+        var orderSql = suppressDependencyNoise
+            ? "retained_reference_count DESC, reference_count DESC, source_path, target_path"
+            : "reference_count DESC, source_path, target_path";
+        sql.Append(@"
+            ),
+            edge_totals AS (
+                SELECT source_path,
+                       target_path,
+                       SUM(ref_count) AS reference_count,
+                       SUM(CASE WHEN origin = 'markdown_heading_name_match' THEN 0 ELSE ref_count END) AS retained_reference_count
+                FROM edges
+                GROUP BY source_path, target_path
+            ),
+            limited_edge_totals AS (
+                SELECT source_path,
+                       target_path,
+                       reference_count,
+                       retained_reference_count
+                FROM edge_totals
+                ORDER BY " + orderSql + @"
+                LIMIT @limit
+            ),");
+    }
+
+    private static void AppendDependencyEvidence(DependencySqlFragmentBuilder sql)
+    {
+        sql.Append(@"
+            edge_evidence_rows AS (
+                SELECT edges.source_path,
+                       edges.target_path,
+                       edges.source_lang,
+                       edges.origin,
+                       edges.raw_reference_kind,
+                       edges.target_kind,
+                       SUM(edges.ref_count) AS evidence_reference_count
+                FROM edges
+                JOIN limited_edge_totals
+                  ON limited_edge_totals.source_path = edges.source_path
+                 AND limited_edge_totals.target_path = edges.target_path
+                GROUP BY edges.source_path,
+                         edges.target_path,
+                         edges.source_lang,
+                         edges.origin,
+                         edges.raw_reference_kind,
+                         edges.target_kind
+            ),
+            ordered_edge_evidence AS (
+                SELECT source_path,
+                       target_path,
+                       source_lang || char(31) ||
+                       origin || char(31) ||
+                       raw_reference_kind || char(31) ||
+                       target_kind || char(31) ||
+                       evidence_reference_count AS evidence_item
+                FROM edge_evidence_rows
+                ORDER BY source_path, target_path, source_lang, origin, raw_reference_kind, target_kind
+            ),
+            edge_evidence_payloads AS (
+                SELECT source_path,
+                       target_path,
+                       GROUP_CONCAT(evidence_item, char(30)) AS evidence_payload
+                FROM ordered_edge_evidence
+                GROUP BY source_path, target_path
+            ),");
+    }
+
+    private static void AppendDependencySymbolsAndSelect(
+        DependencySqlFragmentBuilder sql,
+        bool suppressDependencyNoise)
+    {
+        var retainedFilterSql = suppressDependencyNoise
+            ? " WHERE edges.origin <> 'markdown_heading_name_match'"
+            : string.Empty;
+        var finalOrderSql = suppressDependencyNoise
+            ? "limited_edge_totals.retained_reference_count DESC, limited_edge_totals.reference_count DESC, limited_edge_totals.source_path, limited_edge_totals.target_path"
+            : "limited_edge_totals.reference_count DESC, limited_edge_totals.source_path, limited_edge_totals.target_path";
+        sql.Append(@"
+            distinct_edge_symbols AS (
+                SELECT DISTINCT edges.source_path,
+                                edges.target_path,
+                                edges.symbol_name
+                FROM edges
+                JOIN limited_edge_totals
+                  ON limited_edge_totals.source_path = edges.source_path
+                 AND limited_edge_totals.target_path = edges.target_path" + retainedFilterSql + @"
+            ),
+            ranked_edge_symbols AS (
+                SELECT source_path,
+                       target_path,
+                       symbol_name,
+                       ROW_NUMBER() OVER (PARTITION BY source_path, target_path ORDER BY symbol_name) AS symbol_rank
+                FROM distinct_edge_symbols
+            )
+            SELECT limited_edge_totals.source_path,
+                   limited_edge_totals.target_path,
+                   limited_edge_totals.reference_count,
+                   COALESCE(GROUP_CONCAT(CASE WHEN ranked_edge_symbols.symbol_rank <= @symbolSampleLimit THEN ranked_edge_symbols.symbol_name END, char(31)), '') AS symbols,
+                   COALESCE(edge_evidence_payloads.evidence_payload, '') AS evidence_payload
+            FROM limited_edge_totals
+            LEFT JOIN ranked_edge_symbols
+              ON ranked_edge_symbols.source_path = limited_edge_totals.source_path
+             AND ranked_edge_symbols.target_path = limited_edge_totals.target_path
+            LEFT JOIN edge_evidence_payloads
+              ON edge_evidence_payloads.source_path = limited_edge_totals.source_path
+             AND edge_evidence_payloads.target_path = limited_edge_totals.target_path
+            GROUP BY limited_edge_totals.source_path,
+                     limited_edge_totals.target_path,
+                     limited_edge_totals.reference_count,
+                     edge_evidence_payloads.evidence_payload
+            ORDER BY " + finalOrderSql);
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyProjection.cs b/src/CodeIndex/Database/DbReader.DependencyProjection.cs
new file mode 100644
index 000000000..cb733d9b2
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyProjection.cs
@@ -0,0 +1,77 @@
+using CodeIndex.Models;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private static FileDependencyResult ProjectDependencyRow(SqliteDataReader reader)
+    {
+        var symbolSamples = ParseDependencySymbols(reader.GetString(3));
+        return new FileDependencyResult
+        {
+            SourcePath = reader.GetString(0),
+            TargetPath = reader.GetString(1),
+            ReferenceCount = reader.GetInt32(2),
+            SymbolSamples = symbolSamples,
+            Symbols = string.Join(",", symbolSamples),
+            Evidence = ParseDependencyEvidence(reader.GetString(4)),
+        };
+    }
+
+    internal static List<FileDependencyEvidence> ParseDependencyEvidence(string payload)
+    {
+        if (string.IsNullOrEmpty(payload))
+            return [];
+
+        var evidence = new List<FileDependencyEvidence>();
+        foreach (var item in payload.Split('\u001e', StringSplitOptions.RemoveEmptyEntries))
+        {
+            var fields = item.Split('\u001f');
+            if (fields.Length != 5 || !int.TryParse(fields[4], out var referenceCount))
+                continue;
+
+            evidence.Add(new FileDependencyEvidence
+            {
+                SourceLanguage = fields[0],
+                Origin = fields[1],
+                ReferenceKind = fields[2],
+                TargetKind = fields[3],
+                ReferenceCount = referenceCount,
+            });
+        }
+
+        return evidence;
+    }
+
+    internal static List<string> ParseDependencySymbols(string payload)
+        => string.IsNullOrEmpty(payload)
+            ? []
+            : payload.Split('\u001f', StringSplitOptions.RemoveEmptyEntries).ToList();
+
+    private static List<FileDependencyResult> RankDependencyResults(
+        List<FileDependencyResult> results,
+        int limit,
+        bool suppressDependencyNoise)
+    {
+        foreach (var result in results)
+        {
+            var rankingReferenceCount = suppressDependencyNoise && result.Evidence is { Count: > 0 }
+                ? result.Evidence
+                    .Where(static evidence => evidence.Origin != "markdown_heading_name_match")
+                    .Sum(static evidence => evidence.ReferenceCount)
+                : result.ReferenceCount;
+            result.RankingScore = result.SymbolSamples is { } symbolSamples
+                ? DependencyNoiseProfile.ComputeRankingScore(rankingReferenceCount, symbolSamples)
+                : DependencyNoiseProfile.ComputeRankingScore(rankingReferenceCount, result.Symbols);
+        }
+
+        return results
+            .OrderByDescending(result => result.RankingScore)
+            .ThenByDescending(result => result.ReferenceCount)
+            .ThenBy(result => result.SourcePath, StringComparer.Ordinal)
+            .ThenBy(result => result.TargetPath, StringComparer.Ordinal)
+            .Take(limit)
+            .ToList();
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyQueryBinding.cs b/src/CodeIndex/Database/DbReader.DependencyQueryBinding.cs
new file mode 100644
index 000000000..53ceef54a
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyQueryBinding.cs
@@ -0,0 +1,179 @@
+using CodeIndex.Indexer;
+using CodeIndex.Models;
+using Microsoft.Data.Sqlite;
+using System.Text;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private DependencySqlFragment BuildDependencyGraphLanguagePredicate(string fileAlias, string parameterPrefix)
+    {
+        var supportedLanguages = GetWorkspaceSupportedReferenceLanguages()
+            .OrderBy(language => language, StringComparer.Ordinal)
+            .ToList();
+        if (supportedLanguages.Count == 0)
+            return new DependencySqlFragment("1 = 0", Array.Empty<DependencyQueryParameter>());
+
+        var parameters = new DependencyQueryParameter[supportedLanguages.Count];
+        for (var i = 0; i < supportedLanguages.Count; i++)
+        {
+            var parameterName = $"@{parameterPrefix}{i}";
+            parameters[i] = DependencyQueryParameter.Text(parameterName, supportedLanguages[i]);
+        }
+
+        return new DependencySqlFragment(
+            BuildGraphSupportedLanguagePredicateSql(supportedLanguages, fileAlias, parameterPrefix),
+            parameters);
+    }
+
+    private static DependencySqlFragment BuildDependencySymbolFilter(
+        string symbolSql,
+        IReadOnlyList<string>? dependencySymbols,
+        IReadOnlyList<string>? dependencySymbolFamilies,
+        bool suppressDependencyNoise,
+        string parameterPrefix,
+        string? filterScopeSql = null)
+    {
+        var sql = new StringBuilder();
+        var parameters = new List<DependencyQueryParameter>();
+        AppendRequestedDependencySymbols(
+            sql,
+            parameters,
+            symbolSql,
+            dependencySymbols,
+            dependencySymbolFamilies,
+            parameterPrefix,
+            filterScopeSql);
+        AppendDependencyNoiseFilter(
+            sql,
+            parameters,
+            symbolSql,
+            suppressDependencyNoise,
+            parameterPrefix,
+            filterScopeSql);
+        return new DependencySqlFragment(sql.ToString(), parameters.ToArray());
+    }
+
+    private static void AppendRequestedDependencySymbols(
+        StringBuilder sql,
+        List<DependencyQueryParameter> parameters,
+        string symbolSql,
+        IReadOnlyList<string>? dependencySymbols,
+        IReadOnlyList<string>? dependencySymbolFamilies,
+        string parameterPrefix,
+        string? filterScopeSql)
+    {
+        if (dependencySymbols is not { Count: > 0 } && dependencySymbolFamilies is not { Count: > 0 })
+            return;
+
+        var predicates = new List<string>((dependencySymbols?.Count ?? 0) + (dependencySymbolFamilies?.Count ?? 0));
+        if (dependencySymbols != null)
+        {
+            for (var i = 0; i < dependencySymbols.Count; i++)
+            {
+                var parameterName = $"@{parameterPrefix}Symbol{i}";
+                predicates.Add($"({symbolSql}) = {parameterName}");
+                parameters.Add(DependencyQueryParameter.Text(parameterName, dependencySymbols[i]));
+            }
+        }
+        if (dependencySymbolFamilies != null)
+        {
+            for (var i = 0; i < dependencySymbolFamilies.Count; i++)
+            {
+                var parameterName = $"@{parameterPrefix}Family{i}";
+                predicates.Add($"({symbolSql}) GLOB {parameterName}");
+                parameters.Add(DependencyQueryParameter.Text(
+                    parameterName,
+                    EscapeSqliteGlobLiteral(dependencySymbolFamilies[i]) + "*"));
+            }
+        }
+
+        AppendScopedDependencyPredicate(sql, "(" + string.Join(" OR ", predicates) + ")", filterScopeSql);
+    }
+
+    private static void AppendDependencyNoiseFilter(
+        StringBuilder sql,
+        List<DependencyQueryParameter> parameters,
+        string symbolSql,
+        bool suppressDependencyNoise,
+        string parameterPrefix,
+        string? filterScopeSql)
+    {
+        if (!suppressDependencyNoise)
+            return;
+
+        var parameterNames = new string[DependencyNoiseProfile.SymbolNames.Length];
+        for (var i = 0; i < DependencyNoiseProfile.SymbolNames.Length; i++)
+        {
+            var parameterName = $"@{parameterPrefix}Noise{i}";
+            parameterNames[i] = parameterName;
+            parameters.Add(DependencyQueryParameter.Text(parameterName, DependencyNoiseProfile.SymbolNames[i]));
+        }
+        AppendScopedDependencyPredicate(
+            sql,
+            $"({symbolSql}) COLLATE NOCASE NOT IN ({string.Join(", ", parameterNames)})",
+            filterScopeSql);
+    }
+
+    internal static void AppendDependencySymbolFilter(
+        SqliteCommand cmd,
+        ref string sql,
+        string symbolSql,
+        IReadOnlyList<string>? dependencySymbols,
+        IReadOnlyList<string>? dependencySymbolFamilies,
+        bool suppressDependencyNoise,
+        string parameterPrefix,
+        string? filterScopeSql = null)
+    {
+        var fragment = BuildDependencySymbolFilter(
+            symbolSql,
+            dependencySymbols,
+            dependencySymbolFamilies,
+            suppressDependencyNoise,
+            parameterPrefix,
+            filterScopeSql);
+        sql += fragment.Sql;
+        BindDependencyQueryParameters(cmd, fragment.Parameters);
+    }
+
+    private static void AppendScopedDependencyPredicate(StringBuilder sql, string predicate, string? filterScopeSql)
+        => sql.Append(filterScopeSql == null
+            ? " AND " + predicate
+            : $" AND (NOT ({filterScopeSql}) OR {predicate})");
+
+    private static void BindDependencyQueryParameters(
+        SqliteCommand command,
+        IReadOnlyList<DependencyQueryParameter> parameters)
+    {
+        for (var i = 0; i < parameters.Count; i++)
+        {
+            var parameter = parameters[i];
+            switch (parameter.Kind)
+            {
+                case DependencyQueryParameterKind.Text:
+                    SqliteCommandPolicy.Add(command, parameter.Name, parameter.TextValue!);
+                    break;
+                case DependencyQueryParameterKind.Int32:
+                    SqliteCommandPolicy.Add(command, parameter.Name, parameter.Int32Value);
+                    break;
+                default:
+                    throw new InvalidOperationException($"Unsupported dependency parameter kind: {parameter.Kind}");
+            }
+        }
+    }
+
+    private static string EscapeSqliteGlobLiteral(string value)
+        => value
+            .Replace("[", "[[]", StringComparison.Ordinal)
+            .Replace("*", "[*]", StringComparison.Ordinal)
+            .Replace("?", "[?]", StringComparison.Ordinal);
+
+    private static string DependencyTestPathCondition(string pathSql)
+        => "(" + TestPathCondition.Replace("f.path", pathSql) + $" OR lower({pathSql}) LIKE '%.test%/%')";
+
+    private string BuildDependencyGeneratedFilter(string fileAlias)
+        => !IncludeGeneratedScope.Value && _fileColumns.Contains("generated")
+            ? $" AND COALESCE({fileAlias}.generated, 0) = 0"
+            : string.Empty;
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyQueryExecution.cs b/src/CodeIndex/Database/DbReader.DependencyQueryExecution.cs
new file mode 100644
index 000000000..0b81bdc88
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyQueryExecution.cs
@@ -0,0 +1,40 @@
+using CodeIndex.Models;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private List<FileDependencyResult> ExecuteDependencyQuery(
+        DependencyQueryPlan plan,
+        CancellationToken cancellationToken)
+    {
+        using var command = _conn.CreateCommand();
+        command.CommandText = plan.Sql;
+        BindDependencyQueryParameters(command, plan.Parameters);
+
+        var results = new List<FileDependencyResult>();
+        cancellationToken.ThrowIfCancellationRequested();
+        using var cancellationRegistration = cancellationToken.Register(
+            static state => ((SqliteCommand)state!).Cancel(),
+            command);
+        try
+        {
+            using var reader = command.ExecuteTrackedReader();
+            while (reader.TrackedRead())
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                results.Add(ProjectDependencyRow(reader));
+            }
+        }
+        catch (SqliteException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw new OperationCanceledException(cancellationToken);
+        }
+
+        return RankDependencyResults(
+            results,
+            plan.Request.Limit,
+            plan.Request.SuppressDependencyNoise);
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyQueryPlan.cs b/src/CodeIndex/Database/DbReader.DependencyQueryPlan.cs
new file mode 100644
index 000000000..3ed618b56
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyQueryPlan.cs
@@ -0,0 +1,215 @@
+using CodeIndex.Indexer;
+using CodeIndex.Models;
+using System.Text;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed record DependencyQueryRequest(
+        int Limit,
+        string? Lang,
+        IReadOnlyList<string>? PathPatterns,
+        IReadOnlyList<string>? ExcludePathPatterns,
+        bool ExcludeTests,
+        bool Reverse,
+        IReadOnlyList<string>? DependencySymbols,
+        IReadOnlyList<string>? DependencySymbolFamilies,
+        bool SuppressDependencyNoise);
+
+    private sealed record DependencyQueryPlan(
+        DependencyQueryRequest Request,
+        string Sql,
+        IReadOnlyList<DependencyQueryParameter> Parameters);
+
+    private sealed record DependencySqlFragment(
+        string Sql,
+        IReadOnlyList<DependencyQueryParameter> Parameters)
+    {
+        internal static readonly DependencySqlFragment Empty = new(string.Empty, Array.Empty<DependencyQueryParameter>());
+    }
+
+    private enum DependencyQueryParameterKind
+    {
+        Text,
+        Int32,
+    }
+
+    private readonly record struct DependencyQueryParameter(
+        string Name,
+        DependencyQueryParameterKind Kind,
+        string? TextValue,
+        int Int32Value)
+    {
+        internal static DependencyQueryParameter Text(string name, string value)
+            => new(name, DependencyQueryParameterKind.Text, value, default);
+
+        internal static DependencyQueryParameter Int32(string name, int value)
+            => new(name, DependencyQueryParameterKind.Int32, null, value);
+    }
+
+    private sealed class DependencySqlFragmentBuilder
+    {
+        private readonly StringBuilder _sql = new();
+        private readonly List<DependencyQueryParameter> _parameters = [];
+
+        internal void Append(string sql) => _sql.Append(sql);
+
+        internal void Append(DependencySqlFragment fragment)
+        {
+            _sql.Append(fragment.Sql);
+            AddParameters(fragment.Parameters);
+        }
+
+        internal void AddParameters(IReadOnlyList<DependencyQueryParameter> parameters)
+        {
+            for (var i = 0; i < parameters.Count; i++)
+                _parameters.Add(parameters[i]);
+        }
+
+        internal void AddText(string name, string value)
+            => _parameters.Add(DependencyQueryParameter.Text(name, value));
+
+        internal void AddInt32(string name, int value)
+            => _parameters.Add(DependencyQueryParameter.Int32(name, value));
+
+        internal DependencySqlFragment Build()
+            => new(_sql.ToString(), _parameters.ToArray());
+    }
+
+    private sealed record DependencyQueryExpressions(
+        string ReferenceLineJoin,
+        string ContextSql,
+        string ReferenceIdSql,
+        string ScopedResolutionStateSql,
+        string IdentityScopedSql,
+        string IdentityNameEdgePredicate,
+        string TargetLogicalSymbolName,
+        string TargetLogicalSymbolSegmentCount,
+        string PythonImportMatchSignature,
+        string PythonImportSignature,
+        string SqlDependencyTargetMatch);
+
+    private DependencyQueryExpressions BuildDependencyQueryExpressions()
+    {
+        var identityScopeCondition = """
+            (
+                (src.lang = 'csharp' AND r.reference_kind NOT IN ('attribute', 'annotation'))
+                OR (src.lang = 'dependency_lock' AND r.reference_kind = 'dependency')
+            )
+            """;
+        var resolutionState = _referenceIdentityContractCurrent ? "r.resolution_state" : "NULL";
+        var pythonImportMatchSignature = GetSymbolColumnSql("signature", "NULL", "py_import_match");
+        var sqlDependencyTargetMatch = @"(
+                    (tf.target_lang != 'sql'
+                     AND NOT (snc.source_lang IN ('msbuild', 'solution') AND snc.logical_reference_kind IN ('import', 'project_reference'))
+                     AND NOT (snc.source_lang = 'markdown' AND snc.logical_reference_kind = 'import')
+                     AND NOT (snc.source_lang = 'markdown' AND snc.logical_reference_kind = 'reference')
+                     AND tf.symbol_name = snc.symbol_name)
+                 OR (snc.source_lang = 'python'
+                     AND tf.target_lang = 'python'
+                     AND EXISTS (
+                         SELECT 1 FROM symbols py_import_match
+                         WHERE py_import_match.file_id = snc.source_file_id
+                           AND py_import_match.kind = 'import'
+                           AND python_import_target_name(snc.source_path, snc.symbol_name, snc.context, snc.column_number, " + pythonImportMatchSignature + @") = tf.symbol_name
+                     ))
+                 OR (tf.target_lang = 'sql' AND (
+                        (tf.symbol_segment_count = snc.symbol_segment_count AND tf.symbol_name = snc.symbol_name COLLATE NOCASE)
+                     OR (sql_segment_count(snc.raw_symbol_name) = 1
+                         AND snc.allow_leaf_fallback = 1
+                         AND tf.symbol_segment_count > 1
+                         AND sql_leaf_name(tf.symbol_name) = snc.raw_symbol_name COLLATE NOCASE
+                         AND NOT EXISTS (
+                                SELECT 1
+                                FROM target_files tf_exact
+                                WHERE tf_exact.target_lang = tf.target_lang
+                                  AND tf_exact.symbol_segment_count = 1
+                                  AND tf_exact.symbol_name = snc.symbol_name COLLATE NOCASE
+                            )
+                         AND NOT EXISTS (
+                                SELECT 1
+                                FROM target_files tf_resolved
+                                WHERE tf_resolved.target_lang = tf.target_lang
+                                  AND tf_resolved.symbol_segment_count = snc.symbol_segment_count
+                                  AND tf_resolved.symbol_name = snc.symbol_name COLLATE NOCASE
+                            ))
+                 ))
+                )";
+
+        return new DependencyQueryExpressions(
+            ReferenceLineJoinSql("r"),
+            ReferenceContextSql("r"),
+            $"CASE WHEN {identityScopeCondition} THEN r.id ELSE 0 END",
+            $"CASE WHEN {identityScopeCondition} THEN {resolutionState} ELSE NULL END",
+            $"CASE WHEN {identityScopeCondition} THEN 1 ELSE 0 END",
+            _referenceIdentityContractCurrent ? "snc.identity_scoped = 0" : "snc.source_lang <> 'dependency_lock'",
+            BuildLogicalDependencySymbolNameExpr("dst", "s.name"),
+            BuildLogicalDependencySymbolSegmentCountExpr("dst", "s.name"),
+            pythonImportMatchSignature,
+            GetSymbolColumnSql("signature", "NULL", "py_import"),
+            sqlDependencyTargetMatch);
+    }
+
+    private DependencyQueryPlan BuildDependencyQueryPlan(DependencyQueryRequest request)
+    {
+        var expressions = BuildDependencyQueryExpressions();
+        var resolvedIdentity = BuildResolvedDependencyIdentitySql(request);
+        var source = new DependencySourceSqlBuilder(this, request, expressions).Build();
+        var sourceCandidate = new DependencySourceCandidateSqlBuilder(this, request, expressions).Build();
+        var target = new DependencyTargetSqlBuilder(this, request, expressions).Build();
+        var edge = new DependencyEdgeSqlBuilder(request, expressions, resolvedIdentity).Build();
+        var specialEdges = new DependencySpecialEdgeSqlBuilder(request).Build();
+        var final = BuildDependencyFinalSql(request);
+
+        var builder = new DependencySqlFragmentBuilder();
+        builder.Append(source.Sql);
+        builder.Append(sourceCandidate.Sql);
+        builder.Append(target.Sql);
+        builder.Append(edge.Sql);
+        builder.Append(specialEdges.Sql);
+        builder.Append(final.Sql);
+
+        // Preserve the historical binding order even though the resolved-identity
+        // fragment appears after the source/target CTEs in the final SQL text.
+        builder.AddParameters(resolvedIdentity.Parameters);
+        builder.AddParameters(source.Parameters);
+        builder.AddParameters(sourceCandidate.Parameters);
+        builder.AddParameters(target.Parameters);
+        builder.AddParameters(edge.Parameters);
+        builder.AddParameters(specialEdges.Parameters);
+        AppendDependencyTerminalParameters(builder, request);
+        var fragment = builder.Build();
+        return new DependencyQueryPlan(request, fragment.Sql, fragment.Parameters);
+    }
+
+    private static void AppendDependencyTerminalParameters(
+        DependencySqlFragmentBuilder builder,
+        DependencyQueryRequest request)
+    {
+        if (request.Lang != null)
+            builder.AddText("@lang", request.Lang);
+        AppendDependencyPathParameters(builder, "pathPattern", request.PathPatterns);
+        AppendDependencyPathParameters(builder, "excludePath", request.ExcludePathPatterns);
+        builder.AddInt32("@limit", DependencyNoiseProfile.GetRankingCandidateLimit(request.Limit));
+        if (request.Lang == "csharp")
+            builder.AddInt32("@sourceCandidateLimit", DependencyNoiseProfile.GetRankingCandidateLimit(request.Limit));
+        builder.AddInt32("@symbolSampleLimit", DependencySymbolSampleLimit);
+    }
+
+    private static void AppendDependencyPathParameters(
+        DependencySqlFragmentBuilder builder,
+        string parameterPrefix,
+        IReadOnlyList<string>? pathPatterns)
+    {
+        if (pathPatterns == null)
+            return;
+
+        for (var i = 0; i < pathPatterns.Count; i++)
+        {
+            builder.AddText(
+                SqliteDynamicSql.BuildParameterName(parameterPrefix, i),
+                BuildPathLikePattern(pathPatterns[i]));
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyResolvedIdentitySql.cs b/src/CodeIndex/Database/DbReader.DependencyResolvedIdentitySql.cs
new file mode 100644
index 000000000..12da16fa5
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyResolvedIdentitySql.cs
@@ -0,0 +1,55 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private DependencySqlFragment BuildResolvedDependencyIdentitySql(DependencyQueryRequest request)
+    {
+        if (!_referenceIdentityContractCurrent)
+            return DependencySqlFragment.Empty;
+
+        var builder = new DependencySqlFragmentBuilder();
+        builder.Append(@"
+                SELECT resolved.source_path,
+                       resolved.target_path,
+                       resolved.symbol_name,
+                       COUNT(*) AS ref_count,
+                       resolved.source_lang,
+                       'resolved_identity' AS origin,
+                       resolved.raw_reference_kind,
+                       resolved.target_kind
+                FROM (
+                    SELECT DISTINCT lrp.source_path,
+                           target_file.path AS target_path,
+                           lrp.symbol_name,
+                           lrp.reference_id,
+                           lrp.source_lang,
+                           lrp.raw_reference_kind,
+                           target.kind AS target_kind
+                    FROM logical_references_primary lrp
+                    JOIN symbol_reference_candidates candidate
+                      ON candidate.reference_id = lrp.reference_id
+                    JOIN symbols target ON target.id = candidate.symbol_id
+                    JOIN files target_file ON target_file.id = target.file_id
+                    JOIN target_files scoped_target
+                      ON scoped_target.target_path = target_file.path
+                     AND scoped_target.target_lang = target_file.lang
+                    WHERE lrp.identity_scoped = 1
+                      AND lrp.resolution_state IN ('resolved', 'resolved_group')
+                      AND lrp.source_path != target_file.path");
+        builder.Append(BuildDependencySymbolFilter(
+            "lrp.symbol_name",
+            request.DependencySymbols,
+            request.DependencySymbolFamilies,
+            request.SuppressDependencyNoise,
+            "resolvedDependency"));
+        var limitSql = request.Lang == "csharp" ? " LIMIT @sourceCandidateLimit" : string.Empty;
+        builder.Append(@"
+                     ORDER BY lrp.source_path, lrp.symbol_name, lrp.reference_id" + limitSql + @"
+                ) resolved
+                GROUP BY resolved.source_path, resolved.target_path, resolved.symbol_name,
+                         resolved.source_lang, resolved.raw_reference_kind, resolved.target_kind
+                UNION ALL
+                ");
+        return builder.Build();
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencySourceCandidateSql.cs b/src/CodeIndex/Database/DbReader.DependencySourceCandidateSql.cs
new file mode 100644
index 000000000..89f540756
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencySourceCandidateSql.cs
@@ -0,0 +1,86 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class DependencySourceCandidateSqlBuilder
+    {
+        private readonly DbReader _reader;
+        private readonly DependencyQueryRequest _request;
+        private readonly DependencyQueryExpressions _expressions;
+
+        internal DependencySourceCandidateSqlBuilder(
+            DbReader reader,
+            DependencyQueryRequest request,
+            DependencyQueryExpressions expressions)
+        {
+            _reader = reader;
+            _request = request;
+            _expressions = expressions;
+        }
+
+        internal DependencySqlFragment Build()
+            => _request.Lang == "csharp" ? BuildBoundedCSharpSource() : BuildUnboundedSource();
+
+        private DependencySqlFragment BuildBoundedCSharpSource()
+        {
+            var sql = new DependencySqlFragmentBuilder();
+            sql.Append(@",
+            csharp_dependency_targets AS (
+                SELECT dst.path AS target_path,
+                       " + _expressions.TargetLogicalSymbolName + @" AS symbol_name,
+                       MAX(CASE WHEN " + _reader.BuildMetadataTargetKindExpr("dst") + @" THEN 1 ELSE 0 END) AS has_metadata_target_kind
+                FROM symbols s
+                JOIN files dst ON s.file_id = dst.id
+                WHERE dst.lang = 'csharp'");
+            sql.Append(_reader.BuildDependencyGeneratedFilter("dst"));
+            AppendReverseTargetScope(sql);
+            sql.Append(BuildDependencySymbolFilter(
+                _expressions.TargetLogicalSymbolName,
+                _request.DependencySymbols,
+                _request.DependencySymbolFamilies,
+                _request.SuppressDependencyNoise,
+                "boundedTargetDependency"));
+            sql.Append(@"
+                GROUP BY dst.path, " + _expressions.TargetLogicalSymbolName + @"
+            ),
+            bounded_source_name_counts AS (
+                SELECT snc.*
+                FROM source_name_counts snc
+                WHERE EXISTS (
+                    SELECT 1
+                    FROM csharp_dependency_targets tf
+                    WHERE tf.symbol_name = snc.symbol_name
+                      AND tf.target_path != snc.source_path
+                      AND (snc.is_metadata = 0 OR tf.has_metadata_target_kind = 1)
+                )
+                ORDER BY snc.ref_count DESC, snc.source_path, snc.symbol_name, snc.context, snc.column_number, snc.raw_reference_kind
+                LIMIT @sourceCandidateLimit
+            ),");
+            return sql.Build();
+        }
+
+        private void AppendReverseTargetScope(DependencySqlFragmentBuilder sql)
+        {
+            if (_request.Reverse && _request.PathPatterns is { Count: > 0 })
+            {
+                var predicates = new List<string>(_request.PathPatterns.Count);
+                for (var i = 0; i < _request.PathPatterns.Count; i++)
+                    predicates.Add(BuildPathFilterPredicate("dst", "pathPattern", i, _request.PathPatterns[i]));
+                sql.Append(" AND (" + string.Join(" OR ", predicates) + ")");
+            }
+            if (_request.Reverse && _request.ExcludePathPatterns is { Count: > 0 })
+            {
+                for (var i = 0; i < _request.ExcludePathPatterns.Count; i++)
+                    sql.Append($" AND NOT {BuildPathFilterPredicate("dst", "excludePath", i, _request.ExcludePathPatterns[i])}");
+            }
+            if (_request.ExcludeTests)
+                sql.Append($" AND NOT {DependencyTestPathCondition("dst.path")}");
+        }
+
+        private static DependencySqlFragment BuildUnboundedSource()
+            => new(@",
+            bounded_source_name_counts AS (
+                SELECT * FROM source_name_counts
+            ),", Array.Empty<DependencyQueryParameter>());
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencySourceSql.cs b/src/CodeIndex/Database/DbReader.DependencySourceSql.cs
new file mode 100644
index 000000000..40280bd9a
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencySourceSql.cs
@@ -0,0 +1,161 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class DependencySourceSqlBuilder
+    {
+        private const string SourceAlias = "src";
+
+        private readonly DbReader _reader;
+        private readonly DependencyQueryRequest _request;
+        private readonly DependencyQueryExpressions _expressions;
+        private readonly DependencySqlFragmentBuilder _sql = new();
+
+        internal DependencySourceSqlBuilder(
+            DbReader reader,
+            DependencyQueryRequest request,
+            DependencyQueryExpressions expressions)
+        {
+            _reader = reader;
+            _request = request;
+            _expressions = expressions;
+        }
+
+        internal DependencySqlFragment Build()
+        {
+            AppendPrimaryReferences();
+            AppendSourceScope();
+            AppendLogicalReferences();
+            AppendSourceNameCounts();
+            return _sql.Build();
+        }
+
+        private void AppendPrimaryReferences()
+        {
+            _sql.Append(@"
+            WITH logical_references_primary AS (
+                SELECT src.id AS source_file_id,
+                       src.path AS source_path,
+                       src.lang AS source_lang,
+                       " + _expressions.ReferenceIdSql + @" AS reference_id,
+                       " + _expressions.ScopedResolutionStateSql + @" AS resolution_state,
+                       " + _expressions.IdentityScopedSql + @" AS identity_scoped,
+                       r.symbol_name,
+                       " + _expressions.ContextSql + @" AS context,
+                       r.container_name,
+                       r.line,
+                       r.column_number,
+                       r.reference_kind AS raw_reference_kind,
+                       " + GetLogicalReferenceKindSql("r.reference_kind") + @" AS logical_reference_kind
+                FROM symbol_references r
+                JOIN files src ON r.file_id = src.id" + _expressions.ReferenceLineJoin + @"
+                WHERE 1 = 1");
+            var languagePredicate = _reader.BuildDependencyGraphLanguagePredicate(SourceAlias, "depsLang");
+            _sql.Append(" AND " + languagePredicate.Sql);
+            _sql.AddParameters(languagePredicate.Parameters);
+            _sql.Append(_reader.BuildDependencyGeneratedFilter(SourceAlias));
+        }
+
+        private void AppendSourceScope()
+        {
+            if (_request.Lang != null)
+                _sql.Append(" AND src.lang = @lang");
+            if (!_request.Reverse && _request.PathPatterns is { Count: > 0 })
+            {
+                var predicates = new List<string>(_request.PathPatterns.Count);
+                for (var i = 0; i < _request.PathPatterns.Count; i++)
+                    predicates.Add(BuildPathFilterPredicate(SourceAlias, "pathPattern", i, _request.PathPatterns[i]));
+                _sql.Append(" AND (" + string.Join(" OR ", predicates) + ")");
+            }
+            if (!_request.Reverse && _request.ExcludePathPatterns is { Count: > 0 })
+            {
+                for (var i = 0; i < _request.ExcludePathPatterns.Count; i++)
+                    _sql.Append($" AND NOT {BuildPathFilterPredicate(SourceAlias, "excludePath", i, _request.ExcludePathPatterns[i])}");
+            }
+            if (_request.ExcludeTests)
+                _sql.Append($" AND NOT {DependencyTestPathCondition($"{SourceAlias}.path")}");
+        }
+
+        private void AppendLogicalReferences()
+        {
+            _sql.Append(@"
+                GROUP BY src.id, src.path, src.lang, " + _expressions.ReferenceIdSql + @", " + _expressions.ScopedResolutionStateSql + @", " + _expressions.IdentityScopedSql + @", r.symbol_name, " + _expressions.ContextSql + @", r.container_name, r.line, r.column_number, r.reference_kind, logical_reference_kind
+            ),
+            logical_references AS (
+                SELECT source_file_id, source_path, source_lang, reference_id, identity_scoped,
+                       " + BuildLogicalReferenceNameExpr("source_lang", "symbol_name", "context", "container_name", "column_number") + @" AS symbol_name,
+                       " + BuildLogicalReferenceSegmentCountExpr("source_lang", "symbol_name", "context", "container_name", "column_number") + @" AS symbol_segment_count,
+                       " + BuildLogicalReferenceLeafFallbackAllowedExpr("source_lang", "symbol_name", "context", "container_name", "column_number") + @" AS allow_leaf_fallback,
+                       symbol_name AS raw_symbol_name,
+                       context, line, column_number, raw_reference_kind, logical_reference_kind,
+                       0 AS is_attribute_alias,
+                       CASE WHEN logical_reference_kind IN ('attribute', 'annotation') THEN 1 ELSE 0 END AS is_metadata
+                FROM logical_references_primary
+                UNION ALL
+                -- C# attribute suffix alias: [Foo] in source is stored with symbol_name='Foo',
+                -- but the defining class is named 'FooAttribute'. Emit the canonical 'Foo' + 'Attribute'
+                -- form so deps can match the class file as a target. The alias rows are flagged
+                -- so the edges CTE can restrict them to class-like targets and avoid spurious
+                -- edges to unrelated functions / properties that happen to be named 'FooAttribute'.
+                -- C# 属性のサフィックス別名: ソース上の [Foo] は symbol_name='Foo' で保存されるが、
+                -- 定義クラスは 'FooAttribute' 命名になるため、正規形 'Foo' + 'Attribute' を補って
+                -- deps がクラス側のファイルを target として join できるようにする。alias 行には
+                -- フラグを付け、edges CTE 側で class-like target だけに限定する。これにより、
+                -- 偶然 'FooAttribute' という名前を持つ関数やプロパティへの誤ったエッジを防ぐ。
+                SELECT source_file_id, source_path, source_lang, reference_id, identity_scoped,
+                       symbol_name || 'Attribute' AS symbol_name,
+                       1 AS symbol_segment_count,
+                       0 AS allow_leaf_fallback,
+                       symbol_name || 'Attribute' AS raw_symbol_name,
+                       context, line, column_number, raw_reference_kind, logical_reference_kind,
+                       1 AS is_attribute_alias,
+                       1 AS is_metadata
+                FROM logical_references_primary
+                WHERE source_lang = 'csharp'
+                  AND logical_reference_kind = 'attribute'
+                  AND symbol_name NOT LIKE '%Attribute'
+            ),");
+        }
+
+        private void AppendSourceNameCounts()
+        {
+            _sql.Append(@"
+            source_name_counts AS (
+                -- Grouping includes is_metadata so metadata-only groups ([Foo] / @Foo)
+                -- can be restricted to class-like targets independently from non-metadata
+                -- call-graph groups that share the same symbol_name in the same file
+                -- (e.g. `Foo()` call + `[Foo]` attribute both present in the same source).
+                -- is_metadata を GROUP BY に含めることで、同じ source file / symbol_name を
+                -- 共有する metadata 行と call-graph 行 (例: 同じファイル内の `Foo()` 呼び出し
+                -- と `[Foo]` 属性) を別グループとして扱い、metadata 側だけに class-like
+                -- target 制限を掛けられるようにする。
+                SELECT source_file_id,
+                       source_path,
+                       source_lang,
+                       identity_scoped,
+                       symbol_name,
+                       symbol_segment_count,
+                       allow_leaf_fallback,
+                       raw_symbol_name,
+                       context,
+                       column_number,
+                       raw_reference_kind,
+                       logical_reference_kind,
+                       is_attribute_alias,
+                       is_metadata,
+                       COUNT(*) AS ref_count
+                FROM logical_references
+                WHERE 1 = 1");
+            _sql.Append(BuildDependencySymbolFilter(
+                "symbol_name",
+                _request.DependencySymbols,
+                _request.DependencySymbolFamilies,
+                _request.SuppressDependencyNoise,
+                "sourceDependency",
+                "source_lang = 'csharp'"));
+            _sql.Append(@"
+                GROUP BY source_file_id, source_path, source_lang, identity_scoped, symbol_name, symbol_segment_count, allow_leaf_fallback, raw_symbol_name, context, column_number, raw_reference_kind, logical_reference_kind, is_attribute_alias, is_metadata
+            )");
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencySpecialEdgeSql.cs b/src/CodeIndex/Database/DbReader.DependencySpecialEdgeSql.cs
new file mode 100644
index 000000000..f59ec7e68
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencySpecialEdgeSql.cs
@@ -0,0 +1,137 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class DependencySpecialEdgeSqlBuilder
+    {
+        private readonly DependencyQueryRequest _request;
+        private readonly DependencySqlFragmentBuilder _sql = new();
+
+        internal DependencySpecialEdgeSqlBuilder(DependencyQueryRequest request)
+        {
+            _request = request;
+        }
+
+        internal DependencySqlFragment Build()
+        {
+            AppendMarkdownEdges();
+            AppendDockerEdges();
+            AppendProjectPathEdges();
+            return _sql.Build();
+        }
+
+        private void AppendMarkdownEdges()
+        {
+            _sql.Append(@"
+                UNION ALL
+                -- Resolve explicit Markdown links once per target file. Joining these
+                -- path references through target_files would multiply one link by every
+                -- heading or symbol declared in the destination document.
+                -- 明示的な Markdown link は target file ごとに一度だけ解決する。
+                -- target_files 経由で結合すると、1 link が宛先 document 内の全見出し
+                -- / symbol の件数だけ増幅されるため、file-level path として扱う。
+                SELECT snc.source_path,
+                       ptf.target_path,
+                       snc.raw_symbol_name,
+                       snc.ref_count,
+                       snc.source_lang,
+                       'markdown_explicit_link',
+                       snc.raw_reference_kind,
+                       'file'
+                FROM bounded_source_name_counts snc
+                JOIN path_target_files ptf
+                  ON ptf.target_path = markdown_resolve_path(snc.source_path, snc.symbol_name)
+                WHERE snc.source_lang = 'markdown'
+                  AND snc.logical_reference_kind = 'import'
+                  AND snc.source_path != ptf.target_path");
+            _sql.Append(BuildDependencySymbolFilter(
+                "snc.raw_symbol_name",
+                _request.DependencySymbols,
+                _request.DependencySymbolFamilies,
+                suppressDependencyNoise: false,
+                parameterPrefix: "markdownPathDependency"));
+        }
+
+        private void AppendDockerEdges()
+        {
+            _sql.Append(@"
+                UNION ALL
+                -- Dockerfile stages are symbols within one file, so their dependency edge is
+                -- intentionally a self-file edge. Keep this exception stage-specific rather
+                -- than weakening the cross-file contract for other symbols or languages.
+                -- Dockerfile stage は同一ファイル内の symbol であるため、この依存 edge は
+                -- 意図的に self-file edge とする。他の symbol / 言語の cross-file 契約を
+                -- 緩めないよう stage に限定する。
+                SELECT snc.source_path,
+                       snc.source_path,
+                       snc.symbol_name,
+                       snc.ref_count,
+                       snc.source_lang,
+                       'docker_stage_reference',
+                       snc.raw_reference_kind,
+                       'stage'
+                FROM source_name_counts snc
+                JOIN files self_dst ON self_dst.id = snc.source_file_id
+                WHERE snc.source_lang = 'dockerfile'
+                  AND snc.raw_reference_kind = 'call'
+                  AND EXISTS (
+                        SELECT 1
+                        FROM symbols stage
+                        WHERE stage.file_id = snc.source_file_id
+                          AND stage.kind = 'stage'
+                          AND stage.name = snc.symbol_name COLLATE NOCASE
+                  )");
+            AppendReverseDockerScope();
+            _sql.Append(BuildDependencySymbolFilter(
+                "snc.symbol_name",
+                _request.DependencySymbols,
+                _request.DependencySymbolFamilies,
+                _request.SuppressDependencyNoise,
+                "dockerDependency"));
+        }
+
+        private void AppendReverseDockerScope()
+        {
+            if (_request.Reverse && _request.PathPatterns is { Count: > 0 })
+            {
+                var predicates = new List<string>(_request.PathPatterns.Count);
+                for (var i = 0; i < _request.PathPatterns.Count; i++)
+                    predicates.Add(BuildPathFilterPredicate("self_dst", "pathPattern", i, _request.PathPatterns[i]));
+                _sql.Append(" AND (" + string.Join(" OR ", predicates) + ")");
+            }
+            if (_request.Reverse && _request.ExcludePathPatterns is { Count: > 0 })
+            {
+                for (var i = 0; i < _request.ExcludePathPatterns.Count; i++)
+                    _sql.Append($" AND NOT {BuildPathFilterPredicate("self_dst", "excludePath", i, _request.ExcludePathPatterns[i])}");
+            }
+            if (_request.Reverse && _request.ExcludeTests)
+                _sql.Append($" AND NOT {DependencyTestPathCondition("self_dst.path")}");
+        }
+
+        private void AppendProjectPathEdges()
+        {
+            _sql.Append(@"
+                UNION ALL
+                SELECT snc.source_path,
+                       ptf.target_path,
+                       snc.symbol_name,
+                       snc.ref_count,
+                       snc.source_lang,
+                       'explicit_path_reference',
+                       snc.raw_reference_kind,
+                       'file'
+                FROM bounded_source_name_counts snc
+                JOIN path_target_files ptf
+                  ON ptf.target_path = markdown_resolve_path(snc.source_path, snc.symbol_name)
+                 WHERE snc.source_lang IN ('msbuild', 'solution')
+                  AND snc.logical_reference_kind IN ('import', 'project_reference')
+                  AND snc.source_path != ptf.target_path");
+            _sql.Append(BuildDependencySymbolFilter(
+                "snc.symbol_name",
+                _request.DependencySymbols,
+                _request.DependencySymbolFamilies,
+                _request.SuppressDependencyNoise,
+                "pathDependency"));
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyTargetSql.cs b/src/CodeIndex/Database/DbReader.DependencyTargetSql.cs
new file mode 100644
index 000000000..9498e0f95
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyTargetSql.cs
@@ -0,0 +1,179 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class DependencyTargetSqlBuilder
+    {
+        private const string TargetAlias = "dst";
+
+        private readonly DbReader _reader;
+        private readonly DependencyQueryRequest _request;
+        private readonly DependencyQueryExpressions _expressions;
+        private readonly DependencySqlFragmentBuilder _sql = new();
+
+        internal DependencyTargetSqlBuilder(
+            DbReader reader,
+            DependencyQueryRequest request,
+            DependencyQueryExpressions expressions)
+        {
+            _reader = reader;
+            _request = request;
+            _expressions = expressions;
+        }
+
+        internal DependencySqlFragment Build()
+        {
+            AppendTargetFiles();
+            AppendTargetScope();
+            AppendTargetMetadataQueries();
+            return _sql.Build();
+        }
+
+        private void AppendTargetFiles()
+        {
+            _sql.Append(@"
+            target_files AS (
+                -- Collapse per-symbol rows to one per (target_path, target_lang, symbol_name)
+                -- and remember whether any of the same-name symbols is a class-like kind
+                -- via MAX. Keeping kind in DISTINCT would split identical (path, lang, name)
+                -- rows when one file defines both a class and a same-name function (e.g. a
+                -- C# constructor), inflating the deps reference count.
+                -- (target_path, target_lang, symbol_name) 単位に集約し、同名のシンボルの
+                -- いずれかが class 系であるかを MAX で覚える。kind を DISTINCT に含めると、
+                -- 同じ (path, lang, name) でも class と同名 function (C# のコンストラクタ等)
+                -- が別行として残り、deps の参照カウントが膨らんでしまう。
+                -- has_metadata_target_kind further narrows the class-like set to targets
+                -- that can legitimately be referenced as [Attribute] metadata. For C#
+                -- we cannot resolve base types transitively at SQL time, so the best
+                -- portable approximation is an inheritance-clause check: any class
+                -- declared with a base list is a potential attribute type (direct or
+                -- indirect Attribute derivation). A plain class FooAttribute with no
+                -- base clause is not a valid [Foo] target at compile time.
+                -- Other languages keep the original class-like breadth. Legacy DBs
+                -- without a signature column degrade to the broad class-like set.
+                -- has_metadata_target_kind は [Attribute] metadata target として妥当な
+                -- class-like のみに絞る。C# は SQL 時点で基底型を遡れないため、継承節を
+                -- 持つクラスを候補とする近似を採る(直接・間接の Attribute 継承を
+                -- 取りこぼさない)。他言語は class-like 全体を残す。signature 列が無い
+                -- legacy DB では filter を無効化し class-like 全体に戻る。
+                SELECT dst.path AS target_path,
+                       dst.lang AS target_lang,
+                       " + _expressions.TargetLogicalSymbolName + @" AS symbol_name,
+                       " + _expressions.TargetLogicalSymbolSegmentCount + @" AS symbol_segment_count,
+                       MAX(CASE WHEN s.kind IN ('class','struct','interface') THEN 1 ELSE 0 END) AS has_class_like_kind,
+                       MAX(CASE WHEN s.kind = 'heading' THEN 1 ELSE 0 END) AS has_heading_kind,
+                       MAX(CASE WHEN " + _reader.BuildMetadataTargetKindExpr(TargetAlias) + @"
+                                THEN 1 ELSE 0 END) AS has_metadata_target_kind
+                FROM symbols s
+                JOIN files dst ON s.file_id = dst.id
+                WHERE 1 = 1");
+            var languagePredicate = _reader.BuildDependencyGraphLanguagePredicate(TargetAlias, "depsTargetLang");
+            _sql.Append(" AND " + languagePredicate.Sql);
+            _sql.AddParameters(languagePredicate.Parameters);
+            _sql.Append(_reader.BuildDependencyGeneratedFilter(TargetAlias));
+        }
+
+        private void AppendTargetScope()
+        {
+            if (_request.Lang != null && !_request.Lang.Equals("solution", StringComparison.Ordinal))
+                _sql.Append(" AND dst.lang = @lang");
+            if (_request.Reverse && _request.PathPatterns is { Count: > 0 })
+            {
+                var predicates = new List<string>(_request.PathPatterns.Count);
+                for (var i = 0; i < _request.PathPatterns.Count; i++)
+                    predicates.Add(BuildPathFilterPredicate(TargetAlias, "pathPattern", i, _request.PathPatterns[i]));
+                _sql.Append(" AND (" + string.Join(" OR ", predicates) + ")");
+            }
+            if (_request.Reverse && _request.ExcludePathPatterns is { Count: > 0 })
+            {
+                for (var i = 0; i < _request.ExcludePathPatterns.Count; i++)
+                    _sql.Append($" AND NOT {BuildPathFilterPredicate(TargetAlias, "excludePath", i, _request.ExcludePathPatterns[i])}");
+            }
+            if (_request.ExcludeTests)
+                _sql.Append($" AND NOT {DependencyTestPathCondition($"{TargetAlias}.path")}");
+            _sql.Append(BuildDependencySymbolFilter(
+                _expressions.TargetLogicalSymbolName,
+                _request.DependencySymbols,
+                _request.DependencySymbolFamilies,
+                _request.SuppressDependencyNoise,
+                "targetDependency",
+                "dst.lang = 'csharp'"));
+        }
+
+        private void AppendTargetMetadataQueries()
+        {
+            _sql.Append(@"
+                GROUP BY dst.path, dst.lang, " + _expressions.TargetLogicalSymbolName + @", " + _expressions.TargetLogicalSymbolSegmentCount + @"
+            ),
+            path_target_files AS (
+                SELECT DISTINCT target_path, target_lang
+                FROM target_files
+            ),
+            metadata_raw_suppression AS (
+                -- When a raw C# attribute reference '[Foo]' (stored as symbol_name='Foo',
+                -- logical_reference_kind='attribute') also has a synthetic suffix alias
+                -- row that resolves to a class-like 'FooAttribute' target, drop the raw
+                -- row to avoid creating a duplicate edge to any unrelated 'Foo' symbol
+                -- (method, property, local class) that merely shares the bare name.
+                -- 生の C# 属性参照 '[Foo]' (symbol_name='Foo', kind='attribute') に対して
+                -- 同じ source_file 内で 'FooAttribute' の synthetic alias 行が
+                -- class 系 target に解決できる場合、この行自体は落として
+                -- 同名の関数/プロパティ/ローカルクラス 'Foo' への誤依存を防ぐ。
+                SELECT DISTINCT lrp.source_file_id, lrp.symbol_name
+                FROM logical_references_primary lrp
+                JOIN target_files tf_alias
+                  ON tf_alias.target_lang = lrp.source_lang
+                 AND tf_alias.symbol_name = lrp.symbol_name || 'Attribute'
+                 AND tf_alias.symbol_segment_count = 1
+                 AND tf_alias.has_metadata_target_kind = 1
+                WHERE lrp.source_lang = 'csharp'
+                  AND lrp.logical_reference_kind = 'attribute'
+                  AND lrp.symbol_name NOT LIKE '%Attribute'
+            ),
+            target_ambiguity AS (
+                -- Count class-like definitions at symbol-identity level rather than
+                -- file level. Two same-named class-like definitions in the same file
+                -- (e.g. `namespace A { class FooAttribute { } } namespace B { class
+                -- FooAttribute { } }` both inside one .cs file) collapse to a single
+                -- target_files row because target_files is GROUPed by dst.path, so
+                -- COUNT(DISTINCT target_path) alone would see count=1 and falsely
+                -- treat the metadata target as unambiguous. Joining target_files back
+                -- through files + symbols recovers the per-definition row count while
+                -- still inheriting target_files' lang / path / graph-supported scope
+                -- (since the join only keeps rows whose (path, lang, name) already
+                -- appear in target_files).
+                -- class-like 定義は path 単位ではなく symbol identity 単位で数える。
+                -- 同じ .cs ファイル内に別名前空間で同名 class-like が 2 つあるケースは
+                -- target_files (dst.path で GROUP BY) 上では 1 行に潰れており、
+                -- COUNT(DISTINCT target_path) だけでは count=1 となり metadata target
+                -- が一意と誤判定される。target_files から files + symbols に JOIN し直す
+                -- ことで定義単位の件数を復元する。JOIN が target_files 既存行にしか
+                -- 当たらないため、lang / path / graph-supported スコープはそのまま継承。
+                SELECT tf.target_lang,
+                       tf.symbol_name,
+                       tf.symbol_segment_count,
+                       COUNT(*) AS class_like_target_count
+                FROM target_files tf
+                JOIN files dst
+                  ON dst.path = tf.target_path
+                 AND dst.lang = tf.target_lang
+                JOIN symbols s
+                  ON s.file_id = dst.id
+                 AND " + _expressions.TargetLogicalSymbolName + @" = tf.symbol_name
+                 AND " + _expressions.TargetLogicalSymbolSegmentCount + @" = tf.symbol_segment_count
+                 -- Same language-aware metadata-eligibility filter as
+                 -- target_files: C# restricts to `class` with inheritance
+                 -- clause (interface/struct cannot be attribute targets);
+                 -- JS/TS additionally accepts `function` (decorator
+                 -- factory); others keep the class-like candidate set.
+                 -- target_files と同じ言語別 metadata 適格性フィルタ。
+                 -- C# は class 限定 + 継承節 (interface/struct は除外)。
+                 -- JS/TS は decorator factory 用に function も許容。
+                 -- それ以外は class-like 全体を候補にする。
+                 AND " + _reader.BuildMetadataTargetKindExpr(TargetAlias) + @"
+                WHERE tf.has_metadata_target_kind = 1
+                GROUP BY tf.target_lang, tf.symbol_name, tf.symbol_segment_count
+            ),");
+        }
+    }
+}
diff --git a/tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs b/tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs
index ba4883c26..d8d056d4a 100644
--- a/tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs
+++ b/tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs
@@ -10,6 +10,17 @@ namespace CodeIndex.Tests;
 
 public partial class DbReaderTests
 {
+    [Fact]
+    public void GetFileDependencies_PreCanceledTokenThrows()
+    {
+        var token = new CancellationToken(canceled: true);
+
+        var exception = Assert.Throws<OperationCanceledException>(
+            () => _reader.GetFileDependencies(cancellationToken: token));
+
+        Assert.Equal(token, exception.CancellationToken);
+    }
+
     [Fact]
     public void GetFileDependencies_PythonUsesFileLocalImportsAndModuleOwnership_Issue4412()
     {

From abddf5ccd8a2e12981e22440f56981cda3491952 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 15:15:51 +0900
Subject: [PATCH 20/45] Decompose dependency cycle queries

---
 TESTING_GUIDE.md                              |   4 +-
 .../DbReader.DependencyCycleCandidateSql.cs   | 114 +++++++++
 .../DbReader.DependencyCycleEvidenceSql.cs    | 156 ++++++++++++
 .../DbReader.DependencyCycleExecution.cs      |  41 +++
 .../Database/DbReader.DependencyCyclePlan.cs  |  59 +++++
 .../Database/DbReader.DependencyCycleQuery.cs | 236 +-----------------
 .../DbReaderFileDependencyTests.cs            |  45 ++++
 7 files changed, 429 insertions(+), 226 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyCycleCandidateSql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyCycleEvidenceSql.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyCycleExecution.cs
 create mode 100644 src/CodeIndex/Database/DbReader.DependencyCyclePlan.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 050a395e0..35b649f02 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -187,7 +187,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   `DbSchemaConstraintTests` runs the public-array mutation regression in the non-parallel SQLite-sensitive collection and restores both arrays in `finally`. It must prove that writer validation and newly generated symbol/reference CHECK clauses continue to use the same private canonical taxonomy while the compatibility arrays are visibly mutated.
   Do not put a timing assertion in this test class. When a static lookup replay is useful, keep its Release harness temporary, feed the same persisted kind/count distribution to the legacy and candidate lookups, alternate execution order, and remove it before committing. The normal empty-database full-index A/B remains authoritative for the user-visible performance decision.
 - `DatabaseTests.cs`, `DatabasePermissionPolicyTests.cs`, `DbReader*Tests.cs`, `CSharpBaseListParserTests.cs`
-  SQLite schema, write paths, migrations, and query behavior. DbReader coverage is split by query family, including search, SQL qualified-name handling, file dependencies, impact, and symbol-query suites, while shared seeded fixture state remains on the root `DbReaderTests` part. File-dependency coverage keeps pre-cancellation ahead of command construction and execution.
+  SQLite schema, write paths, migrations, and query behavior. DbReader coverage is split by query family, including search, SQL qualified-name handling, file dependencies, impact, and symbol-query suites, while shared seeded fixture state remains on the root `DbReaderTests` part. File-dependency list and cycle-candidate coverage keep pre-cancellation ahead of command construction and execution; cycle-candidate coverage also pins reverse include/exclude path scope to the target side.
   `CSharpBaseListParserTests` keeps the SQLite-free base-list grammar matrix together, including generic constraints, nested generic/tuple/array syntax, alias qualifiers, primary/base constructors, declaration terminators, and the distinct reader type-reference and metadata head-identifier projections.
   Maintenance-lookup coverage keeps the `files(checksum)`, `files(path COLLATE NOCASE)`, and `file_issues(file_id, kind)` indexes aligned with their predicates and requires `EXPLAIN QUERY PLAN` index `SEARCH` operations for checksum purge, ASCII case-alias lookup, reusable-stat issue probes, and directory/stem rename candidates. The case-alias fixture uses changed content so checksum cannot hide a missing path lookup, and managed validation remains authoritative because SQLite `NOCASE` is only an ASCII prefilter, not a Unicode casing contract. Keep wildcard-bearing, extensionless, and near-match stem semantics in one fixture. Scoped-cleanup planning coverage unions checksum and exact same-directory/stem candidates into ascending deduplicated ID snapshots, merges overlapping plans, proves apply does not absorb matching rows added after planning, and rereads planned IDs immediately before apply so a deleted C# contract that reappears is deferred until a clean retry. The grouped C# fixture gives many targets one common checksum/stem and requires candidate-reader work to grow with unique keys plus returned rows rather than target-count squared; it also asserts that C# pre-workspace planning never deletes matching non-C# rows.
   Reference-resolution lookup coverage keeps the exact fresh-schema and read-migration index sets aligned for file/name, retained folded/NOCASE composite prefixes, resolved reverse edges, and the partial unresolved-mutual path. Assert the absence of all six retired single-prefix indexes plus the former all-row mutual index after migration and reopen, exact column order/collation/partial predicates, and `EXPLAIN QUERY PLAN` `SEARCH` operations for both full and scoped mutual SQL. Preserve fold-ready and legacy-fallback CLI/MCP exact-query signals, and rerun the same-name/different-container plus partial-class-over-same-file ranking fixtures when these indexes change.
@@ -1246,7 +1246,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   `DbSchemaConstraintTests` の公開 array mutation 回帰は、並列実行しない SQLite-sensitive collection で実行し、`finally` で両 array を復元します。互換 array の変更が実際に見える間も、writer validation と新規生成する symbol / reference CHECK 句が同じ private canonical taxonomy を使い続けることを必須とします。
   この test class に timing assertion を追加してはいけません。static lookup replay が有用な場合は Release harness を一時的なものに限定し、同一の保存済み kind/count 分布を旧来経路と候補経路へ流し、実行順を交互にしたうえで commit 前に削除します。ユーザーに見える性能の採否は、通常の空 database full-index A/B を authoritative としてください。
 - `DatabaseTests.cs`、`DatabasePermissionPolicyTests.cs`、`DbReader*Tests.cs`、`CSharpBaseListParserTests.cs`
-  SQLite スキーマ、書き込み経路、マイグレーション、クエリ挙動のテスト。DbReader のカバレッジは search、SQL qualified name、file dependency、impact、symbol query などの query family ごとの partial suite に分割し、共有の seed 済み fixture 状態は root 側の `DbReaderTests` に残します。file dependency の coverage では、command 構築・実行より前の pre-cancellation を固定します。
+  SQLite スキーマ、書き込み経路、マイグレーション、クエリ挙動のテスト。DbReader のカバレッジは search、SQL qualified name、file dependency、impact、symbol query などの query family ごとの partial suite に分割し、共有の seed 済み fixture 状態は root 側の `DbReaderTests` に残します。file dependency list / cycle candidate の coverage では command 構築・実行より前の pre-cancellation を固定し、cycle candidate の coverage では reverse include/exclude path scope が target 側へ適用されることも固定します。
   `CSharpBaseListParserTests` には SQLite を使わない base-list 構文 matrix をまとめ、generic constraint、nested generic / tuple / array、alias qualifier、primary / base constructor、宣言終端、および reader の type-reference 投影と metadata の head-identifier 投影の差を固定します。
   maintenance lookup の coverage では `files(checksum)`、`files(path COLLATE NOCASE)`、`file_issues(file_id, kind)` の index を predicate と同期させ、checksum purge、ASCII case-alias lookup、再利用 stat の issue probe、directory/stem rename 候補が `EXPLAIN QUERY PLAN` で index `SEARCH` を使うことを必須とします。case-alias fixture は checksum で path lookup の欠落が隠れないよう content も変更し、SQLite `NOCASE` は Unicode casing contract ではなく ASCII prefilter にすぎないため managed 検証を authoritative に保ちます。wildcard を含む stem、拡張子なし、近似 stem の意味論は1つの fixture にまとめます。scoped cleanup planning の coverage では checksum と正確な同一 directory/stem の候補を昇順・重複排除済み ID snapshot に統合し、重複 plan の merge、plan 後に追加された一致 row を apply が取り込まないこと、apply 直前に planned ID を再読込して再出現した C# contract を clean retry まで延期することを固定します。grouped C# fixture は多数の target に共通 checksum/stem を与え、candidate reader の処理量が target 数の二乗ではなく unique key 数と返却 row 数に比例すること、および C# workspace 前の plan が一致する non-C# row を削除しないことを要求します。
   参照解決 lookup の coverage では fresh schema / read migration の正確な index setを、file/name、保持したfolded/NOCASE composite prefix、解決済み逆辺、未解決mutual用partial pathまで同期させます。migrationと再open後に退役したsingle-prefix 6本と旧全row mutual indexが存在しないこと、列順・collation・partial predicateを厳密に検証し、full/scoped mutual SQLの両方で`EXPLAIN QUERY PLAN`のindex `SEARCH`を必須とします。fold-ready/legacy fallback双方のCLI/MCP exact-query signalを維持し、これらのindexを変える際は同名・別containerとpartial classが同一file候補より優先される既存ranking fixtureも再実行してください。
diff --git a/src/CodeIndex/Database/DbReader.DependencyCycleCandidateSql.cs b/src/CodeIndex/Database/DbReader.DependencyCycleCandidateSql.cs
new file mode 100644
index 000000000..bdd25284c
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyCycleCandidateSql.cs
@@ -0,0 +1,114 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class DependencyCycleCandidateSqlBuilder
+    {
+        private readonly DbReader _reader;
+        private readonly DependencyQueryRequest _request;
+        private readonly DependencyCycleQueryExpressions _expressions;
+        private readonly DependencySqlFragmentBuilder _sql = new();
+
+        internal DependencyCycleCandidateSqlBuilder(
+            DbReader reader,
+            DependencyQueryRequest request,
+            DependencyCycleQueryExpressions expressions)
+        {
+            _reader = reader;
+            _request = request;
+            _expressions = expressions;
+        }
+
+        internal DependencySqlFragment Build()
+        {
+            AppendCandidateEdgeQuery();
+            AppendCandidateScope();
+            AppendCandidateFilters();
+            return _sql.Build();
+        }
+
+        private void AppendCandidateEdgeQuery()
+        {
+            _sql.Append(@"
+            WITH candidate_edges AS (
+                SELECT src.path AS source_path,
+                       dst.path AS target_path,
+                       MAX(CASE
+                               WHEN src.lang = 'markdown'
+                                AND s.kind = 'heading'
+                                AND NOT " + _expressions.MarkdownExplicitLink + @" THEN 0
+                               ELSE 1
+                           END) AS retained_evidence
+            FROM symbol_references r
+            JOIN files src ON r.file_id = src.id
+            JOIN symbols s ON s.name = r.symbol_name
+            JOIN files dst ON s.file_id = dst.id
+            WHERE src.path != dst.path
+              AND src.lang = dst.lang");
+        }
+
+        private void AppendCandidateScope()
+        {
+            AppendGraphLanguageScope("src", "depsCycleSourceLang");
+            AppendGraphLanguageScope("dst", "depsCycleTargetLang");
+            _sql.Append(_reader.BuildDependencyGeneratedFilter("src"));
+            _sql.Append(_reader.BuildDependencyGeneratedFilter("dst"));
+            if (_request.Lang != null)
+                _sql.Append(" AND src.lang = @lang AND dst.lang = @lang");
+            if (_request.PathPatterns is { Count: > 0 })
+            {
+                var predicates = new List<string>(_request.PathPatterns.Count);
+                for (var i = 0; i < _request.PathPatterns.Count; i++)
+                {
+                    predicates.Add(BuildPathFilterPredicate(
+                        _expressions.ConstrainedAlias,
+                        "pathPattern",
+                        i,
+                        _request.PathPatterns[i]));
+                }
+                _sql.Append(" AND (" + string.Join(" OR ", predicates) + ")");
+            }
+            if (_request.ExcludePathPatterns is { Count: > 0 })
+            {
+                for (var i = 0; i < _request.ExcludePathPatterns.Count; i++)
+                {
+                    _sql.Append($" AND NOT {BuildPathFilterPredicate(_expressions.ConstrainedAlias, "excludePath", i, _request.ExcludePathPatterns[i])}");
+                }
+            }
+            if (_request.ExcludeTests)
+            {
+                _sql.Append($" AND NOT {DependencyTestPathCondition("src.path")}");
+                _sql.Append($" AND NOT {DependencyTestPathCondition("dst.path")}");
+            }
+        }
+
+        private void AppendGraphLanguageScope(string fileAlias, string parameterPrefix)
+        {
+            var predicate = _reader.BuildDependencyGraphLanguagePredicate(fileAlias, parameterPrefix);
+            _sql.Append(" AND " + predicate.Sql);
+            _sql.AddParameters(predicate.Parameters);
+        }
+
+        private void AppendCandidateFilters()
+        {
+            _sql.Append(BuildDependencySymbolFilter(
+                "r.symbol_name",
+                _request.DependencySymbols,
+                _request.DependencySymbolFamilies,
+                suppressDependencyNoise: false,
+                parameterPrefix: "cycleDependencyNames"));
+            _sql.Append(BuildDependencySymbolFilter(
+                "r.symbol_name",
+                dependencySymbols: null,
+                dependencySymbolFamilies: null,
+                suppressDependencyNoise: _request.SuppressDependencyNoise,
+                parameterPrefix: "cycleDependencyNoise",
+                filterScopeSql: "NOT " + _expressions.NoiseEvidenceScope));
+            _sql.Append(@"
+                GROUP BY src.path, dst.path
+                ORDER BY " + _expressions.CandidateOrder + @"
+                LIMIT @limit
+            ),");
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyCycleEvidenceSql.cs b/src/CodeIndex/Database/DbReader.DependencyCycleEvidenceSql.cs
new file mode 100644
index 000000000..9d7946840
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyCycleEvidenceSql.cs
@@ -0,0 +1,156 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class DependencyCycleEvidenceSqlBuilder
+    {
+        private readonly DependencyQueryRequest _request;
+        private readonly DependencyCycleQueryExpressions _expressions;
+        private readonly DependencySqlFragmentBuilder _sql = new();
+
+        internal DependencyCycleEvidenceSqlBuilder(
+            DependencyQueryRequest request,
+            DependencyCycleQueryExpressions expressions)
+        {
+            _request = request;
+            _expressions = expressions;
+        }
+
+        internal DependencySqlFragment Build()
+        {
+            AppendCandidateSymbols();
+            AppendEdgeAggregates();
+            AppendEvidencePayloads();
+            AppendFinalProjection();
+            return _sql.Build();
+        }
+
+        private void AppendCandidateSymbols()
+        {
+            _sql.Append(@"
+            candidate_symbols AS (
+                SELECT candidate_edges.source_path,
+                       candidate_edges.target_path,
+                       r.id AS reference_id,
+                       r.symbol_name,
+                       src.lang AS source_lang,
+                       CASE
+                           WHEN " + _expressions.MarkdownExplicitLink + @"
+                               THEN 'markdown_explicit_link'
+                           WHEN src.lang = 'markdown' AND s.kind = 'heading'
+                               THEN 'markdown_heading_name_match'
+                           ELSE 'symbol_name_match'
+                       END AS origin,
+                       r.reference_kind AS raw_reference_kind,
+                       CASE WHEN s.kind = 'heading' THEN 'heading' ELSE 'symbol' END AS target_kind
+                FROM candidate_edges
+                JOIN files src ON src.path = candidate_edges.source_path
+                JOIN symbol_references r ON r.file_id = src.id
+                JOIN symbols s ON s.name = r.symbol_name
+                JOIN files dst ON s.file_id = dst.id
+                 AND dst.path = candidate_edges.target_path
+                WHERE src.path != dst.path
+                  AND src.lang = dst.lang");
+            _sql.Append(BuildDependencySymbolFilter(
+                "r.symbol_name",
+                _request.DependencySymbols,
+                _request.DependencySymbolFamilies,
+                suppressDependencyNoise: false,
+                parameterPrefix: "cycleAggregateNames"));
+            _sql.Append(BuildDependencySymbolFilter(
+                "r.symbol_name",
+                dependencySymbols: null,
+                dependencySymbolFamilies: null,
+                suppressDependencyNoise: _request.SuppressDependencyNoise,
+                parameterPrefix: "cycleAggregateNoise",
+                filterScopeSql: "NOT " + _expressions.NoiseEvidenceScope));
+        }
+
+        private void AppendEdgeAggregates()
+        {
+            _sql.Append(@"
+            ),
+            edge_reference_totals AS (
+                SELECT source_path,
+                       target_path,
+                       COUNT(DISTINCT reference_id) AS reference_count
+                FROM candidate_symbols
+                GROUP BY source_path, target_path
+            ),
+            edge_evidence_rows AS (
+                SELECT source_path,
+                       target_path,
+                       source_lang,
+                       origin,
+                       raw_reference_kind,
+                       target_kind,
+                       COUNT(DISTINCT reference_id) AS evidence_reference_count
+                FROM candidate_symbols
+                GROUP BY source_path,
+                         target_path,
+                         source_lang,
+                         origin,
+                         raw_reference_kind,
+                         target_kind
+            ),");
+        }
+
+        private void AppendEvidencePayloads()
+        {
+            _sql.Append(@"
+            ordered_edge_evidence AS (
+                SELECT source_path,
+                       target_path,
+                       source_lang || char(31) ||
+                       origin || char(31) ||
+                       raw_reference_kind || char(31) ||
+                       target_kind || char(31) ||
+                       evidence_reference_count AS evidence_item
+                FROM edge_evidence_rows
+                ORDER BY source_path, target_path, source_lang, origin, raw_reference_kind, target_kind
+            ),
+            edge_evidence_payloads AS (
+                SELECT source_path,
+                       target_path,
+                       GROUP_CONCAT(evidence_item, char(30)) AS evidence_payload
+                FROM ordered_edge_evidence
+                GROUP BY source_path, target_path
+            ),
+            distinct_edge_symbols AS (
+                SELECT DISTINCT source_path,
+                                target_path,
+                                symbol_name
+                FROM candidate_symbols" + _expressions.RetainedSymbolFilter + @"
+            ),
+            ranked_edge_symbols AS (
+                SELECT source_path,
+                       target_path,
+                       symbol_name,
+                       ROW_NUMBER() OVER (PARTITION BY source_path, target_path ORDER BY symbol_name) AS symbol_rank
+                FROM distinct_edge_symbols
+            )");
+        }
+
+        private void AppendFinalProjection()
+        {
+            _sql.Append(@"
+            SELECT edge_reference_totals.source_path,
+                   edge_reference_totals.target_path,
+                   edge_reference_totals.reference_count,
+                   COALESCE(GROUP_CONCAT(CASE WHEN symbol_rank <= @symbolSampleLimit THEN symbol_name END, char(31)), '') AS symbols,
+                   COALESCE(edge_evidence_payloads.evidence_payload, '') AS evidence_payload
+            FROM edge_reference_totals
+            LEFT JOIN ranked_edge_symbols
+              ON ranked_edge_symbols.source_path = edge_reference_totals.source_path
+             AND ranked_edge_symbols.target_path = edge_reference_totals.target_path
+            LEFT JOIN edge_evidence_payloads
+              ON edge_evidence_payloads.source_path = edge_reference_totals.source_path
+             AND edge_evidence_payloads.target_path = edge_reference_totals.target_path
+            GROUP BY edge_reference_totals.source_path,
+                     edge_reference_totals.target_path,
+                     edge_reference_totals.reference_count,
+                     edge_evidence_payloads.evidence_payload
+            ORDER BY edge_reference_totals.source_path, edge_reference_totals.target_path");
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyCycleExecution.cs b/src/CodeIndex/Database/DbReader.DependencyCycleExecution.cs
new file mode 100644
index 000000000..03312daa8
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyCycleExecution.cs
@@ -0,0 +1,41 @@
+using CodeIndex.Models;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private List<FileDependencyResult> ExecuteDependencyCycleQuery(
+        DependencyCycleQueryPlan plan,
+        CancellationToken cancellationToken,
+        out int candidateRowCount)
+    {
+        candidateRowCount = 0;
+        using var command = _conn.CreateCommand();
+        command.CommandText = plan.Sql;
+        BindDependencyQueryParameters(command, plan.Parameters);
+
+        var results = new List<FileDependencyResult>();
+        using var cancellationRegistration = cancellationToken.Register(
+            static state => ((SqliteCommand)state!).Cancel(),
+            command);
+        try
+        {
+            using var reader = command.ExecuteTrackedReader();
+            while (reader.TrackedRead())
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                candidateRowCount++;
+                var result = ProjectDependencyRow(reader);
+                result.RankingScore = result.ReferenceCount;
+                results.Add(result);
+            }
+        }
+        catch (SqliteException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw new OperationCanceledException(cancellationToken);
+        }
+
+        return results;
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyCyclePlan.cs b/src/CodeIndex/Database/DbReader.DependencyCyclePlan.cs
new file mode 100644
index 000000000..39b977b36
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.DependencyCyclePlan.cs
@@ -0,0 +1,59 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed record DependencyCycleQueryPlan(
+        string Sql,
+        IReadOnlyList<DependencyQueryParameter> Parameters);
+
+    private sealed record DependencyCycleQueryExpressions(
+        string MarkdownExplicitLink,
+        string NoiseEvidenceScope,
+        string CandidateOrder,
+        string RetainedSymbolFilter,
+        string ConstrainedAlias);
+
+    private DependencyCycleQueryPlan BuildDependencyCycleQueryPlan(DependencyQueryRequest request)
+    {
+        var expressions = BuildDependencyCycleQueryExpressions(request);
+        var candidates = new DependencyCycleCandidateSqlBuilder(this, request, expressions).Build();
+        var evidence = new DependencyCycleEvidenceSqlBuilder(request, expressions).Build();
+        var builder = new DependencySqlFragmentBuilder();
+        builder.Append(candidates.Sql);
+        builder.Append(evidence.Sql);
+        builder.AddParameters(candidates.Parameters);
+        builder.AddParameters(evidence.Parameters);
+        AppendDependencyCycleTerminalParameters(builder, request);
+        var query = builder.Build();
+        return new DependencyCycleQueryPlan(query.Sql, query.Parameters);
+    }
+
+    private DependencyCycleQueryExpressions BuildDependencyCycleQueryExpressions(DependencyQueryRequest request)
+    {
+        var markdownExplicitLink = _referenceColumns.Contains("target_qualifier")
+            ? "(src.lang = 'markdown' AND r.reference_kind = 'reference' AND r.target_qualifier IS NOT NULL AND dst.path = markdown_resolve_path(src.path, r.target_qualifier))"
+            : "0 = 1";
+        return new DependencyCycleQueryExpressions(
+            markdownExplicitLink,
+            "(" + markdownExplicitLink + " OR (src.lang = 'markdown' AND s.kind = 'heading'))",
+            request.SuppressDependencyNoise
+                ? "retained_evidence DESC, source_path, target_path"
+                : "source_path, target_path",
+            request.SuppressDependencyNoise
+                ? " WHERE origin <> 'markdown_heading_name_match'"
+                : string.Empty,
+            request.Reverse ? "dst" : "src");
+    }
+
+    private static void AppendDependencyCycleTerminalParameters(
+        DependencySqlFragmentBuilder builder,
+        DependencyQueryRequest request)
+    {
+        if (request.Lang != null)
+            builder.AddText("@lang", request.Lang);
+        AppendDependencyPathParameters(builder, "pathPattern", request.PathPatterns);
+        AppendDependencyPathParameters(builder, "excludePath", request.ExcludePathPatterns);
+        builder.AddInt32("@limit", request.Limit);
+        builder.AddInt32("@symbolSampleLimit", DependencySymbolSampleLimit);
+    }
+}
diff --git a/src/CodeIndex/Database/DbReader.DependencyCycleQuery.cs b/src/CodeIndex/Database/DbReader.DependencyCycleQuery.cs
index c7b82928e..4dfeb3a0d 100644
--- a/src/CodeIndex/Database/DbReader.DependencyCycleQuery.cs
+++ b/src/CodeIndex/Database/DbReader.DependencyCycleQuery.cs
@@ -1,5 +1,4 @@
 using CodeIndex.Models;
-using Microsoft.Data.Sqlite;
 
 namespace CodeIndex.Database;
 
@@ -24,230 +23,19 @@ public List<FileDependencyResult> GetFileDependencyCycleCandidates(
             return [];
 
         cancellationToken.ThrowIfCancellationRequested();
-        using var cmd = _conn.CreateCommand();
-        var constrainedAlias = reverse ? "dst" : "src";
-        var cycleMarkdownExplicitLinkSql = _referenceColumns.Contains("target_qualifier")
-            ? "(src.lang = 'markdown' AND r.reference_kind = 'reference' AND r.target_qualifier IS NOT NULL AND dst.path = markdown_resolve_path(src.path, r.target_qualifier))"
-            : "0 = 1";
-        var cycleNoiseEvidenceScopeSql =
-            "(" + cycleMarkdownExplicitLinkSql + " OR (src.lang = 'markdown' AND s.kind = 'heading'))";
-        var cycleCandidateOrderSql = suppressDependencyNoise
-            ? "retained_evidence DESC, source_path, target_path"
-            : "source_path, target_path";
-        var retainedCycleSymbolFilterSql = suppressDependencyNoise
-            ? " WHERE origin <> 'markdown_heading_name_match'"
-            : string.Empty;
-        var sql = @"
-            WITH candidate_edges AS (
-                SELECT src.path AS source_path,
-                       dst.path AS target_path,
-                       MAX(CASE
-                               WHEN src.lang = 'markdown'
-                                AND s.kind = 'heading'
-                                AND NOT " + cycleMarkdownExplicitLinkSql + @" THEN 0
-                               ELSE 1
-                           END) AS retained_evidence
-            FROM symbol_references r
-            JOIN files src ON r.file_id = src.id
-            JOIN symbols s ON s.name = r.symbol_name
-            JOIN files dst ON s.file_id = dst.id
-            WHERE src.path != dst.path
-              AND src.lang = dst.lang";
-        sql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "src", "depsCycleSourceLang")}";
-        sql += $" AND {BuildGraphSupportedLanguagePredicate(cmd, "dst", "depsCycleTargetLang")}";
-        AppendDependencyGeneratedFilter(ref sql, "src");
-        AppendDependencyGeneratedFilter(ref sql, "dst");
-        if (lang != null)
-            sql += " AND src.lang = @lang AND dst.lang = @lang";
-        if (pathPatterns is { Count: > 0 })
-        {
-            var ors = new List<string>(pathPatterns.Count);
-            for (int i = 0; i < pathPatterns.Count; i++)
-                ors.Add(BuildPathFilterPredicate(constrainedAlias, "pathPattern", i, pathPatterns[i]));
-            sql += " AND (" + string.Join(" OR ", ors) + ")";
-        }
-        if (excludePathPatterns is { Count: > 0 })
-        {
-            for (int i = 0; i < excludePathPatterns.Count; i++)
-                sql += $" AND NOT {BuildPathFilterPredicate(constrainedAlias, "excludePath", i, excludePathPatterns[i])}";
-        }
-        if (excludeTests)
-        {
-            sql += $" AND NOT {DependencyTestPathCondition("src.path")}";
-            sql += $" AND NOT {DependencyTestPathCondition("dst.path")}";
-        }
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "r.symbol_name",
+        var request = new DependencyQueryRequest(
+            limit,
+            lang,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            reverse,
             dependencySymbols,
             dependencySymbolFamilies,
-            suppressDependencyNoise: false,
-            parameterPrefix: "cycleDependencyNames");
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "r.symbol_name",
-            dependencySymbols: null,
-            dependencySymbolFamilies: null,
-            suppressDependencyNoise: suppressDependencyNoise,
-            parameterPrefix: "cycleDependencyNoise",
-            filterScopeSql: "NOT " + cycleNoiseEvidenceScopeSql);
-        sql += @"
-                GROUP BY src.path, dst.path
-                ORDER BY " + cycleCandidateOrderSql + @"
-                LIMIT @limit
-            ),
-            candidate_symbols AS (
-                SELECT candidate_edges.source_path,
-                       candidate_edges.target_path,
-                       r.id AS reference_id,
-                       r.symbol_name,
-                       src.lang AS source_lang,
-                       CASE
-                           WHEN " + cycleMarkdownExplicitLinkSql + @"
-                               THEN 'markdown_explicit_link'
-                           WHEN src.lang = 'markdown' AND s.kind = 'heading'
-                               THEN 'markdown_heading_name_match'
-                           ELSE 'symbol_name_match'
-                       END AS origin,
-                       r.reference_kind AS raw_reference_kind,
-                       CASE WHEN s.kind = 'heading' THEN 'heading' ELSE 'symbol' END AS target_kind
-                FROM candidate_edges
-                JOIN files src ON src.path = candidate_edges.source_path
-                JOIN symbol_references r ON r.file_id = src.id
-                JOIN symbols s ON s.name = r.symbol_name
-                JOIN files dst ON s.file_id = dst.id
-                 AND dst.path = candidate_edges.target_path
-                WHERE src.path != dst.path
-                  AND src.lang = dst.lang";
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "r.symbol_name",
-            dependencySymbols,
-            dependencySymbolFamilies,
-            suppressDependencyNoise: false,
-            parameterPrefix: "cycleAggregateNames");
-        AppendDependencySymbolFilter(
-            cmd,
-            ref sql,
-            "r.symbol_name",
-            dependencySymbols: null,
-            dependencySymbolFamilies: null,
-            suppressDependencyNoise: suppressDependencyNoise,
-            parameterPrefix: "cycleAggregateNoise",
-            filterScopeSql: "NOT " + cycleNoiseEvidenceScopeSql);
-        sql += @"
-            ),
-            edge_reference_totals AS (
-                SELECT source_path,
-                       target_path,
-                       COUNT(DISTINCT reference_id) AS reference_count
-                FROM candidate_symbols
-                GROUP BY source_path, target_path
-            ),
-            edge_evidence_rows AS (
-                SELECT source_path,
-                       target_path,
-                       source_lang,
-                       origin,
-                       raw_reference_kind,
-                       target_kind,
-                       COUNT(DISTINCT reference_id) AS evidence_reference_count
-                FROM candidate_symbols
-                GROUP BY source_path,
-                         target_path,
-                         source_lang,
-                         origin,
-                         raw_reference_kind,
-                         target_kind
-            ),
-            ordered_edge_evidence AS (
-                SELECT source_path,
-                       target_path,
-                       source_lang || char(31) ||
-                       origin || char(31) ||
-                       raw_reference_kind || char(31) ||
-                       target_kind || char(31) ||
-                       evidence_reference_count AS evidence_item
-                FROM edge_evidence_rows
-                ORDER BY source_path, target_path, source_lang, origin, raw_reference_kind, target_kind
-            ),
-            edge_evidence_payloads AS (
-                SELECT source_path,
-                       target_path,
-                       GROUP_CONCAT(evidence_item, char(30)) AS evidence_payload
-                FROM ordered_edge_evidence
-                GROUP BY source_path, target_path
-            ),
-            distinct_edge_symbols AS (
-                SELECT DISTINCT source_path,
-                                target_path,
-                                symbol_name
-                FROM candidate_symbols" + retainedCycleSymbolFilterSql + @"
-            ),
-            ranked_edge_symbols AS (
-                SELECT source_path,
-                       target_path,
-                       symbol_name,
-                       ROW_NUMBER() OVER (PARTITION BY source_path, target_path ORDER BY symbol_name) AS symbol_rank
-                FROM distinct_edge_symbols
-            )
-            SELECT edge_reference_totals.source_path,
-                   edge_reference_totals.target_path,
-                   edge_reference_totals.reference_count,
-                   COALESCE(GROUP_CONCAT(CASE WHEN symbol_rank <= @symbolSampleLimit THEN symbol_name END, char(31)), '') AS symbols,
-                   COALESCE(edge_evidence_payloads.evidence_payload, '') AS evidence_payload
-            FROM edge_reference_totals
-            LEFT JOIN ranked_edge_symbols
-              ON ranked_edge_symbols.source_path = edge_reference_totals.source_path
-             AND ranked_edge_symbols.target_path = edge_reference_totals.target_path
-            LEFT JOIN edge_evidence_payloads
-              ON edge_evidence_payloads.source_path = edge_reference_totals.source_path
-             AND edge_evidence_payloads.target_path = edge_reference_totals.target_path
-            GROUP BY edge_reference_totals.source_path,
-                     edge_reference_totals.target_path,
-                     edge_reference_totals.reference_count,
-                     edge_evidence_payloads.evidence_payload
-            ORDER BY edge_reference_totals.source_path, edge_reference_totals.target_path";
-
-        cmd.CommandText = sql;
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        if (pathPatterns is { Count: > 0 })
-            AddPathFilterParameterSet(cmd, "pathPattern", pathPatterns);
-        if (excludePathPatterns is { Count: > 0 })
-            AddPathFilterParameterSet(cmd, "excludePath", excludePathPatterns);
-        SqliteCommandPolicy.Add(cmd, "@limit", limit);
-        SqliteCommandPolicy.Add(cmd, "@symbolSampleLimit", DependencySymbolSampleLimit);
-
-        var results = new List<FileDependencyResult>();
-        using var cancellationRegistration = cancellationToken.Register(static state => ((SqliteCommand)state!).Cancel(), cmd);
-        try
-        {
-            using var reader = cmd.ExecuteTrackedReader();
-            while (reader.TrackedRead())
-            {
-                cancellationToken.ThrowIfCancellationRequested();
-                candidateRowCount++;
-                var symbolSamples = ParseDependencySymbols(reader.GetString(3));
-                results.Add(new FileDependencyResult
-                {
-                    SourcePath = reader.GetString(0),
-                    TargetPath = reader.GetString(1),
-                    ReferenceCount = reader.GetInt32(2),
-                    RankingScore = reader.GetInt32(2),
-                    SymbolSamples = symbolSamples,
-                    Symbols = string.Join(",", symbolSamples),
-                    Evidence = ParseDependencyEvidence(reader.GetString(4)),
-                });
-            }
-        }
-        catch (SqliteException) when (cancellationToken.IsCancellationRequested)
-        {
-            throw new OperationCanceledException(cancellationToken);
-        }
-        return results;
+            suppressDependencyNoise);
+        return ExecuteDependencyCycleQuery(
+            BuildDependencyCycleQueryPlan(request),
+            cancellationToken,
+            out candidateRowCount);
     }
 }
diff --git a/tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs b/tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs
index d8d056d4a..c5942ad52 100644
--- a/tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs
+++ b/tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs
@@ -10,6 +10,51 @@ namespace CodeIndex.Tests;
 
 public partial class DbReaderTests
 {
+    [Fact]
+    public void GetFileDependencyCycleCandidates_PreCanceledTokenThrows()
+    {
+        var token = new CancellationToken(canceled: true);
+
+        var exception = Assert.Throws<OperationCanceledException>(
+            () => _reader.GetFileDependencyCycleCandidates(
+                limit: 1,
+                out _,
+                cancellationToken: token));
+
+        Assert.Equal(token, exception.CancellationToken);
+    }
+
+    [Fact]
+    public void GetFileDependencyCycleCandidates_ReversePathScopeAppliesIncludeAndExcludeToTargets()
+    {
+        var sourceFileId = InsertSyntheticDependencyFile("src/ReverseCycleSource.cs");
+        var includedTargetId = InsertSyntheticDependencyFile("targets/keep/IncludedCycleTarget.cs");
+        var excludedTargetId = InsertSyntheticDependencyFile("targets/drop/ExcludedCycleTarget.cs");
+        _writer.InsertSymbols([
+            new SymbolRecord { FileId = includedTargetId, Kind = "class", Name = "IncludedCycleTarget", Line = 1, StartLine = 1, EndLine = 1 },
+            new SymbolRecord { FileId = excludedTargetId, Kind = "class", Name = "ExcludedCycleTarget", Line = 1, StartLine = 1, EndLine = 1 },
+        ]);
+        _writer.InsertReferences([
+            new ReferenceRecord { FileId = sourceFileId, SymbolName = "IncludedCycleTarget", ReferenceKind = "call", Line = 1, Column = 1, Context = "IncludedCycleTarget()" },
+            new ReferenceRecord { FileId = sourceFileId, SymbolName = "ExcludedCycleTarget", ReferenceKind = "call", Line = 2, Column = 1, Context = "ExcludedCycleTarget()" },
+        ]);
+
+        var candidates = _reader.GetFileDependencyCycleCandidates(
+            limit: 10,
+            out var candidateRowCount,
+            lang: "csharp",
+            pathPatterns: ["targets"],
+            excludePathPatterns: ["targets/drop"],
+            reverse: true);
+
+        var candidate = Assert.Single(candidates);
+        Assert.Equal(1, candidateRowCount);
+        Assert.Equal("src/ReverseCycleSource.cs", candidate.SourcePath);
+        Assert.Equal("targets/keep/IncludedCycleTarget.cs", candidate.TargetPath);
+        Assert.Equal(1, candidate.ReferenceCount);
+        Assert.Equal(candidate.ReferenceCount, candidate.RankingScore);
+    }
+
     [Fact]
     public void GetFileDependencies_PreCanceledTokenThrows()
     {

From 17b803cfc04f6a6435986857d2fedd87f23cd515 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 15:50:58 +0900
Subject: [PATCH 21/45] Decompose documentation reference extraction

---
 TESTING_GUIDE.md                              |   4 +-
 ...eExtractor.CoreCSharpDocumentationLines.cs |  78 +++++++
 ...ferenceExtractor.CoreDocumentationLines.cs | 199 ++++++----------
 ...enceExtractor.CoreJvmDocumentationLines.cs |  59 +++++
 ...enceExtractor.CorePhpDocumentationLines.cs | 217 ++++++++++++++++++
 .../ReferenceExtractor.CorePhpLines.cs        |  62 +++++
 .../ReferenceExtractor.CoreRLines.cs          |  18 ++
 .../ReferenceExtractor.CoreReferenceLine.cs   |  61 +----
 .../ReferenceExtractor.CoreReferenceLoop.cs   |   6 +-
 .../ReferenceExtractor.CoreReferencePhases.cs |   3 +-
 ...ReferenceExtractor.CoreSpecializedLines.cs | 124 +---------
 .../ReferenceExtractor.ReferenceRecords.cs    | 202 ----------------
 .../ReferenceExtractorTests.cs                |  27 +++
 13 files changed, 551 insertions(+), 509 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCSharpDocumentationLines.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreJvmDocumentationLines.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CorePhpDocumentationLines.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CorePhpLines.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 35b649f02..1c3b6516b 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -719,7 +719,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   JVM graph fixtures cover demand-driven Java type/module/method-reference, Kotlin type/infix/constructor, Scala contextual, and Gradle/Groovy DSL matches. Preserve dense-line ordering when adding cap-aware exits.
   Python graph fixtures cover streamed decorator arguments, annotations, runtime type checks, typing factories, dataclass/framework integrations, and dynamic imports. `BoundedRegexTests.EnumerateMatches_InstanceRegex_StartsAtRequestedOffset` fixes the no-prefix-rescan contract used by decorator arguments, while `EnumerateMatches_InstanceRightToLeftRegex_PreservesDefaultStartAndOrder` preserves instance-regex default direction.
   Direct instance-enumerator coverage in `BoundedRegexTests` also fixes lazy invalid-`startAt` validation, zero-length progress, `\G` continuation, explicit right-to-left start positions, one terminal timeout diagnostic after a successful prefix, early disposal without suffix work, unsupported `Reset`, and intentional LINQ compatibility.
-  PHP, Ruby, R, and Perl graph fixtures cover streamed attributes/docblocks/types, DSL command targets, namespace/member/resource references, and arrow calls. Keep nested token/type enumeration cap-aware.
+  PHP, Ruby, R, and Perl graph fixtures cover streamed attributes/docblocks/types, DSL command targets, namespace/member/resource references, and arrow calls. Keep nested token/type enumeration cap-aware. `ReferenceExtractorTests.Extract_PhpDocblockMethod_ReturnPrecedesParametersAtReferenceLimit` fixes PHP docblock preamble ordering and container state: an `@method` return type consumes the remaining reference slot before its parameter types while retaining the enclosing-class container snapshot.
   Secondary-language graph fixtures cover streamed Fortran, Visual Basic, F#, Pascal, Objective-C, Haskell, Elixir, Smalltalk, Lua, Dart, Razor, JSON, JavaScript, GitHub Actions, and C++ compound-requirement matches. `BoundedRegexTests.EnumerateMatches_StaticPatternCustomTimeout_ReturnsEmpty` and `EnumerateMatches_StaticPatternCustomTimeout_StopsAfterConsumerBreak` preserve explicit-timeout failure and early-disposal behavior.
   `PerformanceTests.ReferenceExtraction_BoundedDenseFSharpPipeline_StopsAtCapacity` fixes the bounded-list contract across line-phase handoffs and action-based call emitters: a 4,000-stage F# pipeline capped at one reference must not enumerate the unused stages. `PerformanceTests.ReferenceMatchEnumeration_BoundedListDoesNotRequestMatchAfterCapacity` and `ReferenceMatchEnumeration_ConcreteRegexDoesNotRequestSuffixAfterCapacity` prove that generic and concrete wrappers do not call the underlying enumerator's next `MoveNext()` after the cap is filled. `ReferenceMatchEnumeration_BelowCapacity_DoesNotAllocateWrapperEnumerators` keeps 10,000 ordinary generic below-cap scans free of wrapper-enumerator heap allocations. The blocking `net8.0` tests `BoundedRegexEnumeration_DirectNoMatchScansDoNotAllocateEnumerators` and `ReferenceMatchEnumeration_PrefilledCapacityDoesNotAllocateOrLookAhead` each run 10,000 concrete scans with a budget below 1,024 allocated bytes, covering both direct no-match enumeration and the already-full cap path.
   `PerformanceTests.ReferenceExtraction_PrologCallFreeRules_AvoidsPerLineLists` keeps 8,000 call-free Prolog rules from allocating empty goal lists or copying populated directive lists; its `net8.0` allocation budget is blocking.
@@ -1775,7 +1775,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   JVM graph fixture は Java type / module / method-reference、Kotlin type / infix / constructor、Scala contextual、Gradle / Groovy DSL の demand-driven match を検証します。cap-aware exit を追加するときも dense-line の順序を維持してください。
   Python graph fixture は decorator argument、annotation、runtime type check、typing factory、dataclass / framework integration、dynamic import の逐次走査を検証します。`BoundedRegexTests.EnumerateMatches_InstanceRegex_StartsAtRequestedOffset` は decorator argument が prefix を再走査しない契約を固定し、`EnumerateMatches_InstanceRightToLeftRegex_PreservesDefaultStartAndOrder` は instance regex の既定方向を維持します。
   `BoundedRegexTests` の direct instance-enumerator coverage はさらに、invalid `startAt` の遅延検証、zero-length の進行、`\G` continuation、right-to-left の明示開始位置、prefix 成功後に1回だけ記録して終了する timeout、suffix work を行わない早期 Dispose、未対応の `Reset`、意図的な LINQ 互換性を固定します。
-  PHP、Ruby、R、Perl の graph fixture は attribute / docblock / type、DSL command target、namespace / member / resource reference、arrow call の逐次走査を検証します。nested token / type enumeration も cap-aware のままにしてください。
+  PHP、Ruby、R、Perl の graph fixture は attribute / docblock / type、DSL command target、namespace / member / resource reference、arrow call の逐次走査を検証します。nested token / type enumeration も cap-aware のままにしてください。`ReferenceExtractorTests.Extract_PhpDocblockMethod_ReturnPrecedesParametersAtReferenceLimit` は PHP docblock preamble の順序と container state を固定し、`@method` の return type が parameter type より先に残り1枠を消費しつつ、enclosing class の container snapshot を保持することを検証します。
   secondary-language graph fixture は Fortran、Visual Basic、F#、Pascal、Objective-C、Haskell、Elixir、Smalltalk、Lua、Dart、Razor、JSON、JavaScript、GitHub Actions、C++ compound requirement の逐次走査を検証します。`BoundedRegexTests.EnumerateMatches_StaticPatternCustomTimeout_ReturnsEmpty` と `EnumerateMatches_StaticPatternCustomTimeout_StopsAfterConsumerBreak` は、明示 timeout の失敗時挙動と早期破棄を固定します。
   `PerformanceTests.ReferenceExtraction_BoundedDenseFSharpPipeline_StopsAtCapacity` は、行 phase の引き継ぎと action-based call emitter をまたぐ bounded-list 契約を固定します。上限1の4,000段 F# pipeline は未使用の段を列挙してはなりません。`PerformanceTests.ReferenceMatchEnumeration_BoundedListDoesNotRequestMatchAfterCapacity` と `ReferenceMatchEnumeration_ConcreteRegexDoesNotRequestSuffixAfterCapacity` は、generic / concrete wrapper が上限到達後に下位 enumerator の次の `MoveNext()` を呼ばないことを固定します。`ReferenceMatchEnumeration_BelowCapacity_DoesNotAllocateWrapperEnumerators` は通常の generic 上限未到達 scan 10,000回で wrapper enumerator の heap allocation がないことを固定します。blocking な `net8.0` test `BoundedRegexEnumeration_DirectNoMatchScansDoNotAllocateEnumerators` と `ReferenceMatchEnumeration_PrefilledCapacityDoesNotAllocateOrLookAhead` は、direct no-match と既に満杯の cap 経路をそれぞれ10,000回走査し、allocation を1,024 bytes未満に固定します。
   `PerformanceTests.ReferenceExtraction_PrologCallFreeRules_AvoidsPerLineLists` は8,000件の call-free Prolog rule で empty goal list と populated directive list の copy を防ぎます。`net8.0` の allocation budget は blocking です。
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCSharpDocumentationLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCSharpDocumentationLines.cs
new file mode 100644
index 000000000..099237f4a
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreCSharpDocumentationLines.cs
@@ -0,0 +1,78 @@
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitCoreCSharpDocumentationReferences(
+        in CoreDocumentationLineContext line,
+        ref bool inDelimitedDocComment)
+    {
+        if (line.CSharpLinesInsideMultilineStringContent == null
+            || line.CSharpLinesInsideMultilineStringContent[line.LineIndex]
+            || !TryGetCSharpXmlDocCommentSpan(
+                line.OriginalLine,
+                inDelimitedDocComment,
+                line.CSharpLinesInsideBlockComment?[line.LineIndex] ?? false,
+                out var docCommentStartIndex,
+                out var docCommentEndExclusive,
+                out var nextDelimitedDocComment))
+        {
+            return;
+        }
+
+        var docCommentText = line.OriginalLine[docCommentStartIndex..docCommentEndExclusive];
+        if (docCommentText.IndexOf("cref=\"", StringComparison.OrdinalIgnoreCase) >= 0)
+        {
+            EmitCoreCSharpDocCrefReferences(
+                in line,
+                docCommentText,
+                docCommentStartIndex,
+                docCommentEndExclusive,
+                nextDelimitedDocComment);
+        }
+
+        inDelimitedDocComment = nextDelimitedDocComment;
+    }
+
+    private static void EmitCoreCSharpDocCrefReferences(
+        in CoreDocumentationLineContext line,
+        string docCommentText,
+        int docCommentStartIndex,
+        int docCommentEndExclusive,
+        bool nextDelimitedDocComment)
+    {
+        var innermostContainer = line.ContainerResolver.Find(line.LineNumber);
+        var sameLineDeclarationStartColumn = GetCSharpSameLineDocumentedDeclarationStartColumn(
+            line.OriginalLine,
+            docCommentEndExclusive,
+            nextDelimitedDocComment);
+        var docContainer = FindDocumentedContainer(
+            line.ContainerCandidates,
+            line.StructuralLines[line.LineIndex],
+            line.PreparedLine,
+            line.CSharpAttributeRangesOnLine,
+            line.LineNumber,
+            sameLineDeclarationStartColumn);
+        if (docContainer == null
+            || (docContainer.StartLine != line.LineNumber
+                && !CanAttachCSharpXmlDocCommentToNextDeclaration(
+                    innermostContainer,
+                    line.Lookups.GetCSharpXmlDocAttachmentScopeCandidates(),
+                    line.CSharpAttributeRanges,
+                    line.PreparedLines,
+                    line.LineNumber,
+                    docContainer)))
+        {
+            return;
+        }
+
+        CSharpReferenceExtractor.EmitDocCrefReferences(
+            docCommentText,
+            line.References,
+            line.Seen,
+            line.FileId,
+            docCommentStartIndex,
+            docCommentText.Trim(),
+            line.LineNumber,
+            docContainer);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreDocumentationLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreDocumentationLines.cs
index a3c7dd1c8..d3c642254 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreDocumentationLines.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreDocumentationLines.cs
@@ -22,146 +22,77 @@ private readonly record struct CoreDocumentationLineContext(
         bool[]? CSharpLinesInsideMultilineStringContent,
         bool[]? CSharpLinesInsideBlockComment,
         List<(int start, int end)>? CSharpAttributeRangesOnLine,
-        List<(int start, int end)>?[]? CSharpAttributeRanges,
-        Func<SymbolRecord?>? GetPhpLineContainer);
+        List<(int start, int end)>?[]? CSharpAttributeRanges);
 
-    private static void EmitCoreDocumentationReferences(
-        in CoreDocumentationLineContext line,
-        ref bool csharpInDelimitedDocComment,
-        ref bool jvmInDelimitedDocComment,
-        ref bool phpInDocblock,
-        ref SymbolRecord? phpDocblockContainer,
-        ref HashSet<string>? phpDocblockPropertyNames)
+    private struct CoreDocumentationState
+    {
+        internal bool CSharpInDelimitedDocComment;
+        internal bool JvmInDelimitedDocComment;
+        internal PhpDocumentationState Php;
+    }
+
+    private static void EmitCoreLanguageDocumentationReferences(
+        CoreReferenceLoopContext loop,
+        CoreReferenceLoopState state,
+        int lineIndex,
+        int lineNumber,
+        string originalLine,
+        string preparedLine,
+        List<(int start, int end)>? csharpAttributeRangesOnLine)
     {
-        if (line.Language == "csharp"
-            && line.CSharpLinesInsideMultilineStringContent != null
-            && !(line.CSharpLinesInsideMultilineStringContent?[line.LineIndex] ?? false)
-            && TryGetCSharpXmlDocCommentSpan(
-                line.OriginalLine,
-                csharpInDelimitedDocComment,
-                line.CSharpLinesInsideBlockComment?[line.LineIndex] ?? false,
-                out var csharpDocCommentStartIndex,
-                out var csharpDocCommentEndExclusive,
-                out var nextCsharpDelimitedDocComment))
+        var request = loop.Request;
+        if (request.Language == "php")
         {
-            var csharpDocCommentText = line.OriginalLine[csharpDocCommentStartIndex..csharpDocCommentEndExclusive];
-            if (csharpDocCommentText.IndexOf("cref=\"", StringComparison.OrdinalIgnoreCase) >= 0)
-            {
-                var innermostContainer = line.ContainerResolver.Find(line.LineNumber);
-                var sameLineDeclarationStartColumn = GetCSharpSameLineDocumentedDeclarationStartColumn(
-                    line.OriginalLine,
-                    csharpDocCommentEndExclusive,
-                    nextCsharpDelimitedDocComment);
-                var docContainer = FindDocumentedContainer(
-                    line.ContainerCandidates,
-                    line.StructuralLines[line.LineIndex],
-                    line.PreparedLine,
-                    line.CSharpAttributeRangesOnLine,
-                    line.LineNumber,
-                    sameLineDeclarationStartColumn);
-                if (docContainer != null
-                    && (docContainer.StartLine == line.LineNumber
-                        || CanAttachCSharpXmlDocCommentToNextDeclaration(
-                            innermostContainer,
-                            line.Lookups.GetCSharpXmlDocAttachmentScopeCandidates(),
-                            line.CSharpAttributeRanges,
-                            line.PreparedLines,
-                            line.LineNumber,
-                            docContainer)))
-                {
-                    CSharpReferenceExtractor.EmitDocCrefReferences(
-                        csharpDocCommentText,
-                        line.References,
-                        line.Seen,
-                        line.FileId,
-                        csharpDocCommentStartIndex,
-                        csharpDocCommentText.Trim(),
-                        line.LineNumber,
-                        docContainer);
-                }
-            }
-            csharpInDelimitedDocComment = nextCsharpDelimitedDocComment;
+            var phpLine = new CorePhpDocumentationLineContext(
+                request.FileId,
+                originalLine,
+                lineNumber,
+                loop.References,
+                loop.Seen,
+                loop.ContainerResolver);
+            EmitPhpDocumentationReferences(
+                in phpLine,
+                ref state.Documentation.Php);
+            return;
         }
-        else if (line.Language is "java" or "kotlin"
-                 && TryGetJvmDocCommentSpan(
-                     line.OriginalLine,
-                     jvmInDelimitedDocComment,
-                     out var jvmDocCommentStartIndex,
-                     out var jvmDocCommentEndExclusive,
-                     out var jvmSameLineDeclarationStartColumn,
-                     out var nextJvmDelimitedDocComment))
-        {
-            if (jvmDocCommentEndExclusive > jvmDocCommentStartIndex)
-            {
-                var docContainer = FindJvmDocumentedContainer(
-                    line.ContainerCandidates,
-                    line.Lines,
-                    line.StructuralLines[line.LineIndex],
-                    line.LineNumber,
-                    jvmSameLineDeclarationStartColumn);
-                if (docContainer != null)
-                {
-                    var docText = line.OriginalLine[jvmDocCommentStartIndex..jvmDocCommentEndExclusive];
-                    EmitJvmDocLinkReferences(
-                        line.Language,
-                        docText,
-                        line.References,
-                        line.Seen,
-                        line.FileId,
-                        jvmDocCommentStartIndex,
-                        docText.Trim(),
-                        line.LineNumber,
-                        docContainer);
-                }
-            }
 
-            jvmInDelimitedDocComment = nextJvmDelimitedDocComment;
-        }
+        if (request.Language is not ("csharp" or "java" or "kotlin" or "r"))
+            return;
 
-        if (line.Language == "r")
-        {
-            var roxygenContext = line.OriginalLine.Trim();
-            if (roxygenContext.Length > 0)
-            {
-                RReferenceExtractor.EmitRoxygenImportFromReferences(
-                    line.OriginalLine,
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    roxygenContext,
-                    line.LineNumber,
-                    container: null);
-                RReferenceExtractor.EmitRoxygenImportReferences(
-                    line.OriginalLine,
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    roxygenContext,
-                    line.LineNumber,
-                    container: null);
-                RReferenceExtractor.EmitRoxygenMethodReferences(
-                    line.OriginalLine,
-                    line.References,
-                    line.Seen,
-                    line.FileId,
-                    roxygenContext,
-                    line.LineNumber,
-                    container: null);
-            }
-        }
+        var input = loop.Preparation;
+        var documentationLine = new CoreDocumentationLineContext(
+            request.FileId,
+            request.Language,
+            input.Lines,
+            input.PreparedLines,
+            input.StructuralLines,
+            lineIndex,
+            lineNumber,
+            originalLine,
+            preparedLine,
+            loop.References,
+            loop.Seen,
+            loop.ContainerCandidates,
+            loop.ContainerResolver,
+            loop.Lookups,
+            input.CSharpLinesInsideMultilineStringContent,
+            input.CSharpLinesInsideBlockComment,
+            csharpAttributeRangesOnLine,
+            loop.CSharpAttributeRanges);
+        EmitCoreDocumentationReferences(
+            in documentationLine,
+            ref state.Documentation);
+    }
 
-        if (line.Language == "php")
-        {
-            EmitPhpLinePreambleReferences(
-                line.OriginalLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.LineNumber,
-                line.GetPhpLineContainer!,
-                ref phpInDocblock,
-                ref phpDocblockContainer,
-                ref phpDocblockPropertyNames);
-        }
+    private static void EmitCoreDocumentationReferences(
+        in CoreDocumentationLineContext line,
+        ref CoreDocumentationState state)
+    {
+        if (line.Language == "csharp")
+            EmitCoreCSharpDocumentationReferences(in line, ref state.CSharpInDelimitedDocComment);
+        else if (line.Language is "java" or "kotlin")
+            EmitCoreJvmDocumentationReferences(in line, ref state.JvmInDelimitedDocComment);
+        else if (line.Language == "r")
+            EmitRDocumentationReferences(in line);
     }
 }
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreJvmDocumentationLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreJvmDocumentationLines.cs
new file mode 100644
index 000000000..13440c4dc
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreJvmDocumentationLines.cs
@@ -0,0 +1,59 @@
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitCoreJvmDocumentationReferences(
+        in CoreDocumentationLineContext line,
+        ref bool inDelimitedDocComment)
+    {
+        if (!TryGetJvmDocCommentSpan(
+                line.OriginalLine,
+                inDelimitedDocComment,
+                out var docCommentStartIndex,
+                out var docCommentEndExclusive,
+                out var sameLineDeclarationStartColumn,
+                out var nextDelimitedDocComment))
+        {
+            return;
+        }
+
+        if (docCommentEndExclusive > docCommentStartIndex)
+        {
+            EmitCoreJvmDocLinkReferences(
+                in line,
+                docCommentStartIndex,
+                docCommentEndExclusive,
+                sameLineDeclarationStartColumn);
+        }
+
+        inDelimitedDocComment = nextDelimitedDocComment;
+    }
+
+    private static void EmitCoreJvmDocLinkReferences(
+        in CoreDocumentationLineContext line,
+        int docCommentStartIndex,
+        int docCommentEndExclusive,
+        int sameLineDeclarationStartColumn)
+    {
+        var docContainer = FindJvmDocumentedContainer(
+            line.ContainerCandidates,
+            line.Lines,
+            line.StructuralLines[line.LineIndex],
+            line.LineNumber,
+            sameLineDeclarationStartColumn);
+        if (docContainer == null)
+            return;
+
+        var docText = line.OriginalLine[docCommentStartIndex..docCommentEndExclusive];
+        EmitJvmDocLinkReferences(
+            line.Language,
+            docText,
+            line.References,
+            line.Seen,
+            line.FileId,
+            docCommentStartIndex,
+            docText.Trim(),
+            line.LineNumber,
+            docContainer);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CorePhpDocumentationLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CorePhpDocumentationLines.cs
new file mode 100644
index 000000000..2b965e078
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CorePhpDocumentationLines.cs
@@ -0,0 +1,217 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private readonly record struct CorePhpDocumentationLineContext(
+        long FileId,
+        string OriginalLine,
+        int LineNumber,
+        List<ReferenceRecord> References,
+        ReferenceDedupeSet Seen,
+        InnermostContainerResolver ContainerResolver);
+
+    private struct PhpDocumentationState
+    {
+        internal bool InDocblock;
+        internal SymbolRecord? DocblockContainer;
+        internal HashSet<string>? DocblockPropertyNames;
+    }
+
+    private struct PhpLineContainerCache
+    {
+        private readonly InnermostContainerResolver _resolver;
+        private readonly int _lineNumber;
+        private bool _resolved;
+        private SymbolRecord? _container;
+
+        internal PhpLineContainerCache(
+            InnermostContainerResolver resolver,
+            int lineNumber)
+        {
+            _resolver = resolver;
+            _lineNumber = lineNumber;
+        }
+
+        internal SymbolRecord? Resolve()
+        {
+            if (!_resolved)
+            {
+                _container = _resolver.Find(_lineNumber);
+                _resolved = true;
+            }
+
+            return _container;
+        }
+    }
+
+    private static void EmitPhpDocumentationReferences(
+        in CorePhpDocumentationLineContext line,
+        ref PhpDocumentationState state)
+    {
+        var containerCache = new PhpLineContainerCache(
+            line.ContainerResolver,
+            line.LineNumber);
+        EmitPhpAttributeDocumentationReferences(in line, ref containerCache);
+        BeginPhpDocblockIfNeeded(in line, ref state, ref containerCache);
+
+        var context = line.OriginalLine.Trim();
+        if (context.Length > 0)
+        {
+            EmitPhpDocblockSignatureReferences(in line, context, ref state, ref containerCache);
+            EmitPhpDocblockInheritanceReferences(in line, context, ref state, ref containerCache);
+            EmitPhpDocblockPropertyReferences(in line, context, ref state, ref containerCache);
+            EmitPhpDocblockMethodReferences(in line, context, ref state, ref containerCache);
+            EmitPhpDocblockTemplateAndAliasReferences(in line, context, ref state, ref containerCache);
+        }
+
+        EndPhpDocblockIfNeeded(in line, ref state);
+    }
+
+    private static void EmitPhpAttributeDocumentationReferences(
+        in CorePhpDocumentationLineContext line,
+        ref PhpLineContainerCache containerCache)
+    {
+        if (!line.OriginalLine.Contains("#[", StringComparison.Ordinal))
+            return;
+
+        var context = line.OriginalLine.Trim();
+        if (context.Length == 0)
+            return;
+
+        PhpReferenceExtractor.EmitAttributeReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, context,
+            line.LineNumber, containerCache.Resolve());
+    }
+
+    private static void BeginPhpDocblockIfNeeded(
+        in CorePhpDocumentationLineContext line,
+        ref PhpDocumentationState state,
+        ref PhpLineContainerCache containerCache)
+    {
+        if (line.OriginalLine.IndexOf("/**", StringComparison.Ordinal) < 0)
+            return;
+
+        state.InDocblock = true;
+        state.DocblockContainer = containerCache.Resolve();
+        state.DocblockPropertyNames = null;
+    }
+
+    private static void EmitPhpDocblockSignatureReferences(
+        in CorePhpDocumentationLineContext line,
+        string context,
+        ref PhpDocumentationState state,
+        ref PhpLineContainerCache containerCache)
+    {
+        if (line.OriginalLine.Contains("param", StringComparison.OrdinalIgnoreCase))
+            PhpReferenceExtractor.EmitDocblockParamTypeReferences(
+                line.OriginalLine, line.References, line.Seen, line.FileId, context,
+                line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+        if (line.OriginalLine.Contains("return", StringComparison.OrdinalIgnoreCase))
+            PhpReferenceExtractor.EmitDocblockReturnTypeReferences(
+                line.OriginalLine, line.References, line.Seen, line.FileId, context,
+                line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+        if (line.OriginalLine.Contains("var", StringComparison.OrdinalIgnoreCase))
+            PhpReferenceExtractor.EmitDocblockVarTypeReferences(
+                line.OriginalLine, line.References, line.Seen, line.FileId, context,
+                line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+        if (line.OriginalLine.Contains("@throws", StringComparison.OrdinalIgnoreCase))
+            PhpReferenceExtractor.EmitDocblockThrowsTypeReferences(
+                line.OriginalLine, line.References, line.Seen, line.FileId, context,
+                line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+    }
+
+    private static void EmitPhpDocblockInheritanceReferences(
+        in CorePhpDocumentationLineContext line,
+        string context,
+        ref PhpDocumentationState state,
+        ref PhpLineContainerCache containerCache)
+    {
+        if (line.OriginalLine.Contains("extends", StringComparison.OrdinalIgnoreCase))
+            PhpReferenceExtractor.EmitDocblockExtendsTypeReferences(
+                line.OriginalLine, line.References, line.Seen, line.FileId, context,
+                line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+        if (line.OriginalLine.Contains("implements", StringComparison.OrdinalIgnoreCase))
+            PhpReferenceExtractor.EmitDocblockImplementsTypeReferences(
+                line.OriginalLine, line.References, line.Seen, line.FileId, context,
+                line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+        if (line.OriginalLine.Contains("@mixin", StringComparison.OrdinalIgnoreCase))
+            PhpReferenceExtractor.EmitDocblockMixinTypeReferences(
+                line.OriginalLine, line.References, line.Seen, line.FileId, context,
+                line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+    }
+
+    private static void EmitPhpDocblockPropertyReferences(
+        in CorePhpDocumentationLineContext line,
+        string context,
+        ref PhpDocumentationState state,
+        ref PhpLineContainerCache containerCache)
+    {
+        if (!line.OriginalLine.Contains("property", StringComparison.OrdinalIgnoreCase))
+            return;
+
+        PhpReferenceExtractor.EmitDocblockPropertyTypeReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, context,
+            line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache),
+            state.InDocblock, ref state.DocblockPropertyNames);
+    }
+
+    private static void EmitPhpDocblockMethodReferences(
+        in CorePhpDocumentationLineContext line,
+        string context,
+        ref PhpDocumentationState state,
+        ref PhpLineContainerCache containerCache)
+    {
+        if (!line.OriginalLine.Contains("@method", StringComparison.OrdinalIgnoreCase))
+            return;
+
+        PhpReferenceExtractor.EmitDocblockMethodReturnTypeReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, context,
+            line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+        PhpReferenceExtractor.EmitDocblockMethodParameterTypeReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, context,
+            line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+    }
+
+    private static void EmitPhpDocblockTemplateAndAliasReferences(
+        in CorePhpDocumentationLineContext line,
+        string context,
+        ref PhpDocumentationState state,
+        ref PhpLineContainerCache containerCache)
+    {
+        if (line.OriginalLine.Contains("@template", StringComparison.OrdinalIgnoreCase))
+            PhpReferenceExtractor.EmitDocblockTemplateBoundTypeReferences(
+                line.OriginalLine, line.References, line.Seen, line.FileId, context,
+                line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+        if (!line.OriginalLine.Contains("type", StringComparison.OrdinalIgnoreCase))
+            return;
+
+        PhpReferenceExtractor.EmitDocblockTypeAliasTargetReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, context,
+            line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+        PhpReferenceExtractor.EmitDocblockImportTypeSourceReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, context,
+            line.LineNumber, ResolvePhpDocblockContainer(ref state, ref containerCache));
+    }
+
+    private static SymbolRecord? ResolvePhpDocblockContainer(
+        ref PhpDocumentationState state,
+        ref PhpLineContainerCache containerCache)
+        => state.InDocblock ? state.DocblockContainer : containerCache.Resolve();
+
+    private static void EndPhpDocblockIfNeeded(
+        in CorePhpDocumentationLineContext line,
+        ref PhpDocumentationState state)
+    {
+        if (!state.InDocblock
+            || line.OriginalLine.IndexOf("*/", StringComparison.Ordinal) < 0)
+        {
+            return;
+        }
+
+        state.InDocblock = false;
+        state.DocblockContainer = null;
+        state.DocblockPropertyNames = null;
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CorePhpLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CorePhpLines.cs
new file mode 100644
index 000000000..f17ba4496
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CorePhpLines.cs
@@ -0,0 +1,62 @@
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static void EmitPhpLineReferences(in CoreReferenceLineContext line)
+    {
+        if (line.Language != "php")
+            return;
+
+        EmitPhpTypeLineReferences(in line);
+        EmitPhpImportLineReferences(in line);
+        EmitPhpMemberLineReferences(in line);
+    }
+
+    private static void EmitPhpTypeLineReferences(
+        in CoreReferenceLineContext line)
+    {
+        PhpReferenceExtractor.EmitStaticAccessReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+        PhpReferenceExtractor.EmitInstanceofReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+        PhpReferenceExtractor.EmitCatchTypeReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+        PhpReferenceExtractor.EmitReturnTypeReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+        PhpReferenceExtractor.EmitParameterTypeReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+        PhpReferenceExtractor.EmitPropertyTypeReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+        PhpReferenceExtractor.EmitInheritanceTypeReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+    }
+
+    private static void EmitPhpImportLineReferences(
+        in CoreReferenceLineContext line)
+    {
+        PhpReferenceExtractor.EmitUseTypeReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+        PhpReferenceExtractor.EmitUseFunctionReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+        PhpReferenceExtractor.EmitUseConstReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+    }
+
+    private static void EmitPhpMemberLineReferences(
+        in CoreReferenceLineContext line)
+    {
+        PhpReferenceExtractor.EmitObjectMemberAccessReferences(
+            line.PreparedLine, line.References, line.Seen, line.FileId, line.Context,
+            line.LineNumber, line.Container);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreRLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreRLines.cs
index 3ebc1bc49..49e597d7a 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreRLines.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreRLines.cs
@@ -2,6 +2,24 @@ namespace CodeIndex.Indexer;
 
 public static partial class ReferenceExtractor
 {
+    private static void EmitRDocumentationReferences(
+        in CoreDocumentationLineContext line)
+    {
+        var context = line.OriginalLine.Trim();
+        if (context.Length == 0)
+            return;
+
+        RReferenceExtractor.EmitRoxygenImportFromReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, context,
+            line.LineNumber, container: null);
+        RReferenceExtractor.EmitRoxygenImportReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, context,
+            line.LineNumber, container: null);
+        RReferenceExtractor.EmitRoxygenMethodReferences(
+            line.OriginalLine, line.References, line.Seen, line.FileId, context,
+            line.LineNumber, container: null);
+    }
+
     private static void EmitRLineReferences(in CoreReferenceLineContext line)
     {
         EmitRNamespaceAndDispatchReferences(in line);
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs
index 5ba816590..d658e877c 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLine.cs
@@ -220,59 +220,15 @@ private static bool EmitCoreDocumentationAndSpecialLineReferences(
         out string sourceContext)
     {
         var request = loop.Request;
-        var input = loop.Preparation;
         var lineNumber = lineIndex + 1;
-        if (request.Language is "csharp" or "java" or "kotlin" or "r" or "php")
-        {
-            Func<SymbolRecord?>? getPhpLineContainer = null;
-            if (request.Language == "php")
-            {
-                SymbolRecord? phpLineContainer = null;
-                var phpLineContainerResolved = false;
-
-                SymbolRecord? GetPhpLineContainer()
-                {
-                    if (!phpLineContainerResolved)
-                    {
-                        phpLineContainer =
-                            loop.ContainerResolver.Find(lineNumber);
-                        phpLineContainerResolved = true;
-                    }
-
-                    return phpLineContainer;
-                }
-
-                getPhpLineContainer = GetPhpLineContainer;
-            }
-
-            var documentationLine = new CoreDocumentationLineContext(
-                request.FileId,
-                request.Language,
-                input.Lines,
-                input.PreparedLines,
-                input.StructuralLines,
-                lineIndex,
-                lineNumber,
-                originalLine,
-                preparedLine,
-                loop.References,
-                loop.Seen,
-                loop.ContainerCandidates,
-                loop.ContainerResolver,
-                loop.Lookups,
-                input.CSharpLinesInsideMultilineStringContent,
-                input.CSharpLinesInsideBlockComment,
-                csharpAttributeRangesOnLine,
-                loop.CSharpAttributeRanges,
-                getPhpLineContainer);
-            EmitCoreDocumentationReferences(
-                in documentationLine,
-                ref state.CSharpInDelimitedDocComment,
-                ref state.JvmInDelimitedDocComment,
-                ref state.PhpInDocblock,
-                ref state.PhpDocblockContainer,
-                ref state.PhpDocblockPropertyNames);
-        }
+        EmitCoreLanguageDocumentationReferences(
+            loop,
+            state,
+            lineIndex,
+            lineNumber,
+            originalLine,
+            preparedLine,
+            csharpAttributeRangesOnLine);
 
         if (preparedLineIsWhiteSpace
             && request.Language
@@ -323,4 +279,5 @@ is not ("cmake"
             state.MarkupSchemaState);
         return true;
     }
+
 }
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
index 5ed5ee27d..4fb6dfe7a 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
@@ -62,11 +62,7 @@ private sealed class CoreReferenceLoopState
         internal bool XamlInXmlComment;
         internal readonly XamlReferenceExtractor.BindingPropertyElementState? XamlBindingPropertyElementState;
         internal readonly XamlReferenceExtractor.BindingMarkupExtensionState? XamlBindingMarkupExtensionState;
-        internal bool CSharpInDelimitedDocComment;
-        internal bool JvmInDelimitedDocComment;
-        internal bool PhpInDocblock;
-        internal SymbolRecord? PhpDocblockContainer;
-        internal HashSet<string>? PhpDocblockPropertyNames;
+        internal CoreDocumentationState Documentation;
         internal readonly MarkupSchemaReferenceExtractor.MarkupState? MarkupSchemaState;
         internal readonly CssReferenceExtractor.SassLoudCommentState? SassPreparedCommentState;
         internal readonly CssReferenceExtractor.SassLoudCommentState? SassOriginalCommentState;
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
index ccb08c0de..d10e1a60d 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferencePhases.cs
@@ -121,7 +121,8 @@ private static CoreReferenceLineFlow EmitCoreRemainingReferencePhases(
         if (line.Language is "csharp" or "java")
             EmitParenlessInitializerReferences(in line);
 
-        EmitPhpAndScssLineReferences(in line);
+        EmitScssLineReferences(in line);
+        EmitPhpLineReferences(in line);
 
         if (ReferenceLimitReached(line.References))
             return CoreReferenceLineFlow.StopExtraction;
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreSpecializedLines.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreSpecializedLines.cs
index f36c9f97a..68ee9bd9d 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreSpecializedLines.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreSpecializedLines.cs
@@ -275,121 +275,19 @@ private static void EmitParenlessInitializerReferences(
         }
     }
 
-    private static void EmitPhpAndScssLineReferences(
+    private static void EmitScssLineReferences(
         in CoreReferenceLineContext line)
     {
-        if (line.Language == "css")
-        {
-            CssReferenceExtractor.EmitScss(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-        }
-
-        if (line.Language == "php")
-        {
-            PhpReferenceExtractor.EmitStaticAccessReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-
-            PhpReferenceExtractor.EmitInstanceofReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-
-            PhpReferenceExtractor.EmitCatchTypeReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-
-            PhpReferenceExtractor.EmitReturnTypeReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-
-            PhpReferenceExtractor.EmitParameterTypeReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-
-            PhpReferenceExtractor.EmitPropertyTypeReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-
-            PhpReferenceExtractor.EmitInheritanceTypeReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-
-            PhpReferenceExtractor.EmitUseTypeReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-
-            PhpReferenceExtractor.EmitUseFunctionReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-
-            PhpReferenceExtractor.EmitUseConstReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
+        if (line.Language != "css")
+            return;
 
-            PhpReferenceExtractor.EmitObjectMemberAccessReferences(
-                line.PreparedLine,
-                line.References,
-                line.Seen,
-                line.FileId,
-                line.Context,
-                line.LineNumber,
-                line.Container);
-        }
+        CssReferenceExtractor.EmitScss(
+            line.PreparedLine,
+            line.References,
+            line.Seen,
+            line.FileId,
+            line.Context,
+            line.LineNumber,
+            line.Container);
     }
 }
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.ReferenceRecords.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.ReferenceRecords.cs
index 02b1c361d..8cdd08dad 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.ReferenceRecords.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.ReferenceRecords.cs
@@ -8,208 +8,6 @@ namespace CodeIndex.Indexer;
 
 public static partial class ReferenceExtractor
 {
-    private static void EmitPhpLinePreambleReferences(
-        string originalLine,
-        List<ReferenceRecord> references,
-        ReferenceDedupeSet seen,
-        long fileId,
-        int lineNumber,
-        Func<SymbolRecord?> getLineContainer,
-        ref bool inDocblock,
-        ref SymbolRecord? docblockContainer,
-        ref HashSet<string>? docblockPropertyNames)
-    {
-        if (originalLine.Contains("#[", StringComparison.Ordinal))
-        {
-            var attributeContext = originalLine.Trim();
-            if (attributeContext.Length > 0)
-            {
-                PhpReferenceExtractor.EmitAttributeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    attributeContext,
-                    lineNumber,
-                    getLineContainer());
-            }
-        }
-
-        if (originalLine.IndexOf("/**", StringComparison.Ordinal) >= 0)
-        {
-            inDocblock = true;
-            docblockContainer = getLineContainer();
-            docblockPropertyNames = null;
-        }
-
-        var docblockContext = originalLine.Trim();
-        if (docblockContext.Length > 0)
-        {
-            if (originalLine.Contains("param", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockParamTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-
-            if (originalLine.Contains("return", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockReturnTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-
-            if (originalLine.Contains("var", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockVarTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-
-            if (originalLine.Contains("@throws", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockThrowsTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-
-            if (originalLine.Contains("extends", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockExtendsTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-
-            if (originalLine.Contains("implements", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockImplementsTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-
-            if (originalLine.Contains("@mixin", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockMixinTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-
-            if (originalLine.Contains("property", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockPropertyTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer),
-                    inDocblock,
-                    ref docblockPropertyNames);
-            }
-
-            if (originalLine.Contains("@method", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockMethodReturnTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-                PhpReferenceExtractor.EmitDocblockMethodParameterTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-
-            if (originalLine.Contains("@template", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockTemplateBoundTypeReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-
-            if (originalLine.Contains("type", StringComparison.OrdinalIgnoreCase))
-            {
-                PhpReferenceExtractor.EmitDocblockTypeAliasTargetReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-                PhpReferenceExtractor.EmitDocblockImportTypeSourceReferences(
-                    originalLine,
-                    references,
-                    seen,
-                    fileId,
-                    docblockContext,
-                    lineNumber,
-                    ResolvePhpDocblockContainer(inDocblock, docblockContainer, getLineContainer));
-            }
-        }
-
-        if (inDocblock && originalLine.IndexOf("*/", StringComparison.Ordinal) >= 0)
-        {
-            inDocblock = false;
-            docblockContainer = null;
-            docblockPropertyNames = null;
-        }
-    }
-
-    private static SymbolRecord? ResolvePhpDocblockContainer(
-        bool inDocblock,
-        SymbolRecord? docblockContainer,
-        Func<SymbolRecord?> getLineContainer)
-        => inDocblock ? docblockContainer : getLineContainer();
-
     internal static void AddReference(
         List<ReferenceRecord> references,
         ReferenceDedupeSet seen,
diff --git a/tests/CodeIndex.Tests/ReferenceExtractorTests.cs b/tests/CodeIndex.Tests/ReferenceExtractorTests.cs
index a5363f268..d386fcafd 100644
--- a/tests/CodeIndex.Tests/ReferenceExtractorTests.cs
+++ b/tests/CodeIndex.Tests/ReferenceExtractorTests.cs
@@ -5685,6 +5685,33 @@ final class Processor {}
         Assert.DoesNotContain(references, reference => reference.SymbolName == "message" && reference.ReferenceKind == "type_reference");
     }
 
+    [Fact]
+    public void Extract_PhpDocblockMethod_ReturnPrecedesParametersAtReferenceLimit()
+    {
+        const string content = """
+            <?php
+            final class Processor {
+                /**
+                 * @method Result process(InputMessage $message)
+                 */
+            }
+            ?>
+            """;
+
+        var symbols = SymbolExtractor.Extract(1, "php", content);
+        var references = ReferenceExtractor.Extract(
+            1,
+            "php",
+            content,
+            symbols,
+            maxReferenceCount: 1);
+
+        var reference = Assert.Single(references);
+        Assert.Equal("Result", reference.SymbolName);
+        Assert.Equal("type_reference", reference.ReferenceKind);
+        Assert.Equal("Processor", reference.ContainerName);
+    }
+
     [Fact]
     public void Extract_PhpDocblockTemplateBounds_EmitTypeReferences()
     {

From c471e7f9dea265b7faae71b39f9d763e967c3981 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 16:35:02 +0900
Subject: [PATCH 22/45] Decompose existing database validation

---
 .../DbContext.ExistingDatabaseValidation.cs   | 200 ++++++++++
 .../DbContext.ExistingDatabaseValidator.cs    | 253 +++++++++++++
 src/CodeIndex/Database/DbContext.cs           | 350 ------------------
 3 files changed, 453 insertions(+), 350 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbContext.ExistingDatabaseValidation.cs
 create mode 100644 src/CodeIndex/Database/DbContext.ExistingDatabaseValidator.cs

diff --git a/src/CodeIndex/Database/DbContext.ExistingDatabaseValidation.cs b/src/CodeIndex/Database/DbContext.ExistingDatabaseValidation.cs
new file mode 100644
index 000000000..45be44bb2
--- /dev/null
+++ b/src/CodeIndex/Database/DbContext.ExistingDatabaseValidation.cs
@@ -0,0 +1,200 @@
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+internal enum ExistingCodeIndexDbValidationFailure
+{
+    None,
+    Missing,
+    Inaccessible,
+    InvalidTarget,
+    InvalidDatabase,
+    SchemaTooNew,
+    Exception,
+}
+
+public partial class DbContext
+{
+    internal const string DatabaseOpenMissingCategory = "missing_database";
+    internal const string DatabaseOpenPermissionCategory = "permission_denied";
+    internal const string DatabaseOpenSidecarCategory = "sidecar_failure";
+    internal const string DatabaseOpenInvalidUriCategory = "invalid_uri";
+    internal const string DatabaseOpenUnknownCategory = "unknown_open_failure";
+    private const int SqliteCantOpenDirtyWal = 14 | (5 << 8);
+
+    public static bool TryValidateExistingCodeIndexDb(
+        string dbPath,
+        out string message,
+        out bool isNotFound,
+        CancellationToken cancellationToken = default)
+        => TryValidateExistingCodeIndexDb(
+            dbPath,
+            requireWritable: true,
+            requireSupportedUserVersion: false,
+            out message,
+            out isNotFound,
+            out _,
+            cancellationToken);
+
+    internal static bool TryValidateExistingCodeIndexDb(
+        string dbPath,
+        bool requireWritable,
+        bool requireSupportedUserVersion,
+        out string message,
+        out bool isNotFound,
+        out bool isSchemaTooNew,
+        CancellationToken cancellationToken = default)
+        => TryValidateExistingCodeIndexDb(
+            dbPath,
+            requireWritable,
+            requireSupportedUserVersion,
+            out message,
+            out isNotFound,
+            out isSchemaTooNew,
+            out _,
+            out _,
+            cancellationToken);
+
+    internal static bool TryValidateExistingCodeIndexDb(
+        string dbPath,
+        bool requireWritable,
+        bool requireSupportedUserVersion,
+        out string message,
+        out bool isNotFound,
+        out bool isSchemaTooNew,
+        out ExistingCodeIndexDbValidationFailure validationFailure,
+        out Exception? validationException,
+        CancellationToken cancellationToken = default)
+        => TryValidateExistingCodeIndexDb(
+            dbPath,
+            openTarget =>
+            {
+                var mode = requireWritable
+                    ? SqliteConnectionPolicyMode.ReadWrite
+                    : SqliteConnectionPolicyMode.ReadOnly;
+                return new SqliteConnection(SqliteConnectionPolicy.BuildConnectionString(openTarget, mode));
+            },
+            static connection => connection.Open(),
+            sleep: null,
+            requireWritable,
+            requireSupportedUserVersion,
+            out message,
+            out isNotFound,
+            out isSchemaTooNew,
+            out validationFailure,
+            out validationException,
+            cancellationToken);
+
+    internal static bool TryValidateExistingCodeIndexDb(
+        string dbPath,
+        Func<string, SqliteConnection> createConnection,
+        Action<SqliteConnection> openConnection,
+        Action<int>? sleep,
+        out string message,
+        out bool isNotFound,
+        CancellationToken cancellationToken = default)
+        => TryValidateExistingCodeIndexDb(
+            dbPath,
+            createConnection,
+            openConnection,
+            sleep,
+            requireWritable: true,
+            requireSupportedUserVersion: false,
+            out message,
+            out isNotFound,
+            out _,
+            out _,
+            out _,
+            cancellationToken);
+
+    internal static bool TryValidateExistingCodeIndexDb(
+        string dbPath,
+        Func<string, SqliteConnection> createConnection,
+        Action<SqliteConnection> openConnection,
+        Action<int>? sleep,
+        out string message,
+        out bool isNotFound,
+        out Exception? validationException,
+        CancellationToken cancellationToken = default)
+        => TryValidateExistingCodeIndexDb(
+            dbPath,
+            createConnection,
+            openConnection,
+            sleep,
+            requireWritable: true,
+            requireSupportedUserVersion: false,
+            out message,
+            out isNotFound,
+            out _,
+            out _,
+            out validationException,
+            cancellationToken);
+
+    private static bool TryValidateExistingCodeIndexDb(
+        string dbPath,
+        Func<string, SqliteConnection> createConnection,
+        Action<SqliteConnection> openConnection,
+        Action<int>? sleep,
+        bool requireWritable,
+        bool requireSupportedUserVersion,
+        out string message,
+        out bool isNotFound,
+        out bool isSchemaTooNew,
+        out ExistingCodeIndexDbValidationFailure validationFailure,
+        out Exception? validationException,
+        CancellationToken cancellationToken = default)
+        => ProjectValidationResult(
+            ExistingCodeIndexDbValidator.Validate(new ValidationRequest(
+                dbPath,
+                createConnection,
+                openConnection,
+                sleep,
+                requireWritable,
+                requireSupportedUserVersion,
+                cancellationToken)),
+            out message,
+            out isNotFound,
+            out isSchemaTooNew,
+            out validationFailure,
+            out validationException);
+
+    private static bool ProjectValidationResult(
+        ValidationResult result,
+        out string message,
+        out bool isNotFound,
+        out bool isSchemaTooNew,
+        out ExistingCodeIndexDbValidationFailure validationFailure,
+        out Exception? validationException)
+    {
+        message = result.Message;
+        isNotFound = result.IsNotFound;
+        isSchemaTooNew = result.IsSchemaTooNew;
+        validationFailure = result.Failure;
+        validationException = result.Exception;
+        return result.IsValid;
+    }
+
+    internal static string ClassifyCantOpenFailure(string dbPath, int sqliteExtendedErrorCode)
+        => ExistingCodeIndexDbValidator.ClassifyCantOpenFailure(dbPath, sqliteExtendedErrorCode);
+
+    private readonly record struct ValidationRequest(
+        string DbPath,
+        Func<string, SqliteConnection> CreateConnection,
+        Action<SqliteConnection> OpenConnection,
+        Action<int>? Sleep,
+        bool RequireWritable,
+        bool RequireSupportedUserVersion,
+        CancellationToken CancellationToken);
+
+    private readonly record struct ValidationResult(
+        bool IsValid,
+        string Message,
+        bool IsNotFound,
+        bool IsSchemaTooNew,
+        ExistingCodeIndexDbValidationFailure Failure,
+        Exception? Exception)
+    {
+        internal static ValidationResult Valid { get; } = new(
+            true, string.Empty, false, false, ExistingCodeIndexDbValidationFailure.None, null);
+    }
+}
diff --git a/src/CodeIndex/Database/DbContext.ExistingDatabaseValidator.cs b/src/CodeIndex/Database/DbContext.ExistingDatabaseValidator.cs
new file mode 100644
index 000000000..e696bc88a
--- /dev/null
+++ b/src/CodeIndex/Database/DbContext.ExistingDatabaseValidator.cs
@@ -0,0 +1,253 @@
+using CodeIndex.Diagnostics;
+using CodeIndex.Indexer;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbContext
+{
+    private static class ExistingCodeIndexDbValidator
+    {
+        internal static ValidationResult Validate(ValidationRequest request)
+        {
+            request.CancellationToken.ThrowIfCancellationRequested();
+            var targetFailure = ValidateTarget(request, out var openTarget);
+            if (targetFailure.HasValue)
+                return targetFailure.Value;
+
+            var preflightFailure = ValidateFileSystemTarget(request.DbPath, openTarget);
+            if (preflightFailure.HasValue)
+                return preflightFailure.Value;
+
+            try
+            {
+                return OpenAndInspect(request, openTarget);
+            }
+            catch (Exception ex) when (ex is SqliteException or CodeIndexException)
+            {
+                return ProjectException(request.DbPath, openTarget, ex);
+            }
+        }
+
+        private static ValidationResult? ValidateTarget(ValidationRequest request, out string openTarget)
+        {
+            openTarget = request.DbPath;
+            if (!SqliteFileUri.StartsWithFileScheme(request.DbPath))
+                return null;
+
+            if (!SqliteFileUri.TryValidateBounds(request.DbPath, out var boundsError))
+            {
+                return Failure(
+                    ExistingCodeIndexDbValidationFailure.InvalidTarget,
+                    FormatDatabaseOpenFailure(
+                        DatabaseOpenInvalidUriCategory,
+                        request.DbPath,
+                        boundsError?.Message ?? "Invalid SQLite file URI."));
+            }
+
+            if (request.RequireWritable && SqliteFileUri.RequestsReadOnly(request.DbPath))
+            {
+                return Failure(
+                    ExistingCodeIndexDbValidationFailure.Inaccessible,
+                    $"database must be writable: {request.DbPath}");
+            }
+
+            if (!TryGetLocalPath(request.DbPath, out var normalized, out var pathFailureReason)
+                || normalized == null)
+            {
+                return Failure(
+                    ExistingCodeIndexDbValidationFailure.InvalidTarget,
+                    FormatDatabaseOpenFailure(
+                        DatabaseOpenInvalidUriCategory,
+                        request.DbPath,
+                        pathFailureReason));
+            }
+
+            openTarget = normalized;
+            return null;
+        }
+
+        private static ValidationResult? ValidateFileSystemTarget(string dbPath, string openTarget)
+        {
+            var preflight = ProbeDatabasePath(openTarget);
+            if (preflight is not (DatabasePathProbe.Missing
+                or DatabasePathProbe.PermissionDenied
+                or DatabasePathProbe.Directory))
+            {
+                return null;
+            }
+
+            var category = preflight switch
+            {
+                DatabasePathProbe.Missing => DatabaseOpenMissingCategory,
+                DatabasePathProbe.PermissionDenied => DatabaseOpenPermissionCategory,
+                _ => DatabaseOpenUnknownCategory,
+            };
+            var failure = preflight switch
+            {
+                DatabasePathProbe.Missing => ExistingCodeIndexDbValidationFailure.Missing,
+                DatabasePathProbe.PermissionDenied => ExistingCodeIndexDbValidationFailure.Inaccessible,
+                _ => ExistingCodeIndexDbValidationFailure.InvalidTarget,
+            };
+            return Failure(
+                failure,
+                FormatDatabaseOpenFailure(category, dbPath),
+                isNotFound: category == DatabaseOpenMissingCategory);
+        }
+
+        private static ValidationResult OpenAndInspect(ValidationRequest request, string openTarget)
+        {
+            using var connection = request.RequireWritable
+                ? OpenSqliteConnectionWithRetry(
+                    () => request.CreateConnection(openTarget),
+                    request.OpenConnection,
+                    request.Sleep,
+                    dbPath: request.DbPath,
+                    cancellationToken: request.CancellationToken)
+                : OpenArtifactPreservingQueryOnly(request.DbPath);
+            return InspectSchema(connection, request);
+        }
+
+        private static ValidationResult InspectSchema(SqliteConnection connection, ValidationRequest request)
+        {
+            using var command = connection.CreateCommand();
+            command.CommandText = SqliteCommandPolicy.PragmaSql("application_id");
+            if (SqliteCommandPolicy.ReadInt64Scalar(command, "pragma application_id") != ApplicationId)
+                return InvalidDatabase(request.DbPath);
+
+            if (request.RequireSupportedUserVersion)
+            {
+                command.CommandText = SqliteCommandPolicy.PragmaSql("user_version");
+                var userVersion = SqliteCommandPolicy.ReadInt32Scalar(command, "pragma user_version");
+                if ((userVersion & ~CurrentSchemaVersion) != 0)
+                {
+                    return Failure(
+                        ExistingCodeIndexDbValidationFailure.SchemaTooNew,
+                        $"database was written by a newer cdidx schema stamp (user_version {userVersion}); this binary supports up to {CurrentSchemaVersion}: {request.DbPath}",
+                        isSchemaTooNew: true);
+                }
+            }
+
+            command.CommandText = "SELECT name FROM sqlite_master WHERE type = 'table'";
+            using var reader = command.ExecuteReader();
+            var tables = new HashSet<string>(StringComparer.Ordinal);
+            while (reader.Read())
+                tables.Add(reader.GetString(0));
+
+            return RequiredCodeIndexTables.All(tables.Contains)
+                ? ValidationResult.Valid
+                : InvalidDatabase(request.DbPath);
+        }
+
+        private static ValidationResult ProjectException(string dbPath, string openTarget, Exception exception)
+        {
+            if (exception is SqliteException { SqliteErrorCode: 14 } cantOpen)
+            {
+                var category = ClassifyCantOpenFailure(openTarget, cantOpen.SqliteExtendedErrorCode);
+                return Failure(
+                    ExistingCodeIndexDbValidationFailure.Exception,
+                    FormatDatabaseOpenFailure(category, dbPath),
+                    isNotFound: category == DatabaseOpenMissingCategory,
+                    exception: exception);
+            }
+
+            return exception is CodeIndexException codeIndexException
+                ? Failure(ExistingCodeIndexDbValidationFailure.Exception, codeIndexException.Message, exception: exception)
+                : Failure(ExistingCodeIndexDbValidationFailure.Exception, InvalidDatabaseMessage(dbPath), exception: exception);
+        }
+
+        internal static string ClassifyCantOpenFailure(string dbPath, int sqliteExtendedErrorCode)
+        {
+            if (sqliteExtendedErrorCode == SqliteCantOpenDirtyWal)
+                return DatabaseOpenSidecarCategory;
+
+            return ProbeDatabasePath(dbPath) switch
+            {
+                DatabasePathProbe.Missing => DatabaseOpenMissingCategory,
+                DatabasePathProbe.PermissionDenied => DatabaseOpenPermissionCategory,
+                _ when HasInaccessibleSqliteSidecar(dbPath) => DatabaseOpenSidecarCategory,
+                _ => DatabaseOpenUnknownCategory,
+            };
+        }
+
+        private static bool HasInaccessibleSqliteSidecar(string dbPath)
+            => ProbeDatabasePath(dbPath + "-wal") == DatabasePathProbe.PermissionDenied
+               || ProbeDatabasePath(dbPath + "-shm") == DatabasePathProbe.PermissionDenied;
+
+        private static DatabasePathProbe ProbeDatabasePath(string path)
+        {
+            try
+            {
+                var normalizedPath = LongPath.EnsureWindowsPrefix(path);
+                if ((File.GetAttributes(normalizedPath) & FileAttributes.Directory) != 0)
+                    return DatabasePathProbe.Directory;
+
+                using var stream = new FileStream(
+                    normalizedPath,
+                    FileMode.Open,
+                    FileAccess.Read,
+                    FileShare.ReadWrite | FileShare.Delete,
+                    bufferSize: 1,
+                    FileOptions.RandomAccess);
+                return DatabasePathProbe.Readable;
+            }
+            catch (Exception ex) when (ex is FileNotFoundException or DirectoryNotFoundException)
+            {
+                return DatabasePathProbe.Missing;
+            }
+            catch (Exception ex) when (ex is UnauthorizedAccessException or System.Security.SecurityException)
+            {
+                return DatabasePathProbe.PermissionDenied;
+            }
+            catch (IOException)
+            {
+                return DatabasePathProbe.Unknown;
+            }
+        }
+
+        private static string FormatDatabaseOpenFailure(string category, string dbPath, string? detail = null)
+        {
+            var displayPath = dbPath;
+            if (SqliteFileUri.StartsWithFileScheme(dbPath))
+            {
+                var queryIndex = dbPath.IndexOf('?', StringComparison.Ordinal);
+                if (queryIndex >= 0)
+                    displayPath = dbPath[..queryIndex];
+            }
+
+            var pathLabel = DiagnosticSanitizer.ForPath(displayPath);
+            var sanitizedDetail = string.IsNullOrWhiteSpace(detail)
+                ? null
+                : DiagnosticSanitizer.ForMessage(detail);
+            var prefix = category == DatabaseOpenMissingCategory
+                ? $"database not found [{category}]"
+                : $"database open failed [{category}]";
+            return sanitizedDetail == null
+                ? $"{prefix}: {pathLabel}"
+                : $"{prefix}: {pathLabel}; {sanitizedDetail}";
+        }
+
+        private static ValidationResult InvalidDatabase(string dbPath)
+            => Failure(ExistingCodeIndexDbValidationFailure.InvalidDatabase, InvalidDatabaseMessage(dbPath));
+
+        private static string InvalidDatabaseMessage(string dbPath)
+            => $"database is not an existing CodeIndex DB: {dbPath}";
+
+        private static ValidationResult Failure(
+            ExistingCodeIndexDbValidationFailure failure,
+            string message,
+            bool isNotFound = false,
+            bool isSchemaTooNew = false,
+            Exception? exception = null)
+            => new(false, message, isNotFound, isSchemaTooNew, failure, exception);
+
+        private enum DatabasePathProbe
+        {
+            Readable,
+            Missing,
+            PermissionDenied,
+            Directory,
+            Unknown,
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbContext.cs b/src/CodeIndex/Database/DbContext.cs
index edc305157..65e879e34 100644
--- a/src/CodeIndex/Database/DbContext.cs
+++ b/src/CodeIndex/Database/DbContext.cs
@@ -1,24 +1,10 @@
 using CodeIndex.Cli;
-using CodeIndex.Diagnostics;
 using CodeIndex.Indexer;
 using CodeIndex.Models;
 using Microsoft.Data.Sqlite;
-using System.Globalization;
-using System.Runtime.ExceptionServices;
 
 namespace CodeIndex.Database;
 
-internal enum ExistingCodeIndexDbValidationFailure
-{
-    None,
-    Missing,
-    Inaccessible,
-    InvalidTarget,
-    InvalidDatabase,
-    SchemaTooNew,
-    Exception,
-}
-
 /// <summary>
 /// Manages SQLite connection and schema initialization.
 /// SQLite接続とスキーマ初期化を管理する。
@@ -33,12 +19,6 @@ public partial class DbContext : IDisposable
     public const string CacheSizeEnvironmentVariable = "CDIDX_SQLITE_CACHE_KB";
     public const string MmapSizeEnvironmentVariable = "CDIDX_SQLITE_MMAP_BYTES";
     public const string BusyTimeoutEnvironmentVariable = "CDIDX_SQLITE_BUSY_TIMEOUT_MS";
-    internal const string DatabaseOpenMissingCategory = "missing_database";
-    internal const string DatabaseOpenPermissionCategory = "permission_denied";
-    internal const string DatabaseOpenSidecarCategory = "sidecar_failure";
-    internal const string DatabaseOpenInvalidUriCategory = "invalid_uri";
-    internal const string DatabaseOpenUnknownCategory = "unknown_open_failure";
-    private const int SqliteCantOpenDirtyWal = 14 | (5 << 8);
     public const int DefaultWalAutocheckpointPages = 1000;
     public const string DefaultSynchronousMode = "NORMAL";
     public const string SymbolExtractorVersionMetaPrefix = "symbol_extractor_version_";
@@ -440,336 +420,6 @@ internal PreparedCommandCache PreparedCommands
             _connection,
             PreparedCommandCache.ReadCapacityFromEnvironment());
 
-    public static bool TryValidateExistingCodeIndexDb(
-        string dbPath,
-        out string message,
-        out bool isNotFound,
-        CancellationToken cancellationToken = default)
-        => TryValidateExistingCodeIndexDb(
-            dbPath,
-            requireWritable: true,
-            requireSupportedUserVersion: false,
-            out message,
-            out isNotFound,
-            out _,
-            cancellationToken);
-
-    internal static bool TryValidateExistingCodeIndexDb(
-        string dbPath,
-        bool requireWritable,
-        bool requireSupportedUserVersion,
-        out string message,
-        out bool isNotFound,
-        out bool isSchemaTooNew,
-        CancellationToken cancellationToken = default)
-        => TryValidateExistingCodeIndexDb(
-            dbPath,
-            requireWritable,
-            requireSupportedUserVersion,
-            out message,
-            out isNotFound,
-            out isSchemaTooNew,
-            out _,
-            out _,
-            cancellationToken);
-
-    internal static bool TryValidateExistingCodeIndexDb(
-        string dbPath,
-        bool requireWritable,
-        bool requireSupportedUserVersion,
-        out string message,
-        out bool isNotFound,
-        out bool isSchemaTooNew,
-        out ExistingCodeIndexDbValidationFailure validationFailure,
-        out Exception? validationException,
-        CancellationToken cancellationToken = default)
-        => TryValidateExistingCodeIndexDb(dbPath, openTarget =>
-        {
-            var mode = requireWritable ? SqliteConnectionPolicyMode.ReadWrite : SqliteConnectionPolicyMode.ReadOnly;
-            return new SqliteConnection(SqliteConnectionPolicy.BuildConnectionString(openTarget, mode));
-        },
-        static connection => connection.Open(),
-        null,
-        requireWritable,
-        requireSupportedUserVersion,
-        out message,
-        out isNotFound,
-        out isSchemaTooNew,
-        out validationFailure,
-        out validationException,
-        cancellationToken);
-
-    internal static bool TryValidateExistingCodeIndexDb(
-        string dbPath,
-        Func<string, SqliteConnection> createConnection,
-        Action<SqliteConnection> openConnection,
-        Action<int>? sleep,
-        out string message,
-        out bool isNotFound,
-        CancellationToken cancellationToken = default)
-        => TryValidateExistingCodeIndexDb(
-            dbPath,
-            createConnection,
-            openConnection,
-            sleep,
-            requireWritable: true,
-            requireSupportedUserVersion: false,
-            out message,
-            out isNotFound,
-            out _,
-            out _,
-            out _,
-            cancellationToken);
-
-    internal static bool TryValidateExistingCodeIndexDb(
-        string dbPath,
-        Func<string, SqliteConnection> createConnection,
-        Action<SqliteConnection> openConnection,
-        Action<int>? sleep,
-        out string message,
-        out bool isNotFound,
-        out Exception? validationException,
-        CancellationToken cancellationToken = default)
-        => TryValidateExistingCodeIndexDb(
-            dbPath,
-            createConnection,
-            openConnection,
-            sleep,
-            requireWritable: true,
-            requireSupportedUserVersion: false,
-            out message,
-            out isNotFound,
-            out _,
-            out _,
-            out validationException,
-            cancellationToken);
-
-    private static bool TryValidateExistingCodeIndexDb(
-        string dbPath,
-        Func<string, SqliteConnection> createConnection,
-        Action<SqliteConnection> openConnection,
-        Action<int>? sleep,
-        bool requireWritable,
-        bool requireSupportedUserVersion,
-        out string message,
-        out bool isNotFound,
-        out bool isSchemaTooNew,
-        out ExistingCodeIndexDbValidationFailure validationFailure,
-        out Exception? validationException,
-        CancellationToken cancellationToken = default)
-    {
-        message = string.Empty;
-        isNotFound = false;
-        isSchemaTooNew = false;
-        validationFailure = ExistingCodeIndexDbValidationFailure.None;
-        validationException = null;
-        cancellationToken.ThrowIfCancellationRequested();
-
-        if (SqliteFileUri.StartsWithFileScheme(dbPath) && !SqliteFileUri.TryValidateBounds(dbPath, out var boundsError))
-        {
-            validationFailure = ExistingCodeIndexDbValidationFailure.InvalidTarget;
-            message = FormatDatabaseOpenFailure(
-                DatabaseOpenInvalidUriCategory,
-                dbPath,
-                boundsError?.Message ?? "Invalid SQLite file URI.");
-            return false;
-        }
-
-        if (requireWritable && SqliteFileUri.StartsWithFileScheme(dbPath) && SqliteFileUri.RequestsReadOnly(dbPath))
-        {
-            validationFailure = ExistingCodeIndexDbValidationFailure.Inaccessible;
-            message = $"database must be writable: {dbPath}";
-            return false;
-        }
-
-        var openTarget = dbPath;
-        if (SqliteFileUri.StartsWithFileScheme(dbPath))
-        {
-            if (!TryGetLocalPath(dbPath, out var normalized, out var pathFailureReason)
-                || normalized == null)
-            {
-                validationFailure = ExistingCodeIndexDbValidationFailure.InvalidTarget;
-                message = FormatDatabaseOpenFailure(
-                    DatabaseOpenInvalidUriCategory,
-                    dbPath,
-                    pathFailureReason);
-                return false;
-            }
-
-            openTarget = normalized;
-        }
-
-        var preflight = ProbeDatabasePath(openTarget);
-        if (preflight is DatabasePathProbe.Missing or DatabasePathProbe.PermissionDenied or DatabasePathProbe.Directory)
-        {
-            var category = preflight switch
-            {
-                DatabasePathProbe.Missing => DatabaseOpenMissingCategory,
-                DatabasePathProbe.PermissionDenied => DatabaseOpenPermissionCategory,
-                _ => DatabaseOpenUnknownCategory,
-            };
-            message = FormatDatabaseOpenFailure(category, dbPath);
-            isNotFound = category == DatabaseOpenMissingCategory;
-            validationFailure = preflight switch
-            {
-                DatabasePathProbe.Missing => ExistingCodeIndexDbValidationFailure.Missing,
-                DatabasePathProbe.PermissionDenied => ExistingCodeIndexDbValidationFailure.Inaccessible,
-                _ => ExistingCodeIndexDbValidationFailure.InvalidTarget,
-            };
-            return false;
-        }
-
-        try
-        {
-            using var connection = requireWritable
-                ? OpenSqliteConnectionWithRetry(
-                    () => createConnection(openTarget),
-                    openConnection,
-                    sleep,
-                    dbPath: dbPath,
-                    cancellationToken: cancellationToken)
-                : OpenArtifactPreservingQueryOnly(dbPath);
-
-            using var cmd = connection.CreateCommand();
-            cmd.CommandText = SqliteCommandPolicy.PragmaSql("application_id");
-            if (SqliteCommandPolicy.ReadInt64Scalar(cmd, "pragma application_id") != ApplicationId)
-            {
-                validationFailure = ExistingCodeIndexDbValidationFailure.InvalidDatabase;
-                message = $"database is not an existing CodeIndex DB: {dbPath}";
-                return false;
-            }
-
-            if (requireSupportedUserVersion)
-            {
-                cmd.CommandText = SqliteCommandPolicy.PragmaSql("user_version");
-                var userVersion = SqliteCommandPolicy.ReadInt32Scalar(cmd, "pragma user_version");
-                var unknownBits = userVersion & ~CurrentSchemaVersion;
-                if (unknownBits != 0)
-                {
-                    isSchemaTooNew = true;
-                    validationFailure = ExistingCodeIndexDbValidationFailure.SchemaTooNew;
-                    message = $"database was written by a newer cdidx schema stamp (user_version {userVersion}); this binary supports up to {CurrentSchemaVersion}: {dbPath}";
-                    return false;
-                }
-            }
-
-            cmd.CommandText = "SELECT name FROM sqlite_master WHERE type = 'table'";
-            using var reader = cmd.ExecuteReader();
-            var tables = new HashSet<string>(StringComparer.Ordinal);
-            while (reader.Read())
-                tables.Add(reader.GetString(0));
-
-            if (RequiredCodeIndexTables.All(tables.Contains))
-                return true;
-
-            validationFailure = ExistingCodeIndexDbValidationFailure.InvalidDatabase;
-            message = $"database is not an existing CodeIndex DB: {dbPath}";
-            return false;
-        }
-        catch (SqliteException ex) when (ex.SqliteErrorCode is 14)
-        {
-            validationFailure = ExistingCodeIndexDbValidationFailure.Exception;
-            validationException = ex;
-            var category = ClassifyCantOpenFailure(openTarget, ex.SqliteExtendedErrorCode);
-            message = FormatDatabaseOpenFailure(category, dbPath);
-            isNotFound = category == DatabaseOpenMissingCategory;
-            return false;
-        }
-        catch (SqliteException ex)
-        {
-            validationFailure = ExistingCodeIndexDbValidationFailure.Exception;
-            validationException = ex;
-            message = $"database is not an existing CodeIndex DB: {dbPath}";
-            return false;
-        }
-        catch (CodeIndexException ex)
-        {
-            validationFailure = ExistingCodeIndexDbValidationFailure.Exception;
-            validationException = ex;
-            message = ex.Message;
-            return false;
-        }
-    }
-
-    internal static string ClassifyCantOpenFailure(string dbPath, int sqliteExtendedErrorCode)
-    {
-        if (sqliteExtendedErrorCode == SqliteCantOpenDirtyWal)
-            return DatabaseOpenSidecarCategory;
-
-        return ProbeDatabasePath(dbPath) switch
-        {
-            DatabasePathProbe.Missing => DatabaseOpenMissingCategory,
-            DatabasePathProbe.PermissionDenied => DatabaseOpenPermissionCategory,
-            _ when HasInaccessibleSqliteSidecar(dbPath) => DatabaseOpenSidecarCategory,
-            _ => DatabaseOpenUnknownCategory,
-        };
-    }
-
-    private static bool HasInaccessibleSqliteSidecar(string dbPath)
-        => ProbeDatabasePath(dbPath + "-wal") == DatabasePathProbe.PermissionDenied
-           || ProbeDatabasePath(dbPath + "-shm") == DatabasePathProbe.PermissionDenied;
-
-    private static DatabasePathProbe ProbeDatabasePath(string path)
-    {
-        try
-        {
-            var attributes = File.GetAttributes(LongPath.EnsureWindowsPrefix(path));
-            if ((attributes & FileAttributes.Directory) != 0)
-                return DatabasePathProbe.Directory;
-
-            using var stream = new FileStream(
-                LongPath.EnsureWindowsPrefix(path),
-                FileMode.Open,
-                FileAccess.Read,
-                FileShare.ReadWrite | FileShare.Delete,
-                bufferSize: 1,
-                FileOptions.RandomAccess);
-            return DatabasePathProbe.Readable;
-        }
-        catch (Exception ex) when (ex is FileNotFoundException or DirectoryNotFoundException)
-        {
-            return DatabasePathProbe.Missing;
-        }
-        catch (Exception ex) when (ex is UnauthorizedAccessException or System.Security.SecurityException)
-        {
-            return DatabasePathProbe.PermissionDenied;
-        }
-        catch (IOException)
-        {
-            return DatabasePathProbe.Unknown;
-        }
-    }
-
-    private static string FormatDatabaseOpenFailure(string category, string dbPath, string? detail = null)
-    {
-        var displayPath = dbPath;
-        if (SqliteFileUri.StartsWithFileScheme(dbPath))
-        {
-            var queryIndex = dbPath.IndexOf('?', StringComparison.Ordinal);
-            if (queryIndex >= 0)
-                displayPath = dbPath[..queryIndex];
-        }
-        var pathLabel = DiagnosticSanitizer.ForPath(displayPath);
-        var sanitizedDetail = string.IsNullOrWhiteSpace(detail)
-            ? null
-            : DiagnosticSanitizer.ForMessage(detail);
-        var prefix = category == DatabaseOpenMissingCategory
-            ? $"database not found [{category}]"
-            : $"database open failed [{category}]";
-        return sanitizedDetail == null
-            ? $"{prefix}: {pathLabel}"
-            : $"{prefix}: {pathLabel}; {sanitizedDetail}";
-    }
-
-    private enum DatabasePathProbe
-    {
-        Readable,
-        Missing,
-        PermissionDenied,
-        Directory,
-        Unknown,
-    }
-
     public DbContext(DbOpenIntent openIntent, string dbPath, CancellationToken cancellationToken = default)
         : this(
             openIntent,

From 593e8495330f0370daed3a7cbbb0e3ce2ef7e11c Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 17:10:23 +0900
Subject: [PATCH 23/45] Decompose MCP batch query execution

---
 .../Mcp/McpServer.SynchronousToolDispatch.cs  |  33 +
 src/CodeIndex/Mcp/McpServer.ToolDispatch.cs   |  34 +-
 ...pToolHandlers.BatchQuery.ResponseBudget.cs | 227 ++++++
 .../Mcp/McpToolHandlers.BatchQuery.Results.cs | 141 ++++
 .../Mcp/McpToolHandlers.BatchQuery.cs         | 662 ++++++------------
 .../McpServerBatchQueryDispatchParityTests.cs | 217 ++++++
 6 files changed, 820 insertions(+), 494 deletions(-)
 create mode 100644 src/CodeIndex/Mcp/McpServer.SynchronousToolDispatch.cs
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.ResponseBudget.cs
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.Results.cs
 create mode 100644 tests/CodeIndex.Tests/McpServerBatchQueryDispatchParityTests.cs

diff --git a/src/CodeIndex/Mcp/McpServer.SynchronousToolDispatch.cs b/src/CodeIndex/Mcp/McpServer.SynchronousToolDispatch.cs
new file mode 100644
index 000000000..cd186c998
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpServer.SynchronousToolDispatch.cs
@@ -0,0 +1,33 @@
+using System.Text.Json.Nodes;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private JsonNode? DispatchSynchronousToolCall(string toolName, JsonNode? id, JsonNode? args)
+        => toolName switch
+        {
+            "search" => ExecuteSearch(id, args),
+            "definition" => ExecuteDefinition(id, args),
+            "references" => ExecuteReferences(id, args),
+            "callers" => ExecuteCallers(id, args),
+            "callees" => ExecuteCallees(id, args),
+            "symbols" => ExecuteSymbols(id, args),
+            "files" => ExecuteFiles(id, args),
+            "find_in_file" => ExecuteFindInFile(id, args),
+            "excerpt" => ExecuteExcerpt(id, args),
+            "read_resource" => ExecuteReadResource(id, args),
+            "map" => ExecuteMap(id, args),
+            "analyze_symbol" => ExecuteAnalyzeSymbol(id, args),
+            "status" => ExecuteStatus(id, args),
+            "outline" => ExecuteOutline(id, args),
+            "deps" => ExecuteDeps(id, args),
+            "impact_analysis" => ExecuteImpactAnalysis(id, args),
+            "languages" => ExecuteLanguages(id, args),
+            "validate" => ExecuteValidate(id, args),
+            "unused_symbols" => ExecuteUnusedSymbols(id, args),
+            "symbol_hotspots" => ExecuteSymbolHotspots(id, args),
+            "ping" => ExecutePing(id),
+            _ => null,
+        };
+}
diff --git a/src/CodeIndex/Mcp/McpServer.ToolDispatch.cs b/src/CodeIndex/Mcp/McpServer.ToolDispatch.cs
index d824160ec..bde3aa096 100644
--- a/src/CodeIndex/Mcp/McpServer.ToolDispatch.cs
+++ b/src/CodeIndex/Mcp/McpServer.ToolDispatch.cs
@@ -244,33 +244,13 @@ private async Task<JsonNode> DispatchToolCallAsync(
             }
         }
 
-        return toolName switch
-        {
-            "search" => ExecuteSearch(id, args),
-            "definition" => ExecuteDefinition(id, args),
-            "references" => ExecuteReferences(id, args),
-            "callers" => ExecuteCallers(id, args),
-            "callees" => ExecuteCallees(id, args),
-            "symbols" => ExecuteSymbols(id, args),
-            "files" => ExecuteFiles(id, args),
-            "find_in_file" => ExecuteFindInFile(id, args),
-            "excerpt" => ExecuteExcerpt(id, args),
-            "read_resource" => ExecuteReadResource(id, args),
-            "map" => ExecuteMap(id, args),
-            "analyze_symbol" => ExecuteAnalyzeSymbol(id, args),
-            "status" => ExecuteStatus(id, args),
-            "outline" => ExecuteOutline(id, args),
-            "batch_query" => ExecuteBatchQuery(id, args),
-            "deps" => ExecuteDeps(id, args),
-            "impact_analysis" => ExecuteImpactAnalysis(id, args),
-            "languages" => ExecuteLanguages(id, args),
-            "validate" => ExecuteValidate(id, args),
-            "unused_symbols" => ExecuteUnusedSymbols(id, args),
-            "symbol_hotspots" => ExecuteSymbolHotspots(id, args),
-            "ping" => ExecutePing(id),
-            "suggest_improvement" => await ExecuteSuggestImprovementAsync(id, args).ConfigureAwait(false),
-            _ => createUnknownToolResponse(),
-        };
+        if (toolName == "batch_query")
+            return ExecuteBatchQuery(id, args);
+        if (toolName == "suggest_improvement")
+            return await ExecuteSuggestImprovementAsync(id, args).ConfigureAwait(false);
+
+        return DispatchSynchronousToolCall(toolName, id, args)
+            ?? createUnknownToolResponse();
     }
 
     private void EmitToolInvocationTelemetry(string toolName, JsonNode? args, JsonNode response, DateTimeOffset startedAt, double elapsedMs, string? errorType)
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.ResponseBudget.cs b/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.ResponseBudget.cs
new file mode 100644
index 000000000..5b3da6138
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.ResponseBudget.cs
@@ -0,0 +1,227 @@
+using System.Text.Json.Nodes;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private sealed class BatchResponseBudget
+    {
+        private readonly McpServer _server;
+        private readonly JsonNode? _id;
+        private readonly int _submittedCount;
+        private readonly int _responseByteLimit;
+        private readonly ArgumentAdjustmentCollector _adjustments;
+        private readonly JsonArray _results = [];
+        private readonly JsonArray _truncatedQueries = [];
+        private int _estimatedResponseBytes;
+        private int? _cascadeStartedAtIndex;
+
+        internal BatchResponseBudget(
+            McpServer server,
+            JsonNode? id,
+            int submittedCount,
+            int responseByteLimit,
+            ArgumentAdjustmentCollector adjustments)
+        {
+            _server = server;
+            _id = id;
+            _submittedCount = submittedCount;
+            _responseByteLimit = responseByteLimit;
+            _adjustments = adjustments;
+            _estimatedResponseBytes = server.EstimateBatchResponseBytes(
+                id,
+                "Executed 0 queries.",
+                submittedCount,
+                successCount: 0,
+                failureCount: 0,
+                GetBatchFailureScope(submittedCount, 0, 0, cascadeStartedAtIndex: null),
+                cascadeStartedAtIndex: null,
+                responseByteLimit,
+                _results,
+                truncated: false,
+                _truncatedQueries,
+                adjustments);
+        }
+
+        internal bool IsTruncated { get; private set; }
+
+        internal bool TryAppend(
+            JsonObject entry,
+            BatchQuerySlot slot,
+            int candidateSuccessCount,
+            int candidateFailureCount)
+        {
+            var candidateBytes = _server.EstimateBatchAppendBytes(
+                _estimatedResponseBytes,
+                entry,
+                candidateSuccessCount + candidateFailureCount,
+                candidateSuccessCount,
+                candidateFailureCount);
+            if (candidateBytes > _responseByteLimit)
+            {
+                IsTruncated = true;
+                _cascadeStartedAtIndex ??= slot.RequestIndex;
+                _truncatedQueries.Add(BuildTruncatedEntry(slot, "response_byte_limit_exceeded"));
+                return false;
+            }
+
+            _estimatedResponseBytes = candidateBytes;
+            _results.Add(entry);
+            return true;
+        }
+
+        internal void AppendCascadedSlot(BatchQuerySlot slot)
+        {
+            slot.Stopwatch.Stop();
+            _cascadeStartedAtIndex ??= slot.RequestIndex;
+            _truncatedQueries.Add(BuildTruncatedEntry(slot, "response_byte_limit_already_exceeded"));
+        }
+
+        internal JsonNode BuildResponse(int successCount, int failureCount, long totalElapsedMs)
+        {
+            var compactSummary = false;
+            var omitSplitHint = false;
+            JsonObject payload;
+            string summary;
+            while (true)
+            {
+                payload = BuildPayload(successCount, failureCount, totalElapsedMs, omitSplitHint);
+                summary = BuildSummary(successCount, failureCount, totalElapsedMs, compactSummary);
+                _estimatedResponseBytes = _server.EstimateJsonUtf8Bytes(
+                    _server.CreateToolResult(_id, summary, payload.DeepClone()),
+                    _responseByteLimit);
+                if (_estimatedResponseBytes <= _responseByteLimit)
+                    break;
+                if (RemoveLastResultForFinalBudget())
+                    continue;
+                if (RemoveBatchTruncatedQueryToolDisplay(_truncatedQueries))
+                    continue;
+                if (_truncatedQueries.Count > 1)
+                {
+                    _truncatedQueries.RemoveAt(_truncatedQueries.Count - 1);
+                    continue;
+                }
+                if (CompactBatchTruncatedQueryArgsSummaries(_truncatedQueries))
+                    continue;
+                if (IsTruncated && !compactSummary)
+                {
+                    compactSummary = true;
+                    continue;
+                }
+                if (IsTruncated && !omitSplitHint)
+                {
+                    omitSplitHint = true;
+                    continue;
+                }
+                break;
+            }
+
+            ((JsonObject)payload["metadata"]!)["estimated_response_bytes"] = _estimatedResponseBytes;
+            return _server.CreateToolResult(_id, summary, payload);
+        }
+
+        private JsonObject BuildPayload(
+            int successCount,
+            int failureCount,
+            long totalElapsedMs,
+            bool omitSplitHint)
+        {
+            var payload = new JsonObject
+            {
+                ["count"] = _results.Count,
+                ["total_count"] = _submittedCount,
+                ["success_count"] = successCount,
+                ["failure_count"] = failureCount,
+                ["partial_failure"] = failureCount > 0 || _cascadeStartedAtIndex.HasValue,
+                ["failure_scope"] = GetBatchFailureScope(
+                    _submittedCount,
+                    successCount,
+                    failureCount,
+                    _cascadeStartedAtIndex),
+                ["cascade_started_at_index"] = _cascadeStartedAtIndex,
+                ["metadata"] = new JsonObject
+                {
+                    ["submitted"] = _submittedCount,
+                    ["executed"] = successCount + failureCount,
+                    ["errors"] = failureCount,
+                    ["total_elapsed_ms"] = totalElapsedMs,
+                    ["success_count"] = successCount,
+                    ["failure_count"] = failureCount,
+                    ["response_byte_limit"] = _responseByteLimit,
+                    ["estimated_response_bytes"] = _responseByteLimit,
+                },
+                ["results"] = _results.DeepClone(),
+            };
+            _adjustments.ApplyTo(payload);
+            if (IsTruncated)
+            {
+                payload["truncated"] = true;
+                payload["truncated_queries"] = _truncatedQueries.DeepClone();
+                if (!omitSplitHint)
+                {
+                    payload["split_hint"] = BuildBatchSplitHint(
+                        _submittedCount,
+                        _cascadeStartedAtIndex,
+                        _results.Count);
+                }
+            }
+            return payload;
+        }
+
+        private string BuildSummary(
+            int successCount,
+            int failureCount,
+            long totalElapsedMs,
+            bool compactSummary)
+        {
+            if (compactSummary)
+                return $"Response truncated at {_responseByteLimit} bytes.";
+
+            var baseSummary = failureCount == 0
+                ? $"Executed {successCount + failureCount} of {_submittedCount} queries in {totalElapsedMs} ms (all succeeded)."
+                : $"Executed {successCount + failureCount} of {_submittedCount} queries in {totalElapsedMs} ms ({successCount} succeeded, {failureCount} failed).";
+            return IsTruncated
+                ? baseSummary + $" Response truncated at {_responseByteLimit} bytes; split the batch or lower per-slot limits."
+                : baseSummary;
+        }
+
+        private bool RemoveLastResultForFinalBudget()
+        {
+            if (_results.Count == 0)
+                return false;
+
+            var removed = _results[_results.Count - 1];
+            IsTruncated = true;
+            if (removed?["request_index"] is JsonValue requestIndexValue
+                && requestIndexValue.TryGetValue<int>(out var removedRequestIndex))
+            {
+                _cascadeStartedAtIndex = _cascadeStartedAtIndex.HasValue
+                    ? Math.Min(_cascadeStartedAtIndex.Value, removedRequestIndex)
+                    : removedRequestIndex;
+            }
+            _truncatedQueries.Insert(0, new JsonObject
+            {
+                ["request_index"] = removed?["request_index"]?.DeepClone(),
+                ["slot_id"] = removed?["slot_id"]?.DeepClone(),
+                ["tool"] = removed?["tool"]?.DeepClone(),
+                ["args_summary"] = removed?["args_summary"]?.DeepClone(),
+                ["reason"] = "final_response_byte_limit_exceeded",
+            });
+            _results.RemoveAt(_results.Count - 1);
+            return true;
+        }
+
+        private static JsonObject BuildTruncatedEntry(BatchQuerySlot slot, string reason)
+        {
+            var entry = new JsonObject
+            {
+                ["request_index"] = slot.RequestIndex,
+                ["args_summary"] = BuildArgsSummary(slot.ToolArgs),
+                ["reason"] = reason,
+            };
+            AddBatchSlotId(entry, slot.SlotId);
+            AddToolDisplayData(entry, slot.ToolName);
+            return entry;
+        }
+    }
+}
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.Results.cs b/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.Results.cs
new file mode 100644
index 000000000..eb29863ea
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.Results.cs
@@ -0,0 +1,141 @@
+using System.Text.Json.Nodes;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private sealed class BatchQueryResultCollector
+    {
+        private readonly BatchResponseBudget _responseBudget;
+
+        internal BatchQueryResultCollector(
+            McpServer server,
+            JsonNode? id,
+            JsonArray queries,
+            int responseByteLimit,
+            ArgumentAdjustmentCollector adjustments)
+        {
+            _responseBudget = new BatchResponseBudget(
+                server,
+                id,
+                queries.Count,
+                responseByteLimit,
+                adjustments);
+        }
+
+        internal int SuccessCount { get; private set; }
+        internal int FailureCount { get; private set; }
+        internal bool IsTruncated => _responseBudget.IsTruncated;
+
+        internal void AppendCascadedSlot(BatchQuerySlot slot)
+            => _responseBudget.AppendCascadedSlot(slot);
+
+        internal void AppendError(
+            BatchQuerySlot slot,
+            string errorMessage,
+            int? code = null,
+            string? category = null,
+            string? suggestion = null,
+            bool? retrySafe = null,
+            JsonObject? extraData = null)
+        {
+            slot.Stopwatch.Stop();
+            var entry = new JsonObject
+            {
+                ["request_index"] = slot.RequestIndex,
+                ["ok"] = false,
+                ["correlation_id"] = CurrentCorrelationContext.Value?.CorrelationId,
+                ["args_summary"] = BuildArgsSummary(slot.ToolArgs),
+                ["elapsed_ms"] = slot.Stopwatch.ElapsedMilliseconds,
+                ["error"] = errorMessage,
+            };
+            AddBatchSlotId(entry, slot.SlotId);
+            AddToolDisplayData(entry, slot.ToolName);
+            CopySlotErrorData(entry, extraData);
+            if (code.HasValue)
+                entry["code"] = code.Value;
+            if (category is not null)
+                entry["category"] = category;
+            if (suggestion is not null)
+                entry["suggestion"] = suggestion;
+            if (retrySafe.HasValue)
+                entry["retry_safe"] = retrySafe.Value;
+
+            _responseBudget.TryAppend(
+                entry,
+                slot,
+                SuccessCount,
+                FailureCount + 1);
+            FailureCount++;
+        }
+
+        internal void AppendRateLimited(BatchQuerySlot slot, long retryAfterMs)
+        {
+            slot.Stopwatch.Stop();
+            var toolDisplay = slot.ToolName is null
+                ? "(missing)"
+                : BoundToolNameForDisplay(slot.ToolName).Text;
+            var entry = new JsonObject
+            {
+                ["request_index"] = slot.RequestIndex,
+                ["ok"] = false,
+                ["correlation_id"] = CurrentCorrelationContext.Value?.CorrelationId,
+                ["args_summary"] = BuildArgsSummary(slot.ToolArgs),
+                ["elapsed_ms"] = slot.Stopwatch.ElapsedMilliseconds,
+                ["error"] = $"Rate limit exceeded for tool '{toolDisplay}' (retry after {retryAfterMs} ms).",
+                ["error_category"] = "rate_limited",
+                ["retry_after_ms"] = retryAfterMs,
+                ["category"] = McpErrorEnvelope.CategoryRateLimited,
+                ["suggestion"] = $"Back off for at least {retryAfterMs} ms before retrying this tool.",
+                ["retry_safe"] = true,
+            };
+            AddBatchSlotId(entry, slot.SlotId);
+            AddToolDisplayData(entry, slot.ToolName);
+            _responseBudget.TryAppend(
+                entry,
+                slot,
+                SuccessCount,
+                FailureCount + 1);
+            FailureCount++;
+        }
+
+        internal void AppendSuccess(BatchQuerySlot slot, JsonNode response)
+        {
+            slot.Stopwatch.Stop();
+            var entry = new JsonObject
+            {
+                ["request_index"] = slot.RequestIndex,
+                ["ok"] = true,
+                ["correlation_id"] = CurrentCorrelationContext.Value?.CorrelationId,
+                ["args_summary"] = BuildArgsSummary(slot.ToolArgs),
+                ["elapsed_ms"] = slot.Stopwatch.ElapsedMilliseconds,
+                ["summary"] = response["result"]?["content"]?[0]?["text"]?.GetValue<string>(),
+                ["result"] = response["result"]?["structuredContent"]?.DeepClone(),
+            };
+            AddBatchSlotId(entry, slot.SlotId);
+            AddToolDisplayData(entry, slot.ToolName);
+            _responseBudget.TryAppend(
+                entry,
+                slot,
+                SuccessCount + 1,
+                FailureCount);
+            SuccessCount++;
+        }
+
+        internal JsonNode BuildResponse(long totalElapsedMs)
+            => _responseBudget.BuildResponse(SuccessCount, FailureCount, totalElapsedMs);
+
+        private static void CopySlotErrorData(JsonObject entry, JsonObject? extraData)
+        {
+            if (extraData is null)
+                return;
+
+            foreach (var (key, value) in extraData)
+            {
+                if (key is "message" or "jsonrpc_invalid_params" || entry.ContainsKey(key))
+                    continue;
+                entry[key] = value?.DeepClone();
+            }
+        }
+    }
+}
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.cs b/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.cs
index 2505e71d8..1ec9dea80 100644
--- a/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.cs
+++ b/src/CodeIndex/Mcp/McpToolHandlers.BatchQuery.cs
@@ -7,516 +7,244 @@ public partial class McpServer
 {
     private JsonNode ExecuteBatchQuery(JsonNode? id, JsonNode? args)
     {
-        var queriesNode = args?["queries"];
-        if (queriesNode is null)
-            return CreateToolErrorResponse(id, "Missing or empty required parameter: queries");
-        if (queriesNode is not JsonArray queries)
-            return CreateToolErrorResponse(id, "Invalid type for argument 'queries' on tool 'batch_query'. Expected array.");
-        if (queries.Count == 0)
-            return CreateToolErrorResponse(id, "Missing or empty required parameter: queries");
-
-        if (queries.Count > MaxBatchQuerySize)
-            return CreateToolErrorResponse(id, $"Batch too large: {queries.Count} queries (max {MaxBatchQuerySize})");
+        if (!TryReadBatchQueries(id, args, out var queries, out var validationError))
+            return validationError!;
 
-        var resultsArray = new JsonArray();
-        var truncatedQueries = new JsonArray();
         var totalStopwatch = Stopwatch.StartNew();
         var adjustments = new ArgumentAdjustmentCollector();
-        int successCount = 0;
-        int failureCount = 0;
-        int? cascadeStartedAtIndex = null;
-        var truncated = false;
         var responseByteLimit = ReadBatchQueryResponseByteLimit(args, adjustments);
-        var estimateOnly = args?["estimateOnly"]?.GetValue<bool>() ?? false;
-        if (estimateOnly)
-            return ExecuteBatchQueryEstimate(id, queries, responseByteLimit, adjustments);
-        var estimatedResponseBytes = EstimateBatchResponseBytes(id, "Executed 0 queries.", queries.Count, successCount, failureCount,
-            GetBatchFailureScope(queries.Count, successCount, failureCount, cascadeStartedAtIndex), cascadeStartedAtIndex,
-            responseByteLimit, resultsArray, truncated: false, truncatedQueries, adjustments);
+        if (args?["estimateOnly"]?.GetValue<bool>() ?? false)
+            return ExecuteBatchQueryEstimate(id, queries!, responseByteLimit, adjustments);
+
+        var collector = new BatchQueryResultCollector(
+            this,
+            id,
+            queries!,
+            responseByteLimit,
+            adjustments);
+        ExecuteBatchSlots(queries!, collector);
+        totalStopwatch.Stop();
+        return collector.BuildResponse(totalStopwatch.ElapsedMilliseconds);
+    }
 
-        bool TryAppendResult(JsonObject entry, string? toolName, JsonNode? toolArgs, int requestIndex, string? slotId, bool successfulSlot = false, bool failedSlot = false)
+    private bool TryReadBatchQueries(
+        JsonNode? id,
+        JsonNode? args,
+        out JsonArray? queries,
+        out JsonNode? validationError)
+    {
+        var queriesNode = args?["queries"];
+        queries = queriesNode as JsonArray;
+        validationError = null;
+        if (queriesNode is null)
+            validationError = CreateToolErrorResponse(id, "Missing or empty required parameter: queries");
+        else if (queries is null)
+            validationError = CreateToolErrorResponse(id, "Invalid type for argument 'queries' on tool 'batch_query'. Expected array.");
+        else if (queries.Count == 0)
+            validationError = CreateToolErrorResponse(id, "Missing or empty required parameter: queries");
+        else if (queries.Count > MaxBatchQuerySize)
+            validationError = CreateToolErrorResponse(id, $"Batch too large: {queries.Count} queries (max {MaxBatchQuerySize})");
+        return validationError is null;
+    }
+
+    private void ExecuteBatchSlots(JsonArray queries, BatchQueryResultCollector collector)
+    {
+        var caller = CurrentInitializeState.Caller;
+        for (var requestIndex = 0; requestIndex < queries.Count; requestIndex++)
         {
-            var candidateSuccessCount = successCount + (successfulSlot ? 1 : 0);
-            var candidateFailureCount = failureCount + (failedSlot ? 1 : 0);
-            var candidateExecutedCount = candidateSuccessCount + candidateFailureCount;
-            var candidateBytes = EstimateBatchAppendBytes(
-                estimatedResponseBytes,
-                entry,
-                candidateExecutedCount,
-                candidateSuccessCount,
-                candidateFailureCount);
-            if (candidateBytes > responseByteLimit)
+            using var slotCorrelation = BeginChildCorrelation(requestIndex + 1);
+            var slot = CreateBatchQuerySlot(queries[requestIndex], requestIndex);
+            if (collector.IsTruncated)
             {
-                truncated = true;
-                cascadeStartedAtIndex ??= requestIndex;
-                var truncatedEntry = new JsonObject
-                {
-                    ["request_index"] = requestIndex,
-                    ["args_summary"] = BuildArgsSummary(toolArgs),
-                    ["reason"] = "response_byte_limit_exceeded",
-                };
-                AddBatchSlotId(truncatedEntry, slotId);
-                AddToolDisplayData(truncatedEntry, toolName);
-                truncatedQueries.Add(truncatedEntry);
-                return false;
+                collector.AppendCascadedSlot(slot);
+                continue;
             }
 
-            estimatedResponseBytes = candidateBytes;
-            resultsArray.Add(entry);
-            return true;
+            ExecuteBatchSlot(slot, collector, caller);
         }
+    }
 
-        static void CopySlotErrorData(JsonObject entry, JsonObject? extraData)
-        {
-            if (extraData is null)
-                return;
+    private static BatchQuerySlot CreateBatchQuerySlot(JsonNode? query, int requestIndex)
+    {
+        var queryObject = query as JsonObject;
+        var toolName = queryObject?["tool"] is JsonValue toolValue
+            && toolValue.TryGetValue<string>(out var parsedToolName)
+                ? parsedToolName
+                : null;
+        return new BatchQuerySlot(
+            requestIndex,
+            queryObject,
+            toolName,
+            queryObject?["arguments"],
+            ReadBatchSlotId(queryObject),
+            Stopwatch.StartNew());
+    }
 
-            foreach (var (key, value) in extraData)
-            {
-                if (key is "message" or "jsonrpc_invalid_params")
-                    continue;
-                if (entry.ContainsKey(key))
-                    continue;
-                entry[key] = value?.DeepClone();
-            }
+    private void ExecuteBatchSlot(BatchQuerySlot slot, BatchQueryResultCollector collector, string caller)
+    {
+        var toolName = slot.ToolName;
+        if (string.IsNullOrEmpty(toolName))
+        {
+            var message = slot.QueryObject is null
+                ? "Each query must be an object with a string tool name."
+                : "Missing tool name";
+            collector.AppendError(slot, message,
+                category: McpErrorEnvelope.CategoryMissingParameter,
+                suggestion: "Each batch_query slot must include a string `tool` field.",
+                retrySafe: false);
+            return;
         }
 
-        void AppendSlotError(int requestIndex, string? slotId, string? toolName, JsonNode? toolArgs, Stopwatch slotStopwatch, string errorMessage,
-            int? code = null, string? category = null, string? suggestion = null, bool? retrySafe = null, JsonObject? extraData = null)
+        if (toolName.Length > McpBoundedText.MaxToolNameChars)
         {
-            slotStopwatch.Stop();
-            var entry = new JsonObject
-            {
-                ["request_index"] = requestIndex,
-                ["ok"] = false,
-                ["correlation_id"] = CurrentCorrelationContext.Value?.CorrelationId,
-                ["args_summary"] = BuildArgsSummary(toolArgs),
-                ["elapsed_ms"] = slotStopwatch.ElapsedMilliseconds,
-                ["error"] = errorMessage,
-            };
-            AddBatchSlotId(entry, slotId);
-            AddToolDisplayData(entry, toolName);
-            CopySlotErrorData(entry, extraData);
-            if (code.HasValue)
-                entry["code"] = code.Value;
-            // #1581: batch_query slot errors also carry the canonical envelope so clients
-            // get the same `category` / `suggestion` / `retry_safe` decision shape on every
-            // failure path. Defaults stay null when the call site cannot classify safely.
-            // #1581: スロットエラーにも canonical envelope を付与し、失敗経路を問わずクライアント
-            // が同じ判定形状を扱えるようにする。分類できない呼び出し元は null のまま渡す。
-            if (category != null)
-                entry["category"] = category;
-            if (suggestion != null)
-                entry["suggestion"] = suggestion;
-            if (retrySafe.HasValue)
-                entry["retry_safe"] = retrySafe.Value;
-            TryAppendResult(entry, toolName, toolArgs, requestIndex, slotId, failedSlot: true);
-            failureCount++;
+            collector.AppendError(slot, BuildUnknownToolMessage(toolName),
+                category: McpErrorEnvelope.CategoryToolUnknown,
+                suggestion: "Call tools/list to see the tool catalog. Slot tool names are case-sensitive.",
+                retrySafe: false);
+            return;
         }
 
-        // Rate-limited slot error variant. Mirrors the shape of `AppendSlotError` so existing
-        // clients keep working, but also surfaces `error_category` + `retry_after_ms` next to
-        // `error` so well-behaved clients can detect throttling and back off per-slot instead
-        // of inferring it from the human-readable message. The outer call also consumes a
-        // batch_query token, so spamming `batch_query` with N inner calls is bounded by both
-        // the batch_query bucket and per-tool buckets (#1560).
-        // レート制限スロット用の AppendSlotError 変種。既存クライアント互換のため `error` を
-        // そのまま維持しつつ、`error_category` と `retry_after_ms` を併記して、スロット単位での
-        // 検出・バックオフを可能にする。外側の batch_query 自体もトークンを消費するため、
-        // N 個の内側呼び出しを含むスパムは batch_query バケットとツール別バケットの両方で
-        // 上限が掛かる（#1560）。
-        void AppendRateLimitedSlot(int requestIndex, string? slotId, string? toolName, JsonNode? toolArgs, Stopwatch slotStopwatch, long retryAfterMs)
+        if (ValidateToolArguments(toolName, slot.ToolArgs) is JsonObject argumentError)
         {
-            slotStopwatch.Stop();
-            var toolDisplay = toolName is null ? "(missing)" : BoundToolNameForDisplay(toolName).Text;
-            // #1581: emit the canonical envelope (`category`, `suggestion`, `retry_safe`)
-            // next to the legacy #1560 fields so clients have a single decision shape across
-            // top-level and slot-level rate-limit errors.
-            // #1581: 既存の #1560 フィールド（`error_category`, `retry_after_ms`）と並べて
-            // canonical envelope（`category`, `suggestion`, `retry_safe`）も書き、トップレベル
-            // とスロット単位のレート制限エラーで判定形状を揃える。
-            var entry = new JsonObject
-            {
-                ["request_index"] = requestIndex,
-                ["ok"] = false,
-                ["correlation_id"] = CurrentCorrelationContext.Value?.CorrelationId,
-                ["args_summary"] = BuildArgsSummary(toolArgs),
-                ["elapsed_ms"] = slotStopwatch.ElapsedMilliseconds,
-                ["error"] = $"Rate limit exceeded for tool '{toolDisplay}' (retry after {retryAfterMs} ms).",
-                ["error_category"] = "rate_limited",
-                ["retry_after_ms"] = retryAfterMs,
-                ["category"] = McpErrorEnvelope.CategoryRateLimited,
-                ["suggestion"] = $"Back off for at least {retryAfterMs} ms before retrying this tool.",
-                ["retry_safe"] = true,
-            };
-            AddBatchSlotId(entry, slotId);
-            AddToolDisplayData(entry, toolName);
-            TryAppendResult(entry, toolName, toolArgs, requestIndex, slotId, failedSlot: true);
-            failureCount++;
+            collector.AppendError(slot, argumentError["message"]!.GetValue<string>(),
+                category: McpErrorEnvelope.CategoryInvalidArgument,
+                suggestion: "Use exactly the argument names advertised by tools/list for this tool.",
+                retrySafe: false,
+                extraData: argumentError);
+            return;
         }
 
-        var caller = CurrentInitializeState.Caller;
-        for (var requestIndex = 0; requestIndex < queries.Count; requestIndex++)
+        if (ValidateCommonListArguments(slot.ToolArgs) is JsonObject listArgumentError)
         {
-            using var slotCorrelation = BeginChildCorrelation(requestIndex + 1);
-            var q = queries[requestIndex];
-            var queryObject = q as JsonObject;
-            var toolName = queryObject?["tool"] is JsonValue toolValue && toolValue.TryGetValue<string>(out var parsedToolName)
-                ? parsedToolName
-                : null;
-            var toolArgs = queryObject?["arguments"];
-            var slotId = ReadBatchSlotId(queryObject);
-            var slotStopwatch = Stopwatch.StartNew();
+            collector.AppendError(slot, listArgumentError["message"]!.GetValue<string>(),
+                category: McpErrorEnvelope.CategoryInvalidArgument,
+                suggestion: "Send only non-empty string entries within the documented MCP array bounds.",
+                retrySafe: false,
+                extraData: listArgumentError);
+            return;
+        }
 
-            if (truncated)
-            {
-                slotStopwatch.Stop();
-                cascadeStartedAtIndex ??= requestIndex;
-                var truncatedEntry = new JsonObject
-                {
-                    ["request_index"] = requestIndex,
-                    ["args_summary"] = BuildArgsSummary(toolArgs),
-                    ["reason"] = "response_byte_limit_already_exceeded",
-                };
-                AddBatchSlotId(truncatedEntry, slotId);
-                AddToolDisplayData(truncatedEntry, toolName);
-                truncatedQueries.Add(truncatedEntry);
-                continue;
-            }
+        // Keep enablement ahead of write rejection so disabled write tools retain -32601.
+        if (McpToolFilter.IsKnownTool(toolName) && !_toolFilter.IsEnabled(toolName))
+        {
+            collector.AppendError(slot, $"Tool not enabled: {toolName}", code: -32601,
+                category: McpErrorEnvelope.CategoryToolDisabled,
+                suggestion: "This tool is disabled on the server. Ask the operator to enable it or remove the slot.",
+                retrySafe: false);
+            return;
+        }
 
-            if (string.IsNullOrEmpty(toolName))
-            {
-                var message = queryObject is null ? "Each query must be an object with a string tool name." : "Missing tool name";
-                AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, message,
-                    category: McpErrorEnvelope.CategoryMissingParameter,
-                    suggestion: "Each batch_query slot must include a string `tool` field.",
-                    retrySafe: false);
-                continue;
-            }
-            if (toolName.Length > McpBoundedText.MaxToolNameChars)
-            {
-                AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, BuildUnknownToolMessage(toolName),
-                    category: McpErrorEnvelope.CategoryToolUnknown,
-                    suggestion: "Call tools/list to see the tool catalog. Slot tool names are case-sensitive.",
-                    retrySafe: false);
-                continue;
-            }
+        if (toolName is "index" or "backfill_fold" or "suggest_improvement")
+        {
+            collector.AppendError(slot, $"{toolName} is not allowed in batch_query (write operation)",
+                category: McpErrorEnvelope.CategoryInvalidArgument,
+                suggestion: "Call write tools (index / backfill_fold / suggest_improvement) directly via tools/call, not inside batch_query.",
+                retrySafe: false);
+            return;
+        }
 
-            if (ValidateToolArguments(toolName, toolArgs) is JsonObject argumentError)
-            {
-                AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, argumentError["message"]!.GetValue<string>(),
-                    category: McpErrorEnvelope.CategoryInvalidArgument,
-                    suggestion: "Use exactly the argument names advertised by tools/list for this tool.",
-                    retrySafe: false,
-                    extraData: argumentError);
-                continue;
-            }
+        // Reject recursion before consuming the inner tool bucket.
+        if (toolName == "batch_query")
+        {
+            collector.AppendError(slot, "batch_query cannot be nested inside batch_query.",
+                category: McpErrorEnvelope.CategoryInvalidArgument,
+                suggestion: "Flatten the nested batch_query into top-level slots.",
+                retrySafe: false);
+            return;
+        }
 
-            if (ValidateCommonListArguments(toolArgs) is JsonObject listArgumentError)
-            {
-                AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, listArgumentError["message"]!.GetValue<string>(),
-                    category: McpErrorEnvelope.CategoryInvalidArgument,
-                    suggestion: "Send only non-empty string entries within the documented MCP array bounds.",
-                    retrySafe: false,
-                    extraData: listArgumentError);
-                continue;
-            }
+        var slotBucketName = ResolveKnownRateLimitBucketName(toolName) ?? RateLimiter.InvalidToolBucketName;
+        var slotDecision = RateLimiter.TryAcquire(slotBucketName, caller);
+        if (!slotDecision.Allowed)
+        {
+            collector.AppendRateLimited(slot, slotDecision.RetryAfterMs);
+            return;
+        }
 
-            // Honor the per-deployment enablement gate inside batch_query too (#1561). Without
-            // this, an operator who disabled a tool through `CDIDX_MCP_TOOLS_ALLOW` /
-            // `CDIDX_MCP_TOOLS_DENY` could still reach it by smuggling the name into a batch
-            // slot. Only intercept known-but-disabled tools so unknown names still surface as
-            // the existing "Unknown tool" slot error below. The gate runs BEFORE the
-            // write-operation guard so a disabled write tool (e.g. `index` excluded via deny)
-            // surfaces as the structured `code: -32601` "Tool not enabled" — the operator's
-            // intent is "this tool is not on offer", which is more informative for AI clients
-            // than the generic write-in-batch message.
-            // batch_query 内でもデプロイ単位の有効化ゲートを尊重する (#1561)。これが無いと、
-            // `CDIDX_MCP_TOOLS_ALLOW` / `CDIDX_MCP_TOOLS_DENY` で無効化したツールに batch 経由で
-            // 到達できてしまう。既知だが無効なツールだけを捕まえ、未知名は既存の "Unknown tool"
-            // slot エラーに任せる。書き込みツールであっても gate で無効化されていれば、より
-            // 情報量のある `code: -32601` "Tool not enabled" を返したいので、書き込みガードより
-            // 前にこのゲートを置く。
-            if (McpToolFilter.IsKnownTool(toolName) && !_toolFilter.IsEnabled(toolName))
-            {
-                AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, $"Tool not enabled: {toolName}", code: -32601,
-                    category: McpErrorEnvelope.CategoryToolDisabled,
-                    suggestion: "This tool is disabled on the server. Ask the operator to enable it or remove the slot.",
-                    retrySafe: false);
-                continue;
-            }
+        if (ValidateProjectFilterArguments(slot.ToolArgs) is JsonObject projectFilterError)
+        {
+            collector.AppendError(slot, projectFilterError["message"]!.GetValue<string>(),
+                category: McpErrorEnvelope.CategoryInvalidArgument,
+                suggestion: "Use a project name or project path from the current workspace, or correct the solution filter.",
+                retrySafe: false,
+                extraData: projectFilterError);
+            return;
+        }
 
-            // Block write operations in batch / バッチ内では書き込み操作をブロック
-            if (toolName == "index" || toolName == "backfill_fold" || toolName == "suggest_improvement")
-            {
-                AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, $"{toolName} is not allowed in batch_query (write operation)",
-                    category: McpErrorEnvelope.CategoryInvalidArgument,
-                    suggestion: "Call write tools (index / backfill_fold / suggest_improvement) directly via tools/call, not inside batch_query.",
-                    retrySafe: false);
-                continue;
-            }
+        ExecuteAcceptedBatchSlot(slot, collector, toolName);
+    }
 
-            // Reject nested batch_query before the rate-limit consumption so the per-(tool,
-            // caller) bucket cannot be drained by recursive expansion (and so the failure
-            // message is clear instead of the generic "Unknown tool: batch_query") (#1560).
-            // 再帰展開でバケットを消費させないため、レート制限消費の前に内側 batch_query を
-            // 明示的に拒否する。エラーメッセージも "Unknown tool: batch_query" の汎用ではなく
-            // ネスト禁止の明示文に揃える（#1560）。
-            if (toolName == "batch_query")
+    private void ExecuteAcceptedBatchSlot(
+        BatchQuerySlot slot,
+        BatchQueryResultCollector collector,
+        string toolName)
+    {
+        try
+        {
+            var response = DispatchBatchSlotTool(toolName, slot.ToolArgs);
+            if (response is null)
             {
-                AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, "batch_query cannot be nested inside batch_query.",
-                    category: McpErrorEnvelope.CategoryInvalidArgument,
-                    suggestion: "Flatten the nested batch_query into top-level slots.",
+                collector.AppendError(slot, BuildUnknownToolMessage(toolName),
+                    category: McpErrorEnvelope.CategoryToolUnknown,
+                    suggestion: "Call tools/list to see the tool catalog. Slot tool names are case-sensitive.",
                     retrySafe: false);
-                continue;
-            }
-
-            // Throttle each inner slot too, otherwise a single allowed batch_query call could
-            // still drive N inner searches through and defeat the per-(tool, caller) limiter
-            // the outer dispatch enforces. Unknown names use one fixed invalid-name bucket so
-            // one batch cannot allocate untrusted high-cardinality keys. The outer tools/call
-            // has already consumed the caller-wide pre-validation bucket (#1560 / #4547).
-            // 内側スロット単位でもスロットルする。これを行わないと外側の batch_query が 1 回通った
-            // だけで N 個の内側呼び出しが素通りし、(tool, caller) 制限が batch_query 経由で
-            // 迂回されてしまう。判定は (内側ツール, caller) 単位なので、同一バッチ内で許可スロット
-            // と超過スロットを併存させられる。unknown 名は固定 invalid-name bucket に集約し、
-            // 1 batch で未信頼の高 cardinality key を確保できないようにする。外側 tools/call は
-            // caller-wide pre-validation bucket をすでに消費済み（#1560 / #4547）。
-            var slotBucketName = ResolveKnownRateLimitBucketName(toolName) ?? RateLimiter.InvalidToolBucketName;
-            var slotDecision = RateLimiter.TryAcquire(slotBucketName, caller);
-            if (!slotDecision.Allowed)
-            {
-                AppendRateLimitedSlot(requestIndex, slotId, toolName, toolArgs, slotStopwatch, slotDecision.RetryAfterMs);
-                continue;
-            }
-
-            if (ValidateProjectFilterArguments(toolArgs) is JsonObject projectFilterError)
-            {
-                AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, projectFilterError["message"]!.GetValue<string>(),
-                    category: McpErrorEnvelope.CategoryInvalidArgument,
-                    suggestion: "Use a project name or project path from the current workspace, or correct the solution filter.",
-                    retrySafe: false,
-                    extraData: projectFilterError);
-                continue;
+                return;
             }
 
-            try
+            if (response["result"]?["isError"]?.GetValue<bool>() ?? false)
             {
-                // Execute the tool and extract the structured content / ツールを実行し構造化コンテンツを抽出
-                var previousToolOutputName = _currentToolOutputName.Value;
-                _currentToolOutputName.Value = toolName;
-                JsonNode? response;
-                try
-                {
-                    response = toolName switch
-                    {
-                        "search" => ExecuteSearch(null, toolArgs),
-                        "definition" => ExecuteDefinition(null, toolArgs),
-                        "references" => ExecuteReferences(null, toolArgs),
-                        "callers" => ExecuteCallers(null, toolArgs),
-                        "callees" => ExecuteCallees(null, toolArgs),
-                        "symbols" => ExecuteSymbols(null, toolArgs),
-                        "files" => ExecuteFiles(null, toolArgs),
-                        "find_in_file" => ExecuteFindInFile(null, toolArgs),
-                        "excerpt" => ExecuteExcerpt(null, toolArgs),
-                        "read_resource" => ExecuteReadResource(null, toolArgs),
-                        "map" => ExecuteMap(null, toolArgs),
-                        "analyze_symbol" => ExecuteAnalyzeSymbol(null, toolArgs),
-                        "status" => ExecuteStatus(null, toolArgs),
-                        "outline" => ExecuteOutline(null, toolArgs),
-                        "deps" => ExecuteDeps(null, toolArgs),
-                        "impact_analysis" => ExecuteImpactAnalysis(null, toolArgs),
-                        "languages" => ExecuteLanguages(null, toolArgs),
-                        "validate" => ExecuteValidate(null, toolArgs),
-                        "unused_symbols" => ExecuteUnusedSymbols(null, toolArgs),
-                        "symbol_hotspots" => ExecuteSymbolHotspots(null, toolArgs),
-                        "ping" => ExecutePing(null),
-                        _ => null,
-                    };
-                }
-                finally
-                {
-                    _currentToolOutputName.Value = previousToolOutputName;
-                }
-
-                if (response == null)
-                {
-                    AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, BuildUnknownToolMessage(toolName),
-                        category: McpErrorEnvelope.CategoryToolUnknown,
-                        suggestion: "Call tools/list to see the tool catalog. Slot tool names are case-sensitive.",
-                        retrySafe: false);
-                    continue;
-                }
-
-                // Check for tool-level errors (validation failures return isError=true)
-                // ツールレベルのエラーを確認（バリデーション失敗は isError=true を返す）
-                var isError = response["result"]?["isError"]?.GetValue<bool>() ?? false;
-                if (isError)
+                var errorText = response["result"]?["content"]?[0]?["text"]?.GetValue<string>() ?? "Unknown error";
+                var structured = response["result"]?["structuredContent"] as JsonObject;
+                bool? retrySafe = null;
+                if (structured?["retry_safe"] is JsonValue retryValue
+                    && retryValue.TryGetValue<bool>(out var parsedRetrySafe))
                 {
-                    var errorText = response["result"]?["content"]?[0]?["text"]?.GetValue<string>() ?? "Unknown error";
-                    // #1581: lift the inner tool's structured envelope into the batch slot so
-                    // the slot carries the same category/suggestion/retry_safe the standalone
-                    // tools/call response would have. Missing fields (older inner tools) fall
-                    // back to AppendSlotError defaults.
-                    // #1581: 内側ツールの structured envelope をスロットに転写し、tools/call
-                    // 単体呼び出しと同じカテゴリ判定をスロットでも提供する。フィールドが無い
-                    // 旧経路は AppendSlotError の既定（null = 未指定）に戻す。
-                    var innerStructured = response["result"]?["structuredContent"] as JsonObject;
-                    var innerCategory = innerStructured?["category"]?.GetValue<string>();
-                    var innerSuggestion = innerStructured?["suggestion"]?.GetValue<string>();
-                    bool? innerRetrySafe = null;
-                    if (innerStructured?["retry_safe"] is JsonValue rv && rv.TryGetValue<bool>(out var rb))
-                        innerRetrySafe = rb;
-                    AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, errorText,
-                        category: innerCategory,
-                        suggestion: innerSuggestion,
-                        retrySafe: innerRetrySafe);
-                    continue;
+                    retrySafe = parsedRetrySafe;
                 }
-
-                slotStopwatch.Stop();
-                var structured = response["result"]?["structuredContent"];
-                var slotSummary = response["result"]?["content"]?[0]?["text"]?.GetValue<string>();
-                var entry = new JsonObject
-                {
-                    ["request_index"] = requestIndex,
-                    ["ok"] = true,
-                    ["correlation_id"] = CurrentCorrelationContext.Value?.CorrelationId,
-                    ["args_summary"] = BuildArgsSummary(toolArgs),
-                    ["elapsed_ms"] = slotStopwatch.ElapsedMilliseconds,
-                    ["summary"] = slotSummary,
-                    ["result"] = structured?.DeepClone(),
-                };
-                AddBatchSlotId(entry, slotId);
-                AddToolDisplayData(entry, toolName);
-                TryAppendResult(entry, toolName, toolArgs, requestIndex, slotId, successfulSlot: true);
-                successCount++;
-            }
-            catch (Exception ex)
-            {
-                // #2849: classify and sanitize slot exceptions the same way standalone
-                // tools/call does, so bound values, paths, and SQL/content snippets stay
-                // in stderr instead of the batch_query response.
-                var dbDebugDump = Database.DbDebug.CaptureDump(ex);
-                DeferFrameLog(() =>
-                {
-                    WriteMcpLogLine(BuildToolErrorLog(toolName, ex));
-                    Database.DbDebug.WriteCapturedDumpToStderr(dbDebugDump);
-                });
-                var classification = McpErrorEnvelope.ClassifyException(ex);
-                AppendSlotError(requestIndex, slotId, toolName, toolArgs, slotStopwatch, BuildSanitizedToolErrorMessage(toolName, ex),
-                    category: classification.Category,
-                    suggestion: classification.Suggestion,
-                    retrySafe: classification.RetrySafe);
+                collector.AppendError(slot, errorText,
+                    category: structured?["category"]?.GetValue<string>(),
+                    suggestion: structured?["suggestion"]?.GetValue<string>(),
+                    retrySafe: retrySafe);
+                return;
             }
-        }
 
-        totalStopwatch.Stop();
-        var totalElapsedMs = totalStopwatch.ElapsedMilliseconds;
-        JsonObject BuildPayload()
+            collector.AppendSuccess(slot, response);
+        }
+        catch (Exception ex)
         {
-            var payload = new JsonObject
-            {
-                ["count"] = resultsArray.Count,
-                ["total_count"] = queries.Count,
-                ["success_count"] = successCount,
-                ["failure_count"] = failureCount,
-                ["partial_failure"] = failureCount > 0 || cascadeStartedAtIndex.HasValue,
-                ["failure_scope"] = GetBatchFailureScope(queries.Count, successCount, failureCount, cascadeStartedAtIndex),
-                ["cascade_started_at_index"] = cascadeStartedAtIndex,
-                ["metadata"] = new JsonObject
-                {
-                    ["submitted"] = queries.Count,
-                    ["executed"] = successCount + failureCount,
-                    ["errors"] = failureCount,
-                    ["total_elapsed_ms"] = totalElapsedMs,
-                    ["success_count"] = successCount,
-                    ["failure_count"] = failureCount,
-                    ["response_byte_limit"] = responseByteLimit,
-                    ["estimated_response_bytes"] = responseByteLimit,
-                },
-                ["results"] = resultsArray.DeepClone(),
-            };
-            adjustments.ApplyTo(payload);
-            return payload;
+            var dbDebugDump = Database.DbDebug.CaptureDump(ex);
+            DeferFrameLog(() =>
+            {
+                WriteMcpLogLine(BuildToolErrorLog(toolName, ex));
+                Database.DbDebug.WriteCapturedDumpToStderr(dbDebugDump);
+            });
+            var classification = McpErrorEnvelope.ClassifyException(ex);
+            collector.AppendError(slot, BuildSanitizedToolErrorMessage(toolName, ex),
+                category: classification.Category,
+                suggestion: classification.Suggestion,
+                retrySafe: classification.RetrySafe);
         }
+    }
 
-        string BuildSummary()
+    private JsonNode? DispatchBatchSlotTool(string toolName, JsonNode? toolArgs)
+    {
+        var previousToolOutputName = _currentToolOutputName.Value;
+        _currentToolOutputName.Value = toolName;
+        try
         {
-            var baseSummary = failureCount == 0
-                ? $"Executed {successCount + failureCount} of {queries.Count} queries in {totalElapsedMs} ms (all succeeded)."
-                : $"Executed {successCount + failureCount} of {queries.Count} queries in {totalElapsedMs} ms ({successCount} succeeded, {failureCount} failed).";
-            return truncated
-                ? baseSummary + $" Response truncated at {responseByteLimit} bytes; split the batch or lower per-slot limits."
-                : baseSummary;
+            return DispatchSynchronousToolCall(toolName, id: null, toolArgs);
         }
-
-        JsonObject payload;
-        string summary;
-        var compactSummary = false;
-        var omitSplitHint = false;
-        while (true)
+        finally
         {
-            payload = BuildPayload();
-            if (truncated)
-            {
-                payload["truncated"] = true;
-                payload["truncated_queries"] = truncatedQueries.DeepClone();
-                if (!omitSplitHint)
-                    payload["split_hint"] = BuildBatchSplitHint(queries.Count, cascadeStartedAtIndex, resultsArray.Count);
-            }
-
-            summary = BuildSummary();
-            if (compactSummary)
-                summary = $"Response truncated at {responseByteLimit} bytes.";
-            estimatedResponseBytes = EstimateJsonUtf8Bytes(CreateToolResult(id, summary, payload.DeepClone()), responseByteLimit);
-            if (estimatedResponseBytes <= responseByteLimit)
-                break;
-            if (resultsArray.Count > 0)
-            {
-                var removed = resultsArray[resultsArray.Count - 1];
-                truncated = true;
-                if (removed?["request_index"] is JsonValue requestIndexValue
-                    && requestIndexValue.TryGetValue<int>(out var removedRequestIndex))
-                {
-                    cascadeStartedAtIndex = cascadeStartedAtIndex.HasValue
-                        ? Math.Min(cascadeStartedAtIndex.Value, removedRequestIndex)
-                        : removedRequestIndex;
-                }
-                truncatedQueries.Insert(0, new JsonObject
-                {
-                    ["request_index"] = removed?["request_index"]?.DeepClone(),
-                    ["slot_id"] = removed?["slot_id"]?.DeepClone(),
-                    ["tool"] = removed?["tool"]?.DeepClone(),
-                    ["args_summary"] = removed?["args_summary"]?.DeepClone(),
-                    ["reason"] = "final_response_byte_limit_exceeded",
-                });
-                resultsArray.RemoveAt(resultsArray.Count - 1);
-                continue;
-            }
-            if (RemoveBatchTruncatedQueryToolDisplay(truncatedQueries))
-                continue;
-            if (truncatedQueries.Count > 1)
-            {
-                truncatedQueries.RemoveAt(truncatedQueries.Count - 1);
-                continue;
-            }
-            if (CompactBatchTruncatedQueryArgsSummaries(truncatedQueries))
-                continue;
-            if (truncated && !compactSummary)
-            {
-                compactSummary = true;
-                continue;
-            }
-            if (truncated && !omitSplitHint)
-            {
-                omitSplitHint = true;
-                continue;
-            }
-            break;
+            _currentToolOutputName.Value = previousToolOutputName;
         }
-
-        ((JsonObject)payload["metadata"]!)["estimated_response_bytes"] = estimatedResponseBytes;
-        return CreateToolResult(id, summary, payload);
     }
+
+    private readonly record struct BatchQuerySlot(
+        int RequestIndex,
+        JsonObject? QueryObject,
+        string? ToolName,
+        JsonNode? ToolArgs,
+        string? SlotId,
+        Stopwatch Stopwatch);
 }
diff --git a/tests/CodeIndex.Tests/McpServerBatchQueryDispatchParityTests.cs b/tests/CodeIndex.Tests/McpServerBatchQueryDispatchParityTests.cs
new file mode 100644
index 000000000..8e94767a4
--- /dev/null
+++ b/tests/CodeIndex.Tests/McpServerBatchQueryDispatchParityTests.cs
@@ -0,0 +1,217 @@
+using System.Text.Json.Nodes;
+using CodeIndex.Cli;
+using CodeIndex.Mcp;
+
+namespace CodeIndex.Tests;
+
+public partial class McpServerTests
+{
+    [Fact]
+    public void ToolsCall_BatchQuery_SynchronousReadToolsMatchDirectDispatch()
+    {
+        var calls = BuildSynchronousReadToolCalls();
+        Assert.Equal(
+            [
+                "search:{\"query\":\"Run\",\"lang\":\"csharp\",\"limit\":5}",
+                "definition:{\"query\":\"App\",\"exactName\":true}",
+                "references:{\"query\":\"Run\",\"kind\":\"call\"}",
+                "callers:{\"query\":\"Run\",\"rankBy\":\"weighted\"}",
+                "callees:{\"query\":\"App.Run\"}",
+                "symbols:{\"query\":\"App\",\"kind\":\"class\"}",
+                "files:{\"query\":\"app.cs\",\"lang\":\"csharp\"}",
+                "find_in_file:{\"path\":\"src/app.cs\",\"query\":\"Run\",\"before\":1,\"after\":1}",
+                "excerpt:{\"path\":\"src/app.cs\",\"startLine\":1,\"endLine\":5}",
+                "read_resource:{\"uri\":\"cdidx://file/src/app.cs\",\"startLine\":1,\"endLine\":5}",
+                "map:{\"limit\":5,\"excludeTests\":true}",
+                "analyze_symbol:{\"query\":\"Run\",\"includeBody\":true}",
+                "status:{\"fields\":[\"files\"]}",
+                "outline:{\"path\":\"src/app.cs\"}",
+                "deps:{\"path\":\"src/\",\"reverse\":false,\"limit\":10}",
+                "impact_analysis:{\"query\":\"Run\",\"maxHops\":2,\"withPaths\":true}",
+                "languages:{}",
+                "validate:{\"kind\":\"line_too_long\"}",
+                "unused_symbols:{\"lang\":\"csharp\",\"limit\":10}",
+                "symbol_hotspots:{\"lang\":\"csharp\",\"limit\":10}",
+                "ping:{}",
+            ],
+            calls.Select(call => $"{call.Tool}:{call.Arguments.ToJsonString()}"));
+        Assert.True(JsonNode.DeepEquals(
+            new JsonObject { ["fields"] = new JsonArray { "files" } },
+            calls.Single(call => call.Tool == "status").Arguments));
+
+        var clock = new ManualTimeProvider(new DateTimeOffset(2032, 4, 5, 6, 7, 8, TimeSpan.Zero));
+        using var server = new McpServer(
+            _dbPath,
+            ConsoleUi.LoadVersion(),
+            dbPathExplicit: false,
+            serializeResponse: null,
+            authenticator: null,
+            toolFilter: null,
+            auditLog: null,
+            maxConcurrency: McpServer.DefaultMaxConcurrency,
+            timeProvider: clock);
+        server.OverrideRateLimiterForTests(new RateLimiter(RateLimiterOptions.Disabled, clock.GetUtcNow));
+
+        for (var index = 0; index < calls.Length; index++)
+        {
+            var (tool, arguments) = calls[index];
+            var direct = server.HandleMessage(BuildToolCall(index * 2, tool, arguments.DeepClone()))!;
+            var directResult = direct["result"]!;
+            Assert.False(directResult["isError"]?.GetValue<bool>() ?? false);
+
+            var batch = server.HandleMessage(BuildSingleSlotBatchCall(index * 2 + 1, tool, arguments.DeepClone()))!;
+            var slot = Assert.Single(batch["result"]!["structuredContent"]!["results"]!.AsArray())!;
+            Assert.True(slot["ok"]!.GetValue<bool>());
+            Assert.Equal(0, slot["request_index"]!.GetValue<int>());
+            Assert.Equal(tool, slot["tool"]!.GetValue<string>());
+            Assert.Equal(
+                directResult["content"]![0]!["text"]!.GetValue<string>(),
+                slot["summary"]!.GetValue<string>());
+            var directStructured = CloneWithoutInvocationIdentity(directResult["structuredContent"]);
+            var batchStructured = CloneWithoutInvocationIdentity(slot["result"]);
+            Assert.True(
+                JsonNode.DeepEquals(directStructured, batchStructured),
+                $"Structured result differed for synchronous tool '{tool}'. Direct: {directResult["structuredContent"]?.ToJsonString()} Batch: {slot["result"]?.ToJsonString()}");
+        }
+    }
+
+    [Fact]
+    public void ToolsCall_BatchQuery_OperationCanceledSlotIsIsolatedAndOrderIsPreserved()
+    {
+        var previous = McpServer.StatusUpdateCheckForTesting;
+        McpServer.StatusUpdateCheckForTesting = (_, _) => throw new OperationCanceledException("characterization cancellation");
+        try
+        {
+            var request = new JsonObject
+            {
+                ["jsonrpc"] = "2.0",
+                ["id"] = 2,
+                ["method"] = "tools/call",
+                ["params"] = new JsonObject
+                {
+                    ["name"] = "batch_query",
+                    ["arguments"] = new JsonObject
+                    {
+                        ["queries"] = new JsonArray
+                        {
+                            new JsonObject { ["tool"] = "ping" },
+                            new JsonObject
+                            {
+                                ["tool"] = "status",
+                                ["arguments"] = new JsonObject { ["updateCheck"] = true },
+                            },
+                            new JsonObject { ["tool"] = "ping" },
+                        },
+                    },
+                },
+            };
+
+            var response = _server.HandleMessage(request)!;
+            var structured = response["result"]!["structuredContent"]!;
+            Assert.Equal(3, structured["count"]!.GetValue<int>());
+            Assert.Equal(3, structured["total_count"]!.GetValue<int>());
+            Assert.Equal(2, structured["success_count"]!.GetValue<int>());
+            Assert.Equal(1, structured["failure_count"]!.GetValue<int>());
+            Assert.True(structured["partial_failure"]!.GetValue<bool>());
+            Assert.Equal("isolated", structured["failure_scope"]!.GetValue<string>());
+            Assert.Null(structured["cascade_started_at_index"]);
+
+            var metadata = structured["metadata"]!;
+            Assert.Equal(3, metadata["submitted"]!.GetValue<int>());
+            Assert.Equal(3, metadata["executed"]!.GetValue<int>());
+            Assert.Equal(1, metadata["errors"]!.GetValue<int>());
+
+            var slots = structured["results"]!.AsArray();
+            Assert.Equal([0, 1, 2], slots.Select(slot => slot!["request_index"]!.GetValue<int>()));
+            Assert.Equal(["ping", "status", "ping"], slots.Select(slot => slot!["tool"]!.GetValue<string>()));
+            Assert.Equal([true, false, true], slots.Select(slot => slot!["ok"]!.GetValue<bool>()));
+            Assert.Contains("Tool 'status' failed", slots[1]!["error"]!.GetValue<string>(), StringComparison.Ordinal);
+            Assert.Equal(McpErrorEnvelope.CategoryRequestCancelled, slots[1]!["category"]!.GetValue<string>());
+            Assert.True(slots[1]!["retry_safe"]!.GetValue<bool>());
+            Assert.NotNull(slots[0]!["result"]!["version"]);
+            Assert.NotNull(slots[2]!["result"]!["version"]);
+        }
+        finally
+        {
+            McpServer.StatusUpdateCheckForTesting = previous;
+        }
+    }
+
+    private static (string Tool, JsonObject Arguments)[] BuildSynchronousReadToolCalls()
+        =>
+        [
+            ("search", new JsonObject { ["query"] = "Run", ["lang"] = "csharp", ["limit"] = 5 }),
+            ("definition", new JsonObject { ["query"] = "App", ["exactName"] = true }),
+            ("references", new JsonObject { ["query"] = "Run", ["kind"] = "call" }),
+            ("callers", new JsonObject { ["query"] = "Run", ["rankBy"] = "weighted" }),
+            ("callees", new JsonObject { ["query"] = "App.Run" }),
+            ("symbols", new JsonObject { ["query"] = "App", ["kind"] = "class" }),
+            ("files", new JsonObject { ["query"] = "app.cs", ["lang"] = "csharp" }),
+            ("find_in_file", new JsonObject { ["path"] = "src/app.cs", ["query"] = "Run", ["before"] = 1, ["after"] = 1 }),
+            ("excerpt", new JsonObject { ["path"] = "src/app.cs", ["startLine"] = 1, ["endLine"] = 5 }),
+            ("read_resource", new JsonObject { ["uri"] = "cdidx://file/src/app.cs", ["startLine"] = 1, ["endLine"] = 5 }),
+            ("map", new JsonObject { ["limit"] = 5, ["excludeTests"] = true }),
+            ("analyze_symbol", new JsonObject { ["query"] = "Run", ["includeBody"] = true }),
+            ("status", new JsonObject { ["fields"] = new JsonArray { "files" } }),
+            ("outline", new JsonObject { ["path"] = "src/app.cs" }),
+            ("deps", new JsonObject { ["path"] = "src/", ["reverse"] = false, ["limit"] = 10 }),
+            ("impact_analysis", new JsonObject { ["query"] = "Run", ["maxHops"] = 2, ["withPaths"] = true }),
+            ("languages", new JsonObject()),
+            ("validate", new JsonObject { ["kind"] = "line_too_long" }),
+            ("unused_symbols", new JsonObject { ["lang"] = "csharp", ["limit"] = 10 }),
+            ("symbol_hotspots", new JsonObject { ["lang"] = "csharp", ["limit"] = 10 }),
+            ("ping", new JsonObject()),
+        ];
+
+    private static JsonObject BuildToolCall(int id, string tool, JsonNode arguments)
+        => new()
+        {
+            ["jsonrpc"] = "2.0",
+            ["id"] = id,
+            ["method"] = "tools/call",
+            ["params"] = new JsonObject
+            {
+                ["name"] = tool,
+                ["arguments"] = arguments,
+            },
+        };
+
+    private static JsonObject BuildSingleSlotBatchCall(int id, string tool, JsonNode arguments)
+        => BuildToolCall(
+            id,
+            "batch_query",
+            new JsonObject
+            {
+                ["queries"] = new JsonArray
+                {
+                    new JsonObject
+                    {
+                        ["tool"] = tool,
+                        ["arguments"] = arguments,
+                    },
+                },
+            });
+
+    private static JsonNode? CloneWithoutInvocationIdentity(JsonNode? node)
+    {
+        var clone = node?.DeepClone();
+        RemoveInvocationIdentity(clone);
+        return clone;
+    }
+
+    private static void RemoveInvocationIdentity(JsonNode? node)
+    {
+        if (node is JsonObject obj)
+        {
+            obj.Remove("correlation_id");
+            obj.Remove("request_id");
+            foreach (var child in obj.Select(pair => pair.Value).ToArray())
+                RemoveInvocationIdentity(child);
+        }
+        else if (node is JsonArray array)
+        {
+            foreach (var child in array)
+                RemoveInvocationIdentity(child);
+        }
+    }
+}

From a5676466eb1b5ab2c696c3da3e52abd9cbd4521e Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 17:30:25 +0900
Subject: [PATCH 24/45] Decompose SQLite function registration

---
 ...bContext.ConnectionFunctionRegistration.cs | 323 ++++++++++++++++++
 .../Database/DbContext.ConnectionFunctions.cs | 316 +----------------
 2 files changed, 332 insertions(+), 307 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbContext.ConnectionFunctionRegistration.cs

diff --git a/src/CodeIndex/Database/DbContext.ConnectionFunctionRegistration.cs b/src/CodeIndex/Database/DbContext.ConnectionFunctionRegistration.cs
new file mode 100644
index 000000000..6a57736f6
--- /dev/null
+++ b/src/CodeIndex/Database/DbContext.ConnectionFunctionRegistration.cs
@@ -0,0 +1,323 @@
+using CodeIndex.Cli;
+using CodeIndex.Diagnostics;
+using CodeIndex.Indexer;
+using CodeIndex.Models;
+using Microsoft.Data.Sqlite;
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+
+namespace CodeIndex.Database;
+
+public partial class DbContext
+{
+    private static class ConnectionFunctionRegistrar
+    {
+        private static readonly ConditionalWeakTable<SqliteConnection, CSharpCallableTypeKindLookup>
+            CSharpCallableTypeKindLookups = new();
+        private static readonly ConditionalWeakTable<SqliteConnection, object> Registrations = new();
+        private static readonly object RegistrationLock = new();
+        private static readonly ConditionalWeakTable<SqliteConnection, object> PartialRegistrations = new();
+        private static readonly object PartialRegistrationLock = new();
+
+        internal static void Register(SqliteConnection connection)
+        {
+            lock (RegistrationLock)
+            {
+                if (Registrations.TryGetValue(connection, out _))
+                    return;
+
+                RegisterDependencyAndNameNormalizationFunctions(connection);
+                RegisterCSharpReferenceShapeFunctions(connection);
+                RegisterCSharpPartialIdentityFunctions(connection);
+                RegisterCSharpFileAndBaseFunctions(connection);
+                RegisterSqlResolutionFunctions(connection);
+                Registrations.Add(connection, new object());
+            }
+        }
+
+        private static void RegisterDependencyAndNameNormalizationFunctions(SqliteConnection connection)
+        {
+            connection.CreateFunction(
+                "markdown_resolve_path",
+                (string? sourcePath, string? targetPath) => DbReader.ResolveMarkdownDependencyPath(sourcePath, targetPath));
+            connection.CreateFunction(
+                "markdown_normalize_fragment",
+                (string? fragment) => fragment == null ? null : MarkdownAnchorIdentity.NormalizeHeadingFragment(fragment));
+            connection.CreateFunction(
+                "python_import_resolves",
+                (string? sourcePath, string? targetPath, string? referenceName, string? referenceKind, string? context, long? columnNumber, string? signature) =>
+                    PythonImportBindingResolver.ResolvesDependency(sourcePath, targetPath, referenceName, referenceKind, context, columnNumber, signature));
+            connection.CreateFunction(
+                "python_import_target_name",
+                (string? sourcePath, string? referenceName, string? context, long? columnNumber, string? signature) =>
+                    PythonImportBindingResolver.ResolveTargetName(sourcePath, referenceName, context, columnNumber, signature));
+            connection.CreateFunction(
+                "sql_leaf_name",
+                (string? name) => string.IsNullOrWhiteSpace(name) ? null : SqlNameResolver.GetLeafName(name));
+            connection.CreateFunction(
+                "sql_leaf_name_folded",
+                (string? name) => FoldSqlLeafName(name));
+            connection.CreateFunction(
+                "codeindex_name_fold",
+                (string? name) => NameFold.Fold(name),
+                isDeterministic: true);
+            connection.CreateFunction(
+                "sql_normalize_name",
+                (string? name) => string.IsNullOrWhiteSpace(name) ? null : SqlNameResolver.NormalizeQualifiedName(name));
+            connection.CreateFunction(
+                "sql_normalize_name_folded",
+                (string? name) => FoldSqlQualifiedName(name));
+            connection.CreateFunction(
+                "sql_normalize_csharp_verbatim_name",
+                (string? text) => string.IsNullOrWhiteSpace(text) ? null : CSharpVerbatimNameNormalizer.Normalize(text));
+        }
+
+        private static string? FoldSqlLeafName(string? name)
+        {
+            if (string.IsNullOrWhiteSpace(name))
+                return null;
+            var leafName = SqlNameResolver.GetLeafName(name);
+            return leafName.Length == 0 ? null : NameFold.Fold(leafName) ?? leafName;
+        }
+
+        private static string? FoldSqlQualifiedName(string? name)
+        {
+            if (string.IsNullOrWhiteSpace(name))
+                return null;
+            var normalizedName = SqlNameResolver.NormalizeQualifiedName(name);
+            return normalizedName.Length == 0 ? null : NameFold.Fold(normalizedName) ?? normalizedName;
+        }
+
+        private static void RegisterCSharpReferenceShapeFunctions(SqliteConnection connection)
+        {
+            connection.CreateFunction(
+                "csharp_identifier_occurrence_count",
+                (string? text, string? identifier) => CountCSharpIdentifierOccurrences(text, identifier));
+            connection.CreateFunction(
+                "csharp_identifier_occurrence_count_in_line_range",
+                (string? text, long? chunkStartLine, long? rangeStartLine, long? rangeEndLine, string? identifier) =>
+                    CountCSharpIdentifierOccurrencesInLineRange(text, chunkStartLine, rangeStartLine, rangeEndLine, identifier));
+            connection.CreateFunction(
+                "csharp_reference_type_arity",
+                (string? context, string? identifier, long? columnNumber) =>
+                    CSharpTypeReferenceArity.GetReferenceArity(context, identifier, columnNumber));
+            connection.CreateFunction(
+                "csharp_reference_is_member_receiver",
+                (string? context, string? identifier, long? columnNumber) =>
+                    CSharpTypeReferenceArity.IsMemberReceiver(context, identifier, columnNumber));
+            connection.CreateFunction(
+                "csharp_definition_type_arity",
+                (string? signature, string? identifier, string? symbolKind) =>
+                    CSharpTypeReferenceArity.GetDefinitionArity(signature, identifier, symbolKind));
+            connection.CreateFunction(
+                "csharp_constructor_parameter_count",
+                (string? signature, string? identifier, string? symbolKind) =>
+                    CSharpTypeReferenceArity.GetConstructorParameterCount(signature, identifier, symbolKind));
+        }
+
+        private static void RegisterCSharpPartialIdentityFunctions(SqliteConnection connection)
+        {
+            var typeKinds = CSharpCallableTypeKindLookups.GetValue(
+                connection,
+                static _ => new CSharpCallableTypeKindLookup());
+            connection.CreateFunction(
+                "csharp_partial_callable_identity",
+                (string? signature, string? identifier, string? returnType) =>
+                    LogicalPartialSymbolGrouper.BuildCallableIdentity(
+                        signature, identifier, returnType, containerQualifiedName: null, typeKinds: null),
+                isDeterministic: true);
+            connection.CreateFunction(
+                "csharp_partial_callable_identity",
+                (string? signature, string? identifier, string? returnType, string? containerQualifiedName) =>
+                    LogicalPartialSymbolGrouper.BuildCallableIdentity(
+                        signature, identifier, returnType, containerQualifiedName, typeKinds));
+            connection.CreateFunction(
+                "csharp_partial_callable_identity",
+                (string? signature, string? identifier, string? returnType, string? containerQualifiedName, long? symbolId) =>
+                    LogicalPartialSymbolGrouper.BuildCallableIdentity(
+                        signature, identifier, returnType, containerQualifiedName, typeKinds, symbolId));
+            connection.CreateFunction(
+                "csharp_partial_semantic_score",
+                (string? signature, string? symbolKind) =>
+                    LogicalPartialSymbolGrouper.GetSemanticScore(signature, symbolKind),
+                isDeterministic: true);
+            connection.CreateFunction(
+                "csharp_partial_declaration_identity",
+                (string? signature) => LogicalPartialSymbolGrouper.BuildCanonicalDeclarationIdentity(signature),
+                isDeterministic: true);
+            RegisterCSharpPartialDeclaration(connection);
+        }
+
+        private static void RegisterCSharpFileAndBaseFunctions(SqliteConnection connection)
+        {
+            connection.CreateFunction(
+                "codeindex_generated_file_name",
+                (string? path) => FileIndexer.HasGeneratedCodeFileName(path ?? string.Empty),
+                isDeterministic: true);
+            connection.CreateFunction(
+                "csharp_invocation_argument_count",
+                (string? context, string? identifier, long? columnNumber) =>
+                    CSharpTypeReferenceArity.GetInvocationArgumentCount(context, identifier, columnNumber));
+            connection.CreateFunction(
+                "csharp_definition_is_value_type",
+                (string? signature, string? symbolKind) =>
+                    CSharpTypeReferenceArity.IsValueTypeDeclaration(signature, symbolKind));
+            connection.CreateFunction(
+                "csharp_base_identifiers_json",
+                (string? signature) => JsonSerializer.Serialize(
+                    CSharpBaseListParser.Parse(signature, CSharpBaseListProjection.HeadIdentifier),
+                    CliJsonSerializerContext.Default.ListString));
+            connection.CreateFunction(
+                "csharp_base_name_folded",
+                (string? baseReference) =>
+                {
+                    var leaf = GetCSharpBaseReferenceLeaf(baseReference);
+                    return leaf == null ? null : NameFold.Fold(leaf) ?? leaf;
+                });
+            connection.CreateFunction(
+                "csharp_base_name",
+                (string? baseReference) => GetCSharpBaseReferenceLeaf(baseReference));
+            connection.CreateFunction(
+                "csharp_base_reference_matches",
+                (string? baseReference, string? candidateName, string? candidateQualifiedName, string? derivingQualifiedName) =>
+                    CSharpBaseReferenceMatches(baseReference, candidateName, candidateQualifiedName, derivingQualifiedName) ? 1 : 0);
+        }
+
+        private static void RegisterSqlResolutionFunctions(SqliteConnection connection)
+        {
+            connection.CreateFunction(
+                "sql_normalize_exact_source_name",
+                (string? text, string? lang) => string.IsNullOrWhiteSpace(text) ? null : ExactSourceSearchNormalizer.Normalize(text, lang));
+            connection.CreateFunction(
+                "sql_segment_count",
+                (string? name) => string.IsNullOrWhiteSpace(name) ? (int?)null : SqlNameResolver.GetSegmentCount(name));
+            RegisterSqlContextFunctions(connection);
+            RegisterSqlReferenceFunctions(connection);
+        }
+
+        private static void RegisterSqlContextFunctions(SqliteConnection connection)
+        {
+            connection.CreateFunction(
+                "sql_context_has_name",
+                (string? context, string? query) => SqlNameResolver.ContextContainsQualifiedName(context, query) ? 1 : 0);
+            connection.CreateFunction(
+                "sql_context_has_name_folded",
+                (string? context, string? query) => SqlNameResolver.ContextContainsQualifiedNameFolded(context, query) ? 1 : 0);
+            connection.CreateFunction(
+                "sql_context_has_name_at",
+                (string? context, string? query, long? columnNumber) =>
+                    SqlNameResolver.ContextContainsQualifiedNameAtColumn(context, query, ToNullableInt(columnNumber)) ? 1 : 0);
+            connection.CreateFunction(
+                "sql_context_has_name_folded_at",
+                (string? context, string? query, long? columnNumber) =>
+                    SqlNameResolver.ContextContainsQualifiedNameFoldedAtColumn(context, query, ToNullableInt(columnNumber)) ? 1 : 0);
+            connection.CreateFunction(
+                "sql_context_like_name_at",
+                (string? context, string? query, long? columnNumber) =>
+                    SqlNameResolver.ContextContainsQualifiedNameLikeAtColumn(context, query, ToNullableInt(columnNumber)) ? 1 : 0);
+            connection.CreateFunction(
+                "sql_context_like_name_folded_at",
+                (string? context, string? query, long? columnNumber) =>
+                    SqlNameResolver.ContextContainsQualifiedNameLikeFoldedAtColumn(context, query, ToNullableInt(columnNumber)) ? 1 : 0);
+        }
+
+        private static void RegisterSqlReferenceFunctions(SqliteConnection connection)
+        {
+            connection.CreateFunction(
+                "sql_resolve_reference_name",
+                (string? symbolName, string? context, string? containerName) => EmptyAsNull(
+                    SqlNameResolver.ResolveReferenceName(symbolName, context, containerName)));
+            connection.CreateFunction(
+                "sql_resolve_reference_name_folded",
+                (string? symbolName, string? context, string? containerName) => EmptyAsNull(
+                    SqlNameResolver.ResolveReferenceNameFolded(symbolName, context, containerName)));
+            connection.CreateFunction(
+                "sql_resolve_reference_name_at",
+                (string? symbolName, string? context, string? containerName, long? columnNumber) => EmptyAsNull(
+                    SqlNameResolver.ResolveReferenceNameAtColumn(symbolName, context, containerName, ToNullableInt(columnNumber))));
+            connection.CreateFunction(
+                "sql_resolve_reference_name_folded_at",
+                (string? symbolName, string? context, string? containerName, long? columnNumber) => EmptyAsNull(
+                    SqlNameResolver.ResolveReferenceNameFoldedAtColumn(symbolName, context, containerName, ToNullableInt(columnNumber))));
+            connection.CreateFunction(
+                "sql_resolve_reference_segment_count_at",
+                (string? symbolName, string? context, string? containerName, long? columnNumber) => (int?)(
+                    SqlNameResolver.ResolveReferenceSegmentCountAtColumn(symbolName, context, containerName, ToNullableInt(columnNumber)) is var count
+                    && count > 0 ? count : null));
+            connection.CreateFunction(
+                "sql_reference_matches_target_at",
+                (string? symbolName, string? context, string? containerName, long? columnNumber, string? targetName) =>
+                    SqlNameResolver.ReferenceMatchesTargetAtColumn(
+                        symbolName, context, containerName, ToNullableInt(columnNumber), targetName) ? 1 : 0);
+            connection.CreateFunction(
+                "sql_allow_leaf_fallback_at",
+                (string? symbolName, string? context, string? containerName, long? columnNumber) =>
+                    SqlNameResolver.AllowLeafFallbackAtColumn(
+                        symbolName, context, containerName, ToNullableInt(columnNumber)) ? 1 : 0);
+        }
+
+        private static string? EmptyAsNull(string value) => value.Length == 0 ? null : value;
+
+        private static int? ToNullableInt(long? value)
+            => value is null || value < int.MinValue || value > int.MaxValue ? null : (int)value.Value;
+
+        internal static void RegisterCSharpPartialDeclaration(SqliteConnection connection)
+        {
+            lock (PartialRegistrationLock)
+            {
+                // Raw DbReader connections need this function, while active statements make
+                // re-registration unsafe; keep its guard independent from the full family.
+                if (PartialRegistrations.TryGetValue(connection, out _))
+                    return;
+
+                connection.CreateFunction(
+                    "csharp_is_partial_declaration",
+                    (string? signature, string? kind, string? name) =>
+                        LogicalPartialSymbolGrouper.ContainsPartialModifier(signature, kind, name),
+                    isDeterministic: true);
+                PartialRegistrations.Add(connection, new object());
+            }
+        }
+
+        internal static void RefreshCSharpCallableTypeKinds(
+            SqliteConnection connection,
+            IReadOnlySet<string> fileColumns,
+            IReadOnlySet<string> symbolColumns,
+            IReadOnlyList<string>? candidateQueries,
+            bool exact,
+            bool useFoldedNames)
+        {
+            var lookup = CSharpCallableTypeKindLookups.GetValue(
+                connection,
+                static _ => new CSharpCallableTypeKindLookup());
+            lookup.RefreshIfChanged(connection, fileColumns, symbolColumns, candidateQueries, exact, useFoldedNames);
+        }
+
+        internal static void RegisterWithRetry(
+            SqliteConnection connection,
+            Action<int>? sleep,
+            int maxAttempts,
+            CancellationToken cancellationToken,
+            Action<SqliteConnection>? registerConnectionFunctions)
+        {
+            if (maxAttempts <= 0)
+                throw new ArgumentOutOfRangeException(nameof(maxAttempts), maxAttempts, "Must be at least 1.");
+
+            cancellationToken.ThrowIfCancellationRequested();
+            registerConnectionFunctions ??= RegisterConnectionFunctions;
+            for (var attempt = 1; attempt <= maxAttempts; attempt++)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                try
+                {
+                    registerConnectionFunctions(connection);
+                    return;
+                }
+                catch (SqliteException ex) when (DbConnectionFactory.IsTransientBusyError(ex) && attempt < maxAttempts)
+                {
+                    DbConnectionFactory.SleepBeforeRetry(50 * attempt, sleep, cancellationToken);
+                }
+            }
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbContext.ConnectionFunctions.cs b/src/CodeIndex/Database/DbContext.ConnectionFunctions.cs
index c9b321681..f82adcf44 100644
--- a/src/CodeIndex/Database/DbContext.ConnectionFunctions.cs
+++ b/src/CodeIndex/Database/DbContext.ConnectionFunctions.cs
@@ -1,26 +1,10 @@
-using CodeIndex.Cli;
-using CodeIndex.Diagnostics;
 using CodeIndex.Indexer;
-using CodeIndex.Models;
 using Microsoft.Data.Sqlite;
-using System.Globalization;
-using System.Runtime.CompilerServices;
-using System.Runtime.ExceptionServices;
-using System.Text.Json;
 
 namespace CodeIndex.Database;
 
 public partial class DbContext : IDisposable
 {
-    private static readonly ConditionalWeakTable<SqliteConnection, CSharpCallableTypeKindLookup>
-        CSharpCallableTypeKindLookups = new();
-    private static readonly ConditionalWeakTable<SqliteConnection, object>
-        ConnectionFunctionRegistrations = new();
-    private static readonly object ConnectionFunctionRegistrationLock = new();
-    private static readonly ConditionalWeakTable<SqliteConnection, object>
-        CSharpPartialDeclarationFunctionRegistrations = new();
-    private static readonly object CSharpPartialDeclarationFunctionRegistrationLock = new();
-
     private static SqliteConnection OpenArtifactPreservingQueryOnly(string dbPath)
     {
         var connection = CreateArtifactPreservingQueryOnlyConnection(
@@ -34,272 +18,10 @@ private static SqliteConnection OpenArtifactPreservingQueryOnly(string dbPath)
     }
 
     internal static void RegisterConnectionFunctions(SqliteConnection connection)
-    {
-        lock (ConnectionFunctionRegistrationLock)
-        {
-            if (ConnectionFunctionRegistrations.TryGetValue(connection, out _))
-                return;
-
-            RegisterConnectionFunctionsCore(connection);
-            ConnectionFunctionRegistrations.Add(connection, new object());
-        }
-    }
-
-    private static void RegisterConnectionFunctionsCore(SqliteConnection connection)
-    {
-        static int? ToNullableInt(long? value)
-            => value is null || value < int.MinValue || value > int.MaxValue ? null : (int)value.Value;
-
-        connection.CreateFunction(
-            "markdown_resolve_path",
-            (string? sourcePath, string? targetPath) => DbReader.ResolveMarkdownDependencyPath(sourcePath, targetPath));
-        connection.CreateFunction(
-            "markdown_normalize_fragment",
-            (string? fragment) => fragment == null
-                ? null
-                : MarkdownAnchorIdentity.NormalizeHeadingFragment(fragment));
-        connection.CreateFunction(
-            "python_import_resolves",
-            (string? sourcePath, string? targetPath, string? referenceName, string? referenceKind, string? context, long? columnNumber, string? signature) =>
-                PythonImportBindingResolver.ResolvesDependency(sourcePath, targetPath, referenceName, referenceKind, context, columnNumber, signature));
-        connection.CreateFunction(
-            "python_import_target_name",
-            (string? sourcePath, string? referenceName, string? context, long? columnNumber, string? signature) =>
-                PythonImportBindingResolver.ResolveTargetName(sourcePath, referenceName, context, columnNumber, signature));
-        connection.CreateFunction(
-            "sql_leaf_name",
-            (string? name) => string.IsNullOrWhiteSpace(name) ? null : SqlNameResolver.GetLeafName(name));
-        connection.CreateFunction(
-            "sql_leaf_name_folded",
-            (string? name) =>
-            {
-                if (string.IsNullOrWhiteSpace(name))
-                    return null;
-
-                var leafName = SqlNameResolver.GetLeafName(name);
-                return leafName.Length == 0 ? null : NameFold.Fold(leafName) ?? leafName;
-            });
-        connection.CreateFunction(
-            "codeindex_name_fold",
-            (string? name) => NameFold.Fold(name),
-            isDeterministic: true);
-        connection.CreateFunction(
-            "sql_normalize_name",
-            (string? name) => string.IsNullOrWhiteSpace(name) ? null : SqlNameResolver.NormalizeQualifiedName(name));
-        connection.CreateFunction(
-            "sql_normalize_name_folded",
-            (string? name) =>
-            {
-                if (string.IsNullOrWhiteSpace(name))
-                    return null;
-
-                var normalizedName = SqlNameResolver.NormalizeQualifiedName(name);
-                return normalizedName.Length == 0 ? null : NameFold.Fold(normalizedName) ?? normalizedName;
-            });
-        connection.CreateFunction(
-            "sql_normalize_csharp_verbatim_name",
-            (string? text) => string.IsNullOrWhiteSpace(text) ? null : CSharpVerbatimNameNormalizer.Normalize(text));
-        connection.CreateFunction(
-            "csharp_identifier_occurrence_count",
-            (string? text, string? identifier) => CountCSharpIdentifierOccurrences(text, identifier));
-        connection.CreateFunction(
-            "csharp_identifier_occurrence_count_in_line_range",
-            (string? text, long? chunkStartLine, long? rangeStartLine, long? rangeEndLine, string? identifier) =>
-                CountCSharpIdentifierOccurrencesInLineRange(
-                    text,
-                    chunkStartLine,
-                    rangeStartLine,
-                    rangeEndLine,
-                    identifier));
-        connection.CreateFunction(
-            "csharp_reference_type_arity",
-            (string? context, string? identifier, long? columnNumber) =>
-                CSharpTypeReferenceArity.GetReferenceArity(context, identifier, columnNumber));
-        connection.CreateFunction(
-            "csharp_reference_is_member_receiver",
-            (string? context, string? identifier, long? columnNumber) =>
-                CSharpTypeReferenceArity.IsMemberReceiver(context, identifier, columnNumber));
-        connection.CreateFunction(
-            "csharp_definition_type_arity",
-            (string? signature, string? identifier, string? symbolKind) =>
-                CSharpTypeReferenceArity.GetDefinitionArity(signature, identifier, symbolKind));
-        connection.CreateFunction(
-            "csharp_constructor_parameter_count",
-            (string? signature, string? identifier, string? symbolKind) =>
-                CSharpTypeReferenceArity.GetConstructorParameterCount(signature, identifier, symbolKind));
-        var csharpCallableTypeKinds = CSharpCallableTypeKindLookups.GetValue(
-            connection,
-            static _ => new CSharpCallableTypeKindLookup());
-        connection.CreateFunction(
-            "csharp_partial_callable_identity",
-            (string? signature, string? identifier, string? returnType) =>
-                LogicalPartialSymbolGrouper.BuildCallableIdentity(
-                    signature,
-                    identifier,
-                    returnType,
-                    containerQualifiedName: null,
-                    typeKinds: null),
-            isDeterministic: true);
-        connection.CreateFunction(
-            "csharp_partial_callable_identity",
-            (string? signature, string? identifier, string? returnType, string? containerQualifiedName) =>
-                LogicalPartialSymbolGrouper.BuildCallableIdentity(
-                    signature,
-                    identifier,
-                    returnType,
-                    containerQualifiedName,
-                    csharpCallableTypeKinds));
-        connection.CreateFunction(
-            "csharp_partial_callable_identity",
-            (string? signature, string? identifier, string? returnType, string? containerQualifiedName, long? symbolId) =>
-                LogicalPartialSymbolGrouper.BuildCallableIdentity(
-                    signature,
-                    identifier,
-                    returnType,
-                    containerQualifiedName,
-                    csharpCallableTypeKinds,
-                    symbolId));
-        connection.CreateFunction(
-            "csharp_partial_semantic_score",
-            (string? signature, string? symbolKind) =>
-                LogicalPartialSymbolGrouper.GetSemanticScore(signature, symbolKind),
-            isDeterministic: true);
-        connection.CreateFunction(
-            "csharp_partial_declaration_identity",
-            (string? signature) =>
-                LogicalPartialSymbolGrouper.BuildCanonicalDeclarationIdentity(signature),
-            isDeterministic: true);
-        RegisterCSharpPartialDeclarationFunction(connection);
-        connection.CreateFunction(
-            "codeindex_generated_file_name",
-            (string? path) => FileIndexer.HasGeneratedCodeFileName(path ?? string.Empty),
-            isDeterministic: true);
-        connection.CreateFunction(
-            "csharp_invocation_argument_count",
-            (string? context, string? identifier, long? columnNumber) =>
-                CSharpTypeReferenceArity.GetInvocationArgumentCount(context, identifier, columnNumber));
-        connection.CreateFunction(
-            "csharp_definition_is_value_type",
-            (string? signature, string? symbolKind) =>
-                CSharpTypeReferenceArity.IsValueTypeDeclaration(signature, symbolKind));
-        connection.CreateFunction(
-            "csharp_base_identifiers_json",
-            (string? signature) =>
-                JsonSerializer.Serialize(
-                    CSharpBaseListParser.Parse(signature, CSharpBaseListProjection.HeadIdentifier),
-                    CliJsonSerializerContext.Default.ListString));
-        connection.CreateFunction(
-            "csharp_base_name_folded",
-            (string? baseReference) =>
-            {
-                var leaf = GetCSharpBaseReferenceLeaf(baseReference);
-                return leaf == null ? null : NameFold.Fold(leaf) ?? leaf;
-            });
-        connection.CreateFunction(
-            "csharp_base_name",
-            (string? baseReference) => GetCSharpBaseReferenceLeaf(baseReference));
-        connection.CreateFunction(
-            "csharp_base_reference_matches",
-            (string? baseReference, string? candidateName, string? candidateQualifiedName, string? derivingQualifiedName) =>
-                CSharpBaseReferenceMatches(
-                    baseReference,
-                    candidateName,
-                    candidateQualifiedName,
-                    derivingQualifiedName) ? 1 : 0);
-        connection.CreateFunction(
-            "sql_normalize_exact_source_name",
-            (string? text, string? lang) => string.IsNullOrWhiteSpace(text) ? null : ExactSourceSearchNormalizer.Normalize(text, lang));
-        connection.CreateFunction(
-            "sql_segment_count",
-            (string? name) => string.IsNullOrWhiteSpace(name) ? (int?)null : SqlNameResolver.GetSegmentCount(name));
-        connection.CreateFunction(
-            "sql_context_has_name",
-            (string? context, string? query) => SqlNameResolver.ContextContainsQualifiedName(context, query) ? 1 : 0);
-        connection.CreateFunction(
-            "sql_context_has_name_folded",
-            (string? context, string? query) => SqlNameResolver.ContextContainsQualifiedNameFolded(context, query) ? 1 : 0);
-        connection.CreateFunction(
-            "sql_context_has_name_at",
-            (string? context, string? query, long? columnNumber) =>
-                SqlNameResolver.ContextContainsQualifiedNameAtColumn(context, query, ToNullableInt(columnNumber)) ? 1 : 0);
-        connection.CreateFunction(
-            "sql_context_has_name_folded_at",
-            (string? context, string? query, long? columnNumber) =>
-                SqlNameResolver.ContextContainsQualifiedNameFoldedAtColumn(context, query, ToNullableInt(columnNumber)) ? 1 : 0);
-        connection.CreateFunction(
-            "sql_context_like_name_at",
-            (string? context, string? query, long? columnNumber) =>
-                SqlNameResolver.ContextContainsQualifiedNameLikeAtColumn(context, query, ToNullableInt(columnNumber)) ? 1 : 0);
-        connection.CreateFunction(
-            "sql_context_like_name_folded_at",
-            (string? context, string? query, long? columnNumber) =>
-                SqlNameResolver.ContextContainsQualifiedNameLikeFoldedAtColumn(context, query, ToNullableInt(columnNumber)) ? 1 : 0);
-        connection.CreateFunction(
-            "sql_resolve_reference_name",
-            (string? symbolName, string? context, string? containerName) =>
-            {
-                var resolved = SqlNameResolver.ResolveReferenceName(symbolName, context, containerName);
-                return resolved.Length == 0 ? null : resolved;
-            });
-        connection.CreateFunction(
-            "sql_resolve_reference_name_folded",
-            (string? symbolName, string? context, string? containerName) =>
-            {
-                var resolved = SqlNameResolver.ResolveReferenceNameFolded(symbolName, context, containerName);
-                return resolved.Length == 0 ? null : resolved;
-            });
-        connection.CreateFunction(
-            "sql_resolve_reference_name_at",
-            (string? symbolName, string? context, string? containerName, long? columnNumber) =>
-            {
-                var resolved = SqlNameResolver.ResolveReferenceNameAtColumn(symbolName, context, containerName, ToNullableInt(columnNumber));
-                return resolved.Length == 0 ? null : resolved;
-            });
-        connection.CreateFunction(
-            "sql_resolve_reference_name_folded_at",
-            (string? symbolName, string? context, string? containerName, long? columnNumber) =>
-            {
-                var resolved = SqlNameResolver.ResolveReferenceNameFoldedAtColumn(symbolName, context, containerName, ToNullableInt(columnNumber));
-                return resolved.Length == 0 ? null : resolved;
-            });
-        connection.CreateFunction(
-            "sql_resolve_reference_segment_count_at",
-            (string? symbolName, string? context, string? containerName, long? columnNumber) => (int?)(
-                SqlNameResolver.ResolveReferenceSegmentCountAtColumn(symbolName, context, containerName, ToNullableInt(columnNumber)) is var segmentCount
-                && segmentCount > 0
-                    ? segmentCount
-                    : null));
-        connection.CreateFunction(
-            "sql_reference_matches_target_at",
-            (string? symbolName, string? context, string? containerName, long? columnNumber, string? targetName) =>
-                SqlNameResolver.ReferenceMatchesTargetAtColumn(symbolName, context, containerName, ToNullableInt(columnNumber), targetName) ? 1 : 0);
-        connection.CreateFunction(
-            "sql_allow_leaf_fallback_at",
-            (string? symbolName, string? context, string? containerName, long? columnNumber) =>
-                SqlNameResolver.AllowLeafFallbackAtColumn(symbolName, context, containerName, ToNullableInt(columnNumber)) ? 1 : 0);
-    }
+        => ConnectionFunctionRegistrar.Register(connection);
 
     internal static void RegisterCSharpPartialDeclarationFunction(SqliteConnection connection)
-    {
-        lock (CSharpPartialDeclarationFunctionRegistrationLock)
-        {
-            // DbReader also accepts caller-owned raw connections, so it must ensure this
-            // function exists. DbContext connections already registered it, however, and
-            // SQLite rejects replacing a function while any statement is active.
-            // DbReader は caller-owned raw connection も受け付けるため、この function を
-            // 保証する。一方 DbContext connection では登録済みであり、active statement 中の
-            // 再登録を SQLite が拒否するため、connection 単位で一度だけ登録する。
-            if (CSharpPartialDeclarationFunctionRegistrations.TryGetValue(connection, out _))
-                return;
-
-            connection.CreateFunction(
-                "csharp_is_partial_declaration",
-                (string? signature, string? kind, string? name) =>
-                    LogicalPartialSymbolGrouper.ContainsPartialModifier(signature, kind, name),
-                isDeterministic: true);
-            CSharpPartialDeclarationFunctionRegistrations.Add(connection, new object());
-        }
-    }
+        => ConnectionFunctionRegistrar.RegisterCSharpPartialDeclaration(connection);
 
     internal static void RefreshCSharpCallableTypeKinds(
         SqliteConnection connection,
@@ -308,18 +30,13 @@ internal static void RefreshCSharpCallableTypeKinds(
         IReadOnlyList<string>? candidateQueries = null,
         bool exact = false,
         bool useFoldedNames = false)
-    {
-        var lookup = CSharpCallableTypeKindLookups.GetValue(
-            connection,
-            static _ => new CSharpCallableTypeKindLookup());
-        lookup.RefreshIfChanged(
+        => ConnectionFunctionRegistrar.RefreshCSharpCallableTypeKinds(
             connection,
             fileColumns,
             symbolColumns,
             candidateQueries,
             exact,
             useFoldedNames);
-    }
 
     internal static int CountCSharpIdentifierOccurrences(string? text, string? identifier)
     {
@@ -835,25 +552,10 @@ internal static void RegisterConnectionFunctionsWithRetry(
         int maxAttempts = 5,
         CancellationToken cancellationToken = default,
         Action<SqliteConnection>? registerConnectionFunctions = null)
-    {
-        if (maxAttempts <= 0)
-            throw new ArgumentOutOfRangeException(nameof(maxAttempts), maxAttempts, "Must be at least 1.");
-
-        cancellationToken.ThrowIfCancellationRequested();
-        registerConnectionFunctions ??= RegisterConnectionFunctions;
-        for (var attempt = 1; attempt <= maxAttempts; attempt++)
-        {
-            cancellationToken.ThrowIfCancellationRequested();
-            try
-            {
-                registerConnectionFunctions(connection);
-                return;
-            }
-            catch (SqliteException ex) when (DbConnectionFactory.IsTransientBusyError(ex) && attempt < maxAttempts)
-            {
-                DbConnectionFactory.SleepBeforeRetry(50 * attempt, sleep, cancellationToken);
-            }
-        }
-    }
-
+        => ConnectionFunctionRegistrar.RegisterWithRetry(
+            connection,
+            sleep,
+            maxAttempts,
+            cancellationToken,
+            registerConnectionFunctions);
 }

From faca72321b43aea0ece5263812497451471cf90e Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 18:07:25 +0900
Subject: [PATCH 25/45] Decompose core reference extraction orchestration

---
 TESTING_GUIDE.md                              |   6 +-
 ...ferenceExtractor.CoreExtraction.Context.cs |  87 ++++
 ...renceExtractor.CoreExtraction.Execution.cs |  51 ++
 ...ceExtractor.CoreExtraction.Finalization.cs | 131 +++++
 ...ferenceExtractor.CoreExtraction.Lookups.cs | 298 ++++++++++++
 ...nceExtractor.CoreExtraction.Preparation.cs |  87 ++++
 .../ReferenceExtractor.CoreExtraction.cs      | 449 +-----------------
 .../ReferenceExtractorSolidityTests.cs        |  41 ++
 .../ReferenceExtractorTests.cs                |  39 ++
 9 files changed, 751 insertions(+), 438 deletions(-)
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Context.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Execution.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Finalization.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Lookups.cs
 create mode 100644 src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Preparation.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 1c3b6516b..3db091bde 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -586,7 +586,8 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
 - Go function-like symbol coverage shares qualified receiver containers and branch labels in one file fixture while excluding switch keywords.
 - Consolidated Python/Go extractor fixtures retain exact symbol/reference cardinality, including complete per-container result sets, and source-line assertions when those were part of the original regression contract.
 - Assembly reference coverage shares direct call/branch forms and tab-separated decorated indirect-target negatives in one exact-cardinality fixture.
-- Solidity reference coverage shares inheritance whitespace variants, library/modifier/event/interface edges, and comment/string negatives in one fixture.
+- Solidity reference coverage shares inheritance whitespace variants, library/modifier/event/interface edges, and comment/string negatives in one fixture. Its detailed early-return fixture lowers the definition and container safety limits together and asserts that both diagnostics survive before Solidity-specific extraction returns.
+- Python mutual-recursion finalization coverage keeps a complete two-edge cycle ahead of a capped later call and asserts that the retained cycle is still marked when the reference list is already full.
 - Terraform reference coverage shares resource/module/data traversals and raw `var`/`local` object references in one exact-per-name fixture.
 - Language masker copy-on-write coverage pairs unchanged-array reuse and required-clone behavior within the same Lua and Solidity test methods.
 - COBOL target-statement coverage places SQL/CICS, report, sort, queue, file, literal, and external-call variants in one program and checks exact grouped edge counts.
@@ -1642,7 +1643,8 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
 - Go function-like symbol coverage は qualified receiver container と branch label を1つの file fixture で共有し、switch keyword を除外します。
 - 統合した Python/Go extractor fixture でも、container ごとの完全な result set を含む symbol/reference の厳密な件数と、元の回帰契約に含まれていた source line の assertion を維持します。
 - Assembly reference coverage は direct call/branch と tab 区切り decorated indirect-target の negative case を、厳密な件数を持つ1つの fixture で共有します。
-- Solidity reference coverage は inheritance whitespace variant、library/modifier/event/interface edge、comment/string negative を1つの fixture で共有します。
+- Solidity reference coverage は inheritance whitespace variant、library/modifier/event/interface edge、comment/string negative を1つの fixture で共有します。詳細 early-return fixture では definition と container の safety limit を同時に下げ、Solidity 固有抽出から戻る前に両方の diagnostic が維持されることを検証します。
+- Python mutual-recursion finalization coverage は、上限で除外される後続 call より前に完全な2-edge cycle を置き、reference list が既に満杯でも保持済み cycle が mutual として印付けされることを検証します。
 - Terraform reference coverage は resource/module/data traversal と raw `var`/`local` object reference を、name ごとの厳密な件数を持つ1つの fixture で共有します。
 - Language masker の copy-on-write coverage は、変更不要時の配列再利用と mask 必要時の clone を Lua/Solidity それぞれ同じテストメソッド内で検証します。
 - COBOL target-statement coverage は SQL/CICS、report、sort、queue、file、literal、external-call variant を1つの program に配置し、group ごとの edge 件数を厳密に検証します。
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Context.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Context.cs
new file mode 100644
index 000000000..268da7abd
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Context.cs
@@ -0,0 +1,87 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static CoreReferenceLoopContext CreateCoreReferenceLoopContext(
+        CoreExtractionPreparation preparation,
+        CorePreSolidityLookups preSolidityLookups)
+    {
+        var request = preparation.Request;
+        var lines = preparation.Lines.Lines;
+        var postSolidityLookups = BuildCorePostSolidityLookups(
+            preparation,
+            preSolidityLookups);
+        var references = CreateReferenceList(
+            request.MaxReferenceCount,
+            EstimateReferenceListInitialCapacity(lines.Length));
+        var seen = CreateReferenceSeenSet(lines.Length);
+
+        return new CoreReferenceLoopContext
+        {
+            Request = request,
+            Preparation = preparation.Lines,
+            IsJsxFile = preparation.IsJsxFile,
+            IsRazorFile = preparation.IsRazorFile,
+            XamlReferenceEnabled = preparation.XamlReferenceEnabled,
+            ScientificNativeDependencyLimit =
+                preSolidityLookups.ScientificNativeDependencyLimit,
+            CSharpAttributeRanges =
+                preSolidityLookups.CSharpAttributes.Ranges,
+            CSharpAttributeTopLevelRanges =
+                preSolidityLookups.CSharpAttributes.TopLevelRanges,
+            DefinitionNamesComparer =
+                preSolidityLookups.Definitions.Comparer,
+            DefinitionNamesByLine =
+                preSolidityLookups.Definitions.NamesByLine,
+            ScientificDefinitionNameIndicesByLine =
+                preSolidityLookups.Definitions.ScientificNameIndicesByLine,
+            AllDefinitionNames =
+                preSolidityLookups.Definitions.AllNames,
+            FileDefinitionNames =
+                preSolidityLookups.Definitions.FileNames,
+            SqlDefinitionLeafSpansByLine =
+                preSolidityLookups.Sql.DefinitionLeafSpansByLine,
+            SqlWindowFunctionCallSiteSuppressions =
+                preSolidityLookups.Sql.WindowFunctionCallSiteSuppressions,
+            CobolCallableSymbols = preSolidityLookups.CobolCallableSymbols,
+            ContainerCandidates = preSolidityLookups.Containers.Candidates,
+            ContainerResolver = preSolidityLookups.Containers.Resolver,
+            SwiftPropertyDefinitionsByLine =
+                postSolidityLookups.Language.SwiftPropertyDefinitionsByLine,
+            CSharpQualifiedEnumMemberLookup =
+                postSolidityLookups.CSharp.QualifiedEnumMembers,
+            CSharpQualifiedConstantPatternMemberLookup =
+                postSolidityLookups.CSharp.QualifiedConstantPatternMembers,
+            CSharpQualifiedTypePatternLookup =
+                postSolidityLookups.CSharp.QualifiedTypePatterns,
+            KotlinConstructorTypeNames =
+                postSolidityLookups.Language.KotlinConstructorTypeNames,
+            KotlinInfixFunctionNames =
+                postSolidityLookups.Language.KotlinInfixFunctionNames,
+            CallableDefinitionNames =
+                postSolidityLookups.CSharp.CallableDefinitionNames,
+            StylusVariableDefinitionNames =
+                postSolidityLookups.Language.StylusVariableDefinitionNames,
+            DockerfileStageNames =
+                postSolidityLookups.Language.DockerfileStageNames,
+            DockerfileVariableNames =
+                postSolidityLookups.Language.DockerfileVariableNames,
+            ShellCallableNames =
+                postSolidityLookups.Language.ShellCallableNames,
+            ShellGlobalAliasNames =
+                postSolidityLookups.Language.ShellGlobalAliasNames,
+            DynamicDeclarativeState =
+                postSolidityLookups.DynamicDeclarativeState,
+            CSharpUsingAliases = postSolidityLookups.CSharp.UsingAliases,
+            CSharpUsingStatics = postSolidityLookups.CSharp.UsingStatics,
+            Lookups = postSolidityLookups.Extraction,
+            TypeScriptTypeAliases =
+                preSolidityLookups.TypeScriptTypeAliases,
+            SwiftTypeAliases = preSolidityLookups.SwiftTypeAliases,
+            References = references,
+            Seen = seen,
+        };
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Execution.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Execution.cs
new file mode 100644
index 000000000..7a303ba54
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Execution.cs
@@ -0,0 +1,51 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static List<ReferenceRecord> ExtractCoreSolidityReferences(
+        CoreExtractionPreparation preparation,
+        CorePreSolidityLookups preSolidityLookups)
+        => ExtractSolidityReferences(
+            preparation.Request.FileId,
+            preparation.Lines.Lines,
+            preparation.Lines.PreparedLines,
+            preSolidityLookups.Containers.Resolver);
+
+    private static void EmitCoreExtractionPrelude(
+        CoreReferenceLoopContext loop)
+    {
+        var request = loop.Request;
+        if (request.Language == "csharp")
+        {
+            EmitCSharpAsyncIteratorReferences(
+                request.FileId,
+                loop.Preparation.Lines,
+                loop.Preparation.StructuralLines,
+                request.Symbols,
+                loop.References,
+                loop.Seen);
+            EmitCSharpStaticInterfaceMemberImplementationReferences(
+                request.FileId,
+                loop.Preparation.Lines,
+                loop.Preparation.StructuralLines,
+                request.Symbols,
+                request.WorkspaceSymbols ?? request.Symbols,
+                request.CSharpStaticInterfaceMemberLookups,
+                loop.References,
+                loop.Seen);
+        }
+        else if (request.Language == "rust")
+        {
+            RustReferenceExtractor.EmitMultilineAttributeReferences(
+                loop.Preparation.PreparedLines,
+                loop.References,
+                loop.Seen,
+                request.FileId,
+                (lineNumber, _) => FindInnermostContainer(
+                    loop.ContainerCandidates,
+                    lineNumber));
+        }
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Finalization.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Finalization.cs
new file mode 100644
index 000000000..aeb3fce56
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Finalization.cs
@@ -0,0 +1,131 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private static List<ReferenceRecord> FinalizeCoreExtraction(
+        CoreReferenceLoopContext loop,
+        CSharpMultiLineTypePatternState pendingCSharpMultiLineTypePattern)
+    {
+        var request = loop.Request;
+        var references = loop.References;
+        if (!ReferenceLimitReached(references)
+            && request.Language == "csharp")
+        {
+            CSharpReferenceExtractor.EmitSwitchExpressionTypePatternReferences(
+                loop.Preparation.Lines,
+                loop.Preparation.PreparedLines,
+                loop.ContainerCandidates,
+                loop.CSharpQualifiedConstantPatternMemberLookup,
+                loop.CSharpQualifiedTypePatternLookup,
+                loop.CSharpUsingAliases,
+                loop.CSharpUsingStatics,
+                loop.Lookups.HasActiveSameFileCSharpTypeCandidate,
+                references,
+                loop.Seen,
+                request.FileId);
+
+            CSharpReferenceExtractor
+                .FlushPendingMultiLineTypePatternReference(
+                    ref pendingCSharpMultiLineTypePattern,
+                    loop.CSharpQualifiedConstantPatternMemberLookup,
+                    loop.CSharpUsingAliases,
+                    loop.CSharpUsingStatics,
+                    loop.Lookups.HasActiveSameFileCSharpTypeCandidate,
+                    references,
+                    loop.Seen,
+                    request.FileId);
+        }
+
+        if (request.Language == "csharp")
+        {
+            RewriteCSharpPropertyReceiverReferences(
+                loop.Preparation.PreparedLines,
+                references,
+                loop.Lookups);
+            RemoveCSharpCallsDuplicatedByMemberReads(references);
+        }
+
+        loop.Lookups.ApplyCSharpUsingAliasReferenceNames(references);
+        if (!ReferenceLimitReached(references))
+        {
+            loop.Lookups.EmitCSharpBclRegexWithoutTimeoutReferences(
+                references,
+                loop.Seen);
+        }
+        MarkMutualRecursionReferences(references);
+        return references;
+    }
+
+    private static void RemoveCSharpCallsDuplicatedByMemberReads(
+        List<ReferenceRecord> references)
+    {
+        var memberReadSites = references
+            .Where(reference => reference.ReferenceKind == "member_read")
+            .Select(reference => (
+                reference.FileId,
+                reference.Line,
+                reference.Column,
+                reference.SymbolName,
+                reference.ContainerKind,
+                reference.ContainerName))
+            .ToHashSet();
+        if (memberReadSites.Count == 0)
+            return;
+
+        references.RemoveAll(reference =>
+            reference.ReferenceKind == "call"
+            && memberReadSites.Contains((
+                reference.FileId,
+                reference.Line,
+                reference.Column,
+                reference.SymbolName,
+                reference.ContainerKind,
+                reference.ContainerName)));
+    }
+
+    private static void RewriteCSharpPropertyReceiverReferences(
+        IReadOnlyList<string> preparedLines,
+        List<ReferenceRecord> references,
+        CoreExtractionLookups lookups)
+    {
+        foreach (var reference in references)
+        {
+            if (reference.ReferenceKind != "type_reference"
+                || reference.Line <= 0
+                || reference.Line > preparedLines.Count
+                || reference.Column <= 0)
+            {
+                continue;
+            }
+
+            var line = preparedLines[reference.Line - 1];
+            var tokenEnd =
+                reference.Column - 1 + reference.SymbolName.Length;
+            if (tokenEnd >= line.Length
+                || !line.AsSpan(tokenEnd)
+                    .TrimStart()
+                    .StartsWith(".", StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            var owner = lookups.FindCSharpContainerCandidate(
+                reference.ContainerName,
+                reference.Line);
+            var containingType = GetContainingTypeQualifiedName(owner);
+            if (containingType == null
+                || !lookups.HasCSharpFieldOrPropertyMember(
+                    containingType,
+                    reference.SymbolName))
+            {
+                continue;
+            }
+
+            reference.SymbolName =
+                $"{containingType}.{reference.SymbolName}";
+            reference.ReferenceKind = "reference";
+        }
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Lookups.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Lookups.cs
new file mode 100644
index 000000000..cb46af681
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Lookups.cs
@@ -0,0 +1,298 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private readonly record struct CoreCSharpAttributeLookups(
+        List<(int start, int end)>?[]? Ranges,
+        List<(int start, int end)>?[]? TopLevelRanges);
+
+    private readonly record struct CoreDefinitionLookups(
+        StringComparer Comparer,
+        IReadOnlyDictionary<int, HashSet<string>> NamesByLine,
+        IReadOnlyDictionary<int, Dictionary<string, HashSet<int>>>? ScientificNameIndicesByLine,
+        IReadOnlySet<string>? AllNames,
+        IReadOnlySet<string>? FileNames);
+
+    private readonly record struct CoreSqlLookups(
+        Dictionary<int, List<SqlReferenceExtractor.DefinitionLeafSpan>>? DefinitionLeafSpansByLine,
+        HashSet<(int LineNumber, int ColumnIndex)>? WindowFunctionCallSiteSuppressions);
+
+    private readonly record struct CoreContainerLookups(
+        IReadOnlyList<SymbolRecord> Candidates,
+        InnermostContainerResolver Resolver);
+
+    private readonly record struct CorePreSolidityLookups(
+        int ScientificNativeDependencyLimit,
+        IReadOnlyList<TypeScriptReferenceExtractor.TypeAliasBinding>? TypeScriptTypeAliases,
+        IReadOnlyList<SwiftReferenceExtractor.TypeAliasBinding>? SwiftTypeAliases,
+        CoreCSharpAttributeLookups CSharpAttributes,
+        CoreDefinitionLookups Definitions,
+        CoreSqlLookups Sql,
+        IReadOnlyList<SymbolRecord>? CobolCallableSymbols,
+        CoreContainerLookups Containers);
+
+    private readonly record struct CoreCSharpPatternLookups(
+        IReadOnlySet<string> KnownTypeNames,
+        IReadOnlyDictionary<string, List<(string EnumName, string? QualifiedEnumName, bool AllowShortNameFallback)>> QualifiedEnumMembers,
+        IReadOnlyDictionary<string, List<(string ContainerName, string? QualifiedContainerName, bool AllowShortNameFallback)>> QualifiedConstantPatternMembers,
+        IReadOnlyDictionary<string, List<(string ContainerName, string? QualifiedContainerName, bool AllowShortNameFallback)>> QualifiedTypePatterns);
+
+    private readonly record struct CoreCSharpLoopLookups(
+        IReadOnlySet<string> KnownTypeNames,
+        IReadOnlyDictionary<string, List<(string EnumName, string? QualifiedEnumName, bool AllowShortNameFallback)>> QualifiedEnumMembers,
+        IReadOnlyDictionary<string, List<(string ContainerName, string? QualifiedContainerName, bool AllowShortNameFallback)>> QualifiedConstantPatternMembers,
+        IReadOnlyDictionary<string, List<(string ContainerName, string? QualifiedContainerName, bool AllowShortNameFallback)>> QualifiedTypePatterns,
+        IReadOnlyList<CSharpUsingAliasRecord> UsingAliases,
+        IReadOnlyList<CSharpUsingNamespaceRecord> UsingNamespaces,
+        IReadOnlyList<CSharpUsingStaticRecord> UsingStatics,
+        HashSet<string>? CallableDefinitionNames);
+
+    private readonly record struct CoreLanguageLoopLookups(
+        IReadOnlyDictionary<int, SymbolRecord[]>? SwiftPropertyDefinitionsByLine,
+        HashSet<string>? KotlinConstructorTypeNames,
+        HashSet<string>? KotlinInfixFunctionNames,
+        HashSet<string>? StylusVariableDefinitionNames,
+        HashSet<string>? DockerfileStageNames,
+        HashSet<string>? DockerfileVariableNames,
+        HashSet<string>? ShellCallableNames,
+        HashSet<string>? ShellGlobalAliasNames);
+
+    private readonly record struct CorePostSolidityLookups(
+        CoreCSharpLoopLookups CSharp,
+        CoreLanguageLoopLookups Language,
+        DynamicDeclarativeReferenceExtractor.ExtractionState? DynamicDeclarativeState,
+        CoreExtractionLookups Extraction);
+
+    private static CorePreSolidityLookups BuildCorePreSolidityLookups(
+        CoreExtractionPreparation preparation)
+    {
+        var request = preparation.Request;
+        var language = request.Language;
+        var lines = preparation.Lines.Lines;
+        var structuralLines = preparation.Lines.StructuralLines;
+        var preparedLines = preparation.Lines.PreparedLines;
+        var scientificNativeDependencyLimit =
+            ScientificNativeReferenceExtractor.Supports(language)
+                ? GetSafetyLimits().MaxNamesPerLine
+                : 0;
+        var typeScriptTypeAliases = language == "typescript"
+            ? TypeScriptReferenceExtractor.BuildTypeAliasTargets(preparedLines)
+            : null;
+        var swiftTypeAliases = language == "swift"
+            ? SwiftReferenceExtractor.BuildTypeAliasTargets(preparedLines)
+            : null;
+
+        var csharpAttributeTables = language == "csharp"
+            && preparation.Lines.Content.Contains('[', StringComparison.Ordinal)
+                ? BuildCSharpAttributeRanges(preparedLines)
+                : (null, null);
+        var definitionNamesComparer = GetDefinitionNamesComparer(language);
+        var definitionNamesByLine = BuildDefinitionNamesByLine(
+            language,
+            request.Symbols,
+            request.ReportDiagnostic);
+        var scientificDefinitionNameIndicesByLine =
+            BuildScientificDefinitionNameIndicesByLine(
+                language,
+                lines,
+                request.Symbols,
+                definitionNamesByLine);
+        var allDefinitionNames = language == "stylus"
+            ? BuildAllDefinitionNames(
+                language,
+                request.Symbols,
+                request.ReportDiagnostic)
+            : null;
+        var fileDefinitionNames = preparation.IsRazorFile
+            ? BuildFileDefinitionNames(request.Symbols)
+            : null;
+        var sqlDefinitionLeafSpansByLine = language == "sql"
+            ? SqlReferenceExtractor.BuildDefinitionLeafSpansByLine(
+                lines,
+                request.Symbols)
+            : null;
+        var sqlWindowFunctionCallSiteSuppressions = language == "sql"
+            ? SqlReferenceExtractor
+                .BuildWindowFunctionCallSiteSuppressions(structuralLines)
+            : null;
+        var cobolCallableSymbols = language == "cobol"
+            ? BuildCobolCallableSymbols(request.Symbols)
+            : null;
+        var containerCandidates = BuildReferenceContainerCandidates(
+            language,
+            request.Symbols,
+            request.ReportDiagnostic);
+        var containerResolver = new InnermostContainerResolver(
+            containerCandidates,
+            preferCallable: language == "csharp");
+
+        return new CorePreSolidityLookups(
+            scientificNativeDependencyLimit,
+            typeScriptTypeAliases,
+            swiftTypeAliases,
+            new CoreCSharpAttributeLookups(
+                csharpAttributeTables.Item1,
+                csharpAttributeTables.Item2),
+            new CoreDefinitionLookups(
+                definitionNamesComparer,
+                definitionNamesByLine,
+                scientificDefinitionNameIndicesByLine,
+                allDefinitionNames,
+                fileDefinitionNames),
+            new CoreSqlLookups(
+                sqlDefinitionLeafSpansByLine,
+                sqlWindowFunctionCallSiteSuppressions),
+            cobolCallableSymbols,
+            new CoreContainerLookups(
+                containerCandidates,
+                containerResolver));
+    }
+
+    private static CoreCSharpPatternLookups BuildCoreCSharpPatternLookups(
+        CoreExtractionPreparation preparation)
+    {
+        var request = preparation.Request;
+        if (request.Language != "csharp")
+        {
+            return new CoreCSharpPatternLookups(
+                EmptyCSharpStringSet,
+                EmptyCSharpQualifiedEnumMemberLookup,
+                EmptyCSharpQualifiedPatternLookup,
+                EmptyCSharpQualifiedPatternLookup);
+        }
+
+        var typeNameSets = BuildCSharpTypeNameSets(
+            request.Language,
+            request.Symbols);
+        var localQualifiedPatternLookups =
+            BuildCSharpQualifiedPatternLookups(
+                request.Symbols,
+                typeNameSets.NonEnumTypeNames);
+        var workspaceQualifiedPatternLookups =
+            request.CSharpQualifiedPatternLookups
+            ?? (request.WorkspaceSymbols is { Count: > 0 }
+                ? BuildCSharpQualifiedPatternLookups(request.WorkspaceSymbols)
+                : localQualifiedPatternLookups);
+        var qualifiedPatternLookups = new CSharpQualifiedPatternLookups(
+            workspaceQualifiedPatternLookups.EnumMemberLookup,
+            workspaceQualifiedPatternLookups.ConstantPatternMemberLookup,
+            localQualifiedPatternLookups.TypePatternLookup);
+        return new CoreCSharpPatternLookups(
+            typeNameSets.KnownTypeNames,
+            qualifiedPatternLookups.EnumMemberLookup,
+            qualifiedPatternLookups.ConstantPatternMemberLookup,
+            qualifiedPatternLookups.TypePatternLookup);
+    }
+
+    private static CorePostSolidityLookups BuildCorePostSolidityLookups(
+        CoreExtractionPreparation preparation,
+        CorePreSolidityLookups preSolidityLookups)
+    {
+        var request = preparation.Request;
+        var language = request.Language;
+        var lines = preparation.Lines.Lines;
+        var structuralLines = preparation.Lines.StructuralLines;
+        var referenceStructuralLines =
+            preparation.Lines.ReferenceStructuralLines;
+        var preparedLines = preparation.Lines.PreparedLines;
+
+        var swiftPropertyDefinitionsByLine = language == "swift"
+            ? BuildSwiftPropertyDefinitionsByLine(
+                language,
+                request.Symbols,
+                request.ReportDiagnostic)
+            : null;
+        var csharpPatterns = BuildCoreCSharpPatternLookups(preparation);
+
+        HashSet<string>? kotlinConstructorTypeNames = null;
+        HashSet<string>? kotlinInfixFunctionNames = null;
+        if (language == "kotlin")
+        {
+            var kotlinNameSets = KotlinReferenceExtractor.BuildNameSets(
+                language,
+                request.Symbols);
+            kotlinConstructorTypeNames = kotlinNameSets.ConstructorTypeNames;
+            kotlinInfixFunctionNames = kotlinNameSets.InfixFunctionNames;
+            KotlinReferenceExtractor.AddDeclaredInfixFunctionNames(
+                lines,
+                kotlinInfixFunctionNames);
+        }
+
+        var callableDefinitionNames = language == "csharp"
+            ? BuildCallableDefinitionNames(language, request.Symbols)
+            : null;
+        var stylusVariableDefinitionNames = language == "stylus"
+            ? CssReferenceExtractor.BuildStylusVariableDefinitionNames(lines)
+            : null;
+        var dockerfileNameSets = language == "dockerfile"
+            ? DockerfileReferenceExtractor.BuildNameSets(
+                language,
+                request.Symbols)
+            : default;
+        var shellNameSets = language == "shell"
+            ? ShellReferenceExtractor.BuildNameSets(
+                language,
+                request.Symbols)
+            : default;
+        var dynamicDeclarativeState =
+            DynamicDeclarativeReferenceExtractor.CreateState(
+                language,
+                preparedLines,
+                referenceStructuralLines,
+                request.Symbols);
+        IReadOnlyList<(int StartLine, int EndLine)> csharpNamespaceScopes =
+            language == "csharp"
+                ? BuildCSharpNamespaceScopes(request.Symbols)
+                : Array.Empty<(int StartLine, int EndLine)>();
+        var csharpUsingImports = language == "csharp"
+            ? BuildCSharpUsingImports(
+                language,
+                request.Symbols,
+                csharpPatterns.KnownTypeNames,
+                csharpNamespaceScopes,
+                lines,
+                structuralLines)
+            : (
+                Aliases: Array.Empty<CSharpUsingAliasRecord>(),
+                Namespaces: Array.Empty<CSharpUsingNamespaceRecord>(),
+                Statics: Array.Empty<CSharpUsingStaticRecord>());
+        var csharpLookups = new CoreCSharpLoopLookups(
+            csharpPatterns.KnownTypeNames,
+            csharpPatterns.QualifiedEnumMembers,
+            csharpPatterns.QualifiedConstantPatternMembers,
+            csharpPatterns.QualifiedTypePatterns,
+            csharpUsingImports.Aliases,
+            csharpUsingImports.Namespaces,
+            csharpUsingImports.Statics,
+            callableDefinitionNames);
+        var languageLookups = new CoreLanguageLoopLookups(
+            swiftPropertyDefinitionsByLine,
+            kotlinConstructorTypeNames,
+            kotlinInfixFunctionNames,
+            stylusVariableDefinitionNames,
+            dockerfileNameSets.StageNames,
+            dockerfileNameSets.VariableNames,
+            shellNameSets.CallableNames,
+            shellNameSets.GlobalAliasNames);
+        var extractionLookups = new CoreExtractionLookups(
+            request,
+            language,
+            request.Symbols,
+            preSolidityLookups.Containers.Candidates,
+            preparation.Lines.CSharpLinesInsideMultilineStringContent,
+            preparedLines,
+            structuralLines,
+            lines,
+            csharpLookups.KnownTypeNames,
+            csharpLookups.UsingAliases,
+            csharpLookups.UsingNamespaces);
+
+        return new CorePostSolidityLookups(
+            csharpLookups,
+            languageLookups,
+            dynamicDeclarativeState,
+            extractionLookups);
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Preparation.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Preparation.cs
new file mode 100644
index 000000000..93cfb3608
--- /dev/null
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.Preparation.cs
@@ -0,0 +1,87 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Indexer;
+
+public static partial class ReferenceExtractor
+{
+    private readonly record struct CoreExtractionPreparation(
+        ReferenceExtractionContext Request,
+        ReferenceLinePreparation Lines,
+        bool IsJsxFile,
+        bool IsRazorFile,
+        bool XamlReferenceEnabled);
+
+    private readonly record struct CoreExtractionPreparationOutcome(
+        bool IsComplete,
+        List<ReferenceRecord>? References,
+        CoreExtractionPreparation? Preparation)
+    {
+        internal static CoreExtractionPreparationOutcome Complete(
+            List<ReferenceRecord> references)
+            => new(true, references, null);
+
+        internal static CoreExtractionPreparationOutcome Continue(
+            CoreExtractionPreparation preparation)
+            => new(false, null, preparation);
+    }
+
+    private static CoreExtractionPreparationOutcome PrepareCoreExtraction(
+        ReferenceExtractionContext request)
+    {
+        request.CancellationToken.ThrowIfCancellationRequested();
+        var language = request.Language;
+        var isJsxFile = IsJsxFilePath(request.Path);
+        var isRazorFile = IsRazorFilePath(request.Path)
+            || request.RequestedLanguage is "razor" or "blazor" or "cshtml";
+
+        if (language == "ambiguous_m")
+            return CoreExtractionPreparationOutcome.Complete(
+                ExtractAmbiguousMReferences(request));
+        if (language is "clojure" or "erlang" or "ocaml" or "raku")
+            return CoreExtractionPreparationOutcome.Complete(
+                ExtractFunctionalLanguageReferences(request));
+
+        if (TryExtractStructuralMetadataReferences(
+                request.FileId,
+                language,
+                request.Content,
+                request.Symbols,
+                request.Path,
+                request.ContentIsNormalized,
+                request.HasOversizeLine,
+                request.ConflictMarkerLine,
+                request.MaxReferenceCount,
+                request.CancellationToken,
+                out var structuralMetadataReferences))
+        {
+            return CoreExtractionPreparationOutcome.Complete(
+                structuralMetadataReferences);
+        }
+
+        if (!TryPrepareReferenceLines(
+                language,
+                request.Content,
+                isRazorFile,
+                request.ContentIsNormalized,
+                request.HasOversizeLine,
+                request.ConflictMarkerLine,
+                out var preparedInput))
+        {
+            return CoreExtractionPreparationOutcome.Complete([]);
+        }
+        request.CancellationToken.ThrowIfCancellationRequested();
+
+        var xamlReferenceEnabled = language == "xml"
+            && XamlReferenceExtractor.IsXaml(preparedInput.Lines);
+        if (language == "xml" && !xamlReferenceEnabled)
+            return CoreExtractionPreparationOutcome.Complete([]);
+
+        return CoreExtractionPreparationOutcome.Continue(
+            new CoreExtractionPreparation(
+                request,
+                preparedInput,
+                isJsxFile,
+                isRazorFile,
+                xamlReferenceEnabled));
+    }
+}
diff --git a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.cs b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.cs
index 7639cf846..53aae9bf8 100644
--- a/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.cs
+++ b/src/CodeIndex/Indexer/References/ReferenceExtractor.CoreExtraction.cs
@@ -7,441 +7,18 @@ public static partial class ReferenceExtractor
     internal static List<ReferenceRecord> ExtractCore(
         ReferenceExtractionContext request)
     {
-        request.CancellationToken.ThrowIfCancellationRequested();
-        var fileId = request.FileId;
-        var language = request.Language;
-        var content = request.Content;
-        var symbols = request.Symbols;
-        var path = request.Path;
-        var workspaceSymbols = request.WorkspaceSymbols;
-        var requestedLanguage = request.RequestedLanguage;
-        var isJsxFile = IsJsxFilePath(path);
-        var isRazorFile = IsRazorFilePath(path)
-            || requestedLanguage is "razor" or "blazor" or "cshtml";
-
-        if (language == "ambiguous_m")
-            return ExtractAmbiguousMReferences(request);
-        if (language is "clojure" or "erlang" or "ocaml" or "raku")
-            return ExtractFunctionalLanguageReferences(request);
-
-        if (TryExtractStructuralMetadataReferences(
-                fileId,
-                language,
-                content,
-                symbols,
-                path,
-                request.ContentIsNormalized,
-                request.HasOversizeLine,
-                request.ConflictMarkerLine,
-                request.MaxReferenceCount,
-                request.CancellationToken,
-                out var structuralMetadataReferences))
-        {
-            return structuralMetadataReferences;
-        }
-
-        if (!TryPrepareReferenceLines(
-                language,
-                content,
-                isRazorFile,
-                request.ContentIsNormalized,
-                request.HasOversizeLine,
-                request.ConflictMarkerLine,
-                out var preparedInput))
-        {
-            return [];
-        }
-        request.CancellationToken.ThrowIfCancellationRequested();
-
-        content = preparedInput.Content;
-        var lines = preparedInput.Lines;
-        var xamlReferenceEnabled = language == "xml"
-            && XamlReferenceExtractor.IsXaml(lines);
-        if (language == "xml" && !xamlReferenceEnabled)
-            return [];
-
-        var structuralLines = preparedInput.StructuralLines;
-        var referenceStructuralLines =
-            preparedInput.ReferenceStructuralLines;
-        var preparedLines = preparedInput.PreparedLines;
-        var scientificNativeDependencyLimit =
-            ScientificNativeReferenceExtractor.Supports(language)
-                ? GetSafetyLimits().MaxNamesPerLine
-                : 0;
-        var typeScriptTypeAliases = language == "typescript"
-            ? TypeScriptReferenceExtractor.BuildTypeAliasTargets(preparedLines)
-            : null;
-        var swiftTypeAliases = language == "swift"
-            ? SwiftReferenceExtractor.BuildTypeAliasTargets(preparedLines)
-            : null;
-
-        var csharpAttrTables = language == "csharp"
-            && content.Contains('[', StringComparison.Ordinal)
-                ? BuildCSharpAttributeRanges(preparedLines)
-                : (null, null);
-        var csharpAttrRanges = csharpAttrTables.Item1;
-        var csharpAttrTopLevelRanges = csharpAttrTables.Item2;
-        var definitionNamesComparer =
-            GetDefinitionNamesComparer(language);
-        var definitionNamesByLine = BuildDefinitionNamesByLine(
-            language,
-            symbols,
-            request.ReportDiagnostic);
-        var scientificDefinitionNameIndicesByLine =
-            BuildScientificDefinitionNameIndicesByLine(
-                language,
-                lines,
-                symbols,
-                definitionNamesByLine);
-        var allDefinitionNames = language == "stylus"
-            ? BuildAllDefinitionNames(
-                language,
-                symbols,
-                request.ReportDiagnostic)
-            : null;
-        var fileDefinitionNames = isRazorFile
-            ? BuildFileDefinitionNames(symbols)
-            : null;
-        var sqlDefinitionLeafSpansByLine = language == "sql"
-            ? SqlReferenceExtractor.BuildDefinitionLeafSpansByLine(
-                lines,
-                symbols)
-            : null;
-        var sqlWindowFunctionCallSiteSuppressions = language == "sql"
-            ? SqlReferenceExtractor
-                .BuildWindowFunctionCallSiteSuppressions(structuralLines)
-            : null;
-        var cobolCallableSymbols = language == "cobol"
-            ? BuildCobolCallableSymbols(symbols)
-            : null;
-        var containerCandidates = BuildReferenceContainerCandidates(
-            language,
-            symbols,
-            request.ReportDiagnostic);
-        var containerResolver =
-            new InnermostContainerResolver(
-                containerCandidates,
-                preferCallable: language == "csharp");
-        if (language == "solidity")
-        {
-            return ExtractSolidityReferences(
-                fileId,
-                lines,
-                preparedLines,
-                containerResolver);
-        }
-
-        var swiftPropertyDefinitionsByLine = language == "swift"
-            ? BuildSwiftPropertyDefinitionsByLine(
-                language,
-                symbols,
-                request.ReportDiagnostic)
-            : null;
-        var csharpTypeNameSets = language == "csharp"
-            ? BuildCSharpTypeNameSets(language, symbols)
-            : (
-                KnownTypeNames: EmptyCSharpStringSet,
-                NonEnumTypeNames: EmptyCSharpStringSet);
-        var csharpKnownTypeNames = csharpTypeNameSets.KnownTypeNames;
-        var localCSharpQualifiedPatternLookups = language == "csharp"
-            ? BuildCSharpQualifiedPatternLookups(
-                symbols,
-                csharpTypeNameSets.NonEnumTypeNames)
-            : null;
-        var workspaceCSharpQualifiedPatternLookups = language == "csharp"
-            ? request.CSharpQualifiedPatternLookups
-                ?? (workspaceSymbols is { Count: > 0 }
-                    ? BuildCSharpQualifiedPatternLookups(workspaceSymbols)
-                    : localCSharpQualifiedPatternLookups)
-            : null;
-        var csharpQualifiedPatternLookups = language == "csharp"
-            ? new CSharpQualifiedPatternLookups(
-                workspaceCSharpQualifiedPatternLookups!.EnumMemberLookup,
-                workspaceCSharpQualifiedPatternLookups.ConstantPatternMemberLookup,
-                localCSharpQualifiedPatternLookups!.TypePatternLookup)
-            : new CSharpQualifiedPatternLookups(
-                EmptyCSharpQualifiedEnumMemberLookup,
-                EmptyCSharpQualifiedPatternLookup,
-                EmptyCSharpQualifiedPatternLookup);
-        var csharpQualifiedEnumMemberLookup =
-            csharpQualifiedPatternLookups.EnumMemberLookup;
-        var csharpQualifiedConstantPatternMemberLookup =
-            csharpQualifiedPatternLookups.ConstantPatternMemberLookup;
-        var csharpQualifiedTypePatternLookup =
-            csharpQualifiedPatternLookups.TypePatternLookup;
-
-        HashSet<string>? kotlinConstructorTypeNames = null;
-        HashSet<string>? kotlinInfixFunctionNames = null;
-        if (language == "kotlin")
-        {
-            var kotlinNameSets =
-                KotlinReferenceExtractor.BuildNameSets(language, symbols);
-            kotlinConstructorTypeNames =
-                kotlinNameSets.ConstructorTypeNames;
-            kotlinInfixFunctionNames = kotlinNameSets.InfixFunctionNames;
-            KotlinReferenceExtractor.AddDeclaredInfixFunctionNames(
-                lines,
-                kotlinInfixFunctionNames);
-        }
-
-        var callableDefinitionNames = language == "csharp"
-            ? BuildCallableDefinitionNames(language, symbols)
-            : null;
-        var stylusVariableDefinitionNames = language == "stylus"
-            ? CssReferenceExtractor.BuildStylusVariableDefinitionNames(lines)
-            : null;
-        var dockerfileNameSets = language == "dockerfile"
-            ? DockerfileReferenceExtractor.BuildNameSets(language, symbols)
-            : default;
-        var shellNameSets = language == "shell"
-            ? ShellReferenceExtractor.BuildNameSets(language, symbols)
-            : default;
-        var dynamicDeclarativeState =
-            DynamicDeclarativeReferenceExtractor.CreateState(
-                language,
-                preparedLines,
-                referenceStructuralLines,
-                symbols);
-        IReadOnlyList<(int StartLine, int EndLine)> csharpNamespaceScopes =
-            language == "csharp"
-                ? BuildCSharpNamespaceScopes(symbols)
-                : Array.Empty<(int StartLine, int EndLine)>();
-        var csharpUsingImports = language == "csharp"
-            ? BuildCSharpUsingImports(
-                language,
-                symbols,
-                csharpKnownTypeNames,
-                csharpNamespaceScopes,
-                lines,
-                structuralLines)
-            : (
-                Aliases: Array.Empty<CSharpUsingAliasRecord>(),
-                Namespaces: Array.Empty<CSharpUsingNamespaceRecord>(),
-                Statics: Array.Empty<CSharpUsingStaticRecord>());
-        var csharpUsingAliases = csharpUsingImports.Aliases;
-        var csharpUsingStatics = csharpUsingImports.Statics;
-        var lookups = new CoreExtractionLookups(
-            request,
-            language,
-            symbols,
-            containerCandidates,
-            preparedInput.CSharpLinesInsideMultilineStringContent,
-            preparedLines,
-            structuralLines,
-            lines,
-            csharpKnownTypeNames,
-            csharpUsingAliases,
-            csharpUsingImports.Namespaces);
-
-        var references = CreateReferenceList(
-            request.MaxReferenceCount,
-            EstimateReferenceListInitialCapacity(lines.Length));
-        var seen = CreateReferenceSeenSet(lines.Length);
-        if (language == "csharp")
-        {
-            EmitCSharpAsyncIteratorReferences(
-                fileId,
-                lines,
-                structuralLines,
-                symbols,
-                references,
-                seen);
-            EmitCSharpStaticInterfaceMemberImplementationReferences(
-                fileId,
-                lines,
-                structuralLines,
-                symbols,
-                workspaceSymbols ?? symbols,
-                request.CSharpStaticInterfaceMemberLookups,
-                references,
-                seen);
-        }
-        else if (language == "rust")
-        {
-            RustReferenceExtractor.EmitMultilineAttributeReferences(
-                preparedLines,
-                references,
-                seen,
-                fileId,
-                (lineNumber, _) =>
-                    FindInnermostContainer(
-                        containerCandidates,
-                        lineNumber));
-        }
-
-        var pendingCSharpMultiLineTypePattern =
-            EmitCoreReferenceLines(
-                new CoreReferenceLoopContext
-                {
-                    Request = request,
-                    Preparation = preparedInput,
-                    IsJsxFile = isJsxFile,
-                    IsRazorFile = isRazorFile,
-                    XamlReferenceEnabled = xamlReferenceEnabled,
-                    ScientificNativeDependencyLimit =
-                        scientificNativeDependencyLimit,
-                    CSharpAttributeRanges = csharpAttrRanges,
-                    CSharpAttributeTopLevelRanges =
-                        csharpAttrTopLevelRanges,
-                    DefinitionNamesComparer = definitionNamesComparer,
-                    DefinitionNamesByLine = definitionNamesByLine,
-                    ScientificDefinitionNameIndicesByLine =
-                        scientificDefinitionNameIndicesByLine,
-                    AllDefinitionNames = allDefinitionNames,
-                    FileDefinitionNames = fileDefinitionNames,
-                    SqlDefinitionLeafSpansByLine =
-                        sqlDefinitionLeafSpansByLine,
-                    SqlWindowFunctionCallSiteSuppressions =
-                        sqlWindowFunctionCallSiteSuppressions,
-                    CobolCallableSymbols = cobolCallableSymbols,
-                    ContainerCandidates = containerCandidates,
-                    ContainerResolver = containerResolver,
-                    SwiftPropertyDefinitionsByLine =
-                        swiftPropertyDefinitionsByLine,
-                    CSharpQualifiedEnumMemberLookup =
-                        csharpQualifiedEnumMemberLookup,
-                    CSharpQualifiedConstantPatternMemberLookup =
-                        csharpQualifiedConstantPatternMemberLookup,
-                    CSharpQualifiedTypePatternLookup =
-                        csharpQualifiedTypePatternLookup,
-                    KotlinConstructorTypeNames =
-                        kotlinConstructorTypeNames,
-                    KotlinInfixFunctionNames = kotlinInfixFunctionNames,
-                    CallableDefinitionNames = callableDefinitionNames,
-                    StylusVariableDefinitionNames =
-                        stylusVariableDefinitionNames,
-                    DockerfileStageNames =
-                        dockerfileNameSets.StageNames,
-                    DockerfileVariableNames =
-                        dockerfileNameSets.VariableNames,
-                    ShellCallableNames = shellNameSets.CallableNames,
-                    ShellGlobalAliasNames =
-                        shellNameSets.GlobalAliasNames,
-                    DynamicDeclarativeState = dynamicDeclarativeState,
-                    CSharpUsingAliases = csharpUsingAliases,
-                    CSharpUsingStatics = csharpUsingStatics,
-                    Lookups = lookups,
-                    TypeScriptTypeAliases = typeScriptTypeAliases,
-                    SwiftTypeAliases = swiftTypeAliases,
-                    References = references,
-                    Seen = seen,
-                });
-
-        if (!ReferenceLimitReached(references) && language == "csharp")
-        {
-            CSharpReferenceExtractor.EmitSwitchExpressionTypePatternReferences(
-                lines,
-                preparedLines,
-                containerCandidates,
-                csharpQualifiedConstantPatternMemberLookup,
-                csharpQualifiedTypePatternLookup,
-                csharpUsingAliases,
-                csharpUsingStatics,
-                lookups.HasActiveSameFileCSharpTypeCandidate,
-                references,
-                seen,
-                fileId);
-
-            CSharpReferenceExtractor
-                .FlushPendingMultiLineTypePatternReference(
-                    ref pendingCSharpMultiLineTypePattern,
-                    csharpQualifiedConstantPatternMemberLookup,
-                    csharpUsingAliases,
-                    csharpUsingStatics,
-                    lookups.HasActiveSameFileCSharpTypeCandidate,
-                    references,
-                    seen,
-                    fileId);
-        }
-
-        if (language == "csharp")
-        {
-            RewriteCSharpPropertyReceiverReferences(
-                preparedLines,
-                references,
-                lookups);
-            RemoveCSharpCallsDuplicatedByMemberReads(references);
-        }
-
-        lookups.ApplyCSharpUsingAliasReferenceNames(references);
-        if (!ReferenceLimitReached(references))
-        {
-            lookups.EmitCSharpBclRegexWithoutTimeoutReferences(
-                references,
-                seen);
-        }
-        MarkMutualRecursionReferences(references);
-        return references;
-    }
-
-    private static void RemoveCSharpCallsDuplicatedByMemberReads(
-        List<ReferenceRecord> references)
-    {
-        var memberReadSites = references
-            .Where(reference => reference.ReferenceKind == "member_read")
-            .Select(reference => (
-                reference.FileId,
-                reference.Line,
-                reference.Column,
-                reference.SymbolName,
-                reference.ContainerKind,
-                reference.ContainerName))
-            .ToHashSet();
-        if (memberReadSites.Count == 0)
-            return;
-
-        references.RemoveAll(reference =>
-            reference.ReferenceKind == "call"
-            && memberReadSites.Contains((
-                reference.FileId,
-                reference.Line,
-                reference.Column,
-                reference.SymbolName,
-                reference.ContainerKind,
-                reference.ContainerName)));
-    }
-
-    private static void RewriteCSharpPropertyReceiverReferences(
-        IReadOnlyList<string> preparedLines,
-        List<ReferenceRecord> references,
-        CoreExtractionLookups lookups)
-    {
-        foreach (var reference in references)
-        {
-            if (reference.ReferenceKind != "type_reference"
-                || reference.Line <= 0
-                || reference.Line > preparedLines.Count
-                || reference.Column <= 0)
-            {
-                continue;
-            }
-
-            var line = preparedLines[reference.Line - 1];
-            var tokenEnd =
-                reference.Column - 1 + reference.SymbolName.Length;
-            if (tokenEnd >= line.Length
-                || !line.AsSpan(tokenEnd)
-                    .TrimStart()
-                    .StartsWith(".", StringComparison.Ordinal))
-            {
-                continue;
-            }
-
-            var owner = lookups.FindCSharpContainerCandidate(
-                reference.ContainerName,
-                reference.Line);
-            var containingType = GetContainingTypeQualifiedName(owner);
-            if (containingType == null
-                || !lookups.HasCSharpFieldOrPropertyMember(
-                    containingType,
-                    reference.SymbolName))
-            {
-                continue;
-            }
-
-            reference.SymbolName =
-                $"{containingType}.{reference.SymbolName}";
-            reference.ReferenceKind = "reference";
-        }
+        var preparationOutcome = PrepareCoreExtraction(request);
+        if (preparationOutcome.IsComplete)
+            return preparationOutcome.References!;
+
+        var preparation = preparationOutcome.Preparation!.Value;
+        var preSolidityLookups = BuildCorePreSolidityLookups(preparation);
+        if (request.Language == "solidity")
+            return ExtractCoreSolidityReferences(preparation, preSolidityLookups);
+
+        var loop = CreateCoreReferenceLoopContext(preparation, preSolidityLookups);
+        EmitCoreExtractionPrelude(loop);
+        var pendingCSharpMultiLineTypePattern = EmitCoreReferenceLines(loop);
+        return FinalizeCoreExtraction(loop, pendingCSharpMultiLineTypePattern);
     }
 }
diff --git a/tests/CodeIndex.Tests/ReferenceExtractorSolidityTests.cs b/tests/CodeIndex.Tests/ReferenceExtractorSolidityTests.cs
index 422e88205..55922a209 100644
--- a/tests/CodeIndex.Tests/ReferenceExtractorSolidityTests.cs
+++ b/tests/CodeIndex.Tests/ReferenceExtractorSolidityTests.cs
@@ -1,4 +1,5 @@
 using CodeIndex.Indexer;
+using CodeIndex.Models;
 
 namespace CodeIndex.Tests;
 
@@ -41,4 +42,44 @@ interface Child	is	Parent {}
         Assert.Contains(references, reference => reference.SymbolName == "Parent" && reference.ReferenceKind == "extends");
         Assert.DoesNotContain(references, reference => reference.SymbolName is "Phantom" or "CommentOnly");
     }
+
+    [Fact]
+    public void ExtractDetailed_SolidityEarlyReturnPreservesSafetyDiagnostics()
+    {
+        const string content = """
+            contract Vault is Ownable {
+                function run() external onlyOwner {}
+            }
+            """;
+        var previousLimits = ReferenceExtractor.SafetyLimitsForTesting;
+        try
+        {
+            ReferenceExtractor.SafetyLimitsForTesting = new ReferenceExtractionSafetyLimits
+            {
+                MaxLookupSymbols = 1,
+                MaxLookupLines = 100,
+                MaxNamesPerLine = 100,
+                MaxContainerCandidates = 1,
+            };
+            var symbols = SymbolExtractor.Extract(1, "solidity", content);
+
+            var result = ReferenceExtractor.ExtractDetailed(
+                1,
+                "solidity",
+                content,
+                symbols);
+
+            Assert.Contains(result.References, reference =>
+                reference.SymbolName == "Ownable"
+                && reference.ReferenceKind == "extends");
+            Assert.Contains(result.Diagnostics, diagnostic =>
+                diagnostic.Kind == "reference_definition_lookup_symbol_budget_exceeded");
+            Assert.Contains(result.Diagnostics, diagnostic =>
+                diagnostic.Kind == "reference_container_candidate_budget_exceeded");
+        }
+        finally
+        {
+            ReferenceExtractor.SafetyLimitsForTesting = previousLimits;
+        }
+    }
 }
diff --git a/tests/CodeIndex.Tests/ReferenceExtractorTests.cs b/tests/CodeIndex.Tests/ReferenceExtractorTests.cs
index d386fcafd..84e17189f 100644
--- a/tests/CodeIndex.Tests/ReferenceExtractorTests.cs
+++ b/tests/CodeIndex.Tests/ReferenceExtractorTests.cs
@@ -4546,6 +4546,45 @@ def beta():
             && !reference.IsMutualRecursion);
     }
 
+    [Fact]
+    public void Extract_PythonReferenceLimitStillRunsMutualRecursionFinalization()
+    {
+        const string content = """
+            def alpha():
+                beta()
+
+            def beta():
+                alpha()
+
+            def gamma():
+                alpha()
+            """;
+
+        var symbols = SymbolExtractor.Extract(1, "python", content);
+        var references = ReferenceExtractor.Extract(
+            1,
+            "python",
+            content,
+            symbols,
+            maxReferenceCount: 2);
+
+        Assert.Equal(2, references.Count);
+        Assert.Contains(references, reference =>
+            reference.ContainerName == "alpha"
+            && reference.SymbolName == "beta"
+            && reference.ReferenceKind == "call"
+            && reference.IsMutualRecursion
+            && !reference.IsSelfReference);
+        Assert.Contains(references, reference =>
+            reference.ContainerName == "beta"
+            && reference.SymbolName == "alpha"
+            && reference.ReferenceKind == "call"
+            && reference.IsMutualRecursion
+            && !reference.IsSelfReference);
+        Assert.DoesNotContain(references, reference =>
+            reference.ContainerName == "gamma");
+    }
+
     [Fact]
     public void Extract_CSharpConstructorAlias_DoesNotRewriteQualifiedCallWhenAliasNameAppearsElsewhereOnLine()
     {

From 15c9d2cec716d9ad7a5cc667d6bf368dfab14282 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 18:52:58 +0900
Subject: [PATCH 26/45] Extract MCP index discovery planning

---
 .../Mcp/McpToolHandlers.Indexing.Discovery.cs | 248 ++++++++++++++++++
 .../Mcp/McpToolHandlers.Indexing.Execution.cs | 218 +++------------
 2 files changed, 286 insertions(+), 180 deletions(-)
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.Indexing.Discovery.cs

diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Discovery.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Discovery.cs
new file mode 100644
index 000000000..8d606ae97
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Discovery.cs
@@ -0,0 +1,248 @@
+using CodeIndex.Database;
+using CodeIndex.Indexer;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private sealed record McpIndexTargetSet(CSharpStaticInterfacePrepass.FileTarget[] All,
+        List<CSharpStaticInterfacePrepass.FileTarget> CSharp);
+
+    private sealed record McpIndexDiscoveryPlan(
+        FilePurgePlan PurgePlan,
+        IReadOnlySet<string>? RetainedPathsForReuse,
+        bool HadCSharpStaticInterfaceContractsBeforePurge,
+        McpIndexScanAuthority ScanAuthority);
+
+    private sealed record McpIndexScanAuthority(
+        string ProjectPath,
+        IReadOnlyDictionary<string, string> FileLanguages,
+        HashSet<string>? RetainedPaths,
+        HashSet<string>? ListedDirectories,
+        HashSet<string>? AuthoritativeSubtreeDirectories,
+        HashSet<string>? ExplicitlyRemovedPaths,
+        bool HadErrors)
+    {
+        internal bool IsExistingCSharpSymbolPathNowNonCSharp(string indexPath)
+        {
+            var normalizedIndexPath = FileIndexer.NormalizeIndexPath(indexPath);
+            var currentPath = Path.Combine(
+                ProjectPath,
+                FileIndexer.NormalizeRelativePathForCurrentPlatform(normalizedIndexPath));
+            if (FileLanguages.TryGetValue(currentPath, out var currentLanguage))
+                return currentLanguage != "csharp";
+
+            if (RetainedPaths?.Contains(normalizedIndexPath) == true)
+                return false;
+            if (!HadErrors || ExplicitlyRemovedPaths?.Contains(normalizedIndexPath) == true)
+                return true;
+
+            var directory = GetIndexParentDirectory(normalizedIndexPath);
+            if (ListedDirectories?.Contains(directory) == true)
+                return true;
+            while (true)
+            {
+                if (AuthoritativeSubtreeDirectories?.Contains(directory) == true)
+                    return true;
+                if (directory.Length == 0)
+                    return false;
+                directory = GetIndexParentDirectory(directory);
+            }
+        }
+    }
+
+    private static FilePurgePlan PlanInitialMcpIndexPurge(
+        DbWriter writer,
+        string projectPath,
+        bool startedWithNoIndexedFiles,
+        CancellationToken cancellationToken)
+    {
+        var plan = startedWithNoIndexedFiles
+            ? FilePurgePlan.Empty
+            : writer.PlanStaleFiles(projectPath, cancellationToken: cancellationToken);
+        McpIndexStaleFilePurgePlannedForTesting?.Invoke(plan.Count);
+        return plan;
+    }
+
+    private static McpIndexTargetSet BuildMcpIndexTargetSet(
+        string projectPath,
+        FileIndexer indexer,
+        FileIndexer.ScanFilesResult scanResult)
+    {
+        var files = scanResult.Files;
+        var all = new CSharpStaticInterfacePrepass.FileTarget[files.Count];
+        var csharp = new List<CSharpStaticInterfacePrepass.FileTarget>(
+            scanResult.LanguageCounts.GetValueOrDefault("csharp"));
+        var hasGeneratedSuppressionPatterns =
+            indexer.HasGeneratedCodeExtractionSuppressionPatterns;
+        for (var index = 0; index < files.Count; index++)
+        {
+            var filePath = files[index];
+            var language = FileIndexer.GetReusableDetectedLanguage(
+                filePath,
+                scanResult.FileLanguages);
+            var target = CSharpStaticInterfacePrepass.FileTarget.Create(
+                projectPath,
+                filePath,
+                language);
+            target = target with
+            {
+                GeneratedExtractionSuppressed = hasGeneratedSuppressionPatterns
+                    && indexer.IsGeneratedCodeExtractionSuppressed(target.IndexPath),
+                ResolveSymlinkTargets = indexer.ResolvesSymlinkTargets,
+            };
+            all[index] = target;
+            if (language == "csharp")
+                csharp.Add(target);
+        }
+        return new McpIndexTargetSet(all, csharp);
+    }
+
+    private static McpIndexDiscoveryPlan BuildMcpIndexDiscoveryPlan(
+        DbWriter writer,
+        string projectPath,
+        FileIndexer.ScanFilesResult scanResult,
+        McpIndexTargetSet targets,
+        FilePurgePlan initialPurgePlan,
+        bool startedWithNoIndexedFiles,
+        bool deferCSharpMutations,
+        bool? csharpSourceEvidence,
+        bool priorFilterRetainedCSharpContracts,
+        CancellationToken cancellationToken)
+    {
+        var authority = BuildMcpIndexScanAuthority(
+            projectPath,
+            scanResult,
+            targets,
+            startedWithNoIndexedFiles);
+        var purgePlan = RefineMcpIndexPurgePlan(
+            writer,
+            authority,
+            initialPurgePlan,
+            cancellationToken);
+        if (deferCSharpMutations && purgePlan.Count > 0)
+            purgePlan = FilePurgePlan.Empty;
+
+        var hadCSharpContracts = !startedWithNoIndexedFiles
+            && purgePlan.Count > 0
+            && writer.HasCSharpFilesInFileIds(purgePlan.FileIds, cancellationToken)
+            && (csharpSourceEvidence == true
+                || writer.HasCSharpStaticInterfaceContractMembersInFileIds(
+                    purgePlan.FileIds,
+                    includeInterfaceDeclarationsAsConservativeEvidence:
+                        csharpSourceEvidence == null
+                        || !priorFilterRetainedCSharpContracts,
+                    cancellationToken));
+        var retainedPathsForReuse = SelectMcpIndexRetainedPathsForReuse(
+            purgePlan,
+            authority,
+            targets.All.LongLength,
+            startedWithNoIndexedFiles);
+        return new McpIndexDiscoveryPlan(
+            purgePlan,
+            retainedPathsForReuse,
+            hadCSharpContracts,
+            authority);
+    }
+
+    private static McpIndexScanAuthority BuildMcpIndexScanAuthority(
+        string projectPath,
+        FileIndexer.ScanFilesResult scanResult,
+        McpIndexTargetSet targets,
+        bool startedWithNoIndexedFiles)
+    {
+        if (startedWithNoIndexedFiles)
+            return new(projectPath, scanResult.FileLanguages, null, null, null, null, scanResult.HadErrors);
+
+        var retainedPaths = new HashSet<string>(targets.All.Length, StringComparer.Ordinal);
+        foreach (var target in targets.All)
+            retainedPaths.Add(target.IndexPath);
+        if (!scanResult.HadErrors)
+            return new(projectPath, scanResult.FileLanguages, retainedPaths, null, null, null, false);
+
+        retainedPaths.UnionWith(
+            scanResult.ProbeFailedFilePaths.Select(FileIndexer.NormalizeIndexPath));
+        var listedDirectories = scanResult.ListedDirectories
+            .Select(FileIndexer.NormalizeIndexPath)
+            .ToHashSet(StringComparer.Ordinal);
+        var authoritativeDirectories = scanResult.FullyScannedDirectories
+            .Select(FileIndexer.NormalizeIndexPath)
+            .ToHashSet(StringComparer.Ordinal);
+        authoritativeDirectories.UnionWith(
+            scanResult.AttributePrunedDirectories.Select(FileIndexer.NormalizeIndexPath));
+        authoritativeDirectories.UnionWith(
+            scanResult.NestedRepositories.Select(FileIndexer.NormalizeIndexPath));
+        var explicitlyRemovedPaths = scanResult.NonIndexablePaths
+            .Select(FileIndexer.NormalizeIndexPath)
+            .ToHashSet(StringComparer.Ordinal);
+        return new(
+            projectPath,
+            scanResult.FileLanguages,
+            retainedPaths,
+            listedDirectories,
+            authoritativeDirectories,
+            explicitlyRemovedPaths,
+            true);
+    }
+
+    private static FilePurgePlan RefineMcpIndexPurgePlan(
+        DbWriter writer,
+        McpIndexScanAuthority authority,
+        FilePurgePlan initialPurgePlan,
+        CancellationToken cancellationToken)
+    {
+        if (authority.RetainedPaths == null)
+            return initialPurgePlan;
+
+        // Partial scans authorize only listed children and fully scanned/pruned subtrees.
+        // Preserve pre-scan IDs for paths that reappear; prefer a containing scan plan so
+        // its deleted-byte estimate is not double counted by Merge.
+        var scanPurgePlan = !authority.HadErrors
+            || authority.AuthoritativeSubtreeDirectories!.Contains(string.Empty)
+                ? writer.PlanFilesOutsideRetainedSet(
+                    authority.RetainedPaths,
+                    cancellationToken)
+                : writer.PlanFilesOutsideRetainedSetWithinListedDirectories(
+                    authority.RetainedPaths,
+                    authority.ListedDirectories!,
+                    authority.AuthoritativeSubtreeDirectories,
+                    authority.ExplicitlyRemovedPaths!,
+                    cancellationToken);
+        if (scanPurgePlan.Count == 0)
+            return initialPurgePlan;
+        return ContainsEveryMcpIndexPurgeId(scanPurgePlan, initialPurgePlan)
+            ? scanPurgePlan
+            : FilePurgePlan.Merge([initialPurgePlan, scanPurgePlan]);
+    }
+
+    private static bool ContainsEveryMcpIndexPurgeId(FilePurgePlan candidate, FilePurgePlan required)
+    {
+        if (required.Count > candidate.Count)
+            return false;
+        foreach (var fileId in required.FileIds)
+        {
+            if (!FilePurgePlan.ContainsSortedFileId(candidate.FileIds, fileId))
+                return false;
+        }
+        return true;
+    }
+
+    private static IReadOnlySet<string>? SelectMcpIndexRetainedPathsForReuse(
+        FilePurgePlan purgePlan,
+        McpIndexScanAuthority authority,
+        long targetCount,
+        bool startedWithNoIndexedFiles)
+    {
+        if (startedWithNoIndexedFiles
+            || purgePlan.RemainingFileCount - targetCount <= targetCount)
+        {
+            return null;
+        }
+
+        McpIndexRetainedPathFilterAllocatedForTesting?.Invoke((int)targetCount);
+        return authority.RetainedPaths;
+    }
+
+    private static string GetIndexParentDirectory(string path) =>
+        path.LastIndexOf('/') is var separatorIndex && separatorIndex >= 0 ? path[..separatorIndex] : string.Empty;
+}
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
index 2249e0b18..52fe4723c 100644
--- a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
@@ -316,13 +316,11 @@ static string FormatDiagnosticPath(string projectRoot, string path)
         // applied only after a bulk guard, when selected, has suspended synchronization.
         // FTS trigger policy 選択前に stale file cleanup を plan し、実削除は bulk guard
         // 選択時に同期を停止した後だけ行う。
-        var staleFilePurgePlan = startedWithNoIndexedFiles
-            ? FilePurgePlan.Empty
-            : writer.PlanStaleFiles(projectPath, cancellationToken: requestToken);
-        var purged = staleFilePurgePlan.Count;
-        McpIndexStaleFilePurgePlannedForTesting?.Invoke(purged);
-        if (purged > 0)
-            csharpMetadataTargetsNeedRefresh = true;
+        var initialStaleFilePurgePlan = PlanInitialMcpIndexPurge(
+            writer,
+            projectPath,
+            startedWithNoIndexedFiles,
+            requestToken);
 
         // Load current reference-language support before the deferred mutation phase.
         // deferred mutation phase の前に現在の reference-language support を読み込む。
@@ -337,8 +335,6 @@ static string FormatDiagnosticPath(string projectRoot, string path)
         var csharpPrepassSymbolArtifacts = CSharpPrepassSymbolArtifactCache
             .CreateForFreshBuiltInExtraction(
                 startedWithNoIndexedFilesBeforeRebuild && !rebuild);
-        var purgedRefs = 0;
-
         // Scan and index / スキャン・インデックス
         var scanWithDirectorySnapshots = indexer.ScanFilesDetailedWithDirectoryListingSnapshots(
             cancellationToken: requestToken);
@@ -351,125 +347,12 @@ static string FormatDiagnosticPath(string projectRoot, string path)
         if (memorySamples != null)
             memorySamples.Add(CaptureMcpIndexMemorySample("scan", runStopwatch));
         var files = scanResult.Files;
-        var fileTargets = new CSharpStaticInterfacePrepass.FileTarget[files.Count];
+        var targets = BuildMcpIndexTargetSet(projectPath, indexer, scanResult);
+        var fileTargets = targets.All;
+        var csharpPrepassTargets = targets.CSharp;
         var languageCounts = scanResult.LanguageCounts;
-        var csharpPrepassTargetCapacity = languageCounts.TryGetValue("csharp", out var csharpFileCount) ? csharpFileCount : 0;
-        var csharpPrepassTargets = new List<CSharpStaticInterfacePrepass.FileTarget>(csharpPrepassTargetCapacity);
         var hasSqlTargets = languageCounts.ContainsKey("sql");
         var hasTypeScriptTargets = languageCounts.ContainsKey("typescript");
-        var hasGeneratedCodeExtractionSuppressionPatterns = indexer.HasGeneratedCodeExtractionSuppressionPatterns;
-        for (var i = 0; i < files.Count; i++)
-        {
-            var filePath = files[i];
-            var language = FileIndexer.GetReusableDetectedLanguage(filePath, scanResult.FileLanguages);
-            var target = CSharpStaticInterfacePrepass.FileTarget.Create(projectPath, filePath, language);
-            target = target with
-            {
-                GeneratedExtractionSuppressed = hasGeneratedCodeExtractionSuppressionPatterns
-                    && indexer.IsGeneratedCodeExtractionSuppressed(target.IndexPath),
-                ResolveSymlinkTargets = indexer.ResolvesSymlinkTargets
-            };
-            fileTargets[i] = target;
-            if (language == "csharp")
-                csharpPrepassTargets.Add(target);
-        }
-
-        HashSet<string>? scanRetainedPaths = null;
-        HashSet<string>? scanListedDirectories = null;
-        HashSet<string>? scanAuthoritativeSubtreeDirectories = null;
-        HashSet<string>? scanExplicitlyRemovedPaths = null;
-        if (!startedWithNoIndexedFiles)
-        {
-            scanRetainedPaths = new HashSet<string>(fileTargets.Length, StringComparer.Ordinal);
-            foreach (var target in fileTargets)
-                scanRetainedPaths.Add(target.IndexPath);
-
-            FilePurgePlan scanDerivedPurgePlan;
-            if (scanHadErrors)
-            {
-                // A failed probe is not proof that a persisted row disappeared. Conversely,
-                // a successful immediate-child listing is authoritative only for that parent,
-                // while a fully scanned or deliberately pruned directory authorizes its subtree.
-                // probe failureは既存row消滅の根拠にせず、partial scanのauthorityはlisted直下と
-                // fully-scanned / deliberate-prune subtreeだけに厳密に限定する。
-                scanRetainedPaths.UnionWith(
-                    scanResult.ProbeFailedFilePaths.Select(FileIndexer.NormalizeIndexPath));
-                scanListedDirectories = scanResult.ListedDirectories
-                    .Select(FileIndexer.NormalizeIndexPath)
-                    .ToHashSet(StringComparer.Ordinal);
-                scanAuthoritativeSubtreeDirectories = scanResult.FullyScannedDirectories
-                    .Select(FileIndexer.NormalizeIndexPath)
-                    .ToHashSet(StringComparer.Ordinal);
-                scanAuthoritativeSubtreeDirectories.UnionWith(
-                    scanResult.AttributePrunedDirectories.Select(FileIndexer.NormalizeIndexPath));
-                scanAuthoritativeSubtreeDirectories.UnionWith(
-                    scanResult.NestedRepositories.Select(FileIndexer.NormalizeIndexPath));
-                scanExplicitlyRemovedPaths = scanResult.NonIndexablePaths
-                    .Select(FileIndexer.NormalizeIndexPath)
-                    .ToHashSet(StringComparer.Ordinal);
-                scanDerivedPurgePlan = scanAuthoritativeSubtreeDirectories.Contains(string.Empty)
-                    ? writer.PlanFilesOutsideRetainedSet(scanRetainedPaths, requestToken)
-                    : writer.PlanFilesOutsideRetainedSetWithinListedDirectories(
-                        scanRetainedPaths,
-                        scanListedDirectories,
-                        scanAuthoritativeSubtreeDirectories,
-                        scanExplicitlyRemovedPaths,
-                        requestToken);
-            }
-            else
-            {
-                // A clean recursive scan is authoritative for the complete retained set,
-                // including files that still exist but became ignored or unsupported.
-                // clean scanでは保持集合全体をauthorityとし、存在するignore/unsupported化も除外する。
-                scanDerivedPurgePlan = writer.PlanFilesOutsideRetainedSet(
-                    scanRetainedPaths,
-                    requestToken);
-            }
-
-            if (scanDerivedPurgePlan.Count > 0)
-            {
-                var scanPlanContainsPreScanPlan = staleFilePurgePlan.Count <= scanDerivedPurgePlan.Count;
-                for (var planIndex = 0;
-                     scanPlanContainsPreScanPlan && planIndex < staleFilePurgePlan.FileIds.Count;
-                     planIndex++)
-                {
-                    scanPlanContainsPreScanPlan = FilePurgePlan.ContainsSortedFileId(
-                        scanDerivedPurgePlan.FileIds,
-                        staleFilePurgePlan.FileIds[planIndex]);
-                }
-
-                // Preserve the immutable pre-scan plan when a path reappeared during scanning.
-                // When the authoritative scan plan already contains every pre-scan ID, it is
-                // the exact union and retains its deleted-byte estimate without double counting.
-                // scan中に再出現したpathはpre-scan planを維持する。一方scan planが全IDを包含する
-                // 場合はそれ自体が正確なunionなので、deleted-byte見積りを重複加算しない。
-                staleFilePurgePlan = scanPlanContainsPreScanPlan
-                    ? scanDerivedPurgePlan
-                    : FilePurgePlan.Merge([staleFilePurgePlan, scanDerivedPurgePlan]);
-            }
-        }
-
-        purged = staleFilePurgePlan.Count;
-        if (purged > 0)
-            csharpMetadataTargetsNeedRefresh = true;
-        if (deferCSharpMutationsForIncompleteScan && staleFilePurgePlan.Count > 0)
-        {
-            // Do not combine an incomplete C# workspace with any planned deletion. A clean
-            // retry can apply the same stale cleanup while rebuilding implicit references.
-            // C# workspaceが不完全なrunではplanned deleteを延期し、clean retryへ委ねる。
-            staleFilePurgePlan = FilePurgePlan.Empty;
-            purged = 0;
-        }
-        var hadCSharpStaticInterfaceContractsBeforePurge = !startedWithNoIndexedFiles
-            && staleFilePurgePlan.Count > 0
-            && writer.HasCSharpFilesInFileIds(staleFilePurgePlan.FileIds, requestToken)
-            && (indexSnapshot.CSharpStaticInterfaceSourceEvidence == true
-                || writer.HasCSharpStaticInterfaceContractMembersInFileIds(
-                    staleFilePurgePlan.FileIds,
-                    includeInterfaceDeclarationsAsConservativeEvidence:
-                        indexSnapshot.CSharpStaticInterfaceSourceEvidence == null
-                        || !priorFilterRetainedCSharpContractMembers,
-                    requestToken));
         var knownReadableFileSizes = new Dictionary<string, long>(files.Count, StringComparer.Ordinal);
         long knownReadableBytesRead = 0;
         var knownReadableByteEstimateComplete = true;
@@ -489,14 +372,24 @@ void RememberReadableFileSize(string path, long size)
             }
             knownReadableFileSizes[path] = size;
         }
-        HashSet<string>? retainedPathsForReuse = null;
-        if (!rebuild
-            && !startedWithNoIndexedFiles
-            && staleFilePurgePlan.RemainingFileCount - fileTargets.LongLength > fileTargets.LongLength)
-        {
-            retainedPathsForReuse = scanRetainedPaths;
-            McpIndexRetainedPathFilterAllocatedForTesting?.Invoke(fileTargets.Length);
-        }
+        var discoveryPlan = BuildMcpIndexDiscoveryPlan(
+            writer,
+            projectPath,
+            scanResult,
+            targets,
+            initialStaleFilePurgePlan,
+            startedWithNoIndexedFiles,
+            deferCSharpMutationsForIncompleteScan,
+            indexSnapshot.CSharpStaticInterfaceSourceEvidence,
+            priorFilterRetainedCSharpContractMembers,
+            requestToken);
+        var staleFilePurgePlan = discoveryPlan.PurgePlan;
+        var retainedPathsForReuse = discoveryPlan.RetainedPathsForReuse;
+        var hadCSharpStaticInterfaceContractsBeforePurge =
+            discoveryPlan.HadCSharpStaticInterfaceContractsBeforePurge;
+        var purged = staleFilePurgePlan.Count;
+        if (purged > 0)
+            csharpMetadataTargetsNeedRefresh = true;
         await EmitProgressNotificationAsync(progressToken, 0, files.Count, "Index scan complete; indexing files.").ConfigureAwait(false);
         var csharpPositiveNoOpPolicyCandidate = indexSnapshot.CSharpStaticInterfaceSourceEvidence is not null
             && indexSnapshot.IndexComplete
@@ -514,11 +407,12 @@ void RememberReadableFileSize(string path, long size)
         var hasCSharpLanguageTransitions = false;
         void ObservePersistedCSharpPath(string indexPath)
         {
-            if (!hasCSharpLanguageTransitions && IsExistingCSharpSymbolPathNowNonCSharp(indexPath))
+            if (!hasCSharpLanguageTransitions
+                && discoveryPlan.ScanAuthority.IsExistingCSharpSymbolPathNowNonCSharp(indexPath))
                 hasCSharpLanguageTransitions = true;
         }
 
-        var reusableIndexedFileStats = !rebuild && !startedWithNoIndexedFiles
+        var reusableIndexedFileStats = !startedWithNoIndexedFiles
             ? writer.LoadReusableIndexedFileStats(
                 maxSymbolsPerFile,
                 maxReferencesPerFile,
@@ -564,54 +458,17 @@ bool CanReuseCSharpPrepassTargetWithoutRead(CSharpStaticInterfacePrepass.FileTar
             {
                 allCSharpPrepassTargetsReusable = false;
                 (csharpPrepassStatReuse ??= new Dictionary<string, IndexedFileStatReuseResult?>(
-                    csharpPrepassTargetCapacity,
+                    csharpPrepassTargets.Count,
                     StringComparer.Ordinal))[target.IndexPath] = null;
                 return false;
             }
 
             (csharpPrepassStatReuse ??= new Dictionary<string, IndexedFileStatReuseResult?>(
-                csharpPrepassTargetCapacity,
+                csharpPrepassTargets.Count,
                 StringComparer.Ordinal))[target.IndexPath] = existingFile.Value;
             return true;
         }
 
-        bool IsExistingCSharpSymbolPathNowNonCSharp(string indexPath)
-        {
-            var normalizedIndexPath = FileIndexer.NormalizeIndexPath(indexPath);
-            var currentPath = Path.Combine(
-                projectPath,
-                FileIndexer.NormalizeRelativePathForCurrentPlatform(normalizedIndexPath));
-            if (scanResult.FileLanguages.TryGetValue(currentPath, out var currentLanguage))
-                return currentLanguage != "csharp";
-
-            if (scanRetainedPaths?.Contains(normalizedIndexPath) == true)
-                return false;
-            if (!scanHadErrors)
-                return true;
-            if (scanExplicitlyRemovedPaths?.Contains(normalizedIndexPath) == true)
-                return true;
-
-            var directory = GetIndexParentDirectory(normalizedIndexPath);
-            if (scanListedDirectories?.Contains(directory) == true)
-                return true;
-            while (true)
-            {
-                if (scanAuthoritativeSubtreeDirectories?.Contains(directory) == true)
-                    return true;
-                if (directory.Length == 0)
-                    break;
-                directory = GetIndexParentDirectory(directory);
-            }
-
-            return false;
-        }
-
-        static string GetIndexParentDirectory(string path)
-        {
-            var separatorIndex = path.LastIndexOf('/');
-            return separatorIndex >= 0 ? path[..separatorIndex] : string.Empty;
-        }
-
         Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>? csharpWorkspaceFileSnapshots = null;
 
         string FormatCSharpWorkspaceSnapshotPath(string? path)
@@ -678,7 +535,7 @@ CSharpStaticInterfaceWorkspaceSymbols BuildStableCSharpWorkspace(
         {
             allCSharpPrepassTargetsReusable = true;
             csharpPrepassStatReuse = new Dictionary<string, IndexedFileStatReuseResult?>(
-                csharpPrepassTargetCapacity,
+                csharpPrepassTargets.Count,
                 StringComparer.Ordinal);
             foreach (var target in csharpPrepassTargets)
             {
@@ -725,7 +582,8 @@ CSharpStaticInterfaceWorkspaceSymbols BuildStableCSharpWorkspace(
                     isGeneratedCodeExtractionSuppressed: IsGeneratedExtractionSuppressed,
                     parallelism: 1,
                     excludedExistingFileIds: staleFilePurgePlan.FileIds,
-                    isExistingSymbolPathExcluded: IsExistingCSharpSymbolPathNowNonCSharp,
+                    isExistingSymbolPathExcluded:
+                        discoveryPlan.ScanAuthority.IsExistingCSharpSymbolPathNowNonCSharp,
                     patternConfigsAlreadyLoaded: true,
                     cancellationToken: requestToken,
                     symbolArtifactCache: csharpPrepassSymbolArtifacts));
@@ -870,8 +728,7 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
         var indexedSymbolExtractorLanguages = new HashSet<string>(languageCounts.Count, StringComparer.Ordinal);
         var symbolsDroppedByKindFilter = 0;
         var mutualRecursionRefreshNeeded = !referenceIdentityContractMatchedBeforeMutation
-            || purged > 0
-            || purgedRefs > 0;
+            || purged > 0;
         var freshCountFiles = 0L;
         var freshCountChunks = 0L;
         var freshCountSymbols = 0L;
@@ -1039,7 +896,8 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
                         isGeneratedCodeExtractionSuppressed: IsGeneratedExtractionSuppressed,
                         parallelism: 1,
                         excludedExistingFileIds: staleFilePurgePlan.FileIds,
-                        isExistingSymbolPathExcluded: IsExistingCSharpSymbolPathNowNonCSharp,
+                        isExistingSymbolPathExcluded:
+                            discoveryPlan.ScanAuthority.IsExistingCSharpSymbolPathNowNonCSharp,
                         patternConfigsAlreadyLoaded: true,
                         cancellationToken: requestToken));
                 preservePriorPositiveCSharpSourceNoOp = false;
@@ -1314,7 +1172,7 @@ await EmitProgressNotificationAsync(
         }
 
         McpIndexReferencePurgeForTesting?.Invoke();
-        purgedRefs = deferCSharpMutationsForIncompleteScan || startedWithNoIndexedFiles
+        var purgedRefs = deferCSharpMutationsForIncompleteScan || startedWithNoIndexedFiles
             ? 0
             : writer.PurgeUnsupportedReferences(ReferenceExtractor.GetSupportedLanguages(projectPath));
         if (purgedRefs > 0)

From 123d4fcd5e6a1aac4a507b56caeb8fed93c72b8f Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 19:22:05 +0900
Subject: [PATCH 27/45] Extract MCP FTS preflight planning

---
 .../Mcp/McpToolHandlers.Indexing.Execution.cs | 143 +++----------
 .../McpToolHandlers.Indexing.FtsPreflight.cs  | 191 ++++++++++++++++++
 2 files changed, 215 insertions(+), 119 deletions(-)
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.Indexing.FtsPreflight.cs

diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
index 52fe4723c..b4da938bf 100644
--- a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
@@ -353,25 +353,7 @@ static string FormatDiagnosticPath(string projectRoot, string path)
         var languageCounts = scanResult.LanguageCounts;
         var hasSqlTargets = languageCounts.ContainsKey("sql");
         var hasTypeScriptTargets = languageCounts.ContainsKey("typescript");
-        var knownReadableFileSizes = new Dictionary<string, long>(files.Count, StringComparer.Ordinal);
-        long knownReadableBytesRead = 0;
-        var knownReadableByteEstimateComplete = true;
-        void RememberReadableFileSize(string path, long size)
-        {
-            var priorSize = knownReadableFileSizes.TryGetValue(path, out var prior)
-                ? prior
-                : (long?)null;
-            if (knownReadableByteEstimateComplete
-                && !FtsBulkLoadTriggerGuard.TryUpdateKnownByteTotal(
-                    knownReadableBytesRead,
-                    priorSize,
-                    size,
-                    out knownReadableBytesRead))
-            {
-                knownReadableByteEstimateComplete = false;
-            }
-            knownReadableFileSizes[path] = size;
-        }
+        var readableBytes = new McpIndexReadableByteTracker(files.Count);
         var discoveryPlan = BuildMcpIndexDiscoveryPlan(
             writer,
             projectPath,
@@ -761,96 +743,22 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
                         target.GeneratedExtractionSuppressed == true);
         }
 
-        IndexedFileStatReuseResult?[]? statMatchedFiles = null;
-        bool[]? statPreflightCompleted = null;
-        var estimatedDirtyBytes = staleFilePurgePlan.DeletedBytes;
-        var persistedSizeExcessBytes = 0L;
-        var byteEstimateComplete = !scanHadErrors
-            && staleFilePurgePlan.ByteEstimateComplete
-            && knownReadableByteEstimateComplete;
-        var useFtsBulkLoad = rebuild || startedWithNoIndexedFiles;
-        var everyTargetMatchedFtsStatPreflight = !useFtsBulkLoad
-            && staleFilePurgePlan.Count == 0;
-        if (!useFtsBulkLoad)
-        {
-            statMatchedFiles = new IndexedFileStatReuseResult?[fileTargets.Length];
-            statPreflightCompleted = new bool[fileTargets.Length];
-            McpIndexFtsStatPreflightBufferAllocatedForTesting?.Invoke(fileTargets.Length);
-            for (var targetIndex = 0; targetIndex < fileTargets.Length; targetIndex++)
-            {
-                requestToken.ThrowIfCancellationRequested();
-                var target = fileTargets[targetIndex];
-                try
-                {
-                    authorizedRoot.EnsureAuthorizedEntry(target.FilePath);
-                    var statMatchedFile = GetStatMatchedFile(target);
-                    statMatchedFiles[targetIndex] = statMatchedFile;
-                    statPreflightCompleted[targetIndex] = true;
-                    if (statMatchedFile != null)
-                    {
-                        RememberReadableFileSize(target.FilePath, statMatchedFile.Value.Size);
-                        continue;
-                    }
-
-                    everyTargetMatchedFtsStatPreflight = false;
-
-                    var info = new FileInfo(target.FilePath);
-                    if (!info.Exists || info.Length < 0)
-                    {
-                        byteEstimateComplete = false;
-                        continue;
-                    }
-
-                    RememberReadableFileSize(target.FilePath, info.Length);
-                    var persistedSize = reusableIndexedFileStats!.GetPersistedSize(target.IndexPath);
-                    if (!FtsBulkLoadTriggerGuard.TryAccumulateDirtyFileBytes(
-                            estimatedDirtyBytes,
-                            persistedSizeExcessBytes,
-                            info.Length,
-                            persistedSize,
-                            out estimatedDirtyBytes,
-                            out persistedSizeExcessBytes))
-                    {
-                        byteEstimateComplete = false;
-                    }
-                }
-                catch (OperationCanceledException) when (requestToken.IsCancellationRequested)
-                {
-                    throw;
-                }
-                catch (McpIndexAuthorizationException)
-                {
-                    throw;
-                }
-                catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or NotSupportedException or ArgumentException)
-                {
-                    // Estimation must never bypass the existing per-file failure contract.
-                    // The real loop retries authorization/stat work inside its normal try/catch.
-                    byteEstimateComplete = false;
-                    everyTargetMatchedFtsStatPreflight = false;
-                    statPreflightCompleted[targetIndex] = false;
-                }
-            }
-
-            byteEstimateComplete &= knownReadableByteEstimateComplete;
-            var totalBytes = knownReadableBytesRead;
-            if (!knownReadableByteEstimateComplete
-                || totalBytes > long.MaxValue - staleFilePurgePlan.DeletedBytes)
-                byteEstimateComplete = false;
-            else
-                totalBytes += staleFilePurgePlan.DeletedBytes;
-            if (totalBytes > long.MaxValue - persistedSizeExcessBytes)
-                byteEstimateComplete = false;
-            else
-                totalBytes += persistedSizeExcessBytes;
-
-            useFtsBulkLoad = byteEstimateComplete
-                && FtsBulkLoadTriggerGuard.ShouldUseForDirtyBytes(estimatedDirtyBytes, totalBytes);
-        }
+        var ftsPreflight = BuildMcpIndexFtsPreflight(
+            fileTargets,
+            staleFilePurgePlan,
+            rebuild,
+            startedWithNoIndexedFiles,
+            scanHadErrors,
+            reusableIndexedFileStats,
+            authorizedRoot,
+            GetStatMatchedFile,
+            readableBytes,
+            requestToken);
+        var useFtsBulkLoad = ftsPreflight.UseBulkLoad;
 
         var reuseFinalCSharpStatAtActualSkip = false;
         if (preservePriorPositiveCSharpSourceNoOp
-            && everyTargetMatchedFtsStatPreflight)
+            && ftsPreflight.EveryTargetMatched)
         {
             // A pure no-op performs its second and final C# stat pass at the readiness
             // boundary. Reuse the candidate result in the per-file skip loop meanwhile.
@@ -859,7 +767,7 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
         }
 
         if (preservePriorPositiveCSharpSourceNoOp
-            && !everyTargetMatchedFtsStatPreflight)
+            && !ftsPreflight.EveryTargetMatched)
         {
             // Re-stat directly after the potentially long whole-workspace dirty-byte pass.
             // This is the last read-only boundary before readiness/purge/file mutations.
@@ -939,10 +847,7 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
                     }
 
                     foreach (var targetIndex in invalidatedCSharpTargetIndexes)
-                    {
-                        statMatchedFiles![targetIndex] = null;
-                        statPreflightCompleted![targetIndex] = true;
-                    }
+                        ftsPreflight.InvalidateTarget(targetIndex);
                 }
             }
         }
@@ -1199,7 +1104,7 @@ void DeferCSharpMutationsForStatRevalidation(
             {
                 var info = new FileInfo(target.FilePath);
                 if (info.Exists && info.Length >= 0)
-                    RememberReadableFileSize(target.FilePath, info.Length);
+                    readableBytes.Remember(target.FilePath, info.Length);
             }
             catch (Exception ex) when (ex is IOException or UnauthorizedAccessException
                 or NotSupportedException or ArgumentException)
@@ -1230,8 +1135,8 @@ void DeferCSharpMutationsForStatRevalidation(
             HdlGraphContractMatchesCurrent = hdlGraphContractMatchesCurrent,
             HotspotFamilyTrustMatchesCurrent = hotspotFamilyTrustMatchesCurrent,
             ReusableIndexedFileStats = reusableIndexedFileStats,
-            StatMatchedFiles = statMatchedFiles,
-            StatPreflightCompleted = statPreflightCompleted,
+            StatMatchedFiles = ftsPreflight.StatMatches,
+            StatPreflightCompleted = ftsPreflight.Completed,
             SymbolKindFilter = symbolKindFilter,
             PostExtractionHooks = postExtractionHooks,
             GetCSharpWorkspace = () => csharpWorkspace,
@@ -1244,7 +1149,7 @@ void DeferCSharpMutationsForStatRevalidation(
             LoadedCSharpWorkspaceSnapshotMatches = LoadedCSharpWorkspaceSnapshotMatches,
             DeferCSharpStatRevalidation = DeferCSharpMutationsForStatRevalidation,
             DeferCSharpLoadedSnapshotDrift = DeferCSharpMutationsForLoadedSnapshotDrift,
-            RememberReadableFileSize = RememberReadableFileSize,
+            RememberReadableFileSize = readableBytes.Remember,
             InsertIssuesForIndexedFile = InsertIssuesForIndexedFile,
             WriteProjectRootOnce = WriteProjectRootOnce,
             MarkSymbolKindFilterMetaIncompleteOnce = MarkSymbolKindFilterMetaIncompleteOnce,
@@ -1644,16 +1549,16 @@ await EmitProgressNotificationAsync(
             // MCP の no-op full-scan root backfill も readiness stamp 後に限定する。
             WriteProjectRootOnce();
             writer.WriteUnknownExtensionFileMetadata(scanResult.UnknownExtensionFiles);
-            var bytesRead = knownReadableFileSizes.Count == files.Count
-                ? (BytesRead: knownReadableBytesRead,
-                    SkippedFileCount: knownReadableByteEstimateComplete ? 0L : 1L)
+            var bytesRead = readableBytes.Sizes.Count == files.Count
+                ? (BytesRead: readableBytes.Total,
+                    SkippedFileCount: readableBytes.EstimateComplete ? 0L : 1L)
                 : SumReadableFileBytes(
                         files,
                         projectPath,
                         indexRunDiagnostics,
                         mcpIndexDiagnostics,
                         authorizedRoot.EnsureAuthorizedEntry,
-                        knownReadableFileSizes);
+                        readableBytes.Sizes);
             var referenceExtractionCapHits = writer.GetReferenceExtractionCapHits(issuesStateAvailable: true);
             writer.SetMetaValues(
                 (DbContext.LastIndexRunModeMetaKey, rebuild ? "rebuild" : "mcp"),
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FtsPreflight.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FtsPreflight.cs
new file mode 100644
index 000000000..f9b79490c
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FtsPreflight.cs
@@ -0,0 +1,191 @@
+using CodeIndex.Database;
+using CodeIndex.Indexer;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private sealed class McpIndexReadableByteTracker(int capacity)
+    {
+        internal Dictionary<string, long> Sizes { get; } =
+            new(capacity, StringComparer.Ordinal);
+        internal long Total { get; private set; }
+        internal bool EstimateComplete { get; private set; } = true;
+
+        internal void Remember(string path, long size)
+        {
+            var priorSize = Sizes.TryGetValue(path, out var prior)
+                ? prior
+                : (long?)null;
+            if (EstimateComplete)
+            {
+                EstimateComplete = FtsBulkLoadTriggerGuard.TryUpdateKnownByteTotal(
+                    Total,
+                    priorSize,
+                    size,
+                    out var updatedTotal);
+                Total = updatedTotal;
+            }
+            Sizes[path] = size;
+        }
+    }
+
+    private sealed class McpIndexFtsPreflightState(
+        IndexedFileStatReuseResult?[]? statMatches,
+        bool[]? completed,
+        bool useBulkLoad,
+        bool everyTargetMatched)
+    {
+        internal IndexedFileStatReuseResult?[]? StatMatches { get; } = statMatches;
+        internal bool[]? Completed { get; } = completed;
+        internal bool UseBulkLoad { get; } = useBulkLoad;
+        internal bool EveryTargetMatched { get; } = everyTargetMatched;
+
+        internal void InvalidateTarget(int targetIndex)
+        {
+            StatMatches![targetIndex] = null;
+            Completed![targetIndex] = true;
+        }
+    }
+
+    private static McpIndexFtsPreflightState BuildMcpIndexFtsPreflight(
+        CSharpStaticInterfacePrepass.FileTarget[] targets,
+        FilePurgePlan purgePlan,
+        bool rebuild,
+        bool startedWithNoIndexedFiles,
+        bool scanHadErrors,
+        ReusableIndexedFileStatsSnapshot? reusableFiles,
+        McpPathBoundary.IndexRootAuthorization authorizedRoot,
+        McpIndexStatMatchResolver getStatMatch,
+        McpIndexReadableByteTracker readableBytes,
+        CancellationToken cancellationToken)
+    {
+        if (rebuild || startedWithNoIndexedFiles)
+            return new(null, null, useBulkLoad: true, everyTargetMatched: false);
+
+        var statMatches = new IndexedFileStatReuseResult?[targets.Length];
+        var completed = new bool[targets.Length];
+        McpIndexFtsStatPreflightBufferAllocatedForTesting?.Invoke(targets.Length);
+        var everyTargetMatched = purgePlan.Count == 0;
+        var dirtyBytes = purgePlan.DeletedBytes;
+        var persistedSizeExcessBytes = 0L;
+        var estimateComplete = !scanHadErrors
+            && purgePlan.ByteEstimateComplete
+            && readableBytes.EstimateComplete;
+        for (var targetIndex = 0; targetIndex < targets.Length; targetIndex++)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var target = targets[targetIndex];
+            completed[targetIndex] = TryPreflightMcpIndexTarget(
+                in target,
+                reusableFiles!,
+                authorizedRoot,
+                getStatMatch,
+                readableBytes,
+                cancellationToken,
+                ref dirtyBytes,
+                ref persistedSizeExcessBytes,
+                ref estimateComplete,
+                out statMatches[targetIndex]);
+            if (!completed[targetIndex] || statMatches[targetIndex] == null)
+                everyTargetMatched = false;
+        }
+
+        var useBulkLoad = ShouldUseMcpIndexFtsBulkLoad(
+            purgePlan,
+            readableBytes,
+            dirtyBytes,
+            persistedSizeExcessBytes,
+            estimateComplete);
+        return new(statMatches, completed, useBulkLoad, everyTargetMatched);
+    }
+
+    private static bool TryPreflightMcpIndexTarget(
+        in CSharpStaticInterfacePrepass.FileTarget target,
+        ReusableIndexedFileStatsSnapshot reusableFiles,
+        McpPathBoundary.IndexRootAuthorization authorizedRoot,
+        McpIndexStatMatchResolver getStatMatch,
+        McpIndexReadableByteTracker readableBytes,
+        CancellationToken cancellationToken,
+        ref long dirtyBytes,
+        ref long persistedSizeExcessBytes,
+        ref bool estimateComplete,
+        out IndexedFileStatReuseResult? statMatch)
+    {
+        try
+        {
+            authorizedRoot.EnsureAuthorizedEntry(target.FilePath);
+            statMatch = getStatMatch(in target);
+            if (statMatch != null)
+            {
+                readableBytes.Remember(target.FilePath, statMatch.Value.Size);
+                return true;
+            }
+
+            var info = new FileInfo(target.FilePath);
+            if (!info.Exists || info.Length < 0)
+            {
+                estimateComplete = false;
+                return true;
+            }
+
+            readableBytes.Remember(target.FilePath, info.Length);
+            var persistedSize = reusableFiles.GetPersistedSize(target.IndexPath);
+            if (!FtsBulkLoadTriggerGuard.TryAccumulateDirtyFileBytes(
+                    dirtyBytes,
+                    persistedSizeExcessBytes,
+                    info.Length,
+                    persistedSize,
+                    out dirtyBytes,
+                    out persistedSizeExcessBytes))
+            {
+                estimateComplete = false;
+            }
+            return true;
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (McpIndexAuthorizationException)
+        {
+            throw;
+        }
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException
+            or NotSupportedException or ArgumentException)
+        {
+            // Leave the real file loop to retry and report its existing per-file error.
+            statMatch = null;
+            estimateComplete = false;
+            return false;
+        }
+    }
+
+    private static bool ShouldUseMcpIndexFtsBulkLoad(
+        FilePurgePlan purgePlan,
+        McpIndexReadableByteTracker readableBytes,
+        long dirtyBytes,
+        long persistedSizeExcessBytes,
+        bool estimateComplete)
+    {
+        estimateComplete &= readableBytes.EstimateComplete;
+        var totalBytes = readableBytes.Total;
+        if (!readableBytes.EstimateComplete
+            || totalBytes > long.MaxValue - purgePlan.DeletedBytes)
+        {
+            estimateComplete = false;
+        }
+        else
+        {
+            totalBytes += purgePlan.DeletedBytes;
+        }
+
+        if (totalBytes > long.MaxValue - persistedSizeExcessBytes)
+            estimateComplete = false;
+        else
+            totalBytes += persistedSizeExcessBytes;
+
+        return estimateComplete
+            && FtsBulkLoadTriggerGuard.ShouldUseForDirtyBytes(dirtyBytes, totalBytes);
+    }
+}

From 37820448e81d599facf90aab5dae45585b17ff11 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 19:59:16 +0900
Subject: [PATCH 28/45] Unify C# using catalog loading

---
 TESTING_GUIDE.md                              |   2 +
 .../Database/DbReader.CSharpResolution.cs     | 434 +-----------------
 .../Database/DbReader.CSharpUsingCatalog.cs   | 282 ++++++++++++
 src/CodeIndex/Database/DbReader.cs            |  22 +-
 .../DbReaderCSharpUsingCatalogTests.cs        | 118 +++++
 5 files changed, 412 insertions(+), 446 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbReader.CSharpUsingCatalog.cs
 create mode 100644 tests/CodeIndex.Tests/DbReaderCSharpUsingCatalogTests.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 3db091bde..117db4014 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -188,6 +188,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   Do not put a timing assertion in this test class. When a static lookup replay is useful, keep its Release harness temporary, feed the same persisted kind/count distribution to the legacy and candidate lookups, alternate execution order, and remove it before committing. The normal empty-database full-index A/B remains authoritative for the user-visible performance decision.
 - `DatabaseTests.cs`, `DatabasePermissionPolicyTests.cs`, `DbReader*Tests.cs`, `CSharpBaseListParserTests.cs`
   SQLite schema, write paths, migrations, and query behavior. DbReader coverage is split by query family, including search, SQL qualified-name handling, file dependencies, impact, and symbol-query suites, while shared seeded fixture state remains on the root `DbReaderTests` part. File-dependency list and cycle-candidate coverage keep pre-cancellation ahead of command construction and execution; cycle-candidate coverage also pins reverse include/exclude path scope to the target side.
+  `DbReaderCSharpUsingCatalogTests` keeps reader-scoped C# using-catalog behavior explicit: file-scoped namespaces extend through EOF, nested namespace imports stay within the innermost inclusive scope, repeated active path/line lookups reuse the same cached set, and local/global alias shadowing preserves resolvable chains while terminating cycles.
   `CSharpBaseListParserTests` keeps the SQLite-free base-list grammar matrix together, including generic constraints, nested generic/tuple/array syntax, alias qualifiers, primary/base constructors, declaration terminators, and the distinct reader type-reference and metadata head-identifier projections.
   Maintenance-lookup coverage keeps the `files(checksum)`, `files(path COLLATE NOCASE)`, and `file_issues(file_id, kind)` indexes aligned with their predicates and requires `EXPLAIN QUERY PLAN` index `SEARCH` operations for checksum purge, ASCII case-alias lookup, reusable-stat issue probes, and directory/stem rename candidates. The case-alias fixture uses changed content so checksum cannot hide a missing path lookup, and managed validation remains authoritative because SQLite `NOCASE` is only an ASCII prefilter, not a Unicode casing contract. Keep wildcard-bearing, extensionless, and near-match stem semantics in one fixture. Scoped-cleanup planning coverage unions checksum and exact same-directory/stem candidates into ascending deduplicated ID snapshots, merges overlapping plans, proves apply does not absorb matching rows added after planning, and rereads planned IDs immediately before apply so a deleted C# contract that reappears is deferred until a clean retry. The grouped C# fixture gives many targets one common checksum/stem and requires candidate-reader work to grow with unique keys plus returned rows rather than target-count squared; it also asserts that C# pre-workspace planning never deletes matching non-C# rows.
   Reference-resolution lookup coverage keeps the exact fresh-schema and read-migration index sets aligned for file/name, retained folded/NOCASE composite prefixes, resolved reverse edges, and the partial unresolved-mutual path. Assert the absence of all six retired single-prefix indexes plus the former all-row mutual index after migration and reopen, exact column order/collation/partial predicates, and `EXPLAIN QUERY PLAN` `SEARCH` operations for both full and scoped mutual SQL. Preserve fold-ready and legacy-fallback CLI/MCP exact-query signals, and rerun the same-name/different-container plus partial-class-over-same-file ranking fixtures when these indexes change.
@@ -1248,6 +1249,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   この test class に timing assertion を追加してはいけません。static lookup replay が有用な場合は Release harness を一時的なものに限定し、同一の保存済み kind/count 分布を旧来経路と候補経路へ流し、実行順を交互にしたうえで commit 前に削除します。ユーザーに見える性能の採否は、通常の空 database full-index A/B を authoritative としてください。
 - `DatabaseTests.cs`、`DatabasePermissionPolicyTests.cs`、`DbReader*Tests.cs`、`CSharpBaseListParserTests.cs`
   SQLite スキーマ、書き込み経路、マイグレーション、クエリ挙動のテスト。DbReader のカバレッジは search、SQL qualified name、file dependency、impact、symbol query などの query family ごとの partial suite に分割し、共有の seed 済み fixture 状態は root 側の `DbReaderTests` に残します。file dependency list / cycle candidate の coverage では command 構築・実行より前の pre-cancellation を固定し、cycle candidate の coverage では reverse include/exclude path scope が target 側へ適用されることも固定します。
+  `DbReaderCSharpUsingCatalogTests` では、reader scope の C# using catalog 契約を明示的に固定します。file-scoped namespace は EOF まで有効、nested namespace import は inclusive な最内 scope の外へ漏れず、同じ active path/line の反復 lookup は同一の cache set を再利用し、local/global alias の shadowing は解決可能な chain を保ちながら cycle で終了することを維持してください。
   `CSharpBaseListParserTests` には SQLite を使わない base-list 構文 matrix をまとめ、generic constraint、nested generic / tuple / array、alias qualifier、primary / base constructor、宣言終端、および reader の type-reference 投影と metadata の head-identifier 投影の差を固定します。
   maintenance lookup の coverage では `files(checksum)`、`files(path COLLATE NOCASE)`、`file_issues(file_id, kind)` の index を predicate と同期させ、checksum purge、ASCII case-alias lookup、再利用 stat の issue probe、directory/stem rename 候補が `EXPLAIN QUERY PLAN` で index `SEARCH` を使うことを必須とします。case-alias fixture は checksum で path lookup の欠落が隠れないよう content も変更し、SQLite `NOCASE` は Unicode casing contract ではなく ASCII prefilter にすぎないため managed 検証を authoritative に保ちます。wildcard を含む stem、拡張子なし、近似 stem の意味論は1つの fixture にまとめます。scoped cleanup planning の coverage では checksum と正確な同一 directory/stem の候補を昇順・重複排除済み ID snapshot に統合し、重複 plan の merge、plan 後に追加された一致 row を apply が取り込まないこと、apply 直前に planned ID を再読込して再出現した C# contract を clean retry まで延期することを固定します。grouped C# fixture は多数の target に共通 checksum/stem を与え、candidate reader の処理量が target 数の二乗ではなく unique key 数と返却 row 数に比例すること、および C# workspace 前の plan が一致する non-C# row を削除しないことを要求します。
   参照解決 lookup の coverage では fresh schema / read migration の正確な index setを、file/name、保持したfolded/NOCASE composite prefix、解決済み逆辺、未解決mutual用partial pathまで同期させます。migrationと再open後に退役したsingle-prefix 6本と旧全row mutual indexが存在しないこと、列順・collation・partial predicateを厳密に検証し、full/scoped mutual SQLの両方で`EXPLAIN QUERY PLAN`のindex `SEARCH`を必須とします。fold-ready/legacy fallback双方のCLI/MCP exact-query signalを維持し、これらのindexを変える際は同名・別containerとpartial classが同一file候補より優先される既存ranking fixtureも再実行してください。
diff --git a/src/CodeIndex/Database/DbReader.CSharpResolution.cs b/src/CodeIndex/Database/DbReader.CSharpResolution.cs
index ce3a11fe9..47a4bbb40 100644
--- a/src/CodeIndex/Database/DbReader.CSharpResolution.cs
+++ b/src/CodeIndex/Database/DbReader.CSharpResolution.cs
@@ -68,17 +68,9 @@ private HashSet<string> GetActiveCSharpTypeNamespaces(string path, int lineNumbe
             return cachedActiveNamespaces;
         }
 
-        if (!_csharpNamespaceScopesByPath.TryGetValue(path, out var namespaceScopes))
-        {
-            namespaceScopes = LoadCSharpNamespaceScopes(path);
-            _csharpNamespaceScopesByPath[path] = namespaceScopes;
-        }
-
-        if (!_csharpUsingNamespaceScopesByPath.TryGetValue(path, out var usingNamespaceScopes))
-        {
-            usingNamespaceScopes = LoadCSharpUsingNamespaceScopes(path);
-            _csharpUsingNamespaceScopesByPath[path] = usingNamespaceScopes;
-        }
+        var usingCatalog = GetCSharpPathUsingCatalog(path);
+        var namespaceScopes = usingCatalog.NamespaceDeclarations;
+        var usingNamespaceScopes = usingCatalog.NamespaceImports;
 
         var activeNamespaces = new HashSet<string>(StringComparer.Ordinal);
         foreach (var scope in namespaceScopes)
@@ -472,11 +464,7 @@ private bool HasActiveCSharpUsingTypeAlias(string path, int lineNumber, string s
         if (TryResolveActiveCSharpUsingAliasScope(path, lineNumber, symbolName, requireTypeAlias: true, out _))
             return true;
 
-        if (!_csharpUsingAliasScopesByPath.TryGetValue(path, out var scopes))
-        {
-            scopes = LoadCSharpUsingAliasScopes(path);
-            _csharpUsingAliasScopesByPath[path] = scopes;
-        }
+        var scopes = GetCSharpPathUsingCatalog(path).Aliases;
 
         for (var i = scopes.Count - 1; i >= 0; i--)
         {
@@ -522,11 +510,7 @@ private HashSet<string> GetActiveCSharpUsingStaticTargets(string path, int lineN
             return cachedActiveTargets;
         }
 
-        if (!_csharpUsingStaticScopesByPath.TryGetValue(path, out var scopes))
-        {
-            scopes = LoadCSharpUsingStaticScopes(path);
-            _csharpUsingStaticScopesByPath[path] = scopes;
-        }
+        var scopes = GetCSharpPathUsingCatalog(path).StaticImports;
 
         var activeTargets = new HashSet<string>(StringComparer.Ordinal);
         foreach (var scope in scopes)
@@ -551,128 +535,6 @@ private HashSet<string> GetActiveCSharpUsingStaticTargets(string path, int lineN
         return activeTargets;
     }
 
-    private List<CSharpNamespaceScope> LoadCSharpNamespaceScopes(string path)
-    {
-        using var cmd = _conn.CreateCommand();
-        cmd.CommandText = @"
-            SELECT s.line, s.body_start_line, s.body_end_line, s.end_line, s.name, s.signature, f.lines
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE f.path = @path
-              AND f.lang = 'csharp'
-              AND s.kind = 'namespace'
-            ORDER BY s.line";
-        SqliteCommandPolicy.Add(cmd, "@path", path);
-
-        var scopes = new List<CSharpNamespaceScope>();
-        using var reader = cmd.ExecuteTrackedReader();
-        while (reader.TrackedRead())
-        {
-            var line = reader.GetInt32(0);
-            var startLine = reader.IsDBNull(1) ? line : reader.GetInt32(1);
-            var endLine = reader.IsDBNull(2)
-                ? (reader.IsDBNull(3) ? line : reader.GetInt32(3))
-                : reader.GetInt32(2);
-            var signature = GetNullableString(reader, 5);
-            if (!string.IsNullOrWhiteSpace(signature)
-                && signature.TrimEnd().EndsWith(';')
-                && !reader.IsDBNull(6))
-            {
-                endLine = Math.Max(endLine, reader.GetInt32(6));
-            }
-
-            if (startLine <= 0 || endLine < startLine)
-                continue;
-
-            var qualifiedName = NormalizeDbCSharpQualifiedName(reader.GetString(4)) ?? string.Empty;
-            scopes.Add(new CSharpNamespaceScope(qualifiedName, startLine, endLine));
-        }
-
-        return scopes;
-    }
-
-    private List<CSharpUsingNamespaceScope> LoadCSharpUsingNamespaceScopes(string path)
-    {
-        var sql = @"
-            SELECT s.kind, s.line, s.body_start_line, s.body_end_line, s.end_line, s.signature, f.lines
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE f.path = @path
-              AND f.lang = 'csharp'
-              AND (s.kind = 'import' OR s.kind = 'namespace')
-            ORDER BY s.line";
-        var cmd = RentCommand(sql, static c => c.Parameters.Add("@path", SqliteType.Text));
-        SetParameter(cmd, "@path", path);
-
-        var namespaceScopes = new List<(int StartLine, int EndLine)>();
-        var imports = new List<(int Line, string Signature)>();
-        try
-        {
-            using var reader = cmd.ExecuteTrackedReader();
-            while (reader.TrackedRead())
-            {
-                var kind = reader.GetString(0);
-                var line = reader.GetInt32(1);
-                if (kind == "namespace")
-                {
-                    var startLine = reader.IsDBNull(2) ? line : reader.GetInt32(2);
-                    var endLine = reader.IsDBNull(3)
-                        ? (reader.IsDBNull(4) ? line : reader.GetInt32(4))
-                        : reader.GetInt32(3);
-                    var signature = GetNullableString(reader, 5);
-                    if (!string.IsNullOrWhiteSpace(signature)
-                        && signature.TrimEnd().EndsWith(';')
-                        && !reader.IsDBNull(6))
-                    {
-                        endLine = Math.Max(endLine, reader.GetInt32(6));
-                    }
-
-                    if (startLine > 0 && endLine >= startLine)
-                        namespaceScopes.Add((startLine, endLine));
-                    continue;
-                }
-
-                if (!reader.IsDBNull(5))
-                    imports.Add((line, reader.GetString(5)));
-            }
-        }
-        finally
-        {
-            ReleaseCommand(cmd);
-        }
-
-        var scopes = new List<CSharpUsingNamespaceScope>();
-        foreach (var import in imports)
-        {
-            if (!TryParseCSharpUsingNamespaceImport(import.Signature, out var target, out var isGlobal)
-                || isGlobal)
-            {
-                continue;
-            }
-
-            var scopeStartLine = 1;
-            var scopeEndLine = int.MaxValue;
-            var scopeWidth = int.MaxValue;
-            foreach (var (startLine, endLine) in namespaceScopes)
-            {
-                if (import.Line < startLine || import.Line > endLine)
-                    continue;
-
-                var width = endLine - startLine;
-                if (width > scopeWidth)
-                    continue;
-
-                scopeStartLine = startLine;
-                scopeEndLine = endLine;
-                scopeWidth = width;
-            }
-
-            scopes.Add(new CSharpUsingNamespaceScope(target!, import.Line, scopeStartLine, scopeEndLine));
-        }
-
-        return scopes;
-    }
-
     private List<CSharpContainingTypeScope> LoadCSharpContainingTypeScopes(string path)
     {
         using var cmd = _conn.CreateCommand();
@@ -905,286 +767,6 @@ private static string GetLastQualifiedSegment(string qualifiedName)
         return split < 0 ? qualifiedName : qualifiedName[(split + (split == lastColon ? 2 : 1))..];
     }
 
-    private List<CSharpUsingStaticScope> LoadCSharpUsingStaticScopes(string path)
-    {
-        var sql = @"
-            SELECT s.kind, s.line, s.body_start_line, s.body_end_line, s.end_line, s.signature, f.lines
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE f.path = @path
-              AND f.lang = 'csharp'
-              AND (s.kind = 'import' OR s.kind = 'namespace')
-            ORDER BY s.line";
-        var cmd = RentCommand(sql, static c => c.Parameters.Add("@path", SqliteType.Text));
-        SetParameter(cmd, "@path", path);
-
-        var namespaceScopes = new List<(int StartLine, int EndLine)>();
-        var imports = new List<(int Line, string Signature)>();
-        try
-        {
-            using var reader = cmd.ExecuteTrackedReader();
-            while (reader.TrackedRead())
-            {
-                var kind = reader.GetString(0);
-                var line = reader.GetInt32(1);
-                if (kind == "namespace")
-                {
-                    var startLine = reader.IsDBNull(2) ? line : reader.GetInt32(2);
-                    var endLine = reader.IsDBNull(3)
-                        ? (reader.IsDBNull(4) ? line : reader.GetInt32(4))
-                        : reader.GetInt32(3);
-                    var signature = GetNullableString(reader, 5);
-                    if (!string.IsNullOrWhiteSpace(signature)
-                        && signature.TrimEnd().EndsWith(';')
-                        && !reader.IsDBNull(6))
-                    {
-                        endLine = Math.Max(endLine, reader.GetInt32(6));
-                    }
-
-                    if (startLine > 0 && endLine >= startLine)
-                        namespaceScopes.Add((startLine, endLine));
-                    continue;
-                }
-
-                if (!reader.IsDBNull(5))
-                    imports.Add((line, reader.GetString(5)));
-            }
-        }
-        finally
-        {
-            ReleaseCommand(cmd);
-        }
-
-        var scopes = new List<CSharpUsingStaticScope>();
-        foreach (var import in imports)
-        {
-            if (!TryParseCSharpUsingStaticImport(import.Signature, out var target, out var isGlobal)
-                || isGlobal)
-            {
-                continue;
-            }
-
-            var scopeStartLine = 1;
-            var scopeEndLine = int.MaxValue;
-            var scopeWidth = int.MaxValue;
-            foreach (var (startLine, endLine) in namespaceScopes)
-            {
-                if (import.Line < startLine || import.Line > endLine)
-                    continue;
-
-                var width = endLine - startLine;
-                if (width > scopeWidth)
-                    continue;
-
-                scopeStartLine = startLine;
-                scopeEndLine = endLine;
-                scopeWidth = width;
-            }
-
-            scopes.Add(new CSharpUsingStaticScope(target!, import.Line, scopeStartLine, scopeEndLine));
-        }
-
-        return scopes;
-    }
-
-    private List<CSharpUsingAliasScope> LoadCSharpUsingAliasScopes(string path)
-    {
-        using var cmd = _conn.CreateCommand();
-        cmd.CommandText = @"
-            SELECT s.kind, s.line, s.body_start_line, s.body_end_line, s.end_line, s.signature, f.lines
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE f.path = @path
-              AND f.lang = 'csharp'
-              AND (s.kind = 'import' OR s.kind = 'namespace')
-            ORDER BY s.line";
-        SqliteCommandPolicy.Add(cmd, "@path", path);
-
-        var namespaceScopes = new List<(int StartLine, int EndLine)>();
-        var imports = new List<(int Line, string Signature)>();
-        using var reader = cmd.ExecuteTrackedReader();
-        while (reader.TrackedRead())
-        {
-            var kind = reader.GetString(0);
-            var line = reader.GetInt32(1);
-            if (kind == "namespace")
-            {
-                var startLine = reader.IsDBNull(2) ? line : reader.GetInt32(2);
-                var endLine = reader.IsDBNull(3)
-                    ? (reader.IsDBNull(4) ? line : reader.GetInt32(4))
-                    : reader.GetInt32(3);
-                var signature = GetNullableString(reader, 5);
-                if (!string.IsNullOrWhiteSpace(signature)
-                    && signature.TrimEnd().EndsWith(';')
-                    && !reader.IsDBNull(6))
-                {
-                    endLine = Math.Max(endLine, reader.GetInt32(6));
-                }
-
-                if (startLine > 0 && endLine >= startLine)
-                    namespaceScopes.Add((startLine, endLine));
-                continue;
-            }
-
-            if (!reader.IsDBNull(5))
-                imports.Add((line, reader.GetString(5)));
-        }
-
-        var scopes = new List<CSharpUsingAliasScope>();
-        foreach (var import in imports)
-        {
-            if (!TryParseCSharpUsingAliasImport(import.Signature, out var aliasName, out var targetQualifiedName, out var isGlobal)
-                || isGlobal)
-            {
-                continue;
-            }
-
-            var scopeStartLine = 1;
-            var scopeEndLine = int.MaxValue;
-            var scopeWidth = int.MaxValue;
-            foreach (var (startLine, endLine) in namespaceScopes)
-            {
-                if (import.Line < startLine || import.Line > endLine)
-                    continue;
-
-                var width = endLine - startLine;
-                if (width > scopeWidth)
-                    continue;
-
-                scopeStartLine = startLine;
-                scopeEndLine = endLine;
-                scopeWidth = width;
-            }
-
-            scopes.Add(new CSharpUsingAliasScope(
-                aliasName!,
-                targetQualifiedName!,
-                import.Line,
-                scopeStartLine,
-                scopeEndLine,
-                IsKnownCSharpTypeQualifiedName(targetQualifiedName!)));
-        }
-
-        return scopes;
-    }
-
-    private HashSet<string> GetGlobalCSharpUsingStaticTargets()
-    {
-        if (_csharpGlobalUsingStaticTargets != null)
-            return _csharpGlobalUsingStaticTargets;
-
-        var sql = @"
-            SELECT s.signature
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE f.lang = 'csharp'
-              AND s.kind = 'import'";
-
-        var targets = new HashSet<string>(StringComparer.Ordinal);
-        var cmd = RentCommand(sql, static _ => { });
-        try
-        {
-            using var reader = cmd.ExecuteTrackedReader();
-            while (reader.TrackedRead())
-            {
-                if (reader.IsDBNull(0))
-                    continue;
-                if (TryParseCSharpUsingStaticImport(reader.GetString(0), out var target, out var isGlobal)
-                    && isGlobal)
-                {
-                    targets.Add(target!);
-                }
-            }
-        }
-        finally
-        {
-            ReleaseCommand(cmd);
-        }
-
-        _csharpGlobalUsingStaticTargets = targets;
-        return _csharpGlobalUsingStaticTargets;
-    }
-
-    private Dictionary<string, CSharpUsingAliasScope> GetGlobalCSharpUsingAliasesByName()
-    {
-        if (_csharpGlobalUsingAliasesByName != null)
-            return _csharpGlobalUsingAliasesByName;
-
-        var sql = @"
-            SELECT s.signature
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE f.lang = 'csharp'
-              AND s.kind = 'import'";
-
-        var aliases = new Dictionary<string, CSharpUsingAliasScope>(StringComparer.Ordinal);
-        var cmd = RentCommand(sql, static _ => { });
-        try
-        {
-            using var reader = cmd.ExecuteTrackedReader();
-            while (reader.TrackedRead())
-            {
-                if (reader.IsDBNull(0))
-                    continue;
-                if (TryParseCSharpUsingAliasImport(reader.GetString(0), out var aliasName, out var targetQualifiedName, out var isGlobal)
-                    && isGlobal)
-                {
-                    aliases[aliasName!] = new CSharpUsingAliasScope(
-                        aliasName!,
-                        targetQualifiedName!,
-                        0,
-                        1,
-                        int.MaxValue,
-                        IsKnownCSharpTypeQualifiedName(targetQualifiedName!));
-                }
-            }
-        }
-        finally
-        {
-            ReleaseCommand(cmd);
-        }
-
-        _csharpGlobalUsingAliasesByName = aliases;
-        return _csharpGlobalUsingAliasesByName;
-    }
-
-    private HashSet<string> GetGlobalCSharpUsingNamespaces()
-    {
-        if (_csharpGlobalUsingNamespaces != null)
-            return _csharpGlobalUsingNamespaces;
-
-        var sql = @"
-            SELECT s.signature
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE f.lang = 'csharp'
-              AND s.kind = 'import'";
-
-        var namespaces = new HashSet<string>(StringComparer.Ordinal);
-        var cmd = RentCommand(sql, static _ => { });
-        try
-        {
-            using var reader = cmd.ExecuteTrackedReader();
-            while (reader.TrackedRead())
-            {
-                if (reader.IsDBNull(0))
-                    continue;
-                if (TryParseCSharpUsingNamespaceImport(reader.GetString(0), out var target, out var isGlobal)
-                    && isGlobal)
-                {
-                    namespaces.Add(target!);
-                }
-            }
-        }
-        finally
-        {
-            ReleaseCommand(cmd);
-        }
-
-        _csharpGlobalUsingNamespaces = namespaces;
-        return _csharpGlobalUsingNamespaces;
-    }
-
     private static bool TryParseCSharpUsingStaticImport(string signature, out string? target, out bool isGlobal)
     {
         target = null;
@@ -1242,11 +824,7 @@ private bool TryResolveActiveCSharpUsingAliasScope(string path, int lineNumber,
         if (string.IsNullOrWhiteSpace(aliasName))
             return false;
 
-        if (!_csharpUsingAliasScopesByPath.TryGetValue(path, out var scopes))
-        {
-            scopes = LoadCSharpUsingAliasScopes(path);
-            _csharpUsingAliasScopesByPath[path] = scopes;
-        }
+        var scopes = GetCSharpPathUsingCatalog(path).Aliases;
 
         for (var i = scopes.Count - 1; i >= 0; i--)
         {
diff --git a/src/CodeIndex/Database/DbReader.CSharpUsingCatalog.cs b/src/CodeIndex/Database/DbReader.CSharpUsingCatalog.cs
new file mode 100644
index 000000000..ac34ddea6
--- /dev/null
+++ b/src/CodeIndex/Database/DbReader.CSharpUsingCatalog.cs
@@ -0,0 +1,282 @@
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed record CSharpNamespaceScope(
+        string QualifiedName,
+        int ScopeStartLine,
+        int ScopeEndLine);
+
+    private sealed record CSharpUsingStaticScope(
+        string TargetQualifiedName,
+        int Line,
+        int ScopeStartLine,
+        int ScopeEndLine);
+
+    private sealed record CSharpUsingNamespaceScope(
+        string TargetQualifiedName,
+        int Line,
+        int ScopeStartLine,
+        int ScopeEndLine);
+
+    private sealed record CSharpUsingAliasScope(
+        string AliasName,
+        string TargetQualifiedName,
+        int Line,
+        int ScopeStartLine,
+        int ScopeEndLine,
+        bool TargetsType);
+
+    private sealed record CSharpRawUsingImport(int Line, string Signature);
+
+    private sealed record CSharpRawPathUsingCatalog(
+        List<CSharpNamespaceScope> NamespaceDeclarations,
+        List<CSharpRawUsingImport> Imports);
+
+    private sealed record CSharpPathUsingCatalog(
+        List<CSharpNamespaceScope> NamespaceDeclarations,
+        List<CSharpUsingNamespaceScope> NamespaceImports,
+        List<CSharpUsingStaticScope> StaticImports,
+        List<CSharpUsingAliasScope> Aliases);
+
+    private sealed record CSharpGlobalUsingCatalog(
+        HashSet<string> Namespaces,
+        HashSet<string> StaticTargets,
+        Dictionary<string, CSharpUsingAliasScope> AliasesByName);
+
+    private CSharpPathUsingCatalog GetCSharpPathUsingCatalog(string path)
+    {
+        if (_csharpUsingCatalogsByPath.TryGetValue(path, out var cached))
+            return cached;
+
+        var rawCatalog = LoadRawCSharpPathUsingCatalog(path);
+        var catalog = ProjectCSharpPathUsingCatalog(rawCatalog);
+        _csharpUsingCatalogsByPath[path] = catalog;
+        return catalog;
+    }
+
+    private CSharpRawPathUsingCatalog LoadRawCSharpPathUsingCatalog(string path)
+    {
+        const string sql = @"
+            SELECT s.kind, s.line, s.body_start_line, s.body_end_line, s.end_line,
+                   s.signature, f.lines, s.name
+            FROM symbols s
+            JOIN files f ON s.file_id = f.id
+            WHERE f.path = @path
+              AND f.lang = 'csharp'
+              AND (s.kind = 'import' OR s.kind = 'namespace')
+            ORDER BY s.line";
+        var cmd = RentCommand(sql, static c => c.Parameters.Add("@path", SqliteType.Text));
+        SetParameter(cmd, "@path", path);
+
+        var namespaceDeclarations = new List<CSharpNamespaceScope>();
+        var imports = new List<CSharpRawUsingImport>();
+        try
+        {
+            using var reader = cmd.ExecuteTrackedReader();
+            while (reader.TrackedRead())
+            {
+                var line = reader.GetInt32(1);
+                if (reader.GetString(0) == "namespace")
+                {
+                    var (startLine, endLine) = ReadCSharpNamespaceRange(reader, line);
+                    if (startLine <= 0 || endLine < startLine)
+                        continue;
+
+                    var qualifiedName = NormalizeDbCSharpQualifiedName(reader.GetString(7))
+                        ?? string.Empty;
+                    namespaceDeclarations.Add(new CSharpNamespaceScope(
+                        qualifiedName,
+                        startLine,
+                        endLine));
+                    continue;
+                }
+
+                if (!reader.IsDBNull(5))
+                    imports.Add(new CSharpRawUsingImport(line, reader.GetString(5)));
+            }
+        }
+        finally
+        {
+            ReleaseCommand(cmd);
+        }
+
+        return new CSharpRawPathUsingCatalog(namespaceDeclarations, imports);
+    }
+
+    private static (int StartLine, int EndLine) ReadCSharpNamespaceRange(
+        SqliteDataReader reader,
+        int declarationLine)
+    {
+        var startLine = reader.IsDBNull(2) ? declarationLine : reader.GetInt32(2);
+        var endLine = reader.IsDBNull(3)
+            ? (reader.IsDBNull(4) ? declarationLine : reader.GetInt32(4))
+            : reader.GetInt32(3);
+        var signature = GetNullableString(reader, 5);
+        if (!string.IsNullOrWhiteSpace(signature)
+            && signature.TrimEnd().EndsWith(';')
+            && !reader.IsDBNull(6))
+        {
+            endLine = Math.Max(endLine, reader.GetInt32(6));
+        }
+
+        return (startLine, endLine);
+    }
+
+    private CSharpPathUsingCatalog ProjectCSharpPathUsingCatalog(
+        CSharpRawPathUsingCatalog rawCatalog)
+    {
+        var namespaceImports = new List<CSharpUsingNamespaceScope>();
+        var staticImports = new List<CSharpUsingStaticScope>();
+        var aliases = new List<CSharpUsingAliasScope>();
+        foreach (var import in rawCatalog.Imports)
+        {
+            var (scopeStartLine, scopeEndLine) = FindCSharpImportScope(
+                import.Line,
+                rawCatalog.NamespaceDeclarations);
+            if (TryParseCSharpUsingNamespaceImport(import.Signature, out var namespaceTarget, out var namespaceIsGlobal)
+                && !namespaceIsGlobal)
+            {
+                namespaceImports.Add(new CSharpUsingNamespaceScope(
+                    namespaceTarget!, import.Line, scopeStartLine, scopeEndLine));
+            }
+
+            if (TryParseCSharpUsingStaticImport(import.Signature, out var staticTarget, out var staticIsGlobal)
+                && !staticIsGlobal)
+            {
+                staticImports.Add(new CSharpUsingStaticScope(
+                    staticTarget!, import.Line, scopeStartLine, scopeEndLine));
+            }
+
+            if (TryParseCSharpUsingAliasImport(
+                    import.Signature,
+                    out var aliasName,
+                    out var aliasTarget,
+                    out var aliasIsGlobal)
+                && !aliasIsGlobal)
+            {
+                aliases.Add(new CSharpUsingAliasScope(
+                    aliasName!,
+                    aliasTarget!,
+                    import.Line,
+                    scopeStartLine,
+                    scopeEndLine,
+                    IsKnownCSharpTypeQualifiedName(aliasTarget!)));
+            }
+        }
+
+        return new CSharpPathUsingCatalog(
+            rawCatalog.NamespaceDeclarations,
+            namespaceImports,
+            staticImports,
+            aliases);
+    }
+
+    private static (int StartLine, int EndLine) FindCSharpImportScope(
+        int importLine,
+        IReadOnlyList<CSharpNamespaceScope> namespaceDeclarations)
+    {
+        var scopeStartLine = 1;
+        var scopeEndLine = int.MaxValue;
+        var scopeWidth = int.MaxValue;
+        foreach (var scope in namespaceDeclarations)
+        {
+            if (importLine < scope.ScopeStartLine || importLine > scope.ScopeEndLine)
+                continue;
+
+            var width = scope.ScopeEndLine - scope.ScopeStartLine;
+            if (width > scopeWidth)
+                continue;
+
+            scopeStartLine = scope.ScopeStartLine;
+            scopeEndLine = scope.ScopeEndLine;
+            scopeWidth = width;
+        }
+
+        return (scopeStartLine, scopeEndLine);
+    }
+
+    private CSharpGlobalUsingCatalog GetGlobalCSharpUsingCatalog()
+    {
+        if (_csharpGlobalUsingCatalog != null)
+            return _csharpGlobalUsingCatalog;
+
+        var rawImports = LoadRawGlobalCSharpUsingImports();
+        _csharpGlobalUsingCatalog = ProjectGlobalCSharpUsingCatalog(rawImports);
+        return _csharpGlobalUsingCatalog;
+    }
+
+    private List<string> LoadRawGlobalCSharpUsingImports()
+    {
+        const string sql = @"
+            SELECT s.signature
+            FROM symbols s
+            JOIN files f ON s.file_id = f.id
+            WHERE f.lang = 'csharp'
+              AND s.kind = 'import'";
+        var cmd = RentCommand(sql, static _ => { });
+        var imports = new List<string>();
+        try
+        {
+            using var reader = cmd.ExecuteTrackedReader();
+            while (reader.TrackedRead())
+            {
+                if (!reader.IsDBNull(0))
+                    imports.Add(reader.GetString(0));
+            }
+        }
+        finally
+        {
+            ReleaseCommand(cmd);
+        }
+
+        return imports;
+    }
+
+    private CSharpGlobalUsingCatalog ProjectGlobalCSharpUsingCatalog(
+        IReadOnlyList<string> rawImports)
+    {
+        var namespaces = new HashSet<string>(StringComparer.Ordinal);
+        var staticTargets = new HashSet<string>(StringComparer.Ordinal);
+        var aliases = new Dictionary<string, CSharpUsingAliasScope>(StringComparer.Ordinal);
+        foreach (var signature in rawImports)
+        {
+            if (TryParseCSharpUsingNamespaceImport(signature, out var namespaceTarget, out var namespaceIsGlobal)
+                && namespaceIsGlobal)
+            {
+                namespaces.Add(namespaceTarget!);
+            }
+
+            if (TryParseCSharpUsingStaticImport(signature, out var staticTarget, out var staticIsGlobal)
+                && staticIsGlobal)
+            {
+                staticTargets.Add(staticTarget!);
+            }
+
+            if (TryParseCSharpUsingAliasImport(signature, out var aliasName, out var aliasTarget, out var aliasIsGlobal)
+                && aliasIsGlobal)
+            {
+                aliases[aliasName!] = new CSharpUsingAliasScope(
+                    aliasName!,
+                    aliasTarget!,
+                    0,
+                    1,
+                    int.MaxValue,
+                    IsKnownCSharpTypeQualifiedName(aliasTarget!));
+            }
+        }
+
+        return new CSharpGlobalUsingCatalog(namespaces, staticTargets, aliases);
+    }
+
+    private HashSet<string> GetGlobalCSharpUsingNamespaces()
+        => GetGlobalCSharpUsingCatalog().Namespaces;
+
+    private HashSet<string> GetGlobalCSharpUsingStaticTargets()
+        => GetGlobalCSharpUsingCatalog().StaticTargets;
+
+    private Dictionary<string, CSharpUsingAliasScope> GetGlobalCSharpUsingAliasesByName()
+        => GetGlobalCSharpUsingCatalog().AliasesByName;
+}
diff --git a/src/CodeIndex/Database/DbReader.cs b/src/CodeIndex/Database/DbReader.cs
index 2e67d6f85..17e26a280 100644
--- a/src/CodeIndex/Database/DbReader.cs
+++ b/src/CodeIndex/Database/DbReader.cs
@@ -84,11 +84,8 @@ public partial class DbReader : IDisposable
     private readonly IReadOnlySet<string> _symbolIndexes;
     private readonly IReadOnlySet<string> _referenceIndexes;
     private readonly HashSet<string> _indexedHotspotFamilyLanguages;
-    private readonly Dictionary<string, List<CSharpUsingStaticScope>> _csharpUsingStaticScopesByPath = new(StringComparer.Ordinal);
-    private readonly Dictionary<string, List<CSharpNamespaceScope>> _csharpNamespaceScopesByPath = new(StringComparer.Ordinal);
+    private readonly Dictionary<string, CSharpPathUsingCatalog> _csharpUsingCatalogsByPath = new(StringComparer.Ordinal);
     private readonly Dictionary<string, List<CSharpContainingTypeScope>> _csharpContainingTypeScopesByPath = new(StringComparer.Ordinal);
-    private readonly Dictionary<string, List<CSharpUsingNamespaceScope>> _csharpUsingNamespaceScopesByPath = new(StringComparer.Ordinal);
-    private readonly Dictionary<string, List<CSharpUsingAliasScope>> _csharpUsingAliasScopesByPath = new(StringComparer.Ordinal);
     private readonly Dictionary<string, Dictionary<int, HashSet<string>>> _activeCSharpTypeNamespacesByPathLine = new(StringComparer.Ordinal);
     private readonly Dictionary<string, Dictionary<int, List<CSharpContainingTypeScope>>> _activeCSharpContainingTypeScopesByPathLine = new(StringComparer.Ordinal);
     private readonly Dictionary<string, Dictionary<int, HashSet<string>>> _activeCSharpUsingStaticTargetsByPathLine = new(StringComparer.Ordinal);
@@ -98,9 +95,7 @@ public partial class DbReader : IDisposable
     private readonly Dictionary<string, HashSet<string>> _csharpInheritedContainingTypesByQualifiedName = new(StringComparer.Ordinal);
     private readonly Dictionary<string, CSharpContainingTypeScope?> _csharpContainingTypeScopeByQualifiedName = new(StringComparer.Ordinal);
     private bool _disposed;
-    private HashSet<string>? _csharpGlobalUsingStaticTargets;
-    private HashSet<string>? _csharpGlobalUsingNamespaces;
-    private Dictionary<string, CSharpUsingAliasScope>? _csharpGlobalUsingAliasesByName;
+    private CSharpGlobalUsingCatalog? _csharpGlobalUsingCatalog;
     private IReadOnlyCollection<string>? _workspaceSupportedReferenceLanguages;
     internal readonly bool _hasReferencesTable;
     internal readonly bool _hasHotspotReferenceCountsTable;
@@ -280,11 +275,7 @@ ELSE 0
     private const string SyntheticTopLevelCallerName = "<top-level>";
     private const string SyntheticTopLevelCallerKind = "function";
 
-    private sealed record CSharpNamespaceScope(string QualifiedName, int ScopeStartLine, int ScopeEndLine);
     private sealed record CSharpContainingTypeScope(string Path, string Kind, string QualifiedName, string? Visibility, string? Signature, int DeclarationLine, int ScopeStartLine, int ScopeEndLine);
-    private sealed record CSharpUsingStaticScope(string TargetQualifiedName, int Line, int ScopeStartLine, int ScopeEndLine);
-    private sealed record CSharpUsingNamespaceScope(string TargetQualifiedName, int Line, int ScopeStartLine, int ScopeEndLine);
-    private sealed record CSharpUsingAliasScope(string AliasName, string TargetQualifiedName, int Line, int ScopeStartLine, int ScopeEndLine, bool TargetsType);
     private sealed record CSharpTypeNamespaceCandidate(string QualifiedName, string Path, bool IsFileLocal);
     private sealed record CSharpContainingTypeCandidate(string QualifiedName, bool AccessibleFromDerivedType);
 
@@ -741,11 +732,8 @@ public void Dispose()
             return;
 
         _disposed = true;
-        _csharpUsingStaticScopesByPath.Clear();
-        _csharpNamespaceScopesByPath.Clear();
+        _csharpUsingCatalogsByPath.Clear();
         _csharpContainingTypeScopesByPath.Clear();
-        _csharpUsingNamespaceScopesByPath.Clear();
-        _csharpUsingAliasScopesByPath.Clear();
         _activeCSharpTypeNamespacesByPathLine.Clear();
         _activeCSharpContainingTypeScopesByPathLine.Clear();
         _activeCSharpUsingStaticTargetsByPathLine.Clear();
@@ -754,9 +742,7 @@ public void Dispose()
         _csharpTypeContainingTypesByName.Clear();
         _csharpInheritedContainingTypesByQualifiedName.Clear();
         _csharpContainingTypeScopeByQualifiedName.Clear();
-        _csharpGlobalUsingStaticTargets = null;
-        _csharpGlobalUsingNamespaces = null;
-        _csharpGlobalUsingAliasesByName = null;
+        _csharpGlobalUsingCatalog = null;
     }
 
     /// <summary>
diff --git a/tests/CodeIndex.Tests/DbReaderCSharpUsingCatalogTests.cs b/tests/CodeIndex.Tests/DbReaderCSharpUsingCatalogTests.cs
new file mode 100644
index 000000000..d65c01ba3
--- /dev/null
+++ b/tests/CodeIndex.Tests/DbReaderCSharpUsingCatalogTests.cs
@@ -0,0 +1,118 @@
+using System.Reflection;
+using CodeIndex.Database;
+
+namespace CodeIndex.Tests;
+
+public partial class DbReaderTests
+{
+    [Fact]
+    public void SearchReferences_CSharpUsingScopes_KeepFileScopedEofAndInnermostNestedImports()
+    {
+        InsertIndexedFile("src/Color.cs", "csharp",
+            "namespace Probe;\npublic enum Color { Red }\n");
+        InsertIndexedFile("src/FileScoped.cs", "csharp",
+            """
+            using static Probe.Color;
+            namespace RealTypes;
+            public sealed class Red { }
+            public sealed class FileScopedUse
+            {
+                public bool Match(object value) => value is Red;
+            }
+            """);
+        InsertIndexedFile("src/Nested.cs", "csharp",
+            """
+            using static Probe.Color;
+            namespace ScopeHost
+            {
+                namespace Inner
+                {
+                    using RealTypes;
+                    public sealed class NestedUse
+                    {
+                        public bool Match(object value) => value is Red;
+                    }
+                }
+
+                public sealed class OutsideUse
+                {
+                    public bool Match(object value) => value is Red;
+                }
+            }
+            """);
+
+        var results = _reader.SearchReferences(
+            "Red",
+            limit: 20,
+            lang: "csharp",
+            referenceKind: "type_reference",
+            exact: true);
+
+        Assert.Contains(results, row => row.Path == "src/FileScoped.cs" && row.ContainerName == "Match");
+        Assert.Contains(results, row => row.Path == "src/Nested.cs" && row.Line == 9);
+        Assert.DoesNotContain(results, row => row.Path == "src/Nested.cs" && row.Line == 15);
+
+        var activeNamespaces = typeof(DbReader).GetMethod(
+            "GetActiveCSharpTypeNamespaces",
+            BindingFlags.Instance | BindingFlags.NonPublic)!;
+        var first = activeNamespaces.Invoke(_reader, ["src/Nested.cs", 9]);
+        var second = activeNamespaces.Invoke(_reader, ["src/Nested.cs", 9]);
+        Assert.Same(first, second);
+    }
+
+    [Fact]
+    public void SearchReferences_CSharpUsingAliases_PreserveShadowedChainsAndTerminateCycles()
+    {
+        InsertIndexedFile("src/Definitions.cs", "csharp",
+            """
+            namespace Probe { public enum Color { Red } }
+            namespace RealTypes { public sealed class Red { } }
+            """);
+        InsertIndexedFile("src/GlobalUsings.cs", "csharp",
+            """
+            global using Root = global::RealTypes;
+            global using Chain = Root;
+            global using CycleA = CycleB;
+            global using CycleB = CycleA;
+            """);
+        InsertIndexedFile("src/Good.cs", "csharp",
+            """
+            using static Probe.Color;
+            using Red = Chain.Red;
+            public sealed class Good
+            {
+                public bool Match(object value) => value is Red;
+            }
+            """);
+        InsertIndexedFile("src/Shadow.cs", "csharp",
+            """
+            using static Probe.Color;
+            using Chain = MissingTypes;
+            using Red = Chain.Red;
+            public sealed class Shadow
+            {
+                public bool Match(object value) => value is Red;
+            }
+            """);
+        InsertIndexedFile("src/Cycle.cs", "csharp",
+            """
+            using static Probe.Color;
+            using Red = CycleA.Red;
+            public sealed class Cycle
+            {
+                public bool Match(object value) => value is Red;
+            }
+            """);
+
+        var results = _reader.SearchReferences(
+            "Red",
+            limit: 20,
+            lang: "csharp",
+            referenceKind: "type_reference",
+            exact: true);
+
+        Assert.Contains(results, row => row.Path == "src/Good.cs");
+        Assert.DoesNotContain(results, row => row.Path == "src/Shadow.cs");
+        Assert.DoesNotContain(results, row => row.Path == "src/Cycle.cs");
+    }
+}

From 98bc56bf1c2ef1f7f294a04e4e5a973ca6a95b1b Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 20:45:07 +0900
Subject: [PATCH 29/45] Decompose TypeScript augmentation rebuild

---
 TESTING_GUIDE.md                              |   2 +
 ...DbWriter.TypeScriptAugmentationPlanning.cs | 326 ++++++++++++++++
 ...Writer.TypeScriptAugmentationProjection.cs | 134 +++++++
 .../DbWriter.TypeScriptAugmentations.cs       | 369 +-----------------
 tests/CodeIndex.Tests/DatabaseTests.cs        | 207 ++++++++++
 5 files changed, 683 insertions(+), 355 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbWriter.TypeScriptAugmentationPlanning.cs
 create mode 100644 src/CodeIndex/Database/DbWriter.TypeScriptAugmentationProjection.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 117db4014..96fc40e88 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -52,6 +52,7 @@ Use the full suite by default. Use targeted filters only while iterating locally
 - `TransactionScope_RollbackClearsActiveTransactionBeforeDisposeReleasesGate` blocks rollback immediately before terminal-state publication, requires the detached active-transaction reference to be null while concurrent disposal and a successor still wait, then proves the successor transaction remains enlisted and commits after ownership transfers.
 - TypeScript augmentation grouping coverage seeds 5,000 singleton interfaces plus one two-declaration merge. Keep singleton groups as one stored declaration index and materialize declaration-index lists only for merged groups; preserve first-seen group and declaration order without restoring LINQ `GroupBy` allocation.
 - TypeScript augmentation graph-finalization coverage treats one mutual-recursion refresh as a physical-pass performance contract across incremental full scan, scoped update, and MCP indexing. A planned augmentation rebuild must replace the earlier graph pass and still refresh an empty result when it inherited that pass or deleted synthetic edges; marker-only validation with no inserted, deleted, or deferred graph work must restamp readiness with zero graph passes. Fresh or authoritative rebuild scans without TypeScript must use the normal graph pass and stamp augmentation readiness without rebuilding. Keep a late immutable-input drift case that skips augmentation, executes exactly one fallback refresh before partial readiness, leaves the augmentation marker stale, and succeeds with one augmentation-owned refresh on retry. Preserve the ordinary non-TypeScript graph tests, reference-index lifecycle, and the deferred `reference_graph` memory-sample attribution.
+- Direct TypeScript augmentation transaction fixtures must prove that scoped deletion tracks an old edge whose other declaration disappeared outside the graph scope, leaving no augmentation candidate or deleted-only hotspot, and that cancellation during owned deferred-hotspot completion restores reference IDs and rows, candidates, hotspots, and readiness markers exactly.
 - Incremental TypeScript augmentation coverage tracks both old and new interface names across full scan, scoped update, and MCP indexing. Rebuild only declarations sharing those exact names, delete stale augmentation rows for removed names, and batch name predicates below SQLite's parameter budget; retain full-rebuild fallback for fresh/rebuild runs, broad dirty-name sets, project-root or contract-version changes, and an upfront forced extractor refresh. A runtime JavaScript/TypeScript configuration refresh must track every refreshed file's old and new names, with the adaptive broad-set fallback remaining authoritative. Full-fallback and symbols-only paths must keep rollback-safe readiness-only tracking without materializing interface names. Coverage must keep 1,000 untouched singleton interfaces outside the candidate set, cross the name-batch boundary with 1,001 requested names, switch a 5,001-name request back to the full path, preserve unrelated merged references and module classification from non-dirty indexed interface names when disk fallback is unavailable, detect stale-file purge plus a persisted TypeScript-to-non-TypeScript language transition before replacement in all three indexing paths, clear readiness at most once after the latest rollback and skip further checks while that clear is durable, and interrupt synchronous SQLite work plus roll back augmentation rows on cancellation.
 - Index-finalization readiness coverage keeps reference-cap reads valid inside an active writer transaction, preserves an unavailable last-run cap snapshot when scoped updates inherit a missing IssuesReady flag, and checks mixed C#/VB partial hotspot-family rows with one grouped reader initialization. Preserve both language results and the degraded-readiness gate when changing readiness SQL; do not replace them with wall-clock thresholds.
 - CI runs the test project through `tests/CodeIndex.Tests/CodeIndex.Tests.runsettings`, enables VSTest blame crash and hang collection, applies a 75-minute session timeout plus 60-second xUnit long-running diagnostics, and reruns the suite once after an initial failure. If the retry passes, CI uploads `TestResults/flaky-retry.txt` with the TRX and blame artifacts so the run is treated as suspect instead of silently trusted.
@@ -1108,6 +1109,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
 - `TransactionScope_RollbackClearsActiveTransactionBeforeDisposeReleasesGate` は rollback の terminal-state 公開直前を停止し、detach 済み active-transaction reference が null の間も並行 Dispose と後続 owner が待機すること、その後の owner 移譲後に後続 transaction が enlist 状態を維持して commit できることを要求します。
 - TypeScript augmentation grouping coverage は、5,000個の singleton interface と2宣言からなる1個の merge を投入します。singleton group は1個の declaration index だけを保持し、declaration-index list は merged group に限って materializeしてください。LINQ `GroupBy` allocation を戻さず、first-seen group と declaration の順序を維持します。
 - TypeScript augmentation の graph-finalization coverage は、incremental full scan、scoped update、MCP indexing を横断して mutual-recursion refresh が物理的に1回であることを performance contract とします。予定された augmentation rebuild は先行 graph pass を置き換え、空の結果でもそのpassを引き継いだ場合または合成edgeを削除した場合はrefreshしなければなりません。edgeの挿入・削除も遅延graph workもないmarker検証だけなら、graph pass 0回でreadinessをrestampしてください。TypeScript のない fresh または authoritative rebuild scan は通常 graph pass を使い、augmentation rebuild なしで readiness を stamp します。late immutable-input drift では augmentation をskipし、partial readiness 前に fallback refresh を厳密に1回実行して augmentation marker を stale のまま残し、retry は augmentation 所有のrefresh 1回で成功することを維持してください。通常の非TypeScript graph test、reference-index lifecycle、遅延した `reference_graph` memory sample の帰属も保持します。
+- TypeScript augmentation transaction の direct fixture では、graph scope 外で片側宣言が消えた旧edgeを scoped delete が追跡して augmentation candidate と deleted-only hotspot を残さないこと、および owned deferred-hotspot completion 中の cancellation が reference ID / row、candidate、hotspot、readiness marker を完全に復元することを証明してください。
 - incremental TypeScript augmentation coverage は、full scan、scoped update、MCP indexing を横断して変更前・変更後の interface 名を追跡します。その完全一致名を共有する宣言だけを再構築し、削除済み名の stale augmentation 行を消し、SQLite parameter budget 未満で name predicate をbatch化してください。fresh/rebuild、広範なdirty-name集合、project rootまたはcontract version変更、開始時点での強制extractor refreshでは全量fallbackを維持します。実行中に判明するJavaScript/TypeScript設定refreshは、refresh対象全fileの変更前後の名前を追跡し、広範囲集合ではadaptive fallbackをauthoritativeにします。full-fallbackとsymbols-only pathではinterface名をmaterializeせず、rollback-safeなreadiness-only trackingを維持します。1,000個の未変更singleton interfaceがcandidate外であること、1,001 requested namesでname batch境界を越えること、5,001-name requestが全量pathへ戻ること、無関係なmerged referenceとdisk fallback不能時に非dirty名が示すmodule分類を維持すること、stale-file purgeおよび3つのindexing pathすべてで置換前に永続化済みTypeScript→非TypeScript言語遷移を検知すること、直近のrollback後にreadinessを最大1回clearしそのclearが永続化している間は追加checkを省くこと、cancel時に同期SQLite処理をinterruptしてaugmentation行をrollbackすることをcoverageに含めます。
 - index-finalization readiness coverage は active writer transaction 中の reference-cap read、IssuesReady flag を欠いた scoped update が unavailable な last-run cap snapshot を維持すること、C# / VB の partial hotspot-family rows を1回の grouped reader initialization で検証します。readiness SQL を変更するときは両言語の結果と degraded-readiness gate を維持し、wall-clock threshold へ置き換えないでください。
 - CI は `tests/CodeIndex.Tests/CodeIndex.Tests.runsettings` 経由でテストプロジェクトを実行し、VSTest の blame crash / hang 収集、75分のセッションタイムアウト、60秒の xUnit long-running 診断を有効にします。初回失敗時は suite を1回だけ再実行し、再実行で成功した場合は TRX / blame artifact と一緒に `TestResults/flaky-retry.txt` を upload して、その実行を疑わしい flaky run として扱います。
diff --git a/src/CodeIndex/Database/DbWriter.TypeScriptAugmentationPlanning.cs b/src/CodeIndex/Database/DbWriter.TypeScriptAugmentationPlanning.cs
new file mode 100644
index 000000000..01a251eeb
--- /dev/null
+++ b/src/CodeIndex/Database/DbWriter.TypeScriptAugmentationPlanning.cs
@@ -0,0 +1,326 @@
+using TypeScriptDeletedAugmentationReferences = System.Collections.Generic.List<(
+    long Id,
+    long FileId,
+    long? SourceId,
+    long? TargetId,
+    string? ContainerNameFolded,
+    string? SymbolNameFolded)>;
+
+namespace CodeIndex.Database;
+
+public partial class DbWriter
+{
+    private readonly record struct TypeScriptAugmentationScopePlan(
+        string[]? ScopedNames,
+        bool IncludeIndexedInterfaceMarkers);
+
+    private readonly record struct TypeScriptInterfaceDeclaration(
+        long FileId,
+        string Path,
+        string Name,
+        int Line,
+        int Column,
+        string Signature,
+        string Kind,
+        string ContainerName,
+        string? Visibility);
+
+    private TypeScriptAugmentationScopePlan BuildTypeScriptAugmentationScopePlan(
+        IReadOnlyCollection<string>? dirtyNames,
+        CancellationToken cancellationToken)
+    {
+        if (dirtyNames == null)
+            return new TypeScriptAugmentationScopePlan(null, IncludeIndexedInterfaceMarkers: false);
+
+        var uniqueNames = new HashSet<string>(StringComparer.Ordinal);
+        var inspectedNameCount = 0;
+        foreach (var name in dirtyNames)
+        {
+            if (!string.IsNullOrEmpty(name))
+                uniqueNames.Add(name);
+            if ((++inspectedNameCount & 1_023) == 0)
+                cancellationToken.ThrowIfCancellationRequested();
+        }
+        cancellationToken.ThrowIfCancellationRequested();
+        if (uniqueNames.Count > 1_024
+            && ShouldUseFullTypeScriptAugmentationRebuild(uniqueNames.Count, cancellationToken))
+        {
+            return new TypeScriptAugmentationScopePlan(null, IncludeIndexedInterfaceMarkers: false);
+        }
+
+        var scopedNames = new string[uniqueNames.Count];
+        uniqueNames.CopyTo(scopedNames);
+        Array.Sort(scopedNames, StringComparer.Ordinal);
+        return new TypeScriptAugmentationScopePlan(scopedNames, IncludeIndexedInterfaceMarkers: true);
+    }
+
+    private int DeleteAndTrackTypeScriptAugmentationReferences(
+        TypeScriptAugmentationScopePlan scopePlan,
+        HashSet<long> affectedFileIds,
+        CancellationToken cancellationToken)
+    {
+        var deletedReferences = new TypeScriptDeletedAugmentationReferences();
+        if (scopePlan.ScopedNames == null)
+        {
+            DeleteAllTypeScriptAugmentationReferences(
+                affectedFileIds,
+                deletedReferences,
+                cancellationToken);
+        }
+        else
+        {
+            DeleteScopedTypeScriptAugmentationReferences(
+                scopePlan.ScopedNames,
+                affectedFileIds,
+                deletedReferences,
+                cancellationToken);
+        }
+
+        TrackReferenceGraphDeletedReferences(deletedReferences);
+        return deletedReferences.Count;
+    }
+
+    private void DeleteAllTypeScriptAugmentationReferences(
+        HashSet<long> affectedFileIds,
+        TypeScriptDeletedAugmentationReferences deletedReferences,
+        CancellationToken cancellationToken)
+    {
+        var deleteCmd = RentCommand(
+            """
+            DELETE FROM symbol_references
+            WHERE reference_kind = 'augmentation'
+            RETURNING id,
+                      file_id,
+                      source_symbol_id,
+                      target_symbol_id,
+                      container_name_folded,
+                      symbol_name_folded
+            """,
+            static _ => { });
+        try
+        {
+            using var reader = deleteCmd.ExecuteReader();
+            ReadDeletedTypeScriptAugmentationReferences(
+                reader,
+                affectedFileIds,
+                deletedReferences,
+                cancellationToken);
+            cancellationToken.ThrowIfCancellationRequested();
+        }
+        finally
+        {
+            ReleaseCommand(deleteCmd);
+        }
+    }
+
+    private void DeleteScopedTypeScriptAugmentationReferences(
+        IReadOnlyList<string> scopedNames,
+        HashSet<long> affectedFileIds,
+        TypeScriptDeletedAugmentationReferences deletedReferences,
+        CancellationToken cancellationToken)
+    {
+        const int nameBatchSize = 900;
+        for (var offset = 0; offset < scopedNames.Count; offset += nameBatchSize)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var count = Math.Min(nameBatchSize, scopedNames.Count - offset);
+            using (var deleteCmd = CreateTypeScriptAugmentationNameCommand(
+                scopedNames,
+                offset,
+                count,
+                """
+                DELETE FROM symbol_references
+                WHERE reference_kind = 'augmentation'
+                  AND symbol_name IN ({0})
+                RETURNING id,
+                          file_id,
+                          source_symbol_id,
+                          target_symbol_id,
+                          container_name_folded,
+                          symbol_name_folded
+                """))
+            using (var reader = deleteCmd.ExecuteReader())
+            {
+                ReadDeletedTypeScriptAugmentationReferences(
+                    reader,
+                    affectedFileIds,
+                    deletedReferences,
+                    cancellationToken);
+            }
+            TypeScriptAugmentationNameBatchForTesting?.Invoke((offset / nameBatchSize) + 1);
+            cancellationToken.ThrowIfCancellationRequested();
+        }
+    }
+
+    private static void ReadDeletedTypeScriptAugmentationReferences(
+        Microsoft.Data.Sqlite.SqliteDataReader reader,
+        HashSet<long> affectedFileIds,
+        TypeScriptDeletedAugmentationReferences deletedReferences,
+        CancellationToken cancellationToken)
+    {
+        var deletedRowCount = 0;
+        while (reader.Read())
+        {
+            var fileId = reader.GetInt64(1);
+            affectedFileIds.Add(fileId);
+            deletedReferences.Add((
+                reader.GetInt64(0),
+                fileId,
+                ReadNullableInt64(reader, 2),
+                ReadNullableInt64(reader, 3),
+                ReadNullableString(reader, 4),
+                ReadNullableString(reader, 5)));
+            if ((++deletedRowCount & 255) == 0)
+                cancellationToken.ThrowIfCancellationRequested();
+        }
+    }
+
+    private List<TypeScriptInterfaceDeclaration> LoadTypeScriptInterfaceDeclarations(
+        TypeScriptAugmentationScopePlan scopePlan,
+        CancellationToken cancellationToken)
+    {
+        var declarations = new List<TypeScriptInterfaceDeclaration>();
+        if (scopePlan.ScopedNames == null)
+        {
+            var command = RentCommand(
+                BuildTypeScriptInterfaceDeclarationSql(namePredicate: null),
+                static _ => { });
+            try
+            {
+                using var reader = command.ExecuteReader();
+                ReadTypeScriptInterfaceDeclarations(reader, declarations, cancellationToken);
+            }
+            finally
+            {
+                ReleaseCommand(command);
+            }
+        }
+        else
+        {
+            LoadScopedTypeScriptInterfaceDeclarations(
+                scopePlan.ScopedNames,
+                declarations,
+                cancellationToken);
+        }
+        return declarations;
+    }
+
+    private void LoadScopedTypeScriptInterfaceDeclarations(
+        IReadOnlyList<string> scopedNames,
+        List<TypeScriptInterfaceDeclaration> declarations,
+        CancellationToken cancellationToken)
+    {
+        const int nameBatchSize = 900;
+        for (var offset = 0; offset < scopedNames.Count; offset += nameBatchSize)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var count = Math.Min(nameBatchSize, scopedNames.Count - offset);
+            using (var command = CreateTypeScriptAugmentationNameCommand(
+                scopedNames,
+                offset,
+                count,
+                BuildTypeScriptInterfaceDeclarationSql("s.name IN ({0})")))
+            using (var reader = command.ExecuteReader())
+            {
+                ReadTypeScriptInterfaceDeclarations(reader, declarations, cancellationToken);
+            }
+            TypeScriptAugmentationNameBatchForTesting?.Invoke((offset / nameBatchSize) + 1);
+            cancellationToken.ThrowIfCancellationRequested();
+        }
+    }
+
+    private static string BuildTypeScriptInterfaceDeclarationSql(string? namePredicate) =>
+        @"
+            SELECT s.file_id,
+                   f.path,
+                   s.name,
+                   s.line,
+                   s.start_column,
+                   s.signature,
+                   s.kind,
+                   s.container_name,
+                   s.visibility
+            FROM symbols s"
+        + (namePredicate == null ? string.Empty : " INDEXED BY idx_symbols_name")
+        + @"
+            JOIN files f ON f.id = s.file_id
+            WHERE f.lang = 'typescript'
+              AND s.name IS NOT NULL
+              AND s.name <> ''
+              AND s.kind = 'interface'"
+        + (namePredicate == null ? string.Empty : "\n              AND " + namePredicate)
+        + "\n            ORDER BY s.name, s.file_id, s.line";
+
+    private static void ReadTypeScriptInterfaceDeclarations(
+        Microsoft.Data.Sqlite.SqliteDataReader reader,
+        List<TypeScriptInterfaceDeclaration> declarations,
+        CancellationToken cancellationToken)
+    {
+        while (reader.Read())
+        {
+            declarations.Add(new TypeScriptInterfaceDeclaration(
+                reader.GetInt64(0),
+                reader.GetString(1),
+                reader.GetString(2),
+                reader.IsDBNull(3) ? 1 : Math.Max(1, reader.GetInt32(3)),
+                reader.IsDBNull(4) ? 1 : Math.Max(1, reader.GetInt32(4) + 1),
+                reader.IsDBNull(5) ? string.Empty : reader.GetString(5),
+                reader.IsDBNull(6) ? string.Empty : reader.GetString(6),
+                reader.IsDBNull(7) ? string.Empty : reader.GetString(7),
+                reader.IsDBNull(8) ? null : reader.GetString(8)));
+            if ((declarations.Count & 255) == 0)
+                cancellationToken.ThrowIfCancellationRequested();
+        }
+        cancellationToken.ThrowIfCancellationRequested();
+    }
+
+    private Microsoft.Data.Sqlite.SqliteCommand CreateTypeScriptAugmentationNameCommand(
+        IReadOnlyList<string> names,
+        int offset,
+        int count,
+        string sqlTemplate)
+    {
+        SqliteDynamicSql.EnsureParameterBudget(count, "TypeScript augmentation name batch");
+        var command = _conn.CreateCommand();
+        command.Transaction = _activeTransaction;
+        var parameterNames = new string[count];
+        for (var index = 0; index < count; index++)
+        {
+            var parameterName = SqliteDynamicSql.BuildParameterName("augmentation_name", index);
+            parameterNames[index] = parameterName;
+            command.Parameters.Add(parameterName, Microsoft.Data.Sqlite.SqliteType.Text).Value = names[offset + index];
+        }
+        command.CommandText = string.Format(
+            System.Globalization.CultureInfo.InvariantCulture,
+            sqlTemplate,
+            string.Join(", ", parameterNames));
+        return command;
+    }
+
+    private bool ShouldUseFullTypeScriptAugmentationRebuild(
+        int dirtyNameCount,
+        CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        var command = RentCommand(
+            @"
+                SELECT COUNT(*)
+                FROM symbols s INDEXED BY idx_symbols_kind
+                JOIN files f ON f.id = s.file_id
+                WHERE s.kind = 'interface'
+                  AND f.lang = 'typescript'",
+            static _ => { });
+        try
+        {
+            var declarationCount = Convert.ToInt64(
+                command.ExecuteScalar(),
+                System.Globalization.CultureInfo.InvariantCulture);
+            cancellationToken.ThrowIfCancellationRequested();
+            return dirtyNameCount >= Math.Max(1_024L, (declarationCount + 1L) / 2L);
+        }
+        finally
+        {
+            ReleaseCommand(command);
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbWriter.TypeScriptAugmentationProjection.cs b/src/CodeIndex/Database/DbWriter.TypeScriptAugmentationProjection.cs
new file mode 100644
index 000000000..9efed5605
--- /dev/null
+++ b/src/CodeIndex/Database/DbWriter.TypeScriptAugmentationProjection.cs
@@ -0,0 +1,134 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Database;
+
+public partial class DbWriter
+{
+    private List<ReferenceRecord> ProjectTypeScriptAugmentationReferences(
+        string? projectRoot,
+        TypeScriptAugmentationScopePlan scopePlan,
+        IReadOnlyList<TypeScriptInterfaceDeclaration> declarations,
+        CancellationToken cancellationToken)
+    {
+        var moduleFileIds = FindTypeScriptModuleFileIds(
+            projectRoot,
+            declarations,
+            scopePlan.IncludeIndexedInterfaceMarkers,
+            cancellationToken);
+        var groupIndexes = new Dictionary<(string Name, string ScopeKey), int>(declarations.Count);
+        var groups = new List<(int FirstDeclarationIndex, List<int>? DeclarationIndexes)>(declarations.Count);
+        for (var declarationIndex = 0; declarationIndex < declarations.Count; declarationIndex++)
+        {
+            if ((declarationIndex & 1_023) == 0)
+                cancellationToken.ThrowIfCancellationRequested();
+            var declaration = declarations[declarationIndex];
+            var key = (
+                declaration.Name,
+                BuildTypeScriptScopeKey(
+                    declaration.FileId,
+                    declaration.Path,
+                    declaration.Signature,
+                    declaration.ContainerName,
+                    moduleFileIds));
+            if (!groupIndexes.TryGetValue(key, out var groupIndex))
+            {
+                groupIndexes.Add(key, groups.Count);
+                groups.Add((declarationIndex, null));
+                continue;
+            }
+
+            var group = groups[groupIndex];
+            if (group.DeclarationIndexes == null)
+                group.DeclarationIndexes = new List<int>(2) { group.FirstDeclarationIndex };
+            group.DeclarationIndexes.Add(declarationIndex);
+            groups[groupIndex] = group;
+        }
+
+        return ProjectMergedTypeScriptAugmentationGroups(
+            scopePlan,
+            declarations,
+            groups,
+            cancellationToken);
+    }
+
+    private static List<ReferenceRecord> ProjectMergedTypeScriptAugmentationGroups(
+        TypeScriptAugmentationScopePlan scopePlan,
+        IReadOnlyList<TypeScriptInterfaceDeclaration> declarations,
+        IReadOnlyList<(int FirstDeclarationIndex, List<int>? DeclarationIndexes)> groups,
+        CancellationToken cancellationToken)
+    {
+        var references = new List<ReferenceRecord>();
+        var mergedGroupCount = 0;
+        var materializedDeclarationIndexCount = 0;
+        var mergedDeclarationCount = 0;
+        for (var groupIndex = 0; groupIndex < groups.Count; groupIndex++)
+        {
+            if ((groupIndex & 1_023) == 0)
+                cancellationToken.ThrowIfCancellationRequested();
+            var group = groups[groupIndex];
+            if (group.DeclarationIndexes == null)
+                continue;
+
+            mergedGroupCount++;
+            materializedDeclarationIndexCount += group.DeclarationIndexes.Count;
+            foreach (var declarationIndex in group.DeclarationIndexes)
+            {
+                if ((mergedDeclarationCount++ & 1_023) == 0)
+                    cancellationToken.ThrowIfCancellationRequested();
+                var declaration = declarations[declarationIndex];
+                references.Add(new ReferenceRecord
+                {
+                    FileId = declaration.FileId,
+                    SymbolName = declaration.Name,
+                    ReferenceKind = "augmentation",
+                    Line = declaration.Line,
+                    Column = declaration.Column,
+                    Context = declaration.Signature,
+                    ContainerKind = declaration.Kind == "interface" ? "interface" : "type",
+                    ContainerName = declaration.Name,
+                });
+            }
+        }
+        TypeScriptAugmentationGroupingForTesting?.Invoke(new TypeScriptAugmentationGroupingStats(
+            declarations.Count,
+            groups.Count,
+            mergedGroupCount,
+            materializedDeclarationIndexCount,
+            scopePlan.ScopedNames?.Length));
+        return references;
+    }
+
+    private void ApplyTypeScriptAugmentationReferences(
+        List<ReferenceRecord> references,
+        int deletedReferenceCount,
+        HashSet<long> affectedFileIds,
+        bool finalizeDeferredReferenceGraph,
+        ReferenceSecondaryIndexBulkLoadGuard? referenceSecondaryIndexBulkLoad,
+        CancellationToken cancellationToken)
+    {
+        InsertReferencesInAtomicFileScope(
+            references,
+            refreshMutualRecursionFlags: true,
+            cancellationToken,
+            referenceSecondaryIndexBulkLoad);
+        if (references.Count == 0
+            && (deletedReferenceCount > 0 || finalizeDeferredReferenceGraph))
+        {
+            // The insert helper intentionally no-ops for an empty batch. Augmentation
+            // rebuilds finalize only when they deleted synthetic edges or explicitly
+            // inherited a coalesced graph pass. Marker-only validation stays O(1) here.
+            // 空batchはedge削除または先行pass統合時だけgraphを確定し、marker検証だけなら省く。
+            cancellationToken.ThrowIfCancellationRequested();
+            RefreshMutualRecursionFlags(
+                cancellationToken,
+                referenceSecondaryIndexBulkLoad: referenceSecondaryIndexBulkLoad);
+        }
+        for (var referenceIndex = 0; referenceIndex < references.Count; referenceIndex++)
+        {
+            if ((referenceIndex & 1_023) == 0)
+                cancellationToken.ThrowIfCancellationRequested();
+            affectedFileIds.Remove(references[referenceIndex].FileId);
+        }
+        RefreshHotspotReferenceCounts(affectedFileIds, cancellationToken);
+    }
+}
diff --git a/src/CodeIndex/Database/DbWriter.TypeScriptAugmentations.cs b/src/CodeIndex/Database/DbWriter.TypeScriptAugmentations.cs
index 1c47e00d7..945c5acc2 100644
--- a/src/CodeIndex/Database/DbWriter.TypeScriptAugmentations.cs
+++ b/src/CodeIndex/Database/DbWriter.TypeScriptAugmentations.cs
@@ -166,17 +166,6 @@ internal static Action? TypeScriptAugmentationReadyCheckForTesting
         set => ScopedTypeScriptAugmentationReadyCheckForTesting.Value = value;
     }
 
-    private readonly record struct TypeScriptInterfaceDeclaration(
-        long FileId,
-        string Path,
-        string Name,
-        int Line,
-        int Column,
-        string Signature,
-        string Kind,
-        string ContainerName,
-        string? Visibility);
-
     public int RebuildTypeScriptAugmentationReferences(string? projectRoot = null) =>
         RebuildTypeScriptAugmentationReferencesCore(
             projectRoot,
@@ -247,245 +236,25 @@ private int RebuildTypeScriptAugmentationReferencesCore(
         {
             cancellationToken.ThrowIfCancellationRequested();
             _ = TryStartDeferredHotspotReferenceMutation();
-
-            string[]? scopedNames = null;
-            if (dirtyNames != null)
-            {
-                var uniqueNames = new HashSet<string>(StringComparer.Ordinal);
-                var inspectedNameCount = 0;
-                foreach (var name in dirtyNames)
-                {
-                    if (!string.IsNullOrEmpty(name))
-                        uniqueNames.Add(name);
-                    if ((++inspectedNameCount & 1_023) == 0)
-                        cancellationToken.ThrowIfCancellationRequested();
-                }
-                cancellationToken.ThrowIfCancellationRequested();
-                if (uniqueNames.Count > 1_024
-                    && ShouldUseFullTypeScriptAugmentationRebuild(uniqueNames.Count, cancellationToken))
-                {
-                    scopedNames = null;
-                }
-                else
-                {
-                    scopedNames = [.. uniqueNames];
-                    Array.Sort(scopedNames, StringComparer.Ordinal);
-                }
-            }
-
+            var scopePlan = BuildTypeScriptAugmentationScopePlan(dirtyNames, cancellationToken);
             var affectedFileIds = new HashSet<long>();
-            var deletedReferences = new List<(
-                long Id,
-                long FileId,
-                long? SourceId,
-                long? TargetId,
-                string? ContainerNameFolded,
-                string? SymbolNameFolded)>();
-            if (scopedNames == null)
-            {
-                var deleteCmd = RentCommand(
-                    """
-                    DELETE FROM symbol_references
-                    WHERE reference_kind = 'augmentation'
-                    RETURNING id,
-                              file_id,
-                              source_symbol_id,
-                              target_symbol_id,
-                              container_name_folded,
-                              symbol_name_folded
-                    """,
-                    static _ => { });
-                try
-                {
-                    using var reader = deleteCmd.ExecuteReader();
-                    var deletedRowCount = 0;
-                    while (reader.Read())
-                    {
-                        var fileId = reader.GetInt64(1);
-                        affectedFileIds.Add(fileId);
-                        deletedReferences.Add((
-                            reader.GetInt64(0),
-                            fileId,
-                            ReadNullableInt64(reader, 2),
-                            ReadNullableInt64(reader, 3),
-                            ReadNullableString(reader, 4),
-                            ReadNullableString(reader, 5)));
-                        if ((++deletedRowCount & 255) == 0)
-                            cancellationToken.ThrowIfCancellationRequested();
-                    }
-                    cancellationToken.ThrowIfCancellationRequested();
-                }
-                finally
-                {
-                    ReleaseCommand(deleteCmd);
-                }
-            }
-            else
-            {
-                ForEachTypeScriptAugmentationNameBatch(scopedNames, cancellationToken, (names, offset, count) =>
-                {
-                    using var deleteCmd = CreateTypeScriptAugmentationNameCommand(
-                        names,
-                        offset,
-                        count,
-                        """
-                        DELETE FROM symbol_references
-                        WHERE reference_kind = 'augmentation'
-                          AND symbol_name IN ({0})
-                        RETURNING id,
-                                  file_id,
-                                  source_symbol_id,
-                                  target_symbol_id,
-                                  container_name_folded,
-                                  symbol_name_folded
-                        """);
-                    using var reader = deleteCmd.ExecuteReader();
-                    var deletedRowCount = 0;
-                    while (reader.Read())
-                    {
-                        var fileId = reader.GetInt64(1);
-                        affectedFileIds.Add(fileId);
-                        deletedReferences.Add((
-                            reader.GetInt64(0),
-                            fileId,
-                            ReadNullableInt64(reader, 2),
-                            ReadNullableInt64(reader, 3),
-                            ReadNullableString(reader, 4),
-                            ReadNullableString(reader, 5)));
-                        if ((++deletedRowCount & 255) == 0)
-                            cancellationToken.ThrowIfCancellationRequested();
-                    }
-                });
-            }
-            TrackReferenceGraphDeletedReferences(deletedReferences);
-
-            var references = new List<ReferenceRecord>();
-            var declarations = new List<TypeScriptInterfaceDeclaration>();
-            if (scopedNames == null)
-            {
-                var cmd = RentCommand(
-                    BuildTypeScriptInterfaceDeclarationSql(namePredicate: null),
-                    static _ => { });
-                try
-                {
-                    using var reader = cmd.ExecuteReader();
-                    ReadTypeScriptInterfaceDeclarations(reader, declarations, cancellationToken);
-                }
-                finally
-                {
-                    ReleaseCommand(cmd);
-                }
-            }
-            else
-            {
-                ForEachTypeScriptAugmentationNameBatch(scopedNames, cancellationToken, (names, offset, count) =>
-                {
-                    using var cmd = CreateTypeScriptAugmentationNameCommand(
-                        names,
-                        offset,
-                        count,
-                        BuildTypeScriptInterfaceDeclarationSql("s.name IN ({0})"));
-                    using var reader = cmd.ExecuteReader();
-                    ReadTypeScriptInterfaceDeclarations(reader, declarations, cancellationToken);
-                });
-            }
-
-            var moduleFileIds = FindTypeScriptModuleFileIds(
+            var deletedReferenceCount = DeleteAndTrackTypeScriptAugmentationReferences(
+                scopePlan,
+                affectedFileIds,
+                cancellationToken);
+            var declarations = LoadTypeScriptInterfaceDeclarations(scopePlan, cancellationToken);
+            var references = ProjectTypeScriptAugmentationReferences(
                 projectRoot,
+                scopePlan,
                 declarations,
-                includeIndexedInterfaceMarkers: scopedNames != null,
                 cancellationToken);
-            var groupIndexes = new Dictionary<(string Name, string ScopeKey), int>(declarations.Count);
-            var groups = new List<(int FirstDeclarationIndex, List<int>? DeclarationIndexes)>(declarations.Count);
-            for (var declarationIndex = 0; declarationIndex < declarations.Count; declarationIndex++)
-            {
-                if ((declarationIndex & 1_023) == 0)
-                    cancellationToken.ThrowIfCancellationRequested();
-                var declaration = declarations[declarationIndex];
-                var key = (
-                    declaration.Name,
-                    BuildTypeScriptScopeKey(
-                        declaration.FileId,
-                        declaration.Path,
-                        declaration.Signature,
-                        declaration.ContainerName,
-                        moduleFileIds));
-                if (!groupIndexes.TryGetValue(key, out var groupIndex))
-                {
-                    groupIndexes.Add(key, groups.Count);
-                    groups.Add((declarationIndex, null));
-                    continue;
-                }
-
-                var group = groups[groupIndex];
-                if (group.DeclarationIndexes == null)
-                    group.DeclarationIndexes = new List<int>(2) { group.FirstDeclarationIndex };
-                group.DeclarationIndexes.Add(declarationIndex);
-                groups[groupIndex] = group;
-            }
-
-            var mergedGroupCount = 0;
-            var materializedDeclarationIndexCount = 0;
-            var mergedDeclarationCount = 0;
-            for (var groupIndex = 0; groupIndex < groups.Count; groupIndex++)
-            {
-                if ((groupIndex & 1_023) == 0)
-                    cancellationToken.ThrowIfCancellationRequested();
-                var group = groups[groupIndex];
-                if (group.DeclarationIndexes == null)
-                    continue;
-
-                mergedGroupCount++;
-                materializedDeclarationIndexCount += group.DeclarationIndexes.Count;
-                foreach (var declarationIndex in group.DeclarationIndexes)
-                {
-                    if ((mergedDeclarationCount++ & 1_023) == 0)
-                        cancellationToken.ThrowIfCancellationRequested();
-                    var declaration = declarations[declarationIndex];
-                    references.Add(new ReferenceRecord
-                    {
-                        FileId = declaration.FileId,
-                        SymbolName = declaration.Name,
-                        ReferenceKind = "augmentation",
-                        Line = declaration.Line,
-                        Column = declaration.Column,
-                        Context = declaration.Signature,
-                        ContainerKind = declaration.Kind == "interface" ? "interface" : "type",
-                        ContainerName = declaration.Name,
-                    });
-                }
-            }
-            TypeScriptAugmentationGroupingForTesting?.Invoke(new TypeScriptAugmentationGroupingStats(
-                declarations.Count,
-                groups.Count,
-                mergedGroupCount,
-                materializedDeclarationIndexCount,
-                scopedNames?.Length));
-
-            InsertReferencesInAtomicFileScope(
+            ApplyTypeScriptAugmentationReferences(
                 references,
-                refreshMutualRecursionFlags: true,
-                cancellationToken,
-                referenceSecondaryIndexBulkLoad);
-            if (references.Count == 0
-                && (deletedReferences.Count > 0 || finalizeDeferredReferenceGraph))
-            {
-                // The insert helper intentionally no-ops for an empty batch. Augmentation
-                // rebuilds finalize only when they deleted synthetic edges or explicitly
-                // inherited a coalesced graph pass. Marker-only validation stays O(1) here.
-                // 空batchはedge削除または先行pass統合時だけgraphを確定し、marker検証だけなら省く。
-                cancellationToken.ThrowIfCancellationRequested();
-                RefreshMutualRecursionFlags(
-                    cancellationToken,
-                    referenceSecondaryIndexBulkLoad: referenceSecondaryIndexBulkLoad);
-            }
-            for (var referenceIndex = 0; referenceIndex < references.Count; referenceIndex++)
-            {
-                if ((referenceIndex & 1_023) == 0)
-                    cancellationToken.ThrowIfCancellationRequested();
-                affectedFileIds.Remove(references[referenceIndex].FileId);
-            }
-            RefreshHotspotReferenceCounts(affectedFileIds, cancellationToken);
+                deletedReferenceCount,
+                affectedFileIds,
+                finalizeDeferredReferenceGraph,
+                referenceSecondaryIndexBulkLoad,
+                cancellationToken);
             cancellationToken.ThrowIfCancellationRequested();
             MarkTypeScriptAugmentationReady();
             ownedDeferredRefresh?.Complete(cancellationToken);
@@ -503,116 +272,6 @@ AND symbol_name IN ({0})
         }
     }
 
-    private static string BuildTypeScriptInterfaceDeclarationSql(string? namePredicate) =>
-        @"
-            SELECT s.file_id,
-                   f.path,
-                   s.name,
-                   s.line,
-                   s.start_column,
-                   s.signature,
-                   s.kind,
-                   s.container_name,
-                   s.visibility
-            FROM symbols s"
-        + (namePredicate == null ? string.Empty : " INDEXED BY idx_symbols_name")
-        + @"
-            JOIN files f ON f.id = s.file_id
-            WHERE f.lang = 'typescript'
-              AND s.name IS NOT NULL
-              AND s.name <> ''
-              AND s.kind = 'interface'"
-        + (namePredicate == null ? string.Empty : "\n              AND " + namePredicate)
-        + "\n            ORDER BY s.name, s.file_id, s.line";
-
-    private static void ReadTypeScriptInterfaceDeclarations(
-        Microsoft.Data.Sqlite.SqliteDataReader reader,
-        List<TypeScriptInterfaceDeclaration> declarations,
-        CancellationToken cancellationToken)
-    {
-        while (reader.Read())
-        {
-            declarations.Add(new TypeScriptInterfaceDeclaration(
-                reader.GetInt64(0),
-                reader.GetString(1),
-                reader.GetString(2),
-                reader.IsDBNull(3) ? 1 : Math.Max(1, reader.GetInt32(3)),
-                reader.IsDBNull(4) ? 1 : Math.Max(1, reader.GetInt32(4) + 1),
-                reader.IsDBNull(5) ? string.Empty : reader.GetString(5),
-                reader.IsDBNull(6) ? string.Empty : reader.GetString(6),
-                reader.IsDBNull(7) ? string.Empty : reader.GetString(7),
-                reader.IsDBNull(8) ? null : reader.GetString(8)));
-            if ((declarations.Count & 255) == 0)
-                cancellationToken.ThrowIfCancellationRequested();
-        }
-        cancellationToken.ThrowIfCancellationRequested();
-    }
-
-    private Microsoft.Data.Sqlite.SqliteCommand CreateTypeScriptAugmentationNameCommand(
-        IReadOnlyList<string> names,
-        int offset,
-        int count,
-        string sqlTemplate)
-    {
-        SqliteDynamicSql.EnsureParameterBudget(count, "TypeScript augmentation name batch");
-        var command = _conn.CreateCommand();
-        command.Transaction = _activeTransaction;
-        var parameterNames = new string[count];
-        for (var index = 0; index < count; index++)
-        {
-            var parameterName = SqliteDynamicSql.BuildParameterName("augmentation_name", index);
-            parameterNames[index] = parameterName;
-            command.Parameters.Add(parameterName, Microsoft.Data.Sqlite.SqliteType.Text).Value = names[offset + index];
-        }
-        command.CommandText = string.Format(
-            System.Globalization.CultureInfo.InvariantCulture,
-            sqlTemplate,
-            string.Join(", ", parameterNames));
-        return command;
-    }
-
-    private static void ForEachTypeScriptAugmentationNameBatch(
-        IReadOnlyList<string> names,
-        CancellationToken cancellationToken,
-        Action<IReadOnlyList<string>, int, int> action)
-    {
-        const int nameBatchSize = 900;
-        for (var offset = 0; offset < names.Count; offset += nameBatchSize)
-        {
-            cancellationToken.ThrowIfCancellationRequested();
-            action(names, offset, Math.Min(nameBatchSize, names.Count - offset));
-            TypeScriptAugmentationNameBatchForTesting?.Invoke((offset / nameBatchSize) + 1);
-            cancellationToken.ThrowIfCancellationRequested();
-        }
-    }
-
-    private bool ShouldUseFullTypeScriptAugmentationRebuild(
-        int dirtyNameCount,
-        CancellationToken cancellationToken)
-    {
-        cancellationToken.ThrowIfCancellationRequested();
-        var cmd = RentCommand(
-            @"
-                SELECT COUNT(*)
-                FROM symbols s INDEXED BY idx_symbols_kind
-                JOIN files f ON f.id = s.file_id
-                WHERE s.kind = 'interface'
-                  AND f.lang = 'typescript'",
-            static _ => { });
-        try
-        {
-            var declarationCount = Convert.ToInt64(
-                cmd.ExecuteScalar(),
-                System.Globalization.CultureInfo.InvariantCulture);
-            cancellationToken.ThrowIfCancellationRequested();
-            return dirtyNameCount >= Math.Max(1_024L, (declarationCount + 1L) / 2L);
-        }
-        finally
-        {
-            ReleaseCommand(cmd);
-        }
-    }
-
     private bool AddTypeScriptInterfaceNamesAtPath(
         string path,
         HashSet<string>? destination,
diff --git a/tests/CodeIndex.Tests/DatabaseTests.cs b/tests/CodeIndex.Tests/DatabaseTests.cs
index 1d8fe08d2..17ee56a46 100644
--- a/tests/CodeIndex.Tests/DatabaseTests.cs
+++ b/tests/CodeIndex.Tests/DatabaseTests.cs
@@ -8890,6 +8890,213 @@ public void RebuildTypeScriptAugmentationReferences_EmptyBatchRefreshesDeletedEd
         }
     }
 
+    [Fact]
+    public void RebuildTypeScriptAugmentationReferences_ScopedGraphTracksDeletedEdgesWithoutReplacement()
+    {
+        var firstFileId = _writer.UpsertFile(CreateTypeScriptFile("src/scoped-delete-first.ts"));
+        var secondFileId = _writer.UpsertFile(CreateTypeScriptFile("src/scoped-delete-second.ts"));
+        _writer.InsertSymbols(
+        [
+            CreateInterface(firstFileId, "ScopedDeletedMerge"),
+            CreateInterface(secondFileId, "ScopedDeletedMerge"),
+        ]);
+        Assert.Equal(2, _writer.RebuildTypeScriptAugmentationReferences("."));
+        Assert.True(ExecuteScalarLong(
+            "SELECT COUNT(*) FROM symbol_reference_candidates") > 0);
+
+        ExecuteNonQuery(
+            _db.Connection,
+            $"DELETE FROM symbols WHERE file_id = {secondFileId.ToString(CultureInfo.InvariantCulture)} AND name = 'ScopedDeletedMerge'");
+
+        var previousScopeHook = DbWriter.ReferenceGraphRefreshScopeForTesting;
+        DbWriter.ReferenceGraphRefreshScopeStats? scopeStats = null;
+        try
+        {
+            DbWriter.ReferenceGraphRefreshScopeForTesting = stats =>
+            {
+                scopeStats = stats;
+                previousScopeHook?.Invoke(stats);
+            };
+            using var graphScope = _writer.BeginReferenceGraphRefreshScope();
+
+            Assert.Equal(
+                0,
+                _writer.RebuildTypeScriptAugmentationReferences(
+                    ".",
+                    ["ScopedDeletedMerge"]));
+
+            Assert.NotNull(scopeStats);
+            Assert.False(scopeStats!.UsedFullRefresh);
+            Assert.Equal(
+                0,
+                ExecuteScalarLong(
+                    "SELECT COUNT(*) FROM symbol_references WHERE reference_kind = 'augmentation'"));
+            Assert.Equal(
+                0,
+                ExecuteScalarLong("SELECT COUNT(*) FROM symbol_reference_candidates"));
+            Assert.Equal(
+                0,
+                ExecuteScalarLong(
+                    "SELECT COUNT(*) FROM hotspot_reference_counts WHERE lang = 'typescript'"));
+            Assert.True(_writer.TypeScriptAugmentationVersionMatchesCurrent());
+            Assert.True(_writer.ReferenceIdentityContractMatchesCurrent());
+            Assert.Equal(
+                DbContext.HotspotReferenceAggregateFlags,
+                ExecuteScalarLong("PRAGMA user_version")
+                    & DbContext.HotspotReferenceAggregateFlags);
+        }
+        finally
+        {
+            DbWriter.ReferenceGraphRefreshScopeForTesting = previousScopeHook;
+        }
+
+        static FileRecord CreateTypeScriptFile(string path) => new()
+        {
+            Path = path,
+            Lang = "typescript",
+            Size = 80,
+            Lines = 4,
+            Modified = new DateTime(2025, 6, 1, 0, 0, 0, DateTimeKind.Utc),
+        };
+
+        static SymbolRecord CreateInterface(long fileId, string name) => new()
+        {
+            FileId = fileId,
+            Kind = "interface",
+            Name = name,
+            Line = 1,
+            StartLine = 1,
+            EndLine = 1,
+            Signature = $"interface {name} {{ value: number }}",
+        };
+    }
+
+    [Fact]
+    public void RebuildTypeScriptAugmentationReferences_CancellationDuringOwnedDeferredHotspotCompletionRollsBack()
+    {
+        var firstFileId = _writer.UpsertFile(CreateTypeScriptFile("src/owned-cancel-first.ts"));
+        var secondFileId = _writer.UpsertFile(CreateTypeScriptFile("src/owned-cancel-second.ts"));
+        _writer.InsertSymbols(
+        [
+            CreateInterface(firstFileId, "OwnedCancellationMerge"),
+            CreateInterface(secondFileId, "OwnedCancellationMerge"),
+        ]);
+        Assert.Equal(2, _writer.RebuildTypeScriptAugmentationReferences("."));
+
+        var referenceSnapshot = ReadAugmentationReferenceSnapshot();
+        var candidateSnapshot = ReadAugmentationCandidateSnapshot();
+        var hotspotSnapshot = ReadTypeScriptHotspotSnapshot();
+        var augmentationReady = ReadMeta(DbContext.TypeScriptAugmentationVersionMetaKey);
+        var referenceIdentityReady = ReadMeta(DbContext.ReferenceIdentityContractVersionMetaKey);
+        var userVersion = ExecuteScalarLong("PRAGMA user_version");
+        var previousDirtyFilesHook = DbWriter.DeferredHotspotDirtyFilesForTesting;
+        using var cancellation = new CancellationTokenSource();
+        var completionCount = 0;
+        try
+        {
+            DbWriter.DeferredHotspotDirtyFilesForTesting = fileIds =>
+            {
+                completionCount++;
+                previousDirtyFilesHook?.Invoke(fileIds);
+                cancellation.Cancel();
+            };
+
+            var exception = Assert.Throws<OperationCanceledException>(() =>
+                _writer.RebuildTypeScriptAugmentationReferences(
+                    ".",
+                    dirtyNames: null,
+                    cancellation.Token));
+
+            Assert.Equal(cancellation.Token, exception.CancellationToken);
+            Assert.Equal(1, completionCount);
+            Assert.Equal(referenceSnapshot, ReadAugmentationReferenceSnapshot());
+            Assert.Equal(candidateSnapshot, ReadAugmentationCandidateSnapshot());
+            Assert.Equal(hotspotSnapshot, ReadTypeScriptHotspotSnapshot());
+            Assert.Equal(
+                augmentationReady,
+                ReadMeta(DbContext.TypeScriptAugmentationVersionMetaKey));
+            Assert.Equal(
+                referenceIdentityReady,
+                ReadMeta(DbContext.ReferenceIdentityContractVersionMetaKey));
+            Assert.Equal(userVersion, ExecuteScalarLong("PRAGMA user_version"));
+            Assert.True(_writer.TypeScriptAugmentationVersionMatchesCurrent());
+            Assert.True(_writer.ReferenceIdentityContractMatchesCurrent());
+        }
+        finally
+        {
+            DbWriter.DeferredHotspotDirtyFilesForTesting = previousDirtyFilesHook;
+        }
+
+        string ReadAugmentationReferenceSnapshot() => ExecuteScalarString(
+            """
+            SELECT COALESCE(group_concat(entry, '|'), '')
+            FROM (
+                SELECT id || ':' || file_id || ':' || hex(COALESCE(symbol_name, '')) || ':' ||
+                       reference_kind || ':' || COALESCE(line, -1) || ':' ||
+                       COALESCE(column_number, -1) || ':' || hex(COALESCE(context, '')) || ':' ||
+                       hex(COALESCE(container_kind, '')) || ':' ||
+                       hex(COALESCE(container_name, '')) || ':' ||
+                       hex(COALESCE(symbol_name_folded, '')) || ':' ||
+                       hex(COALESCE(container_name_folded, '')) || ':' ||
+                       is_self_reference || ':' || is_mutual_recursion || ':' ||
+                       COALESCE(source_symbol_id, -1) || ':' ||
+                       COALESCE(target_symbol_id, -1) || ':' ||
+                       hex(COALESCE(target_symbol_key, '')) || ':' ||
+                       hex(COALESCE(resolution_state, '')) || ':' ||
+                       resolution_candidate_count AS entry
+                FROM symbol_references
+                WHERE reference_kind = 'augmentation'
+                ORDER BY id
+            )
+            """);
+
+        string ReadAugmentationCandidateSnapshot() => ExecuteScalarString(
+            """
+            SELECT COALESCE(group_concat(entry, '|'), '')
+            FROM (
+                SELECT candidate.reference_id || ':' || candidate.symbol_id || ':' ||
+                       candidate.scope_rank AS entry
+                FROM symbol_reference_candidates AS candidate
+                ORDER BY candidate.reference_id, candidate.symbol_id
+            )
+            """);
+
+        string ReadTypeScriptHotspotSnapshot() => ExecuteScalarString(
+            """
+            SELECT COALESCE(group_concat(entry, '|'), '')
+            FROM (
+                SELECT file_id || ':' || lang || ':' || hex(raw_symbol_name) || ':' ||
+                       hex(symbol_name) || ':' || symbol_segment_count || ':' ||
+                       allow_leaf_fallback || ':' || reference_count || ':' ||
+                       printf('%.17g', reference_score) AS entry
+                FROM hotspot_reference_counts
+                WHERE lang = 'typescript'
+                ORDER BY file_id, raw_symbol_name, symbol_name,
+                         symbol_segment_count, allow_leaf_fallback
+            )
+            """);
+
+        static FileRecord CreateTypeScriptFile(string path) => new()
+        {
+            Path = path,
+            Lang = "typescript",
+            Size = 80,
+            Lines = 4,
+            Modified = new DateTime(2025, 6, 1, 0, 0, 0, DateTimeKind.Utc),
+        };
+
+        static SymbolRecord CreateInterface(long fileId, string name) => new()
+        {
+            FileId = fileId,
+            Kind = "interface",
+            Name = name,
+            Line = 1,
+            StartLine = 1,
+            EndLine = 1,
+            Signature = $"interface {name} {{ value: number }}",
+        };
+    }
+
     [Fact]
     public void RebuildTypeScriptAugmentationReferences_ScopesOldAndNewDirtyNames()
     {

From a2b399264b63edf55de4172fdc081e81ddb8a9e2 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 21:24:20 +0900
Subject: [PATCH 30/45] Unify hotspot candidate query planning

---
 TESTING_GUIDE.md                              |   2 +
 .../DbSymbolReader.HotspotCandidates.cs       | 243 +++++++++++++++
 .../Database/DbSymbolReader.Hotspots.cs       | 279 ++----------------
 .../DbReaderSymbolQueryTests.cs               | 141 +++++++++
 .../CodeIndex.Tests/DbSymbolReaderSqlTests.cs |  38 ++-
 5 files changed, 429 insertions(+), 274 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbSymbolReader.HotspotCandidates.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 96fc40e88..c1c8141a3 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -202,6 +202,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   `DatabasePermissionPolicyTests.cs` injects a file-mode provider so unsupported and access-denied Unix mode operations remain deterministic and cross-platform while proving both best-effort diagnostics and strict remediation failures.
   `DbSchemaConstraintTests.cs` also locks schema constraints to `SymbolKindCatalog` and required file foreign keys so DB readiness checks fail when code enums and SQLite CHECK clauses drift.
   Hotspot ranking fixtures should use the smallest counts that cross each ranking threshold; for structural-rank tests, keep one side just above the raw-reference comparison and the other just above the symbol-count threshold instead of scaling both far beyond the boundary.
+  Hotspot candidate-filter alignment is one public database-behavior contract across site, grouped, and file list/count queries. Keep visibility include/exclude filters before ambiguity cardinality, path include/exclude and test suppression after cardinality, authoritative family identity intact, and all six result/count shapes aligned. The structural SQL fixture separately pins the shared candidate plan to its explicit ten-column projection and forbids `SELECT *`.
   Checkpoint listing and retention fixtures should exceed the relevant directory cap once and exceed the inspected-file cap on only one checkpoint; multiplying both caps together adds filesystem work without increasing boundary coverage. Checkpoint and restore-backup cleanup dry-run tests must assert both exact deleted/retained paths and the continued existence of every candidate directory. Restore dry-run tests should inject destination free space through `DbCommandRunner.AvailableFreeSpaceForTesting`, verify manifest and regular-file path diagnostics independently, and prove that no restore staging or backup directory is created.
   WAL checkpoint contention fixtures must establish a real read transaction before a later writer commit, then lower `busy_timeout` to keep the assertion bounded without fixed sleeps. Permission/error-path coverage may throw from `DbContext.WalCheckpointTruncateExecutedForTesting`; restore the previous `AsyncLocal` value in `finally` so parallel test state cannot leak.
 - `ConcurrencyTests.cs`
@@ -1264,6 +1265,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   `DatabasePermissionPolicyTests.cs` は file-mode provider を注入し、unsupported / access-denied な Unix mode 操作を deterministic かつ cross-platform に保ちながら、best-effort diagnostic と strict remediation failure の両方を検証します。
   `DbSchemaConstraintTests.cs` は DB readiness check が code enum と SQLite CHECK 句の drift を検出できるよう、schema constraint と `SymbolKindCatalog`、必須 file foreign key の同期も固定します。
   hotspot ranking fixture は各 ranking threshold を跨ぐ最小 count を使ってください。structural-rank test では、raw reference 比較をわずかに超える側と symbol-count threshold をわずかに超える側を用意し、境界から大きく離れた件数まで膨らませないでください。
+  hotspot candidate filter の整合性は、site / grouped / file の list / count 全6 query に共通する public database behavior 契約です。visibility include / exclude は ambiguity cardinality より前、path include / exclude と test suppression は cardinality より後に適用し、authoritative family identity と全6形状の結果・件数を一致させてください。structural SQL fixture は別途、共通 candidate plan の明示的な10列 projection と `SELECT *` 禁止を固定します。
   checkpoint listing / retention fixture は対象の directory cap を 1 件だけ超え、inspected-file cap は 1 checkpoint だけで超えてください。両方の cap を掛け合わせても boundary coverage は増えず、filesystem work だけが増えます。checkpoint / restore-backup cleanup の dry-run test では、削除予定・保持予定の正確な path と、全候補 directory が引き続き存在することの両方を検証してください。restore dry-run test は `DbCommandRunner.AvailableFreeSpaceForTesting` で destination free space を注入し、manifest と regular-file path の diagnostic を独立に検証し、restore staging directory や backup directory が作られないことを固定します。
   WAL checkpoint contention fixture は後続 writer commit より先に実際の read transaction を確立し、固定 sleep を使わず assertion を bounded にするため `busy_timeout` を短くします。permission / error path の coverage では `DbContext.WalCheckpointTruncateExecutedForTesting` から exception を throw できますが、parallel test state を漏らさないよう、以前の `AsyncLocal` 値を `finally` で復元してください。
 - `ConcurrencyTests.cs`
diff --git a/src/CodeIndex/Database/DbSymbolReader.HotspotCandidates.cs b/src/CodeIndex/Database/DbSymbolReader.HotspotCandidates.cs
new file mode 100644
index 000000000..6aaa21452
--- /dev/null
+++ b/src/CodeIndex/Database/DbSymbolReader.HotspotCandidates.cs
@@ -0,0 +1,243 @@
+using System.Text;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private readonly record struct SymbolHotspotCandidatePlan(
+        string Sql,
+        List<string> GraphLanguages,
+        List<string> HotspotFamilyLanguages,
+        int? CandidateLimit);
+
+    private SymbolHotspotCandidatePlan BuildSymbolHotspotCandidatePlan(
+        int? resultLimit,
+        string? kind,
+        string? lang,
+        IReadOnlyList<string>? pathPatterns,
+        IReadOnlyList<string>? excludePathPatterns,
+        bool excludeTests,
+        IReadOnlyList<string>? visibilityFilters,
+        IReadOnlyList<string>? excludeVisibilityFilters)
+    {
+        // Ambiguity is computed from the visibility-filtered language/kind candidate set
+        // before path and test filters. This prevents an out-of-scope duplicate from
+        // promoting a same-name symbol to codebase-wide counting. Cross-file grouping is
+        // allowed only for authoritative family keys in fully-ready languages.
+        // 曖昧性は visibility / language / kind 適用後、path / test 適用前に判定する。
+        // scope 外の同名定義による誤った全体集計を防ぎ、cross-file 集約は ready な family に限る。
+        var graphLanguages = new List<string>(GetWorkspaceSupportedReferenceLanguages());
+        var hotspotFamilyLanguages = new List<string>(_hotspotFamilyReadyLanguages);
+        hotspotFamilyLanguages.Sort(StringComparer.Ordinal);
+        var familyLanguageConditionSql = hotspotFamilyLanguages.Count > 0
+            ? $"f.lang IN ({BuildIndexedParameterList("hotspotFamilyLang", hotspotFamilyLanguages.Count)})"
+            : "0";
+        var familyKeySql = GetSymbolColumnSql("family_key");
+        var familyTargetKeySql = hotspotFamilyLanguages.Count > 0
+            ? $@"CASE
+                    WHEN {familyLanguageConditionSql}
+                     AND COALESCE({familyKeySql}, '') <> ''
+                        THEN 'family|' || COALESCE(f.lang, '') || '|' || COALESCE(s.kind, '') || '|' || {familyKeySql}
+                    ELSE NULL
+                END"
+            : "NULL";
+        var containerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name");
+        var containerTargetKeySql = $@"CASE
+                    WHEN COALESCE({containerQualifiedNameSql}, '') <> ''
+                        THEN 'container|' || CAST(s.file_id AS TEXT) || '|' || COALESCE(s.kind, '') || '|' || {containerQualifiedNameSql}
+                    ELSE NULL
+                END";
+        var candidateLimit = GetBoundedHotspotCandidateLimit(resultLimit);
+        var sql = new StringBuilder(capacity: 5_000);
+        sql.Append($@"
+            WITH {BuildBoundedHotspotCandidatePrefix(candidateLimit)}all_candidate_symbols AS MATERIALIZED (
+                SELECT s.id, s.file_id, s.name, s.kind, f.path, f.lang, s.line,
+                       {GetSymbolColumnSql("visibility")} AS visibility,
+                       {GetSymbolColumnSql("container_name")} AS container_name,
+                       CASE
+                           WHEN {familyTargetKeySql} IS NOT NULL
+                               THEN {familyTargetKeySql}
+                           WHEN {containerTargetKeySql} IS NOT NULL
+                               THEN {containerTargetKeySql}
+                           ELSE 'file|' || CAST(s.file_id AS TEXT)
+                       END AS logical_target_key,
+                       COALESCE({familyTargetKeySql}, {containerTargetKeySql}) AS count_safe_key
+                FROM symbols s
+                JOIN files f ON s.file_id = f.id
+                WHERE s.kind NOT IN ('import', 'namespace')");
+        sql.Append(BuildCSharpHotspotFunctionDefinitionGateSql());
+        sql.Append(BuildBoundedHotspotSymbolPredicate(candidateLimit));
+        AppendSymbolHotspotCandidateFilters(
+            sql,
+            graphLanguages,
+            kind,
+            lang,
+            visibilityFilters,
+            excludeVisibilityFilters);
+        sql.Append(@"
+            ),
+            name_cardinality AS (
+                SELECT lang,
+                       name,
+                       COUNT(*) AS defs,
+                       COUNT(DISTINCT logical_target_key) AS target_groups,
+                       COUNT(DISTINCT count_safe_key) AS count_safe_groups,
+                       COUNT(count_safe_key) AS count_safe_defs
+                FROM all_candidate_symbols
+                GROUP BY lang, name
+            ),
+            filtered_candidates AS MATERIALIZED (
+                SELECT id,
+                       file_id,
+                       name,
+                       kind,
+                       path,
+                       lang,
+                       line,
+                       visibility,
+                       container_name,
+                       logical_target_key
+                FROM all_candidate_symbols
+                WHERE 1 = 1");
+        AppendSymbolHotspotPathFilters(
+            sql,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests);
+        sql.Append(@"
+            ),");
+        return new SymbolHotspotCandidatePlan(
+            sql.ToString(),
+            graphLanguages,
+            hotspotFamilyLanguages,
+            candidateLimit);
+    }
+
+    private void AppendSymbolHotspotCandidateFilters(
+        StringBuilder sql,
+        IReadOnlyList<string> graphLanguages,
+        string? kind,
+        string? lang,
+        IReadOnlyList<string>? visibilityFilters,
+        IReadOnlyList<string>? excludeVisibilityFilters)
+    {
+        var filterSql = string.Empty;
+        if (lang != null)
+            filterSql += SymbolLanguageFileIdFilter;
+        else
+            filterSql += $" AND f.lang IN ({BuildIndexedParameterList("gl", graphLanguages.Count)})";
+        if (kind != null)
+            filterSql += " AND s.kind = @kind";
+        AppendVisibilityFilters(ref filterSql, visibilityFilters, excludeVisibilityFilters);
+        sql.Append(filterSql);
+    }
+
+    private string BuildCSharpHotspotFunctionDefinitionGateSql() =>
+        _symbolColumns.Contains("body_start_line")
+        && _symbolColumns.Contains("body_end_line")
+        && _symbolColumns.Contains("signature")
+        && _symbolColumns.Contains("container_kind")
+            ? @"
+                  AND NOT (
+                      f.lang = 'csharp'
+                      AND s.kind = 'function'
+                      AND s.container_kind = 'function'
+                      AND (
+                          (s.body_start_line IS NULL AND s.body_end_line IS NULL)
+                          OR (s.container_kind = 'function' AND COALESCE(s.signature, '') LIKE '%.' || s.name || '(%')
+                      )
+                  )"
+            : string.Empty;
+
+    private static void AppendSymbolHotspotPathFilters(
+        StringBuilder sql,
+        IReadOnlyList<string>? pathPatterns,
+        IReadOnlyList<string>? excludePathPatterns,
+        bool excludeTests)
+    {
+        if (pathPatterns is { Count: > 0 })
+        {
+            sql.Append(" AND (");
+            for (var index = 0; index < pathPatterns.Count; index++)
+            {
+                if (index > 0)
+                    sql.Append(" OR ");
+                sql.Append(BuildPathColumnFilterPredicate("path", "pathPattern", index, pathPatterns[index]));
+            }
+            sql.Append(')');
+        }
+        if (excludePathPatterns != null)
+        {
+            for (var index = 0; index < excludePathPatterns.Count; index++)
+            {
+                sql.Append(" AND NOT ");
+                sql.Append(BuildPathColumnFilterPredicate(
+                    "path",
+                    "excludePathPattern",
+                    index,
+                    excludePathPatterns[index]));
+            }
+        }
+        if (excludeTests)
+        {
+            sql.Append(" AND NOT ");
+            sql.Append(TestPathCondition.Replace("f.path", "path", StringComparison.Ordinal));
+        }
+    }
+
+    private static string BuildIndexedParameterList(string prefix, int count)
+    {
+        var parameters = new StringBuilder(count * (prefix.Length + 4));
+        for (var index = 0; index < count; index++)
+        {
+            if (index > 0)
+                parameters.Append(',');
+            parameters.Append('@');
+            parameters.Append(prefix);
+            parameters.Append(index);
+        }
+        return parameters.ToString();
+    }
+
+    private static void AddSymbolHotspotParameters(
+        SqliteCommand command,
+        SymbolHotspotRowsQuery query,
+        int? limit,
+        string? kind,
+        string? lang,
+        IReadOnlyList<string>? pathPatterns,
+        IReadOnlyList<string>? excludePathPatterns,
+        IReadOnlyList<string>? visibilityFilters,
+        IReadOnlyList<string>? excludeVisibilityFilters)
+    {
+        if (limit.HasValue)
+            SqliteCommandPolicy.Add(command, "@limit", limit.Value);
+        var candidatePlan = query.CandidatePlan;
+        if (candidatePlan.CandidateLimit.HasValue)
+        {
+            SqliteCommandPolicy.Add(
+                command,
+                "@candidateReferenceLimit",
+                candidatePlan.CandidateLimit.Value);
+        }
+        if (lang != null)
+            SqliteCommandPolicy.Add(command, "@lang", lang);
+        else
+        {
+            for (var index = 0; index < candidatePlan.GraphLanguages.Count; index++)
+                SqliteCommandPolicy.Add(command, $"@gl{index}", candidatePlan.GraphLanguages[index]);
+        }
+        if (kind != null)
+            SqliteCommandPolicy.Add(command, "@kind", kind);
+        AddPathFilterParameters(command, pathPatterns, excludePathPatterns);
+        AddVisibilityFilterParameters(command, visibilityFilters, excludeVisibilityFilters);
+        for (var index = 0; index < candidatePlan.HotspotFamilyLanguages.Count; index++)
+        {
+            SqliteCommandPolicy.Add(
+                command,
+                $"@hotspotFamilyLang{index}",
+                candidatePlan.HotspotFamilyLanguages[index]);
+        }
+    }
+}
diff --git a/src/CodeIndex/Database/DbSymbolReader.Hotspots.cs b/src/CodeIndex/Database/DbSymbolReader.Hotspots.cs
index 83db8b866..613c985c0 100644
--- a/src/CodeIndex/Database/DbSymbolReader.Hotspots.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.Hotspots.cs
@@ -11,115 +11,18 @@ public partial class DbReader
 {
     private SymbolHotspotRowsQuery BuildGroupedSymbolHotspotRowsQuery(int? resultLimit, string? kind, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests, IReadOnlyList<string>? visibilityFilters, IReadOnlyList<string>? excludeVisibilityFilters)
     {
-        var containerNameSql = GetSymbolColumnSql("container_name");
-        var containerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name");
-        var familyKeySql = GetSymbolColumnSql("family_key");
-        var hotspotFamilyLangs = _hotspotFamilyReadyLanguages
-            .OrderBy(value => value, StringComparer.Ordinal)
-            .ToList();
-        var familyLangConditionSql = hotspotFamilyLangs.Count > 0
-            ? $"f.lang IN ({string.Join(",", hotspotFamilyLangs.Select((_, i) => $"@hotspotFamilyLang{i}"))})"
-            : "0";
-        var familyTargetKeySql = hotspotFamilyLangs.Count > 0
-            ? $@"CASE
-                    WHEN {familyLangConditionSql}
-                     AND COALESCE({familyKeySql}, '') <> ''
-                        THEN 'family|' || COALESCE(f.lang, '') || '|' || COALESCE(s.kind, '') || '|' || {familyKeySql}
-                    ELSE NULL
-                END"
-            : "NULL";
-        var containerTargetKeySql = $@"CASE
-                    WHEN COALESCE({containerQualifiedNameSql}, '') <> ''
-                        THEN 'container|' || CAST(s.file_id AS TEXT) || '|' || COALESCE(s.kind, '') || '|' || {containerQualifiedNameSql}
-                    ELSE NULL
-                END";
-        var csharpFunctionDefinitionGateSql = _symbolColumns.Contains("body_start_line")
-            && _symbolColumns.Contains("body_end_line")
-            && _symbolColumns.Contains("signature")
-            && _symbolColumns.Contains("container_kind")
-            ? @"
-                  AND NOT (
-                      f.lang = 'csharp'
-                      AND s.kind = 'function'
-                      AND s.container_kind = 'function'
-                      AND (
-                          (s.body_start_line IS NULL AND s.body_end_line IS NULL)
-                          OR (s.container_kind = 'function' AND COALESCE(s.signature, '') LIKE '%.' || s.name || '(%')
-                      )
-                  )"
-            : string.Empty;
-        var graphLangs = GetWorkspaceSupportedReferenceLanguages().ToList();
-        var candidateLimit = GetBoundedHotspotCandidateLimit(resultLimit);
-        var boundedCandidatePrefix = BuildBoundedHotspotCandidatePrefix(candidateLimit);
-        var boundedSymbolPredicate = BuildBoundedHotspotSymbolPredicate(candidateLimit);
-        var sql = $@"
-            WITH {boundedCandidatePrefix}all_candidate_symbols AS MATERIALIZED (
-                SELECT s.id, s.file_id, s.name, s.kind, f.path, f.lang, s.line,
-                       {GetSymbolColumnSql("visibility")} AS visibility,
-                       {containerNameSql} AS container_name,
-                       CASE
-                           WHEN {familyTargetKeySql} IS NOT NULL
-                               THEN {familyTargetKeySql}
-                           WHEN {containerTargetKeySql} IS NOT NULL
-                               THEN {containerTargetKeySql}
-                           ELSE 'file|' || CAST(s.file_id AS TEXT)
-                       END AS logical_target_key,
-                       COALESCE({familyTargetKeySql}, {containerTargetKeySql}) AS count_safe_key
-                FROM symbols s
-                JOIN files f ON s.file_id = f.id
-                WHERE s.kind NOT IN ('import', 'namespace')" + csharpFunctionDefinitionGateSql + boundedSymbolPredicate;
-
-        if (lang != null)
-            sql += SymbolLanguageFileIdFilter;
-        else
-            sql += $" AND f.lang IN ({string.Join(",", graphLangs.Select((_, i) => $"@gl{i}"))})";
-        if (kind != null)
-            sql += " AND s.kind = @kind";
-        AppendVisibilityFilters(ref sql, visibilityFilters, excludeVisibilityFilters);
-
-        sql += @"
-            ),
-            name_cardinality AS (
-                SELECT lang,
-                       name,
-                       COUNT(*) AS defs,
-                       COUNT(DISTINCT logical_target_key) AS target_groups,
-                       COUNT(DISTINCT count_safe_key) AS count_safe_groups,
-                       COUNT(count_safe_key) AS count_safe_defs
-                FROM all_candidate_symbols
-                GROUP BY lang, name
-            ),
-            filtered_candidates AS MATERIALIZED (
-                SELECT id,
-                       file_id,
-                       name,
-                       kind,
-                       path,
-                       lang,
-                       line,
-                       visibility,
-                       container_name,
-                       logical_target_key
-                FROM all_candidate_symbols
-                WHERE 1 = 1";
-        if (pathPatterns is { Count: > 0 })
-        {
-            var ors = new List<string>(pathPatterns.Count);
-            for (int i = 0; i < pathPatterns.Count; i++)
-                ors.Add(BuildPathColumnFilterPredicate("path", "pathPattern", i, pathPatterns[i]));
-            sql += " AND (" + string.Join(" OR ", ors) + ")";
-        }
-        if (excludePathPatterns != null)
-        {
-            for (int i = 0; i < excludePathPatterns.Count; i++)
-                sql += $" AND NOT {BuildPathColumnFilterPredicate("path", "excludePathPattern", i, excludePathPatterns[i])}";
-        }
-        if (excludeTests)
-            sql += $" AND NOT {TestPathCondition.Replace("f.path", "path")}";
-        sql += @"
-            ),
+        var candidatePlan = BuildSymbolHotspotCandidatePlan(
+            resultLimit,
+            kind,
+            lang,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            visibilityFilters,
+            excludeVisibilityFilters);
+        var sql = candidatePlan.Sql + @"
             logical_references AS MATERIALIZED (
-                " + BuildHotspotLogicalReferenceRowsSql(includeLeafMetadata: false, boundedCandidates: candidateLimit.HasValue) + @"
+                " + BuildHotspotLogicalReferenceRowsSql(includeLeafMetadata: false, boundedCandidates: candidatePlan.CandidateLimit.HasValue) + @"
             ),
             file_reference_counts AS MATERIALIZED (
                 SELECT lang,
@@ -296,7 +199,7 @@ JOIN grouped_reference_counts grc
                 GROUP BY hs.name, hs.kind
             )";
 
-        return new SymbolHotspotRowsQuery(sql, graphLangs, hotspotFamilyLangs, candidateLimit);
+        return new SymbolHotspotRowsQuery(sql, candidatePlan);
     }
 
     public HotspotCountResult CountGroupedSymbolHotspots(string? kind, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null)
@@ -883,125 +786,16 @@ WHERE rc.ref_count > 0
 
     private SymbolHotspotRowsQuery BuildSymbolHotspotRowsQuery(int? resultLimit, string? kind, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests, IReadOnlyList<string>? visibilityFilters, IReadOnlyList<string>? excludeVisibilityFilters)
     {
-        var containerNameSql = GetSymbolColumnSql("container_name");
-        var containerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name");
-        var familyKeySql = GetSymbolColumnSql("family_key");
-        var hotspotFamilyLangs = _hotspotFamilyReadyLanguages
-            .OrderBy(value => value, StringComparer.Ordinal)
-            .ToList();
-        var familyLangConditionSql = hotspotFamilyLangs.Count > 0
-            ? $"f.lang IN ({string.Join(",", hotspotFamilyLangs.Select((_, i) => $"@hotspotFamilyLang{i}"))})"
-            : "0";
-        var familyTargetKeySql = hotspotFamilyLangs.Count > 0
-            ? $@"CASE
-                    WHEN {familyLangConditionSql}
-                     AND COALESCE({familyKeySql}, '') <> ''
-                        THEN 'family|' || COALESCE(f.lang, '') || '|' || COALESCE(s.kind, '') || '|' || {familyKeySql}
-                    ELSE NULL
-                END"
-            : "NULL";
-        var containerTargetKeySql = $@"CASE
-                    WHEN COALESCE({containerQualifiedNameSql}, '') <> ''
-                        THEN 'container|' || CAST(s.file_id AS TEXT) || '|' || COALESCE(s.kind, '') || '|' || {containerQualifiedNameSql}
-                    ELSE NULL
-                END";
-        var csharpFunctionDefinitionGateSql = _symbolColumns.Contains("body_start_line")
-            && _symbolColumns.Contains("body_end_line")
-            && _symbolColumns.Contains("signature")
-            && _symbolColumns.Contains("container_kind")
-            ? @"
-                  AND NOT (
-                      f.lang = 'csharp'
-                      AND s.kind = 'function'
-                      AND s.container_kind = 'function'
-                      AND (
-                          (s.body_start_line IS NULL AND s.body_end_line IS NULL)
-                          OR (s.container_kind = 'function' AND COALESCE(s.signature, '') LIKE '%.' || s.name || '(%')
-                      )
-                  )"
-            : string.Empty;
-        // Ambiguity is computed from the unscoped language/kind candidate set so `--path`
-        // cannot hide an out-of-scope duplicate and accidentally promote a same-name symbol
-        // back to codebase-wide counting. Cross-file grouping is allowed only when the
-        // extractor persisted an authoritative family key on a DB that is stamped as fully
-        // current for hotspot-family semantics (currently partial-type families). Same-file
-        // same-container overloads can still share one conservative target key, but only
-        // unique names or authoritative families may promote to codebase-wide counts.
-        // 曖昧性は path 非依存の候補集合で判定し、`--path` で隠れた重複定義が一意扱いに
-        // 戻ってしまうことを防ぐ。cross-file の集約は current な hotspot-family semantics で
-        // fully-ready と判定された DB 上の正式な family key のみに限定し、same-file の
-        // same-container overload は保守的な target として扱いつつ、codebase-wide 集計への
-        // 昇格は一意名か authoritative family のみに限定する。
-        var candidateLimit = GetBoundedHotspotCandidateLimit(resultLimit);
-        var boundedCandidatePrefix = BuildBoundedHotspotCandidatePrefix(candidateLimit);
-        var boundedSymbolPredicate = BuildBoundedHotspotSymbolPredicate(candidateLimit);
-        var sql = $@"
-            WITH {boundedCandidatePrefix}all_candidate_symbols AS MATERIALIZED (
-                SELECT s.id, s.file_id, s.name, s.kind, f.path, f.lang, s.line,
-                       {GetSymbolColumnSql("visibility")} AS visibility,
-                       {containerNameSql} AS container_name,
-                       CASE
-                           WHEN {familyTargetKeySql} IS NOT NULL
-                               THEN {familyTargetKeySql}
-                           WHEN {containerTargetKeySql} IS NOT NULL
-                               THEN {containerTargetKeySql}
-                           ELSE 'file|' || CAST(s.file_id AS TEXT)
-                       END AS logical_target_key,
-                       COALESCE({familyTargetKeySql}, {containerTargetKeySql}) AS count_safe_key
-                FROM symbols s
-                JOIN files f ON s.file_id = f.id
-                WHERE s.kind NOT IN ('import', 'namespace')" + csharpFunctionDefinitionGateSql + boundedSymbolPredicate;
-
-        var graphLangs = GetWorkspaceSupportedReferenceLanguages().ToList();
-        if (lang != null)
-            sql += SymbolLanguageFileIdFilter;
-        else
-            sql += $" AND f.lang IN ({string.Join(",", graphLangs.Select((_, i) => $"@gl{i}"))})";
-        if (kind != null)
-            sql += " AND s.kind = @kind";
-        AppendVisibilityFilters(ref sql, visibilityFilters, excludeVisibilityFilters);
-
-        sql += @"
-            ),
-            name_cardinality AS (
-                SELECT lang,
-                       name,
-                       COUNT(*) AS defs,
-                       COUNT(DISTINCT logical_target_key) AS target_groups,
-                       COUNT(DISTINCT count_safe_key) AS count_safe_groups,
-                       COUNT(count_safe_key) AS count_safe_defs
-                FROM all_candidate_symbols
-                GROUP BY lang, name
-            ),
-            filtered_candidates AS MATERIALIZED (
-                SELECT id,
-                       file_id,
-                       name,
-                       kind,
-                       path,
-                       lang,
-                       line,
-                       visibility,
-                       container_name,
-                       logical_target_key
-                FROM all_candidate_symbols
-                WHERE 1 = 1";
-        if (pathPatterns != null && pathPatterns.Count > 0)
-        {
-            var ors = new List<string>(pathPatterns.Count);
-            for (int i = 0; i < pathPatterns.Count; i++)
-                ors.Add(BuildPathColumnFilterPredicate("path", "pathPattern", i, pathPatterns[i]));
-            sql += " AND (" + string.Join(" OR ", ors) + ")";
-        }
-        if (excludePathPatterns != null)
-        {
-            for (int i = 0; i < excludePathPatterns.Count; i++)
-                sql += $" AND NOT {BuildPathColumnFilterPredicate("path", "excludePathPattern", i, excludePathPatterns[i])}";
-        }
-        if (excludeTests)
-            sql += $" AND NOT {TestPathCondition.Replace("f.path", "path")}";
-        sql += @"
-            ),
+        var candidatePlan = BuildSymbolHotspotCandidatePlan(
+            resultLimit,
+            kind,
+            lang,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            visibilityFilters,
+            excludeVisibilityFilters);
+        var sql = candidatePlan.Sql + @"
             grouped_candidates AS (
                 SELECT MIN(id) AS symbol_id,
                        name,
@@ -1043,7 +837,7 @@ JOIN grouped_metadata gm
                  AND gm.kind = gc.kind
             ),
             logical_references AS MATERIALIZED (
-                " + BuildHotspotLogicalReferenceRowsSql(includeLeafMetadata: true, boundedCandidates: candidateLimit.HasValue) + @"
+                " + BuildHotspotLogicalReferenceRowsSql(includeLeafMetadata: true, boundedCandidates: candidatePlan.CandidateLimit.HasValue) + @"
             ),
             file_reference_counts_exact AS MATERIALIZED (
                 SELECT lang,
@@ -1223,35 +1017,12 @@ file_symbol_counts AS (
                 FROM filtered_candidates
                 GROUP BY path, COALESCE(lang, '')
             )";
-        return new SymbolHotspotRowsQuery(sql, graphLangs, hotspotFamilyLangs, candidateLimit);
-    }
-
-    private static void AddSymbolHotspotParameters(SqliteCommand command, SymbolHotspotRowsQuery query, int? limit, string? kind, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, IReadOnlyList<string>? visibilityFilters, IReadOnlyList<string>? excludeVisibilityFilters)
-    {
-        if (limit.HasValue)
-            SqliteCommandPolicy.Add(command, "@limit", limit.Value);
-        if (query.CandidateLimit.HasValue)
-            SqliteCommandPolicy.Add(command, "@candidateReferenceLimit", query.CandidateLimit.Value);
-        if (lang != null)
-            SqliteCommandPolicy.Add(command, "@lang", lang);
-        else
-        {
-            for (int i = 0; i < query.GraphLanguages.Count; i++)
-                SqliteCommandPolicy.Add(command, $"@gl{i}", query.GraphLanguages[i]);
-        }
-        if (kind != null)
-            SqliteCommandPolicy.Add(command, "@kind", kind);
-        AddPathFilterParameters(command, pathPatterns, excludePathPatterns);
-        AddVisibilityFilterParameters(command, visibilityFilters, excludeVisibilityFilters);
-        for (int i = 0; i < query.HotspotFamilyLanguages.Count; i++)
-            SqliteCommandPolicy.Add(command, $"@hotspotFamilyLang{i}", query.HotspotFamilyLanguages[i]);
+        return new SymbolHotspotRowsQuery(sql, candidatePlan);
     }
 
     private sealed record SymbolHotspotRowsQuery(
         string Sql,
-        List<string> GraphLanguages,
-        List<string> HotspotFamilyLanguages,
-        int? CandidateLimit);
+        SymbolHotspotCandidatePlan CandidatePlan);
 
     private static HotspotCountResult ExecuteHotspotCountSummary(SqliteCommand command)
     {
diff --git a/tests/CodeIndex.Tests/DbReaderSymbolQueryTests.cs b/tests/CodeIndex.Tests/DbReaderSymbolQueryTests.cs
index 9cff7d2e1..6295dc459 100644
--- a/tests/CodeIndex.Tests/DbReaderSymbolQueryTests.cs
+++ b/tests/CodeIndex.Tests/DbReaderSymbolQueryTests.cs
@@ -9,6 +9,147 @@ namespace CodeIndex.Tests;
 
 public partial class DbReaderTests
 {
+    [Fact]
+    public void HotspotCandidateFilters_StayAlignedAcrossSiteGroupedFileAndCountQueries()
+    {
+        var alphaFileId = CreateFile("src/hotspot_alignment/alpha.cs");
+        var betaFileId = CreateFile("src/hotspot_alignment/beta.cs");
+        var privateFileId = CreateFile("src/hotspot_alignment/private.cs");
+        var excludedFileId = CreateFile("src/hotspot_alignment/excluded/duplicate.cs");
+        var testFileId = CreateFile("tests/hotspot_alignment/duplicate.cs");
+        var outsideFileId = CreateFile("other/hotspot_alignment/duplicate.cs");
+        var callerFileId = CreateFile("callers/hotspot_alignment/caller.cs");
+        _writer.InsertSymbols(
+        [
+            CreateFunction(alphaFileId, "VisibilityAlignedHotspot", "public"),
+            CreateFunction(privateFileId, "VisibilityAlignedHotspot", "private"),
+            CreateFunction(alphaFileId, "PathAmbiguousHotspot", "public", line: 3),
+            CreateFunction(outsideFileId, "PathAmbiguousHotspot", "public"),
+            CreateFunction(alphaFileId, "ExcludedPathAmbiguousHotspot", "public", line: 5),
+            CreateFunction(excludedFileId, "ExcludedPathAmbiguousHotspot", "public"),
+            CreateFunction(betaFileId, "TestAmbiguousHotspot", "public"),
+            CreateFunction(testFileId, "TestAmbiguousHotspot", "public"),
+            CreateFunction(betaFileId, "BetaUniqueHotspot", "public", line: 3),
+            CreateFunction(alphaFileId, "FamilyAlignedHotspot", "public", line: 7, familyKey: "alignment-family"),
+            CreateFunction(betaFileId, "FamilyAlignedHotspot", "public", line: 5, familyKey: "alignment-family"),
+        ]);
+
+        var references = new List<ReferenceRecord>();
+        AddReferences(references, alphaFileId, "VisibilityAlignedHotspot", 1);
+        AddReferences(references, callerFileId, "VisibilityAlignedHotspot", 2);
+        AddReferences(references, alphaFileId, "PathAmbiguousHotspot", 1);
+        AddReferences(references, callerFileId, "PathAmbiguousHotspot", 2);
+        AddReferences(references, outsideFileId, "PathAmbiguousHotspot", 1);
+        AddReferences(references, alphaFileId, "ExcludedPathAmbiguousHotspot", 1);
+        AddReferences(references, callerFileId, "ExcludedPathAmbiguousHotspot", 2);
+        AddReferences(references, excludedFileId, "ExcludedPathAmbiguousHotspot", 1);
+        AddReferences(references, betaFileId, "TestAmbiguousHotspot", 1);
+        AddReferences(references, callerFileId, "TestAmbiguousHotspot", 2);
+        AddReferences(references, testFileId, "TestAmbiguousHotspot", 1);
+        AddReferences(references, callerFileId, "BetaUniqueHotspot", 2);
+        AddReferences(references, callerFileId, "FamilyAlignedHotspot", 3);
+        _writer.InsertReferences(references);
+
+        string[] includedPaths = ["src/hotspot_alignment/*", "tests/hotspot_alignment/*"];
+        string[] excludedPaths = ["src/hotspot_alignment/excluded/*"];
+        string[] includedVisibilities = ["public", "private"];
+        string[] excludedVisibilities = ["private"];
+        var sites = _reader.GetSymbolHotspots(
+            20, "function", "csharp", includedPaths, excludedPaths, excludeTests: true,
+            includedVisibilities, excludedVisibilities);
+        var grouped = _reader.GetGroupedSymbolHotspots(
+            20, "function", "csharp", includedPaths, excludedPaths, excludeTests: true,
+            includedVisibilities, excludedVisibilities);
+        var files = _reader.GetFileSymbolHotspots(
+            20, "function", "csharp", includedPaths, excludedPaths, excludeTests: true,
+            includedVisibilities, excludedVisibilities);
+        var siteCount = _reader.CountSymbolHotspots(
+            "function", "csharp", includedPaths, excludedPaths, excludeTests: true,
+            includedVisibilities, excludedVisibilities);
+        var groupedCount = _reader.CountGroupedSymbolHotspots(
+            "function", "csharp", includedPaths, excludedPaths, excludeTests: true,
+            includedVisibilities, excludedVisibilities);
+        var fileCount = _reader.CountFileSymbolHotspots(
+            "function", "csharp", includedPaths, excludedPaths, excludeTests: true,
+            includedVisibilities, excludedVisibilities);
+
+        Assert.Equal(6, sites.Count);
+        Assert.Equal(6, grouped.Count);
+        Assert.Equal(2, files.Count);
+        Assert.Equal(new HotspotCountResult(6, 2), siteCount);
+        Assert.Equal(new HotspotCountResult(6, 2, 7), groupedCount);
+        Assert.Equal(new HotspotCountResult(2, 2), fileCount);
+        Assert.Equal(
+            sites.Select(result => result.Symbol.Name).Order(StringComparer.Ordinal),
+            grouped.Select(result => result.Symbol.Name).Order(StringComparer.Ordinal));
+        Assert.Equal(
+            sites.Select(result => result.Symbol.Path).Distinct(StringComparer.Ordinal).Order(StringComparer.Ordinal),
+            files.Select(result => result.Path).Order(StringComparer.Ordinal));
+        Assert.Equal(3, Site("VisibilityAlignedHotspot").ReferenceCount);
+        Assert.Equal(1, Site("PathAmbiguousHotspot").ReferenceCount);
+        Assert.Equal(1, Site("ExcludedPathAmbiguousHotspot").ReferenceCount);
+        Assert.Equal(1, Site("TestAmbiguousHotspot").ReferenceCount);
+        Assert.Equal(2, Site("BetaUniqueHotspot").ReferenceCount);
+        Assert.Equal(3, Site("FamilyAlignedHotspot").ReferenceCount);
+        Assert.Equal(2, Group("FamilyAlignedHotspot").DefinitionSites);
+
+        SymbolHotspotResult Site(string name) => Assert.Single(
+            sites,
+            result => result.Symbol.Name == name);
+        GroupedHotspotResult Group(string name) => Assert.Single(
+            grouped,
+            result => result.Symbol.Name == name);
+
+        long CreateFile(string path) => _writer.UpsertFile(new FileRecord
+        {
+            Path = path,
+            Lang = "csharp",
+            Size = 100,
+            Lines = 20,
+            Modified = new DateTime(2025, 6, 1, 0, 0, 0, DateTimeKind.Utc),
+        });
+
+        static SymbolRecord CreateFunction(
+            long fileId,
+            string name,
+            string visibility,
+            int line = 1,
+            string? familyKey = null) => new()
+            {
+                FileId = fileId,
+                Kind = "function",
+                Name = name,
+                Line = line,
+                StartLine = line,
+                EndLine = line + 1,
+                BodyStartLine = line + 1,
+                BodyEndLine = line + 1,
+                Signature = $"{visibility} void {name}()",
+                Visibility = visibility,
+                FamilyKey = familyKey,
+            };
+
+        static void AddReferences(
+            List<ReferenceRecord> destination,
+            long fileId,
+            string name,
+            int count)
+        {
+            for (var index = 0; index < count; index++)
+            {
+                destination.Add(new ReferenceRecord
+                {
+                    FileId = fileId,
+                    SymbolName = name,
+                    ReferenceKind = "call",
+                    Line = 10 + index,
+                    Column = 5,
+                    Context = name + "();",
+                });
+            }
+        }
+    }
+
     [Fact]
     public void GetSymbolHotspots_RanksRealCallsAboveManyLowerWeightSubscribeEdges()
     {
diff --git a/tests/CodeIndex.Tests/DbSymbolReaderSqlTests.cs b/tests/CodeIndex.Tests/DbSymbolReaderSqlTests.cs
index 0c02c2233..d0e2ef1e7 100644
--- a/tests/CodeIndex.Tests/DbSymbolReaderSqlTests.cs
+++ b/tests/CodeIndex.Tests/DbSymbolReaderSqlTests.cs
@@ -5,29 +5,27 @@ public class DbSymbolReaderSqlTests
     [Fact]
     public void HotspotFilteredCandidates_UseExplicitProjection()
     {
-        var source = RepositoryTestPaths.ReadText("src", "CodeIndex", "Database", "DbSymbolReader.Hotspots.cs");
-        var filteredBlocks = source
+        var source = RepositoryTestPaths.ReadText(
+            "src",
+            "CodeIndex",
+            "Database",
+            "DbSymbolReader.HotspotCandidates.cs");
+        var filteredBlock = Assert.Single(source
             .Replace("filtered_candidates AS MATERIALIZED (", "filtered_candidates AS (", StringComparison.Ordinal)
             .Split("filtered_candidates AS (", StringSplitOptions.None)
-            .Skip(1)
-            .ToList();
+            .Skip(1));
 
-        Assert.Equal(2, filteredBlocks.Count);
-        foreach (var block in filteredBlocks)
-        {
-            var projection = block[..block.IndexOf("FROM all_candidate_symbols", StringComparison.Ordinal)];
-            Assert.DoesNotContain("SELECT *", projection, StringComparison.Ordinal);
-            Assert.Contains("SELECT id,", projection, StringComparison.Ordinal);
-            Assert.Contains("file_id,", projection, StringComparison.Ordinal);
-            Assert.Contains("name,", projection, StringComparison.Ordinal);
-            Assert.Contains("kind,", projection, StringComparison.Ordinal);
-            Assert.Contains("path,", projection, StringComparison.Ordinal);
-            Assert.Contains("lang,", projection, StringComparison.Ordinal);
-            Assert.Contains("line,", projection, StringComparison.Ordinal);
-            Assert.Contains("visibility,", projection, StringComparison.Ordinal);
-            Assert.Contains("container_name,", projection, StringComparison.Ordinal);
-            Assert.Contains("logical_target_key", projection, StringComparison.Ordinal);
-        }
+        var projection = filteredBlock[..filteredBlock.IndexOf(
+            "FROM all_candidate_symbols",
+            StringComparison.Ordinal)];
+        Assert.DoesNotContain("SELECT *", projection, StringComparison.Ordinal);
+        Assert.Equal(
+            "SELECT id, file_id, name, kind, path, lang, line, visibility, container_name, logical_target_key",
+            string.Join(
+                ' ',
+                projection.Split(
+                    (char[]?)null,
+                    StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)));
     }
 
 }

From 0f12a59a887d200005ea1b84bca9ba7f3eff150a Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 21:55:41 +0900
Subject: [PATCH 31/45] Unify unused symbol candidate queries

---
 TESTING_GUIDE.md                              |   2 +
 ...DbSymbolReader.UnusedSymbols.Candidates.cs | 403 +++++++++++++++++
 .../Database/DbSymbolReader.UnusedSymbols.cs  | 420 +-----------------
 .../DbReaderUnusedCandidateQueryTests.cs      | 146 ++++++
 4 files changed, 564 insertions(+), 407 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Candidates.cs
 create mode 100644 tests/CodeIndex.Tests/DbReaderUnusedCandidateQueryTests.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index c1c8141a3..3d6c5fa46 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -203,6 +203,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   `DbSchemaConstraintTests.cs` also locks schema constraints to `SymbolKindCatalog` and required file foreign keys so DB readiness checks fail when code enums and SQLite CHECK clauses drift.
   Hotspot ranking fixtures should use the smallest counts that cross each ranking threshold; for structural-rank tests, keep one side just above the raw-reference comparison and the other just above the symbol-count threshold instead of scaling both far beyond the boundary.
   Hotspot candidate-filter alignment is one public database-behavior contract across site, grouped, and file list/count queries. Keep visibility include/exclude filters before ambiguity cardinality, path include/exclude and test suppression after cardinality, authoritative family identity intact, and all six result/count shapes aligned. The structural SQL fixture separately pins the shared candidate plan to its explicit ten-column projection and forbids `SELECT *`.
+  Unused-candidate query coverage must keep the SQL-aware and non-SQL paths aligned on the shared 17-column projection, provisional bucket ordering, scope filters, and parameter binding. Retain one mixed C#/SQL public-behavior fixture that proves SQL reference resolution, C# projection and null fallbacks, list/count agreement, and detailed bucket counts together; keep same-file/partial C# suppression and enum-collision scope in their focused fixtures.
   Checkpoint listing and retention fixtures should exceed the relevant directory cap once and exceed the inspected-file cap on only one checkpoint; multiplying both caps together adds filesystem work without increasing boundary coverage. Checkpoint and restore-backup cleanup dry-run tests must assert both exact deleted/retained paths and the continued existence of every candidate directory. Restore dry-run tests should inject destination free space through `DbCommandRunner.AvailableFreeSpaceForTesting`, verify manifest and regular-file path diagnostics independently, and prove that no restore staging or backup directory is created.
   WAL checkpoint contention fixtures must establish a real read transaction before a later writer commit, then lower `busy_timeout` to keep the assertion bounded without fixed sleeps. Permission/error-path coverage may throw from `DbContext.WalCheckpointTruncateExecutedForTesting`; restore the previous `AsyncLocal` value in `finally` so parallel test state cannot leak.
 - `ConcurrencyTests.cs`
@@ -1266,6 +1267,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   `DbSchemaConstraintTests.cs` は DB readiness check が code enum と SQLite CHECK 句の drift を検出できるよう、schema constraint と `SymbolKindCatalog`、必須 file foreign key の同期も固定します。
   hotspot ranking fixture は各 ranking threshold を跨ぐ最小 count を使ってください。structural-rank test では、raw reference 比較をわずかに超える側と symbol-count threshold をわずかに超える側を用意し、境界から大きく離れた件数まで膨らませないでください。
   hotspot candidate filter の整合性は、site / grouped / file の list / count 全6 query に共通する public database behavior 契約です。visibility include / exclude は ambiguity cardinality より前、path include / exclude と test suppression は cardinality より後に適用し、authoritative family identity と全6形状の結果・件数を一致させてください。structural SQL fixture は別途、共通 candidate plan の明示的な10列 projection と `SELECT *` 禁止を固定します。
+  unused candidate query の coverage では、SQL-aware / non-SQL 経路で共通の17列 projection、provisional bucket 順、scope filter、parameter binding を一致させてください。mixed C#/SQL の public behavior fixture 1つで SQL reference resolution、C# projection と null fallback、list/count の一致、詳細 bucket count をまとめて固定し、same-file / partial C# suppression と enum collision scope は焦点を絞った既存 fixture で維持します。
   checkpoint listing / retention fixture は対象の directory cap を 1 件だけ超え、inspected-file cap は 1 checkpoint だけで超えてください。両方の cap を掛け合わせても boundary coverage は増えず、filesystem work だけが増えます。checkpoint / restore-backup cleanup の dry-run test では、削除予定・保持予定の正確な path と、全候補 directory が引き続き存在することの両方を検証してください。restore dry-run test は `DbCommandRunner.AvailableFreeSpaceForTesting` で destination free space を注入し、manifest と regular-file path の diagnostic を独立に検証し、restore staging directory や backup directory が作られないことを固定します。
   WAL checkpoint contention fixture は後続 writer commit より先に実際の read transaction を確立し、固定 sleep を使わず assertion を bounded にするため `busy_timeout` を短くします。permission / error path の coverage では `DbContext.WalCheckpointTruncateExecutedForTesting` から exception を throw できますが、parallel test state を漏らさないよう、以前の `AsyncLocal` 値を `finally` で復元してください。
 - `ConcurrencyTests.cs`
diff --git a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Candidates.cs b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Candidates.cs
new file mode 100644
index 000000000..d1309325c
--- /dev/null
+++ b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Candidates.cs
@@ -0,0 +1,403 @@
+using System.Text;
+using Microsoft.Data.Sqlite;
+
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private sealed class UnusedCandidateSymbol
+    {
+        public long FileId { get; init; }
+        public string Path { get; init; } = string.Empty;
+        public string? Lang { get; init; }
+        public string Kind { get; init; } = string.Empty;
+        public string Name { get; init; } = string.Empty;
+        public int Line { get; init; }
+        public int StartLine { get; init; }
+        public int EndLine { get; init; }
+        public string? Signature { get; init; }
+        public string? Visibility { get; init; }
+        public string? ReturnType { get; init; }
+        public string? ContainerKind { get; init; }
+        public string? ContainerName { get; init; }
+        public string? ContainerQualifiedName { get; init; }
+        public bool IsPublicOrExported { get; init; }
+        public bool IsReflectionOrConfigSuspect { get; init; }
+    }
+
+    private readonly record struct UnusedCandidateScope(
+        string? Kind,
+        string? Lang,
+        IReadOnlyList<string>? PathPatterns,
+        IReadOnlyList<string>? ExcludePathPatterns,
+        bool ExcludeTests,
+        IReadOnlyList<string>? VisibilityFilters,
+        IReadOnlyList<string>? ExcludeVisibilityFilters);
+
+    private readonly record struct UnusedCandidateQueryPlan(
+        string Sql,
+        IReadOnlyList<string> GraphLanguages);
+
+    private readonly record struct UnusedCandidateBucketSql(
+        string IsPublicOrExported,
+        string IsReflectionOrConfigSuspect,
+        string ProvisionalOrder);
+
+    private const string UnusedCandidateColumns =
+        "file_id, path, lang, kind, name, line, start_line, end_line, signature, visibility, " +
+        "return_type, container_kind, container_name, container_qualified_name, " +
+        "is_public_or_exported, is_reflection_or_config_suspect, provisional_bucket_order";
+
+    private List<UnusedSymbolResult> FetchUnusedCandidates(
+        int fetchLimit,
+        int provisionalBucketOrder,
+        int offset,
+        string? kind,
+        string? lang,
+        IReadOnlyList<string>? pathPatterns,
+        IReadOnlyList<string>? excludePathPatterns,
+        bool excludeTests,
+        IReadOnlyList<string>? visibilityFilters = null,
+        IReadOnlyList<string>? excludeVisibilityFilters = null)
+    {
+        var scope = new UnusedCandidateScope(
+            kind, lang, pathPatterns, excludePathPatterns, excludeTests,
+            visibilityFilters, excludeVisibilityFilters);
+        var plan = BuildUnusedCandidatePageQuery(scope, resolveSqlReferences: true);
+        using var cmd = _conn.CreateCommand();
+        cmd.CommandText = plan.Sql;
+        AddUnusedCandidatePageParameters(cmd, plan, scope, provisionalBucketOrder, fetchLimit, offset);
+
+        var results = new List<UnusedSymbolResult>();
+        using var reader = cmd.ExecuteTrackedReader();
+        while (reader.TrackedRead())
+            results.Add(CreateUnusedSymbolResult(ReadUnusedCandidate(reader)));
+        return results;
+    }
+
+    private List<UnusedCandidateSymbol> FetchUnusedCandidateSymbols(
+        int fetchLimit,
+        int offset,
+        int provisionalBucketOrder,
+        string? kind,
+        string? lang,
+        IReadOnlyList<string>? pathPatterns,
+        IReadOnlyList<string>? excludePathPatterns,
+        bool excludeTests,
+        IReadOnlyList<string>? visibilityFilters = null,
+        IReadOnlyList<string>? excludeVisibilityFilters = null)
+    {
+        var scope = new UnusedCandidateScope(
+            kind, lang, pathPatterns, excludePathPatterns, excludeTests,
+            visibilityFilters, excludeVisibilityFilters);
+        var plan = BuildUnusedCandidatePageQuery(scope, resolveSqlReferences: false);
+        using var cmd = _conn.CreateCommand();
+        cmd.CommandText = plan.Sql;
+        AddUnusedCandidatePageParameters(cmd, plan, scope, provisionalBucketOrder, fetchLimit, offset);
+
+        var candidates = new List<UnusedCandidateSymbol>();
+        using var reader = cmd.ExecuteTrackedReader();
+        while (reader.TrackedRead())
+            candidates.Add(ReadUnusedCandidate(reader));
+        return candidates;
+    }
+
+    private QueryCountResult CountUnusedCandidates(UnusedCandidateScope scope)
+    {
+        var plan = BuildUnusedCandidateCountQuery(scope);
+        using var cmd = _conn.CreateCommand();
+        cmd.CommandText = plan.Sql;
+        AddUnusedCandidateScopeParameters(cmd, plan, scope);
+
+        using var reader = cmd.ExecuteTrackedReader();
+        if (!reader.TrackedRead())
+            return new QueryCountResult(0, 0);
+        return new QueryCountResult(
+            reader.GetInt32(0),
+            reader.GetInt32(1),
+            reader.FieldCount > 2
+            && !reader.IsDBNull(2)
+            && Convert.ToInt32(reader.GetValue(2)) != 0);
+    }
+
+    private UnusedCandidateQueryPlan BuildUnusedCandidatePageQuery(
+        UnusedCandidateScope scope,
+        bool resolveSqlReferences)
+    {
+        var graphLanguages = GetUnusedCandidateGraphLanguages(scope.Lang, resolveSqlReferences);
+        var bucketSql = BuildUnusedCandidateBucketSql();
+        var sql = new StringBuilder(capacity: resolveSqlReferences ? 5_000 : 3_000);
+        if (resolveSqlReferences)
+            sql.Append("\n            WITH unused_candidates AS (\n                SELECT ");
+        else
+            sql.Append("\n            SELECT ");
+        sql.Append(BuildUnusedCandidateProjectionSql(bucketSql));
+        AppendUnusedCandidateSourceSql(sql, scope, graphLanguages, resolveSqlReferences);
+
+        if (resolveSqlReferences)
+        {
+            sql.Append("\n            )\n            SELECT ");
+            sql.Append(UnusedCandidateColumns);
+            sql.Append("\n            FROM unused_candidates\n            WHERE provisional_bucket_order = @bucketOrder");
+        }
+        else
+        {
+            sql.Append(" AND (");
+            sql.Append(bucketSql.ProvisionalOrder);
+            sql.Append(") = @bucketOrder");
+        }
+        sql.Append("\n            ORDER BY path, line, name\n            LIMIT @limit OFFSET @offset");
+        return new UnusedCandidateQueryPlan(sql.ToString(), graphLanguages);
+    }
+
+    private UnusedCandidateQueryPlan BuildUnusedCandidateCountQuery(UnusedCandidateScope scope)
+    {
+        var graphLanguages = GetUnusedCandidateGraphLanguages(scope.Lang, resolveSqlReferences: true);
+        var sql = new StringBuilder(capacity: 4_000);
+        sql.Append(@"
+            SELECT COUNT(*), COUNT(DISTINCT f.path), MAX(CASE WHEN f.lang = 'sql' THEN 1 ELSE 0 END)");
+        AppendUnusedCandidateSourceSql(sql, scope, graphLanguages, resolveSqlReferences: true);
+        return new UnusedCandidateQueryPlan(sql.ToString(), graphLanguages);
+    }
+
+    private IReadOnlyList<string> GetUnusedCandidateGraphLanguages(
+        string? lang,
+        bool resolveSqlReferences)
+    {
+        var supportedLanguages = GetWorkspaceSupportedReferenceLanguages();
+        if (lang != null)
+            return Array.Empty<string>();
+
+        var graphLanguages = new List<string>();
+        foreach (var language in supportedLanguages)
+        {
+            if (resolveSqlReferences || !IsSqlLanguage(language))
+                graphLanguages.Add(language);
+        }
+        return graphLanguages;
+    }
+
+    private void AppendUnusedCandidateSourceSql(
+        StringBuilder sql,
+        UnusedCandidateScope scope,
+        IReadOnlyList<string> graphLanguages,
+        bool resolveSqlReferences)
+    {
+        sql.Append(@"
+            FROM symbols s
+            JOIN files f ON s.file_id = f.id
+            WHERE s.kind NOT IN ('import', 'namespace')");
+        sql.Append(BuildUnusedReferenceAbsenceSql(resolveSqlReferences));
+        if (resolveSqlReferences && _hasChunksTable && HasTable("chunks"))
+        {
+            var visibilitySql = $"lower({GetSymbolColumnSql("visibility", "''")})";
+            sql.Append(BuildSameFilePrivateUseExclusionSql(
+                "s", "f", visibilitySql,
+                GetSymbolColumnSql("start_line", "s.line"),
+                GetSymbolColumnSql("end_line", "s.line")));
+            sql.Append(BuildCSharpPartialContainingTypeUseExclusionSql("s", "f", visibilitySql));
+        }
+        sql.Append("\n              AND ");
+        sql.Append(BuildAmbiguousCSharpEnumMemberExclusionSql(
+            "s", "f", scope.PathPatterns, scope.ExcludePathPatterns, scope.ExcludeTests));
+        AppendUnusedCandidateScopeSql(sql, scope, graphLanguages);
+    }
+
+    private string BuildUnusedReferenceAbsenceSql(bool resolveSqlReferences)
+    {
+        if (!resolveSqlReferences)
+        {
+            return @"
+              AND NOT EXISTS (
+                  SELECT 1
+                  FROM symbol_references sr
+                  WHERE sr.symbol_name IS NOT NULL
+                    AND sr.symbol_name <> ''
+                    AND sr.symbol_name = s.name
+              )";
+        }
+
+        var referenceContextSql = ReferenceContextSql("sr");
+        return @"
+              AND NOT EXISTS (
+                  SELECT 1
+                  FROM symbol_references sr
+                  JOIN files rf ON rf.id = sr.file_id" + ReferenceLineJoinSql("sr") + @"
+                  WHERE sr.symbol_name = s.name
+                     OR (f.lang = 'sql' AND rf.lang = 'sql' AND (
+                            (sql_resolve_reference_segment_count_at(sr.symbol_name, " + referenceContextSql + @", sr.container_name, sr.column_number) = sql_segment_count(s.name)
+                             AND sql_reference_matches_target_at(sr.symbol_name, " + referenceContextSql + @", sr.container_name, sr.column_number, s.name) = 1)
+                         OR (sql_segment_count(sr.symbol_name) = 1
+                            AND sql_allow_leaf_fallback_at(sr.symbol_name, " + referenceContextSql + @", sr.container_name, sr.column_number) = 1
+                            AND sr.symbol_name = sql_leaf_name(s.name) COLLATE NOCASE
+                            AND NOT EXISTS (
+                                    SELECT 1
+                                    FROM symbols s_exact
+                                    JOIN files f_exact ON f_exact.id = s_exact.file_id
+                                    WHERE f_exact.lang = 'sql'
+                                      AND sql_segment_count(s_exact.name) = sql_resolve_reference_segment_count_at(sr.symbol_name, " + referenceContextSql + @", sr.container_name, sr.column_number)
+                                      AND sql_reference_matches_target_at(sr.symbol_name, " + referenceContextSql + @", sr.container_name, sr.column_number, s_exact.name) = 1
+                                ))
+                     ))
+              )";
+    }
+
+    private void AppendUnusedCandidateScopeSql(
+        StringBuilder sql,
+        UnusedCandidateScope scope,
+        IReadOnlyList<string> graphLanguages)
+    {
+        var filters = string.Empty;
+        if (scope.Lang != null)
+            filters += SymbolLanguageFileIdFilter;
+        else
+            filters += $" AND f.lang IN ({string.Join(",", graphLanguages.Select((_, i) => $"@gl{i}"))})";
+        if (scope.Kind != null)
+            filters += " AND s.kind = @kind";
+        AppendPathFilters(
+            ref filters,
+            scope.PathPatterns,
+            scope.ExcludePathPatterns,
+            scope.ExcludeTests);
+        AppendVisibilityFilters(
+            ref filters,
+            scope.VisibilityFilters,
+            scope.ExcludeVisibilityFilters);
+        sql.Append(filters);
+    }
+
+    private static void AddUnusedCandidatePageParameters(
+        SqliteCommand command,
+        UnusedCandidateQueryPlan plan,
+        UnusedCandidateScope scope,
+        int provisionalBucketOrder,
+        int fetchLimit,
+        int offset)
+    {
+        SqliteCommandPolicy.Add(command, "@bucketOrder", provisionalBucketOrder);
+        SqliteCommandPolicy.Add(command, "@limit", fetchLimit);
+        SqliteCommandPolicy.Add(command, "@offset", offset);
+        AddUnusedCandidateScopeParameters(command, plan, scope);
+    }
+
+    private static void AddUnusedCandidateScopeParameters(
+        SqliteCommand command,
+        UnusedCandidateQueryPlan plan,
+        UnusedCandidateScope scope)
+    {
+        if (scope.Lang != null)
+            SqliteCommandPolicy.Add(command, "@lang", scope.Lang);
+        else
+        {
+            for (var index = 0; index < plan.GraphLanguages.Count; index++)
+                SqliteCommandPolicy.Add(command, $"@gl{index}", plan.GraphLanguages[index]);
+        }
+        if (scope.Kind != null)
+            SqliteCommandPolicy.Add(command, "@kind", scope.Kind);
+        AddPathFilterParameters(command, scope.PathPatterns, scope.ExcludePathPatterns);
+        AddVisibilityFilterParameters(
+            command,
+            scope.VisibilityFilters,
+            scope.ExcludeVisibilityFilters);
+    }
+
+    private string BuildUnusedCandidateProjectionSql(UnusedCandidateBucketSql bucketSql) => $@"s.file_id, f.path, f.lang, s.kind, s.name, s.line,
+                   {GetSymbolColumnSql("start_line", "s.line")} AS start_line,
+                   {GetSymbolColumnSql("end_line", "s.line")} AS end_line,
+                   {GetSymbolColumnSql("signature")} AS signature,
+                   {GetSymbolColumnSql("visibility")} AS visibility,
+                   {GetSymbolColumnSql("return_type")} AS return_type,
+                   {GetSymbolColumnSql("container_kind")} AS container_kind,
+                   {GetSymbolColumnSql("container_name")} AS container_name,
+                   {GetSymbolColumnSql("container_qualified_name", GetSymbolColumnSql("container_name", "''"))} AS container_qualified_name,
+                   CASE WHEN {bucketSql.IsPublicOrExported} THEN 1 ELSE 0 END AS is_public_or_exported,
+                   CASE WHEN {bucketSql.IsReflectionOrConfigSuspect} THEN 1 ELSE 0 END AS is_reflection_or_config_suspect,
+                   {bucketSql.ProvisionalOrder} AS provisional_bucket_order";
+
+    private UnusedCandidateBucketSql BuildUnusedCandidateBucketSql()
+    {
+        var visibilitySql = $"lower({GetSymbolColumnSql("visibility", "''")})";
+        var signatureSql = $"lower({GetSymbolColumnSql("signature", "''")})";
+        var isPublicOrExportedSql = $"{visibilitySql} IN ('public', 'open', 'pub', 'export')";
+        var reflectionOrConfigSql = $@"(
+                {isPublicOrExportedSql}
+                AND s.kind = 'property'
+                AND (
+                    lower(f.path) LIKE 'config/%'
+                    OR lower(f.path) LIKE '%/config/%'
+                    OR lower(f.path) LIKE 'settings/%'
+                    OR lower(f.path) LIKE '%/settings/%'
+                    OR lower(f.path) LIKE 'options/%'
+                    OR lower(f.path) LIKE '%/options/%'
+                    OR {signatureSql} LIKE '%iconfiguration%'
+                    OR {signatureSql} LIKE '%configurationsection%'
+                    OR {signatureSql} LIKE '%ioptions%'
+                    OR {signatureSql} LIKE '%options<%'
+                )
+            )";
+        var provisionalOrderSql = $@"CASE
+                WHEN {reflectionOrConfigSql} THEN 3
+                WHEN {isPublicOrExportedSql} THEN 2
+                WHEN {visibilitySql} IN ('private', 'fileprivate') THEN 0
+                ELSE 1
+            END";
+        return new UnusedCandidateBucketSql(
+            isPublicOrExportedSql,
+            reflectionOrConfigSql,
+            provisionalOrderSql);
+    }
+
+    private static UnusedCandidateSymbol ReadUnusedCandidate(SqliteDataReader reader) => new()
+    {
+        FileId = reader.GetInt64(0),
+        Path = reader.GetString(1),
+        Lang = GetNullableString(reader, 2),
+        Kind = reader.GetString(3),
+        Name = reader.GetString(4),
+        Line = reader.GetInt32(5),
+        StartLine = GetInt32OrFallback(reader, 6, 5),
+        EndLine = GetInt32OrFallback(reader, 7, 5),
+        Signature = GetNullableString(reader, 8),
+        Visibility = GetNullableString(reader, 9),
+        ReturnType = GetNullableString(reader, 10),
+        ContainerKind = GetNullableString(reader, 11),
+        ContainerName = GetNullableString(reader, 12),
+        ContainerQualifiedName = GetNullableString(reader, 13),
+        IsPublicOrExported = reader.GetInt32(14) != 0,
+        IsReflectionOrConfigSuspect = reader.GetInt32(15) != 0,
+    };
+
+    private string BuildAmbiguousCSharpEnumMemberExclusionSql(
+        string symbolAlias,
+        string fileAlias,
+        IReadOnlyList<string>? pathPatterns,
+        IReadOnlyList<string>? excludePathPatterns,
+        bool excludeTests)
+    {
+        var symbolContainerKindSql = GetSymbolColumnSql("container_kind", "''", symbolAlias);
+        var symbolContainerNameSql = GetSymbolColumnSql("container_name", "''", symbolAlias);
+        var symbolContainerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name", symbolContainerNameSql, symbolAlias);
+        var peerContainerKindSql = GetSymbolColumnSql("container_kind", "''", "s_peer");
+        var peerContainerNameSql = GetSymbolColumnSql("container_name", "''", "s_peer");
+        var peerContainerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name", peerContainerNameSql, "s_peer");
+        var peerPathFiltersSql = BuildPathFiltersSql("f_peer", pathPatterns, excludePathPatterns, excludeTests);
+
+        return $@"
+                NOT (
+                    {fileAlias}.lang = 'csharp'
+                    AND {symbolAlias}.kind = 'enum'
+                    AND {symbolContainerKindSql} = 'enum'
+                    AND EXISTS (
+                        SELECT 1
+                        FROM symbols s_peer
+                        JOIN files f_peer ON f_peer.id = s_peer.file_id
+                        WHERE f_peer.lang = 'csharp'
+                          {peerPathFiltersSql}
+                          AND s_peer.kind = 'enum'
+                          AND {peerContainerKindSql} = 'enum'
+                          AND s_peer.name = {symbolAlias}.name
+                          AND {peerContainerQualifiedNameSql} <> {symbolContainerQualifiedNameSql}
+                    )
+                )";
+    }
+}
diff --git a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
index 41bd9d84f..2cfdbaccb 100644
--- a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
@@ -377,65 +377,9 @@ FROM symbols {ancestorAlias}
         @"\{\s*(?:get|set|init)\b|=>",
         RegexOptions.Compiled | RegexOptions.CultureInvariant);
 
-    private sealed class UnusedCandidateSymbol
-    {
-        public long FileId { get; init; }
-        public string Path { get; init; } = string.Empty;
-        public string? Lang { get; init; }
-        public string Kind { get; init; } = string.Empty;
-        public string Name { get; init; } = string.Empty;
-        public int Line { get; init; }
-        public int StartLine { get; init; }
-        public int EndLine { get; init; }
-        public string? Signature { get; init; }
-        public string? Visibility { get; init; }
-        public string? ReturnType { get; init; }
-        public string? ContainerKind { get; init; }
-        public string? ContainerName { get; init; }
-        public string? ContainerQualifiedName { get; init; }
-        public bool IsPublicOrExported { get; init; }
-        public bool IsReflectionOrConfigSuspect { get; init; }
-        public int ProvisionalBucketOrder { get; init; }
-    }
-
     private readonly record struct UnusedCandidateChunk(int StartLine, int EndLine, string Content);
     private readonly record struct UnusedContractDomainClassification(string Domain, List<string> Tags);
 
-
-    private string BuildAmbiguousCSharpEnumMemberExclusionSql(
-        string symbolAlias,
-        string fileAlias,
-        IReadOnlyList<string>? pathPatterns,
-        IReadOnlyList<string>? excludePathPatterns,
-        bool excludeTests)
-    {
-        var symbolContainerKindSql = GetSymbolColumnSql("container_kind", "''", symbolAlias);
-        var symbolContainerNameSql = GetSymbolColumnSql("container_name", "''", symbolAlias);
-        var symbolContainerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name", symbolContainerNameSql, symbolAlias);
-        var peerContainerKindSql = GetSymbolColumnSql("container_kind", "''", "s_peer");
-        var peerContainerNameSql = GetSymbolColumnSql("container_name", "''", "s_peer");
-        var peerContainerQualifiedNameSql = GetSymbolColumnSql("container_qualified_name", peerContainerNameSql, "s_peer");
-        var peerPathFiltersSql = BuildPathFiltersSql("f_peer", pathPatterns, excludePathPatterns, excludeTests);
-
-        return $@"
-                NOT (
-                    {fileAlias}.lang = 'csharp'
-                    AND {symbolAlias}.kind = 'enum'
-                    AND {symbolContainerKindSql} = 'enum'
-                    AND EXISTS (
-                        SELECT 1
-                        FROM symbols s_peer
-                        JOIN files f_peer ON f_peer.id = s_peer.file_id
-                        WHERE f_peer.lang = 'csharp'
-                          {peerPathFiltersSql}
-                          AND s_peer.kind = 'enum'
-                          AND {peerContainerKindSql} = 'enum'
-                          AND s_peer.name = {symbolAlias}.name
-                          AND {peerContainerQualifiedNameSql} <> {symbolContainerQualifiedNameSql}
-                    )
-                )";
-    }
-
     /// <summary>
     /// Find symbols that have no matching references in the reference table (potential dead code).
     /// Only meaningful for graph-supported languages — unsupported languages are excluded by default.
@@ -604,7 +548,7 @@ private List<UnusedSymbolResult> GetFilteredUnusedSymbolsWithoutSqlResolver(int
             while (!AllTargetUnusedBucketsFilled(resultsByBucket, targetBuckets, targetCount))
             {
                 var batch = FetchUnusedCandidateSymbols(batchSize, offset, provisionalBucket, kind, lang,
-                    pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters).ToList();
+                    pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
                 if (batch.Count == 0)
                     break;
 
@@ -639,7 +583,7 @@ private List<UnusedSymbolResult> CollectUnusedCandidateBucket(int targetCount, i
         while (results.Count < targetCount)
         {
             var batch = FetchUnusedCandidateSymbols(batchSize, offset, provisionalBucketOrder, kind, lang,
-                pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters).ToList();
+                pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
             if (batch.Count == 0)
                 break;
 
@@ -673,7 +617,7 @@ private void CollectPublicUnusedCandidateBucket(int targetCount, int batchSize,
             && candidatesFetched < candidateBudget)
         {
             var batch = FetchUnusedCandidateSymbols(batchSize, offset, 2, kind, lang,
-                pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters).ToList();
+                pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
             if (batch.Count == 0)
                 break;
 
@@ -864,125 +808,6 @@ private static void AddUnusedCandidateChunkLines(SortedDictionary<int, string> l
         }
     }
 
-    private IEnumerable<UnusedCandidateSymbol> FetchUnusedCandidateSymbols(int fetchLimit, int offset, int provisionalBucketOrder, string? kind, string? lang,
-        IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null)
-    {
-        var graphLangs = GetWorkspaceSupportedReferenceLanguages()
-            .Where(value => !IsSqlLanguage(value))
-            .ToList();
-        var visibilitySql = $"lower({GetSymbolColumnSql("visibility", "''")})";
-        var signatureSql = $"lower({GetSymbolColumnSql("signature", "''")})";
-        const string pathSql = "lower(f.path)";
-        var isPublicOrExportedSql = $"{visibilitySql} IN ('public', 'open', 'pub', 'export')";
-        var hasConfigContextSql = $@"(
-                {pathSql} LIKE 'config/%'
-                OR {pathSql} LIKE '%/config/%'
-                OR {pathSql} LIKE 'settings/%'
-                OR {pathSql} LIKE '%/settings/%'
-                OR {pathSql} LIKE 'options/%'
-                OR {pathSql} LIKE '%/options/%'
-                OR {signatureSql} LIKE '%iconfiguration%'
-                OR {signatureSql} LIKE '%configurationsection%'
-                OR {signatureSql} LIKE '%ioptions%'
-                OR {signatureSql} LIKE '%options<%'
-            )";
-        var isReflectionOrConfigSuspectSql = $@"(
-                {isPublicOrExportedSql}
-                AND s.kind = 'property'
-                AND {hasConfigContextSql}
-            )";
-        var provisionalBucketOrderSql = $@"
-            CASE
-                WHEN {isReflectionOrConfigSuspectSql} THEN 3
-                WHEN {isPublicOrExportedSql} THEN 2
-                WHEN {visibilitySql} IN ('private', 'fileprivate') THEN 0
-                ELSE 1
-            END";
-
-        var sql = $@"
-            SELECT s.file_id, f.path, f.lang, s.kind, s.name, s.line,
-                   {GetSymbolColumnSql("start_line", "s.line")} AS start_line,
-                   {GetSymbolColumnSql("end_line", "s.line")} AS end_line,
-                   {GetSymbolColumnSql("signature")} AS signature,
-                   {GetSymbolColumnSql("visibility")} AS visibility,
-                   {GetSymbolColumnSql("return_type")} AS return_type,
-                   {GetSymbolColumnSql("container_kind")} AS container_kind,
-                   {GetSymbolColumnSql("container_name")} AS container_name,
-                   {GetSymbolColumnSql("container_qualified_name", GetSymbolColumnSql("container_name", "''"))} AS container_qualified_name,
-                   CASE WHEN {isPublicOrExportedSql} THEN 1 ELSE 0 END AS is_public_or_exported,
-                   CASE WHEN {isReflectionOrConfigSuspectSql} THEN 1 ELSE 0 END AS is_reflection_or_config_suspect,
-                   {provisionalBucketOrderSql} AS provisional_bucket_order
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE s.kind NOT IN ('import', 'namespace')";
-        sql += $"\n              AND {BuildAmbiguousCSharpEnumMemberExclusionSql("s", "f", pathPatterns, excludePathPatterns, excludeTests)}";
-        sql += """
-              AND NOT EXISTS (
-                  SELECT 1
-                  FROM symbol_references sr
-                  WHERE sr.symbol_name IS NOT NULL
-                    AND sr.symbol_name <> ''
-                    AND sr.symbol_name = s.name
-              )
-            """;
-
-        if (lang != null)
-            sql += SymbolLanguageFileIdFilter;
-        else
-            sql += $" AND f.lang IN ({string.Join(",", graphLangs.Select((_, i) => $"@gl{i}"))})";
-
-        if (kind != null)
-            sql += " AND s.kind = @kind";
-
-        sql += " AND (" + provisionalBucketOrderSql + ") = @provisionalBucketOrder";
-        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
-        AppendVisibilityFilters(ref sql, visibilityFilters, excludeVisibilityFilters);
-        sql += " ORDER BY f.path, s.line, s.name";
-        sql += " LIMIT @limit OFFSET @offset";
-
-        using var cmd = _conn.CreateCommand();
-        cmd.CommandText = sql;
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        else
-        {
-            for (int i = 0; i < graphLangs.Count; i++)
-                SqliteCommandPolicy.Add(cmd, $"@gl{i}", graphLangs[i]);
-        }
-        if (kind != null)
-            SqliteCommandPolicy.Add(cmd, "@kind", kind);
-        SqliteCommandPolicy.Add(cmd, "@provisionalBucketOrder", provisionalBucketOrder);
-        SqliteCommandPolicy.Add(cmd, "@limit", fetchLimit);
-        SqliteCommandPolicy.Add(cmd, "@offset", offset);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        AddVisibilityFilterParameters(cmd, visibilityFilters, excludeVisibilityFilters);
-
-        using var reader = cmd.ExecuteTrackedReader();
-        while (reader.TrackedRead())
-        {
-            yield return new UnusedCandidateSymbol
-            {
-                FileId = reader.GetInt64(0),
-                Path = reader.GetString(1),
-                Lang = GetNullableString(reader, 2),
-                Kind = reader.GetString(3),
-                Name = reader.GetString(4),
-                Line = reader.GetInt32(5),
-                StartLine = GetInt32OrFallback(reader, 6, 5),
-                EndLine = GetInt32OrFallback(reader, 7, 5),
-                Signature = GetNullableString(reader, 8),
-                Visibility = GetNullableString(reader, 9),
-                ReturnType = GetNullableString(reader, 10),
-                ContainerKind = GetNullableString(reader, 11),
-                ContainerName = GetNullableString(reader, 12),
-                ContainerQualifiedName = GetNullableString(reader, 13),
-                IsPublicOrExported = reader.GetInt32(14) != 0,
-                IsReflectionOrConfigSuspect = reader.GetInt32(15) != 0,
-                ProvisionalBucketOrder = reader.GetInt32(16),
-            };
-        }
-    }
-
     private UnusedSymbolResult CreateUnusedSymbolResult(UnusedCandidateSymbol candidate)
     {
         var kind = NormalizeUnusedSymbolKind(candidate);
@@ -1247,157 +1072,6 @@ private static bool StartsWithCSharpWhereConstraint(string text, int index)
         return end >= text.Length || char.IsWhiteSpace(text[end]);
     }
 
-    private List<UnusedSymbolResult> FetchUnusedCandidates(int fetchLimit, int provisionalBucketOrder, int offset, string? kind, string? lang,
-        IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests, IReadOnlyList<string>? visibilityFilters = null, IReadOnlyList<string>? excludeVisibilityFilters = null)
-    {
-        var graphLangs = GetWorkspaceSupportedReferenceLanguages();
-        var visibilitySql = $"lower({GetSymbolColumnSql("visibility", "''")})";
-        var signatureSql = $"lower({GetSymbolColumnSql("signature", "''")})";
-        const string pathSql = "lower(f.path)";
-        var isPublicOrExportedSql = $"{visibilitySql} IN ('public', 'open', 'pub', 'export')";
-        var hasConfigContextSql = $@"(
-                {pathSql} LIKE 'config/%'
-                OR {pathSql} LIKE '%/config/%'
-                OR {pathSql} LIKE 'settings/%'
-                OR {pathSql} LIKE '%/settings/%'
-                OR {pathSql} LIKE 'options/%'
-                OR {pathSql} LIKE '%/options/%'
-                OR {signatureSql} LIKE '%iconfiguration%'
-                OR {signatureSql} LIKE '%configurationsection%'
-                OR {signatureSql} LIKE '%ioptions%'
-                OR {signatureSql} LIKE '%options<%'
-            )";
-        var isReflectionOrConfigSuspectSql = $@"(
-                {isPublicOrExportedSql}
-                AND s.kind = 'property'
-                AND {hasConfigContextSql}
-            )";
-        var provisionalBucketOrderSql = $@"
-            CASE
-                WHEN {isReflectionOrConfigSuspectSql} THEN 3
-                WHEN {isPublicOrExportedSql} THEN 2
-                WHEN {visibilitySql} IN ('private', 'fileprivate') THEN 0
-                ELSE 1
-            END";
-
-        var sql = $@"
-            WITH unused_candidates AS (
-                SELECT s.file_id, f.path, f.lang, s.kind, s.name, s.line,
-                       {GetSymbolColumnSql("start_line", "s.line")} AS start_line,
-                       {GetSymbolColumnSql("end_line", "s.line")} AS end_line,
-                       {GetSymbolColumnSql("signature")} AS signature,
-                       {GetSymbolColumnSql("visibility")} AS visibility,
-                       {GetSymbolColumnSql("return_type")} AS return_type,
-                       {GetSymbolColumnSql("container_kind")} AS container_kind,
-                       {GetSymbolColumnSql("container_name")} AS container_name,
-                       {GetSymbolColumnSql("container_qualified_name", GetSymbolColumnSql("container_name", "''"))} AS container_qualified_name,
-                       CASE WHEN {isPublicOrExportedSql} THEN 1 ELSE 0 END AS is_public_or_exported,
-                       CASE WHEN {isReflectionOrConfigSuspectSql} THEN 1 ELSE 0 END AS is_reflection_or_config_suspect,
-                       {provisionalBucketOrderSql} AS provisional_bucket_order
-                FROM symbols s
-                JOIN files f ON s.file_id = f.id
-                WHERE s.kind NOT IN ('import', 'namespace')
-                  AND NOT EXISTS (
-                      SELECT 1
-                      FROM symbol_references sr
-                      JOIN files rf ON rf.id = sr.file_id" + ReferenceLineJoinSql("sr") + @"
-                      WHERE sr.symbol_name = s.name
-                         OR (f.lang = 'sql' AND rf.lang = 'sql' AND (
-                                (sql_resolve_reference_segment_count_at(sr.symbol_name, " + ReferenceContextSql("sr") + @", sr.container_name, sr.column_number) = sql_segment_count(s.name)
-                                 AND sql_reference_matches_target_at(sr.symbol_name, " + ReferenceContextSql("sr") + @", sr.container_name, sr.column_number, s.name) = 1)
-                         OR (sql_segment_count(sr.symbol_name) = 1
-                            AND sql_allow_leaf_fallback_at(sr.symbol_name, " + ReferenceContextSql("sr") + @", sr.container_name, sr.column_number) = 1
-                            AND sr.symbol_name = sql_leaf_name(s.name) COLLATE NOCASE
-                            AND NOT EXISTS (
-                                    SELECT 1
-                                    FROM symbols s_exact
-                                    JOIN files f_exact ON f_exact.id = s_exact.file_id
-                                    WHERE f_exact.lang = 'sql'
-                                      AND sql_segment_count(s_exact.name) = sql_resolve_reference_segment_count_at(sr.symbol_name, " + ReferenceContextSql("sr") + @", sr.container_name, sr.column_number)
-                                     AND sql_reference_matches_target_at(sr.symbol_name, " + ReferenceContextSql("sr") + @", sr.container_name, sr.column_number, s_exact.name) = 1
-                                ))
-                         ))
-                  )";
-        if (_hasChunksTable && HasTable("chunks"))
-        {
-            sql += BuildSameFilePrivateUseExclusionSql(
-                "s",
-                "f",
-                visibilitySql,
-                GetSymbolColumnSql("start_line", "s.line"),
-                GetSymbolColumnSql("end_line", "s.line"));
-            sql += BuildCSharpPartialContainingTypeUseExclusionSql("s", "f", visibilitySql);
-        }
-        sql += $"\n              AND {BuildAmbiguousCSharpEnumMemberExclusionSql("s", "f", pathPatterns, excludePathPatterns, excludeTests)}";
-
-        if (lang != null)
-            sql += SymbolLanguageFileIdFilter;
-        else
-            sql += $" AND f.lang IN ({string.Join(",", graphLangs.Select((_, i) => $"@gl{i}"))})";
-
-        if (kind != null)
-            sql += " AND s.kind = @kind";
-
-        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
-        AppendVisibilityFilters(ref sql, visibilityFilters, excludeVisibilityFilters);
-        sql += @"
-            )
-            SELECT file_id, path, lang, kind, name, line, start_line, end_line, signature, visibility,
-                   return_type, container_kind, container_name, container_qualified_name,
-                   is_public_or_exported, is_reflection_or_config_suspect, provisional_bucket_order
-            FROM unused_candidates
-            WHERE provisional_bucket_order = @bucketOrder
-            ORDER BY path, line, name
-            LIMIT @limit OFFSET @offset";
-
-        using var cmd = _conn.CreateCommand();
-        cmd.CommandText = sql;
-        SqliteCommandPolicy.Add(cmd, "@bucketOrder", provisionalBucketOrder);
-        SqliteCommandPolicy.Add(cmd, "@limit", fetchLimit);
-        SqliteCommandPolicy.Add(cmd, "@offset", offset);
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        else
-        {
-            var langList = graphLangs.ToList();
-            for (int i = 0; i < langList.Count; i++)
-                SqliteCommandPolicy.Add(cmd, $"@gl{i}", langList[i]);
-        }
-        if (kind != null)
-            SqliteCommandPolicy.Add(cmd, "@kind", kind);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        AddVisibilityFilterParameters(cmd, visibilityFilters, excludeVisibilityFilters);
-
-        var results = new List<UnusedSymbolResult>();
-        using var reader = cmd.ExecuteTrackedReader();
-        while (reader.TrackedRead())
-        {
-            var candidate = new UnusedCandidateSymbol
-            {
-                FileId = reader.GetInt64(0),
-                Path = reader.GetString(1),
-                Lang = GetNullableString(reader, 2),
-                Kind = reader.GetString(3),
-                Name = reader.GetString(4),
-                Line = reader.GetInt32(5),
-                StartLine = GetInt32OrFallback(reader, 6, 5),
-                EndLine = GetInt32OrFallback(reader, 7, 5),
-                Signature = GetNullableString(reader, 8),
-                Visibility = GetNullableString(reader, 9),
-                ReturnType = GetNullableString(reader, 10),
-                ContainerKind = GetNullableString(reader, 11),
-                ContainerName = GetNullableString(reader, 12),
-                ContainerQualifiedName = GetNullableString(reader, 13),
-                IsPublicOrExported = reader.GetInt32(14) != 0,
-                IsReflectionOrConfigSuspect = reader.GetInt32(15) != 0,
-                ProvisionalBucketOrder = reader.GetInt32(16),
-            };
-            results.Add(CreateUnusedSymbolResult(candidate));
-        }
-
-        return results;
-    }
-
     private static List<UnusedSymbolResult> DiversifyUnusedResults(List<UnusedSymbolResult> results, int limit)
     {
         if (results.Count == 0 || limit <= 0)
@@ -1624,7 +1298,7 @@ private UnusedCountResult CountUnusedSymbolsDetailedWithoutSqlResolver(string? k
             while (true)
             {
                 var batch = FetchUnusedCandidateSymbols(batchSize, offset, bucket, kind, lang,
-                    pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters).ToList();
+                    pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
                 if (batch.Count == 0)
                     break;
 
@@ -1764,82 +1438,14 @@ public QueryCountResult CountUnusedSymbols(string? kind, string? lang, IReadOnly
         if (!ScopeMayIncludeSqlSymbols(kind, lang, pathPatterns, excludePathPatterns, excludeTests))
             return CountUnusedSymbolsWithoutSqlResolver(kind, lang, pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
 
-        var graphLangs = GetWorkspaceSupportedReferenceLanguages();
-        using var cmd = _conn.CreateCommand();
-        var referenceLineJoin = ReferenceLineJoinSql("sr");
-        var contextSql = ReferenceContextSql("sr");
-        var sql = @"
-            SELECT COUNT(*), COUNT(DISTINCT f.path), MAX(CASE WHEN f.lang = 'sql' THEN 1 ELSE 0 END)
-            FROM symbols s
-            JOIN files f ON s.file_id = f.id
-            WHERE s.kind NOT IN ('import', 'namespace')
-              AND NOT EXISTS (
-                  SELECT 1
-                  FROM symbol_references sr
-                  JOIN files rf ON rf.id = sr.file_id" + referenceLineJoin + @"
-                  WHERE sr.symbol_name = s.name
-                     OR (f.lang = 'sql' AND rf.lang = 'sql' AND (
-                            (sql_resolve_reference_segment_count_at(sr.symbol_name, " + contextSql + @", sr.container_name, sr.column_number) = sql_segment_count(s.name)
-                             AND sql_reference_matches_target_at(sr.symbol_name, " + contextSql + @", sr.container_name, sr.column_number, s.name) = 1)
-                         OR (sql_segment_count(sr.symbol_name) = 1
-                            AND sql_allow_leaf_fallback_at(sr.symbol_name, " + contextSql + @", sr.container_name, sr.column_number) = 1
-                            AND sr.symbol_name = sql_leaf_name(s.name) COLLATE NOCASE
-                            AND NOT EXISTS (
-                                    SELECT 1
-                                    FROM symbols s_exact
-                                    JOIN files f_exact ON f_exact.id = s_exact.file_id
-                                    WHERE f_exact.lang = 'sql'
-                                      AND sql_segment_count(s_exact.name) = sql_resolve_reference_segment_count_at(sr.symbol_name, " + contextSql + @", sr.container_name, sr.column_number)
-                                      AND sql_reference_matches_target_at(sr.symbol_name, " + contextSql + @", sr.container_name, sr.column_number, s_exact.name) = 1
-                                ))
-                     ))
-              )";
-        if (_hasChunksTable && HasTable("chunks"))
-        {
-            sql += BuildSameFilePrivateUseExclusionSql(
-                "s",
-                "f",
-                $"lower({GetSymbolColumnSql("visibility", "''")})",
-                GetSymbolColumnSql("start_line", "s.line"),
-                GetSymbolColumnSql("end_line", "s.line"));
-            sql += BuildCSharpPartialContainingTypeUseExclusionSql(
-                "s",
-                "f",
-                $"lower({GetSymbolColumnSql("visibility", "''")})");
-        }
-        sql += $"\n              AND {BuildAmbiguousCSharpEnumMemberExclusionSql("s", "f", pathPatterns, excludePathPatterns, excludeTests)}";
-
-        if (lang != null)
-            sql += SymbolLanguageFileIdFilter;
-        else
-            sql += $" AND f.lang IN ({string.Join(",", graphLangs.Select((_, i) => $"@gl{i}"))})";
-
-        if (kind != null)
-            sql += " AND s.kind = @kind";
-
-        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
-        AppendVisibilityFilters(ref sql, visibilityFilters, excludeVisibilityFilters);
-        cmd.CommandText = sql;
-        if (lang != null)
-            SqliteCommandPolicy.Add(cmd, "@lang", lang);
-        else
-        {
-            var langList = graphLangs.ToList();
-            for (int i = 0; i < langList.Count; i++)
-                SqliteCommandPolicy.Add(cmd, $"@gl{i}", langList[i]);
-        }
-        if (kind != null)
-            SqliteCommandPolicy.Add(cmd, "@kind", kind);
-        AddPathFilterParameters(cmd, pathPatterns, excludePathPatterns);
-        AddVisibilityFilterParameters(cmd, visibilityFilters, excludeVisibilityFilters);
-
-        using var reader = cmd.ExecuteTrackedReader();
-        if (!reader.TrackedRead())
-            return new QueryCountResult(0, 0);
-        return new QueryCountResult(
-            reader.GetInt32(0),
-            reader.GetInt32(1),
-            reader.FieldCount > 2 && !reader.IsDBNull(2) && Convert.ToInt32(reader.GetValue(2)) != 0);
+        return CountUnusedCandidates(new UnusedCandidateScope(
+            kind,
+            lang,
+            pathPatterns,
+            excludePathPatterns,
+            excludeTests,
+            visibilityFilters,
+            excludeVisibilityFilters));
     }
 
     private QueryCountResult CountFilteredUnusedSymbols(string? kind, string? lang,
@@ -1894,7 +1500,7 @@ private QueryCountResult CountUnusedSymbolsWithoutSqlResolver(string? kind, stri
             while (true)
             {
                 var batch = FetchUnusedCandidateSymbols(batchSize, offset, bucket, kind, lang,
-                    pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters).ToList();
+                    pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
                 if (batch.Count == 0)
                     break;
 
diff --git a/tests/CodeIndex.Tests/DbReaderUnusedCandidateQueryTests.cs b/tests/CodeIndex.Tests/DbReaderUnusedCandidateQueryTests.cs
new file mode 100644
index 000000000..ca1269ca8
--- /dev/null
+++ b/tests/CodeIndex.Tests/DbReaderUnusedCandidateQueryTests.cs
@@ -0,0 +1,146 @@
+using CodeIndex.Database;
+using CodeIndex.Models;
+
+namespace CodeIndex.Tests;
+
+public partial class DbReaderTests
+{
+    [Fact]
+    public void UnusedCandidateQueries_MixedSqlScopePreservesProjectionAndCounts()
+    {
+        var paths = SeedMixedUnusedCandidates();
+
+        var unused = _reader.GetUnusedSymbols(
+            10, "function", null, paths, null, excludeTests: false);
+        var count = _reader.CountUnusedSymbols(
+            "function", null, paths, null, excludeTests: false);
+        var detailedCount = _reader.CountUnusedSymbolsDetailed(
+            "function", null, paths, null, excludeTests: false);
+
+        Assert.Collection(unused, AssertMixedCSharpCandidate, AssertMixedSqlCandidate);
+        Assert.Equal(new QueryCountResult(2, 2, IncludesSql: true), count);
+        Assert.Equal(2, detailedCount.Count);
+        Assert.Equal(2, detailedCount.FileCount);
+        Assert.True(detailedCount.IncludesSql);
+        Assert.Equal(1, detailedCount.BucketCounts["likely_unused_private"]);
+        Assert.Equal(1, detailedCount.BucketCounts["maybe_unused_nonpublic"]);
+    }
+
+    private string[] SeedMixedUnusedCandidates()
+    {
+        var csharpFileId = CreateMixedCandidateFile("src/mixed_unused_scope.cs", "csharp", 12);
+        var sqlFileId = CreateMixedCandidateFile("src/mixed_unused_scope.sql", "sql", 20);
+        InsertMixedCandidateChunks(csharpFileId, sqlFileId);
+        _writer.InsertSymbols(
+        [
+            CreateMixedCandidate(
+                csharpFileId, "HiddenMixedCandidate", 7, 8,
+                "private string HiddenMixedCandidate()", "private", "string",
+                "class", "MixedCandidateHost", "Fixtures.MixedCandidateHost"),
+            CreateMixedCandidate(
+                sqlFileId, "dbo.UsedMixedCandidate", 3, 5,
+                "CREATE PROCEDURE dbo.UsedMixedCandidate"),
+            CreateMixedCandidate(sqlFileId, "dbo.UnusedMixedCandidate", 11, 14),
+        ]);
+        _writer.InsertReferences(
+        [
+            new ReferenceRecord
+            {
+                FileId = sqlFileId,
+                SymbolName = "dbo.UsedMixedCandidate",
+                ReferenceKind = "call",
+                Line = 18,
+                Column = 6,
+                Context = "EXEC dbo.UsedMixedCandidate;",
+            },
+        ]);
+        return ["src/mixed_unused_scope.*"];
+    }
+
+    private void InsertMixedCandidateChunks(long csharpFileId, long sqlFileId) =>
+        _writer.InsertChunks(
+        [
+            new ChunkRecord
+            {
+                FileId = csharpFileId,
+                ChunkIndex = 0,
+                StartLine = 1,
+                EndLine = 12,
+                Content = "private string HiddenMixedCandidate() => string.Empty;",
+            },
+            new ChunkRecord
+            {
+                FileId = sqlFileId,
+                ChunkIndex = 0,
+                StartLine = 1,
+                EndLine = 20,
+                Content = "CREATE PROCEDURE dbo.UsedMixedCandidate AS SELECT 1;",
+            },
+        ]);
+
+    private long CreateMixedCandidateFile(string path, string lang, int lines) =>
+        _writer.UpsertFile(new FileRecord
+        {
+            Path = path,
+            Lang = lang,
+            Size = 200,
+            Lines = lines,
+            Modified = new DateTime(2025, 6, 1, 0, 0, 0, DateTimeKind.Utc),
+        });
+
+    private static SymbolRecord CreateMixedCandidate(
+        long fileId,
+        string name,
+        int startLine,
+        int endLine,
+        string? signature = null,
+        string? visibility = null,
+        string? returnType = null,
+        string? containerKind = null,
+        string? containerName = null,
+        string? containerQualifiedName = null) => new()
+        {
+            FileId = fileId,
+            Kind = "function",
+            Name = name,
+            Line = startLine,
+            StartLine = startLine,
+            EndLine = endLine,
+            Signature = signature,
+            Visibility = visibility,
+            ReturnType = returnType,
+            ContainerKind = containerKind,
+            ContainerName = containerName,
+            ContainerQualifiedName = containerQualifiedName,
+        };
+
+    private static void AssertMixedCSharpCandidate(UnusedSymbolResult candidate)
+    {
+        Assert.Equal("src/mixed_unused_scope.cs", candidate.Path);
+        Assert.Equal("csharp", candidate.Lang);
+        Assert.Equal("function", candidate.Kind);
+        Assert.Equal("HiddenMixedCandidate", candidate.Name);
+        Assert.Equal((7, 7, 8), (candidate.Line, candidate.StartLine, candidate.EndLine));
+        Assert.Equal("private string HiddenMixedCandidate()", candidate.Signature);
+        Assert.Equal("private", candidate.Visibility);
+        Assert.Equal("string", candidate.ReturnType);
+        Assert.Equal("class", candidate.ContainerKind);
+        Assert.Equal("MixedCandidateHost", candidate.ContainerName);
+        Assert.Equal("likely_unused_private", candidate.UnusedBucket);
+    }
+
+    private static void AssertMixedSqlCandidate(UnusedSymbolResult candidate)
+    {
+        Assert.Equal("src/mixed_unused_scope.sql", candidate.Path);
+        Assert.Equal("sql", candidate.Lang);
+        Assert.Equal("function", candidate.Kind);
+        Assert.Equal("dbo.UnusedMixedCandidate", candidate.Name);
+        Assert.Equal((11, 11, 14), (candidate.Line, candidate.StartLine, candidate.EndLine));
+        Assert.Null(candidate.Signature);
+        Assert.Null(candidate.Visibility);
+        Assert.Null(candidate.ReturnType);
+        Assert.Null(candidate.ContainerKind);
+        Assert.Null(candidate.ContainerName);
+        Assert.Equal("maybe_unused_nonpublic", candidate.UnusedBucket);
+    }
+}

From 06b082c482c62351fd0e7580d6690b0926780f42 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 22:37:04 +0900
Subject: [PATCH 32/45] Decompose plain search execution

---
 TESTING_GUIDE.md                              |   2 +
 .../Cli/QueryCommandRunner.Search.cs          | 306 +-----------------
 .../Cli/QueryCommandRunner.SearchExecution.cs | 168 ++++++++++
 .../Cli/QueryCommandRunner.SearchOutput.cs    | 266 +++++++++++++++
 .../QueryCommandRunnerSearchTests.cs          |  86 +++++
 5 files changed, 524 insertions(+), 304 deletions(-)
 create mode 100644 src/CodeIndex/Cli/QueryCommandRunner.SearchExecution.cs
 create mode 100644 src/CodeIndex/Cli/QueryCommandRunner.SearchOutput.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 3d6c5fa46..5927a77a9 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -221,6 +221,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   End-to-end upgrade path: seeds a pre-column legacy DB, opens it through `TryMigrateForRead`, and exercises the read paths that touch nullable symbol ordinals (outline, symbol search, nearby, unused, analyze bundle) to lock in the real-world failure mode behind #58 / #49. Migration ownership coverage must also distinguish caller-owned transactions from owned transactions, propagate unrelated `BEGIN` errors, preserve populated foreign-key rows across rebuilds, and verify rollback, foreign-key restoration, and successful retry after injected failures.
 - `IndexCommandRunner*Tests.cs`, `QueryCommandRunner*Tests.cs`, `ProgramCliTests.cs`, `InstallScriptTests.cs`
   YAML `outline` integration coverage must assert nested sequence paths, mapping-parent depth, unchanged source ranges and symbol counts, deterministic sorting, and cursor replay across a page boundary.
+  Search-core orchestration coverage must keep validation ahead of database execution, count-mode zero/nonzero payloads aligned, strict-not-found exit semantics intact, and profiled NDJSON ordered as result records, profile metadata, then the terminal record.
   CLI parsing, command execution, and installer behavior. Index command coverage is split by run mode or feature area, and query command coverage is split by command family with partial test classes so shared console and fixture helpers stay centralized. Keep repeated query-result fixtures, such as overlapping chunk content used by multiple search deduplication tests, in narrow class-level helpers instead of duplicating local builders. `ProgramCliTests.cs` covers top-level entrypoint behavior that must be exercised through a subprocess, while `InstallScriptTests.cs` runs focused bash snippets against `install.sh` in library mode to lock in release-installer regressions without performing real network installs. Installer bundle-generation tests must also verify that `install.sh` is marked generated while every canonical `install_modules/` source remains unmarked.
   Authoritative C# scoped-update coverage treats bounded parallel extraction as a correctness and resource contract. Keep the `2 * workers` window bound, fixed-worker reuse, whole-window extraction barrier, target-ordered single-writer persistence, and mixed-language serial boundary in the same suite. Required fallbacks cover parallelism one, active symbol filters, content-load seams, post-extraction hooks, non-authoritative or undersized snapshots, ambiguous nullable language reuse, and speculative probe exceptions returning to the serial per-file boundary. Serial/parallel parity must compare summaries, files/chunks/all semantic symbol and reference columns, normalized reference-line and candidate identities, hotspot aggregates, issues, readiness/user-version metadata, and last-run readable-byte counters across normal, generated, cap, and oversized inputs. Retain all three file-stat barriers. Cancellation before persistence, after validated load, and at extraction completion must preserve the expected committed prefix, batch ownership, and derived readiness. Global watchdog and direct-fatal tests must assert active phase, bounded return, and terminal side effects; source-negative ordering tests must cover both cap-discarded confirmed evidence and an earlier lexical contract candidate still blocked in symbol extraction. Abnormal-window fixtures release every injected block and wait for the snapshotted all-workers-stopped seam before restoring static hooks or deleting the project root.
   `JsonEnvelopeWrapperTests.cs` owns global JSON-envelope token-role coverage. Keep parser-accepted separated and inline query values, option ordering, the `--` end-of-options form, missing-value boundaries for other value-bearing options, and a genuine `--json-envelope` output request together so preprocessing cannot consume command data, suppress a structured error envelope, or place its injected `--json` after the positional boundary.
@@ -1284,6 +1285,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   エンドツーエンドのアップグレード経路: カラム追加前のレガシー DB を用意し、`TryMigrateForRead` 経由で開いてから NULL になりうるシンボル列を触る read path（outline、シンボル検索、近傍、unused、analyze バンドル）を一通り叩き、#58 / #49 の実機失敗モードを固定する。migration ownership の coverage では、caller-owned transaction と cdidx-owned transaction を区別し、無関係な `BEGIN` error を伝播させ、foreign key が設定された既存 row を rebuild 後も保持し、注入 failure 後の rollback、foreign key 復元、retry 成功まで検証する。
 - `IndexCommandRunner*Tests.cs`、`QueryCommandRunner*Tests.cs`、`ProgramCliTests.cs`、`InstallScriptTests.cs`
   YAML `outline` の integration coverage では、入れ子 sequence path、mapping parent の depth、不変な source range と symbol count、決定的な sort、page 境界を越える cursor replay を検証してください。
+  search core の orchestration coverage では、validation が database execution より先に行われること、count mode の zero/nonzero payload が揃うこと、strict-not-found の exit semantics、profile 付き NDJSON が result record、profile metadata、terminal record の順になることを維持してください。
   CLI の引数解析、コマンド実行、installer 挙動のテスト。Index command coverage は run mode または機能領域ごとの partial suite に分割し、Query command coverage は command family ごとの partial test class に分割して、共有 console / fixture helper は一箇所に保ちます。`ProgramCliTests.cs` はグローバル引数の解釈や完全な CLI 起動フローのように subprocess 経由で確認すべき Program エントリポイント挙動を扱い、`InstallScriptTests.cs` は `install.sh` を library mode で source した bash snippet を実行して、実ネットワーク install を行わずに release installer の回帰を固定する。installer bundle 生成テストでは、`install.sh` が generated と判定される一方、canonical な `install_modules/` source はすべて unmarked のままであることも検証してください。
   authoritative C# scoped update の coverage では、bounded parallel extraction を correctness と resource の契約として扱います。`2 * workers` の window 上限、固定 worker の再利用、window 全体の extraction barrier、target 順の single-writer persistence、mixed-language の serial 境界を同じ suite で維持してください。必須 fallback は parallelism 1、active symbol filter、content-load seam、post-extraction hook、non-authoritative / target 不足 snapshot、ambiguous な nullable language reuse、speculative probe 例外から serial per-file boundary への復帰を含みます。serial / parallel parity は normal、generated、cap、oversized input を横断し、summary、file / chunk、symbol / reference の全 semantic column、正規化した reference-line / candidate identity、hotspot aggregate、issue、readiness / user-version metadata、last-run readable-byte counter を比較してください。3段階の file-stat barrier も維持します。persistence 前、validated load 後、extraction completion 時の cancellation は、想定 committed prefix、batch ownership、derived readiness を固定します。global watchdog と direct fatal は active phase、bounded return、terminal side effect を検証し、source-negative ordering は cap で payload から除かれた confirmed evidence と、symbol extraction 中に block した earlier lexical contract candidate の両方を含めます。異常 window の fixture は注入 block をすべて解放し、snapshot 済み all-workers-stopped seam を待ってから static hook の復元と project root の削除を行ってください。
   `JsonEnvelopeWrapperTests.cs` は global JSON envelope の token role coverage を担当します。前処理が command data を消費したり、構造化 error envelope を抑止したり、補う `--json` を positional 境界より後ろへ置いたりしないよう、parser が受理する分離形式と inline 形式の query 値、option 順序、`--` end-of-options 形式、他の value-bearing option の missing-value 境界、実際の `--json-envelope` 出力要求を同じ fixture で維持してください。
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.Search.cs b/src/CodeIndex/Cli/QueryCommandRunner.Search.cs
index 9c346725a..9ee9cab90 100644
--- a/src/CodeIndex/Cli/QueryCommandRunner.Search.cs
+++ b/src/CodeIndex/Cli/QueryCommandRunner.Search.cs
@@ -755,311 +755,9 @@ and not OutputFormatCompact
         if (options.OutputFormat == OutputFormatIssueDrafts)
             return RunSearchIssueDrafts(options, jsonOptions, exactSearch, cancellationToken);
 
-        var exactSubstringHint = SearchQueryAdvisor.BuildExactSubstringHint(options.Query, options.RawFts, exactSearch, options.Prefix);
-        var ndjsonOptions = options.JsonOutputFormat == JsonOutputFormatNdjson ? GetCompactJsonOptions(jsonOptions) : jsonOptions;
-        string? jsonDoneTerminalLine = null;
-        return WithDb(options, jsonOptions, reader =>
-        {
-            if (options.GroupBy != null)
-            {
-                return RunGroupedSearchCount(reader, options, jsonOptions, exactSearch, exactSubstringHint);
-            }
-            if (options.CountBy != null || options.UniqueBy != null)
-            {
-                return RunSearchAggregation(reader, options, jsonOptions, exactSearch, exactSubstringHint);
-            }
-
-            if (options.CountOnly)
-            {
-                var counts = CountSearchMatches(reader, options, exactSearch);
-                var queryDiagnostics = DbReader.AnalyzeFtsQuery(options.Query, options.RawFts, options.Prefix, options.Lang);
-                if (counts.Count == 0)
-                {
-                    if (options.Json)
-                    {
-                        return WriteJsonObjectWithOptionalByteLimit(
-                            BuildCountJsonPayload(
-                                reader,
-                                jsonOptions,
-                                count: 0,
-                                files: 0,
-                                query: options.Query,
-                                queryOptions: options,
-                                ftsQueryDiagnostics: queryDiagnostics,
-                                exactSubstringHint: exactSubstringHint).ToJsonString(jsonOptions),
-                            options,
-                            "search count",
-                            "Narrow the query or increase --max-json-bytes.",
-                            jsonOptions);
-                    }
-                    else
-                    {
-                        Console.WriteLine("0");
-                        WriteExactSubstringHintIfNeeded(exactSubstringHint);
-                    }
-                    return CommandExitCodes.Success;
-                }
-
-                if (options.Json)
-                {
-                    return WriteJsonObjectWithOptionalByteLimit(
-                        BuildCountJsonPayload(
-                            reader,
-                            jsonOptions,
-                            counts.Count,
-                            counts.FileCount,
-                            query: options.Query,
-                            queryOptions: options,
-                            ftsQueryDiagnostics: queryDiagnostics,
-                            exactSubstringHint: exactSubstringHint).ToJsonString(jsonOptions),
-                        options,
-                        "search count",
-                        "Narrow the query or increase --max-json-bytes.",
-                        jsonOptions);
-                }
-                else
-                {
-                    Console.WriteLine($"{counts.Count}");
-                    WriteExactSubstringHintIfNeeded(exactSubstringHint);
-                }
-                return CommandExitCodes.Success;
-            }
-
-            var ftsQueryDiagnostics = DbReader.AnalyzeFtsQuery(options.Query, options.RawFts, options.Prefix, options.Lang);
-            var groupedCounts = options.OutputFormat == OutputFormatGrouped
-                ? CountSearchMatches(reader, options, exactSearch)
-                : default;
-            var displayRows = ReadSearchDisplayRows(reader, options, exactSearch, out var boundedSelection);
-            var sarifSourceRows = displayRows;
-            var selection = boundedSelection ?? ApplySearchOutputSelection(displayRows, options);
-            displayRows = selection.Rows;
-            if (displayRows.Count == 0)
-            {
-                if (options.Json && (options.OutputFormat == OutputFormatCsv || options.OutputFormat == OutputFormatTsv))
-                {
-                    WriteDelimitedSearchResults([], options);
-                    return ZeroResultExitCode(options);
-                }
-                if (options.Json && options.OutputFormat == OutputFormatGrouped)
-                {
-                    var groupedExitCode = WriteGroupedSearchResults([], groupedCounts, options, jsonOptions);
-                    return groupedExitCode == CommandExitCodes.Success ? ZeroResultExitCode(options) : groupedExitCode;
-                }
-                if (options.Json
-                    && options.OutputFormat == OutputFormatCompact
-                    && selection.Selectors.Count > 0)
-                {
-                    var compactExitCode = WriteCompactSearchResults([], options, jsonOptions, selection);
-                    return compactExitCode == CommandExitCodes.Success ? ZeroResultExitCode(options) : compactExitCode;
-                }
-                if (options.Json && TryWriteEmptySearchJsonWithOptionalByteLimit(options, jsonOptions, out var emptyJsonExitCode))
-                    return emptyJsonExitCode == CommandExitCodes.Success ? ZeroResultExitCode(options) : emptyJsonExitCode;
-                var emptySarifRunProperties = options.OutputFormat == OutputFormatSarif
-                    ? BuildAdHocSearchSarifRunProperties(
-                        options,
-                        selection,
-                        CountAdHocSearchSarifSourceResults(reader, options, exactSearch, sarifSourceRows),
-                        returnedResultCount: 0)
-                    : null;
-                if (options.Json && TryWriteEmptyFormattedResult(options, jsonOptions, emptySarifRunProperties))
-                    return ZeroResultExitCode(options);
-                if (options.Json)
-                {
-                    if (options.JsonOutputFormat == JsonOutputFormatArray)
-                    {
-                        return WriteJsonObjectWithOptionalByteLimit(
-                            JsonSerializer.Serialize(
-                                Array.Empty<CompactSearchResult>(),
-                                CliJsonSerializerContextFactory.Create(jsonOptions).CompactSearchResultArray),
-                            options,
-                            "search result array",
-                            "Increase --max-json-bytes or remove the byte cap.",
-                            jsonOptions);
-                    }
-                    else
-                    {
-                        var pathHint = BuildSearchPathGlobHint(reader, options);
-                        if (!options.ResultsOnly)
-                        {
-                            var payload = BuildJsonZeroResultPayload(
-                                reader,
-                                ndjsonOptions,
-                                resultsKey: "results",
-                                query: options.Query,
-                                ftsQueryDiagnostics: ftsQueryDiagnostics,
-                                queryOptions: options,
-                                exactSubstringHint: exactSubstringHint,
-                                extraFields: payload =>
-                                {
-                                    AddSearchPathHint(payload, pathHint);
-                                    AddBareTokenSearchHint(payload, options);
-                                }).ToJsonString(ndjsonOptions);
-                            var stream = WriteNdjsonStream(
-                                [new NdjsonOutputRecord(payload, CountsAsResult: false)],
-                                totalCount: 0,
-                                options,
-                                ndjsonOptions,
-                                reader,
-                                "search",
-                                limitTruncated: false,
-                                "Increase --limit or narrow the query to retrieve the remaining search results.",
-                                totalCountAuthoritative: false,
-                                sourceTotal: selection.Selectors.Count > 0 ? selection.SourceTotal : null,
-                                sourceTotalAuthoritative: selection.Selectors.Count > 0 ? selection.SourceTotalAuthoritative : null,
-                                selectedTotal: selection.Selectors.Count > 0 ? selection.SelectedTotal : null,
-                                selectorOmittedCount: selection.Selectors.Count > 0 ? selection.SelectorOmittedCount : null,
-                                limitOmittedCount: selection.Selectors.Count > 0 ? selection.LimitOmittedCount : null,
-                                selectors: selection.Selectors.Count > 0 ? selection.Selectors : null);
-                            jsonDoneTerminalLine = stream.TerminalLine;
-                            return stream.ExitCode == CommandExitCodes.Success ? ZeroResultExitCode(options) : stream.ExitCode;
-                        }
-                    }
-                }
-                else if (!options.Json)
-                {
-                    CommandErrorWriter.WriteStderr(BuildZeroResultLine("No results found", options));
-                    WriteLangHint(options.Lang, reader);
-                    WriteExactSubstringHintIfNeeded(exactSubstringHint);
-                    var pathHint = BuildSearchPathGlobHint(reader, options);
-                    WriteZeroResultHints(options, reader, filterHint: pathHint?.SuggestedAction);
-                }
-                return ZeroResultExitCode(options);
-            }
+        return ExecutePlainSearch(
+            CreateSearchExecutionPlan(options, jsonOptions, exactSearch, options.Query!));
 
-            if (options.Json)
-            {
-                var compactResults = displayRows.Select(row => row.Compact).ToArray();
-                AttachExactSubstringHint(compactResults, exactSubstringHint);
-                AttachSearchNextSteps(compactResults, options);
-                if (options.SearchFields != null)
-                {
-                    var projectedExitCode = WriteProjectedSearchResults(
-                        compactResults,
-                        selection.OriginalCount,
-                        selection.LimitTruncated,
-                        selection.LimitTruncated ? "limit" : null,
-                        selection.TruncationReason is "sample" or "first_per_file" ? selection.TruncationReason : null,
-                        selection.TruncationReason is "sample" or "first_per_file"
-                            ? selection.SelectionOmittedCount
-                            : null,
-                        selection.SourceTotal,
-                        selection.SourceTotalAuthoritative,
-                        selection.SelectedTotal,
-                        selection.SelectorOmittedCount,
-                        selection.LimitOmittedCount,
-                        selection.Selectors,
-                        options,
-                        jsonOptions,
-                        ndjsonOptions,
-                        reader,
-                        out jsonDoneTerminalLine);
-                    return projectedExitCode;
-                }
-                if (options.OutputFormat == OutputFormatCompact)
-                {
-                    return WriteCompactSearchResults(compactResults, options, jsonOptions, selection);
-                }
-                if (options.OutputFormat == OutputFormatGrouped)
-                {
-                    return WriteGroupedSearchResults(displayRows, groupedCounts, options, jsonOptions);
-                }
-                if (options.OutputFormat == OutputFormatCsv || options.OutputFormat == OutputFormatTsv)
-                {
-                    WriteDelimitedSearchResults(displayRows, options);
-                    return CommandExitCodes.Success;
-                }
-                if (TryWriteFormattedLocations(
-                    options,
-                    displayRows.SelectMany(row => ToSearchFormattedLocations(row, options.Query, exactSearch)).Take(options.Limit),
-                    jsonOptions))
-                    return CommandExitCodes.Success;
-                if (options.OutputFormat == OutputFormatLsp)
-                {
-                    WriteLspLocations(displayRows.SelectMany(row => ToSearchLspLocations(row, exactSearch)).Take(options.Limit), jsonOptions);
-                    return CommandExitCodes.Success;
-                }
-                if (options.OutputFormat == OutputFormatQf)
-                {
-                    WriteQuickfix(displayRows.SelectMany(row => ToSearchQuickfixItems(row, options.Query, exactSearch)).Take(options.Limit));
-                    return CommandExitCodes.Success;
-                }
-                if (options.OutputFormat == OutputFormatSarif)
-                {
-                    var sarifItems = displayRows
-                        .SelectMany(row => ToSearchSarifItems(row, options.Query, exactSearch))
-                        .Take(options.Limit)
-                        .ToList();
-                    var runProperties = BuildAdHocSearchSarifRunProperties(
-                        options,
-                        selection,
-                        CountAdHocSearchSarifSourceResults(reader, options, exactSearch, sarifSourceRows),
-                        sarifItems.Count);
-                    WriteSarif(sarifItems, jsonOptions, runProperties: runProperties);
-                    return CommandExitCodes.Success;
-                }
-                if (options.JsonOutputFormat == JsonOutputFormatArray)
-                {
-                    return WriteJsonObjectWithOptionalByteLimit(
-                        JsonSerializer.Serialize(
-                        compactResults,
-                            CliJsonSerializerContextFactory.Create(jsonOptions).CompactSearchResultArray),
-                        options,
-                        "search result array",
-                        "Reduce --limit, --snippet-lines, or use `--json=ndjson --max-json-bytes` for streaming output.",
-                        jsonOptions);
-                }
-                else
-                {
-                    return WriteSearchNdjsonResults(
-                        compactResults,
-                        selection.OriginalCount,
-                        selection.LimitTruncated,
-                        selection.LimitTruncated ? "limit" : null,
-                        selection.TruncationReason is "sample" or "first_per_file" ? selection.TruncationReason : null,
-                        selection.TruncationReason is "sample" or "first_per_file"
-                            ? selection.SelectionOmittedCount
-                            : null,
-                        selection.SourceTotal,
-                        selection.SourceTotalAuthoritative,
-                        selection.SelectedTotal,
-                        selection.SelectorOmittedCount,
-                        selection.LimitOmittedCount,
-                        selection.Selectors,
-                        options,
-                        ndjsonOptions,
-                        reader,
-                        out jsonDoneTerminalLine);
-                }
-            }
-            else
-            {
-                if (options.OutputFormat == OutputFormatGrouped)
-                {
-                    WriteGroupedSearchResultsHuman(displayRows, options);
-                }
-                else
-                {
-                    foreach (var row in displayRows)
-                    {
-                        var r = row.Result;
-                        Console.WriteLine($"{r.Path}:{r.StartLine}-{r.EndLine}{FormatSearchVisibilitySuffix(r.Visibility)}");
-                        var snippetLines = row.Compact.Snippet.Split('\n', StringSplitOptions.None);
-                        foreach (var line in snippetLines)
-                            Console.WriteLine($"  {line}");
-                        Console.WriteLine();
-                    }
-                }
-                var fileCount = displayRows.Select(row => row.Result.Path).Distinct().Count();
-                CommandErrorWriter.WriteStderr($"({displayRows.Count} results in {fileCount} files)");
-                WriteExactSubstringHintIfNeeded(exactSubstringHint);
-                WriteSearchNextSteps(displayRows, options);
-            }
-            return CommandExitCodes.Success;
-        }, exitCode =>
-        {
-            if (options.Json && options.JsonOutputFormat == JsonOutputFormatNdjson && jsonDoneTerminalLine != null && !options.ResultsOnly)
-                Console.WriteLine(jsonDoneTerminalLine);
-        });
     }
 
     private static List<string> FindUnexpectedRecipePositionals(string[] args)
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.SearchExecution.cs b/src/CodeIndex/Cli/QueryCommandRunner.SearchExecution.cs
new file mode 100644
index 000000000..f94492762
--- /dev/null
+++ b/src/CodeIndex/Cli/QueryCommandRunner.SearchExecution.cs
@@ -0,0 +1,168 @@
+using System.Text.Json;
+using CodeIndex.Database;
+using CodeIndex.Models;
+
+namespace CodeIndex.Cli;
+
+public static partial class QueryCommandRunner
+{
+    private sealed record SearchExecutionPlan(
+        QueryCommandOptions Options,
+        JsonSerializerOptions JsonOptions,
+        JsonSerializerOptions NdjsonOptions,
+        bool ExactSearch,
+        string Query,
+        SearchQueryHint? ExactSubstringHint);
+
+    private sealed record SearchRowExecution(
+        FtsQueryDiagnostics FtsQueryDiagnostics,
+        QueryCountResult GroupedCounts,
+        List<SearchDisplayRow> DisplayRows,
+        IReadOnlyList<SearchDisplayRow> SarifSourceRows,
+        SearchOutputSelection Selection);
+
+    private sealed class SearchExecutionOutcome
+    {
+        public string? JsonDoneTerminalLine { get; set; }
+    }
+
+    private static SearchExecutionPlan CreateSearchExecutionPlan(
+        QueryCommandOptions options,
+        JsonSerializerOptions jsonOptions,
+        bool exactSearch,
+        string query)
+    {
+        var exactSubstringHint = SearchQueryAdvisor.BuildExactSubstringHint(
+            query,
+            options.RawFts,
+            exactSearch,
+            options.Prefix);
+        var ndjsonOptions = options.JsonOutputFormat == JsonOutputFormatNdjson
+            ? GetCompactJsonOptions(jsonOptions)
+            : jsonOptions;
+        return new SearchExecutionPlan(
+            options,
+            jsonOptions,
+            ndjsonOptions,
+            exactSearch,
+            query,
+            exactSubstringHint);
+    }
+
+    private static int ExecutePlainSearch(SearchExecutionPlan plan)
+    {
+        var outcome = new SearchExecutionOutcome();
+        return WithDb(
+            plan.Options,
+            plan.JsonOptions,
+            reader => ExecutePlainSearch(reader, plan, outcome),
+            _ => WritePlainSearchTerminal(plan, outcome));
+    }
+
+    private static int ExecutePlainSearch(
+        DbReader reader,
+        SearchExecutionPlan plan,
+        SearchExecutionOutcome outcome)
+    {
+        var options = plan.Options;
+        if (options.GroupBy != null)
+        {
+            return RunGroupedSearchCount(
+                reader,
+                options,
+                plan.JsonOptions,
+                plan.ExactSearch,
+                plan.ExactSubstringHint);
+        }
+        if (options.CountBy != null || options.UniqueBy != null)
+        {
+            return RunSearchAggregation(
+                reader,
+                options,
+                plan.JsonOptions,
+                plan.ExactSearch,
+                plan.ExactSubstringHint);
+        }
+        if (options.CountOnly)
+            return WritePlainSearchCount(reader, plan);
+
+        var rows = PreparePlainSearchRows(reader, plan);
+        return rows.DisplayRows.Count == 0
+            ? WriteEmptyPlainSearchResults(reader, plan, rows, outcome)
+            : WritePlainSearchResults(reader, plan, rows, outcome);
+    }
+
+    private static int WritePlainSearchCount(DbReader reader, SearchExecutionPlan plan)
+    {
+        var options = plan.Options;
+        var counts = CountSearchMatches(reader, options, plan.ExactSearch);
+        var queryDiagnostics = DbReader.AnalyzeFtsQuery(
+            plan.Query,
+            options.RawFts,
+            options.Prefix,
+            options.Lang);
+        if (options.Json)
+        {
+            return WriteJsonObjectWithOptionalByteLimit(
+                BuildCountJsonPayload(
+                    reader,
+                    plan.JsonOptions,
+                    counts.Count,
+                    counts.FileCount,
+                    query: plan.Query,
+                    queryOptions: options,
+                    ftsQueryDiagnostics: queryDiagnostics,
+                    exactSubstringHint: plan.ExactSubstringHint).ToJsonString(plan.JsonOptions),
+                options,
+                "search count",
+                "Narrow the query or increase --max-json-bytes.",
+                plan.JsonOptions);
+        }
+
+        Console.WriteLine($"{counts.Count}");
+        WriteExactSubstringHintIfNeeded(plan.ExactSubstringHint);
+        return CommandExitCodes.Success;
+    }
+
+    private static SearchRowExecution PreparePlainSearchRows(
+        DbReader reader,
+        SearchExecutionPlan plan)
+    {
+        var options = plan.Options;
+        var ftsQueryDiagnostics = DbReader.AnalyzeFtsQuery(
+            plan.Query,
+            options.RawFts,
+            options.Prefix,
+            options.Lang);
+        var groupedCounts = options.OutputFormat == OutputFormatGrouped
+            ? CountSearchMatches(reader, options, plan.ExactSearch)
+            : default;
+        var displayRows = ReadSearchDisplayRows(
+            reader,
+            options,
+            plan.ExactSearch,
+            out var boundedSelection);
+        var sarifSourceRows = displayRows;
+        var selection = boundedSelection ?? ApplySearchOutputSelection(displayRows, options);
+        return new SearchRowExecution(
+            ftsQueryDiagnostics,
+            groupedCounts,
+            selection.Rows,
+            sarifSourceRows,
+            selection);
+    }
+
+    private static void WritePlainSearchTerminal(
+        SearchExecutionPlan plan,
+        SearchExecutionOutcome outcome)
+    {
+        var options = plan.Options;
+        if (options.Json
+            && options.JsonOutputFormat == JsonOutputFormatNdjson
+            && outcome.JsonDoneTerminalLine != null
+            && !options.ResultsOnly)
+        {
+            Console.WriteLine(outcome.JsonDoneTerminalLine);
+        }
+    }
+}
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.SearchOutput.cs b/src/CodeIndex/Cli/QueryCommandRunner.SearchOutput.cs
new file mode 100644
index 000000000..a4bca6b2f
--- /dev/null
+++ b/src/CodeIndex/Cli/QueryCommandRunner.SearchOutput.cs
@@ -0,0 +1,266 @@
+using System.Text.Json;
+using CodeIndex.Database;
+using CodeIndex.Models;
+
+namespace CodeIndex.Cli;
+
+public static partial class QueryCommandRunner
+{
+    private static int WriteEmptyPlainSearchResults(
+        DbReader reader,
+        SearchExecutionPlan plan,
+        SearchRowExecution rows,
+        SearchExecutionOutcome outcome)
+    {
+        var options = plan.Options;
+        var jsonOptions = plan.JsonOptions;
+        var ndjsonOptions = plan.NdjsonOptions;
+        var exactSearch = plan.ExactSearch;
+        var query = plan.Query;
+        var exactSubstringHint = plan.ExactSubstringHint;
+        var ftsQueryDiagnostics = rows.FtsQueryDiagnostics;
+        var groupedCounts = rows.GroupedCounts;
+        var displayRows = rows.DisplayRows;
+        var sarifSourceRows = rows.SarifSourceRows;
+        var selection = rows.Selection;
+        if (options.Json && (options.OutputFormat == OutputFormatCsv || options.OutputFormat == OutputFormatTsv))
+        {
+            WriteDelimitedSearchResults([], options);
+            return ZeroResultExitCode(options);
+        }
+        if (options.Json && options.OutputFormat == OutputFormatGrouped)
+        {
+            var groupedExitCode = WriteGroupedSearchResults([], groupedCounts, options, jsonOptions);
+            return groupedExitCode == CommandExitCodes.Success ? ZeroResultExitCode(options) : groupedExitCode;
+        }
+        if (options.Json
+            && options.OutputFormat == OutputFormatCompact
+            && selection.Selectors.Count > 0)
+        {
+            var compactExitCode = WriteCompactSearchResults([], options, jsonOptions, selection);
+            return compactExitCode == CommandExitCodes.Success ? ZeroResultExitCode(options) : compactExitCode;
+        }
+        if (options.Json && TryWriteEmptySearchJsonWithOptionalByteLimit(options, jsonOptions, out var emptyJsonExitCode))
+            return emptyJsonExitCode == CommandExitCodes.Success ? ZeroResultExitCode(options) : emptyJsonExitCode;
+        var emptySarifRunProperties = options.OutputFormat == OutputFormatSarif
+            ? BuildAdHocSearchSarifRunProperties(
+                options,
+                selection,
+                CountAdHocSearchSarifSourceResults(reader, options, exactSearch, sarifSourceRows),
+                returnedResultCount: 0)
+            : null;
+        if (options.Json && TryWriteEmptyFormattedResult(options, jsonOptions, emptySarifRunProperties))
+            return ZeroResultExitCode(options);
+        if (options.Json)
+        {
+            if (options.JsonOutputFormat == JsonOutputFormatArray)
+            {
+                return WriteJsonObjectWithOptionalByteLimit(
+                    JsonSerializer.Serialize(
+                        Array.Empty<CompactSearchResult>(),
+                        CliJsonSerializerContextFactory.Create(jsonOptions).CompactSearchResultArray),
+                    options,
+                    "search result array",
+                    "Increase --max-json-bytes or remove the byte cap.",
+                    jsonOptions);
+            }
+            else
+            {
+                var pathHint = BuildSearchPathGlobHint(reader, options);
+                if (!options.ResultsOnly)
+                {
+                    var payload = BuildJsonZeroResultPayload(
+                        reader,
+                        ndjsonOptions,
+                        resultsKey: "results",
+                        query: query,
+                        ftsQueryDiagnostics: ftsQueryDiagnostics,
+                        queryOptions: options,
+                        exactSubstringHint: exactSubstringHint,
+                        extraFields: payload =>
+                        {
+                            AddSearchPathHint(payload, pathHint);
+                            AddBareTokenSearchHint(payload, options);
+                        }).ToJsonString(ndjsonOptions);
+                    var stream = WriteNdjsonStream(
+                        [new NdjsonOutputRecord(payload, CountsAsResult: false)],
+                        totalCount: 0,
+                        options,
+                        ndjsonOptions,
+                        reader,
+                        "search",
+                        limitTruncated: false,
+                        "Increase --limit or narrow the query to retrieve the remaining search results.",
+                        totalCountAuthoritative: false,
+                        sourceTotal: selection.Selectors.Count > 0 ? selection.SourceTotal : null,
+                        sourceTotalAuthoritative: selection.Selectors.Count > 0 ? selection.SourceTotalAuthoritative : null,
+                        selectedTotal: selection.Selectors.Count > 0 ? selection.SelectedTotal : null,
+                        selectorOmittedCount: selection.Selectors.Count > 0 ? selection.SelectorOmittedCount : null,
+                        limitOmittedCount: selection.Selectors.Count > 0 ? selection.LimitOmittedCount : null,
+                        selectors: selection.Selectors.Count > 0 ? selection.Selectors : null);
+                    outcome.JsonDoneTerminalLine = stream.TerminalLine;
+                    return stream.ExitCode == CommandExitCodes.Success ? ZeroResultExitCode(options) : stream.ExitCode;
+                }
+            }
+        }
+        else if (!options.Json)
+        {
+            CommandErrorWriter.WriteStderr(BuildZeroResultLine("No results found", options));
+            WriteLangHint(options.Lang, reader);
+            WriteExactSubstringHintIfNeeded(exactSubstringHint);
+            var pathHint = BuildSearchPathGlobHint(reader, options);
+            WriteZeroResultHints(options, reader, filterHint: pathHint?.SuggestedAction);
+        }
+        return ZeroResultExitCode(options);
+    }
+
+    private static int WritePlainSearchResults(
+        DbReader reader,
+        SearchExecutionPlan plan,
+        SearchRowExecution rows,
+        SearchExecutionOutcome outcome)
+    {
+        var options = plan.Options;
+        var jsonOptions = plan.JsonOptions;
+        var ndjsonOptions = plan.NdjsonOptions;
+        var exactSearch = plan.ExactSearch;
+        var query = plan.Query;
+        var exactSubstringHint = plan.ExactSubstringHint;
+        var groupedCounts = rows.GroupedCounts;
+        var displayRows = rows.DisplayRows;
+        var sarifSourceRows = rows.SarifSourceRows;
+        var selection = rows.Selection;
+        if (options.Json)
+        {
+            var compactResults = displayRows.Select(row => row.Compact).ToArray();
+            AttachExactSubstringHint(compactResults, exactSubstringHint);
+            AttachSearchNextSteps(compactResults, options);
+            if (options.SearchFields != null)
+            {
+                var projectedExitCode = WriteProjectedSearchResults(
+                    compactResults,
+                    selection.OriginalCount,
+                    selection.LimitTruncated,
+                    selection.LimitTruncated ? "limit" : null,
+                    selection.TruncationReason is "sample" or "first_per_file" ? selection.TruncationReason : null,
+                    selection.TruncationReason is "sample" or "first_per_file"
+                        ? selection.SelectionOmittedCount
+                        : null,
+                    selection.SourceTotal,
+                    selection.SourceTotalAuthoritative,
+                    selection.SelectedTotal,
+                    selection.SelectorOmittedCount,
+                    selection.LimitOmittedCount,
+                    selection.Selectors,
+                    options,
+                    jsonOptions,
+                    ndjsonOptions,
+                    reader,
+                    out var projectedTerminalLine);
+                outcome.JsonDoneTerminalLine = projectedTerminalLine;
+                return projectedExitCode;
+            }
+            if (options.OutputFormat == OutputFormatCompact)
+            {
+                return WriteCompactSearchResults(compactResults, options, jsonOptions, selection);
+            }
+            if (options.OutputFormat == OutputFormatGrouped)
+            {
+                return WriteGroupedSearchResults(displayRows, groupedCounts, options, jsonOptions);
+            }
+            if (options.OutputFormat == OutputFormatCsv || options.OutputFormat == OutputFormatTsv)
+            {
+                WriteDelimitedSearchResults(displayRows, options);
+                return CommandExitCodes.Success;
+            }
+            if (TryWriteFormattedLocations(
+                options,
+                displayRows.SelectMany(row => ToSearchFormattedLocations(row, query, exactSearch)).Take(options.Limit),
+                jsonOptions))
+                return CommandExitCodes.Success;
+            if (options.OutputFormat == OutputFormatLsp)
+            {
+                WriteLspLocations(displayRows.SelectMany(row => ToSearchLspLocations(row, exactSearch)).Take(options.Limit), jsonOptions);
+                return CommandExitCodes.Success;
+            }
+            if (options.OutputFormat == OutputFormatQf)
+            {
+                WriteQuickfix(displayRows.SelectMany(row => ToSearchQuickfixItems(row, query, exactSearch)).Take(options.Limit));
+                return CommandExitCodes.Success;
+            }
+            if (options.OutputFormat == OutputFormatSarif)
+            {
+                var sarifItems = displayRows
+                    .SelectMany(row => ToSearchSarifItems(row, query, exactSearch))
+                    .Take(options.Limit)
+                    .ToList();
+                var runProperties = BuildAdHocSearchSarifRunProperties(
+                    options,
+                    selection,
+                    CountAdHocSearchSarifSourceResults(reader, options, exactSearch, sarifSourceRows),
+                    sarifItems.Count);
+                WriteSarif(sarifItems, jsonOptions, runProperties: runProperties);
+                return CommandExitCodes.Success;
+            }
+            if (options.JsonOutputFormat == JsonOutputFormatArray)
+            {
+                return WriteJsonObjectWithOptionalByteLimit(
+                    JsonSerializer.Serialize(
+                    compactResults,
+                        CliJsonSerializerContextFactory.Create(jsonOptions).CompactSearchResultArray),
+                    options,
+                    "search result array",
+                    "Reduce --limit, --snippet-lines, or use `--json=ndjson --max-json-bytes` for streaming output.",
+                    jsonOptions);
+            }
+            else
+            {
+                var ndjsonExitCode = WriteSearchNdjsonResults(
+                    compactResults,
+                    selection.OriginalCount,
+                    selection.LimitTruncated,
+                    selection.LimitTruncated ? "limit" : null,
+                    selection.TruncationReason is "sample" or "first_per_file" ? selection.TruncationReason : null,
+                    selection.TruncationReason is "sample" or "first_per_file"
+                        ? selection.SelectionOmittedCount
+                        : null,
+                    selection.SourceTotal,
+                    selection.SourceTotalAuthoritative,
+                    selection.SelectedTotal,
+                    selection.SelectorOmittedCount,
+                    selection.LimitOmittedCount,
+                    selection.Selectors,
+                    options,
+                    ndjsonOptions,
+                    reader,
+                    out var ndjsonTerminalLine);
+                outcome.JsonDoneTerminalLine = ndjsonTerminalLine;
+                return ndjsonExitCode;
+            }
+        }
+        else
+        {
+            if (options.OutputFormat == OutputFormatGrouped)
+            {
+                WriteGroupedSearchResultsHuman(displayRows, options);
+            }
+            else
+            {
+                foreach (var row in displayRows)
+                {
+                    var r = row.Result;
+                    Console.WriteLine($"{r.Path}:{r.StartLine}-{r.EndLine}{FormatSearchVisibilitySuffix(r.Visibility)}");
+                    var snippetLines = row.Compact.Snippet.Split('\n', StringSplitOptions.None);
+                    foreach (var line in snippetLines)
+                        Console.WriteLine($"  {line}");
+                    Console.WriteLine();
+                }
+            }
+            var fileCount = displayRows.Select(row => row.Result.Path).Distinct().Count();
+            CommandErrorWriter.WriteStderr($"({displayRows.Count} results in {fileCount} files)");
+            WriteExactSubstringHintIfNeeded(exactSubstringHint);
+            WriteSearchNextSteps(displayRows, options);
+        }
+        return CommandExitCodes.Success;
+    }
+}
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
index 6daba5e88..83dc21fbf 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
@@ -12712,6 +12712,92 @@ public void Run()
         }
     }
 
+    [Fact]
+    public void RunSearchCore_ValidationRoutingAndDatabaseExecutionRemainAligned()
+    {
+        var projectRoot = TestProjectHelper.CreateTempProject("cdidx_search_core_execution_alignment");
+        try
+        {
+            var dbPath = TestProjectHelper.CreateProjectDb(projectRoot);
+            TestProjectHelper.InsertIndexedFile(
+                dbPath,
+                "src/alignment.cs",
+                "csharp",
+                "public sealed class AlignmentFixture { public void AlignmentNeedle() { } }\n");
+            var invalidDbPath = TestProjectHelper.WriteTextFile(
+                projectRoot,
+                "invalid.db",
+                "not a SQLite database");
+
+            var (validationExitCode, validationStdout, validationStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
+                [
+                    "AlignmentNeedle",
+                    "--db", invalidDbPath,
+                    "--count",
+                    "--group-by", "file",
+                    "--count-by", "file"
+                ],
+                _jsonOptions));
+
+            Assert.Equal(CommandExitCodes.UsageError, validationExitCode);
+            Assert.Equal(string.Empty, validationStdout);
+            Assert.Contains("--group-by cannot be combined with --count-by or --unique", validationStderr);
+
+            var (zeroCountExitCode, zeroCountStdout, zeroCountStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
+                ["MissingNeedle", "--db", dbPath, "--count", "--json"],
+                _jsonOptions));
+            using (var zeroCountDocument = ParseJsonOutput(zeroCountStdout))
+            {
+                Assert.Equal(CommandExitCodes.Success, zeroCountExitCode);
+                Assert.Equal(string.Empty, zeroCountStderr);
+                Assert.Equal(0, zeroCountDocument.RootElement.GetProperty("count").GetInt32());
+                Assert.Equal(0, zeroCountDocument.RootElement.GetProperty("files").GetInt32());
+            }
+
+            var (countExitCode, countStdout, countStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
+                ["AlignmentNeedle", "--db", dbPath, "--count", "--json"],
+                _jsonOptions));
+            using (var countDocument = ParseJsonOutput(countStdout))
+            {
+                Assert.Equal(CommandExitCodes.Success, countExitCode);
+                Assert.Equal(string.Empty, countStderr);
+                Assert.Equal(1, countDocument.RootElement.GetProperty("count").GetInt32());
+                Assert.Equal(1, countDocument.RootElement.GetProperty("files").GetInt32());
+            }
+
+            var (plainExitCode, plainStdout, plainStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
+                ["AlignmentNeedle", "--db", dbPath, "--json", "--profile", "--slow-query-ms", "0"],
+                _jsonOptions));
+            var plainLines = plainStdout.Split(
+                '\n',
+                StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+
+            Assert.Equal(CommandExitCodes.Success, plainExitCode);
+            Assert.Equal(string.Empty, plainStderr);
+            Assert.Equal(3, plainLines.Length);
+            using (var resultDocument = JsonDocument.Parse(plainLines[0]))
+            using (var profileDocument = JsonDocument.Parse(plainLines[1]))
+            using (var terminalDocument = JsonDocument.Parse(plainLines[2]))
+            {
+                Assert.Equal("src/alignment.cs", resultDocument.RootElement.GetProperty("path").GetString());
+                Assert.True(profileDocument.RootElement.TryGetProperty("profile", out _));
+                Assert.True(IsJsonStreamDoneSentinel(terminalDocument.RootElement));
+            }
+
+            var (strictExitCode, strictStdout, strictStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
+                ["MissingNeedle", "--db", dbPath, "--strict-not-found"],
+                _jsonOptions));
+
+            Assert.Equal(CommandExitCodes.NotFound, strictExitCode);
+            Assert.Equal(string.Empty, strictStdout);
+            Assert.Contains("No results found", strictStderr);
+        }
+        finally
+        {
+            TestProjectHelper.DeleteDirectory(projectRoot);
+        }
+    }
+
     [Fact]
     public void RunSearch_ProfileEmitsSqlPhasesAndQueryPlan_Issue1643()
     {

From 77b12482b3a9f873409157aca2b7cc8cebccaaf9 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 23:17:57 +0900
Subject: [PATCH 33/45] Consolidate unused symbol surface classification

---
 TESTING_GUIDE.md                              |   2 +
 ...mbolReader.UnusedSymbols.Classification.cs | 650 ++++++++++++++++++
 .../Database/DbSymbolReader.UnusedSymbols.cs  | 608 ----------------
 .../DbReaderUnusedClassificationTests.cs      | 157 +++++
 4 files changed, 809 insertions(+), 608 deletions(-)
 create mode 100644 src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Classification.cs
 create mode 100644 tests/CodeIndex.Tests/DbReaderUnusedClassificationTests.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 5927a77a9..ae91a1ed2 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -204,6 +204,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   Hotspot ranking fixtures should use the smallest counts that cross each ranking threshold; for structural-rank tests, keep one side just above the raw-reference comparison and the other just above the symbol-count threshold instead of scaling both far beyond the boundary.
   Hotspot candidate-filter alignment is one public database-behavior contract across site, grouped, and file list/count queries. Keep visibility include/exclude filters before ambiguity cardinality, path include/exclude and test suppression after cardinality, authoritative family identity intact, and all six result/count shapes aligned. The structural SQL fixture separately pins the shared candidate plan to its explicit ten-column projection and forbids `SELECT *`.
   Unused-candidate query coverage must keep the SQL-aware and non-SQL paths aligned on the shared 17-column projection, provisional bucket ordering, scope filters, and parameter binding. Retain one mixed C#/SQL public-behavior fixture that proves SQL reference resolution, C# projection and null fallbacks, list/count agreement, and detailed bucket counts together; keep same-file/partial C# suppression and enum-collision scope in their focused fixtures.
+  Unused-symbol classification coverage must preserve surface-tag insertion order and contract-domain precedence when one symbol overlaps generated, contract-member, configuration, exception-metadata, public, and test signals. Keep those surface predicates evaluated once into the shared analysis, retain private/non-public early returns, and assert aligned reason tags, domain tags, and aggregate domain counts.
   Checkpoint listing and retention fixtures should exceed the relevant directory cap once and exceed the inspected-file cap on only one checkpoint; multiplying both caps together adds filesystem work without increasing boundary coverage. Checkpoint and restore-backup cleanup dry-run tests must assert both exact deleted/retained paths and the continued existence of every candidate directory. Restore dry-run tests should inject destination free space through `DbCommandRunner.AvailableFreeSpaceForTesting`, verify manifest and regular-file path diagnostics independently, and prove that no restore staging or backup directory is created.
   WAL checkpoint contention fixtures must establish a real read transaction before a later writer commit, then lower `busy_timeout` to keep the assertion bounded without fixed sleeps. Permission/error-path coverage may throw from `DbContext.WalCheckpointTruncateExecutedForTesting`; restore the previous `AsyncLocal` value in `finally` so parallel test state cannot leak.
 - `ConcurrencyTests.cs`
@@ -1269,6 +1270,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   hotspot ranking fixture は各 ranking threshold を跨ぐ最小 count を使ってください。structural-rank test では、raw reference 比較をわずかに超える側と symbol-count threshold をわずかに超える側を用意し、境界から大きく離れた件数まで膨らませないでください。
   hotspot candidate filter の整合性は、site / grouped / file の list / count 全6 query に共通する public database behavior 契約です。visibility include / exclude は ambiguity cardinality より前、path include / exclude と test suppression は cardinality より後に適用し、authoritative family identity と全6形状の結果・件数を一致させてください。structural SQL fixture は別途、共通 candidate plan の明示的な10列 projection と `SELECT *` 禁止を固定します。
   unused candidate query の coverage では、SQL-aware / non-SQL 経路で共通の17列 projection、provisional bucket 順、scope filter、parameter binding を一致させてください。mixed C#/SQL の public behavior fixture 1つで SQL reference resolution、C# projection と null fallback、list/count の一致、詳細 bucket count をまとめて固定し、same-file / partial C# suppression と enum collision scope は焦点を絞った既存 fixture で維持します。
+  unused symbol classification の coverage では、1つの symbol が generated、contract member、configuration、exception metadata、public、test の各 signal に重なる場合も、surface tag の追加順と contract domain の優先順位を維持してください。これらの surface predicate は共有 analysis へ1度だけ評価し、private / non-public の early return を保ったまま、reason tag、domain tag、domain 集計件数の一致を assertion します。
   checkpoint listing / retention fixture は対象の directory cap を 1 件だけ超え、inspected-file cap は 1 checkpoint だけで超えてください。両方の cap を掛け合わせても boundary coverage は増えず、filesystem work だけが増えます。checkpoint / restore-backup cleanup の dry-run test では、削除予定・保持予定の正確な path と、全候補 directory が引き続き存在することの両方を検証してください。restore dry-run test は `DbCommandRunner.AvailableFreeSpaceForTesting` で destination free space を注入し、manifest と regular-file path の diagnostic を独立に検証し、restore staging directory や backup directory が作られないことを固定します。
   WAL checkpoint contention fixture は後続 writer commit より先に実際の read transaction を確立し、固定 sleep を使わず assertion を bounded にするため `busy_timeout` を短くします。permission / error path の coverage では `DbContext.WalCheckpointTruncateExecutedForTesting` から exception を throw できますが、parallel test state を漏らさないよう、以前の `AsyncLocal` 値を `finally` で復元してください。
 - `ConcurrencyTests.cs`
diff --git a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Classification.cs b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Classification.cs
new file mode 100644
index 000000000..5a03bc408
--- /dev/null
+++ b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Classification.cs
@@ -0,0 +1,650 @@
+namespace CodeIndex.Database;
+
+public partial class DbReader
+{
+    private const string UnusedBucketLikelyPrivate = "likely_unused_private";
+    private const string UnusedBucketMaybeNonPublic = "maybe_unused_nonpublic";
+    private const string UnusedBucketPublicOrExported = "public_or_exported_no_refs";
+    private const string UnusedBucketReflectionOrConfig = "reflection_or_config_suspect";
+    private const string UnusedContractDomainPrivate = "private_or_file_local";
+    private const string UnusedContractDomainNonPublic = "nonpublic_internal";
+    private const string UnusedContractDomainPublicApi = "public_api_surface";
+    private const string UnusedContractDomainCli = "cli_contract";
+    private const string UnusedContractDomainJson = "json_contract";
+    private const string UnusedContractDomainMcp = "mcp_contract";
+    private const string UnusedContractDomainLsp = "lsp_contract";
+    private const string UnusedContractDomainConfig = "configuration_contract";
+    private const string UnusedContractDomainSerialization = "serialization_or_reflection_contract";
+    private const string UnusedContractDomainGenerated = "generated_code";
+    private const string UnusedContractDomainDocumentation = "documentation_surface";
+    private const string UnusedContractDomainTest = "test_contract";
+    private const string UnusedContractDomainFrameworkOverride = "framework_override";
+    private const string UnusedContractDomainExceptionDiagnostic = "exception_diagnostic";
+
+    private static readonly string[] UnusedContractPathSegments = ["/contracts/", "/contract/", "/dtos/", "/dto/", "/models/", "/model/", "/schemas/", "/schema/"];
+    private static readonly string[] UnusedRecordContractSuffixes =
+    [
+        "Dto",
+        "DTO",
+        "Request",
+        "Response",
+        "Result",
+        "Results",
+        "Model",
+        "Payload",
+        "Envelope",
+    ];
+    private static readonly string[] UnusedGeneratedPathMarkers =
+    [
+        ".g.cs",
+        ".generated.",
+        "/generated/",
+        "/obj/",
+        "/bin/",
+    ];
+    private static readonly string[] UnusedCliPathMarkers = ["/cli/", "/commands/", "/commandline/"];
+    private static readonly string[] UnusedMcpPathMarkers = ["/mcp/"];
+    private static readonly string[] UnusedLspPathMarkers = ["/lsp/", "/languageserver/"];
+    private static readonly string[] UnusedJsonContractTerms =
+    [
+        "Json",
+        "Dto",
+        "DTO",
+        "Request",
+        "Response",
+        "Result",
+        "Results",
+        "Payload",
+        "Envelope",
+        "Contract",
+        "Schema",
+    ];
+    private static readonly HashSet<string> UnusedFrameworkOverrideMemberNames = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "CanRead",
+        "CanSeek",
+        "CanWrite",
+        "Length",
+        "Position",
+        "Flush",
+        "FlushAsync",
+        "Read",
+        "ReadAsync",
+        "ReadByte",
+        "Seek",
+        "SetLength",
+        "Write",
+        "WriteAsync",
+        "WriteByte",
+        "Dispose",
+        "DisposeAsync",
+    };
+    private static readonly HashSet<string> UnusedExceptionMetadataNames = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "CharactersRead",
+        "Utf8BytesRead",
+        "SizeLimit",
+        "Limit",
+        "ByteCount",
+        "BytesRead",
+        "Offset",
+        "Position",
+        "Path",
+        "FileName",
+        "LineNumber",
+        "ColumnNumber",
+        "ActualSize",
+        "MaxSize",
+        "Length",
+    };
+    private static readonly string[] UnusedConfigMemberTerms =
+    [
+        "Configuration",
+        "Config",
+        "Options",
+        "Settings",
+        "Manifest",
+        "Schema",
+        "Metadata",
+        "Limit",
+        "Max",
+        "Min",
+        "Size",
+        "Bytes",
+        "Count",
+        "Capacity",
+        "Timeout",
+        "Version",
+        "Kind",
+        "Category",
+        "Severity",
+        "Source",
+        "Target",
+        "Path",
+        "Name",
+        "Id",
+        "Key",
+    ];
+
+    private static readonly string[] UnusedJsonContextSuffixes = ["JsonContext"];
+    private static readonly string[] UnusedJsonContextSignatureTerms = ["JsonSerializerContext", "JsonSerializable", "JsonSourceGenerationOptions"];
+    private static readonly string[] UnusedContractTypeSignatureTerms = ["DataContract", "Serializable", "MessagePackObject", "ProtoContract"];
+    private static readonly string[] UnusedContractMemberSignatureTerms = ["JsonProperty", "JsonInclude", "DataMember", "XmlElement", "XmlAttribute"];
+    private static readonly string[] UnusedConfigNameSuffixes = ["Options", "Settings", "Configuration", "Config", "Manifest", "Schema"];
+    private static readonly string[] UnusedConfigNameTerms = ["Configuration", "IOptions"];
+    private static readonly string[] UnusedConfigSignatureTerms = ["IConfiguration", "ConfigurationSection", "IOptions", "Options<"];
+    private static readonly string[] UnusedConfigPathSegments = ["/config/", "/configuration/", "/options/", "/settings/", "/manifest/", "/manifests/"];
+    private static readonly string[] UnusedMetadataSignatureTerms = ["JsonProperty", "JsonInclude", "DataMember", "Diagnostic", "Metadata", "IConfiguration", "IOptions", "Options<"];
+    private static readonly string[] UnusedExceptionSuffixes = ["Exception"];
+    private static readonly string[] UnusedTestContainerSuffixes = ["Test", "Tests", "Fixture"];
+    private static readonly string[] UnusedFrameworkOverrideSignatureTerms = [" override ", " override\t", " override\r", " override\n"];
+    private static readonly string[] UnusedFrameworkContainerSuffixes = ["Stream", "TextReader", "TextWriter"];
+    private static readonly string[] UnusedMcpContractTerms = ["Mcp", "JsonRpc"];
+    private static readonly string[] UnusedLspContractTerms = ["Lsp", "LanguageServer"];
+    private static readonly string[] UnusedCliContractTerms = ["Cli", "CommandLine"];
+    private static readonly string[] UnusedCliSignatureTerms = ["CommandLine", "System.CommandLine", "Option<", "Argument<"];
+    private static readonly string[] UnusedCliContractSuffixes = ["Command", "Flag", "Flags", "Usage", "ExitCode", "ErrorCode"];
+    private static readonly string[] UnusedJsonSignatureTerms =
+    [
+        "JsonProperty",
+        "JsonInclude",
+        "JsonSerializerContext",
+        "DataContract",
+        "DataMember",
+        "XmlElement",
+        "XmlAttribute",
+        "YamlMember",
+        "MessagePackObject",
+        "ProtoContract",
+    ];
+
+    internal static readonly string[] OrderedUnusedContractDomains =
+    [
+        UnusedContractDomainPrivate,
+        UnusedContractDomainNonPublic,
+        UnusedContractDomainPublicApi,
+        UnusedContractDomainCli,
+        UnusedContractDomainJson,
+        UnusedContractDomainMcp,
+        UnusedContractDomainLsp,
+        UnusedContractDomainConfig,
+        UnusedContractDomainSerialization,
+        UnusedContractDomainGenerated,
+        UnusedContractDomainDocumentation,
+        UnusedContractDomainTest,
+        UnusedContractDomainFrameworkOverride,
+        UnusedContractDomainExceptionDiagnostic,
+    ];
+
+    private static readonly string[] OrderedUnusedBuckets =
+    [
+        UnusedBucketLikelyPrivate,
+        UnusedBucketMaybeNonPublic,
+        UnusedBucketPublicOrExported,
+        UnusedBucketReflectionOrConfig,
+    ];
+
+    [Flags]
+    private enum UnusedSurfaceFlags : ushort
+    {
+        None = 0,
+        ReflectionOrConfigSuspect = 1 << 0,
+        DocumentationHeading = 1 << 1,
+        MarkdownFenceLanguageMarker = 1 << 2,
+        GeneratedSurface = 1 << 3,
+        SerializationContract = 1 << 4,
+        SourceGeneratedJsonContext = 1 << 5,
+        ContractMember = 1 << 6,
+        ConfigOrMetadataSurface = 1 << 7,
+        TestHook = 1 << 8,
+        ExceptionMetadata = 1 << 9,
+        ConfigOrMetadataMember = 1 << 10,
+    }
+
+    private readonly record struct UnusedSurfaceAnalysis(UnusedSurfaceFlags Flags, List<string> Tags);
+    private readonly record struct UnusedContractDomainClassification(string Domain, List<string> Tags);
+    private UnusedSymbolResult CreateUnusedSymbolResult(UnusedCandidateSymbol candidate)
+    {
+        var kind = NormalizeUnusedSymbolKind(candidate);
+        var surface = AnalyzeUnusedSurfaces(candidate, kind);
+        var classification = ClassifyUnusedSymbol(
+            candidate.IsPublicOrExported,
+            surface.Tags.Count > 0,
+            candidate.Visibility);
+        var reasonTags = BuildUnusedReasonTags(candidate, surface);
+        var contractDomain = ClassifyUnusedContractDomain(
+            candidate,
+            kind,
+            classification.Bucket,
+            surface);
+        return new UnusedSymbolResult
+        {
+            Path = candidate.Path,
+            Lang = candidate.Lang,
+            Kind = kind,
+            Name = candidate.Name,
+            Line = candidate.Line,
+            StartLine = candidate.StartLine,
+            EndLine = candidate.EndLine,
+            Signature = candidate.Signature,
+            Visibility = candidate.Visibility,
+            ReturnType = candidate.ReturnType,
+            ContainerKind = candidate.ContainerKind,
+            ContainerName = candidate.ContainerName,
+            UnusedBucket = classification.Bucket,
+            UnusedConfidence = classification.Confidence,
+            UnusedReason = classification.Reason,
+            UnusedReasonTags = reasonTags,
+            UnusedContractDomain = contractDomain.Domain,
+            UnusedContractDomainTags = contractDomain.Tags,
+        };
+    }
+
+    private UnusedSurfaceAnalysis AnalyzeUnusedSurfaces(
+        UnusedCandidateSymbol candidate,
+        string kind)
+    {
+        var flags = UnusedSurfaceFlags.None;
+        var tags = new List<string>();
+        if (candidate.IsReflectionOrConfigSuspect)
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.ReflectionOrConfigSuspect, tags, "reflection_or_config_suspect");
+        if (IsMarkdownHeadingSymbol(candidate, kind))
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.DocumentationHeading, tags, "documentation_heading");
+        if (IsMarkdownFenceSymbol(candidate, kind))
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.MarkdownFenceLanguageMarker, tags, "markdown_fence_language_marker");
+        if (IsGeneratedSurface(candidate))
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.GeneratedSurface, tags, "generated_surface");
+        AddUnusedSerializationSurfaces(candidate, kind, ref flags, tags);
+        if (IsConfigOrManifestSurface(candidate, kind))
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.ConfigOrMetadataSurface, tags, "config_or_metadata_surface");
+        if (IsTestHookName(candidate.Name))
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.TestHook, tags, "test_hook");
+        if (IsExceptionMetadataProperty(candidate, kind))
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.ExceptionMetadata, tags, "exception_metadata");
+        if (IsConfigOrMetadataMember(candidate, kind))
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.ConfigOrMetadataMember, tags, "config_or_metadata_member");
+        if ((flags & UnusedSurfaceFlags.ReflectionOrConfigSuspect) == 0
+            && candidate.IsPublicOrExported
+            && HasReflectionAttributeContext(kind, candidate.Path, candidate.StartLine))
+        {
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.ReflectionOrConfigSuspect, tags, "reflection_or_config_suspect");
+        }
+        return new UnusedSurfaceAnalysis(flags, tags);
+    }
+
+    private static void AddUnusedSerializationSurfaces(
+        UnusedCandidateSymbol candidate,
+        string kind,
+        ref UnusedSurfaceFlags flags,
+        List<string> tags)
+    {
+        if (IsSourceGeneratedJsonContext(candidate))
+        {
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.SerializationContract, tags, "serialization_contract");
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.SourceGeneratedJsonContext, tags, "source_generated_json_context");
+        }
+        if (IsUnusedContractType(candidate, kind))
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.SerializationContract, tags, "serialization_contract");
+        if (IsUnusedContractMember(candidate, kind))
+            AddUnusedSurface(ref flags, UnusedSurfaceFlags.ContractMember, tags, "contract_member");
+    }
+
+    private static void AddUnusedSurface(
+        ref UnusedSurfaceFlags flags,
+        UnusedSurfaceFlags flag,
+        List<string> tags,
+        string tag)
+    {
+        flags |= flag;
+        AddUnusedSurfaceTag(tags, tag);
+    }
+
+    private static void AddUnusedSurfaceTag(List<string> tags, string tag)
+    {
+        if (!tags.Contains(tag, StringComparer.Ordinal))
+            tags.Add(tag);
+    }
+
+    private static (string Bucket, string Confidence, string Reason) ClassifyUnusedSymbol(
+        bool isPublicOrExported,
+        bool isIntentionalSurfaceSuspect,
+        string? visibility)
+    {
+        if (isIntentionalSurfaceSuspect)
+        {
+            return (
+                UnusedBucketReflectionOrConfig,
+                "low",
+                "symbol with attribute-driven reflection surface, serialization, config, metadata, test-hook, generated, documentation, or compatibility surface and no indexed references");
+        }
+        if (isPublicOrExported)
+            return (UnusedBucketPublicOrExported, "low", "public/exported symbol with no indexed references");
+        if (IsPrivateLikeVisibility(visibility))
+        {
+            return (
+                UnusedBucketLikelyPrivate,
+                "medium",
+                "private/file-local symbol with no indexed references after same-file text validation");
+        }
+        return (UnusedBucketMaybeNonPublic, "low", "non-public symbol with no indexed references");
+    }
+
+    private static List<string> BuildUnusedReasonTags(
+        UnusedCandidateSymbol candidate,
+        UnusedSurfaceAnalysis surface)
+    {
+        var tags = new List<string> { "no_indexed_references" };
+        if (surface.Tags.Count > 0)
+        {
+            tags.Add("intentional_surface_suspect");
+            tags.Add("reflection_or_config_suspect");
+        }
+        foreach (var surfaceTag in surface.Tags)
+            AddUnusedSurfaceTag(tags, surfaceTag);
+        if (candidate.IsPublicOrExported)
+            tags.Add("public_or_exported");
+        else if (IsPrivateLikeVisibility(candidate.Visibility))
+            tags.Add("private_or_file_local");
+        else
+            tags.Add("non_public");
+        return tags;
+    }
+
+    private static UnusedContractDomainClassification ClassifyUnusedContractDomain(
+        UnusedCandidateSymbol candidate,
+        string kind,
+        string bucket,
+        UnusedSurfaceAnalysis surface)
+    {
+        var tags = new List<string>();
+        if (string.Equals(bucket, UnusedBucketReflectionOrConfig, StringComparison.Ordinal))
+            AddUnusedSurfaceTag(tags, "intentional_surface_suspect");
+        foreach (var surfaceTag in surface.Tags)
+            AddUnusedSurfaceTag(tags, surfaceTag);
+
+        if (IsPrivateLikeVisibility(candidate.Visibility))
+            return CreateUnusedContractDomain(UnusedContractDomainPrivate, tags, "private_or_file_local");
+        if (!candidate.IsPublicOrExported && surface.Tags.Count == 0)
+            return CreateUnusedContractDomain(UnusedContractDomainNonPublic, tags, "nonpublic_or_protected");
+
+        AddUnusedSurfaceTag(tags, candidate.IsPublicOrExported ? "public_or_exported" : "nonpublic_or_protected");
+        return ClassifyExposedUnusedContractDomain(candidate, kind, surface, tags);
+    }
+
+    private static UnusedContractDomainClassification ClassifyExposedUnusedContractDomain(
+        UnusedCandidateSymbol candidate,
+        string kind,
+        UnusedSurfaceAnalysis surface,
+        List<string> tags)
+    {
+        if (HasUnusedSurface(surface, UnusedSurfaceFlags.DocumentationHeading))
+            return CreateUnusedContractDomain(UnusedContractDomainDocumentation, tags, "documentation_heading");
+        if (HasUnusedSurface(surface, UnusedSurfaceFlags.MarkdownFenceLanguageMarker))
+            return CreateUnusedContractDomain(UnusedContractDomainDocumentation, tags, "markdown_fence_language_marker");
+        if (IsUnusedTestContractSurface(candidate, surface))
+            return CreateUnusedContractDomain(UnusedContractDomainTest, tags, "test_surface");
+        if (HasUnusedSurface(surface, UnusedSurfaceFlags.GeneratedSurface))
+            return CreateUnusedContractDomain(UnusedContractDomainGenerated, tags, "generated_surface");
+        if (IsExceptionDiagnosticSurface(candidate, kind, surface))
+            return CreateUnusedContractDomain(UnusedContractDomainExceptionDiagnostic, tags, "exception_metadata");
+        if (IsFrameworkOverrideSurface(candidate))
+            return CreateUnusedContractDomain(UnusedContractDomainFrameworkOverride, tags, "framework_override");
+        if (IsMcpContractSurface(candidate))
+            return CreateUnusedContractDomain(UnusedContractDomainMcp, tags, "mcp_tool_contract");
+        if (IsLspContractSurface(candidate))
+            return CreateUnusedContractDomain(UnusedContractDomainLsp, tags, "lsp_protocol_contract");
+        if (IsCliContractSurface(candidate))
+            return CreateUnusedContractDomain(UnusedContractDomainCli, tags, "cli_option_or_result");
+        if (IsConfigurationContractSurface(surface))
+            return CreateUnusedContractDomain(UnusedContractDomainConfig, tags, "configuration_or_metadata_contract");
+        if (IsJsonContractSurface(candidate, surface))
+            return CreateUnusedContractDomain(UnusedContractDomainJson, tags, "json_output_or_input_contract");
+        if (HasUnusedSurface(surface, UnusedSurfaceFlags.ReflectionOrConfigSuspect))
+            return CreateUnusedContractDomain(UnusedContractDomainSerialization, tags, "reflection_or_serialization_contract");
+        return candidate.IsPublicOrExported
+            ? CreateUnusedContractDomain(UnusedContractDomainPublicApi, tags, "public_api_surface")
+            : CreateUnusedContractDomain(UnusedContractDomainNonPublic, tags, "nonpublic_or_protected");
+    }
+
+    private static UnusedContractDomainClassification CreateUnusedContractDomain(
+        string domain,
+        List<string> tags,
+        string domainTag)
+    {
+        AddUnusedSurfaceTag(tags, domain);
+        AddUnusedSurfaceTag(tags, domainTag);
+        return new UnusedContractDomainClassification(domain, tags);
+    }
+
+    private static bool HasUnusedSurface(UnusedSurfaceAnalysis surface, UnusedSurfaceFlags flag)
+        => (surface.Flags & flag) != 0;
+
+    private static bool IsMarkdownHeadingSymbol(UnusedCandidateSymbol candidate, string kind)
+    {
+        return (string.Equals(candidate.Lang, "markdown", StringComparison.OrdinalIgnoreCase)
+                || string.Equals(candidate.Lang, "md", StringComparison.OrdinalIgnoreCase))
+            && (kind.Contains("heading", StringComparison.OrdinalIgnoreCase)
+                || kind.Contains("header", StringComparison.OrdinalIgnoreCase));
+    }
+
+    private static bool IsMarkdownFenceSymbol(UnusedCandidateSymbol candidate, string kind)
+    {
+        if ((!string.Equals(candidate.Lang, "markdown", StringComparison.OrdinalIgnoreCase)
+                && !string.Equals(candidate.Lang, "md", StringComparison.OrdinalIgnoreCase))
+            || !string.Equals(kind, "code", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+        var signature = candidate.Signature?.TrimStart();
+        return signature?.StartsWith("```", StringComparison.Ordinal) == true
+            || signature?.StartsWith("~~~", StringComparison.Ordinal) == true;
+    }
+
+    private static bool IsGeneratedSurface(UnusedCandidateSymbol candidate)
+        => ContainsAny(candidate.Path, UnusedGeneratedPathMarkers);
+
+    private static bool IsSourceGeneratedJsonContext(UnusedCandidateSymbol candidate)
+        => EndsWithAny(candidate.Name, UnusedJsonContextSuffixes)
+            || ContainsAny(candidate.Signature, UnusedJsonContextSignatureTerms);
+
+    private static bool IsUnusedContractType(UnusedCandidateSymbol candidate, string kind)
+    {
+        if (!IsTypeLikeUnusedKind(kind) || IsPrivateLikeVisibility(candidate.Visibility))
+            return false;
+        return ContainsAny(candidate.Path, UnusedContractPathSegments)
+            || IsRecordContractType(candidate)
+            || ContainsAny(candidate.Signature, UnusedContractTypeSignatureTerms);
+    }
+
+    private static bool IsUnusedContractMember(UnusedCandidateSymbol candidate, string kind)
+    {
+        if (!IsDataMemberUnusedKind(kind) || IsPrivateLikeVisibility(candidate.Visibility))
+            return false;
+        return ContainsAny(candidate.Path, UnusedContractPathSegments)
+            || ContainsAny(candidate.Signature, UnusedContractMemberSignatureTerms);
+    }
+
+    private static bool IsConfigOrManifestSurface(UnusedCandidateSymbol candidate, string kind)
+    {
+        if (IsPrivateLikeVisibility(candidate.Visibility))
+            return false;
+        if (!IsTypeLikeUnusedKind(kind) && !IsDataMemberUnusedKind(kind) && !IsFunctionLikeUnusedKind(kind))
+            return false;
+        if (EndsWithAny(candidate.Name, UnusedConfigNameSuffixes)
+            || ContainsAny(candidate.Name, UnusedConfigNameTerms)
+            || ContainsAny(candidate.Signature, UnusedConfigSignatureTerms))
+        {
+            return true;
+        }
+        return IsDataMemberUnusedKind(kind)
+            && (ContainsAny(candidate.Path, UnusedConfigPathSegments)
+                || ContainsAny(candidate.Signature, UnusedConfigSignatureTerms));
+    }
+
+    private static bool IsTestHookName(string? name)
+    {
+        return !string.IsNullOrWhiteSpace(name)
+            && (name.EndsWith("ForTests", StringComparison.OrdinalIgnoreCase)
+                || name.Contains("ForTest", StringComparison.OrdinalIgnoreCase)
+                || name.Contains("TestOnly", StringComparison.OrdinalIgnoreCase));
+    }
+
+    private static bool IsExceptionMetadataProperty(UnusedCandidateSymbol candidate, string kind)
+    {
+        return string.Equals(kind, "property", StringComparison.OrdinalIgnoreCase)
+            && UnusedExceptionMetadataNames.Contains(candidate.Name)
+            && (EndsWithAny(candidate.ContainerName, UnusedExceptionSuffixes)
+                || ContainsAny(candidate.ContainerQualifiedName, UnusedExceptionSuffixes)
+                || ContainsAny(candidate.Signature, UnusedExceptionSuffixes));
+    }
+
+    private static bool IsConfigOrMetadataMember(UnusedCandidateSymbol candidate, string kind)
+    {
+        if (!IsDataMemberUnusedKind(kind) || IsPrivateLikeVisibility(candidate.Visibility))
+            return false;
+        if (!ContainsAny(candidate.Name, UnusedConfigMemberTerms))
+            return false;
+        return ContainsAny(candidate.Path, UnusedContractPathSegments)
+            || ContainsAny(candidate.Path, UnusedConfigPathSegments)
+            || ContainsAny(candidate.Signature, UnusedMetadataSignatureTerms);
+    }
+
+    private static bool IsTypeLikeUnusedKind(string kind)
+        => kind is "class" or "struct" or "record" or "interface" or "enum" or "type";
+
+    private static bool IsDataMemberUnusedKind(string kind)
+        => kind is "property" or "field" or "constant" or "enum_member";
+
+    private static bool IsFunctionLikeUnusedKind(string kind)
+        => kind is "function" or "method";
+
+    private static bool IsRecordContractType(UnusedCandidateSymbol candidate)
+        => ContainsCSharpRecordKeyword(candidate.Signature)
+            && EndsWithAny(candidate.Name, UnusedRecordContractSuffixes);
+
+    private static bool ContainsCSharpRecordKeyword(string? signature)
+    {
+        if (string.IsNullOrWhiteSpace(signature))
+            return false;
+        var trimmed = signature.TrimStart();
+        return trimmed.StartsWith("record ", StringComparison.Ordinal)
+            || trimmed.StartsWith("record(", StringComparison.Ordinal)
+            || signature.Contains(" record ", StringComparison.Ordinal)
+            || signature.Contains(" record(", StringComparison.Ordinal);
+    }
+
+    private static bool EndsWithAny(string? value, IReadOnlyList<string> suffixes)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            return false;
+        foreach (var suffix in suffixes)
+        {
+            if (value.EndsWith(suffix, StringComparison.OrdinalIgnoreCase))
+                return true;
+        }
+        return false;
+    }
+
+    private static bool ContainsAny(string? value, IReadOnlyList<string> fragments)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            return false;
+        foreach (var fragment in fragments)
+        {
+            if (value.Contains(fragment, StringComparison.OrdinalIgnoreCase))
+                return true;
+        }
+        return false;
+    }
+
+    private static bool IsUnusedTestContractSurface(
+        UnusedCandidateSymbol candidate,
+        UnusedSurfaceAnalysis surface)
+    {
+        return IsUnusedTestPath(candidate.Path)
+            || EndsWithAny(candidate.ContainerName, UnusedTestContainerSuffixes)
+            || EndsWithAny(candidate.ContainerQualifiedName, UnusedTestContainerSuffixes)
+            || HasUnusedSurface(surface, UnusedSurfaceFlags.TestHook);
+    }
+
+    private static bool IsUnusedTestPath(string? path)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return false;
+        var normalized = path.Replace('\\', '/');
+        return normalized.StartsWith("test/", StringComparison.OrdinalIgnoreCase)
+            || normalized.StartsWith("tests/", StringComparison.OrdinalIgnoreCase)
+            || normalized.Contains("/test/", StringComparison.OrdinalIgnoreCase)
+            || normalized.Contains("/tests/", StringComparison.OrdinalIgnoreCase)
+            || normalized.Contains(".tests/", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static bool IsExceptionDiagnosticSurface(
+        UnusedCandidateSymbol candidate,
+        string kind,
+        UnusedSurfaceAnalysis surface)
+    {
+        return HasUnusedSurface(surface, UnusedSurfaceFlags.ExceptionMetadata)
+            || (IsDataMemberUnusedKind(kind)
+                && (EndsWithAny(candidate.ContainerName, UnusedExceptionSuffixes)
+                    || EndsWithAny(candidate.ContainerQualifiedName, UnusedExceptionSuffixes)))
+            || (IsTypeLikeUnusedKind(kind) && EndsWithAny(candidate.Name, UnusedExceptionSuffixes));
+    }
+
+    private static bool IsFrameworkOverrideSurface(UnusedCandidateSymbol candidate)
+    {
+        if (ContainsAny(candidate.Signature, UnusedFrameworkOverrideSignatureTerms))
+            return true;
+        if (!UnusedFrameworkOverrideMemberNames.Contains(candidate.Name))
+            return false;
+        return EndsWithAny(candidate.ContainerName, UnusedFrameworkContainerSuffixes)
+            || EndsWithAny(candidate.ContainerQualifiedName, UnusedFrameworkContainerSuffixes)
+            || ContainsAny(candidate.Signature, UnusedFrameworkContainerSuffixes);
+    }
+
+    private static bool IsMcpContractSurface(UnusedCandidateSymbol candidate)
+        => ContainsAny(candidate.Path, UnusedMcpPathMarkers)
+            || ContainsAny(candidate.ContainerName, UnusedMcpContractTerms)
+            || ContainsAny(candidate.ContainerQualifiedName, UnusedMcpContractTerms)
+            || ContainsAny(candidate.Signature, UnusedMcpContractTerms);
+
+    private static bool IsLspContractSurface(UnusedCandidateSymbol candidate)
+        => ContainsAny(candidate.Path, UnusedLspPathMarkers)
+            || ContainsAny(candidate.ContainerName, UnusedLspContractTerms)
+            || ContainsAny(candidate.ContainerQualifiedName, UnusedLspContractTerms)
+            || ContainsAny(candidate.Signature, UnusedLspContractTerms);
+
+    private static bool IsCliContractSurface(UnusedCandidateSymbol candidate)
+    {
+        var hasCliContext = ContainsAny(candidate.Path, UnusedCliPathMarkers)
+            || ContainsAny(candidate.ContainerQualifiedName, UnusedCliContractTerms)
+            || ContainsAny(candidate.Signature, UnusedCliSignatureTerms);
+        if (hasCliContext)
+            return true;
+        return EndsWithAny(candidate.Name, UnusedCliContractSuffixes)
+            || EndsWithAny(candidate.ContainerName, UnusedCliContractSuffixes);
+    }
+
+    private static bool IsConfigurationContractSurface(UnusedSurfaceAnalysis surface)
+        => HasUnusedSurface(surface, UnusedSurfaceFlags.ConfigOrMetadataSurface)
+            || HasUnusedSurface(surface, UnusedSurfaceFlags.ConfigOrMetadataMember);
+
+    private static bool IsJsonContractSurface(
+        UnusedCandidateSymbol candidate,
+        UnusedSurfaceAnalysis surface)
+    {
+        return HasUnusedSurface(surface, UnusedSurfaceFlags.SerializationContract)
+            || HasUnusedSurface(surface, UnusedSurfaceFlags.ContractMember)
+            || HasUnusedSurface(surface, UnusedSurfaceFlags.SourceGeneratedJsonContext)
+            || ContainsAny(candidate.Path, UnusedContractPathSegments)
+            || EndsWithAny(candidate.Name, UnusedRecordContractSuffixes)
+            || EndsWithAny(candidate.ContainerName, UnusedRecordContractSuffixes)
+            || ContainsAny(candidate.Name, UnusedJsonContractTerms)
+            || ContainsAny(candidate.ContainerName, UnusedJsonContractTerms)
+            || ContainsAny(candidate.Signature, UnusedJsonSignatureTerms);
+    }
+
+    private static bool IsPrivateLikeVisibility(string? visibility)
+        => string.Equals(visibility, "private", StringComparison.OrdinalIgnoreCase)
+            || string.Equals(visibility, "fileprivate", StringComparison.OrdinalIgnoreCase);
+}
diff --git a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
index 2cfdbaccb..45d8c4c13 100644
--- a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
@@ -126,41 +126,6 @@ FROM symbols {ancestorAlias}
                 ), '')";
     }
 
-    private const string UnusedBucketLikelyPrivate = "likely_unused_private";
-    private const string UnusedBucketMaybeNonPublic = "maybe_unused_nonpublic";
-    private const string UnusedBucketPublicOrExported = "public_or_exported_no_refs";
-    private const string UnusedBucketReflectionOrConfig = "reflection_or_config_suspect";
-    private const string UnusedContractDomainPrivate = "private_or_file_local";
-    private const string UnusedContractDomainNonPublic = "nonpublic_internal";
-    private const string UnusedContractDomainPublicApi = "public_api_surface";
-    private const string UnusedContractDomainCli = "cli_contract";
-    private const string UnusedContractDomainJson = "json_contract";
-    private const string UnusedContractDomainMcp = "mcp_contract";
-    private const string UnusedContractDomainLsp = "lsp_contract";
-    private const string UnusedContractDomainConfig = "configuration_contract";
-    private const string UnusedContractDomainSerialization = "serialization_or_reflection_contract";
-    private const string UnusedContractDomainGenerated = "generated_code";
-    private const string UnusedContractDomainDocumentation = "documentation_surface";
-    private const string UnusedContractDomainTest = "test_contract";
-    private const string UnusedContractDomainFrameworkOverride = "framework_override";
-    private const string UnusedContractDomainExceptionDiagnostic = "exception_diagnostic";
-    internal static readonly string[] OrderedUnusedContractDomains =
-    [
-        UnusedContractDomainPrivate,
-        UnusedContractDomainNonPublic,
-        UnusedContractDomainPublicApi,
-        UnusedContractDomainCli,
-        UnusedContractDomainJson,
-        UnusedContractDomainMcp,
-        UnusedContractDomainLsp,
-        UnusedContractDomainConfig,
-        UnusedContractDomainSerialization,
-        UnusedContractDomainGenerated,
-        UnusedContractDomainDocumentation,
-        UnusedContractDomainTest,
-        UnusedContractDomainFrameworkOverride,
-        UnusedContractDomainExceptionDiagnostic,
-    ];
     private static readonly HashSet<string> ReflectionPropertyAttributeNames = new(StringComparer.Ordinal)
     {
         "jsonpropertyname",
@@ -247,120 +212,6 @@ FROM symbols {ancestorAlias}
         "return",
         "type",
     };
-    private static readonly string[] UnusedContractPathSegments =
-    [
-        "/contracts/",
-        "/contract/",
-        "/dtos/",
-        "/dto/",
-        "/models/",
-        "/model/",
-        "/schemas/",
-        "/schema/",
-    ];
-    private static readonly string[] UnusedRecordContractSuffixes =
-    [
-        "Dto",
-        "DTO",
-        "Request",
-        "Response",
-        "Result",
-        "Results",
-        "Model",
-        "Payload",
-        "Envelope",
-    ];
-    private static readonly string[] UnusedGeneratedPathMarkers =
-    [
-        ".g.cs",
-        ".generated.",
-        "/generated/",
-        "/obj/",
-        "/bin/",
-    ];
-    private static readonly string[] UnusedCliPathMarkers = ["/cli/", "/commands/", "/commandline/"];
-    private static readonly string[] UnusedMcpPathMarkers = ["/mcp/"];
-    private static readonly string[] UnusedLspPathMarkers = ["/lsp/", "/languageserver/"];
-    private static readonly string[] UnusedJsonContractTerms =
-    [
-        "Json",
-        "Dto",
-        "DTO",
-        "Request",
-        "Response",
-        "Result",
-        "Results",
-        "Payload",
-        "Envelope",
-        "Contract",
-        "Schema",
-    ];
-    private static readonly HashSet<string> UnusedFrameworkOverrideMemberNames = new(StringComparer.OrdinalIgnoreCase)
-    {
-        "CanRead",
-        "CanSeek",
-        "CanWrite",
-        "Length",
-        "Position",
-        "Flush",
-        "FlushAsync",
-        "Read",
-        "ReadAsync",
-        "ReadByte",
-        "Seek",
-        "SetLength",
-        "Write",
-        "WriteAsync",
-        "WriteByte",
-        "Dispose",
-        "DisposeAsync",
-    };
-    private static readonly HashSet<string> UnusedExceptionMetadataNames = new(StringComparer.OrdinalIgnoreCase)
-    {
-        "CharactersRead",
-        "Utf8BytesRead",
-        "SizeLimit",
-        "Limit",
-        "ByteCount",
-        "BytesRead",
-        "Offset",
-        "Position",
-        "Path",
-        "FileName",
-        "LineNumber",
-        "ColumnNumber",
-        "ActualSize",
-        "MaxSize",
-        "Length",
-    };
-    private static readonly string[] UnusedConfigMemberTerms =
-    [
-        "Configuration",
-        "Config",
-        "Options",
-        "Settings",
-        "Manifest",
-        "Schema",
-        "Metadata",
-        "Limit",
-        "Max",
-        "Min",
-        "Size",
-        "Bytes",
-        "Count",
-        "Capacity",
-        "Timeout",
-        "Version",
-        "Kind",
-        "Category",
-        "Severity",
-        "Source",
-        "Target",
-        "Path",
-        "Name",
-        "Id",
-        "Key",
-    ];
     private const int UnusedAttributeContextWindow = 16;
     private const int UnusedPublicOverfetchMultiplier = 16;
     private const int UnusedPublicOverfetchMinimum = 64;
@@ -378,7 +229,6 @@ FROM symbols {ancestorAlias}
         RegexOptions.Compiled | RegexOptions.CultureInvariant);
 
     private readonly record struct UnusedCandidateChunk(int StartLine, int EndLine, string Content);
-    private readonly record struct UnusedContractDomainClassification(string Domain, List<string> Tags);
 
     /// <summary>
     /// Find symbols that have no matching references in the reference table (potential dead code).
@@ -808,44 +658,6 @@ private static void AddUnusedCandidateChunkLines(SortedDictionary<int, string> l
         }
     }
 
-    private UnusedSymbolResult CreateUnusedSymbolResult(UnusedCandidateSymbol candidate)
-    {
-        var kind = NormalizeUnusedSymbolKind(candidate);
-        var surfaceTags = BuildUnusedIntentionalSurfaceTags(candidate, kind);
-        if (!surfaceTags.Contains("reflection_or_config_suspect", StringComparer.Ordinal)
-            && candidate.IsPublicOrExported
-            && HasReflectionAttributeContext(kind, candidate.Path, candidate.StartLine))
-        {
-            AddUnusedSurfaceTag(surfaceTags, "reflection_or_config_suspect");
-        }
-
-        var isIntentionalSurfaceSuspect = surfaceTags.Count > 0;
-        var classification = ClassifyUnusedSymbol(candidate.IsPublicOrExported, isIntentionalSurfaceSuspect, candidate.Visibility);
-        var reasonTags = BuildUnusedReasonTags(candidate.IsPublicOrExported, isIntentionalSurfaceSuspect, candidate.Visibility, surfaceTags);
-        var contractDomain = ClassifyUnusedContractDomain(candidate, kind, classification.Bucket, surfaceTags);
-        return new UnusedSymbolResult
-        {
-            Path = candidate.Path,
-            Lang = candidate.Lang,
-            Kind = kind,
-            Name = candidate.Name,
-            Line = candidate.Line,
-            StartLine = candidate.StartLine,
-            EndLine = candidate.EndLine,
-            Signature = candidate.Signature,
-            Visibility = candidate.Visibility,
-            ReturnType = candidate.ReturnType,
-            ContainerKind = candidate.ContainerKind,
-            ContainerName = candidate.ContainerName,
-            UnusedBucket = classification.Bucket,
-            UnusedConfidence = classification.Confidence,
-            UnusedReason = classification.Reason,
-            UnusedReasonTags = reasonTags,
-            UnusedContractDomain = contractDomain.Domain,
-            UnusedContractDomainTags = contractDomain.Tags,
-        };
-    }
-
     private static string NormalizeUnusedSymbolKind(UnusedCandidateSymbol candidate)
         => NormalizeUnusedSymbolKind(candidate.Lang, candidate.Kind, candidate.Signature);
 
@@ -2388,424 +2200,4 @@ private static bool LooksLikeAttributeBoundaryLine(string line)
         return line.IndexOf('[') >= 0 || line.IndexOf(']') >= 0;
     }
 
-    private static List<string> BuildUnusedIntentionalSurfaceTags(UnusedCandidateSymbol candidate, string kind)
-    {
-        var tags = new List<string>();
-        if (candidate.IsReflectionOrConfigSuspect)
-            AddUnusedSurfaceTag(tags, "reflection_or_config_suspect");
-        if (IsMarkdownHeadingSymbol(candidate, kind))
-            AddUnusedSurfaceTag(tags, "documentation_heading");
-        if (IsMarkdownFenceSymbol(candidate, kind))
-            AddUnusedSurfaceTag(tags, "markdown_fence_language_marker");
-        if (IsGeneratedSurface(candidate))
-            AddUnusedSurfaceTag(tags, "generated_surface");
-        if (IsSourceGeneratedJsonContext(candidate))
-        {
-            AddUnusedSurfaceTag(tags, "serialization_contract");
-            AddUnusedSurfaceTag(tags, "source_generated_json_context");
-        }
-        if (IsUnusedContractType(candidate, kind))
-            AddUnusedSurfaceTag(tags, "serialization_contract");
-        if (IsUnusedContractMember(candidate, kind))
-            AddUnusedSurfaceTag(tags, "contract_member");
-        if (IsConfigOrManifestSurface(candidate, kind))
-            AddUnusedSurfaceTag(tags, "config_or_metadata_surface");
-        if (IsTestHookName(candidate.Name))
-            AddUnusedSurfaceTag(tags, "test_hook");
-        if (IsExceptionMetadataProperty(candidate, kind))
-            AddUnusedSurfaceTag(tags, "exception_metadata");
-        if (IsConfigOrMetadataMember(candidate, kind))
-            AddUnusedSurfaceTag(tags, "config_or_metadata_member");
-        return tags;
-    }
-
-    private static void AddUnusedSurfaceTag(List<string> tags, string tag)
-    {
-        if (!tags.Contains(tag, StringComparer.Ordinal))
-            tags.Add(tag);
-    }
-
-    private static bool IsMarkdownHeadingSymbol(UnusedCandidateSymbol candidate, string kind)
-    {
-        return (string.Equals(candidate.Lang, "markdown", StringComparison.OrdinalIgnoreCase)
-                || string.Equals(candidate.Lang, "md", StringComparison.OrdinalIgnoreCase))
-            && (kind.Contains("heading", StringComparison.OrdinalIgnoreCase)
-                || kind.Contains("header", StringComparison.OrdinalIgnoreCase));
-    }
-
-    private static bool IsMarkdownFenceSymbol(UnusedCandidateSymbol candidate, string kind)
-    {
-        if ((!string.Equals(candidate.Lang, "markdown", StringComparison.OrdinalIgnoreCase)
-                && !string.Equals(candidate.Lang, "md", StringComparison.OrdinalIgnoreCase))
-            || !string.Equals(kind, "code", StringComparison.OrdinalIgnoreCase))
-        {
-            return false;
-        }
-
-        var signature = candidate.Signature?.TrimStart();
-        return signature?.StartsWith("```", StringComparison.Ordinal) == true
-            || signature?.StartsWith("~~~", StringComparison.Ordinal) == true;
-    }
-
-    private static bool IsGeneratedSurface(UnusedCandidateSymbol candidate)
-        => ContainsAny(candidate.Path, UnusedGeneratedPathMarkers);
-
-    private static bool IsSourceGeneratedJsonContext(UnusedCandidateSymbol candidate)
-    {
-        return EndsWithAny(candidate.Name, ["JsonContext"])
-            || ContainsAny(candidate.Signature, ["JsonSerializerContext", "JsonSerializable", "JsonSourceGenerationOptions"]);
-    }
-
-    private static bool IsUnusedContractType(UnusedCandidateSymbol candidate, string kind)
-    {
-        if (!IsTypeLikeUnusedKind(kind) || IsPrivateLikeVisibility(candidate.Visibility))
-            return false;
-        return ContainsAny(candidate.Path, UnusedContractPathSegments)
-            || IsRecordContractType(candidate)
-            || ContainsAny(candidate.Signature, ["DataContract", "Serializable", "MessagePackObject", "ProtoContract"]);
-    }
-
-    private static bool IsUnusedContractMember(UnusedCandidateSymbol candidate, string kind)
-    {
-        if (!IsDataMemberUnusedKind(kind) || IsPrivateLikeVisibility(candidate.Visibility))
-            return false;
-        return ContainsAny(candidate.Path, UnusedContractPathSegments)
-            || ContainsAny(candidate.Signature, ["JsonProperty", "JsonInclude", "DataMember", "XmlElement", "XmlAttribute"]);
-    }
-
-    private static bool IsConfigOrManifestSurface(UnusedCandidateSymbol candidate, string kind)
-    {
-        if (IsPrivateLikeVisibility(candidate.Visibility))
-            return false;
-        if (!IsTypeLikeUnusedKind(kind) && !IsDataMemberUnusedKind(kind) && !IsFunctionLikeUnusedKind(kind))
-            return false;
-        if (EndsWithAny(candidate.Name, ["Options", "Settings", "Configuration", "Config", "Manifest", "Schema"])
-            || ContainsAny(candidate.Name, ["Configuration", "IOptions"])
-            || ContainsAny(candidate.Signature, ["IConfiguration", "ConfigurationSection", "IOptions", "Options<"]))
-        {
-            return true;
-        }
-
-        return IsDataMemberUnusedKind(kind)
-            && (ContainsAny(candidate.Path, ["/config/", "/configuration/", "/options/", "/settings/", "/manifest/", "/manifests/"])
-                || ContainsAny(candidate.Signature, ["IConfiguration", "ConfigurationSection", "IOptions", "Options<"]));
-    }
-
-    private static bool IsTestHookName(string? name)
-    {
-        return !string.IsNullOrWhiteSpace(name)
-            && (name.EndsWith("ForTests", StringComparison.OrdinalIgnoreCase)
-                || name.Contains("ForTest", StringComparison.OrdinalIgnoreCase)
-                || name.Contains("TestOnly", StringComparison.OrdinalIgnoreCase));
-    }
-
-    private static bool IsExceptionMetadataProperty(UnusedCandidateSymbol candidate, string kind)
-    {
-        return string.Equals(kind, "property", StringComparison.OrdinalIgnoreCase)
-            && UnusedExceptionMetadataNames.Contains(candidate.Name)
-            && (EndsWithAny(candidate.ContainerName, ["Exception"])
-                || ContainsAny(candidate.ContainerQualifiedName, ["Exception"])
-                || ContainsAny(candidate.Signature, ["Exception"]));
-    }
-
-    private static bool IsConfigOrMetadataMember(UnusedCandidateSymbol candidate, string kind)
-    {
-        if (!IsDataMemberUnusedKind(kind) || IsPrivateLikeVisibility(candidate.Visibility))
-            return false;
-        if (!ContainsAny(candidate.Name, UnusedConfigMemberTerms))
-            return false;
-
-        var hasContext = ContainsAny(candidate.Path, UnusedContractPathSegments)
-            || ContainsAny(candidate.Path, ["/config/", "/configuration/", "/options/", "/settings/", "/manifest/", "/manifests/"])
-            || ContainsAny(candidate.Signature, ["JsonProperty", "JsonInclude", "DataMember", "Diagnostic", "Metadata", "IConfiguration", "IOptions", "Options<"]);
-        return hasContext;
-    }
-
-    private static bool IsTypeLikeUnusedKind(string kind)
-    {
-        return kind is "class" or "struct" or "record" or "interface" or "enum" or "type";
-    }
-
-    private static bool IsDataMemberUnusedKind(string kind)
-    {
-        return kind is "property" or "field" or "constant" or "enum_member";
-    }
-
-    private static bool IsFunctionLikeUnusedKind(string kind)
-    {
-        return kind is "function" or "method";
-    }
-
-    private static bool IsRecordContractType(UnusedCandidateSymbol candidate)
-    {
-        return ContainsCSharpRecordKeyword(candidate.Signature)
-            && EndsWithAny(candidate.Name, UnusedRecordContractSuffixes);
-    }
-
-    private static bool ContainsCSharpRecordKeyword(string? signature)
-    {
-        if (string.IsNullOrWhiteSpace(signature))
-            return false;
-
-        var trimmed = signature.TrimStart();
-        return trimmed.StartsWith("record ", StringComparison.Ordinal)
-            || trimmed.StartsWith("record(", StringComparison.Ordinal)
-            || signature.Contains(" record ", StringComparison.Ordinal)
-            || signature.Contains(" record(", StringComparison.Ordinal);
-    }
-
-    private static bool EndsWithAny(string? value, IReadOnlyList<string> suffixes)
-    {
-        if (string.IsNullOrWhiteSpace(value))
-            return false;
-        foreach (var suffix in suffixes)
-        {
-            if (value.EndsWith(suffix, StringComparison.OrdinalIgnoreCase))
-                return true;
-        }
-
-        return false;
-    }
-
-    private static bool ContainsAny(string? value, IReadOnlyList<string> fragments)
-    {
-        if (string.IsNullOrWhiteSpace(value))
-            return false;
-        foreach (var fragment in fragments)
-        {
-            if (value.Contains(fragment, StringComparison.OrdinalIgnoreCase))
-                return true;
-        }
-
-        return false;
-    }
-
-    private static (string Bucket, string Confidence, string Reason) ClassifyUnusedSymbol(bool isPublicOrExported, bool isIntentionalSurfaceSuspect, string? visibility)
-    {
-        if (isIntentionalSurfaceSuspect)
-        {
-            return (
-                UnusedBucketReflectionOrConfig,
-                "low",
-                "symbol with attribute-driven reflection surface, serialization, config, metadata, test-hook, generated, documentation, or compatibility surface and no indexed references");
-        }
-
-        if (isPublicOrExported)
-        {
-            return (
-                UnusedBucketPublicOrExported,
-                "low",
-                "public/exported symbol with no indexed references");
-        }
-
-        if (IsPrivateLikeVisibility(visibility))
-        {
-            return (
-                UnusedBucketLikelyPrivate,
-                "medium",
-                "private/file-local symbol with no indexed references after same-file text validation");
-        }
-
-        return (
-            UnusedBucketMaybeNonPublic,
-            "low",
-            "non-public symbol with no indexed references");
-    }
-
-    private static List<string> BuildUnusedReasonTags(bool isPublicOrExported, bool isIntentionalSurfaceSuspect, string? visibility, IReadOnlyList<string> surfaceTags)
-    {
-        var tags = new List<string> { "no_indexed_references" };
-        if (isIntentionalSurfaceSuspect)
-        {
-            tags.Add("intentional_surface_suspect");
-            tags.Add("reflection_or_config_suspect");
-        }
-        foreach (var surfaceTag in surfaceTags)
-            AddUnusedSurfaceTag(tags, surfaceTag);
-        if (isPublicOrExported)
-            tags.Add("public_or_exported");
-        else if (IsPrivateLikeVisibility(visibility))
-            tags.Add("private_or_file_local");
-        else
-            tags.Add("non_public");
-        return tags;
-    }
-
-    private static UnusedContractDomainClassification ClassifyUnusedContractDomain(
-        UnusedCandidateSymbol candidate,
-        string kind,
-        string bucket,
-        IReadOnlyList<string> surfaceTags)
-    {
-        var tags = new List<string>();
-        if (string.Equals(bucket, UnusedBucketReflectionOrConfig, StringComparison.Ordinal))
-            AddUnusedSurfaceTag(tags, "intentional_surface_suspect");
-        foreach (var surfaceTag in surfaceTags)
-            AddUnusedSurfaceTag(tags, surfaceTag);
-
-        if (IsPrivateLikeVisibility(candidate.Visibility))
-            return CreateUnusedContractDomain(UnusedContractDomainPrivate, tags, "private_or_file_local");
-
-        if (!candidate.IsPublicOrExported && surfaceTags.Count == 0)
-            return CreateUnusedContractDomain(UnusedContractDomainNonPublic, tags, "nonpublic_or_protected");
-
-        AddUnusedSurfaceTag(tags, candidate.IsPublicOrExported ? "public_or_exported" : "nonpublic_or_protected");
-
-        if (HasUnusedSurfaceTag(surfaceTags, "documentation_heading") || IsMarkdownHeadingSymbol(candidate, kind))
-            return CreateUnusedContractDomain(UnusedContractDomainDocumentation, tags, "documentation_heading");
-
-        if (HasUnusedSurfaceTag(surfaceTags, "markdown_fence_language_marker") || IsMarkdownFenceSymbol(candidate, kind))
-            return CreateUnusedContractDomain(UnusedContractDomainDocumentation, tags, "markdown_fence_language_marker");
-
-        if (IsUnusedTestContractSurface(candidate))
-            return CreateUnusedContractDomain(UnusedContractDomainTest, tags, "test_surface");
-
-        if (HasUnusedSurfaceTag(surfaceTags, "generated_surface") || IsGeneratedSurface(candidate))
-            return CreateUnusedContractDomain(UnusedContractDomainGenerated, tags, "generated_surface");
-
-        if (HasUnusedSurfaceTag(surfaceTags, "exception_metadata") || IsExceptionDiagnosticSurface(candidate, kind))
-            return CreateUnusedContractDomain(UnusedContractDomainExceptionDiagnostic, tags, "exception_metadata");
-
-        if (IsFrameworkOverrideSurface(candidate))
-            return CreateUnusedContractDomain(UnusedContractDomainFrameworkOverride, tags, "framework_override");
-
-        if (IsMcpContractSurface(candidate))
-            return CreateUnusedContractDomain(UnusedContractDomainMcp, tags, "mcp_tool_contract");
-
-        if (IsLspContractSurface(candidate))
-            return CreateUnusedContractDomain(UnusedContractDomainLsp, tags, "lsp_protocol_contract");
-
-        if (IsCliContractSurface(candidate))
-            return CreateUnusedContractDomain(UnusedContractDomainCli, tags, "cli_option_or_result");
-
-        if (IsConfigurationContractSurface(candidate, kind, surfaceTags))
-            return CreateUnusedContractDomain(UnusedContractDomainConfig, tags, "configuration_or_metadata_contract");
-
-        if (IsJsonContractSurface(candidate, surfaceTags))
-            return CreateUnusedContractDomain(UnusedContractDomainJson, tags, "json_output_or_input_contract");
-
-        if (HasUnusedSurfaceTag(surfaceTags, "reflection_or_config_suspect"))
-            return CreateUnusedContractDomain(UnusedContractDomainSerialization, tags, "reflection_or_serialization_contract");
-
-        return candidate.IsPublicOrExported
-            ? CreateUnusedContractDomain(UnusedContractDomainPublicApi, tags, "public_api_surface")
-            : CreateUnusedContractDomain(UnusedContractDomainNonPublic, tags, "nonpublic_or_protected");
-    }
-
-    private static UnusedContractDomainClassification CreateUnusedContractDomain(string domain, List<string> tags, params string[] domainTags)
-    {
-        AddUnusedSurfaceTag(tags, domain);
-        foreach (var tag in domainTags)
-            AddUnusedSurfaceTag(tags, tag);
-        return new UnusedContractDomainClassification(domain, tags);
-    }
-
-    private static bool HasUnusedSurfaceTag(IReadOnlyList<string> tags, string tag)
-        => tags.Contains(tag, StringComparer.Ordinal);
-
-    private static bool IsUnusedTestContractSurface(UnusedCandidateSymbol candidate)
-    {
-        return IsUnusedTestPath(candidate.Path)
-            || EndsWithAny(candidate.ContainerName, ["Test", "Tests", "Fixture"])
-            || EndsWithAny(candidate.ContainerQualifiedName, ["Test", "Tests", "Fixture"])
-            || IsTestHookName(candidate.Name);
-    }
-
-    private static bool IsUnusedTestPath(string? path)
-    {
-        if (string.IsNullOrWhiteSpace(path))
-            return false;
-
-        var normalized = path.Replace('\\', '/');
-        return normalized.StartsWith("test/", StringComparison.OrdinalIgnoreCase)
-            || normalized.StartsWith("tests/", StringComparison.OrdinalIgnoreCase)
-            || normalized.Contains("/test/", StringComparison.OrdinalIgnoreCase)
-            || normalized.Contains("/tests/", StringComparison.OrdinalIgnoreCase)
-            || normalized.Contains(".tests/", StringComparison.OrdinalIgnoreCase);
-    }
-
-    private static bool IsExceptionDiagnosticSurface(UnusedCandidateSymbol candidate, string kind)
-    {
-        return IsExceptionMetadataProperty(candidate, kind)
-            || (IsDataMemberUnusedKind(kind)
-                && (EndsWithAny(candidate.ContainerName, ["Exception"])
-                    || EndsWithAny(candidate.ContainerQualifiedName, ["Exception"])))
-            || (IsTypeLikeUnusedKind(kind) && EndsWithAny(candidate.Name, ["Exception"]));
-    }
-
-    private static bool IsFrameworkOverrideSurface(UnusedCandidateSymbol candidate)
-    {
-        if (ContainsAny(candidate.Signature, [" override ", " override\t", " override\r", " override\n"]))
-            return true;
-
-        if (!UnusedFrameworkOverrideMemberNames.Contains(candidate.Name))
-            return false;
-
-        return EndsWithAny(candidate.ContainerName, ["Stream", "TextReader", "TextWriter"])
-            || EndsWithAny(candidate.ContainerQualifiedName, ["Stream", "TextReader", "TextWriter"])
-            || ContainsAny(candidate.Signature, ["Stream", "TextReader", "TextWriter"]);
-    }
-
-    private static bool IsMcpContractSurface(UnusedCandidateSymbol candidate)
-    {
-        return ContainsAny(candidate.Path, UnusedMcpPathMarkers)
-            || ContainsAny(candidate.ContainerName, ["Mcp", "JsonRpc"])
-            || ContainsAny(candidate.ContainerQualifiedName, ["Mcp", "JsonRpc"])
-            || ContainsAny(candidate.Signature, ["Mcp", "JsonRpc"]);
-    }
-
-    private static bool IsLspContractSurface(UnusedCandidateSymbol candidate)
-    {
-        return ContainsAny(candidate.Path, UnusedLspPathMarkers)
-            || ContainsAny(candidate.ContainerName, ["Lsp", "LanguageServer"])
-            || ContainsAny(candidate.ContainerQualifiedName, ["Lsp", "LanguageServer"])
-            || ContainsAny(candidate.Signature, ["Lsp", "LanguageServer"]);
-    }
-
-    private static bool IsCliContractSurface(UnusedCandidateSymbol candidate)
-    {
-        var hasCliContext = ContainsAny(candidate.Path, UnusedCliPathMarkers)
-            || ContainsAny(candidate.ContainerQualifiedName, ["Cli", "CommandLine"])
-            || ContainsAny(candidate.Signature, ["CommandLine", "System.CommandLine", "Option<", "Argument<"]);
-        if (hasCliContext)
-            return true;
-
-        return EndsWithAny(candidate.Name, ["Command", "Flag", "Flags", "Usage", "ExitCode", "ErrorCode"])
-            || EndsWithAny(candidate.ContainerName, ["Command", "Flag", "Flags", "Usage", "ExitCode", "ErrorCode"]);
-    }
-
-    private static bool IsConfigurationContractSurface(UnusedCandidateSymbol candidate, string kind, IReadOnlyList<string> surfaceTags)
-    {
-        return HasUnusedSurfaceTag(surfaceTags, "config_or_metadata_surface")
-            || HasUnusedSurfaceTag(surfaceTags, "config_or_metadata_member")
-            || IsConfigOrManifestSurface(candidate, kind)
-            || IsConfigOrMetadataMember(candidate, kind);
-    }
-
-    private static bool IsJsonContractSurface(UnusedCandidateSymbol candidate, IReadOnlyList<string> surfaceTags)
-    {
-        return HasUnusedSurfaceTag(surfaceTags, "serialization_contract")
-            || HasUnusedSurfaceTag(surfaceTags, "contract_member")
-            || HasUnusedSurfaceTag(surfaceTags, "source_generated_json_context")
-            || ContainsAny(candidate.Path, UnusedContractPathSegments)
-            || EndsWithAny(candidate.Name, UnusedRecordContractSuffixes)
-            || EndsWithAny(candidate.ContainerName, UnusedRecordContractSuffixes)
-            || ContainsAny(candidate.Name, UnusedJsonContractTerms)
-            || ContainsAny(candidate.ContainerName, UnusedJsonContractTerms)
-            || ContainsAny(candidate.Signature, ["JsonProperty", "JsonInclude", "JsonSerializerContext", "DataContract", "DataMember", "XmlElement", "XmlAttribute", "YamlMember", "MessagePackObject", "ProtoContract"]);
-    }
-
-    private static bool IsPrivateLikeVisibility(string? visibility)
-    {
-        return string.Equals(visibility, "private", StringComparison.OrdinalIgnoreCase)
-            || string.Equals(visibility, "fileprivate", StringComparison.OrdinalIgnoreCase);
-    }
-
-    private static readonly string[] OrderedUnusedBuckets =
-    [
-        UnusedBucketLikelyPrivate,
-        UnusedBucketMaybeNonPublic,
-        UnusedBucketPublicOrExported,
-        UnusedBucketReflectionOrConfig,
-    ];
 }
diff --git a/tests/CodeIndex.Tests/DbReaderUnusedClassificationTests.cs b/tests/CodeIndex.Tests/DbReaderUnusedClassificationTests.cs
new file mode 100644
index 000000000..ae8fa4ae0
--- /dev/null
+++ b/tests/CodeIndex.Tests/DbReaderUnusedClassificationTests.cs
@@ -0,0 +1,157 @@
+using CodeIndex.Models;
+
+namespace CodeIndex.Tests;
+
+public partial class DbReaderTests
+{
+    [Fact]
+    public void GetUnusedSymbols_OverlappingSurfaceSignalsPreserveDomainPrecedenceAndTags()
+    {
+        const string generatedContractPath = "tests/mcp/config/contracts/GeneratedDto.g.cs";
+        const string attributedGeneratedContractPath = "src/contracts/AttributedDto.g.cs";
+        const string markdownPath = "tests/mcp/guide.md";
+        var generatedContractFileId = CreateUnusedClassificationFile(
+            generatedContractPath,
+            "csharp");
+        var attributedGeneratedContractFileId = CreateUnusedClassificationFile(
+            attributedGeneratedContractPath,
+            "csharp");
+        var markdownFileId = CreateUnusedClassificationFile(markdownPath, "markdown");
+        _writer.InsertChunks(
+        [
+            new ChunkRecord
+            {
+                FileId = attributedGeneratedContractFileId,
+                ChunkIndex = 0,
+                StartLine = 1,
+                EndLine = 7,
+                Content = "using System.Text.Json.Serialization;\n\npublic sealed class AttributedDto\n{\n    [JsonPropertyName(\"title\")]\n    public string Title { get; init; } = \"\";\n}\n",
+            },
+        ]);
+        _writer.InsertSymbols(
+        [
+            new SymbolRecord
+            {
+                FileId = generatedContractFileId,
+                Kind = "property",
+                Name = "Limit",
+                Line = 4,
+                StartLine = 4,
+                EndLine = 4,
+                Signature = "public int Limit { get; set; }",
+                Visibility = "public",
+                ContainerKind = "class",
+                ContainerName = "ParseException",
+                ContainerQualifiedName = "Fixtures.ParseException",
+            },
+            new SymbolRecord
+            {
+                FileId = attributedGeneratedContractFileId,
+                Kind = "property",
+                Name = "Title",
+                Line = 6,
+                StartLine = 5,
+                EndLine = 6,
+                Signature = "public string Title { get; init; } = \"\";",
+                Visibility = "public",
+                ContainerKind = "class",
+                ContainerName = "AttributedDto",
+                ContainerQualifiedName = "Fixtures.AttributedDto",
+            },
+            new SymbolRecord
+            {
+                FileId = markdownFileId,
+                Kind = "heading",
+                Name = "Configuration Guide",
+                Line = 1,
+                StartLine = 1,
+                EndLine = 1,
+                Signature = "# Configuration Guide",
+            },
+        ]);
+
+        var unused = _reader.GetUnusedSymbols(
+            limit: 10,
+            kind: null,
+            lang: null,
+            pathPatterns: ["tests/mcp/**", "src/contracts/**"],
+            excludePathPatterns: null,
+            excludeTests: false);
+        var detailedCount = _reader.CountUnusedSymbolsDetailed(
+            kind: null,
+            lang: null,
+            pathPatterns: ["tests/mcp/**", "src/contracts/**"],
+            excludePathPatterns: null,
+            excludeTests: false);
+
+        var generatedContract = Assert.Single(unused, result => result.Name == "Limit");
+        Assert.Equal("reflection_or_config_suspect", generatedContract.UnusedBucket);
+        Assert.Equal("test_contract", generatedContract.UnusedContractDomain);
+        Assert.Equal(
+        [
+            "no_indexed_references",
+            "intentional_surface_suspect",
+            "reflection_or_config_suspect",
+            "generated_surface",
+            "contract_member",
+            "config_or_metadata_surface",
+            "exception_metadata",
+            "config_or_metadata_member",
+            "public_or_exported",
+        ], generatedContract.UnusedReasonTags);
+        Assert.Equal(
+        [
+            "intentional_surface_suspect",
+            "reflection_or_config_suspect",
+            "generated_surface",
+            "contract_member",
+            "config_or_metadata_surface",
+            "exception_metadata",
+            "config_or_metadata_member",
+            "public_or_exported",
+            "test_contract",
+            "test_surface",
+        ], generatedContract.UnusedContractDomainTags);
+
+        var attributedGeneratedContract = Assert.Single(unused, result => result.Name == "Title");
+        Assert.Equal("reflection_or_config_suspect", attributedGeneratedContract.UnusedBucket);
+        Assert.Equal("generated_code", attributedGeneratedContract.UnusedContractDomain);
+        Assert.Equal(
+        [
+            "intentional_surface_suspect",
+            "generated_surface",
+            "contract_member",
+            "reflection_or_config_suspect",
+            "public_or_exported",
+            "generated_code",
+        ], attributedGeneratedContract.UnusedContractDomainTags);
+
+        var heading = Assert.Single(unused, result => result.Name == "Configuration Guide");
+        Assert.Equal("reflection_or_config_suspect", heading.UnusedBucket);
+        Assert.Equal("documentation_surface", heading.UnusedContractDomain);
+        Assert.Equal(
+        [
+            "intentional_surface_suspect",
+            "documentation_heading",
+            "nonpublic_or_protected",
+            "documentation_surface",
+        ], heading.UnusedContractDomainTags);
+
+        Assert.Equal(3, detailedCount.Count);
+        Assert.Equal(3, detailedCount.FileCount);
+        Assert.Equal(3, detailedCount.BucketCounts["reflection_or_config_suspect"]);
+        Assert.Equal(1, detailedCount.ContractDomainCounts["generated_code"]);
+        Assert.Equal(1, detailedCount.ContractDomainCounts["documentation_surface"]);
+        Assert.Equal(1, detailedCount.ContractDomainCounts["test_contract"]);
+    }
+
+    private long CreateUnusedClassificationFile(string path, string lang) =>
+        _writer.UpsertFile(new FileRecord
+        {
+            Path = path,
+            Lang = lang,
+            Size = 200,
+            Lines = 10,
+            Modified = new DateTime(2025, 6, 1, 0, 0, 0, DateTimeKind.Utc),
+        });
+}

From 04b36daa79ba17df8f01b135460c22e5a78b6c02 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 12 Aug 2026 23:55:41 +0900
Subject: [PATCH 34/45] Decompose search validation and routing

---
 TESTING_GUIDE.md                              |   4 +-
 .../Cli/QueryCommandRunner.Search.cs          | 650 +-----------------
 .../Cli/QueryCommandRunner.SearchRouting.cs   | 496 +++++++++++++
 .../QueryCommandRunner.SearchValidation.cs    | 296 ++++++++
 .../QueryCommandRunnerSearchTests.cs          |  30 +-
 5 files changed, 815 insertions(+), 661 deletions(-)
 create mode 100644 src/CodeIndex/Cli/QueryCommandRunner.SearchRouting.cs
 create mode 100644 src/CodeIndex/Cli/QueryCommandRunner.SearchValidation.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index ae91a1ed2..4aa50fee3 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -222,7 +222,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   End-to-end upgrade path: seeds a pre-column legacy DB, opens it through `TryMigrateForRead`, and exercises the read paths that touch nullable symbol ordinals (outline, symbol search, nearby, unused, analyze bundle) to lock in the real-world failure mode behind #58 / #49. Migration ownership coverage must also distinguish caller-owned transactions from owned transactions, propagate unrelated `BEGIN` errors, preserve populated foreign-key rows across rebuilds, and verify rollback, foreign-key restoration, and successful retry after injected failures.
 - `IndexCommandRunner*Tests.cs`, `QueryCommandRunner*Tests.cs`, `ProgramCliTests.cs`, `InstallScriptTests.cs`
   YAML `outline` integration coverage must assert nested sequence paths, mapping-parent depth, unchanged source ranges and symbol counts, deterministic sorting, and cursor replay across a page boundary.
-  Search-core orchestration coverage must keep validation ahead of database execution, count-mode zero/nonzero payloads aligned, strict-not-found exit semantics intact, and profiled NDJSON ordered as result records, profile metadata, then the terminal record.
+  Search-core orchestration coverage must keep validation ahead of database execution, preserve list-recipes > named-query > recipe > plain route precedence and the recipe-field-before-conflict / plain-conflict-before-field aggregation error order, keep count-mode zero/nonzero payloads aligned, retain strict-not-found exit semantics, and order profiled NDJSON as result records, profile metadata, then the terminal record.
   CLI parsing, command execution, and installer behavior. Index command coverage is split by run mode or feature area, and query command coverage is split by command family with partial test classes so shared console and fixture helpers stay centralized. Keep repeated query-result fixtures, such as overlapping chunk content used by multiple search deduplication tests, in narrow class-level helpers instead of duplicating local builders. `ProgramCliTests.cs` covers top-level entrypoint behavior that must be exercised through a subprocess, while `InstallScriptTests.cs` runs focused bash snippets against `install.sh` in library mode to lock in release-installer regressions without performing real network installs. Installer bundle-generation tests must also verify that `install.sh` is marked generated while every canonical `install_modules/` source remains unmarked.
   Authoritative C# scoped-update coverage treats bounded parallel extraction as a correctness and resource contract. Keep the `2 * workers` window bound, fixed-worker reuse, whole-window extraction barrier, target-ordered single-writer persistence, and mixed-language serial boundary in the same suite. Required fallbacks cover parallelism one, active symbol filters, content-load seams, post-extraction hooks, non-authoritative or undersized snapshots, ambiguous nullable language reuse, and speculative probe exceptions returning to the serial per-file boundary. Serial/parallel parity must compare summaries, files/chunks/all semantic symbol and reference columns, normalized reference-line and candidate identities, hotspot aggregates, issues, readiness/user-version metadata, and last-run readable-byte counters across normal, generated, cap, and oversized inputs. Retain all three file-stat barriers. Cancellation before persistence, after validated load, and at extraction completion must preserve the expected committed prefix, batch ownership, and derived readiness. Global watchdog and direct-fatal tests must assert active phase, bounded return, and terminal side effects; source-negative ordering tests must cover both cap-discarded confirmed evidence and an earlier lexical contract candidate still blocked in symbol extraction. Abnormal-window fixtures release every injected block and wait for the snapshotted all-workers-stopped seam before restoring static hooks or deleting the project root.
   `JsonEnvelopeWrapperTests.cs` owns global JSON-envelope token-role coverage. Keep parser-accepted separated and inline query values, option ordering, the `--` end-of-options form, missing-value boundaries for other value-bearing options, and a genuine `--json-envelope` output request together so preprocessing cannot consume command data, suppress a structured error envelope, or place its injected `--json` after the positional boundary.
@@ -1287,7 +1287,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   エンドツーエンドのアップグレード経路: カラム追加前のレガシー DB を用意し、`TryMigrateForRead` 経由で開いてから NULL になりうるシンボル列を触る read path（outline、シンボル検索、近傍、unused、analyze バンドル）を一通り叩き、#58 / #49 の実機失敗モードを固定する。migration ownership の coverage では、caller-owned transaction と cdidx-owned transaction を区別し、無関係な `BEGIN` error を伝播させ、foreign key が設定された既存 row を rebuild 後も保持し、注入 failure 後の rollback、foreign key 復元、retry 成功まで検証する。
 - `IndexCommandRunner*Tests.cs`、`QueryCommandRunner*Tests.cs`、`ProgramCliTests.cs`、`InstallScriptTests.cs`
   YAML `outline` の integration coverage では、入れ子 sequence path、mapping parent の depth、不変な source range と symbol count、決定的な sort、page 境界を越える cursor replay を検証してください。
-  search core の orchestration coverage では、validation が database execution より先に行われること、count mode の zero/nonzero payload が揃うこと、strict-not-found の exit semantics、profile 付き NDJSON が result record、profile metadata、terminal record の順になることを維持してください。
+  search core の orchestration coverage では、validation が database execution より先に行われること、list-recipes > named-query > recipe > plain の route precedence と recipe では field error が conflict より先・plain では conflict が field error より先になる aggregation error 順、count mode の zero/nonzero payload、strict-not-found の exit semantics、profile 付き NDJSON が result record、profile metadata、terminal record の順になることを維持してください。
   CLI の引数解析、コマンド実行、installer 挙動のテスト。Index command coverage は run mode または機能領域ごとの partial suite に分割し、Query command coverage は command family ごとの partial test class に分割して、共有 console / fixture helper は一箇所に保ちます。`ProgramCliTests.cs` はグローバル引数の解釈や完全な CLI 起動フローのように subprocess 経由で確認すべき Program エントリポイント挙動を扱い、`InstallScriptTests.cs` は `install.sh` を library mode で source した bash snippet を実行して、実ネットワーク install を行わずに release installer の回帰を固定する。installer bundle 生成テストでは、`install.sh` が generated と判定される一方、canonical な `install_modules/` source はすべて unmarked のままであることも検証してください。
   authoritative C# scoped update の coverage では、bounded parallel extraction を correctness と resource の契約として扱います。`2 * workers` の window 上限、固定 worker の再利用、window 全体の extraction barrier、target 順の single-writer persistence、mixed-language の serial 境界を同じ suite で維持してください。必須 fallback は parallelism 1、active symbol filter、content-load seam、post-extraction hook、non-authoritative / target 不足 snapshot、ambiguous な nullable language reuse、speculative probe 例外から serial per-file boundary への復帰を含みます。serial / parallel parity は normal、generated、cap、oversized input を横断し、summary、file / chunk、symbol / reference の全 semantic column、正規化した reference-line / candidate identity、hotspot aggregate、issue、readiness / user-version metadata、last-run readable-byte counter を比較してください。3段階の file-stat barrier も維持します。persistence 前、validated load 後、extraction completion 時の cancellation は、想定 committed prefix、batch ownership、derived readiness を固定します。global watchdog と direct fatal は active phase、bounded return、terminal side effect を検証し、source-negative ordering は cap で payload から除かれた confirmed evidence と、symbol extraction 中に block した earlier lexical contract candidate の両方を含めます。異常 window の fixture は注入 block をすべて解放し、snapshot 済み all-workers-stopped seam を待ってから static hook の復元と project root の削除を行ってください。
   `JsonEnvelopeWrapperTests.cs` は global JSON envelope の token role coverage を担当します。前処理が command data を消費したり、構造化 error envelope を抑止したり、補う `--json` を positional 境界より後ろへ置いたりしないよう、parser が受理する分離形式と inline 形式の query 値、option 順序、`--` end-of-options 形式、他の value-bearing option の missing-value 境界、実際の `--json-envelope` 出力要求を同じ fixture で維持してください。
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.Search.cs b/src/CodeIndex/Cli/QueryCommandRunner.Search.cs
index 9ee9cab90..dd1c9d7d4 100644
--- a/src/CodeIndex/Cli/QueryCommandRunner.Search.cs
+++ b/src/CodeIndex/Cli/QueryCommandRunner.Search.cs
@@ -1,6 +1,5 @@
 using System.Text.Json;
 using CodeIndex.Database;
-using CodeIndex.Models;
 
 namespace CodeIndex.Cli;
 
@@ -109,655 +108,12 @@ private static int RunSearchCore(
                 command: invocationContext.CommandName,
                 omitNullUsage: true);
         }
-        if (options.OpenIssuesPath != null && options.OutputFormat != OutputFormatIssueDrafts)
-        {
-            WriteUsageError(
-                "--open-issues can only be used with `cdidx search --format issue-drafts`.",
-                options,
-                "Use an open-issues JSON file from `gh issue list --state open --json number,title,labels,url`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.OpenIssuesRepository != null && !IssueDuplicatePreflight.IsGitHubOpenIssuesSource(options.OpenIssuesPath))
-        {
-            WriteUsageError(
-                "--repo can only be used with `--open-issues github`.",
-                options,
-                "Use `--open-issues github --repo owner/name` to fetch open issues directly from GitHub.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.IssueState != IssueDuplicatePreflight.DefaultIssueState && !IssueDuplicatePreflight.IsGitHubOpenIssuesSource(options.OpenIssuesPath))
-        {
-            WriteUsageError("--issue-state can only be used with `--open-issues github`.", options, "Use `--open-issues github --repo owner/name --issue-state all`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.DuplicatePreflightTuningExplicit && options.OutputFormat != OutputFormatIssueDrafts)
-        {
-            WriteUsageError(
-                "--duplicate-confidence and --duplicate-threshold can only be used with `cdidx search --format issue-drafts`.",
-                options,
-                "Use these controls when exporting issue draft JSON with duplicate-preflight metadata.");
-            return CommandExitCodes.UsageError;
-        }
-        if ((options.IncludeRecipeQueries.Count > 0 || options.ExcludeRecipeQueries.Count > 0) && options.RecipeName == null)
-        {
-            WriteUsageError(
-                "--include-query and --exclude-query can only be used with --recipe.",
-                options,
-                "Use `--recipe risky-code --include-query raw-diagnostic-echo` to run a child query subset.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.SearchCursor.HasValue && options.RecipeName == null)
-        {
-            WriteUsageError(
-                "--cursor can only be used with --recipe.",
-                options,
-                "Use `--recipe risky-code/raw-diagnostic-echo --format compact --cursor <next_cursor>` to fetch the next page for one child query.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.UnusedCursorOffset.HasValue)
-        {
-            WriteUsageError(
-                "--cursor for search must be a search pagination cursor returned by recipe search.",
-                options,
-                "Use `--cursor <next_cursor>` only with `--recipe`; `unused:<offset>` cursors are for `cdidx unused`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.OutlineCursorOffset.HasValue)
-        {
-            WriteUsageError(
-                "--cursor for search must be a search pagination cursor returned by recipe search.",
-                options,
-                "`outline:<offset>` cursors are for `cdidx outline <path>`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.DependencyCycleCursor.HasValue)
-        {
-            WriteUsageError(
-                "--cursor for search must be a search pagination cursor returned by recipe search.",
-                options,
-                "Dependency-cycle cursors are for `cdidx deps --cycles`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.AuditScopeExplicit && options.RecipeName == null && options.ListRecipes)
-        {
-            WriteUsageError(
-                "--audit-scope cannot be combined with `cdidx search --list-recipes`.",
-                options,
-                "Use `--query <text>` with --list-recipes to filter recipe discovery, or run an ad hoc search with `--source-only`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.ShowExcluded && options.RecipeName == null)
-        {
-            WriteUsageError(
-                "--show-excluded is only supported with `cdidx search --recipe <name>`.",
-                options,
-                "Use it with a recipe run to include the effective scope and exclusion diagnostics in JSON output.");
-            return CommandExitCodes.UsageError;
-        }
-        if ((options.IssueTitle != null || options.IssueLabels.Count > 0) && options.OutputFormat != OutputFormatIssueDrafts)
-        {
-            WriteUsageError(
-                "--issue-title and --issue-label can only be used with `cdidx search --format issue-drafts`.",
-                options,
-                "Use these hints when exporting issue draft JSON for a plain search.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.SnippetLines == 0 && options.OutputFormat != OutputFormatIssueDrafts)
-        {
-            WriteUsageError(
-                "--snippet-lines 0 is only supported with --format issue-drafts.",
-                options,
-                "Use `--format issue-drafts --snippet-lines 0` for path/line-only draft evidence, or pass a positive snippet line count for search output.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.IssueTitle != null && options.RecipeName != null)
-        {
-            WriteUsageError(
-                "--issue-title is only supported for ad hoc search issue drafts.",
-                options,
-                "Recipe issue-drafts produce one draft per recipe query, so their titles are derived from the recipe metadata.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.OutputFormat == OutputFormatIssueDrafts && options.CountOnly)
-        {
-            WriteUsageError(
-                "--count cannot be combined with --format issue-drafts.",
-                options,
-                "Issue-draft export needs result evidence; remove --count.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.NamesOnly && !options.ListRecipes)
-        {
-            WriteUsageError(
-                "--names is only supported with `cdidx recipes` or `cdidx search --list-recipes`.",
-                options,
-                "Use `cdidx recipes --names --json` for a small deterministic recipe-name list.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.NamesOnly && options.SummaryOnly)
-        {
-            WriteUsageError(
-                "--names cannot be combined with --summary-only.",
-                options,
-                "Use one recipe-list shape at a time.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.SummaryOnly
-            && !options.ListRecipes
-            && options.NamedSearchQueries.Count == 0
-            && !(options.RecipeName != null
-                && (options.CountOnly
-                    || options.Compact
-                    || options.OutputFormat == OutputFormatCompact
-                    || options.OutputFormat == OutputFormatIssueDrafts)))
-        {
-            WriteUsageError(
-                "--summary-only is only supported with `cdidx recipes` / `cdidx search --list-recipes`, named-query count output, recipe count output, or recipe issue-drafts output.",
-                options,
-                "Use `cdidx recipes --summary-only --json`, `cdidx search --named-query <name>=<query> --summary-only --json`, `cdidx search --recipe <name> --format compact --summary-only --json`, `cdidx search --recipe <name> --format count --summary-only`, or `cdidx search --recipe <name> --format issue-drafts --summary-only`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.OutputFormat == OutputFormatIssueDrafts && options.JsonOutputFormat == JsonOutputFormatArray)
-        {
-            WriteUsageError(
-                "--json=array is not supported with --format issue-drafts because draft export is a JSON object.",
-                options,
-                "Use plain `--json` or omit --json when exporting issue drafts.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.SearchCursor.HasValue && options.OutputFormat == OutputFormatIssueDrafts)
-        {
-            WriteUsageError(
-                "--cursor cannot be combined with --format issue-drafts.",
-                options,
-                "Use --cursor with recipe JSON or compact output, then export issue drafts after choosing the desired query page.");
-            return CommandExitCodes.UsageError;
-        }
-        var exactSearch = exact || options.TokenBoundary;
-        if (exactSearch && options.Prefix)
-        {
-            WriteSearchValidationError(
-                "--prefix cannot be combined with --exact / --exact-substring / --token-boundary (exact uses instr(), not FTS5 prefix phrases).",
-                options,
-                "Drop --prefix to keep the exact substring path, or drop the exact-mode flag to opt into FTS5 prefix matching.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.GroupBy != null && (options.ListRecipes || options.NamedSearchQueries.Count > 0))
-        {
-            var mode = options.ListRecipes
-                ? "--list-recipes"
-                : "--named-query";
-            WriteUsageError(
-                $"--group-by is not supported with {mode}.",
-                options,
-                "Use `cdidx search <query> --group-by file --count` or remove --group-by for recipe-list and named-batch output.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.OutputFormat == OutputFormatGrouped && (options.ListRecipes || options.NamedSearchQueries.Count > 0 || options.RecipeName != null))
-        {
-            var mode = options.ListRecipes
-                ? "--list-recipes"
-                : options.NamedSearchQueries.Count > 0
-                    ? "--named-query"
-                    : "--recipe";
-            WriteUsageError(
-                "--format grouped is only supported for plain search output.",
-                options,
-                invocationContext.RecipeNameIsPositional && mode == "--recipe"
-                    ? "Run a plain `cdidx search <query> --format grouped`; audit recipe execution does not support grouped output."
-                    : $"Remove {mode}, or run a plain `cdidx search <query> --format grouped`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (TryWriteCappedJsonDiagnosticsUsageError(invocationContext.CommandName, options))
-            return CommandExitCodes.UsageError;
-        if (options.ListRecipes)
-        {
-            if (options.FirstPerFile || options.SampleSize.HasValue)
-            {
-                WriteUsageError(
-                    "row-selection controls are not supported with --list-recipes because recipe discovery does not emit search rows.",
-                    options,
-                    "Remove --first-per-file / --sample, or execute a recipe or plain search that returns rows.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.RecipeName != null || options.NamedSearchQueries.Count > 0 || options.ExtraNames.Count > 0)
-            {
-                WriteUsageError(
-                    "--list-recipes cannot be combined with --recipe, --named-query, or extra positional arguments.",
-                    options,
-                    "Run `cdidx search --list-recipes --query <text>` to filter built-in audit recipes by recipe, query, label, severity, path, or search text.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.OutputFormat is not OutputFormatText and not OutputFormatJson and not OutputFormatCompact)
-            {
-                WriteUsageError(
-                    "--format count/csv/tsv/lsp/qf/sarif/issue-drafts is not supported with --list-recipes.",
-                    options,
-                    "Use plain text output, `--json` / `--format json` for the full recipe list, or `--format compact` for a compact summary.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.JsonOutputFormat == JsonOutputFormatArray)
-            {
-                WriteUsageError(
-                    "--json=array is not supported with --list-recipes because recipe-list output is a JSON object.",
-                    options,
-                    "Use plain `--json` for the recipe-list object.");
-                return CommandExitCodes.UsageError;
-            }
-
-            return WriteSearchRecipeList(options, jsonOptions, invocationContext.CommandName);
-        }
-        if (options.NamedSearchQueries.Count > 0)
-        {
-            if (options.FirstPerFile || options.SampleSize.HasValue)
-            {
-                WriteUsageError(
-                    "row-selection controls are not supported with --named-query because named batches do not expose selector accounting.",
-                    options,
-                    "Remove --first-per-file / --sample, or run each query as a plain search or recipe row output.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.Query != null || options.RecipeName != null || options.ExtraNames.Count > 0)
-            {
-                WriteUsageError(
-                    "--named-query cannot be combined with a positional query, --query, --recipe, or extra positional arguments.",
-                    options,
-                    "Pass one or more `--named-query <name>=<query>` values, or run a plain `cdidx search <query>`.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.OpenIssuesPath != null)
-            {
-                WriteUsageError(
-                    "--open-issues can only be used with `cdidx search --recipe <name> --format issue-drafts`.",
-                    options,
-                    "Remove --open-issues for ad hoc named batches.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.OutputFormat is not OutputFormatText and not OutputFormatJson and not OutputFormatCount and not OutputFormatCompact)
-            {
-                WriteUsageError(
-                    "--format csv/tsv/lsp/qf/sarif/issue-drafts is not supported with --named-query.",
-                    options,
-                    "Use plain text output, `--json`, `--format count`, or `--format compact` for grouped ad hoc results.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.JsonOutputFormat == JsonOutputFormatArray)
-            {
-                WriteUsageError(
-                    "--json=array is not supported with --named-query because named batch output is grouped by query.",
-                    options,
-                    "Use plain `--json` for the grouped named-query object.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.MaxJsonBytes.HasValue && !options.Json)
-            {
-                WriteUsageError(
-                    "--max-json-bytes is only supported with JSON search output.",
-                    options,
-                    "Use `--json` or `--format compact` with --named-query when bounding named batch output.");
-                return CommandExitCodes.UsageError;
-            }
-
-            if (options.CountOnly || options.SummaryOnly)
-                return RunSearchNamedBatchCount(options, jsonOptions, exactSearch);
-
-            return RunSearchNamedBatch(options, jsonOptions, exactSearch);
-        }
-        if (options.RecipeName != null)
-        {
-            if (options.TokenBoundary)
-            {
-                WriteUsageError(
-                    "--token-boundary is only supported for ad hoc search and --named-query batches, not recipe execution.",
-                    options,
-                    "Run an individual query without --recipe if token-boundary filtering is required.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.Query != null || options.ExtraNames.Count > 0)
-            {
-                WriteUsageError(
-                    "--recipe expands into its own curated query set and cannot be combined with a search query.",
-                    options,
-                    "Remove the positional query, or run a plain `cdidx search <query>` without --recipe.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.Prefix)
-            {
-                WriteUsageError(
-                    "--prefix is not supported with --recipe because each recipe query defines its own match mode.",
-                    options,
-                    "Remove --prefix, or run the individual query from the recipe list yourself.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.OutputFormat is not OutputFormatText and not OutputFormatJson and not OutputFormatCount and not OutputFormatCompact and not OutputFormatSarif and not OutputFormatIssueDrafts)
-            {
-                WriteUsageError(
-                    "--format csv/tsv/lsp/qf is not supported with --recipe.",
-                    options,
-                    "Use `--count` / `--format count` for count-only recipe output, `--json` for grouped recipe results, `--format compact` for summary-first compact JSON, `--format sarif` for audit findings, or `--format issue-drafts` for draft exports.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.JsonOutputFormat == JsonOutputFormatArray)
-            {
-                WriteUsageError(
-                    "--json=array is not supported with --recipe because recipe output is grouped by query.",
-                    options,
-                    "Use plain `--json` for the grouped recipe object.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.OutputFormat == OutputFormatSarif
-                && (options.CountOnly
-                    || options.SummaryOnly
-                    || options.GroupBy != null
-                    || options.CountBy != null
-                    || options.UniqueBy != null
-                    || options.ResultsOnly
-                    || options.SearchFields != null
-                    || options.FirstPerFile
-                    || options.SampleSize.HasValue
-                    || options.GroupedPerFileLimitExplicit
-                    || (options.JsonOutputFormatExplicit && options.JsonOutputFormat == JsonOutputFormatNdjson)))
-            {
-                WriteUsageError(
-                    "--format sarif cannot be combined with recipe count, summary, aggregation, projection, row-selection, or NDJSON controls.",
-                    options,
-                    "Use `--recipe <name> --format sarif` with result filters and `--limit` / `--total-limit`, or choose the JSON/count output shape instead.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.GroupedPerFileLimitExplicit)
-            {
-                WriteUsageError(
-                    "--per-file-limit is not supported with --recipe because recipe execution does not produce grouped search output.",
-                    options,
-                    "Use --first-per-file for one selected recipe row per file, or remove --recipe and use grouped ad hoc search output.");
-                return CommandExitCodes.UsageError;
-            }
-            if ((options.FirstPerFile || options.SampleSize.HasValue)
-                && options.SearchCursor.HasValue)
-            {
-                WriteUsageError(
-                    "recipe row-selection controls cannot be combined with --cursor because raw recipe cursors cannot preserve selector state.",
-                    options,
-                    "Remove --cursor and rerun selection from the beginning, or remove --first-per-file / --sample to resume from the cursor.");
-                return CommandExitCodes.UsageError;
-            }
-            if ((options.FirstPerFile || options.SampleSize.HasValue)
-                && (options.CountOnly
-                    || options.GroupBy != null
-                    || options.CountBy != null
-                    || options.UniqueBy != null
-                    || options.ResultsOnly
-                    || (options.SummaryOnly && (options.Compact || options.OutputFormat == OutputFormatCompact))))
-            {
-                WriteUsageError(
-                    "recipe row-selection controls cannot be combined with count, aggregation, results-only, or summary-only compact output.",
-                    options,
-                    "Remove --first-per-file / --sample to keep the non-row output, or choose text, JSON, compact, NDJSON, or issue-drafts row output.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.MaxJsonBytes.HasValue && !SupportsSearchJsonByteLimit(options))
-            {
-                WriteUsageError(
-                    "--max-json-bytes is only supported with JSON search output.",
-                    options,
-                    "Use `--json=ndjson`, `--format count`, `--format compact`, grouped/count-by JSON, or `--format issue-drafts` with --max-json-bytes.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.ResultsOnly && options.JsonOutputFormat != JsonOutputFormatNdjson)
-            {
-                WriteUsageError(
-                    "--results-only is only supported with NDJSON recipe output.",
-                    options,
-                    "Use `--recipe <name> --results-only --search-fields path,line,query_name`, or remove --results-only.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.GroupBy != null)
-            {
-                if (!IsSupportedSearchGroupByValue(options.GroupBy))
-                {
-                    WriteUsageError(
-                        "--group-by for recipe search must be one of file, symbol, origin, return-type, or subsystem.",
-                        options,
-                        $"Use `{invocationContext.RecipeCommandPrefix} <name> --group-by file --count`, `--group-by symbol --count`, `--group-by return-type --count`, `--group-by subsystem --count`, or `--count-by origin`.");
-                    return CommandExitCodes.UsageError;
-                }
-                if (!options.CountOnly)
-                {
-                    WriteUsageError(
-                        $"{invocationContext.RecipeExecutionName} --group-by requires --count.",
-                        options,
-                        "Add --count to request grouped recipe result counts, or remove --group-by to print matching snippets.");
-                    return CommandExitCodes.UsageError;
-                }
-            }
-            if (options.CountBy != null && !IsSupportedSearchAggregationValue(options.CountBy))
-            {
-                WriteUsageError(
-                    "--count-by for recipe search must be one of path, file, symbol, origin, return-type, or subsystem.",
-                    options,
-                    "Use `--count-by path`, `--count-by symbol`, `--count-by return-type`, `--count-by subsystem`, or `--count-by origin`.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.UniqueBy != null && !IsSupportedSearchAggregationValue(options.UniqueBy))
-            {
-                WriteUsageError(
-                    "--unique for recipe search must be one of path, file, symbol, origin, return-type, or subsystem.",
-                    options,
-                    "Use `--unique path`, `--unique symbol`, `--unique return-type`, `--unique subsystem`, or `--unique origin`.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.CountBy != null && options.UniqueBy != null)
-            {
-                WriteUsageError(
-                    "--count-by cannot be combined with --unique.",
-                    options,
-                    "Run one recipe aggregation mode at a time.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.GroupBy != null && (options.CountBy != null || options.UniqueBy != null))
-            {
-                WriteUsageError(
-                    "--group-by cannot be combined with --count-by or --unique.",
-                    options,
-                    "Use either `--group-by <field> --count`, `--count-by <field>`, or `--unique <field>`.");
-                return CommandExitCodes.UsageError;
-            }
-            if ((options.GroupBy != null || options.CountBy != null || options.UniqueBy != null) && (options.ResultsOnly || options.SearchFields != null))
-            {
-                WriteUsageError(
-                    "recipe aggregation cannot be combined with --results-only or --search-fields.",
-                    options,
-                    "Run the aggregation separately, or remove --count-by/--group-by to stream projected recipe rows.");
-                return CommandExitCodes.UsageError;
-            }
-
-            if (options.CountOnly || (options.SummaryOnly && (options.Compact || options.OutputFormat == OutputFormatCompact)))
-            {
-                if (options.GroupBy != null || options.CountBy != null || options.UniqueBy != null)
-                    return RunSearchRecipeAggregation(options, jsonOptions, exact);
-
-                return RunSearchRecipeCount(options, jsonOptions, exact);
-            }
-
-            if (options.CountBy != null || options.UniqueBy != null)
-                return RunSearchRecipeAggregation(options, jsonOptions, exact);
-
-            if (options.OutputFormat == OutputFormatIssueDrafts)
-                return RunSearchRecipeIssueDrafts(options, jsonOptions, exact, cancellationToken);
-
-            return RunSearchRecipe(options, jsonOptions, exact);
-        }
-        if (TryWriteBlankQueryError(options, "search"))
+        if (!TryValidateSearchOptions(options, exact, invocationContext))
             return CommandExitCodes.UsageError;
-        if (options.Query == null)
-        {
-            return CommandErrorWriter.WriteJsonOrHuman(
-                options.Json,
-                jsonOptions,
-                "search requires a query argument",
-                CommandExitCodes.UsageError,
-                BuildMissingSearchQueryHint(cmdArgs),
-                GetUsageLineOrThrow("search"),
-                CommandErrorCodes.UsageError,
-                category: "usage");
-        }
-        if (options.Query.Length > QueryLimits.MaxQueryLength)
-        {
-            WriteUsageError(
-                QueryLimits.FormatQueryTooLongError(),
-                options,
-                "Shorten the search text or split generated input into smaller queries before running `cdidx search`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (TryWriteUnexpectedExtraPositionals("search", options))
-            return CommandExitCodes.UsageError;
-        if ((options.FirstPerFile || options.SampleSize.HasValue)
-            && (options.CountOnly
-                || options.GroupBy != null
-                || options.CountBy != null
-                || options.UniqueBy != null
-                || options.OutputFormat == OutputFormatGrouped))
-        {
-            WriteUsageError(
-                "search row-selection controls cannot be combined with count or aggregation output.",
-                options,
-                "Remove --first-per-file / --sample to count the full filtered population, or choose a row output that reports selector accounting.");
-            return CommandExitCodes.UsageError;
-        }
-        if ((options.FirstPerFile || options.SampleSize.HasValue) && options.ResultsOnly)
-        {
-            WriteUsageError(
-                "search row-selection controls cannot be combined with --results-only because that stream omits selector accounting.",
-                options,
-                "Remove --results-only to retain the NDJSON terminal record, or remove --first-per-file / --sample.");
-            return CommandExitCodes.UsageError;
-        }
-        if ((options.FirstPerFile || options.SampleSize.HasValue)
-            && options.JsonOutputFormat == JsonOutputFormatArray)
-        {
-            WriteUsageError(
-                "search row-selection controls cannot be combined with metadata-free --json=array output.",
-                options,
-                "Add --json-envelope to retain selector accounting, use --json=ndjson / --format compact, or remove --first-per-file / --sample.");
-            return CommandExitCodes.UsageError;
-        }
-        if ((options.FirstPerFile || options.SampleSize.HasValue)
-            && options.OutputFormat is not OutputFormatText
-                and not OutputFormatJson
-                and not OutputFormatCompact
-                and not OutputFormatIssueDrafts)
-        {
-            WriteUsageError(
-                "search row-selection controls are only supported by text, JSON, compact, and issue-drafts row output.",
-                options,
-                "Choose an output shape that reports selector accounting, or remove --first-per-file / --sample.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.GroupBy != null)
-        {
-            if (!IsSupportedSearchGroupByValue(options.GroupBy))
-            {
-                WriteUsageError(
-                    "--group-by for search must be one of file, symbol, origin, return-type, or subsystem.",
-                    options,
-                    "Use `cdidx search <query> --group-by file --count`, `--group-by symbol --count`, `--group-by return-type --count`, `--group-by subsystem --count`, or `--count-by origin`.");
-                return CommandExitCodes.UsageError;
-            }
-            if (!options.CountOnly)
-            {
-                WriteUsageError(
-                    "search --group-by requires --count.",
-                    options,
-                    "Add --count to request grouped result counts, or remove --group-by to print matching snippets.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.OutputFormat is not OutputFormatText and not OutputFormatJson and not OutputFormatCount)
-            {
-                WriteUsageError(
-                    "--group-by for search only supports plain count output or JSON.",
-                    options,
-                    "Use `--count`, optionally with `--json`, instead of compact/location formats.");
-                return CommandExitCodes.UsageError;
-            }
-            if (options.JsonOutputFormat == JsonOutputFormatArray)
-            {
-                WriteUsageError(
-                    "--json=array is not supported with search --group-by because grouped count output is a JSON object.",
-                    options,
-                    "Use plain `--json` for the grouped-count object.");
-                return CommandExitCodes.UsageError;
-            }
-        }
-        if (options.CountBy != null && options.UniqueBy != null)
-        {
-            WriteUsageError(
-                "--count-by cannot be combined with --unique.",
-                options,
-                "Run one aggregation mode at a time.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.GroupBy != null && (options.CountBy != null || options.UniqueBy != null))
-        {
-            WriteUsageError(
-                "--group-by cannot be combined with --count-by or --unique.",
-                options,
-                "Use either `--group-by <field> --count`, `--count-by <field>`, or `--unique <field>`.");
-            return CommandExitCodes.UsageError;
-        }
-        if ((options.CountBy != null || options.UniqueBy != null) && options.JsonOutputFormat == JsonOutputFormatArray)
-        {
-            WriteUsageError(
-                "--json=array is not supported with search aggregation because aggregation output is a JSON object.",
-                options,
-                "Use plain `--json` for `--count-by` or `--unique` aggregation output.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.OutputFormat == OutputFormatGrouped && options.JsonOutputFormat == JsonOutputFormatArray)
-        {
-            WriteUsageError(
-                "--json=array is not supported with search --format grouped because grouped output is a JSON object.",
-                options,
-                "Use plain `--json` or omit --json when using `--format grouped`.");
+        if (!TryCreateSearchRoutePlan(cmdArgs, options, exact, cancellationToken, out var route))
             return CommandExitCodes.UsageError;
-        }
-        if (options.ResultsOnly && options.JsonOutputFormat != JsonOutputFormatNdjson)
-        {
-            WriteUsageError(
-                "--results-only is only supported with NDJSON search output.",
-                options,
-                "Use `--results-only --json=ndjson`, or remove --results-only when using --json=array.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.MaxJsonBytes.HasValue && !SupportsSearchJsonByteLimit(options))
-        {
-            WriteUsageError(
-                "--max-json-bytes is only supported with JSON search output.",
-                options,
-                "Use `--json=ndjson`, `--json=array`, `--format count`, `--format compact`, grouped/count-by JSON, or `--format issue-drafts` with --max-json-bytes.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.CountBy != null && !IsSupportedSearchAggregationValue(options.CountBy))
-        {
-            WriteUsageError(
-                "--count-by for search must be one of path, file, symbol, origin, return-type, or subsystem.",
-                options,
-                "Use `--count-by path`, `--count-by symbol`, `--count-by return-type`, `--count-by subsystem`, or `--count-by origin`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.UniqueBy != null && !IsSupportedSearchAggregationValue(options.UniqueBy))
-        {
-            WriteUsageError(
-                "--unique for search must be one of path, file, symbol, origin, return-type, or subsystem.",
-                options,
-                "Use `--unique path`, `--unique symbol`, `--unique return-type`, `--unique subsystem`, or `--unique origin`.");
-            return CommandExitCodes.UsageError;
-        }
-        if (options.OutputFormat == OutputFormatIssueDrafts)
-            return RunSearchIssueDrafts(options, jsonOptions, exactSearch, cancellationToken);
-
-        return ExecutePlainSearch(
-            CreateSearchExecutionPlan(options, jsonOptions, exactSearch, options.Query!));
 
+        return ExecuteSearchRoute(route);
     }
 
     private static List<string> FindUnexpectedRecipePositionals(string[] args)
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.SearchRouting.cs b/src/CodeIndex/Cli/QueryCommandRunner.SearchRouting.cs
new file mode 100644
index 000000000..f24ed2944
--- /dev/null
+++ b/src/CodeIndex/Cli/QueryCommandRunner.SearchRouting.cs
@@ -0,0 +1,496 @@
+using System.Text.Json;
+
+namespace CodeIndex.Cli;
+
+public static partial class QueryCommandRunner
+{
+    private enum SearchExecutionKind
+    {
+        RecipeList,
+        NamedBatchCount,
+        NamedBatchRows,
+        RecipeAggregation,
+        RecipeCount,
+        RecipeIssueDrafts,
+        RecipeRows,
+        PlainIssueDrafts,
+        PlainRows,
+    }
+
+    private readonly record struct SearchRoutePlan(
+        SearchExecutionKind Execution,
+        QueryCommandOptions Options,
+        bool Exact,
+        CancellationToken CancellationToken)
+    {
+        internal bool ExactSearch => Exact || Options.TokenBoundary;
+        internal JsonSerializerOptions JsonOptions => GetSearchInvocationJsonOptions(Options);
+    }
+
+    private static bool TryCreateSearchRoutePlan(
+        string[] cmdArgs,
+        QueryCommandOptions options,
+        bool exact,
+        CancellationToken cancellationToken,
+        out SearchRoutePlan route)
+    {
+        route = default;
+        SearchExecutionKind execution;
+        if (options.ListRecipes)
+        {
+            if (!TryValidateSearchRecipeListRoute(options))
+                return false;
+            execution = SearchExecutionKind.RecipeList;
+        }
+        else if (options.NamedSearchQueries.Count > 0)
+        {
+            if (!TryValidateSearchNamedBatchRoute(options))
+                return false;
+            execution = options.CountOnly || options.SummaryOnly
+                ? SearchExecutionKind.NamedBatchCount
+                : SearchExecutionKind.NamedBatchRows;
+        }
+        else if (options.RecipeName != null)
+        {
+            if (!TryValidateSearchRecipeRoute(options))
+                return false;
+            execution = GetSearchRecipeExecutionKind(options);
+        }
+        else
+        {
+            if (!TryValidatePlainSearchRoute(cmdArgs, options))
+                return false;
+            execution = options.OutputFormat == OutputFormatIssueDrafts
+                ? SearchExecutionKind.PlainIssueDrafts
+                : SearchExecutionKind.PlainRows;
+        }
+
+        route = new SearchRoutePlan(execution, options, exact, cancellationToken);
+        return true;
+    }
+
+    private static int ExecuteSearchRoute(SearchRoutePlan route) =>
+        route.Execution switch
+        {
+            SearchExecutionKind.RecipeList => WriteSearchRecipeList(
+                route.Options,
+                route.JsonOptions,
+                route.Options.InvocationContext.CommandName),
+            SearchExecutionKind.NamedBatchCount => RunSearchNamedBatchCount(
+                route.Options,
+                route.JsonOptions,
+                route.ExactSearch),
+            SearchExecutionKind.NamedBatchRows => RunSearchNamedBatch(
+                route.Options,
+                route.JsonOptions,
+                route.ExactSearch),
+            SearchExecutionKind.RecipeAggregation => RunSearchRecipeAggregation(
+                route.Options,
+                route.JsonOptions,
+                route.Exact),
+            SearchExecutionKind.RecipeCount => RunSearchRecipeCount(
+                route.Options,
+                route.JsonOptions,
+                route.Exact),
+            SearchExecutionKind.RecipeIssueDrafts => RunSearchRecipeIssueDrafts(
+                route.Options,
+                route.JsonOptions,
+                route.Exact,
+                route.CancellationToken),
+            SearchExecutionKind.RecipeRows => RunSearchRecipe(
+                route.Options,
+                route.JsonOptions,
+                route.Exact),
+            SearchExecutionKind.PlainIssueDrafts => RunSearchIssueDrafts(
+                route.Options,
+                route.JsonOptions,
+                route.ExactSearch,
+                route.CancellationToken),
+            SearchExecutionKind.PlainRows => ExecutePlainSearch(
+                CreateSearchExecutionPlan(
+                    route.Options,
+                    route.JsonOptions,
+                    route.ExactSearch,
+                    route.Options.Query!)),
+            _ => throw new InvalidOperationException("Unknown search execution route."),
+        };
+
+    private static JsonSerializerOptions GetSearchInvocationJsonOptions(QueryCommandOptions options) =>
+        options.InvocationJsonOptions
+        ?? throw new InvalidOperationException("Search invocation JSON options were not initialized.");
+
+    private static SearchExecutionKind GetSearchRecipeExecutionKind(QueryCommandOptions options)
+    {
+        if (options.CountOnly || (options.SummaryOnly && (options.Compact || options.OutputFormat == OutputFormatCompact)))
+        {
+            return HasSearchAggregation(options)
+                ? SearchExecutionKind.RecipeAggregation
+                : SearchExecutionKind.RecipeCount;
+        }
+        if (HasSearchCountOrUniqueAggregation(options))
+            return SearchExecutionKind.RecipeAggregation;
+        return options.OutputFormat == OutputFormatIssueDrafts
+            ? SearchExecutionKind.RecipeIssueDrafts
+            : SearchExecutionKind.RecipeRows;
+    }
+
+    private static bool TryValidateSearchRecipeListRoute(QueryCommandOptions options)
+    {
+        if (HasSearchRowSelectors(options))
+        {
+            return RejectSearchUsage(
+                options,
+                "row-selection controls are not supported with --list-recipes because recipe discovery does not emit search rows.",
+                "Remove --first-per-file / --sample, or execute a recipe or plain search that returns rows.");
+        }
+        if (options.RecipeName != null || options.NamedSearchQueries.Count > 0 || options.ExtraNames.Count > 0)
+        {
+            return RejectSearchUsage(
+                options,
+                "--list-recipes cannot be combined with --recipe, --named-query, or extra positional arguments.",
+                "Run `cdidx search --list-recipes --query <text>` to filter built-in audit recipes by recipe, query, label, severity, path, or search text.");
+        }
+        if (options.OutputFormat is not OutputFormatText and not OutputFormatJson and not OutputFormatCompact)
+        {
+            return RejectSearchUsage(
+                options,
+                "--format count/csv/tsv/lsp/qf/sarif/issue-drafts is not supported with --list-recipes.",
+                "Use plain text output, `--json` / `--format json` for the full recipe list, or `--format compact` for a compact summary.");
+        }
+        if (options.JsonOutputFormat == JsonOutputFormatArray)
+        {
+            return RejectSearchUsage(
+                options,
+                "--json=array is not supported with --list-recipes because recipe-list output is a JSON object.",
+                "Use plain `--json` for the recipe-list object.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidateSearchNamedBatchRoute(QueryCommandOptions options)
+    {
+        if (HasSearchRowSelectors(options))
+        {
+            return RejectSearchUsage(
+                options,
+                "row-selection controls are not supported with --named-query because named batches do not expose selector accounting.",
+                "Remove --first-per-file / --sample, or run each query as a plain search or recipe row output.");
+        }
+        if (options.Query != null || options.RecipeName != null || options.ExtraNames.Count > 0)
+        {
+            return RejectSearchUsage(
+                options,
+                "--named-query cannot be combined with a positional query, --query, --recipe, or extra positional arguments.",
+                "Pass one or more `--named-query <name>=<query>` values, or run a plain `cdidx search <query>`.");
+        }
+        if (options.OpenIssuesPath != null)
+        {
+            return RejectSearchUsage(
+                options,
+                "--open-issues can only be used with `cdidx search --recipe <name> --format issue-drafts`.",
+                "Remove --open-issues for ad hoc named batches.");
+        }
+        if (options.OutputFormat is not OutputFormatText and not OutputFormatJson and not OutputFormatCount and not OutputFormatCompact)
+        {
+            return RejectSearchUsage(
+                options,
+                "--format csv/tsv/lsp/qf/sarif/issue-drafts is not supported with --named-query.",
+                "Use plain text output, `--json`, `--format count`, or `--format compact` for grouped ad hoc results.");
+        }
+        if (options.JsonOutputFormat == JsonOutputFormatArray)
+        {
+            return RejectSearchUsage(
+                options,
+                "--json=array is not supported with --named-query because named batch output is grouped by query.",
+                "Use plain `--json` for the grouped named-query object.");
+        }
+        if (options.MaxJsonBytes.HasValue && !options.Json)
+        {
+            return RejectSearchUsage(
+                options,
+                "--max-json-bytes is only supported with JSON search output.",
+                "Use `--json` or `--format compact` with --named-query when bounding named batch output.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidateSearchRecipeRoute(QueryCommandOptions options) =>
+        TryValidateSearchRecipeIdentityAndOutput(options)
+        && TryValidateSearchRecipeRowSelection(options)
+        && TryValidateSearchRecipeAggregation(options);
+
+    private static bool TryValidateSearchRecipeIdentityAndOutput(QueryCommandOptions options)
+    {
+        if (options.TokenBoundary)
+        {
+            return RejectSearchUsage(
+                options,
+                "--token-boundary is only supported for ad hoc search and --named-query batches, not recipe execution.",
+                "Run an individual query without --recipe if token-boundary filtering is required.");
+        }
+        if (options.Query != null || options.ExtraNames.Count > 0)
+        {
+            return RejectSearchUsage(
+                options,
+                "--recipe expands into its own curated query set and cannot be combined with a search query.",
+                "Remove the positional query, or run a plain `cdidx search <query>` without --recipe.");
+        }
+        if (options.Prefix)
+        {
+            return RejectSearchUsage(
+                options,
+                "--prefix is not supported with --recipe because each recipe query defines its own match mode.",
+                "Remove --prefix, or run the individual query from the recipe list yourself.");
+        }
+        if (options.OutputFormat is not OutputFormatText and not OutputFormatJson and not OutputFormatCount and not OutputFormatCompact and not OutputFormatSarif and not OutputFormatIssueDrafts)
+        {
+            return RejectSearchUsage(
+                options,
+                "--format csv/tsv/lsp/qf is not supported with --recipe.",
+                "Use `--count` / `--format count` for count-only recipe output, `--json` for grouped recipe results, `--format compact` for summary-first compact JSON, `--format sarif` for audit findings, or `--format issue-drafts` for draft exports.");
+        }
+        if (options.JsonOutputFormat == JsonOutputFormatArray)
+        {
+            return RejectSearchUsage(
+                options,
+                "--json=array is not supported with --recipe because recipe output is grouped by query.",
+                "Use plain `--json` for the grouped recipe object.");
+        }
+        if (options.OutputFormat == OutputFormatSarif
+            && (options.CountOnly
+                || options.SummaryOnly
+                || HasSearchAggregation(options)
+                || options.ResultsOnly
+                || options.SearchFields != null
+                || HasSearchRowSelectors(options)
+                || options.GroupedPerFileLimitExplicit
+                || (options.JsonOutputFormatExplicit && options.JsonOutputFormat == JsonOutputFormatNdjson)))
+        {
+            return RejectSearchUsage(
+                options,
+                "--format sarif cannot be combined with recipe count, summary, aggregation, projection, row-selection, or NDJSON controls.",
+                "Use `--recipe <name> --format sarif` with result filters and `--limit` / `--total-limit`, or choose the JSON/count output shape instead.");
+        }
+        if (options.GroupedPerFileLimitExplicit)
+        {
+            return RejectSearchUsage(
+                options,
+                "--per-file-limit is not supported with --recipe because recipe execution does not produce grouped search output.",
+                "Use --first-per-file for one selected recipe row per file, or remove --recipe and use grouped ad hoc search output.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidateSearchRecipeRowSelection(QueryCommandOptions options)
+    {
+        if (HasSearchRowSelectors(options) && options.SearchCursor.HasValue)
+        {
+            return RejectSearchUsage(
+                options,
+                "recipe row-selection controls cannot be combined with --cursor because raw recipe cursors cannot preserve selector state.",
+                "Remove --cursor and rerun selection from the beginning, or remove --first-per-file / --sample to resume from the cursor.");
+        }
+        if (HasSearchRowSelectors(options)
+            && (options.CountOnly
+                || HasSearchAggregation(options)
+                || options.ResultsOnly
+                || (options.SummaryOnly && (options.Compact || options.OutputFormat == OutputFormatCompact))))
+        {
+            return RejectSearchUsage(
+                options,
+                "recipe row-selection controls cannot be combined with count, aggregation, results-only, or summary-only compact output.",
+                "Remove --first-per-file / --sample to keep the non-row output, or choose text, JSON, compact, NDJSON, or issue-drafts row output.");
+        }
+        if (options.MaxJsonBytes.HasValue && !SupportsSearchJsonByteLimit(options))
+        {
+            return RejectSearchUsage(
+                options,
+                "--max-json-bytes is only supported with JSON search output.",
+                "Use `--json=ndjson`, `--format count`, `--format compact`, grouped/count-by JSON, or `--format issue-drafts` with --max-json-bytes.");
+        }
+        if (options.ResultsOnly && options.JsonOutputFormat != JsonOutputFormatNdjson)
+        {
+            return RejectSearchUsage(
+                options,
+                "--results-only is only supported with NDJSON recipe output.",
+                "Use `--recipe <name> --results-only --search-fields path,line,query_name`, or remove --results-only.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidateSearchRecipeAggregation(QueryCommandOptions options)
+    {
+        if (options.GroupBy != null)
+        {
+            if (!IsSupportedSearchGroupByValue(options.GroupBy))
+            {
+                return RejectSearchUsage(
+                    options,
+                    "--group-by for recipe search must be one of file, symbol, origin, return-type, or subsystem.",
+                    $"Use `{options.InvocationContext.RecipeCommandPrefix} <name> --group-by file --count`, `--group-by symbol --count`, `--group-by return-type --count`, `--group-by subsystem --count`, or `--count-by origin`.");
+            }
+            if (!options.CountOnly)
+            {
+                return RejectSearchUsage(
+                    options,
+                    $"{options.InvocationContext.RecipeExecutionName} --group-by requires --count.",
+                    "Add --count to request grouped recipe result counts, or remove --group-by to print matching snippets.");
+            }
+        }
+        if (!TryValidateSearchAggregationFields(options, SearchAggregationTarget.Recipe))
+            return false;
+        if (!TryValidateSearchAggregationConflicts(options, SearchAggregationTarget.Recipe))
+            return false;
+        if (HasSearchAggregation(options) && (options.ResultsOnly || options.SearchFields != null))
+        {
+            return RejectSearchUsage(
+                options,
+                "recipe aggregation cannot be combined with --results-only or --search-fields.",
+                "Run the aggregation separately, or remove --count-by/--group-by to stream projected recipe rows.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidatePlainSearchRoute(string[] cmdArgs, QueryCommandOptions options) =>
+        TryValidatePlainSearchQuery(cmdArgs, options)
+        && TryValidatePlainSearchRowSelection(options)
+        && TryValidatePlainSearchAggregationShape(options);
+
+    private static bool TryValidatePlainSearchQuery(string[] cmdArgs, QueryCommandOptions options)
+    {
+        if (TryWriteBlankQueryError(options, "search"))
+            return false;
+        if (options.Query == null)
+        {
+            CommandErrorWriter.WriteJsonOrHuman(
+                options.Json,
+                GetSearchInvocationJsonOptions(options),
+                "search requires a query argument",
+                CommandExitCodes.UsageError,
+                BuildMissingSearchQueryHint(cmdArgs),
+                GetUsageLineOrThrow("search"),
+                CommandErrorCodes.UsageError,
+                category: "usage");
+            return false;
+        }
+        if (options.Query.Length > QueryLimits.MaxQueryLength)
+            return RejectSearchUsage(
+                options,
+                QueryLimits.FormatQueryTooLongError(),
+                "Shorten the search text or split generated input into smaller queries before running `cdidx search`.");
+        return !TryWriteUnexpectedExtraPositionals("search", options);
+    }
+
+    private static bool TryValidatePlainSearchRowSelection(QueryCommandOptions options)
+    {
+        if (HasSearchRowSelectors(options)
+            && (options.CountOnly
+                || HasSearchAggregation(options)
+                || options.OutputFormat == OutputFormatGrouped))
+        {
+            return RejectSearchUsage(
+                options,
+                "search row-selection controls cannot be combined with count or aggregation output.",
+                "Remove --first-per-file / --sample to count the full filtered population, or choose a row output that reports selector accounting.");
+        }
+        if (HasSearchRowSelectors(options) && options.ResultsOnly)
+        {
+            return RejectSearchUsage(
+                options,
+                "search row-selection controls cannot be combined with --results-only because that stream omits selector accounting.",
+                "Remove --results-only to retain the NDJSON terminal record, or remove --first-per-file / --sample.");
+        }
+        if (HasSearchRowSelectors(options) && options.JsonOutputFormat == JsonOutputFormatArray)
+        {
+            return RejectSearchUsage(
+                options,
+                "search row-selection controls cannot be combined with metadata-free --json=array output.",
+                "Add --json-envelope to retain selector accounting, use --json=ndjson / --format compact, or remove --first-per-file / --sample.");
+        }
+        if (HasSearchRowSelectors(options)
+            && options.OutputFormat is not OutputFormatText
+                and not OutputFormatJson
+                and not OutputFormatCompact
+                and not OutputFormatIssueDrafts)
+        {
+            return RejectSearchUsage(
+                options,
+                "search row-selection controls are only supported by text, JSON, compact, and issue-drafts row output.",
+                "Choose an output shape that reports selector accounting, or remove --first-per-file / --sample.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidatePlainSearchAggregationShape(QueryCommandOptions options)
+    {
+        if (options.GroupBy != null)
+        {
+            if (!IsSupportedSearchGroupByValue(options.GroupBy))
+            {
+                return RejectSearchUsage(
+                    options,
+                    "--group-by for search must be one of file, symbol, origin, return-type, or subsystem.",
+                    "Use `cdidx search <query> --group-by file --count`, `--group-by symbol --count`, `--group-by return-type --count`, `--group-by subsystem --count`, or `--count-by origin`.");
+            }
+            if (!options.CountOnly)
+            {
+                return RejectSearchUsage(
+                    options,
+                    "search --group-by requires --count.",
+                    "Add --count to request grouped result counts, or remove --group-by to print matching snippets.");
+            }
+            if (options.OutputFormat is not OutputFormatText and not OutputFormatJson and not OutputFormatCount)
+            {
+                return RejectSearchUsage(
+                    options,
+                    "--group-by for search only supports plain count output or JSON.",
+                    "Use `--count`, optionally with `--json`, instead of compact/location formats.");
+            }
+            if (options.JsonOutputFormat == JsonOutputFormatArray)
+            {
+                return RejectSearchUsage(
+                    options,
+                    "--json=array is not supported with search --group-by because grouped count output is a JSON object.",
+                    "Use plain `--json` for the grouped-count object.");
+            }
+        }
+        if (!TryValidateSearchAggregationConflicts(options, SearchAggregationTarget.Plain))
+            return false;
+        if (HasSearchCountOrUniqueAggregation(options) && options.JsonOutputFormat == JsonOutputFormatArray)
+        {
+            return RejectSearchUsage(
+                options,
+                "--json=array is not supported with search aggregation because aggregation output is a JSON object.",
+                "Use plain `--json` for `--count-by` or `--unique` aggregation output.");
+        }
+        if (options.OutputFormat == OutputFormatGrouped && options.JsonOutputFormat == JsonOutputFormatArray)
+        {
+            return RejectSearchUsage(
+                options,
+                "--json=array is not supported with search --format grouped because grouped output is a JSON object.",
+                "Use plain `--json` or omit --json when using `--format grouped`.");
+        }
+        if (options.ResultsOnly && options.JsonOutputFormat != JsonOutputFormatNdjson)
+        {
+            return RejectSearchUsage(
+                options,
+                "--results-only is only supported with NDJSON search output.",
+                "Use `--results-only --json=ndjson`, or remove --results-only when using --json=array.");
+        }
+        if (options.MaxJsonBytes.HasValue && !SupportsSearchJsonByteLimit(options))
+        {
+            return RejectSearchUsage(
+                options,
+                "--max-json-bytes is only supported with JSON search output.",
+                "Use `--json=ndjson`, `--json=array`, `--format count`, `--format compact`, grouped/count-by JSON, or `--format issue-drafts` with --max-json-bytes.");
+        }
+
+        return TryValidateSearchAggregationFields(options, SearchAggregationTarget.Plain);
+    }
+}
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.SearchValidation.cs b/src/CodeIndex/Cli/QueryCommandRunner.SearchValidation.cs
new file mode 100644
index 000000000..335830b6c
--- /dev/null
+++ b/src/CodeIndex/Cli/QueryCommandRunner.SearchValidation.cs
@@ -0,0 +1,296 @@
+namespace CodeIndex.Cli;
+
+public static partial class QueryCommandRunner
+{
+    private enum SearchAggregationTarget
+    {
+        Plain,
+        Recipe,
+    }
+
+    private static bool TryValidateSearchOptions(
+        QueryCommandOptions options,
+        bool exact,
+        QueryCommandInvocationContext invocationContext) =>
+        TryValidateSearchIssueSourceOptions(options)
+        && TryValidateSearchRecipeControlOptions(options)
+        && TryValidateSearchIssueShapeOptions(options)
+        && TryValidateSearchDiscoveryShapeOptions(options)
+        && TryValidateSearchCrossRouteOptions(options, exact, invocationContext);
+
+    private static bool TryValidateSearchIssueSourceOptions(QueryCommandOptions options)
+    {
+        if (options.OpenIssuesPath != null && options.OutputFormat != OutputFormatIssueDrafts)
+        {
+            return RejectSearchUsage(
+                options,
+                "--open-issues can only be used with `cdidx search --format issue-drafts`.",
+                "Use an open-issues JSON file from `gh issue list --state open --json number,title,labels,url`.");
+        }
+        if (options.OpenIssuesRepository != null && !IssueDuplicatePreflight.IsGitHubOpenIssuesSource(options.OpenIssuesPath))
+        {
+            return RejectSearchUsage(
+                options,
+                "--repo can only be used with `--open-issues github`.",
+                "Use `--open-issues github --repo owner/name` to fetch open issues directly from GitHub.");
+        }
+        if (options.IssueState != IssueDuplicatePreflight.DefaultIssueState && !IssueDuplicatePreflight.IsGitHubOpenIssuesSource(options.OpenIssuesPath))
+            return RejectSearchUsage(options, "--issue-state can only be used with `--open-issues github`.", "Use `--open-issues github --repo owner/name --issue-state all`.");
+        if (options.DuplicatePreflightTuningExplicit && options.OutputFormat != OutputFormatIssueDrafts)
+        {
+            return RejectSearchUsage(
+                options,
+                "--duplicate-confidence and --duplicate-threshold can only be used with `cdidx search --format issue-drafts`.",
+                "Use these controls when exporting issue draft JSON with duplicate-preflight metadata.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidateSearchRecipeControlOptions(QueryCommandOptions options)
+    {
+        if ((options.IncludeRecipeQueries.Count > 0 || options.ExcludeRecipeQueries.Count > 0) && options.RecipeName == null)
+        {
+            return RejectSearchUsage(
+                options,
+                "--include-query and --exclude-query can only be used with --recipe.",
+                "Use `--recipe risky-code --include-query raw-diagnostic-echo` to run a child query subset.");
+        }
+        if (options.SearchCursor.HasValue && options.RecipeName == null)
+        {
+            return RejectSearchUsage(
+                options,
+                "--cursor can only be used with --recipe.",
+                "Use `--recipe risky-code/raw-diagnostic-echo --format compact --cursor <next_cursor>` to fetch the next page for one child query.");
+        }
+        if (options.UnusedCursorOffset.HasValue)
+        {
+            return RejectSearchUsage(
+                options,
+                "--cursor for search must be a search pagination cursor returned by recipe search.",
+                "Use `--cursor <next_cursor>` only with `--recipe`; `unused:<offset>` cursors are for `cdidx unused`.");
+        }
+        if (options.OutlineCursorOffset.HasValue)
+        {
+            return RejectSearchUsage(
+                options,
+                "--cursor for search must be a search pagination cursor returned by recipe search.",
+                "`outline:<offset>` cursors are for `cdidx outline <path>`.");
+        }
+        if (options.DependencyCycleCursor.HasValue)
+        {
+            return RejectSearchUsage(
+                options,
+                "--cursor for search must be a search pagination cursor returned by recipe search.",
+                "Dependency-cycle cursors are for `cdidx deps --cycles`.");
+        }
+        if (options.AuditScopeExplicit && options.RecipeName == null && options.ListRecipes)
+        {
+            return RejectSearchUsage(
+                options,
+                "--audit-scope cannot be combined with `cdidx search --list-recipes`.",
+                "Use `--query <text>` with --list-recipes to filter recipe discovery, or run an ad hoc search with `--source-only`.");
+        }
+        if (options.ShowExcluded && options.RecipeName == null)
+        {
+            return RejectSearchUsage(
+                options,
+                "--show-excluded is only supported with `cdidx search --recipe <name>`.",
+                "Use it with a recipe run to include the effective scope and exclusion diagnostics in JSON output.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidateSearchIssueShapeOptions(QueryCommandOptions options)
+    {
+        if ((options.IssueTitle != null || options.IssueLabels.Count > 0) && options.OutputFormat != OutputFormatIssueDrafts)
+        {
+            return RejectSearchUsage(
+                options,
+                "--issue-title and --issue-label can only be used with `cdidx search --format issue-drafts`.",
+                "Use these hints when exporting issue draft JSON for a plain search.");
+        }
+        if (options.SnippetLines == 0 && options.OutputFormat != OutputFormatIssueDrafts)
+        {
+            return RejectSearchUsage(
+                options,
+                "--snippet-lines 0 is only supported with --format issue-drafts.",
+                "Use `--format issue-drafts --snippet-lines 0` for path/line-only draft evidence, or pass a positive snippet line count for search output.");
+        }
+        if (options.IssueTitle != null && options.RecipeName != null)
+        {
+            return RejectSearchUsage(
+                options,
+                "--issue-title is only supported for ad hoc search issue drafts.",
+                "Recipe issue-drafts produce one draft per recipe query, so their titles are derived from the recipe metadata.");
+        }
+        if (options.OutputFormat == OutputFormatIssueDrafts && options.CountOnly)
+        {
+            return RejectSearchUsage(
+                options,
+                "--count cannot be combined with --format issue-drafts.",
+                "Issue-draft export needs result evidence; remove --count.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidateSearchDiscoveryShapeOptions(QueryCommandOptions options)
+    {
+        if (options.NamesOnly && !options.ListRecipes)
+        {
+            return RejectSearchUsage(
+                options,
+                "--names is only supported with `cdidx recipes` or `cdidx search --list-recipes`.",
+                "Use `cdidx recipes --names --json` for a small deterministic recipe-name list.");
+        }
+        if (options.NamesOnly && options.SummaryOnly)
+        {
+            return RejectSearchUsage(
+                options,
+                "--names cannot be combined with --summary-only.",
+                "Use one recipe-list shape at a time.");
+        }
+        if (options.SummaryOnly
+            && !options.ListRecipes
+            && options.NamedSearchQueries.Count == 0
+            && !(options.RecipeName != null
+                && (options.CountOnly
+                    || options.Compact
+                    || options.OutputFormat == OutputFormatCompact
+                    || options.OutputFormat == OutputFormatIssueDrafts)))
+        {
+            return RejectSearchUsage(
+                options,
+                "--summary-only is only supported with `cdidx recipes` / `cdidx search --list-recipes`, named-query count output, recipe count output, or recipe issue-drafts output.",
+                "Use `cdidx recipes --summary-only --json`, `cdidx search --named-query <name>=<query> --summary-only --json`, `cdidx search --recipe <name> --format compact --summary-only --json`, `cdidx search --recipe <name> --format count --summary-only`, or `cdidx search --recipe <name> --format issue-drafts --summary-only`.");
+        }
+        if (options.OutputFormat == OutputFormatIssueDrafts && options.JsonOutputFormat == JsonOutputFormatArray)
+        {
+            return RejectSearchUsage(
+                options,
+                "--json=array is not supported with --format issue-drafts because draft export is a JSON object.",
+                "Use plain `--json` or omit --json when exporting issue drafts.");
+        }
+        if (options.SearchCursor.HasValue && options.OutputFormat == OutputFormatIssueDrafts)
+        {
+            return RejectSearchUsage(
+                options,
+                "--cursor cannot be combined with --format issue-drafts.",
+                "Use --cursor with recipe JSON or compact output, then export issue drafts after choosing the desired query page.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidateSearchCrossRouteOptions(
+        QueryCommandOptions options,
+        bool exact,
+        QueryCommandInvocationContext invocationContext)
+    {
+        if ((exact || options.TokenBoundary) && options.Prefix)
+            return RejectSearchValidation(
+                options,
+                "--prefix cannot be combined with --exact / --exact-substring / --token-boundary (exact uses instr(), not FTS5 prefix phrases).",
+                "Drop --prefix to keep the exact substring path, or drop the exact-mode flag to opt into FTS5 prefix matching.");
+        if (options.GroupBy != null && (options.ListRecipes || options.NamedSearchQueries.Count > 0))
+        {
+            var mode = options.ListRecipes
+                ? "--list-recipes"
+                : "--named-query";
+            return RejectSearchUsage(
+                options,
+                $"--group-by is not supported with {mode}.",
+                "Use `cdidx search <query> --group-by file --count` or remove --group-by for recipe-list and named-batch output.");
+        }
+        if (options.OutputFormat == OutputFormatGrouped && (options.ListRecipes || options.NamedSearchQueries.Count > 0 || options.RecipeName != null))
+        {
+            var mode = options.ListRecipes
+                ? "--list-recipes"
+                : options.NamedSearchQueries.Count > 0
+                    ? "--named-query"
+                    : "--recipe";
+            return RejectSearchUsage(
+                options,
+                "--format grouped is only supported for plain search output.",
+                invocationContext.RecipeNameIsPositional && mode == "--recipe"
+                    ? "Run a plain `cdidx search <query> --format grouped`; audit recipe execution does not support grouped output."
+                    : $"Remove {mode}, or run a plain `cdidx search <query> --format grouped`.");
+        }
+
+        return !TryWriteCappedJsonDiagnosticsUsageError(invocationContext.CommandName, options);
+    }
+
+    private static bool HasSearchRowSelectors(QueryCommandOptions options) =>
+        options.FirstPerFile || options.SampleSize.HasValue;
+
+    private static bool HasSearchAggregation(QueryCommandOptions options) =>
+        options.GroupBy != null || options.CountBy != null || options.UniqueBy != null;
+
+    private static bool HasSearchCountOrUniqueAggregation(QueryCommandOptions options) =>
+        options.CountBy != null || options.UniqueBy != null;
+
+    private static bool TryValidateSearchAggregationFields(
+        QueryCommandOptions options,
+        SearchAggregationTarget target)
+    {
+        var recipe = target == SearchAggregationTarget.Recipe;
+        if (options.CountBy != null && !IsSupportedSearchAggregationValue(options.CountBy))
+        {
+            return RejectSearchUsage(
+                options,
+                recipe
+                    ? "--count-by for recipe search must be one of path, file, symbol, origin, return-type, or subsystem."
+                    : "--count-by for search must be one of path, file, symbol, origin, return-type, or subsystem.",
+                "Use `--count-by path`, `--count-by symbol`, `--count-by return-type`, `--count-by subsystem`, or `--count-by origin`.");
+        }
+        if (options.UniqueBy != null && !IsSupportedSearchAggregationValue(options.UniqueBy))
+        {
+            return RejectSearchUsage(
+                options,
+                recipe
+                    ? "--unique for recipe search must be one of path, file, symbol, origin, return-type, or subsystem."
+                    : "--unique for search must be one of path, file, symbol, origin, return-type, or subsystem.",
+                "Use `--unique path`, `--unique symbol`, `--unique return-type`, `--unique subsystem`, or `--unique origin`.");
+        }
+
+        return true;
+    }
+
+    private static bool TryValidateSearchAggregationConflicts(
+        QueryCommandOptions options,
+        SearchAggregationTarget target)
+    {
+        if (options.CountBy != null && options.UniqueBy != null)
+        {
+            return RejectSearchUsage(
+                options,
+                "--count-by cannot be combined with --unique.",
+                target == SearchAggregationTarget.Recipe
+                    ? "Run one recipe aggregation mode at a time."
+                    : "Run one aggregation mode at a time.");
+        }
+        if (options.GroupBy != null && HasSearchCountOrUniqueAggregation(options))
+        {
+            return RejectSearchUsage(
+                options,
+                "--group-by cannot be combined with --count-by or --unique.",
+                "Use either `--group-by <field> --count`, `--count-by <field>`, or `--unique <field>`.");
+        }
+
+        return true;
+    }
+
+    private static bool RejectSearchUsage(QueryCommandOptions options, string message, string hint)
+    {
+        WriteUsageError(message, options, hint);
+        return false;
+    }
+
+    private static bool RejectSearchValidation(QueryCommandOptions options, string message, string hint)
+    {
+        WriteSearchValidationError(message, options, hint);
+        return false;
+    }
+}
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
index 83dc21fbf..3868e460c 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
@@ -12729,19 +12729,25 @@ public void RunSearchCore_ValidationRoutingAndDatabaseExecutionRemainAligned()
                 "invalid.db",
                 "not a SQLite database");
 
-            var (validationExitCode, validationStdout, validationStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
-                [
-                    "AlignmentNeedle",
-                    "--db", invalidDbPath,
-                    "--count",
-                    "--group-by", "file",
-                    "--count-by", "file"
-                ],
-                _jsonOptions));
+            var validationCases = new (string[] Arguments, string ExpectedError)[]
+            {
+                (["AlignmentNeedle", "--count", "--group-by", "file", "--count-by", "file"], "--group-by cannot be combined with --count-by or --unique"),
+                (["--list-recipes", "--named-query", "named=AlignmentNeedle"], "--list-recipes cannot be combined with --recipe, --named-query, or extra positional arguments"),
+                (["--named-query", "named=AlignmentNeedle", "--recipe", "risky-code"], "--named-query cannot be combined with a positional query, --query, --recipe, or extra positional arguments"),
+                (["AlignmentNeedle", "--recipe", "risky-code"], "--recipe expands into its own curated query set and cannot be combined with a search query"),
+                (["--recipe", "risky-code", "--count-by", "bogus", "--unique", "file"], "--count-by for recipe search must be one of path, file, symbol, origin, return-type, or subsystem"),
+                (["AlignmentNeedle", "--count-by", "bogus", "--unique", "file"], "--count-by cannot be combined with --unique"),
+            };
+            foreach (var (arguments, expectedError) in validationCases)
+            {
+                var (validationExitCode, validationStdout, validationStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
+                    [.. arguments, "--db", invalidDbPath],
+                    _jsonOptions));
 
-            Assert.Equal(CommandExitCodes.UsageError, validationExitCode);
-            Assert.Equal(string.Empty, validationStdout);
-            Assert.Contains("--group-by cannot be combined with --count-by or --unique", validationStderr);
+                Assert.Equal(CommandExitCodes.UsageError, validationExitCode);
+                Assert.Equal(string.Empty, validationStdout);
+                Assert.Contains(expectedError, validationStderr);
+            }
 
             var (zeroCountExitCode, zeroCountStdout, zeroCountStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
                 ["MissingNeedle", "--db", dbPath, "--count", "--json"],

From 766b42640479f0b1aac804f51fe48e8d76f437f3 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 01:10:33 +0900
Subject: [PATCH 35/45] Decompose MCP C# indexing preflight

---
 TESTING_GUIDE.md                              |   2 +
 ...cpToolHandlers.Indexing.CSharpWorkspace.cs | 344 ++++++++++
 .../Mcp/McpToolHandlers.Indexing.Execution.cs | 620 +++++-------------
 ...dlers.Indexing.ExtractedFilePersistence.cs |   4 +-
 .../Mcp/McpToolHandlers.Indexing.FileLoop.cs  |  16 +-
 ...cpToolHandlers.Indexing.FilePersistence.cs |  13 +-
 .../Mcp/McpToolHandlers.Indexing.PreWrite.cs  | 232 +++++++
 .../McpToolHandlers.Indexing.SkippedFiles.cs  |  11 +-
 .../McpServerToolsCallTests.cs                | 143 +++-
 9 files changed, 892 insertions(+), 493 deletions(-)
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.Indexing.CSharpWorkspace.cs
 create mode 100644 src/CodeIndex/Mcp/McpToolHandlers.Indexing.PreWrite.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 4aa50fee3..eeae26c4f 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -462,6 +462,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
 - `PreparedCommandCacheTests.DbWriter_WithCache_CSharpStaticInterfaceContractQueriesReuseCacheAndOneWorkspaceRead` keeps persisted C# contract-member candidates and the pending-path contract flag on one `files(lang)` → `symbols(file_id, kind)` row pass. Derive both results from that reader; do not restore a second all-contract query for excluded paths. Interface declarations may be loaded only for exact retained contract container names through bounded `symbols(name)` batches, and those dynamic tail shapes must stay out of the prepared cache. `DatabaseTests.CSharpContractWorkspaceQueries_UseFileKindThenBoundedInterfaceNamePlans` pins both index plans, while `LoadCSharpContractWorkspace_MaterializesOnlyCandidatesAndMatchingInterfaces` requires negative/LIKE-decoy-only reads to execute no interface phase and keeps unrelated plain interfaces out of managed materialization. `PreparedCommandCacheTests.DbWriter_CSharpStaticInterfaceContractMemberPreflightsAreExactBatchedAndCancellable` also splits a 503-path language lookup at 500 parameters, returns only persisted C# paths plus sorted purge-plan IDs/bytes, keeps both SQL tail shapes out of the prepared cache, and stops before the second batch when cancellation is requested.
 - `IndexCommandRunnerTests.Run_UpdateFiles_CsharpContractPreflightAvoidsRedundantWorkspacePasses` keeps a false source-evidence marker authoritative, leaves the repository-wide persisted-member preflight count at zero, and defers candidate reads plus workspace materialization to the single expanded C# pass. Its plain-interface, newly-added-contract, and persisted-contract phases pin the respective one scoped pass, discovery-plus-expanded passes, and one expanded pass. The paired full-scan/MCP known-evidence no-op fixtures require zero source loads, raw prepasses, persisted C# symbol loads, and lookup builds after the initial true or false snapshot. The shortcut must be rejected when explicit `index_completeness=complete` or GraphReady is absent, when symbols-only/filter/version/root/hotspot contracts drift, or when a persisted C# path changes language. Their final-stat mutation fixtures require one complete raw prepass plus every C# content load, and the explicit/shared-DB root-switch fixtures reject cross-root stat reuse.
   Legacy full-scan checkpoint coverage requires graph-bearing and symbols-only retries alike to rescan every directory and proves full scans neither read nor write HEAD-only resume state. Successful and stable-snapshot partial runs delete a seeded legacy checkpoint after the first barrier, while delete failure remains a warning. Listing-bound snapshot fixtures pin one baseline read per directory and no scan-end whole-tree validation. Full, expanded-Update, and MCP consumer fixtures pin exactly two scan-input validations on successful paths: immediately before index-data mutation and immediately before readiness. First-barrier failure must preserve domain rows, trust, evidence, purge state, and FTS recovery state after schema compatibility initialization; final-barrier failure must stay partial and must not stamp readiness. Ignored-directory churn remains clean.
+  MCP C# pre-write coverage runs the first snapshot-barrier preservation fixture with both ordinary and rebuild requests, so rebuild destruction and interrupted-FTS recovery cannot precede the barrier. A C# stat drift injected at `before_write` must suppress purge, preserve prior C# checksums and implicit-implementation references, publish unknown source evidence, and report only the `csharp_prepass` failure phase. The fresh-rebuild fixture also keeps static-interface evidence and its implicit reference authoritative without admitting C# prepass symbol artifacts.
   Plain-interface purge fixtures keep the sorted file-ID preflight exact, cancellation-aware, and bounded to 500 SQLite parameters per uncached batch. Transition-path preflight coverage places the only real member in the second path batch, requires a path-first `files(path)` plus `symbols(file_id, kind)` index plan, rejects keyword-boundary/casing decoys, interrupts on cancellation, and proves the dynamic commands never enter the prepared cache. One-sided same-stem/checksum rename and positive/unknown-evidence `--changed-between` outside-range fixtures require the immutable cleanup plan to remove stale contract rows before reference regeneration without sweeping unrelated missing non-C# rows; `Run_UpdateFiles_ChangedExistingRetainedTargetPreplansMatchingCsharpAlias` proves an already-indexed, stat-changed retained target also plans a checksum-matching C# alias before workspace construction, while unchanged targets reuse persisted checksums without an extra content read. Binary/oversized skip-record drift fixtures mutate after `BuildSkippedFileRecord` and require the nested cleanup/upsert transaction plus batch marker to roll back before retry. `Run_UpdateMode_WithChangedBetween_PurgesMissingIndexedPathOutsideDiff_4056` separately retains the historical all-language reconciliation under authoritative false evidence. `Run_UpdateMode_WithChangedBetween_CleanupPathReappearingAfterScanIsDeferredUntilRetry` restores a deleted contract during discovery, while `Run_UpdateCommits_ExactCleanupPathReappearingAfterSnapshotBarrierPreservesPriorRow` restores an exact Git-deleted target after the final snapshot barrier; both require a partial result that preserves the prior row and implicit reference. Fatal expanded discovery and post-prepass change/delete fixtures likewise preserve prior C# rows and implicit references, leave source evidence unknown, and converge on a later clean retry; unrelated Python/JavaScript cleanup and unchanged scoped targets still proceed under deferred C# mutation. The parallel symbol-cap fixture requires a contract first observed after prepass to leave source evidence unknown and force a later complete repair.
 - Case-folded cleanup coverage treats SQLite `NOCASE` and managed folding as candidate filters only: leaf-case, ancestor-case, and Unicode-folded paths that resolve to distinct file identities must preserve both exact rows, while a true case-only alias may remove the old spelling without a checksum read. An unrelated hardlink is an alias only when its path and identity match the same retained case-fold bucket; `ScopedFileCleanupReappearance_FoldBucketsDoNotCrossMatchTargetIdentities` prevents a path match from one target and an identity match from another from being combined. Git name-status coverage uses a real NUL-delimited rename whose old/new paths contain a tab and newline and asserts both commit and range helpers return the exact unquoted strings.
 - Project-marker budget integration coverage overrides the directory budget to its smallest boundary and enumerates one child; do not materialize the production 8,192-directory cap merely to prove warning propagation.
@@ -1527,6 +1528,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
 - `PreparedCommandCacheTests.DbWriter_WithCache_CSharpStaticInterfaceContractQueriesReuseCacheAndOneWorkspaceRead` は、永続化済み C# contract member 候補と pending-path contract flag を1回の `files(lang)` → `symbols(file_id, kind)` row passで得ることを固定します。両方を同じ reader から導出し、除外 path 判定のための2回目の全 contract query を戻さないでください。interface 宣言は厳密検証後に保持した contract container 名だけを bounded な `symbols(name)` batch で取得でき、その dynamic tail shape は prepared cache に残してはいけません。`DatabaseTests.CSharpContractWorkspaceQueries_UseFileKindThenBoundedInterfaceNamePlans` は両方の index plan を固定し、`LoadCSharpContractWorkspace_MaterializesOnlyCandidatesAndMatchingInterfaces` は negative / LIKE decoy だけの読込で interface phase が0回となり、無関係な通常 interface を managed materialization へ入れないことを要求します。`PreparedCommandCacheTests.DbWriter_CSharpStaticInterfaceContractMemberPreflightsAreExactBatchedAndCancellable` は503件のpath言語lookupを500 parameterで分割し、永続C# pathと昇順のpurge-plan ID/byteだけを返し、両方のSQL tail shapeをprepared cache外に保ち、1つ目のbatch後のcancellationで2つ目を実行しないことも固定します。
 - `IndexCommandRunnerTests.Run_UpdateFiles_CsharpContractPreflightAvoidsRedundantWorkspacePasses` は false の source-evidence marker を authoritative に保ち、repository 全体の persisted-member preflight 回数を0に固定して、candidate read と workspace materialization を1回の expanded C# passへ委譲します。plain-interface、新規contract追加、永続化済みcontractの各phaseで、それぞれscoped 1回、discovery＋expanded、expanded 1回を固定します。対になるfull-scan/MCPのknown-evidence no-op fixtureでは初回のtrueまたはfalse snapshot以降、source load、raw prepass、永続C# symbol load、lookup buildをすべて0に固定します。明示的な `index_completeness=complete` または GraphReady がない場合、symbols-only/filter/version/root/hotspot contract が変わった場合、永続 C# path が別言語へ変わった場合はshortcutを拒否しなければなりません。final-stat mutation fixtureではcomplete raw prepass 1回と全C# content loadを要求し、explicit/shared DBのroot-switch fixtureではcross-root stat reuseを拒否します。
   legacy full-scan checkpoint fixtureはgraph-bearing / symbols-onlyの両方で全directoryを再scanし、HEAD-only resume stateをfull scanが作成も参照もしないことを固定します。seedした旧checkpointはfirst barrier後にsuccess pathとstable-snapshot partial pathの両方で削除し、delete failureだけをwarningにします。listingに結び付いたsnapshot fixtureは各directoryのbaseline取得が1回、scan終端の全件validationが0回であることを固定します。Full / expanded Update / MCPのconsumer fixtureはsuccessful pathのscan-input validationをfirst-write直前とreadiness直前の2回に固定し、first barrier failureではschema compatibility initialization後のdomain row・trust・evidence・purge・FTS recovery stateが不変、final barrier failureではpartialかつreadiness非stampとなることを要求します。ignored directoryのchurnはcleanのままです。
+  MCP C# のpre-write coverageは通常requestとrebuild requestの両方でfirst snapshot-barrierの保持fixtureを実行し、rebuild破棄と中断FTS recoveryがbarrierより前に起きないことを固定します。`before_write`で注入したC# stat driftではpurgeを抑止し、旧C# checksumとimplicit-implementation referenceを保持し、source evidenceをunknownにして、failure phaseを`csharp_prepass`だけに限定します。fresh rebuild fixtureでもC# prepass symbol artifactを取り込まず、static-interface evidenceとimplicit referenceをauthoritativeに保ちます。
   plain-interface purge fixtureではsorted file-ID preflightを正確かつcancellation-awareに保ち、prepared cacheへ残さないSQLite parameter 500件以内のbatchに固定します。transition-path preflight の coverage は実memberを2つ目のpath batchだけに置き、path-first の `files(path)` と `symbols(file_id, kind)` のindex plan、keyword境界・大小文字decoyの拒否、cancellationによる中断、dynamic commandがprepared cacheへ入らないことを要求します。one-sided の同一stem/checksum rename と positive/unknown evidence の `--changed-between` 範囲外 fixture はimmutable cleanup planがreference再生成前にstale contract rowを消し、無関係なmissing non-C# rowを全掃除しないことを要求します。`Run_UpdateFiles_ChangedExistingRetainedTargetPreplansMatchingCsharpAlias` は既にindex済みでstat-changedのretained targetもchecksum一致のC# aliasをworkspace構築前にplanし、未変更targetは追加content readなしで永続checksumを再利用することを固定します。binary/oversized skip-record drift fixtureは`BuildSkippedFileRecord`後にmutationし、retry前にnested cleanup/upsert transactionとbatch markerの両方がrollbackされることを要求します。`Run_UpdateMode_WithChangedBetween_PurgesMissingIndexedPathOutsideDiff_4056` は authoritative false evidence のときだけ従来の全言語 reconciliation を維持することを別途固定します。`Run_UpdateMode_WithChangedBetween_CleanupPathReappearingAfterScanIsDeferredUntilRetry` はdiscovery中に削除済みcontractを復元し、`Run_UpdateCommits_ExactCleanupPathReappearingAfterSnapshotBarrierPreservesPriorRow` はfinal snapshot barrier後にexactなGit削除targetを復元します。どちらも旧rowとimplicit referenceを保持するpartial resultを要求します。expanded discovery のfatal errorとprepass後のchange/delete fixtureも旧C# rowとimplicit referenceを保持し、source evidenceをunknownにして、後続のclean retryで収束させます。C# mutation延期中も無関係なPython/JavaScript cleanupと未変更scoped targetは進行します。parallel symbol-cap fixtureではprepass後に初めて見つかったcontractをsource evidence unknownとして、後続のcomplete repairを強制します。
 - case-folded cleanup coverageではSQLite `NOCASE` とmanaged foldingを候補filterだけに使い、leaf case・ancestor case・Unicode foldが一致してもfile identityが異なるpathは両方のexact rowを保持し、真のcase-only aliasだけがchecksum readなしで旧spellingを削除できることを固定します。無関係なhardlinkをaliasとするにはpathとidentityの両方が同じretained case-fold bucketに一致しなければならず、`ScopedFileCleanupReappearance_FoldBucketsDoNotCrossMatchTargetIdentities` は別target由来のpath一致とidentity一致の合成を防ぎます。Git name-status coverageはold/new pathにtabと改行を含む実NUL区切りrenameを使い、commit/range helperの両方がunquotedな正確な文字列を返すことを検証します。
 - project-marker budget の integration coverage は directory budget を最小境界に override し、child を 1 件だけ列挙します。warning 伝播の検証だけのために本番の 8,192-directory cap を実体化しないでください。shared discovery の coverage は1回の directory enumeration から C#、VB、F#、MSBuild の全 fingerprint が得られることを検証し、family-scope coverage は scan 後の ancestor filesystem probe が0回、fingerprint budget 枯渇後も complete な scope snapshot を利用可能、不完全 discovery では live fallback を維持することを固定してください。
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.CSharpWorkspace.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.CSharpWorkspace.cs
new file mode 100644
index 000000000..c1514edb1
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.CSharpWorkspace.cs
@@ -0,0 +1,344 @@
+using CodeIndex.Database;
+using CodeIndex.Indexer;
+using CodeIndex.Models;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private sealed class McpIndexCSharpFailureCollector(
+        string projectPath,
+        List<IndexFileFailure> failures)
+    {
+        private readonly HashSet<string> _reported = new(StringComparer.Ordinal);
+
+        internal void Record(string path, string stage, Exception exception)
+        {
+            path = string.IsNullOrWhiteSpace(path) ? "<csharp_workspace>" : path;
+            if (!_reported.Add($"{stage}\n{path}"))
+                return;
+
+            var platformRelativePath = FileIndexer.NormalizeRelativePathForCurrentPlatform(path);
+            failures.Add(BuildIndexFileFailure(
+                projectPath,
+                Path.Combine(projectPath, platformRelativePath),
+                exception,
+                stage));
+        }
+
+        internal void RecordIncompletePrepass(IReadOnlyList<string> paths)
+        {
+            if (paths.Count == 0)
+            {
+                Record(
+                    "<csharp_workspace>",
+                    "csharp_prepass",
+                    new IOException(
+                        "C# static-interface workspace preflight could not read a source file."));
+                return;
+            }
+
+            foreach (var path in paths.Take(50))
+            {
+                Record(
+                    path,
+                    "csharp_prepass",
+                    new IOException(
+                        "C# static-interface workspace preflight could not read this source file."));
+            }
+        }
+    }
+
+    private sealed record McpIndexCSharpWorkspaceContext(
+        string ProjectPath,
+        McpPathBoundary.IndexRootAuthorization AuthorizedRoot,
+        List<CSharpStaticInterfacePrepass.FileTarget> Targets,
+        ReusableIndexedFileStatsSnapshot? ReusableIndexedFileStats,
+        McpIndexReadableByteTracker ReadableBytes,
+        McpIndexCSharpFailureCollector Failures,
+        CancellationToken CancellationToken);
+
+    private sealed class McpIndexCSharpPreflightCache
+    {
+        internal Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>? FileSnapshots
+        { get; set; }
+        internal Dictionary<string, IndexedFileStatReuseResult?>? StatReuse { get; set; }
+    }
+
+    private sealed class McpIndexCSharpTransitions
+    {
+        internal bool DeferMutations { get; set; }
+        internal bool PreservePriorPositiveSourceNoOp { get; set; }
+        internal bool SourceEvidenceForStamp { get; set; }
+        internal bool SourceEvidenceComplete { get; set; }
+        internal bool ForceFullRefreshFromInvalidatedNoOp { get; set; }
+        internal bool AllPrepassTargetsReusable { get; set; }
+    }
+
+    private sealed class McpIndexCSharpWorkspaceState(
+        McpIndexCSharpWorkspaceContext context)
+    {
+        private readonly McpIndexCSharpPreflightCache _preflight = new();
+        private readonly McpIndexCSharpTransitions _transitions = new();
+
+        internal CSharpStaticInterfaceWorkspaceSymbols Workspace { get; set; } =
+            new([], false);
+        internal CSharpPrepassSymbolArtifactCache? PrepassArtifacts { get; set; }
+        internal IReadOnlyList<string> IncompletePrepassPaths { get; set; } = [];
+        internal bool DeferMutations
+        {
+            get => _transitions.DeferMutations;
+            set => _transitions.DeferMutations = value;
+        }
+        internal bool PreservePriorPositiveSourceNoOp
+        {
+            get => _transitions.PreservePriorPositiveSourceNoOp;
+            set => _transitions.PreservePriorPositiveSourceNoOp = value;
+        }
+        internal bool SourceEvidenceForStamp
+        {
+            get => _transitions.SourceEvidenceForStamp;
+            set => _transitions.SourceEvidenceForStamp = value;
+        }
+        internal bool SourceEvidenceComplete
+        {
+            get => _transitions.SourceEvidenceComplete;
+            set => _transitions.SourceEvidenceComplete = value;
+        }
+        internal bool ForceFullRefreshFromInvalidatedNoOp
+        {
+            get => _transitions.ForceFullRefreshFromInvalidatedNoOp;
+            set => _transitions.ForceFullRefreshFromInvalidatedNoOp = value;
+        }
+        internal bool AllPrepassTargetsReusable
+        {
+            get => _transitions.AllPrepassTargetsReusable;
+            set => _transitions.AllPrepassTargetsReusable = value;
+        }
+        internal bool HasFileSnapshots => _preflight.FileSnapshots != null;
+
+        internal Dictionary<string, IndexedFileStatReuseResult?> EnsurePrepassStatReuse() =>
+            _preflight.StatReuse ??= new Dictionary<string, IndexedFileStatReuseResult?>(
+                context.Targets.Count,
+                StringComparer.Ordinal);
+
+        internal CSharpStaticInterfaceWorkspaceSymbols BuildStableWorkspace(
+            Func<CSharpStaticInterfaceWorkspaceSymbols> buildWorkspace)
+        {
+            _preflight.FileSnapshots = null;
+            Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot> snapshots = [];
+            var captured = CSharpStaticInterfacePrepass.TryCaptureFileStatSnapshots(
+                context.Targets,
+                out snapshots,
+                out var failedFilePath,
+                context.CancellationToken,
+                target => context.AuthorizedRoot.EnsureAuthorizedEntry(target.FilePath));
+            if (!captured)
+            {
+                return new CSharpStaticInterfaceWorkspaceSymbols(
+                    [],
+                    HasStaticInterfaceContracts: true,
+                    SourceContractEvidenceComplete: false,
+                    IncompleteSourcePaths: [FormatSnapshotPath(failedFilePath)]);
+            }
+
+            McpIndexCSharpPrepassForTesting?.Invoke();
+            var workspace = buildWorkspace();
+            var stable = CSharpStaticInterfacePrepass.TryValidateFileStatSnapshots(
+                context.Targets,
+                snapshots,
+                out var changedFilePath,
+                context.CancellationToken,
+                target => context.AuthorizedRoot.EnsureAuthorizedEntry(target.FilePath));
+            if (!stable || !workspace.SourceContractEvidenceComplete)
+            {
+                var incompletePath = workspace.IncompleteSourcePaths?.FirstOrDefault()
+                    ?? changedFilePath
+                    ?? "<csharp_workspace>";
+                return workspace with
+                {
+                    HasStaticInterfaceContracts = true,
+                    SourceContractEvidenceComplete = false,
+                    IncompleteSourcePaths = [FormatSnapshotPath(incompletePath)],
+                };
+            }
+
+            _preflight.FileSnapshots = snapshots;
+            return workspace;
+        }
+
+        internal string FormatSnapshotPath(string? path)
+        {
+            if (string.IsNullOrWhiteSpace(path) || path == "<csharp_workspace>")
+                return "<csharp_workspace>";
+            if (!Path.IsPathRooted(path))
+                return FileIndexer.NormalizePathSeparators(path);
+            try
+            {
+                var relative = FileIndexer.NormalizePathSeparators(
+                    FileIndexer.GetRelativePathFromDirectory(context.ProjectPath, path));
+                return relative == "."
+                    || relative.StartsWith("../", StringComparison.Ordinal)
+                    || Path.IsPathRooted(relative)
+                        ? path
+                        : relative;
+            }
+            catch (Exception ex) when (ex is IOException or UnauthorizedAccessException
+                or NotSupportedException or ArgumentException)
+            {
+                return path;
+            }
+        }
+
+        internal IndexedFileStatReuseResult? GetStatMatchedFile(
+            in CSharpStaticInterfacePrepass.FileTarget target)
+        {
+            return target.Language == "csharp"
+                && _preflight.StatReuse != null
+                && _preflight.StatReuse.TryGetValue(target.IndexPath, out var cached)
+                    ? cached
+                    : IndexedFileStatReuse.TryGetReusableUnchangedFile(
+                        context.ReusableIndexedFileStats!,
+                        target.FilePath,
+                        target.IndexPath,
+                        target.Language,
+                        target.GeneratedExtractionSuppressed == true);
+        }
+
+        internal bool LoadedSnapshotMatches(
+            in CSharpStaticInterfacePrepass.FileTarget target,
+            FileRecord record,
+            DbWriter writer)
+        {
+            if (target.Language != "csharp" || _preflight.FileSnapshots == null)
+                return true;
+
+            if (CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
+                    target.FilePath,
+                    target.IndexPath,
+                    target.DisplayRelativePath,
+                    record.Size,
+                    record.Modified,
+                    _preflight.FileSnapshots,
+                    out var changedPath,
+                    context.CancellationToken,
+                    context.AuthorizedRoot.EnsureAuthorizedEntry))
+            {
+                return true;
+            }
+
+            DeferForLoadedSnapshotDrift(
+                FormatSnapshotPath(changedPath ?? target.DisplayRelativePath),
+                writer);
+            return false;
+        }
+
+        internal void DeferForLoadedSnapshotDrift(string path, DbWriter writer)
+        {
+            ClearArtifacts();
+            DeferMutations = true;
+            PreservePriorPositiveSourceNoOp = false;
+            SourceEvidenceForStamp = false;
+            SourceEvidenceComplete = false;
+            IncompletePrepassPaths = [path];
+            _preflight.FileSnapshots = null;
+            Workspace = new CSharpStaticInterfaceWorkspaceSymbols(
+                [],
+                HasStaticInterfaceContracts: true,
+                SourceContractEvidenceComplete: false,
+                IncompleteSourcePaths: IncompletePrepassPaths);
+            writer.SetCSharpStaticInterfaceSourceEvidence(null);
+            context.Failures.Record(
+                path,
+                "csharp_workspace_validation",
+                new IOException(
+                    "A C# source changed after workspace preflight; rerun indexing to refresh the complete C# graph."));
+        }
+
+        internal void DeferForStatRevalidation(
+            in CSharpStaticInterfacePrepass.FileTarget target,
+            DbWriter writer)
+        {
+            PreservePriorPositiveSourceNoOp = false;
+            DeferMutations = true;
+            SourceEvidenceForStamp = false;
+            SourceEvidenceComplete = false;
+            writer.SetCSharpStaticInterfaceSourceEvidence(null);
+            context.Failures.Record(
+                target.IndexPath,
+                "csharp_stat_revalidation",
+                new IOException(
+                    "A C# source changed after final workspace preflight; rerun indexing to refresh the complete C# graph."));
+            try
+            {
+                var info = new FileInfo(target.FilePath);
+                if (info.Exists && info.Length >= 0)
+                    context.ReadableBytes.Remember(target.FilePath, info.Length);
+            }
+            catch (Exception ex) when (ex is IOException or UnauthorizedAccessException
+                or NotSupportedException or ArgumentException)
+            {
+            }
+        }
+
+        internal bool TryValidateFileSnapshots(out string? changedFilePath)
+        {
+            changedFilePath = null;
+            return _preflight.FileSnapshots == null
+                || CSharpStaticInterfacePrepass.TryValidateFileStatSnapshots(
+                    context.Targets,
+                    _preflight.FileSnapshots,
+                    out changedFilePath,
+                    context.CancellationToken,
+                    target => context.AuthorizedRoot.EnsureAuthorizedEntry(target.FilePath));
+        }
+
+        internal void RecordIncompletePrepass() =>
+            context.Failures.RecordIncompletePrepass(IncompletePrepassPaths);
+
+        internal void ClearArtifacts()
+        {
+            PrepassArtifacts?.Clear();
+            PrepassArtifacts = null;
+        }
+
+        internal void DeferForIncompletePrepass()
+        {
+            ClearArtifacts();
+            IncompletePrepassPaths = Workspace.IncompleteSourcePaths ?? [];
+            DeferMutations = true;
+            Workspace = new CSharpStaticInterfaceWorkspaceSymbols(
+                [],
+                false,
+                SourceContractEvidenceComplete: false,
+                IncompleteSourcePaths: IncompletePrepassPaths);
+        }
+
+        internal void DeferForBeforeWriteStatDrift(string? changedFilePath)
+        {
+            ClearArtifacts();
+            var driftPath = FormatSnapshotPath(changedFilePath);
+            IncompletePrepassPaths = [driftPath];
+            DeferMutations = true;
+            PreservePriorPositiveSourceNoOp = false;
+            SourceEvidenceForStamp = false;
+            SourceEvidenceComplete = false;
+            _preflight.FileSnapshots = null;
+            Workspace = new CSharpStaticInterfaceWorkspaceSymbols(
+                [],
+                HasStaticInterfaceContracts: true,
+                SourceContractEvidenceComplete: false,
+                IncompleteSourcePaths: IncompletePrepassPaths);
+            context.Failures.RecordIncompletePrepass(IncompletePrepassPaths);
+        }
+
+        internal void RecordScanInputDrift(string changedPath)
+        {
+            context.Failures.Record(
+                FormatSnapshotPath(changedPath),
+                "csharp_workspace_validation",
+                new IOException(
+                    "Directory entries or scan configuration changed after source discovery; rerun indexing from a stable workspace snapshot."));
+        }
+    }
+}
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
index b4da938bf..7d538b486 100644
--- a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.Execution.cs
@@ -341,7 +341,7 @@ static string FormatDiagnosticPath(string projectRoot, string path)
         var scanResult = scanWithDirectorySnapshots.ScanResult;
         var scanInputSnapshot = scanWithDirectorySnapshots.InputSnapshot;
         var scanHadErrors = scanResult.HadErrors;
-        var deferCSharpMutationsForIncompleteScan = !startedWithNoIndexedFiles
+        var initialDeferCSharpMutations = !startedWithNoIndexedFiles
             && scanHadErrors
             && indexSnapshot.CSharpStaticInterfaceSourceEvidence != false;
         if (memorySamples != null)
@@ -361,7 +361,7 @@ static string FormatDiagnosticPath(string projectRoot, string path)
             targets,
             initialStaleFilePurgePlan,
             startedWithNoIndexedFiles,
-            deferCSharpMutationsForIncompleteScan,
+            initialDeferCSharpMutations,
             indexSnapshot.CSharpStaticInterfaceSourceEvidence,
             priorFilterRetainedCSharpContractMembers,
             requestToken);
@@ -408,12 +408,34 @@ void ObservePersistedCSharpPath(string indexPath)
                 maxFileSizeBytes:
                     maxFileBytes ?? FileIndexer.DefaultMaxFileSizeBytes)
             : null;
-        Dictionary<string, IndexedFileStatReuseResult?>? csharpPrepassStatReuse = null;
         var priorPositiveCSharpSourceNoOpCandidate = false;
-        var allCSharpPrepassTargetsReusable = false;
         bool IsGeneratedExtractionSuppressed(CSharpStaticInterfacePrepass.FileTarget target)
             => target.GeneratedExtractionSuppressed == true;
 
+        var failures = new List<IndexFileFailure>();
+        if (scanHadErrors)
+        {
+            foreach (var error in scanResult.Errors)
+            {
+                if (error.IsFatal)
+                    failures.Add(BuildScanFailure(error));
+            }
+        }
+        var csharpFailures = new McpIndexCSharpFailureCollector(projectPath, failures);
+        var csharpState = new McpIndexCSharpWorkspaceState(
+            new McpIndexCSharpWorkspaceContext(
+                projectPath,
+                authorizedRoot,
+                csharpPrepassTargets,
+                reusableIndexedFileStats,
+                readableBytes,
+                csharpFailures,
+                requestToken))
+        {
+            DeferMutations = initialDeferCSharpMutations,
+            PrepassArtifacts = csharpPrepassSymbolArtifacts,
+        };
+
         bool CanReuseCSharpPrepassTargetWithoutRead(CSharpStaticInterfacePrepass.FileTarget target)
         {
             if (rebuild
@@ -438,87 +460,21 @@ bool CanReuseCSharpPrepassTargetWithoutRead(CSharpStaticInterfacePrepass.FileTar
                 IsGeneratedExtractionSuppressed(target));
             if (existingFile == null)
             {
-                allCSharpPrepassTargetsReusable = false;
-                (csharpPrepassStatReuse ??= new Dictionary<string, IndexedFileStatReuseResult?>(
-                    csharpPrepassTargets.Count,
-                    StringComparer.Ordinal))[target.IndexPath] = null;
+                csharpState.AllPrepassTargetsReusable = false;
+                csharpState.EnsurePrepassStatReuse()[target.IndexPath] = null;
                 return false;
             }
 
-            (csharpPrepassStatReuse ??= new Dictionary<string, IndexedFileStatReuseResult?>(
-                csharpPrepassTargets.Count,
-                StringComparer.Ordinal))[target.IndexPath] = existingFile.Value;
+            csharpState.EnsurePrepassStatReuse()[target.IndexPath] = existingFile.Value;
             return true;
         }
 
-        Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>? csharpWorkspaceFileSnapshots = null;
-
-        string FormatCSharpWorkspaceSnapshotPath(string? path)
-        {
-            if (string.IsNullOrWhiteSpace(path) || path == "<csharp_workspace>")
-                return "<csharp_workspace>";
-            if (!Path.IsPathRooted(path))
-                return FileIndexer.NormalizePathSeparators(path);
-            return FormatDiagnosticPath(projectPath, path);
-        }
-
-        CSharpStaticInterfaceWorkspaceSymbols BuildStableCSharpWorkspace(
-            Func<CSharpStaticInterfaceWorkspaceSymbols> buildWorkspace)
-        {
-            csharpWorkspaceFileSnapshots = null;
-            Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot> fileSnapshots = [];
-            string? failedFilePath = null;
-            var capturedFiles = CSharpStaticInterfacePrepass.TryCaptureFileStatSnapshots(
-                csharpPrepassTargets,
-                out fileSnapshots,
-                out failedFilePath,
-                requestToken,
-                target => authorizedRoot.EnsureAuthorizedEntry(target.FilePath));
-            if (!capturedFiles)
-            {
-                return new CSharpStaticInterfaceWorkspaceSymbols(
-                    [],
-                    HasStaticInterfaceContracts: true,
-                    SourceContractEvidenceComplete: false,
-                    IncompleteSourcePaths:
-                    [
-                        FormatCSharpWorkspaceSnapshotPath(failedFilePath)
-                    ]);
-            }
-
-            McpIndexCSharpPrepassForTesting?.Invoke();
-            var workspace = buildWorkspace();
-            var stableFiles = CSharpStaticInterfacePrepass.TryValidateFileStatSnapshots(
-                csharpPrepassTargets,
-                fileSnapshots,
-                out var changedFilePath,
-                requestToken,
-                target => authorizedRoot.EnsureAuthorizedEntry(target.FilePath));
-            if (!stableFiles || !workspace.SourceContractEvidenceComplete)
-            {
-                var incompletePath = workspace.IncompleteSourcePaths?.FirstOrDefault()
-                    ?? changedFilePath
-                    ?? "<csharp_workspace>";
-                return workspace with
-                {
-                    HasStaticInterfaceContracts = true,
-                    SourceContractEvidenceComplete = false,
-                    IncompleteSourcePaths = [FormatCSharpWorkspaceSnapshotPath(incompletePath)],
-                };
-            }
-
-            csharpWorkspaceFileSnapshots = fileSnapshots;
-            return workspace;
-        }
-
         priorPositiveCSharpSourceNoOpCandidate = csharpPositiveNoOpPolicyCandidate
             && !hasCSharpLanguageTransitions;
         if (priorPositiveCSharpSourceNoOpCandidate)
         {
-            allCSharpPrepassTargetsReusable = true;
-            csharpPrepassStatReuse = new Dictionary<string, IndexedFileStatReuseResult?>(
-                csharpPrepassTargets.Count,
-                StringComparer.Ordinal);
+            csharpState.AllPrepassTargetsReusable = true;
+            var prepassStatReuse = csharpState.EnsurePrepassStatReuse();
             foreach (var target in csharpPrepassTargets)
             {
                 requestToken.ThrowIfCancellationRequested();
@@ -529,29 +485,26 @@ CSharpStaticInterfaceWorkspaceSymbols BuildStableCSharpWorkspace(
                     target.IndexPath,
                     target.Language,
                     IsGeneratedExtractionSuppressed(target));
-                csharpPrepassStatReuse[target.IndexPath] = existingFile;
-                allCSharpPrepassTargetsReusable &= existingFile != null;
+                prepassStatReuse[target.IndexPath] = existingFile;
+                csharpState.AllPrepassTargetsReusable &= existingFile != null;
             }
         }
 
-        CSharpStaticInterfaceWorkspaceSymbols csharpWorkspace;
-        IReadOnlyList<string> incompleteCSharpPrepassPaths = [];
-        var forceFullCSharpRefreshFromInvalidatedNoOp = false;
-        if (csharpPrepassTargets.Count == 0 || deferCSharpMutationsForIncompleteScan)
+        if (csharpPrepassTargets.Count == 0 || csharpState.DeferMutations)
         {
-            csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols([], false);
+            csharpState.Workspace = new CSharpStaticInterfaceWorkspaceSymbols([], false);
         }
         else if (priorPositiveCSharpSourceNoOpCandidate
-                 && allCSharpPrepassTargetsReusable)
+                 && csharpState.AllPrepassTargetsReusable)
         {
             // Existing graph rows are already complete and every C# stat matched. Avoid
             // loading persisted contract symbols or constructing a lookup that no file will use.
             // 全C# stat一致のpositive no-opではDB symbol/lookup loadを完全に省略する。
-            csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols([], false);
+            csharpState.Workspace = new CSharpStaticInterfaceWorkspaceSymbols([], false);
         }
         else
         {
-            csharpWorkspace = BuildStableCSharpWorkspace(() =>
+            csharpState.Workspace = csharpState.BuildStableWorkspace(() =>
                 CSharpStaticInterfacePrepass.BuildWorkspaceSymbols(
                     writer,
                     indexer,
@@ -568,144 +521,45 @@ CSharpStaticInterfaceWorkspaceSymbols BuildStableCSharpWorkspace(
                         discoveryPlan.ScanAuthority.IsExistingCSharpSymbolPathNowNonCSharp,
                     patternConfigsAlreadyLoaded: true,
                     cancellationToken: requestToken,
-                    symbolArtifactCache: csharpPrepassSymbolArtifacts));
-            forceFullCSharpRefreshFromInvalidatedNoOp =
+                    symbolArtifactCache: csharpState.PrepassArtifacts));
+            csharpState.ForceFullRefreshFromInvalidatedNoOp =
                 indexSnapshot.CSharpStaticInterfaceSourceEvidence == true
-                || csharpWorkspace.HasStaticInterfaceContracts
-                || csharpWorkspace.RequiresMemberReadReferenceRefresh;
+                || csharpState.Workspace.HasStaticInterfaceContracts
+                || csharpState.Workspace.RequiresMemberReadReferenceRefresh;
         }
-        if (!csharpWorkspace.SourceContractEvidenceComplete)
+        if (!csharpState.Workspace.SourceContractEvidenceComplete)
         {
-            csharpPrepassSymbolArtifacts?.Clear();
-            csharpPrepassSymbolArtifacts = null;
-            incompleteCSharpPrepassPaths = csharpWorkspace.IncompleteSourcePaths ?? [];
-            deferCSharpMutationsForIncompleteScan = true;
+            csharpState.DeferForIncompletePrepass();
             staleFilePurgePlan = FilePurgePlan.Empty;
             purged = 0;
             hadCSharpStaticInterfaceContractsBeforePurge = false;
-            csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
-                [],
-                false,
-                SourceContractEvidenceComplete: false,
-                IncompleteSourcePaths: incompleteCSharpPrepassPaths);
         }
-        var preservePriorPositiveCSharpSourceNoOp = priorPositiveCSharpSourceNoOpCandidate
-            && allCSharpPrepassTargetsReusable
-            && !deferCSharpMutationsForIncompleteScan;
-        var csharpSourceEvidenceForStamp = preservePriorPositiveCSharpSourceNoOp
+        csharpState.PreservePriorPositiveSourceNoOp = priorPositiveCSharpSourceNoOpCandidate
+            && csharpState.AllPrepassTargetsReusable
+            && !csharpState.DeferMutations;
+        csharpState.SourceEvidenceForStamp = csharpState.PreservePriorPositiveSourceNoOp
             ? indexSnapshot.CSharpStaticInterfaceSourceEvidence == true
-            : csharpWorkspace.HasSourceStaticInterfaceContracts;
-        var csharpSourceEvidenceComplete = preservePriorPositiveCSharpSourceNoOp
-            || csharpWorkspace.SourceContractEvidenceComplete;
-        if (preservePriorPositiveCSharpSourceNoOp)
-            csharpWorkspace = csharpWorkspace with { HasStaticInterfaceContracts = false };
-        if (!deferCSharpMutationsForIncompleteScan
-            && !preservePriorPositiveCSharpSourceNoOp
-            && (forceFullCSharpRefreshFromInvalidatedNoOp
+            : csharpState.Workspace.HasSourceStaticInterfaceContracts;
+        csharpState.SourceEvidenceComplete = csharpState.PreservePriorPositiveSourceNoOp
+            || csharpState.Workspace.SourceContractEvidenceComplete;
+        if (csharpState.PreservePriorPositiveSourceNoOp)
+            csharpState.Workspace = csharpState.Workspace with { HasStaticInterfaceContracts = false };
+        if (!csharpState.DeferMutations
+            && !csharpState.PreservePriorPositiveSourceNoOp
+            && (csharpState.ForceFullRefreshFromInvalidatedNoOp
                 || requiresConservativeCSharpSourceRefresh
-                || !csharpSourceEvidenceComplete
+                || !csharpState.SourceEvidenceComplete
                 || (purged > 0 && hadCSharpStaticInterfaceContractsBeforePurge)))
         {
-            csharpWorkspace = csharpWorkspace with { HasStaticInterfaceContracts = true };
-        }
-        var failures = new List<IndexFileFailure>();
-        if (scanHadErrors)
-        {
-            foreach (var error in scanResult.Errors)
-            {
-                if (error.IsFatal)
-                    failures.Add(BuildScanFailure(error));
-            }
+            csharpState.Workspace = csharpState.Workspace with { HasStaticInterfaceContracts = true };
         }
         int processed = 0, skipped = 0, errors = failures.Count;
-        var reportedCSharpWorkspaceFailures = new HashSet<string>(StringComparer.Ordinal);
 
-        void RecordCSharpWorkspaceFailure(string path, string stage, Exception exception)
+        if (!csharpState.SourceEvidenceComplete)
         {
-            path = string.IsNullOrWhiteSpace(path) ? "<csharp_workspace>" : path;
-            if (!reportedCSharpWorkspaceFailures.Add($"{stage}\n{path}"))
-                return;
-
-            errors++;
-            var platformRelativePath = FileIndexer.NormalizeRelativePathForCurrentPlatform(path);
-            failures.Add(BuildIndexFileFailure(
-                projectPath,
-                Path.Combine(projectPath, platformRelativePath),
-                exception,
-                stage));
-        }
-
-        void RecordIncompleteCSharpPrepassFailures(IReadOnlyList<string> paths)
-        {
-            if (paths.Count == 0)
-            {
-                RecordCSharpWorkspaceFailure(
-                    "<csharp_workspace>",
-                    "csharp_prepass",
-                    new IOException("C# static-interface workspace preflight could not read a source file."));
-                return;
-            }
-
-            foreach (var path in paths.Take(50))
-            {
-                RecordCSharpWorkspaceFailure(
-                    path,
-                    "csharp_prepass",
-                    new IOException("C# static-interface workspace preflight could not read this source file."));
-            }
+            csharpState.RecordIncompletePrepass();
+            errors = failures.Count;
         }
-
-        void DeferCSharpMutationsForLoadedSnapshotDrift(string path)
-        {
-            csharpPrepassSymbolArtifacts?.Clear();
-            csharpPrepassSymbolArtifacts = null;
-            deferCSharpMutationsForIncompleteScan = true;
-            preservePriorPositiveCSharpSourceNoOp = false;
-            csharpSourceEvidenceForStamp = false;
-            csharpSourceEvidenceComplete = false;
-            incompleteCSharpPrepassPaths = [path];
-            csharpWorkspaceFileSnapshots = null;
-            csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
-                [],
-                HasStaticInterfaceContracts: true,
-                SourceContractEvidenceComplete: false,
-                IncompleteSourcePaths: incompleteCSharpPrepassPaths);
-            writer.SetCSharpStaticInterfaceSourceEvidence(null);
-            RecordCSharpWorkspaceFailure(
-                path,
-                "csharp_workspace_validation",
-                new IOException(
-                    "A C# source changed after workspace preflight; rerun indexing to refresh the complete C# graph."));
-        }
-
-        bool LoadedCSharpWorkspaceSnapshotMatches(
-            in CSharpStaticInterfacePrepass.FileTarget target,
-            FileRecord record)
-        {
-            if (target.Language != "csharp" || csharpWorkspaceFileSnapshots == null)
-                return true;
-
-            if (CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
-                    target.FilePath,
-                    target.IndexPath,
-                    target.DisplayRelativePath,
-                    record.Size,
-                    record.Modified,
-                    csharpWorkspaceFileSnapshots,
-                    out var changedPath,
-                    requestToken,
-                    authorizedRoot.EnsureAuthorizedEntry))
-            {
-                return true;
-            }
-
-            DeferCSharpMutationsForLoadedSnapshotDrift(
-                FormatCSharpWorkspaceSnapshotPath(changedPath ?? target.DisplayRelativePath));
-            return false;
-        }
-
-        if (!csharpSourceEvidenceComplete)
-            RecordIncompleteCSharpPrepassFailures(incompleteCSharpPrepassPaths);
         HashSet<string>? reusedHotspotFamilyLanguages = null;
         var indexedSymbolExtractorLanguages = new HashSet<string>(languageCounts.Count, StringComparer.Ordinal);
         var symbolsDroppedByKindFilter = 0;
@@ -724,23 +578,14 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
                 && symbolKindFilterMatchesPrior
                 && (target.Language != "csharp" || csharpIndexedProjectRootCompatible)
                 && (target.Language != "csharp" || csharpSymbolNameContractMatchesCurrent)
-                && (target.Language != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
+                && (target.Language != "csharp" || !csharpState.Workspace.HasStaticInterfaceContracts)
                 && (target.Language != "sql" || sqlGraphContractMatchesCurrent)
                 && (target.Language is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent)
                 && AllowReuseWithCurrentHotspotFamilyTrust(target.Language, hotspotFamilyTrustMatchesCurrent);
             if (!allowStatReuse)
                 return null;
 
-            return target.Language == "csharp"
-                && csharpPrepassStatReuse != null
-                && csharpPrepassStatReuse.TryGetValue(target.IndexPath, out var cachedCSharpPrepassReuse)
-                    ? cachedCSharpPrepassReuse
-                    : IndexedFileStatReuse.TryGetReusableUnchangedFile(
-                        reusableIndexedFileStats!,
-                        target.FilePath,
-                        target.IndexPath,
-                        target.Language,
-                        target.GeneratedExtractionSuppressed == true);
+            return csharpState.GetStatMatchedFile(in target);
         }
 
         var ftsPreflight = BuildMcpIndexFtsPreflight(
@@ -757,7 +602,7 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
         var useFtsBulkLoad = ftsPreflight.UseBulkLoad;
 
         var reuseFinalCSharpStatAtActualSkip = false;
-        if (preservePriorPositiveCSharpSourceNoOp
+        if (csharpState.PreservePriorPositiveSourceNoOp
             && ftsPreflight.EveryTargetMatched)
         {
             // A pure no-op performs its second and final C# stat pass at the readiness
@@ -766,7 +611,7 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
             reuseFinalCSharpStatAtActualSkip = true;
         }
 
-        if (preservePriorPositiveCSharpSourceNoOp
+        if (csharpState.PreservePriorPositiveSourceNoOp
             && !ftsPreflight.EveryTargetMatched)
         {
             // Re-stat directly after the potentially long whole-workspace dirty-byte pass.
@@ -794,7 +639,7 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
 
             if (invalidatedCSharpTargetIndexes.Count > 0)
             {
-                csharpWorkspace = BuildStableCSharpWorkspace(() =>
+                csharpState.Workspace = csharpState.BuildStableWorkspace(() =>
                     CSharpStaticInterfacePrepass.BuildWorkspaceSymbols(
                         writer,
                         indexer,
@@ -808,36 +653,36 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
                             discoveryPlan.ScanAuthority.IsExistingCSharpSymbolPathNowNonCSharp,
                         patternConfigsAlreadyLoaded: true,
                         cancellationToken: requestToken));
-                preservePriorPositiveCSharpSourceNoOp = false;
-                if (!csharpWorkspace.SourceContractEvidenceComplete)
+                csharpState.PreservePriorPositiveSourceNoOp = false;
+                if (!csharpState.Workspace.SourceContractEvidenceComplete)
                 {
-                    incompleteCSharpPrepassPaths = csharpWorkspace.IncompleteSourcePaths ?? [];
-                    deferCSharpMutationsForIncompleteScan = true;
+                    csharpState.IncompletePrepassPaths = csharpState.Workspace.IncompleteSourcePaths ?? [];
+                    csharpState.DeferMutations = true;
                     staleFilePurgePlan = FilePurgePlan.Empty;
                     purged = 0;
                     hadCSharpStaticInterfaceContractsBeforePurge = false;
-                    csharpSourceEvidenceForStamp = false;
-                    csharpSourceEvidenceComplete = false;
-                    csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
+                    csharpState.SourceEvidenceForStamp = false;
+                    csharpState.SourceEvidenceComplete = false;
+                    csharpState.Workspace = new CSharpStaticInterfaceWorkspaceSymbols(
                         [],
                         false,
                         SourceContractEvidenceComplete: false,
-                        IncompleteSourcePaths: incompleteCSharpPrepassPaths);
-                    RecordIncompleteCSharpPrepassFailures(incompleteCSharpPrepassPaths);
+                        IncompleteSourcePaths: csharpState.IncompletePrepassPaths);
+                    csharpState.RecordIncompletePrepass();
                     useFtsBulkLoad = false;
                 }
                 else
                 {
                     var requiresFullCSharpRefresh =
                         indexSnapshot.CSharpStaticInterfaceSourceEvidence == true
-                        || csharpWorkspace.HasStaticInterfaceContracts;
-                    forceFullCSharpRefreshFromInvalidatedNoOp = requiresFullCSharpRefresh;
-                    csharpSourceEvidenceForStamp = csharpWorkspace.HasSourceStaticInterfaceContracts;
-                    csharpSourceEvidenceComplete = true;
+                        || csharpState.Workspace.HasStaticInterfaceContracts;
+                    csharpState.ForceFullRefreshFromInvalidatedNoOp = requiresFullCSharpRefresh;
+                    csharpState.SourceEvidenceForStamp = csharpState.Workspace.HasSourceStaticInterfaceContracts;
+                    csharpState.SourceEvidenceComplete = true;
                     useFtsBulkLoad = false;
                     if (requiresFullCSharpRefresh)
                     {
-                        csharpWorkspace = csharpWorkspace with { HasStaticInterfaceContracts = true };
+                        csharpState.Workspace = csharpState.Workspace with { HasStaticInterfaceContracts = true };
                         invalidatedCSharpTargetIndexes.Clear();
                         for (var targetIndex = 0; targetIndex < fileTargets.Length; targetIndex++)
                         {
@@ -852,164 +697,50 @@ bool LoadedCSharpWorkspaceSnapshotMatches(
             }
         }
 
-        async Task<JsonNode> ReturnBeforeWriteSnapshotFailureAsync(string changedPath)
-        {
-            var formattedPath = FormatCSharpWorkspaceSnapshotPath(changedPath);
-            RecordCSharpWorkspaceFailure(
-                formattedPath,
-                "csharp_workspace_validation",
-                new IOException(
-                    "Directory entries or scan configuration changed after source discovery; rerun indexing from a stable workspace snapshot."));
-
-            var (totalFiles, totalChunks, totalSymbols, totalReferences) = writer.GetCounts();
-            await EmitProgressNotificationAsync(
-                progressToken,
-                0,
-                files.Count,
-                "Indexing stopped before index-data mutation because scan inputs changed.").ConfigureAwait(false);
-            if (memorySamples != null)
-                memorySamples.Add(CaptureMcpIndexMemorySample("finalize", runStopwatch));
-
-            var discoveredCSharpFiles = languageCounts.ContainsKey("csharp");
-            var discoveredSqlFiles = languageCounts.ContainsKey("sql");
-            var persistedCSharpFiles = writer.HasAnyFilesWithLanguage("csharp");
-            var persistedSqlFiles = writer.HasAnyFilesWithLanguage("sql");
-            var hasCSharpFiles = discoveredCSharpFiles || persistedCSharpFiles;
-            var hasSqlFiles = discoveredSqlFiles || persistedSqlFiles;
-            var sqlGraphContractReady = !hasSqlFiles
-                || (persistedSqlFiles && sqlGraphContractMatchesCurrent);
-            var csharpSymbolNameReady = !hasCSharpFiles
-                || (persistedCSharpFiles && csharpSymbolNameContractMatchesCurrent);
-            var csharpMetadataTargetReady = !hasCSharpFiles
-                || (persistedCSharpFiles && indexSnapshot.MetadataTargetCSharp == currentMetadataTargetVersion);
-            var structured = new JsonObject
-            {
-                ["path"] = projectPath,
-                ["checked_root_identity"] = authorizedRoot.CheckedRootIdentity,
-                ["rebuild"] = rebuild,
-                ["dry_run"] = false,
-                ["max_file_bytes"] = maxFileBytes,
-                ["index_options"] = optionsPayload,
-                ["unsupported_modes"] = unsupportedModesJson,
-                ["summary"] = new JsonObject
-                {
-                    ["files"] = totalFiles,
-                    ["chunks"] = totalChunks,
-                    ["symbols"] = totalSymbols,
-                    ["references"] = totalReferences,
-                    ["scanned"] = files.Count,
-                    ["skipped"] = 0,
-                    ["purged"] = 0,
-                    ["unknown_extension_file_count"] = scanResult.UnknownExtensionFiles.Count,
-                    ["errors"] = errors,
-                    ["failed_count"] = failures.Count,
-                    ["symbols_dropped_by_kind_filter"] = symbolsDroppedByKindFilter,
-                },
-                ["symbol_kind_filter"] = new JsonObject
-                {
-                    ["include"] = ToJsonStringArray(symbolKindFilter.Include),
-                    ["exclude"] = ToJsonStringArray(symbolKindFilter.Exclude),
-                    ["active"] = symbolKindFilter.IsActive,
-                },
-                ["duration_ms"] = runStopwatch.ElapsedMilliseconds,
-                ["started_at"] = runStartedAtUtc.ToString("o", System.Globalization.CultureInfo.InvariantCulture),
-                ["completed_at"] = GetUtcNow().ToString("o", System.Globalization.CultureInfo.InvariantCulture),
-                ["sql_graph_contract_ready"] = sqlGraphContractReady,
-                ["csharp_symbol_name_ready"] = csharpSymbolNameReady,
-                ["csharp_metadata_target_ready"] = csharpMetadataTargetReady,
-                ["fold_ready"] = (indexSnapshot.Readiness & DbContext.FoldReadyFlag) != 0,
-                ["fold_ready_reason"] = (indexSnapshot.Readiness & DbContext.FoldReadyFlag) != 0
-                    ? null
-                    : DegradationReasonCodes.MissingFoldBackfill,
-            };
-            if (memorySamples != null)
-                structured["memory_trace"] = memorySamples;
-
-            var failureArray = new JsonArray();
-            foreach (var failure in failures.Take(50))
-            {
-                failureArray.Add(new JsonObject
-                {
-                    ["path"] = failure.Path,
-                    ["stage"] = failure.Stage,
-                    ["exception_type"] = failure.ExceptionType,
-                    ["message"] = failure.Message,
-                    ["message_truncated"] = failure.MessageTruncated,
-                });
-            }
-            structured["failed_count"] = failures.Count;
-            structured["failures"] = failureArray;
-            if (failures.Count > 50)
-                structured["failures_truncated"] = failures.Count - 50;
-            AddMcpIndexDiagnostics(structured, failures, mcpIndexDiagnostics);
-            var referenceExtractionCapHits = writer.GetReferenceExtractionCapHits(
-                issuesStateAvailable: (indexSnapshot.Readiness & DbContext.IssuesReadyFlag) != 0);
-            using var referenceSignalReader = new DbReader(writer.Connection, isReadOnly: true);
-            var persistedReadiness = referenceSignalReader.GetPersistedIndexGenerationReadiness(
-                referenceExtractionCapHits);
-            AddIndexGenerationReadinessSignal(structured, persistedReadiness);
-            AddReferenceGraphCompletenessSignal(structured, persistedReadiness);
-            if (!sqlGraphContractReady)
-            {
-                AddSqlGraphContractSignal(
-                    structured,
-                    new SqlGraphContractSignal(
-                        Ready: false,
-                        Relevant: true,
-                        DegradedReason: DegradationReasonCodes.BuildSqlGraphContractDegradedReason()));
-            }
-            return CreateToolResult(
+        var beforeWriteFailures = new McpIndexBeforeWriteFailures(
+            failures,
+            mcpIndexDiagnostics,
+            symbolsDroppedByKindFilter);
+        var beforeWrite = await ValidateMcpIndexBeforeWriteAsync(
+            new McpIndexBeforeWriteContext(
                 id,
-                "Indexing stopped before index-data mutation because the scan snapshot changed.",
-                structured);
-        }
-
-        McpIndexInputSnapshotBarrierForTesting?.Invoke("before_write");
-        if (!indexer.TryValidateScanInputSnapshot(
+                new McpIndexBeforeWriteRequest(
+                    projectPath,
+                    authorizedRoot.CheckedRootIdentity,
+                    rebuild,
+                    maxFileBytes,
+                    optionsPayload,
+                    unsupportedModesJson,
+                    symbolKindFilter),
+                new McpIndexBeforeWriteRun(
+                    progressToken,
+                    runStopwatch,
+                    runStartedAtUtc,
+                    memorySamples),
+                indexer,
                 scanInputSnapshot,
-                out var beforeWriteChangedScanInputPath,
-                requestToken))
-        {
-            return await ReturnBeforeWriteSnapshotFailureAsync(
-                beforeWriteChangedScanInputPath).ConfigureAwait(false);
-        }
-
-        if (!deferCSharpMutationsForIncompleteScan)
-        {
-            var stableFiles = true;
-            string? changedFilePath = null;
-            if (csharpWorkspaceFileSnapshots != null)
-            {
-                stableFiles = CSharpStaticInterfacePrepass.TryValidateFileStatSnapshots(
-                    csharpPrepassTargets,
-                    csharpWorkspaceFileSnapshots,
-                    out changedFilePath,
-                    requestToken,
-                    target => authorizedRoot.EnsureAuthorizedEntry(target.FilePath));
-            }
-            if (!stableFiles)
-            {
-                csharpPrepassSymbolArtifacts?.Clear();
-                csharpPrepassSymbolArtifacts = null;
-                var driftPath = FormatCSharpWorkspaceSnapshotPath(changedFilePath);
-                incompleteCSharpPrepassPaths = [driftPath];
-                deferCSharpMutationsForIncompleteScan = true;
-                staleFilePurgePlan = FilePurgePlan.Empty;
-                purged = 0;
-                hadCSharpStaticInterfaceContractsBeforePurge = false;
-                preservePriorPositiveCSharpSourceNoOp = false;
-                csharpSourceEvidenceForStamp = false;
-                csharpSourceEvidenceComplete = false;
-                csharpWorkspaceFileSnapshots = null;
-                csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
-                    [],
-                    HasStaticInterfaceContracts: true,
-                    SourceContractEvidenceComplete: false,
-                    IncompleteSourcePaths: incompleteCSharpPrepassPaths);
-                RecordIncompleteCSharpPrepassFailures(incompleteCSharpPrepassPaths);
-                useFtsBulkLoad = false;
-            }
-        }
+                scanResult,
+                new McpIndexBeforeWriteReadiness(
+                    indexSnapshot,
+                    sqlGraphContractMatchesCurrent,
+                    csharpSymbolNameContractMatchesCurrent,
+                    currentMetadataTargetVersion),
+                beforeWriteFailures),
+            writer,
+            csharpState,
+            staleFilePurgePlan,
+            purged,
+            hadCSharpStaticInterfaceContractsBeforePurge,
+            useFtsBulkLoad,
+            requestToken).ConfigureAwait(false);
+        if (beforeWrite.Response != null)
+            return beforeWrite.Response;
+        staleFilePurgePlan = beforeWrite.PurgePlan;
+        purged = beforeWrite.Purged;
+        hadCSharpStaticInterfaceContractsBeforePurge =
+            beforeWrite.HadCSharpStaticInterfaceContractsBeforePurge;
+        useFtsBulkLoad = beforeWrite.UseFtsBulkLoad;
+        errors = failures.Count;
 
         // Rebuild destruction and interrupted-FTS recovery are deliberately delayed until
         // the same pre-write scan barrier as ordinary MCP indexing. A drifted scan therefore
@@ -1035,10 +766,10 @@ await EmitProgressNotificationAsync(
         using var hotspotAggregateRefresh = writer.BeginDeferredHotspotReferenceAggregateRefresh(
             deferSecondaryIndexes: useFtsBulkLoad);
         writer.RecoverInterruptedFtsBulkLoadIfNeeded(requestToken);
-        if (!preservePriorPositiveCSharpSourceNoOp)
+        if (!csharpState.PreservePriorPositiveSourceNoOp)
         {
             writer.SetCSharpStaticInterfaceSourceEvidence(
-                csharpSourceEvidenceComplete && csharpSourceEvidenceForStamp ? true : null);
+                csharpState.SourceEvidenceComplete && csharpState.SourceEvidenceForStamp ? true : null);
         }
         writer.ClearReadyFlags();
         writer.ClearReferenceIdentityContractReady();
@@ -1046,7 +777,7 @@ await EmitProgressNotificationAsync(
         writer.ClearSqlGraphContractReady();
         writer.ClearMetadataTargetReady();
         if (hadCSharpStaticInterfaceContractsBeforePurge
-            || csharpWorkspace.HasStaticInterfaceContracts)
+            || csharpState.Workspace.HasStaticInterfaceContracts)
             writer.SetMeta(DbContext.CSharpSymbolNameContractVersionMetaKey, null);
         if (useFullRunBatchMarker)
             writer.MarkBatchInProgress();
@@ -1077,41 +808,12 @@ await EmitProgressNotificationAsync(
         }
 
         McpIndexReferencePurgeForTesting?.Invoke();
-        var purgedRefs = deferCSharpMutationsForIncompleteScan || startedWithNoIndexedFiles
+        var purgedRefs = csharpState.DeferMutations || startedWithNoIndexedFiles
             ? 0
             : writer.PurgeUnsupportedReferences(ReferenceExtractor.GetSupportedLanguages(projectPath));
         if (purgedRefs > 0)
             mutualRecursionRefreshNeeded = true;
 
-        void DeferCSharpMutationsForStatRevalidation(
-            in CSharpStaticInterfacePrepass.FileTarget target)
-        {
-            // The final global C# check passed, but this file changed before its
-            // actual skip. Row mutations have already begun, so preserve every C#
-            // row from this point, leave evidence unknown, and require a clean retry.
-            // global最終check後にC# statが崩れた場合、以後のC# rowを保持してpartialにする。
-            preservePriorPositiveCSharpSourceNoOp = false;
-            deferCSharpMutationsForIncompleteScan = true;
-            csharpSourceEvidenceForStamp = false;
-            csharpSourceEvidenceComplete = false;
-            writer.SetCSharpStaticInterfaceSourceEvidence(null);
-            RecordCSharpWorkspaceFailure(
-                target.IndexPath,
-                "csharp_stat_revalidation",
-                new IOException(
-                    "A C# source changed after final workspace preflight; rerun indexing to refresh the complete C# graph."));
-            try
-            {
-                var info = new FileInfo(target.FilePath);
-                if (info.Exists && info.Length >= 0)
-                    readableBytes.Remember(target.FilePath, info.Length);
-            }
-            catch (Exception ex) when (ex is IOException or UnauthorizedAccessException
-                or NotSupportedException or ArgumentException)
-            {
-            }
-        }
-
         var fileLoopContext = new McpIndexFileLoopContext
         {
             Writer = writer,
@@ -1139,16 +841,8 @@ void DeferCSharpMutationsForStatRevalidation(
             StatPreflightCompleted = ftsPreflight.Completed,
             SymbolKindFilter = symbolKindFilter,
             PostExtractionHooks = postExtractionHooks,
-            GetCSharpWorkspace = () => csharpWorkspace,
-            GetCSharpPrepassArtifacts = () => csharpPrepassSymbolArtifacts,
-            DeferCSharpMutations = () => deferCSharpMutationsForIncompleteScan,
-            PreservePriorPositiveCSharpSourceNoOp =
-                () => preservePriorPositiveCSharpSourceNoOp,
-            HasCSharpWorkspaceSnapshots = () => csharpWorkspaceFileSnapshots != null,
+            CSharpWorkspace = csharpState,
             GetStatMatchedFile = GetStatMatchedFile,
-            LoadedCSharpWorkspaceSnapshotMatches = LoadedCSharpWorkspaceSnapshotMatches,
-            DeferCSharpStatRevalidation = DeferCSharpMutationsForStatRevalidation,
-            DeferCSharpLoadedSnapshotDrift = DeferCSharpMutationsForLoadedSnapshotDrift,
             RememberReadableFileSize = readableBytes.Remember,
             InsertIssuesForIndexedFile = InsertIssuesForIndexedFile,
             WriteProjectRootOnce = WriteProjectRootOnce,
@@ -1175,10 +869,10 @@ await RunMcpIndexFileLoopAsync(fileLoopContext, fileLoopSession)
             .ConfigureAwait(false);
         processed = fileLoopSession.Processed;
         skipped = fileLoopSession.Skipped;
-        // Workspace-drift callbacks still own their outer validation state and append
-        // directly to the shared failure list. Per-file failures do the same through
-        // the session, so the list remains the authoritative error count at the join.
-        // workspace drift callback と file loop の双方が共有 failure list へ追記するため、
+        // The typed C# workspace state appends drift failures directly to the shared
+        // failure list. Per-file failures do the same through the session, so the list
+        // remains the authoritative error count at the join.
+        // typed C# workspace state と file loop の双方が共有 failure list へ追記するため、
         // join 時の error 数は同listから復元する。
         errors = failures.Count;
         ftsMutated = fileLoopSession.FtsMutated;
@@ -1191,11 +885,10 @@ await RunMcpIndexFileLoopAsync(fileLoopContext, fileLoopSession)
         freshCountSymbols = fileLoopSession.FreshCountSymbols;
         freshCountReferences = fileLoopSession.FreshCountReferences;
 
-        csharpPrepassSymbolArtifacts?.Clear();
-        csharpPrepassSymbolArtifacts = null;
+        csharpState.ClearArtifacts();
 
         var referenceIdentityReadyForMutualRecursionRefresh =
-            !deferCSharpMutationsForIncompleteScan && mutualRecursionRefreshNeeded
+            !csharpState.DeferMutations && mutualRecursionRefreshNeeded
                 ? writer.CSharpFamilyTrustAllowsReferenceIdentityReady(
                     startedWithNoIndexedFiles
                     && !scanHadErrors
@@ -1208,7 +901,7 @@ await RunMcpIndexFileLoopAsync(fileLoopContext, fileLoopSession)
             && !scanHadErrors
             && !hasTypeScriptTargets;
         var willRebuildTypeScriptAugmentation =
-            !deferCSharpMutationsForIncompleteScan
+            !csharpState.DeferMutations
             && TypeScriptAugmentationRefreshPolicy.ShouldRebuildReferences(
                 symbolsOnly: false,
                 canFinalize: !scanHadErrors && errors == 0,
@@ -1218,7 +911,7 @@ await RunMcpIndexFileLoopAsync(fileLoopContext, fileLoopSession)
                     canStampTypeScriptAugmentationReadyWithoutRebuild);
         var deferMutualRecursionRefreshToTypeScriptAugmentation =
             mutualRecursionRefreshNeeded && willRebuildTypeScriptAugmentation;
-        if (!deferCSharpMutationsForIncompleteScan
+        if (!csharpState.DeferMutations
             && mutualRecursionRefreshNeeded
             && !deferMutualRecursionRefreshToTypeScriptAugmentation)
         {
@@ -1258,19 +951,15 @@ await EmitProgressNotificationAsync(
         }
         var readinessStableFiles = true;
         string? readinessChangedFilePath = null;
-        if (errors == 0 && !deferCSharpMutationsForIncompleteScan)
+        if (errors == 0 && !csharpState.DeferMutations)
         {
             McpIndexCSharpReadinessValidationForTesting?.Invoke();
-            if (csharpWorkspaceFileSnapshots != null)
+            if (csharpState.HasFileSnapshots)
             {
-                readinessStableFiles = CSharpStaticInterfacePrepass.TryValidateFileStatSnapshots(
-                    csharpPrepassTargets,
-                    csharpWorkspaceFileSnapshots,
-                    out readinessChangedFilePath,
-                    requestToken,
-                    target => authorizedRoot.EnsureAuthorizedEntry(target.FilePath));
+                readinessStableFiles = csharpState.TryValidateFileSnapshots(
+                    out readinessChangedFilePath);
             }
-            else if (preservePriorPositiveCSharpSourceNoOp)
+            else if (csharpState.PreservePriorPositiveSourceNoOp)
             {
                 foreach (var target in csharpPrepassTargets)
                 {
@@ -1302,11 +991,13 @@ await EmitProgressNotificationAsync(
                 requestToken);
             if (!readinessStableFiles || !readinessStableScanInputs)
             {
-                DeferCSharpMutationsForLoadedSnapshotDrift(
-                    FormatCSharpWorkspaceSnapshotPath(
+                csharpState.DeferForLoadedSnapshotDrift(
+                    csharpState.FormatSnapshotPath(
                         readinessChangedFilePath
                         ?? readinessChangedScanInputPath
-                        ?? "<csharp_workspace>"));
+                        ?? "<csharp_workspace>"),
+                    writer);
+                errors = failures.Count;
             }
         }
         // MCP index now runs ValidateContent + InsertIssues per file (bdbb2bd) on par with CLI
@@ -1314,24 +1005,25 @@ await EmitProgressNotificationAsync(
         // path is no longer accurate. Bits are only stamped when every file committed without
         // throwing, so a partial failure leaves trust degraded and `validate` still surfaces it.
         // MCP index は CLI と同等に file_issues を永続化するため、成功時は graph / issues の両方を stamp する。
-        if (!deferCSharpMutationsForIncompleteScan
+        if (!csharpState.DeferMutations
             && postExtractionHooks.ValueIfCreated?.SawCSharpStaticInterfaceSourceContract == true)
         {
-            if (!csharpWorkspace.HasSourceStaticInterfaceContracts)
+            if (!csharpState.Workspace.HasSourceStaticInterfaceContracts)
             {
-                csharpSourceEvidenceForStamp = false;
-                csharpSourceEvidenceComplete = false;
+                csharpState.SourceEvidenceForStamp = false;
+                csharpState.SourceEvidenceComplete = false;
                 writer.SetCSharpStaticInterfaceSourceEvidence(null);
-                RecordCSharpWorkspaceFailure(
+                csharpFailures.Record(
                     "<csharp_workspace>",
                     "csharp_workspace_validation",
                     new InvalidOperationException(
                         "A C# static-interface contract appeared after workspace preflight; rerun indexing to repair unchanged implementers."));
+                errors = failures.Count;
             }
             else
             {
-                csharpSourceEvidenceForStamp = true;
-                csharpSourceEvidenceComplete = true;
+                csharpState.SourceEvidenceForStamp = true;
+                csharpState.SourceEvidenceComplete = true;
                 writer.SetCSharpStaticInterfaceSourceEvidence(true);
             }
         }
@@ -1340,7 +1032,7 @@ await EmitProgressNotificationAsync(
         // the deferred pass before publishing partial metadata.
         // late validation で augmentation を実行できない場合だけ、partial metadata 前に補完する。
         var willRebuildTypeScriptAugmentationAfterReadinessValidation =
-            !deferCSharpMutationsForIncompleteScan
+            !csharpState.DeferMutations
             && TypeScriptAugmentationRefreshPolicy.ShouldRebuildReferences(
                 symbolsOnly: false,
                 canFinalize: !scanHadErrors && errors == 0,
@@ -1436,8 +1128,8 @@ await EmitProgressNotificationAsync(
             writer.MarkIssuesReady();
             writer.MarkIndexReaderContractsReady(symbolsOnlyGraphOmitted: false);
             writer.MarkHdlGraphContractReady();
-            if (csharpSourceEvidenceComplete && !preservePriorPositiveCSharpSourceNoOp)
-                writer.SetCSharpStaticInterfaceSourceEvidence(csharpSourceEvidenceForStamp);
+            if (csharpState.SourceEvidenceComplete && !csharpState.PreservePriorPositiveSourceNoOp)
+                writer.SetCSharpStaticInterfaceSourceEvidence(csharpState.SourceEvidenceForStamp);
             csharpSymbolNameReadyAfter = true;
             if (hasCSharpFilesAfter)
             {
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.ExtractedFilePersistence.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.ExtractedFilePersistence.cs
index 936725a31..1b2e8c307 100644
--- a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.ExtractedFilePersistence.cs
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.ExtractedFilePersistence.cs
@@ -73,7 +73,7 @@ private static (List<SymbolRecord> Symbols, FileIssue? TimeoutIssue)
     {
         if (record.Lang == "csharp"
             && record.Checksum is { } checksum
-            && context.GetCSharpPrepassArtifacts()?.TryTake(
+            && context.CSharpWorkspace.PrepassArtifacts?.TryTake(
                 record.Path,
                 checksum,
                 out var artifact) == true)
@@ -173,7 +173,7 @@ private static (List<ReferenceRecord> References,
                    record.Lang,
                    "reference_extraction"))
         {
-            var workspace = context.GetCSharpWorkspace();
+            var workspace = context.CSharpWorkspace.Workspace;
             extraction = ReferenceExtractor.ExtractDetailedNormalized(
                 fileId,
                 record.Lang,
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FileLoop.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FileLoop.cs
index c2f3b10f3..a5910ae78 100644
--- a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FileLoop.cs
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FileLoop.cs
@@ -12,13 +12,6 @@ public partial class McpServer
     private delegate IndexedFileStatReuseResult? McpIndexStatMatchResolver(
         in CSharpStaticInterfacePrepass.FileTarget target);
 
-    private delegate bool McpIndexLoadedSnapshotMatcher(
-        in CSharpStaticInterfacePrepass.FileTarget target,
-        FileRecord record);
-
-    private delegate void McpIndexStatRevalidationHandler(
-        in CSharpStaticInterfacePrepass.FileTarget target);
-
     private sealed class McpIndexFileLoopContext
     {
         internal required DbWriter Writer { get; init; }
@@ -46,15 +39,8 @@ private sealed class McpIndexFileLoopContext
         internal bool[]? StatPreflightCompleted { get; init; }
         internal required SymbolKindFilter SymbolKindFilter { get; init; }
         internal required IndexCommandRunner.LazyDisposable<PostExtractionHookRunner> PostExtractionHooks { get; init; }
-        internal required Func<CSharpStaticInterfaceWorkspaceSymbols> GetCSharpWorkspace { get; init; }
-        internal required Func<CSharpPrepassSymbolArtifactCache?> GetCSharpPrepassArtifacts { get; init; }
-        internal required Func<bool> DeferCSharpMutations { get; init; }
-        internal required Func<bool> PreservePriorPositiveCSharpSourceNoOp { get; init; }
-        internal required Func<bool> HasCSharpWorkspaceSnapshots { get; init; }
+        internal required McpIndexCSharpWorkspaceState CSharpWorkspace { get; init; }
         internal required McpIndexStatMatchResolver GetStatMatchedFile { get; init; }
-        internal required McpIndexLoadedSnapshotMatcher LoadedCSharpWorkspaceSnapshotMatches { get; init; }
-        internal required McpIndexStatRevalidationHandler DeferCSharpStatRevalidation { get; init; }
-        internal required Action<string> DeferCSharpLoadedSnapshotDrift { get; init; }
         internal required Action<string, long> RememberReadableFileSize { get; init; }
         internal required Action<long, IReadOnlyList<FileIssue>> InsertIssuesForIndexedFile { get; init; }
         internal required Action WriteProjectRootOnce { get; init; }
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FilePersistence.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FilePersistence.cs
index c4640617c..03756e6f0 100644
--- a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FilePersistence.cs
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.FilePersistence.cs
@@ -22,7 +22,7 @@ private async Task<bool> ProcessMcpIndexFileAsync(
         var target = context.Targets[targetIndex];
         context.CancellationToken.ThrowIfCancellationRequested();
         context.AuthorizedRoot.EnsureAuthorizedEntry(target.FilePath);
-        if (context.DeferCSharpMutations()
+        if (context.CSharpWorkspace.DeferMutations
             && target.Language == "csharp")
         {
             TryRememberMcpIndexFileSize(context, target.FilePath);
@@ -31,11 +31,11 @@ private async Task<bool> ProcessMcpIndexFileAsync(
         }
 
         var statMatchedFile = ResolveMcpStatMatch(context, targetIndex, in target);
-        if (context.PreservePriorPositiveCSharpSourceNoOp()
+        if (context.CSharpWorkspace.PreservePriorPositiveSourceNoOp
             && target.Language == "csharp"
             && statMatchedFile == null)
         {
-            context.DeferCSharpStatRevalidation(in target);
+            context.CSharpWorkspace.DeferForStatRevalidation(in target, context.Writer);
             return await CompleteMcpIndexFileEarlyAsync(context, session, emitProgress: true)
                 .ConfigureAwait(false);
         }
@@ -54,7 +54,10 @@ private async Task<bool> ProcessMcpIndexFileAsync(
             target.Language,
             context.CancellationToken);
         var record = loaded.Record;
-        if (!context.LoadedCSharpWorkspaceSnapshotMatches(in target, record))
+        if (!context.CSharpWorkspace.LoadedSnapshotMatches(
+                in target,
+                record,
+                context.Writer))
         {
             context.RememberReadableFileSize(target.FilePath, record.Size);
             return await CompleteMcpIndexFileEarlyAsync(context, session, emitProgress: true)
@@ -171,7 +174,7 @@ private static bool CanReuseLoadedMcpIndexFile(
                 && context.SymbolKindFilterMatchesPrior
                 && (record.Lang != "csharp" || context.CSharpIndexedProjectRootCompatible)
                 && (record.Lang != "csharp" || context.CSharpSymbolNameContractMatchesCurrent)
-                && (record.Lang != "csharp" || !context.GetCSharpWorkspace().HasStaticInterfaceContracts)
+                && (record.Lang != "csharp" || !context.CSharpWorkspace.Workspace.HasStaticInterfaceContracts)
                 && (record.Lang != "sql" || context.SqlGraphContractMatchesCurrent)
                 && (record.Lang is not ("verilog" or "systemverilog" or "vhdl")
                     || context.HdlGraphContractMatchesCurrent)
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.PreWrite.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.PreWrite.cs
new file mode 100644
index 000000000..24afe8efd
--- /dev/null
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.PreWrite.cs
@@ -0,0 +1,232 @@
+using System.Diagnostics;
+using System.Text.Json.Nodes;
+using CodeIndex.Cli;
+using CodeIndex.Database;
+using CodeIndex.Diagnostics;
+using CodeIndex.Indexer;
+
+namespace CodeIndex.Mcp;
+
+public partial class McpServer
+{
+    private readonly record struct McpIndexBeforeWriteRequest(
+        string ProjectPath,
+        string CheckedRootIdentity,
+        bool Rebuild,
+        long? MaxFileBytes,
+        JsonObject OptionsPayload,
+        JsonArray UnsupportedModes,
+        SymbolKindFilter SymbolKindFilter);
+
+    private readonly record struct McpIndexBeforeWriteRun(
+        JsonNode? ProgressToken,
+        Stopwatch Stopwatch,
+        DateTime StartedAtUtc,
+        JsonArray? MemorySamples);
+
+    private readonly record struct McpIndexBeforeWriteReadiness(
+        IndexDatabaseSnapshot IndexSnapshot,
+        bool SqlGraphContractMatchesCurrent,
+        bool CSharpSymbolNameContractMatchesCurrent,
+        string CurrentMetadataTargetVersion);
+
+    private readonly record struct McpIndexBeforeWriteFailures(
+        List<IndexFileFailure> Failures,
+        List<McpIndexDiagnostic> Diagnostics,
+        int SymbolsDroppedByKindFilter);
+
+    private readonly record struct McpIndexBeforeWriteContext(
+        JsonNode? Id,
+        McpIndexBeforeWriteRequest Request,
+        McpIndexBeforeWriteRun Run,
+        FileIndexer Indexer,
+        FileIndexer.ScanInputSnapshot ScanInputSnapshot,
+        FileIndexer.ScanFilesResult ScanResult,
+        McpIndexBeforeWriteReadiness Readiness,
+        McpIndexBeforeWriteFailures FailureState);
+
+    private readonly record struct McpIndexBeforeWriteResult(
+        JsonNode? Response,
+        FilePurgePlan PurgePlan,
+        int Purged,
+        bool HadCSharpStaticInterfaceContractsBeforePurge,
+        bool UseFtsBulkLoad);
+
+    private async Task<McpIndexBeforeWriteResult> ValidateMcpIndexBeforeWriteAsync(
+        McpIndexBeforeWriteContext context,
+        DbWriter writer,
+        McpIndexCSharpWorkspaceState csharpState,
+        FilePurgePlan purgePlan,
+        int purged,
+        bool hadCSharpContractsBeforePurge,
+        bool useFtsBulkLoad,
+        CancellationToken cancellationToken)
+    {
+        McpIndexInputSnapshotBarrierForTesting?.Invoke("before_write");
+        if (!context.Indexer.TryValidateScanInputSnapshot(
+                context.ScanInputSnapshot,
+                out var changedScanInputPath,
+                cancellationToken))
+        {
+            csharpState.RecordScanInputDrift(changedScanInputPath);
+            var response = await ReturnMcpIndexBeforeWriteSnapshotFailureAsync(
+                    context,
+                    writer)
+                .ConfigureAwait(false);
+            return new(response, purgePlan, purged, hadCSharpContractsBeforePurge, useFtsBulkLoad);
+        }
+
+        if (!csharpState.DeferMutations
+            && !csharpState.TryValidateFileSnapshots(out var changedCSharpPath))
+        {
+            csharpState.DeferForBeforeWriteStatDrift(changedCSharpPath);
+            purgePlan = FilePurgePlan.Empty;
+            purged = 0;
+            hadCSharpContractsBeforePurge = false;
+            useFtsBulkLoad = false;
+        }
+
+        return new(null, purgePlan, purged, hadCSharpContractsBeforePurge, useFtsBulkLoad);
+    }
+
+    private async Task<JsonNode> ReturnMcpIndexBeforeWriteSnapshotFailureAsync(
+        McpIndexBeforeWriteContext context,
+        DbWriter writer)
+    {
+        var (totalFiles, totalChunks, totalSymbols, totalReferences) = writer.GetCounts();
+        await EmitProgressNotificationAsync(
+                context.Run.ProgressToken,
+                0,
+                context.ScanResult.Files.Count,
+                "Indexing stopped before index-data mutation because scan inputs changed.")
+            .ConfigureAwait(false);
+        if (context.Run.MemorySamples != null)
+        {
+            context.Run.MemorySamples.Add(
+                CaptureMcpIndexMemorySample("finalize", context.Run.Stopwatch));
+        }
+
+        var structured = BuildMcpIndexBeforeWriteFailurePayload(
+            context,
+            writer,
+            totalFiles,
+            totalChunks,
+            totalSymbols,
+            totalReferences);
+        AddMcpIndexBeforeWriteFailureSignals(context, writer, structured);
+        return CreateToolResult(
+            context.Id,
+            "Indexing stopped before index-data mutation because the scan snapshot changed.",
+            structured);
+    }
+
+    private JsonObject BuildMcpIndexBeforeWriteFailurePayload(
+        McpIndexBeforeWriteContext context,
+        DbWriter writer,
+        long totalFiles,
+        long totalChunks,
+        long totalSymbols,
+        long totalReferences)
+    {
+        var request = context.Request;
+        var failureState = context.FailureState;
+        var readiness = context.Readiness;
+        var languageCounts = context.ScanResult.LanguageCounts;
+        var persistedCSharpFiles = writer.HasAnyFilesWithLanguage("csharp");
+        var persistedSqlFiles = writer.HasAnyFilesWithLanguage("sql");
+        var hasCSharpFiles = languageCounts.ContainsKey("csharp") || persistedCSharpFiles;
+        var hasSqlFiles = languageCounts.ContainsKey("sql") || persistedSqlFiles;
+        var structured = new JsonObject
+        {
+            ["path"] = request.ProjectPath,
+            ["checked_root_identity"] = request.CheckedRootIdentity,
+            ["rebuild"] = request.Rebuild,
+            ["dry_run"] = false,
+            ["max_file_bytes"] = request.MaxFileBytes,
+            ["index_options"] = request.OptionsPayload,
+            ["unsupported_modes"] = request.UnsupportedModes,
+            ["summary"] = new JsonObject
+            {
+                ["files"] = totalFiles,
+                ["chunks"] = totalChunks,
+                ["symbols"] = totalSymbols,
+                ["references"] = totalReferences,
+                ["scanned"] = context.ScanResult.Files.Count,
+                ["skipped"] = 0,
+                ["purged"] = 0,
+                ["unknown_extension_file_count"] = context.ScanResult.UnknownExtensionFiles.Count,
+                ["errors"] = failureState.Failures.Count,
+                ["failed_count"] = failureState.Failures.Count,
+                ["symbols_dropped_by_kind_filter"] = failureState.SymbolsDroppedByKindFilter,
+            },
+            ["symbol_kind_filter"] = new JsonObject
+            {
+                ["include"] = ToJsonStringArray(request.SymbolKindFilter.Include),
+                ["exclude"] = ToJsonStringArray(request.SymbolKindFilter.Exclude),
+                ["active"] = request.SymbolKindFilter.IsActive,
+            },
+            ["duration_ms"] = context.Run.Stopwatch.ElapsedMilliseconds,
+            ["started_at"] = context.Run.StartedAtUtc.ToString("o", System.Globalization.CultureInfo.InvariantCulture),
+            ["completed_at"] = GetUtcNow().ToString("o", System.Globalization.CultureInfo.InvariantCulture),
+            ["sql_graph_contract_ready"] = !hasSqlFiles
+                || (persistedSqlFiles && readiness.SqlGraphContractMatchesCurrent),
+            ["csharp_symbol_name_ready"] = !hasCSharpFiles
+                || (persistedCSharpFiles && readiness.CSharpSymbolNameContractMatchesCurrent),
+            ["csharp_metadata_target_ready"] = !hasCSharpFiles
+                || (persistedCSharpFiles
+                    && readiness.IndexSnapshot.MetadataTargetCSharp
+                        == readiness.CurrentMetadataTargetVersion),
+            ["fold_ready"] =
+                (readiness.IndexSnapshot.Readiness & DbContext.FoldReadyFlag) != 0,
+            ["fold_ready_reason"] =
+                (readiness.IndexSnapshot.Readiness & DbContext.FoldReadyFlag) != 0
+                    ? null
+                    : DegradationReasonCodes.MissingFoldBackfill,
+        };
+        if (context.Run.MemorySamples != null)
+            structured["memory_trace"] = context.Run.MemorySamples;
+        return structured;
+    }
+
+    private void AddMcpIndexBeforeWriteFailureSignals(
+        McpIndexBeforeWriteContext context,
+        DbWriter writer,
+        JsonObject structured)
+    {
+        var failures = context.FailureState.Failures;
+        var failureArray = new JsonArray();
+        foreach (var failure in failures.Take(50))
+        {
+            failureArray.Add(new JsonObject
+            {
+                ["path"] = failure.Path,
+                ["stage"] = failure.Stage,
+                ["exception_type"] = failure.ExceptionType,
+                ["message"] = failure.Message,
+                ["message_truncated"] = failure.MessageTruncated,
+            });
+        }
+        structured["failed_count"] = failures.Count;
+        structured["failures"] = failureArray;
+        if (failures.Count > 50)
+            structured["failures_truncated"] = failures.Count - 50;
+        AddMcpIndexDiagnostics(structured, failures, context.FailureState.Diagnostics);
+
+        var snapshot = context.Readiness.IndexSnapshot;
+        var capHits = writer.GetReferenceExtractionCapHits(
+            issuesStateAvailable: (snapshot.Readiness & DbContext.IssuesReadyFlag) != 0);
+        using var reader = new DbReader(writer.Connection, isReadOnly: true);
+        var persistedReadiness = reader.GetPersistedIndexGenerationReadiness(capHits);
+        AddIndexGenerationReadinessSignal(structured, persistedReadiness);
+        AddReferenceGraphCompletenessSignal(structured, persistedReadiness);
+        if (structured["sql_graph_contract_ready"]?.GetValue<bool>() == false)
+        {
+            AddSqlGraphContractSignal(
+                structured,
+                new SqlGraphContractSignal(
+                    Ready: false,
+                    Relevant: true,
+                    DegradedReason: DegradationReasonCodes.BuildSqlGraphContractDegradedReason()));
+        }
+    }
+}
diff --git a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.SkippedFiles.cs b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.SkippedFiles.cs
index 997db8c4b..e3c0b847c 100644
--- a/src/CodeIndex/Mcp/McpToolHandlers.Indexing.SkippedFiles.cs
+++ b/src/CodeIndex/Mcp/McpToolHandlers.Indexing.SkippedFiles.cs
@@ -54,7 +54,10 @@ private void PersistMcpSkippedFile(
                 target.RelativePath,
                 target.Language);
             context.RememberReadableFileSize(target.FilePath, record.Size);
-            if (!context.LoadedCSharpWorkspaceSnapshotMatches(in target, record))
+            if (!context.CSharpWorkspace.LoadedSnapshotMatches(
+                    in target,
+                    record,
+                    context.Writer))
             {
                 session.Skipped++;
                 return;
@@ -144,9 +147,11 @@ private async Task<bool> HandleMissingMcpIndexFileAsync(
         if (session.FileBatchMarked)
             context.Writer.ClearBatchInProgress();
 
-        if (target.Language == "csharp" && context.HasCSharpWorkspaceSnapshots())
+        if (target.Language == "csharp" && context.CSharpWorkspace.HasFileSnapshots)
         {
-            context.DeferCSharpLoadedSnapshotDrift(target.DisplayRelativePath);
+            context.CSharpWorkspace.DeferForLoadedSnapshotDrift(
+                target.DisplayRelativePath,
+                context.Writer);
             session.Skipped++;
             session.Processed++;
             await EmitProgressNotificationAsync(
diff --git a/tests/CodeIndex.Tests/McpServerToolsCallTests.cs b/tests/CodeIndex.Tests/McpServerToolsCallTests.cs
index d45e399b6..23f2abda8 100644
--- a/tests/CodeIndex.Tests/McpServerToolsCallTests.cs
+++ b/tests/CodeIndex.Tests/McpServerToolsCallTests.cs
@@ -10741,8 +10741,10 @@ public void ToolsCall_Index_FreshSnapshotAbortRetainsDiscoveredLanguageFailuresW
         }
     }
 
-    [Fact]
-    public void ToolsCall_Index_FirstSnapshotBarrierDriftPreservesRowsTrustAndRecoveryMarker()
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public void ToolsCall_Index_FirstSnapshotBarrierDriftPreservesRowsTrustAndRecoveryMarker(bool rebuild)
     {
         var fixtureDir = Path.Combine(
             Path.GetFullPath("."),
@@ -10806,10 +10808,14 @@ public void ToolsCall_Index_FirstSnapshotBarrierDriftPreservesRowsTrustAndRecove
                 Directory.SetLastWriteTimeUtc(fixtureDir, rootModifiedUtc);
             };
 
-            var response = CallIndex(server, fixtureDir);
+            var response = CallIndex(
+                server,
+                fixtureDir,
+                args => args["rebuild"] = rebuild);
 
             Assert.False(response["result"]?["isError"]?.GetValue<bool>() ?? false, response.ToJsonString());
             var structured = response["result"]!["structuredContent"]!;
+            Assert.Equal(rebuild, structured["rebuild"]!.GetValue<bool>());
             Assert.Equal(1, structured["summary"]!["errors"]!.GetValue<int>());
             Assert.Equal(0, structured["summary"]!["purged"]!.GetValue<int>());
             Assert.Equal(["before_write"], phases);
@@ -10842,6 +10848,112 @@ public void ToolsCall_Index_FirstSnapshotBarrierDriftPreservesRowsTrustAndRecove
         }
     }
 
+    [Fact]
+    public void ToolsCall_Index_BeforeWriteCsharpStatDriftSuppressesPurgeAndPreservesCsharpRows()
+    {
+        var fixtureDir = Path.Combine(
+            Path.GetFullPath("."),
+            $"mcp_index_csharp_before_write_drift_{Guid.NewGuid():N}");
+        var dbPath = TestProjectHelper.CreateTempDbPath("cdidx_mcp_csharp_before_write_drift");
+        var previousBarrierHook = McpServer.McpIndexInputSnapshotBarrierForTesting;
+        var interfacePath = Path.Combine(fixtureDir, "IParseable.cs");
+        var implementationPath = Path.Combine(fixtureDir, "Money.cs");
+        var obsoletePath = Path.Combine(fixtureDir, "obsolete.md");
+        var phases = new List<string>();
+        var interfaceChanged = 0;
+        try
+        {
+            Directory.CreateDirectory(fixtureDir);
+            File.WriteAllText(
+                interfacePath,
+                "public interface IParseable<T> { static abstract T Parse(string s); }\n");
+            File.WriteAllText(
+                implementationPath,
+                "public readonly struct Money : IParseable<Money>\n"
+                + "{\n"
+                + "    public static Money Parse(string s) => new();\n"
+                + "}\n");
+            File.WriteAllText(obsoletePath, "# Obsolete\n");
+
+            using var server = new McpServer(dbPath, ConsoleUi.LoadVersion());
+            var initialResponse = CallIndex(server, fixtureDir);
+            Assert.False(
+                initialResponse["result"]?["isError"]?.GetValue<bool>() ?? false,
+                initialResponse.ToJsonString());
+
+            string? priorInterfaceChecksum;
+            string? priorImplementationChecksum;
+            using (var db = new DbContext(DbOpenIntent.WriteIndex, dbPath))
+            {
+                var reader = new DbReader(db.Connection);
+                priorInterfaceChecksum = reader.GetFileByPath("IParseable.cs")?.Checksum;
+                priorImplementationChecksum = reader.GetFileByPath("Money.cs")?.Checksum;
+                Assert.Equal(true, new DbWriter(db).GetCSharpStaticInterfaceSourceEvidence());
+                Assert.Equal(1L, CountImplicitReferences(db));
+            }
+
+            File.AppendAllText(implementationPath, "// force workspace preflight\n");
+            File.SetLastWriteTimeUtc(implementationPath, DateTime.UtcNow.AddSeconds(2));
+            File.Delete(obsoletePath);
+            McpServer.McpIndexInputSnapshotBarrierForTesting = phase =>
+            {
+                phases.Add(phase);
+                if (phase != "before_write"
+                    || Interlocked.Exchange(ref interfaceChanged, 1) != 0)
+                {
+                    return;
+                }
+
+                File.WriteAllText(interfacePath, "public interface IParseable<T> { }\n");
+                File.SetLastWriteTimeUtc(interfacePath, DateTime.UtcNow.AddSeconds(3));
+            };
+
+            var partialResponse = CallIndex(server, fixtureDir);
+
+            Assert.False(
+                partialResponse["result"]?["isError"]?.GetValue<bool>() ?? false,
+                partialResponse.ToJsonString());
+            Assert.Equal(1, interfaceChanged);
+            Assert.Equal(["before_write"], phases);
+            var structured = partialResponse["result"]!["structuredContent"]!;
+            Assert.Equal(1, structured["summary"]!["errors"]!.GetValue<int>());
+            Assert.Equal(0, structured["summary"]!["purged"]!.GetValue<int>());
+            var failure = Assert.Single(structured["failures"]!.AsArray());
+            Assert.Equal("IParseable.cs", failure!["path"]!.GetValue<string>());
+            Assert.Equal("csharp_prepass", failure["stage"]!.GetValue<string>());
+            using var preservedDb = new DbContext(DbOpenIntent.WriteIndex, dbPath);
+            var preservedReader = new DbReader(preservedDb.Connection);
+            Assert.Equal(priorInterfaceChecksum, preservedReader.GetFileByPath("IParseable.cs")?.Checksum);
+            Assert.Equal(priorImplementationChecksum, preservedReader.GetFileByPath("Money.cs")?.Checksum);
+            Assert.NotNull(preservedReader.GetFileByPath("obsolete.md"));
+            Assert.Equal(1L, CountImplicitReferences(preservedDb));
+            Assert.Null(new DbWriter(preservedDb).GetCSharpStaticInterfaceSourceEvidence());
+            var status = preservedReader.GetStatus();
+            Assert.False(status.IndexComplete);
+            Assert.False(status.GraphDataCurrent);
+
+            static long CountImplicitReferences(DbContext db)
+            {
+                using var command = db.Connection.CreateCommand();
+                command.CommandText = """
+                    SELECT COUNT(*)
+                    FROM symbol_references r
+                    JOIN files f ON f.id = r.file_id
+                    WHERE f.path = 'Money.cs'
+                      AND r.symbol_name = 'Parse'
+                      AND r.reference_kind = 'implicit_implementation'
+                    """;
+                return (long)command.ExecuteScalar()!;
+            }
+        }
+        finally
+        {
+            McpServer.McpIndexInputSnapshotBarrierForTesting = previousBarrierHook;
+            TestProjectHelper.DeleteDirectory(fixtureDir);
+            TestProjectHelper.DeleteSqliteDatabaseFiles(dbPath);
+        }
+    }
+
     [Fact]
     public void ToolsCall_Index_ReadinessBoundaryInPlaceCdidxIgnoreChangeLeavesPartialUntilCleanRetry()
     {
@@ -13199,7 +13311,19 @@ public void ToolsCall_Index_Rebuild_SucceedsOnFreshDb()
         var statSnapshotReads = 0;
         try
         {
-            File.WriteAllText(Path.Combine(fixtureDir, "app.cs"), "public class App { }");
+            File.WriteAllText(
+                Path.Combine(fixtureDir, "app.cs"),
+                """
+                public interface IParseable<T>
+                {
+                    static abstract T Parse(string value);
+                }
+
+                public readonly struct Money : IParseable<Money>
+                {
+                    public static Money Parse(string value) => new();
+                }
+                """);
             using var server = new McpServer(dbPath, ConsoleUi.LoadVersion());
             DbWriter.ReusableStatSnapshotReadForTesting = () => statSnapshotReads++;
             CSharpPrepassSymbolArtifactCache.EventForTesting =
@@ -13228,6 +13352,17 @@ public void ToolsCall_Index_Rebuild_SucceedsOnFreshDb()
             Assert.DoesNotContain(
                 artifactEvents,
                 item => item.Phase is "admitted" or "taken");
+            using var verificationDb = new DbContext(DbOpenIntent.WriteIndex, dbPath);
+            var verificationWriter = new DbWriter(verificationDb);
+            Assert.Equal(true, verificationWriter.GetCSharpStaticInterfaceSourceEvidence());
+            using var implicitReferenceCommand = verificationDb.Connection.CreateCommand();
+            implicitReferenceCommand.CommandText = """
+                SELECT COUNT(*)
+                FROM symbol_references
+                WHERE symbol_name = 'Parse'
+                  AND reference_kind = 'implicit_implementation'
+                """;
+            Assert.Equal(1L, (long)implicitReferenceCommand.ExecuteScalar()!);
         }
         finally
         {

From caab9c406baef1930c75919e1cc11b76fab4686d Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 02:19:07 +0900
Subject: [PATCH 36/45] Decompose CLI batch execution

---
 TESTING_GUIDE.md                              |   4 +-
 src/CodeIndex/Cli/QueryCommandRunner.Batch.cs | 950 +-----------------
 .../Cli/QueryCommandRunner.BatchExecution.cs  | 435 ++++++++
 .../Cli/QueryCommandRunner.BatchFacade.cs     | 197 ++++
 ...eryCommandRunner.BatchParallelExecution.cs | 526 ++++++++++
 .../QueryCommandRunnerBatchIssue4871Tests.cs  | 223 +++-
 6 files changed, 1386 insertions(+), 949 deletions(-)
 create mode 100644 src/CodeIndex/Cli/QueryCommandRunner.BatchExecution.cs
 create mode 100644 src/CodeIndex/Cli/QueryCommandRunner.BatchFacade.cs
 create mode 100644 src/CodeIndex/Cli/QueryCommandRunner.BatchParallelExecution.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index eeae26c4f..772f6ff6b 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -248,7 +248,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   Doctor full-inventory coverage keeps composed filter selection, filtered summary counts, exact UTF-8 byte-budget boundaries, and structured overflow errors together in `ProgramRunnerTests`; license JSON remains a subprocess contract in `ProgramCliTests` so immediate-command dispatch and the published field names are both exercised.
   Ctags export JSON coverage reuses one seeded database for default and `--include-generated` variants, asserts the fixed skip-reason keys sum to `skipped_count`, and keeps the missing-`files.generated` degradation in a separate legacy-schema fixture.
   Dry-run JSON coverage for ambiguous `.h` files locks the bounded `language_detections` entries and their stable source/confidence codes without mutating the index.
-  Batch `--json-summary` coverage keeps side-effect-free dispatch plus successful JSON, single-row NDJSON, and JSON-looking text projection in one seeded fixture when the assertions stay distinct; include case-insensitive format values, command-specific JSON formats, and alias-injected JSON defaults so batch classification cannot drift from child parsers. Serialized-output exhaustion remains a separate boundary fixture because of its large escaped payload. Assert `result` / `results` versus raw `stdout` presence explicitly, compare `output_chars` with the actual captured stream length, and cover repeated malformed lines up to the input cap so neither syntax sniffing nor envelope overhead can bypass the transport bounds. Typed-failure coverage reuses one mixed scalar/array/schema/policy/child-failure input across serial and parallel modes, asserts stable ordered categories, and keeps timeout, caller cancellation, and explicit `--include-raw-streams` behavior in focused fixtures. Cancellation coverage includes pre-cancelled setup, cancellation after an earlier failure and after parallel item preparation, and a blocking stdin reader that proves both prompt wake-up and preservation of an in-flight line for the next batch invocation.
+  Batch `--json-summary` coverage keeps side-effect-free dispatch plus successful JSON, single-row NDJSON, and JSON-looking text projection in one seeded fixture when the assertions stay distinct; include case-insensitive format values, command-specific JSON formats, and alias-injected JSON defaults so batch classification cannot drift from child parsers. Serialized-output exhaustion remains a separate boundary fixture because of its large escaped payload. Assert `result` / `results` versus raw `stdout` presence explicitly, compare `output_chars` with the actual captured stream length, and cover repeated malformed lines up to the input cap so neither syntax sniffing nor envelope overhead can bypass the transport bounds. Typed-failure coverage reuses one mixed scalar/array/schema/policy/child-failure input across serial and parallel modes, asserts stable ordered categories, and keeps timeout, caller cancellation, and explicit `--include-raw-streams` behavior in focused fixtures. Shared line-preparation/accounting coverage compares mixed blank, valid, malformed, and unsupported input across serial and parallel modes, including ordered records, first failure, counters, limits, and output characters. Output-limit drain coverage gates two active workers without sleeps, proves the batch remains pending until the held worker completes, keeps an unpublished input-limit record out of committed counters, and verifies console restoration after the join; blocked-input preservation remains in the focused cancellation fixture. Cancellation coverage includes pre-cancelled setup, cancellation after an earlier failure and after parallel item preparation, and a blocking stdin reader that proves both prompt wake-up and preservation of an in-flight line for the next batch invocation.
   Argument-validation variants that only differ by invalid scalar input share one database fixture and iterate within a fact when no per-case state or discovery identity is required.
   Positional `files` glob coverage shares one indexed-file fixture and iterates `*`, `?`, and recursive `**` patterns in a fact, matching the exact tokens that a quoted shell argument passes to the CLI.
   Excerpt focus coverage reuses one indexed fixture for line-only leading-window behavior, the focus-length dependency, and focus-column range validation; zero and non-numeric focus-column values share one indexed Markdown fixture.
@@ -1314,7 +1314,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   doctor full-inventory coverage では、合成 filter の選択、filtered summary 件数、UTF-8 byte budget の exact boundary、structured overflow error を `ProgramRunnerTests` にまとめます。license JSON は `ProgramCliTests` の subprocess contract として、immediate-command dispatch と公開 field 名を同時に検証します。
   ctags export JSON coverage は1つの seeded database を既定と `--include-generated` variant で再利用し、固定された skip-reason key の合計が `skipped_count` と一致することを検証します。`files.generated` がない場合の縮退は別の legacy-schema fixture に保ってください。
   曖昧な `.h` に対する dry-run JSON coverage は、index を変更せず、上限付き `language_detections` entry と安定した判定元・信頼度 code を固定します。
-  batch `--json-summary` coverage は、assertion を明確に保てる場合、副作用なし dispatch と成功時の JSON / 1 row NDJSON / JSON に見える text projection を1つの seeded fixture で共有し、case-insensitive な format 値、command 固有の JSON format、alias が内部追加する JSON default も含めて child parser と batch classification の drift を防いでください。serialized output の枯渇は escape を多く含む大きな payload の境界 fixture として分離します。test 側で `result` / `results` と raw `stdout` の有無を明示し、`output_chars` を実際に捕捉した stream 長と比較し、input cap までの malformed line 反復も検証して、syntax sniffing や envelope overhead が transport 上限を迂回しないようにしてください。typed failure coverage は scalar / array / schema / policy / child failure を混在させた1つの input を serial / parallel mode で共有し、安定した順序と category を検証してください。timeout、caller cancellation、明示的な `--include-raw-streams` の挙動は焦点を絞った fixture に分離します。cancellation coverage には事前 cancel 済み setup、先行 failure 後と parallel item 準備後の cancellation、blocking stdin reader を含め、型付き summary、迅速な wait 解除、同時に読み取った line が次の batch invocation 用に保持されることを決定的に検証します。
+  batch `--json-summary` coverage は、assertion を明確に保てる場合、副作用なし dispatch と成功時の JSON / 1 row NDJSON / JSON に見える text projection を1つの seeded fixture で共有し、case-insensitive な format 値、command 固有の JSON format、alias が内部追加する JSON default も含めて child parser と batch classification の drift を防いでください。serialized output の枯渇は escape を多く含む大きな payload の境界 fixture として分離します。test 側で `result` / `results` と raw `stdout` の有無を明示し、`output_chars` を実際に捕捉した stream 長と比較し、input cap までの malformed line 反復も検証して、syntax sniffing や envelope overhead が transport 上限を迂回しないようにしてください。typed failure coverage は scalar / array / schema / policy / child failure を混在させた1つの input を serial / parallel mode で共有し、安定した順序と category を検証してください。timeout、caller cancellation、明示的な `--include-raw-streams` の挙動は焦点を絞った fixture に分離します。共有 line preparation / accounting の coverage では blank、valid、malformed、unsupported input の混在を serial / parallel mode で比較し、record 順、first failure、counter、limit、output character 数を固定します。output-limit drain coverage は sleep なしの gate で active worker 2つを保持し、一方の worker が完了するまで batch が pending のままであること、未配送の input-limit record が確定済み counter に混入しないこと、join 後に console が復元されることを検証します。blocked input の保持は focused cancellation fixture に分離してください。cancellation coverage には事前 cancel 済み setup、先行 failure 後と parallel item 準備後の cancellation、blocking stdin reader を含め、型付き summary、迅速な wait 解除、同時に読み取った line が次の batch invocation 用に保持されることを決定的に検証します。
   invalid scalar input だけが異なる argument-validation variant は、case ごとの state や discovery identity が不要なら1つの database fixture を共有し、fact 内で反復してください。
   `files` の positional glob coverage は1つの indexed-file fixture を共有し、quote された shell 引数が CLI に渡す token と同じ `*`、`?`、recursive `**` pattern を fact 内で反復してください。
   excerpt の focus coverage は、line-only 時の先頭側 window、focus-length の依存関係、focus-column の範囲検証を1つの indexed fixture で共有してください。focus-column の zero / non-numeric value も1つの indexed Markdown fixture を再利用してください。
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.Batch.cs b/src/CodeIndex/Cli/QueryCommandRunner.Batch.cs
index 642fe2103..176c74144 100644
--- a/src/CodeIndex/Cli/QueryCommandRunner.Batch.cs
+++ b/src/CodeIndex/Cli/QueryCommandRunner.Batch.cs
@@ -1,4 +1,3 @@
-using System.Globalization;
 using System.Runtime.CompilerServices;
 using System.Text;
 using System.Text.Json;
@@ -12,7 +11,7 @@ namespace CodeIndex.Cli;
 public static partial class QueryCommandRunner
 {
     private const int BatchMaxCapturedOutputChars = JsonEnvelopeWrapper.MaxCapturedOutputChars;
-    private static readonly ConditionalWeakTable<TextReader, BatchInputPump> s_batchInputPumps = new();
+    private static readonly ConditionalWeakTable<TextReader, BatchInputPump> s_batchInputPumps = [];
     internal static Action<int>? BatchParallelCommandStartedForTesting { get; set; }
     internal static Action<int>? BatchParallelCommandCompletedForTesting { get; set; }
     internal static Action<int>? BatchInputLineReadForTesting { get; set; }
@@ -21,943 +20,6 @@ public static partial class QueryCommandRunner
     internal static Func<DbContext, DbReader>? BatchParallelReaderFactoryForTesting { get; set; }
     internal static Action? BatchParallelDatabaseValidatingForTesting { get; set; }
 
-    public static int RunBatch(
-        string[] cmdArgs,
-        JsonSerializerOptions jsonOptions,
-        string appVersion = "",
-        CancellationToken cancellationToken = default)
-    {
-        var dbPath = Path.Combine(".cdidx", "codeindex.db");
-        var dbPathExplicit = false;
-        var jsonSummary = false;
-        var maxInputLines = BatchDefaultInputLines;
-        var maxOutputChars = BatchDefaultTotalOutputChars;
-        var maxOutputCharsSpecified = false;
-        var parallelism = 1;
-        var parallelismSpecified = false;
-        var includeRawStreams = false;
-        for (var i = 0; i < cmdArgs.Length; i++)
-        {
-            var arg = cmdArgs[i];
-            if (arg == "--json-summary")
-            {
-                jsonSummary = true;
-                continue;
-            }
-
-            if (arg == "--include-raw-streams")
-            {
-                includeRawStreams = true;
-                continue;
-            }
-
-            if (arg == "--db")
-            {
-                if (i + 1 >= cmdArgs.Length || string.IsNullOrWhiteSpace(cmdArgs[i + 1]))
-                {
-                    CommandErrorWriter.WriteStderr(BuildMissingOptionValueError("--db"));
-                    return CommandExitCodes.UsageError;
-                }
-                dbPath = cmdArgs[++i];
-                dbPathExplicit = true;
-                continue;
-            }
-
-            if (arg.StartsWith("--db=", StringComparison.Ordinal))
-            {
-                dbPath = arg["--db=".Length..];
-                if (string.IsNullOrWhiteSpace(dbPath))
-                {
-                    CommandErrorWriter.WriteStderr(BuildMissingOptionValueError("--db"));
-                    return CommandExitCodes.UsageError;
-                }
-                dbPathExplicit = true;
-                continue;
-            }
-
-            if (arg == "--max-input-lines" || arg.StartsWith("--max-input-lines=", StringComparison.Ordinal))
-            {
-                if (!TryReadBatchBoundedOption(
-                        cmdArgs,
-                        ref i,
-                        arg,
-                        "--max-input-lines",
-                        1,
-                        BatchMaxInputLines,
-                        out maxInputLines))
-                {
-                    return CommandExitCodes.UsageError;
-                }
-                continue;
-            }
-
-            if (arg == "--max-output-chars" || arg.StartsWith("--max-output-chars=", StringComparison.Ordinal))
-            {
-                if (!TryReadBatchBoundedOption(
-                        cmdArgs,
-                        ref i,
-                        arg,
-                        "--max-output-chars",
-                        BatchMinTotalOutputChars,
-                        BatchMaxTotalOutputChars,
-                        out maxOutputChars))
-                {
-                    return CommandExitCodes.UsageError;
-                }
-                maxOutputCharsSpecified = true;
-                continue;
-            }
-
-            if (arg == "--parallel" || arg.StartsWith("--parallel=", StringComparison.Ordinal))
-            {
-                if (!TryReadBatchBoundedOption(
-                        cmdArgs,
-                        ref i,
-                        arg,
-                        "--parallel",
-                        1,
-                        BatchMaxParallelism,
-                        out parallelism))
-                {
-                    return CommandExitCodes.UsageError;
-                }
-                parallelismSpecified = true;
-                continue;
-            }
-
-            CommandErrorWriter.WriteStderr($"Error: {ConsoleUi.FormatBoundedValue(arg)} is not supported for batch.");
-            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
-            return CommandExitCodes.UsageError;
-        }
-
-        if (parallelismSpecified && !jsonSummary)
-        {
-            CommandErrorWriter.WriteStderr("Error: --parallel requires --json-summary so concurrent child output can be isolated and emitted in input order.");
-            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
-            return CommandExitCodes.UsageError;
-        }
-        if (maxOutputCharsSpecified && !jsonSummary)
-        {
-            CommandErrorWriter.WriteStderr("Error: --max-output-chars requires --json-summary because ordinary batch output streams directly.");
-            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
-            return CommandExitCodes.UsageError;
-        }
-        if (includeRawStreams && !jsonSummary)
-        {
-            CommandErrorWriter.WriteStderr("Error: --include-raw-streams requires --json-summary.");
-            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
-            return CommandExitCodes.UsageError;
-        }
-
-        var isUri = dbPath.StartsWith("file:", StringComparison.OrdinalIgnoreCase);
-        if (!isUri && !File.Exists(dbPath))
-        {
-            CommandErrorWriter.WriteStderr($"Error [{CommandErrorCodes.DbNotFound}]: database not found at {FormatDbDiagnosticValue(Path.GetFullPath(dbPath))}");
-            CommandErrorWriter.WriteStderr("Hint: create or refresh the index with `cdidx index <projectPath>` (or `cdidx .`) and then rerun this command.");
-            return CommandExitCodes.DatabaseError;
-        }
-
-        if (parallelism > 1)
-        {
-            BatchParallelSession? firstSession = null;
-            DbContext? validationDb = null;
-            try
-            {
-                validationDb = new DbContext(DbOpenIntent.QueryOnly, dbPath, cancellationToken);
-                BatchParallelDatabaseValidatingForTesting?.Invoke();
-                if (!validationDb.TryValidateIsCodeIndexDb(out var validationReason))
-                    return WriteInvalidCodeIndexDbError(dbPath, validationReason, json: false, jsonOptions);
-                var transferredDb = validationDb;
-                validationDb = null;
-                firstSession = BatchParallelSession.FromValidated(
-                    dbPath,
-                    transferredDb,
-                    cancellationToken);
-            }
-            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-            {
-                firstSession?.Dispose();
-                return WriteBatchSetupCancellationSummary(
-                    maxInputLines,
-                    maxOutputChars,
-                    parallelism,
-                    jsonOptions);
-            }
-            catch
-            {
-                firstSession?.Dispose();
-                throw;
-            }
-            finally
-            {
-                validationDb?.Dispose();
-            }
-
-            try
-            {
-                return RunBatchParallel(
-                    dbPath,
-                    dbPathExplicit,
-                    maxInputLines,
-                    maxOutputChars,
-                    parallelism,
-                    includeRawStreams,
-                    jsonOptions,
-                    appVersion,
-                    firstSession!,
-                    cancellationToken);
-            }
-            catch
-            {
-                firstSession?.Dispose();
-                throw;
-            }
-        }
-
-        try
-        {
-            using var db = new DbContext(DbOpenIntent.QueryOnly, dbPath, cancellationToken);
-            if (!db.TryValidateIsCodeIndexDb(out var validationReason))
-                return WriteInvalidCodeIndexDbError(dbPath, validationReason, json: false, jsonOptions);
-
-            s_batchReader = new DbReader(db);
-            s_batchDbPath = dbPath;
-            s_batchDbPathExplicit = dbPathExplicit;
-            var jsonOutput = jsonSummary
-                ? new BatchJsonOutputWriter(
-                    Console.Out,
-                    maxOutputChars,
-                    BatchTerminalOutputReserveChars,
-                    jsonOptions)
-                : null;
-            var firstFailure = CommandExitCodes.Success;
-            var lineNumber = 0;
-            var commandsProcessed = 0;
-            var lineErrors = 0;
-            var commandFailures = 0;
-            var outputLimitReached = false;
-            var inputLimitReached = false;
-            var batchInput = GetBatchInputPump(Console.In);
-            while (true)
-            {
-                BatchPumpedLine? pumpedLine;
-                try
-                {
-                    pumpedLine = batchInput.ReadAsync(cancellationToken)
-                        .AsTask()
-                        .GetAwaiter()
-                        .GetResult();
-                }
-                catch (OperationCanceledException) when (
-                    jsonSummary
-                    && cancellationToken.IsCancellationRequested)
-                {
-                    firstFailure = CommandExitCodes.CancelledBySignal;
-                    break;
-                }
-                if (pumpedLine is null)
-                    break;
-
-                var line = pumpedLine.Value.Line;
-                var lineExceededLimit = pumpedLine.Value.ExceededLimit;
-                lineNumber++;
-                BatchInputLineReadForTesting?.Invoke(lineNumber);
-                if (cancellationToken.IsCancellationRequested)
-                {
-                    if (!jsonSummary)
-                        cancellationToken.ThrowIfCancellationRequested();
-
-                    firstFailure = CommandExitCodes.CancelledBySignal;
-                    if (lineExceededLimit || !string.IsNullOrWhiteSpace(line))
-                    {
-                        var lineError = BuildBatchCancellationLineError(lineNumber);
-                        if (!WriteBatchLineErrorJson(lineNumber, lineError, jsonOutput!))
-                        {
-                            WriteBatchOutputLimitErrorJson(
-                                lineNumber,
-                                commandName: null,
-                                CommandExitCodes.CancelledBySignal,
-                                maxOutputChars,
-                                jsonOutput!);
-                            outputLimitReached = true;
-                        }
-                        lineErrors++;
-                    }
-                    break;
-                }
-
-                if (lineNumber > maxInputLines)
-                {
-                    var lineError = new BatchLineError(
-                        $"batch input exceeds the {maxInputLines} line limit.",
-                        CommandExitCodes.UsageError,
-                        Hint: "Split the request into smaller batch invocations.",
-                        ErrorCode: CommandErrorCodes.UsageError,
-                        Category: "batch_input_line_limit");
-                    if (jsonSummary)
-                        jsonOutput!.WriteTerminal(BuildBatchLineErrorJson(lineNumber, lineError));
-                    else
-                        WriteBatchLineErrorDiagnostic(lineError, jsonOptions);
-                    lineErrors++;
-                    inputLimitReached = true;
-                    if (firstFailure == CommandExitCodes.Success)
-                        firstFailure = CommandExitCodes.UsageError;
-                    break;
-                }
-
-                if (lineExceededLimit)
-                {
-                    var lineError = new BatchLineError(
-                        $"batch line {lineNumber} exceeds the {BatchMaxLineChars} character limit.",
-                        CommandExitCodes.UsageError,
-                        Hint: "Split the command across smaller arguments or reduce the input record.",
-                        ErrorCode: CommandErrorCodes.UsageError,
-                        Category: "batch_input_line_length_limit");
-                    if (jsonSummary)
-                    {
-                        if (!WriteBatchLineErrorJson(lineNumber, lineError, jsonOutput!))
-                        {
-                            WriteBatchOutputLimitErrorJson(
-                                lineNumber,
-                                commandName: null,
-                                CommandExitCodes.UsageError,
-                                maxOutputChars,
-                                jsonOutput!);
-                            outputLimitReached = true;
-                        }
-                    }
-                    else
-                        WriteBatchLineErrorDiagnostic(lineError, jsonOptions);
-                    lineErrors++;
-                    if (firstFailure == CommandExitCodes.Success)
-                        firstFailure = CommandExitCodes.UsageError;
-                    if (outputLimitReached)
-                        break;
-                    continue;
-                }
-
-                if (string.IsNullOrWhiteSpace(line))
-                    continue;
-
-                if (!TryParseBatchLine(line, lineNumber, jsonOptions, !jsonSummary, out var commandName, out var subArgs, out var parseExitCode, out var parseError))
-                {
-                    if (jsonSummary)
-                    {
-                        if (!WriteBatchLineErrorJson(
-                                lineNumber,
-                                parseError ?? BuildGenericBatchLineError(lineNumber),
-                                jsonOutput!))
-                        {
-                            WriteBatchOutputLimitErrorJson(
-                                lineNumber,
-                                commandName: null,
-                                parseExitCode,
-                                maxOutputChars,
-                                jsonOutput!);
-                            outputLimitReached = true;
-                        }
-                    }
-                    lineErrors++;
-                    if (firstFailure == CommandExitCodes.Success)
-                        firstFailure = parseExitCode;
-                    if (outputLimitReached)
-                        break;
-                    continue;
-                }
-
-                commandsProcessed++;
-                var batchResult = jsonSummary
-                    ? RunBatchQueryCommandWithJsonRecord(
-                        lineNumber,
-                        commandName,
-                        subArgs,
-                        maxOutputChars,
-                        includeRawStreams,
-                        jsonOutput!,
-                        jsonOptions,
-                        appVersion,
-                        cancellationToken)
-                    : new BatchCommandRunResult(
-                        RunBatchQueryCommand(commandName, subArgs, jsonOptions, appVersion, cancellationToken),
-                        OutputLimitReached: false,
-                        CancellationObserved: false);
-                var exitCode = batchResult.ExitCode;
-                if (exitCode != CommandExitCodes.Success)
-                {
-                    commandFailures++;
-                    if (firstFailure == CommandExitCodes.Success)
-                        firstFailure = exitCode;
-                }
-                if (batchResult.OutputLimitReached)
-                {
-                    outputLimitReached = true;
-                    break;
-                }
-                if (batchResult.CancellationObserved)
-                {
-                    firstFailure = CommandExitCodes.CancelledBySignal;
-                    break;
-                }
-            }
-
-            if (jsonSummary)
-                WriteBatchSummaryJson(
-                    lineNumber,
-                    commandsProcessed,
-                    lineErrors,
-                    commandFailures,
-                    firstFailure,
-                    outputLimitReached,
-                    inputLimitReached,
-                    maxInputLines,
-                    maxOutputChars,
-                    parallelism,
-                    jsonOutput!);
-
-            return firstFailure;
-        }
-        catch (OperationCanceledException) when (
-            jsonSummary
-            && cancellationToken.IsCancellationRequested)
-        {
-            return WriteBatchSetupCancellationSummary(
-                maxInputLines,
-                maxOutputChars,
-                parallelism,
-                jsonOptions);
-        }
-        finally
-        {
-            s_batchReader = null;
-            s_batchDbPath = null;
-            s_batchDbPathExplicit = false;
-        }
-    }
-
-    private static bool TryReadBatchBoundedOption(
-        string[] args,
-        ref int index,
-        string currentArg,
-        string optionName,
-        int minimum,
-        int maximum,
-        out int value)
-    {
-        value = 0;
-        string rawValue;
-        if (currentArg == optionName)
-        {
-            if (index + 1 >= args.Length || string.IsNullOrWhiteSpace(args[index + 1]))
-            {
-                CommandErrorWriter.WriteStderr(BuildMissingOptionValueError(optionName));
-                return false;
-            }
-            rawValue = args[++index];
-        }
-        else
-        {
-            rawValue = currentArg[(optionName.Length + 1)..];
-            if (string.IsNullOrWhiteSpace(rawValue))
-            {
-                CommandErrorWriter.WriteStderr(BuildMissingOptionValueError(optionName));
-                return false;
-            }
-        }
-
-        if (!int.TryParse(rawValue, NumberStyles.None, CultureInfo.InvariantCulture, out value)
-            || value < minimum
-            || value > maximum)
-        {
-            CommandErrorWriter.WriteStderr($"Error: {optionName} must be an integer from {minimum} to {maximum}.");
-            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
-            return false;
-        }
-
-        return true;
-    }
-
-    private static int RunBatchParallel(
-        string dbPath,
-        bool dbPathExplicit,
-        int maxInputLines,
-        int maxOutputChars,
-        int parallelism,
-        bool includeRawStreams,
-        JsonSerializerOptions jsonOptions,
-        string appVersion,
-        BatchParallelSession firstSession,
-        CancellationToken cancellationToken)
-    {
-        var sessions = new BatchParallelSession[parallelism];
-        sessions[0] = firstSession;
-        for (var index = 1; index < sessions.Length; index++)
-            sessions[index] = new BatchParallelSession(dbPath);
-        var availableSessions = new Queue<BatchParallelSession>(sessions);
-        using var consoleOwnership = ConsoleStreamOwnership.Enter();
-        var originalOut = Console.Out;
-        var originalError = Console.Error;
-        var stdoutRouter = new BatchConsoleRouter(originalOut);
-        var stderrRouter = new BatchConsoleRouter(originalError);
-        var jsonOutput = new BatchJsonOutputWriter(
-            originalOut,
-            maxOutputChars,
-            BatchTerminalOutputReserveChars,
-            jsonOptions);
-        var firstFailure = CommandExitCodes.Success;
-        var lineNumber = 0;
-        var commandsProcessed = 0;
-        var lineErrors = 0;
-        var commandFailures = 0;
-        var outputLimitReached = false;
-        var inputLimitReached = false;
-        var cancellationObserved = false;
-        using var stopProducing = new CancellationTokenSource();
-        using var producerCancellation = CancellationTokenSource.CreateLinkedTokenSource(
-            cancellationToken,
-            stopProducing.Token);
-        var batchInput = GetBatchInputPump(Console.In);
-        var input = Channel.CreateBounded<BatchPendingItem>(
-            new BoundedChannelOptions(1)
-            {
-                FullMode = BoundedChannelFullMode.Wait,
-                SingleReader = true,
-                SingleWriter = true,
-            });
-
-        Console.SetOut(stdoutRouter);
-        Console.SetError(stderrRouter);
-        try
-        {
-            var producer = Task.Run(async () =>
-            {
-                try
-                {
-                    while (!stopProducing.IsCancellationRequested)
-                    {
-                        if (cancellationToken.IsCancellationRequested)
-                        {
-                            cancellationObserved = true;
-                            break;
-                        }
-
-                        var pumpedLine = await batchInput.ReadAsync(producerCancellation.Token)
-                            .ConfigureAwait(false);
-                        if (pumpedLine is null)
-                            break;
-
-                        lineNumber++;
-                        BatchInputLineReadForTesting?.Invoke(lineNumber);
-                        if (cancellationToken.IsCancellationRequested)
-                        {
-                            cancellationObserved = true;
-                            if (pumpedLine.Value.ExceededLimit
-                                || !string.IsNullOrWhiteSpace(pumpedLine.Value.Line))
-                            {
-                                await input.Writer.WriteAsync(
-                                        new BatchPendingItem(
-                                            lineNumber,
-                                            null,
-                                            [],
-                                            BuildBatchCancellationLineError(lineNumber),
-                                            Terminal: true),
-                                        stopProducing.Token)
-                                    .ConfigureAwait(false);
-                                lineErrors++;
-                            }
-                            break;
-                        }
-
-                        if (lineNumber > maxInputLines)
-                        {
-                            var lineError = new BatchLineError(
-                                $"batch input exceeds the {maxInputLines} line limit.",
-                                CommandExitCodes.UsageError,
-                                Hint: "Split the request into smaller batch invocations.",
-                                ErrorCode: CommandErrorCodes.UsageError,
-                                Category: "batch_input_line_limit");
-                            await input.Writer.WriteAsync(
-                                    new BatchPendingItem(lineNumber, null, [], lineError, Terminal: true),
-                                    stopProducing.Token)
-                                .ConfigureAwait(false);
-                            lineErrors++;
-                            inputLimitReached = true;
-                            break;
-                        }
-
-                        if (pumpedLine.Value.ExceededLimit)
-                        {
-                            var lineError = new BatchLineError(
-                                $"batch line {lineNumber} exceeds the {BatchMaxLineChars} character limit.",
-                                CommandExitCodes.UsageError,
-                                Hint: "Split the command across smaller arguments or reduce the input record.",
-                                ErrorCode: CommandErrorCodes.UsageError,
-                                Category: "batch_input_line_length_limit");
-                            await input.Writer.WriteAsync(
-                                    new BatchPendingItem(lineNumber, null, [], lineError, Terminal: false),
-                                    stopProducing.Token)
-                                .ConfigureAwait(false);
-                            lineErrors++;
-                            continue;
-                        }
-
-                        var line = pumpedLine.Value.Line;
-                        if (string.IsNullOrWhiteSpace(line))
-                            continue;
-
-                        BatchPendingItem item;
-                        if (!TryParseBatchLine(
-                                line,
-                                lineNumber,
-                                jsonOptions,
-                                writeDiagnostics: false,
-                                out var commandName,
-                                out var subArgs,
-                                out _,
-                                out var parseError))
-                        {
-                            item = new BatchPendingItem(
-                                lineNumber,
-                                null,
-                                [],
-                                parseError ?? BuildGenericBatchLineError(lineNumber),
-                                Terminal: false);
-                            lineErrors++;
-                        }
-                        else
-                        {
-                            item = new BatchPendingItem(
-                                lineNumber,
-                                commandName,
-                                subArgs,
-                                null,
-                                Terminal: false);
-                            commandsProcessed++;
-                        }
-
-                        BatchParallelItemPreparedForTesting?.Invoke(lineNumber);
-                        await input.Writer.WriteAsync(item, stopProducing.Token)
-                            .ConfigureAwait(false);
-                    }
-
-                    input.Writer.TryComplete();
-                }
-                catch (OperationCanceledException) when (producerCancellation.IsCancellationRequested)
-                {
-                    if (cancellationToken.IsCancellationRequested)
-                        cancellationObserved = true;
-                    input.Writer.TryComplete();
-                }
-                catch (Exception ex)
-                {
-                    input.Writer.TryComplete(ex);
-                    throw;
-                }
-            });
-            var active = new Queue<(
-                BatchPendingItem Item,
-                Task<BatchParallelCommandResult?> Result,
-                BatchParallelSession? Session)>();
-
-            try
-            {
-                while (!outputLimitReached)
-                {
-                    while (active.Count < parallelism && input.Reader.TryRead(out var item))
-                    {
-                        BatchParallelSession? session = null;
-                        Task<BatchParallelCommandResult?> result;
-                        if (item.Error is not null)
-                        {
-                            result = Task.FromResult<BatchParallelCommandResult?>(null);
-                        }
-                        else
-                        {
-                            session = availableSessions.Dequeue();
-                            var assignedSession = session;
-                            result = Task.Run<BatchParallelCommandResult?>(
-                                () => RunBatchParallelCommand(
-                                    item.LineNumber,
-                                    item.CommandName!,
-                                    item.Arguments,
-                                    dbPath,
-                                    dbPathExplicit,
-                                    assignedSession,
-                                    stdoutRouter,
-                                    stderrRouter,
-                                    jsonOptions,
-                                    appVersion,
-                                    cancellationToken));
-                        }
-                        active.Enqueue((item, result, session));
-                    }
-
-                    if (active.Count > 0
-                        && (active.Peek().Result.IsCompleted
-                            || active.Count == parallelism
-                            || input.Reader.Completion.IsCompleted))
-                    {
-                        var (item, resultTask, session) = active.Dequeue();
-                        var result = resultTask.GetAwaiter().GetResult();
-                        if (session is not null)
-                            availableSessions.Enqueue(session);
-                        if (item.Error is not null)
-                        {
-                            if (item.Error.ExitCode is CommandExitCodes.CancelledBySignal
-                                or CommandExitCodes.LegacyInterrupted)
-                            {
-                                cancellationObserved = true;
-                            }
-                            if (firstFailure == CommandExitCodes.Success)
-                                firstFailure = item.Error.ExitCode;
-
-                            if (item.Terminal)
-                            {
-                                jsonOutput.WriteTerminal(BuildBatchLineErrorJson(item.LineNumber, item.Error));
-                                continue;
-                            }
-
-                            if (!WriteBatchLineErrorJson(item.LineNumber, item.Error, jsonOutput))
-                            {
-                                WriteBatchOutputLimitErrorJson(
-                                    item.LineNumber,
-                                    commandName: null,
-                                    item.Error.ExitCode,
-                                    maxOutputChars,
-                                    jsonOutput);
-                                outputLimitReached = true;
-                                break;
-                            }
-                            continue;
-                        }
-
-                        if (result is null)
-                        {
-                            throw new InvalidOperationException(
-                                "A parallel batch command completed without a result.");
-                        }
-                        if (WriteBatchCommandRecordJson(
-                                item.LineNumber,
-                                item.CommandName!,
-                                item.Arguments,
-                                result.ExitCode,
-                                result.Stdout,
-                                result.Stderr,
-                                result.Error,
-                                ClassifyBatchOutput(item.CommandName!, item.Arguments),
-                                includeRawStreams,
-                                jsonOutput))
-                        {
-                            if (result.ExitCode != CommandExitCodes.Success)
-                            {
-                                if (result.ExitCode is CommandExitCodes.CancelledBySignal
-                                    or CommandExitCodes.LegacyInterrupted)
-                                {
-                                    cancellationObserved = true;
-                                }
-                                commandFailures++;
-                                if (firstFailure == CommandExitCodes.Success)
-                                    firstFailure = result.ExitCode;
-                            }
-                            continue;
-                        }
-
-                        WriteBatchOutputLimitErrorJson(
-                            item.LineNumber,
-                            item.CommandName,
-                            result.ExitCode,
-                            maxOutputChars,
-                            jsonOutput);
-                        outputLimitReached = true;
-                        commandFailures++;
-                        if (firstFailure == CommandExitCodes.Success)
-                            firstFailure = CommandExitCodes.InvalidArgument;
-                        break;
-                    }
-
-                    if (outputLimitReached)
-                        break;
-                    if (active.Count == 0 && input.Reader.Completion.IsCompleted)
-                        break;
-                    if (active.Count > 0 && active.Peek().Result.IsCompleted)
-                        continue;
-
-                    using var waitCancellation = new CancellationTokenSource();
-                    var waitForInput = input.Reader.WaitToReadAsync(waitCancellation.Token).AsTask();
-                    if (active.Count == 0)
-                    {
-                        if (!waitForInput.GetAwaiter().GetResult())
-                            break;
-                        continue;
-                    }
-
-                    var completed = Task.WhenAny(active.Peek().Result, waitForInput)
-                        .GetAwaiter()
-                        .GetResult();
-                    if (ReferenceEquals(completed, active.Peek().Result))
-                    {
-                        waitCancellation.Cancel();
-                        try
-                        {
-                            waitForInput.GetAwaiter().GetResult();
-                        }
-                        catch (OperationCanceledException) when (waitCancellation.IsCancellationRequested)
-                        {
-                        }
-                    }
-                }
-            }
-            catch
-            {
-                stopProducing.Cancel();
-                while (active.Count > 0)
-                {
-                    try
-                    {
-                        active.Dequeue().Result.GetAwaiter().GetResult();
-                    }
-                    catch
-                    {
-                        // Preserve the first failure while ensuring sibling workers have exited.
-                    }
-                }
-
-                try
-                {
-                    producer.GetAwaiter().GetResult();
-                }
-                catch
-                {
-                    // Preserve the first failure from the consumer or ordered worker.
-                }
-                throw;
-            }
-
-            if (outputLimitReached)
-            {
-                stopProducing.Cancel();
-                while (active.Count > 0)
-                    active.Dequeue().Result.GetAwaiter().GetResult();
-            }
-
-            try
-            {
-                producer.GetAwaiter().GetResult();
-            }
-            catch (OperationCanceledException) when (
-                outputLimitReached
-                && !cancellationToken.IsCancellationRequested)
-            {
-            }
-
-            if (cancellationObserved)
-                firstFailure = CommandExitCodes.CancelledBySignal;
-
-            WriteBatchSummaryJson(
-                lineNumber,
-                commandsProcessed,
-                lineErrors,
-                commandFailures,
-                firstFailure,
-                outputLimitReached,
-                inputLimitReached,
-                maxInputLines,
-                maxOutputChars,
-                parallelism,
-                jsonOutput);
-            return firstFailure;
-        }
-        finally
-        {
-            try
-            {
-                foreach (var session in sessions)
-                    session.Dispose();
-            }
-            finally
-            {
-                ConsoleStreamOwnership.Restore(originalOut, originalError);
-            }
-        }
-    }
-
-    private static BatchParallelCommandResult RunBatchParallelCommand(
-        int lineNumber,
-        string commandName,
-        string[] subArgs,
-        string dbPath,
-        bool dbPathExplicit,
-        BatchParallelSession session,
-        BatchConsoleRouter stdoutRouter,
-        BatchConsoleRouter stderrRouter,
-        JsonSerializerOptions jsonOptions,
-        string appVersion,
-        CancellationToken cancellationToken)
-    {
-        using var stdout = new BatchBoundedStringWriter(BatchMaxCapturedOutputChars, "stdout");
-        using var stderr = new BatchBoundedStringWriter(BatchMaxCapturedOutputChars, "stderr");
-        using var stdoutRouterRegistration = ScopedConsoleOutput.Register(stdoutRouter);
-        using var stderrRouterRegistration = ScopedConsoleError.Register(stderrRouter);
-        using var stdoutScope = stdoutRouter.Push(stdout);
-        using var stderrScope = stderrRouter.Push(stderr);
-        var exitCode = CommandExitCodes.DatabaseError;
-        JsonObject? error = null;
-        try
-        {
-            cancellationToken.ThrowIfCancellationRequested();
-            if (!session.TryGetReader(cancellationToken, out var reader, out var validationReason))
-            {
-                exitCode = WriteInvalidCodeIndexDbError(dbPath, validationReason, json: false, jsonOptions);
-            }
-            else
-            {
-                s_batchReader = reader;
-                s_batchDbPath = dbPath;
-                s_batchDbPathExplicit = dbPathExplicit;
-                BatchParallelCommandStartedForTesting?.Invoke(lineNumber);
-                cancellationToken.ThrowIfCancellationRequested();
-                exitCode = RunBatchQueryCommand(commandName, subArgs, jsonOptions, appVersion, cancellationToken);
-                BatchParallelCommandCompletedForTesting?.Invoke(lineNumber);
-            }
-        }
-        catch (BatchOutputCaptureLimitExceededException ex)
-        {
-            exitCode = CommandExitCodes.InvalidArgument;
-            error = BuildBatchCaptureLimitError(ex);
-        }
-        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-        {
-            exitCode = CommandExitCodes.CancelledBySignal;
-            error = BuildBatchCancellationError();
-        }
-        catch (TimeoutException)
-        {
-            exitCode = CommandExitCodes.RuntimeError;
-            error = BuildBatchTimeoutError();
-        }
-        catch (Exception ex)
-        {
-            exitCode = CommandExitCodes.RuntimeError;
-            error = BuildBatchTypedError(
-                "batch command failed without affecting other batch items.",
-                exitCode,
-                "Retry the item directly if command-specific diagnostics are required.",
-                CommandErrorCodes.CommandFailed,
-                SafeDiagnosticFormatter.FormatCategoryType(
-                    "batch_command_failure",
-                    ex.GetType().Name),
-                "command");
-        }
-        finally
-        {
-            s_batchReader = null;
-            s_batchDbPath = null;
-            s_batchDbPathExplicit = false;
-            s_activeQueryProjectRoot = null;
-        }
-
-        return new BatchParallelCommandResult(exitCode, stdout.ToString(), stderr.ToString(), error);
-    }
-
     private static void WriteBatchSummaryJson(
         int inputLinesRead,
         int commandsProcessed,
@@ -1643,7 +705,7 @@ private static bool TryParseBatchLine(
             }
 
             commandName = values[0];
-            subArgs = values.Skip(1).ToArray();
+            subArgs = [.. values.Skip(1)];
             return true;
         }
         catch (Exception ex) when (ex is JsonException or InvalidDataException)
@@ -1762,7 +824,7 @@ private static bool TryParseBatchCommandObject(
             values.Add(value);
         }
 
-        subArgs = values.ToArray();
+        subArgs = [.. values];
         return true;
     }
 
@@ -1868,12 +930,12 @@ private sealed record BatchLineError(
         string? Category = null,
         bool WriteAsJson = false);
 
-    private sealed record BatchCommandRunResult(
+    private readonly record struct BatchCommandRunResult(
         int ExitCode,
         bool OutputLimitReached,
         bool CancellationObserved);
 
-    private sealed record BatchPendingItem(
+    private readonly record struct BatchPendingItem(
         int LineNumber,
         string? CommandName,
         string[] Arguments,
@@ -1938,7 +1000,7 @@ private void Pump(TextReader reader)
 
     private readonly record struct BatchPumpedLine(string? Line, bool ExceededLimit);
 
-    private sealed record BatchParallelCommandResult(
+    private readonly record struct BatchParallelCommandResult(
         int ExitCode,
         string Stdout,
         string Stderr,
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.BatchExecution.cs b/src/CodeIndex/Cli/QueryCommandRunner.BatchExecution.cs
new file mode 100644
index 000000000..ac1f497f1
--- /dev/null
+++ b/src/CodeIndex/Cli/QueryCommandRunner.BatchExecution.cs
@@ -0,0 +1,435 @@
+using System.Text.Json;
+using CodeIndex.Database;
+
+namespace CodeIndex.Cli;
+
+public static partial class QueryCommandRunner
+{
+    private static int ExecuteBatch(
+        in BatchExecutionPlan plan,
+        JsonSerializerOptions jsonOptions,
+        string appVersion,
+        CancellationToken cancellationToken)
+    {
+        if (plan.Parallelism > 1)
+        {
+            BatchParallelSession? firstSession = null;
+            DbContext? validationDb = null;
+            try
+            {
+                validationDb = new DbContext(DbOpenIntent.QueryOnly, plan.DbPath, cancellationToken);
+                BatchParallelDatabaseValidatingForTesting?.Invoke();
+                if (!validationDb.TryValidateIsCodeIndexDb(out var validationReason))
+                    return WriteInvalidCodeIndexDbError(plan.DbPath, validationReason, json: false, jsonOptions);
+                var transferredDb = validationDb;
+                validationDb = null;
+                firstSession = BatchParallelSession.FromValidated(
+                    plan.DbPath,
+                    transferredDb,
+                    cancellationToken);
+            }
+            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+            {
+                firstSession?.Dispose();
+                return WriteBatchSetupCancellationSummary(
+                    plan.MaxInputLines,
+                    plan.MaxOutputChars,
+                    plan.Parallelism,
+                    jsonOptions);
+            }
+            catch
+            {
+                firstSession?.Dispose();
+                throw;
+            }
+            finally
+            {
+                validationDb?.Dispose();
+            }
+
+            try
+            {
+                return RunBatchParallel(
+                    plan,
+                    jsonOptions,
+                    appVersion,
+                    firstSession!,
+                    cancellationToken);
+            }
+            catch
+            {
+                firstSession?.Dispose();
+                throw;
+            }
+        }
+
+        return RunBatchSerial(in plan, jsonOptions, appVersion, cancellationToken);
+    }
+
+    private static int RunBatchSerial(
+        in BatchExecutionPlan plan,
+        JsonSerializerOptions jsonOptions,
+        string appVersion,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            using var db = new DbContext(DbOpenIntent.QueryOnly, plan.DbPath, cancellationToken);
+            if (!db.TryValidateIsCodeIndexDb(out var validationReason))
+                return WriteInvalidCodeIndexDbError(plan.DbPath, validationReason, json: false, jsonOptions);
+
+            s_batchReader = new DbReader(db);
+            s_batchDbPath = plan.DbPath;
+            s_batchDbPathExplicit = plan.DbPathExplicit;
+            var jsonOutput = plan.JsonSummary
+                ? new BatchJsonOutputWriter(
+                    Console.Out,
+                    plan.MaxOutputChars,
+                    BatchTerminalOutputReserveChars,
+                    jsonOptions)
+                : null;
+            var state = new BatchExecutionState();
+            var batchInput = GetBatchInputPump(Console.In);
+            while (true)
+            {
+                BatchPumpedLine? pumpedLine;
+                try
+                {
+                    pumpedLine = batchInput.ReadAsync(cancellationToken)
+                        .AsTask()
+                        .GetAwaiter()
+                        .GetResult();
+                }
+                catch (OperationCanceledException) when (
+                    plan.JsonSummary
+                    && cancellationToken.IsCancellationRequested)
+                {
+                    state.FirstFailure = CommandExitCodes.CancelledBySignal;
+                    state.CancellationObserved = true;
+                    break;
+                }
+                if (pumpedLine is null)
+                    break;
+
+                var currentLine = pumpedLine.Value;
+                var preparation = PrepareBatchLine(
+                    in currentLine,
+                    in plan,
+                    state,
+                    jsonOptions,
+                    writeDiagnostics: !plan.JsonSummary,
+                    cancellationToken,
+                    out var item);
+                switch (preparation)
+                {
+                    case BatchLinePreparationKind.Blank:
+                        continue;
+
+                    case BatchLinePreparationKind.CancellationWithoutRecord:
+                        state.FirstFailure = CommandExitCodes.CancelledBySignal;
+                        break;
+
+                    case BatchLinePreparationKind.CancellationRecord:
+                        state.FirstFailure = CommandExitCodes.CancelledBySignal;
+                        if (!WriteBatchLineErrorJson(item.LineNumber, item.Error!, jsonOutput!))
+                        {
+                            WriteBatchOutputLimitErrorJson(
+                                item.LineNumber,
+                                commandName: null,
+                                CommandExitCodes.CancelledBySignal,
+                                plan.MaxOutputChars,
+                                jsonOutput!);
+                            state.OutputLimitReached = true;
+                        }
+                        RecordPreparedBatchLine(state, preparation);
+                        break;
+
+                    case BatchLinePreparationKind.InputLimit:
+                        if (plan.JsonSummary)
+                            jsonOutput!.WriteTerminal(BuildBatchLineErrorJson(item.LineNumber, item.Error!));
+                        else
+                            WriteBatchLineErrorDiagnostic(item.Error!, jsonOptions);
+                        RecordPreparedBatchLine(state, preparation);
+                        RecordBatchFirstFailure(state, CommandExitCodes.UsageError);
+                        break;
+
+                    case BatchLinePreparationKind.LineLengthError:
+                        if (plan.JsonSummary)
+                        {
+                            if (!WriteBatchLineErrorJson(item.LineNumber, item.Error!, jsonOutput!))
+                            {
+                                WriteBatchOutputLimitErrorJson(
+                                    item.LineNumber,
+                                    commandName: null,
+                                    CommandExitCodes.UsageError,
+                                    plan.MaxOutputChars,
+                                    jsonOutput!);
+                                state.OutputLimitReached = true;
+                            }
+                        }
+                        else
+                        {
+                            WriteBatchLineErrorDiagnostic(item.Error!, jsonOptions);
+                        }
+                        RecordPreparedBatchLine(state, preparation);
+                        RecordBatchFirstFailure(state, CommandExitCodes.UsageError);
+                        if (state.OutputLimitReached)
+                            break;
+                        continue;
+
+                    case BatchLinePreparationKind.ParseError:
+                        if (plan.JsonSummary
+                            && !WriteBatchLineErrorJson(item.LineNumber, item.Error!, jsonOutput!))
+                        {
+                            WriteBatchOutputLimitErrorJson(
+                                item.LineNumber,
+                                commandName: null,
+                                item.Error!.ExitCode,
+                                plan.MaxOutputChars,
+                                jsonOutput!);
+                            state.OutputLimitReached = true;
+                        }
+                        RecordPreparedBatchLine(state, preparation);
+                        RecordBatchFirstFailure(state, item.Error!.ExitCode);
+                        if (state.OutputLimitReached)
+                            break;
+                        continue;
+
+                    case BatchLinePreparationKind.Command:
+                        RecordPreparedBatchLine(state, preparation);
+                        break;
+
+                    default:
+                        throw new InvalidOperationException(
+                            $"Unknown batch line preparation kind '{preparation}'.");
+                }
+
+                if (preparation != BatchLinePreparationKind.Command)
+                    break;
+
+                var batchResult = plan.JsonSummary
+                    ? RunBatchQueryCommandWithJsonRecord(
+                        item.LineNumber,
+                        item.CommandName!,
+                        item.Arguments,
+                        plan.MaxOutputChars,
+                        plan.IncludeRawStreams,
+                        jsonOutput!,
+                        jsonOptions,
+                        appVersion,
+                        cancellationToken)
+                    : new BatchCommandRunResult(
+                        RunBatchQueryCommand(
+                            item.CommandName!,
+                            item.Arguments,
+                            jsonOptions,
+                            appVersion,
+                            cancellationToken),
+                        OutputLimitReached: false,
+                        CancellationObserved: false);
+                if (batchResult.ExitCode != CommandExitCodes.Success)
+                {
+                    state.CommandFailures++;
+                    RecordBatchFirstFailure(state, batchResult.ExitCode);
+                }
+                if (batchResult.OutputLimitReached)
+                {
+                    state.OutputLimitReached = true;
+                    break;
+                }
+                if (batchResult.CancellationObserved)
+                {
+                    state.FirstFailure = CommandExitCodes.CancelledBySignal;
+                    break;
+                }
+            }
+
+            if (plan.JsonSummary)
+            {
+                WriteBatchSummaryJson(
+                    state.InputLinesRead,
+                    state.CommandsProcessed,
+                    state.LineErrors,
+                    state.CommandFailures,
+                    state.FirstFailure,
+                    state.OutputLimitReached,
+                    state.InputLimitReached,
+                    plan.MaxInputLines,
+                    plan.MaxOutputChars,
+                    plan.Parallelism,
+                    jsonOutput!);
+            }
+
+            return state.FirstFailure;
+        }
+        catch (OperationCanceledException) when (
+            plan.JsonSummary
+            && cancellationToken.IsCancellationRequested)
+        {
+            return WriteBatchSetupCancellationSummary(
+                plan.MaxInputLines,
+                plan.MaxOutputChars,
+                plan.Parallelism,
+                jsonOptions);
+        }
+        finally
+        {
+            s_batchReader = null;
+            s_batchDbPath = null;
+            s_batchDbPathExplicit = false;
+        }
+    }
+
+    private static BatchLinePreparationKind PrepareBatchLine(
+        in BatchPumpedLine pumpedLine,
+        in BatchExecutionPlan plan,
+        BatchExecutionState state,
+        JsonSerializerOptions jsonOptions,
+        bool writeDiagnostics,
+        CancellationToken cancellationToken,
+        out BatchPendingItem item)
+    {
+        state.InputLinesRead++;
+        BatchInputLineReadForTesting?.Invoke(state.InputLinesRead);
+        if (cancellationToken.IsCancellationRequested)
+        {
+            if (!plan.JsonSummary)
+                cancellationToken.ThrowIfCancellationRequested();
+
+            state.CancellationObserved = true;
+            if (pumpedLine.ExceededLimit || !string.IsNullOrWhiteSpace(pumpedLine.Line))
+            {
+                item = new BatchPendingItem(
+                    state.InputLinesRead,
+                    null,
+                    [],
+                    BuildBatchCancellationLineError(state.InputLinesRead),
+                    Terminal: true);
+                return BatchLinePreparationKind.CancellationRecord;
+            }
+
+            item = default;
+            return BatchLinePreparationKind.CancellationWithoutRecord;
+        }
+
+        if (state.InputLinesRead > plan.MaxInputLines)
+        {
+            var lineError = new BatchLineError(
+                $"batch input exceeds the {plan.MaxInputLines} line limit.",
+                CommandExitCodes.UsageError,
+                Hint: "Split the request into smaller batch invocations.",
+                ErrorCode: CommandErrorCodes.UsageError,
+                Category: "batch_input_line_limit");
+            item = new BatchPendingItem(
+                state.InputLinesRead,
+                null,
+                [],
+                lineError,
+                Terminal: true);
+            return BatchLinePreparationKind.InputLimit;
+        }
+
+        if (pumpedLine.ExceededLimit)
+        {
+            var lineError = new BatchLineError(
+                $"batch line {state.InputLinesRead} exceeds the {BatchMaxLineChars} character limit.",
+                CommandExitCodes.UsageError,
+                Hint: "Split the command across smaller arguments or reduce the input record.",
+                ErrorCode: CommandErrorCodes.UsageError,
+                Category: "batch_input_line_length_limit");
+            item = new BatchPendingItem(
+                state.InputLinesRead,
+                null,
+                [],
+                lineError,
+                Terminal: false);
+            return BatchLinePreparationKind.LineLengthError;
+        }
+
+        if (string.IsNullOrWhiteSpace(pumpedLine.Line))
+        {
+            item = default;
+            return BatchLinePreparationKind.Blank;
+        }
+
+        if (!TryParseBatchLine(
+                pumpedLine.Line,
+                state.InputLinesRead,
+                jsonOptions,
+                writeDiagnostics,
+                out var commandName,
+                out var subArgs,
+                out _,
+                out var parseError))
+        {
+            item = new BatchPendingItem(
+                state.InputLinesRead,
+                null,
+                [],
+                parseError ?? BuildGenericBatchLineError(state.InputLinesRead),
+                Terminal: false);
+            return BatchLinePreparationKind.ParseError;
+        }
+
+        item = new BatchPendingItem(
+            state.InputLinesRead,
+            commandName,
+            subArgs,
+            null,
+            Terminal: false);
+        return BatchLinePreparationKind.Command;
+    }
+
+    private static void RecordPreparedBatchLine(
+        BatchExecutionState state,
+        BatchLinePreparationKind preparation)
+    {
+        if (preparation == BatchLinePreparationKind.Command)
+        {
+            state.CommandsProcessed++;
+            return;
+        }
+
+        state.LineErrors++;
+        if (preparation == BatchLinePreparationKind.InputLimit)
+            state.InputLimitReached = true;
+    }
+
+    private static void RecordBatchFirstFailure(BatchExecutionState state, int exitCode)
+    {
+        if (state.FirstFailure == CommandExitCodes.Success)
+            state.FirstFailure = exitCode;
+    }
+
+    private readonly record struct BatchExecutionPlan(
+        string DbPath,
+        bool DbPathExplicit,
+        bool JsonSummary,
+        int MaxInputLines,
+        int MaxOutputChars,
+        int Parallelism,
+        bool IncludeRawStreams);
+
+    private sealed class BatchExecutionState
+    {
+        public int InputLinesRead { get; set; }
+        public int CommandsProcessed { get; set; }
+        public int LineErrors { get; set; }
+        public int CommandFailures { get; set; }
+        public int FirstFailure { get; set; } = CommandExitCodes.Success;
+        public bool OutputLimitReached { get; set; }
+        public bool InputLimitReached { get; set; }
+        public bool CancellationObserved { get; set; }
+    }
+
+    private enum BatchLinePreparationKind
+    {
+        Blank,
+        Command,
+        ParseError,
+        LineLengthError,
+        InputLimit,
+        CancellationWithoutRecord,
+        CancellationRecord,
+    }
+}
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.BatchFacade.cs b/src/CodeIndex/Cli/QueryCommandRunner.BatchFacade.cs
new file mode 100644
index 000000000..b7e2fd181
--- /dev/null
+++ b/src/CodeIndex/Cli/QueryCommandRunner.BatchFacade.cs
@@ -0,0 +1,197 @@
+using System.Globalization;
+using System.Text.Json;
+using CodeIndex.Diagnostics;
+
+namespace CodeIndex.Cli;
+
+public static partial class QueryCommandRunner
+{
+    public static int RunBatch(
+        string[] cmdArgs,
+        JsonSerializerOptions jsonOptions,
+        string appVersion = "",
+        CancellationToken cancellationToken = default)
+    {
+        var dbPath = Path.Combine(".cdidx", "codeindex.db");
+        var dbPathExplicit = false;
+        var jsonSummary = false;
+        var maxInputLines = BatchDefaultInputLines;
+        var maxOutputChars = BatchDefaultTotalOutputChars;
+        var maxOutputCharsSpecified = false;
+        var parallelism = 1;
+        var parallelismSpecified = false;
+        var includeRawStreams = false;
+        for (var i = 0; i < cmdArgs.Length; i++)
+        {
+            var arg = cmdArgs[i];
+            if (arg == "--json-summary")
+            {
+                jsonSummary = true;
+                continue;
+            }
+
+            if (arg == "--include-raw-streams")
+            {
+                includeRawStreams = true;
+                continue;
+            }
+
+            if (arg == "--db")
+            {
+                if (i + 1 >= cmdArgs.Length || string.IsNullOrWhiteSpace(cmdArgs[i + 1]))
+                {
+                    CommandErrorWriter.WriteStderr(BuildMissingOptionValueError("--db"));
+                    return CommandExitCodes.UsageError;
+                }
+                dbPath = cmdArgs[++i];
+                dbPathExplicit = true;
+                continue;
+            }
+
+            if (arg.StartsWith("--db=", StringComparison.Ordinal))
+            {
+                dbPath = arg["--db=".Length..];
+                if (string.IsNullOrWhiteSpace(dbPath))
+                {
+                    CommandErrorWriter.WriteStderr(BuildMissingOptionValueError("--db"));
+                    return CommandExitCodes.UsageError;
+                }
+                dbPathExplicit = true;
+                continue;
+            }
+
+            if (arg == "--max-input-lines" || arg.StartsWith("--max-input-lines=", StringComparison.Ordinal))
+            {
+                if (!TryReadBatchBoundedOption(
+                        cmdArgs,
+                        ref i,
+                        arg,
+                        "--max-input-lines",
+                        1,
+                        BatchMaxInputLines,
+                        out maxInputLines))
+                {
+                    return CommandExitCodes.UsageError;
+                }
+                continue;
+            }
+
+            if (arg == "--max-output-chars" || arg.StartsWith("--max-output-chars=", StringComparison.Ordinal))
+            {
+                if (!TryReadBatchBoundedOption(
+                        cmdArgs,
+                        ref i,
+                        arg,
+                        "--max-output-chars",
+                        BatchMinTotalOutputChars,
+                        BatchMaxTotalOutputChars,
+                        out maxOutputChars))
+                {
+                    return CommandExitCodes.UsageError;
+                }
+                maxOutputCharsSpecified = true;
+                continue;
+            }
+
+            if (arg == "--parallel" || arg.StartsWith("--parallel=", StringComparison.Ordinal))
+            {
+                if (!TryReadBatchBoundedOption(
+                        cmdArgs,
+                        ref i,
+                        arg,
+                        "--parallel",
+                        1,
+                        BatchMaxParallelism,
+                        out parallelism))
+                {
+                    return CommandExitCodes.UsageError;
+                }
+                parallelismSpecified = true;
+                continue;
+            }
+
+            CommandErrorWriter.WriteStderr($"Error: {ConsoleUi.FormatBoundedValue(arg)} is not supported for batch.");
+            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
+            return CommandExitCodes.UsageError;
+        }
+
+        if (parallelismSpecified && !jsonSummary)
+        {
+            CommandErrorWriter.WriteStderr("Error: --parallel requires --json-summary so concurrent child output can be isolated and emitted in input order.");
+            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
+            return CommandExitCodes.UsageError;
+        }
+        if (maxOutputCharsSpecified && !jsonSummary)
+        {
+            CommandErrorWriter.WriteStderr("Error: --max-output-chars requires --json-summary because ordinary batch output streams directly.");
+            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
+            return CommandExitCodes.UsageError;
+        }
+        if (includeRawStreams && !jsonSummary)
+        {
+            CommandErrorWriter.WriteStderr("Error: --include-raw-streams requires --json-summary.");
+            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
+            return CommandExitCodes.UsageError;
+        }
+
+        var isUri = dbPath.StartsWith("file:", StringComparison.OrdinalIgnoreCase);
+        if (!isUri && !File.Exists(dbPath))
+        {
+            CommandErrorWriter.WriteStderr($"Error [{CommandErrorCodes.DbNotFound}]: database not found at {FormatDbDiagnosticValue(Path.GetFullPath(dbPath))}");
+            CommandErrorWriter.WriteStderr("Hint: create or refresh the index with `cdidx index <projectPath>` (or `cdidx .`) and then rerun this command.");
+            return CommandExitCodes.DatabaseError;
+        }
+
+        var plan = new BatchExecutionPlan(
+            dbPath,
+            dbPathExplicit,
+            jsonSummary,
+            maxInputLines,
+            maxOutputChars,
+            parallelism,
+            includeRawStreams);
+        return ExecuteBatch(in plan, jsonOptions, appVersion, cancellationToken);
+    }
+
+    private static bool TryReadBatchBoundedOption(
+        string[] args,
+        ref int index,
+        string currentArg,
+        string optionName,
+        int minimum,
+        int maximum,
+        out int value)
+    {
+        value = 0;
+        string rawValue;
+        if (currentArg == optionName)
+        {
+            if (index + 1 >= args.Length || string.IsNullOrWhiteSpace(args[index + 1]))
+            {
+                CommandErrorWriter.WriteStderr(BuildMissingOptionValueError(optionName));
+                return false;
+            }
+            rawValue = args[++index];
+        }
+        else
+        {
+            rawValue = currentArg[(optionName.Length + 1)..];
+            if (string.IsNullOrWhiteSpace(rawValue))
+            {
+                CommandErrorWriter.WriteStderr(BuildMissingOptionValueError(optionName));
+                return false;
+            }
+        }
+
+        if (!int.TryParse(rawValue, NumberStyles.None, CultureInfo.InvariantCulture, out value)
+            || value < minimum
+            || value > maximum)
+        {
+            CommandErrorWriter.WriteStderr($"Error: {optionName} must be an integer from {minimum} to {maximum}.");
+            CommandErrorWriter.WriteStderr($"Usage: {ConsoleUi.GetUsageLine("batch")}");
+            return false;
+        }
+
+        return true;
+    }
+}
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.BatchParallelExecution.cs b/src/CodeIndex/Cli/QueryCommandRunner.BatchParallelExecution.cs
new file mode 100644
index 000000000..073209b55
--- /dev/null
+++ b/src/CodeIndex/Cli/QueryCommandRunner.BatchParallelExecution.cs
@@ -0,0 +1,526 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using System.Threading.Channels;
+using CodeIndex.Diagnostics;
+
+namespace CodeIndex.Cli;
+
+public static partial class QueryCommandRunner
+{
+    private static int RunBatchParallel(
+        BatchExecutionPlan plan,
+        JsonSerializerOptions jsonOptions,
+        string appVersion,
+        BatchParallelSession firstSession,
+        CancellationToken cancellationToken)
+    {
+        var sessions = new BatchParallelSession[plan.Parallelism];
+        sessions[0] = firstSession;
+        for (var index = 1; index < sessions.Length; index++)
+            sessions[index] = new BatchParallelSession(plan.DbPath);
+        var availableSessions = new Queue<BatchParallelSession>(sessions);
+        using var consoleOwnership = ConsoleStreamOwnership.Enter();
+        var originalOut = Console.Out;
+        var originalError = Console.Error;
+        var stdoutRouter = new BatchConsoleRouter(originalOut);
+        var stderrRouter = new BatchConsoleRouter(originalError);
+        var jsonOutput = new BatchJsonOutputWriter(
+            originalOut,
+            plan.MaxOutputChars,
+            BatchTerminalOutputReserveChars,
+            jsonOptions);
+        var state = new BatchExecutionState();
+        using var stopProducing = new CancellationTokenSource();
+        using var producerCancellation = CancellationTokenSource.CreateLinkedTokenSource(
+            cancellationToken,
+            stopProducing.Token);
+        var batchInput = GetBatchInputPump(Console.In);
+        var input = Channel.CreateBounded<BatchPendingItem>(
+            new BoundedChannelOptions(1)
+            {
+                FullMode = BoundedChannelFullMode.Wait,
+                SingleReader = true,
+                SingleWriter = true,
+            });
+
+        Console.SetOut(stdoutRouter);
+        Console.SetError(stderrRouter);
+        try
+        {
+            var producerPlan = new BatchParallelProducerPlan(
+                plan,
+                jsonOptions,
+                state,
+                batchInput,
+                input.Writer,
+                stopProducing.Token,
+                producerCancellation.Token,
+                cancellationToken);
+            var producer = Task.Run(() => ProduceBatchItemsAsync(producerPlan), cancellationToken);
+            var active = new Queue<BatchActiveItem>();
+            var consumerPlan = new BatchParallelConsumerPlan(
+                plan,
+                jsonOptions,
+                appVersion,
+                availableSessions,
+                new BatchParallelOutputServices(stdoutRouter, stderrRouter, jsonOutput),
+                state,
+                cancellationToken);
+
+            try
+            {
+                ConsumeBatchItemsInOrder(in consumerPlan, input.Reader, active);
+            }
+            catch
+            {
+                stopProducing.Cancel();
+                DrainBatchWorkers(active, preserveEarlierFailure: true);
+
+                try
+                {
+                    producer.GetAwaiter().GetResult();
+                }
+                catch
+                {
+                    // Preserve the first failure from the consumer or ordered worker.
+                }
+                throw;
+            }
+
+            if (state.OutputLimitReached)
+            {
+                stopProducing.Cancel();
+                DrainBatchWorkers(active, preserveEarlierFailure: false);
+            }
+
+            try
+            {
+                producer.GetAwaiter().GetResult();
+            }
+            catch (OperationCanceledException) when (
+                state.OutputLimitReached
+                && !cancellationToken.IsCancellationRequested)
+            {
+            }
+
+            if (state.CancellationObserved)
+                state.FirstFailure = CommandExitCodes.CancelledBySignal;
+
+            WriteBatchSummaryJson(
+                state.InputLinesRead,
+                state.CommandsProcessed,
+                state.LineErrors,
+                state.CommandFailures,
+                state.FirstFailure,
+                state.OutputLimitReached,
+                state.InputLimitReached,
+                plan.MaxInputLines,
+                plan.MaxOutputChars,
+                plan.Parallelism,
+                jsonOutput);
+            return state.FirstFailure;
+        }
+        finally
+        {
+            try
+            {
+                foreach (var session in sessions)
+                    session.Dispose();
+            }
+            finally
+            {
+                ConsoleStreamOwnership.Restore(originalOut, originalError);
+            }
+        }
+    }
+
+    private static async Task ProduceBatchItemsAsync(BatchParallelProducerPlan producer)
+    {
+        var plan = producer.ExecutionPlan;
+        try
+        {
+            while (!producer.StopToken.IsCancellationRequested)
+            {
+                if (producer.CallerToken.IsCancellationRequested)
+                {
+                    producer.State.CancellationObserved = true;
+                    break;
+                }
+
+                var pumpedLine = await producer.Input.ReadAsync(producer.ReadToken)
+                    .ConfigureAwait(false);
+                if (pumpedLine is null)
+                    break;
+
+                var currentLine = pumpedLine.Value;
+                var preparation = PrepareBatchLine(
+                    in currentLine,
+                    in plan,
+                    producer.State,
+                    producer.JsonOptions,
+                    writeDiagnostics: false,
+                    producer.CallerToken,
+                    out var item);
+                switch (preparation)
+                {
+                    case BatchLinePreparationKind.Blank:
+                        continue;
+
+                    case BatchLinePreparationKind.CancellationWithoutRecord:
+                        break;
+
+                    case BatchLinePreparationKind.CancellationRecord:
+                    case BatchLinePreparationKind.InputLimit:
+                        await producer.Output.WriteAsync(item, producer.StopToken)
+                            .ConfigureAwait(false);
+                        RecordPreparedBatchLine(producer.State, preparation);
+                        break;
+
+                    case BatchLinePreparationKind.LineLengthError:
+                        await producer.Output.WriteAsync(item, producer.StopToken)
+                            .ConfigureAwait(false);
+                        RecordPreparedBatchLine(producer.State, preparation);
+                        continue;
+
+                    case BatchLinePreparationKind.ParseError:
+                    case BatchLinePreparationKind.Command:
+                        RecordPreparedBatchLine(producer.State, preparation);
+                        BatchParallelItemPreparedForTesting?.Invoke(item.LineNumber);
+                        await producer.Output.WriteAsync(item, producer.StopToken)
+                            .ConfigureAwait(false);
+                        continue;
+
+                    default:
+                        throw new InvalidOperationException(
+                            $"Unknown batch line preparation kind '{preparation}'.");
+                }
+
+                break;
+            }
+
+            producer.Output.TryComplete();
+        }
+        catch (OperationCanceledException) when (producer.ReadToken.IsCancellationRequested)
+        {
+            if (producer.CallerToken.IsCancellationRequested)
+                producer.State.CancellationObserved = true;
+            producer.Output.TryComplete();
+        }
+        catch (Exception ex)
+        {
+            producer.Output.TryComplete(ex);
+            throw;
+        }
+    }
+
+    private static void ConsumeBatchItemsInOrder(
+        in BatchParallelConsumerPlan consumer,
+        ChannelReader<BatchPendingItem> input,
+        Queue<BatchActiveItem> active)
+    {
+        while (!consumer.State.OutputLimitReached)
+        {
+            FillBatchWorkerQueue(in consumer, input, active);
+            if (ShouldConsumeOldestBatchItem(in consumer, input, active))
+            {
+                ConsumeOldestBatchItem(in consumer, active);
+                continue;
+            }
+
+            if (active.Count == 0 && input.Completion.IsCompleted)
+                break;
+            if (active.Count > 0 && active.Peek().Result.IsCompleted)
+                continue;
+            if (!WaitForBatchInputOrOldestWorker(input, active))
+                break;
+        }
+    }
+
+    private static void FillBatchWorkerQueue(
+        in BatchParallelConsumerPlan consumer,
+        ChannelReader<BatchPendingItem> input,
+        Queue<BatchActiveItem> active)
+    {
+        while (active.Count < consumer.ExecutionPlan.Parallelism
+               && input.TryRead(out var item))
+        {
+            BatchParallelSession? session = null;
+            Task<BatchParallelCommandResult?> result;
+            if (item.Error is not null)
+            {
+                result = Task.FromResult<BatchParallelCommandResult?>(null);
+            }
+            else
+            {
+                session = consumer.AvailableSessions.Dequeue();
+                var assignedSession = session;
+                var executionPlan = consumer.ExecutionPlan;
+                var stdoutRouter = consumer.Output.StdoutRouter;
+                var stderrRouter = consumer.Output.StderrRouter;
+                var jsonOptions = consumer.JsonOptions;
+                var appVersion = consumer.AppVersion;
+                var cancellationToken = consumer.CancellationToken;
+                result = Task.Run<BatchParallelCommandResult?>(
+                    () => RunBatchParallelCommand(
+                        item.LineNumber,
+                        item.CommandName!,
+                        item.Arguments,
+                        executionPlan.DbPath,
+                        executionPlan.DbPathExplicit,
+                        assignedSession,
+                        stdoutRouter,
+                        stderrRouter,
+                        jsonOptions,
+                        appVersion,
+                        cancellationToken));
+            }
+            active.Enqueue(new BatchActiveItem(item, result, session));
+        }
+    }
+
+    private static bool ShouldConsumeOldestBatchItem(
+        in BatchParallelConsumerPlan consumer,
+        ChannelReader<BatchPendingItem> input,
+        Queue<BatchActiveItem> active)
+        => active.Count > 0
+           && (active.Peek().Result.IsCompleted
+               || active.Count == consumer.ExecutionPlan.Parallelism
+               || input.Completion.IsCompleted);
+
+    private static void ConsumeOldestBatchItem(
+        in BatchParallelConsumerPlan consumer,
+        Queue<BatchActiveItem> active)
+    {
+        var activeItem = active.Dequeue();
+        var item = activeItem.Item;
+        var result = activeItem.Result.GetAwaiter().GetResult();
+        if (activeItem.Session is not null)
+            consumer.AvailableSessions.Enqueue(activeItem.Session);
+        if (item.Error is not null)
+        {
+            if (item.Error.ExitCode is CommandExitCodes.CancelledBySignal
+                or CommandExitCodes.LegacyInterrupted)
+            {
+                consumer.State.CancellationObserved = true;
+            }
+            RecordBatchFirstFailure(consumer.State, item.Error.ExitCode);
+
+            if (item.Terminal)
+            {
+                consumer.Output.JsonOutput.WriteTerminal(
+                    BuildBatchLineErrorJson(item.LineNumber, item.Error));
+                return;
+            }
+
+            if (!WriteBatchLineErrorJson(item.LineNumber, item.Error, consumer.Output.JsonOutput))
+            {
+                WriteBatchOutputLimitErrorJson(
+                    item.LineNumber,
+                    commandName: null,
+                    item.Error.ExitCode,
+                    consumer.ExecutionPlan.MaxOutputChars,
+                    consumer.Output.JsonOutput);
+                consumer.State.OutputLimitReached = true;
+            }
+            return;
+        }
+
+        if (result is null)
+        {
+            throw new InvalidOperationException(
+                "A parallel batch command completed without a result.");
+        }
+        var completedResult = result.Value;
+        if (WriteBatchCommandRecordJson(
+                item.LineNumber,
+                item.CommandName!,
+                item.Arguments,
+                completedResult.ExitCode,
+                completedResult.Stdout,
+                completedResult.Stderr,
+                completedResult.Error,
+                ClassifyBatchOutput(item.CommandName!, item.Arguments),
+                consumer.ExecutionPlan.IncludeRawStreams,
+                consumer.Output.JsonOutput))
+        {
+            if (completedResult.ExitCode != CommandExitCodes.Success)
+            {
+                if (completedResult.ExitCode is CommandExitCodes.CancelledBySignal
+                    or CommandExitCodes.LegacyInterrupted)
+                {
+                    consumer.State.CancellationObserved = true;
+                }
+                consumer.State.CommandFailures++;
+                RecordBatchFirstFailure(consumer.State, completedResult.ExitCode);
+            }
+            return;
+        }
+
+        WriteBatchOutputLimitErrorJson(
+            item.LineNumber,
+            item.CommandName,
+            completedResult.ExitCode,
+            consumer.ExecutionPlan.MaxOutputChars,
+            consumer.Output.JsonOutput);
+        consumer.State.OutputLimitReached = true;
+        consumer.State.CommandFailures++;
+        RecordBatchFirstFailure(consumer.State, CommandExitCodes.InvalidArgument);
+    }
+
+    private static bool WaitForBatchInputOrOldestWorker(
+        ChannelReader<BatchPendingItem> input,
+        Queue<BatchActiveItem> active)
+    {
+        using var waitCancellation = new CancellationTokenSource();
+        var waitForInput = input.WaitToReadAsync(waitCancellation.Token).AsTask();
+        if (active.Count == 0)
+            return waitForInput.GetAwaiter().GetResult();
+
+        var completed = Task.WhenAny(active.Peek().Result, waitForInput)
+            .GetAwaiter()
+            .GetResult();
+        if (ReferenceEquals(completed, active.Peek().Result))
+        {
+            waitCancellation.Cancel();
+            try
+            {
+                waitForInput.GetAwaiter().GetResult();
+            }
+            catch (OperationCanceledException) when (waitCancellation.IsCancellationRequested)
+            {
+            }
+        }
+
+        return true;
+    }
+
+    private static void DrainBatchWorkers(
+        Queue<BatchActiveItem> active,
+        bool preserveEarlierFailure)
+    {
+        while (active.Count > 0)
+        {
+            if (!preserveEarlierFailure)
+            {
+                active.Dequeue().Result.GetAwaiter().GetResult();
+                continue;
+            }
+
+            try
+            {
+                active.Dequeue().Result.GetAwaiter().GetResult();
+            }
+            catch
+            {
+                // Preserve the first failure while ensuring sibling workers have exited.
+            }
+        }
+    }
+
+    private static BatchParallelCommandResult RunBatchParallelCommand(
+        int lineNumber,
+        string commandName,
+        string[] subArgs,
+        string dbPath,
+        bool dbPathExplicit,
+        BatchParallelSession session,
+        BatchConsoleRouter stdoutRouter,
+        BatchConsoleRouter stderrRouter,
+        JsonSerializerOptions jsonOptions,
+        string appVersion,
+        CancellationToken cancellationToken)
+    {
+        using var stdout = new BatchBoundedStringWriter(BatchMaxCapturedOutputChars, "stdout");
+        using var stderr = new BatchBoundedStringWriter(BatchMaxCapturedOutputChars, "stderr");
+        using var stdoutRouterRegistration = ScopedConsoleOutput.Register(stdoutRouter);
+        using var stderrRouterRegistration = ScopedConsoleError.Register(stderrRouter);
+        using var stdoutScope = stdoutRouter.Push(stdout);
+        using var stderrScope = stderrRouter.Push(stderr);
+        var exitCode = CommandExitCodes.DatabaseError;
+        JsonObject? error = null;
+        try
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            if (!session.TryGetReader(cancellationToken, out var reader, out var validationReason))
+            {
+                exitCode = WriteInvalidCodeIndexDbError(dbPath, validationReason, json: false, jsonOptions);
+            }
+            else
+            {
+                s_batchReader = reader;
+                s_batchDbPath = dbPath;
+                s_batchDbPathExplicit = dbPathExplicit;
+                BatchParallelCommandStartedForTesting?.Invoke(lineNumber);
+                cancellationToken.ThrowIfCancellationRequested();
+                exitCode = RunBatchQueryCommand(commandName, subArgs, jsonOptions, appVersion, cancellationToken);
+                BatchParallelCommandCompletedForTesting?.Invoke(lineNumber);
+            }
+        }
+        catch (BatchOutputCaptureLimitExceededException ex)
+        {
+            exitCode = CommandExitCodes.InvalidArgument;
+            error = BuildBatchCaptureLimitError(ex);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            exitCode = CommandExitCodes.CancelledBySignal;
+            error = BuildBatchCancellationError();
+        }
+        catch (TimeoutException)
+        {
+            exitCode = CommandExitCodes.RuntimeError;
+            error = BuildBatchTimeoutError();
+        }
+        catch (Exception ex)
+        {
+            exitCode = CommandExitCodes.RuntimeError;
+            error = BuildBatchTypedError(
+                "batch command failed without affecting other batch items.",
+                exitCode,
+                "Retry the item directly if command-specific diagnostics are required.",
+                CommandErrorCodes.CommandFailed,
+                SafeDiagnosticFormatter.FormatCategoryType(
+                    "batch_command_failure",
+                    ex.GetType().Name),
+                "command");
+        }
+        finally
+        {
+            s_batchReader = null;
+            s_batchDbPath = null;
+            s_batchDbPathExplicit = false;
+            s_activeQueryProjectRoot = null;
+        }
+
+        return new BatchParallelCommandResult(exitCode, stdout.ToString(), stderr.ToString(), error);
+    }
+
+    private readonly record struct BatchParallelProducerPlan(
+        BatchExecutionPlan ExecutionPlan,
+        JsonSerializerOptions JsonOptions,
+        BatchExecutionState State,
+        BatchInputPump Input,
+        ChannelWriter<BatchPendingItem> Output,
+        CancellationToken StopToken,
+        CancellationToken ReadToken,
+        CancellationToken CallerToken);
+
+    private readonly record struct BatchParallelConsumerPlan(
+        BatchExecutionPlan ExecutionPlan,
+        JsonSerializerOptions JsonOptions,
+        string AppVersion,
+        Queue<BatchParallelSession> AvailableSessions,
+        BatchParallelOutputServices Output,
+        BatchExecutionState State,
+        CancellationToken CancellationToken);
+
+    private readonly record struct BatchParallelOutputServices(
+        BatchConsoleRouter StdoutRouter,
+        BatchConsoleRouter StderrRouter,
+        BatchJsonOutputWriter JsonOutput);
+
+    private readonly record struct BatchActiveItem(
+        BatchPendingItem Item,
+        Task<BatchParallelCommandResult?> Result,
+        BatchParallelSession? Session);
+}
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerBatchIssue4871Tests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerBatchIssue4871Tests.cs
index 6b42a361a..9a63c8abc 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerBatchIssue4871Tests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerBatchIssue4871Tests.cs
@@ -4,6 +4,89 @@ namespace CodeIndex.Tests;
 
 public partial class QueryCommandRunnerTests
 {
+    [Fact]
+    public void RunBatch_SerialAndParallelMixedInputPreserveRecordAndAccountingParity()
+    {
+        using var project = TestProjectHelper.CreateTempProjectScope("cdidx_batch_mixed_parity");
+        var dbPath = TestProjectHelper.CreateProjectDb(project.Root);
+        var input = string.Join(
+            '\n',
+            "",
+            """{"command":"files","args":["--format","count","--json"]}""",
+            """["search","missing-batch-mixed","--json","--strict-not-found"]""",
+            "42",
+            """{"command":"status","args":"--json"}""",
+            """["unknown"]""",
+            """["languages","--format","count"]""",
+            "");
+
+        var (serialExitCode, serialStdout, serialStderr) = CaptureConsoleWithInput(
+            input,
+            () => QueryCommandRunner.RunBatch(
+                ["--db", dbPath, "--json-summary", "--include-raw-streams"],
+                _jsonOptions));
+        var (parallelExitCode, parallelStdout, parallelStderr) = CaptureConsoleWithInput(
+            input,
+            () => QueryCommandRunner.RunBatch(
+                [
+                    "--db", dbPath,
+                    "--json-summary",
+                    "--include-raw-streams",
+                    "--parallel", "3",
+                ],
+                _jsonOptions));
+
+        Assert.Equal(CommandExitCodes.NotFound, serialExitCode);
+        Assert.Equal(serialExitCode, parallelExitCode);
+        Assert.Equal(string.Empty, serialStderr);
+        Assert.Equal(serialStderr, parallelStderr);
+        var serialLines = ParseJsonLines(serialStdout);
+        var parallelLines = ParseJsonLines(parallelStdout);
+        try
+        {
+            Assert.Equal(7, serialLines.Count);
+            Assert.Equal(serialLines.Count, parallelLines.Count);
+            for (var index = 0; index < 6; index++)
+            {
+                Assert.Equal(index + 2, serialLines[index].RootElement.GetProperty("line").GetInt32());
+                Assert.Equal(
+                    serialLines[index].RootElement.GetRawText(),
+                    parallelLines[index].RootElement.GetRawText());
+            }
+
+            var serialSummary = serialLines[^1].RootElement;
+            var parallelSummary = parallelLines[^1].RootElement;
+            Assert.Equal("batch_summary", serialSummary.GetProperty("record").GetString());
+            Assert.Equal("batch_summary", parallelSummary.GetProperty("record").GetString());
+            Assert.Equal(7, serialSummary.GetProperty("input_lines_read").GetInt32());
+            Assert.Equal(7, parallelSummary.GetProperty("input_lines_read").GetInt32());
+            Assert.Equal(4, serialSummary.GetProperty("commands_processed").GetInt32());
+            Assert.Equal(4, parallelSummary.GetProperty("commands_processed").GetInt32());
+            Assert.Equal(2, serialSummary.GetProperty("line_errors").GetInt32());
+            Assert.Equal(2, parallelSummary.GetProperty("line_errors").GetInt32());
+            Assert.Equal(2, serialSummary.GetProperty("command_failures").GetInt32());
+            Assert.Equal(2, parallelSummary.GetProperty("command_failures").GetInt32());
+            Assert.Equal(CommandExitCodes.NotFound, serialSummary.GetProperty("exit_code").GetInt32());
+            Assert.Equal(CommandExitCodes.NotFound, parallelSummary.GetProperty("exit_code").GetInt32());
+            Assert.False(serialSummary.GetProperty("output_limit_reached").GetBoolean());
+            Assert.False(parallelSummary.GetProperty("output_limit_reached").GetBoolean());
+            Assert.False(serialSummary.GetProperty("input_limit_reached").GetBoolean());
+            Assert.False(parallelSummary.GetProperty("input_limit_reached").GetBoolean());
+            Assert.Equal(1, serialSummary.GetProperty("parallelism").GetInt32());
+            Assert.Equal(3, parallelSummary.GetProperty("parallelism").GetInt32());
+            Assert.Equal(
+                serialSummary.GetProperty("output_chars").GetInt32(),
+                parallelSummary.GetProperty("output_chars").GetInt32());
+        }
+        finally
+        {
+            foreach (var document in serialLines)
+                document.Dispose();
+            foreach (var document in parallelLines)
+                document.Dispose();
+        }
+    }
+
     [Fact]
     public void RunBatch_AllJsonSummaryFailuresUseTypedEnvelopesInSerialAndParallel_Issue4871()
     {
@@ -31,7 +114,7 @@ public void RunBatch_AllJsonSummaryFailuresUseTypedEnvelopesInSerialAndParallel_
         foreach (var batchArgs in new[]
                  {
                      new[] { "--db", dbPath, "--json-summary" },
-                     new[] { "--db", dbPath, "--json-summary", "--parallel", "3" },
+                     ["--db", dbPath, "--json-summary", "--parallel", "3"],
                  })
         {
             var (exitCode, stdout, stderr) = CaptureConsoleWithInput(
@@ -253,7 +336,7 @@ public void RunBatch_SetupCancellationUsesTypedSummaryInSerialAndParallel_Issue4
         foreach (var batchArgs in new[]
                  {
                      new[] { "--db", dbPath, "--json-summary" },
-                     new[] { "--db", dbPath, "--json-summary", "--parallel", "2" },
+                     ["--db", dbPath, "--json-summary", "--parallel", "2"],
                  })
         {
             var (exitCode, stdout, stderr) = CaptureConsoleWithInput(
@@ -292,7 +375,7 @@ public void RunBatch_CancellationAfterPriorFailureUsesLineEnvelopeAndCancelledSu
         foreach (var batchArgs in new[]
                  {
                      new[] { "--db", dbPath, "--json-summary" },
-                     new[] { "--db", dbPath, "--json-summary", "--parallel", "2" },
+                     ["--db", dbPath, "--json-summary", "--parallel", "2"],
                  })
         {
             using var cancellation = new CancellationTokenSource();
@@ -475,6 +558,140 @@ public void RunBatch_ParallelCancellationInterruptsBlockedInputAndPreservesNextL
         }
     }
 
+    [Fact]
+    public async Task RunBatch_ParallelOutputLimitDrainsActiveWorkersAndRestoresConsole()
+    {
+        using var project = TestProjectHelper.CreateTempProjectScope("cdidx_batch_output_limit_drain");
+        var dbPath = TestProjectHelper.CreateProjectDb(project.Root);
+        using var bothStarted = new CountdownEvent(2);
+        using var fourthLineRead = new ManualResetEventSlim();
+        using var releaseFourthLine = new ManualResetEventSlim();
+        using var releaseSecond = new ManualResetEventSlim();
+        using var secondCompleted = new ManualResetEventSlim();
+        using var firstRecordWritten = new ManualResetEventSlim();
+        using var stdout = new NotifyingStringWriter(firstRecordWritten);
+        using var stderr = new StringWriter();
+        Task<int>? firstRun = null;
+
+        QueryCommandRunner.BatchParallelCommandStartedForTesting = lineNumber =>
+        {
+            bothStarted.Signal();
+            if (!bothStarted.Wait(TimeSpan.FromSeconds(15)))
+                throw new TimeoutException("Both output-limit batch workers did not start.");
+            if (lineNumber == 1 && !fourthLineRead.Wait(TimeSpan.FromSeconds(15)))
+                throw new TimeoutException("The terminal input-limit line was not read.");
+            if (lineNumber == 2 && !releaseSecond.Wait(TimeSpan.FromSeconds(15)))
+                throw new TimeoutException("The second output-limit batch worker was not released.");
+        };
+        QueryCommandRunner.BatchParallelCommandCompletedForTesting = lineNumber =>
+        {
+            if (lineNumber == 2)
+                secondCompleted.Set();
+        };
+        QueryCommandRunner.BatchInputLineReadForTesting = lineNumber =>
+        {
+            if (lineNumber != 4)
+                return;
+            fourthLineRead.Set();
+            if (!releaseFourthLine.Wait(TimeSpan.FromSeconds(15)))
+                throw new TimeoutException("The terminal input-limit line was not released.");
+        };
+
+        try
+        {
+            firstRun = Task.Factory.StartNew(
+                () =>
+                {
+                    using var capture = ConsoleCapture.Start(
+                        stdout,
+                        stderr,
+                        new StringReader(
+                            """
+                            ["languages","--format","count"]
+                            ["languages","--format","count"]
+                            ["languages","--format","count"]
+                            ["languages","--format","count"]
+                            """ + "\n"));
+                    var expectedOut = Console.Out;
+                    var expectedError = Console.Error;
+                    var exitCode = QueryCommandRunner.RunBatch(
+                        [
+                            "--db", dbPath,
+                            "--json-summary",
+                            "--parallel", "2",
+                            "--max-input-lines", "3",
+                            "--max-output-chars", QueryCommandRunner.BatchMinTotalOutputChars.ToString(),
+                        ],
+                        _jsonOptions);
+                    Assert.Same(expectedOut, Console.Out);
+                    Assert.Same(expectedError, Console.Error);
+                    return exitCode;
+                },
+                CancellationToken.None,
+                TaskCreationOptions.LongRunning,
+                TaskScheduler.Default);
+
+            Assert.True(bothStarted.Wait(TimeSpan.FromSeconds(15)));
+            Assert.True(fourthLineRead.Wait(TimeSpan.FromSeconds(15)));
+            Assert.True(firstRecordWritten.Wait(TimeSpan.FromSeconds(15)));
+            var firstOutputLines = ParseJsonLines(stdout.ToString());
+            try
+            {
+                var outputLimit = Assert.Single(firstOutputLines).RootElement;
+                Assert.Equal("batch_result", outputLimit.GetProperty("record").GetString());
+                Assert.Equal(
+                    "batch_output_limit",
+                    outputLimit.GetProperty("error").GetProperty("category").GetString());
+            }
+            finally
+            {
+                foreach (var document in firstOutputLines)
+                    document.Dispose();
+            }
+            Assert.False(firstRun.IsCompleted);
+
+            releaseFourthLine.Set();
+            Assert.False(firstRun.IsCompleted);
+            releaseSecond.Set();
+            var firstExitCode = await firstRun.WaitAsync(TimeSpan.FromSeconds(15));
+            Assert.True(secondCompleted.IsSet);
+            Assert.Equal(CommandExitCodes.InvalidArgument, firstExitCode);
+            Assert.Equal(string.Empty, stderr.ToString());
+            var lines = ParseJsonLines(stdout.ToString());
+            try
+            {
+                Assert.Equal(2, lines.Count);
+                var firstSummary = lines[1].RootElement;
+                Assert.Equal("batch_summary", firstSummary.GetProperty("record").GetString());
+                Assert.Equal(4, firstSummary.GetProperty("input_lines_read").GetInt32());
+                Assert.Equal(3, firstSummary.GetProperty("commands_processed").GetInt32());
+                Assert.Equal(0, firstSummary.GetProperty("line_errors").GetInt32());
+                Assert.Equal(1, firstSummary.GetProperty("command_failures").GetInt32());
+                Assert.True(firstSummary.GetProperty("output_limit_reached").GetBoolean());
+                Assert.False(firstSummary.GetProperty("input_limit_reached").GetBoolean());
+                Assert.Equal(
+                    CommandExitCodes.InvalidArgument,
+                    firstSummary.GetProperty("exit_code").GetInt32());
+            }
+            finally
+            {
+                foreach (var document in lines)
+                    document.Dispose();
+            }
+
+        }
+        finally
+        {
+            QueryCommandRunner.BatchParallelCommandStartedForTesting = null;
+            QueryCommandRunner.BatchParallelCommandCompletedForTesting = null;
+            QueryCommandRunner.BatchInputLineReadForTesting = null;
+            releaseFourthLine.Set();
+            releaseSecond.Set();
+            if (firstRun is not null)
+                await firstRun.WaitAsync(TimeSpan.FromSeconds(15));
+        }
+    }
+
     private sealed class BlockingBatchReader : TextReader
     {
         private const string DeferredLine = "42\n";

From c8bd97e83759992bfa782d67242d6cde0a1f1b6f Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 03:00:10 +0900
Subject: [PATCH 37/45] Preserve undispatched parallel batch input

---
 TESTING_GUIDE.md                              |   4 +-
 .../+batch-output-limit-replay.fixed.md       |  14 ++
 src/CodeIndex/Cli/QueryCommandRunner.Batch.cs |  46 +++-
 ...eryCommandRunner.BatchParallelExecution.cs | 202 +++++++++++++++---
 .../QueryCommandRunnerBatchIssue4871Tests.cs  | 126 ++++++++++-
 5 files changed, 359 insertions(+), 33 deletions(-)
 create mode 100644 changelog.d/unreleased/+batch-output-limit-replay.fixed.md

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 772f6ff6b..4d54bde02 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -248,7 +248,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   Doctor full-inventory coverage keeps composed filter selection, filtered summary counts, exact UTF-8 byte-budget boundaries, and structured overflow errors together in `ProgramRunnerTests`; license JSON remains a subprocess contract in `ProgramCliTests` so immediate-command dispatch and the published field names are both exercised.
   Ctags export JSON coverage reuses one seeded database for default and `--include-generated` variants, asserts the fixed skip-reason keys sum to `skipped_count`, and keeps the missing-`files.generated` degradation in a separate legacy-schema fixture.
   Dry-run JSON coverage for ambiguous `.h` files locks the bounded `language_detections` entries and their stable source/confidence codes without mutating the index.
-  Batch `--json-summary` coverage keeps side-effect-free dispatch plus successful JSON, single-row NDJSON, and JSON-looking text projection in one seeded fixture when the assertions stay distinct; include case-insensitive format values, command-specific JSON formats, and alias-injected JSON defaults so batch classification cannot drift from child parsers. Serialized-output exhaustion remains a separate boundary fixture because of its large escaped payload. Assert `result` / `results` versus raw `stdout` presence explicitly, compare `output_chars` with the actual captured stream length, and cover repeated malformed lines up to the input cap so neither syntax sniffing nor envelope overhead can bypass the transport bounds. Typed-failure coverage reuses one mixed scalar/array/schema/policy/child-failure input across serial and parallel modes, asserts stable ordered categories, and keeps timeout, caller cancellation, and explicit `--include-raw-streams` behavior in focused fixtures. Shared line-preparation/accounting coverage compares mixed blank, valid, malformed, and unsupported input across serial and parallel modes, including ordered records, first failure, counters, limits, and output characters. Output-limit drain coverage gates two active workers without sleeps, proves the batch remains pending until the held worker completes, keeps an unpublished input-limit record out of committed counters, and verifies console restoration after the join; blocked-input preservation remains in the focused cancellation fixture. Cancellation coverage includes pre-cancelled setup, cancellation after an earlier failure and after parallel item preparation, and a blocking stdin reader that proves both prompt wake-up and preservation of an in-flight line for the next batch invocation.
+  Batch `--json-summary` coverage keeps side-effect-free dispatch plus successful JSON, single-row NDJSON, and JSON-looking text projection in one seeded fixture when the assertions stay distinct; include case-insensitive format values, command-specific JSON formats, and alias-injected JSON defaults so batch classification cannot drift from child parsers. Serialized-output exhaustion remains a separate boundary fixture because of its large escaped payload. Assert `result` / `results` versus raw `stdout` presence explicitly, compare `output_chars` with the actual captured stream length, and cover repeated malformed lines up to the input cap so neither syntax sniffing nor envelope overhead can bypass the transport bounds. Typed-failure coverage reuses one mixed scalar/array/schema/policy/child-failure input across serial and parallel modes, asserts stable ordered categories, and keeps timeout, caller cancellation, and explicit `--include-raw-streams` behavior in focused fixtures. Shared line-preparation/accounting coverage compares mixed blank, valid, malformed, and unsupported input across serial and parallel modes, including ordered records, first failure, counters, limits, and output characters. Output-limit drain coverage gates two active workers without sleeps, proves the batch remains pending until the held worker completes, keeps an unpublished input-limit record out of committed counters, verifies console restoration after the join, and replays only accepted-but-undispatched nonblank input records in source order before pump-buffered future input with fresh line numbers and counters on the next invocation; blocked-input preservation remains in the focused cancellation fixture. Cancellation coverage includes pre-cancelled setup, cancellation after an earlier failure and after parallel item preparation, and a blocking stdin reader that proves both prompt wake-up and preservation of an in-flight line for the next batch invocation.
   Argument-validation variants that only differ by invalid scalar input share one database fixture and iterate within a fact when no per-case state or discovery identity is required.
   Positional `files` glob coverage shares one indexed-file fixture and iterates `*`, `?`, and recursive `**` patterns in a fact, matching the exact tokens that a quoted shell argument passes to the CLI.
   Excerpt focus coverage reuses one indexed fixture for line-only leading-window behavior, the focus-length dependency, and focus-column range validation; zero and non-numeric focus-column values share one indexed Markdown fixture.
@@ -1314,7 +1314,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   doctor full-inventory coverage では、合成 filter の選択、filtered summary 件数、UTF-8 byte budget の exact boundary、structured overflow error を `ProgramRunnerTests` にまとめます。license JSON は `ProgramCliTests` の subprocess contract として、immediate-command dispatch と公開 field 名を同時に検証します。
   ctags export JSON coverage は1つの seeded database を既定と `--include-generated` variant で再利用し、固定された skip-reason key の合計が `skipped_count` と一致することを検証します。`files.generated` がない場合の縮退は別の legacy-schema fixture に保ってください。
   曖昧な `.h` に対する dry-run JSON coverage は、index を変更せず、上限付き `language_detections` entry と安定した判定元・信頼度 code を固定します。
-  batch `--json-summary` coverage は、assertion を明確に保てる場合、副作用なし dispatch と成功時の JSON / 1 row NDJSON / JSON に見える text projection を1つの seeded fixture で共有し、case-insensitive な format 値、command 固有の JSON format、alias が内部追加する JSON default も含めて child parser と batch classification の drift を防いでください。serialized output の枯渇は escape を多く含む大きな payload の境界 fixture として分離します。test 側で `result` / `results` と raw `stdout` の有無を明示し、`output_chars` を実際に捕捉した stream 長と比較し、input cap までの malformed line 反復も検証して、syntax sniffing や envelope overhead が transport 上限を迂回しないようにしてください。typed failure coverage は scalar / array / schema / policy / child failure を混在させた1つの input を serial / parallel mode で共有し、安定した順序と category を検証してください。timeout、caller cancellation、明示的な `--include-raw-streams` の挙動は焦点を絞った fixture に分離します。共有 line preparation / accounting の coverage では blank、valid、malformed、unsupported input の混在を serial / parallel mode で比較し、record 順、first failure、counter、limit、output character 数を固定します。output-limit drain coverage は sleep なしの gate で active worker 2つを保持し、一方の worker が完了するまで batch が pending のままであること、未配送の input-limit record が確定済み counter に混入しないこと、join 後に console が復元されることを検証します。blocked input の保持は focused cancellation fixture に分離してください。cancellation coverage には事前 cancel 済み setup、先行 failure 後と parallel item 準備後の cancellation、blocking stdin reader を含め、型付き summary、迅速な wait 解除、同時に読み取った line が次の batch invocation 用に保持されることを決定的に検証します。
+  batch `--json-summary` coverage は、assertion を明確に保てる場合、副作用なし dispatch と成功時の JSON / 1 row NDJSON / JSON に見える text projection を1つの seeded fixture で共有し、case-insensitive な format 値、command 固有の JSON format、alias が内部追加する JSON default も含めて child parser と batch classification の drift を防いでください。serialized output の枯渇は escape を多く含む大きな payload の境界 fixture として分離します。test 側で `result` / `results` と raw `stdout` の有無を明示し、`output_chars` を実際に捕捉した stream 長と比較し、input cap までの malformed line 反復も検証して、syntax sniffing や envelope overhead が transport 上限を迂回しないようにしてください。typed failure coverage は scalar / array / schema / policy / child failure を混在させた1つの input を serial / parallel mode で共有し、安定した順序と category を検証してください。timeout、caller cancellation、明示的な `--include-raw-streams` の挙動は焦点を絞った fixture に分離します。共有 line preparation / accounting の coverage では blank、valid、malformed、unsupported input の混在を serial / parallel mode で比較し、record 順、first failure、counter、limit、output character 数を固定します。output-limit drain coverage は sleep なしの gate で active worker 2つを保持し、一方の worker が完了するまで batch が pending のままであること、未配送の input-limit record が確定済み counter に混入しないこと、join 後に console が復元されること、受理済みでも未 dispatch の nonblank input record だけが source 順で pump buffer 内の後続入力より前に戻され、次の invocation では line number と counter が新しく付け直されることを検証します。blocked input の保持は focused cancellation fixture に分離してください。cancellation coverage には事前 cancel 済み setup、先行 failure 後と parallel item 準備後の cancellation、blocking stdin reader を含め、型付き summary、迅速な wait 解除、同時に読み取った line が次の batch invocation 用に保持されることを決定的に検証します。
   invalid scalar input だけが異なる argument-validation variant は、case ごとの state や discovery identity が不要なら1つの database fixture を共有し、fact 内で反復してください。
   `files` の positional glob coverage は1つの indexed-file fixture を共有し、quote された shell 引数が CLI に渡す token と同じ `*`、`?`、recursive `**` pattern を fact 内で反復してください。
   excerpt の focus coverage は、line-only 時の先頭側 window、focus-length の依存関係、focus-column の範囲検証を1つの indexed fixture で共有してください。focus-column の zero / non-numeric value も1つの indexed Markdown fixture を再利用してください。
diff --git a/changelog.d/unreleased/+batch-output-limit-replay.fixed.md b/changelog.d/unreleased/+batch-output-limit-replay.fixed.md
new file mode 100644
index 000000000..db31b2247
--- /dev/null
+++ b/changelog.d/unreleased/+batch-output-limit-replay.fixed.md
@@ -0,0 +1,14 @@
+---
+category: fixed
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.Batch.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.BatchParallelExecution.cs
+---
+
+## English
+
+- **Parallel batch output limits no longer discard accepted, undispatched input records** — when `batch --parallel` reaches `--max-output-chars`, accepted nonblank input records that were not dispatched are returned to the shared bounded input pump in source order. The next batch invocation reparses those records with fresh line numbers and counters, ahead of input the pump already buffered, while commands that started remain owned by the first invocation.
+
+## 日本語
+
+- **parallel batch の出力上限で、受理済みかつ未 dispatch の input record が失われなくなりました** — `batch --parallel` が `--max-output-chars` に達した場合、受理済みでも未 dispatch の nonblank input record を source 順のまま共有の bounded input pump に戻します。次の batch invocation は、すでに pump が buffer した入力より先にそれらの record を再 parse し、新しい line number と counter を割り当てます。開始済みの command は最初の invocation の所有のままです。
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.Batch.cs b/src/CodeIndex/Cli/QueryCommandRunner.Batch.cs
index 176c74144..69c10d20b 100644
--- a/src/CodeIndex/Cli/QueryCommandRunner.Batch.cs
+++ b/src/CodeIndex/Cli/QueryCommandRunner.Batch.cs
@@ -947,7 +947,11 @@ private static BatchInputPump GetBatchInputPump(TextReader reader)
 
     private sealed class BatchInputPump
     {
+        // Output-limit recovery can own one channel slot plus one producer-local line.
+        private const int ReplayLineCapacity = 2;
         private readonly Channel<BatchPumpedLine> _lines;
+        private readonly object _replayGate = new();
+        private readonly LinkedList<BatchPumpedLine> _replayLines = [];
 
         public BatchInputPump(TextReader reader)
         {
@@ -966,7 +970,38 @@ public BatchInputPump(TextReader reader)
             _ = Task.Run(() => Pump(reader));
         }
 
-        public async ValueTask<BatchPumpedLine?> ReadAsync(CancellationToken cancellationToken)
+        public ValueTask<BatchPumpedLine?> ReadAsync(CancellationToken cancellationToken)
+        {
+            lock (_replayGate)
+            {
+                if (_replayLines.First is not { } first)
+                    return ReadPumpedLineAsync(cancellationToken);
+
+                _replayLines.RemoveFirst();
+                return ValueTask.FromResult<BatchPumpedLine?>(first.Value);
+            }
+        }
+
+        public void ReplayBeforeBufferedInput(IReadOnlyList<BatchPumpedLine> lines)
+        {
+            if (lines.Count == 0)
+                return;
+
+            lock (_replayGate)
+            {
+                if (_replayLines.Count + lines.Count > ReplayLineCapacity)
+                {
+                    throw new InvalidOperationException(
+                        "Parallel batch replay exceeded the bounded input ownership window.");
+                }
+
+                for (var index = lines.Count - 1; index >= 0; index--)
+                    _replayLines.AddFirst(lines[index]);
+            }
+        }
+
+        private async ValueTask<BatchPumpedLine?> ReadPumpedLineAsync(
+            CancellationToken cancellationToken)
         {
             try
             {
@@ -980,11 +1015,13 @@ public BatchInputPump(TextReader reader)
 
         private void Pump(TextReader reader)
         {
+            long sequence = 0;
             try
             {
                 while (TryReadBatchLine(reader, out var line, out var exceededLimit))
                 {
-                    _lines.Writer.WriteAsync(new BatchPumpedLine(line, exceededLimit))
+                    _lines.Writer.WriteAsync(
+                            new BatchPumpedLine(++sequence, line, exceededLimit))
                         .AsTask()
                         .GetAwaiter()
                         .GetResult();
@@ -998,7 +1035,10 @@ private void Pump(TextReader reader)
         }
     }
 
-    private readonly record struct BatchPumpedLine(string? Line, bool ExceededLimit);
+    private readonly record struct BatchPumpedLine(
+        long Sequence,
+        string? Line,
+        bool ExceededLimit);
 
     private readonly record struct BatchParallelCommandResult(
         int ExitCode,
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.BatchParallelExecution.cs b/src/CodeIndex/Cli/QueryCommandRunner.BatchParallelExecution.cs
index 073209b55..a932a7ef8 100644
--- a/src/CodeIndex/Cli/QueryCommandRunner.BatchParallelExecution.cs
+++ b/src/CodeIndex/Cli/QueryCommandRunner.BatchParallelExecution.cs
@@ -30,12 +30,13 @@ private static int RunBatchParallel(
             BatchTerminalOutputReserveChars,
             jsonOptions);
         var state = new BatchExecutionState();
+        var replayTracker = new BatchParallelReplayTracker();
         using var stopProducing = new CancellationTokenSource();
         using var producerCancellation = CancellationTokenSource.CreateLinkedTokenSource(
             cancellationToken,
             stopProducing.Token);
         var batchInput = GetBatchInputPump(Console.In);
-        var input = Channel.CreateBounded<BatchPendingItem>(
+        var input = Channel.CreateBounded<BatchParallelPendingItem>(
             new BoundedChannelOptions(1)
             {
                 FullMode = BoundedChannelFullMode.Wait,
@@ -51,12 +52,16 @@ private static int RunBatchParallel(
                 plan,
                 jsonOptions,
                 state,
+                replayTracker,
                 batchInput,
                 input.Writer,
-                stopProducing.Token,
-                producerCancellation.Token,
-                cancellationToken);
-            var producer = Task.Run(() => ProduceBatchItemsAsync(producerPlan), cancellationToken);
+                new BatchParallelProducerCancellation(
+                    stopProducing.Token,
+                    producerCancellation.Token,
+                    cancellationToken));
+            var producer = Task.Run(
+                () => ProduceBatchItemsAsync(producerPlan),
+                CancellationToken.None);
             var active = new Queue<BatchActiveItem>();
             var consumerPlan = new BatchParallelConsumerPlan(
                 plan,
@@ -65,6 +70,7 @@ private static int RunBatchParallel(
                 availableSessions,
                 new BatchParallelOutputServices(stdoutRouter, stderrRouter, jsonOutput),
                 state,
+                replayTracker,
                 cancellationToken);
 
             try
@@ -103,6 +109,12 @@ private static int RunBatchParallel(
             {
             }
 
+            if (state.OutputLimitReached && !cancellationToken.IsCancellationRequested)
+            {
+                batchInput.ReplayBeforeBufferedInput(
+                    replayTracker.TakeForReplay(state));
+            }
+
             if (state.CancellationObserved)
                 state.FirstFailure = CommandExitCodes.CancelledBySignal;
 
@@ -139,15 +151,15 @@ private static async Task ProduceBatchItemsAsync(BatchParallelProducerPlan produ
         var plan = producer.ExecutionPlan;
         try
         {
-            while (!producer.StopToken.IsCancellationRequested)
+            while (!producer.Cancellation.StopToken.IsCancellationRequested)
             {
-                if (producer.CallerToken.IsCancellationRequested)
+                if (producer.Cancellation.CallerToken.IsCancellationRequested)
                 {
                     producer.State.CancellationObserved = true;
                     break;
                 }
 
-                var pumpedLine = await producer.Input.ReadAsync(producer.ReadToken)
+                var pumpedLine = await producer.Input.ReadAsync(producer.Cancellation.ReadToken)
                     .ConfigureAwait(false);
                 if (pumpedLine is null)
                     break;
@@ -159,34 +171,46 @@ private static async Task ProduceBatchItemsAsync(BatchParallelProducerPlan produ
                     producer.State,
                     producer.JsonOptions,
                     writeDiagnostics: false,
-                    producer.CallerToken,
+                    producer.Cancellation.CallerToken,
                     out var item);
+                if (preparation == BatchLinePreparationKind.Blank)
+                    continue;
+                if (preparation == BatchLinePreparationKind.CancellationWithoutRecord)
+                    break;
+
+                producer.ReplayTracker.Register(in currentLine, preparation);
+                var pendingItem = new BatchParallelPendingItem(
+                    item,
+                    currentLine.Sequence);
                 switch (preparation)
                 {
-                    case BatchLinePreparationKind.Blank:
-                        continue;
-
-                    case BatchLinePreparationKind.CancellationWithoutRecord:
-                        break;
-
                     case BatchLinePreparationKind.CancellationRecord:
                     case BatchLinePreparationKind.InputLimit:
-                        await producer.Output.WriteAsync(item, producer.StopToken)
+                        await producer.Output.WriteAsync(
+                                pendingItem,
+                                producer.Cancellation.StopToken)
                             .ConfigureAwait(false);
                         RecordPreparedBatchLine(producer.State, preparation);
+                        producer.ReplayTracker.MarkCountersRecorded(currentLine.Sequence);
                         break;
 
                     case BatchLinePreparationKind.LineLengthError:
-                        await producer.Output.WriteAsync(item, producer.StopToken)
+                        await producer.Output.WriteAsync(
+                                pendingItem,
+                                producer.Cancellation.StopToken)
                             .ConfigureAwait(false);
                         RecordPreparedBatchLine(producer.State, preparation);
+                        producer.ReplayTracker.MarkCountersRecorded(currentLine.Sequence);
                         continue;
 
                     case BatchLinePreparationKind.ParseError:
                     case BatchLinePreparationKind.Command:
                         RecordPreparedBatchLine(producer.State, preparation);
+                        producer.ReplayTracker.MarkCountersRecorded(currentLine.Sequence);
                         BatchParallelItemPreparedForTesting?.Invoke(item.LineNumber);
-                        await producer.Output.WriteAsync(item, producer.StopToken)
+                        await producer.Output.WriteAsync(
+                                pendingItem,
+                                producer.Cancellation.StopToken)
                             .ConfigureAwait(false);
                         continue;
 
@@ -200,9 +224,9 @@ await producer.Output.WriteAsync(item, producer.StopToken)
 
             producer.Output.TryComplete();
         }
-        catch (OperationCanceledException) when (producer.ReadToken.IsCancellationRequested)
+        catch (OperationCanceledException) when (producer.Cancellation.ReadToken.IsCancellationRequested)
         {
-            if (producer.CallerToken.IsCancellationRequested)
+            if (producer.Cancellation.CallerToken.IsCancellationRequested)
                 producer.State.CancellationObserved = true;
             producer.Output.TryComplete();
         }
@@ -215,7 +239,7 @@ await producer.Output.WriteAsync(item, producer.StopToken)
 
     private static void ConsumeBatchItemsInOrder(
         in BatchParallelConsumerPlan consumer,
-        ChannelReader<BatchPendingItem> input,
+        ChannelReader<BatchParallelPendingItem> input,
         Queue<BatchActiveItem> active)
     {
         while (!consumer.State.OutputLimitReached)
@@ -238,12 +262,14 @@ private static void ConsumeBatchItemsInOrder(
 
     private static void FillBatchWorkerQueue(
         in BatchParallelConsumerPlan consumer,
-        ChannelReader<BatchPendingItem> input,
+        ChannelReader<BatchParallelPendingItem> input,
         Queue<BatchActiveItem> active)
     {
         while (active.Count < consumer.ExecutionPlan.Parallelism
-               && input.TryRead(out var item))
+               && input.TryRead(out var pendingItem))
         {
+            consumer.ReplayTracker.Commit(pendingItem.InputSequence);
+            var item = pendingItem.Item;
             BatchParallelSession? session = null;
             Task<BatchParallelCommandResult?> result;
             if (item.Error is not null)
@@ -280,7 +306,7 @@ private static void FillBatchWorkerQueue(
 
     private static bool ShouldConsumeOldestBatchItem(
         in BatchParallelConsumerPlan consumer,
-        ChannelReader<BatchPendingItem> input,
+        ChannelReader<BatchParallelPendingItem> input,
         Queue<BatchActiveItem> active)
         => active.Count > 0
            && (active.Peek().Result.IsCompleted
@@ -368,7 +394,7 @@ private static void ConsumeOldestBatchItem(
     }
 
     private static bool WaitForBatchInputOrOldestWorker(
-        ChannelReader<BatchPendingItem> input,
+        ChannelReader<BatchParallelPendingItem> input,
         Queue<BatchActiveItem> active)
     {
         using var waitCancellation = new CancellationTokenSource();
@@ -499,8 +525,12 @@ private readonly record struct BatchParallelProducerPlan(
         BatchExecutionPlan ExecutionPlan,
         JsonSerializerOptions JsonOptions,
         BatchExecutionState State,
+        BatchParallelReplayTracker ReplayTracker,
         BatchInputPump Input,
-        ChannelWriter<BatchPendingItem> Output,
+        ChannelWriter<BatchParallelPendingItem> Output,
+        BatchParallelProducerCancellation Cancellation);
+
+    private readonly record struct BatchParallelProducerCancellation(
         CancellationToken StopToken,
         CancellationToken ReadToken,
         CancellationToken CallerToken);
@@ -512,6 +542,7 @@ private readonly record struct BatchParallelConsumerPlan(
         Queue<BatchParallelSession> AvailableSessions,
         BatchParallelOutputServices Output,
         BatchExecutionState State,
+        BatchParallelReplayTracker ReplayTracker,
         CancellationToken CancellationToken);
 
     private readonly record struct BatchParallelOutputServices(
@@ -523,4 +554,123 @@ private readonly record struct BatchActiveItem(
         BatchPendingItem Item,
         Task<BatchParallelCommandResult?> Result,
         BatchParallelSession? Session);
+
+    private readonly record struct BatchParallelPendingItem(
+        BatchPendingItem Item,
+        long InputSequence);
+
+    private readonly record struct BatchParallelReplayEntry(
+        BatchPumpedLine Input,
+        BatchLinePreparationKind Preparation,
+        bool CountersRecorded);
+
+    private sealed class BatchParallelReplayTracker
+    {
+        // A bounded channel slot, the producer's local item, and the consumer's
+        // just-read item can overlap until the consumer records its commit.
+        private const int Capacity = 3;
+        private readonly object _gate = new();
+        private readonly List<BatchParallelReplayEntry> _uncommitted = new(Capacity);
+
+        public void Register(
+            in BatchPumpedLine input,
+            BatchLinePreparationKind preparation)
+        {
+            lock (_gate)
+            {
+                if (_uncommitted.Count == Capacity)
+                {
+                    throw new InvalidOperationException(
+                        "Parallel batch input ownership exceeded its bounded channel window.");
+                }
+
+                _uncommitted.Add(new BatchParallelReplayEntry(
+                    input,
+                    preparation,
+                    CountersRecorded: false));
+            }
+        }
+
+        public void MarkCountersRecorded(long sequence)
+        {
+            lock (_gate)
+            {
+                for (var index = 0; index < _uncommitted.Count; index++)
+                {
+                    var entry = _uncommitted[index];
+                    if (entry.Input.Sequence != sequence)
+                        continue;
+
+                    _uncommitted[index] = entry with { CountersRecorded = true };
+                    return;
+                }
+
+                // The consumer can commit the line immediately after the
+                // channel write completes, before the producer reaches here.
+                // A committed line no longer needs rollback metadata.
+            }
+        }
+
+        public void Commit(long sequence)
+        {
+            lock (_gate)
+            {
+                for (var index = 0; index < _uncommitted.Count; index++)
+                {
+                    if (_uncommitted[index].Input.Sequence != sequence)
+                        continue;
+
+                    _uncommitted.RemoveAt(index);
+                    return;
+                }
+            }
+
+            throw new InvalidOperationException(
+                "Parallel batch input was dispatched without a matching ownership lease.");
+        }
+
+        public BatchPumpedLine[] TakeForReplay(BatchExecutionState state)
+        {
+            BatchParallelReplayEntry[] entries;
+            lock (_gate)
+            {
+                entries = [.. _uncommitted];
+                _uncommitted.Clear();
+            }
+
+            Array.Sort(
+                entries,
+                static (left, right) => left.Input.Sequence.CompareTo(right.Input.Sequence));
+            var replay = new BatchPumpedLine[entries.Length];
+            for (var index = 0; index < entries.Length; index++)
+            {
+                var entry = entries[index];
+                replay[index] = entry.Input;
+                state.InputLinesRead--;
+                if (!entry.CountersRecorded)
+                    continue;
+
+                if (entry.Preparation == BatchLinePreparationKind.Command)
+                {
+                    state.CommandsProcessed--;
+                }
+                else
+                {
+                    state.LineErrors--;
+                    if (entry.Preparation == BatchLinePreparationKind.InputLimit)
+                        state.InputLimitReached = false;
+                }
+            }
+
+            if (state.InputLinesRead < 0
+                || state.CommandsProcessed < 0
+                || state.LineErrors < 0)
+            {
+                throw new InvalidOperationException(
+                    "Parallel batch replay produced invalid committed counters.");
+            }
+
+            return replay;
+        }
+    }
 }
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerBatchIssue4871Tests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerBatchIssue4871Tests.cs
index 9a63c8abc..88c97bc5d 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerBatchIssue4871Tests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerBatchIssue4871Tests.cs
@@ -663,8 +663,8 @@ public async Task RunBatch_ParallelOutputLimitDrainsActiveWorkersAndRestoresCons
                 Assert.Equal(2, lines.Count);
                 var firstSummary = lines[1].RootElement;
                 Assert.Equal("batch_summary", firstSummary.GetProperty("record").GetString());
-                Assert.Equal(4, firstSummary.GetProperty("input_lines_read").GetInt32());
-                Assert.Equal(3, firstSummary.GetProperty("commands_processed").GetInt32());
+                Assert.Equal(2, firstSummary.GetProperty("input_lines_read").GetInt32());
+                Assert.Equal(2, firstSummary.GetProperty("commands_processed").GetInt32());
                 Assert.Equal(0, firstSummary.GetProperty("line_errors").GetInt32());
                 Assert.Equal(1, firstSummary.GetProperty("command_failures").GetInt32());
                 Assert.True(firstSummary.GetProperty("output_limit_reached").GetBoolean());
@@ -692,6 +692,128 @@ public async Task RunBatch_ParallelOutputLimitDrainsActiveWorkersAndRestoresCons
         }
     }
 
+    [Fact]
+    public async Task RunBatch_ParallelOutputLimitPreservesAcceptedUndispatchedRecordsForNextInvocation()
+    {
+        using var project = TestProjectHelper.CreateTempProjectScope("cdidx_batch_output_limit_replay");
+        var dbPath = TestProjectHelper.CreateProjectDb(project.Root);
+        using var bothStarted = new CountdownEvent(2);
+        using var releaseWorkers = new ManualResetEventSlim();
+        using var fourthPrepared = new ManualResetEventSlim();
+        using var stdout = new StringWriter();
+        using var stderr = new StringWriter();
+        Task<(int First, int Second)>? runs = null;
+
+        QueryCommandRunner.BatchParallelCommandStartedForTesting = _ =>
+        {
+            bothStarted.Signal();
+            if (!bothStarted.Wait(TimeSpan.FromSeconds(15)))
+                throw new TimeoutException("Both replay batch workers did not start.");
+            if (!releaseWorkers.Wait(TimeSpan.FromSeconds(15)))
+                throw new TimeoutException("The fourth replay batch item was not prepared.");
+        };
+        QueryCommandRunner.BatchParallelItemPreparedForTesting = lineNumber =>
+        {
+            if (lineNumber != 4)
+                return;
+            fourthPrepared.Set();
+            releaseWorkers.Set();
+        };
+
+        try
+        {
+            runs = Task.Factory.StartNew(
+                () =>
+                {
+                    using var capture = ConsoleCapture.Start(
+                        stdout,
+                        stderr,
+                        new StringReader(
+                            """
+                            ["search","batch-replay-original-1","--json"]
+                            ["search","batch-replay-original-2","--json"]
+                            ["search","batch-replay-original-3","--json"]
+                            ["search","batch-replay-original-4","--json"]
+                            ["search","batch-replay-sentinel-5","--json"]
+                            """ + "\n"));
+                    var first = QueryCommandRunner.RunBatch(
+                        [
+                            "--db", dbPath,
+                            "--json-summary",
+                            "--parallel", "2",
+                            "--max-output-chars", QueryCommandRunner.BatchMinTotalOutputChars.ToString(),
+                        ],
+                        _jsonOptions);
+                    var second = QueryCommandRunner.RunBatch(
+                        ["--db", dbPath, "--json-summary"],
+                        _jsonOptions);
+                    return (first, second);
+                },
+                CancellationToken.None,
+                TaskCreationOptions.LongRunning,
+                TaskScheduler.Default);
+
+            var (firstExitCode, secondExitCode) = await runs.WaitAsync(TimeSpan.FromSeconds(30));
+            Assert.True(fourthPrepared.IsSet);
+            Assert.Equal(CommandExitCodes.InvalidArgument, firstExitCode);
+            Assert.Equal(CommandExitCodes.Success, secondExitCode);
+            Assert.Equal(string.Empty, stderr.ToString());
+
+            var lines = ParseJsonLines(stdout.ToString());
+            try
+            {
+                Assert.Equal(6, lines.Count);
+                Assert.Equal(
+                    "batch_output_limit",
+                    lines[0].RootElement
+                        .GetProperty("error")
+                        .GetProperty("category")
+                        .GetString());
+
+                var firstSummary = lines[1].RootElement;
+                Assert.Equal("batch_summary", firstSummary.GetProperty("record").GetString());
+                Assert.Equal(2, firstSummary.GetProperty("input_lines_read").GetInt32());
+                Assert.Equal(2, firstSummary.GetProperty("commands_processed").GetInt32());
+                Assert.True(firstSummary.GetProperty("output_limit_reached").GetBoolean());
+
+                var expectedQueries = new[]
+                {
+                    "batch-replay-original-3",
+                    "batch-replay-original-4",
+                    "batch-replay-sentinel-5",
+                };
+                for (var index = 0; index < expectedQueries.Length; index++)
+                {
+                    var record = lines[index + 2].RootElement;
+                    Assert.Equal(index + 1, record.GetProperty("line").GetInt32());
+                    Assert.Equal("search", record.GetProperty("command").GetString());
+                    Assert.Equal(
+                        expectedQueries[index],
+                        record.GetProperty("arguments")[0].GetString());
+                }
+
+                var secondSummary = lines[^1].RootElement;
+                Assert.Equal("batch_summary", secondSummary.GetProperty("record").GetString());
+                Assert.Equal(3, secondSummary.GetProperty("input_lines_read").GetInt32());
+                Assert.Equal(3, secondSummary.GetProperty("commands_processed").GetInt32());
+                Assert.False(secondSummary.GetProperty("output_limit_reached").GetBoolean());
+            }
+            finally
+            {
+                foreach (var document in lines)
+                    document.Dispose();
+            }
+        }
+        finally
+        {
+            QueryCommandRunner.BatchParallelCommandStartedForTesting = null;
+            QueryCommandRunner.BatchParallelItemPreparedForTesting = null;
+            releaseWorkers.Set();
+            if (runs is not null)
+                await runs.WaitAsync(TimeSpan.FromSeconds(15));
+        }
+    }
+
     private sealed class BlockingBatchReader : TextReader
     {
         private const string DeferredLine = "42\n";

From 1be759f418a5089726591ab6f0512716d65c27f9 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 03:43:06 +0900
Subject: [PATCH 38/45] Consolidate search recipe query execution

---
 TESTING_GUIDE.md                              |   2 +
 ...ueryCommandRunner.SearchRecipeExecution.cs | 488 ++++++++++++++++++
 .../Cli/QueryCommandRunner.SearchRecipes.cs   | 470 -----------------
 .../QueryCommandRunnerSearchTests.cs          | 227 +++++++-
 4 files changed, 700 insertions(+), 487 deletions(-)
 create mode 100644 src/CodeIndex/Cli/QueryCommandRunner.SearchRecipeExecution.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 4d54bde02..16af8a5b3 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -267,6 +267,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   Keep long multiline declaration/assignment continuations, declaration types split from their constructors, fully qualified local declaration types, generic-wrapper expression-bodied return types whose audited type occupies a non-terminal argument, and generic return types split before the audited type as positive JSON trust-boundary controls so formatting, qualification, and wrapper shape cannot change annotation binding. Keep overlapping child-query substrings on one call as a negative reuse control so only the first lexical match consumes the annotation.
   MCP schema-origin coverage keeps identical audit phrases in `McpToolCatalog.cs` top-level tool descriptions, concatenated description segments, nested schema-property prose, and executable C# in one indexed fixture; assert explicit `schema_description` search metadata and the recipe's JSON, SARIF, and issue-draft outputs so origin filtering cannot drift across projections.
   Recipe row-selection coverage reuses one multi-file, multi-chunk fixture across aggregate JSON, compact JSON, NDJSON, and issue-draft source metadata. Assert emitted/matched/omitted counts, `selection_reason` / `selection_omitted_count`, first-per-file path uniqueness, selector-preserving replay commands, suppressed raw cursors when a later limit truncates selected rows, and rejection of incoming cursors with either selector. A separate candidate-window fixture must exceed the default low-limit fetch envelope and prove that `--sample <n>` observes at least its requested candidate target; validate rejected selectors for non-row recipe shapes without opening a database.
+  Recipe query-driver parity coverage must share one indexed fixture across full JSON, compact JSON, count-summary JSON, and file aggregation, retaining the intended match while suppressing semantic-safe operations, bounded-alias files, and comment-only origins. Assert matching freshness counts in row/count projections and keep classified child failures invalid in freshness while omitting their result DTOs.
   Unused default-suppression row, JSON count, summary-only, and text count envelopes, including the `--all` count control, share one unused-symbol fixture.
   Unused default-suppressed and `--all` JSON cursor pagination share one unused-symbol fixture.
   Unused full and compact `--by-bucket` JSON envelopes share one taxonomy fixture.
@@ -1333,6 +1334,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   長い複数行へ継続する宣言 / 代入、constructor と別行に分割された宣言型、完全修飾された local 宣言型、audit 対象型が末尾以外の型引数にある generic wrapper を持つ expression-bodied な戻り型、および audit 対象型より前で改行された generic 戻り型を JSON trust-boundary の positive control とし、formatting、修飾、wrapper の形によって注釈の束縛が変わらないことを維持してください。同じ呼び出しで重なる child-query substring は negative reuse control とし、最初の lexical match だけが注釈を消費することを維持してください。
   MCP schema-origin coverage では、同一の audit phrase を `McpToolCatalog.cs` の top-level tool description、連結された description segment、nested schema property の prose、実行可能な C# に置いた1つの indexed fixture を共有し、明示的な `schema_description` 検索 metadata と recipe の JSON、SARIF、issue-draft 出力を検証して、projection 間で origin filter が drift しないようにしてください。
   recipe row-selection coverage は aggregate JSON、compact JSON、NDJSON、issue-draft の source metadata で1つの multi-file / multi-chunk fixture を共有します。emitted / matched / omitted count、`selection_reason` / `selection_omitted_count`、first-per-file の path uniqueness、selector を保持する replay command、後続 limit が選択済み row を truncate する場合の raw cursor 抑止、両 selector と受け取った cursor の併用拒否を検証してください。別の candidate-window fixture では既定の low-limit fetch envelope を超え、`--sample <n>` が少なくとも要求 candidate 数を観測することを証明し、row を持たない recipe shape での selector 拒否は database を開かずに確認してください。
+  recipe query-driver parity coverage は full JSON、compact JSON、count-summary JSON、file aggregation で1つの indexed fixture を共有し、意図した match を保持しつつ、semantic-safe な操作、bounded alias の file、comment-only origin を抑制してください。row / count projection の freshness match count を検証し、分類済み child failure は freshness では invalid のまま、result DTO からは省略されることを確認してください。
   unused default-suppressionのrow、JSON count、summary-only、text count envelopeは、`--all` count controlも含めて1つのunused-symbol fixtureを共有してください。
   unusedのdefault-suppressed JSON cursor paginationと`--all` JSON cursor paginationは1つのunused-symbol fixtureを共有してください。
   unusedのfull JSONとcompact `--by-bucket` JSON envelopeは1つのtaxonomy fixtureを共有してください。
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.SearchRecipeExecution.cs b/src/CodeIndex/Cli/QueryCommandRunner.SearchRecipeExecution.cs
new file mode 100644
index 000000000..ff3f98e04
--- /dev/null
+++ b/src/CodeIndex/Cli/QueryCommandRunner.SearchRecipeExecution.cs
@@ -0,0 +1,488 @@
+using CodeIndex.Database;
+using CodeIndex.Models;
+
+namespace CodeIndex.Cli;
+
+public static partial class QueryCommandRunner
+{
+    private readonly record struct SearchRecipeQueryMaterializationRequest(
+        DbReader Reader,
+        SearchRecipeScopeJsonResult Scope,
+        QueryCommandOptions Options,
+        SearchAuditRecipeQuery RecipeQuery,
+        bool Exact,
+        int? ResultLimit,
+        bool? RawFtsOverride);
+
+    private readonly record struct SearchRecipeQueryMaterializationResult(
+        List<SearchDisplayRow> Rows,
+        bool SourceTotalAuthoritative);
+
+    private static SearchRecipeQueryMaterializationResult MaterializeSearchRecipeQuery(
+        in SearchRecipeQueryMaterializationRequest request)
+    {
+        var queryScope = BuildSearchRecipeQueryScope(request.Scope, request.RecipeQuery);
+        var guardFilters = BuildSearchRecipeGuardFilters(request.Options, request.RecipeQuery);
+        var fetchLimit = request.ResultLimit.HasValue
+            ? GetSearchRecipeFetchLimit(request.Options, request.ResultLimit.Value, request.RecipeQuery)
+            : int.MaxValue;
+        var results = request.Reader.Search(
+            request.RecipeQuery.Query,
+            fetchLimit,
+            request.Options.Lang,
+            false,
+            queryScope.PathPatterns,
+            queryScope.ExcludePaths,
+            queryScope.ExcludeTests,
+            !request.Options.NoDedup,
+            request.Options.Since,
+            request.Exact,
+            false,
+            !request.Options.NoVisibilityRank,
+            cursor: request.Options.SearchCursor,
+            guardFilters: guardFilters,
+            guardWindow: request.Options.GuardWindow,
+            guardScope: request.Options.GuardScope,
+            requiredPathPatterns: GetSearchRecipeRequiredPathPatterns(request.Options, request.RecipeQuery),
+            resultRanking: request.ResultLimit.HasValue
+                ? GetSearchRecipeResultRanking(request.RecipeQuery.ResultRanking, request.ResultLimit.Value)
+                : SearchResultRanking.Default);
+        var sourceTotalAuthoritative = request.ResultLimit.HasValue
+            && IsSearchRecipeSourceTotalAuthoritative(
+                request.Options,
+                request.RecipeQuery,
+                guardFilters,
+                results.Count,
+                fetchLimit);
+        results = ApplySearchRecipeFileRejectQueries(
+            request.Reader,
+            results,
+            request.Options,
+            request.RecipeQuery);
+        var rows = BuildSearchDisplayRows(
+            results,
+            request.Options,
+            request.Exact,
+            request.RecipeQuery.Query,
+            rawFtsOverride: request.RawFtsOverride,
+            recipeQuery: request.RecipeQuery);
+        rows = ApplySearchRecipeSemanticFilter(
+            request.Reader,
+            request.Options,
+            request.RecipeQuery,
+            rows);
+        return new SearchRecipeQueryMaterializationResult(rows, sourceTotalAuthoritative);
+    }
+
+    private static List<SearchRecipeQueryResultJsonResult> CollectSearchRecipeQueryResults(
+        DbReader reader,
+        IReadOnlyList<SearchAuditRecipeQuery> recipeQueries,
+        SearchRecipeScopeJsonResult scope,
+        QueryCommandOptions options,
+        bool userExact,
+        SearchQueryFreshnessContext? freshnessContext,
+        bool includeAuditClassifications,
+        out int total,
+        out int minimumMatchedTotal,
+        out List<SearchQueryFreshnessObservation> freshnessObservations,
+        out bool hasFailures)
+    {
+        var queryResults = new List<SearchRecipeQueryResultJsonResult>();
+        freshnessObservations = [];
+        total = 0;
+        minimumMatchedTotal = 0;
+        hasFailures = false;
+        foreach (var recipeQuery in recipeQueries)
+        {
+            try
+            {
+                var exact = userExact || recipeQuery.ExactSubstring;
+                var resultLimit = GetSearchRecipeEffectiveResultLimit(options, total);
+                var materializationRequest = new SearchRecipeQueryMaterializationRequest(
+                    reader,
+                    scope,
+                    options,
+                    recipeQuery,
+                    exact,
+                    resultLimit,
+                    RawFtsOverride: false);
+                var materialization = MaterializeSearchRecipeQuery(in materializationRequest);
+                var rows = materialization.Rows;
+                var summaryEvidencePaths = BuildSearchRecipeTopFiles(rows);
+                var summaryEvidencePathCount = rows
+                    .Select(row => row.Result.Path)
+                    .Where(path => !string.IsNullOrWhiteSpace(path))
+                    .Distinct(StringComparer.Ordinal)
+                    .Count();
+                var outputSelection = ApplySearchOutputSelection(
+                    rows,
+                    options,
+                    resultLimit,
+                    materialization.SourceTotalAuthoritative);
+                rows = outputSelection.Rows;
+                if (includeAuditClassifications)
+                    ApplySearchRecipeAuditClassifications(reader, recipeQuery, recipeQueries, rows);
+                var minimumOmitted = Math.Max(0, outputSelection.OriginalCount - rows.Count);
+                var selectionReason = GetSearchRecipeSelectionReason(outputSelection);
+                total += rows.Count;
+                minimumMatchedTotal += outputSelection.OriginalCount;
+                queryResults.Add(new SearchRecipeQueryResultJsonResult(
+                    recipeQuery.Name,
+                    recipeQuery.Query,
+                    recipeQuery.Description,
+                    recipeQuery.RecommendedLabels,
+                    recipeQuery.FalsePositiveGuidance,
+                    [.. recipeQuery.RiskEvidence],
+                    ToSearchRecipeGuardFilterJsonResults(recipeQuery.GuardFilters),
+                    exact,
+                    recipeQuery.Severity,
+                    [.. recipeQuery.PathPatterns],
+                    [.. recipeQuery.ExcludePaths],
+                    [.. recipeQuery.MatchOrigins],
+                    [.. recipeQuery.ExcludeOrigins],
+                    [.. recipeQuery.ResultKinds],
+                    [.. recipeQuery.Classifiers],
+                    recipeQuery.StringComparisonTaxonomy,
+                    recipeQuery.BroadCatchTaxonomy,
+                    recipeQuery.NullableContractTaxonomy,
+                    BuildSearchRecipeClassifierCounts(rows),
+                    rows.Count,
+                    rows.Count,
+                    outputSelection.OriginalCount,
+                    minimumOmitted,
+                    selectionReason,
+                    selectionReason != null ? outputSelection.SelectionOmittedCount : null,
+                    resultLimit,
+                    minimumOmitted,
+                    BuildSearchRecipeTopFiles(rows),
+                    outputSelection.LimitTruncated,
+                    outputSelection.LimitTruncated
+                        && !options.FirstPerFile
+                        && !options.SampleSize.HasValue
+                        && rows.Count > 0
+                            ? FormatSearchCursor(rows[^1].Result)
+                            : null,
+                    rows.Select(row => row.Compact).ToList(),
+                    outputSelection.SourceTotal,
+                    outputSelection.SourceTotalAuthoritative,
+                    outputSelection.SourceTotalAuthoritative ? null : outputSelection.SourceTotal,
+                    outputSelection.SelectedTotal,
+                    outputSelection.Returned,
+                    outputSelection.SelectorOmittedCount,
+                    outputSelection.LimitOmittedCount,
+                    outputSelection.Selectors)
+                {
+                    SummaryEvidencePaths = summaryEvidencePaths,
+                    SummaryEvidencePathCount = summaryEvidencePathCount,
+                    SummaryEvidencePathCountAuthoritative = materialization.SourceTotalAuthoritative,
+                });
+                if (freshnessContext != null)
+                {
+                    freshnessObservations.Add(SuccessfulSearchQueryObservation(
+                        freshnessContext,
+                        recipeQuery.Name,
+                        outputSelection.OriginalCount));
+                }
+            }
+            catch (Exception ex) when (
+                freshnessContext != null
+                && TryClassifySearchQueryExecutionFailure(ex, out _))
+            {
+                TryClassifySearchQueryExecutionFailure(ex, out var failureReason);
+                hasFailures = true;
+                freshnessObservations.Add(FailedSearchQueryObservation(
+                    freshnessContext,
+                    recipeQuery.Name,
+                    failureReason));
+            }
+        }
+
+        return queryResults;
+    }
+
+    private static List<SearchRecipeCompactQueryResultJsonResult> CollectSearchRecipeCompactQueryResults(
+        DbReader reader,
+        IReadOnlyList<SearchAuditRecipeQuery> recipeQueries,
+        SearchRecipeScopeJsonResult scope,
+        QueryCommandOptions options,
+        bool userExact,
+        SearchQueryFreshnessContext freshnessContext,
+        out int total,
+        out List<SearchQueryFreshnessObservation> freshnessObservations,
+        out bool hasFailures)
+    {
+        var queryResults = new List<SearchRecipeCompactQueryResultJsonResult>();
+        freshnessObservations = [];
+        total = 0;
+        hasFailures = false;
+        foreach (var recipeQuery in recipeQueries)
+        {
+            try
+            {
+                var exact = userExact || recipeQuery.ExactSubstring;
+                var resultLimit = GetSearchRecipeEffectiveResultLimit(options, total);
+                var materializationRequest = new SearchRecipeQueryMaterializationRequest(
+                    reader,
+                    scope,
+                    options,
+                    recipeQuery,
+                    exact,
+                    resultLimit,
+                    RawFtsOverride: null);
+                var materialization = MaterializeSearchRecipeQuery(in materializationRequest);
+                var rows = materialization.Rows;
+                var outputSelection = ApplySearchOutputSelection(
+                    rows,
+                    options,
+                    resultLimit,
+                    materialization.SourceTotalAuthoritative);
+                rows = outputSelection.Rows;
+                if (!options.SummaryOnly)
+                    ApplySearchRecipeAuditClassifications(reader, recipeQuery, recipeQueries, rows);
+                var minimumOmitted = Math.Max(0, outputSelection.OriginalCount - rows.Count);
+                var selectionReason = GetSearchRecipeSelectionReason(outputSelection);
+                total += rows.Count;
+                queryResults.Add(new SearchRecipeCompactQueryResultJsonResult(
+                    recipeQuery.Name,
+                    recipeQuery.Query,
+                    recipeQuery.Description,
+                    recipeQuery.Severity,
+                    [.. recipeQuery.RiskEvidence],
+                    ToSearchRecipeGuardFilterJsonResults(recipeQuery.GuardFilters),
+                    [.. recipeQuery.PathPatterns],
+                    [.. recipeQuery.ExcludePaths],
+                    [.. recipeQuery.MatchOrigins],
+                    [.. recipeQuery.ExcludeOrigins],
+                    [.. recipeQuery.ResultKinds],
+                    [.. recipeQuery.Classifiers],
+                    recipeQuery.StringComparisonTaxonomy,
+                    recipeQuery.BroadCatchTaxonomy,
+                    BuildSearchRecipeClassifierCounts(rows),
+                    rows.Count,
+                    rows.Count,
+                    outputSelection.OriginalCount,
+                    minimumOmitted,
+                    selectionReason,
+                    selectionReason != null ? outputSelection.SelectionOmittedCount : null,
+                    resultLimit,
+                    minimumOmitted,
+                    BuildSearchRecipeTopFiles(rows),
+                    outputSelection.LimitTruncated,
+                    outputSelection.LimitTruncated
+                        && !options.FirstPerFile
+                        && !options.SampleSize.HasValue
+                        && rows.Count > 0
+                            ? FormatSearchCursor(rows[^1].Result)
+                            : null,
+                    rows.Select(row => new SearchRecipeCompactResultJsonResult(
+                        row.Result.Path,
+                        row.Result.Lang,
+                        row.Result.Visibility,
+                        [.. recipeQuery.RiskEvidence],
+                        row.Result.StartLine,
+                        row.Result.EndLine,
+                        row.Compact.MatchLines,
+                        row.Compact.EnclosingSymbolName,
+                        row.Compact.EnclosingSymbolKind)).ToList(),
+                    outputSelection.SourceTotal,
+                    outputSelection.SourceTotalAuthoritative,
+                    outputSelection.SourceTotalAuthoritative ? null : outputSelection.SourceTotal,
+                    outputSelection.SelectedTotal,
+                    outputSelection.Returned,
+                    outputSelection.SelectorOmittedCount,
+                    outputSelection.LimitOmittedCount,
+                    outputSelection.Selectors));
+                freshnessObservations.Add(SuccessfulSearchQueryObservation(
+                    freshnessContext,
+                    recipeQuery.Name,
+                    outputSelection.OriginalCount));
+            }
+            catch (Exception ex) when (TryClassifySearchQueryExecutionFailure(ex, out _))
+            {
+                TryClassifySearchQueryExecutionFailure(ex, out var failureReason);
+                hasFailures = true;
+                freshnessObservations.Add(FailedSearchQueryObservation(
+                    freshnessContext,
+                    recipeQuery.Name,
+                    failureReason));
+            }
+        }
+
+        return queryResults;
+    }
+
+    private static string? GetSearchRecipeSelectionReason(SearchOutputSelection selection)
+        => selection.SelectionOmittedCount > 0
+            && selection.TruncationReason is "first_per_file" or "sample"
+                ? selection.TruncationReason
+                : null;
+
+    private static bool IsSearchRecipeSourceTotalAuthoritative(
+        QueryCommandOptions options,
+        SearchAuditRecipeQuery recipeQuery,
+        IReadOnlyCollection<SearchGuardFilter> guardFilters,
+        int resultCount,
+        int fetchLimit)
+        => guardFilters.Count == 0
+           && recipeQuery.RejectFileQueries.Count == 0
+           && recipeQuery.SemanticFilter == SearchRecipeSemanticFilter.None
+           && !HasSearchOriginFilters(BuildSearchDisplayFacetFilters(options, recipeQuery))
+           && resultCount < fetchLimit;
+
+    private static int GetSearchRecipeFetchLimit(
+        QueryCommandOptions options,
+        int resultLimit,
+        SearchAuditRecipeQuery? recipeQuery = null)
+    {
+        if (recipeQuery is { SemanticFilter: not SearchRecipeSemanticFilter.None })
+            return int.MaxValue;
+
+        var selectionTarget = resultLimit > 0 && options.SampleSize.HasValue
+            ? Math.Max(resultLimit, options.SampleSize.Value)
+            : resultLimit;
+        return FetchLimitForSearchEnvelope(selectionTarget);
+    }
+
+    private static List<SearchRecipeCountQueryJsonResult> CountSearchRecipeQueryResults(
+        DbReader reader,
+        IReadOnlyList<SearchAuditRecipeQuery> recipeQueries,
+        SearchRecipeScopeJsonResult scope,
+        QueryCommandOptions options,
+        bool userExact,
+        SearchQueryFreshnessContext? freshnessContext,
+        out int total,
+        out int fileCount,
+        out List<SearchQueryFreshnessObservation> freshnessObservations,
+        out bool hasFailures)
+    {
+        var queryCounts = new List<SearchRecipeCountQueryJsonResult>();
+        freshnessObservations = [];
+        var paths = new HashSet<string>(StringComparer.Ordinal);
+        total = 0;
+        hasFailures = false;
+        foreach (var recipeQuery in recipeQueries)
+        {
+            try
+            {
+                var exact = userExact || recipeQuery.ExactSubstring;
+                var materializationRequest = new SearchRecipeQueryMaterializationRequest(
+                    reader,
+                    scope,
+                    options,
+                    recipeQuery,
+                    exact,
+                    ResultLimit: null,
+                    RawFtsOverride: false);
+                var materialization = MaterializeSearchRecipeQuery(in materializationRequest);
+                var rows = materialization.Rows;
+                if (options.Json && !options.SummaryOnly)
+                    ApplySearchRecipeAuditClassifications(reader, recipeQuery, recipeQueries, rows);
+                var count = rows.Count;
+                var fileCountForQuery = rows.Select(row => row.Result.Path).Distinct(StringComparer.Ordinal).Count();
+                foreach (var path in rows.Select(row => row.Result.Path))
+                    paths.Add(path);
+
+                total += count;
+                queryCounts.Add(new SearchRecipeCountQueryJsonResult(
+                    recipeQuery.Name,
+                    recipeQuery.Query,
+                    recipeQuery.Description,
+                    recipeQuery.Severity,
+                    count,
+                    count,
+                    0,
+                    count,
+                    fileCountForQuery,
+                    false,
+                    BuildSearchRecipeClassifierCounts(rows),
+                    BuildSearchRecipeTopFiles(rows)));
+                if (freshnessContext != null)
+                {
+                    freshnessObservations.Add(SuccessfulSearchQueryObservation(
+                        freshnessContext,
+                        recipeQuery.Name,
+                        count));
+                }
+            }
+            catch (Exception ex) when (
+                freshnessContext != null
+                && TryClassifySearchQueryExecutionFailure(ex, out _))
+            {
+                TryClassifySearchQueryExecutionFailure(ex, out var failureReason);
+                hasFailures = true;
+                freshnessObservations.Add(FailedSearchQueryObservation(
+                    freshnessContext,
+                    recipeQuery.Name,
+                    failureReason));
+            }
+        }
+
+        fileCount = paths.Count;
+        return queryCounts;
+    }
+
+    private static List<SearchRecipeAggregationQueryJsonResult> CollectSearchRecipeAggregationResults(
+        DbReader reader,
+        IReadOnlyList<SearchAuditRecipeQuery> recipeQueries,
+        SearchRecipeScopeJsonResult scope,
+        QueryCommandOptions options,
+        bool userExact,
+        string groupBy,
+        out int total,
+        out int fileCount)
+    {
+        var queryResults = new List<SearchRecipeAggregationQueryJsonResult>();
+        var paths = new HashSet<string>(StringComparer.Ordinal);
+        total = 0;
+        foreach (var recipeQuery in recipeQueries)
+        {
+            var exact = userExact || recipeQuery.ExactSubstring;
+            var materializationRequest = new SearchRecipeQueryMaterializationRequest(
+                reader,
+                scope,
+                options,
+                recipeQuery,
+                exact,
+                ResultLimit: null,
+                RawFtsOverride: false);
+            var materialization = MaterializeSearchRecipeQuery(in materializationRequest);
+            var rows = materialization.Rows;
+            foreach (var path in rows.Select(row => row.Result.Path))
+                paths.Add(path);
+
+            var groups = BuildSearchGroupedCounts(groupBy, rows);
+            var selection = ApplySearchGroupOutputSelection(groups, options);
+            total += rows.Count;
+            queryResults.Add(new SearchRecipeAggregationQueryJsonResult(
+                recipeQuery.Name,
+                recipeQuery.Query,
+                recipeQuery.Description,
+                recipeQuery.Severity,
+                rows.Count,
+                rows.Select(row => row.Result.Path).Distinct(StringComparer.Ordinal).Count(),
+                selection.Groups.Count,
+                selection.TotalGroups,
+                selection.Truncated,
+                options.Limit,
+                selection.Groups));
+        }
+
+        fileCount = paths.Count;
+        return queryResults;
+    }
+
+    private static IReadOnlyList<SearchGuardFilter> BuildSearchRecipeGuardFilters(
+        QueryCommandOptions options,
+        SearchAuditRecipeQuery recipeQuery)
+    {
+        if (recipeQuery.GuardFilters.Count == 0)
+            return options.GuardFilters;
+        if (options.GuardFilters.Count == 0)
+            return recipeQuery.GuardFilters;
+
+        var guardFilters = new List<SearchGuardFilter>(recipeQuery.GuardFilters.Count + options.GuardFilters.Count);
+        guardFilters.AddRange(recipeQuery.GuardFilters);
+        guardFilters.AddRange(options.GuardFilters);
+        return guardFilters;
+    }
+}
diff --git a/src/CodeIndex/Cli/QueryCommandRunner.SearchRecipes.cs b/src/CodeIndex/Cli/QueryCommandRunner.SearchRecipes.cs
index 5bdd0252c..0e20add79 100644
--- a/src/CodeIndex/Cli/QueryCommandRunner.SearchRecipes.cs
+++ b/src/CodeIndex/Cli/QueryCommandRunner.SearchRecipes.cs
@@ -2273,400 +2273,6 @@ private static int GetAdHocIssueDraftResultLimit(QueryCommandOptions options)
             ? Math.Min(options.Limit, options.TotalLimit.Value)
             : options.Limit;
 
-    private static List<SearchRecipeQueryResultJsonResult> CollectSearchRecipeQueryResults(
-        DbReader reader,
-        IReadOnlyList<SearchAuditRecipeQuery> recipeQueries,
-        SearchRecipeScopeJsonResult scope,
-        QueryCommandOptions options,
-        bool userExact,
-        SearchQueryFreshnessContext? freshnessContext,
-        bool includeAuditClassifications,
-        out int total,
-        out int minimumMatchedTotal,
-        out List<SearchQueryFreshnessObservation> freshnessObservations,
-        out bool hasFailures)
-    {
-        var queryResults = new List<SearchRecipeQueryResultJsonResult>();
-        freshnessObservations = [];
-        total = 0;
-        minimumMatchedTotal = 0;
-        hasFailures = false;
-        foreach (var recipeQuery in recipeQueries)
-        {
-            try
-            {
-                var exact = userExact || recipeQuery.ExactSubstring;
-                var queryScope = BuildSearchRecipeQueryScope(scope, recipeQuery);
-                var resultLimit = GetSearchRecipeEffectiveResultLimit(options, total);
-                var guardFilters = BuildSearchRecipeGuardFilters(options, recipeQuery);
-                var fetchLimit = GetSearchRecipeFetchLimit(options, resultLimit, recipeQuery);
-                var results = reader.Search(
-                    recipeQuery.Query,
-                    fetchLimit,
-                    options.Lang,
-                    false,
-                    queryScope.PathPatterns,
-                    queryScope.ExcludePaths,
-                    queryScope.ExcludeTests,
-                    !options.NoDedup,
-                    options.Since,
-                    exact,
-                    false,
-                    !options.NoVisibilityRank,
-                    cursor: options.SearchCursor,
-                    guardFilters: guardFilters,
-                    guardWindow: options.GuardWindow,
-                    guardScope: options.GuardScope,
-                    requiredPathPatterns: GetSearchRecipeRequiredPathPatterns(options, recipeQuery),
-                    resultRanking: GetSearchRecipeResultRanking(recipeQuery.ResultRanking, resultLimit));
-                var sourceTotalAuthoritative = IsSearchRecipeSourceTotalAuthoritative(
-                    options,
-                    recipeQuery,
-                    guardFilters,
-                    results.Count,
-                    fetchLimit);
-                results = ApplySearchRecipeFileRejectQueries(reader, results, options, recipeQuery);
-                var rows = BuildSearchDisplayRows(results, options, exact, recipeQuery.Query, rawFtsOverride: false, recipeQuery: recipeQuery);
-                rows = ApplySearchRecipeSemanticFilter(reader, options, recipeQuery, rows);
-                var summaryEvidencePaths = BuildSearchRecipeTopFiles(rows);
-                var summaryEvidencePathCount = rows
-                    .Select(row => row.Result.Path)
-                    .Where(path => !string.IsNullOrWhiteSpace(path))
-                    .Distinct(StringComparer.Ordinal)
-                    .Count();
-                var outputSelection = ApplySearchOutputSelection(rows, options, resultLimit, sourceTotalAuthoritative);
-                rows = outputSelection.Rows;
-                if (includeAuditClassifications)
-                    ApplySearchRecipeAuditClassifications(reader, recipeQuery, recipeQueries, rows);
-                var minimumOmitted = Math.Max(0, outputSelection.OriginalCount - rows.Count);
-                var selectionReason = GetSearchRecipeSelectionReason(outputSelection);
-                total += rows.Count;
-                minimumMatchedTotal += outputSelection.OriginalCount;
-                queryResults.Add(new SearchRecipeQueryResultJsonResult(
-                    recipeQuery.Name,
-                    recipeQuery.Query,
-                    recipeQuery.Description,
-                    recipeQuery.RecommendedLabels,
-                    recipeQuery.FalsePositiveGuidance,
-                    [.. recipeQuery.RiskEvidence],
-                    ToSearchRecipeGuardFilterJsonResults(recipeQuery.GuardFilters),
-                    exact,
-                    recipeQuery.Severity,
-                    [.. recipeQuery.PathPatterns],
-                    [.. recipeQuery.ExcludePaths],
-                    [.. recipeQuery.MatchOrigins],
-                    [.. recipeQuery.ExcludeOrigins],
-                    [.. recipeQuery.ResultKinds],
-                    [.. recipeQuery.Classifiers],
-                    recipeQuery.StringComparisonTaxonomy,
-                    recipeQuery.BroadCatchTaxonomy,
-                    recipeQuery.NullableContractTaxonomy,
-                    BuildSearchRecipeClassifierCounts(rows),
-                    rows.Count,
-                    rows.Count,
-                    outputSelection.OriginalCount,
-                    minimumOmitted,
-                    selectionReason,
-                    selectionReason != null ? outputSelection.SelectionOmittedCount : null,
-                    resultLimit,
-                    minimumOmitted,
-                    BuildSearchRecipeTopFiles(rows),
-                    outputSelection.LimitTruncated,
-                    outputSelection.LimitTruncated
-                        && !options.FirstPerFile
-                        && !options.SampleSize.HasValue
-                        && rows.Count > 0
-                            ? FormatSearchCursor(rows[^1].Result)
-                            : null,
-                    rows.Select(row => row.Compact).ToList(),
-                    outputSelection.SourceTotal,
-                    outputSelection.SourceTotalAuthoritative,
-                    outputSelection.SourceTotalAuthoritative ? null : outputSelection.SourceTotal,
-                    outputSelection.SelectedTotal,
-                    outputSelection.Returned,
-                    outputSelection.SelectorOmittedCount,
-                    outputSelection.LimitOmittedCount,
-                    outputSelection.Selectors)
-                {
-                    SummaryEvidencePaths = summaryEvidencePaths,
-                    SummaryEvidencePathCount = summaryEvidencePathCount,
-                    SummaryEvidencePathCountAuthoritative = sourceTotalAuthoritative,
-                });
-                if (freshnessContext != null)
-                {
-                    freshnessObservations.Add(SuccessfulSearchQueryObservation(
-                        freshnessContext,
-                        recipeQuery.Name,
-                        outputSelection.OriginalCount));
-                }
-            }
-            catch (Exception ex) when (
-                freshnessContext != null
-                && TryClassifySearchQueryExecutionFailure(ex, out _))
-            {
-                TryClassifySearchQueryExecutionFailure(ex, out var failureReason);
-                hasFailures = true;
-                freshnessObservations.Add(FailedSearchQueryObservation(
-                    freshnessContext,
-                    recipeQuery.Name,
-                    failureReason));
-            }
-        }
-
-        return queryResults;
-    }
-
-    private static List<SearchRecipeCompactQueryResultJsonResult> CollectSearchRecipeCompactQueryResults(
-        DbReader reader,
-        IReadOnlyList<SearchAuditRecipeQuery> recipeQueries,
-        SearchRecipeScopeJsonResult scope,
-        QueryCommandOptions options,
-        bool userExact,
-        SearchQueryFreshnessContext freshnessContext,
-        out int total,
-        out List<SearchQueryFreshnessObservation> freshnessObservations,
-        out bool hasFailures)
-    {
-        var queryResults = new List<SearchRecipeCompactQueryResultJsonResult>();
-        freshnessObservations = [];
-        total = 0;
-        hasFailures = false;
-        foreach (var recipeQuery in recipeQueries)
-        {
-            try
-            {
-                var exact = userExact || recipeQuery.ExactSubstring;
-                var queryScope = BuildSearchRecipeQueryScope(scope, recipeQuery);
-                var resultLimit = GetSearchRecipeEffectiveResultLimit(options, total);
-                var guardFilters = BuildSearchRecipeGuardFilters(options, recipeQuery);
-                var fetchLimit = GetSearchRecipeFetchLimit(options, resultLimit, recipeQuery);
-                var results = reader.Search(
-                    recipeQuery.Query,
-                    fetchLimit,
-                    options.Lang,
-                    false,
-                    queryScope.PathPatterns,
-                    queryScope.ExcludePaths,
-                    queryScope.ExcludeTests,
-                    !options.NoDedup,
-                    options.Since,
-                    exact,
-                    false,
-                    !options.NoVisibilityRank,
-                    cursor: options.SearchCursor,
-                    guardFilters: guardFilters,
-                    guardWindow: options.GuardWindow,
-                    guardScope: options.GuardScope,
-                    requiredPathPatterns: GetSearchRecipeRequiredPathPatterns(options, recipeQuery),
-                    resultRanking: GetSearchRecipeResultRanking(recipeQuery.ResultRanking, resultLimit));
-                var sourceTotalAuthoritative = IsSearchRecipeSourceTotalAuthoritative(
-                    options,
-                    recipeQuery,
-                    guardFilters,
-                    results.Count,
-                    fetchLimit);
-                results = ApplySearchRecipeFileRejectQueries(reader, results, options, recipeQuery);
-                var rows = BuildSearchDisplayRows(results, options, exact, recipeQuery.Query, recipeQuery: recipeQuery);
-                rows = ApplySearchRecipeSemanticFilter(reader, options, recipeQuery, rows);
-                var outputSelection = ApplySearchOutputSelection(rows, options, resultLimit, sourceTotalAuthoritative);
-                rows = outputSelection.Rows;
-                if (!options.SummaryOnly)
-                    ApplySearchRecipeAuditClassifications(reader, recipeQuery, recipeQueries, rows);
-                var minimumOmitted = Math.Max(0, outputSelection.OriginalCount - rows.Count);
-                var selectionReason = GetSearchRecipeSelectionReason(outputSelection);
-                total += rows.Count;
-                queryResults.Add(new SearchRecipeCompactQueryResultJsonResult(
-                    recipeQuery.Name,
-                    recipeQuery.Query,
-                    recipeQuery.Description,
-                    recipeQuery.Severity,
-                    [.. recipeQuery.RiskEvidence],
-                    ToSearchRecipeGuardFilterJsonResults(recipeQuery.GuardFilters),
-                    [.. recipeQuery.PathPatterns],
-                    [.. recipeQuery.ExcludePaths],
-                    [.. recipeQuery.MatchOrigins],
-                    [.. recipeQuery.ExcludeOrigins],
-                    [.. recipeQuery.ResultKinds],
-                    [.. recipeQuery.Classifiers],
-                    recipeQuery.StringComparisonTaxonomy,
-                    recipeQuery.BroadCatchTaxonomy,
-                    BuildSearchRecipeClassifierCounts(rows),
-                    rows.Count,
-                    rows.Count,
-                    outputSelection.OriginalCount,
-                    minimumOmitted,
-                    selectionReason,
-                    selectionReason != null ? outputSelection.SelectionOmittedCount : null,
-                    resultLimit,
-                    minimumOmitted,
-                    BuildSearchRecipeTopFiles(rows),
-                    outputSelection.LimitTruncated,
-                    outputSelection.LimitTruncated
-                        && !options.FirstPerFile
-                        && !options.SampleSize.HasValue
-                        && rows.Count > 0
-                            ? FormatSearchCursor(rows[^1].Result)
-                            : null,
-                    rows.Select(row => new SearchRecipeCompactResultJsonResult(
-                        row.Result.Path,
-                        row.Result.Lang,
-                        row.Result.Visibility,
-                        [.. recipeQuery.RiskEvidence],
-                        row.Result.StartLine,
-                        row.Result.EndLine,
-                        row.Compact.MatchLines,
-                        row.Compact.EnclosingSymbolName,
-                        row.Compact.EnclosingSymbolKind)).ToList(),
-                    outputSelection.SourceTotal,
-                    outputSelection.SourceTotalAuthoritative,
-                    outputSelection.SourceTotalAuthoritative ? null : outputSelection.SourceTotal,
-                    outputSelection.SelectedTotal,
-                    outputSelection.Returned,
-                    outputSelection.SelectorOmittedCount,
-                    outputSelection.LimitOmittedCount,
-                    outputSelection.Selectors));
-                freshnessObservations.Add(SuccessfulSearchQueryObservation(
-                    freshnessContext,
-                    recipeQuery.Name,
-                    outputSelection.OriginalCount));
-            }
-            catch (Exception ex) when (TryClassifySearchQueryExecutionFailure(ex, out _))
-            {
-                TryClassifySearchQueryExecutionFailure(ex, out var failureReason);
-                hasFailures = true;
-                freshnessObservations.Add(FailedSearchQueryObservation(
-                    freshnessContext,
-                    recipeQuery.Name,
-                    failureReason));
-            }
-        }
-
-        return queryResults;
-    }
-
-    private static string? GetSearchRecipeSelectionReason(SearchOutputSelection selection)
-        => selection.SelectionOmittedCount > 0
-            && selection.TruncationReason is "first_per_file" or "sample"
-                ? selection.TruncationReason
-                : null;
-
-    private static bool IsSearchRecipeSourceTotalAuthoritative(
-        QueryCommandOptions options,
-        SearchAuditRecipeQuery recipeQuery,
-        IReadOnlyCollection<SearchGuardFilter> guardFilters,
-        int resultCount,
-        int fetchLimit)
-        => guardFilters.Count == 0
-           && recipeQuery.RejectFileQueries.Count == 0
-           && recipeQuery.SemanticFilter == SearchRecipeSemanticFilter.None
-           && !HasSearchOriginFilters(BuildSearchDisplayFacetFilters(options, recipeQuery))
-           && resultCount < fetchLimit;
-
-    private static int GetSearchRecipeFetchLimit(
-        QueryCommandOptions options,
-        int resultLimit,
-        SearchAuditRecipeQuery? recipeQuery = null)
-    {
-        if (recipeQuery is { SemanticFilter: not SearchRecipeSemanticFilter.None })
-            return int.MaxValue;
-
-        var selectionTarget = resultLimit > 0 && options.SampleSize.HasValue
-            ? Math.Max(resultLimit, options.SampleSize.Value)
-            : resultLimit;
-        return FetchLimitForSearchEnvelope(selectionTarget);
-    }
-
-    private static List<SearchRecipeCountQueryJsonResult> CountSearchRecipeQueryResults(
-        DbReader reader,
-        IReadOnlyList<SearchAuditRecipeQuery> recipeQueries,
-        SearchRecipeScopeJsonResult scope,
-        QueryCommandOptions options,
-        bool userExact,
-        SearchQueryFreshnessContext? freshnessContext,
-        out int total,
-        out int fileCount,
-        out List<SearchQueryFreshnessObservation> freshnessObservations,
-        out bool hasFailures)
-    {
-        var queryCounts = new List<SearchRecipeCountQueryJsonResult>();
-        freshnessObservations = [];
-        var paths = new HashSet<string>(StringComparer.Ordinal);
-        total = 0;
-        hasFailures = false;
-        foreach (var recipeQuery in recipeQueries)
-        {
-            try
-            {
-                var exact = userExact || recipeQuery.ExactSubstring;
-                var queryScope = BuildSearchRecipeQueryScope(scope, recipeQuery);
-                var guardFilters = BuildSearchRecipeGuardFilters(options, recipeQuery);
-                var results = reader.Search(
-                    recipeQuery.Query,
-                    int.MaxValue,
-                    options.Lang,
-                    false,
-                    queryScope.PathPatterns,
-                    queryScope.ExcludePaths,
-                    queryScope.ExcludeTests,
-                    !options.NoDedup,
-                    options.Since,
-                    exact,
-                    false,
-                    !options.NoVisibilityRank,
-                    cursor: options.SearchCursor,
-                    guardFilters: guardFilters,
-                    guardWindow: options.GuardWindow,
-                    guardScope: options.GuardScope,
-                    requiredPathPatterns: GetSearchRecipeRequiredPathPatterns(options, recipeQuery));
-                results = ApplySearchRecipeFileRejectQueries(reader, results, options, recipeQuery);
-                var rows = BuildSearchDisplayRows(results, options, exact, recipeQuery.Query, rawFtsOverride: false, recipeQuery: recipeQuery);
-                rows = ApplySearchRecipeSemanticFilter(reader, options, recipeQuery, rows);
-                if (options.Json && !options.SummaryOnly)
-                    ApplySearchRecipeAuditClassifications(reader, recipeQuery, recipeQueries, rows);
-                var count = rows.Count;
-                var fileCountForQuery = rows.Select(row => row.Result.Path).Distinct(StringComparer.Ordinal).Count();
-                foreach (var path in rows.Select(row => row.Result.Path))
-                    paths.Add(path);
-
-                total += count;
-                queryCounts.Add(new SearchRecipeCountQueryJsonResult(
-                    recipeQuery.Name,
-                    recipeQuery.Query,
-                    recipeQuery.Description,
-                    recipeQuery.Severity,
-                    count,
-                    count,
-                    0,
-                    count,
-                    fileCountForQuery,
-                    false,
-                    BuildSearchRecipeClassifierCounts(rows),
-                    BuildSearchRecipeTopFiles(rows)));
-                if (freshnessContext != null)
-                {
-                    freshnessObservations.Add(SuccessfulSearchQueryObservation(
-                        freshnessContext,
-                        recipeQuery.Name,
-                        count));
-                }
-            }
-            catch (Exception ex) when (
-                freshnessContext != null
-                && TryClassifySearchQueryExecutionFailure(ex, out _))
-            {
-                TryClassifySearchQueryExecutionFailure(ex, out var failureReason);
-                hasFailures = true;
-                freshnessObservations.Add(FailedSearchQueryObservation(
-                    freshnessContext,
-                    recipeQuery.Name,
-                    failureReason));
-            }
-        }
-
-        fileCount = paths.Count;
-        return queryCounts;
-    }
-
     private static void ApplySearchRecipeAuditClassifications(
         DbReader reader,
         SearchAuditRecipeQuery recipeQuery,
@@ -4560,82 +4166,6 @@ private sealed class JsonTrustLexicalContextCache
         public JsonTrustLexicalContext? Context { get; set; }
     }
 
-    private static List<SearchRecipeAggregationQueryJsonResult> CollectSearchRecipeAggregationResults(
-        DbReader reader,
-        IReadOnlyList<SearchAuditRecipeQuery> recipeQueries,
-        SearchRecipeScopeJsonResult scope,
-        QueryCommandOptions options,
-        bool userExact,
-        string groupBy,
-        out int total,
-        out int fileCount)
-    {
-        var queryResults = new List<SearchRecipeAggregationQueryJsonResult>();
-        var paths = new HashSet<string>(StringComparer.Ordinal);
-        total = 0;
-        foreach (var recipeQuery in recipeQueries)
-        {
-            var exact = userExact || recipeQuery.ExactSubstring;
-            var queryScope = BuildSearchRecipeQueryScope(scope, recipeQuery);
-            var guardFilters = BuildSearchRecipeGuardFilters(options, recipeQuery);
-            var results = reader.Search(
-                recipeQuery.Query,
-                int.MaxValue,
-                options.Lang,
-                false,
-                queryScope.PathPatterns,
-                queryScope.ExcludePaths,
-                queryScope.ExcludeTests,
-                !options.NoDedup,
-                options.Since,
-                exact,
-                false,
-                !options.NoVisibilityRank,
-                cursor: options.SearchCursor,
-                guardFilters: guardFilters,
-                guardWindow: options.GuardWindow,
-                guardScope: options.GuardScope,
-                requiredPathPatterns: GetSearchRecipeRequiredPathPatterns(options, recipeQuery));
-            results = ApplySearchRecipeFileRejectQueries(reader, results, options, recipeQuery);
-            var rows = BuildSearchDisplayRows(results, options, exact, recipeQuery.Query, rawFtsOverride: false, recipeQuery: recipeQuery);
-            rows = ApplySearchRecipeSemanticFilter(reader, options, recipeQuery, rows);
-            foreach (var path in rows.Select(row => row.Result.Path))
-                paths.Add(path);
-
-            var groups = BuildSearchGroupedCounts(groupBy, rows);
-            var selection = ApplySearchGroupOutputSelection(groups, options);
-            total += rows.Count;
-            queryResults.Add(new SearchRecipeAggregationQueryJsonResult(
-                recipeQuery.Name,
-                recipeQuery.Query,
-                recipeQuery.Description,
-                recipeQuery.Severity,
-                rows.Count,
-                rows.Select(row => row.Result.Path).Distinct(StringComparer.Ordinal).Count(),
-                selection.Groups.Count,
-                selection.TotalGroups,
-                selection.Truncated,
-                options.Limit,
-                selection.Groups));
-        }
-
-        fileCount = paths.Count;
-        return queryResults;
-    }
-
-    private static IReadOnlyList<SearchGuardFilter> BuildSearchRecipeGuardFilters(QueryCommandOptions options, SearchAuditRecipeQuery recipeQuery)
-    {
-        if (recipeQuery.GuardFilters.Count == 0)
-            return options.GuardFilters;
-        if (options.GuardFilters.Count == 0)
-            return recipeQuery.GuardFilters;
-
-        var guardFilters = new List<SearchGuardFilter>(recipeQuery.GuardFilters.Count + options.GuardFilters.Count);
-        guardFilters.AddRange(recipeQuery.GuardFilters);
-        guardFilters.AddRange(options.GuardFilters);
-        return guardFilters;
-    }
-
     private static SearchRecipeRunSummaryJsonResult BuildSearchRecipeRunSummary(
         IReadOnlyList<SearchRecipeQueryResultJsonResult> queryResults,
         int limitPerQuery,
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
index 3868e460c..bc7fb1833 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
@@ -216,7 +216,7 @@ public void RunSearch_RecipeJsonRetainsClassifiedChildFailureAsInvalid_Issue4907
         try
         {
             var dbPath = TestProjectHelper.CreateProjectDb(projectRoot);
-            const int minimumGuardedCandidates = 200;
+            const int minimumGuardedCandidates = DbReader.MaxGuardedSearchCandidates;
             var fixtures = Enumerable.Range(0, minimumGuardedCandidates + 1)
                 .Select(i =>
                 {
@@ -230,20 +230,28 @@ public void RunSearch_RecipeJsonRetainsClassifiedChildFailureAsInvalid_Issue4907
 
             using var env = EnvironmentVariableScope.Capture(SearchAuditRecipes.RecipePathsEnvironmentVariable);
             env.Set(SearchAuditRecipes.RecipePathsEnvironmentVariable, null);
-            string[] BuildArgs(params string[] outputArgs) =>
-            [
-                "--recipe", "broad-token-audit",
-                "--include-query", "token-term-broad",
-                "--include-query", "auth-token",
-                "--db", dbPath,
-                "--limit", "1",
-                "--total-limit", "0",
-                "--require-before", "CDIDX_REVIEW_NO_SUCH_GUARD",
-                "--guard-window", "1",
-                .. outputArgs,
-            ];
+            string[] BuildArgs(string? totalLimit, string limit, params string[] outputArgs)
+            {
+                var args = new List<string>
+                {
+                    "--recipe", "broad-token-audit",
+                    "--include-query", "token-term-broad",
+                    "--include-query", "auth-token",
+                    "--db", dbPath,
+                    "--limit", limit,
+                };
+                if (totalLimit is not null)
+                    args.AddRange(["--total-limit", totalLimit]);
+                args.AddRange(
+                [
+                    "--require-before", "CDIDX_REVIEW_NO_SUCH_GUARD",
+                    "--guard-window", "1",
+                    .. outputArgs,
+                ]);
+                return [.. args];
+            }
             var (exitCode, stdout, stderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
-                BuildArgs("--json"),
+                BuildArgs("0", "1", "--json"),
                 _jsonOptions));
 
             Assert.Equal(CommandExitCodes.UsageError, exitCode);
@@ -267,8 +275,53 @@ string[] BuildArgs(params string[] outputArgs) =>
             Assert.Equal("clean", successfulQuery.GetProperty("freshness_state").GetString());
             Assert.Equal("zero_match", successfulQuery.GetProperty("result_state").GetString());
 
+            foreach (var projection in new[]
+                     {
+                         (TotalLimit: "0", Limit: "1", Args: new[] { "--format", "compact", "--json" }),
+                         (TotalLimit: (string?)null, Limit: "1000", Args: new[] { "--format", "count", "--summary-only", "--json" }),
+                     })
+            {
+                var (projectionExitCode, projectionStdout, projectionStderr) = CaptureConsole(
+                    () => QueryCommandRunner.RunSearch(
+                        BuildArgs(projection.TotalLimit, projection.Limit, projection.Args),
+                        _jsonOptions));
+                Assert.Equal(CommandExitCodes.UsageError, projectionExitCode);
+                Assert.Contains(
+                    "one or more recipe queries failed",
+                    projectionStderr,
+                    StringComparison.Ordinal);
+                using var projectionDocument = ParseJsonOutput(projectionStdout);
+                var projectionRoot = projectionDocument.RootElement;
+                Assert.Equal(2, projectionRoot.GetProperty("query_count").GetInt32());
+                var projectionFreshness = projectionRoot.TryGetProperty("summary", out var projectionSummary)
+                    ? projectionSummary.GetProperty("query_freshness")
+                    : projectionRoot.GetProperty("query_freshness");
+                Assert.Equal("mixed", projectionFreshness.GetProperty("state").GetString());
+                Assert.Contains(
+                    projectionFreshness.GetProperty("invalid_query_names").EnumerateArray(),
+                    name => name.GetString() == "token-term-broad");
+                var failedProjection = Assert.Single(
+                    projectionFreshness.GetProperty("queries").EnumerateArray(),
+                    query => query.GetProperty("name").GetString() == "token-term-broad");
+                Assert.Equal("invalid", failedProjection.GetProperty("freshness_state").GetString());
+                Assert.Equal("query_guard_limit_exceeded", failedProjection.GetProperty("reason").GetString());
+                var successfulFreshness = Assert.Single(
+                    projectionFreshness.GetProperty("queries").EnumerateArray(),
+                    query => query.GetProperty("name").GetString() == "auth-token");
+                Assert.Equal("clean", successfulFreshness.GetProperty("freshness_state").GetString());
+                Assert.Equal("zero_match", successfulFreshness.GetProperty("result_state").GetString());
+                Assert.Equal(0, successfulFreshness.GetProperty("match_count").GetInt32());
+                var successfulProjection = Assert.Single(projectionRoot.GetProperty("queries").EnumerateArray());
+                Assert.Equal("auth-token", successfulProjection.GetProperty("name").GetString());
+                Assert.Equal(0, successfulProjection.GetProperty("count").GetInt32());
+                if (successfulProjection.TryGetProperty("file_count", out var projectionFileCount))
+                    Assert.Equal(0, projectionFileCount.GetInt32());
+                else if (projectionRoot.TryGetProperty("file_count", out var rootFileCount))
+                    Assert.Equal(0, rootFileCount.GetInt32());
+            }
+
             var (sarifExitCode, sarifStdout, sarifStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
-                BuildArgs("--format", "sarif"),
+                BuildArgs("0", "1", "--format", "sarif"),
                 _jsonOptions));
             Assert.Equal(CommandExitCodes.UsageError, sarifExitCode);
             Assert.Contains("one or more recipe queries failed", sarifStderr, StringComparison.Ordinal);
@@ -284,7 +337,7 @@ string[] BuildArgs(params string[] outputArgs) =>
             }
 
             var (draftExitCode, draftStdout, draftStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
-                BuildArgs("--format", "issue-drafts"),
+                BuildArgs("0", "1", "--format", "issue-drafts"),
                 _jsonOptions));
             Assert.Equal(CommandExitCodes.UsageError, draftExitCode);
             Assert.Contains("one or more recipe queries failed", draftStderr, StringComparison.Ordinal);
@@ -299,7 +352,7 @@ string[] BuildArgs(params string[] outputArgs) =>
             }
 
             var (textExitCode, textStdout, textStderr) = CaptureConsole(() => QueryCommandRunner.RunSearch(
-                BuildArgs(),
+                BuildArgs("0", "1"),
                 _jsonOptions));
             Assert.Equal(CommandExitCodes.UsageError, textExitCode);
             Assert.Contains("Invalid queries: token-term-broad", textStdout, StringComparison.Ordinal);
@@ -311,6 +364,146 @@ string[] BuildArgs(params string[] outputArgs) =>
         }
     }
 
+    [Fact]
+    public void RunSearch_RecipeQueryDriversPreserveFilteredRowsAndFreshnessAcrossFormats()
+    {
+        var projectRoot = TestProjectHelper.CreateTempProject("cdidx_recipe_query_driver_parity");
+        try
+        {
+            var dbPath = TestProjectHelper.CreateProjectDb(projectRoot);
+            TestProjectHelper.InsertFreshIndexedFile(
+                projectRoot,
+                dbPath,
+                "src/retained.cs",
+                "csharp",
+                """
+                using System.Text.RegularExpressions;
+
+                public static class Retained
+                {
+                    public static Match Run(string input) => Regex.Match(input, "token");
+                }
+                """);
+            TestProjectHelper.InsertFreshIndexedFile(
+                projectRoot,
+                dbPath,
+                "src/safe.cs",
+                "csharp",
+                """
+                using System.Text.RegularExpressions;
+
+                public static class Safe
+                {
+                    public static string Run(string input) => Regex.Escape(input);
+                }
+                """);
+            TestProjectHelper.InsertFreshIndexedFile(
+                projectRoot,
+                dbPath,
+                "src/bounded.cs",
+                "csharp",
+                """
+                using Regex = CodeIndex.Indexer.BoundedRegex;
+
+                public static class Bounded
+                {
+                    public static object Run(string input) => Regex.Match(input, "token");
+                }
+                """);
+            TestProjectHelper.InsertFreshIndexedFile(
+                projectRoot,
+                dbPath,
+                "src/comment.cs",
+                "csharp",
+                """
+                public static class CommentOnly
+                {
+                    // Regex.Match(input, pattern)
+                }
+                """);
+            using (var db = new DbContext(DbOpenIntent.WriteIndex, dbPath))
+            {
+                db.InitializeSchema();
+                var writer = new DbWriter(db.Connection);
+                writer.MarkGraphReady();
+                writer.SetMeta(
+                    DbContext.ReferenceIdentityContractVersionMetaKey,
+                    DbContext.ReferenceIdentityContractVersion.ToString(
+                        System.Globalization.CultureInfo.InvariantCulture));
+            }
+
+            string[] BaseArgs(params string[] outputArgs) =>
+            [
+                "--recipe", "dogfood-risk-patterns/static-regex-api",
+                "--db", dbPath,
+                "--lang", "csharp",
+                "--limit", "10",
+                .. outputArgs,
+            ];
+
+            foreach (var outputArgs in new[]
+                     {
+                         new[] { "--json" },
+                         new[] { "--format", "compact" },
+                         new[] { "--format", "count", "--summary-only", "--json" },
+                     })
+            {
+                var (exitCode, stdout, stderr) = CaptureConsole(
+                    () => QueryCommandRunner.RunSearch(BaseArgs(outputArgs), _jsonOptions));
+                Assert.Equal(CommandExitCodes.Success, exitCode);
+                Assert.Equal(string.Empty, stderr);
+                using var document = ParseJsonOutput(stdout);
+                var root = document.RootElement;
+                var query = Assert.Single(root.GetProperty("queries").EnumerateArray());
+                Assert.Equal("static-regex-api", query.GetProperty("name").GetString());
+                Assert.Equal(1, query.GetProperty("count").GetInt32());
+                if (query.TryGetProperty("file_count", out var queryFileCount))
+                    Assert.Equal(1, queryFileCount.GetInt32());
+                else if (root.TryGetProperty("file_count", out var rootFileCount))
+                    Assert.Equal(1, rootFileCount.GetInt32());
+                if (query.TryGetProperty("results", out var results))
+                {
+                    var result = Assert.Single(results.EnumerateArray());
+                    Assert.Equal("src/retained.cs", result.GetProperty("path").GetString());
+                }
+
+                var freshness = root.TryGetProperty("summary", out var summary)
+                    ? summary.GetProperty("query_freshness")
+                    : root.GetProperty("query_freshness");
+                Assert.Equal("clean", freshness.GetProperty("state").GetString());
+                var observation = Assert.Single(freshness.GetProperty("queries").EnumerateArray());
+                Assert.Equal("static-regex-api", observation.GetProperty("name").GetString());
+                Assert.Equal("matched", observation.GetProperty("result_state").GetString());
+                Assert.Equal(1, observation.GetProperty("match_count").GetInt32());
+            }
+
+            var (aggregationExitCode, aggregationStdout, aggregationStderr) = CaptureConsole(
+                () => QueryCommandRunner.RunSearch(BaseArgs("--count-by", "file", "--json"), _jsonOptions));
+            Assert.Equal(CommandExitCodes.Success, aggregationExitCode);
+            Assert.Equal(string.Empty, aggregationStderr);
+            using var aggregationDocument = ParseJsonOutput(aggregationStdout);
+            var aggregationRoot = aggregationDocument.RootElement;
+            Assert.Equal("count_by", aggregationRoot.GetProperty("mode").GetString());
+            Assert.Equal("file", aggregationRoot.GetProperty("group_by").GetString());
+            Assert.Equal(1, aggregationRoot.GetProperty("result_count").GetInt32());
+            Assert.Equal(1, aggregationRoot.GetProperty("file_count").GetInt32());
+            var aggregationQuery = Assert.Single(aggregationRoot.GetProperty("queries").EnumerateArray());
+            Assert.Equal("static-regex-api", aggregationQuery.GetProperty("name").GetString());
+            Assert.Equal(1, aggregationQuery.GetProperty("count").GetInt32());
+            Assert.Equal(1, aggregationQuery.GetProperty("file_count").GetInt32());
+            Assert.Equal(1, aggregationQuery.GetProperty("returned_groups").GetInt32());
+            Assert.Equal(1, aggregationQuery.GetProperty("total_groups").GetInt32());
+            Assert.False(aggregationQuery.GetProperty("groups_truncated").GetBoolean());
+            var aggregationGroup = Assert.Single(aggregationQuery.GetProperty("groups").EnumerateArray());
+            Assert.Equal("src/retained.cs", aggregationGroup.GetProperty("file").GetString());
+            Assert.Equal(1, aggregationGroup.GetProperty("count").GetInt32());
+        }
+        finally
+        {
+            TestProjectHelper.DeleteDirectory(projectRoot);
+        }
+    }
+
     [Fact]
     public void SearchMatchClassifier_McpSchemaDescriptionHasDedicatedOrigin_Issues4416_4864()
     {

From 352bfe47c4f468a34b5ce39885a333d1652e8aed Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 04:31:50 +0900
Subject: [PATCH 39/45] Consolidate update file-loop session ownership

---
 TESTING_GUIDE.md                              |    4 +-
 ...Runner.Update.FileLoop.ParallelConsumer.cs |  353 ++++
 ...exCommandRunner.Update.FileLoop.Session.cs |  251 +++
 .../Cli/IndexCommandRunner.Update.FileLoop.cs | 1724 +++++++----------
 ...CommandRunner.Update.ParallelExtraction.cs |  127 --
 .../Cli/IndexCommandRunner.Update.cs          |  138 +-
 .../IndexCommandRunnerUpdateTests.cs          |   52 +
 7 files changed, 1393 insertions(+), 1256 deletions(-)
 create mode 100644 src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.ParallelConsumer.cs
 create mode 100644 src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.Session.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 16af8a5b3..90c70994e 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -224,7 +224,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   YAML `outline` integration coverage must assert nested sequence paths, mapping-parent depth, unchanged source ranges and symbol counts, deterministic sorting, and cursor replay across a page boundary.
   Search-core orchestration coverage must keep validation ahead of database execution, preserve list-recipes > named-query > recipe > plain route precedence and the recipe-field-before-conflict / plain-conflict-before-field aggregation error order, keep count-mode zero/nonzero payloads aligned, retain strict-not-found exit semantics, and order profiled NDJSON as result records, profile metadata, then the terminal record.
   CLI parsing, command execution, and installer behavior. Index command coverage is split by run mode or feature area, and query command coverage is split by command family with partial test classes so shared console and fixture helpers stay centralized. Keep repeated query-result fixtures, such as overlapping chunk content used by multiple search deduplication tests, in narrow class-level helpers instead of duplicating local builders. `ProgramCliTests.cs` covers top-level entrypoint behavior that must be exercised through a subprocess, while `InstallScriptTests.cs` runs focused bash snippets against `install.sh` in library mode to lock in release-installer regressions without performing real network installs. Installer bundle-generation tests must also verify that `install.sh` is marked generated while every canonical `install_modules/` source remains unmarked.
-  Authoritative C# scoped-update coverage treats bounded parallel extraction as a correctness and resource contract. Keep the `2 * workers` window bound, fixed-worker reuse, whole-window extraction barrier, target-ordered single-writer persistence, and mixed-language serial boundary in the same suite. Required fallbacks cover parallelism one, active symbol filters, content-load seams, post-extraction hooks, non-authoritative or undersized snapshots, ambiguous nullable language reuse, and speculative probe exceptions returning to the serial per-file boundary. Serial/parallel parity must compare summaries, files/chunks/all semantic symbol and reference columns, normalized reference-line and candidate identities, hotspot aggregates, issues, readiness/user-version metadata, and last-run readable-byte counters across normal, generated, cap, and oversized inputs. Retain all three file-stat barriers. Cancellation before persistence, after validated load, and at extraction completion must preserve the expected committed prefix, batch ownership, and derived readiness. Global watchdog and direct-fatal tests must assert active phase, bounded return, and terminal side effects; source-negative ordering tests must cover both cap-discarded confirmed evidence and an earlier lexical contract candidate still blocked in symbol extraction. Abnormal-window fixtures release every injected block and wait for the snapshotted all-workers-stopped seam before restoring static hooks or deleting the project root.
+  Authoritative C# scoped-update coverage treats bounded parallel extraction as a correctness and resource contract. Keep the `2 * workers` window bound, fixed-worker reuse, whole-window extraction barrier, target-ordered single-writer persistence, and mixed-language serial boundary in the same suite. Required fallbacks cover parallelism one, active symbol filters, content-load seams, post-extraction hooks, non-authoritative or undersized snapshots, ambiguous nullable language reuse, and speculative probe exceptions returning to the serial per-file boundary. Serial/parallel parity must compare summaries, files/chunks/all semantic symbol and reference columns, normalized reference-line and candidate identities, hotspot aggregates, issues, readiness/user-version metadata, and last-run readable-byte counters across normal, generated, cap, and oversized inputs. Retain all three file-stat barriers. The ordered worker-failure fixture keeps a failed authoritative target, a normal changed target, an unchanged but explicitly targeted authoritative target, and an oversized target in one four-file window; pin the exact persistence-event and commit-hook order, isolated failure phase, incomplete reason, metadata demotion, and separately observed post-update migration-marker cleanup. Cancellation before persistence, after validated load, and at extraction completion must preserve the expected committed prefix, batch ownership, and derived readiness. Global watchdog and direct-fatal tests must assert active phase, bounded return, and terminal side effects; source-negative ordering tests must cover both cap-discarded confirmed evidence and an earlier lexical contract candidate still blocked in symbol extraction. Abnormal-window fixtures release every injected block and wait for the snapshotted all-workers-stopped seam before restoring static hooks or deleting the project root.
   `JsonEnvelopeWrapperTests.cs` owns global JSON-envelope token-role coverage. Keep parser-accepted separated and inline query values, option ordering, the `--` end-of-options form, missing-value boundaries for other value-bearing options, and a genuine `--json-envelope` output request together so preprocessing cannot consume command data, suppress a structured error envelope, or place its injected `--json` after the positional boundary.
   Status-explain coverage must enumerate the source-generated `StatusResult` serializer properties and require every serialized top-level key to succeed without opening a database. Keep major readiness/trust/extension/maintenance/cap-hit metadata assertions, dotted-member resolution, bounded valid unknown candidates, and redaction of hostile field input in the same focused fixture so serialization and explainability cannot drift independently. Keep every structured explain response key registered for status `--fields` projection, and exercise the response through a bounded JSON projection that proves the outer envelope also omits runtime and path metadata.
   Safety-recipe semantic coverage must keep safe and unsafe controls in separate indexed files: assert that `Regex.Escape` / `Regex.Unescape` and literal `UseShellExecute=false` are absent, while matching, source-defined, or unresolved Regex members, literal `true`, and propagated shell-policy values remain with classification evidence. Include alias trivia, alias-like comments and strings, a qualified BCL call in a file with a bare `BoundedRegex` alias, a line break before literal `false`, and computed continuations after block and line comments. Also retain a bare receiver from a legacy index without current reference identity, add enough safe helpers to saturate the normal result envelope, keep count output aligned with full JSON, and retain a separate `new Regex` construction positive.
@@ -1291,7 +1291,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   YAML `outline` の integration coverage では、入れ子 sequence path、mapping parent の depth、不変な source range と symbol count、決定的な sort、page 境界を越える cursor replay を検証してください。
   search core の orchestration coverage では、validation が database execution より先に行われること、list-recipes > named-query > recipe > plain の route precedence と recipe では field error が conflict より先・plain では conflict が field error より先になる aggregation error 順、count mode の zero/nonzero payload、strict-not-found の exit semantics、profile 付き NDJSON が result record、profile metadata、terminal record の順になることを維持してください。
   CLI の引数解析、コマンド実行、installer 挙動のテスト。Index command coverage は run mode または機能領域ごとの partial suite に分割し、Query command coverage は command family ごとの partial test class に分割して、共有 console / fixture helper は一箇所に保ちます。`ProgramCliTests.cs` はグローバル引数の解釈や完全な CLI 起動フローのように subprocess 経由で確認すべき Program エントリポイント挙動を扱い、`InstallScriptTests.cs` は `install.sh` を library mode で source した bash snippet を実行して、実ネットワーク install を行わずに release installer の回帰を固定する。installer bundle 生成テストでは、`install.sh` が generated と判定される一方、canonical な `install_modules/` source はすべて unmarked のままであることも検証してください。
-  authoritative C# scoped update の coverage では、bounded parallel extraction を correctness と resource の契約として扱います。`2 * workers` の window 上限、固定 worker の再利用、window 全体の extraction barrier、target 順の single-writer persistence、mixed-language の serial 境界を同じ suite で維持してください。必須 fallback は parallelism 1、active symbol filter、content-load seam、post-extraction hook、non-authoritative / target 不足 snapshot、ambiguous な nullable language reuse、speculative probe 例外から serial per-file boundary への復帰を含みます。serial / parallel parity は normal、generated、cap、oversized input を横断し、summary、file / chunk、symbol / reference の全 semantic column、正規化した reference-line / candidate identity、hotspot aggregate、issue、readiness / user-version metadata、last-run readable-byte counter を比較してください。3段階の file-stat barrier も維持します。persistence 前、validated load 後、extraction completion 時の cancellation は、想定 committed prefix、batch ownership、derived readiness を固定します。global watchdog と direct fatal は active phase、bounded return、terminal side effect を検証し、source-negative ordering は cap で payload から除かれた confirmed evidence と、symbol extraction 中に block した earlier lexical contract candidate の両方を含めます。異常 window の fixture は注入 block をすべて解放し、snapshot 済み all-workers-stopped seam を待ってから static hook の復元と project root の削除を行ってください。
+  authoritative C# scoped update の coverage では、bounded parallel extraction を correctness と resource の契約として扱います。`2 * workers` の window 上限、固定 worker の再利用、window 全体の extraction barrier、target 順の single-writer persistence、mixed-language の serial 境界を同じ suite で維持してください。必須 fallback は parallelism 1、active symbol filter、content-load seam、post-extraction hook、non-authoritative / target 不足 snapshot、ambiguous な nullable language reuse、speculative probe 例外から serial per-file boundary への復帰を含みます。serial / parallel parity は normal、generated、cap、oversized input を横断し、summary、file / chunk、symbol / reference の全 semantic column、正規化した reference-line / candidate identity、hotspot aggregate、issue、readiness / user-version metadata、last-run readable-byte counter を比較してください。3段階の file-stat barrier も維持します。順序付き worker-failure fixture では、失敗する authoritative target、通常の変更 target、明示対象だが変更なしの authoritative target、oversized target を4-file windowにまとめ、persistence event と commit hook の厳密な順序、分離された failure phase、incomplete reason、metadata demotion、update後に独立観測する migration marker cleanupを固定してください。persistence 前、validated load 後、extraction completion 時の cancellation は、想定 committed prefix、batch ownership、derived readiness を固定します。global watchdog と direct fatal は active phase、bounded return、terminal side effect を検証し、source-negative ordering は cap で payload から除かれた confirmed evidence と、symbol extraction 中に block した earlier lexical contract candidate の両方を含めます。異常 window の fixture は注入 block をすべて解放し、snapshot 済み all-workers-stopped seam を待ってから static hook の復元と project root の削除を行ってください。
   `JsonEnvelopeWrapperTests.cs` は global JSON envelope の token role coverage を担当します。前処理が command data を消費したり、構造化 error envelope を抑止したり、補う `--json` を positional 境界より後ろへ置いたりしないよう、parser が受理する分離形式と inline 形式の query 値、option 順序、`--` end-of-options 形式、他の value-bearing option の missing-value 境界、実際の `--json-envelope` 出力要求を同じ fixture で維持してください。
   status explain の coverage は source-generated `StatusResult` serializer property を列挙し、database を開かずに serialized top-level key がすべて成功することを必須にします。主要な readiness / trust / extension / maintenance / cap-hit metadata、dot 区切り member resolution、unknown key に対する上限付きの有効な candidate、悪意ある field input の redaction を同じ focused fixture に置き、serialization と explainability が独立して drift しないようにしてください。structured explain response の全 key を status の `--fields` projection に登録し、outer envelope からも runtime / path metadata が省略されることを上限付き JSON projection で固定してください。
   safety recipe の意味論 coverage では、安全側と危険側の control を別々の indexed file に置いてください。`Regex.Escape` / `Regex.Unescape` と literal `UseShellExecute=false` が除外され、matching、source-defined、または解決不能な Regex member、literal `true`、伝播された shell-policy 値が classification evidence 付きで残ることを検証します。alias の trivia、alias に見える comment / string、bare `BoundedRegex` alias と完全修飾 BCL call が同居する file、literal `false` の前の改行、block / line comment の後に続く計算式を含めます。また、現行 reference identity を持たない legacy index の bare receiver を残すこと、通常の result envelope を埋める数の safe helper、count 出力と full JSON の一致、別の `new Regex` construction 正例も維持してください。
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.ParallelConsumer.cs b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.ParallelConsumer.cs
new file mode 100644
index 000000000..b255949b6
--- /dev/null
+++ b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.ParallelConsumer.cs
@@ -0,0 +1,353 @@
+using CodeIndex.Indexer;
+
+namespace CodeIndex.Cli;
+
+public static partial class IndexCommandRunner
+{
+    private sealed partial class UpdateFileLoopSession
+    {
+        private void ConsumeParallelUpdateResult(UpdateParallelExtractionResult item)
+        {
+            var target = item.Target;
+            if (cancellationToken.IsCancellationRequested && item.Record != null)
+            {
+                DemoteReadinessOnce();
+                csharpMetadataTargetsNeedRefresh = true;
+            }
+            ThrowIfUpdateCancelled();
+            updateProgress.Start();
+            var relPath = target.RelativePath;
+            currentUpdatePath = relPath;
+            currentUpdatePhase = item.FailurePhase ?? "preparing";
+            var absPath = target.FilePath;
+            var dbPath = target.IndexPath;
+            var fileBatchMarked = false;
+            var csharpWorkspaceSnapshot = csharpWorkspaceSnapshots![dbPath];
+            try
+            {
+                if (item.Record != null)
+                {
+                    readableFileBytes.Remember(item.TargetIndex, item.Record.Size);
+                    if (item.Warning != null && !options.Json && !options.Quiet)
+                    {
+                        updateProgress.Pause();
+                        ConsoleUi.PrintWarning(item.Warning);
+                        updateProgress.Resume();
+                    }
+                    DemoteReadinessOnce();
+                    csharpMetadataTargetsNeedRefresh = true;
+                }
+                var sourceContractSeenBeforeObservation =
+                    postExtractionHooks.Value.SawCSharpStaticInterfaceSourceContract;
+                postExtractionHooks.Value.ObserveCSharpStaticInterfaceSourceContractEvidence(
+                    item.HasCSharpStaticInterfaceSourceContract);
+                if (!csharpWorkspace.HasSourceStaticInterfaceContracts
+                    && !sourceContractSeenBeforeObservation
+                    && postExtractionHooks.Value.SawCSharpStaticInterfaceSourceContract)
+                {
+                    parallelSourceWorkspaceDriftDetected = true;
+                    RecordCSharpWorkspaceDrift(
+                        relPath,
+                        "A C# static-interface contract appeared after workspace preflight.");
+                    skipped++;
+                    return;
+                }
+                if (item.Exception is IndexExtractionStalledException stalledException)
+                {
+                    if (!string.Equals(
+                            item.FailurePhase,
+                            "reading",
+                            StringComparison.Ordinal))
+                    {
+                        DemoteReadinessOnce();
+                        csharpMetadataTargetsNeedRefresh = true;
+                        writer.MarkBatchInProgress();
+                        fileBatchMarked = true;
+                    }
+                    RethrowPreservingStackTrace(
+                        new IndexExtractionStalledException(
+                            updated + removed,
+                            targetPaths.Count,
+                            stalledException.Timeout,
+                            stalledException.ActivePath,
+                            stalledException.WorkerError));
+                }
+                if (item.Exception is CSharpWorkspaceChangedException
+                    or CSharpWorkspaceSnapshotDriftException)
+                {
+                    RecordCSharpWorkspaceDrift(
+                        relPath,
+                        item.Exception.Message,
+                        "reading");
+                    skipped++;
+                    return;
+                }
+                if (item.Exception is FileIndexer.BinaryFileSkippedException
+                    or FileIndexer.FileTooLargeSkippedException)
+                {
+                    var skippedFile = HandleSkippedUpdateFile(
+                        new SkippedUpdateFileHandlingContext
+                        {
+                            Writer = writer,
+                            Indexer = indexer,
+                            Options = options,
+                            AbsolutePath = absPath,
+                            RelativePath = relPath,
+                            IndexPath = dbPath,
+                            KnownLanguage = item.KnownLanguage,
+                            ProjectRootWritten = persistenceOperations.IsProjectRootWritten(),
+                            TargetIndex = item.TargetIndex,
+                            ReadableFileBytes = readableFileBytes,
+                            HasCSharpWorkspaceSnapshot = true,
+                            CSharpWorkspaceSnapshot = csharpWorkspaceSnapshot,
+                            CSharpWorkspaceSnapshots = csharpWorkspaceSnapshots,
+                            WarningList = warningList,
+                            UpdateProgress = updateProgress,
+                            CancellationToken = cancellationToken,
+                            DemoteReadinessOnce = DemoteReadinessOnce,
+                            SetCurrentUpdatePhase =
+                                phase => currentUpdatePhase = phase,
+                            RecordCSharpWorkspaceDrift =
+                                RecordCSharpWorkspaceDrift,
+                            RecordUpdateFileFailure =
+                                RecordUpdateFileFailure,
+                            PurgeStaleUpdateCleanupPaths =
+                                PurgeStaleUpdateCleanupPaths,
+                            RequireTypeScriptAugmentationRefresh =
+                                RequireTypeScriptAugmentationRefresh,
+                            WriteProjectRootOnce = WriteProjectRootOnce,
+                            RecordDynamicGraphFileRefresh =
+                                RecordDynamicGraphFileRefresh,
+                        },
+                        item.Exception);
+                    updated += skippedFile.Updated;
+                    skipped += skippedFile.Skipped;
+                    warnings += skippedFile.Warnings;
+                    mutualRecursionRefreshNeeded |=
+                        skippedFile.MutualRecursionRefreshNeeded;
+                    if (skippedFile.Updated > 0)
+                    {
+                        ftsMutated = true;
+                        parallelExtractionEventForTesting?.Invoke(
+                            new UpdateParallelExtractionTestEvent(
+                                UpdateParallelExtractionEventKind.PersistenceCompleted,
+                                item.TargetIndex,
+                                target.DisplayRelativePath,
+                                WorkerIndex: -1));
+                    }
+                    return;
+                }
+                if (item.Exception is FileNotFoundException or DirectoryNotFoundException)
+                {
+                    RecordCSharpWorkspaceDrift(
+                        relPath,
+                        "The C# file disappeared during its authoritative update pass.");
+                    skipped++;
+                    return;
+                }
+                if (item.Exception != null)
+                {
+                    if (item.Exception is OperationCanceledException)
+                        ThrowIfUpdateCancelled();
+                    if (!string.Equals(
+                            item.FailurePhase,
+                            "reading",
+                            StringComparison.Ordinal))
+                    {
+                        csharpMetadataTargetsNeedRefresh = true;
+                    }
+                    RecordUpdateFileFailure(
+                        relPath,
+                        item.FailurePhase ?? "reading",
+                        item.Exception);
+                    return;
+                }
+
+                var record = item.Record!;
+                currentUpdatePhase = "validating";
+                if (record.Lang != "csharp"
+                    || !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
+                        absPath,
+                        dbPath,
+                        target.DisplayRelativePath,
+                        record.Size,
+                        record.Modified,
+                        csharpWorkspaceSnapshots,
+                        out _,
+                        cancellationToken))
+                {
+                    RecordCSharpWorkspaceDrift(
+                        relPath,
+                        "The C# file changed after extraction and before its authoritative update was persisted.",
+                        "reading");
+                    skipped++;
+                    return;
+                }
+
+                currentUpdatePhase = "reading";
+                parallelExtractionEventForTesting?.Invoke(
+                    new UpdateParallelExtractionTestEvent(
+                        UpdateParallelExtractionEventKind.PersistenceStarted,
+                        item.TargetIndex,
+                        target.DisplayRelativePath,
+                        WorkerIndex: -1));
+                var persistence = PersistPrecomputedUpdateFile(
+                    item,
+                    persistenceOperations.IsProjectRootWritten(),
+                    ref fileBatchMarked);
+                symbolsDroppedByKindFilter +=
+                    persistence.SymbolsDroppedByKindFilter;
+                mutualRecursionRefreshNeeded |=
+                    persistence.MutualRecursionRefreshNeeded;
+                updated++;
+                ftsMutated = true;
+                UpdateFileCommittedForTesting?.Invoke(
+                    updated + removed,
+                    targetPaths.Count);
+                parallelExtractionEventForTesting?.Invoke(
+                    new UpdateParallelExtractionTestEvent(
+                        UpdateParallelExtractionEventKind.PersistenceCompleted,
+                        item.TargetIndex,
+                        target.DisplayRelativePath,
+                        WorkerIndex: -1));
+                ThrowIfUpdateCancelled();
+                updateProgress.WriteVerbose(persistence.VerboseMessage);
+            }
+            catch (IndexExtractionStalledException)
+            {
+                throw;
+            }
+            catch (Exception ex)
+            {
+                if (fileBatchMarked)
+                    writer.ClearBatchInProgress();
+                if (ex is CSharpWorkspaceChangedException)
+                {
+                    RecordCSharpWorkspaceDrift(relPath, ex.Message);
+                    skipped++;
+                    return;
+                }
+                if (ex is OperationCanceledException)
+                    ThrowIfUpdateCancelled();
+                RecordUpdateFileFailure(relPath, currentUpdatePhase, ex);
+            }
+        }
+
+        private void SetUpdatePhase(string path, string phase)
+        {
+            currentUpdatePath = path;
+            currentUpdatePhase = phase;
+        }
+
+        private UpdateFilePersistenceResult PersistPrecomputedUpdateFile(
+            UpdateParallelExtractionResult item,
+            bool projectRootWritten,
+            ref bool fileBatchMarked)
+        {
+            var record = item.Record!;
+            var mutualRecursionRefreshNeeded = false;
+
+            writer.MarkBatchInProgress();
+            fileBatchMarked = true;
+            using var txn = writer.BeginTransaction(
+                cancellationToken,
+                "update precomputed file");
+            var stalePurged = PurgeStaleUpdateCleanupPaths(
+                record.Path,
+                record.Checksum,
+                projectRootWritten);
+            if (stalePurged > 0 && !options.SymbolsOnly)
+                mutualRecursionRefreshNeeded = true;
+            if (stalePurged > 0)
+                RequireTypeScriptAugmentationRefresh();
+            WriteProjectRootOnce();
+            var fileId = writer.UpsertFile(record, out var referenceIdentityChanged);
+            if (!options.SymbolsOnly && referenceIdentityChanged)
+                mutualRecursionRefreshNeeded = true;
+
+            SetUpdatePhase(
+                FormatIndexPhasePath(item.Target.DisplayRelativePath, "chunking"),
+                "chunking");
+            var chunks = ReassignChunkFileIds(item.Chunks!, fileId);
+            if (item.GeneratedSuppressionIssue != null)
+            {
+                writer.InsertChunks(chunks, cancellationToken);
+                writer.InsertSymbols([], cancellationToken);
+                writer.InsertReferencesInAtomicFileScope(
+                    [],
+                    refreshMutualRecursionFlags: false,
+                    cancellationToken);
+                SetUpdatePhase(
+                    FormatIndexPhasePath(item.Target.DisplayRelativePath, "validating"),
+                    "validating");
+                writer.InsertIssues(fileId, item.Issues!);
+                SetUpdatePhase(
+                    FormatIndexPhasePath(item.Target.DisplayRelativePath, "committing"),
+                    "committing");
+                writer.ClearBatchInProgress();
+                txn.Commit();
+                fileBatchMarked = false;
+                RecordDynamicGraphFileRefresh(record.Lang);
+                return new UpdateFilePersistenceResult(
+                    0,
+                    mutualRecursionRefreshNeeded,
+                    $"  [OK  ] {item.Target.RelativePath} ({chunks.Count} chunks, generated-code extraction skipped)");
+            }
+
+            SetUpdatePhase(
+                FormatIndexPhasePath(item.Target.DisplayRelativePath, "symbols"),
+                "symbols");
+            var symbols = ReassignSymbolFileIds(item.Symbols!, fileId);
+            if (item.SymbolCapExceeded)
+            {
+                writer.InsertSymbols([], cancellationToken);
+                writer.InsertReferencesInAtomicFileScope(
+                    [],
+                    refreshMutualRecursionFlags: false,
+                    cancellationToken);
+                writer.InsertIssues(fileId, item.Issues!);
+                writer.ClearBatchInProgress();
+                txn.Commit();
+                fileBatchMarked = false;
+                RecordDynamicGraphFileRefresh(record.Lang);
+                return new UpdateFilePersistenceResult(
+                    0,
+                    mutualRecursionRefreshNeeded,
+                    $"  [SKIP] {item.Target.RelativePath} ({item.Issues![^1].Message})");
+            }
+
+            writer.InsertChunks(chunks, cancellationToken);
+            FileIndexer.ValidateSymbolLineRanges(record, symbols);
+            writer.InsertSymbols(symbols, cancellationToken);
+            SetUpdatePhase(
+                FormatIndexPhasePath(item.Target.DisplayRelativePath, "references"),
+                "references");
+            var references = ReassignReferenceFileIds(item.References!, fileId);
+            writer.InsertReferencesInAtomicFileScope(
+                references,
+                refreshMutualRecursionFlags: false,
+                cancellationToken);
+            SetUpdatePhase(
+                FormatIndexPhasePath(item.Target.DisplayRelativePath, "validating"),
+                "validating");
+            writer.InsertIssues(fileId, item.Issues!);
+            SetUpdatePhase(
+                FormatIndexPhasePath(item.Target.DisplayRelativePath, "committing"),
+                "committing");
+            writer.ClearBatchInProgress();
+            txn.Commit();
+            fileBatchMarked = false;
+            RecordDynamicGraphFileRefresh(record.Lang);
+            if (!options.SymbolsOnly
+                && (symbols.Count > 0 || references.Count > 0))
+            {
+                mutualRecursionRefreshNeeded = true;
+            }
+
+            return new UpdateFilePersistenceResult(
+                0,
+                mutualRecursionRefreshNeeded,
+                $"  [OK  ] {item.Target.RelativePath} ({chunks.Count} chunks, {symbols.Count} symbols, {references.Count} refs)");
+        }
+    }
+}
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.Session.cs b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.Session.cs
new file mode 100644
index 000000000..f5a1c8111
--- /dev/null
+++ b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.Session.cs
@@ -0,0 +1,251 @@
+using System.Diagnostics;
+using CodeIndex.Database;
+using CodeIndex.Diagnostics;
+using CodeIndex.Indexer;
+using CodeIndex.Indexer.Extensibility;
+using CodeIndex.Indexer.Hooks;
+using CodeIndex.Models;
+
+namespace CodeIndex.Cli;
+
+public static partial class IndexCommandRunner
+{
+    private readonly record struct UpdateFileLoopRuntime(
+        DbWriter Writer,
+        FileIndexer Indexer,
+        IndexCommandOptions Options,
+        string ProjectRoot,
+        IndexProgressReporter Progress,
+        CancellationToken CancellationToken,
+        IReadOnlyCollection<string> TargetPaths,
+        List<IndexMemorySampleJsonResult> MemorySamples);
+
+    private record struct UpdateFileLoopCounters(
+        int Updated,
+        int Removed,
+        int Skipped,
+        int Warnings,
+        int Errors,
+        int SymbolsDroppedByKindFilter);
+
+    private record struct UpdateFileLoopRefreshState(
+        bool FtsMutated,
+        bool MutualRecursionRefreshNeeded,
+        bool CSharpMetadataTargetsNeedRefresh,
+        string? CurrentPath,
+        string CurrentPhase,
+        bool ParallelSourceWorkspaceDriftDetected,
+        ReadableFileByteTracker? ReadableFileBytes);
+
+    private readonly record struct UpdateFileLoopWorkspace(
+        CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace,
+        Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>? CSharpWorkspaceSnapshots,
+        IReadOnlyDictionary<string, string>? ScannedUpdateLanguages,
+        bool SymbolKindFilterMatchesPrior,
+        bool CSharpSymbolNameContractMatchesCurrent,
+        bool SqlGraphContractMatchesCurrent,
+        bool HdlGraphContractMatchesCurrent);
+
+    private readonly record struct UpdateFileLoopOutput(
+        Stopwatch Stopwatch,
+        List<string>? IndexRunDiagnostics,
+        LazyDisposable<PostExtractionHookRunner> PostExtractionHooks,
+        HashSet<FileIndexer.FileIdentity> VisitedFileIdentities,
+        List<CliJsonMessage> ErrorList,
+        List<StatusIndexFileError> FileErrorList,
+        List<CliJsonMessage> WarningList);
+
+    private readonly record struct UpdateFileLoopReadinessOperations(
+        Action<IEnumerable<FileIndexer.ScanError>, string> RecordScanErrors,
+        Action<string, string, string> RecordCSharpWorkspaceDrift,
+        Action DemoteReadinessOnce,
+        Action RequireTypeScriptAugmentationRefresh,
+        Action<string?> RecordDynamicGraphFileRefresh);
+
+    private readonly record struct UpdateFileLoopPersistenceOperations(
+        Action WriteProjectRootOnce,
+        Func<string, string?, bool, int> PurgeStaleUpdateCleanupPaths,
+        Func<bool> IsProjectRootWritten);
+
+    private readonly record struct UpdateFileLoopParallelTesting(
+        Action<UpdateParallelExtractionTestEvent>? ExtractionEvent,
+        Func<string, string, Exception?>? ExtractionFailure,
+        Func<TimeSpan>? ExtractionStallTimeout,
+        Action? ExtractionWorkersStopped);
+
+    private readonly record struct UpdateFileLoopRefreshResult(
+        bool FtsMutated,
+        bool MutualRecursionRefreshNeeded,
+        bool CSharpMetadataTargetsNeedRefresh);
+
+    private readonly record struct UpdateFileLoopOutcome(
+        UpdateFileLoopCounters Counters,
+        UpdateFileLoopRefreshResult Refresh,
+        ReadableFileByteTracker ReadableFileBytes);
+
+    private sealed partial class UpdateFileLoopSession
+    {
+        private readonly UpdateFileLoopRuntime runtime;
+        private UpdateFileLoopCounters counters;
+        private UpdateFileLoopRefreshState refresh;
+        private readonly UpdateFileLoopWorkspace workspace;
+        private readonly UpdateFileLoopOutput output;
+        private readonly UpdateFileLoopReadinessOperations readiness;
+        private readonly UpdateFileLoopPersistenceOperations persistenceOperations;
+        private readonly UpdateFileLoopParallelTesting testing;
+
+        internal UpdateFileLoopSession(
+            UpdateFileLoopRuntime runtime,
+            UpdateFileLoopCounters counters,
+            UpdateFileLoopRefreshState refresh,
+            UpdateFileLoopWorkspace workspace,
+            UpdateFileLoopOutput output,
+            UpdateFileLoopReadinessOperations readiness,
+            UpdateFileLoopPersistenceOperations persistence,
+            UpdateFileLoopParallelTesting testing)
+        {
+            this.runtime = runtime;
+            this.counters = counters;
+            this.refresh = refresh;
+            this.workspace = workspace;
+            this.output = output;
+            this.readiness = readiness;
+            persistenceOperations = persistence;
+            this.testing = testing;
+        }
+
+        private DbWriter writer => runtime.Writer;
+        private FileIndexer indexer => runtime.Indexer;
+        private IndexCommandOptions options => runtime.Options;
+        private string projectRoot => runtime.ProjectRoot;
+        private IndexProgressReporter updateProgress => runtime.Progress;
+        private CancellationToken cancellationToken => runtime.CancellationToken;
+        private IReadOnlyCollection<string> targetPaths => runtime.TargetPaths;
+        private List<IndexMemorySampleJsonResult> memorySamples => runtime.MemorySamples;
+        private int updated { get => counters.Updated; set => counters.Updated = value; }
+        private int removed { get => counters.Removed; set => counters.Removed = value; }
+        private int skipped { get => counters.Skipped; set => counters.Skipped = value; }
+        private int warnings { get => counters.Warnings; set => counters.Warnings = value; }
+        private int errors { get => counters.Errors; set => counters.Errors = value; }
+        private int symbolsDroppedByKindFilter
+        {
+            get => counters.SymbolsDroppedByKindFilter;
+            set => counters.SymbolsDroppedByKindFilter = value;
+        }
+        private bool ftsMutated { get => refresh.FtsMutated; set => refresh.FtsMutated = value; }
+        private bool mutualRecursionRefreshNeeded
+        {
+            get => refresh.MutualRecursionRefreshNeeded;
+            set => refresh.MutualRecursionRefreshNeeded = value;
+        }
+        private bool csharpMetadataTargetsNeedRefresh
+        {
+            get => refresh.CSharpMetadataTargetsNeedRefresh;
+            set => refresh.CSharpMetadataTargetsNeedRefresh = value;
+        }
+        private string? currentUpdatePath
+        {
+            get => refresh.CurrentPath;
+            set => refresh.CurrentPath = value;
+        }
+        private string currentUpdatePhase
+        {
+            get => refresh.CurrentPhase;
+            set => refresh.CurrentPhase = value;
+        }
+        private bool parallelSourceWorkspaceDriftDetected
+        {
+            get => refresh.ParallelSourceWorkspaceDriftDetected;
+            set => refresh.ParallelSourceWorkspaceDriftDetected = value;
+        }
+        private ReadableFileByteTracker readableFileBytes
+        {
+            get => refresh.ReadableFileBytes!;
+            set => refresh.ReadableFileBytes = value;
+        }
+        private CSharpStaticInterfaceWorkspaceSymbols csharpWorkspace => workspace.CSharpWorkspace;
+        private Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
+            csharpWorkspaceSnapshots => workspace.CSharpWorkspaceSnapshots;
+        private IReadOnlyDictionary<string, string>? scannedUpdateLanguages
+            => workspace.ScannedUpdateLanguages;
+        private bool symbolKindFilterMatchesPrior => workspace.SymbolKindFilterMatchesPrior;
+        private bool csharpSymbolNameContractMatchesCurrent
+            => workspace.CSharpSymbolNameContractMatchesCurrent;
+        private bool sqlGraphContractMatchesCurrent => workspace.SqlGraphContractMatchesCurrent;
+        private bool hdlGraphContractMatchesCurrent => workspace.HdlGraphContractMatchesCurrent;
+        private Stopwatch stopwatch => output.Stopwatch;
+        private List<string>? indexRunDiagnostics => output.IndexRunDiagnostics;
+        private LazyDisposable<PostExtractionHookRunner> postExtractionHooks
+            => output.PostExtractionHooks;
+        private HashSet<FileIndexer.FileIdentity> visitedFileIdentities
+            => output.VisitedFileIdentities;
+        private List<CliJsonMessage> errorList => output.ErrorList;
+        private List<StatusIndexFileError> fileErrorList => output.FileErrorList;
+        private List<CliJsonMessage> warningList => output.WarningList;
+        private Action<UpdateParallelExtractionTestEvent>? parallelExtractionEventForTesting
+            => testing.ExtractionEvent;
+        private Func<string, string, Exception?>? parallelExtractionFailureForTesting
+            => testing.ExtractionFailure;
+        private Func<TimeSpan>? extractionStallTimeoutForTesting => testing.ExtractionStallTimeout;
+        private Action? parallelExtractionWorkersStoppedForTesting => testing.ExtractionWorkersStopped;
+
+        private void RecordScanErrors(
+            IEnumerable<FileIndexer.ScanError> scanErrors,
+            string fatalPhase = "discovery")
+            => readiness.RecordScanErrors(scanErrors, fatalPhase);
+
+        private void RecordCSharpWorkspaceDrift(
+            string relativePath,
+            string detail,
+            string fatalPhase = "reading")
+            => readiness.RecordCSharpWorkspaceDrift(relativePath, detail, fatalPhase);
+
+        private void DemoteReadinessOnce() => readiness.DemoteReadinessOnce();
+        private void WriteProjectRootOnce() => persistenceOperations.WriteProjectRootOnce();
+        private void RequireTypeScriptAugmentationRefresh()
+            => readiness.RequireTypeScriptAugmentationRefresh();
+
+        private int PurgeStaleUpdateCleanupPaths(
+            string retainedRelativePath,
+            string? checksum,
+            bool includeDirectoryAndStem)
+            => persistenceOperations.PurgeStaleUpdateCleanupPaths(
+                retainedRelativePath,
+                checksum,
+                includeDirectoryAndStem);
+
+        private void RecordDynamicGraphFileRefresh(string? language)
+            => readiness.RecordDynamicGraphFileRefresh(language);
+
+        private void RecordUpdateFileFailure(
+            string relativePath,
+            string phase,
+            Exception exception)
+        {
+            DemoteReadinessOnce();
+            LogIndexFileFailure("index_update_file_failed", relativePath, phase, exception);
+
+            errors++;
+            var errorMessage = FormatIndexFileException(exception);
+            errorList.Add(new CliJsonMessage(relativePath, errorMessage));
+            if (fileErrorList.Count < PartialIndexFileErrorLimit)
+                fileErrorList.Add(BuildIndexFileError(relativePath, phase, exception));
+            if (!options.Json)
+            {
+                updateProgress.Pause();
+                CommandErrorWriter.WriteStderr(
+                    FormatPerFileErrorLine("ERR ", relativePath, exception, errorMessage));
+                updateProgress.Resume();
+            }
+        }
+
+        private void ThrowIfUpdateCancelled()
+        {
+            if (!cancellationToken.IsCancellationRequested)
+                return;
+
+            updateProgress.Pause();
+            throw new IndexInterruptedException(updated + removed, targetPaths.Count);
+        }
+    }
+}
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.cs b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.cs
index 2a42efaae..415e7932e 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.cs
@@ -10,843 +10,490 @@ namespace CodeIndex.Cli;
 
 public static partial class IndexCommandRunner
 {
-    private sealed class UpdateFileLoopContext
+    private sealed partial class UpdateFileLoopSession
     {
-        internal required DbWriter Writer { get; init; }
-        internal required FileIndexer Indexer { get; init; }
-        internal required IndexCommandOptions Options { get; init; }
-        internal required Stopwatch Stopwatch { get; init; }
-        internal required string ProjectRoot { get; init; }
-        internal List<string>? IndexRunDiagnostics { get; init; }
-        internal required IReadOnlyCollection<string> TargetPaths { get; init; }
-        internal required IndexProgressReporter UpdateProgress { get; init; }
-        internal required List<IndexMemorySampleJsonResult> MemorySamples { get; init; }
-        internal required int Updated { get; init; }
-        internal required int Removed { get; init; }
-        internal required int Skipped { get; init; }
-        internal required bool FtsMutated { get; init; }
-        internal required bool MutualRecursionRefreshNeeded { get; init; }
-        internal required bool CSharpMetadataTargetsNeedRefresh { get; init; }
-        internal required int SymbolsDroppedByKindFilter { get; init; }
-        internal required CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace { get; init; }
-        internal Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>? CSharpWorkspaceSnapshots { get; init; }
-        internal IReadOnlyDictionary<string, string>? ScannedUpdateLanguages { get; init; }
-        internal required bool SymbolKindFilterMatchesPrior { get; init; }
-        internal required bool CSharpSymbolNameContractMatchesCurrent { get; init; }
-        internal required bool SqlGraphContractMatchesCurrent { get; init; }
-        internal required bool HdlGraphContractMatchesCurrent { get; init; }
-        internal required LazyDisposable<PostExtractionHookRunner> PostExtractionHooks { get; init; }
-        internal required HashSet<FileIndexer.FileIdentity> VisitedFileIdentities { get; init; }
-        internal required List<CliJsonMessage> ErrorList { get; init; }
-        internal required List<StatusIndexFileError> FileErrorList { get; init; }
-        internal required List<CliJsonMessage> WarningList { get; init; }
-        internal required CancellationToken CancellationToken { get; init; }
-        internal required Action<IEnumerable<FileIndexer.ScanError>, string> RecordScanErrors { get; init; }
-        internal required Action<string, string, string> RecordCSharpWorkspaceDrift { get; init; }
-        internal required Action DemoteReadinessOnce { get; init; }
-        internal required Action WriteProjectRootOnce { get; init; }
-        internal required Action RequireTypeScriptAugmentationRefresh { get; init; }
-        internal required Func<string, string?, bool, int> PurgeStaleUpdateCleanupPaths { get; init; }
-        internal required Action<string?> RecordDynamicGraphFileRefresh { get; init; }
-        internal required Action<string, string, Exception> RecordUpdateFileFailure { get; init; }
-        internal required Func<bool> IsProjectRootWritten { get; init; }
-    }
-
-    private sealed record UpdateFileLoopResult(
-        int Updated,
-        int Removed,
-        int Skipped,
-        int Warnings,
-        int Errors,
-        bool FtsMutated,
-        bool MutualRecursionRefreshNeeded,
-        bool CSharpMetadataTargetsNeedRefresh,
-        int SymbolsDroppedByKindFilter,
-        ReadableFileByteTracker ReadableFileBytes);
-
-    private static UpdateFileLoopResult RunUpdateFileLoop(UpdateFileLoopContext context)
-    {
-        var writer = context.Writer;
-        var indexer = context.Indexer;
-        var options = context.Options;
-        var stopwatch = context.Stopwatch;
-        var projectRoot = context.ProjectRoot;
-        var indexRunDiagnostics = context.IndexRunDiagnostics;
-        var targetPaths = context.TargetPaths;
-        var updateProgress = context.UpdateProgress;
-        var memorySamples = context.MemorySamples;
-        var updated = context.Updated;
-        var removed = context.Removed;
-        var skipped = context.Skipped;
-        var warnings = 0;
-        var errors = 0;
-        var ftsMutated = context.FtsMutated;
-        var mutualRecursionRefreshNeeded = context.MutualRecursionRefreshNeeded;
-        var csharpMetadataTargetsNeedRefresh = context.CSharpMetadataTargetsNeedRefresh;
-        var symbolsDroppedByKindFilter = context.SymbolsDroppedByKindFilter;
-        var csharpWorkspace = context.CSharpWorkspace;
-        var csharpWorkspaceSnapshots = context.CSharpWorkspaceSnapshots;
-        var scannedUpdateLanguages = context.ScannedUpdateLanguages;
-        var symbolKindFilterMatchesPrior = context.SymbolKindFilterMatchesPrior;
-        var csharpSymbolNameContractMatchesCurrent =
-            context.CSharpSymbolNameContractMatchesCurrent;
-        var sqlGraphContractMatchesCurrent = context.SqlGraphContractMatchesCurrent;
-        var hdlGraphContractMatchesCurrent = context.HdlGraphContractMatchesCurrent;
-        var postExtractionHooks = context.PostExtractionHooks;
-        var visitedFileIdentities = context.VisitedFileIdentities;
-        var errorList = context.ErrorList;
-        var fileErrorList = context.FileErrorList;
-        var warningList = context.WarningList;
-        var cancellationToken = context.CancellationToken;
-        var parallelExtractionEventForTesting =
-            UpdateParallelExtractionEventForTesting;
-        var parallelExtractionFailureForTesting =
-            UpdateParallelExtractionFailureForTesting;
-        var extractionStallTimeoutForTesting =
-            IndexExtractionStallTimeoutForTesting;
-        var parallelExtractionWorkersStoppedForTesting =
-            UpdateParallelExtractionWorkersStoppedForTesting;
-
-        void RecordScanErrors(
-            IEnumerable<FileIndexer.ScanError> scanErrors,
-            string fatalPhase = "discovery")
-            => context.RecordScanErrors(scanErrors, fatalPhase);
-
-        void RecordCSharpWorkspaceDrift(
-            string relativePath,
-            string detail,
-            string fatalPhase = "reading")
-            => context.RecordCSharpWorkspaceDrift(relativePath, detail, fatalPhase);
-
-        void DemoteReadinessOnce() => context.DemoteReadinessOnce();
-        void WriteProjectRootOnce() => context.WriteProjectRootOnce();
-        void RequireTypeScriptAugmentationRefresh()
-            => context.RequireTypeScriptAugmentationRefresh();
-
-        int PurgeStaleUpdateCleanupPaths(
-            string retainedRelativePath,
-            string? checksum,
-            bool includeDirectoryAndStem)
-            => context.PurgeStaleUpdateCleanupPaths(
-                retainedRelativePath,
-                checksum,
-                includeDirectoryAndStem);
-
-        void RecordDynamicGraphFileRefresh(string? language)
-            => context.RecordDynamicGraphFileRefresh(language);
-
-        void RecordUpdateFileFailure(
-            string relativePath,
-            string phase,
-            Exception exception)
-            => context.RecordUpdateFileFailure(relativePath, phase, exception);
-
-        void ThrowIfUpdateCancelled()
+        internal UpdateFileLoopOutcome Run()
         {
-            if (!cancellationToken.IsCancellationRequested)
-                return;
-
-            updateProgress.Pause();
-            throw new IndexInterruptedException(updated + removed, targetPaths.Count);
-        }
-
-        updateProgress.Start();
-
-        var updateTargets = new UpdateFileTarget[targetPaths.Count];
-        var updateTargetIndex = 0;
-        foreach (var targetPath in targetPaths)
-            updateTargets[updateTargetIndex++] = UpdateFileTarget.Create(projectRoot, targetPath);
-        var readableFileBytes = new ReadableFileByteTracker(
-            updateTargets.Length,
-            targetIndex => updateTargets[targetIndex].FilePath,
-            projectRoot,
-            indexRunDiagnostics);
+            updateProgress.Start();
 
-        WriteIndexJsonLiveness(options, $"updating {ConsoleUi.Counted(targetPaths.Count, "file")}...");
-        string? currentUpdatePath = null;
-        var currentUpdatePhase = "preparing";
-        var updateHeartbeat = StartIndexJsonPhaseHeartbeat(
-            options,
-            "updating index",
-            () => currentUpdatePath == null
-                ? $"{updated + removed + skipped:N0}/{targetPaths.Count:N0} files processed"
-                : $"{updated + removed + skipped:N0}/{targetPaths.Count:N0} files processed, current {currentUpdatePath}");
-        var updateExtractionWorkStarted = 0;
-        void NotifyUpdateExtractionWorkStarted()
-        {
-            if (Interlocked.Exchange(ref updateExtractionWorkStarted, 1) == 0)
-                UpdateExtractionWorkStartedForTesting?.Invoke();
-        }
+            var updateTargets = new UpdateFileTarget[targetPaths.Count];
+            var updateTargetIndex = 0;
+            foreach (var targetPath in targetPaths)
+                updateTargets[updateTargetIndex++] = UpdateFileTarget.Create(projectRoot, targetPath);
+            readableFileBytes = new ReadableFileByteTracker(
+                updateTargets.Length,
+                targetIndex => updateTargets[targetIndex].FilePath,
+                projectRoot,
+                indexRunDiagnostics);
+
+            WriteIndexJsonLiveness(options, $"updating {ConsoleUi.Counted(targetPaths.Count, "file")}...");
+            var updateHeartbeat = StartIndexJsonPhaseHeartbeat(
+                options,
+                "updating index",
+                () => currentUpdatePath == null
+                    ? $"{updated + removed + skipped:N0}/{targetPaths.Count:N0} files processed"
+                    : $"{updated + removed + skipped:N0}/{targetPaths.Count:N0} files processed, current {currentUpdatePath}");
+            var updateExtractionWorkStarted = 0;
+            void NotifyUpdateExtractionWorkStarted()
+            {
+                if (Interlocked.Exchange(ref updateExtractionWorkStarted, 1) == 0)
+                    UpdateExtractionWorkStartedForTesting?.Invoke();
+            }
 
-        using var symbolExtractionWorker = new LazyDisposable<SymbolExtractionWorkerClient>(() =>
-        {
-            NotifyUpdateExtractionWorkStarted();
-            return new SymbolExtractionWorkerClient(options.MaxFileSizeBytes);
-        });
-        var parallelExtractionFallbackReason = options.Parallelism <= 1
-            ? "parallelism_one"
-            : !csharpWorkspace.HasStaticInterfaceContracts
-                ? "non_authoritative_csharp_workspace"
-                : csharpWorkspaceSnapshots == null
-                    ? "missing_csharp_workspace_snapshots"
-                    : csharpWorkspaceSnapshots.Count < 2
-                        ? "insufficient_authoritative_csharp_targets"
-                        : options.SymbolKindFilter.IsActive
-                            ? "active_symbol_kind_filter"
-                            : UpdateFileContentLoadForTesting != null
-                                ? "content_load_test_hook"
-                                : postExtractionHooks.Value.HasHooks
-                                    ? "post_extraction_hooks"
-                                    : null;
-        var parallelizeAuthoritativeCSharpUpdates =
-            parallelExtractionFallbackReason == null;
-        var parallelExtractionWorkerCount = parallelizeAuthoritativeCSharpUpdates
-            ? Math.Min(options.Parallelism, csharpWorkspaceSnapshots!.Count)
-            : 0;
-        var parallelExtractionWindowCapacity = parallelizeAuthoritativeCSharpUpdates
-            ? checked(parallelExtractionWorkerCount * 2)
-            : 0;
-        UpdateParallelExtractionSchedulingForTesting?.Invoke(
-            parallelizeAuthoritativeCSharpUpdates,
-            parallelExtractionFallbackReason,
-            parallelExtractionWorkerCount,
-            parallelExtractionWindowCapacity);
-        using var parallelExtractionPipeline =
-            new LazyDisposable<UpdateParallelExtractionPipeline>(() =>
+            using var symbolExtractionWorker = new LazyDisposable<SymbolExtractionWorkerClient>(() =>
             {
                 NotifyUpdateExtractionWorkStarted();
-                return new UpdateParallelExtractionPipeline(
-                    indexer,
-                    options,
-                    projectRoot,
-                    csharpWorkspace,
-                    csharpWorkspaceSnapshots!,
-                    parallelExtractionWorkerCount,
-                    parallelExtractionEventForTesting,
-                    parallelExtractionFailureForTesting,
-                    extractionStallTimeoutForTesting,
-                    parallelExtractionWorkersStoppedForTesting);
+                return new SymbolExtractionWorkerClient(options.MaxFileSizeBytes);
             });
-
-        var parallelSourceWorkspaceDriftDetected = false;
-        void ConsumeParallelUpdateResult(UpdateParallelExtractionResult item)
-        {
-            var target = item.Target;
-            if (cancellationToken.IsCancellationRequested && item.Record != null)
-            {
-                DemoteReadinessOnce();
-                csharpMetadataTargetsNeedRefresh = true;
-            }
-            ThrowIfUpdateCancelled();
-            updateProgress.Start();
-            var relPath = target.RelativePath;
-            currentUpdatePath = relPath;
-            currentUpdatePhase = item.FailurePhase ?? "preparing";
-            var absPath = target.FilePath;
-            var dbPath = target.IndexPath;
-            var fileBatchMarked = false;
-            var csharpWorkspaceSnapshot = csharpWorkspaceSnapshots![dbPath];
-            try
-            {
-                if (item.Record != null)
-                {
-                    readableFileBytes.Remember(item.TargetIndex, item.Record.Size);
-                    if (item.Warning != null && !options.Json && !options.Quiet)
-                    {
-                        updateProgress.Pause();
-                        ConsoleUi.PrintWarning(item.Warning);
-                        updateProgress.Resume();
-                    }
-                    DemoteReadinessOnce();
-                    csharpMetadataTargetsNeedRefresh = true;
-                }
-                var sourceContractSeenBeforeObservation =
-                    postExtractionHooks.Value.SawCSharpStaticInterfaceSourceContract;
-                postExtractionHooks.Value.ObserveCSharpStaticInterfaceSourceContractEvidence(
-                    item.HasCSharpStaticInterfaceSourceContract);
-                if (!csharpWorkspace.HasSourceStaticInterfaceContracts
-                    && !sourceContractSeenBeforeObservation
-                    && postExtractionHooks.Value.SawCSharpStaticInterfaceSourceContract)
-                {
-                    parallelSourceWorkspaceDriftDetected = true;
-                    RecordCSharpWorkspaceDrift(
-                        relPath,
-                        "A C# static-interface contract appeared after workspace preflight.");
-                    skipped++;
-                    return;
-                }
-                if (item.Exception is IndexExtractionStalledException stalledException)
-                {
-                    if (!string.Equals(
-                            item.FailurePhase,
-                            "reading",
-                            StringComparison.Ordinal))
-                    {
-                        DemoteReadinessOnce();
-                        csharpMetadataTargetsNeedRefresh = true;
-                        writer.MarkBatchInProgress();
-                        fileBatchMarked = true;
-                    }
-                    RethrowPreservingStackTrace(
-                        new IndexExtractionStalledException(
-                            updated + removed,
-                            targetPaths.Count,
-                            stalledException.Timeout,
-                            stalledException.ActivePath,
-                            stalledException.WorkerError));
-                }
-                if (item.Exception is CSharpWorkspaceChangedException
-                    or CSharpWorkspaceSnapshotDriftException)
-                {
-                    RecordCSharpWorkspaceDrift(
-                        relPath,
-                        item.Exception.Message,
-                        "reading");
-                    skipped++;
-                    return;
-                }
-                if (item.Exception is FileIndexer.BinaryFileSkippedException
-                    or FileIndexer.FileTooLargeSkippedException)
-                {
-                    var skippedFile = HandleSkippedUpdateFile(
-                        new SkippedUpdateFileHandlingContext
-                        {
-                            Writer = writer,
-                            Indexer = indexer,
-                            Options = options,
-                            AbsolutePath = absPath,
-                            RelativePath = relPath,
-                            IndexPath = dbPath,
-                            KnownLanguage = item.KnownLanguage,
-                            ProjectRootWritten = context.IsProjectRootWritten(),
-                            TargetIndex = item.TargetIndex,
-                            ReadableFileBytes = readableFileBytes,
-                            HasCSharpWorkspaceSnapshot = true,
-                            CSharpWorkspaceSnapshot = csharpWorkspaceSnapshot,
-                            CSharpWorkspaceSnapshots = csharpWorkspaceSnapshots,
-                            WarningList = warningList,
-                            UpdateProgress = updateProgress,
-                            CancellationToken = cancellationToken,
-                            DemoteReadinessOnce = DemoteReadinessOnce,
-                            SetCurrentUpdatePhase =
-                                phase => currentUpdatePhase = phase,
-                            RecordCSharpWorkspaceDrift =
-                                RecordCSharpWorkspaceDrift,
-                            RecordUpdateFileFailure =
-                                RecordUpdateFileFailure,
-                            PurgeStaleUpdateCleanupPaths =
-                                PurgeStaleUpdateCleanupPaths,
-                            RequireTypeScriptAugmentationRefresh =
-                                RequireTypeScriptAugmentationRefresh,
-                            WriteProjectRootOnce = WriteProjectRootOnce,
-                            RecordDynamicGraphFileRefresh =
-                                RecordDynamicGraphFileRefresh,
-                        },
-                        item.Exception);
-                    updated += skippedFile.Updated;
-                    skipped += skippedFile.Skipped;
-                    warnings += skippedFile.Warnings;
-                    mutualRecursionRefreshNeeded |=
-                        skippedFile.MutualRecursionRefreshNeeded;
-                    if (skippedFile.Updated > 0)
-                    {
-                        ftsMutated = true;
-                        parallelExtractionEventForTesting?.Invoke(
-                            new UpdateParallelExtractionTestEvent(
-                                UpdateParallelExtractionEventKind.PersistenceCompleted,
-                                item.TargetIndex,
-                                target.DisplayRelativePath,
-                                WorkerIndex: -1));
-                    }
-                    return;
-                }
-                if (item.Exception is FileNotFoundException or DirectoryNotFoundException)
-                {
-                    RecordCSharpWorkspaceDrift(
-                        relPath,
-                        "The C# file disappeared during its authoritative update pass.");
-                    skipped++;
-                    return;
-                }
-                if (item.Exception != null)
-                {
-                    if (item.Exception is OperationCanceledException)
-                        ThrowIfUpdateCancelled();
-                    if (!string.Equals(
-                            item.FailurePhase,
-                            "reading",
-                            StringComparison.Ordinal))
-                    {
-                        csharpMetadataTargetsNeedRefresh = true;
-                    }
-                    RecordUpdateFileFailure(
-                        relPath,
-                        item.FailurePhase ?? "reading",
-                        item.Exception);
-                    return;
-                }
-
-                var record = item.Record!;
-                currentUpdatePhase = "validating";
-                if (record.Lang != "csharp"
-                    || !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
-                        absPath,
-                        dbPath,
-                        target.DisplayRelativePath,
-                        record.Size,
-                        record.Modified,
-                        csharpWorkspaceSnapshots,
-                        out _,
-                        cancellationToken))
+            var parallelExtractionFallbackReason = options.Parallelism <= 1
+                ? "parallelism_one"
+                : !csharpWorkspace.HasStaticInterfaceContracts
+                    ? "non_authoritative_csharp_workspace"
+                    : csharpWorkspaceSnapshots == null
+                        ? "missing_csharp_workspace_snapshots"
+                        : csharpWorkspaceSnapshots.Count < 2
+                            ? "insufficient_authoritative_csharp_targets"
+                            : options.SymbolKindFilter.IsActive
+                                ? "active_symbol_kind_filter"
+                                : UpdateFileContentLoadForTesting != null
+                                    ? "content_load_test_hook"
+                                    : postExtractionHooks.Value.HasHooks
+                                        ? "post_extraction_hooks"
+                                        : null;
+            var parallelizeAuthoritativeCSharpUpdates =
+                parallelExtractionFallbackReason == null;
+            var parallelExtractionWorkerCount = parallelizeAuthoritativeCSharpUpdates
+                ? Math.Min(options.Parallelism, csharpWorkspaceSnapshots!.Count)
+                : 0;
+            var parallelExtractionWindowCapacity = parallelizeAuthoritativeCSharpUpdates
+                ? checked(parallelExtractionWorkerCount * 2)
+                : 0;
+            UpdateParallelExtractionSchedulingForTesting?.Invoke(
+                parallelizeAuthoritativeCSharpUpdates,
+                parallelExtractionFallbackReason,
+                parallelExtractionWorkerCount,
+                parallelExtractionWindowCapacity);
+            using var parallelExtractionPipeline =
+                new LazyDisposable<UpdateParallelExtractionPipeline>(() =>
                 {
-                    RecordCSharpWorkspaceDrift(
-                        relPath,
-                        "The C# file changed after extraction and before its authoritative update was persisted.",
-                        "reading");
-                    skipped++;
-                    return;
-                }
+                    NotifyUpdateExtractionWorkStarted();
+                    return new UpdateParallelExtractionPipeline(
+                        indexer,
+                        options,
+                        projectRoot,
+                        csharpWorkspace,
+                        csharpWorkspaceSnapshots!,
+                        parallelExtractionWorkerCount,
+                        parallelExtractionEventForTesting,
+                        parallelExtractionFailureForTesting,
+                        extractionStallTimeoutForTesting,
+                        parallelExtractionWorkersStoppedForTesting);
+                });
 
-                currentUpdatePhase = "reading";
-                parallelExtractionEventForTesting?.Invoke(
-                    new UpdateParallelExtractionTestEvent(
-                        UpdateParallelExtractionEventKind.PersistenceStarted,
-                        item.TargetIndex,
-                        target.DisplayRelativePath,
-                        WorkerIndex: -1));
-                var persistence = PersistPrecomputedUpdateFile(
-                    new UpdatePrecomputedFilePersistenceContext
-                    {
-                        Writer = writer,
-                        Options = options,
-                        Item = item,
-                        ProjectRootWritten = context.IsProjectRootWritten(),
-                        CancellationToken = cancellationToken,
-                        RequireTypeScriptAugmentationRefresh =
-                            RequireTypeScriptAugmentationRefresh,
-                        PurgeStaleUpdateCleanupPaths =
-                            PurgeStaleUpdateCleanupPaths,
-                        WriteProjectRootOnce = WriteProjectRootOnce,
-                        RecordDynamicGraphFileRefresh =
-                            RecordDynamicGraphFileRefresh,
-                        SetBatchMarkerOwned = owned => fileBatchMarked = owned,
-                        SetPhase = (path, phase) =>
-                        {
-                            currentUpdatePath = path;
-                            currentUpdatePhase = phase;
-                        },
-                    });
-                symbolsDroppedByKindFilter +=
-                    persistence.SymbolsDroppedByKindFilter;
-                mutualRecursionRefreshNeeded |=
-                    persistence.MutualRecursionRefreshNeeded;
-                updated++;
-                ftsMutated = true;
-                UpdateFileCommittedForTesting?.Invoke(
-                    updated + removed,
-                    targetPaths.Count);
-                parallelExtractionEventForTesting?.Invoke(
-                    new UpdateParallelExtractionTestEvent(
-                        UpdateParallelExtractionEventKind.PersistenceCompleted,
-                        item.TargetIndex,
-                        target.DisplayRelativePath,
-                        WorkerIndex: -1));
-                ThrowIfUpdateCancelled();
-                updateProgress.WriteVerbose(persistence.VerboseMessage);
-            }
-            catch (IndexExtractionStalledException)
-            {
-                throw;
-            }
-            catch (Exception ex)
+            try
             {
-                if (fileBatchMarked)
-                    writer.ClearBatchInProgress();
-                if (ex is CSharpWorkspaceChangedException)
+                for (var targetIndex = 0; targetIndex < updateTargets.Length; targetIndex++)
                 {
-                    RecordCSharpWorkspaceDrift(relPath, ex.Message);
-                    skipped++;
-                    return;
-                }
-                if (ex is OperationCanceledException)
                     ThrowIfUpdateCancelled();
-                RecordUpdateFileFailure(relPath, currentUpdatePhase, ex);
-            }
-        }
-        try
-        {
-            for (var targetIndex = 0; targetIndex < updateTargets.Length; targetIndex++)
-            {
-                ThrowIfUpdateCancelled();
-                if (parallelizeAuthoritativeCSharpUpdates
-                    && csharpWorkspaceSnapshots!.ContainsKey(
-                        updateTargets[targetIndex].IndexPath))
-                {
-                    IReadOnlyList<UpdateParallelExtractionRequest> parallelWindow;
-                    try
-                    {
-                        parallelWindow = TryBuildUpdateParallelWindow(
-                            indexer,
-                            updateTargets,
-                            targetIndex,
-                            parallelExtractionWindowCapacity,
-                            csharpWorkspaceSnapshots,
-                            scannedUpdateLanguages,
-                            cancellationToken);
-                    }
-                    catch (OperationCanceledException)
-                        when (cancellationToken.IsCancellationRequested)
-                    {
-                        ThrowIfUpdateCancelled();
-                        throw;
-                    }
-                    catch (Exception)
+                    if (parallelizeAuthoritativeCSharpUpdates
+                        && csharpWorkspaceSnapshots!.ContainsKey(
+                            updateTargets[targetIndex].IndexPath))
                     {
-                        // Probing belongs to the per-file serial error boundary. If a
-                        // speculative window probe fails, let the ordinary consumer
-                        // retry the natural first target and contain any repeat there.
-                        parallelizeAuthoritativeCSharpUpdates = false;
-                        parallelWindow = [];
-                    }
-                    if (parallelWindow.Count > 0)
-                    {
-                        UpdateParallelExtractionWindowResult windowResult;
+                        IReadOnlyList<UpdateParallelExtractionRequest> parallelWindow;
                         try
                         {
-                            windowResult = parallelExtractionPipeline.Value.ExtractWindow(
-                                parallelWindow,
-                                cancellationToken,
-                                (path, phase) =>
-                                {
-                                    currentUpdatePath = FormatIndexPhasePath(path, phase);
-                                    currentUpdatePhase = phase;
-                                });
+                            parallelWindow = TryBuildUpdateParallelWindow(
+                                indexer,
+                                updateTargets,
+                                targetIndex,
+                                parallelExtractionWindowCapacity,
+                                csharpWorkspaceSnapshots,
+                                scannedUpdateLanguages,
+                                cancellationToken);
                         }
                         catch (OperationCanceledException)
+                            when (cancellationToken.IsCancellationRequested)
                         {
-                            var sawValidatedLoad = false;
-                            foreach (var request in parallelWindow)
-                            {
-                                var loaded = request.Progress.GetLoadedRecord();
-                                if (loaded.Record == null)
-                                    continue;
-
-                                sawValidatedLoad = true;
-                                break;
-                            }
-                            if (sawValidatedLoad)
-                            {
-                                DemoteReadinessOnce();
-                                csharpMetadataTargetsNeedRefresh = true;
-                            }
                             ThrowIfUpdateCancelled();
                             throw;
                         }
-                        var results = windowResult.Results;
-                        parallelSourceWorkspaceDriftDetected = false;
-                        var recoverSerialSuffix = false;
-                        var consumedWindowCount = 0;
-                        var consumableResultCount = windowResult.FatalWasNormalized
-                            ? results.Count - 1
-                            : results.Count;
-                        for (var resultIndex = 0;
-                             resultIndex < consumableResultCount;
-                             resultIndex++)
+                        catch (Exception)
                         {
-                            var item = results[resultIndex];
-                            ConsumeParallelUpdateResult(item);
-                            consumedWindowCount++;
-                            if (item.Exception is IndexExtractionStalledException
-                                || parallelSourceWorkspaceDriftDetected)
-                            {
-                                recoverSerialSuffix = true;
-                                break;
-                            }
+                            // Probing belongs to the per-file serial error boundary. If a
+                            // speculative window probe fails, let the ordinary consumer
+                            // retry the natural first target and contain any repeat there.
+                            parallelizeAuthoritativeCSharpUpdates = false;
+                            parallelWindow = [];
                         }
-                        if (windowResult.FatalWasNormalized
-                            && !recoverSerialSuffix)
+                        if (parallelWindow.Count > 0)
                         {
-                            var sourceContractPrecedesFatal =
-                                windowResult
-                                    .UnconsumedSourceContractCandidateBeforeFatal
-                                && !csharpWorkspace
-                                    .HasSourceStaticInterfaceContracts
-                                && !postExtractionHooks.Value
-                                    .SawCSharpStaticInterfaceSourceContract;
-                            if (sourceContractPrecedesFatal)
+                            UpdateParallelExtractionWindowResult windowResult;
+                            try
                             {
-                                // The natural first unconsumed target must be
-                                // retried before a later extraction fatal can
-                                // become terminal. Keep the fatal's readiness
-                                // and batch effects out of this recovery path.
-                                recoverSerialSuffix = true;
+                                windowResult = parallelExtractionPipeline.Value.ExtractWindow(
+                                    parallelWindow,
+                                    cancellationToken,
+                                    (path, phase) =>
+                                    {
+                                        currentUpdatePath = FormatIndexPhasePath(path, phase);
+                                        currentUpdatePhase = phase;
+                                    });
                             }
-                            else
+                            catch (OperationCanceledException)
                             {
-                                var actualFatal =
-                                    windowResult.ActualFatalResult!;
-                                if (actualFatal.Record != null
-                                    || !string.Equals(
-                                        actualFatal.FailurePhase,
-                                        "reading",
-                                        StringComparison.Ordinal))
+                                var sawValidatedLoad = false;
+                                foreach (var request in parallelWindow)
+                                {
+                                    var loaded = request.Progress.GetLoadedRecord();
+                                    if (loaded.Record == null)
+                                        continue;
+
+                                    sawValidatedLoad = true;
+                                    break;
+                                }
+                                if (sawValidatedLoad)
                                 {
                                     DemoteReadinessOnce();
                                     csharpMetadataTargetsNeedRefresh = true;
                                 }
-                                if (!string.Equals(
-                                        actualFatal.FailurePhase,
-                                        "reading",
-                                        StringComparison.Ordinal))
+                                ThrowIfUpdateCancelled();
+                                throw;
+                            }
+                            var results = windowResult.Results;
+                            parallelSourceWorkspaceDriftDetected = false;
+                            var recoverSerialSuffix = false;
+                            var consumedWindowCount = 0;
+                            var consumableResultCount = windowResult.FatalWasNormalized
+                                ? results.Count - 1
+                                : results.Count;
+                            for (var resultIndex = 0;
+                                 resultIndex < consumableResultCount;
+                                 resultIndex++)
+                            {
+                                var item = results[resultIndex];
+                                ConsumeParallelUpdateResult(item);
+                                consumedWindowCount++;
+                                if (item.Exception is IndexExtractionStalledException
+                                    || parallelSourceWorkspaceDriftDetected)
                                 {
-                                    writer.MarkBatchInProgress();
+                                    recoverSerialSuffix = true;
+                                    break;
                                 }
-
-                                var normalizedFatal = results[^1];
-                                ConsumeParallelUpdateResult(normalizedFatal);
-                                consumedWindowCount++;
-                                if (parallelSourceWorkspaceDriftDetected)
+                            }
+                            if (windowResult.FatalWasNormalized
+                                && !recoverSerialSuffix)
+                            {
+                                var sourceContractPrecedesFatal =
+                                    windowResult
+                                        .UnconsumedSourceContractCandidateBeforeFatal
+                                    && !csharpWorkspace
+                                        .HasSourceStaticInterfaceContracts
+                                    && !postExtractionHooks.Value
+                                        .SawCSharpStaticInterfaceSourceContract;
+                                if (sourceContractPrecedesFatal)
+                                {
+                                    // The natural first unconsumed target must be
+                                    // retried before a later extraction fatal can
+                                    // become terminal. Keep the fatal's readiness
+                                    // and batch effects out of this recovery path.
                                     recoverSerialSuffix = true;
+                                }
+                                else
+                                {
+                                    var actualFatal =
+                                        windowResult.ActualFatalResult!;
+                                    if (actualFatal.Record != null
+                                        || !string.Equals(
+                                            actualFatal.FailurePhase,
+                                            "reading",
+                                            StringComparison.Ordinal))
+                                    {
+                                        DemoteReadinessOnce();
+                                        csharpMetadataTargetsNeedRefresh = true;
+                                    }
+                                    if (!string.Equals(
+                                            actualFatal.FailurePhase,
+                                            "reading",
+                                            StringComparison.Ordinal))
+                                    {
+                                        writer.MarkBatchInProgress();
+                                    }
+
+                                    var normalizedFatal = results[^1];
+                                    ConsumeParallelUpdateResult(normalizedFatal);
+                                    consumedWindowCount++;
+                                    if (parallelSourceWorkspaceDriftDetected)
+                                        recoverSerialSuffix = true;
+                                }
                             }
-                        }
-                        if (recoverSerialSuffix)
-                        {
-                            parallelizeAuthoritativeCSharpUpdates = false;
-                            targetIndex += consumedWindowCount - 1;
+                            if (recoverSerialSuffix)
+                            {
+                                parallelizeAuthoritativeCSharpUpdates = false;
+                                targetIndex += consumedWindowCount - 1;
+                                continue;
+                            }
+                            if (results.Count != parallelWindow.Count)
+                            {
+                                throw new InvalidOperationException(
+                                    "A shortened parallel update window returned without a terminal extraction error.");
+                            }
+                            targetIndex += parallelWindow.Count - 1;
                             continue;
                         }
-                        if (results.Count != parallelWindow.Count)
-                        {
-                            throw new InvalidOperationException(
-                                "A shortened parallel update window returned without a terminal extraction error.");
-                        }
-                        targetIndex += parallelWindow.Count - 1;
-                        continue;
-                    }
-                }
-
-                var target = updateTargets[targetIndex];
-                ThrowIfUpdateCancelled();
-                updateProgress.Start();
-                var relPath = target.RelativePath;
-                currentUpdatePath = relPath;
-                currentUpdatePhase = "preparing";
-                var absPath = target.FilePath;
-                var dbPath = target.IndexPath;
-                var fileBatchMarked = false;
-                string? knownLanguage = null;
-                CSharpStaticInterfacePrepass.FileStatSnapshot csharpWorkspaceSnapshot = default;
-                var hasCSharpWorkspaceSnapshot = csharpWorkspaceSnapshots != null
-                    && csharpWorkspaceSnapshots.TryGetValue(dbPath, out csharpWorkspaceSnapshot);
-                try
-                {
-                    if (hasCSharpWorkspaceSnapshot
-                        && !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
-                            absPath,
-                            dbPath,
-                            relPath,
-                            csharpWorkspaceSnapshot.Size,
-                            csharpWorkspaceSnapshot.ModifiedUtc,
-                            csharpWorkspaceSnapshots!,
-                            out _,
-                            cancellationToken))
-                    {
-                        RecordCSharpWorkspaceDrift(
-                            relPath,
-                            "The C# file changed before its authoritative update pass.");
-                        skipped++;
-                        continue;
                     }
 
-                    if (!File.Exists(LongPath.EnsureWindowsPrefix(absPath)))
+                    var target = updateTargets[targetIndex];
+                    ThrowIfUpdateCancelled();
+                    updateProgress.Start();
+                    var relPath = target.RelativePath;
+                    currentUpdatePath = relPath;
+                    currentUpdatePhase = "preparing";
+                    var absPath = target.FilePath;
+                    var dbPath = target.IndexPath;
+                    var fileBatchMarked = false;
+                    string? knownLanguage = null;
+                    CSharpStaticInterfacePrepass.FileStatSnapshot csharpWorkspaceSnapshot = default;
+                    var hasCSharpWorkspaceSnapshot = csharpWorkspaceSnapshots != null
+                        && csharpWorkspaceSnapshots.TryGetValue(dbPath, out csharpWorkspaceSnapshot);
+                    try
                     {
-                        if (hasCSharpWorkspaceSnapshot)
+                        if (hasCSharpWorkspaceSnapshot
+                            && !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
+                                absPath,
+                                dbPath,
+                                relPath,
+                                csharpWorkspaceSnapshot.Size,
+                                csharpWorkspaceSnapshot.ModifiedUtc,
+                                csharpWorkspaceSnapshots!,
+                                out _,
+                                cancellationToken))
                         {
                             RecordCSharpWorkspaceDrift(
                                 relPath,
-                                "The C# file disappeared after contract preflight.");
+                                "The C# file changed before its authoritative update pass.");
                             skipped++;
                             continue;
                         }
 
-                        using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing target");
-                        if (writer.DeleteFileByPath(dbPath))
+                        if (!File.Exists(LongPath.EnsureWindowsPrefix(absPath)))
                         {
-                            DemoteReadinessOnce();
-                            WriteProjectRootOnce();
-                            RequireTypeScriptAugmentationRefresh();
-                            deleteTxn.Commit();
-                            removed++;
-                            ftsMutated = true;
-                            mutualRecursionRefreshNeeded = true;
-                            updateProgress.WriteVerbose($"  [DEL ] {relPath}");
-                        }
-                        else
-                        {
-                            skipped++;
-                            updateProgress.WriteVerbose($"  [SKIP] {relPath} (not in DB)");
-                        }
-                        continue;
-                    }
+                            if (hasCSharpWorkspaceSnapshot)
+                            {
+                                RecordCSharpWorkspaceDrift(
+                                    relPath,
+                                    "The C# file disappeared after contract preflight.");
+                                skipped++;
+                                continue;
+                            }
 
-                    var pathFilter = indexer.EvaluatePathFilter(absPath);
-                    RecordScanErrors(pathFilter.Errors);
-                    if (pathFilter.ShouldSkip)
-                    {
-                        if (!pathFilter.ShouldDeleteExisting)
-                        {
-                            skipped++;
-                            if (options.Verbose && !options.Json && !options.Quiet)
+                            using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing target");
+                            if (writer.DeleteFileByPath(dbPath))
                             {
-                                updateProgress.Pause();
-                                CommandOutputWriter.WriteLine($"  [SKIP] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
-                                updateProgress.Resume();
+                                DemoteReadinessOnce();
+                                WriteProjectRootOnce();
+                                RequireTypeScriptAugmentationRefresh();
+                                deleteTxn.Commit();
+                                removed++;
+                                ftsMutated = true;
+                                mutualRecursionRefreshNeeded = true;
+                                updateProgress.WriteVerbose($"  [DEL ] {relPath}");
+                            }
+                            else
+                            {
+                                skipped++;
+                                updateProgress.WriteVerbose($"  [SKIP] {relPath} (not in DB)");
                             }
                             continue;
                         }
 
-                        using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete skipped path");
-                        if (writer.DeleteFileByPath(dbPath))
+                        var pathFilter = indexer.EvaluatePathFilter(absPath);
+                        RecordScanErrors(pathFilter.Errors);
+                        if (pathFilter.ShouldSkip)
                         {
-                            DemoteReadinessOnce();
-                            WriteProjectRootOnce();
-                            RequireTypeScriptAugmentationRefresh();
-                            deleteTxn.Commit();
-                            removed++;
-                            ftsMutated = true;
-                            mutualRecursionRefreshNeeded = true;
-                            if (options.Verbose && !options.Json && !options.Quiet)
+                            if (!pathFilter.ShouldDeleteExisting)
                             {
-                                updateProgress.Pause();
-                                CommandOutputWriter.WriteLine($"  [DEL ] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
-                                updateProgress.Resume();
+                                skipped++;
+                                if (options.Verbose && !options.Json && !options.Quiet)
+                                {
+                                    updateProgress.Pause();
+                                    CommandOutputWriter.WriteLine($"  [SKIP] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
+                                    updateProgress.Resume();
+                                }
+                                continue;
+                            }
+
+                            using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete skipped path");
+                            if (writer.DeleteFileByPath(dbPath))
+                            {
+                                DemoteReadinessOnce();
+                                WriteProjectRootOnce();
+                                RequireTypeScriptAugmentationRefresh();
+                                deleteTxn.Commit();
+                                removed++;
+                                ftsMutated = true;
+                                mutualRecursionRefreshNeeded = true;
+                                if (options.Verbose && !options.Json && !options.Quiet)
+                                {
+                                    updateProgress.Pause();
+                                    CommandOutputWriter.WriteLine($"  [DEL ] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
+                                    updateProgress.Resume();
+                                }
                             }
+                            else
+                            {
+                                skipped++;
+                                if (options.Verbose && !options.Json)
+                                {
+                                    updateProgress.Pause();
+                                    CommandOutputWriter.WriteLine($"  [SKIP] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
+                                    updateProgress.Resume();
+                                }
+                            }
+                            continue;
                         }
-                        else
+
+                        var indexability = indexer.GetFileIndexabilityForIndexing(absPath);
+                        var detection = indexer.TryDetectLanguageForIndexing(absPath, knownIndexability: indexability);
+                        if (hasCSharpWorkspaceSnapshot
+                            && (indexability != FileIndexer.FileProbeStatus.Supported
+                                || detection.Status != FileIndexer.FileProbeStatus.Supported
+                                || detection.Language != "csharp"))
                         {
+                            RecordCSharpWorkspaceDrift(
+                                relPath,
+                                "The C# file changed language or indexability after contract preflight.");
                             skipped++;
-                            if (options.Verbose && !options.Json)
+                            continue;
+                        }
+                        if (!hasCSharpWorkspaceSnapshot
+                            && csharpWorkspaceSnapshots != null
+                            && indexability == FileIndexer.FileProbeStatus.Supported
+                            && detection.Status == FileIndexer.FileProbeStatus.Supported
+                            && detection.Language == "csharp")
+                        {
+                            RecordCSharpWorkspaceDrift(
+                                relPath,
+                                "A C# target appeared after the authoritative workspace target set was captured.");
+                            skipped++;
+                            continue;
+                        }
+                        if (indexability == FileIndexer.FileProbeStatus.Missing || detection.Status == FileIndexer.FileProbeStatus.Missing)
+                        {
+                            var message = $"{relPath}: skipped because it was deleted during indexing.";
+                            warnings++;
+                            warningList.Add(new CliJsonMessage(relPath, message));
+                            if (!options.Json && !options.Quiet)
                             {
                                 updateProgress.Pause();
-                                CommandOutputWriter.WriteLine($"  [SKIP] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
+                                ConsoleUi.PrintWarning(message);
                                 updateProgress.Resume();
                             }
-                        }
-                        continue;
-                    }
 
-                    var indexability = indexer.GetFileIndexabilityForIndexing(absPath);
-                    var detection = indexer.TryDetectLanguageForIndexing(absPath, knownIndexability: indexability);
-                    if (hasCSharpWorkspaceSnapshot
-                        && (indexability != FileIndexer.FileProbeStatus.Supported
-                            || detection.Status != FileIndexer.FileProbeStatus.Supported
-                            || detection.Language != "csharp"))
-                    {
-                        RecordCSharpWorkspaceDrift(
-                            relPath,
-                            "The C# file changed language or indexability after contract preflight.");
-                        skipped++;
-                        continue;
-                    }
-                    if (!hasCSharpWorkspaceSnapshot
-                        && csharpWorkspaceSnapshots != null
-                        && indexability == FileIndexer.FileProbeStatus.Supported
-                        && detection.Status == FileIndexer.FileProbeStatus.Supported
-                        && detection.Language == "csharp")
-                    {
-                        RecordCSharpWorkspaceDrift(
-                            relPath,
-                            "A C# target appeared after the authoritative workspace target set was captured.");
-                        skipped++;
-                        continue;
-                    }
-                    if (indexability == FileIndexer.FileProbeStatus.Missing || detection.Status == FileIndexer.FileProbeStatus.Missing)
-                    {
-                        var message = $"{relPath}: skipped because it was deleted during indexing.";
-                        warnings++;
-                        warningList.Add(new CliJsonMessage(relPath, message));
-                        if (!options.Json && !options.Quiet)
-                        {
-                            updateProgress.Pause();
-                            ConsoleUi.PrintWarning(message);
-                            updateProgress.Resume();
+                            using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing during probe");
+                            if (writer.DeleteFileByPath(dbPath))
+                            {
+                                DemoteReadinessOnce();
+                                WriteProjectRootOnce();
+                                RequireTypeScriptAugmentationRefresh();
+                                deleteTxn.Commit();
+                                removed++;
+                                ftsMutated = true;
+                                mutualRecursionRefreshNeeded = true;
+                            }
+                            else
+                            {
+                                skipped++;
+                            }
+                            continue;
                         }
 
-                        using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing during probe");
-                        if (writer.DeleteFileByPath(dbPath))
+                        if (indexability == FileIndexer.FileProbeStatus.ProbeFailed || detection.Status == FileIndexer.FileProbeStatus.ProbeFailed)
                         {
                             DemoteReadinessOnce();
-                            WriteProjectRootOnce();
-                            RequireTypeScriptAugmentationRefresh();
-                            deleteTxn.Commit();
-                            removed++;
-                            ftsMutated = true;
-                            mutualRecursionRefreshNeeded = true;
-                        }
-                        else
-                        {
-                            skipped++;
-                        }
-                        continue;
-                    }
 
-                    if (indexability == FileIndexer.FileProbeStatus.ProbeFailed || detection.Status == FileIndexer.FileProbeStatus.ProbeFailed)
-                    {
-                        DemoteReadinessOnce();
-
-                        errors++;
-                        errorList.Add(new CliJsonMessage(relPath, "Could not probe file for indexability/language."));
-                        if (fileErrorList.Count < PartialIndexFileErrorLimit)
-                        {
-                            fileErrorList.Add(new StatusIndexFileError
+                            errors++;
+                            errorList.Add(new CliJsonMessage(relPath, "Could not probe file for indexability/language."));
+                            if (fileErrorList.Count < PartialIndexFileErrorLimit)
                             {
-                                File = FileIndexer.NormalizePathSeparators(relPath),
-                                Category = "file_read_error",
-                                Phase = "reading",
-                                Detail = "Could not probe file for indexability/language.",
-                            });
-                        }
-                        if (!options.Json)
-                        {
-                            updateProgress.Pause();
-                            if (options.Verbose)
-                                CommandErrorWriter.WriteStderr($"  [ERR ] {relPath}: Could not probe file for indexability/language.");
-                            else
-                                CommandErrorWriter.WriteStderr($"  [ERR ] {relPath}: Could not probe file for indexability/language.");
-                            updateProgress.Resume();
+                                fileErrorList.Add(new StatusIndexFileError
+                                {
+                                    File = FileIndexer.NormalizePathSeparators(relPath),
+                                    Category = "file_read_error",
+                                    Phase = "reading",
+                                    Detail = "Could not probe file for indexability/language.",
+                                });
+                            }
+                            if (!options.Json)
+                            {
+                                updateProgress.Pause();
+                                if (options.Verbose)
+                                    CommandErrorWriter.WriteStderr($"  [ERR ] {relPath}: Could not probe file for indexability/language.");
+                                else
+                                    CommandErrorWriter.WriteStderr($"  [ERR ] {relPath}: Could not probe file for indexability/language.");
+                                updateProgress.Resume();
+                            }
+                            continue;
                         }
-                        continue;
-                    }
 
-                    if (indexability != FileIndexer.FileProbeStatus.Supported || detection.Status != FileIndexer.FileProbeStatus.Supported)
-                    {
-                        if (!writer.HasFileAtPath(dbPath))
+                        if (indexability != FileIndexer.FileProbeStatus.Supported || detection.Status != FileIndexer.FileProbeStatus.Supported)
                         {
-                            using var purgeTxn = writer.BeginTransaction(cancellationToken, "update purge unsupported renamed target");
-                            var purged = PurgeStaleUpdateCleanupPaths(
-                                dbPath,
-                                checksum: null,
-                                includeDirectoryAndStem: context.IsProjectRootWritten());
-                            if (purged > 0)
+                            if (!writer.HasFileAtPath(dbPath))
+                            {
+                                using var purgeTxn = writer.BeginTransaction(cancellationToken, "update purge unsupported renamed target");
+                                var purged = PurgeStaleUpdateCleanupPaths(
+                                    dbPath,
+                                    checksum: null,
+                                    includeDirectoryAndStem: persistenceOperations.IsProjectRootWritten());
+                                if (purged > 0)
+                                {
+                                    DemoteReadinessOnce();
+                                    WriteProjectRootOnce();
+                                    RequireTypeScriptAugmentationRefresh();
+                                    purgeTxn.Commit();
+                                    removed += purged;
+                                    ftsMutated = true;
+                                    mutualRecursionRefreshNeeded = true;
+                                    if (options.Verbose && !options.Json && !options.Quiet)
+                                    {
+                                        updateProgress.Pause();
+                                        CommandOutputWriter.WriteLine($"  [DEL ] {relPath} (unsupported renamed target)");
+                                        updateProgress.Resume();
+                                    }
+                                }
+                                else
+                                {
+                                    skipped++;
+                                    if (options.Verbose && !options.Json && !options.Quiet)
+                                    {
+                                        updateProgress.Pause();
+                                        CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unsupported type)");
+                                        updateProgress.Resume();
+                                    }
+                                }
+                                continue;
+                            }
+
+                            DemoteReadinessOnce();
+                            using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete unsupported target");
+                            if (writer.DeleteFileByPath(dbPath))
                             {
-                                DemoteReadinessOnce();
                                 WriteProjectRootOnce();
                                 RequireTypeScriptAugmentationRefresh();
-                                purgeTxn.Commit();
-                                removed += purged;
+                                deleteTxn.Commit();
+                                removed++;
                                 ftsMutated = true;
                                 mutualRecursionRefreshNeeded = true;
                                 if (options.Verbose && !options.Json && !options.Quiet)
                                 {
                                     updateProgress.Pause();
-                                    CommandOutputWriter.WriteLine($"  [DEL ] {relPath} (unsupported renamed target)");
+                                    CommandOutputWriter.WriteLine($"  [DEL ] {relPath} (no longer indexable)");
                                     updateProgress.Resume();
                                 }
                             }
                             else
                             {
                                 skipped++;
-                                if (options.Verbose && !options.Json && !options.Quiet)
+                                if (options.Verbose && !options.Json)
                                 {
                                     updateProgress.Pause();
                                     CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unsupported type)");
@@ -856,361 +503,328 @@ void ConsumeParallelUpdateResult(UpdateParallelExtractionResult item)
                             continue;
                         }
 
-                        DemoteReadinessOnce();
-                        using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete unsupported target");
-                        if (writer.DeleteFileByPath(dbPath))
+                        if (FileIndexer.TryGetFileIdentity(absPath, out var identity, out var linkCount)
+                            && linkCount > 1
+                            && !visitedFileIdentities.Add(identity))
                         {
-                            WriteProjectRootOnce();
-                            RequireTypeScriptAugmentationRefresh();
-                            deleteTxn.Commit();
-                            removed++;
-                            ftsMutated = true;
-                            mutualRecursionRefreshNeeded = true;
-                            if (options.Verbose && !options.Json && !options.Quiet)
+                            var message = "Skipped hardlinked file because the same file content was already indexed from another path.";
+                            warnings++;
+                            warningList.Add(new CliJsonMessage(relPath, message));
+                            if (!options.Json && !options.Quiet)
                             {
                                 updateProgress.Pause();
-                                CommandOutputWriter.WriteLine($"  [DEL ] {relPath} (no longer indexable)");
+                                ConsoleUi.PrintWarning($"{relPath}: {message}");
                                 updateProgress.Resume();
                             }
+
+                            using var deleteTxn = writer.BeginTransaction();
+                            if (writer.DeleteFileByPath(dbPath))
+                            {
+                                DemoteReadinessOnce();
+                                WriteProjectRootOnce();
+                                RequireTypeScriptAugmentationRefresh();
+                                deleteTxn.Commit();
+                                removed++;
+                                ftsMutated = true;
+                                mutualRecursionRefreshNeeded = true;
+                            }
+                            else
+                            {
+                                skipped++;
+                            }
+                            continue;
                         }
-                        else
+
+                        var statReusableLanguage = GetStatReusableLanguage(absPath, detection);
+                        var generatedExtractionSuppressed = indexer.IsGeneratedCodeExtractionSuppressed(dbPath);
+                        var statMatchedFile = IndexedFileStatReuse.TryGetReusableUnchangedFile(
+                            writer,
+                            absPath,
+                            dbPath,
+                            statReusableLanguage,
+                            options.MaxFileSizeBytes ?? FileIndexer.DefaultMaxFileSizeBytes,
+                            options.MaxSymbolsPerFile,
+                            options.MaxReferencesPerFile,
+                            generatedExtractionSuppressed,
+                            allowReuse: symbolKindFilterMatchesPrior
+                                && (statReusableLanguage != "csharp" || csharpSymbolNameContractMatchesCurrent)
+                                && (statReusableLanguage != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
+                                && (statReusableLanguage != "sql" || sqlGraphContractMatchesCurrent)
+                                && (statReusableLanguage is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent));
+                        if (statMatchedFile != null)
                         {
                             skipped++;
-                            if (options.Verbose && !options.Json)
+                            readableFileBytes.Remember(targetIndex, statMatchedFile.Value.Size);
+                            if (options.Verbose && !options.Json && !options.Quiet)
                             {
                                 updateProgress.Pause();
-                                CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unsupported type)");
+                                CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unchanged)");
                                 updateProgress.Resume();
                             }
+                            continue;
                         }
-                        continue;
-                    }
 
-                    if (FileIndexer.TryGetFileIdentity(absPath, out var identity, out var linkCount)
-                        && linkCount > 1
-                        && !visitedFileIdentities.Add(identity))
-                    {
-                        var message = "Skipped hardlinked file because the same file content was already indexed from another path.";
-                        warnings++;
-                        warningList.Add(new CliJsonMessage(relPath, message));
-                        if (!options.Json && !options.Quiet)
-                        {
-                            updateProgress.Pause();
-                            ConsoleUi.PrintWarning($"{relPath}: {message}");
-                            updateProgress.Resume();
-                        }
+                        knownLanguage = scannedUpdateLanguages == null
+                            ? statReusableLanguage
+                            : FileIndexer.GetReusableDetectedLanguage(absPath, scannedUpdateLanguages);
 
-                        using var deleteTxn = writer.BeginTransaction();
-                        if (writer.DeleteFileByPath(dbPath))
-                        {
-                            DemoteReadinessOnce();
-                            WriteProjectRootOnce();
-                            RequireTypeScriptAugmentationRefresh();
-                            deleteTxn.Commit();
-                            removed++;
-                            ftsMutated = true;
-                            mutualRecursionRefreshNeeded = true;
-                        }
-                        else
+                        currentUpdatePhase = "reading";
+                        UpdateFileContentLoadForTesting?.Invoke(relPath);
+                        var loaded = indexer.BuildLoadedRecordWithRawBytes(
+                            absPath,
+                            relPath,
+                            knownLanguage,
+                            cancellationToken);
+                        var record = loaded.Record;
+                        if (hasCSharpWorkspaceSnapshot
+                            && (record.Lang != "csharp"
+                                || !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
+                                    absPath,
+                                    dbPath,
+                                    relPath,
+                                    record.Size,
+                                    record.Modified,
+                                    csharpWorkspaceSnapshots!,
+                                    out _,
+                                    cancellationToken)))
                         {
+                            RecordCSharpWorkspaceDrift(
+                                relPath,
+                                "The C# file changed while the authoritative update pass was reading it.");
                             skipped++;
+                            continue;
                         }
-                        continue;
-                    }
+                        readableFileBytes.Remember(targetIndex, record.Size);
+                        var warning = loaded.Warning;
+                        var generatedSuppressionIssue = generatedExtractionSuppressed
+                            ? indexer.BuildGeneratedCodeExtractionSkippedIssue(record.Path)
+                            : null;
 
-                    var statReusableLanguage = GetStatReusableLanguage(absPath, detection);
-                    var generatedExtractionSuppressed = indexer.IsGeneratedCodeExtractionSuppressed(dbPath);
-                    var statMatchedFile = IndexedFileStatReuse.TryGetReusableUnchangedFile(
-                        writer,
-                        absPath,
-                        dbPath,
-                        statReusableLanguage,
-                        options.MaxFileSizeBytes ?? FileIndexer.DefaultMaxFileSizeBytes,
-                        options.MaxSymbolsPerFile,
-                        options.MaxReferencesPerFile,
-                        generatedExtractionSuppressed,
-                        allowReuse: symbolKindFilterMatchesPrior
-                            && (statReusableLanguage != "csharp" || csharpSymbolNameContractMatchesCurrent)
-                            && (statReusableLanguage != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
-                            && (statReusableLanguage != "sql" || sqlGraphContractMatchesCurrent)
-                            && (statReusableLanguage is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent));
-                    if (statMatchedFile != null)
-                    {
-                        skipped++;
-                        readableFileBytes.Remember(targetIndex, statMatchedFile.Value.Size);
-                        if (options.Verbose && !options.Json && !options.Quiet)
+                        if (warning != null && !options.Json && !options.Quiet)
                         {
                             updateProgress.Pause();
-                            CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unchanged)");
+                            ConsoleUi.PrintWarning(warning);
                             updateProgress.Resume();
                         }
-                        continue;
-                    }
-
-                    knownLanguage = scannedUpdateLanguages == null
-                        ? statReusableLanguage
-                        : FileIndexer.GetReusableDetectedLanguage(absPath, scannedUpdateLanguages);
-
-                    currentUpdatePhase = "reading";
-                    UpdateFileContentLoadForTesting?.Invoke(relPath);
-                    var loaded = indexer.BuildLoadedRecordWithRawBytes(
-                        absPath,
-                        relPath,
-                        knownLanguage,
-                        cancellationToken);
-                    var record = loaded.Record;
-                    if (hasCSharpWorkspaceSnapshot
-                        && (record.Lang != "csharp"
-                            || !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
-                                absPath,
-                                dbPath,
-                                relPath,
-                                record.Size,
-                                record.Modified,
-                                csharpWorkspaceSnapshots!,
-                                out _,
-                                cancellationToken)))
-                    {
-                        RecordCSharpWorkspaceDrift(
-                            relPath,
-                            "The C# file changed while the authoritative update pass was reading it.");
-                        skipped++;
-                        continue;
-                    }
-                    readableFileBytes.Remember(targetIndex, record.Size);
-                    var warning = loaded.Warning;
-                    var generatedSuppressionIssue = generatedExtractionSuppressed
-                        ? indexer.BuildGeneratedCodeExtractionSkippedIssue(record.Path)
-                        : null;
 
-                    if (warning != null && !options.Json && !options.Quiet)
-                    {
-                        updateProgress.Pause();
-                        ConsoleUi.PrintWarning(warning);
-                        updateProgress.Resume();
-                    }
-
-                    var existingId = writer.GetReusableUnchangedFileId(
-                        record.Path,
-                        record.Modified,
-                        record.Checksum,
-                        size: record.Size,
-                        lines: record.Lines,
-                        language: record.Lang,
-                        generated: record.Generated,
-                        maxSymbolsPerFile: options.MaxSymbolsPerFile,
-                        maxReferencesPerFile: options.MaxReferencesPerFile,
-                        generatedExtractionSuppressed: generatedExtractionSuppressed,
-                        allowReuse: symbolKindFilterMatchesPrior
-                            && (record.Lang != "csharp" || csharpSymbolNameContractMatchesCurrent)
-                            && (record.Lang != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
-                            && (record.Lang != "sql" || sqlGraphContractMatchesCurrent)
-                            && (record.Lang is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent));
-                    if (existingId != null)
-                    {
-                        using var purgeTxn = writer.BeginTransaction(cancellationToken, "update purge unchanged stale paths");
-                        var purged = PurgeStaleUpdateCleanupPaths(
+                        var existingId = writer.GetReusableUnchangedFileId(
                             record.Path,
+                            record.Modified,
                             record.Checksum,
-                            includeDirectoryAndStem: context.IsProjectRootWritten());
-                        if (purged > 0)
-                        {
-                            DemoteReadinessOnce();
-                            WriteProjectRootOnce();
-                            RequireTypeScriptAugmentationRefresh();
-                            purgeTxn.Commit();
-                            removed += purged;
-                            ftsMutated = true;
-                            mutualRecursionRefreshNeeded = true;
-                        }
-                        skipped++;
-                        if (options.Verbose && !options.Json && !options.Quiet)
-                        {
-                            updateProgress.Pause();
-                            CommandOutputWriter.WriteLine(purged > 0
-                                ? $"  [SKIP] {relPath} (unchanged; purged {purged:N0} stale renamed path(s))"
-                                : $"  [SKIP] {relPath} (unchanged)");
-                            updateProgress.Resume();
+                            size: record.Size,
+                            lines: record.Lines,
+                            language: record.Lang,
+                            generated: record.Generated,
+                            maxSymbolsPerFile: options.MaxSymbolsPerFile,
+                            maxReferencesPerFile: options.MaxReferencesPerFile,
+                            generatedExtractionSuppressed: generatedExtractionSuppressed,
+                            allowReuse: symbolKindFilterMatchesPrior
+                                && (record.Lang != "csharp" || csharpSymbolNameContractMatchesCurrent)
+                                && (record.Lang != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
+                                && (record.Lang != "sql" || sqlGraphContractMatchesCurrent)
+                                && (record.Lang is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent));
+                        if (existingId != null)
+                        {
+                            using var purgeTxn = writer.BeginTransaction(cancellationToken, "update purge unchanged stale paths");
+                            var purged = PurgeStaleUpdateCleanupPaths(
+                                record.Path,
+                                record.Checksum,
+                                includeDirectoryAndStem: persistenceOperations.IsProjectRootWritten());
+                            if (purged > 0)
+                            {
+                                DemoteReadinessOnce();
+                                WriteProjectRootOnce();
+                                RequireTypeScriptAugmentationRefresh();
+                                purgeTxn.Commit();
+                                removed += purged;
+                                ftsMutated = true;
+                                mutualRecursionRefreshNeeded = true;
+                            }
+                            skipped++;
+                            if (options.Verbose && !options.Json && !options.Quiet)
+                            {
+                                updateProgress.Pause();
+                                CommandOutputWriter.WriteLine(purged > 0
+                                    ? $"  [SKIP] {relPath} (unchanged; purged {purged:N0} stale renamed path(s))"
+                                    : $"  [SKIP] {relPath} (unchanged)");
+                                updateProgress.Resume();
+                            }
+                            continue;
                         }
-                        continue;
-                    }
 
-                    DemoteReadinessOnce();
-                    if (record.Lang == "csharp")
-                        csharpMetadataTargetsNeedRefresh = true;
-                    var persistence = PersistUpdateFile(new UpdateFilePersistenceContext
-                    {
-                        Writer = writer,
-                        Indexer = indexer,
-                        Options = options,
-                        ProjectRoot = projectRoot,
-                        RelativePath = relPath,
-                        AbsolutePath = absPath,
-                        Record = record,
-                        Loaded = loaded,
-                        GeneratedSuppressionIssue = generatedSuppressionIssue,
-                        CSharpWorkspace = csharpWorkspace,
-                        PostExtractionHooks = postExtractionHooks.Value,
-                        SymbolExtractionWorker = symbolExtractionWorker.Value,
-                        ProjectRootWritten = context.IsProjectRootWritten(),
-                        CancellationToken = cancellationToken,
-                        RequireTypeScriptAugmentationRefresh = RequireTypeScriptAugmentationRefresh,
-                        PurgeStaleUpdateCleanupPaths = PurgeStaleUpdateCleanupPaths,
-                        WriteProjectRootOnce = WriteProjectRootOnce,
-                        RecordDynamicGraphFileRefresh = RecordDynamicGraphFileRefresh,
-                        SetBatchMarkerOwned = owned => fileBatchMarked = owned,
-                        SetPhase = (path, phase) =>
+                        DemoteReadinessOnce();
+                        if (record.Lang == "csharp")
+                            csharpMetadataTargetsNeedRefresh = true;
+                        var persistence = PersistUpdateFile(new UpdateFilePersistenceContext
                         {
-                            currentUpdatePath = path;
-                            currentUpdatePhase = phase;
-                        },
-                    });
-                    symbolsDroppedByKindFilter += persistence.SymbolsDroppedByKindFilter;
-                    mutualRecursionRefreshNeeded |= persistence.MutualRecursionRefreshNeeded;
-                    updated++;
-                    ftsMutated = true;
-                    UpdateFileCommittedForTesting?.Invoke(updated + removed, targetPaths.Count);
-                    ThrowIfUpdateCancelled();
-                    updateProgress.WriteVerbose(persistence.VerboseMessage);
-                }
-                catch (IndexExtractionStalledException)
-                {
-                    throw;
-                }
-                catch (Exception ex)
-                {
-                    if (ex is CSharpWorkspaceChangedException)
-                    {
-                        if (fileBatchMarked)
-                            writer.ClearBatchInProgress();
-                        RecordCSharpWorkspaceDrift(relPath, ex.Message);
-                        skipped++;
-                        continue;
-                    }
-
-                    if (ex is FileIndexer.BinaryFileSkippedException
-                        or FileIndexer.FileTooLargeSkippedException)
-                    {
-                        if (fileBatchMarked)
-                            writer.ClearBatchInProgress();
-
-                        var skippedFile = HandleSkippedUpdateFile(
-                            new SkippedUpdateFileHandlingContext
+                            Writer = writer,
+                            Indexer = indexer,
+                            Options = options,
+                            ProjectRoot = projectRoot,
+                            RelativePath = relPath,
+                            AbsolutePath = absPath,
+                            Record = record,
+                            Loaded = loaded,
+                            GeneratedSuppressionIssue = generatedSuppressionIssue,
+                            CSharpWorkspace = csharpWorkspace,
+                            PostExtractionHooks = postExtractionHooks.Value,
+                            SymbolExtractionWorker = symbolExtractionWorker.Value,
+                            ProjectRootWritten = persistenceOperations.IsProjectRootWritten(),
+                            CancellationToken = cancellationToken,
+                            RequireTypeScriptAugmentationRefresh = RequireTypeScriptAugmentationRefresh,
+                            PurgeStaleUpdateCleanupPaths = PurgeStaleUpdateCleanupPaths,
+                            WriteProjectRootOnce = WriteProjectRootOnce,
+                            RecordDynamicGraphFileRefresh = RecordDynamicGraphFileRefresh,
+                            SetBatchMarkerOwned = owned => fileBatchMarked = owned,
+                            SetPhase = (path, phase) =>
                             {
-                                Writer = writer,
-                                Indexer = indexer,
-                                Options = options,
-                                AbsolutePath = absPath,
-                                RelativePath = relPath,
-                                IndexPath = dbPath,
-                                KnownLanguage = knownLanguage,
-                                ProjectRootWritten = context.IsProjectRootWritten(),
-                                TargetIndex = targetIndex,
-                                ReadableFileBytes = readableFileBytes,
-                                HasCSharpWorkspaceSnapshot =
-                                    hasCSharpWorkspaceSnapshot,
-                                CSharpWorkspaceSnapshot =
-                                    csharpWorkspaceSnapshot,
-                                CSharpWorkspaceSnapshots =
-                                    csharpWorkspaceSnapshots,
-                                WarningList = warningList,
-                                UpdateProgress = updateProgress,
-                                CancellationToken = cancellationToken,
-                                DemoteReadinessOnce = DemoteReadinessOnce,
-                                SetCurrentUpdatePhase =
-                                    phase => currentUpdatePhase = phase,
-                                RecordCSharpWorkspaceDrift =
-                                    RecordCSharpWorkspaceDrift,
-                                RecordUpdateFileFailure =
-                                    RecordUpdateFileFailure,
-                                PurgeStaleUpdateCleanupPaths =
-                                    PurgeStaleUpdateCleanupPaths,
-                                RequireTypeScriptAugmentationRefresh =
-                                    RequireTypeScriptAugmentationRefresh,
-                                WriteProjectRootOnce = WriteProjectRootOnce,
-                                RecordDynamicGraphFileRefresh =
-                                    RecordDynamicGraphFileRefresh,
+                                currentUpdatePath = path;
+                                currentUpdatePhase = phase;
                             },
-                            ex);
-                        updated += skippedFile.Updated;
-                        skipped += skippedFile.Skipped;
-                        warnings += skippedFile.Warnings;
-                        mutualRecursionRefreshNeeded |=
-                            skippedFile.MutualRecursionRefreshNeeded;
-                        if (skippedFile.Updated > 0)
-                        {
-                            ftsMutated = true;
-                        }
-                        continue;
+                        });
+                        symbolsDroppedByKindFilter += persistence.SymbolsDroppedByKindFilter;
+                        mutualRecursionRefreshNeeded |= persistence.MutualRecursionRefreshNeeded;
+                        updated++;
+                        ftsMutated = true;
+                        UpdateFileCommittedForTesting?.Invoke(updated + removed, targetPaths.Count);
+                        ThrowIfUpdateCancelled();
+                        updateProgress.WriteVerbose(persistence.VerboseMessage);
                     }
-
-                    if (ex is FileNotFoundException or DirectoryNotFoundException)
+                    catch (IndexExtractionStalledException)
                     {
-                        if (fileBatchMarked)
-                            writer.ClearBatchInProgress();
-
-                        if (hasCSharpWorkspaceSnapshot)
+                        throw;
+                    }
+                    catch (Exception ex)
+                    {
+                        if (ex is CSharpWorkspaceChangedException)
                         {
-                            RecordCSharpWorkspaceDrift(
-                                relPath,
-                                "The C# file disappeared during its authoritative update pass.");
+                            if (fileBatchMarked)
+                                writer.ClearBatchInProgress();
+                            RecordCSharpWorkspaceDrift(relPath, ex.Message);
                             skipped++;
                             continue;
                         }
 
-                        var message = $"{relPath}: skipped because it was deleted during indexing.";
-                        warnings++;
-                        warningList.Add(new CliJsonMessage(relPath, message));
-                        if (!options.Json && !options.Quiet)
+                        if (ex is FileIndexer.BinaryFileSkippedException
+                            or FileIndexer.FileTooLargeSkippedException)
                         {
-                            updateProgress.Pause();
-                            ConsoleUi.PrintWarning(message);
-                            updateProgress.Resume();
-                        }
+                            if (fileBatchMarked)
+                                writer.ClearBatchInProgress();
 
-                        if (writer.HasFileAtPath(dbPath))
-                        {
-                            DemoteReadinessOnce();
-                            using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing during write");
-                            if (writer.DeleteFileByPath(dbPath))
+                            var skippedFile = HandleSkippedUpdateFile(
+                                new SkippedUpdateFileHandlingContext
+                                {
+                                    Writer = writer,
+                                    Indexer = indexer,
+                                    Options = options,
+                                    AbsolutePath = absPath,
+                                    RelativePath = relPath,
+                                    IndexPath = dbPath,
+                                    KnownLanguage = knownLanguage,
+                                    ProjectRootWritten = persistenceOperations.IsProjectRootWritten(),
+                                    TargetIndex = targetIndex,
+                                    ReadableFileBytes = readableFileBytes,
+                                    HasCSharpWorkspaceSnapshot =
+                                        hasCSharpWorkspaceSnapshot,
+                                    CSharpWorkspaceSnapshot =
+                                        csharpWorkspaceSnapshot,
+                                    CSharpWorkspaceSnapshots =
+                                        csharpWorkspaceSnapshots,
+                                    WarningList = warningList,
+                                    UpdateProgress = updateProgress,
+                                    CancellationToken = cancellationToken,
+                                    DemoteReadinessOnce = DemoteReadinessOnce,
+                                    SetCurrentUpdatePhase =
+                                        phase => currentUpdatePhase = phase,
+                                    RecordCSharpWorkspaceDrift =
+                                        RecordCSharpWorkspaceDrift,
+                                    RecordUpdateFileFailure =
+                                        RecordUpdateFileFailure,
+                                    PurgeStaleUpdateCleanupPaths =
+                                        PurgeStaleUpdateCleanupPaths,
+                                    RequireTypeScriptAugmentationRefresh =
+                                        RequireTypeScriptAugmentationRefresh,
+                                    WriteProjectRootOnce = WriteProjectRootOnce,
+                                    RecordDynamicGraphFileRefresh =
+                                        RecordDynamicGraphFileRefresh,
+                                },
+                                ex);
+                            updated += skippedFile.Updated;
+                            skipped += skippedFile.Skipped;
+                            warnings += skippedFile.Warnings;
+                            mutualRecursionRefreshNeeded |=
+                                skippedFile.MutualRecursionRefreshNeeded;
+                            if (skippedFile.Updated > 0)
                             {
-                                WriteProjectRootOnce();
-                                RequireTypeScriptAugmentationRefresh();
-                                deleteTxn.Commit();
-                                removed++;
                                 ftsMutated = true;
-                                mutualRecursionRefreshNeeded = true;
                             }
+                            continue;
                         }
-                        else
+
+                        if (ex is FileNotFoundException or DirectoryNotFoundException)
                         {
-                            skipped++;
+                            if (fileBatchMarked)
+                                writer.ClearBatchInProgress();
+
+                            if (hasCSharpWorkspaceSnapshot)
+                            {
+                                RecordCSharpWorkspaceDrift(
+                                    relPath,
+                                    "The C# file disappeared during its authoritative update pass.");
+                                skipped++;
+                                continue;
+                            }
+
+                            var message = $"{relPath}: skipped because it was deleted during indexing.";
+                            warnings++;
+                            warningList.Add(new CliJsonMessage(relPath, message));
+                            if (!options.Json && !options.Quiet)
+                            {
+                                updateProgress.Pause();
+                                ConsoleUi.PrintWarning(message);
+                                updateProgress.Resume();
+                            }
+
+                            if (writer.HasFileAtPath(dbPath))
+                            {
+                                DemoteReadinessOnce();
+                                using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing during write");
+                                if (writer.DeleteFileByPath(dbPath))
+                                {
+                                    WriteProjectRootOnce();
+                                    RequireTypeScriptAugmentationRefresh();
+                                    deleteTxn.Commit();
+                                    removed++;
+                                    ftsMutated = true;
+                                    mutualRecursionRefreshNeeded = true;
+                                }
+                            }
+                            else
+                            {
+                                skipped++;
+                            }
+                            continue;
                         }
-                        continue;
-                    }
 
-                    if (fileBatchMarked)
-                        writer.ClearBatchInProgress();
-                    RecordUpdateFileFailure(relPath, currentUpdatePhase, ex);
+                        if (fileBatchMarked)
+                            writer.ClearBatchInProgress();
+                        RecordUpdateFileFailure(relPath, currentUpdatePhase, ex);
+                    }
                 }
             }
+            finally
+            {
+                StopIndexJsonPhaseHeartbeat(updateHeartbeat);
+            }
+            if (options.MemoryTrace)
+                memorySamples.Add(CaptureMemorySample("extraction", stopwatch));
+            return new UpdateFileLoopOutcome(
+                counters,
+                new UpdateFileLoopRefreshResult(
+                    ftsMutated,
+                    mutualRecursionRefreshNeeded,
+                    csharpMetadataTargetsNeedRefresh),
+                readableFileBytes);
         }
-        finally
-        {
-            StopIndexJsonPhaseHeartbeat(updateHeartbeat);
-        }
-        if (options.MemoryTrace)
-            memorySamples.Add(CaptureMemorySample("extraction", stopwatch));
-        return new UpdateFileLoopResult(
-            updated,
-            removed,
-            skipped,
-            warnings,
-            errors,
-            ftsMutated,
-            mutualRecursionRefreshNeeded,
-            csharpMetadataTargetsNeedRefresh,
-            symbolsDroppedByKindFilter,
-            readableFileBytes);
     }
 }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.Update.ParallelExtraction.cs b/src/CodeIndex/Cli/IndexCommandRunner.Update.ParallelExtraction.cs
index 9b18090e4..4c6780617 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.Update.ParallelExtraction.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.Update.ParallelExtraction.cs
@@ -736,21 +736,6 @@ private void DisposeResources()
         }
     }
 
-    private sealed class UpdatePrecomputedFilePersistenceContext
-    {
-        internal required DbWriter Writer { get; init; }
-        internal required IndexCommandOptions Options { get; init; }
-        internal required UpdateParallelExtractionResult Item { get; init; }
-        internal required bool ProjectRootWritten { get; init; }
-        internal required CancellationToken CancellationToken { get; init; }
-        internal required Action RequireTypeScriptAugmentationRefresh { get; init; }
-        internal required Func<string, string?, bool, int> PurgeStaleUpdateCleanupPaths { get; init; }
-        internal required Action WriteProjectRootOnce { get; init; }
-        internal required Action<string?> RecordDynamicGraphFileRefresh { get; init; }
-        internal required Action<bool> SetBatchMarkerOwned { get; init; }
-        internal required Action<string, string> SetPhase { get; init; }
-    }
-
     private static IReadOnlyList<UpdateParallelExtractionRequest> TryBuildUpdateParallelWindow(
         FileIndexer indexer,
         UpdateFileTarget[] targets,
@@ -1101,116 +1086,4 @@ void ThrowInjectedFailure()
         }
     }
 
-    private static UpdateFilePersistenceResult PersistPrecomputedUpdateFile(
-        UpdatePrecomputedFilePersistenceContext context)
-    {
-        var writer = context.Writer;
-        var options = context.Options;
-        var item = context.Item;
-        var record = item.Record!;
-        var cancellationToken = context.CancellationToken;
-        var mutualRecursionRefreshNeeded = false;
-
-        writer.MarkBatchInProgress();
-        context.SetBatchMarkerOwned(true);
-        using var txn = writer.BeginTransaction(
-            cancellationToken,
-            "update precomputed file");
-        var stalePurged = context.PurgeStaleUpdateCleanupPaths(
-            record.Path,
-            record.Checksum,
-            context.ProjectRootWritten);
-        if (stalePurged > 0 && !options.SymbolsOnly)
-            mutualRecursionRefreshNeeded = true;
-        if (stalePurged > 0)
-            context.RequireTypeScriptAugmentationRefresh();
-        context.WriteProjectRootOnce();
-        var fileId = writer.UpsertFile(record, out var referenceIdentityChanged);
-        if (!options.SymbolsOnly && referenceIdentityChanged)
-            mutualRecursionRefreshNeeded = true;
-
-        context.SetPhase(
-            FormatIndexPhasePath(item.Target.DisplayRelativePath, "chunking"),
-            "chunking");
-        var chunks = ReassignChunkFileIds(item.Chunks!, fileId);
-        if (item.GeneratedSuppressionIssue != null)
-        {
-            writer.InsertChunks(chunks, cancellationToken);
-            writer.InsertSymbols([], cancellationToken);
-            writer.InsertReferencesInAtomicFileScope(
-                [],
-                refreshMutualRecursionFlags: false,
-                cancellationToken);
-            context.SetPhase(
-                FormatIndexPhasePath(item.Target.DisplayRelativePath, "validating"),
-                "validating");
-            writer.InsertIssues(fileId, item.Issues!);
-            context.SetPhase(
-                FormatIndexPhasePath(item.Target.DisplayRelativePath, "committing"),
-                "committing");
-            writer.ClearBatchInProgress();
-            txn.Commit();
-            context.SetBatchMarkerOwned(false);
-            context.RecordDynamicGraphFileRefresh(record.Lang);
-            return new UpdateFilePersistenceResult(
-                0,
-                mutualRecursionRefreshNeeded,
-                $"  [OK  ] {item.Target.RelativePath} ({chunks.Count} chunks, generated-code extraction skipped)");
-        }
-
-        context.SetPhase(
-            FormatIndexPhasePath(item.Target.DisplayRelativePath, "symbols"),
-            "symbols");
-        var symbols = ReassignSymbolFileIds(item.Symbols!, fileId);
-        if (item.SymbolCapExceeded)
-        {
-            writer.InsertSymbols([], cancellationToken);
-            writer.InsertReferencesInAtomicFileScope(
-                [],
-                refreshMutualRecursionFlags: false,
-                cancellationToken);
-            writer.InsertIssues(fileId, item.Issues!);
-            writer.ClearBatchInProgress();
-            txn.Commit();
-            context.SetBatchMarkerOwned(false);
-            context.RecordDynamicGraphFileRefresh(record.Lang);
-            return new UpdateFilePersistenceResult(
-                0,
-                mutualRecursionRefreshNeeded,
-                $"  [SKIP] {item.Target.RelativePath} ({item.Issues![^1].Message})");
-        }
-
-        writer.InsertChunks(chunks, cancellationToken);
-        FileIndexer.ValidateSymbolLineRanges(record, symbols);
-        writer.InsertSymbols(symbols, cancellationToken);
-        context.SetPhase(
-            FormatIndexPhasePath(item.Target.DisplayRelativePath, "references"),
-            "references");
-        var references = ReassignReferenceFileIds(item.References!, fileId);
-        writer.InsertReferencesInAtomicFileScope(
-            references,
-            refreshMutualRecursionFlags: false,
-            cancellationToken);
-        context.SetPhase(
-            FormatIndexPhasePath(item.Target.DisplayRelativePath, "validating"),
-            "validating");
-        writer.InsertIssues(fileId, item.Issues!);
-        context.SetPhase(
-            FormatIndexPhasePath(item.Target.DisplayRelativePath, "committing"),
-            "committing");
-        writer.ClearBatchInProgress();
-        txn.Commit();
-        context.SetBatchMarkerOwned(false);
-        context.RecordDynamicGraphFileRefresh(record.Lang);
-        if (!options.SymbolsOnly
-            && (symbols.Count > 0 || references.Count > 0))
-        {
-            mutualRecursionRefreshNeeded = true;
-        }
-
-        return new UpdateFilePersistenceResult(
-            0,
-            mutualRecursionRefreshNeeded,
-            $"  [OK  ] {item.Target.RelativePath} ({chunks.Count} chunks, {symbols.Count} symbols, {references.Count} refs)");
-    }
 }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.Update.cs b/src/CodeIndex/Cli/IndexCommandRunner.Update.cs
index b1ede7a38..513f4a517 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.Update.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.Update.cs
@@ -342,28 +342,6 @@ void RecordScanErrors(
             }
         }
 
-        void RecordUpdateFileFailure(
-            string relativePath,
-            string phase,
-            Exception exception)
-        {
-            DemoteReadinessOnce();
-            LogIndexFileFailure("index_update_file_failed", relativePath, phase, exception);
-
-            errors++;
-            var errorMessage = FormatIndexFileException(exception);
-            errorList.Add(new CliJsonMessage(relativePath, errorMessage));
-            if (fileErrorList.Count < PartialIndexFileErrorLimit)
-                fileErrorList.Add(BuildIndexFileError(relativePath, phase, exception));
-            if (!options.Json)
-            {
-                updateProgress.Pause();
-                CommandErrorWriter.WriteStderr(
-                    FormatPerFileErrorLine("ERR ", relativePath, exception, errorMessage));
-                updateProgress.Resume();
-            }
-        }
-
         void ThrowIfUpdateCancelled()
         {
             if (!cancellationToken.IsCancellationRequested)
@@ -686,56 +664,72 @@ bool TryValidateCSharpWorkspaceInputSnapshot(
                 useUpdateSecondaryIndexStaging,
                 cancellationToken);
 
-        var updateLoop = RunUpdateFileLoop(new UpdateFileLoopContext
-        {
-            Writer = writer,
-            Indexer = indexer,
-            Options = options,
-            Stopwatch = stopwatch,
-            ProjectRoot = projectRoot,
-            IndexRunDiagnostics = indexRunDiagnostics,
-            TargetPaths = targetPaths,
-            UpdateProgress = updateProgress,
-            MemorySamples = memorySamples,
-            Updated = updated,
-            Removed = removed,
-            Skipped = skipped,
-            FtsMutated = ftsMutated,
-            MutualRecursionRefreshNeeded = mutualRecursionRefreshNeeded,
-            CSharpMetadataTargetsNeedRefresh = csharpMetadataTargetsNeedRefresh,
-            SymbolsDroppedByKindFilter = symbolsDroppedByKindFilter,
-            CSharpWorkspace = csharpWorkspace,
-            CSharpWorkspaceSnapshots = csharpWorkspaceSnapshots,
-            ScannedUpdateLanguages = scannedUpdateLanguages,
-            SymbolKindFilterMatchesPrior = symbolKindFilterMatchesPrior,
-            CSharpSymbolNameContractMatchesCurrent = csharpSymbolNameContractMatchesCurrent,
-            SqlGraphContractMatchesCurrent = sqlGraphContractMatchesCurrent,
-            HdlGraphContractMatchesCurrent = hdlGraphContractMatchesCurrent,
-            PostExtractionHooks = postExtractionHooks,
-            VisitedFileIdentities = visitedFileIdentities,
-            ErrorList = errorList,
-            FileErrorList = fileErrorList,
-            WarningList = warningList,
-            CancellationToken = cancellationToken,
-            RecordScanErrors = RecordScanErrors,
-            RecordCSharpWorkspaceDrift = RecordCSharpWorkspaceDrift,
-            DemoteReadinessOnce = DemoteReadinessOnce,
-            WriteProjectRootOnce = WriteProjectRootOnce,
-            RequireTypeScriptAugmentationRefresh = RequireTypeScriptAugmentationRefresh,
-            PurgeStaleUpdateCleanupPaths = PurgeStaleUpdateCleanupPaths,
-            RecordDynamicGraphFileRefresh = RecordDynamicGraphFileRefresh,
-            RecordUpdateFileFailure = RecordUpdateFileFailure,
-            IsProjectRootWritten = () => projectRootWritten,
-        });
-        updated = updateLoop.Updated;
-        removed = updateLoop.Removed;
-        skipped = updateLoop.Skipped;
-        warnings += updateLoop.Warnings;
-        errors += updateLoop.Errors;
-        ftsMutated = updateLoop.FtsMutated;
-        mutualRecursionRefreshNeeded = updateLoop.MutualRecursionRefreshNeeded;
-        csharpMetadataTargetsNeedRefresh = updateLoop.CSharpMetadataTargetsNeedRefresh;
-        symbolsDroppedByKindFilter = updateLoop.SymbolsDroppedByKindFilter;
+        var updateLoop = new UpdateFileLoopSession(
+            new UpdateFileLoopRuntime(
+                writer,
+                indexer,
+                options,
+                projectRoot,
+                updateProgress,
+                cancellationToken,
+                targetPaths,
+                memorySamples),
+            new UpdateFileLoopCounters(
+                updated,
+                removed,
+                skipped,
+                Warnings: 0,
+                Errors: 0,
+                symbolsDroppedByKindFilter),
+            new UpdateFileLoopRefreshState(
+                ftsMutated,
+                mutualRecursionRefreshNeeded,
+                csharpMetadataTargetsNeedRefresh,
+                CurrentPath: null,
+                CurrentPhase: "preparing",
+                ParallelSourceWorkspaceDriftDetected: false,
+                ReadableFileBytes: null),
+            new UpdateFileLoopWorkspace(
+                csharpWorkspace,
+                csharpWorkspaceSnapshots,
+                scannedUpdateLanguages,
+                symbolKindFilterMatchesPrior,
+                csharpSymbolNameContractMatchesCurrent,
+                sqlGraphContractMatchesCurrent,
+                hdlGraphContractMatchesCurrent),
+            new UpdateFileLoopOutput(
+                stopwatch,
+                indexRunDiagnostics,
+                postExtractionHooks,
+                visitedFileIdentities,
+                errorList,
+                fileErrorList,
+                warningList),
+            new UpdateFileLoopReadinessOperations(
+                RecordScanErrors,
+                RecordCSharpWorkspaceDrift,
+                DemoteReadinessOnce,
+                RequireTypeScriptAugmentationRefresh,
+                RecordDynamicGraphFileRefresh),
+            new UpdateFileLoopPersistenceOperations(
+                WriteProjectRootOnce,
+                PurgeStaleUpdateCleanupPaths,
+                () => projectRootWritten),
+            new UpdateFileLoopParallelTesting(
+                UpdateParallelExtractionEventForTesting,
+                UpdateParallelExtractionFailureForTesting,
+                IndexExtractionStallTimeoutForTesting,
+                UpdateParallelExtractionWorkersStoppedForTesting))
+            .Run();
+        updated = updateLoop.Counters.Updated;
+        removed = updateLoop.Counters.Removed;
+        skipped = updateLoop.Counters.Skipped;
+        warnings += updateLoop.Counters.Warnings;
+        errors += updateLoop.Counters.Errors;
+        ftsMutated = updateLoop.Refresh.FtsMutated;
+        mutualRecursionRefreshNeeded = updateLoop.Refresh.MutualRecursionRefreshNeeded;
+        csharpMetadataTargetsNeedRefresh = updateLoop.Refresh.CSharpMetadataTargetsNeedRefresh;
+        symbolsDroppedByKindFilter = updateLoop.Counters.SymbolsDroppedByKindFilter;
         var readableFileBytes = updateLoop.ReadableFileBytes;
 
         if (options.ChangedBetweenSpecified
diff --git a/tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs b/tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs
index 3135c3a4c..e400100dc 100644
--- a/tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs
+++ b/tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs
@@ -2199,6 +2199,10 @@ public void Run_UpdateFiles_AuthoritativeCSharpParallelWorkerFailureIsIsolatedWi
         var projectRoot = CreateTempProject();
         var previousFailureHook =
             IndexCommandRunner.UpdateParallelExtractionFailureForTesting;
+        var previousEventHook =
+            IndexCommandRunner.UpdateParallelExtractionEventForTesting;
+        var previousCommittedHook =
+            IndexCommandRunner.UpdateFileCommittedForTesting;
         try
         {
             CreateAuthoritativeParallelUpdateProject(
@@ -2216,16 +2220,35 @@ public void Run_UpdateFiles_AuthoritativeCSharpParallelWorkerFailureIsIsolatedWi
             var succeedingChecksumBefore = ReadIndexedChecksum(dbPath, succeedingPath);
             File.AppendAllText(Path.Combine(projectRoot, failingPath), "// fail symbols\n");
             File.AppendAllText(Path.Combine(projectRoot, succeedingPath), "// still persist\n");
+            File.AppendAllText(
+                Path.Combine(projectRoot, "Source02.cs"),
+                new string('x', 2049));
             File.SetLastWriteTimeUtc(
                 Path.Combine(projectRoot, failingPath),
                 DateTime.UtcNow.AddSeconds(2));
             File.SetLastWriteTimeUtc(
                 Path.Combine(projectRoot, succeedingPath),
                 DateTime.UtcNow.AddSeconds(2));
+            File.SetLastWriteTimeUtc(
+                Path.Combine(projectRoot, "Source02.cs"),
+                DateTime.UtcNow.AddSeconds(2));
+            var persistenceEvents = new ConcurrentQueue<(string Kind, int Index, string Path)>();
+            var committedFiles = new ConcurrentQueue<(int Processed, int Total)>();
             IndexCommandRunner.UpdateParallelExtractionFailureForTesting =
                 (path, phase) => path == failingPath && phase == "symbols"
                     ? new InvalidOperationException("parallel symbols failure")
                     : null;
+            IndexCommandRunner.UpdateParallelExtractionEventForTesting = item =>
+            {
+                if (item.Kind is
+                    IndexCommandRunner.UpdateParallelExtractionEventKind.PersistenceStarted
+                    or IndexCommandRunner.UpdateParallelExtractionEventKind.PersistenceCompleted)
+                {
+                    persistenceEvents.Enqueue((item.Kind.ToString(), item.TargetIndex, item.RelativePath));
+                }
+            };
+            IndexCommandRunner.UpdateFileCommittedForTesting = (processed, total) =>
+                committedFiles.Enqueue((processed, total));
 
             var (exitCode, json) = RunAndCaptureJson(
                 [
@@ -2233,25 +2256,54 @@ public void Run_UpdateFiles_AuthoritativeCSharpParallelWorkerFailureIsIsolatedWi
                     "--files",
                     failingPath,
                     succeedingPath,
+                    "IParseable.cs",
+                    "Source02.cs",
                     "--json",
                     "--parallelism",
                     "2",
+                    "--max-file-bytes",
+                    "512",
                 ]);
 
             Assert.Equal(CommandExitCodes.PartialResult, exitCode);
             Assert.Equal("partial", json.GetProperty("status").GetString());
+            var summary = json.GetProperty("summary");
+            Assert.Equal(3, summary.GetProperty("updated").GetInt32());
+            Assert.Equal(0, summary.GetProperty("removed").GetInt32());
+            Assert.Equal(0, summary.GetProperty("skipped").GetInt32());
+            Assert.Equal(0, summary.GetProperty("warnings").GetInt32());
+            Assert.Equal(1, summary.GetProperty("errors").GetInt32());
             Assert.Equal(failingChecksumBefore, ReadIndexedChecksum(dbPath, failingPath));
             Assert.NotEqual(succeedingChecksumBefore, ReadIndexedChecksum(dbPath, succeedingPath));
             var failure = Assert.Single(
                 json.GetProperty("file_errors").EnumerateArray(),
                 item => item.GetProperty("file").GetString() == failingPath);
             Assert.Equal("symbols", failure.GetProperty("phase").GetString());
+            Assert.Equal(
+                [
+                    ("PersistenceStarted", 1, "Source01.cs"),
+                    ("PersistenceCompleted", 1, "Source01.cs"),
+                    ("PersistenceStarted", 2, "IParseable.cs"),
+                    ("PersistenceCompleted", 2, "IParseable.cs"),
+                    ("PersistenceCompleted", 3, "Source02.cs"),
+                ],
+                persistenceEvents.ToArray());
+            Assert.Equal([(1, 4), (2, 4)], committedFiles.ToArray());
             Assert.False(json.GetProperty("csharp_metadata_target_ready").GetBoolean());
+            Assert.False(json.GetProperty("index_complete").GetBoolean());
+            AssertCompletenessReason(json, "index_incomplete_reasons", "file_too_large");
+            var (statusExitCode, status) = RunStatusAndCaptureJson(
+                ["--db", dbPath, "--json"]);
+            Assert.Equal(CommandExitCodes.Success, statusExitCode);
+            Assert.False(status.GetProperty("migration_in_progress").GetBoolean());
         }
         finally
         {
             IndexCommandRunner.UpdateParallelExtractionFailureForTesting =
                 previousFailureHook;
+            IndexCommandRunner.UpdateParallelExtractionEventForTesting =
+                previousEventHook;
+            IndexCommandRunner.UpdateFileCommittedForTesting = previousCommittedHook;
             DeleteDirectory(projectRoot);
         }
     }

From 59c88250e385a7346b9d62ef4d119157e59f0c54 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 14:11:21 +0900
Subject: [PATCH 40/45] Extract serial update target disposition

---
 TESTING_GUIDE.md                              |   4 +-
 ...ndRunner.Update.FileLoop.SerialConsumer.cs | 568 +++++++++++++++++
 ...unner.Update.FileLoop.SerialPersistence.cs | 261 ++++++++
 .../Cli/IndexCommandRunner.Update.FileLoop.cs | 572 +-----------------
 ...dexCommandRunner.Update.FilePersistence.cs | 269 --------
 .../IndexCommandRunnerUpdateTests.cs          |  52 +-
 6 files changed, 886 insertions(+), 840 deletions(-)
 create mode 100644 src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.SerialConsumer.cs
 create mode 100644 src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.SerialPersistence.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 90c70994e..46a2b626f 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -224,7 +224,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   YAML `outline` integration coverage must assert nested sequence paths, mapping-parent depth, unchanged source ranges and symbol counts, deterministic sorting, and cursor replay across a page boundary.
   Search-core orchestration coverage must keep validation ahead of database execution, preserve list-recipes > named-query > recipe > plain route precedence and the recipe-field-before-conflict / plain-conflict-before-field aggregation error order, keep count-mode zero/nonzero payloads aligned, retain strict-not-found exit semantics, and order profiled NDJSON as result records, profile metadata, then the terminal record.
   CLI parsing, command execution, and installer behavior. Index command coverage is split by run mode or feature area, and query command coverage is split by command family with partial test classes so shared console and fixture helpers stay centralized. Keep repeated query-result fixtures, such as overlapping chunk content used by multiple search deduplication tests, in narrow class-level helpers instead of duplicating local builders. `ProgramCliTests.cs` covers top-level entrypoint behavior that must be exercised through a subprocess, while `InstallScriptTests.cs` runs focused bash snippets against `install.sh` in library mode to lock in release-installer regressions without performing real network installs. Installer bundle-generation tests must also verify that `install.sh` is marked generated while every canonical `install_modules/` source remains unmarked.
-  Authoritative C# scoped-update coverage treats bounded parallel extraction as a correctness and resource contract. Keep the `2 * workers` window bound, fixed-worker reuse, whole-window extraction barrier, target-ordered single-writer persistence, and mixed-language serial boundary in the same suite. Required fallbacks cover parallelism one, active symbol filters, content-load seams, post-extraction hooks, non-authoritative or undersized snapshots, ambiguous nullable language reuse, and speculative probe exceptions returning to the serial per-file boundary. Serial/parallel parity must compare summaries, files/chunks/all semantic symbol and reference columns, normalized reference-line and candidate identities, hotspot aggregates, issues, readiness/user-version metadata, and last-run readable-byte counters across normal, generated, cap, and oversized inputs. Retain all three file-stat barriers. The ordered worker-failure fixture keeps a failed authoritative target, a normal changed target, an unchanged but explicitly targeted authoritative target, and an oversized target in one four-file window; pin the exact persistence-event and commit-hook order, isolated failure phase, incomplete reason, metadata demotion, and separately observed post-update migration-marker cleanup. Cancellation before persistence, after validated load, and at extraction completion must preserve the expected committed prefix, batch ownership, and derived readiness. Global watchdog and direct-fatal tests must assert active phase, bounded return, and terminal side effects; source-negative ordering tests must cover both cap-discarded confirmed evidence and an earlier lexical contract candidate still blocked in symbol extraction. Abnormal-window fixtures release every injected block and wait for the snapshotted all-workers-stopped seam before restoring static hooks or deleting the project root.
+  Authoritative C# scoped-update coverage treats bounded parallel extraction as a correctness and resource contract. Keep the `2 * workers` window bound, fixed-worker reuse, whole-window extraction barrier, target-ordered single-writer persistence, and mixed-language serial boundary in the same suite. Required fallbacks cover parallelism one, active symbol filters, content-load seams, post-extraction hooks, non-authoritative or undersized snapshots, ambiguous nullable language reuse, and speculative probe exceptions returning to the serial per-file boundary. Keep serial target disposition in its exact missing/delete, path-filter, indexability/language-probe, unsupported-purge, hardlink, stat-reuse, load/revalidate, reuse-cleanup, persistence, and catch order. Serial/parallel parity must compare summaries, files/chunks/all semantic symbol and reference columns, normalized reference-line and candidate identities, hotspot aggregates, issues, batch-marker cleanup, readiness/user-version metadata, and last-run readable-byte counters across normal, generated, cap, and oversized inputs. Retain all three file-stat barriers. The ordered worker-failure fixture keeps a failed authoritative target, a normal changed target, an unchanged but explicitly targeted authoritative target, and an oversized target in one four-file window; pin the exact persistence-event and commit-hook order, isolated failure phase, incomplete reason, metadata demotion, and separately observed post-update migration-marker cleanup. Cancellation before persistence, after validated load, and at extraction completion must preserve the expected committed prefix, batch ownership, and derived readiness. Global watchdog and direct-fatal tests must assert active phase, bounded return, and terminal side effects; source-negative ordering tests must cover both cap-discarded confirmed evidence and an earlier lexical contract candidate still blocked in symbol extraction. Abnormal-window fixtures release every injected block and wait for the snapshotted all-workers-stopped seam before restoring static hooks or deleting the project root.
   `JsonEnvelopeWrapperTests.cs` owns global JSON-envelope token-role coverage. Keep parser-accepted separated and inline query values, option ordering, the `--` end-of-options form, missing-value boundaries for other value-bearing options, and a genuine `--json-envelope` output request together so preprocessing cannot consume command data, suppress a structured error envelope, or place its injected `--json` after the positional boundary.
   Status-explain coverage must enumerate the source-generated `StatusResult` serializer properties and require every serialized top-level key to succeed without opening a database. Keep major readiness/trust/extension/maintenance/cap-hit metadata assertions, dotted-member resolution, bounded valid unknown candidates, and redaction of hostile field input in the same focused fixture so serialization and explainability cannot drift independently. Keep every structured explain response key registered for status `--fields` projection, and exercise the response through a bounded JSON projection that proves the outer envelope also omits runtime and path metadata.
   Safety-recipe semantic coverage must keep safe and unsafe controls in separate indexed files: assert that `Regex.Escape` / `Regex.Unescape` and literal `UseShellExecute=false` are absent, while matching, source-defined, or unresolved Regex members, literal `true`, and propagated shell-policy values remain with classification evidence. Include alias trivia, alias-like comments and strings, a qualified BCL call in a file with a bare `BoundedRegex` alias, a line break before literal `false`, and computed continuations after block and line comments. Also retain a bare receiver from a legacy index without current reference identity, add enough safe helpers to saturate the normal result envelope, keep count output aligned with full JSON, and retain a separate `new Regex` construction positive.
@@ -1291,7 +1291,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   YAML `outline` の integration coverage では、入れ子 sequence path、mapping parent の depth、不変な source range と symbol count、決定的な sort、page 境界を越える cursor replay を検証してください。
   search core の orchestration coverage では、validation が database execution より先に行われること、list-recipes > named-query > recipe > plain の route precedence と recipe では field error が conflict より先・plain では conflict が field error より先になる aggregation error 順、count mode の zero/nonzero payload、strict-not-found の exit semantics、profile 付き NDJSON が result record、profile metadata、terminal record の順になることを維持してください。
   CLI の引数解析、コマンド実行、installer 挙動のテスト。Index command coverage は run mode または機能領域ごとの partial suite に分割し、Query command coverage は command family ごとの partial test class に分割して、共有 console / fixture helper は一箇所に保ちます。`ProgramCliTests.cs` はグローバル引数の解釈や完全な CLI 起動フローのように subprocess 経由で確認すべき Program エントリポイント挙動を扱い、`InstallScriptTests.cs` は `install.sh` を library mode で source した bash snippet を実行して、実ネットワーク install を行わずに release installer の回帰を固定する。installer bundle 生成テストでは、`install.sh` が generated と判定される一方、canonical な `install_modules/` source はすべて unmarked のままであることも検証してください。
-  authoritative C# scoped update の coverage では、bounded parallel extraction を correctness と resource の契約として扱います。`2 * workers` の window 上限、固定 worker の再利用、window 全体の extraction barrier、target 順の single-writer persistence、mixed-language の serial 境界を同じ suite で維持してください。必須 fallback は parallelism 1、active symbol filter、content-load seam、post-extraction hook、non-authoritative / target 不足 snapshot、ambiguous な nullable language reuse、speculative probe 例外から serial per-file boundary への復帰を含みます。serial / parallel parity は normal、generated、cap、oversized input を横断し、summary、file / chunk、symbol / reference の全 semantic column、正規化した reference-line / candidate identity、hotspot aggregate、issue、readiness / user-version metadata、last-run readable-byte counter を比較してください。3段階の file-stat barrier も維持します。順序付き worker-failure fixture では、失敗する authoritative target、通常の変更 target、明示対象だが変更なしの authoritative target、oversized target を4-file windowにまとめ、persistence event と commit hook の厳密な順序、分離された failure phase、incomplete reason、metadata demotion、update後に独立観測する migration marker cleanupを固定してください。persistence 前、validated load 後、extraction completion 時の cancellation は、想定 committed prefix、batch ownership、derived readiness を固定します。global watchdog と direct fatal は active phase、bounded return、terminal side effect を検証し、source-negative ordering は cap で payload から除かれた confirmed evidence と、symbol extraction 中に block した earlier lexical contract candidate の両方を含めます。異常 window の fixture は注入 block をすべて解放し、snapshot 済み all-workers-stopped seam を待ってから static hook の復元と project root の削除を行ってください。
+  authoritative C# scoped update の coverage では、bounded parallel extraction を correctness と resource の契約として扱います。`2 * workers` の window 上限、固定 worker の再利用、window 全体の extraction barrier、target 順の single-writer persistence、mixed-language の serial 境界を同じ suite で維持してください。必須 fallback は parallelism 1、active symbol filter、content-load seam、post-extraction hook、non-authoritative / target 不足 snapshot、ambiguous な nullable language reuse、speculative probe 例外から serial per-file boundary への復帰を含みます。serial target disposition は missing/delete、path filter、indexability / language probe、unsupported purge、hardlink、stat reuse、load / revalidate、reuse cleanup、persistence、catch の厳密な順序を維持してください。serial / parallel parity は normal、generated、cap、oversized input を横断し、summary、file / chunk、symbol / reference の全 semantic column、正規化した reference-line / candidate identity、hotspot aggregate、issue、batch marker cleanup、readiness / user-version metadata、last-run readable-byte counter を比較してください。3段階の file-stat barrier も維持します。順序付き worker-failure fixture では、失敗する authoritative target、通常の変更 target、明示対象だが変更なしの authoritative target、oversized target を4-file windowにまとめ、persistence event と commit hook の厳密な順序、分離された failure phase、incomplete reason、metadata demotion、update後に独立観測する migration marker cleanupを固定してください。persistence 前、validated load 後、extraction completion 時の cancellation は、想定 committed prefix、batch ownership、derived readiness を固定します。global watchdog と direct fatal は active phase、bounded return、terminal side effect を検証し、source-negative ordering は cap で payload から除かれた confirmed evidence と、symbol extraction 中に block した earlier lexical contract candidate の両方を含めます。異常 window の fixture は注入 block をすべて解放し、snapshot 済み all-workers-stopped seam を待ってから static hook の復元と project root の削除を行ってください。
   `JsonEnvelopeWrapperTests.cs` は global JSON envelope の token role coverage を担当します。前処理が command data を消費したり、構造化 error envelope を抑止したり、補う `--json` を positional 境界より後ろへ置いたりしないよう、parser が受理する分離形式と inline 形式の query 値、option 順序、`--` end-of-options 形式、他の value-bearing option の missing-value 境界、実際の `--json-envelope` 出力要求を同じ fixture で維持してください。
   status explain の coverage は source-generated `StatusResult` serializer property を列挙し、database を開かずに serialized top-level key がすべて成功することを必須にします。主要な readiness / trust / extension / maintenance / cap-hit metadata、dot 区切り member resolution、unknown key に対する上限付きの有効な candidate、悪意ある field input の redaction を同じ focused fixture に置き、serialization と explainability が独立して drift しないようにしてください。structured explain response の全 key を status の `--fields` projection に登録し、outer envelope からも runtime / path metadata が省略されることを上限付き JSON projection で固定してください。
   safety recipe の意味論 coverage では、安全側と危険側の control を別々の indexed file に置いてください。`Regex.Escape` / `Regex.Unescape` と literal `UseShellExecute=false` が除外され、matching、source-defined、または解決不能な Regex member、literal `true`、伝播された shell-policy 値が classification evidence 付きで残ることを検証します。alias の trivia、alias に見える comment / string、bare `BoundedRegex` alias と完全修飾 BCL call が同居する file、literal `false` の前の改行、block / line comment の後に続く計算式を含めます。また、現行 reference identity を持たない legacy index の bare receiver を残すこと、通常の result envelope を埋める数の safe helper、count 出力と full JSON の一致、別の `new Regex` construction 正例も維持してください。
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.SerialConsumer.cs b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.SerialConsumer.cs
new file mode 100644
index 000000000..15dc6bdd5
--- /dev/null
+++ b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.SerialConsumer.cs
@@ -0,0 +1,568 @@
+using CodeIndex.Database;
+using CodeIndex.Indexer;
+using CodeIndex.Models;
+
+namespace CodeIndex.Cli;
+
+public static partial class IndexCommandRunner
+{
+    private sealed partial class UpdateFileLoopSession
+    {
+        private void ConsumeSerialUpdateTarget(
+            UpdateFileTarget target,
+            int targetIndex,
+            LazyDisposable<SymbolExtractionWorkerClient> symbolExtractionWorker)
+        {
+            ThrowIfUpdateCancelled();
+            updateProgress.Start();
+            var relPath = target.RelativePath;
+            currentUpdatePath = relPath;
+            currentUpdatePhase = "preparing";
+            var absPath = target.FilePath;
+            var dbPath = target.IndexPath;
+            var fileBatchMarked = false;
+            string? knownLanguage = null;
+            CSharpStaticInterfacePrepass.FileStatSnapshot csharpWorkspaceSnapshot = default;
+            var hasCSharpWorkspaceSnapshot = csharpWorkspaceSnapshots != null
+                && csharpWorkspaceSnapshots.TryGetValue(dbPath, out csharpWorkspaceSnapshot);
+            try
+            {
+                if (hasCSharpWorkspaceSnapshot
+                    && !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
+                        absPath,
+                        dbPath,
+                        relPath,
+                        csharpWorkspaceSnapshot.Size,
+                        csharpWorkspaceSnapshot.ModifiedUtc,
+                        csharpWorkspaceSnapshots!,
+                        out _,
+                        cancellationToken))
+                {
+                    RecordCSharpWorkspaceDrift(
+                        relPath,
+                        "The C# file changed before its authoritative update pass.");
+                    skipped++;
+                    return;
+                }
+
+                if (!File.Exists(LongPath.EnsureWindowsPrefix(absPath)))
+                {
+                    if (hasCSharpWorkspaceSnapshot)
+                    {
+                        RecordCSharpWorkspaceDrift(
+                            relPath,
+                            "The C# file disappeared after contract preflight.");
+                        skipped++;
+                        return;
+                    }
+
+                    using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing target");
+                    if (writer.DeleteFileByPath(dbPath))
+                    {
+                        DemoteReadinessOnce();
+                        WriteProjectRootOnce();
+                        RequireTypeScriptAugmentationRefresh();
+                        deleteTxn.Commit();
+                        removed++;
+                        ftsMutated = true;
+                        mutualRecursionRefreshNeeded = true;
+                        updateProgress.WriteVerbose($"  [DEL ] {relPath}");
+                    }
+                    else
+                    {
+                        skipped++;
+                        updateProgress.WriteVerbose($"  [SKIP] {relPath} (not in DB)");
+                    }
+                    return;
+                }
+
+                var pathFilter = indexer.EvaluatePathFilter(absPath);
+                RecordScanErrors(pathFilter.Errors);
+                if (pathFilter.ShouldSkip)
+                {
+                    if (!pathFilter.ShouldDeleteExisting)
+                    {
+                        skipped++;
+                        if (options.Verbose && !options.Json && !options.Quiet)
+                        {
+                            updateProgress.Pause();
+                            CommandOutputWriter.WriteLine($"  [SKIP] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
+                            updateProgress.Resume();
+                        }
+                        return;
+                    }
+
+                    using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete skipped path");
+                    if (writer.DeleteFileByPath(dbPath))
+                    {
+                        DemoteReadinessOnce();
+                        WriteProjectRootOnce();
+                        RequireTypeScriptAugmentationRefresh();
+                        deleteTxn.Commit();
+                        removed++;
+                        ftsMutated = true;
+                        mutualRecursionRefreshNeeded = true;
+                        if (options.Verbose && !options.Json && !options.Quiet)
+                        {
+                            updateProgress.Pause();
+                            CommandOutputWriter.WriteLine($"  [DEL ] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
+                            updateProgress.Resume();
+                        }
+                    }
+                    else
+                    {
+                        skipped++;
+                        if (options.Verbose && !options.Json)
+                        {
+                            updateProgress.Pause();
+                            CommandOutputWriter.WriteLine($"  [SKIP] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
+                            updateProgress.Resume();
+                        }
+                    }
+                    return;
+                }
+
+                var indexability = indexer.GetFileIndexabilityForIndexing(absPath);
+                var detection = indexer.TryDetectLanguageForIndexing(absPath, knownIndexability: indexability);
+                if (hasCSharpWorkspaceSnapshot
+                    && (indexability != FileIndexer.FileProbeStatus.Supported
+                        || detection.Status != FileIndexer.FileProbeStatus.Supported
+                        || detection.Language != "csharp"))
+                {
+                    RecordCSharpWorkspaceDrift(
+                        relPath,
+                        "The C# file changed language or indexability after contract preflight.");
+                    skipped++;
+                    return;
+                }
+                if (!hasCSharpWorkspaceSnapshot
+                    && csharpWorkspaceSnapshots != null
+                    && indexability == FileIndexer.FileProbeStatus.Supported
+                    && detection.Status == FileIndexer.FileProbeStatus.Supported
+                    && detection.Language == "csharp")
+                {
+                    RecordCSharpWorkspaceDrift(
+                        relPath,
+                        "A C# target appeared after the authoritative workspace target set was captured.");
+                    skipped++;
+                    return;
+                }
+                if (indexability == FileIndexer.FileProbeStatus.Missing || detection.Status == FileIndexer.FileProbeStatus.Missing)
+                {
+                    var message = $"{relPath}: skipped because it was deleted during indexing.";
+                    warnings++;
+                    warningList.Add(new CliJsonMessage(relPath, message));
+                    if (!options.Json && !options.Quiet)
+                    {
+                        updateProgress.Pause();
+                        ConsoleUi.PrintWarning(message);
+                        updateProgress.Resume();
+                    }
+
+                    using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing during probe");
+                    if (writer.DeleteFileByPath(dbPath))
+                    {
+                        DemoteReadinessOnce();
+                        WriteProjectRootOnce();
+                        RequireTypeScriptAugmentationRefresh();
+                        deleteTxn.Commit();
+                        removed++;
+                        ftsMutated = true;
+                        mutualRecursionRefreshNeeded = true;
+                    }
+                    else
+                    {
+                        skipped++;
+                    }
+                    return;
+                }
+
+                if (indexability == FileIndexer.FileProbeStatus.ProbeFailed || detection.Status == FileIndexer.FileProbeStatus.ProbeFailed)
+                {
+                    DemoteReadinessOnce();
+
+                    errors++;
+                    errorList.Add(new CliJsonMessage(relPath, "Could not probe file for indexability/language."));
+                    if (fileErrorList.Count < PartialIndexFileErrorLimit)
+                    {
+                        fileErrorList.Add(new StatusIndexFileError
+                        {
+                            File = FileIndexer.NormalizePathSeparators(relPath),
+                            Category = "file_read_error",
+                            Phase = "reading",
+                            Detail = "Could not probe file for indexability/language.",
+                        });
+                    }
+                    if (!options.Json)
+                    {
+                        updateProgress.Pause();
+                        if (options.Verbose)
+                            CommandErrorWriter.WriteStderr($"  [ERR ] {relPath}: Could not probe file for indexability/language.");
+                        else
+                            CommandErrorWriter.WriteStderr($"  [ERR ] {relPath}: Could not probe file for indexability/language.");
+                        updateProgress.Resume();
+                    }
+                    return;
+                }
+
+                if (indexability != FileIndexer.FileProbeStatus.Supported || detection.Status != FileIndexer.FileProbeStatus.Supported)
+                {
+                    if (!writer.HasFileAtPath(dbPath))
+                    {
+                        using var purgeTxn = writer.BeginTransaction(cancellationToken, "update purge unsupported renamed target");
+                        var purged = PurgeStaleUpdateCleanupPaths(
+                            dbPath,
+                            checksum: null,
+                            includeDirectoryAndStem: persistenceOperations.IsProjectRootWritten());
+                        if (purged > 0)
+                        {
+                            DemoteReadinessOnce();
+                            WriteProjectRootOnce();
+                            RequireTypeScriptAugmentationRefresh();
+                            purgeTxn.Commit();
+                            removed += purged;
+                            ftsMutated = true;
+                            mutualRecursionRefreshNeeded = true;
+                            if (options.Verbose && !options.Json && !options.Quiet)
+                            {
+                                updateProgress.Pause();
+                                CommandOutputWriter.WriteLine($"  [DEL ] {relPath} (unsupported renamed target)");
+                                updateProgress.Resume();
+                            }
+                        }
+                        else
+                        {
+                            skipped++;
+                            if (options.Verbose && !options.Json && !options.Quiet)
+                            {
+                                updateProgress.Pause();
+                                CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unsupported type)");
+                                updateProgress.Resume();
+                            }
+                        }
+                        return;
+                    }
+
+                    DemoteReadinessOnce();
+                    using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete unsupported target");
+                    if (writer.DeleteFileByPath(dbPath))
+                    {
+                        WriteProjectRootOnce();
+                        RequireTypeScriptAugmentationRefresh();
+                        deleteTxn.Commit();
+                        removed++;
+                        ftsMutated = true;
+                        mutualRecursionRefreshNeeded = true;
+                        if (options.Verbose && !options.Json && !options.Quiet)
+                        {
+                            updateProgress.Pause();
+                            CommandOutputWriter.WriteLine($"  [DEL ] {relPath} (no longer indexable)");
+                            updateProgress.Resume();
+                        }
+                    }
+                    else
+                    {
+                        skipped++;
+                        if (options.Verbose && !options.Json)
+                        {
+                            updateProgress.Pause();
+                            CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unsupported type)");
+                            updateProgress.Resume();
+                        }
+                    }
+                    return;
+                }
+
+                if (FileIndexer.TryGetFileIdentity(absPath, out var identity, out var linkCount)
+                    && linkCount > 1
+                    && !visitedFileIdentities.Add(identity))
+                {
+                    var message = "Skipped hardlinked file because the same file content was already indexed from another path.";
+                    warnings++;
+                    warningList.Add(new CliJsonMessage(relPath, message));
+                    if (!options.Json && !options.Quiet)
+                    {
+                        updateProgress.Pause();
+                        ConsoleUi.PrintWarning($"{relPath}: {message}");
+                        updateProgress.Resume();
+                    }
+
+                    using var deleteTxn = writer.BeginTransaction();
+                    if (writer.DeleteFileByPath(dbPath))
+                    {
+                        DemoteReadinessOnce();
+                        WriteProjectRootOnce();
+                        RequireTypeScriptAugmentationRefresh();
+                        deleteTxn.Commit();
+                        removed++;
+                        ftsMutated = true;
+                        mutualRecursionRefreshNeeded = true;
+                    }
+                    else
+                    {
+                        skipped++;
+                    }
+                    return;
+                }
+
+                var statReusableLanguage = GetStatReusableLanguage(absPath, detection);
+                var generatedExtractionSuppressed = indexer.IsGeneratedCodeExtractionSuppressed(dbPath);
+                var statMatchedFile = IndexedFileStatReuse.TryGetReusableUnchangedFile(
+                    writer,
+                    absPath,
+                    dbPath,
+                    statReusableLanguage,
+                    options.MaxFileSizeBytes ?? FileIndexer.DefaultMaxFileSizeBytes,
+                    options.MaxSymbolsPerFile,
+                    options.MaxReferencesPerFile,
+                    generatedExtractionSuppressed,
+                    allowReuse: symbolKindFilterMatchesPrior
+                        && (statReusableLanguage != "csharp" || csharpSymbolNameContractMatchesCurrent)
+                        && (statReusableLanguage != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
+                        && (statReusableLanguage != "sql" || sqlGraphContractMatchesCurrent)
+                        && (statReusableLanguage is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent));
+                if (statMatchedFile != null)
+                {
+                    skipped++;
+                    readableFileBytes.Remember(targetIndex, statMatchedFile.Value.Size);
+                    if (options.Verbose && !options.Json && !options.Quiet)
+                    {
+                        updateProgress.Pause();
+                        CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unchanged)");
+                        updateProgress.Resume();
+                    }
+                    return;
+                }
+
+                knownLanguage = scannedUpdateLanguages == null
+                    ? statReusableLanguage
+                    : FileIndexer.GetReusableDetectedLanguage(absPath, scannedUpdateLanguages);
+
+                currentUpdatePhase = "reading";
+                UpdateFileContentLoadForTesting?.Invoke(relPath);
+                var loaded = indexer.BuildLoadedRecordWithRawBytes(
+                    absPath,
+                    relPath,
+                    knownLanguage,
+                    cancellationToken);
+                var record = loaded.Record;
+                if (hasCSharpWorkspaceSnapshot
+                    && (record.Lang != "csharp"
+                        || !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
+                            absPath,
+                            dbPath,
+                            relPath,
+                            record.Size,
+                            record.Modified,
+                            csharpWorkspaceSnapshots!,
+                            out _,
+                            cancellationToken)))
+                {
+                    RecordCSharpWorkspaceDrift(
+                        relPath,
+                        "The C# file changed while the authoritative update pass was reading it.");
+                    skipped++;
+                    return;
+                }
+                readableFileBytes.Remember(targetIndex, record.Size);
+                var warning = loaded.Warning;
+                var generatedSuppressionIssue = generatedExtractionSuppressed
+                    ? indexer.BuildGeneratedCodeExtractionSkippedIssue(record.Path)
+                    : null;
+
+                if (warning != null && !options.Json && !options.Quiet)
+                {
+                    updateProgress.Pause();
+                    ConsoleUi.PrintWarning(warning);
+                    updateProgress.Resume();
+                }
+
+                var existingId = writer.GetReusableUnchangedFileId(
+                    record.Path,
+                    record.Modified,
+                    record.Checksum,
+                    size: record.Size,
+                    lines: record.Lines,
+                    language: record.Lang,
+                    generated: record.Generated,
+                    maxSymbolsPerFile: options.MaxSymbolsPerFile,
+                    maxReferencesPerFile: options.MaxReferencesPerFile,
+                    generatedExtractionSuppressed: generatedExtractionSuppressed,
+                    allowReuse: symbolKindFilterMatchesPrior
+                        && (record.Lang != "csharp" || csharpSymbolNameContractMatchesCurrent)
+                        && (record.Lang != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
+                        && (record.Lang != "sql" || sqlGraphContractMatchesCurrent)
+                        && (record.Lang is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent));
+                if (existingId != null)
+                {
+                    using var purgeTxn = writer.BeginTransaction(cancellationToken, "update purge unchanged stale paths");
+                    var purged = PurgeStaleUpdateCleanupPaths(
+                        record.Path,
+                        record.Checksum,
+                        includeDirectoryAndStem: persistenceOperations.IsProjectRootWritten());
+                    if (purged > 0)
+                    {
+                        DemoteReadinessOnce();
+                        WriteProjectRootOnce();
+                        RequireTypeScriptAugmentationRefresh();
+                        purgeTxn.Commit();
+                        removed += purged;
+                        ftsMutated = true;
+                        mutualRecursionRefreshNeeded = true;
+                    }
+                    skipped++;
+                    if (options.Verbose && !options.Json && !options.Quiet)
+                    {
+                        updateProgress.Pause();
+                        CommandOutputWriter.WriteLine(purged > 0
+                            ? $"  [SKIP] {relPath} (unchanged; purged {purged:N0} stale renamed path(s))"
+                            : $"  [SKIP] {relPath} (unchanged)");
+                        updateProgress.Resume();
+                    }
+                    return;
+                }
+
+                DemoteReadinessOnce();
+                if (record.Lang == "csharp")
+                    csharpMetadataTargetsNeedRefresh = true;
+                _ = postExtractionHooks.Value;
+                var persistence = PersistSerialUpdateFile(
+                    relPath,
+                    absPath,
+                    record,
+                    loaded,
+                    generatedSuppressionIssue,
+                    symbolExtractionWorker.Value,
+                    persistenceOperations.IsProjectRootWritten(),
+                    ref fileBatchMarked);
+                symbolsDroppedByKindFilter += persistence.SymbolsDroppedByKindFilter;
+                mutualRecursionRefreshNeeded |= persistence.MutualRecursionRefreshNeeded;
+                updated++;
+                ftsMutated = true;
+                UpdateFileCommittedForTesting?.Invoke(updated + removed, targetPaths.Count);
+                ThrowIfUpdateCancelled();
+                updateProgress.WriteVerbose(persistence.VerboseMessage);
+            }
+            catch (IndexExtractionStalledException)
+            {
+                throw;
+            }
+            catch (Exception ex)
+            {
+                if (ex is CSharpWorkspaceChangedException)
+                {
+                    if (fileBatchMarked)
+                        writer.ClearBatchInProgress();
+                    RecordCSharpWorkspaceDrift(relPath, ex.Message);
+                    skipped++;
+                    return;
+                }
+
+                if (ex is FileIndexer.BinaryFileSkippedException
+                    or FileIndexer.FileTooLargeSkippedException)
+                {
+                    if (fileBatchMarked)
+                        writer.ClearBatchInProgress();
+
+                    var skippedFile = HandleSkippedUpdateFile(
+                        new SkippedUpdateFileHandlingContext
+                        {
+                            Writer = writer,
+                            Indexer = indexer,
+                            Options = options,
+                            AbsolutePath = absPath,
+                            RelativePath = relPath,
+                            IndexPath = dbPath,
+                            KnownLanguage = knownLanguage,
+                            ProjectRootWritten = persistenceOperations.IsProjectRootWritten(),
+                            TargetIndex = targetIndex,
+                            ReadableFileBytes = readableFileBytes,
+                            HasCSharpWorkspaceSnapshot =
+                                hasCSharpWorkspaceSnapshot,
+                            CSharpWorkspaceSnapshot =
+                                csharpWorkspaceSnapshot,
+                            CSharpWorkspaceSnapshots =
+                                csharpWorkspaceSnapshots,
+                            WarningList = warningList,
+                            UpdateProgress = updateProgress,
+                            CancellationToken = cancellationToken,
+                            DemoteReadinessOnce = DemoteReadinessOnce,
+                            SetCurrentUpdatePhase =
+                                phase => currentUpdatePhase = phase,
+                            RecordCSharpWorkspaceDrift =
+                                RecordCSharpWorkspaceDrift,
+                            RecordUpdateFileFailure =
+                                RecordUpdateFileFailure,
+                            PurgeStaleUpdateCleanupPaths =
+                                PurgeStaleUpdateCleanupPaths,
+                            RequireTypeScriptAugmentationRefresh =
+                                RequireTypeScriptAugmentationRefresh,
+                            WriteProjectRootOnce = WriteProjectRootOnce,
+                            RecordDynamicGraphFileRefresh =
+                                RecordDynamicGraphFileRefresh,
+                        },
+                        ex);
+                    updated += skippedFile.Updated;
+                    skipped += skippedFile.Skipped;
+                    warnings += skippedFile.Warnings;
+                    mutualRecursionRefreshNeeded |=
+                        skippedFile.MutualRecursionRefreshNeeded;
+                    if (skippedFile.Updated > 0)
+                    {
+                        ftsMutated = true;
+                    }
+                    return;
+                }
+
+                if (ex is FileNotFoundException or DirectoryNotFoundException)
+                {
+                    if (fileBatchMarked)
+                        writer.ClearBatchInProgress();
+
+                    if (hasCSharpWorkspaceSnapshot)
+                    {
+                        RecordCSharpWorkspaceDrift(
+                            relPath,
+                            "The C# file disappeared during its authoritative update pass.");
+                        skipped++;
+                        return;
+                    }
+
+                    var message = $"{relPath}: skipped because it was deleted during indexing.";
+                    warnings++;
+                    warningList.Add(new CliJsonMessage(relPath, message));
+                    if (!options.Json && !options.Quiet)
+                    {
+                        updateProgress.Pause();
+                        ConsoleUi.PrintWarning(message);
+                        updateProgress.Resume();
+                    }
+
+                    if (writer.HasFileAtPath(dbPath))
+                    {
+                        DemoteReadinessOnce();
+                        using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing during write");
+                        if (writer.DeleteFileByPath(dbPath))
+                        {
+                            WriteProjectRootOnce();
+                            RequireTypeScriptAugmentationRefresh();
+                            deleteTxn.Commit();
+                            removed++;
+                            ftsMutated = true;
+                            mutualRecursionRefreshNeeded = true;
+                        }
+                    }
+                    else
+                    {
+                        skipped++;
+                    }
+                    return;
+                }
+
+                if (fileBatchMarked)
+                    writer.ClearBatchInProgress();
+                RecordUpdateFileFailure(relPath, currentUpdatePhase, ex);
+            }
+        }
+    }
+}
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.SerialPersistence.cs b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.SerialPersistence.cs
new file mode 100644
index 000000000..84d9d5fed
--- /dev/null
+++ b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.SerialPersistence.cs
@@ -0,0 +1,261 @@
+using CodeIndex.Indexer;
+using CodeIndex.Indexer.Extensibility;
+using CodeIndex.Indexer.Hooks;
+using CodeIndex.Models;
+
+namespace CodeIndex.Cli;
+
+public static partial class IndexCommandRunner
+{
+    private sealed partial class UpdateFileLoopSession
+    {
+        private UpdateFilePersistenceResult PersistSerialUpdateFile(
+            string relativePath,
+            string absolutePath,
+            FileRecord record,
+            LoadedFileRecord loaded,
+            FileIssue? generatedSuppressionIssue,
+            SymbolExtractionWorkerClient symbolExtractionWorker,
+            bool projectRootWritten,
+            ref bool fileBatchMarked)
+        {
+            var mutualRecursionRefreshNeeded = false;
+            var symbolsDroppedByKindFilter = 0;
+
+            writer.MarkBatchInProgress();
+            fileBatchMarked = true;
+            var recordRequiresTypeScriptAugmentationRefresh = record.Lang == "typescript";
+            using var txn = writer.BeginTransaction(cancellationToken, "update file");
+            if (recordRequiresTypeScriptAugmentationRefresh)
+                RequireTypeScriptAugmentationRefresh();
+            var stalePurged = PurgeStaleUpdateCleanupPaths(
+                record.Path,
+                record.Checksum,
+                projectRootWritten);
+            if (stalePurged > 0)
+            {
+                RequireTypeScriptAugmentationRefresh();
+                if (!options.SymbolsOnly)
+                    mutualRecursionRefreshNeeded = true;
+            }
+            WriteProjectRootOnce();
+            var fileId = writer.UpsertFile(record, out var referenceIdentityChanged);
+            if (!options.SymbolsOnly && referenceIdentityChanged)
+                mutualRecursionRefreshNeeded = true;
+            SetUpdatePhase(FormatIndexPhasePath(relativePath, "chunking"), "chunking");
+            var chunks = ChunkSplitter.SplitNormalized(
+                fileId,
+                loaded.Content,
+                loaded.Facts);
+            if (generatedSuppressionIssue != null)
+            {
+                writer.InsertChunks(chunks, cancellationToken);
+                writer.InsertSymbols([], cancellationToken);
+                writer.InsertReferencesInAtomicFileScope(
+                    [],
+                    refreshMutualRecursionFlags: false,
+                    cancellationToken);
+                SetUpdatePhase(
+                    FormatIndexPhasePath(relativePath, "validating"),
+                    "validating");
+                var generatedIssues = AppendIssueIfMissing(
+                    FileIndexer.ValidateContent(
+                        record.Path,
+                        loaded.RawBytes,
+                        loaded.Content,
+                        record.Lang,
+                        loaded.Inspection,
+                        loaded.Facts),
+                    generatedSuppressionIssue);
+                writer.InsertIssues(fileId, generatedIssues);
+                SetUpdatePhase(
+                    FormatIndexPhasePath(relativePath, "committing"),
+                    "committing");
+                writer.ClearBatchInProgress();
+                txn.Commit();
+                fileBatchMarked = false;
+                RecordDynamicGraphFileRefresh(record.Lang);
+                return new UpdateFilePersistenceResult(
+                    0,
+                    mutualRecursionRefreshNeeded,
+                    $"  [OK  ] {relativePath} ({chunks.Count} chunks, generated-code extraction skipped)");
+            }
+
+            SetUpdatePhase(FormatIndexPhasePath(relativePath, "symbols"), "symbols");
+            var symbolExtraction = ExtractSymbolsWithStallTimeout(
+                fileId,
+                record.Lang,
+                loaded.Content,
+                absolutePath,
+                projectRoot,
+                record.Path,
+                FormatIndexPhasePath(relativePath, "symbols"),
+                true,
+                loaded.HasOversizeLine,
+                loaded.ConflictMarkerLine,
+                symbolExtractionWorker,
+                cancellationToken);
+            var symbols = symbolExtraction.Symbols;
+            var symbolRegexTimeoutIssue = symbolExtraction.RegexTimeoutIssue;
+            var fileContext = new FileContext(
+                projectRoot,
+                record.Path,
+                absolutePath,
+                record.Lang);
+            var sourceContractSeenBeforeObservation =
+                postExtractionHooks.Value.SawCSharpStaticInterfaceSourceContract;
+            postExtractionHooks.Value.ObserveCSharpStaticInterfaceSourceSymbols(
+                fileContext,
+                symbols);
+            if (record.Lang == "csharp"
+                && !csharpWorkspace.HasSourceStaticInterfaceContracts
+                && !sourceContractSeenBeforeObservation
+                && postExtractionHooks.Value.SawCSharpStaticInterfaceSourceContract)
+            {
+                writer.SetCSharpStaticInterfaceSourceEvidence(null);
+                throw new CSharpWorkspaceChangedException(
+                    "A C# static-interface contract appeared after workspace preflight.");
+            }
+            if (symbols.Count > options.MaxSymbolsPerFile)
+            {
+                var issue = BuildSymbolCountExceededIssue(
+                    record.Path,
+                    symbols.Count,
+                    options.MaxSymbolsPerFile);
+                IReadOnlyList<FileIssue> capIssues = symbolRegexTimeoutIssue == null
+                    ? [issue]
+                    : AppendIssue([symbolRegexTimeoutIssue], issue);
+                writer.InsertSymbols([], cancellationToken);
+                writer.InsertReferencesInAtomicFileScope(
+                    [],
+                    refreshMutualRecursionFlags: false,
+                    cancellationToken);
+                writer.InsertIssues(fileId, capIssues);
+                writer.ClearBatchInProgress();
+                txn.Commit();
+                fileBatchMarked = false;
+                RecordDynamicGraphFileRefresh(record.Lang);
+                return new UpdateFilePersistenceResult(
+                    0,
+                    mutualRecursionRefreshNeeded,
+                    $"  [SKIP] {relativePath} ({issue.Message})");
+            }
+
+            var familyScopeKey = indexer.GetFamilyScopeKey(absolutePath, record.Lang);
+            SymbolExtractor.ApplyFamilyScope(symbols, familyScopeKey, record.Lang);
+            postExtractionHooks.Value.OnSymbolsExtractedAfterSourceObservation(
+                fileContext,
+                symbols,
+                loaded.Content,
+                familyScopeKey);
+            symbolsDroppedByKindFilter = options.SymbolKindFilter.Apply(symbols);
+            if (symbols.Count > options.MaxSymbolsPerFile)
+            {
+                var issue = BuildSymbolCountExceededIssue(
+                    record.Path,
+                    symbols.Count,
+                    options.MaxSymbolsPerFile);
+                IReadOnlyList<FileIssue> capIssues = symbolRegexTimeoutIssue == null
+                    ? [issue]
+                    : AppendIssue([symbolRegexTimeoutIssue], issue);
+                writer.InsertSymbols([], cancellationToken);
+                writer.InsertReferencesInAtomicFileScope(
+                    [],
+                    refreshMutualRecursionFlags: false,
+                    cancellationToken);
+                writer.InsertIssues(fileId, capIssues);
+                writer.ClearBatchInProgress();
+                txn.Commit();
+                fileBatchMarked = false;
+                RecordDynamicGraphFileRefresh(record.Lang);
+                return new UpdateFilePersistenceResult(
+                    symbolsDroppedByKindFilter,
+                    mutualRecursionRefreshNeeded,
+                    $"  [SKIP] {relativePath} ({issue.Message})");
+            }
+
+            writer.InsertChunks(chunks, cancellationToken);
+            FileIndexer.ValidateSymbolLineRanges(record, symbols);
+            writer.InsertSymbols(symbols, cancellationToken);
+            SetUpdatePhase(
+                FormatIndexPhasePath(relativePath, "references"),
+                "references");
+            List<ReferenceRecord> references;
+            FileIssue? referenceRegexTimeoutIssue;
+            ReferenceExtractionResult referenceExtraction;
+            using (var regexTimeouts = BoundedRegex.CaptureTimeouts(
+                       record.Lang,
+                       "reference_extraction"))
+            {
+                referenceExtraction = ReferenceExtractor.ExtractDetailedNormalized(
+                    fileId,
+                    record.Lang,
+                    loaded.Content,
+                    loaded.HasOversizeLine,
+                    symbols,
+                    record.Path,
+                    record.Lang == "csharp" ? csharpWorkspace.Symbols : null,
+                    cancellationToken,
+                    maxReferenceCount: options.MaxReferencesPerFile + 1,
+                    conflictMarkerLine: loaded.ConflictMarkerLine,
+                    workspaceRoot: projectRoot,
+                    csharpStaticInterfaceMemberLookups:
+                        csharpWorkspace.StaticInterfaceMemberLookups,
+                    csharpQualifiedPatternLookups:
+                        csharpWorkspace.QualifiedPatternLookups);
+                references = referenceExtraction.References;
+                referenceRegexTimeoutIssue =
+                    BuildRegexTimeoutIssue(record.Path, regexTimeouts);
+            }
+            postExtractionHooks.Value.OnReferencesExtracted(fileContext, references);
+            FileIssue? referenceCapIssue = null;
+            if (references.Count > options.MaxReferencesPerFile)
+            {
+                referenceCapIssue = BuildReferenceCountExceededIssue(
+                    record.Path,
+                    references.Count,
+                    options.MaxReferencesPerFile);
+                references = [];
+            }
+            writer.InsertReferencesInAtomicFileScope(
+                references,
+                refreshMutualRecursionFlags: false,
+                cancellationToken);
+            SetUpdatePhase(
+                FormatIndexPhasePath(relativePath, "validating"),
+                "validating");
+            IReadOnlyList<FileIssue> issues = FileIndexer.ValidateContent(
+                record.Path,
+                loaded.RawBytes,
+                loaded.Content,
+                record.Lang,
+                loaded.Inspection,
+                loaded.Facts);
+            if (symbolRegexTimeoutIssue != null)
+                issues = AppendIssue(issues, symbolRegexTimeoutIssue);
+            if (referenceRegexTimeoutIssue != null)
+                issues = AppendIssue(issues, referenceRegexTimeoutIssue);
+            issues = AppendReferenceExtractionDiagnosticIssues(
+                issues,
+                record.Path,
+                referenceExtraction.Diagnostics);
+            if (referenceCapIssue != null)
+                issues = AppendIssue(issues, referenceCapIssue);
+            writer.InsertIssues(fileId, issues);
+            SetUpdatePhase(
+                FormatIndexPhasePath(relativePath, "committing"),
+                "committing");
+            writer.ClearBatchInProgress();
+            txn.Commit();
+            fileBatchMarked = false;
+            RecordDynamicGraphFileRefresh(record.Lang);
+            if (!options.SymbolsOnly && (symbols.Count > 0 || references.Count > 0))
+                mutualRecursionRefreshNeeded = true;
+
+            return new UpdateFilePersistenceResult(
+                symbolsDroppedByKindFilter,
+                mutualRecursionRefreshNeeded,
+                $"  [OK  ] {relativePath} ({chunks.Count} chunks, {symbols.Count} symbols, {references.Count} refs)");
+        }
+    }
+}
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.cs b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.cs
index 415e7932e..44df2fd7e 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.Update.FileLoop.cs
@@ -242,574 +242,10 @@ void NotifyUpdateExtractionWorkStarted()
                         }
                     }
 
-                    var target = updateTargets[targetIndex];
-                    ThrowIfUpdateCancelled();
-                    updateProgress.Start();
-                    var relPath = target.RelativePath;
-                    currentUpdatePath = relPath;
-                    currentUpdatePhase = "preparing";
-                    var absPath = target.FilePath;
-                    var dbPath = target.IndexPath;
-                    var fileBatchMarked = false;
-                    string? knownLanguage = null;
-                    CSharpStaticInterfacePrepass.FileStatSnapshot csharpWorkspaceSnapshot = default;
-                    var hasCSharpWorkspaceSnapshot = csharpWorkspaceSnapshots != null
-                        && csharpWorkspaceSnapshots.TryGetValue(dbPath, out csharpWorkspaceSnapshot);
-                    try
-                    {
-                        if (hasCSharpWorkspaceSnapshot
-                            && !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
-                                absPath,
-                                dbPath,
-                                relPath,
-                                csharpWorkspaceSnapshot.Size,
-                                csharpWorkspaceSnapshot.ModifiedUtc,
-                                csharpWorkspaceSnapshots!,
-                                out _,
-                                cancellationToken))
-                        {
-                            RecordCSharpWorkspaceDrift(
-                                relPath,
-                                "The C# file changed before its authoritative update pass.");
-                            skipped++;
-                            continue;
-                        }
-
-                        if (!File.Exists(LongPath.EnsureWindowsPrefix(absPath)))
-                        {
-                            if (hasCSharpWorkspaceSnapshot)
-                            {
-                                RecordCSharpWorkspaceDrift(
-                                    relPath,
-                                    "The C# file disappeared after contract preflight.");
-                                skipped++;
-                                continue;
-                            }
-
-                            using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing target");
-                            if (writer.DeleteFileByPath(dbPath))
-                            {
-                                DemoteReadinessOnce();
-                                WriteProjectRootOnce();
-                                RequireTypeScriptAugmentationRefresh();
-                                deleteTxn.Commit();
-                                removed++;
-                                ftsMutated = true;
-                                mutualRecursionRefreshNeeded = true;
-                                updateProgress.WriteVerbose($"  [DEL ] {relPath}");
-                            }
-                            else
-                            {
-                                skipped++;
-                                updateProgress.WriteVerbose($"  [SKIP] {relPath} (not in DB)");
-                            }
-                            continue;
-                        }
-
-                        var pathFilter = indexer.EvaluatePathFilter(absPath);
-                        RecordScanErrors(pathFilter.Errors);
-                        if (pathFilter.ShouldSkip)
-                        {
-                            if (!pathFilter.ShouldDeleteExisting)
-                            {
-                                skipped++;
-                                if (options.Verbose && !options.Json && !options.Quiet)
-                                {
-                                    updateProgress.Pause();
-                                    CommandOutputWriter.WriteLine($"  [SKIP] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
-                                    updateProgress.Resume();
-                                }
-                                continue;
-                            }
-
-                            using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete skipped path");
-                            if (writer.DeleteFileByPath(dbPath))
-                            {
-                                DemoteReadinessOnce();
-                                WriteProjectRootOnce();
-                                RequireTypeScriptAugmentationRefresh();
-                                deleteTxn.Commit();
-                                removed++;
-                                ftsMutated = true;
-                                mutualRecursionRefreshNeeded = true;
-                                if (options.Verbose && !options.Json && !options.Quiet)
-                                {
-                                    updateProgress.Pause();
-                                    CommandOutputWriter.WriteLine($"  [DEL ] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
-                                    updateProgress.Resume();
-                                }
-                            }
-                            else
-                            {
-                                skipped++;
-                                if (options.Verbose && !options.Json)
-                                {
-                                    updateProgress.Pause();
-                                    CommandOutputWriter.WriteLine($"  [SKIP] {relPath} ({DescribePathFilter(pathFilter.FilterKind)})");
-                                    updateProgress.Resume();
-                                }
-                            }
-                            continue;
-                        }
-
-                        var indexability = indexer.GetFileIndexabilityForIndexing(absPath);
-                        var detection = indexer.TryDetectLanguageForIndexing(absPath, knownIndexability: indexability);
-                        if (hasCSharpWorkspaceSnapshot
-                            && (indexability != FileIndexer.FileProbeStatus.Supported
-                                || detection.Status != FileIndexer.FileProbeStatus.Supported
-                                || detection.Language != "csharp"))
-                        {
-                            RecordCSharpWorkspaceDrift(
-                                relPath,
-                                "The C# file changed language or indexability after contract preflight.");
-                            skipped++;
-                            continue;
-                        }
-                        if (!hasCSharpWorkspaceSnapshot
-                            && csharpWorkspaceSnapshots != null
-                            && indexability == FileIndexer.FileProbeStatus.Supported
-                            && detection.Status == FileIndexer.FileProbeStatus.Supported
-                            && detection.Language == "csharp")
-                        {
-                            RecordCSharpWorkspaceDrift(
-                                relPath,
-                                "A C# target appeared after the authoritative workspace target set was captured.");
-                            skipped++;
-                            continue;
-                        }
-                        if (indexability == FileIndexer.FileProbeStatus.Missing || detection.Status == FileIndexer.FileProbeStatus.Missing)
-                        {
-                            var message = $"{relPath}: skipped because it was deleted during indexing.";
-                            warnings++;
-                            warningList.Add(new CliJsonMessage(relPath, message));
-                            if (!options.Json && !options.Quiet)
-                            {
-                                updateProgress.Pause();
-                                ConsoleUi.PrintWarning(message);
-                                updateProgress.Resume();
-                            }
-
-                            using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing during probe");
-                            if (writer.DeleteFileByPath(dbPath))
-                            {
-                                DemoteReadinessOnce();
-                                WriteProjectRootOnce();
-                                RequireTypeScriptAugmentationRefresh();
-                                deleteTxn.Commit();
-                                removed++;
-                                ftsMutated = true;
-                                mutualRecursionRefreshNeeded = true;
-                            }
-                            else
-                            {
-                                skipped++;
-                            }
-                            continue;
-                        }
-
-                        if (indexability == FileIndexer.FileProbeStatus.ProbeFailed || detection.Status == FileIndexer.FileProbeStatus.ProbeFailed)
-                        {
-                            DemoteReadinessOnce();
-
-                            errors++;
-                            errorList.Add(new CliJsonMessage(relPath, "Could not probe file for indexability/language."));
-                            if (fileErrorList.Count < PartialIndexFileErrorLimit)
-                            {
-                                fileErrorList.Add(new StatusIndexFileError
-                                {
-                                    File = FileIndexer.NormalizePathSeparators(relPath),
-                                    Category = "file_read_error",
-                                    Phase = "reading",
-                                    Detail = "Could not probe file for indexability/language.",
-                                });
-                            }
-                            if (!options.Json)
-                            {
-                                updateProgress.Pause();
-                                if (options.Verbose)
-                                    CommandErrorWriter.WriteStderr($"  [ERR ] {relPath}: Could not probe file for indexability/language.");
-                                else
-                                    CommandErrorWriter.WriteStderr($"  [ERR ] {relPath}: Could not probe file for indexability/language.");
-                                updateProgress.Resume();
-                            }
-                            continue;
-                        }
-
-                        if (indexability != FileIndexer.FileProbeStatus.Supported || detection.Status != FileIndexer.FileProbeStatus.Supported)
-                        {
-                            if (!writer.HasFileAtPath(dbPath))
-                            {
-                                using var purgeTxn = writer.BeginTransaction(cancellationToken, "update purge unsupported renamed target");
-                                var purged = PurgeStaleUpdateCleanupPaths(
-                                    dbPath,
-                                    checksum: null,
-                                    includeDirectoryAndStem: persistenceOperations.IsProjectRootWritten());
-                                if (purged > 0)
-                                {
-                                    DemoteReadinessOnce();
-                                    WriteProjectRootOnce();
-                                    RequireTypeScriptAugmentationRefresh();
-                                    purgeTxn.Commit();
-                                    removed += purged;
-                                    ftsMutated = true;
-                                    mutualRecursionRefreshNeeded = true;
-                                    if (options.Verbose && !options.Json && !options.Quiet)
-                                    {
-                                        updateProgress.Pause();
-                                        CommandOutputWriter.WriteLine($"  [DEL ] {relPath} (unsupported renamed target)");
-                                        updateProgress.Resume();
-                                    }
-                                }
-                                else
-                                {
-                                    skipped++;
-                                    if (options.Verbose && !options.Json && !options.Quiet)
-                                    {
-                                        updateProgress.Pause();
-                                        CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unsupported type)");
-                                        updateProgress.Resume();
-                                    }
-                                }
-                                continue;
-                            }
-
-                            DemoteReadinessOnce();
-                            using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete unsupported target");
-                            if (writer.DeleteFileByPath(dbPath))
-                            {
-                                WriteProjectRootOnce();
-                                RequireTypeScriptAugmentationRefresh();
-                                deleteTxn.Commit();
-                                removed++;
-                                ftsMutated = true;
-                                mutualRecursionRefreshNeeded = true;
-                                if (options.Verbose && !options.Json && !options.Quiet)
-                                {
-                                    updateProgress.Pause();
-                                    CommandOutputWriter.WriteLine($"  [DEL ] {relPath} (no longer indexable)");
-                                    updateProgress.Resume();
-                                }
-                            }
-                            else
-                            {
-                                skipped++;
-                                if (options.Verbose && !options.Json)
-                                {
-                                    updateProgress.Pause();
-                                    CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unsupported type)");
-                                    updateProgress.Resume();
-                                }
-                            }
-                            continue;
-                        }
-
-                        if (FileIndexer.TryGetFileIdentity(absPath, out var identity, out var linkCount)
-                            && linkCount > 1
-                            && !visitedFileIdentities.Add(identity))
-                        {
-                            var message = "Skipped hardlinked file because the same file content was already indexed from another path.";
-                            warnings++;
-                            warningList.Add(new CliJsonMessage(relPath, message));
-                            if (!options.Json && !options.Quiet)
-                            {
-                                updateProgress.Pause();
-                                ConsoleUi.PrintWarning($"{relPath}: {message}");
-                                updateProgress.Resume();
-                            }
-
-                            using var deleteTxn = writer.BeginTransaction();
-                            if (writer.DeleteFileByPath(dbPath))
-                            {
-                                DemoteReadinessOnce();
-                                WriteProjectRootOnce();
-                                RequireTypeScriptAugmentationRefresh();
-                                deleteTxn.Commit();
-                                removed++;
-                                ftsMutated = true;
-                                mutualRecursionRefreshNeeded = true;
-                            }
-                            else
-                            {
-                                skipped++;
-                            }
-                            continue;
-                        }
-
-                        var statReusableLanguage = GetStatReusableLanguage(absPath, detection);
-                        var generatedExtractionSuppressed = indexer.IsGeneratedCodeExtractionSuppressed(dbPath);
-                        var statMatchedFile = IndexedFileStatReuse.TryGetReusableUnchangedFile(
-                            writer,
-                            absPath,
-                            dbPath,
-                            statReusableLanguage,
-                            options.MaxFileSizeBytes ?? FileIndexer.DefaultMaxFileSizeBytes,
-                            options.MaxSymbolsPerFile,
-                            options.MaxReferencesPerFile,
-                            generatedExtractionSuppressed,
-                            allowReuse: symbolKindFilterMatchesPrior
-                                && (statReusableLanguage != "csharp" || csharpSymbolNameContractMatchesCurrent)
-                                && (statReusableLanguage != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
-                                && (statReusableLanguage != "sql" || sqlGraphContractMatchesCurrent)
-                                && (statReusableLanguage is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent));
-                        if (statMatchedFile != null)
-                        {
-                            skipped++;
-                            readableFileBytes.Remember(targetIndex, statMatchedFile.Value.Size);
-                            if (options.Verbose && !options.Json && !options.Quiet)
-                            {
-                                updateProgress.Pause();
-                                CommandOutputWriter.WriteLine($"  [SKIP] {relPath} (unchanged)");
-                                updateProgress.Resume();
-                            }
-                            continue;
-                        }
-
-                        knownLanguage = scannedUpdateLanguages == null
-                            ? statReusableLanguage
-                            : FileIndexer.GetReusableDetectedLanguage(absPath, scannedUpdateLanguages);
-
-                        currentUpdatePhase = "reading";
-                        UpdateFileContentLoadForTesting?.Invoke(relPath);
-                        var loaded = indexer.BuildLoadedRecordWithRawBytes(
-                            absPath,
-                            relPath,
-                            knownLanguage,
-                            cancellationToken);
-                        var record = loaded.Record;
-                        if (hasCSharpWorkspaceSnapshot
-                            && (record.Lang != "csharp"
-                                || !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
-                                    absPath,
-                                    dbPath,
-                                    relPath,
-                                    record.Size,
-                                    record.Modified,
-                                    csharpWorkspaceSnapshots!,
-                                    out _,
-                                    cancellationToken)))
-                        {
-                            RecordCSharpWorkspaceDrift(
-                                relPath,
-                                "The C# file changed while the authoritative update pass was reading it.");
-                            skipped++;
-                            continue;
-                        }
-                        readableFileBytes.Remember(targetIndex, record.Size);
-                        var warning = loaded.Warning;
-                        var generatedSuppressionIssue = generatedExtractionSuppressed
-                            ? indexer.BuildGeneratedCodeExtractionSkippedIssue(record.Path)
-                            : null;
-
-                        if (warning != null && !options.Json && !options.Quiet)
-                        {
-                            updateProgress.Pause();
-                            ConsoleUi.PrintWarning(warning);
-                            updateProgress.Resume();
-                        }
-
-                        var existingId = writer.GetReusableUnchangedFileId(
-                            record.Path,
-                            record.Modified,
-                            record.Checksum,
-                            size: record.Size,
-                            lines: record.Lines,
-                            language: record.Lang,
-                            generated: record.Generated,
-                            maxSymbolsPerFile: options.MaxSymbolsPerFile,
-                            maxReferencesPerFile: options.MaxReferencesPerFile,
-                            generatedExtractionSuppressed: generatedExtractionSuppressed,
-                            allowReuse: symbolKindFilterMatchesPrior
-                                && (record.Lang != "csharp" || csharpSymbolNameContractMatchesCurrent)
-                                && (record.Lang != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
-                                && (record.Lang != "sql" || sqlGraphContractMatchesCurrent)
-                                && (record.Lang is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent));
-                        if (existingId != null)
-                        {
-                            using var purgeTxn = writer.BeginTransaction(cancellationToken, "update purge unchanged stale paths");
-                            var purged = PurgeStaleUpdateCleanupPaths(
-                                record.Path,
-                                record.Checksum,
-                                includeDirectoryAndStem: persistenceOperations.IsProjectRootWritten());
-                            if (purged > 0)
-                            {
-                                DemoteReadinessOnce();
-                                WriteProjectRootOnce();
-                                RequireTypeScriptAugmentationRefresh();
-                                purgeTxn.Commit();
-                                removed += purged;
-                                ftsMutated = true;
-                                mutualRecursionRefreshNeeded = true;
-                            }
-                            skipped++;
-                            if (options.Verbose && !options.Json && !options.Quiet)
-                            {
-                                updateProgress.Pause();
-                                CommandOutputWriter.WriteLine(purged > 0
-                                    ? $"  [SKIP] {relPath} (unchanged; purged {purged:N0} stale renamed path(s))"
-                                    : $"  [SKIP] {relPath} (unchanged)");
-                                updateProgress.Resume();
-                            }
-                            continue;
-                        }
-
-                        DemoteReadinessOnce();
-                        if (record.Lang == "csharp")
-                            csharpMetadataTargetsNeedRefresh = true;
-                        var persistence = PersistUpdateFile(new UpdateFilePersistenceContext
-                        {
-                            Writer = writer,
-                            Indexer = indexer,
-                            Options = options,
-                            ProjectRoot = projectRoot,
-                            RelativePath = relPath,
-                            AbsolutePath = absPath,
-                            Record = record,
-                            Loaded = loaded,
-                            GeneratedSuppressionIssue = generatedSuppressionIssue,
-                            CSharpWorkspace = csharpWorkspace,
-                            PostExtractionHooks = postExtractionHooks.Value,
-                            SymbolExtractionWorker = symbolExtractionWorker.Value,
-                            ProjectRootWritten = persistenceOperations.IsProjectRootWritten(),
-                            CancellationToken = cancellationToken,
-                            RequireTypeScriptAugmentationRefresh = RequireTypeScriptAugmentationRefresh,
-                            PurgeStaleUpdateCleanupPaths = PurgeStaleUpdateCleanupPaths,
-                            WriteProjectRootOnce = WriteProjectRootOnce,
-                            RecordDynamicGraphFileRefresh = RecordDynamicGraphFileRefresh,
-                            SetBatchMarkerOwned = owned => fileBatchMarked = owned,
-                            SetPhase = (path, phase) =>
-                            {
-                                currentUpdatePath = path;
-                                currentUpdatePhase = phase;
-                            },
-                        });
-                        symbolsDroppedByKindFilter += persistence.SymbolsDroppedByKindFilter;
-                        mutualRecursionRefreshNeeded |= persistence.MutualRecursionRefreshNeeded;
-                        updated++;
-                        ftsMutated = true;
-                        UpdateFileCommittedForTesting?.Invoke(updated + removed, targetPaths.Count);
-                        ThrowIfUpdateCancelled();
-                        updateProgress.WriteVerbose(persistence.VerboseMessage);
-                    }
-                    catch (IndexExtractionStalledException)
-                    {
-                        throw;
-                    }
-                    catch (Exception ex)
-                    {
-                        if (ex is CSharpWorkspaceChangedException)
-                        {
-                            if (fileBatchMarked)
-                                writer.ClearBatchInProgress();
-                            RecordCSharpWorkspaceDrift(relPath, ex.Message);
-                            skipped++;
-                            continue;
-                        }
-
-                        if (ex is FileIndexer.BinaryFileSkippedException
-                            or FileIndexer.FileTooLargeSkippedException)
-                        {
-                            if (fileBatchMarked)
-                                writer.ClearBatchInProgress();
-
-                            var skippedFile = HandleSkippedUpdateFile(
-                                new SkippedUpdateFileHandlingContext
-                                {
-                                    Writer = writer,
-                                    Indexer = indexer,
-                                    Options = options,
-                                    AbsolutePath = absPath,
-                                    RelativePath = relPath,
-                                    IndexPath = dbPath,
-                                    KnownLanguage = knownLanguage,
-                                    ProjectRootWritten = persistenceOperations.IsProjectRootWritten(),
-                                    TargetIndex = targetIndex,
-                                    ReadableFileBytes = readableFileBytes,
-                                    HasCSharpWorkspaceSnapshot =
-                                        hasCSharpWorkspaceSnapshot,
-                                    CSharpWorkspaceSnapshot =
-                                        csharpWorkspaceSnapshot,
-                                    CSharpWorkspaceSnapshots =
-                                        csharpWorkspaceSnapshots,
-                                    WarningList = warningList,
-                                    UpdateProgress = updateProgress,
-                                    CancellationToken = cancellationToken,
-                                    DemoteReadinessOnce = DemoteReadinessOnce,
-                                    SetCurrentUpdatePhase =
-                                        phase => currentUpdatePhase = phase,
-                                    RecordCSharpWorkspaceDrift =
-                                        RecordCSharpWorkspaceDrift,
-                                    RecordUpdateFileFailure =
-                                        RecordUpdateFileFailure,
-                                    PurgeStaleUpdateCleanupPaths =
-                                        PurgeStaleUpdateCleanupPaths,
-                                    RequireTypeScriptAugmentationRefresh =
-                                        RequireTypeScriptAugmentationRefresh,
-                                    WriteProjectRootOnce = WriteProjectRootOnce,
-                                    RecordDynamicGraphFileRefresh =
-                                        RecordDynamicGraphFileRefresh,
-                                },
-                                ex);
-                            updated += skippedFile.Updated;
-                            skipped += skippedFile.Skipped;
-                            warnings += skippedFile.Warnings;
-                            mutualRecursionRefreshNeeded |=
-                                skippedFile.MutualRecursionRefreshNeeded;
-                            if (skippedFile.Updated > 0)
-                            {
-                                ftsMutated = true;
-                            }
-                            continue;
-                        }
-
-                        if (ex is FileNotFoundException or DirectoryNotFoundException)
-                        {
-                            if (fileBatchMarked)
-                                writer.ClearBatchInProgress();
-
-                            if (hasCSharpWorkspaceSnapshot)
-                            {
-                                RecordCSharpWorkspaceDrift(
-                                    relPath,
-                                    "The C# file disappeared during its authoritative update pass.");
-                                skipped++;
-                                continue;
-                            }
-
-                            var message = $"{relPath}: skipped because it was deleted during indexing.";
-                            warnings++;
-                            warningList.Add(new CliJsonMessage(relPath, message));
-                            if (!options.Json && !options.Quiet)
-                            {
-                                updateProgress.Pause();
-                                ConsoleUi.PrintWarning(message);
-                                updateProgress.Resume();
-                            }
-
-                            if (writer.HasFileAtPath(dbPath))
-                            {
-                                DemoteReadinessOnce();
-                                using var deleteTxn = writer.BeginTransaction(cancellationToken, "update delete missing during write");
-                                if (writer.DeleteFileByPath(dbPath))
-                                {
-                                    WriteProjectRootOnce();
-                                    RequireTypeScriptAugmentationRefresh();
-                                    deleteTxn.Commit();
-                                    removed++;
-                                    ftsMutated = true;
-                                    mutualRecursionRefreshNeeded = true;
-                                }
-                            }
-                            else
-                            {
-                                skipped++;
-                            }
-                            continue;
-                        }
-
-                        if (fileBatchMarked)
-                            writer.ClearBatchInProgress();
-                        RecordUpdateFileFailure(relPath, currentUpdatePhase, ex);
-                    }
+                    ConsumeSerialUpdateTarget(
+                        updateTargets[targetIndex],
+                        targetIndex,
+                        symbolExtractionWorker);
                 }
             }
             finally
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.Update.FilePersistence.cs b/src/CodeIndex/Cli/IndexCommandRunner.Update.FilePersistence.cs
index 143e3d91a..4af45d87b 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.Update.FilePersistence.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.Update.FilePersistence.cs
@@ -8,29 +8,6 @@ namespace CodeIndex.Cli;
 
 public static partial class IndexCommandRunner
 {
-    private sealed class UpdateFilePersistenceContext
-    {
-        internal required DbWriter Writer { get; init; }
-        internal required FileIndexer Indexer { get; init; }
-        internal required IndexCommandOptions Options { get; init; }
-        internal required string ProjectRoot { get; init; }
-        internal required string RelativePath { get; init; }
-        internal required string AbsolutePath { get; init; }
-        internal required FileRecord Record { get; init; }
-        internal required LoadedFileRecord Loaded { get; init; }
-        internal FileIssue? GeneratedSuppressionIssue { get; init; }
-        internal required CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace { get; init; }
-        internal required PostExtractionHookRunner PostExtractionHooks { get; init; }
-        internal required SymbolExtractionWorkerClient SymbolExtractionWorker { get; init; }
-        internal required bool ProjectRootWritten { get; init; }
-        internal required CancellationToken CancellationToken { get; init; }
-        internal required Action RequireTypeScriptAugmentationRefresh { get; init; }
-        internal required Func<string, string?, bool, int> PurgeStaleUpdateCleanupPaths { get; init; }
-        internal required Action WriteProjectRootOnce { get; init; }
-        internal required Action<string?> RecordDynamicGraphFileRefresh { get; init; }
-        internal required Action<bool> SetBatchMarkerOwned { get; init; }
-        internal required Action<string, string> SetPhase { get; init; }
-    }
 
     private sealed record UpdateFilePersistenceResult(
         int SymbolsDroppedByKindFilter,
@@ -62,252 +39,6 @@ private sealed class SkippedUpdateFilePersistenceContext
     private sealed record SkippedUpdateFilePersistenceResult(
         bool MutualRecursionRefreshNeeded);
 
-    private static UpdateFilePersistenceResult PersistUpdateFile(
-        UpdateFilePersistenceContext context)
-    {
-        var writer = context.Writer;
-        var options = context.Options;
-        var record = context.Record;
-        var loaded = context.Loaded;
-        var cancellationToken = context.CancellationToken;
-        var mutualRecursionRefreshNeeded = false;
-        var symbolsDroppedByKindFilter = 0;
-
-        writer.MarkBatchInProgress();
-        context.SetBatchMarkerOwned(true);
-        var recordRequiresTypeScriptAugmentationRefresh = record.Lang == "typescript";
-        using var txn = writer.BeginTransaction(cancellationToken, "update file");
-        if (recordRequiresTypeScriptAugmentationRefresh)
-            context.RequireTypeScriptAugmentationRefresh();
-        var stalePurged = context.PurgeStaleUpdateCleanupPaths(
-            record.Path,
-            record.Checksum,
-            context.ProjectRootWritten);
-        if (stalePurged > 0)
-        {
-            context.RequireTypeScriptAugmentationRefresh();
-            if (!options.SymbolsOnly)
-                mutualRecursionRefreshNeeded = true;
-        }
-        context.WriteProjectRootOnce();
-        var fileId = writer.UpsertFile(record, out var referenceIdentityChanged);
-        if (!options.SymbolsOnly && referenceIdentityChanged)
-            mutualRecursionRefreshNeeded = true;
-        context.SetPhase(FormatIndexPhasePath(context.RelativePath, "chunking"), "chunking");
-        var chunks = ChunkSplitter.SplitNormalized(
-            fileId,
-            loaded.Content,
-            loaded.Facts);
-        if (context.GeneratedSuppressionIssue != null)
-        {
-            writer.InsertChunks(chunks, cancellationToken);
-            writer.InsertSymbols([], cancellationToken);
-            writer.InsertReferencesInAtomicFileScope(
-                [],
-                refreshMutualRecursionFlags: false,
-                cancellationToken);
-            context.SetPhase(
-                FormatIndexPhasePath(context.RelativePath, "validating"),
-                "validating");
-            var generatedIssues = AppendIssueIfMissing(
-                FileIndexer.ValidateContent(
-                    record.Path,
-                    loaded.RawBytes,
-                    loaded.Content,
-                    record.Lang,
-                    loaded.Inspection,
-                    loaded.Facts),
-                context.GeneratedSuppressionIssue);
-            writer.InsertIssues(fileId, generatedIssues);
-            context.SetPhase(
-                FormatIndexPhasePath(context.RelativePath, "committing"),
-                "committing");
-            writer.ClearBatchInProgress();
-            txn.Commit();
-            context.SetBatchMarkerOwned(false);
-            context.RecordDynamicGraphFileRefresh(record.Lang);
-            return new UpdateFilePersistenceResult(
-                0,
-                mutualRecursionRefreshNeeded,
-                $"  [OK  ] {context.RelativePath} ({chunks.Count} chunks, generated-code extraction skipped)");
-        }
-
-        context.SetPhase(FormatIndexPhasePath(context.RelativePath, "symbols"), "symbols");
-        var symbolExtraction = ExtractSymbolsWithStallTimeout(
-            fileId,
-            record.Lang,
-            loaded.Content,
-            context.AbsolutePath,
-            context.ProjectRoot,
-            record.Path,
-            FormatIndexPhasePath(context.RelativePath, "symbols"),
-            true,
-            loaded.HasOversizeLine,
-            loaded.ConflictMarkerLine,
-            context.SymbolExtractionWorker,
-            cancellationToken);
-        var symbols = symbolExtraction.Symbols;
-        var symbolRegexTimeoutIssue = symbolExtraction.RegexTimeoutIssue;
-        var fileContext = new FileContext(
-            context.ProjectRoot,
-            record.Path,
-            context.AbsolutePath,
-            record.Lang);
-        var sourceContractSeenBeforeObservation =
-            context.PostExtractionHooks.SawCSharpStaticInterfaceSourceContract;
-        context.PostExtractionHooks.ObserveCSharpStaticInterfaceSourceSymbols(
-            fileContext,
-            symbols);
-        if (record.Lang == "csharp"
-            && !context.CSharpWorkspace.HasSourceStaticInterfaceContracts
-            && !sourceContractSeenBeforeObservation
-            && context.PostExtractionHooks.SawCSharpStaticInterfaceSourceContract)
-        {
-            writer.SetCSharpStaticInterfaceSourceEvidence(null);
-            throw new CSharpWorkspaceChangedException(
-                "A C# static-interface contract appeared after workspace preflight.");
-        }
-        if (symbols.Count > options.MaxSymbolsPerFile)
-        {
-            var issue = BuildSymbolCountExceededIssue(
-                record.Path,
-                symbols.Count,
-                options.MaxSymbolsPerFile);
-            IReadOnlyList<FileIssue> capIssues = symbolRegexTimeoutIssue == null
-                ? [issue]
-                : AppendIssue([symbolRegexTimeoutIssue], issue);
-            writer.InsertSymbols([], cancellationToken);
-            writer.InsertReferencesInAtomicFileScope(
-                [],
-                refreshMutualRecursionFlags: false,
-                cancellationToken);
-            writer.InsertIssues(fileId, capIssues);
-            writer.ClearBatchInProgress();
-            txn.Commit();
-            context.SetBatchMarkerOwned(false);
-            context.RecordDynamicGraphFileRefresh(record.Lang);
-            return new UpdateFilePersistenceResult(
-                0,
-                mutualRecursionRefreshNeeded,
-                $"  [SKIP] {context.RelativePath} ({issue.Message})");
-        }
-
-        var familyScopeKey = context.Indexer.GetFamilyScopeKey(context.AbsolutePath, record.Lang);
-        SymbolExtractor.ApplyFamilyScope(symbols, familyScopeKey, record.Lang);
-        context.PostExtractionHooks.OnSymbolsExtractedAfterSourceObservation(
-            fileContext,
-            symbols,
-            loaded.Content,
-            familyScopeKey);
-        symbolsDroppedByKindFilter = options.SymbolKindFilter.Apply(symbols);
-        if (symbols.Count > options.MaxSymbolsPerFile)
-        {
-            var issue = BuildSymbolCountExceededIssue(
-                record.Path,
-                symbols.Count,
-                options.MaxSymbolsPerFile);
-            IReadOnlyList<FileIssue> capIssues = symbolRegexTimeoutIssue == null
-                ? [issue]
-                : AppendIssue([symbolRegexTimeoutIssue], issue);
-            writer.InsertSymbols([], cancellationToken);
-            writer.InsertReferencesInAtomicFileScope(
-                [],
-                refreshMutualRecursionFlags: false,
-                cancellationToken);
-            writer.InsertIssues(fileId, capIssues);
-            writer.ClearBatchInProgress();
-            txn.Commit();
-            context.SetBatchMarkerOwned(false);
-            context.RecordDynamicGraphFileRefresh(record.Lang);
-            return new UpdateFilePersistenceResult(
-                symbolsDroppedByKindFilter,
-                mutualRecursionRefreshNeeded,
-                $"  [SKIP] {context.RelativePath} ({issue.Message})");
-        }
-
-        writer.InsertChunks(chunks, cancellationToken);
-        FileIndexer.ValidateSymbolLineRanges(record, symbols);
-        writer.InsertSymbols(symbols, cancellationToken);
-        context.SetPhase(
-            FormatIndexPhasePath(context.RelativePath, "references"),
-            "references");
-        List<ReferenceRecord> references;
-        FileIssue? referenceRegexTimeoutIssue;
-        ReferenceExtractionResult referenceExtraction;
-        using (var regexTimeouts = BoundedRegex.CaptureTimeouts(
-                   record.Lang,
-                   "reference_extraction"))
-        {
-            referenceExtraction = ReferenceExtractor.ExtractDetailedNormalized(
-                fileId,
-                record.Lang,
-                loaded.Content,
-                loaded.HasOversizeLine,
-                symbols,
-                record.Path,
-                record.Lang == "csharp" ? context.CSharpWorkspace.Symbols : null,
-                cancellationToken,
-                maxReferenceCount: options.MaxReferencesPerFile + 1,
-                conflictMarkerLine: loaded.ConflictMarkerLine,
-                workspaceRoot: context.ProjectRoot,
-                csharpStaticInterfaceMemberLookups:
-                    context.CSharpWorkspace.StaticInterfaceMemberLookups,
-                csharpQualifiedPatternLookups:
-                    context.CSharpWorkspace.QualifiedPatternLookups);
-            references = referenceExtraction.References;
-            referenceRegexTimeoutIssue =
-                BuildRegexTimeoutIssue(record.Path, regexTimeouts);
-        }
-        context.PostExtractionHooks.OnReferencesExtracted(fileContext, references);
-        FileIssue? referenceCapIssue = null;
-        if (references.Count > options.MaxReferencesPerFile)
-        {
-            referenceCapIssue = BuildReferenceCountExceededIssue(
-                record.Path,
-                references.Count,
-                options.MaxReferencesPerFile);
-            references = [];
-        }
-        writer.InsertReferencesInAtomicFileScope(
-            references,
-            refreshMutualRecursionFlags: false,
-            cancellationToken);
-        context.SetPhase(
-            FormatIndexPhasePath(context.RelativePath, "validating"),
-            "validating");
-        IReadOnlyList<FileIssue> issues = FileIndexer.ValidateContent(
-            record.Path,
-            loaded.RawBytes,
-            loaded.Content,
-            record.Lang,
-            loaded.Inspection,
-            loaded.Facts);
-        if (symbolRegexTimeoutIssue != null)
-            issues = AppendIssue(issues, symbolRegexTimeoutIssue);
-        if (referenceRegexTimeoutIssue != null)
-            issues = AppendIssue(issues, referenceRegexTimeoutIssue);
-        issues = AppendReferenceExtractionDiagnosticIssues(
-            issues,
-            record.Path,
-            referenceExtraction.Diagnostics);
-        if (referenceCapIssue != null)
-            issues = AppendIssue(issues, referenceCapIssue);
-        writer.InsertIssues(fileId, issues);
-        context.SetPhase(
-            FormatIndexPhasePath(context.RelativePath, "committing"),
-            "committing");
-        writer.ClearBatchInProgress();
-        txn.Commit();
-        context.SetBatchMarkerOwned(false);
-        context.RecordDynamicGraphFileRefresh(record.Lang);
-        if (!options.SymbolsOnly && (symbols.Count > 0 || references.Count > 0))
-            mutualRecursionRefreshNeeded = true;
-
-        return new UpdateFilePersistenceResult(
-            symbolsDroppedByKindFilter,
-            mutualRecursionRefreshNeeded,
-            $"  [OK  ] {context.RelativePath} ({chunks.Count} chunks, {symbols.Count} symbols, {references.Count} refs)");
-    }
 
     private static SkippedUpdateFilePersistenceResult PersistSkippedUpdateFile(
         SkippedUpdateFilePersistenceContext context)
diff --git a/tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs b/tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs
index e400100dc..af1763045 100644
--- a/tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs
+++ b/tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs
@@ -2329,7 +2329,7 @@ public void Run_UpdateFiles_AuthoritativeCSharpParallelPersistenceMatchesSerialP
         {
             generatedPatterns.Set(
                 IndexCommandRunner.GeneratedCodePatternsEnvironmentVariable,
-                scenario == "generated" ? "Source02.cs" : null);
+                scenario == "generated" ? "Source00.cs" : null);
             CreateAuthoritativeParallelUpdateProject(serialRoot, implementationCount: 3);
             CreateAuthoritativeParallelUpdateProject(parallelRoot, implementationCount: 3);
             var initialModifiedUtc = DateTime.UtcNow.AddSeconds(-4);
@@ -2410,6 +2410,13 @@ public void Run_UpdateFiles_AuthoritativeCSharpParallelPersistenceMatchesSerialP
                     payload => payload.Path == "IParseable.cs"
                         && payload.HasSourceContract);
             }
+            else if (scenario == "generated")
+            {
+                Assert.Contains(
+                    completedPayloads,
+                    payload => payload.Path == "Source00.cs"
+                        && payload.RetainedSymbols == 0);
+            }
             foreach (var property in new[]
                      {
                          "updated",
@@ -2428,6 +2435,45 @@ public void Run_UpdateFiles_AuthoritativeCSharpParallelPersistenceMatchesSerialP
             var parallelProjection = ReadStableUpdateProjection(
                 Path.Combine(parallelRoot, ".cdidx", "codeindex.db"));
             Assert.Equal(serialProjection, parallelProjection);
+            if (scenario == "generated")
+            {
+                foreach (var json in new[] { serialJson, parallelJson })
+                {
+                    var summary = json.GetProperty("summary");
+                    Assert.Equal(4, summary.GetProperty("updated").GetInt32());
+                    Assert.Equal(0, summary.GetProperty("skipped").GetInt32());
+                    Assert.Equal(0, summary.GetProperty("errors").GetInt32());
+                }
+                var issuePrefix = $"issues:Source00.cs\u001f{FileIndexer.GeneratedCodeExtractionSkippedIssueKind}\u001f";
+                Assert.Contains(
+                    serialProjection,
+                    item => item.StartsWith(issuePrefix, StringComparison.Ordinal));
+                Assert.Contains(
+                    parallelProjection,
+                    item => item.StartsWith(issuePrefix, StringComparison.Ordinal));
+            }
+            else if (scenario == "oversize")
+            {
+                foreach (var json in new[] { serialJson, parallelJson })
+                {
+                    var summary = json.GetProperty("summary");
+                    Assert.Equal(4, summary.GetProperty("updated").GetInt32());
+                    Assert.Equal(0, summary.GetProperty("skipped").GetInt32());
+                    Assert.Equal(0, summary.GetProperty("errors").GetInt32());
+                    Assert.False(json.GetProperty("index_complete").GetBoolean());
+                    AssertCompletenessReason(
+                        json,
+                        "index_incomplete_reasons",
+                        "file_too_large");
+                }
+                const string issuePrefix = "issues:Source02.cs\u001ffile_too_large\u001f";
+                Assert.Contains(
+                    serialProjection,
+                    item => item.StartsWith(issuePrefix, StringComparison.Ordinal));
+                Assert.Contains(
+                    parallelProjection,
+                    item => item.StartsWith(issuePrefix, StringComparison.Ordinal));
+            }
             var (serialStatusExitCode, serialStatus) = RunStatusAndCaptureJson(
                 [
                     "--db",
@@ -2442,6 +2488,8 @@ public void Run_UpdateFiles_AuthoritativeCSharpParallelPersistenceMatchesSerialP
                 ]);
             Assert.Equal(CommandExitCodes.Success, serialStatusExitCode);
             Assert.Equal(serialStatusExitCode, parallelStatusExitCode);
+            Assert.False(serialStatus.GetProperty("migration_in_progress").GetBoolean());
+            Assert.False(parallelStatus.GetProperty("migration_in_progress").GetBoolean());
             foreach (var property in new[]
                      {
                          "graph_table_available",
@@ -2475,6 +2523,8 @@ string[] BuildArgs(string root, string parallelism)
                     "--parallelism",
                     parallelism,
                 };
+                if (scenario == "oversize")
+                    args.Insert(4, "Source02.cs");
                 switch (scenario)
                 {
                     case "symbol_cap":

From 688a9df7ea6d57e73621344a29252eb988accf63 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 15:28:15 +0900
Subject: [PATCH 41/45] Consolidate full-scan pre-write preparation

---
 TESTING_GUIDE.md                              |   2 +
 .../IndexCommandRunner.FileByteTracking.cs    | 165 +++--
 ...Runner.FullScan.CSharpFinalRevalidation.cs | 366 ++++------
 ...xCommandRunner.FullScan.CSharpPreflight.cs | 641 +++++++++--------
 ...xCommandRunner.FullScan.PreWriteSession.cs | 120 ++++
 ...mmandRunner.FullScan.PreWriteValidation.cs | 130 ++++
 ...xCommandRunner.FullScan.TargetSelection.cs | 664 +++++++++---------
 .../Cli/IndexCommandRunner.FullScan.cs        | 621 +++++-----------
 .../IndexCommandRunnerFullScanTests.cs        |  26 +-
 9 files changed, 1336 insertions(+), 1399 deletions(-)
 create mode 100644 src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteSession.cs
 create mode 100644 src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteValidation.cs

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 46a2b626f..8de585c3f 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -35,6 +35,7 @@ Use the full suite by default. Use targeted filters only while iterating locally
 - FTS optimization recommendation coverage keeps the shared evaluator exact at one write below, at, and one write above the 25-write threshold. Status, explain, optimize dry-run, optimize execution, and vacuum maintenance guidance must expose the same `recommended`, `action`, `reason`, `threshold_writes`, `observed_writes`, and `state`; stale batches, known WAL-stale snapshots, forward-incompatible schema stamps, and unavailable legacy counters/page snapshots suppress the recommendation, query-only status performs no source writes, and execution uses the focused counter/page/forward-contract/freshness snapshot instead of full status scans. A hot-WAL fixture opened through an explicit `immutable=1` URI must prove that status, standalone optimize dry-run, and the `index --optimize` dry-run alias preserve the same stale recommendation. A WAL or freelist state of `unknown` cannot select the optimize command, and a successful optimize reports the reset counter afterward.
 - Rebuild reclaim coverage creates a real high-freelist incremental-auto-vacuum database, runs CLI rebuild with a concurrently open reader, and verifies row integrity, before/after logical database-size reduction, ratio reduction below the shared threshold, reclaimed pages/bytes, immediate JSON, persisted `last_index_run.rebuild_reclaim`, and truthful explicit-vacuum metrics. Keep focused cases for below-threshold no-op, injected reclaim failure after commit, and interrupted rebuild recovery; a maintenance failure must preserve a usable committed database and stable bounded telemetry.
 - Full-scan CLI and MCP no-op coverage treats one repository-wide reusable-stat snapshot read and one folded-readiness verification as performance contracts. Keep assertions for one snapshot read, one stat lookup per candidate, one folded verification, and no content load for unchanged files when changing incremental indexing.
+- Full-scan pre-write boundary coverage pins the phase order to `before_write`, write start, then `before_readiness`. The first-barrier drift theory must cover both incremental and rebuild requests and preserve readiness, indexed rows, C# source evidence, FTS recovery, and incomplete-batch markers. Keep C# preflight, target selection, dirty-byte FTS choice, final C# stat revalidation, scan-input validation, and loaded-workspace file-stat validation on the same reference-owned preparation state; no database repair or outer bulk-write/transaction guard may begin before those validations succeed.
 - Reference-graph refresh coverage treats graph-neutral indexing as a performance contract across incremental full scan, scoped `--files` update, and MCP indexing. Keep zero-refresh assertions for new and modified source files without symbols/references, plus a single batched refresh assertion when existing or new graph identity rows change. A healthy incremental generation must restrict identity/candidate/recursion work to transaction-committed dirty files, old and new `(language, folded name)` dependencies, and their old/new reciprocal edges; retain C#/Python language-transition and unchanged-target parity with a subsequent full refresh, rolled-back file batches, cancellation/retry, orphan-candidate cleanup, and the controlled 4,100-of-4,100 broad-scope fallback. Fresh/rebuild runs, missing identity contracts, and dirty sets of at least 4,096 references covering at least 50% of the graph must keep the full-refresh path. Query-plan coverage must keep all four scoped update phases and all ten candidate inserts on dirty-table-driven reference primary-key seeks, keep C# instantiate grouping on lookup names plus `idx_symbols_name_folded`, and prove that a sub-4,096 dirty set does not count the whole reference table without an explicit diagnostic hook.
 - Index-generation completeness coverage uses a table-driven full, symbols-only, max-file-byte, max-symbol, and max-reference matrix, with extractor failure kept separate because it uses a mutable hook. Assert that index-command JSON, immediate status, and workspace health expose identical index/graph booleans and reason arrays where available; MCP cap coverage must match the persisted status snapshot as well. Remove the additive completeness metadata in healthy and capped fixtures to preserve legacy fallback coverage, and clear issue readiness before a scoped capped update to prove current omission evidence survives degraded prior metadata. Lowering or raising the file-size policy must reprocess unchanged files in CLI and MCP indexing so a prior `file_too_large` issue cannot be reused. Structured remediation must distinguish symbols-only / missing-graph causes from reference safety caps and must not label an incomplete index as fold-only. Human output must identify incomplete generations instead of printing a complete summary.
 - Reference-identity refresh coverage treats a stable graph rebuild as a physical-write performance contract. Keep NULL-safe changed-row predicates for source identity, the four-column target-resolution tuple, self-reference, and mutual-recursion updates; trigger audits must remain at zero on a stable rerun, repair each corrupted phase once, and prove a later-phase failure rolls back earlier identity writes. SQLite `changes()` must continue to report the final mutual-recursion phase.
@@ -1098,6 +1099,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
 - FTS optimization recommendation coverage は、25 write threshold の1つ下、ちょうど、1つ上で shared evaluator の境界を固定します。status、explain、optimize dry-run、optimize execution、vacuum maintenance guidance は同じ `recommended`、`action`、`reason`、`threshold_writes`、`observed_writes`、`state` を公開し、stale batch、既知の WAL-stale snapshot、forward-incompatible な schema stamp、利用できない legacy counter / page snapshot は recommendation を抑止します。query-only status は source に書き込まず、execution は full status scan ではなく counter / page / forward-contract / freshness に限定した snapshot を使います。hot WAL fixture を明示的な `immutable=1` URI で開き、status、standalone optimize dry-run、`index --optimize` dry-run alias が同じ stale recommendation を保持することも証明します。WAL または freelist の state が `unknown` の場合は optimize command を選択せず、成功した optimize は reset 後の counter を返す必要があります。
 - rebuild reclaim coverage は、実際に high-freelist となった incremental-auto-vacuum database を作成し、reader connection を開いたまま CLI rebuild を実行して、row integrity、before / after の logical database size 縮小、共通 threshold 未満への ratio 低下、回収 page / byte、即時 JSON、保存された `last_index_run.rebuild_reclaim`、明示的 vacuum の正確な metrics を検証します。below-threshold no-op、commit 後の reclaim failure 注入、interrupted rebuild recovery の focused case も維持してください。maintenance failure が発生しても利用可能な commit 済み database と stable で上限付きの telemetry を保持する必要があります。
 - full-scan CLI と MCP の no-op coverage は、リポジトリ全体の reusable-stat snapshot read と folded-readiness verification がそれぞれ 1 回であることを performance contract とします。incremental indexing を変更するときは、snapshot read が 1 回、候補ごとの stat lookup が 1 回、folded verification が 1 回、unchanged file の content load が 0 回という assertion を維持してください。
+- full-scan の write 前境界 coverage は、phase 順序を `before_write`、write 開始、`before_readiness` に固定します。最初の barrier で drift する theory は incremental / rebuild の両方を対象にし、readiness、indexed row、C# source evidence、FTS recovery、incomplete-batch marker を保持してください。C# preflight、target selection、dirty-byte FTS 判定、最終 C# stat 再検証、scan-input 検証、読み込み済み workspace の file-stat 検証は、同じ reference-owned preparation state 上で実行します。これらが成功する前に database repair や outer bulk-write / transaction guard を開始してはいけません。
 - reference-graph refresh coverage は、incremental full scan、scoped `--files` update、MCP indexing を横断する graph-neutral indexing を performance contract とします。symbol/reference を持たない新規・変更 source file では refresh 0 回を維持し、既存または新規の graph identity 行が変化する場合は batch 全体で refresh 1 回を assertion してください。健全な incremental generation では identity / candidate / recursion 処理を transaction commit 済みの dirty file、旧・新の `(language, folded name)` 依存、旧・新の逆辺に限定します。C# / Python の言語遷移、未変更targetを参照する新規callerと後続full refreshのparity、rollback file batch、cancel後retry、孤立candidate cleanup、4,100件中4,100件をdirtyにする制御broad-scope fallbackを維持してください。fresh/rebuild、identity契約欠落、または4,096件以上かつgraphの50%以上を占めるdirty集合ではfull-refresh経路を維持します。query-plan coverageでは、scoped updateの4 phaseとcandidate INSERT 10本をdirty table起点のreference主キーseekに保ち、C# instantiate groupingをlookup nameと`idx_symbols_name_folded`起点にし、明示的なdiagnostic hookがない4,096件未満のdirty集合ではreference table全件COUNTを行わないことを検証してください。
 - index generation の completeness coverage は full、symbols-only、max-file-byte、max-symbol、max-reference を table-driven matrix で検証し、mutable hook を使う extractor failure は別 case に保ちます。index command JSON、直後の status、workspace health で、利用可能な index/graph の boolean と reason array が完全に一致すること、MCP の cap case も persisted status snapshot と一致することを assertion してください。healthy / capped fixture から additive completeness metadata を削除して legacy fallback coverage を維持し、scoped capped update の前に issue readiness を clear して、prior metadata が degraded でも今回の omission evidence が失われないことを検証します。file-size policy を下げた場合も上げた場合も、CLI / MCP indexing は unchanged file を再処理し、以前の `file_too_large` issue を再利用してはいけません。structured remediation は symbols-only / missing-graph 原因と reference safety cap を区別し、incomplete index を fold-only と表示しない必要があります。human output は complete summary ではなく incomplete generation を明示する必要があります。
 - reference identity refresh coverage は、安定graphの再構築を物理writeのperformance contractとします。source identity、target resolutionの4列tuple、self reference、mutual recursionの更新にはNULL-safeなchanged-row predicateを維持し、安定rerunのtrigger auditは0、各corrupt phaseのrepairは1回、後段phaseの失敗で先行identity writeもrollbackされることを検証してください。SQLite `changes()` は引き続き最後のmutual-recursion phaseを表します。
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FileByteTracking.cs b/src/CodeIndex/Cli/IndexCommandRunner.FileByteTracking.cs
index 6f3288834..8ed6eb069 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FileByteTracking.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FileByteTracking.cs
@@ -93,94 +93,113 @@ or NotSupportedException
         }
     }
 
-    private static bool ShouldUseFullScanFtsBulkLoad(
-        bool rebuild,
-        bool startedWithNoIndexedFiles,
-        int extractionWorkItemCount,
-        FilePurgePlan staleFilePurgePlan,
-        bool scanHadErrors,
-        ReadableFileByteTracker readableFileBytes,
-        ReusableIndexedFileStatsSnapshot reusableIndexedFileStats,
-        IReadOnlyList<FullScanFileTarget> fileTargets,
-        IReadOnlyList<int>? extractionFileIndexes,
-        Action throwIfCancelled)
+    private sealed partial class FullScanPreWriteSession
     {
-        if (rebuild || startedWithNoIndexedFiles)
-            return true;
-        if (extractionWorkItemCount == 0 && staleFilePurgePlan.Count == 0)
-            return false;
-
-        var dirtyBytes = staleFilePurgePlan.DeletedBytes;
-        var persistedSizeExcessBytes = 0L;
-        var byteEstimateComplete = !scanHadErrors
-            && staleFilePurgePlan.ByteEstimateComplete
-            && readableFileBytes.EstimateComplete;
-
-        void AddDirtyFileBytes(int fileIndex)
+        internal void DecideFtsBulkLoad()
         {
-            throwIfCancelled();
-            try
+            var request = Request;
+            var options = request.Core.Options;
+            var baseline = request.Baseline;
+            var runtime = request.Runtime;
+            var scan = State.Scan;
+            var csharp = State.CSharp;
+            var selection = State.Selection;
+            if (options.Rebuild || baseline.StartedWithNoIndexedFiles)
             {
-                var target = fileTargets[fileIndex];
-                var info = new FileInfo(target.FilePath);
-                if (!info.Exists || info.Length < 0)
+                selection.UseFtsBulkLoad = true;
+                return;
+            }
+
+            if (selection.ExtractionWorkItemCount == 0
+                && scan.StaleFilePurgePlan.Count == 0)
+            {
+                selection.UseFtsBulkLoad = false;
+                return;
+            }
+
+            var dirtyBytes = scan.StaleFilePurgePlan.DeletedBytes;
+            var persistedSizeExcessBytes = 0L;
+            var byteEstimateComplete = !baseline.ScanHadErrors
+                && scan.StaleFilePurgePlan.ByteEstimateComplete
+                && selection.ReadableFileBytes.EstimateComplete;
+
+            void AddDirtyFileBytes(int fileIndex)
+            {
+                ThrowIfFullScanCancelled();
+                try
+                {
+                    var target = runtime.FileTargets[fileIndex];
+                    var info = new FileInfo(target.FilePath);
+                    if (!info.Exists || info.Length < 0)
+                    {
+                        byteEstimateComplete = false;
+                        return;
+                    }
+
+                    selection.ReadableFileBytes.Remember(
+                        fileIndex,
+                        info.Length);
+                    var persistedSize = csharp.ReusableIndexedFileStats!
+                        .GetPersistedSize(target.IndexPath);
+                    if (!FtsBulkLoadTriggerGuard.TryAccumulateDirtyFileBytes(
+                            dirtyBytes,
+                            persistedSizeExcessBytes,
+                            info.Length,
+                            persistedSize,
+                            out dirtyBytes,
+                            out persistedSizeExcessBytes))
+                    {
+                        byteEstimateComplete = false;
+                    }
+                }
+                catch (Exception ex) when (
+                    ex is IOException
+                        or UnauthorizedAccessException
+                        or NotSupportedException
+                        or ArgumentException)
                 {
                     byteEstimateComplete = false;
-                    return;
                 }
+            }
 
-                readableFileBytes.Remember(fileIndex, info.Length);
-                var persistedSize = reusableIndexedFileStats.GetPersistedSize(target.IndexPath);
-                if (!FtsBulkLoadTriggerGuard.TryAccumulateDirtyFileBytes(
-                        dirtyBytes,
-                        persistedSizeExcessBytes,
-                        info.Length,
-                        persistedSize,
-                        out dirtyBytes,
-                        out persistedSizeExcessBytes))
+            if (selection.ExtractionFileIndexes != null)
+            {
+                foreach (var fileIndex in selection.ExtractionFileIndexes)
+                    AddDirtyFileBytes(fileIndex);
+            }
+            else
+            {
+                for (var fileIndex = 0;
+                     fileIndex < runtime.FileTargets.Length;
+                     fileIndex++)
                 {
-                    byteEstimateComplete = false;
+                    AddDirtyFileBytes(fileIndex);
                 }
             }
-            catch (Exception ex) when (
-                ex is IOException
-                    or UnauthorizedAccessException
-                    or NotSupportedException
-                    or ArgumentException)
+
+            byteEstimateComplete &=
+                selection.ReadableFileBytes.EstimateComplete;
+            var totalBytes = selection.ReadableFileBytes.KnownBytes;
+            if (!selection.ReadableFileBytes.EstimateComplete
+                || totalBytes
+                > long.MaxValue - scan.StaleFilePurgePlan.DeletedBytes)
             {
                 byteEstimateComplete = false;
             }
-        }
+            else
+            {
+                totalBytes += scan.StaleFilePurgePlan.DeletedBytes;
+            }
 
-        if (extractionFileIndexes != null)
-        {
-            foreach (var fileIndex in extractionFileIndexes)
-                AddDirtyFileBytes(fileIndex);
-        }
-        else
-        {
-            for (var fileIndex = 0; fileIndex < fileTargets.Count; fileIndex++)
-                AddDirtyFileBytes(fileIndex);
-        }
+            if (totalBytes > long.MaxValue - persistedSizeExcessBytes)
+                byteEstimateComplete = false;
+            else
+                totalBytes += persistedSizeExcessBytes;
 
-        byteEstimateComplete &= readableFileBytes.EstimateComplete;
-        var totalBytes = readableFileBytes.KnownBytes;
-        if (!readableFileBytes.EstimateComplete
-            || totalBytes > long.MaxValue - staleFilePurgePlan.DeletedBytes)
-        {
-            byteEstimateComplete = false;
-        }
-        else
-        {
-            totalBytes += staleFilePurgePlan.DeletedBytes;
+            selection.UseFtsBulkLoad = byteEstimateComplete
+                && FtsBulkLoadTriggerGuard.ShouldUseForDirtyBytes(
+                    dirtyBytes,
+                    totalBytes);
         }
-
-        if (totalBytes > long.MaxValue - persistedSizeExcessBytes)
-            byteEstimateComplete = false;
-        else
-            totalBytes += persistedSizeExcessBytes;
-
-        return byteEstimateComplete
-            && FtsBulkLoadTriggerGuard.ShouldUseForDirtyBytes(dirtyBytes, totalBytes);
     }
 }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.CSharpFinalRevalidation.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.CSharpFinalRevalidation.cs
index a637c8e14..b7c25beba 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.CSharpFinalRevalidation.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.CSharpFinalRevalidation.cs
@@ -5,247 +5,165 @@ namespace CodeIndex.Cli;
 
 public static partial class IndexCommandRunner
 {
-    private sealed class FullScanCSharpFinalRevalidationContext
+    private sealed partial class FullScanPreWriteSession
     {
-        internal required DbWriter Writer { get; init; }
-        internal required FileIndexer Indexer { get; init; }
-        internal required IndexCommandOptions Options { get; init; }
-        internal required string ProjectRoot { get; init; }
-        internal required FullScanFileTarget[] FileTargets { get; init; }
-        internal required IReadOnlyList<CSharpStaticInterfacePrepass.FileTarget>
-            CSharpPrepassTargets
-        { get; init; }
-        internal required FilePurgePlan StaleFilePurgePlan { get; init; }
-        internal required bool StartedWithNoIndexedFiles { get; init; }
-        internal required bool CSharpIndexedProjectRootCompatible
+        internal void RevalidateFinalCSharpNoOp()
         {
-            get;
-            init;
-        }
-
-        internal required int ExtractionParallelism { get; init; }
-        internal required bool? PriorCSharpStaticInterfaceSourceEvidence
-        {
-            get;
-            init;
-        }
-
-        internal required ReusableIndexedFileStatsSnapshot
-            ReusableIndexedFileStats
-        { get; init; }
-        internal List<int>? ExtractionFileIndexes { get; init; }
-        internal required int ExtractionWorkItemCount { get; init; }
-        internal required bool UseFtsBulkLoad { get; init; }
-        internal required CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace
-        {
-            get;
-            init;
-        }
+            var csharp = State.CSharp;
+            var selection = State.Selection;
+            if (!csharp.PreservePriorPositiveSourceNoOp
+                || (selection.ExtractionWorkItemCount == 0
+                    && State.Scan.StaleFilePurgePlan.Count == 0))
+            {
+                return;
+            }
 
-        internal Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
-            CSharpWorkspaceFileSnapshots
-        { get; init; }
-        internal required bool ForceFullCSharpRefreshFromInvalidatedNoOp
-        {
-            get;
-            init;
+            // The dirty-byte pass can be long on a mixed-language monorepo. Revalidate C#
+            // once more at the final read-only boundary, then undo tentative stat skips
+            // and promote every affected C# target if any source changed.
+            // mixed-language dirty-byte pass後の最終read-only境界でC#を再statする。
+            FullScanCSharpFinalStatRevalidationForTesting?.Invoke();
+            var invalidatedCSharpFileIndexes =
+                FindInvalidatedFinalCSharpTargets();
+            if (invalidatedCSharpFileIndexes.Count == 0)
+                return;
+
+            RebuildFinalFullScanCSharpWorkspace(
+                invalidatedCSharpFileIndexes);
         }
 
-        internal required bool PreservePriorPositiveCSharpSourceNoOp
+        private List<int> FindInvalidatedFinalCSharpTargets()
         {
-            get;
-            init;
-        }
-
-        internal required bool CSharpSourceEvidenceForStamp { get; init; }
-        internal required bool CSharpSourceEvidenceComplete { get; init; }
-        internal required CancellationToken CancellationToken { get; init; }
-        internal required Action<CSharpStaticInterfaceWorkspaceSymbols>
-            DeferCSharpMutationsForIncompleteWorkspace
-        { get; init; }
-        internal required Func<string, bool>
-            IsExistingCSharpSymbolPathNowNonCSharp
-        { get; init; }
-    }
-
-    private sealed record FullScanCSharpFinalRevalidationResult(
-        List<int>? ExtractionFileIndexes,
-        int ExtractionWorkItemCount,
-        bool UseFtsBulkLoad,
-        CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace,
-        Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
-            CSharpWorkspaceFileSnapshots,
-        bool ForceFullCSharpRefreshFromInvalidatedNoOp,
-        bool PreservePriorPositiveCSharpSourceNoOp,
-        bool CSharpSourceEvidenceForStamp,
-        bool CSharpSourceEvidenceComplete,
-        int PromotedCSharpTargetCount,
-        bool PromotedAllCSharpTargets);
-
-    private static FullScanCSharpFinalRevalidationResult
-        RevalidateFinalFullScanCSharpNoOp(
-            FullScanCSharpFinalRevalidationContext context)
-    {
-        if (!context.PreservePriorPositiveCSharpSourceNoOp
-            || (context.ExtractionWorkItemCount == 0
-                && context.StaleFilePurgePlan.Count == 0))
-        {
-            return BuildUnchangedFinalCSharpRevalidationResult(context);
-        }
-
-        // The dirty-byte pass can be long on a mixed-language monorepo. Revalidate C#
-        // once more at the final read-only boundary, then undo tentative stat skips
-        // and promote every affected C# target if any source changed.
-        // mixed-language dirty-byte pass後の最終read-only境界でC#を再statする。
-        FullScanCSharpFinalStatRevalidationForTesting?.Invoke();
-        var invalidatedCSharpFileIndexes = FindInvalidatedFinalCSharpTargets(
-            context);
-        if (invalidatedCSharpFileIndexes.Count == 0)
-            return BuildUnchangedFinalCSharpRevalidationResult(context);
-
-        return RebuildFinalFullScanCSharpWorkspace(
-            context,
-            invalidatedCSharpFileIndexes);
-    }
-
-    private static List<int> FindInvalidatedFinalCSharpTargets(
-        FullScanCSharpFinalRevalidationContext context)
-    {
-        var invalidatedCSharpFileIndexes = new List<int>();
-        for (var fileIndex = 0;
-             fileIndex < context.FileTargets.Length;
-             fileIndex++)
-        {
-            var target = context.FileTargets[fileIndex];
-            if (target.Language != "csharp")
-                continue;
-
-            context.CancellationToken.ThrowIfCancellationRequested();
-            if (IndexedFileStatReuse.TryGetReusableUnchangedFile(
-                    context.ReusableIndexedFileStats,
-                    target.FilePath,
-                    target.IndexPath,
-                    target.Language,
-                    target.GeneratedExtractionSuppressed) == null)
+            var runtime = Request.Runtime;
+            var invalidatedCSharpFileIndexes = new List<int>();
+            for (var fileIndex = 0;
+                 fileIndex < runtime.FileTargets.Length;
+                 fileIndex++)
             {
-                invalidatedCSharpFileIndexes.Add(fileIndex);
+                var target = runtime.FileTargets[fileIndex];
+                if (target.Language != "csharp")
+                    continue;
+
+                runtime.CancellationToken.ThrowIfCancellationRequested();
+                if (IndexedFileStatReuse.TryGetReusableUnchangedFile(
+                        State.CSharp.ReusableIndexedFileStats!,
+                        target.FilePath,
+                        target.IndexPath,
+                        target.Language,
+                        target.GeneratedExtractionSuppressed) == null)
+                {
+                    invalidatedCSharpFileIndexes.Add(fileIndex);
+                }
             }
-        }
 
-        return invalidatedCSharpFileIndexes;
-    }
+            return invalidatedCSharpFileIndexes;
+        }
 
-    private static FullScanCSharpFinalRevalidationResult
-        RebuildFinalFullScanCSharpWorkspace(
-            FullScanCSharpFinalRevalidationContext context,
+        private void RebuildFinalFullScanCSharpWorkspace(
             IReadOnlyList<int> invalidatedCSharpFileIndexes)
-    {
-        var workspace = BuildStableFullScanCSharpWorkspace(
-            context.ProjectRoot,
-            context.CSharpPrepassTargets,
-            out var workspaceFileSnapshots,
-            () => CSharpStaticInterfacePrepass.BuildWorkspaceSymbols(
-                context.Writer,
-                context.Indexer,
-                context.CSharpPrepassTargets,
-                includeExistingSymbols:
-                    context.CSharpIndexedProjectRootCompatible
-                    && !context.Options.Rebuild
-                    && !context.StartedWithNoIndexedFiles,
-                canReuseExistingSymbolsWithoutRead: null,
-                parallelism: context.ExtractionParallelism,
-                excludedExistingFileIds:
-                    context.StaleFilePurgePlan.FileIds,
-                isExistingSymbolPathExcluded:
-                    context.IsExistingCSharpSymbolPathNowNonCSharp,
-                patternConfigsAlreadyLoaded: true,
-                cancellationToken: context.CancellationToken),
-            context.CancellationToken);
-        if (!workspace.SourceContractEvidenceComplete)
         {
-            var incompleteSourcePaths = workspace.IncompleteSourcePaths;
-            context.DeferCSharpMutationsForIncompleteWorkspace(workspace);
-            return new FullScanCSharpFinalRevalidationResult(
-                context.ExtractionFileIndexes,
-                context.ExtractionWorkItemCount,
-                UseFtsBulkLoad: false,
-                new CSharpStaticInterfaceWorkspaceSymbols(
-                    [],
-                    false,
-                    SourceContractEvidenceComplete: false,
-                    IncompleteSourcePaths: incompleteSourcePaths),
-                workspaceFileSnapshots,
-                context.ForceFullCSharpRefreshFromInvalidatedNoOp,
-                PreservePriorPositiveCSharpSourceNoOp: false,
-                CSharpSourceEvidenceForStamp: false,
-                CSharpSourceEvidenceComplete: false,
-                PromotedCSharpTargetCount: 0,
-                PromotedAllCSharpTargets: false);
-        }
+            var request = Request;
+            var core = request.Core;
+            var baseline = request.Baseline;
+            var contracts = request.Contracts;
+            var runtime = request.Runtime;
+            var scan = State.Scan;
+            var csharp = State.CSharp;
+            var selection = State.Selection;
+            var workspace = BuildStableFullScanCSharpWorkspace(
+                core.ProjectRoot,
+                runtime.CSharpPrepassTargets,
+                out var workspaceFileSnapshots,
+                () => CSharpStaticInterfacePrepass.BuildWorkspaceSymbols(
+                    core.Writer,
+                    core.Indexer,
+                    runtime.CSharpPrepassTargets,
+                    includeExistingSymbols:
+                        contracts.CSharpIndexedProjectRootCompatible
+                        && !core.Options.Rebuild
+                        && !baseline.StartedWithNoIndexedFiles,
+                    canReuseExistingSymbolsWithoutRead: null,
+                    parallelism: runtime.ExtractionParallelism,
+                    excludedExistingFileIds:
+                        scan.StaleFilePurgePlan.FileIds,
+                    isExistingSymbolPathExcluded:
+                        IsExistingCSharpSymbolPathNowNonCSharp,
+                    patternConfigsAlreadyLoaded: true,
+                    cancellationToken: runtime.CancellationToken),
+                runtime.CancellationToken);
+            if (!workspace.SourceContractEvidenceComplete)
+            {
+                var incompleteSourcePaths = workspace.IncompleteSourcePaths;
+                DeferCSharpMutationsForIncompleteWorkspace(workspace);
+                selection.UseFtsBulkLoad = false;
+                csharp.Workspace =
+                    new CSharpStaticInterfaceWorkspaceSymbols(
+                        [],
+                        false,
+                        SourceContractEvidenceComplete: false,
+                        IncompleteSourcePaths: incompleteSourcePaths);
+                csharp.WorkspaceFileSnapshots = workspaceFileSnapshots;
+                csharp.PreservePriorPositiveSourceNoOp = false;
+                csharp.Evidence.ForStamp = false;
+                csharp.Evidence.Complete = false;
+                return;
+            }
 
-        var requiresFullCSharpRefresh =
-            context.PriorCSharpStaticInterfaceSourceEvidence == true
-            || workspace.HasStaticInterfaceContracts;
-        IReadOnlyList<int> csharpFileIndexesToRefresh;
-        if (requiresFullCSharpRefresh)
-        {
-            workspace = workspace with
+            var requiresFullCSharpRefresh =
+                baseline.PriorCSharpStaticInterfaceSourceEvidence == true
+                || workspace.HasStaticInterfaceContracts;
+            IReadOnlyList<int> csharpFileIndexesToRefresh;
+            if (requiresFullCSharpRefresh)
             {
-                HasStaticInterfaceContracts = true,
-            };
-            var allCSharpFileIndexes =
-                new List<int>(context.CSharpPrepassTargets.Count);
-            for (var fileIndex = 0;
-                 fileIndex < context.FileTargets.Length;
-                 fileIndex++)
+                workspace = workspace with
+                {
+                    HasStaticInterfaceContracts = true,
+                };
+                var allCSharpFileIndexes =
+                    new List<int>(runtime.CSharpPrepassTargets.Count);
+                for (var fileIndex = 0;
+                     fileIndex < runtime.FileTargets.Length;
+                     fileIndex++)
+                {
+                    if (runtime.FileTargets[fileIndex].Language == "csharp")
+                        allCSharpFileIndexes.Add(fileIndex);
+                }
+
+                csharpFileIndexesToRefresh = allCSharpFileIndexes;
+            }
+            else
             {
-                if (context.FileTargets[fileIndex].Language == "csharp")
-                    allCSharpFileIndexes.Add(fileIndex);
+                // A previously authoritative negative workspace only needs the
+                // stat-invalidated files when the raw fallback is still negative.
+                // prior negative のraw fallbackもnegativeなら変更fileだけを更新する。
+                csharpFileIndexesToRefresh = invalidatedCSharpFileIndexes;
             }
 
-            csharpFileIndexesToRefresh = allCSharpFileIndexes;
-        }
-        else
-        {
-            // A previously authoritative negative workspace only needs the
-            // stat-invalidated files when the raw fallback is still negative.
-            // prior negative のraw fallbackもnegativeなら変更fileだけを更新する。
-            csharpFileIndexesToRefresh = invalidatedCSharpFileIndexes;
-        }
+            var extractionFileIndexes = selection.ExtractionFileIndexes
+                ?? new List<int>(csharpFileIndexesToRefresh.Count);
+            foreach (var fileIndex in csharpFileIndexesToRefresh)
+                extractionFileIndexes.Add(fileIndex);
+            extractionFileIndexes.Sort();
+            selection.ExtractionFileIndexes = extractionFileIndexes;
+            selection.ExtractionWorkItemCount = extractionFileIndexes.Count;
+            selection.UseFtsBulkLoad = false;
+            selection.Skipped -= csharpFileIndexesToRefresh.Count;
+            selection.Processed -= csharpFileIndexesToRefresh.Count;
+            if (csharpFileIndexesToRefresh.Count
+                == runtime.CSharpPrepassTargets.Count)
+            {
+                selection.SkippedSymbolExtractorLanguages?.Remove("csharp");
+                selection.ReusedHotspotFamilyLanguages?.Remove("csharp");
+            }
 
-        var extractionFileIndexes = context.ExtractionFileIndexes
-            ?? new List<int>(csharpFileIndexesToRefresh.Count);
-        foreach (var fileIndex in csharpFileIndexesToRefresh)
-            extractionFileIndexes.Add(fileIndex);
-        extractionFileIndexes.Sort();
-        return new FullScanCSharpFinalRevalidationResult(
-            extractionFileIndexes,
-            extractionFileIndexes.Count,
-            UseFtsBulkLoad: false,
-            workspace,
-            workspaceFileSnapshots,
-            requiresFullCSharpRefresh,
-            PreservePriorPositiveCSharpSourceNoOp: false,
-            workspace.HasSourceStaticInterfaceContracts,
-            CSharpSourceEvidenceComplete: true,
-            csharpFileIndexesToRefresh.Count,
-            csharpFileIndexesToRefresh.Count
-                == context.CSharpPrepassTargets.Count);
+            csharp.Workspace = workspace;
+            csharp.WorkspaceFileSnapshots = workspaceFileSnapshots;
+            csharp.ForceFullRefreshFromInvalidatedNoOp =
+                requiresFullCSharpRefresh;
+            csharp.PreservePriorPositiveSourceNoOp = false;
+            csharp.Evidence.ForStamp =
+                workspace.HasSourceStaticInterfaceContracts;
+            csharp.Evidence.Complete = true;
+        }
     }
-
-    private static FullScanCSharpFinalRevalidationResult
-        BuildUnchangedFinalCSharpRevalidationResult(
-            FullScanCSharpFinalRevalidationContext context)
-        => new(
-            context.ExtractionFileIndexes,
-            context.ExtractionWorkItemCount,
-            context.UseFtsBulkLoad,
-            context.CSharpWorkspace,
-            context.CSharpWorkspaceFileSnapshots,
-            context.ForceFullCSharpRefreshFromInvalidatedNoOp,
-            context.PreservePriorPositiveCSharpSourceNoOp,
-            context.CSharpSourceEvidenceForStamp,
-            context.CSharpSourceEvidenceComplete,
-            PromotedCSharpTargetCount: 0,
-            PromotedAllCSharpTargets: false);
 }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.CSharpPreflight.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.CSharpPreflight.cs
index a02960a21..2af16d949 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.CSharpPreflight.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.CSharpPreflight.cs
@@ -5,125 +5,116 @@ namespace CodeIndex.Cli;
 
 public static partial class IndexCommandRunner
 {
-    private sealed class FullScanCSharpPreflightContext
+    private sealed partial class FullScanPreWriteSession
     {
-        internal required DbWriter Writer { get; init; }
-        internal required FileIndexer Indexer { get; init; }
-        internal required IndexCommandOptions Options { get; init; }
-        internal required string ProjectRoot { get; init; }
-        internal required FullScanFileTarget[] FileTargets { get; init; }
-        internal required IReadOnlyList<CSharpStaticInterfacePrepass.FileTarget> CSharpPrepassTargets { get; init; }
-        internal required int CSharpPrepassCapacity { get; init; }
-        internal required FilePurgePlan StaleFilePurgePlan { get; init; }
-        internal required bool StartedWithNoIndexedFiles { get; init; }
-        internal required bool PriorIndexComplete { get; init; }
-        internal required int PriorReadiness { get; init; }
-        internal required bool ScanHadErrors { get; init; }
-        internal required bool ForceExtractorRefresh { get; init; }
-        internal required bool PriorSymbolsOnlyGraphOmitted { get; init; }
-        internal required bool SymbolKindFilterMatchesPrior { get; init; }
-        internal required bool CSharpSymbolNameContractMatchesCurrent { get; init; }
-        internal required bool CSharpIndexedProjectRootCompatible { get; init; }
-        internal required bool CSharpHotspotTrustMatchesCurrent { get; init; }
-        internal required bool RequiresConservativeCSharpSourceRefresh { get; init; }
-        internal required bool HadCSharpStaticInterfaceContractsBeforePurge { get; init; }
-        internal required bool? PriorCSharpStaticInterfaceSourceEvidence { get; init; }
-        internal required bool ProjectRootWritten { get; init; }
-        internal required int ExtractionParallelism { get; init; }
-        internal required int FilesCount { get; init; }
-        internal required string ActualMode { get; init; }
-        internal required CancellationToken CancellationToken { get; init; }
-        internal required Func<string, bool> IsExistingCSharpSymbolPathNowNonCSharp { get; init; }
-        internal required Func<bool> GetDeferCSharpMutationsForIncompleteScan { get; init; }
-        internal required Func<int> GetPurged { get; init; }
-        internal required Action<CSharpStaticInterfaceWorkspaceSymbols> DeferCSharpMutationsForIncompleteWorkspace { get; init; }
-    }
-
-    private sealed record FullScanCSharpPreflightResult(
-        ReusableIndexedFileStatsSnapshot? ReusableIndexedFileStats,
-        Dictionary<string, IndexedFileStatReuseResult?>? CSharpPrepassStatReuse,
-        Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>? CSharpWorkspaceFileSnapshots,
-        CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace,
-        CSharpPrepassSymbolArtifactCache? CSharpPrepassSymbolArtifacts,
-        bool ForceFullCSharpRefreshFromInvalidatedNoOp,
-        bool PreservePriorPositiveCSharpSourceNoOp,
-        bool CSharpSourceEvidenceForStamp,
-        bool CSharpSourceEvidenceComplete);
-
-    private static FullScanCSharpPreflightResult PrepareFullScanCSharpWorkspace(
-        FullScanCSharpPreflightContext context)
-    {
-        var writer = context.Writer;
-        var options = context.Options;
-        var cancellationToken = context.CancellationToken;
-        HashSet<string>? retainedPathsForReuse = null;
-        if (!options.Rebuild
-            && !context.StartedWithNoIndexedFiles
-            && context.StaleFilePurgePlan.RemainingFileCount
-                - context.FileTargets.LongLength
-                > context.FileTargets.LongLength)
+        internal void PrepareCSharpWorkspace()
         {
-            retainedPathsForReuse = new HashSet<string>(
-                context.FileTargets.Length,
-                StringComparer.Ordinal);
-            foreach (var target in context.FileTargets)
-                retainedPathsForReuse.Add(target.IndexPath);
-        }
+            var request = Request;
+            var core = request.Core;
+            var baseline = request.Baseline;
+            var contracts = request.Contracts;
+            var runtime = request.Runtime;
+            var scan = State.Scan;
+            var csharp = State.CSharp;
+            var writer = core.Writer;
+            var options = core.Options;
+            var cancellationToken = runtime.CancellationToken;
+            HashSet<string>? retainedPathsForReuse = null;
+            if (!options.Rebuild
+                && !baseline.StartedWithNoIndexedFiles
+                && scan.StaleFilePurgePlan.RemainingFileCount
+                    - runtime.FileTargets.LongLength
+                    > runtime.FileTargets.LongLength)
+            {
+                retainedPathsForReuse = new HashSet<string>(
+                    runtime.FileTargets.Length,
+                    StringComparer.Ordinal);
+                foreach (var target in runtime.FileTargets)
+                    retainedPathsForReuse.Add(target.IndexPath);
+            }
 
-        var csharpPositiveNoOpPolicyCandidate = !options.SymbolsOnly
-            && context.PriorCSharpStaticInterfaceSourceEvidence is not null
-            && context.PriorIndexComplete
-            && (context.PriorReadiness & DbContext.GraphReadyFlag) != 0
-            && !context.ScanHadErrors
-            && !context.HadCSharpStaticInterfaceContractsBeforePurge
-            && !context.ForceExtractorRefresh
-            && !context.PriorSymbolsOnlyGraphOmitted
-            && context.SymbolKindFilterMatchesPrior
-            && context.CSharpSymbolNameContractMatchesCurrent
-            && context.CSharpIndexedProjectRootCompatible
-            && context.CSharpHotspotTrustMatchesCurrent
-            && context.CSharpPrepassTargets.Count > 0;
-        var hasCSharpLanguageTransitions = false;
-        void ObservePersistedCSharpPath(string indexPath)
-        {
-            if (!hasCSharpLanguageTransitions
-                && context.IsExistingCSharpSymbolPathNowNonCSharp(indexPath))
+            var csharpPositiveNoOpPolicyCandidate = !options.SymbolsOnly
+                && baseline.PriorCSharpStaticInterfaceSourceEvidence is not null
+                && baseline.PriorIndexComplete
+                && (baseline.PriorReadiness & DbContext.GraphReadyFlag) != 0
+                && !baseline.ScanHadErrors
+                && !scan.HadCSharpStaticInterfaceContractsBeforePurge
+                && !contracts.ForceExtractorRefresh
+                && !baseline.PriorSymbolsOnlyGraphOmitted
+                && contracts.SymbolKindFilterMatchesPrior
+                && contracts.CSharpSymbolNameContractMatchesCurrent
+                && contracts.CSharpIndexedProjectRootCompatible
+                && contracts.CSharpHotspotTrustMatchesCurrent
+                && runtime.CSharpPrepassTargets.Count > 0;
+            var hasCSharpLanguageTransitions = false;
+            void ObservePersistedCSharpPath(string indexPath)
             {
-                hasCSharpLanguageTransitions = true;
+                if (!hasCSharpLanguageTransitions
+                    && IsExistingCSharpSymbolPathNowNonCSharp(indexPath))
+                {
+                    hasCSharpLanguageTransitions = true;
+                }
             }
-        }
 
-        var reusableIndexedFileStats =
-            !options.Rebuild && !context.StartedWithNoIndexedFiles
-                ? writer.LoadReusableIndexedFileStats(
-                    options.MaxSymbolsPerFile,
-                    options.MaxReferencesPerFile,
-                    cancellationToken,
-                    context.FileTargets.Length,
-                    retainedPathsForReuse,
-                    context.StaleFilePurgePlan.FileIds,
-                    csharpPositiveNoOpPolicyCandidate
-                        ? ObservePersistedCSharpPath
-                        : null,
-                    maxFileSizeBytes:
-                        options.MaxFileSizeBytes ?? FileIndexer.DefaultMaxFileSizeBytes)
-                : null;
-        Dictionary<string, IndexedFileStatReuseResult?>?
-            csharpPrepassStatReuse = null;
-        var priorPositiveCSharpSourceNoOpCandidate =
-            csharpPositiveNoOpPolicyCandidate
-            && !hasCSharpLanguageTransitions;
-        var allCSharpPrepassTargetsReusable = false;
-        if (priorPositiveCSharpSourceNoOpCandidate)
-        {
-            allCSharpPrepassTargetsReusable = true;
-            csharpPrepassStatReuse =
-                new Dictionary<string, IndexedFileStatReuseResult?>(
-                    context.CSharpPrepassCapacity,
-                    StringComparer.Ordinal);
-            foreach (var target in context.CSharpPrepassTargets)
+            var reusableIndexedFileStats =
+                !options.Rebuild && !baseline.StartedWithNoIndexedFiles
+                    ? writer.LoadReusableIndexedFileStats(
+                        options.MaxSymbolsPerFile,
+                        options.MaxReferencesPerFile,
+                        cancellationToken,
+                        runtime.FileTargets.Length,
+                        retainedPathsForReuse,
+                        scan.StaleFilePurgePlan.FileIds,
+                        csharpPositiveNoOpPolicyCandidate
+                            ? ObservePersistedCSharpPath
+                            : null,
+                        maxFileSizeBytes:
+                            options.MaxFileSizeBytes ?? FileIndexer.DefaultMaxFileSizeBytes)
+                    : null;
+            Dictionary<string, IndexedFileStatReuseResult?>?
+                csharpPrepassStatReuse = null;
+            var priorPositiveCSharpSourceNoOpCandidate =
+                csharpPositiveNoOpPolicyCandidate
+                && !hasCSharpLanguageTransitions;
+            var allCSharpPrepassTargetsReusable = false;
+            if (priorPositiveCSharpSourceNoOpCandidate)
+            {
+                allCSharpPrepassTargetsReusable = true;
+                csharpPrepassStatReuse =
+                    new Dictionary<string, IndexedFileStatReuseResult?>(
+                        runtime.CSharpPrepassCapacity,
+                        StringComparer.Ordinal);
+                foreach (var target in runtime.CSharpPrepassTargets)
+                {
+                    cancellationToken.ThrowIfCancellationRequested();
+                    var existingFile =
+                        IndexedFileStatReuse.TryGetReusableUnchangedFile(
+                            reusableIndexedFileStats!,
+                            target.FilePath,
+                            target.IndexPath,
+                            target.Language,
+                            target.GeneratedExtractionSuppressed);
+                    csharpPrepassStatReuse[target.IndexPath] = existingFile;
+                    allCSharpPrepassTargetsReusable &= existingFile != null;
+                }
+            }
+
+            bool CanReuseCSharpPrepassTargetWithoutRead(
+                CSharpStaticInterfacePrepass.FileTarget target)
             {
-                cancellationToken.ThrowIfCancellationRequested();
+                if (contracts.ForceExtractorRefresh
+                    || options.Rebuild
+                    || baseline.StartedWithNoIndexedFiles
+                    || !baseline.ProjectRootWritten
+                    || (contracts.RequiresConservativeCSharpSourceRefresh
+                        && !priorPositiveCSharpSourceNoOpCandidate)
+                    || !contracts.SymbolKindFilterMatchesPrior
+                    || !contracts.CSharpSymbolNameContractMatchesCurrent
+                    || target.Language != "csharp")
+                {
+                    return false;
+                }
+
                 var existingFile =
                     IndexedFileStatReuse.TryGetReusableUnchangedFile(
                         reusableIndexedFileStats!,
@@ -131,217 +122,263 @@ void ObservePersistedCSharpPath(string indexPath)
                         target.IndexPath,
                         target.Language,
                         target.GeneratedExtractionSuppressed);
-                csharpPrepassStatReuse[target.IndexPath] = existingFile;
-                allCSharpPrepassTargetsReusable &= existingFile != null;
+                if (existingFile == null)
+                    allCSharpPrepassTargetsReusable = false;
+                (csharpPrepassStatReuse ??=
+                    new Dictionary<string, IndexedFileStatReuseResult?>(
+                        runtime.CSharpPrepassCapacity,
+                        StringComparer.Ordinal))[target.IndexPath] = existingFile;
+                return existingFile != null;
             }
-        }
 
-        bool CanReuseCSharpPrepassTargetWithoutRead(
-            CSharpStaticInterfacePrepass.FileTarget target)
-        {
-            if (context.ForceExtractorRefresh
-                || options.Rebuild
-                || context.StartedWithNoIndexedFiles
-                || !context.ProjectRootWritten
-                || (context.RequiresConservativeCSharpSourceRefresh
-                    && !priorPositiveCSharpSourceNoOpCandidate)
-                || !context.SymbolKindFilterMatchesPrior
-                || !context.CSharpSymbolNameContractMatchesCurrent
-                || target.Language != "csharp")
+            Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
+                csharpWorkspaceFileSnapshots = null;
+            CSharpStaticInterfaceWorkspaceSymbols csharpWorkspace;
+            var forceFullCSharpRefreshFromInvalidatedNoOp = false;
+            var csharpWorkspaceMaterialized =
+                !options.SymbolsOnly
+                && !scan.DeferCSharpMutationsForIncompleteScan
+                && runtime.CSharpPrepassTargets.Count > 0
+                && !(priorPositiveCSharpSourceNoOpCandidate
+                    && allCSharpPrepassTargetsReusable);
+            var csharpPrepassSymbolArtifacts = CSharpPrepassSymbolArtifactCache
+                .CreateForFreshBuiltInExtraction(
+                    csharpWorkspaceMaterialized
+                    && baseline.StartedWithNoIndexedFiles
+                    && !options.Rebuild
+                    && !options.SymbolsOnly
+                    && IndexExtractionStallTimeoutForTesting == null);
+            if (options.SymbolsOnly
+                || scan.DeferCSharpMutationsForIncompleteScan)
+            {
+                csharpWorkspace =
+                    new CSharpStaticInterfaceWorkspaceSymbols([], false);
+            }
+            else
             {
-                return false;
+                csharpWorkspace = BuildFullScanCSharpWorkspaceWithHeartbeat(
+                    priorPositiveCSharpSourceNoOpCandidate,
+                    allCSharpPrepassTargetsReusable,
+                    CanReuseCSharpPrepassTargetWithoutRead,
+                    csharpPrepassSymbolArtifacts,
+                    out csharpWorkspaceFileSnapshots);
+                forceFullCSharpRefreshFromInvalidatedNoOp =
+                    csharpWorkspaceMaterialized
+                    && (baseline.PriorCSharpStaticInterfaceSourceEvidence == true
+                        || csharpWorkspace.HasStaticInterfaceContracts
+                        || csharpWorkspace
+                            .RequiresMemberReadReferenceRefresh);
             }
 
-            var existingFile =
-                IndexedFileStatReuse.TryGetReusableUnchangedFile(
-                    reusableIndexedFileStats!,
-                    target.FilePath,
-                    target.IndexPath,
-                    target.Language,
-                    target.GeneratedExtractionSuppressed);
-            if (existingFile == null)
-                allCSharpPrepassTargetsReusable = false;
-            (csharpPrepassStatReuse ??=
-                new Dictionary<string, IndexedFileStatReuseResult?>(
-                    context.CSharpPrepassCapacity,
-                    StringComparer.Ordinal))[target.IndexPath] = existingFile;
-            return existingFile != null;
-        }
+            if (!options.SymbolsOnly
+                && !csharpWorkspace.SourceContractEvidenceComplete)
+            {
+                csharpPrepassSymbolArtifacts?.Clear();
+                csharpPrepassSymbolArtifacts = null;
+                var incompleteSourcePaths =
+                    csharpWorkspace.IncompleteSourcePaths;
+                DeferCSharpMutationsForIncompleteWorkspace(
+                    csharpWorkspace);
+                csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
+                    [],
+                    false,
+                    SourceContractEvidenceComplete: false,
+                    IncompleteSourcePaths: incompleteSourcePaths);
+            }
 
-        Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
-            csharpWorkspaceFileSnapshots = null;
-        CSharpStaticInterfaceWorkspaceSymbols csharpWorkspace;
-        var forceFullCSharpRefreshFromInvalidatedNoOp = false;
-        var csharpWorkspaceMaterialized =
-            !options.SymbolsOnly
-            && !context.GetDeferCSharpMutationsForIncompleteScan()
-            && context.CSharpPrepassTargets.Count > 0
-            && !(priorPositiveCSharpSourceNoOpCandidate
-                && allCSharpPrepassTargetsReusable);
-        var csharpPrepassSymbolArtifacts = CSharpPrepassSymbolArtifactCache
-            .CreateForFreshBuiltInExtraction(
-                csharpWorkspaceMaterialized
-                && context.StartedWithNoIndexedFiles
-                && !options.Rebuild
-                && !options.SymbolsOnly
-                && IndexExtractionStallTimeoutForTesting == null);
-        if (options.SymbolsOnly
-            || context.GetDeferCSharpMutationsForIncompleteScan())
-        {
-            csharpWorkspace =
-                new CSharpStaticInterfaceWorkspaceSymbols([], false);
-        }
-        else
-        {
-            csharpWorkspace = BuildFullScanCSharpWorkspaceWithHeartbeat(
-                context,
-                priorPositiveCSharpSourceNoOpCandidate,
-                allCSharpPrepassTargetsReusable,
-                CanReuseCSharpPrepassTargetWithoutRead,
-                csharpPrepassSymbolArtifacts,
-                out csharpWorkspaceFileSnapshots);
-            forceFullCSharpRefreshFromInvalidatedNoOp =
-                csharpWorkspaceMaterialized
-                && (context.PriorCSharpStaticInterfaceSourceEvidence == true
-                    || csharpWorkspace.HasStaticInterfaceContracts
-                    || csharpWorkspace
-                        .RequiresMemberReadReferenceRefresh);
+            var preservePriorPositiveCSharpSourceNoOp =
+                priorPositiveCSharpSourceNoOpCandidate
+                && allCSharpPrepassTargetsReusable
+                && !scan.DeferCSharpMutationsForIncompleteScan;
+            var csharpSourceEvidenceForStamp =
+                preservePriorPositiveCSharpSourceNoOp
+                    ? baseline.PriorCSharpStaticInterfaceSourceEvidence == true
+                    : csharpWorkspace.HasSourceStaticInterfaceContracts;
+            var csharpSourceEvidenceComplete =
+                preservePriorPositiveCSharpSourceNoOp
+                || csharpWorkspace.SourceContractEvidenceComplete;
+            if (preservePriorPositiveCSharpSourceNoOp)
+            {
+                csharpWorkspace =
+                    csharpWorkspace with { HasStaticInterfaceContracts = false };
+            }
+            if (!options.SymbolsOnly
+                && !scan.DeferCSharpMutationsForIncompleteScan
+                && !preservePriorPositiveCSharpSourceNoOp
+                && (forceFullCSharpRefreshFromInvalidatedNoOp
+                    || contracts.RequiresConservativeCSharpSourceRefresh
+                    || !csharpSourceEvidenceComplete
+                    || (scan.Purged > 0
+                        && scan
+                            .HadCSharpStaticInterfaceContractsBeforePurge)))
+            {
+                csharpWorkspace =
+                    csharpWorkspace with { HasStaticInterfaceContracts = true };
+            }
+
+            csharp.ReusableIndexedFileStats = reusableIndexedFileStats;
+            csharp.CSharpPrepassStatReuse = csharpPrepassStatReuse;
+            csharp.WorkspaceFileSnapshots = csharpWorkspaceFileSnapshots;
+            csharp.Workspace = csharpWorkspace;
+            csharp.PrepassSymbolArtifacts = csharpPrepassSymbolArtifacts;
+            csharp.ForceFullRefreshFromInvalidatedNoOp =
+                forceFullCSharpRefreshFromInvalidatedNoOp;
+            csharp.PreservePriorPositiveSourceNoOp =
+                preservePriorPositiveCSharpSourceNoOp;
+            csharp.Evidence.ForStamp = csharpSourceEvidenceForStamp;
+            csharp.Evidence.Complete = csharpSourceEvidenceComplete;
         }
 
-        if (!options.SymbolsOnly
-            && !csharpWorkspace.SourceContractEvidenceComplete)
+        private CSharpStaticInterfaceWorkspaceSymbols
+            BuildFullScanCSharpWorkspaceWithHeartbeat(
+                bool priorPositiveCSharpSourceNoOpCandidate,
+                bool allCSharpPrepassTargetsReusable,
+                Func<CSharpStaticInterfacePrepass.FileTarget, bool>
+                    canReuseCSharpPrepassTargetWithoutRead,
+                CSharpPrepassSymbolArtifactCache? symbolArtifactCache,
+                out Dictionary<string,
+                    CSharpStaticInterfacePrepass.FileStatSnapshot>?
+                    csharpWorkspaceFileSnapshots)
         {
-            csharpPrepassSymbolArtifacts?.Clear();
-            csharpPrepassSymbolArtifacts = null;
-            var incompleteSourcePaths =
-                csharpWorkspace.IncompleteSourcePaths;
-            context.DeferCSharpMutationsForIncompleteWorkspace(
-                csharpWorkspace);
-            csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
-                [],
-                false,
-                SourceContractEvidenceComplete: false,
-                IncompleteSourcePaths: incompleteSourcePaths);
+            var request = Request;
+            var core = request.Core;
+            var baseline = request.Baseline;
+            var contracts = request.Contracts;
+            var runtime = request.Runtime;
+            var scan = State.Scan;
+            WriteFullScanJsonLiveness(
+                core.Options,
+                "preparing C# workspace symbols...");
+            var activeCSharpWorkspaceFiles =
+                new string?[runtime.CSharpPrepassTargets.Count];
+            var heartbeat = StartFullScanJsonPhaseHeartbeat(
+                core.Options,
+                "preparing C# workspace symbols",
+                () => GetActiveCSharpPrepassPath(
+                    activeCSharpWorkspaceFiles));
+            try
+            {
+                if (runtime.CSharpPrepassTargets.Count == 0
+                    || (priorPositiveCSharpSourceNoOpCandidate
+                        && allCSharpPrepassTargetsReusable))
+                {
+                    csharpWorkspaceFileSnapshots = null;
+                    return new CSharpStaticInterfaceWorkspaceSymbols([], false);
+                }
+
+                return BuildStableFullScanCSharpWorkspace(
+                    core.ProjectRoot,
+                    runtime.CSharpPrepassTargets,
+                    out csharpWorkspaceFileSnapshots,
+                    () => CSharpStaticInterfacePrepass.BuildWorkspaceSymbols(
+                        core.Writer,
+                        core.Indexer,
+                        runtime.CSharpPrepassTargets,
+                        includeExistingSymbols:
+                            contracts.CSharpIndexedProjectRootCompatible
+                            && !core.Options.Rebuild
+                            && !baseline.StartedWithNoIndexedFiles,
+                        canReuseExistingSymbolsWithoutRead:
+                            priorPositiveCSharpSourceNoOpCandidate
+                                ? null
+                                : canReuseCSharpPrepassTargetWithoutRead,
+                        reportCandidateFile: (candidateIndex, path) =>
+                            SetActiveCSharpPrepassPath(
+                                activeCSharpWorkspaceFiles,
+                                candidateIndex,
+                                path),
+                        parallelism: runtime.ExtractionParallelism,
+                        excludedExistingFileIds:
+                            scan.StaleFilePurgePlan.FileIds,
+                        isExistingSymbolPathExcluded:
+                            IsExistingCSharpSymbolPathNowNonCSharp,
+                        patternConfigsAlreadyLoaded: true,
+                        cancellationToken: runtime.CancellationToken,
+                        symbolArtifactCache: symbolArtifactCache),
+                    runtime.CancellationToken);
+            }
+            catch (OperationCanceledException) when (
+                runtime.CancellationToken.IsCancellationRequested)
+            {
+                throw new IndexInterruptedException(
+                    0,
+                    runtime.FilesCount,
+                    runtime.ActualMode);
+            }
+            finally
+            {
+                Array.Clear(activeCSharpWorkspaceFiles);
+                StopFullScanJsonPhaseHeartbeat(heartbeat);
+            }
         }
 
-        var preservePriorPositiveCSharpSourceNoOp =
-            priorPositiveCSharpSourceNoOpCandidate
-            && allCSharpPrepassTargetsReusable
-            && !context.GetDeferCSharpMutationsForIncompleteScan();
-        var csharpSourceEvidenceForStamp =
-            preservePriorPositiveCSharpSourceNoOp
-                ? context.PriorCSharpStaticInterfaceSourceEvidence == true
-                : csharpWorkspace.HasSourceStaticInterfaceContracts;
-        var csharpSourceEvidenceComplete =
-            preservePriorPositiveCSharpSourceNoOp
-            || csharpWorkspace.SourceContractEvidenceComplete;
-        if (preservePriorPositiveCSharpSourceNoOp)
+        internal bool IsExistingCSharpSymbolPathNowNonCSharp(string indexPath)
         {
-            csharpWorkspace =
-                csharpWorkspace with { HasStaticInterfaceContracts = false };
+            var core = Request.Core;
+            var currentPath = Path.Combine(
+                core.ProjectRoot,
+                FileIndexer.NormalizeRelativePathForCurrentPlatform(indexPath));
+            return Request.Runtime.FileLanguages.TryGetValue(
+                    currentPath,
+                    out var currentLanguage)
+                && currentLanguage != "csharp";
         }
-        if (!options.SymbolsOnly
-            && !context.GetDeferCSharpMutationsForIncompleteScan()
-            && !preservePriorPositiveCSharpSourceNoOp
-            && (forceFullCSharpRefreshFromInvalidatedNoOp
-                || context.RequiresConservativeCSharpSourceRefresh
-                || !csharpSourceEvidenceComplete
-                || (context.GetPurged() > 0
-                    && context
-                        .HadCSharpStaticInterfaceContractsBeforePurge)))
+
+        private void DeferCSharpMutationsForIncompleteWorkspace(
+            CSharpStaticInterfaceWorkspaceSymbols workspace)
         {
-            csharpWorkspace =
-                csharpWorkspace with { HasStaticInterfaceContracts = true };
-        }
+            if (workspace.SourceContractEvidenceComplete)
+                return;
 
-        return new FullScanCSharpPreflightResult(
-            reusableIndexedFileStats,
-            csharpPrepassStatReuse,
-            csharpWorkspaceFileSnapshots,
-            csharpWorkspace,
-            csharpPrepassSymbolArtifacts,
-            forceFullCSharpRefreshFromInvalidatedNoOp,
-            preservePriorPositiveCSharpSourceNoOp,
-            csharpSourceEvidenceForStamp,
-            csharpSourceEvidenceComplete);
-    }
+            var scan = State.Scan;
+            scan.DeferCSharpMutationsForIncompleteScan = true;
+            scan.StaleFilePurgePlan = FilePurgePlan.Empty;
+            scan.Purged = 0;
+            scan.FtsMutated = false;
+            scan.HadCSharpStaticInterfaceContractsBeforePurge = false;
 
-    private static CSharpStaticInterfaceWorkspaceSymbols
-        BuildFullScanCSharpWorkspaceWithHeartbeat(
-            FullScanCSharpPreflightContext context,
-            bool priorPositiveCSharpSourceNoOpCandidate,
-            bool allCSharpPrepassTargetsReusable,
-            Func<CSharpStaticInterfacePrepass.FileTarget, bool>
-                canReuseCSharpPrepassTargetWithoutRead,
-            CSharpPrepassSymbolArtifactCache? symbolArtifactCache,
-            out Dictionary<string,
-                CSharpStaticInterfacePrepass.FileStatSnapshot>?
-                csharpWorkspaceFileSnapshots)
-    {
-        WriteFullScanJsonLiveness(
-            context.Options,
-            "preparing C# workspace symbols...");
-        var activeCSharpWorkspaceFiles =
-            new string?[context.CSharpPrepassTargets.Count];
-        var heartbeat = StartFullScanJsonPhaseHeartbeat(
-            context.Options,
-            "preparing C# workspace symbols",
-            () => GetActiveCSharpPrepassPath(
-                activeCSharpWorkspaceFiles));
-        try
-        {
-            if (context.CSharpPrepassTargets.Count == 0
-                || (priorPositiveCSharpSourceNoOpCandidate
-                    && allCSharpPrepassTargetsReusable))
+            var incompletePaths = workspace.IncompleteSourcePaths;
+            if (incompletePaths == null || incompletePaths.Count == 0)
             {
-                csharpWorkspaceFileSnapshots = null;
-                return new CSharpStaticInterfaceWorkspaceSymbols([], false);
+                RecordCSharpWorkspaceFailure(
+                    "<csharp_workspace>",
+                    "csharp_prepass",
+                    new IOException(
+                        "C# static-interface workspace preflight could not read a source file."));
+                return;
             }
 
-            return BuildStableFullScanCSharpWorkspace(
-                context.ProjectRoot,
-                context.CSharpPrepassTargets,
-                out csharpWorkspaceFileSnapshots,
-                () => CSharpStaticInterfacePrepass.BuildWorkspaceSymbols(
-                    context.Writer,
-                    context.Indexer,
-                    context.CSharpPrepassTargets,
-                    includeExistingSymbols:
-                        context.CSharpIndexedProjectRootCompatible
-                        && !context.Options.Rebuild
-                        && !context.StartedWithNoIndexedFiles,
-                    canReuseExistingSymbolsWithoutRead:
-                        priorPositiveCSharpSourceNoOpCandidate
-                            ? null
-                            : canReuseCSharpPrepassTargetWithoutRead,
-                    reportCandidateFile: (candidateIndex, path) =>
-                        SetActiveCSharpPrepassPath(
-                            activeCSharpWorkspaceFiles,
-                            candidateIndex,
-                            path),
-                    parallelism: context.ExtractionParallelism,
-                    excludedExistingFileIds:
-                        context.StaleFilePurgePlan.FileIds,
-                    isExistingSymbolPathExcluded:
-                        context
-                            .IsExistingCSharpSymbolPathNowNonCSharp,
-                    patternConfigsAlreadyLoaded: true,
-                    cancellationToken: context.CancellationToken,
-                    symbolArtifactCache: symbolArtifactCache),
-                context.CancellationToken);
-        }
-        catch (OperationCanceledException) when (
-            context.CancellationToken.IsCancellationRequested)
-        {
-            throw new IndexInterruptedException(
-                0,
-                context.FilesCount,
-                context.ActualMode);
+            foreach (var path in incompletePaths.Take(PartialIndexFileErrorLimit))
+            {
+                RecordCSharpWorkspaceFailure(
+                    path,
+                    "csharp_prepass",
+                    new IOException(
+                        "C# static-interface workspace preflight could not read this source file."));
+            }
         }
-        finally
+
+        private void RecordCSharpWorkspaceFailure(
+            string path,
+            string phase,
+            Exception exception)
         {
-            Array.Clear(activeCSharpWorkspaceFiles);
-            StopFullScanJsonPhaseHeartbeat(heartbeat);
+            var diagnostics = State.Diagnostics;
+            path = string.IsNullOrWhiteSpace(path) ? "<csharp_workspace>" : path;
+            if (!diagnostics.ReportedCSharpWorkspaceFailures.Add(
+                    $"{phase}\n{path}"))
+            {
+                return;
+            }
+
+            diagnostics.Errors++;
+            diagnostics.ErrorList.Add(
+                new CliJsonMessage(path, FormatIndexFileException(exception)));
+            if (diagnostics.FileErrorList.Count < PartialIndexFileErrorLimit)
+            {
+                diagnostics.FileErrorList.Add(
+                    BuildIndexFileError(path, phase, exception));
+            }
         }
     }
 }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteSession.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteSession.cs
new file mode 100644
index 000000000..8e923778f
--- /dev/null
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteSession.cs
@@ -0,0 +1,120 @@
+using CodeIndex.Database;
+using CodeIndex.Indexer;
+
+namespace CodeIndex.Cli;
+
+public static partial class IndexCommandRunner
+{
+    private sealed partial class FullScanPreWriteSession(
+        FullScanPreWriteRequest request,
+        FullScanPreWriteState state)
+    {
+        internal FullScanPreWriteRequest Request { get; } = request;
+        internal FullScanPreWriteState State { get; } = state;
+    }
+
+    private readonly record struct FullScanPreWriteRequest(
+        FullScanPreWriteCore Core,
+        FullScanPreWriteBaseline Baseline,
+        FullScanPreWriteContracts Contracts,
+        FullScanPreWriteRuntime Runtime,
+        FullScanPreWriteReusePolicy Reuse);
+
+    private readonly record struct FullScanPreWriteCore(
+        DbWriter Writer,
+        FileIndexer Indexer,
+        IndexCommandOptions Options,
+        string ProjectRoot);
+
+    private readonly record struct FullScanPreWriteBaseline(
+        bool PriorIndexComplete,
+        int PriorReadiness,
+        bool PriorSymbolsOnlyGraphOmitted,
+        bool? PriorCSharpStaticInterfaceSourceEvidence,
+        bool StartedWithNoIndexedFiles,
+        bool ScanHadErrors,
+        bool ProjectRootWritten);
+
+    private readonly record struct FullScanPreWriteContracts(
+        bool SymbolKindFilterMatchesPrior,
+        bool CSharpSymbolNameContractMatchesCurrent,
+        bool CSharpIndexedProjectRootCompatible,
+        bool CSharpHotspotTrustMatchesCurrent,
+        bool RequiresConservativeCSharpSourceRefresh,
+        bool ForceExtractorRefresh);
+
+    private readonly record struct FullScanPreWriteRuntime(
+        FullScanFileTarget[] FileTargets,
+        IReadOnlyList<CSharpStaticInterfacePrepass.FileTarget> CSharpPrepassTargets,
+        IReadOnlyDictionary<string, string> FileLanguages,
+        int CSharpPrepassCapacity,
+        int ExtractionParallelism,
+        int FilesCount,
+        string ActualMode,
+        CancellationToken CancellationToken);
+
+    private readonly record struct FullScanPreWriteReusePolicy(
+        bool CanSkipTargetsBeforeContentLoad,
+        bool SqlGraphContractMatchesCurrent,
+        bool HdlGraphContractMatchesCurrent,
+        IReadOnlyDictionary<string, bool> HotspotFamilyTrustMatchesCurrent,
+        bool JavaScriptTypeScriptRefreshRequired);
+
+    private sealed class FullScanPreWriteState
+    {
+        internal required FullScanPreWriteMutableScanState Scan { get; init; }
+        internal required FullScanPreWriteCSharpState CSharp { get; init; }
+        internal required FullScanPreWriteSelectionState Selection { get; init; }
+        internal required FullScanPreWriteDiagnosticsState Diagnostics { get; init; }
+    }
+
+    private sealed class FullScanPreWriteMutableScanState
+    {
+        internal required FilePurgePlan StaleFilePurgePlan { get; set; }
+        internal bool DeferCSharpMutationsForIncompleteScan { get; set; }
+        internal int Purged { get; set; }
+        internal bool FtsMutated { get; set; }
+        internal bool HadCSharpStaticInterfaceContractsBeforePurge { get; set; }
+    }
+
+    private sealed class FullScanPreWriteCSharpState
+    {
+        internal ReusableIndexedFileStatsSnapshot? ReusableIndexedFileStats { get; set; }
+        internal Dictionary<string, IndexedFileStatReuseResult?>? CSharpPrepassStatReuse { get; set; }
+        internal Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
+            WorkspaceFileSnapshots
+        { get; set; }
+        internal CSharpStaticInterfaceWorkspaceSymbols Workspace { get; set; } =
+            null!;
+        internal CSharpPrepassSymbolArtifactCache? PrepassSymbolArtifacts { get; set; }
+        internal bool ForceFullRefreshFromInvalidatedNoOp { get; set; }
+        internal bool PreservePriorPositiveSourceNoOp { get; set; }
+        internal FullScanPreWriteCSharpEvidence Evidence { get; } = new();
+    }
+
+    private sealed class FullScanPreWriteCSharpEvidence
+    {
+        internal bool ForStamp { get; set; }
+        internal bool Complete { get; set; }
+    }
+
+    private sealed class FullScanPreWriteSelectionState
+    {
+        internal List<int>? ExtractionFileIndexes { get; set; }
+        internal int ExtractionWorkItemCount { get; set; }
+        internal int Processed { get; set; }
+        internal int Skipped { get; set; }
+        internal required ReadableFileByteTracker ReadableFileBytes { get; init; }
+        internal HashSet<string>? ReusedHotspotFamilyLanguages { get; set; }
+        internal HashSet<string>? SkippedSymbolExtractorLanguages { get; set; }
+        internal bool UseFtsBulkLoad { get; set; }
+    }
+
+    private sealed class FullScanPreWriteDiagnosticsState
+    {
+        internal required List<CliJsonMessage> ErrorList { get; init; }
+        internal required List<StatusIndexFileError> FileErrorList { get; init; }
+        internal required HashSet<string> ReportedCSharpWorkspaceFailures { get; init; }
+        internal int Errors { get; set; }
+    }
+}
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteValidation.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteValidation.cs
new file mode 100644
index 000000000..5964483dd
--- /dev/null
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteValidation.cs
@@ -0,0 +1,130 @@
+using CodeIndex.Indexer;
+
+namespace CodeIndex.Cli;
+
+public static partial class IndexCommandRunner
+{
+    private readonly record struct FullScanPreWriteInputValidationResult(
+        bool IsValid,
+        string ChangedPath);
+
+    private sealed partial class FullScanPreWriteSession
+    {
+        internal FullScanPreWriteInputValidationResult PrepareWriteBoundary(
+            FileIndexer.ScanInputSnapshot? inputSnapshot)
+        {
+            PrepareExtractionTargets();
+            DecideFtsBulkLoad();
+            RevalidateFinalCSharpNoOp();
+            var inputValidation =
+                ValidateBeforeWriteScanInput(inputSnapshot);
+            if (inputValidation.IsValid)
+                ValidateBeforeWriteCSharpFileSnapshots();
+            return inputValidation;
+        }
+
+        internal FullScanPreWriteInputValidationResult
+            ValidateBeforeWriteScanInput(
+                FileIndexer.ScanInputSnapshot? inputSnapshot)
+        {
+            if (inputSnapshot == null)
+                return new(true, string.Empty);
+
+            FullScanInputSnapshotBarrierForTesting?.Invoke("before_write");
+            var isValid = Request.Core.Indexer.TryValidateScanInputSnapshot(
+                inputSnapshot,
+                out var changedPath,
+                Request.Runtime.CancellationToken);
+            return new(isValid, changedPath);
+        }
+
+        internal void ValidateBeforeWriteCSharpFileSnapshots()
+        {
+            var options = Request.Core.Options;
+            var scan = State.Scan;
+            if (options.SymbolsOnly
+                || scan.DeferCSharpMutationsForIncompleteScan)
+            {
+                return;
+            }
+
+            var csharp = State.CSharp;
+            var changedFilePath = string.Empty;
+            var stableFiles = csharp.WorkspaceFileSnapshots == null
+                || CSharpStaticInterfacePrepass.TryValidateFileStatSnapshots(
+                    Request.Runtime.CSharpPrepassTargets,
+                    csharp.WorkspaceFileSnapshots,
+                    out changedFilePath,
+                    Request.Runtime.CancellationToken);
+            if (stableFiles)
+                return;
+
+            csharp.PrepassSymbolArtifacts?.Clear();
+            csharp.PrepassSymbolArtifacts = null;
+            var driftPath = FormatCSharpWorkspaceSnapshotPath(
+                Request.Core.ProjectRoot,
+                changedFilePath);
+            var incompleteWorkspace =
+                new CSharpStaticInterfaceWorkspaceSymbols(
+                    [],
+                    HasStaticInterfaceContracts: true,
+                    SourceContractEvidenceComplete: false,
+                    IncompleteSourcePaths: [driftPath]);
+            DeferCSharpMutationsForIncompleteWorkspace(incompleteWorkspace);
+            csharp.PreservePriorPositiveSourceNoOp = false;
+            csharp.Evidence.ForStamp = false;
+            csharp.Evidence.Complete = false;
+            csharp.WorkspaceFileSnapshots = null;
+            csharp.Workspace = incompleteWorkspace;
+            State.Selection.UseFtsBulkLoad = false;
+
+            DeferCSharpExtractionTargets();
+        }
+
+        private void DeferCSharpExtractionTargets()
+        {
+            var fileTargets = Request.Runtime.FileTargets;
+            var selection = State.Selection;
+            var deferredCSharpIndexes =
+                new List<int>(Request.Runtime.CSharpPrepassTargets.Count);
+            if (selection.ExtractionFileIndexes == null)
+            {
+                selection.ExtractionFileIndexes =
+                    new List<int>(fileTargets.Length);
+                for (var fileIndex = 0;
+                     fileIndex < fileTargets.Length;
+                     fileIndex++)
+                {
+                    if (fileTargets[fileIndex].Language == "csharp")
+                        deferredCSharpIndexes.Add(fileIndex);
+                    else
+                        selection.ExtractionFileIndexes.Add(fileIndex);
+                }
+            }
+            else
+            {
+                for (var extractionIndex =
+                         selection.ExtractionFileIndexes.Count - 1;
+                     extractionIndex >= 0;
+                     extractionIndex--)
+                {
+                    var fileIndex =
+                        selection.ExtractionFileIndexes[extractionIndex];
+                    if (fileTargets[fileIndex].Language != "csharp")
+                        continue;
+
+                    deferredCSharpIndexes.Add(fileIndex);
+                    selection.ExtractionFileIndexes.RemoveAt(
+                        extractionIndex);
+                }
+            }
+
+            foreach (var fileIndex in deferredCSharpIndexes)
+                RecordDeferredFullScanCSharpTarget(fileIndex);
+
+            selection.ExtractionFileIndexes.Sort();
+            selection.ExtractionWorkItemCount =
+                selection.ExtractionFileIndexes.Count;
+        }
+    }
+}
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.TargetSelection.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.TargetSelection.cs
index 8d8f8f105..8124f34ff 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.TargetSelection.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.TargetSelection.cs
@@ -5,399 +5,375 @@ namespace CodeIndex.Cli;
 
 public static partial class IndexCommandRunner
 {
-    private sealed class FullScanTargetSelectionContext
+    private sealed partial class FullScanPreWriteSession
     {
-        internal required DbWriter Writer { get; init; }
-        internal required FileIndexer Indexer { get; init; }
-        internal required IndexCommandOptions Options { get; init; }
-        internal required string ProjectRoot { get; init; }
-        internal required FullScanFileTarget[] FileTargets { get; init; }
-        internal required IReadOnlyList<CSharpStaticInterfacePrepass.FileTarget>
-            CSharpPrepassTargets
-        { get; init; }
-        internal required FilePurgePlan StaleFilePurgePlan { get; init; }
-        internal required bool CanSkipTargetsBeforeContentLoad { get; init; }
-        internal required bool StartedWithNoIndexedFiles { get; init; }
-        internal required bool CSharpIndexedProjectRootCompatible
+        internal void PrepareExtractionTargets()
         {
-            get;
-            init;
-        }
-
-        internal required int ExtractionParallelism { get; init; }
-        internal required bool? PriorCSharpStaticInterfaceSourceEvidence
-        {
-            get;
-            init;
-        }
-
-        internal required CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace
-        {
-            get;
-            init;
-        }
-
-        internal Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
-            CSharpWorkspaceFileSnapshots
-        { get; init; }
-        internal required bool ForceFullCSharpRefreshFromInvalidatedNoOp
-        {
-            get;
-            init;
+            ThrowIfFullScanCancelled();
+            var selection = State.Selection;
+            if (Request.Reuse.CanSkipTargetsBeforeContentLoad)
+            {
+                SelectReusableFullScanTargets();
+            }
+            else if (State.Scan.DeferCSharpMutationsForIncompleteScan)
+            {
+                SelectFullScanTargetsWithDeferredCSharp();
+            }
+            else
+            {
+                selection.ExtractionWorkItemCount =
+                    Request.Runtime.FileTargets.Length;
+            }
         }
 
-        internal required bool PreservePriorPositiveCSharpSourceNoOp
+        private void SelectReusableFullScanTargets()
         {
-            get;
-            init;
-        }
+            var fileTargets = Request.Runtime.FileTargets;
+            var statPreflightMatched = new bool[fileTargets.Length];
+            var csharpNoOpHasInterveningWork =
+                State.Scan.StaleFilePurgePlan.Count > 0;
+            for (var fileIndex = 0;
+                 fileIndex < fileTargets.Length;
+                 fileIndex++)
+            {
+                ThrowIfFullScanCancelled();
+                if (State.Scan.DeferCSharpMutationsForIncompleteScan
+                    && fileTargets[fileIndex].Language == "csharp")
+                {
+                    continue;
+                }
+
+                statPreflightMatched[fileIndex] =
+                    GetFullScanTargetStatMatch(fileIndex, true) != null;
+                if (!statPreflightMatched[fileIndex])
+                    csharpNoOpHasInterveningWork = true;
+            }
 
-        internal required bool CSharpSourceEvidenceForStamp { get; init; }
-        internal required bool CSharpSourceEvidenceComplete { get; init; }
-        internal required CancellationToken CancellationToken { get; init; }
-        internal required Action ThrowIfFullScanCancelled { get; init; }
-        internal required Func<bool>
-            GetDeferCSharpMutationsForIncompleteScan
-        { get; init; }
-        internal required Func<int, bool, IndexedFileStatReuseResult?>
-            GetFullScanTargetStatMatch
-        { get; init; }
-        internal required Action<int, IndexedFileStatReuseResult>
-            RecordFullScanTargetStatSkip
-        { get; init; }
-        internal required Action<CSharpStaticInterfaceWorkspaceSymbols>
-            DeferCSharpMutationsForIncompleteWorkspace
-        { get; init; }
-        internal required Func<string, bool>
-            IsExistingCSharpSymbolPathNowNonCSharp
-        { get; init; }
-    }
+            var revalidatedMatches =
+                new IndexedFileStatReuseResult?[fileTargets.Length];
+            RevalidateNonCSharpFullScanTargets(
+                statPreflightMatched,
+                revalidatedMatches,
+                ref csharpNoOpHasInterveningWork);
+            var preservedCSharpNoOpInvalidated =
+                RevalidateCSharpFullScanTargets(
+                    statPreflightMatched,
+                    revalidatedMatches,
+                    csharpNoOpHasInterveningWork);
+            if (preservedCSharpNoOpInvalidated)
+                RebuildInvalidatedFullScanCSharpNoOp(revalidatedMatches);
+
+            var selection = State.Selection;
+            selection.ExtractionFileIndexes =
+                new List<int>(fileTargets.Length);
+            for (var fileIndex = 0;
+                 fileIndex < fileTargets.Length;
+                 fileIndex++)
+            {
+                ThrowIfFullScanCancelled();
+                if (State.Scan.DeferCSharpMutationsForIncompleteScan
+                    && fileTargets[fileIndex].Language == "csharp")
+                {
+                    RecordDeferredFullScanCSharpTarget(fileIndex);
+                    continue;
+                }
+
+                var revalidated = revalidatedMatches[fileIndex];
+                if (revalidated != null)
+                {
+                    RecordFullScanTargetStatSkip(
+                        fileIndex,
+                        revalidated.Value);
+                }
+                else
+                {
+                    selection.ExtractionFileIndexes.Add(fileIndex);
+                }
+            }
 
-    private sealed class FullScanTargetSelectionState
-    {
-        internal List<int>? ExtractionFileIndexes { get; set; }
-        internal int ExtractionWorkItemCount { get; set; }
-        internal required CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace
-        {
-            get;
-            set;
+            selection.ExtractionWorkItemCount =
+                selection.ExtractionFileIndexes.Count;
         }
 
-        internal Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
-            CSharpWorkspaceFileSnapshots
-        { get; set; }
-        internal bool ForceFullCSharpRefreshFromInvalidatedNoOp { get; set; }
-        internal bool PreservePriorPositiveCSharpSourceNoOp { get; set; }
-        internal bool CSharpSourceEvidenceForStamp { get; set; }
-        internal bool CSharpSourceEvidenceComplete { get; set; }
-    }
-
-    private sealed record FullScanTargetSelectionResult(
-        List<int>? ExtractionFileIndexes,
-        int ExtractionWorkItemCount,
-        CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace,
-        Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
-            CSharpWorkspaceFileSnapshots,
-        bool ForceFullCSharpRefreshFromInvalidatedNoOp,
-        bool PreservePriorPositiveCSharpSourceNoOp,
-        bool CSharpSourceEvidenceForStamp,
-        bool CSharpSourceEvidenceComplete);
-
-    private static FullScanTargetSelectionResult
-        PrepareFullScanExtractionTargets(
-            FullScanTargetSelectionContext context)
-    {
-        context.ThrowIfFullScanCancelled();
-        var state = new FullScanTargetSelectionState
-        {
-            CSharpWorkspace = context.CSharpWorkspace,
-            CSharpWorkspaceFileSnapshots =
-                context.CSharpWorkspaceFileSnapshots,
-            ForceFullCSharpRefreshFromInvalidatedNoOp =
-                context.ForceFullCSharpRefreshFromInvalidatedNoOp,
-            PreservePriorPositiveCSharpSourceNoOp =
-                context.PreservePriorPositiveCSharpSourceNoOp,
-            CSharpSourceEvidenceForStamp =
-                context.CSharpSourceEvidenceForStamp,
-            CSharpSourceEvidenceComplete =
-                context.CSharpSourceEvidenceComplete,
-        };
-
-        if (context.CanSkipTargetsBeforeContentLoad)
-        {
-            SelectReusableFullScanTargets(context, state);
-        }
-        else if (context.GetDeferCSharpMutationsForIncompleteScan())
-        {
-            SelectFullScanTargetsWithDeferredCSharp(context, state);
-        }
-        else
+        private void RevalidateNonCSharpFullScanTargets(
+            IReadOnlyList<bool> statPreflightMatched,
+            IList<IndexedFileStatReuseResult?> revalidatedMatches,
+            ref bool csharpNoOpHasInterveningWork)
         {
-            state.ExtractionWorkItemCount = context.FileTargets.Length;
+            var fileTargets = Request.Runtime.FileTargets;
+            for (var fileIndex = 0;
+                 fileIndex < fileTargets.Length;
+                 fileIndex++)
+            {
+                ThrowIfFullScanCancelled();
+                if (fileTargets[fileIndex].Language == "csharp")
+                    continue;
+
+                var revalidated = statPreflightMatched[fileIndex]
+                    ? GetFullScanTargetStatMatch(fileIndex, false)
+                    : null;
+                revalidatedMatches[fileIndex] = revalidated;
+                if (revalidated == null)
+                    csharpNoOpHasInterveningWork = true;
+            }
         }
 
-        return new FullScanTargetSelectionResult(
-            state.ExtractionFileIndexes,
-            state.ExtractionWorkItemCount,
-            state.CSharpWorkspace,
-            state.CSharpWorkspaceFileSnapshots,
-            state.ForceFullCSharpRefreshFromInvalidatedNoOp,
-            state.PreservePriorPositiveCSharpSourceNoOp,
-            state.CSharpSourceEvidenceForStamp,
-            state.CSharpSourceEvidenceComplete);
-    }
-
-    private static void SelectReusableFullScanTargets(
-        FullScanTargetSelectionContext context,
-        FullScanTargetSelectionState state)
-    {
-        var fileTargets = context.FileTargets;
-        var statPreflightMatched = new bool[fileTargets.Length];
-        var csharpNoOpHasInterveningWork =
-            context.StaleFilePurgePlan.Count > 0;
-        for (var fileIndex = 0; fileIndex < fileTargets.Length; fileIndex++)
+        private bool RevalidateCSharpFullScanTargets(
+            IReadOnlyList<bool> statPreflightMatched,
+            IList<IndexedFileStatReuseResult?> revalidatedMatches,
+            bool csharpNoOpHasInterveningWork)
         {
-            context.ThrowIfFullScanCancelled();
-            if (context.GetDeferCSharpMutationsForIncompleteScan()
-                && fileTargets[fileIndex].Language == "csharp")
+            var fileTargets = Request.Runtime.FileTargets;
+            var csharp = State.CSharp;
+            var preservedCSharpNoOpInvalidated = false;
+            for (var fileIndex = 0;
+                 fileIndex < fileTargets.Length;
+                 fileIndex++)
             {
-                continue;
+                ThrowIfFullScanCancelled();
+                if (fileTargets[fileIndex].Language != "csharp"
+                    || State.Scan.DeferCSharpMutationsForIncompleteScan)
+                {
+                    continue;
+                }
+
+                var revalidated = statPreflightMatched[fileIndex]
+                    ? GetFullScanTargetStatMatch(
+                        fileIndex,
+                        csharp.PreservePriorPositiveSourceNoOp
+                        && !csharpNoOpHasInterveningWork)
+                    : null;
+                revalidatedMatches[fileIndex] = revalidated;
+                if (csharp.PreservePriorPositiveSourceNoOp
+                    && revalidated == null)
+                {
+                    preservedCSharpNoOpInvalidated = true;
+                }
             }
 
-            statPreflightMatched[fileIndex] =
-                context.GetFullScanTargetStatMatch(
-                    fileIndex,
-                    true) != null;
-            if (!statPreflightMatched[fileIndex])
-                csharpNoOpHasInterveningWork = true;
-        }
-
-        var revalidatedMatches =
-            new IndexedFileStatReuseResult?[fileTargets.Length];
-        RevalidateNonCSharpFullScanTargets(
-            context,
-            statPreflightMatched,
-            revalidatedMatches,
-            ref csharpNoOpHasInterveningWork);
-        var preservedCSharpNoOpInvalidated =
-            RevalidateCSharpFullScanTargets(
-                context,
-                state,
-                statPreflightMatched,
-                revalidatedMatches,
-                csharpNoOpHasInterveningWork);
-        if (preservedCSharpNoOpInvalidated)
-        {
-            RebuildInvalidatedFullScanCSharpNoOp(
-                context,
-                state,
-                revalidatedMatches);
+            return preservedCSharpNoOpInvalidated;
         }
 
-        state.ExtractionFileIndexes =
-            new List<int>(fileTargets.Length);
-        for (var fileIndex = 0; fileIndex < fileTargets.Length; fileIndex++)
+        private void RebuildInvalidatedFullScanCSharpNoOp(
+            IList<IndexedFileStatReuseResult?> revalidatedMatches)
         {
-            context.ThrowIfFullScanCancelled();
-            if (context.GetDeferCSharpMutationsForIncompleteScan()
-                && fileTargets[fileIndex].Language == "csharp")
+            var request = Request;
+            var core = request.Core;
+            var baseline = request.Baseline;
+            var contracts = request.Contracts;
+            var runtime = request.Runtime;
+            var scan = State.Scan;
+            var csharp = State.CSharp;
+            csharp.Workspace = BuildStableFullScanCSharpWorkspace(
+                core.ProjectRoot,
+                runtime.CSharpPrepassTargets,
+                out var workspaceFileSnapshots,
+                () => CSharpStaticInterfacePrepass.BuildWorkspaceSymbols(
+                    core.Writer,
+                    core.Indexer,
+                    runtime.CSharpPrepassTargets,
+                    includeExistingSymbols:
+                        contracts.CSharpIndexedProjectRootCompatible
+                        && !core.Options.Rebuild
+                        && !baseline.StartedWithNoIndexedFiles,
+                    canReuseExistingSymbolsWithoutRead: null,
+                    parallelism: runtime.ExtractionParallelism,
+                    excludedExistingFileIds:
+                        scan.StaleFilePurgePlan.FileIds,
+                    isExistingSymbolPathExcluded:
+                        IsExistingCSharpSymbolPathNowNonCSharp,
+                    patternConfigsAlreadyLoaded: true,
+                    cancellationToken: runtime.CancellationToken),
+                runtime.CancellationToken);
+            csharp.WorkspaceFileSnapshots = workspaceFileSnapshots;
+            csharp.PreservePriorPositiveSourceNoOp = false;
+            if (!csharp.Workspace.SourceContractEvidenceComplete)
             {
-                RecordDeferredFullScanCSharpTarget(context, fileIndex);
-                continue;
+                var incompleteSourcePaths =
+                    csharp.Workspace.IncompleteSourcePaths;
+                DeferCSharpMutationsForIncompleteWorkspace(csharp.Workspace);
+                csharp.Evidence.ForStamp = false;
+                csharp.Evidence.Complete = false;
+                csharp.Workspace =
+                    new CSharpStaticInterfaceWorkspaceSymbols(
+                        [],
+                        false,
+                        SourceContractEvidenceComplete: false,
+                        IncompleteSourcePaths: incompleteSourcePaths);
+                return;
             }
 
-            var revalidated = revalidatedMatches[fileIndex];
-            if (revalidated != null)
+            var requiresFullCSharpRefresh =
+                baseline.PriorCSharpStaticInterfaceSourceEvidence == true
+                || csharp.Workspace.HasStaticInterfaceContracts
+                || csharp.Workspace.RequiresMemberReadReferenceRefresh;
+            csharp.ForceFullRefreshFromInvalidatedNoOp =
+                requiresFullCSharpRefresh;
+            csharp.Evidence.ForStamp =
+                csharp.Workspace.HasSourceStaticInterfaceContracts;
+            csharp.Evidence.Complete = true;
+            if (!requiresFullCSharpRefresh)
+                return;
+
+            csharp.Workspace = csharp.Workspace with
             {
-                context.RecordFullScanTargetStatSkip(
-                    fileIndex,
-                    revalidated.Value);
-            }
-            else
+                HasStaticInterfaceContracts = true,
+            };
+            for (var fileIndex = 0;
+                 fileIndex < runtime.FileTargets.Length;
+                 fileIndex++)
             {
-                state.ExtractionFileIndexes.Add(fileIndex);
+                if (runtime.FileTargets[fileIndex].Language == "csharp")
+                    revalidatedMatches[fileIndex] = null;
             }
         }
 
-        state.ExtractionWorkItemCount =
-            state.ExtractionFileIndexes.Count;
-    }
-
-    private static void RevalidateNonCSharpFullScanTargets(
-        FullScanTargetSelectionContext context,
-        IReadOnlyList<bool> statPreflightMatched,
-        IList<IndexedFileStatReuseResult?> revalidatedMatches,
-        ref bool csharpNoOpHasInterveningWork)
-    {
-        for (var fileIndex = 0;
-             fileIndex < context.FileTargets.Length;
-             fileIndex++)
+        private void SelectFullScanTargetsWithDeferredCSharp()
         {
-            context.ThrowIfFullScanCancelled();
-            if (context.FileTargets[fileIndex].Language == "csharp")
-                continue;
+            var fileTargets = Request.Runtime.FileTargets;
+            var selection = State.Selection;
+            selection.ExtractionFileIndexes =
+                new List<int>(fileTargets.Length);
+            for (var fileIndex = 0;
+                 fileIndex < fileTargets.Length;
+                 fileIndex++)
+            {
+                if (fileTargets[fileIndex].Language != "csharp")
+                {
+                    selection.ExtractionFileIndexes.Add(fileIndex);
+                    continue;
+                }
 
-            var revalidated = statPreflightMatched[fileIndex]
-                ? context.GetFullScanTargetStatMatch(fileIndex, false)
-                : null;
-            revalidatedMatches[fileIndex] = revalidated;
-            if (revalidated == null)
-                csharpNoOpHasInterveningWork = true;
+                RecordDeferredFullScanCSharpTarget(fileIndex);
+            }
+
+            selection.ExtractionWorkItemCount =
+                selection.ExtractionFileIndexes.Count;
         }
-    }
 
-    private static bool RevalidateCSharpFullScanTargets(
-        FullScanTargetSelectionContext context,
-        FullScanTargetSelectionState state,
-        IReadOnlyList<bool> statPreflightMatched,
-        IList<IndexedFileStatReuseResult?> revalidatedMatches,
-        bool csharpNoOpHasInterveningWork)
-    {
-        var preservedCSharpNoOpInvalidated = false;
-        for (var fileIndex = 0;
-             fileIndex < context.FileTargets.Length;
-             fileIndex++)
+        private void RecordDeferredFullScanCSharpTarget(int fileIndex)
         {
-            context.ThrowIfFullScanCancelled();
-            if (context.FileTargets[fileIndex].Language != "csharp"
-                || context.GetDeferCSharpMutationsForIncompleteScan())
+            long currentSize = 0;
+            try
             {
-                continue;
+                var info = new FileInfo(
+                    Request.Runtime.FileTargets[fileIndex].FilePath);
+                if (info.Exists && info.Length >= 0)
+                    currentSize = info.Length;
             }
-
-            var revalidated = statPreflightMatched[fileIndex]
-                ? context.GetFullScanTargetStatMatch(
-                    fileIndex,
-                    state.PreservePriorPositiveCSharpSourceNoOp
-                    && !csharpNoOpHasInterveningWork)
-                : null;
-            revalidatedMatches[fileIndex] = revalidated;
-            if (state.PreservePriorPositiveCSharpSourceNoOp
-                && revalidated == null)
+            catch (Exception ex) when (
+                ex is IOException
+                    or UnauthorizedAccessException
+                    or NotSupportedException
+                    or ArgumentException)
             {
-                preservedCSharpNoOpInvalidated = true;
             }
-        }
-
-        return preservedCSharpNoOpInvalidated;
-    }
 
-    private static void RebuildInvalidatedFullScanCSharpNoOp(
-        FullScanTargetSelectionContext context,
-        FullScanTargetSelectionState state,
-        IList<IndexedFileStatReuseResult?> revalidatedMatches)
-    {
-        state.CSharpWorkspace = BuildStableFullScanCSharpWorkspace(
-            context.ProjectRoot,
-            context.CSharpPrepassTargets,
-            out var workspaceFileSnapshots,
-            () => CSharpStaticInterfacePrepass.BuildWorkspaceSymbols(
-                context.Writer,
-                context.Indexer,
-                context.CSharpPrepassTargets,
-                includeExistingSymbols:
-                    context.CSharpIndexedProjectRootCompatible
-                    && !context.Options.Rebuild
-                    && !context.StartedWithNoIndexedFiles,
-                canReuseExistingSymbolsWithoutRead: null,
-                parallelism: context.ExtractionParallelism,
-                excludedExistingFileIds:
-                    context.StaleFilePurgePlan.FileIds,
-                isExistingSymbolPathExcluded:
-                    context.IsExistingCSharpSymbolPathNowNonCSharp,
-                patternConfigsAlreadyLoaded: true,
-                cancellationToken: context.CancellationToken),
-            context.CancellationToken);
-        state.CSharpWorkspaceFileSnapshots = workspaceFileSnapshots;
-        state.PreservePriorPositiveCSharpSourceNoOp = false;
-        if (!state.CSharpWorkspace.SourceContractEvidenceComplete)
-        {
-            var incompleteSourcePaths =
-                state.CSharpWorkspace.IncompleteSourcePaths;
-            context.DeferCSharpMutationsForIncompleteWorkspace(
-                state.CSharpWorkspace);
-            state.CSharpSourceEvidenceForStamp = false;
-            state.CSharpSourceEvidenceComplete = false;
-            state.CSharpWorkspace =
-                new CSharpStaticInterfaceWorkspaceSymbols(
-                    [],
-                    false,
-                    SourceContractEvidenceComplete: false,
-                    IncompleteSourcePaths: incompleteSourcePaths);
-            return;
+            RecordFullScanTargetStatSkip(
+                fileIndex,
+                new IndexedFileStatReuseResult(0, currentSize));
         }
 
-        var requiresFullCSharpRefresh =
-            context.PriorCSharpStaticInterfaceSourceEvidence == true
-            || state.CSharpWorkspace.HasStaticInterfaceContracts
-            || state.CSharpWorkspace
-                .RequiresMemberReadReferenceRefresh;
-        state.ForceFullCSharpRefreshFromInvalidatedNoOp =
-            requiresFullCSharpRefresh;
-        state.CSharpSourceEvidenceForStamp =
-            state.CSharpWorkspace.HasSourceStaticInterfaceContracts;
-        state.CSharpSourceEvidenceComplete = true;
-        if (!requiresFullCSharpRefresh)
-            return;
-
-        state.CSharpWorkspace = state.CSharpWorkspace with
+        private IndexedFileStatReuseResult? GetFullScanTargetStatMatch(
+            int fileIndex,
+            bool allowCSharpPrepassCache)
         {
-            HasStaticInterfaceContracts = true,
-        };
-        for (var fileIndex = 0;
-             fileIndex < context.FileTargets.Length;
-             fileIndex++)
-        {
-            if (context.FileTargets[fileIndex].Language == "csharp")
-                revalidatedMatches[fileIndex] = null;
+            var request = Request;
+            var core = request.Core;
+            var baseline = request.Baseline;
+            var contracts = request.Contracts;
+            var reuse = request.Reuse;
+            if (!reuse.CanSkipTargetsBeforeContentLoad)
+                return null;
+
+            var csharp = State.CSharp;
+            var target = request.Runtime.FileTargets[fileIndex];
+            var language = target.Language;
+            var targetRequiresRefresh =
+                reuse.JavaScriptTypeScriptRefreshRequired
+                && (IsJavaScriptTypeScriptLanguage(language)
+                    || IsJavaScriptTypeScriptConfigPath(target.IndexPath));
+            var allowReuse = contracts.SymbolKindFilterMatchesPrior
+                && !targetRequiresRefresh
+                && !baseline.PriorSymbolsOnlyGraphOmitted
+                && (language != "csharp"
+                    || contracts.CSharpIndexedProjectRootCompatible)
+                && (language != "csharp"
+                    || contracts.CSharpSymbolNameContractMatchesCurrent)
+                && (language != "csharp"
+                    || !csharp.Workspace.HasStaticInterfaceContracts)
+                && (language != "sql"
+                    || reuse.SqlGraphContractMatchesCurrent)
+                && (language is not ("verilog" or "systemverilog" or "vhdl")
+                    || reuse.HdlGraphContractMatchesCurrent)
+                && AllowReuseWithCurrentHotspotFamilyTrust(
+                    language,
+                    reuse.HotspotFamilyTrustMatchesCurrent);
+            if (!allowReuse)
+                return null;
+
+            if (allowCSharpPrepassCache
+                && language == "csharp"
+                && csharp.CSharpPrepassStatReuse != null
+                && csharp.CSharpPrepassStatReuse.TryGetValue(
+                    target.IndexPath,
+                    out var cachedCSharpPrepassReuse))
+            {
+                return cachedCSharpPrepassReuse;
+            }
+
+            return IndexedFileStatReuse.TryGetReusableUnchangedFile(
+                csharp.ReusableIndexedFileStats!,
+                target.FilePath,
+                target.IndexPath,
+                language,
+                target.GeneratedExtractionSuppressed);
         }
-    }
 
-    private static void SelectFullScanTargetsWithDeferredCSharp(
-        FullScanTargetSelectionContext context,
-        FullScanTargetSelectionState state)
-    {
-        state.ExtractionFileIndexes =
-            new List<int>(context.FileTargets.Length);
-        for (var fileIndex = 0;
-             fileIndex < context.FileTargets.Length;
-             fileIndex++)
+        private void RecordFullScanTargetStatSkip(
+            int fileIndex,
+            IndexedFileStatReuseResult existingFile)
         {
-            if (context.FileTargets[fileIndex].Language != "csharp")
+            var runtime = Request.Runtime;
+            var options = Request.Core.Options;
+            var selection = State.Selection;
+            var target = runtime.FileTargets[fileIndex];
+            var language = target.Language;
+            selection.Skipped++;
+            selection.Processed++;
+            selection.ReadableFileBytes.Remember(fileIndex, existingFile.Size);
+            if (!string.IsNullOrWhiteSpace(language))
             {
-                state.ExtractionFileIndexes.Add(fileIndex);
-                continue;
+                selection.SkippedSymbolExtractorLanguages ??=
+                    new HashSet<string>(StringComparer.Ordinal);
+                selection.SkippedSymbolExtractorLanguages.Add(language);
             }
 
-            RecordDeferredFullScanCSharpTarget(context, fileIndex);
-        }
-
-        state.ExtractionWorkItemCount =
-            state.ExtractionFileIndexes.Count;
-    }
+            if (FileIndexer.SupportsHotspotFamilyMarkerLanguage(language)
+                && language != null)
+            {
+                selection.ReusedHotspotFamilyLanguages ??=
+                    new HashSet<string>(StringComparer.Ordinal);
+                selection.ReusedHotspotFamilyLanguages.Add(language);
+            }
 
-    private static void RecordDeferredFullScanCSharpTarget(
-        FullScanTargetSelectionContext context,
-        int fileIndex)
-    {
-        long currentSize = 0;
-        try
-        {
-            var info = new FileInfo(
-                context.FileTargets[fileIndex].FilePath);
-            if (info.Exists && info.Length >= 0)
-                currentSize = info.Length;
+            if (options.Verbose && !options.Json && !options.Quiet)
+            {
+                CommandOutputWriter.WriteLine(
+                    $"  [SKIP] {target.IndexPath} (unchanged)");
+            }
         }
-        catch (Exception ex) when (
-            ex is IOException
-                or UnauthorizedAccessException
-                or NotSupportedException
-                or ArgumentException)
+
+        private void ThrowIfFullScanCancelled()
         {
+            var runtime = Request.Runtime;
+            if (!runtime.CancellationToken.IsCancellationRequested)
+                return;
+
+            throw new IndexInterruptedException(
+                State.Selection.Processed,
+                runtime.FilesCount,
+                runtime.ActualMode);
         }
-
-        context.RecordFullScanTargetStatSkip(
-            fileIndex,
-            new IndexedFileStatReuseResult(0, currentSize));
     }
 }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs
index b10f8b52b..4c5c00c28 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs
@@ -116,14 +116,6 @@ void WriteProjectRootOnce()
             }
         }
 
-        void ThrowIfFullScanCancelled(int filesProcessed, int? filesTotal)
-        {
-            if (!cancellationToken.IsCancellationRequested)
-                return;
-
-            throw new IndexInterruptedException(filesProcessed, filesTotal, actualMode);
-        }
-
         int? initialScanFileCapacity = options.Rebuild ? null : writer.GetIndexedFileCount();
         var discovery = DiscoverFullScanFiles(
             indexer,
@@ -151,11 +143,24 @@ void ThrowIfFullScanCancelled(int filesProcessed, int? filesTotal)
             csharpPrepassCapacity);
         var fileTargets = targetPreparation.FileTargets;
         var csharpPrepassTargets = targetPreparation.CSharpPrepassTargets;
-        var readableFileBytes = new ReadableFileByteTracker(
-            files.Count,
-            fileIndex => files[fileIndex],
-            projectRoot,
-            indexRunDiagnostics);
+        var preWriteSelection = new FullScanPreWriteSelectionState
+        {
+            ReadableFileBytes = new ReadableFileByteTracker(
+                files.Count,
+                fileIndex => files[fileIndex],
+                projectRoot,
+                indexRunDiagnostics),
+        };
+        void ThrowIfFullScanCancelled(int filesProcessed, int? filesTotal)
+        {
+            if (!cancellationToken.IsCancellationRequested)
+                return;
+
+            throw new IndexInterruptedException(
+                filesProcessed,
+                filesTotal,
+                actualMode);
+        }
         var errorList = discovery.ErrorList;
         var fileErrorList = errorList
             .Take(PartialIndexFileErrorLimit)
@@ -244,7 +249,7 @@ void ThrowIfFullScanCancelled(int filesProcessed, int? filesTotal)
             : null;
         var purgedRefs = 0;
 
-        int processed = 0, skipped = 0, warnings = warningList.Count, errors = errorList.Count;
+        int warnings = warningList.Count, errors = errorList.Count;
         var ftsMutated = purged > 0;
         var symbolsDroppedByKindFilter = 0;
         var mutualRecursionRefreshNeeded = !options.SymbolsOnly
@@ -256,10 +261,8 @@ void ThrowIfFullScanCancelled(int filesProcessed, int? filesTotal)
             "Indexing...",
             spinnerFrames,
             ConsoleUi.TryWriteErrorLine,
-            canResume: () => processed < files.Count && !indexProgressVisible,
+            canResume: () => preWriteSelection.Processed < files.Count && !indexProgressVisible,
             clearProgressLineBeforeWrite: true);
-        HashSet<string>? reusedHotspotFamilyLanguages = null;
-        HashSet<string>? skippedSymbolExtractorLanguages = null;
         var indexedSymbolExtractorLanguages = new HashSet<string>(languageCounts.Count, StringComparer.Ordinal);
         string? currentJsonIndexFile = null;
         ActiveExtractionPhase?[] activeExtractionPhases = [];
@@ -267,7 +270,7 @@ void ThrowIfFullScanCancelled(int filesProcessed, int? filesTotal)
             options,
             files.Count,
             indexProgress,
-            () => processed,
+            () => preWriteSelection.Processed,
             () => indexProgressVisible,
             () => currentJsonIndexFile,
             () => activeExtractionPhases);
@@ -299,37 +302,6 @@ void RecordCSharpWorkspaceFailure(string path, string phase, Exception exception
                 fileErrorList.Add(BuildIndexFileError(path, phase, exception));
         }
 
-        void DeferCSharpMutationsForIncompleteWorkspace(
-            CSharpStaticInterfaceWorkspaceSymbols workspace)
-        {
-            if (workspace.SourceContractEvidenceComplete)
-                return;
-
-            deferCSharpMutationsForIncompleteScan = true;
-            staleFilePurgePlan = FilePurgePlan.Empty;
-            purged = 0;
-            ftsMutated = false;
-            hadCSharpStaticInterfaceContractsBeforePurge = false;
-
-            var incompletePaths = workspace.IncompleteSourcePaths;
-            if (incompletePaths == null || incompletePaths.Count == 0)
-            {
-                RecordCSharpWorkspaceFailure(
-                    "<csharp_workspace>",
-                    "csharp_prepass",
-                    new IOException("C# static-interface workspace preflight could not read a source file."));
-                return;
-            }
-
-            foreach (var path in incompletePaths.Take(PartialIndexFileErrorLimit))
-            {
-                RecordCSharpWorkspaceFailure(
-                    path,
-                    "csharp_prepass",
-                    new IOException("C# static-interface workspace preflight could not read this source file."));
-            }
-        }
-
         void RequireTypeScriptAugmentationRefresh()
         {
             if (!typeScriptAugmentationReadyCleared)
@@ -379,9 +351,12 @@ bool FullScanJavaScriptTypeScriptConfigChanged()
             return false;
         }
 
-        bool TargetRequiresJavaScriptTypeScriptRefresh(string? language, string indexPath)
+        bool TargetRequiresJavaScriptTypeScriptRefresh(
+            string? language,
+            string indexPath)
             => javaScriptTypeScriptRefreshRequired
-               && (IsJavaScriptTypeScriptLanguage(language) || IsJavaScriptTypeScriptConfigPath(indexPath));
+               && (IsJavaScriptTypeScriptLanguage(language)
+                   || IsJavaScriptTypeScriptConfigPath(indexPath));
 
         void InsertIssuesForIndexedFile(long fileId, IReadOnlyList<FileIssue> issues)
         {
@@ -391,100 +366,77 @@ void InsertIssuesForIndexedFile(long fileId, IReadOnlyList<FileIssue> issues)
                 writer.InsertIssues(fileId, issues);
         }
 
-        bool IsExistingCSharpSymbolPathNowNonCSharp(string indexPath)
+        var preWriteState = new FullScanPreWriteState
         {
-            var currentPath = Path.Combine(
-                projectRoot,
-                FileIndexer.NormalizeRelativePathForCurrentPlatform(indexPath));
-            return scanResult.FileLanguages.TryGetValue(currentPath, out var currentLanguage)
-                && currentLanguage != "csharp";
-        }
-
-        var csharpPreflight = PrepareFullScanCSharpWorkspace(
-            new FullScanCSharpPreflightContext
+            Scan = new FullScanPreWriteMutableScanState
             {
-                Writer = writer,
-                Indexer = indexer,
-                Options = options,
-                ProjectRoot = projectRoot,
-                FileTargets = fileTargets,
-                CSharpPrepassTargets = csharpPrepassTargets,
-                CSharpPrepassCapacity = csharpPrepassCapacity,
+                HadCSharpStaticInterfaceContractsBeforePurge =
+                    hadCSharpStaticInterfaceContractsBeforePurge,
                 StaleFilePurgePlan = staleFilePurgePlan,
-                StartedWithNoIndexedFiles = startedWithNoIndexedFiles,
-                PriorIndexComplete = priorIndexComplete,
-                PriorReadiness = priorReadiness,
-                ScanHadErrors = scanHadErrors,
-                ForceExtractorRefresh = forceExtractorRefresh,
-                PriorSymbolsOnlyGraphOmitted = priorSymbolsOnlyGraphOmitted,
-                SymbolKindFilterMatchesPrior = symbolKindFilterMatchesPrior,
-                CSharpSymbolNameContractMatchesCurrent =
+                DeferCSharpMutationsForIncompleteScan =
+                    deferCSharpMutationsForIncompleteScan,
+                Purged = purged,
+                FtsMutated = ftsMutated,
+            },
+            CSharp = new FullScanPreWriteCSharpState(),
+            Selection = preWriteSelection,
+            Diagnostics = new FullScanPreWriteDiagnosticsState
+            {
+                ErrorList = errorList,
+                FileErrorList = fileErrorList,
+                ReportedCSharpWorkspaceFailures =
+                    reportedCSharpWorkspaceFailures,
+                Errors = errors,
+            },
+        };
+        var preWriteSession = new FullScanPreWriteSession(
+            new FullScanPreWriteRequest(
+                new FullScanPreWriteCore(
+                    writer,
+                    indexer,
+                    options,
+                    projectRoot),
+                new FullScanPreWriteBaseline(
+                    priorIndexComplete,
+                    priorReadiness,
+                    priorSymbolsOnlyGraphOmitted,
+                    priorCSharpStaticInterfaceSourceEvidence,
+                    startedWithNoIndexedFiles,
+                    scanHadErrors,
+                    projectRootWritten),
+                new FullScanPreWriteContracts(
+                    symbolKindFilterMatchesPrior,
                     csharpSymbolNameContractMatchesCurrent,
-                CSharpIndexedProjectRootCompatible =
                     csharpIndexedProjectRootCompatible,
-                CSharpHotspotTrustMatchesCurrent =
                     AllowReuseWithCurrentHotspotFamilyTrust(
                         "csharp",
                         hotspotFamilyTrustMatchesCurrent),
-                RequiresConservativeCSharpSourceRefresh =
                     requiresConservativeCSharpSourceRefresh,
-                HadCSharpStaticInterfaceContractsBeforePurge =
-                    hadCSharpStaticInterfaceContractsBeforePurge,
-                PriorCSharpStaticInterfaceSourceEvidence =
-                    priorCSharpStaticInterfaceSourceEvidence,
-                ProjectRootWritten = projectRootWritten,
-                ExtractionParallelism = extractionParallelism,
-                FilesCount = files.Count,
-                ActualMode = actualMode,
-                CancellationToken = cancellationToken,
-                IsExistingCSharpSymbolPathNowNonCSharp =
-                    IsExistingCSharpSymbolPathNowNonCSharp,
-                GetDeferCSharpMutationsForIncompleteScan =
-                    () => deferCSharpMutationsForIncompleteScan,
-                GetPurged = () => purged,
-                DeferCSharpMutationsForIncompleteWorkspace =
-                    DeferCSharpMutationsForIncompleteWorkspace,
-            });
+                    forceExtractorRefresh),
+                new FullScanPreWriteRuntime(
+                    fileTargets,
+                    csharpPrepassTargets,
+                    scanResult.FileLanguages,
+                    csharpPrepassCapacity,
+                    extractionParallelism,
+                    files.Count,
+                    actualMode,
+                    cancellationToken),
+                new FullScanPreWriteReusePolicy(
+                    CanSkipTargetsBeforeContentLoad:
+                        !forceExtractorRefresh
+                        && !options.Rebuild
+                        && !startedWithNoIndexedFiles
+                        && !options.SymbolsOnly,
+                    sqlGraphContractMatchesCurrent,
+                    hdlGraphContractMatchesCurrent,
+                    hotspotFamilyTrustMatchesCurrent,
+                    javaScriptTypeScriptRefreshRequired)),
+            preWriteState);
+        preWriteSession.PrepareCSharpWorkspace();
+        var csharpPreflight = preWriteState.CSharp;
         var reusableIndexedFileStats =
             csharpPreflight.ReusableIndexedFileStats;
-        var csharpPrepassStatReuse =
-            csharpPreflight.CSharpPrepassStatReuse;
-        var csharpWorkspaceFileSnapshots =
-            csharpPreflight.CSharpWorkspaceFileSnapshots;
-        var csharpWorkspace = csharpPreflight.CSharpWorkspace;
-        var csharpPrepassSymbolArtifacts =
-            csharpPreflight.CSharpPrepassSymbolArtifacts;
-        var forceFullCSharpRefreshFromInvalidatedNoOp =
-            csharpPreflight.ForceFullCSharpRefreshFromInvalidatedNoOp;
-        var preservePriorPositiveCSharpSourceNoOp =
-            csharpPreflight.PreservePriorPositiveCSharpSourceNoOp;
-        var csharpSourceEvidenceForStamp =
-            csharpPreflight.CSharpSourceEvidenceForStamp;
-        var csharpSourceEvidenceComplete =
-            csharpPreflight.CSharpSourceEvidenceComplete;
-
-        void DeferCSharpMutationsForLoadedSnapshotDrift(string path)
-        {
-            csharpPrepassSymbolArtifacts?.Clear();
-            csharpPrepassSymbolArtifacts = null;
-            path = FormatCSharpWorkspaceSnapshotPath(projectRoot, path);
-            deferCSharpMutationsForIncompleteScan = true;
-            preservePriorPositiveCSharpSourceNoOp = false;
-            csharpSourceEvidenceForStamp = false;
-            csharpSourceEvidenceComplete = false;
-            csharpWorkspaceFileSnapshots = null;
-            csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
-                [],
-                HasStaticInterfaceContracts: true,
-                SourceContractEvidenceComplete: false,
-                IncompleteSourcePaths: [path]);
-            writer.SetCSharpStaticInterfaceSourceEvidence(null);
-            RecordCSharpWorkspaceFailure(
-                path,
-                "csharp_workspace_validation",
-                new IOException(
-                    "A C# source changed after workspace preflight; rerun indexing to refresh the complete C# graph."));
-        }
 
         if (options.MemoryTrace)
             memorySamples.Add(CaptureMemorySample("csharp_prepass", stopwatch));
@@ -519,317 +471,82 @@ void CountFreshInsertedRows(
             freshCountReferences += referenceCount;
         }
 
-        var canSkipFullScanTargetsBeforeContentLoad = !forceExtractorRefresh
-            && !options.Rebuild
-            && !startedWithNoIndexedFiles
-            && !options.SymbolsOnly;
-
-        IndexedFileStatReuseResult? GetFullScanTargetStatMatch(
-            int fileIndex,
-            bool allowCSharpPrepassCache)
-        {
-            if (!canSkipFullScanTargetsBeforeContentLoad)
-                return null;
-
-            var target = fileTargets[fileIndex];
-            var language = target.Language;
-            var targetRequiresRefresh = TargetRequiresJavaScriptTypeScriptRefresh(language, target.IndexPath);
-            var allowReuse = symbolKindFilterMatchesPrior
-                && !targetRequiresRefresh
-                && !priorSymbolsOnlyGraphOmitted
-                && (language != "csharp" || csharpIndexedProjectRootCompatible)
-                && (language != "csharp" || csharpSymbolNameContractMatchesCurrent)
-                && (language != "csharp" || !csharpWorkspace.HasStaticInterfaceContracts)
-                && (language != "sql" || sqlGraphContractMatchesCurrent)
-                && (language is not ("verilog" or "systemverilog" or "vhdl") || hdlGraphContractMatchesCurrent)
-                && AllowReuseWithCurrentHotspotFamilyTrust(language, hotspotFamilyTrustMatchesCurrent);
-            var existingFile = !allowReuse
-                ? null
-                : allowCSharpPrepassCache
-                  && language == "csharp"
-                  && csharpPrepassStatReuse != null
-                  && csharpPrepassStatReuse.TryGetValue(target.IndexPath, out var cachedCSharpPrepassReuse)
-                    ? cachedCSharpPrepassReuse
-                    : IndexedFileStatReuse.TryGetReusableUnchangedFile(
-                        reusableIndexedFileStats!,
-                        target.FilePath,
-                        target.IndexPath,
-                        language,
-                        target.GeneratedExtractionSuppressed);
-            return existingFile;
-        }
-
-        void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult existingFile)
+        var inputValidation = preWriteSession.PrepareWriteBoundary(
+            discovery.InputSnapshot);
+        if (!inputValidation.IsValid)
         {
-            var target = fileTargets[fileIndex];
-            var language = target.Language;
-            skipped++;
-            processed++;
-            readableFileBytes.Remember(fileIndex, existingFile.Size);
-            if (!string.IsNullOrWhiteSpace(language))
-            {
-                skippedSymbolExtractorLanguages ??= new HashSet<string>(StringComparer.Ordinal);
-                skippedSymbolExtractorLanguages.Add(language);
-            }
-            if (FileIndexer.SupportsHotspotFamilyMarkerLanguage(language) && language != null)
-            {
-                reusedHotspotFamilyLanguages ??= new HashSet<string>(StringComparer.Ordinal);
-                reusedHotspotFamilyLanguages.Add(language);
-            }
-            if (options.Verbose && !options.Json && !options.Quiet)
-                CommandOutputWriter.WriteLine($"  [SKIP] {target.IndexPath} (unchanged)");
-        }
-
-        var targetSelection = PrepareFullScanExtractionTargets(
-            new FullScanTargetSelectionContext
-            {
-                Writer = writer,
-                Indexer = indexer,
-                Options = options,
-                ProjectRoot = projectRoot,
-                FileTargets = fileTargets,
-                CSharpPrepassTargets = csharpPrepassTargets,
-                StaleFilePurgePlan = staleFilePurgePlan,
-                CanSkipTargetsBeforeContentLoad =
-                    canSkipFullScanTargetsBeforeContentLoad,
-                StartedWithNoIndexedFiles = startedWithNoIndexedFiles,
-                CSharpIndexedProjectRootCompatible =
-                    csharpIndexedProjectRootCompatible,
-                ExtractionParallelism = extractionParallelism,
-                PriorCSharpStaticInterfaceSourceEvidence =
-                    priorCSharpStaticInterfaceSourceEvidence,
-                CSharpWorkspace = csharpWorkspace,
-                CSharpWorkspaceFileSnapshots =
-                    csharpWorkspaceFileSnapshots,
-                ForceFullCSharpRefreshFromInvalidatedNoOp =
-                    forceFullCSharpRefreshFromInvalidatedNoOp,
-                PreservePriorPositiveCSharpSourceNoOp =
-                    preservePriorPositiveCSharpSourceNoOp,
-                CSharpSourceEvidenceForStamp =
-                    csharpSourceEvidenceForStamp,
-                CSharpSourceEvidenceComplete =
-                    csharpSourceEvidenceComplete,
-                CancellationToken = cancellationToken,
-                ThrowIfFullScanCancelled =
-                    () => ThrowIfFullScanCancelled(
-                        processed,
-                        files.Count),
-                GetDeferCSharpMutationsForIncompleteScan =
-                    () => deferCSharpMutationsForIncompleteScan,
-                GetFullScanTargetStatMatch =
-                    GetFullScanTargetStatMatch,
-                RecordFullScanTargetStatSkip =
-                    RecordFullScanTargetStatSkip,
-                DeferCSharpMutationsForIncompleteWorkspace =
-                    DeferCSharpMutationsForIncompleteWorkspace,
-                IsExistingCSharpSymbolPathNowNonCSharp =
-                    IsExistingCSharpSymbolPathNowNonCSharp,
-            });
-        var extractionFileIndexes =
-            targetSelection.ExtractionFileIndexes;
-        var extractionWorkItemCount =
-            targetSelection.ExtractionWorkItemCount;
-        csharpWorkspace = targetSelection.CSharpWorkspace;
-        csharpWorkspaceFileSnapshots =
-            targetSelection.CSharpWorkspaceFileSnapshots;
-        forceFullCSharpRefreshFromInvalidatedNoOp =
-            targetSelection
-                .ForceFullCSharpRefreshFromInvalidatedNoOp;
-        preservePriorPositiveCSharpSourceNoOp =
-            targetSelection.PreservePriorPositiveCSharpSourceNoOp;
-        csharpSourceEvidenceForStamp =
-            targetSelection.CSharpSourceEvidenceForStamp;
-        csharpSourceEvidenceComplete =
-            targetSelection.CSharpSourceEvidenceComplete;
-
-        var useFtsBulkLoad = ShouldUseFullScanFtsBulkLoad(
-            options.Rebuild,
-            startedWithNoIndexedFiles,
-            extractionWorkItemCount,
-            staleFilePurgePlan,
-            scanHadErrors,
-            readableFileBytes,
-            reusableIndexedFileStats!,
-            fileTargets,
-            extractionFileIndexes,
-            () => ThrowIfFullScanCancelled(processed, files.Count));
-
-        var finalCSharpRevalidation =
-            RevalidateFinalFullScanCSharpNoOp(
-                new FullScanCSharpFinalRevalidationContext
+            return WriteFullScanSnapshotFailure(
+                inputValidation.ChangedPath,
+                new FullScanSnapshotFailureContext
                 {
                     Writer = writer,
-                    Indexer = indexer,
                     Options = options,
+                    Stopwatch = stopwatch,
+                    JsonContext = jsonContext,
                     ProjectRoot = projectRoot,
-                    FileTargets = fileTargets,
-                    CSharpPrepassTargets = csharpPrepassTargets,
-                    StaleFilePurgePlan = staleFilePurgePlan,
-                    StartedWithNoIndexedFiles =
-                        startedWithNoIndexedFiles,
-                    CSharpIndexedProjectRootCompatible =
-                        csharpIndexedProjectRootCompatible,
-                    ExtractionParallelism = extractionParallelism,
-                    PriorCSharpStaticInterfaceSourceEvidence =
-                        priorCSharpStaticInterfaceSourceEvidence,
-                    ReusableIndexedFileStats =
-                        reusableIndexedFileStats!,
-                    ExtractionFileIndexes =
-                        extractionFileIndexes,
-                    ExtractionWorkItemCount =
-                        extractionWorkItemCount,
-                    UseFtsBulkLoad = useFtsBulkLoad,
-                    CSharpWorkspace = csharpWorkspace,
-                    CSharpWorkspaceFileSnapshots =
-                        csharpWorkspaceFileSnapshots,
-                    ForceFullCSharpRefreshFromInvalidatedNoOp =
-                        forceFullCSharpRefreshFromInvalidatedNoOp,
-                    PreservePriorPositiveCSharpSourceNoOp =
-                        preservePriorPositiveCSharpSourceNoOp,
-                    CSharpSourceEvidenceForStamp =
-                        csharpSourceEvidenceForStamp,
-                    CSharpSourceEvidenceComplete =
-                        csharpSourceEvidenceComplete,
-                    CancellationToken = cancellationToken,
-                    DeferCSharpMutationsForIncompleteWorkspace =
-                        DeferCSharpMutationsForIncompleteWorkspace,
-                    IsExistingCSharpSymbolPathNowNonCSharp =
-                        IsExistingCSharpSymbolPathNowNonCSharp,
+                    PriorReadiness = priorReadiness,
+                    CSharpSymbolNameContractMatchesCurrent = csharpSymbolNameContractMatchesCurrent,
+                    PriorMetadataTargetCsharpMatchesCurrent = priorMetadataTargetCsharpMatchesCurrent,
+                    PriorFoldVersion = priorFoldVersion,
+                    PriorFoldFingerprint = priorFoldFingerprint,
+                    MemorySamples = memorySamples,
+                    LanguageCounts = languageCounts,
+                    FilesCount = files.Count,
+                    Skipped = preWriteSelection.Skipped,
+                    DanglingSymlinkCount = scanResult.DanglingSymlinks.Count,
+                    Warnings = warnings,
+                    Errors = preWriteState.Diagnostics.Errors,
+                    SymbolsDroppedByKindFilter = symbolsDroppedByKindFilter,
+                    ErrorList = errorList,
+                    FileErrorList = fileErrorList,
+                    WarningList = warningList,
                 });
-        extractionFileIndexes =
-            finalCSharpRevalidation.ExtractionFileIndexes;
-        extractionWorkItemCount =
-            finalCSharpRevalidation.ExtractionWorkItemCount;
-        useFtsBulkLoad = finalCSharpRevalidation.UseFtsBulkLoad;
-        csharpWorkspace = finalCSharpRevalidation.CSharpWorkspace;
-        csharpWorkspaceFileSnapshots =
-            finalCSharpRevalidation.CSharpWorkspaceFileSnapshots;
-        forceFullCSharpRefreshFromInvalidatedNoOp =
-            finalCSharpRevalidation
-                .ForceFullCSharpRefreshFromInvalidatedNoOp;
-        preservePriorPositiveCSharpSourceNoOp =
-            finalCSharpRevalidation
-                .PreservePriorPositiveCSharpSourceNoOp;
-        csharpSourceEvidenceForStamp =
-            finalCSharpRevalidation.CSharpSourceEvidenceForStamp;
-        csharpSourceEvidenceComplete =
-            finalCSharpRevalidation.CSharpSourceEvidenceComplete;
-        skipped -= finalCSharpRevalidation.PromotedCSharpTargetCount;
-        processed -= finalCSharpRevalidation.PromotedCSharpTargetCount;
-        if (finalCSharpRevalidation.PromotedAllCSharpTargets)
-        {
-            skippedSymbolExtractorLanguages?.Remove("csharp");
-            reusedHotspotFamilyLanguages?.Remove("csharp");
         }
 
-        if (discovery.InputSnapshot != null)
-        {
-            FullScanInputSnapshotBarrierForTesting?.Invoke("before_write");
-            if (!indexer.TryValidateScanInputSnapshot(
-                    discovery.InputSnapshot,
-                    out var changedScanInputPath,
-                    cancellationToken))
-            {
-                return WriteFullScanSnapshotFailure(
-                    changedScanInputPath,
-                    new FullScanSnapshotFailureContext
-                    {
-                        Writer = writer,
-                        Options = options,
-                        Stopwatch = stopwatch,
-                        JsonContext = jsonContext,
-                        ProjectRoot = projectRoot,
-                        PriorReadiness = priorReadiness,
-                        CSharpSymbolNameContractMatchesCurrent = csharpSymbolNameContractMatchesCurrent,
-                        PriorMetadataTargetCsharpMatchesCurrent = priorMetadataTargetCsharpMatchesCurrent,
-                        PriorFoldVersion = priorFoldVersion,
-                        PriorFoldFingerprint = priorFoldFingerprint,
-                        MemorySamples = memorySamples,
-                        LanguageCounts = languageCounts,
-                        FilesCount = files.Count,
-                        Skipped = skipped,
-                        DanglingSymlinkCount = scanResult.DanglingSymlinks.Count,
-                        Warnings = warnings,
-                        Errors = errors,
-                        SymbolsDroppedByKindFilter = symbolsDroppedByKindFilter,
-                        ErrorList = errorList,
-                        FileErrorList = fileErrorList,
-                        WarningList = warningList,
-                    });
-            }
-        }
+        staleFilePurgePlan = preWriteState.Scan.StaleFilePurgePlan;
+        deferCSharpMutationsForIncompleteScan =
+            preWriteState.Scan.DeferCSharpMutationsForIncompleteScan;
+        purged = preWriteState.Scan.Purged;
+        ftsMutated = preWriteState.Scan.FtsMutated;
+        errors = preWriteState.Diagnostics.Errors;
+        var extractionFileIndexes =
+            preWriteSelection.ExtractionFileIndexes;
+        var extractionWorkItemCount =
+            preWriteSelection.ExtractionWorkItemCount;
+        var useFtsBulkLoad = preWriteSelection.UseFtsBulkLoad;
+        var csharpWorkspace = csharpPreflight.Workspace;
+        var csharpWorkspaceFileSnapshots =
+            csharpPreflight.WorkspaceFileSnapshots;
+        var csharpPrepassSymbolArtifacts =
+            csharpPreflight.PrepassSymbolArtifacts;
+        var preservePriorPositiveCSharpSourceNoOp =
+            csharpPreflight.PreservePriorPositiveSourceNoOp;
+        var csharpSourceEvidenceForStamp =
+            csharpPreflight.Evidence.ForStamp;
+        var csharpSourceEvidenceComplete =
+            csharpPreflight.Evidence.Complete;
 
-        if (!options.SymbolsOnly && !deferCSharpMutationsForIncompleteScan)
+        void DeferCSharpMutationsForLoadedSnapshotDrift(string path)
         {
-            var changedFilePath = string.Empty;
-            var stableFiles = csharpWorkspaceFileSnapshots == null
-                || CSharpStaticInterfacePrepass.TryValidateFileStatSnapshots(
-                    csharpPrepassTargets,
-                    csharpWorkspaceFileSnapshots,
-                    out changedFilePath,
-                    cancellationToken);
-            if (!stableFiles)
-            {
-                csharpPrepassSymbolArtifacts?.Clear();
-                csharpPrepassSymbolArtifacts = null;
-                var driftPath = FormatCSharpWorkspaceSnapshotPath(projectRoot, changedFilePath);
-                var incompleteWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
-                    [],
-                    HasStaticInterfaceContracts: true,
-                    SourceContractEvidenceComplete: false,
-                    IncompleteSourcePaths: [driftPath]);
-                DeferCSharpMutationsForIncompleteWorkspace(incompleteWorkspace);
-                preservePriorPositiveCSharpSourceNoOp = false;
-                csharpSourceEvidenceForStamp = false;
-                csharpSourceEvidenceComplete = false;
-                csharpWorkspaceFileSnapshots = null;
-                csharpWorkspace = incompleteWorkspace;
-                useFtsBulkLoad = false;
-
-                var deferredCSharpIndexes = new List<int>(csharpPrepassTargets.Count);
-                if (extractionFileIndexes == null)
-                {
-                    extractionFileIndexes = new List<int>(fileTargets.Length);
-                    for (var fileIndex = 0; fileIndex < fileTargets.Length; fileIndex++)
-                    {
-                        if (fileTargets[fileIndex].Language == "csharp")
-                            deferredCSharpIndexes.Add(fileIndex);
-                        else
-                            extractionFileIndexes.Add(fileIndex);
-                    }
-                }
-                else
-                {
-                    for (var extractionIndex = extractionFileIndexes.Count - 1; extractionIndex >= 0; extractionIndex--)
-                    {
-                        var fileIndex = extractionFileIndexes[extractionIndex];
-                        if (fileTargets[fileIndex].Language != "csharp")
-                            continue;
-                        deferredCSharpIndexes.Add(fileIndex);
-                        extractionFileIndexes.RemoveAt(extractionIndex);
-                    }
-                }
-
-                foreach (var fileIndex in deferredCSharpIndexes)
-                {
-                    long currentSize = 0;
-                    try
-                    {
-                        var info = new FileInfo(fileTargets[fileIndex].FilePath);
-                        if (info.Exists && info.Length >= 0)
-                            currentSize = info.Length;
-                    }
-                    catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or NotSupportedException or ArgumentException)
-                    {
-                    }
-                    RecordFullScanTargetStatSkip(
-                        fileIndex,
-                        new IndexedFileStatReuseResult(0, currentSize));
-                }
-
-                extractionFileIndexes.Sort();
-                extractionWorkItemCount = extractionFileIndexes.Count;
-            }
+            csharpPrepassSymbolArtifacts?.Clear();
+            csharpPrepassSymbolArtifacts = null;
+            path = FormatCSharpWorkspaceSnapshotPath(projectRoot, path);
+            deferCSharpMutationsForIncompleteScan = true;
+            preservePriorPositiveCSharpSourceNoOp = false;
+            csharpSourceEvidenceForStamp = false;
+            csharpSourceEvidenceComplete = false;
+            csharpWorkspaceFileSnapshots = null;
+            csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
+                [],
+                HasStaticInterfaceContracts: true,
+                SourceContractEvidenceComplete: false,
+                IncompleteSourcePaths: [path]);
+            writer.SetCSharpStaticInterfaceSourceEvidence(null);
+            RecordCSharpWorkspaceFailure(
+                path,
+                "csharp_workspace_validation",
+                new IOException(
+                    "A C# source changed after workspace preflight; rerun indexing to refresh the complete C# graph."));
         }
 
         // The captured scan has now crossed its only pre-write authority barrier. Start the
@@ -972,12 +689,12 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
                     sqlGraphContractMatchesCurrent,
                 HdlGraphContractMatchesCurrent =
                     hdlGraphContractMatchesCurrent,
-                ReadableFileBytes = readableFileBytes,
+                ReadableFileBytes = preWriteSelection.ReadableFileBytes,
                 IndexProgress = indexProgress,
                 FullScanProgress = fullScanProgress,
                 CancellationToken = cancellationToken,
-                GetProcessedCount = () => processed,
-                PublishProcessedCount = value => processed = value,
+                GetProcessedCount = () => preWriteSelection.Processed,
+                PublishProcessedCount = value => preWriteSelection.Processed = value,
                 ThrowIfFullScanCancelled =
                     ThrowIfFullScanCancelled,
                 SetIndexProgressVisible =
@@ -1020,9 +737,9 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
                     SymbolsDroppedByKindFilter =
                         symbolsDroppedByKindFilter,
                     ReusedHotspotFamilyLanguages =
-                        reusedHotspotFamilyLanguages,
+                        preWriteSelection.ReusedHotspotFamilyLanguages,
                     SkippedSymbolExtractorLanguages =
-                        skippedSymbolExtractorLanguages,
+                        preWriteSelection.SkippedSymbolExtractorLanguages,
                     IndexedSymbolExtractorLanguages =
                         indexedSymbolExtractorLanguages,
                     ErrorList = errorList,
@@ -1035,7 +752,7 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
         var extractionState = extractionPipeline.ConsumerState;
         if (extractionState != null)
         {
-            skipped += extractionState.Skipped;
+            preWriteSelection.Skipped += extractionState.Skipped;
             warnings += extractionState.Warnings;
             errors += extractionState.ErrorsAdded;
             ftsMutated = extractionState.FtsMutated;
@@ -1049,9 +766,9 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
             extractedChunks += extractionState.ExtractedChunks;
             extractedSymbols += extractionState.ExtractedSymbols;
             extractedReferences += extractionState.ExtractedReferences;
-            reusedHotspotFamilyLanguages =
+            preWriteSelection.ReusedHotspotFamilyLanguages =
                 extractionState.ReusedHotspotFamilyLanguages;
-            skippedSymbolExtractorLanguages =
+            preWriteSelection.SkippedSymbolExtractorLanguages =
                 extractionState.SkippedSymbolExtractorLanguages;
         }
 
@@ -1060,7 +777,7 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
         if (options.MemoryTrace)
             memorySamples.Add(CaptureMemorySample("extraction", stopwatch));
 
-        ThrowIfFullScanCancelled(processed, files.Count);
+        ThrowIfFullScanCancelled(preWriteSelection.Processed, files.Count);
         var referenceIdentityReadyForMutualRecursionRefresh =
             !deferCSharpMutationsForIncompleteScan && mutualRecursionRefreshNeeded
                 ? writer.CSharpFamilyTrustAllowsReferenceIdentityReady(
@@ -1127,7 +844,7 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
         }
         if (options.MemoryTrace && !willRebuildTypeScriptAugmentation)
             memorySamples.Add(CaptureMemorySample("reference_graph", stopwatch));
-        ThrowIfFullScanCancelled(processed, files.Count);
+        ThrowIfFullScanCancelled(preWriteSelection.Processed, files.Count);
         if (ftsBulkLoad != null)
         {
             var phase = ftsMutated ? "rebuilding text index" : "restoring text index triggers";
@@ -1162,7 +879,7 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
         }
         if (options.MemoryTrace)
             memorySamples.Add(CaptureMemorySample("text_index", stopwatch));
-        ThrowIfFullScanCancelled(processed, files.Count);
+        ThrowIfFullScanCancelled(preWriteSelection.Processed, files.Count);
         var readinessStableFiles = true;
         string? readinessChangedFilePath = null;
         if (discovery.InputSnapshot != null)
@@ -1325,9 +1042,9 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
             CancellationToken = cancellationToken,
             Errors = errors,
             FileErrorList = fileErrorList,
-            Processed = processed,
+            Processed = preWriteSelection.Processed,
             FileCount = files.Count,
-            Skipped = skipped,
+            Skipped = preWriteSelection.Skipped,
             Purged = purged,
             ScanHadErrors = scanHadErrors,
             StartedWithNoIndexedFiles = startedWithNoIndexedFiles,
@@ -1342,16 +1059,16 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
             TypeScriptAugmentationDirtyNames = typeScriptAugmentationDirtyNames,
             UseScopedTypeScriptAugmentationRefresh = useScopedTypeScriptAugmentationRefresh,
             LanguageCounts = languageCounts,
-            ReusedHotspotFamilyLanguages = reusedHotspotFamilyLanguages,
+            ReusedHotspotFamilyLanguages = preWriteSelection.ReusedHotspotFamilyLanguages,
             PriorHotspotFamilyVersions = priorHotspotFamilyVersions,
             PriorHotspotFamilyMarkerFingerprints = priorHotspotFamilyMarkerFingerprints,
             CurrentHotspotFamilyMarkerFingerprints = currentHotspotFamilyMarkerFingerprints,
             IndexedSymbolExtractorLanguages = indexedSymbolExtractorLanguages,
-            SkippedSymbolExtractorLanguages = skippedSymbolExtractorLanguages,
+            SkippedSymbolExtractorLanguages = preWriteSelection.SkippedSymbolExtractorLanguages,
             PriorFoldVersion = priorFoldVersion,
             PriorFoldFingerprint = priorFoldFingerprint,
             ScanResult = scanResult,
-            ReadableFileBytes = readableFileBytes,
+            ReadableFileBytes = preWriteSelection.ReadableFileBytes,
             MemorySamples = memorySamples,
             TypeScriptAugmentationOwnsDeferredReferenceGraphRefresh =
                 deferMutualRecursionRefreshToTypeScriptAugmentation
@@ -1446,7 +1163,7 @@ void RecordFullScanTargetStatSkip(int fileIndex, IndexedFileStatReuseResult exis
             ExtractedReferences = extractedReferences,
             PersistedReferences = persistedReferences,
             FilesCount = files.Count,
-            Skipped = skipped,
+            Skipped = preWriteSelection.Skipped,
             Purged = purged,
             ScanResult = scanResult,
             LanguageCounts = languageCounts,
diff --git a/tests/CodeIndex.Tests/IndexCommandRunnerFullScanTests.cs b/tests/CodeIndex.Tests/IndexCommandRunnerFullScanTests.cs
index 2642055c9..8d2725e1f 100644
--- a/tests/CodeIndex.Tests/IndexCommandRunnerFullScanTests.cs
+++ b/tests/CodeIndex.Tests/IndexCommandRunnerFullScanTests.cs
@@ -3185,6 +3185,7 @@ public void Run_FullScan_ValidatesScanInputExactlyBeforeWriteAndReadiness(
     {
         var projectRoot = CreateTempProject();
         var previousBarrierHook = IndexCommandRunner.FullScanInputSnapshotBarrierForTesting;
+        var previousWritePhaseHook = IndexCommandRunner.FullScanWritePhaseStartedForTesting;
         var phases = new List<string>();
         try
         {
@@ -3192,6 +3193,8 @@ public void Run_FullScan_ValidatesScanInputExactlyBeforeWriteAndReadiness(
             if (includeCSharp)
                 File.WriteAllText(Path.Combine(projectRoot, "Plain.cs"), "public sealed class Plain { }\n");
             IndexCommandRunner.FullScanInputSnapshotBarrierForTesting = phases.Add;
+            IndexCommandRunner.FullScanWritePhaseStartedForTesting = () =>
+                phases.Add("write_started");
 
             var args = symbolsOnly
                 ? new[] { projectRoot, "--symbols-only", "--json", "--quiet" }
@@ -3199,11 +3202,14 @@ public void Run_FullScan_ValidatesScanInputExactlyBeforeWriteAndReadiness(
             var exitCode = IndexCommandRunner.Run(args, _jsonOptions);
 
             Assert.Equal(CommandExitCodes.Success, exitCode);
-            Assert.Equal(["before_write", "before_readiness"], phases);
+            Assert.Equal(
+                ["before_write", "write_started", "before_readiness"],
+                phases);
         }
         finally
         {
             IndexCommandRunner.FullScanInputSnapshotBarrierForTesting = previousBarrierHook;
+            IndexCommandRunner.FullScanWritePhaseStartedForTesting = previousWritePhaseHook;
             DeleteDirectory(projectRoot);
             SqliteConnection.ClearAllPools();
         }
@@ -3351,8 +3357,11 @@ public void Run_FullScan_FreshSnapshotAbortRetainsDiscoveredLanguageFailuresWith
         }
     }
 
-    [Fact]
-    public void Run_FullScan_FirstSnapshotBarrierDriftPreservesRowsAndTrustAfterSchemaInitialization()
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public void Run_FullScan_FirstSnapshotBarrierDriftPreservesRowsAndTrustAfterSchemaInitialization(
+        bool rebuild)
     {
         var projectRoot = CreateTempProject();
         var previousBarrierHook = IndexCommandRunner.FullScanInputSnapshotBarrierForTesting;
@@ -3376,6 +3385,7 @@ public void Run_FullScan_FirstSnapshotBarrierDriftPreservesRowsAndTrustAfterSche
             string? priorAppChecksum;
             bool? priorSourceEvidence;
             string? priorFtsRecoveryMarker;
+            string? priorBatchMarker;
             using (var db = new DbContext(DbOpenIntent.WriteIndex, dbPath))
             {
                 priorReadiness = db.GetUserVersion();
@@ -3384,7 +3394,9 @@ public void Run_FullScan_FirstSnapshotBarrierDriftPreservesRowsAndTrustAfterSche
                 var priorWriter = new DbWriter(db);
                 priorSourceEvidence = priorWriter.GetCSharpStaticInterfaceSourceEvidence();
                 priorWriter.MarkFtsBulkLoadRecoveryNeeded();
+                priorWriter.MarkBatchInProgress();
                 priorFtsRecoveryMarker = db.GetMetaString(DbWriter.FtsBulkLoadInProgressMetaKey);
+                priorBatchMarker = db.GetMetaString(DbContext.BatchInProgressMetaKey);
             }
 
             File.WriteAllText(appPath, "def run():\n    return 2\n");
@@ -3402,7 +3414,10 @@ public void Run_FullScan_FirstSnapshotBarrierDriftPreservesRowsAndTrustAfterSche
                 Directory.SetLastWriteTimeUtc(projectRoot, rootModifiedUtc);
             };
 
-            var (exitCode, json) = RunAndCaptureJson([projectRoot, "--json", "--quiet"]);
+            var args = rebuild
+                ? new[] { projectRoot, "--rebuild", "--yes", "--json", "--quiet" }
+                : [projectRoot, "--json", "--quiet"];
+            var (exitCode, json) = RunAndCaptureJson(args);
 
             Assert.Equal(CommandExitCodes.PartialResult, exitCode);
             Assert.Equal("partial", json.GetProperty("status").GetString());
@@ -3417,6 +3432,9 @@ public void Run_FullScan_FirstSnapshotBarrierDriftPreservesRowsAndTrustAfterSche
             Assert.Equal(
                 priorFtsRecoveryMarker,
                 preservedDb.GetMetaString(DbWriter.FtsBulkLoadInProgressMetaKey));
+            Assert.Equal(
+                priorBatchMarker,
+                preservedDb.GetMetaString(DbContext.BatchInProgressMetaKey));
             Assert.Equal(priorAppChecksum, new DbReader(preservedDb.Connection).GetFileByPath("app.py")?.Checksum);
             Assert.NotNull(new DbReader(preservedDb.Connection).GetFileByPath("obsolete.md"));
             Assert.Equal(

From efe1a0135a930a3060e832d793fee728e641f03c Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 16:37:22 +0900
Subject: [PATCH 42/45] Unify C# partial-family unused filtering

---
 TESTING_GUIDE.md                              |   4 +-
 .../unreleased/+unused-legacy-schema.fixed.md |  15 ++
 src/CodeIndex/Database/DbReader.cs            |   2 +
 ...DbSymbolReader.UnusedSymbols.Candidates.cs |  74 ++++++--
 .../Database/DbSymbolReader.UnusedSymbols.cs  | 115 +++---------
 .../DbReaderUnusedCandidateQueryTests.cs      | 170 ++++++++++++++++++
 .../LegacySchemaMigrationTests.cs             |  41 ++++-
 7 files changed, 317 insertions(+), 104 deletions(-)
 create mode 100644 changelog.d/unreleased/+unused-legacy-schema.fixed.md

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 8de585c3f..e63ad9e2a 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -204,7 +204,7 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   `DbSchemaConstraintTests.cs` also locks schema constraints to `SymbolKindCatalog` and required file foreign keys so DB readiness checks fail when code enums and SQLite CHECK clauses drift.
   Hotspot ranking fixtures should use the smallest counts that cross each ranking threshold; for structural-rank tests, keep one side just above the raw-reference comparison and the other just above the symbol-count threshold instead of scaling both far beyond the boundary.
   Hotspot candidate-filter alignment is one public database-behavior contract across site, grouped, and file list/count queries. Keep visibility include/exclude filters before ambiguity cardinality, path include/exclude and test suppression after cardinality, authoritative family identity intact, and all six result/count shapes aligned. The structural SQL fixture separately pins the shared candidate plan to its explicit ten-column projection and forbids `SELECT *`.
-  Unused-candidate query coverage must keep the SQL-aware and non-SQL paths aligned on the shared 17-column projection, provisional bucket ordering, scope filters, and parameter binding. Retain one mixed C#/SQL public-behavior fixture that proves SQL reference resolution, C# projection and null fallbacks, list/count agreement, and detailed bucket counts together; keep same-file/partial C# suppression and enum-collision scope in their focused fixtures.
+  Unused-candidate query coverage must keep the SQL-aware and non-SQL paths aligned on the shared 17-column projection, provisional bucket ordering, scope filters, and parameter binding. Retain one mixed C#/SQL public-behavior fixture that proves SQL reference resolution, C# projection and null fallbacks, list/count agreement, and detailed bucket counts together. A separate mixed partial-family fixture must force the resolver-aware and non-SQL routes with an SQL scope probe plus a visibility-filtered SQL control, then require result/count/detailed-count parity while the shared pre-page predicate suppresses a private member used from a peer part; keep same-file C# suppression and enum-collision scope in their focused fixtures.
   Unused-symbol classification coverage must preserve surface-tag insertion order and contract-domain precedence when one symbol overlaps generated, contract-member, configuration, exception-metadata, public, and test signals. Keep those surface predicates evaluated once into the shared analysis, retain private/non-public early returns, and assert aligned reason tags, domain tags, and aggregate domain counts.
   Checkpoint listing and retention fixtures should exceed the relevant directory cap once and exceed the inspected-file cap on only one checkpoint; multiplying both caps together adds filesystem work without increasing boundary coverage. Checkpoint and restore-backup cleanup dry-run tests must assert both exact deleted/retained paths and the continued existence of every candidate directory. Restore dry-run tests should inject destination free space through `DbCommandRunner.AvailableFreeSpaceForTesting`, verify manifest and regular-file path diagnostics independently, and prove that no restore staging or backup directory is created.
   WAL checkpoint contention fixtures must establish a real read transaction before a later writer commit, then lower `busy_timeout` to keep the assertion bounded without fixed sleeps. Permission/error-path coverage may throw from `DbContext.WalCheckpointTruncateExecutedForTesting`; restore the previous `AsyncLocal` value in `finally` so parallel test state cannot leak.
@@ -1273,7 +1273,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   `DbSchemaConstraintTests.cs` は DB readiness check が code enum と SQLite CHECK 句の drift を検出できるよう、schema constraint と `SymbolKindCatalog`、必須 file foreign key の同期も固定します。
   hotspot ranking fixture は各 ranking threshold を跨ぐ最小 count を使ってください。structural-rank test では、raw reference 比較をわずかに超える側と symbol-count threshold をわずかに超える側を用意し、境界から大きく離れた件数まで膨らませないでください。
   hotspot candidate filter の整合性は、site / grouped / file の list / count 全6 query に共通する public database behavior 契約です。visibility include / exclude は ambiguity cardinality より前、path include / exclude と test suppression は cardinality より後に適用し、authoritative family identity と全6形状の結果・件数を一致させてください。structural SQL fixture は別途、共通 candidate plan の明示的な10列 projection と `SELECT *` 禁止を固定します。
-  unused candidate query の coverage では、SQL-aware / non-SQL 経路で共通の17列 projection、provisional bucket 順、scope filter、parameter binding を一致させてください。mixed C#/SQL の public behavior fixture 1つで SQL reference resolution、C# projection と null fallback、list/count の一致、詳細 bucket count をまとめて固定し、same-file / partial C# suppression と enum collision scope は焦点を絞った既存 fixture で維持します。
+  unused candidate query の coverage では、SQL-aware / non-SQL 経路で共通の17列 projection、provisional bucket 順、scope filter、parameter binding を一致させてください。mixed C#/SQL の public behavior fixture 1つで SQL reference resolution、C# projection と null fallback、list/count の一致、詳細 bucket count をまとめて固定します。別の mixed partial-family fixture では、SQL scope probe と visibility filter で除外される SQL control によって resolver-aware / non-SQL の両経路を強制し、peer part から使用される private member を共有の page 前 predicate が抑制した状態で、result / count / detailed-count の一致を必須にしてください。same-file C# suppression と enum collision scope は焦点を絞った既存 fixture で維持します。
   unused symbol classification の coverage では、1つの symbol が generated、contract member、configuration、exception metadata、public、test の各 signal に重なる場合も、surface tag の追加順と contract domain の優先順位を維持してください。これらの surface predicate は共有 analysis へ1度だけ評価し、private / non-public の early return を保ったまま、reason tag、domain tag、domain 集計件数の一致を assertion します。
   checkpoint listing / retention fixture は対象の directory cap を 1 件だけ超え、inspected-file cap は 1 checkpoint だけで超えてください。両方の cap を掛け合わせても boundary coverage は増えず、filesystem work だけが増えます。checkpoint / restore-backup cleanup の dry-run test では、削除予定・保持予定の正確な path と、全候補 directory が引き続き存在することの両方を検証してください。restore dry-run test は `DbCommandRunner.AvailableFreeSpaceForTesting` で destination free space を注入し、manifest と regular-file path の diagnostic を独立に検証し、restore staging directory や backup directory が作られないことを固定します。
   WAL checkpoint contention fixture は後続 writer commit より先に実際の read transaction を確立し、固定 sleep を使わず assertion を bounded にするため `busy_timeout` を短くします。permission / error path の coverage では `DbContext.WalCheckpointTruncateExecutedForTesting` から exception を throw できますが、parallel test state を漏らさないよう、以前の `AsyncLocal` 値を `finally` で復元してください。
diff --git a/changelog.d/unreleased/+unused-legacy-schema.fixed.md b/changelog.d/unreleased/+unused-legacy-schema.fixed.md
new file mode 100644
index 000000000..94d0123f5
--- /dev/null
+++ b/changelog.d/unreleased/+unused-legacy-schema.fixed.md
@@ -0,0 +1,15 @@
+---
+category: fixed
+affected:
+  - src/CodeIndex/Database/DbReader.cs
+  - src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Candidates.cs
+  - src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
+---
+
+## English
+
+- **C# unused-symbol queries now remain safe on read-only legacy databases** — partial-type use filtering is applied before paging without issuing per-candidate database queries, while databases whose legacy chunk or symbol tables lack the required columns retain the existing degraded fallback instead of failing during SQL preparation.
+
+## 日本語
+
+- **C# の unused-symbol query が read-only legacy database でも安全に動作するようになりました** — partial type の使用判定を candidate ごとの database query なしで paging 前に適用し、必要な column が legacy chunk / symbol table にない database では SQL prepare で失敗せず、従来の degraded fallback を維持します。
diff --git a/src/CodeIndex/Database/DbReader.cs b/src/CodeIndex/Database/DbReader.cs
index 17e26a280..991d98467 100644
--- a/src/CodeIndex/Database/DbReader.cs
+++ b/src/CodeIndex/Database/DbReader.cs
@@ -80,6 +80,7 @@ public partial class DbReader : IDisposable
     private readonly IReadOnlySet<string> _fileColumns;
     private readonly IReadOnlySet<string> _symbolColumns;
     private readonly IReadOnlySet<string> _referenceColumns;
+    private readonly IReadOnlySet<string> _chunkColumns;
     private readonly IReadOnlySet<string> _chunkIndexes;
     private readonly IReadOnlySet<string> _symbolIndexes;
     private readonly IReadOnlySet<string> _referenceIndexes;
@@ -598,6 +599,7 @@ private DbReader(
         GeneratedColumnAvailableScope.Value = _fileColumns.Contains("generated");
         _symbolColumns = LoadColumns("symbols");
         _referenceColumns = LoadColumns("symbol_references");
+        _chunkColumns = LoadColumns("chunks");
         _chunkIndexes = LoadIndexes("chunks");
         _symbolIndexes = LoadIndexes("symbols");
         int userVersion;
diff --git a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Candidates.cs b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Candidates.cs
index d1309325c..f12449521 100644
--- a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Candidates.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.Candidates.cs
@@ -126,13 +126,24 @@ private UnusedCandidateQueryPlan BuildUnusedCandidatePageQuery(
     {
         var graphLanguages = GetUnusedCandidateGraphLanguages(scope.Lang, resolveSqlReferences);
         var bucketSql = BuildUnusedCandidateBucketSql();
-        var sql = new StringBuilder(capacity: resolveSqlReferences ? 5_000 : 3_000);
+        var hasUsableUnusedChunks = HasUsableUnusedChunks();
+        var useCSharpPartialUseExclusion = CanApplyCSharpPartialUseExclusion(
+            scope,
+            hasUsableUnusedChunks);
+        var sql = new StringBuilder(
+            capacity: resolveSqlReferences || useCSharpPartialUseExclusion ? 5_000 : 3_000);
         if (resolveSqlReferences)
             sql.Append("\n            WITH unused_candidates AS (\n                SELECT ");
         else
             sql.Append("\n            SELECT ");
         sql.Append(BuildUnusedCandidateProjectionSql(bucketSql));
-        AppendUnusedCandidateSourceSql(sql, scope, graphLanguages, resolveSqlReferences);
+        AppendUnusedCandidateSourceSql(
+            sql,
+            scope,
+            graphLanguages,
+            resolveSqlReferences,
+            hasUsableUnusedChunks,
+            useCSharpPartialUseExclusion);
 
         if (resolveSqlReferences)
         {
@@ -153,10 +164,20 @@ private UnusedCandidateQueryPlan BuildUnusedCandidatePageQuery(
     private UnusedCandidateQueryPlan BuildUnusedCandidateCountQuery(UnusedCandidateScope scope)
     {
         var graphLanguages = GetUnusedCandidateGraphLanguages(scope.Lang, resolveSqlReferences: true);
-        var sql = new StringBuilder(capacity: 4_000);
+        var hasUsableUnusedChunks = HasUsableUnusedChunks();
+        var useCSharpPartialUseExclusion = CanApplyCSharpPartialUseExclusion(
+            scope,
+            hasUsableUnusedChunks);
+        var sql = new StringBuilder(capacity: useCSharpPartialUseExclusion ? 5_000 : 4_000);
         sql.Append(@"
             SELECT COUNT(*), COUNT(DISTINCT f.path), MAX(CASE WHEN f.lang = 'sql' THEN 1 ELSE 0 END)");
-        AppendUnusedCandidateSourceSql(sql, scope, graphLanguages, resolveSqlReferences: true);
+        AppendUnusedCandidateSourceSql(
+            sql,
+            scope,
+            graphLanguages,
+            resolveSqlReferences: true,
+            hasUsableUnusedChunks: hasUsableUnusedChunks,
+            useCSharpPartialUseExclusion: useCSharpPartialUseExclusion);
         return new UnusedCandidateQueryPlan(sql.ToString(), graphLanguages);
     }
 
@@ -181,21 +202,27 @@ private void AppendUnusedCandidateSourceSql(
         StringBuilder sql,
         UnusedCandidateScope scope,
         IReadOnlyList<string> graphLanguages,
-        bool resolveSqlReferences)
+        bool resolveSqlReferences,
+        bool hasUsableUnusedChunks,
+        bool useCSharpPartialUseExclusion)
     {
         sql.Append(@"
             FROM symbols s
             JOIN files f ON s.file_id = f.id
             WHERE s.kind NOT IN ('import', 'namespace')");
         sql.Append(BuildUnusedReferenceAbsenceSql(resolveSqlReferences));
-        if (resolveSqlReferences && _hasChunksTable && HasTable("chunks"))
+        if (useCSharpPartialUseExclusion || (resolveSqlReferences && hasUsableUnusedChunks))
         {
             var visibilitySql = $"lower({GetSymbolColumnSql("visibility", "''")})";
-            sql.Append(BuildSameFilePrivateUseExclusionSql(
-                "s", "f", visibilitySql,
-                GetSymbolColumnSql("start_line", "s.line"),
-                GetSymbolColumnSql("end_line", "s.line")));
-            sql.Append(BuildCSharpPartialContainingTypeUseExclusionSql("s", "f", visibilitySql));
+            if (resolveSqlReferences && hasUsableUnusedChunks)
+            {
+                sql.Append(BuildSameFilePrivateUseExclusionSql(
+                    "s", "f", visibilitySql,
+                    GetSymbolColumnSql("start_line", "s.line"),
+                    GetSymbolColumnSql("end_line", "s.line")));
+            }
+            if (useCSharpPartialUseExclusion)
+                sql.Append(BuildCSharpPartialContainingTypeUseExclusionSql("s", "f", visibilitySql));
         }
         sql.Append("\n              AND ");
         sql.Append(BuildAmbiguousCSharpEnumMemberExclusionSql(
@@ -203,6 +230,31 @@ FROM symbols s
         AppendUnusedCandidateScopeSql(sql, scope, graphLanguages);
     }
 
+    private bool CanApplyCSharpPartialUseExclusion(
+        UnusedCandidateScope scope,
+        bool hasUsableUnusedChunks)
+    {
+        if (scope.Lang != null
+            && !string.Equals(scope.Lang, "csharp", StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        return hasUsableUnusedChunks
+            && _symbolColumns.Contains("visibility")
+            && _symbolColumns.Contains("container_kind")
+            && _symbolColumns.Contains("container_name")
+            && _symbolColumns.Contains("signature");
+    }
+
+    private bool HasUsableUnusedChunks()
+        => _hasChunksTable
+           && _chunkColumns.Contains("file_id")
+           && _chunkColumns.Contains("start_line")
+           && _chunkColumns.Contains("end_line")
+           && _chunkColumns.Contains("content")
+           && HasTable("chunks");
+
     private string BuildUnusedReferenceAbsenceSql(bool resolveSqlReferences)
     {
         if (!resolveSqlReferences)
diff --git a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
index 45d8c4c13..588bbe49a 100644
--- a/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.UnusedSymbols.cs
@@ -362,13 +362,14 @@ private List<UnusedSymbolResult> GetUnusedSymbolsWithoutSqlResolver(int limit, s
             UnusedPublicOverfetchMaximum);
         var publicOrExported = new List<UnusedSymbolResult>(targetCount);
         var fileContentByFileId = new Dictionary<long, string>();
-        var privateLike = CollectUnusedCandidateBucket(targetCount, batchSize, 0, fileContentByFileId,
+        var canInspectSameFileUse = CanInspectUnusedCandidateSameFileUse();
+        var privateLike = CollectUnusedCandidateBucket(targetCount, batchSize, 0, fileContentByFileId, canInspectSameFileUse,
             kind, lang, pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
-        var maybeNonPublic = CollectUnusedCandidateBucket(targetCount, batchSize, 1, fileContentByFileId,
+        var maybeNonPublic = CollectUnusedCandidateBucket(targetCount, batchSize, 1, fileContentByFileId, canInspectSameFileUse,
             kind, lang, pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
-        var reflectionOrConfig = CollectUnusedCandidateBucket(targetCount, batchSize, 3, fileContentByFileId,
+        var reflectionOrConfig = CollectUnusedCandidateBucket(targetCount, batchSize, 3, fileContentByFileId, canInspectSameFileUse,
             kind, lang, pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
-        CollectPublicUnusedCandidateBucket(targetCount, batchSize, publicFetchBudget, fileContentByFileId,
+        CollectPublicUnusedCandidateBucket(targetCount, batchSize, publicFetchBudget, fileContentByFileId, canInspectSameFileUse,
             publicOrExported, reflectionOrConfig, kind, lang, pathPatterns, excludePathPatterns, excludeTests, visibilityFilters, excludeVisibilityFilters);
 
         var merged = new List<UnusedSymbolResult>(privateLike.Count + maybeNonPublic.Count + publicOrExported.Count + reflectionOrConfig.Count);
@@ -390,6 +391,7 @@ private List<UnusedSymbolResult> GetFilteredUnusedSymbolsWithoutSqlResolver(int
             return [];
 
         var fileContentByFileId = new Dictionary<long, string>();
+        var canInspectSameFileUse = CanInspectUnusedCandidateSameFileUse();
         var resultsByBucket = CreateUnusedBucketResultLists();
         const int batchSize = UnusedPublicOverfetchMaximum;
         foreach (var provisionalBucket in GetRelevantUnusedProvisionalBuckets(targetBuckets))
@@ -405,7 +407,7 @@ private List<UnusedSymbolResult> GetFilteredUnusedSymbolsWithoutSqlResolver(int
                 offset += batch.Count;
                 foreach (var candidate in batch)
                 {
-                    if (HasPrivateCSharpUse(candidate, fileContentByFileId))
+                    if (HasSameFilePrivateUse(candidate, fileContentByFileId, canInspectSameFileUse))
                         continue;
 
                     var result = CreateUnusedSymbolResult(candidate);
@@ -424,7 +426,7 @@ private List<UnusedSymbolResult> GetFilteredUnusedSymbolsWithoutSqlResolver(int
     }
 
     private List<UnusedSymbolResult> CollectUnusedCandidateBucket(int targetCount, int batchSize, int provisionalBucketOrder,
-        Dictionary<long, string> fileContentByFileId, string? kind, string? lang,
+        Dictionary<long, string> fileContentByFileId, bool canInspectSameFileUse, string? kind, string? lang,
         IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests,
         IReadOnlyList<string>? visibilityFilters, IReadOnlyList<string>? excludeVisibilityFilters)
     {
@@ -440,7 +442,7 @@ private List<UnusedSymbolResult> CollectUnusedCandidateBucket(int targetCount, i
             offset += batch.Count;
             foreach (var candidate in batch)
             {
-                if (HasPrivateCSharpUse(candidate, fileContentByFileId))
+                if (HasSameFilePrivateUse(candidate, fileContentByFileId, canInspectSameFileUse))
                     continue;
 
                 results.Add(CreateUnusedSymbolResult(candidate));
@@ -456,7 +458,7 @@ private List<UnusedSymbolResult> CollectUnusedCandidateBucket(int targetCount, i
     }
 
     private void CollectPublicUnusedCandidateBucket(int targetCount, int batchSize, int candidateBudget,
-        Dictionary<long, string> fileContentByFileId,
+        Dictionary<long, string> fileContentByFileId, bool canInspectSameFileUse,
         List<UnusedSymbolResult> publicOrExported, List<UnusedSymbolResult> reflectionOrConfig, string? kind, string? lang,
         IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests,
         IReadOnlyList<string>? visibilityFilters, IReadOnlyList<string>? excludeVisibilityFilters)
@@ -474,7 +476,7 @@ private void CollectPublicUnusedCandidateBucket(int targetCount, int batchSize,
             offset += batch.Count;
             foreach (var candidate in batch)
             {
-                if (HasPrivateCSharpUse(candidate, fileContentByFileId))
+                if (HasSameFilePrivateUse(candidate, fileContentByFileId, canInspectSameFileUse))
                     continue;
 
                 candidatesFetched++;
@@ -499,17 +501,15 @@ private void CollectPublicUnusedCandidateBucket(int targetCount, int batchSize,
         }
     }
 
-    private bool HasPrivateCSharpUse(UnusedCandidateSymbol candidate, Dictionary<long, string> fileContentByFileId)
-        => HasSameFilePrivateUse(candidate, fileContentByFileId)
-           || HasCSharpPartialContainingTypeUse(candidate);
-
-    private bool HasSameFilePrivateUse(UnusedCandidateSymbol candidate, Dictionary<long, string> fileContentByFileId)
+    private bool HasSameFilePrivateUse(
+        UnusedCandidateSymbol candidate,
+        Dictionary<long, string> fileContentByFileId,
+        bool canInspectSameFileUse)
     {
-        if (!string.Equals(candidate.Lang, "csharp", StringComparison.Ordinal)
+        if (!canInspectSameFileUse
+            || !string.Equals(candidate.Lang, "csharp", StringComparison.Ordinal)
             || !IsPrivateLikeVisibility(candidate.Visibility)
-            || candidate.Name.Length == 0
-            || !_hasChunksTable
-            || !HasTable("chunks"))
+            || candidate.Name.Length == 0)
             return false;
 
         var fileContent = GetUnusedCandidateFileContent(candidate.FileId, fileContentByFileId);
@@ -520,76 +520,9 @@ private bool HasSameFilePrivateUse(UnusedCandidateSymbol candidate, Dictionary<l
             candidate.EndLine);
     }
 
-    private bool HasCSharpPartialContainingTypeUse(UnusedCandidateSymbol candidate)
-    {
-        if (!string.Equals(candidate.Lang, "csharp", StringComparison.Ordinal)
-            || !IsPrivateLikeVisibility(candidate.Visibility)
-            || candidate.Name.Length == 0
-            || !IsCSharpPartialContainerKind(candidate.ContainerKind)
-            || string.IsNullOrWhiteSpace(candidate.ContainerName)
-            || !_hasChunksTable
-            || !HasTable("chunks"))
-        {
-            return false;
-        }
-
-        var ownSignatureSql = GetSymbolColumnSql("signature", "''", "own_type");
-        var peerSignatureSql = GetSymbolColumnSql("signature", "''", "peer_type");
-        var ownQualifiedNameSql = BuildCSharpPartialTypeQualifiedNameSql("own_type");
-        var peerQualifiedNameSql = BuildCSharpPartialTypeQualifiedNameSql("peer_type");
-        var ownTypeShapeSql = BuildCSharpPartialTypeShapeSql("own_type", "own_ancestor");
-        var peerTypeShapeSql = BuildCSharpPartialTypeShapeSql("peer_type", "peer_ancestor");
-        var peerTypeStartLineSql = GetSymbolColumnSql("start_line", "peer_type.line", "peer_type");
-        var peerTypeEndLineSql = GetSymbolColumnSql("end_line", peerTypeStartLineSql, "peer_type");
-
-        using var cmd = _conn.CreateCommand();
-        cmd.CommandText = $@"
-            SELECT 1
-            FROM symbols own_type
-            JOIN symbols peer_type
-              ON peer_type.file_id <> own_type.file_id
-             AND peer_type.kind = own_type.kind
-             AND peer_type.name = own_type.name
-            JOIN files peer_file ON peer_file.id = peer_type.file_id
-            JOIN chunks peer_chunk ON peer_chunk.file_id = peer_type.file_id
-            WHERE own_type.file_id = @fileId
-              AND own_type.kind = @containerKind
-              AND own_type.name = @containerName
-              AND lower({ownSignatureSql}) LIKE '%partial%'
-              AND lower({peerSignatureSql}) LIKE '%partial%'
-              AND peer_file.lang = 'csharp'
-              AND (
-                  @containerQualifiedName = ''
-                  OR @containerQualifiedName = own_type.name
-                  OR @containerQualifiedName = {ownQualifiedNameSql}
-              )
-              AND (
-                  @containerQualifiedName = ''
-                  OR @containerQualifiedName = peer_type.name
-                  OR @containerQualifiedName = {peerQualifiedNameSql}
-              )
-              AND {ownTypeShapeSql} = {peerTypeShapeSql}
-              AND peer_chunk.end_line >= {peerTypeStartLineSql}
-              AND peer_chunk.start_line <= {peerTypeEndLineSql}
-              AND csharp_identifier_occurrence_count_in_line_range(
-                      peer_chunk.content,
-                      peer_chunk.start_line,
-                      {peerTypeStartLineSql},
-                      {peerTypeEndLineSql},
-                      @symbolName) > 0
-            LIMIT 1";
-        SqliteCommandPolicy.Add(cmd, "@fileId", candidate.FileId);
-        SqliteCommandPolicy.Add(cmd, "@containerKind", candidate.ContainerKind);
-        SqliteCommandPolicy.Add(cmd, "@containerName", candidate.ContainerName);
-        SqliteCommandPolicy.Add(cmd, "@containerQualifiedName", candidate.ContainerQualifiedName ?? string.Empty);
-        SqliteCommandPolicy.Add(cmd, "@symbolName", candidate.Name);
-
-        using var reader = cmd.ExecuteTrackedReader();
-        return reader.TrackedRead();
-    }
-
-    private static bool IsCSharpPartialContainerKind(string? kind)
-        => kind is "class" or "struct" or "interface";
+    private bool CanInspectUnusedCandidateSameFileUse()
+        => HasUsableUnusedChunks()
+           && _chunkColumns.Contains("chunk_index");
 
     private string GetUnusedCandidateFileContent(long fileId, Dictionary<long, string> fileContentByFileId)
     {
@@ -1103,6 +1036,7 @@ private UnusedCountResult CountUnusedSymbolsDetailedWithoutSqlResolver(string? k
         var confidenceCounts = new Dictionary<string, int>(StringComparer.Ordinal);
         var contractDomainCounts = new Dictionary<string, int>(StringComparer.Ordinal);
         var fileContentByFileId = new Dictionary<long, string>();
+        var canInspectSameFileUse = CanInspectUnusedCandidateSameFileUse();
         const int batchSize = UnusedPublicOverfetchMaximum;
         for (var bucket = 0; bucket <= 3; bucket++)
         {
@@ -1117,7 +1051,7 @@ private UnusedCountResult CountUnusedSymbolsDetailedWithoutSqlResolver(string? k
                 offset += batch.Count;
                 foreach (var candidate in batch)
                 {
-                    if (HasPrivateCSharpUse(candidate, fileContentByFileId))
+                    if (HasSameFilePrivateUse(candidate, fileContentByFileId, canInspectSameFileUse))
                         continue;
 
                     var result = CreateUnusedSymbolResult(candidate);
@@ -1305,6 +1239,7 @@ private QueryCountResult CountUnusedSymbolsWithoutSqlResolver(string? kind, stri
         var count = 0;
         var paths = new HashSet<string>(StringComparer.Ordinal);
         var fileContentByFileId = new Dictionary<long, string>();
+        var canInspectSameFileUse = CanInspectUnusedCandidateSameFileUse();
         const int batchSize = UnusedPublicOverfetchMaximum;
         for (var bucket = 0; bucket <= 3; bucket++)
         {
@@ -1319,7 +1254,7 @@ private QueryCountResult CountUnusedSymbolsWithoutSqlResolver(string? kind, stri
                 offset += batch.Count;
                 foreach (var candidate in batch)
                 {
-                    if (HasPrivateCSharpUse(candidate, fileContentByFileId))
+                    if (HasSameFilePrivateUse(candidate, fileContentByFileId, canInspectSameFileUse))
                         continue;
 
                     count++;
diff --git a/tests/CodeIndex.Tests/DbReaderUnusedCandidateQueryTests.cs b/tests/CodeIndex.Tests/DbReaderUnusedCandidateQueryTests.cs
index ca1269ca8..b6e40220e 100644
--- a/tests/CodeIndex.Tests/DbReaderUnusedCandidateQueryTests.cs
+++ b/tests/CodeIndex.Tests/DbReaderUnusedCandidateQueryTests.cs
@@ -26,6 +26,50 @@ public void UnusedCandidateQueries_MixedSqlScopePreservesProjectionAndCounts()
         Assert.Equal(1, detailedCount.BucketCounts["maybe_unused_nonpublic"]);
     }
 
+    [Fact]
+    public void UnusedCandidateQueries_CSharpPartialMemberUseMatchesSqlResolverModes()
+    {
+        var paths = SeedMixedPartialFamilyCandidates();
+
+        // The mixed scope contains a public SQL function, so SQL scope probing selects
+        // the resolver-aware route before the private visibility filter removes that row.
+        Assert.True(_reader.ScopeMayIncludeSqlSymbols(
+            "function", null, paths, null, excludeTests: false));
+        Assert.False(_reader.ScopeMayIncludeSqlSymbols(
+            "function", "csharp", paths, null, excludeTests: false));
+        var mixedResults = _reader.GetUnusedSymbols(
+            1, "function", null, paths, null, excludeTests: false,
+            visibilityFilters: ["private"]);
+        var csharpResults = _reader.GetUnusedSymbols(
+            1, "function", "csharp", paths, null, excludeTests: false,
+            visibilityFilters: ["private"]);
+        var mixedCount = _reader.CountUnusedSymbols(
+            "function", null, paths, null, excludeTests: false,
+            visibilityFilters: ["private"]);
+        var csharpCount = _reader.CountUnusedSymbols(
+            "function", "csharp", paths, null, excludeTests: false,
+            visibilityFilters: ["private"]);
+        var mixedDetailedCount = _reader.CountUnusedSymbolsDetailed(
+            "function", null, paths, null, excludeTests: false,
+            visibilityFilters: ["private"]);
+        var csharpDetailedCount = _reader.CountUnusedSymbolsDetailed(
+            "function", "csharp", paths, null, excludeTests: false,
+            visibilityFilters: ["private"]);
+
+        AssertUnusedResultParity(csharpResults, mixedResults);
+        var candidate = Assert.Single(csharpResults);
+        Assert.Equal("VisibleUnusedHelper", candidate.Name);
+        Assert.DoesNotContain(mixedResults, result => result.Name == "HiddenPartialHandler");
+        Assert.DoesNotContain(mixedResults, result => result.Lang == "sql");
+        Assert.Equal(new QueryCountResult(1, 1, IncludesSql: false), csharpCount);
+        Assert.Equal(csharpCount, mixedCount);
+        AssertUnusedDetailedCountParity(csharpDetailedCount, mixedDetailedCount);
+        Assert.Equal(
+            (csharpCount.Count, csharpCount.FileCount, csharpCount.IncludesSql),
+            (csharpDetailedCount.Count, csharpDetailedCount.FileCount, csharpDetailedCount.IncludesSql));
+        Assert.False(mixedDetailedCount.IncludesSql);
+    }
+
     private string[] SeedMixedUnusedCandidates()
     {
         var csharpFileId = CreateMixedCandidateFile("src/mixed_unused_scope.cs", "csharp", 12);
@@ -57,6 +101,85 @@ private string[] SeedMixedUnusedCandidates()
         return ["src/mixed_unused_scope.*"];
     }
 
+    private string[] SeedMixedPartialFamilyCandidates()
+    {
+        var ownerFileId = CreateMixedCandidateFile("src/mixed_partial_scope.owner.cs", "csharp", 6);
+        var peerFileId = CreateMixedCandidateFile("src/mixed_partial_scope.peer.cs", "csharp", 5);
+        var sqlFileId = CreateMixedCandidateFile("src/mixed_partial_scope.sql", "sql", 1);
+        _writer.InsertChunks(
+        [
+            new ChunkRecord
+            {
+                FileId = ownerFileId,
+                ChunkIndex = 0,
+                StartLine = 1,
+                EndLine = 6,
+                Content = """
+                    namespace Fixtures;
+                    internal partial class MixedPartialHost
+                    {
+                        private void HiddenPartialHandler() { }
+                        private void VisibleUnusedHelper() { }
+                    }
+                    """,
+            },
+            new ChunkRecord
+            {
+                FileId = peerFileId,
+                ChunkIndex = 0,
+                StartLine = 1,
+                EndLine = 5,
+                Content = """
+                    namespace Fixtures;
+                    internal partial class MixedPartialHost
+                    {
+                        private void Wire() => HiddenPartialHandler();
+                    }
+                    """,
+            },
+            new ChunkRecord
+            {
+                FileId = sqlFileId,
+                ChunkIndex = 0,
+                StartLine = 1,
+                EndLine = 1,
+                Content = "CREATE PROCEDURE dbo.PublicPartialScope AS SELECT 1;",
+            },
+        ]);
+        _writer.InsertSymbols(
+        [
+            CreateMixedPartialType(ownerFileId, endLine: 6),
+            CreateMixedPartialType(peerFileId, endLine: 5),
+            CreateMixedCandidate(
+                ownerFileId, "HiddenPartialHandler", 4, 4,
+                "private void HiddenPartialHandler()", "private", "void",
+                "class", "MixedPartialHost", "Fixtures.MixedPartialHost"),
+            CreateMixedCandidate(
+                ownerFileId, "VisibleUnusedHelper", 5, 5,
+                "private void VisibleUnusedHelper()", "private", "void",
+                "class", "MixedPartialHost", "Fixtures.MixedPartialHost"),
+            CreateMixedCandidate(
+                sqlFileId, "dbo.PublicPartialScope", 1, 1,
+                "CREATE PROCEDURE dbo.PublicPartialScope", "public"),
+        ]);
+        return ["src/mixed_partial_scope.*"];
+    }
+
+    private static SymbolRecord CreateMixedPartialType(long fileId, int endLine) => new()
+    {
+        FileId = fileId,
+        Kind = "class",
+        Name = "MixedPartialHost",
+        Line = 2,
+        StartLine = 2,
+        EndLine = endLine,
+        Signature = "internal partial class MixedPartialHost",
+        Visibility = "internal",
+        ContainerKind = "namespace",
+        ContainerName = "Fixtures",
+        ContainerQualifiedName = "Fixtures",
+    };
+
     private void InsertMixedCandidateChunks(long csharpFileId, long sqlFileId) =>
         _writer.InsertChunks(
         [
@@ -143,4 +266,51 @@ private static void AssertMixedSqlCandidate(UnusedSymbolResult candidate)
         Assert.Null(candidate.ContainerName);
         Assert.Equal("maybe_unused_nonpublic", candidate.UnusedBucket);
     }
+
+    private static void AssertUnusedResultParity(
+        IReadOnlyList<UnusedSymbolResult> expected,
+        IReadOnlyList<UnusedSymbolResult> actual)
+    {
+        static object Project(UnusedSymbolResult result) => new
+        {
+            result.Path,
+            result.Lang,
+            result.Kind,
+            result.Name,
+            result.Line,
+            result.StartLine,
+            result.EndLine,
+            result.Signature,
+            result.Visibility,
+            result.ReturnType,
+            result.ContainerKind,
+            result.ContainerName,
+            result.UnusedBucket,
+            result.UnusedConfidence,
+            result.UnusedReason,
+            ReasonTags = string.Join('\n', result.UnusedReasonTags ?? []),
+            result.UnusedContractDomain,
+            ContractDomainTags = string.Join('\n', result.UnusedContractDomainTags ?? []),
+        };
+
+        Assert.Equal(expected.Select(Project), actual.Select(Project));
+    }
+
+    private static void AssertUnusedDetailedCountParity(
+        UnusedCountResult expected,
+        UnusedCountResult actual)
+    {
+        Assert.Equal(
+            (expected.Count, expected.FileCount, expected.IncludesSql),
+            (actual.Count, actual.FileCount, actual.IncludesSql));
+        Assert.Equal(
+            expected.BucketCounts.OrderBy(pair => pair.Key),
+            actual.BucketCounts.OrderBy(pair => pair.Key));
+        Assert.Equal(
+            expected.ConfidenceCounts.OrderBy(pair => pair.Key),
+            actual.ConfidenceCounts.OrderBy(pair => pair.Key));
+        Assert.Equal(
+            expected.ContractDomainCounts.OrderBy(pair => pair.Key),
+            actual.ContractDomainCounts.OrderBy(pair => pair.Key));
+    }
 }
diff --git a/tests/CodeIndex.Tests/LegacySchemaMigrationTests.cs b/tests/CodeIndex.Tests/LegacySchemaMigrationTests.cs
index a9ddee548..c65b53ce8 100644
--- a/tests/CodeIndex.Tests/LegacySchemaMigrationTests.cs
+++ b/tests/CodeIndex.Tests/LegacySchemaMigrationTests.cs
@@ -792,7 +792,8 @@ CREATE TABLE symbols (
                         body_start_line INTEGER,
                         body_end_line INTEGER,
                         end_line INTEGER,
-                        signature TEXT
+                        signature TEXT,
+                        visibility TEXT
                     )
                     """);
                 Exec(seed, """
@@ -809,6 +810,32 @@ container_name TEXT
                     )
                     """);
                 Exec(seed, "INSERT INTO files (id, path, lang) VALUES (1, 'src/LegacyGraph.cs', 'csharp')");
+                Exec(seed, """
+                    INSERT INTO symbols (
+                        id,
+                        file_id,
+                        name,
+                        kind,
+                        line,
+                        body_start_line,
+                        body_end_line,
+                        end_line,
+                        signature,
+                        visibility
+                    )
+                    VALUES (
+                        1,
+                        1,
+                        'LegacyUnused',
+                        'function',
+                        2,
+                        2,
+                        2,
+                        2,
+                        'private void LegacyUnused()',
+                        'private'
+                    )
+                    """);
                 Exec(seed, """
                     INSERT INTO symbol_references (
                         id,
@@ -842,6 +869,18 @@ INSERT INTO symbol_references (
             db.TryMigrateForRead();
 
             var reader = new DbReader(db);
+            Assert.Equal(
+                "LegacyUnused",
+                Assert.Single(reader.GetUnusedSymbols(
+                    10, "function", "csharp", null, null, excludeTests: false)).Name);
+            Assert.Equal(
+                new QueryCountResult(1, 1),
+                reader.CountUnusedSymbols(
+                    "function", "csharp", null, null, excludeTests: false));
+            Assert.Equal(
+                1,
+                reader.CountUnusedSymbolsDetailed(
+                    "function", "csharp", null, null, excludeTests: false).Count);
             var reference = Assert.Single(
                 reader.SearchReferences("GetString", lang: "csharp", exact: true));
             Assert.Equal("Run", reference.ContainerName);

From b4e4fbc4b5182f29f505569ff5d883fc91f735ca Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 18:27:01 +0900
Subject: [PATCH 43/45] Consolidate full-scan extraction session ownership

---
 TESTING_GUIDE.md                              |   4 +
 .../+full-scan-extraction-state.fixed.md      |  15 +
 ...mmandRunner.FullScan.ExtractionPipeline.cs | 672 +++++++++++-------
 ...ommandRunner.FullScan.ExtractionWorkers.cs |  45 +-
 ...xCommandRunner.FullScan.FilePersistence.cs |   8 +-
 ...ndexCommandRunner.FullScan.Interruption.cs |   4 +-
 ...xCommandRunner.FullScan.PreWriteSession.cs |   1 +
 .../IndexCommandRunner.FullScan.Progress.cs   |  28 +-
 ...exCommandRunner.FullScan.ResultConsumer.cs | 664 ++++++++---------
 .../Cli/IndexCommandRunner.FullScan.cs        | 274 +++----
 src/CodeIndex/Cli/IndexCommandRunner.cs       |   1 +
 .../IndexCommandRunnerFullScanTests.cs        | 204 +++++-
 12 files changed, 1079 insertions(+), 841 deletions(-)
 create mode 100644 changelog.d/unreleased/+full-scan-extraction-state.fixed.md

diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index e63ad9e2a..bae41c94c 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -443,6 +443,8 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   cover multi-frame remainder reuse, CRLF split across a 4 KiB read boundary, Unicode bytes, an unterminated final frame, stable EOF, and rejection at one byte over the negotiated cap. They protect direct worker-response deserialization without constructing decoded JSON strings.
 - `IndexCommandRunnerTests`, `FileIndexerTests`, and `PerformanceTests` also cover `CSharpStaticInterfacePrepass` text, raw-byte, chunked raw-token, and streaming file contract probes. Stable candidate reads must authorize and open each file once, keep raw-negative reads to one bounded pass, and rewind that same handle only for a raw-positive full decode. A detected in-place or atomic-replacement mutation must discard that snapshot and reauthorize/reopen once so the prepass cannot diverge from the main indexing pass. Preserve UTF-8 / UTF-16, NUL rejection, growth, cancellation, and lexical-boundary behavior. The 576 KiB semantic-negative/positive allocation guard runs each probe 12 times and stays below 4 KiB of current-thread allocation so a whole-content mask cannot return.
 - The parallel C# static-interface full-scan fixture uses 64 implementation files and treats one workspace lookup build as a performance contract. Keep the contract lookup attached to the immutable prepass snapshot across CLI full scan, scoped update, and MCP indexing; do not rebuild it once per C# file.
+- `Run_FullScan_PostPrepassCsharpContractLeavesReadinessPartialUntilCleanRetry` keeps the full-scan extraction state monotonic across fresh, rebuild, and incremental-existing routes. Its ordered Python-before-C# fixture must prove that the earlier raw chunk persists and remains searchable through both standard and trigram FTS after the later C# workspace snapshot drifts, with exactly one bulk-load optimization.
+- `Run_FullScan_FatalParallelResultKeepsWorkerResourcesAliveUntilPeersStop` blocks one C# symbols worker while a peer reports a fatal extraction stall. Keep the command return prompt, assert that neither worker completion nor artifact-cache clearing occurs before the blocked peer is released, and wait for both cleanup signals before restoring process-wide hooks or deleting the fixture.
 - `CSharpPrepassSymbolArtifactCacheTests`, `FileIndexerTests`, and the CLI/MCP fresh-index fixtures protect bounded prepass artifact reuse. Keep deep-clone independence for generic admission; production owned-list admission must retain list/symbol identity only after successful atomic publication, leave rejected or cancelled input caller-owned, and release workspace fallback symbols only after both lookup snapshots are materialized. Preserve lookup parity and mutation isolation, take-once checksum matching, mismatch consumption, atomic file/symbol/estimated-byte caps, cancellation without partial admission, and non-admission of partial symbols after any bounded-regex timeout. Encoding theories must compare UTF-8, UTF-16 LE/BE, and invalid-UTF-8 prepass checksums with the authoritative loader. Integration coverage must prove reuse only for an empty non-rebuild full index, ordinary extraction for rebuild/symbols-only/existing/incomplete-or-stall paths, authoritative main-read mutation fallback, unchanged post hooks and family/kind processing, and cache clearing before graph work.
 - `SymbolExtractorRequiredLiteralGateTests` keeps built-in required-literal gating deterministic and
   output-preserving. It pins 400 audited Tier A patterns across 51 case-sensitive languages, compares
@@ -1511,6 +1513,8 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   multi-frame remainder の再利用、4 KiB read 境界をまたぐ CRLF、Unicode byte、改行なし最終 frame、安定した EOF、合意済み上限を1 byte 超えた時点での拒否を検証します。decode 済み JSON string を作らず worker response を直接 deserialize する経路を固定します。
 - `IndexCommandRunnerTests`、`FileIndexerTests`、`PerformanceTests` は `CSharpStaticInterfacePrepass` のテキスト判定、raw-byte、chunked raw-token、streaming file 契約 probe も扱います。安定した候補読み取りは各 file を1回だけ認可・openし、raw-negative は bounded pass 1回に留め、raw-positive の full decode だけ同じ handle を rewind してください。in-place mutation または atomic replacement を検知した場合は snapshot を破棄し、prepass と main indexing pass が乖離しないよう1回だけ再認可・再openします。UTF-8 / UTF-16、NUL 拒否、growth、cancellation、lexical boundary を維持してください。576 KiB の semantic-negative/positive allocation guard は各 probe を12回実行して current-thread allocation を4 KiB未満に保ち、content 全体 mask の再導入を防ぎます。
 - parallel C# static-interface full-scan fixture は64個のimplementation fileを使い、workspace lookup buildが1回であることをperformance contractとします。CLI full scan、scoped update、MCP indexingを横断してcontract lookupをimmutable prepass snapshotに保持し、C# fileごとの再構築を戻さないでください。
+- `Run_FullScan_PostPrepassCsharpContractLeavesReadinessPartialUntilCleanRetry` は fresh、rebuild、incremental-existing の各 route で full-scan extraction state が単調に維持されることを固定します。Python を C# より先に処理する fixture で、後段の C# workspace snapshot drift 後も先行 raw chunk が保存され、standard / trigram FTS の両方から検索でき、bulk-load optimization が厳密に1回であることを証明してください。
+- `Run_FullScan_FatalParallelResultKeepsWorkerResourcesAliveUntilPeersStop` は一方の C# symbols worker を block し、peer に fatal extraction stall を返させます。command が速やかに戻ること、block 中の peer を release する前に worker completion と artifact-cache clear のどちらも起きないことを assertion し、process-wide hook の復元や fixture 削除の前に両 cleanup signal を待ってください。
 - `CSharpPrepassSymbolArtifactCacheTests`、`FileIndexerTests`、CLI/MCP の fresh-index fixture は bounded prepass artifact reuse を固定します。汎用 admission の deep-clone 独立性を維持し、production の owned-list admission は原子的な publish 成功後だけ list / symbol identity を保持し、reject または cancel された input は caller-owned のままにしてください。2種類の lookup snapshot を materialize した後だけ workspace fallback symbol を解放し、lookup parity と mutation isolation を保ちます。checksum 一致時の take-once、不一致時の消費、file / symbol / estimated-byte cap の原子性、partial admission を残さない cancellation、bounded-regex timeout 後の partial symbol をadmitしない契約も維持してください。encoding theory は UTF-8、UTF-16 LE/BE、不正 UTF-8 の prepass checksum を authoritative loader と比較します。integration coverage では空 database の非 rebuild full index だけが再利用し、rebuild / symbols-only / existing / incomplete-or-stall 経路は通常 extraction、main read 中の mutation は checksum fallback、post hook と family/kind 処理は従来どおり、graph 開始前に cache が clear されることを証明してください。
 - `SymbolExtractorRequiredLiteralGateTests` は built-in required-literal gate の決定性と output
   不変性を固定します。51 の case-sensitive 言語にまたがる監査済み Tier A pattern 400件、出力順を
diff --git a/changelog.d/unreleased/+full-scan-extraction-state.fixed.md b/changelog.d/unreleased/+full-scan-extraction-state.fixed.md
new file mode 100644
index 000000000..5891f6f86
--- /dev/null
+++ b/changelog.d/unreleased/+full-scan-extraction-state.fixed.md
@@ -0,0 +1,15 @@
+---
+category: fixed
+affected:
+  - src/CodeIndex/Cli/IndexCommandRunner.FullScan.ExtractionPipeline.cs
+  - src/CodeIndex/Cli/IndexCommandRunner.FullScan.ResultConsumer.cs
+  - tests/CodeIndex.Tests/IndexCommandRunnerFullScanTests.cs
+---
+
+## English
+
+- **Full-scan extraction now preserves shared state and worker-resource ownership** — a later C# workspace drift no longer drops text-index mutations already committed for earlier files, and a fatal parallel worker result defers shared queue, cache, hook, and cancellation cleanup until every peer worker has stopped.
+
+## 日本語
+
+- **full-scan extraction が共有 state と worker resource の ownership を保持するようになりました** — 後段の C# workspace drift が先行 file で commit 済みの text-index mutation を失わず、parallel worker の fatal result では全 peer worker の停止まで共有 queue、cache、hook、cancellation の cleanup を延期します。
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ExtractionPipeline.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ExtractionPipeline.cs
index fdce89410..cb8fe31f6 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ExtractionPipeline.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ExtractionPipeline.cs
@@ -10,113 +10,271 @@ namespace CodeIndex.Cli;
 
 public static partial class IndexCommandRunner
 {
-    private sealed class FullScanExtractionPipelineContext
+    private readonly record struct FullScanExtractionCore(
+        DbWriter Writer,
+        FileIndexer Indexer,
+        IndexCommandOptions Options,
+        string ProjectRoot,
+        FullScanFileTarget[] FileTargets,
+        ReadableFileByteTracker ReadableFileBytes,
+        IndexProgressReporter IndexProgress,
+        FullScanProgressSession FullScanProgress);
+
+    private readonly record struct FullScanExtractionWork(
+        List<int>? FileIndexes,
+        int ItemCount,
+        int Parallelism,
+        int FilesCount,
+        bool ForceExtractorRefresh,
+        DbWriter.AuthoritativeFreshFoldRowsClaim? AuthoritativeFreshFoldRowsClaim,
+        CancellationToken CancellationToken,
+        string ActualMode);
+
+    private readonly record struct FullScanExtractionContracts(
+        bool PriorSymbolsOnlyGraphOmitted,
+        bool SymbolKindFilterMatchesPrior,
+        bool CSharpIndexedProjectRootCompatible,
+        bool CSharpSymbolNameContractMatchesCurrent,
+        bool SqlGraphContractMatchesCurrent,
+        bool HdlGraphContractMatchesCurrent,
+        bool StartedWithNoIndexedFiles);
+
+    private readonly record struct FullScanExtractionReuse(
+        bool JavaScriptTypeScriptRefreshRequired,
+        IReadOnlyDictionary<string, bool> HotspotFamilyTrustMatchesCurrent);
+
+    private struct FullScanExtractionRefreshState
+    {
+        internal bool FtsMutated { get; set; }
+        internal bool MutualRecursionRefreshNeeded { get; set; }
+        internal bool CSharpMetadataTargetsNeedRefresh { get; set; }
+        internal int SymbolsDroppedByKindFilter { get; set; }
+        internal HashSet<string>? ReusedHotspotFamilyLanguages { get; set; }
+        internal HashSet<string>? SkippedSymbolExtractorLanguages { get; set; }
+        internal HashSet<string> IndexedSymbolExtractorLanguages { get; set; }
+    }
+
+    private struct FullScanExtractionCounts
+    {
+        internal int Processed { get; set; }
+        internal int Skipped { get; set; }
+        internal int Warnings { get; set; }
+        internal int Errors { get; set; }
+        internal long ExtractedFiles { get; set; }
+        internal long ExtractedChunks { get; set; }
+        internal long ExtractedSymbols { get; set; }
+        internal long ExtractedReferences { get; set; }
+    }
+
+    private struct FullScanExtractionPersistenceCounts
     {
-        internal required DbWriter Writer { get; init; }
-        internal required FileIndexer Indexer { get; init; }
-        internal required IndexCommandOptions Options { get; init; }
-        internal required string ProjectRoot { get; init; }
-        internal required FullScanFileTarget[] FileTargets { get; init; }
-        internal List<int>? ExtractionFileIndexes { get; init; }
-        internal required int ExtractionWorkItemCount { get; init; }
-        internal required int ExtractionParallelism { get; init; }
-        internal required int FilesCount { get; init; }
-        internal required bool ForceExtractorRefresh { get; init; }
-        internal required bool StartedWithNoIndexedFiles { get; init; }
+        internal long PersistedFiles { get; set; }
+        internal long PersistedChunks { get; set; }
+        internal long PersistedSymbols { get; set; }
+        internal long PersistedReferences { get; set; }
+        internal long FreshFiles { get; set; }
+        internal long FreshChunks { get; set; }
+        internal long FreshSymbols { get; set; }
+        internal long FreshReferences { get; set; }
+    }
+
+    private readonly record struct FullScanExtractionRequest(
+        FullScanExtractionCore Core,
+        FullScanExtractionWork Work,
+        FullScanExtractionContracts Contracts,
+        FullScanExtractionReuse Reuse);
+
+    private sealed class FullScanExtractionState
+    {
+        internal required FullScanPreWriteState PreWrite { get; init; }
+        internal FullScanExtractionRefreshState Refresh;
+        internal FullScanExtractionCounts Counts;
+        internal FullScanExtractionPersistenceCounts PersistenceCounts;
+    }
+
+    private readonly record struct FullScanExtractionExternalOperations(
+        Action RequireTypeScriptAugmentationRefresh,
+        Action WriteProjectRootOnce);
+
+    private sealed partial class FullScanExtractionSession
+    {
+        internal required FullScanExtractionRequest Request { get; init; }
+        internal required FullScanExtractionState State { get; init; }
+        internal required FullScanExtractionExternalOperations External { get; init; }
+        internal FullScanExtractionWorkerResources? Lifetime { get; set; }
+
+        private FullScanExtractionCore Core => Request.Core;
+        private FullScanExtractionWork Work => Request.Work;
+        private FullScanExtractionContracts Contracts => Request.Contracts;
+        private FullScanExtractionReuse Reuse => Request.Reuse;
+        internal FullScanPreWriteState PreWriteState => State.PreWrite;
+        internal DbWriter Writer => Core.Writer;
+        internal FileIndexer Indexer => Core.Indexer;
+        internal IndexCommandOptions Options => Core.Options;
+        internal string ProjectRoot => Core.ProjectRoot;
+        internal FullScanFileTarget[] FileTargets => Core.FileTargets;
+        internal ReadableFileByteTracker ReadableFileBytes => Core.ReadableFileBytes;
+        internal IndexProgressReporter IndexProgress => Core.IndexProgress;
+        internal FullScanProgressSession FullScanProgress => Core.FullScanProgress;
+        internal List<int>? ExtractionFileIndexes => Work.FileIndexes;
+        internal int ExtractionWorkItemCount => Work.ItemCount;
+        internal int ExtractionParallelism => Work.Parallelism;
+        internal int FilesCount => Work.FilesCount;
+        internal bool ForceExtractorRefresh => Work.ForceExtractorRefresh;
+        internal bool StartedWithNoIndexedFiles => Contracts.StartedWithNoIndexedFiles;
         internal DbWriter.AuthoritativeFreshFoldRowsClaim? AuthoritativeFreshFoldRowsClaim
+            => Work.AuthoritativeFreshFoldRowsClaim;
+        internal CancellationToken CancellationToken => Work.CancellationToken;
+        internal bool PriorSymbolsOnlyGraphOmitted => Contracts.PriorSymbolsOnlyGraphOmitted;
+        internal bool SymbolKindFilterMatchesPrior => Contracts.SymbolKindFilterMatchesPrior;
+        internal bool CSharpIndexedProjectRootCompatible
+            => Contracts.CSharpIndexedProjectRootCompatible;
+        internal bool CSharpSymbolNameContractMatchesCurrent
+            => Contracts.CSharpSymbolNameContractMatchesCurrent;
+        internal bool SqlGraphContractMatchesCurrent => Contracts.SqlGraphContractMatchesCurrent;
+        internal bool HdlGraphContractMatchesCurrent => Contracts.HdlGraphContractMatchesCurrent;
+        internal int ProcessedCount
         {
-            get;
-            init;
+            get => PreWriteState.Selection.Processed;
+            set => PreWriteState.Selection.Processed = value;
         }
-        internal required bool PriorSymbolsOnlyGraphOmitted { get; init; }
-        internal required bool SymbolKindFilterMatchesPrior { get; init; }
-        internal required bool CSharpIndexedProjectRootCompatible
+        internal bool IndexProgressVisible
         {
-            get;
-            init;
+            get => FullScanProgress.IndexProgressVisible;
+            set => FullScanProgress.IndexProgressVisible = value;
         }
-
-        internal required bool CSharpSymbolNameContractMatchesCurrent
+        internal ActiveExtractionPhase?[] ActiveExtractionPhases
         {
-            get;
-            init;
+            get => FullScanProgress.ActiveExtractionPhases;
+            set => FullScanProgress.ActiveExtractionPhases = value;
         }
-
-        internal required bool SqlGraphContractMatchesCurrent { get; init; }
-        internal required bool HdlGraphContractMatchesCurrent { get; init; }
-        internal required ReadableFileByteTracker ReadableFileBytes
+        internal string? CurrentJsonIndexFile
         {
-            get;
-            init;
+            get => FullScanProgress.CurrentJsonIndexFile;
+            set => FullScanProgress.CurrentJsonIndexFile = value;
         }
+        internal bool DeferCSharpMutationsForIncompleteScan
+            => PreWriteState.Scan.DeferCSharpMutationsForIncompleteScan;
+        internal CSharpStaticInterfaceWorkspaceSymbols CSharpWorkspace
+            => PreWriteState.CSharp.Workspace;
+        internal CSharpPrepassSymbolArtifactCache? CSharpPrepassSymbolArtifacts
+            => PreWriteState.CSharp.PrepassSymbolArtifacts;
+        internal Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?
+            CSharpWorkspaceFileSnapshots
+            => PreWriteState.CSharp.WorkspaceFileSnapshots;
+        internal Action RequireTypeScriptAugmentationRefresh
+            => External.RequireTypeScriptAugmentationRefresh;
+        internal Action WriteProjectRootOnce => External.WriteProjectRootOnce;
+        internal int Processed { get => State.Counts.Processed; set => State.Counts.Processed = value; }
+        internal int Skipped { get => State.Counts.Skipped; set => State.Counts.Skipped = value; }
+        internal int Warnings { get => State.Counts.Warnings; set => State.Counts.Warnings = value; }
+        internal int ErrorsAdded { get => State.Counts.Errors; set => State.Counts.Errors = value; }
+        internal long ExtractedFiles { get => State.Counts.ExtractedFiles; set => State.Counts.ExtractedFiles = value; }
+        internal long ExtractedChunks { get => State.Counts.ExtractedChunks; set => State.Counts.ExtractedChunks = value; }
+        internal long ExtractedSymbols { get => State.Counts.ExtractedSymbols; set => State.Counts.ExtractedSymbols = value; }
+        internal long ExtractedReferences { get => State.Counts.ExtractedReferences; set => State.Counts.ExtractedReferences = value; }
+        internal bool FtsMutated { get => State.Refresh.FtsMutated; set => State.Refresh.FtsMutated = value; }
+        internal bool MutualRecursionRefreshNeeded { get => State.Refresh.MutualRecursionRefreshNeeded; set => State.Refresh.MutualRecursionRefreshNeeded = value; }
+        internal bool CSharpMetadataTargetsNeedRefresh { get => State.Refresh.CSharpMetadataTargetsNeedRefresh; set => State.Refresh.CSharpMetadataTargetsNeedRefresh = value; }
+        internal int SymbolsDroppedByKindFilter { get => State.Refresh.SymbolsDroppedByKindFilter; set => State.Refresh.SymbolsDroppedByKindFilter = value; }
+        internal HashSet<string>? ReusedHotspotFamilyLanguages { get => State.Refresh.ReusedHotspotFamilyLanguages; set => State.Refresh.ReusedHotspotFamilyLanguages = value; }
+        internal HashSet<string>? SkippedSymbolExtractorLanguages { get => State.Refresh.SkippedSymbolExtractorLanguages; set => State.Refresh.SkippedSymbolExtractorLanguages = value; }
+        internal HashSet<string> IndexedSymbolExtractorLanguages => State.Refresh.IndexedSymbolExtractorLanguages;
+        internal List<CliJsonMessage> ErrorList => PreWriteState.Diagnostics.ErrorList;
+        internal List<StatusIndexFileError> FileErrorList => PreWriteState.Diagnostics.FileErrorList;
+        internal List<CliJsonMessage> WarningList => PreWriteState.Diagnostics.WarningList;
+
+        internal bool TargetRequiresJavaScriptTypeScriptRefresh(
+            string? language,
+            string indexPath)
+            => Reuse.JavaScriptTypeScriptRefreshRequired
+               && (IsJavaScriptTypeScriptLanguage(language)
+                   || IsJavaScriptTypeScriptConfigPath(indexPath));
 
-        internal required IndexProgressReporter IndexProgress { get; init; }
-        internal required FullScanProgressSession FullScanProgress { get; init; }
-        internal required CancellationToken CancellationToken { get; init; }
-        internal required Func<int> GetProcessedCount { get; init; }
-        internal required Action<int> PublishProcessedCount { get; init; }
-        internal required Action<int, int?> ThrowIfFullScanCancelled
+        internal bool AllowReuseWithCurrentHotspotFamilyTrust(string? language)
+            => IndexCommandRunner.AllowReuseWithCurrentHotspotFamilyTrust(
+                language,
+                Reuse.HotspotFamilyTrustMatchesCurrent);
+
+        internal void InsertIssuesForIndexedFile(
+            long fileId,
+            IReadOnlyList<FileIssue> issues)
         {
-            get;
-            init;
+            if (StartedWithNoIndexedFiles)
+                Writer.InsertIssuesForNewFile(fileId, issues);
+            else
+                Writer.InsertIssues(fileId, issues);
         }
 
-        internal required Action<bool> SetIndexProgressVisible { get; init; }
-        internal required Action<ActiveExtractionPhase?[]>
-            SetActiveExtractionPhases
-        { get; init; }
-        internal required Action<string?> SetCurrentJsonIndexFile { get; init; }
-        internal required Func<string?> GetCurrentJsonIndexFile { get; init; }
-        internal required Func<bool>
-            GetDeferCSharpMutationsForIncompleteScan
-        { get; init; }
-        internal required Func<bool> GetFtsMutated { get; init; }
-        internal required Func<CSharpStaticInterfaceWorkspaceSymbols>
-            GetCSharpWorkspace
-        { get; init; }
-        internal required Func<CSharpPrepassSymbolArtifactCache?>
-            GetCSharpPrepassSymbolArtifacts
-        { get; init; }
-        internal required Func<Dictionary<string,
-            CSharpStaticInterfacePrepass.FileStatSnapshot>?>
-            GetCSharpWorkspaceFileSnapshots
-        { get; init; }
-        internal required Action<string>
-            DeferCSharpMutationsForLoadedSnapshotDrift
-        { get; init; }
-        internal required Func<string?, string, bool>
-            TargetRequiresJavaScriptTypeScriptRefresh
-        { get; init; }
-        internal required Func<string?, bool>
-            AllowReuseWithCurrentHotspotFamilyTrust
-        { get; init; }
-        internal required Action RequireTypeScriptAugmentationRefresh
+        internal void CountFreshInsertedRows(
+            int chunkCount,
+            int symbolCount,
+            int referenceCount)
         {
-            get;
-            init;
+            State.PersistenceCounts.PersistedFiles++;
+            State.PersistenceCounts.PersistedChunks += chunkCount;
+            State.PersistenceCounts.PersistedSymbols += symbolCount;
+            State.PersistenceCounts.PersistedReferences += referenceCount;
+            if (!StartedWithNoIndexedFiles)
+                return;
+
+            State.PersistenceCounts.FreshFiles++;
+            State.PersistenceCounts.FreshChunks += chunkCount;
+            State.PersistenceCounts.FreshSymbols += symbolCount;
+            State.PersistenceCounts.FreshReferences += referenceCount;
         }
 
-        internal required Action WriteProjectRootOnce { get; init; }
-        internal required Action<long, IReadOnlyList<FileIssue>>
-            InsertIssuesForIndexedFile
-        { get; init; }
-        internal required Action<int, int, int> CountFreshInsertedRows
+        internal void ThrowIfFullScanCancelled(int filesProcessed, int? filesTotal)
         {
-            get;
-            init;
+            if (!CancellationToken.IsCancellationRequested)
+                return;
+
+            throw new IndexInterruptedException(
+                filesProcessed,
+                filesTotal,
+                Work.ActualMode);
         }
 
-        internal required FullScanExtractionConsumerState ConsumerState
+        internal void DeferCSharpMutationsForLoadedSnapshotDrift(string path)
         {
-            get;
-            init;
+            Lifetime?.TakeCSharpArtifacts()?.Clear();
+            var scan = PreWriteState.Scan;
+            var csharp = PreWriteState.CSharp;
+            csharp.PrepassSymbolArtifacts = null;
+            path = FormatCSharpWorkspaceSnapshotPath(ProjectRoot, path);
+            scan.DeferCSharpMutationsForIncompleteScan = true;
+            csharp.PreservePriorPositiveSourceNoOp = false;
+            csharp.Evidence.ForStamp = false;
+            csharp.Evidence.Complete = false;
+            csharp.WorkspaceFileSnapshots = null;
+            csharp.Workspace = new CSharpStaticInterfaceWorkspaceSymbols(
+                [],
+                HasStaticInterfaceContracts: true,
+                SourceContractEvidenceComplete: false,
+                IncompleteSourcePaths: [path]);
+            Writer.SetCSharpStaticInterfaceSourceEvidence(null);
+
+            var diagnostics = PreWriteState.Diagnostics;
+            const string phase = "csharp_workspace_validation";
+            if (!diagnostics.ReportedCSharpWorkspaceFailures.Add(
+                    $"{phase}\n{path}"))
+            {
+                return;
+            }
+
+            var exception = new IOException(
+                "A C# source changed after workspace preflight; rerun indexing to refresh the complete C# graph.");
+            diagnostics.Errors++;
+            diagnostics.ErrorList.Add(
+                new CliJsonMessage(path, FormatIndexFileException(exception)));
+            if (diagnostics.FileErrorList.Count < PartialIndexFileErrorLimit)
+            {
+                diagnostics.FileErrorList.Add(
+                    BuildIndexFileError(path, phase, exception));
+            }
         }
     }
 
-    private sealed record FullScanExtractionPipelineResult(
-        PostExtractionHookRunner? PostExtractionHooks,
-        FullScanExtractionConsumerState? ConsumerState);
-
     private readonly record struct FullScanExtractionScheduling(
         bool Parallelize,
         string? Reason);
@@ -125,56 +283,143 @@ private readonly record struct FullScanExtractionTailCandidate(
         int WorkOrdinal,
         long? Length);
 
+    private sealed class FullScanExtractionWorkerResources(
+        CSharpPrepassSymbolArtifactCache? csharpPrepassSymbolArtifacts,
+        PostExtractionHookRunner postExtractionHooks)
+    {
+        private int disposed;
+        private Task workerCompletion = Task.CompletedTask;
+        private CSharpPrepassSymbolArtifactCache? csharpArtifacts =
+            csharpPrepassSymbolArtifacts;
+
+        internal BlockingCollection<FullScanFileWorkItem>? Results { get; private set; }
+        internal CancellationTokenSource? Cancellation { get; private set; }
+        internal LazyDisposable<SymbolExtractionWorkerClient>? SymbolExtractionWorker
+        { get; private set; }
+
+        internal void AttachResults(BlockingCollection<FullScanFileWorkItem> results)
+            => Results = results;
+
+        internal void AttachCancellation(CancellationTokenSource cancellation)
+            => Cancellation = cancellation;
+
+        internal void AttachSymbolExtractionWorker(
+            LazyDisposable<SymbolExtractionWorkerClient> symbolExtractionWorker)
+            => SymbolExtractionWorker = symbolExtractionWorker;
+
+        internal CSharpPrepassSymbolArtifactCache? TakeCSharpArtifacts()
+            => Interlocked.Exchange(ref csharpArtifacts, null);
+
+        internal void AttachWorkers(Task[] workers)
+        {
+            workerCompletion = Task.WhenAll(workers).ContinueWith(
+                task =>
+                {
+                    _ = task.Exception;
+                    try
+                    {
+                        Results?.CompleteAdding();
+                    }
+                    catch (ObjectDisposedException)
+                    {
+                    }
+                },
+                CancellationToken.None,
+                TaskContinuationOptions.ExecuteSynchronously,
+                TaskScheduler.Default);
+        }
+
+        internal void DisposeNowOrWhenWorkersStop()
+        {
+            var completion = workerCompletion;
+            if (completion.IsCompleted)
+            {
+                _ = completion.Exception;
+                DisposeResources();
+                return;
+            }
+
+            _ = completion.ContinueWith(
+                static (task, state) =>
+                {
+                    _ = task.Exception;
+                    ((FullScanExtractionWorkerResources)state!).DisposeResources();
+                },
+                this,
+                CancellationToken.None,
+                TaskContinuationOptions.ExecuteSynchronously,
+                TaskScheduler.Default);
+        }
+
+        private void DisposeResources()
+        {
+            if (Interlocked.Exchange(ref disposed, 1) != 0)
+                return;
+
+            try { TakeCSharpArtifacts()?.Clear(); } catch { }
+            try { postExtractionHooks.Dispose(); } catch { }
+            try { SymbolExtractionWorker?.Dispose(); } catch { }
+            try { Results?.Dispose(); } catch { }
+            try { Cancellation?.Dispose(); } catch { }
+            try { FullScanExtractionWorkersStoppedForTesting?.Invoke(); } catch { }
+        }
+    }
+
     private const int FullScanExtractionTailWorkerWaves = 4;
     internal const int MaxFullScanExtractionTailProbeCount = 64;
 
-    private static FullScanExtractionPipelineResult
+    private static PostExtractionHookRunner?
         RunFullScanExtractionPipeline(
-            FullScanExtractionPipelineContext context)
+            FullScanExtractionSession context)
     {
         if (context.ExtractionWorkItemCount == 0)
         {
-            context.GetCSharpPrepassSymbolArtifacts()?.Clear();
+            context.CSharpPrepassSymbolArtifacts?.Clear();
+            context.PreWriteState.CSharp.PrepassSymbolArtifacts = null;
             FullScanExtractionSchedulingForTesting?.Invoke(false, null);
-            return new FullScanExtractionPipelineResult(null, null);
+            return null;
         }
 
+        var csharpArtifacts = context.CSharpPrepassSymbolArtifacts;
         var postExtractionHooks = PostExtractionHookRunner.DiscoverDefault(
             context.Options.MaxFileSizeBytes,
             maxSymbolCount: context.Options.MaxSymbolsPerFile + 1,
             maxReferenceCount: context.Options.MaxReferencesPerFile + 1);
-        if (postExtractionHooks.HasHooks)
-            context.AuthoritativeFreshFoldRowsClaim?.Invalidate();
-        var scheduling = ResolveFullScanExtractionScheduling(
-            context,
+        var workerResources = new FullScanExtractionWorkerResources(
+            csharpArtifacts,
             postExtractionHooks);
-        FullScanExtractionSchedulingForTesting?.Invoke(
-            scheduling.Parallelize,
-            scheduling.Reason);
-        context.FullScanProgress.EnsureIndexingActivityVisible();
-        context.FullScanProgress.StartJsonHeartbeatIfNeeded();
+        context.Lifetime = workerResources;
         try
         {
-            var consumerState = ExecuteFullScanExtractionPipeline(
+            if (postExtractionHooks.HasHooks)
+                context.AuthoritativeFreshFoldRowsClaim?.Invalidate();
+            var scheduling = ResolveFullScanExtractionScheduling(
                 context,
+                postExtractionHooks);
+            FullScanExtractionSchedulingForTesting?.Invoke(
+                scheduling.Parallelize,
+                scheduling.Reason);
+            context.FullScanProgress.EnsureIndexingActivityVisible();
+            context.FullScanProgress.StartJsonHeartbeatIfNeeded();
+            ExecuteFullScanExtractionPipeline(
+                context,
+                workerResources,
                 postExtractionHooks,
                 scheduling.Parallelize);
-            return new FullScanExtractionPipelineResult(
-                postExtractionHooks,
-                consumerState);
+            return postExtractionHooks;
         }
         finally
         {
-            context.GetCSharpPrepassSymbolArtifacts()?.Clear();
-            context.SetCurrentJsonIndexFile(null);
+            workerResources.DisposeNowOrWhenWorkersStop();
+            context.Lifetime = null;
+            context.CurrentJsonIndexFile = null;
             context.FullScanProgress.StopJsonHeartbeat();
-            postExtractionHooks.Dispose();
         }
     }
 
     private static FullScanExtractionScheduling
         ResolveFullScanExtractionScheduling(
-            FullScanExtractionPipelineContext context,
+            FullScanExtractionSession context,
             PostExtractionHookRunner postExtractionHooks)
     {
         var parallelize = !context.Options.SymbolKindFilter.IsActive
@@ -281,9 +526,9 @@ internal static int ResolveFullScanExtractionFileIndex(
         return info.Exists ? info.Length : null;
     }
 
-    private static FullScanExtractionConsumerState
-        ExecuteFullScanExtractionPipeline(
-            FullScanExtractionPipelineContext context,
+    private static void ExecuteFullScanExtractionPipeline(
+            FullScanExtractionSession context,
+            FullScanExtractionWorkerResources workerResources,
             PostExtractionHookRunner postExtractionHooks,
             bool parallelizeExtraction)
     {
@@ -294,179 +539,92 @@ private static FullScanExtractionConsumerState
             context.ExtractionWorkItemCount);
         var activeExtractionPhases =
             new ActiveExtractionPhase?[extractionWorkerCount];
-        context.SetActiveExtractionPhases(activeExtractionPhases);
+        context.ActiveExtractionPhases = activeExtractionPhases;
         var extractionQueueCapacity = parallelizeExtraction
             ? Math.Max(1, extractionWorkerCount * 2)
             : 1;
         FullScanExtractionQueueCapacityForTesting?.Invoke(
             extractionQueueCapacity);
 
-        using var extractionResults =
+        var extractionResults =
             new BlockingCollection<FullScanFileWorkItem>(
                 extractionQueueCapacity);
-        using var extractionStallCts =
+        workerResources.AttachResults(extractionResults);
+        var extractionStallCts =
             CancellationTokenSource.CreateLinkedTokenSource(
                 context.CancellationToken);
-        using var mainSymbolExtractionWorker =
+        workerResources.AttachCancellation(extractionStallCts);
+        var mainSymbolExtractionWorker =
             new LazyDisposable<SymbolExtractionWorkerClient>(
                 () => new SymbolExtractionWorkerClient(
                     context.Options.MaxFileSizeBytes));
-        var extractionTailSchedule = parallelizeExtraction
-            ? BuildFullScanExtractionTailSchedule(
-                context.ExtractionWorkItemCount,
-                extractionWorkerCount,
-                context.Indexer.MaxFileSizeBytes,
-                workOrdinal => ReadFullScanExtractionFileLength(
-                    context.FileTargets[
-                        ResolveFullScanExtractionFileIndex(
-                            context.ExtractionFileIndexes,
-                            workOrdinal)].FilePath),
-                context.CancellationToken)
-            : [];
-        var workers = StartFullScanExtractionWorkers(
-            new FullScanExtractionWorkerContext
-            {
-                Indexer = context.Indexer,
-                Options = context.Options,
-                ProjectRoot = context.ProjectRoot,
-                FileTargets = context.FileTargets,
-                ExtractionFileIndexes =
-                    context.ExtractionFileIndexes,
-                ExtractionWorkItemCount =
+        workerResources.AttachSymbolExtractionWorker(mainSymbolExtractionWorker);
+        try
+        {
+            var extractionTailSchedule = parallelizeExtraction
+                ? BuildFullScanExtractionTailSchedule(
                     context.ExtractionWorkItemCount,
-                ExtractionWorkerCount = extractionWorkerCount,
-                ParallelizeExtraction = parallelizeExtraction,
-                ExtractionTailSchedule = extractionTailSchedule,
-                CSharpWorkspace = context.GetCSharpWorkspace(),
-                CSharpPrepassSymbolArtifacts =
-                    context.GetCSharpPrepassSymbolArtifacts(),
-                CSharpWorkspaceFileSnapshots =
-                    context.GetCSharpWorkspaceFileSnapshots(),
-                PostExtractionHooks = postExtractionHooks,
-                ActiveExtractionPhases = activeExtractionPhases,
-                ExtractionResults = extractionResults,
-                ExtractionCancellationToken =
-                    extractionStallCts.Token,
-                CancellationToken = context.CancellationToken,
-            });
-        CompleteFullScanExtractionQueueWhenWorkersFinish(
-            workers,
-            extractionResults);
-
-        var processedBeforeExtraction = context.GetProcessedCount();
-        var consumerContext = CreateFullScanExtractionConsumerContext(
-            context,
-            postExtractionHooks,
-            mainSymbolExtractionWorker.Value,
-            extractionResults,
-            extractionStallCts,
-            workers,
-            activeExtractionPhases,
-            processedBeforeExtraction);
-        var consumerState =
-            ConsumeFullScanExtractionResults(consumerContext);
-        context.PublishProcessedCount(
-            processedBeforeExtraction + consumerState.Processed);
-        return consumerState;
+                    extractionWorkerCount,
+                    context.Indexer.MaxFileSizeBytes,
+                    workOrdinal => ReadFullScanExtractionFileLength(
+                        context.FileTargets[
+                            ResolveFullScanExtractionFileIndex(
+                                context.ExtractionFileIndexes,
+                                workOrdinal)].FilePath),
+                    context.CancellationToken)
+                : [];
+            var workers = StartFullScanExtractionWorkers(
+                new FullScanExtractionWorkerContext
+                {
+                    Indexer = context.Indexer,
+                    Options = context.Options,
+                    ProjectRoot = context.ProjectRoot,
+                    FileTargets = context.FileTargets,
+                    ExtractionFileIndexes = context.ExtractionFileIndexes,
+                    ExtractionWorkItemCount = context.ExtractionWorkItemCount,
+                    ExtractionWorkerCount = extractionWorkerCount,
+                    ParallelizeExtraction = parallelizeExtraction,
+                    ExtractionTailSchedule = extractionTailSchedule,
+                    CSharpWorkspace = context.CSharpWorkspace,
+                    CSharpPrepassSymbolArtifacts = context.CSharpPrepassSymbolArtifacts,
+                    CSharpWorkspaceFileSnapshots = context.CSharpWorkspaceFileSnapshots,
+                    PostExtractionHooks = postExtractionHooks,
+                    ActiveExtractionPhases = activeExtractionPhases,
+                    ExtractionResults = extractionResults,
+                    ExtractionCancellationToken = extractionStallCts.Token,
+                    CancellationToken = context.CancellationToken,
+                },
+                workerResources.AttachWorkers);
+            var processedBeforeExtraction = context.ProcessedCount;
+            var consumerResources = new FullScanExtractionConsumerResources(
+                postExtractionHooks,
+                mainSymbolExtractionWorker.Value,
+                extractionResults,
+                workers,
+                IndexExtractionStallTimeoutForTesting?.Invoke()
+                    ?? IndexExtractionStallTimeout,
+                activeExtractionPhases,
+                extractionStallCts,
+                processedBeforeExtraction);
+            context.ConsumeFullScanExtractionResults(in consumerResources);
+            context.ProcessedCount = processedBeforeExtraction + context.State.Counts.Processed;
+        }
+        catch
+        {
+            try { extractionStallCts.Cancel(); } catch { }
+            throw;
+        }
     }
 
     private static void PrepareFullScanExtractionProgress(
-        FullScanExtractionPipelineContext context)
+        FullScanExtractionSession context)
     {
         if (context.Options.Json || context.Options.Quiet)
             return;
 
         context.IndexProgress.Pause();
-        context.SetIndexProgressVisible(true);
+        context.IndexProgressVisible = true;
         ConsoleUi.PrintProgress(0, context.FilesCount);
     }
 
-    private static void CompleteFullScanExtractionQueueWhenWorkersFinish(
-        Task[] workers,
-        BlockingCollection<FullScanFileWorkItem> extractionResults)
-    {
-        _ = Task.WhenAll(workers).ContinueWith(
-            _ => extractionResults.CompleteAdding(),
-            CancellationToken.None,
-            TaskContinuationOptions.ExecuteSynchronously,
-            TaskScheduler.Default);
-    }
-
-    private static FullScanExtractionConsumerContext
-        CreateFullScanExtractionConsumerContext(
-            FullScanExtractionPipelineContext context,
-            PostExtractionHookRunner postExtractionHooks,
-            SymbolExtractionWorkerClient symbolExtractionWorker,
-            BlockingCollection<FullScanFileWorkItem> extractionResults,
-            CancellationTokenSource extractionStallCts,
-            Task[] workers,
-            ActiveExtractionPhase?[] activeExtractionPhases,
-            int processedBeforeExtraction)
-        => new()
-        {
-            Writer = context.Writer,
-            Indexer = context.Indexer,
-            Options = context.Options,
-            ProjectRoot = context.ProjectRoot,
-            FileTargets = context.FileTargets,
-            FilesCount = context.FilesCount,
-            ProcessedBeforeExtraction = processedBeforeExtraction,
-            ForceExtractorRefresh = context.ForceExtractorRefresh,
-            StartedWithNoIndexedFiles =
-                context.StartedWithNoIndexedFiles,
-            PriorSymbolsOnlyGraphOmitted =
-                context.PriorSymbolsOnlyGraphOmitted,
-            SymbolKindFilterMatchesPrior =
-                context.SymbolKindFilterMatchesPrior,
-            CSharpIndexedProjectRootCompatible =
-                context.CSharpIndexedProjectRootCompatible,
-            CSharpSymbolNameContractMatchesCurrent =
-                context.CSharpSymbolNameContractMatchesCurrent,
-            SqlGraphContractMatchesCurrent =
-                context.SqlGraphContractMatchesCurrent,
-            HdlGraphContractMatchesCurrent =
-                context.HdlGraphContractMatchesCurrent,
-            ReadableFileBytes = context.ReadableFileBytes,
-            PostExtractionHooks = postExtractionHooks,
-            SymbolExtractionWorker = symbolExtractionWorker,
-            IndexProgress = context.IndexProgress,
-            ExtractionResults = extractionResults,
-            Workers = workers,
-            ExtractionStallTimeout =
-                IndexExtractionStallTimeoutForTesting?.Invoke()
-                ?? IndexExtractionStallTimeout,
-            ActiveExtractionPhases = activeExtractionPhases,
-            CancellationToken = context.CancellationToken,
-            CancelExtraction = extractionStallCts.Cancel,
-            EnsureIndexingActivityVisible =
-                context.FullScanProgress.EnsureIndexingActivityVisible,
-            ReportJsonIndexProgressIfNeeded =
-                context.FullScanProgress.ReportJsonIndexProgressIfNeeded,
-            ThrowIfFullScanCancelled =
-                context.ThrowIfFullScanCancelled,
-            PublishProcessedCount = context.PublishProcessedCount,
-            SetCurrentJsonIndexFile = context.SetCurrentJsonIndexFile,
-            GetCurrentJsonIndexFile = context.GetCurrentJsonIndexFile,
-            GetDeferCSharpMutationsForIncompleteScan =
-                context.GetDeferCSharpMutationsForIncompleteScan,
-            GetFtsMutated = context.GetFtsMutated,
-            GetCSharpWorkspace = context.GetCSharpWorkspace,
-            GetCSharpPrepassSymbolArtifacts =
-                context.GetCSharpPrepassSymbolArtifacts,
-            GetCSharpWorkspaceFileSnapshots =
-                context.GetCSharpWorkspaceFileSnapshots,
-            DeferCSharpMutationsForLoadedSnapshotDrift =
-                context.DeferCSharpMutationsForLoadedSnapshotDrift,
-            TargetRequiresJavaScriptTypeScriptRefresh =
-                context.TargetRequiresJavaScriptTypeScriptRefresh,
-            AllowReuseWithCurrentHotspotFamilyTrust =
-                context.AllowReuseWithCurrentHotspotFamilyTrust,
-            RequireTypeScriptAugmentationRefresh =
-                context.RequireTypeScriptAugmentationRefresh,
-            WriteProjectRootOnce = context.WriteProjectRootOnce,
-            InsertIssuesForIndexedFile =
-                context.InsertIssuesForIndexedFile,
-            CountFreshInsertedRows = context.CountFreshInsertedRows,
-            State = context.ConsumerState,
-        };
 }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ExtractionWorkers.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ExtractionWorkers.cs
index dcb4b521d..a5cf071b8 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ExtractionWorkers.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ExtractionWorkers.cs
@@ -30,7 +30,8 @@ private sealed class FullScanExtractionWorkerContext
     }
 
     private static Task[] StartFullScanExtractionWorkers(
-        FullScanExtractionWorkerContext context)
+        FullScanExtractionWorkerContext context,
+        Action<Task[]> attachWorkers)
     {
         var indexer = context.Indexer;
         var options = context.Options;
@@ -50,8 +51,14 @@ private static Task[] StartFullScanExtractionWorkers(
         var extractionCancellationToken = context.ExtractionCancellationToken;
         var cancellationToken = context.CancellationToken;
         var nextExtractionIndex = -1;
-        var workers = Enumerable.Range(0, extractionWorkerCount)
-            .Select(workerIndex => Task.Factory.StartNew(() =>
+        var workers = new Task[extractionWorkerCount];
+        var startedWorkerCount = 0;
+        try
+        {
+            for (var workerIndex = 0; workerIndex < extractionWorkerCount; workerIndex++)
+            {
+                var capturedWorkerIndex = workerIndex;
+                workers[workerIndex] = Task.Factory.StartNew(() =>
             {
                 using var workerSymbolExtractionWorker = new LazyDisposable<SymbolExtractionWorkerClient>(
                     () => new SymbolExtractionWorkerClient(options.MaxFileSizeBytes));
@@ -75,7 +82,7 @@ private static Task[] StartFullScanExtractionWorkers(
                     var displayRelativePath = target.DisplayRelativePath;
                     try
                     {
-                        Volatile.Write(ref activeExtractionPhases[workerIndex], new(displayRelativePath, "reading"));
+                        Volatile.Write(ref activeExtractionPhases[capturedWorkerIndex], new(displayRelativePath, "reading"));
                         FullScanFileContentLoadForTesting?.Invoke(displayRelativePath);
                         var loaded = indexer.BuildLoadedRecordWithRawBytes(
                             filePath,
@@ -120,13 +127,13 @@ private static Task[] StartFullScanExtractionWorkers(
                             : null;
                         if (parallelizeExtraction)
                         {
-                            Volatile.Write(ref activeExtractionPhases[workerIndex], new(record.Path, "chunking"));
+                            Volatile.Write(ref activeExtractionPhases[capturedWorkerIndex], new(record.Path, "chunking"));
                             chunks = ChunkSplitter.SplitNormalized(0, content, loaded.Facts);
                             if (generatedSuppressionIssue != null)
                             {
                                 symbols = [];
                                 references = [];
-                                Volatile.Write(ref activeExtractionPhases[workerIndex], new(record.Path, "validating"));
+                                Volatile.Write(ref activeExtractionPhases[capturedWorkerIndex], new(record.Path, "validating"));
                                 issues = AppendIssueIfMissing(
                                     FileIndexer.ValidateContent(record.Path, rawBytes, content, record.Lang, loaded.Inspection, loaded.Facts),
                                     generatedSuppressionIssue);
@@ -146,7 +153,7 @@ private static Task[] StartFullScanExtractionWorkers(
                                     extractionCancellationToken);
                                 continue;
                             }
-                            Volatile.Write(ref activeExtractionPhases[workerIndex], new(record.Path, "symbols"));
+                            Volatile.Write(ref activeExtractionPhases[capturedWorkerIndex], new(record.Path, "symbols"));
                             FullScanFilePhaseForTesting?.Invoke(record.Path, "symbols");
                             FileIssue? symbolRegexTimeoutIssue;
                             if (string.Equals(record.Lang, "csharp", StringComparison.Ordinal)
@@ -168,7 +175,7 @@ private static Task[] StartFullScanExtractionWorkers(
                                     filePath,
                                     projectRoot,
                                     record.Path,
-                                    Volatile.Read(ref activeExtractionPhases[workerIndex])!.Format(),
+                                    Volatile.Read(ref activeExtractionPhases[capturedWorkerIndex])!.Format(),
                                     true,
                                     hasOversizeLine,
                                     loaded.ConflictMarkerLine,
@@ -212,7 +219,7 @@ private static Task[] StartFullScanExtractionWorkers(
                             }
                             else
                             {
-                                Volatile.Write(ref activeExtractionPhases[workerIndex], new(record.Path, "references"));
+                                Volatile.Write(ref activeExtractionPhases[capturedWorkerIndex], new(record.Path, "references"));
                                 FullScanFilePhaseForTesting?.Invoke(record.Path, "references");
                                 using var regexTimeouts = BoundedRegex.CaptureTimeouts(record.Lang, "reference_extraction");
                                 referenceExtraction = ReferenceExtractor.ExtractDetailedNormalized(
@@ -232,7 +239,7 @@ private static Task[] StartFullScanExtractionWorkers(
                                 references = referenceExtraction.References;
                                 referenceRegexTimeoutIssue = BuildRegexTimeoutIssue(record.Path, regexTimeouts);
                             }
-                            Volatile.Write(ref activeExtractionPhases[workerIndex], new(record.Path, "validating"));
+                            Volatile.Write(ref activeExtractionPhases[capturedWorkerIndex], new(record.Path, "validating"));
                             issues = FileIndexer.ValidateContent(record.Path, rawBytes, content, record.Lang, loaded.Inspection, loaded.Facts);
                             if (symbolRegexTimeoutIssue != null)
                                 issues = AppendIssue(issues, symbolRegexTimeoutIssue);
@@ -249,7 +256,7 @@ private static Task[] StartFullScanExtractionWorkers(
                         }
                         else
                         {
-                            Volatile.Write(ref activeExtractionPhases[workerIndex], new(record.Path, "validating"));
+                            Volatile.Write(ref activeExtractionPhases[capturedWorkerIndex], new(record.Path, "validating"));
                             issues = FileIndexer.ValidateContent(record.Path, rawBytes, content, record.Lang, loaded.Inspection, loaded.Facts);
                         }
                         extractionResults.Add(
@@ -380,16 +387,24 @@ private static Task[] StartFullScanExtractionWorkers(
                     }
                     catch (Exception ex)
                     {
-                        var failedPhase = Volatile.Read(ref activeExtractionPhases[workerIndex])?.Phase ?? "unknown";
+                        var failedPhase = Volatile.Read(ref activeExtractionPhases[capturedWorkerIndex])?.Phase ?? "unknown";
                         extractionResults.Add(FullScanFileWorkItem.Failure(fileIndex, filePath, displayRelativePath, failedPhase, ex), extractionCancellationToken);
                     }
                     finally
                     {
-                        Volatile.Write(ref activeExtractionPhases[workerIndex], null);
+                        Volatile.Write(ref activeExtractionPhases[capturedWorkerIndex], null);
                     }
                 }
-            }, cancellationToken, TaskCreationOptions.LongRunning, TaskScheduler.Default))
-            .ToArray();
+            }, cancellationToken, TaskCreationOptions.LongRunning, TaskScheduler.Default);
+                startedWorkerCount++;
+            }
+        }
+        catch
+        {
+            attachWorkers(workers[..startedWorkerCount]);
+            throw;
+        }
+        attachWorkers(workers);
         return workers;
     }
 }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.FilePersistence.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.FilePersistence.cs
index 6279bfc38..7f81169e8 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.FilePersistence.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.FilePersistence.cs
@@ -24,7 +24,7 @@ private sealed class FullScanFilePersistenceContext
         internal required PostExtractionHookRunner PostExtractionHooks { get; init; }
         internal required SymbolExtractionWorkerClient SymbolExtractionWorker { get; init; }
         internal required CancellationToken CancellationToken { get; init; }
-        internal required Action<long, IReadOnlyList<FileIssue>> InsertIssuesForIndexedFile { get; init; }
+        internal required FullScanExtractionSession ExtractionSession { get; init; }
         internal required Action WriteProjectRootOnce { get; init; }
         internal required Action<string, string> SetPhase { get; init; }
     }
@@ -95,7 +95,7 @@ private static FullScanFilePersistenceResult PersistFullScanFile(
             var generatedIssues = AppendIssueIfMissing(
                 RequireWorkItemIssues(item),
                 context.GeneratedSuppressionIssue);
-            context.InsertIssuesForIndexedFile(fileId, generatedIssues);
+            context.ExtractionSession.InsertIssuesForIndexedFile(fileId, generatedIssues);
             context.SetPhase(
                 FormatIndexPhasePath(record.Path, "committing"),
                 "committing");
@@ -170,7 +170,7 @@ private static FullScanFilePersistenceResult PersistFullScanFile(
                 : AppendIssue([symbolRegexTimeoutIssue], issue);
             writer.InsertSymbols([], cancellationToken);
             writer.InsertReferencesInAtomicFileScope([], cancellationToken);
-            context.InsertIssuesForIndexedFile(fileId, capIssues);
+            context.ExtractionSession.InsertIssuesForIndexedFile(fileId, capIssues);
             txn.Commit();
             return new FullScanFilePersistenceResult(
                 chunks.Count,
@@ -330,7 +330,7 @@ private static FullScanFilePersistenceResult PersistFullScanFile(
             mutualRecursionRefreshNeeded = true;
         context.SetPhase(FormatIndexPhasePath(record.Path, "validating"), "validating");
         var issues = RequireWorkItemIssues(item);
-        context.InsertIssuesForIndexedFile(fileId, issues);
+        context.ExtractionSession.InsertIssuesForIndexedFile(fileId, issues);
         context.SetPhase(FormatIndexPhasePath(record.Path, "committing"), "committing");
         context.WriteProjectRootOnce();
         txn.Commit();
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.Interruption.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.Interruption.cs
index 791794e81..6c0c3c906 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.Interruption.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.Interruption.cs
@@ -82,7 +82,7 @@ private static void ThrowIfFullScanExtractionStalled(
         long lastProgressTimestamp,
         string? currentFile,
         ActiveExtractionPhase?[] activeExtractionPhases,
-        Action cancelStalledWork)
+        CancellationTokenSource stalledWorkCancellation)
     {
         if (!TryGetFullScanExtractionStallPath(
                 filesProcessed,
@@ -96,7 +96,7 @@ private static void ThrowIfFullScanExtractionStalled(
             return;
         }
 
-        cancelStalledWork();
+        stalledWorkCancellation.Cancel();
         throw new IndexExtractionStalledException(filesProcessed, filesTotal, timeout, activePath);
     }
 
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteSession.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteSession.cs
index 8e923778f..31a7234d3 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteSession.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.PreWriteSession.cs
@@ -114,6 +114,7 @@ private sealed class FullScanPreWriteDiagnosticsState
     {
         internal required List<CliJsonMessage> ErrorList { get; init; }
         internal required List<StatusIndexFileError> FileErrorList { get; init; }
+        internal required List<CliJsonMessage> WarningList { get; init; }
         internal required HashSet<string> ReportedCSharpWorkspaceFailures { get; init; }
         internal int Errors { get; set; }
     }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.Progress.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.Progress.cs
index b5f06fc52..61abaa85b 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.Progress.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.Progress.cs
@@ -9,36 +9,30 @@ private sealed class FullScanProgressSession : IDisposable
         private readonly IndexCommandOptions options;
         private readonly int filesCount;
         private readonly IndexProgressReporter indexProgress;
-        private readonly Func<int> getProcessed;
-        private readonly Func<bool> isProgressVisible;
-        private readonly Func<string?> getCurrentJsonIndexFile;
-        private readonly Func<ActiveExtractionPhase?[]> getActiveExtractionPhases;
+        private readonly FullScanPreWriteSelectionState selection;
         private bool redirectedIndexingMessagePrinted;
         private long lastJsonProgressAt = Stopwatch.GetTimestamp();
         private CancellationTokenSource? jsonHeartbeatCts;
         private Task? jsonHeartbeatTask;
+        internal bool IndexProgressVisible { get; set; }
+        internal string? CurrentJsonIndexFile { get; set; }
+        internal ActiveExtractionPhase?[] ActiveExtractionPhases { get; set; } = [];
 
         internal FullScanProgressSession(
             IndexCommandOptions options,
             int filesCount,
             IndexProgressReporter indexProgress,
-            Func<int> getProcessed,
-            Func<bool> isProgressVisible,
-            Func<string?> getCurrentJsonIndexFile,
-            Func<ActiveExtractionPhase?[]> getActiveExtractionPhases)
+            FullScanPreWriteSelectionState selection)
         {
             this.options = options;
             this.filesCount = filesCount;
             this.indexProgress = indexProgress;
-            this.getProcessed = getProcessed;
-            this.isProgressVisible = isProgressVisible;
-            this.getCurrentJsonIndexFile = getCurrentJsonIndexFile;
-            this.getActiveExtractionPhases = getActiveExtractionPhases;
+            this.selection = selection;
         }
 
         internal void EnsureIndexingActivityVisible()
         {
-            if (options.Json || options.Quiet || isProgressVisible())
+            if (options.Json || options.Quiet || IndexProgressVisible)
                 return;
 
             if (indexProgress.Interactive)
@@ -59,7 +53,7 @@ internal void ReportJsonIndexProgressIfNeeded()
             if (!options.Json || options.Quiet || filesCount == 0)
                 return;
 
-            var processed = getProcessed();
+            var processed = selection.Processed;
             var now = Stopwatch.GetTimestamp();
             if (processed == 0
                 || processed == filesCount
@@ -104,14 +98,14 @@ await Task.Delay(TimeSpan.FromSeconds(5), token)
                             break;
 
                         var file = GetJsonIndexHeartbeatPath(
-                            getCurrentJsonIndexFile(),
+                            CurrentJsonIndexFile,
                             FormatActiveExtractionPhases(
-                                getActiveExtractionPhases()));
+                                ActiveExtractionPhases));
                         var fileSuffix = string.IsNullOrEmpty(file)
                             ? string.Empty
                             : $": {file}";
                         ConsoleUi.TryWriteErrorLine(
-                            $"cdidx: still indexing {getProcessed():N0}/{filesCount:N0} file(s){fileSuffix}...");
+                            $"cdidx: still indexing {selection.Processed:N0}/{filesCount:N0} file(s){fileSuffix}...");
                     }
                 },
                 token);
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ResultConsumer.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ResultConsumer.cs
index 373bbc458..16d2c8337 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ResultConsumer.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.ResultConsumer.cs
@@ -10,414 +10,346 @@ namespace CodeIndex.Cli;
 
 public static partial class IndexCommandRunner
 {
-    private sealed class FullScanExtractionConsumerContext
-    {
-        internal required DbWriter Writer { get; init; }
-        internal required FileIndexer Indexer { get; init; }
-        internal required IndexCommandOptions Options { get; init; }
-        internal required string ProjectRoot { get; init; }
-        internal required FullScanFileTarget[] FileTargets { get; init; }
-        internal required int FilesCount { get; init; }
-        internal required int ProcessedBeforeExtraction { get; init; }
-        internal required bool ForceExtractorRefresh { get; init; }
-        internal required bool StartedWithNoIndexedFiles { get; init; }
-        internal required bool PriorSymbolsOnlyGraphOmitted { get; init; }
-        internal required bool SymbolKindFilterMatchesPrior { get; init; }
-        internal required bool CSharpIndexedProjectRootCompatible { get; init; }
-        internal required bool CSharpSymbolNameContractMatchesCurrent { get; init; }
-        internal required bool SqlGraphContractMatchesCurrent { get; init; }
-        internal required bool HdlGraphContractMatchesCurrent { get; init; }
-        internal required ReadableFileByteTracker ReadableFileBytes { get; init; }
-        internal required PostExtractionHookRunner PostExtractionHooks { get; init; }
-        internal required SymbolExtractionWorkerClient SymbolExtractionWorker { get; init; }
-        internal required IndexProgressReporter IndexProgress { get; init; }
-        internal required BlockingCollection<FullScanFileWorkItem> ExtractionResults { get; init; }
-        internal required Task[] Workers { get; init; }
-        internal required TimeSpan ExtractionStallTimeout { get; init; }
-        internal required ActiveExtractionPhase?[] ActiveExtractionPhases { get; init; }
-        internal required CancellationToken CancellationToken { get; init; }
-        internal required Action CancelExtraction { get; init; }
-        internal required Action EnsureIndexingActivityVisible { get; init; }
-        internal required Action ReportJsonIndexProgressIfNeeded { get; init; }
-        internal required Action<int, int?> ThrowIfFullScanCancelled { get; init; }
-        internal required Action<int> PublishProcessedCount { get; init; }
-        internal required Action<string?> SetCurrentJsonIndexFile { get; init; }
-        internal required Func<string?> GetCurrentJsonIndexFile { get; init; }
-        internal required Func<bool> GetDeferCSharpMutationsForIncompleteScan { get; init; }
-        internal required Func<bool> GetFtsMutated { get; init; }
-        internal required Func<CSharpStaticInterfaceWorkspaceSymbols> GetCSharpWorkspace { get; init; }
-        internal required Func<CSharpPrepassSymbolArtifactCache?> GetCSharpPrepassSymbolArtifacts { get; init; }
-        internal required Func<Dictionary<string, CSharpStaticInterfacePrepass.FileStatSnapshot>?> GetCSharpWorkspaceFileSnapshots { get; init; }
-        internal required Action<string> DeferCSharpMutationsForLoadedSnapshotDrift { get; init; }
-        internal required Func<string?, string, bool> TargetRequiresJavaScriptTypeScriptRefresh { get; init; }
-        internal required Func<string?, bool> AllowReuseWithCurrentHotspotFamilyTrust { get; init; }
-        internal required Action RequireTypeScriptAugmentationRefresh { get; init; }
-        internal required Action WriteProjectRootOnce { get; init; }
-        internal required Action<long, IReadOnlyList<FileIssue>> InsertIssuesForIndexedFile { get; init; }
-        internal required Action<int, int, int> CountFreshInsertedRows { get; init; }
-        internal required FullScanExtractionConsumerState State { get; init; }
-    }
-
-    private sealed class FullScanExtractionConsumerState
-    {
-        internal int Processed { get; set; }
-        internal int Skipped { get; set; }
-        internal int Warnings { get; set; }
-        internal int ErrorsAdded { get; set; }
-        internal bool FtsMutated { get; set; }
-        internal bool MutualRecursionRefreshNeeded { get; set; }
-        internal bool CSharpMetadataTargetsNeedRefresh { get; set; }
-        internal int SymbolsDroppedByKindFilter { get; set; }
-        internal long ExtractedFiles { get; set; }
-        internal long ExtractedChunks { get; set; }
-        internal long ExtractedSymbols { get; set; }
-        internal long ExtractedReferences { get; set; }
-        internal HashSet<string>? ReusedHotspotFamilyLanguages { get; set; }
-        internal HashSet<string>? SkippedSymbolExtractorLanguages { get; set; }
-        internal required HashSet<string> IndexedSymbolExtractorLanguages { get; init; }
-        internal required List<CliJsonMessage> ErrorList { get; init; }
-        internal required List<StatusIndexFileError> FileErrorList { get; init; }
-        internal required List<CliJsonMessage> WarningList { get; init; }
-    }
+    private readonly record struct FullScanExtractionConsumerResources(
+        PostExtractionHookRunner PostExtractionHooks,
+        SymbolExtractionWorkerClient SymbolExtractionWorker,
+        BlockingCollection<FullScanFileWorkItem> ExtractionResults,
+        Task[] Workers,
+        TimeSpan ExtractionStallTimeout,
+        ActiveExtractionPhase?[] ActiveExtractionPhases,
+        CancellationTokenSource ExtractionCancellation,
+        int ProcessedBeforeExtraction);
 
-    private static FullScanExtractionConsumerState ConsumeFullScanExtractionResults(
-        FullScanExtractionConsumerContext context)
+    private sealed partial class FullScanExtractionSession
     {
-        var lastExtractionProgressAt = Stopwatch.GetTimestamp();
-        while (!context.ExtractionResults.IsCompleted)
+        internal void ConsumeFullScanExtractionResults(
+            in FullScanExtractionConsumerResources resources)
         {
-            var processed = context.ProcessedBeforeExtraction + context.State.Processed;
-            context.ThrowIfFullScanCancelled(processed, context.FilesCount);
-            if (!context.ExtractionResults.TryTake(out var item, millisecondsTimeout: 100))
+            var lastExtractionProgressAt = Stopwatch.GetTimestamp();
+            while (!resources.ExtractionResults.IsCompleted)
             {
-                ThrowIfFullScanExtractionStalled(
-                    processed,
-                    context.FilesCount,
-                    context.ExtractionStallTimeout,
-                    lastExtractionProgressAt,
-                    context.GetCurrentJsonIndexFile(),
-                    context.ActiveExtractionPhases,
-                    context.CancelExtraction);
-                continue;
+                var processed = resources.ProcessedBeforeExtraction + Processed;
+                ThrowIfFullScanCancelled(processed, FilesCount);
+                if (!resources.ExtractionResults.TryTake(out var item, millisecondsTimeout: 100))
+                {
+                    ThrowIfFullScanExtractionStalled(
+                        processed,
+                        FilesCount,
+                        resources.ExtractionStallTimeout,
+                        lastExtractionProgressAt,
+                        CurrentJsonIndexFile,
+                        resources.ActiveExtractionPhases,
+                        resources.ExtractionCancellation);
+                    continue;
+                }
+
+                lastExtractionProgressAt = Stopwatch.GetTimestamp();
+                CurrentJsonIndexFile = item.RelativePath;
+                ProcessFullScanExtractionItem(in resources, item);
+                CompleteFullScanExtractionItem(resources.ProcessedBeforeExtraction);
             }
 
-            lastExtractionProgressAt = Stopwatch.GetTimestamp();
-            context.SetCurrentJsonIndexFile(item.RelativePath);
-            ProcessFullScanExtractionItem(context, item);
-            CompleteFullScanExtractionItem(context);
+            Task.WaitAll(resources.Workers, CancellationToken);
         }
 
-        Task.WaitAll(context.Workers, context.CancellationToken);
-        return context.State;
-    }
-
-    private static void ProcessFullScanExtractionItem(
-        FullScanExtractionConsumerContext context,
-        FullScanFileWorkItem item)
-    {
-        var state = context.State;
-        var options = context.Options;
-        var writer = context.Writer;
-        var indexFilePhase = item.FailurePhase ?? "preparing";
-        var itemFileExtracted = item.Record == null ? 0L : 1L;
-        var itemChunksExtracted = item.Chunks?.Count ?? 0L;
-        var itemSymbolsExtracted = item.Symbols?.Count ?? 0L;
-        var itemReferencesExtracted = item.References?.Count ?? 0L;
-        context.EnsureIndexingActivityVisible();
-        if (item.Exception is IndexExtractionStalledException stalledException)
-            RethrowPreservingStackTrace(stalledException);
-
-        try
+        private void ProcessFullScanExtractionItem(
+            in FullScanExtractionConsumerResources resources,
+            FullScanFileWorkItem item)
         {
-            if (ShouldDeferFullScanCSharpItem(context, item))
+            var options = Options;
+            var writer = Writer;
+            var indexFilePhase = item.FailurePhase ?? "preparing";
+            var itemFileExtracted = item.Record == null ? 0L : 1L;
+            var itemChunksExtracted = item.Chunks?.Count ?? 0L;
+            var itemSymbolsExtracted = item.Symbols?.Count ?? 0L;
+            var itemReferencesExtracted = item.References?.Count ?? 0L;
+            FullScanProgress.EnsureIndexingActivityVisible();
+            if (item.Exception is IndexExtractionStalledException stalledException)
+                RethrowPreservingStackTrace(stalledException);
+
+            try
             {
-                state.Skipped++;
-                return;
-            }
+                if (ShouldDeferFullScanCSharpItem(item))
+                {
+                    Skipped++;
+                    return;
+                }
 
-            if (item.Exception != null)
-                RethrowPreservingStackTrace(item.Exception);
+                if (item.Exception != null)
+                    RethrowPreservingStackTrace(item.Exception);
 
-            if (item.Record == null)
-            {
-                RecordSkippedFullScanExtractionItem(context, item);
-                return;
-            }
+                if (item.Record == null)
+                {
+                    RecordSkippedFullScanExtractionItem(item);
+                    return;
+                }
 
-            var record = item.Record;
-            context.ReadableFileBytes.Remember(item.FileIndex, record.Size);
-            if (item.Warning != null && !options.Json && !options.Quiet)
-            {
-                context.IndexProgress.Pause();
-                ConsoleUi.PrintWarning(item.Warning);
-                context.IndexProgress.Resume();
-            }
+                var record = item.Record;
+                ReadableFileBytes.Remember(item.FileIndex, record.Size);
+                if (item.Warning != null && !options.Json && !options.Quiet)
+                {
+                    IndexProgress.Pause();
+                    ConsoleUi.PrintWarning(item.Warning);
+                    IndexProgress.Resume();
+                }
 
-            var generatedSuppressionIssue = item.GeneratedSuppressionChecked
-                ? item.GeneratedSuppressionIssue
-                : context.Indexer.BuildGeneratedCodeExtractionSkippedIssue(record.Path);
-            var existingId = GetReusableFullScanFileId(context, record, generatedSuppressionIssue);
-            if (existingId != null)
-            {
-                RecordReusedFullScanExtractionItem(context, record);
-                return;
-            }
+                var generatedSuppressionIssue = item.GeneratedSuppressionChecked
+                    ? item.GeneratedSuppressionIssue
+                    : Indexer.BuildGeneratedCodeExtractionSkippedIssue(record.Path);
+                var existingId = GetReusableFullScanFileId(record, generatedSuppressionIssue);
+                if (existingId != null)
+                {
+                    RecordReusedFullScanExtractionItem(record);
+                    return;
+                }
 
-            if (record.Lang == "csharp")
-                state.CSharpMetadataTargetsNeedRefresh = true;
-            if (record.Lang == "typescript")
-                context.RequireTypeScriptAugmentationRefresh();
+                if (record.Lang == "csharp")
+                    CSharpMetadataTargetsNeedRefresh = true;
+                if (record.Lang == "typescript")
+                    RequireTypeScriptAugmentationRefresh();
 
-            var persistence = PersistFullScanFile(new FullScanFilePersistenceContext
-            {
-                Writer = writer,
-                Indexer = context.Indexer,
-                Options = options,
-                ProjectRoot = context.ProjectRoot,
-                Item = item,
-                Record = record,
-                GeneratedSuppressionIssue = generatedSuppressionIssue,
-                StartedWithNoIndexedFiles = context.StartedWithNoIndexedFiles,
-                DeferCSharpMutationsForIncompleteScan =
-                    context.GetDeferCSharpMutationsForIncompleteScan(),
-                CSharpWorkspace = context.GetCSharpWorkspace(),
-                CSharpPrepassSymbolArtifacts =
-                    context.GetCSharpPrepassSymbolArtifacts(),
-                PostExtractionHooks = context.PostExtractionHooks,
-                SymbolExtractionWorker = context.SymbolExtractionWorker,
-                CancellationToken = context.CancellationToken,
-                InsertIssuesForIndexedFile = context.InsertIssuesForIndexedFile,
-                WriteProjectRootOnce = context.WriteProjectRootOnce,
-                SetPhase = (path, phase) =>
+                var persistence = PersistFullScanFile(new FullScanFilePersistenceContext
+                {
+                    Writer = writer,
+                    Indexer = Indexer,
+                    Options = options,
+                    ProjectRoot = ProjectRoot,
+                    Item = item,
+                    Record = record,
+                    GeneratedSuppressionIssue = generatedSuppressionIssue,
+                    StartedWithNoIndexedFiles = StartedWithNoIndexedFiles,
+                    DeferCSharpMutationsForIncompleteScan =
+                        DeferCSharpMutationsForIncompleteScan,
+                    CSharpWorkspace = CSharpWorkspace,
+                    CSharpPrepassSymbolArtifacts =
+                        CSharpPrepassSymbolArtifacts,
+                    PostExtractionHooks = resources.PostExtractionHooks,
+                    SymbolExtractionWorker = resources.SymbolExtractionWorker,
+                    CancellationToken = CancellationToken,
+                    ExtractionSession = this,
+                    WriteProjectRootOnce = WriteProjectRootOnce,
+                    SetPhase = (path, phase) =>
+                    {
+                        CurrentJsonIndexFile = path;
+                        indexFilePhase = phase;
+                    },
+                });
+                itemChunksExtracted = persistence.ExtractedChunks;
+                itemSymbolsExtracted = persistence.ExtractedSymbols;
+                itemReferencesExtracted = persistence.ExtractedReferences;
+                SymbolsDroppedByKindFilter += persistence.SymbolsDroppedByKindFilter;
+                MutualRecursionRefreshNeeded |= persistence.MutualRecursionRefreshNeeded;
+                CSharpMetadataTargetsNeedRefresh |= persistence.CSharpMetadataTargetsNeedRefresh;
+                FtsMutated = true;
+                if (persistence.StampSymbolExtractorLanguage
+                    && !string.IsNullOrWhiteSpace(record.Lang))
                 {
-                    context.SetCurrentJsonIndexFile(path);
-                    indexFilePhase = phase;
-                },
-            });
-            itemChunksExtracted = persistence.ExtractedChunks;
-            itemSymbolsExtracted = persistence.ExtractedSymbols;
-            itemReferencesExtracted = persistence.ExtractedReferences;
-            state.SymbolsDroppedByKindFilter += persistence.SymbolsDroppedByKindFilter;
-            state.MutualRecursionRefreshNeeded |= persistence.MutualRecursionRefreshNeeded;
-            state.CSharpMetadataTargetsNeedRefresh |= persistence.CSharpMetadataTargetsNeedRefresh;
-            state.FtsMutated = true;
-            if (persistence.StampSymbolExtractorLanguage
-                && !string.IsNullOrWhiteSpace(record.Lang))
+                    IndexedSymbolExtractorLanguages.Add(record.Lang);
+                }
+                CountFreshInsertedRows(
+                    persistence.PersistedChunks,
+                    persistence.PersistedSymbols,
+                    persistence.PersistedReferences);
+                IndexProgress.WriteVerbose(persistence.VerboseMessage);
+            }
+            catch (IndexExtractionStalledException)
             {
-                state.IndexedSymbolExtractorLanguages.Add(record.Lang);
+                throw;
             }
-            context.CountFreshInsertedRows(
-                persistence.PersistedChunks,
-                persistence.PersistedSymbols,
-                persistence.PersistedReferences);
-            context.IndexProgress.WriteVerbose(persistence.VerboseMessage);
-        }
-        catch (IndexExtractionStalledException)
-        {
-            throw;
-        }
-        catch (Exception ex)
-        {
-            LogIndexFileFailure("index_file_failed", item.FilePath, indexFilePhase, ex);
-            state.ErrorsAdded++;
-            var errorMessage = FormatIndexFileException(ex);
-            state.ErrorList.Add(new CliJsonMessage(item.FilePath, errorMessage));
-            if (state.FileErrorList.Count < PartialIndexFileErrorLimit)
-                state.FileErrorList.Add(BuildIndexFileError(item.RelativePath, indexFilePhase, ex));
-            if (!options.Json)
+            catch (Exception ex)
             {
-                context.IndexProgress.Pause();
-                ConsoleUi.ClearProgressLine();
-                ConsoleUi.TryWriteErrorLine(
-                    FormatPerFileErrorLine("ERR ", item.FilePath, ex, errorMessage));
-                context.IndexProgress.Resume();
+                LogIndexFileFailure("index_file_failed", item.FilePath, indexFilePhase, ex);
+                ErrorsAdded++;
+                var errorMessage = FormatIndexFileException(ex);
+                ErrorList.Add(new CliJsonMessage(item.FilePath, errorMessage));
+                if (FileErrorList.Count < PartialIndexFileErrorLimit)
+                    FileErrorList.Add(BuildIndexFileError(item.RelativePath, indexFilePhase, ex));
+                if (!options.Json)
+                {
+                    IndexProgress.Pause();
+                    ConsoleUi.ClearProgressLine();
+                    ConsoleUi.TryWriteErrorLine(
+                        FormatPerFileErrorLine("ERR ", item.FilePath, ex, errorMessage));
+                    IndexProgress.Resume();
+                }
+            }
+            finally
+            {
+                ExtractedFiles += itemFileExtracted;
+                ExtractedChunks += itemChunksExtracted;
+                ExtractedSymbols += itemSymbolsExtracted;
+                ExtractedReferences += itemReferencesExtracted;
             }
-        }
-        finally
-        {
-            state.ExtractedFiles += itemFileExtracted;
-            state.ExtractedChunks += itemChunksExtracted;
-            state.ExtractedSymbols += itemSymbolsExtracted;
-            state.ExtractedReferences += itemReferencesExtracted;
-        }
-    }
-
-    private static bool ShouldDeferFullScanCSharpItem(
-        FullScanExtractionConsumerContext context,
-        FullScanFileWorkItem item)
-    {
-        if (item.FileIndex < 0
-            || context.FileTargets[item.FileIndex].Language != "csharp")
-        {
-            return false;
         }
 
-        var deferCurrentItem = context.GetDeferCSharpMutationsForIncompleteScan();
-        if (!deferCurrentItem
-            && item.Exception is CSharpWorkspaceSnapshotDriftException driftException)
+        private bool ShouldDeferFullScanCSharpItem(
+            FullScanFileWorkItem item)
         {
-            context.DeferCSharpMutationsForLoadedSnapshotDrift(driftException.Path);
-            context.State.FtsMutated = context.GetFtsMutated();
-            return true;
-        }
+            if (item.FileIndex < 0
+                || FileTargets[item.FileIndex].Language != "csharp")
+            {
+                return false;
+            }
 
-        var workspaceFileSnapshots = context.GetCSharpWorkspaceFileSnapshots();
-        if (!deferCurrentItem
-            && item.Record != null
-            && workspaceFileSnapshots != null
-            && !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
-                item.FilePath,
-                context.FileTargets[item.FileIndex].IndexPath,
-                context.FileTargets[item.FileIndex].DisplayRelativePath,
-                item.Record.Size,
-                item.Record.Modified,
-                workspaceFileSnapshots,
-                out var changedPath,
-                context.CancellationToken))
-        {
-            context.DeferCSharpMutationsForLoadedSnapshotDrift(
-                changedPath ?? context.FileTargets[item.FileIndex].DisplayRelativePath);
-            context.State.FtsMutated = context.GetFtsMutated();
-            return true;
-        }
+            var deferCurrentItem = DeferCSharpMutationsForIncompleteScan;
+            if (!deferCurrentItem
+                && item.Exception is CSharpWorkspaceSnapshotDriftException driftException)
+            {
+                DeferCSharpMutationsForLoadedSnapshotDrift(driftException.Path);
+                return true;
+            }
 
-        return deferCurrentItem;
-    }
+            var workspaceFileSnapshots = CSharpWorkspaceFileSnapshots;
+            if (!deferCurrentItem
+                && item.Record != null
+                && workspaceFileSnapshots != null
+                && !CSharpStaticInterfacePrepass.TryValidateLoadedFileStatSnapshot(
+                    item.FilePath,
+                    FileTargets[item.FileIndex].IndexPath,
+                    FileTargets[item.FileIndex].DisplayRelativePath,
+                    item.Record.Size,
+                    item.Record.Modified,
+                    workspaceFileSnapshots,
+                    out var changedPath,
+                    CancellationToken))
+            {
+                DeferCSharpMutationsForLoadedSnapshotDrift(
+                    changedPath ?? FileTargets[item.FileIndex].DisplayRelativePath);
+                return true;
+            }
 
-    private static void RecordSkippedFullScanExtractionItem(
-        FullScanExtractionConsumerContext context,
-        FullScanFileWorkItem item)
-    {
-        var state = context.State;
-        var path = item.RelativePath;
-        state.Warnings++;
-        state.WarningList.Add(new CliJsonMessage(path, item.Warning ?? "File skipped"));
-        if (!context.Options.Json
-            && !context.Options.Quiet
-            && item.Warning != null)
-        {
-            context.IndexProgress.Pause();
-            ConsoleUi.PrintWarning(item.Warning);
-            context.IndexProgress.Resume();
+            return deferCurrentItem;
         }
 
-        if (!context.Writer.HasFileAtPath(path))
+        private void RecordSkippedFullScanExtractionItem(
+            FullScanFileWorkItem item)
         {
-            state.Skipped++;
-            return;
-        }
+            var path = item.RelativePath;
+            Warnings++;
+            WarningList.Add(new CliJsonMessage(path, item.Warning ?? "File skipped"));
+            if (!Options.Json
+                && !Options.Quiet
+                && item.Warning != null)
+            {
+                IndexProgress.Pause();
+                ConsoleUi.PrintWarning(item.Warning);
+                IndexProgress.Resume();
+            }
 
-        using var deleteTxn = context.Writer.BeginTransaction(
-            context.CancellationToken,
-            "full scan delete skipped file");
-        if (!context.Writer.DeleteFileByPath(path))
-            return;
+            if (!Writer.HasFileAtPath(path))
+            {
+                Skipped++;
+                return;
+            }
 
-        state.CSharpMetadataTargetsNeedRefresh = true;
-        context.RequireTypeScriptAugmentationRefresh();
-        context.WriteProjectRootOnce();
-        deleteTxn.Commit();
-        state.FtsMutated = true;
-    }
+            using var deleteTxn = Writer.BeginTransaction(
+                CancellationToken,
+                "full scan delete skipped file");
+            if (!Writer.DeleteFileByPath(path))
+                return;
 
-    private static long? GetReusableFullScanFileId(
-        FullScanExtractionConsumerContext context,
-        FileRecord record,
-        FileIssue? generatedSuppressionIssue)
-    {
-        var options = context.Options;
-        if (context.ForceExtractorRefresh
-            || options.Rebuild
-            || context.StartedWithNoIndexedFiles
-            || options.SymbolsOnly)
-        {
-            return null;
+            CSharpMetadataTargetsNeedRefresh = true;
+            RequireTypeScriptAugmentationRefresh();
+            WriteProjectRootOnce();
+            deleteTxn.Commit();
+            FtsMutated = true;
         }
 
-        var targetRequiresRefresh =
-            context.TargetRequiresJavaScriptTypeScriptRefresh(record.Lang, record.Path);
-        return context.Writer.GetReusableUnchangedFileId(
-            record.Path,
-            record.Modified,
-            record.Checksum,
-            size: record.Size,
-            lines: record.Lines,
-            language: record.Lang,
-            generated: record.Generated,
-            maxSymbolsPerFile: options.MaxSymbolsPerFile,
-            maxReferencesPerFile: options.MaxReferencesPerFile,
-            generatedExtractionSuppressed: generatedSuppressionIssue != null,
-            allowReuse: context.SymbolKindFilterMatchesPrior
-                && !targetRequiresRefresh
-                && !context.PriorSymbolsOnlyGraphOmitted
-                && (record.Lang != "csharp" || context.CSharpIndexedProjectRootCompatible)
-                && (record.Lang != "csharp" || context.CSharpSymbolNameContractMatchesCurrent)
-                && (record.Lang != "csharp" || !context.GetCSharpWorkspace().HasStaticInterfaceContracts)
-                && (record.Lang != "sql" || context.SqlGraphContractMatchesCurrent)
-                && (record.Lang is not ("verilog" or "systemverilog" or "vhdl")
-                    || context.HdlGraphContractMatchesCurrent)
-                && context.AllowReuseWithCurrentHotspotFamilyTrust(record.Lang));
-    }
+        private long? GetReusableFullScanFileId(
+            FileRecord record,
+            FileIssue? generatedSuppressionIssue)
+        {
+            var options = Options;
+            if (ForceExtractorRefresh
+                || options.Rebuild
+                || StartedWithNoIndexedFiles
+                || options.SymbolsOnly)
+            {
+                return null;
+            }
 
-    private static void RecordReusedFullScanExtractionItem(
-        FullScanExtractionConsumerContext context,
-        FileRecord record)
-    {
-        var state = context.State;
-        var stalePurged = context.GetDeferCSharpMutationsForIncompleteScan()
-            ? 0
-            : context.Writer.PurgeStaleFilesSharingChecksum(
-                context.ProjectRoot,
+            var targetRequiresRefresh =
+                TargetRequiresJavaScriptTypeScriptRefresh(record.Lang, record.Path);
+            return Writer.GetReusableUnchangedFileId(
                 record.Path,
-                record.Checksum);
-        if (stalePurged > 0)
-        {
-            state.FtsMutated = true;
-            state.CSharpMetadataTargetsNeedRefresh = true;
-            context.RequireTypeScriptAugmentationRefresh();
-            if (!context.Options.SymbolsOnly)
-                state.MutualRecursionRefreshNeeded = true;
+                record.Modified,
+                record.Checksum,
+                size: record.Size,
+                lines: record.Lines,
+                language: record.Lang,
+                generated: record.Generated,
+                maxSymbolsPerFile: options.MaxSymbolsPerFile,
+                maxReferencesPerFile: options.MaxReferencesPerFile,
+                generatedExtractionSuppressed: generatedSuppressionIssue != null,
+                allowReuse: SymbolKindFilterMatchesPrior
+                    && !targetRequiresRefresh
+                    && !PriorSymbolsOnlyGraphOmitted
+                    && (record.Lang != "csharp" || CSharpIndexedProjectRootCompatible)
+                    && (record.Lang != "csharp" || CSharpSymbolNameContractMatchesCurrent)
+                    && (record.Lang != "csharp" || !CSharpWorkspace.HasStaticInterfaceContracts)
+                    && (record.Lang != "sql" || SqlGraphContractMatchesCurrent)
+                    && (record.Lang is not ("verilog" or "systemverilog" or "vhdl")
+                        || HdlGraphContractMatchesCurrent)
+                    && AllowReuseWithCurrentHotspotFamilyTrust(record.Lang));
         }
 
-        state.Skipped++;
-        if (!string.IsNullOrWhiteSpace(record.Lang))
-        {
-            state.SkippedSymbolExtractorLanguages ??=
-                new HashSet<string>(StringComparer.Ordinal);
-            state.SkippedSymbolExtractorLanguages.Add(record.Lang);
-        }
-        if (FileIndexer.SupportsHotspotFamilyMarkerLanguage(record.Lang)
-            && record.Lang != null)
+        private void RecordReusedFullScanExtractionItem(
+            FileRecord record)
         {
-            state.ReusedHotspotFamilyLanguages ??=
-                new HashSet<string>(StringComparer.Ordinal);
-            state.ReusedHotspotFamilyLanguages.Add(record.Lang);
-        }
-        if (context.Options.Verbose
-            && !context.Options.Json
-            && !context.Options.Quiet)
-        {
-            context.IndexProgress.Pause();
-            ConsoleUi.ClearProgressLine();
-            CommandOutputWriter.WriteLine($"  [SKIP] {record.Path}");
-            context.IndexProgress.Resume();
+            var stalePurged = DeferCSharpMutationsForIncompleteScan
+                ? 0
+                : Writer.PurgeStaleFilesSharingChecksum(
+                    ProjectRoot,
+                    record.Path,
+                    record.Checksum);
+            if (stalePurged > 0)
+            {
+                FtsMutated = true;
+                CSharpMetadataTargetsNeedRefresh = true;
+                RequireTypeScriptAugmentationRefresh();
+                if (!Options.SymbolsOnly)
+                    MutualRecursionRefreshNeeded = true;
+            }
+
+            Skipped++;
+            if (!string.IsNullOrWhiteSpace(record.Lang))
+            {
+                SkippedSymbolExtractorLanguages ??=
+                    new HashSet<string>(StringComparer.Ordinal);
+                SkippedSymbolExtractorLanguages.Add(record.Lang);
+            }
+            if (FileIndexer.SupportsHotspotFamilyMarkerLanguage(record.Lang)
+                && record.Lang != null)
+            {
+                ReusedHotspotFamilyLanguages ??=
+                    new HashSet<string>(StringComparer.Ordinal);
+                ReusedHotspotFamilyLanguages.Add(record.Lang);
+            }
+            if (Options.Verbose
+                && !Options.Json
+                && !Options.Quiet)
+            {
+                IndexProgress.Pause();
+                ConsoleUi.ClearProgressLine();
+                CommandOutputWriter.WriteLine($"  [SKIP] {record.Path}");
+                IndexProgress.Resume();
+            }
         }
-    }
 
-    private static void CompleteFullScanExtractionItem(
-        FullScanExtractionConsumerContext context)
-    {
-        context.State.Processed++;
-        var processed = context.ProcessedBeforeExtraction + context.State.Processed;
-        context.PublishProcessedCount(processed);
-        context.SetCurrentJsonIndexFile(null);
-        context.ThrowIfFullScanCancelled(processed, context.FilesCount);
-        context.ReportJsonIndexProgressIfNeeded();
-        if (context.Options.Json || context.Options.Quiet)
-            return;
+        private void CompleteFullScanExtractionItem(int processedBeforeExtraction)
+        {
+            Processed++;
+            var processed = processedBeforeExtraction + Processed;
+            ProcessedCount = processed;
+            CurrentJsonIndexFile = null;
+            ThrowIfFullScanCancelled(processed, FilesCount);
+            FullScanProgress.ReportJsonIndexProgressIfNeeded();
+            if (Options.Json || Options.Quiet)
+                return;
 
-        context.IndexProgress.Pause();
-        ConsoleUi.PrintProgress(processed, context.FilesCount);
-        context.IndexProgress.Resume();
+            IndexProgress.Pause();
+            ConsoleUi.PrintProgress(processed, FilesCount);
+            IndexProgress.Resume();
+        }
     }
 }
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs
index 4c5c00c28..bdbd63840 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs
@@ -255,25 +255,21 @@ void ThrowIfFullScanCancelled(int filesProcessed, int? filesTotal)
         var mutualRecursionRefreshNeeded = !options.SymbolsOnly
             && (!writer.ReferenceIdentityContractMatchesCurrent() || purged > 0);
 
-        var indexProgressVisible = false;
+        FullScanProgressSession? fullScanProgressForResume = null;
         var indexProgress = new IndexProgressReporter(
             options,
             "Indexing...",
             spinnerFrames,
             ConsoleUi.TryWriteErrorLine,
-            canResume: () => preWriteSelection.Processed < files.Count && !indexProgressVisible,
+            canResume: () => preWriteSelection.Processed < files.Count
+                && !fullScanProgressForResume!.IndexProgressVisible,
             clearProgressLineBeforeWrite: true);
         var indexedSymbolExtractorLanguages = new HashSet<string>(languageCounts.Count, StringComparer.Ordinal);
-        string? currentJsonIndexFile = null;
-        ActiveExtractionPhase?[] activeExtractionPhases = [];
-        using var fullScanProgress = new FullScanProgressSession(
+        using var fullScanProgress = fullScanProgressForResume = new FullScanProgressSession(
             options,
             files.Count,
             indexProgress,
-            () => preWriteSelection.Processed,
-            () => indexProgressVisible,
-            () => currentJsonIndexFile,
-            () => activeExtractionPhases);
+            preWriteSelection);
         var extractionParallelism = Math.Max(1, options.Parallelism);
         var typeScriptAugmentationNeedsRefresh = !options.SymbolsOnly
             && (options.Rebuild
@@ -351,21 +347,6 @@ bool FullScanJavaScriptTypeScriptConfigChanged()
             return false;
         }
 
-        bool TargetRequiresJavaScriptTypeScriptRefresh(
-            string? language,
-            string indexPath)
-            => javaScriptTypeScriptRefreshRequired
-               && (IsJavaScriptTypeScriptLanguage(language)
-                   || IsJavaScriptTypeScriptConfigPath(indexPath));
-
-        void InsertIssuesForIndexedFile(long fileId, IReadOnlyList<FileIssue> issues)
-        {
-            if (startedWithNoIndexedFiles)
-                writer.InsertIssuesForNewFile(fileId, issues);
-            else
-                writer.InsertIssues(fileId, issues);
-        }
-
         var preWriteState = new FullScanPreWriteState
         {
             Scan = new FullScanPreWriteMutableScanState
@@ -384,6 +365,7 @@ void InsertIssuesForIndexedFile(long fileId, IReadOnlyList<FileIssue> issues)
             {
                 ErrorList = errorList,
                 FileErrorList = fileErrorList,
+                WarningList = warningList,
                 ReportedCSharpWorkspaceFailures =
                     reportedCSharpWorkspaceFailures,
                 Errors = errors,
@@ -453,24 +435,6 @@ void InsertIssuesForIndexedFile(long fileId, IReadOnlyList<FileIssue> issues)
         var persistedChunks = 0L;
         var persistedSymbols = 0L;
         var persistedReferences = 0L;
-        void CountFreshInsertedRows(
-            int chunkCount = 0,
-            int symbolCount = 0,
-            int referenceCount = 0)
-        {
-            persistedFiles++;
-            persistedChunks += chunkCount;
-            persistedSymbols += symbolCount;
-            persistedReferences += referenceCount;
-            if (!startedWithNoIndexedFiles)
-                return;
-
-            freshCountFiles++;
-            freshCountChunks += chunkCount;
-            freshCountSymbols += symbolCount;
-            freshCountReferences += referenceCount;
-        }
-
         var inputValidation = preWriteSession.PrepareWriteBoundary(
             discovery.InputSnapshot);
         if (!inputValidation.IsValid)
@@ -517,8 +481,6 @@ void CountFreshInsertedRows(
         var csharpWorkspace = csharpPreflight.Workspace;
         var csharpWorkspaceFileSnapshots =
             csharpPreflight.WorkspaceFileSnapshots;
-        var csharpPrepassSymbolArtifacts =
-            csharpPreflight.PrepassSymbolArtifacts;
         var preservePriorPositiveCSharpSourceNoOp =
             csharpPreflight.PreservePriorPositiveSourceNoOp;
         var csharpSourceEvidenceForStamp =
@@ -526,29 +488,6 @@ void CountFreshInsertedRows(
         var csharpSourceEvidenceComplete =
             csharpPreflight.Evidence.Complete;
 
-        void DeferCSharpMutationsForLoadedSnapshotDrift(string path)
-        {
-            csharpPrepassSymbolArtifacts?.Clear();
-            csharpPrepassSymbolArtifacts = null;
-            path = FormatCSharpWorkspaceSnapshotPath(projectRoot, path);
-            deferCSharpMutationsForIncompleteScan = true;
-            preservePriorPositiveCSharpSourceNoOp = false;
-            csharpSourceEvidenceForStamp = false;
-            csharpSourceEvidenceComplete = false;
-            csharpWorkspaceFileSnapshots = null;
-            csharpWorkspace = new CSharpStaticInterfaceWorkspaceSymbols(
-                [],
-                HasStaticInterfaceContracts: true,
-                SourceContractEvidenceComplete: false,
-                IncompleteSourcePaths: [path]);
-            writer.SetCSharpStaticInterfaceSourceEvidence(null);
-            RecordCSharpWorkspaceFailure(
-                path,
-                "csharp_workspace_validation",
-                new IOException(
-                    "A C# source changed after workspace preflight; rerun indexing to refresh the complete C# graph."));
-        }
-
         // The captured scan has now crossed its only pre-write authority barrier. Start the
         // outer write scopes immediately afterwards so no durable readiness, evidence, purge,
         // or file mutation can precede the validation above.
@@ -662,115 +601,93 @@ void DeferCSharpMutationsForLoadedSnapshotDrift(string path)
 
         fullScanProgress.ReportJsonIndexProgressIfNeeded();
 
-        var extractionPipeline = RunFullScanExtractionPipeline(
-            new FullScanExtractionPipelineContext
+        var extractionSession = new FullScanExtractionSession
+        {
+            Request = new FullScanExtractionRequest(
+                    new FullScanExtractionCore(
+                        writer,
+                        indexer,
+                        options,
+                        projectRoot,
+                        fileTargets,
+                        preWriteSelection.ReadableFileBytes,
+                        indexProgress,
+                        fullScanProgress),
+                    new FullScanExtractionWork(
+                        extractionFileIndexes,
+                        extractionWorkItemCount,
+                        extractionParallelism,
+                        files.Count,
+                        forceExtractorRefresh,
+                        authoritativeFreshFoldRowsClaim,
+                        cancellationToken,
+                        actualMode),
+                    new FullScanExtractionContracts(
+                        priorSymbolsOnlyGraphOmitted,
+                        symbolKindFilterMatchesPrior,
+                        csharpIndexedProjectRootCompatible,
+                        csharpSymbolNameContractMatchesCurrent,
+                        sqlGraphContractMatchesCurrent,
+                        hdlGraphContractMatchesCurrent,
+                        startedWithNoIndexedFiles),
+                    new FullScanExtractionReuse(
+                        javaScriptTypeScriptRefreshRequired,
+                        hotspotFamilyTrustMatchesCurrent)),
+            State = new FullScanExtractionState
             {
-                Writer = writer,
-                Indexer = indexer,
-                Options = options,
-                ProjectRoot = projectRoot,
-                FileTargets = fileTargets,
-                ExtractionFileIndexes = extractionFileIndexes,
-                ExtractionWorkItemCount = extractionWorkItemCount,
-                ExtractionParallelism = extractionParallelism,
-                FilesCount = files.Count,
-                ForceExtractorRefresh = forceExtractorRefresh,
-                StartedWithNoIndexedFiles = startedWithNoIndexedFiles,
-                AuthoritativeFreshFoldRowsClaim = authoritativeFreshFoldRowsClaim,
-                PriorSymbolsOnlyGraphOmitted =
-                    priorSymbolsOnlyGraphOmitted,
-                SymbolKindFilterMatchesPrior =
-                    symbolKindFilterMatchesPrior,
-                CSharpIndexedProjectRootCompatible =
-                    csharpIndexedProjectRootCompatible,
-                CSharpSymbolNameContractMatchesCurrent =
-                    csharpSymbolNameContractMatchesCurrent,
-                SqlGraphContractMatchesCurrent =
-                    sqlGraphContractMatchesCurrent,
-                HdlGraphContractMatchesCurrent =
-                    hdlGraphContractMatchesCurrent,
-                ReadableFileBytes = preWriteSelection.ReadableFileBytes,
-                IndexProgress = indexProgress,
-                FullScanProgress = fullScanProgress,
-                CancellationToken = cancellationToken,
-                GetProcessedCount = () => preWriteSelection.Processed,
-                PublishProcessedCount = value => preWriteSelection.Processed = value,
-                ThrowIfFullScanCancelled =
-                    ThrowIfFullScanCancelled,
-                SetIndexProgressVisible =
-                    value => indexProgressVisible = value,
-                SetActiveExtractionPhases =
-                    phases => activeExtractionPhases = phases,
-                SetCurrentJsonIndexFile =
-                    path => currentJsonIndexFile = path,
-                GetCurrentJsonIndexFile =
-                    () => currentJsonIndexFile,
-                GetDeferCSharpMutationsForIncompleteScan =
-                    () => deferCSharpMutationsForIncompleteScan,
-                GetFtsMutated = () => ftsMutated,
-                GetCSharpWorkspace = () => csharpWorkspace,
-                GetCSharpPrepassSymbolArtifacts =
-                    () => csharpPrepassSymbolArtifacts,
-                GetCSharpWorkspaceFileSnapshots =
-                    () => csharpWorkspaceFileSnapshots,
-                DeferCSharpMutationsForLoadedSnapshotDrift =
-                    DeferCSharpMutationsForLoadedSnapshotDrift,
-                TargetRequiresJavaScriptTypeScriptRefresh =
-                    TargetRequiresJavaScriptTypeScriptRefresh,
-                AllowReuseWithCurrentHotspotFamilyTrust = language =>
-                    AllowReuseWithCurrentHotspotFamilyTrust(
-                        language,
-                        hotspotFamilyTrustMatchesCurrent),
-                RequireTypeScriptAugmentationRefresh =
-                    RequireTypeScriptAugmentationRefresh,
-                WriteProjectRootOnce = WriteProjectRootOnce,
-                InsertIssuesForIndexedFile =
-                    InsertIssuesForIndexedFile,
-                CountFreshInsertedRows = CountFreshInsertedRows,
-                ConsumerState = new FullScanExtractionConsumerState
+                PreWrite = preWriteState,
+                Refresh = new FullScanExtractionRefreshState
                 {
                     FtsMutated = ftsMutated,
-                    MutualRecursionRefreshNeeded =
-                        mutualRecursionRefreshNeeded,
-                    CSharpMetadataTargetsNeedRefresh =
-                        csharpMetadataTargetsNeedRefresh,
-                    SymbolsDroppedByKindFilter =
-                        symbolsDroppedByKindFilter,
-                    ReusedHotspotFamilyLanguages =
-                        preWriteSelection.ReusedHotspotFamilyLanguages,
-                    SkippedSymbolExtractorLanguages =
-                        preWriteSelection.SkippedSymbolExtractorLanguages,
-                    IndexedSymbolExtractorLanguages =
-                        indexedSymbolExtractorLanguages,
-                    ErrorList = errorList,
-                    FileErrorList = fileErrorList,
-                    WarningList = warningList,
+                    MutualRecursionRefreshNeeded = mutualRecursionRefreshNeeded,
+                    CSharpMetadataTargetsNeedRefresh = csharpMetadataTargetsNeedRefresh,
+                    SymbolsDroppedByKindFilter = symbolsDroppedByKindFilter,
+                    ReusedHotspotFamilyLanguages = preWriteSelection.ReusedHotspotFamilyLanguages,
+                    SkippedSymbolExtractorLanguages = preWriteSelection.SkippedSymbolExtractorLanguages,
+                    IndexedSymbolExtractorLanguages = indexedSymbolExtractorLanguages,
                 },
-            });
-        var postExtractionHooks =
-            extractionPipeline.PostExtractionHooks;
-        var extractionState = extractionPipeline.ConsumerState;
-        if (extractionState != null)
-        {
-            preWriteSelection.Skipped += extractionState.Skipped;
-            warnings += extractionState.Warnings;
-            errors += extractionState.ErrorsAdded;
-            ftsMutated = extractionState.FtsMutated;
-            mutualRecursionRefreshNeeded =
-                extractionState.MutualRecursionRefreshNeeded;
-            csharpMetadataTargetsNeedRefresh =
-                extractionState.CSharpMetadataTargetsNeedRefresh;
-            symbolsDroppedByKindFilter =
-                extractionState.SymbolsDroppedByKindFilter;
-            extractedFiles += extractionState.ExtractedFiles;
-            extractedChunks += extractionState.ExtractedChunks;
-            extractedSymbols += extractionState.ExtractedSymbols;
-            extractedReferences += extractionState.ExtractedReferences;
-            preWriteSelection.ReusedHotspotFamilyLanguages =
-                extractionState.ReusedHotspotFamilyLanguages;
-            preWriteSelection.SkippedSymbolExtractorLanguages =
-                extractionState.SkippedSymbolExtractorLanguages;
-        }
+            },
+            External = new FullScanExtractionExternalOperations(
+                    RequireTypeScriptAugmentationRefresh,
+                    WriteProjectRootOnce),
+        };
+        var postExtractionHooks = RunFullScanExtractionPipeline(extractionSession);
+        preWriteState.CSharp.PrepassSymbolArtifacts = null;
+        deferCSharpMutationsForIncompleteScan =
+            preWriteState.Scan.DeferCSharpMutationsForIncompleteScan;
+        csharpWorkspaceFileSnapshots =
+            preWriteState.CSharp.WorkspaceFileSnapshots;
+        csharpWorkspace = preWriteState.CSharp.Workspace;
+        preservePriorPositiveCSharpSourceNoOp =
+            preWriteState.CSharp.PreservePriorPositiveSourceNoOp;
+        csharpSourceEvidenceForStamp = preWriteState.CSharp.Evidence.ForStamp;
+        csharpSourceEvidenceComplete = preWriteState.CSharp.Evidence.Complete;
+        preWriteSelection.Skipped += extractionSession.State.Counts.Skipped;
+        persistedFiles += extractionSession.State.PersistenceCounts.PersistedFiles;
+        persistedChunks += extractionSession.State.PersistenceCounts.PersistedChunks;
+        persistedSymbols += extractionSession.State.PersistenceCounts.PersistedSymbols;
+        persistedReferences += extractionSession.State.PersistenceCounts.PersistedReferences;
+        freshCountFiles += extractionSession.State.PersistenceCounts.FreshFiles;
+        freshCountChunks += extractionSession.State.PersistenceCounts.FreshChunks;
+        freshCountSymbols += extractionSession.State.PersistenceCounts.FreshSymbols;
+        freshCountReferences += extractionSession.State.PersistenceCounts.FreshReferences;
+        warnings += extractionSession.State.Counts.Warnings;
+        errors = preWriteState.Diagnostics.Errors + extractionSession.State.Counts.Errors;
+        ftsMutated = extractionSession.State.Refresh.FtsMutated;
+        mutualRecursionRefreshNeeded =
+            extractionSession.State.Refresh.MutualRecursionRefreshNeeded;
+        csharpMetadataTargetsNeedRefresh =
+            extractionSession.State.Refresh.CSharpMetadataTargetsNeedRefresh;
+        symbolsDroppedByKindFilter =
+            extractionSession.State.Refresh.SymbolsDroppedByKindFilter;
+        extractedFiles += extractionSession.State.Counts.ExtractedFiles;
+        extractedChunks += extractionSession.State.Counts.ExtractedChunks;
+        extractedSymbols += extractionSession.State.Counts.ExtractedSymbols;
+        extractedReferences += extractionSession.State.Counts.ExtractedReferences;
+        preWriteSelection.ReusedHotspotFamilyLanguages =
+            extractionSession.State.Refresh.ReusedHotspotFamilyLanguages;
+        preWriteSelection.SkippedSymbolExtractorLanguages =
+            extractionSession.State.Refresh.SkippedSymbolExtractorLanguages;
 
         indexProgress.Pause();
 
@@ -927,10 +844,21 @@ void DeferCSharpMutationsForLoadedSnapshotDrift(string path)
                 cancellationToken);
             if (!readinessStableFiles || !readinessStableScanInputs)
             {
-                DeferCSharpMutationsForLoadedSnapshotDrift(
+                extractionSession.DeferCSharpMutationsForLoadedSnapshotDrift(
                     readinessChangedFilePath
                     ?? readinessChangedScanInputPath
                     ?? "<csharp_workspace>");
+                deferCSharpMutationsForIncompleteScan =
+                    preWriteState.Scan.DeferCSharpMutationsForIncompleteScan;
+                preservePriorPositiveCSharpSourceNoOp =
+                    preWriteState.CSharp.PreservePriorPositiveSourceNoOp;
+                csharpSourceEvidenceForStamp = preWriteState.CSharp.Evidence.ForStamp;
+                csharpSourceEvidenceComplete = preWriteState.CSharp.Evidence.Complete;
+                csharpWorkspaceFileSnapshots =
+                    preWriteState.CSharp.WorkspaceFileSnapshots;
+                csharpWorkspace = preWriteState.CSharp.Workspace;
+                errors = preWriteState.Diagnostics.Errors
+                    + extractionSession.State.Counts.Errors;
             }
         }
 
diff --git a/src/CodeIndex/Cli/IndexCommandRunner.cs b/src/CodeIndex/Cli/IndexCommandRunner.cs
index aa3f1d2d5..6dd20e76f 100644
--- a/src/CodeIndex/Cli/IndexCommandRunner.cs
+++ b/src/CodeIndex/Cli/IndexCommandRunner.cs
@@ -82,6 +82,7 @@ public void Dispose()
     internal static Action? FullScanWritePhaseStartedForTesting { get; set; }
     internal static Action<bool, string?>? FullScanExtractionSchedulingForTesting { get; set; }
     internal static Action? FullScanExtractionWorkStartedForTesting { get; set; }
+    internal static Action? FullScanExtractionWorkersStoppedForTesting { get; set; }
     internal static Action<string>? FullScanFileContentLoadForTesting { get; set; }
     internal static Action<string, string>? FullScanFilePhaseForTesting { get; set; }
     internal static Action<int>? FullScanExtractionQueueCapacityForTesting { get; set; }
diff --git a/tests/CodeIndex.Tests/IndexCommandRunnerFullScanTests.cs b/tests/CodeIndex.Tests/IndexCommandRunnerFullScanTests.cs
index 8d2725e1f..40b7991cf 100644
--- a/tests/CodeIndex.Tests/IndexCommandRunnerFullScanTests.cs
+++ b/tests/CodeIndex.Tests/IndexCommandRunnerFullScanTests.cs
@@ -2306,6 +2306,137 @@ FROM symbol_references r
         }
     }
 
+    [Fact]
+    public void Run_FullScan_FatalParallelResultKeepsWorkerResourcesAliveUntilPeersStop()
+    {
+        var projectRoot = CreateTempProject();
+        lock (FullScanContentLoadHookGate)
+        {
+            var previousPhaseHook = IndexCommandRunner.FullScanFilePhaseForTesting;
+            var previousWorkStartedHook =
+                IndexCommandRunner.FullScanExtractionWorkStartedForTesting;
+            var previousWorkersStoppedHook =
+                IndexCommandRunner.FullScanExtractionWorkersStoppedForTesting;
+            var previousArtifactHook =
+                CSharpPrepassSymbolArtifactCache.EventForTesting;
+            using var blockedWorkerStarted = new ManualResetEventSlim();
+            using var releaseBlockedWorker = new ManualResetEventSlim();
+            using var workersStopped = new ManualResetEventSlim();
+            using var artifactCleared = new ManualResetEventSlim();
+            var artifactEvents =
+                new ConcurrentQueue<CSharpPrepassSymbolArtifactCacheEvent>();
+            var pipelineUsed = 0;
+            try
+            {
+                File.WriteAllText(
+                    Path.Combine(projectRoot, "A.cs"),
+                    "public class A { public static int Value => 1; }\n");
+                File.WriteAllText(
+                    Path.Combine(projectRoot, "B.cs"),
+                    "public class B { public static int Value => 2; }\n");
+                CSharpPrepassSymbolArtifactCache.EventForTesting = item =>
+                {
+                    artifactEvents.Enqueue(item);
+                    if (item.Phase == "cleared")
+                        artifactCleared.Set();
+                };
+                IndexCommandRunner.FullScanExtractionWorkStartedForTesting = () =>
+                    Interlocked.Exchange(ref pipelineUsed, 1);
+                IndexCommandRunner.FullScanExtractionWorkersStoppedForTesting =
+                    workersStopped.Set;
+                IndexCommandRunner.FullScanFilePhaseForTesting = (path, phase) =>
+                {
+                    if (phase != "symbols")
+                        return;
+                    if (path == "A.cs")
+                    {
+                        blockedWorkerStarted.Set();
+                        releaseBlockedWorker.Wait(TimeSpan.FromSeconds(30));
+                        return;
+                    }
+                    if (path == "B.cs")
+                    {
+                        if (!blockedWorkerStarted.Wait(TimeSpan.FromSeconds(30)))
+                        {
+                            throw new TimeoutException(
+                                "The blocked full-scan peer did not reach symbol extraction.");
+                        }
+                        throw new IndexCommandRunner.IndexExtractionStalledException(
+                            0,
+                            null,
+                            TimeSpan.FromMilliseconds(10),
+                            "B.cs [symbols]",
+                            "injected fatal full-scan result");
+                    }
+                };
+
+                var stopwatch = Stopwatch.StartNew();
+                var (exitCode, json) = RunAndCaptureJson(
+                    [projectRoot, "--parallelism", "2", "--json", "--quiet"]);
+                stopwatch.Stop();
+
+                Assert.True(blockedWorkerStarted.IsSet);
+                Assert.True(
+                    stopwatch.Elapsed < TimeSpan.FromSeconds(5),
+                    $"The fatal full-scan result waited for its blocked peer for {stopwatch.Elapsed}.");
+                Assert.Equal(CommandExitCodes.CancelledBySignal, exitCode);
+                Assert.Equal(
+                    CommandErrorCodes.IndexExtractionStalled,
+                    json.GetProperty("error_code").GetString());
+                Assert.Contains(
+                    "B.cs [symbols]",
+                    json.GetProperty("message").GetString(),
+                    StringComparison.Ordinal);
+                Assert.Contains(
+                    "injected fatal full-scan result",
+                    json.GetProperty("message").GetString(),
+                    StringComparison.Ordinal);
+                Assert.False(workersStopped.IsSet);
+                Assert.Contains(
+                    artifactEvents,
+                    item => item.Phase == "admitted" && item.Path == "A.cs");
+                Assert.Contains(
+                    artifactEvents,
+                    item => item.Phase == "admitted" && item.Path == "B.cs");
+                Assert.DoesNotContain(artifactEvents, item => item.Phase == "cleared");
+
+                releaseBlockedWorker.Set();
+                Assert.True(
+                    workersStopped.Wait(TimeSpan.FromSeconds(30)),
+                    "The fatal full-scan extraction workers did not stop.");
+                Assert.True(
+                    artifactCleared.Wait(TimeSpan.FromSeconds(30)),
+                    "The full-scan worker resources were not cleared after the workers stopped.");
+                var completedEvents = artifactEvents.ToArray();
+                var takenIndex = Array.FindIndex(
+                    completedEvents,
+                    item => item.Phase == "taken" && item.Path == "A.cs");
+                var clearedIndex = Array.FindIndex(
+                    completedEvents,
+                    item => item.Phase == "cleared");
+                Assert.True(takenIndex >= 0);
+                Assert.True(clearedIndex > takenIndex);
+                Assert.Equal(1, completedEvents.Count(item => item.Phase == "cleared"));
+            }
+            finally
+            {
+                releaseBlockedWorker.Set();
+                var cleanupSafe = Volatile.Read(ref pipelineUsed) == 0
+                    || workersStopped.Wait(TimeSpan.FromSeconds(30));
+                IndexCommandRunner.FullScanFilePhaseForTesting = previousPhaseHook;
+                IndexCommandRunner.FullScanExtractionWorkStartedForTesting =
+                    previousWorkStartedHook;
+                IndexCommandRunner.FullScanExtractionWorkersStoppedForTesting =
+                    previousWorkersStoppedHook;
+                CSharpPrepassSymbolArtifactCache.EventForTesting =
+                    previousArtifactHook;
+                if (cleanupSafe)
+                    DeleteDirectory(projectRoot);
+                SqliteConnection.ClearAllPools();
+            }
+        }
+    }
+
     [Fact]
     public void Run_FullScan_ParallelCsharpStaticInterfacePrepass_IndexesImplicitImplementationReference()
     {
@@ -2686,24 +2817,42 @@ public void Second() { }
     }
 
     [Theory]
-    [InlineData(false)]
-    [InlineData(true)]
+    [InlineData(false, false)]
+    [InlineData(true, false)]
+    [InlineData(false, true)]
     public void Run_FullScan_PostPrepassCsharpContractLeavesReadinessPartialUntilCleanRetry(
-        bool rebuildExisting)
+        bool rebuildExisting,
+        bool incrementalExisting)
     {
         var projectRoot = CreateTempProject();
-        var interfacePath = Path.Combine(projectRoot, "IParseable.cs");
-        var moneyPath = Path.Combine(projectRoot, "Money.cs");
+        var csharpRoot = Path.Combine(projectRoot, "csharp");
+        var interfacePath = Path.Combine(csharpRoot, "IParseable.cs");
+        var moneyPath = Path.Combine(csharpRoot, "Money.cs");
+        var ftsSourcePath = Path.Combine(projectRoot, "00_FtsBeforeDrift.py");
         const string moneySource =
             "public readonly struct Money : IParseable<Money>\n"
             + "{\n"
             + "    public static Money Parse(string s) => new();\n"
             + "}\n";
         var previousContentLoadHook = IndexCommandRunner.FullScanFileContentLoadForTesting;
+        var previousOptimizeHook = IndexCommandRunner.FullScanFtsOptimizeForTesting;
         var interfaceRewritten = false;
+        var optimizeCount = 0;
         try
         {
-            if (rebuildExisting)
+            Directory.CreateDirectory(csharpRoot);
+            if (incrementalExisting)
+            {
+                File.WriteAllText(ftsSourcePath, "# fullscanftsbaseline\n");
+                File.WriteAllText(
+                    interfacePath,
+                    "public interface IParseable<T> { } // baseline\n");
+                File.WriteAllText(moneyPath, moneySource);
+                Assert.Equal(
+                    CommandExitCodes.Success,
+                    IndexCommandRunner.Run([projectRoot, "--json", "--quiet"], _jsonOptions));
+            }
+            else if (rebuildExisting)
             {
                 File.WriteAllText(Path.Combine(projectRoot, "app.py"), "print('ready')\n");
                 Assert.Equal(
@@ -2711,8 +2860,25 @@ public void Run_FullScan_PostPrepassCsharpContractLeavesReadinessPartialUntilCle
                     IndexCommandRunner.Run([projectRoot, "--json", "--quiet"], _jsonOptions));
             }
 
+            File.WriteAllText(ftsSourcePath, "# fullscanftsdrifttoken\n");
             File.WriteAllText(interfacePath, "public interface IParseable<T> { }\n");
-            File.WriteAllText(moneyPath, moneySource);
+            File.WriteAllText(
+                moneyPath,
+                incrementalExisting
+                    ? moneySource + "// dirty before extraction\n"
+                    : moneySource);
+            if (incrementalExisting)
+            {
+                var changedAt = DateTime.UtcNow.AddSeconds(2);
+                File.SetLastWriteTimeUtc(ftsSourcePath, changedAt);
+                File.SetLastWriteTimeUtc(interfacePath, changedAt);
+                File.SetLastWriteTimeUtc(moneyPath, changedAt);
+            }
+            IndexCommandRunner.FullScanFtsOptimizeForTesting = () =>
+            {
+                optimizeCount++;
+                previousOptimizeHook?.Invoke();
+            };
             IndexCommandRunner.FullScanFileContentLoadForTesting = path =>
             {
                 if (interfaceRewritten || !path.EndsWith(".cs", StringComparison.OrdinalIgnoreCase))
@@ -2738,6 +2904,29 @@ public void Run_FullScan_PostPrepassCsharpContractLeavesReadinessPartialUntilCle
             Assert.Contains(
                 partialJson.GetProperty("file_errors").EnumerateArray(),
                 error => error.GetProperty("phase").GetString() == "csharp_workspace_validation");
+            var dbPath = Path.Combine(projectRoot, ".cdidx", "codeindex.db");
+            (long chunks, long fts, long trigram) ftsCounts;
+            using (var connection = OpenNonPoolingConnection(dbPath))
+            {
+                connection.Open();
+                using var command = connection.CreateCommand();
+                command.CommandText = """
+                    SELECT
+                        (SELECT COUNT(*) FROM chunks WHERE content LIKE '%fullscanftsdrifttoken%'),
+                        (SELECT COUNT(*) FROM fts_chunks WHERE fts_chunks MATCH 'fullscanftsdrifttoken'),
+                        (SELECT COUNT(*) FROM fts_chunks_trigram WHERE fts_chunks_trigram MATCH 'fullscanftsdrifttoken')
+                    """;
+                using var reader = command.ExecuteReader();
+                Assert.True(reader.Read());
+                ftsCounts = (
+                    reader.GetInt64(0),
+                    reader.GetInt64(1),
+                    reader.GetInt64(2));
+            }
+            Assert.Equal(1L, ftsCounts.chunks);
+            Assert.Equal(
+                (fts: 1L, trigram: 1L, optimize: 1),
+                (fts: ftsCounts.fts, trigram: ftsCounts.trigram, optimize: optimizeCount));
 
             IndexCommandRunner.FullScanFileContentLoadForTesting = previousContentLoadHook;
             var (recoveryExitCode, recoveryJson) = RunAndCaptureJson(arguments);
@@ -2749,6 +2938,7 @@ public void Run_FullScan_PostPrepassCsharpContractLeavesReadinessPartialUntilCle
         finally
         {
             IndexCommandRunner.FullScanFileContentLoadForTesting = previousContentLoadHook;
+            IndexCommandRunner.FullScanFtsOptimizeForTesting = previousOptimizeHook;
             DeleteDirectory(projectRoot);
             SqliteConnection.ClearAllPools();
         }

From b7d559b2a8216e189cf963d24bc32d78199acb1f Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 19:14:02 +0900
Subject: [PATCH 44/45] Inline pattern extraction scan state

---
 .../SymbolExtractor.ExtractionPhases.cs       | 19 ++++++++++----
 .../SymbolExtractor.PatternEmissionFlow.cs    |  2 +-
 .../SymbolExtractor.PatternExtraction.cs      |  2 +-
 .../Symbols/SymbolExtractor.PatternLoop.cs    |  4 +--
 tests/CodeIndex.Tests/PerformanceTests.cs     | 25 +++++++++++++++++++
 5 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.ExtractionPhases.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.ExtractionPhases.cs
index acd4ab60d..170103610 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.ExtractionPhases.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.ExtractionPhases.cs
@@ -173,12 +173,21 @@ private bool[] BuildCssQualifiedRuleAncestors() =>
             _cssQualifiedRuleAncestors ??= FindCssQualifiedRuleAncestors(CssScannerLines!);
     }
 
-    private sealed class PatternScanState
+    private struct PatternScanState
     {
-        public FSharpTypeBodyState FSharpTypeBodyState = FSharpTypeBodyState.None;
+        public PatternScanState()
+        {
+            FSharpTypeBodyState = FSharpTypeBodyState.None;
+            GoImportBlock = false;
+            CSharpSuppressedContinuationUntil = -1;
+            CSharpSuppressedContinuationResumeLine = -1;
+            CSharpSuppressedContinuationResumeRawColumn = 0;
+        }
+
+        public FSharpTypeBodyState FSharpTypeBodyState;
         public bool GoImportBlock;
-        public int CSharpSuppressedContinuationUntil = -1;
-        public int CSharpSuppressedContinuationResumeLine = -1;
+        public int CSharpSuppressedContinuationUntil;
+        public int CSharpSuppressedContinuationResumeLine;
         public int CSharpSuppressedContinuationResumeRawColumn;
     }
 
@@ -197,7 +206,7 @@ private static bool TryPreparePatternLine(
         string? projectRoot,
         string[] lines,
         PatternScanInputs scanInputs,
-        PatternScanState scanState,
+        ref PatternScanState scanState,
         SymbolExtractionList symbols,
         SymbolExtractionState extractionState,
         HashSet<string>? dockerfileStageNames,
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternEmissionFlow.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternEmissionFlow.cs
index f67384b9e..21262f117 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternEmissionFlow.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternEmissionFlow.cs
@@ -40,7 +40,7 @@ private static PatternScanResult EmitAcceptedPatternSymbol(
         var extractionState = extraction.ExtractionState;
         var cssSeenSymbols = extraction.CssSeenSymbols;
         var dockerfileStageNames = extraction.DockerfileStageNames;
-        var scanState = extraction.ScanState;
+        ref var scanState = ref extraction.ScanState;
         ref var pendingRecordPrimaryComponents = ref extraction.PendingRecordPrimaryComponents;
         ref var recordPrimaryComponentParentIndex = ref extraction.RecordPrimaryComponentParentIndex;
         emittedKind = kind;
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternExtraction.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternExtraction.cs
index 3e84e8b68..a0cced313 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternExtraction.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternExtraction.cs
@@ -80,7 +80,7 @@ public PatternExtractionContext(
         public Func<CSharpDeclarationStartScope> GetCSharpDeclarationStartScope { get; }
         public SymbolExtractionList Symbols { get; }
         public SymbolExtractionState ExtractionState { get; }
-        public PatternScanState ScanState { get; }
+        public PatternScanState ScanState;
         public HashSet<SymbolLineIdentity>? CssSeenSymbols { get; }
         public HashSet<string>? DockerfileStageNames { get; }
         public List<PendingRecordPrimaryComponents>? PendingRecordPrimaryComponents;
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternLoop.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternLoop.cs
index ee0063be3..0caece88f 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternLoop.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.PatternLoop.cs
@@ -17,7 +17,7 @@ private static void ScanPatternLines(PatternExtractionContext context)
         var scanInputs = context.ScanInputs;
         var symbols = context.Symbols;
         var extractionState = context.ExtractionState;
-        var scanState = context.ScanState;
+        ref var scanState = ref context.ScanState;
         var dockerfileStageNames = context.DockerfileStageNames;
         for (int i = 0; i < lines.Length; i++)
         {
@@ -34,7 +34,7 @@ private static void ScanPatternLines(PatternExtractionContext context)
                     projectRoot,
                     lines,
                     scanInputs,
-                    scanState,
+                    ref scanState,
                     symbols,
                     extractionState,
                     dockerfileStageNames,
diff --git a/tests/CodeIndex.Tests/PerformanceTests.cs b/tests/CodeIndex.Tests/PerformanceTests.cs
index 5c2ba075c..87d475f85 100644
--- a/tests/CodeIndex.Tests/PerformanceTests.cs
+++ b/tests/CodeIndex.Tests/PerformanceTests.cs
@@ -238,6 +238,31 @@ public void SymbolExtraction_CsharpHotPath_StaysWithinAllocationBudget()
         Assert.True(allocatedBytes < 18_000_000, $"Symbol extraction allocated {allocatedBytes:N0} bytes");
     }
 
+#if NET8_0
+    [Fact]
+#else
+    [Fact(Skip = PracticalBudgetTestTarget.SecondaryTargetSkipReason)]
+#endif
+    public void SymbolExtraction_PatternContext_StaysWithinAllocationBudget()
+    {
+        const string content = "package sample\n\nfunc run() {}\n";
+        const int extractionCount = 4_096;
+        var symbols = SymbolExtractor.Extract(1, "go", content);
+        Assert.Contains(symbols, symbol => symbol.Kind == "function" && symbol.Name == "run");
+        for (var iteration = 0; iteration < 32; iteration++)
+            _ = SymbolExtractor.Extract(1, "go", content);
+
+        var allocatedBytes = MeasureAllocatedBytes(() =>
+        {
+            for (var iteration = 0; iteration < extractionCount; iteration++)
+                _ = SymbolExtractor.Extract(1, "go", content);
+        });
+
+        Assert.True(
+            allocatedBytes < 16_730_000,
+            $"Pattern extraction allocated {allocatedBytes:N0} bytes for {extractionCount:N0} files");
+    }
+
 #if NET8_0
     [Fact]
 #else

From 068d1fbe89488a0a6da8a19fa92dd1c669d2c272 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Thu, 13 Aug 2026 19:22:18 +0900
Subject: [PATCH 45/45] Keep JVM triple-string scanning stack-local

---
 .../StructuralLineMasker.JvmTripleStrings.cs  | 20 +++++++++------
 tests/CodeIndex.Tests/PerformanceTests.cs     | 25 +++++++++++++++++++
 2 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmTripleStrings.cs b/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmTripleStrings.cs
index c7b1d067d..a3d3a69ad 100644
--- a/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmTripleStrings.cs
+++ b/src/CodeIndex/Indexer/References/Support/StructuralLineMasker.JvmTripleStrings.cs
@@ -8,17 +8,23 @@ private enum JvmTripleStringPolicy
         Scala,
     }
 
-    private static void MaskKotlinTripleStringContents(string[] lines) =>
-        new JvmTripleStringScanner(
+    private static void MaskKotlinTripleStringContents(string[] lines)
+    {
+        var scanner = new JvmTripleStringScanner(
             lines,
-            JvmTripleStringPolicy.Kotlin).MaskLines();
+            JvmTripleStringPolicy.Kotlin);
+        scanner.MaskLines();
+    }
 
-    private static void MaskScalaTripleStringContents(string[] lines) =>
-        new JvmTripleStringScanner(
+    private static void MaskScalaTripleStringContents(string[] lines)
+    {
+        var scanner = new JvmTripleStringScanner(
             lines,
-            JvmTripleStringPolicy.Scala).MaskLines();
+            JvmTripleStringPolicy.Scala);
+        scanner.MaskLines();
+    }
 
-    private sealed class JvmTripleStringScanner(
+    private struct JvmTripleStringScanner(
         string[] lines,
         JvmTripleStringPolicy policy)
     {
diff --git a/tests/CodeIndex.Tests/PerformanceTests.cs b/tests/CodeIndex.Tests/PerformanceTests.cs
index 87d475f85..f596cdb20 100644
--- a/tests/CodeIndex.Tests/PerformanceTests.cs
+++ b/tests/CodeIndex.Tests/PerformanceTests.cs
@@ -263,6 +263,31 @@ public void SymbolExtraction_PatternContext_StaysWithinAllocationBudget()
             $"Pattern extraction allocated {allocatedBytes:N0} bytes for {extractionCount:N0} files");
     }
 
+#if NET8_0
+    [Fact]
+#else
+    [Fact(Skip = PracticalBudgetTestTarget.SecondaryTargetSkipReason)]
+#endif
+    public void StructuralLineMasking_JvmTripleStrings_StaysWithinAllocationBudget()
+    {
+        string[] lines = ["val value = \"\"\"literal\"\"\""];
+        const int maskingCount = 4_096;
+        var masked = StructuralLineMasker.MaskLines("kotlin", lines);
+        Assert.DoesNotContain("literal", masked[0], StringComparison.Ordinal);
+        for (var iteration = 0; iteration < 32; iteration++)
+            _ = StructuralLineMasker.MaskLines("kotlin", lines);
+
+        var allocatedBytes = MeasureAllocatedBytes(() =>
+        {
+            for (var iteration = 0; iteration < maskingCount; iteration++)
+                _ = StructuralLineMasker.MaskLines("kotlin", lines);
+        });
+
+        Assert.True(
+            allocatedBytes < 1_000_000,
+            $"JVM triple-string masking allocated {allocatedBytes:N0} bytes for {maskingCount:N0} calls");
+    }
+
 #if NET8_0
     [Fact]
 #else