feat(schema): introduce Producer node and route ASYNC_CALLS through it

Add Producer/DECLARES_PRODUCER, flip ASYNC_CALLS to Producer→Route,
wire GraphMeta counters, kuzu two-hop async queries, MCP find/resolve
producer parity, describe rollups, and PR-C tests (ontology 14 unchanged).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HumanBean17

README.md

@@ -386,7 +386,7 @@ Unresolved targets become **phantom** nodes (`resolved=false`, FQN guessed from
 | `CALLS` | method → method | In-process call (confidence-scored, strategy-tagged). |
 | `EXPOSES` | type → route | Type exposes an HTTP/async route. |
 | `HTTP_CALLS` | client → route | Cross-service HTTP call (caller-side Client to target Route). |
-| `ASYNC_CALLS` | symbol → route | Cross-service async (Kafka, Rabbit, JMS, …). |
+| `ASYNC_CALLS` | producer → route | Cross-service async (Kafka, Rabbit, JMS, …). |
 
 JDK / Spring / Lombok callees are represented as **phantom** method symbols at index time. Caller/callee traversals default to `exclude_external=true` so those edges are filtered by FQN prefix without dropping them from the graph.
 
@@ -426,7 +426,7 @@ Resolution order for `microservice`:
 
 Current ontology version is **14**. Any index built before this version must be rebuilt via `cocoindex update ... --full-reprocess -f` or a full `java-codebase-rag reprocess` (no selective flags) so vectors and graph stay aligned. Until re-indexed, the server defensively JSON-decodes string-form list columns so nothing explodes, but filters like `array_contains` will not work.
 
-Ontology **14** introduces `EDGE_SCHEMA` in `java_ontology.py` as the canonical edge navigation schema (see `docs/EDGE-NAVIGATION.md`). **`HTTP_CALLS` is `Client → Route`** (SCHEMA-V2 PR-B). **`ASYNC_CALLS` remains `Symbol → Route` until PR-C**, which adds the `Producer` node, `DECLARES_PRODUCER`, and flips `ASYNC_CALLS` to `Producer → Route`. Run one full reprocess after upgrading through the SCHEMA-V2 sequence (or when you need the v14 ontology gate).
+Ontology **14** introduces `EDGE_SCHEMA` in `java_ontology.py` as the canonical edge navigation schema (see `docs/EDGE-NAVIGATION.md`). **`HTTP_CALLS` is `Client → Route`** (SCHEMA-V2 PR-B). **`ASYNC_CALLS` is `Producer → Route`** with `DECLARES_PRODUCER` (SCHEMA-V2 PR-C). Run one full reprocess after upgrading through the SCHEMA-V2 sequence (or when you need the v14 ontology gate).
 
 Ontology **13** materializes stored `OVERRIDES` edges between method Symbols (subtype override → supertype declaration, matching `signature` on a direct `IMPLEMENTS` / `EXTENDS` hop). `neighbors(edge_types=["OVERRIDES"])` traverses this relationship; `OVERRIDDEN_BY*` keys in `edge_summary` remain describe-time rollups only.
 

build_ast_graph.py

@@ -96,7 +96,7 @@ Use these strings **verbatim** in `neighbors(..., edge_types=[...])`:
 | Method overrides | `OVERRIDES` | Subtype **method** → supertype **declaration** method (same `signature`, one `IMPLEMENTS`/`EXTENDS` hop). `in` = overriders; `out` = overridden declarations |
 | Method calls | `CALLS` | `in` = callers; `out` = callees |
 | Service boundary | `EXPOSES` | Symbol → Route (handler exposes route) |
-| Cross-service | `HTTP_CALLS`, `ASYNC_CALLS` | `HTTP_CALLS`: Client → Route; `ASYNC_CALLS`: Symbol → Route until SCHEMA-V2 PR-C (`Producer` node) |
+| Cross-service | `HTTP_CALLS`, `ASYNC_CALLS` | `HTTP_CALLS`: Client → Route; `ASYNC_CALLS`: Producer → Route via `DECLARES_PRODUCER` |
 
 Symmetric: cross-service and intra-service questions use the **same** `neighbors` call with different `edge_types`.
 
@@ -191,6 +191,7 @@ Exact allowed values for roles, capabilities, client kinds, etc. live in `java_o
 | List interfaces in service S | `find(kind="symbol", filter={"microservice":S,"symbol_kind":"interface"})` | `neighbors` / `describe` |
 | List HTTP or Kafka entry points | `find(kind="route", filter={...})` | `describe` |
 | List Feign / HTTP clients | `find(kind="client", filter={...})` | `neighbors(..., out, ["HTTP_CALLS"])` if needed |
+| List async producers | `find(kind="producer", filter={...})` | `neighbors(..., out, ["ASYNC_CALLS"])` if needed |
 | Who calls method M? | Stable symbol id via `resolve`, `find`, or `search` | `neighbors(ids=sym_id, direction="in", edge_types=["CALLS"])` |
 | What does M call? | Same | `neighbors(..., direction="out", edge_types=["CALLS"])` |
 | Who hits this route? | `find(kind="route", ...)` or route id from logs | `neighbors(ids=route_id, direction="in", edge_types=["HTTP_CALLS","ASYNC_CALLS","EXPOSES"])` |
@@ -263,7 +264,7 @@ Virtual keys (`OVERRIDDEN_BY`, …) and composed dot-keys are **not** valid `Edg
 
 ### Ontology glossary (version 14)
 
-Source of truth: `java_ontology.py` (`EDGE_SCHEMA`, valid sets). Strings are case-sensitive. Edge navigation: [`docs/EDGE-NAVIGATION.md`](./EDGE-NAVIGATION.md) — for `HTTP_CALLS`, traverse via `DECLARES_CLIENT` from a method Symbol or `neighbors` outbound from a Client id; `ASYNC_CALLS` still uses `*_current` member traversals until SCHEMA-V2 PR-C.
+Source of truth: `java_ontology.py` (`EDGE_SCHEMA`, valid sets). Strings are case-sensitive. Edge navigation: [`docs/EDGE-NAVIGATION.md`](./EDGE-NAVIGATION.md) — for `HTTP_CALLS`, traverse via `DECLARES_CLIENT` from a method Symbol or `neighbors` outbound from a Client id; for `ASYNC_CALLS`, traverse via `DECLARES_PRODUCER` or outbound from a Producer id.
 
 **Roles:** `CONTROLLER`, `SERVICE`, `REPOSITORY`, `COMPONENT`, `CONFIG`, `ENTITY`, `CLIENT`, `MAPPER`, `DTO`, `OTHER`.
 

docs/AGENT-GUIDE.md

@@ -15,8 +15,9 @@
 | CALLS | Symbol | Symbol | many_to_many | yes | yes |
 | EXPOSES | Symbol | Route | one_to_one | yes | yes |
 | DECLARES_CLIENT | Symbol | Client | one_to_many | yes | yes |
+| DECLARES_PRODUCER | Symbol | Producer | one_to_many | yes | yes |
 | HTTP_CALLS | Client | Route | many_to_many | yes | no |
-| ASYNC_CALLS | Symbol | Route | many_to_many | yes | no |
+| ASYNC_CALLS | Producer | Route | many_to_many | yes | no |
 
 ## EXTENDS
 
@@ -183,6 +184,26 @@
 - `member_subject`: neighbors(['{id}'],'out',['DECLARES_CLIENT'])
 - `alien_subject`: DECLARES_CLIENT connects method Symbol → Client
 
+## DECLARES_PRODUCER
+
+**Endpoints**: `Symbol → Producer`
+**Cardinality**: `one_to_many`
+**Brownfield-resolver-sourced**: yes
+**Member-only** (hints): yes
+
+**Purpose**: method declares an outbound async producer call site
+
+**Attributes**:
+
+- `confidence` (`DOUBLE`) — producer declaration confidence in [0.0, 1.0]
+- `strategy` (`STRING`) — producer resolution strategy literal
+
+**Typical traversals**:
+
+- `type_subject`: neighbors(['{id}'],'out',['DECLARES']) then neighbors(member_ids,'{direction}',['DECLARES_PRODUCER'])
+- `member_subject`: neighbors(['{id}'],'out',['DECLARES_PRODUCER'])
+- `alien_subject`: DECLARES_PRODUCER connects method Symbol → Producer
+
 ## HTTP_CALLS
 
 **Endpoints**: `Client → Route`
@@ -209,12 +230,12 @@
 
 ## ASYNC_CALLS
 
-**Endpoints**: `Symbol → Route`
+**Endpoints**: `Producer → Route`
 **Cardinality**: `many_to_many`
 **Brownfield-resolver-sourced**: yes
 **Member-only** (hints): no
 
-**Purpose**: resolved async call from declaring method to topic route (pre-flip: Symbol→Route; PR-C: Producer→Route)
+**Purpose**: resolved async call from a declared Producer to a topic route
 
 **Attributes**:
 
@@ -226,8 +247,7 @@
 
 **Typical traversals**:
 
-- `type_subject_current`: neighbors(['{id}'],'out',['DECLARES']) then neighbors(member_ids,'out',['ASYNC_CALLS'])
 - `type_subject`: neighbors(['{id}'],'out',['DECLARES']) then neighbors(member_ids,'out',['DECLARES_PRODUCER']) then neighbors(producer_ids,'out',['ASYNC_CALLS'])
-- `member_subject_current`: neighbors(['{id}'],'out',['ASYNC_CALLS'])
 - `member_subject`: neighbors(['{id}'],'out',['DECLARES_PRODUCER']) then neighbors(producer_ids,'out',['ASYNC_CALLS'])
-- `alien_subject`: ASYNC_CALLS is Symbol→Route until PR-C; use member_subject_current. After PR-C (Producer→Route), use member_subject via DECLARES_PRODUCER
+- `route_subject`: neighbors(['{id}'],'in',['ASYNC_CALLS']) then neighbors(producer_ids,'in',['DECLARES_PRODUCER']) for declaring method
+- `alien_subject`: ASYNC_CALLS connects Producer→Route; use DECLARES_PRODUCER from a method Symbol, or neighbors(producer_id,'out',['ASYNC_CALLS']) from a Producer id

docs/EDGE-NAVIGATION.md

@@ -98,8 +98,8 @@ You cannot reason reliably about cross-service behaviour until these surfaces ex
 **Sequence:**
 
 1. Cluster routes by path prefix; **`describe`** on representative `route:` ids.
-2. For each major route, **`neighbors(direction="in", edge_types=["EXPOSES"])`** to land on handler symbols; for inbound **`HTTP_CALLS`**, expect **Client** callers (then **`DECLARES_CLIENT` inbound** to the declaring method); **`ASYNC_CALLS`** inbound still lands on Symbol callers until PR-C.
-3. Use **`find(kind="client", …)`** with the same microservice filter to list outbound integration points; follow outbound **`HTTP_CALLS`** from each Client (or **`ASYNC_CALLS`** from methods until Producer lands).
+2. For each major route, **`neighbors(direction="in", edge_types=["EXPOSES"])`** to land on handler symbols; for inbound **`HTTP_CALLS`**, expect **Client** callers (then **`DECLARES_CLIENT` inbound** to the declaring method); for inbound **`ASYNC_CALLS`**, expect **Producer** callers (then **`DECLARES_PRODUCER` inbound** to the declaring method).
+3. Use **`find(kind="client", …)`** and **`find(kind="producer", …)`** with the same microservice filter to list outbound integration points; follow outbound **`HTTP_CALLS`** from each Client and **`ASYNC_CALLS`** from each Producer.
 
 **Stopping rule:** You can summarize how traffic enters the service, what modules/controllers own key paths, and what external systems it calls—**without** claiming tests, runtime config, or unindexed siblings exist in MCP.
 
@@ -116,7 +116,7 @@ You cannot reason reliably about cross-service behaviour until these surfaces ex
 **Sequence:**
 
 1. **`neighbors(direction="in", edge_types=["EXPOSES"])`** onto the handling symbol; walk **`CALLS`** outbound method-by-method.
-2. When a method makes outbound HTTP, **`neighbors(..., out, ["DECLARES_CLIENT"])`** then outbound **`HTTP_CALLS`** from each Client id; for async (pre-PR-C), **`ASYNC_CALLS`** may still be direct from the method Symbol.
+2. When a method makes outbound HTTP, **`neighbors(..., out, ["DECLARES_CLIENT"])`** then outbound **`HTTP_CALLS`** from each Client id; for async, **`neighbors(..., out, ["DECLARES_PRODUCER"])`** then outbound **`ASYNC_CALLS`** from each Producer id.
 3. Stop at leaves, framework boundaries, or unresolved edges; read **`edge.attrs`** (`attrs.confidence`, `attrs.strategy`, `attrs.match`) and report low-confidence segments as resolver gaps, not as facts.
 
 **Stopping rule:** You reach a stable leaf (external IO, message publish, clear terminal layer) **or** you document every unresolved hop with a concrete next non-MCP check.
@@ -239,11 +239,11 @@ Ten edge types:
 | Group | Edges |
 | ----- | ----- |
 | Type wiring | `EXTENDS`, `IMPLEMENTS`, `INJECTS` |
-| Containment | `DECLARES`, `DECLARES_CLIENT` |
+| Containment | `DECLARES`, `DECLARES_CLIENT`, `DECLARES_PRODUCER` |
 | Method overrides | `OVERRIDES` |
 | Method calls | `CALLS` |
 | Service boundary | `EXPOSES` |
-| Cross-service | `HTTP_CALLS` (Client→Route), `ASYNC_CALLS` (Symbol→Route until Producer) |
+| Cross-service | `HTTP_CALLS` (Client→Route), `ASYNC_CALLS` (Producer→Route) |
 
 For exact argument shapes, recovery playbook, and slash aliases see
 [`docs/AGENT-GUIDE.md`](https://github.com/HumanBean17/java-codebase-rag/blob/master/docs/AGENT-GUIDE.md) in the java-codebase-rag repo.

docs/skills/java-codebase-explore.md

@@ -301,6 +301,26 @@ class EdgeSpec:
             "alien_subject": "DECLARES_CLIENT connects method Symbol → Client",
         },
     ),
