hecks 5.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/journal_store/translation_write.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "held_domain"
+require_relative "edge_audit"
+require_relative "translation_write/shape_edge"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # The `write_translation` change: composes the chain of edges from the latest held era to the
+      # current shape into one edge, writes it, deletes the intermediate edges only the chain used,
+      # and audits what was written. A refused audit puts the translations directory back as it was.
+      #
+      # Planning is a read; only `apply_write_translation` writes, and only to the domain's own
+      # `translations/` directory.
+      module TranslationWrite
+        # What a write would do: the file it writes and its text, the stale files it deletes, and
+        # the shape labels the chain passes through. `message` alone answers when nothing is to be done.
+        Plan = Struct.new(:message, :path, :text, :removals, :labels, keyword_init: true)
+
+        include ShapeEdge
+
+        private
+
+        def examine_write_translation(held)
+          domain = HeldDomain.open(plain(held[:domain]))
+          return {} unless domain.capable?
+
+          domain.reading do |lineage|
+            translation_plan(domain, lineage)
+            { capable: true, held: domain.held_eras(lineage).size }
+          end
+        end
+
+        def apply_write_translation(held)
+          path = plain(held[:domain])
+          domain = HeldDomain.open(path)
+          plan = domain.reading { |lineage| translation_plan(domain, lineage) }
+          return plan.message if plan.message
+
+          write_and_audit(path, plan)
+          written_report(plan)
+        end
+
+        # Writes the plan, then audits what it wrote; a refusal or a failure restores the files.
+        def write_and_audit(path, plan)
+          originals = write_translation!(plan)
+          begin
+            audit_written_translation!(path)
+          rescue StandardError
+            restore_translations!(originals)
+            raise
+          end
+        end
+
+        # The plan a write would carry out, or the sentence that says none is needed.
+        #
+        # @return [Plan] see `Plan`
+        # @raise [Runtime::WiringError] when the chain cannot be composed into one edge
+        def translation_plan(domain, lineage)
+          eras = domain.held_eras(lineage)
+          return Plan.new(message: "#{domain.domain_name} holds no era yet — nothing to write.") if eras.empty?
+
+          latest = domain.named(eras.last)
+          return Plan.new(message: "#{domain.domain_name} matches era #{latest[:ordinal]} — nothing to write.") if
+            held_shape(latest) == domain.shape
+
+          composed_plan(domain, latest)
+        end
+
+        def held_shape(era) = PostgresEra::LineageManager.held_shape(era)
+
+        def composed_plan(domain, latest)
+          current = Runtime::StorageShape.mint_hash(domain.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+          chain = Translation::Compose.chain(domain.translations, domain: domain.domain_name,
+                                                                  from: latest[:label], to: current)
+          return already_leads(latest[:label], current) if chain.size == 1
+          return shape_edge_plan(domain, latest, current) if chain.empty?
+
+          edge_plan(domain, latest[:label], current, chain)
+        end
+
+        # Writes the composed edge and deletes the stale ones; returns what each file held before.
+        #
+        # @return [Hash{String => String, nil}] each touched path with its earlier text, nil if absent
+        def write_translation!(plan)
+          originals = [plan.path, *plan.removals].to_h { |path| [path, read_if_present(path)] }
+          File.write(plan.path, plan.text)
+          plan.removals.each { |path| FileUtils.rm_f(path) }
+          originals
+        end
+
+        def read_if_present(path) = File.exist?(path) ? File.read(path) : nil
+
+        # Puts each touched file back as `write_translation!` found it.
+        def restore_translations!(originals)
+          originals.each do |path, text|
+            text ? File.write(path, text) : FileUtils.rm_f(path)
+          end
+        end
+
+        # Audits the edge that was just written, as the boot does.
+        #
+        # @raise [Runtime::WiringError] when the audit refuses the composed edge
+        def audit_written_translation!(path)
+          domain = HeldDomain.open(path)
+          finding = domain.reading { |lineage| EdgeAudit.call(domain, lineage, domain.held_eras(lineage)) }
+          return if finding.nil? || finding.ok
+
+          raise Runtime::WiringError,
+                "cannot write the translation of #{domain.domain_name}: the audit refused the composed " \
+                "edge —\n  #{finding.refusals.join("\n  ")}"
+        end
+
+        def written_report(plan)
+          removed = plan.removals.map { |path| "  removed #{File.basename(path)}" }
+          ["wrote #{plan.path}", *removed, "the audit passed: #{plan.labels.join(" -> ")}"].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store.rb

@@ -3,6 +3,9 @@
 require_relative "journal_store/examination"
 require_relative "journal_store/changes"
 require_relative "journal_store/readings"
+require_relative "journal_store/translation_write"
+require_relative "journal_store/reconciliation"
+require_relative "journal_store/held_mint"
 
 module Hecks
   module Adapters
@@ -19,6 +22,8 @@ module Hecks
       include Examination
       include Changes
       include Readings
+      include TranslationWrite
+      include Reconciliation
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
@@ -27,12 +32,23 @@ module Hecks
       # @param root [String, nil] unused
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
+      # Answers the held mint of the Hecks domain: see `HeldMint#answer`.
+      #
+      # @param held [Hash] the `MintHeld` record: `run`, and optionally `rehearsal_verdict`,
+      #   `watermark` and `confirm`
+      # @return [Hash{Symbol => Hash}] `run`, `outcome` and `label`
+      # @raise [Runtime::WiringError] naming why the mint was refused
+      def mint(**held)
+        HeldMint.new.answer(run: plain(held[:run]), confirm: plain(held[:confirm]),
+                            rehearsal_verdict: plain(held[:rehearsal_verdict]), watermark: plain(held[:watermark]))
+      end
+
       private
 
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
 
       # Aggregate names, from the comma-separated list a request carries.
-      def names(list) = plain(list).to_s.split(",").map(&:strip).reject(&:empty?)
+      def names(list) = Text.comma_list(plain(list))
 
       # `id:old,id:new` as the map the tail merge takes; the side is what follows the last colon.
       def winners(held)
@@ -46,7 +62,7 @@ module Hecks
       def raw_era(domain, lineage, ordinal)
         present = lineage.db.exec("SELECT to_regclass('hecks_eras') AS present")[0]["present"]
         (present && lineage.raw_era(ordinal)) or
-          raise Runtime::NotFound, "#{domain.bluebook.name} holds no era #{ordinal}"
+          raise Runtime::NotFound, "#{domain.domain_name} holds no era #{ordinal}"
       end
     end
   end

data/lib/hecks/hecks/adapters/landed_work.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/landed_work"
+
+Hecks.adapter "LandedWork" do
+  port "LandedWork"
+end

data/lib/hecks/hecks/adapters/landed_work.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "started_work"
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The `LandedWork` port's adapter for `Tickets::Work`: finds the open step a landed branch was
+    # cut for, so the bluebook can finish it.
+    #
+    # A branch names its step by the whole branch name, else by the name without a leading `qa/`
+    # (QA's branches carry that prefix, the steps they close do not). Only a `planned` or `started`
+    # step is found; a branch with no step, or one already done or dropped, is refused by name and
+    # the bluebook reacts to neither. It writes nothing.
+    class LandedWork
+      # The prefix QA puts on a branch whose step carries the bare name.
+      QA_PREFIX = "qa/"
+
+      # @param registry [Runtime::Registry, nil] the booted registry whose Work rows are read
+      # @param aggregate [Object, nil] unused
+      def initialize(registry: nil, aggregate: nil)
+        @registry = registry
+      end
+
+      # @param held [Hash] the landing's `branch`
+      # @return [Hash{Symbol => Hash}] `branch:` the key of the open step the branch names
+      # @raise [ConsoleCapture::Failure] when no open step is named by the branch
+      def find_landed_work(**held)
+        branch = plain(held[:branch]).to_s
+        found = (candidates(branch) & open_keys).first
+        raise ConsoleCapture::Failure, "no open step is named #{branch}" unless found
+
+        { branch: { value: found } }
+      end
+
+      private
+
+      def candidates(branch) = [branch, branch.delete_prefix(QA_PREFIX)].reject(&:empty?).uniq
+
+      def open_keys
+        aggregate = StartedWork.work_aggregate(@registry)
+        return [] unless aggregate
+
+        records = @registry.repository("Tickets", aggregate).all
+        records.select { |row| %w[planned started].include?(StartedWork.value(row, :status)) }
+               .map { |row| StartedWork.value(row, :work).to_s }
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/ledger/chain.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Hecks
+  module Adapters
+    class Ledger
+      # The hash chain over a journal's entries: each digest takes the digest before it, so
+      # changing, dropping or reordering an entry changes every digest after it.
+      module Chain
+        # The digest a chain starts from: sixty-four zeros.
+        GENESIS = ("0" * 64).freeze
+
+        module_function
+
+        # The digest after one entry.
+        #
+        # Every field is length-prefixed, so no two entries pack to the same bytes.
+        #
+        # @param previous [String] the digest before this entry
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose state codec encodes the entry
+        # @param entry [Ports::Persistence::Entry] the journal entry
+        # @return [String] the next digest, lowercase hexadecimal
+        def step(previous, aggregate, entry)
+          hasher = Digest::SHA256.new
+          hasher << previous
+          fields(aggregate, entry).each do |field|
+            hasher << [field.bytesize].pack("Q>")
+            hasher << field
+          end
+          hasher.hexdigest
+        end
+
+        # The digest after a run of entries.
+        #
+        # @param seed [String] the digest before the first entry
+        # @param aggregate [Bluebook::Aggregate] the aggregate the entries belong to
+        # @param entries [Array<Ports::Persistence::Entry>] the entries, in append order
+        # @return [String] the last digest, or `seed` when there are none
+        def fold(seed, aggregate, entries)
+          entries.reduce(seed) { |digest, entry| step(digest, aggregate, entry) }
+        end
+
+        # One digest for several journals' sealed points, independent of their order.
+        #
+        # @param points [Array<Hash>] each with `name:`, `through:` and the digest under `key`
+        # @param key [Symbol] which digest of each point to take: `:head` or `:previous`
+        # @return [String] lowercase hexadecimal
+        def summary(points, key)
+          lines = points.sort_by { |point| point[:name] }.map { |point| "#{point[:name]}:#{point[:through]}:#{point[key]}" }
+          Digest::SHA256.hexdigest(lines.join("\n"))
+        end
+
+        # What an entry contributes to its digest, as text.
+        def fields(aggregate, entry)
+          state = entry.state && Ports::Persistence::StateCodec.encode(aggregate, entry.state)
+          [entry.operation, entry.id.to_s, JSON.generate(state), JSON.generate(entry.mirrors)]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/ledger/journal.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "chain"
+
+module Hecks
+  module Adapters
+    class Ledger
+      # One chained journal of a booted domain: the persistence adapter that holds it, and the seals
+      # kept beside it.
+      #
+      # An adapter's journal is chained when it can keep seals (`ledger_anchors`,
+      # `record_ledger_anchor`) beside the entries it appends. A sequenced journal (Postgres,
+      # Sqlite) seals up to its projection checkpoint, the point compaction deletes through, and
+      # counts a seal by sequence; a journal with no sequence (Heki) seals everything it holds
+      # and counts entries.
+      class Journal
+        # The seal before the first: nothing covered, the genesis digest.
+        START = { through: 0, head: Chain::GENESIS }.freeze
+
+        # @return [String] the aggregate's storage name, as the journal is named
+        attr_reader :name
+
+        # @param aggregate [Bluebook::Aggregate] the aggregate the journal belongs to
+        # @param adapter [Object] the persistence adapter holding its entries
+        # @return [Journal, nil] the chained journal, or nil when the adapter keeps no seals
+        def self.of(aggregate, adapter)
+          return unless %i[ledger_anchors record_ledger_anchor entries].all? { |method| adapter.respond_to?(method) }
+
+          new(aggregate, adapter)
+        end
+
+        # @param aggregate [Bluebook::Aggregate] the aggregate the journal belongs to
+        # @param adapter [Object] a persistence adapter that keeps seals
+        def initialize(aggregate, adapter)
+          @name = aggregate.storage_name
+          @aggregate = aggregate
+          @adapter = adapter
+        end
+
+        # @return [Boolean] whether any seal is kept beside the journal
+        def sealed? = !@adapter.ledger_anchors.empty?
+
+        # Seals the journal at its end, unless nothing was appended since its last seal.
+        #
+        # @return [Hash, nil] `name:`, `through:`, `head:` and `previous:` of the seal the journal
+        #   now stands at; nil when it was never sealed and holds nothing
+        def seal
+          last = @adapter.ledger_anchors.last
+          base = last || START
+          fresh = unsealed(base)
+          return last && { name: @name }.merge(last) if fresh.empty?
+
+          record(base, fresh)
+        end
+
+        # Compares each seal with the journal and with the seal before it.
+        #
+        # @return [Hash] `seals:` how many seals are held, `entries:` how many were re-walked
+        # @raise [Runtime::WiringError] on the first seal that does not follow the one before it,
+        #   or whose head the journal does not reproduce
+        def verify
+          held = @adapter.ledger_anchors
+          before = START
+          walked = held.sum do |anchor|
+            refuse(anchor, "does not follow the seal before it") unless anchor[:previous] == before[:head]
+            count = rewalk(anchor, before)
+            before = anchor
+            count
+          end
+          { seals: held.size, entries: walked }
+        end
+
+        private
+
+        def record(base, fresh)
+          through = fresh.last.sequence || (base[:through] + fresh.size)
+          head = Chain.fold(base[:head], @aggregate, fresh)
+          @adapter.record_ledger_anchor(through: through, head: head, previous: base[:head])
+          { name: @name, through: through, head: head, previous: base[:head] }
+        end
+
+        # The entries appended since a seal, in order.
+        def unsealed(base)
+          return @adapter.entries unless @adapter.respond_to?(:entries_since)
+
+          @adapter.entries_since(base[:through]).select { |entry| entry.sequence <= @adapter.checkpoint }
+        end
+
+        # Recomputes one seal's head from the journal, when its entries are still held.
+        def rewalk(anchor, before)
+          return 0 unless @adapter.respond_to?(:entries_since) && @adapter.respond_to?(:compacted_through)
+          return 0 if @adapter.compacted_through >= anchor[:through]
+
+          held = @adapter.entries_since(before[:through]).select { |entry| entry.sequence <= anchor[:through] }
+          refuse(anchor, "no longer matches the journal") unless Chain.fold(anchor[:previous], @aggregate, held) == anchor[:head]
+          held.size
+        end
+
+        def refuse(anchor, reason)
+          raise Runtime::WiringError, "#{@name}: the seal through #{anchor[:through]} #{reason}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/ledger.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/ledger"
+
+Hecks.adapter "Ledger" do
+  port "Ledger"
+end

data/lib/hecks/hecks/adapters/ledger.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "ledger/chain"
+require_relative "ledger/journal"
+
+module Hecks
+  module Adapters
+    # The `Ledger` port's adapter: seals the hash chain of a domain's append-only journals before
+    # compaction removes rows from them, and walks the chain again to show the journals were not
+    # rewritten.
+    #
+    # Each journal keeps its seals beside it (`ledger_anchors`, `record_ledger_anchor`), so a
+    # sealed head can be compared with the journal it protects and a compaction cannot take the
+    # evidence of what it removed along with it. A journal an adapter does not chain (Memory, the
+    # era journal, which the database already protects) is left out.
+    #
+    # Arguments arrive materialized, so a value object is `{ value: x }`.
+    class Ledger
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Seals every chained journal of a domain at its present end.
+      #
+      # @param held [Hash] the `Era` record of a compaction: `domain`
+      # @return [Hash{Symbol => Hash}] `domain:` as asked, `through:` the entries sealed in all,
+      #   `head:` one digest for the journals' sealed heads and `previous:` the same for the seals
+      #   before them
+      # @raise [Runtime::NotFound] if the domain directory does not exist
+      # @raise [Runtime::WiringError] if the domain has no chained journal with entries
+      def capture(**held)
+        domain = plain(held[:domain])
+        points = journals(domain).filter_map(&:seal)
+        raise Runtime::WiringError, "no journal entries to seal" if points.empty?
+
+        {
+          domain:   { value: domain },
+          through:  { value: points.sum { |point| point[:through] } },
+          head:     { value: Chain.summary(points, :head) },
+          previous: { value: Chain.summary(points, :previous) }
+        }
+      end
+
+      # Walks every chained journal from its first seal and compares each seal with the journal.
+      #
+      # @param held [Hash] the `Audit` record: `domain`
+      # @return [Hash{Symbol => Hash}] `checked:` the seals and entries compared, `report:` what
+      #   was found
+      # @raise [Runtime::NotFound] if the domain directory does not exist
+      # @raise [Runtime::WiringError] if nothing is sealed, or a seal does not match its journal
+      def walk(**held)
+        sealed = journals(plain(held[:domain])).select(&:sealed?)
+        raise Runtime::WiringError, "nothing is sealed yet: the chain cannot be shown intact" if sealed.empty?
+
+        counts = sealed.map(&:verify)
+        report(sealed.size, counts.sum { |count| count[:seals] }, counts.sum { |count| count[:entries] })
+      end
+
+      private
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+
+      def report(journals, seals, entries)
+        text = "#{journals} journal#{"s" unless journals == 1}: #{seals} seals held, #{entries} entries re-walked"
+        { checked: { value: seals + entries }, report: { value: text } }
+      end
+
+      def journals(path)
+        raise Runtime::NotFound, "no such domain #{path.inspect}" unless Dir.exist?(path.to_s)
+
+        registry = Hecks.boot(File.expand_path(path), install_driving: false).registry
+        registry.bluebooks.flat_map do |domain_name, bluebook|
+          bluebook.aggregates.filter_map { |aggregate| journal(registry, domain_name, aggregate) }
+        end
+      end
+
+      def journal(registry, domain_name, aggregate)
+        repository = registry.repository(domain_name, aggregate)
+        return unless repository.is_a?(Ports::Persistence::AppendOnly)
+
+        Journal.of(aggregate, repository.adapter)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/local_files.rb

@@ -2,8 +2,9 @@
 
 require "fileutils"
 require_relative "console_capture"
-require "hecks/cli/project_cli"
-require "hecks/cli/domain_stub"
+require_relative "rails_app_files"
+require "hecks/tools/project_cli"
+require "hecks/tools/domain_stub"
 
 module Hecks
   module Adapters
@@ -20,7 +21,7 @@ module Hecks
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
       # Writes a command-line launcher beside each domain of the current directory, or beside the
-      # named ones, through `Hecks::CLI::ProjectCli`. A launcher is a generated file that only
+      # named ones, through `Hecks::Tools::ProjectCli`. A launcher is a generated file that only
       # points at its domain, so an existing one is replaced and nothing else is touched.
       #
       # @param held [Hash] the `Launch` record: `domains` (comma separated paths under the current
@@ -28,9 +29,9 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `output:` one line per launcher written
       # @raise [ConsoleCapture::Failure] when no launcher was written
       def write(**held)
-        domains = plain(held[:domains]).to_s.split(",").map(&:strip).reject(&:empty?)
+        domains = Text.comma_list(plain(held[:domains]))
         text = ConsoleCapture.answer do
-          CLI::ProjectCli.call(domains, program: "hecks project_cli", root: Dir.pwd, remove_stale_bin: false)
+          Tools::ProjectCli.call(domains, program: "hecks project_cli", root: Dir.pwd, remove_stale_bin: false)
         end
         unless text.include?("->")
           reason = text.strip.empty? ? "no domain found" : text.strip
@@ -60,12 +61,25 @@ module Hecks
         { output: { value: report } }
       end
 
+      # Writes the controllers and routes a Rails app drives its domain through,
+      # leaving every file the app already has alone.
+      #
+      # @param held [Hash] the `Launch` record: optionally `dir`, the app's directory (the current
+      #   one when absent)
+      # @return [Hash{Symbol => Hash}] `output:` one line per file, written or kept
+      # @raise [ConsoleCapture::Failure] when the app has no `bluebook/` or it declares no bluebook
+      def write_rails(**held)
+        report = RailsAppFiles.new(File.expand_path(plain(held[:dir]) || ".", Dir.pwd)).call
+        puts report
+        { output: { value: report } }
+      end
+
       private
 
       # The directory the stub is written into: the named one, or the snake-cased name under the
       # current directory.
       def stub_target(held)
-        File.expand_path(plain(held[:dir]) || CLI::DomainStub.directory(plain(held[:name])), Dir.pwd)
+        File.expand_path(plain(held[:dir]) || Tools::DomainStub.directory(plain(held[:name])), Dir.pwd)
       end
 
       # Warns that a service written inside the hecks clone is not one to deploy from there.
@@ -87,7 +101,7 @@ module Hecks
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
 
       def stub_files(name, adapter)
-        CLI::DomainStub.files(name: name, adapter: adapter)
+        Tools::DomainStub.files(name: name, adapter: adapter)
       rescue ArgumentError => e
         raise ConsoleCapture::Failure, e.message
       end

data/lib/hecks/hecks/adapters/pg_admin.rb

@@ -131,12 +131,18 @@ module Hecks
       def configured_databases
         named = CONFIGURED_DATABASES.filter_map { |variable| ENV.fetch(variable, nil) }
         url = ENV.fetch("DATABASE_URL", nil)
-        named << URI.parse(url).path.to_s.delete_prefix("/") if url && !url.empty?
+        named << database_name(url) if url && !url.empty?
         named.reject(&:empty?)
       rescue URI::InvalidURIError
         named
       end
 
+      # The database a `postgres://` URL names: its path, without the leading slash.
+      def database_name(url)
+        path = URI.parse(url).path
+        path.to_s.delete_prefix("/")
+      end
+
       def named(held)
         database = plain(held[:database])
         raise ConsoleCapture::Failure, "no database named" if database.to_s.empty?

data/lib/hecks/hecks/adapters/process_pool.rb

@@ -43,7 +43,7 @@ module Hecks
 
       # The flags of a sweep, and the fields of the record that fill them.
       SWEEP_FLAGS = { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers,
-                      "--adapter" => :adapter }.freeze
+                      "--adapter" => :adapter, "--shard" => :shard, "--list-shards" => :list_shards }.freeze
 
       class << self
         # @return [#call, nil] runs a child given `(command, env, chdir)` and answers a `Finished`;
