@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/analysis/target/identity.ts

@@ -0,0 +1,237 @@
+import { resolve } from "node:path";
+import type { CodeSymbol, StructuralProvider } from "@mrclrchtr/supi-code-runtime/api";
+import type { ResolvedTargetData, TargetOutcome } from "./types.ts";
+
+/**
+ * Normalize provider-specific declaration kinds into stable identity families.
+ * Display kinds remain untouched; this value is used only for matching and
+ * target-handle identity across semantic/structural observations.
+ */
+export function canonicalDeclarationKind(kind: string | null): string {
+  const normalized = (kind ?? "").toLowerCase();
+  if (
+    ["function", "variable", "constant", "field", "field-function", "property"].includes(normalized)
+  ) {
+    return "value";
+  }
+  if (["method", "constructor"].includes(normalized)) return "member";
+  return normalized;
+}
+
+/** Exact declaration-name observation used to derive provider-independent identity. */
+export interface DeclarationIdentityObservation {
+  readonly file: string;
+  readonly name: string | null;
+  readonly providerKind: string | null;
+  readonly nameAnchor: { readonly line: number; readonly character: number } | null;
+}
+
+/** Evidence-backed canonical kind and whether structural syntax established it. */
+export interface DeclarationIdentityResult {
+  readonly identityKind: string;
+  readonly structuralEvidence: boolean;
+}
+
+/** Canonical identity plus the same-line occurrence used by Target handles. */
+export interface DeclarationOccurrenceIdentity extends DeclarationIdentityResult {
+  readonly declarationOccurrence: number;
+}
+
+/**
+ * Resolve an identity kind without rewriting the provider-reported display kind.
+ * An LSP `Variable` becomes `type` only when Tree-sitter reports the exact name
+ * anchor inside a type-alias declaration.
+ */
+export async function resolveDeclarationIdentityKind(
+  observation: DeclarationIdentityObservation,
+  structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+): Promise<DeclarationIdentityResult> {
+  const identityKind = canonicalDeclarationKind(observation.providerKind);
+  if (
+    !structural ||
+    observation.providerKind?.toLowerCase() !== "variable" ||
+    !observation.nameAnchor
+  ) {
+    return { identityKind, structuralEvidence: false };
+  }
+  try {
+    const { line, character } = observation.nameAnchor;
+    const result = await structural.nodeAt(observation.file, line, character);
+    if (result.kind !== "success") return { identityKind, structuralEvidence: false };
+    const node = result.data;
+    const exactNameAnchor =
+      node.text === observation.name &&
+      node.startLine === line &&
+      node.startCharacter === character;
+    const isTypeAlias =
+      node.type === "type_identifier" &&
+      node.ancestry.some((ancestor) => ancestor.type === "type_alias_declaration");
+    return exactNameAnchor && isTypeAlias
+      ? { identityKind: "type", structuralEvidence: true }
+      : { identityKind, structuralEvidence: false };
+  } catch {
+    return { identityKind, structuralEvidence: false };
+  }
+}
+
+/**
+ * Build an evidence-backed identity resolver for one semantic declaration set.
+ * Results are cached so disambiguation candidates share structural observations.
+ */
+export function createCodeSymbolIdentityResolver(
+  file: string,
+  allSymbols: readonly CodeSymbol[],
+  structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+): (symbol: CodeSymbol) => Promise<DeclarationOccurrenceIdentity> {
+  const identities = new Map<CodeSymbol, Promise<DeclarationIdentityResult>>();
+  const occurrences = new Map<CodeSymbol, Promise<DeclarationOccurrenceIdentity>>();
+
+  const resolveIdentity = (symbol: CodeSymbol): Promise<DeclarationIdentityResult> => {
+    const existing = identities.get(symbol);
+    if (existing) return existing;
+    const identity = resolveDeclarationIdentityKind(
+      {
+        file,
+        name: symbol.name,
+        providerKind: symbol.kind,
+        nameAnchor: symbol.nameAnchor ?? null,
+      },
+      structural,
+    );
+    identities.set(symbol, identity);
+    return identity;
+  };
+
+  return (symbol) => {
+    const existing = occurrences.get(symbol);
+    if (existing) return existing;
+    const occurrence = resolveCodeSymbolOccurrence(symbol, allSymbols, resolveIdentity);
+    occurrences.set(symbol, occurrence);
+    return occurrence;
+  };
+}
+
+async function resolveCodeSymbolOccurrence(
+  symbol: CodeSymbol,
+  allSymbols: readonly CodeSymbol[],
+  resolveIdentity: (symbol: CodeSymbol) => Promise<DeclarationIdentityResult>,
+): Promise<DeclarationOccurrenceIdentity> {
+  const peers = allSymbols.filter(
+    (candidate) =>
+      candidate.name === symbol.name &&
+      (candidate.container ?? null) === (symbol.container ?? null) &&
+      candidate.declarationAnchor.line === symbol.declarationAnchor.line,
+  );
+  const observed = await Promise.all(
+    peers.map(async (candidate) => ({ candidate, identity: await resolveIdentity(candidate) })),
+  );
+  const selectedIdentity = await resolveIdentity(symbol);
+  const matching = observed
+    .filter(({ identity }) => identity.identityKind === selectedIdentity.identityKind)
+    .map(({ candidate }) => candidate)
+    .sort(compareCodeSymbolDeclarations);
+  return {
+    ...selectedIdentity,
+    declarationOccurrence: Math.max(0, matching.indexOf(symbol)),
+  };
+}
+
+function compareCodeSymbolDeclarations(left: CodeSymbol, right: CodeSymbol): number {
+  return (
+    left.declarationAnchor.character - right.declarationAnchor.character ||
+    (left.nameAnchor?.character ?? 0) - (right.nameAnchor?.character ?? 0)
+  );
+}
+
+/** Refine one semantic target with exact structural type-alias evidence. */
+export async function refineTypeAliasIdentity(
+  target: ResolvedTargetData,
+  structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+): Promise<ResolvedTargetData> {
+  if (target.identityKind !== undefined) return target;
+  const identity = await resolveDeclarationIdentityKind(
+    {
+      file: target.file,
+      name: target.name,
+      providerKind: target.kind,
+      nameAnchor:
+        target.anchorKind === "name"
+          ? { line: target.displayLine, character: target.displayCharacter }
+          : null,
+    },
+    structural,
+  );
+  return {
+    ...target,
+    identityKind: identity.identityKind,
+    provenance: identity.structuralEvidence ? ["semantic", "structural"] : target.provenance,
+  };
+}
+
+/** Refine resolved and candidate identities before Target-handle registration. */
+export async function refineTargetOutcomeIdentity(
+  outcome: TargetOutcome,
+  cwd: string,
+  structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+): Promise<TargetOutcome> {
+  if (outcome.kind === "resolved") {
+    return { kind: "resolved", target: await refineTypeAliasIdentity(outcome.target, structural) };
+  }
+  if (outcome.kind !== "disambiguation" && outcome.kind !== "kind-mismatch") return outcome;
+
+  const observations = await Promise.all(
+    outcome.candidates.map(async (candidate) => {
+      if (candidate.identityKind !== undefined) {
+        return { candidate, identityRefined: false };
+      }
+      const identity = await resolveDeclarationIdentityKind(
+        {
+          file: resolve(cwd, candidate.file),
+          name: candidate.name,
+          providerKind: candidate.kind,
+          nameAnchor:
+            candidate.anchorKind === "name"
+              ? { line: candidate.line, character: candidate.character }
+              : null,
+        },
+        structural,
+      );
+      return {
+        candidate: {
+          ...candidate,
+          identityKind: identity.identityKind,
+          provenance: identity.structuralEvidence
+            ? (["semantic", "structural"] as const)
+            : (["semantic"] as const),
+        },
+        identityRefined: true,
+      };
+    }),
+  );
+  const candidates = observations.map(({ candidate }) => candidate);
+  return {
+    ...outcome,
+    candidates: observations.some(({ identityRefined }) => identityRefined)
+      ? assignCandidateOccurrences(candidates, cwd)
+      : candidates,
+  };
+}
+
+function assignCandidateOccurrences(
+  candidates: Extract<TargetOutcome, { kind: "disambiguation" | "kind-mismatch" }>["candidates"],
+  cwd: string,
+): Extract<TargetOutcome, { kind: "disambiguation" | "kind-mismatch" }>["candidates"] {
+  const occurrences = new Map<string, number>();
+  return candidates.map((candidate) => {
+    const key = [
+      resolve(cwd, candidate.file),
+      candidate.declarationAnchor.line,
+      candidate.name,
+      candidate.identityKind ?? canonicalDeclarationKind(candidate.kind),
+      candidate.container ?? "",
+    ].join("\0");
+    const declarationOccurrence = occurrences.get(key) ?? 0;
+    occurrences.set(key, declarationOccurrence + 1);
+    return { ...candidate, declarationOccurrence };
+  });
+}

