fix: add defensive cycle guard to prerequisite evaluation

[tanderson-ld]

Summary

Adds defensive cycle detection to the recursive prerequisite walk in LdClient.EvaluateInternal, bringing the .NET client SDK's behavior into line with the LaunchDarkly server SDK evaluators.

Tracker: SDK-2708. Parent: SDK-2695. Spec change: sdk-specs#246 (CSPE 1.2.5, 1.2.5.1, 1.2.5.2). Contract-test coverage: sdk-test-harness#384 (merged in v2.38.0). Companion PRs: android-client-sdk#377, ios-client-sdk#512, js-core#1816, flutter-client-sdk#329.

Background

The LaunchDarkly service validates prerequisite graphs on every mutation and rejects any change that would produce a cycle, so under normal operation the SDK does not see a cyclic prerequisite graph. Server-side SDK evaluators nonetheless carry defensive cycle detection for exceptional cases — for example, delivery of updates out of order or a persisted state loaded from disk that predates a subsequent correction. Note that the .NET server SDK evaluator already carries this guard (PrereqFlagKeyStack in Evaluator.cs); this PR extends the same posture to the client SDK.

The fix

EvaluateInternal<T> now threads a lazily-allocated HashSet<string> through the recursion carrying the flag keys on the current evaluation path. Before descending into a prerequisite, the walker checks whether that key is already on the path; if so, it skips that edge and continues with remaining prerequisites at the same level.

• Lazy allocation: variation calls on prereq-less flags (the common case) allocate zero collections. The HashSet<string> is created only when the walker descends into a prerequisite for the first time in a call, then reused for the rest of the walk.
• Mutable Add / finally Remove: no per-descent copy. ancestors.Add(featureKey) before recursing, ancestors.Remove(featureKey) in a finally — the invariant "the set contains exactly the current path" holds even under exceptions.
• Ancestor-set (current-path) semantics — this is deliberate. A prerequisite reached via multiple non-cyclic paths (a diamond A -> [B, C], B -> [D], C -> [D]) is not a cycle; each path should emit its own prerequisite event. A global visited-set would silently drop the second event; the ancestor-set pattern correctly emits D twice. There is a unit test guarding this.

The optional trailing parameter HashSet<string> visited = null is added to EvaluateInternal<T>, so all existing callers (the public BoolVariation / IntVariation / StringVariation / DoubleVariation / JsonVariation and their *Detail counterparts) work unchanged.

Caller-visible behavior on a cycle

The requested flag returns its cached value and reason unchanged. A client-side prerequisite cycle is not surfaced as MALFORMED_FLAG and does not fall back to the caller-provided default value. This differs from server-side behavior — the client already holds an authoritative pre-evaluated result from the server; only the ancillary event walk is affected by the cycle.

Files changed

• pkgs/sdk/client/src/LdClient.cs — cycle guard in EvaluateInternal<T>.
• pkgs/sdk/client/test/LaunchDarkly.ClientSdk.Tests/LdClientEventTests.cs — 5 new xUnit tests: self-loop, two-cycle (evaluating each end), three-cycle, and a non-cyclic diamond that asserts the shared descendant emits an event for each path (the ancestor-set regression fence).
• pkgs/sdk/client/contract-tests/TestService.cs — declares client-prereq-cycle-detection so the matching contract tests in sdk-test-harness v2.38.0+ activate for this SDK.

Verification

• Unit tests: dotnet test -f net8.0 --filter "Prerequisite|Cycle|Diamond" → 6 passed, 0 failures (the original prereq event test plus 5 new cycle-detection tests).

Changelog

Updated prerequisite evaluation event emission to match server SDK behavior for cyclic prerequisite graphs.

---

Note

Medium Risk
Touches core flag evaluation and analytics event emission for prerequisite walks; behavior change is defensive but affects event ordering/counts on malformed graphs.

Overview
Adds defensive cycle detection to the recursive prerequisite walk in LdClient.EvaluateInternal, aligning client SDK behavior with server evaluators and sdk-spec CSPE 1.2.5.

Before descending into each prerequisite, the walker tracks flag keys on the current path in a lazily allocated HashSet<string> (add before recurse, remove in finally). If a prerequisite key is already on that path, that edge is skipped; the requested flag still returns its cached value and reason unchanged.

Ancestor-set semantics (not a global visited set) preserve correct analytics for diamond graphs: a shared prerequisite reached via separate branches still emits one evaluation event per path.

Contract tests declare capability client-prereq-cycle-detection. Five xUnit tests cover self-loops, 2- and 3-cycles, and the diamond regression case.

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