hecks 2.8.0 → 3.0.0

data/lib/hecks/quality_control/cli/qa_mine_combinations.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require_relative "../../../hecks"
+require_relative "../../fuzzing/combination_miner"
+require_relative "../../fuzzing/domain_generator"
+require_relative "../adapters/agent"
+require_relative "child"
+require_relative "../../cache_dir"
+require_relative "../../hecks/adapters/codebase/tree"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control mine_combinations`: asks an agent to mine the
+    # adversarial corpus for new domain combinations, then checks them. It is opt-in and never run
+    # by `hecks quality_control tick` (an agent call costs money and answers differently each run).
+    # `--brief` prints the agent's prompt and stops; `--from <dir>` re-checks an earlier run;
+    # `--against <domain>` narrows the census; `--agent "cmd"` reads the prompt on stdin.
+    #
+    # The agent defaults to `claude -p` (`QA_MINER_AGENT` overrides); candidates that boot are
+    # checked by `hecks quality_control check_generated_domains --source`, whose report is this
+    # command's report. Exit 0: all clean. 2: a finding (see `.claude/skills/hecks_qa/SKILL.md`). 1:
+    # an operational
+    # error.
+    class QaMineCombinations
+      EXIT_OK = 0
+      EXIT_ERROR = 1
+      RESULT_MARKER = "QA_GENERATED_RESULT "
+
+      USAGE = "usage: hecks quality_control mine_combinations [--candidates N] [--rust] [--seeds K] " \
+              "[--steps M] " \
+              "[--adversarial F] [--repair-rounds R] [--agent CMD] [--from <candidates-dir>] " \
+              "[--against <domain> …] [--brief]"
+
+      Miner = Hecks::Fuzzing::CombinationMiner
+
+      # Mines and checks the candidates.
+      #
+      # @param argv [Array<String>] the flags in the usage line
+      # @param root [String] the repository root
+      # @return [Integer] 0 all clean, 2 a finding, 1 an operational error
+      # @raise [SystemExit] on a bad argument, an agent that fails or writes nothing, or no
+      #   candidate that boots
+      def self.call(argv, root:)
+        new(root: root).call(argv)
+      end
+
+      # @param root [String] the repository root
+      def initialize(root:)
+        @root = root
+      end
+
+      # @param argv [Array<String>] the flags in the usage line
+      # @return [Integer] the exit status
+      # @raise [SystemExit] on a bad argument, an agent that fails or writes nothing, or no
+      #   candidate that boots
+      def call(argv)
+        @options = parse(argv.dup)
+        return EXIT_OK if @options == :help
+
+        @run_dir = File.join(runs_root, "run-#{Time.now.strftime('%Y%m%d-%H%M%S')}-#{Process.pid}")
+        @out_dir = @options[:from] || File.join(@run_dir, "candidates")
+        @agent_log = File.join(@run_dir, "agent.log")
+        @agent = Hecks::Adapters::Agent.new
+        @command = @agent.command_for(@options[:agent])
+        corpus = @options[:against].empty? ? Miner.corpus_paths(@root) : @options[:against]
+        @brief = Miner.brief(corpus, root: @root, bug_titles: Miner.recent_bug_titles(@root))
+        prompt = Miner.prompt(@root, @brief, count: @options[:candidates], out_dir: @out_dir)
+        if @options[:brief]
+          puts prompt
+          return EXIT_OK
+        end
+
+        mine(prompt)
+      end
+
+      # Each flag that takes a value: the option it sets and how the value is read.
+      VALUE_FLAGS = {
+        "--candidates" => [:candidates, ->(v) { Integer(v) }], "--seeds" => [:seeds, ->(v) { Integer(v) }],
+        "--steps" => [:steps, ->(v) { Integer(v) }], "--adversarial" => [:adversarial, ->(v) { Float(v) }],
+        "--repair-rounds" => [:repair_rounds, ->(v) { Integer(v) }], "--agent" => [:agent, :itself.to_proc],
+        "--from" => [:from, ->(v) { File.expand_path(v) }]
+      }.freeze
+
+      private
+
+      def parse(argv)
+        options = { candidates: 3, rust: false, seeds: 5, steps: 25, adversarial: 0.3, repair_rounds: 1,
+                    agent: nil, from: nil, brief: false, against: [] }
+        until argv.empty?
+          arg = argv.shift
+          if %w[-h --help].include?(arg)
+            puts USAGE
+            return :help
+          end
+          parse_flag(options, arg, argv)
+        end
+        options
+      end
+
+      def parse_flag(options, arg, argv)
+        case arg
+        when *VALUE_FLAGS.keys
+          key, reader = VALUE_FLAGS.fetch(arg)
+          options[key] = reader.call(argv.shift)
+        when "--rust" then options[:rust] = true
+        when "--brief" then options[:brief] = true
+        when "--against" then options[:against] << File.expand_path(argv.shift)
+        else abort "#{USAGE}\nunexpected argument: #{arg.inspect}"
+        end
+      end
+
+      def relative(path) = path.delete_prefix("#{@root}/")
+
+      # Runs are kept under the checkout's `tmp/`; an installed gem, or a root that cannot be
+      # written, keeps them under the cache root instead.
+      def runs_root
+        checkout = Hecks::Adapters::Codebase::Tree.new(root: @root).checkout? && File.writable?(@root)
+        checkout ? File.join(@root, "tmp/qa-mined") : Hecks::CacheDir.path("qa-mined")
+      end
+
+      # Returns nil when the agent finished, else why it did not.
+      def ask_agent(prompt)
+        @agent.ask(prompt: prompt, command: @command, chdir: @root, log: @agent_log)
+        nil
+      rescue Hecks::Adapters::Agent::Failed => e
+        e.message
+      end
+
+      def boot_error(candidate, boot_root)
+        dir = Hecks::Fuzzing::DomainGenerator.write(
+          { "source" => File.read(candidate[:bluebook]), "aggregates" => [], "policies" => [] },
+          File.join(boot_root, candidate[:slug])
+        )
+        output, = Open3.capture2e(*Child.argv(@root, "qa_generated_domains", "--check", dir, "--seeds", "0"),
+                                  chdir: @root)
+        line = output.lines.reverse.find { |candidate_line| candidate_line.start_with?(RESULT_MARKER) }
+        return "boot check produced no result: #{output.lines.last(5).join.strip}" unless line
+
+        result = JSON.parse(line.delete_prefix(RESULT_MARKER))
+        result["status"] == "invalid" ? result["error"] : nil
+      end
+
+      def mine(prompt)
+        FileUtils.mkdir_p(@out_dir)
+        FileUtils.mkdir_p(@run_dir)
+        puts "combination miner: #{@brief['corpus'].size} corpus domain(s), " \
+             "#{@brief['unmet_pairs'].size} unmet pair(s) — #{relative(@run_dir)}"
+        unless @options[:from]
+          puts "asking the agent for #{@options[:candidates]} candidate(s) (#{@command.first}; " \
+               "log #{relative(@agent_log)})…"
+          failure = ask_agent(prompt)
+          abort "combination miner: #{failure}" if failure
+        end
+
+        candidates = Miner.candidates(@out_dir)
+        abort "combination miner: the agent wrote no candidates under #{relative(@out_dir)}" if candidates.empty?
+
+        invalid, repaired = boot_and_repair(candidates)
+        report(candidates, invalid, repaired)
+        valid = candidates.reject { |candidate| invalid.key?(candidate[:slug]) }
+        abort "combination miner: no candidate booted — nothing to check" if valid.empty?
+
+        puts
+        check(valid)
+      end
+
+      # @return [Array(Hash, Array<String>)] the slug-to-error map of candidates that never booted,
+      #   and the slugs a repair round fixed
+      def boot_and_repair(candidates)
+        boot_root = File.join(@run_dir, "boot")
+        failures = candidates.filter_map { |candidate| (error = boot_error(candidate, boot_root)) && [candidate, error] }
+        repaired = []
+        @options[:repair_rounds].times do |round|
+          break if failures.empty? || @options[:from]
+
+          puts "repair round #{round + 1}: #{failures.size} candidate(s) did not boot — back to the agent…"
+          failure = ask_agent(Miner.repair_prompt(failures, out_dir: @out_dir))
+          abort "combination miner: #{failure}" if failure
+
+          still = failures.filter_map { |candidate, _| (error = boot_error(candidate, boot_root)) && [candidate, error] }
+          repaired.concat(failures.map { |candidate, _| candidate[:slug] } - still.map { |candidate, _| candidate[:slug] })
+          failures = still
+        end
+        [failures.to_h { |candidate, error| [candidate[:slug], error] }, repaired]
+      end
+
+      def report(candidates, invalid, repaired)
+        puts
+        candidates.each do |candidate|
+          if invalid.key?(candidate[:slug])
+            puts "  #{candidate[:slug]}: INVALID — #{invalid[candidate[:slug]]}"
+            next
+          end
+
+          pairs = begin
+            Miner.new_pairs(candidate[:dir], @brief["covered"])
+          rescue StandardError, ScriptError => e
+            ["(census failed: #{e.class})"]
+          end
+          puts "  #{candidate[:slug]}: boots#{' (repaired)' if repaired.include?(candidate[:slug])}; " \
+               "new pair(s): #{pairs.empty? ? 'none' : pairs.join(', ')}"
+          first = candidate[:hypothesis].to_s.lines.map(&:strip).find { |line| !line.empty? && !line.start_with?("#") }
+          puts "    #{first}" if first
+        end
+      end
+
+      def check(valid)
+        args = ["--start", (Time.now.to_i % 1_000_000).to_s, "--seeds", @options[:seeds].to_s,
+                "--steps", @options[:steps].to_s, "--adversarial", @options[:adversarial].to_s]
+        args << "--rust" if @options[:rust]
+        args.concat(valid.flat_map { |candidate| ["--source", candidate[:bluebook]] })
+        _, status = Process.wait2(Process.spawn(*Child.argv(@root, "qa_generated_domains", *args), chdir: @root))
+        status.exitstatus || EXIT_ERROR
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_open_pr.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require_relative "../../../hecks"
+# The era subsystem does not load with core (ADR 0033).
+require_relative "../../ports/persistence/plugins/era"
+require_relative "../adapters/git_pr"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control patch.open`: opens a PR and records it in the
+    # QualityControl ledger in one step. It is the only door into `QualityControl::Patch.Open` and
+    # `QualityControl::Improvement.Open`.
+    #
+    # It refuses (exit 1, nothing opened or recorded) unless the ledger's own `Open` command would
+    # take the record and the `GitPr` adapter agrees. The command's `given`s are the rules, asked
+    # as a dry run before anything is opened: the branch starts with the practice's prefix; with
+    # `--bug`, the bug is `fixed`; with `--angle`, it is `investigating`. The adapter answers the
+    # rest: the tree is clean, `PR_CAP_PER_DAY` (0 = uncapped) is unmet since local midnight, and
+    # the bug's commit is an ancestor of `HEAD`. It is idempotent. `QA_REPO_DIR` picks the checkout
+    # `git` runs in, so a spec can use a throwaway repo and a fake `gh`.
+    class QaOpenPr
+      EXIT_OK = 0
+
+      USAGE = "usage: hecks quality_control patch.open --bug BUG#n --title \"…\" [--body \"…\"]\n       " \
+              "hecks quality_control improvement.open --improvement [--angle ANGLE-n] --title \"…\" [--body \"…\"]"
+
+      SHA_PATTERN = /\A[0-9a-fA-F]{7,40}\z/
+
+      # Stands in for the commit of a bug that is not fixed yet, so its dry run reaches the `given`.
+      PLACEHOLDER_COMMIT = "0000000"
+
+      # Opens and records the PR.
+      #
+      # @param argv [Array<String>] `--bug`, `--improvement`, `--angle`, `--title` and `--body`
+      # @param root [String] the repository root
+      # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` and `QA_REPO_DIR`
+      # @return [Integer] 0 once opened and recorded
+      # @raise [SystemExit] with `refused: ...` when a rule refuses, or the arguments are wrong
+      def self.call(argv, root:, env: ENV)
+        new(root: root, env: env).call(argv)
+      end
+
+      # @param root [String] the repository root
+      # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` and `QA_REPO_DIR`
+      def initialize(root:, env: ENV)
+        @domain_dir = env.fetch("QA_SWEEP_DOMAIN_DIR", File.join(root, "qa/bluebook"))
+        @repo_dir = env.fetch("QA_REPO_DIR", root)
+      end
+
+      # @param argv [Array<String>] the command line's arguments
+      # @return [Integer] the exit status
+      # @raise [SystemExit] with `refused: ...` when a rule refuses, or the arguments are wrong
+      def call(argv)
+        options = parse(argv.dup)
+        return EXIT_OK if options == :help
+
+        @options = options
+        @git_pr = Hecks::Adapters::GitPr.new(repo_dir: @repo_dir)
+        @branch = refusing { @git_pr.branch }
+        refusing { @git_pr.assert_clean_tree! }
+        @runtime = boot_ledger
+        find_citations
+        check_rules
+        view = open_pull_request
+        record(view)
+        merge_when_green(view[:number]) if dial(:AUTO_MERGE, false)
+        puts "#{view[:url]} (#{view[:headRefName]} @ #{view[:headRefOid].to_s[0, 7]}) — #{view[:title]}"
+        EXIT_OK
+      end
+
+      private
+
+      def parse(argv)
+        options = {}
+        until argv.empty?
+          arg = argv.shift
+          case arg
+          when "-h", "--help"
+            puts USAGE
+            return :help
+          when "--improvement"
+            options[:improvement] = true
+          when "--bug", "--angle", "--title", "--body"
+            value = argv.shift
+            abort "#{USAGE}\n#{arg} needs a value" if value.nil? || value.empty?
+            options[arg.delete_prefix("--").to_sym] = value
+          else
+            abort "#{USAGE}\nunexpected argument: #{arg.inspect}"
+          end
+        end
+        validate(options)
+      end
+
+      def validate(options)
+        abort "#{USAGE}\n--title is required" unless options[:title]
+        abort "#{USAGE}\ngive --bug BUG#n OR --improvement, not both" if options[:bug] && options[:improvement]
+        abort "#{USAGE}\ngive --bug BUG#n or --improvement" unless options.key?(:bug) || options.key?(:improvement)
+        abort "#{USAGE}\n--angle only means something with --improvement" if options[:angle] && !options[:improvement]
+
+        options
+      end
+
+      # Every rule the adapter enforces refuses the same way: exit 1, nothing opened or recorded.
+      def refusing
+        yield
+      rescue Hecks::Adapters::GitPr::Refusal, Hecks::Adapters::GitPr::CommandFailed => e
+        abort "refused: #{e.message}"
+      end
+
+      def boot_ledger
+        Hecks.boot(@domain_dir)
+      rescue StandardError => e
+        abort "the QualityControl ledger did not boot — fix the ledger itself before opening a PR against it " \
+              "(#{e.class}: #{e.message})"
+      end
+
+      def query(name, **args) = @runtime.query("QualityControl::#{name}", **args)
+
+      # Falls back to a dial-less fixture ledger's values: uncapped, non-draft, no auto-merge.
+      def dial(name, fallback)
+        return fallback unless defined?(::QualityControlDials) && ::QualityControlDials.const_defined?(name)
+
+        ::QualityControlDials.const_get(name)
+      end
+
+      def find_citations
+        @bug = @angle = nil
+        if @options[:bug]
+          @bug = ::QualityControl::Bug.find(@options[:bug])
+          abort "refused: no such bug #{@options[:bug].inspect}" unless @bug
+        end
+        return unless @options[:angle]
+
+        @angle = ::QualityControl::Angle.find(@options[:angle])
+        abort "refused: no such angle #{@options[:angle].inspect}" unless @angle
+      end
+
+      # What a refused `given` says to do next, by the rule's own wording; nothing for a rule it
+      # does not know.
+      def hint_for(rule)
+        case rule
+        when "the bug is fixed"
+          " (#{@bug.id} is #{@bug.status.inspect} — dispatch investigate and fix first " \
+          "(hecks run qa/bluebook fix id=#{@bug.id} reference.value=#{@bug.id} commit.value=<sha>))"
+        when "the angle is under investigation"
+          " (#{@angle.id} is #{@angle.status.inspect} — dispatch angle.investigate first, so the lead " \
+          "reads as picked up before something is built from it)"
+        when "the branch is one this practice recognises as its own"
+          " (the branch is #{@branch.inspect}; a PR this practice opens is on a branch it can recognise " \
+          "as its own, QualityControlDials::BRANCH_PREFIX)"
+        else ""
+        end
+      end
+
+      # Asks the ledger whether `verb` would take these facts, without recording anything. The
+      # number is one no record holds yet, so the dry run reaches the `given`s rather than
+      # `AlreadyExists`.
+      def refuse_unless_ledger_takes(verb, **facts)
+        @runtime.dry_run?(verb, **facts)
+      rescue Hecks::Runtime::GivenNotMet => e
+        hint = hint_for(e.message.split(" — ", 2).last)
+        abort "refused: #{e.message}#{hint} — a dry run of #{verb}, so nothing was opened or recorded"
+      end
+
+      def next_number(aggregate)
+        query("#{aggregate}.All").map { |row| row[:number][:value] }.max.to_i + 1
+      end
+
+      def check_rules
+        recorded = { url: { value: "https://github.com/pull/0" }, title: { value: @options[:title] },
+                     branch: { value: @branch }, now: { value: Time.now.to_i } }
+        if @bug
+          commit = @bug.commit.to_h[:value].to_s
+          refuse_unless_ledger_takes("QualityControl::Patch.Open",
+                                     bug: @bug.id, number: { value: next_number("Patch") },
+                                     commit: { value: commit.match?(SHA_PATTERN) ? commit : PLACEHOLDER_COMMIT },
+                                     **recorded)
+        else
+          refuse_unless_ledger_takes("QualityControl::Improvement.Open",
+                                     **(@angle ? { angle: @angle.id } : {}),
+                                     number: { value: next_number("Improvement") }, **recorded)
+        end
+        check_daily_cap
+        check_ancestry
+      end
+
+      def check_daily_cap
+        cap = dial(:PR_CAP_PER_DAY, 0)
+        return unless cap.positive?
+
+        today = Time.now
+        midnight = Time.new(today.year, today.month, today.day).to_i
+        opened_today = query("Patch.OpenedSince", since: { value: midnight }).size +
+                       query("Improvement.OpenedSince", since: { value: midnight }).size
+        refusing { @git_pr.assert_under_daily_cap!(opened_today: opened_today, cap: cap) }
+      end
+
+      def check_ancestry
+        return unless @bug
+
+        commit = @bug.commit.to_h[:value].to_s
+        abort "refused: #{@bug.id} carries no commit" unless commit.match?(SHA_PATTERN)
+
+        refusing do
+          @git_pr.assert_ancestor!(commit: commit, owner: @bug.id)
+          @git_pr.assert_pushed!(branch: @branch, commit: commit, owner: @bug.id)
+        end
+      end
+
+      # @return [Hash] `gh`'s view of the PR, opened here when the branch had none
+      def open_pull_request
+        view = refusing { @git_pr.open_pull_request(@branch) }
+        if view
+          puts "PR ##{view[:number]} already open for #{@branch} — not re-creating"
+        else
+          create_pull_request
+          view = refusing { @git_pr.open_pull_request(@branch) }
+          abort "gh pr create returned, but gh pr view #{@branch} shows no open PR — record nothing" unless view
+        end
+        sha = view[:headRefOid].to_s
+        unless sha.match?(SHA_PATTERN)
+          abort "refused: gh reports head #{sha.inspect} for ##{view[:number]}, which does not look like a sha"
+        end
+
+        check_pr_head(sha)
+        view
+      end
+
+      # The PR must carry the fix commit, whether this run opened it or an earlier one did.
+      def check_pr_head(sha)
+        return unless @bug
+
+        refusing { @git_pr.assert_pr_head!(head: sha, commit: @bug.commit.to_h[:value].to_s, owner: @bug.id) }
+      end
+
+      def create_pull_request
+        # The body names the ledger record so the PR and the ledger point at each other.
+        cited = if @bug then "Fixes #{@bug.id}."
+                elsif @angle then "Builds #{@angle.id}."
+                else "Deliberate work, no Bug or Angle behind it."
+                end
+        body = @options[:body] ||
+               "#{cited}\n\nOpened by hecks quality_control patch.open and recorded in the QualityControl ledger."
+        begin
+          @git_pr.create_pull_request(branch: @branch, title: @options[:title], body: body,
+                                      draft: dial(:DRAFT_ONLY, false))
+        rescue Hecks::Adapters::GitPr::CommandFailed => e
+          abort e.message
+        end
+      end
+
+      def record(view)
+        number = view[:number]
+        sha = view[:headRefOid].to_s
+        now = Time.now.to_i
+        if @bug
+          record_patch(view, number, sha, now)
+        else
+          record_improvement(view, number, sha, now)
+        end
+      end
+
+      def record_patch(view, number, sha, now)
+        if query("Patch.All").map { |row| row[:number][:value] }.include?(number)
+          puts "Patch ##{number} already recorded — not re-recording"
+          return
+        end
+
+        ::QualityControl::Patch.open!(
+          bug: @bug.id, number: { value: number }, url: { value: view[:url] },
+          branch: { value: view[:headRefName] }, commit: { value: sha }, title: { value: view[:title] },
+          now: { value: now }
+        )
+        puts "recorded Patch ##{number} for #{@bug.id} at #{sha[0, 7]}"
+      end
+
+      def record_improvement(view, number, sha, now)
+        existing = ::QualityControl::Improvement.find(number)
+        if existing && existing.status != "opened"
+          puts "Improvement ##{number} already recorded (#{existing.status}) — not re-recording"
+          return
+        end
+
+        # A run that stopped between `open!` and `land!` leaves the record `opened`: finish it.
+        existing || ::QualityControl::Improvement.open!(
+          **(@angle ? { angle: @angle.id } : {}),
+          number: { value: number }, url: { value: view[:url] },
+          branch: { value: view[:headRefName] }, title: { value: view[:title] },
+          now: { value: now }
+        )
+        ::QualityControl::Improvement.find(number).land!(number: { value: number }, commit: { value: sha })
+        puts "recorded Improvement ##{number}#{" for #{@angle.id}" if @angle}, landed at #{sha[0, 7]}"
+      end
+
+      def merge_when_green(number)
+        begin
+          @git_pr.merge_when_green(number)
+        rescue Hecks::Adapters::GitPr::CommandFailed => e
+          abort "recorded, but #{e.message}"
+        end
+        puts "auto-merge queued for ##{number} (QualityControlDials::AUTO_MERGE)"
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_postgres_migrate.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "../../../hecks"
+# The era subsystem does not load with core; a `PostgresEra` domain needs it (ADR 0033).
+require_relative "../../ports/persistence/plugins/era"
+require_relative "../../adapters/driven/heki"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control migrate_ledger_from_heki`: copies each aggregate's
+    # current state from a Heki data directory into the repository that the domain's
+    # `.hecksagon`/`.world` files bind today (for example `PostgresEra`). It is domain-agnostic.
+    #
+    #   migrate_ledger_from_heki <domain_dir> <heki_data_dir> [aggregate_name ...]         # dry run
+    #   migrate_ledger_from_heki <domain_dir> <heki_data_dir> [aggregate_name ...] --force # apply
+    #
+    # One `save` per id from `Heki#all`, not a journal replay: state is kept byte-for-byte, the
+    # per-append history is not. The Heki side is only read. An id the destination holds under a
+    # different state is always refused, so a second run is idempotent. Only aggregates with a
+    # `<storage_name>.heki` file in the Heki directory are considered; trailing names (`hecks_name`
+    # or `storage_name`) narrow further.
+    class QaPostgresMigrate
+      USAGE = "usage: hecks quality_control migrate_ledger_from_heki <domain_dir> <heki_data_dir> " \
+              "[aggregate_name ...] [--force]"
+
+      # Migrates, or reports what a migration would do.
+      #
+      # @param argv [Array<String>] the domain directory, the Heki directory, aggregate names, and
+      #   `--force` to apply
+      # @param out [IO] where the report goes
+      # @param err [IO] where a refusal goes
+      # @return [Integer] 0 when nothing conflicts, 1 for a usage error or a conflict
+      def self.call(argv, out: $stdout, err: $stderr)
+        new(out: out, err: err).call(argv)
+      end
+
+      # @param out [IO] where the report goes
+      # @param err [IO] where a refusal goes
+      def initialize(out: $stdout, err: $stderr)
+        @out = out
+        @err = err
+      end
+
+      # @param argv [Array<String>] the domain directory, the Heki directory, aggregate names, and
+      #   `--force` to apply
+      # @return [Integer] 0 when nothing conflicts, 1 for a usage error or a conflict
+      def call(argv)
+        argv = argv.dup
+        force = argv.delete("--force")
+        domain_dir = argv.shift
+        return usage("no domain directory given") if domain_dir.nil?
+        return usage("no such domain directory #{domain_dir.inspect}") unless Dir.exist?(domain_dir)
+
+        heki_dir = argv.shift
+        return usage("no Heki data directory given") if heki_dir.nil?
+        return usage("no such Heki data directory #{heki_dir.inspect}") unless Dir.exist?(heki_dir)
+
+        heki_dir = File.expand_path(heki_dir)
+        registry = Hecks.boot(domain_dir).registry
+        candidates = candidates_in(registry, heki_dir, argv)
+        if candidates.empty?
+          @out.puts "hecks quality_control migrate_ledger_from_heki: no aggregate matched " \
+                    "#{argv.empty? ? '(any)' : argv.inspect} with a " \
+                    "corresponding .heki file under #{heki_dir}"
+          return 0
+        end
+
+        migrated, skipped, conflicts = copy(candidates, registry, heki_dir, force)
+        report(force, migrated, skipped, conflicts)
+        conflicts.empty? ? 0 : 1
+      end
+
+      # Deep comparison independent of key type and hash order; only array order is meaningful.
+      # `spec/qa_postgres_migration_spec.rb` pins this for conflict detection.
+      #
+      # @param value [Object] a state, or any part of one
+      # @return [Object] the same with every hash keyed by string and sorted
+      def self.canonical(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(k, v), h| h[k.to_s] = canonical(v) }.sort.to_h
+        when Array
+          value.map { |v| canonical(v) }
+        else
+          value
+        end
+      end
+
+      private
+
+      def usage(message)
+        @err.puts "hecks quality_control migrate_ledger_from_heki: #{message}"
+        @err.puts USAGE
+        1
+      end
+
+      # A candidate is an aggregate whose own `.heki` file exists, whatever it is bound to now.
+      def candidates_in(registry, heki_dir, wanted)
+        registry.bluebooks.each_with_object([]) do |(domain_name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            next unless wanted.empty? || wanted.include?(aggregate.hecks_name) || wanted.include?(aggregate.storage_name)
+
+            heki_path = File.join(heki_dir, "#{aggregate.storage_name}.heki")
+            next unless File.exist?(heki_path)
+
+            all << { domain_name: domain_name, aggregate: aggregate, heki_path: heki_path }
+          end
+        end
+      end
+
+      def copy(candidates, registry, heki_dir, force)
+        migrated = []
+        skipped = []
+        conflicts = []
+        candidates.each do |candidate|
+          aggregate = candidate[:aggregate]
+          # Guarded like a factory-built repository so a Heki store decodes through the state codec.
+          source = Hecks::Ports::Persistence::CodecBoundary.guard!(
+            Hecks::Adapters::Heki.new(aggregate: aggregate, settings: { dir: heki_dir }, root: nil)
+          )
+          dest = registry.repository(candidate[:domain_name], aggregate)
+          source.all.each do |instance|
+            name = "#{aggregate.storage_name}/#{instance.id}"
+            existing = dest.find(instance.id)
+            if existing.nil?
+              dest.save(instance) if force
+              migrated << name
+            elsif self.class.canonical(existing.state) == self.class.canonical(instance.state)
+              skipped << name
+            else
+              conflicts << name
+            end
+          end
+        end
+        [migrated, skipped, conflicts]
+      end
+
+      def report(force, migrated, skipped, conflicts)
+        label = force ? "MIGRATED" : "WOULD MIGRATE"
+        migrated.each { |id| @out.puts "#{label} #{id}" }
+        skipped.each { |id| @out.puts "SKIP #{id}: destination already holds the identical state" }
+        conflicts.each do |id|
+          @err.puts "REFUSED #{id}: the destination already holds a DIFFERENT state for this id — " \
+                    "not overwritten, --force or not. Resolve by hand (compare the two states, decide " \
+                    "which is authoritative) before migrating this id again."
+        end
+        @out.puts "" unless migrated.empty? && skipped.empty? && conflicts.empty?
+        @out.puts "#{force ? 'migrated' : 'would migrate'} #{migrated.size}, skipped #{skipped.size} " \
+                  "(already caught up), refused #{conflicts.size} (conflicting data)"
+        @out.puts "re-run with --force to apply" unless force || migrated.empty?
+      end
+    end
+  end
+end