hecks 3.5.0 → 3.6.0

data/lib/hecks/tools/era_reattest.rb

@@ -3,6 +3,7 @@
 require "hecks"
 require "json"
 require_relative "../tools"
+require_relative "era_reattest/reporting"
 
 module Hecks
   module Tools
@@ -14,6 +15,8 @@ module Hecks
     module EraReattest
       USAGE = "usage: hecks reattest <domain> <era ordinal> [--accept]"
 
+      extend Reporting
+
       module_function
 
       # Shows the held text against its recorded digest and, with `--accept`, re-freezes it.
@@ -57,20 +60,25 @@ module Hecks
       def open_lineage(registry, bluebook)
         first = bluebook.aggregates.first or abort "#{bluebook.name} declares no aggregates"
         adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
-        capable =
-          begin
-            adapter_class = registry.adapter_class(adapter_name)
-            adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
-          rescue StandardError
-            false
-          end
         # Only a lineage-capable adapter holds era texts.
-        unless capable
+        unless lineage_capable?(registry, adapter_name)
           abort "#{bluebook.name} is bound to #{adapter_name}, which holds no eras — " \
                 "there is no frozen text to re-attest."
         end
 
         settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
+        ensured_lineage(bluebook, settings)
+      end
+
+      def lineage_capable?(registry, adapter_name)
+        adapter_class = registry.adapter_class(adapter_name)
+        adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
+      rescue StandardError
+        false
+      end
+
+      # @return [Object] the domain's lineage, with its base tables ensured
+      def ensured_lineage(bluebook, settings)
         db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
         lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
         lineage.ensure_base!
@@ -82,19 +90,19 @@ module Hecks
         text = era[:held_text]
         stored = era[:held_digest]
         computed = Digest::SHA256.hexdigest(text)
-        if stored == computed
-          puts "#{bluebook.name} era #{ordinal}: the held text matches its digest — nothing to re-attest."
-          return 0
-        end
+        return matches_digest(bluebook, ordinal) if stored == computed
 
-        puts "#{bluebook.name} era #{ordinal}: the held text does NOT match its recorded digest."
-        puts "  recorded: #{stored || '(none)'}"
-        puts "  computed: #{computed}"
+        report_mismatch(bluebook, ordinal, stored, computed)
         return 1 unless shape_unchanged?(bluebook, era, ordinal, text)
 
         show(text)
         return refuse_without_accept unless accept
 
+        attest(lineage, ordinal)
+      end
+
+      # @return [Integer] 0
+      def attest(lineage, ordinal)
         fresh = lineage.reattest!(ordinal)
         puts
         puts "ATTESTED: era #{ordinal} re-frozen as #{fresh[0, 12]}… — the old and new digests are recorded."
@@ -105,18 +113,7 @@ module Hecks
       #
       # @return [Boolean] false after printing the refusal
       def shape_unchanged?(bluebook, era, ordinal, text)
-        stored_projection = era[:held_projection] && JSON.parse(era[:held_projection])
-        verdict = Hecks::Translation::Reattest.shape_guard!(
-          domain: bluebook.name, ordinal: ordinal, text: text,
-          stored_hash: era[:hash], stored_projection: stored_projection
-        )
-        case verdict
-        when :cosmetic
-          puts "  shape:    unchanged — the edit is cosmetic (the text still projects to era #{ordinal}'s " \
-               "minted name)"
-        when :unnamed
-          puts "  shape:    era #{ordinal} was never named, so no shape comparison is possible — read carefully"
-        end
+        report_shape(shape_verdict(bluebook, era, ordinal, text), ordinal)
         true
       rescue Hecks::Runtime::WiringError => e
         puts
@@ -124,22 +121,14 @@ module Hecks
         false
       end
 
-      # @return [void]
-      def show(text)
-        puts
-        puts "The held text AS IT NOW STANDS — the original is gone; this is what you would be attesting to:"
-        puts "─" * 72
-        puts text
-        puts "─" * 72
-      end
-
-      # @return [Integer] 1
-      def refuse_without_accept
-        puts
-        puts "REFUSED: nothing changed. If you have read the text above and accept it as this era's"
-        puts "frozen source, run again with --accept. The attestation (old digest, new digest, when)"
-        puts "goes on the record either way you decide."
-        1
+      # @return [Symbol, nil] what the shape guard found, `:cosmetic` or `:unnamed`
+      # @raise [Hecks::Runtime::WiringError] when the held text changed the era's shape
+      def shape_verdict(bluebook, era, ordinal, text)
+        stored_projection = era[:held_projection] && JSON.parse(era[:held_projection])
+        Hecks::Translation::Reattest.shape_guard!(
+          domain: bluebook.name, ordinal: ordinal, text: text,
+          stored_hash: era[:hash], stored_projection: stored_projection
+        )
       end
     end
   end

