polyrun 1.0.0 → 1.2.0

data/lib/polyrun/config.rb

@@ -5,6 +5,10 @@ module Polyrun
   class Config
     DEFAULT_FILENAMES = %w[polyrun.yml config/polyrun.yml].freeze
 
+    # Parallel worker defaults (+run-shards+, +POLYRUN_WORKERS+); single source with {Resolver} and {Effective}.
+    DEFAULT_PARALLEL_WORKERS = 5
+    MAX_PARALLEL_WORKERS = 10
+
     attr_reader :path, :raw
 
     def self.load(path: nil)
@@ -59,3 +63,6 @@ module Polyrun
     end
   end
 end
+
+require_relative "config/resolver"
+require_relative "config/effective"

data/lib/polyrun/database/provision.rb

@@ -1,5 +1,6 @@
 require "open3"
 require "shellwords"
+require_relative "../process_stdio"
 
 module Polyrun
   module Database
@@ -49,20 +50,24 @@ module Polyrun
       # Multi-DB Rails apps must pass all template URLs in one invocation so each DB uses its own +migrations_paths+.
       # Uses +db:prepare+ (not +db:migrate+ alone) so empty template databases load +schema.rb+ first;
       # apps that squash or archive migrations and keep only incremental files need that path.
+      #
+      # Streams stdout/stderr to the terminal by default. With +silent: true+, redirects child stdio
+      # to +File::NULL+ (no live output; non-interactive).
       def prepare_template!(rails_root:, env:, silent: true)
         exe = File.join(rails_root, "bin", "rails")
         raise Polyrun::Error, "Provision: missing #{exe}" unless File.executable?(exe)
 
         child_env = ENV.to_h.merge(env)
         child_env["RAILS_ENV"] ||= ENV["RAILS_ENV"] || "test"
-        rails_out, err, st = Open3.capture3(child_env, exe, "db:prepare", chdir: rails_root)
-        Polyrun::Log.warn err if !silent && !err.to_s.empty?
+        st, out, err = Polyrun::ProcessStdio.spawn_wait(
+          child_env,
+          exe,
+          "db:prepare",
+          chdir: rails_root,
+          silent: silent
+        )
         unless st.success?
-          msg = +"db:prepare failed"
-          msg << "\n--- stderr ---\n#{err}" unless err.to_s.strip.empty?
-          # Rails often prints the first migration/SQL error on stdout; stderr may only show InFailedSqlTransaction.
-          msg << "\n--- stdout ---\n#{rails_out}" unless rails_out.to_s.strip.empty?
-          raise Polyrun::Error, msg
+          raise Polyrun::Error, Polyrun::ProcessStdio.format_failure_message("db:prepare", st, out, err)
         end
 
         true

data/lib/polyrun/partition/constraints.rb

@@ -1,3 +1,5 @@
+require_relative "timing_keys"
+
 module Polyrun
   module Partition
     # Hard constraints for plan assignment (spec_queue.md): pins, serial globs.
@@ -31,21 +33,30 @@ module Polyrun
       end
 
       # Returns Integer shard index if constrained, or nil if free to place by LPT/HRW.
+      # For +path:line+ items (example granularity), also matches pins/globs against the file path only.
       def forced_shard_for(path)
         rel = path.to_s
         abs = File.expand_path(rel, @root)
+        variants = [rel, abs]
+        if (fp = TimingKeys.file_part_for_constraint(rel))
+          variants << fp
+          variants << File.expand_path(fp, @root)
+        end
+        variants.uniq!
 
         @pin_map.each do |pattern, shard|
           next if pattern.to_s.empty?
 
-          if match_pattern?(pattern.to_s, rel, abs)
-            return shard
+          variants.each do |rel_i|
+            abs_i = File.expand_path(rel_i, @root)
+            return shard if match_pattern?(pattern.to_s, rel_i, abs_i)
           end
         end
 
         @serial_globs.each do |g|
-          if match_pattern?(g, rel, abs)
-            return @serial_shard
+          variants.each do |rel_i|
+            abs_i = File.expand_path(rel_i, @root)
+            return @serial_shard if match_pattern?(g, rel_i, abs_i)
           end
         end
 

data/lib/polyrun/partition/paths.rb

