hecks 2.7.0 → 2.9.0

data/lib/hecks/bench/workload.rb

@@ -1,137 +0,0 @@
-require "json"
-
-module Hecks
-  module Bench
-    # A fixed command sequence for one example domain, identical for every runtime.
-    #
-    # `setup` runs once, untimed, before a run starts. `cycle(n)` answers the timed
-    # commands for the n-th unit of work. Every cycle names its own records by `n`, so
-    # cycles never collide and no command is ever refused: a refusal would mean the
-    # benchmark measured a rejection path rather than the work it claims.
-    #
-    # Steps are the same `{"verb", "args"}` shape `bin/run` and the corpus scripts use.
-    # Ruby dispatches them through `dispatch_flat` and the Rust binary reads them as
-    # JSON lines, so both runtimes see byte-identical input.
-    class Workload
-      # One command to dispatch.
-      #
-      # @!attribute verb
-      #   @return [String] the fully qualified command, e.g. `"Pizzas::Order.CreatePizza"`
-      # @!attribute args
-      #   @return [Hash{String => Object}] the command's arguments, string-keyed throughout
-      Step = Struct.new(:verb, :args) do
-        # Renders the step as one line of `rust --serve` input.
-        #
-        # @return [String] the step as compact JSON with no trailing newline
-        def to_json_line
-          JSON.generate("verb" => verb, "args" => args)
-        end
-
-        # Gives the arguments as `dispatch_flat` takes them.
-        #
-        # @return [Hash{Symbol => Object}] `args` with only its top-level keys symbolized,
-        #   the way the corpus replay hands them over
-        def ruby_args
-          args.transform_keys(&:to_sym)
-        end
-      end
-
-      # @return [String] the example domain's directory name, also its Cargo feature
-      attr_reader :name
-
-      # @return [String] the absolute path of the example domain directory
-      attr_reader :domain_path
-
-      # @return [Array<Step>] the commands run once, untimed, before any cycle
-      attr_reader :setup
-
-      # Builds a workload.
-      #
-      # @param name [String] the example domain's directory name, e.g. `"pizzas"`
-      # @param setup [Array<Step>] the untimed preparation commands
-      # @param cycle [#call] takes a cycle number and returns that cycle's `Array<Step>`
-      def initialize(name:, setup:, cycle:)
-        @name = name
-        @domain_path = File.expand_path("../../../examples/#{name}", __dir__)
-        @setup = setup
-        @cycle = cycle
-      end
-
-      # Gives the timed commands for one unit of work.
-      #
-      # @param number [Integer] the zero-based cycle number, unique across warmup and
-      #   measurement so record names never repeat
-      # @return [Array<Step>] the commands in dispatch order
-      def cycle(number) = @cycle.call(number)
-
-      # Gives how many commands each cycle dispatches.
-      #
-      # @return [Integer] the length of every cycle
-      def commands_per_cycle = cycle(0).size
-
-      # Lists the workloads `bin/bench` knows.
-      #
-      # @return [Hash{String => Workload}] each workload keyed by its domain name
-      def self.all
-        { "pizzas" => pizzas, "banking" => banking }
-      end
-
-      # Looks up one workload.
-      #
-      # @param name [String] a key of `.all`
-      # @return [Workload] the workload for `name`
-      # @raise [ArgumentError] if there is no workload with that name
-      def self.fetch(name)
-        all.fetch(name) do
-          raise ArgumentError, "unknown domain #{name.inspect} — one of #{all.keys.join(', ')}"
-        end
-      end
-
-      # A pizza is created, topped twice and bought: four commands and two aggregate updates.
-      #
-      # @return [Workload] the pizzas workload
-      def self.pizzas
-        new(name: "pizzas", setup: [], cycle: lambda { |n|
-          pizza = "pizza-#{n}"
-          [
-            Step.new("Pizzas::Order.CreatePizza",
-                     { "name"  => { "value" => pizza },
-                       "pizza" => { "price_cents" => { "cents" => 1200 }, "size" => { "value" => "large" } } }),
-            Step.new("Pizzas::Order.AddTopping",
-                     { "name" => pizza, "topping" => { "value" => "Basil" }, "amount" => { "value" => 3 } }),
-            Step.new("Pizzas::Order.AddTopping",
-                     { "name" => pizza, "topping" => { "value" => "Olive" }, "amount" => { "value" => 2 } }),
-            Step.new("Pizzas::Order.Purchase",
-                     { "name" => pizza, "customer_name" => { "value" => "Chris" },
-                       "amount" => { "cents" => 1200 } })
-          ]
-        })
-      end
-
-      # An account is opened, credited twice and debited once, all for one registered customer.
-      #
-      # @return [Workload] the banking workload
-      def self.banking
-        register = Step.new("Banking::Customer.Register",
-                            { "reference" => { "value" => "CUST-0001" },
-                              "name"      => { "given" => "Ada", "family" => "Lovelace" },
-                              "email"     => { "address" => "ada@example.com" } })
-        new(name: "banking", setup: [register], cycle: lambda { |n|
-          number = { "value" => "acct-#{n}" }
-          money = ->(cents) { { "cents" => cents, "currency" => "USD" } }
-          [
-            Step.new("Banking::Account.Open",
-                     { "number" => number, "kind" => { "name" => "current" },
-                       "daily_limit" => { "cents" => 50_000 }, "customer" => "CUST-0001" }),
-            Step.new("Banking::Account.Credit",
-                     { "number" => number, "amount" => money.call(10_000), "narrative" => { "text" => "Deposit" } }),
-            Step.new("Banking::Account.Credit",
-                     { "number" => number, "amount" => money.call(5000), "narrative" => { "text" => "Deposit" } }),
-            Step.new("Banking::Account.Debit",
-                     { "number" => number, "amount" => money.call(2500), "narrative" => { "text" => "Groceries" } })
-          ]
-        })
-      end
-    end
-  end
-end

