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 so telemetry hooks can skip repeated reads of the same flag result within a configurable window, without changing LaunchDarkly analytics event counts.

New public pieces: HookDecorator (stackable hook wrapper), DedupingHook (suppresses whole before/after evaluation series when the exposure matches the last one reported), EvaluationExposureDeduper (default 10‑minute window, monotonic clock, one record per flag per environment), EvaluationExposureKey, and EvaluationSeriesContext.evaluationExposureKey. FeatureFlag.isInExperiment is included in exposure identity. LDClient now tracks environmentName per multi-environment instance so shared config hooks dedupe per environment.

LDClientVariation reads the flag once before running hooks and passes that snapshot into the series context so dedupe decisions match the result the evaluation actually returns. Dedupe state resets on identify; unwrapped hooks behave as before.

^{Reviewed by Cursor Bugbot for commit 31e0591. 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 9ee867b. Configure here.}