@@ -8,9 +8,45 @@ module Polyrun
         File.read(File.expand_path(path.to_s, Dir.pwd)).split("\n").map(&:strip).reject(&:empty?)
       end
 
+      # Prefer +spec/+ RSpec files, then +test/+ Minitest, then Polyrun Quick files (same globs as +polyrun quick+).
+      # Order avoids running the broader Quick glob when RSpec or Minitest files already exist.
+      def detect_auto_suite(cwd = Dir.pwd)
+        base = File.expand_path(cwd)
+        return :rspec if Dir.glob(File.join(base, "spec/**/*_spec.rb")).any?
+
+        return :minitest if Dir.glob(File.join(base, "test/**/*_test.rb")).any?
+
+        quick = quick_parallel_default_paths(base)
+        return :quick if quick.any?
+
+        nil
+      end
+
+      # Infer parallel suite from explicit paths (+_spec.rb+ vs +_test.rb+ vs Polyrun quick-style +.rb+).
+      # Returns +:rspec+, +:minitest+, +:quick+, +:invalid+ (mixed spec and test), or +nil+ (empty).
+      def infer_suite_from_paths(paths)
+        paths = paths.map { |p| File.expand_path(p) }
+        return nil if paths.empty?
+
+        specs = paths.count { |p| File.basename(p).end_with?("_spec.rb") }
+        tests = paths.count { |p| File.basename(p).end_with?("_test.rb") }
+        return :invalid if specs.positive? && tests.positive?
+
+        return :rspec if specs.positive?
+        return :minitest if tests.positive?
+
+        others = paths.size - specs - tests
+        return :quick if others.positive?
+
+        nil
+      end
+
       # When +paths_file+ is set but missing, returns +{ error: "..." }+.
       # Otherwise returns +{ items:, source: }+ (human-readable source label).
-      def resolve_run_shard_items(paths_file: nil, cwd: Dir.pwd)
+      #
+      # +partition.suite+ (optional): +auto+ (default), +rspec+, +minitest+, +quick+ — used only when resolving
+      # from globs (no explicit +paths_file+ and no +spec/spec_paths.txt+).
+      def resolve_run_shard_items(paths_file: nil, cwd: Dir.pwd, partition: {})
         if paths_file
           abs = File.expand_path(paths_file.to_s, cwd)
           unless File.file?(abs)
@@ -20,9 +56,54 @@ module Polyrun
         elsif File.file?(File.join(cwd, "spec", "spec_paths.txt"))
           {items: read_lines(File.join(cwd, "spec", "spec_paths.txt")), source: "spec/spec_paths.txt"}
         else
-          {items: Dir.glob(File.join(cwd, "spec/**/*_spec.rb")).sort, source: "spec/**/*_spec.rb glob"}
+          resolve_run_shard_items_glob(cwd: cwd, partition: partition)
         end
       end
+
+      def resolve_run_shard_items_glob(cwd:, partition: {})
+        suite = (partition["suite"] || partition[:suite] || "auto").to_s.downcase
+        suite = "auto" if suite.empty?
+
+        base = File.expand_path(cwd)
+        spec = Dir.glob(File.join(base, "spec/**/*_spec.rb")).sort
+        test = Dir.glob(File.join(base, "test/**/*_test.rb")).sort
+        quick = quick_parallel_default_paths(base)
+
+        case suite
+        when "rspec"
+          return {error: "partition.suite is rspec but no spec/**/*_spec.rb files"} if spec.empty?
+
+          {items: spec, source: "spec/**/*_spec.rb glob"}
+        when "minitest"
+          return {error: "partition.suite is minitest but no test/**/*_test.rb files"} if test.empty?
+
+          {items: test, source: "test/**/*_test.rb glob"}
+        when "quick"
+          return {error: "partition.suite is quick but no Polyrun quick files under spec/ or test/"} if quick.empty?
+
+          {items: quick, source: "Polyrun quick glob"}
+        when "auto"
+          if spec.any?
+            {items: spec, source: "spec/**/*_spec.rb glob"}
+          elsif test.any?
+            {items: test, source: "test/**/*_test.rb glob"}
+          elsif quick.any?
+            {items: quick, source: "Polyrun quick glob"}
+          else
+            {
+              error: "no spec paths (spec/spec_paths.txt, partition.paths_file, or spec/**/*_spec.rb); " \
+                     "no test/**/*_test.rb; no Polyrun quick files"
+            }
+          end
+        else
+          {error: "unknown partition.suite: #{suite.inspect} (expected auto, rspec, minitest, quick)"}
+        end
+      end
+
+      def quick_parallel_default_paths(base)
+        require_relative "../quick/runner"
+        Polyrun::Quick::Runner.parallel_default_paths(base)
+      end
     end
   end
 end

