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

package/ios/HotUpdater/Internal/BundleFileStorageService.swift

@@ -52,27 +52,28 @@ public struct BsdiffPatchDescriptor {
     public let baseFileHash: String
     public let patchFileHash: String
     public let patchUrl: URL
+    public let byteSize: Int64?
 
     public init(
         algorithm: String,
         baseBundleId: String,
         baseFileHash: String,
         patchFileHash: String,
-        patchUrl: URL
+        patchUrl: URL,
+        byteSize: Int64? = nil
     ) {
         self.algorithm = algorithm
         self.baseBundleId = baseBundleId
         self.baseFileHash = baseFileHash
         self.patchFileHash = patchFileHash
         self.patchUrl = patchUrl
+        self.byteSize = byteSize
     }
 }
 
 public struct UpdateProgressPayload {
     public let progress: Double
     public let artifactType: String
-    public let downloadedBytes: Int64?
-    public let totalBytes: Int64?
     public let details: DiffProgressDetails?
 
     public struct DiffProgressFileSnapshot {
@@ -147,30 +148,47 @@ public struct UpdateProgressPayload {
     public init(
         progress: Double,
         artifactType: String,
-        downloadedBytes: Int64? = nil,
-        totalBytes: Int64? = nil,
         details: DiffProgressDetails? = nil
     ) {
         self.progress = progress
         self.artifactType = artifactType
-        self.downloadedBytes = downloadedBytes
-        self.totalBytes = totalBytes
         self.details = details
     }
 
     public var userInfo: [String: Any] {
-        var info: [String: Any] = [
+        [
             "artifactType": artifactType,
             "progress": progress,
             "details": details?.userInfo ?? NSNull()
         ]
-        if let downloadedBytes {
-            info["downloadedBytes"] = downloadedBytes
-        }
-        if let totalBytes {
-            info["totalBytes"] = totalBytes
-        }
-        return info
+    }
+}
+
+/// How a staged bundle arrived. `updateBundle` resolves with `dictionary`.
+public struct UpdateDelivery: Equatable {
+    public enum Method: String {
+        /// A bsdiff patch produced at least one file.
+        case patch
+        /// Only changed files were downloaded, possibly none.
+        case manifest
+        /// The full tar.br archive was downloaded.
+        case archive
+    }
+
+    public let method: Method
+    /// A file's patch was tried, but the full file was downloaded instead.
+    public let patchFallback: Bool
+
+    public init(method: Method, patchFallback: Bool) {
+        self.method = method
+        self.patchFallback = patchFallback
+    }
+
+    public var dictionary: [String: Any] {
+        [
+            "delivery": method.rawValue,
+            "patchFallback": patchFallback,
+        ]
     }
 }
 
@@ -178,9 +196,7 @@ public enum BundleStorageError: Error, CustomNSError {
     case directoryCreationFailed
     case downloadFailed(Error)
     case incompleteDownload(expected: Int64, actual: Int64)
-    case extractionFormatError(Error)
     case invalidBundle
-    case insufficientDiskSpace
     case signatureVerificationFailed(SignatureVerificationError)
     case moveOperationFailed(Error)
     case bundleInCrashedHistory(String)
@@ -200,9 +216,7 @@ public enum BundleStorageError: Error, CustomNSError {
         case .directoryCreationFailed: return "DIRECTORY_CREATION_FAILED"
         case .downloadFailed: return "DOWNLOAD_FAILED"
         case .incompleteDownload: return "INCOMPLETE_DOWNLOAD"
-        case .extractionFormatError: return "EXTRACTION_FORMAT_ERROR"
         case .invalidBundle: return "INVALID_BUNDLE"
-        case .insufficientDiskSpace: return "INSUFFICIENT_DISK_SPACE"
         case .signatureVerificationFailed: return "SIGNATURE_VERIFICATION_FAILED"
         case .moveOperationFailed: return "MOVE_OPERATION_FAILED"
         case .bundleInCrashedHistory: return "BUNDLE_IN_CRASHED_HISTORY"
@@ -227,19 +241,10 @@ public enum BundleStorageError: Error, CustomNSError {
             userInfo[NSLocalizedDescriptionKey] = "Download incomplete: received \(actual) bytes, expected \(expected) bytes"
             userInfo[NSLocalizedRecoverySuggestionErrorKey] = "The download was interrupted. Check network connection and try again"
 
-        case .extractionFormatError(let underlyingError):
-            userInfo[NSLocalizedDescriptionKey] = "The downloaded bundle file is not a valid compressed archive"
-            userInfo[NSUnderlyingErrorKey] = underlyingError
-            userInfo[NSLocalizedRecoverySuggestionErrorKey] = "The downloaded file is not a supported bundle archive. Try downloading again"
-
         case .invalidBundle:
             userInfo[NSLocalizedDescriptionKey] = "Bundle missing required platform files (index.ios.bundle or main.jsbundle)"
             userInfo[NSLocalizedRecoverySuggestionErrorKey] = "Verify the bundle was built correctly with metro bundler"
 
-        case .insufficientDiskSpace:
-            userInfo[NSLocalizedDescriptionKey] = "Insufficient disk space to download and extract bundle"
-            userInfo[NSLocalizedRecoverySuggestionErrorKey] = "Free up device storage and try again"
-
         case .signatureVerificationFailed(let underlyingError):
             userInfo[NSLocalizedDescriptionKey] = "Bundle signature verification failed"
             userInfo[NSUnderlyingErrorKey] = underlyingError
@@ -280,7 +285,7 @@ public protocol BundleStorageService {
     func prepareLaunch(bundle: Bundle, pendingRecovery: PendingCrashRecovery?) -> LaunchSelection
 
     // Bundle update
-    func updateBundle(bundleId: String, fileUrl: URL?, fileHash: String?, manifestUrl: URL?, manifestFileHash: String?, changedAssets: [String: ChangedAssetDescriptor]?, progressHandler: @escaping (UpdateProgressPayload) -> Void, completion: @escaping (Result<Bool, Error>) -> Void)
+    func updateBundle(bundleId: String, manifestUrl: URL, manifestFileHash: String, archiveUrl: URL?, assets: [String: ChangedAssetDescriptor], progressHandler: @escaping (UpdateProgressPayload) -> Void, completion: @escaping (Result<UpdateDelivery, Error>) -> Void)
     func stageReleaseSelection(_ selection: PersistedSelection) -> Bool
     func acceptReleaseCatalog(catalogId: String, scopeKey: String, generation: Int64, catalogHash: String, channel: String, selectionContextHash: String) -> Bool
     func getActiveUpdateState() -> [String: Any]
@@ -288,15 +293,13 @@ public protocol BundleStorageService {
     func commitReleaseSelection(_ selection: PersistedSelection) -> Bool
 
     // Rollback support
+    func markLaunchStarted(bundleId: String?)
     func markLaunchCompleted(bundleId: String?)
     func notifyAppReady() -> [String: Any]
     func getCrashHistory() -> CrashedHistory
     func clearCrashHistory() -> Bool
     func getInstallId() -> String
-    func getUserId() -> String?
-    func getUsername() -> String?
-    func setUser(userId: String?, username: String?)
-    
+
     /**
      * Gets the base URL for the current active bundle directory
      * @return Base URL string (e.g., "file:///data/.../bundle-store/abc123") or empty string
@@ -306,7 +309,7 @@ public protocol BundleStorageService {
 
     /**
      * Gets the current active bundle ID from bundle storage.
-     * Reads manifest.json first and falls back to older metadata when needed.
+     * Reads the required OTA manifest.json.
      */
     func getBundleId() -> String?
 
@@ -332,6 +335,8 @@ public extension BundleStorageService {
 }
 
 class BundleFileStorageService: BundleStorageService {
+    private static let maximumSafeByteSize: Int64 = 9_007_199_254_740_991
+
     private struct ActiveBundleMetadataSnapshot {
         let activeBundleId: String
         let bundleId: String?
@@ -341,80 +346,59 @@ class BundleFileStorageService: BundleStorageService {
     private struct ParsedBundleManifest {
         let bundleId: String
         let assets: [String: ParsedManifestAsset]
+        let archive: ParsedArchive?
     }
 
     private struct ParsedManifestAsset {
         let fileHash: String
         let signature: String?
+        let byteSize: Int64?
+        let downloadByteSize: Int64?
     }
 
-    private enum UpdateProgress {
-        static let downloadEnd = 0.7
-        static let verificationStart = 0.72
-        static let verificationEnd = 0.82
-        static let extractionStart = 0.82
-        static let extractionEnd = 0.97
-        static let bundleValidation = 0.98
-        static let activationReady = 0.99
-        static let complete = 1.0
+    private struct ParsedArchive {
+        let downloadFileHash: String
+        let downloadByteSize: Int64
+        let tarByteSize: Int64
     }
 
     private let fileSystem: FileSystemService
     private let downloadService: DownloadService
-    private let decompressService: DecompressService
+    /// The wait before a download's second attempt; it doubles for each later one.
+    private let downloadRetryDelay: TimeInterval
     private let preferences: PreferencesService
     private let isolationKey: String
 
-    private let id = Int.random(in: 1..<100)
-    
     // Queue for potentially long-running sequences within updateBundle or for explicit background tasks.
     private let fileOperationQueue: DispatchQueue
 
-    private var activeTasks: [URLSessionTask] = []
-
+    private var hasPreparedLaunch = false
     private var currentLaunchReport: LaunchReport?
+    // The staged bundle this process launched before its first content. Only that
+    // launch is pending; a bundle staged later waits for the next launch.
+    private var pendingLaunchBundleId: String?
+    // Crash history is written at first content on the main thread while JavaScript can read it.
+    private let crashedHistoryLock = NSLock()
+    // A bundle waiting for its retry that this process keeps refusing, see InterruptedLaunch.
+    private var retryHeldBundleId: String?
     private let activeBundleMetadataLock = NSLock()
     private var activeBundleMetadataSnapshot: ActiveBundleMetadataSnapshot?
     private let builtInBundleIdProvider: () -> String
+    private let builtInAssetResolver: BuiltInAssetResolver
     private let updateStrategyProvider: () -> UpdateStrategy
     private let releaseStateLock = NSRecursiveLock()
     private var pendingInstallSelections: [String: PersistedSelection] = [:]
 
+    private let installIdentityLock = NSLock()
     private var currentInstallIdentity: InstallIdentity?
-    private var currentUserIdentity: UserIdentity?
 
     private let protectedBundleStoreEntries: Set<String> = [
         BundleMetadata.metadataFilename,
         CrashedHistory.crashedHistoryFilename,
         LaunchReport.launchReportFilename,
-        InstallIdentity.installIdentityFilename,
-        UserIdentity.userIdentityFilename,
+        "builtin-index-v1.json",
     ]
 
-    private func normalizeIdentityValue(_ value: String?) -> String? {
-        guard let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines),
-              !trimmed.isEmpty else {
-            return nil
-        }
-        return trimmed
-    }
-
-    private func emitArchiveProgress(
-        progressHandler: @escaping (UpdateProgressPayload) -> Void,
-        progress: Double,
-        downloadedBytes: Int64? = nil,
-        totalBytes: Int64? = nil
-    ) {
-        progressHandler(
-            UpdateProgressPayload(
-                progress: max(0, min(progress, 1)),
-                artifactType: "archive",
-                downloadedBytes: downloadedBytes,
-                totalBytes: totalBytes
-            )
-        )
-    }
-
     private func createDiffProgressFiles(
         changedAssets: [String: ChangedAssetDescriptor]
     ) -> [UpdateProgressPayload.DiffProgressFileSnapshot] {
@@ -576,10 +560,7 @@ class BundleFileStorageService: BundleStorageService {
             return
         }
 
-        try StreamingTarArchiveExtractor.decompressBrotliFile(
-            from: downloadedPath,
-            to: destinationPath
-        )
+        try BrotliFileDecompressor.decompress(from: downloadedPath, to: destinationPath)
         try? fileSystem.removeItem(atPath: downloadedPath)
     }
 
@@ -604,7 +585,7 @@ class BundleFileStorageService: BundleStorageService {
 
         let sourcePath: String
         do {
-            sourcePath = try ArchiveExtractionUtilities.extractionURL(
+            sourcePath = try FileUtilities.fileURL(
                 for: assetPath,
                 destinationRoot: currentBundleDir
             ).path
@@ -722,6 +703,14 @@ class BundleFileStorageService: BundleStorageService {
         atPath path: String,
         asset: ParsedManifestAsset
     ) throws {
+        if let expectedByteSize = asset.byteSize {
+            let attributes = try fileSystem.attributesOfItem(atPath: path)
+            guard let size = attributes[.size] as? NSNumber,
+                  size.int64Value == expectedByteSize else {
+                throw BundleStorageError.signatureVerificationFailed(.fileHashMismatch)
+            }
+        }
+
         guard let actualHash = HashUtils.calculateSHA256(fileURL: URL(fileURLWithPath: path)) else {
             throw BundleStorageError.signatureVerificationFailed(.fileReadFailed)
         }
@@ -751,22 +740,28 @@ class BundleFileStorageService: BundleStorageService {
 
     public init(fileSystem: FileSystemService,
                 downloadService: DownloadService,
-                decompressService: DecompressService,
                 preferences: PreferencesService,
                 isolationKey: String,
                 builtInBundleIdProvider: @escaping () -> String = { "" },
+                builtInAssetResolver: BuiltInAssetResolver? = nil,
                 updateStrategyProvider: @escaping () -> UpdateStrategy = {
                     let fingerprintHash = HotUpdaterConfig.shared.fingerprintHash
                         ?? Bundle.main.object(forInfoDictionaryKey: "HOT_UPDATER_FINGERPRINT_HASH") as? String
                     return (fingerprintHash?.isEmpty == false) ? .fingerprint : .appVersion
-                }) {
+                },
+                downloadRetryDelay: TimeInterval = 1) {
 
         self.fileSystem = fileSystem
+        self.downloadRetryDelay = downloadRetryDelay
         self.downloadService = downloadService
-        self.decompressService = decompressService
         self.preferences = preferences
         self.isolationKey = isolationKey
         self.builtInBundleIdProvider = builtInBundleIdProvider
+        self.builtInAssetResolver = builtInAssetResolver ?? IOSBuiltInAssetResolver(
+            cacheURL: URL(fileURLWithPath: fileSystem.documentsPath())
+                .appendingPathComponent("bundle-store", isDirectory: true)
+                .appendingPathComponent("builtin-index-v1.json")
+        )
         self.updateStrategyProvider = updateStrategyProvider
 
         // Create queue for file operations
@@ -779,6 +774,7 @@ class BundleFileStorageService: BundleStorageService {
 
         // Clean up old bundles if isolationKey format changed
         checkAndCleanupIfIsolationKeyChanged()
+        recoverInterruptedPromotions()
     }
 
     // MARK: - Metadata File Paths
@@ -804,18 +800,9 @@ class BundleFileStorageService: BundleStorageService {
         return URL(fileURLWithPath: storeDir).appendingPathComponent(LaunchReport.launchReportFilename)
     }
 
-    private func installIdentityFileURL() -> URL? {
-        guard case .success(let storeDir) = bundleStoreDir() else {
-            return nil
-        }
-        return URL(fileURLWithPath: storeDir).appendingPathComponent(InstallIdentity.installIdentityFilename)
-    }
-
-    private func userIdentityFileURL() -> URL? {
-        guard case .success(let storeDir) = bundleStoreDir() else {
-            return nil
-        }
-        return URL(fileURLWithPath: storeDir).appendingPathComponent(UserIdentity.userIdentityFilename)
+    private func installIdentityFileURL() -> URL {
+        NoBackupStorage.directory(in: fileSystem)
+            .appendingPathComponent(InstallIdentity.installIdentityFilename)
     }
 
     // MARK: - Metadata Operations
@@ -864,54 +851,28 @@ class BundleFileStorageService: BundleStorageService {
         _ = report.save(to: file)
     }
 
-    private func loadInstallIdentity() -> InstallIdentity? {
+    /// Loads the install identity, creating it once when its file is missing.
+    @discardableResult
+    private func loadOrCreateInstallIdentity() -> InstallIdentity {
+        installIdentityLock.lock()
+        defer { installIdentityLock.unlock() }
+
         if let currentInstallIdentity {
             return currentInstallIdentity
         }
-        guard let file = installIdentityFileURL(),
-              let identity = InstallIdentity.load(from: file) else {
-            return nil
+        let file = installIdentityFileURL()
+        if let identity = InstallIdentity.load(from: file) {
+            currentInstallIdentity = identity
+            return identity
         }
-        currentInstallIdentity = identity
-        return identity
-    }
 
-    private func saveInstallIdentity(_ identity: InstallIdentity) -> Bool {
+        let identity = InstallIdentity()
+        // Keep the new id for this process even when it cannot be saved.
         currentInstallIdentity = identity
-        guard let file = installIdentityFileURL() else {
-            return false
-        }
-        return identity.save(to: file)
-    }
-
-    private func loadUserIdentity() -> UserIdentity? {
-        if let currentUserIdentity {
-            return currentUserIdentity
-        }
-        guard let file = userIdentityFileURL(),
-              let identity = UserIdentity.load(from: file) else {
-            return nil
-        }
-        currentUserIdentity = identity
+        _ = identity.save(to: file)
         return identity
     }
 
-    private func saveUserIdentity(_ identity: UserIdentity?) -> Bool {
-        currentUserIdentity = identity
-        guard let file = userIdentityFileURL() else {
-            return false
-        }
-
-        guard let identity else {
-            if FileManager.default.fileExists(atPath: file.path) {
-                try? FileManager.default.removeItem(at: file)
-            }
-            return true
-        }
-
-        return identity.save(to: file)
-    }
-
     private func resolveBuiltInBundleId() -> String? {
         let bundleId = builtInBundleIdProvider().trimmingCharacters(in: .whitespacesAndNewlines)
         return bundleId.isEmpty ? nil : bundleId
@@ -938,11 +899,10 @@ class BundleFileStorageService: BundleStorageService {
     }
 
     private func createInitialMetadata() -> BundleMetadata {
-        let currentBundleId = getCachedBundleId()
         return BundleMetadata(
             isolationKey: isolationKey,
             stableBundleId: nil,
-            stagingBundleId: currentBundleId,
+            stagingBundleId: nil,
             verificationPending: false,
             pendingTransition: nil
         )
@@ -956,18 +916,18 @@ class BundleFileStorageService: BundleStorageService {
     }
 
     private func getActiveBundleId() -> String? {
-        if let cachedBundleId = getCachedBundleId() {
+        guard let metadata = loadMetadataOrNull() else { return nil }
+        if let cachedBundleId = getCachedBundleId(),
+           cachedBundleId == metadata.stagingBundleId || cachedBundleId == metadata.stableBundleId {
             return cachedBundleId
         }
 
-        let metadata = loadMetadataOrNull()
-
-        if let stagingBundleId = metadata?.stagingBundleId,
-           metadata?.verificationPending == false {
+        if let stagingBundleId = metadata.stagingBundleId,
+           metadata.verificationPending == false {
             return stagingBundleId
         }
 
-        if let stableBundleId = metadata?.stableBundleId {
+        if let stableBundleId = metadata.stableBundleId {
             return stableBundleId
         }
 
@@ -1017,22 +977,6 @@ class BundleFileStorageService: BundleStorageService {
         }
     }
 
-    func canUseManifestDrivenInstall() -> Bool {
-        guard let currentBundleId = getCachedBundleId(),
-              case .success(let storeDir) = bundleStoreDir() else {
-            return false
-        }
-
-        let currentBundleDir = (storeDir as NSString).appendingPathComponent(currentBundleId)
-        guard fileSystem.fileExists(atPath: currentBundleDir),
-              let snapshot = getActiveBundleMetadataSnapshot(),
-              let currentManifest = parseBundleManifest(from: snapshot.manifest) else {
-            return false
-        }
-
-        return currentManifest.assets.isEmpty == false
-    }
-
     private func resolveActiveBundleMetadataSnapshot(
         activeBundleId: String,
         bundleDirectory: String
@@ -1041,9 +985,7 @@ class BundleFileStorageService: BundleStorageService {
         let manifestBundleId =
             (manifest["bundleId"] as? String)?
             .trimmingCharacters(in: .whitespacesAndNewlines)
-        let resolvedBundleId =
-            (manifestBundleId?.isEmpty == false ? manifestBundleId : nil) ??
-            readCompatibilityBundleId(in: bundleDirectory)
+        let resolvedBundleId = manifestBundleId?.isEmpty == false ? manifestBundleId : nil
 
         return ActiveBundleMetadataSnapshot(
             activeBundleId: activeBundleId,
@@ -1070,34 +1012,6 @@ class BundleFileStorageService: BundleStorageService {
         )
     }
 
-    private func readCompatibilityBundleId(in bundleDirectory: String) -> String? {
-        let compatibilityBundleIdPath = (bundleDirectory as NSString)
-            .appendingPathComponent(compatibilityBundleIdFilename())
-        if fileSystem.fileExists(atPath: compatibilityBundleIdPath) {
-            do {
-                let compatibilityBundleId = try String(
-                    contentsOfFile: compatibilityBundleIdPath,
-                    encoding: .utf8
-                )
-                    .trimmingCharacters(in: .whitespacesAndNewlines)
-
-                if !compatibilityBundleId.isEmpty {
-                    return compatibilityBundleId
-                }
-            } catch {
-                NSLog(
-                    "[BundleStorage] Failed to read compatibility bundle metadata at \(compatibilityBundleIdPath): \(error.localizedDescription)"
-                )
-            }
-        }
-
-        return nil
-    }
-
-    private func compatibilityBundleIdFilename() -> String {
-        "BUNDLE_ID"
-    }
-
     private func readManifest(in bundleDirectory: String) -> [String: Any]? {
         let manifestPath = (bundleDirectory as NSString).appendingPathComponent("manifest.json")
         guard fileSystem.fileExists(atPath: manifestPath) else {
@@ -1124,7 +1038,7 @@ class BundleFileStorageService: BundleStorageService {
 
         var assets: [String: ParsedManifestAsset] = [:]
         for (assetPath, assetValue) in rawAssets {
-            guard ArchiveExtractionUtilities.normalizedRelativePath(from: assetPath) == assetPath else {
+            guard FileUtilities.normalizedRelativePath(from: assetPath) == assetPath else {
                 return nil
             }
             guard let asset = assetValue as? [String: Any],
@@ -1137,42 +1051,136 @@ class BundleFileStorageService: BundleStorageService {
                 .trimmingCharacters(in: .whitespacesAndNewlines)
             assets[assetPath] = ParsedManifestAsset(
                 fileHash: fileHash,
-                signature: signature?.isEmpty == false ? signature : nil
+                signature: signature?.isEmpty == false ? signature : nil,
+                byteSize: Self.parseSafeByteSize(asset["byteSize"]),
+                downloadByteSize: Self.parseSafeByteSize(asset["downloadByteSize"])
+            )
+        }
+
+        let archive: ParsedArchive?
+        if let payload = manifest["archive"] as? [String: Any],
+           let downloadFileHash = payload["downloadFileHash"] as? String,
+           Self.isPlainSHA256(downloadFileHash),
+           let downloadByteSize = Self.parseSafeByteSize(payload["downloadByteSize"]),
+           downloadByteSize > 0,
+           let tarByteSize = Self.parseSafeByteSize(payload["tarByteSize"]),
+           tarByteSize >= 1024 {
+            archive = ParsedArchive(
+                downloadFileHash: downloadFileHash,
+                downloadByteSize: downloadByteSize,
+                tarByteSize: tarByteSize
             )
+        } else {
+            archive = nil
         }
 
-        return ParsedBundleManifest(bundleId: manifestBundleId, assets: assets)
+        return ParsedBundleManifest(
+            bundleId: manifestBundleId,
+            assets: assets,
+            archive: archive
+        )
     }
 
-    private func parseBundleManifest(fromFile manifestPath: String) -> ParsedBundleManifest? {
-        guard let manifest = readManifest(in: (manifestPath as NSString).deletingLastPathComponent) else {
+    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 <= Double(maximumSafeByteSize),
+              doubleValue.rounded(.towardZero) == doubleValue else {
             return nil
         }
+        return Int64(doubleValue)
+    }
 
-        return parseBundleManifest(from: manifest)
+    private static func isPlainSHA256(_ value: String) -> Bool {
+        value.count == 64 && value.allSatisfy {
+            ("0"..."9").contains($0) || ("a"..."f").contains($0)
+        }
     }
 
-    private func writeManifestFile(_ manifest: ParsedBundleManifest, to destination: String) throws {
+    private func copyVerifiedManifest(from source: String, to destination: String) throws {
         let manifestDirectory = (destination as NSString).deletingLastPathComponent
         guard fileSystem.createDirectory(atPath: manifestDirectory) else {
             throw BundleStorageError.directoryCreationFailed
         }
+        if fileSystem.fileExists(atPath: destination) {
+            try fileSystem.removeItem(atPath: destination)
+        }
+        do {
+            try fileSystem.copyItem(atPath: source, toPath: destination)
+        } catch {
+            throw BundleStorageError.moveOperationFailed(error)
+        }
+    }
+
+    private func shouldUseArchive(
+        archive: ParsedArchive?,
+        archiveUrl: URL?,
+        downloads: [String: ChangedAssetDescriptor],
+        assets: [String: ParsedManifestAsset]
+    ) -> Bool {
+        guard downloads.count >= 2,
+              archive != nil,
+              archiveUrl != nil,
+              assets.values.allSatisfy({ $0.byteSize != nil }) else {
+            return false
+        }
 
-        let assets = manifest.assets
-            .sorted { $0.key < $1.key }
-            .reduce(into: [String: [String: String]]()) { partialResult, entry in
-                var assetPayload = ["fileHash": entry.value.fileHash]
-                if let signature = entry.value.signature, !signature.isEmpty {
-                    assetPayload["signature"] = signature
+        var individualLowerBound: Int64 = 0
+        var hasOfferedPatch = false
+        for (path, descriptor) in downloads {
+            guard let originalByteSize = assets[path]?.downloadByteSize else {
+                return false
+            }
+            let plannedByteSize: Int64
+            if let patch = descriptor.patch {
+                hasOfferedPatch = true
+                guard let patchByteSize = patch.byteSize,
+                      patchByteSize >= 0,
+                      patchByteSize <= Self.maximumSafeByteSize else {
+                    return false
                 }
-                partialResult[entry.key] = assetPayload
+                plannedByteSize = min(originalByteSize, patchByteSize)
+            } else {
+                plannedByteSize = originalByteSize
             }
-        let payload: [String: Any] = [
-            "bundleId": manifest.bundleId,
-            "assets": assets,
-        ]
-        let data = try JSONSerialization.data(withJSONObject: payload, options: [.prettyPrinted])
-        try data.write(to: URL(fileURLWithPath: destination))
+            let (sum, overflowed) = individualLowerBound.addingReportingOverflow(plannedByteSize)
+            guard !overflowed,
+                  sum <= Self.maximumSafeByteSize else { return false }
+            individualLowerBound = sum
+        }
+
+        guard let archive else { return false }
+        var logicalByteSize: Int64 = 0
+        for asset in assets.values {
+            guard let byteSize = asset.byteSize else { return false }
+            let (sum, overflowed) = logicalByteSize.addingReportingOverflow(byteSize)
+            guard !overflowed,
+                  sum <= Self.maximumSafeByteSize else { return false }
+            logicalByteSize = sum
+        }
+        let (tarOverhead, overheadUnderflowed) = archive.tarByteSize
+            .subtractingReportingOverflow(logicalByteSize)
+        guard !overheadUnderflowed,
+              tarOverhead >= 0 else { return false }
+
+        if archive.downloadByteSize <= individualLowerBound {
+            return true
+        }
+
+        guard downloads.count == assets.count,
+              !hasOfferedPatch else {
+            return false
+        }
+        let (archiveBound, boundOverflowed) = individualLowerBound
+            .addingReportingOverflow(tarOverhead)
+        guard !boundOverflowed,
+              archiveBound <= Self.maximumSafeByteSize else { return false }
+        return archive.downloadByteSize <= archiveBound
     }
 
     /**
@@ -1308,8 +1316,10 @@ class BundleFileStorageService: BundleStorageService {
         )
     }
 
+    /// Rolls back the pending staging bundle. `unfinishedLaunch` means its launch
+    /// ended before first content without a crash marker.
     @discardableResult
-    private func rollbackPendingBundle(_ stagingId: String) -> Bool {
+    private func rollbackPendingBundle(_ stagingId: String, unfinishedLaunch: Bool = false) -> Bool {
         guard var metadata = loadMetadataOrNull(), metadata.stagingBundleId == stagingId else {
             return false
         }
@@ -1318,9 +1328,7 @@ class BundleFileStorageService: BundleStorageService {
         let pendingSelectionTransition = metadata.pendingSelectionTransition
         let stableSelection = metadata.stableSelection
 
-        var crashedHistory = loadCrashedHistory()
-        crashedHistory.addEntry(stagingId)
-        let _ = saveCrashedHistory(crashedHistory)
+        recordFailedLaunch(stagingId, unfinishedLaunch: unfinishedLaunch)
 
         let fallbackBundleId = metadata.stableBundleId.flatMap { candidate in
             if case .success(let storeDir) = bundleStoreDir() {
@@ -1539,6 +1547,7 @@ class BundleFileStorageService: BundleStorageService {
             metadata.stagingBundleId = nil
             metadata.stagingSelection = selection
             metadata.verificationPending = false
+            metadata.launchInProgress = false
             metadata.pendingTransition = nil
             metadata.pendingSelectionTransition = nil
         }
@@ -1619,7 +1628,42 @@ class BundleFileStorageService: BundleStorageService {
         DispatchQueue.global(qos: .background).async(execute: workItem)
     }
 
+    /**
+     * Downloads `url`, trying again after a retryable failure (see
+     * `DownloadError.isRetryable`) up to `DownloadError.maximumAttempts`
+     * attempts in all, 1 and then 2 seconds apart, unless `retrying` is
+     * false. The last attempt's result is returned, so a failure keeps what
+     * classifies it. Blocks the calling thread.
+     */
     private func downloadFileSynchronously(
+        from url: URL,
+        to destination: String,
+        retrying: Bool = true,
+        progressHandler: @escaping (DownloadProgress) -> Void
+    ) -> Result<URL, Error> {
+        var attempt = 1
+        while true {
+            let result = downloadFileOnce(
+                from: url,
+                to: destination,
+                progressHandler: progressHandler
+            )
+            guard case .failure(let error) = result,
+                  retrying,
+                  attempt < DownloadError.maximumAttempts,
+                  DownloadError.isRetryable(error) else {
+                return result
+            }
+            let delay = downloadRetryDelay * pow(2, Double(attempt - 1))
+            NSLog("[BundleStorage] Download failed (attempt \(attempt)/\(DownloadError.maximumAttempts)): \(error.localizedDescription). Retrying in \(delay)s")
+            if delay > 0 {
+                Thread.sleep(forTimeInterval: delay)
+            }
+            attempt += 1
+        }
+    }
+
+    private func downloadFileOnce(
         from url: URL,
         to destination: String,
         progressHandler: @escaping (DownloadProgress) -> Void
@@ -1666,7 +1710,7 @@ class BundleFileStorageService: BundleStorageService {
             do {
                 var bundlePaths: [String] = []
                 for assetPath in parsedManifest.assets.keys {
-                    let assetURL = try ArchiveExtractionUtilities.extractionURL(
+                    let assetURL = try FileUtilities.fileURL(
                         for: assetPath,
                         destinationRoot: directoryPath
                     )
@@ -1688,38 +1732,7 @@ class BundleFileStorageService: BundleStorageService {
             }
         }
 
-        let iosBundlePath = (directoryPath as NSString).appendingPathComponent("index.ios.bundle")
-        if self.fileSystem.fileExists(atPath: iosBundlePath) {
-            NSLog("[BundleStorage] Found iOS bundle atPath: \(iosBundlePath)")
-            return .success(iosBundlePath)
-        }
-
-        let mainBundlePath = (directoryPath as NSString).appendingPathComponent("main.jsbundle")
-        if self.fileSystem.fileExists(atPath: mainBundlePath) {
-            NSLog("[BundleStorage] Found main bundle atPath: \(mainBundlePath)")
-            return .success(mainBundlePath)
-        }
-
-        do {
-            let contents = try self.fileSystem.contentsOfDirectory(atPath: directoryPath)
-            NSLog("[BundleStorage] Directory contents: \(contents)")
-
-            // Additional search: check all .bundle files
-            for file in contents {
-                if file.hasSuffix(".bundle") {
-                    let bundlePath = (directoryPath as NSString).appendingPathComponent(file)
-                    NSLog("[BundleStorage] Found alternative bundle atPath: \(bundlePath)")
-                    return .success(bundlePath)
-                }
-            }
-            
-            NSLog("[BundleStorage] No bundle file found in directory: \(directoryPath)")
-            NSLog("[BundleStorage] Available files: \(contents)")
-            return .success(nil)
-        } catch let error {
-            NSLog("[BundleStorage] Error reading directory contents: \(error.localizedDescription)")
-            return .failure(error)
-        }
+        return .success(nil)
     }
         
     /**
@@ -1752,7 +1765,7 @@ class BundleFileStorageService: BundleStorageService {
         let bundles = contents.compactMap { item -> String? in
             let fullPath = (storeDir as NSString).appendingPathComponent(item)
 
-            if protectedBundleStoreEntries.contains(item) {
+            if protectedBundleStoreEntries.contains(item) || item.hasSuffix(".install-backup") {
                 return nil
             }
 
@@ -1864,11 +1877,11 @@ class BundleFileStorageService: BundleStorageService {
         }
 
         let relativePath = String(bundleURL.path.dropFirst(sourcePrefix.count))
-        guard ArchiveExtractionUtilities.normalizedRelativePath(from: relativePath) == relativePath else {
+        guard FileUtilities.normalizedRelativePath(from: relativePath) == relativePath else {
             throw BundleStorageError.invalidBundle
         }
 
-        return try ArchiveExtractionUtilities.extractionURL(
+        return try FileUtilities.fileURL(
             for: relativePath,
             destinationRoot: destinationDirectory
         ).path
@@ -1924,8 +1937,8 @@ class BundleFileStorageService: BundleStorageService {
     private func selectLaunch(bundle: Bundle) -> LaunchSelection {
         guard let metadata = loadMetadataOrNull() else {
             return LaunchSelection(
-                bundleURL: getCachedBundleURL() ?? getFallbackBundleURL(bundle: bundle),
-                launchedBundleId: getCachedBundleId(),
+                bundleURL: getFallbackBundleURL(bundle: bundle),
+                launchedBundleId: nil,
                 shouldRollbackOnCrash: false
             )
         }
@@ -1972,13 +1985,24 @@ class BundleFileStorageService: BundleStorageService {
     }
 
     func prepareLaunch(bundle: Bundle, pendingRecovery: PendingCrashRecovery?) -> LaunchSelection {
+        builtInAssetResolver.use(bundle: bundle)
         saveLaunchReport(nil)
-        if loadInstallIdentity() == nil {
-            let identity = InstallIdentity()
-            _ = saveInstallIdentity(identity)
-        }
+        loadOrCreateInstallIdentity()
         applyPendingRecoveryIfNeeded(pendingRecovery)
-        return selectLaunch(bundle: bundle)
+        // Only a new storage instance consumes an unfinished launch. Repeated bundle
+        // lookups or bridge reloads in this process must not reject its own launch.
+        if !hasPreparedLaunch,
+           let metadata = loadMetadataOrNull(),
+           metadata.verificationPending,
+           metadata.launchInProgress,
+           let stagingBundleId = metadata.stagingBundleId {
+            rollbackPendingBundle(stagingBundleId, unfinishedLaunch: true)
+        }
+        hasPreparedLaunch = true
+        // A launch is recorded only once it can show UI (markLaunchStarted).
+        let selection = selectLaunch(bundle: bundle)
+        pendingLaunchBundleId = selection.shouldRollbackOnCrash ? selection.launchedBundleId : nil
+        return selection
     }
     
     // MARK: - Bundle Update
@@ -1986,943 +2010,805 @@ class BundleFileStorageService: BundleStorageService {
     /**
      * Updates the bundle from the specified URL. This operation is asynchronous.
      * @param bundleId ID of the bundle to update
-     * @param fileUrl URL of the bundle file to download (or nil to reset)
-     * @param fileHash Combined hash string for verification (sig:<signature> or <hex_hash>)
+     * @param manifestUrl URL of the complete target manifest
+     * @param manifestFileHash Hash or signature of the target manifest
      * @param progressHandler Callback for download and extraction progress (0.0 to 1.0)
      * @param completion Callback with result of the operation
      */
-    func updateBundle(bundleId: String, fileUrl: URL?, fileHash: String?, manifestUrl: URL?, manifestFileHash: String?, changedAssets: [String: ChangedAssetDescriptor]?, progressHandler: @escaping (UpdateProgressPayload) -> Void, completion: @escaping (Result<Bool, Error>) -> Void) {
+    func updateBundle(bundleId: String, manifestUrl: URL, manifestFileHash: String, archiveUrl: URL? = nil, assets: [String: ChangedAssetDescriptor], progressHandler: @escaping (UpdateProgressPayload) -> Void, completion: @escaping (Result<UpdateDelivery, Error>) -> Void) {
         // Check if bundle is in crashed history
-        let crashedHistory = loadCrashedHistory()
-        if crashedHistory.contains(bundleId) {
+        if getCrashHistory().contains(bundleId) {
             NSLog("[BundleStorage] Bundle '\(bundleId)' is in crashed history, rejecting update")
             completion(.failure(BundleStorageError.bundleInCrashedHistory(bundleId)))
             return
         }
 
-        // Get the current bundle ID from the cached bundle URL (exclude fallback bundles)
-        let currentBundleId = self.getCachedBundleId()
-
-        guard let validFileUrl = fileUrl else {
-            NSLog("[BundleStorage] fileUrl is nil, resetting bundle URL.")
-            // Dispatch the sequence to the file operation queue to ensure completion is called asynchronously
-            // and to keep file operations off the calling thread if it's the main thread.
-            fileOperationQueue.async {
-                let setResult = self.setBundleURL(localPath: nil)
-                switch setResult {
-                case .success:
-                    let previousMetadata = self.loadMetadataOrNull()
-                    var resetMetadata = self.createInitialMetadata()
-                    resetMetadata.highestSeenCatalogs = previousMetadata?.highestSeenCatalogs ?? [:]
-                    resetMetadata.currentSelectionContexts = previousMetadata?.currentSelectionContexts ?? [:]
-                    let _ = self.saveMetadata(resetMetadata)
-                    self.saveLaunchReport(nil)
-                    let cleanupResult = self.cleanupOldBundles(currentBundleId: currentBundleId, bundleId: bundleId)
-                    switch cleanupResult {
-                    case .success:
-                        completion(.success(true))
-                    case .failure(let error):
-                        NSLog("[BundleStorage] Error during cleanup after reset: \(error)")
-                        completion(.failure(error))
-                    }
-                case .failure(let error):
-                    NSLog("[BundleStorage] Error resetting bundle URL: \(error)")
-                    completion(.failure(error))
-                }
-            }
-            return
-        }
-        
-        // Start the bundle update process on a background queue
-        fileOperationQueue.async {
-
+        fileOperationQueue.async(flags: .barrier) {
             let storeDirResult = self.bundleStoreDir()
             guard case .success(let storeDir) = storeDirResult else {
-                completion(.failure(storeDirResult.failureError ?? BundleStorageError.unknown(nil)))
+                completion(.failure(UpdateFailureError.classifying(
+                    storeDirResult.failureError ?? BundleStorageError.unknown(nil),
+                    during: .storage
+                )))
                 return
             }
-            
-            let finalBundleDir = (storeDir as NSString).appendingPathComponent(bundleId)
-            
-            if self.fileSystem.fileExists(atPath: finalBundleDir) {
-                let findResult = self.findBundleFile(
-                    in: finalBundleDir,
-                    expectedBundleId: bundleId
-                )
-                switch findResult {
-                case .success(let existingBundlePath):
-                    if let bundlePath = existingBundlePath {
-                        NSLog("[BundleStorage] Using cached bundle at path: \(bundlePath)")
-                        let currentMetadata = self.loadMetadataOrNull() ?? self.createInitialMetadata()
-                        guard let updatedMetadata = self.prepareMetadataForNewStagingBundle(currentMetadata, bundleId: bundleId) else {
-                            completion(.failure(BundleStorageError.unknown(
-                                NSError(domain: "HotUpdater", code: 0, userInfo: [
-                                    NSLocalizedDescriptionKey: "Release catalog selection is stale"
-                                ])
-                            )))
-                            return
-                        }
-                        let setResult = self.setBundleURL(localPath: bundlePath)
-                        switch setResult {
-                        case .success:
-                            let _ = self.saveMetadata(updatedMetadata)
-                            NSLog("[BundleStorage] Set staging bundle (cached): \(bundleId), verificationPending: true")
-
-                            self.emitArchiveProgress(
-                                progressHandler: progressHandler,
-                                progress: UpdateProgress.complete
-                            )
-                            self.scheduleCleanupOldBundles(
-                                bundleIdsToKeep: [currentBundleId, updatedMetadata.stableBundleId, bundleId].compactMap { $0 }
-                            )
-                            completion(.success(true))
-                        case .failure(let error):
-                            completion(.failure(error))
-                        }
-                        return
-                    } else {
-                        NSLog("[BundleStorage] Cached directory exists but invalid, removing: \(finalBundleDir)")
-                        do {
-                            try self.fileSystem.removeItem(atPath: finalBundleDir)
-                            // Continue with download process on success
-                            if let manifestUrl,
-                               let manifestFileHash,
-                               let changedAssets,
-                               self.canUseManifestDrivenInstall() {
-                                self.updateBundleFromManifest(
-                                    bundleId: bundleId,
-                                    fileUrl: validFileUrl,
-                                    fileHash: fileHash,
-                                    manifestUrl: manifestUrl,
-                                    manifestFileHash: manifestFileHash,
-                                    changedAssets: changedAssets,
-                                    storeDir: storeDir,
-                                    progressHandler: progressHandler,
-                                    completion: completion
-                                )
-                            } else {
-                                if manifestUrl != nil && manifestFileHash != nil && changedAssets != nil {
-                                    NSLog("[BundleStorage] Skipping manifest-driven install for \(bundleId) because no active OTA manifest is available. Using archive.")
-                                }
-                                self.prepareAndDownloadBundle(bundleId: bundleId, fileUrl: validFileUrl, fileHash: fileHash, storeDir: storeDir, progressHandler: progressHandler, completion: completion)
-                            }
-                        } catch let error {
-                            NSLog("[BundleStorage] Failed to remove invalid bundle dir: \(error.localizedDescription)")
-                            completion(.failure(BundleStorageError.unknown(error)))
-                        }
-                    }
-                case .failure(let error):
-                    completion(.failure(error))
-                }
-            } else {
-                if let manifestUrl,
-                   let manifestFileHash,
-                   let changedAssets,
-                   self.canUseManifestDrivenInstall() {
-                    self.updateBundleFromManifest(
-                        bundleId: bundleId,
-                        fileUrl: validFileUrl,
-                        fileHash: fileHash,
-                        manifestUrl: manifestUrl,
-                        manifestFileHash: manifestFileHash,
-                        changedAssets: changedAssets,
-                        storeDir: storeDir,
-                        progressHandler: progressHandler,
-                        completion: completion
-                    )
-                } else {
-                    if manifestUrl != nil && manifestFileHash != nil && changedAssets != nil {
-                        NSLog("[BundleStorage] Skipping manifest-driven install for \(bundleId) because no active OTA manifest is available. Using archive.")
-                    }
-                    self.prepareAndDownloadBundle(bundleId: bundleId, fileUrl: validFileUrl, fileHash: fileHash, storeDir: storeDir, progressHandler: progressHandler, completion: completion)
-                }
-            }
+            self.updateBundleFromManifest(
+                bundleId: bundleId,
+                manifestUrl: manifestUrl,
+                manifestFileHash: manifestFileHash,
+                archiveUrl: archiveUrl,
+                changedAssets: assets,
+                storeDir: storeDir,
+                progressHandler: progressHandler,
+                completion: completion
+            )
         }
     }
-    
-    /**
-     * Prepares directories and starts the download process.
-     * This method is part of the asynchronous `updateBundle` flow.
-     * @param bundleId ID of the bundle to update
-     * @param fileUrl URL of the bundle file to download
-     * @param fileHash Combined hash string for verification (sig:<signature> or <hex_hash>)
-     * @param storeDir Path to the bundle-store directory
-     * @param progressHandler Callback for download and extraction progress
-     * @param completion Callback with result of the operation
-     */
-    private func updateBundleFromManifest(
-        bundleId: String,
-        fileUrl: URL,
-        fileHash: String?,
-        manifestUrl: URL,
-        manifestFileHash: String,
-        changedAssets: [String: ChangedAssetDescriptor],
-        storeDir: String,
-        progressHandler: @escaping (UpdateProgressPayload) -> Void,
-        completion: @escaping (Result<Bool, Error>) -> Void
-    ) {
-        let tempDirResult = tempDir()
-        guard case .success(let tempDirectory) = tempDirResult else {
-            completion(.failure(tempDirResult.failureError ?? BundleStorageError.unknown(nil)))
-            return
-        }
 
-        try? self.fileSystem.removeItem(atPath: tempDirectory)
-        guard self.fileSystem.createDirectory(atPath: tempDirectory) else {
-            completion(.failure(BundleStorageError.directoryCreationFailed))
-            return
-        }
+    /// How the per-file install produced one file.
+    private enum AssetInstallOutcome {
+        case patched
+        /// `patchFallback` is true when a patch for the running bundle was
+        /// offered but the original file was downloaded instead.
+        case downloaded(patchFallback: Bool)
+    }
 
-        let currentBundleId = self.getCachedBundleId()
-        let currentBundleDir = currentBundleId.map {
-            (storeDir as NSString).appendingPathComponent($0)
+    private func downloadManifestAsset(
+        assetPath: String,
+        expectedAsset: ParsedManifestAsset,
+        changedAsset: ChangedAssetDescriptor,
+        currentBundleId: String?,
+        currentBundleDir: String?,
+        destinationPath: String,
+        tempDirectory: String,
+        progressFile: UpdateProgressPayload.DiffProgressFileSnapshot,
+        progressHandler: @escaping (UpdateProgressPayload) -> Void
+    ) throws -> AssetInstallOutcome {
+        let expectedHash = expectedAsset.fileHash
+        var diffFiles = [progressFile]
+        let patched = applyPatchAssetIfPossible(
+            assetPath: assetPath,
+            changedAsset: changedAsset,
+            currentBundleId: currentBundleId,
+            currentBundleDir: currentBundleDir,
+            destinationPath: destinationPath,
+            expectedHash: expectedHash,
+            tempDirectory: tempDirectory,
+            files: &diffFiles,
+            progressHandler: progressHandler
+        )
+        if patched {
+            // The patch produced these bytes, so a mismatch is a patch failure.
+            try UpdateFailureError.during(.patch, resource: .patch) {
+                try verifyManifestAssetFile(atPath: destinationPath, asset: expectedAsset)
+            }
+            updateDiffProgressFile(
+                files: &diffFiles,
+                assetPath: assetPath,
+                status: "downloaded",
+                progress: 1
+            )
+            self.emitDiffProgress(
+                progressHandler: progressHandler,
+                phase: diffFiles.allSatisfy { $0.status == "downloaded" }
+                    ? "finalizing"
+                    : "downloading",
+                files: diffFiles
+            )
+            return .patched
         }
-        let tempManifestPath = (tempDirectory as NSString).appendingPathComponent("manifest.json")
-        let tmpDir = (storeDir as NSString).appendingPathComponent("\(bundleId).tmp")
-        let realDir = (storeDir as NSString).appendingPathComponent(bundleId)
-        var diffFiles = createDiffProgressFiles(changedAssets: changedAssets)
 
-        do {
+        guard let changedAssetFileUrl = changedAsset.fileUrl else {
+            updateDiffProgressFile(
+                files: &diffFiles,
+                assetPath: assetPath,
+                status: "failed",
+                progress: 0
+            )
             self.emitDiffProgress(
                 progressHandler: progressHandler,
-                phase: "manifest",
-                files: diffFiles,
-                manifestProgress: 0
+                phase: "downloading",
+                files: diffFiles
             )
-            switch self.downloadFileSynchronously(
-                from: manifestUrl,
-                to: tempManifestPath,
-                progressHandler: { progress in
-                    self.emitDiffProgress(
-                        progressHandler: progressHandler,
-                        phase: "manifest",
-                        files: diffFiles,
-                        manifestProgress: progress.progress
-                    )
-                }
-            ) {
-            case .success:
-                break
-            case .failure(let error):
-                if let downloadError = error as? DownloadError,
-                   case .incompleteDownload(let expected, let actual) = downloadError {
-                    throw BundleStorageError.incompleteDownload(expected: expected, actual: actual)
-                }
-                throw BundleStorageError.downloadFailed(error)
-            }
-
-            let manifestVerificationResult = SignatureVerifier.verifyBundle(
-                fileURL: URL(fileURLWithPath: tempManifestPath),
-                fileHash: manifestFileHash
+            // With no original file to fall back to, the patch decides the install.
+            throw UpdateFailureError(
+                underlying: BundleStorageError.downloadFailed(
+                    NSError(domain: "HotUpdater", code: 0, userInfo: [
+                        NSLocalizedDescriptionKey: "Changed asset fileUrl missing and patch could not be applied: \(assetPath)"
+                    ])
+                ),
+                failure: UpdateFailure.patch.with(resource: .patch)
             )
-            guard case .success = manifestVerificationResult else {
-                if case .failure(let error) = manifestVerificationResult {
-                    throw BundleStorageError.signatureVerificationFailed(error)
-                }
-                throw BundleStorageError.unknown(nil)
-            }
+        }
 
-            guard let manifestData = try? Data(contentsOf: URL(fileURLWithPath: tempManifestPath)),
-                  let manifestJson = try JSONSerialization.jsonObject(with: manifestData) as? [String: Any],
-                  let targetManifest = parseBundleManifest(from: manifestJson),
-                  targetManifest.bundleId == bundleId
-            else {
-                throw BundleStorageError.invalidBundle
-            }
-            self.emitDiffProgress(
-                progressHandler: progressHandler,
-                phase: diffFiles.isEmpty ? "finalizing" : "downloading",
-                files: diffFiles
+        let changedAssetDownloadPath = downloadPath(
+            assetPath: assetPath,
+            changedAsset: changedAsset
+        )
+        let downloadDestinationPath: String
+        if changedAsset.fileCompression == "br" {
+            downloadDestinationPath = compressedTempPath(
+                tempDirectory: tempDirectory,
+                assetPath: assetPath,
+                compression: "br"
             )
+        } else {
+            downloadDestinationPath = destinationPath
+        }
 
-            let currentManifest = getActiveBundleMetadataSnapshot().flatMap { snapshot in
-                parseBundleManifest(from: snapshot.manifest)
-            }
-
-            if self.fileSystem.fileExists(atPath: tmpDir) {
-                try self.fileSystem.removeItem(atPath: tmpDir)
-            }
-            guard self.fileSystem.createDirectory(atPath: tmpDir) else {
-                throw BundleStorageError.directoryCreationFailed
-            }
-
-            let sortedAssets = targetManifest.assets.sorted { $0.key < $1.key }
-
-            for asset in sortedAssets {
-                let assetPath = asset.key
-                let expectedAsset = asset.value
-                let expectedHash = expectedAsset.fileHash
-                let destinationPath = try ArchiveExtractionUtilities.extractionURL(
-                    for: assetPath,
-                    destinationRoot: tmpDir
-                ).path
-                let destinationDir = (destinationPath as NSString).deletingLastPathComponent
-                guard self.fileSystem.createDirectory(atPath: destinationDir) else {
-                    throw BundleStorageError.directoryCreationFailed
-                }
-
-                if currentManifest?.assets[assetPath]?.fileHash == expectedHash {
-                    guard let currentBundleDir,
-                          self.fileSystem.fileExists(atPath: currentBundleDir)
-                    else {
-                        throw BundleStorageError.downloadFailed(
-                            NSError(domain: "HotUpdater", code: 0, userInfo: [
-                                NSLocalizedDescriptionKey: "Current bundle directory unavailable for reused asset: \(assetPath)"
-                            ])
-                        )
-                    }
-
-                    let sourcePath = try ArchiveExtractionUtilities.extractionURL(
-                        for: assetPath,
-                        destinationRoot: currentBundleDir
-                    ).path
-                    guard self.fileSystem.fileExists(atPath: sourcePath),
-                          HashUtils.verifyHash(fileURL: URL(fileURLWithPath: sourcePath), expectedHash: expectedHash)
-                    else {
-                        throw BundleStorageError.signatureVerificationFailed(.fileHashMismatch)
-                    }
-
-                    try self.fileSystem.copyItem(atPath: sourcePath, toPath: destinationPath)
-                    try verifyManifestAssetFile(atPath: destinationPath, asset: expectedAsset)
-                    continue
-                }
-
-                guard let changedAsset = changedAssets[assetPath] else {
-                    updateDiffProgressFile(
-                        files: &diffFiles,
-                        assetPath: assetPath,
-                        status: "failed",
-                        progress: 0
-                    )
-                    self.emitDiffProgress(
-                        progressHandler: progressHandler,
-                        phase: "downloading",
-                        files: diffFiles
-                    )
-                    throw BundleStorageError.downloadFailed(
-                        NSError(domain: "HotUpdater", code: 0, userInfo: [
-                            NSLocalizedDescriptionKey: "Changed asset missing from update response: \(assetPath)"
-                        ])
-                    )
-                }
-
-                guard changedAsset.fileHash.caseInsensitiveCompare(expectedHash) == .orderedSame else {
-                    updateDiffProgressFile(
-                        files: &diffFiles,
-                        assetPath: assetPath,
-                        status: "failed",
-                        progress: 0
-                    )
-                    self.emitDiffProgress(
-                        progressHandler: progressHandler,
-                        phase: "downloading",
-                        files: diffFiles
-                    )
-                    throw BundleStorageError.signatureVerificationFailed(.fileHashMismatch)
-                }
-
-                let patched = applyPatchAssetIfPossible(
-                    assetPath: assetPath,
-                    changedAsset: changedAsset,
-                    currentBundleId: currentBundleId,
-                    currentBundleDir: currentBundleDir,
-                    destinationPath: destinationPath,
-                    expectedHash: expectedHash,
-                    tempDirectory: tempDirectory,
+        switch self.downloadFileSynchronously(
+            from: changedAssetFileUrl,
+            to: downloadDestinationPath,
+            progressHandler: { progress in
+                self.updateDiffProgressFile(
                     files: &diffFiles,
-                    progressHandler: progressHandler
+                    assetPath: assetPath,
+                    status: "downloading",
+                    progress: progress.progress,
+                    downloadPath: changedAssetDownloadPath,
+                    downloadedBytes: progress.downloadedBytes,
+                    totalBytes: progress.totalBytes
                 )
-                if patched {
-                    try verifyManifestAssetFile(atPath: destinationPath, asset: expectedAsset)
-                    updateDiffProgressFile(
-                        files: &diffFiles,
-                        assetPath: assetPath,
-                        status: "downloaded",
-                        progress: 1
-                    )
-                    self.emitDiffProgress(
-                        progressHandler: progressHandler,
-                        phase: diffFiles.allSatisfy { $0.status == "downloaded" }
-                            ? "finalizing"
-                            : "downloading",
-                        files: diffFiles
+                self.emitDiffProgress(
+                    progressHandler: progressHandler,
+                    phase: "downloading",
+                    files: diffFiles
+                )
+            }
+        ) {
+        case .success(let downloadedFileURL):
+            do {
+                try UpdateFailureError.during(.extraction, resource: .file) {
+                    try materializeDownloadedAsset(
+                        downloadedPath: downloadedFileURL.path,
+                        destinationPath: destinationPath,
+                        changedAsset: changedAsset
                     )
-                    continue
                 }
-
-                guard let changedAssetFileUrl = changedAsset.fileUrl else {
-                    updateDiffProgressFile(
-                        files: &diffFiles,
-                        assetPath: assetPath,
-                        status: "failed",
-                        progress: 0
-                    )
-                    self.emitDiffProgress(
-                        progressHandler: progressHandler,
-                        phase: "downloading",
-                        files: diffFiles
-                    )
-                    throw BundleStorageError.downloadFailed(
-                        NSError(domain: "HotUpdater", code: 0, userInfo: [
-                            NSLocalizedDescriptionKey: "Changed asset fileUrl missing and patch could not be applied: \(assetPath)"
-                        ])
+                // Compressed files are checked after decoding, so their
+                // mismatch is an extraction failure.
+                let verificationPhase: UpdatePhase =
+                    changedAsset.fileCompression == "br" ? .extraction : .verification
+                try UpdateFailureError.during(verificationPhase, resource: .file) {
+                    try verifyManifestAssetFile(
+                        atPath: destinationPath,
+                        asset: expectedAsset
                     )
                 }
-
-                let changedAssetDownloadPath = downloadPath(
+            } catch {
+                updateDiffProgressFile(
+                    files: &diffFiles,
                     assetPath: assetPath,
-                    changedAsset: changedAsset
+                    status: "failed",
+                    progress: 1
                 )
-                let downloadDestinationPath: String
-                if changedAsset.fileCompression == "br" {
-                    downloadDestinationPath = compressedTempPath(
-                        tempDirectory: tempDirectory,
-                        assetPath: assetPath,
-                        compression: "br"
-                    )
-                } else {
-                    downloadDestinationPath = destinationPath
-                }
-
-                switch self.downloadFileSynchronously(
-                    from: changedAssetFileUrl,
-                    to: downloadDestinationPath,
-                    progressHandler: { progress in
-                        self.updateDiffProgressFile(
-                            files: &diffFiles,
-                            assetPath: assetPath,
-                            status: "downloading",
-                            progress: progress.progress,
-                            downloadPath: changedAssetDownloadPath,
-                            downloadedBytes: progress.downloadedBytes,
-                            totalBytes: progress.totalBytes
-                        )
-                        self.emitDiffProgress(
-                            progressHandler: progressHandler,
-                            phase: "downloading",
-                            files: diffFiles
-                        )
-                    }
-                ) {
-                case .success(let downloadedFileURL):
-                    do {
-                        try materializeDownloadedAsset(
-                            downloadedPath: downloadedFileURL.path,
-                            destinationPath: destinationPath,
-                            changedAsset: changedAsset
-                        )
-                        try verifyManifestAssetFile(
-                            atPath: destinationPath,
-                            asset: expectedAsset
-                        )
-                    } catch {
-                        updateDiffProgressFile(
-                            files: &diffFiles,
-                            assetPath: assetPath,
-                            status: "failed",
-                            progress: 1
-                        )
-                        self.emitDiffProgress(
-                            progressHandler: progressHandler,
-                            phase: "downloading",
-                            files: diffFiles
-                        )
-                        throw error
-                    }
-                    updateDiffProgressFile(
-                        files: &diffFiles,
-                        assetPath: assetPath,
-                        status: "downloaded",
-                        progress: 1
-                    )
-                    self.emitDiffProgress(
-                        progressHandler: progressHandler,
-                        phase: diffFiles.allSatisfy { $0.status == "downloaded" }
-                            ? "finalizing"
-                            : "downloading",
-                        files: diffFiles
-                    )
-                case .failure(let error):
-                    let lastKnownProgress = diffFiles.first(where: { $0.path == assetPath })?.progress ?? 0
-                    updateDiffProgressFile(
-                        files: &diffFiles,
-                        assetPath: assetPath,
-                        status: "failed",
-                        progress: lastKnownProgress
-                    )
-                    self.emitDiffProgress(
-                        progressHandler: progressHandler,
-                        phase: "downloading",
-                        files: diffFiles
-                    )
-                    if let downloadError = error as? DownloadError,
-                       case .incompleteDownload(let expected, let actual) = downloadError {
-                        throw BundleStorageError.incompleteDownload(expected: expected, actual: actual)
-                    }
-                    throw BundleStorageError.downloadFailed(error)
-                }
+                self.emitDiffProgress(
+                    progressHandler: progressHandler,
+                    phase: "downloading",
+                    files: diffFiles
+                )
+                throw error
             }
-
+            updateDiffProgressFile(
+                files: &diffFiles,
+                assetPath: assetPath,
+                status: "downloaded",
+                progress: 1
+            )
             self.emitDiffProgress(
                 progressHandler: progressHandler,
-                phase: "finalizing",
+                phase: diffFiles.allSatisfy { $0.status == "downloaded" }
+                    ? "finalizing"
+                    : "downloading",
                 files: diffFiles
             )
-
-            let manifestDestination = (tmpDir as NSString).appendingPathComponent("manifest.json")
-            try writeManifestFile(targetManifest, to: manifestDestination)
-
-            switch self.findBundleFile(in: tmpDir, expectedBundleId: bundleId) {
-            case .success(let maybeBundlePath):
-                guard let bundlePathInTmp = maybeBundlePath else {
-                    throw BundleStorageError.invalidBundle
-                }
-
-                if self.fileSystem.fileExists(atPath: realDir) {
-                    try self.fileSystem.removeItem(atPath: realDir)
-                }
-
-                do {
-                    try self.fileSystem.moveItem(atPath: tmpDir, toPath: realDir)
-                } catch {
-                    throw BundleStorageError.moveOperationFailed(error)
-                }
-
-                let finalBundlePath = try resolveBundlePathAfterMove(
-                    bundlePathInTmp,
-                    from: tmpDir,
-                    to: realDir
-                )
-                let currentMetadata = self.loadMetadataOrNull() ?? self.createInitialMetadata()
-                guard let updatedMetadata = self.prepareMetadataForNewStagingBundle(currentMetadata, bundleId: bundleId) else {
-                    self.cleanupTemporaryFiles([tempDirectory])
-                    completion(.failure(BundleStorageError.unknown(
-                        NSError(domain: "HotUpdater", code: 0, userInfo: [
-                            NSLocalizedDescriptionKey: "Release catalog selection is stale"
-                        ])
-                    )))
-                    return
-                }
-                switch self.setBundleURL(localPath: finalBundlePath) {
-                case .success:
-                    let _ = self.saveMetadata(updatedMetadata)
-                    self.cleanupTemporaryFiles([tempDirectory])
-                    self.scheduleCleanupOldBundles(
-                        bundleIdsToKeep: [currentBundleId, updatedMetadata.stableBundleId, bundleId].compactMap { $0 }
-                    )
-                    progressHandler(
-                        UpdateProgressPayload(
-                            progress: UpdateProgress.complete,
-                            artifactType: "diff",
-                            details: UpdateProgressPayload.DiffProgressDetails(
-                                totalFilesCount: diffFiles.count,
-                                completedFilesCount: diffFiles.filter { $0.status == "downloaded" }.count,
-                                files: diffFiles
-                            )
-                        )
-                    )
-                    completion(.success(true))
-                case .failure(let error):
-                    try? self.fileSystem.removeItem(atPath: realDir)
-                    self.cleanupTemporaryFiles([tempDirectory])
-                    completion(.failure(error))
-                }
-            case .failure(let error):
-                throw error
-            }
-        } catch {
-            NSLog("[BundleStorage] Manifest-driven install failed: \(error.localizedDescription). Falling back to archive.")
-            try? self.fileSystem.removeItem(atPath: tmpDir)
-            self.cleanupTemporaryFiles([tempDirectory])
-            self.prepareAndDownloadBundle(
-                bundleId: bundleId,
-                fileUrl: fileUrl,
-                fileHash: fileHash,
-                storeDir: storeDir,
+            // 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
+            } ?? false
+            return .downloaded(patchFallback: patchWasTried)
+        case .failure(let error):
+            let lastKnownProgress = diffFiles.first(where: { $0.path == assetPath })?.progress ?? 0
+            updateDiffProgressFile(
+                files: &diffFiles,
+                assetPath: assetPath,
+                status: "failed",
+                progress: lastKnownProgress
+            )
+            self.emitDiffProgress(
                 progressHandler: progressHandler,
-                completion: completion
+                phase: "downloading",
+                files: diffFiles
             )
+            let transferError: Error
+            if let downloadError = error as? DownloadError,
+               case .incompleteDownload(let expected, let actual) = downloadError {
+                transferError = BundleStorageError.incompleteDownload(expected: expected, actual: actual)
+            } else {
+                transferError = BundleStorageError.downloadFailed(error)
+            }
+            throw UpdateFailureError.classifying(transferError, during: .transfer, resource: .file)
         }
     }
 
-    private func prepareAndDownloadBundle(
-        bundleId: String,
-        fileUrl: URL,
-        fileHash: String?,
-        storeDir: String,
-        progressHandler: @escaping (UpdateProgressPayload) -> Void,
-        completion: @escaping (Result<Bool, Error>) -> Void
-    ) {
-        // 1) Prepare temp directory for download
-        let tempDirResult = tempDir()
-        guard case .success(let tempDirectory) = tempDirResult else {
-            completion(.failure(tempDirResult.failureError ?? BundleStorageError.unknown(nil)))
-            return
-        }
-        
-        // 2) Clean up any previous temp dir
-        try? self.fileSystem.removeItem(atPath: tempDirectory)
-        
-        // 3) Create temp dir
-        if !self.fileSystem.createDirectory(atPath: tempDirectory) {
-            completion(.failure(BundleStorageError.directoryCreationFailed))
-            return
+    // Retain only target files on retry; partial files are rehashed before reuse.
+    private func pruneStagingDirectory(_ directory: String, assets: Set<String>, prefix: String = "") throws {
+        for name in try fileSystem.contentsOfDirectory(atPath: directory) {
+            let relativePath = prefix + name
+            let path = (directory as NSString).appendingPathComponent(name)
+            let type = try fileSystem.attributesOfItem(atPath: path)[.type] as? FileAttributeType
+            if type == .typeDirectory, assets.contains(where: { $0.hasPrefix(relativePath + "/") }) {
+                try pruneStagingDirectory(path, assets: assets, prefix: relativePath + "/")
+            } else if type != .typeRegular || !assets.contains(relativePath) {
+                try fileSystem.removeItem(atPath: path)
+            }
         }
+    }
 
-        // 4) Determine bundle filename from URL
-        let bundleFileName = fileUrl.lastPathComponent.isEmpty ? "bundle.zip" : fileUrl.lastPathComponent
-        let tempBundleFile = (tempDirectory as NSString).appendingPathComponent(bundleFileName)
-
-        NSLog("[BundleStorage] Starting download from \(fileUrl)")
-
-        // Download with integrated disk space check
-        var diskSpaceError: BundleStorageError? = nil
-
-        _ = self.downloadService.downloadFile(
-            from: fileUrl,
-            to: tempBundleFile,
-            fileSizeHandler: { fileSize in
-                // This will be called when Content-Length is received
-                NSLog("[BundleStorage] File size received: \(fileSize) bytes")
-
-                // Check available disk space
-                do {
-                    let attributes = try FileManager.default.attributesOfFileSystem(forPath: NSHomeDirectory())
-                    if let freeSize = attributes[.systemFreeSize] as? Int64 {
-                        let requiredSpace = fileSize * 2  // ZIP + extracted files
+    private func installArchive(
+        archive: ParsedArchive,
+        archiveUrl: URL,
+        targetManifest: ParsedBundleManifest,
+        preparedDirectory: String,
+        tempDirectory: String,
+        progressHandler: @escaping (UpdateProgressPayload) -> Void
+    ) throws -> [UpdateProgressPayload.DiffProgressFileSnapshot] {
+        let archiveScratch = (tempDirectory as NSString).appendingPathComponent("archive")
+        try? fileSystem.removeItem(atPath: archiveScratch)
+        guard fileSystem.createDirectory(atPath: archiveScratch) else {
+            throw BundleStorageError.directoryCreationFailed
+        }
+        defer { try? fileSystem.removeItem(atPath: archiveScratch) }
 
-                        NSLog("[BundleStorage] Available: \(freeSize) bytes, Required: \(requiredSpace) bytes")
+        let compressedPath = (archiveScratch as NSString).appendingPathComponent("bundle.tar.br")
+        let tarPath = (archiveScratch as NSString).appendingPathComponent("bundle.tar")
+        let extractedDirectory = (archiveScratch as NSString).appendingPathComponent("extracted")
+        var progressFiles = [UpdateProgressPayload.DiffProgressFileSnapshot(
+            path: "bundle.tar.br",
+            downloadPath: "bundle.tar.br",
+            status: "pending",
+            progress: 0,
+            order: 0
+        )]
+        emitDiffProgress(
+            progressHandler: progressHandler,
+            phase: "downloading",
+            files: progressFiles
+        )
 
-                        if freeSize < requiredSpace {
-                            NSLog("[BundleStorage] Insufficient disk space detected: need \(requiredSpace) bytes, available \(freeSize) bytes")
-                            // Store error to be returned in completion handler
-                            diskSpaceError = .insufficientDiskSpace
-                        }
-                    }
-                } catch {
-                    NSLog("[BundleStorage] Failed to check disk space: \(error.localizedDescription)")
-                }
-            },
-            progressHandler: { downloadProgress in
-                self.emitArchiveProgress(
+        // One attempt: a failed archive falls back to per-file downloads, which retry.
+        switch downloadFileSynchronously(
+            from: archiveUrl,
+            to: compressedPath,
+            retrying: false,
+            progressHandler: { progress in
+                self.updateDiffProgressFile(
+                    files: &progressFiles,
+                    assetPath: "bundle.tar.br",
+                    status: "downloading",
+                    progress: progress.progress,
+                    downloadPath: "bundle.tar.br",
+                    downloadedBytes: progress.downloadedBytes,
+                    totalBytes: progress.totalBytes
+                )
+                self.emitDiffProgress(
                     progressHandler: progressHandler,
-                    progress: Self.mapProgress(
-                        downloadProgress.progress,
-                        start: 0,
-                        end: UpdateProgress.downloadEnd
-                    ),
-                    downloadedBytes: downloadProgress.downloadedBytes,
-                    totalBytes: downloadProgress.totalBytes
+                    phase: "downloading",
+                    files: progressFiles
                 )
-            },
-            completion: { [weak self] result in
-            guard let self = self else {
-                let error = NSError(domain: "HotUpdaterError", code: 998,
-                                    userInfo: [NSLocalizedDescriptionKey: "Self deallocated during download"])
-                completion(.failure(error))
-                return
             }
+        ) {
+        case .success:
+            break
+        case .failure(let error):
+            throw BundleStorageError.downloadFailed(error)
+        }
 
-            // Check for disk space error first before processing download result
-            if let diskError = diskSpaceError {
-                NSLog("[BundleStorage] Throwing disk space error")
-                self.cleanupTemporaryFiles([tempDirectory])
-                completion(.failure(diskError))
-                return
-            }
+        let compressedAttributes = try fileSystem.attributesOfItem(atPath: compressedPath)
+        guard let compressedSize = compressedAttributes[.size] as? NSNumber,
+              compressedSize.int64Value == archive.downloadByteSize,
+              HashUtils.verifyHash(
+                fileURL: URL(fileURLWithPath: compressedPath),
+                expectedHash: archive.downloadFileHash
+              ) else {
+            throw UpdateFailureError(
+                underlying: BundleStorageError.invalidBundle,
+                failure: .hashMismatch
+            )
+        }
 
-            // Dispatch the processing of the downloaded file to the file operation queue
-            let workItem = DispatchWorkItem {
-                switch result {
-                case .success(let location):
-                    self.processDownloadedFileWithTmp(location: location,
-                                                      tempBundleFile: tempBundleFile,
-                                                      fileHash: fileHash,
-                                                      storeDir: storeDir,
-                                                      bundleId: bundleId,
-                                                      tempDirectory: tempDirectory,
-                                                      progressHandler: progressHandler,
-                                                      completion: completion)
-                case .failure(let error):
-                    NSLog("[BundleStorage] Download failed: \(error.localizedDescription)")
-                    self.cleanupTemporaryFiles([tempDirectory]) // Sync cleanup
-
-                    // Map DownloadError.incompleteDownload to BundleStorageError.incompleteDownload
-                    if let downloadError = error as? DownloadError,
-                       case .incompleteDownload(let expected, let actual) = downloadError {
-                        completion(.failure(BundleStorageError.incompleteDownload(expected: expected, actual: actual)))
-                    } else {
-                        completion(.failure(BundleStorageError.downloadFailed(error)))
-                    }
+        try UpdateFailureError.during(.extraction) {
+            try BrotliFileDecompressor.decompress(
+                from: compressedPath,
+                to: tarPath,
+                expectedOutputByteSize: archive.tarByteSize
+            )
+        }
+
+        let expectedFiles = try targetManifest.assets.reduce(
+            into: [String: Int64](),
+            { result, entry in
+                guard let byteSize = entry.value.byteSize else {
+                    throw BundleStorageError.invalidBundle
                 }
+                result[entry.key] = byteSize
+            }
+        )
+        try UpdateFailureError.during(.extraction) {
+            try TarArchiveExtractor.extract(
+                from: tarPath,
+                to: extractedDirectory,
+                expectedFiles: expectedFiles
+            )
+            for (path, asset) in targetManifest.assets {
+                let extractedPath = try FileUtilities.fileURL(
+                    for: path,
+                    destinationRoot: extractedDirectory
+                ).path
+                try verifyManifestAssetFile(atPath: extractedPath, asset: asset)
             }
-            self.fileOperationQueue.async(execute: workItem)
         }
+
+        try promoteVerifiedArchiveDirectory(
+            preparedDirectory,
+            withArchiveDirectory: extractedDirectory
         )
+
+        updateDiffProgressFile(
+            files: &progressFiles,
+            assetPath: "bundle.tar.br",
+            status: "downloaded",
+            progress: 1,
+            downloadedBytes: archive.downloadByteSize,
+            totalBytes: archive.downloadByteSize
+        )
+        emitDiffProgress(
+            progressHandler: progressHandler,
+            phase: "finalizing",
+            files: progressFiles
+        )
+        return progressFiles
     }
-    
-    /**
-     * Logs detailed diagnostic information about a file system path.
-     * @param path The path to diagnose
-     * @param context Additional context for logging
-     */
-    private func logFileSystemDiagnostics(path: String, context: String) {
-        let fileManager = FileManager.default
 
-        // Check if path exists
-        let exists = fileManager.fileExists(atPath: path)
-        NSLog("[BundleStorage] [\(context)] Path exists: \(exists) - \(path)")
+    private func promoteVerifiedArchiveDirectory(
+        _ preparedDirectory: String,
+        withArchiveDirectory archiveDirectory: String
+    ) throws {
+        let backupDirectory = preparedDirectory + ".archive-backup"
+        try? fileSystem.removeItem(atPath: backupDirectory)
+        try fileSystem.moveItem(atPath: preparedDirectory, toPath: backupDirectory)
+
+        do {
+            try fileSystem.moveItem(
+                atPath: archiveDirectory,
+                toPath: preparedDirectory
+            )
+        } catch {
+            try? fileSystem.removeItem(atPath: preparedDirectory)
+            do {
+                try fileSystem.moveItem(atPath: backupDirectory, toPath: preparedDirectory)
+            } catch let restoreError {
+                throw BundleStorageError.moveOperationFailed(restoreError)
+            }
+            throw error
+        }
+        try? fileSystem.removeItem(atPath: backupDirectory)
+    }
 
-        if exists {
+    private func recoverInterruptedPromotions() {
+        guard case .success(let storeDir) = bundleStoreDir(),
+              let entries = try? fileSystem.contentsOfDirectory(atPath: storeDir) else { return }
+        for entry in entries where entry.hasSuffix(".install-backup") {
+            let finalDirectory = (storeDir as NSString).appendingPathComponent(String(entry.dropLast(".install-backup".count)))
             do {
-                let attributes = try fileManager.attributesOfItem(atPath: path)
-                let size = attributes[.size] as? Int64 ?? 0
-                let permissions = attributes[.posixPermissions] as? Int ?? 0
-                NSLog("[BundleStorage] [\(context)] Size: \(size) bytes, Permissions: \(String(permissions, radix: 8))")
+                try recoverInterruptedPromotion(finalDirectory: finalDirectory)
             } catch {
-                NSLog("[BundleStorage] [\(context)] Failed to get attributes: \(error.localizedDescription)")
+                NSLog("[BundleStorage] Cannot recover interrupted promotion: \(error)")
             }
         }
+    }
 
-        // Check parent directory
-        let parentPath = (path as NSString).deletingLastPathComponent
-        let parentExists = fileManager.fileExists(atPath: parentPath)
-        NSLog("[BundleStorage] [\(context)] Parent directory exists: \(parentExists) - \(parentPath)")
+    private func recoverInterruptedPromotion(finalDirectory: String) throws {
+        let backup = finalDirectory + ".install-backup"
+        guard fileSystem.fileExists(atPath: backup) else { return }
+        if fileSystem.fileExists(atPath: finalDirectory) {
+            if isCompleteBundleDirectory(finalDirectory) {
+                try fileSystem.removeItem(atPath: backup)
+                return
+            }
+            try fileSystem.removeItem(atPath: finalDirectory)
+        }
+        try fileSystem.moveItem(atPath: backup, toPath: finalDirectory)
     }
 
-    /**
-     * Processes a downloaded bundle file using the "tmp" rename approach.
-     * This method is part of the asynchronous `updateBundle` flow and is expected to run on a background thread.
-     * @param location URL of the downloaded file
-     * @param tempBundleFile Path to store the downloaded bundle file
-     * @param fileHash Combined hash string for verification (sig:<signature> or <hex_hash>)
-     * @param storeDir Path to the bundle-store directory
-     * @param bundleId ID of the bundle being processed
-     * @param tempDirectory Temporary directory for processing
-     * @param progressHandler Callback for download/apply progress (0.0 to 1.0)
-     * @param completion Callback with result of the operation
-     */
-    private func processDownloadedFileWithTmp(
-        location: URL,
-        tempBundleFile: String,
-        fileHash: String?,
-        storeDir: String,
+    private func isCompleteBundleDirectory(_ directory: String) -> Bool {
+        let bundleId = (directory as NSString).lastPathComponent
+        guard let manifest = readManifest(in: directory),
+              let parsed = parseBundleManifest(from: manifest),
+              parsed.bundleId == bundleId,
+              case .success(let bundlePath) = findBundleFile(in: directory, expectedBundleId: bundleId),
+              bundlePath != nil else { return false }
+        return parsed.assets.allSatisfy { path, asset in
+            guard let file = try? FileUtilities.fileURL(for: path, destinationRoot: directory) else { return false }
+            return (try? verifyManifestAssetFile(atPath: file.path, asset: asset)) != nil
+        }
+    }
+
+    private func promoteStagedBundle(
         bundleId: String,
-        tempDirectory: String,
+        stagingDirectory: String,
+        finalDirectory: String,
+        bundlePathInStaging: String
+    ) throws -> BundleMetadata {
+        releaseStateLock.lock()
+        defer { releaseStateLock.unlock() }
+        let currentMetadata = loadMetadataOrNull() ?? createInitialMetadata()
+        guard let updatedMetadata = prepareMetadataForNewStagingBundle(currentMetadata, bundleId: bundleId) else {
+            throw BundleStorageError.unknown(StaleReleaseSelectionError())
+        }
+        let finalBundlePath = try resolveBundlePathAfterMove(
+            bundlePathInStaging, from: stagingDirectory, to: finalDirectory
+        )
+        let previousPreference = try preferences.getItem(forKey: "HotUpdaterBundleURL")
+        let backup = finalDirectory + ".install-backup"
+        try recoverInterruptedPromotion(finalDirectory: finalDirectory)
+        if fileSystem.fileExists(atPath: finalDirectory) {
+            try fileSystem.moveItem(atPath: finalDirectory, toPath: backup)
+        }
+        var promoted = false
+        do {
+            try fileSystem.moveItem(atPath: stagingDirectory, toPath: finalDirectory)
+            promoted = true
+            try setBundleURL(localPath: finalBundlePath).get()
+            // Metadata is the durable activation point. Launch never uses an
+            // untracked preference if this write fails or the process terminates.
+            guard saveMetadata(updatedMetadata) else {
+                throw UpdateFailureError(
+                    underlying: BundleStorageError.unknown(NSError(domain: "HotUpdater", code: 0,
+                        userInfo: [NSLocalizedDescriptionKey: "Failed to persist bundle activation metadata"])),
+                    failure: .storage
+                )
+            }
+        } catch {
+            let installError = error
+            let preferenceResult = setBundleURL(localPath: previousPreference)
+            if promoted { try fileSystem.removeItem(atPath: finalDirectory) }
+            if fileSystem.fileExists(atPath: backup) {
+                try fileSystem.moveItem(atPath: backup, toPath: finalDirectory)
+            }
+            try preferenceResult.get()
+            throw installError
+        }
+        try? fileSystem.removeItem(atPath: backup)
+        return updatedMetadata
+    }
+
+    private func updateBundleFromManifest(
+        bundleId: String,
+        manifestUrl: URL,
+        manifestFileHash: String,
+        archiveUrl: URL?,
+        changedAssets: [String: ChangedAssetDescriptor],
+        storeDir: String,
         progressHandler: @escaping (UpdateProgressPayload) -> Void,
-        completion: @escaping (Result<Bool, Error>) -> Void
+        completion: @escaping (Result<UpdateDelivery, Error>) -> Void
     ) {
-        let currentBundleId = self.getCachedBundleId()
-        NSLog("[BundleStorage] Processing downloaded file atPath: \(location.path)")
+        let tempDirResult = tempDir()
+        guard case .success(let tempDirectory) = tempDirResult else {
+            completion(.failure(UpdateFailureError.classifying(
+                tempDirResult.failureError ?? BundleStorageError.unknown(nil),
+                during: .storage
+            )))
+            return
+        }
 
-        // 1) Ensure the bundle file exists
-        guard self.fileSystem.fileExists(atPath: location.path) else {
-            logFileSystemDiagnostics(path: location.path, context: "Download Location Missing")
-            self.cleanupTemporaryFiles([tempDirectory])
-            completion(.failure(BundleStorageError.downloadFailed(NSError(
-                domain: "HotUpdaterError",
-                code: 1,
-                userInfo: [NSLocalizedDescriptionKey: "Downloaded file does not exist atPath: \(location.path)"]
-            ))))
+        try? self.fileSystem.removeItem(atPath: tempDirectory)
+        guard self.fileSystem.createDirectory(atPath: tempDirectory) else {
+            completion(.failure(UpdateFailureError.classifying(
+                BundleStorageError.directoryCreationFailed,
+                during: .storage
+            )))
             return
         }
 
-        // 2) Define tmpDir and realDir
+        let currentBundleId = self.getCachedBundleId()
+        let currentBundleDir = currentBundleId.map {
+            (storeDir as NSString).appendingPathComponent($0)
+        }
+        let tempManifestPath = (tempDirectory as NSString).appendingPathComponent("manifest.json")
         let tmpDir = (storeDir as NSString).appendingPathComponent("\(bundleId).tmp")
         let realDir = (storeDir as NSString).appendingPathComponent(bundleId)
+        var diffFiles: [UpdateProgressPayload.DiffProgressFileSnapshot] = []
+        // The running step classifies the errors whose type does not.
+        var failurePhase = UpdatePhase.storage
+        var failureResource: UpdateFailureResource?
 
         do {
-            // 3) Remove any existing tmpDir
-            if self.fileSystem.fileExists(atPath: tmpDir) {
-                try self.fileSystem.removeItem(atPath: tmpDir)
-                NSLog("[BundleStorage] Removed existing tmpDir: \(tmpDir)")
-            }
-
-            // 4) Create tmpDir
-            guard self.fileSystem.createDirectory(atPath: tmpDir) else {
-                throw BundleStorageError.directoryCreationFailed
-            }
-            NSLog("[BundleStorage] Created tmpDir: \(tmpDir)")
-            logFileSystemDiagnostics(path: tmpDir, context: "TmpDir Created")
-
-            // 5) Verify bundle integrity (hash or signature based on fileHash format)
-            NSLog("[BundleStorage] Verifying bundle integrity...")
-            self.emitArchiveProgress(
+            try recoverInterruptedPromotion(finalDirectory: realDir)
+            failurePhase = .transfer
+            failureResource = .manifest
+            self.emitDiffProgress(
                 progressHandler: progressHandler,
-                progress: UpdateProgress.verificationStart
+                phase: "manifest",
+                files: diffFiles,
+                manifestProgress: 0
             )
-            let tempBundleURL = URL(fileURLWithPath: tempBundleFile)
-            let verificationResult = SignatureVerifier.verifyBundle(fileURL: tempBundleURL, fileHash: fileHash)
-            switch verificationResult {
+            switch self.downloadFileSynchronously(
+                from: manifestUrl,
+                to: tempManifestPath,
+                progressHandler: { progress in
+                    self.emitDiffProgress(
+                        progressHandler: progressHandler,
+                        phase: "manifest",
+                        files: diffFiles,
+                        manifestProgress: progress.progress
+                    )
+                }
+            ) {
             case .success:
-                NSLog("[BundleStorage] Bundle verification completed successfully")
-                self.emitArchiveProgress(
-                    progressHandler: progressHandler,
-                    progress: UpdateProgress.verificationEnd
-                )
+                break
             case .failure(let error):
-                NSLog("[BundleStorage] Bundle verification failed: \(error)")
-                try? self.fileSystem.removeItem(atPath: tmpDir)
-                self.cleanupTemporaryFiles([tempDirectory])
-                completion(.failure(BundleStorageError.signatureVerificationFailed(error)))
-                return
+                if let downloadError = error as? DownloadError,
+                   case .incompleteDownload(let expected, let actual) = downloadError {
+                    throw BundleStorageError.incompleteDownload(expected: expected, actual: actual)
+                }
+                throw BundleStorageError.downloadFailed(error)
             }
 
-            // 6) Unzip directly into tmpDir with progress tracking (0.8 - 1.0)
-            NSLog("[BundleStorage] Extracting \(tempBundleFile) → \(tmpDir)")
-            logFileSystemDiagnostics(path: tempBundleFile, context: "Before Extraction")
-            do {
-                try self.decompressService.unzip(file: tempBundleFile, to: tmpDir, progressHandler: { unzipProgress in
-                    self.emitArchiveProgress(
-                        progressHandler: progressHandler,
-                        progress: Self.mapProgress(
-                            unzipProgress,
-                            start: UpdateProgress.extractionStart,
-                            end: UpdateProgress.extractionEnd
-                        )
-                    )
-                })
-                NSLog("[BundleStorage] Extraction complete at \(tmpDir)")
-                logFileSystemDiagnostics(path: tmpDir, context: "After Extraction")
-            } catch {
-                let nsError = error as NSError
-                NSLog("[BundleStorage] Extraction failed - Domain: \(nsError.domain), Code: \(nsError.code), Description: \(nsError.localizedDescription)")
-                logFileSystemDiagnostics(path: tmpDir, context: "Extraction Failed")
-                try? self.fileSystem.removeItem(atPath: tmpDir)
-                self.cleanupTemporaryFiles([tempDirectory])
-                completion(.failure(BundleStorageError.extractionFormatError(error)))
-                return
+            failurePhase = .verification
+            let manifestVerificationResult = SignatureVerifier.verifyBundle(
+                fileURL: URL(fileURLWithPath: tempManifestPath),
+                fileHash: manifestFileHash
+            )
+            guard case .success = manifestVerificationResult else {
+                if case .failure(let error) = manifestVerificationResult {
+                    throw BundleStorageError.signatureVerificationFailed(error)
+                }
+                throw BundleStorageError.unknown(nil)
             }
 
-            // 7) Remove the downloaded bundle file
-            try? self.fileSystem.removeItem(atPath: tempBundleFile)
-
-            // 8) Verify that a valid bundle file exists inside tmpDir
-            self.emitArchiveProgress(
-                progressHandler: progressHandler,
-                progress: UpdateProgress.bundleValidation
-            )
-            switch self.findBundleFile(in: tmpDir, expectedBundleId: bundleId) {
-            case .success(let maybeBundlePath):
-                if let bundlePathInTmp = maybeBundlePath {
-                    NSLog("[BundleStorage] Found valid bundle in tmpDir: \(bundlePathInTmp)")
-                    logFileSystemDiagnostics(path: bundlePathInTmp, context: "Bundle Found")
-
-                    // 9) Remove any existing realDir
-                    if self.fileSystem.fileExists(atPath: realDir) {
-                        try self.fileSystem.removeItem(atPath: realDir)
-                        NSLog("[BundleStorage] Removed existing realDir: \(realDir)")
-                    }
+            failurePhase = .manifest
+            guard let manifestData = try? Data(contentsOf: URL(fileURLWithPath: tempManifestPath)),
+                  let manifestJson = try JSONSerialization.jsonObject(with: manifestData) as? [String: Any],
+                  let targetManifest = parseBundleManifest(from: manifestJson),
+                  targetManifest.bundleId == bundleId
+            else {
+                throw BundleStorageError.invalidBundle
+            }
+            // Validate the entire wire contract even when every byte can be reused.
+            guard Set(targetManifest.assets.keys) == Set(changedAssets.keys) else {
+                throw BundleStorageError.invalidBundle
+            }
+            for (path, asset) in targetManifest.assets {
+                guard FileUtilities.normalizedRelativePath(from: path) == path,
+                      path != "manifest.json",
+                      let descriptor = changedAssets[path],
+                      descriptor.fileUrl != nil,
+                      descriptor.fileHash.caseInsensitiveCompare(asset.fileHash) == .orderedSame else {
+                    throw BundleStorageError.invalidBundle
+                }
+                _ = try FileUtilities.fileURL(for: path, destinationRoot: tmpDir)
+            }
 
-                    // 10) Rename (move) tmpDir → realDir
+            // Downloads, patches, and extraction below classify their own errors.
+            failurePhase = .storage
+            failureResource = nil
+            guard self.fileSystem.createDirectory(atPath: tmpDir) else {
+                throw BundleStorageError.directoryCreationFailed
+            }
+            try pruneStagingDirectory(tmpDir, assets: Set(targetManifest.assets.keys))
+            let sortedAssets = targetManifest.assets.sorted { $0.key < $1.key }
+            let localDirectories = [currentBundleDir, realDir].compactMap { $0 }.filter { fileSystem.fileExists(atPath: $0) }
+            var downloads: [String: ChangedAssetDescriptor] = [:]
+            for (index, asset) in sortedAssets.enumerated() {
+                // Local preparation has its own progress interval, with no download files.
+                progressHandler(UpdateProgressPayload(
+                    progress: 0.15 + 0.05 * Double(index) / Double(max(1, sortedAssets.count)),
+                    artifactType: "diff",
+                    details: .init(totalFilesCount: 0, completedFilesCount: 0)
+                ))
+                let assetPath = asset.key
+                let expectedAsset = asset.value
+                let destinationPath = try FileUtilities.fileURL(for: assetPath, destinationRoot: tmpDir).path
+                guard self.fileSystem.createDirectory(atPath: (destinationPath as NSString).deletingLastPathComponent) else {
+                    throw BundleStorageError.directoryCreationFailed
+                }
+                if (try? fileSystem.attributesOfItem(atPath: destinationPath)[.type] as? FileAttributeType) == .typeRegular,
+                   (try? verifyManifestAssetFile(atPath: destinationPath, asset: expectedAsset)) != nil {
+                    continue
+                }
+                if fileSystem.fileExists(atPath: destinationPath) { try self.fileSystem.removeItem(atPath: destinationPath) }
+
+                var reused = false
+                // The cached target is only a candidate, just like the active OTA.
+                for directory in localDirectories {
+                    guard let sourcePath = try? FileUtilities.fileURL(for: assetPath, destinationRoot: directory).path,
+                          (try? fileSystem.attributesOfItem(atPath: sourcePath)[.type] as? FileAttributeType) == .typeRegular,
+                          (try? verifyManifestAssetFile(atPath: sourcePath, asset: expectedAsset)) != nil else { continue }
                     do {
-                        try self.fileSystem.moveItem(atPath: tmpDir, toPath: realDir)
-                        NSLog("[BundleStorage] Renamed tmpDir to realDir: \(realDir)")
-                        logFileSystemDiagnostics(path: realDir, context: "After Move")
+                        try self.fileSystem.copyItem(atPath: sourcePath, toPath: destinationPath)
+                        try verifyManifestAssetFile(atPath: destinationPath, asset: expectedAsset)
+                        reused = true
+                        break
                     } catch {
-                        let nsError = error as NSError
-                        NSLog("[BundleStorage] Move operation failed - Domain: \(nsError.domain), Code: \(nsError.code), Description: \(nsError.localizedDescription)")
-                        logFileSystemDiagnostics(path: tmpDir, context: "Move Failed - Source")
-                        logFileSystemDiagnostics(path: realDir, context: "Move Failed - Destination")
-                        throw BundleStorageError.moveOperationFailed(error)
+                        try? self.fileSystem.removeItem(atPath: destinationPath)
                     }
-
-                    // 11) Construct final bundlePath for preferences
-                    let finalBundlePath = try resolveBundlePathAfterMove(
-                        bundlePathInTmp,
-                        from: tmpDir,
-                        to: realDir
-                    )
-
-                    // 12) Set the bundle URL in preferences (for backwards compatibility)
-                    let currentMetadata = self.loadMetadataOrNull() ?? self.createInitialMetadata()
-                    guard let updatedMetadata = self.prepareMetadataForNewStagingBundle(currentMetadata, bundleId: bundleId) else {
-                        self.cleanupTemporaryFiles([tempDirectory])
-                        completion(.failure(BundleStorageError.unknown(
-                            NSError(domain: "HotUpdater", code: 0, userInfo: [
-                                NSLocalizedDescriptionKey: "Release catalog selection is stale"
-                            ])
-                        )))
-                        return
+                }
+                if reused { continue }
+                if builtInAssetResolver.copyIfMatches(assetPath: assetPath, expectedHash: expectedAsset.fileHash, destination: destinationPath) {
+                    try UpdateFailureError.during(.verification, resource: .file) {
+                        try verifyManifestAssetFile(atPath: destinationPath, asset: expectedAsset)
+                    }
+                    continue
+                }
+                downloads[assetPath] = changedAssets[assetPath]
+            }
+
+            var archiveInstalled = false
+            var patchedFiles = false
+            // The archive is chosen before any patch is tried, so only the
+            // per-file install can fall back from a patch.
+            var patchFallbacks = false
+            if shouldUseArchive(
+                archive: targetManifest.archive,
+                archiveUrl: archiveUrl,
+                downloads: downloads,
+                assets: targetManifest.assets
+            ), let archive = targetManifest.archive, let archiveUrl {
+                do {
+                    diffFiles = try UpdateFailureError.during(.storage, resource: .archive) {
+                        try installArchive(
+                            archive: archive,
+                            archiveUrl: archiveUrl,
+                            targetManifest: targetManifest,
+                            preparedDirectory: tmpDir,
+                            tempDirectory: tempDirectory,
+                            progressHandler: progressHandler
+                        )
+                    }
+                    archiveInstalled = true
+                } catch {
+                    NSLog("[BundleStorage] tar.br optimization failed; falling back to individual files: \(error.localizedDescription)")
+                    guard fileSystem.fileExists(atPath: tmpDir) else {
+                        throw error
                     }
-                    let setResult = self.setBundleURL(localPath: finalBundlePath)
-                    switch setResult {
-                    case .success:
-                        NSLog("[BundleStorage] Successfully set bundle URL: \(finalBundlePath)")
+                }
+            }
 
-                        // 13) Set staging metadata for rollback support
-                        let _ = self.saveMetadata(updatedMetadata)
-                        NSLog("[BundleStorage] Set staging bundle: \(bundleId), verificationPending: true")
+            if !archiveInstalled {
+                diffFiles = createDiffProgressFiles(changedAssets: downloads)
+                emitDiffProgress(progressHandler: progressHandler, phase: "downloading", files: diffFiles)
+                let progressLock = NSLock()
+                let workers = OperationQueue()
+                workers.maxConcurrentOperationCount = 4
+                var installError: Error?
+                var installOutcomes: [AssetInstallOutcome] = []
+                for progressFile in diffFiles {
+                    let assetPath = progressFile.path
+                    let expectedAsset = targetManifest.assets[assetPath]!
+                    let descriptor = downloads[assetPath]!
+                    let destinationPath = try FileUtilities.fileURL(for: assetPath, destinationRoot: tmpDir).path
+                    // Separate temp namespaces also avoid collisions between flattened asset paths.
+                    let workerTemp = (tempDirectory as NSString).appendingPathComponent(String(progressFile.order))
+                    workers.addOperation {
+                        progressLock.lock()
+                        let shouldSkip = installError != nil
+                        progressLock.unlock()
+                        if shouldSkip { return }
+                        do {
+                            guard self.fileSystem.createDirectory(atPath: workerTemp) else { throw BundleStorageError.directoryCreationFailed }
+                            let outcome = try self.downloadManifestAsset(
+                                assetPath: assetPath, expectedAsset: expectedAsset, changedAsset: descriptor,
+                                currentBundleId: currentBundleId, currentBundleDir: currentBundleDir,
+                                destinationPath: destinationPath, tempDirectory: workerTemp, progressFile: progressFile,
+                                progressHandler: { payload in
+                                    progressLock.lock()
+                                    defer { progressLock.unlock() }
+                                    if let snapshot = payload.details?.files.first,
+                                       let index = diffFiles.firstIndex(where: { $0.path == assetPath }) {
+                                        diffFiles[index] = snapshot
+                                    }
+                                    self.emitDiffProgress(progressHandler: progressHandler, phase: "downloading", files: diffFiles)
+                                }
+                            )
+                            progressLock.lock()
+                            installOutcomes.append(outcome)
+                            progressLock.unlock()
+                        } catch {
+                            progressLock.lock()
+                            if installError == nil { installError = error }
+                            progressLock.unlock()
+                        }
+                    }
+                }
+                // Join all workers before cleaning scratch files, even after a failure.
+                workers.waitUntilAllOperationsAreFinished()
+                if let installError { throw installError }
+                for outcome in installOutcomes {
+                    switch outcome {
+                    case .patched:
+                        patchedFiles = true
+                    case .downloaded(let patchFallback):
+                        patchFallbacks = patchFallbacks || patchFallback
+                    }
+                }
+            }
 
-                        // 14) Clean up the temporary directory
-                        self.cleanupTemporaryFiles([tempDirectory])
+            self.emitDiffProgress(
+                progressHandler: progressHandler,
+                phase: "finalizing",
+                files: diffFiles
+            )
 
-                        self.emitArchiveProgress(
-                            progressHandler: progressHandler,
-                            progress: UpdateProgress.activationReady
-                        )
-                        self.scheduleCleanupOldBundles(
-                            bundleIdsToKeep: [currentBundleId, updatedMetadata.stableBundleId, bundleId].compactMap { $0 }
-                        )
+            let manifestDestination = (tmpDir as NSString).appendingPathComponent("manifest.json")
+            try copyVerifiedManifest(from: tempManifestPath, to: manifestDestination)
 
-                        // 15) Complete with success
-                        self.emitArchiveProgress(
-                            progressHandler: progressHandler,
-                            progress: UpdateProgress.complete
-                        )
-                        completion(.success(true))
-                    case .failure(let err):
-                        let nsError = err as NSError
-                        NSLog("[BundleStorage] Failed to set bundle URL - Domain: \(nsError.domain), Code: \(nsError.code), Description: \(nsError.localizedDescription)")
-                        // Preferences save failed → remove realDir and clean up
-                        try? self.fileSystem.removeItem(atPath: realDir)
-                        self.cleanupTemporaryFiles([tempDirectory])
-                        completion(.failure(err))
-                    }
-                } else {
-                    // No valid .jsbundle found → delete tmpDir and fail
-                    NSLog("[BundleStorage] No valid bundle file found in tmpDir")
-                    logFileSystemDiagnostics(path: tmpDir, context: "Invalid Bundle")
-                    try? self.fileSystem.removeItem(atPath: tmpDir)
-                    self.cleanupTemporaryFiles([tempDirectory])
-                    completion(.failure(BundleStorageError.invalidBundle))
+            switch self.findBundleFile(in: tmpDir, expectedBundleId: bundleId) {
+            case .success(let maybeBundlePath):
+                guard let bundlePathInTmp = maybeBundlePath else {
+                    // The manifest does not name exactly one platform bundle file.
+                    throw UpdateFailureError(
+                        underlying: BundleStorageError.invalidBundle,
+                        failure: UpdateFailure.invalidResponse.with(resource: .manifest)
+                    )
                 }
-            case .failure(let findError):
-                let nsError = findError as NSError
-                NSLog("[BundleStorage] Error finding bundle file - Domain: \(nsError.domain), Code: \(nsError.code), Description: \(nsError.localizedDescription)")
-                // Error scanning tmpDir → delete tmpDir and fail
-                try? self.fileSystem.removeItem(atPath: tmpDir)
+
+                let updatedMetadata = try promoteStagedBundle(
+                    bundleId: bundleId,
+                    stagingDirectory: tmpDir,
+                    finalDirectory: realDir,
+                    bundlePathInStaging: bundlePathInTmp
+                )
                 self.cleanupTemporaryFiles([tempDirectory])
-                completion(.failure(findError))
+                self.scheduleCleanupOldBundles(
+                    bundleIdsToKeep: [currentBundleId, updatedMetadata.stableBundleId, bundleId].compactMap { $0 }
+                )
+                progressHandler(UpdateProgressPayload(
+                    progress: 1.0,
+                    artifactType: "diff",
+                    details: .init(
+                        totalFilesCount: diffFiles.count,
+                        completedFilesCount: diffFiles.filter { $0.status == "downloaded" }.count,
+                        files: diffFiles
+                    )
+                ))
+                let delivery: UpdateDelivery.Method =
+                    archiveInstalled ? .archive : (patchedFiles ? .patch : .manifest)
+                completion(.success(UpdateDelivery(method: delivery, patchFallback: patchFallbacks)))
+            case .failure(let error):
+                throw error
             }
-        } catch let error {
-            // Any failure during unzip or rename → clean tmpDir and fail
-            let nsError = error as NSError
-            NSLog("[BundleStorage] Error during tmpDir processing - Domain: \(nsError.domain), Code: \(nsError.code), Description: \(nsError.localizedDescription)")
-            logFileSystemDiagnostics(path: tmpDir, context: "Processing Error")
-            try? self.fileSystem.removeItem(atPath: tmpDir)
+        } catch {
+            NSLog("[BundleStorage] Manifest-driven install failed: \(error.localizedDescription).")
+            // Preserve staging for a hash-checked retry. Never trust its presence alone.
             self.cleanupTemporaryFiles([tempDirectory])
-
-            // Re-throw specific BundleStorageError if it is one, otherwise wrap as unknown
-            if let bundleError = error as? BundleStorageError {
-                completion(.failure(bundleError))
-            } else {
-                completion(.failure(BundleStorageError.unknown(error)))
-            }
+            completion(.failure(UpdateFailureError.classifying(
+                error,
+                during: failurePhase,
+                resource: failureResource
+            )))
         }
     }
 
-    private static func mapProgress(_ value: Double, start: Double, end: Double) -> Double {
-        let clampedValue = min(max(value, 0), 1)
-        return start + (clampedValue * (end - start))
+    func markLaunchStarted(bundleId: String?) {
+        // Unlike prepareLaunch, this can run while JavaScript stages a newer bundle.
+        releaseStateLock.lock()
+        defer { releaseStateLock.unlock() }
+        guard let bundleId,
+              var metadata = loadMetadataOrNull(),
+              metadata.verificationPending,
+              !metadata.launchInProgress,
+              metadata.stagingBundleId == bundleId else {
+            return
+        }
+        metadata.launchInProgress = true
+        _ = saveMetadata(metadata)
     }
 
-    // MARK: - Rollback Support
-
-    /**
-     * Marks the current launch as successful after the first content appeared.
-     */
     func markLaunchCompleted(bundleId: String?) {
+        // Before the guard: content from the built-in bundle (nil) also counts.
+        readyInterruptedLaunchRetry(bundleId)
         guard let bundleId,
               var metadata = loadMetadataOrNull(),
               metadata.verificationPending,
@@ -2935,6 +2821,7 @@ class BundleFileStorageService: BundleStorageService {
         metadata.stableBundleId = nil
         metadata.stableSelection = nil
         metadata.verificationPending = false
+        metadata.launchInProgress = false
         metadata.pendingTransition = nil
         metadata.pendingSelectionTransition = nil
         metadata.updatedAt = Date().timeIntervalSince1970 * 1000
@@ -2953,9 +2840,10 @@ class BundleFileStorageService: BundleStorageService {
 
     func notifyAppReady() -> [String: Any] {
         guard let report = loadLaunchReport() else {
-            if let metadata = loadMetadataOrNull(),
+            if let launchedBundleId = pendingLaunchBundleId,
+               let metadata = loadMetadataOrNull(),
                metadata.verificationPending,
-               metadata.stagingBundleId != nil {
+               metadata.stagingBundleId == launchedBundleId {
                 return ["status": "PENDING"]
             }
             return ["status": LaunchReportStatus.unchanged.rawValue]
@@ -2981,11 +2869,20 @@ class BundleFileStorageService: BundleStorageService {
     }
 
     /**
-     * Returns the crashed bundle history.
+     * Returns the bundles this device refuses to install: crash history, plus a
+     * bundle waiting for its retry until a process that may retry it.
      * @return The crashed history object
      */
     func getCrashHistory() -> CrashedHistory {
-        return loadCrashedHistory()
+        crashedHistoryLock.lock()
+        defer { crashedHistoryLock.unlock() }
+        var history = loadCrashedHistory()
+        if let interrupted = history.interruptedLaunch,
+           !interrupted.retryReady || interrupted.bundleId == retryHeldBundleId,
+           !history.contains(interrupted.bundleId) {
+            history.bundles.append(CrashedBundleEntry(bundleId: interrupted.bundleId))
+        }
+        return history
     }
 
     /**
@@ -2993,40 +2890,59 @@ class BundleFileStorageService: BundleStorageService {
      * @return true if clearing was successful
      */
     func clearCrashHistory() -> Bool {
+        crashedHistoryLock.lock()
+        defer { crashedHistoryLock.unlock() }
         var history = loadCrashedHistory()
         history.clear()
+        retryHeldBundleId = nil
         return saveCrashedHistory(history)
     }
 
-    func getInstallId() -> String {
-        if let installId = loadInstallIdentity()?.installId {
-            return installId
-        }
-
-        let identity = InstallIdentity()
-        guard saveInstallIdentity(identity) else {
-            return identity.installId
+    /// A crash, or a second unfinished launch of the same bundle, adds the bundle
+    /// to crash history. A first unfinished launch cannot tell a hang from a user
+    /// leaving early, so it leaves the bundle one retry instead.
+    private func recordFailedLaunch(_ bundleId: String, unfinishedLaunch: Bool) {
+        crashedHistoryLock.lock()
+        defer { crashedHistoryLock.unlock() }
+        var history = loadCrashedHistory()
+        let interrupted = history.interruptedLaunch
+        if unfinishedLaunch, interrupted?.bundleId != bundleId {
+            NSLog("[BundleStorage] Launch of \(bundleId) ended before first content; it gets one retry")
+            history.interruptedLaunch = InterruptedLaunch(bundleId: bundleId)
+            retryHeldBundleId = bundleId
+        } else {
+            history.addEntry(bundleId)
+            if interrupted?.bundleId == bundleId {
+                history.interruptedLaunch = nil
+            }
         }
-        return identity.installId
-    }
-
-    func getUserId() -> String? {
-        loadUserIdentity()?.userId
-    }
-
-    func getUsername() -> String? {
-        loadUserIdentity()?.username
+        _ = saveCrashedHistory(history)
     }
 
-    func setUser(userId: String?, username: String?) {
-        let normalizedUserId = normalizeIdentityValue(userId)
-        let normalizedUsername = normalizeIdentityValue(username)
-        let identity = UserIdentity(userId: normalizedUserId, username: normalizedUsername)
-        if identity.isEmpty {
-            _ = saveUserIdentity(nil)
+    /// First content appeared, so the app works again. A bundle waiting for its
+    /// retry may be installed from the next process on. This process keeps
+    /// refusing it, so the session that recovered never reloads into it. Content
+    /// from that bundle verifies it.
+    private func readyInterruptedLaunchRetry(_ currentBundleId: String?) {
+        crashedHistoryLock.lock()
+        defer { crashedHistoryLock.unlock() }
+        var history = loadCrashedHistory()
+        guard let interrupted = history.interruptedLaunch else {
+            return
+        }
+        if interrupted.bundleId == currentBundleId {
+            history.interruptedLaunch = nil
+        } else if interrupted.retryReady {
             return
+        } else {
+            history.interruptedLaunch?.retryReady = true
+            retryHeldBundleId = interrupted.bundleId
         }
-        _ = saveUserIdentity(identity)
+        _ = saveCrashedHistory(history)
+    }
+
+    func getInstallId() -> String {
+        loadOrCreateInstallIdentity().installId
     }
 
     /**