hecks 3.5.0 → 3.6.0

data/lib/hecks/cli/stress_concurrency_specs.rb

@@ -3,6 +3,8 @@
 require "etc"
 require "open3"
 require "fileutils"
+require_relative "stress_concurrency_specs/usage"
+require_relative "stress_concurrency_specs/reporting"
 
 module Hecks
   module CLI
@@ -28,28 +30,10 @@ module Hecks
         "spec/adapters/driven/postgres_concurrent_dispatch_spec.rb"
       ].freeze
 
-      USAGE = <<~TEXT
-        Usage: hecks stress_concurrency [--runs N] [--parallel N] [--seed-start N]
-
-          --runs N        How many times to run EACH group below. Each run uses
-                           a different --seed (seed-start + run index).
-          --parallel N    How many parallel-safe-group runs to have going as
-                           separate OS processes AT THE SAME TIME (default: this
-                           machine's own core count, via Etc.nprocessors) — real
-                           concurrent scheduler/CPU contention, not just varied
-                           seeds one after another. The Postgres-backed group
-                           always runs one process at a time regardless of this
-                           flag.
-          --seed-start N  First --seed value; runs use seed_start,
-                           seed_start + 1, ... seed_start + runs - 1.
-
-        `hecks stress_concurrency` fills --runs and --seed-start from the defaults its
-        bluebook declares (`hecks stress_concurrency --help` shows them).
-
-        Exits 0 if every run's every example passed, 1 if anything failed -
-        failing runs' full output is saved under tmp/stress-failures/
-        for a real repro (same seed, same command, just add CI=true).
-      TEXT
+      # The value flags and the settings they fill.
+      FLAGS = { "--runs" => :runs, "--parallel" => :parallel, "--seed-start" => :seed_start }.freeze
+
+      extend Reporting
 
       module_function
 
@@ -66,68 +50,111 @@ module Hecks
         status = parse!(argv, settings, out)
         return status if status
 
-        missing = %i[runs seed_start].reject { |name| settings.key?(name) }
-        unless missing.empty?
-          warn "missing #{missing.map { |name| "--#{name.to_s.tr('_', '-')}" }.join(', ')}: " \
-               "`hecks stress_concurrency` supplies the defaults its bluebook declares (--help for usage)"
-          return 64
-        end
+        return 64 if missing_defaults?(settings)
 
         results = run_all(root, settings, out)
         report(root, results, out)
       end
 
+      # Warns when the launcher did not supply `--runs` and `--seed-start`.
+      #
+      # @param settings [Hash{Symbol => Integer}] the parsed flags
+      # @return [Boolean] whether a default is missing
+      def missing_defaults?(settings)
+        missing = %i[runs seed_start].reject { |name| settings.key?(name) }
+        return false if missing.empty?
+
+        warn "missing #{missing.map { |name| "--#{name.to_s.tr("_", "-")}" }.join(", ")}: " \
+             "`hecks stress_concurrency` supplies the defaults its bluebook declares (--help for usage)"
+        true
+      end
+
       # @param argv [Array<String>] the arguments; consumed
       # @param settings [Hash{Symbol => Integer}] filled in from the flags
       # @param out [IO] where the usage goes for `--help`
       # @return [Integer, nil] an exit status to stop with, or nil to go on
       def parse!(argv, settings, out)
-        flags = { "--runs" => :runs, "--parallel" => :parallel, "--seed-start" => :seed_start }
         until argv.empty?
           arg = argv.shift
-          if flags.key?(arg)
-            settings[flags[arg]] = Integer(argv.shift)
-          elsif %w[--help -h].include?(arg)
-            out.puts USAGE
-            return 0
-          else
-            warn "unrecognized argument: #{arg.inspect} (--help for usage)"
-            return 64
-          end
+          return stop_for(arg, out) unless FLAGS.key?(arg)
+
+          settings[FLAGS[arg]] = Integer(argv.shift)
         end
         nil
       end
 
+      # @param arg [String] a command-line word that is not a value flag
+      # @param out [IO] where the usage goes for `--help`
+      # @return [Integer] 0 for `--help`, 64 for an unknown argument
+      def stop_for(arg, out)
+        if %w[--help -h].include?(arg)
+          out.puts USAGE
+          return 0
+        end
+
+        warn "unrecognized argument: #{arg.inspect} (--help for usage)"
+        64
+      end
+
       # @param root [String] the checkout the specs run in
       # @param settings [Hash{Symbol => Integer}] `runs`, `parallel` and `seed_start`
       # @param out [IO] where the progress goes
       # @return [Array<Hash>] one result per run
       def run_all(root, settings, out)
+        seeds = (settings[:seed_start]...(settings[:seed_start] + settings[:runs])).to_a
+        announce(settings, out)
+
+        results = run_parallel_group(root, seeds, settings[:parallel], out) + run_serial_group(root, seeds, out)
+        out.puts
+        out.puts
+        results
+      end
+
+      # @param root [String] the checkout the specs run in
+      # @param seeds [Array<Integer>] the seeds to run
+      # @param parallel [Integer] how many runs go at the same time
+      # @param out [IO] where the progress goes
+      # @return [Array<Hash>] one result per seed
+      def run_parallel_group(root, seeds, parallel, out)
+        seeds.each_slice(parallel).flat_map do |batch|
+          progress(run_batch(root, PARALLEL_SAFE_SPEC_FILES, batch, label: "parallel-safe"), out)
+        end
+      end
+
+      # @param root [String] the checkout the specs run in
+      # @param seeds [Array<Integer>] the seeds to run, one process at a time
+      # @param out [IO] where the progress goes
+      # @return [Array<Hash>] one result per seed
+      def run_serial_group(root, seeds, out)
+        seeds.flat_map do |seed|
+          progress([run_once(root, SERIAL_ONLY_SPEC_FILES, seed, label: "postgres (serial)")], out)
+        end
+      end
+
+      # Says what is about to run.
+      #
+      # @param settings [Hash{Symbol => Integer}] `runs`, `parallel` and `seed_start`
+      # @param out [IO] where the announcement goes
+      # @return [void]
+      def announce(settings, out)
         runs = settings[:runs]
         seed_start = settings[:seed_start]
-        seeds = (seed_start...(seed_start + runs)).to_a
         out.puts "Stress-running the parallel-safe group #{runs} time(s) (#{settings[:parallel]} at a time), " \
                  "seeds #{seed_start}..#{seed_start + runs - 1}:"
         PARALLEL_SAFE_SPEC_FILES.each { |f| out.puts "  - #{f}" }
         out.puts "...and the Postgres-backed group #{runs} time(s), ONE PROCESS AT A TIME:"
         SERIAL_ONLY_SPEC_FILES.each { |f| out.puts "  - #{f}" }
         out.puts
+      end
 
-        results = []
-        seeds.each_slice(settings[:parallel]) do |batch|
-          batch_results = run_batch(root, PARALLEL_SAFE_SPEC_FILES, batch, label: "parallel-safe")
-          results.concat(batch_results)
-          batch_results.each { |result| out.print result[:success] ? "." : "F" }
-          out.flush
-        end
-        seeds.each do |seed|
-          result = run_once(root, SERIAL_ONLY_SPEC_FILES, seed, label: "postgres (serial)")
-          results << result
-          out.print result[:success] ? "." : "F"
-          out.flush
-        end
-        out.puts
-        out.puts
+      # Prints one dot per passing run and an F per failing one.
+      #
+      # @param results [Array<Hash>] the runs just finished
+      # @param out [IO] where the progress goes
+      # @return [Array<Hash>] `results`
+      def progress(results, out)
+        results.each { |result| out.print result[:success] ? "." : "F" }
+        out.flush
         results
       end
 
@@ -143,7 +170,7 @@ module Hecks
         command = ["bundle", "exec", "rspec", *spec_files, "--seed", seed.to_s, "--format", "progress"]
         stdout, status = Open3.capture2e({ "CI" => "true" }, *command, chdir: root)
         { label: label, seed: seed, success: status.success?, output: stdout,
-          reproduce: "CI=true bundle exec rspec #{spec_files.join(' ')} --seed #{seed}" }
+          reproduce: "CI=true bundle exec rspec #{spec_files.join(" ")} --seed #{seed}" }
       end
 
       # One thread per child process: `Open3.capture2e` already spawns a real process per call.
