hecks 2.9.0 → 3.0.0

data/lib/hecks/cli.rb

@@ -1,61 +1,116 @@
 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 `bin/<name>`.
+  # domain-operator tools, each also runnable from a checkout as `exe/hecks <name>`.
   #
-  # Every subcommand's logic lives under `cli/`, with `bin/<name>` a thin wrapper
-  # over the same entry point, so the two can't drift apart.
+  # Every subcommand's logic lives under `cli/`, and `exe/hecks` routes to it.
   #
   # See `docs/decisions/0066-the-gem-ships-a-hecks-executable-and-dev-tooling-stays-in-the-repo.md`.
   module CLI
-    # One subcommand's help: a one-line summary and its usage line.
-    Command = Struct.new(:summary, :usage)
+    # 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\":[…]}'>"
+        "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]"
+        "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]"
+        "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"
+        "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>"
+        "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] <domain> [<domain> …]"
+        "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]"
+        "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/.",
-        "hecks project_diagrams <domain-path> <ChapterName>"
+        "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 …]"
+        "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]"
+        "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
@@ -73,6 +128,15 @@ module Hecks
 
     module_function
 
+    # The checkout this library is loaded from, which a corpus sweep needs; an installed gem has
+    # none.
+    #
+    # @return [String, nil] the repository root, or nil when `hecks.gemspec` is not beside `lib/`
+    def checkout_root
+      root = File.expand_path("../..", __dir__)
+      root if File.exist?(File.join(root, "hecks.gemspec"))
+    end
+
     # Routes `argv` to its subcommand and runs it.
     #
     # A subcommand followed only by `--help`/`-h` prints its usage without
@@ -81,9 +145,12 @@ module Hecks
     # @param argv [Array<String>] the command line, subcommand first
     # @param out [#puts] where help goes
     # @param err [#puts] where usage errors go
-    # @return [Integer] the process exit status for a subcommand that returns; a
-    #   subcommand that fails exits the process itself
+    # @return [Integer] the process exit status: 2 for a bad command, 1 for a bad word, the
+    #   subcommand's own Integer when it returns one, else 0; a subcommand that fails exits
+    #   the process itself
     def start(argv, out: $stdout, err: $stderr)
+      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"
@@ -92,12 +159,121 @@ module Hecks
         return asked ? 0 : USAGE_STATUS
       end
 
-      if rest.length == 1 && HELP_FLAGS.include?(rest.first)
+      if help_asked?(name, rest)
         help(COMMANDS.fetch(name), out)
-      else
-        dispatch(name, rest)
+        return 0
+      end
+
+      words, problem = launcher_words(name, rest)
+      if problem
+        err.puts "hecks #{name}: #{problem}"
+        return 1
+      end
+
+      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.
+    # @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) }
+    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.
+    # @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]
+    end
+
+    # Appends the flag or option word for one `name=value` into `extra`.
+    # @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
-      0
+    end
+
+    # Takes `--wait` and `--confirm`, each with an optional Boolean word, out of `words`.
+    # @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
     end
 
     # Runs one known subcommand with the working directory as its root.
@@ -107,36 +283,9 @@ module Hecks
     # @return [void]
     # @raise [SystemExit] when the subcommand exits the process itself
     def dispatch(name, argv)
-      program = "hecks #{name}"
-      case name
-      when "run"
-        require_relative "cli/run"
-        Run.call(argv, program: program)
-      when "docs", "narrate"
-        require_relative "cli/document"
-        Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd)
-      when "ir"
-        require_relative "cli/ir"
-        Ir.call(argv, program: program)
-      when "stores"
-        require_relative "cli/stores"
-        Stores.call(argv, program: program)
-      when "model_check"
-        require_relative "cli/model_check"
-        ModelCheck.call(argv, program: program)
-      when "smoke_test"
-        require_relative "cli/smoke_test"
-        SmokeTest.call(argv, root: Dir.pwd)
-      when "project_diagrams"
-        require_relative "cli/project_diagrams"
-        ProjectDiagrams.call(argv, program: program, root: Dir.pwd)
-      when "project_cli"
-        require_relative "cli/project_cli"
-        ProjectCli.call(argv, program: program, root: Dir.pwd, remove_stale_bin: false)
-      when "mcp"
-        require_relative "cli/mcp"
-        Mcp.call(argv)
-      end
+      command = COMMANDS.fetch(name)
+      require_relative command.file
+      command.run.call(argv, "hecks #{name}", name)
     end
 
     # @api private