data/lib/hecks/tools/evolve_run/arguments.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module EvolveRun
+      # The lifecycle of a keyword's argument: `argument-propose`, `argument-admit`,
+      # `argument-deprecate` and `argument-retire`.
+      module Arguments
+        # @return [Boolean] whether the gates held
+        def propose_argument(args, evolve, root)
+          keyword = args.shift or abort "argument-propose which keyword's argument?"
+          context = evolve.option(args, "context") or abort "--context is required"
+          kind = evolve.option(args, "kind") or abort "--kind is required — text|symbol|number|flag|literal|constant|pairs|list"
+          ok = guarded("#{keyword} argument", context, evolve, root) do
+            evolve.propose_argument(keyword: keyword, context: context, kind: kind, **argument_options(args, evolve))
+          end
+          puts_argument_proposed(context, keyword) if ok
+          ok
+        end
+
+        # @return [Boolean] whether the gates held
+        def set_argument_status(command, args, evolve, root)
+          keyword = args.shift or abort "#{command} which keyword's argument?"
+          context = evolve.option(args, "context") or abort "--context is required"
+          guarded("#{keyword} argument", context, evolve, root) do
+            evolve.set_argument_status(keyword: keyword, context: context, to: ARGUMENT_STATUS.fetch(command),
+                                       at: evolve.option(args, "at", ""), named: evolve.option(args, "named", ""))
+          end
+        end
+
+        private
+
+        def argument_options(args, evolve)
+          { required: evolve.option(args, "required", "false"),
+            at: evolve.option(args, "at", ""), named: evolve.option(args, "named", ""),
+            fills: evolve.option(args, "fills", ""),
+            pairs_shape: evolve.option(args, "pairs-shape") }
+        end
+
+        def puts_argument_proposed(context, keyword)
+          puts "Proposed. It reaches no projection until admitted. Before `hecks evolve argument-admit`:"
+          puts "  1. teach the #{context} builder's #{keyword} method the argument"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/evolve_run/words.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module EvolveRun
+      # The lifecycle of a word: `propose`, `admit`, `deprecate`, `retire` and `rename`.
+      module Words
+        # @return [Boolean] whether the gates held
+        def propose(args, evolve, root)
+          word = args.shift or abort "propose what word?"
+          context = evolve.option(args, "context") or abort "--context is required — a word is a word somewhere"
+          ok = guarded(word, context, evolve, root) do
+            evolve.propose(word: word, context: context, **proposal_options(args, evolve))
+          end
+          puts_proposed(context) if ok
+          ok
+        end
+
+        # @return [Boolean] whether the gates held
+        def set_status(command, args, evolve, root)
+          word = args.shift or abort "#{command} what word?"
+          context = evolve.option(args, "context") or abort "--context is required"
+          guarded(word, context, evolve, root) do
+            evolve.set_status(word: word, context: context, to: WORD_STATUS.fetch(command))
+          end
+        end
+
+        # @return [Boolean] whether the gates held
+        def rename(args, evolve, root)
+          word = args.shift or abort "rename what word?"
+          context = evolve.option(args, "context") or abort "--context is required"
+          to = evolve.option(args, "to") or abort "--to is required — a rename goes somewhere"
+          ok = guarded(word, context, evolve, root) { evolve.rename(word: word, context: context, to: to) }
+          puts_renamed(context, word, to) if ok
+          ok
+        end
+
+        private
+
+        def proposal_options(args, evolve)
+          { body: evolve.option(args, "body", "none"), inner: evolve.option(args, "inner", ""),
+            opens: evolve.option(args, "opens", ""), fills: evolve.option(args, "fills", "") }
+        end
+
+        def puts_proposed(context)
+          puts "Proposed. It reaches no projection until admitted. Before `hecks evolve admit`:"
+          puts "  1. teach the #{context} builder the word (and its spec/dsl_spec example)"
+        end
+
+        def puts_renamed(context, word, to)
+          puts "Renamed. The old spelling keeps parsing — that is the point. Before this holds:"
+          puts "  1. alias the new word to the old in the #{context} builder (alias_method :#{to}, :#{word})"
+          puts "  2. add the identical-IR example to spec/dsl_spec.rb"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/evolve_run.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "../tools"
+require_relative "evolve_run/words"
+require_relative "evolve_run/arguments"
 
 module Hecks
   module Tools