data/lib/polyrun/partition/plan.rb

@@ -1,41 +1,48 @@
-require "json"
-
+require_relative "timing_keys"
 require_relative "constraints"
 require_relative "hrw"
 require_relative "min_heap"
 require_relative "stable_shuffle"
-
 module Polyrun
   module Partition
-    # Assigns discrete items (e.g. spec paths) to shards (spec_queue.md).
+    # Assigns discrete items (e.g. spec paths, or +path:line+ example locators) to shards (spec_queue.md).
     #
     # Strategies:
     # - +round_robin+ — sorted paths, assign by index mod +total_shards+.
     # - +random_round_robin+ — Fisher–Yates shuffle (optional +seed+), then same mod assignment.
-    # - +cost_binpack+ (+cost+, +binpack+, +timing+) — LPT greedy binpack using per-path weights;
+    # - +cost_binpack+ (+cost+, +binpack+, +timing+) — LPT greedy binpack using per-item weights;
     #   optional {Constraints} for pins / serial globs before LPT on the rest.
+    #   Default +timing_granularity+ is +file+ (one weight per spec file). Experimental +:example+
+    #   uses +path:line+ locators and per-example weights in the timing JSON.
     # - +hrw+ (+rendezvous+) — rendezvous hashing for minimal remapping when m changes; optional constraints.
     class Plan
       COST_STRATEGIES = %w[cost cost_binpack binpack timing].freeze
       HRW_STRATEGIES = %w[hrw rendezvous].freeze
 
-      attr_reader :items, :total_shards, :strategy, :seed, :constraints
+      attr_reader :items, :total_shards, :strategy, :seed, :constraints, :timing_granularity
 
-      def initialize(items:, total_shards:, strategy: "round_robin", seed: nil, costs: nil, constraints: nil, root: nil)
-        @items = items.map(&:to_s).freeze
+      def initialize(items:, total_shards:, strategy: "round_robin", seed: nil, costs: nil, constraints: nil, root: nil, timing_granularity: :file)
+        @timing_granularity = TimingKeys.normalize_granularity(timing_granularity)
+        @root = root ? File.expand_path(root) : Dir.pwd
+        @items = items.map do |x|
+          if @timing_granularity == :example
+            TimingKeys.normalize_locator(x, @root, :example)
+          else
+            x.to_s.strip
+          end
+        end.freeze
         @total_shards = Integer(total_shards)
         raise Polyrun::Error, "total_shards must be >= 1" if @total_shards < 1
 
         @strategy = strategy.to_s
         @seed = seed
-        @root = root ? File.expand_path(root) : Dir.pwd
         @constraints = normalize_constraints(constraints)
         @costs = normalize_costs(costs)
 
         validate_constraints_strategy_combo!
         if cost_strategy? && (@costs.nil? || @costs.empty?)
           raise Polyrun::Error,
-            "strategy #{@strategy} requires a timing map (path => seconds), e.g. merged polyrun_timing.json"
+            "strategy #{@strategy} requires a timing map (path => seconds or path:line => seconds), e.g. merged polyrun_timing.json"
         end
       end
 
@@ -85,24 +92,14 @@ module Polyrun
           "seed" => seed,
           "paths" => shard(shard_index)
         }
+        m["timing_granularity"] = timing_granularity.to_s if timing_granularity == :example
         secs = shard_weight_totals
         m["shard_seconds"] = secs if cost_strategy? || (hrw_strategy? && secs.any? { |x| x > 0 })
         m
       end
 
