User traits

docs/README.md

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

docs/integration/collector.md

@@ -159,7 +159,7 @@ The SDK calls:
 
 | Request | Purpose |
 | --- | --- |
-| `POST /v1/sessions` | `session_start` and `session_end` lifecycle payloads |
+| `POST /v1/sessions` | Session lifecycle and identity: `session_start`, `session_end`, `traits_updated`, `user_changed` |
 | `POST /v1/events/batch` | JSON event batches |
 | `POST /v1/frames` | multipart PNG frame upload |
 
@@ -173,10 +173,26 @@ an accepted start response and reads its `sessionId`; events, frames, and the
 end lifecycle request then use that collector-issued ID. Events and frames are
 not uploaded before this handshake completes.
 
+Session payloads may include:
+
+- `traits` — full traits snapshot when the host has set a bag (`session_start`,
+  `traits_updated`, `user_changed`); 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
+  cached). Ignored by the collector when `traits` is present.
+
+Accepted session responses (`202`) may return `traitsId`. The SDK caches that
+value in process memory and stamps it onto subsequent event batches. Host apps
+register traits with `TugboatReplay.setTraits` and change the runtime user with
+`TugboatReplay.setUserId`. The SDK does **not** call `/v1/identify` or
+`/v1/events/identify`.
+
 Event payloads contain:
 
 - event ID, type, `atMs`, and absolute UTC `triggeredAt`;
 - optional user/session/run/action IDs;
+- optional `traitsId` (pass-through only; does not upsert the traits dictionary);
 - optional before/after frame references, related-event ID, and result;
 - serialized state and target anchors;
 - event-specific data under `payload`;

packages/tugboat/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 0.5.1
+
+### Added
+
+- **User traits via collector sessions** — `TugboatReplay.setTraits` posts
+  `eventType: traits_updated` on `POST /v1/sessions` with a full traits bag,
+  caches the response `traitsId`, and stamps it on event batches.
+  `TugboatReplay.setUserId` posts `user_changed` and updates the runtime user
+  id. Pre-set traits are included on the next `session_start`. No
+  `/v1/identify` route.
+
+### Changed
+
+- **`setUserId` skips unchanged ids** — calling `TugboatReplay.setUserId` /
+  `CollectorHttpSink.setUserId` with the same value as the current runtime
+  user id does not post `user_changed`.
+
 ## 0.5.0
 
 ### Breaking changes

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.0`. Session JSON writers emit schema
+The current package version is `0.5.1`. Session JSON writers emit schema
 version `9`; compatibility readers should accept versions `6` through
 `9`. Structural fingerprints use fingerprint schema version `6`.
 
@@ -153,11 +153,35 @@ Identity contract:
 - `captureSessionId` (`session.id`) — SDK-generated emitted evidence session
 - `collectorSessionId` — stamped after HTTP `session_start` acceptance
 - `explorationRunId` — exploration control-plane ID from config
+- `traitsId` — collector-issued traits dictionary id after `setTraits` / session responses
 
 `TugboatReplay.activeSessionId` remains as a deprecated alias for
 `activationRequestId`. Inspect `TugboatReplay.health` for sink/outbox/screenshot
 budget pressure without reading protected content.
 
+### User traits and user id
+
+When an HTTP collector is configured, register a full traits snapshot (not a
+partial merge) via `POST /v1/sessions`:
+
+```dart
+await TugboatReplay.setTraits({
+  'plan': 'pro',
+  'seatCount': 3,
+});
+
+await TugboatReplay.setUserId(currentUserId);
+```
+
+- `setTraits` sends `eventType: traits_updated` with the full bag when a capture
+  session is active, caches the response `traitsId`, and stamps that id onto
+  subsequent event batches.
+- `setUserId` sends `eventType: user_changed` (with the cached traits bag when
+  set) and updates the runtime user id on later sessions/events. Calls with the
+  same id as the current runtime user are ignored (no `user_changed` post).
+- Pre-activate calls are retained in memory and included on the next
+  `session_start`. There is no `/v1/identify` route.
+
 Optional durable HTTP delivery (Collector only, default off):
 
 ```dart
@@ -380,11 +404,12 @@ so it is suitable for health polling and cannot grow with session duration.
 
 ## Public surface
 
-The supported import exports `TugboatReplay`, `TugboatNavigatorObserver`,
-`TugboatReplayConfig`, capture/semantic/masking enums and policies, collector
-configuration and host helpers, markers (`TugboatSensitive`, `TugboatTag`,
-`TugboatSubView`, `TugboatInternal`), anchor and session models, the controller,
-and `TugboatExplorationTransport`.
+The supported import exports `TugboatReplay` (including `setTraits` /
+`setUserId`), `TugboatNavigatorObserver`, `TugboatReplayConfig`,
+capture/semantic/masking enums and policies, collector configuration and host
+helpers, markers (`TugboatSensitive`, `TugboatTag`, `TugboatSubView`,
+`TugboatInternal`), anchor and session models, the controller, and
+`TugboatExplorationTransport`.
 
 `TugboatCaptureSink` and the built-in sink implementations are internal today;
 config supports only the WebSocket and HTTP destinations above. A stable custom

packages/tugboat/example/pubspec.yaml

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