polyrun 1.1.0 → 1.3.0

data/lib/polyrun/cli/queue_command.rb

@@ -7,11 +7,18 @@ module Polyrun
       private
 
       # File-backed queue (spec_queue.md): init → claim batches → ack (ledger append-only).
+      #
+      # *N×M and load balancing*: +queue init+ uses the same +Partition::Plan+ slice as +polyrun plan+
+      # when +--shard+ / +--total+ (or +partition.shard_index+ / +shard_total+ / CI env) define a matrix.
+      # Each CI job runs +init+ once for its shard; the queue holds **only** that shard's paths (no duplicate
+      # work across matrix jobs). **M** local workers use +queue claim+ on a **shared** queue directory
+      # (NFS or the runner disk): claims are mutually exclusive — **dynamic** balance (fast workers pull more
+      # batches), **not** the same static per-worker wall time as +cost_binpack+ on the full suite.
+      # +--timing+ on init sorts dequeue order (heavy items first when weights are known); it does **not**
+      # replace binpack across workers — for that, use static +plan+ / +run-shards+ with +cost_binpack+.
       def cmd_queue(argv)
         dir = ".polyrun-queue"
         paths_file = nil
-        timing_path = nil
-        timing_granularity = nil
         worker = ENV["USER"] || "worker"
         batch = 5
         lease_id = nil
@@ -20,7 +27,7 @@ module Polyrun
         Polyrun::Debug.log("queue: subcommand=#{sub.inspect}")
         case sub
         when "init"
-          queue_cmd_init(argv, dir, paths_file, timing_path, timing_granularity)
+          queue_cmd_init(argv, dir)
         when "claim"
           queue_cmd_claim(argv, dir, worker, batch)
         when "ack"
@@ -33,34 +40,54 @@ module Polyrun
         end
       end
 
