@onekeyfe/react-native-range-downloader 3.0.67 → 3.0.69

package/nitrogen/generated/ios/swift/RangeFallbackKind.swift

@@ -0,0 +1,72 @@
+///
+/// RangeFallbackKind.swift
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+/**
+ * Represents the JS union `RangeFallbackKind`, backed by a C++ enum.
+ */
+public typealias RangeFallbackKind = margelo.nitro.reactnativerangedownloader.RangeFallbackKind
+
+public extension RangeFallbackKind {
+  /**
+   * Get a RangeFallbackKind for the given String value, or
+   * return `nil` if the given value was invalid/unknown.
+   */
+  init?(fromString string: String) {
+    switch string {
+      case "serverIgnoredRange":
+        self = .serverignoredrange
+      case "rangeUnsupported":
+        self = .rangeunsupported
+      case "authExpired":
+        self = .authexpired
+      case "notFound":
+        self = .notfound
+      case "redirectRejected":
+        self = .redirectrejected
+      case "checksumMismatch":
+        self = .checksummismatch
+      case "multipartOrBadTotal":
+        self = .multipartorbadtotal
+      case "transientNetwork":
+        self = .transientnetwork
+      case "throttled":
+        self = .throttled
+      case "budgetExhausted":
+        self = .budgetexhausted
+      default:
+        return nil
+    }
+  }
+
+  /**
+   * Get the String value this RangeFallbackKind represents.
+   */
+  var stringValue: String {
+    switch self {
+      case .serverignoredrange:
+        return "serverIgnoredRange"
+      case .rangeunsupported:
+        return "rangeUnsupported"
+      case .authexpired:
+        return "authExpired"
+      case .notfound:
+        return "notFound"
+      case .redirectrejected:
+        return "redirectRejected"
+      case .checksummismatch:
+        return "checksumMismatch"
+      case .multipartorbadtotal:
+        return "multipartOrBadTotal"
+      case .transientnetwork:
+        return "transientNetwork"
+      case .throttled:
+        return "throttled"
+      case .budgetexhausted:
+        return "budgetExhausted"
+    }
+  }
+}

package/nitrogen/generated/shared/c++/RangeDownloadOutcome.hpp

@@ -30,7 +30,9 @@ namespace margelo::nitro::reactnativerangedownloader {
    */
   enum class RangeDownloadOutcome {
     COMPLETED      SWIFT_NAME(completed) = 0,
-    FALLBACK      SWIFT_NAME(fallback) = 1,
+    FALLBACKTRANSIENT      SWIFT_NAME(fallbacktransient) = 1,
+    FALLBACKPERMANENT      SWIFT_NAME(fallbackpermanent) = 2,
+    FALLBACK      SWIFT_NAME(fallback) = 3,
   } CLOSED_ENUM;
 
 } // namespace margelo::nitro::reactnativerangedownloader
