fix: add defensive cycle guard to prerequisite evaluation

[tanderson-ld]

Summary

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

Tracker: SDK-2705. 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.

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. This PR extends the same defensive posture to the Flutter client SDK.

The fix

_variationInternal now threads a lazily-allocated Set<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 Set<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(flagKey) before recursing, ancestors.remove(flagKey) in a finally — the invariant "the set contains exactly the current path" holds even under early exits.
• 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 named parameter visited is added last, so all existing callers (the seven typed and untyped variation / variationDetail entry points) 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

• packages/common_client/lib/src/ld_common_client.dart — cycle guard in _variationInternal.
• packages/common_client/test/ld_dart_client_test.dart — 5 new tests under the existing given mock flag data with prerequisites group: 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).
• apps/flutter_client_contract_test_service/bin/contract_test_service.dart — declares client-prereq-cycle-detection so the matching contract tests in sdk-test-harness v2.38.0+ activate for this SDK.

Verification

• Unit tests: dart test test/ld_dart_client_test.dart → 31 tests, 0 failures. The 5 new cycle-detection tests all pass.

Changelog

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

---

Note

Medium Risk
Changes flag evaluation’s prerequisite recursion and analytics event ordering, but behavior is narrowly scoped to abnormal cyclic graphs and is covered by new unit and contract tests.

Overview
Adds defensive cycle detection to the recursive prerequisite walk in LDCommonClient._variationInternal, matching server SDK behavior when a cyclic prereq graph appears (e.g. stale persisted state).

The walker threads a lazily allocated ancestor set (current path only): before recursing into a prerequisite it skips edges whose key is already on the path, then continues with other prerequisites. The evaluated flag still returns its cached value and reason; only the ancillary prereq event walk is affected. Diamond graphs still emit one prereq event per independent path (not treated as cycles).

Adds five unit tests (self-loop, 2- and 3-cycles, diamond regression) and advertises the client-prereq-cycle-detection contract-test capability on the Flutter contract test service.

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