@scalebun-release/react-native 2.5.0

package/src/features/ota/OtaOrchestrator.ts

@@ -0,0 +1,1513 @@
+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 { getDeviceCountry, prefetchDeviceCountry } from './geoCountry';
+import { deviceTargetingAttributes } from './deviceAttributes';
+import { resolveInstallationId } from '../../core/id/installationId';
+import { detectOtaEnvironment, type OtaEnvironment } from './environment';
+import { retryWithBackoff, isRetryableNetworkError, HttpStatusError } from './retry';
+import {
+  stageSignedWithRetry,
+  verdictErrorCode,
+  signedPatchSupported,
+  trySignedPatch,
+  type StageVerdict,
+} from './signedDownload';
+import { createStorageBackend, type StorageBackend } from '../../storage/StorageBackend';
+import { resolveMobileOS } from '../../core/context/device';
+
+/**
+ * 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;
+  // A platform OTA cannot serve is not reported as Android — it is not reported at all.
+  const mobileOS = resolveMobileOS();
+  if (!mobileOS) return;
+
+  const items = events.map((e) => ({
+    kind: 'ota_event' as const,
+    type: e.type,
+    bundleId: e.bundleId,
+    // Without this the backend stored a null releaseId on every row it ingested,
+    // while serving the release id on every check — so the delivery funnel could
+    // only ever be grouped by bundle, and a bundle re-promoted under a second
+    // release merged the two into one indistinguishable series.
+    releaseId: e.releaseId,
+    installationId: params.installationId,
+    // OTA bundles are compiled per platform, so this genuinely is ios|android. Narrowed via
+    // resolveMobileOS so a non-mobile RN target is skipped rather than served an Android bundle.
+    platform: mobileOS,
+    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 {
+  /**
+   * `WITHHELD` means the device reported root/jailbreak indicators and the host
+   * configured `onCompromisedDevice: 'withhold'`. It is NOT `UP_TO_DATE`: the
+   * device may well be behind, we simply declined to find out. Collapsing the
+   * two would make a withheld fleet indistinguishable from a current one.
+   */
+  status:
+    | 'UP_TO_DATE'
+    | 'UPDATE_INSTALLED'
+    | 'ROLLED_BACK'
+    | 'ERROR'
+    | 'WITHHELD';
+  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;
+  /**
+   * @deprecated Not honoured, and never was — nothing in JS reads this field.
+   *
+   * The boot-attempt limit lives in native code, where the counter it bounds is
+   * incremented (`MAX_BOOT_ATTEMPTS` in `SlotManager.kt` / `OtaSlotManager.swift`,
+   * both 2). Setting it here has no effect; the field is kept only so existing
+   * call sites keep compiling. Change the limit natively, or file a request for
+   * it to be plumbed through `initOutbox`-style native config.
+   */
+  maxRevertAttempts?: number;
+  /**
+   * What to do when the device reports root/jailbreak indicators.
+   *
+   *   'allow'    — DEFAULT. Check, download and install as normal. The
+   *                indicators are still detected, still logged, and still sent
+   *                with the check request as telemetry.
+   *   'withhold' — Do not check for or install updates on this device. The
+   *                device stays on whatever bundle it is already running.
+   *
+   * The default is `'allow'` and must stay `'allow'`. Flipping it would
+   * silently stop updates for every existing host app — including the ones
+   * whose "indicators" are a developer's test-keys build or a false positive —
+   * which is a far worse outcome than the risk it mitigates. Withholding is an
+   * opt-in a security-sensitive host makes with knowledge of its own users.
+   *
+   * What this is and is not: root defeats any check made from inside the app,
+   * so this is a POLICY, not a security boundary. A rooted device can patch the
+   * check out. What it does buy is that the SDK stops handing fresh, signed
+   * bundles to a device whose OTA slot other privileged processes can rewrite,
+   * and that the decision is auditable — an `UPDATE_WITHHELD` OTA event is
+   * emitted every time it fires, so the host never has to infer it from
+   * silence.
+   *
+   * Mobile only by nature. The web SDK ships no OTA lane at all — there is no
+   * bundle slot on a device to protect and no web counterpart to this flag.
+   */
+  onCompromisedDevice?: 'allow' | 'withhold';
+}
+
+import { resolveCompromisedDevicePolicy } from '../../config/otaPolicyState';
+
+const DEFAULT_HEALTHY_AFTER_MS = 10_000;
+
+export class OtaOrchestrator {
+  private enabled = false;
+  private currentBundle: OtaBundlePayload | null = null;
+
+  /**
+   * The bundle this process is running, once hydrated from the native slots.
+   * Read-only view for integrations (e.g. the CodePush shim's
+   * getUpdateMetadata) that need to report the running version.
+   */
+  public getCurrentBundle(): OtaBundlePayload | null {
+    return this.currentBundle;
+  }
+  private isRestartRequiredState = false;
+
+  /**
+   * The sync currently running, if any. sync() had NO concurrency control:
+   * every caller started a full check/download/stage/apply cycle against the
+   * SAME slot directories. Two of them overlapping is not a wasted request,
+   * it is a corrupted install — native stage() ends with "remove next/,
+   * rename tmp -> next/" while apply() is doing "move next/ -> current/", so
+   * one racing the other throws and apply() can leave NO current/ slot at
+   * all. A host with a screen that syncs on mount and another that syncs on
+   * foreground reproduces this in seconds; on 2026-09-21 it cost two devices
+   * that could only be recovered by reinstalling.
+   */
+  private syncInFlight: Promise<SyncResult> | null = null;
+
+  /** When the last network check actually went out (see MIN_CHECK_INTERVAL_MS). */
+  private lastCheckAt = 0;
+
+  /**
+   * A bundle that is staged and waiting for its restart.
+   *
+   * Kept SEPARATE from `currentBundle`, which must keep naming the bundle
+   * this process is actually executing. Overwriting `currentBundle` at apply
+   * time told the server the device was already running code it had never
+   * run, so the next check was answered with the NEXT release instead of
+   * "up to date" — which is how a single launch chained three installs. It
+   * also mis-attributed every CHECK and BOOT_SUCCESS event to a bundle the
+   * device had not booted.
+   */
+  private pendingBundle: OtaBundlePayload | null = null;
+  /** Root/jailbreak indicators observed at init; empty when none found. */
+  private integrityIndicators: string[] = [];
+  /**
+   * The native detector was actually asked and answered on this launch.
+   *
+   * Kept separate from an empty `integrityIndicators` because the two are not
+   * the same fact: `false` means never measured (no native module, or the read
+   * threw), `true` with an empty list means measured and clean. Reporting the
+   * first as the second would show an unmeasured fleet as a clean one.
+   */
+  private integrityMeasured = false;
+  private healthyTimer: ReturnType<typeof setTimeout> | null = null;
+  private bootGuardConfig: BootGuardConfig = {};
+  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 enforcement is no longer a JS concern: signed releases are
+   * verified and staged in NATIVE code against RSA keys embedded in the app
+   * package (SB-OTA-RSA-SHA256-V1), and unsigned releases keep working on
+   * SHA-256 integrity alone. There is nothing for the host to configure here.
+   */
+  init(config?: BootGuardConfig): 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;
+        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;
+
+      // Config lands BEFORE the integrity read, so the log below can state the
+      // policy that will actually be applied rather than assume the default.
+      // (It used to be assigned after; the boot-guard heartbeat hit the same
+      // ordering bug once and silently fell back to the default window.)
+      this.bootGuardConfig = config ?? {};
+
+      // Device integrity signal.
+      //
+      // Reported, not enforced. Root defeats any check made from inside the app,
+      // so this is not a boundary — it is context. It tells an operator that a
+      // device's OTA slot is writable by other processes, which is what makes the
+      // launch-time hash re-check in SlotManager meaningful rather than paranoid.
+      //
+      // A host app that wants to act on it sets `onCompromisedDevice:
+      // 'withhold'` (default `'allow'` — see BootGuardConfig), or reads
+      // `deviceIntegrityIndicators()` and decides for itself. The DETECTION here
+      // is unconditional either way; only the decision downstream changes.
+      try {
+        const raw = NativeScaleBunOta?.getDeviceIntegrity?.();
+        this.integrityIndicators = raw ? (JSON.parse(raw) as string[]) : [];
+        // Only a string the detector actually returned counts as a measurement;
+        // an absent method (older native, unsupported platform) leaves this
+        // false so the check request omits the field instead of claiming clean.
+        this.integrityMeasured = typeof raw === 'string';
+        if (this.integrityIndicators.length > 0) {
+          logger.warn(
+            `[OTA] Device integrity indicators present: ${this.integrityIndicators.join(', ')}. ` +
+              (this.shouldWithhold()
+                ? "onCompromisedDevice is 'withhold' — this device will NOT be offered or " +
+                  'installed any update while the indicators persist.'
+                : 'Updates still install and are still signature-verified, but an installed ' +
+                  'bundle on this device can be modified by other privileged processes. ' +
+                  "Set ota.onCompromisedDevice: 'withhold' to stop updating such devices."),
+          );
+        }
+      } catch {
+        this.integrityIndicators = [];
+        this.integrityMeasured = false;
+      }
+      logger.debug(
+        `[OTA] Orchestrator initialized (RN ${this.environment.rnVersionString ?? 'unknown'}` +
+          `${this.environment.bridgeless ? ', bridgeless' : ''}` +
+          `${this.environment.hermes ? `, Hermes HBC v${this.environment.hermesBytecodeVersion ?? '?'}` : ''})`,
+      );
+
+      // ONE read of the slot state, shared by both boot-time consumers.
+      //
+      // `getSlotState()` is CONSUME-ON-READ for the revert record: both native
+      // implementations delete it as they serialise, so that a rollback is
+      // reported exactly once instead of on every launch forever. Calling it
+      // twice therefore means the second caller never sees the revert — which is
+      // precisely what happened, since hydration ran first and swallowed it. It
+      // is also a blocking synchronous bridge call, so one read is cheaper.
+      const slotState = this.readSlotState();
+
+      // Rehydrate which bundle we are running from the native slot state.
+      // Without this `currentBundle` stays null for the whole process after a
+      // restart, so every check reported no current bundle and the backend had
+      // no way to know what the device was actually on.
+      this.hydrateCurrentBundleFromSlots(slotState);
+
+      // Warm the device-country cache (edge Worker lookup) so checks can carry
+      // a country when the API itself sits behind no geo-stamping CDN.
+      // Fire-and-forget and failure-soft — a check without a country is valid.
+      void prefetchDeviceCountry();
+
+      // Check if the boot guard fired on this launch (native reverted before JS
+      // loaded). BEFORE the identity check, because both read the install record
+      // and the identity check retires it — a revert must get its chance to name
+      // the bundle that failed while the record still describes it.
+      this.checkBootGuardRecovery(slotState);
+
+      // Prove the bundle we installed is the bundle that loaded.
+      this.verifyRunningBundleIdentity();
+
+      // Boot-guard health is a LOCAL fact: this process booted from the staged
+      // bundle and did not crash. The heartbeat used to start only on the
+      // `action === 'NONE'` branch of sync(), so confirming a good bundle needed
+      // a successful network round-trip that returned exactly that answer — a
+      // device offline, rate-limited, or still being offered an update could
+      // never clear its marker, and the guard reverted a bundle that was working.
+      //
+      // It runs HERE, last, and is handed the slot state that was already read.
+      // Starting it earlier made it call getSlotState() itself, and that read is
+      // consume-on-read for the revert record — it swallowed the revert before
+      // checkBootGuardRecovery() could name the bundle that failed, so a
+      // crash-rollback went unreported. It also read bootGuardConfig before
+      // init() had assigned it, so healthyAfterMs silently fell back to the
+      // default.
+      this.startBootGuardHeartbeat(slotState);
+    });
+  }
+
+  /**
+   * Read the active slot back into `currentBundle` so the next check reports
+   * what this device is genuinely running.
+   */
+  /**
+   * Parse the native slot state once. Returns null when the module is absent or
+   * the payload is unreadable — every caller treats that as "factory bundle".
+   */
+  private readSlotState(): Record<string, any> | null {
+    if (!NativeScaleBunOta) return null;
+    try {
+      return JSON.parse(NativeScaleBunOta.getSlotState());
+    } catch {
+      return null;
+    }
+  }
+
+  private hydrateCurrentBundleFromSlots(state: Record<string, any> | null): void {
+    try {
+      const 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,
+          releaseId: record.releaseId ?? undefined,
+          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 record = this.readInstallRecord();
+
+    // No record at all — installed by an SDK that predates install records, or
+    // local storage was cleared. NOTHING can be concluded here and nothing is
+    // reported: the marker is a random per-publish token, never the bundle id,
+    // so comparing the two would flag a false mismatch on every healthy launch.
+    if (!record) return;
+
+    // The record describes a bundle that is no longer the active one (a revert,
+    // or a bundle staged by another path). It cannot verify this launch, and
+    // keeping it would make the next launch mis-report what is running.
+    if (record.sha256 !== this.currentBundle.sha256) {
+      this.clearInstallExpectation();
+      return;
+    }
+
+    // Already proven on an earlier launch. The token is retired once verified
+    // while the REST of the record stays — it is also the sha256 -> bundleId map
+    // that `hydrateCurrentBundleFromSlots` reads to report what this device is
+    // running. Wiping the whole record here is what made every launch after the
+    // first send `currentBundleId: undefined`, which the server reads as "not on
+    // this bundle" and answers by serving the same bundle again, forever.
+    if (!record.identityToken) return;
+
+    if (running === record.identityToken) {
+      logger.debug('[OTA] Install verified — running bundle matches what was installed.');
+      this.retireIdentityToken(record);
+      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, {
+      releaseId: this.currentBundle.releaseId,
+      error: `install_not_effective — expected ${record.identityToken}, running ${running ?? 'none'}`,
+    });
+    // Deliberately NOT retired: the condition is still true on the next boot and
+    // should keep reporting until the integration is fixed. Retiring the token
+    // here would make a permanently broken install look like a one-off.
+  }
+
+  // ── Install expectation ────────────────────────────────────────────────────
+  // 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,
+          // Carried so telemetry emitted on a LATER launch (a boot-guard
+          // rollback, an ineffective install) can still be attributed to the
+          // release, not merely the bundle. The check response is long gone by
+          // then; this record is the only thing that remembers.
+          releaseId: bundle.releaseId ?? null,
+          // The join key back to the native slot, which records sha256 and
+          // nothing else identifying.
+          sha256: bundle.sha256,
+          identityToken: bundle.identityToken ?? null,
+        }),
+      );
+    } catch {
+      // Verification is a safety net, never a precondition for installing.
+    }
+  }
+
+  private readInstallRecord(): {
+    bundleId: string;
+    version: number;
+    releaseId?: string | null;
+    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;
+    }
+  }
+
+  /**
+   * Drop the identity token once the install has been proven, keeping the rest
+   * of the record.
+   *
+   * The record does two jobs: it proves an install took effect (once), and it
+   * maps the native slot's sha256 back to a bundle id (for the life of that
+   * bundle). Only the first job is finished after a successful verification, so
+   * only the token is retired.
+   */
+  private retireIdentityToken(record: {
+    bundleId: string;
+    version: number;
+    releaseId?: string | null;
+    sha256: string;
+  }): void {
+    try {
+      this.storage().set(
+        OtaOrchestrator.INSTALL_EXPECTATION_KEY,
+        JSON.stringify({
+          bundleId: record.bundleId,
+          version: record.version,
+          releaseId: record.releaseId ?? null,
+          sha256: record.sha256,
+          identityToken: null,
+        }),
+      );
+    } catch {
+      /* non-fatal */
+    }
+  }
+
+  private clearInstallExpectation(): void {
+    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(state: Record<string, any> | null): void {
+    try {
+      if (!state?.bootGuardReverted) return;
+
+      // WHICH bundle was rolled back, and it has to come from the install
+      // record. The obvious source — `state.previous` — is wrong twice over:
+      // slot meta.json carries only `{sha256, installedAt}` so it has no bundle
+      // id to read, and `revert()` deletes the previous slot as its last step,
+      // so by the time this runs there is no previous meta at all. The event
+      // therefore reported `bundleId: 'unknown'` on every rollback, and the
+      // backend drops any ota_event whose bundleId does not resolve to a bundle
+      // the app owns — so the crash-guard's own rollback signal never arrived.
+      //
+      // Native now stamps the sha256 of the bundle it reverted AWAY FROM into
+      // the revert record; the install record maps that back to a bundle id.
+      const record = this.readInstallRecord();
+      const revertedSha: string | undefined = state.bootGuardRevertedSha256;
+      const matchesRecord = !!record && (!revertedSha || record.sha256 === revertedSha);
+
+      // Report the reason native actually determined — a hash mismatch and a
+      // crash loop are different incidents and were being collapsed into one.
+      const reason: string = state.bootGuardRevertReason || 'boot_crash_guard';
+
+      if (matchesRecord && record) {
+        logger.warn(
+          `[OTA] Boot guard fired — reverted away from bundle ${record.bundleId} ` +
+            `(v${record.version}); reason: ${reason}`,
+        );
+        otaEventEmitter.emitSimple('AUTO_ROLLBACK', record.bundleId, {
+          releaseId: record.releaseId ?? undefined,
+          version: record.version,
+          reason,
+        });
+        // The record describes a bundle this device is no longer running.
+        this.clearInstallExpectation();
+        return;
+      }
+
+      // No usable record (older SDK, cleared storage). Say so rather than
+      // emitting an event the server is obliged to discard.
+      logger.warn(
+        `[OTA] Boot guard fired (reason: ${reason}) but the rolled-back bundle could not be ` +
+          'identified locally — no install record. The rollback is not reported to the server.',
+      );
+    } catch {
+      // Slot state parsing failed — non-fatal
+    }
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * Root/jailbreak indicators detected on this device, as stable reason strings.
+   * Empty means nothing was detected — not proof the device is clean.
+   */
+  deviceIntegrityIndicators(): string[] {
+    return [...this.integrityIndicators];
+  }
+
+  /**
+   * Should this device be refused an update?
+   *
+   * TRUE only when BOTH are so: the host opted into `'withhold'`, and the native
+   * detector actually found something. An empty indicator list is never a reason
+   * to withhold — "nothing detected" is the normal state of every healthy
+   * device, and treating it as a reason would brick updates for the whole fleet
+   * the moment a host set the flag.
+   */
+  private shouldWithhold(): boolean {
+    // Resolved at DECISION time, not at init: /config is fetched asynchronously,
+    // so a policy that arrives mid-session takes effect on the next check rather
+    // than only on the next launch.
+    //
+    // STRICTEST WINS and the server can only TIGHTEN — see
+    // resolveCompromisedDevicePolicy. A host that asked for 'withhold' keeps it
+    // whatever the server says; a customer who has shipped nothing can still be
+    // switched on without an app release, which is the point of the feature.
+    return (
+      resolveCompromisedDevicePolicy(this.bootGuardConfig.onCompromisedDevice) ===
+        'withhold' && this.integrityIndicators.length > 0
+    );
+  }
+
+  /**
+   * Announce the refusal, once per decision point.
+   *
+   * A withheld update must be visible as a decision, not as an absence. The
+   * event carries the indicators that drove it so the host can log WHY, and it
+   * names the bundle the device stays on (`'unknown'` for a device still on the
+   * factory bundle, which owns no OTA bundle id).
+   */
+  private emitWithheld(): void {
+    logger.warn(
+      `[OTA] Update WITHHELD — device integrity indicators present (${this.integrityIndicators.join(', ')}) ` +
+        "and ota.onCompromisedDevice is 'withhold'. This device stays on its current bundle.",
+    );
+    otaEventEmitter.emitSimple('UPDATE_WITHHELD', this.currentBundle?.id ?? 'unknown', {
+      releaseId: this.currentBundle?.releaseId,
+      version: this.currentBundle?.version,
+      indicators: [...this.integrityIndicators],
+    });
+  }
+
+  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 {
+      // ── COMPROMISED-DEVICE POLICY ────────────────────────────────────────
+      // Opt-in, default 'allow' (see BootGuardConfig.onCompromisedDevice). The
+      // short-circuit is HERE as well as in sync() because checkForUpdate is a
+      // public entry point in its own right — the CodePush shim's
+      // `checkForUpdate` and any host that drives the check by hand reach the
+      // network through this method without going through sync().
+      if (this.shouldWithhold()) {
+        this.emitWithheld();
+        return { action: 'NONE' };
+      }
+
+      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.
+      // OTA has no bundle for a non-mobile target; claiming Android there would install the wrong one.
+      const mobileOS = resolveMobileOS();
+      if (!mobileOS) throw new Error('OTA is not supported on this platform');
+      // SDK trust coverage (CICDPAGE §12): report which trusted key IDs are
+      // embedded in this binary so the dashboard can measure key-rotation
+      // adoption. Telemetry only — the server never trusts a key a device claims.
+      // Defensive: optional native method, never let it break a check.
+      let trustedKeyIds: string[] | undefined;
+      try {
+        const raw = NativeScaleBunOta?.getTrustedKeyIds?.();
+        if (raw) {
+          const arr = JSON.parse(raw);
+          if (Array.isArray(arr) && arr.length) trustedKeyIds = arr.slice(0, 16);
+        }
+      } catch {
+        /* trust reporting is best-effort — never break the update check */
+      }
+      const payload: OtaCheckRequest = {
+        appVersion: requestParams.appVersion,
+        platform: mobileOS,
+        installationId: requestParams.installationId,
+        currentBundleId: this.currentBundle?.id,
+        currentBundleHash: this.currentBundle?.sha256,
+        ...(signedPatchSupported(NativeScaleBunOta) ? { otaCapabilities: ['signed_patch_v1'] } : {}),
+        trustedKeyIds,
+        // Root/jailbreak indicators, so a console can report how much of a fleet
+        // is affected instead of every operator guessing. Telemetry only — the
+        // server must never trust it (a rooted device can send `[]`), and the
+        // withholding decision above is made entirely on-device.
+        //
+        // `[]` and absent mean DIFFERENT things and are kept apart: `[]` is
+        // "the detector ran and found nothing", absent is "never measured"
+        // (native module missing, or the read threw). Sending `[]` for both
+        // would report an unmeasured fleet as a clean one.
+        integrityIndicators: this.integrityMeasured
+          ? [...this.integrityIndicators]
+          : undefined,
+        channelName: requestParams.channelName,
+        // Host-supplied country wins; otherwise the cached edge-Worker lookup
+        // fills in (see geoCountry.ts). Undefined when neither knows — the
+        // server renders unknown as unknown rather than guessing.
+        country: requestParams.country ?? getDeviceCountry() ?? undefined,
+        // Hardware/OS context under the host's own attributes (host wins on
+        // collision) — this is what lets ATTRIBUTE rules target device classes
+        // (deviceModel / manufacturer / brand / osVersion / formFactor).
+        attributes: { ...deviceTargetingAttributes(), ...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.
+   */
+  /**
+   * Minimum gap between network checks. Not a policy, a stampede guard: an
+   * app that syncs on mount AND on every foreground transition can otherwise
+   * issue a burst of identical checks. Small enough not to get in the way of
+   * publishing and testing a release.
+   */
+  private static readonly MIN_CHECK_INTERVAL_MS = 15_000;
+
+  /**
+   * Check, download, stage and apply — at most ONE at a time.
+   *
+   * Concurrent callers join the sync already running rather than starting a
+   * second one, and a call made while an update is already staged returns
+   * without touching the slots: the staged bundle has to be activated by a
+   * restart before anything else can usefully happen, and re-checking here
+   * is what used to chain a second install onto the first.
+   */
+  async sync(rawParams: Parameters<OtaOrchestrator['runSync']>[0]): Promise<SyncResult> {
+    if (this.isRestartRequiredState) {
+      logger.debug(
+        '[OTA] An update is staged and waiting for a restart — skipping this check.',
+      );
+      return { status: 'UP_TO_DATE', bundle: this.pendingBundle ?? undefined };
+    }
+    if (this.syncInFlight) {
+      logger.debug('[OTA] A sync is already running — joining it.');
+      return this.syncInFlight;
+    }
+    const elapsed = Date.now() - this.lastCheckAt;
+    if (this.lastCheckAt > 0 && elapsed < OtaOrchestrator.MIN_CHECK_INTERVAL_MS) {
+      logger.debug(
+        `[OTA] Checked ${Math.round(elapsed / 1000)}s ago — within the ${
+          OtaOrchestrator.MIN_CHECK_INTERVAL_MS / 1000
+        }s minimum interval, skipping.`,
+      );
+      return { status: 'UP_TO_DATE' };
+    }
+    this.lastCheckAt = Date.now();
+    this.syncInFlight = this.runSync(rawParams).finally(() => {
+      this.syncInFlight = null;
+    });
+    return this.syncInFlight;
+  }
+
+  private async runSync(rawParams: {
+    apiUrl: string;
+    clientKey: string;
+    appVersion: string;
+    /** Omit to use the SDK's canonical per-install id (recommended — P8). */
+    installationId?: string;
+    // P1: these five existed on checkForUpdate and on the wire contract, but
+    // sync() — the only caller that matters — never accepted them, so they
+    // were structurally undefined on every real device: every install pinned
+    // to the `default` channel and the whole targeting engine matched nothing.
+    // The C1 comment in OtaTypes.ts claimed this was fixed; the plumbing had
+    // stopped exactly one function short of true.
+    channelName?: string;
+    country?: string;
+    attributes?: Record<string, string | number>;
+    segmentIds?: string[];
+    lifecycleStage?: string;
+    /**
+     * @deprecated IGNORED. Activation is driven strictly by the release's
+     * installMode (IMMEDIATE / ON_NEXT_RESUME / ON_NEXT_RESTART). This flag is
+     * pinned false internally and honoured nowhere — publish an IMMEDIATE
+     * release instead of forcing a client-side restart.
+     */
+    autoRestart?: boolean;
+  }): Promise<SyncResult> {
+    const params = {
+      ...rawParams,
+      installationId: rawParams.installationId ?? resolveInstallationId(),
+      // ENFORCED GLOBALLY: the legacy client `autoRestart` override is ignored —
+      // pinned false here so no app config (or future code path that reads
+      // params.autoRestart) can re-enable it. Activation is driven STRICTLY by
+      // the release's server-set installMode: IMMEDIATE restarts now,
+      // ON_NEXT_RESUME arms a resume-restart, ON_NEXT_RESTART (default) applies
+      // on the next cold start. Honouring `autoRestart:true` forced every release
+      // to restart immediately (defeating installMode), and on bridgeless it
+      // forced the in-process restart that cannot load a staged bundle.
+      autoRestart: false as boolean,
+    };
+    try {
+      if (!this.enabled || !NativeScaleBunOta) {
+        return { status: 'ERROR', error: 'OTA native module disabled or missing' };
+      }
+
+      // ── COMPROMISED-DEVICE POLICY ────────────────────────────────────────
+      // Before ANY network call and before the CHECK event: a withheld device
+      // must not appear in the funnel's denominator as a device that asked and
+      // was told nothing. It did not ask. Default is 'allow', so this is inert
+      // unless the host opted in (see BootGuardConfig.onCompromisedDevice).
+      if (this.shouldWithhold()) {
+        this.emitWithheld();
+        return { status: 'WITHHELD' };
+      }
+
+      logger.debug('[OTA] Sync started…');
+
+      // The funnel's denominator, for devices already on an OTA bundle. Emitted
+      // before the request, so a check that fails outright still counts as a
+      // check — the only CHECK rows before this came from a server-side geo
+      // side-effect that is skipped whenever the request carries no country.
+      //
+      // Only when a current bundle is known: every ota_event must name a bundle
+      // the app owns or the server drops it, and a device still on the binary's
+      // factory bundle has no such id to give. Those devices are counted
+      // server-side when they are offered something.
+      if (this.currentBundle?.id) {
+        otaEventEmitter.emitSimple('CHECK', this.currentBundle.id, {
+          releaseId: this.currentBundle.releaseId,
+          version: this.currentBundle.version,
+        });
+      }
+
+      const checkRes = await this.checkForUpdate(params);
+
+      if (checkRes.action === 'NONE') {
+        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', {
+          releaseId: this.currentBundle?.releaseId,
+        });
+        const reverted = await NativeScaleBunOta.revertToPrevious();
+        if (reverted) {
+          this.currentBundle = null;
+          // isRestartRequired flips true; the reverted bundle binds on the next
+          // cold start. autoRestart is intentionally not consulted (pinned false
+          // in sync()) — activation policy is uniform across update and rollback.
+          this.isRestartRequiredState = true;
+          return { status: 'ROLLED_BACK' };
+        }
+        return { status: 'ERROR', error: 'Native rollback failed' };
+      }
+
+      if (!checkRes.bundle) {
+        return { status: 'UP_TO_DATE' };
+      }
+
+      const bundle = checkRes.bundle;
+      // When the presigned download URL (300 s TTL) was issued — a retry past 240 s re-checks.
+      const offeredAt = Date.now();
+      let patchUsed = false;
+
+      // The offer itself. Everything downstream (download, install, activation)
+      // is a conversion against this, so without it the top of the funnel was
+      // unmeasurable and a rollout that never reached devices looked identical
+      // to one whose devices all declined to download.
+      otaEventEmitter.emitSimple('OFFERED', bundle.id, {
+        releaseId: bundle.releaseId,
+        version: bundle.version,
+      });
+
+      // ── DOWNLOAD ─────────────────────────────────────────────────────────
+      // Authenticity is enforced NATIVELY now (see the envelope branch below):
+      // SHA-256 proves the bytes arrived intact, and for signed releases the
+      // RSA signature — checked in native code against keys embedded in the app
+      // package — proves they came from you. JS neither pins keys nor verifies
+      // signatures.
+      otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, {
+        releaseId: bundle.releaseId,
+        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;
+
+      if (bundle.envelope) {
+        // ── NATIVE-ENFORCED VERIFY + STAGE (SB-OTA-RSA-SHA256-V1) ───────────
+        // Hand the whole envelope to native code, which verifies the RSA
+        // signature against the keys EMBEDDED in the app package, then downloads
+        // the artifact, enforces the SIGNED size + SHA-256, and stages it into
+        // the `next` slot — all outside JS. JavaScript never stages bytes it has
+        // not proven authentic. No patch path here: a signed offer is always a
+        // full verified download (native patch is a documented follow-up).
+        //
+        // Retried when — and only when — a retry can help (see signedDownload.ts): one dropped
+        // connection used to lose a 19 MB update until the next cold start. A retry after an
+        // expired URL asks the server again, and stops quietly if the release was withdrawn.
+        const native = NativeScaleBunOta;
+
+        // Patch FIRST when the server offered one and this binary can apply it signed. One
+        // attempt, no retry: on any failure the full download below runs exactly as before, so a
+        // patch can only ever save bytes. Security lives in native (verifyAndStagePatch): the
+        // rebuilt bundle must hash to the SIGNED artifactSha256, from a signed base.
+        if (bundle.patch && signedPatchSupported(native)) {
+          const pv = await trySignedPatch(native as any, bundle.envelope, bundle.url, bundle.patch);
+          if (pv.ok) {
+            patchUsed = true;
+            staged = true;
+            logger.debug(`[OTA] Staged v${bundle.version} from a ${(bundle.patch.size / 1024).toFixed(0)} KB patch`);
+          } else {
+            logger.info(`[OTA] Patch not applied (${pv.code ?? "unknown"}) — downloading the full bundle`);
+          }
+        }
+
+        if (!staged) {
+        const result = await stageSignedWithRetry<typeof bundle>(
+          {
+            attempt: async (b) => {
+              try {
+                const verdictJson = await native.verifyAndStageRelease(
+                  JSON.stringify({ ...b.envelope, downloadUrl: b.url }),
+                );
+                return JSON.parse(verdictJson) as StageVerdict;
+              } catch (err: any) {
+                // A rejected promise (or an unparseable verdict) is machinery failure,
+                // never a valid result — treat it as a hard failure (not retried).
+                return { ok: false, code: 'verify_stage_threw', message: err?.message ?? String(err) };
+              }
+            },
+            recheck: async () => {
+              const again = await this.checkForUpdate(params);
+              return again.action === 'DOWNLOAD' && again.bundle?.envelope ? again.bundle : null;
+            },
+            now: () => Date.now(),
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+          },
+          bundle,
+          offeredAt,
+        );
+        const verdict = result.verdict;
+
+        if (result.withdrawn) {
+          unsubscribeProgress();
+          // No progress post: the live tracker's vocabulary has no "withdrawn", and FAILED would
+          // report a release the server stopped offering as a device that failed to download it.
+          logger.info(
+            `[OTA] Release v${bundle.version} is no longer offered — stopping the download without reporting a failure.`,
+          );
+          return { status: 'UP_TO_DATE' };
+        }
+
+        if (!verdict.ok) {
+          unsubscribeProgress();
+          postProgress(0, 'FAILED');
+          logger.error(
+            `[OTA] Native verify/stage refused the release: ${verdict.code ?? 'unknown'}` +
+              `${verdict.message ? ` — ${verdict.message}` : ''}`,
+          );
+          otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+            releaseId: bundle.releaseId,
+            // `error` is mapped onto the wire `errorCode` by deliverOtaEvents —
+            // carry the stable native verdict code there, with the download
+            // reason when native gave one from the fixed vocabulary
+            // (`DOWNLOAD_FAILED:http_403`). Emitted ONCE, after the last attempt.
+            error: verdictErrorCode(verdict),
+            version: bundle.version,
+          });
+          return {
+            status: 'ERROR',
+            error: `Release verification failed (${verdict.code ?? 'unknown'})`,
+            bundle,
+          };
+        }
+
+        staged = true;
+        }
+      } else {
+        // ── LEGACY / UNSIGNED (SHA-256 integrity only) ─────────────────────
+        // No envelope means the app embeds no trusted keys and the release is
+        // unsigned: keep the pre-RSA behaviour so those apps still update.
+
+        // 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, {
+          releaseId: bundle.releaseId,
+          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, {
+        releaseId: bundle.releaseId,
+        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, {
+          releaseId: bundle.releaseId,
+          error: 'Atomic slot swap failed',
+          version: bundle.version,
+        });
+        return { status: 'ERROR', error: 'Applying update failed', bundle };
+      }
+
+      // NOT `this.currentBundle` — see the field docs. This process is still
+      // executing the previous bundle; the staged one becomes current when a
+      // restart binds it, and hydrateCurrentBundleFromSlots reads it back from
+      // the install record on the next launch.
+      this.pendingBundle = 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, {
+        releaseId: bundle.releaseId,
+        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 is driven STRICTLY by the release's installMode. The legacy
+      // client `autoRestart` override is pinned false in sync() (see above), so
+      // it no longer participates — a release activates exactly as published:
+      // IMMEDIATE restarts now, ON_NEXT_RESUME on next foreground, and
+      // ON_NEXT_RESTART (the default) on the next cold start.
+      const installMode = bundle.installMode ?? 'ON_NEXT_RESTART';
+      if (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(preRead?: Record<string, any> | null): void {
+    if (!NativeScaleBunOta) return;
+    // A render error already condemned this launch; nothing may re-arm the heartbeat.
+    if (this.bootFailedThisLaunch) return;
+
+    // Cancel any existing timer
+    if (this.healthyTimer) {
+      clearTimeout(this.healthyTimer);
+      this.healthyTimer = null;
+    }
+
+    try {
+      // getSlotState() is CONSUME-ON-READ for the revert record, so a caller that
+      // has already read it passes the parsed result down rather than letting
+      // this read again and swallow a rollback. `null` is a real answer (module
+      // absent or payload unreadable) — only `undefined` means "nobody read it".
+      const state =
+        preRead !== undefined
+          ? preRead
+          : (JSON.parse(NativeScaleBunOta.getSlotState()) as Record<string, any>);
+
+      // 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;
+
+          // The honest activation signal. INSTALLED is emitted optimistically,
+          // BEFORE the bundle has ever executed, so counting it as adoption
+          // credits bundles that were installed and then crash-reverted. This
+          // fires only once the bundle has actually booted and survived.
+          const running = this.currentBundle;
+          if (running?.id) {
+            otaEventEmitter.emitSimple('BOOT_SUCCESS', running.id, {
+              releaseId: running.releaseId,
+              version: running.version,
+              durationMs: healthyMs,
+            });
+          }
+        });
+      }, healthyMs);
+    } catch {
+      // State parsing failed — non-fatal, don't block
+    }
+  }
+
+  private bootFailedThisLaunch = false;
+
+  /**
+   * A render error was caught while a freshly-applied bundle is still inside its health window.
+   *
+   * WHY. The boot guard's only evidence of a bad bundle is that the process died before
+   * `healthyAfterMs`. An error boundary with a fallback keeps the process ALIVE: the user sees the
+   * fallback, the timer fires, `markHealthy()` runs, and a bundle that cannot render its first
+   * screen is recorded as healthy and never reverted. ScaleBunErrorBoundary calls this so the
+   * marker stays set: the next cold start counts toward the bundle's revert exactly as a crash
+   * would have.
+   *
+   * No-op outside the window (the bundle already proved itself, or this launch is not an OTA
+   * bundle's first run), so a boundary catching an ordinary bug later in the session never
+   * condemns a healthy release.
+   *
+   * @returns true when the window was open and `markHealthy` has been withheld.
+   */
+  noteBootFailure(): boolean {
+    if (!this.healthyTimer) return false;
+    clearTimeout(this.healthyTimer);
+    this.healthyTimer = null;
+    this.bootFailedThisLaunch = true;
+    logger.warn(
+      '[OTA] Boot guard: a render error was caught inside the health window — this bundle is NOT ' +
+        'marked healthy, and the next cold start counts toward reverting it.',
+    );
+    return true;
+  }
+
+  /** 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();