feat: add configurable evaluation exposure deduplication

[abelonogov-ld]

Summary

Apps that evaluate a flag on every render or inside a loop invoke their hooks for each call, even when the evaluation resolves to the same result every time. This lets a hook ask for a dedupe window so those redundant evaluation series are collapsed.

Only hooks are affected. Analytics events are untouched — feature, debug, and summary events are still recorded for every evaluation, so the evaluation counts LaunchDarkly reports for your flags do not change.

Deduplication is opt-in per hook, and there is no client-wide setting. A hook observes every evaluation until it returns a deduper, so an audit hook can see everything while an observability hook on the same client keeps a long window:

class MetricsHook: Hook {
    // Told about every evaluation (default: evaluationExposureDeduper == nil).
}

class ObservabilityHook: Hook {
    let evaluationExposureDeduper: EvaluationExposureDeduper? =
        EvaluationExposureDeduper(window: 30, maxSize: 5_000)
}

config.hooks = [MetricsHook(), ObservabilityHook()]

Behavior when a hook carries a window:

• The hook observes an evaluation at most once per window per unique result, keyed on flag key, variation, event version, experiment status, and the fully qualified context key.
• Suppression covers the whole evaluation series: a suppressed evaluation invokes neither beforeEvaluation nor afterEvaluation, so a hook that pairs its stages never sees an unmatched before.
• Each hook is deduplicated independently, so one hook observing an evaluation never suppresses it for another.
• identify clears every hook's deduper, even when the context is unchanged, so identify stays a reliable way for an app to mark a new phase of a session.

This started as a port of flagExposureDedupeWindowMillis from the Web Observability SDK, moved down to the flag SDK level. Companion PR for the Android SDK: launchdarkly/android-client-sdk#380. Sample app: launchdarkly/hello-ios#73.

What changed since the first revision

Reviewers who read an earlier description will find three design decisions reversed:

1. Deduplication moved off the event pipeline and onto hooks. It originally suppressed the feature event and the summary event together, which reduced volume the most but also dropped the evaluation counts LaunchDarkly reports. The telemetry the feature is really aimed at is produced by hooks, so gating hooks alone gets the volume reduction without touching what LaunchDarkly reports.
2. The window became a per-hook policy rather than one client-wide setting. A single window forces unrelated hooks to share a deduplication policy, which does not hold up once an app registers hooks with different purposes alongside the observability plugin's.
3. The LDConfig options are gone entirely, and the default is now no deduplication. Returning nil (or .disabled) means the hook sees every evaluation. Deduplication is a property of what a hook does with an evaluation, so the hook is now the only place that decides.

EvaluationExposureDeduper.disabled is therefore equivalent to returning nil. It stays because returning it states the intent explicitly, and because the SDK recognizes it by identity to skip building exposure keys.

Notes for reviewers

• The decision is made before the series opens, not after the evaluation completes. The mobile observability plugins start a span in beforeEvaluation and end it in afterEvaluation. Suppressing only the after stage would leave those spans orphaned. So hooks are selected up front using the stored flag to identify the exposure.
• Experiment status is its own key component. versionForEvents prefers flagVersion, which only moves when the flag itself changes, so a prerequisite flipping can move an evaluation into or out of an experiment while it lands on the same variation of the same flag version.
• Two hooks given the same deduper instance share its window, so give each hook its own instance unless you intend that.
• EvaluationExposureDeduper is public and open for subclassing. Cap default is defaultMaxSize (2000). Windows are TimeInterval in seconds, matching every other duration on this SDK.
• Hooks are snapshotted into RegisteredHook at client start so the resolved deduper is fixed for the client's lifetime.
• Sample app PR demonstrates two independently-deduplicated counting hooks: feat: demonstrate per-hook evaluation exposure deduplication hello-ios#73

Known limitation

The key has no notion of where a flag was read, so two evaluations from different code paths that land on the same variation collapse into one. A hook that needs per-operation fidelity can subclass the deduper and fold ambient scope (e.g. active span id) into the key.

Test plan

• EvaluationExposureDeduperSpec — unit coverage for disabled, suppression, window expiry, keys, reset, eviction
• Hook / client specs covering per-hook policies, identify reset, and events still firing when hooks are suppressed
• xcodebuild test / swift test green on the branch
• hello-ios sample builds against this branch (feat: demonstrate per-hook evaluation exposure deduplication hello-ios#73)

---

Note

Overview
Opt-in hook deduplication collapses repeated evaluations that resolve to the same exposure, so hooks (e.g. observability) are not invoked on every render or loop iteration. Analytics events are unchanged—only the hook evaluation series is gated.

Hooks can expose evaluationExposureDeduper (default nil = observe every evaluation). The SDK pairs each hook with a deduper at client init via RegisteredHook, tracks environmentName on multi-environment clients, and filters hooks before beforeEvaluation/afterEvaluation using an EvaluationExposureKey built from the stored flag (variation, event version, experiment status, context key). Suppressed evaluations skip the entire hook series so paired spans are not left open.

EvaluationExposureDeduper implements a configurable time window (default 10 minutes), per-flag last-result tracking, thread-safe shouldRecord/reset, and .disabled. identify resets all hook dedupers, including when the context is unchanged, so apps can mark a new session phase.

FeatureFlag gains isInExperiment for exposure identity. Extensive unit and integration tests cover deduper behavior, multi-hook policies, shared vs separate deduper instances, and secondary environments.

^{Reviewed by Cursor Bugbot for commit c322334. 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 2 potential issues.

^{❌ 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 e407016. Configure here.}

[cursor]

Hot-path hook array allocations

Medium Severity

hooksForEvaluation checks hooks.isEmpty and hooks.count, but hooks is now a computed map over registeredHooks. Every flag evaluation allocates at least one new array, and evaluations with hooks allocate two, on the SDK’s hottest path. The same stored property check previously avoided that cost.

Additional Locations (1)

• LaunchDarkly/LaunchDarkly/LDClient.swift#L286-L287

 

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

[cursor]

Wrong-type eval suppresses later hooks

Medium Severity

exposureKey is built from the stored flag before evaluation, including its variation and experiment fields. A WRONG_TYPE result still opens that window even though hooks observe a nil-variation error, so a later correctly typed evaluation of the same flag can be suppressed and never reach the hook.

Additional Locations (1)

• LaunchDarkly/LaunchDarkly/LDClientVariation.swift#L166-L185

 

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