@scalebun/react-native 1.10.6 → 1.11.0

package/src/analytics/automaticEvents.ts

@@ -39,6 +39,8 @@ export type AutomaticEventName =
 export interface AutomaticEvent {
     name: AutomaticEventName;
     properties: Record<string, unknown>;
+    /** Original observation time. Delivery can be delayed while native coordinates resolve. */
+    timestamp?: number;
 }
 
 type AutomaticEventListener = (event: AutomaticEvent) => void;
@@ -60,10 +62,12 @@ function compactProperties(
 export function emitAutomaticEvent(
     name: AutomaticEventName,
     properties?: Record<string, unknown>,
+    timestamp?: number,
 ): void {
     const event: AutomaticEvent = {
         name,
         properties: compactProperties(properties),
+        timestamp,
     };
     if (listeners.size === 0) {
         pending.push(event);

package/src/core/config/schema.ts

@@ -85,6 +85,10 @@ type Field =
     | { kind: 'bool'; def?: boolean; opt?: true }
     | { kind: 'num'; min?: number; max?: number; int?: true; def?: number; opt?: true }
     | { kind: 'str'; min?: number; opt?: true }
+    // Array of strings. Message parity target is the vendored z's
+    // `z.array(z.string())`: "Expected array, received X" at the field path,
+    // "Expected string, received X" at [...path, index] per bad element.
+    | { kind: 'strArr'; opt?: true }
     | { kind: 'enum'; values: readonly string[]; opt?: true }
     | { kind: 'any'; def: () => unknown }
     | { kind: 'obj'; shape: Record<string, Field>; def?: true; opt?: true };
@@ -198,6 +202,11 @@ const SHAPE: Record<string, Field> = {
             checkOnForeground: bool(true),
             channelOverride: { kind: 'str', opt: true },
             publicSigningKey: { kind: 'str', opt: true },
+            // Rotation support: several pinned keys, any of which may verify a
+            // bundle. Ship a build pinning [old, new], re-sign server-side with
+            // new, drop old next release — no emergency store submission when a
+            // key must be replaced. Merged with publicSigningKey by the facade.
+            publicSigningKeys: { kind: 'strArr', opt: true },
             mandatoryBlocksUi: bool(false),
         },
     },
@@ -232,9 +241,11 @@ function parseField(
                   ? 'Expected number, received undefined'
                   : field.kind === 'str'
                     ? 'Expected string, received undefined'
-                    : field.kind === 'enum'
-                      ? "Invalid enum value. Expected " + field.values.map((v) => `'${v}'`).join(' | ')
-                      : 'Expected object, received undefined',
+                    : field.kind === 'strArr'
+                      ? 'Expected array, received undefined'
+                      : field.kind === 'enum'
+                        ? "Invalid enum value. Expected " + field.values.map((v) => `'${v}'`).join(' | ')
+                        : 'Expected object, received undefined',
         );
     }
 
@@ -250,6 +261,20 @@ function parseField(
                 return fail(`String must contain at least ${field.min} character(s)`);
             }
             return { ok: true, value: input, present: true };
+        case 'strArr': {
+            // Mirrors the vendored ArraySchema exactly: element failures are
+            // reported at their index and fail the whole field (no partial
+            // arrays reach the output).
+            if (!Array.isArray(input)) return fail(`Expected array, received ${typeofName(input)}`);
+            let allOk = true;
+            for (let i = 0; i < input.length; i++) {
+                if (typeof input[i] !== 'string') {
+                    issues.push({ path: [...path, i], message: `Expected string, received ${typeofName(input[i])}` });
+                    allOk = false;
+                }
+            }
+            return allOk ? { ok: true, value: [...input], present: true } : { ok: false, present: true };
+        }
         case 'num':
             if (typeof input !== 'number' || Number.isNaN(input)) {
                 return fail(`Expected number, received ${typeofName(input)}`);
@@ -381,6 +406,8 @@ export interface ScaleBunConfig {
         checkOnForeground: boolean;
         channelOverride?: string;
         publicSigningKey?: string;
+        /** Additional pinned keys for rotation; unioned with publicSigningKey. */
+        publicSigningKeys?: string[];
         mandatoryBlocksUi: boolean;
     };
 }

package/src/core/constants/version.ts

@@ -1,6 +1,11 @@
 /**
  * ScaleBun SDK version. Sent with the session-start envelope so the dashboard
  * can attribute telemetry to the SDK build that produced it.
- * Keep in sync with package.json "version".
+ * Keep in sync with package.json "version" — `version.test.ts` fails when they drift.
+ *
+ * Why the test matters: the 1.11.0 bump missed this line, so the build would have reported itself as
+ * 1.10.6. Every "is the release live, and on what share of traffic" question is answered from this
+ * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
+ * version was introduced to solve.
  */
-export const SDK_VERSION = '1.10.6';
+export const SDK_VERSION = '1.11.0';

package/src/features/journey/ScaleBunDebugRoot.tsx

@@ -28,9 +28,14 @@ import React, {
     type ReactNode,
 } from 'react';
 import { View, NativeEventEmitter, NativeModules } from 'react-native';
-import { emitAutomaticEvent } from '../../analytics/automaticEvents';
 import { resolveTouchTarget, describeTouchTarget } from './touchTarget';
 import { resolvePlatformOS } from '../../core/context/device';
+import {
+    INTERACTION_PROTOCOL_VERSION,
+    generateInteractionId,
+    nearestInteractionStart,
+    type InteractionStartContext,
+} from './interactionProtocol';
 
 // ─── Lazy imports to avoid native module cascade at load time ────────────────
 // We only import TYPE references at the top level; actual modules are require()'d
@@ -60,6 +65,11 @@ interface ScaleBunDebugRootProps {
     suppressDeprecationWarning?: boolean;
 }
 
+interface TouchStartContext extends InteractionStartContext {
+    locationX?: number;
+    locationY?: number;
+}
+
 export function ScaleBunDebugRoot({
     children,
     navigationRef,
@@ -270,7 +280,9 @@ export function ScaleBunDebugRoot({
     // and forwards them to SessionManager as USER_ACTION events.
     const lastNativeTouchTsRef = useRef<number>(0);
     const nativeTrackingConfirmedRef = useRef<boolean>(false);
-    const pendingJsEmitRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const touchStartRef = useRef<TouchStartContext | null>(null);
+    const interactionStartsRef = useRef<TouchStartContext[]>([]);
+    const pendingJsEmitsRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
 
     useEffect(() => {
         let subscription: any = null;
@@ -284,10 +296,19 @@ export function ScaleBunDebugRoot({
                     lastNativeTouchTsRef.current = Date.now();
                     nativeTrackingConfirmedRef.current = true;
 
-                    // Cancel any pending JS emission — native event wins
-                    if (pendingJsEmitRef.current !== null) {
-                        clearTimeout(pendingJsEmitRef.current);
-                        pendingJsEmitRef.current = null;
+                    const nativeOccurredAt =
+                        typeof event.occurredAt === 'number'
+                            ? event.occurredAt
+                            : (typeof event.timestamp === 'number' ? event.timestamp : Date.now()) -
+                              (typeof event.durationMs === 'number' ? event.durationMs : 0);
+                    const start = nearestInteractionStart(interactionStartsRef.current, nativeOccurredAt);
+
+                    // Cancel only this physical touch's fallback. A single timer used to cancel a
+                    // previous rapid tap and silently lose it on devices without native tracking.
+                    if (start) {
+                        const pending = pendingJsEmitsRef.current.get(start.interactionId);
+                        if (pending !== undefined) clearTimeout(pending);
+                        pendingJsEmitsRef.current.delete(start.interactionId);
                     }
 
                     const { SessionManager } = require('../session/SessionManager');
@@ -306,6 +327,15 @@ export function ScaleBunDebugRoot({
                     } catch { /* no-throw */ }
 
                     (sm as any).onGestureDetected(event.gestureType || 'tap', {
+                        interactionId: event.interactionId || start?.interactionId || generateInteractionId(),
+                        interactionProtocol: event.interactionProtocol || INTERACTION_PROTOCOL_VERSION,
+                        occurredAt: nativeOccurredAt,
+                        ui: start?.ui,
+                        stateStatus: start?.stateStatus ?? 'not_captured',
+                        target: start?.target,
+                        targetId: start?.targetId,
+                        screenName: start?.screenName,
+                        emitAutomaticAnalytics: start?.emitAutomaticAnalytics ?? captureAutomaticInteractions,
                         x: event.rawX,
                         y: event.rawY,
                         // Use the actual native end coords when present, not the down
@@ -334,11 +364,12 @@ export function ScaleBunDebugRoot({
 
         return () => {
             try { subscription?.remove(); } catch { /* no-throw */ }
+            for (const timer of pendingJsEmitsRef.current.values()) clearTimeout(timer);
+            pendingJsEmitsRef.current.clear();
         };
-    }, []);
+    }, [captureAutomaticInteractions]);
 
     // ─── Touch Tracking State ───────────────────────────────────────────
-    const touchStartRef = useRef<{ x: number; y: number; ts: number } | null>(null);
 
     // On-screen rect of the root view — the EXACT view the native screenshot
     // captures. Normalizing pageX/pageY against this rect makes JS-fallback taps
@@ -377,7 +408,36 @@ export function ScaleBunDebugRoot({
     const handleTouchStart = (e: any) => {
         try {
             const touch = e.nativeEvent;
-            touchStartRef.current = { x: touch.pageX, y: touch.pageY, ts: Date.now() };
+            const target = resolveTouchTarget(e);
+            let ui: string | undefined;
+            let screenName: string | undefined;
+            try {
+                const { uiStateSignature } = require('./uiState');
+                ui = uiStateSignature();
+            } catch { /* no-throw */ }
+            try {
+                const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
+                screenName = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
+            } catch { /* no-throw */ }
+            const start: TouchStartContext = {
+                interactionId: generateInteractionId(),
+                occurredAt: Date.now(),
+                x: touch.pageX,
+                y: touch.pageY,
+                locationX: touch.locationX,
+                locationY: touch.locationY,
+                target: describeTouchTarget(target),
+                targetId: target?.testID,
+                screenName,
+                ui,
+                stateStatus: ui ? 'captured_nonempty' : 'not_instrumented',
+                emitAutomaticAnalytics: captureAutomaticInteractions,
+            };
+            touchStartRef.current = start;
+            interactionStartsRef.current = interactionStartsRef.current
+                .filter((candidate) => start.occurredAt - candidate.occurredAt < 5000)
+                .concat(start)
+                .slice(-8);
         } catch { /* no-throw */ }
     };
 
@@ -413,16 +473,24 @@ export function ScaleBunDebugRoot({
             // WHAT was tapped, resolved from the React fiber on the touch event. Without this the tap
             // carries only coordinates, so every tap in the app groups into one row per gesture type.
             // Defensive by construction — returns undefined rather than throwing (see touchTarget.ts).
-            const tapped = describeTouchTarget(resolveTouchTarget(e));
+            const tapped = start?.target ?? describeTouchTarget(resolveTouchTarget(e));
 
             const gestureDetails: any = {
                 target: tapped,
-                x: touch.pageX,
-                y: touch.pageY,
-                pageX: touch.pageX,
-                pageY: touch.pageY,
-                locationX: touch.locationX,
-                locationY: touch.locationY,
+                interactionId: start?.interactionId ?? generateInteractionId(),
+                interactionProtocol: INTERACTION_PROTOCOL_VERSION,
+                occurredAt: start?.occurredAt ?? Date.now(),
+                ui: start?.ui,
+                stateStatus: start?.stateStatus ?? 'not_captured',
+                targetId: start?.targetId,
+                screenName: start?.screenName,
+                emitAutomaticAnalytics: start?.emitAutomaticAnalytics ?? captureAutomaticInteractions,
+                x: start?.x ?? touch.pageX,
+                y: start?.y ?? touch.pageY,
+                pageX: start?.x ?? touch.pageX,
+                pageY: start?.y ?? touch.pageY,
+                locationX: start?.locationX ?? touch.locationX,
+                locationY: start?.locationY ?? touch.locationY,
                 viewportWidth: vpW > 0 ? vpW : undefined,
                 viewportHeight: vpH > 0 ? vpH : undefined,
             };
@@ -434,8 +502,8 @@ export function ScaleBunDebugRoot({
             // measureInWindow returns rootRect.y = statusBarHeight, so subtracting it
             // double-counts the status bar and pushes every marker upward.
             if (rootRect && rootRect.w > 0 && rootRect.h > 0) {
-                const nx = Math.max(0, Math.min(1, touch.pageX / rootRect.w));
-                const ny = Math.max(0, Math.min(1, touch.pageY / rootRect.h));
+                const nx = Math.max(0, Math.min(1, (start?.x ?? touch.pageX) / rootRect.w));
+                const ny = Math.max(0, Math.min(1, (start?.y ?? touch.pageY) / rootRect.h));
                 gestureDetails.normalizedX = nx;
                 gestureDetails.normalizedY = ny;
                 gestureDetails.normalizedPrecomputed = true;
@@ -472,7 +540,7 @@ export function ScaleBunDebugRoot({
                 const dx = touch.pageX - start.x;
                 const dy = touch.pageY - start.y;
                 const dist = Math.sqrt(dx * dx + dy * dy);
-                const duration = Date.now() - start.ts;
+                const duration = Date.now() - start.occurredAt;
                 gestureDetails.duration = duration;
 
                 if (dist >= 15) {
@@ -494,44 +562,17 @@ export function ScaleBunDebugRoot({
                 }
             }
 
-            const targetInfo = _extractTarget(e);
-            gestureDetails.target = targetInfo?.testId || targetInfo?.accessibilityLabel;
-
-            if (captureAutomaticInteractions) {
-                let screen: string | undefined;
-                try {
-                    const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
-                    screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
-                } catch { /* no-throw */ }
-                emitAutomaticEvent('element_interacted', {
-                    gesture_type: gestureType,
-                    screen_name: screen,
-                    // testID/nativeID is an author-controlled stable identifier.
-                    // Accessibility labels and rendered text are deliberately omitted.
-                    target_id: targetInfo?.testId,
-                    normalized_x: gestureDetails.normalizedX,
-                    normalized_y: gestureDetails.normalizedY,
-                    direction: gestureDetails.direction,
-                    duration_ms: gestureDetails.duration,
-                });
-            }
-
             // Feed the Engage gesture detector (rage_tap / dead_tap) — only committed
             // taps, not swipes/scrolls/long-presses. Pure JS, cross-platform; emits the
             // unified `$gesture` signal the engage trigger engine listens for.
             if (gestureType === 'tap') {
                 try {
                     const { gestureTriggerDetector } = require('../engage/gestureTriggerDetector');
-                    let screen: string | undefined;
-                    try {
-                        const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
-                        screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
-                    } catch { /* no-throw */ }
                     gestureTriggerDetector.recordTap({
-                        x: touch.pageX,
-                        y: touch.pageY,
-                        hasTarget: !!(targetInfo?.testId || targetInfo?.accessibilityLabel),
-                        screen,
+                        x: start?.x ?? touch.pageX,
+                        y: start?.y ?? touch.pageY,
+                        hasTarget: !!(start?.targetId || start?.target),
+                        screen: start?.screenName,
                     });
                 } catch { /* no-throw */ }
             }
@@ -546,7 +587,7 @@ export function ScaleBunDebugRoot({
             // screenshot capture view). Three-tier suppression:
             //   1. Native confirmed active → skip JS entirely (native handles all touches)
             //   2. Native event within 300ms → skip (existing dedup)
-            //   3. First touch (native not yet confirmed) → defer 200ms to let native arrive
+            //   3. First touch (native not yet confirmed) → defer 600ms to let native arrive
             const sinceNative = Date.now() - lastNativeTouchTsRef.current;
             if (nativeTrackingConfirmedRef.current) {
                 // Native tracker is active — skip JS path entirely
@@ -557,11 +598,9 @@ export function ScaleBunDebugRoot({
                 // If native fires during the delay, it cancels this pending emit.
                 const capturedType = gestureType;
                 const capturedDetails = { ...gestureDetails };
-                if (pendingJsEmitRef.current !== null) {
-                    clearTimeout(pendingJsEmitRef.current);
-                }
-                pendingJsEmitRef.current = setTimeout(() => {
-                    pendingJsEmitRef.current = null;
+                const interactionId = capturedDetails.interactionId as string;
+                const timer = setTimeout(() => {
+                    pendingJsEmitsRef.current.delete(interactionId);
                     if (nativeTrackingConfirmedRef.current) return;
                     try {
                         const { SessionManager } = require('../session/SessionManager');
@@ -583,6 +622,7 @@ export function ScaleBunDebugRoot({
                     // devices with no native tracker at all it merely delays a background emission,
                     // which nothing user-visible waits on.
                 }, 600);
+                pendingJsEmitsRef.current.set(interactionId, timer);
             }
 
             touchStartRef.current = null;
@@ -702,25 +742,6 @@ export function useScaleBunScreen(name: string): void {
     }, [name, manager]);
 }
 
-// ─── Helpers ────────────────────────────────────────────────────────────────
-
-function _extractTarget(e: any): { testId?: string; accessibilityLabel?: string; text?: string } | undefined {
-    try {
-        const target = e?.target;
-        if (!target) return undefined;
-
-        // React Native nativeEvent target properties
-        const props = target._internalFiberInstanceHandleDEV?.memoizedProps ?? {};
-        return {
-            testId: props.testID || props.nativeID || undefined,
-            accessibilityLabel: props.accessibilityLabel || undefined,
-            text: undefined,
-        };
-    } catch {
-        return undefined;
-    }
-}
-
 // ─── Styles ─────────────────────────────────────────────────────────────────
 // IMPORTANT: Do NOT use StyleSheet.create() here.
 // In RN 0.84 bridgeless mode, StyleSheet.create() calls

package/src/features/journey/interactionProtocol.ts

@@ -0,0 +1,65 @@
+/** One physical interaction, shared by replay and analytics projections. */
+export const INTERACTION_PROTOCOL_VERSION = 1;
+
+export type InteractionStateStatus =
+    | 'captured_empty'
+    | 'captured_nonempty'
+    | 'not_captured'
+    | 'not_instrumented';
+
+export interface InteractionStartContext {
+    interactionId: string;
+    occurredAt: number;
+    x: number;
+    y: number;
+    target?: string;
+    targetId?: string;
+    screenName?: string;
+    ui?: string;
+    stateStatus: InteractionStateStatus;
+    emitAutomaticAnalytics: boolean;
+}
+
+export function generateInteractionId(): string {
+    return `ixj-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** Match a native bridge event to the JS evidence sampled at the same finger-down. */
+export function nearestInteractionStart<T extends InteractionStartContext>(
+    starts: readonly T[],
+    occurredAt: number,
+    toleranceMs = 1500,
+): T | undefined {
+    let best: T | undefined;
+    let bestDelta = toleranceMs + 1;
+    for (const start of starts) {
+        const delta = Math.abs(start.occurredAt - occurredAt);
+        if (delta < bestDelta) {
+            best = start;
+            bestDelta = delta;
+        }
+    }
+    return bestDelta <= toleranceMs ? best : undefined;
+}
+
+/** Analytics is a projection of the same evidence; no second click is invented. */
+export function automaticInteractionProperties(
+    payload: Record<string, unknown>,
+    screenName: string | undefined,
+    canonicalMirror: boolean,
+): Record<string, unknown> {
+    return {
+        gesture_type: payload.gestureType,
+        screen_name: screenName,
+        interaction_id: payload.interaction_id,
+        interaction_protocol: payload.interaction_protocol,
+        state_status: payload.state_status,
+        ui: payload.ui,
+        target_id: payload.target_id,
+        normalized_x: payload.normalizedX,
+        normalized_y: payload.normalizedY,
+        direction: payload.direction,
+        duration_ms: payload.durationMs,
+        canonical_mirror: canonicalMirror || undefined,
+    };
+}

package/src/features/journey/uiState.ts

@@ -0,0 +1,89 @@
+/**
+ * UI STATE AT INTERACTION TIME — React Native.
+ *
+ * A screen is not just `Cart`. It is `Cart` with the filter sheet down, or up; with the address form
+ * expanded, or collapsed. Those are different interaction surfaces and a tap on one must never be
+ * counted on another — heat from the open sheet painted over the closed layout is a picture of
+ * something that never existed.
+ *
+ * HOW THIS DIFFERS FROM THE WEB, and the difference is not an omission:
+ *
+ *   The web SDK ALSO detects state automatically, by reading `aria-expanded` and open `<dialog>`
+ *   elements out of the live DOM. Those are platform-defined, so reading them is a measurement.
+ *
+ *   React Native has no equivalent. There is no queryable tree of accessibility state that says a
+ *   bottom sheet is up; a sheet is a component with a boolean in someone's store, and the only place
+ *   that boolean exists is the host's own code. Guessing at it — from a modal's presence in the tree, or
+ *   from a component name — would produce a state key that is right on some apps and silently wrong on
+ *   others, and a wrong state key partitions taps into buckets corresponding to nothing.
+ *
+ * So on RN, state is DECLARED and never inferred. `ScaleBun.setUiState('filter-sheet', 'open')` is the
+ * whole mechanism, and its absence means "not captured" rather than "nothing was open". That
+ * distinction is carried all the way to the dashboard: a tap with no declared state is NULL, not '',
+ * and cannot be selected as a state or counted as one. Reporting it as "nothing was open" would be
+ * asserting a measurement nobody took.
+ *
+ * PAIRED WITH: whatzbug-web-sdk/packages/web/src/features/journey/uiState.ts — same wire format
+ * (`name:value` pairs, sorted, `;`-joined, <= 96 chars), same separator stripping, same explicit-wins
+ * precedence, so one dashboard control queries both platforms.
+ */
+
+/** Host-declared state dimensions. The only source on this platform. */
+const declared = new Map<string, string>();
+
+/**
+ * `;` and `:` are the wire separators and cannot appear inside a name or value; the length is bounded.
+ *
+ * Names and values are IDENTIFIERS, not content. They become aggregation keys in the dashboard, so a
+ * value carrying a person's name or a cart total would put user data into a query key — and into every
+ * chart legend built from it.
+ */
+const clean = (s: string): string =>
+  typeof s === 'string' ? s.replace(/[;:|]/g, '').trim().slice(0, 32) : '';
+
+/**
+ * Declare the state of one UI dimension.
+ *
+ * Call it when the state CHANGES, not on every render: the value is read at interaction time, so it
+ * only has to be correct by the time the next tap lands.
+ */
+export function setUiState(name: string, value: string): void {
+  const n = clean(name);
+  const v = clean(value);
+  if (n && v) declared.set(n, v);
+}
+
+/**
+ * Stop reporting a dimension — or, with no name, all of them.
+ *
+ * Later taps carry no value for it, which is not the same as carrying a value. Clearing all is what a
+ * screen unmount wants: declarations from the previous screen would otherwise follow the user onto a
+ * surface where they mean nothing, and every tap there would be filed under a state that was not on
+ * screen.
+ */
+export function clearUiState(name?: string): void {
+  if (name === undefined) declared.clear();
+  else declared.delete(clean(name));
+}
+
+/**
+ * The signature for the interaction happening RIGHT NOW, or undefined when nothing is declared.
+ *
+ * undefined rather than '' deliberately — see the header. '' is the web's "we looked and nothing was
+ * open"; on RN there is nothing to look at, so the honest answer is silence.
+ */
+export function uiStateSignature(): string | undefined {
+  if (!declared.size) return undefined;
+  /* SORTED, or the same surface produces different signatures depending on the order the host happened
+     to declare things in, and every count fragments into several that mean nothing. */
+  const pairs = [...declared.keys()]
+    .sort()
+    .map((k) => `${k}:${declared.get(k)}`);
+  let signature = '';
+  for (const pair of pairs) {
+    const next = signature ? `${signature};${pair}` : pair;
+    if (next.length > 96) break;
+    signature = next;
+  }
+  return signature || undefined;
+}

package/src/features/ota/OtaTypes.ts

@@ -6,6 +6,50 @@
  * of truth; conformance tests in both repos assert against them to prevent drift.
  */
 
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * OTA-TELEMETRY-SPEC — remaining telemetry fixes (from the 2026-08 audit)
+ * ═══════════════════════════════════════════════════════════════════════════
+ * These close the SDK half of spec §84-86. All are ADDITIVE + backward-compatible
+ * (new optional fields, new enum members, new no-throw emit calls); old installed
+ * clients omit them and the backend ingests nullable/unknown fields. Each ALTERS
+ * DEVICE RUNTIME BEHAVIOR, so land them behind a real RN build + device/kill-test
+ * (Metro cannot exercise the boot-guard) — this file only carries the contract
+ * types + this spec, not the runtime wiring.
+ *
+ * 1. releaseId end-to-end  (CRITICAL — root of the dashboard funnel mismatch)
+ *    Backend already serves it: OtaBundlePayload.releaseId (done, this file +
+ *    ota-check.service.ts). SDK TODO:
+ *      - store payload.releaseId on the downloaded/installed bundle state, and
+ *      - set `releaseId: bundle.releaseId` in the delivery mapper
+ *        OtaOrchestrator.ts deliverOtaEvents (~:105) — currently only bundleId.
+ *      Then ota_events carry releaseId and the funnel keys by release.
+ *
+ * 2. Emit CHECK + OFFERED  (funnel top is currently unmeasurable)
+ *    - CHECK: emit at the start of checkForUpdate (OtaOrchestrator.ts ~:480),
+ *      before the fetch. ('CHECK' type already exists — no emit site today.)
+ *    - OFFERED: add 'OFFERED' to OtaEventType, emit when checkRes.action ===
+ *      'DOWNLOAD' (~:619) before download begins.
+ *
+ * 3. Emit BOOT_SUCCESS  (honest activation signal)
+ *    Add 'BOOT_SUCCESS' to OtaEventType and emit it from the boot-guard
+ *    markHealthy path (OtaOrchestrator.ts ~:863). INSTALLED (~:794) is emitted
+ *    optimistically BEFORE the bundle boots; keep it (it means "staged+swapped")
+ *    but let the dashboard measure real activation on BOOT_SUCCESS. Optionally
+ *    add 'VERIFIED' after signature check (~:635).
+ *
+ * 4. Stamp the running OTA bundle onto session/crash telemetry
+ *    SessionMetadata.bundleId is the NATIVE app package id, not the OTA bundle.
+ *    Add optional otaBundleId?/otaBundleVersion? (distinct fields — do NOT
+ *    overload bundleId) sourced from otaOrchestrator.getCurrentBundle() at
+ *    session start (SessionManager.ts ~:451), so crashes attribute to the
+ *    running bundle/version (release-health crash impact).
+ *
+ * Do NOT repurpose errorCode (it already collapses failure-error vs rollback-
+ * reason); add a new optional field if the two must be distinguished.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
 // ── SDK → backend (POST /sdk/ota/check) ──────────────────────────────────────
 export interface OtaCheckRequest {
   appVersion: string;
@@ -62,6 +106,13 @@ export interface OtaCheckResponse {
 export interface OtaBundlePayload {
   id: string;
   version: number;
+  /**
+   * The release this bundle is served AS (the backend now includes it — see
+   * ota.contracts.ts / ota-check.service.ts). Optional, for backward-compat with
+   * older backends. Carry it onto the emitted OtaEventItem.releaseId so telemetry
+   * is attributable by RELEASE, not just bundle. See OTA-TELEMETRY-SPEC below.
+   */
+  releaseId?: string;
   url: string;         // presigned GET — short-TTL
   size: number;
   sha256: string;