-      def self.load_timing_costs(path)
-        abs = File.expand_path(path.to_s, Dir.pwd)
-        return {} unless File.file?(abs)
-
-        data = JSON.parse(File.read(abs))
-        return {} unless data.is_a?(Hash)
-
-        out = {}
-        data.each do |k, v|
-          key = File.expand_path(k.to_s, Dir.pwd)
-          out[key] = v.to_f
-        end
-        out
+      def self.load_timing_costs(path, granularity: :file, root: nil)
+        TimingKeys.load_costs_json_file(path, granularity, root: root)
       end
 
       def self.cost_strategy?(name)
@@ -134,7 +131,12 @@ module Polyrun
 
         c = {}
         costs.each do |k, v|
-          key = File.expand_path(k.to_s, @root)
+          key =
+            if @timing_granularity == :example
+              TimingKeys.normalize_locator(k.to_s, @root, :example)
+            else
+              File.expand_path(k.to_s, @root)
+            end
           c[key] = v.to_f
         end
         c
@@ -161,19 +163,27 @@ module Polyrun
       end
 
       def weight_for(path)
-        abs = File.expand_path(path.to_s, @root)
-        return @costs[abs] if @costs&.key?(abs)
+        key = cost_lookup_key(path.to_s)
+        return @costs[key] if @costs&.key?(key)
 
         default_weight
       end
 
       def weight_for_optional(path)
-        abs = File.expand_path(path.to_s, @root)
-        return @costs[abs] if @costs&.key?(abs)
+        key = cost_lookup_key(path.to_s)
+        return @costs[key] if @costs&.key?(key)
 
         0.0
       end
 
+      def cost_lookup_key(path)
+        if @timing_granularity == :example
+          TimingKeys.normalize_locator(path, @root, :example)
+        else
+          File.expand_path(path, @root)
+        end
+      end
+
       def cost_shards
         @cost_shards ||= build_lpt_buckets
       end

data/lib/polyrun/partition/timing_keys.rb

@@ -0,0 +1,85 @@
+require "json"
+
+require_relative "../log"
+
+module Polyrun
+  module Partition
+    # Normalizes partition item keys and timing JSON keys for +file+ vs experimental +example+ granularity.
+    #
+    # * +file+ — one item per spec file; keys are absolute paths (see {#canonical_file_path}).
+    # * +example+ — one item per example (RSpec-style +path:line+); keys are +"#{absolute_path}:#{line}+".
+    module TimingKeys
+      module_function
+
+      # Resolves the parent directory with +File.realpath+ so +/var/...+ and +/private/var/...+ (macOS
+      # tmpdirs) and symlink segments map to one key for the same file.
+      def canonical_file_path(abs_path)
+        dir = File.dirname(abs_path)
+        base = File.basename(abs_path)
+        File.join(File.realpath(dir), base)
+      rescue SystemCallError
+        abs_path
+      end
+
+      # @return [:file, :example]
+      def normalize_granularity(value)
+        case value.to_s.strip.downcase
+        when "example", "examples"
+          :example
+        else
+          :file
+        end
+      end
+
+      # File path only (for partition constraints) when +item+ is +path:line+.
+      def file_part_for_constraint(item)
+        s = item.to_s
+        m = s.match(/\A(.+):(\d+)\z/)
+        return nil unless m && m[2].match?(/\A\d+\z/)
+
+        m[1]
+      end
+
+      # Normalize a path or +path:line+ locator relative to +root+ for cost maps and +Plan+ items.
+      def normalize_locator(raw, root, granularity)
+        s = raw.to_s.strip
+        return canonical_file_path(File.expand_path(s, root)) if s.empty?
+
+        if granularity == :example && (m = s.match(/\A(.+):(\d+)\z/)) && m[2].match?(/\A\d+\z/)
+          fp = canonical_file_path(File.expand_path(m[1], root))
+          return "#{fp}:#{m[2]}"
+        end
+
+        canonical_file_path(File.expand_path(s, root))
+      end
+
+      # Loads merged timing JSON (+path => seconds+ or +path:line => seconds+).
+      #
+      # @param root [String, nil] directory for normalizing relative keys (default: +Dir.pwd+). Use the
+      #   same working directory (or pass the same +root+ as {Partition::Plan}+'s +root+) as when
+      #   generating the timing file so keys align.
+      def load_costs_json_file(path, granularity, root: nil)
+        abs = File.expand_path(path.to_s, Dir.pwd)
+        return {} unless File.file?(abs)
+
+        data = JSON.parse(File.read(abs))
+        return {} unless data.is_a?(Hash)
+
+        g = normalize_granularity(granularity)
+        root = File.expand_path(root || Dir.pwd)
+        out = {}
+        data.each do |k, v|
+          key = normalize_locator(k.to_s, root, g)
+          fv = v.to_f
+          if out.key?(key) && out[key] != fv
+            Polyrun::Log.warn(
+              "polyrun: timing JSON duplicate key #{key.inspect} after normalize (#{out[key]} vs #{fv}); using #{fv}"
+            )
+          end
+          out[key] = fv
+        end
+        out
+      end
+    end
+  end
+end

