@scalebun/react-native 1.0.1 → 1.0.3

package/src/features/ota/OtaOrchestrator.ts

@@ -1,9 +1,136 @@
-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 type { OtaCheckRequest, OtaCheckResponse, OtaBundlePayload } from './OtaTypes';
 import { otaEventEmitter } from './OtaEventEmitter';
+import { verifyBundleSignature, type SignatureConfig } from './signature';
+import { detectOtaEnvironment, type OtaEnvironment } from './environment';
+import { retryWithBackoff, isRetryableNetworkError, HttpStatusError } from './retry';
+import { createStorageBackend, type StorageBackend } 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(): string | null {
+  try {
+    const id = (globalThis as unknown as { __SCALEBUN_OTA_ID__?: string }).__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.
+ */
+interface NativeProgressTick {
+  bytesRead: number;
+  /** -1 when the server sent no usable length (chunked / gzip). */
+  totalBytes: number;
+}
+
+function subscribeNativeProgress(
+  onTick: (tick: NativeProgressTick) => void,
+): () => void {
+  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: {
+  apiUrl: string;
+  clientKey: string;
+  appVersion: string;
+  installationId: string;
+}): Promise<void> {
+  const events = otaEventEmitter.flush();
+  if (!events.length) return;
+
+  const items = events.map((e) => ({
+    kind: 'ota_event' as const,
+    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: any) {
+    // 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}`);
+  }
+}
 
 export interface SyncResult {
   status: 'UP_TO_DATE' | 'UPDATE_INSTALLED' | 'ROLLED_BACK' | 'ERROR';
@@ -36,25 +163,262 @@ export class OtaOrchestrator {
   private isRestartRequiredState = false;
   private healthyTimer: ReturnType<typeof setTimeout> | null = null;
   private bootGuardConfig: BootGuardConfig = {};
+  private signatureConfig: SignatureConfig | undefined;
+  private environment: OtaEnvironment | null = null;
+  /** One-time boot checks have run in this process (init is idempotent). */
+  private initialized = false;
+  private storageBackend: StorageBackend | null = null;
 
   /**
    * 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?: BootGuardConfig): void {
+  init(config?: BootGuardConfig & { signature?: SignatureConfig }): void {
     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();
     });
   }
 
+  /**
+   * Read the active slot back into `currentBundle` so the next check reports
+   * what this device is genuinely running.
+   */
+  private hydrateCurrentBundleFromSlots(): void {
+    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,
+        } as OtaBundlePayload;
+        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 } as OtaBundlePayload;
+      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.
+   */
+  private verifyRunningBundleIdentity(): void {
+    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.
+
+  private static readonly INSTALL_EXPECTATION_KEY = 'scalebun.ota.pendingInstall';
+
+  private recordInstallExpectation(bundle: OtaBundlePayload): void {
+    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.
+    }
+  }
+
+  private readInstallRecord(): {
+    bundleId: string;
+    version: number;
+    sha256: string;
+    identityToken: string | null;
+  } | null {
+    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;
+    }
+  }
+
+  private readInstallExpectation(): { bundleId: string; identityToken: string } | null {
+    const record = this.readInstallRecord();
+    return record && record.identityToken
+      ? { bundleId: record.bundleId, identityToken: record.identityToken }
+      : null;
+  }
+
+  private clearInstallExpectation(): void {
+    try {
+      this.storage().set(OtaOrchestrator.INSTALL_EXPECTATION_KEY, '');
+    } catch {
+      /* non-fatal */
+    }
+  }
+
+  private storage(): StorageBackend {
+    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
@@ -95,31 +459,65 @@ export class OtaOrchestrator {
     appVersion: string;
     installationId: string;
     channelName?: string;
+    country?: string;
+    attributes?: Record<string, string | number>;
+    segmentIds?: string[];
+    lifecycleStage?: string;
   }): Promise<OtaCheckResponse> {
     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: OtaCheckRequest = {
         appVersion: requestParams.appVersion,
         platform: Platform.OS === 'ios' ? 'ios' : 'android',
         installationId: requestParams.installationId,
         currentBundleId: this.currentBundle?.id,
         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),
-      });
 
-      if (!res.ok) {
-        throw new Error(`OTA check failed with status ${res.status}`);
-      }
+      const data = await retryWithBackoff<OtaCheckResponse>(
+        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()) as OtaCheckResponse;
+        },
+        { label: 'check', isRetryable: isRetryableNetworkError },
+      );
 
-      const data: OtaCheckResponse = await res.json();
       return data;
     } catch (err: any) {
       logger.error(`[OTA] checkForUpdate failed: ${err.message}`);
@@ -176,11 +574,77 @@ 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: number, status: string) => {
+        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
@@ -206,13 +670,36 @@ 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,
@@ -220,6 +707,8 @@ export class OtaOrchestrator {
         return { status: 'ERROR', error: 'Staging bundle failed', bundle };
       }
 
+      postProgress(bundle.size, 'COMPLETED');
+
       const downloadDuration = Date.now() - downloadStart;
       otaEventEmitter.emitSimple('DOWNLOAD_COMPLETE', bundle.id, {
         version: bundle.version,
@@ -242,14 +731,34 @@ 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 {
@@ -260,6 +769,13 @@ export class OtaOrchestrator {
     } catch (err: any) {
       logger.error(`[OTA] Sync error: ${err.message}`);
       return { 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);
     }
   }
 
@@ -305,13 +821,68 @@ export class OtaOrchestrator {
     }
   }
 
+  /** One-shot guard so repeated syncs cannot stack resume listeners. */
+  private 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).
+   */
+  private armResumeRestart(): void {
+    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(): void {
     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();