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. (e.g. root R with R→A→D and R→B→C→D
   processed D before C, even though C hands off to D.)
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
   initialExecutionContext.

What changed

packages/sdk/server-ai — AgentGraphDefinition.ts 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 context = initialExecutionContext plus only
  that node's true dependency results (transitive ancestors forward / descendants reverse). Results
  are kept in a private map keyed by node; unrelated branches and self-loops 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) via _reachableAndDiscovery, used only for tie-breaks — so order never depends on object
  key enumeration.

type TraversalFn = (node: AgentGraphNode, executionContext: Record<string, unknown>) => unknown;

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

• Canonical cross-SDK vectors G1–G6 (+G2b) assert 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; self-loop excluded from its own context; deterministic across
  runs.

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.

---

Note

High Risk
Marked breaking (fix!): orchestration order and what each node sees in executionContext change for convergent paths, cycles, and parallel branches—apps that relied on old BFS order or a global context map may behave differently.

Overview
Breaking change: AgentGraphDefinition.traverse and reverseTraverse no longer use plain BFS with one shared, growing executionContext. They now use topological ordering (Kahn-style over in-/out-degree, with BFS discovery order for ties and cycle breaks) so convergent nodes run only after all predecessors or descendants, and pure cycles are fully visited on reverse instead of being a no-op.

Each callback gets a fresh context: initialExecutionContext plus only that node’s transitive predecessors (forward) or descendants (reverse)—parallel branches no longer leak into each other, and the caller’s initial map is not mutated; results live in a private map keyed by node.

Tests add shared G1–G6 / G2b vectors for exact visit order and context keys; the create-agent-graph README describes topological vs reverse-topological traversal.

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

[github-actions]

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 26360 bytes
Compressed size limit: 29000
Uncompressed size: 129188 bytes

[github-actions]

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 39108 bytes
Compressed size limit: 39300
Uncompressed size: 213642 bytes

[github-actions]

@launchdarkly/browser size report
This is the brotli compressed size of the ESM build.
Compressed size: 179691 bytes
Compressed size limit: 200000
Uncompressed size: 831704 bytes

[github-actions]

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 32077 bytes
Compressed size limit: 34000
Uncompressed size: 114525 bytes

[tanderson-ld]

Do you have any performance requirements wrt throughput or memory allocation delays? May be worth a quick benchmark to see if your expected cases are well behaved.