@@ -44,6 +46,8 @@ namespace margelo::nitro {
       std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
       switch (hashString(unionValue.c_str(), unionValue.size())) {
         case hashString("completed"): return margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome::COMPLETED;
+        case hashString("fallbackTransient"): return margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome::FALLBACKTRANSIENT;
+        case hashString("fallbackPermanent"): return margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome::FALLBACKPERMANENT;
         case hashString("fallback"): return margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome::FALLBACK;
         default: [[unlikely]]
           throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum RangeDownloadOutcome - invalid value!");
@@ -52,6 +56,8 @@ namespace margelo::nitro {
     static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome arg) {
       switch (arg) {
         case margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome::COMPLETED: return JSIConverter<std::string>::toJSI(runtime, "completed");
+        case margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome::FALLBACKTRANSIENT: return JSIConverter<std::string>::toJSI(runtime, "fallbackTransient");
+        case margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome::FALLBACKPERMANENT: return JSIConverter<std::string>::toJSI(runtime, "fallbackPermanent");
         case margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome::FALLBACK: return JSIConverter<std::string>::toJSI(runtime, "fallback");
         default: [[unlikely]]
           throw std::invalid_argument("Cannot convert RangeDownloadOutcome to JS - invalid value: "
@@ -65,6 +71,8 @@ namespace margelo::nitro {
       std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
       switch (hashString(unionValue.c_str(), unionValue.size())) {
         case hashString("completed"):
+        case hashString("fallbackTransient"):
+        case hashString("fallbackPermanent"):
         case hashString("fallback"):
           return true;
         default:

package/nitrogen/generated/shared/c++/RangeDownloadParams.hpp

@@ -44,10 +44,14 @@ namespace margelo::nitro::reactnativerangedownloader {
     std::optional<std::string> expectedSha256     SWIFT_PRIVATE;
     std::optional<double> segmentCount     SWIFT_PRIVATE;
     std::optional<double> minConcurrentBytes     SWIFT_PRIVATE;
+    std::optional<double> maxSegmentAttempts     SWIFT_PRIVATE;
+    std::optional<double> requestTimeoutSeconds     SWIFT_PRIVATE;
+    std::optional<double> stallTimeoutSeconds     SWIFT_PRIVATE;
+    std::optional<double> overallDeadlineSeconds     SWIFT_PRIVATE;
 
   public:
     RangeDownloadParams() = default;
-    explicit RangeDownloadParams(DownloadChannel channel, std::string taskId, std::string url, std::string destFilePath, std::optional<std::string> expectedSha256, std::optional<double> segmentCount, std::optional<double> minConcurrentBytes): channel(channel), taskId(taskId), url(url), destFilePath(destFilePath), expectedSha256(expectedSha256), segmentCount(segmentCount), minConcurrentBytes(minConcurrentBytes) {}
+    explicit RangeDownloadParams(DownloadChannel channel, std::string taskId, std::string url, std::string destFilePath, std::optional<std::string> expectedSha256, std::optional<double> segmentCount, std::optional<double> minConcurrentBytes, std::optional<double> maxSegmentAttempts, std::optional<double> requestTimeoutSeconds, std::optional<double> stallTimeoutSeconds, std::optional<double> overallDeadlineSeconds): channel(channel), taskId(taskId), url(url), destFilePath(destFilePath), expectedSha256(expectedSha256), segmentCount(segmentCount), minConcurrentBytes(minConcurrentBytes), maxSegmentAttempts(maxSegmentAttempts), requestTimeoutSeconds(requestTimeoutSeconds), stallTimeoutSeconds(stallTimeoutSeconds), overallDeadlineSeconds(overallDeadlineSeconds) {}
   };
 
 } // namespace margelo::nitro::reactnativerangedownloader
@@ -66,7 +70,11 @@ namespace margelo::nitro {
         JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, "destFilePath")),
         JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, "expectedSha256")),
         JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, "segmentCount")),
-        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, "minConcurrentBytes"))
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, "minConcurrentBytes")),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, "maxSegmentAttempts")),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, "requestTimeoutSeconds")),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, "stallTimeoutSeconds")),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, "overallDeadlineSeconds"))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::reactnativerangedownloader::RangeDownloadParams& arg) {
@@ -78,6 +86,10 @@ namespace margelo::nitro {
       obj.setProperty(runtime, "expectedSha256", JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.expectedSha256));
       obj.setProperty(runtime, "segmentCount", JSIConverter<std::optional<double>>::toJSI(runtime, arg.segmentCount));
       obj.setProperty(runtime, "minConcurrentBytes", JSIConverter<std::optional<double>>::toJSI(runtime, arg.minConcurrentBytes));
+      obj.setProperty(runtime, "maxSegmentAttempts", JSIConverter<std::optional<double>>::toJSI(runtime, arg.maxSegmentAttempts));
+      obj.setProperty(runtime, "requestTimeoutSeconds", JSIConverter<std::optional<double>>::toJSI(runtime, arg.requestTimeoutSeconds));
+      obj.setProperty(runtime, "stallTimeoutSeconds", JSIConverter<std::optional<double>>::toJSI(runtime, arg.stallTimeoutSeconds));
+      obj.setProperty(runtime, "overallDeadlineSeconds", JSIConverter<std::optional<double>>::toJSI(runtime, arg.overallDeadlineSeconds));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -95,6 +107,10 @@ namespace margelo::nitro {
       if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, "expectedSha256"))) return false;
       if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, "segmentCount"))) return false;
       if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, "minConcurrentBytes"))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, "maxSegmentAttempts"))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, "requestTimeoutSeconds"))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, "stallTimeoutSeconds"))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, "overallDeadlineSeconds"))) return false;
       return true;
     }
   };