-      def queue_cmd_init(argv, dir, paths_file, timing_path, timing_granularity)
+      def queue_cmd_init(argv, dir)
+        cfg = Polyrun::Config.load(path: ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        ctx = plan_command_initial_context(pc)
+        paths_file = nil
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun queue init --paths-file P [--timing PATH] [--timing-granularity VAL] [--dir DIR]"
+          opts.banner = "usage: polyrun queue init --paths-file P [--dir DIR] [same partition options as polyrun plan]"
           opts.on("--dir PATH") { |v| dir = v }
-          opts.on("--paths-file PATH") { |v| paths_file = v }
-          opts.on("--timing PATH") { |v| timing_path = v }
-          opts.on("--timing-granularity VAL") { |v| timing_granularity = v }
+          opts.on("--paths-file PATH", String) { |v| paths_file = v }
+          plan_command_register_partition_options!(opts, ctx)
         end.parse!(argv)
         unless paths_file
           Polyrun::Log.warn "queue init: need --paths-file"
           return 2
         end
-        cfg = Polyrun::Config.load(path: ENV["POLYRUN_CONFIG"])
-        g = resolve_partition_timing_granularity(cfg.partition, timing_granularity)
-        items = Polyrun::Partition::Paths.read_lines(paths_file)
-        costs =
-          if timing_path
-            Polyrun::Partition::Plan.load_timing_costs(
-              File.expand_path(timing_path, Dir.pwd),
-              granularity: g
-            )
-          end
-        ordered = queue_init_ordered_items(items, costs, g)
+        code = Polyrun::Partition::PathsBuild.apply!(partition: pc, cwd: Dir.pwd)
+        return code if code != 0
+
+        ordered, code = queue_partition_manifest_and_ordered_paths(cfg, pc, ctx, paths_file)
+        return code if code != 0
+
         Polyrun::Queue::FileStore.new(dir).init!(ordered)
         Polyrun::Log.puts JSON.generate({"dir" => File.expand_path(dir), "count" => ordered.size})
         0
       end
 
+      def queue_partition_manifest_and_ordered_paths(cfg, pc, ctx, paths_file)
+        Polyrun::Log.warn "polyrun queue init: using #{cfg.path}" if @verbose && cfg.path
+
+        manifest, code = plan_command_manifest_from_paths(cfg, pc, [], ctx, paths_file)
+        return [nil, code] if code != 0
+
+        paths = manifest["paths"] || []
+        g = resolve_partition_timing_granularity(pc, ctx[:timing_granularity])
+        timing_for_sort = plan_resolve_timing_path(pc, ctx[:timing_path], ctx[:strategy])
+        costs = queue_init_timing_costs(timing_for_sort, g)
+        [queue_init_ordered_items(paths, costs, g), 0]
+      end
+
+      def queue_init_timing_costs(timing_for_sort, g)
+        return nil unless timing_for_sort
+
+        Polyrun::Partition::Plan.load_timing_costs(
+          File.expand_path(timing_for_sort.to_s, Dir.pwd),
+          granularity: g
+        )
+      end
+
       def queue_init_ordered_items(items, costs, granularity = :file)
         if costs && !costs.empty?
           dw = costs.values.sum / costs.size.to_f

data/lib/polyrun/cli/run_shards_command.rb

@@ -12,12 +12,10 @@ module Polyrun
 
       private
 
-      # Default and upper bound for parallel OS processes (POLYRUN_WORKERS / --workers).
-      DEFAULT_PARALLEL_WORKERS = 5
-      MAX_PARALLEL_WORKERS = 10
+      # Default and upper bound for parallel OS processes (POLYRUN_WORKERS / --workers); see {Polyrun::Config}.
 
       # Spawns N OS processes (not Ruby threads) with POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL so
-      # {Coverage::Collector} writes coverage/polyrun-fragment-<shard>.json. Merge with merge-coverage.
+      # {Coverage::Collector} writes coverage/polyrun-fragment-worker<N>.json (or shard<S>-worker<W>.json in N×M CI). Merge with merge-coverage.
       def cmd_run_shards(argv, config_path)
         run_shards_run!(argv, config_path)
       end
@@ -37,6 +35,54 @@ module Polyrun
         cmd_run_shards(combined, config_path)
       end
 
+      # Same as parallel-rspec but runs +bundle exec rails test+ or +bundle exec ruby -I test+ after +--+.
+      def cmd_parallel_minitest(argv, config_path)
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        code = start_bootstrap!(cfg, argv, config_path)
+        return code if code != 0
+
+        sep = argv.index("--")
+        combined =
+          if sep
+            head = argv[0...sep]
+            tail = argv[sep..]
+            head + ["--merge-coverage"] + tail
+          else
+            argv + ["--merge-coverage", "--"] + minitest_parallel_cmd
+          end
+        Polyrun::Debug.log_kv(parallel_minitest: "combined argv", argv: combined)
+        cmd_run_shards(combined, config_path)
+      end
+
+      # Same as parallel-rspec but runs +bundle exec polyrun quick+ after +--+ (one Quick process per shard).
+      # Run from the app root with +bundle exec+ so workers resolve the same gem as the parent (same concern as +bundle exec rspec+).
+      def cmd_parallel_quick(argv, config_path)
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        code = start_bootstrap!(cfg, argv, config_path)
+        return code if code != 0
+
+        sep = argv.index("--")
+        combined =
+          if sep
+            head = argv[0...sep]
+            tail = argv[sep..]
+            head + ["--merge-coverage"] + tail
+          else
+            argv + ["--merge-coverage", "--", "bundle", "exec", "polyrun", "quick"]
+          end
+        Polyrun::Debug.log_kv(parallel_quick: "combined argv", argv: combined)
+        cmd_run_shards(combined, config_path)
+      end
+
+      def minitest_parallel_cmd
+        rails_bin = File.expand_path("bin/rails", Dir.pwd)
+        if File.file?(rails_bin)
+          ["bundle", "exec", "rails", "test"]
+        else
+          ["bundle", "exec", "ruby", "-I", "test"]
+        end
+      end
+
       # Convenience alias: optional legacy script/build_spec_paths.rb (if present and partition.paths_build unset), then parallel-rspec.
       def cmd_start(argv, config_path)
         cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
@@ -66,10 +112,21 @@ module Polyrun
       end
 
       # ENV for a worker process: POLYRUN_SHARD_* plus per-shard database URLs from polyrun.yml or DATABASE_URL.
-      def shard_child_env(cfg:, workers:, shard:)
+      # When +matrix_total+ > 1 with multiple local workers, sets +POLYRUN_SHARD_MATRIX_INDEX+ / +POLYRUN_SHARD_MATRIX_TOTAL+
+      # so {Coverage::Collector} can name fragments uniquely across CI matrix jobs (NxM sharding).
+      def shard_child_env(cfg:, workers:, shard:, matrix_index: nil, matrix_total: nil)
         child_env = ENV.to_h.merge(
           Polyrun::Database::Shard.env_map(shard_index: shard, shard_total: workers)
         )
+        mt = matrix_total.nil? ? 0 : Integer(matrix_total)
+        if mt > 1
+          if matrix_index.nil?
+            Polyrun::Log.warn "polyrun run-shards: matrix_total=#{mt} but matrix_index is nil; omit POLYRUN_SHARD_MATRIX_*"
+          else
+            child_env["POLYRUN_SHARD_MATRIX_INDEX"] = Integer(matrix_index).to_s
+            child_env["POLYRUN_SHARD_MATRIX_TOTAL"] = mt.to_s
+          end
+        end
         dh = cfg.databases
         if dh.is_a?(Hash) && !dh.empty?
           child_env.merge!(Polyrun::Database::UrlBuilder.env_exports_for_databases(dh, shard_index: shard))

data/lib/polyrun/cli/run_shards_plan_boot_phases.rb

@@ -25,7 +25,7 @@ module Polyrun
       end
 
       def run_shards_plan_phase_b(o, cmd, cfg, pc, run_t0, config_path)
-        items, paths_source, err = run_shards_resolve_items(o[:paths_file])
+        items, paths_source, err = run_shards_resolve_items(o[:paths_file], pc)
         return [err, nil] if err
 
         costs, strategy, err = run_shards_resolve_costs(o[:timing_path], o[:strategy], o[:timing_granularity])

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -15,7 +15,7 @@ module Polyrun
 
       def run_shards_plan_options_state(pc)
         {
-          workers: env_int("POLYRUN_WORKERS", RunShardsCommand::DEFAULT_PARALLEL_WORKERS),
+          workers: env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS),
           paths_file: nil,
           strategy: (pc["strategy"] || pc[:strategy] || "round_robin").to_s,
           seed: pc["seed"] || pc[:seed],

data/lib/polyrun/cli/run_shards_planning.rb

@@ -38,9 +38,9 @@ module Polyrun
           Polyrun::Log.warn "polyrun run-shards: --workers must be >= 1"
           return 2
         end
-        if w > RunShardsCommand::MAX_PARALLEL_WORKERS
-          Polyrun::Log.warn "polyrun run-shards: capping --workers / POLYRUN_WORKERS from #{w} to #{RunShardsCommand::MAX_PARALLEL_WORKERS}"
-          o[:workers] = RunShardsCommand::MAX_PARALLEL_WORKERS
+        if w > Polyrun::Config::MAX_PARALLEL_WORKERS
+          Polyrun::Log.warn "polyrun run-shards: capping --workers / POLYRUN_WORKERS from #{w} to #{Polyrun::Config::MAX_PARALLEL_WORKERS}"
+          o[:workers] = Polyrun::Config::MAX_PARALLEL_WORKERS
         end
         nil
       end
@@ -53,18 +53,18 @@ module Polyrun
         nil
       end
 
-      def run_shards_resolve_items(paths_file)
-        resolved = Polyrun::Partition::Paths.resolve_run_shard_items(paths_file: paths_file)
+      def run_shards_resolve_items(paths_file, partition)
+        resolved = Polyrun::Partition::Paths.resolve_run_shard_items(paths_file: paths_file, partition: partition)
         if resolved[:error]
           Polyrun::Log.warn "polyrun run-shards: #{resolved[:error]}"
           return [nil, nil, 2]
         end
         items = resolved[:items]
         paths_source = resolved[:source]
-        Polyrun::Log.warn "polyrun run-shards: #{items.size} spec path(s) from #{paths_source}"
+        Polyrun::Log.warn "polyrun run-shards: #{items.size} path(s) from #{paths_source}"
 
         if items.empty?
-          Polyrun::Log.warn "polyrun run-shards: no spec paths (spec/spec_paths.txt, partition.paths_file, or spec/**/*_spec.rb)"
+          Polyrun::Log.warn "polyrun run-shards: no paths (empty paths file or list)"
           return [nil, nil, 2]
         end
         [items, paths_source, nil]
@@ -119,7 +119,7 @@ module Polyrun
 
       def run_shards_warn_parallel_banner(item_count, workers, strategy)
         Polyrun::Log.warn <<~MSG
-          polyrun run-shards: #{item_count} spec path(s) -> #{workers} parallel worker processes (not Ruby threads); strategy=#{strategy}
+          polyrun run-shards: #{item_count} path(s) -> #{workers} parallel worker processes (not Ruby threads); strategy=#{strategy}
           (plain `bundle exec rspec` is one process; this command fans out.)
         MSG
       end

data/lib/polyrun/cli/run_shards_run.rb

@@ -50,6 +50,8 @@ module Polyrun
         cfg = ctx[:cfg]
         plan = ctx[:plan]
         parallel = ctx[:parallel]
+        mx = ctx[:matrix_shard_index]
+        mt = ctx[:matrix_shard_total]
 
         pids = []
         workers.times do |shard|
@@ -59,7 +61,7 @@ module Polyrun
             next
           end
 
-          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard)
+          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard, matrix_index: mx, matrix_total: mt)
 
           Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
           pid = Process.spawn(child_env, *cmd, *paths)
