feat: Add experimental support for data-saving mode (FDv2). (#314)

The final wiring PR for FDv2 in the Flutter SDK: surfaces the data
system on the public API so applications can use it. The data system
itself lives in `common_client` (already on main via #310/#311/#312);
this PR is the Flutter exposure.

## Changes
- **`LDConfig`** gains a `dataSystem` option (passed through to
`LDCommonConfig`). Setting it opts the SDK into FDv2. Documented as
early access / not semver-stable.
- **`LDClient.setConnectionMode([ConnectionMode?])`** — applies a manual
connection-mode override (sticks and suppresses automatic
state-detection transitions; `null` clears it and resumes automatic
resolution). Early access.
- **Public exports** — adds the data-system configuration types
(`DataSystemConfig`, `ConnectionModeId`, `ModeDefinition`,
`EndpointConfig`, `InitializerEntry`/`SynchronizerEntry`,
`CacheInitializer`/`PollingInitializer`/`StreamingInitializer`/`PollingSynchronizer`/`StreamingSynchronizer`,
`Fdv1FallbackConfig`) and removes the internal `FDv2*` connection-mode
types from the public surface (they’re used internally by
`setConnectionMode`, not part of the API).

## Validation
- `flutter analyze` clean; all 47 flutter package tests pass against
current main.
- End-to-end behavior (incl. FDv1 fallback) is exercised by the v3
contract tests — added in the stacked follow-up.

## Release note
The `launchdarkly_common_client` pin is still `1.13.0` (the last
released version, which predates FDv2). CI resolves it via the melos
path override, so the workspace builds against the FDv2 `common_client`
on main. **Before this ships, `common_client` must release with the FDv2
work and this pin must be bumped** (per `RELEASING.md`: common →
common_client → flutter, in dependency order).

Two drafts will be stacked on this PR: the v3 contract tests, and the
FDv2 example app.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes how connection modes are chosen when FDv2 is enabled and adds
experimental runtime overrides over networking/lifecycle behavior;
impact is limited by early-access APIs and mostly additive wiring.
> 
> **Overview**
> **Surfaces FDv2 (data-saving mode) on the Flutter public API** by
adding optional `dataSystem` on `LDConfig` (passed through to
`common_client`) and exporting the related configuration types
(`DataSystemConfig`, `ConnectionModeId`, initializer/synchronizer
entries, etc.). Internal `FDv2*` connection-mode types are **removed
from the public export list**; apps use `ConnectionModeId` instead.
> 
> Adds **`LDClient.setConnectionMode([ConnectionModeId?])`** as an
early-access manual override that sticks until cleared with `null`,
wired through `ConnectionManager.setMode`.
**`ConnectionManagerConfig.initialModeOverride`** seeds that behavior at
construction (including from `dataSystem.initialConnectionMode`).
> 
> When **`dataSystem` is configured**, foreground automatic resolution
defaults to **streaming** (not FDv1
`dataSourceConfig.initialConnectionMode`), and any configured initial
connection mode is applied as the sticky override. FDv1 apps without
`dataSystem` keep the previous data-source-driven initial mode.
> 
> Tests cover initial override on startup, lifecycle suppression while
overridden, and resuming automatic resolution after clearing.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
f884852. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

packages/flutter_client_sdk/lib/launchdarkly_flutter_client_sdk.dart

@@ -45,11 +45,6 @@ export 'package:launchdarkly_common_client/launchdarkly_common_client.dart'
         PersistenceConfig,
         ApplicationInfo,
         ConnectionMode,
-        FDv2ConnectionMode,
-        FDv2Streaming,
-        FDv2Polling,
-        FDv2Offline,
-        FDv2Background,
         ResolvedConnectionMode,
         ResolvedStreaming,
         ResolvedPolling,
@@ -73,7 +68,19 @@ export 'package:launchdarkly_common_client/launchdarkly_common_client.dart'
         PluginCredentialInfo,
         PluginEnvironmentMetadata,
         PluginMetadata,
-        PollingConfig;
+        PollingConfig,
+        DataSystemConfig,
+        ConnectionModeId,
+        ModeDefinition,
+        EndpointConfig,
+        InitializerEntry,
+        SynchronizerEntry,
+        CacheInitializer,
+        PollingInitializer,
+        StreamingInitializer,
+        PollingSynchronizer,
+        StreamingSynchronizer,
+        Fdv1FallbackConfig;
 
 export 'src/ld_client.dart' show LDClient;
 export 'src/config/ld_config.dart' show LDConfig, ApplicationEvents;

packages/flutter_client_sdk/lib/src/config/ld_config.dart

@@ -90,6 +90,10 @@ final class LDConfig extends LDCommonConfig {
   /// [plugins] can be used to add plugins to the SDK.
   ///
   /// Plugin support is currently experimental and subject to change.
+  ///
+  /// [dataSystem] opts the SDK into the FDv2 data acquisition protocol.
+  /// This feature is not stable, and not subject to any backwards
+  /// compatibility guarantees or semantic versioning. It is in early access.
   LDConfig(super.sdkCredential, super.autoEnvAttributes,
       {super.applicationInfo,
       super.httpProperties,
@@ -103,7 +107,8 @@ final class LDConfig extends LDCommonConfig {
       super.globalPrivateAttributes,
       ApplicationEvents? applicationEvents,
       super.hooks,
-      List<Plugin>? plugins})
+      List<Plugin>? plugins,
+      super.dataSystem})
       : applicationEvents = applicationEvents ?? ApplicationEvents(),
         plugins =
             plugins != null ? UnmodifiableListView(List.from(plugins)) : null;

packages/flutter_client_sdk/lib/src/connection_manager.dart

@@ -82,6 +82,14 @@ final class ConnectionManagerConfig {
   /// Defaults to [const FDv2Offline()].
   final FDv2ConnectionMode backgroundConnectionMode;
 
+  /// An initial mode override applied at construction, equivalent to calling
+  /// [ConnectionManager.setMode] immediately after creation. When non-null
+  /// the manager starts in this mode and suppresses automatic resolution
+  /// until the override is cleared.
+  ///
+  /// Defaults to null (automatic resolution from construction).
+  final FDv2ConnectionMode? initialModeOverride;
+
   /// Some platforms (windows, web, mac, linux) can continue executing code
   /// in the background.
   final bool runInBackground;
@@ -121,6 +129,7 @@ final class ConnectionManagerConfig {
   ConnectionManagerConfig({
     this.initialConnectionMode = ConnectionMode.streaming,
     this.backgroundConnectionMode = const FDv2Offline(),
+    this.initialModeOverride,
     this.runInBackground = true,
     this.disableAutomaticBackgroundHandling = false,
     this.disableAutomaticNetworkHandling = false,
@@ -153,7 +162,8 @@ final class ConnectionManager {
   StreamSubscription<NetworkState>? _networkStateSub;
 
   /// When non-null, [resolveMode] is skipped and this mode is
-  /// applied regardless of lifecycle/network.
+  /// applied regardless of lifecycle/network. Seeded from
+  /// [ConnectionManagerConfig.initialModeOverride].
   FDv2ConnectionMode? _modeOverride;
 
   ApplicationState _applicationState;
@@ -183,6 +193,7 @@ final class ConnectionManager {
         _config = config,
         _destination = destination,
         _resolutionTable = resolutionTable ?? flutterDefaultResolutionTable(),
+        _modeOverride = config.initialModeOverride,
         _applicationState = config.initialApplicationState,
         // Network has no synchronous platform API; start optimistic. If
         // the network is actually unavailable, the first detector emission
@@ -195,7 +206,7 @@ final class ConnectionManager {
         networkAvailable: true,
         inForeground:
             config.initialApplicationState == ApplicationState.foreground,
-        requestedMode: null,
+        requestedMode: config.initialModeOverride,
       ),
       debounceWindow: config.debounceWindow,
     );

packages/flutter_client_sdk/lib/src/ld_client.dart

@@ -78,11 +78,23 @@ interface class LDClient {
         DiagnosticSdkData(name: sdkName, version: sdkVersion),
         hooks: combined);
     final stateDetector = FlutterStateDetector();
+    // Under the FDv2 data system the connection mode is governed by the
+    // data system configuration, not the FDv1 data source options: the
+    // foreground slot defaults to streaming, and an initial connection mode
+    // (if configured) is applied as a sticky override, equivalent to calling
+    // setConnectionMode immediately after construction.
+    final dataSystem = config.dataSystem;
+    final initialModeOverride = switch (dataSystem?.initialConnectionMode) {
+      final id? => _fdv2FromConnectionModeId(id),
+      null => null,
+    };
     _connectionManager = ConnectionManager(
         logger: _client.logger,
         config: ConnectionManagerConfig(
-            initialConnectionMode:
-                config.dataSourceConfig.initialConnectionMode,
+            initialConnectionMode: dataSystem != null
+                ? ConnectionMode.streaming
+                : config.dataSourceConfig.initialConnectionMode,
+            initialModeOverride: initialModeOverride,
             backgroundConnectionMode:
                 FlutterDefaultConfig.defaultBackgroundConnectionMode,
             disableAutomaticBackgroundHandling:
@@ -343,6 +355,25 @@ interface class LDClient {
     _connectionManager.offline = offline;
   }
 
+  /// Set the connection mode the SDK uses for data acquisition.
+  ///
+  /// The mode is applied as a manual override: it sticks and suppresses
+  /// automatic state-detection transitions (backgrounding, network
+  /// availability) until cleared. Call with no argument (or null) to clear
+  /// the override and resume automatic mode resolution.
+  ///
+  /// The mode is a [ConnectionModeId], which can identify any of the FDv2
+  /// built-in modes (including [ConnectionModeId.background]).
+  ///
+  /// This method is not stable, and not subject to any backwards
+  /// compatibility guarantees or semantic versioning. It is in early
+  /// access. If you want access to this feature please join the EAP.
+  /// https://launchdarkly.com/docs/sdk/features/data-saving-mode
+  void setConnectionMode([ConnectionModeId? mode]) {
+    _connectionManager
+        .setMode(mode == null ? null : _fdv2FromConnectionModeId(mode));
+  }
+
   /// Check if the SDK has finished initialization.
   ///
   /// This does not indicate that initialization was successful, but that it is
@@ -389,3 +420,13 @@ interface class LDClient {
         this, _pluginEnvironmentMetadata, [plugin], _client.logger);
   }
 }
+
+/// Translates a public [ConnectionModeId] into the internal
+/// [FDv2ConnectionMode] the connection manager drives.
+FDv2ConnectionMode _fdv2FromConnectionModeId(ConnectionModeId mode) =>
+    switch (mode) {
+      ConnectionModeId.polling => const FDv2Polling(),
+      ConnectionModeId.background => const FDv2Background(),
+      ConnectionModeId.offline => const FDv2Offline(),
+      _ => const FDv2Streaming(),
+    };

packages/flutter_client_sdk/test/persistence/connection_manager_test.dart

@@ -899,4 +899,101 @@ void main() {
       connectionManager.dispose();
     });
   });
+
+  group('given an initial mode override', () {
+    test(
+        'it applies the override on the buffered initial reconcile, without '
+        'any detector emission', () async {
+      registerFallbackValue(ConnectionMode.streaming);
+
+      final destination = MockDestination();
+      final logger = LDLogger(adapter: MockLogAdapter());
+      final config = ConnectionManagerConfig(
+        initialModeOverride: const FDv2Polling(),
+        debounceWindow: const Duration(seconds: 1),
+      );
+      final mockDetector = MockStateDetector();
+
+      final connectionManager = ConnectionManager(
+        logger: logger,
+        config: config,
+        destination: destination,
+        detector: mockDetector,
+      );
+
+      // The buffered initial reconcile fires on the next microtask after
+      // construction.
+      await Future<void>.microtask(() {});
+
+      verify(() => destination.setMode(const ResolvedPolling())).called(1);
+
+      connectionManager.dispose();
+    });
+
+    test(
+        'the override sticks across lifecycle changes and suppresses automatic '
+        'resolution', () async {
+      registerFallbackValue(ConnectionMode.streaming);
+
+      final destination = MockDestination();
+      final logger = LDLogger(adapter: MockLogAdapter());
+      final config = ConnectionManagerConfig(
+        runInBackground: true,
+        backgroundConnectionMode: const FDv2Background(),
+        initialModeOverride: const FDv2Polling(),
+        debounceWindow: Duration.zero,
+      );
+      final mockDetector = MockStateDetector();
+
+      final connectionManager = ConnectionManager(
+        logger: logger,
+        config: config,
+        destination: destination,
+        detector: mockDetector,
+      );
+
+      mockDetector.setApplicationState(ApplicationState.background);
+      await mockDetector.applicationState.first;
+      await _pumpDebouncerHop();
+
+      // The override is honored regardless of lifecycle; the background slot
+      // is never resolved while the override is active.
+      verify(() => destination.setMode(const ResolvedPolling()));
+      verifyNever(() => destination.setMode(const ResolvedBackground()));
+
+      connectionManager.dispose();
+    });
+
+    test('clearing the override resumes automatic resolution', () async {
+      registerFallbackValue(ConnectionMode.streaming);
+
+      final destination = MockDestination();
+      final logger = LDLogger(adapter: MockLogAdapter());
+      final config = ConnectionManagerConfig(
+        runInBackground: true,
+        initialModeOverride: const FDv2Polling(),
+        debounceWindow: Duration.zero,
+      );
+      final mockDetector = MockStateDetector();
+
+      final connectionManager = ConnectionManager(
+        logger: logger,
+        config: config,
+        destination: destination,
+        detector: mockDetector,
+      );
+
+      await _pumpDebouncerHop();
+      reset(destination);
+
+      // Clearing the override resumes automatic resolution; in the foreground
+      // with network available that resolves to streaming.
+      connectionManager.setMode(null);
+      await _pumpDebouncerHop();
+
+      verify(() => destination.setMode(const ResolvedStreaming()));
+
+      connectionManager.dispose();
+    });
+  });
 }