Harden exact graph identity semantics (#5187)

Author: Widthdom

changelog.d/unreleased/5187.fixed.md

@@ -5,14 +5,18 @@ issues:
 affected:
   - src/CodeIndex/Database/DbReader.GraphIdentity.cs
   - src/CodeIndex/Database/DbReader.GraphQueries.cs
+  - src/CodeIndex/Database/DbReader.GraphReferenceQueries.cs
+  - src/CodeIndex/Database/DbReader.GraphReferenceQueryExecution.cs
   - src/CodeIndex/Database/DbReader.ImpactDefinitions.cs
   - src/CodeIndex/Database/DbReader.References.cs
   - src/CodeIndex/Database/DbReader.ImpactTraversal.cs
   - src/CodeIndex/Database/DbSymbolReader.Analysis.cs
   - src/CodeIndex/Cli/CliFlagSchema.cs
   - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/JsonEnvelopeWrapper.Bounded.cs
   - src/CodeIndex/Cli/QueryCommandRunner.Graph.cs
   - src/CodeIndex/Cli/QueryCommandRunner.Dependencies.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.Locations.cs
   - src/CodeIndex/Cli/ProjectionFieldRegistry.cs
   - src/CodeIndex/Mcp/McpToolArgumentContracts.cs
   - src/CodeIndex/Mcp/McpToolCatalog.cs

src/CodeIndex/Cli/QueryCommandRunner.Graph.cs

@@ -68,7 +68,8 @@ public static int RunReferences(string[] cmdArgs, JsonSerializerOptions jsonOpti
                             options.ExcludePaths,
                             options.ExcludeTests,
                             options.Kind,
-                            includeQualifiedCommonCalls: options.IncludeQualifiedCommonCalls)
+                            includeQualifiedCommonCalls: options.IncludeQualifiedCommonCalls,
+                            requireAuthoritativeIdentity: true)
                         : reader.CountSearchReferencesTotal(query, options.Lang, options.Kind, options.PathPatterns, options.ExcludePaths, options.ExcludeTests, exact, options.IncludeQualifiedCommonCalls);
                 var effectiveSqlGraphSignal = NarrowSqlGraphContractSignal(
                     baseSqlGraphSignal,
@@ -113,7 +114,8 @@ public static int RunReferences(string[] cmdArgs, JsonSerializerOptions jsonOpti
                         options.MaxLineWidth,
                         offset: JsonEnvelopeWrapper.GetBoundedResponseOffset("references"),
                         referenceKind: options.Kind,
-                        includeQualifiedCommonCalls: options.IncludeQualifiedCommonCalls)
+                        includeQualifiedCommonCalls: options.IncludeQualifiedCommonCalls,
+                        requireAuthoritativeIdentity: true)
                     : reader.SearchReferences(query, options.Limit, options.Lang, options.Kind, options.PathPatterns, options.ExcludePaths, options.ExcludeTests, exact, options.MaxLineWidth, offset: JsonEnvelopeWrapper.GetBoundedResponseOffset("references"), includeQualifiedCommonCalls: options.IncludeQualifiedCommonCalls);
             if (options.IncludeBody && JsonEnvelopeWrapper.ShouldMaterializeBody("references"))
                 AttachBodyExcerpts(reader, results, options.SnippetLines, options.MaxLineWidth);

src/CodeIndex/Database/DbReader.GraphIdentity.cs

@@ -220,6 +220,22 @@ private GraphQueryIdentityMetadata BuildGraphQueryIdentityMetadata(
             CandidatesTruncated: truncated);
     }
 