@@ -140,7 +142,7 @@ module Polyrun
 
         if ctx[:parallel]
           Polyrun::Log.warn <<~MSG
-            polyrun run-shards: coverage — each worker writes coverage/polyrun-fragment-<shard>.json when Polyrun coverage is enabled (POLYRUN_SHARD_INDEX per process).
+            polyrun run-shards: coverage — each worker writes coverage/polyrun-fragment-worker<N>.json when Polyrun coverage is enabled (POLYRUN_SHARD_INDEX per process).
             polyrun run-shards: next step — merge with: polyrun merge-coverage -i 'coverage/polyrun-fragment-*.json' -o coverage/merged.json --format json,cobertura,console
           MSG
         end

data/lib/polyrun/cli/start_bootstrap.rb

@@ -4,10 +4,6 @@ module Polyrun
     module StartBootstrap
       private
 
-      # Keep in sync with {RunShardsCommand} worker defaults.
-      START_ARG_WORKERS_DEFAULT = 5
-      START_ARG_WORKERS_MAX = 10
-
       def start_bootstrap!(cfg, argv, config_path)
         if start_run_prepare?(cfg) && !truthy_env?("POLYRUN_START_SKIP_PREPARE")
           recipe = cfg.prepare["recipe"] || cfg.prepare[:recipe] || "default"