@@ -34,6 +36,9 @@ module Hecks
               "<keyword> --context <Context> [--kind K] [--at N] [--named NAME] [--required true|false] " \
               "[--fills F]"
 
+      extend Words
+      extend Arguments
+
       module_function
 
       # Runs one lifecycle command.
@@ -45,21 +50,23 @@ module Hecks
       def main(argv, root: Tools::ROOT)
         require "hecks/grammar/evolve"
         args = argv.dup
-        command = args.shift
-        evolve = Hecks::Grammar::Evolve
-        ok =
-          case command
-          when "status" then status(evolve)
-          when "propose" then propose(args, evolve, root)
-          when *WORD_STATUS.keys then set_status(command, args, evolve, root)
-          when "rename" then rename(args, evolve, root)
-          when "argument-propose" then propose_argument(args, evolve, root)
-          when *ARGUMENT_STATUS.keys then set_argument_status(command, args, evolve, root)
-          else abort USAGE
-          end
+        ok = run_command(args.shift, args, Hecks::Grammar::Evolve, root)
         ok == false ? 1 : 0
       end
 
+      # @return [Boolean, nil] whether the command's gates held
+      def run_command(command, args, evolve, root)
+        case command
+        when "status" then status(evolve)
+        when "propose" then propose(args, evolve, root)
+        when *WORD_STATUS.keys then set_status(command, args, evolve, root)
+        when "rename" then rename(args, evolve, root)
+        when "argument-propose" then propose_argument(args, evolve, root)
+        when *ARGUMENT_STATUS.keys then set_argument_status(command, args, evolve, root)
+        else abort USAGE
+        end
+      end
+
       # Rewrites spec/golden/ir/Bluebook.json by running its spec with `GOLDEN=rewrite`.
       #
       # @param root [String] the checkout
@@ -87,102 +94,48 @@ module Hecks
       # @param root [String] the checkout
       # @return [Boolean] true if the block ran and the gates held
       def guarded(word, context, evolve, root, &)
+        edit_and_gate(word, context, evolve, root, &)
+      rescue StandardError => e
+        # `restore_on_raise` has already restored the files; this only reports.
+        puts "\nRESTORED — #{e.message} Nothing was changed."
+        false
+      end
+
+      # @return [Boolean] true if the block ran and the gates held; false after restoring the
+      #   snapshots when a gate refused
+      def edit_and_gate(word, context, evolve, root, &) # rubocop:disable Naming/PredicateMethod -- the edit's verdict
         paths = evolve.syntax_paths + [File.join(root, "spec/golden/ir/Bluebook.json")]
         snapshots = paths.to_h { |path| [path, File.read(path)] }
         evolve.restore_on_raise(paths, &)
         regenerate!(root)
         if gates_pass?(root)
           puts "\n#{context}.#{word} — the gates hold. Regenerated projections and the golden are in the tree."
-          true
-        else
-          snapshots.each { |path, content| File.write(path, content) }
-          puts "\nRESTORED — the gates refused, and the failures above are the checklist. " \
-               "Nothing was changed."
-          false
+          return true
         end
-      rescue StandardError => e
-        # `restore_on_raise` has already restored the files; this only reports.
-        puts "\nRESTORED — #{e.message} Nothing was changed."
+        restore(snapshots)
         false
       end
 
+      # Puts every snapshot back after a gate refused.
+      def restore(snapshots)
+        snapshots.each { |path, content| File.write(path, content) }
+        puts "\nRESTORED — the gates refused, and the failures above are the checklist. " \
+             "Nothing was changed."
+      end
+
       # @return [true]
-      def status(evolve) # rubocop:disable Naming/PredicateMethod
+      def status(evolve) # rubocop:disable Naming/PredicateMethod -- the command always succeeds
         rows = evolve.keyword_rows
         moving = rows.reject { |row| row[:status] == "admitted" }
         renamed = rows.reject { |row| row[:was].to_s.empty? }
         puts "#{rows.size} keyword rows; #{moving.size} not simply admitted; #{renamed.size} renamed"
