test: exercise FDv2 and FDv1 fallback via the v3 contract tests (#315)

Stacked on #314 (the Flutter FDv2 exposure). Wires the Flutter contract
test service for the **v3 (FDv2) harness** and runs it in CI, so the
data system — including FDv1 fallback — is exercised end-to-end.

## Changes
- **Contract service:** advertise the `fdv1-fallback` capability; map
the harness `dataSystem` configuration onto `LDConfig.dataSystem`
(including the `fdv1Fallback` polling config); regenerate the service
API model (`service_api.openapi.*`) for the `dataSystem` schema.
- **CI (`.github/actions/ci/action.yml`):** add an **FDv2 contract-tests
run** (the `launchdarkly/gh-actions/actions/contract-tests` action with
`version: v3`, `branch: v3`) alongside the existing FDv1 run. Because
the FDv1 run stops the test service at the end, the FDv2 step restarts
it. Modeled on cpp-sdks' `contract-tests-fdv2` job.

## Validation
The v3 harness passes end-to-end against this service: **816 total / 792
ran / 24 skipped, exit 0** (run locally against this branch on merged
main), including the full FDv1 fallback suite. Contract service analyzes
clean.

## Notes for review
The CI YAML can't be run locally, so a couple of assumptions to
sanity-check:
- The pinned `contract-tests@contract-tests-v1.3.0` action supports
`version: v3` / `branch: v3` (cpp uses the same action with v3).
- FDv1 and FDv2 share `testharness-suppressions.txt` (the v3 run passes
with it; cpp keeps a separate `*-fdv2.txt` — we can split if preferred).

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Changes are limited to CI and the contract-test adapter; production
SDK behavior is exercised indirectly via harness mapping, with no auth
or customer-facing API changes in this diff.
> 
> **Overview**
> Adds **FDv2 contract test coverage** in shared CI alongside the
existing FDv1 run: the FDv1 step is labeled explicitly, then a second
pass **restarts** the Flutter contract test service and invokes
`contract-tests` with **`version`/`branch` v3** (same suppressions
file).
> 
> The **Flutter contract test service** is extended for the v3 harness:
it advertises **`fdv1-fallback`** (and related) capabilities, accepts a
**`dataSystem`** block on client creation (OpenAPI + codegen), and
**`_mapDataSystem`** translates harness shapes (connection mode
overrides, initializers/synchronizers, **`fdv1Fallback`**) into
**`LDConfig.dataSystem`** and initial connection mode. Smaller harness
fixes include omitting null evaluation **`value`** keys, stricter
context casts, and **`Timeout.none`** on the long-running test server.
> 
> **`pubspec.lock`** bumps pinned local SDK packages used by the
contract app.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
db18961. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

.github/actions/ci/action.yml

@@ -63,7 +63,7 @@ runs:
         cd packages/common
         dart test test/serialization/canonicalize_json_platform_test.dart -p chrome --test-randomize-ordering-seed=random
 
-    - name: Contract Tests
+    - name: Contract Tests (FDv1)
       shell: bash
       run: |
         pushd apps/flutter_client_contract_test_service
@@ -75,6 +75,22 @@ runs:
         enable_persistence_tests: false
         extra_params: '-status-timeout 100 --skip-from=./apps/flutter_client_contract_test_service/testharness-suppressions.txt'
 
+    # FDv2 contract tests run against the v3 harness. The FDv1 run above
+    # stops the test service when it finishes, so start it again here.
+    - name: Contract Tests (FDv2)
+      shell: bash
+      run: |
+        pushd apps/flutter_client_contract_test_service
+        flutter test bin/contract_test_service.dart > test-service-fdv2.log 2>&1 & disown
+    - uses: launchdarkly/gh-actions/actions/contract-tests@contract-tests-v1.3.0
+      with:
+        test_service_port: 8080
+        token: ${{ inputs.github_token }}
+        version: 'v3'
+        branch: 'v3'
+        enable_persistence_tests: false
+        extra_params: '-status-timeout 100 --skip-from=./apps/flutter_client_contract_test_service/testharness-suppressions.txt'
+
     - name: SSE Contract Tests Service
       shell: bash
       run: |

apps/flutter_client_contract_test_service/bin/contract_test_service.dart

@@ -28,6 +28,8 @@ class TestApiImpl extends SdkTestApi {
     'client-per-context-summaries',
     'client-prereq-events',
     'auto-env-attributes',
+    'client-event-source-http-errors',
+    'fdv1-fallback',
   ];
 
   static const clientUrlPrefix = '/client/';
@@ -50,6 +52,8 @@ class TestApiImpl extends SdkTestApi {
   Future<PostResponse> Post(PostSchema body) async {
     final startWaitTimeMillis =
         body.configuration?.startWaitTimeMs?.toInt() ?? defaultWaitTimeMillis;
+    final mappedDataSystem =
+        _mapDataSystem(body.configuration?.dataSystem?.toJson());
     final config = LDConfig(
       body.configuration?.credential ?? '',
       AutoEnvAttributes.disabled,
@@ -64,9 +68,10 @@ class TestApiImpl extends SdkTestApi {
           streaming: body.configuration?.streaming?.baseUri,
           events: body.configuration?.events?.baseUri),
       dataSourceConfig: DataSourceConfig(
-          initialConnectionMode: body.configuration?.streaming != null
-              ? ConnectionMode.streaming
-              : ConnectionMode.polling,
+          initialConnectionMode: mappedDataSystem?.initialConnectionMode ??
+              (body.configuration?.streaming != null
+                  ? ConnectionMode.streaming
+                  : ConnectionMode.polling),
           evaluationReasons: body.configuration?.clientSide?.evaluationReasons,
           useReport: body.configuration?.clientSide?.useReport),
       events: EventsConfig(
@@ -78,6 +83,7 @@ class TestApiImpl extends SdkTestApi {
           body.configuration?.events?.allAttributesPrivate ?? false,
       globalPrivateAttributes:
           body.configuration?.events?.globalPrivateAttributes,
+      dataSystem: mappedDataSystem?.config,
     );
 
     final configuration = body.configuration!;
@@ -289,6 +295,148 @@ class TestApiImpl extends SdkTestApi {
     return response;
   }
 
+  /// Translates the harness `dataSystem` configuration block into the
+  /// SDK's [DataSystemConfig] and an initial connection mode.
+  ///
+  /// Two shapes are supported, mirroring the harness:
+  /// - `connectionModeConfig` with a map of mode name to mode definition
+  ///   plus `initialConnectionMode`. The SDK overrides built-in modes
+  ///   only, so a definition is applied when its name matches a built-in
+  ///   ([ConnectionModeId]); other names are ignored.
+  /// - Top-level `initializers`/`synchronizers` lists, which override the
+  ///   built-in streaming mode.
+  ({DataSystemConfig config, ConnectionMode initialConnectionMode})?
+      _mapDataSystem(Map<String, dynamic>? raw) {
+    if (raw == null) {
+      return null;
+    }
+
+    // The FDv1 fallback is configured at the data-system level (a polling
+    // config); it applies to whichever modes are built below.
+    Fdv1FallbackConfig? parseFdv1Fallback() {
+      if (raw['fdv1Fallback'] case final Map<String, dynamic> fallback) {
+        return Fdv1FallbackConfig(
+          pollInterval: fallback['pollIntervalMs'] != null
+              ? Duration(
+                  milliseconds: (fallback['pollIntervalMs'] as num).toInt())
+              : null,
+          endpoints: fallback['baseUri'] != null
+              ? EndpointConfig(
+                  pollingBaseUri: Uri.parse(fallback['baseUri'] as String))
+              : null,
+        );
+      }
+      return null;
+    }
+
+    final fdv1Fallback = parseFdv1Fallback();
+
+    ModeDefinition translateMode(Map<String, dynamic> modeJson) {
+      final initializers = <InitializerEntry>[];
+      for (final entry in (modeJson['initializers'] as List<dynamic>? ?? [])) {
+        final initializer = entry as Map<String, dynamic>;
+        if (initializer['polling'] case final Map<String, dynamic> polling) {
+          initializers.add(PollingInitializer(
+              endpoints: EndpointConfig(
+                  pollingBaseUri: polling['baseUri'] != null
+                      ? Uri.parse(polling['baseUri'] as String)
+                      : null)));
+        }
+      }
+
+      final synchronizers = <SynchronizerEntry>[];
+      for (final entry in (modeJson['synchronizers'] as List<dynamic>? ?? [])) {
+        final synchronizer = entry as Map<String, dynamic>;
+        if (synchronizer['streaming']
+            case final Map<String, dynamic> streaming) {
+          synchronizers.add(StreamingSynchronizer(
+              initialReconnectDelay: streaming['initialRetryDelayMs'] != null
+                  ? Duration(
+                      milliseconds:
+                          (streaming['initialRetryDelayMs'] as num).toInt())
+                  : null,
+              endpoints: EndpointConfig(
+                  streamingBaseUri: streaming['baseUri'] != null
+                      ? Uri.parse(streaming['baseUri'] as String)
+                      : null)));
+        } else if (synchronizer['polling']
+            case final Map<String, dynamic> polling) {
+          synchronizers.add(PollingSynchronizer(
+              pollInterval: polling['pollIntervalMs'] != null
+                  ? Duration(
+                      milliseconds: (polling['pollIntervalMs'] as num).toInt())
+                  : null,
+              endpoints: EndpointConfig(
+                  pollingBaseUri: polling['baseUri'] != null
+                      ? Uri.parse(polling['baseUri'] as String)
+                      : null)));
+        }
+      }
+
+      return ModeDefinition(
+          initializers: initializers,
+          synchronizers: synchronizers,
+          fdv1Fallback: fdv1Fallback);
+    }
+
+    ConnectionMode parseInitialMode(String? name) {
+      return switch (name) {
+        'polling' => ConnectionMode.polling,
+        'offline' => ConnectionMode.offline,
+        _ => ConnectionMode.streaming,
+      };
+    }
+
+    ConnectionModeId? builtInModeId(String name) {
+      return switch (name) {
+        'streaming' => ConnectionModeId.streaming,
+        'polling' => ConnectionModeId.polling,
+        'background' => ConnectionModeId.background,
+        'offline' => ConnectionModeId.offline,
+        _ => null,
+      };
+    }
+
+    if (raw['connectionModeConfig'] case final Map<String, dynamic> connMode) {
+      final overrides = <ConnectionModeId, ModeDefinition>{};
+      if (connMode['customConnectionModes']
+          case final Map<String, dynamic> modes) {
+        for (final entry in modes.entries) {
+          if (builtInModeId(entry.key) case final id?) {
+            overrides[id] = translateMode(entry.value as Map<String, dynamic>);
+          }
+        }
+      }
+      final initialModeName = connMode['initialConnectionMode'] as String?;
+      return (
+        config: DataSystemConfig(
+          connectionModes: overrides,
+          // Under the FDv2 data system the initial mode must be carried on
+          // the data system config; the FDv1 initialConnectionMode is inert.
+          initialConnectionMode:
+              initialModeName == null ? null : builtInModeId(initialModeName),
+        ),
+        initialConnectionMode: parseInitialMode(initialModeName),
+      );
+    }
+
+    if (raw['initializers'] != null || raw['synchronizers'] != null) {
+      // Top-level source lists override the built-in streaming mode.
+      return (
+        config: DataSystemConfig(
+            connectionModes: {ConnectionModeId.streaming: translateMode(raw)}),
+        initialConnectionMode: ConnectionMode.streaming,
+      );
+    }
+
+    // Present but empty (or useDefaultDataSystem): FDv2 with built-in
+    // modes.
+    return (
+      config: DataSystemConfig(),
+      initialConnectionMode: ConnectionMode.streaming,
+    );
+  }
+
   LDContext _contextFromSingleOrMulti(SingleOrMultiBuildContext input) {
     if (input.single != null) {
       return _flattenedListToContext(
@@ -315,8 +463,8 @@ class TestApiImpl extends SdkTestApi {
       final multi = input.multi!.toList();
       final builder = common.LDContextBuilder();
       for (var single in multi) {
-        final kind = single['kind'];
-        final key = single['key'];
+        final kind = single['kind'] as String;
+        final key = single['key'] as String?;
 
         final singleAttributesBuilder = builder.kind(kind, key);
         _buildSingleAttributes(singleAttributesBuilder, single.toJson());
@@ -364,7 +512,12 @@ class TestApiImpl extends SdkTestApi {
 
   Response _responseFromEvaluation(LDValue value) {
     final response = Response();
-    response['value'] = common.LDValueSerialization.toJson(value);
+    // A null evaluation result is omitted rather than set: the response
+    // map rejects null values, and an absent key deserializes the same
+    // as an explicit null on the harness side.
+    if (common.LDValueSerialization.toJson(value) case final Object json) {
+      response['value'] = json;
+    }
     return response;
   }
 
@@ -385,7 +538,7 @@ class TestApiImpl extends SdkTestApi {
     if (input['private'] != null) {
       retMap['_meta'] = {'privateAttributes': input['private']};
     }
-    retMap.addAll(input['custom'] ?? {});
+    retMap.addAll(input['custom'] as Map<String, dynamic>? ?? {});
     return retMap;
   }
 
@@ -453,7 +606,7 @@ final class _WifiConnected extends ConnectivityPlatform {
 }
 
 void main() async {
-  test('Run contract tests', () async {
+  test(timeout: Timeout.none, 'Run contract tests', () async {
     ConnectivityPlatform.instance = _WifiConnected();
     widgets.WidgetsFlutterBinding.ensureInitialized(); // needed before mocking
     // ignore: invalid_use_of_visible_for_testing_member