@@ -76,7 +72,7 @@ module Polyrun
       def parse_workers_from_start_argv(argv)
         sep = argv.index("--")
         head = sep ? argv[0...sep] : argv
-        workers = env_int("POLYRUN_WORKERS", START_ARG_WORKERS_DEFAULT)
+        workers = env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS)
         i = 0
         while i < head.size
           if head[i] == "--workers" && head[i + 1]
@@ -87,7 +83,7 @@ module Polyrun
             i += 1
           end
         end
-        workers.clamp(1, START_ARG_WORKERS_MAX)
+        workers.clamp(1, Polyrun::Config::MAX_PARALLEL_WORKERS)
       end
 
       def truthy_env?(name)

data/lib/polyrun/cli.rb

@@ -12,7 +12,11 @@ require_relative "cli/queue_command"
 require_relative "cli/timing_command"
 require_relative "cli/init_command"
 require_relative "cli/quick_command"
+require_relative "cli/ci_shard_run_parse"
 require_relative "cli/ci_shard_run_command"
+require_relative "cli/config_command"
+require_relative "cli/default_run"
+require_relative "cli/help"
 
 module Polyrun
   class CLI
@@ -21,6 +25,18 @@ module Polyrun
       "ci-shard-rspec" => :cmd_ci_shard_rspec
     }.freeze
 