package/src/analysis/target/symbol.ts

@@ -1,6 +1,6 @@
 /**
  * Symbol target resolution — discovers symbols via the semantic substrate
- * and returns typed outcomes (resolved, disambiguation, or error).
+ * and returns typed outcomes (resolved, disambiguation, kind mismatch, or error).
  *
  * This resolver is semantic-only: it does not fall back to text search
  * or heuristic guessing. Ambiguous matches produce explicit disambiguation.
@@ -12,8 +12,9 @@ import type {
   SemanticProvider as SemanticSubstrate,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
+import type { TargetSymbolKind } from "../../session/target-input.ts";
 import type { AnchorKind } from "../../session/target-store.ts";
-import { normalizePath } from "../search/ripgrep.ts";
+import { normalizePath } from "../search/paths.ts";
 import type { DisambiguationCandidateData, TargetOutcome } from "./types.ts";
 
 const MAX_CANDIDATES = 8; // default fallback when maxResults is not provided
@@ -31,6 +32,13 @@ function isExactDocumentSymbolMatch(candidate: CodeSymbol, workspaceSymbol: Code
   );
 }
 
+function hasSameDeclarationAnchor(candidate: CodeSymbol, workspaceSymbol: CodeSymbol): boolean {
+  return (
+    candidate.declarationAnchor.line === workspaceSymbol.declarationAnchor.line &&
+    candidate.declarationAnchor.character === workspaceSymbol.declarationAnchor.character
+  );
+}
+
 /**
  * The preferred anchor for resolution/downstream: the name (identifier) anchor
  * when the provider derived it, else the declaration anchor. Strict consumers
@@ -53,19 +61,23 @@ async function refineResolvedSymbolAnchor(
   semantic: SemanticSubstrate,
 ): Promise<CodeSymbol> {
   try {
-    const documentSymbols = await semantic.documentSymbols(workspaceSymbol.file);
-    if (!documentSymbols || documentSymbols.length === 0) {
-      return workspaceSymbol;
-    }
+    const result = await semantic.documentSymbols(workspaceSymbol.file);
+    if (result.kind === "unavailable" || result.data.length === 0) return workspaceSymbol;
 
-    const exactMatches = documentSymbols.filter((candidate) =>
+    const exactMatches = result.data.filter((candidate) =>
       isExactDocumentSymbolMatch(candidate, workspaceSymbol),
     );
-    if (exactMatches.length !== 1) {
-      return workspaceSymbol;
-    }
+    const declarationMatches = exactMatches.filter((candidate) =>
+      hasSameDeclarationAnchor(candidate, workspaceSymbol),
+    );
+    const refined =
+      declarationMatches.length === 1
+        ? declarationMatches[0]
+        : exactMatches.length === 1
+          ? exactMatches[0]
+          : undefined;
+    if (!refined) return workspaceSymbol;
 
-    const refined = exactMatches[0];
     const a = anchorOf(refined);
     if (a.line <= 0 && a.character <= 0) {
       return workspaceSymbol;
@@ -84,7 +96,7 @@ async function refineResolvedSymbolAnchor(
  * @param cwd - session working directory
  * @param semantic - the semantic substrate (LSP-backed)
  * @param options - optional filters: path scope, kind filter, exported-only
- * @returns Typed outcome: resolved, disambiguation, or error
+ * @returns Typed outcome: resolved, disambiguation, kind mismatch, or error
  */
 export async function resolveSymbolTarget(
   symbol: string,
@@ -92,105 +104,176 @@ export async function resolveSymbolTarget(
   semantic: SemanticSubstrate,
   options?: {
     path?: string;
-    kind?: string;
+    kind?: TargetSymbolKind;
     exportedOnly?: boolean;
     maxResults?: number;
   },
 ): Promise<TargetOutcome> {
-  const results = await semantic.workspaceSymbols(symbol);
-  if (results === null) {
+  const result = await semantic.workspaceSymbols(symbol);
+  if (result.kind === "unavailable") {
     return {
       kind: "error",
-      message: `Symbol discovery for \`${symbol}\` requires active LSP. Use \`file\` + coordinates, or enable LSP and retry.`,
+      message: `Symbol discovery for \`${symbol}\` is unavailable: ${result.reason}`,
     };
   }
-  if (results.length === 0) {
+  if (result.data.length === 0) {
     return { kind: "error", message: `Symbol not found: \`${symbol}\`` };
   }
 
-  // Filter by path scope. Tool paths may include pi's leading `@` prefix;
-  // normalize through the shared path helper so every caller gets the same
-  // scope semantics.
   const scopePath = options?.path ? normalizePath(options.path, cwd) : null;
-  let candidates = results.filter((s) => {
-    if (scopePath && !isWithinOrEqual(scopePath, s.file)) return false;
-    return true;
-  });
-
-  // Filter by kind
-  if (options?.kind) {
-    const kindLower = options.kind.toLowerCase();
-    candidates = candidates.filter((s) => s.kind.toLowerCase().includes(kindLower));
+  const scoped = result.data.filter((candidate) =>
+    scopePath ? isWithinOrEqual(scopePath, candidate.file) : true,
+  );
+  const eligible = options?.exportedOnly
+    ? scoped.filter((candidate) => !NON_EXPORTED_KINDS.has(candidate.kind))
+    : scoped;
+  if (eligible.length === 0) {
+    return {
+      kind: "error",
+      message: `Symbol not found: \`${symbol}\`${scopePath ? ` in path \`${options?.path}\`` : ""}`,
+    };
   }
 
-  // Filter to exported symbols only
-  if (options?.exportedOnly) {
-    candidates = candidates.filter((s) => !NON_EXPORTED_KINDS.has(s.kind));
+  const requestedKind = options?.kind;
+  if (requestedKind) {
+    const exactKind = eligible.filter((candidate) =>
+      providerKindMatches(candidate.kind, requestedKind),
+    );
+    if (exactKind.length === 0) {
+      return buildCandidateOutcome({
+        kind: "kind-mismatch",
+        candidates: eligible,
+        semantic,
+        cwd,
+        maxResults: options.maxResults,
+        requestedKind,
+      });
+    }
+    return resolveCandidates(exactKind, semantic, cwd, options.maxResults);
   }
 
-  // Range-less candidates (line=0,char=0) come from URI-only workspace symbols.
-  // Keep them for disambiguation but don't promote to single-match resolution.
+  return resolveCandidates(eligible, semantic, cwd, options?.maxResults);
+}
+
+function providerKindMatches(reported: string, requested: TargetSymbolKind): boolean {
+  return normalizeProviderKind(reported) === normalizeProviderKind(requested);
+}
+
+function normalizeProviderKind(kind: string): string {
+  return kind.replace(/[\s_-]/g, "").toLowerCase();
+}
+
+async function resolveCandidates(
+  candidates: readonly CodeSymbol[],
+  semantic: SemanticSubstrate,
+  cwd: string,
+  maxResults?: number,
+): Promise<TargetOutcome> {
   const ranged = candidates.filter(
-    (s) => s.declarationAnchor.line > 0 || s.declarationAnchor.character > 0,
+    (candidate) =>
+      candidate.declarationAnchor.line > 0 || candidate.declarationAnchor.character > 0,
   );
-
   if (ranged.length === 1) {
-    const c = await refineResolvedSymbolAnchor(ranged[0], semantic);
-    const a = anchorOf(c);
-    return {
-      kind: "resolved",
-      target: {
-        file: c.file,
-        position: { line: a.line - 1, character: a.character - 1 },
-        displayLine: a.line,
-        displayCharacter: a.character,
-        name: c.name,
-        kind: c.kind,
-        confidence: "semantic",
-        anchorKind: (c.nameAnchor ? "name" : "declaration") as AnchorKind,
-        container: c.container ?? null,
-      },
-    };
+    return resolvedTarget(await refineResolvedSymbolAnchor(ranged[0], semantic));
   }
+  return buildCandidateOutcome({
+    kind: "disambiguation",
+    candidates,
+    semantic,
+    cwd,
+    maxResults,
+  });
+}
 
-  // All candidates lost or only rangeless
-  if (candidates.length === 0) {
-    return {
-      kind: "error",
-      message: `Symbol not found: \`${symbol}\`${scopePath ? ` in path \`${options?.path}\`` : ""}`,
-    };
-  }
+function resolvedTarget(candidate: CodeSymbol): TargetOutcome {
+  const anchor = anchorOf(candidate);
+  return {
+    kind: "resolved",
+    target: {
+      file: candidate.file,
+      position: { line: anchor.line - 1, character: anchor.character - 1 },
+      displayLine: anchor.line,
+      displayCharacter: anchor.character,
+      declarationAnchor: { ...candidate.declarationAnchor },
+      declarationOccurrence: 0,
+      name: candidate.name,
+      kind: candidate.kind,
+      confidence: "semantic",
+      provenance: ["semantic"],
+      anchorKind: (candidate.nameAnchor ? "name" : "declaration") as AnchorKind,
+      container: candidate.container ?? null,
+    },
+  };
+}
+
+interface CandidateOutcomeBase {
+  candidates: readonly CodeSymbol[];
+  semantic: SemanticSubstrate;
+  cwd: string;
+  maxResults?: number;
+}
+
+type CandidateOutcomeOptions = CandidateOutcomeBase &
+  (
+    | { kind: "disambiguation"; requestedKind?: never }
+    | { kind: "kind-mismatch"; requestedKind: TargetSymbolKind }
+  );
 
-  // Multiple candidates — refine each to a name (identifier) anchor before
-  // returning disambiguation, so position-strict downstream substrates
-  // (tree-sitter calleesAt, LSP rename) receive the identifier anchor rather
-  // than the declaration anchor (the `export` keyword) that workspace-symbol
-  // hits carry. Mirrors the single-match refine path above.
-  // Per ADR 0003, `anchorOf` prefers the refined doc symbol's `nameAnchor`.
-  // TODO: batch the per-file documentSymbols dedupe across candidates.
-  const cap = options?.maxResults ?? MAX_CANDIDATES;
+/**
+ * Refine only bounded visible candidates to name anchors while retaining the
+ * exact provider result count for omission disclosure. No candidate is
+ * promoted when the requested provider kind did not match.
+ */
+async function buildCandidateOutcome(
+  options: CandidateOutcomeOptions,
+): Promise<Extract<TargetOutcome, { kind: "disambiguation" | "kind-mismatch" }>> {
+  const cap = options.maxResults ?? MAX_CANDIDATES;
   const refined = await Promise.all(
-    candidates.slice(0, cap).map((c) => refineResolvedSymbolAnchor(c, semantic)),
+    options.candidates
+      .slice(0, cap)
+      .map((candidate) => refineResolvedSymbolAnchor(candidate, options.semantic)),
   );
-  const candidatesOut = refined.map((c, idx) => {
-    const relFile = path.relative(cwd, c.file);
-    const a = anchorOf(c);
+  const common = {
+    candidates: toDisambiguationCandidates(refined, options.cwd),
+    omittedCount: Math.max(0, options.candidates.length - cap),
+  };
+  return options.kind === "kind-mismatch"
+    ? {
+        kind: options.kind,
+        requestedKind: options.requestedKind,
+        ...common,
+      }
+    : { kind: options.kind, ...common };
+}
+
+function toDisambiguationCandidates(
+  candidates: readonly CodeSymbol[],
+  cwd: string,
+): DisambiguationCandidateData[] {
+  const occurrences = new Map<string, number>();
+  return candidates.map((candidate, index) => {
+    const relFile = path.relative(cwd, candidate.file);
+    const anchor = anchorOf(candidate);
+    const occurrenceKey = [
+      relFile,
+      candidate.declarationAnchor.line,
+      candidate.name,
+      candidate.kind,
+      candidate.container ?? "",
+    ].join("\0");
+    const declarationOccurrence = occurrences.get(occurrenceKey) ?? 0;
+    occurrences.set(occurrenceKey, declarationOccurrence + 1);
     return {
-      name: c.name,
-      kind: c.kind,
-      container: c.container ?? null,
+      name: candidate.name,
+      kind: candidate.kind,
+      container: candidate.container ?? null,
       file: relFile,
-      line: a.line,
-      character: a.character,
-      reason: relFile,
-      rank: idx + 1,
-      anchorKind: (c.nameAnchor ? "name" : "declaration") as AnchorKind,
+      line: anchor.line,
+      character: anchor.character,
+      declarationAnchor: { ...candidate.declarationAnchor },
+      declarationOccurrence,
+      rank: index + 1,
+      anchorKind: (candidate.nameAnchor ? "name" : "declaration") as AnchorKind,
     };
-  }) satisfies DisambiguationCandidateData[];
-
-  return {
-    kind: "disambiguation",
-    candidates: candidatesOut,
-    omittedCount: Math.max(0, candidates.length - cap),
-  };
+  });
 }

package/src/analysis/target/types.ts

@@ -10,7 +10,10 @@ import type {
   SemanticProvider as SemanticSubstrate,
   StructuralProvider as StructuralSubstrate,
 } from "@mrclrchtr/supi-code-runtime/api";
-import type { AnchorKind } from "../../session/target-store.ts";
+import type { TargetSymbolKind } from "../../session/target-input.ts";
+import type { AnchorKind, TargetProviderProvenance } from "../../session/target-store.ts";
+
+export type { TargetProviderProvenance } from "../../session/target-store.ts";
 
 // ── Normalized query ──────────────────────────────────────────────────
 
@@ -69,12 +72,23 @@ export interface ResolvedTargetData {
   /** 1-based position for user display */
   displayLine: number;
   displayCharacter: number;
+  /**
+   * Stable 1-based declaration occurrence used for target identity. Unlike
+   * the preferred display anchor, this does not move during name refinement.
+   */
+  declarationAnchor: { line: number; character: number };
+  /** Zero-based occurrence among otherwise-identical declarations on that line. */
+  declarationOccurrence: number;
   name: string | null;
   kind: string | null;
+  /** Evidence-backed provider-independent kind used for matching and handle identity. */
+  identityKind?: string;
   confidence: "semantic" | "structural" | "heuristic" | "unavailable";
+  /** Provider families that established this declaration, strongest first. */
+  provenance: readonly TargetProviderProvenance[];
   /** Which anchor this target carries — drives strict-consumer enforcement (ADR 0003). */
   anchorKind: AnchorKind;
-  /** Symbolic container (class/namespace/module name), or null for top-level. */
+  /** Named symbolic container, or null when no container name was reported. */
   container: string | null;
   /**
    * Resolution provenance — present when the target was resolved from
@@ -85,13 +99,18 @@ export interface ResolvedTargetData {
 }
 
 /**
- * A file-level target group with one or more discoverable targets.
+ * A file-derived Target group with zero or more evidence-backed declarations.
  */
 export interface ResolvedTargetGroupData {
   file: string;
   displayName: string;
   targets: ResolvedTargetData[];
+  /** Providers that successfully enumerated the selected file. */
+  discoveryProvenance: readonly TargetProviderProvenance[];
+  /** Conservative confidence across the complete group, before display capping. */
   confidence: "semantic" | "structural" | "heuristic" | "unavailable";
+  /** Complete-group declarations whose provider observations could not establish hierarchy. */
+  unknownNestingCount: number;
 }
 
 /**
@@ -100,11 +119,18 @@ export interface ResolvedTargetGroupData {
 export interface DisambiguationCandidateData {
   name: string;
   kind: string | null;
+  /** Evidence-backed provider-independent kind used for handle identity. */
+  identityKind?: string;
+  /** Provider families that established this candidate declaration. */
+  provenance?: readonly TargetProviderProvenance[];
   container: string | null;
   file: string;
   line: number;
   character: number;
-  reason: string;
+  /** Stable 1-based declaration occurrence for target identity. */
+  declarationAnchor: { line: number; character: number };
+  /** Zero-based occurrence among otherwise-identical declarations on that line. */
+  declarationOccurrence: number;
   rank: number;
   /** Which anchor this candidate carries (ADR 0003). */
   anchorKind: AnchorKind;
@@ -124,4 +150,10 @@ export type TargetOutcome =
       candidates: DisambiguationCandidateData[];
       omittedCount: number;
     }
+  | {
+      kind: "kind-mismatch";
+      requestedKind: TargetSymbolKind;
+      candidates: DisambiguationCandidateData[];
+      omittedCount: number;
+    }
   | { kind: "error"; message: string };