fix: Close the final initializer on exhaustion; document the source manager contract (#304)

## What this changes

Two small behavior hardenings and an explicit statement of the source
manager's API contract.

- **Initializer exhaustion closes the final initializer.** Every other
transition closes the previous source when the next one is activated,
but the exhaustion path returned null with the last initializer still
active. When no synchronizer activation follows, that initializer (and
its HTTP client) was held until shutdown. A terminal null now leaves no
source running.
- **`engageFdv1Fallback()` is a no-op when no FDv1 fallback slot is
configured.** Blocking every slot without unblocking a fallback would
leave nothing to activate. The orchestration layer checks before
engaging; the guard makes the operation safe regardless of the caller.
- **`hasFdv1FallbackConfigured`** replaces `hasFdv1Fallback` to make
clear it reports configuration, not engagement state.

## The documented contract

The class docs now state the assumptions the manager operates under, so
they are visible at the API surface rather than implicit in the call
sites:

- The manager assumes a single, sequential driver. At most one source is
active at a time: activating a source closes the previous one,
exhaustion closes the final initializer, and `close` closes whatever
remains.
- The synchronizer scan cursor doubles as the active-slot pointer. From
an activation (`nextAvailableSynchronizer` /
`recreateCurrentSynchronizer`) until the next cursor mutation
(`resetSynchronizerIndex` / `engageFdv1Fallback`), the cursor identifies
the running synchronizer's slot — `isPrimarySynchronizer` and
`blockCurrentSynchronizer` read it and are only meaningful inside that
window. After mutating the cursor, a new synchronizer must be activated
before consulting either. The driver satisfies this by construction:
both reads happen strictly between an activation and the run's outcome
being decided, and cursor mutations happen only after the outcome is
decided.

## Testing

New tests pin the exhaustion close (a terminal null leaves no source
running) and the fallback-engagement guard (engaging with no configured
FDv1 slot leaves the slot list untouched). Full package suite passes.

SDK-2186

Author: kinyoklion

packages/common_client/lib/src/data_sources/fdv2/source_manager.dart

@@ -33,6 +33,21 @@ final class SynchronizerSlot {
 
 /// Manages the state of initializers and synchronizers, tracks which
 /// source is active, and handles source transitions for the orchestrator.
+///
+/// The manager assumes a single, sequential driver and relies on these
+/// contracts:
+///
+/// - At most one source is active at a time. Activating a source closes
+///   the previously active one, exhausting the initializer list closes
+///   the final initializer, and [close] closes whatever remains.
+/// - The synchronizer scan cursor doubles as the active-slot pointer:
+///   from an activation ([nextAvailableSynchronizer] or
+///   [recreateCurrentSynchronizer]) until the next cursor mutation
+///   ([resetSynchronizerIndex] or [engageFdv1Fallback]), the cursor
+///   identifies the running synchronizer's slot. [isPrimarySynchronizer]
+///   and [blockCurrentSynchronizer] read the cursor and are only
+///   meaningful inside that window. After mutating the cursor, activate
+///   a new synchronizer before consulting either of them.
 final class SourceManager {
   final List<InitializerFactory> _initializerFactories;
   final List<SynchronizerSlot> _synchronizerSlots;
@@ -66,12 +81,14 @@ final class SourceManager {
 
   /// Get the next initializer and set it as the active source. Closes the
   /// previous active source. Returns null when all initializers are
-  /// exhausted.
+  /// exhausted; exhaustion also closes the final initializer, so a
+  /// terminal null leaves no source running.
   Initializer? nextInitializer() {
     if (_shutdown) return null;
 
     _initializerIndex += 1;
     if (_initializerIndex >= _initializerFactories.length) {
+      _closeActiveSource();
       return null;
     }
 
@@ -130,8 +147,10 @@ final class SourceManager {
     return synchronizer;
   }
 
-  /// Mark the current synchronizer as blocked (e.g. after a terminal
-  /// error).
+  /// Mark the active synchronizer's slot as blocked (e.g. after a
+  /// terminal error). Reads the scan cursor, so it must only be called
+  /// while the cursor identifies the active slot (see the class
+  /// contract).
   void blockCurrentSynchronizer() {
     if (_synchronizerIndex >= 0 &&
         _synchronizerIndex < _synchronizerSlots.length) {
@@ -140,14 +159,25 @@ final class SourceManager {
     }
   }
 
-  /// Reset the synchronizer scan position so the next call to
-  /// [nextAvailableSynchronizer] starts from the beginning.
+  /// Reset the synchronizer scan cursor so the next call to
+  /// [nextAvailableSynchronizer] starts from the beginning. After a
+  /// reset the cursor no longer identifies the active slot; activate a
+  /// new synchronizer before consulting [isPrimarySynchronizer] or
+  /// [blockCurrentSynchronizer].
   void resetSynchronizerIndex() {
     _synchronizerIndex = -1;
   }
 
-  /// Block all non-FDv1 synchronizers and unblock FDv1 synchronizers.
+  /// Block all non-FDv1 synchronizers, unblock the FDv1 fallback, and
+  /// reset the scan cursor so the next activation selects the fallback.
+  /// Does nothing when no FDv1 fallback slot is configured, since
+  /// blocking every slot without unblocking one would leave nothing to
+  /// activate. The active source keeps running until the next
+  /// activation closes it.
   void engageFdv1Fallback() {
+    if (!hasFdv1FallbackConfigured) {
+      return;
+    }
     for (final slot in _synchronizerSlots) {
       slot.state = slot.isFdv1Fallback
           ? SynchronizerSlotState.available
@@ -156,7 +186,10 @@ final class SourceManager {
     _synchronizerIndex = -1;
   }
 
-  /// True if the current synchronizer is the first available (primary).
+  /// True if the active synchronizer occupies the first available slot
+  /// (the primary). Reads the scan cursor, so it is only meaningful
+  /// while the cursor identifies the active slot (see the class
+  /// contract).
   bool get isPrimarySynchronizer =>
       _synchronizerIndex == _firstAvailableIndex();
 
@@ -165,8 +198,9 @@ final class SourceManager {
       .where((slot) => slot.state == SynchronizerSlotState.available)
       .length;
 
-  /// True if any synchronizer slot is marked as an FDv1 fallback.
-  bool get hasFdv1Fallback =>
+  /// True if any synchronizer slot is the FDv1 fallback, whether or not
+  /// it has been engaged.
+  bool get hasFdv1FallbackConfigured =>
       _synchronizerSlots.any((slot) => slot.isFdv1Fallback);
 
   /// Close the active source and mark the manager as shut down.

packages/common_client/test/data_sources/fdv2/source_manager_test.dart

@@ -76,6 +76,23 @@ void main() {
         reason: 'starting the second source closes the first');
   });
 
+  test('initializer exhaustion closes the final initializer', () {
+    final created = <RecordingInitializer>[];
+    final factory = InitializerFactory(create: (_) {
+      final initializer = RecordingInitializer();
+      created.add(initializer);
+      return initializer;
+    });
+
+    final manager = _manager(initializers: [factory]);
+
+    expect(manager.nextInitializer(), isNotNull);
+    expect(created.single.closed, isFalse);
+    expect(manager.nextInitializer(), isNull);
+    expect(created.single.closed, isTrue,
+        reason: 'a terminal null must leave no source running');
+  });
+
   test('synchronizers cycle through available slots and wrap around', () {
     final created = <RecordingSynchronizer>[];
     final manager = _manager(slots: [_slot(0, created), _slot(1, created)]);
@@ -150,7 +167,7 @@ void main() {
       _slot(1, fdv1Created, isFdv1Fallback: true),
     ]);
 
-    expect(manager.hasFdv1Fallback, isTrue);
+    expect(manager.hasFdv1FallbackConfigured, isTrue);
     expect(manager.availableSynchronizerCount, 1);
 
     manager.nextAvailableSynchronizer();
@@ -165,6 +182,19 @@ void main() {
         reason: 'the FDv2 tier is disabled after fallback');
   });
 
+  test('engaging FDv1 fallback without a configured slot does nothing', () {
+    final created = <RecordingSynchronizer>[];
+    final manager = _manager(slots: [_slot(0, created), _slot(1, created)]);
+
+    expect(manager.hasFdv1FallbackConfigured, isFalse);
+    manager.engageFdv1Fallback();
+
+    expect(manager.availableSynchronizerCount, 2,
+        reason: 'blocking every slot without unblocking a fallback would '
+            'leave nothing to activate');
+    expect(manager.nextAvailableSynchronizer(), isNotNull);
+  });
+
   test('close prevents further source creation', () {
     final created = <RecordingSynchronizer>[];
     final manager = _manager(slots: [_slot(0, created)]);