feat: add an initial connection mode to the FDv2 data system config (#318)

Adds `DataSystemConfig.initialConnectionMode` so an application can
choose the connection mode the FDv2 data system starts in.

Setting it is equivalent to calling `setConnectionMode` with that mode
immediately after the client is created: it is a sticky override. While
a mode is set this way the SDK stays in it and does not switch
automatically in response to application lifecycle or network changes.
Clearing the override (`setConnectionMode(null)`) resumes automatic
resolution. When the option is null (the default) the SDK resolves the
mode automatically, starting in streaming while in the foreground.

It is typed as `ConnectionModeId` rather than the FDv1 `ConnectionMode`
enum so it can reach the FDv2 built-in modes (including `background`)
and, later, custom modes.

When a data system is configured, the FDv1
`DataSourceConfig.initialConnectionMode` no longer influences the
connection mode. The SDK now starts in streaming and lets the data
system configuration and connection manager resolve the effective mode,
and the FDv1 option is documented as having no effect under FDv2.

The Flutter wiring that consumes this option
(`setConnectionMode(ConnectionModeId)` and applying the initial
override) stacks on top of this PR.

SDK-2187

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> FDv2-enabled clients that previously relied on
DataSourceConfig.initialConnectionMode will now always bootstrap in
streaming until data-system resolution runs, which is a deliberate
behavior shift in connection startup.
> 
> **Overview**
> Adds **`DataSystemConfig.initialConnectionMode`**
(`ConnectionModeId?`) so FDv2 apps can pick the connection mode at
startup. Documented behavior matches a post-create
**`setConnectionMode`** sticky override: while set, the SDK does not
auto-switch on lifecycle/network; **`null`** restores automatic
resolution (default: auto, foreground streaming).
> 
> When **`dataSystem`** is configured, **`LDCommonClient`** no longer
seeds **`DataSourceManager`** from
**`DataSourceConfig.initialConnectionMode`**; it always starts in
**streaming** and defers effective mode to the FDv2 data system /
connection manager. **`DataSourceConfig.initialConnectionMode`** is
documented as **ignored under FDv2** in favor of the new field.
> 
> Applying the config value at runtime is expected in follow-on Flutter
wiring; this change is the config surface and FDv1/FDv2 split at client
construction.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
a546858. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: joker23 <2494686+joker23@users.noreply.github.com>

Author: kinyoklion

packages/common_client/lib/src/config/data_system_config.dart

@@ -73,7 +73,21 @@ final class DataSystemConfig {
   /// their built-in definition.
   final Map<ConnectionModeId, ModeDefinition> connectionModes;
 
+  /// The connection mode the SDK starts in.
+  ///
+  /// Setting this is equivalent to calling `setConnectionMode` with the
+  /// same mode immediately after the client is created.
+  /// While a mode is set this way the SDK stays in it and does
+  /// not switch automatically in response to application lifecycle or
+  /// network changes. Call `setConnectionMode(null)` to clear the override
+  /// and resume automatic mode resolution.
+  ///
+  /// When null (the default) the SDK resolves the connection mode
+  /// automatically, starting in streaming while in the foreground.
+  final ConnectionModeId? initialConnectionMode;
+
   const DataSystemConfig({
     this.connectionModes = const {},
+    this.initialConnectionMode,
   });
 }

packages/common_client/lib/src/ld_common_client.dart

@@ -284,7 +284,13 @@ final class LDCommonClient {
     _dataSourceManager = DataSourceManager(
         startingMode: _config.offline
             ? ConnectionMode.offline
-            : _config.dataSourceConfig.initialConnectionMode,
+            // Under the FDv2 data system the connection mode is governed by
+            // the data system configuration (and the connection manager),
+            // not the FDv1 data source options; start in streaming and let
+            // that machinery resolve the effective mode.
+            : _config.dataSystem != null
+                ? ConnectionMode.streaming
+                : _config.dataSourceConfig.initialConnectionMode,
         statusManager: _dataSourceStatusManager,
         dataSourceEventHandler: dataSourceEventHandler,
         logger: _logger);

packages/common_client/lib/src/ld_common_config.dart

@@ -49,6 +49,10 @@ final class DataSourceConfig {
   bool evaluationReasons;
 
   /// The mode to use for connections when the SDK is initialized.
+  ///
+  /// This has no effect when the FDv2 data system is enabled (a
+  /// [DataSystemConfig] is provided). In that case use
+  /// [DataSystemConfig.initialConnectionMode] instead.
   ConnectionMode initialConnectionMode;
 
   /// Settings for the SDK polling data source.
@@ -69,6 +73,10 @@ final class DataSourceConfig {
   /// [ConnectionMode.offline] then the data source will not request data from
   /// LaunchDarkly, but the sending of events will be unaffected. In order
   /// to completely disable network activity use [LDConfig.offline].
+  ///
+  /// This option has no effect when the FDv2 data system is enabled (a
+  /// [DataSystemConfig] is provided); use
+  /// [DataSystemConfig.initialConnectionMode] in that case.
   DataSourceConfig(
       {bool? useReport,
       bool? evaluationReasons,