fix(go): resolve import paths correctly for multi-file symbol disambiguation

INV-007: When multiple Go files define the same symbol (e.g., generated
protobuf files copied across services), the analyzer now correctly uses
import paths to disambiguate.

Changes:
- ListNameResolver.lookup() now tries progressively shorter path suffixes
  (e.g., "zzz_correct/genproto" → "genproto") to find unique matches
- Falls back to deterministic (sorted by path) ordering when ambiguous
- Fixes flaky test failures on Python 3.13 due to dict ordering changes

The fix ensures call edges point to the correct target file based on
the import statement, not arbitrary file traversal order.

Signed-off-by: jgstern-agent <josh-agent@iterabloom.com>

Author: jgstern-agent

.agent/invariant-ledger.md

@@ -176,7 +176,21 @@ type, AND location).
 
 ---
 
-## INV-007: Template for New Invariants
+## INV-007: Go Import Path Resolution
+- **Statement:** When multiple Go files define the same symbol (same package name, same function),
+  call resolution must use the import path to pick the correct target file
+- **Status:** ✅ FIXED
+- **Root cause:** `symbol_resolution.py:ListNameResolver.lookup()` only checked the last directory
+  segment of the import path (e.g., "genproto") which matched multiple candidates. When no unique
+  match was found, it returned the first candidate, which was non-deterministic across Python versions.
+- **Fix:** Enhanced `ListNameResolver.lookup()` to:
+  1. Try progressively shorter suffixes of the import path (e.g., "zzz_correct/genproto", "genproto")
+  2. Return when exactly one candidate matches a suffix
+  3. Sort candidates deterministically (by path) when falling back to ambiguous resolution
+- **Regression tests:**
+  - `tests/test_go.py::TestGoImportPathResolution::test_resolves_call_to_correct_file_by_import_path`
+
+## INV-XXX: Template for New Invariants
 - **Statement:** [What must always be true]
 - **Status:** [UNFIXED | PARTIALLY ADDRESSED | FIXED | TBD]
 - **Root cause:** [File:line or description]

src/hypergumbo/symbol_resolution.py

@@ -584,20 +584,41 @@ def lookup(
 
         # Multiple candidates - try to disambiguate with path hint
         if path_hint:
-            # Extract directory hint from path (e.g., "grpc" from "/path/to/grpc/server.go")
-            dir_hint = path_hint.rstrip("/").rsplit("/", 1)[-1] if "/" in path_hint else path_hint
-            for candidate in candidates:
-                if dir_hint in candidate.path:
+            # Try progressively shorter suffixes of the path hint to find unique match
+            # e.g., for "github.com/example/src/zzz_correct/genproto", try:
+            #   1. "src/zzz_correct/genproto" (longest useful suffix)
+            #   2. "zzz_correct/genproto"
+            #   3. "genproto" (shortest)
+            path_parts = path_hint.rstrip("/").split("/")
+
+            # Start from second-to-last segment (skip domain parts like github.com)
+            # and try progressively shorter suffixes
+            for i in range(len(path_parts) - 1, 0, -1):
+                suffix = "/".join(path_parts[i:])
+                matching = [c for c in candidates if suffix in c.path]
+                if len(matching) == 1:
                     return LookupResult(
-                        symbol=candidate,
+                        symbol=matching[0],
                         confidence=self.CONFIDENCE_PATH_HINT,
                         match_type="path_hint",
                         candidates=candidates,
                     )
 
-        # Ambiguous - return first with low confidence
+            # Fallback: try just the last segment
+            dir_hint = path_parts[-1]
+            matching = [c for c in candidates if dir_hint in c.path]
+            if len(matching) == 1:
+                return LookupResult(
+                    symbol=matching[0],
+                    confidence=self.CONFIDENCE_PATH_HINT,
+                    match_type="path_hint",
+                    candidates=candidates,
+                )
+
+        # Ambiguous - sort for deterministic ordering, return first with low confidence
+        sorted_candidates = sorted(candidates, key=lambda s: s.path)
         return LookupResult(
-            symbol=candidates[0],
+            symbol=sorted_candidates[0],
             confidence=self.CONFIDENCE_AMBIGUOUS,
             match_type="ambiguous",
             candidates=candidates,

tests/test_go.py

@@ -977,6 +977,9 @@ def test_resolves_call_to_correct_file_by_import_path(self, tmp_path: Path) -> N
 
         We use 'aaa_wrong' vs 'zzz_correct' naming to ensure alphabetical
         ordering would pick the WRONG file (aaa < zzz).
+
+        Fixed in INV-007: ListNameResolver now tries progressively shorter
+        path suffixes to find unique matches.
         """
         from hypergumbo.analyze.go import analyze_go