data/lib/polyrun/prepare/assets.rb

@@ -1,6 +1,6 @@
 require "digest/md5"
 require "fileutils"
-require "open3"
+require_relative "../process_stdio"
 
 module Polyrun
   module Prepare
@@ -41,14 +41,21 @@ module Polyrun
       end
 
       # Shells out to +bin/rails assets:precompile+ when +rails_root+ contains +bin/rails+.
+      # +silent: true+ discards child stdio (+File::NULL+); +silent: false+ inherits the terminal.
       def precompile!(rails_root:, silent: true)
         exe = File.join(rails_root, "bin", "rails")
         raise Polyrun::Error, "Prepare::Assets: no #{exe}" unless File.executable?(exe)
 
-        cmd = [exe, "assets:precompile"]
-        _out, err, st = Open3.capture3(*cmd, chdir: rails_root)
-        Polyrun::Log.warn err if !silent && !err.empty?
-        raise Polyrun::Error, "assets:precompile failed: #{err}" unless st.success?
+        st, out, err = Polyrun::ProcessStdio.spawn_wait(
+          nil,
+          exe,
+          "assets:precompile",
+          chdir: rails_root,
+          silent: silent
+        )
+        unless st.success?
+          raise Polyrun::Error, Polyrun::ProcessStdio.format_failure_message("assets:precompile", st, out, err)
+        end
 
         true
       end

data/lib/polyrun/process_stdio.rb

@@ -0,0 +1,91 @@
+require "tempfile"
+
+module Polyrun
+  # Run a subprocess without +Open3+ pipe reader threads (avoids noisy +IOError+s on SIGINT when
+  # streams close). By default stdin/stdout/stderr are inherited so output streams live and the
+  # child can use the TTY for prompts.
+  module ProcessStdio
+    MAX_FAILURE_CAPTURE_BYTES = 32_768
+
+    class << self
+      # @param env [Hash, nil] optional environment for the child (only forwarded when a Hash)
+      # @param argv [Array<String>] command argv
+      # @param silent [Boolean] if true, connect stdin/stdout/stderr to +File::NULL+ (no terminal output;
+      #   non-interactive). Still no Open3 pipe threads.
+      # @return [Process::Status]
+      def inherit_stdio_spawn_wait(env, *argv, chdir: nil, silent: false)
+        st, = spawn_wait(env, *argv, chdir: chdir, silent: silent)
+        st
+      end
+
+      # Like {#inherit_stdio_spawn_wait}, but returns captured stdout/stderr when +silent+ is true.
+      # On success those strings are empty (not read). When +silent+ is false, output goes to the TTY
+      # and returned captures are empty.
+      #
+      # @return [Array(Process::Status, String, String)] status, stdout capture, stderr capture
+      def spawn_wait(env, *argv, chdir: nil, silent: false)
+        args = spawn_argv(env, *argv)
+        return spawn_wait_inherit(args, chdir) unless silent
+
+        spawn_wait_silent(args, chdir)
+      end
+
+      # Builds a diagnostic string for failed subprocesses (used when +silent: true+ hid live output).
+      def format_failure_message(label, status, stdout, stderr)
+        msg = "#{label} failed (exit #{status.exitstatus})"
+        s = stdout.to_s
+        e = stderr.to_s
+        msg << "\n--- stdout ---\n#{s}" unless s.strip.empty?
+        msg << "\n--- stderr ---\n#{e}" unless e.strip.empty?
+        msg
+      end
+
+      private
+
+      def spawn_argv(env, *argv)
+        a = []
+        a << env if env.is_a?(Hash)
+        a.concat(argv)
+        a
+      end
+
+      def spawn_wait_inherit(args, chdir)
+        opts = {in: :in, out: :out, err: :err}
+        opts[:chdir] = chdir if chdir
+        pid = Process.spawn(*args, **opts)
+        st = Process.wait2(pid).last
+        [st, "", ""]
+      end
+
+      def spawn_wait_silent(args, chdir)
+        Tempfile.create("polyrun-out") do |tfout|
+          Tempfile.create("polyrun-err") do |tferr|
+            tfout.close
+            tferr.close
+            out_path = tfout.path
+            err_path = tferr.path
+            opts = {in: File::NULL, out: out_path, err: err_path}
+            opts[:chdir] = chdir if chdir
+            pid = Process.spawn(*args, **opts)
+            st = Process.wait2(pid).last
+            if st.success?
+              [st, "", ""]
+            else
+              out = File.binread(out_path)
+              err = File.binread(err_path)
+              [st, truncate_failure_capture(out), truncate_failure_capture(err)]
+            end
+          end
+        end
+      end
+
+      def truncate_failure_capture(bytes)
+        s = bytes.to_s
+        return s if s.bytesize <= MAX_FAILURE_CAPTURE_BYTES
+
+        tail = s.byteslice(-MAX_FAILURE_CAPTURE_BYTES, MAX_FAILURE_CAPTURE_BYTES)
+        "... (#{s.bytesize} bytes total; showing last #{MAX_FAILURE_CAPTURE_BYTES} bytes)\n" + tail
+      end
+    end
+  end
+end