@@ -156,31 +183,6 @@ module Hecks
       def run_batch(root, spec_files, seeds, label:)
         seeds.map { |seed| Thread.new { run_once(root, spec_files, seed, label: label) } }.map(&:value)
       end
-
-      # @param root [String] the checkout; failing runs' output is saved under its `tmp/`
-      # @param results [Array<Hash>] every run's result
-      # @param out [IO] where the verdict goes
-      # @return [Integer] 0 when every run passed, else 1
-      def report(root, results, out)
-        failures = results.reject { |r| r[:success] }
-        if failures.empty?
-          out.puts "CLEAN — #{results.size}/#{results.size} runs passed. " \
-                   "No new flakiness beyond a single ordinary `rspec` run found in this many tries."
-          return 0
-        end
-
-        dir = File.join(root, "tmp/stress-failures")
-        FileUtils.mkdir_p(dir)
-        out.puts "FOUND FLAKINESS — #{failures.size}/#{results.size} runs failed:"
-        failures.each do |failure|
-          path = File.join(dir, "#{failure[:label].tr(' ', '_').gsub(/[()]/, '')}-seed#{failure[:seed]}.log")
-          File.write(path, failure[:output])
-          out.puts "  [#{failure[:label]}] seed #{failure[:seed]} — output saved to #{path.sub("#{root}/", '')}"
-          out.puts "    reproduce: #{failure[:reproduce]}"
-        end
-        out.puts
-        1
-      end
     end
   end
 end

