@hot-updater/react-native 1.1.4 → 1.2.0-rc.1

package/ios/HotUpdater/Internal/BundleFileStorageService.swift

@@ -344,6 +344,14 @@ public protocol BundleStorageService {
      * Restores the original bundle and clears downloaded bundle state.
      */
     func resetChannel() -> Result<Bool, Error>
+
+    /**
+     * Resets the channel only while the named Release selection is current,
+     * checked and reset in one critical section with the catalog checks, so
+     * a newer catalog accepted meanwhile keeps the channel. Success is false
+     * for a stale selection.
+     */
+    func resetChannelIfSelectionCurrent(catalogId: String, scopeKey: String, generation: Int64, catalogHash: String, channel: String, selectionContextHash: String) -> Result<Bool, Error>
 }
 
 public extension BundleStorageService {
@@ -356,10 +364,12 @@ public extension BundleStorageService {
     func getActiveUpdateState() -> [String: Any] { [:] }
     func isReleaseSelectionCurrent(catalogId _: String, scopeKey _: String, generation _: Int64, catalogHash _: String, channel _: String, selectionContextHash _: String) -> Bool { false }
     func commitReleaseSelection(_: PersistedSelection) -> Bool { false }
+    func resetChannelIfSelectionCurrent(catalogId _: String, scopeKey _: String, generation _: Int64, catalogHash _: String, channel _: String, selectionContextHash _: String) -> Result<Bool, Error> { .success(false) }
 }
 
 class BundleFileStorageService: BundleStorageService {
     private static let maximumSafeByteSize: Int64 = 9_007_199_254_740_991
+    private static let nilUUID = "00000000-0000-0000-0000-000000000000"
     /// Files downloaded at once when the archive is not used.
     static let parallelFileDownloads = 16
     /// What one request costs beyond the first `parallelFileDownloads`, in
@@ -564,10 +574,75 @@ class BundleFileStorageService: BundleStorageService {
         return (patchDirectory as NSString).appendingPathComponent("\(safeName).bsdiff")
     }
 
+    /// Copies, with no OTA bundle installed, the packaged file each built-in
+    /// patch was made from, when its bytes are the patch's base: store
+    /// processing may have changed them. Only these patches are priced and
+    /// applied; the others fall back to their files.
+    private func prepareBuiltInPatchBases(
+        downloads: [String: ChangedAssetDescriptor],
+        currentBundleId: String?,
+        tempDirectory: String
+    ) -> [String: String] {
+        guard currentBundleId == nil else { return [:] }
+        var bases: [String: String] = [:]
+        for (assetPath, descriptor) in downloads {
+            guard let patch = descriptor.patch,
+                  isPatchForRunningBundle(patch, currentBundleId: nil) else {
+                continue
+            }
+            let basePath = patchBaseTempPath(
+                tempDirectory: tempDirectory,
+                assetPath: assetPath
+            )
+            if builtInAssetResolver.copyIfMatches(
+                assetPath: assetPath,
+                expectedHash: patch.baseFileHash,
+                destination: basePath
+            ) {
+                bases[assetPath] = basePath
+            } else {
+                try? fileSystem.removeItem(atPath: basePath)
+            }
+        }
+        return bases
+    }
+
+    /// Where the built-in bundle's file is copied to serve as a patch's base.
+    private func patchBaseTempPath(
+        tempDirectory: String,
+        assetPath: String
+    ) -> String {
+        let safeName = assetPath
+            .replacingOccurrences(of: "/", with: "__")
+            .replacingOccurrences(of: "\\", with: "__")
+        let patchDirectory = (tempDirectory as NSString).appendingPathComponent("patches")
+        _ = fileSystem.createDirectory(atPath: patchDirectory)
+        return (patchDirectory as NSString).appendingPathComponent("\(safeName).base")
+    }
+
     private func patchDownloadPath(assetPath: String) -> String {
         return "\(assetPath).bsdiff"
     }
 
+    /// Whether `patch` was made against the running bundle: the OTA bundle
+    /// `currentBundleId`, or with none, the built-in bundle, whose ID is
+    /// MIN_BUNDLE_ID once its native build is registered.
+    private func isPatchForRunningBundle(
+        _ patch: BsdiffPatchDescriptor,
+        currentBundleId: String?
+    ) -> Bool {
+        guard patch.algorithm == "bsdiff" else { return false }
+        if let currentBundleId {
+            return currentBundleId == patch.baseBundleId
+        }
+        // A Debug build reports the nil UUID, and has no built-in bundle.
+        guard let builtInBundleId = resolveBuiltInBundleId(),
+              builtInBundleId != Self.nilUUID else {
+            return false
+        }
+        return builtInBundleId == patch.baseBundleId
+    }
+
     private func downloadPath(
         assetPath: String,
         changedAsset: ChangedAssetDescriptor
@@ -609,6 +684,7 @@ class BundleFileStorageService: BundleStorageService {
         changedAsset: ChangedAssetDescriptor,
         currentBundleId: String?,
         currentBundleDir: String?,
+        builtInBasePath: String?,
         destinationPath: String,
         expectedHash: String,
         tempDirectory: String,
@@ -616,29 +692,34 @@ class BundleFileStorageService: BundleStorageService {
         progressHandler: @escaping (UpdateProgressPayload) -> Void
     ) -> Bool {
         guard let patch = changedAsset.patch,
-              patch.algorithm == "bsdiff",
-              currentBundleId == patch.baseBundleId,
-              let currentBundleDir
+              isPatchForRunningBundle(patch, currentBundleId: currentBundleId)
         else {
             return false
         }
 
         let sourcePath: String
-        do {
-            sourcePath = try FileUtilities.fileURL(
-                for: assetPath,
-                destinationRoot: currentBundleDir
-            ).path
-        } catch {
-            return false
-        }
-        guard self.fileSystem.fileExists(atPath: sourcePath),
-              HashUtils.verifyHash(
-                fileURL: URL(fileURLWithPath: sourcePath),
-                expectedHash: patch.baseFileHash
-              )
-        else {
-            return false
+        if currentBundleId == nil {
+            // Copied and checked before the plan priced the patch.
+            guard let builtInBasePath else { return false }
+            sourcePath = builtInBasePath
+        } else {
+            guard let currentBundleDir else { return false }
+            do {
+                sourcePath = try FileUtilities.fileURL(
+                    for: assetPath,
+                    destinationRoot: currentBundleDir
+                ).path
+            } catch {
+                return false
+            }
+            guard self.fileSystem.fileExists(atPath: sourcePath),
+                  HashUtils.verifyHash(
+                    fileURL: URL(fileURLWithPath: sourcePath),
+                    expectedHash: patch.baseFileHash
+                  )
+            else {
+                return false
+            }
         }
 
         let patchPath = patchTempPath(
@@ -648,6 +729,9 @@ class BundleFileStorageService: BundleStorageService {
 
         defer {
             try? self.fileSystem.removeItem(atPath: patchPath)
+            if currentBundleId == nil {
+                try? self.fileSystem.removeItem(atPath: sourcePath)
+            }
             if self.fileSystem.fileExists(atPath: destinationPath),
                !HashUtils.verifyHash(
                 fileURL: URL(fileURLWithPath: destinationPath),
@@ -1165,7 +1249,9 @@ class BundleFileStorageService: BundleStorageService {
         archive: ParsedArchive?,
         archiveUrl: URL?,
         downloads: [String: ChangedAssetDescriptor],
-        assets: [String: ParsedManifestAsset]
+        assets: [String: ParsedManifestAsset],
+        currentBundleId: String?,
+        builtInPatchBases: [String: String]
     ) -> Bool {
         guard downloads.count >= 2,
               archive != nil,
@@ -1181,7 +1267,11 @@ class BundleFileStorageService: BundleStorageService {
                 return false
             }
             let plannedByteSize: Int64
-            if let patch = descriptor.patch {
+            // Only a patch this device applies saves bytes.
+            if let patch = descriptor.patch,
+               currentBundleId == nil
+                ? builtInPatchBases[path] != nil
+                : isPatchForRunningBundle(patch, currentBundleId: currentBundleId) {
                 hasOfferedPatch = true
                 guard let patchByteSize = patch.byteSize,
                       patchByteSize >= 0,
@@ -2228,6 +2318,7 @@ class BundleFileStorageService: BundleStorageService {
         changedAsset: ChangedAssetDescriptor,
         currentBundleId: String?,
         currentBundleDir: String?,
+        builtInBasePath: String?,
         destinationPath: String,
         tempDirectory: String,
         progressFile: UpdateProgressPayload.DiffProgressFileSnapshot,
@@ -2240,6 +2331,7 @@ class BundleFileStorageService: BundleStorageService {
             changedAsset: changedAsset,
             currentBundleId: currentBundleId,
             currentBundleDir: currentBundleDir,
+            builtInBasePath: builtInBasePath,
             destinationPath: destinationPath,
             expectedHash: expectedHash,
             tempDirectory: tempDirectory,
@@ -2374,7 +2466,7 @@ class BundleFileStorageService: BundleStorageService {
             // A patch for the running bundle was offered, but the original
             // file came instead; a patch for another base was never tried.
             let patchWasTried = changedAsset.patch.map {
-                $0.algorithm == "bsdiff" && $0.baseBundleId == currentBundleId
+                isPatchForRunningBundle($0, currentBundleId: currentBundleId)
             } ?? false
             return .downloaded(patchFallback: patchWasTried)
         case .failure(let error):
@@ -2850,11 +2942,18 @@ class BundleFileStorageService: BundleStorageService {
             // The archive is chosen before any patch is tried, so only the
             // per-file install can fall back from a patch.
             var patchFallbacks = false
+            let builtInPatchBases = prepareBuiltInPatchBases(
+                downloads: downloads,
+                currentBundleId: currentBundleId,
+                tempDirectory: tempDirectory
+            )
             if shouldUseArchive(
                 archive: targetManifest.archive,
                 archiveUrl: archiveUrl,
                 downloads: downloads,
-                assets: targetManifest.assets
+                assets: targetManifest.assets,
+                currentBundleId: currentBundleId,
+                builtInPatchBases: builtInPatchBases
             ), let archive = targetManifest.archive, let archiveUrl {
                 do {
                     diffFiles = try UpdateFailureError.during(.storage, resource: .archive) {
@@ -2908,6 +3007,7 @@ class BundleFileStorageService: BundleStorageService {
                             let outcome = try self.downloadManifestAsset(
                                 assetPath: assetPath, expectedAsset: expectedAsset, changedAsset: descriptor,
                                 currentBundleId: currentBundleId, currentBundleDir: currentBundleDir,
+                                builtInBasePath: builtInPatchBases[assetPath],
                                 destinationPath: destinationPath, tempDirectory: workerTemp, progressFile: progressFile,
                                 progressHandler: { payload in
                                     progressLock.lock()
@@ -3216,6 +3316,31 @@ class BundleFileStorageService: BundleStorageService {
         return getBundleMetadataSnapshot(bundleId: bundleId)?.manifest ?? [:]
     }
 
+    func resetChannelIfSelectionCurrent(
+        catalogId: String,
+        scopeKey: String,
+        generation: Int64,
+        catalogHash: String,
+        channel: String,
+        selectionContextHash: String
+    ) -> Result<Bool, Error> {
+        // The catalog checks take the same recursive lock, so none accepts a
+        // newer catalog between this check and the reset.
+        releaseStateLock.lock()
+        defer { releaseStateLock.unlock() }
+        guard isReleaseSelectionCurrent(
+            catalogId: catalogId,
+            scopeKey: scopeKey,
+            generation: generation,
+            catalogHash: catalogHash,
+            channel: channel,
+            selectionContextHash: selectionContextHash
+        ) else {
+            return .success(false)
+        }
+        return resetChannel()
+    }
+
     func resetChannel() -> Result<Bool, Error> {
         releaseStateLock.lock()
         defer { releaseStateLock.unlock() }

package/ios/HotUpdater/Internal/HotUpdater.mm

@@ -1213,6 +1213,15 @@ RCT_EXPORT_MODULE();
                                            rejecter:reject];
 }
 
+- (void)resetChannelIfSelectionCurrent:(NSDictionary *)params
+                               resolve:(RCTPromiseResolveBlock)resolve
+                                reject:(RCTPromiseRejectBlock)reject {
+    [HotUpdaterNativeUpdates() resetChannelIfSelectionCurrentWithImpl:[self instanceImpl]
+                                                               params:params
+                                                             resolver:resolve
+                                                             rejecter:reject];
+}
+
 - (facebook::react::ModuleConstants<JS::NativeHotUpdater::Constants::Builder>)constantsToExport {
     return [self getConstants];
 }
@@ -1394,6 +1403,15 @@ RCT_EXPORT_METHOD(resetChannel:(RCTPromiseResolveBlock)resolve
                                            rejecter:reject];
 }
 
+RCT_EXPORT_METHOD(resetChannelIfSelectionCurrent:(NSDictionary *)params
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    [HotUpdaterNativeUpdates() resetChannelIfSelectionCurrentWithImpl:[self instanceImpl]
+                                                               params:params
+                                                             resolver:resolve
+                                                             rejecter:reject];
+}
+
 - (NSDictionary *)constantsToExport {
     return [self _buildConstantsDictionary];
 }

package/ios/HotUpdater/Internal/HotUpdaterImpl.swift

@@ -1062,6 +1062,37 @@ private func hotUpdaterGetMinBundleId() -> String {
         }
     }
 
+    /// Resets the channel while the Release selection `params` names is
+    /// current, as `resetChannel` does; resolves false for a stale one.
+    @objc
+    public func resetChannelIfSelectionCurrent(
+        _ params: [AnyHashable: Any]?,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        guard let guardParams = ReleaseSelectionGuardParams(params) else {
+            resolver(false)
+            return
+        }
+        let result = launchPreparationLock.resetChannelIfSelectionCurrent(guardParams, in: bundleStorage) {
+            do {
+                try preferences.setItem(nil, forKey: Self.CHANNEL_STORAGE_KEY)
+            } catch {
+                NSLog("[HotUpdaterImpl] Failed to clear channel override: \(error)")
+            }
+            self.currentLaunchSelection = nil
+        }
+
+        switch result {
+        case .success(let success):
+            resolver(success)
+        case .failure(let error):
+            let normalizedCode = HotUpdaterImpl.normalizeErrorCode(from: error)
+            let nsError = error as NSError
+            reject(normalizedCode, nsError.localizedDescription, nsError)
+        }
+    }
+
     private func prepareLaunchIfNeeded(bundle: Bundle) -> LaunchSelection {
         launchPreparationLock.withLock { prepareLaunchLocked(bundle: bundle) }
     }

package/ios/HotUpdater/Internal/HotUpdaterInterface.swift

@@ -37,6 +37,20 @@ final class HotUpdaterNativeUpdatesAdapter: NSObject, HotUpdaterNativeUpdatesInt
         HotUpdaterNativeUpdateBridge.resetChannel(impl: impl as! HotUpdaterImpl, resolver: resolve, rejecter: reject)
     }
 
+    func resetChannelIfSelectionCurrent(
+        withImpl impl: HotUpdaterImplInterface,
+        params: [AnyHashable: Any]?,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        HotUpdaterNativeUpdateBridge.resetChannelIfSelectionCurrent(
+            impl: impl as! HotUpdaterImpl,
+            params: params,
+            resolver: resolve,
+            rejecter: reject
+        )
+    }
+
     func takeEvents(withImpl impl: HotUpdaterImplInterface) -> String? {
         HotUpdaterNativeUpdateBridge.takeEvents(impl: impl as! HotUpdaterImpl)
     }

package/ios/HotUpdater/Internal/HotUpdaterNativeUpdates.swift

@@ -80,6 +80,13 @@ final class HotUpdaterImplUpdateHost: NativeUpdateHost {
         return (value as? Bool) ?? false
     }
 
+    func resetChannelIfSelectionCurrent(_ guardParams: [String: Any]) async -> Bool {
+        let value = try? await promise { resolve, reject in
+            self.impl.resetChannelIfSelectionCurrent(guardParams, resolver: resolve, rejecter: reject)
+        }
+        return (value as? Bool) ?? false
+    }
+
     func releaseCatalogCache(_ partition: String) -> String? {
         impl.releaseCatalogCacheValue(partition)
     }
@@ -216,6 +223,36 @@ public final class HotUpdaterNativeUpdateBridge: NSObject {
         }
     }
 
+    /// `resetChannelIfSelectionCurrent` for JavaScript: waits for a native
+    /// check or staging as `resetChannel` does, then resets only while the
+    /// Release selection `params` names is current.
+    @objc(resetChannelIfSelectionCurrentWithImpl:params:resolver:rejecter:)
+    public static func resetChannelIfSelectionCurrent(
+        impl: HotUpdaterImpl,
+        params: [AnyHashable: Any]?,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        let checker = checker(impl: impl)
+        Task {
+            await checker.whenIdle {
+                await withCheckedContinuation { (done: CheckedContinuation<Void, Never>) in
+                    impl.resetChannelIfSelectionCurrent(params, resolver: { value in
+                        // The reset deleted staged bundles; their queued downloads go too.
+                        if (value as? Bool) == true {
+                            NativeUpdateEvents.remove(name: "onBundleDownloaded", from: HotUpdaterImplUpdateHost(impl: impl))
+                        }
+                        resolve(value)
+                        done.resume()
+                    }, rejecter: { code, message, error in
+                        reject(code, message, error)
+                        done.resume()
+                    })
+                }
+            }
+        }
+    }
+
     /// The queued plugin events as a JSON array, cleared as they are taken.
     @objc(takeEventsWithImpl:)
     public static func takeEvents(impl: HotUpdaterImpl) -> String? {

package/ios/HotUpdater/Internal/LaunchPreparationLock.swift

@@ -30,6 +30,30 @@ final class LaunchPreparationLock {
         }
     }
 
+    /// Resets the channel in `storage` while the selection `guardParams` names
+    /// is current, as `resetChannel` does. Once it resets, `clearNextLaunch`
+    /// runs under the lock.
+    func resetChannelIfSelectionCurrent(
+        _ guardParams: ReleaseSelectionGuardParams,
+        in storage: BundleStorageService,
+        clearNextLaunch: () -> Void
+    ) -> Result<Bool, Error> {
+        withLock {
+            let result = storage.resetChannelIfSelectionCurrent(
+                catalogId: guardParams.catalogId,
+                scopeKey: guardParams.scopeKey,
+                generation: guardParams.generation,
+                catalogHash: guardParams.catalogHash,
+                channel: guardParams.channel,
+                selectionContextHash: guardParams.selectionContextHash
+            )
+            if case .success(true) = result {
+                clearNextLaunch()
+            }
+            return result
+        }
+    }
+
     /// Commits `selection` in `storage`. Committing anything but a bundle, such
     /// as the built-in bundle, deletes every downloaded bundle, so it runs
     /// under the lock as a channel reset does. Once it commits,
@@ -52,3 +76,31 @@ final class LaunchPreparationLock {
         }
     }
 }
+
+/// The Release selection a guarded change names, as JavaScript sends it.
+struct ReleaseSelectionGuardParams {
+    let catalogId: String
+    let scopeKey: String
+    let generation: Int64
+    let catalogHash: String
+    let channel: String
+    let selectionContextHash: String
+
+    init?(_ params: [AnyHashable: Any]?) {
+        guard let data = params as? [String: Any],
+              let catalogId = data["catalogId"] as? String,
+              let scopeKey = data["scopeKey"] as? String,
+              let generation = data["generation"] as? NSNumber,
+              let catalogHash = data["catalogHash"] as? String,
+              let channel = data["channel"] as? String,
+              let selectionContextHash = data["selectionContextHash"] as? String else {
+            return nil
+        }
+        self.catalogId = catalogId
+        self.scopeKey = scopeKey
+        self.generation = generation.int64Value
+        self.catalogHash = catalogHash
+        self.channel = channel
+        self.selectionContextHash = selectionContextHash
+    }
+}

package/ios/HotUpdater/Internal/NativeUpdateCheck.swift

@@ -379,6 +379,9 @@ protocol NativeUpdateHost: NativeUpdateEventStorage {
         progress: @escaping (Double) -> Void
     ) async throws -> Any?
     func resetChannel() async -> Bool
+    /// Resets the channel only while the Release selection `guardParams`
+    /// names is current, in one step with the catalog checks.
+    func resetChannelIfSelectionCurrent(_ guardParams: [String: Any]) async -> Bool
     func releaseCatalogCache(_ partition: String) -> String?
     func setReleaseCatalogCache(_ partition: String, value: String) -> Bool
     func removeReleaseCatalogCache(_ partition: String)
@@ -955,6 +958,22 @@ final class NativeUpdateChecker {
     /// The target the last staging committed, for another retained result of
     /// the same target.
     private var lastCommittedTargetKey: String?
+    /// The last switched-channel leave that reset the device, for another
+    /// retained result of the same catalog. Kept apart from the committed
+    /// target, which a later staging replaces.
+    private var lastLeftTargetKeyValue: String?
+    private var lastLeftTargetKey: String? {
+        get {
+            committedTargetLock.lock()
+            defer { committedTargetLock.unlock() }
+            return lastLeftTargetKeyValue
+        }
+        set {
+            committedTargetLock.lock()
+            lastLeftTargetKeyValue = newValue
+            committedTargetLock.unlock()
+        }
+    }
 
     init(
         host: NativeUpdateHost,
@@ -1173,6 +1192,7 @@ final class NativeUpdateChecker {
                 currentBundleId: currentBundleId,
                 minimumReleaseId: minimumReleaseId,
                 currentChannel: currentChannel,
+                isSwitched: isSwitched,
                 targetChannel: targetChannel,
                 explicitChannel: explicitChannel,
                 cohort: cohort,
@@ -1208,6 +1228,7 @@ final class NativeUpdateChecker {
         currentBundleId: String,
         minimumReleaseId: String,
         currentChannel: String,
+        isSwitched: Bool,
         targetChannel: String,
         explicitChannel: String?,
         cohort: String,
@@ -1286,6 +1307,20 @@ final class NativeUpdateChecker {
         guard host.acceptReleaseCatalog(guardParams) else {
             throw NativeUpdateCheckError.invalidResponse("Rejected a stale or inconsistent Release catalog")
         }
+        // The switched channel holds nothing for this build any more, as a
+        // deleted channel does: the server answers its scope with an accepted
+        // catalog without releases. A scope without a catalog proves nothing,
+        // since a cache can still answer that for a channel deployed seconds ago.
+        if isSwitched, targetChannel == currentChannel,
+           catalog.releases.isEmpty, catalog.rollbackReleases.isEmpty {
+            return leaveSwitchedChannel(
+                options: options,
+                currentBundleId: currentBundleId,
+                minimumReleaseId: minimumReleaseId,
+                channel: currentChannel,
+                guardParams: guardParams
+            )
+        }
         let stableInTargetScope = stable.flatMap { stable in
             stable.catalogId.jsEquals(catalogId) && stable.scopeKey.jsEquals(scopeKey) ? stable : nil
         }
@@ -1499,6 +1534,95 @@ final class NativeUpdateChecker {
         )
     }
 
+    /// Leaves a switched channel that holds nothing for this build, such as a
+    /// deleted one, as checkForUpdate.ts does: a rollback to the built-in
+    /// bundle whose staging also clears the runtime channel, so the next check
+    /// reads the build's default channel. The check itself resets nothing,
+    /// since the reset removes the running bundle's files.
+    private func leaveSwitchedChannel(
+        options: NativeCheckRequest,
+        currentBundleId: String,
+        minimumReleaseId: String,
+        channel: String,
+        guardParams: [String: Any]
+    ) -> HotUpdaterUpdate {
+        let runsBuiltIn = currentBundleId.jsEquals(minimumReleaseId)
+        let errorScope = ErrorScope(
+            channel: channel,
+            bundleId: currentBundleId,
+            updateStrategy: options.updateStrategy,
+            targetBundleId: minimumReleaseId,
+            targetReleaseId: nil
+        )
+        // With the catalog's freshness guard, as ordinary selections, so a
+        // leave from an older catalog never joins a current one's staging.
+        let targetKey = Self.jsonKey([
+            "LEAVE_CHANNEL", channel, minimumReleaseId,
+            guardParams["catalogId"] ?? NSNull(), guardParams["generation"] ?? NSNull(),
+            guardParams["catalogHash"] ?? NSNull(), guardParams["selectionContextHash"] ?? NSNull(),
+        ])
+        let install = { [self] (_: @escaping (Double) -> Void) async throws -> Bool in
+            do {
+                // This leave, from this or another result of the same catalog,
+                // already happened: calling it again changes nothing.
+                if lastLeftTargetKey == targetKey, host.channel() == host.defaultChannel() {
+                    return true
+                }
+                // A device that left or changed the channel meanwhile keeps it.
+                guard host.channel() == channel else {
+                    throw NativeUpdateCheckError.staleReleaseCatalog
+                }
+                // The staging holds the gate, as `resetChannel()` waits for;
+                // native checks the catalog again in the same step as the
+                // reset, so a newer one accepted meanwhile keeps the channel.
+                guard await host.resetChannelIfSelectionCurrent(guardParams) else {
+                    throw NativeUpdateCheckError.staleReleaseCatalog
+                }
+                lastLeftTargetKey = targetKey
+                NativeUpdateEvents.remove(name: "onBundleDownloaded", from: host)
+                return true
+            } catch {
+                reportUpdateError(error, stage: "download", resource: "artifact", scope: errorScope)
+                throw error
+            }
+        }
+        let fromReleaseId = runningReleaseId(bundleId: currentBundleId, channel: channel)
+        queueEvent("onUpdateCheck", [
+            "status": "UPDATE_AVAILABLE",
+            "channel": channel,
+            "fromBundleId": currentBundleId,
+            "fromReleaseId": fromReleaseId ?? NSNull(),
+            "toBundleId": minimumReleaseId,
+            "toReleaseId": NSNull(),
+            "transitionKind": "USE_BUILTIN",
+            "updateStatus": "ROLLBACK",
+            "shouldForceUpdate": !runsBuiltIn,
+            "updateStrategy": options.updateStrategy.name,
+        ])
+        return HotUpdaterUpdate(
+            id: minimumReleaseId,
+            releaseId: nil,
+            status: .rollback,
+            shouldForceUpdate: !runsBuiltIn,
+            message: nil,
+            rolloutCohortCount: 1000,
+            targetCohorts: [],
+            bundleId: minimumReleaseId,
+            transitionKind: "USE_BUILTIN",
+            runsCurrentBundle: runsBuiltIn,
+            targetKey: targetKey,
+            checker: self,
+            install: install,
+            // Current while the device is still switched to the channel and
+            // the catalog is current, and once the staging left it.
+            isSelectionCurrent: { [host] in
+                let current = host.channel()
+                return current == host.defaultChannel()
+                    || (current == channel && host.isReleaseSelectionCurrent(guardParams))
+            }
+        )
+    }
+
     // MARK: State
 
     private static func jsonKey(_ fields: [Any]) -> String {