+    "DECLARES_PRODUCER": EdgeSpec(
+        name="DECLARES_PRODUCER",
+        src="Symbol",
+        dst="Producer",
+        cardinality="one_to_many",
+        brownfield_resolver_sourced=True,
+        attrs=(
+            EdgeAttr("confidence", "DOUBLE", "producer declaration confidence in [0.0, 1.0]"),
+            EdgeAttr("strategy", "STRING", "producer resolution strategy literal"),
+        ),
+        purpose="method declares an outbound async producer call site",
+        member_only=True,
+        typical_traversals={
+            "type_subject": _SYMBOL_TYPE_TRAVERSAL.format(
+                id="{id}", direction="{direction}", edge="DECLARES_PRODUCER",
+            ),
+            "member_subject": "neighbors(['{id}'],'out',['DECLARES_PRODUCER'])",
+            "alien_subject": "DECLARES_PRODUCER connects method Symbol → Producer",
+        },
+    ),
     "HTTP_CALLS": EdgeSpec(
         name="HTTP_CALLS",
         src="Client",
@@ -337,7 +357,7 @@ class EdgeSpec:
     ),
     "ASYNC_CALLS": EdgeSpec(
         name="ASYNC_CALLS",
-        src="Symbol",
+        src="Producer",
         dst="Route",
         cardinality="many_to_many",
         brownfield_resolver_sourced=True,
@@ -348,25 +368,24 @@ class EdgeSpec:
             EdgeAttr("raw_topic", "STRING", "uninterpolated topic template from the call site"),
             EdgeAttr("match", "STRING", "cross_service|intra_service|ambiguous|phantom|unresolved"),
         ),
