hecks 5.0.0 → 7.0.0

data/lib/hecks/{cli → tools}/follow.rb

@@ -5,7 +5,7 @@ require "optparse"
 require_relative "../../hecks"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks follow`: live-tails a domain's persisted event log as JSON lines.
     #
     # Events are one table per domain, so this polls the first repository that answers `:events`
@@ -49,8 +49,8 @@ module Hecks
       # @return [Object] the first repository that answers `:events`
       # @raise [SystemExit] when none does
       def event_repository(runtime, domain_name, program)
-        repositories = runtime.registry.bluebooks.flat_map do |bluebook_domain, bluebook|
-          bluebook.aggregates.map { |aggregate| runtime.registry.repository(bluebook_domain, aggregate) }
+        repositories = runtime.bluebooks.flat_map do |bluebook_domain, bluebook|
+          bluebook.aggregates.map { |aggregate| runtime.repository(bluebook_domain, aggregate) }
         end
         repositories.find { |repo| repo.respond_to?(:events) } or
           abort "#{program}: no adapter in #{domain_name} persists an event log"
@@ -63,7 +63,7 @@ module Hecks
       # @param filter [String, nil] the aggregate name asked for
       # @return [Boolean]
       def matches?(event, filter)
-        filter.nil? || event.aggregate.to_s.split("::").last.casecmp?(filter) || event.aggregate == filter
+        filter.nil? || Naming.demodulise(event.aggregate).casecmp?(filter) || event.aggregate == filter
       end
 
       # @param repository [Object] answers `events`

data/lib/hecks/tools/fuzz_sweep/findings.rb

@@ -8,7 +8,8 @@ module Hecks
       # Replays a generated sequence and judges, groups and shrinks what it finds.
       module Findings
         # An exception escaping Replay's per-step isolation is an interpreter defect, not a domain
-        # refusal.
+        # refusal. A sweep on SQLite or Postgres also checks that adapter's projection answers
+        # each rooted read model as the in-process loop does (ADR 0122).
         #
         # @param domain [String] the domain directory
         # @param steps [Array<Hash>] the sequence to replay
@@ -17,7 +18,7 @@ module Hecks
         #   `:crash`) and its message
         def outcome(domain, steps, adapter = :memory)
           history = Hecks::Fuzzing::Replay.call(domain, steps, adapter: adapter)
-          violations = Hecks::Fuzzing::Properties.check(history).reject { |_, result| result == true }
+          violations = property_results(domain, steps, adapter, history).reject { |_, result| result == true }
           return [:clean, nil] if violations.empty?
 
           [:property_violation, violations.map { |name, message| "#{name}: #{message}" }.join("; ")]
@@ -25,6 +26,21 @@ module Hecks
           [:crash, "#{e.class}: #{e.message}"]
         end
 
+        # The standard battery's results, and the projection agreement's when `adapter` has one.
+        #
+        # @param domain [String] the domain directory
+        # @param steps [Array<Hash>] the sequence replayed
+        # @param adapter [Symbol] the persistence it was replayed on
+        # @param history [Hash] the replayed history
+        # @return [Hash{Symbol => true, String}] each property name mapped to its result
+        def property_results(domain, steps, adapter, history)
+          results = Hecks::Fuzzing::Properties.check(history)
+          agreement = Hecks::Fuzzing::ProjectionAgreement
+          return results unless agreement.checks?(adapter)
+
+          results.merge(agreement::PROPERTY => agreement.property(domain, steps, adapter))
+        end
+
         # Groups findings by property name or exception class, stable across shrink candidates.
         #
         # @param message [String, nil] a finding's message

data/lib/hecks/tools/fuzz_sweep/options.rb

@@ -9,32 +9,71 @@ module Hecks
       # The command line of a sweep: its options, and what the chosen adapter needs.
       module Options
         # The options that take a whole number, and the key each fills.
-        INTEGER_OPTIONS = { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers }.freeze
+        INTEGER_OPTIONS = { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers,
+                            "--list-shards" => :list_shards }.freeze
 
         # The most children a Postgres sweep runs at once unless `--workers` says otherwise.
         POSTGRES_WORKERS = 4
 
         # @param args [Array<String>] the command line, consumed
-        # @return [Hash, nil] `seeds`, `steps`, `workers`, `adapter`, `persist` and `domain`; nil
-        #   after a refusal
+        # @return [Hash, nil] `seeds`, `steps`, `workers`, `adapter`, `persist`, `domain`, `shard`
+        #   (the shard's number and the shard count) and `list_shards` (how many shards to list);
+        #   nil after a refusal
         def parse(args)
-          options = { seeds: 20, steps: 30, workers: nil, adapter: :memory, domain: nil, persist: false }
+          options = { seeds: 20, steps: 30, workers: nil, adapter: :memory, domain: nil, persist: false,
+                      shard: nil, list_shards: nil }
           until args.empty?
             apply_option(options, args.shift, args)
             return nil unless adapter_known?(options[:adapter])
           end
-          options
+          settle_shards(options)
         end
 
         # Records one command-line word in `options`, taking its value from `rest` when it has one.
         def apply_option(options, arg, rest)
           if (key = INTEGER_OPTIONS[arg]) then options[key] = Integer(rest.shift)
           elsif arg == "--persist-regressions" then options[:persist] = true
-          elsif arg == "--adapter" then options[:adapter] = rest.shift.to_s.downcase.to_sym
+          elsif arg == "--adapter" then options[:adapter] = adapter_name(rest.shift)
+          elsif arg == "--shard" then options[:shard] = rest.shift.to_s
           else options[:domain] = arg
           end
         end
 
+        # Turns `--shard I/N` into the pair it names, and refuses the shard options that do not fit
+        # together or with what they split.
+        #
+        # @param options [Hash] the options as typed
+        # @return [Hash, nil] the options with `shard` parsed, or nil after a refusal
+        def settle_shards(options)
+          return options if options.values_at(:shard, :list_shards).none?
+          return nil unless shard_choice_clear?(options)
+
+          options[:shard] &&= Shards.parse_shard(options[:shard])
+          options.values_at(:shard, :list_shards).any? ? options : nil
+        end
+
+        # @return [Boolean] whether the shard options name one split of the corpus; warns why not
+        def shard_choice_clear?(options)
+          reason = shard_conflict(options)
+          warn reason if reason
+          reason.nil?
+        end
+
+        # @return [String, nil] why the shard options cannot be used together, or nil when they can
+        def shard_conflict(options)
+          if options[:shard] && options[:list_shards]
+            "--shard sweeps one shard and --list-shards lists them all; use one"
+          elsif options[:domain]
+            "shards split every domain of the checkout, so no domain can be named"
+          elsif options[:list_shards] && !options[:list_shards].positive?
+            "--list-shards takes a shard count of 1 or more"
+          end
+        end
+
+        # @param word [String, nil] the word after `--adapter`
+        # @return [Symbol] the adapter it names, lowercased
+        def adapter_name(word) = word.to_s.downcase.to_sym
+
         # @return [Boolean] whether `adapter` is one a sweep can boot on; warns when it is not
         def adapter_known?(adapter)
           return true if ADAPTERS.include?(adapter)

data/lib/hecks/tools/fuzz_sweep/pool.rb

@@ -16,16 +16,27 @@ module Hecks
         # @yieldparam domain [String] a domain directory
         # @yieldreturn [Boolean] whether it was clean
         # @return [Boolean] true if every domain's child exited 0, false if any exited non-zero
-        def fuzz_in_pool(domains, workers, &) # rubocop:disable Naming/PredicateMethod -- the sweep's verdict
+        def fuzz_in_pool(domains, workers, &)
           results = run_children(domains, workers, &)
           slowest = results.max_by(5) { |_, (_, _, seconds)| seconds }
                            .map { |index, (_, _, seconds)| "#{File.basename(domains[index])} #{seconds.round}s" }
           warn "slowest domains: #{slowest.join(", ")}"
+          warn "domain seconds: #{seconds_by_domain(domains, results)}"
           replay_outputs(results).all?
         end
 
         private
 
+        # Every domain's wall seconds, so a cost table can be read off one run's log.
+        #
+        # @return [String] `directory seconds` for each domain, in domain order, the directory
+        #   relative to the working directory when it lies under it
+        def seconds_by_domain(domains, results)
+          results.sort.map do |index, (_, _, seconds)|
+            "#{domains[index].delete_prefix("#{Dir.pwd}/")} #{seconds.round(1)}"
+          end.join(", ")
+        end
+
         # @return [Hash{Integer => Array}] by domain index: whether the child succeeded, its output
         #   file, and its seconds
         def run_children(domains, workers, &)

data/lib/hecks/tools/fuzz_sweep/shards.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module FuzzSweep
+      # Splits the domains of a sweep into `n` shards, so `n` jobs together sweep every domain once.
+      #
+      # The split is a pure function of the domain list, `n` and the committed cost table: no clock,
+      # no discovery order and no run history reach it, so every job computes the same partition.
+      # Domains are dealt, dearest first, to whichever shard holds the least cost so far, which
+      # keeps the shards near one another in cost; a domain the table does not name costs the
+      # table's median, and an absent table costs every domain the same.
+      module Shards
+        # What `--shard` takes: the shard's number, a slash, and how many shards there are.
+        SHARD_WORD = %r{\A([1-9]\d*)/([1-9]\d*)\z}
+
+        # Where the committed cost table is read from, relative to the checkout: one
+        # `directory:seconds` line for each domain, `#` lines being notes.
+        COST_TABLE = "spec/fuzzing/fuzz_runtime_baseline.log"
+
+        # What a domain costs when no table says: every domain alike.
+        FLAT_COST = 1.0
+
+        # A split that left a domain out or put one in two shards.
+        class NotAPartition < StandardError; end
+
+        module_function
+
+        # @param word [String, nil] the word after `--shard`
+        # @return [Array(Integer, Integer), nil] the shard's number and the shard count, or nil when
+        #   the word is not `I/N` with `I` between 1 and `N`; warns what is accepted
+        def parse_shard(word)
+          match = SHARD_WORD.match(word.to_s)
+          return [match[1].to_i, match[2].to_i] if match && match[1].to_i <= match[2].to_i
+
+          warn "unknown --shard #{word.inspect} — use I/N with I from 1 to N, such as 1/2, 2/2 or 3/4"
+          nil
+        end
+
+        # @param domains [Array<String>] the domain directories, each unique
+        # @param shards [Integer] how many shards to split into
+        # @param costs [Hash{String => Float}] each domain directory's cost, perhaps lacking some
+        # @return [Array<Array<String>>] the domains of each shard, each in the order `domains` has
+        def partition(domains, shards, costs = {})
+          price = prices(domains, costs)
+          order = domains.each_index.sort_by { |index| [-price[index], domains[index]] }
+          deal(order, price, shards).map { |indexes| indexes.sort.map { |index| domains[index] } }
+        end
+
+        # @param order [Array<Integer>] the domain positions, in the order to deal them
+        # @param price [Array<Float>] each position's cost
+        # @param shards [Integer] how many shards to deal into
+        # @return [Array<Array<Integer>>] the positions each shard took, each to the lightest shard
+        #   so far, the lowest numbered when they tie
+        def deal(order, price, shards)
+          loads = Array.new(shards, 0.0)
+          order.each_with_object(Array.new(shards) { [] }) do |index, taken|
+            lightest = loads.each_index.min_by { |shard| [loads[shard], shard] }
+            loads[lightest] += price[index]
+            taken[lightest] << index
+          end
+        end
+
+        # @param domains [Array<String>] the domain directories
+        # @param number [Integer] the shard wanted, from 1
+        # @param shards [Integer] how many shards there are
+        # @param costs [Hash{String => Float}] each domain directory's cost
+        # @return [Array<String>] the domains that shard sweeps
+        def select(domains, number, shards, costs = {}) = partition(domains, shards, costs).fetch(number - 1)
+
+        # The assignment as data: one line for each domain, `I/N<TAB>cost<TAB>directory`, shard by
+        # shard. A split that left a domain out or put one in two shards is refused, since a job
+        # that reads this list would then trust a sweep that covers less than it says.
+        #
+        # @param domains [Array<String>] the domain directories
+        # @param shards [Integer] how many shards to split into
+        # @param costs [Hash{String => Float}] each domain directory's cost
+        # @param root [String] the checkout the directories are shown relative to
+        # @return [Array<String>] the lines
+        # @raise [NotAPartition] when the shards are not a partition of `domains`
+        def listing(domains, shards, costs, root)
+          split = partition(domains, shards, costs)
+          raise NotAPartition, "the shards are not a partition of the domains" unless split.flatten.sort == domains.sort
+
+          price = domains.zip(prices(domains, costs)).to_h
+          split.each_with_index.flat_map do |members, index|
+            members.map { |domain| row("#{index + 1}/#{shards}", price[domain], domain.delete_prefix("#{root}/")) }
+          end
+        end
+
+        def row(shard, price, directory) = "#{shard}\t#{price.round(1)}\t#{directory}"
+
+        # Every discoverable domain, or the share of them `--shard I/N` asks for, which a pool
+        # starts dearest first so the longest domain is never the last one left running.
+        #
+        # @param options [Hash] the parsed options: `shard`, perhaps
+        # @param root [String] the checkout
+        # @return [Array<String>] the domain directories this sweep covers
+        def domains_for(options, root)
+          domains = Hecks::Corpus.fuzzable_domains(root)
+          return domains unless options[:shard]
+
+          number, shards = options[:shard]
+          puts "shard #{number}/#{shards}"
+          costs = costs_from(root)
+          dearest_first(select(domains, number, shards, costs), costs)
+        end
+
+        # @param domains [Array<String>] the domain directories
+        # @param costs [Hash{String => Float}] each domain directory's cost
+        # @return [Array<String>] the same domains, dearest first, ties in path order
+        def dearest_first(domains, costs)
+          price = domains.zip(prices(domains, costs)).to_h
+          domains.sort_by { |domain| [-price[domain], domain] }
+        end
+
+        # Prints the listing of every domain of the checkout, and sweeps nothing.
+        #
+        # @param shards [Integer] how many shards to split into
+        # @param root [String] the checkout
+        # @return [Integer] 0 once printed
+        def print_listing(shards, root)
+          puts listing(Hecks::Corpus.fuzzable_domains(root), shards, costs_from(root), root)
+          0
+        end
+
+        # @param root [String] the checkout
+        # @return [Hash{String => Float}] seconds by absolute domain directory, from the committed
+        #   table; empty when the table is absent
+        def costs_from(root)
+          path = File.join(root, COST_TABLE)
+          return {} unless File.file?(path)
+
+          File.readlines(path, chomp: true).reject { |line| line.strip.empty? || line.start_with?("#") }
+              .to_h { |line| line.split(":", 2).then { |dir, seconds| [File.join(root, dir), Float(seconds)] } }
+        end
+
+        # @return [Array<Float>] each domain's cost, a missing one at the table's median
+        def prices(domains, costs)
+          fallback = median(costs.values) || FLAT_COST
+          domains.map { |domain| costs.fetch(domain, fallback) }
+        end
+
+        def median(values)
+          return nil if values.empty?
+
+          ranked = values.sort
+          (ranked[(ranked.size - 1) / 2] + ranked[ranked.size / 2]) / 2.0
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/fuzz_sweep.rb

@@ -8,6 +8,7 @@ require_relative "fuzz_sweep/options"
 require_relative "fuzz_sweep/findings"
 require_relative "fuzz_sweep/reporting"
 require_relative "fuzz_sweep/pool"
+require_relative "fuzz_sweep/shards"
 
 module Hecks
   module Tools
@@ -15,11 +16,13 @@ module Hecks
     # properties, then shrinks each distinct finding and saves it under `tmp/fuzz-failures/`.
     #
     #   hecks fuzz [domain] [--seeds N] [--steps N] [--workers N] [--adapter memory|sqlite|postgres]
-    #               [--persist-regressions]
+    #               [--persist-regressions] [--shard I/N | --list-shards N]
     #
     # The sweep is single-runtime on purpose; the cross-runtime differential is
     # `spec/rust_conformance_fuzz_spec.rb`. Without a domain it sweeps every domain
-    # `Hecks::Corpus.fuzzable_domains` finds, one forked child per core.
+    # `Hecks::Corpus.fuzzable_domains` finds, one forked child per core. `--shard I/N` sweeps only
+    # shard I of N (see `Shards`), so N jobs together sweep every domain once; `--list-shards N`
+    # prints which shard each domain falls in and sweeps nothing.
     module FuzzSweep
       # How many seeds are drawn for each seed that must execute.
       DRAW_LIMIT = 5
@@ -57,13 +60,16 @@ module Hecks
       #   argument is refused
       def main(argv, root: Tools::ROOT)
         require "hecks"
-        require "hecks/fuzzing"
         options = parse(argv.dup)
-        return 1 unless options && adapter_ready?(options)
+        return 1 unless options
+        return Shards.print_listing(options[:list_shards], root) if options[:list_shards]
+
+        require "hecks/fuzzing"
+        return 1 unless adapter_ready?(options)
 
         # Every discoverable domain, so one added anywhere is swept without a list. Paths the sweep
         # cannot boot are routed by Hecks::Corpus::ROUTES to the check that owns them.
-        domains = options[:domain] ? [options[:domain]] : Hecks::Corpus.fuzzable_domains(root)
+        domains = options[:domain] ? [options[:domain]] : Shards.domains_for(options, root)
         ok = sweep(domains, worker_count(options), options, root)
 
         puts(ok ? "CLEAN — no generated sequence broke a property or the interpreter." : "FUZZ FOUND SOMETHING.")
@@ -85,12 +91,12 @@ module Hecks
         fuzz_in_pool(domains, workers) { |domain| fuzz_in_child(options, domain, root) }
       end
 
-      # Runs in a forked child. A Postgres child gets its own scratch schema, so children can fuzz
-      # one database at once.
+      # Runs in a forked child. A Postgres child fuzzes in its own scratch schema, which
+      # `IsolatedBoot.scratch_schema` names by the child's pid, so children can fuzz one database
+      # at once.
       #
       # @return [Boolean] whether the domain was clean
       def fuzz_in_child(options, domain, root)
-        ENV[Hecks::Fuzzing::IsolatedBoot::FUZZ_SCHEMA_ENV] = "hecks_fuzz_#{Process.pid}" if options[:adapter] == :postgres
         fuzz_with(options, domain, root)
       end
 
@@ -177,13 +183,25 @@ module Hecks
       end
 
       # @return [Array(Symbol, String)] the verdict, replaying a clean run once more to see that it
-      #   repeats; and its message
+      #   repeats, and, for a domain that attaches Bulk, once more each way to see that a bulk run
+      #   matches dispatching its rows by hand, and on a SQL store that one statement matches row by
+      #   row (ADR 0129); and its message
       def verdict_for(domain, generated, adapter)
         verdict, message = outcome(domain, generated, adapter)
         return [verdict, message] unless verdict == :clean
 
         determinism = Hecks::Fuzzing::Properties.replay_is_deterministic(domain, generated, adapter: adapter)
-        determinism == true ? [:clean, nil] : [:nondeterminism, determinism]
+        return [:nondeterminism, determinism] unless determinism == true
+
+        parity = Hecks::Fuzzing::Properties.bulk_runs_match_hand_dispatch(domain, generated, adapter: adapter)
+        return [:bulk_parity, parity] unless parity == true
+
+        set_parity(domain, generated, adapter)
+      end
+
+      def set_parity(domain, generated, adapter)
+        parity = Hecks::Fuzzing::Properties.set_transform_matches_row_by_row(domain, generated, adapter: adapter)
+        parity == true ? [:clean, nil] : [:set_transform_parity, parity]
       end
     end
   end

data/lib/hecks/tools/gate.rb

@@ -1,31 +1,64 @@
 # frozen_string_literal: true
 
 require "open3"
-require "yaml"
+require "hecks/vocabulary"
 require_relative "../tools"
+require_relative "stage_progress"
+require_relative "gate_memo/session"
+require_relative "gate_report"
 
 module Hecks
   module Tools
-    # Runs a stage's checks, which `lib/hecks/gate/stages.yml` holds as data, all at once and
-    # reports every one, so a red check does not hide the others.
+    # Runs a stage's checks, which the `GateStage` and `GateCheck` rows of the Vocabulary bluebook
+    # hold as data, all at once and reports every one, so a red check does not hide the others.
     #
     #   hecks gate pre_push                # every check of the stage
     #   hecks gate pre_push only=rubocop   # the named checks
     #   hecks gate --list                  # the stages and their checks
     #
     # A green stage prints which checks passed; a red one prints each failing check's whole output
-    # and what its failure means, and answers status 1.
+    # and what its failure means, and answers status 1. A check whose inputs are unchanged since its
+    # last green run is not run: it is printed as skipped, and the verdict counts it as skipped, not
+    # passed (see GateMemo).
     module Gate
-      STAGES_FILE = File.expand_path("../gate/stages.yml", __dir__)
       USAGE = "usage: hecks gate <stage> [only=a,b] | hecks gate --list"
 
