@scalebun/react-native 1.10.7 → 1.11.1

package/src/features/ota/OtaOrchestrator.ts

@@ -106,6 +106,11 @@ async function deliverOtaEvents(params: {
     kind: 'ota_event' as const,
     type: e.type,
     bundleId: e.bundleId,
+    // Without this the backend stored a null releaseId on every row it ingested,
+    // while serving the release id on every check — so the delivery funnel could
+    // only ever be grouped by bundle, and a bundle re-promoted under a second
+    // release merged the two into one indistinguishable series.
+    releaseId: e.releaseId,
     installationId: params.installationId,
     // OTA bundles are compiled per platform, so this genuinely is ios|android. Narrowed via
     // resolveMobileOS so a non-mobile RN target is skipped rather than served an Android bundle.
@@ -158,14 +163,18 @@ export interface BootGuardConfig {
    */
   healthyAfterMs?: number;
   /**
-   * Maximum consecutive boot-guard reverts before the SDK stops trying
-   * OTA bundles and pins to the factory bundle. Default: 2.
+   * @deprecated Not honoured, and never was — nothing in JS reads this field.
+   *
+   * The boot-attempt limit lives in native code, where the counter it bounds is
+   * incremented (`MAX_BOOT_ATTEMPTS` in `SlotManager.kt` / `OtaSlotManager.swift`,
+   * both 2). Setting it here has no effect; the field is kept only so existing
+   * call sites keep compiling. Change the limit natively, or file a request for
+   * it to be plumbed through `initOutbox`-style native config.
    */
   maxRevertAttempts?: number;
 }
 
 const DEFAULT_HEALTHY_AFTER_MS = 10_000;
-const DEFAULT_MAX_REVERT_ATTEMPTS = 2;
 
 export class OtaOrchestrator {
   private enabled = false;
@@ -257,22 +266,35 @@ export class OtaOrchestrator {
           `${this.environment.hermes ? `, Hermes HBC v${this.environment.hermesBytecodeVersion ?? '?'}` : ''})`,
       );
 
+      // ONE read of the slot state, shared by both boot-time consumers.
+      //
+      // `getSlotState()` is CONSUME-ON-READ for the revert record: both native
+      // implementations delete it as they serialise, so that a rollback is
+      // reported exactly once instead of on every launch forever. Calling it
+      // twice therefore means the second caller never sees the revert — which is
+      // precisely what happened, since hydration ran first and swallowed it. It
+      // is also a blocking synchronous bridge call, so one read is cheaper.
+      const slotState = this.readSlotState();
+
       // Rehydrate which bundle we are running from the native slot state.
       // Without this `currentBundle` stays null for the whole process after a
       // restart, so every check reported no current bundle and the backend had
       // no way to know what the device was actually on.
-      this.hydrateCurrentBundleFromSlots();
+      this.hydrateCurrentBundleFromSlots(slotState);
 
       // Warm the device-country cache (edge Worker lookup) so checks can carry
       // a country when the API itself sits behind no geo-stamping CDN.
       // Fire-and-forget and failure-soft — a check without a country is valid.
       void prefetchDeviceCountry();
 
+      // Check if the boot guard fired on this launch (native reverted before JS
+      // loaded). BEFORE the identity check, because both read the install record
+      // and the identity check retires it — a revert must get its chance to name
+      // the bundle that failed while the record still describes it.
+      this.checkBootGuardRecovery(slotState);
+
       // Prove the bundle we installed is the bundle that loaded.
       this.verifyRunningBundleIdentity();
-
-      // Check if the boot guard fired on this launch (native reverted before JS loaded)
-      this.checkBootGuardRecovery();
     });
   }
 