+    # Keep in sync with +dispatch_cli_command_subcommands+ (+when+ branches). Used for implicit path routing.
+    DISPATCH_SUBCOMMAND_NAMES = %w[
+      plan prepare merge-coverage report-coverage report-junit report-timing
+      env config merge-timing db:setup-template db:setup-shard db:clone-shards
+      run-shards parallel-rspec start build-paths init queue quick
+    ].freeze
+
+    # First argv token that is a normal subcommand (not a path); if argv[0] is not here but looks like paths, run implicit parallel.
+    IMPLICIT_PATH_EXCLUSION_TOKENS = (
+      DISPATCH_SUBCOMMAND_NAMES + CI_SHARD_COMMANDS.keys + %w[help version]
+    ).freeze
+
     include Helpers
     include PlanCommand
     include PrepareCommand
@@ -33,7 +49,11 @@ module Polyrun
     include TimingCommand
     include InitCommand
     include QuickCommand
+    include CiShardRunParse
     include CiShardRunCommand
+    include ConfigCommand
+    include DefaultRun
+    include Help
 
     def self.run(argv = ARGV)
       new.run(argv)
@@ -44,12 +64,30 @@ module Polyrun
       config_path = parse_global_cli!(argv)
       return config_path if config_path.is_a?(Integer)
 
-      command = argv.shift
-      if command.nil?
-        print_help
-        return 0
+      if argv.empty?
+        Polyrun::Debug.log_kv(
+          command: "(default)",
+          cwd: Dir.pwd,
+          polyrun_config: config_path,
+          argv_rest: [],
+          verbose: @verbose
+        )
+        return dispatch_default_parallel!(config_path)
+      end
+
+      if implicit_parallel_run?(argv)
+        Polyrun::Debug.log_kv(
+          command: "(paths)",
+          cwd: Dir.pwd,
+          polyrun_config: config_path,
+          argv_rest: argv.dup,
+          verbose: @verbose
+        )
+        return dispatch_implicit_parallel_targets!(argv, config_path)
       end
 
