binpacker 0.3.0 → 0.5.0

data/lib/binpacker/progress.rb

@@ -7,7 +7,7 @@ module Binpacker
     def initialize(worker_count, tty: $stdout.tty?)
       @worker_count = worker_count
       @tty = tty
-      @workers = Array.new(worker_count) { { done: 0, total: 0, file: "", elapsed: 0.0 } }
+      @workers = Array.new(worker_count) { { done: 0, total: 0, file: '', elapsed: 0.0 } }
       @start = Time.now
       @last_ci_output = Time.at(Time.now.to_f - CI_INTERVAL)
       @lines_written = 0
@@ -32,8 +32,9 @@ module Binpacker
       end
     end
 
-    def finish(worker_stats = [])
+    def finish(_worker_stats = [])
       return unless @tty
+
       redraw
       $stdout.puts
     end
@@ -42,9 +43,10 @@ module Binpacker
       active = worker_stats.reject { |s| s[:files] == 0 && s[:examples] == 0 }
       return if active.empty?
 
-      active.each_with_index do |s, i|
+      worker_stats.each_with_index do |s, wid|
+        next if s[:files] == 0 && s[:examples] == 0
+
         t = format_time(s[:total_time])
-        wid = worker_stats.index(s)
         $stdout.puts "  Worker #{wid}: #{s[:files]} tests, #{t} | #{s[:examples]} examples, #{s[:passed]} passed"
       end
       total_tests = active.sum { |s| s[:files] }
@@ -55,7 +57,7 @@ module Binpacker
       max_dev = times.map { |t| (t - mean).abs }.max
       dev_pct = mean > 0 ? (max_dev / mean * 100).round(1) : 0
 
-      $stdout.puts "  ──"
+      $stdout.puts '  ──'
       $stdout.puts "  Total: #{total_tests} tests, #{format_time(total_time)} | #{total_examples} examples"
       $stdout.puts "  Balance: max deviation #{format_time(max_dev)} (#{dev_pct}%)"
     end
@@ -67,7 +69,7 @@ module Binpacker
         clear_lines
         @workers.each_with_index do |w, i|
           bar = build_bar(w[:done], w[:total])
-          status = w[:total] > 0 && w[:done] >= w[:total] ? "done" : w[:file][-50..] || ""
+          status = w[:total] > 0 && w[:done] >= w[:total] ? 'done' : w[:file][-50..] || ''
           $stdout.puts format_line(i, bar, w[:done], w[:total], status, w[:elapsed])
         end
         @lines_written = @worker_count
@@ -76,13 +78,15 @@ module Binpacker
 
     def clear_lines
       return if @lines_written == 0
+
       @lines_written.times do
         $stdout.print "\033[A\033[K"
       end
     end
 
     def build_bar(done, total)
-      return "[----------]" if total == 0
+      return '[----------]' if total == 0
+
       width = 10
       filled = (done.to_f / total * width).round
       "[#{'█' * filled}#{'░' * (width - filled)}]"
@@ -96,10 +100,11 @@ module Binpacker
     def periodic_output
       now = Time.now
       return if now - @last_ci_output < CI_INTERVAL
+
       @last_ci_output = now
 
       parts = @workers.map.with_index do |w, i|
-        ratio = w[:total] > 0 ? "#{w[:done]}/#{w[:total]}" : "0/?"
+        ratio = w[:total] > 0 ? "#{w[:done]}/#{w[:total]}" : '0/?'
         "W#{i}: #{ratio}"
       end
       elapsed = (now - @start).round(1)
@@ -108,7 +113,8 @@ module Binpacker
     end
 
     def format_time(seconds)
-      return "  0.0s" if seconds < 0.001
+      return '  0.0s' if seconds < 0.001
+
       m = (seconds / 60).floor
       s = (seconds % 60).round(1)
       m > 0 ? "#{m}m#{s.to_s.rjust(4, '0')}s" : "#{s.to_s.rjust(5)}s"

data/lib/binpacker/report.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "json"
+require 'json'
 
 module Binpacker
   # Builds the machine-readable Run report: predicted versus actual per-Worker
@@ -9,13 +9,17 @@ module Binpacker
     SCHEMA = 1
     DRIFT_LIMIT = 10
 
