Implement orbit-graph impact query (BFS with confidence floor and 200-node cap)

[danieljhkim]

Task

ORB-00316 — Implement orbit-graph impact query (BFS with confidence floor and 200-node cap)

Description

Problem

GRAPH_SPEC.md §9.5 defines impact: BFS over the union of inbound refs (callers) and outbound callees, plus relations for impl-driven edges. Default depth 3. Default confidence floor same_module. Returns a flat list of touched symbols ordered by graph distance, capped at 200 visited nodes.

Why It Matters

impact is the blast-radius query agents run before edits: 'what does changing this symbol affect?' It composes refs (P4.2) for inbound edges and callees (P4.3) for outbound edges into a single graph traversal, so it lands after both. The 200-node cap is the contract for keeping response sizes within context-window budgets — agents that need more coverage split into narrower queries from sub-nodes.

Constraints / Notes

• Signature per GRAPH_SPEC.md §13: the method takes a Selector reference and a depth (u8) and returns an ImpactResult or GraphError.
• Default depth: 3. Caller may override but the 200-node cap always applies.
• Default confidence floor: same_module (matches the refs default — excludes only fuzzy_name).
• BFS over: inbound refs (call into Graph::refs with default RefOpts), outbound callees (call into Graph::callees), and relations (impl-driven edges from the relations table for the starting symbol and each frontier node).
• Cap at 200 visited nodes regardless of depth. When the cap fires, ImpactResult carries truncated=true and visited_nodes=200. Callers can split into narrower queries from sub-nodes if more coverage is needed.
• Output: flat list of touched symbols ordered by BFS distance, each entry carrying qualified_name, distance from origin, and the edge_kind that brought it in (so callers can reconstruct the traversal path).
• Calls self.ensure_synced at entry per ORB-00312.
• Performance per GRAPH_SPEC.md §12: under 50ms p95 at depth=3 over about 100 nodes.
• Errors translate at the crate boundary per docs/design-patterns/error_translation.md. Sibling tests per docs/design-patterns/test_layout.md.

Plan ID: P4.4. Depends on ORB-00315 (P4.2, refs) and ORB-00314 (P4.3, callees). Runs in parallel with P4.5.

Acceptance Criteria

• Graph::impact method implemented; returns ImpactResult
• BFS over the union of inbound refs (Graph::refs with same_module floor) and outbound callees (Graph::callees internally) plus relations (impl-driven edges)
• Default depth = 3; --depth N override respected up to the 200-node cap
• 200-node cap enforced regardless of depth; ImpactResult carries truncated as bool and visited_nodes as usize
• Default confidence floor is same_module (matches refs default — excludes only fuzzy_name)
• Output ordered by BFS distance; each entry includes qualified_name, distance (u8 or usize), and edge_kind from the prior hop
• Calls self.ensure_synced at entry per the P3.4 contract
• Tests: 5-node tree at depth=2 returns all 5; circular reference does not infinite-loop; 300-node synthetic graph at depth=10 returns exactly 200 with truncated=true
• Performance smoke prints actual ms for the 200-node-cap case (no hard gate; P6.2 owns gating)
• cargo test -p orbit-graph query::impact passes
• cargo clippy -p orbit-graph -- -D warnings passes

Execution Summary

Click to expand

Outcome: success

Changes:

• Implemented Graph::impact with an ensure_synced entry point and bounded BFS over inbound refs, outbound callee edges, and structural relations using the refs default same_module confidence floor.
• Added ImpactResult/ImpactEntry output fields for touched symbols, distance, prior-hop edge kind, visited_nodes, and truncated, with a 200-node cap and default depth constant of 3.
• Moved callees query internals into query::callees so Graph::callees behavior is preserved and impact can reuse the span-contained call lookup.
• Added query::impact tests for a 5-node depth-2 traversal, cycle handling, 300-node cap/truncation, ensure_synced behavior, and the 200-node-cap performance smoke print.

Assessment: Validated with cargo test -p orbit-graph query::impact, cargo test -p orbit-graph callees, cargo clippy -p orbit-graph -- -D warnings, and make ci-fast.

Validation

• Not reported

Branch Freshness

• Base ref: origin/agent-main
• Head ref: orbit/ORB-00316-6a13d019
• Behind base: 0
• Ahead of base: 1