data/lib/hecks/bench.rb

@@ -1,28 +0,0 @@
-module Hecks
-  # The throughput and latency harness `bin/bench` drives.
-  #
-  # It dispatches a fixed, valid command workload against the Ruby runtime on each
-  # persistence adapter and against the native Rust binary, and reports
-  # commands per second plus p50 and p99 latency for each. Not required by
-  # `lib/hecks.rb` on purpose: a booted domain never needs it.
-  #
-  # ## What is measured
-  #
-  # Every runtime is driven the same way: one caller, one command at a time, each
-  # waiting for the previous answer. The Ruby side times `dispatch_flat` in-process.
-  # The Rust side times a full round trip over the pipes of `rust --serve`. See
-  # `docs/benchmarks.md` for what that does and does not compare.
-  module Bench
-  end
-end
-
-require_relative "bench/stats"
-require_relative "bench/workload"
-require_relative "bench/environment"
-require_relative "bench/postgres_probe"
-require_relative "bench/run"
-require_relative "bench/ruby_runner"
-require_relative "bench/rust_runner"
-require_relative "bench/suite"
-require_relative "bench/report"
-require_relative "bench/cli"

data/lib/hecks/codemod.rb

@@ -1,443 +0,0 @@
-require_relative "bluebook/meta_validator"
-require_relative "corpus"
-
-module Hecks
-  # Shared machinery for a codemod that migrates real `.bluebook` source.
-  #
-  # ## Why this module exists
-  #
-  # For migrating source once a DSL builder change turns a required
-  # declaration into an optional, redundant one — pulled out of
-  # `bin/codemod_implicit_append_fields` (the first one built), which
-  # needed three real, hard-won fixes before it could be trusted: a
-  # process-lifetime AST cache with no invalidation, a batch-revert
-  # granularity that let one unsafe candidate sink every other safe one
-  # sharing its boot, and (in the spine the codemod migrates for, not
-  # here) an append-at-end insertion that only round-tripped correctly
-  # for whichever field happened to be last. None of those are guessable
-  # in advance; they only surface by actually running a real edit
-  # against real self-hosted code. This module is that lesson, kept —
-  # the next codemod plugs in two rule-specific procs (`find_candidates`,
-  # `apply_candidate`) and inherits the boot/safety-net machinery rather
-  # than rediscovering it.
-  #
-  # ## The three-step contract
-  #
-  # **A codemod is not pattern-matching alone**. Deciding "is this line safe
-  # to delete" means knowing what the runtime would resolve it to — so
-  # every codemod built on this module follows the same three steps:
-  #   1. Boot the real domain (or the self-hosted meta-domain) and read
-  #      its IR to find candidates — provided by the caller's own
-  #      `find_candidates`, since the actual redundancy rule is specific
-  #      to whichever spine change this migration serves.
-  #   2. Locate and remove each candidate's own source text — the
-  #      caller's own `apply_candidate`.
-  #   3. Re-boot from the edited text and diff the full IR export
-  #      against the pre-edit export. Byte-identical -> keep. Anything
-  #      else (including a raised exception — the self-hosted
-  #      meta-domain dispatches itself into being, S14, so a bad edit
-  #      can surface as a runtime refusal, not just a differing export)
-  #      -> revert and report skipped, never silently guessed past.
-  #
-  # ## Design-time checklist for a future codemod
-  #
-  # For the spine change a future codemod migrates corpus text for —
-  # both items below are real bugs this module's own first use found,
-  # not hypothetical:
-  #   - Does the resolved value get inserted into an order-sensitive
-  #     list (the exported IR is array-order-sensitive throughout)? If
-  #     so, the spine's own insertion must preserve the original
-  #     position, not just append — an append-at-end insertion only
-  #     round-trips correctly for a value that already happened to be
-  #     last.
-  #   - Does resolution depend on another construct already being
-  #     declared (the aggregate/entity a `sets`/`append:` field resolves
-  #     against)? If a creator command can be declared before the
-  #     construct it creates (real, live: `command "Handler"` before
-  #     `entity "Handler"`, one file down), one-pass resolution
-  #     genuinely cannot see it yet — not a codemod bug, a structural
-  #     limit worth naming rather than working around.
-  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
-
-    # The same lightweight path `spec/spec_helper.rb`'s own
-    # `boot_in_memory` uses — `Hecks.with_registry` satisfies
-    # `Hecks.bluebook`'s own `collect`'s "loaded outside a boot" check
-    # without `Hecks.boot`'s full era-check/adapter-wiring path, which
-    # needs a live Postgres connection for `compliance` and would make
-    # every codemod depend on a database it has no reason to touch — a
-    # codemod only ever reads a chapter's own declared IR, never a
-    # stored record.
-    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")
-
-    # Exports a booted registry's canonical IR as JSON, for a before/after diff.
-    #
-    # @param registry [Runtime::Registry] the booted registry to export
-    # @return [String] the pretty-printed JSON IR export
-    def self.export_json(registry) = Hecks::Projector::Exporter.json(registry)
-
-    # `Hecks::Adapters::Prism` caches a file's parsed AST for the
-    # life of the process, keyed by path — fine for every existing
-    # caller (a file loads once per process: one `bin/ir` run, one
-    # rspec worker), but a codemod legitimately reloads the same path
-    # after editing it, and a stale cached tree reports a
-    # `given`/`ensures` block at its old line number, which no longer
-    # matches the freshly re-executed file's own `block.source_location`
-    # — surfacing as "did not survive extraction" on a perfectly valid
-    # file. `Prism.forget` is the real invalidation API this module's
-    # own first use motivated (found here, fixed at the source rather
-    # than left as a private `TREES.clear` poke from outside).
-    #
-    # @param path [String, Array<String>] a single `.bluebook` file, a directory
-    #   to glob every `.bluebook` file from, or an explicit list of file paths
-    # @return [Runtime::Registry] a fresh registry with every file loaded and judged
-    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
-
-    # `forget_all`, not a single `forget` — the meta-domain is nine
-    # files (`MetaValidator::GRAMMAR_FILES`) merged into one registry,
-    # and a caller here (the codemod runner) doesn't generally know in
-    # advance which one it just edited.
-    # @return [String] the freshly re-derived meta-domain's canonical IR, as JSON
-    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
-
-    # Forces the self-hosted meta-domain to re-derive from its current source,
-    # discarding any cached parse trees or memoized registry.
-    #
-    # @return [Runtime::Registry] the freshly re-derived meta-domain's registry
-    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 every aggregate (and every nested entity, recursively)
-    # across every chapter in a booted registry, yielding [owning
-    # construct, command] pairs — `construct` is whichever
-    # Aggregate/Entity actually owns the command, the same distinction
-    # `AggregateBuilder#command` vs `EntityBuilder#command` already
-    # draws. Generic enough for any rule that needs to walk real
-    # commands, not specific to the attribute-redundancy rule.
-    #
-    # @param registry [Runtime::Registry] a booted registry
-    # @yield [construct, command] every command in the registry, once per aggregate
-    #   and once per nested entity
-    # @yieldparam construct [Bluebook::Aggregate, Bluebook::Entity] whichever
-    #   aggregate or entity actually owns `command`
-    # @yieldparam command [Bluebook::Command] the command
-    # @return [Hash{String => Bluebook::Chapter}] `registry.bluebooks`, unchanged
-    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
-
-    # Finds one construct's own attribute by name.
-    #
-    # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct to search
-    # @param name [String, Symbol, #to_s] the attribute's declared name
-    # @return [Bluebook::Attribute, nil] the matching attribute, or nil if `construct`
-    #   declares no attribute named `name`
-    def self.owner_attribute(construct, name)
-      construct.attributes.find { |attr| attr.name.to_s == name.to_s }
-    end
-
-    # A list attribute's own element construct — the value object or
-    # entity `list_of(...)` names, resolved by `hecks_name` the same way
-    # `AttributeCollector#resolve_identity_field!` already does. Shared
-    # because "what does this list actually hold" is a question any
-    # append-shaped rule needs answered, not just this one.
-    #
-    # Nothing in the DSL stops a value object and an entity nested under
-    # the same aggregate from sharing a `hecks_name` — they are declared
-    # through two separate collections with no cross-kind uniqueness
-    # check between them. A silent value-objects-before-entities pick
-    # would resolve such a pair the same way every time regardless of
-    # which one `list_field` actually names, so a genuine collision is
-    # refused instead, the same "never first-wins silently" call
-    # `EntityBuilder#install_closed_sets!` already makes for a same-named
-    # closed set.
-    #
-    # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
-    #   declaring `list_field`
-    # @param list_field [String, Symbol, #to_s] the name of the `list_of(...)` attribute
-    # @return [Bluebook::Entity, Bluebook::ValueObject, nil] the construct
-    #   `list_field` holds a list of, or nil if `list_field` names no attribute,
-    #   isn't a list, or names no known value object or entity
-    # @raise [RuntimeError] if a value object and an entity both match `list_field`'s type
-    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
-
-    # Either a raised exception or a differing export counts as unsafe
-    # — see the module header on why the meta-domain specifically can
-    # raise. Returns [value_or_nil, error_message_or_nil].
-    #
-    # @yield the risky boot/export step to run
-    # @return [Array(Object, nil), Array(nil, String)] `[the block's result, nil]`
-    #   on success, or `[nil, "ExceptionClass: message"]` if the block raises
-    #   any StandardError
-    def self.safely
-      [yield, nil]
-    rescue StandardError => e
-      [nil, "#{e.class}: #{e.message}"]
-    end
-
-    # **The reusable runner** — every real bug fix this module carries lives
-    # here, not in a caller's own script. A caller supplies:
-    #
-    #   find_candidates: ->(registry) { [...] }
-    #     Given a booted registry, return every candidate this rule
-    #     could migrate. A candidate is whatever shape the caller wants
-    #     — `apply_candidate` is the only other thing that reads it.
-    #
-    #   apply_candidate: ->(text, candidate) { [new_text, changed_bool] }
-    #     Given one file's current text and one candidate, return the
-    #     edited text and whether a match was actually found/removed —
-    #     `false` (text unchanged) when the candidate doesn't apply to
-    #     this file, which is how the meta-domain's multi-file search
-    #     below finds the right one without the caller needing to know
-    #     which file a candidate lives in ahead of time.
-    #
-    #   label: ->(candidate) { "..." }
-    #     One-line description for the results report.
-    class Runner
-      # @param find_candidates [Proc] `->(registry) { [...] }` — given a booted
-      #   registry, returns every candidate this rule could migrate; a candidate's
-      #   shape is the caller's own, read back only by `apply_candidate`
-      # @param apply_candidate [Proc] `->(text, candidate) { [new_text, changed_bool] }`
-      #   — given one file's current text and one candidate, returns the edited text
-      #   and whether a match was found; `false` means the candidate doesn't apply to
-      #   this file
-      # @param label [Proc] `->(candidate) { "..." }` — a one-line description of a
-      #   candidate, for the results report
-      def initialize(find_candidates:, apply_candidate:, label:)
-        @find_candidates = find_candidates
-        @apply_candidate = apply_candidate
-        @label = label
-      end
-
-      # Runs this rule's codemod across every example domain and the meta-domain.
-      #
-      # @param dry_run [Boolean] when true, every safe edit is still written and
-      #   reverified, then reverted rather than kept
-      # @return [Hash{Symbol => Array}] `:applied` (`Array<Hash{file: String,
-      #   candidates: Array<String>}>`), `:skipped` (`Array<Hash{file: String,
-      #   reason: String, candidates: Array<String>}>`), and `:clean`
-      #   (`Array<String>` of domain directories or `"meta-domain"` with no candidates)
-      def run(dry_run: false)
-        results = { applied: [], skipped: [], clean: [] }
-        run_example_domains(results, dry_run)
-        run_meta_domain(results, dry_run)
-        results
-      end
-
-      # Prints `run`'s results to stdout.
-      #
-      # @param results [Hash{Symbol => Array}] a `run` result
-      # @param dry_run [Boolean] whether this was a dry run, for the report's own heading
-      # @return [void]
-      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
-
-      # The per-candidate write/verify/revert sequence below is one
-      # coherent unit (see the comment ahead of the candidates.each
-      # loop for why it can't batch) — splitting it across methods just
-      # to satisfy the line count would scatter state four ways 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
-            File.write(target_file, text)
-            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
-              File.write(target_file, original_text)
-              Codemod.safely { Codemod.load_bluebook(bluebook_files) }
-              applied_by_file[target_file] << candidate
-            else
-              live[target_file] = original_text
-              File.write(target_file, original_text)
-              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 one batched write-then-verify — the
-      # meta-domain is one shared registry (SyntaxBoot dispatches it
-      # into itself, S14), so a single unsafe candidate among many would
-      # otherwise sink every other, genuinely safe candidate in the same
-      # run: this module's first real run found exactly that (25
-      # candidates, one dispatch-time break, all 25 reverted as a batch
-      # before this per-candidate loop existed). `before_meta` stays the
-      # fixed reference throughout — a truly safe candidate never
-      # changes the IR, so the running state's own export should always
-      # still equal the pristine original after each kept edit, by
-      # definition, no moving target needed.
-      # Same shape and same reason as run_example_domains just above (see
-      # its own comment) — the write/verify/revert sequence, per
-      # candidate (this method's own comment explains why it cannot
-      # batch), is one coherent unit; splitting it would scatter
-      # before_meta/live_meta/applied_by_file state across methods for
-      # no gain.
-      # 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| File.write(f, live_meta[f]) }
-
-          # **Dry run still verifies** — see run_example_domains' own
-          # comment; the edit is always written and rebooted for real,
-          # then always reverted afterward when dry-run (whether or not
-          # it was safe) so the next candidate is judged against the
-          # true original state, never an accumulated hypothetical.
-          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
-            File.write(target_file, original_text)
-            Codemod.safely { Codemod.boot_meta }
-            applied_by_file[target_file] << candidate
-          else
-            live_meta[target_file] = original_text
-            File.write(target_file, original_text)
-            Codemod.safely { Codemod.boot_meta } # restore cache/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