data/lib/hecks/codemod.rb

@@ -0,0 +1,324 @@
+require_relative "bluebook/meta_validator"
+require_relative "corpus"
+
+module Hecks
+  # Shared machinery for a codemod that migrates real `.bluebook` source: boot,
+  # find candidates, edit, then verify by diffing the re-booted IR before keeping it.
+  module Codemod
+    ROOT = File.expand_path("../..", __dir__)
+
+    EXAMPLE_ROOTS = Corpus.members(:example, root: ROOT).map(&:path)
+    META_FILES    = (Dir.glob(File.join(ROOT, "lib/hecks/grammar/*.bluebook")) +
+                      Dir.glob(File.join(ROOT, "lib/hecks/framework/bluebook/*.bluebook")) +
+                      Dir.glob(File.join(ROOT, "lib/hecks/language/bluebook/**/*.bluebook"))).sort
+
+    # Boots the lightweight, in-memory path — a codemod only reads a chapter's
+    # own declared IR, never a stored record, so it has no reason to need Postgres.
+    PERSISTENCE_PORT = File.join(ROOT, "lib/hecks/ports/persistence.port")
+    EXTRACTION_PORT  = File.join(ROOT, "lib/hecks/ports/extraction.port")
+    MEMORY_ADAPTER   = File.join(ROOT, "lib/hecks/adapters/driven/memory.adapter")
+    PRISM_ADAPTER    = File.join(ROOT, "lib/hecks/adapters/driven/prism.adapter")
+
+    def self.export_json(registry) = Hecks::Projector::Exporter.json(registry)
+
+    # Text that stands in for a file while a dry run judges an edit.
+    #
+    # `Kernel.load` evaluates the staged text in place of the file, under the file's own path, so
+    # a codemod can boot the edited bluebook without writing a tracked file: a dry run that is
+    # interrupted, or read by a parallel process, leaves the checkout exactly as it was.
+    module Shadow
+      # Prepended to `Kernel`'s singleton: loads staged text when there is any for the file.
+      module Loader
+        # @param file [String] the path being loaded
+        # @return [Boolean] true, as `Kernel.load` answers
+        def load(file, *)
+          text = Shadow.texts[file.to_s]
+          return super unless text
+
+          Hecks::Adapters::Prism::TREES[file.to_s] = ::Prism.parse(text).value
+          eval(text, TOPLEVEL_BINDING.dup, file.to_s, 1)
+          true
+        end
+      end
+      Kernel.singleton_class.prepend(Loader)
+
+      module_function
+
+      # @return [Hash{String => String}] the staged text by absolute path
+      def texts = (@texts ||= {})
+
+      # Stages `text` as `file`'s contents and drops the file's cached parse.
+      #
+      # @param file [String] the path the text stands in for
+      # @param text [String] the staged source
+      # @return [String] the text
+      def put(file, text)
+        Hecks::Adapters::Prism.forget(file)
+        texts[file] = text
+      end
+
+      # Stops standing in for `file`.
+      #
+      # @param file [String] the path to read from disk again
+      # @return [void]
+      def drop(file)
+        texts.delete(file)
+        Hecks::Adapters::Prism.forget(file)
+      end
+
+      # @return [Boolean] whether any text is staged
+      def active? = !texts.empty?
+    end
+
+    # Puts `text` where `file`'s next load will find it: on disk, or (a dry run) staged in memory.
+    #
+    # @param file [String] the bluebook's path
+    # @param text [String] the new source
+    # @param dry_run [Boolean] whether to leave the file untouched
+    # @return [void]
+    def self.stage(file, text, dry_run:)
+      dry_run ? Shadow.put(file, text) : File.write(file, text)
+    end
+
+    # Undoes `stage`: rewrites the original, or stops staging.
+    #
+    # @param file [String] the bluebook's path
+    # @param original [String] the source as it was on disk
+    # @param dry_run [Boolean] whether the edit was only staged
+    # @return [void]
+    def self.unstage(file, original, dry_run:)
+      dry_run ? Shadow.drop(file) : File.write(file, original)
+    end
+
+    # Forgets each path's cached AST first — a stale tree after editing a file
+    # misreports that file's own source locations.
+    def self.load_bluebook(path)
+      paths = if path.is_a?(Array)
+                path
+              elsif File.directory?(path)
+                Dir.glob(File.join(path, "*.bluebook"))
+              else
+                [path]
+              end
+      paths.each { |file| Hecks::Adapters::Prism.forget(file) }
+
+      registry = Hecks::Runtime::Registry.new
+      Hecks.with_registry(registry) do
+        Kernel.load(PERSISTENCE_PORT)
+        Kernel.load(EXTRACTION_PORT)
+        Kernel.load(MEMORY_ADAPTER)
+        Kernel.load(PRISM_ADAPTER)
+        Hecks::Bluebook::MetaValidator.defer { paths.each { |file| Kernel.load(file) } }
+        Hecks::Bluebook::MetaValidator.judge_deferred!(registry)
+      end
+      registry
+    end
+
+    # Forgets every tree, not just one — callers rarely know which of the
+    # meta-domain's several files they just edited.
+    def self.boot_meta
+      Hecks::Adapters::Prism.forget_all
+      Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
+      export_json(Hecks::Bluebook::MetaValidator.grammar_registry)
+    end
+
+    def self.meta_registry
+      Hecks::Adapters::Prism.forget_all
+      Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
+      Hecks::Bluebook::MetaValidator.grammar_registry
+    end
+
+    # Walks nested entities recursively too, not just each aggregate's own commands.
+    def self.each_command(registry)
+      registry.bluebooks.each_value do |chapter|
+        chapter.aggregates.each do |aggregate|
+          walk = lambda do |construct|
+            construct.commands.each { |command| yield construct, command }
+            construct.entities.each(&walk) if construct.respond_to?(:entities)
+          end
+          walk.call(aggregate)
+        end
+      end
+    end
+
+    def self.owner_attribute(construct, name)
+      construct.attributes.find { |attr| attr.name.to_s == name.to_s }
+    end
+
+    # Raises on a name collision between a value object and an entity — nothing
+    # in the DSL prevents two from sharing a `hecks_name`, so it can't be resolved silently.
+    def self.element_construct_for(construct, list_field)
+      list_attr = owner_attribute(construct, list_field)
+      return nil unless list_attr&.list?
+
+      value_objects = construct.respond_to?(:value_objects) ? construct.value_objects : []
+      entities      = construct.respond_to?(:entities) ? construct.entities : []
+      matches = (value_objects + entities).select { |c| c.hecks_name.to_s == list_attr.type.to_s }
+
+      if matches.size > 1
+        raise "#{construct.hecks_name}##{list_field} names #{list_attr.type}, held by both a value " \
+              "object and an entity — ambiguous, cannot resolve which one the list holds"
+      end
+
+      matches.first
+    end
+
+    # Rescues StandardError only, so a genuine bug still raises rather than
+    # silently counting as an unsafe candidate to revert.
+    def self.safely
+      [yield, nil]
+    rescue StandardError => e
+      [nil, "#{e.class}: #{e.message}"]
+    end
+
+    # Runs one codemod rule across every example domain and the meta-domain,
+    # verifying each candidate edit via IR diff before keeping it.
+    class Runner
+      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  #{r[:file]} (#{r[:reason]}): #{Array(r[:candidates]).join(', ')}" }
+      end
+
+      private
+
+      def apply_many(text, candidates)
+        applied = []
+        candidates.each do |c|
+          text, changed = @apply_candidate.call(text, c)
+          applied << c if changed
+        end
+        [text, applied]
+      end
+
+      # Kept as one method: the write/verify/revert sequence is a single unit,
+      # and splitting it would scatter shared state for no readability gain.
+      # rubocop:disable-next Metrics/AbcSize
+      # rubocop:disable-next Metrics/BlockLength
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/MethodLength
+      # rubocop:disable-next Metrics/PerceivedComplexity
+      def run_example_domains(results, dry_run)
+        Codemod::EXAMPLE_ROOTS.each do |domain_dir|
+          bluebook_files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
+          next if bluebook_files.empty?
+
+          before_json = Codemod.export_json(Codemod.load_bluebook(bluebook_files))
+          candidates  = @find_candidates.call(Codemod.load_bluebook(bluebook_files))
+
+          if candidates.empty?
+            results[:clean] << domain_dir
+            next
+          end
+
+          live = bluebook_files.to_h { |file| [file, File.read(file)] }
+          applied_by_file = Hash.new { |hash, file| hash[file] = [] }
+
+          candidates.each do |candidate|
+            target_file = bluebook_files.find { |file| apply_many(live[file], [candidate]).last.any? }
+            unless target_file
+              results[:skipped] << { file: domain_dir, reason: "no matching source line", candidates: [@label.call(candidate)] }
+              next
+            end
+
+            original_text = live[target_file]
+            text, = apply_many(original_text, [candidate])
+            live[target_file] = text
+            Codemod.stage(target_file, text, dry_run: dry_run)
+            after_json, error = Codemod.safely do
+              Codemod.export_json(Codemod.load_bluebook(bluebook_files))
+            end
+
+            if after_json == before_json && !dry_run
+              applied_by_file[target_file] << candidate
+            elsif after_json == before_json
+              live[target_file] = original_text
+              Codemod.unstage(target_file, original_text, dry_run: dry_run)
+              Codemod.safely { Codemod.load_bluebook(bluebook_files) }
+              applied_by_file[target_file] << candidate
+            else
+              live[target_file] = original_text
+              Codemod.unstage(target_file, original_text, dry_run: dry_run)
+              Codemod.safely { Codemod.load_bluebook(bluebook_files) }
+              reason = error ? "reboot raised after edit (#{error}) — reverted" : "IR changed after edit — reverted"
+              results[:skipped] << { file: target_file, reason: reason, candidates: [@label.call(candidate)] }
+            end
+          end
+
+          applied_by_file.each do |file, applied|
+            results[:applied] << { file: file, candidates: applied.map(&@label) }
+          end
+        end
+      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.
+      # rubocop:disable-next Metrics/AbcSize
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/PerceivedComplexity
+      def run_meta_domain(results, dry_run)
+        before_meta     = Codemod.boot_meta
+        meta_candidates = @find_candidates.call(Codemod.meta_registry)
+
+        if meta_candidates.empty?
+          results[:clean] << "meta-domain"
+          return
+        end
+
+        live_meta = Codemod::META_FILES.to_h { |f| [f, File.read(f)] }
+        applied_by_file = Hash.new { |h, k| h[k] = [] }
+
+        meta_candidates.each do |candidate|
+          target_file = Codemod::META_FILES.find { |f| apply_many(live_meta[f], [candidate]).last.any? }
+          unless target_file
+            results[:skipped] << { file: "meta-domain", reason: "no matching source line", candidates: [@label.call(candidate)] }
+            next
+          end
+
+          text, = apply_many(live_meta[target_file], [candidate])
+          original_text = live_meta[target_file]
+          live_meta[target_file] = text
+          Codemod::META_FILES.each { |f| Codemod.stage(f, live_meta[f], dry_run: dry_run) }
+
+          # 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.
+          after_meta, error = Codemod.safely { Codemod.boot_meta }
+
+          if after_meta == before_meta && !dry_run
+            applied_by_file[target_file] << candidate
+          elsif after_meta == before_meta # dry-run, safe — revert, but count as applied
+            live_meta[target_file] = original_text
+            Codemod::META_FILES.each { |f| Codemod.unstage(f, live_meta[f], dry_run: dry_run) }
+            Codemod.safely { Codemod.boot_meta }
+            applied_by_file[target_file] << candidate
+          else
+            live_meta[target_file] = original_text
+            Codemod::META_FILES.each { |f| Codemod.unstage(f, live_meta[f], dry_run: dry_run) }
+            Codemod.safely { Codemod.boot_meta } # resync memoized state to the reverted text
+            reason = error ? "reboot raised (#{error})" : "IR changed"
+            results[:skipped] << { file: "meta-domain", reason: reason, candidates: [@label.call(candidate)] }
+          end
+        end
+
+        applied_by_file.each do |file, candidates|
+          results[:applied] << { file: file, candidates: candidates.map(&@label) }
+        end
+      end
+    end
+  end
+end