+    private string BuildReferenceRootSymbolIdsSql(string referenceAlias)
+    {
+        if (!_referenceIdentityContractCurrent)
+            return "NULL";
+
+        var targetSymbolIdSql = $"CAST({referenceAlias}.target_symbol_id AS TEXT)";
+        if (!HasTable("symbol_reference_candidates"))
+            return targetSymbolIdSql;
+
+        return $@"COALESCE((
+                    SELECT GROUP_CONCAT(identity_candidate.symbol_id)
+                    FROM symbol_reference_candidates AS identity_candidate
+                    WHERE identity_candidate.reference_id = {referenceAlias}.id
+                ), {targetSymbolIdSql})";
+    }
+
     private GraphQueryIdentityMetadata BuildSelectedGraphQueryIdentityMetadata(
         DefinitionResult selectedDefinition)
         => new(

src/CodeIndex/Database/DbReader.GraphQueries.cs

@@ -724,7 +724,7 @@ ELSE 5
     /// SQL 側で要求された LIMIT/OFFSET を適用し、呼び出し側が要求以上の中間ページを
     /// materialize しないようにする。
     /// </summary>
-    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)
+    private List<CallerResult> GetCallersExactCore(string symbolName, int limit, int offset, string? lang, IReadOnlyList<string>? pathPatterns, IReadOnlyList<string>? excludePathPatterns, bool excludeTests, IReadOnlyList<long>? targetSymbolIds, bool requireAuthoritativeIdentity, bool includeAmbiguousMSource, bool includeMemberReads)
     {
         if (!_hasReferencesTable) return new List<CallerResult>();
         using var cmd = _conn.CreateCommand();
@@ -744,12 +744,7 @@ private List<CallerResult> GetCallersExactCore(string symbolName, int limit, int
         var targetSymbolIdSql = hasIdentityTargetScope
             ? $@"CASE
                     WHEN r.resolution_state = 'resolved'
-                         AND EXISTS (
-                             SELECT 1
-                             FROM symbol_reference_candidates projected_identity_candidate
-                             WHERE projected_identity_candidate.reference_id = r.id
-                               AND projected_identity_candidate.symbol_id IN ({targetSymbolIdsSql})
-                         )
+                         AND r.target_symbol_id IN ({targetSymbolIdsSql})
                     THEN r.target_symbol_id
                     ELSE NULL
                 END"
@@ -783,19 +778,25 @@ ELSE NULL
                 ? "(r.symbol_name = @symbolName COLLATE NOCASE OR (f.lang = 'sql' AND r.symbol_name = sql_leaf_name(@symbolName) COLLATE NOCASE)" + polymorphicNameCondition + " OR (f.lang = 'solution' AND r.reference_kind = 'project_reference' AND r.container_name = @symbolName COLLATE NOCASE))"
                 : "(((f.lang = 'sql') AND sql_context_has_name_at(" + contextSql + @", @symbolName, r.column_number) = 1) OR ((f.lang != 'sql') AND r.symbol_name = @symbolName COLLATE NOCASE) OR " + BuildCSharpQualifiedContextFallbackSql(BuildQualifiedContextMatchSql(contextSql, "r.column_number", folded: false, like: false)) + " OR " + BuildQualifiedLeafFallbackSql("r.symbol_name", "r.symbol_name_folded", folded: false) + polymorphicNameCondition + " OR (f.lang = 'solution' AND r.reference_kind = 'project_reference' AND r.container_name = @symbolName COLLATE NOCASE))";
         var nameCondition = "\n              AND " + namePredicate;
-        // Identity-scoped traversal admits only references whose candidate set contains the
-        // requested canonical target. Unresolved/ambiguous same-leaf rows remain available to
-        // broad reference discovery, but they are not confirmed call-graph edges.
-        // identity scope の traversal は candidate set が要求 target を含む参照だけを採用する。
-        // unresolved/ambiguous な同名 leaf は広い reference 探索には残すが、確定 call graph edge
-        // としては扱わない。
-        var identityTargetPredicate = $@"EXISTS (
+        // Selector traversal admits only references authoritatively resolved to that target.
+        // Name-resolved roots, including a partial family that currently has one member, retain
+        // resolved-group evidence whose candidate set intersects the requested identities.
+        // Unresolved/ambiguous same-leaf rows remain available to broad reference discovery,
+        // but not as confirmed graph edges.
+        // selector traversal は対象へ確定解決された参照だけを採用する。現在の member が1件の
+        // partial family を含む name-resolved root は、candidate set が要求 identity と交差する
+        // resolved-group evidence を維持する。未解決・曖昧な同名 leaf は広い reference 探索には
+        // 残すが、確定 graph edge としては扱わない。
+        var candidateIdentityTargetPredicate = $@"EXISTS (
                   SELECT 1
                   FROM symbol_reference_candidates identity_candidate
                   WHERE identity_candidate.reference_id = r.id
                     AND identity_candidate.symbol_id IN ({targetSymbolIdsSql})
                     AND r.resolution_state IN ('resolved', 'resolved_group')
               )";
+        var identityTargetPredicate = requireAuthoritativeIdentity
+            ? $"(r.resolution_state = 'resolved' AND r.target_symbol_id IN ({targetSymbolIdsSql}))"
+            : candidateIdentityTargetPredicate;
         var targetCondition = !hasIdentityTargetContract
             ? nameCondition
             : targetSymbolIds!.Count == 0
@@ -962,8 +963,17 @@ public ImpactAnalysisResult AnalyzeImpact(string symbolName, int maxDepth = 5, i
         lang = NormalizeQueryLanguage(lang);
         var resolvedName = selectedDefinition?.Name ?? ResolveSymbolName(symbolName, lang);
         var definitionOffset = string.Equals(responseCollection, "definitions", StringComparison.Ordinal) ? offset : 0;
+        var selectedDefinitionMatchesFilters = selectedDefinition != null
+            && SelectedDefinitionMatchesImpactFilters(
+                selectedDefinition,
+                lang,
+                pathPatterns,
+                excludePathPatterns,
+                excludeTests);
         var definitionResolution = selectedDefinition != null
-            ? ResolveSelectedImpactDefinition(selectedDefinition)
+            ? selectedDefinitionMatchesFilters
+                ? ResolveSelectedImpactDefinition(selectedDefinition)
+                : EmptyImpactDefinitionResolution()
             : ResolveImpactDefinitions(symbolName, limit, lang, pathPatterns, excludePathPatterns, excludeTests, definitionOffset);
         if (selectedDefinition == null
             && definitionResolution.Definitions.Count == 0
@@ -1080,7 +1090,8 @@ public ImpactAnalysisResult AnalyzeImpact(string symbolName, int maxDepth = 5, i
             ? offset
             : 0;
         var (callers, truncated, truncatedReason, terminationReason, cycles) = selectedDefinition != null
-            ? GetTransitiveCallersForCandidate(
+            ? selectedDefinitionMatchesFilters
+                ? GetTransitiveCallersForCandidate(
                 selectedDefinition,
                 maxDepth,
                 limit,
@@ -1091,12 +1102,14 @@ public ImpactAnalysisResult AnalyzeImpact(string symbolName, int maxDepth = 5, i
                 withPaths,
                 callerOffset,
                 includeMemberReads)
+                : ([], false, null, ImpactTerminationReasons.Completed, [])
             : GetTransitiveCallers(symbolName, maxDepth, limit, lang, pathPatterns, excludePathPatterns, excludeTests, withPaths, resultOffset: callerOffset, includeMemberReads: includeMemberReads);
         var callerExistsBeforeOffset = false;
         if (callers.Count == 0 && callerOffset > 0)
         {
             var callerProbe = selectedDefinition != null
-                ? GetTransitiveCallersForCandidate(
+                ? selectedDefinitionMatchesFilters
+                    ? GetTransitiveCallersForCandidate(
                     selectedDefinition,
                     maxDepth,
                     1,
@@ -1107,6 +1120,7 @@ public ImpactAnalysisResult AnalyzeImpact(string symbolName, int maxDepth = 5, i
                     withPaths: false,
                     resultOffset: 0,
                     includeMemberReads)
+                    : ([], false, null, ImpactTerminationReasons.Completed, [])
                 : GetTransitiveCallers(symbolName, maxDepth, 1, lang, pathPatterns, excludePathPatterns, excludeTests, withPaths: false, resultOffset: 0, includeMemberReads: includeMemberReads);
             callerExistsBeforeOffset = callerProbe.Results.Count > 0;
         }

src/CodeIndex/Database/DbReader.GraphReferenceQueries.cs

@@ -327,7 +327,7 @@ private string BuildCallerListSql(
         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 referenceSpanLengthSql = _referenceColumns.Contains("span_length") ? "r.span_length" : "NULL";
-        var rootSymbolIdSql = _referenceIdentityContractCurrent ? "r.target_symbol_id" : "NULL";
+        var rootSymbolIdSql = BuildReferenceRootSymbolIdsSql("r");
         var sql = @"
             WITH logical_references AS (
                 SELECT f.path, f.lang, r.container_kind, r.container_name, r.symbol_name,
@@ -536,6 +536,13 @@ private string BuildCalleeQualifiedNameFilterSql(GraphReferenceQueryRequest requ
 
     private string BuildCallerIdentityFilterSql(GraphReferenceQueryRequest request)
     {
+        if (request.IdentitySymbolId != null)
+        {
+            return _referenceIdentityContractCurrent
+                ? " AND r.target_symbol_id = @targetSymbolId"
+                : " AND 1 = 0";
+        }
+
         if (request.CallerIdentitySymbolIds == null || !HasTable("symbol_reference_candidates"))
             return string.Empty;
 
@@ -634,7 +641,11 @@ private void BindGraphReferenceQueryPlan(SqliteCommand command, GraphReferenceQu
         }
         if (plan.BindIdentityParameter)
         {
-            if (request.CallerIdentitySymbolIds != null)
+            if (request.IdentitySymbolId != null)
+            {
+                SqliteCommandPolicy.Add(command, plan.Direction.IdentityParameterName, request.IdentitySymbolId.Value);
+            }
+            else if (request.CallerIdentitySymbolIds != null)
             {
                 var symbolIdValues = request.CallerIdentitySymbolIds
                     .Select(static symbolId => symbolId.ToString(System.Globalization.CultureInfo.InvariantCulture))
@@ -644,10 +655,6 @@ private void BindGraphReferenceQueryPlan(SqliteCommand command, GraphReferenceQu
                     "@callerTargetSymbolIdsJson",
                     JsonStringListCodec.Serialize(symbolIdValues));
             }
-            else
-            {
-                SqliteCommandPolicy.Add(command, plan.Direction.IdentityParameterName, request.IdentitySymbolId!.Value);
-            }
         }
         AddPathFilterParameters(command, request.PathPatterns, request.ExcludePathPatterns);
         if (plan.Shape != GraphReferenceQueryShape.TotalCount)

src/CodeIndex/Database/DbReader.ImpactDefinitions.cs

@@ -108,6 +108,7 @@ private static ImpactDefinitionResolution ResolveSelectedImpactDefinition(
         DefinitionResult definition)
     {
         var precise = IsPreciseImpactFallbackKind(definition.Kind);
+        var nonCallable = definition.Kind is "namespace" or "import";
         var symbolIds = definition.SymbolId is long symbolId
             ? new HashSet<long> { symbolId }
             : [];
@@ -119,10 +120,45 @@ private static ImpactDefinitionResolution ResolveSelectedImpactDefinition(
             PreciseDefinitionCount: precise ? 1 : 0,
             PreciseLogicalDefinitionCount: precise ? 1 : 0,
             PreciseDefinitionFileCount: precise ? 1 : 0,
-            NonCallableDefinitionCount: precise ? 1 : 0,
+            NonCallableDefinitionCount: nonCallable ? 1 : 0,
             SinglePreciseDefinition: precise ? definition : null,
             PhysicalSymbolIds: symbolIds,
             PhysicalDefinitionPaths: new HashSet<string>(StringComparer.Ordinal) { definition.Path },
             PhysicalSymbolIdsTruncated: false);
     }
+
+    private static ImpactDefinitionResolution EmptyImpactDefinitionResolution()
+        => new(
+            [],
+            PhysicalCount: 0,
+            PhysicalFileCount: 0,
+            LogicalCount: 0,
+            PreciseDefinitionCount: 0,
+            PreciseLogicalDefinitionCount: 0,
+            PreciseDefinitionFileCount: 0,
+            NonCallableDefinitionCount: 0,
+            SinglePreciseDefinition: null,
+            PhysicalSymbolIds: [],
+            PhysicalDefinitionPaths: [],
+            PhysicalSymbolIdsTruncated: false);
+
+    private bool SelectedDefinitionMatchesImpactFilters(
+        DefinitionResult definition,
+        string? lang,
+        IReadOnlyList<string>? pathPatterns,
+        IReadOnlyList<string>? excludePathPatterns,
+        bool excludeTests)
+    {
+        if (lang != null && !string.Equals(definition.Lang, lang, StringComparison.Ordinal))
+            return false;
+
+        using var command = _conn.CreateCommand();
+        var sql = "SELECT 1 FROM files f WHERE f.path = @selectedDefinitionPath";
+        AppendPathFilters(ref sql, pathPatterns, excludePathPatterns, excludeTests);
+        sql += " LIMIT 1";
+        command.CommandText = sql;
+        SqliteCommandPolicy.Add(command, "@selectedDefinitionPath", definition.Path);
+        AddPathFilterParameters(command, pathPatterns, excludePathPatterns);
+        return command.ExecuteScalar() != null;
+    }
 }

src/CodeIndex/Database/DbReader.ImpactTraversal.cs

@@ -406,8 +406,9 @@ private List<CallerResult> ReadImpactCallerPage(
             request.ExcludePathPatterns,
             request.ExcludeTests,
             targetIds,
-            includeAmbiguousMSource,
-            request.IncludeMemberReads);
+            requireAuthoritativeIdentity: request.SelectedDefinition != null,
+            includeAmbiguousMSource: includeAmbiguousMSource,
+            includeMemberReads: request.IncludeMemberReads);
     }
 
     private int GetImpactGraphStateEntryBudget(int limit)