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

[kinyoklion]

Summary

This PR is based on the evaluator marking branch because it uses the marker and the marking that branch adds.

This change adds the override layer described by the OVERRIDE specification to the FDv2 data system of the Node.js server SDK.

An override source is configured with the new overrides property of the data system options, which accepts a source object or a factory function. A source is not a data source: it takes no part in the initializer and synchronizer pipeline and has no effect on initialization status, data availability, or data source status. The SDK starts it when the client is created, before the data source, passes it a sink, and closes it with the client. In offline mode the source is not started. The public LDOverrideSource and LDOverrideSink interfaces let an application supply a custom source. A configuration that is not a source fails client construction, the way an unsupported data source configuration does.

The source supplies complete snapshots to the override store. Each snapshot replaces the whole store in one assignment, so the store holds exactly one snapshot at any instant. The store holds prepared, marked copies of the definitions and never modifies the objects the source supplied. An overlay at the store read boundary returns the override entry for a key in preference to LaunchDarkly data, and an enumeration includes every flag the store holds. Evaluation, prerequisite and segment resolution, and the all-flags read all go through the overlay.

The client consults the override store before the not-initialized short circuit, and before it asks the data store anything: with a persistent store the initialization check is I/O, and an overridden flag must not wait on a store that is slow or unreachable. An overridden flag is served before the client has LaunchDarkly data, while a flag the store does not hold still gets the not-ready default. Evaluation never waits for the source: an evaluation reads the override store as it is at that moment. The source's initial load is part of starting the client, so the promise that waitForInitialization returns settles after the load as well, whether initialization succeeded or failed, bounded by the caller's timeout; for the file-based source that is a local read that completes within milliseconds of construction. A failed start of the source is logged and the client runs without overrides. The source is created before the data store, so an invalid override configuration fails construction before a persistent store has connected.

The override layer checks the shape of every definition before it stores it. The SDK keeps definitions in their JSON form, so a hand-written definition with a field of the wrong type (a flag without variations, a target or clause without values, rules that are not an array, an on switch that is a string) would otherwise make evaluation throw instead of returning a malformed-flag result. The fields the SDK itself sets when it prepares a definition, such as the sets it generates for large target lists, cannot be supplied. A definition that fails the check is rejected with an error that names the kind, the key, and the field, and no part of that snapshot is applied: the layer keeps its previous contents. Only the key, variations, and values are required; every other field may be absent, as in LaunchDarkly data, so LaunchDarkly definitions, value-only overrides, and TestData flags all pass. The store's maps have no prototype, so a key such as constructor or __proto__ is an ordinary key.

The all-flags state keeps override-affected flags with their values, versions, and marked reasons, and presents them with trackEvents and trackReason false and no debugEventsUntilDate. While the client is not initialized and the store holds entries, the state is valid and holds only those flags. A type mismatch keeps the marking of the evaluation it replaces. Adding, changing, or removing an override fires the normal flag change notifications, including for the flags that depend on a changed flag or segment.

The OVERRIDE specification's test vectors are vendored and run as a unit test through the full client stack, asserting the value, the variation index, and the reason.

SDK-3247

---

Note

Overview
Adds an experimental flag/segment override layer to the FDv2 server SDK via dataSystem.overrides, wired through public LDOverrideSource / LDOverrideSink APIs (source or factory).

Override snapshots replace an in-memory OverrideLayer and are read through a ReadStoreOverlay so per-key overrides win over LaunchDarkly data without changing init or data-source status. LDClientImpl serves overridden flags before the not-ready short-circuit (including when the persistent store is slow), marks evaluations with overrideAffected, adjusts allFlagsState (override-only when uninitialized, strips tracking for affected flags), fans change notifications through OverrideSink, and makes waitForInitialization wait for the source’s initial load while evaluations do not.

Definitions are validated and prepared atomically per snapshot; malformed snapshots are rejected and the previous layer is kept. OVERRIDE spec vectors and broad unit/integration tests cover precedence, dependencies, lifecycle, and configuration edge cases.

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

[github-actions]

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 25437 bytes
Compressed size limit: 44000
Uncompressed size: 165420 bytes

[github-actions]

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 29603 bytes
Compressed size limit: 30000
Uncompressed size: 142116 bytes

[github-actions]

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 32662 bytes
Compressed size limit: 34000
Uncompressed size: 117055 bytes

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[joker23]

nit: we should assess https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone for deep copy. I'm not too partial to it because there may be compatibility issues.

[kinyoklion]

I am not convinced this copy is required. So I will check that.

[kinyoklion]

Checked. The copy itself is needed only to keep the sink contract (the SDK never modifies the objects a source supplies; the other SDKs make the same promise and preparation here writes into nested data), but it was hand-rolled, and the serialized text it produced was also being used for change detection, which is not order-stable. Fixed in 7933b13: the layer now copies with the clone helper from js-sdk-common and stores only the prepared item, and the sink compares entries with fastDeepEqual, the same way the client flag manager computes changed keys. No serialized text is kept, so structuredClone is not needed. A test re-supplies a definition with every object's properties reversed and expects no notification.

Written by Claude Code on behalf of @kinyoklion.

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