fix: stamp userId on traits_updated session events (#48)

* fix: stamp userId on traits_updated events

Slim session payloads omitted userId from traits_updated even though the
sink already had the runtime id. Collector could not associate a traits
bag with the current user unless setUserId also ran in the debounce window.

Co-authored-by: Deepak Gupta <deepakg202@users.noreply.github.com>

* chore: bump packages to 0.8.12

CI requires a tugboat version bump. Keep tugboat_dio on the same lockstep
line; adapter behavior is unchanged.

Co-authored-by: Deepak Gupta <deepakg202@users.noreply.github.com>

* fix: stamp userId and traits on all session events

user_changed and session_end now send the current runtime userId plus the
traits bag (or cached traitsId). Slim payloads had dropped those fields, so
the collector lost identity on user-only updates and on session close.

Co-authored-by: Deepak Gupta <deepakg202@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Deepak Gupta <deepakg202@users.noreply.github.com>

Author: deepakg202

docs/README.md

@@ -30,8 +30,8 @@ should be verified in their own repositories.
 
 ## Current compatibility
 
-- package version: `0.8.11`;
-- release line: `0.8.x` (`0.8.11` is a patch after `0.8.10`);
+- package version: `0.8.12`;
+- release line: `0.8.x` (`0.8.12` is a patch after `0.8.11`);
 - session JSON schema: `10`;
 - fingerprint schema: `6`;
 - minimum Dart SDK: `3.9.2`;

docs/integration/collector.md

@@ -197,11 +197,15 @@ not uploaded before this handshake completes.
 
 Session payloads may include:
 
+- `userId` — current runtime user on every session lifecycle event, including
+  `session_end`. After start, `null` is an explicit identity-clear on
+  `user_changed` / `session_identify` and the current (possibly anonymous)
+  identity on `traits_updated` and `session_end`;
 - `traits` — full traits snapshot when the host has set a bag (`session_start`,
-  `session_identify`, `traits_updated`, `user_changed`); the collector stores
-  the bag as-is (no server-side partial merge);
+  `session_identify`, `traits_updated`, `user_changed`, `session_end`); the
+  collector stores the bag as-is (no server-side partial merge);
 - `traitsId` — pass-through of a prior collector-issued id when no new bag is