data/lib/hecks/cli.rb

@@ -1,3 +1,6 @@
+require_relative "cli/command_table"
+require_relative "cli/launcher_words"
+
 module Hecks
   # The `hecks` command an installed gem puts on the path: one router over the
   # domain-operator tools, each also runnable from a checkout as `exe/hecks <name>`.
@@ -6,111 +9,8 @@ module Hecks
   #
   # See `docs/decisions/0066-the-gem-ships-a-hecks-executable-and-dev-tooling-stays-in-the-repo.md`.
   module CLI
-    # One subcommand: a one-line summary, its usage line, the file that holds it and the
-    # call that runs it (given the argv after the name, its program name and its own name).
-    Command = Struct.new(:summary, :usage, :file, :run)
-
-    # Every subcommand, in the order the help lists them.
-    COMMANDS = {
-      "run"              => Command.new(
-        "Dispatch a verb, or run a JSON step list, against a domain.",
-        "hecks run [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>",
-        "cli/run",
-        ->(argv, program, _name) { Run.call(argv, program: program) }
-      ),
-      "docs"             => Command.new(
-        "Print a domain's usage document, projected from its bluebook.",
-        "hecks docs [domain-path] [aggregate]",
-        "cli/document",
-        ->(argv, program, name) { Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd) }
-      ),
-      "narrate"          => Command.new(
-        "Print a domain read back in English, projected from its bluebook.",
-        "hecks narrate [domain-path] [aggregate]",
-        "cli/document",
-        ->(argv, program, name) { Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd) }
-      ),
-      "ir"               => Command.new(
-        "Print a booted domain's IR as JSON.",
-        "hecks ir <domain> [--translations] | hecks ir --meta",
-        "cli/ir",
-        ->(argv, program, _name) { Ir.call(argv, program: program) }
-      ),
-      "stores"           => Command.new(
-        "Print every aggregate's current records as JSON.",
-        "hecks stores <domain>",
-        "cli/stores",
-        ->(argv, program, _name) { Stores.call(argv, program: program) }
-      ),
-      "model_check"      => Command.new(
-        "Statically check a domain's IR for dead states and unreachable steps.",
-        "hecks model_check [--strict] [--profile client] [--wait] [<domain> …]",
-        "cli/model_check",
-        ->(argv, program, _name) { ModelCheck.call(argv, program: program, root: checkout_root) }
-      ),
-      "smoke_test"       => Command.new(
-        "Boot a domain and dispatch every declared command and report once.",
-        "hecks smoke_test [domain]",
-        "cli/smoke_test",
-        ->(argv, _program, _name) { SmokeTest.call(argv, root: Dir.pwd) }
-      ),
-      "project_diagrams" => Command.new(
-        "Write a domain's Mermaid diagrams under ./docs/generated/diagrams/ (positional form only).",
-        "hecks project_diagrams <domain-path> <ChapterName>  (writes) | " \
-        "hecks project_diagrams domain=<path> chapter=<Name>  (prints; writes nothing)",
-        "cli/project_diagrams",
-        ->(argv, program, _name) { ProjectDiagrams.call(argv, program: program, root: Dir.pwd) }
-      ),
-      "project_cli"      => Command.new(
-        "Write a command-line launcher beside each domain, named after its bluebook.",
-        "hecks project_cli [domain-path …]",
-        "cli/project_cli",
-        ->(argv, program, _name) { ProjectCli.call(argv, program: program, root: Dir.pwd, remove_stale_bin: false) }
-      ),
-      "mcp"              => Command.new(
-        "Serve the MCP door over stdio (no authentication; stdio only).",
-        "hecks mcp [--stdio]",
-        "cli/mcp",
-        ->(argv, _program, _name) { Mcp.call(argv) }
-      )
-    }.freeze
-
     HELP_FLAGS = ["--help", "-h"].freeze
 
