@scalebun/react-native 1.11.0 → 1.13.0

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

@@ -84,6 +84,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.
@@ -121,7 +126,6 @@ async function deliverOtaEvents(params) {
 /** Boot-guard configuration */
 
 const DEFAULT_HEALTHY_AFTER_MS = 10_000;
-const DEFAULT_MAX_REVERT_ATTEMPTS = 2;
 export class OtaOrchestrator {
   enabled = false;
   currentBundle = null;
@@ -198,22 +202,35 @@ export class OtaOrchestrator {
       this.signatureConfig = config?.signature;
       __DEV__ && 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 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();
     });
   }
 
@@ -221,10 +238,20 @@ export class OtaOrchestrator {
    * Read the active slot back into `currentBundle` so the next check reports
    * what this device is genuinely running.
    */
-  hydrateCurrentBundleFromSlots() {
-    if (!NativeScaleBunOta) 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) return null;
+    try {
+      return JSON.parse(NativeScaleBunOta.getSlotState());
+    } catch {
+      return null;
+    }
+  }
+  hydrateCurrentBundleFromSlots(state) {
     try {
-      const state = JSON.parse(NativeScaleBunOta.getSlotState());
       const current = state?.current;
       if (!current?.sha256) return;
 
@@ -239,6 +266,7 @@ export class OtaOrchestrator {
         this.currentBundle = {
           id: record.bundleId,
           version: record.version,
+          releaseId: record.releaseId ?? undefined,
           sha256: record.sha256
         };
         __DEV__ && logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
@@ -275,37 +303,42 @@ export 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__ && logger.debug('[OTA] Install verified — running bundle matches what was installed.');
-        this.clearInstallExpectation();
-        return;
-      }
-      logger.error(`[OTA] INSTALL DID NOT TAKE EFFECT — bundle ${this.currentBundle.id} was installed and ` + `carries a known identity marker, but the running bundle reports ` + `${running ?? 'no marker at all'}. The app is executing different code than the slot ` + 'manager believes. Check that the host app resolves the OTA bundle path at launch ' + '(see the ScaleBunOta integration for your React Native version).');
-      otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `install_not_effective — expected ${expected.identityToken}, running ${running ?? 'none'}`
-      });
-      // Deliberately NOT cleared: the condition is still true on the next boot
-      // and should keep reporting until the integration is fixed. Clearing here
-      // would make a permanently broken install look like a one-off.
+
+    // 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__ && 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.
-      logger.error(`[OTA] BUNDLE MISMATCH — slot says ${this.currentBundle.id} is active but the ` + `running bundle identifies as ${running}.`);
-      otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `bundle_identity_mismatch — running ${running}`
-      });
-    }
+    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 ────────────────────────────────────────────────────
@@ -319,6 +352,11 @@ export 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,
@@ -338,12 +376,28 @@ export 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 {
@@ -362,17 +416,43 @@ export 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) return;
+  checkBootGuardRecovery(state) {
     try {
-      const stateJson = NativeScaleBunOta.getSlotState();
-      const state = JSON.parse(stateJson);
-      if (state.bootGuardReverted) {
-        logger.warn('[OTA] Boot guard fired — app was reverted to previous bundle');
-        otaEventEmitter.emitSimple('AUTO_ROLLBACK', state.previous?.bundleId ?? 'unknown', {
-          reason: 'boot_guard_crash_loop_detected'
+      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) {
+        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
     }
@@ -473,6 +553,22 @@ export class OtaOrchestrator {
         };
       }
       __DEV__ && 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') {
         __DEV__ && logger.debug('[OTA] App is up to date');
@@ -486,7 +582,9 @@ export class OtaOrchestrator {
       // 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');
+        otaEventEmitter.emitSimple('MANUAL_ROLLBACK', this.currentBundle?.id ?? 'unknown', {
+          releaseId: this.currentBundle?.releaseId
+        });
         const reverted = await NativeScaleBunOta.revertToPrevious();
         if (reverted) {
           this.currentBundle = null;
@@ -511,6 +609,15 @@ export 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.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
@@ -518,6 +625,7 @@ export class OtaOrchestrator {
       const signatureOutcome = await verifyBundleSignature(bundle.sha256, bundle.signature, this.signatureConfig);
       if (!signatureOutcome.ok) {
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: `Signature check failed: ${signatureOutcome.reason}`,
           version: bundle.version
         });
@@ -530,6 +638,7 @@ export class OtaOrchestrator {
 
       // ── DOWNLOAD ─────────────────────────────────────────────────────────
       otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version
       });
       const downloadStart = Date.now();
@@ -628,6 +737,7 @@ export class OtaOrchestrator {
         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
         });
@@ -640,6 +750,7 @@ export class OtaOrchestrator {
       postProgress(bundle.size, 'COMPLETED');
       const downloadDuration = Date.now() - downloadStart;
       otaEventEmitter.emitSimple('DOWNLOAD_COMPLETE', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version,
         durationMs: downloadDuration,
         patchUsed
@@ -651,6 +762,7 @@ export class OtaOrchestrator {
       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
         });
@@ -674,6 +786,7 @@ export class OtaOrchestrator {
       // it is skipped when there is no marker to compare.
       this.recordInstallExpectation(bundle);
       otaEventEmitter.emitSimple('INSTALLED', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version
       });
       __DEV__ && logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
@@ -746,6 +859,19 @@ export class OtaOrchestrator {
           NativeScaleBunOta?.markHealthy();
           __DEV__ && 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 {

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

@@ -1,2 +1,2 @@
-
+export {};
 //# sourceMappingURL=OtaTypes.js.map

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

@@ -60,7 +60,13 @@ export function useOtaUpdate(options) {
     setIsSyncing(true);
     setDownloadProgress(0);
     try {
-      const result = await 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.sync(optionsRef.current);
       setSyncResult(result);
 
       // Handle mandatory update blocking
@@ -71,7 +77,10 @@ export 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 = useCallback(() => {
     setMandatoryUpdatePending(false);
     otaOrchestrator.restart();

package/lib/module/public/ScaleBunFacade.js

@@ -253,6 +253,11 @@ class ScaleBunFacade {
           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: {
@@ -262,15 +267,123 @@ class ScaleBunFacade {
             verifier
           }
         } : {}),
-        ...(typeof ota.healthyTimeoutMs === 'number' ? {
-          healthyTimeoutMs: ota.healthyTimeoutMs
+        ...(healthyAfterMs !== undefined ? {
+          healthyAfterMs
         } : {})
       });
       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) {
       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__) {
+      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.getDeviceInfo();
+        const appVersion = info?.appVersion;
+        if (!appVersion) {
+          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) {
+        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 = buildDebugConfigFromInitConfig(debugConfig);

package/lib/typescript/core/constants/version.d.ts

@@ -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 declare const SDK_VERSION = "1.11.0";
+export declare const SDK_VERSION = "1.13.0";
 //# sourceMappingURL=version.d.ts.map

package/lib/typescript/features/ota/OtaEventEmitter.d.ts

@@ -5,10 +5,24 @@
  *
  * Sprint 5 deliverable (S5-NAT-2, S5-NAT-3).
  */
-export type OtaEventType = 'CHECK' | 'DOWNLOAD_STARTED' | 'DOWNLOAD_PROGRESS' | 'DOWNLOAD_COMPLETE' | 'INSTALLED' | 'APPLY_FAILED' | 'AUTO_ROLLBACK' | 'MANUAL_ROLLBACK';
+export type OtaEventType = 
+/** A check was made against the server. The denominator of the funnel. */
+'CHECK'
+/** The server answered with a bundle for this device — the offer, before any bytes move. */
+ | 'OFFERED' | 'DOWNLOAD_STARTED' | 'DOWNLOAD_PROGRESS' | 'DOWNLOAD_COMPLETE'
+/** Staged and swapped. Emitted optimistically, BEFORE the bundle has booted. */
+ | 'INSTALLED'
+/** The bundle booted and survived to the healthy mark — the honest activation signal. */
+ | 'BOOT_SUCCESS' | 'APPLY_FAILED' | 'AUTO_ROLLBACK' | 'MANUAL_ROLLBACK';
 export interface OtaEvent {
     type: OtaEventType;
     bundleId: string;
+    /**
+     * The release this bundle was served as. Optional because a bundle installed
+     * by an older SDK has no recorded release; present on everything emitted by a
+     * current one, so the delivery funnel can key by release rather than bundle.
+     */
+    releaseId?: string;
     version?: number;
     /** 0–100 for DOWNLOAD_PROGRESS */
     progress?: number;

package/lib/typescript/features/ota/OtaOrchestrator.d.ts

@@ -15,8 +15,13 @@ export interface BootGuardConfig {
      */
     healthyAfterMs?: number;
     /**
-     * Maximum consecutive boot-guard reverts before the SDK stops trying
-     * OTA bundles and pins to the factory bundle. Default: 2.
+     * @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;
 }
@@ -51,6 +56,11 @@ export declare class OtaOrchestrator {
      * 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;
     private hydrateCurrentBundleFromSlots;
     /**
      * Compare the bundle the slot manager believes is active against the identity
@@ -71,7 +81,16 @@ export declare class OtaOrchestrator {
     private static readonly INSTALL_EXPECTATION_KEY;
     private recordInstallExpectation;
     private readInstallRecord;
-    private readInstallExpectation;
+    /**
+     * 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;
     private clearInstallExpectation;
     private storage;
     /**