add cross-service resolution mode flag for pass6 matching (#30)

HumanBean17 · cursoragent · web-flow · commit bb5a8dfe4b10 · 2026-05-06T10:09:07.000+03:00
* add cross-service resolution mode flag for pass6 matching

Introduce `cross_service_resolution` (auto|brownfield_only), persist it in GraphMeta, and gate pass6 cross-service promotion so brownfield-only mode keeps only fully brownfield-sourced edges.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;

* moved completed plan

* split suppressed pass6 debug examples by channel

Keep brownfield-only suppression counts unchanged but log separate first-five examples for HTTP and async to make pass6 debugging clearer.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;

---------

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/.cursor/rules/agent-workflow.mdc b/.cursor/rules/agent-workflow.mdc
@@ -66,9 +66,9 @@ When you're given a per-PR task prompt from `plans/CURSOR-PROMPTS-*.md`:
   `java_ontology.py`. Don't sprinkle role / capability / client-kind /
   strategy / match string literals across other modules.
 - Schema changes that affect the Lance index or Kuzu graph need a
-  matching update to the README "Re-index required" callout. Bump
-  `ontology_version` when enrichment semantics change. The current
-  version is **7**.
+  matching update to the  README "Re-index required" callout. Bump
+ `ontology_version` when enrichment semantics change. The current
+ version is **8**.
 - Brownfield is a first-class surface: any new auto-detection
   (route, role, capability, http client, async producer) must
   compose with the matching `BrownfieldOverrides` layer. Last writer
diff --git a/.cursor/rules/project-overview.mdc b/.cursor/rules/project-overview.mdc
@@ -20,8 +20,9 @@ when needed.
 
 - `README.md` — feature surface, env vars, ranking, capabilities,
   tool list, "Re-index required" callouts. The current
-  `ontology_version` is **7** (HTTP_CALLS / ASYNC_CALLS caller
-  edges + brownfield client/producer composition). Earlier
+  `ontology_version` is **8** (HTTP_CALLS / ASYNC_CALLS caller
+  edges + brownfield client/producer composition + cross-service
+  resolution mode on GraphMeta). Earlier
   ontology bumps are described inline in the README's
   callouts list.
 - `CODEBASE_REQUIREMENTS.md` — Java-repo assumptions and per-file
diff --git a/AGENTS.md b/AGENTS.md
@@ -8,8 +8,8 @@ for tools that don't read `.cursor/rules/`.
 ## Where to look
 
 - `README.md` — feature surface, env vars, ranking, capabilities,
-  tool list, "Re-index required" callouts. **`ontology_version` is
-  currently 7.**
+ tool list, "Re-index required" callouts. **`ontology_version` is
+ currently 8.**
 - `CODEBASE_REQUIREMENTS.md` — Java-repo assumptions and tuning map.
 - `propose/` and `plans/` (plus their `completed/` subdirs) —
   in-flight scope and the rationale behind current design.
diff --git a/README.md b/README.md
@@ -100,7 +100,9 @@ Resolution order for `microservice`:
 > 4. **`ontology_version` 7** adds caller-side edge extraction (`HTTP_CALLS`, `ASYNC_CALLS`) and
 >    brownfield caller composition (`http_client_overrides`, `async_producer_overrides`,
 >    `@CodebaseClient`, `@CodebaseProducer`) — rebuild Kuzu after upgrading.
->    rebuild the Kuzu graph (`build_ast_graph.py` or `refresh_code_index`).
+> 5. **`ontology_version` 8** adds `GraphMeta.cross_service_resolution` (from
+>    `cross_service_resolution` in `.lancedb-mcp.yml`) — rebuild the Kuzu graph
+>    (`build_ast_graph.py` or `refresh_code_index`) after upgrading.
 >
 > Any index built before these changes must be rebuilt via
 > `cocoindex update ... --full-reprocess -f` or `refresh_code_index`. Until
@@ -289,6 +291,22 @@ route_overrides:
 ```
 
 Unknown `framework` / `kind` strings are dropped with a stderr warning.
+
+**Cross-service resolution mode** — optional top-level key in the same file:
+
+```yaml
+cross_service_resolution: auto          # default when omitted
+# cross_service_resolution: brownfield_only
+```
+
+With `brownfield_only`, pass 6 does not promote auto-detected call sites to
+`cross_service` matches: only edges where both the caller strategy and every
+matched route’s `source_layer` come from brownfield (`@CodebaseRoute`,
+`@CodebaseClient`, YAML overrides, meta-annotation closure, or FQN maps) stay
+`cross_service`. Everything else that would have been a cross-service match
+becomes `unresolved`. `intra_service`, `phantom`, and `ambiguous` behaviour is
+unchanged. Unknown values log a warning and behave like `auto`.
+
 Resolution order for each method mirrors role brownfield: built-in extraction,
 then annotation map, then meta-annotation closure (same `collect_annotation_meta_chain`
 index as roles — see `plans/completed/PLAN-BROWNFIELD-ROLE-OVERRIDES-design-fixes.md`),
diff --git a/ast_java.py b/ast_java.py
@@ -70,8 +70,9 @@
     "EqualsAndHashCode", "ToString",
 })
 
-# Phase 5: HTTP_CALLS + ASYNC_CALLS (B2b); bumps whenever extraction / enrichment semantics change.
-ONTOLOGY_VERSION = 7
+# Phase 5: HTTP_CALLS + ASYNC_CALLS (B2b); Phase 6: cross-service resolution mode on GraphMeta.
+# Bumps whenever extraction / enrichment semantics change.
+ONTOLOGY_VERSION = 8
 
 ROLE_ANNOTATIONS: dict[str, str] = {
     # Spring Web
diff --git a/build_ast_graph.py b/build_ast_graph.py
@@ -51,6 +51,7 @@
     parse_java,
 )
 from graph_enrich import (
+    _load_config_cross_service_resolution,
     collect_annotation_meta_chain,
     load_brownfield_overrides,
     microservice_for_path,
@@ -254,6 +255,7 @@ class GraphTables:
     parse_errors: int = 0
     skipped_files: int = 0
     pass3_skipped_cross_service: int = 0
+    cross_service_resolution: str = "auto"
 
 
 # ---------- file walk (see `path_filtering.iter_java_source_files`) ----------
@@ -1276,6 +1278,7 @@ def pass4_routes(
         prs = str(source_root.resolve())
     except OSError:
         prs = str(source_root)
+    tables.cross_service_resolution = _load_config_cross_service_resolution(prs)
     meta_chain = collect_annotation_meta_chain(prs)
 
     for ast in asts.values():
@@ -1411,6 +1414,7 @@ def pass5_imperative_edges(
         prs = str(source_root.resolve())
     except OSError:
         prs = str(source_root)
+    tables.cross_service_resolution = _load_config_cross_service_resolution(prs)
     meta_chain = collect_annotation_meta_chain(prs)
     routes_by_id = {r.id: r for r in tables.routes_rows}
     existing_route_ids = set(routes_by_id)
@@ -1648,6 +1652,30 @@ def _match_call_edge(
     return "cross_service", candidates
 
 
+_BROWNFIELD_LAYERS = frozenset({
+    "layer_c_source",
+    "layer_b_ann",
+    "layer_b_fqn",
+    "layer_a_meta",
+})
+
+
+def _is_brownfield_sourced(
+    call_strategy: str,
+    candidates: list[RouteRow],
+) -> bool:
+    """Both sides must come from brownfield layers for an edge to count as
+    authoritative under brownfield_only mode."""
+    if not candidates:
+        return False
+    if call_strategy not in _BROWNFIELD_LAYERS:
+        return False
+    return all(
+        getattr(c, "source_layer", "builtin") in _BROWNFIELD_LAYERS
+        for c in candidates
+    )
+
+
 def pass6_match_edges(
     tables: GraphTables,
     *,
@@ -1670,6 +1698,11 @@ def pass6_match_edges(
     tables.call_edge_stats.async_calls_match_breakdown.clear()
     tables.call_edge_stats.cross_service_calls_total = 0
 
+    brownfield_only = tables.cross_service_resolution == "brownfield_only"
+    suppressed_auto_cross_http: list[str] = []
+    suppressed_auto_cross_async: list[str] = []
+    suppressed_auto_cross_count = 0
+
     def _micro_factor(member: MemberEntry | None) -> float:
         return 1.0 if (member and member.microservice) else 0.85
 
@@ -1679,10 +1712,18 @@ def _micro_factor(member: MemberEntry | None) -> float:
         member = member_by_id.get(row.symbol_id)
         base = row.confidence / max(1e-9, (0.3 * _micro_factor(member)))
         src_route = route_by_id.get(row.route_id)
+        # Declared Feign client methods use `http_consumer` routes; synthetic phantoms from
+        # imperative clients are `http_endpoint` even when `feign_name` is populated from
+        # `@CodebaseClient.targetService` / YAML hints — those must path-match like RestTemplate.
+        _feign_like = (
+            src_route is not None
+            and src_route.kind == "http_consumer"
+            and bool(src_route.feign_name)
+        )
         call = OutgoingCallDecl(
             method_fqn=f"{member.parent_fqn}#{member.decl.signature}" if member else "",
             method_sig=member.decl.signature if member else "",
-            client_kind="feign_method" if (src_route and src_route.feign_name) else "rest_template",
+            client_kind="feign_method" if _feign_like else "rest_template",
             channel="http",
             feign_target_name=src_route.feign_name if src_route else "",
             feign_target_url=src_route.feign_url if src_route else "",
@@ -1700,6 +1741,16 @@ def _micro_factor(member: MemberEntry | None) -> float:
             end_line=member.decl.end_line if member else 0,
         )
         outcome, candidates = _match_call_edge(call, all_routes, member.microservice if member else "")
+        if (
+            brownfield_only
+            and outcome == "cross_service"
+            and not _is_brownfield_sourced(row.strategy, candidates)
+        ):
+            outcome = "unresolved"
+            candidates = []
+            suppressed_auto_cross_count += 1
+            if len(suppressed_auto_cross_http) < 5:
+                suppressed_auto_cross_http.append(call.method_fqn)
         if outcome in VALID_CALL_MATCHES:
             row.match = outcome
         if outcome in ("cross_service", "intra_service") and len(candidates) == 1:
@@ -1736,6 +1787,16 @@ def _micro_factor(member: MemberEntry | None) -> float:
             end_line=member.decl.end_line if member else 0,
         )
         outcome, candidates = _match_call_edge(call, all_routes, member.microservice if member else "")
+        if (
+            brownfield_only
+            and outcome == "cross_service"
+            and not _is_brownfield_sourced(row.strategy, candidates)
+        ):
+            outcome = "unresolved"
+            candidates = []
+            suppressed_auto_cross_count += 1
+            if len(suppressed_auto_cross_async) < 5:
+                suppressed_auto_cross_async.append(call.method_fqn)
         if outcome in VALID_CALL_MATCHES:
             row.match = outcome
         if outcome in ("cross_service", "intra_service") and len(candidates) == 1:
@@ -1760,6 +1821,18 @@ def _micro_factor(member: MemberEntry | None) -> float:
     )
 
     if verbose:
+        if brownfield_only:
+            n_bf = tables.call_edge_stats.cross_service_calls_total
+            first_http = ", ".join(suppressed_auto_cross_http)
+            first_async = ", ".join(suppressed_auto_cross_async)
+            print(
+                f"[pass6] cross_service_resolution=brownfield_only:\n"
+                f"        {n_bf} cross_service edges from brownfield layers,\n"
+                f"        {suppressed_auto_cross_count} auto-cross-service candidates suppressed -> unresolved\n"
+                f"        (first 5 http: {first_http})\n"
+                f"        (first 5 async: {first_async})",
+                file=sys.stderr,
+            )
         print(
             f"[pass6] http_match={dict(sorted(tables.call_edge_stats.http_calls_match_breakdown.items()))}, "
             f"async_match={dict(sorted(tables.call_edge_stats.async_calls_match_breakdown.items()))}, "
@@ -1805,7 +1878,8 @@ def _micro_factor(member: MemberEntry | None) -> float:
     "http_calls_match_breakdown STRING, "
     "async_calls_match_breakdown STRING, "
     "cross_service_calls_total INT64, "
-    "pass3_skipped_cross_service INT64"
+    "pass3_skipped_cross_service INT64, "
+    "cross_service_resolution STRING"
     ")"
 )
 
@@ -1925,6 +1999,11 @@ def _write_nodes(
     meta_chain: dict[str, frozenset[str]] | None,
 ) -> None:
     overrides = load_brownfield_overrides(project_root)
+    try:
+        prs = str(project_root.resolve())
+    except OSError:
+        prs = str(project_root)
+    tables.cross_service_resolution = _load_config_cross_service_resolution(prs)
     mch = meta_chain
     # packages
     for pkg, pid in tables.packages.items():
@@ -2183,7 +2262,8 @@ def _write_meta(conn: kuzu.Connection, tables: GraphTables, source_root: Path) -
         "http_calls_match_breakdown: $http_calls_match_breakdown, "
         "async_calls_match_breakdown: $async_calls_match_breakdown, "
         "cross_service_calls_total: $cross_service_calls_total, "
-        "pass3_skipped_cross_service: $pass3_skipped_cross_service})",
+        "pass3_skipped_cross_service: $pass3_skipped_cross_service, "
+        "cross_service_resolution: $cross_service_resolution})",
         {
             "k": "graph",
             "ov": ONTOLOGY_VERSION,
@@ -2209,6 +2289,7 @@ def _write_meta(conn: kuzu.Connection, tables: GraphTables, source_root: Path) -
             "async_calls_match_breakdown": json.dumps(async_match),
             "cross_service_calls_total": int(call_stats.cross_service_calls_total),
             "pass3_skipped_cross_service": int(tables.pass3_skipped_cross_service),
+            "cross_service_resolution": str(tables.cross_service_resolution),
         },
     )
 
diff --git a/graph_enrich.py b/graph_enrich.py
@@ -143,6 +143,41 @@ def _load_config_microservice_roots(project_root_str: str) -> tuple[str, ...]:
     return ()
 
 
+@lru_cache(maxsize=64)
+def _load_config_cross_service_resolution(project_root_str: str) -> str:
+    """Read `cross_service_resolution` from `.lancedb-mcp.yml` at project_root.
+
+    Returns "auto" or "brownfield_only". Defaults to "auto" when the key is absent
+    or the file is missing / malformed. Unknown values warn on stderr and fall back
+    to "auto".
+    """
+    root = Path(project_root_str)
+    for name in CONFIG_FILENAMES:
+        candidate = root / name
+        if not candidate.is_file():
+            continue
+        try:
+            import yaml  # PyYAML; already a transitive dep of cocoindex
+        except ImportError:
+            return "auto"
+        try:
+            data = yaml.safe_load(candidate.read_text(encoding="utf-8"))
+        except Exception:
+            return "auto"
+        if not isinstance(data, dict):
+            return "auto"
+        val = data.get("cross_service_resolution", "auto")
+        if val not in {"auto", "brownfield_only"}:
+            print(
+                f"[lancedb-mcp] cross_service_resolution: unknown value "
+                f"{val!r}, falling back to 'auto'",
+                file=sys.stderr,
+            )
+            return "auto"
+        return val
+    return "auto"
+
+
 def load_microservice_overrides(project_root: str | Path | None) -> tuple[str, ...]:
     """Combined override list (env var ++ config file).
 
diff --git a/kuzu_queries.py b/kuzu_queries.py
@@ -346,7 +346,8 @@ def meta(self) -> dict[str, Any]:
             "m.http_calls_match_breakdown AS http_calls_match_breakdown, "
             "m.async_calls_match_breakdown AS async_calls_match_breakdown, "
             "m.cross_service_calls_total AS cross_service_calls_total, "
-            "m.pass3_skipped_cross_service AS pass3_skipped_cross_service"
+            "m.pass3_skipped_cross_service AS pass3_skipped_cross_service, "
+            "m.cross_service_resolution AS cross_service_resolution"
         )
         _META_PRE_E3 = (
             "MATCH (m:GraphMeta) RETURN m.key AS key, m.ontology_version AS ontology_version, "
@@ -422,6 +423,7 @@ def meta(self) -> dict[str, Any]:
         async_calls_match_breakdown: dict[str, Any] = {}
         cross_service_calls_total = 0
         pass3_skipped_cross_service = 0
+        cross_service_resolution: str | None = None
         if meta_mode != "legacy":
             rfw_raw = row.get("routes_by_framework") or "{}"
             try:
@@ -478,6 +480,11 @@ def meta(self) -> dict[str, Any]:
                 async_calls_match_breakdown = {}
             cross_service_calls_total = int(row.get("cross_service_calls_total") or 0)
             pass3_skipped_cross_service = int(row.get("pass3_skipped_cross_service") or 0)
+            if meta_mode == "pr_e3":
+                raw_csr = row.get("cross_service_resolution")
+                cross_service_resolution = (
+                    str(raw_csr) if raw_csr not in (None, "") else None
+                )
         return {
             "ontology_version": int(row.get("ontology_version") or 0),
             "built_at": int(row.get("built_at") or 0),
@@ -502,6 +509,7 @@ def meta(self) -> dict[str, Any]:
             "async_calls_match_breakdown": async_calls_match_breakdown,
             "cross_service_calls_total": cross_service_calls_total,
             "pass3_skipped_cross_service": pass3_skipped_cross_service,
+            "cross_service_resolution": cross_service_resolution,
             "db_path": self.db_path,
         }
 
diff --git a/plans/completed/PLAN-POST-TIER1B-FOLLOWUPS.md b/plans/completed/PLAN-POST-TIER1B-FOLLOWUPS.md
diff --git a/server.py b/server.py
@@ -343,6 +343,7 @@ class GraphMetaOutput(BaseModel):
     http_calls_match_breakdown: dict[str, int] = Field(default_factory=dict)
     async_calls_match_breakdown: dict[str, int] = Field(default_factory=dict)
     cross_service_calls_total: int = 0
+    cross_service_resolution: str | None = None
     message: str | None = None
 
 
@@ -523,6 +524,7 @@ def _graph_meta_output() -> GraphMetaOutput:
         http_calls_match_breakdown={str(k): int(v) for k, v in (meta.get("http_calls_match_breakdown") or {}).items()},
         async_calls_match_breakdown={str(k): int(v) for k, v in (meta.get("async_calls_match_breakdown") or {}).items()},
         cross_service_calls_total=int(meta.get("cross_service_calls_total") or 0),
+        cross_service_resolution=meta.get("cross_service_resolution"),
     )
 
 
diff --git a/tests/test_call_edges_e2e.py b/tests/test_call_edges_e2e.py
@@ -76,8 +76,7 @@ def test_graph_meta_call_edge_counters(tmp_path: Path, corpus_root: Path) -> Non
     assert 0.0 <= m["async_calls_resolved_pct"] <= 1.0
 
 
-def test_ontology_version_bumped_to_7(tmp_path: Path, corpus_root: Path) -> None:
+def test_ontology_version_matches_graph_meta(tmp_path: Path, corpus_root: Path) -> None:
     db = tmp_path / "ontology.kuzu"
     _build(corpus_root, db)
-    assert ONTOLOGY_VERSION == 7
-    assert KuzuGraph(str(db)).meta()["ontology_version"] == 7
+    assert KuzuGraph(str(db)).meta()["ontology_version"] == ONTOLOGY_VERSION
diff --git a/tests/test_cross_service_resolution_flag.py b/tests/test_cross_service_resolution_flag.py