-    # The launcher's flags that mean the same for every subcommand here: `--wait` (a subcommand
-    # exits with its own verdict, so waiting changes nothing) and `--confirm` (nothing here asks
-    # for one). Each may carry a Boolean word, as at the launcher.
-    GENERIC_FLAGS = ["--wait", "--confirm"].freeze
-
-    # A launcher word: `name=value`, where the name has no path characters.
-    NAME_VALUE = /\A[A-Za-z_][\w-]*=/
-
-    # The launcher's `name=value` spellings of a subcommand's positional arguments.
-    #
-    # `slots` lists, in positional order, the names that fill each place (`domain` before
-    # `aggregate`); `many` lets the first slot repeat and take a comma list; `exists` makes
-    # the first slot's values paths that must exist; `flags` and `options` are `--name`
-    # switches and `--name value` pairs; `ignored` names a launcher argument this form has no
-    # use for. A subcommand absent here (`run`, whose pairs are the verb's own, `mcp`, and
-    # `project_diagrams`, whose launcher form answers instead of writing) keeps its words.
-    LAUNCHER_FORMS = {
-      "docs"        => { slots: [%w[domain], %w[aggregate]], exists: true },
-      "narrate"     => { slots: [%w[domain], %w[aggregate]], exists: true },
-      "ir"          => { slots: [%w[domain]], flags: %w[translations meta], exists: true },
-      "stores"      => { slots: [%w[domain]], exists: true },
-      "model_check" => { slots: [%w[domains domain]], many: true, flags: %w[strict],
-                         options: %w[profile], ignored: %w[run] },
-      "smoke_test"  => { slots: [%w[subject domain]], ignored: %w[run] },
-      "project_cli" => { slots: [%w[domain]], many: true }
-    }.freeze
-
-    # Subcommands whose words are their own: `run`'s pairs and `mcp`'s flags are not the launcher's.
-    UNTOUCHED = %w[run mcp].freeze
-
-    # Subcommands whose `name=value` form is the launcher's own question, which answers
-    # differently from the positional form: `project_diagrams` writes files, the question prints.
-    LAUNCHER_ANSWERS = ["project_diagrams"].freeze
-
     # Printed above the usage line by `overview`, on every path that reaches it
     # (a bare `hecks`, `hecks --help`, and an unknown subcommand alike).
     HERO = <<~BANNER.freeze
@@ -126,6 +26,9 @@ module Hecks
     # Exit status for a missing or unknown subcommand.
     USAGE_STATUS = 2
 
+    include LauncherWords
+    extend LauncherWords
+
     module_function
 
     # The checkout this library is loaded from, which a corpus sweep needs; an installed gem has
@@ -152,128 +55,49 @@ module Hecks
       Encoding.default_external = Encoding::UTF_8
       Encoding.default_internal = Encoding::UTF_8
       name, *rest = argv
-      if name.nil? || !COMMANDS.key?(name)
-        asked = HELP_FLAGS.include?(name) || name == "help"
-        err.puts "hecks: unknown command #{name.inspect}" unless asked || name.nil?
-        overview(asked ? out : err)
-        return asked ? 0 : USAGE_STATUS
-      end
-
-      if help_asked?(name, rest)
-        help(COMMANDS.fetch(name), out)
-        return 0
-      end
+      return refuse_command(name, out, err) unless COMMANDS.key?(name)
+      return command_help(name, out) if help_asked?(name, rest)
 
       words, problem = launcher_words(name, rest)
-      if problem
-        err.puts "hecks #{name}: #{problem}"
-        return 1
-      end
+      return refuse_words(name, problem, err) if problem
 
       result = dispatch(name, words)
       result.is_a?(Integer) ? result : 0
     end
 
-    # Whether the words ask for a subcommand's usage: a lone flag for `run`, whose other words are
-    # the verb's own, and the flag anywhere for the rest.
+    # Answers an absent or unknown subcommand with the overview.
     # @api private
