Make inspect selectors reusable and overload-aware (#5159)

DEVELOPER_GUIDE.md

@@ -1746,6 +1746,19 @@ language across reference/caller/callee evidence. `graph_language_source`,
 `graph_language_confidence`, `graph_language_candidates`, and `graph_language_conflict`
 distinguish authoritative filter/definition decisions from consistent inference and keep
 mixed-language evidence unresolved.
+CLI `inspect --selector 'id:<n>@g:<fingerprint>'` validates the emitted index generation, resolves
+the persisted ID directly in the active database, and then enters this same candidate-bundle path.
+Keep selector parsing in a typed extensible model,
+reject non-positive/malformed IDs before opening graph state, and report an absent database-local
+ID or a stale/cross-database generation as `E018_QUERY_NOT_FOUND`. The unversioned `id:<n>` form
+remains a same-database compatibility input but cannot prove generation provenance.
+`identity_scoped` must describe evidence precision, not merely schema
+availability: if an inbound reference still has more than one resolution candidate, emit
+`identity_scope_reason: ambiguous_reference_candidates` and keep the candidate rows visible while
+marking the bundle non-identity-scoped. C# call resolution may narrow ordinary required-parameter
+overloads by positional argument count only. Named arguments, optional/default parameters,
+`params`, generic method inference, and incomplete syntax remain ambiguous. Extension receiver
+adjustment and dynamic receiver types are outside this arity helper.
 Path/line resolution must select `symbols.id` and enter the same candidate-bundle builder as
 name resolution; do not hand graph loaders only the display name. Each bounded references,
 callers, and callees section computes its own stable-order page and authoritative total.
@@ -5707,6 +5720,18 @@ reference/caller/callee query は `symbol_reference_candidates` または
 言語を推論します。`graph_language_source`、`graph_language_confidence`、
 `graph_language_candidates`、`graph_language_conflict` により、filter/definition による
 authoritative な判定と一貫した推論を区別し、複数言語の evidence は未確定のままにします。
+CLI `inspect --selector 'id:<n>@g:<fingerprint>'` は出力時の index generation を検証し、active
+database の永続 ID を直接解決してから同じ candidate-bundle 経路へ入ります。selector parser は型付きで拡張可能な model に保ち、正でない
+ID や不正形式は graph state を開く前に拒否し、database-local ID が存在しない場合は
+もちろん、stale / cross-database generation の場合も `E018_QUERY_NOT_FOUND` を返してください。
+generation なしの `id:<n>` は same-database 互換入力として維持しますが、generation provenance
+は証明できません。`identity_scoped` は schema の利用可否だけでなく
+evidence の精度を表します。inbound reference に複数の resolution candidate が残る場合は
+candidate row を維持しつつ bundle を non-identity-scoped とし、
+`identity_scope_reason: ambiguous_reference_candidates` を出力します。C# call は通常の required
+parameter overload を位置引数個数だけで絞り込めます。named argument、optional/default parameter、
+`params`、generic method inference、不完全な構文は曖昧なままにします。extension の receiver
+調整と dynamic receiver の型は、この arity helper の対象外です。
 path/line resolution は `symbols.id` を select し、name resolution と同じ
 candidate-bundle builder に入れてください。graph loader に display name だけを渡しては
 なりません。上限付きの references、callers、callees section は、それぞれ安定順序の page と

TESTING_GUIDE.md

@@ -879,6 +879,7 @@ Use the inventory below before adding or moving a test class:
 - Console-only test classes belong in the dedicated non-parallel console-sensitive collection once every capture/swap window, including writer-disposal checks, is protected by `ConsoleCapture` or `TestConsoleLock.Gate`; they do not also need the SQLite-sensitive collection.
 - Pure i18n resolution, self-locking JSON-envelope capture, and isolated LSP request/budget fixtures should remain outside the SQLite-sensitive collection; owning a temporary DB is not itself process-global state when the context is disposed before helper cleanup.
 - Independent C# query regressions for static lambdas, declaration continuations, and named-argument labels use standalone test classes plus `QueryCommandTestSupport`; do not fold them back into the SQLite-pool-sensitive `QueryCommandRunnerTests` partial class.
+- Inspect-selector overload regressions also stay standalone with `QueryCommandTestSupport`. Cover emitted-selector round trips, candidate-scoped pagination, missing/malformed/stale/cross-database IDs, distinct required-arity calls, and truthful ambiguity for named/generic/optional/`params` cases in isolated indexed fixtures.
 - JSON compatibility-alias and versioned-error query regressions also use standalone classes and the same self-locking support so their independent temporary databases can run outside the pool-sensitive collection.
 - Search fixture classification and count-mode guard-filter regressions are standalone for the same reason; their per-test databases and self-locking console captures do not require SQLite pool serialization.
 - Status hotspot-readiness regressions are standalone and reuse the shared partial-type database fixture from `QueryCommandTestSupport`; keep the fixture centralized even though the status class runs outside the pool-sensitive collection.
@@ -1998,6 +1999,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
 - console だけを扱う test class は、writer disposal check を含むすべての capture / swap 期間を `ConsoleCapture` または `TestConsoleLock.Gate` で保護したうえで、専用の non-parallel な console-sensitive collection に入れる。SQLite-sensitive collection にも入れる必要はない。
 - pure i18n resolution、内部で lock する JSON-envelope capture、独立した LSP request / budget fixture は SQLite-sensitive collection の外に保つ。一時 DB を所有するだけなら、context を helper cleanup 前に dispose している限り process-global state ではない。
 - static lambda、宣言 continuation、named-argument label の独立した C# query regression は standalone test class と `QueryCommandTestSupport` を使います。SQLite-pool-sensitive な `QueryCommandRunnerTests` partial class に戻さないでください。
+- inspect selector の overload regression も `QueryCommandTestSupport` を使う standalone class に保ちます。出力 selector の往復、candidate-scoped pagination、存在しない / 不正 / stale / cross-database の ID、required arity が異なる call、named / generic / optional / `params` の正直な曖昧性を、独立した indexed fixture で検証してください。
 - JSON compatibility-alias と versioned-error の query regression も standalone class と同じ self-locking support を使い、独立した一時 database を pool-sensitive collection の外で実行してください。
 - search fixture classification と count-mode guard-filter の regression も同じ理由で standalone にします。test ごとの database と self-locking console capture は SQLite pool の直列化を必要としません。
 - status hotspot-readiness regression は standalone とし、共有 partial-type database fixture を `QueryCommandTestSupport` から再利用します。status class を pool-sensitive collection の外で実行しても fixture は一元化してください。

USER_GUIDE.md

@@ -338,7 +338,17 @@ traverse a combined identity graph; narrow it with language or path filters.
 `inspect` and MCP `analyze_symbol` return `candidate_bundles` when a name resolves to
 indexed definitions. Each bundle is labeled with a stable selector containing the symbol ID,
 qualified/container name, signature, language, kind, path, and line, and its graph sections
-are scoped to that candidate identity. When multiple candidates are returned, the top-level
+are scoped to that candidate identity. Reuse an emitted generation-bound ID selector with
+`cdidx inspect --selector 'id:<n>@g:<fingerprint>'` against the same database to inspect exactly
+that physical symbol without repeating name resolution. The legacy `id:<n>` form is accepted for
+the active database, but only the emitted generation fingerprint can detect a rebuilt or different
+database. Symbol IDs are database-local; a missing, stale, or cross-database selector returns
+`E018_QUERY_NOT_FOUND`. `identity_scoped` is true only when every inbound edge belongs uniquely
+to the selected identity. `identity_scope_reason: ambiguous_reference_candidates` keeps
+optional, `params`, named-argument, generic-inference, and otherwise unresolved overload evidence
+explicit instead of presenting duplicated candidate evidence as exact. C# calls with ordinary
+required parameters are narrowed only when their positional argument count safely distinguishes
+an overload; extension receiver adjustment and dynamic receiver types are not inferred by this narrowing. When multiple candidates are returned, the top-level
 `references`, `callers`, and `callees` arrays are explicitly labeled
 `graph_scope: primary_candidate` and mirror only the first prioritized bundle instead of
 merging unrelated definitions; consume the corresponding bundle for every other candidate.
@@ -420,6 +430,10 @@ same section envelopes and accepts their cursors. In path/line mode, `--path`
 locates the definition but does not restrict inbound references or callers to
 that file. Inspect graph cursors are accepted only by `inspect`; passing one to
 another command is a usage error.
+Selector-mode pagination uses the same contract: replay `--selector`, the same
+filters and page size, and the returned `--cursor`. Do not combine `--selector`
+with a symbol query, source coordinate, or `--group-partials`; `--path` by itself
+remains an evidence filter.
 For narrower `inspect` evidence, `--fields <csv|list>` implies JSON and selects
 top-level groups such as `definitions`, `file`, `graph`, `references`,
 `callers`, and `callees`. Collection selectors accept one nested level, for
@@ -3996,7 +4010,18 @@ language または path filter で対象を絞り込んでください。
 `inspect` と MCP `analyze_symbol` は、名前が index 済み定義へ解決される場合に
 `candidate_bundles` を返します。各 bundle は symbol ID、qualified/container name、
 signature、language、kind、path、line を含む安定 selector で識別され、graph section は
-その candidate identity に限定されます。複数 candidate が返る場合、top-level の
+その candidate identity に限定されます。同じ database に対して、出力された generation-bound
+ID selector を `cdidx inspect --selector 'id:<n>@g:<fingerprint>'` で再利用すると、name resolution
+を繰り返さず対象の物理 symbol だけを inspect できます。legacy の `id:<n>` 形式も active database
+向けに受理しますが、再構築後または別 database であることを検出できるのは出力された generation
+fingerprint 付き形式だけです。symbol ID は database-local であり、存在しない、stale、または
+cross-database selector は `E018_QUERY_NOT_FOUND` を返します。`identity_scoped` は inbound edge がすべて選択 identity
+へ一意に属する場合だけ true になります。optional、`params`、named argument、generic inference
+などで overload を確定できない場合は `identity_scope_reason: ambiguous_reference_candidates` を
+返し、重複した candidate evidence を exact として扱いません。C# の通常の required parameter
+呼び出しは、位置引数の個数で overload を安全に区別できる場合だけ絞り込みます。extension の
+receiver 調整と dynamic receiver の型はこの絞り込みでは推論しません。
+複数 candidate が返る場合、top-level の
 `references`、`callers`、`callees` 配列は `graph_scope: primary_candidate` と
 明示され、無関係な定義を結合せず優先順位1位の bundle だけを反映します。それ以外は
 対応する bundle を利用してください。`--fields candidates` で bundle を明示的に
@@ -4076,6 +4101,10 @@ path/line mode の `--path` は定義の位置を特定しますが、inbound re
 そのファイルだけに制限しません。MCP `analyze_symbol` も同じ section envelope を公開し、
 その cursor を受け付けます。inspect graph cursor は `inspect` だけが受理し、別 command に
 渡すと usage error になります。
+selector mode の pagination も同じ contract を使います。`--selector`、同じ filter と page size、
+返された `--cursor` を再指定してください。`--selector` は symbol query、source coordinate、
+`--group-partials` と組み合わせられません。`--path` だけを指定した場合は evidence filter として
+引き続き利用できます。
 `inspect` の証跡をさらに絞りたい場合、`--fields <csv|list>` は JSON 出力を暗黙に有効化し、
 `definitions`、`file`、`graph`、`references`、`callers`、`callees` などの
 top-level group を選択します。collection selector は 1 階層の nested field に対応し、

changelog.d/unreleased/5159.fixed.md

@@ -0,0 +1,40 @@
+---
+category: fixed
+issues:
+  - 5159
+affected:
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/InspectGraphCursor.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.ArgumentParser.Results.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.ArgumentParser.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.Inspect.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Mcp/McpToolHandlers.cs
+  - src/CodeIndex/Database/DbContext.ConnectionFunctionRegistration.cs
+  - src/CodeIndex/Database/DbContext.SchemaMetadata.cs
+  - src/CodeIndex/Database/DbReader.FilesStatus.cs
+  - src/CodeIndex/Database/DbSymbolReader.Analysis.cs
+  - src/CodeIndex/Database/DbSymbolReader.Hotspots.cs
+  - src/CodeIndex/Database/DbWriter.References.cs
+  - src/CodeIndex/Indexer/CSharpTypeReferenceArity.cs
+  - src/CodeIndex/Models/QueryResults.cs
+  - src/CodeIndex/Models/SymbolSelector.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerIssue5159Tests.cs
+  - tests/CodeIndex.Tests/DbReaderSymbolIdentityTests.cs
+  - tests/CodeIndex.Tests/DbReaderSymbolQueryTests.cs
+  - tests/CodeIndex.Tests/DbReaderImpactTests.cs
+  - tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+  - USER_GUIDE.md
+  - DEVELOPER_GUIDE.md
+  - TESTING_GUIDE.md
+---
+
+## English
+
+- **Inspect selectors now round-trip exact overload identities (#5159)** — `inspect --selector 'id:<n>@g:<fingerprint>'` reuses emitted generation-bound, database-local symbol IDs with candidate-scoped pagination and stable missing/invalid/stale diagnostics. C# required-parameter overloads narrow conservatively by positional argument count, while optional, `params`, named, generic, and unresolved calls remain explicitly non-identity-scoped instead of duplicating evidence under a false exact label.
+
+## 日本語
+
+- **inspect selector で正確な overload identity を再利用できるようになりました (#5159)** — `inspect --selector 'id:<n>@g:<fingerprint>'` は出力済みの generation-bound かつ database-local な symbol ID を candidate-scoped pagination と安定した missing / invalid / stale diagnostic 付きで再利用します。C# の required-parameter overload は位置引数個数で保守的に絞り込み、optional、`params`、named、generic、未解決 call は、重複 evidence を誤って exact とせず明示的に non-identity-scoped のままにします。

src/CodeIndex/Cli/CliFlagSchema.cs

@@ -515,6 +515,7 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--indexed-only", Description = "Languages: list only languages present in the current index", PrimaryCommands = Set(LanguagesFilterCommands) },
             new() { Name = "--capability", ValueDomain = Values(["all", "none", "graph", "references", "symbols", "missing-any", "missing-graph", "missing-references", "missing-symbols", "search-only"]), Description = "Languages: filter by language capability or capability gap", PrimaryCommands = Set(LanguagesFilterCommands) },
             new() { Name = "--query", ValuePlaceholder = "<query>", Description = "Literal query", PrimaryCommands = Set(QueryCommands) },
+            new() { Name = "--selector", ValuePlaceholder = "<id:n[@g:fingerprint]>", Description = "Inspect one exact symbol identity using a selector emitted by inspect", PrimaryCommands = Set("inspect") },
             new() { Name = "--recipe", ValuePlaceholder = "<name|name/query>", ValueKind = CliOptionValueKind.FreeText, Description = "Search: run a built-in audit recipe query set, optionally selecting one child query", PrimaryCommands = Set("search") },
             new() { Name = "--include-query", ValuePlaceholder = "<name>", Description = "Search recipe: include one child query; repeat or comma-separate values", PrimaryCommands = Set("search") },
             new() { Name = "--exclude-query", ValuePlaceholder = "<name>", Description = "Search recipe: exclude one child query; repeat or comma-separate values", PrimaryCommands = Set("search") },