-        moving.each { |row| puts "  #{row[:status].ljust(10)} #{row[:context]}.#{row[:word]}" }
-        renamed.each { |row| puts "  renamed    #{row[:context]}.#{row[:word]} (was #{row[:was]})" }
+        print_status_rows(moving, renamed)
         true
       end
 
-      # @return [Boolean] whether the gates held
-      def propose(args, evolve, root)
-        word = args.shift or abort "propose what word?"
-        context = evolve.option(args, "context") or abort "--context is required — a word is a word somewhere"
-        ok = guarded(word, context, evolve, root) do
-          evolve.propose(word: word, context: context,
-                         body: evolve.option(args, "body", "none"), inner: evolve.option(args, "inner", ""),
-                         opens: evolve.option(args, "opens", ""), fills: evolve.option(args, "fills", ""))
-        end
-        if ok
-          puts "Proposed. It reaches no projection until admitted. Before `hecks evolve admit`:"
-          puts "  1. teach the #{context} builder the word (and its spec/dsl_spec example)"
-        end
-        ok
-      end
-
-      # @return [Boolean] whether the gates held
-      def set_status(command, args, evolve, root)
-        word = args.shift or abort "#{command} what word?"
-        context = evolve.option(args, "context") or abort "--context is required"
-        guarded(word, context, evolve, root) do
-          evolve.set_status(word: word, context: context, to: WORD_STATUS.fetch(command))
-        end
-      end
-
-      # @return [Boolean] whether the gates held
-      def rename(args, evolve, root)
-        word = args.shift or abort "rename what word?"
-        context = evolve.option(args, "context") or abort "--context is required"
-        to = evolve.option(args, "to") or abort "--to is required — a rename goes somewhere"
-        ok = guarded(word, context, evolve, root) { evolve.rename(word: word, context: context, to: to) }
-        if ok
-          puts "Renamed. The old spelling keeps parsing — that is the point. Before this holds:"
-          puts "  1. alias the new word to the old in the #{context} builder (alias_method :#{to}, :#{word})"
-          puts "  2. add the identical-IR example to spec/dsl_spec.rb"
-        end
-        ok
-      end
-
-      # @return [Boolean] whether the gates held
-      def propose_argument(args, evolve, root)
-        keyword = args.shift or abort "argument-propose which keyword's argument?"
-        context = evolve.option(args, "context") or abort "--context is required"
-        kind = evolve.option(args, "kind") or abort "--kind is required — text|symbol|number|flag|literal|constant|pairs|list"
-        ok = guarded("#{keyword} argument", context, evolve, root) do
-          evolve.propose_argument(keyword: keyword, context: context, kind: kind,
-                                  required: evolve.option(args, "required", "false"),
-                                  at: evolve.option(args, "at", ""), named: evolve.option(args, "named", ""),
-                                  fills: evolve.option(args, "fills", ""),
-                                  pairs_shape: evolve.option(args, "pairs-shape"))
-        end
-        if ok
-          puts "Proposed. It reaches no projection until admitted. Before `hecks evolve argument-admit`:"
-          puts "  1. teach the #{context} builder's #{keyword} method the argument"
-        end
-        ok
-      end
-
-      # @return [Boolean] whether the gates held
-      def set_argument_status(command, args, evolve, root)
-        keyword = args.shift or abort "#{command} which keyword's argument?"
-        context = evolve.option(args, "context") or abort "--context is required"
-        guarded("#{keyword} argument", context, evolve, root) do
-          evolve.set_argument_status(keyword: keyword, context: context, to: ARGUMENT_STATUS.fetch(command),
-                                     at: evolve.option(args, "at", ""), named: evolve.option(args, "named", ""))
-        end
+      def print_status_rows(moving, renamed)
+        moving.each { |row| puts "  #{row[:status].ljust(10)} #{row[:context]}.#{row[:word]}" }
+        renamed.each { |row| puts "  renamed    #{row[:context]}.#{row[:word]} (was #{row[:was]})" }
       end
     end
   end