@@ -60,7 +60,8 @@ module Hecks
 
       # Runs a fuzz sweep over one domain, or over every domain of the checkout when none is named.
       #
-      # @param held [Hash] the `Fuzzing` record: `domain`, `seeds`, `steps`, `workers`, `adapter`
+      # @param held [Hash] the `Fuzzing` record: `domain`, `seeds`, `steps`, `workers`, `adapter`,
+      #   `shard` and `list_shards`
       # @return [Hash{Symbol => Hash}] `report:` what the sweep printed
       # @raise [ConsoleCapture::Failure] when the sweep found something, or could not run
       def sweep(**held)

data/lib/hecks/hecks/adapters/push_size.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    # How big a push is, against the QualityControl world's `push_nudge` setting: `commits:` and
+    # `hours:` for when a push is due, and `urgent_commits:` for when it is urgent. It only says so
+    # in a line; a push of any size is never refused.
+    module PushSize
+      # The world verb that carries the thresholds.
+      VERB = "push_nudge"
+
+      # The thresholds when the world declares none.
+      DEFAULTS = { commits: 15, hours: 6, urgent_commits: 40 }.freeze
+
+      # The word a Work row's title opens with when the push is past `urgent_commits`.
+      URGENT = "URGENT"
+
+      module_function
+
+      # @param registry [Runtime::Registry, nil]
+      # @return [Hash{Symbol => Integer, Float}] `commits:`, `hours:` and `urgent_commits:`
+      def thresholds(registry)
+        declared = registry&.world("QualityControl")&.for_verb(VERB) || {}
+        merged = DEFAULTS.merge(declared.slice(*DEFAULTS.keys))
+        { commits: Integer(merged[:commits]), hours: Float(merged[:hours]),
+          urgent_commits: Integer(merged[:urgent_commits]) }
+      end
+
+      # @param ahead [Integer] the unpushed commits
+      # @param limits [Hash] see {thresholds}
+      # @return [Symbol] `:urgent`, `:over` or `:within`
+      def size_class(ahead, limits)
+        return :urgent if ahead > limits[:urgent_commits]
+
+        ahead > limits[:commits] ? :over : :within
+      end
+
+      # @return [String] the sentence past the threshold, "" within it
+      def sentence(ahead, limits)
+        kind = size_class(ahead, limits)
+        return "" if kind == :within
+
+        "#{"#{URGENT} " if kind == :urgent}PUSH NOW: #{ahead} commits is over the #{limits[:commits]} you set " \
+          "(urgent at #{limits[:urgent_commits]})"
+      end
+
+      # @return [String] the `push-due` Work row's title, naming the size class past the threshold
+      def title(base, ahead, limits)
+        case size_class(ahead, limits)
+        when :urgent then "#{URGENT}: #{base}, #{ahead} commits"
+        when :over then "#{base}, #{ahead} commits"
+        else base
+        end
+      end
+    end
+  end
+end