trace tool: v2 enhancements — bidirectional traversal, richer heuristics, configurable ranking

[HumanBean17]

Summary

Follow-up enhancements for the trace MCP tool, deferred from the v1 proposal (PR #234). These are not needed for initial implementation but should be revisited once we have production usage data.

Enhancements

1. Bidirectional traversal

The v1 trace is unidirectional ("in" or "out"), matching the neighbors contract. Some impact analysis questions benefit from mixed traversal (e.g., follow CALLS out, then INJECTS in to see what dependencies a path pulls in).

Decision for v1: Agent issues two trace calls. No "both" direction.

When to revisit: If production telemetry shows the two-call pattern is a top-3 trace usage pattern (e.g., >20% of trace calls are paired in+out on the same seed).

Open design question: A "both" direction requires specifying which edge types follow which direction — this could turn the signature into a mini query language. A simpler alternative: accept direction: list[Literal["in", "out"]] with a per-direction edge_types mapping. Needs a proposal.

2. Richer collapse_trivial heuristic

The v1 heuristic collapses chains where an intermediate node has exactly 1 in-edge and 1 out-edge in the result set, and its role is OTHER or declaring-class role is SERVICE/COMPONENT.

Decision for v1: Degree-1 heuristic, no configurability.

When to revisit: If production shows (a) false positives — collapsing chains that carry semantic meaning, or (b) false negatives — wrapper/delegate chains that don't meet the degree-1 threshold but should still collapse.

Possible v2 parameters:

• trivial_chain_min_length: minimum chain length to collapse (default 2)
• trivial_roles: configurable set of roles considered trivial (instead of hardcoded OTHER)
• Integration with cyclomatic complexity or method body size (if that metadata becomes available)

3. Configurable path ranking

The v1 ranking is fixed: leaf role priority > min path confidence > path length (shorter first).

Decision for v1: Fixed ranking, no rank_by parameter.

When to revisit: If agents consistently re-rank paths client-side (observable via tool call patterns — trace followed by manual filtering).

Possible v2 parameter:

rank_by: Literal["default", "shortest_first", "highest_confidence_first"] = "default"

4. Configurable fan_out_cap ranking

The v1 ranking sorts by confidence, breaks ties by role priority.

Decision for v1: Confidence primary, role tiebreaker, no parameter.

When to revisit: If production shows high-confidence but low-signal edges consistently dominate the top-K (e.g., utility/logging methods with high confidence because they're always resolved).

5. Nested tree output field

The v1 output uses a flat edges list with parent_edge_id for lightweight tree reconstruction. Each edge has a nullable parent_edge_id referencing the incoming edge to its from_id. This lets agents reconstruct the call tree without duplicating node payloads, but requires client-side processing.

A full nested tree field was proposed during review (PR #234 comment). The nested tree would give agents a ready-made hierarchical view:

"tree": {
  "id": "route:com.example.orders.OrderController.createOrder",
  "children": [
    {
      "id": "sym:com.example.orders.OrderController#createOrder",
      "edge_type": "EXPOSES",
      "children": [
        {
          "id": "sym:com.example.orders.OrderServiceImpl#createOrder",
          "edge_type": "CALLS",
          "children": [...]
        }
      ]
    }
  ]
}

Decision for v1: parent_edge_id on TraceEdge only. No nested tree.

Why deferred: The nested tree duplicates structural data already expressible from flat edges + parent_edge_id. For large traces (200+ nodes), the nested JSON adds significant token cost competing with the agent's context window — the exact problem trace exists to solve. Additionally, collapsing (collapsed: true edges with collapsed_intermediates) and cross-service boundaries (cross_service_boundary: true leaf nodes) make the tree structure more complex to consume correctly.

When to revisit: If production shows agents routinely rebuild the tree from parent_edge_id references, or if agents fail to understand call hierarchy from the flat list. This would indicate the lightweight approach is insufficient and the full tree is worth the token cost.

Possible v2 approaches:

• Add include_tree: bool = False parameter (opt-in to avoid token cost by default)
• Compute tree from existing edges — no new traversal, just output formatting
• Tree nodes reference IDs in nodes dict (no NodeRef duplication)
• Collapsed edges become tree nodes with collapsed: true and children from collapsed_intermediates
• Cross-service boundary nodes become leaves with cross_service_boundary: true

6. Cross-service: seamless multi-service traversal

The v1 cross-service design uses boundary-stop: BFS records the cross-service edge with full attributes and the downstream Route/Producer node, but does not follow into the downstream service. The agent issues a separate trace call if it wants to continue.

Decision for v1: Boundary-stop. Agent decides per-service.

When to revisit: If production shows agents always follow cross-service boundaries (every trace with cross-service edges is followed by another trace into the downstream service), seamless traversal may be worth the added complexity and context cost.

Open design questions:

• How to handle hop budget across service boundaries (scaffolding edges consume 2 hops per boundary crossing)
• How to represent multi-service paths in the paths array (currently paths are single-service)
• How to cap total output size when traversing across 2+ services
• Whether to require explicit opt-in (cross_service_depth: int = 0 where 0 = boundary-stop, N = follow N services deep)

Acceptance criteria

Each enhancement needs its own proposal under propose/active/ before implementation. The proposal should include production evidence justifying the change.

Dependencies

• Requires trace v1 to be shipped and in production use
• Requires telemetry/observability on trace usage patterns (at minimum: call counts, depth distribution, pruning stats)

[HumanBean17]

Additional trade-offs from second review (PR #234)

Tracking specific v1 decisions that may need revisiting:

fan_out_cap: relative-to-source role priority

The v1 uses a static role tiebreaker (CONTROLLER > SERVICE > REPOSITORY > CLIENT > OTHER). Review raised that this can be counterintuitive: from a SERVICE node, a CONTROLLER callee ties ahead of a REPOSITORY callee at equal confidence. In practice you'd usually want the repository.

v2 option: Make role priority relative to the source node's role. A SERVICE node would prioritize REPOSITORY callees, a CONTROLLER node would prioritize SERVICE callees, etc. Requires defining a role affinity matrix. This is more complex but produces more intuitive results for the dominant traversal patterns.

Trigger to revisit: If agents consistently re-rank fan_out_cap results client-side, or if production telemetry shows the static tiebreaker produces suboptimal paths in >10% of capped traces.

Post-pruning budget option

The v1 max_nodes_discovered counts pre-pruning (intentional — it's a compute guardrail). Review noted that aggressive prune_roles can result in fewer output nodes for the same budget: discover 500, prune 450, return 50.

v2 option: Add a secondary min_result_nodes parameter that guarantees a minimum output size by allowing the budget to stretch if pruning is too aggressive. Or flip to a post-pruning budget (less desirable — defeats the compute guardrail purpose, but worth evaluating if users report undersized results).

Trigger to revisit: If users report that trace with aggressive prune_roles consistently returns too few nodes to be useful.

[HumanBean17]

Additional follow-up from proposal update: agent guidance for trace

The proposal now includes a "Agent tool selection: trace vs neighbors" section with specific heuristics. The experimental validation (§Experimental validation) requires that in ≥70% of multi-hop questions, the agent picks trace over a neighbors loop without manual prompting. If this criterion fails, the heuristics need iteration.

Potential v2 guidance improvements

Neighbors loop detection (client-side): The proposal notes that session-level call tracking (detecting 3+ consecutive neighbors calls with the same edge type) may need to be a client-side hint in the skill rather than server-side. v2 should evaluate whether the MCP server can track per-session call patterns (requires stateful server or session tokens) vs keeping this purely in the skill document.

Adaptive escalation: If the experimental validation shows that agents don't naturally escalate from neighbors to trace when drowning, v2 may need a stronger signal — e.g., the neighbors response itself includes a "hint: consider trace for multi-hop traversal" when result count exceeds a threshold. This is different from the current hint (which is in hints_structured) because it would be in the main response body.

Per-codebase tuning: The prune_roles defaults and fan_out_cap that work on one codebase may not work on another. v2 could include per-codebase tuning guidance in the skill that adapts based on java-codebase-rag meta output (e.g., if the codebase has few DTOs, prune_roles=["DTO"] is wasted).

[HumanBean17]

Design change: cross-service traversal redesign

The proposal was redesigned: cross-service traversal now stops at service boundaries instead of following seamlessly into downstream services. BFS records cross_service_boundary=True on the edge and includes the downstream Route in the result, but does not traverse further.

What this means for v2 follow-ups

The original issue mentioned "seamless traversal" as a v2 enhancement. That's no longer the goal. Instead, the v2 follow-ups for cross-service are:

1. Cross-service multi-hop via chained trace calls: If the agent wants to trace across multiple services, it issues sequential trace calls. v2 could offer a convenience — e.g., the server detects the agent's pattern and offers a pre-computed multi-service trace as an optimization. But the default remains boundary-stop.

2. Cross-service boundary detail enrichment: The boundary signal currently includes the downstream Route's NodeRef. v2 could enrich it further — e.g., include the Route's edge_summary (handler method FQN, HTTP method, path) directly in the cross-service edge attributes, so the agent doesn't need to describe the Route before deciding whether to trace into it.

3. Bidirectional cross-service tracing: Currently, trace only follows outbound cross-service edges (CALLS out -> HTTP_CALLS out to Route). v2 could support inbound cross-service tracing (from a Route, follow HTTP_CALLS in to Client, then CALLS in to callers in the upstream service). This is related to the bidirectional traversal item already tracked here.

[HumanBean17]

Proposal scoping update

1. Cross-service: seamless multi-service traversal — Done

Item #6 is already shipped in 3434843 (PR #256, cross_service: bool flag). Removing from scope.

2. Nested tree output — Rework, not additive

Decision: replace the current flat edges + paths output with a nested tree field as the default (and only) format. No output_format switch, no additive field.

Why this is safe:

• BFS visits each node once (visited set), so the result is already a tree — not a DAG. Nested format maps 1:1.
• hop → implicit in nesting depth.
• parent_edge_id → implicit in nesting.
• Edge attrs, collapsed/collapsed_intermediates, cross_service_boundary → attributes on tree nodes.
• nodes dict stays as a deduplication table; tree nodes reference by ID.

Token savings: the current paths array is the biggest context cost — it copies full TraceEdge objects across up to 20 ranked paths, with shared edges serialized repeatedly. Dropping paths + edges in favor of tree removes this duplication entirely.

Mitigating ranked path list loss

Dropping paths removes the curated "top N important root-to-leaf paths" signal. To preserve this ranking without the duplication, add a lightweight ranked_leaves field:

"ranked_leaves": [
  {"id": "sym:com.example.OrderServiceImpl#createOrder", "score": 4.8},
  {"id": "sym:com.example.PaymentGateway#process", "score": 3.2}
]

This is just leaf node IDs sorted by the existing path ranking heuristic (leaf role priority → min confidence → path length), capped at max_paths. No edge duplication, minimal token cost (~2 fields per leaf), and agents still get a "start here" signal for which branches matter most.