chore: development v0.2.73 - comprehensive testing complete [auto-commit]

Author: githubrobbi

Cargo.lock

@@ -38,7 +38,7 @@ exclude = [
 # Workspace Package Metadata (inherited by all crates)
 # ─────────────────────────────────────────────────────────────────────────────
 [workspace.package]
-version = "0.2.72"
+version = "0.2.73"
 edition = "2024"
 rust-version = "1.85"
 license = "MPL-2.0 OR LicenseRef-UFFS-Commercial"

Cargo.toml

@@ -21,7 +21,7 @@ Traditional file search tools (including `os.walk`, `FindFirstFile`, etc.) work
 
 **UFFS reads the MFT directly** - once - and queries it in memory using Polars DataFrames. This is like reading the entire phonebook once instead of looking up each name individually.
 
-### Benchmark Results (v0.2.72)
+### Benchmark Results (v0.2.73)
 
 | Drive Type | Records | Time | Throughput |
 |------------|---------|------|------------|
@@ -33,7 +33,7 @@ Traditional file search tools (including `os.walk`, `FindFirstFile`, etc.) work
 
 | Comparison | Records | Time | Notes |
 |------------|---------|------|-------|
-| **UFFS v0.2.72** | **18.7 Million** | **~142 seconds** | All disks, fast mode |
+| **UFFS v0.2.73** | **18.7 Million** | **~142 seconds** | All disks, fast mode |
 | UFFS v0.1.30 | 18.7 Million | ~315 seconds | Baseline |
 | Everything | 19 Million | 178 seconds | All disks |
 | WizFile | 6.5 Million | 299 seconds | Single HDD |

README.md

@@ -4051,7 +4051,12 @@ impl ParallelMftReader {
         let total_bytes = total_records * record_size;
 
         // Use adaptive concurrency and I/O size based on drive type (M2 optimization)
-        let concurrency = self.drive_type.optimal_concurrency();
+        // For HDD, use extent-aware concurrency (fragmentation affects optimal value)
+        let concurrency = if matches!(self.drive_type, crate::platform::DriveType::Hdd) {
+            crate::platform::DriveType::optimal_concurrency_for_hdd(self.extent_map.extent_count())
+        } else {
+            self.drive_type.optimal_concurrency()
+        };
         let io_chunk_size = self.drive_type.optimal_io_size();
 
         info!(
@@ -4472,7 +4477,16 @@ impl ParallelMftReader {
 
         // Use provided values or adaptive defaults based on drive type
         // M1: Adaptive concurrency and I/O size based on drive type
-        let concurrency = concurrency.unwrap_or_else(|| self.drive_type.optimal_concurrency());
+        // For HDD, use extent-aware concurrency (fragmentation affects optimal value)
+        let concurrency = concurrency.unwrap_or_else(|| {
+            if matches!(self.drive_type, crate::platform::DriveType::Hdd) {
+                crate::platform::DriveType::optimal_concurrency_for_hdd(
+                    self.extent_map.extent_count(),
+                )
+            } else {
+                self.drive_type.optimal_concurrency()
+            }
+        });
         let io_chunk_size = io_chunk_size.unwrap_or_else(|| self.drive_type.optimal_io_size());
 
         info!(
@@ -4837,7 +4851,16 @@ impl ParallelMftReader {
         let total_records = self.extent_map.total_records() as usize;
 
         // Use provided values or adaptive defaults
-        let concurrency = concurrency.unwrap_or_else(|| self.drive_type.optimal_concurrency());
+        // For HDD, use extent-aware concurrency (fragmentation affects optimal value)
+        let concurrency = concurrency.unwrap_or_else(|| {
+            if matches!(self.drive_type, crate::platform::DriveType::Hdd) {
+                crate::platform::DriveType::optimal_concurrency_for_hdd(
+                    self.extent_map.extent_count(),
+                )
+            } else {
+                self.drive_type.optimal_concurrency()
+            }
+        });
         let io_chunk_size = io_chunk_size.unwrap_or_else(|| self.drive_type.optimal_io_size());
         let num_workers = num_workers.unwrap_or_else(num_cpus::get);
 
@@ -7344,7 +7367,12 @@ pub fn prepare_volume_state(
 ) -> VolumeState {
     let record_size = extent_map.bytes_per_record as usize;
     let total_records = extent_map.total_records() as usize;
-    let max_concurrency = drive_type.optimal_concurrency();
+    // For HDD, use extent-aware concurrency (fragmentation affects optimal value)
+    let max_concurrency = if matches!(drive_type, crate::platform::DriveType::Hdd) {
+        crate::platform::DriveType::optimal_concurrency_for_hdd(extent_map.extent_count())
+    } else {
+        drive_type.optimal_concurrency()
+    };
     let io_chunk_size = drive_type.optimal_io_size();
 
     // Generate I/O operations
@@ -7672,8 +7700,8 @@ mod tests {
         assert_eq!(resolve_concurrency(None, DriveType::Ssd), 8);
         assert_eq!(resolve_io_size(None, DriveType::Ssd), 2 * 1024 * 1024);
 
-        // Test HDD with None (should use optimal)
-        assert_eq!(resolve_concurrency(None, DriveType::Hdd), 2);
+        // Test HDD with None (default is 4, but actual I/O uses extent-aware logic)
+        assert_eq!(resolve_concurrency(None, DriveType::Hdd), 4);
         assert_eq!(resolve_io_size(None, DriveType::Hdd), 1024 * 1024);
 
         // Test Unknown with None (should use conservative)

crates/uffs-mft/src/io.rs

@@ -1420,13 +1420,40 @@ impl DriveType {
     #[must_use]
     pub const fn optimal_concurrency(&self) -> usize {
         match self {
-            Self::Nvme => 32,   // NVMe can handle 64K+ queue depth
-            Self::Ssd => 8,     // SATA NCQ supports 32
-            Self::Hdd => 2,     // Sequential, avoid seeks
+            Self::Nvme => 32, // NVMe can handle 64K+ queue depth
+            Self::Ssd => 8,   // SATA NCQ supports 32
+            Self::Hdd => 4,   // Default for HDD; use optimal_concurrency_for_hdd() with
+            // extent count for better tuning
             Self::Unknown => 4, // Conservative default
         }
     }
 
+    /// Returns the optimal I/O concurrency for HDD based on MFT fragmentation.
+    ///
+    /// Benchmarks (2026-01-24) show that HDD optimal concurrency depends on
+    /// fragmentation:
+    /// - Highly fragmented (>50 extents): concurrency=2 is best (more I/O ops =
+    ///   more seeks = worse)
+    /// - Moderately fragmented (17-50 extents): concurrency=4 is best
+    /// - Less fragmented (<17 extents): concurrency=4-6 works well
+    ///
+    /// | Drive | Extents | Best Concurrency | Notes |
+    /// |-------|---------|------------------|-------|
+    /// | S:    | 62      | 2                | Highly fragmented, 2 is 6% faster than 4 |
+    /// | D:    | 28      | 6                | Moderate, 6 is 6.5% faster than 2 |
+    /// | E:    | 19      | 4                | Moderate, 4 is 7% faster than 2 |
+    /// | M:    | 17      | 4                | Moderate, 4 is 3.7% faster than 2 |
+    #[must_use]
+    pub const fn optimal_concurrency_for_hdd(extent_count: usize) -> usize {
+        if extent_count > 50 {
+            2 // Highly fragmented: minimize seeks
+        } else if extent_count > 20 {
+            4 // Moderately fragmented
+        } else {
+            6 // Less fragmented: can handle more concurrency
+        }
+    }
+
     /// Returns the optimal I/O chunk size for this drive type.
     ///
     /// This is the size of each async read operation. Larger chunks reduce
@@ -1773,15 +1800,41 @@ mod tests {
     fn test_hdd_optimal_settings() {
         let drive_type = DriveType::Hdd;
 
-        // HDD should use minimal concurrency to avoid seeks
-        assert_eq!(drive_type.optimal_concurrency(), 2);
+        // HDD: default concurrency=4, but use optimal_concurrency_for_hdd() with extent
+        // count
+        assert_eq!(drive_type.optimal_concurrency(), 4);
         assert_eq!(drive_type.optimal_io_size(), 1024 * 1024); // 1 MB
         assert_eq!(drive_type.optimal_chunk_size(), 1024 * 1024); // 1 MB
         assert_eq!(drive_type.prefetch_buffers(), 2);
         assert!(!drive_type.is_high_performance());
         assert!(!drive_type.benefits_from_parallel_parsing());
     }
 
+    #[test]
+    fn test_hdd_extent_aware_concurrency() {
+        // Benchmarks (2026-01-24) show optimal concurrency depends on fragmentation:
+        // - S: 62 extents -> concurrency=2 best (highly fragmented)
+        // - D: 28 extents -> concurrency=6 best (moderate)
+        // - E: 19 extents -> concurrency=4 best (moderate)
+        // - M: 17 extents -> concurrency=4 best (less fragmented)
+
+        // Highly fragmented (>50 extents): use 2
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(62), 2);
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(100), 2);
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(51), 2);
+
+        // Moderately fragmented (21-50 extents): use 4
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(50), 4);
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(28), 4);
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(21), 4);
+
+        // Less fragmented (<=20 extents): use 6
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(20), 6);
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(19), 6);
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(17), 6);
+        assert_eq!(DriveType::optimal_concurrency_for_hdd(1), 6);
+    }
+
     #[test]
     fn test_unknown_optimal_settings() {
         let drive_type = DriveType::Unknown;

crates/uffs-mft/src/platform.rs

@@ -1 +1 @@
-v0.2.72
+v0.2.73