@scalebun/react-native 1.0.2 → 1.0.3

package/lib/module/features/ota/OtaOrchestrator.js

@@ -1,8 +1,113 @@
-import { DevSettings, NativeModules, Platform } from 'react-native';
+import { AppState, DeviceEventEmitter, DevSettings, NativeEventEmitter, NativeModules, Platform } from 'react-native';
 import { logger } from '../../core/logger/internalLogger';
 import { noThrow } from '../../core/lifecycle/crashSafe';
 import NativeScaleBunOta from '../../specs/NativeScaleBunOta';
 import { otaEventEmitter } from './OtaEventEmitter';
+import { verifyBundleSignature } from './signature';
+import { detectOtaEnvironment } from './environment';
+import { retryWithBackoff, isRetryableNetworkError, HttpStatusError } from './retry';
+import { createStorageBackend } from '../../storage/StorageBackend';
+
+/**
+ * Identity marker injected into the bundle by `scalebun ota publish` before
+ * Hermes compilation. Lets the SDK prove that the bundle it *installed* is the
+ * bundle actually *running* — see `verifyRunningBundleIdentity`.
+ */
+function readRunningBundleMarker() {
+  try {
+    const id = globalThis.__SCALEBUN_OTA_ID__;
+    return typeof id === 'string' && id.length > 0 ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Download progress: native → JS → (hook + backend live tracker).
+ *
+ * Both native downloaders emit throttled `ScaleBunOtaProgress` ticks — Android
+ * over `RCTDeviceEventEmitter`, iOS via the `ScaleBunOtaEvents` RCTEventEmitter.
+ * This subscribes for the duration of one download. Until this existed, the
+ * hook's `downloadProgress` and the backend's `/sdk/ota/progress` +
+ * live-downloads dashboard were declared on both ends and connected by
+ * NOTHING — the tracker had never received a single real row.
+ */
+
+function subscribeNativeProgress(onTick) {
+  try {
+    if (Platform.OS === 'ios') {
+      const eventsModule = NativeModules.ScaleBunOtaEvents;
+      if (!eventsModule) return () => {};
+      const emitter = new NativeEventEmitter(eventsModule);
+      const sub = emitter.addListener('ScaleBunOtaProgress', onTick);
+      return () => sub.remove();
+    }
+    const sub = DeviceEventEmitter.addListener('ScaleBunOtaProgress', onTick);
+    return () => sub.remove();
+  } catch {
+    return () => {};
+  }
+}
+
+/** POST at most once per this interval; first and terminal ticks always go. */
+const PROGRESS_POST_INTERVAL_MS = 1_000;
+
+/**
+ * Deliver queued OTA lifecycle events to the backend's batch endpoint.
+ *
+ * ── Why the orchestrator owns this ──────────────────────────────────────────
+ *
+ * `otaEventEmitter.setFlushCallback` documents itself as "called by the SDK
+ * core to wire into the existing batch transport" — and nothing, anywhere,
+ * ever called it. `flush()` drained the queue into a null callback, so every
+ * OTA event the real SDK ever emitted was silently discarded in-process.
+ * All 129 ota_events rows in the dev database came from the test app's
+ * SIMULATOR; the funnel, adoption charts, and guard thresholds had never seen
+ * one byte of real-device telemetry.
+ *
+ * Owning delivery here (with the params sync() already has) instead of relying
+ * on bootstrap wiring means OTA telemetry works in every integration shape —
+ * full SDK, standalone orchestrator, CodePush shim — because the component
+ * that EMITS the events is the component that delivers them.
+ */
+async function deliverOtaEvents(params) {
+  const events = otaEventEmitter.flush();
+  if (!events.length) return;
+  const items = events.map(e => ({
+    kind: 'ota_event',
+    type: e.type,
+    bundleId: e.bundleId,
+    installationId: params.installationId,
+    platform: Platform.OS === 'ios' ? 'ios' : 'android',
+    appVersion: params.appVersion,
+    durationMs: e.durationMs,
+    errorCode: e.error ?? e.reason,
+    patchUsed: e.patchUsed,
+    timestamp: e.timestamp
+  }));
+  try {
+    const base = params.apiUrl.replace(/\/+$/, '');
+    // The batch lane is session-scoped for replay items; OTA rows carry their
+    // own installationId and ignore the session, so a synthetic id is correct.
+    const res = await fetch(`${base}/ingestion/sessions/ota-${params.installationId}/batch`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-scalebun-client-key': params.clientKey
+      },
+      body: JSON.stringify({
+        items
+      })
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    logger.debug(`[OTA] Delivered ${items.length} telemetry event(s)`);
+  } catch (err) {
+    // Failed delivery must not fail the update — but the events must not be
+    // lost either: requeue so the next sync retries them.
+    for (const e of events) otaEventEmitter.emit(e);
+    logger.debug(`[OTA] Telemetry delivery failed (will retry next sync): ${err?.message}`);
+  }
+}
 
 /** Boot-guard configuration */
 
@@ -14,29 +119,225 @@ export class OtaOrchestrator {
   isRestartRequiredState = false;
   healthyTimer = null;
   bootGuardConfig = {};
+  environment = null;
+  /** One-time boot checks have run in this process (init is idempotent). */
+  initialized = false;
+  storageBackend = null;
 
-  /**
-   * Initialize the orchestrator. Checks for boot-guard recovery state.
+  /**
+   * Initialize the orchestrator. Checks for boot-guard recovery state.
+   *
+   * `signature` is optional: an app that has not adopted signing keeps working
+   * on SHA-256 integrity alone. Once a public key IS configured, a bundle that
+   * cannot be verified is refused rather than installed (OTA-03).
    */
   init(config) {
     noThrow(() => {
+      // Idempotent: init() runs its one-time checks ONCE per process. Found
+      // live — a host that calls init() again after installing an update (any
+      // retry/re-entry path does this) re-runs the identity verification in a
+      // process whose running JS legitimately predates the install, producing
+      // a false "INSTALL DID NOT TAKE EFFECT" alarm. The boot-time checks are
+      // only meaningful in a fresh process; a second init() must not repeat
+      // them. Config is still refreshed so late signature setup works.
+      if (this.initialized) {
+        this.bootGuardConfig = config ?? this.bootGuardConfig;
+        this.signatureConfig = config?.signature ?? this.signatureConfig;
+        return;
+      }
       if (!NativeScaleBunOta) {
         logger.warn('[OTA] NativeScaleBunOta module unavailable — OTA disabled');
         return;
       }
+
+      // ── RUNTIME GATE ─────────────────────────────────────────────────────
+      // Refuse to run on a runtime where the install would silently no-op.
+      // See environment.ts: bridgeless below RN 0.76.1 ignores
+      // getJSBundleFile() entirely, so a bundle installs, reports INSTALLED,
+      // and the app keeps running the APK asset. Staying loudly disabled is
+      // strictly better than reporting success that never happened — those
+      // false INSTALLED rows feed adoption metrics and guard thresholds.
+      this.environment = detectOtaEnvironment();
+      if (!this.environment.supported) {
+        logger.error(`[OTA] DISABLED — ${this.environment.blockReason}`);
+        this.enabled = false;
+        return;
+      }
+      if (this.environment.bridgeless && !this.environment.rnVersion) {
+        logger.warn('[OTA] Running bridgeless but the React Native version could not be determined. ' + 'If this app is below RN 0.76.1, OTA updates will install and never load.');
+      }
+      if (this.environment.requiresReactHostIntegration) {
+        // RN 0.82 removed ReactNativeHost, so the legacy
+        // `override fun getJSBundleFile()` integration does not exist there.
+        // We cannot see which form the host used — the identity check after
+        // restart is what proves it — but naming the right fix up front turns
+        // a confusing silent failure into a one-line correction.
+        logger.debug('[OTA] React Native >= 0.82 detected. The only valid Android integration is ' + 'getDefaultReactHost(..., jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(ctx)) — ' + 'ReactNativeHost and its getJSBundleFile() override no longer exist.');
+      }
+      this.initialized = true;
       this.enabled = true;
       this.bootGuardConfig = config ?? {};
-      logger.debug('[OTA] Orchestrator initialized successfully');
+      this.signatureConfig = config?.signature;
+      logger.debug(`[OTA] Orchestrator initialized (RN ${this.environment.rnVersionString ?? 'unknown'}` + `${this.environment.bridgeless ? ', bridgeless' : ''}` + `${this.environment.hermes ? `, Hermes HBC v${this.environment.hermesBytecodeVersion ?? '?'}` : ''})`);
+
+      // 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();
+
+      // 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();
     });
   }
 
-  /**
-   * Sprint 5 (S5-NAT-1): Check if the native boot guard reverted us on this cold start.
-   * If getSlotState() shows bootMarkerPresent=false but we have a 'previous' slot
-   * and no 'current' OTA bundle, the native layer already reverted.
+  /**
+   * Read the active slot back into `currentBundle` so the next check reports
+   * what this device is genuinely running.
+   */
+  hydrateCurrentBundleFromSlots() {
+    if (!NativeScaleBunOta) return;
+    try {
+      const state = JSON.parse(NativeScaleBunOta.getSlotState());
+      const current = state?.current;
+      if (!current?.sha256) return;
+
+      // Keyed on sha256, NOT bundleId. The native `stageBundle` is never told
+      // the bundleId — it writes a meta.json containing only `sha256` and
+      // `installedAt` — so `current.bundleId` is always absent. Hydrating from
+      // it left `currentBundle` null on every launch, which meant the device
+      // never told the server what it was running and the server re-offered
+      // the same bundle forever. sha256 is the field that is actually there.
+      const record = this.readInstallRecord();
+      if (record && record.sha256 === current.sha256) {
+        this.currentBundle = {
+          id: record.bundleId,
+          version: record.version,
+          sha256: record.sha256
+        };
+        logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
+        return;
+      }
+
+      // An OTA bundle is installed but we have no record of installing it —
+      // a reinstall of the app, cleared storage, or a bundle staged by an
+      // older SDK. Report the hash so the server can still recognise it.
+      this.currentBundle = {
+        sha256: current.sha256
+      };
+      logger.debug(`[OTA] Running an OTA bundle (sha ${String(current.sha256).slice(0, 12)}…) with no local install record.`);
+    } catch {
+      // Slot state unreadable — treat as factory bundle.
+    }
+  }
+
+  /**
+   * Compare the bundle the slot manager believes is active against the identity
+   * marker compiled into the bundle that actually loaded.
+   *
+   * A mismatch means the install path reported success while the runtime kept
+   * executing different code — the silent no-op this whole guard exists for.
+   * It is reported as APPLY_FAILED, because that is what happened, regardless
+   * of what the previous session's telemetry claimed.
+   *
+   * The expectation recorded at install time is what makes this conclusive.
+   * Without it, a missing marker is ambiguous — it could be a bundle published
+   * before markers existed, or an install that never took effect. Having
+   * written down "this bundle definitely carries marker X" before restarting,
+   * a missing marker afterwards can only mean the second.
+   */
+  verifyRunningBundleIdentity() {
+    if (!this.currentBundle) return;
+    const running = readRunningBundleMarker();
+    const expected = this.readInstallExpectation();
+
+    // Stale record from an earlier install — the slot has moved on since.
+    if (expected && expected.bundleId !== this.currentBundle.id) {
+      this.clearInstallExpectation();
+      return;
+    }
+    if (expected) {
+      if (running === expected.identityToken) {
+        // Proven: the bundle we installed is the bundle executing.
+        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.
+      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}`
+      });
+    }
+  }
+
+  // ── Install expectation ────────────────────────────────────────────────────
+  // Written just before the restart that activates a bundle, read on the next
+  // boot. Synchronous, disk-backed, and the same store used for the device id —
+  // it has to survive a process death that happens moments after the write.
+
+  static INSTALL_EXPECTATION_KEY = 'scalebun.ota.pendingInstall';
+  recordInstallExpectation(bundle) {
+    try {
+      this.storage().set(OtaOrchestrator.INSTALL_EXPECTATION_KEY, JSON.stringify({
+        bundleId: bundle.id,
+        version: bundle.version,
+        // The join key back to the native slot, which records sha256 and
+        // nothing else identifying.
+        sha256: bundle.sha256,
+        identityToken: bundle.identityToken ?? null
+      }));
+    } catch {
+      // Verification is a safety net, never a precondition for installing.
+    }
+  }
+  readInstallRecord() {
+    try {
+      const raw = this.storage().get(OtaOrchestrator.INSTALL_EXPECTATION_KEY);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      return typeof parsed?.bundleId === 'string' && typeof parsed?.sha256 === 'string' ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+  readInstallExpectation() {
+    const record = this.readInstallRecord();
+    return record && record.identityToken ? {
+      bundleId: record.bundleId,
+      identityToken: record.identityToken
+    } : null;
+  }
+  clearInstallExpectation() {
+    try {
+      this.storage().set(OtaOrchestrator.INSTALL_EXPECTATION_KEY, '');
+    } catch {
+      /* non-fatal */
+    }
+  }
+  storage() {
+    if (!this.storageBackend) this.storageBackend = createStorageBackend();
+    return this.storageBackend;
+  }
+
+  /**
+   * Sprint 5 (S5-NAT-1): Check if the native boot guard reverted us on this cold start.
+   * If getSlotState() shows bootMarkerPresent=false but we have a 'previous' slot
+   * and no 'current' OTA bundle, the native layer already reverted.
    */
   checkBootGuardRecovery() {
     if (!NativeScaleBunOta) return;
@@ -60,31 +361,57 @@ export class OtaOrchestrator {
     return this.isRestartRequiredState;
   }
 
-  /**
-   * Perform an OTA check against the backend endpoint.
+  /**
+   * Perform an OTA check against the backend endpoint.
    */
   async checkForUpdate(requestParams) {
     try {
+      const env = this.environment ?? detectOtaEnvironment();
+
+      // C1: send the channel and targeting context. `channelName` was already an
+      // accepted parameter here and was then dropped on the floor — the payload
+      // never carried it — so every device resolved to `default` no matter what
+      // the host app asked for. Undefined fields are omitted by JSON.stringify,
+      // so an app that supplies nothing behaves exactly as before.
       const payload = {
         appVersion: requestParams.appVersion,
         platform: Platform.OS === 'ios' ? 'ios' : 'android',
         installationId: requestParams.installationId,
         currentBundleId: this.currentBundle?.id,
-        currentBundleHash: this.currentBundle?.sha256
+        currentBundleHash: this.currentBundle?.sha256,
+        channelName: requestParams.channelName,
+        country: requestParams.country,
+        attributes: requestParams.attributes,
+        segmentIds: requestParams.segmentIds,
+        lifecycleStage: requestParams.lifecycleStage,
+        // Runtime compatibility context. Without these the backend cannot tell
+        // whether a bundle is safe for this binary: appVersion is a marketing
+        // string, while the RN version and the Hermes bytecode format are the
+        // actual runtime contract. A bundle compiled against a different HBC
+        // version either fails to load or crashes later on a missing path.
+        rnVersion: env.rnVersionString ?? undefined,
+        hermes: env.hermes,
+        hermesBytecodeVersion: env.hermesBytecodeVersion ?? undefined,
+        bridgeless: env.bridgeless
       };
       const url = `${requestParams.apiUrl.replace(/\/+$/, '')}/sdk/ota/check`;
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'x-scalebun-client-key': requestParams.clientKey
-        },
-        body: JSON.stringify(payload)
+      const data = await retryWithBackoff(async () => {
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'x-scalebun-client-key': requestParams.clientKey
+          },
+          body: JSON.stringify(payload)
+        });
+        if (!res.ok) {
+          throw new HttpStatusError(`OTA check failed with status ${res.status}`, res.status);
+        }
+        return await res.json();
+      }, {
+        label: 'check',
+        isRetryable: isRetryableNetworkError
       });
-      if (!res.ok) {
-        throw new Error(`OTA check failed with status ${res.status}`);
-      }
-      const data = await res.json();
       return data;
     } catch (err) {
       logger.error(`[OTA] checkForUpdate failed: ${err.message}`);
@@ -94,9 +421,9 @@ export class OtaOrchestrator {
     }
   }
 
-  /**
-   * Downloads, stage, and apply an update in one step.
-   * Sprint 5: emits lifecycle events + starts boot-guard heartbeat.
+  /**
+   * Downloads, stage, and apply an update in one step.
+   * Sprint 5: emits lifecycle events + starts boot-guard heartbeat.
    */
   async sync(params) {
     try {
@@ -145,12 +472,75 @@ export class OtaOrchestrator {
       const bundle = checkRes.bundle;
       let patchUsed = false;
 
+      // ── 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
+      // staging would mean writing unverified code to the slot directory first.
+      const signatureOutcome = await verifyBundleSignature(bundle.sha256, bundle.signature, this.signatureConfig);
+      if (!signatureOutcome.ok) {
+        otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          error: `Signature check failed: ${signatureOutcome.reason}`,
+          version: bundle.version
+        });
+        return {
+          status: 'ERROR',
+          error: `Bundle signature check failed (${signatureOutcome.reason})`,
+          bundle
+        };
+      }
+
       // ── DOWNLOAD ─────────────────────────────────────────────────────────
       otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, {
         version: bundle.version
       });
       const downloadStart = Date.now();
       logger.debug(`[OTA] Downloading update v${bundle.version}…`);
+
+      // Live progress: native tick → DOWNLOAD_PROGRESS (feeds useOtaUpdate) →
+      // throttled POST to the live tracker. `bundle.size` is the authoritative
+      // total — the server just told us — so an unknown native total (-1 on
+      // chunked/gzip bodies) still yields a truthful percentage.
+      let lastPostAt = 0;
+      const postProgress = (bytesRead, status) => {
+        const total = bundle.size > 0 ? bundle.size : Math.max(bytesRead, 1);
+        const percent = Math.min(100, Math.round(bytesRead / total * 100));
+        const elapsedS = (Date.now() - downloadStart) / 1000;
+        const payload = {
+          installationId: params.installationId,
+          bundleId: bundle.id,
+          bytesRead,
+          totalBytes: total,
+          progressPercent: percent,
+          speedKbps: elapsedS > 0 ? Math.round(bytesRead / 1024 / elapsedS) : 0,
+          status
+        };
+        // Fire-and-forget: progress display must never delay or fail the
+        // download it describes.
+        fetch(`${params.apiUrl.replace(/\/+$/, '')}/sdk/ota/progress`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'x-scalebun-client-key': params.clientKey
+          },
+          body: JSON.stringify(payload)
+        }).catch(() => {});
+      };
+      const unsubscribeProgress = subscribeNativeProgress(({
+        bytesRead
+      }) => {
+        const total = bundle.size > 0 ? bundle.size : bytesRead;
+        otaEventEmitter.emit({
+          type: 'DOWNLOAD_PROGRESS',
+          bundleId: bundle.id,
+          timestamp: Date.now(),
+          progress: Math.min(100, Math.round(bytesRead / Math.max(total, 1) * 100))
+        });
+        const now = Date.now();
+        if (now - lastPostAt >= PROGRESS_POST_INTERVAL_MS) {
+          lastPostAt = now;
+          postProgress(bytesRead, 'DOWNLOADING');
+        }
+      });
       let staged = false;
 
       // Sprint 7: Try patch first if offered, fall back to full bundle
@@ -170,12 +560,34 @@ export class OtaOrchestrator {
         }
       }
 
-      // Full-bundle fallback (or primary path when no patch is available)
+      // Full-bundle fallback (or primary path when no patch is available).
+      // Retried with backoff: on a mobile network a transient drop mid-download
+      // is the common case, and previously one failure meant waiting for the
+      // next cold start — often hours away, sometimes never.
       if (!staged) {
-        staged = await NativeScaleBunOta.stageBundle(bundle.url, bundle.sha256);
+        try {
+          staged = await retryWithBackoff(async () => {
+            const ok = await NativeScaleBunOta.stageBundle(bundle.url, bundle.sha256);
+            if (!ok) {
+              // Native returns a bare boolean, so a hash mismatch and a
+              // dropped connection are indistinguishable here. Retrying a
+              // genuine mismatch a couple of times is cheap; not retrying a
+              // dropped connection costs the whole update.
+              throw new Error('stageBundle returned false');
+            }
+            return ok;
+          }, {
+            label: `download v${bundle.version}`,
+            attempts: 3
+          });
+        } catch {
+          staged = false;
+        }
       }
+      unsubscribeProgress();
       if (!staged) {
-        logger.error('[OTA] Staging bundle failed');
+        postProgress(0, 'FAILED');
+        logger.error('[OTA] Staging bundle failed after retries');
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
           error: 'Staging failed — SHA-256 mismatch or download error',
           version: bundle.version
@@ -186,6 +598,7 @@ export class OtaOrchestrator {
           bundle
         };
       }
+      postProgress(bundle.size, 'COMPLETED');
       const downloadDuration = Date.now() - downloadStart;
       otaEventEmitter.emitSimple('DOWNLOAD_COMPLETE', bundle.id, {
         version: bundle.version,
@@ -210,15 +623,36 @@ export class OtaOrchestrator {
       }
       this.currentBundle = bundle;
       this.isRestartRequiredState = true;
+
+      // Written BEFORE the restart, so the next boot can prove whether this
+      // install actually took effect. Only recorded when the server told us the
+      // bundle carries a marker — otherwise there is nothing to compare against
+      // and a recorded expectation would produce a false alarm.
+      // Recorded unconditionally, not only when a marker is present: this is
+      // also the record that tells the next launch WHICH bundle the slot's
+      // sha256 belongs to, without which the device cannot report what it is
+      // running. Identity verification is the second job of this record, and
+      // it is skipped when there is no marker to compare.
+      this.recordInstallExpectation(bundle);
       otaEventEmitter.emitSimple('INSTALLED', bundle.id, {
         version: bundle.version
       });
       logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
 
-      // Flush telemetry events before restart
-      otaEventEmitter.flush();
-      if (params.autoRestart) {
+      // Deliver telemetry BEFORE a restart tears the JS runtime down —
+      // an INSTALLED event queued but not sent would vanish with the process.
+      await deliverOtaEvents(params);
+
+      // Activation, per the release's installMode. `params.autoRestart` is the
+      // host app's own override and continues to force a restart regardless.
+      // These behaviours were documented (docs, CLI help, the CodePush shim's
+      // enum) for a year while nothing implemented them — every release
+      // behaved as ON_NEXT_RESTART no matter what was published.
+      const installMode = bundle.installMode ?? 'ON_NEXT_RESTART';
+      if (params.autoRestart || installMode === 'IMMEDIATE') {
         this.restart();
+      } else if (installMode === 'ON_NEXT_RESUME') {
+        this.armResumeRestart();
       }
       return {
         status: 'UPDATE_INSTALLED',
@@ -231,16 +665,23 @@ export class OtaOrchestrator {
         status: 'ERROR',
         error: err.message ?? 'Unexpected sync failure'
       };
+    } finally {
+      // Every other exit (UP_TO_DATE, ROLLBACK, staging failure, throw)
+      // delivers here. This also carries events queued at INIT — boot-guard
+      // AUTO_ROLLBACKs and identity-check APPLY_FAILEDs fire before any
+      // apiUrl/clientKey exist, so they wait in the queue for the first sync.
+      // Fire-and-forget: delivery is never allowed to delay a result.
+      void deliverOtaEvents(params);
     }
   }
 
-  /**
-   * Sprint 5 (S5-NAT-1): Boot-guard heartbeat.
-   *
-   * After booting from an OTA bundle, start a timer. If the app survives
-   * `healthyAfterMs` without crashing, call `markHealthy()` to clear the
-   * native boot-guard marker. If JS crashes before the timer fires, the
-   * marker stays set and native code reverts on next cold start.
+  /**
+   * Sprint 5 (S5-NAT-1): Boot-guard heartbeat.
+   *
+   * After booting from an OTA bundle, start a timer. If the app survives
+   * `healthyAfterMs` without crashing, call `markHealthy()` to clear the
+   * native boot-guard marker. If JS crashes before the timer fires, the
+   * marker stays set and native code reverts on next cold start.
    */
   startBootGuardHeartbeat() {
     if (!NativeScaleBunOta) return;
@@ -273,13 +714,67 @@ export class OtaOrchestrator {
     }
   }
 
-  /**
-   * Reload the JS app bundle to apply the new update immediately.
+  /** One-shot guard so repeated syncs cannot stack resume listeners. */
+  resumeRestartArmed = false;
+
+  /**
+   * ON_NEXT_RESUME: restart the JS runtime the next time the app returns to
+   * the foreground after genuinely being in the background.
+   *
+   * The staged bundle is already applied at this point — the restart is purely
+   * about WHEN the user experiences the reload. Two deliberate choices:
+   *
+   *  - Armed only after a real background→active transition, never on the
+   *    initial 'active' state, so installing while the user is mid-session
+   *    does not instantly yank the screen out from under them.
+   *  - One-shot. The listener removes itself after firing (or after the
+   *    restart makes the whole question moot).
+   */
+  armResumeRestart() {
+    if (this.resumeRestartArmed) return;
+    this.resumeRestartArmed = true;
+    let wasBackground = false;
+    try {
+      const sub = AppState.addEventListener('change', state => {
+        if (state === 'background') {
+          wasBackground = true;
+          return;
+        }
+        if (state === 'active' && wasBackground) {
+          try {
+            sub.remove();
+          } catch {
+            /* the restart below makes cleanup moot */
+          }
+          this.resumeRestartArmed = false;
+          logger.info('[OTA] App resumed — activating the staged update now');
+          this.restart();
+        }
+      });
+      logger.debug('[OTA] Update staged — will activate on next resume (ON_NEXT_RESUME)');
+    } catch {
+      // AppState unavailable (tests, exotic hosts): the update still activates
+      // on the next cold start, which is the documented fallback behaviour.
+      this.resumeRestartArmed = false;
+    }
+  }
+
+  /**
+   * Reload the JS app bundle to apply the new update immediately.
+   *
+   * Order matters: the native `restartApp()` is the only path that works in
+   * RELEASE builds. `DevSettings.reload()` looks callable there too — it
+   * logged, returned, and reloaded nothing when tested live on a release APK,
+   * which made every "restart" this SDK ever promised a silent no-op in
+   * production. DevSettings remains as the dev-build fallback for hosts that
+   * have not rebuilt native yet.
    */
   restart() {
     noThrow(() => {
       logger.info('[OTA] Triggering app restart…');
-      if (DevSettings && typeof DevSettings.reload === 'function') {
+      if (NativeScaleBunOta && typeof NativeScaleBunOta.restartApp === 'function') {
+        NativeScaleBunOta.restartApp();
+      } else if (DevSettings && typeof DevSettings.reload === 'function') {
         DevSettings.reload();
       } else if (NativeModules.RNReload) {
         NativeModules.RNReload.reload();