package/nitrogen/generated/shared/c++/RangeDownloadResult.hpp

@@ -25,10 +25,13 @@
 
 // Forward declaration of `RangeDownloadOutcome` to properly resolve imports.
 namespace margelo::nitro::reactnativerangedownloader { enum class RangeDownloadOutcome; }
+// Forward declaration of `RangeFallbackKind` to properly resolve imports.
+namespace margelo::nitro::reactnativerangedownloader { enum class RangeFallbackKind; }
 
 #include "RangeDownloadOutcome.hpp"
 #include <string>
 #include <optional>
+#include "RangeFallbackKind.hpp"
 
 namespace margelo::nitro::reactnativerangedownloader {
 
@@ -40,10 +43,11 @@ namespace margelo::nitro::reactnativerangedownloader {
     RangeDownloadOutcome outcome     SWIFT_PRIVATE;
     std::string filePath     SWIFT_PRIVATE;
     std::optional<std::string> fallbackReason     SWIFT_PRIVATE;
+    std::optional<RangeFallbackKind> fallbackKind     SWIFT_PRIVATE;
 
   public:
     RangeDownloadResult() = default;
-    explicit RangeDownloadResult(RangeDownloadOutcome outcome, std::string filePath, std::optional<std::string> fallbackReason): outcome(outcome), filePath(filePath), fallbackReason(fallbackReason) {}
+    explicit RangeDownloadResult(RangeDownloadOutcome outcome, std::string filePath, std::optional<std::string> fallbackReason, std::optional<RangeFallbackKind> fallbackKind): outcome(outcome), filePath(filePath), fallbackReason(fallbackReason), fallbackKind(fallbackKind) {}
   };
 
 } // namespace margelo::nitro::reactnativerangedownloader
@@ -58,7 +62,8 @@ namespace margelo::nitro {
       return margelo::nitro::reactnativerangedownloader::RangeDownloadResult(
         JSIConverter<margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome>::fromJSI(runtime, obj.getProperty(runtime, "outcome")),
         JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, "filePath")),
-        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, "fallbackReason"))
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, "fallbackReason")),
+        JSIConverter<std::optional<margelo::nitro::reactnativerangedownloader::RangeFallbackKind>>::fromJSI(runtime, obj.getProperty(runtime, "fallbackKind"))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::reactnativerangedownloader::RangeDownloadResult& arg) {
@@ -66,6 +71,7 @@ namespace margelo::nitro {
       obj.setProperty(runtime, "outcome", JSIConverter<margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome>::toJSI(runtime, arg.outcome));
       obj.setProperty(runtime, "filePath", JSIConverter<std::string>::toJSI(runtime, arg.filePath));
       obj.setProperty(runtime, "fallbackReason", JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.fallbackReason));
+      obj.setProperty(runtime, "fallbackKind", JSIConverter<std::optional<margelo::nitro::reactnativerangedownloader::RangeFallbackKind>>::toJSI(runtime, arg.fallbackKind));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -79,6 +85,7 @@ namespace margelo::nitro {
       if (!JSIConverter<margelo::nitro::reactnativerangedownloader::RangeDownloadOutcome>::canConvert(runtime, obj.getProperty(runtime, "outcome"))) return false;
       if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, "filePath"))) return false;
       if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, "fallbackReason"))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::reactnativerangedownloader::RangeFallbackKind>>::canConvert(runtime, obj.getProperty(runtime, "fallbackKind"))) return false;
       return true;
     }
   };

