[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. An exception from the source's Dispose is logged and the rest of the client still shuts down, and a snapshot that the source supplies during shutdown is ignored. A configuration error in the source propagates from the constructor like any other invalid component configuration. An exception from the source's Start does not: the SDK logs it, disposes the source, removes any snapshot the source supplied before failing, and the client runs without overrides, because a client in an incident is better off without its overrides than not starting. The SDK's own file-based source never throws from Start; it logs a failed load and retries. The source is not built when the client is offline, so no overrides are served and a configuration error in it is not reported; the SDK logs a warning saying so. 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 (a failure of the base store propagates, as it does without the overlay), 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, a source whose Build throws leaves nothing started, and a source whose Start throws is disposed while the client runs without overrides. AllFlagsState reads through the overlay, so it includes override-only flags. When neither the client nor the store is initialized and the layer holds flags, it returns a state of those flags alone (with a warning logged once), read from the layer rather than the merged store so that LaunchDarkly data in a store without an init marker stays out; with no override flags the state is invalid, as it is without a source. Without a source this state is empty, because the SDK reports no flags before the store is initialized, so the override flags only add to what it reports; overrides never remove a flag from the state. When the store fails to list its flags, the failure is logged and the state holds the override layer's flags and is invalid: without a source that state is invalid and empty, and a client-side SDK bootstrapped from the state uses its flags whatever its validity says, so the overridden values still reach it. 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, including the reason MigrationVariation reports for an unrecognized stage.

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.

It depends on the model and evaluator marking change, #363, which is merged into dotnet-server-sdk-v9.

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 for the FDv2 data system: DataSystemBuilder.Overrides() configures an optional IOverrideSource that pushes full snapshots through IOverrideSink, without affecting initialization or data-source status.

When a source is configured, the SDK builds an override layer and wraps the read-only store with OverrideOverlay so evaluations, prerequisites, segments, and AllFlagsState see override entries before LaunchDarkly data. OverrideSink replaces the layer atomically and notifies flag listeners using the same path as LaunchDarkly updates, including dependency fan-out via OverrideChanges and IExternalDependencies on DataSourceUpdatesImpl (LaunchDarkly changes can now reach overridden flags that reference them).

LdClient is updated so overridden flags can be served before the client initializes; AllFlagsState can return override-only flags (with one-time warnings), fall back to overrides when GetAll fails, and disable per-flag event tracking when overrideAffected is set. Start/dispose failures on the source are logged and the client continues without overrides; offline mode skips starting the source. FDv1DataSystem exposes empty override APIs for parity. Extensive unit tests and override-vectors.json cover the stack.

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

_{Opened from termag}

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[kinyoklion]

On the MigrationVariation point from the review summary: fixed in 1b6a23d. The WRONG_TYPE reason for an unrecognized stage now keeps overrideAffected from the evaluation, the same as the EvaluationAndFlag path (test: MigrationVariationKeepsTheMarkingWhenAnOverrideHasAnUnrecognizedStage). Go had the same gap, fixed in launchdarkly/go-server-sdk#492. Node already kept the marking.

Agent comment: written by Claude Code (an AI coding agent) on behalf of @kinyoklion.

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[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 58ef4ac. Configure here.}