Merge main and retarget native capture onto 0.8.12

Keep published 0.8.12 as the session identity stamp. Fold native CPU
capture and overlay identity into 0.8.13, and lockstep tugboat_dio.

Co-authored-by: Chinmay Kabi <chinmay@blend.to>

Author: cursoragent

docs/README.md

@@ -58,8 +58,8 @@ gates, canaries) are not listed below.
 
 ## Current compatibility
 
-- package version: `0.8.13` on this branch (`0.8.12` native capture line plus overlay identity);
-- native runtime: `com.tugboat.sdk:capture-runtime` `0.1.0` (local Maven, experimental);
+- package version: `0.8.13` (`0.8.x` patch after published `0.8.12`);
+- native runtime: `capture-runtime` `0.1.0` compiled from monorepo sources (unpublished);
 - planned first native-capable adapter: Flutter `0.9.0` after privacy and performance gates;
 - session JSON schema: `10`;
 - fingerprint schema: `6`;

docs/architecture/repository-scope.md

@@ -85,7 +85,7 @@ older OS versions report `unsupportedApi` and Flutter falls back.
 ## Flutter adapter scope
 
 `package:tugboat` stays the public Dart API. First native-capable version is
-planned as `0.9.0`. This Phase 0/1 line is `0.8.12` and does not enable
+planned as `0.9.0`. This Phase 0/1 line is `0.8.13` and does not enable
 native capture.
 
 In scope for the Android and Apple CPU betas:

docs/decisions/0008-independent-versioning.md

@@ -23,6 +23,6 @@ Public runtime API / C ABI changes bump `capture-runtime`. Adapter source
 changes bump `tugboat` and update
 [compatibility.md](../releases/compatibility.md).
 
-This `0.8.12` line is not the first native-capable public adapter; `0.9.0`
+This `0.8.13` line is not the first native-capable public adapter; `0.9.0`
 is planned after privacy and performance gates, still mapped to
 `capture-runtime` `0.1.x`.

docs/integration/collector.md

@@ -204,11 +204,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/performance/cpu-capture-baseline.md

@@ -79,7 +79,7 @@ pins, not with the host desktop toolchain.
 | Flutter min Gradle (3.47.2) | 8.14.0 |
 | Example min / compile SDK | min 24, compile/target 36 |
 | Package constraints | Dart `^3.9.2`, Flutter `>=3.35.0` |
-| tugboat | 0.8.12 (capture path unchanged from 0.8.11) |
+| tugboat | 0.8.13 (default Flutter capture path unchanged from 0.8.12) |
 
 Host CMake 3.28.3 and host clang 18.1.3 were present on the lab machine. They
 are not the Android compile pin.

docs/releases/compatibility.md

@@ -3,7 +3,7 @@
 | Adapter | Adapter version | Native runtime |
 | --- | --- | --- |
 | Flutter `tugboat` | 0.8.13 | Android `capture-runtime` 0.1.x compiled from monorepo sources (unpublished Maven is not required). Apple `TugboatCaptureRuntime` 0.1.x compiled from monorepo sources (unpublished CocoaPod is not required). Plugin iOS floor 12; native capture still reports unsupported below iOS 15. |
-| Flutter `tugboat` | 0.8.12 | Android `com.tugboat.sdk:capture-runtime` 0.1.x (local Maven; experimental). Apple `TugboatCaptureRuntime` 0.1.x (local CocoaPod / SwiftPM; experimental). |
+| Flutter `tugboat` | 0.8.12 | none (Flutter `flutterRepaintBoundary` only; session identity stamp patch) |
 | Flutter `tugboat` | 0.9.0 (planned) | Android `capture-runtime` 0.1.x and Apple `TugboatCaptureRuntime` 0.1.x |
 | Apple `TugboatCaptureRuntime` | 0.1.0 | unpublished local CocoaPod / SwiftPM; iOS 15 live Flutter-layer CPU path |
 | `@tugboat/react-native` | — | not started |

internal/docs/canaries/production-replay-acceptance.md

@@ -12,11 +12,10 @@ database receipt alone as proof that a replay is correct.
 
 ## Current acceptance status
 
-The current SDK release candidate is **0.8.12**, which writes session schema
-**v10**. Capture, session schema, and fingerprints are unchanged from `0.8.11`.
-Native CPU screenshot capture is opt-in and **out of this production gate**
-until device privacy rows and performance gates pass. Production cohorts must
-keep `TugboatScreenshotCaptureBackend.flutterRepaintBoundary`.
+The current SDK release candidate is **0.8.13**, which writes session schema
+**v10**. Native CPU screenshot capture is opt-in and **out of this production
+gate** until device privacy rows and performance gates pass. Production
+cohorts must keep `TugboatScreenshotCaptureBackend.flutterRepaintBoundary`.
 
 It preserves structural interaction replay while no longer emitting
 `controlValue`, `controlValueTransition`, `semanticAnnotation`, `stateAnchor`,
