@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/session/target-input.ts

@@ -0,0 +1,98 @@
+/** Canonical target values accepted by the Workspace code-intelligence session. */
+
+/** A 1-based source point supplied by a public code-intelligence tool. */
+export interface SourcePointInput {
+  readonly file: string;
+  readonly line: number;
+  readonly character: number;
+}
+
+/** Exact LSP SymbolKind vocabulary accepted by semantic target discovery. */
+export const TARGET_SYMBOL_KINDS = [
+  "file",
+  "module",
+  "namespace",
+  "package",
+  "class",
+  "method",
+  "property",
+  "field",
+  "constructor",
+  "enum",
+  "interface",
+  "function",
+  "variable",
+  "constant",
+  "string",
+  "number",
+  "boolean",
+  "array",
+  "object",
+  "key",
+  "null",
+  "enumMember",
+  "struct",
+  "event",
+  "operator",
+  "typeParameter",
+] as const;
+
+/** Provider-reported symbol kind used as a strict semantic filter. */
+export type TargetSymbolKind = (typeof TARGET_SYMBOL_KINDS)[number];
+
+/** A semantic symbol query and its optional workspace-relative scope. */
+export interface SymbolTargetInput {
+  readonly query: string;
+  readonly scope?: string;
+  readonly symbolKind?: TargetSymbolKind;
+}
+
+/** Session-scoped target handle returned by code_resolve. */
+export interface HandleTargetInput {
+  readonly handle: string;
+}
+
+/** Provider-backed source anchor. */
+export interface AnchorTargetInput {
+  readonly anchor: SourcePointInput;
+}
+
+/** Semantic symbol selector. */
+export interface SymbolTargetSelectorInput {
+  readonly symbol: SymbolTargetInput;
+}
+
+/** File-level selector. */
+export interface FileTargetInput {
+  readonly file: string;
+}
+
+/** Canonical exact-one target selector. */
+export type TargetInput =
+  | HandleTargetInput
+  | AnchorTargetInput
+  | SymbolTargetSelectorInput
+  | FileTargetInput;
+
+/** Target variants accepted by code_resolve. */
+export type ResolveTargetInput = AnchorTargetInput | SymbolTargetSelectorInput | FileTargetInput;
+
+/** Target variants accepted by code_graph. */
+export type GraphTargetInput = HandleTargetInput | AnchorTargetInput | SymbolTargetSelectorInput;
+
+/** Target variants accepted by precise Orientation focus. */
+export type OrientationTargetInput =
+  | HandleTargetInput
+  | AnchorTargetInput
+  | SymbolTargetSelectorInput;
+
+/** Target variants accepted by code_refactor_plan. */
+export type RefactorTargetInput = HandleTargetInput | AnchorTargetInput;
+
+/** Return the selected target branch. Public schemas guarantee exactly one branch. */
+export function targetInputKind(input: TargetInput): "handle" | "anchor" | "symbol" | "file" {
+  if ("handle" in input) return "handle";
+  if ("anchor" in input) return "anchor";
+  if ("symbol" in input) return "symbol";
+  return "file";
+}

package/src/session/target-store.ts

@@ -25,6 +25,9 @@ import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
  */
 export type AnchorKind = "name" | "declaration";
 
+/** Provider families that contributed evidence to one resolved target. */
+export type TargetProviderProvenance = "semantic" | "structural";
+
 /**
  * A stored resolved target entry with handles and metadata.
  *
@@ -39,17 +42,21 @@ export interface TargetStoreEntry {
   file: string;
   /** 0-based position for LSP calls. */
   position: { line: number; character: number };
+  /** Stable 0-based declaration occurrence used to distinguish overloads. */
+  declarationPosition?: { line: number; character: number } | null;
+  declarationOccurrence?: number;
   /** 1-based position for user display. */
   displayLine: number;
   displayCharacter: number;
   name: string | null;
   kind: string | null;
   confidence: ConfidenceMode;
-  provenance: string;
+  /** Monotonic provider families that established this target. */
+  provenance: readonly TargetProviderProvenance[];
   /** Which anchor this target carries — drives strict-consumer enforcement (ADR 0003). */
   anchorKind: AnchorKind;
   fileFingerprint: string;
