chore(tugboat): bump package version to 0.5.3 and update documentation

- Updated package version in `pubspec.yaml`, `README.md`, and `CHANGELOG.md` to reflect the new version 0.5.3.
- Adjusted compatibility information in documentation to align with the new version.
- Enhanced documentation to clarify the behavior of identity management during session lifecycles.

Author: deepakg202

docs/README.md

@@ -28,7 +28,7 @@ verified in their own repositories.
 
 ## Current compatibility
 
-- package version: `0.5.1`;
+- package version: `0.5.3`;
 - session JSON schema: `9`;
 - fingerprint schema: `6`;
 - minimum Dart SDK: `3.9.2`;

packages/tugboat/README.md

@@ -5,7 +5,7 @@ checkpoints around meaningful interactions, compact structural anchors, route
 transitions, scrolling evidence, and optional viewport semantic maps. Capture
 can be sent to the local exploration WebSocket, the HTTP collector, or both.
 
-The current package version is `0.5.1`. Session JSON writers emit schema
+The current package version is `0.5.3`. Session JSON writers emit schema
 version `9`; compatibility readers should accept versions `6` through
 `9`. Structural fingerprints use fingerprint schema version `6`.
 

packages/tugboat/example/pubspec.yaml

@@ -32,7 +32,7 @@ resolution: workspace
 dependencies:
   flutter:
     sdk: flutter
-  tugboat: ^0.5.1
+  tugboat: ^0.5.3
 
   # The following adds the Cupertino Icons font to your application.
   # Use with the CupertinoIcons class for iOS style icons.

packages/tugboat/lib/src/collector_http_sink.dart

@@ -19,12 +19,15 @@ class CollectorHttpSink implements TugboatCaptureSink {
     Map<String, dynamic>? initialTraits,
     String? initialTraitsId,
     String? initialUserId,
+    @visibleForTesting Duration? identityDebounceDuration,
   }) : _config = config,
        _userId = initialUserId ?? config.userId,
        _traits = initialTraits == null
            ? null
            : Map<String, dynamic>.from(initialTraits),
        _traitsId = initialTraitsId,
