hecks 5.0.0 → 7.0.0

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "time"
+require "hecks/quality_control/adapters/run_keys"
+require "hecks/runtime/asking"
+require "hecks/runtime/errors"
+require "hecks/runtime/row_sweep"
+require "hecks/runtime/dispatcher"
+
+module Hecks
+  module Adapters
+    # The `Reader` port's adapter: reads one CI run of main (`gh run view`, job logs) for the spec
+    # files it failed, and reports each to `RedSpec` through the boot whose `MainRun` asked. A file
+    # already red is updated, never opened twice. It answers the commit and whether the run settled,
+    # which the bluebook's policies use to clear the files the run did not fail.
+    #
+    # `gh` is the one thing it reaches for besides the clock; a spec stubs `Open3` with a fake run.
+    class RunReader
+      # A line of RSpec's "Failed examples:" summary as a job log prints it: the file, then the
+      # example's description.
+      # The path is read up to its `.rb` and the location that follows (`:12` or `[1:2]`), so a
+      # path with a space in it still matches; RSpec may quote it or escape the space.
+      FAILED_EXAMPLE = %r{rspec ['"]?(\./spec/.+?\.rb)(?:\[[^\]]*\]|:\d+)['"]?\s*(?:#\s*(.*))?$}
+
+      # Where a path's escaped space is unescaped.
+      ESCAPED_SPACE = "\\ "
+
+      # A job whose name says it runs specs.
+      SPEC_JOB = /spec/i
+
+      # The one conclusion that clears a red spec: the job ran its specs and they passed.
+      PASSED = "success"
+
+      # The branch and the event whose runs count: a push to main.
+      BRANCH = "main"
+      EVENT = "push"
+
+      # Job conclusions that are no verdict on the specs: the job did not run to an end.
+      UNFINISHED = [nil, "", "cancelled", "skipped", "neutral", "stale", "action_required"].freeze
+
+      # What `gh run view --json` is asked for.
+      JSON_FIELDS = "headSha,headBranch,event,createdAt,conclusion,jobs"
+
+      # Longest text the reader keeps of a failure line or the example list.
+      SHORT = 200
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] the checkout `gh` runs in; this repository when nil
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @root = root || File.expand_path("../../../..", __dir__)
+      end
+
+      # @param path [String] a spec path such as `spec/a/b_spec.rb`
+      # @return [String] the key of its row; see `RunKeys`
+      def self.key_for(path) = RunKeys.spec(path)
+
+      # @param run [Hash, String] the GitHub run id
+      # @param repo [Hash, String] `owner/name`
+      # @return [Hash] `commit:` and `settled:` ("yes" only when every spec job ended `success`)
+      # @raise [Runtime::GivenNotMet] when the run is not a push to main
+      def read(run:, repo:, **)
+        id = named(run)
+        view = JSON.parse(gh("run", "view", id, "--repo", named(repo), "--json", JSON_FIELDS))
+        refuse_unless_main!(view, id)
+        seen = { run: id, commit: view.fetch("headSha") }
+        file_failures(failures_in(gh("run", "view", id, "--repo", named(repo), "--log-failed")), view, seen)
+        { commit: { value: seen[:commit] }, settled: { value: green?(view, id) ? "yes" : "no" } }
+      end
+
+      private
+
+      def green?(view, id) = settled?(view) && !behind_a_row?(id)
+
+      # Reports each failing file; a failed job whose log named none is reported as a row
+      # of its own.
+      def file_failures(failures, view, seen)
+        failures.each { |path, examples| report(RunKeys.spec(path), path, examples, seen) }
+        report_unparsed(view, failures, seen)
+      end
+
+      def named(value) = value.is_a?(Hash) ? value.values.first.to_s : value.to_s
+
+      # Only a push to main is read: another branch's run, or a pull request's, says nothing
+      # of main.
+      def refuse_unless_main!(view, id)
+        return if view["headBranch"] == BRANCH && view["event"] == EVENT
+
+        raise Runtime::GivenNotMet, "run #{id} is #{view["event"].inspect} on #{view["headBranch"].inspect}, " \
+                                    "not a #{EVENT} to #{BRANCH}; only main's own runs are read"
+      end
+
+      def spec_jobs(view) = view.fetch("jobs", []).select { |job| job["name"].to_s.match?(SPEC_JOB) }
+
+      # Every job that runs specs ended `success`, and at least one did. A failed job with no
+      # failure parsed from its log is not green: the run clears nothing.
+      def settled?(view)
+        jobs = spec_jobs(view)
+        jobs.any? && jobs.all? { |job| job["conclusion"] == PASSED }
+      end
+
+      # A spec job that failed (or timed out) while the log named no failing example is reported as
+      # a row of its own, so the failure stays visible and open.
+      def report_unparsed(view, failures, seen)
+        return unless failures.empty?
+
+        spec_jobs(view).reject { |job| UNFINISHED.include?(job["conclusion"]) || job["conclusion"] == PASSED }.each do |job|
+          name = job["name"].to_s
+          report(RunKeys.job(name), "job #{name}", ["#{name} #{job["conclusion"]}: no failing example in its log"], seen,
+                 title: "spec job #{name} failed on main with no failing example parsed")
+        end
+      end
+
+      # @return [Hash{String => Array<String>}] each failing spec file to its failing example texts
+      def failures_in(log)
+        log.each_line(chomp: true).with_object(Hash.new { |h, k| h[k] = [] }) do |line, found|
+          match = FAILED_EXAMPLE.match(line)
+          found[match[1].delete_prefix("./").gsub(ESCAPED_SPACE, " ")] << match[2].to_s.strip if match
+        end
+      end
+
+      def report(key, path, examples, seen, title: "#{path} is red on main")
+        facts = facts_of(examples, seen[:run], seen[:commit])
+        row = row_for(key)
+        if row
+          dispatch("QualityControl::RedSpec.Update", facts.merge(to: key)) unless older?(seen[:run], row)
+        else
+          open_or_reopen(key, path, title, facts)
+        end
+      end
+
+      # A file never seen red is opened; one cleared earlier already has its row, which reopens.
+      def open_or_reopen(key, path, title, facts)
+        facts = facts.merge(title: title, since: Time.now.utc.strftime("%Y-%m-%d"))
+        dispatch("QualityControl::RedSpec.Open", facts.merge(spec: key, path: path))
+      rescue Runtime::AlreadyExists
+        dispatch("QualityControl::RedSpec.Reopen", facts.merge(to: key))
+      end
+
+      # A run older than the one the row last saw does not overwrite what the row knows.
+      def older?(run, row) = run.to_i < last_run_of(row)
+
+      def last_run_of(row)
+        value = row[:last_run]
+        (value.respond_to?(:value) ? value.value : value).to_s.to_i
+      end
+
+      # Whether some red row was last seen by a newer run than this one: GitHub run ids grow, so a
+      # run behind a row says nothing of the file's state now and clears nothing.
+      def behind_a_row?(run) = open_rows.any? { |row| last_run_of(row) > run.to_i }
+
+      def facts_of(examples, run, commit)
+        count = examples.size
+        { failures: count, first_failure: short(examples.first.to_s), examples: short(examples.first(3).join(" | ")),
+          last_run: run, commit: commit,
+          detail: short("#{count} failing example#{"s" unless count == 1}; first: #{examples.first}; run #{run}; sha #{commit}") }
+      end
+
+      def short(text) = text.length > SHORT ? "#{text[0, SHORT - 3]}..." : text
+
+      # The spec's row while it is red: a red row is updated, a green or absent one is opened.
+      def row_for(key) = open_rows.find { |row| row[:id].to_s == key }
+
+      def open_rows
+        sweep = Runtime::RowSweep.new(registry)
+        aggregate = sweep.query_aggregate("QualityControl", "RedSpec", verb: "RedSpec.OnMain")
+        sweep.rows("QualityControl", aggregate, "OnMain", {})
+      end
+
+      def dispatch(verb, args) = Runtime::Dispatcher.new(registry).dispatch_flat(verb, args)
+
+      def registry
+        Runtime::Asking.registry or raise Runtime::GivenNotMet, "a run is read only when its MainRun asks"
+      end
+
+      def gh(*args)
+        out, err, status = Open3.capture3("gh", *args, chdir: @root)
+        raise Runtime::GivenNotMet, "gh #{args.first(3).join(" ")} failed: #{err.lines.first&.strip}" unless status.success?
+
+        out
+      rescue Errno::ENOENT
+        raise Runtime::GivenNotMet, "gh is not installed or not on PATH"
+      end
+    end
+  end
+end

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

@@ -5,9 +5,9 @@ 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.
+    # enrol, generate and judge bluebooks: the seed, the generated-domain check, the combination
+    # miner, the mutation test, 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
@@ -26,6 +26,12 @@ module Hecks
         run_command("qa_mine_combinations", *words(arguments), answers: [0, 1])
       end
 
+      # @param arguments [Hash, String, nil] the command's own flags, such as `--from-dials`
+      # @return [Hash] `text:` the kill rate, and every mutant no test caught
+      def mutate(arguments: nil)
+        run_command("qa_mutate", *words(arguments), answers: [0, 2])
+      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

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

@@ -12,10 +12,12 @@ module Hecks
       # `hecks/quality_control/cli/<command>`.
       COMMANDS = {
         "qa_tick"                      => ["QaTick", :argv_root],
+        "qa_event_pump"                => ["QaEventPump", :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_mutate"                    => ["QaMutate", :argv_root],
         "qa_domain_novelty"            => ["QaDomainNovelty", :argv_root],
         "qa_discover_external_domains" => ["QaDiscoverExternalDomains", :argv_root],
         "qa_concurrency_racer"         => ["QaConcurrencyRacer", :argv_root],

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

@@ -86,7 +86,7 @@ module Hecks
                            "pass --known-path <path> ... to run without the ledger", usage: false
           end
 
-          JSON.parse(out).filter_map { |row| row.dig("path", "value") }
+          JSON.parse(out).filter_map { |row| row["path"] }
         end
 
         # The sibling directories under `projects_dir`, leaving out this repo (already fully covered

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

@@ -9,7 +9,7 @@ module Hecks
         # Why an empty result is a question about the census, not a verdict on the domain.
         READ_AS_QUESTION = "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 " \
+                           "bluebook-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 " \

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

@@ -99,14 +99,14 @@ module Hecks
         [argv.first(split), argv.drop(split + 1).reject { |arg| arg == "--against" }]
       end
 
-      # `hecks project_rust` reads exactly `<name>/bluebook/<name>.bluebook`, so refuse anything
+      # `hecks build.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`; " \
+                          "(`<name>/bluebook/<name>.bluebook` — a flat file breaks `hecks build.project_rust!`; " \
                           "see qa/stress_domains/ledger_ordering/NOTES.md)"
       end
 
@@ -121,7 +121,7 @@ module Hecks
           raise Stopped
         end
 
-        JSON.parse(out).map { |row| row.dig("path", "value") }.compact
+        JSON.parse(out).filter_map { |row| row["path"] }
       end
 
       def normalize(path) = File.expand_path(path, @root)

data/lib/hecks/quality_control/cli/qa_event_pump/attached.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaEventPump
+      # The domains the pump reads and reacts for: each name with the directory that boots it. The
+      # ledger, `QualityControl`, is the one whose `EventCursor` rows hold the positions.
+      class Attached
+        # @param root [String] the repository root the default directories are found under
+        # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` overrides the ledger's directory
+        # @param dirs [Hash{String => String}, nil] the directories by domain name, in place of the
+        #   defaults
+        def initialize(root:, env: ENV, dirs: nil)
+          @dirs = dirs || default_dirs(root, env)
+          @runtimes = {}
+        end
+
+        # @return [Array<String>] the attached domain names, in the order the pump visits them
+        def names = @dirs.keys
+
+        # @param name [String] a domain name
+        # @return [Boolean] whether the pump attaches this domain
+        def known?(name) = @dirs.key?(name)
+
+        # @return [Array<Hecks::Registry>] the registries of every domain booted so far this run
+        def registries = @runtimes.values.map(&:registry)
+
+        # @param name [String] an attached domain name
+        # @return [String] the directory that boots it
+        def dir(name) = @dirs.fetch(name)
+
+        # @param name [String] an attached domain name
+        # @return [Hecks::Runtime::Dispatcher] the domain booted once, and kept for the run
+        def runtime(name)
+          @runtimes[name] ||= Hecks.boot(dir(name))
+        end
+
+        # Whether a domain booted in this process has already delivered `policy` for `event`. The
+        # reaction log keeps the event id each reaction answered, so a second run of the same event
+        # in this process is skipped whatever the cursor says.
+        #
+        # @param event [Hecks::Runtime::Event] the event, with its id
+        # @param policy [Hecks::Bluebook::Policy] the policy about to run
+        # @return [Boolean] true when a delivered reaction for this event and policy is logged
+        def reacted?(event, policy)
+          registries.any? do |registry|
+            registry.reaction_log.any? do |record|
+              record[:delivered] && record[:policy] == policy.name && record[:on] == event.name &&
+                registry.reaction_event(record) == event.id
+            end
+          end
+        end
+
+        private
+
+        def default_dirs(root, env)
+          {
+            "QualityControl" => env.fetch("QA_SWEEP_DOMAIN_DIR", File.join(root, "qa/bluebook")),
+            "Fixer"          => File.join(root, "lib/hecks/fixer"),
+            "Coder"          => File.join(root, "lib/hecks/coder"),
+            "CiPipeline"     => File.join(root, "lib/hecks/ci_pipeline")
+          }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_event_pump/consumer.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "hecks/naming"
+
+module Hecks
+  module QualityControlCli
+    class QaEventPump
+      # One attached domain as a consumer: the logs of the domains its hecksagon subscribes to, read
+      # past each cursor, with the policies that react to each event run through the domain's own
+      # runtime. A subscription to a domain the pump does not attach is named, not read.
+      class Consumer
+        # @param name [String] the consumer's domain name
+        # @param attached [Attached] the attached domains
+        # @param cursors [Cursors] where the positions are kept
+        # @param reactions [Reactions] where the reactions already made are kept
+        def initialize(name, attached:, cursors:, reactions:)
+          @name = name
+          @attached = attached
+          @cursors = cursors
+          @reactions = reactions
+          @failed = false
+        end
+
+        # @return [Boolean] whether reading or reacting stopped this consumer
+        def failed? = @failed
+
+        # Reads every attached log this consumer subscribes to, and names each subscription it
+        # cannot read.
+        #
+        # @return [Array<String>] one line per reaction and per problem
+        def lines
+          producers.flat_map { |producer| read(producer) } + unattached
+        end
+
+        private
+
+        def runtime = @attached.runtime(@name)
+
+        def subscribed
+          (runtime.registry.hecksagon(@name)&.subscriptions || []).filter_map { |event| Naming.qualifier(event) }.uniq
+        end
+
+        def producers = subscribed.select { |domain| @attached.known?(domain) }
+
+        def unattached
+          (subscribed - producers).map { |domain| "#{@name} subscribes to #{domain}, which the pump does not attach" }
+        end
+
+        # Reads one producer's log past this consumer's cursor, reacting to each entry in turn. A
+        # stop leaves the cursor on the last entry that was reacted to.
+        def read(producer)
+          start = @cursors.position(producer, @name)
+          entries = Reader.after(@attached.dir(producer), start)[:events]
+          entries.each_with_index.flat_map { |entry, index| react(producer, entry, start + index + 1) }
+        rescue StandardError => e
+          @failed = true
+          ["#{@name} <- #{producer}: stopped, #{e.class}: #{e.message}"]
+        end
+
+        # Runs each policy that reacts to the entry and that neither the ledger nor this process
+        # holds a reaction for, then moves the cursor past it. A reaction is recorded as soon as
+        # its policy answers, before the cursor moves. The reactions and the cursor share one
+        # transaction where the ledger's store has one, so a stop between them rolls both back
+        # and the rerun repeats both.
+        def react(producer, entry, position)
+          event = Reader.event(entry)
+          @cursors.transaction do
+            lines = runtime.outbox.policies_for(event, producer).flat_map do |policy, home|
+              next [] if reacted?(event, policy)
+
+              fire(event, policy, home, producer, position)
+            end
+            @cursors.advance(producer, @name, position)
+            lines
+          end
+        end
+
+        # Whether the policy has already reacted to this event: recorded in the ledger by an
+        # earlier pass, or delivered in this process by a domain attached here, by either path.
+        def reacted?(event, policy)
+          @reactions.recorded?(@name, event.id, policy.name) || @attached.reacted?(event, policy)
+        end
+
+        def fire(event, policy, home, producer, position)
+          log = runtime.reactions
+          before = log.size
+          runtime.outbox.react_policy(event, policy: policy, home: home, domain: producer,
+                                             event_uid: "#{producer}##{position}")
+          records = log.drop(before)
+          @reactions.record(@name, event.id, policy.name) if records.any?
+          records.map { |record| describe(record, policy, event, producer) }
+        end
+
+        def describe(record, policy, event, producer)
+          label = "#{@name} <- #{producer} #{event.name}: #{policy.name}"
+          return "reacted: #{label}" if record[:delivered]
+
+          "refused: #{label}: #{record[:reason]}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_event_pump/cursors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaEventPump
+      # The positions the pump has read to, kept as the ledger's `EventCursor` rows: one per (log,
+      # consumer). A row is opened at the start of the log the first time a consumer reads it.
+      class Cursors
+        # @param runtime [Hecks::Runtime::Dispatcher] the booted ledger the rows live in
+        def initialize(runtime)
+          @runtime = runtime
+        end
+
+        # @param log [String] the domain whose event log is read
+        # @param consumer [String] the domain whose policies react
+        # @return [Integer] the count of log entries the consumer has reacted to
+        def position(log, consumer)
+          row = row_for(key(log, consumer)) || open_row(log, consumer)
+          row[:position][:value]
+        end
+
+        # Moves one consumer's cursor past the entries it has reacted to.
+        #
+        # @param log [String] the domain whose event log was read
+        # @param consumer [String] the domain whose policies reacted
+        # @param position [Integer] the count of entries now reacted to
+        # @return [void]
+        def advance(log, consumer, position)
+          @runtime.dispatch_flat("QualityControl::EventCursor.Advance", to: key(log, consumer), position: position)
+        end
+
+        # Runs the block in one transaction on the ledger's store where that store has one, so a
+        # reaction and the cursor past it commit together or not at all. A store without
+        # transactions (Memory) yields, and the reaction log is then the only guard against a rerun.
+        #
+        # @yield the reaction and the cursor move, as one unit
+        # @return [Object] the block's own value
+        def transaction(&)
+          repository = @runtime.registry.repository("QualityControl", cursor_aggregate)
+          repository.respond_to?(:transaction) ? repository.transaction(&) : yield
+        end
+
+        private
+
+        def cursor_aggregate = ledger_bluebook.aggregates.find { |aggregate| aggregate.hecks_name == "EventCursor" }
+
+        def ledger_bluebook = @runtime.registry.bluebook("QualityControl")
+
+        def key(log, consumer) = "#{log}/#{consumer}"
+
+        def row_for(key) = @runtime.query("QualityControl::EventCursor.All").find { |row| row[:key][:value] == key }
+
+        def open_row(log, consumer)
+          @runtime.dispatch_flat("QualityControl::EventCursor.Start", key: key(log, consumer), log: log, consumer: consumer)
+          row_for(key(log, consumer))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_event_pump/reactions.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaEventPump
+      # The reactions the pump has made, kept as the ledger's `EventReaction` rows: one per
+      # (consumer, event, policy). The pump asks before it runs a policy, and records the reaction
+      # once the policy's command has answered, delivered or refused. The keys are read once, on
+      # first use, and kept for the run, so a pass costs one query however many events it reads.
+      class Reactions
+        # @param runtime [Hecks::Runtime::Dispatcher] the booted ledger the rows live in
+        def initialize(runtime)
+          @runtime = runtime
+          @known = nil
+        end
+
+        # @param consumer [String] the domain whose policy would run
+        # @param event_id [String] the id of the event the policy would react to
+        # @param policy [String] the policy's name
+        # @return [Boolean] whether the ledger already holds this reaction
+        def recorded?(consumer, event_id, policy)
+          known.include?(key(consumer, event_id, policy))
+        end
+
+        # @param consumer [String] the domain whose policy answered
+        # @param event_id [String] the id of the event it answered
+        # @param policy [String] the policy's name
+        # @return [void]
+        def record(consumer, event_id, policy)
+          row = key(consumer, event_id, policy)
+          @runtime.dispatch_flat("QualityControl::EventReaction.Record", key: row, consumer: consumer,
+                                                                         event_id: event_id, policy: policy)
+          known << row
+        end
+
+        private
+
+        def known
+          @known ||= @runtime.query("QualityControl::EventReaction.All").to_set { |row| row[:key][:value] }
+        end
+
+        def key(consumer, event_id, policy) = "#{consumer}/#{event_id}/#{policy}"
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_event_pump/reader.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+require "hecks/hecks/adapters/in_process_boot"
+
+module Hecks
+  module QualityControlCli
+    class QaEventPump
+      # Reads a domain's event log past a cursor through the `Operation.Follow` query, and turns
+      # each entry back into an event a policy can react to.
+      module Reader
+        module_function
+
+        # @param dir [String] the directory of the domain whose log is read
+        # @param position [Integer] the count of entries already read
+        # @return [Hash] `cursor:` the count now read to, and `events:` the entries past `position`
+        #   (each with its payload as JSON text, as the query answers it)
+        def after(dir, position)
+          Hecks::Adapters::InProcessBoot.new.follow(domain: dir, since: position, wait: 0)
+        end
+
+        # @param entry [Hash] one entry the query answered
+        # @return [Hecks::Runtime::Event] the event, with its payload parsed back to a hash
+        def event(entry)
+          Hecks::Runtime::Outbox.event_from(entry.merge("payload" => JSON.parse(entry["payload"])))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "../../../hecks"
+# The era subsystem does not load with core (ADR 0033); the QualityControl ledger binds it.
+require_relative "../../ports/persistence/plugins/era"
+require_relative "qa_event_pump/attached"
+require_relative "qa_event_pump/cursors"
+require_relative "qa_event_pump/reactions"
+require_relative "qa_event_pump/reader"
+require_relative "qa_event_pump/consumer"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control event_pump.pump!`: reads each attached domain's
+    # event log past its cursor and runs the policies that react to what it reads. A consumer reads
+    # the logs its hecksagon subscribes to, and each cursor is one (log, consumer) row of the
+    # ledger's `EventCursor`. The pump writes no domain's event log.
+    #
+    # A policy that has an `EventReaction` row for its event is not run again. A refused reaction is
+    # recorded and named, and the cursor moves past it. A cursor does not move for an event whose
+    # reaction could not run at all: that consumer stops, and the pump exits 1.
+    class QaEventPump
+      EXIT_OK = 0
+      EXIT_ERROR = 1
+
+      USAGE = "usage: hecks quality_control event_pump.pump!"
+
+      # Runs the pump, or prints its usage for `--help`.
+      #
+      # @param argv [Array<String>] no arguments
+      # @param root [String] the repository root the attached domains are found under
+      # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` picks the ledger's bluebook
+      #   directory
+      # @return [Integer] 0 when every consumer read its logs, 1 when one could not
+      # @raise [SystemExit] when given arguments
+      def self.call(argv, root:, env: ENV)
+        return reject(argv) unless argv.empty?
+
+        new(root: root, env: env).run
+      end
+
+      # @param argv [Array<String>] the arguments given
+      # @return [Integer] 0 for `--help`
+      # @raise [SystemExit] for any other argument
+      def self.reject(argv)
+        return puts(USAGE) && EXIT_OK if %w[-h --help].include?(argv.first)
+
+        abort "#{USAGE}\nthis command takes no arguments — one pump is always the same pump"
+      end
+
+      # @param root [String] the repository root
+      # @param env [Hash{String => String}] the environment the ledger's directory is read from
+      # @param attached [Attached, nil] the attached domains; built from `root` and `env` when
+      #   absent
+      def initialize(root:, env: ENV, attached: nil)
+        @attached = attached || Attached.new(root: root, env: env)
+      end
+
+      # Runs every consumer once and prints what each reaction did.
+      #
+      # @return [Integer] 0 or 1, as `call` answers
+      def run
+        ledger = @attached.runtime("QualityControl")
+        cursors = Cursors.new(ledger)
+        reactions = Reactions.new(ledger)
+        consumers = @attached.names.map do |name|
+          Consumer.new(name, attached: @attached, cursors: cursors, reactions: reactions)
+        end
+        lines = consumers.flat_map(&:lines)
+        lines.each { |line| puts line }
+        puts "event pump: #{lines.size} line(s) reported"
+        consumers.any?(&:failed?) ? EXIT_ERROR : EXIT_OK
+      end
+    end
+  end
+end