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

[HumanBean17]

Summary

• Adds Producer node, DECLARES_PRODUCER, and flips ASYNC_CALLS to Producer → Route (ontology 14 unchanged; full reprocess still required for v14 graph shape).
• Materializes producers in pass5 (AsyncCallRow.producer_id), emits edges in pass6/write; GraphMeta gains producers_total / declares_producer_total / producers_by_kind.
• Downstream: two-hop async in find_route_callers, trace_request_flow, impact expansion, pr_analysis; MCP find(kind="producer") / resolve(hint_kind="producer"); type-level describe rollups DECLARES.DECLARES_PRODUCER and OVERRIDDEN_BY.DECLARES_PRODUCER.
• Regenerated docs/EDGE-NAVIGATION.md (11 edges). PR-D (hints v3) is next — not in this PR.

ASYNC_CALLS / Producer grep (this PR’s *.py / *.md deltas)

Area	Accounting
build_ast_graph.py	Producer DDL/rows, DECLARES_PRODUCER, ASYNC_CALLS FROM Producer, pass5 materialization, pass6 via producer_id, GraphMeta counters
java_ontology.py	DECLARES_PRODUCER + ASYNC_CALLS src=Producer; post-flip traversals
kuzu_queries.py	Two-hop async queries; list_producers; RouteCaller producer branch (topic/broker)
mcp_v2.py / server.py	producer kind on find/resolve/neighbors schema; no mcp_hints.py
pr_analysis.py	Cross-service async reachability two-hop
Tests	All 12 Tests for PR-C from plans/PLAN-SCHEMA-V2.md
Docs	README, AGENT-GUIDE, exploration skill, EDGE-NAVIGATION

Sentinel checks (zero on diff): no TPL_NEIGHBORS_WRONG_SUBJECT_KIND / neighbors_empty_hints implementation; no Symbol)-[e:ASYNC_CALLS] in production emit/query paths; no ONTOLOGY_VERSION = 15.

Test plan

• .venv/bin/ruff check build_ast_graph.py kuzu_queries.py mcp_v2.py
• .venv/bin/python -m pytest tests/test_call_edges_e2e.py tests/test_brownfield_clients.py tests/test_mcp_v2.py tests/test_ast_graph_build.py -v
• rm -rf /tmp/schema-v2-c && .venv/bin/python build_ast_graph.py --source-root tests/fixtures/http_caller_smoke --kuzu-path /tmp/schema-v2-c --verbose
• .venv/bin/ruff check .
• PATH=".venv/bin:$PATH" .venv/bin/python -m pytest tests -v (550 passed, 10 skipped)

Made with Cursor

[HumanBean17]

Review summary

Solid, plan-aligned PR-C implementation. Schema flip (Producer + DECLARES_PRODUCER + ASYNC_CALLS: Producer → Route), pass5 materialization, downstream two-hop queries, MCP find/resolve, and describe rollups all match plans/PLAN-SCHEMA-V2.md. Assuming tests are green, this is approve with minor follow-ups.

---

What looks good

• End-to-end wiring in build_ast_graph.py, java_ontology.py, and regenerated docs/EDGE-NAVIGATION.md (11 edges); DDL ↔ EDGE_SCHEMA stays consistent.
• Pass5 mirrors Client: materialize Producer → DECLARES_PRODUCER → ASYNC_CALLS, sensible dedup keys, GraphMeta producer counters.
• Downstream updated: find_route_callers, trace_request_flow, impact expansion, pr_analysis all use two-hop async; RouteCaller adds caller_node_kind="producer" with topic/broker.
• MCP parity: find(kind="producer"), resolve(hint_kind="producer"), type rollups (DECLARES.DECLARES_PRODUCER, OVERRIDDEN_BY.DECLARES_PRODUCER).
• Plan sentinels respected (ontology 14 unchanged; no Symbol)-[e:ASYNC_CALLS] in production paths).

---

Should fix before or right after merge

1. MCP tool descriptions still describe a 3-kind world

Literal types were extended, but several LLM-facing strings in server.py were not:

• _INSTRUCTIONS: resolve still “symbol/route/client”
• find kind description: no producer
• resolve hint_kind: still “all three kinds”
• describe id help: no p: / producer prefix
• neighbors ids help: still symbol/route/client only

These are part of the MCP contract for tool selection — worth updating in this PR or an immediate follow-up.

2. Pass6 async rematch hardcodes client_kind="kafka_send"

HTTP pass6 reconstructs kind from the Client row; async pass6 always uses kafka_send when rebuilding OutgoingCallDecl for matching. For stream_bridge_send producers, pass6 can diverge from pass5 (producer.producer_kind is on ProducerRow). Suggest using producer.producer_kind when producer is present.

3. docs/AGENT-GUIDE.md banner

Still says “PR-C adds Producer…” in future tense — update to present tense post-merge.

---

Minor / optional

• _resolve_producer_candidates reuses client_target / client_target_path ResolveReason values for topic lookup — works, but misleading for agents reading reason.
• _producer_id omits broker from the hash key; two call sites with same topic + different brokers collapse to one Producer — confirm intentional or add broker to the key.
• producers_total is on GraphMeta and in counts_json, but not on GraphMetaOutput / KuzuGraph.meta() top-level return (plan said “if applicable”) — optional polish.

---

Expected breaking change (documented)

Agents must not use neighbors(method_id, out, ["ASYNC_CALLS"]) anymore; traverse DECLARES_PRODUCER then ASYNC_CALLS. Docs/skills updated; runtime hints deferred to PR-D as scoped.

---

Recommendation: Approve; address MCP description strings and pass6 producer_kind in this PR or a tiny immediate follow-up.