@onekeyfe/react-native-range-downloader 3.0.66 → 3.0.68

package/ios/ReactNativeRangeDownloader.swift

@@ -1,5 +1,4 @@
 import Foundation
-import CommonCrypto
 import NitroModules
 import ReactNativeNativeLogger
 
@@ -14,24 +13,38 @@ import ReactNativeNativeLogger
 //   - one hardcoded background session identifier → one session per channel;
 //   - `onProgress` closure       → a listener registry broadcasting
 //     `RangeDownloadEvent`s (multi-consumer);
-//   - `throws FallbackError`     → returns `RangeDownloadResult(.fallback, …)`.
+//   - `throws FallbackError`     → returns a typed `RangeDownloadResult`
+//     (`fallbackTransient` / `fallbackPermanent` + `fallbackKind`).
 class ReactNativeRangeDownloader: HybridReactNativeRangeDownloaderSpec {
 
   func download(params: RangeDownloadParams) throws -> Promise<RangeDownloadResult> {
     return Promise.async {
-      let (outcome, filePath, fallbackReason) = await RangeDownloader.shared.download(
+      let (klass, filePath, fallbackReason, fallbackClass) = await RangeDownloader.shared.download(
         channel: params.channel,
         taskId: params.taskId,
         urlString: params.url,
         filePath: params.destFilePath,
         expectedSha256: params.expectedSha256,
         segmentCount: params.segmentCount.map { Int($0) },
-        minConcurrentBytes: params.minConcurrentBytes.map { Int64($0) }
+        minConcurrentBytes: params.minConcurrentBytes.map { Int64($0) },
+        // §5.4: caller-tunable retry/timeout/deadline knobs forwarded straight
+        // from the regenerated `RangeDownloadParams`. Omitted (nil) values let the
+        // core use its platform defaults.
+        maxSegmentAttempts: params.maxSegmentAttempts.map { Int($0) },
+        requestTimeoutSeconds: params.requestTimeoutSeconds,
+        stallTimeoutSeconds: params.stallTimeoutSeconds,
+        overallDeadlineSeconds: params.overallDeadlineSeconds
       )
+      // Wire mapping (OCDS §4): map the in-process typed class onto the
+      // regenerated wire enum — no lossy collapse. `completed`, `fallbackTransient`
+      // and `fallbackPermanent` each cross the JS bridge as their own case, and the
+      // optional `fallbackKind` sub-classification is forwarded so callers /
+      // analytics can branch without parsing the reason string.
       return RangeDownloadResult(
-        outcome: outcome,
+        outcome: klass.wireOutcome,
         filePath: filePath,
-        fallbackReason: fallbackReason
+        fallbackReason: fallbackReason,
+        fallbackKind: fallbackClass?.wireKind
       )
     }
   }
@@ -107,6 +120,42 @@ class ReactNativeRangeDownloader: HybridReactNativeRangeDownloaderSpec {
 /// "channel|taskId" so multiple channels can download at once. Each running
 /// task's `taskDescription` encodes "channel|taskId|segIndex" so a delegate
 /// callback can locate both the run and the segment.
+// MARK: - Typed failure model (OCDS §4) — wire projections
+//
+// The dependency-free enum bodies for `RangeDownloadClass` / `RangeFallbackClass`
+// (plus the deterministic logic funcs) live in `RangeDownloadLogic.swift` so they
+// can be unit-tested without the Nitro / NativeLogger deps. Only the wire
+// projections — which depend on the codegen enums (`RangeDownloadOutcome` /
+// `RangeFallbackKind`) — remain here, in the module that has those generated types.
+//
+// The IN-PROCESS core returns the Swift-native typed class to its in-process
+// caller (BundleUpdate); the Nitro shim maps it onto the regenerated wire enum
+// `RangeDownloadOutcome` (completed | fallbackTransient | fallbackPermanent) so
+// the failure class crosses the JS boundary as an EXPLICIT value, never inferred
+// from incidental on-disk side effects (which §4 forbids).
+extension RangeDownloadClass {
+  /// 1:1 projection onto the generated wire enum (`RangeDownloadOutcome`) that
+  /// crosses the JS bridge. No collapse: each in-process class maps to its own
+  /// typed wire case.
+  var wireOutcome: RangeDownloadOutcome {
+    switch self {
+    case .completed: return .completed
+    case .fallbackTransient: return .fallbacktransient
+    case .fallbackPermanent: return .fallbackpermanent
+    }
+  }
+}
+
+extension RangeFallbackClass {
+  /// 1:1 projection onto the generated wire enum (`RangeFallbackKind`). The case
+  /// names are the wire union's string values verbatim, so `fromString` is exact
+  /// and total (the force-unwrap can never fail).
+  var wireKind: RangeFallbackKind {
+    // swiftlint:disable:next force_unwrapping
+    return RangeFallbackKind(fromString: self.rawValue)!
+  }
+}
+
 public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
 
   public static let shared = RangeDownloader()
@@ -161,26 +210,87 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     var continuation: CheckedContinuation<Void, Error>?
     var prevProgress = -1
     var fellBack = false
+    /// §4 typed class for the eventual fallback. Set by the delegate when it
+    /// classifies a non-206 status or a redirect/total/stash failure; consumed by
+    /// finalize so the outcome is an EXPLICIT class, never inferred from on-disk
+    /// side effects. `serverIgnoredRange` (Permanent) is the historical default
+    /// for the bare `fellBack` path (status 200).
+    var fellBackKind: RangeFallbackClass = .serverIgnoredRange
     /// Set when a segment could not be stashed (move/size-check failure). Carries
     /// the terminal error so didCompleteWithError finalizes instead of hanging.
     var stashError: Error?
+    /// §4/§5.4: per-segment indexes whose finished body was a TRANSIENT HTTP
+    /// status (429/5xx/408/416) — the body is discarded and the segment is
+    /// re-enqueued (G2) instead of failing the whole run. Optional Retry-After
+    /// seconds captured from that response, used to override backoff.
+    var transientSegmentRetryAfter: [Int: Double?] = [:]
+    /// §4 (416): segment indexes that returned `416 Range Not Satisfiable`. A
+    /// bare 416 must NOT re-request the same range blindly: the total size /
+    /// validator is re-evaluated (re-probe) first. If the total or ETag changed
+    /// the object changed under us → object-change (wipe + restart, Permanent);
+    /// otherwise the range is still valid and we keep the resumable `.segN` and
+    /// retry. Set in didFinishDownloadingTo, consumed in didCompleteWithError.
+    var sizeReevalIndexes: Set<Int> = []
     /// Whether a strong validator (ETag) was captured for this run. When false,
     /// resumable `.segN` state must not be trusted across attempts.
     var hasValidator = false
     let sessionIdentifier: String
 
+    /// §5.4: per-segment transient retry budget (caller-tunable).
+    let maxSegmentAttempts: Int
+    /// §5.4: number of transient retry attempts already spent per segment index.
+    var segmentAttempts: [Int: Int] = [:]
+    /// §5.4: segment indexes the stall watchdog cancelled, so didCompleteWithError
+    /// treats the resulting NSURLErrorCancelled as a transient stall (retry),
+    /// not an external user cancel (terminate).
+    var stallCancelledIndexes: Set<Int> = []
+    /// §5.4 (G2): segment indexes with a backoff retry already SCHEDULED (an
+    /// asyncAfter pending) but not yet re-enqueued. A pending retry is invisible
+    /// to `getAllTasks` (no live task exists during the backoff window), so a
+    /// sibling segment's completion could otherwise re-increment this segment's
+    /// attempt counter and schedule a DUPLICATE retry. Inserted when the
+    /// asyncAfter is armed; cleared inside `enqueueSegment` when the real task is
+    /// created. Both `retrySegmentIfUnderBudget` and the missing-segment
+    /// re-enqueue gate on this set so a segment is never double-enqueued.
+    var pendingRetryIndexes: Set<Int> = []
+    /// §5.11 (single-run portion): wall-clock deadline; nil = unbounded. The
+    /// cross-restart budget/deadline is owned by the shared-JS track.
+    let deadline: Date?
+    /// §5.4: last time ANY segment of this run made progress (didWriteData),
+    /// used by the stall watchdog. Only foreground/active time should count.
+    var lastProgressAt = Date()
+    /// The URL this run is fetching, retained so the delegate can re-enqueue a
+    /// single segment without re-plumbing it through every call.
+    var url: URL?
+
     init(channel: DownloadChannel, taskId: String, filePath: String,
-         segmentCount: Int, sessionIdentifier: String) {
+         segmentCount: Int, sessionIdentifier: String,
+         maxSegmentAttempts: Int, deadline: Date?) {
       self.channel = channel
       self.taskId = taskId
       self.filePath = filePath
       self.segmentCount = segmentCount
       self.sessionIdentifier = sessionIdentifier
+      self.maxSegmentAttempts = maxSegmentAttempts
+      self.deadline = deadline
     }
 
     func segPath(_ index: Int) -> String { "\(filePath).seg\(index)" }
+
+    /// True once the wall-clock deadline (if any) has passed.
+    var isPastDeadline: Bool {
+      guard let deadline = deadline else { return false }
+      return Date() >= deadline
+    }
   }
 
+  // Default retry/backoff/deadline knobs (§5.4 / §5.11 single-run). Caller-tunable
+  // via RangeDownloadParams; these are platform configuration, not part of OCDS.
+  private static let defaultMaxSegmentAttempts = 4
+  private static let defaultRequestTimeoutSeconds: Double = 60
+  private static let defaultStallTimeoutSeconds: Double = 30
+  // §5.4 backoff knobs now live on `RangeDownloadLogic` (used only by backoffDelay).
+
   override init() {
     super.init()
     NotificationCenter.default.addObserver(
@@ -246,6 +356,12 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     cfg.isDiscretionary = false
     cfg.sessionSendsLaunchEvents = true
     cfg.httpMaximumConnectionsPerHost = segmentCount
+    // §5.4: connection / request timeout. The session is cached per channel, so
+    // this uses the default; per-run knobs are enforced by the JS-side deadline
+    // and the in-app stall watchdog rather than re-creating the session. A
+    // background session keeps the resource timeout generous so a legitimately
+    // long suspended transfer is not killed by the OS resource clock (§5.10).
+    cfg.timeoutIntervalForRequest = RangeDownloader.defaultRequestTimeoutSeconds
     let created = URLSession(configuration: cfg, delegate: self, delegateQueue: nil)
     lock.lock()
     // Another thread may have raced us; prefer the first-stored session.
@@ -324,10 +440,11 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
   // MARK: - Public entry
 
   /// Downloads [urlString] into [filePath] using concurrent background ranges.
-  /// Returns `(.completed, filePath, nil)` on success, or `(.fallback, filePath,
-  /// reason)` when the caller should use its single-stream path. Transient
-  /// network errors are also reported as `.fallback` with the error reason (the
-  /// `.segN` files are kept for the next attempt).
+  /// Returns `(.completed, filePath, nil, nil)` on success, or a typed fallback
+  /// tuple `(.fallbackTransient | .fallbackPermanent, filePath, reason, kind)`
+  /// when the caller should use its single-stream path. Transient network errors
+  /// resolve to `.fallbackTransient` and KEEP the `.segN` files for the next
+  /// attempt; permanent ones discard them.
   public func download(
     channel: DownloadChannel,
     taskId: String,
@@ -335,42 +452,90 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     filePath: String,
     expectedSha256: String?,
     segmentCount: Int?,
-    minConcurrentBytes: Int64?
-  ) async -> (RangeDownloadOutcome, String, String?) {
+    minConcurrentBytes: Int64?,
+    maxSegmentAttempts: Int? = nil,
+    requestTimeoutSeconds: Double? = nil,
+    stallTimeoutSeconds: Double? = nil,
+    overallDeadlineSeconds: Double? = nil
+  ) async -> (RangeDownloadClass, String, String?, RangeFallbackClass?) {
     let segCount = max(1, segmentCount ?? Self.defaultSegmentCount)
     let minBytes = minConcurrentBytes ?? Self.defaultMinConcurrentBytes
+    let maxAttempts = max(1, maxSegmentAttempts ?? Self.defaultMaxSegmentAttempts)
+    // §5.4: caller-tunable stall window for this run's watchdog; the background
+    // URLSession's per-request timeout is cached per channel (see `session(...)`),
+    // so the per-run request timeout is enforced via the deadline + stall watchdog
+    // rather than re-creating the session.
+    let stallSeconds = (stallTimeoutSeconds.map { $0 > 0 ? $0 : nil } ?? nil)
+      ?? Self.defaultStallTimeoutSeconds
+    _ = requestTimeoutSeconds // documented above; session timeout is channel-cached
+    let deadline: Date? = {
+      guard let s = overallDeadlineSeconds, s > 0 else { return nil }
+      return Date().addingTimeInterval(s)
+    }()
     let key = Self.runKey(channel: channel, taskId: taskId)
 
     guard let url = URL(string: urlString) else {
-      return (.fallback, filePath, "invalid url")
+      return (.fallbackPermanent, filePath, "invalid url", .rangeUnsupported)
     }
     // HTTPS-only: background URLSession + transport hardening.
     guard urlString.hasPrefix("https://") else {
-      return (.fallback, filePath, "url must use https")
+      return (.fallbackPermanent, filePath, "url must use https", .redirectRejected)
+    }
+
+    // §5.8 (G7): at most one live run per destination. A second download() for
+    // the same key/filePath while one is in flight joins-or-fails-fast rather
+    // than overwriting RunState and co-writing the same `.segN`. The guard keys
+    // off `runs[key]` MEMBERSHIP, not `continuation != nil`: the continuation is
+    // only assigned after probe + insert, so a `continuation != nil` test left a
+    // window (insert → continuation assignment, and the synchronous
+    // allSegmentsPresent fast path which never sets a continuation at all) where
+    // a half-initialized run was invisible and a 2nd download() could overwrite
+    // `runs[key]`. We fail fast (the caller retry loop re-drives cleanly) to
+    // avoid join bookkeeping hangs.
+    if let existing = run(forKey: key), existing.filePath == filePath {
+      return (.fallbackTransient, filePath,
+              "another run is already active for this destination", .budgetExhausted)
     }
 
     let probe: ProbeResult
     do {
       probe = try await self.probe(url: url)
     } catch {
-      return (.fallback, filePath, "probe failed: \(error.localizedDescription)")
+      // A probe that cannot reach the server is a transient network condition.
+      return (.fallbackTransient, filePath,
+              "probe failed: \(error.localizedDescription)", .transientNetwork)
     }
     guard probe.supportsRange, probe.total >= minBytes else {
-      return (.fallback, filePath, "range unsupported or file too small")
+      return (.fallbackPermanent, filePath,
+              "range unsupported or file too small", .rangeUnsupported)
     }
 
     let state = RunState(
       channel: channel, taskId: taskId, filePath: filePath,
       segmentCount: segCount,
-      sessionIdentifier: Self.sessionIdentifier(for: channel)
+      sessionIdentifier: Self.sessionIdentifier(for: channel),
+      maxSegmentAttempts: maxAttempts, deadline: deadline
     )
     state.totalSize = probe.total
     state.etag = probe.etag
+    state.url = url
     state.hasValidator = (probe.etag?.isEmpty == false)
-    state.ranges = Self.planRanges(total: probe.total, segments: segCount)
+    state.ranges = RangeDownloadLogic.planRanges(total: probe.total, segments: segCount)
     state.segmentWritten = [Int64](repeating: 0, count: state.ranges.count)
 
+    // §5.8 (G7): claim the destination slot atomically. Re-check membership under
+    // the SAME lock hold as the insert so two download() calls that both passed
+    // the early guard (which ran before their respective async probes) cannot
+    // both insert — the loser fails fast and never co-writes `.segN`. From this
+    // insert onward `runs[key]` membership is the single-flight authority, so a
+    // half-initialized run (continuation not yet assigned, or the synchronous
+    // fast path that never assigns one) is still observed as live by any racer.
     lock.lock()
+    if let existing = runs[key], existing.filePath == filePath, existing !== state {
+      lock.unlock()
+      return (.fallbackTransient, filePath,
+              "another run is already active for this destination", .budgetExhausted)
+    }
     runs[key] = state
     lock.unlock()
 
@@ -386,6 +551,12 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
 
     emit(channel: channel, taskId: taskId, type: "start", progress: 0, message: "")
 
+    // §5.4: start the bytes-stalled watchdog for this run. It cancels a stalled
+    // segment task so didCompleteWithError routes it through the in-place retry
+    // path. It only counts foreground/active wall time toward the stall window so
+    // a legitimately suspended background transfer (§5.10) is never false-cancelled.
+    startStallWatchdog(key: key, stallSeconds: stallSeconds)
+
     do {
       // If every segment is already on disk (resume after suspension/kill), skip
       // straight to concatenation.
@@ -402,32 +573,36 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     } catch let fb as FallbackError {
       clearRun(key: key)
       emit(channel: channel, taskId: taskId, type: "fallback", progress: 0, message: fb.reason)
-      return (.fallback, filePath, fb.reason)
+      return (fb.kind.failureClass, filePath, fb.reason, fb.kind)
     } catch {
-      // Transient error → ask caller to fall back (segments retained for retry).
+      // A non-FallbackError thrown out of the run is a local/transient condition
+      // (disk I/O, an interrupted segment) → ask the caller to retry the
+      // concurrent path; segments are retained for resume.
       clearRun(key: key)
       let reason = error.localizedDescription
       emit(channel: channel, taskId: taskId, type: "fallback", progress: 0, message: reason)
-      return (.fallback, filePath, reason)
+      return (.fallbackTransient, filePath, reason, .transientNetwork)
     }
 
     clearRun(key: key)
 
     // Optional immediate SHA256 self-check backstop. When omitted, the caller
-    // verifies after the fact.
+    // verifies after the fact. A whole-file checksum mismatch is Permanent (§4):
+    // the assembled bytes are unsalvageable, so discard final + artifacts.
     if let expected = expectedSha256, !expected.isEmpty {
-      let actual = Self.calculateSHA256(filePath)
+      let actual = RangeDownloadLogic.calculateSHA256(filePath)
       if actual?.lowercased() != expected.lowercased() {
         try? FileManager.default.removeItem(atPath: filePath)
+        discardArtifacts(filePath: filePath)
         let reason = "sha256 mismatch (expected \(expected), got \(actual ?? "nil"))"
         OneKeyLog.error("RangeDownloader", "\(channel.stringValue)/\(taskId): \(reason)")
         emit(channel: channel, taskId: taskId, type: "fallback", progress: 0, message: reason)
-        return (.fallback, filePath, reason)
+        return (.fallbackPermanent, filePath, reason, .checksumMismatch)
       }
     }
 
     emit(channel: channel, taskId: taskId, type: "complete", progress: 100, message: "")
-    return (.completed, filePath, nil)
+    return (.completed, filePath, nil, nil)
   }
 
   private func clearRun(key: String) {
@@ -436,23 +611,23 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
 
   // MARK: - Range planning / probing
 
-  static func planRanges(total: Int64, segments: Int) -> [(start: Int64, end: Int64)] {
-    var out: [(Int64, Int64)] = []
-    let chunk = (total + Int64(segments) - 1) / Int64(segments)
-    var i = 0
-    while i < segments {
-      let start = Int64(i) * chunk
-      if start >= total { break }
-      let end = min(start + chunk - 1, total - 1)
-      out.append((start, end))
-      i += 1
+  private struct ProbeResult { let total: Int64; let etag: String?; let supportsRange: Bool }
+
+  struct FallbackError: Error {
+    let reason: String
+    /// §4 typed sub-class. Defaults to a Permanent `serverIgnoredRange` only so an
+    /// un-annotated legacy throw keeps the previous "discard + single-stream"
+    /// behavior; all new throw sites pass an explicit kind.
+    let kind: RangeFallbackClass
+    init(reason: String, kind: RangeFallbackClass = .serverIgnoredRange) {
+      self.reason = reason
+      self.kind = kind
     }
-    return out
   }
 
-  private struct ProbeResult { let total: Int64; let etag: String?; let supportsRange: Bool }
-
-  struct FallbackError: Error { let reason: String }
+  // HTTP status classification (classifyStatus), Retry-After parsing
+  // (parseRetryAfterSeconds), Content-Range parsing and backoff math now live on
+  // `RangeDownloadLogic` (OCDS §4 / §5). Callsites use `RangeDownloadLogic.<fn>`.
 
   /// One-byte Range request on a default (foreground) session to learn total
   /// size + ETag + Range support. Background sessions can't do data tasks, so
@@ -474,7 +649,7 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
         let etag = http.value(forHTTPHeaderField: "ETag")
         if http.statusCode == 206,
            let cr = http.value(forHTTPHeaderField: "Content-Range"),
-           let total = Self.parseContentRangeTotal(cr) {
+           let total = RangeDownloadLogic.parseContentRangeTotal(cr) {
           cont.resume(returning: ProbeResult(total: total, etag: etag, supportsRange: true))
         } else {
           // 200 (Range ignored) or anything else → single-stream.
@@ -485,29 +660,6 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     }
   }
 
-  static func parseContentRangeTotal(_ header: String) -> Int64? {
-    // "bytes 0-0/65226095"
-    guard let slash = header.lastIndex(of: "/") else { return nil }
-    let tail = header[header.index(after: slash)...]
-    return Int64(tail.trimmingCharacters(in: .whitespaces))
-  }
-
-  /// Parses the start/end of a "bytes <start>-<end>/<total>" Content-Range.
-  static func parseContentRangeBounds(_ header: String) -> (start: Int64, end: Int64)? {
-    // Drop the leading "bytes " and the trailing "/<total>".
-    let trimmed = header.trimmingCharacters(in: .whitespaces)
-    guard let spaceIdx = trimmed.firstIndex(of: " ") else { return nil }
-    var rangePart = String(trimmed[trimmed.index(after: spaceIdx)...])
-    if let slash = rangePart.firstIndex(of: "/") {
-      rangePart = String(rangePart[..<slash])
-    }
-    let bounds = rangePart.split(separator: "-", maxSplits: 1).map { String($0) }
-    guard bounds.count == 2,
-          let start = Int64(bounds[0].trimmingCharacters(in: .whitespaces)),
-          let end = Int64(bounds[1].trimmingCharacters(in: .whitespaces)) else { return nil }
-    return (start, end)
-  }
-
   // MARK: - Task reconciliation (handles app relaunch)
 
   /// Ensures exactly one in-flight (or completed) artifact per missing segment:
@@ -549,14 +701,8 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
       for (idx, range) in ranges.enumerated() {
         if FileManager.default.fileExists(atPath: state.segPath(idx)) { continue }
         if liveIndexes.contains(idx) { continue }
-        var req = URLRequest(url: url)
-        req.setValue("bytes=\(range.start)-\(range.end)", forHTTPHeaderField: "Range")
-        if let etag = state.etag { req.setValue(etag, forHTTPHeaderField: "If-Range") }
-        let task = session.downloadTask(with: req)
-        task.taskDescription = Self.encodeTaskDescription(
-          channel: state.channel, taskId: state.taskId, segIndex: idx
-        )
-        task.resume()
+        self.enqueueSegment(state: state, session: session, url: url,
+                            idx: idx, range: range)
       }
       // It's possible every segment was already present but the early
       // allSegmentsPresent check raced a just-finished task; re-check.
@@ -566,6 +712,247 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     }
   }
 
+  /// Creates and starts a single Range download task for [idx]. Factored out of
+  /// `reconcileAndStartTasks` so the delegate can re-enqueue ONE segment on a
+  /// transient failure (§5.4) without touching the others. Caller must ensure no
+  /// live task already exists for this index (double-enqueue guard).
+  private func enqueueSegment(state: RunState, session: URLSession, url: URL,
+                              idx: Int, range: (start: Int64, end: Int64)) {
+    var req = URLRequest(url: url)
+    req.setValue("bytes=\(range.start)-\(range.end)", forHTTPHeaderField: "Range")
+    if let etag = state.etag { req.setValue(etag, forHTTPHeaderField: "If-Range") }
+    let task = session.downloadTask(with: req)
+    task.taskDescription = Self.encodeTaskDescription(
+      channel: state.channel, taskId: state.taskId, segIndex: idx
+    )
+    // Reset this segment's progress estimate so a re-enqueued attempt doesn't
+    // double-count bytes from the failed attempt in the aggregate progress.
+    // §5.4 (G2): the real task now exists and is visible to `getAllTasks`, so
+    // clear the pending-retry marker — the in-flight check is authoritative again.
+    lock.lock()
+    if idx < state.segmentWritten.count { state.segmentWritten[idx] = 0 }
+    state.pendingRetryIndexes.remove(idx)
+    state.lastProgressAt = Date()
+    lock.unlock()
+    task.resume()
+  }
+
+  /// Marks a segment's finished body as a TRANSIENT HTTP outcome (§4) so
+  /// didCompleteWithError re-enqueues just that segment instead of failing the run.
+  private func markSegmentTransient(state: RunState, idx: Int, retryAfter: Double?) {
+    lock.lock()
+    state.transientSegmentRetryAfter[idx] = retryAfter
+    lock.unlock()
+  }
+
+  /// §5.4: re-enqueue a single transient-failed segment under its attempt budget,
+  /// with jittered exponential backoff (overridden by `Retry-After`). Returns true
+  /// when a retry was scheduled; false when the budget/deadline is exhausted (the
+  /// caller then finalizes the run as a resumable transient fallback). Must be
+  /// called from a delegate callback for [idx].
+  private func retrySegmentIfUnderBudget(state: RunState, idx: Int,
+                                         retryAfter: Double?) -> Bool {
+    // Deadline check first (§5.11 single-run bound).
+    if state.isPastDeadline { return false }
+    // §5.4 (G2): claim the pending-retry slot and bump the attempt counter under
+    // ONE lock hold. If a retry is already pending for this idx (its asyncAfter
+    // hasn't fired yet), a concurrent caller — e.g. a sibling segment's
+    // completion driving the missing-segment re-enqueue — must NOT bump the
+    // counter again nor arm a duplicate asyncAfter. Returning `true` here reports
+    // "a retry is in flight for this segment" without scheduling a second one.
+    let claim: (alreadyPending: Bool, attempts: Int) = lock.withLockValue {
+      if state.pendingRetryIndexes.contains(idx) {
+        return (true, state.segmentAttempts[idx] ?? 0)
+      }
+      let n = (state.segmentAttempts[idx] ?? 0) + 1
+      state.segmentAttempts[idx] = n
+      state.pendingRetryIndexes.insert(idx)
+      return (false, n)
+    }
+    if claim.alreadyPending { return true }
+    let attempts = claim.attempts
+    if attempts > state.maxSegmentAttempts {
+      // Over budget: release the slot we just claimed so a later genuine retry
+      // (if any) isn't blocked, and report exhausted.
+      lock.withLockValue { _ = state.pendingRetryIndexes.remove(idx) }
+      return false
+    }
+    guard let url = lock.withLockValue({ state.url }) else {
+      lock.withLockValue { _ = state.pendingRetryIndexes.remove(idx) }
+      return false
+    }
+    let ranges = lock.withLockValue { state.ranges }
+    guard idx < ranges.count else {
+      lock.withLockValue { _ = state.pendingRetryIndexes.remove(idx) }
+      return false
+    }
+    let range = ranges[idx]
+    let delay = RangeDownloadLogic.backoffDelay(attempt: attempts, retryAfter: retryAfter)
+    let session = session(forChannel: state.channel, segmentCount: state.segmentCount)
+    let channelStr = state.channel.stringValue
+    let taskId = state.taskId
+    OneKeyLog.info("RangeDownloader",
+                   "\(channelStr)/\(taskId): retry segment \(idx) attempt \(attempts)/\(state.maxSegmentAttempts) in \(String(format: "%.2f", delay))s")
+    DispatchQueue.global().asyncAfter(deadline: .now() + delay) { [weak self] in
+      guard let self = self else { return }
+      // Bail if the run was cleared (cancel / finalize) or the segment landed
+      // in the meantime, and guard against a double-enqueue. On every bail path
+      // clear the pending-retry marker (G2) so it doesn't leak: either the slot
+      // is moot (run gone / segment landed) or a real task already exists.
+      guard let live = self.run(forKey: Self.runKey(channel: state.channel, taskId: state.taskId)),
+            live === state else {
+        self.lock.withLockValue { _ = state.pendingRetryIndexes.remove(idx) }
+        return
+      }
+      if FileManager.default.fileExists(atPath: state.segPath(idx)) {
+        self.lock.withLockValue { _ = state.pendingRetryIndexes.remove(idx) }
+        return
+      }
+      session.getAllTasks { tasks in
+        let alreadyLive = tasks.contains { t in
+          guard let d = t.taskDescription,
+                let decoded = Self.decodeTaskDescription(d),
+                decoded.channel.stringValue == channelStr,
+                decoded.taskId == taskId,
+                decoded.segIndex == idx else { return false }
+          return t.state == .running || t.state == .suspended
+        }
+        if alreadyLive {
+          self.lock.withLockValue { _ = state.pendingRetryIndexes.remove(idx) }
+          return
+        }
+        // enqueueSegment clears the pending marker once the real task exists.
+        self.enqueueSegment(state: state, session: session, url: url,
+                            idx: idx, range: range)
+      }
+    }
+    return true
+  }
+
+  /// §4 (416): a segment got `416 Range Not Satisfiable`. Per §4 a bare 416 must
+  /// NOT discard resumable bytes and must NOT blindly re-request the same range —
+  /// the total/validator is re-evaluated first. We re-probe the URL:
+  ///   • Probe fails / range no longer supported → transient; retry the segment
+  ///     in place under budget (the network blip will clear), keeping `.segN`.
+  ///   • Total or ETag CHANGED → the object changed under us; the planned ranges
+  ///     are stale → object-change: wipe + restart (Permanent), so the run
+  ///     re-plans against the new object instead of stitching mismatched bytes.
+  ///   • Total/ETag UNCHANGED → the range is genuinely still valid (a transient
+  ///     server hiccup); keep `.segN` and retry the segment normally.
+  /// Must be called from a delegate callback for [idx]; runs the re-probe async.
+  private func reevaluateSizeThenRetry(state: RunState, session: URLSession,
+                                       idx: Int, retryAfter: Double?,
+                                       ranges: [(start: Int64, end: Int64)]) {
+    guard let url = lock.withLockValue({ state.url }) else {
+      finalizeTransientFallback(state: state, idx: idx,
+                                reason: "segment \(idx) 416 but url missing", ranges: ranges)
+      return
+    }
+    let priorTotal = lock.withLockValue { state.totalSize }
+    let priorEtag = lock.withLockValue { state.etag }
+    let channelStr = state.channel.stringValue
+    let taskId = state.taskId
+    OneKeyLog.info("RangeDownloader",
+                   "\(channelStr)/\(taskId): segment \(idx) 416 — re-evaluating size before retry")
+    Task { [weak self] in
+      guard let self = self else { return }
+      // Re-confirm the run is still live before acting on the re-probe.
+      let stillLive = self.run(forKey: Self.runKey(channel: state.channel, taskId: state.taskId)).map { $0 === state } ?? false
+      guard stillLive else { return }
+      let probe: ProbeResult
+      do {
+        probe = try await self.probe(url: url)
+      } catch {
+        // Re-probe itself failed → transient network condition. Retry the
+        // segment in place; the original range is unchanged and `.segN` is kept.
+        if self.retrySegmentIfUnderBudget(state: state, idx: idx, retryAfter: retryAfter) { return }
+        self.finalizeTransientFallback(state: state, idx: idx,
+                                       reason: "segment \(idx) 416; re-probe failed, retry budget exhausted",
+                                       ranges: ranges)
+        return
+      }
+      let totalChanged = !probe.supportsRange || probe.total != priorTotal
+      let etagChanged = (probe.etag?.isEmpty == false || priorEtag?.isEmpty == false)
+        && (probe.etag != priorEtag)
+      if totalChanged || etagChanged {
+        // §4: the object changed under us — the planned `.segN` ranges no longer
+        // describe this object. Object-change → wipe + restart (Permanent) so a
+        // fresh run re-plans; never stitch bytes from two different objects.
+        OneKeyLog.info("RangeDownloader",
+                       "\(channelStr)/\(taskId): segment \(idx) 416 → object changed (total \(priorTotal)→\(probe.total), etag \(priorEtag ?? "nil")→\(probe.etag ?? "nil")); wipe + restart")
+        self.lock.lock()
+        state.fellBack = true
+        state.fellBackKind = .multipartOrBadTotal
+        self.lock.unlock()
+        self.finalizePermanentFallback(state: state, session: session, ranges: ranges)
+        return
+      }
+      // Total/validator unchanged → the 416 was a transient server hiccup; the
+      // range is still valid. Keep `.segN` and retry this segment normally.
+      OneKeyLog.info("RangeDownloader",
+                     "\(channelStr)/\(taskId): segment \(idx) 416 → size unchanged (total \(priorTotal)); retrying range as-is")
+      if self.retrySegmentIfUnderBudget(state: state, idx: idx, retryAfter: retryAfter) { return }
+      self.finalizeTransientFallback(state: state, idx: idx,
+                                     reason: "segment \(idx) 416; size unchanged, retry budget exhausted",
+                                     ranges: ranges)
+    }
+  }
+
+  // backoffDelay (§5.4) now lives on `RangeDownloadLogic`.
+
+  // MARK: - Stall watchdog (§5.4)
+
+  /// Periodically checks whether the run has received any bytes within the stall
+  /// window. A stalled segment task is cancelled so didCompleteWithError routes it
+  /// through the in-place retry path. The watchdog stops itself when the run is no
+  /// longer live (finalized / cancelled). It is intentionally lenient: it only
+  /// fires when wall time since the last byte exceeds the window AND there is an
+  /// in-flight task, so a suspended background transfer (which makes no JS/main
+  /// progress while suspended) is not false-cancelled because the watchdog timer
+  /// itself is also suspended with the app.
+  private func startStallWatchdog(key: String, stallSeconds: Double) {
+    let interval = max(5.0, stallSeconds / 2.0)
+    DispatchQueue.global().asyncAfter(deadline: .now() + interval) { [weak self] in
+      self?.stallWatchdogTick(key: key, stallSeconds: stallSeconds, interval: interval)
+    }
+  }
+
+  private func stallWatchdogTick(key: String, stallSeconds: Double, interval: Double) {
+    guard let state = run(forKey: key),
+          lock.withLockValue({ state.continuation != nil }) else {
+      return // run finalized / cancelled — stop.
+    }
+    let last = lock.withLockValue { state.lastProgressAt }
+    let stalled = Date().timeIntervalSince(last) >= stallSeconds
+    if stalled {
+      let channelStr = state.channel.stringValue
+      let taskId = state.taskId
+      let session = session(forChannel: state.channel, segmentCount: state.segmentCount)
+      session.getAllTasks { tasks in
+        for t in tasks {
+          guard let d = t.taskDescription,
+                let decoded = Self.decodeTaskDescription(d),
+                decoded.channel.stringValue == channelStr,
+                decoded.taskId == taskId,
+                t.state == .running else { continue }
+          OneKeyLog.info("RangeDownloader",
+                         "\(channelStr)/\(taskId): stall watchdog cancelling segment \(decoded.segIndex) (no bytes for \(String(format: "%.0f", stallSeconds))s)")
+          // Mark this index as stall-cancelled so didCompleteWithError treats the
+          // resulting NSURLErrorCancelled as a transient stall, not a user cancel.
+          self.lock.lock(); state.stallCancelledIndexes.insert(decoded.segIndex); self.lock.unlock()
+          t.cancel()
+        }
+      }
+      // Re-stamp so we don't repeatedly cancel within the same window while the
+      // cancel + retry round-trips.
+      lock.lock(); state.lastProgressAt = Date(); lock.unlock()
+    }
+    // Reschedule.
+    DispatchQueue.global().asyncAfter(deadline: .now() + interval) { [weak self] in
+      self?.stallWatchdogTick(key: key, stallSeconds: stallSeconds, interval: interval)
+    }
+  }
+
   private func allSegmentsPresent(state: RunState,
                                   ranges: [(start: Int64, end: Int64)]) -> Bool {
     for (idx, range) in ranges.enumerated() {
@@ -589,12 +976,19 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
           let (state, idx) = run(for: desc) else { return }
     lock.lock()
     if idx < state.segmentWritten.count { state.segmentWritten[idx] = totalBytesWritten }
+    // §5.4: stamp last-progress for the stall watchdog. Any byte on any segment
+    // counts as the run making progress.
+    state.lastProgressAt = Date()
     let sum = state.segmentWritten.reduce(0, +)
     let total = state.totalSize
     var emit = false
     if total > 0 {
       let p = Int((sum * 100) / total)
-      if p != state.prevProgress { state.prevProgress = p; emit = true }
+      // §5.7 monotonic non-decreasing: only emit on a strict increase, so a
+      // transient re-enqueue (which resets segmentWritten[idx]=0 and dips the
+      // aggregate) never ticks the bar backward — prevProgress is the run's
+      // running max. A genuine restart resets prevProgress separately.
+      if p > state.prevProgress { state.prevProgress = p; emit = true }
     }
     let progressValue = total > 0 ? Int((sum * 100) / total) : 0
     let channel = state.channel
@@ -616,28 +1010,59 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     let expectedLen = range.end - range.start + 1
 
     // We require a 206 Partial Content that matches the requested byte range.
-    // Anything else — 200 (Range ignored / ETag changed) or an out-of-range
-    // Content-Range — means we cannot safely assemble this segment, so flag
-    // fallback; finalize happens in didCompleteWithError.
+    // Anything else is classified per §4: a Permanent status (200/401/403/404/
+    // 410/501/505/other-4xx) flags the whole run for discard+single-stream; a
+    // Transient status (408/416/429/5xx) marks just THIS segment for in-place
+    // retry (G2) and keeps the other segments / `.segN`. Finalize/retry happens
+    // in didCompleteWithError.
     guard let http = downloadTask.response as? HTTPURLResponse else {
-      lock.lock(); state.fellBack = true; lock.unlock()
+      // No HTTP response on a finished body is anomalous → treat as transient.
+      markSegmentTransient(state: state, idx: idx, retryAfter: nil)
       return
     }
     if http.statusCode != 206 {
-      lock.lock(); state.fellBack = true; lock.unlock()
+      let kind = RangeDownloadLogic.classifyStatus(http.statusCode)
+      if kind.failureClass == .fallbackTransient {
+        // §4 (416): a 416 is transient but the requested range may no longer be
+        // satisfiable (the object shrank/changed). Flag this segment for a size
+        // re-evaluation (re-probe) BEFORE the range is re-requested, instead of
+        // blindly re-asking for the same bytes.
+        if http.statusCode == 416 {
+          lock.lock(); state.sizeReevalIndexes.insert(idx); lock.unlock()
+        }
+        let retryAfter = RangeDownloadLogic.parseRetryAfterSeconds(
+          http.value(forHTTPHeaderField: "Retry-After"))
+        markSegmentTransient(state: state, idx: idx, retryAfter: retryAfter)
+      } else {
+        lock.lock(); state.fellBack = true; state.fellBackKind = kind; lock.unlock()
+      }
+      return
+    }
+    // §5.5: reject multipart/byteranges — we requested exactly one range and can
+    // only assemble a single contiguous body per segment.
+    if let ctype = http.value(forHTTPHeaderField: "Content-Type")?.lowercased(),
+       ctype.contains("multipart/byteranges") {
+      lock.lock(); state.fellBack = true; state.fellBackKind = .multipartOrBadTotal; lock.unlock()
       return
     }
     // Verify the server's Content-Range start/end matches what we asked for so a
-    // stashed `.segN` can't be a slice of a different object/range.
+    // stashed `.segN` can't be a slice of a different object/range; and (§5.5)
+    // verify the total matches the probe total (reject absent / `*` / mismatch).
     if let cr = http.value(forHTTPHeaderField: "Content-Range") {
-      guard let parsed = Self.parseContentRangeBounds(cr),
+      guard let parsed = RangeDownloadLogic.parseContentRangeBounds(cr),
             parsed.start == range.start, parsed.end == range.end else {
-        lock.lock(); state.fellBack = true; lock.unlock()
+        lock.lock(); state.fellBack = true; state.fellBackKind = .multipartOrBadTotal; lock.unlock()
+        return
+      }
+      let expectedTotal = lock.withLockValue { state.totalSize }
+      guard let total = RangeDownloadLogic.parseContentRangeTotal(cr), total == expectedTotal else {
+        // Absent / `*` / disagreeing total → the object changed or is non-conforming.
+        lock.lock(); state.fellBack = true; state.fellBackKind = .multipartOrBadTotal; lock.unlock()
         return
       }
     } else {
       // 206 without a Content-Range header is non-conforming — don't trust it.
-      lock.lock(); state.fellBack = true; lock.unlock()
+      lock.lock(); state.fellBack = true; state.fellBackKind = .multipartOrBadTotal; lock.unlock()
       return
     }
 
@@ -676,53 +1101,82 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
 
   public func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
     guard let desc = task.taskDescription,
-          let (state, _) = run(for: desc) else { return }
+          let (state, idx) = run(for: desc) else { return }
     let ranges = lock.withLockValue { state.ranges }
+
+    // A Permanent classification anywhere in the run (didFinishDownloadingTo set
+    // `fellBack`) wins over per-segment retries: discard and single-stream.
+    if lock.withLockValue({ state.fellBack }) {
+      finalizePermanentFallback(state: state, session: session, ranges: ranges)
+      return
+    }
+
     if let error = error {
-      // Background ignores user-cancels (e.g. our own fallback cancel below) —
-      // surface only genuine give-ups.
       let nsErr = error as NSError
       if nsErr.domain == NSURLErrorDomain && nsErr.code == NSURLErrorCancelled {
+        // Distinguish a stall-watchdog cancel (transient → retry this segment)
+        // from an external/user cancel or our own permanent-fallback sibling
+        // cancel (swallow). A genuine cancel never set stallCancelledIndexes.
+        let wasStall = lock.withLockValue { state.stallCancelledIndexes.remove(idx) != nil }
+        if wasStall {
+          if retrySegmentIfUnderBudget(state: state, idx: idx, retryAfter: nil) { return }
+          finalizeTransientFallback(state: state, idx: idx, reason: "segment \(idx) stalled; retry budget exhausted", ranges: ranges)
+        }
         return
       }
-      finishContinuation(state: state, with: error, ranges: ranges)
+      // §4: connection lost / timeout / DNS / TLS → Transient. Retry THIS segment
+      // in place under its budget; keep the others and their `.segN`.
+      if retrySegmentIfUnderBudget(state: state, idx: idx, retryAfter: nil) { return }
+      finalizeTransientFallback(state: state, idx: idx,
+                                reason: error.localizedDescription, ranges: ranges)
       return
     }
-    if lock.withLockValue({ state.fellBack }) {
-      // Abandon the other in-flight segment tasks for THIS run so they don't
-      // keep downloading after we've decided to fall back to single-stream.
-      let channel = state.channel
-      let taskId = state.taskId
-      session.getAllTasks { tasks in
-        for t in tasks {
-          if let d = t.taskDescription,
-             let decoded = Self.decodeTaskDescription(d),
-             decoded.channel.stringValue == channel.stringValue,
-             decoded.taskId == taskId {
-            t.cancel()
-          }
-        }
+
+    // §4: this segment's finished body was a Transient HTTP status (429/5xx/408/
+    // 416). Discard the body and re-enqueue just this segment under its budget.
+    let transientRetryAfter = lock.withLockValue { () -> (present: Bool, retryAfter: Double?) in
+      if let ra = state.transientSegmentRetryAfter[idx] {
+        state.transientSegmentRetryAfter.removeValue(forKey: idx)
+        return (true, ra)
       }
-      cleanupSegments(state: state, ranges: ranges)
-      finishContinuation(state: state,
-                         with: FallbackError(reason: "server returned 200 to a Range request"),
-                         ranges: ranges)
+      return (false, nil)
+    }
+    if transientRetryAfter.present {
+      // §4 (416): a 416 segment must re-evaluate the total/validator (re-probe)
+      // BEFORE re-requesting the same range. If the object changed → object-change
+      // (wipe + restart, Permanent); otherwise keep `.segN` and retry normally.
+      let needsSizeReeval = lock.withLockValue { state.sizeReevalIndexes.remove(idx) != nil }
+      if needsSizeReeval {
+        reevaluateSizeThenRetry(state: state, session: session, idx: idx,
+                                retryAfter: transientRetryAfter.retryAfter, ranges: ranges)
+        return
+      }
+      if retrySegmentIfUnderBudget(state: state, idx: idx, retryAfter: transientRetryAfter.retryAfter) { return }
+      finalizeTransientFallback(state: state, idx: idx,
+                                reason: "segment \(idx) throttled/5xx; retry budget exhausted", ranges: ranges)
       return
     }
+
     // A segment failed to stash (move/size-check failure in didFinishDownloadingTo).
-    // That segment will never appear, so finalize terminally instead of waiting.
-    if let stashErr = lock.withLockValue({ state.stashError }) {
-      finishContinuation(state: state, with: stashErr, ranges: ranges)
+    // A short/truncated body is transient (the bytes will be re-fetched), so retry
+    // this segment under budget rather than failing the whole run.
+    if lock.withLockValue({ state.stashError }) != nil {
+      lock.lock(); state.stashError = nil; lock.unlock()
+      if retrySegmentIfUnderBudget(state: state, idx: idx, retryAfter: nil) { return }
+      finalizeTransientFallback(state: state, idx: idx,
+                                reason: "segment \(idx) could not be stashed; retry budget exhausted", ranges: ranges)
       return
     }
+
     if allSegmentsPresent(state: state, ranges: ranges) {
       finishContinuation(state: state, with: nil, ranges: ranges)
       return
     }
     // This task finished error==nil but not all segments are present. If any
-    // tasks for THIS run are still in flight, wait for their completions.
-    // Otherwise nothing will ever resume the continuation — finalize with a
-    // descriptive terminal error so the JS promise resolves (as fallback).
+    // tasks for THIS run are still in flight (or a backoff retry is pending),
+    // wait. Otherwise re-enqueue the missing segment(s) under budget; only when a
+    // segment's budget/deadline is exhausted do we finalize as a resumable
+    // transient fallback (keeping `.segN`).
     let channel = state.channel
     let taskId = state.taskId
     session.getAllTasks { [weak self] tasks in
@@ -735,18 +1189,100 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
         return t.state == .running || t.state == .suspended
       }
       if stillInFlight { return }
+      // §5.4 (G2): a backoff retry pending for ANY missing segment has no live
+      // task (it's a delayed asyncAfter), so it's invisible to `getAllTasks`
+      // above. If one is pending, that scheduled retry will re-drive completion;
+      // bail now rather than double-incrementing its attempt counter and arming
+      // a duplicate retry.
+      let pendingRetry = self.lock.withLockValue { !state.pendingRetryIndexes.isEmpty }
+      if pendingRetry { return }
       // Re-check under no-in-flight: a just-finished stash may have completed.
       if self.allSegmentsPresent(state: state, ranges: ranges) {
         self.finishContinuation(state: state, with: nil, ranges: ranges)
         return
       }
-      let missing = ranges.indices.first {
-        !FileManager.default.fileExists(atPath: state.segPath($0))
+      // Re-enqueue every missing segment that still has budget. `retrySegmentIf
+      // UnderBudget` itself gates on `pendingRetryIndexes`, so a segment already
+      // mid-backoff is reported as "in flight" (true) and never re-armed (G2).
+      var anyRetryScheduled = false
+      var exhaustedIdx: Int?
+      for mIdx in ranges.indices
+      where !FileManager.default.fileExists(atPath: state.segPath(mIdx)) {
+        if self.retrySegmentIfUnderBudget(state: state, idx: mIdx, retryAfter: nil) {
+          anyRetryScheduled = true
+        } else if exhaustedIdx == nil {
+          exhaustedIdx = mIdx
+        }
       }
-      let reason = "segment \(missing.map(String.init) ?? "?") missing/truncated after completion"
-      self.finishContinuation(state: state,
-                              with: FallbackError(reason: reason),
-                              ranges: ranges)
+      if anyRetryScheduled { return }
+      let missing = exhaustedIdx
+        ?? ranges.indices.first { !FileManager.default.fileExists(atPath: state.segPath($0)) }
+      self.finalizeTransientFallback(
+        state: state, idx: missing ?? 0,
+        reason: "segment \(missing.map(String.init) ?? "?") missing/truncated; retry budget exhausted",
+        ranges: ranges)
+    }
+  }
+
+  /// §4 Permanent: abandon sibling tasks, discard `.segN`, finalize the run with a
+  /// Permanent fallback carrying the run's classified kind.
+  private func finalizePermanentFallback(state: RunState, session: URLSession,
+                                         ranges: [(start: Int64, end: Int64)]) {
+    let channel = state.channel
+    let taskId = state.taskId
+    let kind = lock.withLockValue { state.fellBackKind }
+    session.getAllTasks { tasks in
+      for t in tasks {
+        if let d = t.taskDescription,
+           let decoded = Self.decodeTaskDescription(d),
+           decoded.channel.stringValue == channel.stringValue,
+           decoded.taskId == taskId {
+          t.cancel()
+        }
+      }
+    }
+    cleanupSegments(state: state, ranges: ranges)
+    let reason: String
+    switch kind {
+    case .serverIgnoredRange: reason = "server returned 200 to a Range request"
+    case .multipartOrBadTotal: reason = "non-conforming 206 (multipart / range / total mismatch)"
+    case .authExpired: reason = "auth expired (401/403); fetch a fresh signed URL"
+    case .notFound: reason = "object not found (404/410)"
+    case .redirectRejected: reason = "rejected non-HTTPS redirect"
+    case .rangeUnsupported: reason = "range unsupported / non-retryable status"
+    case .checksumMismatch: reason = "whole-file checksum mismatch"
+    case .transientNetwork, .throttled, .budgetExhausted: reason = "permanent fallback"
+    }
+    finishContinuation(state: state, with: FallbackError(reason: reason, kind: kind), ranges: ranges)
+  }
+
+  /// §4 Transient: finalize the run as a RESUMABLE fallback. `.segN` files are
+  /// intentionally KEPT so the next concurrent attempt resumes only the missing
+  /// segment(s); never restart from byte 0 while resumable bytes exist.
+  private func finalizeTransientFallback(state: RunState, idx: Int, reason: String,
+                                         ranges: [(start: Int64, end: Int64)]) {
+    finishContinuation(state: state,
+                       with: FallbackError(reason: reason, kind: .budgetExhausted),
+                       ranges: ranges)
+  }
+
+  /// §5.9: HTTPS-only on every redirect hop. A redirect to a non-HTTPS URL is
+  /// rejected (Permanent, `redirectRejected`). Passing `nil` to the completion
+  /// handler cancels the redirect; the task then completes with an error which
+  /// our run classification turns into a Permanent fallback (we pre-mark the run
+  /// so didCompleteWithError doesn't misread the cancel as transient).
+  public func urlSession(_ session: URLSession, task: URLSessionTask,
+                         willPerformHTTPRedirection response: HTTPURLResponse,
+                         newRequest request: URLRequest,
+                         completionHandler: @escaping (URLRequest?) -> Void) {
+    if request.url?.scheme?.lowercased() != "https" {
+      OneKeyLog.error("RangeDownloader", "blocked redirect to non-HTTPS URL")
+      if let desc = task.taskDescription, let (state, _) = run(for: desc) {
+        lock.lock(); state.fellBack = true; state.fellBackKind = .redirectRejected; lock.unlock()
+      }
+      completionHandler(nil)
+    } else {
+      completionHandler(request)
     }
   }
 
@@ -856,6 +1392,22 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     discardArtifacts(filePath: filePath)
   }
 
+  /// True when at least one concurrent segment artifact survives for this file.
+  ///
+  /// The downloader cleans its `.segN` files itself on every *permanent*
+  /// fallback (server returned 200 → `cleanupSegments` in didCompleteWithError;
+  /// SHA mismatch → cleanup in concatenateAndFinish; Range unsupported → nothing
+  /// was ever stashed) and deliberately RETAINS them on a *transient* one (a
+  /// suspend/network drop that left "segment N missing/truncated"). So a
+  /// surviving `.segN` is a reliable signal that the fallback is resumable —
+  /// the caller uses it to avoid deleting bytes a later attempt can resume.
+  public func hasArtifacts(filePath: String) -> Bool {
+    for idx in 0..<Self.defaultSegmentCount {
+      if FileManager.default.fileExists(atPath: "\(filePath).seg\(idx)") { return true }
+    }
+    return false
+  }
+
   /// Discards all segment artifacts (used by the caller when falling back to
   /// single-stream so the bare slot is clean). Prefer `cancel(...)` when tasks
   /// may still be in flight; this file-only delete is for the post-fallback
@@ -869,23 +1421,7 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
 
   // MARK: - SHA256 (streaming backstop)
 
-  static func calculateSHA256(_ filePath: String) -> String? {
-    let fm = FileManager.default
-    guard fm.fileExists(atPath: filePath),
-          let fileHandle = FileHandle(forReadingAtPath: filePath) else { return nil }
-    defer { try? fileHandle.close() }
-    var context = CC_SHA256_CTX()
-    CC_SHA256_Init(&context)
-    while autoreleasepool(invoking: { () -> Bool in
-      let data = fileHandle.readData(ofLength: 8192)
-      if data.isEmpty { return false }
-      data.withUnsafeBytes { CC_SHA256_Update(&context, $0.baseAddress, CC_LONG(data.count)) }
-      return true
-    }) {}
-    var hash = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
-    CC_SHA256_Final(&hash, &context)
-    return hash.map { String(format: "%02x", $0) }.joined()
-  }
+  // calculateSHA256 (§5.5) now lives on `RangeDownloadLogic`.
 }
 
 private extension NSLock {