data/lib/polyrun/quick/runner.rb

@@ -62,6 +62,30 @@ module Polyrun
         new(out: out, err: err, verbose: verbose).run(paths)
       end
 
+      # Files Polyrun::Quick would run with no explicit paths (excludes normal RSpec/Minitest files).
+      def self.parallel_default_paths(cwd = Dir.pwd)
+        base = File.expand_path(cwd)
+        globs = [
+          File.join(base, "spec", "polyrun_quick", "**", "*.rb"),
+          File.join(base, "test", "polyrun_quick", "**", "*.rb"),
+          File.join(base, "spec", "**", "*.rb"),
+          File.join(base, "test", "**", "*.rb")
+        ]
+        globs.flat_map { |g| Dir.glob(g) }.uniq.reject { |p| quick_path_excluded?(p, base) }.sort
+      end
+
+      def self.quick_path_excluded?(path, base)
+        rel = Pathname.new(path).relative_path_from(Pathname.new(base)).to_s
+        parts = rel.split(File::SEPARATOR)
+        bn = File.basename(path)
+        return true if bn.end_with?("_spec.rb", "_test.rb")
+        return true if %w[spec_helper.rb rails_helper.rb test_helper.rb].include?(bn)
+        return true if parts[0] == "spec" && %w[support fixtures factories].include?(parts[1])
+        return true if parts[0] == "test" && %w[support fixtures].include?(parts[1])
+
+        false
+      end
+
       def initialize(out: $stdout, err: $stderr, verbose: false)
         @out = out
         @err = err
@@ -153,27 +177,12 @@ module Polyrun
       end
 
       def default_globs
-        base = File.expand_path(Dir.pwd)
-        globs = [
-          File.join(base, "spec", "polyrun_quick", "**", "*.rb"),
-          File.join(base, "test", "polyrun_quick", "**", "*.rb"),
-          File.join(base, "spec", "**", "*.rb"),
-          File.join(base, "test", "**", "*.rb")
-        ]
-        globs.flat_map { |g| Dir.glob(g) }.uniq.reject { |p| default_quick_exclude?(p, base) }.sort
+        Runner.parallel_default_paths(Dir.pwd)
       end
 
       # Omit RSpec/Minitest files and common helpers so +polyrun quick+ with no args does not load normal suites.
       def default_quick_exclude?(path, base)
