feat: add configurable evaluation exposure deduplication

[abelonogov-ld]

Summary

Opt-in deduplication of evaluation exposures for hooks. A hook is told about every evaluation until you wrap it, so nothing changes for existing hooks:

config.hooks = [
    MetricsHook(),                                      // every evaluation
    DedupingHook(ObservabilityHook()),                  // 10 minute window
    DedupingHook(TelemetryHook(), window: 60),
    DedupingHook(ExperimentHook(), deduper: myCustomDeduper)
]

New public API:

• HookDecorator — an open class conforming to Hook that forwards every stage to the hook it wraps, and reports that hook's metadata. Decorators stack in either order.
• DedupingHook — a decorator that suppresses an evaluation whose result the wrapped hook has just been told about. Wrap with a window, or with a deduper of your own.
• EvaluationExposureDeduper — the policy. The window is its only setting. Subclass it to decide differently; shouldRecord(key:now:) and reset() are the only members DedupingHook calls.
• EvaluationExposureKey — what identifies an evaluation result: environment name, flag key, variation, flag version, experiment status, and fully qualified context key.
• EvaluationSeriesContext.evaluationExposureKey — resolves that identity on demand, so an evaluation costs a flag lookup only when a hook asks for one.

The policy keeps one record per flag per environment, holding the result that flag last reported. The wrapped hook hears about the flag again as soon as the result changes, and once per window while it stays the same. Tracking the last result rather than every result seen means a flag flipping back and forth cannot hide its flips, and it bounds the records to the flags the environment serves.

The decision is taken in beforeEvaluation, before the series opens, so a suppressed evaluation reaches neither stage of the wrapped hook. Hooks pair their stages: the observability plugin starts a span in the before stage and ends it in the after one, so suppressing only the after stage would leave that span in its map to be evicted later and exported with a meaningless duration and no feature_flag event.

LDClient.identify clears what the wrapped hook has been told about, so the first evaluation of each flag afterwards always reaches it. Analytics events are untouched: feature, debug, and summary events are still recorded for every evaluation, so the evaluation counts LaunchDarkly reports for a flag do not change.

Describe alternatives you've considered

• A deduper declared on the Hook protocol. It was the first shape this took. It puts a policy on the protocol that every hook implementer has to think about, and it cannot be composed, so a hook that wanted deduplication plus anything else had nowhere to put the second behavior. The decorator gives both without touching Hook.
• Filtering only afterEvaluation. This is what the browser and React Native observability plugins do, and it is much less machinery: no exposure key before the evaluation, no resolver, no suppression marker in the series data. It is wrong here, because the mobile observability hook pairs its stages, as above.
• Deduplicating on every distinct exposure seen, rather than one record per flag. A flag that flips between two results would report neither flip after the first, and the set of remembered exposures grows with every result a flag has ever had.
• Date() for the window. A correction that moves the device clock backwards leaves every recorded time in the future, so those flags stay suppressed until real time catches up. Windows are measured against CLOCK_MONOTONIC_RAW, exposed as EvaluationExposureDeduper.monotonicNow(), which no correction reaches and which, unlike mach_absolute_time and everything built on it, keeps counting while the device sleeps.

Additional context

• Additive and off by default. An unwrapped hook behaves exactly as it does today.
• A hook set on LDConfig is one instance shared by the clients for every environment in secondaryMobileKeys, and so is its deduper. The environment is therefore part of both the exposure key and the per-flag record; sharing a record across environments would make each look like the other having changed its result, and neither would ever be suppressed.
• Experiment status is a component of the key in its own right, because versionForEvents prefers the flag's own version: 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.
• Mirrored on Android in launchdarkly/android-client-sdk, with docs in sdk-meta and ld-docs-private. Demonstrated in launchdarkly/hello-ios.

---

Note

Overview
Adds opt-in deduplication for hook evaluation callbacks: wrap a hook in DedupingHook (default 10‑minute window, or a custom EvaluationExposureDeduper) so repeated evaluations with the same EvaluationExposureKey skip both beforeEvaluation and afterEvaluation until the result changes, the window expires, or identify clears state.

Introduces HookDecorator for stacking hook behavior, EvaluationExposureKey / evaluationExposureKey on EvaluationSeriesContext, and UnfairLock for thread-safe dedupe state. LDClient now hashes the mobile key once (mobileKeyHash), collects hooks deterministically at init, and reads each flag once per variation so hooks and the returned value describe the same snapshot.

Unwrapped hooks and LaunchDarkly feature/debug/summary events still run on every evaluation; only wrapped hook stages are suppressed.

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

[abelonogov-ld]

@launchdarkly verify changes here with Android https://github.com/launchdarkly/android-client-sdk main

[abelonogov-ld]

@devin verify changes here with Android https://github.com/launchdarkly/android-client-sdk main

[devin-ai-integration]

Could not match GitHub user abelonogov-ld to a Devin account. Please make sure your GitHub account is linked in your Devin settings.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

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