@@ -182,7 +181,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.13` for this release), then open every recorded session.
 
 For each interaction, inspect the actual replay UI and verify:
 

platforms/android/CHANGELOG.md

@@ -9,6 +9,7 @@ Initial local Maven artifact `com.tugboat.sdk:capture-runtime:0.1.0`.
 - Platform JPEG quality 80 and SHA-256 of the JPEG.
 - Public API recorded in `api.txt`.
 
-Not published to Maven Central. Flutter 0.8.12 consumes this from
-`.local-maven` when the example/plugin is built after
-`tool/ci/build-android-runtime.sh`.
+Not published to Maven Central. Flutter 0.8.13 compiles this from monorepo
+sources. Local Maven (`.local-maven` after
+`tool/ci/build-android-runtime.sh`) is only for the standalone native Android
+sample.

sdks/flutter/packages/tugboat/CHANGELOG.md

@@ -1,6 +1,6 @@
 ## 0.8.13
 
-Patch release after `0.8.12`.
+Patch release after published `0.8.12`.
 
 ### Fixed
 
@@ -15,6 +15,20 @@ Patch release after `0.8.12`.
 
 ### Added
 
+- Convert `tugboat` into a Flutter plugin with an experimental opt-in native
+  CPU capture backend (`nativeCpuExperimental`) on Android (`PixelCopy`) and
+  iOS (live Flutter-layer rendering). The default remains
+  `flutterRepaintBoundary`, with automatic fallback when native capture is
+  unavailable or fails safely.
+- Record a regenerable JPEG size envelope for the current Dart encoder so the
+  native CPU capture path can compare codec output against the same buffers.
+- Native `encodeMicros` is the Pigeon capture round-trip only. Nested native
+  stage timings stay on the backend trace so `TugboatFrame.captureMicros` does
+  not double-count PixelCopy, dHash, JPEG, and SHA-256.
+- Published `TugboatFrame` records include `requestedBackend`,
+  `resolvedBackend`, and `fallbackReason` so production screenshots identify
+  Flutter vs native without `capture_diagnostic` events. HTTP `/v1/frames` is
+  still JPEG-only.
 - `route_change` now splits route identity (`routeName`, `routeType`,
   `routeNamed`, and the matching `from*` fields) without changing `route`,
   `fromRoute`, or `navigation`.
@@ -25,34 +39,22 @@ Patch release after `0.8.12`.
 - Claimed route changes copy `causeTargetFingerprint` and `causeGesture` from
   the interaction. Overlay after-frames still capture under exploration
   screenshot suppression when `overlayKind` is not `page`.
+- Raise the example Android wrapper to Gradle 8.14 / AGP 8.11.1 / Kotlin 2.2.20
+  so Flutter 3.47 can build a release APK for device-lab capture gates.
+- Document the mobile monorepo, native capture contracts, fallback, coverage,
+  and path-aware version / license / API-surface checks. Native capture stays
+  experimental.
 
 ## 0.8.12
 
 Patch release after `0.8.11`.
 
-### Added
+### Fixed
 
-- Record a regenerable JPEG size envelope for the current Dart encoder so the
-  native CPU capture path can compare codec output against the same buffers.
-- Convert `tugboat` into a Flutter plugin with an experimental opt-in Android
-  native CPU capture backend (`nativeCpuExperimental`). The default remains
-  `flutterRepaintBoundary`, with automatic fallback when native capture is
-  unavailable or fails safely.
-- Add an experimental iOS native CPU path in `TugboatCaptureRuntime` 0.1.0
-  (SwiftPM + CocoaPod). It renders the live Flutter layer so Metal content is
-  present, then uses C++ masks/dHash and ImageIO JPEG. `drawHierarchy` remains
-  an optional UIKit compatibility mode. Unpublished.
-- Native `encodeMicros` is the Pigeon capture round-trip only. Nested native
-  stage timings stay on the backend trace so `TugboatFrame.captureMicros` does
-  not double-count PixelCopy, dHash, JPEG, and SHA-256.
-- Published `TugboatFrame` records include `requestedBackend`, `resolvedBackend`,
-  and `fallbackReason` so production screenshots identify Flutter vs native
-  without `capture_diagnostic` events. HTTP `/v1/frames` is still JPEG-only.
-- Raise the example Android wrapper to Gradle 8.14 / AGP 8.11.1 / Kotlin 2.2.20
-  so Flutter 3.47 can build a release APK for device-lab capture gates.
-- Document the mobile monorepo, native capture contracts, fallback, coverage,
-  and path-aware version / license / API-surface checks. Native capture stays
-  experimental; Flutter remains on the 0.8.12 line.
+- 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
 

sdks/flutter/packages/tugboat/README.md

@@ -11,6 +11,10 @@ version `6`.
 
 ## 0.8.13
 
+Experimental opt-in native CPU screenshot capture (`nativeCpuExperimental`) on
+Android (`PixelCopy`) and iOS (live Flutter-layer rendering). Keep
+`TugboatScreenshotCaptureBackend.flutterRepaintBoundary` in production.
+
 `route_change` now carries split route identity (`routeName` / `routeType` /
 `routeNamed`), a closed overlay kind (`page`, `sheet`, `dialog`, `popup`,
 `unknown`), presentation-parent fields for overlay pushes, and a bounded
@@ -20,11 +24,9 @@ screenshot suppression.
 
 ## 0.8.12
 
-Capture, session schema, and fingerprints are unchanged from `0.8.11`. This
-patch records the Dart JPEG size envelope used as the native CPU capture
-baseline and exposes an experimental opt-in native CPU backend on Android
-(`PixelCopy`) and iOS (live Flutter-layer rendering). Keep
-`TugboatScreenshotCaptureBackend.flutterRepaintBoundary` in production.
+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
 
@@ -116,7 +118,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.13
 ```
 
 See `../tugboat_dio/README.md`.