-    def initialize(profile:, algorithm:, predicted_loads:, worker_stats:, all_timings:, timings:)
+    def initialize(profile:, algorithm:, predicted_loads:, worker_stats:, all_timings:, timings:,
+                   shard: nil, discovered: nil, selected: nil)
       @profile = profile
       @algorithm = algorithm
       @predicted_loads = predicted_loads
       @worker_stats = worker_stats
       @all_timings = all_timings
       @timings = timings
+      @shard = shard
+      @discovered = discovered
+      @selected = selected
     end
 
     def to_h
@@ -26,6 +30,7 @@ module Binpacker
         schema: SCHEMA,
         profile: @profile,
         algorithm: @algorithm,
+        shard: shard_section,
         worker_count: @worker_stats.size,
         predicted_makespan: round(predicted.max || 0.0),
         actual_makespan: round(actual.max || 0.0),
@@ -44,6 +49,29 @@ module Binpacker
 
     private
 
+    # The audit trail for a sharded run, and the reason `discovered` is recorded at all.
+    #
+    # Shards never talk to each other: each computes the same N-way partition and trusts the others to have
+    # computed it identically. They do so only while they agree on the timing data the partition is cut
+    # from, which in CI means every shard restoring the same timing cache. A shard that restores a
+    # different one — a cache miss where its siblings hit — partitions differently, and the failure is
+    # silent: tests land in no shard at all and the build stays green.
+    #
+    # `discovered` is the whole-suite count before slicing, so it agrees across shards that see the same
+    # repository. `selected` is this shard's slice. Summing `selected` over a matrix's reports and
+    # comparing to the shared `discovered` turns that silent skip into a failure —
+    # `binpacker shards-check` does exactly that.
+    def shard_section
+      return nil unless @shard
+
+      {
+        index: @shard.index,
+        total: @shard.total,
+        discovered_tests: @discovered,
+        selected_tests: @selected
+      }
+    end
+
     def workers
       @worker_stats.map.with_index do |s, i|
         {
@@ -84,13 +112,15 @@ module Binpacker
     end
 
     def normalize_file(file)
-      file.to_s.sub(%r{\A\./}, "")
+      file.to_s.sub(%r{\A\./}, '')
     end
 
     def deviation_pct(loads)
       return 0.0 if loads.empty?
+
       mean = loads.sum / loads.size
       return 0.0 unless mean.positive?
+
       max_dev = loads.map { |t| (t - mean).abs }.max
       round(max_dev / mean * 100)
     end

data/lib/binpacker/shard.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Binpacker
+  # One slice of the suite, for splitting a run across independent machines.
+  #
+  # Workers divide a suite across the cores of ONE machine and share its wall clock; a shard divides it
+  # across machines that have no wall clock in common. So the two compose rather than compete: a CI matrix
+  # of N jobs each passing `--shard k/N` runs `worker_count` workers over its own slice, and the suite's
+  # wall time becomes roughly the slowest shard rather than the whole.
+  #
+  # The slice is cut by the SAME weight-balanced partitioner that assigns work to workers, over the same
+  # measured timings — shards are just a coarser bin-packing of the same problem, so an equal-count split
+  # would balance no better than round-robin. That also makes the cut deterministic: given one timing file,
+  # every shard computes the identical N-way partition and takes only its own bin, so no shard needs to
+  # know what the others decided, and every test lands in exactly one shard.
+  class Shard
+    attr_reader :index, :total
+
+    # Parses the `k/n` form used by `--shard` and BINPACKER_SHARD. `k` is 1-based, so a matrix can pass its
+    # own 1-based job number straight through.
+    #
+    # @param spec [String, nil]
+    # @return [Shard, nil] nil when `spec` is nil or empty, i.e. an unsharded run.
+    def self.parse(spec)
+      return nil if spec.nil? || spec.to_s.strip.empty?
+
+      match = %r{\A\s*(\d+)\s*/\s*(\d+)\s*\z}.match(spec.to_s)
+      raise ConfigError, "invalid shard #{spec.inspect}: expected the form K/N, e.g. 1/3" unless match
+
+      new(index: Integer(match[1]), total: Integer(match[2]))
+    end
+
+    def initialize(index:, total:)
+      raise ConfigError, "shard count must be at least 1, got #{total}" if total < 1
+      raise ConfigError, "shard index must be between 1 and #{total}, got #{index}" unless (1..total).cover?(index)
+
+      @index = index
+      @total = total
+      freeze
+    end
+
+    def to_s
+      "#{index}/#{total}"
+    end
+
+    # Whole-suite runs still construct no Shard, so this is only ever true for an explicit `--shard 1/1`.
+    def whole_suite?
+      total == 1
+    end
+
+    # @param tests [Array<Test>] every test discovered, before any slicing
+    # @param timings [Hash] predicted weight per test key, as `Timing#load_with_fallback` returns
+    # @param scheduler [Scheduler] the same partitioner the run uses for workers
+    # @return [Array<Test>] the tests belonging to this shard
+    def select(tests:, timings:, scheduler:)
+      return tests if whole_suite?
+
+      bins = scheduler.partition(tests: tests, worker_count: total, timings: timings)
+      bins[index - 1].remaining
+    end
+  end
+end

data/lib/binpacker/shard_check.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Binpacker
+  # Fan-in audit for a sharded matrix: did the shards, between them, actually run the whole suite?
+  #
+  # Shards never coordinate. Each cuts the same N-way partition from the timing data it loaded and takes
+  # its own bin, which is correct exactly as long as they all loaded the SAME data. In CI that means every
+  # shard job restoring the same timing cache — and the failure mode when one does not is the bad one:
+  # it partitions differently, some tests land in no shard, and every job still reports success. Nothing
+  # inside a single shard can notice, because a shard cannot tell "not mine" from "does not exist".
+  #
+  # So the check belongs after the matrix, over the run reports it produced. Point it at every shard's
+  # report and it fails unless the reports describe one coherent split of one suite.
+  class ShardCheck
+    Result = Struct.new(:ok, :problems, :summary, keyword_init: true) do
+      def ok? = ok
+    end
+
+    def self.call(paths) = new(paths).call
+
+    def initialize(paths)
+      @paths = Array(paths)
+    end
+
+    def call
+      return failure(['no run reports given']) if @paths.empty?
+
+      reports, unreadable = load_reports
+      return failure(unreadable) unless unreadable.empty?
+
+      shards = reports.filter_map { |path, data| shard_of(path, data) }
+      missing = reports.map(&:first) - shards.map { |s| s[:path] }
+      return failure(missing.map { |p| "#{p}: no `shard` section — was it run with --shard?" }) unless missing.empty?
+
+      problems = check(shards)
+      problems.empty? ? success(shards) : failure(problems)
+    end
+
+    private
+
+    def load_reports
+      reports = []
+      unreadable = []
+      @paths.each do |path|
+        reports << [path, JSON.parse(File.read(path))]
+      rescue Errno::ENOENT
+        unreadable << "#{path}: no such file"
+      rescue JSON::ParserError => e
+        unreadable << "#{path}: not valid JSON (#{e.message})"
+      end
+      [reports, unreadable]
+    end
+
+    def shard_of(path, data)
+      section = data['shard']
+      return nil unless section.is_a?(Hash)
+
+      {
+        path: path,
+        index: section['index'],
+        total: section['total'],
+        discovered: section['discovered_tests'],
+        selected: section['selected_tests']
+      }
+    end
+
+    def check(shards)
+      problems = []
+      problems.concat(agreement_problems(shards, :total, 'shard count'))
+      problems.concat(agreement_problems(shards, :discovered, 'discovered test count'))
+      problems.concat(completeness_problems(shards))
+      problems.concat(coverage_problems(shards))
+      problems
+    end
+
+    # Every report must describe the same matrix. Disagreement here means the reports were not produced by
+    # one run, and no coverage conclusion drawn from them would mean anything.
+    def agreement_problems(shards, field, label)
+      values = shards.map { |s| s[field] }.uniq
+      return [] if values.size <= 1
+
+      ["shards disagree on #{label}: #{values.sort_by(&:to_s).inspect}"]
+    end
+
+    # A matrix that lost a job silently drops that job's slice, which looks exactly like a smaller suite.
+    def completeness_problems(shards)
+      total = shards.first[:total]
+      return [] if total.nil?
+
+      seen = shards.map { |s| s[:index] }
+      duplicates = seen.tally.select { |_, n| n > 1 }.keys.sort
+      problems = []
+      problems << "shard #{duplicates.join(', ')} reported more than once" unless duplicates.empty?
+
+      absent = (1..total).to_a - seen
+      problems << "no report for shard #{absent.join(', ')} of #{total}" unless absent.empty?
+      problems
+    end
+
+    # The check this class exists for: the slices must add up to the suite.
+    def coverage_problems(shards)
+      discovered = shards.first[:discovered]
+      return [] if discovered.nil?
+
+      selected = shards.sum { |s| s[:selected].to_i }
+      return [] if selected == discovered
+
+      verb = selected < discovered ? 'ran no shard' : 'ran in more than one shard'
+      ["shards cover #{selected} of #{discovered} tests — #{(discovered - selected).abs} #{verb}. " \
+       'The shards partitioned different timing data; make every shard load the same timing file.']
+    end
+
+    def success(shards)
+      Result.new(
+        ok: true,
+        problems: [],
+        summary: "#{shards.size} shards cover all #{shards.first[:discovered]} tests"
+      )
+    end
+
+    def failure(problems)
+      Result.new(ok: false, problems: problems, summary: 'shard coverage check failed')
+    end
+  end
+end

data/lib/binpacker/timing.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "json"
+require 'json'
 
 module Binpacker
   class Timing
@@ -8,40 +8,69 @@ module Binpacker
 
     DEFAULT_WEIGHT = 1.0
 
+    # Samples retained per test by #compact! and consulted by the
+    # median in #load_per_file. Three samples make a single anomalous
+    # run (GC pause, noisy CI neighbour) unable to move the weight.
+    MAX_SAMPLES_PER_TEST = 3
+
     def initialize(path)
       @path = Pathname(path)
     end
 
+    # True once any timing samples exist, i.e. the project has been
+    # calibrated at least once. Callers use this to tell a measured
+    # run (weights in seconds) from a pure cold start (fallbacks only).
+    def calibrated?
+      !samples_by_test.empty?
+    end
+
     def load_with_fallback(tests)
       per_file = load_per_file
+      coefficient = seconds_per_kb(per_file)
       tests.each_with_object({}) do |test, hash|
         key = normalize_path(test.file)
-        hash[test.key] = per_file.fetch(key) { filesize_weight(test.file) }
+        hash[test.key] = per_file.fetch(key) { fallback_weight(test.file, coefficient) }
       end
     end
 
     def load_raw
-      return {} unless @path.exist?
-
-      @path.each_line(encoding: "UTF-8")
-        .map { |line| parse_line(line) }
-        .compact
-        .group_by { |e| [normalize_path(e.file), e.name] }
-        .transform_values { |entries| entries.last.time }
+      @load_raw ||= samples_by_test.transform_values(&:last)
     end
 
+    # Predicted weight per file: the median of each test's recent
+    # samples, summed per file. The append-only history must NOT be
+    # summed wholesale — a file present in N historical runs would
+    # weigh ~N times its true cost, so long-lived files dominate and
+    # newly added ones are starved, skewing the partition.
     def load_per_file
-      return {} unless @path.exist?
+      samples_by_test.each_with_object({}) do |((file, _name), times), per_file|
+        weight = median(times.last(MAX_SAMPLES_PER_TEST))
+        per_file[file] = per_file.fetch(file, 0.0) + weight
+      end
+    end
 
-      @path.each_line(encoding: "UTF-8")
-        .map { |line| parse_line(line) }
-        .compact
-        .group_by { |e| normalize_path(e.file) }
-        .transform_values { |entries| entries.sum(&:time) }
+    # Rewrites the timing file keeping only the most recent
+    # MAX_SAMPLES_PER_TEST samples per test, so the append-only
+    # history (and any CI cache built from it) stays bounded instead
+    # of growing by one run per invocation.
+    def compact!
+      samples = samples_by_test
+      return if samples.empty?
+
+      tmp = Pathname("#{@path}.tmp")
+      tmp.open('w', encoding: 'UTF-8') do |io|
+        samples.each do |(file, name), times|
+          times.last(MAX_SAMPLES_PER_TEST).each do |time|
+            io.puts JSON.generate({ file: file, name: name, time: time })
+          end
+        end
+      end
+      File.rename(tmp.to_s, @path.to_s)
+      invalidate
     end
 
     def normalize_path(path)
-      Pathname(path).cleanpath.to_s.sub(/\A\.\//, "")
+      Pathname(path).cleanpath.to_s.sub(%r{\A\./}, '')
     end
 
     # True when a measured Weight already exists for this Test.
@@ -49,34 +78,103 @@ module Binpacker
       load_raw.key?([normalize_path(file), name])
     end
 
-    def weight_for(file:, name:)
-      measured = load_raw
-      measured.fetch([file, name]) { filesize_weight(file) }
-    end
-
     def append(file:, name:, time:)
       @path.dirname.mkpath unless @path.dirname.directory?
-      @path.open("a", encoding: "UTF-8") { |io| io.puts JSON.generate({ file: file, name: name, time: time }) }
+      @path.open('a', encoding: 'UTF-8') { |io| io.puts JSON.generate({ file: file, name: name, time: time }) }
+      invalidate
     end
 
     def append_all(entries)
       return if entries.empty?
+
       @path.dirname.mkpath unless @path.dirname.directory?
-      @path.open("a", encoding: "UTF-8") do |io|
+      @path.open('a', encoding: 'UTF-8') do |io|
         entries.each { |e| io.puts JSON.generate({ file: e[:file], name: e[:name], time: e[:time] }) }
       end
+      invalidate
     end
 
     private
 
+    # [normalized file, name] => [sample, ...] in append (= run) order.
+    def samples_by_test
+      @samples_by_test ||= begin
+        samples = Hash.new { |h, k| h[k] = [] }
+        if @path.exist?
+          @path.each_line(encoding: 'UTF-8') do |line|
+            entry = parse_line(line)
+            samples[[normalize_path(entry.file), entry.name]] << entry.time if entry
+          end
+        end
+        samples.default_proc = nil
+        samples
+      end
+    end
+
+    def invalidate
+      @samples_by_test = nil
+      @load_raw = nil
+    end
+
+    def median(values)
+      sorted = values.sort
+      mid = sorted.size / 2
+      sorted.size.odd? ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2.0
+    end
+
     def filesize_weight(file)
       path = Pathname(file)
       path.exist? ? [path.size / 1024.0, DEFAULT_WEIGHT].max : DEFAULT_WEIGHT
     end
 
+    # Seconds-per-KB coefficient used to scale filesize fallbacks onto
+    # the same axis as measured Weights. Measured Weights are seconds;
+    # the raw filesize fallback is KB, so mixing them (batch floors,
+    # donor selection) compares apples to oranges — 30s of predicted
+    # work reads as "30 KB of files". We estimate a conversion from
+    # the files we DO have timings for: for each measured file that
+    # still exists on disk with size > 0, take measured_seconds /
+    # size_kb, and use the median of those ratios (robust to a few
+    # outlier files that are unusually fast or slow for their size).
+    # nil when nothing can be estimated (no measurements, or none of
+    # the measured files exist on disk) — callers then keep raw KB.
+    def seconds_per_kb(per_file)
+      ratios = per_file.filter_map do |file, seconds|
+        kb = size_kb(file)
+        next if kb.nil? || kb <= 0
+
+        seconds / kb
+      end
+      ratios.empty? ? nil : median(ratios)
+    end
+
+    # Predicted Weight for an unmeasured Test. Without a coefficient we
+    # keep the legacy raw-KB behavior (floored at 1.0). With one we
+    # scale filesize into seconds: an existing file becomes
+    # size_kb * coefficient (floored at 0.01 to avoid degenerate zero
+    # weights, but NOT at 1.0 — sub-second predictions are meaningful
+    # now that the unit is seconds); a missing/unreadable file falls
+    # back to DEFAULT_WEIGHT as a plausible seconds-scale default.
+    def fallback_weight(file, coefficient)
+      return filesize_weight(file) if coefficient.nil?
+
+      kb = size_kb(file)
+      return DEFAULT_WEIGHT if kb.nil?
+
+      [kb * coefficient, 0.01].max
+    end
+
+    # File size in KB, or nil when the file does not exist / is unreadable.
+    def size_kb(file)
+      path = Pathname(file)
+      path.exist? ? path.size / 1024.0 : nil
+    rescue SystemCallError
+      nil
+    end
+
     def parse_line(line)
       data = JSON.parse(line.strip)
-      Entry.new(file: data["file"], name: data["name"], time: data["time"])
+      Entry.new(file: data['file'], name: data['name'], time: data['time'])
     rescue JSON::ParserError
       nil
     end

data/lib/binpacker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Binpacker
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/binpacker/worker_queue.rb

@@ -37,7 +37,7 @@ module Binpacker
     end
 
     def total_weight(timings)
-      remaining.sum { |t| timings.fetch(t.key, Timing::DEFAULT_WEIGHT) }
+      remaining.sum(0.0) { |t| timings.fetch(t.key, Timing::DEFAULT_WEIGHT) }
     end
 
     def push(test)

data/lib/binpacker.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
-require_relative "binpacker/version"
-require_relative "binpacker/config"
-require_relative "binpacker/timing"
-require_relative "binpacker/test_discovery"
-require_relative "binpacker/worker_queue"
-require_relative "binpacker/scheduler"
-require_relative "binpacker/worker"
-require_relative "binpacker/test_runner"
-require_relative "binpacker/calibration"
-require_relative "binpacker/report"
-require_relative "binpacker/skills"
-require_relative "binpacker/project_state"
-require_relative "binpacker/orchestrator"
-require_relative "binpacker/progress"
+require_relative 'binpacker/version'
+require_relative 'binpacker/config'
+require_relative 'binpacker/timing'
+require_relative 'binpacker/test_discovery'
+require_relative 'binpacker/worker_queue'
+require_relative 'binpacker/scheduler'
+require_relative 'binpacker/shard'
+require_relative 'binpacker/shard_check'
+require_relative 'binpacker/worker'
+require_relative 'binpacker/test_runner'
+require_relative 'binpacker/calibration'
+require_relative 'binpacker/report'
+require_relative 'binpacker/skills'
+require_relative 'binpacker/project_state'
+require_relative 'binpacker/orchestrator'
+require_relative 'binpacker/progress'
 
 module Binpacker
   Error = Class.new(StandardError)

data/sig/binpacker/orchestrator.rbs

@@ -1,6 +1,31 @@
 module Binpacker
   class Orchestrator
-    def initialize: (untyped, ?passthrough: untyped, ?quiet: untyped, ?report_path: untyped) -> void
+    MIN_BATCH_WEIGHT: Float
+    COLD_START_BATCHES_PER_WORKER: Integer
+
+    @config: untyped
+    @passthrough: untyped
+    @quiet: untyped
+    @report_path: untyped
+    @shard: Binpacker::Shard?
+    @discovered_count: Integer
+    @selected_count: Integer
+    @timings: Hash[untyped, Float]
+    @predicted_loads: Array[Float]
+
+    def initialize: (untyped, ?passthrough: untyped, ?quiet: untyped, ?report_path: untyped, ?shard: Binpacker::Shard?) -> void
     def run: () -> { passed: untyped, total: untyped, passed_count: untyped, timings: Array[untyped], empty_filter: untyped }
+
+    private
+
+    def discover: () -> untyped
+    def run_static: (untyped, untyped, Binpacker::Timing, untyped) -> untyped
+    def run_dynamic: (untyped, untyped, Binpacker::Timing, untyped, Float) -> untyped
+    def write_report: (untyped, Array[untyped]) -> void
+    def min_batch_weight: (Binpacker::Timing, Hash[untyped, Float]) -> Float
+    def drain_batch: (Binpacker::WorkerQueue?, Float) -> Array[untyped]
+    def finalize: (Binpacker::Timing, Array[untyped], untyped, untyped, untyped, untyped) -> { passed: untyped, total: untyped, passed_count: untyped, timings: Array[untyped], empty_filter: untyped }
+    def minitest_empty_filter?: (untyped, untyped) -> bool
+    def minitest_include_filter?: () -> bool
   end
 end

data/sig/binpacker/report.rbs

@@ -3,7 +3,8 @@ module Binpacker
     SCHEMA: Integer
     DRIFT_LIMIT: Integer
 
-    def initialize: (profile: untyped, algorithm: untyped, predicted_loads: untyped, worker_stats: untyped, all_timings: untyped, timings: untyped) -> void
+    def initialize: (profile: untyped, algorithm: untyped, predicted_loads: untyped, worker_stats: untyped, all_timings: untyped, timings: untyped, ?shard: Binpacker::Shard?, ?discovered: Integer?, ?selected: Integer?) -> void
+    def shard_section: () -> Hash[Symbol, untyped]?
     def to_h: () -> Hash[Symbol, untyped]
     def write: (untyped) -> untyped
   end

data/sig/binpacker/scheduler.rbs

@@ -1,5 +1,16 @@
 module Binpacker
   class Scheduler
     def self.for: (untyped) -> (Binpacker::LptScheduler | Binpacker::MultifitScheduler)
+
+    # Declared on the base so a caller holding a `Scheduler` can partition; the base body raises
+    # NotImplementedError and every concrete scheduler overrides it.
+    def partition: (tests: Array[untyped], worker_count: Integer, timings: Hash[untyped, Float]) -> Array[Binpacker::WorkerQueue]
+  end
+
+  class LptScheduler < Scheduler
+  end
+
+  class MultifitScheduler < Scheduler
+    ITERATIONS: Integer
   end
 end