@scalebun/react-native 1.10.5 → 1.10.7

package/lib/typescript/features/ota/crypto/loadSha512.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Isolated lazy loader for the OPTIONAL `@noble/hashes` SHA-512.
+ *
+ * Separate file from `loadEd25519` because Metro miscounts a module holding two
+ * different-string inline `require()` calls — see the comment there.
+ *
+ * ed25519 is defined in terms of SHA-512, and React Native has no native
+ * SHA-512, so @noble/ed25519 cannot verify anything until a hash provider is
+ * wired into it. Which property it expects differs by major version, so the
+ * wiring lives in `builtinVerifier`, not here; this module only obtains the
+ * function.
+ */
+export type Sha512Fn = (msg: Uint8Array) => Uint8Array;
+export declare function loadSha512(): Sha512Fn | null;
+//# sourceMappingURL=loadSha512.d.ts.map

package/lib/typescript/features/ota/crypto/nativeVerifier.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Native ed25519 verifier — platform crypto wrapped as a SignatureVerifier.
+ *
+ * WHY IT EXISTS. The built-in @noble verifier runs in JS, inside the very
+ * bundle it protects: an attacker who lands one malicious bundle can neuter a
+ * JS check for every update after it. Platform crypto (CryptoKit on iOS,
+ * Android's conscrypt on API 33+) sits outside the bundle's reach — and using
+ * it also drops the runtime dependency on the optional @noble peers wherever
+ * the OS provides ed25519.
+ *
+ * WHAT IT DOES NOT FIX, stated plainly: the ORCHESTRATION still lives in JS.
+ * A hostile bundle can skip calling any verifier and drive the native staging
+ * methods directly. Moving the crypto native shrinks the attack surface (no
+ * more tampering with a bundled crypto lib to flip a verdict) but the full
+ * close needs native-ENFORCED staging with a natively-pinned key — an
+ * architectural change tracked separately, not smuggled into this one.
+ *
+ * VERDICT CONTRACT (mirrors the spec): the native side resolves
+ * 'valid' | 'invalid' | 'unavailable'. 'invalid' is a definitive NO.
+ * 'unavailable' (Android < 33, malformed input, machinery failure) means this
+ * source cannot answer — the composed verifier below then delegates to the
+ * @noble builtin, and when that is absent too it THROWS, which the policy
+ * layer converts to a rejection. Every path that cannot verify refuses.
+ */
+import type { SignatureVerifier } from '../signature';
+/**
+ * The native-first verifier, or null when the native module (or its
+ * verifyEd25519 method — an app running new JS against an old binary) is
+ * absent. Cached like the builtin: module availability does not change at
+ * runtime, and this is consulted on every update check.
+ */
+export declare function getNativeVerifier(): SignatureVerifier | null;
+/** Test seam — clears the cached resolution. */
+export declare function _resetNativeVerifier(): void;
+//# sourceMappingURL=nativeVerifier.d.ts.map

package/lib/typescript/features/ota/signature.d.ts

@@ -11,10 +11,17 @@
  * download and nothing else. On a platform whose entire purpose is remote code
  * delivery, that is the control that matters most.
  *
- * WHY IT IS SHAPED LIKE THIS. The SDK ships zero third-party runtime
- * dependencies, and React Native has no built-in ed25519. So verification is
- * delegated to a host-provided verifier when one is installed, and the SDK's job
- * is to decide — unambiguously — what happens when there is not one.
+ * WHY IT IS SHAPED LIKE THIS. React Native has no built-in ed25519, so the
+ * verification primitive has to come from somewhere. It is resolved in order:
+ * a host-supplied verifier, else the built-in one assembled from the OPTIONAL
+ * `@noble/ed25519` + `@noble/hashes` peers, else nothing — and the SDK's job is
+ * to decide, unambiguously, what happens in that last case.
+ *
+ * The built-in path exists because requiring every adopter to hand-write a
+ * verifier put the most security-critical operation in the product in code the
+ * SDK could neither test nor audit, and made a routine dependency bump able to
+ * silently stop all updates. See `crypto/builtinVerifier.ts`. Signing stays
+ * opt-in, and apps that never adopt it carry no curve arithmetic.
  *
  * THE POLICY, which is the important part:
  *
@@ -40,8 +47,16 @@ export type SignatureVerifier = (input: {
     publicKey: string;
 }) => boolean | Promise<boolean>;
 export interface SignatureConfig {
-    /** ed25519 public key shipped in the app binary. Absent = signing not adopted. */
-    publicKey?: string;
+    /**
+     * ed25519 public key(s) shipped in the app binary. Absent = signing not
+     * adopted. An ARRAY pins several keys at once and a bundle is accepted when
+     * ANY of them verifies — this is what makes key rotation possible without an
+     * app-store release: ship a build pinning [old, new], start signing with new,
+     * drop old from the next build. With a single pinnable key, losing the
+     * private key meant no OTA capability until a new binary cleared review —
+     * the exact emergency OTA exists to solve.
+     */
+    publicKey?: string | string[];
     /** Host-provided ed25519 verification function. */
     verifier?: SignatureVerifier;
 }
@@ -50,7 +65,7 @@ export type SignatureOutcome = {
     reason: 'verified' | 'not_configured';
 } | {
     ok: false;
-    reason: 'no_verifier' | 'invalid_signature' | 'missing_signature' | 'verifier_threw';
+    reason: 'no_verifier' | 'invalid_signature' | 'missing_signature' | 'verifier_threw' | 'no_keys';
 };
 /**
  * Decide whether a bundle may be staged.

package/lib/typescript/public/ScaleBunFacade.d.ts

@@ -69,17 +69,30 @@ declare class ScaleBunFacade {
     /**
      * Boot the OTA orchestrator when the init config asks for it.
      *
-     * `publicSigningKey` is honoured here so signature enforcement is reachable
-     * from configuration alone. The SDK ships no ed25519 implementation, so a
-     * host that pins a key must also supply `ota.verifySignature`; pinning a key
-     * without a verifier is fail-CLOSED by design (signature.ts) — an update
-     * that cannot be verified is not installed. We say that out loud rather than
-     * letting the app discover it as a silent no-update condition.
+     * `publicSigningKey` / `publicSigningKeys` are honoured here so signature
+     * enforcement is reachable from configuration alone. The list form exists
+     * for key ROTATION: a build pinning [old, new] keeps verifying while the
+     * server moves to the new key, so replacing a key never needs an emergency
+     * store release. Both fields merge (deduplicated) into one pinned set.
+     *
+     * Verification comes from `ota.verifySignature` when supplied, else the
+     * built-in @noble-based verifier (optional peers). Pinning keys with
+     * NEITHER available is fail-CLOSED by design (signature.ts) — an update
+     * that cannot be verified is not installed. We say that out loud rather
+     * than letting the app discover it as a silent no-update condition.
      */
     private _maybeStartOta;
     private _autoEnableDebug;
     /** Boot the Phase 1 envelope tracking lane if an appId is configured. */
     private _maybeStartEventTracker;
+    /**
+     * Fold the native bridge's device facts into the analytics context once it answers.
+     *
+     * Detected values never overwrite a populated one with an empty one — `nativeDeviceContext`
+     * drops absent keys and `applyDetectedContext` ignores an empty patch — so a bridge that
+     * cannot answer leaves whatever `Platform.constants` already found.
+     */
+    private _applyNativeDeviceContext;
     /**
      * Android-only: read the Play Install Referrer once per install and route it into
      * attribution. `scalebun_click_id` → the deterministic click path; the full
@@ -140,6 +153,30 @@ declare class ScaleBunFacade {
         variant: (key: string) => string | null;
     };
     /** Convenience: emit a Phase 1 purchase event (revenue + currency + transaction_id). */
+    /**
+     * Declare which UI state the user is looking at, so taps are attributed to the surface they
+     * happened on rather than averaged across every variant of the screen.
+     *
+     *     ScaleBun.setUiState('filter-sheet', 'open');
+     *     ScaleBun.setUiState('checkout-step', 'payment');
+     *
+     * Call it when the state CHANGES — the value is read at tap time, so it only has to be right by
+     * the time the next tap lands. On React Native this is the ONLY source of UI state: unlike the web,
+     * there is no queryable accessibility tree that says a sheet is up, and guessing would produce a
+     * state key that is right on some apps and silently wrong on others.
+     *
+     * Names and values are identifiers, not content: they become query keys in the dashboard, so a
+     * person's name or a cart total does not belong in one. `;`, `:` and `|` are stripped and both
+     * halves are capped at 32 characters.
+     */
+    setUiState(name: string, value: string): void;
+    /**
+     * Stop reporting a UI state dimension — or, with no argument, all of them.
+     *
+     * Clear on screen unmount. A declaration left behind follows the user onto a surface where it means
+     * nothing, and every tap there is filed under a state that was not on screen.
+     */
+    clearUiState(name?: string): void;
     trackPurchase(input: {
         revenue: number;
         currency: string;

package/lib/typescript/specs/NativeScaleBunOta.d.ts

@@ -76,6 +76,29 @@ export interface Spec extends TurboModule {
      * `recreateReactContextInBackground()` (bridge). iOS: RCTReloadCommand.
      */
     restartApp(): void;
+    /**
+     * Verify a detached ed25519 signature in NATIVE code.
+     *
+     * Exists because the JS verifier runs inside the very bundle it protects —
+     * an attacker who lands one malicious bundle can neuter a JS check for every
+     * update after it. Platform crypto is outside the bundle's reach, and it also
+     * removes the runtime dependency on the optional @noble peers wherever the OS
+     * provides ed25519 (iOS 13+ CryptoKit everywhere; Android API 33+).
+     *
+     * All three arguments are lowercase hex, pre-validated by the JS caller:
+     * the 32-byte bundle SHA-256 (the signature is over its RAW BYTES, matching
+     * the CLI's signing contract), the 64-byte signature, the 32-byte public key.
+     *
+     * Resolves a verdict STRING, not a boolean, because "the signature is wrong"
+     * and "this OS cannot check" must never collapse into one value:
+     *   'valid'       — signature verifies under the key
+     *   'invalid'     — it does not; the caller must refuse the bundle
+     *   'unavailable' — this OS level has no ed25519 (Android < 33); the caller
+     *                   falls back to the JS verifier
+     * A rejected promise is machinery failure and the caller treats it as
+     * 'unavailable' — never as 'valid'.
+     */
+    verifyEd25519(messageHex: string, signatureHex: string, publicKeyHex: string): Promise<string>;
 }
 /**
  * Resolved via `get` (not `getEnforcing`) so the SDK degrades gracefully when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalebun/react-native",
-  "version": "1.10.5",
+  "version": "1.10.7",
   "description": "React Native SDK for ScaleBun",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -69,11 +69,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
+    "@babel/preset-env": "^8.0.2",
+    "@noble/ed25519": "^3.1.0",
+    "@noble/hashes": "^2.3.0",
     "@react-native-community/eslint-config": "^3.2.0",
     "@types/jest": "^29.5.12",
     "@types/node": "^25.3.3",
     "@types/react": "^18.2.0",
     "@types/react-native": "^0.73.0",
+    "babel-jest": "^30.4.1",
     "del-cli": "^5.1.0",
     "esbuild": "0.25.0",
     "eslint": "^8.57.0",
@@ -92,7 +96,9 @@
     "expo-router": ">=1.0.0",
     "react": ">=18.0.0",
     "react-native": ">=0.74.0",
-    "react-native-view-shot": ">=3.0.0"
+    "react-native-view-shot": ">=3.0.0",
+    "@noble/ed25519": ">=2.0.0",
+    "@noble/hashes": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "react-native-view-shot": {
@@ -103,6 +109,12 @@
     },
     "expo-router": {
       "optional": true
+    },
+    "@noble/ed25519": {
+      "optional": true
+    },
+    "@noble/hashes": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -139,6 +151,9 @@
     "lint": "eslint \"**/*.{js,ts,tsx}\"",
     "clean": "del-cli lib dist",
     "build": "bob build && node scripts/build-dist.mjs",
-    "watch": "bob build --watch"
+    "watch": "bob build --watch",
+    "test:screens": "node --experimental-transform-types --import ./scripts/rn-globals.mjs --import ./scripts/register-ts-ext.mjs --test scripts/screen-detection.test.ts",
+    "test:uistate": "node --experimental-transform-types --import ./scripts/rn-globals.mjs --import ./scripts/register-ts-ext.mjs --test scripts/ui-state.test.ts",
+    "typecheck:scripts": "tsc --noEmit -p tsconfig.scripts.json"
   }
 }

package/src/analytics/EventTracker.ts

@@ -387,6 +387,25 @@ export class EventTracker {
         this.persistQueue();
     }
 
+    /**
+     * Fold in device facts that were not knowable at init.
+     *
+     * `Platform.constants` answers Android synchronously, so its model and manufacturer ride the
+     * very first event. iOS exposes neither there — only the native bridge knows, and the bridge is
+     * async and may not be installed at all. Without this the iOS half of every install reported no
+     * model whatsoever.
+     *
+     * `buildEnvelope` reads `cfg.context` per event, so applying it here reaches every event from
+     * the next one onward. Detected keys WIN over whatever the integrator configured, for the same
+     * reason `mergeDeviceContext` inverts the usual precedence: a measurement must not be
+     * overridable by a guess. Empty patches are ignored so a bridge that answered with nothing
+     * cannot blank a value the static path already found.
+     */
+    applyDetectedContext(patch: Record<string, string>): void {
+        if (!patch || Object.keys(patch).length === 0) return;
+        this.cfg.context = { ...(this.cfg.context ?? {}), ...patch };
+    }
+
     // ─── internals ─────────────────────────────────────────────────────────────
 
     private buildEnvelope(eventName: string, properties?: Record<string, any>): Envelope {

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

@@ -3,4 +3,4 @@
  * can attribute telemetry to the SDK build that produced it.
  * Keep in sync with package.json "version".
  */
-export const SDK_VERSION = '1.10.5';
+export const SDK_VERSION = '1.10.7';

package/src/core/context/device.ts

@@ -114,6 +114,10 @@ export function staticDeviceContext(): Record<string, string> {
     if (c.Model) out.device_model = String(c.Model);
     if (c.Manufacturer) out.manufacturer = String(c.Manufacturer);
     else if (c.Brand) out.manufacturer = String(c.Brand);
+    // iOS exposes no manufacturer because it does not need to: every device running iOS is Apple's.
+    // A tautology, not a guess — and it means the field is populated on event #1 rather than waiting
+    // for a bridge that may never answer.
+    else if (out.platform_os === 'ios') out.manufacturer = 'Apple';
     return out;
 }
 
@@ -122,11 +126,13 @@ export function nativeDeviceContext(info: {
     platform?: string;
     osVersion?: string;
     deviceModel?: string;
+    manufacturer?: string;
 } | null): Record<string, string> {
     const out: Record<string, string> = {};
     if (!info) return out;
     if (info.osVersion) out.os_version = info.osVersion;
     if (info.deviceModel) out.device_model = info.deviceModel;
+    if (info.manufacturer) out.manufacturer = info.manufacturer;
     return out;
 }
 

package/src/features/journey/ScaleBunDebugRoot.tsx

@@ -503,9 +503,31 @@ export function ScaleBunDebugRoot({
                     const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
                     screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
                 } catch { /* no-throw */ }
+                /**
+                 * UI STATE, read HERE and not later.
+                 *
+                 * A tap belongs to the surface that was on screen when the finger landed: tapping the
+                 * filter button while the sheet is DOWN belongs to `closed`, because that is what the
+                 * user was looking at when they reached for it. Reading it after the handler has run
+                 * moves every "open the thing" tap into the state it created — the one state it
+                 * certainly does not belong to.
+                 *
+                 * Declared-only on this platform (see uiState.ts): absent means not captured, which
+                 * the dashboard keeps distinct from "nothing was open".
+                 */
+                let ui: string | undefined;
+                try {
+                    const { uiStateSignature } = require('./uiState');
+                    ui = uiStateSignature();
+                } catch { /* no-throw: a tap must never be lost to state capture */ }
                 emitAutomaticEvent('element_interacted', {
                     gesture_type: gestureType,
                     screen_name: screen,
+                    /* THIS MAP ENUMERATES. A field added to the payload and forgotten here reaches the
+                       backend as undefined with no error anywhere — the recurring defect class in this
+                       codebase. `ui` is the key the grid aggregate reads for state, byte-identical to
+                       the web SDK's, so one dashboard control queries both platforms. */
+                    ui,
                     // testID/nativeID is an author-controlled stable identifier.
                     // Accessibility labels and rendered text are deliberately omitted.
                     target_id: targetInfo?.testId,

package/src/features/journey/uiState.ts

@@ -0,0 +1,84 @@
+/**
+ * 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. */
+  return [...declared.keys()]
+    .sort()
+    .map((k) => `${k}:${declared.get(k)}`)
+    .join(';')
+    .slice(0, 96);
+}

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;