hecks 6.0.0 → 7.0.0

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "qa_era_mint"
+require_relative "../../adapters/driven/postgres_era/lineage_manager/mint_decision"
+
+module Hecks
+  module Adapters
+    # The auto-mint rule the Maintenance mint enforces. A mint runs without the owner's confirm only
+    # when
+    # the edge leaving the held era is empty, every change in the shape diff is additive, and the
+    # rehearsal
+    # refused nothing. The rule is declared as `AutoMintAdditive` in quality_control.bluebook; this
+    # module
+    # is its check. The stranded-marker and watermark guards stay in `MainMaintenance#mint`.
+    module QaAutoMint
+      # The edge file's opening line and its closing line, with nothing between them when it is
+      # empty.
+      EDGE_HEADER = /\AHecks\.data_translation\s+"[^"]*",\s+from:\s+"[^"]*",\s+to:\s+"[^"]*"\s+do\z/
+
+      module_function
+
+      # The facts the rule reads from a ledger: its live watermark, the edge leaving its held era
+      # and that edge's text, and the verdict the shared mint decision reaches for the held era.
+      #
+      # @param ledger [String] the bluebook directory of the ledger
+      # @return [Hash] `watermark`, `from`, `to`, `edge_text`, `verdict`, `held` and `current`
+      def facts(ledger)
+        held = JournalStore::HeldDomain.open(ledger, mode: :translated)
+        registry = held.registry
+        latest, watermark = latest_era(held)
+        verdict = PostgresEra::LineageManager::MintDecision.decide_latest(
+          latest, bluebook: held.bluebook, translations: registry.translations, directory: ledger, watermark: watermark
+        )
+        { watermark: watermark, held: held_bluebook(latest), current: held.bluebook, verdict: verdict }
+          .merge(edge_facts(held, ledger, latest[:label]))
+      end
+
+      # @return [Array(Hash, Integer)] the latest held era and the live watermark, read from its
+      #   database
+      def latest_era(held)
+        db = PostgresEra.connect_for(held.domain_name, held.settings)
+        lineage = PostgresEra::Lineage.new(db, held.domain_name)
+        [lineage.eras.last, lineage.last_ordinal]
+      ensure
+        db&.close
+      end
+
+      # @return [Runtime::ProjectedBluebook] the held era's stored storage shape, as a bluebook view
+      def held_bluebook(latest) = PostgresEra::LineageManager.held_bluebook(latest)
+
+      # The bluebook directory a mint is for: the one the request names, or the QualityControl
+      # ledger.
+      #
+      # @return [String]
+      def ledger_for(root, requested) = requested || File.join(root, QaEraMint::LEDGER)
+
+      # The ledger a mint is for, refused by name when its world declares it disposable: its boot
+      # holds every shape change itself, so there is no era to mint.
+      #
+      # @return [String] the bluebook directory
+      # @raise [Runtime::WiringError] if the ledger is disposable
+      def mintable_ledger_for(root, requested)
+        ledger = ledger_for(root, requested)
+        raise Runtime::WiringError, QaEraMint::DISPOSABLE if QaEraMint.disposable?(ledger)
+
+        ledger
+      end
+
+      # The journal rows the run's own `Maintenance` record wrote above the rehearsed watermark: the
+      # mint command saves that record before its entry point runs, so it is the one change the
+      # rehearsal could not have read.
+      #
+      # @param ledger [String] the bluebook directory of the ledger
+      # @param run [String] the run key, which is the record's id
+      # @param rehearsed [Integer] the watermark the rehearsal read
+      # @return [Integer]
+      def own_rows_after(ledger, run, rehearsed)
+        held = JournalStore::HeldDomain.open(ledger, mode: :translated)
+        db = PostgresEra.connect_for(held.domain_name, held.settings)
+        PostgresEra::Lineage.new(db, held.domain_name).rows_of_after(rehearsed, "maintenance", run)
+      ensure
+        db&.close
+      end
+
+      # Why a rehearsed watermark is stale at the live one: the ledger moved by something other than
+      # the run's own record, which `commands` counts in the journal now.
+      #
+      # @param commands [#own_rows_after] reads the journal
+      # @param ledger [String] the bluebook directory of the ledger
+      # @param run [String] the run key
+      # @param rehearsed [Integer] the watermark the rehearsal read
+      # @param live [Integer] the live watermark
+      # @return [String, nil]
+      def stale_for(commands, ledger, run, rehearsed, live)
+        stale_watermark(rehearsed, live, own_rows: commands.own_rows_after(ledger, run, rehearsed))
+      end
+
+      # A watermark is stale when the ledger moved by anything but the run's own record.
+      #
+      # @param own_rows [Integer] the rows that record wrote above the rehearsed watermark
+      # @return [String, nil] the reason the live watermark moved from the rehearsed one, or nil
+      def stale_watermark(rehearsed, live, own_rows: 0)
+        return if rehearsed == live - own_rows
+
+        "the ledger watermark moved from #{rehearsed} to #{live} since the rehearsal; rehearse again"
+      end
+
+      # Why a mint waits for the owner: never when confirmed, else the reason the rule holds it.
+      #
+      # @param confirm [Boolean, nil] the owner's confirmation
+      # @return [String, nil]
+      def hold_reason(facts, confirm, refusal_total)
+        held_reason(facts, refusal_total: refusal_total) unless confirm == true
+      end
+
+      # Why the auto-mint rule holds a mint for the owner, or nil when it lets the mint run
+      # unconfirmed. With no edge file, the implicit empty edge stands in for an empty edge when
+      # the shape change qualifies for one.
+      #
+      # @param facts [Hash] what `facts` read from the ledger
+      # @param refusal_total [Integer, nil] the rehearsal's refusal count
+      # @return [String, nil] the reason the owner must approve, or nil when the rule holds
+      def held_reason(facts, refusal_total:)
+        edge_reason(facts) || additive_reason(facts) || rehearsal_reason(refusal_total)
+      end
+
+      # @return [String, nil] why the edge leaving the held era does not stand in for an empty one
+      def edge_reason(facts)
+        return "no translation edge leaves #{facts[:from]}" if facts[:edge_text].nil? && !implicit?(facts)
+        return "the edge from #{facts[:from]} is not empty" if facts[:edge_text] && !empty_edge?(facts[:edge_text])
+
+        nil
+      end
+
+      # @return [String, nil] why the shared decision does not take the shape change as additive
+      def additive_reason(facts)
+        case facts[:verdict].reason
+        when :non_qualifying then "the shape change is not additive"
+        when :unrecorded then "the move from #{facts[:from]} to #{facts[:to]} is not recorded"
+        end
+      end
+
+      # @return [String, nil] why the rehearsal refused rows
+      def rehearsal_reason(refusal_total)
+        return if refusal_total.is_a?(Integer) && refusal_total.zero?
+
+        "the rehearsal refused #{refusal_total.inspect} rows"
+      end
+
+      # Whether an edge file declares nothing: its header and its `end`, with no line between them.
+      #
+      # @param text [String] the edge file's text
+      # @return [Boolean]
+      def empty_edge?(text)
+        body = text.lines.map(&:strip).reject { |line| line.empty? || line.start_with?("#") }
+        body.size == 2 && EDGE_HEADER.match?(body.first) && body.last == "end"
+      end
+
+      # Whether no edge file is needed: the shared decision takes the implicit empty edge.
+      #
+      # @return [Boolean]
+      def implicit?(facts) = facts[:verdict].verdict == "would_mint" && facts[:verdict].source == "implicit"
+
+      # @return [Hash] the edge leaving the held era's label for the current shape's label, and its
+      #   text
+      def edge_facts(held, ledger, from)
+        to = Runtime::StorageShape.mint_hash(held.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+        { from: from, to: to, edge_text: edge_text(File.join(ledger, "translations"), from, to) }
+      end
+
+      # The text of the edge that leads from `from` to `to`, found by its header.
+      #
+      # @return [String, nil]
+      def edge_text(dir, from, to)
+        header = %(from: "#{from}", to: "#{to}")
+        Dir.glob(File.join(dir, "*.bluebook")).map { |path| File.read(path) }.find { |text| header_of(text).include?(header) }
+      end
+
+      # @return [String] the first line of an edge file, where its source and target are named
+      def header_of(text) = text.lines.first.to_s
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "../../hecks/adapters/journal_store/held_domain"
+
+module Hecks
+  module Adapters
+    # The mint of the QualityControl ledger's next era, run by the Maintenance mint. The era check
+    # of the ledger the QA world names runs once with the mint command's request. The world keeps
+    # `mint_eras false`; this one check's settings carry `mint_eras true` and the request, which is
+    # the one-mint permission the world's comment describes.
+    module QaEraMint
+      # The ledger's bluebook directory, under the repository root.
+      LEDGER = "qa/bluebook"
+
+      # What a mint of a disposable ledger answers: its boot holds every shape change itself.
+      DISPOSABLE = "disposable, no mint needed: the ledger's world declares disposable_ledger true, " \
+                   "so its boot brings the shape up to date without an era"
+
+      module_function
+
+      # Whether a ledger's world declares `disposable_ledger true`, so it needs no mint.
+      #
+      # @param ledger [String, JournalStore::HeldDomain] the bluebook directory, or the opened one
+      # @return [Boolean]
+      def disposable?(ledger)
+        held = ledger.is_a?(String) ? JournalStore::HeldDomain.open(ledger, mode: :translated) : ledger
+        PostgresEra::LineageManager::DisposableLedger.declared?(held.settings)
+      end
+
+      # Mints the next era of the ledger, or refuses by name.
+      #
+      # @param root [String] the repository root holding `qa/bluebook`
+      # @param domain [String] the domain the mint is for; the ledger must hold it
+      # @param era [Integer] the ordinal the mint is for; it must be the era the ledger would mint
+      #   next
+      # @param request [Hash] the mint command's request: `confirm` (a boolean), `verdict` (the
+      #   rehearsal's verdict) and `watermark` (the ledger watermark the rehearsal read)
+      # @param ledger [String, nil] the bluebook directory of the ledger; the QualityControl ledger
+      #   under `root` when nil
+      # @return [Array(String, Boolean)] the minted era's label or the refusal, and whether it
+      #   minted
+      def call(root, domain:, era:, request:, ledger: nil)
+        held = JournalStore::HeldDomain.open(ledger || File.join(root, LEDGER), mode: :translated)
+        return [DISPOSABLE, false] if disposable?(held)
+
+        settings = held.settings.merge(mint_eras: true, mint_request: request)
+        refuse_wrong_mint!(held, settings, domain, era)
+        mint!(held, settings) ? [Runtime::StorageShape.mint_label(held.bluebook), true] : [unminted, false]
+      rescue Runtime::WiringError, Runtime::NotFound => e
+        [e.message, false]
+      end
+
+      # Refuses a mint that names another domain, or an era other than the one the ledger would mint
+      # next.
+      #
+      # @return [void]
+      # @raise [Runtime::WiringError] naming the mismatch
+      def refuse_wrong_mint!(held, settings, domain, era)
+        name = held.domain_name
+        raise Runtime::WiringError, "the ledger holds #{name}, not #{domain}" unless name == domain
+
+        next_era = next_era_of(settings, name)
+        return if next_era == era
+
+        raise Runtime::WiringError, "the mint names era #{era}, but the ledger's next era is #{next_era}"
+      end
+
+      # @return [Integer] the ordinal the ledger would mint next: one past its latest held era
+      def next_era_of(settings, name)
+        db = PostgresEra.connect_for(name, settings)
+        latest = PostgresEra::Lineage.new(db, name).eras.last
+        latest ? latest[:ordinal] + 1 : 1
+      ensure
+        db&.close
+      end
+
+      # Runs the era check with the request. It mints when the shape drifted, and answers false when
+      # the shape is already the ledger's current one.
+      #
+      # @return [Integer, nil] the ordinal minted, or nil when nothing minted
+      def mint!(held, settings)
+        text = Runtime::EraCheck.source_text_for(held.bluebook, held.directory, registry: held.registry) ||
+               Runtime::EraCheck.refuse_missing_source!(held.bluebook, held.directory)
+        held.registry.adapter_class(held.adapter_name).era_check!(
+          registry: held.registry, bluebook: held.bluebook, current_text: text, settings: settings,
+          directory: held.directory
+        )
+      end
+
+      # @return [String] the refusal for a mint that found nothing to mint
+      def unminted = "the ledger already holds the current shape; no era was minted"
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "fileutils"
+
+module Hecks
+  module Adapters
+    # The marker file that quiets QA for a mint window. While a fresh marker exists, `hecks
+    # quality_control sweep.tick` refuses to start any step (it prints `quiesced: skipped
+    # <step>` and exits 0), so nothing writes to the QA ledger and its watermark holds still
+    # between a rehearsal and the mint. The tick reads the marker before each step, so a tick
+    # already running notices it too.
+    #
+    # The marker is one JSON file beside the stranded-mint record (`~/.claude/hecks-dev/quiesce`,
+    # `HECKS_QUIESCE_STATE` moves it) holding its owner, reason and time. A marker older than the
+    # staleness window (two hours) is ignored and reported, so a crashed mint cannot freeze QA
+    # for good. It touches no ledger and no git state, and the mint itself never requires it.
+    class QaQuiesceMarker
+      # Raised when a hold or release is refused; the message is the reason.
+      class Refused < RuntimeError; end
+
+      # Where the marker lives.
+      PATH = ENV.fetch("HECKS_QUIESCE_STATE", File.expand_path("~/.claude/hecks-dev/quiesce")).freeze
+
+      # How long a marker holds before it counts as left behind by a crash.
+      STALE_AFTER = Integer(ENV.fetch("HECKS_QUIESCE_STALE_SECONDS", 2 * 60 * 60))
+
+      # What a marker says: who holds the window, why and since when.
+      Hold = Struct.new(:owner, :reason, :held_at, keyword_init: true)
+
+      # @param path [String] the marker file
+      # @param stale_after [Integer] seconds after which a marker is ignored
+      # @param clock [#call] answers the current Time
+      def initialize(path: PATH, stale_after: STALE_AFTER, clock: -> { Time.now })
+        @path = path
+        @stale_after = stale_after
+        @clock = clock
+      end
+
+      # @return [Hold, nil] the marker's content, fresh or stale, or nil when there is none
+      def read
+        return unless File.exist?(@path)
+
+        data = JSON.parse(File.read(@path))
+        Hold.new(owner: data["owner"].to_s, reason: data["reason"].to_s, held_at: Time.iso8601(data["held_at"]))
+      rescue JSON::ParserError, ArgumentError, TypeError
+        Hold.new(owner: "unknown", reason: "unreadable marker", held_at: File.mtime(@path))
+      end
+
+      # @return [Hold, nil] the marker when it is present and not stale
+      def active
+        hold = read
+        hold if hold && !stale?(hold)
+      end
+
+      # @return [Hold, nil] the marker when it is present and past the staleness window
+      def stale
+        hold = read
+        hold if hold && stale?(hold)
+      end
+
+      # Writes the marker. A fresh marker of another owner is refused unless forced; the same
+      # owner's hold is refreshed, and a stale one is replaced.
+      #
+      # @return [Hold] what was written
+      # @raise [Refused] when another owner holds a fresh marker and `force` is false
+      def hold!(owner:, reason:, force: false)
+        current = active
+        if current && current.owner != owner && !force
+          raise Refused, "already held by #{current.owner} (#{describe(current)}); release it, or hold with force"
+        end
+
+        write(Hold.new(owner: owner, reason: reason, held_at: @clock.call))
+      end
+
+      # Removes the marker. Another owner's fresh marker stays unless forced.
+      #
+      # @return [Hold, nil] the marker removed, or nil when there was none
+      # @raise [Refused] when another owner holds a fresh marker and `force` is false
+      def release!(owner:, force: false)
+        current = read
+        return unless current
+        if current.owner != owner && !force && !stale?(current)
+          raise Refused, "held by #{current.owner} (#{describe(current)}), not #{owner}; release with force to remove it"
+        end
+
+        FileUtils.rm_f(@path)
+        current
+      end
+
+      # @return [String] a sentence on the marker: owner, reason and age, or that QA is not quiesced
+      def status
+        hold = read
+        return "not quiesced: no marker at #{@path}" unless hold
+
+        "#{stale?(hold) ? "stale (ignored)" : "quiesced"}: #{describe(hold)}"
+      end
+
+      # @return [String] "owner, reason, held 12 minutes ago"
+      def describe(hold)
+        "owner #{hold.owner}, reason #{hold.reason.inspect}, held #{age(hold)} ago (since #{hold.held_at.utc.iso8601})"
+      end
+
+      private
+
+      def stale?(hold) = (@clock.call - hold.held_at) > @stale_after
+
+      def age(hold)
+        seconds = (@clock.call - hold.held_at).to_i
+        return "#{seconds}s" if seconds < 120
+        return "#{seconds / 60}m" if seconds < 7200
+
+        "#{seconds / 3600}h"
+      end
+
+      def write(hold)
+        FileUtils.mkdir_p(File.dirname(@path))
+        temp = "#{@path}.#{Process.pid}"
+        File.write(temp, JSON.generate(owner: hold.owner, reason: hold.reason, held_at: hold.held_at.utc.iso8601))
+        File.rename(temp, @path)
+        hold
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Hecks
+  module Adapters
+    # The keys of the `RedSpec` rows a run reader files. A key is a readable slug of what is red
+    # and a digest of the exact text, so two spec paths never share a key: separators stay distinct
+    # (`__`), and paths differing only in case or punctuation differ in the digest.
+    module RunKeys
+      # The `.rb` ending of a spec path, left off its key.
+      RUBY_SUFFIX = ".rb"
+
+      # Runs of characters a Work key does not hold.
+      KEY_BREAK = /[^a-zA-Z0-9_]+/
+
+      # Hex digits of the exact text's digest a key ends with.
+      DIGEST_LENGTH = 10
+
+      module_function
+
+      # @param path [String] a spec path such as `spec/a/b_spec.rb`
+      # @return [String] `red-<readable slug>-<digest>`
+      def spec(path) = build(path.delete_suffix(RUBY_SUFFIX).gsub("/", "__"), path)
+
+      # @param job [String] the name of a spec job that failed with no failing example in its log
+      # @return [String] `red-job-<readable slug>-<digest>`
+      def job(job) = build("job-#{job}", job)
+
+      # @return [String] the key for a readable slug and the exact text it stands for
+      def build(slug, exact)
+        "red-#{slug.gsub(KEY_BREAK, "-").downcase}-#{Digest::SHA256.hexdigest(exact)[0, DIGEST_LENGTH]}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+# Binds the `Reader` port to `RunReader`, which reads a CI run of main for the spec files it failed.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/run_reader"
+
+Hecks.adapter "RunReader" do
+  port "Reader"
+end

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/cli/child.rb

@@ -12,6 +12,7 @@ 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],

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