@hot-updater/react-native 1.0.0-rc.4 → 1.0.0-rc.41

package/ios/HotUpdater/Internal/HotUpdaterImpl.swift

@@ -1,5 +1,6 @@
 import Foundation
 import React
+import UIKit
 
 private func hotUpdaterUncaughtExceptionHandler(_ exception: NSException) {
     HotUpdaterRecoveryManager.shared.handleUncaughtException(exception)
@@ -17,6 +18,18 @@ private func hotUpdaterUpdateSignalLaunchStateSymbol(
 @_silgen_name("HotUpdaterPerformRecoveryReload")
 private func hotUpdaterPerformRecoveryReloadSymbol() -> ObjCBool
 
+@_silgen_name("HotUpdaterMarkFailedRuntime")
+private func hotUpdaterMarkFailedRuntime()
+
+@_silgen_name("HotUpdaterIsFailedRuntime")
+private func hotUpdaterIsFailedRuntime() -> ObjCBool
+
+@_silgen_name("HotUpdaterInstallRecoveryHooks")
+private func hotUpdaterInstallRecoveryHooks()
+
+@_silgen_name("HotUpdaterAfterSurfaceStarts")
+private func hotUpdaterAfterSurfaceStarts(_ action: @convention(block) @escaping () -> Void)
+
 @_silgen_name("HotUpdaterCopyMinBundleId")
 private func hotUpdaterCopyMinBundleIdSymbol() -> UnsafeMutableRawPointer
 
@@ -44,11 +57,28 @@ private func hotUpdaterGetMinBundleId() -> String {
     private let cohortService: CohortService
     private let recoveryManager: HotUpdaterRecoveryManager
     private let releaseCatalogCache: ReleaseCatalogCacheService
+    private let keyValueStorage: KeyValueStorageService
     private var currentLaunchSelection: LaunchSelection?
+    private var launchStartObservers: [NSObjectProtocol] = []
 
     private static let DEFAULT_CHANNEL = "production"
     private static let CHANNEL_STORAGE_KEY = "HotUpdaterChannel"
 
+    private static func parseSafeByteSize(_ value: Any?) -> Int64? {
+        guard let number = value as? NSNumber,
+              String(cString: number.objCType) != "c" else {
+            return nil
+        }
+        let doubleValue = number.doubleValue
+        guard doubleValue.isFinite,
+              doubleValue >= 0,
+              doubleValue <= 9_007_199_254_740_991,
+              doubleValue.rounded(.towardZero) == doubleValue else {
+            return nil
+        }
+        return Int64(doubleValue)
+    }
+
     // MARK: - Initialization
 
     /**
@@ -59,12 +89,9 @@ private func hotUpdaterGetMinBundleId() -> String {
         let isolationKey = HotUpdaterImpl.getIsolationKey()
         let preferences = VersionedPreferencesService()
         let downloadService = URLSessionDownloadService()
-        let decompressService = DecompressService()
-
         let bundleStorage = BundleFileStorageService(
             fileSystem: fileSystem,
             downloadService: downloadService,
-            decompressService: decompressService,
             preferences: preferences,
             isolationKey: isolationKey,
             builtInBundleIdProvider: { HotUpdaterImpl.minBundleId() }
@@ -75,7 +102,10 @@ private func hotUpdaterGetMinBundleId() -> String {
             bundleStorage: bundleStorage,
             preferences: preferences,
             recoveryManager: recoveryManager,
-            releaseCatalogCache: ReleaseCatalogCacheService()
+            releaseCatalogCache: ReleaseCatalogCacheService(),
+            keyValueStorage: KeyValueStorageService(
+                directory: NoBackupStorage.directory(in: fileSystem)
+            )
         )
     }
 
@@ -83,18 +113,23 @@ private func hotUpdaterGetMinBundleId() -> String {
      * Primary initializer with dependency injection.
      * @param bundleStorage Service for bundle storage operations
      * @param preferences Service for preference storage
+     * @param keyValueStorage Persistent key-value store for client plugins
      */
     internal init(
         bundleStorage: BundleStorageService,
         preferences: PreferencesService,
         recoveryManager: HotUpdaterRecoveryManager,
-        releaseCatalogCache: ReleaseCatalogCacheService = ReleaseCatalogCacheService()
+        releaseCatalogCache: ReleaseCatalogCacheService = ReleaseCatalogCacheService(),
+        keyValueStorage: KeyValueStorageService = KeyValueStorageService(
+            directory: NoBackupStorage.directory(in: FileManagerService())
+        )
     ) {
         self.bundleStorage = bundleStorage
         self.preferences = preferences
         self.cohortService = CohortService()
         self.recoveryManager = recoveryManager
         self.releaseCatalogCache = releaseCatalogCache
+        self.keyValueStorage = keyValueStorage
         super.init()
 
         // Configure preferences with isolation key
@@ -219,9 +254,11 @@ private func hotUpdaterGetMinBundleId() -> String {
     /**
      * Updates the bundle from JavaScript bridge.
      * This method acts as the primary error boundary for all bundle operations.
-     * @param params Dictionary with bundleId and fileUrl parameters
-     * @param resolve Promise resolve callback
-     * @param reject Promise reject callback
+     * @param params Dictionary with bundleId, manifest, and asset parameters
+     * @param resolve Promise resolve callback, called with the staged bundle's
+     *   `{ delivery, patchFallback }`
+     * @param reject Promise reject callback; download and install failures
+     *   carry `stage`, `reason`, and their details in the error's userInfo
      */
     public func updateBundle(_ params: NSDictionary?,
                                          resolver resolve: @escaping RCTPromiseResolveBlock,
@@ -236,43 +273,49 @@ private func hotUpdaterGetMinBundleId() -> String {
                 return
             }
 
+            // Invalid update parameters are an invalid update response.
             guard let bundleId = data["bundleId"] as? String, !bundleId.isEmpty else {
-                let error = NSError(domain: "HotUpdater", code: 0,
-                                   userInfo: [NSLocalizedDescriptionKey: "Missing or empty 'bundleId'"])
+                let error = UpdateFailure.invalidResponse.error(description: "Missing or empty 'bundleId'")
                 reject("MISSING_BUNDLE_ID", error.localizedDescription, error)
                 return
             }
 
-            let fileUrlString = data["fileUrl"] as? String ?? ""
-
-            var fileUrl: URL? = nil
-            if !fileUrlString.isEmpty {
-                guard let url = URL(string: fileUrlString) else {
-                    let error = NSError(domain: "HotUpdater", code: 0,
-                                       userInfo: [NSLocalizedDescriptionKey: "Invalid 'fileUrl' provided: \(fileUrlString)"])
-                    reject("INVALID_FILE_URL", error.localizedDescription, error)
-                    return
-                }
-                fileUrl = url
+            guard let manifestFileHash = data["manifestFileHash"] as? String,
+                  !manifestFileHash.isEmpty else {
+                let error = UpdateFailure.invalidResponse.with(resource: .manifest)
+                    .error(description: "Missing manifest file hash")
+                reject("INVALID_MANIFEST", error.localizedDescription, error)
+                return
             }
-
-            // Extract fileHash if provided
-            let fileHash = data["fileHash"] as? String
-            let manifestFileHash = data["manifestFileHash"] as? String
             let channel = data["channel"] as? String
             let manifestUrlString = data["manifestUrl"] as? String ?? ""
-            var manifestUrl: URL? = nil
-            if !manifestUrlString.isEmpty {
-                guard let url = URL(string: manifestUrlString) else {
-                    let error = NSError(domain: "HotUpdater", code: 0,
-                                       userInfo: [NSLocalizedDescriptionKey: "Invalid 'manifestUrl' provided: \(manifestUrlString)"])
+            guard let manifestUrl = URL(string: manifestUrlString) else {
+                let error = UpdateFailure.invalidResponse.with(resource: .manifest).error(
+                    description: "Invalid 'manifestUrl' provided: \(manifestUrlString)"
+                )
+                reject("INVALID_FILE_URL", error.localizedDescription, error)
+                return
+            }
+            let archiveUrl: URL?
+            if let archiveUrlString = data["archiveUrl"] as? String {
+                guard let parsedArchiveUrl = URL(string: archiveUrlString) else {
+                    let error = UpdateFailure.invalidResponse.with(resource: .archive).error(
+                        description: "Invalid 'archiveUrl' provided: \(archiveUrlString)"
+                    )
                     reject("INVALID_FILE_URL", error.localizedDescription, error)
                     return
                 }
-                manifestUrl = url
+                archiveUrl = parsedArchiveUrl
+            } else {
+                archiveUrl = nil
+            }
+            guard let assetsPayload = data["assets"] as? [String: [String: Any]] else {
+                let error = UpdateFailure.invalidResponse.with(resource: .manifest)
+                    .error(description: "Missing manifest assets")
+                reject("INVALID_MANIFEST", error.localizedDescription, error)
+                return
             }
-            let changedAssetsPayload = data["changedAssets"] as? [String: [String: Any]]
-            let changedAssets = changedAssetsPayload?.reduce(into: [String: ChangedAssetDescriptor]()) { partialResult, entry in
+            let assets = assetsPayload.reduce(into: [String: ChangedAssetDescriptor]()) { partialResult, entry in
                 guard let fileHash = entry.value["fileHash"] as? String,
                       !fileHash.isEmpty
                 else {
@@ -296,7 +339,8 @@ private func hotUpdaterGetMinBundleId() -> String {
                         baseBundleId: baseBundleId,
                         baseFileHash: baseFileHash,
                         patchFileHash: patchFileHash,
-                        patchUrl: patchUrl
+                        patchUrl: patchUrl,
+                        byteSize: Self.parseSafeByteSize(payload["byteSize"])
                     )
                 }
                 let filePayload = entry.value["file"] as? [String: Any]
@@ -315,11 +359,8 @@ private func hotUpdaterGetMinBundleId() -> String {
             }
             let selection = (data["selection"] as? [String: Any]).flatMap(Self.parseSelection)
             if let selection, !bundleStorage.stageReleaseSelection(selection) {
-                let error = NSError(
-                    domain: "HotUpdater",
-                    code: 0,
-                    userInfo: [NSLocalizedDescriptionKey: "Release catalog selection is stale"]
-                )
+                // Not an update failure, so the rejection carries no stage or reason.
+                let error = StaleReleaseSelectionError() as NSError
                 reject("UNKNOWN_ERROR", error.localizedDescription, error)
                 return
             }
@@ -327,10 +368,10 @@ private func hotUpdaterGetMinBundleId() -> String {
             // Extract progress callback if provided
             let progressCallback = data["progressCallback"] as? RCTResponseSenderBlock
 
-            NSLog("[HotUpdaterImpl] updateBundle called with bundleId: \(bundleId), fileUrl: \(fileUrl?.absoluteString ?? "nil"), fileHash: \(fileHash ?? "nil")")
+            NSLog("[HotUpdaterImpl] updateBundle called with bundleId: \(bundleId), manifestUrl: \(manifestUrl.absoluteString)")
 
             // Heavy work is delegated to bundle storage service with safe error handling
-            bundleStorage.updateBundle(bundleId: bundleId, fileUrl: fileUrl, fileHash: fileHash, manifestUrl: manifestUrl, manifestFileHash: manifestFileHash, changedAssets: changedAssets, progressHandler: { payload in
+            bundleStorage.updateBundle(bundleId: bundleId, manifestUrl: manifestUrl, manifestFileHash: manifestFileHash, archiveUrl: archiveUrl, assets: assets, progressHandler: { payload in
                 DispatchQueue.main.async {
                     NotificationCenter.default.post(
                         name: .updateProgressDidChange,
@@ -354,7 +395,7 @@ private func hotUpdaterGetMinBundleId() -> String {
                 // Return results on main thread for React Native bridge
                 DispatchQueue.main.async {
                     switch result {
-                    case .success:
+                    case .success(let delivery):
                         NSLog("[HotUpdaterImpl] Update successful for \(bundleId). Resolving promise.")
                         if let channel, !channel.isEmpty {
                             do {
@@ -367,12 +408,14 @@ private func hotUpdaterGetMinBundleId() -> String {
                                 NSLog("[HotUpdaterImpl] Failed to persist channel override: \(error)")
                             }
                         }
-                        resolve(true)
+                        // { delivery: "patch" | "manifest" | "archive", patchFallback }
+                        resolve(delivery.dictionary)
                     case .failure(let error):
                         NSLog("[HotUpdaterImpl] Update failed for \(bundleId) - Error: \(error)")
 
                         let normalizedCode = HotUpdaterImpl.normalizeErrorCode(from: error)
-                        let nsError = error as NSError
+                        // A classified failure adds stage, reason, and its details to userInfo.
+                        let nsError = UpdateFailureError.rejectionError(for: error)
                         reject(normalizedCode, nsError.localizedDescription, nsError)
                     }
                 }
@@ -507,6 +550,8 @@ private func hotUpdaterGetMinBundleId() -> String {
      * Rare or platform-specific codes are collapsed to UNKNOWN_ERROR to reduce surface area.
      */
     private static func normalizeErrorCode(from error: Error) -> String {
+        // Classification wraps an error without changing its code.
+        let error = UpdateFailureError.unwrap(error)
         let baseCode: String
 
         if let storageError = error as? BundleStorageError {
@@ -532,7 +577,6 @@ private func hotUpdaterGetMinBundleId() -> String {
         "DIRECTORY_CREATION_FAILED",
         "DOWNLOAD_FAILED",
         "INCOMPLETE_DOWNLOAD",
-        "EXTRACTION_FORMAT_ERROR",
         "INVALID_BUNDLE",
         "INSUFFICIENT_DISK_SPACE",
         "SIGNATURE_VERIFICATION_FAILED",
@@ -545,6 +589,11 @@ private func hotUpdaterGetMinBundleId() -> String {
     // MARK: - Rollback Support
 
     public func notifyAppReady() -> [String: Any] {
+        // A failed runtime can finish queued native calls while recovery starts.
+        // Keep its readiness loop from consuming the new launch's report.
+        if hotUpdaterIsFailedRuntime().boolValue {
+            return ["status": "PENDING"]
+        }
         return bundleStorage.notifyAppReady()
     }
 
@@ -568,16 +617,21 @@ private func hotUpdaterGetMinBundleId() -> String {
         return bundleStorage.getInstallId()
     }
 
-    public func getUserId() -> String? {
-        return bundleStorage.getUserId()
-    }
+    // MARK: - Client Plugin Storage
 
-    public func getUsername() -> String? {
-        return bundleStorage.getUsername()
+    /**
+     * Reads a value from the persistent key-value store for client plugins.
+     * @return The stored value or nil when the key has none
+     */
+    public func getStorageItem(_ key: String) -> String? {
+        return keyValueStorage.getItem(key)
     }
 
-    public func setUser(_ userId: String?, username: String?) {
-        bundleStorage.setUser(userId: userId, username: username)
+    /**
+     * Writes a value to the persistent key-value store; nil removes the key.
+     */
+    public func setStorageItem(_ key: String, value: String?) {
+        keyValueStorage.setItem(key, value: value)
     }
 
     /**
@@ -597,7 +651,7 @@ private func hotUpdaterGetMinBundleId() -> String {
 
     /**
      * Gets the current active bundle ID from bundle storage.
-     * Reads manifest.json first and falls back to the legacy BUNDLE_ID file.
+     * Reads the required OTA manifest.json.
      * Built-in bundle fallback is handled in JS.
      */
     public func getBundleId() -> String? {
@@ -651,12 +705,49 @@ private func hotUpdaterGetMinBundleId() -> String {
 
         let pendingRecovery = recoveryManager.consumePendingCrashRecovery()
         let selection = bundleStorage.prepareLaunch(bundle: bundle, pendingRecovery: pendingRecovery)
+        markLaunchStartedInForeground(selection)
         recoveryManager.startMonitoring(bundleId: selection.launchedBundleId, shouldRollback: selection.shouldRollbackOnCrash) { [weak self] launchedBundleId in
             self?.bundleStorage.markLaunchCompleted(bundleId: launchedBundleId)
         }
         currentLaunchSelection = selection
         return selection
     }
+
+    // A background launch, such as a silent push, may never render. Only a
+    // launch in the foreground may leave an unfinished launch for the next
+    // process to roll back.
+    private func markLaunchStartedInForeground(_ selection: LaunchSelection) {
+        let bundleId = selection.shouldRollbackOnCrash ? selection.launchedBundleId : nil
+        let mark = { [weak self] in
+            guard let self else { return }
+            self.removeLaunchStartObservers()
+            guard let bundleId else { return }
+            guard UIApplication.shared.applicationState == .background else {
+                self.bundleStorage.markLaunchStarted(bundleId: bundleId)
+                return
+            }
+            self.launchStartObservers = [
+                UIApplication.willEnterForegroundNotification,
+                UIApplication.didBecomeActiveNotification,
+            ].map { name in
+                NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in
+                    self?.removeLaunchStartObservers()
+                    self?.bundleStorage.markLaunchStarted(bundleId: bundleId)
+                }
+            }
+        }
+        // UIApplication is read on the main thread.
+        if Thread.isMainThread {
+            mark()
+        } else {
+            DispatchQueue.main.async(execute: mark)
+        }
+    }
+
+    private func removeLaunchStartObservers() {
+        launchStartObservers.forEach { NotificationCenter.default.removeObserver($0) }
+        launchStartObservers = []
+    }
 }
 
 @objcMembers
@@ -672,6 +763,7 @@ final class HotUpdaterRecoveryManager: NSObject {
     private var handlersInstalled = false
     private var isMonitoring = false
     private var recoveryRequested = false
+    private var monitoringGeneration = 0
     private var currentBundleId: String?
     private var shouldRollbackOnCrash = false
     private var contentAppearedCallback: ((String?) -> Void)?
@@ -709,6 +801,10 @@ final class HotUpdaterRecoveryManager: NSObject {
         shouldRollback: Bool,
         onContentAppeared: @escaping (String?) -> Void
     ) {
+        objc_sync_enter(self)
+        defer { objc_sync_exit(self) }
+
+        monitoringGeneration += 1
         currentBundleId = bundleId
         shouldRollbackOnCrash = shouldRollback
         recoveryRequested = false
@@ -719,6 +815,7 @@ final class HotUpdaterRecoveryManager: NSObject {
         stopMonitoringWorkItem = nil
 
         installHandlersIfNeeded()
+        hotUpdaterInstallRecoveryHooks()
         registerObservers()
         installSignalHandlersIfNeeded()
         hotUpdaterUpdateSignalLaunchState(bundleId, shouldRollback: shouldRollback)
@@ -726,9 +823,8 @@ final class HotUpdaterRecoveryManager: NSObject {
 
     func handleUncaughtException(_ exception: NSException) {
         writeCrashMarker()
-        if requestRecoveryReloadIfNeeded() {
-            return
-        }
+        // An uncaught native exception cannot safely continue in this process.
+        // Preserve the marker so the next launch can select the safe bundle.
         previousUncaughtExceptionHandler?(exception)
     }
 
@@ -742,16 +838,22 @@ final class HotUpdaterRecoveryManager: NSObject {
         previousUncaughtExceptionHandler = NSGetUncaughtExceptionHandler()
 
         RCTSetFatalHandler { [weak self] error in
-            self?.writeCrashMarker()
-            if self?.requestRecoveryReloadIfNeeded() != true {
-                self?.previousFatalHandler?(error)
+            guard !hotUpdaterIsFailedRuntime().boolValue else { return }
+            if self?.requestRecoveryReloadIfNeeded(onFailure: {
+                self?.forwardFatalError(error)
+            }) != true {
+                self?.writeCrashMarker()
+                self?.forwardFatalError(error)
             }
         }
 
         RCTSetFatalExceptionHandler { [weak self] exception in
-            self?.writeCrashMarker()
-            if self?.requestRecoveryReloadIfNeeded() != true {
-                self?.previousFatalExceptionHandler?(exception)
+            guard !hotUpdaterIsFailedRuntime().boolValue else { return }
+            if self?.requestRecoveryReloadIfNeeded(onFailure: {
+                self?.forwardFatalException(exception)
+            }) != true {
+                self?.writeCrashMarker()
+                self?.forwardFatalException(exception)
             }
         }
 
@@ -759,6 +861,33 @@ final class HotUpdaterRecoveryManager: NSObject {
         handlersInstalled = true
     }
 
+    private func forwardFatalError(_ error: Error?) {
+        if let previousFatalHandler {
+            previousFatalHandler(error)
+        } else {
+            let handler = RCTGetFatalHandler()
+            RCTSetFatalHandler(nil)
+            RCTFatal(error)
+            // React Native's DEBUG default handler can return.
+            if RCTGetFatalHandler() == nil {
+                RCTSetFatalHandler(handler)
+            }
+        }
+    }
+
+    private func forwardFatalException(_ exception: NSException?) {
+        if let previousFatalExceptionHandler {
+            previousFatalExceptionHandler(exception)
+        } else {
+            let handler = RCTGetFatalExceptionHandler()
+            RCTSetFatalExceptionHandler(nil)
+            RCTFatalException(exception)
+            if RCTGetFatalExceptionHandler() == nil {
+                RCTSetFatalExceptionHandler(handler)
+            }
+        }
+    }
+
     private func installSignalHandlersIfNeeded() {
         guard !signalHandlersInstalled else {
             return
@@ -777,7 +906,7 @@ final class HotUpdaterRecoveryManager: NSObject {
         unregisterObservers()
         NotificationCenter.default.addObserver(
             self,
-            selector: #selector(handleJavaScriptDidFailToLoad),
+            selector: #selector(handleJavaScriptDidFailToLoad(_:)),
             name: NSNotification.Name.RCTJavaScriptDidFailToLoad,
             object: nil
         )
@@ -802,15 +931,25 @@ final class HotUpdaterRecoveryManager: NSObject {
         )
     }
 
-    @objc private func handleJavaScriptDidFailToLoad() {
-        if requestRecoveryReloadIfNeeded() {
+    @objc private func handleJavaScriptDidFailToLoad(_ notification: Notification) {
+        let error = notification.userInfo?["error"] as? NSError ?? NSError(
+            domain: "HotUpdaterRecovery",
+            code: 1,
+            userInfo: [NSLocalizedDescriptionKey: "JavaScript bundle failed to load"]
+        )
+        if requestRecoveryReloadIfNeeded(onFailure: { [weak self] in
+            self?.forwardFatalError(error)
+        }) {
             return
         }
         unregisterObservers()
     }
 
     @objc private func handleContentDidAppear() {
-        guard isMonitoring else {
+        objc_sync_enter(self)
+        defer { objc_sync_exit(self) }
+
+        guard isMonitoring, !recoveryRequested else {
             return
         }
 
@@ -820,14 +959,19 @@ final class HotUpdaterRecoveryManager: NSObject {
         hotUpdaterUpdateSignalLaunchState(currentBundleId, shouldRollback: false)
 
         stopMonitoringWorkItem?.cancel()
+        let generation = monitoringGeneration
         let workItem = DispatchWorkItem { [weak self] in
-            self?.finishMonitoring()
+            self?.finishMonitoring(generation: generation)
         }
         stopMonitoringWorkItem = workItem
         DispatchQueue.main.asyncAfter(deadline: .now() + .seconds(10), execute: workItem)
     }
 
-    private func finishMonitoring() {
+    private func finishMonitoring(generation: Int) {
+        objc_sync_enter(self)
+        defer { objc_sync_exit(self) }
+        guard monitoringGeneration == generation else { return }
+
         isMonitoring = false
         recoveryRequested = false
         stopMonitoringWorkItem = nil
@@ -837,31 +981,40 @@ final class HotUpdaterRecoveryManager: NSObject {
         hotUpdaterUpdateSignalLaunchState(nil, shouldRollback: false)
     }
 
-    private func requestRecoveryReloadIfNeeded() -> Bool {
+    private func requestRecoveryReloadIfNeeded(onFailure: @escaping () -> Void) -> Bool {
+        objc_sync_enter(self)
+        defer { objc_sync_exit(self) }
+
         guard isMonitoring, shouldRollbackOnCrash else {
             return false
         }
 
-        objc_sync_enter(self)
+        hotUpdaterMarkFailedRuntime()
         if recoveryRequested {
-            objc_sync_exit(self)
             return true
         }
         recoveryRequested = true
-        objc_sync_exit(self)
+        writeCrashMarker()
 
         let bundleId = currentBundleId
-        DispatchQueue.main.async { [weak self] in
+        let generation = monitoringGeneration
+        hotUpdaterAfterSurfaceStarts { [weak self] in
             guard let self else {
                 return
             }
 
+            objc_sync_enter(self)
+            let isCurrentLaunch = self.monitoringGeneration == generation
+            objc_sync_exit(self)
+            guard isCurrentLaunch else { return }
+
             let started = hotUpdaterPerformRecoveryReload()
             if !started {
                 objc_sync_enter(self)
                 self.recoveryRequested = false
                 objc_sync_exit(self)
                 NSLog("[HotUpdaterRecovery] Failed to trigger recovery reload")
+                onFailure()
             } else {
                 NSLog("[HotUpdaterRecovery] Triggered recovery reload for bundleId=\(bundleId ?? "nil")")
             }
@@ -871,6 +1024,9 @@ final class HotUpdaterRecoveryManager: NSObject {
     }
 
     private func writeCrashMarker() {
+        objc_sync_enter(self)
+        defer { objc_sync_exit(self) }
+
         guard isMonitoring else {
             return
         }

package/ios/HotUpdater/Internal/KeyValueStorageService.swift

@@ -0,0 +1,71 @@
+import Foundation
+
+/// Persistent string key-value store for client plugins, kept in
+/// `Application Support/HotUpdater/storage.json` outside device backups.
+///
+/// Keys are opaque; JavaScript namespaces them per plugin. The file is read
+/// into memory on first use, and every write replaces the whole file.
+final class KeyValueStorageService {
+    static let storageFilename = "storage.json"
+
+    private let fileURL: URL
+    private let lock = NSLock()
+    private var items: [String: String]?
+
+    init(directory: URL) {
+        self.fileURL = directory.appendingPathComponent(Self.storageFilename)
+    }
+
+    func getItem(_ key: String) -> String? {
+        lock.lock()
+        defer { lock.unlock() }
+        return loadedItems()[key]
+    }
+
+    /// Stores `value` under `key`, or removes the key when `value` is nil.
+    /// Returns false when the file could not be written.
+    @discardableResult
+    func setItem(_ key: String, value: String?) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+
+        var updatedItems = loadedItems()
+        updatedItems[key] = value
+        // Memory stays the source of truth for this process, so the next
+        // successful write also persists a value whose own write failed.
+        items = updatedItems
+
+        do {
+            let data = try JSONSerialization.data(
+                withJSONObject: updatedItems,
+                options: [.sortedKeys]
+            )
+            try NoBackupStorage.write(data, to: fileURL)
+            return true
+        } catch {
+            NSLog("[KeyValueStorage] Failed to write \(fileURL.path): \(error)")
+            return false
+        }
+    }
+
+    private func loadedItems() -> [String: String] {
+        if let items {
+            return items
+        }
+        let loadedItems = Self.readItems(from: fileURL)
+        items = loadedItems
+        return loadedItems
+    }
+
+    /// A missing, unreadable, or corrupt file reads as an empty store.
+    private static func readItems(from file: URL) -> [String: String] {
+        guard let data = try? Data(contentsOf: file) else {
+            return [:]
+        }
+        guard let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            NSLog("[KeyValueStorage] Ignoring unreadable store at \(file.path)")
+            return [:]
+        }
+        return object.compactMapValues { $0 as? String }
+    }
+}

package/ios/HotUpdater/Internal/NotificationExtension.swift

@@ -1,7 +1,5 @@
 import Foundation
 
 extension Notification.Name {
-    static let downloadProgressUpdate = Notification.Name("HotUpdaterDownloadProgressUpdate")
-    static let downloadDidFinish = Notification.Name("HotUpdaterDownloadDidFinish")
     static let updateProgressDidChange = Notification.Name("HotUpdaterUpdateProgressDidChange")
 }