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. 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. Because the client is created synchronously and a file read is not, the evaluation methods and allFlagsState wait for the source's initial load to complete, so an override present at startup takes effect from the first evaluation. A failed start is logged and the client runs without overrides.

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 override layer to the FDv2 data system via dataSystem.overrides, wired through new LDOverrideSource / LDOverrideSink APIs.

An override source pushes full snapshots into an OverrideLayer; reads go through a ReadStoreOverlay so per-key overrides win over LaunchDarkly data without affecting client initialization or data-source status. LDClientImpl starts the source before the data source (skipped in offline mode), waits on async initial load before variation* / allFlagsState, and serves overridden flags even when the client is not initialized.

Override-affected evaluations get overrideAffected on reasons; allFlagsState strips per-flag tracking fields for those flags while keeping values/reasons. OverrideSink fans out flag-change notifications using dependency tracking (prerequisites and segments). OVERRIDE spec vectors are vendored and exercised through the full client stack.

Also exports the override types from the public API and validates override configuration in Configuration (invalid types warn and drop; malformed sources throw at construction).

^{Reviewed by Cursor Bugbot for commit 4fc2262. 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: 27065 bytes
Compressed size limit: 29000
Uncompressed size: 131676 bytes

[github-actions]

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

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

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

[cursor]

Override dependents miss LD change notifications

Medium Severity

OverrideSink fans change notifications through the merged view only when the override layer itself is replaced. LaunchDarkly upserts still go through TransactionalDataSourceUpdates on the raw feature store, whose dependency graph never includes override definitions. A flag or segment that exists only in the overlay, or whose override edges differ from LaunchDarkly data, is not notified when the LaunchDarkly prerequisite or segment it reads actually changes, so listeners can keep a stale evaluation.

Additional Locations (1)

• packages/shared/sdk-server/src/LDClientImpl.ts#L335-L356

 

^{Reviewed by Cursor Bugbot for commit 4fc2262. Configure here.}