feat: Add the override store, overlay, source interfaces, and data system wiring

[kinyoklion]

Summary

Adds the override store, the overlay at the store read boundary, the override source interfaces, and the data system wiring for flag overrides, as defined by the OVERRIDE specification. With this change an application can configure an override source on the FDv2 data system and have its flags and segments take precedence over LaunchDarkly data at evaluation time.

Configuration surface: DataSystemBuilder.Overrides(IComponentConfigurer<IOverrideSource>) and DataSystemConfiguration.OverrideSource. At most one source is accepted. IOverrideSource (Start(IOverrideSink), IDisposable) and IOverrideSink.SetOverrides(FullDataSet<ItemDescriptor>) follow the shape of the data source interfaces, so an application can supply a custom source the same way it supplies a custom data source. The SDK builds the source when the client is created, starts it before the data sources so that its initial load completes inside the client constructor, and disposes it with the client. A configuration error in the source propagates from the constructor like any other invalid component configuration. The source is not built when the client is offline. Without a configured source the SDK is unchanged.

The override layer (Internal/Overrides): OverrideLayer holds the entries as an immutable map swapped on every snapshot, marking copies of the supplied definitions so the source's own objects are never modified. OverrideOverlay implements the data system's read-only store: a read returns the override entry when one exists and the LaunchDarkly entry otherwise, an enumeration returns the union with override entries winning, and initialization status still comes from the base store. OverrideSink applies snapshots one at a time and computes the flags an update may have changed, including dependency fan-out through prerequisites and segments over both the old and the new merged views, then sends the same flag change notifications a LaunchDarkly change would.

Client behavior: the not-initialized short-circuit consults the override layer first, so an overridden flag is served before the client has LaunchDarkly data while a flag the layer does not hold takes exactly the path it took before this feature. An evaluation that fails with an unexpected exception keeps the marking when the flag came from the layer. A malformed override definition is logged and skipped during change computation so the other notifications still fire, and a source whose Build or Start throws leaves nothing started. AllFlagsState reads through the overlay, so it includes override-only flags and, before initialization, returns a state built from overrides alone (with a warning logged once). A flag whose evaluation is override-affected keeps its value, version, and marked reason in the state but has trackEvents and trackReason off and no debugEventsUntilDate, because a consumer of the state must not send individual events for it. A wrong-type result keeps the marking on its reason.

The specification's test vectors run as a unit test against the full client stack (value, variation index, and reason; the summary-counter contribution is asserted once the events change lands). Unit tests cover the layer, overlay, sink, the builder, and the client behaviors above.

This PR is based on the branch of the model and evaluator marking change, which it depends on.

SDK-3248

Follow-up from review

A LaunchDarkly change now notifies the flags whose overrides depend on it. The override layer keeps the dependency edges of its own entries, rebuilt on every replacement, and DataSourceUpdatesImpl expands each changed LaunchDarkly item through both its own tracker and the layer's until nothing new is reached, so an override that matches a LaunchDarkly segment or has a LaunchDarkly prerequisite is notified like the LaunchDarkly flags that depend on it. An entry whose references cannot be read contributes no edges, the same as the change computation skips it.

---

Note

Overview
Adds experimental flag overrides to the FDv2 data system so operators can force per-key flag/segment definitions that win over LaunchDarkly at read time, without affecting initialization or data-source status.

Configuration: DataSystemBuilder.Overrides(...) and IOverrideSource / IOverrideSink plug into DataSystemConfiguration; the source starts synchronously before data sources and is skipped when offline.

Runtime: OverrideLayer + OverrideOverlay sit on the read-only store boundary; OverrideSink applies full snapshots and fans out flag change notifications (including dependency tracking across LaunchDarkly data and override entries via IExternalDependencies). LdClient can evaluate overridden flags before the client is initialized, adjusts AllFlagsState (override-only when needed, disables tracking fields when overrideAffected), and disposes cleanly on build/start failures.

Tests: Unit coverage for layer/overlay/sink/builder/client plus OVERRIDE spec vectors in override-vectors.json.

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

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

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