data/lib/hecks/tools/fuzz_sweep/findings.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module FuzzSweep
+      # Replays a generated sequence and judges, groups and shrinks what it finds.
+      module Findings
+        # An exception escaping Replay's per-step isolation is an interpreter defect, not a domain
+        # refusal.
+        #
+        # @param domain [String] the domain directory
+        # @param steps [Array<Hash>] the sequence to replay
+        # @param adapter [Symbol] the persistence to boot on
+        # @return [Array(Symbol, String)] the verdict (`:clean`, `:property_violation`,
+        #   `:crash`) and its message
+        def outcome(domain, steps, adapter = :memory)
+          history = Hecks::Fuzzing::Replay.call(domain, steps, adapter: adapter)
+          violations = Hecks::Fuzzing::Properties.check(history).reject { |_, result| result == true }
+          return [:clean, nil] if violations.empty?
+
+          [:property_violation, violations.map { |name, message| "#{name}: #{message}" }.join("; ")]
+        rescue StandardError => e
+          [:crash, "#{e.class}: #{e.message}"]
+        end
+
+        # Groups findings by property name or exception class, stable across shrink candidates.
+        #
+        # @param message [String, nil] a finding's message
+        # @return [String] the property name or exception class it opens with
+        def signature_of(message)
+          return "unknown" unless message
+
+          message.split(":").first
+        end
+
+        # A compound finding that mixes a known shape with any other offender is not known and still
+        # fails.
+        #
+        # @param name [String] the domain's name
+        # @param failure [Hash] a finding: `signature` and `message`
+        # @return [Boolean] whether every offender is an allowlisted one
+        def known_finding?(name, failure)
+          matchers = KNOWN_FUZZ_FINDINGS.dig(name, failure[:signature])
+          return false unless matchers
+
+          failure[:message].split("; ").all? { |chunk| matchers.any? { |regex| regex.match?(chunk) } }
+        end
+
+        # Skips only exact, already-tracked wiring gaps; any other WiringError is re-raised.
+        #
+        # @param error [Hecks::Runtime::WiringError] what generating a sequence raised
+        # @return [Symbol] a key of `SKIPPED_DOMAIN_REASONS`
+        def known_unfuzzable_wiring_gap(error)
+          case error.message
+          when %r{a compute/rekey rule is declared}
+            # compute/rekey needs an era/Postgres migration, so it cannot boot under IsolatedBoot's
+            # Memory rebind. Real coverage lives in spec/adapters/driven/postgres_era/*_spec.rb.
+            :skip_compute_rekey
+          else
+            raise error
+          end
+        end
+
+        # Shrinks steps, then arguments, keeping a removal only while the same finding reproduces.
+        #
+        # @param domain [String] the domain directory
+        # @param steps [Array<Hash>] the failing sequence
+        # @param signature [String] the finding to keep
+        # @param adapter [Symbol] the persistence to boot on
+        # @return [Array<Hash>] the smallest sequence found
+        def shrink(domain, steps, signature, adapter = :memory)
+          Hecks::Fuzzing::Shrinker.call(steps) { |candidate| same_finding?(domain, candidate, signature, adapter) }.steps
+        end
+
+        # @param domain [String] the domain directory
+        # @param candidate [Array<Hash>] a sequence to replay
+        # @param signature [String] the finding to keep
+        # @param adapter [Symbol] the persistence to boot on
+        # @return [Boolean] whether the candidate sequence reproduces the finding
+        def same_finding?(domain, candidate, signature, adapter)
+          verdict, message = outcome(domain, candidate, adapter)
+          "#{verdict}: #{signature_of(message)}" == signature
+        end
+
+        # @param step [Hash] one step of a sequence
+        # @return [Hash] its arguments
+        def args_of(step) = Hecks::Fuzzing::Shrinker.args_of(step)
+
+        # The argument pass alone.
+        #
+        # @param domain [String] the domain directory
+        # @param steps [Array<Hash>] the failing sequence
+        # @param signature [String] the finding to keep
+        # @param adapter [Symbol] the persistence to boot on
+        # @return [Array<Hash>] the sequence with every argument the finding does not need dropped
+        def shrink_arguments(domain, steps, signature, adapter = :memory)
+          Hecks::Fuzzing::Shrinker.drop_arguments(steps, Hecks::Fuzzing::Shrinker::Meter.new(nil)) do |candidate|
+            same_finding?(domain, candidate, signature, adapter)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/fuzz_sweep/options.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "etc"
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module FuzzSweep
+      # The command line of a sweep: its options, and what the chosen adapter needs.
+      module Options
+        # @param args [Array<String>] the command line, consumed
+        # @return [Hash, nil] `seeds`, `steps`, `workers`, `adapter` and `domain`; nil after a
+        #   refusal
+        def parse(args)
+          options = { seeds: 20, steps: 30, workers: nil, adapter: :memory, domain: nil }
+          until args.empty?
+            apply_option(options, args.shift, args)
+            return nil unless adapter_known?(options[:adapter])
+          end
+          options
+        end
+
+        # Records one command-line word in `options`, taking its value from `rest` when it has one.
+        def apply_option(options, arg, rest)
+          case arg
+          when "--seeds" then options[:seeds] = Integer(rest.shift)
+          when "--steps" then options[:steps] = Integer(rest.shift)
+          when "--workers" then options[:workers] = Integer(rest.shift)
+          when "--adapter" then options[:adapter] = rest.shift.to_s.downcase.to_sym
+          else options[:domain] = arg
+          end
+        end
+
+        # @return [Boolean] whether `adapter` is one a sweep can boot on; warns when it is not
+        def adapter_known?(adapter)
+          return true if ADAPTERS.include?(adapter)
+
+          warn "unknown --adapter #{adapter} — memory, sqlite, or postgres"
+          false
+        end
+
+        # @return [Boolean] whether the chosen adapter can be used: only `postgres` needs a server
+        def adapter_ready?(options)
+          options[:adapter] != :postgres || postgres_reachable?
+        end
+
+        # One child per core; a real Postgres runs one at a time.
+        #
+        # @return [Integer] how many children may run at once
+        def worker_count(options)
+          options[:workers] || (options[:adapter] == :postgres ? 1 : Etc.nprocessors)
+        end
+
+        # `postgres` needs a reachable local server and is slower per dispatch, so pass smaller
+        # `--seeds` and `--steps`.
+        #
+        # @return [Boolean] whether a local Postgres answers; warns why when it does not
+        def postgres_reachable?
+          require "pg"
+          PG.connect(dbname: "postgres").close
+          true
+        rescue LoadError, PG::Error => e
+          warn "--adapter postgres needs a reachable local Postgres — #{e.class}: #{e.message}"
+          false
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/fuzz_sweep/pool.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module FuzzSweep
+      # Runs one forked child per domain and prints their output in domain order.
+      module Pool
+        # Forks one child per domain, up to `workers`, printing each child's output whole in domain
+        # order. A child that crashes exits non-zero and counts as a finding.
+        #
+        # @param domains [Array<String>] the domain directories
+        # @param workers [Integer] how many children may run at once
+        # @yieldparam domain [String] a domain directory
+        # @yieldreturn [Boolean] whether it was clean
+        # @return [Boolean] true if every domain's child exited 0, false if any exited non-zero
+        def fuzz_in_pool(domains, workers, &) # rubocop:disable Naming/PredicateMethod -- the sweep's verdict
+          results = run_children(domains, workers, &)
+          slowest = results.max_by(5) { |_, (_, _, seconds)| seconds }
+                           .map { |index, (_, _, seconds)| "#{File.basename(domains[index])} #{seconds.round}s" }
+          warn "slowest domains: #{slowest.join(", ")}"
+          replay_outputs(results).all?
+        end
+
+        private
+
+        # @return [Hash{Integer => Array}] by domain index: whether the child succeeded, its output
+        #   file, and its seconds
+        def run_children(domains, workers, &)
+          pending = domains.each_with_index.to_a
+          running = {}
+          results = {}
+          until pending.empty? && running.empty?
+            start_children(pending, running, workers, &)
+            pid, status = Process.wait2
+            index, out, started = running.delete(pid)
+            results[index] = [status.success?, out, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started]
+          end
+          results
+        end
+
+        def start_children(pending, running, workers, &)
+          while running.size < workers && (domain, index = pending.shift)
+            out = Tempfile.new("fuzz")
+            pid = fork_child(out, domain, &)
+            running[pid] = [index, out, Process.clock_gettime(Process::CLOCK_MONOTONIC)]
+          end
+        end
+
+        def fork_child(out, domain)
+          fork do
+            $stdout.reopen(out)
+            $stderr.reopen(out)
+            exit(yield(domain) ? 0 : 1)
+          end
+        end
+
+        # Prints each child's output in domain order.
+        #
+        # @return [Array<Boolean>] whether each child was clean
+        def replay_outputs(results)
+          results.sort.map do |_, (clean, out, _)|
+            out.rewind
+            print out.read
+            out.close!
+            clean
+          end
+        end
+      end
+    end
+  end
+end