-  sent (for example `session_end`, or `session_start` after only an id is
+  sent (for example `session_end` or `session_start` after only an id is
   cached). Ignored by the collector when `traits` is present.
 
 Accepted session responses (`202`) may return `traitsId`. The SDK caches that

docs/integration/production-replay-acceptance.md

@@ -12,7 +12,7 @@ database receipt alone as proof that a replay is correct.
 
 ## Current acceptance status
 
-The current SDK release candidate is **0.8.11**, which writes session schema
+The current SDK release candidate is **0.8.12**, which writes session schema
 **v10**. It preserves structural interaction replay while no longer emitting
 `controlValue`, `controlValueTransition`, `semanticAnnotation`, `stateAnchor`,
 or `stateSignature` in new writer output. It also does not emit `state_change`.
@@ -177,7 +177,7 @@ flows share a session, list the event IDs or timestamps that delimit each flow.
 
 Wait until the collector session has finalized and the replay is available in
 the production website. Filter to the recorded Blend build and SDK version
-under test (`0.8.11` for this release), then open every recorded session.
+under test (`0.8.12` for this release), then open every recorded session.
 
 For each interaction, inspect the actual replay UI and verify:
 

packages/tugboat/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.8.12
+
+Patch release after `0.8.11`.
+
+### Fixed
+
+- Stamp the current runtime `userId` and traits snapshot on every session
+  lifecycle POST (`session_start`, `session_identify`, `traits_updated`,
+  `user_changed`, `session_end`). Slim payloads had omitted identity from
+  traits-only updates and omitted both fields from `session_end`.
+
 ## 0.8.11
 
 Patch release after `0.8.10`.

packages/tugboat/README.md

@@ -5,10 +5,16 @@ 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.8.11`. Session JSON writers and readers use
+The current package version is `0.8.12`. Session JSON writers and readers use
 schema version `10` only. Structural fingerprints use fingerprint schema
 version `6`.
 
+## 0.8.12
+
+Session lifecycle POSTs now stamp the current runtime `userId` and traits on
+`session_start`, `session_identify`, `traits_updated`, `user_changed`, and
+`session_end`.
+
 ## 0.8.11
 
 The SDK now enforces a maximum cyclomatic complexity of 10. Internal helpers
@@ -99,7 +105,7 @@ The package requires Dart 3.9.2 or newer and Flutter 3.35.0 or newer.
 
 ```yaml
 dependencies:
-  tugboat_dio: ^0.8.11
+  tugboat_dio: ^0.8.12
 ```
 
 See `packages/tugboat_dio/README.md`.

packages/tugboat/example/pubspec.yaml

@@ -32,7 +32,7 @@ resolution: workspace
 dependencies:
   flutter:
     sdk: flutter
-  tugboat: ^0.8.11
+  tugboat: ^0.8.12
 
   # 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

@@ -399,16 +399,16 @@ class CollectorHttpSink implements TugboatCaptureSink {
     if (session == null) return _SendResult.accepted;
 
     final sessionId = _sessionIdForLifecycle(eventType, session.id);
-    final includeFullTraits = _includesFullTraits(eventType);
+    final traits = _traits;
 
     final body = mapTugboatSessionLifecycleToCollectorSession(
       eventType: eventType,
       sessionId: sessionId,
       triggeredAt: triggeredAt,
       config: _config,
       userId: _userId,
-      traits: includeFullTraits ? _traits : null,
-      traitsId: includeFullTraits ? null : _traitsId,
+      traits: traits,
+      traitsId: traits == null ? _traitsId : null,
       activeLocale: activeLocale,
     );
 
@@ -434,14 +434,6 @@ class CollectorHttpSink implements TugboatCaptureSink {
       ? localSessionId
       : _collectorSessionId ?? localSessionId;
 
-  bool _includesFullTraits(String eventType) =>
-      _traits != null &&
-      (_isSessionStart(eventType) ||
-          eventType ==
-              TugboatCollectorSessionEventType.sessionIdentify.wireValue ||
-          eventType ==
-              TugboatCollectorSessionEventType.traitsUpdated.wireValue);
-
   bool _isSessionStart(String eventType) =>
       eventType == TugboatCollectorSessionEventType.sessionStart.wireValue;
 

packages/tugboat/lib/src/collector_mapper.dart

@@ -158,20 +158,16 @@ Map<String, Object?> mapTugboatSessionLifecycleToCollectorSession({
   TugboatLocaleInfo? activeLocale,
 }) {
   final isSessionStart = _isSessionStart(eventType);
-  final carriesUserId = _carriesUserId(eventType);
-  final carriesTraits = _carriesTraits(eventType);
 
   final body = <String, Object?>{
     'sessionId': sessionId,
     'eventType': eventType,
     'triggeredAt': triggeredAt.toUtc().toIso8601String(),
+    // Only session_start inherits the configured startup identity. Later
+    // lifecycle records send the runtime id as-is, including null.
+    'userId': isSessionStart ? userId ?? config.userId : userId,
   };
 
-  if (carriesUserId) {
-    // Only session_start inherits the configured startup identity. Later
-    // lifecycle records use null as an explicit identity-clear operation.
-    body['userId'] = isSessionStart ? userId ?? config.userId : userId;
-  }
   if (isSessionStart) {
     final appInfo = Map<String, Object?>.from(config.appInfo.toJson())
       ..remove('installationId')
@@ -192,27 +188,15 @@ Map<String, Object?> mapTugboatSessionLifecycleToCollectorSession({
       'locale': locale,
     });
   }
-  if (carriesTraits) {
-    // Full traits bag wins over traitsId pass-through.
-    if (traits != null) body['traits'] = traits;
-    if (traits == null && traitsId != null) body['traitsId'] = traitsId;
-  }
+  // Full traits bag wins over traitsId pass-through.
+  if (traits != null) body['traits'] = traits;
+  if (traits == null && traitsId != null) body['traitsId'] = traitsId;
   return body;
 }
 
 bool _isSessionStart(String eventType) =>
     eventType == TugboatCollectorSessionEventType.sessionStart.wireValue;
 
-bool _carriesUserId(String eventType) =>
-    _isSessionStart(eventType) ||
-    eventType == TugboatCollectorSessionEventType.sessionIdentify.wireValue ||
-    eventType == TugboatCollectorSessionEventType.userChanged.wireValue;
-
-bool _carriesTraits(String eventType) =>
-    _isSessionStart(eventType) ||
-    eventType == TugboatCollectorSessionEventType.sessionIdentify.wireValue ||
-    eventType == TugboatCollectorSessionEventType.traitsUpdated.wireValue;
-
 /// Trailing digits from a tugboat frame id (`frame-12` → `12`).
 /// Returns null when the id does not end in digits.
 int? frameNumberFromId(String frameId) {

packages/tugboat/lib/src/sdk_version.dart

@@ -1,3 +1,3 @@
 // Keep this in sync with packages/tugboat/pubspec.yaml. The SDK version test
 // reads pubspec.yaml directly so release bumps fail fast if this drifts.
-const tugboatSdkVersion = '0.8.11';
+const tugboatSdkVersion = '0.8.12';

packages/tugboat/pubspec.yaml

@@ -1,7 +1,7 @@
 name: tugboat
 description: >-
   Screenshot-based session replay with compact interaction anchors for Tugboat.
-version: 0.8.11
+version: 0.8.12
 repository: https://github.com/blendto/tugboat-flutter
 issue_tracker: https://github.com/blendto/tugboat-flutter/issues
 homepage: https://github.com/blendto/tugboat-flutter