---
id: graph/queries
name: Implement graph query methods (topologicalOrder, ancestors, descendants, call graph queries)
status: completed
depends_on:
  - graph/flowgraph-class
scope: moderate
risk: low
impact: component
level: implementation
---

## Description

Implement the query methods on FlowGraph that delegate to graphology and graphology-dag, plus the call-graph-specific observability queries.

## Acceptance Criteria

- [ ] `topologicalOrder(): string[]` — delegates to `graphology-dag.topologicalSort`, throws `CycleError` if cycles exist (should never happen after validated construction)
- [ ] `hasCycles(): boolean` — delegates to `graphology-dag.hasCycle`
- [ ] `findCycles(): string[][]` — delegates to graphology cycle detection (debugging)
- [ ] `ancestors(nodeId): string[]` — delegates to `graphology-dag.ancestors`
- [ ] `descendants(nodeId): string[]` — delegates to `graphology-dag.descendants`
- [ ] `predecessors(nodeId): string[]` — delegates to `graph.inNeighbors`
- [ ] `successors(nodeId): string[]` — delegates to `graph.outNeighbors`
- [ ] `reachableFrom(nodeIds): Set<string>` — custom BFS/DFS traversal from starting nodes
- [ ] Call graph queries: `filterByStatus(status): string[]`, `getRoots(): string[]`, `children(requestId): string[]`, `duration(requestId): number`, `lineage(requestId): string[]`
- [ ] `filterByStatus`: O(n) filter over `forEachNode()` — documented as sufficient for expected sizes
- [ ] `getRoots()`: returns nodes with `parentRequestId === undefined`
- [ ] `lineage()`: ancestor chain from root to target
- [ ] Unit tests for each query method with known graph structures

## References

- docs/architecture/flowgraph-api.md — query methods, call graph queries
- docs/architecture/operation-graph.md — query delegation to graphology-dag
- docs/architecture/call-graph.md — observability queries

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion