hecks 2.9.0 → 3.0.0

data/lib/hecks/quality_control/adapters/sweep_tools.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "qa_tool"
+
+module Hecks
+  module Adapters
+    # The `SweepTools` port's adapter: answers `Sweep`'s queries by running the QA commands that
+    # work a whole pass: a tick, a sweep, the Heki migration, the ledger's role and a concurrency
+    # racer. A run that finds something ends with status 2, which is an answer; anything else the
+    # command calls an error is refused with its report.
+    class SweepTools < QaTool
+      # @return [Hash] `text:` one tick's report
+      def tick
+        run_command("qa_tick", answers: [0, 2])
+      end
+
+      # @param target [Hash, String, nil] the target to sweep; the rotation's pick when absent
+      # @param arguments [Hash, String, nil] the sweep's own flags, such as `--all --seeds 5`
+      # @return [Hash] `text:` the sweep's report
+      def run(target: nil, arguments: nil)
+        run_command("qa_sweep", *plain(target), *words(arguments), answers: [0, 2])
+      end
+
+      # @param domain [Hash, String] the domain directory whose bindings are the destination
+      # @param data [Hash, String] the Heki data directory read from
+      # @param arguments [Hash, String, nil] aggregate names, and `--force` to apply
+      # @return [Hash] `text:` what was, or would be, migrated
+      def migrate_ledger_from_heki(domain:, data:, arguments: nil)
+        run_command("qa_postgres_migrate", plain(domain), plain(data), *words(arguments))
+      end
+
+      # @param database [Hash, String] the database the role is made to own
+      # @param role [Hash, String, nil] the role's name; `hecks_qa` when absent
+      # @return [Hash] `text:` what was done, and what already held
+      def create_ledger_role(database:, role: nil)
+        run_command("qa_postgres_role", plain(database), *(role ? ["--role", plain(role)] : []))
+      end
+
+      # @param domain [Hash, String] the domain directory
+      # @param database [Hash, String] the scratch database
+      # @param schema [Hash, String] the schema this racer dispatches into
+      # @param verb [Hash, String] the command to dispatch
+      # @param step_arguments [Hash, String] the command's arguments, as JSON
+      # @return [Hash] `text:` `succeeded`, `refused` or `crashed:<class>: <message>`
+      def race(domain:, database:, schema:, verb:, step_arguments:)
+        run_command("qa_concurrency_racer", plain(domain), plain(database), plain(schema), plain(verb),
+                    plain(step_arguments))
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/target_tools.adapter

@@ -0,0 +1,7 @@
+# Binds the `TargetTools` port to `TargetTools`, which answers `Target`'s queries: the seed, generated domains, the miner, the novelty gate and the scan.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/target_tools"
+
+Hecks.adapter "TargetTools" do
+  port "TargetTools"
+end

data/lib/hecks/quality_control/adapters/target_tools.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "qa_tool"
+
+module Hecks
+  module Adapters
+    # The `TargetTools` port's adapter: answers `Target`'s queries by running the QA commands that
+    # enrol, generate and judge chapters: the seed, the generated-domain check, the combination
+    # miner, the novelty gate and the external-domain scan. A finding or a judgment is an answer;
+    # anything else the command calls an error is refused with its report.
+    class TargetTools < QaTool
+      # @return [Hash] `text:` each corpus domain's outcome: identified, or already on file
+      def seed
+        run_command("qa_seed_targets")
+      end
+
+      # @param arguments [Hash, String, nil] the command's own flags, such as `--domains 3 --rust`
+      # @return [Hash] `text:` the report of the generated domains' check
+      def check_generated_domains(arguments: nil)
+        run_command("qa_generated_domains", *words(arguments), answers: [0, 2])
+      end
+
+      # @param arguments [Hash, String, nil] the command's own flags, such as `--brief`
+      # @return [Hash] `text:` the miner's report
+      def mine_combinations(arguments: nil)
+        run_command("qa_mine_combinations", *words(arguments), answers: [0, 1])
+      end
+
+      # @param domain [Hash, String] the candidate stress domain's path
+      # @param arguments [Hash, String, nil] `--against` and the paths to compare with
+      # @return [Hash] `text:` the new form pairs it earns its place with, or that it earns none
+      def judge_novelty(domain:, arguments: nil)
+        run_command("qa_domain_novelty", plain(domain), *words(arguments), answers: [0, 1])
+      end
+
+      # @param arguments [Hash, String, nil] the command's own flags, such as `--max-depth 4`
+      # @return [Hash] `text:` the sibling domains that depend on hecks and are not enrolled
+      def discover_external_domains(arguments: nil)
+        run_command("qa_discover_external_domains", *words(arguments))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    # How one QA command starts another as its own OS process, from `lib/` rather than through a
+    # launcher script: a sweep spawns racers and generated-domain checks, and a launcher query runs
+    # any of them. A fresh process is the point: its own boot, its own Postgres connections, and a
+    # crash that ends only itself.
+    module Child
+      # Each command's class, and how it is called: `:argv_root` is `call(ARGV, root:)`, `:argv` is
+      # `call(ARGV)` and `:root` is `call(root:)`. A command lives in
+      # `hecks/quality_control/cli/<command>`.
+      COMMANDS = {
+        "qa_tick"                      => ["QaTick", :argv_root],
+        "qa_sweep"                     => ["QaSweep", :argv_root],
+        "qa_pr_check"                  => ["QaPrCheck", :argv_root],
+        "qa_generated_domains"         => ["QaGeneratedDomains", :argv_root],
+        "qa_mine_combinations"         => ["QaMineCombinations", :argv_root],
+        "qa_domain_novelty"            => ["QaDomainNovelty", :argv_root],
+        "qa_discover_external_domains" => ["QaDiscoverExternalDomains", :argv_root],
+        "qa_concurrency_racer"         => ["QaConcurrencyRacer", :argv_root],
+        "qa_postgres_migrate"          => ["QaPostgresMigrate", :argv],
+        "qa_postgres_role"             => ["QaPostgresRole", :argv],
+        "qa_seed_angles"               => ["QaSeedAngles", :root],
+        "qa_seed_targets"              => ["QaSeedTargets", :root]
+      }.freeze
+
+      module_function
+
+      # @param root [String] the checkout whose `lib/` holds the command and where it runs
+      # @param command [String] a key of `COMMANDS`
+      # @param args [Array<String>] the command's own arguments
+      # @return [Array<String>] the argv that runs it under Bundler, ready for `Process.spawn`
+      #   or `Open3` with `chdir: root`
+      # @raise [KeyError] when the command is not one of `COMMANDS`
+      def argv(root, command, *args)
+        klass, style = COMMANDS.fetch(command)
+        call = { argv_root: "ARGV, root: #{root.inspect}", argv: "ARGV", root: "root: #{root.inspect}" }.fetch(style)
+        code = "require #{"hecks/quality_control/cli/#{command}".inspect}; " \
+               "exit(Hecks::QualityControlCli::#{klass}.call(#{call}))"
+        ["bundle", "exec", "ruby", "-I", File.join(root, "lib"), "-e", code, "--", *args]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../../hecks"
+require_relative "../../ports/persistence/plugins/era"
+require_relative "../../fuzzing/concurrent_dispatch"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control race`: one racer of
+    # `Hecks::Fuzzing::ConcurrentDispatch`, run as its own OS process.
+    #
+    # It is spawned, not forked: the caller (`hecks quality_control ask run`) holds live
+    # `PostgresEra` connections, and fork duplicates their file descriptors and SSL state,
+    # corrupting them when a child exits.
+    #
+    #   hecks quality_control race <domain-path> <database> <schema> <verb> <args-json>
+    #
+    # It prints one line, `succeeded`, `refused` or `crashed:<class>: <message>`, and always exits
+    # 0.
+    class QaConcurrencyRacer
+      USAGE = "usage: hecks quality_control race <domain-path> <database> <schema> <verb> <args-json>"
+
+      # Dispatches the one step and prints how it went.
+      #
+      # @param argv [Array<String>] the domain path, database, schema, verb and args JSON
+      # @param root [String] unused; a racer needs no checkout of its own
+      # @param out [IO] where the outcome goes
+      # @return [Integer] 0 always
+      # @raise [SystemExit] with the usage line when an argument is missing
+      def self.call(argv, root: nil, out: $stdout)
+        domain_path, database, schema, verb, args_json = argv
+        abort USAGE unless domain_path && database && schema && verb && args_json
+
+        step = { "verb" => verb, "args" => JSON.parse(args_json) }
+        outcome = Hecks::Fuzzing::ConcurrentDispatch.boot_preserving_schema(domain_path, database: database,
+                                                                                         schema:   schema) do |copy|
+          Hecks::Fuzzing::ConcurrentDispatch.dispatch_one(Hecks.boot(copy), step)
+        end
+        out.puts outcome
+        0
+      end
+    end
+  end
+end

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

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control discover_external_domains`: reports sibling-repo
+    # bluebook domains under `--projects-dir` that already depend on the hecks gem but are not
+    # enrolled yet. It never enrolls anything itself.
+    #
+    #   hecks quality_control discover_external_domains
+    #   hecks quality_control discover_external_domains --projects-dir ~/Projects
+    #   hecks quality_control discover_external_domains --max-depth 4
+    #   hecks quality_control discover_external_domains --known-path <path> ...   # bypass the
+    # ledger read
+    class QaDiscoverExternalDomains
+      USAGE = "usage: hecks quality_control discover_external_domains [--projects-dir <path>] " \
+              "[--max-depth N] [--known-path <path> ...]"
+
+      DEFAULT_PROJECTS_DIR = File.expand_path("~/Projects").freeze
+      DEFAULT_MAX_DEPTH = 3
+
+      # Skipped everywhere in a sibling repo: VCS internals, vendored dependency trees, and this
+      # repo's own worktree scratch space.
+      SKIP_DIR_BASENAMES = %w[.git .hg .svn vendor node_modules .bundle tmp log coverage .yardoc .ruby-lsp
+                              .parked bower_components .claude dist build].freeze
+
+      # Word-boundary matched so "hecksagain" (a real, separate gem) and "hecks_site" never
+      # false-positive as a hecks dependency.
+      GEMFILE_PATTERN = /gem\s*\(?\s*["']hecks["']/
+      GEMFILE_LOCK_PATTERN = /^\s+hecks\s+\(/
+
+      # Raised for a wrong command line or an unreadable ledger; it ends the run with status 1.
+      class Refused < StandardError
+        # @return [Boolean] whether the usage line follows the message
+        attr_reader :usage
+
+        # @param message [String] why the run stopped
+        # @param usage [Boolean] whether the usage line follows the message
+        def initialize(message, usage: true)
+          super(message)
+          @usage = usage
+        end
+      end
+
+      # Reports the candidates.
+      #
+      # @param argv [Array<String>] `--projects-dir`, `--max-depth` and `--known-path`
+      # @param root [String] the repository root
+      # @return [Integer] 0 once reported, 1 for a usage error or an unreadable ledger
+      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>] `--projects-dir`, `--max-depth` and `--known-path`
+      # @return [Integer] the exit status
+      def call(argv)
+        options = parse(argv.dup)
+        return 0 if options == :help
+
+        candidates, skipped, siblings = discover(options)
+        report(options, candidates, skipped, siblings)
+        0
+      rescue Refused => e
+        warn e.message
+        warn USAGE if e.usage
+        1
+      end
+
+      private
+
+      def parse(argv)
+        options = { projects_dir: DEFAULT_PROJECTS_DIR, max_depth: DEFAULT_MAX_DEPTH, known_paths: nil }
+        until argv.empty?
+          case (arg = argv.shift)
+          when "-h", "--help"
+            puts USAGE
+            return :help
+          when "--projects-dir"
+            refuse!("--projects-dir needs a path") if argv.empty?
+            options[:projects_dir] = File.expand_path(argv.shift)
+          when "--max-depth"
+            refuse!("--max-depth needs a number") if argv.empty?
+            options[:max_depth] = Integer(argv.shift)
+          when "--known-path"
+            refuse!("--known-path needs a path") if argv.empty?
+            (options[:known_paths] ||= []) << File.expand_path(argv.shift)
+          else
+            refuse!("unexpected argument #{arg.inspect}")
+          end
+        end
+        refuse!("--max-depth must be >= 0") if options[:max_depth].negative?
+        refuse!("#{options[:projects_dir]} is not a directory") unless File.directory?(options[:projects_dir])
+        options
+      end
+
+      def refuse!(message)
+        raise Refused, message
+      end
+
+      def depends_on_hecks?(dir)
+        gemfile = File.join(dir, "Gemfile")
+        lockfile = File.join(dir, "Gemfile.lock")
+
+        (File.file?(gemfile) && File.read(gemfile).match?(GEMFILE_PATTERN)) ||
+          (File.file?(lockfile) && File.read(lockfile).match?(GEMFILE_LOCK_PATTERN))
+      end
+
+      # A monorepo's real hecks-dependent Ruby app can live below the sibling repo's own top level
+      # (a nested `Gemfile` there, not one at `repo_root`). Checked against the candidate's own
+      # directory first, then each ancestor up to and including `repo_root`, so the common case, the
+      # dependency declared at `repo_root` itself, still answers exactly as it always has.
+      def depends_on_hecks_anywhere_above?(entity_dir, repo_root)
+        root = File.expand_path(repo_root)
+        dir = File.expand_path(entity_dir)
+        loop do
+          return true if depends_on_hecks?(dir)
+          return false if dir == root
+
+          parent = File.dirname(dir)
+          return false if parent == dir # filesystem root reached without finding repo_root
+
+          dir = parent
+        end
+      end
+
+      # `repo_root` itself is depth 0, so a project that is one domain at its own top can be a
+      # candidate too.
+      def bluebook_shaped_dirs(repo_root, max_depth)
+        found = []
+        walk = lambda do |dir, depth|
+          entity_name = File.basename(dir)
+          found << [dir, entity_name] if File.file?(File.join(dir, "bluebook", "#{entity_name}.bluebook"))
+          return if depth >= max_depth
+
+          children_of(dir).each do |child|
+            next if SKIP_DIR_BASENAMES.include?(child)
+
+            child_path = File.join(dir, child)
+            next unless File.directory?(child_path) && !File.symlink?(child_path)
+            next if child == "bluebook" # the bluebook/ directory itself is never an entity dir
+
+            walk.call(child_path, depth + 1)
+          end
+        end
+        walk.call(repo_root, 0)
+        found
+      end
+
+      def children_of(dir)
+        Dir.children(dir).sort
+      rescue Errno::EACCES, Errno::ENOENT
+        []
+      end
+
+      # Shells out rather than booting the ledger in-process, so this is safe to run alongside a
+      # live qa_tick or qa_sweep.
+      def ledger_target_paths
+        out, err, status = Open3.capture3("bundle", "exec", "ruby", File.join(@root, "exe/hecks"),
+                                          "run", "qa/bluebook", "ask", "target.all", chdir: @root)
+        unless status.success?
+          raise Refused, "hecks quality_control discover_external_domains: could not read the ledger's targets " \
+                         "(hecks run qa/bluebook ask target.all exited #{status.exitstatus}):\n#{err}\n" \
+                         "pass --known-path <path> ... to run without the ledger", usage: false
+        end
+
+        JSON.parse(out).filter_map { |row| row.dig("path", "value") }
+      end
+
+      def sibling_repos(projects_dir)
+        hecks_root = begin
+          File.realpath(@root)
+        rescue Errno::ENOENT
+          @root
+        end
+        Dir.children(projects_dir).sort.filter_map do |child|
+          next if child == "hecks" # this repo, already fully covered by existing seeding
+
+          path = File.join(projects_dir, child)
+          next unless File.directory?(path) && !File.symlink?(path)
+
+          begin
+            next if File.realpath(path) == hecks_root
+          rescue Errno::ENOENT
+            next
+          end
+
+          path
+        end
+      end
+
+      # @return [Array(Array<Hash>, Array<String>, Array<String>)] the candidates, the siblings
+      #   with no hecks dependency, and every sibling scanned
+      def discover(options)
+        known_raw = options[:known_paths] || ledger_target_paths
+        # Ledger paths may be stored root-relative or absolute; normalize both to compare.
+        known = known_raw.to_set { |path| path.start_with?("/") ? File.expand_path(path) : File.expand_path(path, @root) }
+        siblings = sibling_repos(options[:projects_dir])
+        candidates = []
+        skipped = []
+        siblings.each do |repo_path|
+          found = false
+          bluebook_shaped_dirs(repo_path, options[:max_depth]).each do |entity_dir, entity_name|
+            next unless depends_on_hecks_anywhere_above?(entity_dir, repo_path)
+
+            found = true
+            absolute = File.expand_path(entity_dir)
+            next if known.include?(absolute)
+
+            repo_name = File.basename(repo_path)
+            candidates << { repo: repo_name, reference: "#{repo_name}/#{entity_name}", path: absolute }
+          end
+          skipped << repo_path unless found
+        end
+        [candidates.sort_by { |c| [c[:repo], c[:reference]] }, skipped, siblings]
+      end
+
+      def report(options, candidates, skipped, siblings)
+        puts "scanned #{siblings.size} sibling(s) under #{options[:projects_dir]} " \
+             "(max depth #{options[:max_depth]}), #{siblings.size - skipped.size} depend on the hecks gem"
+        puts "no hecks dependency, skipped: #{skipped.map { |p| File.basename(p) }.join(', ')}" unless skipped.empty?
+        puts
+        if candidates.empty?
+          puts "no new candidates — every hecks-dependent sibling's bluebook-shaped domain is either " \
+               "already a Target or none was found in the shape <name>/bluebook/<name>.bluebook within " \
+               "--max-depth #{options[:max_depth]}."
+          return
+        end
+
+        puts "#{candidates.size} candidate(s) — report only, nothing identified. Review each, then run " \
+             "the command yourself to enroll it:"
+        puts
+        candidates.each do |c|
+          puts "  #{c[:reference]}"
+          puts "    path: #{c[:path]}"
+          puts "    enroll: hecks run qa/bluebook identify reference=#{c[:reference]} path=#{c[:path]}"
+          puts
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require_relative "../../../hecks"
+require_relative "../../fuzzing/form_census"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control judge_novelty`: does a new stress domain earn its
+    # place? It is the gate before a domain becomes a `Target`.
+    #
+    #   hecks quality_control judge_novelty <domain-path> [--against <path> ...]
+    #
+    # A domain is new when it puts two forms together on one aggregate that no existing target does
+    # (`Hecks::Fuzzing::FormCensus`). It is compared against the ledger's `Target.path` rows unless
+    # `--against` names others. "Nothing new" can also mean the domain's form is not yet named in
+    # `FormCensus::FORMS`.
+    #
+    # Exit codes: 0 new pair found; 1 no new pair; 2 usage or wrong path shape.
+    class QaDomainNovelty
+      EXIT_NOVEL = 0
+      EXIT_NOTHING = 1
+      EXIT_USAGE = 2
+
+      USAGE = "usage: hecks quality_control judge_novelty <domain-path> [--against <path> ...]"
+
+      # Judges the candidate.
+      #
+      # @param argv [Array<String>] the candidate's path, then optionally `--against` and paths
+      # @param root [String] the repository root
+      # @return [Integer] 0 when the candidate earns its place, 1 when it does not, 2 for a usage
+      #   error
+      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 candidate's path, then optionally `--against` and paths
+      # @return [Integer] the exit status
+      def call(argv)
+        candidate, against = parse(argv)
+        refuse_unless_stress_domain_shaped!(normalize(candidate))
+        existing_source = against.empty? ? "the ledger's Target.path rows" : "--against"
+        existing = (against.empty? ? ledger_target_paths : against).map { |path| normalize(path) }.uniq
+        own = existing.select { |path| path == normalize(candidate) }
+        existing -= own
+        puts "note: #{candidate} is already a target — left out of the comparison" unless own.empty?
+
+        missing, present = existing.partition { |path| Hecks::Fuzzing::FormCensus.bluebook_files(path).nil? }
+        missing.each { |path| warn "skipping #{path}: no bluebook/*.bluebook on disk" }
+        judge(candidate, present, existing_source)
+      rescue UsageError => e
+        warn e.message
+        warn USAGE
+        EXIT_USAGE
+      rescue Stopped
+        EXIT_USAGE
+      end
+
+      private
+
+      # Raised for a wrong command line or path shape; it ends the run with `EXIT_USAGE`.
+      class UsageError < StandardError; end
+
+      # Raised once the reason has been printed; it ends the run with `EXIT_USAGE`.
+      class Stopped < StandardError; end
+
+      def parse(argv)
+        candidate = nil
+        against = []
+        mode = :candidate
+        argv.each do |arg|
+          if arg == "--against"
+            mode = :against
+          elsif mode == :against
+            against << arg
+          elsif candidate.nil?
+            candidate = arg
+          else
+            raise UsageError, "unexpected argument #{arg.inspect}"
+          end
+        end
+        raise UsageError, "no candidate domain given" if candidate.nil?
+        raise UsageError, "--against needs at least one path" if mode == :against && against.empty?
+
+        [candidate, against]
+      end
+
+      # `hecks project_rust` reads exactly `<name>/bluebook/<name>.bluebook`, so refuse anything
+      # else early.
+      def refuse_unless_stress_domain_shaped!(path)
+        expected = File.join(path, "bluebook", "#{File.basename(path)}.bluebook")
+        return if File.file?(expected)
+
+        raise UsageError, "#{path} is not shaped like a stress domain: expected #{expected} to exist " \
+                          "(`<name>/bluebook/<name>.bluebook` — a flat file breaks `hecks project_rust`; " \
+                          "see qa/stress_domains/ledger_ordering/NOTES.md)"
+      end
+
+      # The ledger's target paths via one read-only `ask`; never boots the ledger in this process.
+      def ledger_target_paths
+        out, err, status = Open3.capture3("bundle", "exec", "ruby", File.join(@root, "exe/hecks"),
+                                          "run", "qa/bluebook", "ask", "target.all", chdir: @root)
+        unless status.success?
+          warn "hecks quality_control judge_novelty: could not read the ledger's targets (hecks run qa/bluebook ask " \
+               "target.all exited #{status.exitstatus}):\n#{err}"
+          warn "pass --against <path> ... to run without the ledger"
+          raise Stopped
+        end
+
+        JSON.parse(out).map { |row| row.dig("path", "value") }.compact
+      end
+
+      def normalize(path) = File.expand_path(path, @root)
+
+      def judge(candidate, present, existing_source)
+        census = Hecks::Fuzzing::FormCensus.census(normalize(candidate))
+        candidate_pairs = Hecks::Fuzzing::FormCensus.covered_pairs(census)
+        existing_pairs = present.each_with_object(Hash.new { |h, k| h[k] = [] }) do |path, covered|
+          Hecks::Fuzzing::FormCensus.covered_pairs(Hecks::Fuzzing::FormCensus.census(path)).each do |pair, names|
+            covered[pair].concat(names.map { |name| "#{name} (#{path.delete_prefix("#{@root}/")})" })
+          end
+        end
+        new_pairs = candidate_pairs.reject { |pair, _| existing_pairs.key?(pair) }
+
+        puts "candidate: #{candidate} — #{census.size} aggregate(s), #{candidate_pairs.size} form pair(s) met"
+        puts "against:   #{present.size} domain(s) from #{existing_source}, " \
+             "#{existing_pairs.size} form pair(s) met between them"
+        puts
+        return nothing_new(candidate) if new_pairs.empty?
+
+        width = new_pairs.keys.map(&:size).max
+        puts "new pair(s) — met on one aggregate here, on none of the existing targets:"
+        new_pairs.sort.each { |pair, names| puts "  #{pair.ljust(width)}  #{names.uniq.join(', ')}" }
+        puts
+        puts "#{new_pairs.size} new pair(s) — #{candidate} earns its place."
+        EXIT_NOVEL
+      end
+
+      def nothing_new(candidate)
+        puts "no new pair — every pair of forms #{candidate} puts together on one aggregate is already met " \
+             "by an existing target. Either the domain is not new, or the form it exists for is not yet " \
+             "named in Hecks::Fuzzing::FormCensus::FORMS (lib/hecks/fuzzing/form_census.rb) — name it " \
+             "there first, citing the gap it is one step from, and run this again."
+        puts
+        puts "READ THAT AS A QUESTION ABOUT THE CENSUS, NOT A VERDICT ON THE DOMAIN. This gate measures " \
+             "ONE AGGREGATE's own declared forms, so a domain whose point is a chapter-level construct — " \
+             "a policy, an `across` target, a process manager, a read model's own group_by/median, an " \
+             "outbox, a dry run — is invisible to it by construction, not by omission. `corrects` and " \
+             "`role_gated` were exactly that: declared all over the corpus, unnamed here, so this line " \
+             "told three stress domains built around retroactive correction that they were redundant " \
+             "(their own NOTES.md each say so). If that is your domain's case, say which construct it " \
+             "exists for in its NOTES.md and keep it."
+        EXIT_NOTHING
+      end
+    end
+  end
+end