feat(schema): HTTP_CALLS originates from Client, not Symbol

[HumanBean17]

Summary

• Flips HTTP_CALLS to Client → Route in EDGE_SCHEMA, Kuzu DDL, pass5/6 emission (HttpCallRow.client_id), and graph write Cypher.
• Replaces CallerInfo with RouteCaller in kuzu_queries.py; reshapes find_route_callers, trace_request_flow inbound (HTTP two-hop), and impact-analysis HTTP expansion (three-hop via DECLARES_CLIENT).
• pr_analysis.py: cross-service route reachability uses DECLARES_CLIENT + HTTP_CALLS (async leg unchanged until PR-C).
• HTTP doc sweep: README.md, docs/AGENT-GUIDE.md, docs/skills/java-codebase-explore.md; regenerated docs/EDGE-NAVIGATION.md.
• All Tests for PR-B from plans/PLAN-SCHEMA-V2.md added/updated (verbatim names).

Re-index

Graphs built before this PR need a full java-codebase-rag reprocess (ontology still 14; no second bump).

grep -rn 'HTTP_CALLS' --include='*.py' --include='*.md' . accounting

Production / shipped (updated in this PR):

Area	Files	Account
Schema	java_ontology.py	EDGE_SCHEMA["HTTP_CALLS"] src=Client, post-flip typical_traversals
Builder	build_ast_graph.py	DDL FROM Client TO Route; _CREATE_HTTP_CALL from Client; HttpCallRow.client_id; pass6 resolves via clients_by_id
Queries	kuzu_queries.py	RouteCaller; two-hop find_route_callers / inbound trace_request_flow; impact HTTP three-hop
PR analysis	pr_analysis.py	Two-hop HTTP cross-service caller count
MCP allowlists	mcp_v2.py, server.py	Edge label unchanged (neighbors still valid); no Symbol→Route Cypher
Docs	README.md, docs/AGENT-GUIDE.md, docs/skills/java-codebase-explore.md, docs/EDGE-NAVIGATION.md (generated)	HTTP traversal text + table

Tests (updated assertions to Client-anchored edges): tests/test_call_edges_e2e.py, tests/test_kuzu_queries.py, tests/test_pr_analysis.py, tests/test_client_hint_recovery.py, tests/test_schema_consistency.py, tests/test_brownfield_clients.py, tests/test_mcp_v2.py, tests/test_mcp_hints.py, tests/test_mcp_v2_compose.py, tests/test_feign_not_exposer.py, tests/test_cross_service_resolution_flag.py.

Unchanged / reference only: ast_java.py (comment), CODEBASE_REQUIREMENTS.md, docs/MANUAL-VERIFICATION-CHECKLIST.md, docs/PROPOSES-ORDER.md, .cursor/skills/propose/examples.md, propose/**, plans/** (historical / forward-looking).

Out of scope (confirmed)

• No Producer / DECLARES_PRODUCER / ASYNC_CALLS flip (PR-C)
• No mcp_hints.py / hints v3 (PR-D)
• No second ontology bump

Test plan

• .venv/bin/ruff check .
• .venv/bin/python -m pytest tests/test_call_edges_e2e.py tests/test_kuzu_queries.py tests/test_pr_analysis.py tests/test_client_hint_recovery.py tests/test_schema_consistency.py tests/test_brownfield_clients.py tests/test_mcp_v2_compose.py::test_describe_client_edge_summary_includes_http_calls_out -v (83 passed)
• .venv/bin/python scripts/generate_edge_navigation.py --check
• .venv/bin/python -m pytest tests -v (522 passed; 18 CLI tests fail locally — system java-codebase-rag not installed in editable venv path)

Made with Cursor

[HumanBean17]

Critical review (PR-B / SCHEMA-V2)

Verdict: Request changes on one item; the core HTTP flip looks correct.

---

What’s solid

• Builder: DDL FROM Client TO Route, HttpCallRow.client_id, dedup (cid, rid), write Cypher, pass6 via clients_by_id → member_id — internally consistent. Pass5 already pairs Client + DECLARES_CLIENT before HTTP edges.
• Ontology + docs: EDGE_SCHEMA, EDGE-NAVIGATION.md, README re-index callout, agent guides — post-flip two-hop pattern is aligned.
• Kuzu: Splitting HTTP_CALLS|ASYNC_CALLS unions into separate HTTP (three-hop) vs async (Symbol→Route) queries avoids binder pitfalls.
• RouteCaller HTTP branch: Correct caller_node_id = Client, declaring_symbol_id back-ref, target_service / raw_uri.
• Scope: No second ontology bump, no Producer/ASYNC flip, CallerInfo fully removed from Python.

---

Must fix

Async callers labeled caller_node_kind="client"

In find_route_callers and trace_request_flow, async still traverses Symbol-[ASYNC_CALLS]->Route, but both set caller_node_kind="client" (and trace_request_flow uses 'client' AS caller_node_kind while caller is a Symbol).

That breaks the PR-B contract (“return the caller-side node”) and will mislead consumers until PR-C.

Suggested fix (pick one for this PR):

• Do not emit async rows in RouteCaller / inbound trace until PR-C wires Producer, or
• Document an interim shape clearly — but do not label Symbol-backed async callers as "client".

PR-C should own caller_node_kind="producer"; PR-B should not lie with "client".

---

Should fix / plan gaps

1. Impact-analysis expansion — Plan Decision 24 / PR-B DoD: trace_flow cross-service HTTP should surface bridging Client id. Cypher is three-hop but RETURN is still only handler n. Consider c.id AS caller_client_id in RETURN, or call out deferral to PR-C in the PR body.

2. test_pr_analysis_changed_methods_finds_routes_via_declares_client — Only asserts the graph has cross-service HTTP edges; never runs compute_risk or the updated pr_analysis.py queries. UC9 is still mostly mocked. A small integration test on cross_service_callers_count would help.

3. mcp_v2.py / server.py untouched — Fine if v2 no longer exposes find_route_callers; worth a one-liner in the PR. Note: neighbors(route, in, ["HTTP_CALLS"]) now returns Client ids; test_neighbors_route_in_http_calls_returns_callers still mocks a Symbol caller (pre-flip mental model).

---

Behavioral notes (non-blocking)

• pr_analysis: HTTP leg now counts Client ids, not declaring symbols — UC5-correct but changes risk-score semantics vs pre-flip; worth documenting.
• test_call_edges_method_two_http_clients_two_routes: Asserts distinct clients, not distinct routes — name is slightly misleading.
• Re-index: Required; old Symbol→Route HTTP_CALLS graphs will break until full reprocess.

---

PR-B DoD snapshot

Item	Status
No Symbol-[HTTP_CALLS]->Route in production Python	✅
CallerInfo → RouteCaller	⚠️ async caller_node_kind wrong
Named PR-B tests	Mostly ✅; UC9 integration thin
HTTP doc sweep + EDGE-NAVIGATION	✅
Impact expansion surfaces caller node id	❌
mcp_v2/server alignment	N/A (note in PR)

Happy to re-review after the async caller_node_kind fix.