hecks 3.5.0 → 3.7.0

data/lib/hecks/tools/era_reattest/reporting.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module EraReattest
+      # What the re-attestation says to the person running it.
+      module Reporting
+        # @return [Integer] 0
+        def matches_digest(bluebook, ordinal)
+          puts "#{bluebook.name} era #{ordinal}: the held text matches its digest — nothing to re-attest."
+          0
+        end
+
+        def report_mismatch(bluebook, ordinal, stored, computed)
+          puts "#{bluebook.name} era #{ordinal}: the held text does NOT match its recorded digest."
+          puts "  recorded: #{stored || "(none)"}"
+          puts "  computed: #{computed}"
+        end
+
+        # Says how the held text's shape compares with the era's minted name.
+        #
+        # @param verdict [Symbol, nil] `:cosmetic`, `:unnamed`, or nothing to say
+        def report_shape(verdict, ordinal)
+          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
+        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
+        end
+      end
+    end
+  end
+end

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,80 @@
+# 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
+        # The options that take a whole number, and the key each fills.
+        INTEGER_OPTIONS = { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers }.freeze
+
+        # The most children a Postgres sweep runs at once unless `--workers` says otherwise.
+        POSTGRES_WORKERS = 4
+
+        # @param args [Array<String>] the command line, consumed
+        # @return [Hash, nil] `seeds`, `steps`, `workers`, `adapter`, `persist` and `domain`; nil
+        #   after a refusal
+        def parse(args)
+          options = { seeds: 20, steps: 30, workers: nil, adapter: :memory, domain: nil, persist: false }
+          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)
+          if (key = INTEGER_OPTIONS[arg]) then options[key] = Integer(rest.shift)
+          elsif arg == "--persist-regressions" then options[:persist] = true
+          elsif arg == "--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 is capped, because each child holds its own
+        # connections and its own scratch schema, and runs one at a time on macOS, where libpq
+        # segfaults when a forked child connects.
+        #
+        # @return [Integer] how many children may run at once
+        def worker_count(options)
+          options[:workers] || (options[:adapter] == :postgres ? postgres_workers : Etc.nprocessors)
+        end
+
+        # @return [Integer] the children a Postgres sweep runs at once by default
+        def postgres_workers
+          RUBY_PLATFORM.include?("darwin") ? 1 : [Etc.nprocessors, POSTGRES_WORKERS].min
+        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