-    def help_asked?(name, rest)
-      return rest.length == 1 && HELP_FLAGS.include?(rest.first) if name == "run"
-
-      rest.any? { |word| HELP_FLAGS.include?(word) }
+    # @return [Integer] 0 when help was asked for, else the usage status
+    def refuse_command(name, out, err)
+      asked = HELP_FLAGS.include?(name) || name == "help"
+      err.puts "hecks: unknown command #{name.inspect}" unless asked || name.nil?
+      overview(asked ? out : err)
+      asked ? 0 : USAGE_STATUS
     end
 
-    # Whether a command line is the launcher's own form of a subcommand that answers differently
-    # from its positional form, so the executable leaves it to the launcher.
-    #
-    # @param argv [Array<String>] the command line, subcommand first
-    # @return [Boolean]
-    def launcher_form?(argv)
-      LAUNCHER_ANSWERS.include?(argv.first) && argv.drop(1).any? { |word| word.match?(NAME_VALUE) }
-    end
-
-    # Rewrites the launcher's spellings into the subcommand's own: drops the generic flags and
-    # turns `name=value` words into the positionals and flags the subcommand reads.
-    #
-    # @param name [String] a key of `COMMANDS`
-    # @param rest [Array<String>] the words after the subcommand
-    # @return [Array(Array<String>, String)] the words to run with, and a refusal (nil when
-    #   there is none)
-    def launcher_words(name, rest)
-      return [rest, nil] if UNTOUCHED.include?(name)
-
-      require_relative "doors/cli_door"
-      words = strip_generic(rest)
-      form  = LAUNCHER_FORMS[name]
-      return [words, nil] unless form && words.any? { |word| word.match?(NAME_VALUE) }
-
-      slots, extra, refusal = bind_named_words(form, words)
-      return [nil, refusal] if refusal
-
-      missing = slots.first.find { |path| !File.exist?(path) } if form[:exists]
-      return [nil, "no such domain #{missing.inspect}"] if missing
-
-      [words.grep_v(NAME_VALUE) + extra + slots.flatten, nil]
-    rescue Runtime::TypeMismatch => e
-      [nil, e.message]
-    end
-
-    # Sorts the `name=value` words of `words` into the form's positional slots and its flags.
+    # Prints one subcommand's usage.
     # @api private
-    #
-    # @param form [Hash] an entry of `LAUNCHER_FORMS`
-    # @param words [Array<String>] the words after the subcommand, generic flags removed
-    # @return [Array(Array<Array<String>>, Array<String>, String)] the slot contents, the extra
-    #   flag words, and a refusal (nil when there is none)
-    def bind_named_words(form, words)
-      slots = Array.new(form[:slots].length) { [] }
-      extra = []
-      words.grep(NAME_VALUE).each do |word|
-        key, value = word.split("=", 2)
-        key  = key.tr("-", "_")
-        slot = form[:slots].index { |names| names.include?(key) }
-        if slot
-          slots[slot].concat(form[:many] ? value.split(",") : [value])
-        elsif (refusal = bind_flag_or_option(form, key, value, extra))
-          return [nil, nil, refusal]
-        end
-      end
-      [slots, extra, nil]
+    # @return [Integer] 0
+    def command_help(name, out)
+      help(COMMANDS.fetch(name), out)
+      0
     end
 
-    # Appends the flag or option word for one `name=value` into `extra`.
+    # Says why a subcommand's words were refused.
     # @api private
-    #
-    # @return [String, nil] a refusal when the form takes no such argument
-    def bind_flag_or_option(form, key, value, extra)
-      if Array(form[:flags]).include?(key)
-        extra << "--#{key.tr('_', '-')}" if Doors::CliDoor.boolean(value)
-        nil
-      elsif Array(form[:options]).include?(key)
-        extra.push("--#{key}", value)
-        nil
-      elsif !Array(form[:ignored]).include?(key)
-        known = form[:slots].flatten + Array(form[:flags]) + Array(form[:options])
-        "no argument #{key.inspect} — this verb takes #{known.sort.join(', ')}"
-      end
+    # @return [Integer] 1
+    def refuse_words(name, problem, err)
+      err.puts "hecks #{name}: #{problem}"
+      1
     end
 
-    # Takes `--wait` and `--confirm`, each with an optional Boolean word, out of `words`.
+    # Whether the words ask for a subcommand's usage: a lone flag for `run`, whose other words are
+    # the verb's own, and the flag anywhere for the rest.
     # @api private
