traverseBFS: inner neighbor loop adds nodes without limit check, overshooting opts.limit

[inth3shadows]

File: src/graph/traversal.ts
Lines: 65 (outer while guard), 99–112 (inner for loop)

Defect: traverseBFS checks nodes.size < opts.limit only in the outer while condition (L65). The inner for loop (L99–112) calls nodes.set(nextNode.id, nextNode) at L110 unconditionally for every unvisited neighbor, with no per-add limit check. When a single node has more neighbors than the remaining capacity, all are added in one pass — the outer guard only prevents the next dequeue, not the current batch.

Failure trace:

• traverseBFS("A", { limit: 3 }): start node inserted before loop (nodes.size=1).
• Dequeue A: nodes.size=1 < 3 → enter loop. A has 5 neighbors [B,C,D,E,F].
• Inner for loop: nodes.set(B) (size=2), nodes.set(C) (size=3), nodes.set(D) (size=4), nodes.set(E) (size=5), nodes.set(F) (size=6) — all added, no limit check inside loop.
• Outer while: nodes.size=6 >= 3 → exit. Result has 6 nodes despite limit=3.

Expected fix:
Add a limit check inside the inner for loop, either as a break or a guard before nodes.set:

for (const adjEdge of adjacentEdges) {
  if (nodes.size >= opts.limit) break;   // ← add this
  const nextNodeId = …;
  if (visited.has(nextNodeId)) continue;
  …
  nodes.set(nextNode.id, nextNode);
  queue.push(…);
}

[inth3shadows]

---

Verification & metadata (added after filing)

Anchor: Introduced in cc6e7a5c (2026-01-18, the original graph-traversal implementation); present in every release through v1.1.6 and still on main @ 712a406. Not a recent regression.

These 5 issues are really 3 root defects:

• Depth guard returns before visited.add → getCallersRecursive/getCalleesRecursive: depth guard returns before visited.add, causing duplicate results #1086, getImpactRecursive: inconsistent visited vs nodes gate causes incoming edges to be silently dropped #1089
• Dedup gate also gates edge collection (an edge is dropped when its endpoint was already collected) → getImpactRecursive: inconsistent visited vs nodes gate causes incoming edges to be silently dropped #1089, traverseBFS: same target enqueued via two edges; second dequeue skips edge, producing incomplete edge set #1090
• limit checked once per stack frame, not per node added → traverseBFS: inner neighbor loop adds nodes without limit check, overshooting opts.limit #1087, dfsRecursive: nodes.set called before limit check in inner loop, overshooting opts.limit for all siblings #1088

Regression coverage belongs in __tests__/graph.test.ts.

Reproduced against the compiled dist/ build with the real GraphTraverser and a mock QueryBuilder (only getNodeById/getNodesByIds/get{In,Out}goingEdges).

traverseBFS('A', { limit: 3 })   // A has 5 neighbors
// Observed: 6 nodes returned (limit exceeded)

The outer while guards nodes.size < limit, but the inner neighbor loop calls nodes.set with no per-add check, so one high-degree node overshoots in a single pass.

[colbymchenry]

Fixed in 43a6fa6 (#1106). traverseBFS now checks the node budget per-add inside the neighbor loop, not just on the outer while — so a single high-degree node can no longer insert its whole fan-out and overshoot opts.limit. Regression test added in graph.test.ts. Thanks for the clear repro! Ships in the next release.