fix!: Make AgentGraph traversal topological

[mattrmc1]

Summary

Makes AgentGraphDefinition traversal topological and gives each visitor a dependency-scoped
execution context, aligning the traversal behavior across the LaunchDarkly AI SDKs.

Previously traverse / reverseTraverse were plain BFS over a single shared, accumulating context
map. That had two problems:

1. Ordering: where branches of unequal length converge, the convergence node ran on first
   discovery — before all of its predecessors had run.
2. Context leakage & mutation: every callback saw the results of all previously-visited nodes
   (including unrelated parallel branches), and results were written back into the caller's context
   map.

What changed

lib/sdk/server-ai — AgentGraphDefinition.java only (no public API/signature changes):

• traverse now visits a node only after all of its reachable predecessors have been visited
  (Kahn over in-degree; the root is always released first). On cycles, the unvisited node with the
  lowest remaining in-degree is chosen next, ties broken by discovery order.
• reverseTraverse now visits a node only after all of its reachable descendants have been
  visited, so the root is visited last (Kahn over out-degree, root excluded from cycle-break
  selection). Pure cycles now visit every node instead of being a no-op.
• Scoped context: each callback receives a fresh map = the initial context plus only that node's
  true dependency results (transitive ancestors forward / descendants reverse). Dependencies are
  accumulated before the node is marked visited in both directions, so a self-loop node never
  includes itself; unrelated branches are excluded and the caller's map is never mutated. Cross-node
  data flows only through callback return values.
• Determinism: discovery order is the graph's BFS encounter order (root first, then declared edge
  order), used only for tie-breaks.

void traverse(BiFunction<AgentGraphNode, Map<String, Object>, Object> fn, Map<String, Object> ctx);

Behavior change (breaking)

Titled fix! because visit order and callback-context contents change for graphs with convergent
paths, cycles, or parallel branches. Simple linear graphs are unaffected. Cross-SDK parity with
JS/Python/.NET/Java.

Tests

• A data-driven test over the canonical cross-SDK vectors G1–G6 (+G2b) asserts exact visit
  order and exact context keys in both directions.
• Convergence runs the shared node last; pure cycle visits all nodes (root last); caller context not
  mutated; unrelated branches excluded; a dedicated self-loop test confirms a node is not in its own
  context; deterministic across runs. Redundant per-vector order-only tests were dropped in favor of
  the data-driven vector test.

Notes

• No manual CHANGELOG.md edit — release-please generates it from the conventional-commit title.
• Graph tracking / wire parsing unchanged; this PR is scoped to traversal + context.
• Minor follow-up (not required): the class-level Javadoc still says traversal is "BFS-based" — worth
  updating to "topological / dependency-order" so the docs match the new behavior.

---

Note

Overview
Replaces BFS traverse / reverseTraverse on AgentGraphDefinition with dependency-ordered walks (Kahn-style, cycle-safe, BFS discovery for tie-breaks). Convergence nodes run only after all predecessors (or descendants in reverse); pure cycles now visit every reachable node instead of effectively no-oping on reverse.

Breaking behavior: each visitor gets a fresh map—initial ctx plus only that node’s true dependency results (ancestors forward, descendants reverse). The caller’s ctx is not mutated with node outputs, and parallel-branch results no longer leak into unrelated callbacks. Self-loops exclude the node from its own context.

Tests add cross-SDK G1–G8 vectors for exact visit order and context keys, plus determinism, diamond graphs, and caller-context immutability checks.

^{Reviewed by Cursor Bugbot for commit 3c24de6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit da3503b. Configure here.}