@scalebun/react-native 1.11.0 → 1.13.0

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

@@ -90,6 +90,11 @@ async function deliverOtaEvents(params) {
     kind: 'ota_event',
     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.
@@ -127,7 +132,6 @@ async function deliverOtaEvents(params) {
 /** Boot-guard configuration */
 
 const DEFAULT_HEALTHY_AFTER_MS = 10_000;
-const DEFAULT_MAX_REVERT_ATTEMPTS = 2;
 class OtaOrchestrator {
   enabled = false;
   currentBundle = null;
@@ -204,22 +208,35 @@ class OtaOrchestrator {
       this.signatureConfig = config?.signature;
       __DEV__ && _internalLogger.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();
+      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 (0, _geoCountry.prefetchDeviceCountry)();
 
+      // Check if the boot guard fired on this launch (native reverted before JS
+      // loaded). BEFORE the identity check, because both read the install record
+      // and the identity check retires it — a revert must get its chance to name
+      // the bundle that failed while the record still describes it.
+      this.checkBootGuardRecovery(slotState);
+
       // Prove the bundle we installed is the bundle that loaded.
       this.verifyRunningBundleIdentity();
-
-      // Check if the boot guard fired on this launch (native reverted before JS loaded)
-      this.checkBootGuardRecovery();
     });
   }
 
@@ -227,10 +244,20 @@ class OtaOrchestrator {
    * Read the active slot back into `currentBundle` so the next check reports
    * what this device is genuinely running.
    */
-  hydrateCurrentBundleFromSlots() {
-    if (!_NativeScaleBunOta.default) return;
+  /**
+   * Parse the native slot state once. Returns null when the module is absent or
+   * the payload is unreadable — every caller treats that as "factory bundle".
+   */
+  readSlotState() {
+    if (!_NativeScaleBunOta.default) return null;
+    try {
+      return JSON.parse(_NativeScaleBunOta.default.getSlotState());
+    } catch {
+      return null;
+    }
+  }
+  hydrateCurrentBundleFromSlots(state) {
     try {
-      const state = JSON.parse(_NativeScaleBunOta.default.getSlotState());
       const current = state?.current;
       if (!current?.sha256) return;
 
@@ -245,6 +272,7 @@ class OtaOrchestrator {
         this.currentBundle = {
           id: record.bundleId,
           version: record.version,
+          releaseId: record.releaseId ?? undefined,
           sha256: record.sha256
         };
         __DEV__ && _internalLogger.logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
@@ -281,37 +309,42 @@ class OtaOrchestrator {
   verifyRunningBundleIdentity() {
     if (!this.currentBundle) return;
     const running = readRunningBundleMarker();
-    const expected = this.readInstallExpectation();
+    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;
 
-    // Stale record from an earlier install — the slot has moved on since.
-    if (expected && expected.bundleId !== this.currentBundle.id) {
+    // The record describes a bundle that is no longer the active one (a revert,
+    // or a bundle staged by another path). It cannot verify this launch, and
+    // keeping it would make the next launch mis-report what is running.
+    if (record.sha256 !== this.currentBundle.sha256) {
       this.clearInstallExpectation();
       return;
     }
-    if (expected) {
-      if (running === expected.identityToken) {
-        // Proven: the bundle we installed is the bundle executing.
-        __DEV__ && _internalLogger.logger.debug('[OTA] Install verified — running bundle matches what was installed.');
-        this.clearInstallExpectation();
-        return;
-      }
-      _internalLogger.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.otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `install_not_effective — expected ${expected.identityToken}, running ${running ?? 'none'}`
-      });
-      // Deliberately NOT cleared: the condition is still true on the next boot
-      // and should keep reporting until the integration is fixed. Clearing here
-      // would make a permanently broken install look like a one-off.
+
+    // Already proven on an earlier launch. The token is retired once verified
+    // while the REST of the record stays — it is also the sha256 -> bundleId map
+    // that `hydrateCurrentBundleFromSlots` reads to report what this device is
+    // running. Wiping the whole record here is what made every launch after the
+    // first send `currentBundleId: undefined`, which the server reads as "not on
+    // this bundle" and answers by serving the same bundle again, forever.
+    if (!record.identityToken) return;
+    if (running === record.identityToken) {
+      __DEV__ && _internalLogger.logger.debug('[OTA] Install verified — running bundle matches what was installed.');
+      this.retireIdentityToken(record);
       return;
     }
-    if (running && running !== this.currentBundle.id) {
-      // No recorded expectation (installed by an older SDK), but the running
-      // marker disagrees with the active slot outright. Still conclusive.
-      _internalLogger.logger.error(`[OTA] BUNDLE MISMATCH — slot says ${this.currentBundle.id} is active but the ` + `running bundle identifies as ${running}.`);
-      _OtaEventEmitter.otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `bundle_identity_mismatch — running ${running}`
-      });
-    }
+    _internalLogger.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.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 ────────────────────────────────────────────────────
@@ -325,6 +358,11 @@ class OtaOrchestrator {
       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,
@@ -344,12 +382,28 @@ class OtaOrchestrator {
       return null;
     }
   }
-  readInstallExpectation() {
-    const record = this.readInstallRecord();
-    return record && record.identityToken ? {
-      bundleId: record.bundleId,
-      identityToken: record.identityToken
-    } : null;
+
+  /**
+   * Drop the identity token once the install has been proven, keeping the rest
+   * of the record.
+   *
+   * The record does two jobs: it proves an install took effect (once), and it
+   * maps the native slot's sha256 back to a bundle id (for the life of that
+   * bundle). Only the first job is finished after a successful verification, so
+   * only the token is retired.
+   */
+  retireIdentityToken(record) {
+    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 */
+    }
   }
   clearInstallExpectation() {
     try {
@@ -368,17 +422,43 @@ class OtaOrchestrator {
    * If getSlotState() shows bootMarkerPresent=false but we have a 'previous' slot
    * and no 'current' OTA bundle, the native layer already reverted.
    */
-  checkBootGuardRecovery() {
-    if (!_NativeScaleBunOta.default) return;
+  checkBootGuardRecovery(state) {
     try {
-      const stateJson = _NativeScaleBunOta.default.getSlotState();
-      const state = JSON.parse(stateJson);
-      if (state.bootGuardReverted) {
-        _internalLogger.logger.warn('[OTA] Boot guard fired — app was reverted to previous bundle');
-        _OtaEventEmitter.otaEventEmitter.emitSimple('AUTO_ROLLBACK', state.previous?.bundleId ?? 'unknown', {
-          reason: 'boot_guard_crash_loop_detected'
+      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 = 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 = state.bootGuardRevertReason || 'boot_crash_guard';
+      if (matchesRecord && record) {
+        _internalLogger.logger.warn(`[OTA] Boot guard fired — reverted away from bundle ${record.bundleId} ` + `(v${record.version}); reason: ${reason}`);
+        _OtaEventEmitter.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.
+      _internalLogger.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
     }
@@ -479,6 +559,22 @@ class OtaOrchestrator {
         };
       }
       __DEV__ && _internalLogger.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.otaEventEmitter.emitSimple('CHECK', this.currentBundle.id, {
+          releaseId: this.currentBundle.releaseId,
+          version: this.currentBundle.version
+        });
+      }
       const checkRes = await this.checkForUpdate(params);
       if (checkRes.action === 'NONE') {
         __DEV__ && _internalLogger.logger.debug('[OTA] App is up to date');
@@ -492,7 +588,9 @@ class OtaOrchestrator {
       // Handle server-initiated rollback (Sprint 4)
       if (checkRes.action === 'ROLLBACK') {
         _internalLogger.logger.warn('[OTA] Server requested ROLLBACK — reverting to previous bundle');
-        _OtaEventEmitter.otaEventEmitter.emitSimple('MANUAL_ROLLBACK', this.currentBundle?.id ?? 'unknown');
+        _OtaEventEmitter.otaEventEmitter.emitSimple('MANUAL_ROLLBACK', this.currentBundle?.id ?? 'unknown', {
+          releaseId: this.currentBundle?.releaseId
+        });
         const reverted = await _NativeScaleBunOta.default.revertToPrevious();
         if (reverted) {
           this.currentBundle = null;
@@ -517,6 +615,15 @@ class OtaOrchestrator {
       const bundle = checkRes.bundle;
       let patchUsed = false;
 
+      // The offer itself. Everything downstream (download, install, activation)
+      // is a conversion against this, so without it the top of the funnel was
+      // unmeasurable and a rollout that never reached devices looked identical
+      // to one whose devices all declined to download.
+      _OtaEventEmitter.otaEventEmitter.emitSimple('OFFERED', bundle.id, {
+        releaseId: bundle.releaseId,
+        version: bundle.version
+      });
+
       // ── VERIFY AUTHENTICITY (OTA-03) ─────────────────────────────────────
       // Before anything touches the disk. SHA-256 proves the bytes arrived
       // intact; only the signature proves they came from you. Checking after
@@ -524,6 +631,7 @@ class OtaOrchestrator {
       const signatureOutcome = await (0, _signature.verifyBundleSignature)(bundle.sha256, bundle.signature, this.signatureConfig);
       if (!signatureOutcome.ok) {
         _OtaEventEmitter.otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: `Signature check failed: ${signatureOutcome.reason}`,
           version: bundle.version
         });
@@ -536,6 +644,7 @@ class OtaOrchestrator {
 
       // ── DOWNLOAD ─────────────────────────────────────────────────────────
       _OtaEventEmitter.otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version
       });
       const downloadStart = Date.now();
@@ -634,6 +743,7 @@ class OtaOrchestrator {
         postProgress(0, 'FAILED');
         _internalLogger.logger.error('[OTA] Staging bundle failed after retries');
         _OtaEventEmitter.otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: 'Staging failed — SHA-256 mismatch or download error',
           version: bundle.version
         });
@@ -646,6 +756,7 @@ class OtaOrchestrator {
       postProgress(bundle.size, 'COMPLETED');
       const downloadDuration = Date.now() - downloadStart;
       _OtaEventEmitter.otaEventEmitter.emitSimple('DOWNLOAD_COMPLETE', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version,
         durationMs: downloadDuration,
         patchUsed
@@ -657,6 +768,7 @@ class OtaOrchestrator {
       if (!applied) {
         _internalLogger.logger.error('[OTA] Applying update failed');
         _OtaEventEmitter.otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: 'Atomic slot swap failed',
           version: bundle.version
         });
@@ -680,6 +792,7 @@ class OtaOrchestrator {
       // it is skipped when there is no marker to compare.
       this.recordInstallExpectation(bundle);
       _OtaEventEmitter.otaEventEmitter.emitSimple('INSTALLED', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version
       });
       __DEV__ && _internalLogger.logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
@@ -752,6 +865,19 @@ class OtaOrchestrator {
           _NativeScaleBunOta.default?.markHealthy();
           __DEV__ && _internalLogger.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.otaEventEmitter.emitSimple('BOOT_SUCCESS', running.id, {
+              releaseId: running.releaseId,
+              version: running.version,
+              durationMs: healthyMs
+            });
+          }
         });
       }, healthyMs);
     } catch {

package/lib/commonjs/features/ota/OtaTypes.js

@@ -1,2 +1,6 @@
 "use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 //# sourceMappingURL=OtaTypes.js.map

package/lib/commonjs/features/ota/useOtaUpdate.js

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

package/lib/commonjs/public/ScaleBunFacade.js

@@ -259,6 +259,11 @@ class ScaleBunFacade {
           _internalLogger.logger.warn('[ScaleBun] A signing key is pinned but no signature verifier is available. ' + 'Signature checking is fail-closed: updates will be REJECTED until one exists. ' + 'Install the optional peers `@noble/ed25519` + `@noble/hashes` (no further ' + 'code needed), or supply `ota.verifySignature`.');
         }
       }
+      // `healthyAfterMs` is the field BootGuardConfig actually declares.
+      // This passed `healthyTimeoutMs`, which nothing reads, so a host that
+      // tuned the boot-guard window silently got the 10s default instead.
+      // Both spellings are accepted so the older one keeps working.
+      const healthyAfterMs = typeof ota.healthyAfterMs === 'number' ? ota.healthyAfterMs : typeof ota.healthyTimeoutMs === 'number' ? ota.healthyTimeoutMs : undefined;
       otaOrchestrator.init({
         ...(signingRequested ? {
           signature: {
@@ -268,15 +273,123 @@ class ScaleBunFacade {
             verifier
           }
         } : {}),
-        ...(typeof ota.healthyTimeoutMs === 'number' ? {
-          healthyTimeoutMs: ota.healthyTimeoutMs
+        ...(healthyAfterMs !== undefined ? {
+          healthyAfterMs
         } : {})
       });
       _internalLogger.logger.info('[ScaleBun] OTA enabled from init config.');
+
+      // Run the checks the config asked for. Until this existed, `ota.enabled`
+      // initialised the orchestrator and then never checked anything: the
+      // documented `checkOnForeground` and `channelOverride` options were read
+      // by no code at all, and an app following the documented config received
+      // updates only if it ALSO drove `useOtaUpdate` or the CodePush shim by
+      // hand. Nothing logged, because "no update available" and "never asked"
+      // look identical from the outside.
+      this._startOtaChecks(ota);
     } catch (err) {
       _internalLogger.logger.warn(`[ScaleBun] OTA init failed: ${err?.message ?? err}`);
     }
   }
+
+  /** Guards against overlapping config-driven OTA checks. */
+  _otaCheckInFlight = false;
+  /** Wall clock of the last config-driven check, for the foreground floor. */
+  _otaLastCheckAt = 0;
+  _otaForegroundListener = null;
+
+  /**
+   * Minimum gap between config-driven checks.
+   *
+   * A foreground transition is cheap to trigger — app switchers, permission
+   * dialogs and share sheets all produce one — so an unthrottled check would
+   * put a request on the hot path every time the user glanced away. Ten
+   * minutes is well below any realistic release cadence and well above that
+   * noise. A host that wants a check on demand calls `useOtaUpdate().sync()`,
+   * which is never throttled.
+   */
+  static OTA_MIN_CHECK_INTERVAL_MS = 10 * 60 * 1000;
+
+  /**
+   * Drive OTA checks from init config: once at startup, then on each
+   * foreground when `checkOnForeground` is on (the schema default).
+   *
+   * `appVersion` is resolved from the native bridge rather than asked of the
+   * integrator, because it gates the server's `targetAppVersion` semver check
+   * — sending a wrong or invented value is worse than sending none, and there
+   * is no honest default. If it cannot be resolved, the check is skipped with
+   * a warning instead of guessing.
+   */
+  _startOtaChecks(ota) {
+    // Never in a debug build. `ScaleBunOtaModule.getJSBundleFile()` returns null
+    // there on purpose so Metro keeps ownership of the bundle — so a bundle
+    // downloaded in dev is installed into a slot that will never be loaded, and
+    // the identity check on the next launch then correctly observes that the
+    // running code is not what was installed and reports APPLY_FAILED. Checking
+    // at all in dev buys nothing and manufactures that false alarm. A developer
+    // testing the OTA path drives `useOtaUpdate().sync()` explicitly.
+    if (__DEV__) {
+      _internalLogger.logger.info('[ScaleBun] OTA checks are skipped in debug builds (Metro owns the bundle).');
+      return;
+    }
+    const runCheck = async trigger => {
+      if (this._otaCheckInFlight) return;
+      if (trigger === 'foreground' && Date.now() - this._otaLastCheckAt < ScaleBunFacade.OTA_MIN_CHECK_INTERVAL_MS) {
+        return;
+      }
+      const clientKey = this._clientKey;
+      const apiUrl = this._apiBaseUrl;
+      if (!clientKey || !apiUrl) return;
+      this._otaCheckInFlight = true;
+      try {
+        const info = await _bridgeAdapter.bridgeAdapter.getDeviceInfo();
+        const appVersion = info?.appVersion;
+        if (!appVersion) {
+          _internalLogger.logger.warn('[ScaleBun] OTA check skipped — the app version could not be read from the ' + 'native bridge. Rebuild the native app, or drive checks yourself with ' + 'useOtaUpdate({ appVersion }).');
+          return;
+        }
+        this._otaLastCheckAt = Date.now();
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const {
+          otaOrchestrator
+        } = require('../features/ota/OtaOrchestrator');
+        await otaOrchestrator.sync({
+          apiUrl,
+          clientKey,
+          appVersion,
+          // The documented option, finally connected. Omitted means the
+          // server's `default` channel, exactly as before.
+          channelName: typeof ota.channelOverride === 'string' ? ota.channelOverride : undefined
+          // Never forced from config: the release's own installMode
+          // decides when the app restarts, and yanking the screen out
+          // from under a user is not a decision this switch should make.
+        });
+      } catch (err) {
+        _internalLogger.logger.warn(`[ScaleBun] OTA check failed: ${err?.message ?? err}`);
+      } finally {
+        this._otaCheckInFlight = false;
+      }
+    };
+    void runCheck('startup');
+    if (ota.checkOnForeground === false) return;
+    if (this._otaForegroundListener) return; // idempotent across repeated init()
+    try {
+      // Through `appLifecycle`, not a second AppState subscription: the SDK
+      // already owns one and fanning out from it keeps every consumer on the
+      // same transition sequence.
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const {
+        appLifecycle
+      } = require('../core/lifecycle/appLifecycle');
+      this._otaForegroundListener = state => {
+        if (state === 'active') void runCheck('foreground');
+      };
+      appLifecycle.addListener(this._otaForegroundListener);
+    } catch {
+      // Lifecycle unavailable (tests, exotic hosts) — the startup check stands.
+      this._otaForegroundListener = null;
+    }
+  }
   _autoEnableDebug(debugConfig) {
     try {
       const dbgConfig = (0, _debug.buildDebugConfigFromInitConfig)(debugConfig);

package/lib/module/core/constants/version.js

@@ -8,5 +8,5 @@
  * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
  * version was introduced to solve.
  */
-export const SDK_VERSION = '1.11.0';
+export const SDK_VERSION = '1.13.0';
 //# sourceMappingURL=version.js.map