-        rel = Pathname.new(path).relative_path_from(Pathname.new(base)).to_s
-        parts = rel.split(File::SEPARATOR)
-        bn = File.basename(path)
-        return true if bn.end_with?("_spec.rb", "_test.rb")
-        return true if %w[spec_helper.rb rails_helper.rb test_helper.rb].include?(bn)
-        return true if parts[0] == "spec" && %w[support fixtures factories].include?(parts[1])
-        return true if parts[0] == "test" && %w[support fixtures].include?(parts[1])
-
-        false
+        Runner.quick_path_excluded?(path, base)
       end
     end
   end

data/lib/polyrun/rspec.rb

@@ -11,5 +11,24 @@ module Polyrun
         Polyrun::Data::ParallelProvisioning.run_suite_hooks!
       end
     end
+
+    # Experimental: add {Timing::RSpecExampleFormatter} and write per-example JSON (see +timing_granularity: example+).
+    # With +output_path:+, that path is used directly (no +ENV+ mutation). Without it, the formatter
+    # reads +ENV["POLYRUN_EXAMPLE_TIMING_OUT"]+ or defaults to +polyrun_timing_examples.json+.
+    def install_example_timing!(output_path: nil)
+      require_relative "timing/rspec_example_formatter"
+      fmt =
+        if output_path
+          op = output_path
+          Class.new(Polyrun::Timing::RSpecExampleFormatter) do
+            define_method(:timing_output_path) { op }
+          end
+        else
+          Polyrun::Timing::RSpecExampleFormatter
+        end
+      ::RSpec.configure do |config|
+        config.add_formatter fmt
+      end
+    end
   end
 end

data/lib/polyrun/templates/POLYRUN.md

@@ -25,7 +25,7 @@ Adjust `--workers` or use `bin/rspec_parallel` if your repo provides a wrapper.
 ### Model B — matrix: one shard per job
 
 - Matrix sets `POLYRUN_SHARD_INDEX` and `POLYRUN_SHARD_TOTAL` explicitly (many runners do not set `CI_NODE_*` by default).
-- Each job runs `polyrun build-paths`, `polyrun plan`, then `bundle exec rspec` for that shard only (see `bin/polyrun-rspec` or `bin/rspec_ci_shard` patterns).
+- Each job runs `polyrun ci-shard-run -- …` (e.g. `-- bundle exec rspec` or `ci-shard-rspec`), or `build-paths` + `plan` + your runner manually. Legacy: `bin/polyrun-rspec` or `bin/rspec_ci_shard` patterns.
 - Upload `coverage/polyrun-fragment-<shard>.json` per job; a `merge-coverage` job downloads all fragments and merges.
 
 Do not combine Model A and Model B in one workflow without a documented reason (nested parallelism and duplicate merges).

data/lib/polyrun/templates/ci_matrix.polyrun.yml

@@ -1,5 +1,8 @@
 # Polyrun — partition contract for CI matrix (one job per POLYRUN_SHARD_INDEX).
-# Each matrix row: set POLYRUN_SHARD_INDEX and POLYRUN_SHARD_TOTAL; run build-paths, plan, rspec.
+# Each matrix row: set POLYRUN_SHARD_INDEX and POLYRUN_SHARD_TOTAL; run:
+#   bundle exec polyrun -c polyrun.yml ci-shard-run -- bundle exec rspec
+# (or ci-shard-rspec; or e.g. ci-shard-run -- bundle exec polyrun quick).
+# Equivalent to build-paths, plan --shard/--total, then run that command with this slice's paths.
 # A separate CI job downloads coverage/polyrun-fragment-*.json and runs merge-coverage.
 # Do not use parallel-rspec with multiple workers inside the same matrix row unless you intend nested parallelism.
 # See: docs/SETUP_PROFILE.md

data/lib/polyrun/timing/merge.rb

@@ -4,7 +4,8 @@ require_relative "../debug"
 
 module Polyrun
   module Timing
-    # Merges per-shard timing JSON files (spec2 §2.4): path => wall seconds (float).
+    # Merges per-shard timing JSON files (spec2 §2.4): path => wall seconds (float), or (experimental)
+    # +absolute_path:line+ => seconds for per-example timing.
     # Disjoint suites: values merged by taking the maximum per path when duplicates appear.
     module Merge
       module_function