Never schedule fewer workers than the file count already justifies

sqrt(files) dips below the existing job-count formula between roughly 400 and
800 files, so the rule quietly took workers away from large runs. On 600 warm
files it scheduled 12 where the default schedules 14, and measured 13.2% slower
against a 2.2% control.

The rule exists to stop small runs being starved, never to reduce a large one.
Take the maximum of the two, so the adaptive count can only ever raise
parallelism. Small runs are unchanged: 9, 25, 50, 100 and 200 files still
schedule 2, 3, 4, 5 and 7 workers.

The test asserts the invariant across 13 file counts rather than trusting a
table, because the dip only shows up in a band neither end of the range covers.

Reported by @staabm on the pull request.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: SanderMuller

src/Parallel/Scheduler.php

@@ -91,7 +91,7 @@ public function scheduleWork(
 
 		$desiredNumberOfProcesses = null;
 		if ($this->adaptiveParallelWorkerCount) {
-			$desiredNumberOfProcesses = $this->resolveDesiredNumberOfProcesses(count($files), $cpuCores);
+			$desiredNumberOfProcesses = $this->resolveDesiredNumberOfProcesses(count($files), $numberOfJobs, $cpuCores);
 
 			// the spawn loop stops when the queue runs dry, so a worker without a
 			// job of its own never starts - chunk finely enough to feed them all
@@ -133,7 +133,7 @@ public function scheduleWork(
 	 *
 	 * @return positive-int
 	 */
-	private function resolveDesiredNumberOfProcesses(int $numberOfFiles, int $cpuCores): int
+	private function resolveDesiredNumberOfProcesses(int $numberOfFiles, int $numberOfJobs, int $cpuCores): int
 	{
 		if ($numberOfFiles < 1) {
 			return 1;
@@ -142,7 +142,12 @@ private function resolveDesiredNumberOfProcesses(int $numberOfFiles, int $cpuCor
 		$floor = $numberOfFiles >= self::ADAPTIVE_SECOND_WORKER_FILE_THRESHOLD ? 2 : 1;
 		$fromFileCount = (int) round(self::ADAPTIVE_WORKERS_PER_SQRT_FILE * sqrt($numberOfFiles));
 
-		return max(1, min(max($floor, $fromFileCount), $cpuCores, $numberOfFiles));
+		// never below what the job count alone already justifies: the point is to stop
+		// small runs being starved, not to take workers away from large ones, and
+		// sqrt() dips under the existing formula between roughly 400 and 800 files
+		$fromJobCount = max((int) floor($numberOfJobs / $this->minimumNumberOfJobsPerProcess), 1);
+
+		return max(1, min(max($floor, $fromFileCount, $fromJobCount), $cpuCores, $numberOfFiles));
 	}
 
 	/**

tests/PHPStan/Parallel/SchedulerTest.php

@@ -231,6 +231,25 @@ public function testAdaptiveWorkerCountKeepsTinyRunsSerial(): void
 		$this->assertSame(2, $scheduler->scheduleWork(14, array_fill(0, 9, 'file.php'), $callback)->getNumberOfProcesses());
 	}
 
+	public function testAdaptiveWorkerCountIsNeverBelowTheDefault(): void
+	{
+		// the rule exists to stop small runs being starved, never to take workers away
+		// from large ones - sqrt() alone dips under the existing formula between roughly
+		// 400 and 800 files, which measured 13% slower at 600
+		$callback = static fn (string $file): int => 0;
+		foreach ([1, 5, 9, 25, 50, 100, 200, 300, 400, 600, 800, 1424, 4524] as $numberOfFiles) {
+			$files = array_fill(0, $numberOfFiles, 'file.php');
+			$legacy = (new Scheduler(20, Scheduler::AUTO, 2))->scheduleWork(14, $files, $callback);
+			$adaptive = (new Scheduler(20, Scheduler::AUTO, 2, true))->scheduleWork(14, $files, $callback);
+
+			$this->assertGreaterThanOrEqual(
+				$legacy->getNumberOfProcesses(),
+				$adaptive->getNumberOfProcesses(),
+				sprintf('%d files', $numberOfFiles),
+			);
+		}
+	}
+
 	public function testAdaptiveWorkerCountNeverExceedsTheJobCount(): void
 	{
 		// a worker with no job never starts, so the schedule must not claim one