package/nitrogen/generated/shared/c++/RangeFallbackKind.hpp

@@ -0,0 +1,108 @@
+///
+/// RangeFallbackKind.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+namespace margelo::nitro::reactnativerangedownloader {
+
+  /**
+   * An enum which can be represented as a JavaScript union (RangeFallbackKind).
+   */
+  enum class RangeFallbackKind {
+    SERVERIGNOREDRANGE      SWIFT_NAME(serverignoredrange) = 0,
+    RANGEUNSUPPORTED      SWIFT_NAME(rangeunsupported) = 1,
+    AUTHEXPIRED      SWIFT_NAME(authexpired) = 2,
+    NOTFOUND      SWIFT_NAME(notfound) = 3,
+    REDIRECTREJECTED      SWIFT_NAME(redirectrejected) = 4,
+    CHECKSUMMISMATCH      SWIFT_NAME(checksummismatch) = 5,
+    MULTIPARTORBADTOTAL      SWIFT_NAME(multipartorbadtotal) = 6,
+    TRANSIENTNETWORK      SWIFT_NAME(transientnetwork) = 7,
+    THROTTLED      SWIFT_NAME(throttled) = 8,
+    BUDGETEXHAUSTED      SWIFT_NAME(budgetexhausted) = 9,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::reactnativerangedownloader
+
+namespace margelo::nitro {
+
+  // C++ RangeFallbackKind <> JS RangeFallbackKind (union)
+  template <>
+  struct JSIConverter<margelo::nitro::reactnativerangedownloader::RangeFallbackKind> final {
+    static inline margelo::nitro::reactnativerangedownloader::RangeFallbackKind fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("serverIgnoredRange"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::SERVERIGNOREDRANGE;
+        case hashString("rangeUnsupported"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::RANGEUNSUPPORTED;
+        case hashString("authExpired"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::AUTHEXPIRED;
+        case hashString("notFound"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::NOTFOUND;
+        case hashString("redirectRejected"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::REDIRECTREJECTED;
+        case hashString("checksumMismatch"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::CHECKSUMMISMATCH;
+        case hashString("multipartOrBadTotal"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::MULTIPARTORBADTOTAL;
+        case hashString("transientNetwork"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::TRANSIENTNETWORK;
+        case hashString("throttled"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::THROTTLED;
+        case hashString("budgetExhausted"): return margelo::nitro::reactnativerangedownloader::RangeFallbackKind::BUDGETEXHAUSTED;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum RangeFallbackKind - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::reactnativerangedownloader::RangeFallbackKind arg) {
+      switch (arg) {
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::SERVERIGNOREDRANGE: return JSIConverter<std::string>::toJSI(runtime, "serverIgnoredRange");
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::RANGEUNSUPPORTED: return JSIConverter<std::string>::toJSI(runtime, "rangeUnsupported");
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::AUTHEXPIRED: return JSIConverter<std::string>::toJSI(runtime, "authExpired");
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::NOTFOUND: return JSIConverter<std::string>::toJSI(runtime, "notFound");
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::REDIRECTREJECTED: return JSIConverter<std::string>::toJSI(runtime, "redirectRejected");
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::CHECKSUMMISMATCH: return JSIConverter<std::string>::toJSI(runtime, "checksumMismatch");
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::MULTIPARTORBADTOTAL: return JSIConverter<std::string>::toJSI(runtime, "multipartOrBadTotal");
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::TRANSIENTNETWORK: return JSIConverter<std::string>::toJSI(runtime, "transientNetwork");
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::THROTTLED: return JSIConverter<std::string>::toJSI(runtime, "throttled");
+        case margelo::nitro::reactnativerangedownloader::RangeFallbackKind::BUDGETEXHAUSTED: return JSIConverter<std::string>::toJSI(runtime, "budgetExhausted");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert RangeFallbackKind to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("serverIgnoredRange"):
+        case hashString("rangeUnsupported"):
+        case hashString("authExpired"):
+        case hashString("notFound"):
+        case hashString("redirectRejected"):
+        case hashString("checksumMismatch"):
+        case hashString("multipartOrBadTotal"):
+        case hashString("transientNetwork"):
+        case hashString("throttled"):
+        case hashString("budgetExhausted"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-range-downloader",
-  "version": "3.0.67",
+  "version": "3.0.69",
   "description": "react-native-range-downloader",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/ReactNativeRangeDownloader.nitro.ts

@@ -14,16 +14,50 @@ export interface RangeDownloadParams {
   expectedSha256?: string; // optional: in-module post-download self-check; else caller verifies later
   segmentCount?: number; // default 8 (mirrors current behavior)
   minConcurrentBytes?: number; // default 2MB (below this falls straight back to single stream)
+  // OCDS §5.4: caller-tunable retry/backoff/deadline knobs. Defaults are platform
+  // configuration (filled in by the native module when omitted), not part of the
+  // standard. These let the OTA / APK / asset callers tune behavior per channel.
+  maxSegmentAttempts?: number; // per-segment transient retry budget within a single run (default 4)
+  requestTimeoutSeconds?: number; // connection/request timeout per segment task (default 60)
+  stallTimeoutSeconds?: number; // bytes-stalled (no-progress) watchdog window (default 30)
+  overallDeadlineSeconds?: number; // single-run wall-clock bound before giving up (default 0 = none)
 }
 
+// OCDS §4: the failure class is an EXPLICIT, typed outcome of the operation, never
+// inferred from incidental on-disk side effects (e.g. whether `.segN` survives).
+//   - `completed`         — destFilePath fully on disk (and expectedSha256, if passed, has passed)
+//   - `fallbackTransient` — concurrent path interrupted but RESUMABLE; segments kept; caller
+//                           should retry the concurrent path / keep its progress floor
+//   - `fallbackPermanent` — concurrency fundamentally unusable for this object; segments are
+//                           unsalvageable and have been discarded; caller restarts single-stream
+//   - `fallback`          — DEPRECATED legacy alias kept for wire/back-compat during the
+//                           transition; new callers consume the two typed classes above
 export type RangeDownloadOutcome =
-  | 'completed' // destFilePath fully on disk (and expectedSha256, if passed, has passed)
-  | 'fallback'; // concurrent unavailable, caller should run its own single-stream path
+  | 'completed'
+  | 'fallbackTransient'
+  | 'fallbackPermanent'
+  | 'fallback';
+
+// OCDS §4: optional sub-classification of a fallback, so the caller (and analytics)
+// can distinguish WHY the concurrent path was abandoned without parsing the reason
+// string. Present only when outcome is a fallback class.
+export type RangeFallbackKind =
+  | 'serverIgnoredRange' // server answered 200 to a Range request (Permanent)
+  | 'rangeUnsupported' // probe inconclusive / range not supported (Permanent)
+  | 'authExpired' // 401/403: signed URL dead; caller must fetch a fresh URL (Permanent)
+  | 'notFound' // 404/410: object gone (Permanent)
+  | 'redirectRejected' // non-HTTPS redirect rejected per §5.9 (Permanent)
+  | 'checksumMismatch' // whole-file checksum mismatch after assembly (Permanent)
+  | 'multipartOrBadTotal' // multipart/byteranges or Content-Range total disagrees (Permanent)
+  | 'transientNetwork' // connection lost / timeout / DNS / TLS / stall (Transient)
+  | 'throttled' // 429 / 5xx (except 501/505) (Transient)
+  | 'budgetExhausted'; // per-segment attempts / deadline exhausted while still resumable (Transient)
 
 export interface RangeDownloadResult {
   outcome: RangeDownloadOutcome;
   filePath: string;
   fallbackReason?: string; // filled when outcome=fallback (range unsupported / 200 / too small ...)
+  fallbackKind?: RangeFallbackKind; // typed sub-class of the fallback (see §4); omitted on completed
 }
 
 export interface RangeDownloadEvent {