+       _identityDebounceDuration =
+           identityDebounceDuration ?? _defaultIdentityDebounceDuration,
        _client = _CollectorHttpClient(
          inner: client ?? http.Client(),
          apiKey: config.apiKey,
@@ -66,7 +69,9 @@ class CollectorHttpSink implements TugboatCaptureSink {
   /// billing, feature flags). Debouncing merges those into one lifecycle POST
   /// (`session_identify` when both change) instead of back-to-back
   /// `user_changed` / `traits_updated`.
-  static const _identityDebounceDuration = Duration(seconds: 3);
+  static const _defaultIdentityDebounceDuration = Duration(seconds: 3);
+
+  final Duration _identityDebounceDuration;
 
   Timer? _identityDebounceTimer;
   bool _userDirty = false;
@@ -199,10 +204,11 @@ class CollectorHttpSink implements TugboatCaptureSink {
 
   /// Registers a full traits snapshot with the collector.
   ///
-  /// No-ops when [traits] deep-equals the cached bag. While `session_start` is
-  /// still pending, updates memory only (folded into start at send time).
-  /// Otherwise debounces `traits_updated` or `session_identify` when combined
-  /// with a pending user change within [_identityDebounceDuration].
+  /// No-ops when [traits] equals the cached bag via [mapEquals] (shallow:
+  /// nested maps/lists compared with `==`). While `session_start` is still
+  /// pending, updates memory only (folded into start at send time). Otherwise
+  /// debounces `traits_updated` or `session_identify` when combined with a
+  /// pending user change within [_identityDebounceDuration].
   Future<void> setTraits(Map<String, dynamic> traits) async {
     if (_disposed) return;
     if (mapEquals(_traits, traits)) return;

packages/tugboat/lib/src/tugboat.dart

@@ -104,9 +104,10 @@ class TugboatReplay {
 
   /// Updates the runtime user id used on collector sessions and events.
   ///
-  /// No-ops when [userId] equals the current runtime id. When a capture session
-  /// is active and the id changes, debounces lifecycle posts (3s). Combined
-  /// with a pending traits change, posts `session_identify`; otherwise
+  /// Always records a remount override via [hasPendingUserIdOverride]. Collector
+  /// posting no-ops when [userId] equals the current runtime id. When a capture
+  /// session is active and the id changes, debounces lifecycle posts (3s).
+  /// Combined with a pending traits change, posts `session_identify`; otherwise
   /// `user_changed`. While `session_start` is still pending, updates memory only.
   static Future<void> setUserId(String? userId) async {
     _pendingUserId = userId;

packages/tugboat/test/collector_http_sink_test.dart

@@ -205,8 +205,27 @@ void main() {
     expect(headers['X-Sdk-Version'], tugboatSdkVersion);
   }
 
+  /// Short debounce so identity tests avoid ~3s wall-clock sleeps.
+  const testIdentityDebounce = Duration(milliseconds: 40);
+
+  CollectorHttpSink createIdentitySink({
+    Map<String, dynamic>? initialTraits,
+    String? initialTraitsId,
+    String? initialUserId,
+  }) {
+    return CollectorHttpSink(
+      config: configForServer(),
+      initialTraits: initialTraits,
+      initialTraitsId: initialTraitsId,
+      initialUserId: initialUserId,
+      identityDebounceDuration: testIdentityDebounce,
+    );
+  }
+
   Future<void> awaitIdentityDebounce() async {
-    await Future<void>.delayed(const Duration(milliseconds: 3100));
+    await Future<void>.delayed(
+      testIdentityDebounce + const Duration(milliseconds: 40),
+    );
   }
 
   test('collector defaults flush low-volume events every 3 seconds', () {
@@ -796,7 +815,7 @@ void main() {
     'setTraits posts traits_updated, caches traitsId, stamps next events',
     () async {
       sessionResponseTraitsId = 'trt_abc';
-      final sink = CollectorHttpSink(config: configForServer());
+      final sink = createIdentitySink();
       final session = createSession();
       sink.startSession(session);
       await Future<void>.delayed(const Duration(milliseconds: 50));
@@ -898,7 +917,7 @@ void main() {
     'new session_start includes traits bag after mid-session setTraits',
     () async {
       sessionResponseTraitsId = 'trt_mid';
-      final sink = CollectorHttpSink(config: configForServer());
+      final sink = createIdentitySink();
       sink.startSession(createSession(id: 'session-a'));
       await Future<void>.delayed(const Duration(milliseconds: 50));
       expect(sessionPosts, hasLength(1));
@@ -944,8 +963,7 @@ void main() {
 
   test('setUserId posts user_changed with cached traits', () async {
     sessionResponseTraitsId = 'trt_user';
-    final sink = CollectorHttpSink(
-      config: configForServer(),
+    final sink = createIdentitySink(
       initialTraits: {'plan': 'pro'},
       initialUserId: 'user_a',
     );
@@ -1018,10 +1036,7 @@ void main() {
   );
 
   test('setUserId no-ops when user id is unchanged', () async {
-    final sink = CollectorHttpSink(
-      config: configForServer(),
-      initialUserId: 'user_a',
-    );
+    final sink = createIdentitySink(initialUserId: 'user_a');
     sink.startSession(createSession());
     await Future<void>.delayed(const Duration(milliseconds: 50));
     expect(sessionPosts, hasLength(1));
@@ -1045,7 +1060,7 @@ void main() {
 
   test('setTraits no-ops when traits bag is unchanged', () async {
     sessionResponseTraitsId = 'trt_skip';
-    final sink = CollectorHttpSink(config: configForServer());
+    final sink = createIdentitySink();
     sink.startSession(createSession());
     await Future<void>.delayed(const Duration(milliseconds: 50));
     expect(sessionPosts, hasLength(1));
@@ -1071,7 +1086,7 @@ void main() {
     'setUserId then setTraits within debounce posts session_identify once',
     () async {
       sessionResponseTraitsId = 'trt_both';
-      final sink = CollectorHttpSink(config: configForServer());
+      final sink = createIdentitySink();
       sink.startSession(createSession());
       await Future<void>.delayed(const Duration(milliseconds: 50));
       expect(sessionPosts, hasLength(1));
@@ -1097,7 +1112,7 @@ void main() {
   );
 
   test('debounced identity uses first dirty time as triggeredAt', () async {
-    final sink = CollectorHttpSink(config: configForServer());
+    final sink = createIdentitySink();
     sink.startSession(createSession());
     await Future<void>.delayed(const Duration(milliseconds: 50));
 
@@ -1121,7 +1136,9 @@ void main() {
       isTrue,
     );
     expect(
-      triggeredAt.isBefore(afterDebounce.subtract(const Duration(seconds: 2))),
+      triggeredAt.isBefore(
+        afterDebounce.subtract(const Duration(milliseconds: 20)),
+      ),
       isTrue,
     );
     sink.dispose();
@@ -1130,12 +1147,12 @@ void main() {
   test(
     'coalesced identity triggeredAt reflects latest dirty mark when both change',
     () async {
-      final sink = CollectorHttpSink(config: configForServer());
+      final sink = createIdentitySink();
       sink.startSession(createSession());
       await Future<void>.delayed(const Duration(milliseconds: 50));
 
       await sink.setUserId('user_at');
-      await Future<void>.delayed(const Duration(milliseconds: 200));
+      await Future<void>.delayed(const Duration(milliseconds: 15));
       final beforeTraits = DateTime.now();
       await sink.setTraits({'plan': 'pro'});
       final afterTraits = DateTime.now();
@@ -1161,7 +1178,7 @@ void main() {
 
   test('endSession flushes debounced identity before session_end', () async {
     sessionResponseTraitsId = 'trt_end';
-    final sink = CollectorHttpSink(config: configForServer());
+    final sink = createIdentitySink();
     sink.startSession(createSession());
     await Future<void>.delayed(const Duration(milliseconds: 50));