+      command = argv.shift
+
       Polyrun::Debug.log_kv(
         command: command,
         cwd: Dir.pwd,
@@ -96,6 +134,7 @@ module Polyrun
       end
     end
 
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity -- explicit dispatch table
     def dispatch_cli_command_subcommands(command, argv, config_path)
       case command
       when "plan"
@@ -112,6 +151,8 @@ module Polyrun
         cmd_report_timing(argv)
       when "env"
         cmd_env(argv, config_path)
+      when "config"
+        cmd_config(argv, config_path)
       when "merge-timing"
         cmd_merge_timing(argv)
       when "db:setup-template"
@@ -141,52 +182,7 @@ module Polyrun
         2
       end
     end
-
-    def print_help
-      Polyrun::Log.puts <<~HELP
-        usage: polyrun [global options] <command> [options]
-
-        global:
-          -c, --config PATH    polyrun.yml path (or POLYRUN_CONFIG)
-          -v, --verbose
-          -h, --help
-
-        Trace timing (stderr): DEBUG=1 or POLYRUN_DEBUG=1
-        Branch coverage in JSON fragments: POLYRUN_COVERAGE_BRANCHES=1 (stdlib Coverage; merge-coverage merges branches)
-        polyrun quick coverage: POLYRUN_COVERAGE=1 or (config/polyrun_coverage.yml + POLYRUN_QUICK_COVERAGE=1); POLYRUN_COVERAGE_DISABLE=1 skips
-        Merge wall time (stderr): POLYRUN_PROFILE_MERGE=1 (or verbose / DEBUG)
-        Post-merge formats (run-shards): POLYRUN_MERGE_FORMATS (default: json,lcov,cobertura,console,html)
-        Skip optional script/build_spec_paths.rb before start: POLYRUN_SKIP_BUILD_SPEC_PATHS=1
-        Skip start auto-prepare / auto DB provision: POLYRUN_START_SKIP_PREPARE=1, POLYRUN_START_SKIP_DATABASES=1
-        Skip writing paths_file from partition.paths_build: POLYRUN_SKIP_PATHS_BUILD=1
-        Warn if merge-coverage wall time exceeds N seconds (default 10): POLYRUN_MERGE_SLOW_WARN_SECONDS (0 disables)
-        Parallel RSpec workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start)
-        Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
-
-        commands:
-          version              print version
-          plan                 emit partition manifest JSON
-          prepare              run prepare recipe: default | assets (optional prepare.command overrides bin/rails assets:precompile) | shell (prepare.command required)
-          merge-coverage       merge SimpleCov JSON fragments (json/lcov/cobertura/console)
-          run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage
-          parallel-rspec       run-shards + merge-coverage (defaults to: bundle exec rspec after --)
-          start                parallel-rspec; auto-runs prepare (shell/assets) and db:setup-* when polyrun.yml configures them; legacy script/build_spec_paths.rb if paths_build absent
-          ci-shard-run         CI matrix: build-paths + plan for POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL (or config), then run your command with that shard's paths after -- (like run-shards; not multi-worker)
-          ci-shard-rspec       same as ci-shard-run -- bundle exec rspec; optional -- [rspec-only flags]
-          build-paths          write partition.paths_file from partition.paths_build (same as auto step before plan/run-shards)
-          init                 write a starter polyrun.yml or POLYRUN.md from built-in templates (see docs/SETUP_PROFILE.md)
-          queue                file-backed batch queue (init / claim / ack / status)
-          quick                run Polyrun::Quick (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
-          report-coverage      write all coverage formats from one JSON file
-          report-junit         RSpec JSON or Polyrun testcase JSON → JUnit XML (CI)
-          report-timing        print slow-file summary from merged timing JSON
-          merge-timing         merge polyrun_timing_*.json shards
-          env                  print shard + database env (see polyrun.yml databases)
-          db:setup-template    migrate template DB (PostgreSQL)
-          db:setup-shard       CREATE DATABASE shard FROM template (one POLYRUN_SHARD_INDEX)
-          db:clone-shards      migrate templates + DROP/CREATE all shard DBs (replaces clone_shard shell scripts)
-      HELP
-    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
     def cmd_version
       Polyrun::Log.puts "polyrun #{Polyrun::VERSION}"

data/lib/polyrun/config/dotted_path.rb

@@ -0,0 +1,21 @@
+module Polyrun
+  class Config
+    # Read nested keys from loaded YAML (+String+ / +Symbol+ indifferent at each step).
+    module DottedPath
+      module_function
+
+      def dig(raw, dotted)
+        segments = dotted.split(".")
+        return nil if segments.empty?
+        return nil if segments.any?(&:empty?)
+
+        segments.reduce(raw) do |m, seg|
+          break nil if m.nil?
+          break nil unless m.is_a?(Hash)
+
+          m[seg] || m[seg.to_sym]
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/config/effective.rb

@@ -0,0 +1,72 @@
+require_relative "dotted_path"
+require_relative "resolver"
+
+module Polyrun
+  class Config
+    # Nested hash of values Polyrun uses: loaded YAML (string keys) with overlays for
+    # merged +prepare.env+, resolved +partition.shard_index+ / +shard_total+ / +shard_processes+ / +timing_granularity+,
+    # and top-level +workers+ (+POLYRUN_WORKERS+ default).
+    #
+    # +build+ memoizes the last (cfg, env) in-process so repeated +dig+ calls on the same load do not
+    # rebuild the tree (single-threaded CLI).
+    module Effective
+      class << self
+        # Per-thread cache avoids rebuilding the effective tree on repeated +dig+; no class ivars (RuboCop ThreadSafety).
+        def build(cfg, env: ENV)
+          key = cache_key(cfg, env)
+          per_thread = (Thread.current[:polyrun_effective_build] ||= {})
+          per_thread[key] ||= build_uncached(cfg, env: env)
+        end
+
+        def dig(cfg, dotted_path, env: ENV)
+          Polyrun::Config::DottedPath.dig(build(cfg, env: env), dotted_path)
+        end
+
+        private
+
+        def cache_key(cfg, env)
+          [cfg.path, cfg.object_id, env_fingerprint(env)]
+        end
+
+        def env_fingerprint(env)
+          env.to_h.keys.sort.map { |k| [k, env[k]] }.hash
+        end
+
+        def build_uncached(cfg, env:)
+          r = Polyrun::Config::Resolver
+          base = deep_stringify_keys(cfg.raw)
+
+          prep = cfg.prepare
+          base["prepare"] = deep_stringify_keys(prep)
+          base["prepare"]["env"] = r.merged_prepare_env(prep, env)
+
+          pc = cfg.partition
+          part = deep_stringify_keys(pc).merge(
+            "shard_index" => r.resolve_shard_index(pc, env),
+            "shard_total" => r.resolve_shard_total(pc, env),
+            "shard_processes" => r.resolve_shard_processes(pc, env),
+            "timing_granularity" => r.resolve_partition_timing_granularity(pc, nil, env).to_s
+          )
+          base["partition"] = part
+
+          base["workers"] = r.parallel_worker_count_default(env)
+
+          base
+        end
+
+        def deep_stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) do |(k, v), m|
+              m[k.to_s] = deep_stringify_keys(v)
+            end
+          when Array
+            obj.map { |e| deep_stringify_keys(e) }
+          else
+            obj
+          end
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/config/resolver.rb

