@scalebun/react-native 1.0.2 → 1.0.3

package/src/features/ota/OtaOrchestrator.ts

@@ -1,323 +1,894 @@
-import { DevSettings, 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';
-
-export interface SyncResult {
-  status: 'UP_TO_DATE' | 'UPDATE_INSTALLED' | 'ROLLED_BACK' | 'ERROR';
-  bundle?: OtaBundlePayload;
-  error?: string;
-  /** True when the server-side release has isMandatory set */
-  isMandatory?: boolean;
-}
-
-/** Boot-guard configuration */
-export interface BootGuardConfig {
-  /**
-   * Milliseconds the app must run without crashing after an OTA update
-   * before the boot-guard marker is cleared. Default: 10_000 (10s).
-   */
-  healthyAfterMs?: number;
-  /**
-   * Maximum consecutive boot-guard reverts before the SDK stops trying
-   * OTA bundles and pins to the factory bundle. Default: 2.
-   */
-  maxRevertAttempts?: number;
-}
-
-const DEFAULT_HEALTHY_AFTER_MS = 10_000;
-const DEFAULT_MAX_REVERT_ATTEMPTS = 2;
-
-export class OtaOrchestrator {
-  private enabled = false;
-  private currentBundle: OtaBundlePayload | null = null;
-  private isRestartRequiredState = false;
-  private healthyTimer: ReturnType<typeof setTimeout> | null = null;
-  private bootGuardConfig: BootGuardConfig = {};
-
-  /**
-   * Initialize the orchestrator. Checks for boot-guard recovery state.
-   */
-  init(config?: BootGuardConfig): void {
-    noThrow(() => {
-      if (!NativeScaleBunOta) {
-        logger.warn('[OTA] NativeScaleBunOta module unavailable — OTA disabled');
-        return;
-      }
-      this.enabled = true;
-      this.bootGuardConfig = config ?? {};
-      logger.debug('[OTA] Orchestrator initialized successfully');
-
-      // 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.
-   */
-  private checkBootGuardRecovery(): void {
-    if (!NativeScaleBunOta) return;
-
-    try {
-      const stateJson = NativeScaleBunOta.getSlotState();
-      const state = JSON.parse(stateJson);
-
-      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',
-        });
-      }
-    } catch {
-      // Slot state parsing failed — non-fatal
-    }
-  }
-
-  isEnabled(): boolean {
-    return this.enabled;
-  }
-
-  isRestartRequired(): boolean {
-    return this.isRestartRequiredState;
-  }
-
-  /**
-   * Perform an OTA check against the backend endpoint.
-   */
-  async checkForUpdate(requestParams: {
-    apiUrl: string;
-    clientKey: string;
-    appVersion: string;
-    installationId: string;
-    channelName?: string;
-  }): Promise<OtaCheckResponse> {
-    try {
-      const payload: OtaCheckRequest = {
-        appVersion: requestParams.appVersion,
-        platform: Platform.OS === 'ios' ? 'ios' : 'android',
-        installationId: requestParams.installationId,
-        currentBundleId: this.currentBundle?.id,
-        currentBundleHash: this.currentBundle?.sha256,
-      };
-
-      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: OtaCheckResponse = await res.json();
-      return data;
-    } catch (err: any) {
-      logger.error(`[OTA] checkForUpdate failed: ${err.message}`);
-      return { action: 'NONE' };
-    }
-  }
-
-  /**
-   * Downloads, stage, and apply an update in one step.
-   * Sprint 5: emits lifecycle events + starts boot-guard heartbeat.
-   */
-  async sync(params: {
-    apiUrl: string;
-    clientKey: string;
-    appVersion: string;
-    installationId: string;
-    autoRestart?: boolean;
-  }): Promise<SyncResult> {
-    try {
-      if (!this.enabled || !NativeScaleBunOta) {
-        return { status: 'ERROR', error: 'OTA native module disabled or missing' };
-      }
-
-      logger.debug('[OTA] Sync started…');
-      const checkRes = await this.checkForUpdate(params);
-
-      if (checkRes.action === 'NONE') {
-        logger.debug('[OTA] App is up to date');
-        // If we booted from an OTA bundle and it's healthy, clear the boot guard
-        this.startBootGuardHeartbeat();
-        return { status: 'UP_TO_DATE' };
-      }
-
-      // 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');
-        const reverted = await NativeScaleBunOta.revertToPrevious();
-        if (reverted) {
-          this.currentBundle = null;
-          this.isRestartRequiredState = true;
-          if (params.autoRestart) {
-            this.restart();
-          }
-          return { status: 'ROLLED_BACK' };
-        }
-        return { status: 'ERROR', error: 'Native rollback failed' };
-      }
-
-      if (!checkRes.bundle) {
-        return { status: 'UP_TO_DATE' };
-      }
-
-      const bundle = checkRes.bundle;
-      let patchUsed = false;
-
-      // ── DOWNLOAD ─────────────────────────────────────────────────────────
-      otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, { version: bundle.version });
-      const downloadStart = Date.now();
-      logger.debug(`[OTA] Downloading update v${bundle.version}…`);
-
-      let staged = false;
-
-      // Sprint 7: Try patch first if offered, fall back to full bundle
-      if (bundle.patch && NativeScaleBunOta.stagePatch) {
-        logger.debug(
-          `[OTA] Patch available (${(bundle.patch.size / 1024).toFixed(0)} KB vs ` +
-            `${(bundle.size / 1024).toFixed(0)} KB full) — trying patch…`,
-        );
-        try {
-          staged = await NativeScaleBunOta.stagePatch(
-            bundle.patch.url,
-            bundle.patch.sha256,
-            bundle.sha256, // expected full-bundle hash after patching
-          );
-          if (staged) {
-            patchUsed = true;
-            logger.debug('[OTA] Patch applied successfully');
-          } else {
-            logger.warn('[OTA] Patch staging returned false — falling back to full bundle');
-          }
-        } catch (patchErr: any) {
-          logger.warn(`[OTA] Patch staging failed: ${patchErr.message} — falling back to full bundle`);
-        }
-      }
-
-      // Full-bundle fallback (or primary path when no patch is available)
-      if (!staged) {
-        staged = await NativeScaleBunOta.stageBundle(bundle.url, bundle.sha256);
-      }
-
-      if (!staged) {
-        logger.error('[OTA] Staging bundle failed');
-        otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
-          error: 'Staging failed — SHA-256 mismatch or download error',
-          version: bundle.version,
-        });
-        return { status: 'ERROR', error: 'Staging bundle failed', bundle };
-      }
-
-      const downloadDuration = Date.now() - downloadStart;
-      otaEventEmitter.emitSimple('DOWNLOAD_COMPLETE', bundle.id, {
-        version: bundle.version,
-        durationMs: downloadDuration,
-        patchUsed,
-      });
-
-      // ── APPLY ────────────────────────────────────────────────────────────
-      // 2. Apply update atomically (next→current, current→previous, sets boot marker)
-      const applied = await NativeScaleBunOta.applyUpdate();
-      if (!applied) {
-        logger.error('[OTA] Applying update failed');
-        otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
-          error: 'Atomic slot swap failed',
-          version: bundle.version,
-        });
-        return { status: 'ERROR', error: 'Applying update failed', bundle };
-      }
-
-      this.currentBundle = bundle;
-      this.isRestartRequiredState = true;
-
-      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) {
-        this.restart();
-      }
-
-      return {
-        status: 'UPDATE_INSTALLED',
-        bundle,
-        isMandatory: bundle.isMandatory,
-      };
-    } catch (err: any) {
-      logger.error(`[OTA] Sync error: ${err.message}`);
-      return { status: 'ERROR', error: err.message ?? 'Unexpected sync failure' };
-    }
-  }
-
-  /**
-   * 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.
-   */
-  private startBootGuardHeartbeat(): void {
-    if (!NativeScaleBunOta) return;
-
-    // Cancel any existing timer
-    if (this.healthyTimer) {
-      clearTimeout(this.healthyTimer);
-      this.healthyTimer = null;
-    }
-
-    try {
-      const stateJson = NativeScaleBunOta.getSlotState();
-      const state = JSON.parse(stateJson);
-
-      // Only run the heartbeat if boot-guard marker is present
-      // (meaning we're running from a freshly-applied OTA bundle)
-      if (!state.bootMarkerPresent) {
-        return;
-      }
-
-      const healthyMs = this.bootGuardConfig.healthyAfterMs ?? DEFAULT_HEALTHY_AFTER_MS;
-      logger.debug(`[OTA] Boot guard active — marking healthy after ${healthyMs}ms`);
-
-      this.healthyTimer = setTimeout(() => {
-        noThrow(() => {
-          NativeScaleBunOta?.markHealthy();
-          logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
-          this.healthyTimer = null;
-        });
-      }, healthyMs);
-    } catch {
-      // State parsing failed — non-fatal, don't block
-    }
-  }
-
-  /**
-   * Reload the JS app bundle to apply the new update immediately.
-   */
-  restart(): void {
-    noThrow(() => {
-      logger.info('[OTA] Triggering app restart…');
-      if (DevSettings && typeof DevSettings.reload === 'function') {
-        DevSettings.reload();
-      } else if (NativeModules.RNReload) {
-        NativeModules.RNReload.reload();
-      }
-    });
-  }
-}
-
-export const otaOrchestrator = new OtaOrchestrator();
+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';
+  bundle?: OtaBundlePayload;
+  error?: string;
+  /** True when the server-side release has isMandatory set */
+  isMandatory?: boolean;
+}
+
+/** Boot-guard configuration */
+export interface BootGuardConfig {
+  /**
+   * Milliseconds the app must run without crashing after an OTA update
+   * before the boot-guard marker is cleared. Default: 10_000 (10s).
+   */
+  healthyAfterMs?: number;
+  /**
+   * Maximum consecutive boot-guard reverts before the SDK stops trying
+   * OTA bundles and pins to the factory bundle. Default: 2.
+   */
+  maxRevertAttempts?: number;
+}
+
+const DEFAULT_HEALTHY_AFTER_MS = 10_000;
+const DEFAULT_MAX_REVERT_ATTEMPTS = 2;
+
+export class OtaOrchestrator {
+  private enabled = false;
+  private currentBundle: OtaBundlePayload | null = null;
+  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 & { 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 ?? {};
+      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
+   * and no 'current' OTA bundle, the native layer already reverted.
+   */
+  private checkBootGuardRecovery(): void {
+    if (!NativeScaleBunOta) return;
+
+    try {
+      const stateJson = NativeScaleBunOta.getSlotState();
+      const state = JSON.parse(stateJson);
+
+      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',
+        });
+      }
+    } catch {
+      // Slot state parsing failed — non-fatal
+    }
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  isRestartRequired(): boolean {
+    return this.isRestartRequiredState;
+  }
+
+  /**
+   * Perform an OTA check against the backend endpoint.
+   */
+  async checkForUpdate(requestParams: {
+    apiUrl: string;
+    clientKey: string;
+    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 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 },
+      );
+
+      return data;
+    } catch (err: any) {
+      logger.error(`[OTA] checkForUpdate failed: ${err.message}`);
+      return { action: 'NONE' };
+    }
+  }
+
+  /**
+   * Downloads, stage, and apply an update in one step.
+   * Sprint 5: emits lifecycle events + starts boot-guard heartbeat.
+   */
+  async sync(params: {
+    apiUrl: string;
+    clientKey: string;
+    appVersion: string;
+    installationId: string;
+    autoRestart?: boolean;
+  }): Promise<SyncResult> {
+    try {
+      if (!this.enabled || !NativeScaleBunOta) {
+        return { status: 'ERROR', error: 'OTA native module disabled or missing' };
+      }
+
+      logger.debug('[OTA] Sync started…');
+      const checkRes = await this.checkForUpdate(params);
+
+      if (checkRes.action === 'NONE') {
+        logger.debug('[OTA] App is up to date');
+        // If we booted from an OTA bundle and it's healthy, clear the boot guard
+        this.startBootGuardHeartbeat();
+        return { status: 'UP_TO_DATE' };
+      }
+
+      // 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');
+        const reverted = await NativeScaleBunOta.revertToPrevious();
+        if (reverted) {
+          this.currentBundle = null;
+          this.isRestartRequiredState = true;
+          if (params.autoRestart) {
+            this.restart();
+          }
+          return { status: 'ROLLED_BACK' };
+        }
+        return { status: 'ERROR', error: 'Native rollback failed' };
+      }
+
+      if (!checkRes.bundle) {
+        return { status: 'UP_TO_DATE' };
+      }
+
+      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
+      if (bundle.patch && NativeScaleBunOta.stagePatch) {
+        logger.debug(
+          `[OTA] Patch available (${(bundle.patch.size / 1024).toFixed(0)} KB vs ` +
+            `${(bundle.size / 1024).toFixed(0)} KB full) — trying patch…`,
+        );
+        try {
+          staged = await NativeScaleBunOta.stagePatch(
+            bundle.patch.url,
+            bundle.patch.sha256,
+            bundle.sha256, // expected full-bundle hash after patching
+          );
+          if (staged) {
+            patchUsed = true;
+            logger.debug('[OTA] Patch applied successfully');
+          } else {
+            logger.warn('[OTA] Patch staging returned false — falling back to full bundle');
+          }
+        } catch (patchErr: any) {
+          logger.warn(`[OTA] Patch staging failed: ${patchErr.message} — falling back to full bundle`);
+        }
+      }
+
+      // 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) {
+        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) {
+        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,
+        });
+        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,
+        durationMs: downloadDuration,
+        patchUsed,
+      });
+
+      // ── APPLY ────────────────────────────────────────────────────────────
+      // 2. Apply update atomically (next→current, current→previous, sets boot marker)
+      const applied = await NativeScaleBunOta.applyUpdate();
+      if (!applied) {
+        logger.error('[OTA] Applying update failed');
+        otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          error: 'Atomic slot swap failed',
+          version: bundle.version,
+        });
+        return { status: 'ERROR', error: 'Applying update failed', bundle };
+      }
+
+      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!`);
+
+      // 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',
+        bundle,
+        isMandatory: bundle.isMandatory,
+      };
+    } 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);
+    }
+  }
+
+  /**
+   * 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.
+   */
+  private startBootGuardHeartbeat(): void {
+    if (!NativeScaleBunOta) return;
+
+    // Cancel any existing timer
+    if (this.healthyTimer) {
+      clearTimeout(this.healthyTimer);
+      this.healthyTimer = null;
+    }
+
+    try {
+      const stateJson = NativeScaleBunOta.getSlotState();
+      const state = JSON.parse(stateJson);
+
+      // Only run the heartbeat if boot-guard marker is present
+      // (meaning we're running from a freshly-applied OTA bundle)
+      if (!state.bootMarkerPresent) {
+        return;
+      }
+
+      const healthyMs = this.bootGuardConfig.healthyAfterMs ?? DEFAULT_HEALTHY_AFTER_MS;
+      logger.debug(`[OTA] Boot guard active — marking healthy after ${healthyMs}ms`);
+
+      this.healthyTimer = setTimeout(() => {
+        noThrow(() => {
+          NativeScaleBunOta?.markHealthy();
+          logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
+          this.healthyTimer = null;
+        });
+      }, healthyMs);
+    } catch {
+      // State parsing failed — non-fatal, don't block
+    }
+  }
+
+  /** 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 (NativeScaleBunOta && typeof NativeScaleBunOta.restartApp === 'function') {
+        NativeScaleBunOta.restartApp();
+      } else if (DevSettings && typeof DevSettings.reload === 'function') {
+        DevSettings.reload();
+      } else if (NativeModules.RNReload) {
+        NativeModules.RNReload.reload();
+      }
+    });
+  }
+}
+
+export const otaOrchestrator = new OtaOrchestrator();