[kinyoklion]

Summary

This is the third step of the flag overrides port described by the OVERRIDE specification. It is based on the model marker branch because the phases are stacked; retarget to feat/overrides once that branch merges.

The override layer (ldclient/impl/overrides). OverrideLayer is the override store: it holds marked shallow copies of the flag and segment definitions a source supplies, keyed by key, and is replaced wholesale on each update, so the layer's contents are exactly one snapshot at any instant and an empty snapshot clears it. Dictionaries are decoded with the model constructors, and an invalid definition raises rather than being defaulted. OverrideStoreView is the overlay at the store read boundary: a read of a flag or segment returns the override entry when one exists and the LaunchDarkly entry otherwise, whatever the state of the base store, and an enumeration is the union of both with the override entry winning, including over a deleted item. A failure of the base enumeration propagates, as it does without the overlay. When that read fails, all_flags_state logs the failure as before and, if the override layer holds flags, returns a state of those flags marked invalid rather than an empty one: overrides only add to the state, and a client-side SDK bootstrapped from it uses its flags whatever $valid says, so the overridden values still reach it. With no override flags the state is the same invalid, empty state as without a source. The sink stops accepting snapshots when the client is closed, and when the source fails to start it also clears what the source supplied. OverrideSinkImpl applies each snapshot as one serialized operation and notifies flag change listeners of every flag whose merged-view evaluation may have changed: entries added, removed, or changed, plus every flag that depends on them through prerequisites or segment references. An identical snapshot notifies nothing.

LaunchDarkly changes reach override dependents. The layer keeps a dependency graph of its entries, rebuilt on each replacement, and the store (sync and async) expands every changed LaunchDarkly item through both its own graph and the layer's, to a fixpoint. A change to a prerequisite flag or a segment that an override entry references therefore notifies that entry's flag, the same way dependent flags are notified for LaunchDarkly data, and a chain may cross between LaunchDarkly data and overrides any number of times. Without an override source the store's behavior is unchanged.

Configuration and wiring. OverrideSource and OverrideSink are public protocols in ldclient.interfaces, so a custom source can be supplied. OverrideSourceBuilder and DataSystemConfig.override_source (also on AsyncDataSystemConfig) plus ConfigBuilder.overrides(...) make the source an option of the FDv2 data system. The source is built with the data system, so invalid configuration raises from the client constructor like any other invalid component configuration. It starts before the data system's own threads and its initial load completes before the constructor returns; it is closed when the client is closed, after the sink stops accepting snapshots, and an exception from its close is logged. An exception from its start does not fail the constructor or start: the data system logs it, closes the source, clears any snapshot the source supplied before failing, and the client runs without overrides. The SDK's own file-based source does not raise from start; a custom source could. The source is not built or started when the client is offline, and the SDK logs a warning that it is not used. The data system's store becomes the overlay when a source is configured, so evaluation, prerequisite and segment resolution, and the all-flags read all see override precedence. The override source has no effect on initialization status, data availability, or data source status. The legacy FDv1 data system reports no override source.

The client facade. Both LDClient and AsyncLDClient consult the override layer before the not-initialized short-circuit: an overridden flag is served before the client has LaunchDarkly data, and a flag the layer does not hold takes exactly the path it took before this feature, so a configured but empty source changes nothing with the same warning and event as before. The all-flags state reads through the overlay. While the client has no LaunchDarkly data it contains only the flags the layer holds, read from the layer rather than the overlay so that LaunchDarkly data in a store without an init marker stays out (with a once-per-client warning), and it is invalid when the layer holds no flags. 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. An evaluation that fails with an unexpected exception reports the EXCEPTION reason with overrideAffected when the flag came from the override layer, in a single evaluation and in the all-flags state (OVERRIDE 1.5.4); the marker is read through is_override_definition, so the error path cannot fail on an unexpected store item. On the async client, override change notifications are marshalled onto the event loop, like every other change notification.

Tests. Unit tests for the layer, overlay (sync and async), and sink; client tests for the gate, source lifecycle, construction errors, offline, precedence, prerequisite and segment overrides, all-flags state, and flag change and flag value change listeners, for both clients; and a runner for the OVERRIDE specification test vectors (ldclient/testing/testdata/override-vectors/vectors.json) through the full client stack. The vector runner's per-evaluation summary marker assertion is added with the events step.

SDK-3250

---

Note

Overview
Adds experimental flag/segment overrides that take precedence over LaunchDarkly data at evaluation time, wired through FDv2 for sync and async clients.

New stack: OverrideLayer (snapshot store), store overlay (OverrideStoreView / async variant), and OverrideSinkImpl to apply source snapshots and fan out flag change notifications. Public OverrideSource / OverrideSink protocols and ConfigBuilder.overrides(...) configure an optional source on DataSystemConfig.

Data system: FDv2 builds and starts the override source (skipped offline), exposes override_layer, and serves reads through the overlay. LaunchDarkly store updates cross-notify override dependents via extended dependency tracking on Store. Failed override start logs, clears partial snapshots, and continues without overrides.

Client behavior: Before the not-initialized short-circuit, evaluation reads the override layer so overridden flags work without LD connectivity; all_flags_state can return override-only state (with once-per-client warnings) and may stay valid: false when the base store fails but overrides exist. Evaluation errors set overrideAffected on reasons when the definition came from overrides. Sync LDClient rolls back components if the data system fails to start.

Tests: Unit coverage for layer/overlay/sink and store external deps; broad sync/async client tests; OVERRIDE spec vectors runner.

^{Reviewed by Cursor Bugbot for commit aa6274b. 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]

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 aa6274b. Configure here.}