+      # RuboCop keys its cache by file content, so one directory shared by every worktree lets each
+      # reuse the others' results. It is set here, in the gate's child environment, and not in
+      # .rubocop.yml, so CI and a bare `rubocop` keep the defaults (ADR 0091).
+      RUBOCOP_CACHE_ROOT = File.join(Dir.home, ".cache", "hecks", "rubocop")
+
       module_function
 
+      # @return [Hash{String => Hash}] each stage by name: its `env` and its `checks`, in order,
+      #   each check with its `id`, `title`, `run` words and `blocked`
+      def stages
+        checks = Vocabulary.rows("GateCheck").to_h { |row| [row["name"], check(row)] }
+        Vocabulary.rows("GateStage").to_h do |row|
+          stage = { "env" => env(row["env"]), "checks" => row["checks"].split(",").map { |name| checks.fetch(name) } }
+          [row["name"], stage]
+        end
+      end
+
+      # @param row [Hash{String => String}] a `GateCheck` row
+      # @return [Hash] the check: a script runs as `sh -ec`, otherwise `argv` is the command's words
+      def check(row)
+        run = row["script"].empty? ? row["argv"].split : ["sh", "-ec", row["script"]]
+        row.slice("id", "title", "blocked").merge("run" => run)
+      end
+
+      # @param words [String] `NAME=value` words
+      # @return [Hash{String => String}] the variables a stage sets
+      def env(words)
+        words.split.to_h { |word| word.split("=", 2) }
+      end
+
       # @param argv [Array<String>] a stage name and optionally `only=a,b`, or `--list`
       # @param root [String] the checkout the checks run in