@@ -280,10 +302,21 @@ export class OtaOrchestrator {
    * Read the active slot back into `currentBundle` so the next check reports
    * what this device is genuinely running.
    */
-  private hydrateCurrentBundleFromSlots(): void {
-    if (!NativeScaleBunOta) return;
+  /**
+   * Parse the native slot state once. Returns null when the module is absent or
+   * the payload is unreadable — every caller treats that as "factory bundle".
+   */
+  private readSlotState(): Record<string, any> | null {
+    if (!NativeScaleBunOta) return null;
+    try {
+      return JSON.parse(NativeScaleBunOta.getSlotState());
+    } catch {
+      return null;
+    }
+  }
+
+  private hydrateCurrentBundleFromSlots(state: Record<string, any> | null): void {
     try {
-      const state = JSON.parse(NativeScaleBunOta.getSlotState());
       const current = state?.current;
       if (!current?.sha256) return;
 
@@ -298,6 +331,7 @@ export class OtaOrchestrator {
         this.currentBundle = {
           id: record.bundleId,
           version: record.version,
+          releaseId: record.releaseId ?? undefined,
           sha256: record.sha256,
         } as OtaBundlePayload;
         __DEV__ && logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
@@ -335,49 +369,50 @@ export class OtaOrchestrator {
     if (!this.currentBundle) return;
 
     const running = readRunningBundleMarker();
-    const expected = this.readInstallExpectation();
+    const record = this.readInstallRecord();
 
-    // Stale record from an earlier install — the slot has moved on since.
-    if (expected && expected.bundleId !== this.currentBundle.id) {
+    // No record at all — installed by an SDK that predates install records, or
+    // local storage was cleared. NOTHING can be concluded here and nothing is
+    // reported: the marker is a random per-publish token, never the bundle id,
+    // so comparing the two would flag a false mismatch on every healthy launch.
+    if (!record) return;
+
+    // The record describes a bundle that is no longer the active one (a revert,
+    // or a bundle staged by another path). It cannot verify this launch, and
+    // keeping it would make the next launch mis-report what is running.
+    if (record.sha256 !== this.currentBundle.sha256) {
       this.clearInstallExpectation();
       return;
     }
 
-    if (expected) {
-      if (running === expected.identityToken) {
-        // Proven: the bundle we installed is the bundle executing.
-        __DEV__ && logger.debug('[OTA] Install verified — running bundle matches what was installed.');
-        this.clearInstallExpectation();
-        return;
-      }
-
-      logger.error(
-        `[OTA] INSTALL DID NOT TAKE EFFECT — bundle ${this.currentBundle.id} was installed and ` +
-          `carries a known identity marker, but the running bundle reports ` +
-          `${running ?? 'no marker at all'}. The app is executing different code than the slot ` +
-          'manager believes. Check that the host app resolves the OTA bundle path at launch ' +
-          '(see the ScaleBunOta integration for your React Native version).',
-      );
-      otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `install_not_effective — expected ${expected.identityToken}, running ${running ?? 'none'}`,
-      });
-      // Deliberately NOT cleared: the condition is still true on the next boot
-      // and should keep reporting until the integration is fixed. Clearing here
-      // would make a permanently broken install look like a one-off.
+    // Already proven on an earlier launch. The token is retired once verified
+    // while the REST of the record stays — it is also the sha256 -> bundleId map
+    // that `hydrateCurrentBundleFromSlots` reads to report what this device is
+    // running. Wiping the whole record here is what made every launch after the
+    // first send `currentBundleId: undefined`, which the server reads as "not on
+    // this bundle" and answers by serving the same bundle again, forever.
+    if (!record.identityToken) return;
+
+    if (running === record.identityToken) {
+      __DEV__ && logger.debug('[OTA] Install verified — running bundle matches what was installed.');
+      this.retireIdentityToken(record);
       return;
     }
 
-    if (running && running !== this.currentBundle.id) {
-      // No recorded expectation (installed by an older SDK), but the running
-      // marker disagrees with the active slot outright. Still conclusive.
-      logger.error(
-        `[OTA] BUNDLE MISMATCH — slot says ${this.currentBundle.id} is active but the ` +
-          `running bundle identifies as ${running}.`,
-      );
-      otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `bundle_identity_mismatch — running ${running}`,
-      });
-    }
+    logger.error(
+      `[OTA] INSTALL DID NOT TAKE EFFECT — bundle ${this.currentBundle.id} was installed and ` +
+        `carries a known identity marker, but the running bundle reports ` +
+        `${running ?? 'no marker at all'}. The app is executing different code than the slot ` +
+        'manager believes. Check that the host app resolves the OTA bundle path at launch ' +
+        '(see the ScaleBunOta integration for your React Native version).',
+    );
+    otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
+      releaseId: this.currentBundle.releaseId,
+      error: `install_not_effective — expected ${record.identityToken}, running ${running ?? 'none'}`,
+    });
+    // Deliberately NOT retired: the condition is still true on the next boot and
+    // should keep reporting until the integration is fixed. Retiring the token
+    // here would make a permanently broken install look like a one-off.
   }
 
   // ── Install expectation ────────────────────────────────────────────────────
@@ -394,6 +429,11 @@ export class OtaOrchestrator {
         JSON.stringify({
           bundleId: bundle.id,
           version: bundle.version,
+          // Carried so telemetry emitted on a LATER launch (a boot-guard
+          // rollback, an ineffective install) can still be attributed to the
+          // release, not merely the bundle. The check response is long gone by
+          // then; this record is the only thing that remembers.
+          releaseId: bundle.releaseId ?? null,
           // The join key back to the native slot, which records sha256 and
           // nothing else identifying.
           sha256: bundle.sha256,
@@ -408,6 +448,7 @@ export class OtaOrchestrator {
   private readInstallRecord(): {
     bundleId: string;
     version: number;
+    releaseId?: string | null;
     sha256: string;
     identityToken: string | null;
   } | null {
@@ -423,11 +464,35 @@ export class OtaOrchestrator {
     }
   }
 
-  private readInstallExpectation(): { bundleId: string; identityToken: string } | null {
-    const record = this.readInstallRecord();
-    return record && record.identityToken
-      ? { bundleId: record.bundleId, identityToken: record.identityToken }
-      : null;
+  /**
+   * Drop the identity token once the install has been proven, keeping the rest
+   * of the record.
+   *
+   * The record does two jobs: it proves an install took effect (once), and it
+   * maps the native slot's sha256 back to a bundle id (for the life of that
+   * bundle). Only the first job is finished after a successful verification, so
+   * only the token is retired.
+   */
+  private retireIdentityToken(record: {
+    bundleId: string;
+    version: number;
+    releaseId?: string | null;
+    sha256: string;
+  }): void {
+    try {
+      this.storage().set(
+        OtaOrchestrator.INSTALL_EXPECTATION_KEY,
+        JSON.stringify({
+          bundleId: record.bundleId,
+          version: record.version,
+          releaseId: record.releaseId ?? null,
+          sha256: record.sha256,
+          identityToken: null,
+        }),
+      );
+    } catch {
+      /* non-fatal */
+    }
   }
 
   private clearInstallExpectation(): void {
@@ -448,19 +513,50 @@ export class OtaOrchestrator {
    * If getSlotState() shows bootMarkerPresent=false but we have a 'previous' slot
    * and no 'current' OTA bundle, the native layer already reverted.
    */
-  private checkBootGuardRecovery(): void {
-    if (!NativeScaleBunOta) return;
-
+  private checkBootGuardRecovery(state: Record<string, any> | null): void {
     try {
-      const stateJson = NativeScaleBunOta.getSlotState();
-      const state = JSON.parse(stateJson);
+      if (!state?.bootGuardReverted) return;
+
+      // WHICH bundle was rolled back, and it has to come from the install
+      // record. The obvious source — `state.previous` — is wrong twice over:
+      // slot meta.json carries only `{sha256, installedAt}` so it has no bundle
+      // id to read, and `revert()` deletes the previous slot as its last step,
+      // so by the time this runs there is no previous meta at all. The event
+      // therefore reported `bundleId: 'unknown'` on every rollback, and the
+      // backend drops any ota_event whose bundleId does not resolve to a bundle
+      // the app owns — so the crash-guard's own rollback signal never arrived.
+      //
+      // Native now stamps the sha256 of the bundle it reverted AWAY FROM into
+      // the revert record; the install record maps that back to a bundle id.
+      const record = this.readInstallRecord();
+      const revertedSha: string | undefined = state.bootGuardRevertedSha256;
+      const matchesRecord = !!record && (!revertedSha || record.sha256 === revertedSha);
+
+      // Report the reason native actually determined — a hash mismatch and a
+      // crash loop are different incidents and were being collapsed into one.
+      const reason: string = state.bootGuardRevertReason || 'boot_crash_guard';
 
-      if (state.bootGuardReverted) {
-        logger.warn('[OTA] Boot guard fired — app was reverted to previous bundle');
-        otaEventEmitter.emitSimple('AUTO_ROLLBACK', state.previous?.bundleId ?? 'unknown', {
-          reason: 'boot_guard_crash_loop_detected',
+      if (matchesRecord && record) {
+        logger.warn(
+          `[OTA] Boot guard fired — reverted away from bundle ${record.bundleId} ` +
+            `(v${record.version}); reason: ${reason}`,
+        );
+        otaEventEmitter.emitSimple('AUTO_ROLLBACK', record.bundleId, {
+          releaseId: record.releaseId ?? undefined,
+          version: record.version,
+          reason,
         });
+        // The record describes a bundle this device is no longer running.
+        this.clearInstallExpectation();
+        return;
       }
+
+      // No usable record (older SDK, cleared storage). Say so rather than
+      // emitting an event the server is obliged to discard.
+      logger.warn(
+        `[OTA] Boot guard fired (reason: ${reason}) but the rolled-back bundle could not be ` +
+          'identified locally — no install record. The rollback is not reported to the server.',
+      );
     } catch {
       // Slot state parsing failed — non-fatal
     }
@@ -591,6 +687,23 @@ export class OtaOrchestrator {
       }
 
       __DEV__ && logger.debug('[OTA] Sync started…');
+
+      // The funnel's denominator, for devices already on an OTA bundle. Emitted
+      // before the request, so a check that fails outright still counts as a
+      // check — the only CHECK rows before this came from a server-side geo
+      // side-effect that is skipped whenever the request carries no country.
+      //
+      // Only when a current bundle is known: every ota_event must name a bundle
+      // the app owns or the server drops it, and a device still on the binary's
+      // factory bundle has no such id to give. Those devices are counted
+      // server-side when they are offered something.
+      if (this.currentBundle?.id) {
+        otaEventEmitter.emitSimple('CHECK', this.currentBundle.id, {
+          releaseId: this.currentBundle.releaseId,
+          version: this.currentBundle.version,
+        });
+      }
+
       const checkRes = await this.checkForUpdate(params);
 
       if (checkRes.action === 'NONE') {
@@ -603,7 +716,9 @@ export class OtaOrchestrator {
       // Handle server-initiated rollback (Sprint 4)
       if (checkRes.action === 'ROLLBACK') {
         logger.warn('[OTA] Server requested ROLLBACK — reverting to previous bundle');
-        otaEventEmitter.emitSimple('MANUAL_ROLLBACK', this.currentBundle?.id ?? 'unknown');
+        otaEventEmitter.emitSimple('MANUAL_ROLLBACK', this.currentBundle?.id ?? 'unknown', {
+          releaseId: this.currentBundle?.releaseId,
+        });
         const reverted = await NativeScaleBunOta.revertToPrevious();
         if (reverted) {
           this.currentBundle = null;
@@ -623,6 +738,15 @@ export class OtaOrchestrator {
       const bundle = checkRes.bundle;
       let patchUsed = false;
 
+      // The offer itself. Everything downstream (download, install, activation)
+      // is a conversion against this, so without it the top of the funnel was
+      // unmeasurable and a rollout that never reached devices looked identical
+      // to one whose devices all declined to download.
+      otaEventEmitter.emitSimple('OFFERED', bundle.id, {
+        releaseId: bundle.releaseId,
+        version: bundle.version,
+      });
+
       // ── VERIFY AUTHENTICITY (OTA-03) ─────────────────────────────────────
       // Before anything touches the disk. SHA-256 proves the bytes arrived
       // intact; only the signature proves they came from you. Checking after
@@ -634,6 +758,7 @@ export class OtaOrchestrator {
       );
       if (!signatureOutcome.ok) {
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: `Signature check failed: ${signatureOutcome.reason}`,
           version: bundle.version,
         });
@@ -645,7 +770,10 @@ export class OtaOrchestrator {
       }
 
       // ── DOWNLOAD ─────────────────────────────────────────────────────────
-      otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, { version: bundle.version });
+      otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, {
+        releaseId: bundle.releaseId,
+        version: bundle.version,
+      });
       const downloadStart = Date.now();
       __DEV__ && logger.debug(`[OTA] Downloading update v${bundle.version}…`);
 
@@ -750,6 +878,7 @@ export class OtaOrchestrator {
         postProgress(0, 'FAILED');
         logger.error('[OTA] Staging bundle failed after retries');
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: 'Staging failed — SHA-256 mismatch or download error',
           version: bundle.version,
         });
@@ -760,6 +889,7 @@ export class OtaOrchestrator {
 
       const downloadDuration = Date.now() - downloadStart;
       otaEventEmitter.emitSimple('DOWNLOAD_COMPLETE', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version,
         durationMs: downloadDuration,
         patchUsed,
@@ -771,6 +901,7 @@ export class OtaOrchestrator {
       if (!applied) {
         logger.error('[OTA] Applying update failed');
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: 'Atomic slot swap failed',
           version: bundle.version,
         });
@@ -791,7 +922,10 @@ export class OtaOrchestrator {
       // it is skipped when there is no marker to compare.
       this.recordInstallExpectation(bundle);
 
-      otaEventEmitter.emitSimple('INSTALLED', bundle.id, { version: bundle.version });
+      otaEventEmitter.emitSimple('INSTALLED', bundle.id, {
+        releaseId: bundle.releaseId,
+        version: bundle.version,
+      });
       __DEV__ && logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
 
       // Deliver telemetry BEFORE a restart tears the JS runtime down —
@@ -863,6 +997,19 @@ export class OtaOrchestrator {
           NativeScaleBunOta?.markHealthy();
           __DEV__ && logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
           this.healthyTimer = null;
+
+          // The honest activation signal. INSTALLED is emitted optimistically,
+          // BEFORE the bundle has ever executed, so counting it as adoption
+          // credits bundles that were installed and then crash-reverted. This
+          // fires only once the bundle has actually booted and survived.
+          const running = this.currentBundle;
+          if (running?.id) {
+            otaEventEmitter.emitSimple('BOOT_SUCCESS', running.id, {
+              releaseId: running.releaseId,
+              version: running.version,
+              durationMs: healthyMs,
+            });
+          }
         });
       }, healthyMs);
     } catch {

package/src/features/ota/OtaTypes.ts

@@ -8,42 +8,38 @@
 
 /**
  * ═══════════════════════════════════════════════════════════════════════════
- * OTA-TELEMETRY-SPEC — remaining telemetry fixes (from the 2026-08 audit)
+ * OTA-TELEMETRY-SPEC — status (spec §84-86)
  * ═══════════════════════════════════════════════════════════════════════════
- * 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.
+ * Items 1-3 are DONE. All were additive and backward-compatible: old installed
+ * clients simply omit the new fields and never emit the new types, and the
+ * backend ingests nullable columns. Because they alter device runtime behaviour,
+ * verify against a real RN build + device kill-test before release — Metro
+ * cannot exercise the boot guard.
  *
- * 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.
+ * 1. releaseId end-to-end — DONE. `recordInstallExpectation` persists the
+ *    release id (so a rollback reported launches later can still name it),
+ *    `hydrateCurrentBundleFromSlots` restores it, every emit site passes it, and
+ *    `deliverOtaEvents` maps it onto the wire item.
  *
- * 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.
+ * 2. CHECK + OFFERED — DONE. CHECK is emitted at the top of `sync()` for devices
+ *    already on an OTA bundle (a device on the factory bundle has no owned
+ *    bundle id to name, and the server drops rows it cannot resolve — those are
+ *    counted server-side instead). OFFERED is emitted on `action === 'DOWNLOAD'`
+ *    before any bytes move.
  *
- * 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).
+ * 3. BOOT_SUCCESS — DONE. Emitted from the boot-guard heartbeat once the bundle
+ *    has actually booted and survived to `healthyAfterMs`. INSTALLED is kept and
+ *    still means "staged + swapped", but activation should be measured on
+ *    BOOT_SUCCESS: INSTALLED fires before the bundle has run, so it credits
+ *    bundles that installed and then crash-reverted.
  *
- * 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).
+ * 4. Stamp the running OTA bundle onto session/crash telemetry — NOT DONE.
+ *    `SessionMetadata.bundleId` is the NATIVE app package id, not the OTA bundle,
+ *    so crashes cannot currently be attributed to the bundle that produced them
+ *    (release-health crash impact). Needs optional otaBundleId?/otaBundleVersion?
+ *    (distinct fields — do NOT overload bundleId) sourced from
+ *    `otaOrchestrator.getCurrentBundle()` at session start, plus the matching
+ *    backend columns and a Prisma migration.
  *
  * Do NOT repurpose errorCode (it already collapses failure-error vs rollback-
  * reason); add a new optional field if the two must be distinguished.
@@ -149,14 +145,16 @@ export interface OtaPatchPayload {
 }
 
 // ── Adoption telemetry (rides the unified batch envelope as kind:'ota_event') ──
-export type OtaEventType =
-  | 'CHECK'
-  | 'DOWNLOAD_STARTED'
-  | 'DOWNLOAD_COMPLETE'
-  | 'INSTALLED'
-  | 'APPLY_FAILED'
-  | 'AUTO_ROLLBACK'
-  | 'MANUAL_ROLLBACK';
+//
+// The event vocabulary is declared ONCE, in OtaEventEmitter — the module that
+// emits it. This file used to carry a second, shorter copy under the same name,
+// so `OtaEventItem.type` and the emitter's events could disagree while both
+// type-checked, and adding a funnel step meant remembering to edit two unions.
+// `DOWNLOAD_PROGRESS` is emitted for UI only and never queued for upload, so it
+// is excluded here rather than re-listing the rest.
+import type { OtaEventType as EmittedOtaEventType } from './OtaEventEmitter';
+
+export type OtaEventType = Exclude<EmittedOtaEventType, 'DOWNLOAD_PROGRESS'>;
 
 export interface OtaEventItem {
   kind: 'ota_event';

package/src/features/ota/useOtaUpdate.ts

@@ -115,7 +115,13 @@ export function useOtaUpdate(options: UseOtaUpdateOptions): UseOtaUpdateReturn {
     setIsSyncing(true);
     setDownloadProgress(0);
     try {
-      const result = await otaOrchestrator.sync(options);
+      // Read through the ref, not the closed-over `options`. The dependency list
+      // below cannot name the targeting fields (`attributes` and `segmentIds` are
+      // fresh object/array identities on every render, so listing them would
+      // rebuild this callback each time), which left a host that changed
+      // `channelName` or `lifecycleStage` syncing against the values captured on
+      // first render. The ref is assigned on every render, so it is always current.
+      const result = await otaOrchestrator.sync(optionsRef.current);
       setSyncResult(result);
 
       // Handle mandatory update blocking
@@ -131,7 +137,10 @@ export function useOtaUpdate(options: UseOtaUpdateOptions): UseOtaUpdateReturn {
     } finally {
       setIsSyncing(false);
     }
-  }, [options.apiUrl, options.clientKey, options.appVersion, options.installationId, options.autoRestart]);
+    // Empty: everything this reads comes from `optionsRef`, so the callback has a
+    // stable identity and never needs rebuilding. A host can safely pass it to a
+    // memoised child or an effect dependency list.
+  }, []);
 
   const restart = useCallback(() => {
     setMandatoryUpdatePending(false);

package/src/features/session/JourneyEventPipeline.ts

@@ -93,31 +93,33 @@ export class JourneyEventPipeline {
             journeyId?: string;
             /** Frame that was on screen when this happened. Resolved by the caller; see sessionTypes. */
             frameId?: string;
+            timestamp?: number;
         },
     ): JourneyEvent | null {
         try {
             const key = `${type}:${opts?.subtype ?? ''}`;
-            const now = Date.now();
-            if (key === this.lastEventKey && (now - this.lastEventTs) < this.config.dedupeWindowMs) {
+            const receivedAt = Date.now();
+            const occurredAt = opts?.timestamp ?? receivedAt;
+            if (key === this.lastEventKey && (receivedAt - this.lastEventTs) < this.config.dedupeWindowMs) {
                 // Within dedup window — allow high-confidence native events to
                 // REPLACE a prior low-confidence JS event for the same gesture.
                 // This prevents the race where JS fires first and the pipeline
                 // drops the native event that has more accurate coordinates.
                 const incomingConfidence = (opts?.payload as any)?.confidence;
                 if (incomingConfidence === 'high' && this.lastEventConfidence !== 'high') {
-                    this._replaceLastEvent(key, now, opts);
+                    this._replaceLastEvent(key, receivedAt, opts);
                 }
                 return null;
             }
             this.lastEventKey = key;
-            this.lastEventTs = now;
+            this.lastEventTs = receivedAt;
             this.lastEventConfidence = (opts?.payload as any)?.confidence ?? null;
 
             const event: JourneyEvent = {
                 eventId: generateEventId(),
                 sessionId: this.sessionId,
                 journeyId: opts?.journeyId,
-                ts: now,
+                ts: occurredAt,
                 type,
                 subtype: opts?.subtype,
                 severity: opts?.severity ?? inferSeverity(type),