@@ -0,0 +1,78 @@
+require_relative "../env/ci"
+require_relative "../partition/timing_keys"
+
+module Polyrun
+  class Config
+    # Single source for values derived from +polyrun.yml+, +ENV+, and CI detection.
+    # Used by {Effective}, CLI helpers, and prepare.
+    module Resolver
+      module_function
+
+      def env_int(name, fallback, env = ENV)
+        s = env[name]
+        return fallback if s.nil? || s.empty?
+
+        Integer(s, exception: false) || fallback
+      end
+
+      def prepare_env_yaml_string_map(prep)
+        (prep["env"] || prep[:env] || {}).transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      # Same merge order as +polyrun prepare+: YAML +prepare.env+ overrides process +ENV+ for overlapping keys.
+      def merged_prepare_env(prep, env = ENV)
+        prep_env = prepare_env_yaml_string_map(prep)
+        env.to_h.merge(prep_env)
+      end
+
+      def partition_int(pc, keys, default)
+        keys.each do |k|
+          v = pc[k] || pc[k.to_sym]
+          next if v.nil? || v.to_s.empty?
+
+          i = Integer(v, exception: false)
+          return i unless i.nil?
+        end
+        default
+      end
+
+      def resolve_shard_index(pc, env = ENV)
+        return Integer(env["POLYRUN_SHARD_INDEX"]) if env["POLYRUN_SHARD_INDEX"] && !env["POLYRUN_SHARD_INDEX"].empty?
+
+        ci = Polyrun::Env::Ci.detect_shard_index
+        return ci unless ci.nil?
+
+        partition_int(pc, %w[shard_index shard], 0)
+      end
+
+      def resolve_shard_total(pc, env = ENV)
+        return Integer(env["POLYRUN_SHARD_TOTAL"]) if env["POLYRUN_SHARD_TOTAL"] && !env["POLYRUN_SHARD_TOTAL"].empty?
+
+        ci = Polyrun::Env::Ci.detect_shard_total
+        return ci unless ci.nil?
+
+        partition_int(pc, %w[shard_total total], 1)
+      end
+
+      # Processes per CI matrix job for +ci-shard-run+ / +ci-shard-rspec+ (NxM: N jobs × M processes).
+      # +POLYRUN_SHARD_PROCESSES+ or +partition.shard_processes+; CLI +--shard-processes+ / +--workers+ overrides.
+      def resolve_shard_processes(pc, env = ENV)
+        return Integer(env["POLYRUN_SHARD_PROCESSES"]) if env["POLYRUN_SHARD_PROCESSES"] && !env["POLYRUN_SHARD_PROCESSES"].empty?
+
+        partition_int(pc, %w[shard_processes shard_workers workers_per_shard], 1)
+      end
+
+      # +cli_val+ is an override (e.g. +run-shards --timing-granularity+); +nil+ uses YAML then +POLYRUN_TIMING_GRANULARITY+.
+      def resolve_partition_timing_granularity(pc, cli_val, env = ENV)
+        raw = cli_val
+        raw ||= pc && (pc["timing_granularity"] || pc[:timing_granularity])
+        raw ||= env["POLYRUN_TIMING_GRANULARITY"]
+        Polyrun::Partition::TimingKeys.normalize_granularity(raw || "file")
+      end
+
+      def parallel_worker_count_default(env = ENV)
+        env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS, env)
+      end
+    end
+  end
+end

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"