+      # @param progress [StageProgress] where each check's start and end lines go
       # @return [Integer] 0 when every check passed, 1 when one failed, 2 on bad usage
-      def main(argv, root: Tools::ROOT, **)
-        stages = YAML.load_file(STAGES_FILE, aliases: true)
+      def main(argv, root: Tools::ROOT, progress: StageProgress.new, **)
+        stages = self.stages
         return list(stages) if argv == ["--list"]
 
         name, only = parse(argv)
@@ -35,7 +68,17 @@ module Hecks
         checks = select(stage.fetch("checks"), only)
         return unknown(stage, only) if checks.nil?
 
-        report(name, checks, run_all(stage, checks, root))
+        run_planned(name, stage, checks, root, progress)
+      end
+
+      # Runs the checks the memo does not skip, records the green ones, and reports the stage.
+      #
+      # @return [Integer] the verdict of `report`
+      def run_planned(name, stage, checks, root, progress)
+        session = GateMemo::Session.new(root: root, env: stage.fetch("env", {}))
+        plan = session.plan(checks)
+        results = run_all(stage, plan.run, root, progress)
+        GateReport.report(name, plan, results, session.record(results))
       end
 
       # @param argv [Array<String>] the command line words
@@ -61,18 +104,30 @@ module Hecks
       # @param stage [Hash] the stage: its `env` and `checks`
       # @param checks [Array<Hash>] the checks to run
       # @param root [String] the directory they run in
+      # @param progress [StageProgress] told when each check starts and ends
       # @return [Hash{String => Array}] each check's id, and its output and whether it passed
-      def run_all(stage, checks, root)
+      def run_all(stage, checks, root, progress)
         env = stage.fetch("env", {}).reject { |key, _| ENV.key?(key) }
         threads = checks.map do |check|
-          Thread.new { [check["id"], run_one(check, env, root)] }
+          progress.start(check["id"])
+          Thread.new { [check["id"], run_timed(check, env, root, progress)] }
         end
         threads.to_h(&:value)
       end
 