-    def strip_generic(words)
-      queue = words.dup
-      kept  = []
-      until queue.empty?
-        word = queue.shift
-        flag, value = word.split("=", 2)
-        if GENERIC_FLAGS.include?(flag)
-          value ||= Doors::CliDoor::BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
-          Doors::CliDoor.boolean(value)
-        else
-          kept << word
-        end
-      end
-      kept
+    def help_asked?(name, rest)
+      return rest.length == 1 && HELP_FLAGS.include?(rest.first) if name == "run"
+
+      rest.any? { |word| HELP_FLAGS.include?(word) }
     end
 
     # Runs one known subcommand with the working directory as its root.

data/lib/hecks/codemod/runner.rb

@@ -0,0 +1,92 @@
+require_relative "sweep"
+
+module Hecks
+  module Codemod
+    # Runs one codemod rule across every example domain and the meta-domain,
+    # verifying each candidate edit via IR diff before keeping it.
+    class Runner
+      # @return [#call] finds a booted registry's candidate edits
+      attr_reader :find_candidates
+
+      # @return [#call] applies one candidate to a file's text, answering the text and whether
+      #   it changed
+      attr_reader :apply_candidate
+
+      # @return [#call] words a candidate for the report
+      attr_reader :label
+
+      def initialize(find_candidates:, apply_candidate:, label:)
+        @find_candidates = find_candidates
+        @apply_candidate = apply_candidate
+        @label = label
+      end
+
+      def run(dry_run: false)
+        results = { applied: [], skipped: [], clean: [] }
+        run_example_domains(results, dry_run)
+        run_meta_domain(results, dry_run)
+        results
+      end
+
+      def report(results, dry_run:)
+        puts "== results (#{dry_run ? "DRY RUN — nothing written" : "applied"}) =="
+        puts "clean (no candidates): #{results[:clean].join(", ")}" unless results[:clean].empty?
+        results[:applied].each { |r| puts "APPLIED  #{r[:file]}: #{r[:candidates].join(", ")}" }
+        results[:skipped].each { |r| puts skipped_line(r) }
+      end
+
+      private
+
+      def skipped_line(entry)
+        "SKIPPED  #{entry[:file]} (#{entry[:reason]}): #{Array(entry[:candidates]).join(", ")}"
+      end
+
+      def run_example_domains(results, dry_run)
+        Codemod::EXAMPLE_ROOTS.each { |domain_dir| run_example_domain(domain_dir, results, dry_run) }
+      end
+
+      def run_example_domain(domain_dir, results, dry_run)
+        files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
+        return if files.empty?
+
+        before = Codemod.export_json(Codemod.load_bluebook(files))
+        candidates = @find_candidates.call(Codemod.load_bluebook(files))
+        return results[:clean] << domain_dir if candidates.empty?
+
+        Sweep.new(self, example_setup(domain_dir, files, before), results, dry_run).call(candidates)
+      end
+
+      def example_setup(domain_dir, files, before)
+        Sweep::Setup.new(
+          files: files, before: before, no_match_file: domain_dir, failure_file: ->(target) { target },
+          reboot: -> { Codemod.export_json(Codemod.load_bluebook(files)) }, stage_files: ->(target) { [target] },
+          reason: lambda { |error|
+            error ? "reboot raised after edit (#{error}) — reverted" : "IR changed after edit — reverted"
+          }
+        )
+      end
+
+      # Per-candidate, not batched — the meta-domain is one shared,
+      # self-dispatching registry (S14), so a single unsafe candidate could
+      # otherwise sink every other, genuinely safe one in the same run.
+      def run_meta_domain(results, dry_run)
+        before = Codemod.boot_meta
+        candidates = @find_candidates.call(Codemod.meta_registry)
+        return results[:clean] << "meta-domain" if candidates.empty?
+
+        Sweep.new(self, meta_setup(before), results, dry_run).call(candidates)
+      end
+
+      # A dry run stages the text in memory and reboots from it, then drops it — so the next
+      # candidate is judged against the true original state and no file is written.
+      def meta_setup(before)
+        Sweep::Setup.new(
+          files: Codemod::META_FILES, before: before, no_match_file: "meta-domain",
+          failure_file: ->(_target) { "meta-domain" }, reboot: -> { Codemod.boot_meta },
+          stage_files: ->(_target) { Codemod::META_FILES },
+          reason: ->(error) { error ? "reboot raised (#{error})" : "IR changed" }
+        )
+      end
+    end
+  end
+end