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

package/android/src/test/java/com/margelo/nitro/reactnativerangedownloader/MonotonicProgressGateTest.kt

@@ -0,0 +1,368 @@
+package com.margelo.nitro.reactnativerangedownloader
+
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import java.io.File
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * Focused JVM unit coverage for the **MonotonicProgressGate** — the
+ * `AtomicInteger(-1)` + CAS emit-gating idiom the Nitro adapter
+ * ([ReactNativeRangeDownloader]) wraps around its concurrent progress callback.
+ *
+ * IMPORTANT: this gate is NOT a standalone extracted symbol — it is the inline
+ * adapter expression at `ReactNativeRangeDownloader.kt`:
+ *   - line 94:   `val lastProgress = java.util.concurrent.atomic.AtomicInteger(-1)`
+ *   - lines 104-105:
+ *       `val prev = lastProgress.get()`
+ *       `if (p > prev && lastProgress.compareAndSet(prev, p)) { …emit… }`
+ *
+ * So "driving the real code" here means driving the REAL JDK
+ * [java.util.concurrent.atomic.AtomicInteger] (the exact type the adapter
+ * holds) through the verbatim adapter expression. [tryAdvance] below is NOT a
+ * re-implementation of business logic — it is the literal `p > prev && CAS(prev,p)`
+ * line copied from the adapter, kept in one place so the concurrency tests can
+ * call it. The 0..100 clamp and the `total > 0` guard are the CALLER's job and
+ * live in [RangeDownloadLogic.progressPercent] (driven directly here too); the
+ * gate is purely "advance to a strictly-higher Int, lock-free".
+ *
+ * The RunRegistry / single-flight and segment-artifact-path assertions drive the
+ * genuinely-extracted [RangeDownloadLogic.runKey] and
+ * [RangeDownloadLogic.sweepPartialArtifacts] against a real [ConcurrentHashMap]
+ * (mirroring the adapter's `activeDownloads` put / `remove(key, value)` at lines
+ * 87 / 112). Pure JVM JUnit — no Nitro / HybridObject / Context, matching the
+ * established module pattern (see RangeDownloadLogicTest / IsPermanentHttpStatusTest).
+ */
+class MonotonicProgressGateTest {
+
+  private lateinit var tmpDir: File
+
+  @Before
+  fun setUp() {
+    tmpDir = File.createTempFile("crd-gate", "").let {
+      it.delete(); it.mkdirs(); it
+    }
+  }
+
+  @After
+  fun tearDown() {
+    tmpDir.deleteRecursively()
+  }
+
+  // The VERBATIM adapter gate expression (ReactNativeRangeDownloader.kt:104-105)
+  // driven against the REAL java.util.concurrent.atomic.AtomicInteger. Returns
+  // true iff `p` strictly exceeds the current max AND this thread won the CAS.
+  private fun tryAdvance(gate: AtomicInteger, p: Int): Boolean {
+    val prev = gate.get()
+    return p > prev && gate.compareAndSet(prev, p)
+  }
+
+  // ---- MonotonicProgressGate: single-threaded behavior ----
+
+  @Test
+  fun firstCallWithZeroAdvancesFromInitialMinusOne() {
+    // Initial state is -1 (adapter line 94), so the very first 0% must emit.
+    val gate = AtomicInteger(-1)
+    assertTrue("0 must beat the -1 initial and emit", tryAdvance(gate, 0))
+    assertEquals(0, gate.get())
+  }
+
+  @Test
+  fun ascendingZeroToHundredEveryCallEmits() {
+    val gate = AtomicInteger(-1)
+    for (p in 0..100) {
+      assertTrue("ascending $p must emit", tryAdvance(gate, p))
+      assertEquals(p, gate.get())
+    }
+    assertEquals(100, gate.get())
+  }
+
+  @Test
+  fun duplicateValueDoesNotReEmit() {
+    val gate = AtomicInteger(-1)
+    assertTrue("first 5 emits", tryAdvance(gate, 5))
+    assertFalse("equal value must NOT re-emit (strictly-greater only)", tryAdvance(gate, 5))
+    assertEquals("state unchanged on a no-emit", 5, gate.get())
+  }
+
+  @Test
+  fun outOfOrderLowerValueIsDroppedAndStateHolds() {
+    val gate = AtomicInteger(-1)
+    assertTrue("10 emits", tryAdvance(gate, 10))
+    assertFalse("a later 7 (< current max 10) must be dropped", tryAdvance(gate, 7))
+    assertEquals("state must stay at the high-water mark 10", 10, gate.get())
+    // And a subsequent strictly-higher value still advances normally.
+    assertTrue("11 still emits after a dropped 7", tryAdvance(gate, 11))
+    assertEquals(11, gate.get())
+  }
+
+  @Test
+  fun outOfOrderRepeatingStreamEmitsOnlyMonotonicHighWaterMarks() {
+    // Mirrors the real worker callback shape: out-of-order, repeating percentages.
+    val gate = AtomicInteger(-1)
+    val emitted = mutableListOf<Int>()
+    for (p in listOf(10, 10, 25, 25, 20, 50, 50, 49, 100, 100)) {
+      if (tryAdvance(gate, p)) emitted.add(p)
+    }
+    assertEquals(listOf(10, 25, 50, 100), emitted)
+    assertEquals(100, gate.get())
+  }
+
+  // ---- MonotonicProgressGate: concurrency (the load-bearing CAS contract) ----
+
+  @Test
+  fun concurrentSameTargetExactlyOneWinsCas() {
+    // K threads all try to advance -1 -> the SAME target. CAS guarantees exactly
+    // one winner; all losers see a no-emit; final state == that target.
+    val k = 64
+    val target = 42
+    val gate = AtomicInteger(-1)
+    val ready = CountDownLatch(k)
+    val go = CountDownLatch(1)
+    val wins = AtomicInteger(0)
+    val pool = Executors.newFixedThreadPool(k)
+    repeat(k) {
+      pool.submit {
+        ready.countDown()
+        go.await(5, TimeUnit.SECONDS)
+        if (tryAdvance(gate, target)) wins.incrementAndGet()
+      }
+    }
+    ready.await(5, TimeUnit.SECONDS)
+    go.countDown()
+    pool.shutdown()
+    assertTrue("workers must finish", pool.awaitTermination(10, TimeUnit.SECONDS))
+
+    assertEquals("exactly ONE thread may win the CAS to the same target", 1, wins.get())
+    assertEquals("state must equal the advanced target", target, gate.get())
+  }
+
+  @Test
+  fun concurrentRacingIncrementsEmitOncePerDistinctHighWaterUpdate() {
+    // Many threads each push the SAME ascending sequence 0..100 concurrently.
+    // The gate is lock-free + monotonic, so across ALL threads each distinct
+    // high-water value (0..100 -> 101 values) advances exactly once: total true
+    // returns == 101, regardless of thread count or interleaving. Final == 100.
+    val threads = 16
+    val maxPercent = 100
+    val gate = AtomicInteger(-1)
+    val totalWins = AtomicInteger(0)
+    val ready = CountDownLatch(threads)
+    val go = CountDownLatch(1)
+    val pool = Executors.newFixedThreadPool(threads)
+    repeat(threads) {
+      pool.submit {
+        ready.countDown()
+        go.await(5, TimeUnit.SECONDS)
+        for (p in 0..maxPercent) {
+          if (tryAdvance(gate, p)) totalWins.incrementAndGet()
+        }
+      }
+    }
+    ready.await(5, TimeUnit.SECONDS)
+    go.countDown()
+    pool.shutdown()
+    assertTrue("workers must finish", pool.awaitTermination(10, TimeUnit.SECONDS))
+
+    assertEquals(
+      "true returns must equal the count of distinct strictly-increasing updates (0..100)",
+      maxPercent + 1,
+      totalWins.get(),
+    )
+    assertEquals("final state must be the max seen", maxPercent, gate.get())
+  }
+
+  @Test
+  fun concurrentMonotonicityNeverObservesARegression() {
+    // Under concurrent advancement the gate must never let `get()` go backwards.
+    // An observer thread samples the gate while writers race it forward; every
+    // sample must be >= the previous sample.
+    val gate = AtomicInteger(-1)
+    val writers = 8
+    val maxPercent = 100
+    val ready = CountDownLatch(writers)
+    val go = CountDownLatch(1)
+    val regressionObserved = AtomicInteger(0)
+    val pool = Executors.newFixedThreadPool(writers + 1)
+
+    val observer = pool.submit {
+      var last = Int.MIN_VALUE
+      // Sample aggressively until the gate reaches the terminal value.
+      while (gate.get() < maxPercent) {
+        val now = gate.get()
+        if (now < last) regressionObserved.incrementAndGet()
+        last = now
+      }
+      if (gate.get() < last) regressionObserved.incrementAndGet()
+    }
+
+    repeat(writers) {
+      pool.submit {
+        ready.countDown()
+        go.await(5, TimeUnit.SECONDS)
+        for (p in 0..maxPercent) tryAdvance(gate, p)
+      }
+    }
+    ready.await(5, TimeUnit.SECONDS)
+    go.countDown()
+    observer.get(10, TimeUnit.SECONDS)
+    pool.shutdown()
+    assertTrue("workers must finish", pool.awaitTermination(10, TimeUnit.SECONDS))
+
+    assertEquals("observer must never see progress go backwards", 0, regressionObserved.get())
+    assertEquals(maxPercent, gate.get())
+  }
+
+  // ---- Caller-owned clamp/guard feeding the gate (RangeDownloadLogic.progressPercent) ----
+
+  @Test
+  fun callerClampAndGuardOwnTheZeroToHundredRangeNotTheGate() {
+    // total <= 0 yields no percentage at all (guarded by the caller), so the gate
+    // is never even consulted.
+    assertNull("non-positive total emits nothing", RangeDownloadLogic.progressPercent(10, 0))
+    assertNull(RangeDownloadLogic.progressPercent(10, -1))
+    // Over-100 transferred (momentary cross-segment overshoot) is clamped to 100
+    // BEFORE the gate, so the gate only ever sees values in 0..100.
+    assertEquals(100, RangeDownloadLogic.progressPercent(150, 100))
+    // The full pipeline: clamped percentages flow into the gate monotonically.
+    val gate = AtomicInteger(-1)
+    val emitted = mutableListOf<Int>()
+    for ((transferred, total) in listOf(0L to 100L, 50L to 100L, 49L to 100L, 150L to 100L)) {
+      val p = RangeDownloadLogic.progressPercent(transferred, total) ?: continue
+      if (tryAdvance(gate, p)) emitted.add(p)
+    }
+    assertEquals(listOf(0, 50, 100), emitted)
+  }
+
+  // ---- RunRegistry / single-flight (RangeDownloadLogic.runKey + activeDownloads map) ----
+
+  @Test
+  fun runKeyJoinsChannelAndTaskStablyAndCollisionFree() {
+    // Stable: same inputs -> same key.
+    assertEquals("MAIN|task-1", RangeDownloadLogic.runKey("MAIN", "task-1"))
+    assertEquals(
+      RangeDownloadLogic.runKey("MAIN", "task-1"),
+      RangeDownloadLogic.runKey("MAIN", "task-1"),
+    )
+    // Collision-free across channel and across taskId.
+    assertNotEquals(
+      RangeDownloadLogic.runKey("MAIN", "t"),
+      RangeDownloadLogic.runKey("OTHER", "t"),
+    )
+    assertNotEquals(
+      RangeDownloadLogic.runKey("MAIN", "a"),
+      RangeDownloadLogic.runKey("MAIN", "b"),
+    )
+  }
+
+  @Test
+  fun singleFlightRegistryDedupesSecondRegisterForSameKey() {
+    // Models the adapter's `activeDownloads[runKey] = handle` (line 87) single-flight
+    // map. putIfAbsent rejects a second register for the same key.
+    val registry = ConcurrentHashMap<String, Any>()
+    val key = RangeDownloadLogic.runKey("MAIN", "task-7")
+    val first = Any()
+    val second = Any()
+    assertNull("first register wins", registry.putIfAbsent(key, first))
+    assertTrue("second register for same key is rejected (returns the incumbent)",
+      registry.putIfAbsent(key, second) === first)
+    assertTrue("incumbent handle must remain", registry[key] === first)
+    // A different key (different taskId) co-exists, not deduped.
+    val otherKey = RangeDownloadLogic.runKey("MAIN", "task-8")
+    assertNull(registry.putIfAbsent(otherKey, second))
+    assertEquals(2, registry.size)
+  }
+
+  @Test
+  fun cancelRemovesOnlyTheMatchingHandleNotAConcurrentReplacement() {
+    // Mirrors `activeDownloads.remove(runKey, cancelHandle)` (line 112): the
+    // value-conditional remove only clears OUR handle, so a concurrent cancel that
+    // already replaced the handle for the same key is left intact.
+    val registry = ConcurrentHashMap<String, Any>()
+    val key = RangeDownloadLogic.runKey("MAIN", "task-9")
+    val ours = Any()
+    val replacement = Any()
+    registry[key] = ours
+    // Simulate a concurrent cancel replacing the handle under the same key.
+    registry[key] = replacement
+    // Our finally-block remove must NOT evict the replacement.
+    assertFalse("value-conditional remove must not evict a replaced handle",
+      registry.remove(key, ours))
+    assertTrue("replacement handle survives", registry[key] === replacement)
+    // Removing the actual current value succeeds and clears the key.
+    assertTrue(registry.remove(key, replacement))
+    assertNull(registry[key])
+  }
+
+  @Test
+  fun concurrentRegistersForSameKeyOnlyOneWins() {
+    val registry = ConcurrentHashMap<String, Any>()
+    val key = RangeDownloadLogic.runKey("MAIN", "race")
+    val k = 32
+    val winners = AtomicInteger(0)
+    val ready = CountDownLatch(k)
+    val go = CountDownLatch(1)
+    val pool = Executors.newFixedThreadPool(k)
+    repeat(k) {
+      pool.submit {
+        val mine = Any()
+        ready.countDown()
+        go.await(5, TimeUnit.SECONDS)
+        if (registry.putIfAbsent(key, mine) == null) winners.incrementAndGet()
+      }
+    }
+    ready.await(5, TimeUnit.SECONDS)
+    go.countDown()
+    pool.shutdown()
+    assertTrue(pool.awaitTermination(10, TimeUnit.SECONDS))
+    assertEquals("exactly one concurrent register may win the single-flight slot", 1, winners.get())
+    assertEquals(1, registry.size)
+  }
+
+  // ---- segment artifact paths / sweep (RangeDownloadLogic.sweepPartialArtifacts) ----
+
+  @Test
+  fun segmentArtifactPathsAreDotSegNUnderTheDotPartialPrefix() {
+    // Drive the REAL sweep: it deletes `<dest>.partial` + every
+    // `<dest>.partial.seg<N>` matched by filename prefix, for ANY segment count.
+    val dest = File(tmpDir, "asset.bin").absolutePath
+    val partial = File("$dest.partial").apply { writeText("p") }
+    val count = 8
+    val segs = (0 until count).map { File("$dest.partial.seg$it").apply { writeText("$it") } }
+    // Verify the path shape the adapter/helper assembles for a given filePath+count.
+    segs.forEachIndexed { i, f ->
+      assertEquals("seg path must be <dest>.partial.seg$i", "$dest.partial.seg$i", f.absolutePath)
+    }
+    // A sibling NOT under the `.partial` prefix must survive the sweep.
+    val unrelated = File("$dest.keep").apply { writeText("k") }
+
+    RangeDownloadLogic.sweepPartialArtifacts(dest)
+
+    assertFalse("`.partial` must be swept", partial.exists())
+    segs.forEach { assertFalse("${it.name} must be swept", it.exists()) }
+    assertTrue("unrelated sibling must survive", unrelated.exists())
+  }
+
+  @Test
+  fun sweepClearsCustomSegmentCountByPrefixNotJustDefaultEight() {
+    val dest = File(tmpDir, "big.bin").absolutePath
+    File("$dest.partial").writeText("p")
+    // A custom (non-default) 16-segment run must be fully cleared by prefix.
+    val segs = (0 until 16).map { File("$dest.partial.seg$it").apply { writeText("$it") } }
+
+    RangeDownloadLogic.sweepPartialArtifacts(dest)
+
+    segs.forEach { assertFalse("${it.name} (custom count) must be swept", it.exists()) }
+    assertFalse(File("$dest.partial").exists())
+  }
+}