-        purpose="resolved async call from declaring method to topic route (pre-flip: Symbol→Route; PR-C: Producer→Route)",
+        purpose="resolved async call from a declared Producer to a topic route",
         typical_traversals={
-            "type_subject_current": (
-                "neighbors(['{id}'],'out',['DECLARES']) "
-                "then neighbors(member_ids,'out',['ASYNC_CALLS'])"
-            ),
             "type_subject": (
                 "neighbors(['{id}'],'out',['DECLARES']) "
                 "then neighbors(member_ids,'out',['DECLARES_PRODUCER']) "
                 "then neighbors(producer_ids,'out',['ASYNC_CALLS'])"
             ),
-            "member_subject_current": "neighbors(['{id}'],'out',['ASYNC_CALLS'])",
             "member_subject": (
                 "neighbors(['{id}'],'out',['DECLARES_PRODUCER']) "
                 "then neighbors(producer_ids,'out',['ASYNC_CALLS'])"
             ),
+            "route_subject": (
+                "neighbors(['{id}'],'in',['ASYNC_CALLS']) "
+                "then neighbors(producer_ids,'in',['DECLARES_PRODUCER']) for declaring method"
+            ),
             "alien_subject": (
-                "ASYNC_CALLS is Symbol→Route until PR-C; use member_subject_current. "
-                "After PR-C (Producer→Route), use member_subject via DECLARES_PRODUCER"
+                "ASYNC_CALLS connects Producer→Route; use DECLARES_PRODUCER from a method Symbol, "
+                "or neighbors(producer_id,'out',['ASYNC_CALLS']) from a Producer id"
             ),
         },
     ),