+      # @return [Array(String, Boolean)] what the check printed, and whether it exited 0; the end
+      #   line is written as the check finishes
+      def run_timed(check, env, root, progress)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        output, passed = run_one(check, env, root)
+        progress.finish(check["id"], passed, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+        [output, passed]
+      end
+
       # @return [Array(String, Boolean)] what the check printed, and whether it exited 0
       def run_one(check, env, root)
         argv = check.fetch("run").map { |word| word.to_s.sub("{workers}", workers.to_s) }
+        env = { "RUBOCOP_CACHE_ROOT" => RUBOCOP_CACHE_ROOT }.merge(ENV.slice("RUBOCOP_CACHE_ROOT")).merge(env)
         output, status = Open3.capture2e(env, *argv, chdir: root)
         [output, status.success?]
       rescue SystemCallError => e
@@ -86,30 +141,6 @@ module Hecks
         [Etc.nprocessors / 2, 1].max
       end
 
-      # @param name [String] the stage name
-      # @param checks [Array<Hash>] the checks that ran
-      # @param results [Hash{String => Array}] each check's output and whether it passed
-      # @return [Integer] 0 when every check passed, 1 otherwise
-      def report(name, checks, results)
-        failed = checks.reject { |check| results.fetch(check["id"]).last }
-        failed.each { |check| print_failure(name, check, results.fetch(check["id"]).first) }
-        return summary(name, "red", failed, 1) unless failed.empty?
-
-        summary(name, "green", checks, 0)
-      end
-
-      # @return [Integer] the given status, after printing the stage's verdict and its check ids
-      def summary(name, verdict, checks, status)
-        puts "[gate #{name}] #{verdict}: #{checks.map { |check| check["id"] }.join(", ")}"
-        status
-      end
-
-      # @return [void] prints a failing check's output and what its failure means
-      def print_failure(name, check, output)
-        puts "\n[gate #{name}] #{check["title"]}\n\n#{output}"
-        puts "\n[gate #{name}] BLOCKED: #{check["blocked"]}\n"
-      end
-
       def list(stages)
         stages.each do |name, stage|
           puts "#{name}: #{stage.fetch("checks").map { |check| check["id"] }.join(", ")}"

data/lib/hecks/tools/gate_memo/local_files.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Tools
+    module GateMemo
+      # The gitignored files a copy keeps for itself, which decide where a booted domain stores and
+      # so what a check that boots it sees (`FolderOverlay`): local worlds and hecksagons beside a
+      # domain or in the working directory, and the `local` environment. Git ignores them, so the
+      # memo's `owned` list leaves them out; a check that boots a domain reads them from disk, or a
+      # green on one copy's database would be reused on a copy that names another.
+      module LocalFiles
+        # Globs under the checkout.
+        GLOBS = %w[lib/**/*.local.hecksagon lib/**/*.local.world examples/**/*.local.hecksagon
+                   examples/**/*.local.world qa/**/*.local.hecksagon qa/**/*.local.world
+                   *.local.hecksagon *.local.world environments/local.hecksagon
+                   environments/local.world].freeze
+
+        # The checks that boot a domain, so read its local files.
+        BOOTING = %w[rspec fuzzing query_agreement engine_agreement model_check].freeze
+
+        module_function
+
+        # @param root [String] the checkout
+        # @return [Array<String>] the local world and hecksagon files on disk, git-ignored or not,
+        #   relative to the checkout and sorted
+        def files(root)
+          found = GLOBS.flat_map { |glob| Dir.glob(glob, base: root) }
+          found.uniq.select { |rel| File.file?(File.join(root, rel)) }.sort
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/gate_memo/rehearsal.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../gate_memo"
+
+module Hecks
+  module Tools
+    module GateMemo
+      # Whether a mint rehearsal's copy of a ledger can be reused. Only a rehearsal that said
+      # `would_mint`
+      # is kept, and it is reused only while the ledger's watermark and its translation edge are the
+      # ones
+      # it read. Reuse never skips the mint's own check: `moved?` compares the live watermark, and
+      # the
+      # PostgresEra lineage manager refuses a mint whose watermark moved.
+      module Rehearsal
+        # The one verdict a mint may follow.
+        VERDICT = "would_mint"
+
+        module_function
+
+        # @param domain [String] the domain the rehearsal was for
+        # @return [String] the memo key of the domain's rehearsal
+        def key(domain) = "mint_rehearsal:#{domain}"
+
+        # @return [Hash, nil] the entry to keep for a rehearsal, or nil when its verdict is not
+        # would_mint
+        def entry(verdict:, watermark:, edge:)
+          return nil unless verdict == VERDICT
+
+          { "verdict" => verdict, "watermark" => watermark, "edge" => edge, "at" => Time.now.utc.iso8601 }
+        end
+
+        # @return [Boolean] whether the memo's rehearsal of the domain said would_mint on this
+        # watermark
+        #   and this edge; false when the edge is unknown
+        def reusable?(memo, domain, watermark:, edge:)
+          entry = memo[key(domain)]
+          !edge.nil? && entry.is_a?(Hash) && entry["verdict"] == VERDICT &&
+            entry["watermark"] == watermark && entry["edge"] == edge
+        end
+
+        # @return [Boolean] whether the live watermark differs from the one the rehearsal read, so a
+        #   mint needs a new rehearsal
+        def moved?(entry, live_watermark) = entry["watermark"] != live_watermark
+
+        # @return [void] keeps a would_mint entry for the domain, and forgets any other verdict
+        def remember(memo, domain, entry)
+          entry ? memo[key(domain)] = entry : memo.delete(key(domain))
+        end
+      end
+    end
+  end
+end