package/android/src/test/java/com/margelo/nitro/reactnativerangedownloader/Ocds416ResumeTest.kt

@@ -0,0 +1,272 @@
+package com.margelo.nitro.reactnativerangedownloader
+
+import okhttp3.OkHttpClient
+import okhttp3.mockwebserver.MockWebServer
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import java.io.File
+import java.util.concurrent.TimeUnit
+
+/**
+ * OCDS gap A2 (SPEC #4 — 416 Range Not Satisfiable kept TRANSIENT).
+ *
+ * Guards the single most-damaging §4 mistake called out in the core comment
+ * (ConcurrentRangeDownloader.kt lines 590-593): 416 MUST classify as transient
+ * (`isPermanentHttpStatus` line 593 `416 -> false`, placed ABOVE the
+ * `in 400..499 -> true` catch-all at line 594). If 416 were permanent the core
+ * would discard the resumable `.segN` bytes and restart the whole object from
+ * byte 0 — exactly the "do not discard resumable bytes" rule this test pins.
+ *
+ * Scenario: a RESUME run where parts 0..4 are already full on disk (seeded
+ * `.segN`), and the part[5] window hits a single 416 (`STATUS_416` →
+ * `416 + Content-Range: bytes star-slash-total`, FaultServer.kt:67,139-142) that then
+ * succeeds on retry. The load-bearing claims:
+ *   - outcome == COMPLETED and the assembled SHA matches the source (so the 416
+ *     was recovered, not fatal, and nothing was corrupted);
+ *   - the seeded windows 0..4 are NOT re-fetched — proving the 416 did NOT
+ *     trigger a from-0 wipe/restart of already-downloaded segments;
+ *   - the seeded `.segN` for parts 0..4 are NOT deleted/re-created — their
+ *     on-disk length stays exactly full (the "do not discard resumable bytes"
+ *     guarantee, asserted on the bytes on disk, not just the request log);
+ *   - part[5] is requested exactly TWICE (416 then OK), and every request for
+ *     it starts inside its own window (>= part[5].start), never at file byte 0.
+ *
+ * Drives the REAL [ConcurrentRangeDownloader.download] over the
+ * [RangeFaultServer] harness — no behavior is re-implemented here.
+ */
+class Ocds416ResumeTest {
+
+  private lateinit var server: MockWebServer
+  private lateinit var tmpDir: File
+
+  // 3 MiB > minConcurrentBytes (2 MiB) → concurrent path, 8 non-empty parts.
+  private val content: ByteArray = ByteArray(3 * 1024 * 1024) { (it % 251).toByte() }
+  private val parts: List<PlannedPart> by lazy { planParts(content.size.toLong(), 8) }
+
+  @Before
+  fun setUp() {
+    tmpDir = File.createTempFile("crd-ocds-416", "").let {
+      it.delete(); it.mkdirs(); it
+    }
+  }
+
+  @After
+  fun tearDown() {
+    if (this::server.isInitialized) server.shutdown()
+    tmpDir.deleteRecursively()
+  }
+
+  // --- helpers (mirror ConcurrentRangeDownloaderOcdsTest) ------------------
+
+  private fun startServer(faultServer: RangeFaultServer) {
+    server = MockWebServer()
+    server.dispatcher = faultServer.dispatcher
+    server.start()
+  }
+
+  private fun url() = server.url("/asset.bin").toString()
+
+  private fun partialPath() = File(tmpDir, "asset.bin.partial").absolutePath
+
+  private fun segFile(partial: String, index: Int) = File("$partial.seg$index")
+
+  // ------------------------------------------------------------------------
+  // OCDS gap A2: 416 on a resume is TRANSIENT — recovered in place, resumable
+  // bytes preserved, no from-0 restart.
+  // ------------------------------------------------------------------------
+  @Test
+  fun ocds416OnResumeIsTransientKeepsResumableBytesAndCompletes() {
+    val target = parts[5]
+    val fs = RangeFaultServer(content)
+      // One 416 on the part[5] window, then the retry is served normally.
+      .arm(RangeFaultServer.FaultMode.STATUS_416, target.start, target.end, times = 1)
+    startServer(fs)
+
+    val partial = partialPath()
+
+    // Seed parts 0..4 as already-completed `.segN` files (mid-run resume model).
+    // These full-length segments must survive the 416 untouched.
+    seedSegments(partial, content, completedThrough = 4, segments = 8)
+    val seededLengths: Map<Int, Long> = (0..4).associateWith { idx ->
+      val f = segFile(partial, idx)
+      assertTrue("seed for part $idx must exist before run", f.exists())
+      f.length()
+    }
+    // Sanity: each seed is exactly its planned full length going in.
+    for (idx in 0..4) {
+      assertEquals(
+        "seed for part $idx must start at full planned length",
+        parts[idx].length,
+        seededLengths.getValue(idx),
+      )
+    }
+
+    // Fast backoff so the single 416 retry runs quickly (mirrors ocdsT10).
+    val downloader = ConcurrentRangeDownloader(
+      httpClient = OkHttpClient(),
+      segmentCount = 8,
+      retryBaseDelayMillis = 50L,
+      retryMaxDelayMillis = 200L,
+    )
+
+    val outcome = downloader.download(
+      url = url(),
+      partialFilePath = partial,
+      onProgress = { _, _ -> },
+    )
+
+    // (1) The 416 was recovered (not fatal) and assembly is byte-correct.
+    assertEquals(ConcurrentRangeDownloader.Outcome.COMPLETED, outcome)
+    assertEquals(content.size.toLong(), File(partial).length())
+    assertEquals(sha256(content), sha256(File(partial)))
+
+    // The probe always issues a "bytes=0-0" capability check; exclude it from the
+    // segment-window counts (mirrors ocdsT2b lines 184-191).
+    val PROBE = 0L to 0L
+    val ranges = fs.requestedRanges.toList().filterNot { it == PROBE }
+
+    // (2) No from-0 wipe/restart: the seeded windows 0..4 are NOT re-fetched.
+    // A permanent-416 regression would discard `.segN` and re-request these.
+    for (idx in 0..4) {
+      val p = parts[idx]
+      val reqs = ranges.filter { it.first in p.start..p.end }
+      assertTrue("seeded segment $idx must NOT be re-fetched after a 416 (got $reqs)", reqs.isEmpty())
+    }
+    // And specifically nothing ever re-requested file byte 0 as a segment fetch.
+    assertTrue(
+      "no segment fetch may restart at file byte 0 after a 416",
+      ranges.none { it.first == 0L && it.second == 0L },
+    )
+
+    // (3) The direct on-disk proof that a 416 never discards resumable `.segN`
+    // bytes lives in `ocds416NeverDiscardsSeededSegmentsOnDisk` (a perpetual 416
+    // is held mid-run so the seeded segments can be length-checked on disk). On
+    // this COMPLETED path the segments are correctly consumed, so the load-bearing
+    // proof here is the SHA + the request log: seeded windows 0..4 were never
+    // re-fetched (asserted above) and part[5] recovered in place (asserted next).
+
+    // (4) part[5] is requested exactly TWICE (416 then OK). The 416 has an empty
+    // body, so part[5] has 0 bytes on disk → the retry re-requests the SAME full
+    // window (start == part.start, end == part.end), never advancing past it and
+    // never collapsing to file byte 0.
+    val targetReqs = ranges.filter { it.first == target.start && it.second == target.end }
+    assertEquals(
+      "part[5] must be requested exactly twice (416 then OK)",
+      2,
+      targetReqs.size,
+    )
+    assertTrue(
+      "every part[5] request must start inside its own window (>= part.start), never file byte 0",
+      targetReqs.all { it.first >= target.start },
+    )
+
+    // (5) The tail beyond part[5] (parts 6..7) was fetched once each — the run
+    // proceeded normally around the recovered 416 with no global restart.
+    for (idx in 6..7) {
+      val p = parts[idx]
+      val reqs = ranges.filter { it.first == p.start && it.second == p.end }
+      assertEquals("tail segment $idx must be requested once", 1, reqs.size)
+    }
+
+    // (6) On COMPLETED every `.segN` is consumed (no straggler artifacts).
+    for (i in 0 until 8) {
+      assertFalse(".seg$i must be wiped on success", segFile(partial, i).exists())
+    }
+  }
+
+  // ------------------------------------------------------------------------
+  // OCDS gap A2 (resumable-bytes guard, no from-0 wipe): drive a run that does
+  // NOT complete past the 416 so we can observe the seeded `.segN` ON DISK and
+  // prove a 416 leaves them intact (rather than discarding them and restarting
+  // from byte 0). We arm 416 FOREVER on part[5] so it never recovers; the run
+  // exhausts the per-segment retry budget and throws, leaving the seeded
+  // segments 0..4 untouched on disk for direct length inspection.
+  // ------------------------------------------------------------------------
+  @Test
+  fun ocds416NeverDiscardsSeededSegmentsOnDisk() {
+    val target = parts[5]
+    val fs = RangeFaultServer(content)
+      // Fire 416 forever so part[5] never recovers and the run gives up — but a
+      // transient classification must keep the OTHER segments' bytes on disk.
+      .arm(RangeFaultServer.FaultMode.STATUS_416, target.start, target.end, times = Int.MAX_VALUE)
+    startServer(fs)
+
+    val partial = partialPath()
+    seedSegments(partial, content, completedThrough = 4, segments = 8)
+    val seededLengths: Map<Int, Long> = (0..4).associateWith { idx ->
+      segFile(partial, idx).length()
+    }
+
+    // Fast backoff so the bounded retries exhaust quickly.
+    val downloader = ConcurrentRangeDownloader(
+      httpClient = OkHttpClient(),
+      segmentCount = 8,
+      retryBaseDelayMillis = 20L,
+      retryMaxDelayMillis = 80L,
+    )
+
+    var threw = false
+    var outcome: ConcurrentRangeDownloader.Outcome? = null
+    try {
+      outcome = downloader.download(
+        url = url(),
+        partialFilePath = partial,
+        onProgress = { _, _ -> },
+      )
+    } catch (e: Exception) {
+      threw = true
+    }
+
+    // A perpetual 416 is transient → retried then given up (throws), NEVER a
+    // permanent FALLBACK that wipes artifacts, and NEVER a corrupt COMPLETED.
+    assertTrue(
+      "a perpetual 416 must give up via a thrown transient exhaustion, not COMPLETED/FALLBACK",
+      threw,
+    )
+    assertFalse(
+      "a 416 must not produce a COMPLETED outcome",
+      outcome == ConcurrentRangeDownloader.Outcome.COMPLETED,
+    )
+
+    // THE load-bearing on-disk assertion: the seeded `.segN` for parts 0..4 are
+    // still present AND still exactly their full planned length. A permanent-416
+    // regression (discard resumable bytes + restart from byte 0) would have
+    // deleted or truncated these — this fails loudly if that ever happens.
+    for (idx in 0..4) {
+      val f = segFile(partial, idx)
+      assertTrue("seeded `.seg$idx` must NOT be discarded by a 416", f.exists())
+      assertEquals(
+        "seeded `.seg$idx` must keep its full resumable length after a 416 (no from-0 wipe)",
+        seededLengths.getValue(idx),
+        f.length(),
+      )
+      assertEquals(
+        "seeded `.seg$idx` length must equal its planned window length",
+        parts[idx].length,
+        f.length(),
+      )
+    }
+
+    // The 416 part window was actually exercised (the fault fired), and no
+    // request collapsed to a from-0 restart of an already-seeded window.
+    val PROBE = 0L to 0L
+    val ranges = fs.requestedRanges.toList().filterNot { it == PROBE }
+    val targetReqs = ranges.filter { it.first == target.start && it.second == target.end }
+    assertTrue("part[5] (the 416 window) must have been requested", targetReqs.isNotEmpty())
+    assertTrue(
+      "every part[5] request stays inside its window; no from-0 restart",
+      targetReqs.all { it.first >= target.start },
+    )
+    for (idx in 0..4) {
+      val p = parts[idx]
+      assertTrue(
+        "seeded window $idx must never be re-fetched because of a 416",
+        ranges.none { it.first in p.start..p.end },
+      )
+    }
+  }
+}