Implement orbit-graph trace query (command handler call tree)

[danieljhkim]

Task

ORB-00317 — Implement orbit-graph trace query (command handler call tree)

Description

Problem

GRAPH_SPEC.md §9.6 defines trace: structural feature expansion. Resolves a command name to its handler symbol via commands.handler_symbol, then BFS over callees with depth 5. Returns the call tree as nested JSON. Capped at 200 visited nodes per spec §9.6 ('depth 5 with branching factor 5 is otherwise about 3k nodes worst-case').

Why It Matters

trace is the 'show me everything this command does' query — useful for code review, onboarding, and refactor planning when an agent needs to understand a feature's surface area without reading every file. The cap means even sprawling commands return bounded results; agents re-trace from a sub-handler if more depth is needed.

Constraints / Notes

• Signature per GRAPH_SPEC.md §13: the method takes a command name (string) and a depth (u8) and returns a TraceResult or GraphError.
• Default depth: 5.
• Resolution: look up the commands table row WHERE name matches, follow handler_symbol FK to its symbol row, BFS over Graph::callees from that symbol.
• Cap at 200 visited nodes regardless of depth, per GRAPH_SPEC.md §9.6. When the cap fires, TraceResult carries truncated=true and visited_nodes=200.
• Output is a tree (nested), not a flat list — this is the structural difference vs impact (P4.4). The tree shape matches the call hierarchy starting from the handler.
• Unknown command name returns Ok with an empty TraceResult — no Err, no panic.
• Calls self.ensure_synced at entry per ORB-00312.
• Performance: same envelope as impact (BFS over similar node counts).
• 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.5. Depends on ORB-00314 (P4.3, callees). Runs in parallel with P4.4. Last task of Phase 4.

Acceptance Criteria

• Graph::trace method implemented; takes command name and depth, returns TraceResult with nested-tree shape
• Default depth = 5
• Resolution path: look up commands WHERE name = ? then follow handler_symbol to a Graph::callees BFS from that symbol
• 200-node cap enforced regardless of depth; TraceResult carries truncated as bool and visited_nodes as usize
• Output is a tree (nested), NOT a flat list — distinct from impact which is flat by distance
• Unknown command name returns Ok with an empty TraceResult (no error, no panic)
• Calls self.ensure_synced at entry per the P3.4 contract
• Tests: trace a synthetic command with a 3-level call tree returns the full tree; trace with branching factor 5 depth 5 truncates at 200 visited nodes
• cargo test -p orbit-graph query::trace passes
• cargo clippy -p orbit-graph -- -D warnings passes

Execution Summary

Click to expand

Outcome: success

Changes:

• Implemented Graph::trace with ensure_synced-at-entry, command handler resolution through commands.handler_symbol, default depth 5 when depth is 0, bounded BFS over callees, nested TraceResult/TraceNode output, unknown-command empty results, and a 200-node truncation cap.
• Added focused trace query tests for default-depth three-level trees, branching-factor truncation at 200 nodes, unknown commands, and OnRead sync triggering.
• Updated the orbit-graph spec to document the concrete TraceResult/TraceNode JSON/API shape.

Assessment: The implementation is scoped to orbit-graph trace behavior and validated against the required targeted test and clippy commands plus ci-fast guardrails.

Validation:

• cargo test -p orbit-graph query::trace
• cargo clippy -p orbit-graph -- -D warnings
• make ci-fast

Validation

• Not reported

Branch Freshness

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