-  /** 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
@@ -63,15 +70,26 @@ export interface TargetStoreEntry {
 export interface TargetRegistrationInput {
   file: string;
   position: { line: number; character: number };
+  /**
+   * Stable 0-based declaration occurrence. Provider-backed registrations
+   * supply this so overloads remain distinct while name refinement retains
+   * the same target identity.
+   */
+  declarationPosition?: { line: number; character: number };
+  /** Zero-based occurrence among matching declarations on the same line. */
+  declarationOccurrence?: number;
   displayLine: number;
   displayCharacter: number;
   name: string | null;
   kind: string | null;
+  /** Provider-independent declaration kind used only for stable identity. */
+  identityKind?: string;
   confidence: ConfidenceMode;
-  provenance: string;
+  /** Provider families observed by this registration. */
+  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 (ADR 0003 — disambiguates same-file collisions in the identity hash). */
+  /** Named symbolic container used to disambiguate same-file identity collisions, or null when unreported (ADR 0003). */
   container: string | null;
   /**
    * Resolution provenance — present when the target was resolved from
@@ -79,6 +97,8 @@ export interface TargetRegistrationInput {
    * the anchor was snapped, and the provider-backed evidence source.
    */
   resolution?: import("../types/index.ts").AnchoredResolutionMetadata;
+  /** Reuse one verified fingerprint across a bounded registration batch. */
+  fileFingerprint?: string;
 }
 
 /** Output from registering a target: stable session-scoped handles and the full stored entry. */
