feat: Debounce lifecycle, network, and setMode signals

[tanderson-ld]

Summary

Implements CSFDV2 CONNMODE section 3.5 state-change debouncing for the Flutter SDK. Lifecycle, network, and user-requested-mode signals accumulate over a configurable window (default 1 second) before driving automatic mode resolution. Per spec 3.5.6, identify calls do not participate.

Stacked on #280 (-flutter); rebase onto main once that merges.

StateDebounceManager (common_client/data_sources/fdv2)

• DebouncedState holds networkAvailable, inForeground, requestedMode.
• Per-setter early-return on unchanged value.
• Duration.zero bypasses the timer (synchronous fire) for tests and FDv1-style immediate behavior.
• Injectable DebounceTimerFactory for fake_async-based testing.
• close() cancels any pending timer; setters after close are no-ops.

Flutter ConnectionManager integration

• ConnectionManagerConfig.debounceWindow (default 1s).
• Lifecycle and network listeners feed the debouncer instead of calling _handleState() directly. The debouncer's reconcile callback invokes _handleState() once the window closes.
• setMode(ConnectionMode? mode) sets _modeOverride synchronously (CONNMODE 2.0.3 -- automatic transitions suppressed immediately) and pushes through the debouncer (CONNMODE 3.5.5 -- mode application is debounced).
• Foreground -> background transition flushes synchronously per CONNMODE 3.3.1 (the process may be killed before the window closes); the debouncer still handles the resulting mode change.
• Network-availability propagation to the destination remains synchronous; only the mode-resolution outcome is debounced.

Tests

• state_debounce_manager_test: single-fire, flap-and-return, multi-axis change, requested-mode, close cancellation, immediate mode.
• connection_manager_test: existing assertions pinned to Duration.zero (preserve FDv1-style synchronous semantics); three new debounce-window tests using fake_async.

Resolves the two TODO sites in connection_manager.dart previously tagged SDK-2187.

---

Note

Medium Risk
Changes when the SDK reconnects or changes mode during rapid lifecycle/network flaps; critical paths (background flush, offline, sync network availability) are explicitly preserved but timing of mode switches shifts by up to the debounce window.

Overview
Adds StateDebounceManager in common_client to batch lifecycle, network, and user setMode signals over a configurable window (default 1s) before a single reconcile callback, with Duration.zero for immediate/test behavior and exports from the public package API.

Flutter ConnectionManager now routes lifecycle and network updates through the debouncer (replacing direct _handleState on every signal), adds debounceWindow and initialApplicationState on config, seeds lifecycle from FlutterStateDetector.initialApplicationState at client startup, and keeps foreground→background flush and destination network availability synchronous while debouncing resolved mode application. setMode sets the override immediately but applies the resolved mode after debounce; offline still bypasses debouncing.

Tests add state_debounce_manager_test, pin existing connection_manager_test expectations to Duration.zero, and add fake_async debounce integration cases.

^{Reviewed by Cursor Bugbot for commit 8edb1a6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[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 8edb1a6. Configure here.}

[cursor]

Startup never reconciles mode

Medium Severity

After construction, ConnectionManager only applies resolved mode when the debouncer fires, and StateDebounceManager skips scheduling when lifecycle/network values match its seeded pending state. Initial detector events that confirm foreground plus available network therefore never trigger _handleState, so automatic resolution (e.g. background launch with runInBackground: false) may not run until a later change plus the debounce window.

Additional Locations (1)

• packages/common_client/lib/src/data_sources/fdv2/state_debounce_manager.dart#L95-L109

 

^{Reviewed by Cursor Bugbot for commit 8edb1a6. Configure here.}

[cursor]

Raw exception text in logs

Low Severity

The reconcile error handler logs the caught value with string interpolation ($error), which can embed sensitive request URIs or other PII from exception toString() output instead of a fixed, categorized message.

 

^{Triggered by learned rule: Never expose raw exception toString() in logs or StatusEvent messages in data sources}

^{Reviewed by Cursor Bugbot for commit 8edb1a6. Configure here.}