feat: Add the override layer, the store overlay, and the override source configuration

[kinyoklion]

Summary

This adds the override layer that the OVERRIDE specification describes: an override source supplies complete snapshots of flag and segment definitions to an override store, and an overlay at the store read boundary returns the store's entry for a key in preference to LaunchDarkly data. Evaluation, prerequisite and segment resolution, and the all-flags state all read through the overlay, so an override is a full definition that evaluates like any other. Overrides do not take part in the data system: they have no effect on initialization status, data availability, or data source status, and they are never written to a persistent store.

Public surface, all marked experimental and subject to change:

• DataSystemBuilder.overrides(ComponentConfigurer<OverrideSource>) and DataSystemConfiguration.getOverrideSource(). The option lives on the FDv2 data system builder only. An FDv1 data source configuration has no place to supply one.
• subsystems.OverrideSource (start with a sink, close) and subsystems.OverrideSink (replace the whole layer with one snapshot). The SDK builds the source like any other component, starts it before the data source so its initial load completes during client construction, and closes it with the client. An offline client starts no override source. A source that cannot be built fails client construction the same way other invalid component configuration does.

Internals:

• OverrideLayer holds marked shallow copies of the supplied entities in an immutable map that is swapped on each update. The source's objects are never modified.
• OverrideOverlayStore implements the read boundary: per-key reads prefer the layer, enumeration is the union with override precedence, and when the base store fails while the layer holds entries the layer's entries are still served.
• OverrideSinkImpl serializes snapshot application and fires the normal flag change notifications for every flag whose merged-view evaluation may have changed, using the dependency tracker over both the old and the new merged views so prerequisite and segment dependents are included.
• The not-initialized short-circuit consults the layer first: a flag that the layer holds is served before the client has LaunchDarkly data, and any other flag returns the client-not-ready default as before. The all-flags state does the same, logging once that it returned only override entries, and presents an override-affected flag with trackEvents and trackReason false and no debugEventsUntilDate.

The OVERRIDE specification's test vectors run as a unit test through the full client stack (value, variation index, and reason). The per-evaluation summary marker in the vectors is asserted by the events change that follows.

This PR depends on the model and evaluator marking change (rlamb/overrides-java-model-marker) and is based on that branch; retarget it to feat/overrides once that branch merges.

The existing file data source keeps its current behavior; this change does not touch its code paths.

SDK-3246

Follow-ups 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.
• isFlagKnown consults the override layer before the not-initialized short circuit, the same as evaluation does, so an override-only flag is known while the client is uninitialized.

---

Note

Overview
Adds an experimental override layer for the FDv2 data system so operators can supply full flag/segment snapshots that take precedence over LaunchDarkly data at the store read boundary, without affecting client initialization or data source status.

Configuration & lifecycle: DataSystemBuilder.overrides(...) wires an OverrideSource that pushes wholesale snapshots to OverrideSink. FDv2 builds the source like other components, starts it before the data source (so sync loads apply during construction), overlays reads via OverrideOverlayStore, and closes the source with the client. Offline clients skip overrides; FDv1 always returns a null override layer.

Evaluation & API behavior: Overridden flags evaluate even when the client/store is not initialized; non-overridden flags still get the client-not-ready default. isFlagKnown and allFlagsState follow the same rules (override-only all-flags when uninitialized, with a one-time warning). Override-affected results keep value/reason but disable per-flag event tracking in FeatureFlagsState.

Change notifications: LaunchDarkly updates fan out through both the normal dependency tracker and the override layer’s edges (ExternalDependencies), so LD segment/prerequisite changes notify overridden dependents; override updates use merged-view diffs and dependency fan-out in OverrideSinkImpl.

^{Reviewed by Cursor Bugbot for commit 5a27c9f. 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 5a27c9f. Configure here.}