@@ -125,19 +145,20 @@ export function computeFileFingerprint(
 /**
  * Build a deterministic target handle from target identity fields.
  *
- * Per ADR 0003, position is intentionally excluded from symbol identity:
- * nameAnchor is best-effort, so the same symbol can resolve to a name
- * anchor or fall back to the declaration anchor across calls; including
- * position would break the "re-resolve reuses the same IDs" invariant.
- * Identity is cwd, file path, name, kind, container, and fingerprint.
+ * Per ADR 0003, the preferred display/name-anchor position is excluded from
+ * symbol identity because it may refine. Identity uses cwd, file path, name,
+ * canonical provider-independent kind, container, stable declaration line and
+ * same-line occurrence, and fingerprint. The occurrence keeps overloads
+ * distinct without coupling identity to provider-specific declaration columns.
  */
 function computeTargetId(opts: {
   cwd: string;
   file: string;
-  position: { line: number; character: number };
   name: string | null;
-  kind: string | null;
+  identityKind: string;
   container: string | null;
+  declarationPosition: { line: number; character: number } | null;
+  declarationOccurrence: number;
   fingerprint: string;
 }): string {
   const hash = createHash("sha256");
@@ -147,10 +168,16 @@ function computeTargetId(opts: {
   hash.update("\0");
   hash.update(opts.name ?? "");
   hash.update("\0");
-  hash.update(opts.kind ?? "");
+  hash.update(opts.identityKind);
   hash.update("\0");
   hash.update(opts.container ?? "");
   hash.update("\0");
+  hash.update(
+    opts.declarationPosition
+      ? `${opts.declarationPosition.line}:${opts.declarationOccurrence}`
+      : "",
+  );
+  hash.update("\0");
   hash.update(opts.fingerprint);
   return `tg-${hash.digest("hex").slice(0, 28)}`;
 }
@@ -181,10 +208,10 @@ function computeSpanId(
  * Register a resolved target in the given session-scoped store and return
  * stable session-scoped handles.
  *
- * If the same target (same file, position, name, kind) is registered
- * and the file fingerprint matches, the same IDs are returned.
- *
- * Returns an error when the backing file cannot be read for fingerprinting.
+ * If the same target identity (file, name, canonical kind, container,
+ * declaration occurrence, and fingerprint) is registered again, its stable
+ * target ID is reused and compatible facts are merged monotonically.
+ * Unreadable files are registered as unfingerprinted and rechecked on lookup.
  */
 export function registerWorkflowTarget(
   store: Map<string, TargetStoreEntry>,
@@ -196,47 +223,123 @@ export function registerWorkflowTarget(
 
   // Compute fingerprint; if unavailable, still allow registration but
   // mark as unfingerprinted so stale checks know the fingerprint is absent
-  const fingerprintResult = computeFileFingerprint(absFile);
+  const fingerprintResult = input.fileFingerprint ? null : computeFileFingerprint(absFile);
   const fingerprint =
-    fingerprintResult.kind === "ok" ? fingerprintResult.fingerprint : "unfingerprinted";
+    input.fileFingerprint ??
+    (fingerprintResult?.kind === "ok" ? fingerprintResult.fingerprint : "unfingerprinted");
 
   const targetId = computeTargetId({
     cwd: key,
     file: input.file,
-    position: input.position,
     name: input.name,
-    kind: input.kind,
+    identityKind: input.identityKind ?? input.kind ?? "",
     container: input.container,
+    declarationPosition: input.declarationPosition ?? null,
+    declarationOccurrence: input.declarationOccurrence ?? 0,
     fingerprint,
   });
   const spanId = computeSpanId(key, input.file, input.position, fingerprint);
 
-  // Check for existing entry with same targetId
-  const existing = store.get(targetId);
-  if (existing) {
-    return { targetId: existing.targetId, spanId: existing.spanId, entry: existing };
-  }
-
-  const entry: TargetStoreEntry = {
+  const incoming: TargetStoreEntry = {
     targetId,
     spanId,
     file: absFile,
     position: { line: input.position.line, character: input.position.character },
+    declarationPosition: input.declarationPosition ? { ...input.declarationPosition } : null,
+    declarationOccurrence: input.declarationOccurrence ?? 0,
     displayLine: input.displayLine,
     displayCharacter: input.displayCharacter,
     name: input.name,
     kind: input.kind,
     confidence: input.confidence,
-    provenance: input.provenance,
+    provenance: normalizeProvenance(input.provenance),
     anchorKind: input.anchorKind,
     fileFingerprint: fingerprint,
     container: input.container,
     resolution: input.resolution,
   };
 
+  const existing = store.get(targetId);
+  const entry = existing ? mergeTargetRefinement(existing, incoming) : incoming;
   store.set(targetId, entry);
 
-  return { targetId, spanId, entry };
+  return { targetId, spanId: entry.spanId, entry };
+}
+
+/**
+ * Merge compatible facts behind one stable target ID. Anchor precision,
+ * evidence strength, display kind, and provider provenance refine independently
+ * so no weaker or missing observation erases stronger established facts.
+ */
+function mergeTargetRefinement(
+  existing: TargetStoreEntry,
+  incoming: TargetStoreEntry,
+): TargetStoreEntry {
+  const anchorSource = selectAnchorSource(existing, incoming);
+  const strongestEvidenceSource = selectStrongestEvidenceSource(existing, incoming);
+  // Missing classification is not evidence that can erase an established display kind.
+  const displayKind = strongestEvidenceSource.kind ?? existing.kind ?? incoming.kind;
+
+  return {
+    ...existing,
+    spanId: anchorSource.spanId,
+    position: { ...anchorSource.position },
+    displayLine: anchorSource.displayLine,
+    displayCharacter: anchorSource.displayCharacter,
+    kind: displayKind,
+    anchorKind: anchorSource.anchorKind,
+    resolution: anchorSource.resolution,
+    confidence: strongestEvidenceSource.confidence,
+    provenance: mergeProvenance(existing.provenance, incoming.provenance),
+  };
+}
+
+function selectAnchorSource(
+  existing: TargetStoreEntry,
+  incoming: TargetStoreEntry,
+): TargetStoreEntry {
+  if (existing.anchorKind === "declaration" && incoming.anchorKind === "name") return incoming;
+  if (existing.anchorKind === "name" && incoming.anchorKind === "declaration") return existing;
+  if (!existing.resolution && incoming.resolution) return incoming;
+  return existing;
+}
+
+function selectStrongestEvidenceSource(
+  existing: TargetStoreEntry,
+  incoming: TargetStoreEntry,
+): TargetStoreEntry {
+  return confidenceRank(incoming.confidence) > confidenceRank(existing.confidence)
+    ? incoming
+    : existing;
+}
+
+const PROVENANCE_ORDER: readonly TargetProviderProvenance[] = ["semantic", "structural"];
+
+function normalizeProvenance(
+  provenance: readonly TargetProviderProvenance[],
+): readonly TargetProviderProvenance[] {
+  const sources = new Set(provenance);
+  return Object.freeze(PROVENANCE_ORDER.filter((source) => sources.has(source)));
+}
+
+function mergeProvenance(
+  existing: readonly TargetProviderProvenance[],
+  incoming: readonly TargetProviderProvenance[],
+): readonly TargetProviderProvenance[] {
+  return normalizeProvenance([...existing, ...incoming]);
+}
+
+function confidenceRank(confidence: ConfidenceMode): number {
+  switch (confidence) {
+    case "semantic":
+      return 3;
+    case "structural":
+      return 2;
+    case "heuristic":
+      return 1;
+    case "unavailable":
+      return 0;
+  }
 }
 
 /**